Memory & lifecycle

Jolt is a C++ library reached through Emscripten's WebIDL binder. Nothing on the WASM side is garbage collected: every object you create there lives until something frees it, and freeing the wrong thing corrupts memory silently, usually surfacing as a crash somewhere unrelated.

If you only use <Physics>, <RigidBody>, <Shape> and the hooks, you can skip this page — the library owns that memory and frees it when components unmount. Read on before you touch a Jolt.* object directly, which mostly means useJolt().jolt, body.body, a caster you created yourself, or anything reached through Raw.module.

There is exactly one jolt-physics module per page — it owns a single WASM linear memory that every body, shape and constraint lives in — so the library keeps it in a module level singleton:

import { free, getJoltModule, JoltModule, initJolt } from '@react-three/jolt';

await initJolt(); // <Physics> does this for you
const jolt = getJoltModule(); // throws a useful error if it isn't loaded yet
const v = new jolt.Vec3(0, 1, 0);
free(v); // the documented way to destroy something you own

JoltModule.module is the module itself. JoltModule used to be called Raw, and Raw is still exported as an alias of the same object, so existing Raw.module.* code keeps working.

Each <Physics> builds its own JoltInterface on that module and takes an id for it from JoltModule.registerInterface(joltInterface) — a monotonically increasing counter, never reused, so a stale id can never resolve to somebody else's world. JoltModule.getInterface(id) resolves it back (undefined once that world is destroyed), JoltModule.releaseInterface(id) drops the slot in PhysicsSystem.destroy() (it frees nothing itself — the caller destroys the interface), and JoltModule.interfaceCount / JoltModule.liveInterfaceIds() tell you how many worlds, and which, are live right now. This replaced a map keyed by React's useId() (issue #35): that key changes across remounts, so an unmount/remount grew the map instead of reusing a slot, and once it held enough entries a new <Physics> was silently handed an old world's interface.

There is no fixed cap on how many worlds you can mount, but each one costs about 20 MB of the fixed 128 MB WASM heap the jolt-physics WASM builds ship with (no growth), so roughly six fit at once. Past that, new PhysicsSystem() throws — rather than letting emscripten abort the module for the rest of the page — with a message naming how much heap is free, how much is needed, and how many worlds are already live: r3/jolt: not enough WASM heap for another physics world - .... See <Physics>: Destroying a world for the deferred-unmount mechanics that can make that check pass a tick later than you'd expect, and registerDisposable for tying non-body objects to a world's teardown.

This is the rule that catches everyone, and it has no equivalent in JavaScript.

Any C++ function returning by value — Vec3::Normalized(), Quat::sIdentity(), RMat44::sRotationTranslation(), Shape::GetCenterOfMass(), ShapeSettings::Create(), Body::GetWorldSpaceSurfaceNormal(), RRayCast::GetPointOnRay(), AABox::sBiggest(), … — comes back through the binder as a pointer to one static temporary per function, shared by every caller.

That means:

import { BodyState, Raw, vec3 } from '@react-three/jolt';

function centerOfMass(body: BodyState) {
    const joltPosition = body.body.GetCenterOfMassPosition(); // by value: shared temporary

    Raw.module.destroy(joltPosition); // ❌ frees memory the binder owns. Corruption, elsewhere.
    const kept = joltPosition;        // ❌ the next call overwrites it

    return vec3.three(joltPosition).clone(); // ✅ copy the components out immediately
}

ShapeSettings::Create() is the one that bites hardest, because its ShapeResult is also a static temporary — createShapeFromSettings exists so you never have to get that sequence (check error → Get() → AddRef() → Clear() → destroy settings) right by hand.

Property assignment and by-value arguments copy:

settings.mPosition = v;   // copies v
bodyInterface.SetPosition(id, v, activation); // copies v
list.push_back(v);        // copies v

So the temporary you built is yours to destroy immediately afterwards — and a single scratch object can be re-Set() for every element of a loop instead of allocating one per element.

vec3.jolt(), vec3.rjolt() and quat.jolt() always return a new object the caller owns, even when given another Jolt object (they clone it). They never hand back their argument, so destroying the result can never free something Jolt still holds.

const position = vec3.rjolt([0, 10, 0]); // I own this
bodyInterface.SetPosition(body.BodyID, position, Raw.module.EActivation_Activate);
Raw.module.destroy(position); // ...so I free it

vec3.three() / quat.three() never allocate WASM memory and never destroy their input. A THREE.Vector3 argument is passed through unchanged — pass an out target or .clone() if you intend to keep it.

World-space positions are RVec3. In jolt-physics ≥ 1.0 every world-space position argument takes Jolt.RVec3, not Jolt.Vec3 — that's vec3.rjolt(). They are interchangeable at runtime in the single-precision builds, but not in the types.

Construct, call, destroy, even if the callback throws. The shape most code wants:

import { Raw, withJolt, withRJolt } from '@react-three/jolt';

const length = withJolt([0, 1, 0], (v) => v.Length());

withRJolt([0, 10, 0], (position) =>
    bodyInterface.SetPosition(body.BodyID, position, Raw.module.EActivation_Activate)
);

withQuat() does the same for quaternions.

For per-frame code, one shared object per flavour, reused forever:

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

// SetLinearVelocity copies its argument, so one shared vector is enough
bodyInterface.SetLinearVelocity(body.BodyID, joltScratch.vec3(0, 5, 0));

These have their own lifetimes and their own rules:

React tears a parent down before its children, so <Physics> frees the Jolt interface before the bodies inside it unmount. Everything that world owned — bodies, constraints, shapes — goes with the interface, and the systems check physicsSystem.destroyed before touching Jolt afterwards. This is why unmounting a world is safe even though the children clean up "too late".

Practical consequences:

The demo's fix is the pattern to copy until #227 lands a library-level guard: keep the timer handle so you can clearTimeout it on unmount, and re-check physicsSystem.destroyed inside the callback itself (a timer can already be in flight the instant its cleanup runs):

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

function Launcher({ x, body }: { x: number; body: React.MutableRefObject<BodyState | undefined> }) {
    const { physicsSystem } = useJolt();
    const relaunch = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);

    const launch = useCallback(() => {
        relaunch.current = undefined;
        const state = body.current;
        // the world can go away between the timer being set and it firing
        if (!state || physicsSystem.destroyed) return;
        state.position = new THREE.Vector3(x, 1, 0);
    }, [x, physicsSystem, body]);

    useEffect(() => () => clearTimeout(relaunch.current), []);

    return null;
}

The library's internal console output is off by default — a bundled library can't rely on NODE_ENV. Turn it on while you are debugging:

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

setDebug(true);

That enables the internal warnings (devWarn) for things like dropped simulation time, excess Jolt interfaces and failed heightmap loads. It is separate from <Physics debug>, which draws collision shapes in the scene.

For Jolt's own assertions and its debug renderer, use a debug build of the engine — jolt-physics/debug-wasm-compat.

The repository tests allocation balance by wrapping the module's constructors and asserting the live-object count is flat across many iterations (test/jolt-alloc.ts, installAllocTracker(Raw)). If you write a system that touches Jolt directly, the same trick is the only reliable way to catch a leak: a leak that grows by one object per frame is invisible until it isn't, and a double free shows up as the count drifting negative.