Chapter 1. The Protocol

Table of Contents
Startup
Pregame phase
Playing phase
Done phase

Communication between server and game server happens by means of binary tokens (opcodes), which are of type integer, followed by zero or more opcode-specific variables which can be of type integer, character, or string.

At each point in time, a game server happens to be in a specific state. Messages received from the server may lead to state changes, as may some explicit transitions being executed by the game server itself. A list of all states can be found in the appendix of states.

Several actions refer to seats on the table the game is being played on. Each seat can be either empty or have an assignment. A full list can be found in the appendix of seat assignments.

Interactions are presented here categorically. For a complete reference of game server/server interactions, please see the appendix.

Startup

The GGZ server ggzd and the game server communicate via a connection which gets established using socketpair(). The game server can then access the communication channel on a certain file descriptor. Usually this descriptor has the value 3, but if the environment variable GGZSOCKET is set, its value should be used instead. Likewise, the environment variable GGZMODE can be queried to see if the game server is running on GGZ at all.

The first message which will arrive is the GAME_LAUNCH message, used to configure the game based on the table information: how many players are going to participate, are there any reserved seats, and so on. The game server will then notify ggzd about it having the data received, and set its internal status from CREATED to WAITING.