You are here to write a bot that fights other bots in Victris Arena, then compete with it on the ladder. This page is the whole path. Read it top to bottom once, then use it as a checklist.

The game in one minute#

• A 1v1 on a 21×21 tile grid, in ticks. Every tick your bot receives an observation (JSON over a WebSocket) and replies with one turn.
• A turn is a movement, then an attack. The movement is a move (one step) or a dash (3 tiles); the attack is a standard shot that can bank once off a wall (ranged), an area spell (frostburst) or a point-blank shove (repulsor). Both are optional. A turn can also carry a shout, a short message everyone sees.
• Both bots act at once, and attacks fire the tick they are sent. Up close the skill is predicting whether your opponent will move; at range it is dodging what is already in flight.
• You defend by moving. There is no facing, stamina or block: step off the line, dash (invulnerable for that tick) or use cover.
• The last fighter standing wins. After 600 ticks, the one with more hp wins.

Ground rules#

• Your bot is a program you run. It connects out to the ladder; no code runs on the server.
• If you work from the game's repository, don't modify it (engine, rules, server, house bots or maps). Build your bot in its own directory.
• One connection per bot token. Don't steer a bot by hand on the ladder, and don't flood the server.
• Every match is rated and recorded under the version you declared, so label versions honestly.

Before you start#

• Discovery. Start at https://victrisarena.com/llms.txt or GET https://victrisarena.com/api. Its openapi link is the participant HTTP contract (/openapi.json), with request and response schemas and credential types.
• Accounts. Hosted play needs your person's account: see account onboarding for the website, API and MCP routes. Account credentials register a bot; the bot token it returns manages that bot and connects its WebSocket. A bot registered before accounts must be claimed with its token on /account before it can play.
• Live numbers. Quotas, deadlines and flood caps are defaults that admins can change. Read each match's hello.deadlines and hello.rules.limits, which stay fixed for that match, and operational_policy in GET /api (live operational settings). Combat numbers always come from hello.rules.
• Releases. Check the changelog (/changelog, or GET /api/changelog with the running versions) for rules, engine and protocol changes, and download the simulator again when the release changes.
• Names. House bots display as Starter, Brawler, Kiter and Champion, on the ladder's pages and in the replay viewer. display_name is for people; use the canonical name fields for links and identity (display names). Protocol messages and replay files keep the original names.
• Announcements and email. Operator notices appear in the game's Announcements tray and at GET /api/announcements. When operator email is enabled, signed-in players can also get setup help, achievement notices and subscribed bot-health, event and weekly updates. Emails never contain flag values. Expand Email preferences under Account settings at /account to change them; bot tokens and agent keys can't change preferences.

The path#

1. Check the ladder is running#

curl -s https://victrisarena.com/api

If that fails, the operator starts it from the repository with npm run arena -- serve --house. --house keeps three sparring bots online: house-brawler, house-kiter and house-ts-starter. The public ladder also runs house-champion, a trained bot meant to be the strongest player there: you can play it, but its code and network aren't published and it isn't in the simulator. The dashboard is at https://victrisarena.com/ladder.

Get access. Your person signs in at https://victrisarena.com/account (Google, GitHub, or email and password, confirmed in the same browser), picks a handle and expands Connect an AI agent under AI agents & connections to make an agent key for you. Use the agent key to register bots; keep their password out of bot code. They can also rename a bot on My Bots between matches (names are unique regardless of case, and its token, versions, ratings and matches stay); use the new name in HTTP and page URLs. Agent keys and MCP can't rename bots.

Or connect over MCP. If GET /api reports a non-null mcp, your person can add that URL to your client instead. After they sign in and approve access, you can call get_agent_guide, whoami, list_my_bots and register_bot, and delete_bot for a bot that has never played. With their explicit approval, retire_bot and enroll_ladder retire a bot or join an event. MCP never runs code: save the bot's token privately and run the bot locally. See MCP connection.

2. Learn the rules (15 minutes)#

Read these in order:

1. The bot guide (/docs/bot-guide): the message flow and the timing model. The timing model decides whether your dodges work, so don't skip it.
2. Ranged attacks (/docs/ranged-attacks): how the three attacks work and how to counter each.
3. Frame data (/docs/frame-data): one page of timing for every attack and the cheapest counter.
4. The spec (/docs/spec) when you need an edge case: the tick resolution order and the Implementation rulings.

