Introduction

Jolt physics in React — a react-three-fiber wrapper around the Jolt Physics engine.

Summary

@react-three/jolt (or r3/jolt) puts the Jolt Physics engine behind a declarative react-three-fiber component tree: wrap a mesh in <RigidBody> and it falls.

npm install @react-three/jolt jolt-physics

Warning

Status: alpha. Every API on this site is subject to change, and some of it will. The library is under active development again after a long pause — see the milestones for what "1.0" means here. Pin an exact version if you build on it today.

What Jolt is

Jolt is the rigid body engine written for Horizon Forbidden West: a modern, multi-core-friendly C++ engine that also powers Godot Jolt, compiled to WebAssembly by JoltPhysics.js. It is deterministic, fast at scale, and unusually deep — vehicles, characters, ragdolls, soft bodies, heightfields and a large constraint library are all first-class in the engine itself rather than bolted on.

The price of that depth is an API with sharp edges. Jolt is a C++ library reached through an Emscripten binding, which means manual memory management, layer and filter setup before a single body exists, and a lot of ceremony between "I have a mesh" and "it falls". This library exists to take that on for you.

What this library adds

<Physics> and <RigidBody> — a world and bodies that follow React's lifecycle, with shapes derived automatically from your three.js geometry.
A BodyState per body — one object with plain three.js types (THREE.Vector3, THREE.Quaternion) for reading and writing pose, velocity, damping, friction, mass and degrees of freedom, instead of a BodyInterface and a BodyID.
Systems, not singletons — PhysicsSystem, BodySystem, ConstraintSystem and the query classes are ordinary objects you can reach from useJolt() when the components aren't enough.
Memory ownership rules that hold — conversion helpers that always return something you own, scoped (withJolt) and scratch (joltScratch) variants for hot paths, and bodies/shapes that free their WASM allocations when they unmount. See Memory & lifecycle.
Extras — instanced bodies, heightfields, a character controller, a camera rig, four- and two-wheeled vehicles, and an input-to-command mapper.

Jolt or Rapier?

@react-three/rapier is the sibling library most people compare this to, and it is the right default today. Both wrap a WASM physics engine for r3f; they differ in maturity and in what the engine underneath is good at.

	`@react-three/rapier`	`@react-three/jolt`
Status	stable, widely used	alpha, API in motion
Engine	Rapier (Rust)	Jolt (C++), the Horizon Forbidden West engine
Colliders	explicit `<CuboidCollider>` etc. plus `colliders` autogeneration	autogenerated from geometry, or an explicit `<Shape>`
Strengths	2D and 3D, mature docs and ecosystem, determinism	scale (many bodies), built-in vehicles/characters, deep constraint set, heightfields
Memory	handled by wasm-bindgen	manual — the library owns it for you, but the rules leak out when you touch Jolt directly

Pick Rapier if you want something dependable right now. Pick Jolt if you are pushing on body counts, want Jolt's vehicle/character systems, or are willing to trade stability for the engine's ceiling — and are happy to report bugs.

Where to go next

Installation — peers, bundler setup, Vite and Next.js.
Physics — the world component and every prop it takes.
RigidBody — bodies, props and the BodyState API.
Memory & lifecycle — read this before you touch a Jolt.* object.

Edit this page