GalaxyNG

Table of Contents

Introduction

The two basic items to host a game are a Linux box and an internet connection. GalaxyNG should compile and run right out of the box on Linux. This software is required:

C (gcc) compiler; to compile the server 
crontab; to automatically run turns at a given time 
procmail; to automatically process in comming orders

The GalaxyNG server is command line based, so you don't need X-windows. It requires little memory and even runs on a 2 MB Amiga. Creating influence maps is the one operation that is memory intensive. GalaxyNG also doesn't need much hard disk space. Depending on the number of players and planets, you need up to 20 MB of disk space per game. It isn't so much that the GalaxyNG server is large but that the data files can become quite large. For instance, turn reports with the battleprotocol option enabled can be 500 KB. So if there are 30 players left, this would amount to 15 MB of disk space just to store the reports before they are sent. In these times of GB hard disks this should not be a problem though :)

It isn't that difficult to start up your own game. It takes a while to configure the server and set up a game, but once it runs it needs practically no time at all. The whole process is automated, except for a possible bug fix or answering questions. Before you run a game you should make sure you have enough time and a connection to the internet for at least one year, since games can run that long. If you start a game, please continue it to the end, as it is very frustrating for players if a game just ends somewhere in the middle without coming to a conclusion.

Compilation

To extract the code, run:

tar -xvzf galaxy-#.tar.gz

This creates the directory NG/.

Most of the configuration is done after compilation and is handled by the program NG/install.sh. Before compiling the GalaxyNG server you should review NG/Source/makefile to make sure it fits your computer's configuration. The following variables can be configured:

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

The above settings are valid for most systems that have GCC installed. They have been tested on Debian, Slackware, SuSE, and RedHat systems and should compile without changes on most Linux boxes. 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, in the NG/ directory run:

make

This creates the executable NG/Source/galaxyng.

Installation

To install the GalaxyNG server, in the NG/ directory run:

make install

It creates $HOME/Games and installs a number of files in it.

To install the GalaxyNG server in a different directory, you must edit the first line of NG/install.sh. 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 GalaxyNG server in /home/gng/mygames, add:

export GALAXYNGHOME=/home/gng/mygames

Files and Directories

The following files are created.

File Explanation
Games/galaxyng The server program. You use it to create new games, check orders, and run turns.
Games/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.
Games/procmailrc An example .procmailrc file. This contains the commands to automatically process game registrations, incoming orders and other email received by the server.
Games/.galaxyngrc The server configuration file. The installation script tries to figure out the location of sendmail and formail. It also asks for the GM email address.

The installation program also creates a number of directories:

Directory Explanation
Games/data/ Game data is stored in a subdirectory for each game.
Games/orders/ Players' orders are stored in a subdirectory for each game, with the name <race_name>.<turn_number>.
Games/forecasts/ Forecasts are stored in a subdirectory for each game. This feature is normally only enabled when debugging the program, as it can consume significant hard disk space.
Games/reports/ Turn reports are stored in a subdirectory for each game. This feature is normally only enabled when debugging the program, as it can consume significant hard disk space.
Games/log/ Logs of information on processed orders and turns are stored in a file for each game.
Games/statistics/ For experimental purposes.
Games/notices/ Game notices are stored in files described below. You can use these to insert information in the bulletins that players receive in their turn reports.

There are three kind of notices available:

Notice Explanation
Games/notices/global.bulletin Information that applies to all your games.
Games/notices/<game name>.info Information that applies to a particular game.
Games/notices/<game name>.<turn number>.notice Information that applies to a particular turn of a game.

Configuration

The server is 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>/, whcih overrides the global settings for that particular game. A documented .galaxyngrc file can be found in the Doc/ directory. You can use it to specify the following parameters:

Parameter Explanation
GMemail The GM email address. If this is not present, the GM report will not be mailed.
GMpassword The GM password - this password is only used for relaying messages to players. DO NOT USE A VALUABLE PASSWORD No attempt is made to secure it.
SERVERemail The server email address. If this is not present, the GM email will be used.
sendmail The command that is used to send email, usually { /usr/sbin/sendmail -t }.
compress The command that is used to compress email, usually { /usr/bin/zip }.
encode The command that is used to attach compressed files to email, usually { /usr/bin/mmencode } or or { /usr/bin/mimencode } or { /usr/bin/uuencode }.
StartTime On some systems cron behaves a bit oddly after a system reset, and re-runs many old cron jobs. You can use the StartTime option to protect against this. The server will refuse to run a turn if the current time is not almost equal to the time specified. A start time of 13:00 would only run a turn if the current time is between 13:00 and 13:09. (It treats the last digit of the time as a wild card, so specifying 13:05 would have the same effect.)

Use

Running a galaxy game consists of steps:

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

Then repeat steps 4, 5, and 6 until the players request the game be stopped.

Utilities

Registering players, checking orders and running turns are, of course, very cumbersome processes that are best automated with procmail, formail and cron.

