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 — 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.

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 instanced rendering options.
  3. If simulation is the bottleneck, lower the agent count or simplify the active behavior profile.

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. Enable Use Instanced Rendering on the archetype (requires a non-skinned mesh).
  3. Use a single material per agent (no multi-material mesh).
  4. Keep the mesh low-poly.
  5. 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 the Agent Debugger (Tools > Massive Swarm System > Agent Debugger) 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 Agent Debugger.

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 Radius Scale in SwarmSettings is above 0 — a value of 0 disables the Personal Space pass entirely.

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

This is expected behavior

The Importance LOD system intentionally reduces update frequency for distant (Reduced and Cheap tier) agents. At those distances the visual difference is negligible — this is by design to keep large swarms affordable.

To extend the full-quality range: raise Reduced Quality Start Distance and Cheap Quality Start Distance in SwarmSettings → Importance LOD. Be aware this increases simulation cost.

Agents do not navigate around walls

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

  1. In SwarmSettings, 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 ignore the close-range queue and pile in

Close-Range Pressure is disabled, or agents are not reaching the engage radius.

  1. In the behavior profile, confirm Use Close-Range Pressure is enabled.
  2. Raise Start Pressing Radius so agents enter the pressure zone before they stop.
  3. Confirm Strike Distance and Queue Radius are configured to match your intent.