Swarm Settings Asset

SwarmSettings is a ScriptableObject that lives in your project (usually at Assets/CreativeSpore/MassiveSwarmSystem/Settings/). One instance applies to the whole swarm. Create a new one via right-click → Create → Massive Swarm System → Swarm Settings.

The default settings asset is auto-assigned to a new SwarmManager. Duplicate it for level-specific tuning and assign the variant to the manager's Settings slot.

Finding a setting fast

This inspector has a search-and-filter bar at the top. See Finding a Setting to search by word or symptom, show only the performance-heavy settings, or show only the ones you have changed.

Capacity

• Max Agents — total agent slots allocated at startup. Raise this before spawning more agents than the default allows. Lower it to reduce memory overhead on mobile.

Timing & Visuals

These fields appear in the Timing & Visuals section of the Advanced inspector. The Simple inspector shows only Apply Fixed Timestep On Initialize (in its Setup section) and the two Render Smoothing fields (in its Performance section); Fixed Timestep, Maximum Allowed Timestep, and Visual Interpolation are Advanced-only. The defaults suit most projects — switch to Advanced to change them.

• Apply Fixed Timestep On Initialize — on by default. The swarm writes the two timestep values below to Unity's Time.fixedDeltaTime and Time.maximumDeltaTime at startup, locking the simulation rate and capping the catch-up window without you editing Project Settings. Turn it off only if you drive Unity's Time Manager yourself.
• Fixed Timestep — physics and swarm simulation timestep in seconds, applied when the toggle above is on. The default 0.0333 runs the swarm at 30 Hz. Smaller values mean more simulation steps per second and higher CPU cost.
• Maximum Allowed Timestep — caps the fixed-step catch-up window in seconds, applied when the toggle above is on. This is what stops the low-frame-rate spiral: when a frame runs long, Unity would otherwise run several catch-up simulation steps in the next frame, each of which costs more under load and drops the frame rate further. Capping the window near Fixed Timestep lets in-game time slow down instead of snowballing. The inspector's OnValidate keeps this at or above Fixed Timestep; a value set from code at runtime is applied as-is, and Unity ignores any value below Fixed Timestep.
• Visual Interpolation — controls how pooled agent visuals are positioned between fixed simulation steps.
  • None — visuals snap to the last simulated position each frame.
  • Interpolate — visuals blend between the previous and current simulated positions. Smooth at normal frame rates; adds one fixed step of visual lag.
  • Extrapolate — visuals project ahead using the agent's current velocity. Responsive but can overshoot on sharp direction changes.
• Enable Render Smoothing — filters each agent's drawn position through a velocity-adaptive low-pass so a dense crowd packed around a target stops trembling in place. The filter runs on the pose Visual Interpolation produces, so the two combine. The simulation, attack reach, and containment all work from the agent's true position; only the rendered body is filtered, and it can never drift more than half the agent's radius from that position. The agent's collider moves with the rendered body, so raycasts and trigger checks hit what the player sees — if a check needs the true position instead, see Hit detection. On by default.
• Render Smoothing Cutoff — how strongly the filter damps jitter, in Hz. Lower values smooth more — calmer dense piles, but slight visual lag on fast movers. Higher values track motion more tightly. The default is 0.6; adjust in small steps (about 0.2 at a time) and judge by eye — useful values sit near the default, well below the allowed maximum of 10. Raise it if fast-moving agents look rubbery; lower it if a settled pile still shimmers.

Warning

Maximum Allowed Timestep must be at least as large as Fixed Timestep or Unity ignores the value. The OnValidate clamp enforces this automatically in the inspector, but watch for it when setting values from code.

Default Spawn Profile

Fallback values used when an agent is spawned without an archetype, or when an archetype does not provide its own movement profile.

• Default Agent Radius — fallback agent radius in world units used for body blocking, Personal Space, and grid queries when no archetype radius is provided.
• Agent Spacing Scale — multiplies each agent's radius for agent-to-agent separation. 1 uses the archetype radius directly. 0 disables separation (and also disables Personal Space entirely). Values above 1 spread agents wider than their physical radius.
• Default Movement Profile — fallback SwarmMovementProfile asset for speed, acceleration, and turning when an agent has no profile of its own. If unassigned, built-in default movement values are used.
• Default Push Resistance — how hard default agents resist external shoves. Higher values mean external forces like pushback affect the agent less.
• Grid Cell Size — spatial hash cell size for neighbor queries. Keep this close to agent diameter (roughly 2 × Default Agent Radius). Very small cells increase hash overhead; very large cells increase per-cell neighbor checks.

