Java runtime behavior

This page document the general behavior of the java runtime and how the objects interacts with the libraries.

At the time of writing, this runtime does not follow any MVC pattern.

Specific naming convention in the runtime

• system scope : refer to the world concept in the Physics language
• world : refer to an runtime simulated world World, which contains both the ode4j DWorld instance and all the objects in the simulation

Main behavior of a simulation

Both the rendering and simulation loops are scheduled with the rendering loop. The Renderer class is responsible for initializing the rendering of the library, and interact with a Simulation instance (implementation of RendererCallback). For multiple simulations (alternative views), the CompositeRendererCallback is used to hold multiple Simulation class and splits the rendering into sections of the window.

For the initialization part, the generated code of our simulation interface between the renderer (the Simulation class is inherited and provided to the renderer) and the simulation objects (PhysicalEntity) and worlds (SystemScope). It is responsible for setting all the initial properties of the PhysicalEntity instances, all those objects are grouped into a instance of the World class.

After initialization, the built-in part of the Simulation class takes over. For each rendering step of the renderer (which calls render in the simulation), the Simulation object :

• set the camera (using overidden methods)
• render the world (all the objects through the World class, call the rendering of each PhysicalEntity)
• make a simulation step

Behavior of PhysicalEntity instances

Rendering / shape

The rendering part of the objects is initialized through the styles map in PropertiesBuilder. This object is also responsible for instanciating properties of the PhysicalEntity from the styles.

The rendering is based on a Fixture object, which is responsible for setting both the simulated shape (and mass distribution of the object) and provide methods to render the object.

On the simulation part, a fixture provide a DMass and a DGeom object, containing data about mass distribution and shape of the object (used for collisions and rotations).

As for the rendering, a processing PShape object is instanciated though the various Fixture implementations (BoxFixture, SphereFixture...). This object is used on each rendering and is not modified (unless merging with another object, which modify the shape).

Physical simulation

The physical object used in the ode4j library is a DBody. It is responsible for simulation the position, speed, acceleration of the object.

It is attached to a DMass to define the mass of the object, used for forces (both linear or rotational).

The collisions between object are handled in the World class (details below) through a DSpace object (containing all the shapes of the object). Each PhysicalEntity has a DGeom stored in this DSpace and bound to the object DBody, allowing collisions to be computed.

As mentioned before, both the DMass and DGeom objects are instanciated and linked to the DBody through the fixture (bindToBody method).

Collision handling

The collision handling takes place in the World class, where the detection occurs through a DSpace object. When a collision is detected between two objects, both objects collision reaction (defined in styles) is taken. The one with greater priority (reaction priority, or if equals, object with higher mass) is executed first. Then if the first reaction allows the second one to be done and the second one is different, the reaction of the second object is performed.

Both the reaction, the priority and the interaction with other reaction if defined in a CollisionReaction instance, having the following methods.

Name	Purpose
getPriority	Returns the default priority for the collision reaction, high value mean high priority
react	Apply the collision reaction between the two objects. If both objects have the same reaction (other object reaction equals to the current CollisionReaction object), then the collision must be applied on both object (since the second wont be called)
preventDifferentReaction	Returns a boolean to indicate whether the collision reaction prevent different reactions from happening

The most simple collisions are defined in the enum SimpleCollisionReaction, other collision reaction (that requires parameters for example) may have their own classes (such as ElasticCollisionReaction).