README

Box3D




!Box3D Logo

Box3D is a 3D physics engine for games.



 Features

 Collision

- Continuous collision detection
- Contact events
- Convex hulls, capsules, spheres, triangle meshes, and height fields
- Multiple shapes per body
- Collision filtering
- Ray casts, shape casts, and overlap queries
- Sensor system
- Character mover

 Physics

- Robust _Soft Step_ rigid body solver
- Continuous physics for fast translations and rotations
- Island based sleep
- Revolute, prismatic, distance, motor, weld, and wheel joints
- Joint limits, motors, springs, and friction
- Joint and contact forces
- Body movement events and sleep notification

 System

- Data-oriented design
- Written in portable C17
- Extensive multithreading and SIMD
- Optimized for large piles of bodies
- Cross platform determinism
- Recording and replay

 Samples

- Uses sokol to run with D3D11 on Windows, Metal on macOS, and OpenGL 4.5 on Linux.
- Graphical user interface with imgui.
- Many samples to demonstrate features and performance.

 Building all platforms

- Install CMake
- Install git
- Ensure these run from the command line

 Building with CMake presets (recommended)

This uses the presets in CMakePresets.json.

- Windows: cmake --preset windows then cmake --build --preset windows-release
- Linux: cmake --preset linux-release then cmake --build --preset linux-release
- macOS: cmake --preset macos then cmake --build --preset macos-release
- Windows MinGW: cmake --preset mingw-release then cmake --build --preset mingw-release

Run the samples app (must be in the Box3D directory).

- Windows: .\build\bin\Release\samples.exe
- Linux: ./build/bin/samples
- macOS: ./build/bin/Release/samples

 Building for Visual Studio

- Install Visual Studio
- Run build_vs2026.bat
- Open and build build/box3d.slnx

 Building for Linux

- Run build.sh from a bash shell
- Results are in the build sub-folder

 Building for Xcode

- mkdir build
- cd build
- cmake -G Xcode ..
- Open box3d.xcodeproj
- Select the samples scheme
- Build and run the samples

 Building for Web

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

Box3D uses SSE2 with WebAssembly. Define BOX3D_DISABLE_SIMD to disable SSE2.

 Building and installing

- mkdir build
- cd build
- cmake ..
- cmake --build . --config Release
- cmake --install . (might need sudo)

 Using Box3D in your project

The core library has no dependencies beyond the C runtime (and libm on Unix). Linking it
gives you the box3d::box3d target.

I recommend to use FetchContent:

cmake
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)


For a vendored copy or git submodule, point add_subdirectory at it:

cmake
add_subdirectory(extern/box3d)

target_link_libraries(my_app PRIVATE box3d::box3d)


To use a copy installed with cmake --install, find the package:

cmake
f