Warning

Setting Agent Spacing Scale to 0 disables Personal Space entirely — the runtime skips the separation pass regardless of behavior profile settings. Keep it above 0 for any profile that needs visible crowd separation.

Agent Reactions

Controls how agents respond to external forces — pushback from weapons, explosions, or any code that calls SwarmAgent.AddImpulse (one-shot knockback) or SwarmAgent.AddForce (sustained force). See SwarmAgent.

• Default External Control Duration — seconds that an external force influences an agent after it is applied. After this window, normal steering resumes.
• External Velocity Damping — how quickly the external velocity component decays per second. Higher values cause agents to return to normal steering sooner.
• External Force Steering Authority — fraction of normal steering that remains active while an external force is in effect (range 0–1). 0 means external force overrides steering entirely; 1 means steering runs at full weight alongside the external force.
• Max External Velocity — speed cap on the velocity component contributed by external forces. Prevents agents from flying off at extreme distances when large impulses are applied.

Grounding

• Enable Grounding — physics-based ground probes, step-up smoothing, and gravity. Leave on for 3D scenes; disable for top-down flat levels.
• Ground Layer Mask — which collision layers count as walkable ground.
• Max Ground Slope Angle — steepest slope agents can stand on.

Warning

Ground Layer Mask must include the layer your floor and terrain colliders are on. If it is empty or wrong, agents fall through the ground. The grounding system uses physics probes — it reads collider layers, not NavMesh.

The Grounding section enabled, with Ground Layer Mask set to a real layer (here, Default) — the setup agents need to stay on the floor.

Body Blocking

Body Blocking is the physics pass that resolves overlaps between agents so they hold space instead of sharing it. It runs in the simulation step, separate from Personal Space: Personal Space is a steering behavior that nudges a crowd apart through movement, while Body Blocking corrects whatever overlap is left over.

• Enable Body Blocking — agents resolve overlaps with each other. Keep on for readable dense crowds.
• Body Blocking Correction Strength — fraction of each overlap resolved per simulation step (0–1). Higher pulls agents apart faster but can jitter in a tight pack; the default 0.65 settles smoothly.
• Body Blocking Max Correction Per Step — cap on the separation distance applied to one agent in a single step, in world units. Stops a deep overlap from launching a body.
• Body Blocking Velocity Push — velocity impulse added while correcting an overlap, so separation carries a little momentum rather than being pure position fix-up. 0 corrects position only.
• Body Blocking Max Pairs Per Agent — caps how many overlapping neighbors each agent resolves per step. Only real overlaps count toward the limit. Below 8 causes clumping that is hard to undo; 12–16 is the safe range for dense swarms. This cap applies to soft blocking only — it has no effect while Hard Agent Separation is on (see below).
• Body Blocking Reduced Interval — how often Reduced-tier agents (visible, but not near the target) resolve overlaps, in fixed steps. 1 is every step; the default is 8. Lower toward 2–4 if mid-distance crowds show pile-up jitter. Full-tier agents always run every step.
• Body Blocking Cheap Interval — how often Cheap-tier agents (far or off screen) resolve overlaps, in fixed steps. Higher saves more on distant crowds; the default 16 stays within the off-screen quality grace, so agents are corrected before the camera reaches them.

Warning

Agent Spacing Scale (in Default Spawn Profile) sets the radius used for agent-to-agent separation, for both Body Blocking and Personal Space. Setting it to 0 disables separation entirely — the runtime skips the pass regardless of behavior profile settings. Keep it above 0 for any swarm that needs visible crowd separation.

Hard Agent Separation (Layer 1)

Soft Body Blocking resolves a fraction of each overlap per step and shares a per-agent budget, so a very dense pack — hundreds of agents crushing toward one target — can stay partly interpenetrated. Hard Agent Separation is an optional pass that resolves awake agents to their full minimum spacing each step, so the crowd keeps usable spacing under that pressure. It is off by default; turn it on for scenes that visibly pile up.

