AtMap3: An Atlanits 3.0 Mapping Utility
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Version 2.24

Document date: 30 Oct 1997

-------------------------------------------------------------
!!!! RULE NUMBER 1 !!!!

If you are upgrading from an earlier version of AtMap3 BACKUP
YOUR DATA BEFORE INSTALLING THIS VERSION !!! 
Do this by coping the entire contents of your DATA sub-directory
somewhere else.
I also suggest backing up your old AtMap3.EXE file in case
you feel inspired to return to that version (you'd have to return 
to your old data at the same time).
Also, create a new sub-directory off the AtMap3 direstory called
TURNS. This is where AtMap3 generated turn files can be put
if you plan on doing that sort of thing.

--------------------------------------------------------------
!!!! RULE NUMBER 2 !!!!

Reading this document will probably help. Then again, it may 
not. Give it a go anyway.

--------------------------------------------------------------

The application AtMap3 is shareware and may be distributed freely, 
as long as accompanied by this document. 
It may not be sold or used for commercial gain (likely, hey :) ). 
Developed by 
    Trevor Tickner, Cape Town, South Africa
    Email: bldsoft@ilink.nis.za

If you wish to make a donation to the AtMap3 development fund, you
may arrange it through Geoff who hosts Atlantis 3.

At the moment, the relevant files may be downloaded from
  ftp://ftp.shore.net/members2/t/twells/atl3/
as Tabor Wells has kindly placed them there for public consumption.


Configuring Atmap3
==================

Create a sub-directory for the program and copy the EXE file 
(ATMAP3.EXE) into it. Create two sub-directories off this 
directory: 
   DATA    which will hold all the map information, and
   IMPORT  which is where you put turn files to be imported into 
           AtMap3
   TURNS   for turn files (yea, really)


Modify the INI file (not necessary if your upgrading your version)
====================
The INI file (ATLANTIS.INI) should be placed in the same directory
as the EXE file. Open and modify the PATH settings in the INI file to 
reflect the directories you have created. The other INI setting are
configured within AtMap3 itself.


Brief Functionality Explanation
===============================

NOTE: Most of the functionality and interaction of the system has
  been described along with the menu item / button which most affects
  that functionality. This was done rather than have a seperate sections
  for describing the general operation and functionality and for 
  detailing how to use the various screens and forms. It may make
  finding some info harder, but, hey, this is a readme not a 
  detailed help file :) For example, to find out how unit info is
  shown on the map, goto the section describing how the menu item
  'View/Troop Selection' works.
  
Screen Layout:
There are 3 main areas to the main screen:
 - The largest area is taken up by the map itself. This can be
   scrolled by the horizontal and vertical scroll bars below and the 
   the right of the map area. 
 - The Global map area: present at the top right corner of the form.
   This shows an overall view of the map. Click on this map to move 
   the large map view.
 - The view options area: found below the Global map. Here you can
   modify settings which affect the main map display. This area also
   extends to the area below the main map, where the 'Key' buttons are
   located.

Settings:
 Update Global Map: when ON, the global map is drawn and updated when
   changes occur. Set it off to speed things up - in particular, 
   AtMap3 will startup much faster if this option is off, as otherwise
   the entire known map needs to be drawn at startup. Also, turn file
   imports will occur faster with this OFF.

 Zoom Map: use the slider to zoom the main map in and out.

 Show: Underworld / Overworld  : pretty self explanatory. Choose to
   view either the overworld or underworld.  
 Show: Hex Coordinates: Whether to show coords in on the main map. 
   Note that if the main map zoom level is too far out, coordinates
   are not shown whether this option is set or not.
 Show: Pop Center Icons: Indicates whether city/town/village icons are shown
   on the map.
 Show: Pop Center Names: Indicates whether city/town/village names are shown
   on the map.
 Show: Gates: shows any known gates info 
 Show: Shafts: shows any known shaft info
 Show: Other: shows 'Other' text entries which can be captured for each
  hex (eg. lairs, crypts, ruins and caves).
 Show: Indicate Unconfirmed: Hex data can be confirmed or unconfirmed,
  depending upon the source of the information. If this setting is ON
  then unconfirmed hexes are shown as hatched colouring,rather than as
  solid colours. (allows one to quickly see which hex info is confirmed)
 Show: Troop Locations: this turns on/off the display of troops on the map.
  See below for more detail on how units are displayed on the map.

