# Box3D ![Box3D Logo](https://box2d.org/images/logo.svg) Box3D is a 3D physics engine for games. ## Build status [![Build Status](https://github.com/erincatto/box3d/actions/workflows/build.yml/badge.svg)](https://github.com/erincatto/box3d/actions) ## 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 ### Physics - 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 - Data-oriented design - Written in portable C17 - Extensive multithreading and SIMD - Optimized for large piles of bodies ### Samples - Uses sokol to run with D3D11 on Window, Metal on macOS, and OpenGL 4.3 on Linux - Graphical user interface with imgui - Many samples to demonstrate features and performance ## Building all platforms - Install [CMake](https://cmake.org/) - Install [git](https://git-scm.com/) - Ensure these run from the command line ## Building with CMake presets (recommended) 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). - Windows: `.\build\bin\Release\samples.exe` - Linux: `./build/bin/samples` - macOS: `./build/bin/Release/samples` ## Building for Visual Studio - Install [Visual Studio](https://visualstudio.microsoft.com/) - 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 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. 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. ## Compatibility 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 The user manual lives in [`docs/`](docs/) and is built with Doxygen. Enable the `BOX3D_DOCS` CMake option and build the `doc` target. ## Community - [Discord](https://discord.gg/NKYgCBP) ## Contributing Please do not submit pull requests. Instead, please file an issue for bugs or feature requests. For support, please visit the Discord server. ## Giving feedback Please file an issue or start a chat on discord. You can also use [GitHub Discussions](https://github.com/erincatto/box3d/discussions). ## License Box3D is developed by Erin Catto and uses the [MIT license](https://en.wikipedia.org/wiki/MIT_License). ## Sponsorship 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).