2026-05-23 12:04:16 -07:00
# Box3D
2026-05-10 13:36:52 -07:00
2026-05-23 12:04:16 -07:00

2026-05-10 13:36:52 -07:00
Box3D is a 3D physics engine for games.
2026-05-23 12:04:16 -07:00
## Build Status
[](https://github.com/erincatto/box3d/actions)
2026-05-10 13:36:52 -07:00
## Features
### Collision
2026-05-23 12:04:16 -07:00
2026-05-10 13:36:52 -07:00
- Continuous collision detection
- Contact events
2026-05-23 12:04:16 -07:00
- Convex hulls, capsules, spheres, triangle meshes, and height fields
2026-05-10 13:36:52 -07:00
- Multiple shapes per body
- Collision filtering
- Ray casts, shape casts, and overlap queries
- Sensor system
### Physics
2026-05-23 12:04:16 -07:00
2026-05-10 13:36:52 -07:00
- Robust _ Soft Step _ rigid body solver
- Continuous physics for fast translations and rotations
- Island based sleep
- Revolute, prismatic, distance, mouse joint, weld, and wheel joints
- Joint limits, motors, springs, and friction
- Joint and contact forces
- Body movement events and sleep notification
### System
2026-05-23 12:04:16 -07:00
2026-05-10 13:36:52 -07:00
- Data-oriented design
- Written in portable C17
- Extensive multithreading and SIMD
- Optimized for large piles of bodies
### Samples
2026-05-23 12:04:16 -07:00
- Uses sokol to run with D3D11 on Window, Metal on macOS, and OpenGL 4.3 on Linux
2026-05-10 13:36:52 -07:00
- Graphical user interface with imgui
- Many samples to demonstrate features and performance
## Building All Platforms
2026-05-23 12:04:16 -07:00
2026-05-10 13:36:52 -07:00
- Install [CMake ](https://cmake.org/ )
- Install [git ](https://git-scm.com/ )
- Ensure these run from the command line
2026-06-28 10:44:34 -07:00
## Building with CMake presets
The presets in `CMakePresets.json` give one build flow on every platform and are picked up automatically by Visual Studio, VS Code, and CLion (open the folder and choose a preset). From the command line:
- 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`
Run the samples app (must be in the Box3D directory).
- Bash: `./build/bin/Release/samples`
- Cmd: `.\build\bin\Release\samples.exe`
2026-05-10 13:36:52 -07:00
## Building for Visual Studio
2026-05-23 12:04:16 -07:00
2026-05-10 13:36:52 -07:00
- Install [Visual Studio ](https://visualstudio.microsoft.com/ )
- Run `build_vs2026.bat`
- Open and build `build/box3d.slnx`
## Building for Linux
2026-05-23 12:04:16 -07:00
2026-05-10 13:36:52 -07:00
- Run `build.sh` from a bash shell
- Results are in the build sub-folder
## Building for Xcode
2026-05-23 12:04:16 -07:00
2026-05-10 13:36:52 -07:00
- mkdir build
- cd build
- cmake -G Xcode ..
- Open `box3d.xcodeproj`
- Select the samples scheme
- Build and run the samples
## Building and installing
2026-05-23 12:04:16 -07:00
2026-05-10 13:36:52 -07:00
- mkdir build
- cd build
- cmake ..
- cmake --build . --config Release
- cmake --install . (might need sudo)
2026-06-28 10:44:34 -07:00
## 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. When Box3D is consumed as a subproject it builds the
library only; samples, tests, and benchmarks are skipped.
The recommended path is FetchContent, which pins a tag and needs no separate install step:
```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
find_package(box3d 0.1 REQUIRED)
target_link_libraries(my_app PRIVATE box3d::box3d)
```
See [`docs/hello.md` ](docs/hello.md ) for a minimal first program.
2026-05-10 13:36:52 -07:00
## Compatibility
2026-05-23 12:04:16 -07:00
2026-05-10 13:36:52 -07:00
The Box3D library and samples build and run on Windows, Linux, and Mac.
You will need a compiler that supports C17 to build the Box3D library.
You will need a compiler that supports C++20 to build the samples.
Box3D uses SSE2 and Neon SIMD math to improve performance. This can be disabled by defining `BOX3D_DISABLE_SIMD` .
## Documentation
2026-05-23 12:04:16 -07:00
2026-06-10 13:21:14 -07:00
The user manual lives in [`docs/` ](docs/ ) and is built with Doxygen. Enable the `BOX3D_DOCS` CMake option and build the `doc` target.
2026-05-10 13:36:52 -07:00
## Community
2026-05-23 12:04:16 -07:00
2026-05-10 13:36:52 -07:00
- [Discord ](https://discord.gg/NKYgCBP )
## Contributing
2026-05-23 12:04:16 -07:00
2026-05-10 13:36:52 -07:00
Please do not submit pull requests. Instead, please file an issue for bugs or feature requests. For support, please visit the Discord server.
2026-05-23 12:04:16 -07:00
## Giving Feedback
2026-05-10 13:36:52 -07:00
Please file an issue or start a chat on discord. You can also use [GitHub Discussions ](https://github.com/erincatto/box3d/discussions ).
## License
2026-05-23 12:04:16 -07:00
2026-05-10 13:36:52 -07:00
Box3D is developed by Erin Catto and uses the [MIT license ](https://en.wikipedia.org/wiki/MIT_License ).
## Sponsorship
2026-05-23 12:04:16 -07:00
2026-05-10 13:36:52 -07:00
Support development of Box3D through [Github Sponsors ](https://github.com/sponsors/erincatto ).
Please consider starring this repository and subscribing to my [YouTube channel ](https://www.youtube.com/@erin_catto ).