This page covers the new driveline format introduced along SuperTuxKart 0.7
(See the Theorical Driveline Model in this separate article if you feel so inclined but you probably don't need it)
How to create drivelines with the track exporter
The track exporter is able to create quad and graph data structures from specific meshes in the track. While it can't handle all theoretical cases (e.g. a looped track as the last example above is not possible, to do this you have to manually edit the graph file), it can handle all kinds of shortcuts and alternative ways.
Creating the Main Driveline
First of all you need one mesh to be the main driveline. This is the main way the AI should be driving. The mesh can be created either by manually extruding ..., or by using curves (as described in the track making tutorial). Add a game logic property called 'type' and give it the value 'main-driveline'.
This mesh must not be closed (see picture). To indicate the start point and therefore the direction in which the karts should be driving, add a single vertex with an edge to each of the two start points - see picture. The track exporter will export all the quads in this mesh including the implicit quad that connects the end to the beginning. Then it will add a graph describing this loop. Each track must have exactly one main driveline.
Note that the additional two vertices are completely ignored, they are only used to indicate where to start.
For proper lap counting you also have to define an 'activate' property which specifies which check line to activate (see checklines below)
Creating a Shortcut or Alternative Way
If you want to add a shortcut (or alternative way), use a similar structure as for the main driveline, but give the game logic property 'type' the value 'driveline' (as opposed to main-driveline)
The shortcut is added in the picture using again two vertices to indicate where the start point is. The export script will then automatically export the additional quads, and create the graph from the closest quad of the main driveline to the beginning of the shortcut, and from the end of the shortcut to the closest quad.
Checks and Lap Counting
SuperTuxkart is using 'check lines' for triggering events and counting laps. In Blender they are represented by a line segment (i.e. with a definite beginning and end, not an infinite line) that is triggered when a kart crosses it.
Checklines are generally added near the middle of the track; they should be in a place where they cannot be missed unless by cheating.
A checkline called lap is implicitly created at the start of the driveline (no need to create this line yourself, it will be created automatically for you when you export the track).
Check structures can be activated or deactivated (for each player). When an activated structure is triggered (crossed), the structure becomes deactivated (for the kart that just triggered it). As one effect of triggering, a check structure can activate other check structures.
For lap counting to work, you need at least one checkline (usually near the center of the track) that activates the lap line (as in the screenshot above), and you need to make the implicit lapline (the driveline) activate your checkline (as in the screenshot below). It is nonetheless recommended to use more than one checkline, read below for more information.
Placing at least one checkline prevents the player from cheating by triggering a new lap detection by driving in circles around the start line. Using the checkline technique, the lap won't be counted unless the lapline was first activated by crossing the middle-of-track checkline.
You can also define a chain of check lines: check line 1 activates check line 2, which activates check line 3, which activates the new lap line (which re-activates the first check line). So karts have to cross the check lines in the right order in order to get a lap counted. Note that this system is meant to prevent cheating, i.e. bypassing a significant amount of the track, not to prevent shortcuts. If you want to prevent shortcuts, you either have to model the track appropriately (by putting objects, water, bananas, ...to prevent a kart from using the shortcut), or setting the physics parameters (i.e. making the terrain to cause a slow down of the kart so that it's not worth using this shortcut).
The check structures can be grouped: all check structures of type 'lap' belong to a group 'lap', and all check structures with the same 'name' property will be grouped together, too. This means that e.g. you activate (say) 'lap', all lap counting lines will be activated; and if you cross a lap counting line, all check structures with the group 'lap' will be deactivated etc. One reason why you want to have more than one lap line is if a kart might cross the start line a little bit to the left or right of the actual start line (and you don't want to widen the quads to accommodate this since the quads might be too wide and look odd in the minimap). Preferred solution is to model the track so that it is obvious where a kart is supposed to cross the line, e.g. having some kind of 'gate' or so. But if this is inconvenient just add more lap counting lines to the left and/or right of the first quad line, and stk will take this into account.
STK supports a command line parameter --check-debug, which will cause STK to print a message to the terminal when a check structure is triggered etc. This can be useful in solving problems when laps are not counted correctly.
If lap counting or checklines don't work as intended, see Artist_Debug_Mode#Debug_checklines
How to convert old drivelines to the new format
The old driveline format used two meshes - one for the left side, and one for the right side. To convert these to the new format:
Also see this video tutorial.
- For each of the two drivelines remove the edge that crosses the starting line. So instead of having a loop you have two lines, each line having a starting point and an ending point indicating the direction in which the karts are driving (see picture above).
- Combine the two meshes into a single mesh.
- Create a new edge connecting the two starting points.
- Create a new edge connecting the two ending points.
- Select the two starting vertices, extrude them (vertices only), to indicate where the first quad to drive on is.
- Add the game logic property 'type', and set it to 'main-driveline'
Now you should be ready to export the track.
The file format
While it is not at all necessary to know or understand the file format used, here a short description which should help in debugging any problems, or modeling more complex graphs than the default one created by the exporter script.
The created .quad file is plain ASCII, e.g.:
<?xml version="1.0"?> <quads> <quad p0="15.575774,33.574879,0.000000" p1="-20.480236,11.145029,-0.000000" p2="-36.736404,14.047918,-0.000000" p3="-36.095619,34.736038,-0.000000"/> <quad p0="0:3" p1="0:2" p2="-89.494789,13.467787,-0.000000" p3="-90.163483,34.155022,-0.000000"/> <quad p0="1:3" p1="1:2" p2="-108.047676,9.295321,-0.000000" p3="-129.087753,34.263454,-0.000001"/> ...
A quad is defined by specifying four coordinates. This can be done either by using four 3d coordinates (as in the first quad line), or by referring to a point of an already defined quad: the latter case uses p0="Q:P" which means: use point P of quad Q as point 0 of the current quad.
Similarly the graph files are plain ASCII, too:
<?xml version="1.0"?> <graph> <node-list from-quad="0" to-quad="54"/> <edge-loop from="0" to="54"/> </graph>
The first section described the mapping of quads to graph nodes - it will always be a 1:1 mapping, i.e. each quad will be used in exactly one graph node. Then the connection of the graph nodes are described. Besides defining a loop, a single edge can be defined as well: <edge from="15" to="23"/>