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.

Five ScriptableObjects

All configuration lives in five asset types:

Asset	What it controls	Assigned to
SwarmSettings	Global parameters: agent capacity, grounding, body blocking, LOD, dormancy. One per scene.	The SwarmManager component
SwarmAgentArchetype	Visual prefab, agent radius, push resistance, and which profiles this enemy type uses.	The spawner or director
SwarmBehaviorProfile	Which steering behaviors are active and how strongly each one contributes.	The archetype
SwarmMovementProfile	Max speed, acceleration, braking, turn rate, and orientation blend.	The archetype
SwarmAttackProfile	Melee reach, damage, cooldown and windup for agents that attack. Optional.	The archetype

SwarmSettings is global, so the same instance applies to every agent in the scene. Everything else hangs off the archetype, which is what lets two enemy types have different steering, speed and attacks without touching each other.

Importance LOD

Not all agents get the same per-step cost. Every agent falls into one of three tiers:

• Full: all behaviors run every step.
• Reduced: Personal Space runs less frequently and with fewer neighbor samples. Approach & Press steering is recomputed on a throttled interval, and cached results fill the skipped steps.
• Cheap: Personal Space runs even less frequently with a further-reduced sample cap. Approach & Press throttling is more aggressive.

Distance to the target is the main input, but it is not the only one, and the tiers are not three rings on a map. The classifier walks a short ladder in order and takes the first branch that matches:

1. A dormant agent is Cheap, wherever it is standing.
2. An agent inside the near-target band is Full, but only while there is a free slot under Full Quality Agent Cap. Past the cap, the overflow drops to the next rung.
3. An agent the camera is drawing is Reduced, however far from its target it is. So is any agent inside the mid distance band.
4. An agent that was Reduced last step stays Reduced a little past the boundary, so nothing flickers between tiers while it walks the line.
5. Everything else is Cheap.

Then, if the Full cap still has room after that first pass, a second one spends what is left. Any agent that is either in the near band or on camera can be promoted to Full, with near-band agents winning the ties. So a small swarm can run entirely at Full while a thousand-agent one exhausts the cap on the near band alone and nothing gets promoted.

Distance runs one way, camera visibility the other. Only one cell of the six depends on the camera at all: an agent has to be both far from its target and undrawn before it goes Cheap.

The distances and the cap live in SwarmSettings. In Simple mode they sit under Performance; the section actually titled Importance LOD appears once you switch the inspector to Advanced.

Visual fidelity is a separate system and does not follow the importance tier. Shader quality is a straight on/off: any agent being drawn renders at full VAT quality no matter how far the camera is, and an agent that is not drawn renders cheap. Camera distance only changes how often the animation refreshes, in three bands: every visual sync up close, every second sync past Distant Visible Distance, every fourth sync while off screen. This split is why tuning Importance LOD distances changes simulation cost without changing 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, so 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 picks up to Max Active Target Count of them to actively chase (10 by default). Distance from the swarm centroid drives that choice, but two things bend it: a target's Priority scores it as though it were closer, so a priority-2 objective can hold a slot against a nearer priority-1 one, and a target already in the active set gets a stickiness bonus so the set does not churn when two candidates sit near the boundary. 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.

Additive is the word that matters. A behavior never overrides another one, it only adds its own pull, which is why turning a behavior off can change the direction of agents that were never near it. The clamp is also why weights are relative rather than absolute: doubling every weight changes nothing.

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.