Buttons:
 Colour chart: Brings up the hex colour toolbar. See menu description below.
 Icon Chart: Brings up the hex feature icon toolbar. See menu description below.
 Troops : Brings up the Troop Display toolbar. See menu description below.

Turn Display and Navigators
 To the left of the 3 toolbar buttons is a diplay indicating the current turn
 being shown. This is normally the turn of the last imported Turn file, but
 may be scrolled up and down with the 4 buttons on either side of the turn
 number. < and > move back and forward a single turn, while << and >> move
 back and forward 5 turns at a time. Needless to say you cannot scroll forward
 further than your latest imported turn file. 
 Note that the current turn being displayed relates ONLY to unit data. 
 Pop.center, hex, production etc data is always displayed at its most recent
 levels, no matter what turn number you are looking at. Troops, however, will
 be displayed on the map in whatever position and in whatever state 
 they were seen on the turn displayed in the turn display panel.

Menu Items
==========
 
File: 
  Reload Database 
     Effectively un-does all changes to data made since the last save,
     by reloading all the data.
  Save Database
     Save changes

Navigate: 
  Go home: Moves the main map to a coordinate and zoom in level which
     you have specified as 'home'.
  Goto Coordinate: prompts you to enter a coordinate, and then moves the
     map to center on that coordinate.
  Save Position as Home: saves the current X,Y and zoom level at the
     'home' position, to which you jump when you select 'Go home' (and
     when the app first starts)
  Find City: allows you to search for a pop. center by name (or part of
     a name). Type in the text to search for, and if any matches are found
     a list containing all the matches will be shown. Select the city 
     you're interested in and press the 'Goto' button at the bottom of the
     search result form and the main map will center on that pop. center.

