/--------------------================--------------------\
 [# ReCaged 0.8.0 ("The Devil's Mind is an Idle Workshop") #]
  \--------------------================--------------------/

  A Free Software, Futuristic, Racing Game

 Copyright (C) 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2023 Mats Wahlberg

 Copying and distribution of this file, with or without modification,
 are permitted in any medium without royalty provided the copyright
 notice and this notice are preserved. This file is offered as-is,
 without any warranty.



1) [TABLE OF CONTENTS]

1) Table of Contents
2) Introduction
3) Licensing
4) Requirements
5) Compiling
6) Running
7) Default Controls
8) Configuration
9) Credits
10) Links



2) [INTRODUCTION]
TODO... Futuristic, Vehicular combat, inspiration...

Supports OSes...
TODO: installer for windows, more OSes!

TODO: update...
Also, a POSIX compliant OS should be used (such as GNU or BSD). A GNU variant
is recommended (such as GNU/kfreebsd or GNU/linux). Note that Windows is not a
targeted OS, because it's not POSIX compliant and generally difficult to
use/develop on. It has however been successfully tested on many operative
systems and there is a windows installer.



3) [LICENSING]

ReCaged  Copyright (C) 2009, 2010, 2011, 2012, 2013, 2014, 2015 Mats Wahlberg

ReCaged is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

ReCaged is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with ReCaged.  If not, see <http://www.gnu.org/licenses/>.


TODO... See COPYING for more info!


Licensing information of binary media files is specified in a README file in
the same directory as the relevant media file. However, all files are released
under the same terms as above (GPL version 3), unless stated otherwise inside
the file or in an accompanying README file.

TODO: licensing directory!



4) [REQUIREMENTS]

The hardware requirements are modest, a recommended minimum would be:

* Processor:	1.5GHz, 32bit
* Memory:	32MiB RAM memory free
* Graphics:	OpenGL 1.5 or later, 16MiB video memory

Memory and processor requirements also depends on OS and other programs 
running at the same time as ReCaged. If you want to use many high detail
models, be prepared that the requirements might increase a bit.

Note: hardware opengl acceleration recommended, but software rendering is a
viable alternative (assuming you got enough processing power).

Except for the usual requirements ReCaged needs OpenGL and a few third party
libraries (the compiled windows binary includes these):

   4.1) [OPENGL]
   As mentioned above, some kind of OpenGL implementation is needed for
   rendering of 3D graphics. This is OS dependent, but it is quite common
   (either hardware or software). This version requires GL 1.5 or later.
   Note that ReCaged does not use GLU or GLUT, only GL.

   4.2) [GLEW]
   ReCaged uses the library "OpenGL Extension Wrangler Library" for loading and
   checking opengl versions and extensions.

   4.3) [SDL]
   ReCaged uses the library "Simple DirectMedia Layer" for some OS independent
   functionality.

   4.4) [ODE]
   ReCaged uses the library "Open Dynamics Engine" for most physics simulations.

TODO:

Z LIB
PNG reference library
IJG JPEG library


5) [COMPILING]

If you have installed a pre-compiled package or used the windows installer,
you can skip this section. Otherwise read on...

First of all, you will need the libraries mentioned above (gl, glew, sdl and
ode). Also check if your distro provides development libraries in separate
packages and if so, install them too (look for packages named like
lib<name>-dev). Also make sure you got the usual development tools (Make, C++
compiler, libraries etc). Autotools are needed when building from git.

The build process is the standard autoconf routine (see the file "INSTALL" for
more information): run "./configure" followed by "make". "make install" will
install (but that is not needed to run, you could just start "recaged" from the
src directory).

If you're building from the git repository (development),
first run "autoreconf -vfi" to generate the configure script and other
required files. Remember to set "CPPFLAGS" and "LDFLAGS" if necessary.

If you are building on OS X (you crazy person!), you can use MacPorts to get
all necessary dependencies (libsdl, ode, glew, etc. you can also get automake,
autoconf and git for development versions). The rest or the build process is
just like above. Remember that macports use a nonstandard path (/opt/local),
so you will need to run configure like this:

./configure CPPFLAGS=-I/opt/local/include LDFLAGS=-L/opt/local/lib


On Windows things will be more difficult: since there is no package manager,
you would have to install all requirements manually. There is however a script
called "build.sh" included to help automate the build process.

TODO: build.sh cross compiling!

First of all, install MinGW (a minimal port of GNU for windows - it provides
compilers and standard libraries). The latest version can be downloaded here:

