
CONTENTS

This file contains the full documentation for the AmigaBoulderDash
program.  Please read the distribution information if your read nothing else
in this file.

 Distribution information

       Introduction      
         Overview        
     The cave editor     

   System requirements   
  Hard-disk installation 
    Changes since V0.9   

          Bugs           
         Author          
    Additional credits   

  DISTRIBUTION RESTRICTIONS

  Amiga Boulder Dash program 1997 by Jeff Bevis

  Permission to use and distribute this program is granted subject to    
  the following conditions:                        

    This program is DonationWare.  If you find the program to be    
       useful you should send appropriate payment to the author.    
       $20 (US) is suggested.  I have chosen to distribute the full
       executable (rather than a partially crippled version).  This
       is due, in part, to my own disdain of CrippleWare, but also
       to encourage widespread distribution of the program.
       
       I will remember those who donated when the time comes to
       distribute the next version...  And will likely mail out
       updates in the future.  (when: I can't say :-)
       
       (keep in mind that I spent over $1000 in trying to provide
        this latest release!  I'm broke now!)

    This program may not be sold for profit without the            
       written approval of the author.

     Permission is granted for this program to be included in    
       freely distributable software libraries, such as the        
       Fred Fish freely distributable AMIGA software library.

     This program may NOT be distributed as part of a commercial
       publication, such as a disk/magazine.

     This program should only be distributed in its entirety,
       with all original files present and intact (and unmodified).    

     The author accepts absolutely no liability for any use,    
       misuse, or inability to use this software, nor any        
       consequences (whether intentional or accidental) arising
       from its use or possession.                    

     No warranty is implied nor in effect for the user of this     
       program.  Use of this program is at your own risk!    

 Contents

ADDITIONAL CREDITS

There are many people who have contributed to this version of the game.

     Peter Broadribb
        Game mechanics & refinements; Additional caves.

     Laurence Vanhelsuw
        Inspiration; Additional caves

     Gerhard Witte
        Play testing; Constructive criticism; Psychotic limbo.
        The software bug-magnet.

     Heath Doerr
        Videotape; Letting me play the original!

     Ryan Osborn
        Mucho play-testing, suggestions.

     Mike Cuddy
        68030 debugging.

     Mike Seifert
        Providing the first 68030 platform for on which I could
        debug the game!

     Mike Ringle
        Original caves, play-testing.

     Chris Varga
        Additional sampling.

     Corey Linkel
        Additional caves; play-testing.

     Chris Green
        Help with graphics.library.

     Teijo Kinnunen
        Easy to use music software.

      PL 
        A wonderful idea back in the early 80's.

     Barbara 'B'
        Motivation enhancement!

 Contents

SYSTEM REQUIREMENTS

I have attempted to make this version of the program accessible to as many
Amiga users as possible.  The previous version failed to run on faster
machines do to some idiotic oversights on my part.  However, now it should
make no difference which processor you have.


Things you need:

     Kickstart 2.0 or higher.
      I will no longer support version 1.3 of the OS in any of my
      present or future projects.  It's antiquated, and should no longer
      be in use.  If you're still using 1.3, I strongly(!) encourage you
      to upgrade to the latest OS release.  Without 2.0, I would still
      be writing the cave editor today...

     At least 512K of FAST memory.  The program runs too slowly 
      on machines with only CHIP memory.  The result is usually a
      flickering gameplay display.  A1200 users are particularly
      vulnerable to this problem since that machine is shipped with
      2Mb of CHIP memory only.

     The program must load into FAST memory (I can't empasize that
      enough).  If you've tied up your FAST memory with other
      applications, you could end up running the program in CHIP
      (and it won't work well).

     At least 1Mb RAM total, with at least 1Mb CHIP recommended.
      (Precautions have been taken to hopefully get the program to 
      work in less, but there are no lesser systems nearby to test :-)

     Lots of free time.


Things you don't need:

     A 68020, 030, or 040 is not needed, but recommended.  The game 
      runs better if you give it the power!  The graphics animation
      is about 50% slower with a 68000 processor.

     Hard disk.  (although it helps a lot)

     A Joystick (you can use the keyboard now)

 Contents

INTRODUCTION

This is all Laurence Vanhelsuw's fault.  If his Rocky Clone V1.0 hadn't
fallen into my hands, I would have continued to lead a perfectly happy
life.  Instead, my desire to play Boulderdash was rekindled (rather 
violently, I might add), and thusly this incarnation of the game was
born.

Laurence's program does a great job of accurately reproducing the
cell automata of the C64 version of Boulderdash, and I was duly impressed.
However, I wanted it to look and sound like the C64 version (well, we
should hope it would be a little better :-)  This program represents a
totally new implementation of the game, and none of the source code from
Rocky Clone V1.0 has been used in this program.  Several of the Rocky 
game caves are reproduced here, though -- primarily because 1) I haven't
had time to make a lot of new caves, and 2) I think Rocky players
(especially Laurence) would get a kick out of seeing the caves with
new, better graphics and sound.

For this release, the program has undergone many changes.  Lots of new
features have been added, most notably the  cave editor.  Creating your
own new cave files has never been simpler!  For a full description of the
new features and/or changes from version 0.9, see the  Changes section of
this file.

This version of the program has been tested successfully on several
machine configurations:

     A2000
     A3000-25
     A3000 with PPS '040
     A4000

On each of these machines the program seemed to run fine.  The program
did not run well on the A1200 machines it was tested on, however they 
were not equipped with FAST memory (see  system requirements).

 Contents

CHANGES SINCE VERSION 0.9

The game has been extensively rewritten since the initial release.  Many
(and I mean MANY) new features and functions have been added.  The most
glaring change from version 0.9 is the addition of a full game level
editor.  I sincerely hope THIS addition to the game will motivate others
to produce and share their own caves.

Other changes/features you should be aware of are:

     68010,020,030,040 compatability has been achieved.

     The program no longer does a "hostile takeover" of the machine.
      In fact, it is now OS-friendly.  (ie, task switching is not 
      disabled.)  It does, however, OwnBlitter() during the entirety
      of gameplay, which will cause 80% of other tasks (which have
      graphical output) to still be blocked.

     The program no longer messes around with the CIAs, except for
      Teijo's music software (which appropriately allocates this
      system resource).

     The full program has been tested with latest available Enforcer.
      No Enforcer problems are known to exist at this time.

     Game 'levels' are now more appropriately called 'caves'.

     Butterflies and Fireflies may follow edges differently than
      before.  Previously, butterflies 'rotated' in the 'counter-
      clockwise' direction.  That is, if following an interior edge,
      they would move counterclockwise.  Fireflies rotated clockwise.
      The rotation for each is now selectable in the editor.  I suggest
      that these 'rotation' parameters be kept the same in your own
      levels for the sake of consistency for the player.

     Certain walls are now 'unstable' for rocks and diamonds.  If 
      a rock or diamond is sitting on a corner of this type of wall,
      it will fall off the edge.  This can cause compatibility problems
      with older caves which assume this isn't going to happen.  

     Permanent wall now has its own selectable color, and its imagery
      has been changed.

     Boulders can now be colored.  Three tinting options are available
      from the editor, and the tinting colors can be selected by the
      user.

     Regular wall now has its own selectable color.

     The color of semi-permeable walls has changed.  It's orange now.
      It was blue in version 0.9.

     Diamonds now fall through semi-permeable walls the same way as
      do rocks.

     Boulders fall a little differently.  Version 0.9 permitted them
      to fall 'diagonally'.  However, in this version they move left
      or right and then drop directly downward.  This change was made
      to comply better with the C64 version's behavior.  In general,
      this doesn't cause serious compatibility problems since the
      conditions for falling are pretty much the same.
      
     There is now a vertically-growing wall object similar in
      function to the horizontally-growing wall.
      
     Another new object, "Homocide Box," has been added.  This object
      must be protected as if it were the player.  If destroyed, it
      will cause the player to be killed immediately.  It is prone
      to the same dangers as is the player (ie, falling rocks,
      explosions, butterflies, etc.)

     Keyboard input can now substitute for joystick movement.  The 
      Cursor keys emulate joystick directions, and the shift key 
      represents the fire button.  Either may be used interchangeably
      during gameplay.

  File passwords can be used to keep others from viewing your
      cave files.

  Cave codes have been added.  The password is shown at the
      bottom of the screen when the cave title is shown.  Typing this
      password into the 'Code' box in the game window (before play
      begins) will select that level to be the first encountered during
      play.

 Oh yeah -- there's a  cave editor now, too.  Users no longer need
      to edit the cave file in a textual format.  All editing and 
      parameter manipulation is done through the editor functions.
      Naturally, the editor was contructed with the help of OS2.0's
      splendid gadtools.library.

 Contents

