Read as Markdown

Ladder API

The ladder (npm run arena -- serve) serves everything on one port, 7777 by default:

Leaderboard, bot detail and admin data tables sort when you click a column heading; click again to reverse direction. The selected order follows refreshed records, including additions and removals. This sorts the loaded browser data; API response ordering is unchanged. Reference and match-stat tables keep their fixed order.

Public HTML guides are at /guide and /guide/<name> (for example, /guide/agents and /guide/api). The web build generates them from the same sources as the Markdown at /docs/<name>. Served repository links resolve to the appropriate ladder endpoint or source file on GitHub. /docs/ranged-attacks also serves the ranged attack guide. The homepage, bot-building guide and release notes include text before JavaScript loads. Rankings, event directories and achievements also include introductory summaries and links to current JSON data. Bot and match pages include their identity, canonical URL and summary in the initial HTML; missing entities return 404 with X-Robots-Tag: noindex. Live tables and account interactions still load in the browser. Public pages include JSON-LD describing the game, website, guides and breadcrumbs. Live rules and frame data still come from the running ladder. Canonical URLs, /sitemap.xml and /robots.txt use the configured public address, or the local ladder address when no public address is set. The sitemap adds ranked public bots and recent public bot matches to the build's page list, so entity discovery does not require JavaScript. Account, consent, admin and standalone viewer pages carry noindex metadata and are omitted from the sitemap.

Every API response is JSON. Errors look like {"error": "..."}, with a 4xx status.

Timestamps remain UTC ISO-8601 instants. Match pages and relative-time tooltips display them in the viewer's browser time zone, with a zone label and UTC available on hover. If the browser cannot resolve or format its zone, the display falls back to UTC.

On the bot WebSocket, an unknown message type is a schema error (an idle turn during a match). Attack names must be entries in hello.rules.attacks; other names are refused as unknown_attack without cancelling movement. Direct shots lock their aim direction after movement, before repulsors resolve. A push shifts the launch point but preserves that direction; the shot still fires with its normal cooldown, even if its shooter lands on the original aim tile.

A connection that inherits an attached match receives that match's hello before observations. During startup it must send ready within the original startup window; during play it receives the current observation immediately, without a new ready wait. The same match_id identifies resumption, with the original version, spent budget and tick deadline. Keep retained client state for that id, or initialize a fresh process from hello. A new connection with the same token replaces the old one, which receives replaced and closes.

A queue during the inherited match returns already_queued and does not change its version. Answer observations until end, then queue again. After a disconnect outside a match, reconnect and queue again. The socket does not resend results missed while offline; use GET /api/matches?bot=<name> to reconcile them by match id.

Planned restarts and recovery

When shutdown begins, the ladder stops starting matches and sends every authenticated connection a notice, including idle and queued bots:

{"type":"server_draining","drain_deadline":"2026-10-10T01:00:00.000Z"}

Connections accepted during draining receive the same notice. drain_deadline is a UTC timestamp: the deadline for waiting on active matches, not a scheduled interruption time or an estimate of when service will return. The server can close earlier if matches finish. It may close immediately when no matches are running. The notice needs no acknowledgement; keep answering active matches with their existing deadlines. Queued bots can stay connected, but no new match starts. /api/status reports draining: true; a queued reply and its wait estimate do not promise a match during that time. Ignore server message types you do not recognise. The notice is ladder-only, outside combat and replay inputs.

After draining (up to serve --drain-timeout, default 600 s), sockets close with code 1012 and reason server restarting. Reconnect with the same bearer token and endpoint; registration and bot versions survive a normal restart, but waiting queues and active simulation state do not. Send queue with your desired version after connecting. The normal sequence is queue → queued → hello → ready → observation, with a new match_id; initialize new strategy state and read the new hello.rules. There is no connection-level hello or session message on /bot: hello arrives when a match is assigned. Do not wait for it before queueing.

This differs from a network drop while the same server process and match remain alive: within the reconnect grace period (10 s by default), that match can resume with its existing hello and current observation. Keep retained state for the same match_id, answer immediately, and do not replay buffered turns. Resuming does not reset deadlines or spent budget.

A drain timeout, second stop signal or crash can abandon an unfinished match without an end message or stored result. Such a match is not restored by the next process. Completed, stored results remain available through the match API; missed end messages are not resent. Do not wait indefinitely for the old match to end before reconnecting and queueing again.

Retry transport failures, opening-handshake timeouts and temporary failed upgrades (including HTTP 502/503) with backoff: the starters wait 1 s, double after unsuccessful attempts and cap the delay at 30 s, continuing until stopped or a fatal error occurs. A 502 alone does not establish a planned restart. Stop on missing_authorization, invalid_token, suspended, banned, retired, account_banned or replaced. A shutdown notice or close frame may be missing during abrupt failures, so recovery must also work without them. Scheduled maintenance estimates, when known, appear in operator announcements at GET /api/announcements; no return-time guarantee is part of the WebSocket protocol.

WebSocket keepalive and recovery

The ladder sends WebSocket Ping control frames every 25 seconds by default, including while bots are idle or queued. Answer each with a Pong carrying the same payload; ws and Python's websockets do this automatically. A socket that has not answered by the next ping check is terminated. The server also answers client Pings. The local match runner answers Pings but does not send periodic ones. These are control frames, separate from JSON messages: there is no application heartbeat message, and sending {"type":"ping"} is a schema error.

An apparently open socket can still have a broken network path. Give the client its own heartbeat and connection timeout rather than relying on readyState, incoming JSON, or the server's eventual close. The reference clients use:

These client settings are recommendations, not match deadlines or protocol requirements. The server's 25 s interval is a ladder default (LadderOptions.pingMs can override it). Configure intermediaries to allow idle periods longer than the heartbeat interval, with room for network and scheduling delays; proxy/NAT timeouts vary, so there is no universal idle timeout to assume. Keep the WebSocket reader and event loop responsive so automatic Pongs and timers can run. Shorter client intervals/deadlines detect failures faster but are more sensitive to latency and pauses.

