Skip to content

Behaviors

Behaviors are modular steering passes that run each simulation step. Enable them in a SwarmBehaviorProfile assigned to your archetype. Most profiles only need two or three active behaviors.

Finding a behavior setting fast

The Behavior Profile inspector has a search-and-filter bar at the top. See Finding a Setting to search by word or symptom, or to narrow the inspector to the rows that sit away from the factory default. On one of the shipped preset profiles that includes rows the preset tuned, not only rows you touched.

Create one with right-click in the Project window → Create → Massive Swarm System → Agents → Behavior Profile, then drop it into the Behavior Profile slot on your archetype.

Start from a preset

The fastest way to a swarm that looks right is not to tune anything. Open a Behavior Profile and the top section is Starting Presets, six buttons that write a complete, playable configuration in one click. Pick the closest one, hit Play, then tune from there.

Preset What it gives you
Direct Chaser Straight pursuit with basic spacing. No wander, no standoff. The simplest thing that works
Loose Surround Agents press in and spread around the target. A small chase wander keeps the ring from looking geometric
Tight Horde Dense pressure right against the target, with stronger spacing so bodies still hold their ground
Melee Queue Packed in tight and ready to strike. No wander, so the crowd reads as deliberate rather than milling
Wide Circle The only preset that turns Orbit Style on. Loose circling at a wider radius, with a 1 unit standoff
Vampire Survivors Crowd The survivor-like baseline: hardest approach pressure of the six, moderate spacing, some wander

A preset rewrites the whole profile, not just its own fields

Every preset writes all seven behavior blocks. It turns Approach & Press, Personal Space and Idle Motion on; it forces Retreat, Hold Nearby Swarm and Predictive Catch-Up off; it forces Orbit Style off for five of the six (Wide Circle is the exception); and it resets the entire Out-of-Sight Fallback block, including the toggle back to off and Sight Distance back to 25. So if you spent an afternoon tuning Retreat and then click a preset to "try something", that tuning is gone. Undo works, but check the profile before you save. The inspector says the same thing above the buttons, though only when help text is turned on.

Where to start

If you would rather build a profile by hand, this is the shortcut version.

Game type Recommended behaviors
Default horde Approach & Press, Personal Space, Idle Motion
Survivor-like crowds Approach & Press (strong), Personal Space (moderate)
Melee packs Approach & Press + Personal Space
Flankers / interceptors Add Predictive Catch-Up
Harassers / strafing enemies Orbit Style + light approach pressure
Loose crowd cohesion Small Hold Nearby Swarm (tune carefully against Personal Space)

Game view of swarm agents pressing in around the player target

Approach & Press + Personal Space: agents close on the target, press against it, and hold their spacing through the crowd instead of collapsing to a single point.

Simple mode field finder

The inspector's Simple mode surfaces a condensed set of fields in three blocks. The third one, Out-of-Sight Fallback, only becomes editable while Approach Target is enabled, since it is a fallback for the approach behavior. Each field links to its full documentation in the Advanced subgroup pages.

Simple block Field Full documentation
Approach Target Approach Weight Approach & Press
Approach Target Combat Standoff Approach & Press
Crowd Spacing Spacing Strength Personal Space
Crowd Spacing Spacing Radius Personal Space
Out-of-Sight Fallback Use Out-of-Sight Fallback Out-of-Sight Fallback

When Simple mode is hiding something that still runs

Simple mode does not disable the four Advanced-only behaviors, it just stops showing them. If Predictive Catch-Up, Retreat, Hold Nearby Swarm or Orbit Style is enabled on the profile, the inspector prints a notice naming which ones and telling you to switch to Advanced. That message is the answer to "why is my swarm doing something I have no control for", so read it rather than dismissing it.

Factory defaults

What a brand-new Behavior Profile contains, before you touch anything or apply a preset. Three behaviors ship on and four ship off. Keep this handy for undoing a tuning pass that went sideways, especially if you are reading the PDF away from the editor.

