A physics simulation is used in games and applications where objects are exposed to physical forces: Think of games like pool billiard and car racing simulators. Massive objects are pulled by gravity, forces cause objects to gain momentum, friction slows them down, solid objects collide and bounce off one another, etc. Action and Adventure games also make use of physics to implement solid obstacles, falling, and jumping.

The jMonkeyEngine3 has built-in support for jBullet Physics (based on Bullet Physics) via the com.jme3.bullet package. This article focuses mostly on the RigidBodyControl, but also introduces you to others.

If you are looking for info on how to respond to physics events such as collisions, read about Physics Listeners.

Bullet physics runs internally at 60fps by default. This rate is not dependent on the actual framerate and it does not lock the framerate at 60fps. Instead, when the actual fps is higher than the physics framerate the system will display interpolated positions for the physics objects. When the framerate is lower than the physics framerate, the physics space will be stepped multiple times per frame to make up for the missing calculations. You create a Bullet PhysicsSpace in jME3 with a com.jme3.bullet.BulletAppState.

Internally, the updating and syncing of the actual physics objects happens in the following way:

1. collision callbacks (BulletAppState.update())
2. user update (simpleUpdate in main loop, update() in Controls and AppStates)
3. physics to scenegraph syncing and applying (updateLogicalState())
4. stepping physics (before or in parallel to Application.render())

When you use this physics simulation, values correspond to the following units:

• 1 length unit (1.0f) equals 1 meter,
• 1 weight unit (1.0f) equals 1 kilogram,
• most torque and rotation values are expressed in radians.

Full code samples are here:

• TestBrickWall.java
• TestQ3.java
• TestSimplePhysics.java
• TestWalkingChar.java

A short overview of how to write a jME application with Physics capabilities:

Do the following once per application to gain access to the physicsSpace object:

1. Make you application extend com.jme3.app.SimpleApplication.
2. Create a BulletAppState field:

   private BulletAppState bulletAppState;

