How to Configure Double Precision Mode for Large Worlds in Jolt Physics

To enable double precision mode in Jolt Physics, define the JPH_DOUBLE_PRECISION macro before including any Jolt headers and rebuild the library, which switches the internal Real type from float to double and aliases Vec3 to DVec3 for high-precision physics calculations.

The jrouwe/JoltPhysics library supports compile-time double precision configuration to eliminate floating-point drift in massive game worlds. When simulating physics at distances exceeding millions of units from the origin, single-precision floats introduce noticeable jitter and positional errors. This guide explains how to configure double precision mode using the JPH_DOUBLE_PRECISION macro and adapt your code to use 64-bit vector types.

Understanding Double Precision Configuration

Jolt Physics implements double precision as a compile-time switch rather than a runtime setting. The core mechanism resides in Jolt/Math/Real.h, where the Real type is conditionally defined:

#ifdef JPH_DOUBLE_PRECISION
    using Real = double;
#else
    using Real = float;
#endif

When JPH_DOUBLE_PRECISION is defined, the entire library recompiles using 64-bit arithmetic. The public API remains identical, but underlying calculations in Body positioning, Shape intersection tests, and PhysicsSystem simulation use double precision. This change affects Jolt/Math/Vec3.h and Jolt/Math/Mat44.h, which typedef to DVec3 and DMat44 respectively when the macro is active.

Enabling Double Precision Mode

CMake Configuration

The recommended approach is adding the definition to your CMakeLists.txt before the add_subdirectory(Jolt) call:

option(JPH_ENABLE_DOUBLE_PRECISION "Compile Jolt with double precision" OFF)

if (JPH_ENABLE_DOUBLE_PRECISION)
    add_definitions(-DJPH_DOUBLE_PRECISION)
endif()

add_subdirectory(Jolt)

Regenerate your build files with cmake -S . -B build and rebuild the target using cmake --build build --target Jolt.

Manual Definition

For quick testing or non-CMake builds, define the macro before including Jolt/Jolt.h:

#define JPH_DOUBLE_PRECISION
#include "Jolt.h"

int main()
{
    // With the macro active, JPH::Real is double
    // and JPH::Vec3 resolves to JPH::DVec3
    JPH::Real largeCoordinate = 1.0e8;
    JPH::Vec3 position = JPH::Vec3(5.0e8, 0.0, -2.0e8);
}

Working with Double Precision Types

Vector and Matrix Type Aliases

When JPH_DOUBLE_PRECISION is defined, the following typedefs automatically redirect to their explicit double-precision counterparts:

• Real → double (defined in Jolt/Math/Real.h)
• Vec3 → DVec3 (defined in Jolt/Math/Vec3.h)
• Mat44 → DMat44 (defined in Jolt/Math/Mat44.h)

You can still explicitly use DVec3 and DMat44 for clarity in your codebase. These types provide the full 64-bit IEEE 754 range necessary for large-world coordinates.

Body Creation with Large Coordinates

After enabling double precision, create bodies at extreme distances without precision loss:

#include "Jolt.h"

void SpawnSatellite(JPH::PhysicsSystem &system)
{
    // Position 500 million units from origin
    JPH::DVec3 orbitPosition = JPH::DVec3(5.0e8, 0.0, 0.0);
    
    JPH::BodyCreationSettings settings(
        new JPH::BoxShape(JPH::Vec3(100.0f, 100.0f, 100.0f)),
        orbitPosition,                    // DVec3 accepts large coordinates
        JPH::Quat::sIdentity(),
        JPH::EMotionType::Dynamic,
        JPH::Layers::MOVING
    );
    
    JPH::Body *body = system.GetBodyInterface().CreateBody(settings);
    system.GetBodyInterface().AddBody(
        body->GetID(), 
        JPH::EActivation::Activate
    );
}

Debug Rendering Considerations

When rendering gigantic worlds, use the inBaseOffset parameter available in shape classes like Shape::GetSupport to shift the world origin for visualization:

// Shift render origin by 1 million units
JPH::Vec3 worldOffset = JPH::Vec3(1e6f, 0.0f, 0.0f);
renderer.DrawBody(body, worldOffset);

This technique separates the high-precision physics simulation from the single-precision rendering pipeline.

Key Implementation Files

The double precision system spans these critical source files:

• Jolt/Math/Real.h – Defines the Real type alias that switches between float and double based on the JPH_DOUBLE_PRECISION macro.
• Jolt/Math/DVec3.h – Implements the DVec3 class for 64-bit vector arithmetic used in large-world position calculations.
• Jolt/Math/Vec3.h – Contains the Vec3 typedef that conditionally resolves to DVec3 when double precision is enabled.
• Jolt/Math/DMat44.h – Provides double-precision 4×4 transformation matrices for accurate rigid body transforms.
• Jolt/Math/Mat44.h – Defines the Mat44 alias that redirects to DMat44 in double precision builds.
• Jolt/Jolt.h – The central inclusion header that must be included after defining JPH_DOUBLE_PRECISION for the macro to take effect.

Summary

• Define JPH_DOUBLE_PRECISION in your CMake configuration or source code before including Jolt headers to switch the library to 64-bit arithmetic.
• Rebuild the entire Jolt library after changing the precision mode, as the macro affects core type definitions in Jolt/Math/Real.h.
• Use DVec3 and DMat44 explicitly, or rely on the automatic Vec3/Mat44 aliases to handle positions in worlds spanning millions of units without jitter.
• Leverage rendering offsets via inBaseOffset parameters to visualize large worlds while maintaining single-precision graphics pipelines.

Frequently Asked Questions

What is the JPH_DOUBLE_PRECISION macro?

The JPH_DOUBLE_PRECISION macro is a compile-time flag that changes Jolt's internal Real type from 32-bit float to 64-bit double. When defined before including Jolt headers, it causes Vec3 to alias DVec3 and Mat44 to alias DMat44, enabling high-precision physics calculations throughout the engine.

Do I need to change my existing code when enabling double precision?

No API changes are required. Existing code using Vec3, Mat44, and Real continues to function because these types automatically resolve to their double-precision counterparts. However, you should verify that external libraries or rendering code handling Jolt-transformed data can accommodate 64-bit floating-point values.

Does double precision mode affect performance?

Yes, double precision mode increases memory usage for physics data by approximately 100% and may reduce simulation throughput by 10-30% depending on CPU architecture. The trade-off is necessary for large-world accuracy where single-precision artifacts would break simulation stability at extreme coordinates.

Can I mix single and double precision in the same project?

No, Jolt Physics requires a uniform precision mode across the entire library. You cannot link double-precision Jolt objects with single-precision code within the same physics system. However, you can convert between DVec3 and Vec3 explicitly for boundary interfaces with rendering or networking systems that require 32-bit values.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}