# Pioneers player's guide

Dave
Cole
Andy
Heroff
Roland
Clobus
Documentation in progress
2000
Andy Heroff
2004, 2006
Roland Clobus
&legal;

## For players

### Introduction

#### Obtaining newer versions

New versions of Pioneers are regularly made available. See the homepage for latest version.

#### Reporting Bugs

If you encounter a bug, report it with the bug tracker on SourceForge. ( https://sourceforge.net/tracker/?group_id=5095&atid=105095 ). Please check first if you have the latest version.

#### Authors and History

Pioneers is a GNOME game based upon the board game Settlers of Catan created by Mayfair Games. Pioneers was originally authored by Dave Cole in the spring and summer of 1999, under the name Gnocatan. Dave wanted to be able to play the game without having to travel, so he developed a computer implementation of the game. The Pioneers project stalled in the late summer of 1999 and saw little development until the early spring of 2000 when the project was taken over by Andy Heroff and moved to SourceForge. Andy recruited several developers (including Dave) and they improved upon the original game as well as fixed bugs that have been found in older versions.

After summer 2002 the Pioneers project lay dormant again, when in summer 2003 Bas Wijnen found some security bugs, and started programming new features. A little later he was joined by Roland Clobus. Bas made the split between the core code and the user interface, while Roland was working on the user interface.

In June 2005 the project was renamed from Gnocatan to Pioneers.

To be continued...

### The Pioneers user interface

When you start Pioneers, the main window is displayed. The user interface is built up from a number of panels.

#### The client user interface

#### The identity panel

Before you have connected to a server, this panel will not be displayed. Once you have connected, the panel is painted with your player color. It also shows how many roads, settlements, and cities are still available to be built.

Once the game play starts, the last dice roll performed by a player is also displayed.

##### The identity panel

#### The actions panel

##### The waiting prompt

When it is not your turn, a message is displayed in the status line at the very bottom for whom the game is waiting.

##### The actions buttons

When it is your turn, one more more of the buttons in the action toolbar are active. Only the actions that you are allowed to perform will be enabled.

###### The actions buttons

###### Action panel buttons

Button | Description
--- | ---
Roll Dice | Roll the dice to start your turn.
Trade | Perform trade with either the bank (maritime), or with other players (domestic).
Undo | You can undo road, settlement, and city building that has just been performed. As soon as you buy a development card, play a development card, or finish your turn, you will not be able to undo building.
Finish | Indicate that you have finished performing setup, your turn, or road building.
Road | Build a road segment. It must join one of your own settlements or cities, or one of your own roads. It can be built on land or on the coast.
Ship | Build a ship. It must join one of your own settlements or cities at the coast, or one of your own ships. It can be built on water or on the coast.
Move Ship | Move a ship that is at the end of the line to another place.
Bridge | Build a bridge. It must join one of you own settlements or cities on the coast, one of your own bridges, or a road. It can only be built on water.
Settlement | Build a settlement.
City | Upgrade a settlement to a city.
Develop | Purchase a development card from the bank.

##### The robber prompt

If you roll 7 on the dice, all players who are holding more than 7 resources will be prompted to discard half of them (rounded down). While there are still players who have to discard resources, the actions panel will be replaced by a list of those players. Next to each player name is the number of resources that they must discard.

###### The discard list

##### The place robber prompt

After all excess resources have been discarded, if you were the player who rolled 7 on the dice, you must place the robber on the map. The actions panel is replaced by a prompt to that effect.

When you play a soldier development card, you must place the robber on the map. The actions panel is replaced by a prompt to that effect.

###### The place robber prompt

##### The steal from prompt

If you ever place the robber on a hex which has buildings owned by more than one other player, and more than one of them is holding resources, you will need to select the player from which you wish to steal resources. The actions panel will be replaced by a prompt which instructs you to chose the victim of the robber by selecting one of the buildings on the hex.

###### The steal from prompt

#### The resources panel

As the game progresses you will accumulate resources. The resources panel displays how many of each resource type you are holding.

##### The resources panel

#### The development cards panel

If you spend the right combination of resources, you can purchase development cards from the bank. All of the development cards that you are currently holding are displayed in this list. Note that any cards in this list are not yet in play. Other players only know how many development cards you are holding, not the types of those cards. Once you play a development card, it will be removed from this list.

##### The development cards panel

#### The player summary panel

This panel contains a summary of public statistics about all players in the game. Some of the rows in the summary have a number displayed on the right. This number represents the number of victory points that have been earned by that statistic.

If the panel grows too large to fit in the available space, it will automatically scroll to display the summary about the current player.

##### The player summary panel

#### The Pioneers map

##### The Pioneers map

Pioneers is played on a map which is built up from a grid of terrain hexes. Each hex on the map has a terrain type which defines the resources, if any, that are produced by that hex.

Settlements and cities are built on the corners of land hexes, while roads are built along the edges of land hexes.

In the center of resource producing hexes, there is a circle containing a number. At the start of each turn, two dice are rolled, all hexes that are labeled with a number equaling the sum of the two dice will produce resources for buildings on that hex. Underneath the number in the circle are some dots. The number of dots is equal to the number of different dice combinations that will generate this number. To highlight the two most commonly rolled numbers, the 6 and 8 are displayed in red (there is no label with the number 7). In addition, the hexes that produced resources this turn are painted with a green background.

The sea hexes which have a circle in them have building sites for ports where maritime trading can be performed. The location of the building sites is indicated by a dashed line drawn from the circle to a hex corner. The color of the circle indicates the resource type which may be traded at the ports. At the blue circles all resource types can be traded.

The black bottle shape is the robber.

The following table shows each terrain type, and the resources produced by that terrain.

##### Pioneers terrain types

Graphic | Terrain | Resource | Description
--- | --- | --- | ---
| Hill | Brick | Bricks are produced from the clay found in hills.
| Field | Grain | Grain is produced by crops grown in fields.
| Mountain | Ore | Ore is produced by quarries in mountains.
| Pasture | Wool | Wool is produced by sheep in pastures.
| Forest | Lumber | Lumber is produced by trees in forests.
| Desert |  | No resources are produced in the desert.
| Sea |  | No resources are produced in the sea, but maritime trading may be performed at ports.

#### The chat panel

Underneath the map is a field where you can enter messages that will be broadcast to all other players. When you type a message and press Return, the message will be broadcast to all players.

##### The chat panel

Normally, text that you type will appear with your player name, for example "`player1 said: foo`". If you start your text with "`:`" the output will omit the "said", like "`player1 needs more lumber`".

The chat also knows some special commands that start with "`/`". The commands currently defined are:

##### Chat Commands

Command | Arguments | Description
--- | --- | ---
`;` | chat message | The chat message is added directly behind the name of the player. Example: `;'s victory is imminent` will become player name's victory is imminent
`:` | chat message | The chat message is added after the name of the player with a space in between. Example: `:needs lumber` will become player name needs lumber
`/me` | chat message | This is the same as the "`:`" described above, but IRC addicts might prefer this variant.
`/beep` | player name | Let player name's client beep.

If you want to send a smiley that starts with a : or ;, type a space before the smiley.

#### The messages panel

Underneath the chat panel is a message area where all interesting game events are logged.

##### The messages panel

#### The status bar

The status bar is used for providing instructions about the current state of the game.

To the right of the instructional message is an indicator which shows when the client program is waiting for response to a command sent to the server. When packets are dropped between the server and client, the indicator will display the text "Waiting", and the game will be temporarily unresponsive.

Rightmost in the status bar is the turn indicator. This area identifies the player turn sequence. The current player is highlighted with a thick black border.

##### The status bar

### Playing Pioneers

#### Joining a Pioneers game

The Pioneers client program is "pioneers". When you run this program, you will be presented with the connect dialog.

##### The connect dialog

Using the connect dialog, you identify the game which you wish to join. This dialog is automatically invoked when you start Pioneers. If the initial connection fails, you can invoke the dialog from the Game/New game menu, or by using the Ctrl N keyboard shortcut.

###### The connect dialog

Enter your name, and join an existing game or create a new game.

Only if pioneers-server-gtk is installed, you can create new games.

##### Join public game

The dialog displays a list of Pioneers games that are currently running on the Internet. The default meta server is pioneers.debian.net

###### The Join a public game dialog

You join a game by selecting it and pressing the OK button in the connect dialog. To obtain an updated list, push the Refresh button.

Some meta servers also allow you to start new games on their host. If this is possible, the New remote game button will be active and will bring you to the Create a public game dialog.

##### The Create a public game dialog

In this dialog, you can select various parameters for the new game: board name (available types will be retrieved from the meta-server), default or random terrain, the number of players, victory points to reach, which sevens rule to apply and how many AI players should join the game.

###### The Create a public game dialog

Once you're satisfied with your choices, press the OK button. The game will be started once enough players have entered the game. The new game will of course be registered to the meta server it was started from. Other players can see it in the list if they press the Join public game button, or refresh the list of public games.

The server started remotely will terminate itself automatically when the game is finished, or if sits around for more than 20 minutes without any connected players. Please also note that adding AI players will silently fail if the pioneersai program is not installed on the meta server.

##### Join private game

You can manually specify the game that you wish to join by entering the server host and port in the Server Host and Server Port fields. The hostname/port combinations you used recently are remembered. You can recall them quickly with the Recent Games button at the bottom.

###### The Join a private game dialog

#### Pioneers setup phase

Once you have successfully connected to a Pioneers game server, the game map will be downloaded from the server and displayed in the map area of the display. You will be assigned a player color, which will be displayed in the identity panel, the player summary, and in the status bar. As soon as all other players have connected to the server, the setup phase will begin.

During the setup phase you must build one settlement and one road segment on the map. The settlement can be built on any land hex, and the road must be built on a land edge connected to the settlement.

Once you have built both your settlement and road, you must press the Finish Setup button. The next player will then enter the setup phase. The last player performs a double setup, that is, they build two settlements, each with a connecting road. Once the last player has completed setup, all other players perform a second setup in reverse sequence.

Once the first player has completed their second setup, the game will begin.

#### Pioneers turn sequence

When it is your turn, the actions panel will show all of the actions that you can perform. Some care must be exercised, as some actions can only be performed once per turn, and other actions can only be performed in strict sequence.

##### Simplified turn sequence

1. Roll the dice.

2. Optionally trade with the bank, or other players.

3. Optionally build roads, settlements, and cities. Optionally buy development cards.

4. Finish your turn.

You may play one non-victory point development card at any time during your turn, even before you roll the dice. You may play as many victory point cards as you like at any time during your turn.

As soon as you have built a road, settlement, or city, you will not be able to trade for the rest of the turn. Likewise, if you buy a development card, you will not be able to trade for the rest of the turn.

##### Dice roll / resource collection

When the dice are rolled, they are added together, the total determines the resources that each player collects during that turn. In the center of each land hex (except for the desert) is a number. Whenever the dice roll matches the number in the hex, all buildings on the corners of that hex will collect resources of the type generated by that hex.

Settlements collect one resource, and cities receive two resources. If a player has multiple buildings on a hex, each of those buildings will collect resources.

The hex containing the robber never generates resources.

If you roll 7 on the dice, all players with excess resources must discard them, then you must move the robber.

##### Discarding resources

If you roll 7 on the dice, all players holding more than 7 resources must discard half of them. The discard resources dialog will be displayed for all players who must discard.

###### The discard dialog

You must choose the resources to be given back to the bank.

Once all players have discarded their excess resources, the player who rolled the 7 will have to move the robber.

##### Moving the robber

The robber begins the game in the desert, but can never be moved back into the desert.

If you roll 7 on the dice, you must move the robber to a new location on the map.

Whenever you play a soldier development card, you must move the robber to a new location on the map.

Once you have moved the robber to a new hex, the robber will steal a random resource from another player who has a building on that hex. If there are multiple potential victims for the robber, you will need to choose the victim by selecting one of the buildings on the hex. When the robber steals the resource, only the players involved in the transaction will be told which resource was stolen.

#### Trade

You may trade resources only after you have rolled the dice, but before you build anything, or buy a development card. When you wish to trade resources, press the Trade button in the actions panel and the trade interface will be displayed.

##### The trade interface

On the left side of the interface are two frames; the top frame is where you specify which resources you wish to receive in a trade, and the bottom frame is where you optionally specify which resources you wish to give to other players during a trade.

Each frame contains a table, and each row of the table describes one resource. From left to right, the columns are;

##### Trade resource controls

Check | Controls whether or not this resource will be involved in the trade. Trade quotes submitted by either the bank or other players can only include resource types that are checked.
Name | The resource type.
In hand | Shows how many of each resource type you have in hand. If you select a valid trade, you see the amount you will have if you accept the quote.

The Call for Quotes button underneath the two tables is used to invite other players to trade resources with you.

To the right of the tables is the list where all quotes will be displayed. The bank quotes are listed first, followed by all quotes supplied by other players. The first quote from each player is highlighted with an indicator. Next to each player quote is tick or cross which indicates whether or not you have the resources to perform the trade. As you select quotes from the list, the Accept Quote button sensitivity will also indicate whether or not you have the resources required to perform the trade. Also the amount of each resource shows a preview how many you will have if you accept the quote.

To finish trading, press the Finish Trading button at the bottom right of the trading interface.

##### Trading with the bank

Maritime trade is trade performed with the bank. To perform maritime trading, check one or more resources in the I Want table. If you have sufficient resources to perform maritime trading, the bank will quote for each possible trade.

- Players who have built on a port with a resource label may trade two identical resources of that type for single resource of their choice.

- Players who have built on a port with the question mark label may trade three identical resources of any type for single resource of their choice.

- All players may trade four identical resources of any type for a single resource of their choice.

Select the trade that you wish to perform, then press the Accept Quote button.

##### Trading with other players

Domestic trade is trade performed with other players. To perform domestic trading, check one or more resources in the I Want table, and one or more resources in the Give Them table. Once you have specified the resources that you wish to exchange in the trade, click the Call For Quotes button. All other players will then use the quote interface to submit quotes within the trade parameters you have set.

Select the trade that you wish to perform, then press the Accept Quote button.

##### Submitting trade quotes

When another player presses the Call For Quotes button in the trade interface, the quote interface will be displayed.

###### The quote interface

The top of the interface has an indicator to show which player initiated the trade. It also describes the trade parameters.

On the left side of the interface are two frames; the top frame is where you specify which resources you wish to receive in a trade, and the bottom frame is where you specify which resources you wish to give to the player who initiated the trade exchange.

Each frame contains a table, and each row of the table describes one resource. The player who initiated the trade controls which rows in each table can be used. If the initiating player calls for a resource that you do not have, the corresponding row in the Give Them table will be disabled. From left to right, the columns are;

###### Quote resource controls

Name | The resource type.
In hand | Shows how many of each resource type you will have in hand after performing trade.
Less | Press this to decrease the number of the resource you wish to receive / give.
More | Press this to increase the number of the resource you wish to receive / give.
Number to trade | Shows how many of the resource you wish to trade.

Underneath the tables are two buttons. Press the Quote button to submit a new quote, or press the Delete button to retract a quote. Note that the Quote button will be disabled if you have already submitted a matching quote.

To the right of the tables is the list where all quotes will be displayed. Quotes from all players are listed. The first quote from each player is highlighted with an indicator.

To decline the offer to perform trading, press the Reject Domestic Trade button at the bottom right of the interface.

#### Development cards

There are 25 development cards in the game, they are shuffled at the start of the game. When you buy a development card from the bank, it is held secret in your hand. Other players only learn how many development cards you have, not the types of those cards.

When you play a development card, all other players will see the card. There are victory point, and non victory point development cards. Victory point development cards earn you one victory point as soon as you play them. Non-victory point development cards have special effects as described below.

##### Development cards

VP | Card | Number | Description
--- | --- | --- | ---
| Road Building | 2 | When you play this card, you can build two road segments for free. The normal limits on road building apply.
| Monopoly | 2 | When you play this card, you choose a resource type that you want to monopolize. All resources of that type that are held by other players will transferred to your hand.
| Year of Plenty | 2 | When you play this card you can take any two resource cards from the bank.
| Soldier | 14 | When you play this card, you must move the robber to a new hex. The first player to play three soldiers will earn the largest army award.
1 | Chapel | 1 | No special effects.
1 | Pioneer University | 1 | No special effects.
1 | Governors House | 1 | No special effects.
1 | Library | 1 | No special effects.
1 | Market | 1 | No special effects.

##### The monopoly development card

When you play the monopoly development card, the monopoly dialog will be displayed.

###### The monopoly dialog

You must choose the resource type that you wish to monopolize. When you press OK, all resources of the selected type held by other players will be transferred to your hand.

##### The year of plenty development card

When you play the year of plenty development card, the year of plenty dialog will be displayed.

###### The year of plenty dialog

You must select any two resource cards that you wish to take from the bank.

If the bank has enough cards, ++ is shown between the less and more buttons. Otherwise, the amount in the bank is shown.

##### Largest army award

The first player to play three soldier cards will earn the largest army award. This award is worth 2 victory points.

Only one player can have the largest army award at a time.

Ownership of the largest army award will change only when another player builds a larger army.

#### Building

By spending the right combination of resources, you can build roads, settlements, and cities. At any time during the game you can check the resource cost of each type of building by consulting the legend dialog.

##### The legend dialog

At the start of the game, you have 15 road segments, five settlements, and four cities available. You will not be able to build more of any item than you have available. The identity panel tells you how many of each item you currently have available.

A city is built by upgrading a settlement. When you upgrade an existing settlement, that settlement is again available for building somewhere else on the map.

Buildings must not be placed next to each other. This means that a hex can have, at most, three buildings on it. During game play, you can only place a building adjacent to one of your road segments.

Roads must be placed adjacent to one of your buildings, or one of your roads. You cannot extend your road through a building owned by another player.

##### Longest road

The first player to build a continuous path of five or more road segments will earn the longest road award. The length of your road is measured by determining the greatest distance that can be traveled from one point on your road to another without traveling over the same segment more than once, and without backtracking.

This award is worth 2 victory points. Only one player can have the longest road award at a time.

If another player builds a longer road, the longest road award will be transferred to that player.

If the longest road is cut by a player placing a building which divides the road, the ownership of the longest road award is re-evaluated. If after the longest road has been cut, and more than one player has the longest road, the award is temporarily removed from play. If no player has a road of five or more segments, the award is temporarily removed from play.

#### Game objective

The objective of the game is to achieve a certain number of victory points before all other players. There are several ways to earn victory points.

- For each settlement you have on the map, you earn 1 victory point.

- For each city you have on the map, you earn 2 victory points.

- The player with the longest road of five or more segments earns 2 victory points.

- The player with the largest number of soldiers in play (minimum of three) earns 2 victory points.

- There are a number of special development cards which when played are each worth 1 victory point.

##### The game over dialog

Once you have won the game, all players will to notified of your glorious victory.

###### The game over dialog

### Frequently asked questions

#### Playing games

Where can I find games?

You can find games at the metaserver (pioneers.debian.net)

But there hardly are any games present?

Perhaps people don't register their games (it is optional), or use their own metaservers.

I've seen a game at the metaserver, but I cannot join?

Is the Host something like 'localhost' or without dots? In that case someone did register the game, but it is not accessible from the outside of the intranet that hosts the game.

The button 'New remote game' is always disabled. Why?

The metaserver at pioneers.debian.net acts only as a point where games can register. It has been configured not to create new games.

#### The chat room

Why is nobody responding?

If you enter the chat room, and see several squares in the icon before the name of a player, it means that that player is disconnected.

This game will never start. How can I play?

One person has to create a new game. If it is set up, you can start a new instance of pioneers, and connect to that game. You can quit the instance of pioneers with the chat room.

#### Creating games

How do I do create new games?

Run pioneers-server-gtk. In the server parameters:

- Choose a port that is publicly accessible (create a hole in your firewall if needed)

- Set register to 'yes', so other people can find the game

- Leave metaserver empty, or use 'pioneers.debian.net'

- Reported hostname should be your publicly accessible hostname or ip address

- Select a game of your liking, and click 'Start Server'

What exactly does 'reported hostname' do?

For computers directly connected to the Internet: it should contain your ip address or full hostname.

For computers connected to the Internet using an intranet: it should contain the ip address (or full hostname) of the connection to the Internet, AND you need to have your gateway set up for port forwarding, to accept incoming connections.

How do I configure my router?

Henner Keßler wrote a small HOWTO describing a possible way to configure your router, using dyndns.

What if I only want to play against the computer players?

Use the pioneers-server-gtk, and set register to 'no', and add as many computer players as needed. In the client, choose 'Join private game', the host is 'localhost', and use the port you have selected in the server.

What if I only want to play games inside my own intranet?

Do not register your game at the metaserver, and choose 'Join private game' on each computer that joins the game. Use the ip address of the server, and the port you have selected in the server.

## For game masters

### The Computer Player

Pioneers comes with a computer player, pioneersai. This player isn't too bad at the moment, but not finished yet. Most notably, it cannot initiate domestic trade, and use the maritime rules yet.

pioneersai is a terminal application without GUI. Its command line options are:

#### pioneersai command line options

Option | Arguments | Description
--- | --- | ---
-s | servername | Connect to servername
-p | port | Connect to port port
-n | name | Set the player name. If this option is absent, a random name will be choosen.
-a | playertype | Choose the type of AI player. Currently, there is only one type `greedy`, which is obviously also the default.
-t | milliseconds | Set time to wait between turns.
-c |  | Stop the computer player from giving comments.

However, most of the time you won't start pioneersai manually. Both game servers offer ways to start a number of AI players.

### Configuration

This chapter is included for the people who wish to control exactly the way Pioneers is running.

The extra configuration options are processed in this order:

1. Command line

2. Settings file

3. Environment

4. Built-in settings

#### pioneers

The client is controlled by the command line, the environment and the settings file.

##### pioneers command line options

Short | Long | Description
--- | --- | ---
-s | --server | Hostname of the server
-p | --port | Port of the server
-n | --name | Player name
| --language | Override the language as set in the environment. Valid choices: de en es fr hu it nl sv

When both the server and port are set, the client will not display the connect dialog, but will directly connect to this port. When the connection is closed (because the game is over, or the connection fails), the client quits.

Server and port need both to be set, or not at all.

##### Settings file ~/.config/pioneers

Section | Key | Type | Description
--- | --- | --- | ---
connect | server | string | Last used server for private game
connect | port | string | Last used port for private game
connect | meta-server | string | Address of the meta server
connect | name | string | Last used player name
favorites | server%dname | string | History entry of private server games
favorites | server%dport | string | History entry of private server games
settings | color_chat | boolean | Display chat messages in user's color
settings | color_messages | boolean | Display colors in the message log
settings | color_summary | boolean | Use colors in the summary
settings | toolbar_show_accelerators | boolean | Show the keyboard accelerators in the toolbar
settings | show_toolbar | boolean | Show the toolbar
settings | legend_page | boolean | Display the legend page beside the map
settings | theme | string | The theme

##### pioneers environment

Variable | Description
--- | ---
PIONEERS_META_SERVER | The host name of the meta server

When the host name is not provided in the client, this environment variable will be used. If it is not set, the default (pioneers.debian.net) will be used.

#### pioneers-server-console

##### pioneers-server-console command line

M | Short | Type | Description
--- | --- | --- | ---
| -a | integer | Admin port to listen on
* | -c | integer | Number of computer players to add
* | -g | string | Game name to use
| -h |  | Show help
* | -k | integer | Kill after n seconds with no player
| -m | string | Register at meta-server name (implies -r)
| -n | string | Use this hostname when registering at the meta-server
* | -P | integer | Number of players
* | -p | string | Port to listen on
* | -r |  | Register with meta-server
| -R | 0|1|2 | Seven rule
| -s |  | Don't start game immediately, wait for command on admin port
| -t | integer | Tournament mode. AI players added after %d minutes
* | -T | 0|1 | Select terrain type (0=default, 1=random)
* | -v | integer | Number of points needed to win
* | -x |  | Quit after a player has won

The column 'M' shows whether the switch is used by the meta-server

##### pioneers-server-console environment

Variable | Description
--- | ---
PIONEERS_DIR | The location of the *.game files
PIONEERS_META_SERVER | The host name of the meta server

#### Server admin interface protocol

When the server is started with the command line switch `-a`, the following commands can be sent to that port:

##### Admin interface commands

Command | Argument type
--- | ---
`admin set-game` | string
`admin set-register-server` | integer
`admin set-num-players` | integer
`admin set-sevens-rule` | integer
`admin set-victory-points` | integer
`admin set-random-terrain` | integer
`admin set-port` | integer
`admin start-server` | none
`admin stop-server` | none
`admin quit` | none

`admin set-game` should be used before the other game parameters are changed, because it changes all game parameters.

If a game was running while a game parameter is changed, it will be aborted.

When no game is running when `admin quit` is issued, the application will quit.