Box3D and the Physics of Agreement

Erin Catto built the engine behind a decade of 2D games. His 3D sequel treats cross-platform determinism not as a feature, but as the constraint that shapes everything else.

9 min read • View on GitHub • More from erincatto

A long row of identical brass clockwork orreries on wooden desks, each turning through the same orbit in perfect unison, with a small seated figure at every desk. The scene is a physical picture of cross-platform determinism: many separate machines producing one identical motion with no drift.
Determinism as a workshop: many machines, one motion. Box3D is built so that every machine agrees, tick after tick.

You can think of Box3D as a fork of Box2D, extended with many features needed for 3D games.

Erin Catto, Box3D and Box2D author · Announcing Box3D :: Box2D
Key Takeaways

A Thousand Players, One Universe

Picture a server-authoritative open-world game with a thousand players at once. The server simulates the world: falling trees, ragdolls, voxels, saloon doors, tumbleweeds. Every client receives the state and has to render the same reality the server sees. If one machine drifts by a single bit of floating-point arithmetic, the world splits. A knocked-over barrel lands in two different places. A ragdoll settles into two different poses. The players are now living in separate universes and the session desyncs.

That is the requirement Box3D was built to satisfy. Cross-platform determinism means two different machines, running the same simulation from the same inputs, produce identical results frame after frame. It is a much harder promise than it sounds, and it is the reason the engine makes so many unusual choices.

The engine is a portable C17 core under the MIT license with no runtime dependencies beyond the C runtime and libm on Unix. It handles continuous collision detection, convex hulls, capsules, spheres, triangle meshes, height fields, compound shapes, and a full set of joints. It ships with a Soft Step rigid-body solver, island-based sleep, and recording and replay. For a project this young, that is a lot of surface.

The Man Behind the Falling Fruit

The engine comes from Erin Catto, whose Box2D is arguably the most influential 2D physics library ever shipped. It powered Angry Birds, a generation of indies, and countless prototypes. When Catto wanted a 3D engine, he did not start from a blank file.

Box3D began as a fork of Dirk Gregorius's hobby version of Rubikon, a physics engine that Catto integrated into Unreal Engine for The Legend of California. He then replaced most of that fork's APIs, data structures, and algorithms with Box2D-derived code, keeping some of the Rubikon-Lite hull generation and collision routines. The result is closer to a 3D Box2D than a fresh engine.

A WSJ hedcut-style editorial portrait of Erin Catto, author of Box2D and Box3D, rendered in black ink on a pure white background with stipple shading for skin and hatching for hair.

Catto is careful about what the project is not. He has said he is not trying to compete with other physics engines, and he describes Box3D as alpha software even as it runs in shipped games. That honesty matters when you are deciding whether to embed it.

Despite usage in a few games now, I still consider Box3D to be alpha software.

Erin Catto, Box3D and Box2D author · Announcing Box3D :: Box2D

The Lockstep Problem

Agreement does not happen by accident. It is a stack of conditions, and breaking any one of them breaks the whole. The first condition is a fixed timestep. Box3D's step function takes both a time step and an explicit substep count, and the docs recommend 1/60 and 4.

B3_API void b3World_Step( b3WorldId worldId, float timeStep, int subStepCount );

That signature is a contract. The caller must advance time in fixed increments, because a variable timestep produces a variable number of integration steps, and two machines that step a different number of times will never agree. The substep count is explicit for the same reason: it changes how the solver converges, so it must be identical everywhere. The Soft Step solver then runs the same fixed number of substeps on every machine.

The Lockstep Problem: agreement is a stack of conditions. Turn any one off and the machines drift apart.

The other conditions are subtler. Uniform precision means every machine must agree on whether the solver runs in single or double precision. Order-independent math means the solver cannot depend on the order in which floating-point operations are summed, because different CPU instruction sets sum contact impulses in different orders and get slightly different answers. Each of these conditions is a place where the engine has to be deliberate instead of convenient.

The Engine That Borrows Your Threads

Most engines ship a thread pool. Box3D ships none. It asks the host application to provide two callbacks and never spawns a thread of its own.

typedef void* b3EnqueueTaskCallback( b3TaskCallback* task, void* taskContext, void* userContext, const char* taskName );
typedef void  b3FinishTaskCallback( void* userTask, void* userContext );

The contract is precise. The enqueue callback returns a user task handle, and returning null tells Box3D the work was executed serially inside the callback so no finish call is needed. The finish callback must block until the task completes. This lets the engine plug into whatever job system the host already uses, from a custom scheduler to Unreal's task graph.

There is a sharp edge here, and the docs call it out directly. Because b3World_Step holds its stack across every fork and join, calling it from inside a job that blocks on its own sub-jobs can deadlock. The engine is borrowing the host's threads, so the host has to know not to nest the step inside a job that will wait on itself.

Collision Without a Margin

For convex hull collision, Box3D uses the Separating Axis Test. The idea is old and geometric: if two convex shapes do not overlap, there exists an axis along which their projections are separated. Find that axis and you have your contact information, including the feature, normal, and points.

The alternative most engines reach for is GJK for distance and EPA for penetration depth. Catto's case against that path is specific. EPA tends to require a collision margin, a small artificial gap that keeps the math stable, and it can be numerically brittle near the boundaries where shapes barely touch. SAT sidesteps both problems and produces the contact data directly, which is exactly what a deterministic solver wants. Box3D then uses wide SIMD to solve multiple contact points together, which speeds up the solver without changing its answer.

Box3D uses the Separating Axis Test for collision detection.

Erin Catto, Box3D and Box2D author · SIMD for Collision :: Box2D

Precision at the Edge of the World

A large open world breaks ordinary floating-point math. A 32-bit float has enough precision near the origin, but a coordinate a few kilometers out loses the fine detail needed to tell whether a ray grazes a wall. Box3D's answer is origin-relative queries.

Query functions like b3World_CastRay, b3World_OverlapShape, and b3World_CastShape take a b3Pos origin argument. Proxy geometry is kept in float relative to that origin, so a query stays precise far from the world origin instead of degrading with distance. The engine pushes the origin into the caller's hands and rebases the math around it.

A close-up of a single tiny cube resting on a vast white plane far from a large origin obelisk. A measuring tape stretches from the obelisk to the cube, its tick marks growing blurry and irregular with distance until they dissolve into stipple dots, while a hand holds a small crisp brass ruler right at the cube with sharp markings. The blurry distant tape is float precision far from the origin; the crisp local ruler is the rebased b3Pos origin.
Float precision decays with distance from the origin. Rebase the query onto a nearby origin and the local math stays sharp.

Where Box3D Fits

Box3D's niche is a Box2D-style design in a native C API where determinism, large worlds, or replay matter. It is not the safest general production choice yet, because it is explicitly alpha.

ProjectLanguage / approachHow it differs from Box3D
Box3DC17, MIT, no runtime dependenciesDeterminism and replay are stated goals, not add-ons
Jolt PhysicsC++The general-purpose alternative Catto considered forking
Bullet PhysicsC++Long-established with a broad ecosystem
NVIDIA PhysXC++Vendor-backed with heavy tooling and integrations
RapierRust, WebAssemblyStrong web story; Box3D ships no official JS package
HavokCommercialVendor support and established authoring tools
Box2DC, 2DThe architectural sibling, not a competitor

The engine's value shows in the case it was built for: a server-authoritative open-world game where the server and every client must simulate the same physics and stay in agreement. If that is your problem, the determinism discipline that runs through the whole API is the reason to look. If it is not, the mature alternatives have longer production histories and more integrations behind them.