Skip to content

Physics & Colliders

Agents are simulation data, not physics bodies. Each one carries a single query collider so your raycasts, bullets and triggers can find it, and the swarm reads your own colliders only through a few layer masks. Read this page when a wall, a Rigidbody, a player or a trigger volume does not react to the swarm the way you expected.

How the swarm sees your scene

The swarm moves agents itself, once per fixed step, and writes the result onto pooled agent GameObjects. No Rigidbody is ever added to an agent, so Unity's physics engine never moves one. What the swarm does read from your scene is a short list of layer masks:

Setting Where What it reads
Obstacle Layer Mask SwarmSettings, Obstacle Blocking Colliders agents are pushed back out of. With Surface Flow on, the Walkable and Unwalkable layers are removed from it (see Static walls and floors).
Walkable Layer Mask and Unwalkable Layer Mask SwarmManager, Surface Flow The geometry the Surface Flow bake stands agents on and routes around.
Ground Layer Mask SwarmSettings, Grounding What agents stand on.
Target Mask, Projectile Collision Mask Weapon components What a shot may damage, and what stops it.

The physics collision matrix (Project Settings, Physics) is not on that list. The swarm's own queries test masks directly and ignore it. The matrix still decides what your Rigidbodies and your Character Controller bump into, and that includes agent colliders. Most of the surprises on this page come from that split.

What do you have?

You have What to do Section
A wall or floor that never moves Put its layer in the right mask for your navigation setup Static walls and floors
A collider your script or an animation moves Swarm Flow Modifier in a Surface Flow scene Moving obstacles
A Rigidbody prop the player or physics shoves Rigidbody, Swarm Flow Modifier and Swarm Pushable Rigidbody props
A door or barricade agents break Swarm Flow Modifier and Swarm Breakable Doors and Barricades
A Character Controller player Keep it off the agents' backs The player
A Rigidbody player Same layer-pair rule as a prop The player
A raycast, bullet or overlap query Include the agent layer in your mask Hitting agents
A trigger volume that should detect agents The scene object needs the Rigidbody Hitting agents
Agents on slopes, steps or in the air Grounding settings Ground, slopes and steps
A 2D game Not covered What is not covered

Static walls and floors

Without Surface Flow, put the layer your wall colliders are on into Obstacle Layer Mask on the SwarmSettings asset. Each agent then tests a capsule covering the path it travelled since its last check, and is pushed back out toward the side it came from. That directional push is what holds a packed crowd behind a thin wall. Obstacle Blocking Query Interval sets how many fixed steps pass between checks, though an agent that Hard Agent Separation or the dormant spacing pass just moved is checked again in the same step. Also, trigger colliders are ignored unless Obstacle Query Trigger Interaction says otherwise.

With Surface Flow on, the manager removes the Walkable and Unwalkable layers from that mask before it queries. The baked cells already keep agents off walls, and two containments with different resting positions make pressed bodies flicker. The result is the read-only Effective Obstacle Layer Mask on SwarmManager. So a wall on an Unwalkable layer is held by the cell boundary, not by physics, and adding its layer to Obstacle Layer Mask changes nothing. Obstacle blocking in a Surface Flow scene is for things on layers outside both masks.

Obstacle blocking skips three kinds of collider, whatever their layer:

  • Any collider under an agent prefab.
  • Colliders belonging to a registered SwarmTarget. Target Body Blocking holds agents off a target instead.
  • Colliders under a SwarmPushable.

Two more details explain behavior that looks odd. The collider an agent is standing on is exempt while its top is within the agent's step height. And with grounding on, an obstacle whose top is within Max Step Height above the agent's feet is stepped onto instead of blocking it.

Walls and floors share Default out of the box

The default settings asset and the sample assets ship with Obstacle and Ground both set to Default only, except the Sandbox asset, which puts Obstacle on layer 8. Default only works for a first scene. A Rigidbody prop you add on Default is then an obstacle too, and it moves, so read Moving obstacles before relying on that.

Moving obstacles

A moving collider on a layer in Obstacle Layer Mask keeps agents out, with brief overlap at its leading edge. The baked Surface Flow field does not know about it, so routes do not bend around it.

The overlap is shallow and short, and it is not a guarantee: an agent's center can sit just inside the collider for a few steps as it arrives. Leave the collider's layer out of Obstacle Layer Mask and nothing pushes agents back, so they end up inside it far more often and deeper.

In a Surface Flow scene, the supported route for something that moves is a Swarm Flow Modifier on it, sized to its footprint. The modifier follows the object and restamps its cells once it has moved past Move Threshold. Those cells trail the object and are a cell coarse. Doors and Barricades has the fields.

A Swarm Flow Modifier stamps nothing without Surface Flow Field Navigation on the SwarmManager.

Rigidbody props the crowd pushes back on

Put a Rigidbody and a collider on a crate, shove it into a crowd, and nothing says the crowd should react. Agents ignore any object the swarm has not been told about, and agent colliders are static colliders as far as Unity's physics is concerned. What happens next depends on your layer collision matrix and on what you add to the object.

