Tomb Raider Level File Format

Tomb Raider I/II/III/IV Data File Format
Document Version 1.00 (20030811)

    

Foreword

This document is aimed at superseding the respectable TRosettaStone document which is dated of late 99 ! It was (and is yet) an invaluable source of information when it comes to work with the file format used by the Tomb Raider engines. This document owes a lot to TRosettaStone and is not a complete rewrite: it retains the majority of the original text. But I felt it was time to correct / update the document because since the last 4 years a lot of work from different people shed some new lights on the TR file formats.

This document only describes the level file format, not the .DAT file nor the ID / animations of the different items found in the game.Those may be the subject of other documents, that have yet to be written. You can have a look to the original TRosettaStone document as it has a lot of information about these subjects.

Note on the screenshots: the screenshots you can see in this document are taken either from the game or from TRPlayer, a tool which attempts to display Tomb Raider levels and whose sources will be available soon here. The source of the screenshot is specified when needed, but basically if you can see Lara, it's from the game, else it's from TRPlayer :). When the screenshot quality does not matter, I tried to lower it as much as possible to lighten the weight of the images.

Contributors

Several people have been involved in the (difficult) task of deciphering the TR file formats (not only the level file format). Here's an alphabetical list (if you have contributed in a way or another and are not in this list, please contact me  and I will update it) , but before that I have to give a special thanks to the TRosettaStone writer  and historically first contributor, R.Stone (or is he M.Bartoli ?): without you, nothing could exist in the "Unofficial TR Community", as it is known. You deserve much of the greetings. 

And for the remaining part of the greetings, here's the list of people:

Popov, Rgbold, TRWad, Turbo Pascal, Dr. Willard, Yuri Zhivago

Most of them can be reached at the unofficial community forum here.

If you have some corrections to make on this document or some new information to add, feel free to contact me (Popov), as I will try to maintain this document up to date as much as I can. Please, don't spread modified copy of this document yourself, instead send me a mail so that I can apply the modifications myself: it will be safer in the long run because we know modifications can only be issued from one source, not from any people around the world. Of course, you can still spread this document itself (but as-is) !

English is not my native language (far from it !), so this document would need a thorough review and lots of corrections to make it acceptable. So, if yourself are an english guy (or even just better than me) and have some free hours to waste...

Conventions used in this doc

Abbreviations

Abbreviation Description
TR Tomb Raider
TRSDoc The original TRosettaStone document
TR1 Tomb Raider 1. It also includes TR1 unfinished business if not otherwise stated
TR2 Tomb Raider 2. It also includes TR2 Golden Mask if not otherwise stated
TR3 Tomb Raider 3 - Adventures of Lara Croft. It also includes TR3 Lost Artifact if not otherwise stated
TR4 Tomb Raider 4 - The last revelation
TRLE Tomb Raider Level Editor, shipped with Tomb Raider Chronicles (TR5)

Differences between TR file formats

When something is only relevant to a specific TR version, these icons will be used:

TR1 only: 
TR2 only: 
TR3 only: 
TR4 only: 

These icons can be combined if something applies to several TR versions but not all (for eg.  would mean that whatever follows the icons is applicable only to TR3 and TR4). When a block of text is specific to some given TR versions, it is showed like that:


Here some specifities of TR3/4 are explained...

Using the following combo-box, you can filter this document to only show information relevant to a specific TR version. By default, this document show all information from all TR versions. Try to filter on TR1 or TR2: the above text should disappear...

Filter for

Other icons

Other icons have been used throughout this text:

 indicates that's something is unknown and has to be worked out. If you think you can help on those ones, don't be shy and drop me a line !

Additional thanks

Thanks to clipart-graphics.net for providing the icons found in this text.
Some pictures were also taken from the official Tomb Raider web site.

Unknowns

Here's the list of current unknowns:


Introduction

This document contains detailed descriptions of the Tomb Raider I / II / III / IV data file formats. It is assumed that the reader has knowledge and experience programming in C or C++, and has at least a passing familiarity with graphics programming. All information in this document was derived from different people (see the foreword ), without the aid or assistance of anyone at Core Design or Eidos (though, the TRLE has been used to help working out some part of the file format). As such, the information in this document may contain errors or omissions, and all structure and variable names were deduced from the interpretation of the data (and therefore could be misleading or completely wrong). All the information in this document was tested and is therefore plausible, but could also be a misinterpretation. All information herein is provided as is - you get what you pay for, and this one's free. This was a spare-time project that set out to document the Tomb Raider 2 (.TR2) file format; along the way, additional information about Tomb Raider 1 / Gold (.PHD, .TUB) and Tomb Raider 3 (.TR2) files became available, and that information is provided in context. Tomb Raider 4 (.TR4) file format description is now also integral part of this document.

Because of Core/Eidos' position on Tomb Raider level editing tools, it is suggested that any tools that you develop be released in source code form, anonymously, using Usenet newsgroups.  Anonymity can protect you from legal action, wide distribution via Usenet prevents Core/Eidos from attempting to recall or control the distribution of your software, and distributing source code both allows multi-platform development (e.g. let others port it to the Mac or Linux for you) and encourages others to write utilities, since they can learn and benefit from your source code.  Also, Linux has taught us that 40,000 people debugging a single application makes for a clean final product ;-)

Tomb Raider, Tomb Raider Gold, Unfinished Business, Tomb Raider II, Tomb Raider III, Tomb Raider IV, Lara Croft, and all images and data within the data files and game engine are Copyright © Core Design and/or Eidos PLC.  Modification and/or distribution of any part of a Tomb Raider data file (any version) is almost certainly a copyright violation.

This document was composed at a screen resolution of 1024x768, and is best viewed at that resolution.  This document can be viewed offline (not connected to the Internet), provided that you download the whole package here to get all the additional images.  If you do not, images will be broken links, but the text can still be read. Use your browser's BACK button to return from a link, e.g. if you click on a structure declaration to see its definition, clicking BACK will return you to your point of origin after you've examined the structure definition.


Table of Contents


I. The Fundamentals

Overview

