Skip to content

Colliders

Colliders make entities visible to collision detection and spatial queries. A collider needs Position and automatically requires CollisionLayer. Add RigidBody only when the built-in resolver should move or bounce the entity.

import { Define } from '@shell/ecs';
import { CircleCollider } from '@shell/physics';
import { Position } from '@shell/transform';
const CircleColliderPrefab = Define.prefab()
.with(Position, { x: 100, y: 100, z: 0 })
.with(CircleCollider, { radius: 16 });
commands.spawn(CircleColliderPrefab);
FieldTypeDefaultDescription
radiusnumber1Radius around its centre
offsetXnumber0Its centre’s distance right of Position; below 0, to the left
offsetYnumber0Its centre’s distance below Position; below 0, above it
const BoxColliderPrefab = Define.prefab()
.with(Position, { x: 200, y: 100, z: 0 })
.with(BoxCollider, { width: 64, height: 32 });
commands.spawn(BoxColliderPrefab);
FieldTypeDefaultDescription
widthnumber1Full width around its centre
heightnumber1Full height around its centre
offsetXnumber0Its centre’s distance right of Position; below 0, to the left
offsetYnumber0Its centre’s distance below Position; below 0, above it
oneWaybooleanfalseSolid only from above: see One-way platforms

Box colliders are axis-aligned. Rotation and pivot are not applied.

A collider’s shape is centred on its entity’s Position moved by offsetX and offsetY. A character’s feet box below its sprite is one entity:

const PlayerPrefab = Define.prefab()
.with(DynamicBody)
.with(Position, { x: 0, y: 0, z: 0 })
.with(BoxCollider, { width: 12, height: 6, offsetY: 13 });

The shape collides, is hit by raycasts and overlaps, and is drawn by physics debug where it is. Collision response still moves Position. Like the size, the offset does not turn or flip with the entity. A child entity does not place a shape: physics reads a child’s Position as a place in the world.

If an entity has both collider components, collision detection uses its circle collider.

CollisionLayer controls which colliders interact. Define layers as bit flags so masks can combine them:

export const Layers = {
Player: 1 << 0,
Enemy: 1 << 1,
World: 1 << 2,
Pickup: 1 << 3,
} as const;

Configure each entity with its own layer and the layers it accepts:

const PlayerColliderPrefab = Define.prefab()
.with(Position)
.with(CollisionLayer, {
layer: Layers.Player,
mask: Layers.Enemy | Layers.World | Layers.Pickup,
})
.with(CircleCollider, { radius: 16 });
const WallColliderPrefab = Define.prefab()
.with(Position)
.with(CollisionLayer, {
layer: Layers.World,
mask: Layers.Player | Layers.Enemy,
})
.with(BoxCollider, { width: 64, height: 32 });

Place a custom CollisionLayer before the collider in the prefab definition. This makes the intended layer data explicit instead of relying on the default supplied by the collider requirement.

Normal collision detection is mutual. Both expressions must match:

(player.mask & wall.layer) !== 0;
(wall.mask & player.layer) !== 0;

Adding CircleCollider or BoxCollider automatically adds CollisionLayer with both fields set to 1 when it is missing.

A Project names its layers once, in the Layers list of its physics settings (PhysicsSettings, physics:settings). Each layer is a name and its bit: bit N is the layer 1 << (N - 1), up to 32 layers. A new layer takes the lowest free bit, and removing one leaves its gap, so the other layers and every mask keep their meaning. A bit no layer has is unnamed. The physics works on bits and never reads the names.

Keep your constants in the same order as the bits, or ask for a bit by its name:

import { layerBit, layerNames } from '@shell/physics';
// 1 << 1 where Enemy's bit is 2. A system passes its `resources` in place of the world.
const enemy = layerBit(world, 'Enemy');
// All 32 names by bit, '' for an unnamed layer.
const names = layerNames(world);

layerBit throws for a name that is not in the asset, so a typo is never a silent 0.

A collider with trigger on notices what it touches and pushes nothing: it is never pushed, and nothing is pushed out of it. Its contacts come in the three collision events, each marked trigger. Use it for zones, pickups and hit areas:

const PickupPrefab = Define.prefab()
.with(Position, { x: 250, y: 100, z: 0 })
.with(CollisionLayer, {
layer: Layers.Pickup,
mask: Layers.Player,
})
.with(CircleCollider, { radius: 10, trigger: true });
const pickup = world.get('commands').spawn(PickupPrefab).root;

A trigger may sit on a body or on a child under one, and moves with it. A trigger with no body notices only what moves: two colliders that do not move never meet.

A collider’s body is the nearest RigidBody on its own entity or up its parents. A collider on a child with no RigidBody of its own is a part of its parent’s body: it is pushed with it, and two colliders of one body never meet. A child with a RigidBody of its own is its own body.

A collider with no body, on its own entity or above it, is a static wall: solid, in the static index, as a static body’s collider is. A wall or a floor needs no RigidBody; a zone that only notices needs trigger.

The built-in resolver handles each contact between two colliders by their bodies: it moves each body’s Position and Velocity, and a collider with no body is a wall that does not move, with friction and bounce 0. Every dynamic body also needs Velocity. A contact with a trigger is left alone.

Response includes:

  • Impulses along the collision normal
  • Restitution using the higher restitution of the two bodies: a bouncy body bounces off one with none
  • Friction along the surface of contact, using the lower friction of the two bodies
  • Positional correction to reduce overlap
  • Several passes over the step’s contacts, so the weight of a stack reaches its floor and the stack stands: world.get('physicsContacts').iterations, 8 unless the Project’s physics settings (Contact passes) or a system set it, a whole number from 1 to 64 (fewer cost less each step; any other value throws)
  • Infinite effective mass for static and kinematic bodies

