      ______              ___________________              ______
      >     |____________|   AstroWar 1.00   |____________|     <
      ~~||~~|  Centurion |~~~~~~~~~~~~~~~~~~~| 2:2502/666 |~~||~~
        ||   ~~~~~~~~~~~~                     ~~~~~~~~~~~~   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                     CENTURION                     ||
        ||                                                   ||
        ||                                                   ||
        ||                        -*-                        ||
        ||                                                   ||
        ||                                                   ||
        ||                   AstroWar 1.00                   ||
        ||                                                   ||
        ||        A Space Conquest Game Played by Mail       ||
        ||                                                   ||
        ||          Copyright (C) Damian Walker 1997         ||
        ||                                                   ||
        ||                                                   ||
        ||                        -*-                        ||
        ||                                                   ||
        ||                                                   ||
        ||                    USER MANUAL                    ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                  .   |                            ||
        ||                     \|/    *     +                ||
        ||                    --+--                          ||
        ||               +     /|\            .              ||
        ||                      |    .  +                    ||
        ||                  *   |          *                 ||
        ||                        ().                        ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||                                                   ||
        ||   ____________                     ____________   ||
      __||__|  Copyright |___________________|    1997    |__||__
      >     |~~~~~~~~~~~~| (C) Damian Walker |~~~~~~~~~~~~|     <
      ~~~~~~              ~~~~~~~~~~~~~~~~~~~              ~~~~~~
.hAstroWar 1.00 - User Manual
.fContents                                                              %2d
        AstroWar 1.00 - Host for a Turn-based Space Conquest Game

        Copyright (C) Damian Walker 1997

        This program is free software; you can redistribute it and/or
        modify it under the terms of the GNU General Public License as
        published by the Free Software Foundation; either version 2 of
        the License, or (at your option) any later version.

        This program is distributed in the hope that it will be useful,
        but WITHOUT ANY WARRANTY; without even the implied warranty of
        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
        GNU General Public License for more details.

        You should have received a copy of the GNU General Public
        License along with this program; if not, write to the Free
        Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
        MA 02111-1307, USA.

SECTION 0_______________________________________________________________
                                                                Contents

        1.      INTRODUCTION TO ASTROWAR
        1.1.    What is AstroWar?
        1.2.    What You Need to Run AstroWar
        1.3.    Acknowledgements

        2.      INSTALLING AND RUNNING
        2.1.    On Unpacking... What You Should See
        2.2.    General Configuration
        2.3.    Creating a Game
        2.4.    Running a Game

        3.      PLAYING THE GAME
        3.1.    Getting Started
        3.2.    Scouting, Conquering and Redeployment
        3.3.    Requesting Details About Your Empire
        3.4.    The Message System
        3.5.    Winning the Game
        3.6.    Resigning Your Position

        4.      CUSTOMIZING YOUR GAME
        4.1.    Resizing the Galaxy
        4.2.    Twiddling With Starships
        4.3.    Victory Conditions and Other Miscellany

        5.      DEVELOPMENT NOTES
        5.1.    Recompiling the Source Code
        5.2.    Developing an Interface
        5.3.    Writing Add-on Utilities

        6.      TROUBLESHOOTING
        6.1.    Cannot open log file <filename>
        6.2.    Command line error: type 'astrowar ?' for help
        6.3.    AstroWar already running
        6.4.    Out of memory <action>
        6.5.    Bad return code <number> from <technobabble>
        6.6.    Bad command in line <number> of <path>astrowar.data
        6.7.    Cannot read config file <filename>
        6.8.    Cannot open detail file <filename>
        6.9.    Bad command in detail file <filename>
        6.10.   Cannot open game list <filename>
        6.11.   Bad detail file (line <line> in <gamelistfile>)
        6.12.   Bad line <line> in game list <file>
        6.13.   Game list <filename> is empty
        6.14.   Game <name> not found
        6.15.   Cannot open file <filename>
        6.16.   Bad header in file <filename>
        6.17.   File <filename> already exists
        6.18.   Cannot create file <filename>

        A.      GENERAL REFERENCE
        A.1.    The Command Line, Environment and Error levels
        A.2.    Configuration File Commands
        A.3.    Orders
        A.4.    Reports

        B.      BINARY FILE FORMATS
        B.1.    The Indexed Databases
        B.2.    The Orders File
        B.3.    The Report File

        C.      SUPPORT AND RESOURCES
        C.1.    Resources on the Internet
        C.2.    Resources in Fidonet
        C.3.    Contacting the Authors
.fIntroduction                                                        %2d
SECTION 1_______________________________________________________________
                                                Introduction to AstroWar

        This section of the manual introduces you to the program, and
        gives some details of the program's requirements.

        -About the Manual-----------------------------------------------
          To save me writing a separate developers' kit, and to save you
           having to find it, I have included development information in
        this manual.  If you're not a programmer, don't be put off, just
                              skip the sections on AstroWar development.
        ----------------------------------------------------------------

1.1.    What is AstroWar?

        AstroWar is a play-by-email game of space conquest.  What's so
        special about this particular game? From the player's view, it's
        simple and fun.  From the game moderator or sysop's view, it's
        fully automatic, adaptable, expandable, portable and free!  Bear
        with me while I justify some of these claims...

        It's simple:  The rules and construction of this game are as
        simple as I could make them.  There is just one type of planet,
        and one type of ship.  Each planet just has a single statistic:
        production, which decides how many ships it produces each turn.
        Ships are just single faceless, nameless units which are used in
        greater or lesser numbers in order to overwhelm, hold back or
        discourage an enemy.

        It's fun:  How can I justify this?  Well, I can't really since
        it's just my opinion, but most of the players in the beta test
        games find it quite entertaining.  Its simplicity means that you
        won't spend much time learning the rules, and you'll be playing
        properly and developing your strategies almost immediately. It's
        hardly worth setting up a practice game.

        It's fully automatic:  Well, almost anyway.  It doesn't install
        itself or start new games.  But once you've installed the
        program and created one or more games, you don't need to tinker
        with it at all. You just run the turn processing commands and
        AstroWar and its associated utilities do all the work.  I
        process my games automatically overnight, so my games are run
        without me lifting a finger.  This level of automation means
        that you can play in your own games, as long as other players
        trust you not to examine the data files too closely.

        It's adaptable: You can tinker with the settings of new games
        before you create them, altering the physical size of the galaxy
        and the number of planets in it, the speed at which ships move
        and the maximum distance they can travel in one uninterrupted
        journey.  All of these settings can have an important effect
        upon gameplay.  Also, the player interface is external, so
        players can use whatever interface they find available for the
        game, be it graphical, email or a BBS-door.

        It's expandable: Such simple gameplay positively begs for
        expansion, and the data files are laid out such that it is
        reasonably simple to write add-ons to alter gameplay.  The
        program also has direct support for disabling such things as
        production, victory checking and fleet movement, so that these
        aspects of the game may be replaced externally.  Source code for
        the program is available, and some of it is public domain, which
        means that if you want to write an add-on, half of your work has
        already been done for you.

        It's portable: Source code distribution allows porting to other
        platforms by anyone with a mind to do so.  Most of the source is
        in straight ANSI C, and the few non-ANSI constructs employed are
        easily located and changed.  The program is also distributed in
        executable form.  I maintain the 32-bit DOS DPMI version and the
        Linux version, and others are helping me to port AstroWar and
        its associated utilities to platforms such as the Amiga.

        It's free: There is no restriction on distribution and use of
        the binary distributions.  Grab them and use them for as long as
        you like, you're welcome to them.  The source code is
        distributed under the GNU GPL, so you can recompile that or
        change it as you like, as long as your own source is also
        distributed under the GNU GPL.

1.2.    What You Need to Run AstroWar

        To run AstroWar, you need one of the binary distribution
        archives.  Appendix C list gives details of where you can get
        the binary distributions.  Alternatively, if you have the source
        distribution, you can compile it by following the instructions
        in section 5.1 of this manual.

        As well as the AstroWar program itself, you will also need one
        or more interface programs.  One such program is AstroMail,
        which allows players to write orders and read reports using
        Fidonet netmail. Take a look at some of the sites listed in
        Appendix C for a copy of AstroMail, or to find any other
        interfaces which might be available.

        If there are any hardware or software requirements particular to
        your platform, you will find them in a 'read.me' file which
        comes with each official binary distribution.  AstroWar is not a
        particularly demanding program as far as speed or memory
        requirements are concerned, and should a binary distribution not
        be available for your platform, the source code could be
        compiled with the minimum of effort.

1.3.    Acknowledgements

        A number of people have helped in the development of AstroWar.
        First of all, there are the developers; apart from myself, they
        are Tim Franklin and Ricky Walker, who helped me in the
        development of the Linux version, and Thomas Newsom, who is
        working on the Amiga version.

        There are also the beta testers of the DOS DPMI version.  These
        are Martyn Wilkins and Sy Hughes.
.fInstalling and Running                                              %2d
SECTION 2_______________________________________________________________
                                                  Installing and Running

        This section gives in tutorial form the instructions you need
        for unpacking the program, setting it up, creating some games
        and running them.

2.1.    On Unpacking... What You Should See

        Since you are reading this manual, you've probably managed to
        extract the files from the archive without difficulty.  All the
        distribution files reside in one directory.  For the rest of
        this manual, I will assume that you have unpacked AstroWar into
        the directory '/astrowar'.

        -Running AstroWar under MS-DOS----------------------------------
                 Throughout this manual you will see long filenames like
           'astrowar.data' and 'planet.index'.  Don't worry about these,
           MS-DOS will truncate them internally to fit in the normal 8+3
                    pattern. Similarly, forward slashes in pathnames are
                                automatically translated to backslashes.
        ----------------------------------------------------------------

        There may well be unofficial binary distribution archives of
        AstroWar, since the source code is freely available.  If you
        have an official binary distribution, it should contain the
        following files:

                astrowar        or astrowar.exe, the executable
                astrowar.doc    this manual
                read.me         platform-specific details
                file_id.diz     the archive description
                astrowar.sam    a sample configuration file
                gamelist.sam    a sample game list file
                detail.sam      a sample detail file

        If any of these files are missing, you can find them in one of
        the official binary distributions.  However, the only files
        which are really necessary are this manual and the executable.

2.2.    General Configuration

        The general configuration file for AstroWar is called
        'astrowar.data', and it is situated in the AstroWar directory.
        There is only one command in the general config, 'logfile',
        which is used as follows:

                logfile <log filename>

        The sample configuration file 'astrowar.sam' contains an example
        of how the 'logfile' command is used.  If you have installed
        AstroWar in the '/astrowar' directory then you can just rename
        the sample configuration file as 'astrowar.data' without making
        any changes to it.

