Colliders

A collider is the invisible shape the physics engine uses for collision detection. It does not need to match the visual mesh exactly — in fact, using a simpler shape is almost always better for performance.

Collider shapes

In Inspector → Physics → Collider Shape, choose one of:

Shape	Icon	Best use
Box	□	Crates, buildings, flat floors, any roughly rectangular object
Sphere	○	Balls, rounded objects, fast-moving projectiles
Capsule	⌓	Characters, humanoid objects, pillars
Cylinder	⌀	Barrels, columns, wheels
Convex Hull	◇	Complex shapes that are roughly convex; automatically generated from the mesh
Mesh	▲	Exact collision with complex concave geometry; highest accuracy, highest cost

Choosing the right shape

Start with Box or Sphere — they have the lowest CPU cost.
Use Capsule for characters — it avoids getting stuck on edges.
Use Convex Hull for props where a box is too imprecise.
Reserve Mesh colliders for static terrain, walls, and background geometry. Never use Mesh for dynamic bodies — it is not supported and falls back to Convex Hull.

Collider sizing and offset

After selecting a shape, you can fine-tune its size and position relative to the object:

Size — X, Y, Z dimensions (Box and Cylinder), or Radius + Height (Sphere, Capsule).
Center Offset — shift the collider relative to the object's pivot point.
Rotation Offset — rotate the collider relative to the object.

Enable Show Collider in the Physics section to visualise the collision shape as a green wireframe in the Viewport.

Compound colliders

Complex objects often need multiple simple colliders working together — for example, a chair has four legs and a seat, each best represented by a box.

Select the object.
Inspector → Physics → Add Collider (adds a second collider component).
Repeat for each part — size and position each independently.

All colliders on the same object act as one compound shape.

Triggers

A Trigger is a collider that detects when other objects overlap it, but does not physically push them. Use triggers for:

Detecting when a player enters a zone
Activating events when an object passes a line
Counting objects that pass through a point

Enable trigger mode: Inspector → Physics → Is Trigger.

When an object enters or exits a trigger, events fire in your scripts:

import { on } from '@shapebox/api'

on('triggerEnter', (other) => {
  console.log(other.name, 'entered the trigger!')
})

on('triggerExit', (other) => {
  console.log(other.name, 'left the trigger.')
})

Collision layers

Collision layers let you control which objects can collide with which others — for example, making projectiles ignore each other and only hit enemies or the environment.

Configure layers in Editor → Project Settings → Physics → Collision Matrix:

Create named layers (e.g. Player, Enemy, Environment, Projectile).
Assign objects to a layer: Inspector → Physics → Layer.
In the Collision Matrix, uncheck pairs that should not collide.

Collision events in scripts

import { on } from '@shapebox/api'

on('collisionEnter', (other, contact) => {
  console.log('Hit', other.name, 'at', contact.point)
  console.log('Impact strength:', contact.impulse)
})

on('collisionStay', (other) => {
  // Fires every frame while two objects remain in contact
})

on('collisionExit', (other) => {
  console.log('Separated from', other.name)
})

Performance tips

Prefer Box, Sphere, or Capsule over Mesh for dynamic objects.
Use Mesh collider only on Static body type objects.
Avoid very small dynamic objects — they require high-frequency CCD and are physics-expensive.
Group static geometry into a single object with a single Mesh collider where possible.
Use collision layers to skip unnecessary collision checks between large groups of objects.