server/doc/introduction.md

# Introduction

Eressea is a play-by-email strategy role-playing game that simulates a fantasy world. Unlike most video games, there are are no fancy graphics, but everything that happens is communicated by text.

As a player, you are in control of a number of characters, which are referred to as units, which combine to make a faction. Your faction competes with other factions over the resources of the world that you explore together. Sometimes this leads to war, and sometimes to friendship between factions, and eventually it all adds up to a rich history of the world, with its own heroes and legends.

Eressea is different from most games in many respects, but most of all in that there is no declared winner. There is not even a goal, other than to enjoy yourself, and set your own goals. Do you want to monopolize a natural resource? Become the strongest military force? Create a democratic government for the factions in your part of the world? Collect trophies from slain dragons? Map the entire globe? Those are all valid goals to set for yourself, but you might find your own.

### How to play

Eressea is played in weekly turns. Every weekend, you receive a textual report containing your units, the part of the world that they can observe, and any events that happened since the last report. 

Based on that report, players send an email to the game's server that contains orders for all of their units. A week later, the server evaluates the orders from all players, updates the state of the world, and sends out new reports.

A (slightly simplified) report may look like this:

	Report for Eressea, Sunday, 13. April 2014, 23:25

	It is the first week of the month of harvest moon in
	the 1. year of the fourth age. It is summer.

	Guardians (xin8), elves/draig (guardian@gmx.de)

	Your faction has 4 people in 1 unit.

	Vetkan (10,1), highland, 1012 peasants, 13156 silver,
	17 horses. To the northwest lies the forests of
	Buviken (9,2), to the northeast the mountains of Rebus
	(10,2), to the east the plain of Setutvul (-9,1), to
	the southeast the mountains of Vithil (-9,0), to the
	southwest the forests of Posotmetid (10,0) and to the
	west the forests of Cesartapun (9,1)

	The local market offers silk and mandrakes.

	Statistics for Vetkan (10,1):

	  Peasant wages: 11 silver
	  Recruits: 25 peasants

	  Pelenth (opw4), size 10, fortification.

	    * Fighters of Pelenth (r6b0), 4 elves,
	      aggressive, skills: melee 5, has: platemail,
	      sword, 500 silver.

	  + Osswid the Destroyer (wtmj), Vikings (atnf), 1
	    dwarf, has: 1 iron.

What you see here are two units, Osswid (wtmj) and the Fighters of Pelenth (r6b0). The fighters are our own unit, but Osswid belongs to the faction Vikings (atnf). Every unit, faction or other object in the game is identified by a four-letter code, and it is common to append it to the name in parentheses. The fort of Pelenth (opw4) is a building, and our fighters are inside, which causes them to be indented a little more, and gives them some benefits including additional protection in combat.

While Osswid is a single dwarf, our unit of fighters consists of several elves. Units can any number of men, which are always of the same race. Each unit can learn any number of skills, and our Fighters are skilled in melee combat at a respectable level 5. They own a sword and one platemail, which means that one of them will be well equipped when going into battle, while the other three will fight with their bare hands. The unit also has 500 pieces of silver, the currency of the game.

Since he isn't of our own faction, we cannot tell what skills Osswid has, but we can tell that he's unarmed.

We see all this because one of our units is in the region, the highland of Vetkan (10,1). Regions do not have a four-letter identifier, but are instead identified by their coordinates on the map, which makes it easier to visualize the world.

The region of Vetkan is surrounded by a number of other regions on six sides, since Eressea's Map uses a hexagonal grid. Every region has a terrain, and we can see highland, mountain, plain and forest regions in our vicinity. Each terrain has different qualities: For example, mountains are good for mining iron ore and quarries, while plains are fertile and forests produce lumber. Each region is inhabited by a peasant population, and you can see that Vetkan has a population of 1012. These peasants are the basis of the region's economy, and they own a combined 13,156 silver that we could try to acquire through taxation or other means.

Example orders for this faction may look like this:

	ERESSEA xin8 "password"
	UNIT r6b0
		STUDY perception
		GIVE wtmj 100 silver
		GIVE TEMP 1 150 silver
		GIVE TEMP 2 150 silver
	MAKE TEMP 1
		RECRUIT 1
		MOVE W
	END
	MAKE TEMP 2
		RECRUIT 1
		MOVE E
	END

Every set of orders begins with the faction's id and password, and is followed by orders for one or more units. A unit's orders begin with the word UNIT followed by the unit's id, and one or more orders. In this case, we are giving the unit an order to STUDY the perception skill, and to GIVE silver to three other units. STUDY is a standard action, and each unit can perform exactly one per turn. If you do not specify a standard action, then the unit will usually repeat the action from the previous week. GIVE is a free action, and all units can perform as many free actions in a week as they like.

The MAKE TEMP order is special: It creates a new unit with a temporary id (in this case, we're calling them TEMP 1 and TEMP 2). The server will replace this with a unique id by the time it sends the next report, but until then, we can address the new unit by this temporary identifier, for example to give it the silver that it requires for recruiting new members. RECRUIT is another example of a free action, while MOVE is a standard action. The MAKE TEMP order is technically given by the unit whose orders preceded it, and the new unit's orders are finished with the END keyword.