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 to reach those knobs and the extra debug options.

Core — Setup¶

Start here — most projects only need these two

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 tracked by agents. Extras stay registered as fallbacks and rotate in automatically when they become meaningfully closer to the swarm than a current active member.
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 runs each FixedUpdate: registered targets are ranked by squared distance to the swarm centroid, but active targets receive a multiplicative score bonus (controlled by Active Swap Distance Factor) that makes it harder for nearby non-active targets to displace them.

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

Active Swap Distance Factor¶

Visible effect — How sticky the current active target set is. Lower values make registered non-active targets work harder to displace an active member; higher values let the active set reshuffle more freely.
Gameplay effect — Prevents the active set from churning when two targets hover near the boundary. At the default, a non-active target must be noticeably closer than an active one before it earns its slot. Raise it toward 1 for faster rotation when targets move around unpredictably; lower it for a more stable, locked-in active set.
Increase when — The active set feels slow to pick up a target that has clearly moved closer than a current active member.
Decrease when — The active set shuffles too often when targets are nearly equidistant to the swarm centroid.
Pitfalls — Setting this to 1 removes the stickiness bonus entirely, so the active set can swap a member for any target that is even fractionally closer at the moment of evaluation. At high registered-target counts this can cause visible thrashing.
Technical effect — Each active target's squared-distance score is multiplied by factor² before the ranking comparison. A non-active target can only displace an active member if its raw squared distance beats that discounted score.

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 run its own setup before the first allocation, then call SwarmManager.Initialize() manually. (The Settings asset is assigned in the inspector, not from script.)
Increase when — n/a (boolean).
Decrease when — A script must run its own setup before the first allocation, then call SwarmManager.Initialize() manually.
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 (compared on squared distances) 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 Bounds Center and Bounds Size manually.

Field	What it does
Bounds Center	World-space center of the bake volume.
Bounds 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. At runtime the manager strips both Walkable and Unwalkable layers from SwarmSettings obstacle blocking. The flow field routes around that geometry, and its cell-boundary pass keeps agents inside walkable cells each frame — so there is no gap for obstacle blocking to backstop. Obstacle blocking in a surface-flow scene is for dynamic obstacles (barricades, breakables, doors) on a separate layer that does not overlap either surface-flow mask.

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. Eikonal solves that field with Fast Marching so directions vary by continuous angle instead of the eight grid steps — the smoothest flow, at a heavier bake.
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.

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.

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.