# collider

> Talos next · Since 0.6

Collision shape.

SIZING RULE. size, radius and height are in the entity's LOCAL units. The world extent is that dimension multiplied by transform.scale, so a collider scales with its entity exactly as the entity's mesh does. A 10 m wide floor is therefore either size [10, 0.2, 10] at scale [1, 1, 1], or size [1, 1, 1] at scale [10, 0.2, 10]. Writing the metre dimensions into BOTH squares them, giving a 100 m collider around a 10 m mesh. That is the authoring mistake this note exists to prevent, and it is not a rule the contract can catch, because both spellings are legal and only the author knows which was meant. The fixtures use the second spelling wherever the entity scales a unit-cube mesh, so the mesh and the collider are driven by one number.

Use it in a scene entity's `components` list as `{ "type": "collider", … }`. The contract writes the fields flat and refuses unknown keys.

## Fields

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `shape` | `ColliderShape` | yes |  | `box`, `sphere`, `capsule`, `trimesh`, `hulls` |  |
| `size` | `Vec3` | no |  |  | Full extent of a box collider along each local axis, before scale. Not a half-extent. |
| `radius` | `number` | no |  |  | Radius of a sphere or capsule, before scale. A scalar, so a non-uniform transform.scale on this entity is ill-defined; the contract does not reject it, but keep such entities at uniform scale. |
| `height` | `number` | no |  |  | Total height of a capsule along local Y, before scale. |
| `center` | `Vec3` | no | `[0,0,0]` |  | Offset of the collider's centre from the entity origin, in the entity's LOCAL units and before scale. Defaults to [0, 0, 0], and is multiplied by transform.scale exactly as size is. Needed whenever the mesh origin is not the shape's centre. A normalized asset has its origin at base-centre, so a 1.8 m capsule on such an entity needs center [0, 0.9, 0] to stand on the ground instead of sinking half-way into it. |
| `isTrigger` | `boolean` | no |  |  |  |
| `material` | `PhysicsMaterial` | no |  |  |  |
| `detail` | `PhysicsColliderDetail` | no |  | `exact`, `convex-hull`, `box` | What this trimesh collider is simulated as when its entity is a DYNAMIC body: its exact triangles, their convex hull, or their bounding box. Wins over the scene's meta.physics colliderDetail for this collider only; absent follows it. A static or kinematic trimesh is always exact, because the navmesh and the character controller are built from it, and a box, sphere or capsule has nothing to simplify: detail on any of those is ignored and reported as collider-detail-ignored (a warning). |

## Rules that can refuse it

- `collider-detail-ignored`
- `collider-material-invalid`
- `dynamic-needs-collider`
- `feel/action-out-of-reach`
- `feel/camera-clip`
- `missing-collider`
- `sensor-shape-unsupported`
- `spring-bone-unknown`
- `spring-collider-invalid`
- `terrain/entity-buried`
- `terrain/entity-floating`
- `tilemap-invalid`
- `transform-not-finite`
- `trigger-needs-trigger-collider`
- `vehicle-geometry`
- `vehicle-needs-dynamic-body`

## Example

From the contract's tested fixture `fixtures/contract/full20/scene.json#ramp`.

```json
{
  "type": "collider",
  "shape": "trimesh"
}
```