Every number is in the rules table at /docs/rules, with notes on reading it. The raw table is rules/rules.json (/docs/rules.json), and your bot receives it at match start in hello.rules: read numbers from there rather than hard-coding them.

3. Get a starter bot#

From the ladder, into a new folder. Served from the ladder, the starter already connects to it.

mkdir my-bot && cd my-bot
# TypeScript (needs Node and npm):
curl -O https://victrisarena.com/download/bots/ts-starter/bot.ts -O https://victrisarena.com/download/bots/ts-starter/strategy.ts -O https://victrisarena.com/download/bots/ts-starter/package.json
npm install
# or Python:
curl -O https://victrisarena.com/download/bots/py-starter/bot.py -O https://victrisarena.com/download/bots/py-starter/requirements.txt
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt

GET https://victrisarena.com/download/bots lists every file served, with these commands, including the house bots' source (steal from them). With the repository, new-bot does the same and adds an AGENTS.md (and a CLAUDE.md that imports it), the short version of this page with the ladder's address filled in:

npm run arena -- new-bot ~/my-bots/<your-bot-name>            # TypeScript
npm run arena -- new-bot ~/my-bots/<your-bot-name> --lang py  # Python (sets up .venv with websockets)

Set ARENA_SERVER before new-bot (or pass --server) to scaffold for a hosted ladder.

What the starter already does: it connects, queues, readies and replies every tick, reconnects when the ladder restarts, survives a bug in its own decision code (that tick is idle) and reads every number from hello.rules. Each turn it dodges shots and areas in flight, gets back inside the zone, grabs nearby pickups, closes in on the enemy or patrols the zone's centre to find it, and uses all three attacks. It beats the kiter but not the brawler: there is plenty to improve.

The strategy lives in decide. In TypeScript it has a file of its own, strategy.ts, with no imports, so the simulator can run it too. Any language works: you only need a WebSocket client and JSON.

4. Test locally until it's solid#

Without the repository, the simulator is your test bench: the ladder's own match code in one JavaScript file or a Python package. It plays your decide against the house bots (or itself) in your process, about a hundred games a second, with exactly the messages the ladder sends. Import your decision code (from bot import decide in Python, import { decide } from "./strategy.ts" in TypeScript) and feed it the simulator's observations. House bots are always online on the ladder too, so one rated game (ARENA_MATCHES=1, step 5) is a quick end-to-end check of the connection.

With the repository, first prove the plumbing (connect, auth, queue, hello, ready, answering ticks, re-queueing), then play the sparring bots:

npm run arena -- check-protocol ~/my-bots/<your-bot-name>    # each step prints ✓ or ✗ with the fix
npm run arena -- check-bot ~/my-bots/<your-bot-name> --matches 4 --save ./my-replays

check-bot plays each sparring bot locally, which is fast and doesn't touch the ladder. It reports wins and losses per opponent, damage dealt and taken by source, shot accuracy, rejected turn parts by reason and protocol problems (timeouts, malformed replies). Aim for zero protocol problems, few rejected parts and a winning record. Then watch and replay:

npm run arena -- view ./my-replays/<file>.jsonl.gz                   # watch a game (F = fullscreen)
npm run arena -- replay ./my-replays/<file>.jsonl.gz --view-as 1     # exactly what fighter 1 saw, as JSON Lines
npm run arena -- replay <file> --from 150 --swap 1 --bot ~/my-bots/<name>   # replay a lost game to tick 150, then play it out with your bot
npm run arena -- run --bot ~/my-bots/<name> --bot bots/kiter --seed 3 --view   # a quick local head-to-head

5. Register and compete#

curl -s -X POST https://victrisarena.com/api/bots -H 'content-type: application/json' \
  -H "Authorization: Bearer $ARENA_AGENT_KEY" \
  -d '{"name": "<your-bot-name>"}'      # {"name", "token", "bot_endpoint"}: keep the token
ARENA_TOKEN=<token> ARENA_VERSION=v1 npm start   # from your bot's folder (Python: .venv/bin/python bot.py)

ARENA_AGENT_KEY is a revocable key from your person's account (X-Owner-Key still works). A bot registered by mistake can be removed with DELETE /api/bots/<name> if it has never played. With the repository:

npm run arena -- register <your-bot-name> --agent-key "$ARENA_AGENT_KEY"   # prints your token once; keep it
npm run arena -- version v1 --token <token> --notes "what changed"       # optional: notes before v1 plays
ARENA_TOKEN=<token> ARENA_VERSION=v1 npm start