Signals: server termination may appear as an abnormal close (often code 1006), but a broken path can prevent even that from reaching the client promptly. There is no stale JSON event or guaranteed stale-session close code. A local matching-Pong timeout is sufficient reason to abandon the socket. The TypeScript clients log heartbeat timeout: no pong in 20 s and call terminate() immediately; Python raises a connection error after its heartbeat fails and sets close_timeout=5 (legacy websockets clients can take up to five times this value to close). Both reconnect through their existing close/error path. Opening-handshake timeouts also retry. Retry delays are capped; the bots continue trying until stopped or a fatal error occurs.

Queue silence is normal: after queued, a bot may receive no JSON for an arbitrarily long time because no eligible opponent is available, quotas apply, or the ladder is draining. estimated_wait_s is not a deadline. Do not reconnect or repeatedly send queue merely because no match started. Matching Pongs prove transport responsiveness, not matchmaking or match progress. If Pongs continue but expected match messages stop, log the last message's type, match_id and tick separately from heartbeat activity and investigate that stall.

After a timeout:

1. Abandon the old socket, clear its heartbeat timers and use one reconnect loop. Reconnect with the same token; do not register another bot or rotate the token to recover.
2. Send one queue with your version when the new socket opens. If a match is still attached, expect its hello followed by the current observation; already_queued is harmless here.
3. Preserve retained strategy state for the same match_id, or initialize a fresh process from hello. Send ready, then answer current observations immediately. Do not resend turns buffered on the old socket; deadlines and spent budget are unchanged.
4. Send another queue after end. If the old match already finished, the opening queue asks for a new one; reconcile missed results through the match API.
5. Stop on missing_authorization, invalid_token, suspended, banned, retired, account_banned or replaced. A second process using the same token must not keep fighting the first for ownership.

Saving the current match is not guaranteed. The default 10 s reconnect grace starts when the server detects the disconnect, not when the network first fails. Until then missed turns can count as failures; 10 consecutive failed ticks disqualify. A heartbeat may detect failure too late, the grace may expire, or combat may end the match while the bot is offline. Use hello.deadlines for startup and turn deadlines, not the heartbeat timings.

The small working examples are the connection sections of the TypeScript starter, Python starter and house client. TypeScript matches each Pong to its outstanding Ping and clears timers on close; Python configures ping_interval=20, ping_timeout=20, open_timeout=10 and close_timeout=5 on websockets.connect.

Account onboarding

Participation requires a user account: bot registration and human play both need one. Spectating, docs, downloads and offline simulation stay public. GET /api reports authentication_required, public accounts configuration, mcp, and onboarding links for signup, sign-in, choosing a handle, registering and claiming existing bots. Only an explicit serve --allow-anonymous local development ladder permits anonymous registration and play. Without that option, missing Supabase configuration stops startup.

Choose whichever path fits:

API signup and sign-in

Supabase handles identity and passwords; Arena keeps handles, bots and keys. No service role or operator-issued credential is needed. The following uses curl and jq. Save {"email":"[email protected]","password":"your password"} as credentials.json in a private folder outside your bot repository, with file permissions 600.

ARENA_SERVER=https://arena.victris.ai
CONFIG=$(curl -fsS "$ARENA_SERVER/api")
AUTH_URL=$(printf '%s' "$CONFIG" | jq -r '.accounts.supabase_url')/auth/v1
PUBLISHABLE_KEY=$(printf '%s' "$CONFIG" | jq -r '.accounts.publishable_key')

# Create your user. Open the confirmation email; signup does not bypass confirmation.
curl -fsS "$AUTH_URL/signup?redirect_to=$ARENA_SERVER/account" \
  -H "apikey: $PUBLISHABLE_KEY" -H 'content-type: application/json' \
  --data-binary @credentials.json

# After confirmation, sign in. Store tokens privately (access tokens expire).
umask 077
curl -fsS "$AUTH_URL/token?grant_type=password" \
  -H "apikey: $PUBLISHABLE_KEY" -H 'content-type: application/json' \
  --data-binary @credentials.json > session.json
ARENA_ACCESS_TOKEN=$(jq -r '.access_token' session.json)

# Choose your public identity; an unavailable handle can be retried with another name.
curl -fsS -X PUT "$ARENA_SERVER/api/account/handle" \
  -H "Authorization: Bearer $ARENA_ACCESS_TOKEN" -H 'content-type: application/json' \
  -d '{"handle":"your-handle"}'

# Register manually, or create a key for your agent and use the registration example below.
curl -fsS "$ARENA_SERVER/api/account/keys" \
  -H "Authorization: Bearer $ARENA_ACCESS_TOKEN" -H 'content-type: application/json' \
  -d '{"label":"my coding agent"}' > agent-key.json
ARENA_AGENT_KEY=$(jq -r '.key' agent-key.json)
export ARENA_SERVER ARENA_AGENT_KEY
npm run arena -- register my-bot     # if you have the repository; HTTP works without it

For direct registration, POST /api/bots accepts the same user access token. A missing handle returns handle_required; a missing credential returns authentication_required with account_url. OAuth MCP tokens and bot tokens cannot register through HTTP. Neither an owner field nor a legacy operator owner key proves account identity. The owner always comes from the authenticated account.

Supabase's public Auth API also supplies POST /resend with {"type":"signup","email":"[email protected]"}, POST /recover with {email}, and POST /token?grant_type=refresh_token with {refresh_token}. These need the same apikey and JSON headers. Store the replacement access and refresh tokens from each refresh response. Password reset links return to /account, where the browser chooses a new password. Browser signup/recovery uses PKCE: open its link in the requesting browser. For API signup, confirm the email and then use the password sign-in above. Supabase Auth REST reference describes Auth errors, rate limits and payloads.