Tomb Raider is driven by two sets of files. The script file, TOMBPC.DAT, contains all the text strings describing the various elements in the game (e.g. the game engine knows about "Key 1"; it looks in TOMBPC.DAT to determine the name to be displayed in Lara's inventory, such as "Rusty Key" or "Taste rostige" or "Clé Rouillée"), the level and cut-scene filenames (e.g. WALL.TR2, CUT3.TR2), the order in which they are to be played, and various per-level and per-game configuration options (e.g. what weapons and objects Lara starts the level with, whether or not the "cheat" codes work, etc.). The level files, {level-name}.PHD / TUB / TR2 / TR4, contain everything about the level, including the geographical geometry, the geometry (meshes) of all animate and inanimate objects in the level, all the textures and colour data, all animation data, index information (and, in TR1 and TR4, the actual sound sample data) for all sounds, accessibility maps - everything necessary to run the game. For whatever reason, Core has included everything in one file instead of breaking it up into logical groupings; this means that every level contains all the meshes, textures, sound information, and animation data for Lara and all of her weapons. There are a fair number of other redundancies, too.

Note: this document does not deal with the TOMBPC.DAT ! See foreword .

Basic data types

For the purposes of further discussion, the following are assumed:

  bit8 specifies an 8-bit signed integer (range -128..127)
  bitu8 specifies an 8-bit unsigned integer (range 0..255)
  bit16 specifies a 16-bit signed integer (range -32768..32767)
  bitu16 specifies a 16-bit unsigned integer (range 0..65535)
  bit32 specifies a 32-bit signed integer (range -2147483648..2147483647)
  bitu32 specifies a 32-bit unsigned integer (range 0..4294967295)
  float specifies a 32-bit signed float (range ?)

All multi-byte integers are stored in little-endian (Intel-x86, etc.) format, with the least significant byte stored first and the most significant byte stored last. When using this data in platforms with big-endian (PowerPC, etc.) number format, be sure to reverse the order of bytes.

Data alignment is something one has to be careful about. When some entity gets an address that is a multiple of n, it is said to be n-byte aligned. The reason it is important here is that some systems prefer multibyte alignment for multibyte quantities, and compilers for such systems may pad the data to get the "correct" alignments, thus making the in-memory structures out of sync with their file counterparts. However, a compiler may be commanded to use a lower level of alignment, one that will not cause padding. And for TR's data structures, 2-byte alignment should be successful in nearly all cases, with exceptions noted below.

To set single-byte alignment in Microsoft Visual C++, use the following compiler directive:

#pragma pack(push, tr2, 1)
To return to the project's default alignment, use the following directive:
#pragma pack(pop, tr2)

To achieve 2-byte alignment in Metrowerks CodeWarrior, widely used in the MacOS, use this compiler directive:

#pragma options align=mac68k
To return to the project's default alignment, use this directive:
#pragma options align=reset
Similar options exist for other compilers.

Coordinates

The world coordinate system is oriented with the X-Z plane horizontal and Y vertical, with -Y being "up" (e.g. decreasing Y values indicate increasing altitude). The world coordinate system is right-handed (+X goes right, +Y goes bottom and +Z goes 'into' the screen) and is specified using bit32 values; however, the geography is limited to the +X/+Z quadrant for reasons that are explained below. Mesh coordinates are relative and are specified using bit16 s.  There are some additional coordinate values used, such as "the number of 1024-unit blocks between points A and B";  these are simply scaled versions of more conventional coordinates.

Colours

All colours in TR are specified either explicitly (using either the tr_colour structure, described below, or the 16-bit ARGB structure) or implicitly, by indexing one of the palettes (only in TR1/2/3 - there's no palette in TR4).


If, for some reason, 16-bit textures are turned off, all colours and textures use an 8-bit palette that is stored in the level file.  This palette consists of a 256-element array of tr_colour structures, each designating some colour;  textures and other elements that need to reference a colour specify an index (0..255) into the Palette[] array.  There is also a 16-bit palette, which is used for identifying colours of solid polygons.  The 16-bit palette contains up to 256 four-byte entries;  the first three bytes are a tr_colour, while the last byte is ignored (set to 0).

The 16-bit textile array, which contains tr_textile16 structures, specifies colours using 16-bit ARGB, where the highest bit (0x8000) is a crude alpha channel (really just simple transparency - 0 ::= transparent, 1 ::= opaque).  The next 5 bits (0x7c00) specify the red channel, the next 5 bits (0x03e0) specify the green channel, and the last 5 bits (0x001f) specify the blue channel, each on a scale from 0..31.


The 32-bit textile array, which contains tr_textile32 structures, specifies colours using 32-bit ARGB, where the highest byte is the alpha channel (255 means the texel is fully opaque, 0 the texel is fully transparent).  The next bytes specify (in this order) the red / green / blue channels. The 16 and 32-bit textile arrays depict the same graphics data, but of course the 32-bit array has a better color resolution. It's the one used if you select a 32 bits A8R8G8B8 texture format in the setup menu from TR4.

Objects

There are two basic types of objects in TR - meshes and sprites. Meshes are collections of textured or coloured polygons (only in TR1/2/3 - there are no coloured polys in TR4) that are assembled to form a three-dimensional object (such as a tree, a tiger, or Lara herself). The "rooms" themselves are also composed of meshes. Mesh objects may contain more than one mesh; though these meshes are moved relative to each other, each mesh is rigid. Sprites are two-dimensional images that are inserted into three-dimensional space, such as the "secret" dragons, ammunition, medi-packs, etc. There are also animated sprite sequences, such as the fire at the end of "The Great Wall." Core had presumably used this method to reduce CPU utilization on the PlayStation and/or the earlier PCs. Sprites become less and less abundant; TR2 has very few scenery sprites, and TR3's pickups are models instead of sprites. Objects are referenced in one of two ways - as an offset into an array (e.g. Moveables[i]) or using an identifying tag (ObjectID). In the latter case, the related array (Items[], Moveables[], etc.) is searched until a matching ObjectID is found.

Animations

There are three basic types of animations in TR, two corresponding directly with meshes and sprites, and a third type, animated textures. Sprite animation (sprite sequences) consists simply of a series of sprites that are to be displayed one after another, e.g. grenade explosions. Mesh animations are much more complex, done by what is essentially a skeletal-modeling scheme. These involve some arrays (Frames[] and MeshTree[]) of offsets and rotations for each element of a composite mesh. Frames are then grouped into an array (Animations[]) that describes discrete "movements," e.g. Lara taking a step or a tiger striking with its paw. The animations are "sewn together" by a state change array and an animation dispatch array, which, together with state information about the character, ensure that the animation is fluid (e.g. if Lara is running and the player releases the RUN key, she will stop; depending upon which of her feet was down at the time, either her left or right foot will strike the floor as part of the "stop" animation. The correct animation (left foot stop vs. right foot stop) is selected using these structures and the state information). Animated textures are simply a list of textures that are cycled through in an endless loop; they are normally used as geographic elements of the levels (e.g. water surface, bubbling lava, Atlantean plasma walls).


TR4 uses a new scheme to cycle through the list of textures in an animated texture: you can see it in action in angkor1.tr4, room # 76:

The animated texture here is made of two textures and we can see in the game that the textures scroll in the v coordinate direction.
  We still have to work out how this new scheme is selected over the old one (a bit somewhere would tell it ?) and how in the end the animation is rendered (are the two textures modulated before rendering ? is it possible to have more than two textures ?).

Lighting

There are two main types of lighting in Tomb Raider, constant and vertex. Constant lighting means that all parts of an object have the same illumination, while in vertex lighting, each polygon vertex has its own light value, and the illumination of the polygon interiors is interpolated from the vertex values. Furthermore, lighting can be either internal or external. Internal lighting is specified in an object's data, external lighting is calculated using the room's light sources (ambient light, point light sources, spot lights (TR4), flares, gunshots). When available, external lighting also uses the vertex normals to calculate the incoming light at each vertex. Light intensities are described either with a single value or with a 16 bits color value (you can see it more like a 'color filter'), depending mainly on the TR version.

Textures

All mesh surfaces are either coloured or textured  (only textured in TR4) .  Coloured surfaces are "painted" with a single colour that is either specified explicitly or using an index into the palette.  Textured surfaces map textures (bitmapped images) from the texture tiles (textiles) to each point on the mesh surface.  This is done using conventional UV mapping, which is specified in "Object Textures" below; each object texture specifies a mapping from a set of vertices to locations in the textile, and these texture vertices are associated with position vertices specified here. Each textile is a 256x256 pixels wide area.

Sounds

There are several sorts of sounds, which can be classified as either continuous or triggered. Continuous sounds are level-background sounds (such as the blowing wind in "The Great Wall") and sound sources (such as waterfalls; these are in SoundSources[]). Triggered sounds are sounds played when some event happens, such as at certain animation frames (footsteps and other Lara sounds), when doors open and close, and when weapons are fired. Sounds are stored in two places: the game-data files and the CD audio tracks (the latter are separate soundfiles in the MacOS version). The latter kind of sound is referred to straightforwardly, by index, while the former kind of sound is referred to using a three-layer indexing scheme, to provide a maximum amount of abstraction. An internal sound index references SoundMap[], which points to a SoundDetails[] record, which in turn points to a SampleIndices[] entry, which in turn points to a sound sample. SoundDetails[] contains such features as sound intensity, how many sound samples to choose from, among others. The sound samples themselves are in Microsoft WAVE format, and they are embedded either in the data files (TR1 / TR4) or in a separate file (MAIN.SFX) in TR2 and TR3. 

Basic Data Structures

Much of the .TR file is comprised of structures based on a few fundamental data structures, described below.

(Some compilers, like CodeWarrior, will pad this structure to make 4 bytes; one must either read and write 3 bytes explicitly, or else use a simple array of bytes instead of this structure.)


    And as mentioned earlier, the 16-bit palette uses a similar structure:


If the rectangle is a coloured polygon (not textured), the .Texture element contains two indices: the low byte (.Texture & 0xff) is an index into the 256-colour palette, while the high byte (.Texture >> 8) is in index into the 16-bit palette, when present. 

The Texture field can have the bit 15 set : when it is, the face is two-sided (ie. visible from both sides)

The extra field LightingEffect exists only for tris / quads making meshes (used by moveables and static meshes), not for tris / quads making rooms ! It has this layout:

Bit 0 not set Bit 0 set Bit 1-7 all set to 0 Bit 1-7 all set to 1


                    1-bit transparency (0 ::= transparent, 1 ::= opaque) (0x8000)
                    5-bit red channel (0x7c00)
                    5-bit green channel (0x03e0)
                    5-bit blue channel (0x001f)




II. Room Geometry

Overview

A room in TR2 is simply a rectangular three-dimensional area. A room may be "indoors" or "outdoors," may or may not be enclosed, may be accessible or inaccessible to Lara, may or may not contain doors or objects. All rooms have "portals," called "doors" in some documentation, which are pathways to adjacent rooms. There are two kinds of portals, visibility portals and collisional portals. Visibility portals are for determining how much of a room (if any) is visible from another room, while collisional portals are for enabling an object to travel from one room to another. The visibility portals are most likely for doing "portal rendering", which is a visibility-calculation scheme that goes as follows: The viewpoint is a member of some room, which is then listed as visible from it. This room's (visibility) portals are checked for visibility from that viewpoint, and visible portals have their opposite-side rooms marked as visible. These rooms are then checked for portals that are visible from the viewpoint through the viewpoint's room's portals, and visible ones have their opposite-side rooms marked as visible. This operation is repeated, with viewing through intermediate portals, until all visible portals have been found. The result is a tree of rooms, starting from the viewpoint's room; only those rooms and their contents need be rendered. It is clear that both visibility and collision calculations require that objects have room memberships given for them, and indeed we shall find that most map objects have room memberships. Try to give a look here for in-depth information about Portal rendering.

Rooms may overlap; as we shall see, this is involved in how horizontal collisional portals are implemented. However, different rooms may overlap without either being directly accessible from the other; there are several inadvertent examples of such "5D space" in the Tomb Raider series. The only possibly deliberate example I know of is the flying saucer in "Area 51" in TR3, whose interior is bigger than its exterior.

A room can have an "alternate room" specified for it; that means that that room can be replaced by that alternate as the game is running. This trick is used to produce such tricks as empty rooms vs. rooms full of water, scenery rearrangements (for example, the dynamited house in "Bartoli's Hideout" in TR2), and so forth. An empty room is first created, and then a full room is created at its location from a copy of it. The empty room then has that full room set as its alternate, and when that room is made to alternate, one sees a full room rather than an empty one.

The rooms are stored sequentially in an array, and "Room Numbers" are simply indices into this array (e.g. "Room Number 5" is simply Rooms[5]; the first room is Rooms[0]).

Rooms are divided into Sectors, which are 1024x1024 unit squares that form a grid on the X-Z plane.  Sectors are the defining area for floor/ceiling height and various actions (e.g. a tiger appears and attacks when Lara steps on a given square);  the various attributes of each sector are stored in the Sector Data (described in this section) and the FloorData .  As an aside, Sectors correspond to the "squares," easily visible in all of the Tomb Raider games, that experienced players count when gauging jumps;  they also account for some of the game's less-appealing graphic artifacts. Careful tiling and texture construction can make these "squares" almost invisible.

Rooms have two kinds of surfaces, rendered and collisional, much like the two kinds of portals. The former are what is seen, while the latter control how objects interact with the world geometry. Furthermore, these two types are specified separately in the room data.

Rooms are defined with a complex structure, which is described below "inside-out," meaning that the smaller component structures are described first, followed by the larger structures that are built using the smaller structures.

Room Structures


BoxIndex is more complicated:


Furthermore, there is a special value of the "real" index, 2047, or 0x7ff.
  So, there's the need to fully understand this field when used by TR3/4...

Intensity1 ranges from 0 (dark) to 0x1FFF (bright). However, some rooms occasionally have some lights with intensity greater than 0x1FFF (look at room #9, 2nd light in level1.phd for eg).
Fade1 is the distance max the light shines on and ranges from 0 to 0x7FFF.

Intensity1 ranges from 0 (dark) to 0x1FFF (bright). However, some rooms have some lights with intensity greater than 0x1FFF (look at room #17, 2nd light in xian.tr2 for eg). Really, the range is from 0 to 0x7FFF (ultra bright). Above 0x7FFF, it seems the light is always black...
Fade1 is the distance max the light shines on and ranges from 0 to 0x7FFF.
 Intensity2 and Fade2 seem not to be used...

Intensity1+Intensity2 is light color. Format is 0x00BBGGRR (Intensity1 is 0xGGRR and Intensity2 is 0x00BB).
Fade1 is the power of the light and ranges mainly from 0 (low power) to 0x1FFF (high power). Though, values greater than 0x1FFF do exist and their meanings are unknown.
Fade2 is the distance max the light can shine on. Range is mainly from 0 to 0x7FFF, but negative values do exist and their meanings are unknown.
 Need to work out accurately the Fade1 and Fade2 fields...

TR4 has a rather different room light structure:


 Have to describe precisely the fields of the tr4_room_light structure...

Lighting1 ranges from 0 (bright) to 0x1FFF (dark)


 Changing the value of Lighting1 seems to do nothing...
Lighting2 ranges from 0 (bright) to 0x1FFF (dark)


 Changing the value of Lighting1 seems to do nothing...
Lighting2 is the per-vertex color, in this format (16 bits): 0RRRRRGGGGGBBBBB


Attributes is a set of flags:



The lowest 5 bits are used in combination with the LightMode field of the tr_room structure. See below.

 Changing the value of Intensity2 seems to do nothing...
Intensity1 ranges from 0 (bright) to 0x1FFF (dark). There's not a -1 special value for Intensity1 as stated in TRSDoc: mesh lighting is always used


 Changing the value of Intensity2 seems to do nothing...
Intensity1 is constant color with format (16 bits): 0BBBBBGGGGGRRRRR

Flags have these meanings:


AmbientIntensity1 ranges from 0 (bright) to 0x1FFF (dark).
 AmbientIntensity2 seems not to be used in TR2/3 (should use 0 for TR3 though, else strange effects...).

AmbientIntensity1 + AmbientIntensity2 is the ambient color. R = low 8 bits of AmbientIntensity2, G = high 8 bits of AmbientIntensity1 and B = low 8 bits of AmbientIntensity1.

LightMode can have these values (LightMode is not a bitfield !):


When LightMode is 1 or 2, it works in conjunction with the 5 lowest bits of vertex attributes:

III. FloorData

The FloorData defines special sector attributes such as floor and ceiling slopes, collisional portals to other rooms, climbability of walls, and all the various types of triggering. It is referenced by the sectors as an array of 16-bit unsigned integers, e.g. the current sector is calculated as (((CurrentX - tr_room_info.x) / 1024) * tr_room.NumZsectors) + ((CurrentZ - tr_room_info.z) / 1024), which is then used as an offset into tr_room:: SectorList[]; tr_room_sector::FDindex is an offset into the FloorData[] array.

The FloorData consists of opcodes and operands.  Opcodes are 16 bits, as follows:
        Function:           bits 0..7 (0x00FF)
        SubFunction:    bits 8..14 (0x7F00)
        EndData:           bit 15 (0x8000)
If EndData is set, there are no more opcodes (after the current one) in this section of FloorData;  otherwise, the next opcode in FloorData should be interpreted after the current one.

Some functions reference an FDlist, which is a separate list of opcodes and operands that immediately follows the current FloorData opcode.  FDlist opcodes and operands are different from the base FloorData opcodes and operands:
        FDfunction:  bits 10-13 (0x3C00)
        Operands:  bits 0-9 (0x03FF) vary, depending on FDfunction
        FDcontinue:  bit 15 (0x8000)

Several of the functions indicate adjustments to the sector's floor and ceiling heights; these are specified by adjusting the corner heights. The corners will be denoted as 00, 01, 10, and 11; the first is the corner's X coordinate and the second is the corner's Z coordinate, with both given as multiples of 1024.

When parsing functions for TR3, use only the lower 5 bits to find the function value, because some of TR3's functions use the upper 3 bits of the lower byte as part of the operand. However, this will also work correctly in TR1 and TR2.

FloorData Functions are described below.
    Function 0x01: Portal Sector
        SubFunction 0x00: Room Portal: the next FloorData element (the operand) is the number of the room that this sector is a collisional portal to.
        An entity that arrives in a sector with this function present will gets its room membership changed to this function's operand, without any change in position.

    Function 0x02: Floor Slant
        SubFunction 0x00: Floor Slant: The next FloorData element contains the slant values for the floor of this sector.  Slant values are specified in increments of 256 units. The high byte (bit8) is the Z slope, while the low byte (bit8) is the X slope. If the X slope is greater than zero, then its value is added to the floor heights of corners 00 and 01. If it is less than zero, then its value is subtracted from the floor heights of corners 10 and 11. If the Z slope is greater than zero, then its value is added to the floor heights of corners 00 and 10. If it is less than zero, then its value is subtracted from the floor heights of corners 01 and 11.

    Function 0x03: Ceiling Slant
        SubFunction 0x00: Ceiling Slant: The next FloorData element contains the slant values for the ceiling of this sector.  Slant values are specified in increments of 256 units. The high byte (bit8) is the Z slope, while the low byte (bit8) is the X slope. If the X slope is greater than zero, then its value is subtracted from the ceiling heights of corners 10 and 11. If it is less than zero, then its value is added to the ceiling heights of corners 00 and 01. If the Z slope is greater than zero, then its value is subtracted from the ceiling heights of corners 00 and 10. If it is less than zero, then its value is added to the ceiling heights of corners 01 and 11.

    Function 0x04: Trigger items, switch cameras, end the level and much more.
As used below, "run FDlist(activate or deactivate)" means go through each element in FDlist and perform its function ("run FDlist+1" just means start at FDlist[1] rather than FDlist[0]).  Activate/deactivate is only used for the activate/deactivate item function.
There are two states for each item, active/inactive (the meaning depends on the item, e.g. a tiger must be active to be seen, if a door is active it is open, if it is inactive it is closed, etc.) and on/off (keyholes and switches).
The bitu16 immediately following the 0x04 FloorData opcode contains flags; the bits at 0x3e00 are the Activation Mask (which is XORed with any appropriate item flags), the bit at 0x0100 indicates "state change occurs only once". A good example of activation-mask use is the multiple-switch room of "Palace Midas" in TR1.
        SubFunction 0x00: Run FDlist(activate)
        SubFunction 0x01: If Lara is on the ground, run FDlist(activate)
        SubFunction 0x02: If item at FDlist[0] is on, run FDlist+1(activate), else run FDlist+1(deactivate)
        SubFunction 0x03: If item at FDlist[0] is on, run FDlist+1(activate)
        SubFunction 0x04: If item at FDlist[0] is picked up, run FDlist+1(activate)
        SubFunction 0x05: If item at FDlist[0] is in this sector, run FDlist+1(activate), else run FDlist+1(deactivate)
        SubFunction 0x06: If Lara is on the ground, run FDlist(deactivate)
        SubFunction 0x07: unknown
        SubFunction 0x08: If Lara is not on the ground, run FDlist(activate)
            (mainly used for activating collision detection with such objects as footbridges)
        SubFunction 0x09: Run FDlist(deactivate)

    Function 0x05: Kills Lara
        Any SubFunction: If Lara is on the ground, it kills Lara with fire.

    Function 0x06: Climbable Walls
        This subfunction indicates climbability of walls; its value is the bitwise OR of the values associated with all the climbable-wall directions (0x01 ::= +Z, 0x02 ::= +X, 0x04 ::= -Z, 0x08 ::= -X), e.g. SubFunction 0x09 indicates that the walls on both the +Z and -X sides of this sector are climbable.

      Functions 0x07 to 0x12: (only in TR3) These specify the floor and ceiling slopes, which are more complicated here, since these functions specify dividing up the floors and ceilings into triangles along either of the two diagonals. Also, one of the triangles may be a collisional portal to the room above (if in the ceiling) or to the room below (if in the floor). The function word must be parsed as follows:

Bit 15: Continuation bit
Bits 10-14: value t01
Bits 5-9: value t00
Bits 0-4 function value

where t00 and t01 are signed.

It is followed by one operand, to be parsed as follows:

Bits 12-15: value t13
Bits 8-11: value t12
Bits 4-7: value t11
Bits 0-3: value t10

where t10, t11, t12, and t13 are unsigned.

Here are the triangulations and vertex adjustments; for some of the functions, one of the triangles is a portal to another room:

Functions 0x07, 0x0b, 0x0c:

Triangle 1: 00-01-10 (function 0x0b: is a portal)
Triangle 2: 11-10-01 (function 0x0c: is a portal)

Overall adjustment: adj = t00 + t01 + t10 + t12

Add these quantities to these vertex floor heights:

00: (adj - t11)
01: (adj - t12)
10: (adj - t10)
11: (adj - t13)

Functions 0x08, 0x0d, 0x0e:

Triangle 1: 01-11-00 (function 0x0d: is a portal)
Triangle 2: 10-00-11 (function 0x0e: is a portal)

Overall adjustment: adj = t00 + t01 + t11 + t13

Add these quantities to these vertex floor heights:

00: (adj - t11)
01: (adj - t12)
10: (adj - t10)
11: (adj - t13)

Functions 0x09, 0x0f, 0x10:

Triangle 1: 00-10-01 (function 0x0f: is a portal)
Triangle 2: 11-01-10 (function 0x10: is a portal)

Overall adjustment: adj = t10 + t12

Subtract these quantities from these vertex ceiling heights:

00: (adj - t12)
01: (adj - t11)
10: (adj - t13)
11: (adj - t10)

Functions 0x0a, 0x10, 0x11:

Triangle 1: 01-00-11 (function 0x11: is a portal)
Triangle 2: 10-11-00 (function 0x12: is a portal)

Overall adjustment: adj = t11 + t13

Subtract these quantities from these vertex ceiling heights:

00: (adj - t12)
01: (adj - t11)
10: (adj - t13)
11: (adj - t10)
 

      Function 0x13: has subfunction 0x00 and no operand. Unknown, but is possibly monkey-swingability of the ceiling.
 
 

FloorData FDlist functions are described below:
    FDfunction 0x00: Activate or deactivate item
        Operand (bits 0..9): Item index

    FDfunction 0x01: Switch to camera (also uses the bitu16 immediately following)
        Operand (bits 0..6): Index in Cameras[]
   The bitu16 immediately following specifies delay and repeatability for switched camera
        Operand (bits 0..7 (0xff)): Camera Delay
           Number of seconds to wait before automatically switching back to the normal camera.
            0x00 never switches back to the normal camera.
        Operand (bit 8 (0x100)): If set, only switch to camera once; otherwise, switch to
camera every time

    FDfunction 0x02: Underwater Current
        Operand (bits 0..9 (0x3ff)): direction and intensity of flow
             0, 1, 2          -Z direction in decreasing intensity (0 is strongest)
             3, 4, 5          -X direction in decreasing intensity
             6, 7, 8          +Z direction in decreasing intensity
             9, 10, 11     +X direction in decreasing intensity

    FDfunction 0x03:: Set AlternateRoom Variable
        Operand (bit 0 (0x01)): AlternateRoom Flag value (0/1)

    FDfunction 0x04:  Alter Room Flags this affects (enhances/negates) roomflags (always paired with 0x05)
        Operand: not sure, range 0 - 5

    FDfunction 0x05: Alter Room Flags this affects (enhances/negates) roomflags (always paired with 0x04)
        Operand: not sure, range 0 - 5

    FDfunction 0x06: Look at Item (if a camera change is also desired, this should come first)
        Operand (bits 0..9 (0x3ff)): Item index

    FDfunction 0x07: End Level

    FDfunction 0x08: Play CD Track
        Operand (bits 0..9 (0x3ff)): CD track ID (TR1: Internal Sound Index )

    FDfunction 0x09: Assault Course Clock Control
        Operand (bits 0..9 (0x3ff)):
                0x1c ::= clear clock
                0x1d ::= stop clock
                0x1e ::= clock reset and displayed
        This opcode is also associated with switches; other values of its operand appear to indicate switch sounds.

    FDfunction 0x0a: Play "Found Secret" Sound
        Operand (bits 0..9 (0x3ff)): Which secret (0..NumSecrets-1)

    FDfunction 0x0b: Unknown

While FloorData index 0 means the sector does not use floordata, there is still a "dummy" entry for index 0.  This dummy entry doesn't contain any useful information.


IV. Mesh Geometry

Overview: Nearly all of the non-geographic visual elements in TR2 (as well as a few parts of the landscape) are specified as meshes.  A mesh is simply a list of vertices and how they're arranged.  The TR2 mesh structure includes a list of vertices as relative coordinates (which allows meshes to easily be placed anywhere in the world geometry), a list of normals (to indicate which side of each face is visible), and lists of Rectangles and Triangles, both Textured and Coloured.  The elements of each tr_face4 or tr_face3 structure (Rectangles and Triangles) contain an offset into the Vertices[] array for the mesh. Other arrays (Moveables[], StaticMeshes[]) do not reference the array Meshes[] directly, but instead reference the array MeshPointers[], which points to locations inside of Meshes[], inside of which the meshes are stored in packed fashion.

Meshes:
      The sign of the number of normals specifies which sort of lighting to use. If the sign is positive, then external vertex lighting is used, with the lighting calculated from the room's ambient and point-source lighting values. The latter appears to use a simple Lambert law for directionality: intensity is proportional to max((normal direction).(direction to source), 0). If the sign is negative, then internal vertex lighting is used, using the data included with the mesh.NOTE that this is not a "real" C/C++ structure, in that the arrays are sized by the NumXXX elements that precede them.

typedef struct {
    tr_vertex Centre; // This is usually close to the mesh's centroid, and appears to be the center of a sphere used for collision testing.
    bit32 CollisionSize; // This appears to be the radius of that aforementioned collisional sphere.
    bit16 NumVertices; // number of vertices in this mesh
    tr_vertex Vertices[NumVertices]; // list of vertices (relative coordinates)
    bit16 NumNormals; // If positive, number of normals in this mesh.
                                    // If negative, number of vertex lighting elements (* (-1))
    tr_vertex Normals[NumNormals]; // list of normals (if NumNormals is positive)
    bit16 Lights[-NumNormals]; // list of light values (if NumNormals is negative)
    bit16 NumTexturedRectangles; // number of textured rectangles in this mesh
    tr_face4 TexturedRectangles[NumTexturedRectangles]; // list of textured rectangles
    bit16 NumTexturedTriangles; // number of textured triangles in this mesh
    tr_face3 TexturedTriangles[NumTexturedTriangles]; // list of textured triangles
    bit16 NumColouredRectangles; // number of coloured rectangles in this mesh
    tr_face4 ColouredRectangles[NumColouredRectangles]; // list of coloured rectangles
    bit16 NumColouredTriangles; // number of coloured triangles in this mesh
    tr_face3 ColouredTriangles[NumColouredTriangles]; // list of coloured triangles
    } tr_mesh;
 
 

Static Meshes:

/*
 * StaticMesh structure. This defines meshes that don't move (e.g. skeletons
 * lying on the floor, spiderwebs, trees, statues, etc.)
 * StaticMeshes have two bounding boxes; it is not clear why they have more than
 * one. One could be the visibililty box, and one could be the collisional
 * box, for instance; the former being used for visibility testing, and the
 * latter for collision testing.
 */
typedef struct { // 32 bytes
    bitu32 ObjectID; // Object Identifier (matched in Items[])
    bitu16 Mesh; // mesh (offset into MeshPointers[])
    tr_vertex BoundingBox[2][2]; // First index is which one; second index is opposite corners
    bitu16 Flags; // Meaning uncertain; it is usually 2, and is 3 for objects Lara can travel through,
                      // like TR2's skeletons and underwater vegetation
    } tr_staticmesh;
 
 

Moveables:

/*
 * Moveable structure. This defines a list of contiguous meshes that
 * comprise one object.
 * This structure also points to the hierarchy and offsets of the meshes
 * (MeshTree), and also to the animations used (Animation); these will be
 * described in detail below. If the Animation index is -1, that means that
 * the entity's animations are all generated by the engine; an example is
 * Lara's ponytail. Some movables are really stationary, such as locks and
 * the sky, and some are not rendered, such as "look at me" points to aim
 * the camera at.
 */
typedef struct { // 18 bytes
    bitu32 ObjectID; // Item Identifier (matched in Items[])
    bitu16 NumMeshes; // number of meshes in this object
    bitu16 StartingMesh; // stating mesh (offset into MeshPointers[])
    bitu32 MeshTree; // offset into MeshTree[]
    bitu32 FrameOffset; // byte offset into Frames[] (divide by 2 for Frames[i])
    bitu16 Animation; // offset into Animations[]
    } tr_moveable;
 
 

Items: Items are instances of objects, which can be sprite sequences or movables. For an object to appear in a level, it must be referenced in the Items[] array. Multiple instances are possible (e.g. two identical tigers in different rooms are represented using two entries in Items[], one for each). The object ID is used to locate the appropriate sprite sequence or movable for the item.

typedef struct {     // 24 bytes [TR1: 22 bytes]
    bit16 ObjectID; // Object Identifier (matched in Moveables[], or SpriteSequences[], as appropriate)
    bit16 Room; // which room contains this item
    bit32 x; // item position in world coordinates
    bit32 y;
    bit32 z;
    bit16 Angle; // ((0xc000 >> 14) * 90) degrees
    bit16 Intensity1; // (constant lighting; -1 means use mesh lighting)
    bit16 Intensity2; // Like Intensity1, and almost always with the same value. [absent from TR1 data files]
    bitu16 Flags; // 0x0100 indicates "initially invisible", 0x3e00 is Activation Mask
                            // 0x3e00 indicates "open" or "activated";  these can be XORed with
                           // related FloorData::FDlist fields (e.g. for switches)
    } tr_item ;

Sprites:

These are "billboard" objects that are always rendered perpendicular to the view direction. These are used for text and explosion effects and similar things; they are also used for some scenery objects and pickup items, though this use gets less as one goes from TR1 to TR3. The various "Sides" below are the positions of the sprite sides relative to the sprite's overall position, measured in TR's world-coordinate units.

typedef struct { // 16 bytes
    bitu16 Tile;
    bitu8 x;
    bitu8 y;
    bitu16 Width;        // actually (Width * 256) + 255
    bitu16 Height;       // actually (Height * 256) + 255
    bit16 LeftSide;
    bit16 TopSide;
    bit16 RightSide;
    bit16 BottomSide;
    } tr_sprite_texture;
 
 

Sprite Sequences:
These are collections of sprites that are referred to as a group. The members of this group can be cycled through (animated sprites such as flames) or selected in other ways (text). Some sequences have only one member; this is done so as to access all the sprites in the same way.

typedef struct { // 8 bytes
    bit32 ObjectID; // Item identifier (matched in Items[])
    bit16 NegativeLength; // negative of "how many sprites are in this sequence"
    bit16 Offset; // where (in sprite texture list) this sequence starts
    } tr_sprite_sequence ;


V. Mesh Construction and Animation

Overview:
The animated mesh objects in the Tomb Raider series are sets of meshes that are moved relative to each other, as defined by Moveables[] entries. Each entry describes which meshes to be used (a contiguous set of them referred to in MeshPointers[]), what hierarchy and relative offsets they have (contents of MeshTree[] pointed to), and what animations are to be used (contents of Animations[] pointed to).

The hierarchy used is a branching one, with the meshes being at the nodes, and with the first mesh being the root node. The MeshTree[] values, called "Bone2" in some documentation, are applied to each of the child meshes in sequence; they are sets of four bit32's, the first being a hierarchy operator, and the remaining three being the coordinates in the parent mesh's system. A hierarchy example is that for the Lara meshes:

Hips
        Left thigh
                Left shin
                        Left foot
        Right thigh
                Right shin
                        Right foot
        Torso
                Left inner arm
                        Left outer arm
                                Left hand
                Right inner arm
                        Right outer arm
                                Right hand
                Head
(Ponytail is a separate object)
This is implemented by using a stack of meshes and "push" and "pop" operations in MeshTree[]. Normally, each mesh's parent is the previous mesh in series. But such meshes can be "remembered" by adding them to a stack of meshes with a "push" operation. This remembered mesh can then be used as the parent mesh with a "pop" operation. It is not clear what the maximum stack depth is; most TR mesh stacks do not extend beyond 2 or 3 meshes.

The animations for each mesh object are selected with some ingenious techniques. Which animations to use are not hardcoded; instead, each entity has some states it can be in, and these states are used to select which animation. For example, locks have only one state (they just sit there), doors have two states (open and closed), and Lara has numerous states, such as standing, walking, running, jumping, falling, being hurt, dying, etc. Each animation has a state ID, which can be used to select it; however, state transitions might seem to require a large number of intermediate states (opening, closing, starting to jump, landing, etc.). The alternative used in the Tomb Raider engine is for each animation to have bridge animations to other states' animations, which are selected using the ID of which state to change to. These bridge animations then lead to the animation with the appropriate state. Thus, a closed door will run a looped closed-door animation as long as its state stays "closed", but when its state becomes "open", it will change to an opening-door bridge animation, which will end in a looped open-door animation. Likewise, closing a door will make it use a closing-door bridge animation. Some bridge animations are chosen with a finer grain of selectivity, however, such as using one for left foot forward and one for right foot forward.

Thus, each animation references a set of StateChange structures (called simply a "structure" in some documentation), each one of which references an AnimDispatch structure (called a "range" in some documentation). Each StateChange structure contains a new state and which AnimDispatch structures to use. When an entity goes into a new state, the StateChange structures are scanned for that state's ID, and if one matches, then that StateChange's AnimDispatches are then scanned for a range of frames that contains the ID of the current frame. If such an AnimDispatch is found, the animation and the frame are changed to those listed in it.

The ultimate unit of animation is, of course, the frame, and each frame consists of a bounding box, the offset of the root mesh, and rotation angles for all the meshes with respect to their parent meshes. The root mesh is also rotated, but relative to the object's overall coordinates. All rotations are performed around the meshes' origins, and are in order Y, X, Z (yaw, pitch, roll). The reason for the root mesh's displacement is because entities traveling on solid surfaces are likely tracked by having their locations be at ground level, and Lara's hips, for example, are well above the ground. Finally, some of the angles are not specified explicitly, when they are not, they are zero.

Frames are referenced in two ways, either by an offset into the Frames[] array that contains them, or by frame index. The values of the latter appear to be unique to each kind of entity, but not between entities; the first frame for each kind is numbered 0. This is likely a convenience when constructing the animations, since the list of animation frames for each entity can be constructed separately. However, using these indices is fairly simple. Each Animation structure has a first-frame index; this index is subtracted from the index of the desired frame in order to find out its index relative to the animation's first frame.

There are also some special AnimCommands (called "Bone1" in some documentation) for doing various additional things. Some of them are for setting reference points; these may either be 3D ones, for example for grab locations, or 2D ones, for jumps from surface. Some others define actions per frame, like playing sounds, emitting bubbles, and so forth.

Finally, some entities appear to have very incomplete animations; their complete animations are "borrowed" from similar entities. One example of this is the various goons in TR2's Venice levels -- some of them have a full set of animations, while some others have only the standing animation. The ones with only the standing animation borrow their other animations from the fully-animated ones.

Data Structures:

/*
 * MeshTree structure
 *
 * MeshTree[] is actually groups of four bit32s. The first one is a
 * "flags" word;
 *    bit 1 (0x0002) indicates "put the parent mesh on the mesh stack";
 *    bit 0 (0x0001) indicates "take the top mesh off of the mesh stack and use as the parent mesh"
 * when set, otherwise "use the previous mesh are the parent mesh".
 * When both are present, the bit-0 operation is always done before the bit-1 operation; in effect, read the stack but do not change it.
 * The next three bit32s are X, Y, Z offsets of the mesh's origin from the parent mesh's origin.
 */
typedef struct { // 4 bytes
    bit32 Coord;
    } tr_meshtree;
 

/*
 * Animation structure.
 * This describes each individual animation; these may be looped by specifying
 * the next animation to be itself. In TR2 and TR3, one must be careful when
 * parsing frames using the FrameSize value as the size of each frame, since
 * an animation's frame range may extend into the next animation's frame range,
 * and that may have a different FrameSize value.
 */
typedef struct { // 32 bytes
    bitu32 FrameOffset; // byte offset into Frames[] (divide by 2 for Frames[i])
    bitu8 FrameRate;    // Engine ticks per frame
    bitu8 FrameSize; // number of bit16's in Frames[] used by this animation
    bitu16 StateID;
    bitu8 Unknown2[8];
    bitu16 FrameStart; // first frame in this animation
    bitu16 FrameEnd; // last frame in this animation (numframes = (End - Start) + 1)
    bitu16 NextAnimation;
    bitu16 NextFrame;
    bitu16 NumStateChanges;
    bitu16 StateChangeOffset; // offset into StateChanges[]
    bitu16 NumAnimCommands; // How many of them to use.
    bitu16 AnimCommand; // offset into AnimCommand[]
    } tr_animation ;

/*
 * State Change structure
 * Each one contains the state to change to and which animation dispatches
 * to use; there may be more than one, with each separate one covering a different
 * range of frames.
 */
typedef struct { // 6 bytes
    bitu16 StateID;
    bitu16 NumAnimDispatches; // number of ranges (seems to always be 1..5)
    bitu16 AnimDispatch; // Offset into AnimDispatches[]
    } tr_state_change ;

/*
 * Animation Dispatch structure
 * This specifies the next animation and frame to use; these are associated
 * with some range of frames. This makes possible such specificity as one
 * animation for left foot forward and another animation for right foot forward.
 */
typedef struct { // 8 bytes
    bit16 Low;                        // Lowest frame that uses this range
    bit16 High;                       // Highest frame (+1?) that uses this range
    bit16 NextAnimation;      // Animation to dispatch to
    bit16 NextFrame;            // Frame offset to dispatch to
    } tr_anim_dispatch ;

/*
 * AnimCommand structure
 * These are various commands associated with each animation; they are
 * called "Bone1" in some documentation. They are varying numbers of bit16's
 * packed into an array; the first of each set is the opcode, which determines
 * how operand bit16's follow it. Some of them refer to the whole animation
 * (jump and grab points, etc.), while others of them are associated with
 * specific frames (sound, bubbles, etc.).
 */
typedef struct { // 2 bytes
    bit16 Value;
    } tr_anim_command ;

Here are all the AnimCommand opcodes and their operands:
// 1: 3 operands. Position reference: (x,y,z); found in grab and block-move animations
// 2: 2 operands. Position reference on surface for jumping: (x,z) for horizontal and (y,z) for vertical surfaces(?)
// 3: No operands. Not clear; occurs in animations that are "slaved" to other animations, such as Lara throwing switches or moving blocks.
// 4: No operands. Not clear; occurs in some death and settling-down animations, but not all.
// 5: 2 operands. The first one is a frame number, and the second one is the ID of the sound to play at that frame (internal sound index).
In TR2 and TR3, one of the sound indices two highest bits may be set; when they are, their meanings are

0x4000 -- play this sound when on dry land (example: footsteps)
0x8000 -- play this sound when in water (example: running through shallow water)

// 6: 2 operands. The first one is a frame number, and the second one is some miscellaneous action.
//     0: Occurs in flipping-over animations; freeze camera at current position until end of animation?
//     3: Make bubble
//     12: Temporarily stop responding to controls?
//     etc.
14 and 15: Some kind of camera control?
18: ?
19: ?
20: Lara changing clothes (using a different Lara model)
21: ?
22: ?
23: Hide object
24: Show object
26: Some kind of camera control?
TR3 has additional ones, such as
-32736 = 0x8000 + 32
32
16416 = 0x4000 + 32

/*
 * Frame structure.
 *
 * Frames indicate how composite meshes are positioned and rotated. They work
 * in conjunction with Animations[] and MeshTree[]. A given frame has the following
 * format:
 * bit16 BB1x, BB1y, BB1z // bounding box (low)
 * bit16 BB2x, BB2y, BB2z // bounding box (high)
 * bit16 OffsetX, OffsetY, OffsetZ // starting offset for this moveable
 * (TR1 ONLY: bit16 NumValues // number of angle sets to follow; these start with the first mesh, and meshes without angles get zero angles.)
 * (TR2/3: NumValues is implicitly NumMeshes (from moveable))
 * What follows next is a list of angle sets. In TR2/3, an angle set can
 * specify either one or three axes of rotation. If either of the high two
 * bits (0xc000) of the first angle bitu16 are set, it's one axis: only one
 * bitu16, low 10 bits (0x03ff), scale is 0x100 ::= 90 degrees; the high two
 * bits are interpreted as follows: 0x4000 ::= X only, 0x8000 ::= Y only,
 * 0xC000 ::= Z only.
 * If neither of the high bits are set, it's a three-axis rotation. The next
 * 10 bits (0x3ff0) are the X rotation, the next 10 (including the following
 * bitu16) (0x000f, 0xfc00) are the Y rotation, the next 10 (0x03ff) are the
 * Z rotation, same scale as before (0x100 ::= 90 degrees).
 * Rotations are performed in Y, X, Z order.
 * TR1 ONLY: All angle sets are two words and interpreted like the two-word
 * sets in TR2/3, EXCEPT that the word order is reversed.
 */



 
 


VI. Non-Player Character Behaviour

Overview:
All the Tomb Raider game physics and entity behavior appears to be hardcoded, with each type ID being associated with some specific sort of behavior (as Lara, as a boat, as a tiger, as a door, as a boulder, as a lock, etc.). There is no sign of the sorts of schemes used by some other game engines for specifying this behavior in data files. One scheme is to use generic characters, generic projectiles, and so forth, and to specialize them by reading in appropriate records from data files. Another scheme is to use interpreted pseudocode; this is used by id's Quake. This hardcoding makes it difficult to port the earlier Tomb Raider scenarios to the engines of the later games, which could be desirable with their improved 3D-card and sound-card support. While textures, models, and animations can be ported, behavior cannot be.

However, there is a hint that TR3 may have some such information. Some of its characters are hostile in some levels, and not in others (the India-level monkeys, the Antarctica-level flamethrower wielders); there may be some flag in Items[] that determines whether a character is hostile or not. But the hostile and non-hostile versions of these characters may have separate type ID's.

Despite that lack, the Tomb Raider series does have navigation hints for the Non-Player Characters; those entities that move freely across the maps under the command of the game AI. One of the NPC's is the camera, since only Lara (and the vehicles she rides) is under the direct control of the player; the game AI makes the camera follow Lara. The camera uses the navigation hints used by the flying NPC's; these can be constructed so as to help the camera out of tight spots.

The navigation hints are three data structures: boxes, overlaps, and zones. Most sectors point to some box, the main exceptions being horizontal-portal sectors. Several neighbring sectors may point to the same box. A box is a horizontal rectangle, with corners and height specified; each box also has a pointer into the list of overlaps. Each segment in that list is the list of accessible neighboring boxes for some box; the NPC's apparently select from this list to decide where to go next. This selection is done with the help of the zones. These structures of 6 (TR1) or 10 (TR2, TR3) bit16 's that act as zone ID's; their overall indexing is the same as the boxes, meaning that each box will have an associated set of zone ID's. An NPC will select one of this set to use, and will prefer to go into the overlaps-list boxes that have the same zone value as the box it is currently in. For example, one can create guard paths by making chains of zone-ID-sharing boxes, with their overlaps pointing to the next boxes in those chains.

Data Structures:

Boxes:

typedef struct { // 8 bytes [TR1: 20 bytes] In TR1, the first four are bit32's instead of bitu8's, and are not scaled.
    bitu8 Zmin;     // sectors (* 1024 units)
    bitu8 Zmax;
    bitu8 Xmin;
    bitu8 Xmax;
    bit16 TrueFloor; // Y value (no scaling)
    bit16 OverlapIndex; // index into Overlaps[]. The high bit is sometimes set; this
                                  // occurs in front of swinging doors and the like.
    } tr_box ;

Overlaps:

This is a set of lists of neighboring boxes for each box, each member being a bitu16; the highest bit being set marks the end of each list. NPC's apparently use this list to decide where to go next.

Zones:

This is a set of bit16's, 6 for TR1 and 10 for TR2 and TR3. NPCs prefer to travel to a box with the same zone ID as the one they are currently at. Which of these zone ID's it uses depends on the kind of the NPC and its current state. The first half of the Zones structure is for the "normal" room state, and the second half is for the "alternate" room state. TR1, for example, has 2 sets of ground zones and 1 set of fly zones; its zones are

ground zone 1 (normal)
ground zone 2 (normal)
fly zone (normal)
ground zone 1 (alternate)
ground zone 2 (alternate)
fly zone (alternate)

The ground zones are for NPC's that travel on the ground, while the fly zones are for flying or swimming NPC's. TR2 and TR3 have similar breakdowns, though they have 4 ground zones.
 


VII. Sound

Overview:
The Tomb Raider series makes abundant use of sound, which appears in a variety of contexts. Sounds can be either continuous or triggered. Continuous ones can be for the whole level or produced by some sound-source object. The whole-level sound is a CD-track sound, which is played continuously, thus the blowing-wind sounds in the underground parts of "The Great Wall". Sound-source objects make sound in a range around some specific point. Likewise, triggered ones can be triggered by a variety of events. The triggering can be hardcoded in the engine (gunshots, switch pulls) or by reaching some animation frame (footsteps, Lara's somewhat unladylike sounds). Switch pulls and/or door sounds may be specified with operand of FDFunction 0x09; operand values lower than those used for assault-course clock control may specify which sounds to use.

Though CD-track sounds are referred to by track index, game-data sounds are referred to by an internal sound index; this is translated into which sound sample with the help of three layers of indexing, to allow for a suitable degree of abstraction. Internal sound indices for various sounds appear to be consistent across all the level files in a game; a gunshot or a passport opening in one level file will have the same internal sound index as in all the others. The highest level of these is the SoundMap[] array, which translates the internal sound index into an index into SoundDetails[]. Each SoundDetails record contains such details as the sound intensity, how many samples to select from, and an index into SampleIndices[]. This allows for selecting among multiple samples to produce variety; that index is the index to the SampleIndices[] value of first of these, with the rest of them being having the next indices in series of that array. Thus, if the number of samples is 4, then the TR engine looks in SampleIndices[] locations Index, Index+1, Index+2, and Index+3. Finally, the SampleIndices[] array references some arrays of sound samples. In TR1, these samples are embedded in the level files, and SampleIndices[] contains the displacements of each one in bytes from the beginning of that embedded block. In TR2 and TR3, these samples are concatenated in the file "MAIN.SFX" with no additional information; SampleIndices[] contains sequence numbers (0, 1, 2, 3, ...) in MAIN.SFX. Finally , the samples themselves are all in Microsoft WAVE format.

The CD-audio tracks are stored in different fashions in the various versions of the TR series. In the PC version of TR3, they are all stored in the file CDAUDIO.WAD, which has the format (source: Sven, BachmannS@gmx.net, http://wotsit.org/cgi-bin/download.cgi?tr3audio): a series of header records with this format:

{ // 0x108 bytes
        bit32 SampleLength;     // how many bytes
        bit32 SampleOffset;     // offset in file
        bit8 Name[256];         // C string; the length is a guess, because Sven's sizes are inconsistent.
};
followed by embedded samples in the Microsoft WAVE format.

In the Macintosh versions of TR1 and TR2, the CD audio tracks are separate files in AIFF format, while in the Macintosh version of TR3, these tracks are separate files in Microsoft WAVE format. The Macintosh version of TR3 contains an additional file, CDAudio.db, which contains the names of all the track files as 32-byte zero-padded C strings with no extra contents.

Data Structures:

/*
 * SoundSource structure
 * This structure contains the details of continuous-sound sources. Although
 * a SoundSource object has a position, it has no room membership; the sound
 * seems to propagate omnidirectionally for about 10 horizontal-grid sizes
 * without regard for the presence of walls.
 */
typedef struct {
    bit32 x;     // absolute X position of sound source (world coordinates)
    bit32 y;     // absolute Y position of sound source (world coordinates)
    bit32 z;     // absolute Z position of sound source (world coordinates)
    bitu16 SoundID; // internal sound index
    bitu16 Flags; // 0x40, 0x80, or 0xc0
    } tr_sound_source ;

SoundMap is for mapping from internal-sound index to SoundDetails index; it is 370 bit16s in TR2 and TR3 and 256 bit16s in TR1 . A value of -1 indicates "none".

/*
 * Sound-sample details (SoundDetails)
 */
typedef struct { // 8 bytes
    bit16 Sample; // (index into SampleIndices)
    bit16 Volume;
    bit16 Unknown1; // sound range? (distance at which this sound can be heard?)
    bit16 Unknown2; // Bits 8-15: priority?, Bits 2-7: number of sound
                           // samples in this group, Bits 0-1: channel number?
    } tr_sound_details ;

SampleIndices: In TR1, this is a list of indices into the embedded sound-samples object, which precedes this object in the level file. In TR2 and TR3, this is a list of indices into the file "MAIN.SFX"; the indices are the index numbers of that file's embedded sound samples, rather than the samples' starting locations. That file itself is a set of concatenated soundfiles with no catalogue info present. In all the TR series, the sound format used is Microsoft WAVE (.wav).
 


VIII. Miscellany

These are various odds and ends that do not fit into the earlier categories.

Version: Every level file (.PHD, .TUB, .TR2) begins with a bitu32 version number.  This seems to be used by the engine to guarantee compatibility between various level editor versions and the game engine version.  More generally, it can be used to determine what sort of level is being read.  Here are the known (observed) values for the version header:

        0x00000020    Tomb Raider 1, Gold, Unfinished Business
        0x0000002d    Tomb Raider 2
        0xFF080038    Tomb Raider 3
        0xFF180038    Tomb Raider 3

Palette: This consists of 256 tr_colour structs, one for each palette entry. However, the individual colour values range from 0 to 63; they must be multiplied by 4 to get the correct values.

This used for all 8-bit colour, such as 8-bit textures.

Object Textures:

/*
 * Object-texture vertex structure. It specifies a vertex location in textile coordinates.
 * The Xpixel and Ypixel are the actual coordinates of the vertex's pixel.
 * The Xcoordinate and Ycoordinate values depend on where the other vertices
 * are in the object texture. And if the object texture is used to specify
 * a triangle, then the fourth vertex's values will all be zero.
 */
typedef struct { // 4 bytes
    bitu8 Xcoordinate; // 1 if Xpixel is the low value, 255 if Xpixel is the high value in the object texture
    bitu8 Xpixel;
    bitu8 Ycoordinate; // 1 if Ypixel is the low value, 255 if Ypixel is the high value in the object texture
    bitu8 Ypixel;
    } tr_object_texture_vert ;

/*
 * Object texture structure.
 * These, thee contents of ObjectTextures[], are used for specifying texture
 * mapping for the world geometry and for mesh objects.
 */
typedef struct { // 20 bytes
    bitu16 Attribute;  // 0 means that a texture is all-opaque, and that transparency
                                 // information is ignored.
                                // 1 means that transparency information is used. In 8-bit colour,
                                // index 0 is the transparent colour, while in 16-bit colour, the
                                // top bit (0x8000) is the alpha channel (1 = opaque, 0 = transparent).
                                // 2 (only in TR3) means that the opacity (alpha) is equal to the intensity;
                                // the brighter the colour, the more opaque it is. The intensity is probably calculated
                                // as the maximum of the individual color values.

    bitu16 Tile; // index into textile list
    tr_object_texture_vert Vertices[4]; // the four corners of the texture
    } tr_object_texture ;

Animated Textures:

Animated textures describe sets of object textures that are cycled through to produce texture animations; they are a set of bit16's with the following format (not a "real" C/C++ structure):

bit16 NumAnimatedTextures
struct {
    bit16 NumTextureIDs; // Actually, this is the number of texture ID's - 1.
    bit16 TextureIDs[NumTextureIDs + 1]; // offsets into ObjectTextures[], in animation order.
    } AnimatedTextures[NumAnimatedTextures];

If a texture belongs to an animated-texture group, it will automatically be animated by the engine. The animation framerate is most likely hardcoded.
 

Cameras:
These are positions to switch the camera to; the camera gets switched to one of these as specified in the floordata, which also specify what to look at, how long to switch, and whether to do so only once.

typedef struct {
    bit32 x;
    bit32 y;
    bit32 z;
    bit16 Room;
    bitu16 Unknown1; // correlates to Boxes[]? Zones[]?
    } tr_camera;
 
 

Cinematic Frames:
These are camera positionings for cutscenes. All the entity animations are specified separately, and it is not clear where there is any syncing between these frames and any of the animations.

typedef struct {
    bit16 rotY;   // rotation about Y axis, +/- 32767 == +/- 180 degrees
    bit16 rotZ;    // rotation about Z axis, +/- 32767 == +/- 180 degrees
    bit16 rotZ2;  // seems to work a lot like rotZ;  I haven't yet been able to
                          // differentiate them
    bit16 posZ;   // camera position relative to something (target? Lara? room
                          // origin?).  pos* are _not_ in world coordinates.
    bit16 posY;   // camera position relative to something (see posZ)
    bit16 posX;   // camera position relative to something (see posZ)
    bit16 unknown; // changing this can cause a runtime error
    bit16 rotX;   // rotation about X axis, +/- 32767 == +/- 180 degrees
    } tr_cinematic_frame;
 

LightMap:
A 32*256 array of bitu8 's which is apparently for applying light to 8-bit colour, in some documentation called "ColourMap". The current palette index and lighting value are used to calcuate an index to this table, which is a table of palette indices.

The Tomb Raider series' software rendering, like that of most real-time-3D games, uses 8-bit colour for speed and low bulk; however, there is the serious problem of how to do lighting with 8-bit colour, because doing it directly is computationally expensive. The usual solution is to arrange the palettes' colours in ramps, which the engine then follows in the appropriate directions. However, the TR series' palettes generally lack such neat ramps.

But the TR series has a more general solution, one that does not require palettes to have colour ramps. It uses precalculated lighting tables, the "ColourMap" objects. These contain translations of a colour value and a lighting value, listed by palette index. The translation goes as follows:

n = ColourMap[256 * k + i];

where i is the original palette index, k is determined from the lighting value, and n is the new palette index. The lighting index k varies from 0 to 31, and the corresponding lighting value is, for TR1,

2 - k / 16

and for TR2 and TR3,

2 - (k + 1) / 16

This may be associated with the curious fact of the lighting values in the data files increasing in the "wrong" direction in TR1 and TR2, with 0 being full brightness and greater values being darker.
 


ChangeLog

V1.00 (changes from the TRosetta Stone doc)