README.md
1[](https://travis-ci.org/opentomb/OpenTomb)
2
3OpenTomb — an open-source Tomb Raider 1-5 engine remake
4-------------------------------------------------------
5
6### Table of contents ###
7
8- [What is this?](#what-is-this)
9- [Why create a new engine?](#why-create-a-new-engine)
10- [Features](#features)
11- [Supported platforms](#supported-platforms)
12- [Setup](#setup)
13- [Compiling](#compiling)
14- [Running and Configuration](#running-and-configuration)
15- [Licensing](#licensing)
16- [Credits](#credits)
17
18
19### What is this? ###
20OpenTomb is an open-source re-implementation of the classic Tomb Raider engine,
21intended to play levels from all classic-era Tomb Raider games (1—5), as well as
22custom TRLE levels. The project does not use any of the original Tomb Raider
23code, as all attempts to retrieve source files from Eidos/Core were in vain.
24
25Instead, everything is being re-developed completely from scratch. It should be
26noted, however, that OpenTomb uses certain legacy routines from unfinished
27open-source projects, such as [OpenRaider](http://openraider.sourceforge.net/)
28and VT project (found at [icculus.org](https://icculus.org/)), plus some code
29from Quake Tenebrae.
30
31OpenTomb tries to recreate the original Tomb Raider series experience, although
32with contemporary updates, features and additions, being able to fully benefit
33from running on modern PCs with powerful CPUs and graphic cards.
34
35Links to forums and info:
36* TR forum link: http://www.tombraiderforums.com/showthread.php?t=197508
37* Discord channel: https://discord.gg/d8mQgdc
38
39### Why create a new engine? ###
40It's true that we have fully working Windows builds of TR2-5, and TR1 works
41perfectly through [DosBox](https://www.dosbox.com/). However, as time
42progresses the situation will only worsen, with newer Operating Systems
43becoming increasingly unlikely to support the games. OpenTomb will always
44be able to be ported to any platform you wish.
45
46It is also true that there are patchers for the original engine, aiming to
47improve and update it: TREP, TRNG, etc. The advantage with OpenTomb is that we
48are not limited by the original Binary, a huge limitation when it comes to new
49features, graphical enhancements, code modification and more. An open-source
50engine removes these limitations.
51
52### Features ###
53* OpenTomb has a completely different collision approach to the original engine,
54circumventing many of the limitations present. We use a terrain generator to
55make an optimized collision mesh for each room from so-called "floordata".
56* OpenTomb is capable of a variable frame rate, not limited to 30fps like the
57original engine.
58* OpenTomb uses common and flexible libraries, such as OpenGL, OpenAL, SDL and
59Bullet Physics.
60* OpenTomb implements a Lua scripting engine to define all entity functionality.
61 This means that, again, unlike the original, much less is hardcoded into the
62 engine itself, so functionality can be extended or modified without havng to
63 modify and recompile the engine itself.
64* Many abandoned and unused features from the original engine have been enabled
65in OpenTomb. New animation, unused items, hidden PSX-specific structures inside
66level files, and so on!
67
68### Supported platforms ###
69OpenTomb is a cross-platform engine: currently it can be ran on Windows, Mac or
70Linux. No mobile implementations are in development yet, but they are indeed
71possible.
72
73### Setup ###
74To run any of the levels from the original games, you will need the assets from
75that respective game. These resources often tend to be in cryptic formats, with
76variations across games. Because of this, you'll need to convert some game
77resources to usable formats yourself, or get them from somewhere on the Net.
78
79Here is the list of all needed assets and where to get them:
80
81 * Data folders from each game. Get them from your retail game CDs or Steam/GOG
82 bundles. Just take data folder from each game's folder, and put it into
83 corresponding `/data/tr*/` folder. For instance, for TR3, the path would be
84 `OpenTomb/data/tr3/data/`
85
86 * CD audio tracks. OpenTomb only supports OGG audiotracks for a moment, so you
87 should convert original soundtracks by yourself, or just download whole TR1-5
88 music package here: https://opentomb.earvillage.net
89 PLEASE NOTE: Files may need to be renamed for this to work, please see
90 https://github.com/opentomb/OpenTomb/issues/447
91
92 * Loading screens for TR1-3 and TR5. For TR3, get them from pix directory of
93 your installed official game. Just put this pix directory into `/data/tr3/`
94 folder. As for other games, it's a bit tricky to get loading screens, as there
95 were no loading screens for PC versions TR1-2, TR4 used level screenshots as
96 loading screens, and TR5 used an encrypted format to store all loading
97 graphics. So, to ease your life, you can simply download loading screen package
98 here: http://trep.trlevel.de/temp/loading_screens.zip
99 Just put it right into OpenTomb directory, and that should do the trick. Note:
100 the engine supports png and pcx format of screen images.
101
102### Compiling ###
103There is a CMakeLists.txt file provided with source code, so you can compile
104OpenTomb using CMake. On Windows, you can also compile it from Code::Blocks IDE
105(project file is also provided). Alternatively, you can manually compile it in
106Code::Blocks by recursively adding all source files from /src directory, and
107adding these libraries in Linker Settings under Project Build options:
108
109* libmingw32.a
110* libSDL2main.a
111* libSDL2.dll.a
112* liblua.a
113* libpng.a
114* libz.a
115* libpthread.a
116
117On Linux, just download the source code and run in terminal:
118
119 cmake . && make
120
121The required dependencies are the development headers for SDL2, png, LUA 5.2,
122ZLIB. You can install them in an Ubuntu-based distro with this command:
123
124 sudo apt-get install libopenal-dev libsdl2-dev libpng12-dev liblua5.2-dev libglu1-mesa-dev zlib1g-dev
125
126On Mac, use XCode project, which is also available in source code.
127
128NB: Please note that OpenTomb requires C++11 (`-std=c++11`) flag to compile
129properly! You may use CPU-specific optimization flags (`-march=prescott`,
130`-march=i486`, `-march=core2`), as well as general optimization flags (`-O1` and `-O2`),
131 but DON'T USE `-O3` flag, as Bullet tends to crash with this optimization level
132 (GCC 5.1+ may compile it without errors).
133
134### Running and Configuration ###
135To run OpenTomb, simply run the executable generated by the build. By default,
136no command line options are needed. Access the console by pressing \`. This
137allows you to enter commands to select levels, change settings, and more. Enter
138'help' to get a list of commands. Enter 'exit' to quit the engine.
139
140Currently, all settings in OpenTomb are managed through config.lua and
141autoexec.lua. Config.lua contains persistent engine and game settings, while
142autoexec.lua contains any commands which should be executed on engine start-up.
143
144Config.lua is divided into different sections: screen, audio, render, controls,
145console and system. In each of these sections, you can change numerous
146parameters, the names of which are usually fairly intuitive.
147
148Autoexec.lua is a simple list of commands which are ran at startup. Modifying
149existing commands may cause the engine to function incorrectly.
150
151To select a level, enter 'setgamef(game, level) into either autoexec.lua or in
152the console, where game is 1-5. Mansion levels are generally 0, and games which
153do not have a mansion begin from level 1. For example, to load level 2 of TR3,
154you would enter `setgamef(3, 2)`.
155
156### Licensing ###
157OpenTomb is an open-source engine distributed under LGPLv3 license, which means
158that ANY part of the source code must be open-source as well. Hence, all used
159libraries and bundled resources must be open-source with GPL-compatible
160licenses. Here is the list of used libraries and resources and their licenses:
161
162* OpenGL — does not need licensing (https://www.opengl.org/about/#11)
163* OpenAL Soft — LGPL
164* SDL / SDL Image — zlib
165* Bullet — zlib
166* Freetype2 — GPL
167* Lua — MIT
168* ffmpeg rpl format and codecs (http://git.videolan.org/)
169
170* Droid Sans Mono, Roboto Condensed Regular and Roboto Regular fonts — Apache
171
172### Credits ###
173NB: Please note that authors and contributors list is constantly extending, as
174there is more and more people involved in project development, so someone may be
175 missing from this list!
176
177* [TeslaRus](https://github.com/TeslaRus): main developer.
178* [Cochrane](https://github.com/Cochrane): renderer rewrites and optimizing, Mac OS X support.
179* [Gh0stBlade](https://github.com/Gh0stBlade): renderer add-ons, shader port, gameflow implementation, state
180control fix-ups, camera and AI programming.
181* [Lwmte](https://github.com/Lwmte): state and scripting fix-ups, controls, GUI and audio modules, trigger
182and entity system rewrites.
183* Nickotte: interface programming, ring inventory implementation,
184camera fix-ups.
185* [pmatulka](https://github.com/pmatulka): Linux port and testing.
186* [richardba](https://github.com/richardba): Github migration, Github repo maintenance, website design.
187* [Saracen](https://github.com/Saracen): room and static mesh lighting.
188* [T4Larson](https://github.com/T4Larson): general stability patches and bugfixing.
189* [vobject](https://github.com/vobject): nightly builds, maintaining general compiler compatibility.
190* [vvs-](https://github.com/vvs-): testing, feedback, bug report.
191* [xproger](https://github.com/xproger): documentation updates.
192* [Banderi](https://github.com/Banderi): documentation, bugfixing.
193* [gabrielmtzcarrillo](https://github.com/gabrielmtzcarrillo): entity shader work.
194* [filfreire](https://github.com/filfreire): documentation.
195
196
197Additional contributions from: Ado Croft (extensive testing),
198E. Popov (TRN caustics shader port), [godmodder](https://github.com/godmodder) (general help),
199[jack9267](https://github.com/jack9267) (vt loader optimization), meta2tr (testing and bugtracking),
200shabtronic (renderer fix-ups), [Tonttu](https://github.com/Tonttu) (console patch) and
201[xythobuz](https://github.com/xythobuz) (additional Mac compatibility patches).
202
203Translations by: [Joey79100](https://github.com/Joey79100) (French), Nickotte (Italian), [Lwmte](https://github.com/Lwmte) (Russian),
204[SuiKaze Raider](https://twitter.com/suikazeraider) (Spanish), [filfreire](https://github.com/filfreire) (Portuguese - Portugal).
205
){kind=link}