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 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).

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, based on a right-handed Cartesian coordinate system.

Jolt JNI doesn’t require a particular "up" direction. However, the "up" direction for characters defaults to +Y, and the direction of gravity in a physics system defaults to -Y.

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

Dimensions and distances are specified in meters.

Discrete time and collision detection

Physics simulation occurs in discrete steps of short duration.

For fast-moving 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.