While it is on, it takes over agent-to-agent spacing from soft Body Blocking — the two do not stack. It runs every step on every awake agent with its own neighbor budget, so it costs more than soft blocking. Leave it off unless a scene needs the guarantee.

• Enable Hard Agent Separation — turns the pass on. It runs only while Enable Body Blocking is on (the inspector greys these controls out otherwise) and Agent Spacing Scale is above 0.
• Hard Separation Max Iterations — maximum separation sweeps per step. Neighbors are gathered once and replayed across the sweeps, so each extra sweep is cheap, and it stops early once the crowd is separated. 4 clears a dense corner crush in about a second; raise it to converge faster at little extra cost.
• Hard Separation Max Step Radius Fraction — caps how far the pass may move an agent in one step, as a fraction of its radius. This keeps separation within a step's safe travel so it cannot push a body through a wall before containment re-clamps it. 1 is a full radius (the safe maximum); lower settles slower but gentler.
• Hard Separation Residual Threshold — the pass stops sweeping for the step once the deepest remaining overlap is below this distance, in world units. Keeps a settled crowd at one sweep per step.

What changes while Hard Agent Separation is on

The hard pass resolves all of each awake agent's overlaps every step to reach full spacing, so the soft-path throttles drop out: Max Pairs Per Agent has no effect (the hard pass sizes its own budget to clear the whole crush), and the Reduced/Cheap Intervals above no longer apply — every awake agent runs every step regardless of Importance LOD tier. Correction Strength and Velocity Push still tune how agents resolve against dormant neighbors. Dormant agents stay on the cheap dormant-to-dormant heartbeat (see Dormancy).

Warning

Hard Agent Separation is validated on Surface Flow Field scenes. On scenes with physical obstacle walls, re-check the per-step cost at your target agent count before shipping — the pass runs on every awake agent, every step.

Target Crowd Blocking

Target Crowd Blocking steers agents away from the area directly around the target, so the crowd rings outward instead of collapsing into the center. It is a steering influence, not a hard collision. Agents at the very front are pushed laterally, making room for more of the crowd to land attacks simultaneously.

• Enable Target Crowd Blocking — turns the system on. Leave on whenever you want the crowd to form a ring rather than a pile.
• Target Blocking Falloff Distance — extra distance beyond the target's body surface where the influence fades to zero, in world units. A small value creates a sharp edge to the ring; a larger value produces a smoother gradient and spreads the crowd over a wider band.
• Target Blocking Strength — scales the steering impulse pushing agents out of the blocked area. Higher values keep agents at the ring edge more aggressively; lower values let the crowd press inward more.
• Target Blocking Max Agents — caps how many agents are considered when computing the blocking result each step. Raise this if the ring looks patchy in very large crowds.

Note

The body radius used by both Target Crowd Blocking and Target Body Blocking is configured per-target on the SwarmTarget component (Body Radius Source = Auto Detect or Manual). See Targets.

Target Body Blocking

Target Body Blocking resolves hard physical overlaps between agents and the target's body. Where Target Crowd Blocking shapes crowd flow through steering, this pass physically separates any agent that has clipped inside the target radius.

• Enable Target Body Blocking — turns the correction pass on. Leave on for any target with a physical body agents should not clip through.
• Target Body Blocking Correction Strength — fraction of the overlap resolved each simulation step. Higher values snap agents out faster but can produce visible jitter near the target surface.
• Target Body Blocking Max Correction Per Step — hard cap on the correction distance applied in a single step, in world units. Prevents runaway corrections when agents clip deeply.
• Target Body Blocking Velocity Push — velocity impulse added while correcting overlaps. A small value gives the correction a sense of physicality; 0 applies position correction only with no velocity change.

Obstacle Blocking

Obstacle Blocking keeps agents out of level colliders (walls, pillars, props). When its query runs, each agent tests a capsule volume spanning the path it travelled since the last check against the configured layer mask — so a fast or low-frame-rate step cannot tunnel through thin geometry — and is pushed back out toward the side it came from. That directional push is what holds a dense crowd behind a wall rather than letting pressure squeeze bodies through to the far side.

