Troubleshooting physics issues

Libbulletjme 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, by loading a native library of the "debug" type, such as "Linux64DebugSp_libbulletjme.so".

Visualization

Many physics issues can be diagnosed visually. For instance, if you neglect to add a collision object to the physics space, SPORT will automatically omit it from the visualization.

SPORT can be used to visualize:

  • collision shapes,

  • vehicle wheels,

  • physics joints,

  • soft bodies,

  • the centers and local axes of collision objects, and

  • the axis-aligned bounding boxes of collision objects.

Color conventions

When visualizing a collision shape, SPORT uses colors to distinguish different types of collision objects:

  • yellow for an object without contact response, including any ghost object,

  • magenta for a rigid body (or collider) that’s dynamic, responsive, and active,

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

  • brown for a character that’s grounded, and

  • pink for a character (with contact response) that isn’t grounded.

When visualizing a physics joint, SPORT uses:

  • green for a "A" end and

  • red for a "B" end.

When visualizing a soft body, SPORT uses:

  • red for the faces and

  • orange for the links.

When visualizing coordinate axes, SPORT uses:

  • red for the +X axis,

  • green for the +Y axis, and

  • blue for the +Z axis.

When visualizing bounding boxes, SPORT uses:

  • red for a ghost object whose overlapping count has increased,

  • green for a ghost whose count has decreased,

  • yellow for a ghost whose count is unchanged, and

  • white for a non-ghost collision object.

An introduction to PhysicsDumper

The following temporary statements could be used to dump (to System.out) all collision objects in a physics space:

PhysicsDumper dumper = new PhysicsDumper();
dumper.dump(physicsSpace);

Here is sample output for a space containing 2 rigid bodies and nothing else:

PhysicsSpace with 0 chars, 0 ghosts, 0 joints, 2 rigids, 0 vehicles
 bphase=DBVT grav[y=-9.81] timeStep[0.0166667 maxSS=4] listeners[c=0 t=1]
 solver[SI iters=10 cfm=0 batch=128 splitImp[th=global erp=0.1] mode=WarmStart,VelocityDependent,SIMD,Cone]
 rayTest=SubSimplex,HeightfieldAccel
  Rigid Kin msLoc[x=-0.243501 y=-0.317344]
   contact[fric=0.5 rest=0 damp=0.1 pth=1e+18 stiff=1e+18]
   Sphere r=1 marg=0
   with 0 ignores and 0 joints
  Rigid Dyn(mass=2) msLoc[x=3.39744 y=-4.02647] loc[x=3.42799 y=-4.13896] orient[x=0 y=0 z=-0.24 w=0.971]
   contact[fric=0.5 rest=0 damp=0.1 pth=1e+18 stiff=1e+18]
   grav[y=-9.81] NOTprotected ccd[mth=0] damp[l=0 a=0] sleep[lth=0.8 ath=1 time=0]
   v[x=2.96385 y=-10.9131] force[xyz=0] lFact[xyz=1]
   inert[xyz=0.8] w[z=-0.714854] torq[xyz=0] aFact[xyz=1]
   Sphere r=1 marg=0
   with 0 ignores and 0 joints

2-space indentation indicates the hierarchy of spaces/objects/joints. Single-space indentation indicates additional description of the foregoing object. Related values are enclosed in square brackets.

To dump a physics space to a text file:

PrintStream dumpStream = new PrintStream("dump.txt");
PhysicsDumper dumper = new PhysicsDumper(dumpStream);
dumper.dump(physicsSpace);

What is dumped

You can dump specific collision objects:

dumper.dump(character);
dumper.dump(multiBodyCollider);
dumper.dump(ghostObject);
dumper.dump(rigidBody);
dumper.dump(softBody);

You can dump specific collision shapes:

dumper.dump(collisionShape, "");

When dumping a space, the default is to describe every collision object; physics joints are counted but not described in detail. To describe the joints in each body, configure the dumper like so:

dumper.setEnabled(DumpFlags.JointsInBodies, true); // default=false

To describe the motors in each joint, configure the dumper like so:

dumper.setEnabled(DumpFlags.Motors, true); // default=false

To dump just the physics joints (no collision objects):

dumper.setEnabled(DumpFlags.Pcos, false); // default=true
dumper.setEnabled(DumpFlags.JointsInSpaces, true); // default=false

Other dump flags can be set to describe the nodes or clusters in each soft body or the child shapes in each compound collision shape.

Summary

  • During development, enable Java assertions and use debug-enabled libraries.

  • SPORT visualization can be used to diagnose issues.

  • To obtain detailed information about scenes and physics, use a dumper.