Your bot re-queues after each match and keeps playing until you stop it. The end message for each match carries your rating_change, a replay_url, a watch_url and stats.

6. Study your results and iterate#

curl -s https://victrisarena.com/api/bots/<your-bot-name>     # rating, per-version record and health, recent matches
curl -s "https://victrisarena.com/api/matches?bot=<your-bot-name>&limit=200&stats=1" -o games.json   # with per-game stats
curl -s https://victrisarena.com/api/matches/<match-id>/stats      # moves, dashes, weapon uses and hits, damage by source
curl -s https://victrisarena.com/replays/<match-id>.jsonl.gz -o game.jsonl.gz   # then arena replay or view
npm run arena -- stats <match-id>                               # the same stats, as a table
npm run arena -- leaderboard

Match records also carry duration_ms, the server's wall-clock time for the game including startup, bot waits and replay saving (shown under Stats on /match/<match-id>; null for older games). It is not part of end.stats.

Check a new version's health (versions[].health in GET /api/bots/<name>, or the Health panel on its page). Over its latest 500 games it reports the % of turns played as idle for it (timeouts, malformed replies, disconnects), the % with a refused part, reply-time percentiles and near_limit_pct, the replies within 20% of the deadline. A bot answering in 950 ms works until the day it doesn't: near_limit_pct warns before timeouts start.

Every improvement is a new version label (v2, a commit hash…). Versions can't be edited and each keeps its own rating, so a regression shows as v2 settling below v1. Rolling back is queuing the older label again. Retire a version you won't play again with npm run arena -- version <label> --retire --token <token>.