• Enable Obstacle Blocking — turns the pass on. Leave on for any scene with physical level geometry agents should not walk through.
• Obstacle Layer Mask — which collision layers count as blocking obstacles. Keep agent collider layers and ground layers out of this mask; those are handled by Body Blocking and Grounding respectively.
• Obstacle Blocking Correction Strength — fraction of the overlap resolved each step by the incremental depenetration fallback. High values correct penetrations quickly; very high values on large fast-moving crowds can produce jitter. The entry-face and safe-side containment that holds a crowd behind a wall repositions the body in full and is not governed by this value.
• Obstacle Blocking Max Correction Per Step — hard cap on the per-step distance the incremental fallback moves a body, in world units. The full-reposition containment path is not capped by it.
• Obstacle Blocking Velocity Push — velocity impulse added while correcting obstacle overlaps.
• Obstacle Blocking Max Colliders Per Agent — caps obstacle hits returned per query. The buffer is allocated once at startup to this size; raising it adds minor memory cost but allows more obstacles to be resolved per step. In cluttered or compound geometry, setting it too low can drop a wall from the query result and let a body through, so it affects containment, not just performance.
• Obstacle Blocking Query Interval — runs the obstacle query every N fixed steps instead of every step. Higher values cut physics query cost; the capsule still spans the steps in between, so a skipped step is covered rather than left open. The default of 2 balances cost against containment. Raise it to save more on lighter scenes; very high values can let a wall under sustained crowd pressure leak the occasional body.
• Obstacle Query Trigger Interaction — whether obstacle queries hit trigger colliders in addition to solid colliders.

Obstacle Layer Mask lives on the SwarmSettings asset, not on SwarmManager

You set Obstacle Layer Mask on the SwarmSettings asset in the Obstacle Blocking section. The SwarmManager inspector shows a read-only Effective Obstacle Layer Mask derived field — when Surface Flow Navigation is on, the manager strips both its Walkable and Unwalkable layers from the mask at runtime. Wall containment is handled entirely by the flow field's cell-boundary pass (the same pass the Enforce Cell Boundaries option mirrors on the sample follower component), which keeps agents inside walkable cells every frame. That leaves obstacle blocking free for dynamic obstacles — barricades, breakables, doors — on a separate layer. That derived value is not stored.

Visibility LOD

Off-screen agents still run full movement integration every step. These settings reduce facing-update and animation-refresh cost without changing simulation results.

• Offscreen Facing Update Interval — agents whose primary renderer has been off screen longer than the grace time only refresh their facing direction this often (in fixed steps). Movement and position integration still run every step. Set to 1 to refresh every step (no saving); raise it to cut visual-sync cost on large off-screen crowds.
• Offscreen Facing Visibility Grace Time — keeps full-rate facing updates briefly after an agent leaves view, in seconds. Prevents agents from snapping to a stale facing the moment they cross the camera edge.

Animation refresh by camera distance

Animation refresh cadence follows the camera, not the simulation importance tier. An on-screen agent close to the camera refreshes every visual sync. One farther than Distant Visible Distance from the camera refreshes on the Distant Visible Animation Refresh stride. Off-screen agents refresh on the Off-Screen Animation Refresh stride — they are not drawn, so the stride controls how current their pose is when they return to view.

• Distant Visible Distance — distance from the camera in world units beyond which an on-screen agent switches from every-sync refresh to the distant stride. Lower values throttle more of the visible crowd; higher values keep more agents at full animation cadence.
• Distant Visible Animation Refresh — how often on-screen agents farther than Distant Visible Distance from the camera refresh Animator and VAT playback parameters, in visual syncs. 1 means every sync; higher values reduce MaterialPropertyBlock writes for distant visible agents at the cost of slightly coarser animation.
• Off-Screen Animation Refresh — how often off-screen agents refresh Animator and VAT playback parameters, in visual syncs. Since off-screen agents are not drawn, this can be higher than the on-screen rate without any visible effect.

VAT shader quality LOD

