Jolt Physics: A C++ Rigid Body Library Built for Multi Core Game and VR Workloads

The Problem Jolt Physics Solves: Physics That Does Not Own Your Main Thread

Most physics engines assume the simulation step is the centre of the frame and everything else waits for it. Jolt Physics was written around the opposite assumption. The README's design considerations section says the author wanted to address issues found in existing engines, and the first of those is that games do more than simulate physics, and those other things happen across multiple threads.

The concrete claim is about concurrent access outside the main simulation update. Sections of a simulation can be loaded and unloaded in the background: a batch of physics bodies is prepared on a background thread without locking or affecting the simulation, then inserted with what the README describes as minimal impact on performance. Collision queries can run in parallel with adding, removing or updating a body. If the change happened on the same thread, the change is immediately visible; if it happened on another thread, the query sees a consistent before or after state. The README explicitly rejects the alternative of maintaining read and write versions of the world, because that prevents changes from being immediately visible.

The intended audience is therefore narrow and specific: C++ game and VR teams that already have their own job system, their own streaming, and a reason to care that a navigation mesh bake does not stall the frame. If you are writing a small 2D game or a simulation where one physics tick per frame is the whole budget, this architecture is more machinery than you need. The repository is a library, not an engine: there is no renderer, no editor and no scene graph in the top-level layout, which lists Jolt/, Samples/, UnitTests/, PerformanceTest/, HelloWorld/ and JoltViewer/ but nothing resembling a runtime framework.

How Jolt Physics Works: Broad Phase Before the Step, Narrow Phase in the Background

The mechanism for parallel queries is split into two phases. Collision queries can run parallel to the main physics simulation by doing a coarse check (a broad phase query) before the simulation step, then doing fine checks (narrow phase queries) in the background. The README's stated motivation is that long running processes, such as navigation mesh generation, can be spread out across multiple frames.

That is an architectural commitment, not a slogan. It means the broad phase result is a snapshot taken before the step, and the narrow phase work is deferred. A query that starts before the step and finishes after it is answering against the pre-step world. For navigation baking and visibility work that is usually acceptable. For a gameplay query that must reflect a body moved earlier in the same frame, it is not, and you would keep that query on the simulation thread. The README does not offer a third option where a background query waits for the current step to complete.

Two other design decisions follow from the streaming use case. Bodies do not automatically wake up when created, and neighbouring bodies are not woken when a body is removed, because accidental wake-ups cause performance problems when loading and unloading content. The README notes this can be triggered manually if desired. That is a deliberate default in the opposite direction from many engines, and it is the kind of thing that produces a bug report along the lines of "my object is asleep and I never told it to sleep".

The simulation also runs deterministically, and the README points to a Deterministic Simulation section in the documentation to understand the limits. The pitch is that you can replicate a simulation to a remote client by replicating only the inputs. The word limits is doing real work in that sentence; the README does not enumerate them, so treat determinism as a property to verify against the documentation rather than a guarantee you inherit for free.

Installing Jolt Physics and Running the HelloWorld Sample

Jolt Physics ships as source with a CMake build. The repository has a Build/ directory and a HelloWorld/ directory at the top level, which is where the minimal example lives. The README does not include a copy-paste install block, so the steps below follow the repository layout rather than a quoted command list: clone, configure with CMake, build, run the HelloWorld target.

git clone https://github.com/jrouwe/JoltPhysics.git
cd JoltPhysics
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

What you should see is a configured build tree under build/ and, on success, compiled targets including the HelloWorld sample and the UnitTests. The exact generator and target names depend on your platform and CMake generator; on multi-config generators such as Visual Studio the --config Release flag selects the configuration.

The HelloWorld sample is the first real use. It is a small standalone program that sets up a physics system, adds a floor and a falling body, and steps the simulation. There is no window and no renderer in it, which is the point: it isolates the simulation API from any engine integration. The Samples/ directory holds the larger interactive demos referenced from Docs/Samples.md, and Samples/Tests/ contains the individual test cases. If you are integrating rather than exploring, the practical first step is to add the Jolt/ directory to your own build and link it, then port the HelloWorld setup into your engine's update loop. The library is header and source C++; there is no package manager entry documented in the README.

What Jolt Physics Actually Simulates, and Where the Edges Are

The feature list is long, and the shape coverage is the part that decides most integrations. Bodies can be spheres, boxes, capsules, tapered capsules, cylinders, tapered cylinders, convex hulls, planes, compounds, triangle meshes and height field terrain. Continuous collision detection is used across those shapes, which matters for fast-moving thin objects.

Constraints cover fixed, point, distance (including springs), hinge, slider (also called prismatic), cone, rack and pinion, gear, pulley, smooth spline paths, swing-twist for humanoid shoulders, and 6 DOF, with motors to drive them. Collision detection includes ray casting, shape versus shape tests, shape casting, broadphase-only tests, and sensors for trigger volumes.

The character and vehicle support is where the trade-offs are visible. Game character simulation offers a rigid body capsule that moves during the physics simulation, described as the cheapest option and the most accurate collision response between character and dynamic bodies, or a virtual character that has no rigid body and simulates one using collision checks, updated outside the physics update for more control but with less accurate interaction with dynamic bodies. That is a genuine either/or: control versus fidelity, and you pick per project.

