raven ioctl

Documentation repository.

ioctl.org : jan's home page : Euphrates and Tigris

Euphrates & Tigris

This is a natty little board-game. In my copious spare time I'm implementing a distributed version of it. The protocol this uses is human-readable and designed to make implementing clients reasonably simple. The rules of the game are available online.

State of play

The server is pretty much finished, barring debugging (thanks to Shamus for help with the latter); the client is still at a rudimentary stage but it uses the gedhrel.qb Java framework so it should be relatively simple to finish.

Protocol details

The protocol uses the normal telnet CR+LF linebreaking but does not support WILL/WONT/DO/DONT commands; although commands exist which make playing using a raw telnet session (which supports ANSI colour escapes) possible, the intention has always been to run this for clients.

Server messages are listed below in bold; responses are in normal text. The server has the notion of a connection id; during a game, however, connections are referred to by the E+T protocol by player number (0, 1, 2, 3).

welcome id First message; id indicates this connection id.
newconn id Notifies all other connections of a new connection.
name nnn Sets this connection's name.
name id nnn Reports a name change.
who Asks for a list of connected users.
who n id1 name1 id2 name2 ... Reports on number of connections, n, and their ids and names.
say text Sends the message text to all connected users.
say id name: text This message indicates something has been said.
note text General notification of some event, in human-readable form. Generally, the message text ought to be supplied to the user though some mechanism (for instance, a talker window).
ERROR text Notification of some kind of error. The client should report the error message to the user through some mechanism (for instance, a talker window).
quit Disconnects the session. If in the middle of the game, aborts the game.
outconn id Reports that a connection has disappeared.
password pwd Sets that connection's takeover password. If no password is specified for a session, it cannot be taken over.
password-confirm pwd Confirms that the takeover password as been set.
takeover id pwd Assuming the pwd corresponds to the takeover password for the specified session, this replaces the current connection with the one associated with that session, and closes the old connection. The intention is that this be used over poor-quality networks to permit games to be resumed seamlessly.
takeover-confirm id Confirms that the takeover was successful; gives the client their new effective session id.
ask id1 id2 id3 e+t Invites up to three other players to join a game of Euphrates and Tigris. Three ids are required; for less than four players, the missing ids should be replaced with hyphens.
ask id1 id2 id3 e+t restore game-id Invites up to three other players to complete a previously aborted game.
state asked n id0 name0 id1 name1 ... Reports that you are currently being invited to join a game.
accept Accepts the invitation.
decline Declines the invitation. Returns all invited players to state connected. This command can also be issued from state accepted to cancel an acceptance.
state connected This message may occur at any time that a player is in some kind of 'shared state' with other players, and indicates that such state is over; the player is back in the initial state, not in the middle of any game.
state accepted Confirms your acceptance of the game.
accepts id name Report of acceptance to other potential players.
declines id name Lets all disappointed players know who didn't want to play with them.
state commence Readies the clients that a game is about to commence.
playorder id0 id1 ... Reports the play order. All messages involved solely with the gameplay will refer to player number, which can be converted to id by looking up in this zero-based list.
board x y description

Reports the size and state of the board. Board co-ordinates are numbered from (0,0) in the top-left to (x-1, y-1) in the bottom right. The description is made up from a continuous sequence of four-character cell descriptions and will therefor be 4xy characters in total. Cells in the description occur from left to right then row-by-row.

A four-character cell is broken down into parts: the first character signifies the type, the next three are dependent on the cell type.

Character number Meaning
1 2 3 4
.c.. An empty space. c represents the colour of the space, according to the following scheme:
  • r red;
  • g green;
  • b blue;
  • k black;
  • - no colour.
