Table of Contents

Scripting in TR4 and TR5

In this chapter we will describe full gameflow script specification for TR4/TR5 script file (usually called SCRIPT.DAT) and language file, which contains all the strings used in game for specific language (e.g., ENGLISH.DAT, FRENCH.DAT, and so on).

The Script File

The script is divided into several blocks (or headers), some of them are global (applicable to whole game instance), and some are per-level only.

Global Header

This header contains general information not specific to particular level.

InputTimeout: in early TR4 demos (for example, version dated September 15, 1999) this parameter specified time interval, after which game will engage pre-recorded rolling demo, in case there was no user input. This feature became useless in final version.

SecurityTag parameter meant to be a special “key” value used to encrypt script data. Encryption is done with simple XOR operation against the data. However, this value was never used, and instead, hardcoded one was specified. This matter will be discussed later.

Level Header

This section defines platform-specific information, such as file extensions used in PC an PlayStation versions of the game. All the mentioned strings are null-terminated.

Level Listing Block

Note that the offsets in the offset table themselves are not relative to the file address 0. The level-path offsets are relative to the first path string’s starting byte address (56 + NumTotalLevels * 2), while the level-data offsets are relative to the first level data’s starting byte address (56 +
NumTotalLevels * 2 + LevelpathStringLen + NumTotalLevels * 2).

It is also worth noting that the level-path strings in SCRIPT.DAT are ordered the same way they were ordered in corresponding [Level] blocks in uncompiled SCRIPT.TXT. For example, if the first [Level] in SCRIPT.TXT defines Level=DATA\TEST1,101 and the second Level=DATA\TEST2,101 — then there will be 2 level-paths in SCRIPT.DAT, in the order such as this: DATA\\TEST1.DATA\\TEST2; where . is the null-terminator (0x00) byte.

To get to a certain level’s path within SCRIPT.DAT knowing only its number, just look-up at OffsetsToLevelpathString[LevelNum] and go to that offset (remember, it is not relative to file address 0!).

Level Block

Inside the level block, each level stores its own data describing certain parameters, such as level name, puzzle item names, load camera position, default background ambience soundtrack, and so on (the title level is no exception!).

While in SCRIPT.TXT each parameter was given its own line and position within the file itself, in SCRIPT.DAT this is not the case. Rather, bitfields are used for bool options (enabled/disabled; such as Lightning option) and the rest of the usually multi-byte data uses an opcode data structure.

That is, preceding a certain type of data you usually find a byte. That is the opcode byte — depending on its value, it can be determined what kind and how many arguments follow that need parsing. For example, chunk 0x81 indicates the level description opcode; with that info, the parser knows that 4 arguments follows: the string index, etc. This structure is somewhat akin to the AnimCommands structure of level files (see description above). The chunk order does matter; the original tomb4.exe binary seems to crash if something is not ordered the way it should be.

The title screen is special in that it uses the 0x82 opcode the indicate the level-name and audio track information and it, naturally, lacks the string index integer as the title level has no name associated with it.

struct tr4_script_leveldata
{uint8_t LevelData [LevelDataLen];}

LevelData is all of the level’s data continuously stored in memory. Number of level data sections is equal to overall amount of levels in game, and overall size of all level data sections comprise Level Block.

To get to a certain level’s data section, follow that particular level’s offset from inside the offset table you loaded (described above). The data sections themselves are ordered the very same way levels were ordered in SCRIPT.TXT. For more info on the types of all available TR4 chunks and how to parse them, see the Script Opcodes section.

Language File Listing Block

After the level block follows a simple array of ASCII strings which define all the language files the game can choose from. There are, however, no offset tables for this one, so one must simply read until a null-byte is reached, and then take that as the string and repeat onwards until EOF. Therefore, the last byte of SCRIPT.DAT must always be the null-terminator (0x00).

This setup is valid only for standard TR4 scripts generated by original TRLE script utility. TRNG scripts have their own special footer and data block appended to the bottom of the file, which contain all the extra information it needs.

