Concepts¶
The mental model behind Massive Swarm System. Read this once after Getting Started to understand how every setting connects.
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 arrays inside SwarmAgentData. 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. Adaptive surround slot solving and Close-Range Pressure are skipped by default.
- Cheap — distant agents. Personal Space runs even less frequently with a further-reduced sample cap. Adaptive surround and Close-Range Pressure remain skipped.
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.
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.
Agents are allocated and released from a flat buffer — there is no instantiation after initial pool warmup.
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.