Swarm Manager¶

The single component that owns the simulation. Every scene that uses Massive Swarm System has exactly one SwarmManager.

Add it via right-click in Hierarchy → Massive Swarm System → Swarm Manager. This creates the manager GameObject, its sibling agent-visuals container, and auto-assigns a default settings asset.

SwarmManager requires a SwarmVisualManager component on the same GameObject — the context menu setup handles this automatically.

The inspector has a Simple / Advanced mode toggle at the top. Simple hides the target-selection tuning knobs and shows a summary hint instead. Switch to Advanced when you need to change retargeting behavior or when you need the surface-flow fields that are hidden by default.

Core — Setup¶

Start here — most projects only need these three

Settings¶

Visible effect — Which global simulation parameters apply to this manager (capacity, grounding, body blocking, LOD, dormancy).
Gameplay effect — All agents in this scene share one settings asset. Swap assets to give a scene different behavior budgets without touching the manager.
Increase when — n/a (asset reference).
Decrease when — n/a (asset reference).
Technical effect — The manager reads grounding, LOD, dormancy, and obstacle-blocking parameters from this asset at the start of each simulation step.

Max Active Target Count¶

Visible effect — How many SwarmTarget objects the swarm reacts to at once. Any number of targets can be registered in the scene; only the closest Max Active are picked each tick and considered by agents. Extras stay registered as fallbacks and rotate in automatically when they become closer to the swarm.
Gameplay effect — Raise it for multi-target setups (escort missions, multi-boss rooms) where agents must split toward more than one target simultaneously. Lower it to keep a large pool of registered fallbacks but only ever attract agents to a handful at a time.
Increase when — Agents need to engage more targets concurrently than the current value allows.
Decrease when — You want the swarm to focus on fewer hot targets even though many SwarmTargets exist in the scene.
Technical effect — Sizes the per-slot snapshot, surface-flow goal-field, and per-agent target-index buffers. Active-set selection ranks all registered targets by squared distance to the swarm centroid each FixedUpdate and writes the top N into the active slots.

Initialize On Awake¶

Visible effect — Whether the manager allocates its agent buffer and prepares for spawning immediately on Awake.
Gameplay effect — Leave on for most scenes. Turn off only when a script needs to assign a settings asset or configure the manager before it runs.
Increase when — n/a (boolean).
Decrease when — A script must set the Settings reference or override configuration before the first simulation step.
Technical effect — When off, nothing allocates until SwarmManager.Initialize() is called manually from script.

Core — Target Selection¶

Power-user knobs — leave at defaults unless you have a reason

Retarget Interval¶

Visible effect — How frequently (in seconds) each agent re-evaluates which target to follow.
Gameplay effect — Shorter intervals make agents react faster when a new target appears or an old one moves far away. Longer intervals reduce overhead but make switches feel sluggish.
Increase when — The swarm is large and retarget cost is visible in profiling.
Decrease when — Agents feel slow to react to a new target entering the scene.
Technical effect — Each agent stores its own cooldown timer seeded with a jittered offset; when the timer fires, the agent scans the target registry and switches if the hysteresis condition passes.

Retarget Interval Jitter¶

Visible effect — Adds a deterministic per-agent spread to the retarget interval, so checks are distributed across frames rather than firing in a synchronized pulse.
Gameplay effect — Invisible to players but prevents a large swarm from processing all retarget checks in a single frame spike.
Increase when — Frame timing shows retarget work clustering in a single frame.
Decrease when — You need tightly synchronized retarget behavior (uncommon).
Technical effect — The jitter is deterministic (agent index–based), so results are reproducible across runs.

Target Switch Distance Factor¶

