
    Device: The Machine, Version 2.9
    Creator: Douglas Selph
    E-Mail: digger@csi.com

Purpose: 

   The Machine was designed for use within the galaxy game to
read in turn reports, maintain an internal database of the cosmos
and respond to requests to make certain game functions easier.

Requirements:

   Basic C-compiler.

Features:

   - Able to directly read in turn reports into it's database, providing
     services for:

	The display and position of planets.
	The contents and position of groups.
	The stats of ships for races.

   In regards to Planets:

     - Can display any portion of the cosmos similar to
       the "map" command in conjuction with the turn reports.
       The limitation is that the database only knows about
       what it has read from the turn reports.

       Also able to display on the map an area around a particular
       planet of interest.

       Able to show either resource value, planet size, or the
       id of the planet next to the planet symbol on the map.

     - Can display the distance between two planets in light
       years.
    
     - Can display a list of the planets, listing the size
       and resource values for uninhabitied plantes, and
       full planet descriptions for your planets.  Also now
       it lists the routes that planet is participating in.

     - Can display the closest planets to a particular planet.

     - Function that displays shows the path from planet A to B
       through one intermediate planet with a maximum jump in 
       light years.

     - Can display info regarding just your planets.

   In regards to Ships:

     - Able to read ship decriptions from the turn report.
       Maintains pertainent tech levels for each race of
       ships.

     - Able to display the ships with the following ship
       attributes calculated for you: mass, #light years
       able to move on a single turn, if cargo ship # of
       light years when full, defense power (compare this
       value to the attack power to get ratio; this is the
       most valuable calculated number in my opinion), and
       cost of the ship.

    - A function that allows you to enter: the # of light 
      years you wish a ship to move, and the mass of the
      ship to compute: the necessary drive power needed to 
      move the ship with that mass at that speed. 
      Use this value to determine the drive of the ship needed.

    - A function that allows you to enter: the desired
      defense power wanted, and the mass of the ship to
      compute: the necessary shield strength needed to
      give a ship of that mass the desired defense power.

    - A function that displays an estimate of the number of 
      ships a particular planet may produce in a single turn.
      This is really buggy and I have stopped using it.  To
      get the most accurate measure, for one turn count the
      number of mass 1 ships the planet is able to produce.

    - A function that allows you to design a test ship.

    - Galaxy Version 3+ support which shows the effective ship
      cargo capacity, the effective shield defense strength
      and movement after a full load of cargo.  This is done
      by preceeding the command with the letter 'C'.

   Adding your own Testing Race to the ship decriptions :

      To add your own testing race to enter in ship descriptions that 
      you haven't actually made yet, but would like to see what it looks 
      like if it were made, do the following: after you have done at
      least one save to create 'save.ships':

	 In 'save.ships' copy the section starting from the line 
	 "Your Ship Types" and ending with at least one of the ships 
	 listed in the Your Ship Types list.  Copy this section and 
	 place it above the 'Your Ship Types' section.  Change the name 
	 'Your' to 'Test' and delete or add any ships to the list as 
	 desired.  You may also add any set of tech levels to the
	 tech level list.  You will see it when you start back up.
	 Note: the 'at' command uses these tech levels to choose from.

   In regards to Groups:

    - Can read in the "Group" sections from the turn report.
      Can then print out the groups sorted by planet and race 
      for quick assement of what ships are at what planet.

    - Can read in alien groups as well from the turn report.
      Able to print out the groups for a particular race.
     
To Use:

    ( Step 1. )

    Enter with 'main' or 'main -m'.

    The '-m' flag is if you are on a teletype and would
    like displays to be interrupted with '--more--' after
    22 or so lines.

    If you are first starting up, don't worry about all the
    "No such file or directory" messages.

    Type '?' for a list of commands.

    ( Step 2. )

    The 'rt' command (read turn report) can be used to 
    read in turn reports.  Go ahead and use this
    command to read in all the turn reports you 
    have accumulated.  

    ( Step 3. )

    The 's' command to save the data read in into the database:
	"save.ships", "save.planets", and "save.groups".

    ( Step 4. )

    With regards to planets, the commands I use the most are: 
      'dp' (display planets) and 'py' (print yours); 
	also, 'da' (display of planets sorted by distance from
	a specified planet), and sometimes 'pp'.  
    With regards to ships, the commands I use the most are: 
      'ps' (print ships); also, in terms of design 'cd' 
      (calc drive power), 'cs' (calc shield power)', 'ck'
      (calc kill percentage).
    With regards to groups, the commands I use the most are: 
      the amazing 'gp' command (print groups sorted by planet), 
      This is the command I use by far the most.  It lists
      the planet stats, the routes the planet is involved in
      and the ships at a planet.  

    ( Step 5. )
      
    Type 'q' to exit.  Will save all data back out into
    the database.  If you do not want to modify the database
    exit with an 'x'.

Database Notes:

    The database is stored in the files: 
     
      "save.planets" : list of known planets.
      "save.ships" : list of ship descriptions and tech levels.
      "save.groups" : list of groups.  
      "save.routes" : list of routes extracted from turn report.
      "save.version" : If this file exists the machine will compute
	 mass based on Galaxy Verions 3.0 where any weapons over one 
	 is half.  If this file does not exist, mass will be computed 
	 as per pre 3.0.

    You can print these files out because they are in a readable
    ascii format.

Known Bugs:

    o The machine does not understand two column output, nor no under-
      scores, in Russel version of galaxy (RWALLACE@vax1.tcd.ie).  You
      must be run your turn reports with "NO TWOCOL" and "UNDERSCORES".

    o Group lists (in save.groups) sometimes have extra groups from old
      turn reports.  This bug I am almost certain I fixed.  For example,
      sometimes you might see the groups for a planet and there are many
      more groups than you would expect.  This was because for some reason
      the group from the previous turn report read in was not cleared before
      the current turn report was read in.  This I fixed.  However, if
      you see any problems where the appear to me more groups than the listed
      on your turn report, just remove save.groups (harmless) and re-read
      your latest turn report.  

      Again, I think I fixed this, but I wanted to just make you aware of
      what to watch out for (just in case).

      Aside: I was trying to add the ability for the Machine to read in 
        alien turn reports (turn reports sent to you by an ally for instance)
        to add to your database of known planets and groups, but in doing
	so I think I made the program too complicated.  Ideally I would like 
	to fix the code so that eventually I would be able to read in alien 
	turn reports along with your own turn reports to get a comprehensive 
	database (save.planets, save.groups, and save.ships) of the galaxy.  
	Time permitting, maybe in the future.
    
    o The 'calc' command (calculate the number of ships a planet may produce)
      really really is not very accurate.  Don't depend on it.  The best way
      to find out is to see how many mass 1 size ships the planet can make.

Future Possibilities (To Be Done):

    o Function to compute amount of capital that a planet
      would produce.  Same for population.

    o Able to read in alien turn reports:
      Instead of doing 'Your' groups and planets, translate
      this to the race name listed in the turn sheet.  This
      way alien turn sheets could be read.  Be carefully not
      to clear ship descriptions.

    o Galaxy 3.0 Changes to Hit.

    o Be able to read group information from Battle section.

Warnings:

    o The formula for calculating the kill ratio of a ship against a ship
      was computed using Rob Muir's version of galaxy.  I am not sure this
      formula holds true for version 3.0 of Russels galaxy or other versions
      of galaxy out there.  

Good Luck:

    Any suggestions or comments may be mailed to me
    at the e-mail address.

