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 five 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 (n/a), mesh, convex	Collision from actual geometry - see below.

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 can't crash the sim.

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 is shared by the editor's Play and the exported player, so mesh collision is identical in-editor and in a shipped game.

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.
• Kind-specific fields - center and size for a box; radius/height for capsule and cylinder; a mesh picker for mesh.
• Fit (primitives only) - resizes and centres the shape to wrap the object's mesh, using the mesh bounds × the Transform scale. Because the physics body isn't scaled, the shape is stored in world units.
• 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, 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.

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.

📸 Screenshot - save as img/physics-collider-editor.png

The Inspector Collider component with two shape blocks: a capsule (solid) and a box flagged as a trigger, showing the kind picker, center/size fields, the Fit button, and the convex / trigger / static flag row.

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.