GAMEMASTER

                        Atlantis Gamemaster's Guide
                                      
   This document describes how to compile, setup, and run a game of
   Atlantis.
   
Compiling Atlantis

   Atlantis is a standard C++ program, with no UI or other
   platform-specific features. As such, simply putting all of the source
   files into a project or makefile and compiling it as a command-line
   application is about all there is to it. Note that there are source
   files in two directories; the basic Atlantis engine files live in the
   main directory, and the rule-set specific files are in a
   sub-directory. You need to include both sets of source files in the
   makefile. The sample Atlantis rule-set is called Atlantis Conquest,
   and is in the sub-directory conquest.
   
Unix

   A makefile is included for compilation on Unix, using the GNU gcc
   compiler. This has only been tested on Linux, but should probably work
   on any Unix system. Just type 'make <gamedirname>' at the top level,
   where <gamedirname> is one of the various subdirectories.  You can get
   more information about the GNU compiler at http://www.gnu.org.
   
Windows

   I am now using the GNU gcc compiler on Windows as well. This has the
   advantage that I can use it on both Unix and Windows, and as an added
   bonus the compiler is freely available. As above, just switch into the
   rule-set subdirectory and type 'make'. The Win32 port of gcc can be
   found at http://sourceware.cygnus.com/cygwin/.
   
   I'm no longer using Visual C++, so I don't include a Visual C++
   makefile. If someone wants to create a makefile for others to use,
   I'll be happy to put it on the download page.
   
   However, it is very easy to make a VC project to compile Atlantis:
    1. Choose a rule-set that you want to compile. For instance, the
       Atlantis Conquest rule-set is in the subdirectory conquest.
    2. Create a 'Console Application' Workspace in the rule-set
       directory.
    3. Add all of the Atlantis engine source files to the project. These
       are all of the .cpp files located in the main directory.
    4. Add all of the rule-set specific source files; these are all of
       the .cpp files in the rule-set directory.
    5. Update the include path to include both the main directory and the
       rule-set directory.
    6. That's it; you should be able to compile Atlantis at this point.
       You'll probably want to compile the 'Checked' version in case you
       want to debug.
       
Generating the rules

   The rules consist of an HTML file which reference a CSS.
   The command is:
   ./miskatonic.exe genrules intro.html rules.css <output.html>

   It will also produce a file called skills.dot
   This can be converted into a graphic with:
   dot skills.dot -Tpng -o skills.png