3. Initialize your bulletAppState and attach it to the state manager:

   public void simpleInitApp() {
       bulletAppState = new BulletAppState();
       stateManager.attach(bulletAppState);

BulletAppState bas = app.getStateManager().getState(BulletAppState.class);

For each Spatial that you want to be physical:

1. Create a CollisionShape.
2. Create the PhysicsControl from the CollisionShape and a mass value.
3. Add the PhysicsControl to its Spatial.
4. Add the PhysicsControl to the PhysicsSpace.
5. Attach the Spatial to the rootNode (as usual).
6. (Optional) Implement the PhysicsCollisionListener interface to respond to PhysicsCollisionEvents.

Let's look at the details:

A CollisionShape is a simplified shape for which physics are easier to calculate than for the true shape of the model. This simplication approach speeds up the simulation greatly.

Before you can create a Physics Control, you must create a CollisionShape from the com.jme3.bullet.collision.shapes package. (Read the tip under "PhysicsControls Code Samples" how to use default CollisionShapes for Boxes and Spheres.)

All non-mesh CollisionShapes can be used for dynamic, kinematic, as well as static Spatials. (Code samples see below)

The mesh-accurate shapes can use a CollisionShapeFactory as constructor (code samples see below).

bulletAppState.getPhysicsSpace().enableDebug(assetManager);

• One way of using a constructor and a Geometry's mesh for static Spatials:

  MeshCollisionShape level_shape = 
      new MeshCollisionShape(level_geo.getMesh());

• One way of using a constructor and a Geometry's mesh for dynamic Spatials:

  HullCollisionShape shape = 
      new HullCollisionShape(katamari_geo.getMesh());

• Creating a dynamic compound shape for a whole Node and subnodes:

  CompoundCollisionShape myComplexShape =
      CollisionShapeFactory.createMeshShape((Node) myComplexGeometry );

• Creating a dynamic HullCollisionShape shape (or CompoundCollisionShape with HullCollisionShapes as children) for a Geometry:

  CollisionShape shape = 
      CollisionShapeFactory.createDynamicMeshShape(spaceCraft);

• An angular, non-mesh-accurate compound shape:

  CompoundCollisionShape boxShape =
      CollisionShapeFactory.createBoxCompoundShape((Node) crate_geo);

• A round, non-mesh-accurate compound shape:

  SphereCollisionShape sphereShape =
      new SphereCollisionShape(1.0f);

BulletPhysics are available in jME3 through PhysicsControls classes from the com.jme3.bullet.control package. jME3's PhysicsControl classes directly extend BulletPhysics objects and are the recommended way to use physics in a jME3 application. PhysicsControls are flexible and can be added to any Spatial to make it act according to physical properties.

Click the links for details on the special PhysicsControls. This article is about RigidBodyControl.

The PhysicsControl constructors expect a Collision Shape and a mass (a float in kilogram). The most commonly used PhysicsControl is the RigidBodyControl:

RigidBodyControl myThing_phys = 
    new RigidBodyControl( myThing_shape , 123.0f ); // dynamic

RigidBodyControl myDungeon_phys = 
    new RigidBodyControl( myDungeon_shape , 0.0f ); // static 

The following creates a box Geometry with the correct default BoxCollisionShape:

Box b = new Box(1,1,1);
Geometry box_geo = new Geometry("Box", b);
box_geo.addControl(new RigidBodyControl( 1.0f )); // explicit non-zero mass, implicit BoxCollisionShape

The following creates a MeshCollisionShape for a whole loaded (static) scene:

...
gameLevel.addControl(new RigidBodyControl(0.0f)); // explicit zero mass, implicit MeshCollisionShape

For each physical Spatial in the scene:

1. Add a PhysicsControl to a Spatial.

   myThing_geo.addControl(myThing_phys);

2. Remember to also attach the Spatial to the rootNode, as always!

The PhysicsSpace is an object in BulletAppState that is like a rootNode for Physics Controls.

• Just like you add the Geometry to the rootNode, you add its PhysicsControl to the PhysicsSpace.

  bulletAppState.getPhysicsSpace().add(myThing_phys); 
  rootNode.attachChild(myThing_geo); 

• When you remove a Geometry from the scene and detach it from the rootNode, also remove the PhysicsControl from the PhysicsSpace:

  bulletAppState.getPhysicsSpace().remove(myThing_phys);
  myThing_geo.removeFromParent();

The PhysicsSpace also manages global physics settings. Typically, you can leave the defaults, and you don't need to change the following settings:

• Specify physics accuracy.

  bulletAppState.getPhysicsSpace().setAccuracy(1f/60f;);

• Specify global gravity.

  bulletAppState.getPhysicsSpace().setGravity(new Vector3f(0, -9.81f, 0));

• Specify the size of the physics space as two opposite corners (only applies to AXIS_SWEEP broadphase).

  bulletAppState.getPhysicsSpace().setWorldMax(new Vector3f(10000f, 10000f, 10000f));
  bulletAppState.getPhysicsSpace().setWorldMin(new Vector3f(-10000f, -10000f, -10000f));

After you have registered, attached, and added everything, you can adjust physical properties or apply forces.

On a RigidBodyControl, you can set the following physical properties.

On a RigidBodyControl, you can apply the following physical forces:

All physical objects…

• must not overlap.
• can detect collisions and report several values about the impact.
• can respond to collisions dynamically, or statically, or kinematically.

• Kinematics are solid and characters can "stand" on them.
• When they collide, Kinematics push dynamic objects, but a dynamic object never pushes a Kinematic.
• You can hang kinematics up "in mid-air" and attach other PhysicsControls to them using hinges and joints. Picture them as "air hooks" for flying aircraft carriers, floating islands in the clouds, suspension bridges, swings, chains…
• You can use Kinematics to create mobile remote-controlled physical objects, such as moving elevator platforms, flying blimps/airships. You have full control how Kinematics move, they never "fall" or "topple over".

Use the following methods to move dynamic physical objects.

PhysicsControls also support the following advanced features:

• Multiple Objects Too Slow? Do not overuse PhysicsControls. Although PhysicsControls are put to “sleep” when they are not moving, creating a world solely out of dynamic physics objects will quickly bring you to the limits of your computer's capabilities.
  Solution: Improve performance by replacing some physical Spatials with non-physical Spatials. Use the non-physical ones for non-solid things for which you do not need to detect collisions – foliage, plants, effects, ghosts, all remote or unreachable objects.

• Complex Shape Too Slow? Breaking the level into manageable pieces helps the engine improve performance: The less CPU-intensive broadphase filters out parts of the scene that are out of reach. It only calculates the collisions for objects that are actually close to the action.
  Solution: A huge static city or terrain model should never be loaded as one huge mesh. Divide the scene into multiple physics objects, with each its own CollisionShape. Choose the most simple CollisionShape possible; use mesh-accurate shapes only for the few cases where precision is more important than speed. For example, you can use the very fast PlaneCollisionShape for flat streets, floors and the outside edge of the scene, if you keep these pieces separate.

• Buggy? If you get weird behaviour, such as physical nodes jittering wildy and being ejected "for no apparent reason", it means you have created an impossible state – solid objects overlapping. This can happen when you position solid spatials too close to other solid spatials, e.g. when moving them with setLocalTranslation().
  Solution: Use the debug mode to make CollisionShapes visible and verify that CollisionShapes do not overlap.

  bulletAppState.getPhysicsSpace().enableDebug(assetManager);

• Need more interactivity? You can actively control a physical game by triggering forces. You may also want to be able respond to collisions, e.g. by substracting health, awarding points, or by playing a sound.
  Solution: To specify how the game responds to collisions, you use Physics Listeners.