How Minie works

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

All C++ source code associated with Minie (including a modified partial snapshot of Bullet, a snapshot of V-HACD, and some "glue code") resides in the Libbulletjme repository. Before instantiating physics objects, a Minie application must dynamically load a native library of this code, compiled for the platform on which the app is executing.

The Libbulletjme project publishes native libraries for the 13 platforms Minie supports:

On desktop platforms, JMonkeyEngine automatically loads the appropriate native library during initialization of the JmeDesktopSystem class if it detects Minie’s NativeMeshUtil class. On Android platforms, the native library is loaded (if present) during static initialization of the JmeAndroidSystem class.

Collision detection is organized around collision objects that interact in the context of a collision space. Collision objects can be soft (varying shape) or rigid (non-varying shape). Rigid objects can be mobile (moving) or static (non-moving). And mobile objects can be dynamic (driven by forces, torques, and impulses) or kinematic (driven directly by external calculations).

In Minie, collision spaces that simulate forces, torques, and impulses are referred to as physics spaces.

By themselves, collision objects are invisible, while scene-graph spatials have no effect on physics. To visualize a collision object, it must be associated with one or more scene-graph spatial(s). For debugging purposes, Minie can visualize collision objects by auto-generating spatials for them. For full-custom visualization, a physics control should be used to associate collision objects with spatials.

Each rigid collision object references a collision shape that describes the shape of its surface. Most collision shapes are scalable, allowing you to grow or shrink objects simply by varying the shape’s scale factors.

A collision object’s absolute location and orientation are quantified in physics-space coordinates, based on a right-handed Cartesian coordinate system. These typically correspond to world coordinates of the scene. However, Minie supports scaling the physics space relative to the scene, in which case the physics-space units (psu) might differ the from world units (wu).

With notable exceptions, Minie doesn’t specify real-world units for distance. Instead, its documentation refers to physics-space units, which could be light-years or millimeters, depending on the application. Nor does Minie specify which axis serves as the "up" direction. If you use a Y-up coordinate system with a psu of one meter, then Minie’s default gravity will be roughly correct for the Earth’s surface. However, there are good reasons to use physics-space units other than meters.

Locations relative to a collision object’s center and subject to its rotation are quantified using local coordinates. The documentation distinguishes scaled local coordinates (measured in psu) from shape coordinates (which depend on scale factors).

Within a physics space, simulation occurs in discrete steps of short duration. While it’s possible to vary these durations from step to step, a fixed duration (or time step) tends to yield more reproducible results.

Each simulation step consists of 4 phases:

Collisions are reported to listeners registered at the space. For fast-moving objects, Minie offers optional continuous collision detection (CCD) using swept spheres. Collisions detected by CCD are reported to those same listeners.

To simplify the creation and management of physics spaces, Minie provides app states. The simplest of these is BulletAppState; it manages a single space without any soft objects or multibodies. Simulation of the space can take place on the render thread or else on a dedicated physics thread. Either way, the app state attempts to synchronize to real time during each rendered frame.

Debug visualization can be enabled or disabled simply by setting a parameter.

Direct buffers used in Minie should have native byte order.

All other native objects created by Minie are carefully tracked using weak references.

Successful initialization of a native library causes Minie to start a daemon thread named "Physics Cleaner". Its purpose is to free any tracked native objects whose corresponding java objects have been garbage collected.

As a performance enhancement, Minie can parallelize certain for-loops on platforms that support OpenMP. To enable this feature, a multithreaded (Mt) native library must be loaded.

For more detail about Bullet physics, download and read the Bullet User Manual.

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