Visible effect — How much closer a new target must be (as a fraction of the current target's distance) before the agent switches. Lower values make agents stickier.
Gameplay effect — Prevents noisy swapping when two targets are nearly equidistant. Raise it to make agents opportunistically chase whichever target is marginally closer.
Increase when — Agents feel too reluctant to switch to an obviously closer target.
Decrease when — Agents thrash between two close targets too easily.
Technical effect — A candidate target must satisfy candidateDist < currentDist * factor before switching is considered.

Target Switch Min Distance Improvement¶

Visible effect — A world-space distance floor (in world units) that the new target must beat, regardless of the factor ratio.
Gameplay effect — Stops swaps between two targets that are practically side by side. Matters most when two targets are close together and the ratio check alone is too noisy.
Increase when — Agents still thrash between very close targets even after tightening the distance factor.
Decrease when — Agents fail to switch even when a target is clearly closer.
Technical effect — Applied as an additional AND condition after the distance-factor check.

Immediate Retarget Distance Factor¶

Visible effect — An emergency threshold: if a target is this fraction of the current distance, the agent switches even before its retarget cooldown expires.
Gameplay effect — Lets agents snap to a very close target immediately rather than waiting for the next evaluation window. Keep this well below Target Switch Distance Factor so it only fires on genuinely obvious switches.
Increase when — Agents wait too long to switch when a target spawns directly adjacent.
Decrease when — Agents switch too aggressively mid-cooldown.
Pitfalls — Setting this above or equal to Target Switch Distance Factor causes it to fire on every evaluation, making the cooldown meaningless.
Technical effect — Bypasses the retarget cooldown when the candidate distance is below currentDist * immediateRetargetDistanceFactor.

The manager is also where the Surface Flow Field is baked — the bake bounds, layer masks, and Bake Now button live in this inspector, though the runtime data is stored on the linked SwarmSettings asset.

For the system overview and runtime tuning, see Navigation. The fields below describe the bake-time configuration only.

Enable it on the linked SwarmSettings asset (or click Enable Surface Flow Field directly in the inspector). The manager bakes automatically the first time it initializes at play start, so no manual step is required. Click Bake Now to also save a snapshot with the scene — useful for Scene-view gizmo previews at edit time or for faster play-mode entry on large maps.

Sampling Bounds¶

The bake only processes geometry inside this volume. Use the Snap Bounds To Scene button to fit it automatically around all enabled colliders matching the Walkable or Unwalkable masks, or set Center and Size manually.

Field	What it does
Center	World-space center of the bake volume.
Size	World-space extents of the bake volume.

Layers¶

Field	What it does
Walkable Layer Mask	Floor and ramp layers the bake can stand agents on.
Unwalkable Layer Mask	Walls, columns, overhead bars, and props that block cells or connections. Keep separate from Walkable Layer Mask.

The bake rasterizes the union of Walkable and Unwalkable. The Effective Obstacle Layer Mask shown below the layer controls is a read-only preview. Layers present in either surface-flow mask are automatically excluded from SwarmSettings obstacle blocking, because static obstacles handled by the flow field do not also need runtime physics checks.

Bake Sampling¶

All parameters here are advanced — leave at defaults unless you have a reason

Field	What it does
Cell Size	World-space size of each flow-field cell. Smaller cells produce more accurate paths but increase memory and bake time quadratically over the sampled area.
Quality	Cardinal stores 8-way direction arrows. Smooth stores an integration field for wall-aware gradient sampling — better directions, higher per-goal memory cost.
Max Slope Angle	Steepest slope (in degrees) the bake accepts as walkable.
Max Step Height	Maximum small ledge height allowed between adjacent cells.
Max Drop Height	Maximum one-way downward drop allowed between adjacent cells.
Connection Ground Tolerance	How much the ground at the midpoint between adjacent cells can deviate from the expected height before the connection is rejected. Raise if valid terrain is left disconnected; lower to reject narrower gaps or holes. (Advanced mode only.)
Query Trigger Interaction	Controls whether trigger colliders are included in terrain and blocker raycasts during the bake. (Advanced mode only.)

Auto Bake On Awake¶

Field

What it does

Auto Bake On Awake

When on (default), the manager rebuilds the surface map and rebakes every target field automatically when it initializes at play start. The runtime always matches the current scene geometry without a manual step. Turn this off to instead reuse the snapshot saved with the scene via Bake Now — faster startup on large maps, but the saved map can go stale if scene colliders change after the bake.

After configuring bounds and layers, you can optionally click Bake Now to build the map and save it with the scene. This is required only when Auto Bake On Awake is off; otherwise it is purely a convenience for previewing the bake in the Scene view at edit time, or for skipping the physics raycast pass at play start.

Scene Gizmos (Surface Flow)¶

Field	What it does
Gizmo Visibility	When to draw cells and arrows in the Scene view. When Selected matches standard manager gizmo behavior; Always keeps the map visible while editing other objects.
Gizmo Target Index	Which baked target field to visualize. `-1` shows the first available field.
Gizmo Draw Radius	Maximum XZ radius around the Scene-view focus area within which cells, arrows, and unreachable markers are drawn. Bounds wire and goal highlight always draw regardless of this value.

Debug¶

The Debug section is editor-only. None of these fields affect runtime simulation cost in shipped builds, except Track Step Timings which has a small stopwatch overhead when enabled.

Scene Gizmos¶

Field	What it does
Show Movement Direction Gizmos	Draws a line per agent showing its current movement direction in the Scene view.
Movement Direction Gizmo Length	World-space length of each direction line.
Show Desired Target Position Gizmos	Draws the per-agent target point derived by the active behavior profile.
Show Selected Agents Only Debug Gizmos	Limits agent-level gizmos to only the agents currently selected in the SwarmAgentDebugWindow.
Show Personal Space Debug Gizmos	Visualizes personal space and local crowd spacing checks.
Show Dormancy Debug Gizmos	Tints dormant agents in the Scene view so you can see which agents are sleeping and skipping steering.

Stats Overlay¶

Field	What it does
Show Stats Overlay	Displays a runtime HUD in the Game view showing active agent count and simulation timings.
Show Stats Overlay System Info	Adds device, CPU, GPU, memory, and OS details to the overlay. Useful when validating performance across devices.

Profiling (Advanced mode only)¶

Field	What it does
Track Step Timings	Captures lightweight stopwatch timings around each simulation step. Useful during profiling; disable before shipping.
Step Timing Average Sample Count	Number of frames used to smooth displayed timing averages when tracking is active.

Swarm Visual Manager¶

Automatically added alongside SwarmManager. It owns the pool of visual GameObjects and syncs their position, rotation, and animation state from SwarmAgentData each frame. The parent GameObject for pooled agents is created automatically as a sibling of the manager.

The defaults work for desktop builds. On mobile or with GPU instanced rendering, review the fields below — several directly affect rendering correctness and performance at high agent counts.

General¶

Field	What it does
Manager	The `SwarmManager` that owns the simulation data this component renders. Assigned automatically when both components are on the same GameObject.
Fallback Agent Prefab	Prefab used when a spawn request or archetype does not specify its own agent prefab.
Agent Root	Parent transform for pooled agent visual instances. Defaults to this GameObject when left empty.
Initial Pool Size	Number of agent visuals to prewarm for each prefab on the first spawn. Higher values reduce instantiation spikes at wave start but use memory up front. The pool never exceeds the manager's capacity regardless of this value.

Instanced Rendering¶

These fields control how Graphics.DrawMeshInstanced calls are issued for archetypes that opt into GPU instanced rendering. They have no effect on archetypes using the per-agent MeshRenderer path.

Mobile correctness: read these before shipping

Graphics.DrawMeshInstanced does not cull individual instances automatically. Without the frustum culling fields below configured correctly, every active agent submits a draw call regardless of whether it is on screen — this is a significant regression on mobile.

Field	What it does
Instanced Culling Camera	The camera used for per-instance frustum culling before each `DrawMeshInstanced` call. When left empty, the component resolves the main camera (or first active camera) automatically. Assign explicitly on mobile or when your scene has multiple cameras to ensure the correct camera is used.
Disable Instanced Frustum Culling	Turns off per-instance CPU frustum culling entirely. Only useful when all active agents are guaranteed to be on screen at once (rare). Leave this off — culling is on by default.
Instanced Shadow Casting Mode	Shadow casting mode for all instanced archetypes. Defaults to Off because `DrawMeshInstanced` has no per-instance shadow culling — every active agent would cast a shadow even off-screen, which is expensive on mobile. Enable only on platforms where instanced shadows are affordable.
Instanced Receive Shadows	Whether instanced agents receive shadows from other casters.
Instanced Layer	Unity layer used when issuing instanced draw calls.

Swarm Settings — global simulation parameters consumed by the manager.
Targets — what agents chase.
Navigation — runtime behavior of the Surface Flow Field.
Performance — stats overlay, profiling, LOD tuning.