Skip to content

Troubleshooting

Common first-run issues and how to fix them.

Something missing entirely?

If the swarm is not appearing at all, work through the Getting Started walkthrough first, since it covers the minimum required setup.

Setup issues

Agents fall through the ground

SwarmSettings → Ground Layer Mask does not include the collider layer for your floor.

  1. Open the active SwarmSettings asset.
  2. Set Ground Layer Mask to include the layer your floor and terrain colliders are on.

The grounding system uses physics probes, not NavMesh, so the layer must match your actual colliders, not the NavMesh surface.

Agents sink or pop a moment after stepping onto a ledge

Grounding Execution Mode is set to Batched Deferred. That mode schedules the ground probes on one fixed step and applies the results on the next, so ground height is always one step behind. It buys the lowest main-thread cost, and render interpolation hides it in most scenes, but a sharp height change can show a brief sink or pop.

  1. Open the active SwarmSettings asset.
  2. Under Grounding, set Grounding Execution Mode to Batched. You keep the threaded probe batch and lose the one-step lag, because the results are consumed inside the same step.
  3. If you want the reference behavior, set it to Immediate, which is the shipped default.

All three modes produce the same ground result. Only the timing and the main-thread cost differ, so this is a performance trade rather than a correctness one.

Agents clip into walls

Obstacle Layer Mask is empty or set to the wrong layer.

  1. Open the active SwarmSettings asset.
  2. Set Obstacle Layer Mask to the layer your wall colliders are on.

Keep swarm agent layers out of this mask to avoid self-interference.

A dense crowd squeezes agents through a wall

Obstacle Blocking holds a packed crowd behind a static wall on its own, even at the frame rates a 1000-agent swarm can produce. The push is directional (agents move back toward the side they came from) so a thin wall is contained as well as a thick one. If you still see bodies reach the far side under sustained pressure:

  1. Confirm the wall's layer is in Obstacle Layer Mask and that swarm agent layers are not (see above).
  2. Lower Obstacle Blocking Query Interval toward 1 in SwarmSettings → Obstacle Blocking. The default 2 suits typical crowds; 1 checks every agent every step for the tightest containment, at higher query cost.

Agents face the wrong direction

The prefab's visual mesh is not aligned to local +Z forward.

  1. Open the prefab in Prefab edit mode.
  2. Rotate the visual mesh so it faces local +Z.
  3. Save.

The swarm simulation drives facing from the agent's forward axis, so the visual mesh must match that axis.

No agents appear when I press Play

  • Confirm the spawner has an Agent Archetype assigned and Auto Spawn Count above 0.
  • Confirm the archetype has a prefab assigned.
  • Confirm SwarmManager is active and initialized in the scene.

If spawning stops silently and none of the above explains it, select the SwarmSpawnerDirector in Play mode and read the Last Blocker field on its inspector. It names the reason the most recent spawn attempt was refused:

Last Blocker What it means
None Nothing refused a spawn. Look at the spawner's count and interval instead.
NoManager The director found no SwarmManager.
NoSpawner No spawner is assigned or enabled under the director.
ManagerCapacity The swarm is at Max Agents. Raise it in SwarmSettings, or let agents despawn first.
SourceMaxAlive That spawner hit its own Max Alive cap.
TotalLimitReached The director hit its total spawn limit for the run.
PoseSamplingFailed The spawner could not find a valid spawn pose, most often a spawn volume that does not overlap walkable ground.

SwarmTarget does not register

SwarmTarget searches for a SwarmManager on OnEnable. If the manager is not active when the target enables, the target logs an error and re-attempts on Start.

  1. Confirm SwarmManager is active in the scene.
  2. Confirm Initialize On Awake is on (the default).
  3. If you initialize the manager manually, do so before any SwarmTarget component enables.

Performance issues

Frame rate drops at high agent counts

  1. On SwarmManager, enable Show Stats Overlay and Track Step Timings together. The overlay on its own reports FPS, frame time and agent counts, but its "Fixed" line is only the configured step length, not measured cost. The per-step rows that actually separate simulation from rendering appear only while Track Step Timings is on, and that one ships off.
  2. If rendering is the bottleneck, see Animation for VAT and prefab optimization options.
  3. If simulation is the bottleneck, lower the agent count or simplify the active behavior profile.

Frame rate collapses far below the agent count it should handle

