StimuliGrid

Remarks

The first of doc 37 § D15's three bounds. Sight is O(listeners × sources) and the schedule is the whole design: five hundred listeners against five hundred sources is a quarter of a million radius tests a pass, and the numbers a game ships are larger than that in both directions at once.

A uniform grid rather than a tree, and rebuilt rather than updated. Every source moves every frame — they are characters — so the incremental update a tree needs to be worth its structure is the case that never happens. Rebuilding is one pass over an array that is already in hand, and it costs a bucket write per source.

⚠ Two-dimensional, over X and Z. A level is mostly a floor: cells over the vertical axis as well would triple the number of cells a query walks — a 25-metre radius spans three cells in Y that almost always hold the same one occupant — for a level where every agent is within a few metres of the same height. Height still counts, because the distance test below is in three dimensions; what a tall level costs is a longer chain in one cell, not a wrong answer. Crowd systems make the same trade and for the same reason.

⚠ Not the physics broad phase, and that is a deliberate difference from what doc 37 § D15 says. A stimuli source is not necessarily a body: a noise, a security camera, a scripted marker and a corpse are all perceivable and none of them has a collider. Querying Jolt would find bodies, which then have to be mapped back to entities and filtered down to the ones that are actually sources — a broad phase over the wrong set, whose cost is the level's collision geometry rather than the handful of things worth looking for. The physics world is still where the occlusion trace goes, which is the expensive half.

Fields and properties (3)

• public int Count

  How many sources are in it.

• public float CellSize

  How wide a cell is, in metres.

• public int OccupiedCells

  How many cells have anything in them.

Methods (3)

• public void Build(ReadOnlySpan<Vector3> positions, float cellSize)

  Puts a set of positions in.

• public int Query(Vector3 centre, float radius, List<int> results, out int cells)

  Everything within a radius of a point.

• public void Clear()

  Empties it.

Used by (2)

• PerceptionSystemVixen.Ai.Perception
• StimuliGridTestsVixen.Ai.Perception.Tests