How Jolt JNI works

For physics simulation and collision detection, Jolt JNI uses Jolt Physics, a modern, open-source, 3-D physics simulator, released under an MIT license.

To enable efficient simulation of complex moving shapes, Jolt JNI also incorporates Khaled Mamou’s Volumetric-Hierarchical Approximate Convex Decomposition (V-HACD) algorithm, released under a 3-Clause BSD License.

Native libraries

Jolt Physics and V-HACD are written in C++, so Jolt JNI uses the Java Native Interface (JNI) to access their objects and methods.

Before instantiating physics objects, a Jolt-JNI app must dynamically load a native library of this code, compiled for the platform on which the app is executing.

The Jolt-JNI project publishes native libraries for 12 different platforms:

  • Windows (x86-64 with and without AVX2),

  • Linux (x86-64 with and without FMA, armhf, and aarch64),

  • macOS (x86-64 and ARM64), and

  • Android (armeabi-v7a, arm64-v8a, x86, and x86_64).

32-bit and 64-bit versions of the same operating system count as distinct platforms!

For each platform, Jolt JNI builds 2 types of libraries:

  • "Debug" (for development, debugging, and functional testing) and

  • "Release" (for performance testing and production use).

Furthermore, native libraries come in 2 flavors:

All these native libraries share a common API, so a single JVM library suffices.

Bodies, physics systems, and shapes

Collision detection is organized around bodies and constraints that interact in the context of a physics system.

Bodies can be soft (varying shape) or rigid (non-varying shape). Rigid bodies can be moving or static (non-moving). And moving bodies can be dynamic (driven by forces, torques, and impulses) or kinematic (driven directly by external calculations).

  • bodies (Body class)

    • soft bodies

    • rigid bodies

      • moving

        • dynamic

        • kinematic

      • static

  • constraints (Constraint abstract class)

Each rigid body references a collision shape that describes the shape of its surface.

Coordinate systems and units

A body’s absolute location and orientation are quantified in system coordinates (also known as world space), a right-handed Cartesian coordinate system.

Dimensions and distances are nominally in meters. Simulation is most accurate for dynamic objects between 0.1 and 10 meters in size, with speeds under 500 meters per second. Static object should be 0.1 to 2,000 meters in size. To simulate outside these ranges, scale dimensions and distances accordingly.

In the JVM library, double-precision floating point is always used to represent locations in system coordinates. If all simulation takes place within roughly 5,000 meters of the origin, single-precision native libraries provide sufficient accuracy. For larger worlds, use double-precision native libraries.

Jolt JNI doesn’t require a particular "up" direction. However, the "up" directions for characters, heightfields, and vehicles all default to +Y, and the direction of gravity defaults to -Y.

Masses are nominally in kilograms.

Locations relative to a shape’s origin and subject to its rotation are quantified using local coordinates.

Discrete time and collision detection

Physics simulation occurs in discrete steps of short duration.

For fast-moving rigid bodies, Jolt JNI offers optional continuous collision detection (CCD) using linear casting.

Direct buffers, garbage collection, and threading

Direct buffers used in Jolt JNI should have native byte order.

All other native objects created by Jolt JNI are carefully tracked using weak references. Invocation of the JoltPhysicsObject.startCleaner() method starts a daemon thread. The thread’s purpose is to free any native objects owned by Java objects that have been garbage collected.

Multi-threaded simulation is built into Jolt JNI. The number of worker threads is configured into a JobSystem that’s typically created during initialization.

Next steps

For more detail about how Jolt Physics works, refer to the Jolt Physics website.

To gain hands-on experience, proceed to the first tutorial page.