Launching¶

Once the binaries are built (see Installation), Zappy is launched in three steps: first the server, then the GUI, then one or more AIs per team. All the commands below run from the repository root through the wrapper scripts.

Launch order

Always start the server first: it is the one that opens the TCP port. The GUI and the AIs are clients; they fail (exit code 84) if they cannot find a server at the given address.

Launching the server¶

./zappy_server -p <port> -x <width> -y <height> \
               -n <team1> <team2> ... -c <clients> -f <frequency>

Option	Meaning	Default
`-p`	TCP listening port (1..65535)	`4242`
`-x`	Map width (> 0)	`10`
`-y`	Map height (> 0)	`10`
`-n`	List of team names (at least one)	`team1 team2`
`-c`	Number of clients (eggs) allowed per team (> 0)	`3`
`-f`	Frequency: number of time units per second (> 0)	`100`

The -n option consumes every following token that is not a new option; the reserved name GRAPHIC and duplicates are rejected. A configuration error prints a message on standard error and terminates the program with exit code 84.

Meaning of -c

-c sets the number of eggs (hence connection slots) per team at startup. It is also the number of AI clients that may connect to that team before a Fork creates additional slots.

Example:

./zappy_server -p 4242 -x 20 -y 20 -n team1 team2 team3 -c 6 -f 100

Launching the GUI¶

./zappy_gui -h <host> -p <port>

Option	Meaning	Default
`-h`	Server host (address)	none (must be provided)
`-p`	Server TCP port	`4242`

In practice, provide both options. On connection the GUI automatically sends GRAPHIC\n to the server, which replies with the complete initial state of the game (map size, teams, tile contents, players, eggs). A 3D window opens (1280 × 720) and shows the game in real time.

./zappy_gui -h localhost -p 4242

The GUI is passive

The GUI only observes: after GRAPHIC, it sends nothing more and merely displays the events broadcast by the server.

Launching an AI¶

./zappy_ai -p <port> -n <team> -h <host>

Option	Meaning	Default
`-p`	Server TCP port	none (must be provided)
`-n`	Name of the team to join	none (must be provided)
`-h`	Server host	`127.0.0.1`
`--debug`	Enable verbose logging	disabled

Each zappy_ai process controls a single player. To get several players in a team, launch several processes with the same -n. The number of connections per team is bounded by the server's -c (plus the eggs created via Fork).

On connection the AI performs the handshake (see Handshake): it waits for WELCOME, sends the team name, then receives the number of remaining slots and the map dimensions. A connection error terminates the process with exit code 84.

./zappy_ai -p 4242 -n team1 -h localhost

A complete example session¶

The following example sets up a game with 3 teams, the GUI and two AIs per team. Open several terminals (or use & to background processes).

# Terminal 1 — the server (start it first)
./zappy_server -p 4242 -x 20 -y 20 -n team1 team2 team3 -c 6 -f 100

# Terminal 2 — the GUI (spectator)
./zappy_gui -h localhost -p 4242

# Terminal 3..N — two AIs per team
./zappy_ai -p 4242 -n team1 -h localhost
./zappy_ai -p 4242 -n team1 -h localhost
./zappy_ai -p 4242 -n team2 -h localhost
./zappy_ai -p 4242 -n team2 -h localhost
./zappy_ai -p 4242 -n team3 -h localhost
./zappy_ai -p 4242 -n team3 -h localhost

sequenceDiagram
    participant U as You
    participant S as zappy_server
    participant G as zappy_gui
    participant A as zappy_ai

    U->>S: ./zappy_server -p 4242 ...
    Note over S: opens port 4242
    U->>G: ./zappy_gui -h localhost -p 4242
    G->>S: GRAPHIC
    S->>G: initial state
    U->>A: ./zappy_ai -p 4242 -n team1
    A->>S: handshake (WELCOME, team1, ...)
    S->>G: pnw / enw (new player)

Late connections

The server stays available as long as it runs: you can connect new AIs or (re)launch the GUI at any time, within the limit of available team slots.

The SFML launcher (optional)¶

The graphical launcher automates this whole procedure. After building it (make -C launcher), run it:

./launcher/zappy_launcher

The "Mewzappy Launcher" window offers a settings screen (port, width, height, number of clients, frequency, team list — respective defaults 4242, 10, 10, 1, 1). On Launch, the launcher:

first builds the project by invoking the root Makefile (cd .. && make -j) and shows the output;
then launches one zappy_server, one zappy_gui, then one zappy_ai per team and per client, from the entered settings. It calls the root wrapper binaries with the options:
- server: -p -x -y -c -f -n <teams...>
- GUI: -p <port> -h localhost
- AI: -p <port> -n <team> -h localhost
stops all processes (SIGTERM) when you click Stop or close the window.

Why go through the root?

The launcher runs the "bare" binaries (zappy_server, zappy_gui, zappy_ai) from the repository root directory: it relies on the wrapper scripts described in Installation.

Known limitations

Some launch and option behaviours have documented discrepancies. See Known limitations.