View:
  Terrain Colour chart: Brings up a terrain colour toolbar which allows
     the user to specify what colours to use for each terrain type. Note
     that underworld terrain types matching overworld ones are not
     seperately identified : ie. underforest and forest are considered the
     same as far as colouring is concenred.

     Using the Terrain Colour Chart
     ------------------------------
     Most of this form is taken up by hexes representing each terrain type.
     Select the terrain type whose colour you wish to change (by clicking on
     its corresponding hex) and the press then <Select Colour> button. 
     Choose the colour you want from the displayed dialog and press OK. Your
     selected colour will replace the previous one for the relevant terrain
     type. (NOTE: double clicking a terrain hex also brings up the colour 
     dialog)

  Feature Icon Chart: Brings up a toolbar allowing the user to select icons
     and colours to use to represent features on the map such as Cities, gates,
     shafts etc.

     Feature Icon Chart
     ------------------------------
     Use this to change both the icons representing the various features and 
     the colour used to draw them (generally the fill colour).
     The bottom of form lists the 6 different terrain features shown on the
     map. Select the one you wish to change. Then select from the list of 
     available icons the one you wish to use to represent this feature.
     You can change the colour used in the icon by pressing the <Select Colour>
     button of by double clicking on a feature (as for the Terrain Colour
     Chart).

     Most of this form is taken up by hexes representing each terrain type.
     Select the terrain type whose colour you wish to change (by clicking on
     its corresponding hex) and the press then <Select Colour> button. 
     Choose the colour you want from the displayed dialog and press OK. Your
     selected colour will replace the previous one for the relevant terrain
     type.

  Troop Selection: use this option to bring up the troop display 'toolbar'. This
     floating form allows you to select how and which faction units should
     be displayed on the map. 
     At the top of this toolbar, there is a drop down list holding all the
     previosly saved Troop Display Configurations which you may have created.
     Select from this list to swap between them. Use the 'Add New' button 
     and the 'Delete' button to add new or remove existing Troop Display 
     Configurations.
     To build a Troop Display Configurations (TDC), use the 'Add New' button.
     Enter a name for the new TDC and press OK. A new (empty) TDC is created.
     Now, choose whether this TDC is to be built from individual factions
     or from Alliances (see Alliance Maintenance further down for details on
     alliances). To make the list of factions/alliances which are to make up
     this TDC, use the 'Add', 'Remove' and 'Colour' buttons at the bottom of
     the toolbar. Adding to a faction based TDC brings up the Faction Maintenance
     form from which you can select a faction. Repeat this process to add more 
     factions. You can choose a colour to use for the faction withing the 
     Faction Maintenance screen, or by using the 'Colour' button on the 
     troop toolbar once the faction is in the TDC list.
     An alliance based TDC is created in a similar way, execept additions are
     selected from a list of alliances.

     On map Units
     ------------
     (NOTE:  I'm going to use the term 'faction' to represent 'faction or 
        alliance', depending upon what type of TDC you're using )
     Due to obvious space restricions within map hexes, individual units are
     not shown on the map. Rather, faction presence in a hex is represented.
     Up to four seperate factions can be shown to be present in a hex. The
     presence of a faction is represented by a small triangle filled with
     the colour of that faction (or alliance). The four triangles are placed
     along the NW/NE/SW/SE edges of the hexes, allowing other terrain features
     like pop.centers shafts etc to still be seen. When map units are turned 
     on, all terrain feature descriptions (town names, etc) are turned off 
     make the map clearer.
     The idea is that the 4 factions with the greatest presence (in 
     terms of troops numbers) are displayed, from ordered highest 
     to lowest, the order being NW,NE,SW,SE. The selected TDC 
     determines which factions are elegible for display on 
     the map. Units which were spotted on previous turns, but which are not
     spotted this (the current) turn are shown with a dotted black border 
     to indicate that the supposed location is historic.
     Create an empty faction based TDC to have all factions' units displayed.
     NOTE: See 'Other operations' and 'View/Full Unit List' sections below
       for info on getting detailed unit info for each hex. 

  Faction List: Presents a form displaying all the known factions. Factions 
     information can be imported as from the 'Import Faction List' menu
     item (see below). Listed faction information can be modified, and 
     factions can be assigned a colour (for use in later versions of AtMap3,
     when units will be shown on the map). Use the Find button to search for
     a faction - search on faction number, or all or part of the factions name
     or player's email address.

  Gate List: Selecting this menu item brings up a list of all known Gates.
     Select a gate and use the 'Goto' button to center the map on the hex 
     containing that gate.

  Full Unit List: Select this to bring up a list of all the spotted units
    (for the turn being displayed). Select from the drop down faction
    list at the top of the form to restrict the units shown in the list.
    Use the 'Mine' and 'All' buttons as a quick way to make such selections.
    Clicking on a unit in the hex will cause its data to be displayed in the
    bottom half of the form. Use the Skills/Equipment/Troops/Can Study buttons
    beside the lower list box to choose what info is shown in that list box.

    When a unit is selected, the 'Map to Hex' button can be used to shift
    the main map to center on the hex in which the selected unit resides.
    If you have sufficient space on your screen, you can move the Unit List
    form across and out of the way so that the main map can be better seen.
    If the currently selected unit is in a hex visible on the main map, that
    hex will flash to help identify it. This only works for your own units,
    and is meant to assist you writing your turns. You can capture you turns
    orders withing AtMap3, and the Full Unit List is one place to do this.
    Double click on one of your units in the Full Unit List to bring up
    a small panel into which you can type your orders for that unit. Any
    @ commands from your turn template in your results file will 
    automatically be included the unit's orders. Type in orders as you
    would normally for each unit. When the order for a unit are done, press
    either the 'Done' button or the 'Close' button. Either one will close the
    order capture form, but 'Done' will indicate that you consider the orders
    for that unit complete, and a small cross will appear in the coloured box
    to the left of the unit in the unit list, helping you identify which units
    orders have been completed and which not. Pressing the 'Close' button will
    keep the orders you have captured for that unit, but will not mark that 
    unit's orders as done (with that x). Of couse, you can always double click
    on any of your units at a later date and change the orders and change the
    'Done' mark.
    See the section 'Special/Generate Turn file' for info on how to build a
    turn file once all unit orders have been given.

  Faction Details: Displays some info about your faction. You must have
    put your own faction number in the Faction Number field before
    you can do most things withing AtMap3.
    Registered users will be given a registration key which they
    would type into the Registration Key field below.
    A Hostile<->Ally faction list is visible on this form, but not
    yet implemented.


