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 — The inspector auto-clamps this to at most Target Switch Distance Factor, so you can't push it higher. The ceiling is the trap: set it equal to Target Switch Distance Factor and the immediate-retarget test matches the normal switch test, so the cooldown stops adding any stickiness. Keep it below the switch factor.
Technical effect — Bypasses the retarget cooldown when the candidate distance is below currentDist * immediateRetargetDistanceFactor.

The manager is where the Surface Flow Field is turned on and baked — the on/off toggle, bake bounds, layer masks, and Bake Now button all live in this inspector. Shared routing parameters live on the linked SwarmSettings asset. Because the toggle is on the manager, one scene can run the field while another that reuses the same settings asset does not.

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

Turn it on with the Surface Flow Field Navigation toggle here (or click Enable Surface Flow Field when the section is off). 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.
Bounds Source	Optional. When set, Snap Bounds To Scene fits the footprint around only the colliders under this object and its children. Leave empty to fit every matching collider in the scene.

Skip a giant floor plane

A scene-wide floor plane makes Snap Bounds To Scene stretch the volume across the whole floor, when you usually only care about the area with slopes, steps, and obstacles. Parent that geometry under one object, drop it into Bounds Source, and snap — the footprint hugs your obstacles instead of the floor. The floor underneath is still sampled: the snap lowers the bottom of the volume to cover any ground that overlaps the footprint, so agents stay grounded.

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.
Climb Cost Bias	Soft penalty against routes that climb upward, as extra step cost per world unit of climb (in multiples of one flat step). `0` ignores climb entirely; `1` makes a 1-unit climb cost as much as one extra flat step. A steep climb is still taken when no comparably short flatter route exists.
Wall Clearance Strength	How hard routes bow away from walls, as extra step cost at the wall face (in multiples of one flat step). `0` keeps the shortest path that grazes walls and corners; higher values push the route farther off. The cost is soft, so a gap an agent could fit through is never sealed.
Wall Clearance Distance	How far the wall berth reaches, in world units. The penalty is strongest one cell off the wall and fades to zero at this distance. Below half a cell it rounds to off.
Clearance Radius	Agent footprint radius the bake reasons about, in world units. The bake sphere-casts at this radius, so a slot between two walls narrower than twice this value bakes non-passable, while a wider opening stays walkable. `0` = legacy single-ray point sample.
Agent Height	Agent standing height the bake reasons about, in world units. With a non-zero height and an Unwalkable mask set, each cell checks a capsule spanning this height above the floor, so a floor under an overhead obstacle bakes walkable only when the agent fits under it. `0` = footprint-only (no overhead detection).
Connection 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 Triggers	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	Which target's baked flow field to visualize. Pick a SwarmTarget from the scene by name, or leave it on Auto to show 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.

Open Legend when you need to decode the Scene-view markers. It explains the green walkable cells, red unwalkable markers, pink unreachable markers, and cyan flow arrows used by the manager-owned Surface Flow gizmos. When Gizmo Visibility is Hidden, the legend is disabled with the rest of the Surface Flow gizmo controls.

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.

Per-Agent Scene Gizmos¶

Per-agent scene gizmos (movement direction, desired target position, personal space, dormancy) have moved to the Swarm Debug window. An Open Swarm Debug Window button in this section opens it directly.

The gizmos draw only while the window is open in Play mode, for the manager it is inspecting. See Swarm Debug for the full control reference.

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
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 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.
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.
Receive Shadows	Whether instanced agents receive shadows from other casters.
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.