INSTALLATION

No ASSIGNs, fonts, or special libraries are needed to run this program.
All that is required is that the program files exist in the same directory,
and that the program be invoked only from that directory (or by its 
Workbench icon).

These are the files you need to have:

     abd
     abd.info
     abd.guide
     abd.guide.info
     abd.snd
     abd.txt
     abd.16
     abd.ed
     abd.ts
     abd.mod

Additionally, there must exist a subdirectory 'caves' in the same directory
as the game files.  This subdirectory must (or will) contain all the cave
files you wish to have accessible.  Cave files always end in '.caves'.  There
are three cave files provided with this release:

     Original.caves   (these are enhanced caves from version 0.9)
     BDash_I.caves
     CKit.caves

 Contents

OVERVIEW

When you run the program, a window appears on the Workbench.  This window
is often referred to as the "startup window" in this document.  The main
purpose of the window is to allow you to  select a cave file to play (each
file may contain many unique caves).  You may only select one cave file
at at time.  Note that selecting the cave file (by clicking on its name
in the listview gadget) will cause the program to attempt to load the 
cave file into memory.  Any other currently loaded cave file (including
work left in the editor) will immediately be unloaded.

There are several button gadgets in the startup window:

     Play
        This gadget, when not ghosted, begins play of the chosen
        cave file.

     Editor
        Use this gadget (again, only when not ghosted) to edit
