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 — 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 — the layer must match your actual colliders, not the NavMesh surface.

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 — the visual mesh must match that axis.

No agents appear when I press Play

• Confirm the spawner has at least one archetype assigned and Count > 0.
• Confirm the archetype has a prefab assigned.
• Confirm SwarmManager is active and initialized in the scene.

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. Enable Show Stats Overlay on SwarmManager to identify whether the bottleneck is simulation or rendering.
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–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 nearly doubles its CPU cost for no visible gain at these crowd sizes.
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 — apply 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.

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.

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 — 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 — ask on Discord or email us. If it's a bug, that page lists what to include so we can reproduce it quickly.