Box3D: a C17 3D physics engine from the author of Box2D

What Box3D solves and who it is for

Box3D is a 3D physics engine for games, released as v0.1.0 on 2026-06-30 by Erin Catto, the author of Box2D. The problem it addresses is the one Box2D solved for 2D: giving a game a self-contained rigid body simulator that does not drag a large engine or a scripting runtime along with it. The README states that the core library has no dependencies beyond the C runtime, plus libm on Unix. That is the whole pitch. If you are writing a game in C or C++, and you want to link a physics library the way you link a math library, this is aimed at you.

The audience is narrower than the feature list suggests. The library builds with a C17 compiler; the samples require C++20. There is no C# binding, no JavaScript package, no Unreal or Unity plugin, and no Godot integration documented in the README. People searching for box3d unity or box3d godot will not find an official answer here. Integration work is on the adopter, not the project. The samples use sokol for rendering (D3D11 on Windows, Metal on macOS, OpenGL 4.5 on Linux) and imgui for the interface, but those are sample dependencies, not library dependencies.

The design targets large piles of bodies. The README lists island based sleep, extensive multithreading and SIMD, and a Soft Step rigid body solver. Cross platform determinism and recording/replay are listed as system features, which matters if you need lockstep networking or reproducible replays. Those are the claims; the repository does not publish benchmark numbers in the README, so treat performance as something to measure on your own scene rather than something the project certifies.

The collision and solver model behind Box3D

The shape set is convex hulls, capsules, spheres, triangle meshes, and height fields, with multiple shapes per body and collision filtering. Queries cover ray casts, shape casts, and overlap tests. Contact events and a sensor system are exposed, and there is a character mover. Continuous collision detection is present, and the README separately lists continuous physics for fast translations and rotations, which is the part that matters when a bullet or a fast-moving character would otherwise tunnel through a wall between frames.

On the dynamics side, the joint list is revolute, prismatic, distance, motor, weld, and wheel, with limits, motors, springs, and friction. Joint and contact forces are readable, and the engine emits body movement events and sleep notifications. Sleep is island based, so a settled stack stops consuming solver time as a group rather than one body at a time.

The architecture is described as data-oriented, written in portable C17, with multithreading and SIMD. The compatibility notes say SSE2 and Neon are used for the math, and that defining BOX3D_DISABLE_SIMD turns SIMD off. That is a real escape hatch: on a platform where the vector paths misbehave, or in a build where you want to isolate a numerical difference, you can disable them and compare. The WebAssembly path is the one place the README gives a specific instruction, because it uses SSE2 and asks you to define BOX3D_DISABLE_SIMD if you need to turn it off.

What the README does not describe is the solver's internal data flow: how contacts are generated, how islands are formed, or how the Soft Step solver iterates. Those details live in docs/, which is built with Doxygen behind the BOX3D_DOCS CMake option. Until you build that target, the README is a feature list, not a design document.

Building Box3D with CMake presets and linking it

The recommended path is CMake presets from CMakePresets.json. On Linux, configure and build with the release preset:

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

On Windows the equivalent is `cmake --preset windows` followed by `cmake --build --preset windows-release`. The macOS and MinGW presets follow the same pattern. The samples executable is written to build/bin on Linux and macOS, and to build\bin\Release on Windows. The README notes the samples app must be run from the Box3D directory, which usually means it looks for assets relative to the working directory.

If you would rather not use presets, the plain CMake flow is four commands:

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

Adding `cmake --install .` installs the package, and the README notes it might need sudo. For consuming the library, the README recommends FetchContent and pins the tag:

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 target is `box3d::box3d`. If you vendor the source as a submodule, `add_subdirectory(extern/box3d)` exposes the same target. If you installed with `cmake --install`, use `find_package(box3d 0.1 REQUIRED)` instead. For a first real program, the README points at docs/hello.md, which is the minimal example the project ships. The README does not reproduce that program inline, so read the file in the repository rather than guessing at the world-creation and step API.

Visual Studio users have build_vs2026.bat, which produces build/box3d.slnx. There is also a build_vs2022.bat in the repository root, and build.sh for Linux. The Xcode flow is manual: create a build directory, run `cmake -G Xcode ..`, open box3d.xcodeproj, and select the samples scheme.

Where Box3D is the wrong tool

