jolt

Jolt Physics, the rigid and soft body physics library (shapes, constraints, queries, characters, vehicles), through C++23 modules, cross-platform deterministic.

English · 简体中文 · Upstream · Releases · mcpp · Index

The upstream C++ API is unchanged: JPH::PhysicsSystem, JPH::BodyInterface, JPH::BoxShape, JPH::Vec3 and every other public name are the upstream entities, in the namespaces upstream declares them in. The library's sources are vendored byte for byte from the 5.6.0 release and built as upstream's CMake build does with CROSS_PLATFORM_DETERMINISTIC on (JPH_CROSS_PLATFORM_DETERMINISTIC, -ffp-contract=off, no fast math), and the same in every profile (JPH_NO_DEBUG: upstream's asserts and debug-only members stay off): the same scene gives the same bits on x86-64, arm64 and wasm32, with any number of worker threads (a pinned hash in the tests). The SIMD level is the target's baseline (SSE2 on x86-64, NEON on arm64), so a binary runs on any machine of its architecture.

Modules

• import mcpplibs.mwrap.jolt;: every public name of the headers under <Jolt/…> — 450 types, 127 functions and operators and 6 objects of JPH, and the names of its nested namespaces (ClosestPoint, HalfFloatConversion, ScaleHelpers, StreamUtils, literals)

More Modules API -> upstream's README

Getting started

mcpp new world --template mcpplibs.mwrap.jolt@5.6.0
cd world
mcpp run

The default template drops a ball on a floor, saves the world on the way down, restores it and runs on again: the ball rests at the same place, bit for bit.

[dependencies]
mcpplibs.mwrap.jolt = "5.6.0"

# For the same bits everywhere: Jolt's inline math is compiled in your units too.
[build]
cxxflags = ["-ffp-contract=off"]

import std;
import mcpplibs.mwrap.jolt;

int main() {
    JPH::RegisterDefaultAllocator();
    JPH::Factory::sInstance = new JPH::Factory();
    JPH::RegisterTypes();
    JPH::PhysicsSystem world;   // Init with your layers, then CreateAndAddBody, Update, SaveState, RestoreState
    JPH::TempAllocatorImpl temp(1024 * 1024);
    JPH::JobSystemSingleThreaded jobs(mcpplibs::mwrap::jolt::cMaxPhysicsJobs);
}

Constants and macros

Fifty static or constexpr (not inline) objects at namespace scope have internal linkage (each includer has its own) and a module cannot export them. They are in mcpplibs::mwrap::jolt (and its nested namespaces of the same names: HalfFloatConversion, HeightFieldShapeConstants, ScaleHelpers) under their names, with their types and values — cMaxPhysicsJobs, cMaxPhysicsBarriers, cDefaultConvexRadius, cDefaultCollisionTolerance, JPH_PI, cBroadPhaseLayerInvalid, cObjectLayerInvalid … — a constant array (sAllSubShapeTypes, sSubShapeTypeNames …) as a std::array of its elements. Two static functions of the narrow phase (ActiveEdges::FixNormal, IsEdgeActive) are internal helpers and not exported. JPH::FPControlWord is exported where upstream declares it (SSE and Arm; not wasm32).

Jolt's macros are configuration (JPH_* switches) and code generation (JPH_DECLARE_RTTI_*, JPH_OVERRIDE_NEW_DELETE, JPH_ASSERT): there is no .macros module. A unit that needs them includes the headers beside the import.

What is and is not wrapped

• Wrapped: every name of the headers in JPH and its nested namespaces (668 in all, the internal ones above among them). tools/surface.py derives the list from the headers as clang reads them.
• A translation unit that also includes the headers (add upstream/jolt to its include path and define JPH_CROSS_PLATFORM_DETERMINISTIC and JPH_NO_DEBUG, as the package does) sees the same entities (tests/header_mix_test.cpp).
• Not here: the debug renderer (JPH_DEBUG_RENDERER), the profiler, the object stream (JPH_OBJECT_STREAM: text and binary serialisation of settings; StateRecorder saves and restores a world without it), the GPU compute backends (DX12, Vulkan, Metal) and their CPU emulation (hair is simulated on them), double precision (JPH_DOUBLE_PRECISION), and the samples, viewer and tests.
• The Web: one thread (JobSystemSingleThreaded); the package links with a 1 MiB stack and growing memory there.

Verification

• mcpp test: a stack of boxes knocked down by a ball that comes to rest on the floor; a ray and a point query; a world saved, run on and restored runs on to the uninterrupted run's bits; a scene's hash after 200 steps pinned, the same with 0, 1 and 4 workers; the adapted constants; header mixing.
• python3 tools/check_exports.py: the module is exactly tools/surface.json; given a clang++ (required on CI's LLVM row) the record is derived again from the headers and compared.
• python3 tools/test_template.py: mcpp new from an installed copy, a strict build, and a run of the generated project.
• CI: Linux x86-64 and arm64 (GCC 16, LLVM 23), macOS and Windows (LLVM 23), each in the dev and release profiles, and wasm32 under node — the same pinned hash on every row.

License

The wrapper is Apache-2.0 (mcpp-community). Jolt Physics is MIT, © 2021 Jorrit Rouwe. Upstream's README and LICENSE are kept in upstream/jolt/ and deployed with a program's licenses. Provenance: upstream/documents.json.