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:

No per-agent Update. A single SwarmManager ticks the whole swarm in one FixedUpdate loop, with no per-GameObject scheduling overhead.
Data and visuals are decoupled. Simulation runs on flat arrays in SwarmAgentData; visual GameObjects are pooled and follow data. You can swap prefabs, change materials, or use VAT without touching simulation code.
Importance LOD. Distant agents pay less per step. The tier controls simulation cost — behavior recompute cadence, personal space sampling, body-blocking frequency — not how agents look. Visual quality follows the camera independently (see Visibility LOD).

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:

Frame rate and frame time.
Active agent count.
Tier counts (Full / Reduced / Cheap / Dormant).

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 the Swarm StepSimulation sample; every per-pass marker nests under it with a Swarm prefix (for example Swarm Importance LOD, Swarm Integrate Agents, Swarm Body Blocking). 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.

Fixed timestep and the catch-up spiral¶

Apply Fixed Timestep On Initialize ships on. It pins the swarm to Fixed Timestep (default 0.0333, 30 Hz) and caps Maximum Allowed Timestep so a slow frame cannot snowball: without the cap, one long frame makes Unity run several catch-up simulation steps the next frame, each heavier under load, which drops the frame rate further and queues even more steps. The cap lets in-game time slow down instead. If a swarm collapses to single-digit fps under load, check this toggle first.

Raising the simulation rate (a smaller Fixed Timestep) multiplies every per-step cost. At 1000+ agents, 30 Hz looks the same as 50 Hz and costs noticeably less. See Swarm Settings — Timing & Visuals.

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. Approach & Press steering is recomputed on a throttled interval; cached results fill the skipped steps.
Cheap — distant agents. Personal Space runs even less often. Approach & Press throttling is more aggressive.

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.

Hard Agent Separation — budget before enabling¶

Hard Agent Separation (SwarmSettings → Body Blocking) holds spacing in a crushing crowd, but it is a cost lever, not a saving. Unlike soft Body Blocking, it runs on every awake agent every step with no Importance LOD throttle, so its cost scales with the awake count rather than the visible count. Turn it on only for scenes that visibly pile up, watch the Swarm Body Blocking profiler marker after enabling it, and leave it off elsewhere.

See Swarm Settings — Hard Agent Separation.

Render Smoothing — cheap, on by default¶

Enable Render Smoothing (SwarmSettings → Timing & Visuals) runs a small per-agent filter during the visual sync: about 77 nanoseconds per agent, roughly 0.08 ms per frame at 1000 agents, with no allocations. It runs only for visible, non-dormant agents, so it scales with the on-screen count rather than the total. It is not worth turning off for performance — disable it only if you want raw, unfiltered render positions. The cost is identical at any cutoff value.

See Swarm Settings — Timing & Visuals.

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

Switch to VAT animation instead of SkinnedMeshRenderer + Animator.
Use a single material per agent (no multi-material mesh).
Keep the mesh low-poly.
Disable shadow casting on the agent renderer.
Set Animator Culling Mode to Cull Completely if using SwarmAgentAnimation.

See Animation for the full VAT setup guide, and VAT Render Quality Tiers for choosing the right shader tier for mobile vs. desktop.

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 rate collapses to single digits under load	Confirm Apply Fixed Timestep On Initialize is on; keep Fixed Timestep at `0.0333`.
Frame drops, simulation-bound	Lower Reduced Quality Start Distance and set Full Quality Agent Cap.
Frame drops, render-bound	Switch the archetype to VAT. Use a low-poly single-material mesh.
One-frame spikes when many agents spawn	Lower Max Spawn Per Frame on the director.
Dense crowd thrashes	Enable Dormancy.
Dense crowd interpenetrates despite spacing	Enable Hard Agent Separation — costs more (every awake agent, every step).
Mobile is much slower than desktop	Replace the agent prefab. See the Mobile section above.

Concepts — the architecture that makes the levers work.
Swarm Settings — where Capacity, LOD, Dormancy live.
Animation — VAT, Animator-based animation, mobile prefab checklist.
Troubleshooting — performance issues and fixes.