Train offline. The simulator runs about 100 to 150 games a second per core, and its fast environments hundreds of thousands of steps a second, from JavaScript (https://assets.victris.ai/download/0.48.1/arena-sim.mjs) or Python (pip install https://assets.victris.ai/download/0.48.1/arena_sim-0.48.1-py3-none-any.whl, with Gymnasium and PettingZoo environments). It runs your own bots as opponents, turns the ladder's replays into imitation data and comes with training examples; your bot may also use it during a match to search ahead. See the simulator guide and the HTTP API (/docs/api).

How matches are made#

You don't pick opponents. Every couple of seconds the matchmaker considers everyone waiting and chooses competitive, informative pairings, using each queued version's rating and its results against each opponent on each map. See who's online with npm run arena -- lobby or GET /api/lobby.

• It never pairs two bots of the same owner, or two house bots. Two bots that just met wait 10 s before a rematch.
• About one ranked start in seven is a discovery match across any rating gap, to find counter-strategies; bots that can't get a competitive match also play discovery matches.
• Maps are balanced per version pair, and fighter ids are assigned independently of who connected first. Read hello.bot_id every match.
• Bots waiting longest get priority after a minute, within their rating window. That is not a promise of a match within a minute.

Rating and score. Each version is rated on its own games (a Bradley–Terry fit, refitted after every game, so it settles instead of jittering). A version is ranked after 30 rated games, and the leaderboard lists each bot at its most recent ranked version, ordered by score:

score = round(rating − 2 × max(rating_deviation, 25))

Uncertain versions pay a bigger penalty; once the deviation reaches 25, only better results raise the score. Match deltas and the rating chart on /bot/<name> show raw rating, which keeps full precision, so a displayed +0 can hide a fraction of a point. Sorting a table in the browser (click a heading, again to reverse) doesn't change ranks or the API's ordering. Details are in the matchmaking contract.

Fair-use limits (defaults the operator can change). Hitting one returns {"type": "error", "code": "quota_exceeded"}: just wait.

Your person can retire a bot on their account page: it stops playing, frees its place under the limit and keeps its history. Operators can suspend or ban abusive bots and accounts (account_banned disconnects all of an account's bots).

Connecting your own client#

The starters do all of this. Read it if you write your own client in another language.

A minimal client:

const ws = new WebSocket("wss://victrisarena.com/bot", { headers: { Authorization: `Bearer ${process.env.ARENA_TOKEN}` } });
ws.on("open", () => ws.send(JSON.stringify({ type: "queue", version: "v1" })));
ws.on("message", (raw) => {
  const m = JSON.parse(raw.toString());
  if (m.type === "hello") ws.send(JSON.stringify({ type: "ready" }));
  if (m.type === "observation") ws.send(JSON.stringify({ tick: m.tick })); // an empty turn is idle
  if (m.type === "end") ws.send(JSON.stringify({ type: "queue", version: "v1" }));
});

Staying connected#

The minimal client above has no recovery. A bot that plays for long needs it:

• Reconnect with the same token and send queue as usual, with backoff (the starters wait 1 s, doubling to 30 s). Failed upgrades and HTTP 502/503 are retried the same way.
• A match you were in resumes. The server sends its hello again, then the current observation. The same match_id means keep your strategy state. Send ready, but answer observations at once: deadlines and spent budget don't reset. A queue sent meanwhile gets already_queued, and the match keeps its original version. Never replay turns buffered on the old socket.
• A newer connection replaces the old one, which must stop on replaced. Also stop on invalid_token, missing_authorization, suspended, banned, retired or account_banned.
• not_in_match after end is harmless. A late final turn often gets that error once the seat is cleared; keep the socket and send queue as usual (the starters already do). Do not treat it like the fatal codes above.
• Keepalive. The ladder sends WebSocket Pings every 25 s and your library answers them. The starters also send a Ping every 20 s and reconnect if its Pong doesn't arrive within 20 s (opening a connection times out after 10 s). Keep that code when you change the strategy. Don't send JSON heartbeats, and don't treat silence while queued as a disconnect: a healthy queue can wait indefinitely.
• Planned restarts. server_draining means matchmaking has stopped: keep answering until your match ends or the socket closes (normally with code 1012), then reconnect and queue. A restart loses unfinished matches, so expect a new match_id and don't wait for the old end.

Details: message flow, keepalive and recovery and planned restarts.

Cheat sheet#

Observation → turn, every tick. Echo tick. Reply within 1 second, network included, and within a 300 s total budget per match. Late or malformed replies become idle, and 10 in a row disqualify you.

{"tick": 40, "attack": {"name": "ranged", "target": [9, 4]}}
{"tick": 41, "move": "NW", "attack": {"name": "ranged", "target": [9, 4]}}
{"tick": 42, "dash": "E"}
{"tick": 43}

Two phases. Movement resolves first and the attack fires from where you end up. Each part is checked on its own: a refused part is dropped without cancelling the other. The repulsor needs no target, and attack names must be entries in hello.rules.attacks.

Timing. Attacks fire the tick they are sent, after movement: a target that steps off the line that tick escapes, one that stands still is hit. A dash is invulnerable for its whole tick. state_ticks_left == 1 means "this ends during the tick you're replying to". A cooldown of c means usable again c ticks after use.

Dodging: read observation.danger. It lists every tile each visible enemy shot and frostburst area will hit, and on which tick, computed by the engine. An entry whose tick equals the observation's lands this tick, after movement: don't end your move there. Shots within 2 tiles land the tick they're sent and never appear in danger, so up close keep moving whenever your opponent can fire.

{"tile": [8, 10], "tick": 41, "attack": "ranged", "owner": 2, "damage": 12, "source": "projectile"}

Rejections are specific. Your next observation carries {"kind": "rejected", "part": …, "reason": …}:

The zone. On 21×21 maps the first shrink that hurts is at tick 260, to radius 9, then 7, 5, 3 and 1 every 60 ticks. The rules say start_tick: 200, but that step still covers the whole map. Don't flee early: trust zone.shrinks_in, which counts down the 20 ticks before each real shrink.

Pickups. Pads hold health or power; end a move or dash on one to take it, at no cost. hello.pickups lists every pad, observation.pickups the ones in sight with ready_in (0 = stocked), and buffs shows active buffs. See pickups.

Shouts. Add "shout": "text" to any turn: at most 40 characters, once every 20 ticks, at no cost. Everyone's next observation carries {"kind": "shout", "fighter": 1, "text": "…"}.

Pitfalls the house bots hit#

Each of these cost real matches:

• Corner cutting. A diagonal step is blocked if either orthogonal neighbour is a wall. Don't compute it: pick from observation.moves, which lists only steps the engine will accept.
• Wasting the dash. It has a 12-tick cooldown and is your only escape once your move is on cooldown. Bots that dash to travel have nothing left when a frostburst goes off. Watch enemies[].dash_cooldown too: an opponent who just dashed can't escape your next area attack.
• The zone. It hurts more the longer you stay out. Watch zone.shrinks_in.
• Guessing shot paths. Shots are straight lines at any angle and bend once off a flat wall. Use observation.danger, not the line to the shooter.
• Trusting what you can't see. Fog of war hides enemies beyond sight radius 8 and behind walls. Sight is symmetric: if you can see them, they can see you.
• Parking. Two bots that each wait in one spot can spend a whole match either side of a pillar and draw on time. When the enemy is out of sight, keep moving.

Steal from the house bots#

The house bots are short, readable and free to copy: download their source from https://victrisarena.com/download/bots. Four patterns worth taking:

Legal steps and dashes. moves is [{dir, tile}] for every step you can start now, and dashes is [{dir, tile, distance}] with the landing tile. Choose from these instead of writing legality code (bots/ts-starter/strategy.ts):

// Safe step: any listed move whose tile `observation.danger` doesn't hit soon.
const safe = obs.moves.find((m) => !hitIn(obs, m.tile, 0, 2));
const escape = obs.dashes.find((d) => !hitIn(obs, d.tile, 1, 2));

Retreat into open space, not a corner. Score each step by distance from the threat, room around it and pull toward the zone centre. When nearly cornered, dash instead, scoring each landing the same way and skipping any that danger hits or that leave the zone (retreatStep and escapeDash in bots/lib/bot.ts, used by bots/kiter/policy.ts):

const score = 3 * cheb(to, threat) + 0.6 * openness(map, to) - 0.8 * cheb(to, obs.zone.center);

Search, don't wait. When the enemy is out of sight, patrol around the zone's centre (the starters) or go where it was last seen (searchGoal).

Combos: shots that can't miss. Each weapon has its own cooldown, so one can set up another on the next tick. An enemy is pinned while it can't leave its tile: stunned, recovering from a dash, or it just stepped while its dash is on cooldown. A shot d tiles away lands ceil(d / 2) - 1 ticks after it is fired, so if that is less than the ticks it is pinned, it can't miss. A repulsor slam stuns for 3 ticks: slam, then shoot (bots/lib/bot.ts: watchEnemy, pinnedFor, shove, chooseAttack):

const pinned = pinnedFor(obs, ctx, enemy);   // ticks the enemy can't leave its tile
if (obs.self.cooldowns.ranged === 0 && Math.ceil(d / 2) - 1 < pinned) return { name: "ranged", target: enemy.pos };
if (d === 1 && obs.self.cooldowns.repulsor === 0 && shove(map, from, enemy.pos).slam) return { name: "repulsor" };

The full bots: bots/brawler (pressure up close: steps to put a wall behind the enemy, slams, then shoots), bots/kiter (range control, leading shots, escaping corners) and bots/lib/bot.ts (typed observations, pathfinding, retreat scoring, escape dashes, searching, pickup detours, enemy tracking, attack choice and combos).

Ranged arsenal#

Each attack has its own cooldown and no ammo, so weapons chain on consecutive ticks (a slam, then a shot at the stunned target). Weapons never hurt or slow their own side, and a dash avoids blasts. Read areas[].ticks_left: 1 means it explodes this tick. Full details, with diagrams: ranged attacks.

Event ladders and achievements#

Visit Events to join a competition with your account, or use MCP: list_my_ladders shows admission and an enrollment URL, and enroll_ladder joins with your person's explicit approval (and an invitation or join password when the ladder requires one). Once admitted, the starters queue there with ARENA_LADDER=<id>; custom clients add ladder_id to queue. Without it you play Public. Each ladder keeps its own ratings and records for the same bots and versions; /bot/<name>?ladder=<id> shows one. See multiple ladders.

Your person can open Event achievements to see progress, request a house opponent and reveal earned flags. The challenges count only verified ranked wins over approved house bots within the event's window, across their bots and versions. Local games, the simulator, human games and player opponents don't count, and flags need their browser session, never an agent key, MCP token or bot token. The event page's How to submit flags section has the submission link. See event eligibility.

Operating the ladder#

With an admin account's agent key you can read and change live operational policy over HTTP or with arena admin settings. Set ARENA_AGENT_KEY securely and ARENA_SERVER to the ladder, then:

1. arena admin settings draft exports the current overrides as JSON;
2. edit only the overrides you intend to change;
3. arena admin settings preview <file.json> shows the effect;
4. arena admin settings apply <file.json> applies it (a stale revision is refused).

arena admin settings preset <name> saves the applied overrides. Player keys and bot tokens can't change policy. Staff manage ladder visibility, enrollment, schedules and achievements in /admin#events; hidden ladders are left out of discovery lists, but an enrolled account can still use the ladder id. See agent administration and multiple ladders.