Agent Debugger

The Agent Debugger is an editor window that shows the live steering state of one agent at a time during Play mode. Use it when something looks wrong on a specific enemy — wrong movement, unexpected facing, a behavior with no visible effect — and you need to trace the cause back to a specific steering contribution or configuration value.

Open the debugger when...

• An agent runs in the wrong direction and you can't tell which behavior is responsible.
• Dormancy seems to activate or not activate unexpectedly.
• A behavior profile change has no visible effect on a specific agent.
• Surface Flow routes an agent into a wall or off the grid.

Menu path: Tools > Massive Swarm System > Agent Debugger

The window docks anywhere in the editor layout. Its data only populates in Play mode.

The Agent Debugger in Play mode. The Steering Contribution Breakdown panel (left) lists each behavior's color, magnitude, and direction; with Gizmos on, those same contributions are drawn as colored vectors from the selected agent in the Scene view.

Selecting an agent

Three ways to point the debugger at an agent:

1. Click an agent visual in the Scene view with Follow Selection enabled (the default). The window automatically updates to the selected agent's manager and index.
2. Click a SwarmManager GameObject in the Hierarchy. The window keeps the current index but switches to that manager.
3. Set the index manually using the Agent Index slider or field in the Runtime Selection panel.

The toolbar also has two explicit buttons: Use Active Manager picks the first active SwarmManager in the scene; Use Selected Agent reads the manager and index from whatever is currently selected in the Scene or Hierarchy view.

Agent Index is the agent's slot in the simulation arrays — it stays stable until the agent is despawned and its slot is reused.

Toolbar controls

Control	What it does
Use Active Manager	Assigns the first active SwarmManager found in the scene.
Use Selected Agent	Reads the manager and index from the currently selected agent visual.
Follow Selection	When on, any scene or hierarchy selection that contains an agent automatically updates the debugger target.
Gizmos	When on, steering contribution vectors are drawn as colored lines in the Scene view for the selected agent.

Runtime Selection panel

This panel sits below the toolbar and is always visible.

Field	What it shows
Manager	The SwarmManager being inspected. Drag a different manager here to switch.
Agent Index	The simulation slot index (0 to active count − 1). A slider appears when agents are active.
Gizmo Scale	Scales the length of the Scene-view steering vectors. Range 0.25 to 3.
Behavior Isolation	Switches the manager's behavior isolation mode. See Behavior Isolation Mode below.

A yellow warning appears when isolation is active — the simulation is no longer running all behaviors, so results shown are diagnostic only.

Debug Interpretation panel

Shows high-level agent intent for the selected simulation step.

Field	What it means
Agent Index	The simulation slot index, confirmed from the snapshot.
Target Index	Which registered SwarmTarget this agent is currently pursuing. Shows None if no target is assigned.
Behavior Profile	The SwarmBehaviorProfile asset driving this agent. Shows Built-in Defaults if no profile is assigned.
Movement Profile	The SwarmMovementProfile asset driving speed and acceleration for this agent.
Current High-Level State	A readable summary of what the agent is trying to do. See High-level states below.
Current Goal Facing Source	Which behavior is currently supplying the goal facing direction — the direction the agent wants to face before blending.
Orientation Mode	The orientation mode from the agent's archetype (e.g. Face Movement Direction, Face Target).
Distance To Target Center	Planar world-unit distance from this agent to its target's position. N/A if no target.
Distance To Desired Target Position	Distance to the agent's assigned surround slot or approach point, when one is computed. N/A if not applicable.
Target Awareness	A 0–1 value. Low values mean the agent is far from or has recently lost sight of its target; full surround behavior only runs at high awareness.

A note appears in this panel when both Approach And Surround and Close-Range Pressure are contributing simultaneously — facing may stay goal-biased while movement includes queueing or spacing corrections.

High-level states

State	Meaning
Idle / No Clear Goal	The agent has no target or very low awareness.
Approaching Surround Slot	Moving toward an assigned surround position around the target.
Pressing Target	In the Close-Range Pressure zone and actively pressing toward the target.
Queueing Around Target	In the Close-Range Pressure zone but holding position, waiting for a press window.
Lost Target Following Crowd	Target is out of sight; using group-pull / lost-target recovery to stay with the swarm.

Facing Vectors panel

Shows the four direction values the simulation tracks for orientation blending.

Field	What it means
Goal Facing Direction	The normalized direction supplied by the highest-priority behavior for facing.
Movement Direction	The direction the agent is currently moving — used as a facing fallback when no behavior claims priority.
Desired Facing Direction	The blended target direction before the movement profile's turn-speed clamping is applied.
Current Forward	The agent's actual forward direction this step, after turn-speed clamping.

All vectors show as (x, z) normalized pairs. A dash (-) means the vector is near-zero.

Steering Contribution Breakdown panel

