- Overview
- General Protocol Guidelines
- Authentication & Handshake
- AI
↔️ Server Protocol - GUI
↔️ Server Protocol - Examples
- Additional Notes
- References
Zappy is a distributed multiplayer game consisting of three main components:
- Server (C): Orchestrates the game world, player actions, and communication.
- Graphical Client (GUI) (C++): Connects to the server for real-time visualization and interaction.
- AI Client (any language): Autonomous agents that play the game by connecting to and interacting with the server.
All communication between components occurs over TCP sockets using a line-based, human-readable protocol. This document outlines the communication protocol, connection lifecycle, message structure, command sets, and best practices for robust interaction.
- All components communicate via TCP/IP.
- The server listens on a configurable port for both AI and GUI clients.
- Each client opens a direct TCP connection to the server.
- Line-based protocol: Each message is a single line terminated by a newline (
\n). - Plain text: Messages are composed of ASCII characters (UTF-8 safe).
- Commands: Each line represents one command or response.
- No binary data: All data is transmitted as readable text.
Forward\nWELCOME\n- All messages must use UTF-8 encoding.
- Non-ASCII characters should be avoided except in player/team names, which must be UTF-8 safe and validated by the server.
- Each connection is stateful and persistent until closed by either party.
- Clients must reconnect and re-authenticate after a disconnect.
- The server may close connections on protocol violations, timeouts, or capacity limits.
- Invalid commands or malformed messages result in an
ko(for AI) or error message (GUI) response. - The server may disconnect clients that repeatedly send invalid input.
- Clients should gracefully handle server-initiated disconnects and unexpected errors.
1. Upon connecting:
-
All clients receive the message:
WELCOME\n
2. Authentication phase:
-
AI Client: Must send the team name as the very first message.
<team_name>\n
-
GUI Client: Must send the string
GRAPHIC.GRAPHIC\n
3. Server responds:*
- If accepted:
- AI: Sends map size and client slot info.
- GUI: Sends the full world state (see below).
- If rejected (full teams, unknown team, etc.), the server closes the connection.
- AI sends:
<team_name> - Server responds:
- Number of remaining slots for the team
- Map size
- Each AI command is sent as a single line of text.
- Commands are case-sensitive and must match protocol specification.
- Arguments are separated by spaces.
Forward\nSet linemate\n| Command | Description |
|---|---|
| Forward | Move player forward |
| Right | Turn right |
| Left | Turn left |
| Look | Get visible tiles |
| Inventory | Get inventory |
| Broadcast <msg> | Broadcast message to all players |
| Connect_nbr | Get number of free slots for team |
| Fork | Lay an egg (for reproduction) |
| Eject | Push other players off the tile |
| Take <object> | Pick up an object (e.g., Take food) |
| Set <object> | Place an object from inventory onto the tile |
| Incantation | Start elevation ritual |
| Command/Response | Description |
|---|---|
| ok | Command succeeded |
| ko | Command failed |
| message <dir>, <msg> | Received a broadcast message |
| dead | Player has died |
| Elevation underway | Elevation ritual started |
| Current level: <lvl> | Level after successful incantation |
| ... | Various state updates (see subject doc) |
- GUI sends:
GRAPHIC - Server responds: Full world state via a sequence of protocol messages.
- GUI commands are single-line, case-sensitive strings.
- The GUI can request information or send control commands to the server.
msz\n # Request map size
bct x y\n # Request contents of the tile at (x,y)
mct\n # Request contents of all tiles
tna\n # Request team names
ppo #id\n # Request position of player #id| Command | Description |
|---|---|
| msz | Get map size |
| bct x y | Get contents of tile (x,y) |
| mct | Get contents of all map tiles |
| tna | Get all team names |
| ppo #id | Get player position |
| plv #id | Get player level |
| pin #id | Get player inventory |
| sgc | Get current game time unit |
| sst n | Set frequency (admin only, rarely used) |
The server pushes real-time updates to the GUI, including but not limited to:
| Command | Description |
|---|---|
| msz X Y | Map size |
| bct X Y q0...q6 | Tile contents (quantities for each resource) |
| tna <team> | Team name |
| ppo #id X Y O | Player position and orientation |
| plv #id L | Player level |
| pin #id X Y q0...q6 | Player inventory |
| pdi #id | Player death |
| enw #egg #id X Y | New egg laid |
| ebo #egg | Egg hatches |
| edi #egg | Egg dies |
| sgt T | Time unit change |
| seg <team> | Game ends, team wins |
| smg <msg> | Message to GUI |
| ... | See protocol PDF for full list |
[Client] connects to server
[Server] WELCOME\n
[Client] team1\n
[Server] 3\n
[Server] 10 10\n
[Client] Forward\n
[Server] ok\n
[Client] Look\n
[Server] [{tile1},{tile2},...]\n
[Client] Take food\n
[Server] ok\n[Client] connects to server
[Server] WELCOME\n
[Client] GRAPHIC\n
[Server] msz 10 10\n
[Server] bct 0 0 1 0 0 0 0 0 0\n
...
[Server] tna team1\n
[Server] tna team2\n
...- The full protocol, including command/response sequences and edge cases, is defined in the official protocol PDF.
- All components should robustly handle unexpected or out-of-order messages.
- For best results, implement a line buffer on both sending and receiving sides.
- The protocol is stateless with respect to the actual content of commands; the server tracks all game state and determines the validity of actions.
- Timeouts: Recommended to disconnect clients that are inactive for a pre-defined period.