scripting_tr2_tr3.asc

Scripting in TR2/TR3 for PC/PSX

Overview

The internal gameflow, which levels come in what order, what item(s) Lara has at the beginning of each level, the filenames of the level and cut-scene files, all the visible text (e.g. Save Game,'' Rusty Key,'' etc.), and various other options are controlled by a script file called TOMBPC.DAT/TOMBPSX.DAT. The scripts were compiled using a utility known as GAMEFLOW.EXE which was distributed by Eidos in the German release of Tomb Raider II Gold. Both TR2 and TR3 use these script files. From both games the format remained unchanged. TR1’s gameflow is hardcoded thus there is no external file controlling this resulting in loss of flexibility.

uint32_t Version;             // The Script Version (Always 3 for TR2/3)
uint8_t Description[256];     // Null-terminated string describing the script copyright info etc. Not encrypted.
uint16_t GameflowSize;        // Size in bytes of the game flow data, always 128 bytes
int32_t FirstOption;          // What to do when the game starts
int32_t TitleReplace;         // What to do when EXIT_TO_TITLE is requested
int32_t OnDeathDemoMode;      // What to do when Lara dies during the demo mode
int32_t OnDeathInGame;        // What to do when Lara dies during the game
uint32_t DemoTime;            // Time in game ticks (1/30th of a second) to wait before starting a demo
int32_t OnDemoInterrupt;      // What to do when the demo mode is interrupted
int32_t OnDemoEnd;            // What to do when the demo mode ends
uint8_t Unknown1[36];         // Filler
uint16_t NumLevels;           // Number of levels in the game, including the training level, not including the title level.
uint16_t NumChapterScreens;   // Chapter screens (Present in TR2, first used in TR3)
uint16_t NumTitles;           // Number of title elements (TITLE.TR2 level + the legal/title pictures in *.PCX format)
uint16_t NumFMVs;             // Number of FMV cutscenes PC - (*.RPL), PSX - (*STR)
uint16_t NumCutscenes;        // Number of in-game (engine-rendered) cutscenes (CUT*.TR2)
uint16_t NumDemoLevels;       // Number of demo levels
uint16_t TitleSoundID;        // ID of title soundtrack
uint16_t SingleLevel;         // If doing only a single level, the level ID (starting at 1). -1 means disabled.
uint8_t Unknown2[32];         // Filler
uint16_t Flags;               // Various flags, see below
uint8_t Unknown3[6];          // Filler
uint8_t XORKey;               // Key used to encrypt/decrypt strings
uint8_t LanguageID;           // Script Language ID, see below
uint16_t SecretSoundID;       // ID of soundtrack to play when a secret is found
uint8_t Unknown4[4];          // Filler

// If Flags & UseXor true each character (except null-terminator) must be ^ XorKey to decrypt the string.

TPCStringArray[NumLevels] LevelStrings;                  // level name strings
TPCStringArray[NumChapterScreens] ChapterScreenStrings;  // chapter screen strings
TPCStringArray[NumTitles] TitleStrings;                  // title strings
TPCStringArray[NumFMVs] FMVStrings;                      // FMV path strings
TPCStringArray[NumLevels] LevelPathStrings;              // level path strings
TPCStringArray[NumCutscenes] CutscenePathStrings;        // cutscene path strings

uint16_t SequenceOffsets[NumLevels + 1];                 // Relative offset to sequence info (the +1 is because the first one is the FrontEnd sequence, for when the game starts)
uint16_t SequenceNumBytes;                               // Size of SequenceOffsets in bytes
uint16_t[] Sequences[NumLevels + 1];                     // Sequence info see explanation below (SIZE is dependant on first opcode)

uint16_t DemoLevelIDs[NumDemoLevels];

#if PSX
    PSXFMVInfo[NumFMVs];
#endif

uint16_t NumGameStrings;
TPCStringArray[NumGameStrings] GameStrings;

#if PSX
    TPCStringArray[size] PSXStrings; // size is 79 for the TR2 beta, 80 for all other versions
#else
    TPCStringArray[41] PCStrings;
#endif

TPCStringArray[NumLevels] PuzzleStrings[4];
#if PSX && TR2_BETA
    TPCStringArray[NumLevels] SecretsStrings[4];
    TPCStringArray[NumLevels] SpecialStrings[2];
#endif
TPCStringArray[NumLevels] PickupStrings[2];
TPCStringArray[NumLevels] KeyStrings[4];

String arrays

struct TPCStringArray // (variable length)
{
    uint16_t Offsets[Count]; // List containing for each string an offset in the Data block (Count * 2 bytes)
    uint16_t TotalSize; // Total size, in bytes (2 bytes)
    uint8_t Data[TotalSize]; // Strings block, usually encrypted (XOR-ed with XORKey, see above)
}

