Zappy — Présentation

Zappy est un projet réseau d'Epitech : un jeu de plateau multijoueur en temps réel se déroulant sur une carte de tuiles. Plusieurs équipes y font évoluer leurs joueurs en collectant des ressources et en réalisant des rituels d'élévation, jusqu'à atteindre le niveau maximal.

L'objectif du jeu

Chaque équipe contrôle un ensemble de joueurs (les « drones ») disséminés sur une carte torique (un monde sans bord : sortir par la droite réapparaît à gauche, par le haut réapparaît en bas). Le but est de faire monter ses joueurs du niveau 1 au niveau 8 grâce à des incantations (rituels d'élévation) qui consomment des ressources et exigent un certain nombre de joueurs réunis sur une même tuile.

Condition de victoire

La première équipe à posséder 6 joueurs de niveau 8 remporte la partie. Le serveur diffuse alors l'événement de fin de partie (seg <équipe>) et s'arrête une fois les derniers messages transmis.

Pour survivre, chaque joueur doit régulièrement consommer de la nourriture (food) : son inventaire démarre avec 10 unités de nourriture, et il meurt s'il tombe à court. Les élévations supérieures réclament les six pierres du jeu : linemate, deraumere, sibur, mendiane, phiras et thystame.

Les trois composants

Zappy est constitué de trois programmes distincts qui communiquent par un protocole texte sur TCP. Le serveur est autoritaire : il détient l'état réel du monde, applique les règles et arbitre toutes les actions. L'IA et le GUI ne sont que des clients TCP qui se connectent à lui.

Composant	Binaire	Langage	Rôle
Serveur	zappy_server	C++17	Autorité du jeu : monde, règles, temps, sockets
IA	zappy_ai	Python 3.11+	Un client par joueur ; décide des actions à envoyer
GUI	zappy_gui	C++17 + Raylib	Visualisation 3D temps réel de la partie

Le serveur est la seule source de vérité

Les clients n'imposent jamais l'état du monde. Une IA peut anticiper localement le résultat d'une action (pour décider plus vite), mais c'est toujours la réponse du serveur qui fait foi. Le GUI, lui, est purement passif : il n'envoie que la commande GRAPHIC au démarrage puis se contente d'afficher les événements reçus.

Architecture globale

graph TB
    subgraph Clients
        AI1["zappy_ai<br/>(équipe A, joueur 1)"]
        AI2["zappy_ai<br/>(équipe A, joueur 2)"]
        AI3["zappy_ai<br/>(équipe B, joueur 1)"]
        GUI["zappy_gui<br/>(spectateur)"]
    end

    SERVER["zappy_server<br/>(autorité du jeu)"]

    AI1 -- "protocole texte / TCP" --> SERVER
    AI2 -- "protocole texte / TCP" --> SERVER
    AI3 -- "protocole texte / TCP" --> SERVER
    GUI -- "GRAPHIC + événements / TCP" --> SERVER

    SERVER --- WORLD["Monde torique<br/>(tuiles, ressources, œufs)"]

Le serveur gère toutes les connexions via un unique appel poll() (entrées/sorties non bloquantes) et un ordonnanceur d'événements : chaque commande d'IA a un délai exprimé en unités de temps avant de produire son effet. La cadence du jeu est réglée par l'option -f (fréquence) : une unité de temps dure 1000 / f millisecondes — plus f est grand, plus le jeu est rapide.

Cycle de vie d'une partie

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 (état initial)
    AI->>S: (connexion TCP)
    S->>AI: WELCOME
    AI->>S: <nom-équipe>
    S->>AI: <slots restants>
    S->>AI: <X> <Y>
    loop Boucle de jeu
        AI->>S: commande (Forward, Look, Incantation, ...)
        S->>AI: réponse (après délai)
        S->>G: événements (ppo, pic, pie, bct, ...)
    end
    S->>G: seg <équipe> (fin de partie)

Comment lire cette documentation

Cette documentation est organisée par composant et par thème :

• Démarrage rapide — installer puis lancer l'ensemble (serveur, GUI, IA) en quelques commandes.
• Serveur (C++) — l'autorité du jeu : réseau, boucle de temps, monde, mécaniques, commandes et délais.
• IA (Python) — le client décisionnel : réseau, protocole, état interne, machine à états (FSM) et coordination d'équipe.
• GUI (Raylib) — le visualiseur 3D : installation de Raylib, build et rendu.
• Protocole de communication — la référence des messages échangés (handshake, IA ↔ serveur, GUI ↔ serveur).
• Glossaire — toutes les définitions des termes du jeu.

Nouveau sur le projet ?

Commencez par le Glossaire pour acquérir le vocabulaire, puis suivez le Démarrage rapide pour avoir une partie qui tourne en local.

Limitations connues

Certains comportements présentent des écarts ou des bugs documentés. Ils sont regroupés sur la page Limitations connues.