RigidBody

<RigidBody> wraps three.js objects, builds a Jolt shape from their geometry, creates the body, and keeps the two in sync every frame.

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

<RigidBody position={[0, 1, 0]}>
    <mesh>
        <boxGeometry args={[1, 1, 1]} />
        <meshStandardMaterial color="green" />
    </mesh>
</RigidBody>;

Children render inside an <object3D> the body drives. Anything non-visual (lights, groups, your own components) can live in there too; only meshes contribute to the collision shape.

To place the collision shape yourself — a trigger volume with no mesh, a cheap primitive standing in for a detailed model, several pieces making up one body — use the named collider components and <RigidBody colliders>. See Colliders.

Event props — onCollisionEnter, onCollisionPersist, onCollisionExit, onSensorEnter, onSensorExit, onSleep, onWake, onContactValidate (and the onIntersectionEnter / onIntersectionExit aliases) — have a section of their own.

<RigidBody
    type="dynamic"
    shape="box"
    position={[0, 5, 0]}
    rotation={[0, Math.PI / 4, 0]}
    mass={10}
    linearDamping={0.05}
    angularDamping={0.05}
    group={0}
    subGroup={1}
    dof={{ x: true, y: true, z: true, rotX: false, rotY: true, rotZ: false }}
    onCollisionEnter={(e) => console.log(e.other.handle, e.normal)}
>
    <mesh>
        <boxGeometry args={[1, 1, 1]} />
        <meshStandardMaterial color="teal" />
    </mesh>
</RigidBody>

<RigidBody ref> gives you the BodyState for that body, once it exists.

import { BodyState, RigidBody } from '@react-three/jolt';
import { useEffect, useRef } from 'react';
import * as THREE from 'three';

export function Ball() {
    const body = useRef<BodyState>(null);

    useEffect(() => {
        body.current?.addImpulse(new THREE.Vector3(0, 40, 0));
    }, []);

    return (
        <RigidBody ref={body} position={[0, 10, 0]} shape="sphere">
            <mesh>
                <sphereGeometry args={[1, 32, 32]} />
                <meshStandardMaterial color="orange" />
            </mesh>
        </RigidBody>
    );
}

The ref prop is currently typed any, so TypeScript does not check it: useRef<BodyState>(null) compiles, but so does useRef<HTMLDivElement>(null). You are annotating, not verifying. The ref is also null until the body is created — which happens in an effect, and waits for child <Shape> components if there are any — so always guard with ?..

Tracked in #160, along with doc comments for every BodyState member.

Every body is also reachable through the body system:

import { BodyState, useJolt } from '@react-three/jolt';
import { useEffect } from 'react';
import * as THREE from 'three';

function Nudge({ handle }: { handle: number }) {
    const { bodySystem } = useJolt();

    useEffect(() => {
        const body = bodySystem.getBody(handle);
        if (body) body.position = new THREE.Vector3(0, 3, 2);

        bodySystem.dynamicBodies.forEach((state: BodyState) => {
            state.addImpulse(new THREE.Vector3(0, 2, 1));
        });
    }, [bodySystem, handle]);

    return null;
}

bodySystem holds dynamicBodies, staticBodies and kinematicBodies as Map<number, BodyState>, keyed by handle; getBody(handle) searches all three. A handle is Jolt's BodyID.GetIndexAndSequenceNumber(), and Jolt recycles them — don't hold one across a body's lifetime.

One object per body. Everything on it speaks three.js types; the Jolt side is an implementation detail.

const position = useRef(new THREE.Vector3());
const rotation = useRef(new THREE.Quaternion());

useFrame(() => {
    body.current?.readPose(position.current, rotation.current);
});

The position/rotation getters allocate a new three.js object each read — fine for effects, avoid in a per-frame loop, where readPose exists.

A kinematic body is moved by you and pushes everything it touches. Drive it with a target pose, never by writing position — that teleports, and a teleport carries nothing with it.

