Hosting Vga-planets on Unix From: cg@primenet.com (cg) Date: Thu, 18 Apr 1996 00:00:00 +0000 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 :-) Up