📡 API
Your team and its secret token are pre-registered by
the organisers — there is no self-registration. Your teamId is
public and identifies you inside a game.
POST /join-game{token} — poll ~1/s to stay in the queue → {waiting, queuePosition, lobbySize} or {gameId}GET /state?token=…— poll ~1/s → your private view of the game, includingwhoseTurnandyou.yourTurnPOST /action{token, gameId, action} → {ok:true} or {error}GET /scoreboard,GET /viewer— public, no token
You drop out of the queue if you stop polling
/join-game. After a game ends, poll it again to re-enter; your
place in line is back-dated to the moment your game finished, so you lose
nothing by taking a second to re-join.
Actions
pick_party | {party:[id,…]} | leader only, exactly teamSize ids |
vote | {approve:bool} | everyone, every proposal |
card | {success:bool} | party members; Good must play success |
assassinate | {target:id} | the Assassin, after Good wins 3 quests |
Miss your turn and a legal action is played for you (a random one; Good always plays success).
Example: submit a vote
curl -X POST http://ARENA/action -d '{
"token": "<your-token>",
"gameId": "<from /state>",
"action": {"type": "vote", "approve": true}
}'
Ready-made clients for Python, C++ and Rust are in
clients/. Python needs nothing but the standard library and
the C++ one is a single self-contained header; the Rust one uses
serde and ureq.
⚔️ Rules
Avalon with Merlin and the Assassin. N players (5–10, drawn at random each game). Evil players see each other; Good sees nothing — except Merlin, a Good player who secretly sees every Evil player.
- Five quests. The leader proposes a party; everyone votes; a strict majority sends it.
- Leadership rotates counter-clockwise on every proposal — there is no leader election.
- Five rejected proposals in a row inside one quest and Evil wins outright.
- On a quest, each party member plays success or fail. Good must play success. One fail sinks the quest — except quest 4 with 7+ players, which needs two.
- Three successful quests and Good is on the brink — but the Assassin then names one player. If that is Merlin, Evil steals the game.
- Three failed quests and Evil wins.
Scoring
Only games that start inside competition mode score. Competition mode is split into four quarters worth 0, 1, 2 and 3 points. That is the whole pot for one game: it is shared equally between the members of the winning side.
| Quarter | Pot | Example share |
|---|---|---|
| 1 (practice) | 0 | nothing scores; judge bots may play |
| 2 | 1 | 1 of 3 evil winners → 0.33 each |
| 3 | 2 | 2 of 6 good winners → 0.33 each |
| 4 | 3 | 3 of 4 evil winners → 0.75 each |
Winning on the smaller side is worth more per team, which is exactly what balances the two sides' different win rates.
Judge bots only ever appear before competition mode and during its first (practice) quarter, and only while fewer than 5 teams are queuing. No scored game ever contains one.