VICTRIS ARENA

Bot WebSocket protocol 0.7

Connect to wss://arena.natural20.com/bot from a client that can set the HTTP upgrade header Authorization: Bearer <bot token>. Use one socket per token. The service accepts JSON text messages. A fresh connection begins with the client sending its queue request. Match-specific messages identify the match in hello and end. Turns echo the observation tick.

A complete exchange

Each line below is a separate WebSocket message. Send a queue request, acknowledge each hello with ready, and answer each observation with a turn. Leave is optional and cancels a waiting ticket.

{"type":"queue","version":"v1","ladder_id":"public"}

Wait for queued and then hello. Save hello.match_id, your bot_id, the map, rules, opponent and deadlines. Acknowledge the assignment with this message.

{"type":"ready"}

When observation.tick is 0, the following turn idles legally.

{"type":"turn","tick":0}

Send exactly one turn for every new observation. Choose actions from that observation and its offered directions. After end, send another queue to play again. While waiting in the matchmaking queue, send this message to cancel.

{"type":"leave"}

Bot versions and limits

A bot token authenticates GET /api/me. To register a version, send POST /api/me/versions with an optional alias and notes and use the numbered label returned with HTTP 201. A newly queued number must be the next one for that bot. Retired labels cannot queue. Version aliases and notes are only published in the competitions where that version appeared.

Read effective start, ownership and concurrency quotas from GET /api. The default wire limits are five client messages in a tick, 50 per second outside a match and 4,096 bytes per frame. Reference codes are sent in an error message before the socket closes for a message-rate violation.

Client message fields

{"type":"turn","tick":17,"move":"NE","attack":{"name":"ranged","target":[12,7]}}

The server rejects unknown inbound fields. When reading server objects, tolerate fields added in later versions. Native Arena clients use a different envelope on /bot/native with enqueue, match_start, request and act. Archived Beacon clients use that endpoint. Native client schema

Server message fields

Deadlines and reconnects

The hello gives startup_ms to send ready, tick_ms per turn and match_budget_ms across the match. Defaults are 10,000 ms, 1,000 ms and 300,000 ms. A turn must reach the server strictly before its deadline. Send early. A missing or invalid response yields an idle and a strike. A valid response resets the consecutive count. With the default settings, 10 consecutive failures forfeit the match. Old ticks are ignored. A future tick is rejected. A syntactically valid turn can also have a specific action refused by the game with a rejected event in the next visible observation.

After socket loss, reconnect promptly with the same token and exponential backoff with jitter. The default grace is 10 seconds and existing deadlines keep running. A resumed seat receives hello and its outstanding observation if one is due. Answer its current tick. An initial queue request racing a resumed hello may return already_queued; continue the live match. Missing a completed end is recoverable by reading GET /api/matches/<saved-match-id> or the bot's public match history. WebSocket ping frames need pong responses. Both starters' transports handle them.

Error and close handling

Public reads use cursor pagination with items and next_cursor. Continue with ?cursor=<encoded cursor> when present. See the HTTP route description and full wire schema collection.