====== TRosettaStone 3 ======

|**Document Version 3.0 preview** \\   \\ Including Tomb Raider ''<nowiki>.PHD/.TUB</nowiki>'', Tomb Raider II-III ''<nowiki>.TR2</nowiki>'', Tomb Raider IV ''<nowiki>.TR4</nowiki>'' and Tomb Raider Chronicles (V) ''<nowiki>.TRC</nowiki>'' information, where available. \\  \\ Also includes ''<nowiki>TOMBPC.DAT</nowiki>'' and ''<nowiki>SCRIPT.TR4</nowiki>'' script information, ''<nowiki>CDAUDIO.WAD</nowiki>'' and ''<nowiki>CUTSEQ.PAK</nowiki>'' / ''<nowiki>CUTSEQ.BIN</nowiki>'' information.|{{:logo:trosej-mid.png?nolink&}}|

<note tip>
**A one-page version (every page is displayed one after the other, allows using browser Ctrl+F) of TRS3 is available [[trsone|here]].**
</note>

====== Introduction ======

Until now the Tomb Raider community, especially programmers and resource hacking enthusiasts, referenced [[http://www.tnlc.com/eep/tr/TRosettaStone.html|a document called TRosettaStone]] (based on [[https://icculus.org/vt/vt/doc/Tomb%20Raider%20II%20Data%20Formats.htm|vt's documentation]]), which hadn’t been updated since 1999, and [[http://www.evpopov.com/perso/dl/TRStone/TRLevelFileFormat.html|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.
===== Description =====

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.

===== Conventions =====

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

<note tip>
As level formats are concerned, **TR4**  usually applies not only to original game, but to //custom levels//  built by fans using //Tomb Raider Level Editor//  (''<nowiki>winroomedit.exe</nowiki>'') version ''<nowiki>.49</nowiki>'', used to work with TR4-specific level file format. This level editor version is the only one level editor officially released by Eidos / Core, along with TR5.
</note>

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: {{:icons:tr1.png?nolink&}} is for TR1, {{:icons:tr2.png?nolink&}} is for TR2, {{:icons:tr3.png?nolink&}} is for TR3, {{:icons:tr4.png?nolink&}} is for TR4, and {{:icons:tr5.png?nolink&}} 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//.
  * **TE** refers to new advanced level editor called //Tomb Editor//, developed by joint efforts of TRLE community with //MontyTRC// as lead programmer.
  * **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//.
===== Current Unknowns =====

  - Clarify what’s the purpose of ''<nowiki>Normal</nowiki>''  field in [[trs:room_geometry#tr5_room_vertex|[tr5_room_vertex]]] structure, and if really ''<nowiki>Attributes</nowiki>''  field was removed.
  - Whole [[trs:room_geometry#tr5_room|[tr5_room]]] structure needs detailed analysis with all its extra //Unknown//  fields.
  - Clarify fog bulb values which affect its radius.
  - Clarify the CUTSEQ.bin packed coordinates structure format.

===== Copyright note =====

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.

[[trs:fundamentals|The Fundamentals]]

[[trs:room_geometry|Room Geometry]]

[[trs:floordata|FloorData]]

[[trs:meshes_models|Meshes and Models]]

[[trs:mesh_construction_animation|Mesh Construction and Animation]]

[[trs:npc_behaviour|Non-Player Character Behaviour]]

[[trs:sound|Music and Sound]]

[[trs:miscellany|Miscellany]]

[[trs:file_formats|Level File Formats]]

[[trs:scripting_tr2_tr3|Scripting in TR2/TR3 for PC/PSX]]

[[trs:scripting_tr4_tr5|Scripting in TR4 and TR5]]

[[trs:pak|PAK file format (TR4-TR5)]]

[[trs:cutseq|CUTSEQ file format (TR4-TR5)]]

[[catalogues:catalogues|Catalogues]]

\\