Residual: A LucasArts 3D game interpreter

Last updated:    $Date$
------------------------------------------------------------------------------

What is Residual?
-----------------
Residual is a ScummVM (http://www.scummvm.org/) sub-project to play LucasArts'
LUA-based 3D adventures, such as Grim Fandango. Residual is an OpenGL program,
and requires a 3D card with working OpenGL support for optimum playability.

A software renderer is also included for machines without hardware OpenGL.

The main ScummVM program can run LucasArts 2D SCUMM adventures (among others).
Residual is named such as it aims to do the same for the residual (remaining) 
games. It is also a word pun, as the engine used in these LUA-based adventure
is called GrimE (as opposed to SCUMM). Grime is a type of residue.

What games does it support?
---------------------------
Residual is a fairly new project and slow developing project, and is still very
much considered alpha. Currently it contains initial support for Grim Fandango.

It is possible, but far from promised, that we can support the other LucasArts
LUA-based title 'Escape from Monkey Island' in the distant future.

How do I run Residual?
----------------------
As Residual is still under heavy development, it is not yet stable, easy
to use, nor complete. Some technical ability is required.

See the Configuation File section, to see how to create the configulatun file.

Residual understands command-line options: 
'-fps' display fps information.
'-fullscreen' switch to full screen
'-soft' switch to software 3d renderering.
'-zbuffer' enables masking for hardware 3d rendering.

Configuration file:
---- -------------------
By default, the configuration file is saved in, and loaded from:

        Windows Vista:
        \Users\username\AppData\Roaming\Residual\residual.ini,

        Windows 2000/XP:
        \Documents and Settings\username\Application Data\Residual\residual.ini,

        Windows NT4:
        <windir>\Profiles\username\Application Data\Residual\residual.ini,

        Windows 95/98/ME:
       <windir>\residual.ini,

        Unix:
        ~/.residualrc

        Mac OS X:
        ~/Library/Preferences/Residual Preferences

        Others:
        residual.ini in the current directory

An example config file looks as follows:

       DataDir=[path to all the .lab files]
       good_times=TRUE

It runs really slow when using -zbuffer!
----------------------------------------
A large portion of older cards (Such as 3dfx cards, Radeon 7500 and earlier,
Matrox G4xx series cards, etc) and newer cards too (Radeon X800 GTO
with Windows drivers) do not have a fast glDrawPixels implementation.

Unix users may be able to achieve playable framerates by using Mesa 5.0 or
above, but people unable to upgrade or Windows users must use software
renderer (-soft).

Black screen while menu dialogs on Radeon with Windows!
-------------------------------------------------------
Turn off force fullscene antialiasing in OpenGL gfx driver options.

What is the state of Residual? 
------------------------------- 
Basic gameplay works, including cutscenes. Some of the game is playable,
but many features are either missing or unstable. There is no abilitity
to save/load, etc. Crashes are likely.

Game currently playable to:
	Meche leaves Manny again (Rubacava, Year 2)

Caveats (in order of appearance):
1) Sound track destruction doesn't do quite a good enough job when
   entering the spider web area (sp.set) in the Petrified Forest
2) Video of Copal's death (among other movies) plays at *almost* 2x
   the correct speed, this causes buffer overflows in the audio.
   While hardcoding the speed to the correct value used by the other
   movies works, it is not a good fix and so it is not implemented
3) Sometimes the Demon Beavers get stuck on obstacles - open the 
   menu for a moment and they will correct themselves

What are the default keys?
--------------------------
e,u,p,i    : Examine, Use, Pickup, Inventory
Arrow keys : Movement
Shift      : Hold to run
Enter      : Selects items in inventory, conversation, etc
Escape     : Skips cutscenes, exits certain screens
q          : Exit Dialog Menu
Ctrl + c   : Force Quit (from command-line)

Development/debug keys from the original game
---------------------------------------------
Ctrl + e   : Enter lua string to execute
Ctrl + g   : Jump to set
Ctrl + i   : Toggle walk boxes
Ctrl + l   : Toggle lighting
Ctrl + n   : Display background name
Ctrl + o   : Create a door
Ctrl + p   : Execute patch file
Ctrl + s   : Turn on cursor
Ctrl + u   : Create a new object
Ctrl + v   : print the value of a variable
Alt + n    : Next viewpoint
Apt + p    : Prev viewpoint
Alt + s    : Run lua script
Shift + n  : Next set
Shift + p  : Prev set
Shift + o  : Toggle object names
F3         : Toggle sector editor
Home       : Go to default position in current set
j          : Enter jump number

How do I report bugs?
---------------------
Don't. Residual is very alpha and we KNOW it doesn't work right.