Protocols for Hearts

This is a small description of the protocols used by the hearts app and server.

This is a documentation of the game available in hearts.luispedro.org.

Design

There are two protocols used by hearts. For playing in the network, we first contact a public server to find out if there are any others in the same situation. This protocol lets users know of others, of whether they are available for games, etc. In the future, one might such functionality as the possibility to login with a given reserved name. The result of this phase is that four players are assembled. Here the second protocol comes into play. In it, the four players connect to a common game server which controls the whole game. This server might be on the internet, or it might be one of the players. If it is one of the players, the problem of users behind firewalls remain to be solved. Here the players exchange messages with the server whichcontrols the whole game. In the future this "game server" might report back to the "login server" the results of the game for user rating purposes.

Protocol basics

The protocol is text-based. The enconding used is 8-bit Ascii. All text is exchanged in English and it is left for the app to translate if necessary. This makes possible for diffferent players to translate to different strings. Where sensible, the serverr replys with text-codes instead of the real text.

The protocols are based in exchanging messages. These can be single messages or Request/Reply pairs. Each message starts by a codeword followed by a space-separated list of arguments (which can be empty) and ends with a unix-style newline character. Request/Reply pairs are identified by using the letters Q (for Query) and R (for Reply) at the end of a messagecode. For example, here is how the server asks for a player's name:

NameQ<NL>
NameR "super trouper"<NL>

We also see another aspect in the small example: strings are quoted. In general numbers are passed as text in the obvious way, and strings are quoted. See each protocols description for more information on this.

Hearts Game Protocol

This is the protocol used when the game is going on. It is used both when playing a network or a local game (a local game being a network game using Unix Protocol communication).

Server Messages

startGame: startGame port

Tells the client to start running a game server on the specified port

connectTo: connectTo host port

Tells the client to connect to host:port.

lookAt: lookAt name player1 player2 player3 player4

Informs the user of an existing table named name with players named 1 through 4. If any of these players are not set, the value passed is the special value [null].

Client Messages

createTable:createTable name

Tells the server to create a new table named name

joinTable: joinTable tableName

Tells the server that the player wishes to joing the specified table.

leaveTable: leaveTable

Tells the server that the player wishes to leave the table it is currently on.

hello. hello name

This should be the first message that the client sends. It advertises which name the player wishes to be known under. In the future there will probably be added a password or similar mechanism for doing this.

Whenever there is a change to the tables generated by one of the players, either with createTable, joinTable or leaveTable, other players, including the player which caused the change, will get a lookAt message reporting the new changes.