the selected cave file.  This invokes the  cave editor.

     New
        This gadget will create a new cave file and automatically
open the  cave editor screen.

     Quit
        This button, or the startup-window close gadget, will
        quit the program.

In addition to these gadgets, there are two text-entry gadgets.

     Password
 File passwords must be entered here.  Cave files which
        require a password are not editable unless the correct
        password has been entered.

     Code
Enter a  cave code (appears during gameplay with the
        name of the level) to start play on any level you
        like. 


After you click 'Play', you get the game title screen.  Press any key or
the joystick trigger button to continue.  The next screen appears with the
title of the first cave.  Again, press a key or the joystick trigger.
You'll then begin play on the first cave.

At the bottom is shown:

    CAVE xxx    the current cave level number
    NEED xxx    the number of diamonds still needed to finish the level

    TIME xxx    the time (seconds) you have to complete the level
    xxxxxxxx    your score    

During gameplay, the following keyboard commands exist:

    SPACE        pauses the game
    ESCAPE        leave the game;  returns to the Workbench window
    RETURN        commit suicide -- restarts the level
    cursor keys    enulates joystick movement
    SHIFT keys    emulates joystick firebutton

The idea is to get the number of diamonds indicated before time runs out.
To do so, you move around with the joystick, avoiding obstacles and threats
while maneuvering to collect diamonds.  When you have enough diamonds to
leave the cave (you will hear a 'snap' sound and the screen will flash),
you must find the exit symbol and move into it.

At the end of a level, your time bonus is calculated and added to your score.
You then proceed to the next cave.  Simple, right!?!

At any time during gameplay, you can press the escape key to back out to
the title screen.  Pressing escape at the title screen returns you to the
Workbench window.

 Contents

