Zappy — Overview

Zappy is an Epitech networking project: a real-time, multiplayer board game played on a tile map. Several teams grow their players by collecting resources and performing elevation rituals, racing to reach the maximum level.

The goal of the game

Each team controls a set of players (the "drones") scattered across a toroidal map (a borderless world: leaving on the right reappears on the left, leaving at the top reappears at the bottom). The aim is to raise your players from level 1 to level 8 through incantations (elevation rituals) that consume resources and require a given number of players gathered on the same tile.

Win condition

The first team to own 6 players at level 8 wins the game. The server then broadcasts the end-of-game event (seg <team>) and shuts down once the last messages have been delivered.

To survive, every player must regularly consume food: its inventory starts with 10 units of food, and the player dies if it runs out. Higher elevations require the six stones of the game: linemate, deraumere, sibur, mendiane, phiras and thystame.

The three components

Zappy is made of three distinct programs that communicate through a text protocol over TCP. The server is authoritative: it holds the real state of the world, enforces the rules and arbitrates every action. The AI and the GUI are merely TCP clients connecting to it.

Component	Binary	Language	Role
Server	zappy_server	C++17	Game authority: world, rules, time, sockets
AI	zappy_ai	Python 3.11+	One client per player; decides which actions to send
GUI	zappy_gui	C++17 + Raylib	Real-time 3D visualization of the game

The server is the single source of truth

Clients never dictate world state. An AI may locally anticipate the outcome of an action (to decide faster), but the server's reply is always authoritative. The GUI is purely passive: it sends only the GRAPHIC command at startup and then merely displays the events it receives.

Global architecture

graph TB
    subgraph Clients
        AI1["zappy_ai<br/>(team A, player 1)"]
        AI2["zappy_ai<br/>(team A, player 2)"]
        AI3["zappy_ai<br/>(team B, player 1)"]
        GUI["zappy_gui<br/>(spectator)"]
    end

    SERVER["zappy_server<br/>(game authority)"]

    AI1 -- "text protocol / TCP" --> SERVER
    AI2 -- "text protocol / TCP" --> SERVER
    AI3 -- "text protocol / TCP" --> SERVER
    GUI -- "GRAPHIC + events / TCP" --> SERVER

    SERVER --- WORLD["Toroidal world<br/>(tiles, resources, eggs)"]

The server handles all connections through a single poll() call (non-blocking I/O) and an event scheduler: every AI command has a delay expressed in time units before it produces its effect. The game pace is set by the -f (frequency) option: one time unit lasts 1000 / f milliseconds — the larger f, the faster the game.

Lifecycle of a game

sequenceDiagram
    participant AI as zappy_ai
    participant S as zappy_server
    participant G as zappy_gui

    G->>S: GRAPHIC
    S->>G: msz, sgt, tna, mct, pnw/plv/pin, enw (initial state)
    AI->>S: (TCP connection)
    S->>AI: WELCOME
    AI->>S: <team-name>
    S->>AI: <remaining slots>
    S->>AI: <X> <Y>
    loop Game loop
        AI->>S: command (Forward, Look, Incantation, ...)
        S->>AI: reply (after delay)
        S->>G: events (ppo, pic, pie, bct, ...)
    end
    S->>G: seg <team> (end of game)

How to read this documentation

This documentation is organised by component and by theme:

• Quick start — install then launch the whole stack (server, GUI, AI) in a few commands.
• Server (C++) — the game authority: networking, time loop, world, mechanics, commands and delays.
• AI (Python) — the decision client: networking, protocol, internal state, finite-state machine (FSM) and team coordination.
• GUI (Raylib) — the 3D viewer: installing Raylib, building and rendering.
• Communication protocol — the reference of exchanged messages (handshake, AI ↔ server, GUI ↔ server).
• Glossary — all definitions of the game's terms.

New to the project?

Start with the Glossary to pick up the vocabulary, then follow the Quick start to get a game running locally.

Known limitations

Some behaviours have documented discrepancies or bugs. They are gathered on the Known limitations page.