If you have never used procmail before, read the Procmail Quick Start and review the example Procmail configuration file in $HOME/Games/procmailrc carefully. If procmail is misconfigured, you could lose or bounce your email. 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. The Procmail Quick Start also discusses additional configuration needed to support maildir delivery and/or qmail.

Each entry in .procmailrc defines a recipe that tells what has to be done to a message and under what condition. The recipe for order messages is:

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

Translated it means: if the subject of the message contains the string "order", pipe the message to formail. It is case insensitive, so order, NewOrder and ORDERS will all match the condition. A lock file with the name orders.lock is used to prevent the simultaneous execution of the same recipe if two or more messages arrive at the same time. There are similar entries for the commands to request a copy of a turn report, relay messages to other players and register for games. You will find them in the example procmailrc file at $HOME/Games/procmailrc.

formail reformats email messages. When used with the -rkbt flags, all mail header lines are thrown away, a To: line is generated with the address of person that sent the message, a Subject: line is generated, with the original subject prepended with Re:, and the body of the message is retained. This allows the GalaxyNG server to mail forecasts, turn reports and other responses to the person who sent the message.

cron runs programs on a schedule. You can use cron to send orders due messages and run turns.

Automatic Registration Engine

The Automatic Registration Engine (ARE) is invoked by procmail to respond to emails from players signing up for games. For example, to allow up to 25 players to sign up for a game named Jangi, use this procmail recipe:

:0 rw :Jangi.lock
* ^Subject.*Join Jangi
|/usr/bin/formail -rkbt -s $HOME/Games/are Jangi 25 0 0 0 | /usr/sbin/sendmail -t

Up to 25 people could register for Jangi by sending an email to the server with the subject "Join Jangi."

You can also let players specify the number and sizes of their homeworlds, with these parameters: <total planet size> <maximum planet size> <maximum number of planets>. For example, to allow 10 players to sign up for a game named Welland with 2,500 production on up to 5 planets, with no planet larger than 1,000 production, use this procmail recipe:

:0 rw :Welland.lock
* ^Subject.*Join Welland
|/usr/bin/formail -rkbt -s $HOME/Games/are Welland 10 2500 1000 5 | /usr/sbin/sendmail -t

Players can request planet sizes by adding this line to their registration email:

#PLANETS <size of planet 1> <size of planet 2> ... <size of planet n>
e.g. #PLANETS 1000 500 500 250 250

The server will send error messages to players who submit requests for planets that do not match the criteria specified in the .procmail recipe.

Note that better examples of game signup recipes can be found in the file $HOME/Games/procmailrc.

The email address and planet sizes are written to two files: $HOME/Games/<game name>.players for players that were accepted and $HOME/Games/<game name>.standby for players that were rejected. The contents of these files can be pasted into your .glx file.

Creating a New Game

The game configuration file specifies the structure of the galaxy: number of home, empty, and stuff planets; size and name of the galaxy; the email address of each of the players; and some game options. Create a template game configuration file by using the -template command.

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

This creates a file named <game name>.glx with default values for all parameters, plus documentation about what each parameter does. Edit this file to insert the email addresses of the players and make any desired changes to the configuration. For example, if you have eight players and you want to call the game Orion, you can create the game as follows:

./galaxyng -template Orion 8

The template should be edited to change the dummy email addresses to the real email addresses of the players and make changes to configuration options, if desired. The game is then created by running:

./galaxyng -create <game name>

So, for the Orion game, 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 an ASCII 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

To create the turn 0 score, first create a directory for it:

mkdir <web directory>/<game name>

and then create the score:

./galaxyng -score <game name> > <web directory>/<game name>/score.html

So, for the Orion game, run:

mkdir <web directory>/Orion
./galaxyng -score Orion > <web directory>/Orion/score.html

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.

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.

Sending Orders Due Mesages

Players that haven't sent orders can be reminded with an orders due message. You do this with:

./galaxyng -due <game name>

For example:

./galaxyng -due Orion

Running Turns

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 your $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 sent 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 an ASCII map. That way you can follow the game.

If for some reason there was a problem with a turn, you can rerun it by executing:

./run_game <game name> <turn>

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

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 and send reminders at 17:15 hours, you can use the following cron file:

#           days             days 
#  Min Hour of     months    of     Command to run
#           month           week
    15   21   *      *     1,3,5     /home/username/Games/run_game Orion
    15   17   *      *     1,3,5     /home/username/Games/galaxyng -due Orion

To enable a cron file run:

crontab <your cron file>

To see what cron files you have enabled run:

crontab -l

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

See the crontab and cron manuals for more information.

You also have the option to run turns when all players indicate they are ready to run the turn. You do this with the immediate flag, e.g.

./galaxyng -immediate <game name>

This will run a check to see if one of two conditions has been met: a) all players have submitted final orders, or b) the GM specified number of hours has elapsed since the last turn was run. The key is the tick interval in hours, which should be placed in the .galaxyngrc file as:

