# BattleBots Arena

> Write a tank bot in one JavaScript file, practise it against built-in bots in the browser, and enter it in a tournament. Everything below works without a human clicking through the UI.

The site is a single-page app: fetching `/` returns an empty shell. Use the URLs below instead.

## 1. Get the starter

- Starter bot: `/starter-bot.js` (`curl -O https://dd-battlebots.pages.dev/starter-bot.js`)
- Its comments are the full bot API: what `act(observation, nav)` sees, what it can return, the map, shooting, and the `nav` pathfinding helpers.
- A bot is one ES module with no imports. It must `export default { apiVersion: 1, bot: { id, name, act(obs, nav) } }`, optionally with `look: { colors: [hull, turret], font }`.
- Bots run in a Web Worker with no network or storage. Each `act` call gets about 50 ms; a call that throws or runs late counts as standing still.

## 2. Practise

Open this in a browser and the round starts as soon as the arena loads:

    /?practice&bot=starter&opponent=orbiter&bots=2&seed=1

| Param | Value |
|---|---|
| `practice` | Required. Opens the practice screen and starts the round |
| `bot` | `starter`, or your bot's source, URL-encoded (`encodeURIComponent`). Repeat for more bots |
| `opponent` | Built-ins that fill the empty slots: `hunter`, `orbiter` or `mix` (default) |
| `bots` | Tanks in the match, 2–50 (default: your bots, at least 2) |
| `seed` | Integer. Same seed and same bots give the same match; omit for a random one |

Params also work in the fragment (`/#practice&bot=...`), which never reaches the server; use it for long sources. Load errors show on the practice screen. When the match ends, a "Battle result" dialog names the winner and lists each bot's kills, damage, HP and errors.

## 3. Enter a tournament

You need the tournament's 6-character code from the organizer. Post the bot file as the request body:

    curl --data-binary @bot.js 'https://dd-battlebots.pages.dev/api/tournaments/CODE/submissions?player=YOUR_NAME'

- `player` (required): who entered it, up to 32 characters.
- `name` (optional): the bot's name, up to 16 characters. Without it, the server reads the first `name: '...'` in the file. It must be unique in the tournament; the unchanged starter's "Starter" is probably taken.
- Returns `201 { id, editToken, name, editLink }`. Keep `editToken` and `editLink`: they are the only way to replace the bot, and they can't be recovered.

Replace the bot until the tournament starts:

    curl -X PUT --data-binary @bot.js -H 'Authorization: Bearer EDIT_TOKEN' 'https://dd-battlebots.pages.dev/api/tournaments/CODE/submissions/ID'

Check a code first with `GET /api/tournaments/CODE`, which returns `{ code, name, started }`.

Limits: 64 KB per file; 10 create/replace requests per IP per 10 minutes (429 with `Retry-After`). 404 means an unknown code (or a wrong id or token), 409 a started tournament or a taken name. Errors are `{ error }` with a readable message.

The server never runs your file, so test it with a practice round before you enter it.