Box3D: A Physics Engine Built for Data-Oriented Game Design

When data layout matters: Box3D's trade-off

Box3D is built for game engines where physics bottlenecks are known: large piles of bodies, frequent collision queries, or tight frame budgets. It does not hide its design. The architecture is data-oriented, meaning shapes and constraints are stored in arrays optimized for cache locality, not as object-graph pointers. This choice makes multithreading straightforward and SIMD operations natural, but it also means the API does not look like traditional OOP physics libraries. You get the box3d::box3d target when linking; everything else is visible and open to optimization. Single-body queries and edge cases are not the focus; the library assumes you have dozens or hundreds of objects in flight. The data-oriented approach also explains why there are no official plugins for Unreal or Unity: integrating with an editor-centric engine would require translating the editor's object model into arrays, a cost Box3D does not pay. Scenes with large piles of bodies benefit most from this design because the array layout reduces memory fragmentation and cache misses. The trade-off is clear: you get raw performance on wide scenes at the cost of rebuilding your integration.

Collision handling with shape variety

Box3D detects collisions on convex hulls, capsules, spheres, triangle meshes, and height fields. Each body can hold multiple shapes. The engine provides continuous collision detection to prevent tunneling during fast motion, ray casts for casting queries into the world, shape casts to sweep a shape along a path, and overlap queries to test intersection without contact. The sensor system marks shapes that report contacts but do not participate in physics, useful for trigger volumes. A character mover utility handles common patterns of player-controlled movement on terrain. Collision filtering lets you disable interactions between specific shape pairs without testing them, which matters in large scenes where you want to avoid testing thousands of pairs. Manifold data exposes the contact points and normals for custom response logic. The sample_collision example demonstrates these capabilities, the sample_continuous example shows fast-moving body handling, and the sample_character example shows terrain interaction. The continuous collision detection is critical to protecting against fast-moving bodies that would otherwise tunnel through geometry.

Rigid body dynamics with joint constraints

The core solver is called Soft Step and uses island-based sleeping to save CPU on stationary groups. Rigid bodies can rotate or translate freely, or be constrained by revolute, prismatic, distance, motor, weld, and wheel joints. Each joint supports limits, motors, springs, and friction. The engine reports joint and contact forces for downstream logic like ragdolls or breakable constraints. When bodies move or enter sleep, the engine fires events. Recording and replay allow deterministic playback for debugging or network synchronization. This is useful for lockstep multiplayer where every client must arrive at identical simulation state. Island-based sleep reduces CPU usage on inactive bodies by treating stationary clusters as a single unit that can be deactivated together. The sample_joint example demonstrates these constraints, sample_compound shows compound bodies with multiple shapes, sample_events shows body movement and sleep events, and sample_issues tests edge cases. The Soft Step solver design prioritizes stability over speed, suitable for games where physics accuracy matters more than raw performance.

SIMD and multithreading optimizations

Box3D uses SSE2 SIMD intrinsics and Neon SIMD math on ARM to accelerate vector and matrix operations. SIMD can be disabled by defining BOX3D_DISABLE_SIMD at compile time, useful for platforms that do not support it or when debugging. The library is designed for multithreading from the ground up; the data-oriented layout means you can partition bodies into independent islands and process them in parallel without lock contention. Island-based partitioning naturally divides the work because stationary and moving body groups do not interact heavily with each other. The samples app demonstrates this with many bodies in flight, and the sample_benchmark example exercises the multithreading on large scenes. On WebAssembly, the library uses SSE2 with Emscripten; you can disable it with BOX3D_DISABLE_SIMD when building for WASM if performance is not critical. The Portable C17 implementation means the code compiles without architecture-specific headers on most platforms.

Building and linking Box3D

Box3D requires a C17 compiler; the samples require C++20. On Windows, Linux, and macOS, the recommended build path uses CMake presets. Start by installing CMake and git. For Windows:

cmake --preset windows
cmake --build --preset windows-release

For Linux:

cmake --preset linux-release
cmake --build --preset linux-release

For macOS:

cmake --preset macos
cmake --build --preset macos-release

Run the samples app to verify the build. On Windows it is .\build\bin\Release\samples.exe. On Linux, ./build/bin/samples. On macOS, ./build/bin/Release/samples. The samples app uses sokol to render with D3D11 on Windows, Metal on macOS, and OpenGL 4.5 on Linux, plus imgui for controls. The samples include benchmarks, collision tests, joints, compound bodies, continuous physics, events, geometry, and issues.

To use Box3D in a CMake project, fetch it from git:

include(FetchContent)
FetchContent_Declare(box3d
  GIT_REPOSITORY https://github.com/erincatto/box3d.git
  GIT_TAG v0.1.0)
FetchContent_MakeAvailable(box3d)

target_link_libraries(my_app PRIVATE box3d::box3d)

The core library has no dependencies beyond the C runtime and math library. To install the library on your system instead of fetching it:

mkdir build
cd build
cmake ..
cmake --build . --config Release
cmake --install .

For WebAssembly, the build requires the Emscripten SDK:

emcmake cmake -B build -DBOX3D_SAMPLES=OFF
cmake --build build

Alternatively, use Visual Studio on Windows by running build_vs2026.bat and opening build/box3d.slnx, or use Xcode on macOS with cmake -G Xcode after creating a build directory.

Not a game engine, so you own the integration

Box3D is a library, not a game engine. It has no editor, no asset importers, no default renderers, and no official plugins for Unreal, Godot, or Unity. You build your own integration, which means writing C code to feed shapes to the physics engine and read results back. The repository includes docs/hello.md with a minimal first program. For teams porting middleware from Box2D, migration patterns are documented. Pull requests are disabled; the author prefers feature requests filed as issues or discussed on Discord. The design acknowledges that every engine has different needs, so Box3D stays focused on the physics simulation itself. The LLM usage section notes that migrations between Box2D and Box3D are areas where LLM tooling is used, showing the author is aware of the integration gap. This approach trades off convenience for flexibility, leaving all architecture decisions to you.

Determinism and platform portability

Box3D promises cross-platform determinism: the same inputs produce the same outputs on Windows, Linux, and macOS if the same compiler is used. This is significant because floating-point arithmetic is sensitive to order of operations and SIMD intrinsics, which typically differ per platform. Box3D implements this by constraining the solver run deterministically; you do not get to tweak tolerances per platform. If determinism is critical to your project, run the sample_determinism sample across all your target hardware before shipping. The library provides recording and replay capabilities which depend on this guarantee. For network play, clients can synchronize by replaying the same recorded inputs, making this feature useful for rollback and lockstep networking. The commitment to determinism without toggles is unusual among physics engines and reflects a deliberate design choice.

Positioning against PhysX, Jolt, and Rapier

PhysX, the NVIDIA physics engine, is closed-source and tightly integrated with Unreal and proprietary game engines. It requires the PhysX SDK installation and license agreement. Jolt, a newer open-source alternative written in C++, has more editor-friendly tooling and a larger API surface; it is often compared to Box3D. Rapier, a pure-Rust library, runs in the browser via WebAssembly and is often paired with Bevy. Box3D trades breadth of features and editor integration for focused performance on large rigid-body scenes and exact cross-platform determinism without runtime toggles. The most recent release is v0.1.0 from 2026-06-30, and the last push was on 2026-09-28, showing active development. The single-threaded licensing and visible code path make Box3D suitable for projects where you need to audit or modify the physics solver itself.

Editorial conclusion

Box3D is for game developers and engine teams who want deterministic physics, multithreading without compromise, and direct control over collision and constraint behavior. It is not for designers who expect a prebuilt editor integration or for teams moving a 2D game to 3D without rewriting the physics layer. Before committing, verify that the sample applications run on your target platforms and that sokol works with your graphics stack. Test the determinism claims on the exact hardware and compiler you plan to ship with, since cross-platform determinism depends on both.

Frequently asked questions

Official sources

1. erincatto/box3d on GitHub
2. Issues
3. License: MIT
4. README
5. Releases