A swarm that runs at 30 fps can drop to 8 to 10 fps once the frame rate dips under load and never recovers. That is the catch-up spiral: when one frame runs long, Unity runs several fixed simulation steps in the next frame to catch up, each step costs more under crowd pressure, the frame runs even longer, and Unity queues still more steps.

  1. Open the active SwarmSettings asset and confirm Apply Fixed Timestep On Initialize is on (it ships on by default). This caps Unity's catch-up window through Maximum Allowed Timestep, so a slow frame lets in-game time slow down instead of snowballing.
  2. Leave Fixed Timestep at 0.0333 (30 Hz) unless you need a higher simulation rate. Stepping the swarm at 50 Hz instead of 30 runs 67% more simulation steps every second, and at these crowd sizes there is nothing visible to show for it.
  3. Keep Maximum Allowed Timestep at or just above Fixed Timestep. See Swarm Settings: Timing & Visuals.

If the simulation itself is the heavy part, not just the spiral, the largest per-step cost in a dense crowd is the physics body and obstacle blocking. Enabling the Surface Flow Field offloads grounding and pathing onto baked grid data instead of per-agent physics probes, which lowers the simulation floor for large swarms. It is off by default and optional; see Navigation and Performance.

Mobile performance is much lower than desktop

The dominant mobile cost is almost always the agent prefab, not the swarm simulation. On a test device at 1000 agents, the simulation cost approximately 10 ms; replacing a SkinnedMeshRenderer agent with a simple capsule raised frame rate from ~16 fps to ~60 fps on the same device.

Mobile fix priorities, in order

  1. Switch to VAT animation instead of SkinnedMeshRenderer + Animator.
  2. Use a single material per agent (no multi-material mesh).
  3. Keep the mesh low-poly.
  4. Disable shadow casting on the agent renderer.

See Animation for the full VAT setup guide.

Behavior issues

Need to pinpoint which behavior is the cause?

Open Swarm Debug (Tools > Massive Swarm System > Swarm Debug) and select an agent. The Steering Contribution Breakdown panel shows the magnitude and direction of every active behavior, and Behavior Isolation mode lets you suppress individual behaviors to identify the culprit. See Swarm Debug.

Agents bunch up into a single point

Personal Space is disabled or weighted too low.

  1. In the active SwarmBehaviorProfile, enable Personal Space and raise Spacing Strength.
  2. Confirm Agent Spacing Scale in SwarmSettings is above 0. A value of 0 disables the Personal Space pass entirely.

Agents overlap or interpenetrate in a dense crowd

Personal Space and soft Body Blocking spread a crowd, but under heavy pressure (hundreds of agents crushing toward one target) soft blocking resolves only part of each overlap per step and can leave bodies interpenetrated.

  1. Confirm Enable Body Blocking is on and Agent Spacing Scale is above 0 in SwarmSettings.
  2. Enable Hard Agent Separation in SwarmSettings → Body Blocking. It resolves awake agents to full minimum spacing every step, so the pack keeps usable spacing under pressure. It costs more than soft blocking. See Swarm Settings: Hard Agent Separation.

A settled crowd stays merged and never spreads back out

Dormancy Body Blocking Interval is 0. Two sleeping agents get no separation from each other between heartbeat ticks, so at 0 there is nothing left to push them apart once a pile has fully fallen asleep. It stays merged at whatever overlap it had when it settled.

  1. Open the active SwarmSettings asset.
  2. Under Dormancy, set Dormancy Body Blocking Interval back to 8 (the default). Lower values mean tighter spacing and more cost.

Heartbeat pushes are bounded per step and each moved sleeper is re-checked against obstacles the same step, so raising this cannot shove sleeping agents through walls. 0 is still a real saving on levels where crowds never settle, which is why it is allowed rather than clamped.

A resting agent is slow to react

Dormant agents do not re-evaluate every step. An agent that went dormant behind a blocked path wakes on whichever rule fires first: its blocker check on the Dormancy Wake Recheck Interval stride, a moving agent inside Dormancy Nearby Wake Radius, or the random probe on Dormancy Random Wake Probe Interval (default 180 steps, spread across agents by seed so the cost never spikes on one step).

If sleepers react too slowly for your game:

  1. Open the active SwarmSettings asset.
  2. Under Dormancy, lower Dormancy Random Wake Probe Interval, or turn on Dormancy Wake On Target Move so target movement past the dormancy distance threshold wakes them at once.
  3. Raise Dormancy Nearby Wake Radius if you want passing agents to wake a resting pack sooner.

Every one of these trades some of dormancy's CPU saving for reaction time. Turning Enable Dormancy off removes the delay entirely, at full simulation cost for resting agents.

Agents never reach their Max Speed

Movement is capped so that no single fixed step carries an agent farther than its own body radius in the plane. It is a continuous-collision safeguard: without it a speed spike or a long frame would move a body through a wall faster than blocking can react.

The cap only bites when Max Speed × fixed timestep exceeds the agent radius, so it shows up with fast agents, small radii, or a coarse timestep.

  1. Raise Agent Radius on the SwarmAgentArchetype if the agent's body is smaller than it looks.
  2. Or lower Fixed Timestep in SwarmSettings so each step moves a shorter distance.