2.3.    Creating a Game

        There are a few steps to creating a game.  First, you must make
        a directory for it.  For our example, make a directory called
        '/astrowar/game1'.  This will hold all the config and data files
        for our first game.

        Now we need to add this directory to the game list file,
        'gamelist.data'.  Conveniently, the sample file 'gamelist.sam'
        contains this exact directory, so if you're following these
        examples verbatim you can just rename the sample file as
        'gamelist.data' without making any changes.  Apart from the
        comments, 'gamelist.data' should contain the following:

                /astrowar/game1/

        To add further games to the game list, you just add more
        directory names to the 'gamelist.data' file.  Note the trailing
        slash.  This is mandatory.  If your operating systems uses some
        other character to separate directory names from filenames, you
        need to use that instead.  AstroWar expects to be able to simply
        add a filename to this directory name to create a full path and
        filename.

        With the game directory created, and added to the
        'gamelist.data' file, you are ready to create the configuration
        file, properly termed the 'detail file' for your new game.  This
        file is named 'detail.data' and resides in the game directory.
        Luckily, we have a sample detail file called 'detail.sam' to
        save a bit of typing.

        You can copy the sample file into the /astrowar/game1 directory
        as 'detail.data' without making any changes at all.  Apart from
        the comments, the file should contain the following text:

                name Game1
                planets 121
                xmin -20
                xmax 20
                ymin -20
                ymax 20
                speed 4
                maxdist 40

        These are the default game values.  You can actually omit every
        line here except 'name', and the game will have these settings.
        They are really only here as an example, and generally you will
        only include the commands which differ from these default
        values.  Section 4, 'Customising Your Game', contains more
        information about the commands in the detail file.

        So now, in addition to the files included in the binary
        distribution, we should also have the following:

                /astrowar/astrowar.data
                /astrowar/gamelist.data
                /astrowar/game1/detail.data

        This being the case, we can now invoke AstroWar and tell it to
        create our game for us.  The command line for this is as
        follows:

                astrowar create -game Game1

        'create' is an AstroWar command, and '-game Game1' is a switch
        which tells AstroWar which game to create.  As you run this, you
        will see the program banner, and a number of messages showing
        AstroWar's progress in creating a game.  The empire and fleet
        files start empty, so these will be created quickly.  The planet
        file will take a bit longer to create, since all 121 planets are
        generated at this point.

        -A Note About Detail Files--------------------------------------
            When you run AstroWar, it looks in every directory listed in
             'gamelist.data' for a 'detail.data' file, which it reads to
               build up a list of games and their locations.  If any one
           'detail.data' file contains an error, AstroWar will refuse to
           run (even if the error is in the detail file for a game other
                                 than the one you're trying to process).
        ----------------------------------------------------------------

        With this process complete, your game is created and ready to
        run.  If you have had any problems, refer to section 6,
        'Troubleshooting', and also check the 'read.me' file for any
        compatibility problems which may occur.

2.4.    Running a Game

        Before attempting to run a game, we must turn our attention to
        the subject of external interfaces.  The AstroWar package is
        purely a game host, and contains no interface.

        AstroWar simply reads its orders from a single binary
        'orders.data' file in the game directory; the job of putting the
        orders there falls upon the interface program.  Similarly, it
        outputs its reports to 'report.data' in the game directory,
        leaving to the interface program the details of relaying the
        reports to the players. So, before running the first turn of a
        game, you must ensure that you have an interface program in
        place.

        For the purposes of this manual, I will assume that you are
        going to run your games via Fidonet netmail, using the AstroMail
        interface program.  Appendix C contains details of how to obtain
        AstroMail, so if you don't have it already, get it now and
        install it (details are in AstroMail's own manual).  If you
        aren't connected to Fidonet, you might want to use a more
        appropriate interface program, in which case you will have to
        adjust the examples accordingly.

        Once AstroMail is set up, you can decide how you are going to
        run your game.  This can be any number of ways, depending upon
        who you are and how your computer system is arranged.  If you
        are a Fidonet sysop, you will probably want to run your games
        automatically, overnight, like I do.

        However you decide to run your games, you will need to take the
        following steps each turn:

        * Delete any existing 'report.data' file in the directory of the
          game you are about to process.  AstroWar will not process a
          new turn until last turn's 'report.data' has been deleted.

        * Run the interface program(s) to transfer the players' orders
          into the 'orders.data' file in the game's directory.

        * Run AstroWar itself in order to process the turn and produce
          the reports, which will be saved in the 'report.data' file in
          the game's directory.

        * Run the interface program(s) again, this time to transfer the
          reports from 'report.data' into something the players or their
          turn viewers will be able to read.

        * Delete the 'orders.data' file which has just been processed.
          If you forget to do this, then next turn's orders will just be
          added to this turn's orders, and this turn's orders will be
          processed a second time.

        On a Unix system, the above steps might result in the following
        script file for our examples:

                rm /astrowar/game1/report.data
                astroml in
                astrowar turn -game Game1
                astroml out -game Game1
                rm /astrowar/game1/orders.data

        Refer to AstroMail's manual for more precise details of what the
        'astroml' commands do.  If you're using a different interface
        program, then it's the 'astroml' commands you want to replace
        with whatever your interface program uses.

        If you are a BBS sysop as mentioned above, you may want to put
        these commands in a nightly maintenance batch script, or a
        weekly-run script, to automatically process the game without
        your intervention.

        -AstroWar's Log File--------------------------------------------
        If you encounter a problem running AstroWar, you can look in its
              log file for details of what went wrong.  See section 6 on
         'troubleshooting' for details of what various log entries mean.
         You can also trap various error levels returned by the program,
                                    details of which are iln appendix A.
        ----------------------------------------------------------------
.fPlaying the Game                                                    %2d
SECTION 3_______________________________________________________________
                                                        Playing the Game

        This section of the manual is a player guide.  Since different
        players may use different interfaces in a single game, the guide
        is vague about details of what keys or commands to use.  More
        precise information should be available from the manual or help
        system of the interface program in use.

        Furthermore, interface developers may freely use this player
        guide as the basis of something more appropriate to their own
        interface (as I have done in the manual for AstroMail; take a
        look at the player guide in AstroMail to see what I mean).

3.1.    Getting Started

        AstroWar is a simple game of space conquest, usually played by
        email.  The simplicity of the rules mean that the time taken to
        learn the game is extremely short.  However, it may take just as
        long to develop a winning strategy as it does for more complex
        games.

        Let's take a look at the game rules before we go into details of
        how to play.  The map consists of a number of planets spread
        across a galactic map.  The number of planets and the size of
        the map are defined by the person running the game.

        There is only one type of planet, although each planet has a
        production rating.  This production rating reflects the number
        of ships that planet produces each turn, when it is owned by a
        player.  Neutral planets do not produce any ships.

        Ships are not treated individually in AstroWar.  There is only
        one type of ship, the variation being in the number of ships you
        send to the planets you are attacking.  Ships are sent in fleets
        of one or more ships, and each fleet's mission is decided by the
        number of ships sent, and the ownership of the planet the ships
        are being sent to.

        Part of the game's attraction lies in the high level of secrecy.
        In some games, you can see the entire map when you start the
        game, and sometimes you can see where other empires are.  Some
        games are very open, and allow you to see as much detail about
        other players' empires as those players can see.

        This is not the case with AstroWar.  When you start playing
        AstroWar, you only see full details of your homeworld, and the
        positions of nearby planets.  To get more information, you must
        scout the planets you can see, and you must start to expand
        before you see planets further away.

        But I'm getting ahead of myself here, for before any of this
        becomes apparent you must first join a game.  In order to join a
        game, you must submit a 'join' request.  With this join request
        you give a name which will be used to identify your empire.
        Your empire name can be up to 15 characters long.

        Upon successfully joining a game, you will receive confirmation
        that your request to join has been accepted.  With this you will
        be given the name of your homeworld, that homeworld's details,
        and a map of nearby planets to get you started.  Note that
        homeworld planets always have a production of 15 ships per turn.

        There are a few cases in which a join request might fail.
        Firstly, you might choose an empire name which is already in
        use.  This is unlikely, but possible.  Another case in which a
        request to join might be rejected is when the game is full, i.e.
        there are no planets which have not already been scouted or
        taken.  In the former case, just try to join again, with a
        different name.  In the latter case there's nothing you can do,
        except wait for the game to finish and re-start, or find another
        game.

3.2.    Scouting, Conquering and Redeployment

        The first thing you will want to do when you start a new game is
        scout one or more of the planets which were shown on your first
        map.  To scout a planet, simply send a single ship to it.  When
        the ship arrives, you will receive details about the production
        and ownership of that planet, along with the number of ships
        currently in orbit.  The scout ship will then turn around and
        begin the return journey.

        Once you have received details about some of the nearby planets,
        you should start making your attacks.  A fleet of 2 or more
        ships sent to a neutral or enemy planet consititutes and attack
        force.  Generally, you should send more ships than are already
        in orbit around a planet if you wish to take it.  However, you
        can send your attacks in two or more 'waves' if you don't have
        enough ships to take the planet straight away.  The first
        arrivals will reduce the enemy's numbers, so that the later
        fleets have an easier job of taking the planet.  If a fleet
        takes a planet, it is disbanded, and the ships take up orbit
        around the planet.

        You can start making attacks before you scout, but this is not
        always a good idea, particularly if you are joining a game which
        has already been running for a number of turns.  For all you
        know, an attack fleet sent out 'blind' might be travelling
        towards a planet belonging to a relatively powerful empire, and
        this is not a good way to gain allies.

        Once you have more than one planet, you may want to start
        redistributing your forces, for more effective attacks or
        defence.  Sending any number of ships from one of your planets
        to another is a normal fleet movement.  When the fleet arrives,
        it will be disbanded and the ships will join those in orbit
        around the planet.

        -A Note About Fleet Movements-----------------------------------
        A fleet does not start to move towards its destination until the
           turn after it is launched.  So, for instance, if you launch a
            fleet from one planet to a planet four squares away, it will
          still be four squares away on its first turn; only in the next
                                             turn will it start to move.
        ----------------------------------------------------------------

3.3.    Requesting Details About Your Empire

        Although the reports you receive from scouting, attacking and
        fleet movements tell you everything you need to know about your
        planets, there are times when you will want reminding about
        various aspects of your empire.  There are a couple of reports
        which you can request from AstroWar, whenever you need them.

        The planet list contains a list of all your planets, together
        with a remider of the planets' positions, their production
        ratings and the number of ships in orbit around them.  Only your
        own planets are included in this list; if you want up-to-date
        information about enemy or neutral planets you must scout them.

        -Turn Phases----------------------------------------------------
            There are four phases to each AstroWar turn: Fleet movement,
        Order processing, Ship production and Victory checking, executed
         in that order.  Bear this order in mind when submitting orders;
             for example, a planet report (a response to a 'planet list'
             order) will not take into account the ship production which
                                               comes later in that turn.
        ----------------------------------------------------------------

        The fleet list contains a list of all your fleets, with a
        reminder of their planets of origin and their destinations.  The
        list also contains the number of ships in the fleets, and their
        distances from their objectives.  You can use the distance
        figure to work out how long it will be before a fleet arrives.

        As your empire expands, you will want to be able to see more of
        the map.  This information isn't given to you automatically, you
        must request it using the map order.  When you submit a map
        order, you must give the name of a planet around which the map
        will be centred.  You can only centre a map around a planet you
        own, so in order to begin mapping the entire galaxy you must
        start expanding your empire.

3.4.    The Message System

        In order that you can communicate with other empires, to form
        alliances, make threats or gloat over victories, there is a
        message system which passes free-form messages between players.

        To write to another empire, simply submit a 'write' order, along
        with the name of the empire you wish to send to, and the text of
        the message.  Next turn, that empire will receive that message
        with the your empire name identified as the writer (in order
        that he or she can reply).

        It is also possible to write a general announcement to all
        empires.  This is not always a good idea.  Usually your empire
        will be unknown to others until they see your planets, or
        receive a message from you.  Secrecy itself may often be a
        useful weapon, but writing a message to all will immediately
        reveal your existence to everyone else in the game.  Later on in
        the game, if your empire becomes powerful, you could perhaps use
        this facility as a propaganda tool.

        Finally, it is also possible to write messages to the system,
        and receive messages from the system.  Although this has no use
        in the standard game, it is there as a way of communicating with
        add-ons.  Add-ons can scan for messages to the system and
        interpret their contents as extended orders to access features
        in that add-on.  Similarly, replies or information generated by
        add-ons will be addressed as coming from 'the system'.

3.5.    Winning the Game

        The standard victory conditions dictate that the empire who owns
        everybody else's homeworlds wins the game.  This is a change
        from the usual condition of conquering all of everyone else's
        planets, since that condition usually results in a tedious end
        game where the eventual victor has to mop up the remains of
        defeated empires.

        One problem is that enemy homeworlds are not identified.  You
        can assume that, in a normal game, all the homeworlds will have
        a production of 15 ships per turn.  However, not all planets
        with this production are homeworlds.  You just have to hunt out
        all the non-neutral planets with 15 production until you are
        awarded victory.

        When victory is awarded to a player, a report is sent out to
        everyone saying who the winner is.  However, the game must be
        manually stopped and restarted by the person running the game,
        so it is possible that a few turns may go by with the 'victory'
        message being sent out.

        It is quite possible that victory conditions in a game have been
        disabled, making it 'open-ended'.  This means that the game will
        continue indefinitely.

3.6.    Resigning Your Position

        Once your position has become unworkable, or you want to quit
        the game for some other reason like lack of time, there is a
        'resign' command you can use.  Resigning from a game will cause
        all your planets to revert to neutral status, and will make all
        in-transit fleets wink out of existence.

        If you are going to have to stop playing a game, it's polite to
        resign properly.  If you just let your fleets build up
        uselessly, it will get in the way of legitimate players and ruin
        their enjoyment of the game.
.fCustomising Your Game                                               %2d
SECTION 4_______________________________________________________________
                                                   Customising Your Game

        This section gives hints and tips for game moderators creating
        new games, on how to customise the settings in 'detail.data' to
        create interesting variations in gameplay. All the changes
        described here should be made before you attempt to create a
        game using 'astrowar create' described in section 2.

        -Testing--------------------------------------------------------
         When experimenting with changes to the gameplay, it is always a
         good idea to test your games before recruiting players.  Set up
        a local test game and run a few turns before committing yourself
                                to a particular combination of settings.
        ----------------------------------------------------------------

4.1.    Resizing the Galaxy

        There are two changes you can make to the makeup of the galaxy.
        The first is to alter the number of planets, using the 'planets'
        command.  A standard game has 121 planets, but this number can
        be increased or decreased.  To double the number of planets,
        simply include

                planets 242

        in your 'detail.data' file before creating the game.  If you
        want more planets, but with normal density, you will have to
        change the size of the galaxy as well.  This can be done with
        the 'xmax', 'xmin', 'ymax' and 'ymin' commands, as shown in the
        following example:

                xmin -30
                xmax 30
                ymin -30
                ymax 30

        This retains the same approximate density as the smaller-scale
        standard settings.  To retain the normal planetary density as
        used by AstroWar, use the formula:

                side = 4 * ( sqrt(planets) - 1 ) + 1

        where 'side' is the length of one side of the galaxy.  This is
        obviously only relevant for square galaxies, a slightly
        different formula will need to be used for a rectangle.

        -Caution!-------------------------------------------------------
          Too sparse a galaxy can leave some players stranded on planets
          too remote to have any neighbours close enough to see.  Trying
           to put more planets in a galaxy than its size can handle will
         cause the game creator to hang!  Choose these values carefully.
        ----------------------------------------------------------------

        Don't get carried away creating large games, unless you've got
        plenty of time to spare.  The amount of time required to create
        a large galaxy increases exponentially.  If you really need a
        ridiculously large game, consider setting your system up to
        create it over night.

4.2.    Twiddling With Starships

        As well as modifying the galactic parameters, you can also
        meddle with the technology of the starships as well.  You have
        two variables to play with-- speed and maximum distance.

        The speed rating is the number of squares a fleet can move each
        turn.  Modify this with care, and keep in mind the frequency of
        turns as well.  It might be a good idea to give the speed of
        ships an inverse relationship with the speed of the game.  The
        format of the 'speed' command is simply

                speed <squares>

        where <squares> is the number of squares a fleet should move
        each turn. The maximum distance, or 'maxdist' command, takes the
        form:

                maxdist <squares>

        where <squares> is the maximum number of squares a single
        journey can take.  No fleet may be launched directly between two
        planets which are further apart than this; such a journey must
        be split up and be routed via stop-off points.  This simulates
        fuel consumption, and increases the importance of lines of
        defence in the game, since a restricted travel range prevents
        border defences from being ignored.

        -A Note of Caution----------------------------------------------
           Setting too low a figure for 'maxdist' may leave some players
         isolated on small groups of planets which are too far away from
             their nearest neigbours to allow those players to 'escape'.
        ----------------------------------------------------------------

        You can see ship technology settings can have a far bigger
        effect on gameplay than simply changing the size and density of
        the galaxy.  New strategies must be developed to cope with the
        long delays of slow ship travel and the limitations of a finite
        travel range.

4.3.    Victory Conditions and Other Miscellany

        Although AstroWar is intelligent enough not to give an early
        victory to the only player in a game (the first player to join
        owns everyone's homeworlds), a premature victory is possible.
        If the first two players start the game close together, one
        player might take the other player's homeworld before anyone
        else joins the game, giving a premature victory where much of
        the galaxy is left unexplored.

        To prevent such a situation requires a little bit of manual
        intervention in the game.  The 'novictory' command, which takes
        no parameters, disables internal victory checking.  You could
        include this in the game's 'detail.data' file for the first few
        turns, until the game gets moving, and then remove it.  Or you
        could wait until someone gets a 'game full' message before
        taking the 'novictory' out; this ensure that the game doesn't
        end before all planets have been taken or explored.

        It could be that you don't like the standard victory conditions;
        to tell the truth, neither do I.  You could include the
        'novictory' command in your detail file indefinitely, creating
        an open-ended game where you or the players can decide when the
        game is over.

        AstroWar's capacity for add-on software allows the possibility
        of an external victory checker which awards victory based on its
        own victory conditions.  In this case, you would disable the
        internal victory checking, allowing the external program full
        control over victory.

        Victory checking is only one of four phases of turn processing.
        The four phases, in sequence, are movement, order processing,
        production and victory checking.  Any of these four phases may
        be disabled by including one of the following commands in the
        'detail.data':

                nomovement
                noorders
                noproduction
                novictory

        The 'novictory' command has already been discussed.  If a
        'nomovement' command is included, any fleets will just hang in
        space without moving.  This also means that there will be no
        fleet arrivals, no battles and no scouting.  Usually you would
        only include a 'nomovement' command if you had an external
        program to handle fleet movement.

        The 'noorders' command disables order processing.  This means
        there will be no new players, fleet launches, planet or fleet
        lists, maps, messages or resignations processed; all of these
        things are responses to orders.  As with 'nomovement', you would
        probably only include this if you had some external program to
        handle the processing of orders.

        The 'noproduction' command disables ship production.  The
        effects of this are simple to understand, and do not have any
        extra repurcussions.  You might find a use for disabling ship
        production on a turn-by-turn basis, by adding or removing
        'noproduction' between turns.  For example, look at the
        following DOS batch file segment for a game which is processed
        daily:

                ...
                ECHO. | DATE | FIND "Sun"
                IF ERRORLEVEL 1 GOTO NotSunday
                    TYPE detail.data | FIND/V "noproduction">detail.data
                    GOTO Process
                :NotSunday
                    ECHO noproduction>>detail.data
                :Process
                astrowar turn -game whatever
                ...

        This batch file is simple to understand, and an equivalent could
        be written in any batch language.  It looks at the date to see
        if it is Sunday.  If it is, any line in the file 'detail.data'
        containing 'noproduction' is removed.  If it isn't Sunday, a
        'noproduction' command will be added to 'detail.data'.  Don't
        worry about the fact that there will be more than one
        'noproduction' command, AstroWar doesn't care.

        The effect of this batch file on a daily game would be to
        disable production six out of every seven turns.  Coupled with a
        low ship speed, say 1, this could produce an interesting game
        where management of resources is much more important than in
        normal games.

        Another reason for disabling ship production is, as with the
        other 'no...' commands, to allow an external program to take
        over the job of this turn phase.  The production rules in
        AstroWar are about as simple as production rules can get, but
        they could be replaced with something more detailed.
.fDevelopment Notes                                                   %2d
SECTION 5_______________________________________________________________
                                                       Development Notes

        This section of the manual is of interest to developers.  By
        'developers' I include people who are compiling the source
        distribution of AstroWar, as well as those writing add ons and
        interfaces to the program.

5.1.    Recompiling the Source Code

        There are a number of reasons why you might want to recompile
        the source code, rather than using an existing binary
        distribution of the game.  The most obvious reason is that a
        binary distribution might not be available for your platform.
        Or perhaps there is some incompatibility between the appropriate
        binary distribution and your particular system (I know, for
        instance, that my 386 binary distribution will have problems
        with some versions of QEMM).

        Another reason you might want to recompile the source is to
        include some improvement to the basic game which would be
        impossible, or inconvenient, as an external add-on.  In such
        cases you might like to modify AstroWar itself for changes to
        gameplay or interface.

        The source distribution comes with all the necessary tools to
        recompile AstroWar, apart from a C compiler and an
        implementation of 'make'.  If you have C and 'make', and the
        source distribution, you can compile AstroWar.  It uses no
        external libraries, and no assembly code, and is written using
        ANSI C.

        5.1.1. Makefiles and Platform-dependent Definitions

        Once you have extracted the source code into a new directory,
        your first step is to select an appropriate makefile and
        'platform' header.  For users of supported platforms, selection
        of the makefile is simply a case of making a mental note of
        which makefile to use when running 'make'.  If there is no
        makefile for your platform, you will have to create one yourself
        using one of the existing makefiles as a pattern.

        You don't have to use 'make' at all.  Some compilers which have
        integrated development enviroments (GUI or otherwise) have their
        own way of managing large projects, and you might prefer to use
        that rather than 'make'.  But these examples assume you are
        using the standard command line 'make', so you'll have to
        translate the examples into something appropriate for your
        development system.

        After sorting out a makefile, selecting or creating a
        'platform' file is only slightly more involved.  But first, what
        is this 'platform' file I keep talking about?  Well, some
        developers support platform differences by using a multitude of
        '#if's in their source code, to selectively compile different
        sections of program depending on which platform you are using
        (determined by #defined macros).

        I don't like this approach, since it makes my source code messy
        and unreadable, and when you want to add support for a new
        platform you have to keep track of where these code segments
        are.  Keeping them all in one source file is one solution, but
        that tends to compromise the structure of your program.

        The solution I employ is a combination of makefiles and
        'platform' headers.  As well as having a makefile for each
        platform, there is also a 'platform.*' file.  For instance, the
        Linux files are 'makefile.lx' and 'platform.lx'.  All the
        system-specific definitions are kept in 'platform.*', which is
        included (using the filename 'platform.h') in just about every
        source file.  So, for instance, in 'platform.lx' there is a
        line:

                #define stricmp(a,b) strcasecmp(a,b)

        since GCC under Linux uses 'strcasecmp' instead of 'stricmp';
        this approach, in my opinion, is much better than putting '#if's
        for each case-insensitive comparison I make.

        Before you can go on to compile AstroWar, you must create
        'platform.h' with the contents of the appropriate platform
        header.  In some operating systems, such as Unix, you can create
        'platform.h' as a symbolic link to the platform file you need.
        In less sophisticated operating systems, such as DOS, you need
        to copy or rename the appropriate platform.file as 'platform.h'.

        When creating a 'platform.h' for a new platform, use one of the
        existing ones as a pattern, as you did with the makefile.  If
        you need to create a new platform file, I'd be grateful if you
        would send it to me at one of the addresses shown in Appendix C,
        so it can be included in future source distributions. The
        platform header also includes the program's exact title and
        version number, using the macro 'PROGNAME'.  Choose an
        appropriate name for your AstroWar port, as it will appear in
        the log and on the screen when the program is run.

        5.1.2. Building the Executable

        With the correct makefile selected and the 'platform.h' file in
        place, you can proceed to build your executable.  Simply run
        'make' as in the following example:

                make -f makefile.lx

        replacing 'makefile.lx' with the makefile you have chosen for
        your platform.  Upon successful compilation, you will see a
        range of object files, and the final executable.  Once you're
        happy with the executable, you can delete the object files if
        you like.

        5.1.3. Compiling the Documentation

        The documentation for the program is in the file 'astrowar.txt'.
        This is the 'source' for the document 'astrowar.doc', and is
        supplied as such so that you can make any changes you need (see
        later) without having to worry about messing up page formatting.

        To compile the documentation, first you must compile the program
        'doc.c'.  This is a single-file project, so you can just invoke
        your compiler to compile the single file into an executable.
        It's in ANSI C, so you shouldn't have a problem with it.  Using
        GCC (any platform) the command line is:

                gcc doc.c -o doc

        which will create 'doc' or 'doc.exe'.  'Doc' is a public domain
        utility for formatting documents, written specifically so that I
        could distribute documentation for AstroWar and other programs
        in 'source' form, while being sure that people could compile the
        document on any platform.  Feel free to use and distribute
        'doc.c' in your own projects.

        With a compiled executable for 'doc', you can generate the
        repaginated documentation.  Run the following command:

                doc astrowar.txt -o astrowar.doc

        and you will get the repaginated documentation in
        'astrowar.doc'.  When writing 'doc' source yourself, notice the
        format of the '.h' and '.f' commands for headers and footers,
        the inclusion of '^L' characters for forced page breaks.

        'Doc' also semi-intelligent when it comes to inserting its own
        page breaks.  A single-line title will never be separated from
        the following paragraph, and as long as a paragraph is not too
        big to fit on the page, it will not be broken.  So unlike other
        simple page formatters, you can write and edit documents without
        thinking or worrying about where the pagebreaks will fall (as
        long as you use the same paragraph and title format as I do,
        that is).

        5.1.4. Preparing a Binary Archive for Public Release

        AstroWar is distributed under the GNU GPL, and all the
        conditions for distributing your port, or alteration, of
        AstroWar are contained in the file 'COPYING', distributed with
        the source and binary archives.  Read it carefully before
        distributing your version of AstroWar.

        In addition to the conditions, I also have a number of
        suggestions which you might like to follow, in order to help
        you, and me, to keep the software consistent.  You don't have to
        follow them, as the only mandatory conditions are those in
        'copying', but it would be helpful if you did.

        If you have created a port of the standard package to a new
        platform, you might like to consider sending it to me so that it
        can be distributed as an 'official' version.  This means that
        you will be consulted if and when new versions are released, so
        that you can keep your port up to date.

        The official binary distributions all contain the files listed
        in section 2.  Whether your version of the software is intended
        to be 'official' or not, you might like to ensure that at least
        those files listed are included in your package.  That way,
        users following this manual will find everything they need.

        Apart from the executable and documentation you have just
        created, there are the sample files which are included in the
        source distribution.  You can just copy these across to your new
        binary package.

        A 'read.me' file for your version would be useful.  You can use
        an existing 'read.me' from an official binary distribution as a
        pattern if you like.  This 'read.me' file should contain details
        specific to your version or platform, such as hardware and
        software requirements and installation instructions.

        The 'file_id.diz' is a multi-line description of the package,
        and as with the 'read.me', you might like to use a 'file_id.diz'
        from an existing binary distribution as a pattern.  The
        'file_id.diz' description format is widely used in Fidonet for
        importing descriptions into BBS file lists, but it is appearing
        more and more in files at FTP and WWW sites as well.

        -A Note about 'read.me' and 'file_id.diz'-----------------------
              Please don't be tempted to just copy the 'read.me' and the
           'file_id.diz' out of an existing distribution, especially the
                source distribution.  The files with the source code are
           inappropriate for a binary distribution, and the files coming
         with other binary distributions will want at least their titles
                                                               changing.
        ----------------------------------------------------------------

        5.1.5. Source Code Changes and Filename Conventions

        When the source code needs alterations to run on your platform,
        try to restrict changes to the makefile and 'platform' file if
        possible.  Use '#defines' in the platform header to reflect
        differences in library functions ('stricmp', for instance). If
        some functions are missing from your compiler, add an extra
        source file with an implementation of the function in it, put a
        reference to that source file in the makefile, and put the
        function declaration in the platform header.

        There are advantages to this approach, particularly if you want
        to keep your version up to date with the official one.  If you
        make changes to the other source files, you will have to make
        that same change to the source files for each new version of
        AstroWar.  If there are a multitude of changes you will have
        quite a bit of work ahead of you.

        There may be a reason that you need to change the existing C
        source, though.  Perhaps I use a function which has no
        equivalent in your compiler, and some task needs doing in a
        completely different way using whatever functions your system
        offers.  Or maybe you're using a GUI, and find AstroWar's
        text-based output unsuitable.

        In these cases, when you change a source file, keep the original
        intact and save your altered source file under a different name.
        Then change your makefile to refer to the new source file
        instead of the old one.  This way, your new source can be
        included in the official source distribution alongside the
        standard source code.

        There is a standard filename convention I use in these cases.
        You'll notice that all the base filenames are six characters or
        less.  This leaves an extra two characters for variations on the
        standard source files, and I usually add something in the format
        '_<letter>' where <letter> identifies the port.  So, an
        alteration to 'scrlog.c' for Windows might be named
        'scrlog_w.c'.  The Windows makefile would refer to 'scrlog_w.c'
        instead of 'scrlog.c', although all the functions within the
        source file would retain their existing names.

        In addition, the following filename conventions are used for the
        official distributions of AstroWar:

                ast100.*                Source distribution
                ast100<letter>.*        Binary distribution

        Where <letter> is a letter identifying the binary distribution.
        It is the same as the <letter> used for any extra source files,
        as described a moment ago.

5.2.    Developing an Interface

        AstroWar, as has already been noted, can be played using a
        variety of interfaces.  This subsection contains some ideas and
        technical details about creating an interface for AstroWar.  See
        also the notes in the next subsection about the AstroWar API.

        First, what sort of interfaces can we have?  The existing
        AstroMail interface allows play via Fidonet netmail, using a
        traditional PBeM format of orders sent to the host, and reports
        coming back in the text of messages.  These reports come back as
        a combination of paragraphed text, tables and semi-graphical
        ASCII map images.  An obvious development from this is a similar
        interface for the Internet, or other email systems.

        Many games with a play-by-mail option are graphical, and a
        graphical interface for AstroWar is possible; users can click on
        planets or command buttons to issue their orders.  Such a
        program can be implemented as a turn viewer for AstroMail text
        reports, or as an interface to the binary orders and report
        files on a local system. There are other possibilities, too.  A
        BBS door game, a web game, even a pen-and-paper PBM if someone
        thought it was worth the effort for such a simple game.

        Exact details of file formats can be found in Appendix B of this
        manual.

        5.2.1. The Rudiments of Interface Writing

        An interface program for AstroWar has two jobs.  First, it
        receives orders from the players and saves them in the
        'orders.data' file.  Second, it takes reports from 'report.data'
        and presents them to the players.

        A useful interface might do other things, like showing the game
        details from 'detail.data', providing useful forecasts to help
        the players, or maintaining a master map for each player
        combining all the maps and planet details they have ever
        received.

        But it is the first two jobs which concern us here.  In this
        subsection I will describe how to carry out the essentials, and
        leave the extras at your discretion.  You will want to add
        extras, even AstroMail goes a little way beyond the simple
        relaying of orders.

        5.2.2. Joining Players to a Game

        First, I will discuss joining players to a game, since the
        processing of join reports and orders differs slightly from the
        rest of the orders.

        Most orders in the 'orders.data' file are self-sufficient; they
        contain all the information needed to successfully process the
        orders.  Similarly, most 'report.data' reports are
        self-sufficient in the same way.  However, the processing of
        orders and reports concerning new players requires certain
        details to be stored externally for later use.

        A 'join' order contains two parameters.  One is the empire name
        the player wishes to use.  The other is a unique 'transaction
        number'.  The transaction number is necessary because we can't
        rely on a new empire name being unique; two players may attempt
        to join using the same name.  When the second player attempts to
        join, we need to differentiate the reply to this 'join' order
        from the reports being sent to the first player.  This is done
        using transaction numbers.

        When the 'join' report, successful or otherwise, comes back from
        AstroWar after order processing, this transaction number
        identifies the 'join' order to which the report is replying.
        Therefore, as you receive each join order from a player, you
        have to store its details somewhere, along with the transaction
        number, so that when the join report comes back you know who to
        send it to.

        AstroMail uses a 'join request queue' to do this. On receipt of
        a join order, it stores the user details and the transaction
        number as a record in the queue.  It deletes this record when a
        join report comes back; if the join report accepts the new
        player, the player details are moved to a player file for that
        game, otherwise they are discarded once the report has been
        relayed to the user.

        The transaction number has to be unique across all interfaces.
        If two different interfaces are using the same transaction
        number, they will get confused and start replying to each
        other's players.  AstroMail uses a file 'transaction.data' in
        each game directory.  This is a four-byte file containing a
        32-bit integer in little-endian format, and AstroMail use this
        each time it needs a transaction number.  The transaction number
        is incremented AFTER use, and is then written back to the
        'transaction.data' file.  I suggest that your interface uses
        this same file, in the same way.

        5.2.3. Accepting Orders from Players

        When taking orders from players, first you should ensure that
        the player is actually playing in the game.  Generally AstroWar
        ignores orders from non-existent empires, but if a player has
        been rejected due to choosing a duplicate name, it's important
        not to allow the user to start submitting orders under that
        name-- such orders will be interpreted as coming from the 'real'
        player using the name.

        You can solve this problem by keeping a player file for each
        game, specifically for players using your interface.  Each time
        a join request is accepted, add the new player (user details and
        empire name) to the player file.  When an order is received from
        a user, you can then check that the user has been accepted in
        the game, and at the same time, match the user details with an
        empire name which will be used when writing the orders to
        'orders.data'.

        5.2.4. Sending Reports to Players

        Sending reports is a little more involved.  If you are thinking
        in terms of a multi-user mail interface like AstroMail, you must
        be prepared to deal with more than one user at a time.  The
        technique I use is to read through the records in 'report.data'
        building up a series of temporary files, one for each player.
        Once that pass is complete, I then pick up the temporary files
        in turn, and send them to the players.

        In this case, you need to make use of the player file you
        maintain for users of your interface.  Remember, the report file
        will contain records not only for your players, but for users of
        other interfaces as well.  You should ignore the report records
        which are not destined for your players.

        Remember also that you need to process 'join' reports as well as
        regular player reports.  So on reading a 'join' report, you need
        to look up the transaction number in your join request queue.
        If it's there, deal with it as described earlier.  If not,
        ignore it since it's probably for a user of another interface.

        The second approach is more appropriate for graphical and other
        interactive interfaces.  In these, you will usually be
        interacting with one user at a time.  So after looking in the
        player file for the empire details of that particular user, you
        only need to process reports addressed to that user's empire,
        and ignore all the rest.  This works on the assumption that the
        other players who use your interface will be along later to look
        at their reports, so you repeat the process for them at that
        time.

        -A Note About Interpreting Reports------------------------------
              When interpreting reports, give the planet and fleet lists
         priority over other reports.  External utilities may add fleets
               without a 'send' order, or alter planet details (even the
           production or position) without the appropriate report.  Your
          interface will have to pick these things up via the planet and
                                                          fleet reports.
        ----------------------------------------------------------------

        5.2.5. Some Do's and Don'ts

        The rudiments of writing an interface have been just about
        covered.  But when thinking about extending your user interface,
        there are some points you need to keep in mind, given in this
        section.

        Don't allow your players any more information than they should
        have, according to the rules of the game.  If players using your
        interface have unfair advantages over users of other interfaces,
        those running games might be hesitant about using your
        interface at all.  The simple way to achieve this is to leave
        the files 'planet.*', 'fleets.*' and 'empire.*' well alone,
        don't open them even for reading. Just stick to accessing the
        'report.data' and 'orders.data' files, along with any other
        files of your own making.

        You can, of course, build up your own map, fleet, empire and
        planet files from information extracted from the report file,
        since this is no more than the players could do themselves.
        AstroMail itself keeps a fleet file, 'pfleet.*', used to remind
        players about where fleets were going to and from, since fleet
        arrival, intelligence and battle reports in 'report.data' do not
        contain this information.  But the important thing to remember
        is that AstroMail builds these files up from records read from
        'report.data', it does not access 'fleets.data' to get fleet
        details.

5.3.    Writing Add-on Utilities

        The number of ideas for add-on utilities for AstroWar is almost
        endless.  You could write replacements for any of the four turn
        phases (fleet movement, order processing, production or victory
        checking).  You could write a replacement for 'create', giving
        more variation in the shape and makeup of the galaxy.  You could
        write a program which runs through the planet file at the start
        of a game, replacing those awful names that AstroWar comes up
        with.

        Or, instead of replacing an existing part of the game, you could
        write something that adds to game play.  Simple ideas like ion
        storms, which reduce the strength of nearby fleets and orbital
        defenses, or mega-weapons which can be aimed at nearby planets,
        can be quite effective.  Even simpler ideas like stats or
        rankings generators can add value to the game.

        The rest of this subsection gives some tips and technical
        information about writing add-ons for AstroWar.

        5.3.1. The 'AstroWar API'

        Some of the source code for AstroWar isn't covered by the GNU
        GPL, but is public domain.  These files form the AstroWar API,
        allowing you to read and write to AstroWar's data files without
        concerning yourself with byte-by-byte details of the file
        structures.

        I recommend that you use this API rather than writing to the
        files directly.  Most of the files have indexes that must be
        maintained, and you'll save yourself a lot of work by calling
        the API routines to write and sort records, rather than writing
        your own routines to do the same thing.

        This, of course, dictates that you have a C compiler.  You don't
        have to use C to write your applications though, as most
        compilers have the capability of interacting with code written
        in other languages.

        The API makes use of hidden data.  You don't have access to the
        fields of the record structures for the game list, config files,
        orders, reports, planets, fleets or empires.  Instead, you use
        API functions to 'set' or 'get' the values of the fields in a
        record.  This means that when the file structures are altered or
        extended, you should be able to link your existing code to the
        extended API without changing (or even recompiling).

        You could copy the structure definitions from the API into your
        own code and access a record directly, but I don't recommend
        this, since you lose the advantages of the hidden data
        structures.  In particular, modification of some fields has
        hidden side effects, without which the API will not work
        properly.

        Most parts of the API have a similar pattern, based around
        standard database access.  You dynamically create memory for
        records using '..._new' and '..._old' routines.  You access
        records using '..._first', '..._last', '..._next', '..._prev'
        and '..._find' routines.  You write using '..._write' or
        '..._delete' routines.  You access individual fields using
        '..._set...' and '..._get...' routines.  All of these routines
        take care of such things as header verification, index
        maintenance and limited file integrity checking.

        A full list of API functions is not included with this manual,
        since it is rather large.  You can find out the format of all
        the functions by looking in the '.h' files in the source code
        distribution.  However, a couple of small examples might help
        you get started in using the API.  The following program prints
        out a list of empires from a game in the current directory:

                int main(void)
                {
                    result  r;
                    empire *e = empire_new()
                    char    name[16];

                    /* open file and list empires */
                    if(( r = empire_open("") ) == R_OK)
                    {
                        puts("Empire list:");
                        r = empire_first(e, E_NAME);
                        while(r == R_OK)
                        {
                            empire_getname(name, e);
                            printf("    %s\n", name);
                            r = empire_next(e, E_NAME);
                        }
                        r = R_OK; /* set all OK */
                    }

                    /* close files and return */
                    empire_close();
                    empire_old(e);
                    return r;
                }

        This example only illustrates the workings of some of the API
        routines, but you should get the general idea of how the API
        works from this.  I don't check for success on 'empire_new'
        since the empire record is only 33 bytes.  Purists may prefer to
        check every '_new' allocation, but this will increase the amount
        of code immensely.

        'Result' is simply an enumerated type, with various values all
        starting 'R_', as in 'R_OK'.  'E_NAME' is another enumerated
        value, specifying the 'name' index is to be used in reading
        records ('E_NONE' means read the file non-indexed).

        -About Reading Without Indexes----------------------------------
           Do not update indexed files when reading through them without
        using indexes.  The files will be corrupted if you do this.  Non
              indexed reads are only intended for reading through a file
                   quickly, such as creating totals or other statistics.
        ----------------------------------------------------------------

        5.3.2. Communicating with Players

        Many utilities will need some way to communicate with players,
        either in receiving special orders or sending out reports.  It
        is not a good idea to try and add new record types to the
        'orders' and 'report' files though, as this will make your
        utility incompatible with other programs (including AstroWar).

        Fortunately, a way around this has been provided, using the
        message system.  Messages may be addressed to or from 'the
        system', by putting a blank string in the appropriate field.

        Messages in the order file which are addressed to the system are
        simply ignored by AstroWar.  So one way to allow players to
        communicate with external programs is to look through the orders
        file, for messages to the system, containing a particular
        pattern of text.  My recommendation is to look for the name of
        your utility, followed by a colon, at the start of any message
        to the system.  If you find it, you can assume that the text
        that follows in that message will be intended for your utility.

        Similarly, a program can send a report to a player by adding a
        message to the report file, addressed from the system.  Precise
        formatting for these messages is only required if you want your
        messages to be interpreted by software at the player's end, for
        instance, if you want your utility to be directly supported by
        interface programs.
.fTroubleshooting                                                     %2d
SECTION 6_______________________________________________________________
                                                         Troubleshooting

        This section takes some errors which may appear in the log or on
        the screen, and provides some explanation as to why they might
        be given.

6.1.    Cannot open log file <filename>

        For some reason, Astrowar cannot open the log file for output.
        AstroWar will not run without a log file.  The most likely
        explanation for this is that you have mis-typed a directory
        name.

        Another explanation is that you are trying to share log files in
        a multitasking environment.  If this is the case, make sure that
        either (a) AstroWar has its own non-shared log-file, or (b) that
        AstroWar never runs concurrently with any program whose log file
        it shares.

6.2.    Command line error: type 'astrowar ?' for help

        Obvious.  A list of valid commands is given when you follow the
        instruction.  Alternatively, a more complete command line guide
        is given in appendix A.

6.3.    AstroWar already running

        AstroWar shouldn't be run concurrently with itself, or with
        anything else which uses its data files.  It protects against
        this happening using a semaphore file, 'astrowar.sem', saved in
        the main AstroWar directory.

        If AstroWar is interrupted (or crashes) in such a way that it
        cannot exit gratefully, this file will be left in the AstroWar
        directory and must be deleted before AstroWar can be run again.

        AstroMail, and possibly other interfaces, use the 'astrowar.sem'
        file as well, to ensure that they are not run at the same time
        as AstroWar.  So if AstroWar is not running, make sure no other
        AstroWar utilies are running before deleting this semaphore.

6.4.    Out of memory <action>

        AstroWar has run out of memory.  This is unlikely, since
        AstroWar is not a memory hog.  The names of all games are read
        into memory at once, so if you try and run a couple of million
        games at one AstroWar installation, you might come across this.

        Alternatively, this might come about because of incompatibility
        with some memory manager or swap system.  If this is the case,
        there's not much you can do about it, apart from use another
        memory manager, or see if you can find another distribution of
        the software for your platform (compiled with a different
        compiler).

6.5.    Bad return code <number> from <technobabble>

        This is one of those awful return codes you can do nothing
        about, and it means that I haven't done my job properly.  It
        shows that two parts of the program aren't matching up properly.
        If you see this, please send an exact copy of your log file to
        me, along with precise details of the AstroWar version you are
        using, and what platform you are running it on.

6.6.    Bad command in line <number> of <path>astrowar.data

        Another obvious one.  You've made a typo in your configuration
        file, on the line indicated.  The sample configuration file
        'astrowar.sam' contains comments showing the exact format of
        each configuration command; at the time of writing there's only
        one.  You can also find a full explanation of all configuration
        commands from all of AstroWar's text files, in Appendix A of
        this manual.

6.7.    Cannot read config file <filename>

        The configuration file cannot be read.  If the configuration
        file is present, this could be a mis-typed pathname on the
        command line or in the ASTROWAR environment variable described
        in Appendix A.

6.8.    Cannot open detail file <filename>

        A detail file is not present.  If you know the file exists,
        check the pathname.

6.9.    Bad command in detail file <filename>

        Check all the commands in the named detail file.  If you can't
        find the error, start taking lines away until the error goes
        away.  One common mistake that even I make from time to time is
        to use the non-existent command 'game' when I mean to write
        'name', so you could check for this first.

6.10.   Cannot open game list <filename>

        Another self explanatory one.  Check that your game list file
        exists, and that the pathname shown is correct.

6.11.   Bad detail file (line <line> in <gamelistfile>)

        Similar to the error described in 6.9, but this one is
        encountered when reading the game list (as the game list is
        read, the detail file in each directory is checked).  Check the
        line <line> in your game list file, to see which detail file
        caused the error.  Then look at that detail file; refer to
        section 6.9 for more information on debugging detail files.

6.12.   Bad line <line> in game list <file>

        One of the lines in your game list is neither a comment nor an
        existing directory containing a 'detail.data' file.

6.13.   Game list <filename> is empty

        Running AstroWar without at least one game set up is a waste of
        time.  Ensure that you have at least one path in your game list
        file, and that the directory contains a 'detail.data'.

6.14.   Game <name> not found

        You have attempted to create or process a game which has not
        been set up in the game list file.  The most common cause of
        this is a typing error in the game name on the command line.

6.15.   Cannot open file <filename>

        One of AstroWar's data files cannot be opened.  This is
        sometimes a result of processing a game before you've created
        it.

6.16.   Bad header in file <filename>

        Each of AstroWar's binary data files contains an eight byte
        header, which confirms the file type and version number.  This
        error occurs when the header is not as expected for a given
        file.

        The most obvious cause is file corruption.  Another possible
        cause is that you're running an earlier version of AstroWar than
        that which created the data files.  It is quite possible that in
        future releases of AstroWar, the structures of some data files
        will be changed, in which case earlier versions of AstroWar may
        not be able to read the data files created by later versions.

6.17.   File <filename> already exists

        Occurs when you attempt to create a file which already exists.
        There are two common causes for this.

        Firstly, if you create a game which already exists (or partially
        exists), you will get this error and AstroWar will stop.  Before
        creating a game, make sure that the game directory is empty,
        apart from the 'detail.data' and perhaps some third party
        utility configuration files.

        Secondly, this occurs when you process a turn, and the last
        turn's 'report.data' is still present in the directory.  Ensure
        that at some point between the turns, you delete the previous
        turn's report file.

6.18.   Cannot create file <filename>

        A file error has occurred when trying to create one of
        AstroWar's data files.  Ensure that the directory exists, and
        that it is not read only.
.fAppendix A - General Reference                                      %2d
APPENDIX A______________________________________________________________
                                                       General Reference

        This appendix contains just about everything you need to know
        about AstroWar's command lines, config files, and the orders and
        reports produced, from a non-technical point of view.

A.1.    The Command Line, Environment and Error Levels

        The format of the AstroWar command line is

                astrowar <command> <switches>

        <command> can be one of the following:

                create          which creates a game,
                turn            which processes a turn, or
                ?               which displays a brief help screen.

        and <switches> are one or more of the following:

                -game <name>    The game to be created (mandatory),
                -path <dir>     Path to the 'astrowar.data' and
                                'gamelist.data' files.

        If you miss out '-path', AstroWar looks in the current directory
        for its data files.  Instead of using the '-path' switch to
        point AstroWar to data files elsewhere, you can use the
        'ASTROWAR' environment variable.

        -Specifying a Path Name-----------------------------------------
              When specifying a pathname using the '-path' switch or the
           'ASTROWAR' environment variable, make sure you put a trailing
         slash or backslash (or other directory separator) at the end of
                        the pathname, as your operating system requires.
        ----------------------------------------------------------------

        AstroWar returns one of a number of error levels when it exits.
        You can use these to determine whether a run was successful or
        not, and why it might have failed.  This is especially useful
        when you are running AstroWar automatically overnight, as you
        can trap errors and somehow bring them to your attention (by
        posting a message, for example).  The error levels are:

                0       everything went OK
                3       error accessing some file or other
                4       bad header encountered in a file
                5       a file to be created already exists
                7       possible corrupt file or index
                9       out of memory
                10      bad command encountered

A.2.    Configuration File Commands

        This part of the appendix shows the composition of AstroWar's
        ASCII configuration files.  In all files, a blank line, or any
        line starting with a semi-colon (;) is regarded as a comment.

        There is only one command in 'astrowar.data', which is
        'logfile'.  Its format is as follows:

                logfile <filename>

        where <filename> is the full path and filename of the log file.
        The log file is stored in FrontDoor format, so Fidonet sysops
        running AstroWar can integrate their log files.

        The 'gamelist.data' file contains no commands, but instead
        contains a list of directories in which games reside.  Each
        directory name must be followed by a trailing directory
        separator (slash, backslash or something else, as required by
        your operating system).

        The 'detail.data' file contains a range of commands for
        controlling game settings both at creation time and afterwards.
        The commands are as follows:

            name <gamename>     This sets the name of the game, and is
                                the only mandatory command in the detail
                                file.

            planets <num>       Sets the number of planets in the game,
                                and is only used by AstroWar when
                                creating a game.  It may be used later
                                by other utilities, however, so leave it
                                alone once you've created the game.
                                <Num> defaults to 121.

            xmin <num>          The minimum and maximum X and Y
            xmax <num>          co-ordinates of planets on the map.
            ymin <num>          Used when creating the game, these
            ymax <num>          commands allow you to control the size
                                of the galaxy.  As with 'planets', other
                                programs might use these figures after
                                the game has started, so don't meddle
                                with them once the game is running.
                                Note that <num> may be positive or
                                negative in any of these, but ensure
                                that the 'min' values are always less
                                than the 'max' values, otherwise you'll
                                get an 'invalid detail file' error.

            speed <num>         This is the number of squares a fleet
                                will travel each turn.  Used when
                                processing fleet movements, this may or
                                may not have any effect on external
                                fleet movement processors.

            maxdist <num>       This is the maximum number of squares a
                                fleet may travel in a single journey,
                                used when processing fleet movements.
                                It may or may not have any effect on
                                external fleet movement processors.

            nomovement          These four commands disable various
            noorders            phases of turn processing: fleet
            noproduction        movement, order processing, ship
            novictory           production and victory checking.  They
                                are checked each time you process a
                                turn, so you may add or remove them as
                                you please at any time during a game.

A.3.    Orders

        This section gives a list of orders understood by the order
        processing phase of turn processing.  The format of the orders
        as shown below is a vague abstraction of what is stored; exact
        details of the file formats are given in Appendix B.

            join <empire>       A join order, or join request, asking
                                that a player be added to the game with
                                the empire name <empire>.

            send <n> <o> <d>    A send order.  Orders a launch of <n>
                                ships from planet <o> to planet <d>,
                                where <o> is owned by this empire and
                                there are at least <n> ships in orbit.

            planets             Requests a list of the planets owned by
                                this empire.

            fleets              Requests a list of fleets belonging to
                                this empire.

            map <planet>        Requests a map of the area around
                                <planet>, showing the names and
                                positions of all planets within 7
                                squares of this centre planet.

            write <emp> <txt>   Write a message to empire <emp>,
                                containing the text <txt>.  <Emp> may be
                                an empire name, All ("*") or The System
                                (""), and <txt> may be up to 64k of text
                                spread across multiple lines.

            resign              Requests that this empire is removed
                                from the game.  All planets revert to
                                neutral ownership (with ships in orbit
                                remaining), and all fleets will
                                magically disappear.

A.4.    Reports

        This section gives a list of reports generated by the program.
        The parameters given, like those for orders, are only an
        abstraction of what is stored.  Precise details of the format of
        'report.data' are given in Appendix B.

            join <home>         Confirmation of a join request, giving
                                the homeworld name.  A join report is
                                always followed by a planet list and a
                                map image.

            nojoin <reason>     Rejection of a join request, giving the
                                reason why the request was rejected.
                                Possible reasons are that the game is
                                full, or that a duplicate empire name
                                was chosen.

            send <f><s><o><d>   Confirmation of a fleet launch, as
                                requested by a send order.  <F> is the
                                fleet number of the new fleet, <s> is
                                the number of ships sent, <o> is the
                                planet of origin and <d> is the
                                destination.

            nosend <s><o><d><r> Rejection of a fleet launch order.  <S>
                                is the number of ships to be sent, <o>
                                is the planet of origin, <d> is the
                                destination, and <r> is the reason the
                                ships couldn't be sent.  Possible
                                reasons are numerous, for example: the
                                player doesn't own the origin planet,
                                the origin planet is unknown (possibly
                                misspelled), the destination planet is
                                unknown (again, possibly misspelled),
                                there are not enough ships at <o>, or
                                <o> and <d> are too far apart.

            planets...<etc>     A planet list, given in response to a
                                planet list request.  Followed by a list
                                of planets owned by this player, giving
                                name, position, production and total
                                ships in orbit for each.

            fleets...<etc>      A fleet list, given in response to a
                                fleet list request.  Followed by a list
                                of fleets owned by this player, giving
                                fleet number, origin and destination
                                planets, ships in the fleet and distance
                                left to travel.

            map <planet>...     A map image, given in response to a map
                                order.  <Planet> is the planet at the
                                centre of the map, and following this is
                                a list of planets, each with its
                                position.  This data can be assembled by
                                the player or the interface software
                                into something resembling a map.

            nomap <planet> <r>  A rejection of a map order.  <Planet> is
                                the name of the planet the map was to be
                                centred on, and <r> is the reason why
                                the map couldn't be made.  Possible
                                reasons are that the planet is not owned
                                by the player requesting the map, and
                                that the planet is completely unknown,
                                possibly misspelled.

            write <emp> <txt>   A message.  <Emp> is the empire which
                                sent the message (or The System, "") and
                                <txt> is the message text.

            nowrite <emp> <r>   A bounced message.  <Emp> is the
                                intended recipient, and <r> is the
                                reason the message couldn't be sent.
                                The only reason in this version of
                                AstroWar is that the destination empire
                                doesn't exist.  This could be because
                                the name was misspelled, or because the
                                empire has resigned from the game.

            victory <emp>       A victory report, showing that the game
                                has been won by <emp>.

            arrival <f>         An arrival report, showing that fleet
                                <f> has arrived at its destination.  It
                                is up to the player or the interface
                                software to remember what the
                                destination was, and how many ships were
                                in the fleet.

            intelligence <f>    An intelligence report from fleet <f>.
                <p><o><s>       <p> is the production, <o> is the owner,
                                and <s> is the number of ships in orbit.
                                It is up to the player or the interface
                                software to keep track of which planet
                                the fleet was bound for, and which was
                                the planet of origin in order that the
                                later 'arrival' report can be fully
                                understood.

            battle <f><o><s><e> A battle report.  Fleet <f> has arrived
                                at its destination and attacked the
                                ships in orbit belonging to <o>.  After
                                the battle, <s> of the attacker's ships
                                and <e> ships of the enemy remain.  If
                                <s> is zero, the attacker lost, if <e>
                                is zero, the attacker took the planet.
                                A battle report is always followed by a
                                defence report for the player who was
                                attacked (if the planet was not
                                neutral).  It is up to the attacker or
                                the interface software to remember what
                                planet <f> was bound for.

            defence             A defence report.  Planet <p> has been
                <p><o><s><e>    attacked by a fleet belonging to <o>.
                                <s> of the defender's ships and <e> of
                                the attackers ships remain.  If <s> is
                                zero, the planet has been taken by the
                                attacker, otherwise it remains in the
                                defender's posession.
.fAppendix B - Binary File Formats                                    %2d
APPENDIX B______________________________________________________________
                                                     Binary File Formats

        It is assumed that, if you are using C, you will be making use
        of the AstroWar API.  So, to make a refreshing change, the file
        format descriptions in this appendix will be in BASIC format,
        that is, the format used by QBASIC, Visual BASIC and various
        other compatible PC-based BASIC languages.  I would use Pascal,
        but I don't know any Pascal so BASIC will have to do.

        -A Note About Text Values---------------------------------------
           All text values in AstroWar's files are null-terminated.  You
                will have to make sure your program processes and writes
        null-terminated string values correctly.  The recommended course
         of action is to write an equivalent to the AstroWar API in your
            language, and have the 'set' and 'get' routines do the work.
        ----------------------------------------------------------------

B.1.    The Indexed Databases

        The indexed databases are the easiest to understand of all the
        files.  Although there are indexes to maintain, each record is
        the same; this applies to the index files and the data files.
        There are no variant records (unions) or sub-records here, such
        unpleasantness can wait until you tackle the orders and report
        files.

B.1.1.  The Empire File

        The empire file is named 'empire.data', and its index file is
        named 'empire.index'.  The first eight bytes of 'empire.data'
        are the null-terminated string 'AST100E', with the records
        starting on the 9th byte of the file.  The equivalent 8-byte
        header for 'empire.index' is 'AST100e'. Their definitions are as
        follows:

                '
                ' **** Definition of records in empire.index ****
                '
                TYPE EmpireIndex
                    RecPos  AS LONG ' position of record - 1
                    EmpName AS STRING * 16
                END TYPE
                '
                ' **** Definition of records in empire.data ****
                '
                TYPE EmpireRecord
                    Deleted   AS STRING * 1  ' = ASCII 1 when deleted
                    EmpName   AS STRING * 16 ' empire name
                    Homeworld AS STRING * 16 ' planet name of homeworld
                END TYPE

        A small section of BASIC code for reading a record follows.  It
        assumes that the index file is #1 and the data file is #2 (both
        opened as BINARY), and that the index file pointer points to the
        start of the next index record:

                DIM EIndex AS EmpireIndex
                DIM Empire AS EmpireRecord
                GET #1, , EIndex
                GET #2, EIndex.RecPos + 1, EmpireRecord

        Note that we add 1 to the EIndex.RecPos.  The first byte of the
        file is 0 in C, or 1 in BASIC.

B.1.2.  The Fleets File

        The fleets files are named 'fleets.data' and 'fleets.index', and
        their 8-byte headers are the null-terminated strings 'AST100F'
        and 'AST100f' respectively.  Their records are defined as
        follows:

                '
                ' **** Definition of records in fleets.index ****
                '
                TYPE FleetsIndex
                    RecPos  AS LONG
                    FleetNo AS LONG
                END TYPE
                '
                ' **** Definition of records in fleets.data ****
                '
                TYPE FleetsRecord
                    Deleted AS STRING * 1  ' = ASCII 1 for deleted
                    FleetNo AS LONG        ' fleet number
                    Owner   AS STRING * 16 ' empire name of owner
                    Origin  AS STRING * 16 ' planet of origin
                    Dest    AS STRING * 16 ' destination planet
                    Ships   AS LONG        ' ships in fleet
                    Distnce AS INTEGER     ' distance from dest
                END TYPE

        The code for reading a record from the fleet file would be
        broadly similar to that shown for the empire file in B.1.1.

B.1.3.  The Planet File

        The planet files are named 'planet.data' and 'planet.index'.
        Their 8-byte headers are the null-terminated strings 'AST100P'
        and 'AST100p' respectively.  The format of the records is:

                '
                ' **** Definition of a record in planets.index ****
                '
                TYPE PlanetIndex
                    RecPos AS LONG
                    PName  AS STRING * 16
                END TYPE
                '
                ' **** Definition of a record in planets.data ****
                '
                TYPE PlanetRecord
                    Deleted AS STRING * 1  ' = ASCII 1 if deleted
                    PName   AS STRING * 16 ' planet name
                    Owner   AS STRING * 16 ' empire name of owner
                    XPos    AS INTEGER     ' X position
                    YPos    AS INTEGER     ' Y position
                    Prod    AS INTEGER     ' Production
                    Ships   AS LONG        ' Ships in orbit
                END TYPE

        When a planet is neutral, Owner is a null string.  The code for
        reading a planet record is similar to that for reading an empire
        record.

B.2.    The Orders File

        Orders are not stored in an indexed database, but in a serial
        binary file.  This file is called 'orders.data', and has an
        8-byte header like the database files.  The header is the null
        terminated string 'AST100O' (note the last three characters are
        two numbers and a capital letter).

        There are seven different types of record in this file, each
        corresponding to one of the orders listed in appendix A.  When
        reading an order record, you need to read the first character in
        order to see what the format of the rest of the record is.  The
        comments in the following structures assume this character was
        read into the variable 'OrderType', defined using 'DIM OrderType
        AS STRING * 1'.

                '
                ' **** Join order, where OrderType = "J" ****
                '
                TYPE JoinOrder
                    TransNo AS LONG      ' transaction number
                    EName AS STRING * 16 ' desired empire name
                END TYPE

                '
                ' **** Send order, where OrderType = "S" ****
                '
                TYPE SendOrder
                    EName  AS STRING * 16 ' Empire giving the order
                    Origin AS STRING * 16 ' Planet of origin
                    Dest   AS STRING * 16 ' Destination planet
                    Ships  AS LONG        ' Ships to send
                END TYPE

                '
                ' **** Planets order, where OrderType = "P" ****
                '
                TYPE PlanetsOrder
                    EName  AS STRING * 16 ' Empire giving the order
                END TYPE

                '
                ' **** Fleets order, where OrderType = "F" ****
                '
                TYPE FleetsOrder
                    EName  AS STRING * 16 ' Empire giving the order
                END TYPE

                '
                ' **** Map order, where OrderType = "M" ****
                '
                TYPE MapOrder
                    EName  AS STRING * 16 ' empire giving the order
                    Centre AS STRING * 16 ' planet at map centre
                END TYPE

                '
                ' **** Write order, where OrderType = "W" ****
                '      Text is variable length in the file, terminated
                '      by a null byte (ASCII 0)
                '
                TYPE WriteOrder
                    EName AS STRING * 16   ' empire writing the message
                    Recip AS STRING * 16   ' intended recipient
                    Text  AS STRING * 4096 ' go easy on the string space
                END TYPE

                '
                ' **** Resign order, where OrderType = "R" ****
                '
                TYPE ResignOrder
                    EName AS STRING * 16 ' empire issuing the order
                END TYPE

        As an example of code to read the orders file, I'll start you
        off with this snippet.

                DIM OrderType AS STRING * 1
                DIM Join AS JoinOrder
                ' ... and the rest ...
                GET #1, , OrderType
                SELECT CASE OrderType
                    CASE "J"
                        GET #1, , Join
                    CASE "S"
                        ' ... etc ...
                END SELECT

        This assumes that the orders file has been read, and that the
        file position is just at the start of an order record.  The
        message (write order) record is a bit fiddly to read, but there
        are various solutions.  Reading the record byte by byte until
        you find the NUL isn't recommended, it might be better to read a
        chunk of the file, find the NUL in memory, and work out from
        this where the file pointer should really be positioned before
        reading the next order record.

B.3.    The Report File

        If you thought that the orders file was a bit fiddly and hard to
        read, take a look at the report file.  It has the variant
        records like the orders file, but some of these records have
        series of other records within them.  Luckily, these records
        within records are not variant records themselves.

        There are 15 different record types in the report file (not
        counting the sub-records), and as with the order file, you need
        to read the first character of each report record to find out
        what type of record follows.  The comments in the following
        structures assume that the string variable 'ReportType' is used
        to hold this character.

                '
                ' **** Join report, where ReportType = "J" ****
                '
                TYPE JoinReport
                    TransNo AS LONG        ' transaction number
                    Homewld AS STRING * 16 ' homeworld
                END TYPE
                '
                ' **** Join error, where ReportType = "j" ****
                '      Reason is one of the following:
                '       "D" - duplicate empire name
                '       "F" - game full
                '
                TYPE JoinError
                    TransNo AS LONG       ' transaction number
                    Reason  AS STRING * 1 ' reason for error
                END TYPE

                '
                ' **** Send report, where ReportType = "S" ****
                '
                TYPE SendReport
                    EName   AS STRING * 16 ' empire name
                    FleetNo AS LONG        ' new fleet number
                    Origin  AS STRING * 16 ' planet of origin
                    Dest    AS STRING * 16 ' destination planet
                    Ships   AS STRING * 16 ' ships in fleet
                END TYPE
                '
                ' **** Send error, where ReportType = "s" ****
                '      Reason is one of the following:
                '       "D" - destination unknown
                '       "O" - origin unknown
                '       "U" - origin is someone else's planet
                '       "S" - not enough ships (or ships to send < 1)
                '       "M" - fleet sent too far
                '
                TYPE SendError
                    EName  AS STRING * 16 ' empire name
                    Origin AS STRING * 16 ' planet of origin
                    Dest   AS STRING * 16 ' destination planet
                    Ships  AS LONG        ' intended fleet size
                    Reason AS STRING * 1  ' reason for error
                END TYPE

                '
                ' **** Planet list, where ReportType = "P" ****
                '
                TYPE PlanetReport
                    EName  AS STRING * 16 ' empire name
                    ' -------------------------------------- repeated...
                    PName  AS STRING * 16 ' planet name
                    X      AS INTEGER     ' X position
                    Y      AS INTEGER     ' Y position
                    Prod   AS INTEGER     ' production
                    Ships  AS LONG        ' ships in orbit
                    ' -------------- ... terminated by a single NUL byte
                END TYPE

                '
                ' **** Fleet list, where ReportType = "F" ****
                '
                TYPE FleetReport
                    EName   AS STRING * 16 ' empire name
                    ' -------------------------------------- repeated...
                    FleetNo AS LONG        ' fleet number
                    Origin  AS STRING * 16 ' planet of origin
                    Dest    AS STRING * 16 ' destination planet
                    Ships   AS LONG        ' ships in fleet
                    Dist    AS INTEGER     ' distance left to travel
                    ' ----------------- ... terminated by four NUL bytes
                END TYPE

                '
                ' **** Map Image, where ReportType = "M" ****
                '
                TYPE MapReport
                    EName  AS STRING * 16 ' empire name
                    Centre AS STRING * 16 ' planet at map centre
                    ' -------------------------------------- repeated...
                    PName  AS STRING * 16 ' planet name
                    X      AS INTEGER     ' X position
                    Y      AS INTEGER     ' Y position
                    ' -------------- ... terminated by a single NUL byte
                END TYPE
                '
                ' **** Map error, where ReportType = "M" ****
                '      Reason is one of
                '       "P" - map centre unknown
                '       "U" - map centre is someone else's planet
                '
                TYPE MapError
                    EName  AS STRING * 16 ' empire name
                    Centre AS STRING * 16 ' intended map centre
                    Reason AS STRING * 1  ' reason for error
                END TYPE

                '
                ' **** Message, where ReportType = "W" ****
                '      Text is variable length in the file, terminated
                '      by a null byte (ASCII 0)
                '
                TYPE WriteReport
                    EName  AS STRING * 16   ' empire name of recipient
                    Sender AS STRING * 16   ' sender
                    Text   AS STRING * 4096 ' easy on string space again
                END TYPE
                '
                ' **** Bounced message, where ReportType = "w" ****
                '
                TYPE WriteError
                    EName  AS STRING * 16 ' empire name of sender
                    Recip  AS STRING * 16 ' intended recipient
                    Reason AS STRING * 1  ' "R", for recipient unknown
                END TYPE

                '
                ' **** Victory Report, where ReportType = "V" ****
                '
                TYPE VictoryReport
                    EName  AS STRING * 16 ' empire to send report to
                    Victor AS STRING * 16 ' empire name of victor
                END TYPE

                '
                ' **** Arrival report, where ReportType = "A" ****
                '
                TYPE ArrivalReport
                    EName   AS STRING * 16 ' empire name
                    FleetNo AS LONG        ' fleet number
                END TYPE

                '
                ' **** Intelligence report, where ReportType = "I" ****
                '
                TYPE IntelligenceReport
                    EName   AS STRING * 16 ' empire name
                    FleetNo AS LONG        ' fleet number of scout
                    Owner   AS STRING * 16 ' owner of planet
                    Prod    AS INTEGER     ' production of planet
                    Ships   AS LONG        ' ships in orbit
                END TYPE

                '
                ' **** Battle report, where ReportType = "B" ****
                '
                TYPE BattleReport
                    EName   AS STRING * 16 ' empire name
                    FleetNo AS LONG        ' fleet number
                    Owner   AS STRING * 16 ' owner of destination planet
                    Ships   AS LONG        ' attacker's ships remaining
                    Enemy   AS LONG        ' defender's ships remaining
                END TYPE

                '
                ' **** Defence report, where ReportType = "D" ****
                '
                TYPE DefenceReport
                    EName  AS STRING * 16 ' empire name
                    PName  AS STRING * 16 ' planet attacked
                    Owner  AS STRING * 16 ' owner of attacking fleet
                    Ships  AS LONG        ' defender's ships remaining
                    Enemy  AS LONG        ' attacker's ships remaining
                END TYPE

        The code for reading this report file is broadly similar to the
        example given for the orders file.  However, there are the
        sub-records to think of as well.  For the sub-records I
        recommend reading enough to check for the NUL byte(s); if the
        bytes read are not NUL then reposition the file pointer back to
        the byte(s) just read, and read the entire subrecord.  If you
        use this approach you will probably want to give the sub-records
        a TYPE structure of their own, as I have done in the C source.
        For reading the text of a message, refer to the notes in section
        B.2 about reading message orders; the same advice applies here.
.fAppendix C - Support and Resources                                  %2d
APPENDIX C______________________________________________________________
                                                   Support and Resources

        This section gives details about what help and resources are
        available for AstroWar in Fidonet and on the Internet.  I won't
        give too much in the way of site addresses, since these can
        change.  I'd rather just give a addresses for official support
        sites, and use those sites to provide up-to-date information
        about other resources.  Hopefully the main support sites will
        remain where they are.

C.1.    Resources on the Internet

        The main Internet resource for AstroWar is the AstroWar home
        page, at:

                http://www.bsnet.co.uk/net2502/centurion/astrowar.html

        Links to other AstroWar-related web sites, and file space, will
        be added to this web page.  You can also find an AstroWar entry
        at Greg Lindahl's PBM List home page, at

                http://www.pbm.com/~lindahl/pbm.html

        I will try and arrange for AstroWar to be hosted at an FTP site,
        possibly ftp.pbm.com and ftp.funet.fi. If you wish to discuss
        AstroWar in a newsgroup, the best place to try would be
        rec.games.pbm.  I read that group, and I can answer your queries
        in the newsgroup or email.

C.2.    Resources in Fidonet

        Since Centurion is a Fidonet system, not an Internet one, you
        will find that support is more reliable in Fidonet.  A text
        equivalent to the AstroWar home page is available via routed
        netmail or file request.  To receive the document via netmail,
        send a netmail to INFOMAIL at 2:2502/666 with ASTROWAR as the
        subject.  To request the document as a (ZIPped) file, request
        ASTROWAR (a magic name) from the same address.

        All official source and binary distributions are available via
        file request from Centurion.  The filenames can be found on the
        web page and in the ASTROWAR document just mentioned.

        Finally, a support echo exists for AstroWar.  Its tag is
        ASTROWAR_UK, and despite the _UK suffix, international
        participants are welcome.  The echo is available from my system,
        and may be carried on various national or continental backbones.
        Netmail me for details.

C.3.    Contacting the Authors

        You can contact me, Damian Walker, via Fidonet netmail, at
        2:2502/666.  If you're on the Internet, email me at:

                damian.walker@f666.n2502.z2.fidonet.org

        which will go through the Fidonet/Internet gateway.  I do have
        an Internet address, but that changes from time to time (my
        current address will expire mid '98).  My real Internet address
        will be available on the AstroWar homepage.

        You can contact Tom Newsom, the Amiga developer, at his Fidonet
        address of 2:2502/61, or the Internet equivalent:

                thomas.newsom@f61.n2502.z2.fidonet.org

        At the time of writing, only Amiga, DOS and Linux versions are
        under development, so I can only give DOS/Linux and Amiga
        developer details here.  Details of contacting other authors
        should be in the 'read.me' files of their binary distributions.

        -Final Note-----------------------------------------------------
        AstroWar is the result of many months of programming and design.
         I hope that people enjoy it, but I don't know unless they write
             to me.  Please, whether you like the program or not, get in
               touch at one of the addresses above and let me know.  All
                            comments, source code and ideas are welcome.
        ----------------------------------------------------------------
