@DATABASE "MazeMania AmigaGuide Documentation"
@WORDWRAP
@NODE MAIN "Introduction"
@{b}----- Introduction -----@{ub}


   @{b}MazeMania@{ub} v1.15, written by Daniel Pink in BlitzBasic ][

   This program is MailWare.  See @{" About the Author " link ME} to see what this involves.

   @{b}MazeMania@{ub} is based around an algorithm for creating random mazes, with the following features.

o  Mazes have one entry point and one exit point.
o  Mazes have only one route through.
o  All parts of the maze are accessible.
o  Mazes can be created up to sizes of 1000x1000, memory permitting.
o  Mazes can be saved, optionally using a packed format.
o  Mazes can be loaded, automatically recognising packed format.
o  Mazes can be viewed in a 2D format.
o  The 2D bitmap can be stored as an IFF bitmap file.
o  Mazes can be explored in a 3D view.
o  A progress indicator can be used for time consuming operations.
o  Configuration can be stored in the icon.
o  Many keyboard shortcuts.
o  @{b}FREE@{ub} ( <------ Probably the best feature ;-)
 
          @{"    Requirements    " link REQUIREMENTS}
          @{"      Buttons       " link BUTTONS}
          @{"       Menus        " link MENUS}
          @{" Keyboard Shortcuts " link KEYSHORT}
          @{"   Configuration    " link CONFIG}
          @{"    Memory Usage    " link MEMUSE}
          @{"  Acknowledgements  " link THANX}
          @{"      History       " link HISTORY}
          @{"  About the Author  " link ME}
@ENDNODE MAIN

@NODE REQUIREMENTS "System Requirements"
@{b}----- System Requirements -----@{ub}

   System requirements for @{b}MazeMania@{ub} are as follows -

   o An Amiga ;-)

   o Version 2.04 or higher of AmigaDos

   o ReqTools.Library in Libs: directory

   o Gadtools.Library in Libs: directory


   If creating large mazes then there may be some additional @{" Memory Requirements " link MEMUSE}.
@ENDNODE REQUIREMENTS

@NODE BUTTONS "Button Usuage"
@{b}----- Button usuage -----@{ub}


@{b}Create New Maze@{ub} Button

   This is the function that MazeMania is based around.  Just enter values for the width and height, and a maze will be generated to those requirements.  As larger mazes take longer to produce, there is an option of a progress indicator.  The @{" Configuration " link CONFIG} contains parameters relevant to the progress indicator.

@{b}Save Current Maze@{ub} Button

   This allows a maze to be saved to disk.  First a file requester prompts for a file name, and then there is an option to save in a packed or unpacked format.  The unpacked format takes ((NoColumns+2)*(NoRows+1))+8 bytes for the maze, while the packed format takes ((NoColumns+2)*(NoRows+1)/4)+8 bytes.  I.E.  A 100 by 100 maze will use 10310 bytes in the unpacked format, and 2583 bytes in the packed format.  The packing and unpacking process is so fast on my A1200 @28 Mhz that the time taken to pack and unpack is hardly noticeable!

@{b}Load New Maze@{ub} Button

   This allows a previously saved maze to be reloaded.  A file requester prompts for a file name, and then the maze is loaded.  Packed and unpacked formats are automatically recognised.

@{b}View Maze (2D)@{ub} Button

   This allows a maze to be viewed in 2D.  First the maze is drawn to a bitmap, and then a window opens to allow the bitmap to be viewed.  The maze is drawn using the number of pixels per square specified in the @{" Configuration " link CONFIG}.  As large mazes take a while to draw there is an option of a progress indicator.  See @{" Configuration " link CONFIG} for details.

@{b}View Maze (3D)@{ub} Button

   This opens a window and shows a 3D view of the maze, facing south from the start position.  The maze can then be explored using a joystick in the joystick port, or the cursor keys.  The direction faced can be altered by pushing left or right, and backwards and forwards allows a single step, if the way is not blocked!  The view can be altered via the @{" Menu Items " link MENUS} for the 3D window.
