Concepts¶
The mental model behind Massive Swarm System. Read this once after Getting Started to understand how every setting connects.
Looking up a term?
Recurring navigation and spacing terms are defined in one place on the Glossary page.
Manager-Driven Simulation¶
Every agent in the swarm is a data record, not a self-updating GameObject. The SwarmManager owns the simulation loop — it runs once per fixed timestep and processes all agents in a batch. No per-agent Update, FixedUpdate, or LateUpdate ever runs.
Centralized processing eliminates the per-GameObject scheduling overhead that tanks frame rate in traditional crowd setups, which is what makes 1000+ agents affordable.
The Data / Visual Split¶
The simulation tracks agent positions, velocities, and facing vectors in dense parallel arrays owned by SwarmManager. Visual GameObjects are pooled separately by SwarmVisualManager and moved to match the simulation data each frame.
Visuals never drive simulation state. You can change a prefab, swap a material, or adjust the pool without touching behavior code, and the simulation runs with or without renderers.
Four ScriptableObjects¶
All configuration lives in four asset types. Create one of each, assign them to an archetype, and the system picks them up:
| Asset | What it controls |
|---|---|
SwarmSettings |
Global parameters: agent capacity, grounding, body blocking, LOD, dormancy. One per scene. |
SwarmAgentArchetype |
Visual prefab + agent radius + which behavior and movement profiles to use. |
SwarmBehaviorProfile |
Which steering behaviors are active and how strongly each one contributes. |
SwarmMovementProfile |
Max speed, acceleration, braking, turn rate, and orientation blend. |
SwarmSettings is global — the same instance applies to all agents in the scene. The behavior and movement profiles are per-archetype, so different enemy types can have different steering and speed without touching each other.
Importance LOD¶
Not all agents get the same per-step cost. Agents are classified into three tiers based on their planar distance from their current 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 frequently with a further-reduced sample cap. Approach & Press throttling is more aggressive.
The tier boundaries are set in SwarmSettings under Importance LOD. You can also cap how many agents stay at Full tier (Full Quality Agent Cap), which is useful for preventing a budget spike when many agents pile onto one target.
Visual fidelity — VAT shader quality and animation refresh cadence — follows the camera independently, not the importance tier. On-screen agents close to the camera render at full quality and refresh every visual sync regardless of their sim tier; off-screen agents render cheap and refresh on a slower stride. This split is why tuning Importance LOD distances changes simulation cost but not how the crowd looks.
Spawning Flow¶
SwarmSpawnerDirector coordinates one or more SwarmRectSpawner or SwarmRingSpawner components. When spawn conditions trigger, the spawners ask SwarmManager to allocate agent slots. SwarmVisualManager then picks pooled prefabs from the pool and binds them by index.
Simulation state lives in flat, preallocated arrays — agents are allocated and released by index, with no per-agent allocation in the hot loop. The visual pool prewarms a set number of GameObjects per prefab and grows on demand when the live count climbs past that size.
Target System¶
SwarmTarget registers with SwarmManager automatically on OnEnable and unregisters on OnDisable. Any number of targets can be registered; each tick the manager actively chases the registered targets closest to the swarm centroid, up to its Max Active Target Count (10 by default). Each agent tracks one target at a time. Retargeting is done on a per-agent cooldown with hysteresis, so agents do not thrash between targets when two targets are equally close.
Behavior Blending¶
Steering behaviors are additive. Each enabled behavior adds a steering vector contribution. The manager sums all contributions, clamps the result to unit length, smooths it through the steering response in the movement profile, and multiplies by max speed.
Weights are relative, not absolute
A weight of 2 on Approach with 1 on Personal Space means approach contributes twice as strongly before clamping — not that it adds twice as much force in world-space terms. This matters when tuning: raising one behavior's weight reduces the relative influence of all others.