[ Home ]

GalaxyNG Server Manual
For release-5-0g

By Frans Slothouber (rfsber@xs4all.nl)

Last update March 2001

1 Table of Contents

01......... Table of Contents
02......... Compilation
03......... Installation
03.01.......... Installing in a Different Directory
03.02.......... Files Created by the Install Process
04......... Use
04.01.......... Creating a New Game
04.02.......... Mailing the Turn 0 Reports
04.03.......... Processing Orders
04.04.......... Auto Checking
04.05.......... Running a Turn
04.06.......... Rerunning a Turn
04.07.......... Running Turns Automatically
05......... Command Summary
06......... Configuration
06.01.......... Server Configuration File
06.02.......... Environment Variables

2 Compilation

Most of the configuration is done after compilation and is handled by the install program. Before compiling galaxyng you might want to edit the makefile in the Source/ directory to make it fit your machine's configuration. The following variables can be configured:

  CC     = gcc
  CFLAGS = -Wall -pedantic -g 
  LIBS   = -lm

The above settings are valid for most Unix systems that have GCC installed. It should compile without changes on a Linux box. (Has been tested on a Debian, Slackware, SuSE, and Redhat system). Do not add any optimization options otherwise the code will not function properly! The server only runs a couple of times per week, so speed is not an issue.

To compile the code just type

  make 

in the top level directory GalaxyNG/, this creates the executable Source/galaxyng.

3 Installation

After you compiled the code, do a

  make install

to install galaxyng. It creates a directory called Games in your home directory and installs a number of files in it.

3.1 Installing in a Different Directory

If you want to have the game installed in a different directory you have to edit the first line of the install.sh script. You also must set the environment variable GALAXYNGHOME to this directory. You can do this by adding a line to your .bash_profile file (or the appropriate file for your favourite shell). For instance if you have installed the game in /home/gng/mygames, add

export GALAXYNGHOME=/home/gng/mygames

3.2 Files Created by the Install Process

The following files are created.

galaxyng The server program. You use it to create new games, check orders, and run turns.
run_game A shell script to run a game. It is used in combination with cron, and allows you to automatically run turns at specified times.
procmailrc An example procmailrc file. This contains the command to automatically process incoming orders when ever a player send you an email with orders and a specific subject. To use it copy it to $HOME/.procmail.
.galaxyngrc The configuration file for the the server. here you can specify the email address the GM reports are send to, as well what command should be used to send email.

The installation script tries to figure out the location of all programs needed to run the game, sendmail and formail. It also asks you for an email address. The GM status reports go to this address.

The installation program also creates a number of directories:

orders/ This is where the players orders are stored. For each game there is a subdirectory. Orders are stored here under the name <nation_name>.<turn_number>.
data/ This is where the game data is stored, there is a subdirectory for each game.
reports/ Contains, for each game a subdirectory where the turn reports are stored. It is only used for debug purposes.
log/ Contains log files that contain information on processed orders, and game runs.
statistics/ For experimental purposes.
data Contains, for each game a subdirectory where all the game data is stored.
notices/ This contains game notices. You can use these to provide additional information to the turn reports.

There are three kind of notices available:

global.bulletin In this you can store information that applies to all your games. You can find an example in the Doc/ directory.
<game name>.info In this you can store information that applies to a particular game.
<game name>.<turn number>.info In this you can store information that applies to a particular turn of a game.

4 Use

Running a galaxy game consists of steps:

  1. create a new game,
  2. mail the turn 0 report,
  3. check and store the orders that the players sent in,
  4. run a turn,
  5. mail the turn reports.

Then repeat steps 3, 4, and 5, until the players request the game to stopped.

4.1 Creating a New Game

To create a game use the command:

  ./galaxyng -create <specification file>  

The specification file specifies the structure of the galaxy, that is the number of home planets, empty planets, stuff planets, the name of the galaxy and the size of the galaxy as well as the the email address of each of the players.

You can create a template .glx file by using the -template command.

  ./galaxyng -template <game name> <number of players>  

This creates a .glx file with default values for all parameters, plus documentation about what each parameter does. You will have to edit this file to insert the email addresses of the players. For instance, say you got eight players to play in a galaxy game, and want to call this game Orion. You can then create this game as follows

  ./galaxyng -template Orion 8  

Edit the Orion.glx and change the dummy email addresses to the real email addresses of the players, then run

  ./galaxyng -create Orion.glx

The server gives a detailed list of what it is doing and what planets are created. When the game is created a map is printed. A lot of output is created so you might want to redirect the output of the server to some file, say orionlayout.txt:

  ./galaxyng -create Orion.glx  > orionlayout.txt

4.2 Mailing the Turn 0 Reports

If you are happy with the galaxy you created, you can mail the turn 0 reports with:

  ./galaxyng -mail0 <game name>

Before you start any real games you might want to try to run a couple of test games with yourself as player. This way you can see if everything works OK.

So

  ./galaxyng -mail0 Orion

for your Orion game.

4.3 Processing Orders

When you receive orders from a player, you can store and check them with the following command:

  ./galaxyng -check <file with orders>

The file with orders has to be a properly formatted email message, with a To: field and a Subject: field with the word "orders" in it.

The orders are stored in the directory orders/<game name> and the program sends a forecast to the player. A log file is kept of all orders that are checked. It can be found at $HOME/Games/log/orders_processed.txt.

4.4 Auto Checking

Checking orders by hand is of course a very cumbersome process that is best automated. You can automate with procmail and formail. They are program that can reformat and process incomming emails.

If you never used procmail before, read the man pages, and then use the example procmailrc installed in $HOME/Games/procmailrc. Also read the example procmailrc file as it contains additional documentation.

