Collision groups & layers

Jolt filters collisions at three levels: broad-phase layers, object layers, and per-body collision groups. The first two are preset by this library; groups and sub-groups are yours.

Each <Physics> world sets up three object layers and maps them onto three broad-phase layers:

Layer and NUM_OBJECT_LAYERS are exported if you need the constants, but the tables themselves aren't configurable yet. Body layers follow from the type you give a <RigidBody>: static uses NON_MOVING, kinematic and dynamic use MOVING, rig uses RIG. (Layer.KINEMATIC is declared but nothing is assigned to it.)

Group filtering is the "this specific pair of objects shouldn't collide" filter. Object layers stay the broad category filter.

A group is a set of bodies that filter against each other; a subGroup is that body's id within the group. Two bodies consult the filter only when their group ids match — bodies in different groups, and bodies with no group at all, always collide normally. Within a group, every sub-group pair collides until you turn one off.

<RigidBody group={7} subGroup={1}>
    <mesh>
        <boxGeometry args={[5, 0.5, 8]} />
        <meshStandardMaterial color="#ff4060" />
    </mesh>
</RigidBody>

import { useJolt } from '@react-three/jolt';
import { useEffect } from 'react';

function Trapdoor() {
    const { bodySystem } = useJolt();

    useEffect(() => {
        // the platform (sub group 1) and the player (sub group 2) stop colliding
        bodySystem.disableCollision(1, 2);
        return () => bodySystem.enableCollision(1, 2);
    }, [bodySystem]);

    return null;
}

Both props are reactive — writing them after creation pushes a new CollisionGroup through BodyInterface.SetCollisionGroup and wakes the body, so the change takes effect on the next step. A body that never asked for a group gets one lazily the first time you set either. group={0} and subGroup={0} are real ids and are no longer swallowed by a truthy check. Setting a prop back to undefined does not clear the group.

The same thing on a BodyState:

body.group = 7;
body.subGroup = 2;
// `collisionGroup` / `collisionSubGroup` are aliases of the same pair
body.collisionSubGroup = 3;

Or, creating bodies by hand:

const handle = bodySystem.addBody(mesh, { group: 7, subGroup: 1 });
const body = bodySystem.getBody(handle);
if (body) body.subGroup = 2;

The table is a Jolt GroupFilterTable, built the first time a grouped body is created. Raise subGroupCount before that if you need more than 256 ids — the table is sized once:

bodySystem.subGroupCount = 1024;

Filtering a sub-group against itself (a === b) is also rejected with a warning: Jolt stores only the lower triangle of the table, so the (n, n) slot aliases a real pair's bit. Give every body in a group its own sub-group id instead of relying on it.

Every grouped body owns its own CollisionGroup, created with the body and destroyed when the body is removed — handles are recycled, so a stale group is never left behind. The filter table is reference counted and released by bodySystem.destroy(), which <Physics> calls for you on unmount.

A body with isSensor reports contacts but blocks nothing — orthogonal to groups, and the basis of trigger volumes and force fields.

<RigidBody isSensor>
    <mesh>
        <boxGeometry args={[4, 4, 4]} />
    </mesh>
</RigidBody>

Broad-phase layer filters, object-layer pair tables and per-cast body/shape filters exist in Jolt and are set to permissive defaults here. Queries do expose their filter objects (raycaster.bodyFilter, raycaster.objectFilter, …) if you are willing to work with raw Jolt — mind the ownership rules if you replace one.