Documentation Index
Fetch the complete documentation index at: https://docs.battlecode.cam/llms.txt
Use this file to discover all available pages before exploring further.
The cambc CLI is your main tool for local development, testing, and interacting with the platform. Install it with pip install cambc.
Project setup
cambc starter
Scaffold a new Cambridge Battlecode project. Run this first after installing.
Creates the following project structure:
your-project/
├── cambc.toml # Project configuration
├── .gitignore # Ignores replays, __pycache__, venvs
├── bots/
│ └── starter/
│ └── main.py # Starter bot (optional, prompted)
└── maps/ # Custom maps (optional, prompted)
cambc.toml
The config file created by cambc starter. All fields have defaults and all CLI options override config values.
bots_dir = "bots" # Where to find bots
maps_dir = "maps" # Where to find maps
replay = "replay.replay26" # Default replay output path
seed = 1 # Default map seed
cambc run are resolved by first checking the raw path, then checking inside bots_dir. So cambc run starter opponent resolves to bots/starter and bots/opponent.
Local development
cambc run
Run a local match between two bots. No time limits are enforced locally.
cambc run <bot_a> <bot_b> [map]
| Argument | Description |
|---|
bot_a | First bot — a directory containing main.py, a .py file, or a name in bots_dir |
bot_b | Second bot — same formats as bot_a |
map | Optional .map26 map file. If omitted, uses the first map in maps_dir |
| Option | Description |
|---|
--replay PATH | Output replay file path (overrides cambc.toml default) |
--seed N | Map seed (overrides cambc.toml default) |
--watch | Open the visualiser automatically after the match |
--tle N | Turn time limit in milliseconds (0 to disable, server uses 2) |
--map-random | Pick a random map from the maps directory instead of the first one |
cambc run starter starter # bot vs itself
cambc run my_bot opponent --seed 42 # fixed seed
cambc run my_bot opponent maps/custom.map26 # custom map
cambc run --watch my_bot opponent # run + auto-open visualiser
cambc run my_bot opponent --replay out.replay26 # custom replay path
cambc run prints a summary showing the winner, win condition, turn count, and a resource breakdown (titanium, axionite, units, and buildings) for each team.
cambc watch
View a replay in the browser-based visualiser.
cambc watch [replay_file]
cambc watch --match <match_id> [--game <n>]
localhost and opens your browser. Press Ctrl+C to stop the server.
cambc watch replay.replay26
cambc watch --match abc123 # opens match on platform
cambc watch --match abc123 --game 3 # specific game within the match
cambc map-editor
Open the map editor to create custom .map26 files.
cambc map-editor # local map editor
cambc map-editor --platform # open map editor on the platform
cambc login.
cambc login
Authenticate with the platform. Opens a browser window for OAuth login and stores your session locally.
The session persists across CLI invocations until it expires or you run cambc logout.
cambc logout
Clear stored credentials.
cambc submit
Upload a bot to compete on the ladder.
The path can be a directory containing main.py, a single .py file, or a .zip. Directories are auto-zipped before upload. See submission requirements for constraints.
cambc submit ./my_bot/ # directory (auto-zipped)
cambc submit my_bot.py # single file
cambc submit my_bot.zip # pre-zipped
cambc status
Show your current team, rating, rank, and member list.
Displays your username, team name, category, Elo rating, matches played, and team members with roles.
cambc match
The cambc match group provides all match-related commands. When called with just a match ID, it defaults to showing match details.
cambc match info
View details of a specific match including per-game results.
cambc match info <match_id>
cambc match <match_id> # shorthand — defaults to info
cambc match list
View recent match history.
cambc match list [options]
| Option | Description |
|---|
--type {ladder|unrated} | Filter by match type |
--team NAME | Filter by team name or ID |
--mine | Show only your team’s matches |
--limit N | Number of matches to show (default 20, max 100) |
--cursor CURSOR | Pagination cursor from previous results |
cambc match unrated
Challenge another team to an unrated match.
cambc match unrated <opponent_team_id>
cambc match unrated <opponent_team_id> --match <source_match_id>
cambc match unrated <opponent_team_id> --map arena --map galaxy
| Option | Description |
|---|
--match ID | Use the opponent’s submission version from a specific past match instead of their latest |
--map NAME | Map name (repeatable, up to 5). If omitted, 5 random maps are used |
Rate limits apply: max 10 test/unrated matches per 10 minutes.
cambc match test
Upload two local bots and run a remote match with full time limit enforcement on AWS Graviton3 hardware.
cambc match test <bot_a> <bot_b> [maps...]
cambc run, this enforces the 2ms CPU time limit per round — use this to check your bot’s performance before submitting. You can optionally specify .map26 files — one per game.
cambc match test my_bot opponent # test two bots remotely
cambc match test my_bot opponent maps/arena.map26 # with a specific map
cambc match replay
Download replay files for a completed match.
cambc match replay <match_id> # download all 5 game replays
cambc match replay <match_id> --game 3 # download a specific game
cambc match replay <match_id> -o out.replay26 # custom output path
cambc match watch
Open a match replay in the browser.
cambc match watch <match_id>
cambc match watch <match_id> --game 3
cambc match tests
View your team’s remote test run history.
cambc match tests [--limit N]
cambc team
Search for teams or view team details.
cambc team search <query> # search by name
cambc team info <team_id> # view team details