Import
  Import Turn File: Use this to extract the relevant data from a turn
     file. Data imported this was is considered 'confirmed'. To import
     a turn, put the turn file in the IMPORT sub-directory and use this
     menu option. Select the file to import and press 'Open'. 
  Bulk Turn File Import: Use this to perform the Import Turn File operation
     on a group of result files as a batch. Useful when importing many
     historic turn files all at once, although you are likely to be 
     prompted to identify items vs creatures along the way.
  Import AtMap3 data: Used to import a file created using the 
     'Export AtMap3 Data' option described below. Select the file
     to import and indicate whether the data imported is to be
     considered un-confirmed (if you do not check this option, the
     'confirmedness' of each hex data will match that of the originator
     of the data).
     Also, the user can specify the precedence to use when importing ATD data:
     The issue is whether the data being imported should replace any which
     map already be present in the map. If this item is checked, then almost
     all exisiting map data will be replaced by that in the ATD file (eg. if
     the ATD file holds no pop. centre info for a hex which is marked as 
     having a town on the map, the town details will be overwritten).
     Generally, its better to leave this option OFF when importing ATD, and 
     that is how it defaults.
  Import Faction List: Use this to import a list of factions. The list must
     be of the format used in the standard Atlantis 3 player list file which
     can be downloaded from the web site. i.e.
               faction_name (fac_no), email_address
     Use the View/Factions menu to view loaded faction information.
     It's quite important that this file be kept up to date, as the faction
     list is used as a cross reference for unit owners when turns are imported.
     WITHOUT A LOADED FACTION LIST, ALL UNITS IN AN IMPORTED TURN FILE WILL
     BELONG TO AN UNKNOWN FACTION !! 

Export Data
  Generate Map: brings up a Generate map screen, whereby you can specify
     the dimensions, zoom level and what to display on the gererated map.
     Specify the file name and generate a BMP map to your specification.
  Export AtMap3 Data: specify the filename, coordinates and size of the
     rectangle of hexes to export and some options of what info to include
     in the export. Press the Export button to create the export file. 
     Pass this on to another AtMap3 user who can Import it using the
     option in the Import menu.

Special
  Combat Simulation: I've written a simple combat simulation. It handles
    two sides, tactical advantage, Behind/In front, terrain based riding bonus  
    (not WINGs yet tho), SWOR, MSWO, CHAI, PARM, MARM, HORS, XBOW, LBOW, DBOW.   
    (but not healing)
    You can simulate creatures/monsters by setting their Hit points (often > 1)
    NO MAGIC IS CATERED FOR YET, but I do want to add this in future versions.
    Build your armies on each side by adding units, and press the 'Run Combat'
    button. After the battle calculation, the results form should appear 
    showing the battle in a similar format to that shown in turn results.
    If you close the battle results form, you can take another look using the
    'View Results' button.
    Save and load battles you've built using the 'Load Battle' and 'Save Battle'
    buttons at the bottom of the form. Don't use this to facility to 
    simulate combat with AIF factions, and especially not me ! :)

  Generate Turn File: Once you're happy you've competed your orders for 
    the turn, you can generate a turn file for sending to Atlantis.
    Specify the directory (I suggest you create a TURNS sub-directory 
    off your AtMap3 directory). Provide a file name and away it goes.
    NB : MAKE SURE YOU ARE DISPLAYING THE CORRECT TURN NUMBER (ie, the
     one for which you want to generate a turn file, usually the most
     recent turn) OTHERWISE YOU COULD GENERATE A TURN FILE FOR AN EARLIER
     TURN.

Maintain
  Maintain Alliances: Here is where you can keep track of alliances and
    which factions belong in each. Create new alliances, name them and
    add factions to them. A faction can be placed in more than one
    alliance. There is no support for multiple levels (ie. alliances
    within alliances). Here you can also assign a colour to each alliance,
    which is used when units are displaced based upon an alliance based
    Troop Display Configuration (TDC). 
  Options: Doesn't do anything. Makes the program look more complete.    

Help (actually, this file is all the help you gonna get)
  About 
    Tells you all about the program and me :)


Other operations
================

Right clicking on main map brings up a Popup menu from which you can:
 Save View as home }  as per the entries
 Move to home      }  under the Navigate menu
 Center here   - centers the map view on the clicked on hex
 View Units: This brings up a unit list similar to the 
   Entire Unit List. The diffence is of course that this list is for
   the clicked on hex only. You can provide unit orders by double clicking 
   on your units in the unit list.
 
