Document DungeonMap V2.2 documentation DungeonMap V2.2 =============== 1991-94 © Bill Elliot 727 94 Ave SW., Calgary, Alberta T2V 0X8 Disclaimer ---------- DungeonMap is provided "AS IS" without warranty of any kind, either expressed or implied. By using DungeonMap, you agree to accept the entire risk as to the quality and performance of the program. Bill Elliot will not accept any liability for this product. 0. Important ============ 0.1. A Programmer's Plea ------------------------ DungeonMap is shareware. If you find this program useful, please send $10 to: Bill Elliot 727 94 Ave SW., Calgary, Alberta T2V 0X8 Even if you think that DungeonMap is terrible, I would appreciate a letter giving me CONSTRUCTIVE ideas on how I can improve it. Please promote the shareware system by making a contribution to the authors of the shareware products you commonly use. There are many advantages to the shareware system: -- You can receive quality programs at a decent price. Had this been a commercial program, you could expect to pay at least $19.95. -- You can thoroughly examine a shareware program before reimbursing the author. Once you've bought a commercial program, you're stuck with it. -- You promote the creation of a number of exciting and diverse programs that would otherwise not reach the public if commercial marketing was the only alternative. Along with your $, please send your name, address, and the version number of DungeonMap that you are currently using. This can be found by displaying the About requester located in the Project menu. 0.2. Legal Bits... ------------------ Now, for the legal stuff. You don't need to read this unless you plan on uploading, distributing, marketing, or stealing DungeonMap... DungeonMap is Copyrighted 1991-94 by Bill Elliot All Rights are Reserved Worldwide DungeonMap is freely distributable as long as all the following conditions are met: 1) All the files must be included in their original form without additions, deletions, or modifications of any kind. Any such modifications must appear in separate files. 2) All copyright notices must remain intact. 3) DungeonMap may not be sold commercially alone, or as a component in another product. 4) DungeonMap may not appear on shareware or public domain disks for which the consumers are charged more than a nominal disk copying fee of seven dollars (US $7) per disk. 5) DungeonMap may not appear on any electronic service which charges more than the basic access fee to download DungeonMap. 6) DungeonMap may not appear on any electronic service that claims copyrights to uploaded programs, either alone or as part of a collection. If you would like a variance to any of the above conditions, please contact me for written permission. 0.3. Another Way to Contact Me + An Ad -------------------------------------- I am also on the Amiga Users of Calgary (AMUC) bulletin board on a fairly regular basis. This is the first BBS to use the full power of the Amiga's ability to multitask. Some of its features are: - It has a mouse and pull-down menu driven interface. - A 2.0 look and feel. - Can download, upload, read your messages, take part in an on-line conference ALL AT THE SAME TIME. - While a file is downloading, and you see another file you want, you can just add it to the list to be downloaded. - There is also an off-line reader available for it, with the ability to do off-line responding. You can use a regular ASCII terminal package to access VBBS initially to get a copy of the special required terminal package. This term package is what gives all the above features. Just look for a file called IceTERMnnn.LZH. The most current version, as of this writing, is IceTERM115.LZH. The most current version of the off-line reader program is called IceOLR31.LZH. The phone numbers to call are: (403)282-5171 (403)282-5137 (403)289-1882 (403)284-5624 (403)282-5238 (403)282-5224 (403)289-1794 My Internet address there is: Bill_Elliot@amuc.mtroyal.ab.ca 0.4. Requirements ----------------- This software was written and tested on AmigaDos version 2.04, and uses the features of version 2, such as: Gadtools, ASL, etc. So you require 2.04. If you are still using V1.3, GET V2.04 or higher as they are light years ahead of V1.3. 1. Using DungeonMap ------------------- DungeonMap is intended to be used as an aid to Dungeon Masters (DM's) © TSR for creating dungeons for use in Advanced Dungeons & Dragons (AD&D) © TSR. But, you can use it for what ever you like. The legend says "Door" and "Arch." But, these can be interpreted any way you please (E.g., Door's could be locked or secret doors, and Arch's could be open or unlocked doors). Just use your imagination. For the most part the program is self explanatory. I'll just cover some of the more subtle points and features. 1.1. Loading Saved Maps... -------------------------- DungeonMap will first look for a directory (in what ever directory you run DungeonMap from) called DungeonMapData. If DungeonMapData is found, DungeonMap will display the files in this directory. Otherwise, it will display the files in the current directory. NOTE: All files saved by DungeonMap are forced to have a suffix of ".DAT". Therefore, only files ending in ".DAT" are displayed. This helps save some time scrolling through other unrelated files. As the dungeon data is loaded, messages are displayed in the drag bar after every 100 nodes are loaded. This gives you some idea of what is happening during those long loads (E.g., a 1400 node map). 1.2. Saving Maps... ------------------- The same procedure as above is used for selecting which directory to display files from. But, this selection process is only for the first save or load. The requester will keep the directory you may change it to (at least till you quite the program). 1.3. Choosing a Map format... ----------------------------- This allows you to choose the style of map to generate. You can choose a dungeon style that is irregular in shape. Or, you can create a town, which is rectangular, and where you can control the straightness of the roads (among other things.) 1.4. Creating new Dungeons... ----------------------------- This is really what you're here for. You will be presented with a requester which asks how for the size of dungeon to create and how you want it created. (I.E., What proportion of the exits will be OPEN, WALLS, DOORS, and ARCHS). The total of these proportions must equal 100 or the OK gadget will not be available. Just a warning on size. I would not try anything larger than say 2000 nodes. Even this will take a fairly long time. If you get tired of waiting for the dungeon to be completed, or you feel enough dungeon has been created, then the process can be stopped. Just select the "NEW MAP" option again. You will notice that while creating a map the "NEW MAP" option will read "STOP MAP". Here are a couple of the messages you will see displayed in the drag bar, while the Map is being created. They, and their meanings are as follows: "Creating dungeon of xxx nodes. yyy nodes created." This is just a progress report saying that xxx nodes of the requested yyy nodes have been created. You will also see the dungeon being drawn as it is created. "No undefined exits. Choosing a new start point for dungeon generation..." If there are no more undefined exits, a new one is created, at random, on one of the outside edges. Then the dungeon creation will continue from that point. 1.5. Editing the Dungeon... --------------------------- Just click the mouse in the middle of a wall, door, arch, or opening to change it to the item selected under menu item "Change to". The selection process looks at each node as if it had been divided into 9 grids, and selects the exit based on the gird it is in. This is easier to visualize with a picture. So.... Exit +-----------+ | |XXX| | <------- Entire square is a node on the map. | |XXX| | |-----------| Exit |XXX| |XXX| Exit |XXX| |XXX| |-----------| | |XXX| | | |XXX| | +-----------+ Exit If you try to create an exit on an undefined node, the node will be made defined (I.E., turned gray). If this was an accident and you want the node to be undefined (I.E., white), then just select "Change to - Erase" and click the mouse anywhere on the node. Also, see the section on `Map centring...'. 1.6. Creating new Towns... -------------------------- The requester will ask for the width and height of the map. These values must be an odd number. The maximums are calculated based on the size of the screen. This is controlled by the amount of overscan you are using, and whether interlace option is turned on. Then there are 3 controls for streets. The straightness must be between 1 and 99%. The straighter the streets must be the slower the town creation will be. The other 2 street controls (Start at wall, & Start at courts) control where the streets begin, and how many there are. The limits on these values vary depending on the size of the town (the larger the town the more streets there can be). The final 2 controls control the number of Gates into the town there will be (upper limit is less than or equal to the number of streets starting at the wall), and the number of unused nodes in the town (e.g., pillar, rock, etc.). Again these are limited based on the size of the town. The generation of a town can be stopped in the same way as with a dungeon map creation (select STOP MAP). But, this option is only checked between major steps of the town creation (I.E., it may not be as quick to respond). In a future release I'll probably make this more responsive. But, it will probably slow down the creation of the town. I would very much like to thank Kent Paul Dolan for presenting his algorithm for creating a town map in his program TownMaze. 1.7. Editing the Town... ------------------------ Editing towns is easier than dungeons. The nodes contain only one object (a wall, open space, or door). There is no need to select a specific portion of a node. The entire node is changed to the selected type. Note: You cannot edit the portion outside the outer wall of the town. To do this, create a town larger than you need, and erase the portion you don't need. Also, see the section on `Map centring...'. 1.8. Creating random Items/Events... ------------------------------------ The requester will ask you how many Items/Events you would like generated. The maximum allowed is the lower of all Item/Events available and 20% of the available map nodes. That's all there is to it. 1.9. Editing the Items/Events... -------------------------------- Select the Edit option "Change to - Item/Event", and then choose the Item/ Event option you wish to place. Now each click of your mouse will place one of these on the map, up to the limit you have set. The number you have left to place is always displayed in the menu beside the Item/Event option. To remove an erroneously placed Item/Event select the Item/Event option "Remove Item/Event", and click on the offending Item/Event. 1.10. Changing the Items/Events Menu... --------------------------------------- The Items/Events displayed in the menu are read from a file called "ItemEventList". This file is looked for in the directory where your maps are stored. The initially directory is assumed to be "DungeonMapData" below where DungeonMap is found. The file is reloaded fresh before each random generation, or file load. Also, Items/Events in the map file are read first, before the ItemEventList file. The format of this file is: A,B,CC,DDDDDDDD Where A - ASCII letter to use for representing this on the map Note: It is not a good idea to use upper and lower case letters that look the same. They can be hard to tell apart, unless they are used in different types of locations. B - Type of location this Item/Event can be placed on ( F=floor, O=opening ). C - Maximum number of this Item/Event that you would like in a map. D - 16 character description of the Item/Event. Essentially the remainder of the line, up to 16 characters. The description can contain spaces and special characters. 1.11. Map centring... --------------------- If the centre map option is turned on, all maps created or loaded will automatically be centred on the screen. No changes are made to the actual map information. It is just drawn centred. This centring will effect your ability to edit the map. For example, if the map is shifted left the nodes on the right part of the map will not be available for editing. To de-centre a map just turn off the option, and select the "Edit" option of "Redraw". 1.12. Choosing the size of the print... --------------------------------------- There are 2 sizes or formats for printing the maps. The first, I call "Fixed Size Node", has all maps (regardless of size) having each node printed the same size. The second format is called "Max Node Size". This prints the map as large as will fit on the paper (paper size is controlled via Preferences). 1.13. Printing the map... ------------------------- While the dungeon map is being printed, you sometimes want to cancel the printout. This could be because you chose the option by accident or because it is taking too long (due to the print density chosen). Well, this is no problem. While a dungeon is printing the print option will read "STOP PRINT". Just select this option again and the print will be stopped. This should happen immediately. The only output that should still be printed is just what is already in the printers internal buffer. The maps (dungeons & towns) are all printed in the background. So, while it is being printed, you can continue with loading, or creating new maps. The printing controls for DungeonMap are all controlled through your preferences (set through Workbench). Note: that B/W gives a much better print out over gray scale, and that density 2 is usually good enough (At least it is on my printer. Your quality may vary). 1.14. Displaying the legend... ------------------------------ The legend is an option, that when selected, will display a small window. The window contains a color coded legend for the maps. Just so you can keep it out of your way, this window can be moved to anywhere on the screen, The legend will not be printed if it is displayed. 1.15. Exiting from DungeonMap... -------------------------------- If you are printing, creating a new map, or haven't saved your most recent creation/change, them you will be told this, and asked what you wish to do about it. I believe in graceful exits. 1.16. Rexx Commands... ---------------------- To use ARexx to access and manipulate DungeonMap there are only a few things you need to know, besides how to use ARexx. The first is the name of the port or 'ADDRESS' for DungeonMap. This will be the string 'DungeonMap' plus a single digit. The first execution of DungeonMap will have an address of DungeonMap0, the second will be DungeonMap1, and so on, up to DungeonMap9. If you need more than 10 copies of DungeonMap running at one time, CALL ME. I'ld love to know what you are doing. The second think you need to know is that you must use the ARexx command "OPTIONS RESULTS" to turn on the ability to get information from DungeonMap. With this done the DungeonMap commands "Info" and "WhatIs" can return you the requested information (see below for details). The last major thing to know is to ALWAYS eith use "FAIL AT 10" at the start of your ARexx or check RC after EVERY command to ensure success. The values that RC may have after a DungeonMap command are as follows: 0 - Everything is fine. 10 - The command failed to do what you asked, or a requester was presented and you canceled the operation. 20 - You passed an invalid argument or are missing an argument for the command. Check the command syntax again. 100 - DungeonMap doesn't know this command. Check the spelling. 200 - Major system failure (e.g. out of memory, menus couldn't be constructed, etc.). This is usually accompanied by a requester telling you what is wrong. Now just a few words on the syntax format I'll be using for the rest of this section. If there are 2 or more values separated with a slash (/) then this is a list of options, and only one is returned or needed. A value in round brackets is an actual value. There are only 3 of these - (x) - An X offset on the DungeonMap in nodes. (y) - A Y offset on the DungeonMap in nodes. (ItemSymbol) - A character you have assigned to an Item/Event via the file "ItemEventList". These can also be seen in the Item/Event menu. Or, this may be blank if you wish to erase Item/Events. Well with that out of the way, here are the available commands: 1.16.1. Information Retrieval Commands -------------------------------------- Info - Returns a single string in RESULT with the following info. Interlace/Non-Interlace AutoCentre/NoAutoCentre Fixed/Max Dungeon/Town (x) (y) Open/Wall/Arch/Door/Item/Erase (ItemSymbol) Interlace/Non-Interlace - Screen Mode AutoCentre/NoAutoCentre - Is the map being drawn centred on the screen Fixed/Max - Print Size Dungeon/Town - Map format selected (x) (y) - Maximum size of screen in nodes. You may draw between 1 to (x) and 1 to (y). Open/Wall/Arch/Door/Item/Erase - The thing to be drawn with the "Draw" command. (ItemSymbol) - If the thing to be draw is an Item/Event then this is the Item/Event that will be drawn. WhatIs (x) (y) Floor/North/East/West/South - Returns what is in the map at a specific location, and optionally a direction. If no direction is given, then the floor is assumed. In Dungeons the floor is only usefull to get the Item/Event. This command returns the following info. Open/Wall/Arch/Door/Floor/Undefined (ItemSymbol) 1.16.2. Options Setting Commands -------------------------------- These commands mirror there menu counter-parts. For more information see their descriptions above. AutoCentre On/Off Format Dungeon/Town Interlace On/Off PrintSize Fixed/Max 1.16.3. Map Manipulation Commands --------------------------------- This is the real meat of the system. This is where you can start to change the maps you have created, or create them using your own methods. ClearMap - Clear the screen for a new map. ChangeTo Open/Wall/Arch/Door/Item/Erase - Change the thing you are going to be drawing Draw (x) (y) Open/Wall/Arch/Door/Floor - Draw the above at location (x) (y) Direction is only useful for Dungeons. Towns ignore direction. ItemEvent (ItemSymbol)/blank - Change the Item/Event to be drawn. Load (Filename) - Load up the map called (Filename). NewItemEvents (n) - Generate (n) random Item/Events. The maximum for (n) is the lower of 20% of the non-wall nodes, and the number of ItemEvents available. Print - Print the displayed map. No need to wait for DungeonMap to complete printing, as a copy is made for printing. SaveAs (FileName) - Save this map as (Filename). Quit - Just like it says, quit out of DungeonMap. 2. History & Future Plans ------------------------- History ------- V1.0 - First release with dungeons only.. V1.1 - Creation of town type maps with streets, buildings, and town squares. - Allow background printing of one map while the next is being created. - Improved the speed and quality of the creation method. - Added a title to the printout. - Allowed for 2 types of printout (Fixed node size, and maximum node size) - Automatically adjust window size to your overscan settings. - Moved the legend into an optional window to make more room for drawing. - Some internal restructuring to ease future additions. - The format of the saved dungeon files, has been changed. DungeonMap will still read version 1.0 format dungeon files. But, it will save them in the new format. To avoid future problems, please load and save all files you may have created using DungeonMap V1.0. - The default data directory was changed from "DATA" to "DungeonMapData". There were just too many programs looking for DATA. - The auto-centre option, and the centre edit command no longer modify the actual map data. It only modifies how the map is displayed. - Program now contains a version string. So you can find the version of DungeonMap by typing "VERSION DungeonMap". - This will be the last version that will save or print without registering. I don't like doing this. But, not enough registrations are being sent in. To those who did, my heart felt thanx. You will notice some of your ideas were added to the list V2.0 - This version forward REQUIRES ADOS 2.04 or higher. - Convert to ADos 2.0 ASL.LIBRARY from REQ.LIBRARY. - Convert appearance to conform to 2.0 style guide. - Add ability to lay down a series of walls, instead of single wall nodes. - Convert requesters to use sliders for easier input, and NO error message as you cannot enter invalid values. You can also more easily see the maximum allowable values. - ALL gadgets on these new requesters are keyboard controllable. - Small addition to the saved files. This release will still read the old format, but will only write the new format. To avoid future problems, please load and save all files you may have created using DungeonMap V2.0. - Added an option to toggle interlace mode on and off. - Modified the node hot spots for dungeons. This was needed to allow for the laying down of walls. - Added the ability to just start editing with no map loaded. Just start drawing to un-ghost the menu items. - Added more Right-Amiga commands. - Fixed a number of small bugs found. V2.1 - Allow the random creation and editing of encounters in dungeons & towns. These encounter descriptions can be specified by the user & the user can specify a maximum number of occurances for a map. - Added more Right-Amiga commands. - Fixed a number of small bugs found. V2.2 - Add a REXX interface to control editing via Rexx macros. See the documentation for a list of the 15 available commands. - Fixed a problem with drawing in Town type maps. - Added reading the screen configuration prefs. The screen will now auto- configure to the same as your default public screen (frequently this is just Workbench). Future plans ------------ I have a lot I would like to do with DungeonMap. The following are a few of my ideas and a rough grouping of them into releases. This is only tentative. So if you would like to see an option sooner, or have any other ideas, just drop me a note and I'll see what I can do. V2.3 - Create Icons for data files, and allow starting of DungeonMap from the data file Icon. - Save the configuration options in the program & project Icons. V2.4 - Allow for maps that are larger than a single screen. This will require the ability to scroll the map on the screen. - Add a zoom feature to enlarge sections of the map. - Add ability to insert previously designed maps or map portions. - Maybe, add ability to have roaming monsters, to simulate random encounters. - Additional ideas that people may request.