Soft bodies support edge constraints, dihedral bend constraints, Cosserat rod constraints, tetrahedron volume constraints, long range attachment constraints (tethers), limiting simulation to stay within a range of a skinned vertex, internal pressure, collision with rigid bodies, and collision tests against soft bodies. There is also a strand-based hair simulation running on GPU, based on Cosserat rods, with guide and follow hairs and hair versus hair collision handled by accumulating average velocity in a grid. The README states that hair collision with the environment only supports ConvexHull and CompoundShapes at the moment. That is a concrete boundary, and it is worth reading before you plan a character pipeline around it. Water buoyancy calculations and an optional double precision mode for large worlds round out the list.

Determinism, Sleeping Bodies and Other Sharp Edges

Determinism is the most over-read feature in the README. It says the simulation runs deterministically and that you can replicate a simulation to a remote client by merely replicating the inputs, then directs you to the Deterministic Simulation documentation to understand the limits. The limits are not spelled out in the README, so anyone building lockstep networking should read that documentation before committing. Determinism across machines with different CPU feature sets is the obvious question, and the required CPU features section (SSE2 minimum on x86/x64, with SSE4.1 through AVX512 as compile options) makes it clear that the build can vary in ways that may matter.

The no-auto-wake default is the second edge. Bodies do not wake on creation and neighbours do not wake on removal. In a streaming world this is exactly right, because otherwise loading a level triggers a cascade of wake-ups. In a small game where you spawn a crate and expect it to fall, it is a surprise the first time. The README says this can be triggered manually, so the fix exists, but you have to know to apply it.

The third edge is scope. The README is direct: the library tries to simulate rigid bodies in the real world but makes approximations, and therefore should mainly be used for games or VR simulations. If you need engineering-grade accuracy, or you are simulating something where a few percent of penetration matters, this is the wrong category of tool regardless of how fast it is.

Finally, the platform list is broad but not universal: Windows x86/x64/ARM64, Linux x86/x64/ARM32/ARM64/RISC-V64/LoongArch64/PowerPC64LE, FreeBSD, Android, Platform Blue (a popular game console) x64, macOS, iOS, MSYS2 MinGW64, and WebAssembly via the separate JoltPhysics.js project. WebAssembly users are on a different repository, not this one.

Jolt Physics vs PhysX, Bullet, Rapier and Godot Physics

The comparison that matters is not feature count but who controls the frame. PhysX and Bullet are both long-established C++ physics libraries with broad shape and constraint coverage, and both have been embedded in engines for years. The difference Jolt Physics argues for is the concurrency model: background preparation of body batches, queries that run parallel to the simulation, and a documented position on what a query sees when a body changes on another thread. If your engine already has a job system and a streaming requirement, that is the axis to compare on, not the shape list.

Rapier is a different proposition. It is built for Rust and, through bindings, for other languages, so the choice is usually made at the language boundary rather than on physics features. If your project is Rust, Jolt Physics is not the natural pick.

Godot Physics is the reference implementation inside Godot, and the question of whether to use Jolt Physics with Godot is really a question about bindings and engine integration, which this repository does not provide. The same applies to Unity: Jolt Physics is a C++ library, and any engine integration is a separate effort.

Box2D is a 2D engine. Jolt Physics is a 3D rigid body library with terrain, soft bodies and hair simulation. The overlap is small, and the choice is usually decided by whether the game is 2D or 3D long before physics is discussed.

One practical note on the comparison: the README cites Horizon Forbidden West and Death Stranding 2: On the Beach as users. Those are shipping titles, which is stronger evidence than any feature table, but it also tells you the integration was done by studios with dedicated engine teams.

Maintenance, Licence and Upgrade Cost

The repository is not archived. The last push was on 2026-09-20, one day before this writing, and the most recent release is v5.6.0 from 2026-07-11, preceded by v5.5.0 on 2025-12-28 and v5.4.0 on 2025-09-27. That cadence suggests releases roughly every six to nine months, with development activity between them.

The licence is MIT, which is permissive and places few obligations on how you ship the library, though you should read LICENSE in full rather than rely on a summary. The repository also contains ContributorAgreement.md and a CLA assistant badge, which means contributing patches upstream involves signing a contributor agreement. That affects you only if you intend to send changes back; it does not restrict using the library.

Upgrade cost is the part that is easy to underestimate. Jolt Physics is a source-level dependency with a CMake build, not a binary package, so an upgrade means rebuilding against the new source and recompiling your integration points. The API surface is broad (shapes, constraints, characters, vehicles, soft bodies, hair), and the release cadence is frequent enough that you should expect to read release notes between versions rather than assume drop-in compatibility. There is no documented ABI stability promise in the README.

A second cost is CPU feature targeting. Because the library can be compiled with SSE2, SSE4.1, SSE4.2, AVX, AVX2 or AVX512 on x86/x64, you are choosing a minimum CPU at build time. Shipping one binary for a wide audience means targeting the lowest common denominator, or building multiple variants.

Editorial conclusion

Adopt Jolt Physics if you are shipping a C++ game or VR title that already owns its threading and asset streaming, and you need collision queries that run alongside the simulation rather than blocking it. Do not adopt it if you want a full engine or a scripting-first workflow: there is no editor and no scene graph, and the README states it should mainly be used for games or VR simulations because it approximates real-world rigid body behaviour. Verify first that your target CPU meets the required feature set (SSE2 on x86/x64, with SSE4.1 through AVX512 as compile options), that your platform appears in the supported list, and that your determinism requirements fit within the limits the Deterministic Simulation documentation describes. The MIT licence keeps integration cost low, but the CLA in ContributorAgreement.md matters if you plan to send patches upstream.

Frequently asked questions

Official sources

1. Issues
2. jrouwe/JoltPhysics on GitHub
3. License: MIT
4. README
5. Releases