Skip to content

Gameflow script specification

ActiveMath edited this page Jul 15, 2015 · 8 revisions

Gameflow script specification

(usually SCRIPT.DAT)


Options Header


Bitfield8 options (per-bit option description) 1:FlyCheat; 2:LoadSave; 3:Title; 4:PlayAnyLevel; 8:DemoDisc
bit8	 Unused;
bit8	 Unused;
bit8 	 Unused;
bitu32   InputTimeout;
bitu8    Security;	//	this is completely useless

Extension & Level Header


All the mentioned strings are null-terminated.

bitu8    NumTotalLevels;	//	including the title level
bitu16   NumUniqueLevelPaths;	//
bitu16	 LevelpathStringLen;	//	sum of lengths of all level-path strings, including 0x00s
bitu16	 LevelBlockLen;		//	sum of lengths of each level-script data length
  
bitu8	 PSXLevelString [5];	//	typically ".PSX"
bitu8	 PSXFMVString   [5];	//	typically ".FMV"
bitu8	 PSXCutString	[5];	//	typically ".CUT"
bitu8	 Unused [5];		//	possibly for some additional extension type?
  
bitu8	 PCLevelString	[5];	//	typically ".TR4"
bitu8	 PCFMVString	[5];	//	typically ".BIK"
bitu8	 PCCutString	[5];	//	typically ".TR4"
bitu8	 Unused	[5];

Level Listing


bitu16	OffsetsToLevelpathString [NumTotalLevels];
bitu8	LevelpathStringBlock [LevelpathStringLen];
  
bitu16	OffsetsToLevelData [NumTotalLevels];

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 you ordered their corresponding [Level] blocks in 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, audio-loop etc. (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 classic Tomb Raider level files. The chunk order does matter; the original tomb4 binary seems to crash if something is not ordered the way it should be. For reference, look up Gameflow.cpp here. 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.

bitu8	LevelBlock [LevelBlockLen];	//  all of the level's data is continuously stored in memory here (total level num)

To get to a certain level's data block, follow that particular level's offset from inside the offset table you loaded (described above). The data blocks themselves are ordered the very same way you ordered your levels in script.txt. For more info on the types of all available TRLE chunks and how to parse them, see the OPCODES section.


Language File Definitions


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 simply read until you reach a null-byte 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).

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. 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 you defined:

File=	0,ENGLISH.TXT
File=	1,FRENCH.TXT
File=	2,GERMAN.TXT
File=	3,ITALIAN.TXT
File=	4,SPANISH.TXT
File=	5,US.TXT

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 etc. 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 string at the end of SCRIPT.DAT would look like this (highest->lowest priority):

ENGLISH.DAT.FRENCH.DAT.GERMAN.DAT.ITALIAN.DAT.SPANISH.DAT.US.DAT.

where the splitting '.' symbol specifies the null-terminator (0x00) byte.


Strings


In contrary to TR3/2, TRLE uses a more sophisticated language-handling scheme. Instead of storing the strings in script.dat for every different language, TRLE splits the string definition (lang.dat) and script definition (script.dat) data into the 2 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 lang.dat (where 'lang' can be any supported language). See the language script file specification for more information.


Opcodes


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

0x81  Level           bitu8 stringIndex, Bitfield16 levelOptions, bitu8 pathIndex, bitu8 audio
0x82  [Title] Level   bitu8 pathIndex, Bitfield16 titleOptions, bitu8 audio
0x8c  Legend          bitu8 stringIndex
0x91  LoadCamera      bit32 srcX, bit32 srcY, bit32 srcZ, bit32 targX, bit32 targY, bit32 targZ, bitu8 room
0x89  Layer1          bitu8 red, bitu8 green, bitu8 blue, bit8 speed
0x8a  Layer2          bitu8 red, bitu8 green, bitu8 blue, bit8 speed
0x8e  Mirror          bitu8 room, bit32 xAxis
0x8f  Fog             bitu8 red, bitu8 green, bitu8 blue
0x84  Cut             bitu8 cutIndex
0x8b  UVrotate        bit8 speed
0x85  ResidentCut1    bitu8 cutIndex
0x86  ResidentCut2    bitu8 cutIndex
0x87  ResidentCut3    bitu8 cutIndex
0x88  ResidentCut4    bitu8 cutIndex
0x80  FMV             bitu8: 4 least significant bits represent the FMV index; 4 most significant bits (y) represent the FMV trigger bitfield as in y=1<->bit 8 set
0x92  ResetHUB        bitu8 levelIndex
0x90  AnimatingMIP    bitu8: 4 least significant bits represent animatingObjectIndex - 1; 4 most significant bits represent the distance
0x8d  LensFlare       bitu16 yClicks, bit16 zClicks, bitu16 xClicks, bitu8 red, bitu8 green, bitu8 blue
0x93  KEY_ITEM1       bitu16 stringIndex, bitu16 height, bitu16 size, bitu16 yAngle, bitu16 zAngle, bitu16 xAngle, bitu16 unknown
0x94  KEY_ITEM2   -=-   
0x95	KEY_ITEM3   -=-   
0x96	KEY_ITEM4   -=-  
0x97	KEY_ITEM5   -=-   
0x98	KEY_ITEM6   -=-
0x99	KEY_ITEM7   -=-
0x9a	KEY_ITEM8   -=-
0x9b	KEY_ITEM9   -=-
0x9c	KEY_ITEM10  -=-
0x9d	KEY_ITEM11  -=-
0x9e	KEY_ITEM12  -=-
0x9f	PUZZLE_ITEM1  -=-
0xa0	PUZZLE_ITEM2  -=-
0xa1	PUZZLE_ITEM3  -=-
0xa2	PUZZLE_ITEM4  -=-
0xa3	PUZZLE_ITEM5  -=-
0xa4	PUZZLE_ITEM6  -=-
0xa5	PUZZLE_ITEM7  -=-
0xa6	PUZZLE_ITEM8  -=-
0xa7	PUZZLE_ITEM9  -=-
0xa8	PUZZLE_ITEM10  -=-
0xa9	PUZZLE_ITEM11  -=-
0xaa	PUZZLE_ITEM12  -=-
  
