collider
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-ignoredcollider-material-invaliddynamic-needs-colliderfeel/action-out-of-reachfeel/camera-clipmissing-collidersensor-shape-unsupportedspring-bone-unknownspring-collider-invalidterrain/entity-buriedterrain/entity-floatingtilemap-invalidtransform-not-finitetrigger-needs-trigger-collidervehicle-geometryvehicle-needs-dynamic-body
Example
From the contract's tested fixture fixtures/contract/full20/scene.json#ramp.
{
"type": "collider",
"shape": "trimesh"
}