Skip to content

Protocol — Overview

The Zappy server exposes a single TCP port (default 4242) on which two distinct families of clients connect:

  • the AI (the autonomous players, one zappy_ai process per drone);
  • the GUI (the graphical viewer zappy_gui).

Both channels share the same port and the same transport mechanics, but speak two different textual dialects. The server determines the client type from the first line it receives after the welcome message (see Handshake).

flowchart LR
    AI1["zappy_ai (drone)"] -- "text, \\n" --> S(("Server\nport 4242"))
    AI2["zappy_ai (drone)"] -- "text, \\n" --> S
    GUI["zappy_gui"] -- "text, \\n" --> S
    S -- "replies + events" --> AI1
    S -- "world events" --> GUI

Transport

Newline-terminated text lines

All communication is textual, line by line. Every message (request or reply) is terminated by a newline \n. The server tolerates and strips a trailing \r (NetworkBuffer::popLine, server/srcs/network/NetworkBuffer.cpp). Sockets are non-blocking on both sides.

The server keeps a per-client read buffer bounded to MAX_BUFFER_SIZE = 65536 bytes (server/srcs/network/AClient.hpp); an overflow closes the connection.

Common conventions

Identifiers

Player and egg identifiers are prefixed with # on the GUI channel (e.g. #3). The AI channel never manipulates identifiers: a drone only knows its own local view.

Direction encoding (GUI)

Player orientations are transmitted to the GUI as integers:

Code Direction
1 North
2 East
3 South
4 West

(directionToGui, server/srcs/protocol/GUIProtocol.cpp.)

Resource indices

Resources are always enumerated in this fixed order, both in tile contents (bct, Look) and in inventories (pin, Inventory). The index is used as-is by the pgt/pdr events:

Index Resource
0 food
1 linemate
2 deraumere
3 sibur
4 mendiane
5 phiras
6 thystame

(resourceToGuiId, server/srcs/protocol/GUIProtocol.cpp; Resource enum, server/srcs/world/Tile.hpp.)

Broadcast sound direction (AI)

A message received by a drone (message K, <text>) carries a K ∈ 0..8 indicating the tile/sound it comes from, relative to the receiving drone's orientation. K = 0 means "same tile"; 1..8 indicate the directions around the drone, starting from the front and turning counter-clockwise (server/srcs/algorithms/BroadcastAlgo.cpp).

Time units and frequency

Game time is expressed in time units. One unit lasts 1000 / f milliseconds, where f is the server frequency (option -f, default 100). A higher frequency therefore speeds the game up. Each AI command has an execution delay expressed in time units (see AI ↔ Server). The GUI can change the frequency on the fly with sst (see GUI ↔ Server). Reference: server/srcs/scheduler/Scheduler.cpp.

In-flight command limit (AI)

10 pending commands maximum

A drone may have at most 10 commands awaiting a reply at any time. Any additional command immediately receives ko (server/srcs/core/AICommandDispatcher.cpp). On the AI side, the CommandQueue enforces the same MAX_PENDING_COMMANDS = 10 bound (ai/src/network/command_queue.py).

Protocol pages

See also Server > Mechanics and AI > Protocol layer.