PSX FMV Info

struct PSXFMVInfo // 8 bytes
{
    uint32_t Start;     // Start frame
    uint32_t End;       // End frame
};

This specific info is exclusive to TOMBPSX.DAT.

Script Flags

• Bit 0 (0x01) — DemoVersion. If set, it indicates that the game is a demo distribution.

• Bit 1 (0x02) — TitleDisabled. If set, it indicates that the game has no Title Screen.

• Bit 2 (0x04) — CheatModeCheckDisabled. If set, it indicates that the game does not look for the cheat sequence keystrokes and events.

• Bit 3 (0x08) — NoInputTimeout. If set, it indicates that the game waits forever if there is no input (won’t enter demo mode).

• Bit 4 (0x10) — LoadSaveDisabled. If set, it indicates that the game does not allow save games.

• Bit 5 (0x20) — ScreenSizingDisabled. If set, it indicates that the game does not allow screen resizing (with the function keys).

• Bit 6 (0x40) — LockoutOptionRing. If set, it indicates that the user has no access to the Option Ring while playing the game.

• Bit 7 (0x80) — DozyCheatEnabled. If set, it indicates that the game has the DOZY cheat enabled (only present in the final build of TR2 on PSX).

• Bit 8 (0x100) — UseXor. If set, it indicates that a cypher byte was used to encrypt the strings in the script file, and is stored in the XorKey field.

• Bit 9 (0x200) — GymEnabled. Is Gym available on title screen.

• Bit 10 (0x400) — SelectAnyLevel. If set, it enables level select when New Game is selected.

• Bit 11 (0x800) — EnableCheatCode. It apparently has no effect on the PC game.

Script Language

• 0 — English

• 1 — French

• 2 — German

• 3 — American

• 4 — Japanese

Script Sequencing & Opcodes/Operands

Each script has `sequence information'', Opcodes and Operands are all stored as `uint16_t. Sequences contain a set of commands to execute where an additional value (operand) is usually passed as a parameter to the function the command needs to call. Note: that if a level is a demo level, its level ID will be 1024 higher than a normal level ID.

Script Opcodes

• 0 — Picture — Unused. Compiles but does not show in-game. Maybe PSX. Operand is picture ID.

• 1 — ListStart — Unused. Maybe PSX.

• 2 — ListEnd — Unused. Maybe PSX.

• 3 — FMV — Display Full Motion Video. Operand is FMV ID.

• 4 — Level — Start a playable level. Operand is level ID.

• 5 — Cine — Display cut scene sequence. Operand is cutscene ID.

• 6 — Complete — Display level-completion statistics panel.

• 7 — Demo — Display demo sequence. Operand is demo level ID.

• 8 — JumpToSequence — Jump to another sequence. Operand is sequence ID.

• 9 — End — Close script sequence.

• 10 — Track — Play Soundtrack (it precedes opcodes of associated levels). Operand is track ID.

• 11 — Sunset — Gradually dim all lights in rooms with LightMode set to sunset. Used in Bartoli’s Hideout.

• 12 — LoadPic — Show chapter screen (under TR3). Operand is picture ID.

• 13 — DeadlyWater — Unknown. Nothing changes in-game. Used in Temple of Xian. Maybe not-implemented ancestor of TR3 Death_by_Drowning?

• 14 — RemoveWeapons — Lara starts the level with no weapons.

• 15 — GameComplete — End of game, show the final statistics and start the credits sequence.

• 16 — CutAngle — Match the North-South orientation of the Room Editor and the North-South orientation of the 3D animated characters from a CAD application. Operand is horizontal rotation (angle in degrees * 65536 / 360)

• 17 — NoFloor — Lara dies when her feet reach the given depth. If falling, 4 to 5 extra blocks are added to Depth. Operand is depth (blocks * 1024), relative to where Lara starts the level.

• 18 — StartInv / Bonus — Give item to lara at level-start (StartInv) or at all-secrets-found (Bonus). Operand is item ID (see below).

• 19 — StartAnim — Lara starts the level with the given animation. Operand is animation ID.

• 20 — Secrets — If zero, the level does not account for secrets. Non-zero value means the level must be accounted for secrets.

• 21 — KillToComplete — Kill all enemies to finish the level.

• 22 — RemoveAmmo — Lara starts the level without ammunition or medi packs.

The correct way to parse a sequence is to first read a uint16_t opcode specifying what this command within the sequence does. In reference to the list above, certain commands MUST have an additional uint16_t read from the sequence data directly after the opcode that’s the pairing operand to this opcode. Not all opcodes have an operand so this must be done correctly. The original games execute each sequence command 1 by 1 until it reaches End (9), where it then runs the next sequence.