Version 0.1.0 is the first release, dated 2026-06-30. Every API in the headers is one release old. If your project ships on a schedule that does not tolerate a physics API changing under it, pin the tag and vendor the source, because the README gives no compatibility promise across future versions.

Pull requests are disabled. The contributing section says to file an issue for bugs or feature requests, and that support happens on Discord. That is a deliberate bottleneck: you cannot send a patch, only a report. If your team's workflow depends on upstreaming fixes and getting them merged on your own timeline, this repository will not support that. Forking is the alternative, and forking a physics engine means owning the fork.

The README also states that LLMs are used in unit tests, the samples app, code migration between Box2D and Box3D, build configuration, code reviews, and benchmarking, while the author takes responsibility for every line of code in Box2D and Box3D. That is a disclosure, not a defect, but it tells you which parts of the tree are most likely to contain generated code: the tests and the samples. If you plan to read the test suite as a specification, keep that in mind.

Documentation is the weakest area. The user manual lives in docs/ and is built with Doxygen behind the BOX3D_DOCS option and the doc target. The README does not document rollback, does not describe a networking model, and does not give a migration guide from any other engine. The feature list is long enough to be misleading: continuous collision detection, character mover, and sensors are all listed, but the README does not say what each one requires of the caller. A character mover, for example, is a component you drive, not a controller you drop in.

Box3D against Jolt, PhysX, Bullet and Rapier

The comparison people actually search for is box3d vs jolt, and the difference is language and packaging. Jolt is a C++ physics engine with a long release history and a wide set of integrations; Box3D is C17 with a C++20 samples layer, and its core has no dependencies beyond the C runtime and libm. If your codebase is C and you do not want a C++ boundary in your build, that difference is the whole decision. If your codebase is C++ and you want the larger body of existing integrations, Jolt is the safer default until Box3D matures.

Against PhysX and Havok, the difference is scale and scope. Those are vendor-backed engines with GPU acceleration paths, authoring toolchains, and commercial support. Box3D does not claim any of that. It is a library you link, and the README's installation story is four CMake commands. Against Bullet, the difference is age and API stability: Bullet has been deployed for many years and carries the compatibility surface that comes with that, while Box3D is at 0.1.0 and can change freely. Against Rapier, the difference is language and runtime: Rapier is a Rust engine used from Rust and from JavaScript, while Box3D is C17 with no JavaScript package in the README. People searching for Box3D js will not find an official binding here.

Determinism is the one axis where Box3D makes a specific promise that is worth weighing: cross platform determinism is listed as a system feature, alongside recording and replay. If you need lockstep multiplayer or reproducible simulation replays, that combination is the reason to look at this project rather than a general-purpose engine. Verify it on your own platforms before you build a netcode design on it, because the README states the feature without describing the conditions it holds under.

Licence, maintenance and upgrade cost

Box3D uses the MIT licence, and the LICENSE file is in the repository root. MIT is permissive: it allows commercial and closed-source use, and it requires that the copyright notice and licence text be preserved. That is the extent of what can be said here; if your organisation has specific obligations around attribution or patent terms, have counsel read the actual LICENSE file rather than this summary.

The repository is not archived, and the last push was on 2026-09-17. The only release is v0.1.0 from 2026-06-30. There is no second release to measure a cadence against, so anyone planning an upgrade path is planning against a single data point. The practical consequence is that pinning is not optional. The README's own FetchContent example pins GIT_TAG v0.1.0, and that is the right default: a moving main branch on a 0.1.0 library is not a dependency you want in a shipped build.

Upgrade cost also includes the docs build. The manual is Doxygen-generated behind BOX3D_DOCS, which means reading the current API requires either building the doc target or reading headers directly. There is no hosted manual referenced in the README. For a team evaluating the library, budget time for that step; the feature list will not tell you the argument order of a world creation call.

Editorial conclusion

Box3D is worth adopting if you write C or C++ game code, want a small dependency-free core with cross-platform determinism and recording/replay, and can work against a v0.1.0 API that will move. It is the wrong choice if you need a mature, widely deployed engine with years of production hardening, a large third-party ecosystem, or a documented migration path from another physics library. Before committing, read docs/hello.md, build the samples app on your target platform, and confirm that the joint and collision features you need are actually present in the v0.1.0 headers rather than only in the feature list.

Frequently asked questions

Official sources

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