0xab	PICKUP_ITEM1  -=-
0xac	PICKUP_ITEM2  -=-
0xad	PICKUP_ITEM3  -=-
0xae	PICKUP_ITEM4  -=-

0xaf  EXAMINE1 -=-
0xb0  EXAMINE2 -=-
0xb1  EXAMINE3 -=-
  
0xb2 KEY_ITEM1_COMBO1 -=-
0xb3 KEY_ITEM1_COMBO2 -=-
0xb4 KEY_ITEM2_COMBO1 -=-
0xb5 KEY_ITEM2_COMBO2 -=-
0xb6 KEY_ITEM3_COMBO1 -=-
0xb7 KEY_ITEM3_COMBO2 -=-
0xb8 KEY_ITEM4_COMBO1 -=-
0xb9 KEY_ITEM4_COMBO2 -=-
0xba KEY_ITEM5_COMBO1 -=-
0xbb KEY_ITEM5_COMBO2 -=-
0xbc KEY_ITEM6_COMBO1 -=-
0xbd KEY_ITEM6_COMBO2 -=-
0xbe KEY_ITEM7_COMBO1 -=-
0xbf KEY_ITEM7_COMBO2 -=-
0xc0 KEY_ITEM8_COMBO1 -=-
0xc1 KEY_ITEM8_COMBO2 -=-

0xc2	PUZZLE_ITEM1_COMBO1 -=-
0xc3	PUZZLE_ITEM1_COMBO2  -=-
0xc4	PUZZLE_ITEM2_COMBO1  -=-
0xc5	PUZZLE_ITEM2_COMBO2  -=-
0xc6	PUZZLE_ITEM3_COMBO1  -=-
0xc7	PUZZLE_ITEM3_COMBO2  -=-
0xc8	PUZZLE_ITEM4_COMBO1  -=-
0xc9	PUZZLE_ITEM4_COMBO2  -=-
0xca	PUZZLE_ITEM5_COMBO1  -=-
0xcb	PUZZLE_ITEM5_COMBO2  -=-
0xcc	PUZZLE_ITEM6_COMBO1  -=-
0xcd	PUZZLE_ITEM6_COMBO2 -=-
0xce	PUZZLE_ITEM7_COMBO1 -=-
0xcf	PUZZLE_ITEM7_COMBO2 -=-
0xd0	PUZZLE_ITEM8_COMBO1 -=-
0xd1	PUZZLE_ITEM8_COMBO2 -=-

0xd2  PICKUP_ITEM1_COMBO1 -=-
0xd3  PICKUP_ITEM1_COMBO2 -=-
0xd4  PICKUP_ITEM2_COMBO1 -=-
0xd5  PICKUP_ITEM2_COMBO2 -=-
0xd6  PICKUP_ITEM3_COMBO1 -=-
0xd7  PICKUP_ITEM3_COMBO2 -=-
0xd8  PICKUP_ITEM4_COMBO1 -=-
0xd9  PICKUP_ITEM4_COMBO2 -=-

* 0x83  level-data-end  *no arguments* - this opcode appears at the end of every level (incl. title) block

The Bitfield16 levelOptions/titleOptions is laid out as follows (per-bit description):

  1. YoungLara
  2. Weather
  3. Horizon
  4. Horizon (has to be paired with 3)
  5. Layer2 used (?)
  6. Starfield
  7. Lightning
  8. Train
  9. Pulse
  10. ColAddHorizon
  11. ResetHUB used
  12. ColAddHorizon (has to be paired with 10)
  13. Timer
  14. Mirror used
  15. RemoveAmulet
  16. NoLevel