KNOWN BUGS

     Blitter access for other tasks will be blocked during gameplay.
      This will cause programs which try to render graphics to sleep 
      until you leave gameplay (and return to the editor or Workbench
      window).
      
     The current version will not work properly on machines without
      FAST memory.  The program must be loaded into FAST memory to
      run quickly enough to provide adquate game speed and a stable
      double-buffered display.

 Contents

CONTACT:

Jeff Bevis
618 Ash Street
Beech Grove, IN  46107

Internet:  bevis@ecn.purdue.edu

Generally, the best way to reach me is by email except during the summer
months.  At that time, my net access is limited so you should contact me
by snail-mail.

Feel free to mail me your own cave creations;  I would love to collect
caves YOU have created and release them as part of a (free) compilation
in the future.  Let's see what we can do with this thing!

     Suggestions are the best way to get changes.

     Monetary contributions greatly enhance my motivation!

 Other credits     Contents

FILE PASSWORD PROTECTION

It is possible to prevent others from editing your cave files by adding
a file password.  To add such protection, simply type in a non-empty
password name in the password box in the  cave selector window and save
the cave.  Others will not be able to edit your file unless they have the
correct password.

Keep in mind that it's not very useful to have a file password unless you
also select encryption to be used, too.  The cave file format is readable
text unless it is encrypted.  Be careful, though!  If you save your file
in encrypted form, and then forget your password, you will have no way 
to recover your file!!  Because of this potential for disaster, I suggest
you always keep one copy of your cave file in non-encrypted form, and
save with a different filename when generating the encrypted copy.  To do
this, just change the file name in the  cave selector window (the old
file will not be deleted unless you tell the program to do so).

Note please that the file password is an entirely different thing than 
the  cave codes.

 Contents

THE CAVE EDITOR

In the previous version, the only way to create a cave was to type it into
the cave file by hand.  No more!  The cave editor supplied with this release
makes creating your own levels almost as easy as playing them!

The editor features allow you to do the following things in a friendly,
reliable environment:

     Remove caves from a file
     Change the play order of caves in a file
     Create new caves in any editable file
 Add  password protection to the file
     Draw cave maps in a "paint" fashion
     Adjust a plethora of parameters on a per-cave basis:
         Time limits
         Graphics
         Colors
         ... and more
 View  cave passwords

The Amiga Boulder Dash cave editor is a part of the game program itself.
You may choose to edit existing cave files, or create your own from
scratch (by selecting "New" from the startup window).

There are several windows associated with the cave editor; none of these 
windows appear on the Workbench (like the startup window).  Instead, 
a separate screen is used.  The height of this screen is usually a little 
over 210 lines, which makes it a little taller than a normal NTSC screen.
Normally this will not cause any problems.  The windows which comprise
the editor are:

  Cave selector
  Visual editor
  Color palette
    Cave info  

Saving of the edited caves (probably the most important feature!) is
accomplished in the cave selector.  See the Cave Selector section for
more information on how this is done.

There are several design rules to keep in mind when using the cave
editor to make your own caves.  Please see the  designing caves section
for more information.

For examples with the cave editor, the BDash_I cave file has been left
unencrypted and without a file password.

 Selecting cave file     Contents

DESIGNING CAVES

Cave designers should heed the following design criteria:

     ALWAYS BOUND MOVABLE OR MOVING OBJECTS WITH PERMANENT WALLS
      This is the single most important characteristic of all
      good caves.  No objects such as the player, butterflies or 
      fireflies, growing walls, diamonds or rocks, or anything
      else which moves, should ever be allowed to get to the edge of
      a cave.  Explosions must never center on the very edge of caves,
      and this design rule keeps that from happening.  It is OK to 
      have non-moving objects on the borders, however, like limbo
      or non-permanent walls.  Non-permanent walls are NOT a good
      bounding device, though, since they can be destroyed by any
      explosion which then leaves the cave borders accessible to 
      moving objects.
      
      One final warning here:  If you don't follow this rule, and 
      something moves to the border of the cave, the object may be
      able to move OUT OF THE CAVE.  If this happens, expect weird
      results and POTENTIAL CRASHES.  You were warned!!

     Allow a little extra time on each level.  Some machines run
      a little slower than others, and not everyone plays as well
      as you do, so you should add at least 10% extra time than
      is actually necessary to complete each level.
      
      One 68000 machines, game play is currently about 1/8 slower
      than on '020 an above processors.

 Cave editor     Contents

