Until now the Tomb Raider community, especially programmers and resource hacking enthusiasts, referenced a document called TRosettaStone (based on vt's documentation), which hadn’t been updated since 1999, and its revised version (we can call it TRosettaStone 2), which was done by E. Popov in 2000 or 2001. Both of these documents served well for their time, but they were plagued by many errors and inaccuracies.

Many people noted these errors and inaccuracies, but nobody of them revised existing documentation, keeping all their knowledge just in their head. It is widely known that original document lacks some info here and there, and something is wrongly described — but it’s not mentioned anywhere (except some lost forum posts). So when a newbie programmer comes to community, he has to come through all the same trials and errors as everyone else once came.

“It shouldn’t happen like that.”

The purpose of TRosettaStone 3 is to replace original document and serve as the comprehensive source of information for anyone willing to participate in classic-era Tomb Raider software development. We will use original TRosettaStone as a basis, heavily borrowing from E. Popov revision. Also, this document will widely borrow information from TREP user’s manual, NGLE manual, and a bunch of forum threads and messages concerning internal game engine structures.

However, while original TRosettaStone and update by Popov were aimed primarily at exploring already existing game assets, such as levels, sound files, scripts, etc., this document is being created by and as a reference for programmers who are creating open-source reimplementations of original game engines. Because of this, we will sometimes explore not only game file formats, but also internal game logic, procedures and other related aspects. It will be updated synchronously with development of OpenTomb, one of such reimplementation projects, which has received lots of feedback from the community.

This document contains detailed descriptions of the classic-era Tomb Raider 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. This document is self-contained; all hyperlinks refer only to itself.

All information in this document was derived independently, without the aid or assistance of anyone at Core Design or Eidos. As such, the information in this document may contain errors or omissions, and many structure and variable names were deduced from the interpretation of the data (and therefore could be misleading or completely wrong). However, we re-use certain variable and function names from original Tomb Raider debug builds and mappings/symbols from the leaked Tomb Raider Chronicles PSX SDK.

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 is a spare-time project that set out to document the Tomb Raider file formats.

Generally, game versions are referenced by abbreviations:

• TR1 refers to Tomb Raider and Tomb Raider: Unfinished Business
• TR2 refers to Tomb Raider II and Tomb Raider II: The Golden Mask
• TR3 refers to Tomb Raider III and Tomb Raider III: The Lost Artifact
• TR4 refers to Tomb Raider: The Last Revelation
• TR5 refers to Tomb Raider: Chronicles

When we provide some version-specific info about certain structures or methods, this information will be marked with special bullet images, defining engine versions for which this info is applicable: is for TR1, is for TR2, is for TR3, is for TR4, and is for TR5. Version-specific information will continue up to the next paragraph or list entry, until otherwise noted.

Also, if external programs and utilities are involved, here are abbreviations for them:

• TRLE refers to Tomb Raider Level Editor — an official tool by Core Design used to build levels.
• NGLE refers to TRLE version which was unofficially patched and now extensively used by level editing community.
• Dxtre3d refers to so-called unofficial level editor developed by Felix aka Turbo Pascal.
• TREP refers to a binary patcher which is used to patch TR4 engine in its Level Editor version (bundled with TR5) for some advanced features and upgrades by level editing community.
• TRNG is another patcher with same purpose as TREP, however, incompatible with it. TRNG offers even more advanced features and upgrades to old TR4 engine.
• FLEP refers to a similar patcher as TREP, which is used for same TR4 engine, albeit previously modified by TRNG.

1. Room light structure from TR4 needs additional description.
2. Same for TR5 room light structure.
3. Exact description of what is exactly “room layer” in TR5.
4. Clarify the meaning of Bit 4 in [tr2_room_vertex] structure.
5. Clarify what’s the purpose of Normal field in [tr5_room_vertex] structure, and if really Attributes field was removed.
6. Whole [tr5_room] structure needs detailed analysis with all its extra Unknown fields.
7. Clarify fog bulb values which affect its radius.
8. What’s the purpose of bits 0-2 (mapping correction) in flags field in [tr4_object_texture] structure?
9. Clarify the CUTSEQ.bin packed coordinates structure format.

Tomb Raider, Tomb Raider Gold, Unfinished Business, Tomb Raider II, Tomb Raider III, Tomb Raider: The Last Revelation, Tomb Raider Chronicles, Lara Croft, and all images and data within the data files and game engine are Copyright © Square Enix.

The Fundamentals

Room Geometry

FloorData

Meshes and Models

Mesh Construction and Animation

Non-Player Character Behaviour

Music and Sound

Miscellany

Level File Formats

Scripting in TR2/TR3 for PC/PSX

Scripting in TR4 and TR5

PAK file format (TR4-TR5)

CUTSEQ file format (TR4-TR5)

Catalogues