Troubleshooting physics issues

Jolt JNI uses assert statements to verify assumptions made while coding. During development, Java assertions should be enabled using:

  • the "-ea" JVM argument or

  • the enableAssertions setting of Gradle JavaExec tasks.

Similarly, native-code assertions should be enabled during development. You do this by loading a native library with the "Debug" buildtype, such as "com.github.stephengold:jolt-jni-Windows64:1.0.0:DebugSp".

If a native-code assertion fails, it will crash the JVM. To troubleshoot such crashes, attach a native-code debugger (such as GDB) to the JVM itself.

To troubleshoot issues involving native-memory allocation, enable allocation tracing with Jolt.setTraceAllocations(true). Allocation tracing prints a line to the standard output every time Jolt JNI allocates or frees a native object. Allocation tracing requires a "Debug" native library.

Visualization

Many physics issues can be diagnosed visually. For instance, if you neglect to add a body to the physics system, Sport-Jolt will automatically omit it from the visualization.

Sport-Jolt can visualize:

  • collision shapes,

  • the centers of mass of bodies,

  • vehicle wheels,

  • constraints,

  • the edges, faces, and pinned vertices of soft bodies,

  • the origins and local axes of bodies and characters, and

  • the axis-aligned bounding boxes of characters and physics systems.

Color conventions

When visualizing a collision shape, Sport-Jolt uses colors to distinguish different types of physics objects:

  • yellow for rigid body (without contact response) such as a sensor,

  • magenta for a rigid body (with contact response) that’s dynamic, responsive, and active,

  • gray for a rigid body (with contact response) that’s static, kinematic, or deactivated,

  • brown for a character that’s supported, and

  • pink for a character that isn’t supported.

When visualizing a constraint, Sport-Jolt uses:

  • green for visualizing the "body1" end,

  • red for visualizing the "body2" end, and

  • blue for visualizing the pivots.

When visualizing a soft body, Sport-Jolt uses:

  • red for the faces and

  • orange for the edges.

When visualizing coordinate axes, Sport-Jolt uses:

  • red for the +X axis,

  • green for the +Y axis, and

  • blue for the +Z axis.

Summary

  • During development, enable Java assertions and use a "Debug" native library.

  • Sport-Jolt visualization can be used to diagnose physics issues.