Existing bots

A bot without an account cannot play (account_required on /bot). Sign in, choose a handle, then paste its existing token into Claim a bot on /account, or send POST /api/account/claim with {token} using a user access token. Claiming preserves its bot token, versions and match history. House bots and human player seats cannot be claimed. A claimed bot continues using its bot token; it never needs the person's password or JWT in its runtime. House bots are the only accountless hosted participants.

Registering and managing a bot

POST /api/bots

curl -s -X POST https://arena.victris.ai/api/bots -H 'content-type: application/json' \
  -H "Authorization: Bearer $ARENA_AGENT_KEY" \
  -d '{"name": "my-bot"}'

{ "name": "my-bot", "token": "arena_3f…", "bot_endpoint": "wss://arena.victris.ai/bot", "note": "…" }

• Name: 2–24 letters, digits, - or _, unique regardless of case.
• Token: shown once and stored hashed.
• Registration key: if the ladder runs with --registration-key K, send the header X-Registration-Key: K.
• Authentication: send Authorization: Bearer <Supabase user access token or account agent key>. An account agent key is also accepted as X-Owner-Key for existing integrations. Account ownership and quota enforcement are shared with the website and MCP. Legacy operator owner keys work only on explicitly anonymous local ladders.
• Bot limit: at most 5 bots per owner by default (bot_limit). An account's retired bots don't count.

DELETE /api/bots/<name>

curl -s -X DELETE https://arena.victris.ai/api/bots/my-bot -H 'X-Owner-Key: <agent key>'

{ "name": "my-bot", "outcome": "deleted" }

Deletes one of your account's bots that has never played a game, of any kind, such as one registered by mistake: its versions go with it, and its name and its place under the bot limit are free again. A connected bot is closed with invalid_token. Send one of the account's agent keys as X-Owner-Key (invalid_owner_key otherwise; Authorization: Bearer <agent key> also works; operator-issued owner keys can't delete). A bot that has played can't be deleted (409 bot_has_played), because its matches, replays and opponents' ratings depend on it: its owner retires it on the account page instead. Other codes: no_such_bot (404, also for another account's bot), bot_moderated (409: suspended or banned), account_banned. npm run arena -- delete-bot <name> --owner-key <key> does the same.

Authenticated routes (Authorization: Bearer <token>)

Without the header you get 401 with "code": "missing_authorization". With an unknown token you get 401 with "code": "invalid_token".

Accounts (Authorization: Bearer <Supabase access token>)

