GM Guide
- Linux system and prerequisites
- Installing the server
- Creating a new game
- Mail handling
- Initial reports
- Running the turn
Eressea was designed to run on a UNIX system. While the code can also be built on any other flavor of UNIX including OS X, as well as Windows, Linux is probably the easiest to use and most widely available operating system, and this guide will focus on that.
If you are not already a Linux user, you will first need a machine. You could rent a host, set up a virtual machine, or use a Raspberry Pi, and your mileage may vary only a little bit from what I am describing in this guide. I will use a free Ubuntu Linux instance from koding.com here, because the steps should be easy to follow for anyone, and easy to adapt to your own situation if you choose to go another route.
Go to https://koding.com, where you are given access to a free virtual machine in the cloud with an easy-to use web IDE. Note that with the free account, this virtual machine shuts down anytime you close your browser, so it's like a computer that is only on when you are using it, not a permanently running internet appliance.
Once you have confirmed your email address, turn on the VM koding-vm-0, and after a few minutes you will see a screen like the one here:
While you now have a fully functional Ubuntu 14.04 Linux, we need to install some extra packages in order to install Eressea. In the Terminal window on the bottom right of the screen, type the following commands:
sudo apt-get -y update
sudo apt-get -y install gcc make git cmake libxml2-dev liblua5.2-dev libtolua-dev libncurses5-dev libsqlite3-dev
echo export ERESSEA=~/eressea >> .bash_aliases
echo export LANG=en_US.UTF-8 >> .bash_aliases
source .bash_aliases
Eressea is an open-source project hosted on the social coding site github. We need to clone a copy of the source code before we can build it. Type:
mkdir -p eressea/server
cd eressea
git clone https://github.com/eressea/server git
cd git
Notice how the file browser on the left of your screen is now showing your new eressea directory and all the files you just checked out.
The game is distributed as platform-independent source code, and we need to compile it into an executable for our platform to make it usable:
cd ~/eressea/git
git submodule update --init
s/cmake-init
s/build && s/runtests && s/install
If all went well, you should now have a lot of files installed into the ~/eressea/server directory. If you like, you can use the file browser on the left side of the screen to explore.
Every game of Eressea needs a data file that contains the map data, player positions and complete state of the world. You can choose to run a single game world, or have multiple worlds side-by-side if you want to operate more than one game. Each game is defined by a set of rules, and there are currently two rulesets in the distribution, e2 and e3, which describe the rules for the original Eressea, or the E3 and Deveron game, respectively. As a starting point, you should probably copy one of them, and give it your own name. I recommend you try to avoid naming your game Eressea, as that name is already associated with my own games, and the name of the game system itself. For the purpose of this guide, I will name my game Arda, and want to copy the configuration from e2 to a directory a1:
cd ~/eressea/server/conf
cp -r e2 a1
At this point, find the eressea/server directory in the file browser, and select the option "Workspace from here" from the dropdown. This makes it easier to navigate and edit files. From the file browser view, find conf/a1/config.xml, double click it to open it in the editor view on the top right. Let's make some modifications to it:
Find any lines that contain the name "Eressea", and change them to your game's name. Let's also change the game ID to 1, since this is the first (and so far only) game we want to host:
<game name="Arda">
<param name="game.id" value="1"/>
<param name="game.name" value="Arda"/>
<text locale="de">Bitte denke daran, deine Befehle mit dem Betreff
ARDA 1 BEFEHLE an arda-server@hotmail.com zu senden.</text>
<text locale="en">Remember to send your orders to
arda-server@hotmail.com with the subject ARDA 1 ORDERS.</text>
<text locale="de">ARDA 1 BEFEHLE</text>
<text locale="en">ARDA 1 ORDERS</text>
There are a lot of other moving pieces to the game that you could configure at this point, this XML file and the ones that it includes are pretty powerful, but I will not go into that here, since doing this right probably involves more familiarity with git and github.
Notice that I've replaced the email address of the server with a custom Hotmail account. I recommend using an account on an external mail server that has POP3 or IMAP support. If you have a small domain somewhere that comes with a limited number of mail boxes, using one of those works great, too. You could of course run your own mail server, but since that is a lot of hassle, and this machine is not permanently on the internet, I would advise against it and definitely won't go into it. See the section later in this document for how to set up email handling for the game.
The game data and all files for a world will reside in a per-game directory. Let's create it now:
cd ~/eressea/git
s/setup -g 1 -r a1
cd ../game-1
The next step is to create a map for your world. There are several ways to do this, but the most straightforward is to edit the map by hand using the built-in editor. To run it, first start the game in interactive mode:
cd ~/eressea/game-1
./eressea
This will give you an interactive prompt, with a cursor prefixed by E> . Type the following commands at the prompt to start the editor:
require 'config'
gmtool.editor()
Now you see the (empty) map, and a cursor that you can use to navigate with the arrow keys. Notice the coordinates at the bottom left changing when you do so, select some regions with the space bar, and get a feel for how the hex layout of the map is represented in this textual representation.
You can press 'f' to terraform the region under the cursor, or chain ';' and 'f' to terraform all currently selected regions at once. With just these tools and plenty of patience, you can build yourself a map.
TODO: insert a link to advanced world generation and scripting here.
Press F2 to save your world to a file. Since we are in turn 0, you should call it "0.dat". It will be stored in the ~/eressea/game-1/data/ directory, and each future turn will produce a new file.
TODO: insert link to advanced editor commands here.
At this point, you should have an email address and a choice of playable race for each of your players, and you'll want to seed them on the map so your game can get started. There are several schools of thoughts for the best methods of placement, I personally like putting multiple factions in the same starting hex to encourage cooperation early on, but some GMs prefer to liberally scatter factions across the entire world to encourage exploration first.
Whatever your choice, edit the file ~/eressea/game-1/newfactions so it contains one line for each player:
enno@hotmail.com elf de
foo@example.com orc en
[...]
At this time you are also choosing the language for the player's reports from either "de" for German or "en" for English.
Still in the editor, pressing "A" will create some new regions with random terrain for the players and seed each of them in an individual hex, with about 3 hexes per player. This creates a world where players need to explore to find their neighbors, rush to claim the land around them, and eventually fight to gain more.
TODO: add link to a page explaining advanced selection methods for player placement.
If you walk around the map with the cursor keys, you will see the player's units appear in the region info box on the right hand side of the editor. To find the hexes where players are, chain the keys 'h' and 'p' to highlight all player hexes.
Again, remember to save your world with F2 after players have been seeded, so you don't lose your work. Leave the editor with 'Q', then leave the interactive console with Ctrl-D to return to the terminal.
Since you are not running your own mail server, but storing email on an external host, we are going to use fetchmail and procmail to retrieve and filter orders.
sudo apt-get install -y sendmail procmail fetchmail mailutils
echo "set askcc=False;" >> ~/.mailrc
Check that sending email works by sending yourself a message from the command line:
echo "Hello World" | mail you@yourdomain.com -s "data backup" -A ~/eressea/game-1/data/0.dat -r arda-server@hotmail.com
TODO: fetchmailrc and procmailrc examples TODO: echeck, optional?
Before your game starts, you have to send an initial set of reports to all of your players. These can be generated by a custom script like this:
./eressea -t0 reports.lua
TODO: how to compress reports and send email (steal from s/preview).
In an unattended server that is permanently connected to the internet, Eressea can run as an automatically scheduled cronjob. Since we are using a virtual machine that's only online whenever we use it, starting this job manually is the best solution. To run a turn for game 1, type:
~/eressea/server/bin/run-eressea.cron 1
This will run fetchmail one last time (TODO: is this true?), run the turn and create reports, compress them, and mail them to the players, all in one.