Behavior Ships Default values
Approach & Press on Weight 1, Arrival Distance 0.75, Combat Standoff 0, Chase Wander Weight 0, Chase Wander Interval 0.6
Personal Space on Weight 1, Radius 1.25, Max Neighbors 8
Idle Motion on Weight 0.2, Change Interval 2, Jitter 0.5
Out-of-Sight Fallback off Sight Distance 25, Follow Radius 3, Follow Weight 0.75, Seek Bias 0.15, Max Neighbors 12, Follow Memory 0.75
Retreat off Weight 1, Panic Radius 3, Recover Radius 6
Hold Nearby Swarm off Weight 0.35, Radius 2.5, Max Neighbors 8
Predictive Catch-Up off Weight 1, Prediction Time 0.35, Max Prediction Distance 6, Distance Prediction Factor 0
Orbit Style off Orbit Style Weight 0.75, Orbit Style Distance 4, Distance Tolerance 1, Orbit Direction Clockwise

The values under a behavior that ships off are what it starts with the moment you enable it.

Runtime blending

before the capthe sum runs past 1after the cappulled back onto the circlemore Approach weightit turns, it does not grow The dashed circle is length 1. Whatever comes out of it is multiplied by Max Speed.
What the clamp costs you, drawn out. Below the circle, raising a weight makes that behavior pull harder. Above it, the sum is already saturated, so a bigger weight only swings the result around toward that behavior. Past that point the useful control is lowering the others, not raising the one you want.

Behavior steering is additive: the manager combines all enabled contributions, clamps the result to unit length, smooths it through the movement profile, and multiplies by Max Speed.

Key points:

  • Disable, don't zero. Several behaviors cost query budget even when their weight is 0. Disable the behavior fully when you want it gone.
  • Weights are relative, and they saturate. A weight of 2 on Approach against 1 on Personal Space makes Approach pull twice as hard before the clamp. The combined steering is capped at unit length, though, so once the total reaches that cap raising one behavior's weight only turns the result toward it and pulls the others down. Past the cap a weight stops being independent. Tune in small steps and watch the whole mix, not one knob.
  • Agent Spacing Scale in SwarmSettings: 0 disables Personal Space entirely. Above 1 it widens the radius Orbit Style circles at, and it feeds body blocking and the dormancy check. It does not touch where Approach & Press stops: that standoff is built from the target's body radius, the agent's own radius and Combat Standoff, with no spacing scale in it.
  • Approach & Press uses a built-in LOD. When Use Out-of-Sight Fallback is on, agents outside Sight Distance fall back to lost-target leader following; with the toggle off (the default), every agent always pursues directly. Reduced and Cheap tier agents reuse cached steering, refreshed every N fixed steps (Approach And Press Reduced Interval / Cheap Interval in SwarmSettings).

Importance LOD and behavior cost

The LOD system (configured in SwarmSettings → Importance LOD) reduces behavior frequency for distant agents:

Tier Behavior cost
Full All behaviors run every step
Reduced Personal Space runs at reduced rate and with fewer samples. Approach & Press steering recomputed every N steps (cached between)
Cheap Personal Space even less frequent, further-reduced sample cap. Approach & Press steering recomputed even less often (cached between)

Reduced Quality Start Distance is the line where an agent drops out of Full, and Full Quality Agent Cap keeps the Full tier from spiking when a crowd converges on one target.

Cheap works differently, and this is the part that surprises people: Cheap Quality Start Distance is a requirement, not a trigger. An agent only goes Cheap once it is past that distance and off camera. Anything the gameplay camera can see stays at Reduced no matter how far away it is, and it holds that tier for Off Screen Quality Grace seconds after leaving the frame so agents at the edge do not flicker between tiers. Agents already in Reduced also have to clear Cheap Demotion Margin on top of the distance before they drop.

Within 12 units of its target 12 to 18 units Beyond 18 units On camera or within grace Off camera Full while the 96 cap has room Reduced Reduced Full while the 96 cap has room Reduced Cheap far and unseen Dormant agents are Cheap regardless of both axes. On-camera agents can still be promoted to Full if the 96 cap has room left over.
Distance runs one way, camera visibility the other. Cheap is the only one of the six cells that needs both conditions, which is why a visible agent 200 units out still pays the Reduced behavior cost.

Diagnosing behavior problems

When a behavior change has no visible effect, or an agent moves in an unexpected direction, use Swarm Debug (Tools > Massive Swarm System > Swarm Debug). It shows the live steering contribution from each behavior for one selected agent, and lets you isolate or mute individual behaviors without editing profile assets.

See Swarm Debug for the full reference.

Behavior sections