Running a Game of Atlantis

   The Atlantis program is actually very simple in terms of input and
   output. It takes a set of files as input, runs the turn, and writes
   out a set of files to the same directory. The Atlantis program does
   not do anything in terms of scanning for email, sending email, or
   anything of that nature. It is up to the gamemaster to either make
   sure the files are in the right place, and the right emails get sent
   out, or he must find or write a program to do that.
   
   Explanation: Atlantis is designed to be a very generic program, that
   will run on many computer systems, and in different ways. Different
   computer systems handle email in different ways; making Atlantis work
   on all of these different systems would be quite a task, and in my
   opinion one that is best separated from the actual game-running
   program. Further, nothing about Atlantis requires that it be an email
   game at all; the engine could be used in many different ways (a
   web-based version, for instance, wouldn't be too hard to do).
   
   The rest of this section assumes that the gamemaster is moving the
   files around by hand; if he is using a program to automate the
   process, he should follow the instructions with that program.
   
Setting Up the Game

   Generally, I find it best to make a directory to run a game of
   Atlantis, and then store each turn as a sub-directory. To start the
   game, make the directory game, and the subdirectory game/turn.0.
   Change the current directory to be game/turn.0 (Atlantis uses the
   current directory to find any files it is looking for), and run the
   program atlantis new (note that the actually program name may well be
   something different, depending on how you compiled it). This will
   output the files game.out and players.out; these are the initial game
   database and game status file. At this point, you are ready to prepare
   for the first turn; follow the instructions below for how to prepare
   and run a turn.
   
Running a Turn

   To set-up a turn, first make the directory for the turn (i.e.
   game/turn.1), and copy the previous turn's game.out and players.out
   into place as the new game.in and players.in. At this point, you can
   edit the players.in file to add or remove players from the game.
   
   The players.in file will be in the following format:
   
AtlantisPlayerStatus
Version: 262144
TurnNumber: 1
GameStatus: Running

Faction: 1
Name: Merry Pranksters (1)
Email: gdunbar@prankster.com
Password: none
Faction: 2
Name: Evil Faction (2)
Email: evil@prankster.com
Password: none

   This file will be your primary method of communicating with the
   Atlantis program. The first 2 lines tell Atlantis that this is a game
   status file, and what version of the Atlantis engine was used to write
   this file. The next line indicates the last turn that was run, and the
   GameStatus: line indicates the current status of the game (the 3
   settings of GameStatus: are "New", "Running", and "Finished"). None of
   the first four lines should be modified by the gamemaster.
   
   Next in the file comes a list of the factions in the game, and some
   information about the faction. You can perform the following actions
   on a faction using this file:
    1. You can change the name, email address, or password for the
       faction. Note that there are in-game methods for doing this as
       well (the ADDRESS order, for instance), but it is preferable to
       change things in the players.in file. This is because the in-game
       methods do not take effect until the next turn is run; whereas
       editing the file is immediate.
    2. You can remove a faction from the game. Do this by adding the line
       "Order: Quit" to the faction's section of the players.in file.
    3. You can add silver to a faction's unclaimed fund by adding the
       line "Reward: [amount]" to the faction's section of the players.in
       file.
    4. Any other lines within a faction's section will be kept in the
       players.out file when a turn is run, so you can store extra
       information about a faction in this file. For instance, if you
       wish to implement an Atlantis Times newsletter feature, you can
       add a line "Times: on" or "Times: off" to each faction's section
       indicating whether they wish to receive the Times or not.
    5. You can add a faction to the game by making a new faction section,
       leading with the line "Faction: New". It isn't required that you
       fill in the email address and password, but it's probably always a
       good idea. After the turn is run, the faction will be assigned a
       faction number, and will be present in the players.out file.
       
   Also before running a turn, players will probably want to issue orders
   for their faction. Orders should be put into the turn directory
   (game/turn.1, in our example), with the filename orders.[num], where
   [num] is the faction number. This file should be a proper Atlantis
   order file, with the #atlantis line at the beginning of the orders and
   #end at the end. Note that new factions cannot issue orders for their
   faction.
   
   Once the players.in file has been updated, and any orders are in place
   for the turn, you are ready to run the Atlantis program. Do this by
   changing into the turn directory (recall that Atlantis only looks for
   files in the current directory), and issue the command atlantis run.
   (Again, note that the actual executable name depends on how you
   compiled the program). This will run the turn, generating the files
   game.out, players.out, and report.[num] for each faction in the game.
   Each report file can then be sent to its owner, and you are ready to
   set-up for the next turn.
   
Syntax Checker

   The Atlantis program can also act as a syntax checker for a set of
   orders. Run the program atlantis check [orders] [check], where the
   actual program name is the program that you compiled. [orders] should
   be the filename of the orders file, and [check] will be the filename
   that is created, containing the results of the syntax check. If you
   have a program that automatically handles email, players often
   appreciate getting a copy of the syntax check results whenever they
   send in orders.
   
Game Editing

   The Atlantis program can also be used to edit the game database. To
   use the game editor, change the current directory to be the turn
   directory (like game/turn.1), and run the command atlantis edit. This
   will present a rudimentary text interface to change some parts of the
   game, such as unit possessions. When done editing, you can either quit
   without saving changes, or save and exit. If you choose the save
   changes, a new game database file game.out will be created; to use
   this file as the new game database file, move the file to game.in,
   replacing the old game.in file.
     _________________________________________________________________


World Creation

   The following is a description of the options involved in Atlantis world
   creation. None of the information here is relevant if you merely want to
   run a standard game.

   All of the following assumes that you have access to the GM report in order
   to view the game map after creation - at least while you're experimenting.
   You will have to make sure the gamedef GM_REPORT is set to 1. The GM_REPORT
   will be created as 'report.1' in the atlantis directory - it's an omniscient
   turn report.


Basics: world size, land mass and levels

   The most important consideration for any game is world size as this will
   determine the number of players that can comfortably join a game and the
   amount of competition. You are prompted for world width and height in
   the creation process by the game.

   # of surface hexes = width * (height / 2)

   The ocean percent value is a rough estimate of how much of these will be
   land mass:

   # of surface land hexes = width * (height / 2) * <ocean percent> / 100
   
   (see Land Mass Distribution below for a description how to change ocean
   percent.)

   For instance with a default <ocean percent> of 60, a 128 x 128 map will have
   8192 surface hexes and about 4915 land hexes. In standard Atlantis, a faction
   can make use of 100 maximum. Reduce that somewhat for mixed factions, magic
   factions and a little bit of friction and you might want to aim for 50 land
   hexes per player. That means that a game this size would allow up to 100
   players to expand and play comfortably (note: this is just a very rough
   sketch and things can vary considerably on the play style chosen by your
   players and other rules you may or may not have enforced in your game).

   Underworld levels, while not being available to players immediately at
   start, also have an effect on the total number of regions available for
   play. They are set by the gamedefs UNDERWORLD_LEVELS (the number of
   underworld levels beneath the surface), UNDERDEEP_LEVELS (the number of
   underdeep levels) and ABYSS_LEVEL (this is just an on/off switch).

   The underworld levels are only 1/2 the size in both coordinates of the
   surface level (except the top one if there's more than one), underdeep
   levels are 1/4th the size in both coordinates (except the topmost if
   there's more than one - that will be 1/2 size), and the Abyss is just
   a tiny area with a Black Keep for the Wyreth victory conditions.


Land Mass Distribution

   The distribution of land mass determines whether players will be able to
   expand on a large continental mass and how important ships and sailing
   will be in the game.

   <CONTINENT SIZE> and <OCEAN PERCENT>:
   These aren't gamedefs - they are hard-coded into 'world.cpp' in the
   gameset directory. In 'world.cpp' you'll find the 'Game::CreateWorld()'
   function with the following line:
   
      regions.CreateSurfaceLevel( 1, xx, yy, 60, 16, 0 );
                                             ^    ^ 
                                <ocean percent>  <continent size>
                                
   As you can see, the hard-coded defaults are 60 for <ocean percent> and
   16 for <continent size>, but you can edit them here.  
   
   <continent size> will control how much land is allocated to
   a continent at a time. For smaller worlds this value should be
   decreased or you'll find that all your land mass is allocated to one
   or two continents only. For huge worlds it might be increased
   correspondingly if you want to have continents fit for your world size.

   ARCHIPELAGO: this gamedef controls how often land is created not as a
   continent but as a small island chain. The size of the islands can range
   from very small to a value that's linked with continent size but even
   the bigger islands will tend to be much smaller than your continents.
   So while an archipelago world might be created by setting <continent
   size> to a really low value, setting ARCHIPELAGO will allow your world
   to have both solid continents and islands at the same time. The value of
   ARCHIPELAGO is treated as a percent chance that any attempt at creating
   new land mass will end up forming an archipelago. Note that because
   archipelagos are much smaller than continents, the overall land mass
   allocated to them will be smaller than this gamedef value.
   
   Setting ARCHIPELAGO activates the code for filling in inland seas and
   severing land bridges (see 'Map Refinements' below) 

Terrain Type Allocation

   Terrain distribution is probably more a matter of style and flavor than
   the aspects discussed in previous chapters. It can become a matter of
   resource availability if not much land is available either due to
   world or continent size.

   Terrain types are allocated in 'world.cpp' in the function
   GetRegType(ARegion *pReg). Depending on the region's level and distance
   to the equator a different table of terrain type choices is used. If you
   want to have more or less of a specific terrain or add in new types you'll
   need to edit these tables. For most games using the standard terrain set
   you won't need to look into this. (The exception to this are lakes which
   are currently handled by their own gamedef - see below)

   LAKES_EXIST: lakes are a terrain type that is impassable by foot but can
   be sailed on or flown over just like ocean. They are meant to introduce
   added variety and some hindrance to land movement on the continents
   where inland sea masses have been erased. They can be set so that all
   adjacent hexes act as coastal terrain (having similar races and possibly
   resources) by using the LAKESIDE_IS_COASTAL gamedef. Lakes can also
   provide some economic benefit to adjacent land hexes, this is handled by
   the LAKE_WAGE_EFFECT setting. Here we are concerned with lake placement.

   The LAKES_EXIST gamedef sets the chance that any given land hex is
   allocated as lake and not as any other type of terrain. The basic chance
   for this to happen depends on whether this hex has previously been an
   ocean hex that has been filled in via removal of inland seas (see below).
   In case it has, the percent chance is equal to the LAKES_EXIST setting.
   In all other cases, the chance is LAKES_EXIST / 10 + 1 %.
   This creates areas with a higher abundance of lakes, usually on
   main continents and not islands.
   
   Setting LAKES_EXIST activates the code for filling in inland seas and
   severing land bridges (see 'Map Refinements' below).

   ODD_TERRAIN: this gamedef adds a sprinkle of chaos to your maps by
   inserting single hexes of different terrain. The terrain type is still
   allocated in the normal way - it might just be different from the patch
   of terrain around it.
   The value of ODD_TERRAIN is the chance that this happens, per hex, in
   0.1%. A setting of '4' will therefore create interspersed terrain in
   0.4% of all hexes. Note that the terrain type can of course end up to
   be the same as that of the surrounding hexes.
   
Map Refinements

   Standard Atlantis maps tend to show either a web of land
   hexes against a backdrop of water or continents with a shotgun
   pattern of ocean sprinkled in between. The ARCHIPELAGO and LAKES_EXIST
   gamedefs both activate functions that erase ocean hexes caught in a 
   continental land mass without a connection to the main ocean and cut
   some of the land bridges between continents that are only 1 hex wide.
   
   You will find that your continents will tend to be larger when these
   options are switched on - setting a lower <continent size> will
   reduce this effect.

Town Setup

   Towns are always a focus of economic activities in Atlantis and are
   strategically important locations. The number and placement of towns
   can therefore have a strong effect on the competition and feel of a
   game.
   
   TOWN_PROBABILITY: this is the chance for creating towns compared to
   standard Atlantis. '100' is the default setting. A value of '80'
   means that only 80% of the usual number of towns will be created.
   
   TOWN_SPREAD: normally towns are much more likely in plains than anywhere
   else. This might or might not suit your game - why should your
   dwarves have less towns just because they live in the mountains?
   At the default value of '0', the chance for a town is directly
   proportional to the terrain's economy value. At a TOWN_SPREAD setting
   of '100' at the other end of the scale the chance is exactly the same
   regardless of terrain. The effect is that other terrain types - which
   are already economically less interesting than plains - become much
   more viable as a base for factions.
   
   TOWNS_NOT_ADJACENT: ever seen too many towns in one spot, especially
   on those already rich plains? This gamedef is a possible check against
   town clustering. TOWNS_NOT_ADJACENT is the percent chance that a
   town will not be created if another one has already been created next
   to it. A setting of '50' for instance will decrease the likelihood by
   50%, and a setting of '100' and above will prevent towns from being
   adjacent. Note that starting cities are an exception to this since
   they are created by a different part of the code and are necessary
   for the game.
   
   LESS_ARCTIC_TOWNS: use this gamedef to reduce chances of towns near the
   polar caps (within 9 hexes of the map border). The town chance is
   reduced by approximately the LESS_ARCTIC_TOWNS setting x 3% times
   9 minus the distance from the polar cap. 
   Towns that are created will also be considerably smaller than usual.
     _________________________________________________________________