Procmail can be difficult to get working. On some systems procmail works by just creating a .procmailrc file in your home directory. On other systems you have to create a .forward file, that contains | /usr/bin/procmail to get procmail to work.

Each entry in a .procmailrc defines recipe. It that tells what has to be done to a message and under what condition. The recipe for order messages looks as follows.

  :0 rw :turno
  * ^Subject:.*Order
  |/usr/bin/formail -rkbt -s $HOME/Games/galaxyng -check

Translated it means: if the subject of the message contains the word "order", pipe the message to formail. The condition is case insensitive, so Order, or ORDER also works. A lock file with the name turno.lock is used to prevent the simultaneous execution of the same recipe if two or more message that arrive at the same time.

formail reformats the message. All mail header lines are thrown away. A To: line is generated with the address of person that send the message. A Subject: line is generated, with the original subject prepended with Re:. This together with the body of the message is fed to the galaxy server, running the check command.

The server will analyse the orders in the body, and send a reply to the person that send the message.

There are similar entries for the command to request a copy of a turn report, and the command to relay an message to another player. You will find them in the example procmailrc file.

If you want to keep a copy of the orders players sent-in, you can use the following entry

# Someone sent-in orders, check them..
:0
* ^Subject:.*order
{
        :0 c
        $HOME/mail/orders

        :0 rw:order.lock
        |/usr/bin/formail -rkbt -s /home/gng/Games/galaxyng -check
}

Do not use:

# Someone sent-in orders, check them..
:0 rw :order.lock
* ^Subject:.*order
{
        :0 c
        $HOME/mail/orders

        :0
        |/usr/bin/formail -rkbt -s /home/gng/Games/galaxyng -check
}

In this case procmail ignores the lock file, and it can happen that when two players send in orders shortly after eachother the orders of the first player are overwritten

4.5 Running a Turn

When it is time to run a turn you do this with:

  ./run_game <game name>

This shell script collects all orders in one file, runs the turn based on these orders, and then sends out all the turn reports to the players. It also creates high-score lists in HTML and places it in you $HOME/public_html directory, if you have one. You can edit the script and add other commands that need to be run for each turn.

After each turn you are send a GM status report. It tells you whether the turn ran successfully. It is especially handy if the server runs on some remote computer. It also contains information on the status of all nations in the game, a list of all bombings and a map. That way you can follow the game.

4.6 Rerunning a Turn

If for some reason there was a problem with a turn ran, you can rerun, execute:

  ./run_game <game name> <turn>

The game will be rerun and new turn reports are send to the players. This only works for turns that already ran.

4.7 Running Turns Automatically

Although it is simple to run a turn it becomes cumbersome after a few turns. Automization is again the solution. You can do this with cron. For instance if you have a game called Orion, that runs on Monday, Wednesday, and Friday around 21:15 hours, you can use the following cron file:

#           day            day 
#  Min Hour of     month   the     Command to run
#           month         week
    15   21   *      *     1     /home/yourname/Games/run_game Orion
    15   21   *      *     3     /home/yourname/Games/run_game Orion
    15   21   *      *     5     /home/yourname/Games/run_game Orion

To enable a cron file run

   crontab <your cron file>

To see what cron file you have enabled run

   crontab -l

An example file can be found at $HOME/GalaxyNG/games.crontab

To enable it run.

See the crontab and cron manual for more information.

5 Command Summary

Command

Parameters

Explanation

template <game name> <number of players> Create a template specification file.
create <game specification file> Create a new game.
mail0 <game name> Create and email the turn 0 reports.
dummymail0 <game name> Create the turn 0 reports, but don't email them. You can find them in reports/<game name>
run <game name> <file with orders> [turn number] Run a turn, and mail the turn reports.
dummyrun <game name> <file with orders> [turn number] Run a turn but do not mail the turn reports. Store them in reports/ instead.
check message via stdin Check orders and mail a forecast, used in combination with procmail.
dummycheck message via stdin Check orders, do not mail a forecast.
report message via stdin Mail a copy of a turn report, used in combination with procmail.
relay message via stdin Relay a message from one player to another player, used in combination with procmail.
lastorders <game name> [turn number] List for each player the last turn orders were sent-in.
players <game name> [turn number] List password and address of each player.
toall <game name> Create a mail header to mail a message to all players.
map <game name> [turn number] Show a map of the galaxy.
score <game name> Create a high-score list in HTML format.
hall <game name> [turn number] Create a table with information for the Hall of Fame. At the end of a game, run this command and send the output to fslothouber@acm.org.

6 Configuration

6.1 Server Configuration File

The server can be configured with a .galaxyngrc file. The server looks for this file in the directory $HOME/Games/. It also looks for the file in $HOME/Games/data/<game name>/. You can use this to override settings for a particular game. An example .galaxyngrc file is generated when you install the game. A documented .galaxyngrc file can be found in the Docs/ directory. You can use it to specify the following parameters. Only the first two are essential to run games.

GMemail The address the GM status reports are send to.
sendmail The command that is used to send mail to the players.
compress The command to compress email with, usually { /usr/bin/zip }.
encode Path to the command to attach a file to an email with, usually { /usr/bin/mmencode }.
FullBombing Switch to turn on old style galaxy bombing rule.
DontDropDead Switch, idle players are not dropped from the game.
SaveReportCopy When running a turn also save a copy of each turn report in reports/<game name>/.

6.2 Environment Variables

You can override where the server looks for all its data files by setting the GALAXYNGHOME variable. If it is not set the server looks in $HOME/Games/.