PHOST Automated Hosting Support Programs
========================================
by Andrew Sterian  asterian@eecs.umich.edu

This file describes three shell scripts which I use to run automated VGA
Planets games using PHOST on a Unix system. The scripts perform three
functions: automated execution of the PHOST program and mailing of the
result files, automated checking of TRN files as they are submitted, and
automated mailing of reminder messages for players who have not yet
submitted turns.

The three included scripts are:

          PHOSTRUN  -- runs PHOST and mails RST files
          PTURNCHK  -- checks incoming TRN files and mails acknowledgments
          PREMIND   -- mails reminder messages

The first thing you should do is go through these scripts and find the word
CONFIG in them. Change the paths of the programs that follow in the scripts
to suit your system. Perhaps an automatic configuration script will be
included in the future but for now you have to manually set up program
paths yourself. There are other things hard-coded into the scripts, such as
the subject lines used for outgoing messages. If you wish to change these
you will have to dig through the code.

You should see some extra files that serve as examples for other necessary
functions:

          PROCMAIL.EX  -- Example .procmailrc file for use by 'procmail' in
                          handling incoming TRN files. You don't have to use
                          'procmail', but you do need some kind of mechanism
                          for piping received mail to the PTURNCHK program.

          CRONTAB.EX   -- Example entry for 'crontab' for use in scheduling
                          host runs and reminder messages.

          GAMEDIR.EX   -- This directory contains a sample game setup with
                          all of the files and subdirectories needed by the
                          three programs (but no actual game files). It can
                          be used as a template for a real game directory.

          NEXTTURN     -- Short script for removing excess files from a
                          previous host run.

The basic flow of operation of the three programs is as follows:

    1) PHOSTRUN is meant to be scheduled using 'crontab' to run at fixed
       times. The program runs PHOST and mails out RST files to the
       players. See the CRONTAB.EX file for an example of what to put in
       the 'crontab' entry.

    2) The players mail UUENCODED TRN files to the host. An external mail
       handling program, such as 'procmail', is used to forward the mail to
       the PTURNCHK program (on standard input) which then decodes the turn
       file and uses PHOST to perform a turn check (using the -c option).
       The result of the turn check is mailed back to the player. Players
       can receive confirmation of receipt of their turn files in a matter
       of seconds.

    3) PREMIND is meant to be scheduled using 'crontab' at some time
       interval prior to hosting. PREMIND looks in the game directory for
       missing TRN files and sends a short reminder message to those
       players who are delinquent. The use of PREMIND is optional. It
       probably doesn't make sense to use it for games that run daily.

See the individual script files themselves for detailed operation and usage
information.

Game Setup
==========

To set up a PHOST game on your system, perform the following steps:

1) If you haven't already done so, edit the PTURNCHK, PHOSTRUN, and PREMIND
files and search for the keyword CONFIG. Then, edit the lines that follow
to reflect the program pathnames that are in effect for your system.

2) Place the three program files in a local program directory (such as
/usr/local/bin or $HOME/bin). Make sure they are executable.

3) Create a new game directory. For example:
                cd games/planets
                mkdir game1

4) Create 5 subdirectories in this game directory. The names given below as
an example are default names which can be redefined in the phost.config
file:
                cd game1
                mkdir universe global-data save backups bad

5) Obtain the data files for the PHOST game. If you mastered the game under
DOS, you need to run PCONVERT (see the documentation that comes with
PHOST). Place the game-specific files (e.g., pdata.hst, pconfig.hst, etc.)
in the 'universe' subdirectory.

6) Place the non-game-specific files (e.g., hullspec.dat, truehull.dat) in
the 'global-data' subdirectory, OR in a separate higher-level directory if
you wish to host multiple games using these files (in which case you can
remove the 'global-data' subdirectory).

7) Create a phost.config file in the game directory (you can copy the one
that came with these files). Edit the file to reflect the names of the
subdirectories you chose and define the e-mail addresses of your players.

8) Install or edit the .procmailrc file in your home directory to
automatically pass incoming TRN e-mail messages to the PTURNCHK program. A
sample .procmailrc file can be found as the file PROCMAIL.EX that came with
these scripts.

9) Edit your crontab file (usually by typing 'crontab -e') to schedule run
times for the PHOSTRUN and PREMIND programs. A sample crontab file can be
found as the file CRONTAB.EX.
 
10) Test things out!

The PHOST.CONFIG File
=====================

The three programs all assume that a PHOST game has already been set up in
a game directory on the host's system. The game directory must be passed as
an argument to all three programs. In addition, the three programs assume
that a file named 'phost.config' exists in this game directory. The
contents of this file is described below. A sample 'phost.config' file is
included in the GAMEDIR.EX example directory.

