Jolt Physics

Purpose

modules/jolt_physics/ integrates Jolt Physics — a fast, accurate, multi-threaded rigid-body dynamics library by Jorrit Rouwe — as a Godot 3D PhysicsServer3D backend. The Jolt source is vendored under thirdparty/jolt. As of recent Godot versions, Jolt is the recommended 3D physics engine; the in-tree godot_physics_3d backend remains as a fallback.

Directory layout

modules/jolt_physics/
├── jolt_physics_server_3d.{cpp,h}     PhysicsServer3DExtension subclass that proxies to Jolt
├── joints/                             Per-joint adapter classes (HingeJolt, SliderJolt, …)
├── shapes/                             Collision shape adapters (BoxShapeJolt, ConvexHullShapeJolt, …)
├── spaces/                             JoltSpace3D — wraps Jolt's PhysicsSystem per Godot space
├── objects/                            JoltBody3D, JoltArea3D, JoltSoftBody3D
├── misc/                               Filter/listener glue, debug drawing
├── doc_classes/                        XML class reference for Jolt-specific properties
├── icons/, register_types.cpp, SCsub, config.py
└── README, LICENSE                     Upstream notice

Integration

Selecting Jolt is a project-settings switch:

[physics]
3d/physics_engine="Jolt Physics"

When set, Main::setup2 constructs JoltPhysicsServer3D instead of GodotPhysicsServer3D. The WrapMT shim is the same — Jolt's public API is wrapped behind PhysicsServer3DExtension, so all standard Godot physics nodes (RigidBody3D, CharacterBody3D, StaticBody3D, Area3D, SoftBody3D, joints, shapes) work unchanged.

How calls flow

graph LR
    Node[RigidBody3D] -->|body_apply_impulse| Server[JoltPhysicsServer3D]
    Server -->|JPH::BodyInterface| JoltBody[JoltBody3D]
    JoltBody --> Jolt[Jolt PhysicsSystem]
    Jolt -->|step| Body[JPH::Body]
    Body -->|state callback| JoltBody
    JoltBody -->|transform sync| Node
    Server -->|space_step| JoltSpace3D
    JoltSpace3D --> Jolt

JoltSpace3D (spaces/jolt_space_3d.cpp) wraps a JPH::PhysicsSystem per Godot space. Each Body3D / Area3D / SoftBody3D Godot node maps to a JPH::Body. The adapter layer translates between Godot's Variant-based API and Jolt's typed C++ API, including unit conversions, sleep state propagation, and contact reporting.

Features

• Discrete and continuous collision detection (CCD) per body.
• A pluggable BroadPhaseLayer setup so users can group bodies by interaction layer.
• Soft bodies (SoftBody3D works against Jolt's soft body system).
• Full set of joints: hinge, slider, fixed, cone-twist, generic 6DOF, plus pin (translated from Godot's joint definitions).
• Vehicle physics (Jolt's vehicle constraint system; exposed via Godot's VehicleBody3D + VehicleWheel3D).
• Multi-threaded simulation (Jolt has its own job system; the Godot integration uses Godot's WorkerThreadPool as the job runner).

Project settings

Project settings under physics/jolt_3d/ expose Jolt-specific tuning:

• Sleep thresholds.
• Contact / penetration tolerances.
• Solver iteration counts.
• Time-step substepping.
• Memory budget for the temp allocator.

The defaults are tuned for typical games; advanced users can override per-project.

Key abstractions

Abstraction	File	Role
JoltPhysicsServer3D	modules/jolt_physics/jolt_physics_server_3d.cpp	The PhysicsServer3DExtension
JoltSpace3D	modules/jolt_physics/spaces/jolt_space_3d.cpp	One JPH::PhysicsSystem per Godot space
JoltBody3D / JoltArea3D / JoltSoftBody3D	modules/jolt_physics/objects/	Per-body adapters
JoltShape3D family	modules/jolt_physics/shapes/	Collision shape adapters
JoltJoint3D family	modules/jolt_physics/joints/	Joint adapters

Integration points

• The standard Godot physics nodes (scene/3d/physics/) talk to PhysicsServer3D and are oblivious to which backend is active. Switching is a config change.
• Vehicle simulation reuses Godot's vehicle node API but lifts onto Jolt's vehicle constraint when Jolt is active.
• Soft body cloth simulation is supported — the Godot SoftBody3D node delegates to Jolt for cloth dynamics.

Entry points for modification

• New shape type → declare in shapes/, implement creation in JoltPhysicsServer3D::shape_create. Make sure the existing Shape3D resource also registers the new type (most projects only need shapes already supported).
• Tuning the simulation → project settings under physics/jolt_3d/* are the first stop; see also JoltPhysicsServer3D::_init_default_options.
• Updating Jolt → bump the vendored copy under thirdparty/jolt/ and patch the adapter layer for any breaking API changes.