Script Opcodes

Here is a list of all available TR4 opcodes, their meaning and their corresponding arguments (order of arguments matters!):

It is important to note that the LoadCamera opcode has been removed in TR5, which means that all the other opcodes (>= 0x92) are shifted by 1).

The uint16_t values levelOptions and titleOptions are actually bit fields containing several boolean options, and are laid out as follows (per-bit description):

Bit 0 (0x0001) — YoungLara

Bit 1 (0x0002) — Weather

Bit 2 (0x0004) — Horizon

Bit 3 (0x0008) — Layer1 used

Bit 4 (0x0010) — Layer2 used

Bit 5 (0x0020) — Starfield

Bit 6 (0x0040) — Lightning

Bit 7 (0x0080) — Train

Bit 8 (0x0100) — Pulse

Bit 9 (0x0200) — ColAddHorizon

Bit 10 (0x0400) — ResetHUB used

Bit 11 (0x0800) — LensFlare used

Bit 12 (0x1000) — Timer

Bit 13 (0x2000) — Mirror used

Bit 14 (0x4000) — Remove Horus amulet from inventory

Bit 15 (0x8000) — NoLevel

The Language File

In contrary to TR2 and TR3, TR4 uses a more sophisticated language-handling scheme. Instead of storing the strings in SCRIPT.DAT for every different language, TR4 splits the string definition ({LANGUAGE}.DAT) and script definition (SCRIPT.DAT) data into the two mentioned files. This allows for smaller files, finer grain of selectivity and easy localization.

This means that, within SCRIPT.DAT, strings are always given as string indices, i.e. numbers that correspond to the array positions of the corresponding strings within {LANGUAGE}.DAT, where {LANGUAGE} can be any supported language filename.

From these files, the game will choose the first one that is available and use that as the string resource. See below for details on string selection.

Language File Priority

The number of supported language files depends on what was defined in SCRIPT.TXT, in the [Language] section. Also, the priority of loading is specified there (the first number before the comma). For example, if we have defined:

…that would mean that the game will first look for ENGLISH.DAT for loading. If that’s not present, it will look for FRENCH.DAT. If not, it’ll look for GERMAN.DAT, and so on. If none of the files are present, the game will crash. In SCRIPT.DAT, these numbers reflect on the order of file name strings: in the above situation, the language file listing block at the end of SCRIPT.DAT would look like this (highest→lowest priority):

StringOffsetTable is a table holding offsets which point to corresponding strings. Therefore, its size is NumGenericStrings + NumPSXStrings + NumPCStrings.

Offsets in the offset table themselves are not relative to the file address 0! They are actually relative to the first string’s starting byte address!

In order to get an absolute offset of a string whose relative offset you retrieved from the offset table, do the following:

absoluteOffset = relativeOffset + sizeof(tr4_lang_header)

sizeof(tr4_lang_header) depends, of course, on the number of strings in each group. Therefore, the header size is sizeof(uint16_t) * 6 + sizeof(OffsetTable).

String Data

In the usual TR4 situation, there are typically 359 strings (that is, usually NumTotalStrings = NumGenericStrings + NumPSXStrings + NumPCStrings = 359) defined. This, however, is not a limit nor rule of any kind.

All the strings defined within {LANGUAGE}.DAT files are ASCII null-terminated strings. Every character (byte) contained in such a string is XOR-ed with byte 0xA5 (as mentioned above, it is done regardless of what byte was specified in SCRIPT.TXT under the Security option).

The null-termination byte is not being XOR-ed!

After the above defined header section goes an array of strings, in a predefined order: Generic → PSX → PC.

The length of this array of total (NumTotalStrings) strings is therefore TotalStringsLen = GenericStringsLen + PSXStringsLen + PCStringsLen.

Hence the string array has the following format:

struct tr4_lang_stringdata
{
string_entry Strings[NumTotalStrings];}

where string_entry is simply a char array, whose length depends on the corresponding string’s length. That can be calculated by subtracting the next string’s by the current string’s offset.