Project Components

Three independent modules communicating over TCP

AI Client

No language constraint — autonomous agents that explore Trantor, forage resources, communicate via broadcasts, and coordinate incantations. The player can send up to 10 commands ahead without waiting for responses.

Any LanguageTCPAutonomous

Read docs →

SRV

Server

Written in Rust (spec allows C, C++ or Rust). A single-process, single-thread server using poll() — manages the Trantor world simulation, enforces timing rules, and dispatches events to AI and GUI clients.

Rustpoll()TCP

Read docs →

GUI

Written in C++ (SFML recommended). Connects to the server using the special GRAPHIC team name. Must include a 2D visualisation at minimum; 3D is a bonus.

C++SFML2D / 3D

Read docs →

README.md

Zappy — A Tribute to Zaphod Beeblebrox

A networked multi-player strategy game where teams of autonomous AI agents compete on a tile-based world. The first team to have 6 players reach elevation 8 wins.

Architecture

Three independent programs communicate over TCP sockets. The server is the single source of truth; AI clients and the GUI client both connect to it.

zappy_ai

One process per player. Fully autonomous — navigates, forages, cooperates via broadcasts, triggers incantations.

⟷

zappy_server

Written in Rust (spec: C, C++ or Rust). Single-process, single-thread, uses poll(). The team name GRAPHIC is reserved for the GUI to authenticate.

⟷

zappy_gui

Written in C++ with SFML. Authenticates with GRAPHIC as team name. Passive observer rendering the world in real-time.

Game Rules

The world is Trantor — a zero-relief, toroidal tile map (edges wrap around). Trantorians are pacifists; they forage resources and incant. Each player starts with 10 food (1 260 time units of life). One food unit sustains a player for 126 time units. A player who runs out of food receives dead and is disconnected.

Vision increases with elevation: at level 1, a player sees 1 tile ahead; each elevation adds one line in front and one extra tile on each side. The Look command returns a flat list of tiles ordered front-to-back, left-to-right.

Command	Description	Time	Response
`Forward`	Move one tile ahead	`7/f`	`ok`
`Right`	Turn 90° clockwise	`7/f`	`ok`
`Left`	Turn 90° counter-clockwise	`7/f`	`ok`
`Look`	Observe surrounding tiles	`7/f`	`[tile, ...]`
`Inventory`	List carried resources & food left	`1/f`	`[linemate n, ...]`
`Broadcast text`	Directional message to all players	`7/f`	`ok`
`Connect_nbr`	Query available team slots	`—`	`value`
`Fork`	Lay an egg (new player slot)	`42/f`	`ok`
`Eject`	Push all players off this tile	`7/f`	`ok / ko`
`Take object`	Pick up an object from this tile	`7/f`	`ok / ko`
`Set object`	Drop an object on this tile	`7/f`	`ok / ko`
`Incantation`	Start elevation ritual (group action)	`300/f`	`Elevation underway → level k`

Resources

food×0.5

linemate×0.3

deraumere×0.15

sibur×0.1

mendiane×0.1

phiras×0.08

thystame×0.05

Resources spawn at startup and every 20 time units. Quantity per resource = map_width × map_height × density. On a 10×10 map: 50 food, 5 thystame.

Elevation Requirements

Transition	Players	linemate	deraumere	sibur	mendiane	phiras	thystame
1 → 2	1	1	—	—	—	—	—
2 → 3	2	1	1	1	—	—	—
3 → 4	2	2	—	1	—	2	—
4 → 5	4	1	1	2	—	1	—
5 → 6	4	1	2	1	3	—	—
6 → 7	6	1	2	3	—	1	—
7 → 8	6	2	2	2	2	2	1

Players do not need to be on the same team — only the same level. Incantation is verified at start and end: if conditions fail at either check, elevation fails. Players are frozen during the ritual; stones are consumed on success.

Connection Protocol

When a client connects, the following handshake occurs:

text

Server → Client : WELCOME
Client → Server : TEAM-NAME
Server → Client : CLIENT-NUM    (available slots for this team)
Server → Client : X Y           (world dimensions)

The AI client can pipeline up to 10 commands without waiting for responses. Commands beyond 10 are silently dropped. The GUI authenticates by sending GRAPHIC as team name.

Getting Started

bash

# 1. Build all binaries
make

# 2. Start the server (20×20 map, 2 teams, 5 slots each, 100 ticks/s)
./zappy_server -p 4242 -x 20 -y 20 -n team1 team2 -c 5 -f 100

# 3. Connect the graphical client
./zappy_gui -p 4242 -h localhost

# 4. Launch AI clients (one per player)
./zappy_ai -p 4242 -n team1 -h localhost

-p portTCP port to listen on

-x widthMap width (tiles)

-y heightMap height (tiles)

-n names…Team names (space-separated)

-c clientsMax clients per team

-f freqTime units per second

Victory Condition

The first team to have 6 players simultaneously reach elevation level 8 wins. Achieving this requires gathering the rarest resources across the map and perfectly coordinating a final group incantation ritual.