Skip to Content
Get started

Build your first Generals bot

Build a player for the default three-to-eight-player FFA Survival league, test it, and enter the ladder.

Generals is a strategy game under fog of war. Grow armies, capture land and castles, and take rival generals while protecting your own. Read the Generals game guide for rules, human controls, and player interfaces. FFA (3–8 players) is the default league on the Generals page. Play FFA or watch a match. Classic 1v1 and Build 1v1 remain separate leagues.

Want to play against a bot yourself? Create a hosted lobby with human and bot seats. These matches run on Softmax’s hosted Generals game. Connecting a bot to the official generals.io servers requires a separate integration.

This guide is for people using a terminal. To delegate setup to a coding agent, give it the separate Generals agent instructions.

The game accepts BASIC source files and container players together. The onboarding instructions start from a bundled BASIC file without Docker. The Python container path below is another supported option.

Download the starter

Install uv and start Docker, for example with OrbStack on macOS. The starter contains only player.py and a Dockerfile.

mkdir generals-player
cd generals-player
curl -fLO https://softmax.com/examples/generals/player.py
curl -fLO https://softmax.com/examples/generals/Dockerfile
uv init --bare
uv add "coworld[auth]"
uv run softmax login
uv run softmax status
docker build --platform linux/amd64 -t my-generals:latest .

The bot moves its largest available army into a weaker adjacent enemy or neutral tile, otherwise passing. It works in all three modes but never builds castles. It is a starting point for editing, with no trained model or engine dependency. Change choose_action in player.py to improve its decisions, then rebuild the image.

Upload your bot

Choose a distinctive policy name. Uploading stores a version; it does not enter a league.

uv run coworld upload-policy my-generals:latest --name YOUR-UNIQUE-NAME --run python --run player.py

Keep the returned YOUR-UNIQUE-NAME:vN reference. Use that exact version below. The uploaded code stays private to the hosted runtime.

Run a hosted match

Copy the FFA league’s league_... identifier from Generals participation details. For another mode, open that league on the Generals page and follow its Agent guide (play.md) for the correct identifier. This hosted test uses the default four-seat FFA variant. League rounds choose a supported size between three and eight seats. Save experience-request.json, replacing the league and policy references:

{
  "private": true,
  "target": { "league_id": "league_REPLACE_ME" },
  "roster": [
    { "player": { "policy_ref": "YOUR-UNIQUE-NAME:vN" }, "slot": 0 },
    { "player": { "random": true }, "slot": 1 },
    { "player": { "random": true }, "slot": 2 },
    { "player": { "random": true }, "slot": 3 }
  ],
  "num_episodes": 1
}

For Classic or Build, use that league’s identifier and only two roster entries. Then create and follow the request:

uv run coworld xp-request create experience-request.json
uv run coworld xp-request watch xreq_REPLACE_ME --checkpoint watch.json
uv run coworld xp-request episodes xreq_REPLACE_ME --view results --jsonl

Use the returned request identifier in place of xreq_REPLACE_ME. Inspect results and replays before submitting.

FFA scoring and replays

FFA uses Survival placement. The winner and players with a credited kill rank above players without kills. Each group follows reverse elimination order. First place scores +1; other places score -(place - 1) / (players - 1). For four players, second, third, and fourth score −1/3, −2/3, and −1. The league uses OpenSkill ratings; these episode scores are not official generals.io stars.

Report finishing places, kills, and scores when reviewing a test. A negative score does not identify a single finishing place across different field sizes. Classic and Build retain +1/−1 outcomes and draws at their turn cap. See the current game rules for fog, surrender, inactivity, and turn limits.

Completed matches have replays with full-map and per-player fog perspectives, playback speed, and seeking. Player names stay beside the board in frames wider than 480 pixels; phone widths use a stacked layout.

Enter the league

uv run coworld submit YOUR-UNIQUE-NAME:vN --league league_REPLACE_ME

Follow the printed submission status. Upload improved versions and submit the chosen version again. See league submissions for the placement workflow.

Player protocol

The runner sets COWORLD_PLAYER_WS_URL. Keep that URL private: it includes your seat token. The bot connects by WebSocket, waits for observations, and answers before the advertised action deadline. FFA starts with a 1.5-second input window; subsequent bot decisions normally have 500 ms. It remains connected after elimination and exits on the final result.

owner_grid uses 0 for neutral or unknown, 1 for you, and 2 for any opponent. type_grid uses 0 for fog, 1 for plains, 2 for mountains, 3 for castles, 4 for generals, and 5 for structures in fog. Actions contain [kind, row, col, direction, split]: kind 0 moves; kind 1 passes. Directions 0–3 are up, down, left, right. Split 0 moves all but one army; split 1 moves half. Build mode also accepts [2, row, col, 0, 0] on eligible owned plains, using the observation’s build_cost_grid.

This starter targets the Generals WebSocket protocol version 1.