Track file
Track files are binary files of extension '.trk' used by Stunts to contain individual tracks and their terrain. When produced by Stunts itself, they have a fixed length of 1802 bytes.
Overview
One of the most interesting features of Stunts is the possibility to create your own tracks, whatever the editor you choose to do so.
Each track is composed of 30x30 tiles, one byte for each tile. That is 900 bytes for track layout, with 1 additionnal byte for the horizon. Terrain information (grass, water and mountains) is recorded the same way, that is 900 bytes for terrain information too. There is an extra byte that's ignored by Stunts and is usually a zero. Therefore, any track file (extension .TRK) should be 1,802 bytes long. It is possible to store additional data overlaid past the default 1,802 bytes of a raw track file, though.
Track layout starts at offset 0000h. Horizon is at offset 0384h. Terrain information starts at offset 0385h and the extra byte is at offset 0709h. Information is recorded row by row: left to right, bottom to top for the track layout block, but left to right and top to bottom for the terrain block.
Terrain codification
Adapted from Jonas Baehr's page [2]
Key to the table columns:
- Element: Terrain element name.
- Orientation reference: for elements with multiple possible orientations, the feature of the element to which the orientation columns refer to.
- Orientation: Orientation of the reference feature. "Any" indicates there is just one orientation. The other columns refer to map sides as cardinal points (N, S, W, E = top, bottom, left, right). The ">" sign indicates direction, so S>N means vertical orientation, bottom to top. Compass points indicate the corners of a tile or element (NW, SW, SE, NE = top left, bottom left, bottom right, top right).
To find the hexadecimal value for a certain element, find its entry under the row of the element name and the column of the desired orientation.
| Element | Orientation reference |
Orientation | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Any | NW | SW | SE | NE | S>N | E>W | N>S | W>E | ||
| Flat ground | 00 | |||||||||
| Water | 01 | |||||||||
| Diagonal coast | Corner inside water | 05 | 02 | 03 | 04 | |||||
| Flat hill | 06 | |||||||||
| Hill slope (straight) | Uphill direction | 07 | 08 | 09 | 0A | |||||
| Angled slope (outer edge) | Heightened corner | 0B | 0C | 0D | 0E | |||||
| Angled slope (inner edge) | Lowered corner | 11 | 12 | 0F | 10 | |||||
Using any byte value higher than 12h in the terrain is almost guaranteed to cause Stunts to crash when loading the track file.
Track codification
Adapted from Jonas Baehr's page
Key to the table columns:
- Element: Terrain element name.
- Orientation reference: for elements with multiple possible orientations, the feature of the element to which the orientation columns refer to.
- Orientation: Orientation of the reference feature. "Any" indicates there is just one orientation. The other columns refer to map/tile sides as cardinal points (N, S, W, E = top, bottom, left, right). The ">" sign indicates direction, so S>N means vertical orientation, bottom to top. Compass points indicate the corners of a tile or element (NW, SW, SE, NE = top left, bottom left, bottom right, top right).
To find the hexadecimal value for a certain element, find its entry under the row of the element name and the column of the desired orientation. Since the description of the orientation of some track pieces can be quite complex, the codes are presented in multiple tables to facilitate comprehension. We suggest you to use the "Find" command of your browser for efficiently locating track elements.
Important observation: For multi-tile elements (loops, corks, large corners and splits), the value given in the tables should be used for the top, left or top left (N/W/NW) tile only. The remaining tile(s) must be the adequate filler element(s), as described in the corresponding section.
Linear elements
By "linear" it is meant that the orientation of the element can be described unambiguously with a straight arrow. That includes most types of straight roads and ramps, as well as most stunt elements.
| Element | Orientation reference |
Orientation | ||||
|---|---|---|---|---|---|---|
| Any | S>N | E>W | N>S | W>E | ||
| Blank | 00 | |||||
| Paved s/f line | Track direction | 01 | B5 | B3 | B4 | |
| Dirt s/f line | Track direction | 86 | 89 | 87 | 88 | |
| Icy s/f line | Track direction | 93 | 96 | 94 | 95 | |
| Paved road | Track direction | 04 | 05 | |||
| Dirt road | Track direction | 0E | 0F | |||
| Icy road | Track direction | 18 | 19 | |||
| Paved crossroad | 4A | |||||
| Dirt crossroad | 7D | |||||
| Icy crossroad | 8A | |||||
| Elevated road | Track direction | 22 | 23 | |||
| Solid elevated road | Track direction | 63 | 64 | |||
| El. span over road | Bridge direction | 65 | 66 | |||
| Elevated span | Track direction | 67 | 68 | |||
| Elevated ramp | Ascending direction | 26 | 25 | 27 | 24 | |
| Bridge ramp | Ascending direction | 3A | 39 | 3B | 38 | |
| Solid ramp | Ascending direction | 61 | 60 | 62 | 5F | |
| Left-handed cork u/d | Ascending direction | 75 | 76 | 77 | 78 | |
| Right-handed cork u/d | Ascending direction | 79 | 7A | 7B | 7C | |
| Loop | Track direction | 40 | 41 | |||
| Cork l/r | Track direction | 55 | 56 | |||
| Tunnel | Track direction | 42 | 43 | |||
| Slalom road | Track direction | 73 | 74 | |||
| Pipe | Track direction | 44 | 45 | |||
| Half pipe (obstacle) | Track direction | 53 | 54 | |||
| Pipe start/end | Entering pipe direction | 46 | 48 | 47 | 49 | |
| Highway | Track direction | 6D | 6E | |||
| Highway start/end | Entering highway direction | 6F | 72 | 71 | 70 | |
| Banked road | Ascending direction *of the banking* |
32 | 30 | 33 | 31 | |
In order to distinguish left-handed and right-handed corks u/d, picture a car moving along the corkscrew. Stick your right thumb along the vertical direction of the car (upwards or downwards) and rotate your other fingers around it. If your fingers' rotating movement matches that of the car, the cork is right-handed; otherwise, it is left-handed.
Corners and splits
| Element | Orientation reference |
Orientation | |||
|---|---|---|---|---|---|
| S-E | W-S | N-E | W-N | ||
| Paved sharp corner | Connected sides | 06 | 07 | 08 | 09 |
| Paved large corner | Connected sides | 0A | 0B | 0C | 0D |
| Dirt sharp corner | Connected sides | 10 | 11 | 12 | 13 |
| Dirt large corner | Connected sides | 14 | 15 | 16 | 17 |
| Icy sharp corner | Connected sides | 1A | 1B | 1C | 1D |
| Icy large corner | Connected sides | 1E | 1F | 20 | 21 |
| Banked corner | Connected sides | 34 | 35 | 36 | 37 |
| Elevated corner | Connected sides | 69 | 6A | 6B | 6C |
| Element | Orientation reference |
Orientation | ||||
|---|---|---|---|---|---|---|
| S-E | W-S | N-E | W-N | |||
| Paved sharp corner | North-south road | Corner orientation | 4F | 4B | 4D | 51 |
| East-west road | Corner orientation | 4C | 52 | 50 | 4E | |
| Paved large corner | North-south road | Corner orientation | 5B | 57 | 59 | 5D |
| East-west road | Corner orientation | 58 | 5E | 5C | 5A | |
| Dirt sharp corner | North-south road | Corner orientation | 82 | 7E | 80 | 84 |
| East-west road | Corner orientation | 7F | 85 | 83 | 81 | |
| Icy sharp corner | North-south road | Corner orientation | 8F | 8B | 8D | 91 |
| East-west road | Corner orientation | 8C | 92 | 90 | 8E | |
Miscellaneous track elements
Special cases in which the orientation cannot be described through the simpler conventions used elsewhere.
| Element | Orientation reference |
Orientation | ||
|---|---|---|---|---|
| SW-NE | SE-NW | |||
| Chicane | North-south road | Connected tiles | 3C | 3E |
| East-west road | Connected tiles | 3D | 3F | |
| Element | Orientation reference |
Orientation | ||||
|---|---|---|---|---|---|---|
| NW | SW | SE | NE | |||
| Banked road start/end | North-south road | Highest point of the banking | 28 | 2E | 2A | 2C |
| East-west road | Highest point of the banking | 2F | 2B | 2D | 29 | |
Scenery
| Element | Orientation reference |
Orientation | ||||
|---|---|---|---|---|---|---|
| Any | S | N | E | W | ||
| Ghost car (player) | 02 | |||||
| Ghost car (opponent) | 03 | |||||
| Palm tree | 97 | |||||
| Cactus | 98 | |||||
| Pine tree | 99 | |||||
| Tennis court | 9A | |||||
| Gas station | Building front | 9B | 9C | 9D | 9E | |
| Barn | Building front | 9F | A0 | A1 | A2 | |
| Office building | Building front | A3 | A4 | A5 | A6 | |
| Windmill | Building front | A7 | A8 | A9 | AA | |
| Ship | Ship bow | AD | AE | AC | AB | |
| Joe's Dinner | Building front | AF | B0 | B1 | B2 | |
The ghost cars were not intended to be actual scenery elements and thus are not available form the in-game editor. Track Blaster is able to insert the player ghost car as a regular track piece.
Fillers
| Element | Orientation reference |
Orientation | |||
|---|---|---|---|---|---|
| NW | SW | SE | NE | ||
| Filler | Tile position | ** | FE | FD | FF |
Filler tiles are necessary for multi-part track elements to be built correctly. The proper positioning of such tiles will be described using a 2x2 grid of tiles in which the NW tile contains the value of the actual track element. For 2x1 elements (loops and corks l/r), the track element tile is either the top or the left one (depending on orientation), and so the correct fillers are either SW or NE respectively. For 2x2 elements (corks u/d, chicanes and large corners) all three fillers should be used.
Editing track files with external tools such as Track Blaster gives the user liberty to omit filler tiles, either leaving the other tiles blank or filling them with other elements. That is the main trick deployed to build illusion tracks, as the space where the fillers would be will appear to contain the full NW tile track element except at very short viewing distances and yet the physical behaviour will be set by whatever element the designer put in its place.
Horizon codification
- 00 Desert
- 01 Tropical
- 02 Alpine
- 03 City
- 04 Country
- 05 Chaotic scenery (can make the game react weird sometimes)
Extra byte
Probably thought of as a reserved byte or just a padding byte to make the file length even at the time of its inception, the last byte of a raw track file (at zero-based location 0709 hexadecimal) is unused by Stunts. When a track is created with the internal editor, it is generated as a 1,802-byte file with this last byte being null. When Stunts or the internal editor read a track file, this byte is loaded into memory together with the rest of the file, but is at all times ignored by the game. Later, modifying the track and saving it again will keep the value stored in this byte. Track Blaster behaves in the exact same manner with respect to the extra byte.
Bliss takes advantage of how this byte is handled by Stunts and uses it to try to recognise tracks that have been built with it. Tracks created with Bliss will store a 153 instead of a 0, but tracks edited with Bliss will preserve their current value. Values 2, 150, 151, 152 are also found sometimes, although they are no longer produced. This led to the Bliss format byte controversy. It is projected that future versions of the editor will cease to use this byte completely.
Metadata
Storing additional data for a track is possible in several ways, although all of them have their shortcomings. The most reliable is the extra byte, but it's only one byte. Another option is to use an external, parallel file, but it would tend to get lost and would have to be renamed whenever the track file is renamed, just like what happens with .HIG files. A very restrictive way of adding more information within the first 1802 bytes is to use some track element codes that are not normally used, but this is highly problematic. Finally, perhaps the most desirable option, albeit with a couple of limitations, is to add a binary overlay. Bliss allows for both the overlay and parallel file methods of storing metadata.
Bliss binary metadata format
Bliss stores its metadata right after the 1,802 bytes of the raw track file if in overlay or in a separate file with the same name as the track file and an extension '.smd'. The first four bytes contain the text "smdf", followed by four null bytes. After that, the metadata consists of chunks. For each chunk, there's an alphanumeric four-byte chunk ID and a word representing the length of the chunk. Finally, as many bytes as this length will contain the value for that chunk parameter. The following chunks IDs are recognised by Bliss:
- "Titl" - Track title
- "Autr" - Track author
- "Comm" - General comment
- "Chmp" - Tournament-related comment
- "Date" - Creation date of the track
- "Tool" - Editor or tool used to create the track
- "Etim" - Editing time in seconds
"Etim" is a dword. "Tool" is a UTF-8 string representing the name of the tool, except that the last four bytes are a dword containing the tool version in decimal xxyyzz for xx.yy.zz. "Date" is a word for the year, a byte for the month and another byte for the day. The rest are UTF-8 strings. Unknown chunks are skipped.
There was an argument in the past over whether the metadata format should be binary or text, with Cas being the promoter of binary and Dreadnaut defending text. Ultimately, binary was chosen for both split and overlay, but Cas is considering switching to text for split.
Overlaying
When using an overlay, the maximum track file length is 13,802 bytes, that is, 12,000 bytes more than the size of a raw track file. The reason for this is that Stunts will attempt to load the whole file in memory and the bytes following the track in Stunts' memory are those of the current replay being recorded, which can have a maximum of 12,000 tics, equallying 10 minutes at 20 tics per second. Because this memory region is not in use while a track is being loaded, nothing happens, but if the size exceeds this amount, Stunts will overwrite another region and may crash.
Even though Stunts will load the overlay to memory, it will NOT write it back down to the file if it is edited with the internal editor. Instead, it will truncate the file to the first 1,802 bytes. Other tools, such as Track Blaster will just refuse to open a track file with any length other than 1,802 bytes.
Stunts is also able to load track files shorter than 1,802 bytes. The procedure is always the same when loading: take as many bytes as the file contains and copy them to memory starting at the first byte of the memory region dedicated for the current track. This means that it is possible to create a track file without a terrain and Stunts will just load it on top of the current terrain.
