Colliders & Shapes

A Collider gives an object physical form - one or more shapes that the simulation can hit, block against, or detect overlaps with.

Compound colliders - one body, many shapes

A Collider component holds a list of shapes, not a single shape. An object can carry several at once - for example a solid body shape plus a separate trigger volume, or several primitives that together approximate a complex form. This mirrors Unity's multiple-collider-components model. The primary shape (the first enabled one) drives the character-controller capsule and the legacy AABB fallback; the rest add collision geometry to the same body.

Each shape in the list is independently a different primitive, independently a trigger or solid, and independently toggleable.

The shape kinds

Every shape has a kind:

Kind	Fields used	Notes
box	center, size	size is half-extents (x, y, z) - a size of 0.5 is a 1-unit cube.
sphere	center, radius	A ball of the given radius.
capsule	center, radius, height	A pill along local Y. height is the total height including the rounded caps.
cylinder	center, radius, height	A cylinder along local Y. height is the total height.
mesh	center, mesh, convex	Collision from actual geometry - see below. center offsets it like any other shape.
shape2d	center	Sized by the object's Shape2D component: a ball for a circle, a rounded box (half a unit deep in Z) for a box or capsule. See 2D Games.

The Collider also carries four optional fields for the whole body: layer (0 to 15), collidesWith (a mask of layers), oneWay (pass through from below its local +Y) and friction (default 0.5). They are described on 2D Games, where they matter most, and work in 3D too.

Shared fields:

• center - the shape's local offset from the entity origin.
• size - box half-extents.
• radius - sphere / capsule / cylinder cross-section.
• height - capsule / cylinder total height along local Y.

Behind the scenes these map to engine ShapeDescs. Rapier's capsule halfHeight excludes the two hemispherical caps, so Awaken converts height to halfHeight = height/2 − radius; a cylinder's halfHeight is simply height/2. Radii and heights are floored to small positive values so a degenerate shape cannot crash the sim, and a capsule or cylinder total height is clamped to at least 2 x radius - it cannot be shorter than its own rounded ends.

A new shape defaults to a box with center (0,0,0), size (0.5, 0.5, 0.5), radius 0.5, and height 2.

Mesh colliders - convex hull vs exact triangles

A mesh collider builds collision geometry from real mesh data. The mesh field names a collision-mesh asset id, or "" to use the object's own render mesh. How the geometry is built depends on the body:

• Static + convex off → triangle mesh (trimesh). Collides against the exact triangles. Precise, but only valid on static (fixed) bodies - a trimesh is a hollow surface with no volume or mass, so it is unstable on a moving body.
• Dynamic, or convex on → convex hull. Wraps the geometry in a simplified convex shell that is safe on moving bodies. Turn on the convex flag to force this on a static object too.

Mesh vertices are pre-scaled by the object's Transform scale before the shape is built (static bodies bake their full world scale composed through parents; dynamic bodies use local scale), so the collision shape lines up with the rendered mesh. This shape builder (createMeshShapeFor in packages/runtime/src/physics/meshShape.ts) is shared by the editor's Play and the exported player, so mesh collision is identical in-editor and in a shipped game. A mesh shape whose geometry cannot be found builds as a box of the shape's size instead.

WARNING

A trimesh trigger doesn't reliably report overlaps - a hollow surface has no inside, so a body passing through never "intersects" it. Awaken automatically forces a mesh trigger to build as a convex hull instead, so a solid volume detects overlaps like a primitive sensor.

The trigger and pinned flags

Two per-shape flags change how a shape behaves:

• trigger (labelled trigger in the Inspector) - makes the shape a sensor. It detects overlaps and fires onCollision to the object's scripts, but does not physically block anything. Add a Script with onCollision / onCollisionEnter to react. See Raycasts, Triggers & Events.
• pinned (labelled static in the Inspector) - world-anchors the shape. By default a collider follows its Transform: a rotating door's blocking mesh swings with the door. A pinned shape is placed once at Play start and never re-posed, so it stays put even as its object moves. The classic use is a doorway trigger on a swinging door - the door mesh follows the door, but the pinned trigger stays in the opening instead of rotating off the player. Pinning is only meaningful on non-dynamic bodies (a dynamic body is wholly simulated, so pinned is ignored on it).

Each shape also has an enabled toggle - disable a shape to remove it from the sim without deleting it.

The Inspector collider editor

Select an object and, in the Inspector, the Collider component shows one editable block per shape:

• Enable toggle + kind picker - box / sphere / capsule / cylinder / mesh / shape2d.
• Fit - on a primitive, resizes and centres the shape to wrap the object's mesh, using the mesh bounds × the Transform scale (the physics body isn't scaled, so the shape is stored in world units). On a mesh shape, shifts the collision mesh onto the object's own mesh, which corrects an imported offset.
• × - removes the shape.
• Kind-specific fields - center for every kind (mesh included); size for a box; radius for sphere, capsule and cylinder; height for capsule and cylinder; a mesh picker for mesh.
• Mesh picker + auto (mesh only) - a searchable list of collision meshes ((render mesh) = the object's own mesh), plus an auto button that picks the closest-matching collision mesh by name and size. Switching a shape's kind to mesh also runs this auto-match and notes what it matched, so you aren't hunting through thousands of assets.
• Flags - convex (mesh only), trigger, and static (pinned).
• + Add collider shape - append another shape to the compound collider.

The Collider's own layer, collidesWith, oneWay and friction fields sit below the shape list.

When you first Add a Collider component from the "+ Add Component…" menu, Awaken automatically runs Fit so the default box wraps the object's mesh rather than sitting at unit size.

Editing a Collider (or RigidBody) during Play rebuilds the running simulation in place so the change takes effect immediately.

See also

• Inspector - where the collider editor lives.
• RigidBody - make the collider a moving body.
• Raycasts, Triggers & Events - react to trigger overlaps.
• Debug Overlays - see collider wireframes with F4.
• Colliders & Skeletons import - where imported collision meshes come from.
• 2D Games - Shape 2D colliders, layers, one-way platforms and 2D physics.