How to use JoltPhysics: clone, build and add rigid body physics

What JoltPhysics is and who it is for

JoltPhysics (repository jrouwe/JoltPhysics) is a multi core friendly rigid body physics and collision detection library written in C++. It calculates how rigid objects move, bump into each other and connect through joints. The README says it is suitable for games and VR applications and is used by Horizon Forbidden West and Death Stranding 2: On the Beach.

The README describes only a library, not an editor or a game engine. You integrate it into your own code.

• Good fit: C++ game developers who need rigid bodies and collisions.
• Good fit: VR developers building interactive objects.
• Good fit: teams that want multithreaded physics updates and background collision queries.
• Good fit: developers who need deterministic simulation, replicating state by sending inputs.
• Not a fit: projects that need an editor or engine out of the box, or non-C++ code without a binding (the README points to a separate WebAssembly project, JoltPhysics.js).

Check the prerequisites before you start

The README lists the supported compilers: Visual Studio 2022 or later, Clang 16 or later, or GCC 12 or later. It also uses CMake, and points to a Build section and a CMake FetchContent example for integration.

The library uses C++17, depends only on the standard template library, does not use RTTI and does not use exceptions. On x86 and x64 the minimum CPU requirement is SSE2, and it can be compiled with SSE4.1, SSE4.2, AVX, AVX2 or AVX512.

• Compiler: Visual Studio 2022+, Clang 16+ or GCC 12+.
• Build system: CMake.
• Language standard: C++17.

Clone the repository and build it

The install method is clone-and-build. Start by cloning the repository from GitHub. The README then sends you to its Build section (Build/README.md) for build instructions, so follow that file for the exact steps on your platform.

Integrate it with CMake FetchContent

If you would rather not manage a clone yourself, the README links a HelloWorld example that uses CMake FetchContent to show how to add Jolt to a CMake project. Use that example as a reference for wiring the library into your own build.

Learn from the HelloWorld example and the samples

The README suggests starting with the HelloWorld example (HelloWorld/HelloWorld.cpp). Every feature in Jolt has its own sample, and running the Samples application (Docs/Samples.md) and reading the code in Samples/Tests is a practical way to learn the API.

For the full architecture and API reference, the README links the latest documentation at jrouwe.github.io/JoltPhysics. Documentation for a specific release is also available. When upgrading from an older version, read the Release Notes or API Changes documents.

• HelloWorld/HelloWorld.cpp: the starting example.
• Docs/Samples.md: how to run the samples.
• Samples/Tests: code for each feature.
• Docs/ReleaseNotes.md and Docs/APIChanges.md: for upgrades.

Know the feature set and the platform support

Jolt supports rigid bodies of many shapes, including sphere, box, capsule, convex hull, mesh and terrain (height field). It also covers many constraints such as hinge, slider, cone, gear and 6 DOF, plus sensors, character simulation, vehicles, soft bodies and water buoyancy. An optional double precision mode is available for large worlds.

The README lists Windows, Linux, FreeBSD, Android, macOS, iOS and MSYS2 MinGW64 among supported platforms. Platform Blue support requires your own build environment and a PlatformBlue.h file that the README says is available on the Platform Blue developer forum, due to NDA requirements.

• Bodies: sphere, box, capsule, cylinder, convex hull, plane, compound, mesh, terrain.
• Constraints: fixed, point, distance, hinge, slider, cone, rack and pinion, gear, pulley, 6 DOF and more.
• Characters: rigid body character and virtual character (capsule).
• Vehicles: wheeled, tracked and motorcycles.

Understand the design choices that matter for multithreading and networking

The README says Jolt is designed to spread work across CPU cores. Collision queries can run in parallel with body changes and with the main simulation step. Bodies do not wake up automatically when created, which avoids performance problems when content loads.

The simulation is deterministic, so you can replicate it to a remote client by replicating its inputs. The README says to read the Deterministic Simulation section to understand the limits. The library makes approximations for games and VR, so it is not meant for exact real-world engineering.