Spaceman Spiff
                                in
                          Escape from Zorg!

          (CS248 Fall 2000 assignment 3, by Robert Bridson)

Platform:
  Prebuilt for firebirds (Redhat Linux 6.2 on Pentium)
  Also compiles on Sweet Hall Sun UltraSparcs with OpenGL, and probably any
  other machine with X, OpenGL 1.1, and Objective CAML.

How to build:
  You first need Objective CAML 3.00, available at
    http://caml.inria.fr/ocaml/distrib.html
  and LablGL 0.94 (the OpenGL API for OCAML), available at
    http://wwwfun.kurims.kyoto-u.ac.jp/soft/olabl/
  Change directories to spiff/src.
  Edit the makefile according to where the OCAML libraries are located
  on your system.
  Type "make install". This will create the game and editor executables
  in the spiff directory and the spiff/Dungeon director respectively.
  You can further type "make clean" to reduce disk space usage.

How to run:
  Just run either executable.

How to play (and the premise):
  You are the fearless Spaceman Spiff, held captive in the dungeons of 
  Zorg after crashlanding (yet again) on the hostile desert planet. After 
  a fierce battle with the evil Zorgoids, you were overcome, only to wake 
  up later in a smelly prison cell with nothing more than your clothes 
  ... and your carefully hidden Dematterizer.

  The Dematterizer, when fired, swings a chunk of matter into the Fifth 
  Dimension --- temporarily. It soon swings back into reality, so it's a 
  good idea to not be in the space it occupied. In particular be careful 
  about falling into dematterized pits, since in your weakened condition 
  you won't be able to jump out.

  Beware of guards patrolling the dungeons, who will easily overcome your
  puny Earthling physique and lock you up again if they can catch you. The
  Zorgoids have a limited patience for escape attempts; get caught too many
  times and they will freeze you in carbonated scum forever (a.k.a. Game
  Over). However, you may find the occasional treasure chest, with which
  you can bribe the guards into giving you another chance.

  To advance from the depths of the dungeon to the surface though the
  intermediate levels, you will need to use the teleporters. To activate
  a teleporter, you need to collect 9 charges (they look like batteries).

  The screen is divided into the world view (what Spiff is seeing), a
  display of the remaining chances for escape on the right, an indicator
  showing the remaining charge in the dematterizer on the bottom, and a
  panel in the bottom right showing teleporter charges collected so far.

  While in game mode (entered by selecting 'Start' or 'Resume' in the Game 
  menu) the following controls are active:

     mouse movement - rotate Spiff
     mouse button -   fire dematterizer
     cursor keys -    walk around
     0/insert -       jump
     escape -         pause game (and get menubar)

  One command worth trying out in the Option menu is 'Stereo' --- it puts
  the game display in red/blue stereo mode, so that if you are wearing
  red/blue glasses (the left lens should be red, the right blue) you will
  get a full 3D effect.

  The game level editor is pretty crude, but functional enough to create
  some interesting levels. The display is of slices (in the vertical
  direction) of the level. Use the left button to select the current cube,
  and the controls below to put objects in that cube. Use the right button
  to change whether or not the cube is solid (if it is, the controls below
  can change the wall textures).

Advanced features:
  On-screen controls panel. This is very simple, just showing the
  dematterizer charge, how many teleporter charges you have, and how many
  chances you have left.

  View-frustum culling AND dynamic occlusion culling. This is done based
  on the underlying 3d grid of the game. At each frame, I do a partial
  breadth-first search in this grid to discover all non-occluded cubes
  in the view frustum. As I go I assemble a list of solid game objects
  (walls of and solid objects contained in visible cubes) and a list of
  partially transparent (dematterized) objects. The search begins by
  placing the cube containing the eye in a queue. Then while the queue
  is not empty, I take the first cube off it and figure out which of its
  faces are facing the eye (1 to 3, or the special case 0 for the cube
  containing the eye). I then check if any of the respective adjoining cubes
  have already passed the view frustum clipping test - in which case this
  cube must be in the frustum. If the cube passes, I add the cubes adjoining
  the rear faces to the queue. Also, if the cube passes I check if it's
  occluded --- i.e. if the cubes adjoining its visible faces are either
  outside the view frustum, solid, or occluded themselves. I only add
  the cube and its contents to the rendering lists if it passes this
  occlusion test.

  Collision detection. This is done all with axis-aligned boxes - simple,
  but effective enough for the game. The only hard part is collision response;
  making sure that things can slide over abutting boxes without entering them.
  I have to make sure to deflect an objects displacement as little as possible
  while still avoiding collision. The underlying 3d grid also helps to make
  collision detection for n objects O(n) instead of O(n^2), as we only
  have to check an object against the objects in nearby cubes.

  Simulated dynamics. Very simple - just gravity.

  Advanced rendering effects. The partial transparency of dematterized
  objects is achieved by making two rendering passes. On the first pass,
  the solid objects are rendered normally. Then the depth buffer is made
  read-only and the transparent objects are rendered from furthest to
  nearest (recall that the culling algorithm's breadth-first search generates
  a list of transparent objects in this order).
  The red-blue stereo effect is achieved by another two passes, from a
  slightly displaced viewpoint. In the first pass, we mask the color channels
  so only red is drawn, then we clear the depth buffer (but not the frame
  buffer) and mask blue instead.

  AI. Very simple - the guards follow the scent trail left by Spiff as he
  moves around the dungeon, attempting to jump over or walk around obstacles
  they encounter. However, this behaviour is enough to keep the player on
  his toes.

  Game level editor. This is a bit crude, but functional enough to create
  lots of fun levels with puzzles to be solved. See the README in the
  Dungeon/ directory for more details on this.

Game content:
  The textures mostly began as digital photos I took of things around campus;
  the rest I created from scratch. Touch-up work was done with Photoshop,
  ClarisWorks, and my paint program from assignment 1. If you're really
  curious, the brick walls are from the main quad, the stone floor tiles
  from the Burghers of Calais installation, the rough stone ceiling from
  an Escondido Village sandbox, the wooden steps from a redwood fir tree,
  the bribes from a wooden bench, the alien's skin from eucalyptus bark,
  and the iron bars from an iron utility cover.

  The models are original, created by directly typing them in by hand
  (sometimes with the help of graph paper). The creation of the guard was made
  a bit easier by defining a primitive for drawing generalized cylinder
  sweeps.

  The pixamp of Spaceman Spiff in the chances display was snagged from the
  web and then touched up - probably in violation of Bill Watterson's
  copyright I'm afraid.

External code sources:
  None.