How sigmapitech/zappy works
Project Type and Purpose
• ZAPPY is a full-stack, networked multiplayer game composed of three primary subsystems:
• Server (written in C) – the authoritative game logic and networking engine
• GUI client (written in C++) – a real-time OpenGL/SDL2 visualizer that connects as the “GRAPHIC” team
• AI client (written in Python) – autonomous player agents that connect to the server, parse state, and issue commands
• Additional support components include the “runner” (Python scripts to orchestrate AI teams in CI/testing), developer scripts, documentation, and Nix/flakes build configurations.
Key File-Tree Indicators
• Top-level directories:
• ai/ – Python package implementing client logic, communication cipher, async/sync** clients, legacy code
• gui/ – C++ API layers, rendering engine (Demeter), entities, networking, main entrypoint
• server/ – C code organized by client I/O, lifecycle, game events, networking, ring buffer utilities, world management
• runner/ – Python CLI to launch AI processes for automated matches
• scripts/ – Developer tooling for code formatting, header insertion, commit checks
• docs/ – Sphinx/Doxygen documentation for each subsystem and cross-cutting protocols
• Build and configuration: Makefile at root, Doxyfile, flake.nix, CI workflows in .github/workflows.
• Server Core (red)
• Network Listener / TCP Acceptor
• Client Manager
• Game Logic Engine (world grid, resource spawner, event queue)
• Protocol Validator / Command Executor
• Broadcast Propagation Service
• AI Clients (green)
• Command Manager + Async/Sync Client
• Message Cipher Module
• Behavior Engine (parsing look/inventory, deciding moves)
• GUI Client (green)
• Network Module (same protocol, reserved “GRAPHIC” team)
• Rendering Engine (Demeter, OpenGL/SDL2)
• Entities & Sub-window Manager
• Runner & CI Tools (blue)
• Python orchestration to spin up multiple AI clients
• Test harness invoking server and validating game outcomes
• Developer Scripts & Build System (gray)
• Makefile, Doxygen, Nix flakes, commit-hook scripts
• AI Clients →← Server Core over TCP sockets (exchange textual protocol commands and state updates)
• GUI Client →← Server Core over TCP (push-based updates → renderer)
• Server Core internal: Network Listener → Client Manager → Game Logic → Broadcast Service → Network I/O
• Runner orchestrates spawning of Server Core and multiple AI Clients; collects logs and metrics
• CI Workflows trigger tests against each subsystem (ai, gui, server)
c. Architectural Patterns and Principles
• Modular separation: network I/O, game logic, client logic, rendering decoupled into their own modules
• Event queue pattern on server for ordered player actions and world updates
• Client-Server protocol layer common to both AI and GUI (“GRAPHIC” is just a reserved team name)
• Use of asynchronous messaging in AI module vs. event-driven redraws in GUI for performance
d. Technologies and Frameworks
• Server: plain C, POSIX sockets, custom ring buffers, Makefile build
• GUI: C++17, SDL2, OpenGL, ImGui, custom asset loaders (.obj3D, GLSL shaders)
• AI & Runner: Python3, asyncio, custom cipher, pyproject.toml for dependencies
• DevOps: Nix/flakes, CI via GitHub Actions