const platform = useRef<BodyState>(null);

useFrame((state) => {
    // the step loop re-aims this every substep with that substep's real dt
    platform.current?.setKinematicTarget([Math.sin(state.elapsed) * 5, 2, 0]);
});

setKinematicTarget is the one to reach for: the target is sticky and re-applied at the top of every substep, so the body converges on it whatever the frame rate, and a body that has arrived simply parks there. moveKinematic(position, rotation?, deltaTime?) is the one-shot version — it applies once, with deltaTime defaulting to the world's step length (physicsSystem.timeStep, or the last frame delta when the world steps with timeStep="vary").

Leaving rotation out keeps the body's current rotation in both.

Riders are carried because MoveKinematic gives the platform a real velocity, which is what wakes the sleeping bodies resting on it — this works with stock body settings. Two things are still worth tuning for a demo that has to feel solid:

position/setPosition, rotation/setRotation and setPositionAndRotation work on every motion type, including static bodies (issue #61) — SetPosition/SetRotation update the broadphase regardless of motion type, and the three.js object is brought along by a small "dirty statics" drain in PhysicsSystem.onUpdate, since the frame loop otherwise only walks bodies that can be awake (dynamic/kinematic).

// fine: an occasional reposition of scenery
wall.current!.position = new THREE.Vector3(4, 0, 0);

It is a teleport, not simulation, whatever the motion type — the same reason resetPoseCache() is called for you on every write. For a static body specifically that means:

Moving a static body every frame is an anti-pattern for exactly those reasons: it looks like motion but has none of its physical consequences. Reach for type="kinematic" with setKinematicTarget (or moveKinematic) for anything that moves repeatedly — statics are for the occasional reposition of scenery (moving a platform into place at level start, snapping a door open). activateOnChange has no effect either way: a static body never activates, since a static is never simulated.

Setters that can move a body (position, rotation, velocity, angularVelocity, scale, group, subGroup) used to wake a sleeping body unconditionally (issue #167). activateOnChange controls that per body:

const crate = useRef<BodyState>(null);

useEffect(() => {
    // repositioning sleeping scenery shouldn't wake it just to move it and let it fall back
    // asleep a moment later
    crate.current!.activateOnChange = false;
    crate.current!.position = new THREE.Vector3(3, 0.5, -2);
}, []);

Opt-in perf optimisation (issue #168). By default, the physics frame sync writes each body's pose into object.position/object.quaternion, and three.js recomposes object.matrix from those every frame on its own. With bodyState.matrixAutoUpdate = false (or <RigidBody matrixAutoUpdate={false}>), the sync instead composes the pose straight into object.matrix and flags matrixWorldNeedsUpdate, and turns off three's own Object3D.matrixAutoUpdate so nothing recomposes it a second time. object.position and object.quaternion are left exactly as they were at creation — reading them no longer tells you where the object is; use bodyState.position / readPose instead.

<RigidBody matrixAutoUpdate={false} position={[0, 5, 0]}>
    <mesh>
        <boxGeometry args={[1, 1, 1]} />
    </mesh>
</RigidBody>

Measured with 1000 dynamic bodies stepped for 120 frames (packages/react-three-jolt/test/matrix-auto-update.test.ts): roughly a 4–6% reduction in sync-loop time, from skipping three's Object3D.updateMatrix() and an extra Matrix4.decompose() per body. Worth it for scenes with hundreds to thousands of always-visible dynamic bodies; not worth the readability cost for a handful.

friction, restitution, mass, gravityFactor, linearDamping, angularDamping, isSensor — all plain get/set number/boolean properties. color gets/sets the three.js material colour (and the per-instance colour on instanced bodies).

mass is the body's simulated mass in kilograms, read from its motion properties rather than from the shape's density, so it reflects a mass prop or a later write. Static and kinematic bodies have infinite mass in Jolt and report 0; setting it on one does nothing (a devWarn names which motion type ignored it), and so does setting it to 0 or a negative number on a dynamic body. Setting it scales the inverse mass and the inertia tensor together and leaves the body's degrees of freedom untouched — unlike going through Jolt's SetMassProperties directly, which would reset them to "all".

handle, body (the raw Jolt.Body), BodyID, object (the three.js object), meshType, isInstance, and group / subGroup (plus the collisionGroup / collisionSubGroup aliases) — see Collision groups & layers. setGroup(group, { activate? }) / setSubGroup(subGroup, { activate? }) are the method forms with a one-call activation override (#167).

The three edit methods call notifyShapeChanged for you, so the body's mass properties and broadphase bounds follow the edit. You only call it yourself if you mutate a shape by hand through body.shape. See mutable compounds.

A motion source is a body that pushes other bodies when they touch it — conveyors, bounce pads, force fields, teleporters. These are Jolt patterns the library packages up rather than Jolt objects.

const conveyor = useRef<BodyState>(null);

useEffect(() => {
    // local-space vector: rotate the pad and the push rotates with it
    conveyor.current?.activateMotionSource(new THREE.Vector3(-2.4, 0, 0));
    conveyor.current!.motionAsSurfaceVelocity = true; // belt-like, instead of an impulse
}, []);

Combine with isSensor for a force field: contacts still fire, but nothing is blocked.

destroy(ignoreThree?) tears the body down, but you rarely call it — <RigidBody> unmounting calls bodySystem.removeBody(handle) for you, which also removes any constraints attached to the body first. See Memory & lifecycle.

useConstraint joins two bodies and keeps the constraint alive for the lifetime of the component. It is removed on unmount and re-created when the type, bodies or option values change.

import { BodyState, RigidBody, useConstraint } from '@react-three/jolt';
import { useRef } from 'react';

export function Swing() {
    const anchor = useRef<BodyState>(null);
    const weight = useRef<BodyState>(null);

    useConstraint('distance', anchor, weight, { point1: [0, 5, 0], min: 1, max: 4 });

    return (
        <>
            <RigidBody ref={anchor} type="static" position={[0, 5, 0]}>
                <mesh>
                    <boxGeometry args={[0.5, 0.5, 0.5]} />
                </mesh>
            </RigidBody>
            <RigidBody ref={weight} position={[0, 1, 0]}>
                <mesh>
                    <sphereGeometry args={[0.5]} />
                </mesh>
            </RigidBody>
        </>
    );
}

Types: fixed, point, distance, hinge (alias revolute), slider (alias prismatic), cone, swingTwist, sixDOF. Options cover anchors (point1, point2, position), axes (axis, normal, twistAxis, planeAxis), limits (min, max, angle, twistMin, twistMax), friction, space, and spring / motor sub-objects. The hook returns a ref to the typed Jolt constraint (ConstraintTypeMap[T]), so a 'hinge' gives you a Jolt.HingeConstraint with SetTargetAngularVelocity and friends.

<InstancedRigidBodies> replaces <instancedMesh>: the child mesh describes the shape and material, count says how many, and every instance gets its own body. The ref gives you an array of BodyState.

import { BodyState, InstancedRigidBodies } from '@react-three/jolt';
import { useRef } from 'react';

export function Confetti() {
    const bodies = useRef<BodyState[]>(null);

    return (
        <InstancedRigidBodies
            ref={bodies}
            count={200}
            color="#D9594C"
            position={[0, 10, 0]}
            rotation={[0, 0, 0]}
        >
            <mesh>
                <boxGeometry args={[0.5, 0.5, 0.5]} />
                <meshStandardMaterial />
            </mesh>
        </InstancedRigidBodies>
    );
}

It takes the same event props as <RigidBody> — onCollisionEnter, onCollisionPersist, onCollisionExit, onSensorEnter, onSensorExit, onIntersectionEnter, onIntersectionExit, onSleep, onWake — subscribed on every instance body. The payload's target.index says which instance fired:

<InstancedRigidBodies
    count={200}
    onCollisionEnter={(e) => console.log('instance', e.target.index, 'hit', e.other.handle)}
>
    <mesh>
        <boxGeometry args={[0.5, 0.5, 0.5]} />
        <meshStandardMaterial />
    </mesh>
</InstancedRigidBodies>

Every event in the library — step, contact, sensor, sleep/wake — goes through one primitive and one set of names. A concept is spelled the same way whether you reach it as a React prop, a hook, or an imperative subscription.

The same names exist world-wide on <Physics>, plus onSettled and onActivityChange.

<RigidBody onCollisionEnter={(e) => console.log(e.other.object?.name, e.normal)}>
    <mesh>
        <boxGeometry args={[1, 1, 1]} />
    </mesh>
</RigidBody>

Handler identity is deliberately not a subscription dependency, so an inline arrow does not resubscribe on every render, and StrictMode's mount → cleanup → mount leaves exactly one subscription.

import type { BodyState } from '@react-three/jolt';

function watch(body: BodyState) {
    const off = body.on('collisionEnter', (e) => console.log(e.other.handle));
    off(); // unsubscribe
}

Every subscription returns its own unsubscribe, and removal never compares function identity. Registering the same function twice gives two subscriptions and two handles, so an inline arrow is just as removable as a named one. body.onCollisionEnter(fn) and friends are one-line sugar for the same thing, spelled exactly like the props. The old removeContactListener(fn) / removeActivationListener(fn) methods still exist, are deprecated, and now remove every subscription made for that function.

From a component, useBodyEvent and useWorldEvent do the same with an effect's lifetime:

import { BodyState, useBodyEvent, useWorldEvent } from '@react-three/jolt';

function Counter({ body }: { body: BodyState | undefined }) {
    useBodyEvent(body, 'collisionEnter', (e) => console.log(e.penetration));
    useWorldEvent('settled', () => console.log('the world stopped moving'));
    return null;
}

import type { BodyState } from '@react-three/jolt';
import type * as THREE from 'three';

interface CollisionTarget {
    body: BodyState | undefined;
    object: THREE.Object3D | undefined;
    handle: number; // BodyID.GetIndexAndSequenceNumber()
    subShapeId: number; // SubShapeID.GetValue(); -1 for a shape with no sub-shapes
    index?: number; // instance index, for <InstancedRigidBodies>
}
interface CollisionPayload {
    target: CollisionTarget; // the body this handler is registered on
    other: CollisionTarget;
    flipped: boolean; // true when `target` is Jolt's body 2
    contactCount: number; // open sub-shape manifolds between the two bodies
}
interface CollisionEnterPayload extends CollisionPayload {
    normal: THREE.Vector3; // world space, from `other` toward `target`
    penetration: number;
    points: THREE.Vector3[]; // world space; points.length === pointCount
    pointCount: number;
}

collisionEnter and collisionPersist carry the manifold (CollisionEnterPayload); collisionExit, sensorEnter and sensorExit carry CollisionPayload. sleep and wake carry ActivationPayload ({ body, handle }), and contactValidate carries ValidatePayload ({ target, other, baseOffset }). All of them are exported types.

// do
<RigidBody onCollisionEnter={(e) => setPoint(e.points[0].clone())}>{mesh}</RigidBody>;
// don't
<RigidBody onCollisionEnter={(e) => setLastContact(e)}>{mesh}</RigidBody>;

body and object are undefined when the other side is a Jolt body that was never registered with BodySystem — the vehicle chassis and the character controller's rig anchor are both like this. handle is always valid.

payload.targetSubShape and payload.otherSubShape turn a raw SubShapeID into the <Shape> that produced it:

interface SubShapeRef {
    id: number;                            // SubShapeID.GetValue()
    index: number;                         // top-level compound child, or -1 for a leaf shape
    userData: number;                      // the tag stamped on the <Shape>/descriptor, or 0
    descriptor: ShapeDescriptor | undefined;  // what it was built from, `name` included
}

They are resolved on first read. Touching targetSubShape is what walks the shape; a handler that never asks costs nothing per contact, which is why they are getters rather than fields. The SubShapeRef is pooled like the rest of the payload.

index comes from the bit path Jolt packs into the id, and userData from Shape::GetSubShapeUserData, which resolves all the way down to the leaf that was hit. The two answer different questions: index is which child of the body's shape, userData is which declaration, at any nesting depth. descriptor is only filled in when the body kept the description it was built from — <Shape> and the automatic describeObject path both do; bodySystem.addBody(object, { shape }) does not unless you also pass shapeDescriptor.

<RigidBody onCollisionEnter={(e) => console.log('hit', e.targetSubShape.descriptor?.name)}>
    <Shape>
        <Shape name="hull" size={[4, 1, 2]} />
        <Shape name="wing" size={[1, 0.2, 6]} position={[2, 0, 0]} />
    </Shape>
</RigidBody>

A <Shape> takes the same onCollisionEnter / onCollisionPersist / onCollisionExit / onSensorEnter / onSensorExit props as a <RigidBody>, scoped to itself:

<RigidBody type="static">
    <Shape>
        <Shape size={[8, 1, 8]} position={[-6, 0, 0]} onCollisionEnter={leftPanelLitUp} />
        <Shape size={[8, 1, 8]} position={[6, 0, 0]} onCollisionEnter={rightPanelLitUp} />
    </Shape>
</RigidBody>

They subscribe on the parent body and filter by sub-shape, so they cost the same as the body's own handlers plus one integer compare. A <Shape> that has any of them and no explicit userData is assigned one automatically (from the top of the 32-bit range, well clear of your own numbering). Pass userData yourself to choose the tag, and name to label the descriptor.

Two caveats, both from how Jolt resolves a SubShapeID:

Per substep, not per rendered frame — under a fixed timeStep one frame may run several:

beforeStep → pending body actions → joltInterface.Step() → queued events → afterStep

and within the event flush:

collisionExit, sensorExit → collisionEnter, sensorEnter → collisionPersist → sleep, wake

Exits come first so a handler keeping a "things I'm touching" set is never transiently over-counted while a contact migrates between sub-shapes. Within one kind, world-level handlers run before per-body ones, and per-body fires for Jolt's body 1 then body 2, each with its own target / other / flipped.

You may do anything from a handler. It runs after Step() has returned, so adding, moving and removing bodies is safe; the mutation lands at the top of the next substep. Each handler is dispatched inside its own try/catch, so a throw is logged and does not abort the rest of the frame.

The one exception to all of the above: it runs synchronously inside the step, because its answer is what Jolt asked for. It must be fast and must not touch bodies. Return false to reject the contact — one-way platforms, team pass-through:

<RigidBody onContactValidate={(e) => (e.other.object?.userData.team === 'blue' ? false : true)}>
    <mesh>
        <boxGeometry args={[4, 0.5, 4]} />
    </mesh>
</RigidBody>

If nothing is listening, contacts cost a pair refcount and nothing else: no manifold is wrapped, no payload is built, nothing is queued. Each BodyState publishes an eventMask bitfield and the world emitter another; the Jolt callback ors them and bails out. onCollisionPersist is therefore free to leave unsubscribed even though Jolt reports persisted contacts every step. Up to four contact points are copied per event. The pair refcount behind isContacting() is maintained whether or not anyone is listening, because it is public API in its own right.

The answers this implementation took to the event RFC's open questions, recorded here so they can be changed:

The old onContactAdded / onContactRemoved / onContactPersisted props are kept as deprecated aliases for onCollisionEnter / onCollisionExit / onCollisionPersist. They now receive the new payload; their declared type never matched what was actually dispatched, so nothing that worked before breaks.