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.

Consider using the content processing APIs!

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 or 3D content processing functionality to generate ground data.

Even if you need fairly direct control of the ground geometry, the best way to do this is still probably to generate the data in face vertex mesh format, with the 2D content processing functionality then used to generate an iMesh object (with iPathEngine::buildMeshFromContent()) and the iMesh save methods then used to generate actual ground mesh xml for saving to disk.

The content processing APIs are really now the 'standard' way to generate PathEngine ground meshes, but the versioning of the underlying ground mesh data is still very stable, and this page is then provided both as (partial) reference to the format of this ground mesh data, and in case situations arise where you really need to generate this data directly, for some reason.

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 independently 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', 'sectionID' and 'userData'.
These correspond to the PE_FaceAttribute_SurfaceType, PE_FaceAttribute_SectionID and PE_FaceAttribute_UserData faces attributes, described in Face Attributes.

Note that the xml snippet shown above does not include any versioning information and for historical reasons the surfaceType and userData attributes will then each default to 0 if they are not specified in the xml, whereas the sectionID attribute defaults to -1.