@ENDNODE BUTTONS

@NODE MENUS "Menu Usuage"
@{b}----- Menu usuage -----@{ub}


@{b}Main Menu@{ub}

   The @{i}About@{ui} option brings up an about requester, which also gives details about the size and memory usage of the current maze.

   The @{i}Save Config@{ui} option saves the current @{" Configuration " link CONFIG} information to the programs icon file.

   The @{i}Indicator Rate@{ui} option allows the rate at which the indicator is updated to be altered.  The figure specifies the amount of time between updates in ticks.  (1/50th second for PAL, 1/60th second for NTSC)

   The @{i}2D Pixel@{ui} option allows the amount of pixels used by the 2D drawing routine to be altered.

   The @{i}Quit@{ui} option.  Well, who would want to anyway ;-)


@{b}2D Maze Menu@{ub}

  The @{i}Save Bitmap@{ui} option allows the 2D bitmap to be saved to disk as an IFF file.  This can then be read into your favourite paint program for printing, or whatever else you want to do with it.

  The @{i}Close Window@{ui} option closes the 2D Maze window.


@{b}3D Maze Menu@{ub}

  The @{i}Close Window@{ui} option closes the 3D Maze window.

  The @{i}Inside View@{ui} option alters the 3D view to inside the maze.

  The @{i}Above View@{ui} option alters the 3D view to slightly above the maze.
@ENDNODE MENUS

@NODE KEYSHORT "Keyboard Shortcuts"
@{b}----- Keyboard Shortcuts -----@{ub}

   I really hate being restricted to using the mouse, so having to constantly swap between using the keyboard and the mouse.  For this reason I have made sure that every option in @{b}MazeMania@{ub} can be accessed via the keyboard as well.  This probably doesn't make much difference for a program like this, but there are many Amiga programs which just can't be used without encountering this problem (including Workbench).  This is probably about the only useful feature of WinDoze, even if it is a real pane in the glass!  Anyway, getting back to the point, here is a list of the ways things can be accesed via the keyboard -

o All menu items have shortcuts.
o All buttons in the main window can be accessed using the underlined character.
o Buttons in all of the Reqtools Requesters can be accessed using the underlined characters.
o The bitmap for the 2D view can be moved using the cursor keys.
o The 3D view can be explored using the cursor keys.
o The active window can be altered using the TAB key.
@ENDNODE KEYSHORT

@NODE CONFIG "Configuration"
@{b}----- Configuration -----@{ub}


   Configuration information is stored in the icon file.  This can also be written to using the option in the main window.  If no information is present or it is invalid when the program is started then default values are used.  Configuration items are as follows :-

@{b}MAINWIDTH@{ub}=xxx
   specifies the width of the main window in pixels.

@{b}MAINHEIGHT@{ub}=xxx
   specifies the height of the main window in pixels.

@{b}MAINX@{ub}=xxx
   specifies the X position of the top left of the main window in pixels.  Note if this tool type cannot be found then the main window is centred horizontally on the screen.

@{b}MAINY@{ub}=xxx
   specifies the Y position of the top left of the main window in pixels.  Note if this tool type cannot be found then the main window is centred vertically on the screen.

@{b}3DVIEW@{ub}=ABOVE|INSIDE
   specifies which view to use by default for the 3D window.  Only use ONE of the values!

@{b}2DPIXACROSS@{ub}=xx
   specifies the number of pixels to use across for each square when drawing the maze in 2D.

@{b}2DPIXDOWN@{ub}=xx
   specifies the number of pixels to use down for each square when drawing the maze in 2D.

@{b}INDICATORRATE@{ub}=xx
   specifies how often to update the progress indicator.  (10..60 ticks)

