This version (2018/11/03 21:15) was approved by zdimension.The Previously approved version (2018/11/03 21:11) is available.Diff

TRosettaStone 3

Document Version 3.0 preview

Including Tomb Raider .PHD/.TUB, Tomb Raider II-III .TR2, Tomb Raider IV .TR4 and Tomb Raider Chronicles (V) .TRC information, where available.

Also includes TOMBPC.DAT and SCRIPT.TR4 script information, CDAUDIO.WAD and CUTSEQ.PAK / CUTSEQ.BIN information.
A one-page version (every page is displayed one after the other, allows using browser Ctrl+F) of TRS3 is available here.

Introduction

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.

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
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 (winroomedit.exe) version .49, 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.

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.

Current Unknowns

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


trs.txt · Last modified: 2018/11/03 21:13 (external edit)
Back to top
CC Attribution-Share Alike 4.0 International
Driven by DokuWiki Recent changes RSS feed Valid CSS Valid XHTML 1.0