Residual: A 3D game interpreter

What is Residual?
-----------------
Residual allow to play 3D games such as Grim Fandango.

Residual utilizes OpenGL for 3D graphics hardware acceleration.
A software renderer is also included for machines without hardware OpenGL.

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

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

How do I run Residual?
----------------------
As Residual is not yet stable, easy to use, or complete.
Some technical ability might be required.

It runs really slow !
----------------------------------------
Some gfx cards do not have a fast glDrawPixels access to zbuffer
implementation in the system driver.

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. Software renderer is generally faster on modern platform.

What is the state of Residual? 
------------------------------
Basic gameplay works, including cutscenes. Parts of the game are playable,
but many features are either missing or unstable. Crashes are likely.

Grim Fandango currently playable to the end. (With quite a few glitches)

Some puzzles might be hard to complete currently.

Also beware that since Residual is currently in an alpha-state, there is
no guarantee that your saves will continue to work with newer builds.

For more information, see the page on Residual at the wiki page:
http://apps.sourceforge.net/mediawiki/residual

Which datafiles are needed?
---------------------------
*.LAB
GRIM.TAB

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)
Alt + x    : Quit (ingame)
F1         : Menu

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

Note that these are only available after enabling debug-mode.


How do I enable debug-keys?
---------------------------
To enable debug-keys, you will have to add the following to your configuration file
under your Grim Fandango-entry:

game_devel_mode=true

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

        Windows Vista/7:
        \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

How do I report bugs?
---------------------
You can report bugs at our github-issue-tracker:
https://www.github.com/residual/residual/issues

Please read the Wiki regarding how to report bugs properly first though:
https://sourceforge.net/apps/mediawiki/residual/index.php?title=Reporting_Bugs

Remember to always have the following information in your bug reports:
* Bug details, including instructions on reproducing it
* Language of game (English, German, ...)
* Platform and Compiler (Win32, Linux, MacOS, ...)
* Preferably also a link to a save game right before the bug happened.