The phost.config file must at least contain the e-mail addresses of the
active players defined as shell variables of the form 'playerX'. For
example:

            player1=john@aol.com
            player2=dave@clark.net
            player3=dude@well.ca
            # player 4 is out
            player5=nobody   # Player 5 is out too
            player6=ringo@fab4.net
                 [etc.]

Inactive players must be left undefined or may be set to the special value
'nobody'.

There are 3 other shell variables which should be defined in the
phost.config file. Defaults are provided by the 3 programs but specifying
these values explicitly is a good idea:

          ReceivedMailFile    (default:  $HOME/Mail/received)
              This variable should contain the name of a file which is to
              receive messages that are most likely not TRN files. PTURNCHK
              will append the current message to this file if it cannot
              find anything recognizable by UUDECODE or XXDECODE. This case
              arises often if players send mail messages to their hosts
              with special keywords in the subject lines that are reserved
              for TRN file submissions.

         HumanHost            (default:  $LOGNAME if it exists, else `logname`)
              This variable must contain the e-mail address of the host
              person. If one of the programs encounters an unexpected
              error, a mail message will be sent to this e-mail address.

         Tmpdir               (default: /tmp)
              This variable must contain the name of a directory suitable
              for holding temporary files.

The phost.config file may also contain overrides for any one of the
following 5 variables:

                              UniverseDir
                              GlobalDataDir
                              SaveDir
                              BackupDir
                              BadTrnDir

These variables store directory names which are expected to exist as part
of the game setup. Nominally, they are subdirectories of the main game
directory but one or all may be changed as necessary. When the
'phost.config' file is read, the variable 'gamedir' is defined as the
absolute pathname of the game directory. Thus, the above 5 directories may
be defined relative to $gamedir. The description of these directories and
their default values follows:

         UniverseDir    (default value:  $gamedir/universe)
             This directory is assumed to contain all of the PHOST
             game-specific files (such as 'pdata.hst', 'pconfig.hst',
             'xyplan.dat', etc.)

         GlobalDataDir  (default value:  $gamedir/global-data)
             This directory is assumed to contain all of the
             game-independent hosting files (such as 'hullspec.dat',
             'planet.nm', etc.)  It may be the same directory as the
             universe directory.

         SaveDir        (default value:  $gamedir/save)
             This directory is where the input to PTURNCHK is stored as a
             file. The original mail message that PTURNCHK receives is
             stored in a file with the name 'msg.XXXXX' where the X's
             represent the process ID number of PTURNCHK. These files are
             all stored in the save directory for future review by the host
             person if necessary. If the directory does not exist when
             PTURNCHK runs, PTURNCHK will attempt to create it.

         BackupDir      (default value:  $gamedir/backups)
             This directory is where PTURNCHK stores TRN files which are
             about to be overwritten by a new submission. Also, PHOSTRUN
             uses this directory to store a backup of the game files prior
             to hosting. When a player re-submits a TRN file for the same
             turn, the previous TRN file is stored in the backup directory.
             If this directory does not exist when PTURNCHK or PHOSTRUN
             runs, then it will be created.

         BadTrnDir      (default value:  $gamedir/bad)
             When PTURNCHK encounters a bad TRN file, it stores the file in
             this directory for future review, if necessary. If this
             directory does not exist when PTURNCHK runs, PTURNCHK will
             attempt to create it.

For example, if the player wishes to accept the default values for the
above directories but a) his game-independent data files are in a
higher-level directory (to be shared across multiple games), and b) he
wants to override the name of the bad-TRN directory from 'bad' to 'badtrns'
then the phost.config file may include the following:

            GlobalDataDir=/usr/local/planets/global-files
            BadTrnDir=$gamedir/badtrns

Administration
==============

The original author of these programs is Andrew Sterian
(asterian@eecs.umich.edu) although the PTURNCHK program is actually a
heavily modified and expanded version of the turn check script included
with Dave Boynton's original 'uturn' program. In as much as it is in my
power to do so, I am placing these programs in the public domain. You may
use, modify, distribute, and otherwise hack at these files freely. It would
be nice if you sent me a note telling me you're
using/modifying/distributing/hacking these programs. If you do distribute
modified versions of these files, please state clearly that the original
files have been modified so that I am not held accountable for your
modifications :-)

There are no warranties provided with these programs and you use them at
your own risk. There is also no support offered with these programs. They
work for me. If they don't work for you, then hack at them until they do.
Your suggestions on improving these scripts are welcome but don't expect to
see suggestions become reality any time soon :-)

