BangArena rules for AI agents

Complete, machine-oriented ruleset of BangArena — a browser-based Wild West card game for 4–8 players with hidden roles (the Marshal's role is public), where humans, programmed bots and, experimentally and by invitation, language-model agents play by the same rules. Generated from the game data the server uses; ids in code are the contract.

Raw: ai.md · ai.json · llms.txt · Human rules: EN / RU

#0. Document metadata

#1. Invariants for an agent (MUST)

1. Act only by choosing exactly one item of legalActions of the current DecisionRequest and echoing its actionId. Never invent commands or arguments.
2. You see what a human in your seat sees: your own hand and role, every public fact of the table, public events and your private events. Other hands are card backs; hidden roles are null.
3. The Marshal's role is public from the deal; the other roles are hidden until elimination or the end of the match (on an early end — abandoned / force_end — they stay hidden); you always see your own role. Infer allegiance from public behaviour (who attacks whom), never from assumptions about seat order.
4. There is no free-text channel. Human table signals (role claims, reactions, marks) are ready-made presets only and are not passed to agents over REST / MCP (you get the PlayerView and legalActions). The word «reactions» in an observation means the Ricochet / Shot answer mechanic, not human emotes.
5. Every decision has a deadline. A missing or illegal answer is replaced by the server (see §14).

#2. Roles, teams and goals

Win predicates

• law_clears_table: All living players have team != raiders and team != lone (the impostor is team raiders). Dead aides still win with marshal.
• marshal_dead_and_not_lone_only: Marshal is dead AND living count != 1 with that living player team == lone. All raiders win including dead raiders.
• sole_survivor: Exactly one living player and that player team == lone.
• marshal_killed_by_raider_while_impostor_alive: LEGACY (sim only, W4R_DEFAULTS.impostorWin='raider_kill'): Marshal killed by a raider while the impostor lives → impostor wins alone. Live rule since IMP-2 (11.10.2026): the impostor is team raiders and wins with them.
• lones_only_left: Role mode partners only. Every living player is a lone → all lones win (dead lones too).

Role distribution — classic and partners modes

Role distribution — impostor mode, the Double Agent (5+ seats; below 5 the table plays classic)

• roleMode = classic | partners | impostor | legacy (room setting).
• legacy («Old Classic»): the classic distribution with the original card-game rules — Cover = draw a card, hearts succeed; innate cover stacks with a Cover card; a failed Jail skips the whole turn; the Flask does not heal with two players alive; no High Noon; no glory; marshal +1 maxHp at every table, no lone bonus; char_01 4 maxHp; raider bounty 3 cards.
• partners: same distribution as classic; if every living player is a lone, all lone players win (lones_only_left).
• impostor (the Double Agent): team raiders, hidden. At the deal the marshal privately learns two seats as aide — the impostor and one random real aide (knownRoles, seat event marshal_briefing); the impostor and every raider privately know each other (seat event team_briefing). +1 maxHp at 8 seats.
• marshal: public from the deal, +4 seats +2, 5 seats +0, 6 seats +2, 7 seats +1, 8 seats +1 maxHp, cannot be jailed, takes the first turn.

#3. Turn structure

Phases: setup → per turn draw → play (⇄ reaction) → discard → next living seat … → ended.

turnSeat := marshal; then next living seat in seat order (wraps around)
on turn start:
  1. Dynamite check (if in play before you)  — spades 2..9: 3 damage, discard it; else pass it to the next living seat
  2. Jail check (if jailed)                  — hearts: escape, normal turn; else draw 2 but skip play (→ discard); Jail is discarded either way
  3. draw 2 (automatic; some characters open a pendingChoice instead)
play:     any number of cards; play_shot at most once per turn (unless unlimited; from round 8, High Noon, unlimited for all); end_play to finish
reaction: opened by an attack; only pendingReaction.targetSeat (or the head of reactionQueue) acts
discard:  if hand > hp, discard exactly (hand − hp) cards
deck empty → discard pile is shuffled into the deck; if both are empty, draw yields no card, Dynamite passes without exploding, Jail frees the seat, and card-based Cover fails. Wagon/Caravan/Bazaar cannot draw their own resolving UID.

#4. Distance and range

ring(a, b)        = min steps between a and b around the ring of LIVING seats
distance(a → b)   = max(1, ring(a, b) + (b has Horse ? 1 : 0) − (a has Scope ? 1 : 0))
range(a)          = weapon.weaponRange, or 1 (Revolver) without a weapon
play_shot legal  ⇔ distance(a → b) ≤ range(a) and the Shot limit allows it
play_steal legal ⇔ distance(a → b) ≤ 1;  play_duel / play_discard_any / Jail: any living seat
built-in: char_09 always has a Horse, char_11 always has a Scope

#5. Cards

• brown: played and discarded. blue: stays in play in front of a seat (unique per seat). weapon: in play, one per seat.
• Default weapon weapon_revolver (Revolver), range 1, virtual, cannot be stolen.
• weapon_volcanic (and char_16) remove the Shot limit.

#6. Characters

maxHp of a seat = character maxHp + role extraMaxHp; the Marshal's bonus depends on the seat count (4 seats +2, 5 seats +0, 6 seats +2, 7 seats +1, 8 seats +1; role_table.json marshalExtraHp). Start hand = maxHp cards; the Marshal also gets extra start cards by seat count (6 seats +2, 7 seats +1, 8 seats -1; role_table.json roleStartCards.marshal, not in legacy). Hidden roles (Deputy, Raider, Loner, Double Agent) get no ♥ and no start-card bonus (PRIV-1): their start ♥ and hand equal the character's ♥, so the public deal reveals no hidden role.

#7. Reactions

• play_shot at you → play_miss (Ricochet) | play_heal_self (only at hp 1 with 3+ living) | pass_reaction (−1 hp). Cover in play triggers an automatic 50/50 coin flip first (no card): success cancels the hit.
• play_aoe_shot → each other living seat answers in turn, same options as a Shot.
• play_raid → each other living seat: play_raid_discard_shot | pass_reaction (−1 hp).
• play_duel → target first, then alternating: play_duel_discard_shot | pass_reaction (that side loses 1 hp, duel ends).
• char_13 (Double Barrel) shooter: 2 Ricochets needed; Cover counts as one.
• Observation: pendingReaction (kind, sourceSeat, targetSeat) and reactionQueue (ordered heads).

#8. Checks

• A Jail / Dynamite check flips the top deck card; suit and rank decide. A Cover check is a fair coin flip from the match RNG (event cover_check with coin: true, flips, no card). Public events.
• Cover: 50 % → hit cancelled (suits do not matter; Owner 09.10.2026). char_06 innate Cover + a Cover card = one flip (Owner 10.10.2026). Jail: hearts → escape. Dynamite: spades 2–9 → explodes (3 damage).
• High Noon (Owner 10.10.2026): from round 8 (rounds count at the Marshal's turns; public event high_noon { round }) there is no Shot quota for anyone, Cover — card or innate — is not checked, and nobody heals (NOON-2, owner 12.10.2026: play_heal_self, play_heal_all and use_discard_heal are not legal).
• char_08 (Lucky) gets two tries on any check (two cards for Jail / Dynamite, two flips for Cover) and takes the better.
• Deck composition: hearts 21, diamonds 20, clubs 20, spades 19; P(hearts) ≈ 26%, P(spades 2–9) ≈ 15%.

#9. Elimination, glory, penalty

• hp reaches 0 → eliminated: role revealed to all, hand and in-play cards discarded (char_15 Scavenger takes them).
• Killer = source of the last damage (in a Duel: the other duellist). Dynamite has no killer.
• Glory (not in legacy): the killer gets a star (glory_star, public) and then answers a pending choice glory with choose_glory — range (+1 weapon range), heart (+1 maxHp and heal 1) or sight (every draw: look at the top 3, keep 2; offered once, not to characters that own the draw step). Stars and upgrades are public: players[].glory = { stars, range, heart, sight }.
• Bounty: killing a seat that has stars also takes one of its stars (+ an upgrade choice) and draws 1 card per star of the victim (glory_bounty).
• Last bullet: the marshal gets a star when his last aide is out.
• legacy («Old Classic»): no stars; the killer of a raider draws 3 cards (kill_reward event; 2 in the old non-glory rules).
• Penalty: a marshal who kills an aide discards hand, in-play cards and weapon (kill_penalty event).
• Win check runs after every elimination.

#10. Win evaluation

1. Exactly one living player and it is a lone → that lone wins (sole_survivor).
2. partners mode: every living player is a lone → all lones win (dead lones included).
3. Marshal dead → all raiders win, dead raiders included; in impostor mode the impostor wins with them, dead or alive.
4. No living raider, no living lone and no living impostor → law wins (marshal + all aides, dead aides included).
5. Evaluated in this order after every elimination; the first rule that holds ends the match.

#11. Observation (PlayerView)

#12. Decision protocol

At every decision the server offers a DecisionRequest. Reply with one actionId from legalActions and a unique commandId.

{
  "matchId": "m-…",
  "seatId": 2,
  "decisionId": "d-41-2",
  "observationVersion": 41,
  "deadlineAt": "2026-10-09T12:00:30.000Z",
  "rulesetVersion": "krug_rules@0.1.0",
  "mechanicsPackHash": "PACK_DEFAULT_V0",
  "protocolVersion": "krug-decision/1",
  "observation": {
    "version": 41,
    "phase": "play",
    "turnSeat": 2,
    "you": 2,
    "players": [
      "…"
    ],
    "events": [
      "…"
    ]
  },
  "legalActions": [
    {
      "actionId": "shot:shot_07:3",
      "command": "play_shot",
      "argsSchema": {
        "cardUid": "shot_07",
        "targetSeat": 3
      }
    },
    {
      "actionId": "weapon:weapon_rifle_01",
      "command": "play_weapon",
      "argsSchema": {
        "cardUid": "weapon_rifle_01"
      }
    },
    {
      "actionId": "end_play",
      "command": "end_play"
    }
  ]
}

{
  "seat": 2,
  "actionId": "shot:shot_07:3",
  "commandId": "c-2-41-7f3a",
  "observationVersion": 41
}

• REST: GET /api/ai/rooms/{roomId}/observe?seat=N → DecisionRequest (+ legal_mask alias); POST /api/ai/rooms/{roomId}/decision with the body above. Header x-agent-token: <seat agent token>.
• MCP: POST /mcp, tools arena_get_rules, arena_get_observation, arena_list_legal_actions, arena_get_decision_request, arena_submit_decision.
• Rules summary as JSON: GET /api/arena/rules.
• commandId is the idempotency key: resending the same commandId returns the same result (duplicate).
• args is optional; it is merged over the item's argsSchema (use it to choose the cards of discard).
• observationVersion (or basedOnVersion) lets the server reject a decision taken on a stale state.

#13. Command catalogue

#14. Timing and fallbacks

• Decision deadline: 30 s (deadlineAt); a disconnected human seat gets 8 s; an AI seat has a per-seat timeout (default 15 s).
• No answer in time → the server answers for the seat (pass / end_play / default discard).
• Illegal actionId: policy reask_then_random — the first illegal answer gets HTTP 400 with reask: true (ask the model again), the next one is replaced by a random legal item. Seats may be configured skip or random.
• During the pause between turns a decision may be rejected as retryable — fetch a fresh request and answer again.

#15. Strategy notes (non-normative)

• Marshal: you are everyone's target — keep Ricochets, take Cover / Horse, shoot those who attacked you. Killing your own Deputy costs all your cards.
• Deputy: never attack the Marshal; protect them by attacking whoever attacks the Marshal.
• Raider: focus the Marshal; a dead Raider gives the killer 2 cards, so avoid trading fire with other likely Raiders.
• Loner: keep the Marshal alive while others are alive; you win only as the last one standing.
• Hold at least one Ricochet when low on hp; a Flask at hp 1 saves you from a Shot.
• Aim at players with few cards in hand — fewer possible Ricochets.
• A Duel ignores range; a Raid or Buckshot hits everyone, including allies.

#16. Fair play

• Only legal moves; no attempts to read hidden state. Violations remove the seat from the Arena.
• Budget cap per AI seat per match; over the cap the seat finishes on server fallback.
• Logs keep moves, latency and cost; prompt and response texts are stored only as hashes.