
         StahlWorks d3caster, a 3-D Java Game Engine 
         ===========================================
         StahlWorks Technologies, www.stahlworks.com
          Read CHANGES.TXT for current version info

   Supplied in form of a demo game, called "Art Attack".

   Purpose of this package:
   -  to give copy-and-paste examples for rock-solid,
      everywhere compatible Java Game Programming.
   -  to provide a basis for modifications (simply
      called "mod's") by changing the code, and/or 
      graphics and sound. you are free to publish
      such modified games on your own website.

   Prerequisites:
   -  you need to have a Sun Java 2 SDK installed.
      search Google for "sun java 2 j2se" for download.
   -  to use the supplied image conversion tool d3conv,
      you need also Sun's Java Advanced Imaging,
      and Java Advanced Imaging Image I/O Tools. 
      Search Google for "Java Advanced Imaging API",
      or try to download it directly from
      http://java.sun.com/products/java-media/jai/

   Intended audience:
   -  if you intend to change the code, you should have
      a good knowledge of Java programming, and the
      ability to learn by examples.
   -  but you may also create new games just by
      changing the map, graphics and sounds.
      you are free to publish such modifications (mods)
      on your own website, but make sure that you
      include only artworks that are either made
      by yourself, or which are free for distribution
      (like the artworks supplied in this package).

   Credits:
   -  The 3-D graphics part is based on "java maze",
      created by Jonathan Thomas, www.shinelife.co.uk.
   -  Ogg Vorbis compression classes were downloaded from
      http://www.jcraft.com/jorbis/

   Features (added, since java maze):
   -  support for different screen and texture resolutions;
      now, from 64x64 to 512x512, everything's possible.
      256x256 prooved to be the optimum compromise.
   -  high-color (15-bit) JPG based textures.
      truecolor was too slow, at least on a Pentium III 900 Mhz.
   -  dynamic texture and image loading:
      the stuff is loaded step by step while playing.
   -  correct object drawing with depth sorting
   -  objects: rocket, robots, decoration and obstacles
   -  object/wall and object/rocket collision detection
      (and even rocket/rocket collision, sometimes)
   -  everywhere-compatible sound system, for JDK1 and JDK2
   -  Ogg Vorbis sound compression support (JDK2 only)
   -  loadable world map (worldmap.gif), with color-based
      object encoding. to be created/edited by paint program.
   -  area handling. an "area" is a special zone where robots
      are located, they attack the player once he steps in.
   -  text display via memory-mapped font, bypassing
      performance problems with Java's Graphics class
   -  a stable, constant timing system, independent of CPU speed
   -  smoke on walls after rocket hit

   Bug fixes:
   -  There was a crash when standing close to a wall.
      Probably caused by division by 0, due to some
      number over- or underflow. Search the source for "FIX for
      division by zero". Also added further value checks.
   -  Fixed clipping of floor and ceiling. This really took a while,
      analyzing and recoding parts of renderBufferVLine,
      and replacing some constant number magic. Now there is proper 
      width/height aspect handling, the applet may have any size.
   -  read CHANGES.TXT for more.

   Game design tips:
   -  the user must get immediate optical feedback
      while things are loading.
      otherwise he gets impatient, thinking that
      the applet crashed (which is often the case
      with many bad designed website applets).
   -  a firm steering, or motion control, is very
      important. if the user presses cursor right,
      the system MUST react IMMEDITATELY, and turn
      to the right, without the slightest "jerky" feeling.
      only while some stuff is loaded, the system may,
      temporarily, react a bit slower.
   -  the game MUST be COMPATIBLE accross ALL browsers.
      a simple test: the "worst" java and html browser 
      available is Netscape 4.79 (yes, 4.79).
      If it runs there, it probably runs everywhere.

   Technical issues concerning the engine:
   -  in general, avoid that the player walks through
      wide open space (i.e., outside the building), 
      as this slows down the rendering.
   -  many parts of the source do not cope with
      extreme coordinate limits, e.g. x=0 and x=255,
      to reduce complexity. the world map image
      simply has a large wall around the edges
      to deal with this.
   -  the sound system isn't very generic, it provides
      exactly the sounds needed for the supplied demo game,
      so replacing or extending the sounds can be a bit tricky.
      watch out for some hard-coded maxium sound lenghts
      or playback timings within d3sound*.java.
   -  some downloadable Firefox extensions may change the behaviour
      of the Java 2 VM, e.g. leading to unexpected calls to stop()
      and destroy(). this has nothing to do with the game engine;
      disabling these extensions solves the problem.

   Things left out:
   -  whole rawpic/ png's are not included in the distribution
      as this would blow up the package beyond 8 MB.
      After all, it's not important,
      you can run the game as it is - and if you want
      to develop own stuff, you also have to create
      own graphics and sound. Be creative!
   -  The full Art Attack, available online at stahlworks.com/games/
      has support for nicknames and an "area heroes list".
      This required lots of PHP web programming,
      and much hard-to-understand URLConnection stuff,
      which is stripped off the source for better readability.


   License and distribution
   ------------------------
   
   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.

   Furthermore, all graphics and music supplied in this package
   were created and composed by StahlWorks Technologies, and they
   are also free for distribution, either as they are, or in
   modified form.

