Spatial Query System

Project Overview

The Spatial Query System is an editor-integrated Unity package that allows AI agents to select optimal navigation targets based on a stack of evaluators. It supports real-time scoring, customizable debug visualization, and runs seamlessly in edit mode.

Why I Built It

I read an article about spatial queries and liked the idea and how simple it is on paper, but I never gave it much thought since I didn't need it.

Then, in Tank Lore, I needed a system that places enemies dynamically based on their combat style, the player's position and the room's layout. I came up with criteria for choosing a spot: every room tile is scored by its distance from the player, walls and other enemies, and by whether it's visible to the player. Halfway through, I had a déjà vu feeling about the structure I was building, looked it up, and found the same article. I followed its structure, expanded it to fit the game, and it has worked well ever since.

Core Framework

A flexible system for sampling points via generators and scoring them with evaluators. Designed to be modular and extensible, supporting custom generators, evaluators, and subjects without additional setup.

Edit-Mode Support

Runs in edit mode for real-time visualization and tuning. Debug views help developers see scoring in action without entering play mode.

Customizable Debugger

Fully editor-configurable debugging display for point sampling and evaluator scoring. Tailor visualization to project needs.

Built-in Generators

Includes Grid, Circular Grid, Ring, and Cone generators with configurable parameters. Add custom generators that auto-register in the system.

Evaluators

Five built-in evaluators: Distance, Navmesh Distance, Direction, Line of Sight, and Overlap. Each offers weight, filtering, and priority settings. Custom evaluators integrate seamlessly.

Scoring Weights & Filtering

Control evaluator influence via weights, filter unwanted points early, and define priorities to optimize performance.

Sample Point Reports

Detailed scoring reports available per sample point GameObject for in-depth analysis of decision-making.

Custom Components

Generate new generators, evaluators, and evaluator subjects from Unity menus using provided templates. Learn more on the GitHub page.

Impact

With the system in place, we used the system for a big variety of purposes like finding points for the enemies to move to, spots for props to place on a level, enemy spawn points (what instigated this), drop points, where to spawn summons if any, and many many other systems in the game. It was flexible enough that everyone in the team used it, and adding more generators and evaluators was effortless.