A track specification is a directory containing the various assets that define a particular course. One of the files in this directory is the track file, which is an ASCII file that specifies the geometry and AI meta-data for a particular track using the the JSON syntax extended with C-style comments (most JSON parsers accept such comments).
This specification is meant to be a baseline specification that you can extend with information that is specific to your game. For example, you might add acceleration/breaking hints to sectors.
A track file consists of a JSON object with the following fields:
A track is a JSON object that describes the geometry of the track. The track is represented as a list of polygonal sectors. Note that while the track geometry can be used for simple rendering, it is not meant to be a substitute for the actual 3D mesh representation of the world.
A vertex is a location in 3D space. Each track description has an array of vertices, which are then referenced by index (zero-based). The representation of a vertex is an array of three numbers representing the X, Y, and Z coordinates of the vertex. The Y coordinate is used to represent the altitude of the vertex.
A sector is a convex polygon that defines a region of the track. Its edges are classified into walls, entry edges, and exit edges. The entry/exit distinction defines the direction that vehicles are expected to travel. A sector has the following fields:
Edges have the following common fields:
A wall edge represents the boundary of the track and has no additional fields.
Entry and exit edges connect sectors connect two sectors, with the exit edge in one sector having a corresponding entry edge in the neighbor sector. These edges have the following additional fields:
A 2D vertex is a location on the XZ plane (recall that the Y-axis is elevation). Each racing line description has an array of vertices, which are then referenced by index (zero-based). The representation of a 2D vertex is an array of three numbers representing the X and Z coordinates of the vertex.
A racing line specifies a path around the track that the AI can follow. Currently lines are expected to define a loop. It has the following fields:
A segment is a piece of a line. There are two kinds of segments: lines and arcs. They share the following common fields:
Line segments do not have any additional fields.
Arc segments have the following additional fields:
Here is an example of a minimal track with a single racing line. The track geometry is in blue and the racing lines are in caynne.
This file format can be extended by adding additional fields to the various objects. To improve interoperability between groups, we adopt the following convention for extensions. Suppose that group gpr-123 wants to add two fields (bar and baz) to an object. It does so by adding a object-valued field "gpr-123" to the object; this object contains the bar and baz fields.
We could extend the racing line specifications to use Catmull-Rom splines.
Currently racing lines form closed loops; we could introduce split and join points to generalize lines to multiple circular paths.