• Enable VAT Quality LOD — keys VAT shader quality on camera frustum visibility, not the simulation importance tier. On-screen agents always render at full VAT quality regardless of how far they are from their target. Off-screen agents render at cheap quality: frame interpolation is disabled, the Mobile shader drops the per-vertex normal tap (Standard and High keep it), and all shaders snap to the dominant walk/run clip. Since off-screen agents are not drawn, the reduced quality is never player-visible — the savings scale with how much of the crowd is off screen. Disable to keep every agent at full VAT shader quality. Only affects the package VAT shaders (Massive Swarm System/Swarm VAT/Mobile, /Standard, /High) and custom shaders that read _InstancePlayback.w.

Importance LOD

The Importance LOD system classifies every active agent into one of three tiers each reclassify pass: Full (near the target and within budget), Reduced (visible or mid-range), and Cheap (distant or off-screen). Later passes use the tier to decide how often to run work like Personal Space, Approach & Press, and ground probes.

Core classification

• Enable Importance LOD — enables per-agent tier classification. Leave on for large counts; all agents run at Full tier when disabled.
• Full Quality Agent Cap — maximum agents allowed in Full tier. 0 means unlimited (every qualified agent stays Full). When the budget is reached, borderline agents stay Reduced.
• Reduced Quality Start Distance — planar distance from the target at which agents drop from the Full tier to the Reduced tier. Agents closer than this stay Full (before the optional cap).
• Cheap Quality Start Distance — planar distance at which agents drop from the Reduced tier to the Cheap tier. Agents farther than this become Cheap. Clamped at runtime to be no less than Reduced Quality Start Distance.
• Importance LOD Reclassify Interval — runs the full tier classification once per this many fixed steps. Tier transitions are coarse (distance bands are several world units wide) so reclassifying every N steps is visually invisible and reduces classifier self-cost proportionally.
• Cheap Demotion Margin — hysteresis distance in world units applied at the Reduced→Cheap boundary, so agents hovering there do not flicker between the two tiers. A Reduced agent must move past the Cheap Quality Start Distance plus this margin before it drops to Cheap. Other tier boundaries are unaffected.
• Crowd Edge Promotion Strength — integer range (0–2) of grid cells scanned around Full-tier agents. Cheap agents inside that range are promoted to Reduced so the visible crowd edge stays stable. 0 disables the pass.
• Off Screen Quality Grace — seconds an agent stays in the Full tier after its renderer leaves view. Prevents classification popping near the camera edge.

Personal Space refresh by tier

• Reduced Personal Space Refresh — how often Reduced-tier agents run the Personal Space separation pass, in fixed steps. 1 means every step; higher values reduce cost but make mid-range crowd separation less responsive.
• Cheap Personal Space Refresh — how often Cheap-tier agents run the Personal Space separation pass, in fixed steps.
• Reduced Personal Space Neighbor Scale — multiplies the Personal Space max-neighbor sample count for Reduced-tier agents (range 0–1). Lower values check fewer neighbors per pass.
• Cheap Personal Space Neighbor Scale — multiplies the max-neighbor sample count for Cheap-tier agents. 0 disables the Personal Space pass entirely for that tier.

Behavior tier restrictions

• Approach And Press Reduced Interval — how often Reduced-tier agents run Approach & Press steering, in fixed steps. On skipped steps the agent reuses its last approach steering so chase pacing remains stable. Full-tier agents always run every step.
• Approach And Press Cheap Interval — how often Cheap-tier agents run Approach & Press steering, in fixed steps. Full-tier agents always run every step.

For LOD tuning recommendations, see Performance.

Dormancy

Dormant agents skip steering computation when blocked by the crowd and unable to make progress. They wake automatically when space opens up.

Core

• Enable Dormancy — turns the system on. Reduces simulation cost in dense, slow-moving crowds.
• Dormancy Delay Seconds — how long an agent must keep wanting to move while staying inside the distance threshold before it goes dormant. Lower values save cost faster but raise the chance of brief flicker.
• Dormancy Distance Threshold — planar displacement threshold in world units. An agent that wants to move but stays within this distance from its anchor for the full delay goes dormant. Lower values require agents to be more truly stuck; higher values sleep slow movers sooner.

Wake conditions