SELECTING A CAVE FILE

Select a cave file from the Workbench game window (the first one which opens
when you run the game).  To do this, you simply click on one of the names
in the list at the left side of the window.  If this list is empty, you may
not have a caves subdirectory in the main game directory, or you may not
have any caves in that directory.

If there is any problem loading your selected file, it will be displayed in
the text box at the top of the window.  Otherwise, you may then play or 
edit the caves in that file.  (to edit, you may need to enter a file
password first, if it is required)

Information about the cave file is shown at the bottom of the window.

     Author
        The name of the author of the currently loaded cave file.

     Date
        The last date of modification of the cave file.

     Version
        The version number of the cave file.  Higher numbers
        indicate later versions.  Numbering begins with 1 (one).

     Encryption status
        Cave files may be encrypted.  The status of the currently
        loaded file is shown to the right of the version number.

 Contents

CAVE SELECTOR

The Cave Selector is the first of the editor windows.  It presents a list
of the caves contained in the current file (listed in play order from top
to bottom).  You may rearrange the play order with the move up/down gadgets,
add a new cave, or edit an existing cave.  To edit, select the cave you

VISUAL EDITOR

The visual editor is the primary work window for the editor package.  It
provides a graphical (scrolling window) display of the currently selected
cave (which was selected in the cave selector).  In this part of the
editor you may redraw the cave by adding or removing any game objects you
desire.

Most of the gadgetry should be self explanatory.

Special keycode operations in the visual editor:

     cursor
        Cave window scrolling, same effect as using the sliders
        at the sides of the window.

     SHIFT+cursor
        Jump to an edge of the cave.  For instance, the 
        SHIFT+cursor_up combination would show the topmost
        visible portion of the cave.
        
     ALT+cursor
        Shift the entire cave by one position in the specified 
        direction.  This is useful in centering or adding space
        to a cave early on in its development.  Note that the
        portion which is shifted off of the other side of the
        cave 'rotates' around to the other side.  This makes
        the shifting operation lossless in that no cave
        information will be lost during shifting.

