BoxCollider (component)

A box collision shape. Works with or without a Physics component: on its own it is static collision geometry, and alongside one it moves with the body.

Sizing

half is the box's half-extents in the entity's local space, multiplied by the entity's world scale. Leave it unset and the box derives from the entity's model bounds, so a bare BoxCollider matches what is rendered at any scale, and follows the mesh when renderer.mesh.setVertices or renderer.mesh.update changes it: by the next physics step the box takes the new geometry's size and centre.

entity.find("crate").component.add("BoxCollider", {})                     -- fits the mesh
entity.find("wall").component.add("BoxCollider", { half = { 2, 4, 0.2 } }) -- authored

Fields

Field	Meaning
half	Half-extents. Unset derives from model bounds.
isTrigger	Report overlaps without blocking.
friction	Surface friction.
restitution	Bounciness.
rollingResistance	How strongly the surface resists a body rolling on it: a rolling body slows at this many times gravity on level ground, so a ball rolled at v stops after v^2 / (2 * rollingResistance * 9.81). 0 rolls on.
spinningResistance	The same for a body spinning on the surface about the contact normal. 0 spins on.
surface	The surface the collider is made of, by name: one Physics.defineSurface defined gives it its friction, restitution and resistances in place of the fields above, and contacts, contact events and ray and shape casts report the name either way. Empty names none.
oneWay	The direction, in the collider's own frame, bodies pass through it along: a body moving that way goes through, and a body meeting it from the side the direction points to stands on it (a jump-through platform is {0, 1, 0}). Physics.passThrough(entity) drops a standing body through. Unset blocks from every side.
surfaceVelocity	The velocity, m/s in the collider's own frame, its surface moves at along itself while the collider stays put: friction carries what rests on it (a conveyor belt, a treadmill, an escalator). Write it at runtime to change the speed or direction. Unset holds the surface still.
contactTag	The tag the world's contact filter reads this collider by: Physics.setContactFilter(tagA, tagB, mode) makes two tags pass through each other ("ignore"), report contacts and push nothing ("sensor") or collide ("solid"). Empty names none.

Composing

A collider on a child entity attaches to the nearest ancestor carrying a Physics component, so a body made of several shapes puts each on its own entity and each keeps its own material and trigger flag.

Past a few dozen boxes sharing one material, CompoundCollider is cheaper: it is a single broadphase volume where separate components are one each.