Setup Agents The body
Layer pair off in the matrix, or agent colliders set to trigger Not affected. Their centers end up inside the body. Passes through at its own speed.
Layer pair on, agent colliders solid Not affected. They do not slow, give way or get pushed. Stops as if against a wall, and is carried back by agents walking into it.
Rigidbody, Swarm Flow Modifier and Swarm Pushable Move aside, and push back with Force Per Agent. Slowed or held by the crowd.

The first two rows were measured in Zombie City, with a force-driven box sent through a cluster of agents:

  • Pair off (Default against the agent layer, as Configure Demo Project sets it): the box travelled the full distance at its free speed, and agent centers were inside it for much of the way.
  • Pair on (Player against the agent layer): the box stopped almost at once and stayed stopped, and the agents carried it backward. Agent centers were inside it only in the first frames, where the box had been spawned onto agents.

Unity ships every layer pair on, so a project that never changed its matrix starts in the second case. The first row's trigger case follows from Unity's own rule that a trigger never blocks a body.

Putting the prop's layer in Obstacle Layer Mask does not rescue the first row in a Surface Flow scene when that layer is also the floor's. The two Surface Flow masks are removed from obstacle blocking, so a prop left on a Walkable layer stays invisible to the swarm.

Making a prop push back

  1. Add a non-kinematic Rigidbody.
  2. Add a Swarm Flow Modifier sized to the object, with Blocks Agents on. Set Route to Free if the crowd should shove the prop instead of detouring around it.
  3. Add a Swarm Pushable. The Flow Modifier inspector warns and offers an Add Swarm Pushable button when Blocks Agents is on and it finds a non-kinematic Rigidbody without one.
  4. Drive the prop with a force. Setting its velocity directly overrides what the crowd adds.
  5. Give the prop a layer that still collides with your walls and floor, or a shoved prop passes through the wall it was pushed into. Zombie City's bins sit on Default, which collides with the Obstacle and Low Obstacle layers once you run Configure Demo Project.

The Flow Modifier closes the cells under the prop, so routes treat it as blocked. Those cells trail the prop and are a cell coarse, which is why the Swarm Pushable adds the exact box on top: each step, an agent inside the box is moved out of it, by at most its own radius and never into a wall. An agent with a wall behind it stays where it is and only pushes back. Each pressing agent adds Force Per Agent, capped by Max Crowd Force. The prop's own collider stops mattering to agents, so its layer only has to work for your walls and floor. A kinematic Rigidbody receives no push. All three components need Surface Flow on. Without it no Swarm component makes a prop push back, and adding them makes things worse: obstacle blocking skips a Swarm Pushable's colliders, so a prop that Obstacle Layer Mask was holding agents off stops blocking them.

In Zombie City, agents leaning on a bin push back against the player. A few slow it down and a crowd stops it. How many it takes depends on the player's Push Force, the bin's mass and Force Per Agent. Doors and Barricades lists the two Pushable fields.

For a hazard that moves on its own and never gets slowed, such as a vehicle on a path, see Moving obstacles.

The player

A Character Controller

An agent's collider is sized from Agent Radius and seated at the agent's feet, so a large radius makes a tall body: a radius of 0.95 is a body almost two units tall. Agent transforms are written every frame, which teleports the collider instead of sweeping it, so one can appear already inside your player's capsule. A Character Controller answers an overlap by pushing the capsule out the shortest way, and inside a ring of bodies that is up. Step Offset is never consulted, which is why lowering it does not help.

Two ways to stop the engine resolving that overlap:

  • Exclude Layers on the Character Controller, set to the agent layer. This is scoped to one character and leaves your collision matrix alone.
  • Agent Collider Is Trigger on SwarmSettings, which makes every agent query collider a trigger for every character at once.

Either removes the physical resistance, so the player would walk through the crowd. Put it back in your own move code. This is per-character wiring, not something the package does for you. Gather nearby agent bodies with Physics.OverlapCapsule on the agent layer, then move the player out of each one with the vertical component set to zero. Overlap queries take an explicit layer mask and ignore Exclude Layers, so they still see the bodies the controller skips. Working only on the horizontal plane is what makes the climb impossible instead of merely unlikely.

DemoPlayerController in the Full Demo has this recipe built in, as SeparateFromAgents. It is written for the Exclude Layers route: its overlap query ignores triggers, so it finds no bodies when Agent Collider Is Trigger is on. Agent Separation Mask and Agent Separation Capacity configure the overlap query. Ground Mask decides which contact counts as real footing, so leave the agent layer out of it or a packed crowd reads as floor. Slide Off Speed is how fast the player slides off a body that does not qualify. The component also has a Swarm Blocking group: Use Swarm Crowd Blocking, Crowd Blocking Radius, Crowd Blocking Strength and Crowd Push Speed. Those read the swarm's crowd readout, and they do nothing while Enable Target Crowd Blocking is off on SwarmSettings, which is how every sample ships. Turn that setting on before tuning them.