<gamename>.tick  <tick interval in hours>

So, for example, this would run a turn if all players have submited final orders or if 48 hours have passed since the previous turn was run:

SpaceInvaders.tick  48

To send final orders, players add a "FinalOrders" to their #galaxy line when submitting their final orders for running the game. For example:

#GALAXY GameName RaceName Password FinalOrders

If players do not submit final orders, the turn will not run until the time limit has expired.

Influence Maps

Various colorful maps can be created: public, industry, attack, and defence. You must have freetype, GD, libjpeg and libpng and their development libraries installed to enable this feature.

Each map is 500k - 1MB in size. Generating influence maps is memory intensive. It may not be possible to create industry, attack and defence maps on hosted servers with limited memory. Public maps should be possible in most circumstances.

Currently, attack and defence maps aren't working.

Command Summary

Command Explanation
galaxyng -template <game name> <number of players> Create a template specification file.
are <game name> <player limit> <total planet size> <maximum planet size> <max. number of planets> < <email> Configure the automatic registration engine.
galaxyng -create <game specification file> Create a new game.
galaxyng -mail0 <game name> Create and email the turn 0 reports.
galaxyng -dummymail0 <game name> Create the turn 0 reports, but don't email them. You can find them in reports/<game name>
run_game <game name> [turn number] Run a game turn. If the turn number is not specified, the next turn will run. If the turn number is specified and a file named [turn#].all is found, it is used instead of individual player orders files.
galaxyng -run <game name> <file with orders> [turn number] Run a turn, and mail the turn reports, used in combination with run_game.
galaxyng -dummyrun <game name> <file with orders> [turn number] Run a turn but do not mail the turn reports. Store them in reports/ instead.
galaxyng -check <message via stdin> Check orders and mail a forecast, used in combination with procmail.
galaxyng -dummycheck <message via stdin> Check orders, do not mail a forecast.
galaxyng -report <message via stdin> Mail a copy of a turn report, used in combination with procmail.
galaxyng -relay <message via stdin> Relay a message from one player to another player, used in combination with procmail.
galaxyng -lastorders <game name> [turn number] List for each player the last turn orders were sent in.
galaxyng -due <game name> Send orders due email to players that haven't turned in orders for the current turn.
galaxyng -players <game name> [turn number] List password and address of each player.
galaxyng -toall <game name> Create a mail header to mail a message to all players.
galaxyng -map <game name> [turn number] Show an ASCII map of the galaxy.
galaxyng -influence <game name> [public|industry|attack|defence] [turn number] Produce an influence map of the galaxy. If no map type or turn number is specified, all maps for the current turn will be generated. If turn number is specified, map type must also be specified.
galaxyng -score <game name> Create a high score list in HTML format.
galaxyng -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 the Hall of Fame maintainer.

Hosting Team Games

First get two teams... best is to have the players themselves form the team and appoint a team captain for each team. After that you will have two lists with email addresses. You add them in the .glx file and above the first list you add:

team 0

and before the second list you add:

team 1

At the top of the .glx file you add:

teamgame

and then depending on the number of players there are:

rows 10
colums 10

(in this case the game would have 100 players). You then run the create command and the game is ready. You can create a special report for each of the team captains with:

./galaxyng -teaminfo  game  turn  team_number

All very simple :) except... depending on the number of players you will have to edit the creategame.c file. The galaxy that is created looks something like:

t0   t1   t0  ...  t1   t0   t1 

t1   t0   t1  ...  t0   t1   t1 
      .            .
      .            .
      .            .
t0   t1   t0  ...  t1   t0   t1 

t1   t0   t1  ...  t0   t1   t1

Where t0 is the home planet of a team 0 player and t1 is the home planet of a team 1 player. (That way each team player is surrounded by an equal amount of allies and enemies).

The number of rows and colums is defined in the .glx file. However, rows x colums must be equal to the number of players that join. And in some case this gives odd results. For instance if 16 players join the galaxy will be 4 by 4. However if 14 player join the galaxy will be 2 x 7 which will look very odd. This can be solved by using a bigger number of row and colums and removing some of the planets (I did that for Tiger3). For instance for the 14 player one, you can make it 4 by 4 and remove 2 planets:

t1   t0   t1 

t1   t0   t1   t0 

t0   t1   t0   t1 

t1   t0   t1

You can find out how this is done in createCheckeredLayout()... it is currently setup for a 7 by 7 grid and the removed of the corner players and 4 players in the middle...

Troubleshooting

The GalaxyNG server defaults to brief logging. To change the logging level, issue one of the following commands prior to running the server, or add it to your .bash_profile:

declare -x GNG_LOG_LEVEL=full
declare -x GNG_LOG_LEVEL=part
declare -x GNG_LOG_LEVEL=brief
declare -x GNG_LOG_LEVEL=none

Example House Rules

You should post house rules for your GalaxyNG server on your web site.