Opcode-18 StartInv and Bonus

(repeat means give another)

By default, the item is given at level start (StartInv). Adding 1000 to the item ID means it will be given when all secrets are found (Bonus).

Tomb Raider 2

• 0 — Pistols

• 1 — Shotgun

• 2 — Automatic pistols

• 3 — Uzis

• 4 — Harpoon gun

• 5 — M-16

• 6 — Grenade launcher

• 7 — Pistol clip (no effect, infinite by default)

• 8 — Shotgun-shell box (adds 2 shells)

• 9 — Automatic-pistol clip (adds 2 shells)

• 10 — Uzi clip (adds 2 shells)

• 11 — Harpoon bundle (adds 2 harpoons)

• 12 — M-16 clip (add 2 shells)

• 13 — Grenade pack (adds 1 grenade)

• 14 — Flare box (adds 1 flare)

• 15 — Small medipack (adds 1 pack)

• 16 — Big medipack (adds 1 pack)

• 17 — Pickup 1

• 18 — Pickup 2

• 19 — Puzzle 1

• 20 — Puzzle 2

• 21 — Puzzle 3

• 22 — Puzzle 4

• 23 — Key 1

• 24 — Key 2

• 25 — Key 3

• 26 — Key 4

Tomb Raider 3

• 0  — Pistols

• 1  — Shotgun

• 2  — Desert Eagle

• 3  — Uzis

• 4  — Harpoon gun

• 5  — MP5

• 6  — Rocket launcher

• 7  — Grenade launcher

• 8  — Pistol clip (no effect, infinite by default)

• 9  — Shotgun-shell box (adds 2 shells)

• 10 — Desert eagle clip (adds 5 shells)

• 11 — Uzi clip (adds 2 shells)

• 12 — Harpoon bundle (adds 2 harpoons)

• 13 — MP5 clip (add 2 shells)

• 14 — Rocket pack (adds 1 rocket)

• 15 — Grenade pack (adds 1 grenade)

• 16 — Flare box (adds 1 flare)

• 17 — Small medipack (adds 1 pack)

• 18 — Big medipack (adds 1 pack)

• 19 — Pickup 1

• 20 — Pickup 2

• 21 — Puzzle 1

• 22 — Puzzle 2

• 23 — Puzzle 3

• 24 — Puzzle 4

• 25 — Key 1

• 26 — Key 2

• 27 — Key 3

• 28 — Key 4

• 29 — Save crystal

Tomb Raider 2 Identifications

Note	TR2 only information here. These lists are virtually colored blue.

FMV IDs

• 0 — LOGO (everybody’s corporate logos)

• 1 — ANCIENT (monks vs. dragon)

• 2 — MODERN (Lara drops in from helicopter)

• 3 — LANDING (Seaplane lands at rig)

• 4 — MS (Lara hitchhikes on a minisub)

• 5 — CRASH (Lara goes to Tibet and has a rough landing there)

• 6 — JEEP (Lara steals it and outruns Bartoli’s goons)

• 7 — END (Lara escaping the collapsing lair)

Cutscene IDs

• 0 — CUT1 (At the end of the Great Wall)

• 1 — CUT2 (Lara the stowaway)

• 2 — CUT3 (Bartoli vs. goon)

• 3 — CUT4 (Bartoli stabs himself)

Soundtrack IDs

• 0 — BLANK (no sound)

• 3 — CUT1 (``at the fancy door'' soundtrack)

• 4 — CUT2 (``Lara the stowaway'' soundtrack)

• 5 — CUT3 (``Bartoli vs. goon'' soundtrack)

• 30 — CUT4 (``Bartoli stabs himself'' soundtrack)

• 31 — DERELICT (eerie choppy/echo-y synths)

• 32 — WATER (dripping/pouring water sounds)

• 33 — WIND (Blowing wind)

• 34 — HEARTBT (musical embellishment of one)

• 52 — SHOWER (that infamous shower scene)

• 58 — MACHINES (in the offshore rig)

• 59 — FLOATING (wispy synths)

Other Script Commands

FirstOption, TitleReplace, OnDeathDemoMode, OnDeathInGame, OnDemoInterrupt and OnDemoEnd can also be setup to perform specific actions. For example, OnDeathInGame will be set to "0x500" which loads the title screen when Lara dies in-game.

Commands

• Level / Sequence + operand — 0x000 — Load specified script sequence (0 means Frontend, 1 means Gym, 2 means first level)

• Demo + operand — 0x400 — Load specified demo level

• ExitToTitle — 0x500 — Exit to Title Screen

• ExitGame — 0x700 — Exit entire game?

• TitleDeselect — 0x900 — Unknown