http://sourceforge.net/projects/mingw/files/Installer/mingw-get-setup.exe/download

TODO: new mingw installer is different, mention installing msys in the new gui,
finding the shell... 

msys-base

The only installation option really recommended to choose
here is the "MSYS Basic System", which provides a bash shell suitable for
working with MinGW. It's not necessarily needed but working without it is much
harder and you will not be able to use the automated script.

Now use the msys bash shell to run the provided script "build.sh" with the
arguments to install the necessary libraries and compile (run "build.sh
help" for more details). Running "./build.sh w32deps" will install the
necessary libraries (in you home directory) and tools for compiling releases.

Finally: Running "./build.sh w32inst" should configure and build ReCaged for
w32 with the necessary libraries statically linked (and strip out debug symbols
and ... TODO!

Alternatively you can compile and install the SDL, ODE and GLEW libraries
manually, and install NSIS. This process will not be covered in detail here.

You can also use "./build.sh w32quick" to run ./configure with suitable arguments

Then cd into the src directory of recaged and run "./configure && make" to compile.
But if you want to create a complete installer, instead run "./configure
--enable-w32static --enable-w32console && make" to compile and then build the
NSIS installer. Or just use "./build.sh w32inst". The "--enable-w32static"
option makes sure all libraries that would normally have to be included as
DLLs are linked into the exe, and "--enable-w32console" enables console log
output (requires SDL to have been built with "--disable-stdio-redirect").

TODO: correct this, configure not necessary if using w32quick, but mention it
as an alternative...



6) [RUNNING]

TODO: all of this should be rewritten!

note about installed and portable mode, xdg/standard dirs, arguments, etc...
And see COMPILATION



7) [DEFAULT CONTROLS]

While (almost) all input keys can be changed (data/profiles/default/keys.lst),
the following are the default keys for the car:

* Arrow keys for accelerating/reversing/breaking and steering
* Space for locking/drifting breaks
* Changing of camera modes using F1-F4
* For quitting the game, just press Esc.

TODO: gamepad input, defaults...

There are also a couple of demo/debug keys (these keys can not be changed):

Camera movement/tweaking:
* A/D, W/S and Q/E - movement along X, Y and Z axes.
  Note that these buttons will be used for weapon control in future versions.

Creation:
* F5-F8 - create some objects:
  box, beachball, funbox, molecule.
  Note that this function will also be removed in future versions

Debugging:
* F9  - switch car (if more than one)
* F10 - recreate car at track starting point
* F11 - simulation pause (camera can still be moved)
* F12 - wireframe geom/collision rendering toggle, the following is provided:
   + models (normal rendering, only the 3D models)
   + models and (clearly visible) simple geoms (all geoms but trimeshes)
   + models and all geoms (includes trimeshes)
   + all geoms (like above, but without 3D models)
   + simple geoms (like above but without trimeshes)
   + collisions (all geoms, black background and colour based on collision)



8) [CONFIGURATION]

TODO: note about installed vs portable file layout, xdg, $HOME, etc...
ReCaged can be configured using a couple of plain-text files divided into
several directories inside the data and config directories, such as "teams",
"worlds" and "profiles"

What you might be most interested in is specified in internal.conf, it
provides many ways of tweaking the precision and performance, and also is the
place where you can change default resolution, fullscreen, FOV (or change to a
realistic, dynamic FOV)

TODO: mention tmp_menu_selections! profile, track/car settings...



9) [CREDITS]

ReCaged credits (some people referred to by nicknames):

  * Mats Wahlberg ("Slinger")	Creator/developer + development 3D models
  * K.Mac			Extensive testing, hacks and new ideas
  * MeAkaJon			Creating the original project homepage
  * Spontificus			Hacks, fixes, move to C++, git and new website
  * MoruganKodi/コディ[KODI]	Many High Detail 3D models for cars and tracks
  * orgyia			Testing, scramble-like test track
  * You (yes, you)		For being interested and trying ReCaged!


Other Projects that made ReCaged possible:

  * Free Software Foundation	"Free Software, Free Society"
  * The GNU Project		Developing a Free OS
  * TuxFamily			Amazingly generous hosting for the project!
TODO: SAVANNAH, hosting



10) [LINKS]

  * ReCaged Homepage:	http://recaged.net/
  * ReCaged Forum:	http://forum.recaged.net/
  * Page on Savannah:	https://savannah.nongnu.org/projects/recaged/