OpenRayman/README.md

# OpenRayman


An open source reimplementation of the Rayman 2: The Great Escape engine using C++11 and modern OpenGL.


## Usage


`openrayman [options] ...`  


OpenRayman needs the base game `rayman2` to run.


`rayman2` can be created by starting OpenRayman without it or by using the command line option `--convert-data "folder"`. The `folder` variable should point to a valid Rayman 2: The Great Escape installation.


`rayman2` will be copied into the OpenRayman storage folder (in windows `%appdata%\openrayman` or linux `~/.local/share/openrayman`). This is all that needs to be done to run OpenRayman.


Do note that OpenRayman contains some extensions to the Rayman 2: The Great Escape game, such as more menu options.


If for some reason you wish to run without these modifications then you will either need to edit the `config.json` file and change the `game` variable from `rayman2_openrayman` to `rayman2`, or by specifying the game to run via the command line option `--game rayman2`.


You should always target `rayman2_openrayman` when making a mod.


## Obtaining "Rayman 2: The Great Escape"


As previously mentioned, a valid installation of Rayman 2: The Great Escape (PC version) must be used for data extraction.


Rayman 2: The Great Escape can be bought on GOG (https://www.gog.com/game/rayman_2_the_great_escape) or installed from a valid CD.


Installing the game on Linux needs to be done via `wine` but should work without further tweaking.


(TODO: installing on Android)


The only tested version is the GOG version.


## GL3W


You need to build gl3w.h and gl3w.c before you build the project.


This can be done by executing lib/gl3w/gl3w_gen.py with Python 2.


## Building on Linux


CMake should be used to generate makefiles, and `make` should be used to build the engine.


```
mkdir build
cd build
cmake ..
make -j8
```

The engine can be installed via `sudo make install` and can then be started by executing the command `openrayman`.


Additionally, a .desktop file will be created.


## Building on Windows


Building should be done with MinGW, and is almost the same as on Linux.


You need to use the command `cmake -G "MinGW Makefiles" ..` instead of `cmake ..` to create makefiles, as OpenRayman cannot be built with MSVC.


You might also need `mingw32-make -j8` instead of `make -j8`.


## Building on Mac OS X


Mac OS X is not supported at the moment (might work with CMake?).


## Licensing


All files in this repository are licensed under GPLv3, except for files that are a part of libopenrayman.


## libopenrayman


libopenrayman is a library that contains several classes for decoding and decompiling file formats used by the Rayman 2: The Great Escape engine.


libopenrayman is at large based upon szymski's Rayman2Lib (https://github.com/szymski/Rayman2Lib).


All files related to libopenrayman are located in the libopenrayman/ subdirectory.


## Special thanks to


https://github.com/szymski/Rayman2Lib


All others who have taken part of the UnLockRay project (https://www.reddit.com/r/UnLockRay/) and helped reverse engineer the Rayman 2: The Great Escape engine.


Palorifgrodbierzrt for creating Ray2Get, which the `apm_audio_track` implementation is partially based upon (I figured out the `WAVEFORMATEX` part though ;)).
Initial commit 2016-06-10 20:35:24 -04:00			`# OpenRayman`


			`An open source reimplementation of the Rayman 2: The Great Escape engine using C++11 and modern OpenGL.`


Add glfw as submodule 2016-06-11 12:22:42 -04:00			`## Usage`
Initial commit 2016-06-10 20:35:24 -04:00

Add rough TODO, for now 2016-06-10 21:20:54 -04:00			`openrayman [options] ...`
Some initial boilerplate 2016-06-10 21:12:15 -04:00
Initial commit 2016-06-10 20:35:24 -04:00
Add a game class for mod support This commit adds a game class, which is a collection of files that can depend on other files. The base game "rayman2" contains all files required for the game, and they can then be overriden by games that depend on it. OpenRayman will use this for editing menus (adding settings) and possibly other things. All mods should target "rayman2_openrayman". 2016-06-14 21:55:52 -04:00			OpenRayman needs the base game `rayman2` to run.


Mostly complete audio decoding * OpenRayman can now fully decode .apm (Ubisoft? IMA ADPCM) audio used by Rayman 2 for music. * APM audio is fully preseved and encoded into FLAC audio to ease editing with external programs (e.g. Audacity) * Support for .bnm (audio banks with PCM and IMA ADPCM audio) is underway. This is only commited to get the online GitHub repo up to date. * The data extractor is now threaded (not fully, it simply runs linearly in another thread) * The data extractor now has a GUI progress dialog showing some information to the user (IProgressDialog on Win32, GTK3 on Linux) * Various minor changes and bugfixes 2016-08-14 16:33:53 -04:00			`rayman2` can be created by starting OpenRayman without it or by using the command line option `--convert-data "folder"`. The `folder` variable should point to a valid Rayman 2: The Great Escape installation.
Add a game class for mod support This commit adds a game class, which is a collection of files that can depend on other files. The base game "rayman2" contains all files required for the game, and they can then be overriden by games that depend on it. OpenRayman will use this for editing menus (adding settings) and possibly other things. All mods should target "rayman2_openrayman". 2016-06-14 21:55:52 -04:00

Edit documentation to reflect changes in storage path 2016-07-07 02:32:00 -04:00			`rayman2` will be copied into the OpenRayman storage folder (in windows `%appdata%\openrayman` or linux `~/.local/share/openrayman`). This is all that needs to be done to run OpenRayman.
Add a game class for mod support This commit adds a game class, which is a collection of files that can depend on other files. The base game "rayman2" contains all files required for the game, and they can then be overriden by games that depend on it. OpenRayman will use this for editing menus (adding settings) and possibly other things. All mods should target "rayman2_openrayman". 2016-06-14 21:55:52 -04:00

			`Do note that OpenRayman contains some extensions to the Rayman 2: The Great Escape game, such as more menu options.`


Mostly complete audio decoding * OpenRayman can now fully decode .apm (Ubisoft? IMA ADPCM) audio used by Rayman 2 for music. * APM audio is fully preseved and encoded into FLAC audio to ease editing with external programs (e.g. Audacity) * Support for .bnm (audio banks with PCM and IMA ADPCM audio) is underway. This is only commited to get the online GitHub repo up to date. * The data extractor is now threaded (not fully, it simply runs linearly in another thread) * The data extractor now has a GUI progress dialog showing some information to the user (IProgressDialog on Win32, GTK3 on Linux) * Various minor changes and bugfixes 2016-08-14 16:33:53 -04:00			If for some reason you wish to run without these modifications then you will either need to edit the `config.json` file and change the `game` variable from `rayman2_openrayman` to `rayman2`, or by specifying the game to run via the command line option `--game rayman2`.
Add a game class for mod support This commit adds a game class, which is a collection of files that can depend on other files. The base game "rayman2" contains all files required for the game, and they can then be overriden by games that depend on it. OpenRayman will use this for editing menus (adding settings) and possibly other things. All mods should target "rayman2_openrayman". 2016-06-14 21:55:52 -04:00

			You should always target `rayman2_openrayman` when making a mod.


Mostly complete audio decoding * OpenRayman can now fully decode .apm (Ubisoft? IMA ADPCM) audio used by Rayman 2 for music. * APM audio is fully preseved and encoded into FLAC audio to ease editing with external programs (e.g. Audacity) * Support for .bnm (audio banks with PCM and IMA ADPCM audio) is underway. This is only commited to get the online GitHub repo up to date. * The data extractor is now threaded (not fully, it simply runs linearly in another thread) * The data extractor now has a GUI progress dialog showing some information to the user (IProgressDialog on Win32, GTK3 on Linux) * Various minor changes and bugfixes 2016-08-14 16:33:53 -04:00			`## Obtaining "Rayman 2: The Great Escape"`


			`As previously mentioned, a valid installation of Rayman 2: The Great Escape (PC version) must be used for data extraction.`


			`Rayman 2: The Great Escape can be bought on GOG (https://www.gog.com/game/rayman_2_the_great_escape) or installed from a valid CD.`


			Installing the game on Linux needs to be done via `wine` but should work without further tweaking.


			`(TODO: installing on Android)`


			`The only tested version is the GOG version.`


Fix for windows 2016-06-12 10:37:23 -04:00			`## GL3W`


			`You need to build gl3w.h and gl3w.c before you build the project.`


			`This can be done by executing lib/gl3w/gl3w_gen.py with Python 2.`


Add glfw as submodule 2016-06-11 12:22:42 -04:00			`## Building on Linux`
Initial commit 2016-06-10 20:35:24 -04:00

Add a game class for mod support This commit adds a game class, which is a collection of files that can depend on other files. The base game "rayman2" contains all files required for the game, and they can then be overriden by games that depend on it. OpenRayman will use this for editing menus (adding settings) and possibly other things. All mods should target "rayman2_openrayman". 2016-06-14 21:55:52 -04:00			CMake should be used to generate makefiles, and `make` should be used to build the engine.
Initial commit 2016-06-10 20:35:24 -04:00

			```
			`mkdir build`
			`cd build`
			`cmake ..`
			`make -j8`
			```

Add a game class for mod support This commit adds a game class, which is a collection of files that can depend on other files. The base game "rayman2" contains all files required for the game, and they can then be overriden by games that depend on it. OpenRayman will use this for editing menus (adding settings) and possibly other things. All mods should target "rayman2_openrayman". 2016-06-14 21:55:52 -04:00			The engine can be installed via `sudo make install` and can then be started by executing the command `openrayman`.


			`Additionally, a .desktop file will be created.`
Initial commit 2016-06-10 20:35:24 -04:00

Add glfw as submodule 2016-06-11 12:22:42 -04:00			`## Building on Windows`
Initial commit 2016-06-10 20:35:24 -04:00

Add a game class for mod support This commit adds a game class, which is a collection of files that can depend on other files. The base game "rayman2" contains all files required for the game, and they can then be overriden by games that depend on it. OpenRayman will use this for editing menus (adding settings) and possibly other things. All mods should target "rayman2_openrayman". 2016-06-14 21:55:52 -04:00			`Building should be done with MinGW, and is almost the same as on Linux.`
Fix for windows 2016-06-12 10:37:23 -04:00

			You need to use the command `cmake -G "MinGW Makefiles" ..` instead of `cmake ..` to create makefiles, as OpenRayman cannot be built with MSVC.


			You might also need `mingw32-make -j8` instead of `make -j8`.
Initial commit 2016-06-10 20:35:24 -04:00

Add glfw as submodule 2016-06-11 12:22:42 -04:00			`## Building on Mac OS X`
Initial commit 2016-06-10 20:35:24 -04:00

			`Mac OS X is not supported at the moment (might work with CMake?).`
Add documentation for some of the formats This could not have been done without the amazing https://github.com/szymski/Rayman2Lib. (i have not verified if it works, it might be crap) 2016-06-15 22:25:48 -04:00

Refactoring, lots of refactoring * Split OpenRayman into two parts (openrayman and libopenrayman) libopenrayman is licensed under LGPLv3 * dsb_interpreter -> dsb_script gf_converter -> gf_texture This means that all currently available formats share a mostly common interface (specify stream via constructor, check if the file is valid via valid() and/or extract/decompile via a function returning bool) * Since all formats can only be created via an std::istream, libopenrayman includes two helper stream functions in openrayman::common These are in_mem_(i/o)stream and encoded_stream in_mem stream read and write to a block of memory (can be created from vector/char) encoded_streams take an existing stream and decodes data after reading it from the original stream Some small refactoring to other parts of the engine 2016-07-07 02:16:48 -04:00			`## Licensing`


			`All files in this repository are licensed under GPLv3, except for files that are a part of libopenrayman.`


			`## libopenrayman`


Mostly complete audio decoding * OpenRayman can now fully decode .apm (Ubisoft? IMA ADPCM) audio used by Rayman 2 for music. * APM audio is fully preseved and encoded into FLAC audio to ease editing with external programs (e.g. Audacity) * Support for .bnm (audio banks with PCM and IMA ADPCM audio) is underway. This is only commited to get the online GitHub repo up to date. * The data extractor is now threaded (not fully, it simply runs linearly in another thread) * The data extractor now has a GUI progress dialog showing some information to the user (IProgressDialog on Win32, GTK3 on Linux) * Various minor changes and bugfixes 2016-08-14 16:33:53 -04:00			`libopenrayman is a library that contains several classes for decoding and decompiling file formats used by the Rayman 2: The Great Escape engine.`
Refactoring, lots of refactoring * Split OpenRayman into two parts (openrayman and libopenrayman) libopenrayman is licensed under LGPLv3 * dsb_interpreter -> dsb_script gf_converter -> gf_texture This means that all currently available formats share a mostly common interface (specify stream via constructor, check if the file is valid via valid() and/or extract/decompile via a function returning bool) * Since all formats can only be created via an std::istream, libopenrayman includes two helper stream functions in openrayman::common These are in_mem_(i/o)stream and encoded_stream in_mem stream read and write to a block of memory (can be created from vector/char) encoded_streams take an existing stream and decodes data after reading it from the original stream Some small refactoring to other parts of the engine 2016-07-07 02:16:48 -04:00

			`libopenrayman is at large based upon szymski's Rayman2Lib (https://github.com/szymski/Rayman2Lib).`


			`All files related to libopenrayman are located in the libopenrayman/ subdirectory.`


Add documentation for some of the formats This could not have been done without the amazing https://github.com/szymski/Rayman2Lib. (i have not verified if it works, it might be crap) 2016-06-15 22:25:48 -04:00			`## Special thanks to`


			`https://github.com/szymski/Rayman2Lib`
Refactoring, lots of refactoring * Split OpenRayman into two parts (openrayman and libopenrayman) libopenrayman is licensed under LGPLv3 * dsb_interpreter -> dsb_script gf_converter -> gf_texture This means that all currently available formats share a mostly common interface (specify stream via constructor, check if the file is valid via valid() and/or extract/decompile via a function returning bool) * Since all formats can only be created via an std::istream, libopenrayman includes two helper stream functions in openrayman::common These are in_mem_(i/o)stream and encoded_stream in_mem stream read and write to a block of memory (can be created from vector/char) encoded_streams take an existing stream and decodes data after reading it from the original stream Some small refactoring to other parts of the engine 2016-07-07 02:16:48 -04:00

Mostly complete audio decoding * OpenRayman can now fully decode .apm (Ubisoft? IMA ADPCM) audio used by Rayman 2 for music. * APM audio is fully preseved and encoded into FLAC audio to ease editing with external programs (e.g. Audacity) * Support for .bnm (audio banks with PCM and IMA ADPCM audio) is underway. This is only commited to get the online GitHub repo up to date. * The data extractor is now threaded (not fully, it simply runs linearly in another thread) * The data extractor now has a GUI progress dialog showing some information to the user (IProgressDialog on Win32, GTK3 on Linux) * Various minor changes and bugfixes 2016-08-14 16:33:53 -04:00			`All others who have taken part of the UnLockRay project (https://www.reddit.com/r/UnLockRay/) and helped reverse engineer the Rayman 2: The Great Escape engine.`


			Palorifgrodbierzrt for creating Ray2Get, which the `apm_audio_track` implementation is partially based upon (I figured out the `WAVEFORMATEX` part though ;)).