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

> Configure double precision mode in Jolt Physics for large worlds. Define JPH_DOUBLE_PRECISION before including headers and rebuild for enhanced accuracy.

- Repository: [Jorrit Rouwe/JoltPhysics](https://github.com/jrouwe/JoltPhysics)
- Tags: how-to-guide
- Published: 2026-07-17

---

**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`](https://github.com/jrouwe/JoltPhysics/blob/main/Jolt/Math/Real.h), where the `Real` type is conditionally defined:

```cpp
#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`](https://github.com/jrouwe/JoltPhysics/blob/main/Jolt/Math/Vec3.h) and [`Jolt/Math/Mat44.h`](https://github.com/jrouwe/JoltPhysics/blob/main/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`](https://github.com/jrouwe/JoltPhysics/blob/main/CMakeLists.txt) before the `add_subdirectory(Jolt)` call:

```cmake
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`](https://github.com/jrouwe/JoltPhysics/blob/main/Jolt/Jolt.h):

```cpp
#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`](https://github.com/jrouwe/JoltPhysics/blob/main/Jolt/Math/Real.h))
- **`Vec3`** → `DVec3` (defined in [`Jolt/Math/Vec3.h`](https://github.com/jrouwe/JoltPhysics/blob/main/Jolt/Math/Vec3.h))
- **`Mat44`** → `DMat44` (defined in [`Jolt/Math/Mat44.h`](https://github.com/jrouwe/JoltPhysics/blob/main/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:

```cpp
#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:

```cpp
// 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`](https://github.com/jrouwe/JoltPhysics/blob/main/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`](https://github.com/jrouwe/JoltPhysics/blob/main/Jolt/Math/DVec3.h)** – Implements the `DVec3` class for 64-bit vector arithmetic used in large-world position calculations.
- **[`Jolt/Math/Vec3.h`](https://github.com/jrouwe/JoltPhysics/blob/main/Jolt/Math/Vec3.h)** – Contains the `Vec3` typedef that conditionally resolves to `DVec3` when double precision is enabled.
- **[`Jolt/Math/DMat44.h`](https://github.com/jrouwe/JoltPhysics/blob/main/Jolt/Math/DMat44.h)** – Provides double-precision 4×4 transformation matrices for accurate rigid body transforms.
- **[`Jolt/Math/Mat44.h`](https://github.com/jrouwe/JoltPhysics/blob/main/Jolt/Math/Mat44.h)** – Defines the `Mat44` alias that redirects to `DMat44` in double precision builds.
- **[`Jolt/Jolt.h`](https://github.com/jrouwe/JoltPhysics/blob/main/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`](https://github.com/jrouwe/JoltPhysics/blob/main/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.