Project documentation is lacking and should be elaborated upon

[LambdaCalculus37]

While I have been able to get around some of the project and managed to compile and run a nix build after some trial and error, I should point out that this project needs some better documentation overall.

Specifically, the following areas need to be better documented:

• Compiling and required libraries. What libraries and tools are needed that are agnostic to all platforms, and what platform-specific libraries and tools are needed?
• Setting up and running OpenLara. I found out, after several hours of trial and error, that, at least in the case for the DOS version's data files, that case sensitivity will affect the *nix and macOS builds, both of which do have case sensitivity in their filesystems. In my case, running the game on nix kept giving me the error that data/1/TITLE was not found, and then followed up with data/1/LEVEL; i.e. I had to rename all of the data files to be in ALL CAPS so OpenLara would properly read them, and this wasn't mentioned anywhere that case sensitivity might affect certain OSes and that it should be considered.
• (related to above) I have seen demos where the FMVs from the game do play correctly, but even though I have the FMV files in data/1/FMV, they don't play during the game. This is not documented anywhere as to where they should be located.
• Some of the README files that are included with some of the ports mention that the data for the PS1 and Sega Saturn versions can also be used with OpenLara, but as above, there is next to no documentation written on how to extract the needed data from the discs, and how to lay it out so that OpenLara can make use of it. I originally tried going this route, but gave up because it was near impossible to figure out just how to put all the data together for OpenLara to use it.

While this is a great project with tons of promise, terrible documentation can and will turn people off from wanting to use it. I would be willing to help write documentation to help users out, but in order to be able to do that, I would need to know how everything works so that info can be shared with others.

[BielBdeLuna]

on the videos: the video RPL files go into folder "/videos/1/" 1 being Tomb raider 1

[abelsromero]

Context and legal should be included. The Readme states "Classic Tomb Raider open-source engine" but that's not true. The web demo and releases include playable versions with asset included. That to my understanding is not alowed for copyright reasons, and other OS game engine implementations make sure to not include assets or link to them in any way.

[BielBdeLuna]

maybe the old 90's demo could be included as a separate download in order to have assets to see it ( it was the Vilcabamba level ) the Vilcabamba level is I think the best example of the TR gameplay variety as it has keys / water / blocks to move / levers / traps / false floors / enemies of different kinds

[abelsromero]

maybe the old 90's demo could be included as a separate download in order to have assets to see it ( it was the Vilcabamba level )

The problem is that afaik the project cannot provide any link other than to official stores and a mention like "You need a legal copy of the original files/demo/etc." To be clear I am not refering to the legal use licence you get when purchasing the game, but the copyrighted materials (music/textures etc.). That additional copyright is there to prevent derivative work, unless Tomb Rider has some special licence which I doubt because that would mean anyone could make a Lara spin off.

Even if the files are not in the repo, but providing binaries and linking a demo (even if not afiliated with the project) can justify a takedown from the legal owners and the repo owners cannot fight it.

[LambdaCalculus37]

The web demo and releases include playable versions with asset included. That to my understanding is not alowed for copyright reasons, and other OS game engine implementations make sure to not include assets or link to them in any way.

I'm not asking for the assets to be included. I'm asking for documentation on what to do with the assets of each version once they're extracted, and also, in the case of the PS1 version, how to extract them.

This is a word-for-word quote out of the README that's included with the nix binary:

STEP 1: Create empty folder "[your_folder]" and for original PC, PSX and Sega Saturn CD version owners copy data from your CD into folder

This is way too vague for anyone to figure out. Here would be a better example of showing how to lay out the needed folders:

Once you have created a folder for the OpenLara executable, create three additional folders within it: 'audio', 'level', and 'video'. In each, create a folder titled '1' (or '2' for Tomb Raider II, and so on).

And then, for copying the assets:

All CD Audio tracks can be ripped and placed into the respective audio/ subfolder (1/ for Tomb Raider, etc.). Be sure to name the tracks as 'track0xx.ogg' (xx is the track number; e.g. track002.ogg) for OpenLara to read them.

If you are using the DOS version's assets, copy all files from the DATA folder of the Tomb Raider CD to level/1. macOS and Linux users should be aware that case sensitivity is used, and all files may need to be renamed to use ALL CAPS (e.g. TITLE.PCX, for example). Then copy all files from the FMV folder of the TR CD into video/1 and rename similarly if on Linux or macOS.

If you are using the PS1 or Sega Saturn version's assets, instructions go here

In the PS1's case, there was mention of using jPSXdec to extract the data from the PS1 version, but zero mention of how. jPSXdec gives two options: normal 2048/bytes extraction, or raw 2352/bytes extraction. There's zero mention of what method to use. Ditto the Saturn version; do you just drag and drop the files out and lay them out how they're supposed to go, or do you need a special extraction tool for the Saturn as well?

That's what I'm talking about. Not "supply me with the assets"; it's "I have the assets here, but now what do I do with them?"

[BielBdeLuna]

you can do a PR yourself too, even from github

[Richard-L]

I agree on not including copyrighted asset files.

The TR1 demos are super easy to find and can be linked to. They will have the first two levels to try OpenLara. Further TRUB files can be included as they were made freeware.

[krux02]

I would like to comment here to say that I totally agree. The documentation needs to be improved. I have the gog version I could extract all files I need to play the game, but still I have no music and no title screen. I don't know how to fix this and I would really like to get to know to to address these. even putting the assets was a guessing game for me. I even installed discord enered the channel in the hopes that the documentation might be hidden behind the discord wall, but no, I wasn't very helpful either.

[XProger]

@krux02 PC version of og game doesn't have loading screens and music, you should use PSX instead, discord has pinned messages...

[LambdaCalculus37]

Created Pull Request #414 to begin a documentation folder. The first entry is asset layout for OpenLara (where all files should go).