• Dormancy Wake Blocker Lookahead — how far ahead, in world units, the wake-up check looks for blocking neighbors along the agent's desired direction. Larger values keep agents asleep longer in dense crowds.
• Dormancy Wake Blocker Half Angle Degrees — half-angle of the cone in front of a dormant agent used to count blockers. 90 means a full forward hemisphere; smaller values restrict the check to a narrow path ahead.
• Dormancy Wake Required Blockers — minimum blockers inside the cone needed to keep the agent asleep. 1 wakes as soon as the path is clear; raise it for crowds where some lingering bodies should not stop progress.
• Dormancy Wake On Target Move — when on, target movement past the distance threshold immediately wakes dormant agents. Leave off to let blocker / probe / nearby-motion rules stagger wake-up instead.
• Dormancy Random Wake Probe Interval — how often a dormant agent is allowed to wake as a random probe even when its path still looks blocked, in fixed steps. 0 disables random wake probes. Checks are spread by agent seed across fixed steps.
• Dormancy Nearby Wake Radius — distance around a dormant agent where moving agents can wake it on the next wake check. 0 disables nearby-motion wake-up.
• Dormancy Nearby Wake Min Speed — minimum planar speed another agent needs before it can wake nearby dormant agents.

Cost tuning

• Dormancy Body Blocking Interval — dormant-to-dormant body-blocking heartbeat in fixed steps. 0 disables sleeper-sleeper correction (cheapest, no correction bursts). Awake agents still resolve lightly against dormant bodies regardless.
• Dormancy Wake Recheck Interval — how often a dormant agent recomputes movement intent and runs its blocker wake check, in fixed steps. Re-checks are spread round-robin across agents so cost is amortized.

Tuning order

Start with Enable Dormancy + Dormancy Delay Seconds + Dormancy Distance Threshold. Raise Dormancy Wake Required Blockers if dormant agents wake too eagerly in a packed crowd; lower Dormancy Random Wake Probe Interval if rear-rank agents look frozen too long after the front lines clear.

Surface Flow Field

SwarmSettings stores the runtime parameters for the optional Surface Flow Field navigation system. Bake-time configuration (cell size, quality, bounds, layers, Bake Now button) lives on the Swarm Manager inspector.

Most fields are covered on the Navigation page. The fields below are not covered there. Every Surface Flow Field setting — the LOD skip intervals, wall margin, and the grounding option below included — lives in the Advanced inspector; Simple mode does not show them.

Advanced: LOD skip intervals

These fields gate how often Reduced and Cheap agents run the entire surface-flow per-agent loop body — cell lookup, release-distance check, and off-grid detection. They are distinct from the sample interval fields, which only gate the field read itself.

• Surface Flow Skip Reduced Interval — Reduced-tier agents refresh surface-flow bookkeeping this often, in fixed steps. On skipped steps the last cached steering direction is applied directly. Setting this to 1 makes every Reduced agent run the full loop every step.
• Surface Flow Skip Cheap Interval — Cheap-tier agents refresh surface-flow bookkeeping this often, in fixed steps. At the default value the worst-case staleness window is a few frames, which is invisible at Cheap-tier distances.

Advanced: wall clearance

• Surface Flow Wall Margin — extra clearance kept between an agent's body and any blocked cell edge when Enforce Cell Boundaries is on, in world units. Added to the agent's own radius. Raise this if agents still visibly clip into wall cells after enabling boundary enforcement.

Not the same as Wall Clearance

Surface Flow Wall Margin is a runtime body gap. It is separate from the bake-time Wall Clearance Strength / Distance on the Swarm Manager, which shapes the route itself. See the Glossary.

Grounding outside the field

• Assume Flat Ground Outside Field (experimental) — when Surface Flow grounding is active and an agent is outside the baked field, skip physics ground probes and assume the surrounding world is flat at the field's lowest walkable cell height. Only enable this on levels where the area outside the baked field is actually flat. Works in both Prefer Field Height and Replace Physics When Available grounding modes.

Warning

Assume Flat Ground Outside Field is marked experimental. Enabling it on levels with varied terrain outside the baked field causes agents to float or sink when they leave the field boundary.

Related

• Swarm Manager — the component that consumes these settings.
• Performance — how Capacity, LOD, and Dormancy affect frame budget.
• Troubleshooting — common Grounding, Body Blocking, and Obstacle Blocking issues.