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

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. Bliss track editor can produce both the player's and the opponent's ghost cars.

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 or Bliss 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.

Other track element codes

While codes B6h through FCh are not used by the editors, they do have some strange effects on Stunts, but there doesn't seem to be a good way of taking advantage of them. Most of these codes appear like a variety of track element combinations with terrain when looking at the perspective display of the track at the menu before entering the internal editor. Some appear as coloured dots and even a few cause a crash. But even if there is no crash, once the game starts or the internal editor is opened, all these turn to vertical paved roads, even the ones that appeared like plain grass.

This behaviour seems to suggest that these values are used internally by Stunts as it renders the track before one is allowed to play. Some track codes translate to different 3D objects depending on the terrain. For example, the straight paved road is very different when on a slope. So Stunts transforms editor codes to game codes to be able to render more quickly during the race.

Here is a list of the values and their effects:

• 00 -> B5 - Normal track elements
• B6 -> B9 - Paved slopes (up north, up west, up south, up east)
• BA -> BD - Dirt slopes
• BE -> C1 - Ice slopes
• C2 -> C5 - Strange slopes (grey/green)
• C6 -> D3 - Grass
• D4 -> D5 - Dot (sign?)
• D6 -> D7 - Grey line at north wall (fence?)
• D8 - Water square
• D9 - Water North-East
• DA - Water North-West
• DB - Water South-West
• DC - Water South-East
• DD - Empty slope (west?)
• DE -> DF - Hill top or maybe east slope
• E0 -> E9 - Hill sides and corners
• EA -> ED - Coloured dots (pink, dark pink, whitish, black)
• EE -> F5 - Grass
• F6 - Strange small object
• F7 -> FA - Stunts crashes!
• FB - Another strange small object
• FC - Corner slope
• FD -> FF - Fillers

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.

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 little-endian 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
• "Colr" - Colouring information

"Etim" is a little-endian 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. "Colr" is a RLE compressed string containing the colouring information on the grid if any. 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 at that time. For version 2.5.5, a text-based split file format was introduced as an alternative. Binary split was preserved and Bliss still defaults to one-file binary format. Text format is only available as split.

Colouring information, when included, is to be read as follows: read one byte, which is the count, then two words, which correspond to the border and background colours respectively in 16bit colour (RRRRRGGGGGGBBBBB). Then assign as these two colours to as many tiles as the count going from left to right, then from top to bottom. Repeat until the whole grid has been covered. The transparent colour is represented with 1111100000011111b. When the border or background colour is set to this value, it means it is not present for that tile.

Bliss text-based split metadata format

When this format is selected, Bliss will store the data in a separate file with extension ".smd". From the perspective of Bliss, this is still a binary file, as the structure completely disregards the operating system.

The file must start with the text "[smdf]" plus a character 0Ah or "[smdf]" plus a character 0Dh to be considered valid. This is equivalent to saying the first line must be "[smdf]" in ASCII or UTF-8, but other encodings may not work and a BOM at the beginning of the file would render it invalid. From that point onwards, all bytes 0ah and 0dh are stripped out of the stream, except that one or more of those characters will stop line formation. This means that any combination of whatever number of bytes 0ah and 0dh will be interpreted as an end of line. Therefore, Bliss sees no empty lines in these files. Lines that do not contain an equal sign will be ignored (comments). For lines that do contain an equal sign, everything to the left of the equal sign is the property name and everything to the right of it is the value. Spaces at the end of the property name or at the beginning of the value are removed and the property name is case-insensitive within the ASCII threshold. When producing one of these files, Bliss will use 0d0ah as separators, as is common in DOS and supported by most OSs.

Following are the recognised property names:

• "title" or "titl" - Track title
• "author" or "autr" - Track author's name
• "comment" or "comm" - General comment
• "tour_info" or "chmp" - Tournament information
• "creation_date" or "date" - Date of creation of the track in YYYY-MM-DD format
• "tool" - Name of the tool used to create the track (without the version number)
• "tool_version" - Version number in the form v.s.d or v.ss.dd
• "editing_time" or "etim" - Number of seconds used to edit the track

The text format does not support colouring information.

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

• 1. ^back Online track viewer (inactive) (by Jonas Baehr)
• 2. ^back Hex codes for terrain and track elements (by Jonas Baehr)
• Online track viewer at Southern Cross