Swarm Settings Asset

SwarmSettings is a ScriptableObject that lives in your project (usually at Assets/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.

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 and in the Setup section of the Simple inspector.

• Apply Fixed Timestep On Initialize — when enabled, the swarm applies the two timestep values below to Unity's Time.fixedDeltaTime and Time.maximumDeltaTime at startup. Useful for locking simulation rate without touching Project Settings by hand.
• Fixed Timestep — physics and swarm simulation timestep in seconds, applied when the toggle above is on. 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. Clamped at runtime to be no less than Fixed Timestep, so physics can never advance slower than one step per rendered frame.
• 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.

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 ApplyExternalForce.

• 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

• Enable Body Blocking — agents resolve overlaps with each other. Keep on for readable dense crowds.

Warning

Agent Spacing Scale (in Default Spawn Profile) controls the radius used for agent-to-agent separation. Setting it 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.

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 resolves overlaps between agents and level colliders (walls, pillars, props). It runs a sphere overlap query each step and pushes agents out of any collider in the configured layer mask.

• 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. High values correct penetrations quickly; very high values on large fast-moving crowds can produce jitter.
• Obstacle Blocking Max Correction Per Step — hard cap on the per-step correction distance, in world units.
• 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.
• Obstacle Blocking Query Interval — runs the obstacle overlap query every N fixed steps instead of every step. Higher values reduce physics query cost but allow brief penetration between checks. The correction is applied when the query does run, so the visible result depends on query frequency and agent speed together.
• 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 automatically strips its surface-flow Walkable and Unwalkable layers from the mask at runtime so static walkable geometry is handled by the flow field instead. That derived value is not stored.

Visibility LOD

Off-screen agents still run full movement integration every step. These settings reduce facing-update 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.

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 And Surround, 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.
• LOD Switch Margin — hysteresis distance in world units that prevents agents from flickering between tiers near a boundary. An agent must cross the boundary plus this margin before its tier changes.
• Crowd Edge Promotion — 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.

Animation refresh by tier

• Reduced Animation Refresh — how often Reduced-tier agents update Animator and VAT playback parameters during the visual sync pass, in fixed steps. Higher values cut MaterialPropertyBlock write cost at the cost of slightly coarser animation cadence on mid-range agents.
• Cheap Animation Refresh — how often Cheap-tier agents update Animator and VAT playback parameters during the visual sync pass, in fixed steps.

Behavior tier restrictions

• Close Range Pressure Full Tier Only — when enabled, Close-Range Pressure steering and its speed multiplier only run for Full-tier agents. Reduced and Cheap agents skip the pass entirely.
• Adaptive Surround Full Tier Only — when enabled, only Full-tier agents run the adaptive Approach And Surround slot selection. Reduced and Cheap agents reuse cached slots or fall back to cheap seeded surround points.
• Approach And Surround Reduced Interval — how often Reduced-tier agents run Approach And Surround 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 Surround Cheap Interval — how often Cheap-tier agents run Approach And Surround steering, in fixed steps. Full-tier agents always run every step.

VAT shader quality LOD

• Enable VAT Quality LOD — reduces VAT shader cost on distant agents by force-disabling frame interpolation and normal-texture sampling at Reduced tier, and snapping to the dominant walk/run clip at Cheap tier. Only affects the package VAT shader (Massive Swarm System/Swarm VAT URP) and custom shaders that read _InstancePlayback.w. Disable to keep every agent at full VAT shader quality regardless of distance.

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

• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• Nearby Wake Min Speed — minimum planar speed another agent needs before it can wake nearby dormant agents.

Cost tuning

• 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.
• 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 Wake Required Blockers if dormant agents wake too eagerly in a packed crowd; lower 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 advanced fields below are only visible in the Advanced inspector tab and are not covered elsewhere.

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

• 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.

Advanced: 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.