Collision response does not generate angular impulses, and boxes remain axis-aligned even when Rotation.z is integrated. The resolver is suited to simple push-apart behavior rather than a full constraint-based simulation.

RigidBody.friction slows how fast two bodies in contact slide along each other. In each fixed step the resolver removes as much of that sliding speed as would stop the slide, but never more than friction times the impulse that pushes the two bodies apart in that step. Friction therefore stops a slide and never reverses it, and a harder push together allows more of it.

A body lying on a floor is pushed into it by gravity, so its speed along the floor falls by friction × gravity every second until it rests. With gravity 500 and a friction of 0.5, a box pushed at 250 units per second stops after one second, whatever its mass:

import { Define } from '@shell/ecs';
import {
BodyType,
BoxCollider,
DynamicBody,
RigidBody,
StaticBody,
Velocity,
} from '@shell/physics';
import { Position } from '@shell/transform';
const FloorPrefab = Define.prefab()
.with(StaticBody)
.with(Position, { x: 400, y: 316, z: 0 })
.with(RigidBody, { type: BodyType.Static, friction: 0.5 })
.with(BoxCollider, { width: 800, height: 32 });
const CratePrefab = Define.prefab()
.with(DynamicBody)
.with(Position, { x: 100, y: 284, z: 0 })
.with(RigidBody, { friction: 0.5 })
.with(Velocity, { x: 250, y: 0, z: 0 })
.with(BoxCollider, { width: 32, height: 32 });

Each contact uses the lower friction of its two bodies (restitution takes the higher). The default is 0: a body with no friction slides freely on everything, whatever the other body’s value, and a scene that never sets the field has no friction in it. Both bodies need a value above 0 for a contact to have friction, so give one to the floor as well as to what lies on it.

Earlier versions stored friction and did not apply it. A value set back then did nothing and acts now, wherever both bodies of a contact have one, so look through scenes and prefabs made before for a friction that is not 0.

  • Friction acts on the speed of one body relative to the other. A body lying on a moving kinematic platform is carried along with it.
  • Friction needs the two bodies to be pushed together. Without gravity, as in a top-down game, a body that slides along a wall is slowed only as far as it also moves into the wall, and a body that touches nothing is not slowed at all. Use linearDamping for drag that does not depend on a contact.
  • Friction does not rotate anything. A circle does not roll: it slides to rest as a box does.
  • A floor built from several static boxes has seams, and a box that slides over them can be stopped dead at any of them, with friction or without: a box is pushed out of another box along the smaller overlap, which is sideways for a tile it has only just reached. A circle is not stopped there, but loses some speed at each seam. Where bodies slide, make the floor one wide box.
  • A body held by friction against a force too weak to move it does not stay exactly still. Positions are integrated before contacts are resolved, so it creeps at that force’s acceleration times the length of a fixed step: pushed with an acceleration of 60, it moves about one unit each second at the default 60 steps per second.

A box with oneWay is solid only from above. y grows down, so its top is the edge with the smallest y:

const PlatformPrefab = Define.prefab()
.with(StaticBody)
.with(Position, { x: 400, y: 300, z: 0 })
.with(BoxCollider, { width: 128, height: 16, oneWay: true });
  • A body coming down onto its top lands and stands there, as on any static box. A circle stands on it while its centre is over it.
  • A body going up through it, or walking into its side, passes. It is not pushed, and no collision event names the two.
  • A body that jumped half-way into it and falls back passes down through.
  • The push is always straight up, so a body walks along a row of touching one-way boxes without snagging at their seams. Touching one-way boxes are sealed to each other only, and a solid box beside one keeps its side.
  • It works on static and kinematic boxes. A kinematic one is seen rising or falling through its Velocity. One moved some other way, by a clip or a tween, still holds what stands on it.
  • Two one-way boxes never collide. Raycasts and overlaps hit a one-way box from any side, as any box.
  • A fast fall lands too. A dynamic body that moves farther in one fixed step than its own size (a circle’s width, a box’s smaller side) is swept: it is cast from where it was along its move against the static colliders, solid and one-way, and stops at the first it meets, where the step’s contacts take it with its bounce; one it starts the step touching, moving into it, too. A one-way box stops only what comes down onto its top. Nothing is set for it. Its limits: it meets only the static colliders there at the end of the last step, so one spawned this step is met from the next; one the body already overlaps at the start of the step is left to the contacts, so a fast body already inside a thin collider can still cross it; and two moving bodies are not swept against each other, so two fast bodies can still pass through one another.

Put platforms on a collision layer of their own, and take that bit off a body’s mask for a moment:

export const Layers = { World: 1 << 0, Platforms: 1 << 1 } as const;
// A platform: .with(CollisionLayer, { layer: Layers.Platforms, mask: Layers.World })
// The player: .with(CollisionLayer, { layer: Layers.World, mask: Layers.World | Layers.Platforms })
const collision = player.getComponent(CollisionLayer)!;
collision.mask &= ~Layers.Platforms; // it falls through
// A quarter of a second later:
collision.mask |= Layers.Platforms;

The body is not caught when the bit comes back while it is still inside the platform, since it is not coming down onto the top.

During each fixed step, CollisionSystem:

  1. Rebuilds the spatial index from current collider and position data.
  2. Filters candidate pairs using collision layers.
  3. Tests circle-circle, circle-box, and box-box intersections.
  4. Emits collision lifecycle events.

CollisionResolverSystem then consumes active contacts and applies response. Systems that need current collision data should run after PhysicsSet.Collide in Schedule.FixedPostUpdate.

const GameplayCollisionSystem = Define.system()
.after(PhysicsSet.Collide)
.update(({ events }) => {
// Read collision events here.
});

See Collision Events for contact payloads and event handling.