Track file

From Stunts Wiki

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

Simple corners
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
Split corners
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.

Chicanes
Element Orientation
reference
Orientation
SW-NE SE-NW
Chicane North-south road Connected tiles 3C 3E
East-west road Connected tiles 3D 3F
Banked road entrances
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.

External links