On a ladder with accounts (GET /api reports its Supabase project in accounts; it's null on a ladder without them), people sign in with email/password, Google or GitHub, through Supabase Auth, on the ladder's account page, /account, and manage their bots there. Email signup requires a confirmation link; Forgot password sends a link to choose a new password. Open either link in the browser that requested it (PKCE). Supabase handles passwords and auth emails; the ladder receives only the sign-in's access token. The page uses these routes, with that token. An account's bots show its handle as their owner, and count against its bot limit (max_bots).

The account response includes boolean email_preferences: onboarding, achievements, bot_health, event_reminders, weekly_digest, admin_warnings. PUT /api/account/notifications accepts a partial email_preferences object alongside or instead of email_announcements; omitted values stay unchanged. Only the signed-in browser account changes its preferences. New optional categories are off for preexisting players; new accounts enable onboarding/achievements.

GET /api/email/unsubscribe?token=<opaque-token> reads the category label only, or returns an invalid/expired-link message with status 200 for the confirmation page. POST opts out without login; invalid/expired tokens return 400. Tokens are authenticated, encrypted and expire after 90 days. GET never changes subscriptions. GET /api/admin/emails returns modes, private submission history and persisted incidents; GET /api/admin/emails/preview?kind=welcome|achievement|admin returns sample branded HTML, text and subject without sending. POST /api/admin/emails/incidents/<scope>/resolve requires a reason and current admin authority; it records an operator resolution without claiming measured recovery or sending a recovery email. scope=* is the global incident. These admin routes return no recipient addresses or flag values. See email setup.

Every account route requires a browser session: OAuth-client JWTs are refused, including ones with the ordinary authenticated audience. MCP JWTs must target the canonical /mcp audience and an approved account/client grant; MCP also accepts an account's agent key as Authorization: Bearer <key>, valid until it is revoked. Discovery is public at /.well-known/oauth-protected-resource/mcp; MCP returns its URL in WWW-Authenticate on a 401. A missing or revoked Arena grant returns 403 mcp_consent_required. Tools are whoami, list_my_bots, register_bot, delete_bot, retire_bot, list_my_ladders, enroll_ladder and get_agent_guide; see MCP.md.

Errors carry a code: missing_authorization and invalid_session (401: sign in again), auth_unavailable (503), handle_required (409: pick a handle first), bot_limit, key_limit, already_claimed (the bot belongs to another account), no_such_bot, bot_has_played, bot_moderated, accounts_disabled (404).

Event achievements

GET /api/events returns definitions for visible ladders: ID, name, description, UTC opens_at/closes_at, display timezone, public metadata (or null), branding image (or null), submission_url (HTTPS or null), submission_instructions (string, empty by default), flag_mode (official or testing), revision, enabled state, phase (upcoming, open, closed), ready, unavailable opponent names, approved opponents and five conditions. It contains no flags or account progress. The player page is /achievements?event=saintcon-2026. An explicit GET /api/events?event=<id> includes that event even when its ladder is hidden, so direct achievement links work. Metadata contains kind (precon, main, community), purpose, audience, format, and preparation; event and ladder enrollment pages display it. Upcoming enabled ladders accept preregistration through the existing account enrollment route while bot queues wait for opening. The October 12–16 precon uses open enrollment and five unofficial testing flags, with no HC submission site. Testing flags use the same private earning and reveal routes, are stable across restarts and require no HC secret configuration. Official events still require their configured secrets; see EVENTS.md.

Private routes require a verified browser Supabase access token in Authorization: Bearer <token>. Bot tokens, agent keys and MCP tokens are refused. Account identity comes exclusively from the token; there is no account selector or staff reveal bypass. Responses, including errors, use Cache-Control: private, no-store and Vary: Authorization. A supplied browser Origin must match the ladder.

Missing/expired credentials return 401; banned accounts, foreign origins and locked/revoked reveals return 403. Unknown events/achievement IDs return 404. Opponent requests return 409 for closed events, offline bots or existing requests, 429 for cooldowns, and 503 if official opponents are unavailable. Reveal returns 503 if delivery is unavailable. Earning stops at closing; earned flags remain revealable when configured. See eligibility and queue policy.

Admin routes use the existing verified admin account authentication:

Reading results

Profiles sum each bot's wins, losses and draws across all its versions on the selected ladder, including retired versions. Owner links on the leaderboard and bot pages keep that ladder selected when opening /user/<handle>.

Match stats

Use the simulator's verifyReplay to check a downloaded replay's tick hashes and combat result. For a forfeit or disqualification, it checks that combat was still running, the ending is at the next unresolved tick, and the winner is a living fighter (or a draw for a forfeit). The server's reason for the external ending remains trusted; combat inputs do not record socket decisions.

Every finished match has stats: the same object arrives in your bot's end message as stats, and the ladder keeps it (even after the replay file is trimmed). The schema is docs/schema/match-stats.json (/docs/schema/match-stats.json).

Match records also keep duration_ms, measured with a monotonic server clock from match setup until the result is ready to persist, including startup, bot waits, simulation and replay saving. Queueing, database persistence and sending the end message are excluded. This field is in GET /api/matches/<id> and match lists, including human and voided games, and appears on /match/<id> under Stats. It is null for older games. It is separate from replay-derived combat stats and is not added to the bot protocol or local replays.

curl -s https://arena.victris.ai/api/matches/<match-id>/stats -o stats.json
curl -s "https://arena.victris.ai/api/matches?bot=<your-bot>&limit=200&stats=1" -o my-games.json
npm run arena -- stats <match-id>          # as a table (--json for the raw object)
npm run arena -- stats replays/x.jsonl.gz  # the same, computed from a local replay

{"match_id": "m_…", "stats_version": 2, "map": "pillars-21", "seed": 3, "ticks": 521, "winner": 2, "reason": "last_standing",
 "fighters": [{"id": 1, "name": "kiter", "version": "v3", "hp": 0, "alive": false,
   "moves": 16, "moves_blocked": 0, "dashes": 4, "dash_tiles": 12,
   "weapons": {"ranged": {"uses": 5, "hits": 2, "damage": 30}, "frostburst": {"uses": 2, "hits": 0, "damage": 0}, "repulsor": {"uses": 0, "hits": 0, "damage": 0}},
   "ricochets": {"bounces": 4, "hits": 1, "damage": 18},
   "pickups": {"health": 0, "power": 3}, "healed": 0,
   "damage_dealt": 30, "dealt_by_source": {"ranged": 30}, "damage_taken": 100, "taken_by_source": {"zone": 100},
   "wall_slams": 0, "knocked_back": 0, "stunned": 0, "zone_ticks": 20,
   "rejected": {"not_visible": 1}, "refused_turns": 1, "refused_turns_by_reason": {"not_visible": 1}, "server_idles": {"timeout": 2},
   "timing": {"replies": 520, "mean_ms": 41, "p50_ms": 18, "p95_ms": 160, "max_ms": 1003, "near_limit": 3,
     "tick_ms": 1000, "budget_ms": 300000, "budget_ms_left": 278680, "histogram": [210, 95, 80, 60, 45, 12, 5, 4, 2, 1, 1, 1, 1, 0, 1, 2]},
   "disconnects": 0, "disqualified": false}, …]}

• fighters[].id is the fighter id: hello.bot_id identifies you, and hello.opponent.bot_id identifies your opponent. Match records map it to bots in bots[].fighter. Stats winner is a fighter id; a match record's winner is a bot id (both use null for a draw).
• weapons lists every attack in the rules. uses counts attacks the engine accepted and fired; hits counts hits on an opponent, so accuracy is hits / uses. Damage includes the power buff.
• ricochets.bounces counts your shots that bounced off a wall; hits and damage are the hits they scored after bouncing (also counted under weapons). Hit events carry "ricochet": true for these.
• moves are steps taken; moves_blocked are steps the engine accepted but another fighter stopped. Dashes are counted separately, with the tiles they covered.
• Damage sources are attack names plus wall_slam, collision and zone.
• rejected counts refused turn parts by reason (as in rejected events); refused_turns counts turns with at least one refused part (and refused_turns_by_reason the same per reason, a turn counting once for each); server_idles counts ticks the server played as idle for you (timeout, malformed_json, disconnected…). Both hold reason codes only: the text of an error (what your bot sent, or what was wrong with it) goes to your bot alone, in the next observation, and is never recorded.
• timing is how long you took to reply, as the server timed it: from sending the observation to your reply arriving, network included. A reply that never came counts at the deadline. near_limit counts replies that took at least 80% of the tick limit: one slow moment from a timeout, so watch it before timeouts show up in server_idles. budget_ms_left is what was left of the match's response-time budget. histogram counts replies per bucket (upper bounds 10, 25, 50, 100, 200, 300, 400, 500, 600, 700, 800, 850, 900, 950 and 1000 thousandths of tick_ms, then slower) so matches add up. timing is null where nothing was timed, as in the simulator.
• disconnects counts contiguous runs of recorded disconnected idle turns for this fighter, not socket-close events. Ten consecutive such turns count as ten server_idles.disconnected and one disconnects. A brief drop with no recorded disconnected turn is not counted, and multiple drops without an intervening other turn form one run. disqualified says the match ended because this fighter failed too many ticks in a row.
• Stats are recomputed from the replay by the engine, so arena stats on a downloaded replay gives the same numbers.

server_idles.timeout means no usable reply arrived before that fighter's turn deadline; server_idles.disconnected means its connection was treated as unavailable. These identify the affected fighter, not which process, network path or server component caused the problem. The wire/replay code is disconnected, not disconnect. An absent key means zero recorded idles for that reason. Counts cover replayed ticks; the unresolved tick at a server-decided forfeit or disqualification is not recorded as another idle turn.

The live protocol sends timeout rejections only to the affected bot and sends no disconnect event to either bot. Final stats expose both fighters' counters. Use end or the saved match record for completion, rather than inferring a result from idle counters or a socket close. Turn timeout is separate from match reasons timeout_hp, timeout_damage and timeout_draw (the combat tick limit). See disconnects, timeouts and match completion for grace-period behavior, resumption and missed-result handling.

Version health

GET /api/bots/<name> gives each version a health summary of its latest 500 matches, counting only matches with current (stats_version 2) stats, or null when none are available. matches and turns report that measured subset; older stats remain stored but do not contribute missing measurements as zero. Check it after deploying a version: it shows what your bot's own logs may not.

"health": {"matches": 500, "turns": 214300,
  "idle_pct": 1.6, "idle_pct_by_reason": {"timeout": 1.4, "schema": 0.2},
  "refused_pct": 3.4, "refused_pct_by_reason": {"not_ready": 3.1, "blocked": 0.4},
  "reply_ms": {"replies": 213000, "mean": 410, "p50": 400, "p95": 900, "max": 1004},
  "near_limit_pct": 6.2, "lowest_budget_ms_left": 120000, "disconnects": 2, "disqualifications": 1}

• Percentages are of turns (one a tick), to two decimals. idle_pct: turns the server played as idle for the version because its reply was late, malformed or missing, and idle_pct_by_reason the same by reason. refused_pct: turns with at least one part the engine refused, and refused_pct_by_reason the same by reason (a turn refused for two reasons counts under each). Reason codes only, never error text.
• reply_ms: reply times over those matches. p50 and p95 come from the summed histograms, so each is the upper bound of its bucket (never above max); mean and max are exact. Null when no match timed a reply.
• near_limit_pct: replies that took at least 80% of the tick limit, as a % of replies. Anything above 0 means the version runs close to timing out.
• lowest_budget_ms_left: the least response-time budget any of the matches ended with.
• disconnects: sum of the match stats' runs of recorded disconnected idle turns; disqualifications: matches lost by failing too many ticks in a row.

The bot's page shows the same, per version, in its Health panel.

Administration (an admin account)

Admins are accounts with the admin role, so the ladder needs accounts (Supabase) to have any. Send Authorization: Bearer with an admin's Supabase access token (the web console at https://arena.victris.ai/admin signs in like /account) or one of the admin's agent keys (as arena admin does, from --agent-key or ARENA_AGENT_KEY): an agent key carries its account's role, so treat an admin's keys as admin credentials. Without a credential the answer is 401 admin_required; an account without the role gets 403 not_admin.

ARENA_ADMINS (comma-separated emails, any case) makes the accounts that sign in with those emails admins whatever their role, so a new ladder has its first admin; only removing an email there takes it away, and that takes effect at once, for the account's agent keys too. The email is Supabase's confirmed one: the ladder keeps it on the account only when ARENA_ADMINS names it, and an admin must have signed in once (as they must to make an agent key). Admins grant and remove the role by handle (or account id), and can ban or delete accounts that aren't admins'. A banned account's account routes, agent keys and MCP answer 403 account_banned, and its bots are disconnected and refused with the same code, on the WebSocket and /api/me; lifting the ban restores all of it. Deleting an account removes it with its handle, agent keys and MCP approvals; its bots are banned (tokens replaced) but keep their names and match history. The same person signing in again gets a new, empty account, so ban rather than delete to keep someone out. The ladder keeps no emails, so accounts are found by handle, bot name or id.

GET /api/announcements is public and returns the latest 100 published, unarchived in-game messages as {id,title,body,published}. Drafts and email-only messages are excluded. Titles are 1–120 characters on one line; bodies are 1–5000 characters of plain text. Choose at least one channel. Preview saves an email audience snapshot of confirmed, non-anonymous, non-banned Supabase accounts, excluding players who opted out and deduplicating addresses. Preview fails without the email credentials when email is true; an in-game-only message works without accounts or email setup. Publish previews within one hour or create a fresh preview.

The in-game tray, admin preview and delivery history make HTTP(S) URLs and [label](https://…) links clickable, opening them in a new tab. For example, See [the rules](https://arena.victris.ai/docs/spec). HTML, other markup, invalid URLs and non-HTTP(S) targets stay text. The API and email text preserve the original body.

Edits use the same title and body validation as new messages and retain the notice's ID and browser read markers. Draft edits keep the saved audience and original one-hour expiry; review the edited draft before publication. Publication freezes the email title and body. Later edits update the notice but neither change queued/retried emails nor resend messages. Admin responses include email_title, email_text and email_html for the frozen published email (or current draft content before publication). The HTML uses the game's email layout, escapes message text and formats only valid HTTP(S) links. Deliveries include HTML and a plain-text alternative; the console renders HTML in a sandboxed preview. Published title and body remain frozen; visual styling comes from the running release. Deletion removes the notice from both public announcements and admin history, including hidden notices and drafts. Email already sent cannot be recalled. Edits and deletions require admin authentication and create audit entries; missing IDs return 404.

Delivery counts are pending, sending, accepted, failed, unknown, and skipped. The server submits one private email at a time, at most one per second, and resumes pending work after restart. accepted means the provider accepted the message, not that it arrived in an inbox. Timeouts, network failures and interrupted sends are unknown and aren't retried automatically; retry only includes definite refusals. Opt-outs are checked again immediately before sending. The player's account API includes email_announcements (true by default); PUT /api/account/notifications with {"email_announcements":false} changes only the signed-in player's preference. Bot tokens and owner keys cannot change it. Browsers poll public notices every 15 seconds and retain read markers locally.

Historical usage

The admin console's Usage dashboard reads GET /api/admin/analytics, using the same admin sign-in or agent-key authentication as the other admin routes. from and to are inclusive UTC calendar dates; defaults cover the last 30 days through today. Invalid dates, reversed ranges, future end dates and more than 366 days return 400. Every day appears, including days with no activity. For example:

curl -H "Authorization: Bearer $ARENA_AGENT_KEY" \
  'https://arena.victris.ai/api/admin/analytics?from=2026-10-01&to=2026-10-10'

The response carries from, to, timezone (UTC), generated, signup_tracking_since, current, summary, daily, top_bots (up to ten player bots) and maps:

• current: users, banned_users, bots, active_bots, suspended_bots, banned_bots, house_bots and all-time completed games. Here active means the bot's moderation status.
• summary: new users, bots, versions; completed games, split into ranked, human and other (legacy modes); voided attempts separately; distinct active_bots and human_players over the range. Here active means participation in a completed game.
• daily: those same fields plus day, with distinct participants per day. Range-wide distinct counts are not sums of daily counts.
• top_bots: name, current owner, games, ranked, human, ordered by game count.
• maps: map, games, ordered by game count.

Games count once on the UTC day they finish, including forfeits; voided matches do not count as completed games or activity. Registrations use their creation day. Player bot/version counts and active bots exclude house bots and human play seats. human_players counts saved human seats, not unique people: anonymous visits create new seats, and signed-in play can reuse one. Users are accounts that visited this ladder, not every Supabase signup or website visitor. Daily signup aggregates survive later deletion without retaining account identifiers. Backfill counts retained accounts; accounts deleted before signup_tracking_since cannot be recovered. Older human seats are identified by anonymous names and saved human games; unused signed-in seats from before the upgrade may remain in bot counts until identified by a human game. Data comes from retained SQLite records and survives replay trimming and restarts.

The console refreshes historical usage every minute (live connections and match capacity every three seconds), supports presets and custom ranges, and exports the displayed daily data as CSV.

Limits

A bot held back by a limit stays queued, and gets {"type": "error", "code": "quota_exceeded", "message": …} (at most once every 5 minutes per reason). Each throttle is written to the audit log.

Replays are the engine's JSON Lines format, gzipped. They're self-contained (rules and map embedded), so npm run arena -- replay <file>, --view-as <id> and --from/--swap all work on them.

Queueing over the WebSocket

After connecting, and again after each end, a bot asks for its next match:

{"type": "queue", "version": "v2"}

The server replies {"type": "queued", "version": "v2", "estimated_wait_s": 0}. {"type": "leave"} takes the bot out of the queue.

• Versions: a label the bot hasn't used before is registered on the spot. It is rated from its own games only, but the matchmaker starts it from the bot's current rating. A retired version can't queue.
• Every game is rated, for the two versions that played it. Ratings are a Bradley-Terry fit to every rated game, refitted after each one: a version's games all count equally, whenever they were played. Each version keeps its own rating and record, so a changed bot's results show on their own and a regression shows as a lower rating. The house bots average 1500 (all but house-champion, which is there to be beaten and floats above the scale). A version is ranked after 30 rated games; the leaderboard lists each bot once, at its ranked version that played last, by leaderboard_score.
• Leaderboard score: round(rating − 2×max(rating_deviation, 25)), using the model's full-precision values before rounding. The 25-point deviation floor applies only to this score: rating_deviation still reports the actual standard error, and rating fits and matchmaking keep using it. Once deviation reaches 25, further uncertainty reduction alone cannot improve the score; stronger results can still improve the rating. Uncertain versions keep the larger penalty, and each new label must still qualify from its own games. The number of games needed to reach the floor depends on the results and opponents.

How pairing works: every couple of seconds the matchmaker considers the whole available queue. It combines competitive quality, waiting time, fewer recent games, settling new versions against established ones, and information from under-tested matchups. Maximum-weight matching chooses the combination of pairs, rather than taking the best individual pair first.

Forecasts start from the same Bradley–Terry matchmaking ratings used for placement. Each version pair's results are smoothed toward that estimate with 20 prior games; its results on each map are then smoothed toward the pair estimate with another 20 prior games. Quality is averaged over a uniform mix of the configured maps, so opposite map-specific blowouts aren't mistaken for an even match. A small recent-opponent penalty discourages repeats without outweighing competitiveness. Human and voided results don't enter matchup forecasts.

Discovery: approximately one in seven ranked starts is reserved for under-tested version pairs across all rating gaps, independently of predicted competitiveness. Coverage is averaged over the configured maps. Early results that contradict the rating prediction get extra testing until the pair has 20 games. When no competitive match can be allocated, compatible bots can also play discovery matches rather than wait for a rating window; those fallback starts are additional to the normal discovery share. Owner exclusions, quotas, capacity and rematch holds apply to all matches. This allows testing for non-transitive strategies such as A > B, B > C, C > A while retaining Bradley–Terry leaderboard ratings.

The competitive rating window starts at 400 points and widens by 20 per second of the shorter wait. At 60 seconds, the oldest eligible bots get priority against their best available opponents, and their own waits widen the window; the gap is capped at 1200 points. An established competitive matchup (at least 20 version-pair games, predicted score 25–75% and average map quality at least 0.5) can pass the initial window, within that cap. Discovery bypasses both competitive rating filters. Waiting cannot override same-owner, house-versus-house, quota, capacity or rematch restrictions. Two bots that just played must both wait 10 seconds before meeting again. There is no opponent-refusal mechanism: skipping ready forfeits a rated game.

For each version pair, the next ranked map is chosen from its least-played configured maps, independently of the expected winner; the match seed breaks ties. Fighter IDs are assigned to reduce each bot's accumulated ranked-seat imbalance, with seeded ties. The engine still randomizes spawn sides. These choices leave combat, protocol and Bradley–Terry ratings unchanged. The operator guide describes decision traces and shadow comparisons.

People playing from /play click a bot that's online; that game starts when the bot next queues, and it isn't rated.

Pacing: a bot starts at most one match every 0.3 seconds (serve --match-interval <seconds> changes this). A bot waiting out its interval stays queued, and the queued reply's estimated_wait_s includes the remaining time.

On the ladder, end also carries watch_url, and rating_change is your version's change from the refit after the game (null when the game wasn't rated). Other versions' ratings move a little with each refit too.

Ratings recorded on matches and rating_change are rounded to whole points; a displayed +0 can hide a fractional change. The fit keeps full precision, so these small changes accumulate. With thousands of games, one new result usually has little influence. Match deltas and historical charts describe the raw rating. Current standings on the leaderboard, Online list and bot version table display Score, which subtracts twice the greater of the standard error and 25. Online shows the connected version; the leaderboard and bot headline show the latest qualifying version, so compare the version labels and selected ladder.

Queue errors arrive as {"type": "error", "code": …}:

• version_retired
• version_limit (more than 1000 new versions in a day)
• quota_exceeded (not fatal: you stay queued)
• already_queued (you're in a match: continue it, then queue after end), not_in_match (a turn with no match running)

Connection errors (the socket closes afterwards):

• missing_authorization: no Authorization: Bearer header on the upgrade request
• invalid_token: no bot has this token
• replaced: a newer connection took over this token; stop this client
• suspended, banned: the operator has suspended or banned this bot
• retired: its owner retired this bot; register a new one to play
• account_banned: an admin has banned the account this bot belongs to
• rate_limited: more than 5 messages in one tick, or more than 50 a second outside a match

Competition ladders

See multiple ladders for participation and operator setup. GET /api/ladders returns visible definitions (visible defaults to true) with phase, leaderboard_url and associated event links. Hidden ladders remain accessible by ID; signed-in account listings include them when the account has a membership. An explicit ?ladder=<id> on /api/ladders or /api/account/ladders also includes that ladder, supporting direct enrollment links (/ladders?ladder=<id>). ?ladder=<id> selects independent ratings/history for /api/leaderboard, /api/matches, /api/lobby, /api/bots/<name> and its /ratings.

Bot objects in rankings, details, matches, lobby entries and event opponents include display_name: Starter, Brawler, Kiter or Champion for official house opponents on any ladder, and the canonical name for player bots. Use name for identifiers, API calls and links. /api/status adds display_name to online entries and display_names in seat order to active matches; rating history adds opponent_display_name with the version suffix. Replay files and WebSocket messages retain canonical names. The replay viewer uses match display_name fields for actions and fighter labels, falling back to the recorded bot names when match metadata is unavailable or a replay is uploaded.

These default to Public; /api/status is aggregate unless scoped. An unknown ladder returns 404. Match responses include ladder_id.

These require an unbanned account, reject foreign origins, and return private, no-store responses. These browser routes reject bot/agent/MCP credentials. Consented MCP clients (OAuth or newly created agent keys) can inspect membership with list_my_ladders and enroll with enroll_ladder after explicit owner approval, through the same admission checks. Existing registration-only credentials require renewed consent or a new key; see MCP.md. Bot tokens cannot enroll. No active enrollment returns enrollment_required for event queues, opponent requests and flag reveals.

Branding image uploads require an admin browser session or admin agent key. A supplied Origin must match the ladder. Images are limited to 5 MiB and 40 million pixels, decoded and resized to fit 1600 × 900 without cropping or enlargement. SVG and animated images are refused. Errors are 400 for invalid images or alternative text, 413 for size, 415 for unsupported MIME types, and 503 for missing or unavailable storage; provider details are not exposed. Rejected uploads keep the existing branding. Public /api/events and associated ladder event summaries include image or null; credentials and internal overrides are absent. Branding changes remain available after the scoring definition freezes.

Flag submission details are public on /achievements and in event API views. Instructions preserve line breaks and format HTTP(S) URLs and [label](https://…) links; HTML and other markup stay plain text. Do not include secret flag values. Submission edits require an admin browser session or admin agent key and are audited without copying the instructions into the audit log.

Ladder settings and event earning switches persist across manifest reloads; admin overrides take precedence. Award counts are unique accounts per event and achievement, with revoked awards counted separately. Staff changes are audited without invitation or flag secrets. Approval cannot bypass a global account ban. Revocation does not erase historical standings or awards.

WebSocket queue adds optional ladder_id; omission selects public. queued and ladder end identify the ladder. One bot queues in one scope at a time; switch after completing a match. Ratings start independently in each scope; new version seeds use only prior ratings from that ladder. Global quotas still apply. Event matches ending outside the window or after an enrollment change remain recorded but are unrated. Human matches use Public.

Live operational settings

Admins edit policy at /admin#settings, using their Supabase session or an admin account's agent key:

• GET /api/admin/settings: effective values, bundled and deployment defaults, field bounds and application timing, per-ladder capacity, the latest 50 revisions and saved presets.
• POST /api/admin/settings/preview: validate {revision, overrides, ladders} and return the old/new values, application timing and number of existing replay files the next cleanup would remove. This changes nothing.
• PUT /api/admin/settings: validate and atomically persist the same complete snapshot, audit it, and activate it. A stale revision returns 409 settings_conflict; invalid values or unknown fields/ladders return 400 invalid_settings.
• POST /api/admin/settings/presets: {revision, name} saves the currently applied overrides (up to 50 named presets). Loading a preset or history revision in the editor requires review and application before activation.

overrides contains only changed global operational fields; omitted fields inherit deployment defaults. ladders maps ladder IDs to optional max_concurrent and owner_concurrency overrides. Empty objects reset everything to deployment defaults. Resets do not clear quota history or remove existing bots/keys. The smaller global/ladder capacity applies. Lower capacity lets active matches finish; lower retention permanently deletes older replay files at the next cleanup, preserving match records and stats.

For example, after reading the current revision, review and apply this complete override snapshot (it resets other overrides):

{"revision": 0, "overrides": {"tick_ms": 1500, "maxBotsPerOwner": 8}, "ladders": {"public": {"max_concurrent": 100, "owner_concurrency": 20}}}

GET https://arena.victris.ai/api publishes operational_policy with current bot match limits, ladder limits and message caps. Match hello and replay rules embed the actual match limits, including the derived human response budget; reconnect hello retains that snapshot. Startup configuration and the shipped rules remain defaults. Match deadlines and per-tick flood limits change only for new matches; ticket/invitation expiry changes affect new issues, and WebSocket message size affects new connections. Scheduler, cleanup and ping timers are rescheduled live. Changing discovery allocation resets its scheduling credit.

Agents changing operational settings

An agent can use every settings endpoint with Authorization: Bearer <admin-agent-key>; no browser session is needed. The key must belong to an admin account. Player agent keys and bot tokens cannot administer settings. Revoking the key or removing its account's admin role immediately removes this access. Bot-authoring MCP tools continue to use their documented player scope; use the HTTP API or CLI for settings administration.

The CLI uses ARENA_AGENT_KEY (or --agent-key) and ARENA_SERVER (or --server). With an admin key already configured securely:

npm run --silent arena -- admin settings                    # values, bounds, defaults, history and presets
npm run --silent arena -- admin settings draft > settings.json
# Edit only the desired overrides or ladder capacities in settings.json.
npm run --silent arena -- admin settings preview settings.json
npm run --silent arena -- admin settings apply settings.json
npm run --silent arena -- admin settings preset "Experiment A"

The draft contains the current revision, existing global overrides, and per-ladder override map, so a small edit preserves other settings. Preview returns changes and retention impact without mutation. Apply validates/previews that exact file before submitting it and rejects a stale revision; it never silently refreshes a stale draft. Inspect changed settings and export a fresh draft before retrying a conflict. To restore a saved preset or history revision, use its overrides and ladders with the freshly read current revision, then preview and apply.

Benchmark clients

npm run benchmark drives these same HTTP/WebSocket routes using reusable test accounts and bot tokens. See Benchmarking the ladder for isolated ladder setup, participant provisioning, workload profiles and capacity evidence. It adds no server endpoints and changes no quotas automatically.

Server health

GET /api/admin/health powers /admin#health, which refreshes every five seconds. It uses the same admin session or agent-key authentication as the other admin routes and returns Cache-Control: private, no-store. Collection is always enabled, in bounded in-memory one-second buckets; restarting resets it. The rolling window covers the latest 300 second buckets, including the current bucket. No bot names, tokens, inputs or replay contents are collected.

The response contains generated, uptime_seconds, window_seconds (300), observed_seconds (up to 300), current tick_ms, and capacity: {running,max}. timings has these operations, each with count, mean_ms, p50_ms, p95_ms, p99_ms, max_ms and over_budget. Durations are null when there are no samples; percentiles use logarithmic histograms with 5% bucket width above 0.001 ms, while means and maxima are exact.

turns: {valid,invalid,timeouts,disconnected} counts settled pending turns; disconnected excludes ticks skipped while already offline. Timeout rate is timeouts / (valid + invalid + timeouts), undefined when there are no attempts. sends: {total,backpressured,max_buffered_bytes} counts observations with an active turn deadline and how often the socket still had buffered bytes after sending. Buffering does not establish delivery latency. Match aggregates cover all ladders and house bots, excluding human games. capacity includes all live matches.

games describes non-voided bot games with at least one resolved tick that finished in the window. It contains count, mean_turns, mean_moves, mean_dashes, mean_duration_ms, max_duration_ms and ms_per_turn. Means are per completed game, with each game weighted equally; ms_per_turn is total game duration divided by total resolved ticks. A turn is one simulation tick, in which both bots can act. Moves are successful one-tile steps across both fighters; blocked steps and dashes are excluded, and dashes are averaged separately. Duration uses a monotonic clock from match setup until the result is ready to persist, matching the saved duration_ms: it includes startup, bot waits, simulation, replay generation/compression, replay writes and rating updates, but not database persistence, queueing or network delivery of the end message. Human games, voided games, startup forfeits and failed result saves do not enter these aggregates. Games are attributed to their completion bucket even when they started before the window. An empty window has count zero and null means, maximum duration and per-turn duration.

High event-loop delay, observation preparation time, simulation time or timeout lateness can reveal server stalls. Bot timeouts alone do not identify the cause; compare them with these server metrics and queued socket writes. For deeper investigation, enable the separate profiler described below.

Admin profiling

Server diagnostics are opt-in (serve --profiling or ARENA_PROFILING=1), disabled by default. All routes below require a current admin account session or agent key; player keys and bot tokens are refused. Responses are private and no-store.

Disabled diagnostics or an overlapping capture return 409; invalid capture requests return 400. The server retains ten managed CPU profile files under <data>/profiles; metadata is process-local. No inspector network port or arbitrary inspector command endpoint is exposed. Labels are normalized and SQL, bot inputs and credentials aren't recorded. CPU profiles contain function names/source paths. Metrics cover the whole server process, not just a selected ladder. See server profiling for stage deltas, flamegraphs, operation semantics and measurement overhead.