@{b}MAZELARGE@{ub}=xxx
   specifies the size in area of the maze at which to use a progress indicator.  This allows the progress indicator to be used when the maze will take a long time to be processed, which will obviously be different for different machine specifications.
@ENDNODE CONFIG

@NODE MEMUSE "Memory Usuage"
@{b}----- Memory Usuage -----@{ub}


   For large mazes the memory usage can be quite intensive.  If you try to create a maze which is too large, or draw a maze which is too large, then the program won't guru, but should exit cleanly, returning ALL memory that was in use.  The current memory usage can be viewed in the About requester.

   A 1000x1000 maze would use 1000*1000 bytes (976.6 K) of fast ram if available, or chip ram otherwise.

   A 1000x1000 maze with 4 pixels across and down per square would need @{b}1953K !!@{ub} of CHIP ram for the 2D bitmap.

   The 3D bitmap used is not dependent on the maze size, but the size of your screen.

   Mazes could be created to a larger size than 1000x1000, this was just a figure I decided upon that seems much larger than is needed, unless you're really sad I doubt you could really be bothered to complete a maze that big!  The only reason for creating a maze that big is to show that it can be done.
@ENDNODE MEMUSE

@NODE THANX "Acknowledgements"
@{b}----- Acknowledgements -----@{ub}


Thanks to

   Acid software for the excellent @{b}BlitzBasic ][@{ub}. (If you haven't got it, then BUY it NOW, its worth every penny/cent/etc!)

   LES (Leading Edge Software) for their update to the @{b}BlitzBasic@{ub} Debugger, and many new @{b}Blitz@{ub} commands.

   Neil O'Rourke for his @{b}Blitz@{ub} commands for the progress indicator, and for access to the ReqTools lib.
@ENDNODE THANX

@NODE HISTORY "Program History"
@{b}----- Program History -----@{ub}

V1.15
   Bug fix.  Somehow while optimising the time taken to create the maze, I managed to stop the maze from saving properly in the packed format.  This has now been fixed (hopefully not introducing any other bugs ;-).
   Bug fix.  Read icon from icon named "DansMazes".  Now checks the name of the program, so you can rename it to whatever you want to.
   Bug fix.  When scrolling the 2d bitmap using the keyboard, vertical movement would cause small horizontal movements, and vice versa.  This has now been fixed.
   The name was altered from DansMazes to MazeMania, as DansMazes seemed just a little bit on the pretentious side!
   Documentation altered to AmigaGuide format.

V1.14
   Bug fix.  Visited Mr Guru if a maze not requiring the progress indicator was created after one that did require the progress indicator.

V1.13
   First release on Aminet.
@ENDNODE HISTORY

@NODE ME "About the author"
@{b}----- About the author -----@{ub}

   My name is Daniel Pink.  I wrote this program during my final year of study at the University of Hertfordshire, England, studying Computing Mathematics.  I can currently be contacted via E-Mail at D.C.J.Pink@Herts.ac.uk , but as I have almost finished studying, this E-Mail address will not be valid after about the end of July 1995.  I plan to get connected again soon, however until then I can still be contacted at the following Snail-Mail address -

26 Elderbek Close,
Cheshunt,
Hertfordshire,
England.
EN7 6HS.

   As indicated in the introduction, this program is MailWare.  I don't expect to make any money from this program, I wrote it for my own amusement, and I realise it was probably a lot more interesting to write than it will be to use.  However, I would appreciate some feedback.  If you're having problems getting it to work, want to express an opinion about the program, have any suggestions for improvements, you want a copy of the BlitzBasic source code, you're just a bit bored, or for any other reason then email me.  Also if you want to use the maze files for a game or whatever then let me know and I'll explain the file format.  Also, if you could let me know the configuration of your machine, as this program has only been tested on my 3.0 Dos A1200, and I would like to know if it works on different dos versions, with graphics cards etc.  In theory it should work on 2.0, but I haven't been able check this yet.
@ENDNODE ME