Effective top speed is roughly radius / fixedTimestep. On the shipped defaults, a 0.5 radius and the 0.0333 timestep, that works out to 15 units per second, well above typical swarm speeds. Halve the radius to 0.25 and the ceiling halves with it, to 7.5.

Agents spin or wobble around the target

Turn speed is too high relative to agent speed, or steering response is too loose.

  • Lower Max Turn Speed in SwarmMovementProfile.
  • Or reduce Approach Weight in the behavior profile.
  • For oscillation rather than spin, reduce Steering Response in the movement profile.

Distant agents look frozen or jittery

Animation refresh cadence follows the camera, not the simulation importance tier. An on-screen agent farther than Distant Visible Distance from the camera refreshes on the Distant Visible Animation Refresh stride; an off-screen agent refreshes on the Off-Screen Animation Refresh stride.

To smooth animation on distant but visible agents:

  1. Open the active SwarmSettings asset.
  2. Under Visibility LOD → Animation Refresh, lower Distant Visible Animation Refresh toward 1 (every sync) or raise Distant Visible Distance to widen the band of agents that refresh every sync.

If the agents are off screen and look wrong when they return to view, lower Off-Screen Animation Refresh instead.

Reduced Quality Start Distance and Cheap Quality Start Distance (under Importance LOD) are simulation cost knobs. They do not affect how agents look.

Agents do not navigate around walls

Navigation around obstacles requires the Surface Flow Field, which is off by default.

  1. On SwarmManager, enable Surface Flow Field Navigation.
  2. On SwarmManager, configure grid bounds and set the ground and blocker layers.
  3. Enter Play mode. The field bakes at startup.

For flat levels with simple obstacles, Enable Body Blocking and Enable Obstacle Blocking in SwarmSettings push agents around small geometry without a full flow field. See Navigation for details.

Agents route around a wall that is not there any more

The Surface Flow Field's map geometry is baked, not sampled live. It is read from the bake and never re-cast at runtime, which is what keeps a 1000-agent swarm affordable. So any change to level geometry after the bake leaves the routes describing the old level: agents walk around a deleted wall, or into one you just added.

  1. On SwarmManager, press Bake Now after changing level geometry.
  2. Or enter Play mode, which bakes at startup.

Surface Flow Runtime Rebake (on by default) does not cover this. It rebakes the route to a target as that target moves, using the map that is already baked. It never re-scans colliders, so moving or deleting an obstacle alone will not update the map. Runtime obstacle changes are outside the scope of the baked field in this version.

Walkable cells appear under the player or target

The bake already ignores colliders that belong to a SwarmTarget, so a target sharing the Walkable layer should not leave a walkable patch under itself. If one still shows up, the collider is parented above the SwarmTarget object, so the bake can't tell it apart from the level.

  1. Move the collider onto the SwarmTarget object or a child of it.
  2. Re-bake (Play mode, or the Bake Now button on SwarmManager).

Agents cut straight toward the target instead of following the flow route

Surface Flow Direct Approach Distance is 0, so an agent steers at its target the whole way and never hands travel over to the route. One that sits near its target in a straight line but far along the path (a turret on a ledge reached by a ramp, or a target behind a wall) then pulls across open ground instead of taking the flow.

  1. Open the active SwarmSettings asset.
  2. In the Surface Flow Field navigation group, set Surface Flow Direct Approach Distance to about 8 (the default). It is measured along the route in world units: an agent steers straight at the target once it is within this distance by path, and follows the flow beyond it. 0 turns the hand-off off.
  3. Confirm Surface Flow Quality is Smooth or Eikonal on the SwarmManager. The setting reads the integration-field path data and does nothing on Cardinal.

A sloped or raised route counts as farther by path, so an elevated target holds the route longer than its straight-line distance suggests.

A dense crowd around the target trembles or boils in place

Render Smoothing is off, or the cutoff is too high for a nearly-static pile.

  1. Open the active SwarmSettings asset.
  2. Confirm Enable Render Smoothing is on.
  3. If the crowd still shimmers, lower Render Smoothing Cutoff. A lower value applies stronger smoothing; the trade-off is a little extra visual lag on fast-moving agents.

Fast-moving agents look rubbery or laggy

Render Smoothing cutoff is too low, so the filter cannot keep up with brisk movement.

  1. Open the active SwarmSettings asset.
  2. Raise Render Smoothing Cutoff. Higher values track real motion more tightly and reduce perceived lag.
  3. If the lag persists, turn Enable Render Smoothing off for that swarm.

Still stuck?

Can't find it here?

Head to Help & Support to ask on Discord or email us. If it's a bug, that page lists what to include so we can reproduce it quickly.