CompoundCollider (component)

One collision shape built from many box children, sharing a single broadphase volume and a single material.

When to reach for it

Situation	Use
A handful of shapes, each wanting its own material or trigger flag	Separate collider components on child entities
Many boxes sharing one material, such as a voxel chunk or a destructible wall	CompoundCollider

The difference is cost. Separate collider components are one broadphase entry each; a compound is one entry for the whole set, with contacts still resolved per child. That crossover is what makes a compound the right answer for a voxel chunk and the wrong one for a character's head.

Children

Each child is { offset = vec3, half = vec3 } in the entity's local space. The whole set scales with the entity's transform.

entity.find("chunk").component.add("CompoundCollider", {
    children = {
        { offset = { 0, 0, 0 }, half = { 0.5, 0.5, 0.5 } },
        { offset = { 1, 0, 0 }, half = { 0.5, 0.5, 0.5 } },
    },
})

Fields

Field	Meaning
children	The box set.
isTrigger	Report overlaps without blocking, for every child.
friction	Surface friction, shared by every child.
restitution	Bounciness, shared by every child.
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.