Each row shows one behavior's contribution to the final steering direction. Each row has a color swatch, a magnitude, and a normalized direction.

Behavior	Color
Approach And Surround	Blue
Close-Range Pressure	Red
Personal Space	Orange
Idle Motion	Light grey
Retreat	Pink
Group Pull	Light blue
Predictive Catch-Up	Green
Orbit Style	Cyan
Final Steering	Yellow

Final Steering is the accumulated result after all weighted contributions are combined. When a behavior's magnitude reads 0.00, it is either disabled, not active this step (due to LOD tier), or its conditions are not met.

When Gizmos is on in the toolbar, these same contributions are drawn as colored vectors in the Scene view from the agent's position.

Dormancy panel

Shows the dormancy system state for the selected agent. Only relevant when Enable Dormancy is on in SwarmSettings.

Field	What it means
Is Dormant	Whether the agent is currently sleeping (no steering computation).
Window Frames	Frames spent in the stuck-detection window, and the required frame count before sleep triggers.
Smoothed Steering	The low-pass filtered steering magnitude used to decide if the agent is trying to move.
Above Min Desired (>0.1)	Whether the smoothed steering magnitude is high enough to even evaluate dormancy. Agents that aren't trying to move skip the dormancy check entirely.
Position Delta This Step	How far the agent moved in the last simulation step.
Distance From Anchor	Distance from the position where the stuck window started. When dormant, waking requires this distance to exceed the threshold.
Distance Threshold	The world-unit distance required to trigger either sleep (too little movement) or wake (enough displacement).
Candidate This Step	A summary of why this agent is or is not a dormancy candidate this step.

When dormant, additional fields appear: the frozen desired direction, wake lookahead distance, wake cone half-angle, required blocker count to stay asleep, whether a target move triggers an immediate wake, the random-wake probe interval, and the nearby-motion-wake radius and minimum speed.

Surface Flow panel

Shows the flow field state for the selected agent. Only populates when Enable Surface Flow Navigation is on in SwarmSettings.

Field	What it means
Resolved Target Slot	Which flow goal field is bound to this agent's current target.
Goal Cell Index	The grid cell index the flow field routes toward (the target's cell).
Reachable / Unreachable	Grid-wide count of reachable vs. unreachable cells in the current bake.
Bake Data Version	Increments each time the field is rebaked. Useful for confirming a bake has completed.
Grid Size	Grid dimensions in cells and the world-unit size per cell.
Cell Coords	The (x, z) grid coordinates and flat cell index for the agent's current position.
Cell Status	One of: Flow (routed), Goal cell, Unreachable (no path from goal), Unwalkable (no surface sample), Off Grid.
Cell Surface Y	The baked surface height at this cell, plus how far above it the agent currently sits.
Cell Flow Direction	The compass direction the flow field sends agents from this cell toward the goal. A dash means no flow (goal cell or blocked).
Neighbour Connections	A 3×3 compass grid showing which of the eight adjacent cell connections are open (green) or blocked (red).

If the agent is off the grid, the panel shows a warning and the Cell Status only. If the field has no bake yet, a warning indicates the bake may still be in flight.

Behavior Isolation Mode

Behavior isolation is an editor-only debug tool. It overrides the simulation on the selected manager so only a subset of behaviors runs. Use it when a behavior change has no visible effect and you want to confirm it is actually contributing, or to identify which behavior is causing an unexpected result.

Isolation changes live simulation

While isolation is active, the whole swarm on that manager runs with reduced behaviors — not just the selected agent. Results are not representative of real gameplay. Always reset to All Behaviors before testing performance or tuning values.

The Behavior Isolation dropdown in the Runtime Selection panel sets the mode. Options:

Mode	What runs
All Behaviors	Normal blended simulation. This is the default.
Approach And Surround Only	Only the approach-and-surround pass runs. All others are suppressed.
Close-Range Pressure Only	Only the close-range pressure pass runs.
Personal Space Only	Only the personal-space separation pass runs.
Idle Motion Only	Only the idle motion pass runs.
Retreat Only	Only the retreat pass runs.
Group Pull Only	Only the group pull pass runs.
Predictive Catch-Up Only	Only the predictive catch-up pass runs.
Orbit Style Only	Only the orbit style pass runs.
Mute Approach And Surround	All behaviors run except approach and surround.
Mute Close-Range Pressure	All behaviors run except close-range pressure.
Mute Personal Space	All behaviors run except personal space.

To return to normal blending: set the dropdown back to All Behaviors.

Isolation mode is stored on the SwarmManager component and supports Undo. It is not serialized to any behavior profile asset — it does not edit your settings.

Related pages

• Behaviors — behavior descriptions and the runtime blending model.
• Performance — Stats Overlay and step timing tools for aggregate swarm metrics.
• Troubleshooting — common setup and behavior problems with fixes.
• Navigation — Surface Flow Field setup and bake configuration.