XML Ground Meshes

The PathEngine mesh format supports the representation of a base 3d ground mesh together with additional related information such as a set of named positions and obstacles on that mesh and a 'mapping to 2D'.

The format is defined using a subset of XML.
For information about XML see The XML FAQ.
To reduce file size and time spent processing files at run-time, a 'tokenised XML' format is also supported.
For information about the tokenised XML format used by PathEngine refer to Tokenised XML.

Content processing functionality

In order to take advantage of features such as automatic connection between mesh parts, developers are recommended not to use this mesh format directly, but to instead use the exporter, or PathEngine's 2D content processing functionality as provided through the API with iPathEngine::buildMeshFromContent() .

Scope of this document

When building meshes, developers only need to generate the base 3D mesh.
This can then be loaded into PathEngine and additional information such as content positions added through the API.
Saving the mesh (with iMesh::saveGroundEx()) will then save this additional information out with the mesh in the required format.

The scope of this document is limited, then, to a description of the 3d mesh part of the format.

Structure

The file contains a single mesh element at the toplevel.
This encloses a mesh3D element, which in turn encloses verts and tris element (in that order) specifying the actual mesh geometry.

The verts elements contains an ordered sequence of vertices, with attributes to specify the coordinates of each vertex.
Each vertex is represented by a vert element with x, y attributes and an optional z attribute.
X and Y coordinates must be integers. The Z coordinate may be a floating point, and if this is not present vertex Z will default to 0.

The tris element contains an ordered sequence of faces.
Each face has three edges, with attributes providing information about vertices and connections for each edge.

edge0StartVert, edge1StartVert, and edge2StartVert attributes are indices into the list of vertices already described.

The format supports a Z coordinate specified independantly per edge (to support ground features such as Steps and Staircases).
edge0StartZ, edge1StartZ, edge1StartZ optionally specify this Z coordinate as a float.
If a Z attribute is not specified then the edge start Z is taken from the start vertex.

edge0Connection, edge1Connection, and edge2Connection attributes are indices into the list of tris.
These connection attributes control the possibility for movement between faces in the ground surface.
In order for two edges to connect, the two edges must reference the same two vertices, but in reverse order.
Each connection must be specified only once, from the face with higher index to the face with lower index.
Each connection is specified in terms of the face index for the target edge.

A simple but complete example mesh.

The following example shows what a 200 by 200 square mesh centred on the origin and at height 0 would look like in XML.

<mesh>
 <mesh3D>
  <verts>
   <vert x="-100" y="100"/>
   <vert x="100" y="100"/>
   <vert x="-100" y="-100"/>
   <vert x="100" y="-100"/>
  </verts>
  <tris>
   <tri edge0StartVert="0" edge1StartVert="1" edge2StartVert="2"/>
   <tri edge0StartVert="1" edge1StartVert="3" edge2StartVert="2" edge2Connection="0"/>
  </tris>
 </mesh3D>
</mesh>

Face attributes

The following attributes may be specified per tri: 'surfaceType' and 'sectionID'.
These correspond to the PE_FaceAttribute_SurfaceType and PE_FaceAttribute_SectionID faces attributes described in Face Attributes.