  /--------------===========--------------\
 [# ReCaged 0.7.1 ("The Sky's the Limit") #]
  \--------------===========--------------/

 A Free Software, Futuristic, Racing Simulator

---
 Copyright (C) 2009, 2010, 2011, 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.
---



1) [TABLE OF CONTENTS]

1) Table of Contents
2) Licensing
3) Running
4) Default Controls
5) Configuration
6) Hardware Requirements
7) Software Requirements
   7.1) OpenGL
   7.2) GLEW
   7.3) SDL
   7.4) ODE
8) Compilation
9) Credits
10) Links



2) [LICENSING]

ReCaged  Copyright (C) 2009, 2010, 2011, 2023 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/>.



Information on the licensing of the included media/"binary" files is
specified in README files located in the same directory as each media file.



3) [RUNNING]

The current version of ReCaged does not require installation in order to run.
Instead, just place recaged (on windows: recaged.exe) in any directory.
In the archive, there are two directories: src and data. While data is needed,
src is only needed for compilation.

Src is not needed for rc to run - it contains the sourcecode for compilation
and modification of rc. The data directory contains the default configuration
and all 3D models. Without the 3D files in the data directory, rc will not
have anything to render, which is why rc will refuse to start if these files
are missing.

A few options are available as arguments:
Path to data directory ("-d"), default: "data" in the same dir as the binary).
Path to profile directory ("-p"), default: "profiles" inside the data dir.

Example: use the read only _data_ directory "/opt/recaged/data", and "profile"
directory the user has read/write access to (in home):
> recaged -d /opt/recaged/data -p /home/slinger/recaged



4) [DEFAULT CONTROLS]

While (almost) all input keys can be changed (data/profiles/default/keys.lst),
the following is the defaults 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.


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.

Spawning:
* F5-F8 - spawn 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 - respawn 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)



5) [Configuration]

RC can be configured using a couple of plain-text files divided into several
directories inside the data directory, 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 performance, and also is the place where
you will be able to select resolution, full screen toggling, and eye_distance.

If you are wondering about the last one:

The viewing angle in the game is calculated based on your eye distance from
the screen, in pixels. This system got the advantage of always providing a
realistic viewing angle for all resolutions. But if you don't like this, you
can force a viewing angle in the configuration file (internal.conf).

If you want to tweak this value to your specific workstation, determine how
many pixels a normal length unit is by dividing your screen height (or width)
resolution with your physical screen height (or width). You can then multiply
the resulting value with the distance you have measured between your eyes and
screen (in reality).



6) [HARDWARE REQUIREMENTS]

The requirements for running rc is 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 rc. If you want to use many high detail models,
be prepared that the requirements might increase a bit.

Note: hardware opengl acceleration recommended, but of course, software
rendering is an alternative, assuming you got enough processing power.

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. There is however a windows compiled version (recaged.exe)
which might work.



7) [SOFTWARE REQUIREMENTS]

RC needs OpenGL and three libraries (the compiled windows binary includes the
needed libraries):

   7.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 RC does not use GLU or GLUT, only GL.

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

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

   7.4) [ODE]
   RC uses the library "Open Dynamics Engine" for some physics simulations.



8) [COMPILING]

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 and/or meta-packages
named like lib<name>-dev). Also make sure you got at least a Make program and
a C++ compiler (such as GNU Make and the GNU C++ Compiler, g++) and the usual
libraries.

RC currently does not use autoconf, but only a custom makefile, so in order
to compile, just cd into the src directory and type "make".


On windows things will be more difficult: since there is no package manager,
you will have to install all requirements manually.

First of all, install MinGW (a minimal port of GNU for windows - it provides
compilers and standard libraries for compilation), make sure to install make,
autoconf and g++. Msys is also recommended (as it provides a user interface to
MinGW).

Then you must compile and install the SDL, ODE and GLEW libraries. This
process will not be covered in detail here. Once you have downloaded and
extracted a tarball, cd into the appropriate directory and use:
./configure && make && make install
(exception for GLEW: it doesn't use autoconf, just "make" and make install").

Then cd into the src directory of rc and use "make w32" to compile a static
binary, called "recaged.exe", which includes the needed libraries (for easy
redistribution).



9) [CREDITS]

ReCaged credits (with alternative names on gorcx.net forum):

  * Mats Wahlberg ("Slinger")	Creator (coder) + development 3D models
  * "K.Mac"			Extensive testing, hacks and new ideas
  * "Spontificus"		Testing, hacks and various fixes


Other Projects that made ReCaged possible:

  * "Free Software Foundation"  "Free Software, Free Society", supporting the
				free software movement

  * "The GNU Project"           Developing a Free OS. Its work for computer
				freedom has changed the world

  * "Simple DirectMedia Layer"	OS/hardware abstractions
  * "Open Dynamics Engine"	Rigid body dynamics and collision detection
  * "OpenGL Extension Wrangler" OpenGL version/extension loader



10) [LINKS]

* ReCaged homepage:
http://recaged.net

* ReCaged savannah project page:
https://savannah.nongnu.org/projects/recaged/

