Skip to content

Performance

This page covers the levers for keeping 1000+ agents at frame rate on your target hardware.

Why it scales

Three architectural choices do most of the work:

  1. No per-agent Update. A single SwarmManager ticks the whole swarm in one FixedUpdate loop, with no per-GameObject scheduling overhead.
  2. Data and visuals are decoupled. Simulation runs on flat arrays in SwarmAgentData; visual GameObjects are pooled and follow data. You can render with MeshRenderer, Graphics.DrawMeshInstanced, or VAT without touching simulation code.
  3. Importance LOD. Distant agents pay less per step. The visual difference is negligible at the distances LOD operates; the freed budget is significant.

See Concepts for the full mental model.

How to measure

Before tuning, measure. Two tools help:

Stats Overlay

On SwarmManager (Debug section), turn on Show Stats Overlay. The Game-view HUD shows:

  • Active agent count.
  • Per-step simulation time.
  • Tier counts (Full / Reduced / Cheap).

Enable Show Stats Overlay System Info to also display device, CPU, GPU, memory, and OS — useful when validating across devices.

For finer numbers, switch the inspector to Advanced and turn on Track Step Timings. The overlay then shows the rolling average per step. Disable before shipping.

Unity Profiler

The simulation runs inside the manager's FixedUpdate. Look for SwarmManager.Tick and the per-pass markers under it. If a single behavior dominates, that is your tuning target.

Tuning levers

Capacity

Set Max Agents in SwarmSettings to the highest count you actually spawn. Higher capacity allocates more arrays at startup; it does not cost per-step time, but it does cost memory.

See Swarm Settings — Capacity.

Importance LOD

The single biggest lever. Three tiers, classified by planar distance to target:

  • Full — closest agents. All behaviors run every step.
  • Reduced — mid-range agents. Personal Space runs less frequently and with fewer neighbor samples.
  • Cheap — distant agents. Personal Space runs even less often. Close-Range Pressure and adaptive surround are skipped.

Tune in SwarmSettings → Importance LOD:

  • Lower Reduced Quality Start Distance to shrink the Full-tier band around the target — agents drop to Reduced sooner.
  • Lower Cheap Quality Start Distance to push more agents into the Cheap tier.
  • Set Full Quality Agent Cap to a fixed number so a pile-on never explodes the budget.

See Swarm Settings — Importance LOD for fields, and Behaviors → Importance LOD and behavior cost for the per-behavior table.

Dormancy

Stuck agents in dense crowds can stop steering entirely until space opens up. Enable Dormancy in SwarmSettings for static or slow-moving crowds; the saving compounds with crowd density.

See Swarm Settings — Dormancy.

Behavior weighting — disable, don't zero

Several behaviors cost query budget even when their weight is 0. If a behavior is not contributing, disable it on the profile. Setting the weight to 0 is not the same as disabling.

See Behaviors → Runtime blending.

Spawning bursts

A long pause followed by a burst can produce a one-frame spike. Cap it with Max Spawn Per Frame on the Swarm Spawner Director.

Mobile

The dominant mobile cost is almost always the agent prefab, not the swarm simulation. On a test device at 1000 agents, the simulation cost ~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.
  6. Set Animator Culling Mode to Cull Completely if using SwarmAgentAnimation.

See Animation for the full VAT setup guide.

Surface Flow Field cost

The flow field bake scales with grid cell count, not agent count. Once baked, per-agent runtime cost is a single cell lookup.

Bake throughput is controlled by Surface Flow Concurrent Bakes (low values, 1–2, avoid traffic spikes) and the per-tier sample intervals. See Navigation — Performance guidance for details.

Quick reference

Symptom First lever to pull
Frame drops, simulation-bound Lower Reduced Quality Start Distance and set Full Quality Agent Cap.
Frame drops, render-bound Switch the archetype to VAT or enable instanced rendering.
One-frame spikes when many agents spawn Lower Max Spawn Per Frame on the director.
Dense crowd thrashes Enable Dormancy.
Mobile is much slower than desktop Replace the agent prefab. See the Mobile section above.