Copying the separation code needs the mask set

m_agentSeparationMask has no initializer, so it starts as Nothing, and SeparateFromAgents returns at once while the mask is empty. No error, no warning: the player still climbs. Ground Mask has the opposite default. It starts as Everything, so the agent layer counts as footing until you uncheck it.

A Rigidbody player

A Rigidbody player meets agent colliders by the same layer-pair rule as a prop, in the table above. A registered SwarmTarget's colliders are skipped by obstacle blocking and by grounding, so the swarm never treats the player as a wall or as ground. Target Body Blocking keeps agents out of the target's radius using position alone, with no collider involved.

Hitting agents

Every agent has exactly one query collider on its root GameObject. If the prefab root already has a collider, the swarm uses it. Otherwise it adds a sphere, or a capsule when the renderer is tall. There is no setting to turn that off.

The swarm overwrites the root collider

On every spawn, the root collider's trigger flag is set from Agent Collider Is Trigger. A sphere gets its radius and center from Agent Radius. A capsule gets that radius, is stood upright, is made at least twice the radius tall and is centered at half its height. A sphere or capsule hitbox you authored on the root is therefore resized. Any other root collider type, such as a Box or Mesh, keeps its shape and only gets the trigger flag. Colliders on children keep their authored shape and flags, and are also treated as agent colliders, so obstacle blocking and grounding skip them.

Solid or trigger. Agent Collider Is Trigger is off by default. Solid colliders are what Unity's physics sees as obstacles. Triggers stay findable by queries while physics ignores them. A trigger raises OnTriggerEnter and a solid collider raises OnCollisionEnter, and neither fires unless the other object brings a Rigidbody. If agents are triggers, your own queries need a trigger interaction that includes them.

Raycasts, overlaps and bullets. Include the agent layer in your mask. A hit gives you the collider, and GetComponentInParent<SwarmAgent>() gets you the agent visual. The shipped weapons find the IDamageable the same way, walking up from the hit collider. Keep a SwarmAgent.Handle if you need the agent later, because the visual is pooled and reused. SwarmAgent has the API.

Which position you mean. The agent's drawn body, and the collider riding on it, does not sit exactly on the simulation position. Visual Interpolation offsets it by up to one fixed step of movement, and Render Smoothing adds more once a crowd packs in. The gap is a fraction of a unit for a typical agent and can reach several units in a tightly packed crowd. That gap is deliberate, so raycasts and collider queries hit what the player sees. The swarm's own attacks always use the simulation position. If your hit detection goes through the collider, it already agrees with the screen. If it works from positions (distance checks, melee reach, server validation), read the true position through SwarmManager or a SwarmAgentHandle. Do not mix the two on one hit.

Triggers on scene objects. Agent colliders have no Rigidbody, so two static colliders never talk. The scene object that should detect agents brings a kinematic Rigidbody. The knockback recipe is a working example, and TouchDamageSource builds the same rig for itself.

Swarm damage to your targets does not depend on any of this. It comes from the target registry, so the collision matrix never decides who gets hurt.

Ground, slopes and steps

Grounding sends a sphere cast down from just above each agent against Ground Layer Mask and stands the agent on the best qualifying hit.

Setting Effect
Ground Layer Mask Which layers count as ground. If it misses your floor, agents fall through it.
Max Ground Slope Angle Steepest surface an agent stands on.
Max Step Height Tallest ledge an agent steps up onto. Anything higher blocks it.
Surface Flow Grounding Mode In a Surface Flow scene, whether the baked cell height replaces or supplements the physics probe.
Enable Grounding Off for flying or flat top-down agents. They keep the Y they spawned at, unless a Surface Flow grounding mode sets their height from the field.

Registered target colliders, SwarmPushable colliders and agent colliders never count as ground. Allow Agent Colliders As Ground is the experimental exception for agents that stack. The full field list is on Swarm Settings, and Navigation covers the Surface Flow modes.

Timing

The swarm simulates in the manager's FixedUpdate. At initialize it also writes Time.fixedDeltaTime and Time.maximumDeltaTime from Fixed Timestep and Maximum Allowed Timestep, unless Apply Fixed Timestep On Initialize is off. That is a project-wide change, so every Rigidbody in your project steps at the swarm's rate. A Character Controller is not affected: it moves when your script calls Move. Turn the toggle off if you manage the Time Manager yourself.

A SwarmPushable applies its force in its own FixedUpdate, which is why a force-driven prop and the crowd's push combine and a velocity you set does not. The fixed update does not run at a time scale of zero, so the swarm pauses with it. The runtime never calls Physics.Simulate itself.

What is not covered

  • 2D. The runtime uses only 3D physics (Physics, Collider), and the simulation works on the XZ plane. Collider2D and Rigidbody2D objects are invisible to it, and SwarmTarget measures only 3D colliders and a Character Controller.
  • A Rigidbody on the agent prefab. The swarm writes each agent's transform itself, so a Rigidbody there would fight it. Leave it off.