GameTools physics.xml

Objects that interact with each other (vehicles, terrain, buildings, packing crates, etc) require an XML file to describe how they are represented as physical entities. These files are named with the same name as Java plugin files - but they reside in the 'physics' directory and have a '.xml' file. (eg physics/Jeep.xml).

Example

Here is an example of a physics '.xml' file:

<?xml version="1.0" ?>
<physicsobject>
  <properties
    static                 = "false"
    mass                   = "1000"
    friction               = "0.5"
  />
  <shape>
    <box x_size  ="2.0" y_size  ="5.0"  z_size  ="1.0"
         x_offset="0.0" y_offset="-0.2" z_offset="1.0" />
  </shape>
</physicsobject>

Structure

Since this is an XML 'level' file, the first three lines must always be:

<?xml version="1.0" ?>

A variety of physics behavioral models are supported - each has it's own outer level tags. Currently:

• <physicsobject>...</physicsobject>

  For most objects in the world.

• <physicsvehicle>...</physicsvehicle>...

  For wheeled ground vehicles, trucks, cars, etc.

Physics Object

The <physicsobject> tag has one attribute:

 <physicsobject name="Name">

It contains further records:

Physical Properties:

These are the basic physical properties of the object mass, friction, drag, etc:

 <properties static           ="boolean'"
             mass             ="float (kg)"
             friction         ="float"
             linear_drag      ="float"
             angular_drag     ="float"
             motion_threshold ="float (m/s)" />

Reasonable defaults are provided for each of the fields.

Constrained child objects

Any object can have 'child' objects that are constrained to move with it in some way. These may be driven by their own Java behavior plugin, by the plugin of the parent object - or simply left to move passively in response to other things that happen in the physics world. A child object can move relative to it's parent in any, all or none of six degrees of freedom: X, Y, Z, Heading, Pitch or Roll. Each axis can allow motion in an unlimited manner, according to 'hard' limits or be locked to the parent object so the child cannot move in that axis. The default is for all axes to be locked at their zero position.

 <constraint name="Name"  src="model filename">
   <lockX  value="float (meters)"  />
   <lockY  value="float (meters)"  />
   <lockZ  value="float (meters)"  />
   <lockH  value="float (degrees)" />
   <lockP  value="float (degrees)" />
   <lockR  value="float (degrees)" />

   <freeX />
   <freeY />
   <freeZ />
   <freeH />
   <freeP />
   <freeR />

   <limitX low="float (meters)" high="float (meters)" />
   <limitY low="float (meters)" high="float (meters)" />
   <limitZ low="float (meters)" high="float (meters)" />
   <limitH low="float (meters)" high="float (meters)" />
   <limitP low="float (meters)" high="float (meters)" />
   <limitR low="float (meters)" high="float (meters)" />
 </constraint> 

There can be multiple constraint records corresponding to multiple child objects. The "Name" field indicates where the Java behavior and child's physics model may be found. The "src" field indicates where the polygonal model may be found.

NOTE: Because Java plugins can change the mode of each axis between lock/free/limit, it is legal to provide all three of the 'lock' and 'limit' parameters (value/low/high) with any of the lock/free/limit tags in order that you may (for example) set limits for a usually locked axis. When the script switches the mode from locked to limit, the values specified in the 'lock' record will take effect.

Physical Shape

The physics software consumes vastly too much CPU time if the collision behavior of each object is defined by a complex polygonal outline. Generally we need to represent objects as much simpler shapes - cubes, spheres, etc.

The 'shape' record allows you to define that simpler shape using some number of basic 3D primitives:

 <shape>
   <box       x_size  ="float (meters)"
              y_size  ="float (meters)"
              z_size  ="float (meters)"
              x_offset="float (meters)"
              y_offset="float (meters)"
              z_offset="float (meters)"
              h_offset="float (degrees)"
              p_offset="float (degrees)"
              r_offset="float (degrees)"
   />
   <zcone     radius  ="float (meters)"
              length  ="float (meters)"
              x_offset="float (meters)"
              y_offset="float (meters)"
              z_offset="float (meters)"
              h_offset="float (degrees)"
              p_offset="float (degrees)"
              r_offset="float (degrees)"
   />
   <xcylinder radius  ="float (meters)"
              length  ="float (meters)"
              x_offset="float (meters)"
              y_offset="float (meters)"
              z_offset="float (meters)"
              h_offset="float (degrees)"
              p_offset="float (degrees)"
              r_offset="float (degrees)"
   />
   <ycylinder radius  ="float (meters)"
              length  ="float (meters)"
              x_offset="float (meters)"
              y_offset="float (meters)"
              z_offset="float (meters)"
              h_offset="float (degrees)"
              p_offset="float (degrees)"
              r_offset="float (degrees)"
   />
   <zcylinder radius  ="float (meters)"
              length  ="float (meters)"
              x_offset="float (meters)"
              y_offset="float (meters)"
              z_offset="float (meters)"
              h_offset="float (degrees)"
              p_offset="float (degrees)"
              r_offset="float (degrees)"
   />
   <sphere    radius  ="float (meters)"
              x_offset="float (meters)"
              y_offset="float (meters)"
              z_offset="float (meters)"
              h_offset="float (degrees)"
              p_offset="float (degrees)"
              r_offset="float (degrees)"
   />
 </shape>

Physics Vehicle

Vehicle models can have all of the properties, constraints and shape fields of the basic Physics Objects - but there are a few extra <properties> fields that are unique to wheeled vehicles - and a special set of inner structures relating to the vehicle's wheel models.

 <physicsvehicle name="Name">

   <wheels front_wheel_name="'model file name"
           rear_wheel_name ="'model file name" />

   <properties
     engine_max            ="float"
     engine_scale          ="float"
     steering_max          ="float"
     steering_scale        ="float"
     damping_0             ="float"
     damping_1             ="float"
     front_wheel_radius    ="float (meters)"
     front_wheel_width     ="float (meters)"
     front_axle_length     ="float (meters)"
     front_axle_offset     ="float (meters)"
     rear_axle_length      ="float (meters)"
     rear_axle_offset      ="float (meters)"
     rear_wheel_radius     ="float (meters)"
     rear_wheel_width      ="float (meters)"
     wheel_friction        ="float"
     roll_influence        ="float"
     suspension_stiffness  ="float"
     suspension_rest_length="float (meters)"
     suspension_damping    ="float"
     suspension_compression="float" />
 </physicsvehicle>

Wikiid Pages relating to gameTools ()

gameTools - Main page

gameTools - Support Tools : plb_to_ac3d, mklevel, mktile, mktree, tiled, autogen_java, mk3dgallery

gameTools - File Formats : title_screen.rgb, ultimate.xml, material.xml, decoration.xml, physics.xml tiled.xml, tiled_autotiles.xml, Level files, Tile naming scheme, PLB files

gameTools - Source Code : Game functions: gameCamera, gameClock, gameChecksum/gameHashTable, gameHTTP, gameIsect, gameJoystick, gameParticleManager, gameScreen/gameMouse, gameSky, gameStarter, gameStrokeFont, gameUtils Material database: MatList/MatEntry Tile map handling: TileObject/MapFlag/MapEntry/Map Java Interfacing: JavaLink Image file loading: liImage/liImageFactory 3D Model file loading: loadPLB, PLB exporter Physics: Sabot, Bullet, gameTools - Use with Blender, PLB exporter Object management: Object