Double clicking a hex on the main map brings up a form allowing
you to capture or modify information about that hex. There are some
limitations to this screen, as discussed below. Note that you can
modify the confirmed/unconfirmed flag from a hex on this screen.
Also, you can view the Products, Goods Wanted and Goods for sale
in the selected hex. The hex detail form has a button at the bottom
right which allows you to bring up the Unit list for the hex.
Just above the 'Save' and 'Close' buttons, is a label indicating 
when (in turn number) the hex was last updated from a result file.
This helps keep track of how outdated your data may be.


A note on the underworld:
-------------------------
I considered a number of alternatives for handling the fact that the
underworld coord system does not match the overworld one, and that 
not all directions can be travelled from all underworld hexes. 
The option I chose was to spread the underworld map out so that its hexes
correspondes to surface locations. The empty or 'rock' hexes are used
to indicate whether units can move between hexes. A thin yellow bar 
running between underworld terrain hexes indicates that units may travel
directly from the one hex to the other. 


 
Known Bugs and Limitations
==========================

- The list of Provinces, Natives and Terrain types can not be
  modified manually - these are built from the data in turn files.
  ie. You cannot add a particluar province to the Province list - it
  will be added when a turn file containing a hex with that province 
  is imported - same applies to the Natives list.

- And many others, but this is WIP.


Version 2.0 Enhancements
========================

* Now recognise difference between City,Town and Village. These are 
  also each represented differently on the map.
* Added fields for holding gate info, shaft info and Other (lairs etc).
  Each of these items can be individually shown or hidden, along with
  cute little symbols for each
* Added Comments field for each hex. Only visible in the Hex Details page.
* Support underworld hex data
* Little 'zoom area' rectangle on the global map so you know where you're
  looking on the normal map.
* Turn file parsing should now handle Ship movements in the Events section
  of the report. The terrain types 'seen' from on board ship should now
  magically appear on your map :)
* Added Export and Import of AtMap3 Data facility to enable the
  easy transferral of information between users of AtMap3. The
  Export/Import file created is a text file.


Version 2.1 Enhancements (completed 11 May 1997)
========================

* Fixed a problem encountered when importing AtMap3 export files (.ATD) which 
  have blank lines.
* You can now click on the X,Y display panel at the bottom of the map form to
  bring up the 'Goto coordinate' feature.
* You can now turn off Population center names and Population center icons
  almost independantly (you can't have names on and icons off)
* Gate, shaft, cave, ruin, lair and crypt information is now automatically
  extracted from Turn files. 
* Import ADT file procedure now has an added option: 
    Override existing map data (if any)
* The overview map now displays the underworld or overworld, depending upon which
  one you are currently viewing.
* 2 'toolbox' forms have been added:
    Terrain Color Chart
    Map Feature Icon Chart
* To speed up map redrawing when the 'Show Coordinates' option is turned on, the
  coordinates are not displayed on the hexes themselves, buy rather down the side
  and along the bottom of the map.
* People using lower spec machines can set the Atlantis.INI file option in the 
  [PREFERENCES] section:
    BufferDraw=TRUE
  This will cause AtMap3 to imploy a map buffering technique when redrawing the
  main map, which should significantly speed up the redraw time when scrolling
  the map small amounts. 
* A faction list screen has been added (along with the ability to import 
  the standard Faction List file). This screen shows all imported faction 
  info, and allows one to change some of the faction details. 
* TODO: If you are upgrading from an earlier version of AtMap3, then
   delete your TERRAIN.DAT file (in DATA sub-directory) while AtMap3 
   is not running, and then run AtMap3. A new TERRAIN.DAT will be
   generated including some specialised underworld terrain types.


Version 2.24 Enhancements (completed 30 Oct 1997)
=========================

* More hex info. Including production and goods details.
* Bulk Turn Import
* Alliances: Can keep track of faction allegences and used to display units
    on a 'sides' basis.
* On map units: The presence of faction or alliance units can be dsiplayed
    on the main map.
* Unit Information: Unit info is extracted from result files and available
    for your perusing pleasure.
* Capturing orders and Building turn files: each unit can be given orders
    and at the end of it all, a turn file can be generated.
* Combat Simulation: says it all. If not, see the description up above.
* List / Goto Gates - choose gate from a list and center map on it.
* City Navigation - search for an move map to a pop center.


Enjoy. Enquiries and suggestions can be sent to my email address below.
No complaints please :)


Trevor Tickner
(still playing the 'not-yet-dead' Golden Empire (#189), AIF Member)
bldsoft@ilink.nis.za