Mouse functions:

     Left mouse button
        Pressing this mouse button inside of the cave window will
        'paint' the currently selected object at the pointer's
        position.  You may draw single positions, or you can drag
        the mouse over an area, drawing the object throughout.

     Right mouse button
        This button provides a limited undo.  The previous drawing
        operation may be removed with this feature.  Only drawing
        performed with the mouse may be undone.  (shift operations
        or sizing operations can't be undone.)

TESTING CAVES

The cave can be easily tested during development.  The "Test" gadget
begins gameplay with the current cave.  Pressing escape during testing
returns to the editor.  Note that when (and if) the player enters the
exit box (completing the level) during test play, you still have to
press escape to return to the editor.  This is done to permit viewing
the results (score, etc) if needed or useful.

 Contents

CAVE COLOR PALETTE

The palette window permits you to adjust colors for the following items
on a per-cave basis:

     Diamonds
     Boulders
     Dirt
     Butterflies
     Regular walls
     Permanent walls

The features of the palette window are:

     RGB color sliders
        Adjust the currently selected color

     Color operations
        Spread, Copy, and Exchange colors

     Color gadgets
        Rectangular samples of each color.

     Gadgets to select boulder and diamond characteristics

One color is selected as the "current" color at any given time.  This color
will have its red, green, and blue values shown in the color sliders.
Adjusting the sliders will adjust the currently selected color with
immediate visual feedback.  To select a different "current" color, simply
click inside the gadget for the desired color.  The currently selected 
color will always be marked by an "X" in its gadget.

Most of the color gadgets in the window represent single colors.  The
diamond and butterfly gadgets, however, represent sixteen colors each.
Both of these gadgets actually represent color-cycle sequences.  When
selecting colors in these gadgets, the "X" marker will appear on top of
one of the sixteen colors in the gadget (this is the selected color).

Colors may be copied with the "copy" gadget.  The currently selected color
will be copied to another location if the user clicks "copy" then the 
destination color gadget.  The exchange operation is similar in operation,
except the destination color replaces the source.

The Spread operation applies only to the sixteen-color diamond and
butterfly color gadgets.  It produces smoothly-graded color transitions
between any two arbitrary colors in a single gadget.  To use do this,
first select a color at one end of the range to be affected.  Then, click
"spread" and subsequently the color at the other end of the range.


BOULDER TYPE

This gadget selects one of three types of boulders to use with the cave.
The three possible selections are:

     Monochromatic
        Gray boulder which looks like the version 0.9 boulder.

     Boulder color tinted
        Tinted boulder;  The tinting color comes from the color
        gadget at the top of the palette window.  Shading on
        the boulder is automatically generated.

     Tinted + Wall Highlight
        The boulder is again tinted, however, it also has a
        second color highlight in its brightest area.  The 
        color used is the same as for regular walls.

DIAMOND TYPE

This gadget selects the shape of the diamond for the cave.  There are 
several possibilities.  Most of the shapes use only the diamond color
cycle, however, there are "two-color" diamonds which use both the
regular diamond color sequence AND the butterfly color sequence.  

 Contents

CAVE INFORMATION

This intimidating window has a bazillion sliders and gadgets to change
every possible cave parameter:

     Cave width (4 to 64)
        Width of the cave map

     Cave height (4 to 48)
        Height of the cave map

     Max amoeba (0 to 100%)
        Maximum portion of the cave map the amoeba may occupy
        before turning into rocks.

     Amoeba growth (0 to 100%)
        Normal rate of amoeba growth.  100% is fastest growth.

     Amoeba flood
        Rate of amoeba growth after "amoeba time" has elapsed.
        (see below)

     Permeability
        Rate which boulders and diamonds penetrate permeable
        walls.  100% is fast.

     Time limit (5 to 750)
        Time allotted to finish the level.  Roughly in seconds.

     Amoeba time (5 to 750)
        Amount of time during which the amoeba grows at its
        regular rate.  Afterwards, it grows at the flood rate.

     Milling time (5 to 750)
        Amount of time the magic walls will mill diamonds and
        rocks after they are first activated.

     Diamonds needed (0 to 500)
        Number of diamonds required to complete the level (the
        exit activates when the player collects this number of
        diamonds).

     Diamond points (-500 to 500)
        Points received for each diamond prior to acquisition
        of the number needed for completion of the level.

     Greedy points (-500 to 500)
        Points received for each diamond after the player
        has collected enough to finish the level.

     Time bonus (-500 to 500)
        Score bonus given for completing the level.

     Intermission bonus (-1000 to 1000)
        Score bonus given for successfully completing an
        intermission level.

     Intermission checkbox
        Selects whether the cave is an intermission level.
        Intermissions are different only in that the player
        continues to the next cave if killed, rather than
        starting the same level again.

     Cave name
        The name of the cave (displayed before playing the
        cave).

     Butterfly rotation
        Direction the butterfly will traverse around an interior
        edge.

     Firefly rotation
        Direction the fireflies will traverse around an interior
        edge.


In addition, the following information for the cave is shown, but cannot
be changed in the info window:

     Ordinal number of the cave in the list of caves for the file,
      beginning with one.

     Password code for the cave (automatically generated)

 Contents

CAVE CODES

Cave codes permit the user to start gameplay with any cave in
a cave file.  The cave codes are different for each cave file, and
must be acquired in one of two ways.

     Either by playing the cave file, and recording the passwords
      for each cave you encounter, or:
      
 The  cave editor info window provides the cave author with
      the cave code.

The level is entered in the startup window "Code" text gadget.

NOTE that cave codes are a different thing than  file passwords.  The file
password controls editing access to the cave file.  Cave codes are for 
the player to use when playing the cave file.

 Contents

