box3d/README.md
2026-05-10 13:36:52 -07:00

98 lines
3 KiB
Markdown

![Box3D Logo](https://box2d.org/images/logo.svg)
# Build Status
[![Build Status](https://github.com/erincatto/box3d/actions/workflows/build.yml/badge.svg)](https://github.com/erincatto/box3d/actions)
# Box3D
Box3D is a 3D physics engine for games.
[![Box3D Version 3.0 Release Demo](https://img.youtube.com/vi/dAoM-xjOWtA/0.jpg)](https://www.youtube.com/watch?v=dAoM-xjOWtA)
## Features
### Collision
- Continuous collision detection
- Contact events
- Convex polygons, capsules, circles, rounded polygons, segments, and chains
- 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
- OpenGL with GLFW
- 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 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)
## 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
- [Manual](https://box2d.org/documentation/)
## 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).