GUI (Raylib) — Overview¶

The Zappy graphical client (gui/) is a real-time 3D viewer written in C++17 with Raylib. It connects to the Zappy server as a GRAPHIC client: it does not play, it sends no game command, it simply displays the world the server describes to it.

The scene uses a perspective camera orbiting the map; every player, egg and resource is drawn as a billboard sprite (a quad always facing the camera), on top of a 3D checkerboard of tiles.

In one sentence

The GUI reads the server's protocol stream, rebuilds the world state in memory (GameState), then renders it at 60 FPS in a 1280×720 window.

Key characteristics¶

Single-process, single-thread. One loop does everything: networking, parsing, update, rendering (gui/src/core/main.cpp:67).
Non-blocking socket. The network is polled without ever blocking the render loop (gui/src/network/NetworkClient.cpp:79).
No command input. The GUI only emits the GRAPHIC\n handshake (gui/src/core/main.cpp:55); afterwards it merely listens.
3D billboard rendering. Animated sprites, team recoloring via GLSL shader, movement interpolation.

Source tree¶

The code is split by responsibility (gui/src/):

src/
├── core/        # main.cpp (loop, CLI, handshake) + GameState.hpp (world state)
├── network/     # NetworkClient (socket) + MessageParser (protocol decoding)
├── player/      # Direction, PlayerData, PlayerMotion(Tracker) — interpolation
├── renderer/    # Renderer3D, IsoCamera, AnimatedSprite, PlayerCard
└── world/       # ResourceType, TileData, EggData

Compilation produces the build/zappy_gui binary (gui/Makefile:12).

Dead code

The gui/raylib/ folder (Window.hpp/Window.cpp) is an old wrapper that is not compiled (absent from the Makefile SRCS). Do not rely on it.

Processing chain¶

The four core components form a one-way pipeline: server bytes become lines, lines become state mutations, the state is rendered to the screen.

flowchart LR
    S[Zappy server] -->|TCP| NC[NetworkClient]
    NC -->|lines| MP[MessageParser]
    MP -->|mutations| GS[GameState]
    GS -->|read| R[Renderer3D]
    R -->|frames| W[Raylib window]

Component	Role	File
`NetworkClient`	Non-blocking TCP connection, line splitting	`gui/src/network/NetworkClient.cpp`
`MessageParser`	Decoding of the 21 protocol commands	`gui/src/network/MessageParser.cpp`
`GameState`	World state (map, players, eggs, timers)	`gui/src/core/GameState.hpp`
`Renderer3D`	Camera, tiles, sprites, shader, HUD	`gui/src/renderer/Renderer3D.cpp`

Where to go next¶

Installing Raylib The most important dependency. Raylib must be present on the system — start here.
Build & run Compile with make, run zappy_gui -h <host> -p <port>.
Graphics rendering The render loop, the camera, the animated sprites, the team shader.
GUI ↔ Server protocol The commands the GUI knows how to interpret.

Limitations

Some aspects are incomplete (frozen player info card, sst/mct commands not handled, Raylib version not pinned). See Known limitations.