With the standard board, empty spaces will only be uncoloured or blue.
&cpl. A leader. c represents the colour of the leader, pl is the player number of its owner.
#ctrc2 A tile. c1 represents its colour. If it contains a treasure, the treasure priority is given as tr; otherwise, tr is 0. When faced with a choice of which trasures to take, a player must choose the highest-numbered treasures first. In the normal game, these are those nearest the corners of the board. Apart from this restriction, treasure selection is unconstrained. c2 is the colour of the undelying space.
^c1c2tr A monument of colours c1 and c2. tr indicates the presence of any treasure tiles.
!... A catastrophe.
=c1.. A coloured tile covered by the conflict tile.
board Can be used at any time by a player to request the board description.
ansiboard Although the intention is not that this game should be played by a direct telnet connection, this requests a board image which is delivered as a sequence of note lines. This command requires a terminal capable of interpreting ANSI colour escpae sequences.
hand tile red # green # blue # black # leader red # green # blue # black # catastrophe # Reports the players hand. Number of tiles held of each colour is given; number of leaders of the appropriate colour in hand (0 or 1), and number of catastrophe tiles left to play.
hand Can be used at any time by a player to request the hand description.
score wild # red # green # blue # black # The player's score is given. wild refers to the number of treasures claimed, which are used at the end of the game to bolster the player's weakest colour(s).
score Can be used at any time by a player to request his score.
board! x y cell The client should be ready to receive these notices at any time, which indicate that the contents of the specified cell have changed in some fashion. The new contents are described in cell according to the scheme given above.
otherhand player tile #tiles leader red # green # blue # black # catastrophe #catastrophes Indicates that the numbered opponent now holds a given number of tiles and catastrophes.
otherscore+ player wild # red # green # blue # black # Notification that an opponent has scored some points. Only deltas are recorded; although it is perfectly possible for a client to keep track of each opponent's score, it is not intended that this happen. The spirit of the game requires that an exact count of each opponent's score is not known at any given point.
abort Stops the game currently in progress; it may be requmed later.
state playeraction player action Indicates that it is player's turn to make his actionth move.
ask action Requests a move from the client that this is sent to.
pass The player whose turn it is chooses to make no move.
discard red # green # blue # black # Discards the given tiles from hand. Each number must be specified, even if zero, and in the order given (this protocol is intended for implementation by client, not telnet).
leaderadd colour x y Move the given leader from hand onto the board.
leadermove x-from y-from x-to y-to Move the given leader on the board.
leadertake x y Remove from the board the leader at the given coordinates.
catastrophe x y Play a catastrophe tile at the given coordinates.
tile colour x y Play a tile of the given colour at the given coordinates.
state internal attacker defender colour Indicate that a given colour is being contested in an internal conflict.
ask add colour Asks a player how many tiles of the given colour he wishes to commit to the current conflict. This message will be sent to attackers and defenders (in turn) for both internal and external conflicts.
add colour number Adds the given number of tiles from hand to a conflict.
state internaldef attacker defender colour added-by-attacker Indicate that a given colour is being contested in an internal conflict, and that the attacker has added added-by-attacker red tiles.
ask external colour1 colour2 ... Asks the current player which of the given conflicts should be resolved first. At present, this happens even if there is a single conflict to resolve. The current player may be asked this again after the first conflict has been resolved if any more colours are being contested.
resolve colour Asks the current player which of the given conflicts should be resolved first. At present, this happens even if there is a single conflict to resolve.
state external attacker defender colour Indicate that a given colour is being contested in an external conflict. The attacker will be sent an ask add colour message.
state externaldef attacker defender colour added-by-attacker This message is similar in purpose to the state internaldef message.
ask monument colour1 x y colour2 colour3 ... Asks the current player if he wishes to build a monument with a corner at (x, y). The possible secondary colours of the monument are given after the coordinates.
build x y colour1 colour2 The response to ask monument if the player chooses to build one. The coordinates given are of the top-left corner of the intended monument; they are required because it is possible (although unlikely) that there may be as many as four potential sites for the monument.
decline The response to ask monument if the player chooses not to build one.
state treasureask player Indicates that player has to decide which treasure tokens to take.
ask treasure Sent to the appropriate player asking him to supply coordinates of the treasure token to take. The player may be sent this message multiple times if his green leader occupies a kingdom with more than two treasures.
take x y Indicates the coordinates of the treasure that the player wishes to take first.
state gameover Indicates that the game has come to a conclusion, and that the clients should be ready to receive final scoring details.
finalscore player p wild # red # green # blue # black # position n Reports the given player's final score, and ranking.


At present, there is no way (apart from trying it) to determine if connected clients are already engaged in a game.

There is no way (at present) to a client to be involved with more than one simultaneous shared connection. This is possible to fix using a session identifier prefix on 'shared' messages, but I'm not sure of the utility.

I'd like bug reports via email to ent@ioctl.org