Introduction
------------

This archive contains the Java source code for the java maze raycasting
engine applet. The source code is called "maze.java" and compiles under
a java1.1 or later compiler.

java maze is developed by myself, Jonathan Thomas. You can contact me
by e-mail at jthomas@deverse.co.uk.

This document, README.TXT, contains the following sections:

        License - read this carefully before you use the source!
        Who is this aimed at?
        What do I need to compile and run java maze?
        Known bugs/issues
        Future additions

*********************************************************************

License
-------

This program 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 2
of the License, or (at your option) any later version.
This program 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 this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

Who is this aimed at?
---------------------

This source code is aimed at accomplished Java programmers who want to
learn more about optimized 3D graphics programming, perhaps adding
features as they go. If you're a novice, I would recommend you do not
tackle this code - it's poorly documented, and a perfect example of how
not to write modular, reusable code.

If you're still not sure what java maze is, see my homepage for a demo:

  http://www.shinelife.co.uk/

What do I need to compile and run java maze?
--------------------------------------------

You'll need a Java development environment such as the Sun JDK or
Microsoft Visual J++.

Also, java maze is an applet. This means you'll need a .html file to
run it to run within a web browser. Those of you proficient in
java programming should have no problem with this.

Known bugs/issues
-----------------

There are a number of issues with the code in its current form. I'd be
flattered if somebody had the time and dedication to fix these problems.

- Odd crashes when standing close to walls. This is -something- to do with
  the optimization of the floor drawing.
- Clipping of the floor and ceiling is not completed. This shows itself
  worst when you walk towards the corners of the map.
- Object support is minimal. Also objects are not depth sorted.
- No collision detection with walls. If the amount of mail I've recieved
  about java maze is anything to go by, this is -by far- the most
  important bug in the world... ever!
- The renderer draws walls on the right hand side of the applet a slightly
  different shade to walls on the left hand side.
- Walls are supposed to be lit at the same level as the floor tile they
  face - the implementation of this is not quite right.

Future additions
----------------

As for future feature additions go, I can think of the following. By the
way, my work on java maze is done - I'm relying on others to
implement these features:

- Support for 16 and 24bit colour modes.
- Trilinear (sort of) mip-mapping on the walls and floor. I don't like
  the artifacts you see on distant walls and floor.
- Coloured lighting. This would look awesome. You'd probably need three
  different lightmaps for RGB.
- IP networking support for Internet play.
- Intelligent enemies for a singleplayer game.
- Polygon objects, such as barrels and lamps. Also sliding doors,
  portcullises (portculli?). Anyone remember "Into the Shadows" ??
- Sky texture that shows through parts of the map without a ceiling. I
  tried this once, but I couldn't get a decent framerate. 
- Dynamic lighting effects (from fireballs, guns, flickering lamps etc).
  This can't be that difficult given that the engine already reacts in
  realtime to changes in the lightmap.
- A map editor facility, to create/save/load maps.
- Lightmap generator (probably some kind of raytracer) to create a
  realistic lightmap from a list of light sources.

And finally ...

- Optimize! Experiment with several different algorithms and squeeze
  every single ounce of performance out of the JVM! java maze is one
  of the few java graphical applets with a reasonable framerate - I'd
  like it to stay that way.
