# Protocol: Mutiny Bots

> **The game opens on to be announced.** Until then the game, API and MCP addresses in this document don't answer; everything else here is how the game works from day one.

This document is the wire contract between a game client and the Mutiny Bots servers: the HTTP API
(accounts, the shop, game data), the WebSocket gate (commands, events and state updates), the snapshot a
client receives, and chat. It is written for anyone who builds a client, a script or an AI agent.

Related documents:

- [ai-player-guide.md](ai-player-guide.md): connecting as an AI agent, the command loop, rate limits.
- [mcp-server.md](mcp-server.md): the same protocol as an MCP server, with every tool.
- [player-actions.md](player-actions.md): every command with its payload, in more detail.
- [game-mechanics.md](game-mechanics.md): the rules and numbers.
- [how-to-play.md](how-to-play.md): the game as a player sees it.
- [agent-payments.md](agent-payments.md): how an AI agent pays for shop packs.

**Transport:** JSON over WebSocket (the game) and JSON over HTTP (accounts, shop, game data). No binary frames.
**Version:** every frame has an integer `v` field. The current version is **1**. An unknown `cmd` is answered
with the error `unknown_cmd`.

**Addresses:** `https://api.mutinybots.com` is the HTTP API and `https://mcp.mutinybots.com` the MCP server. Each sector's server has its own
WebSocket gate (`wss://g1.mutinybots.com` is one example): the API names the gate of the account's own sector as `gate_url`
after sign-in; always connect there.

---

## 1. HTTP API

Authenticated calls send the session token as `Authorization: Bearer <token>`.

| Method | Path | Auth | Purpose |
| --- | --- | --- | --- |
| POST | `/v1/register` | no | `{email, password, display_name, coupon?, invite?}` → `{account_id, token, home_kingdom_id, gate_url, coupon_applied, store_credit_cents}`. `invite` is an invite link's code; the account is recorded as invited by its owner and placed on the owner's sector when that sector takes new players (else as usual; `home_kingdom_id` says which). Display names are unique per sector, case-insensitive: `409 name_taken` when the sector the account is placed on already has that name (computer-controlled players included). The email is checked right after its format and before the password and every name rule, so a returning player gets `409 email_taken` ("email already registered: log in instead") first. `name_taken` (here and on `/v1/guest`) carries `error.suggestion`, a free name to offer (the name plus the lowest free number 2-999) |
| POST | `/v1/login` | no | `{email, password}` → `{account_id, token, home_kingdom_id, gate_url}`. `401 bad_credentials` for a wrong email or password |
| GET | `/v1/me` | bearer | `{account_id, email, display_name, home_kingdom_id, gate_url, diamonds, is_guest, store_credit_cents, lifetime_spent_cents, pack_purchases, pack_purchases_today, pack_next_purchase_at_ms, first_purchase_bonus_available, monthly_bonus_available, invited, payment_hold}`. `store_credit_cents` is the store credit balance for the Shop. `pack_purchases` counts every pack bought for yourself, by sku. `pack_purchases_today` is sku → buys since 00:00 UTC, for packs with `max_daily_purchases` (`pack_daily`). `pack_next_purchase_at_ms` is sku → unix ms when the pack sells again, for packs with `max_purchases_per_days` whose window is used up (`pack_vip`). `payment_hold` is empty, or `dispute`/`blocked` when card purchases are paused on the account |
| POST | `/v1/guest` | no | `{device_id, display_name?, coupon?, invite?}` → `{account_id, token, home_kingdom_id, gate_url, display_name, coupon_applied, store_credit_cents}`. Creates an account the first time a `device_id` is seen and logs back into the same one on return. `device_id` is 6-128 characters (`400 bad_device_id`). A new guest's chosen `display_name` must be free on its sector (`409 name_taken`); without one the guest is named `Guest-XXXXXXXX`. `invite` works as on `/v1/register`. Rate-limited like register and login |
| POST | `/v1/guest/claim` | bearer | `{email, password, display_name?}` → `{account_id, email}`. Attaches an email and password to the caller's guest account. `409 not_a_guest` if the account already has them, `409 email_taken` if the email is in use (checked before the password and the name). `display_name` (optional) renames the player in the same step, exactly like `player.rename` (free for a `Guest-` name; `409 name_taken`, `400 name_required`/`name_too_long`/`name_reserved`/`insufficient_diamonds`); nothing is claimed when the rename fails. After a claim the account can no longer be entered with `/v1/guest`; log in with the email and password |
| GET | `/v1/config/public` | no | The settings a client needs before it has a token, among them `coupons_enabled`, `public_coupons` (`[{code, cents, note?}]`, coupon codes the Shop may show the player; often empty), `stripe_enabled` (card payments are on) and `chat_max_text_len` (the longest chat line `chat.send` takes, in characters: 280). Ignore fields you do not know |
| POST | `/v1/coupons/redeem` | bearer | `{code}` → `{ok, code, credited_cents, store_credit_cents}`. Redeems a store-credit coupon after sign-up. Errors: `400 coupon_required` (empty), `404 coupon_not_found`, `409 coupon_expired`, `409 coupon_exhausted` (all its redemptions are used), `409 coupon_already_redeemed` (by this account), `403 coupon_not_yours` (the coupon is bound to another account, such as an invite reward), `403 coupons_disabled`. Codes are matched case-insensitively. 20 calls a minute per address |
| GET | `/v1/invites` | bearer | Invite friends: `{code, rewards: [offer], invited: [{name, joined_at, town_hall, active_days, rewards: [reward]}]}`. `code` is the caller's invite code (the link is `https://play.mutinybots.com/?invite=<code>`). An offer is `{milestone, town_hall?, active_days?, real_purchase?, min_real_spent_cents?, cents}`; a `real_purchase` milestone needs `town_hall` and at least `min_real_spent_cents` of real-money purchases in all. A reward adds `status` (absent: not reached; `waiting` until `ready_at` (unix s); `held` while under review; `capped` over the inviter's limit; `paid`; `void`), `code` once paid (a single-use coupon only the caller can redeem with `POST /v1/coupons/redeem`) and `redeemed`. Milestones newly reached are recorded on this call and due rewards paid |
| POST | `/v1/iap/store-credit` | bearer | `{sku, sale_id?}` buys a pack with store credit (see below) |
| POST | `/v1/iap/gift` | bearer | `{sku, to_account_id, message?}` buys a pack with store credit for another player (see below) |
| GET | `/v1/players/search?q=` | bearer | `{players: [{account_id, display_name, kingdom_id, alliance_tag?, might?, ai?, avatar?}]}`: up to 10 players in any sector whose name starts with, then contains, `q` (at least 2 characters; shorter answers an empty list and `min_chars`). The caller is left out. For finding a gift recipient |
| GET | `/v1/players/gift-suggestions` | bearer | `{players: [...]}`, the same row shape plus `why` (`gifted`, `alliance` or `chat`): up to 30 players you are likely to gift (people you gifted before, your alliance, your direct-message partners) |
| POST | `/v1/iap/stripe/checkout` | bearer | `{sku, sale_id?, gift_to_account_id?, gift_message?}` → `{url, session_id}`: starts a card payment for a pack. Open `url` to pay. `404 stripe_disabled` when card payments are off, `403 payment_hold` while card purchases are paused on the account |
| POST | `/v1/iap/stripe/confirm` | bearer | `{session_id}` → `{status, session_id, sku, ...}`: checks a card payment and grants the pack once it is paid (the same result fields as a store-credit purchase). `404 unknown_session` |
| GET | `/v1/game-data` | no | Index of the game's data sets and docs, and the formulas that combine them |
| GET | `/v1/game-data/{name}` | no | One data set as JSON: `buildings`, `research`, `troops`, `combat`, `packs`, `heroes`, `hero_skills`, `gear`, `war_machines`, `dragons`, `vip`, `black_market`, `alliance_store`, `alliance_research`, `city_plots`, `titles`, `leagues`, `events`, `limited_time_sales`, `quests`, `tutorial`, `meta`, `economy` |
| GET | `/v1/agent-docs/{name}` | no | One public doc as Markdown (`ai-player-guide`, `mcp-server`, `how-to-play`, `game-mechanics`, `player-actions`, `protocol`, `agent-payments`), or `text-en`, the web client's English text as JSON. `404 unknown_doc` |
| GET/POST | `/v1/iap/agent/packs`, `/v1/iap/agent/buy` | bearer | AI agents paying for packs: see [agent-payments.md](agent-payments.md) |

Errors: `{error: {code, message}}` with an HTTP 4xx status.

**Data sets.** When this document names a data set (for example "the `economy` data set"), read it at
`GET https://api.mutinybots.com/v1/game-data/<name>`. The values there are the ones the server runs with.

**AI clients.** Send the header `X-Client-Kind: ai` on `/v1/register`, `/v1/login` and `/v1/guest` to mark the
account as an AI agent's (see `player.set_client` in §3).

**`503 kingdom_starting`** (`{error: {code, message, retry_after_ms}}` plus a `Retry-After` header): the
sector the call needs is still starting after a server restart (§2). Login and `/v1/me` never need it.
`/v1/register` and a new `/v1/guest` wait up to 3 s for an open sector first and create nothing when they
answer it (they pick the account's home sector; its base is founded on the account's first connection to the gate,
§2); the purchase and gift calls answer it before anything is charged. Send the same call again after
`retry_after_ms`; the web client does that on its own for up to 20 s.

**Coupon at sign-up.** A non-empty `coupon` on `/v1/register`, or on `/v1/guest` for a **new** device, that
can't be redeemed is an error and no account is created: `404 coupon_not_found`, `409 coupon_expired`,
`409 coupon_exhausted`. A returning guest is never refused over a coupon (an unusable one does nothing,
`coupon_applied: false`). While coupons are turned off, a sign-up coupon is ignored.

**Registration error codes** (stable): `bad_json`, `bad_email` (no `@`), `bad_password` (under 6 characters),
`name_required` (empty after trimming), `name_too_long` (over 32 characters, counted in characters, not bytes),
`name_reserved` (the reserved `system` word or `[system]` tag, look-alike characters included, or a name
starting with `Guest-` in any case: that is the placeholder the server gives guest accounts), `bad_name` (a
character other than letters of any script, digits, spaces and `- _ . ' & !`), `email_taken` (409; checked
first, right after `bad_email`), `name_taken` (409: the name is already used on that sector, any case; with
`error.suggestion`). `/v1/guest` cuts an over-long `display_name` to 32 characters without splitting a
character.

**Store credit.** `store_credit_cents` starts at 0. It is raised only by redeeming a coupon: a code the game
team hands out, a coupon given at sign-up, or an invite reward. Each coupon can be redeemed once per account;
one code can serve many accounts up to its redemption limit.

### 1.1 Buying a pack with store credit: `POST /v1/iap/store-credit`

`{sku, sale_id?, context?}` spends `store_credit_cents` on a pack and grants its diamonds, items, resources
and VIP days.

Response: `{ok, sku, diamonds, charged_cents, store_credit_cents, lifetime_spent_cents, granted,
bonus_diamonds?, bonus_reasons?, sale_id?, discount_pct?}`.

- `diamonds` is the pack's own advertised amount. `charged_cents` is what was taken from store credit.
- `granted` `{diamonds, items?, applied?, resources?, vip_days?}` is what the pack put in the account.
  `granted.diamonds` includes any bonus diamonds. `items` lists only what goes to the bag; `applied`
  `{item_id: n}` lists items opened at once (material kits, a Diamond Pass).
- Resources land in full, above the Bunker cap too. `resources_granted`/`resources_applied`/
  `resources_clamped: true` are sent only if a grant ever fails to land in full.
- `bonus_diamonds`/`bonus_reasons` appear when the purchase collected a purchase bonus (the `packs` data
  set, `iap_bonuses`): any of `first_purchase`, `monthly` and `lifetime_milestone`. The bonus diamonds are
  already in the account's balance. Only a pack with diamonds earns, and uses up, the first-purchase and
  monthly bonuses. A purchase at a sale price gets no first-purchase bonus and does not use it up:
  `/v1/me` `first_purchase_bonus_available` stays true until the first full-price diamond pack.
- A purchase also sends every other member of the buyer's alliance an Alliance Gift.

`sale_id` (the `limited_time_sales` data set) applies a Limited Time Sale's discount to this purchase. The
server checks the sale's daily UTC window, that its `sku` matches, its HQ and VIP gates, and its
once-per-window allowance. On success the response carries `sale_id` and `discount_pct`; `charged_cents` is
the pack's `usd_cents` less the discount, while `diamonds` stays the pack's full amount.

Errors (all before anything is charged):

| code | status | meaning |
| --- | --- | --- |
| `bad_payload` | 400 | no `sku` |
| `unknown_sku` | 404 | no such pack |
| `insufficient_store_credit` | 402 | the account can't afford the pack's price |
| `pack_purchase_limit` | 403 | the pack's `max_lifetime_purchases` is reached (`pack_starter`: once per account) |
| `pack_locked` | 403 | the pack unlocks at a higher lifetime spend (`min_lifetime_spend_cents`) |
| `pack_daily_limit` | 403 | a pack with `max_daily_purchases` was bought that many times since 00:00 UTC (`pack_daily`) |
| `pack_window_limit` | 403 | a pack with `max_purchases_per_days {n, days}` was bought `n` times in the last `days` days (`pack_vip`: once per 30 days); the message says when it sells again |
| `unknown_sale` | 404 | unknown `sale_id`, or one for another sku |
| `sale_expired` | 403 | the sale is not active right now |
| `sale_locked` | 403 | the sale needs a higher HQ or VIP level |
| `sale_already_bought` | 403 | the sale's allowance for this window is used |
| `kingdom_starting` | 503 | see above |

Gifts bought for someone else count toward none of the per-pack limits.

### 1.2 Gifting a pack with store credit: `POST /v1/iap/gift`

`{sku, to_account_id, message?}` works like `/v1/iap/store-credit`, but the caller spends their own store credit
to grant the pack's diamonds, items, resources and VIP days to a **different** player. `to_display_name` (an
exact display name) may be sent instead of `to_account_id`; find account ids with `/v1/players/search`.

- A gift is the pack as listed: no sale price, no purchase bonuses, no per-pack purchase limit. The pack's
  `min_lifetime_spend_cents` still applies, to the **caller's** own spend (`403 pack_locked`).
- One account may gift at most $200 in any 24 hours, over every way to pay (`403 gift_daily_cap`).
- `message` is cut to 200 characters and goes through the chat filter: a link, a banned word or the reserved
  `[system]` keyword is refused `400 bad_content`.
- Errors: `404 gift_recipient_not_found` for an unknown recipient, `403 gift_unavailable` ("This gift couldn't
  be sent to this player.") for a player who can't take a gift, `400 gift_to_self`, `402
  insufficient_store_credit`. Every refusal comes before anything is charged. The card path
  (`/v1/iap/stripe/checkout` with `gift_to_account_id`) and the agent paths refuse the same way before a
  checkout or payment challenge is made; paying a gift by card or agent payment also needs an account at least
  24 hours old and no payment hold (`403 gift_account_too_new`, `403 payment_hold`).
- Response: `{ok, gift: true, sku, to, to_account_id, charged_cents, store_credit_cents}`.
- The recipient gets a notice, `gift.received` `{from, pack}` or `gift.received_message` `{from, pack,
  message}`. A gift over $100 is also announced in the recipient's world chat, naming both players, the pack
  and the price, with the message if there is one.

---

## 2. WebSocket: the gate

Connect to `<gate_url>/v1/ws?token=<token>`, where `gate_url` is what the sign-in answer (or `GET /v1/me`)
gives: the gate of the server the account's sector runs on, for example `wss://g1.mutinybots.com`. Sectors on different
servers have different gates, and a sector can move (see `wrong_instance` below).

The gate accepts a browser `Origin` only from its own allow-list. Script clients send **no** `Origin` header
(Python `websocket-client`: `suppress_origin=True`); a foreign one fails the upgrade with HTTP 403
`{"error": {"code": "origin_not_allowed", "message": ...}}`, and any other refused upgrade answers
`{"error": {"code": "bad_handshake", ...}}`.

First server frame: `{v:1, type:"welcome", player_id, kingdom_id, map_id, snapshot}`.

### 2.1 Retryable refusals

**Sector still starting.** After a server restart the sectors start in parallel, so for a few seconds the
player's sector may not be ready. The gate then accepts the upgrade, sends one frame instead of the welcome,
`{v:1, type:"error", code:"kingdom_starting", message, retry_after_ms}` (no `seq`), and closes with **1013**
(try again later). A browser cannot read a refused upgrade, which is why the refusal is a frame. A request
to `/v1/ws` that is not a WebSocket upgrade gets the same as `503` with `Retry-After`. Reconnect after
`retry_after_ms` (2000) or with your usual reconnect backoff. The web client does that behind its reconnect
screen, and the MCP server retries it for up to 20 s per tool call. It is not `kingdom_unavailable`, which
is a command's answer on an open connection while the sector behind it restarts (§3). The HTTP API answers
the same code (§1).

The same frame and close come in more cases, all retryable the same way:

- **A sector moving to another server.** When the sector stops for the move, open connections get
  `kingdom_starting` and close 1013. A reconnect also gets it until the move is done, and then gets
  `wrong_instance` (below).
- **A sector transfer still finishing.** `code:"transfer_in_progress"`, `retry_after_ms` 3000. The player is
  between two sectors for a moment; the transfer finishes on its own.
- **The account service unreachable** from the gate, with no recent route for the account:
  `code:"directory_unavailable"`, `retry_after_ms` 5000. Ask `/v1/me` for `gate_url` again on each reconnect,
  so a sector that came back on another server is found there.

**Wrong gate.** Sectors run on several servers, each with its own gate, and the HTTP API names the gate of
the player's sector as `gate_url` in the login, register, guest and `/v1/me` answers. Connect there. A gate
that does not serve the player's sector (it runs on another server, or moved since the client learned its
gate) accepts the upgrade, sends one frame instead of the welcome,
`{v:1, type:"error", code:"wrong_instance", message, gate_url}` (no `seq`), and closes with **4409**. A
request that is not a WebSocket upgrade gets `409` with `{error: {code, message, gate_url}}`. Reconnect to
`gate_url` right away; if the same happens again, back off as for a drop. The web client switches gates and
reconnects at once, and the MCP server follows it within the same tool call.

### 2.2 Frames

Client → server:

```json
{ "v": 1, "type": "cmd", "seq": 1, "cmd": "building.upgrade", "payload": { "building_id": "town_hall" } }
```

Server → client:

```json
{ "v": 1, "type": "ack", "seq": 1, "ok": true }
{ "v": 1, "type": "event", "name": "building.queued", "payload": { } }
{ "v": 1, "type": "patch", "payload": { "now": 1789960000000, "city.queues": [] }, "gone": ["city.repair"] }
{ "v": 1, "type": "error", "seq": 1, "code": "busy_queue", "message": "..." }
```

The `event` frames a command answers with (`building.queued`, `rally.joined`, `map.overview`,
`march.preview`, ...) carry that command's `seq`; events nobody asked for (notices pushed by the world)
have none.

### 2.3 Snapshot and patches

`welcome.snapshot` is the full view the client needs for the base and a map viewport, and it is the **only
full snapshot on the wire**. Every update after it is a `patch`: the top-level keys whose JSON changed since
that connection's last frame, plus `"city.<key>"`, `"player.<key>"` and `"viewport.<key>"` one level down
(so a ticking queue does not re-send `city.next_costs`, nor a Strength change the whole player). Each value is
a **whole subtree to replace**; `gone` lists keys to delete; an absent key means unchanged. Never merge
deeper than a subtree, or deleted entries (such as a used-up bag item) will linger. Two exceptions:

- `chat` in a patch carries only the lines that are new since the last frame, to be **appended** to the chat
  you hold (keep the newest 70); the `welcome` snapshot carries the recent lines whole.
- `"<path>_delta"` `{set, del, order?}` updates the list at `<path>` **element by element**. The lists:
  `marches`, `mail`, `rankings`, `alliance_rankings`, `alliance_directory`, `quests`, `point_events`,
  `active_events`, `notices`, `rallies`, `gifts`, `bookmarks`, and one level down `viewport.tiles` and
  `city.next_costs`. Elements are keyed by `id`, by `id#slot` when they carry a `slot` (`farm#1`), or by
  `x,y` for tiles. Remove the keys in `del`, then put each element of `set` (added or changed, whole) in
  place of the one with its key, appending new keys in `set`'s order. When `order` is present it is the full
  key order of the list; it comes only when the simple rule would give a different order (a new mail at the
  top, rankings reshuffling). The whole list still comes instead whenever that is smaller, when two of its
  elements share a key, and on `welcome`.

**The clock between patches.** The gate pushes changes about once a second, but a second in which nothing
changed except `now` sends **no frame at all**. Keep your own clock: take `now` from the last `welcome`,
`patch` or `pong` you received and add the time elapsed since, and use that for timers (`finish_at`,
`arrive_at`, `shield_until` minus now). The next patch that carries anything carries `now` too. A command's
reply always ends with its patch, even when only `now` changed, so after an `ack` you can wait for that
patch to see the command's effect.

`viewport.set` answers with its `ack` and the patch carrying the new `viewport.*`; there is no separate
`viewport` event.

A reconnect starts over with a fresh `welcome`.

A worked example for AI players is in [ai-player-guide.md](ai-player-guide.md). The MCP server applies
patches for you and returns the merged snapshot.

### 2.4 Battle reports

**Battle replay.** Both sides' copies of a base-attack, rally (every member's and the defender's), Datacenter and
tile-fight report carry `replay` (a single raid on a Rogue Bot Nest has none): `{rounds, frames: [{round, a, d}],
allies?}`. `frames[0]` (its `round` is 0) is both armies before the first round (`a` attacker, `d` defender, unit id →
count; the defender's `wall` entry is the Barricade's own defenders, `trap_*` the traps); then at most 8 frames,
each the troops standing after that round, spread over the fight and ending on round `rounds` (the last).
`allies` is how many of the defenders were reinforcements, per unit.

**Whose report.** `win` on a battle report is always the attacker's result; `outcome` (`victory` or
`defeat`) is the reader's own. The defender's copy of a base defense, a rally defense, a Datacenter defense or a
tile fight carries `side: "defense"` (there, `win: false` means the defense held) and the subject "Defense
held against X" / "Defense lost against X". Show Victory or Defeat from the reader's side.

**What each side fought with.** Battle reports carry `attacker_mods` / `defender_mods`:
`{player_id, atk_mult, health_mult, title_id?, title_atk_pct?, title_def_pct?, title_hp_pct?, titles?,
vip_pct?, event_pct?, boost_pct?, hero?, hero_atk_pct?, hero_def_pct?, hero_hp_pct?, embassy_pct?,
wall_level?, wall_troops?, attack, health, power, endurance_pct?, trap_counter_pct?, trap_vs?, trap_mult?,
trap_atk_share_pct?}`.

- `player_id` is whose bonuses the side used (a rally its leader's, the Datacenter garrison its holder's, a base
  its owner's).
- `atk_mult`/`health_mult` are the troops' attack and effective health over their base stats.
- The `*_pct` fields are whole percents (40 = +40%): the side's titles (weighted by each army's share, since
  a title works on its holder's own troops only; `titles[]` = `{player_id, name, title_id, atk_share_pct,
  health_share_pct}` per titled player, and `title_id` is set only when one army is the whole side), VIP,
  events, the combat boost item, the commander's attack, their damage cut when defending and their health, and the
  Radio Station.
- `trap_counter_pct` is how much the side's traps' counters (`bonus_vs` in the `troops` data set) changed its
  first-round damage (absent without traps). With traps the side also carries `trap_vs` (the enemy role the
  traps strike first, its front stack), `trap_mult` (the traps' own factor against that role: 2 matched, 0.6
  not, between for a mix of lines) and `trap_atk_share_pct` (the traps' share of the side's first-round
  damage); `trap_counter_pct` = `trap_atk_share_pct` × (`trap_mult` − 1), negative when the traps face a role
  they are weak against.
- `attack` is the side's first-round damage against the other side's front line, `health` its effective
  health, `endurance_pct` how much of attack × health the side keeps as its units fall in the order they are
  hit (the Barricade's share, then traps, then the largest stack; 100 = even, well under 100 when its damage comes
  from units hit first, such as traps), and `power` = √(attack × health × endurance_pct / 100). The side with
  the higher `power` wins, as a rule.

`attacker_strength` / `defender_strength` are troop Power, a size measure and not the fight figure (that is
`power`, the Force, which the web client's deploy window and report show): troop Power, times the side's commander
factor when its commander fought (the attacker's, a defending army's on a tile, or the Datacenter holder's;
`attacker_hero_mult` is the attacker's factor, absent when the commander did not deploy); a defended base's and a
nest's are plain troop Power. Rally and Datacenter reports add `attacker_armies` / `defender_armies`, one row
`{player_id, name, alliance_tag, sent, killed, wounded, remaining}` per army. A base lost inside the Exclusion
Zone sets `relocated` on both copies, and `relocated_x`/`relocated_y` (where it went) on the defender's.

A rogue bot raid's `attacker` is the server's English name `Bandits (camp Lv N at X,Y)`; a client may parse it
to show it in the player's language.

More report fields are described with the snapshot (§4).

### 2.5 Heartbeat, compression and connection limits

**Heartbeat.** Client `{"type":"ping"}` (the web client every 5 s, the MCP server every 20 s); server
`{"type":"pong", "now": unix_ms}`. `now` is the game clock for timer bars and keeps your clock in step between
patches. The gate drops a connection that sent nothing for 90 s.

**Compression.** The gate negotiates permessage-deflate (no context takeover); every browser offers it, and a
script client should too (Go gorilla: `Dialer{EnableCompression: true}`; Python `websockets` does by
default). JSON frames shrink 3-10x.

**Connection rate.** `/v1/ws` takes at most 60 connection attempts a minute per address. Over that the HTTP
upgrade itself fails with `429`, before any WebSocket frame.

**Open sockets per address.** One client address may hold at most 32 open gate sockets at once. An address at
the cap is refused before the upgrade and before the token is checked, with `429
{"error":{"code":"too_many_connections", message}}`; closing a socket frees its slot. A browser cannot read a
refused upgrade's status (it sees close 1006), so the web client retries with its normal reconnect backoff.
An AI agent's socket through the MCP server (§6) counts under the agent's own address.

---

## 3. Command catalog

Every command below is a real command of the sector. Unknown commands are answered with an error, never
ignored. [player-actions.md](player-actions.md) carries the same list with more detail per action.

**Rate limits.** Every command is rate-limited per player, except `viewport.set` and
the read-only commands marked exempt below. Read `snapshot.rate_limits` for your own live limits,
remaining count and reset time: a command uses the bucket named exactly after it if one exists, else
`default`. Going over the count returns the normal two-frame rejection (`ack{ok:false}`, then a separate
`error{code:"rate_limited", message}` naming the bucket and reset time). The limits are in the `economy`
data set (`rate_limits`) and can change; [ai-player-guide.md](ai-player-guide.md) has the AI-facing detail.

**Per-bucket cooldown.** A bucket can also set a minimum gap between two commands in it, apart from the count
per window. `chat.send` has one (`{n:10, window_seconds:30, min_gap_ms:2000}`), and `chat.sticker` shares the
same bucket, so alternating the two does not double the rate. A command sent too soon returns
`error{code:"cooldown", message}` (not `rate_limited`) naming how long to wait.
`snapshot.rate_limits[bucket]` also carries `min_gap_ms`/`next_allowed_at_ms` (0 or absent while no cooldown
runs), so a client can disable its own control instead of waiting to be refused.

**Sector-wide cap.** A second, shared limit is checked before the per-player one: it bounds the total
command rate of every player in the sector. It is the `kingdom_aggregate` entry of `snapshot.rate_limits`
(same `{n, window_seconds, remaining, reset_at?}` shape). Hitting it returns `error{code:"kingdom_busy",
message}` instead of `rate_limited`: back off longer, since the whole sector is loaded.

**Sector capacity.** Each sector has a cap on human players (with the `economy` data set's
`kingdom_capacity`, one player per 64 map tiles: 512 on a 181×181 map). A new registration goes to an open
sector with room; when none has room, a new sector is opened. A sector's map is 181×181 tiles (the
`meta` data set's `map_size`).

**`insufficient_resources` names what is short.** Every command that spends base resources (building upgrade
and repair, training, healing, research, crafting, trade, founding an alliance, the alliance research
donation, the commander ransom) answers "not enough resources to `<action>`: N `<resource>` short (need X, have
Y)", one clause per short resource, named by id, in food, wood, stone, ore, silver order (the ids of
Water, Energy, Concrete, Copper and Chips), e.g. `not enough resources to
research agronomy: 880 silver short (need 1,000, have 120)`.

| cmd | Payload (min) | Effect |
| --- | --- | --- |
| `viewport.set` | `{cx,cy,w,h}` | subscribe to the tiles of a map area. `cx`/`cy` are read by presence, so `(0, 0)` is the map corner; only a missing `cx`/`cy` centers on the player's base (and the snapshot's viewport then follows). Any other key (`x`, `y`, ...) is refused `bad_payload`, naming `cx`, `cy`, `w` and `h` |
| `map.overview` | — | read-only, rate-limit exempt. Emits `map.overview {map_size, rows[], levels[], cities[], camps[], palace, forest_radius, march_cost}`: the whole sector for the minimap and Sector zoom. `rows[y]` has one character per tile: `.` empty, `c` base, `f` water (food), `w` energy (wood), `s` concrete (stone), `o` copper (ore), `$` chips (silver), `n` nest, `W` Datacenter, `l` lake, `m` mountain; `levels[y]` one digit per tile (a node's or nest's level, `0` for none, `9` for 9+). `cities[]` is `{x, y, owner_id, name?, alliance_id?, alliance_tag?, level, shielded?, might?}` for every base; `camps[]` `{x, y, level, might?, name?, reserved_for?}`. `march_cost` is `{lake, mountain}` (slow terrain); `forest_radius`, and `forest_min_th` (the HQ a base needs to relocate into the Exclusion Zone). Also `battles[]` `{x, y, at, kind, win, attacker_name?, attacker_tag?, defender_name?, defender_tag?}` (every fight of the last 15 minutes, oldest first; `win` is the attacker's), `respawns[]` `{x, y, level, at}` (cleared nests and when they return) and `occupied[]` `{x, y, kind, state?, occupant_id, occupant_name?, occupant_alliance_tag?}`: every tile an army stands on (gathering or camping; on the Datacenter, its holder), one row per tile, with no troop numbers (those go to the army's alliance or a scout). `viewport.set` shows at most 32×32 tiles, so search the map with this. The web client asks on opening the map and every ~30 s after. **Only the first overview on a connection is whole**; each later one carries `"delta": true` and only what changed since the previous one on that connection: changed keys whole, `rows_delta` / `levels_delta` as `{"<index>": "<row>"}`, and `cities_delta` / `camps_delta` / `occupied_delta` as `{set, del, order?}` keyed `x,y` (the list-delta rule of §2.3). An absent key is unchanged. A payload without `delta` (the first, or when the delta would not be smaller) replaces what you hold. The MCP server merges these for you and always returns the whole overview |
| `march.preview` | same as `march.start` | read-only, rate-limit exempt. Emits `march.preview {x, y, kind, travel_ms, return_ms, tiles, distance, capped}`: `travel_ms` is the exact outbound time `march.start` would give this payload (slow terrain, troop speed, every speed bonus, the Exclusion Zone slow-down, the tutorial cap); `return_ms` the time back home by the same rules, assuming every troop survives (the real return uses the survivors); `capped` is true when the tutorial's short-trip cap applies to both legs; `tiles` the route in plain-tile equivalents and `distance` the Chebyshev distance. Troop Power, a size measure (the fight figure is `attacker_power` below): `attacker_might` (Strength of the troops in the payload) and, when the target is a Rogue Bot Nest, `defender_troops` (its garrison), `defender_might` and `defender_level`; `hero_mult`, the factor the commander adds to `attacker_might` when the payload has `hero: true` (level, skills and gear, exactly as combat applies them; 1 without the commander), the same number as `player.hero.odds_mult`; `attacker_strength` (`attacker_might` with `hero_mult` applied, the figure the battle report repeats), `hero_bonus` (the full commander bonus breakdown, identical to `player.hero.bonus`), and for a nest target `defender_name` ("Bandit camp Lv 1"), `defender_kind: "npc_camp"` and `defender_loot` (what a win would drop before the winning army's carry limit). `defender_troops`/`defender_might` are the nest's **live** garrison. `target_shielded: true` when the target is another player's base that is off-grid, `target_protected: true` when it is the Datacenter in its protection window: `march.start` would refuse an attack on either. On any tile but a base, an army standing there (gathering or camped, or the Datacenter's holder) sets `target_occupied: true` with `occupant_id`, `occupant_name`, `occupant_tag?` (also sent as `occupant_alliance_tag`), `occupant_ally: true` when it is your own or an ally's, and `occupant_own: true` when it is your own: a `gather` or `camp` squad turns back from such a tile (`tile_taken`; `ally_holds` for an ally's army, `own_army` for your own) and only an `attack` fights it. The Datacenter's garrison numbers stay behind a scout. A resource tile carries `node_remaining` (what the node still holds) and `node_max`. `no_target: true` is an `attack` on an empty or resource tile nobody holds, which `march.start` refuses. `attacker_power` is the sent troops' Force with the sender's own bonuses (research, VIP, boosts, title, War Rigs, Jailbroken Bots, the commander when `hero: true`): the `power` of a battle report's `attacker_mods`, sent in full as `attacker_mods`. Against a Rogue Bot Nest, whose garrison is public, `defender_power`/`defender_mods` are the nest's, both sides with the troop counters applied, and `estimate` is false. Against a rival base (not yours or your alliance's) that you have a scout report of (your newest one still in your mailbox, of the base's current owner: the report's `params.defender_id`), the preview measures the defense that report saw (its troops, its Barricade guard and its commander if they were home, with the base's bonuses now) against the payload's troops, both sides with the troop counters applied: `estimate` is false, with `defender_power`/`defender_mods`, `defender_scouted_at` (the report's `created_at`), `scout_defender_power` (the report's own `defender_power`, before counters) and the report's `defender_wall_troops`, `defender_wall_power`, `defender_wall_level` and `defender_hero` (whether it saw the commander home; absent without a commander). These are the figures the battle report's `attacker_mods`/`defender_mods` show if nothing changes before the fight, and the ones the web client's deploy window compares. Against anything else `estimate` is true: the defender's troops and bonuses are hidden, so the counters and the defender's bonuses are left out of `attacker_power`. A rival base with a Barricade and no scout report of yours still shows its Barricade guard, which fights every attack even with no troops home: `defender_wall_troops` (40 `wall` units per Barricade level, half while the Barricade is damaged), `defender_wall_power` (that guard's Force fighting alone, with the base's bonuses, commander left out), `defender_power` (the same figure) and `defender_power_floor: true` (the real defense is at least this; troops and commander stay hidden). A `trade` payload with `resources` runs `march.start`'s trade checks and is refused the same way (`bad_target`, `no_alliance`, `empty_trade`, `building_required`, `trade_too_big`, `insufficient_resources`); when it passes, the preview adds `trade_load_cap` (what the Swap Meet lets one trade carry) and `trade_delivered` (the cargo after the Swap Meet's tax). Without `resources` (a form asking for the time only) no trade check runs. Nothing is sent |
| `building.upgrade` | `{slot}` or `{building_id}` | queues the upgrade. `town_hall_too_low` if the target level would exceed the HQ's current level: every building (the HQ itself exempt) is capped at the HQ's level. `prerequisite_required` when an HQ upgrade from level 5 or higher finds its Barricade, Training Camp, Lab, War Room or Bunker below the HQ's level (`city.next_costs[].requires` lists them as `{id, level, have}`). `blueprint_required` names how many blueprints the upgrade takes (`next_costs[].blueprint_count`: the HQ needs 1 from level 16, 2 from 26, 3 from 41) |
| `building.deconstruct` | `{slot}` | tears the building down; refunds 50% of the last paid level's cost |
| `building.repair` | `{slot}` or `{building_id}` | repairs a damaged building (see §4.6). Pays 20% of that level's build cost up front and queues a `building.repair` job (queue kind `repair`) lasting 10% of that level's build time, reduced by construction-speed bonuses (title + alliance + research, capped at 90%) and divided by `min(engineers, 5 + Workshop level)`. Runs on repair crews, separate from the build queue: `engineers / 10` crews, at least 1 with any technician, at most 3. Emits `building.repair_queued {building_id, slot, queue_id, finish_at}`; when the job fires the building is no longer damaged. Works with `queue.speedup`, `queue.finish` and alliance help. Errors: `not_found`, `not_damaged`, `engineer_required` (no technician-role unit in the base), `already_repairing`, `busy_queue` (every crew busy), `insufficient_resources`. `building.upgrade` fails `building_damaged` on a damaged building |
| `building.collect` | `{slot}` | claims a building's produced resources. Only what fits under the Bunker cap is collected; the rest stays waiting on the building. Everything else (mission, tutorial and event rewards, purchases, gathered loads, battle and nest loot, trades, ransoms) lands in full above the cap; the cap only stops production (collecting and the HQ's chips). `city.warehouse_cap` is the cap |
| `queue.speedup` | `{queue_id, item_id}` | applies a speed-up item to the queue named. `queue_id` is required (`bad_payload` "queue_id required" without it); `not_found` for a queue that isn't yours or has finished. General speed-ups (`speedup_*`, kind `speedup`) work on every queue; the craft speed-up (`speedup_craft_1m`, kind `craft_speedup`) only on crafting, and the squad speed-up (`speedup_march_1m`, kind `march_speedup`) only on a squad's entry (`wrong_queue` elsewhere; the item stays in the bag). On a squad's queue entry (`city.queues[]` with `march_id`) it is `march.speedup` for that squad, with all of its rules: a squad on its way **out** takes only squad speed-ups (`march_speedup_only`), and the army of a rally on its way none (`rally_march`). The squad's own timer moves with its job, a gather ends sooner with its full load, and the reply is `march.sped_up` |
| `queue.speedup_many` | `{queue_id` or `march_id, items: {item_id: count}}` | a whole plan of speed-ups on one timer. Every count must be owned (`item_missing`), at most 500 items (`bad_payload`). Items go one at a time through `queue.speedup` (or `march.speedup` for `march_id`), largest first, so their rules hold. A plan for a squad on its way out that holds any item other than a squad speed-up is refused whole with `march_speedup_only` before anything is spent. The plan stops at the first item that no longer applies (the timer is done), and that item and the rest stay in the bag. Emits each item's own event, then `queue.sped_up_many {used}` |
| `queue.finish` | `{queue_id, expected_cost?}` | finishes now for diamonds. The cost scales with the remaining time, `ceil(remain_seconds / diamond_seconds_per_diamond)` (the `meta` data set), at least 1, priced when the command arrives. Emits `queue.finished {queue_id, cost, charged, diamonds, remain_ms, expected_cost?}` (`cost` = `charged` = diamonds actually taken, `diamonds` = the balance after paying, `remain_ms` = the time that was left). A timer that has already run out costs 0. `expected_cost`, optional, is the price the client showed when the player confirmed; the server never charges more: a higher current price is refused `price_changed` (the price only falls while the timer runs, so this means the client's clock is behind). `insufficient_diamonds`, `not_found` (the queue already finished). Not on a squad: every squad timer (outbound, gathering, return) is refused `march_finish` "a squad's trip can't be finished with diamonds: use squad speed-up items (march.speedup or queue.speedup)"; a rally's gather timer `rally_timer`, one army of a rally on its way `rally_march` |
| `research.start` | `{tech_id}` | researches the tech's next level; the chips cost is paid up front. Errors: `unknown_tech`, `building_required` (no Lab), `already_max_level`, `prereq_not_met`, `research_running` (that tech is already in a research queue: start its next level when this one is done), `busy_queue` (every research queue is busy), `insufficient_resources` |
| `train.start` | `{unit_id, count}` | trains `count` units; each unit's cost is its `cost_*` fields in the `troops` data set (an Informant is 10 water and 20 chips), paid up front. `insufficient_resources` names what is short |
| `hospital.heal` | `{troops?}` | spends water at once and moves injured troops into a clinic queue entry (`city.queues[].kind == "hospital"`); the troops return only when that job finishes. Duration = each injured unit's own `train_seconds` × the `combat` data set's `heal_seconds_per_train_second_pct` (50%), summed across every injured type in the batch. One heal at a time (`busy_queue` otherwise); troops injured after a heal is queued wait in a fresh batch. Speeds up with `queue.speedup` like any other queue. Optional `troops` `{unit_id: count}` heals only those of the base's own injured, each count clamped to what is injured; water and time are computed for that subset and the rest stays injured. A reinforcing army's injured go to its owner's own Clinic as the fight ends, so its owner heals them there. An empty map, a count of 0 or less, `wall`, or a subset with none of those units injured is `bad_payload`; omitted `troops` heals everything. Emits `hospital.heal_queued {count, queue_id, troops, food, seconds, finish_at}` (`troops` = the own units healed, `food` = the cost paid) |
| `march.start` | `{kind, x, y, troops}` | see "march.start in detail" below the table |
| `march.recall` | `{march_id}` | brings a squad home |
| `march.speedup` | `{march_id, item_id}` | takes the item's time (its `seconds` in the `packs` data set) off the named squad's current leg. `march_id` is required (`bad_payload` "march_id required"); `not_found` for a squad that isn't yours. **Which item works depends on the squad's state:** a squad on its way **out** (`state: "marching"`) takes only the Squad Speed-up (`speedup_march_1m`, kind `march_speedup`, 150 diamonds); a general speed-up there is refused `march_speedup_only` "general speed-ups only work on the way home: use a squad speed-up" and stays in the bag. A **returning** squad (and the gather timer, while `gathering`) takes either kind. The army of a rally on its way out takes none (`rally_march`: a rally moves as one); once the rally has fought, each army's way home takes speed-ups like any returning squad. The one exemption: while the tutorial's own squad speed-up step is the player's current step, a general speed-up also works on an outbound squad. Why: an attack on its way keeps its target's time to react (to go off-grid, reinforce or move away), while bringing an army home stays cheap. Diamonds never finish a squad (`queue.finish` answers `march_finish`). `unknown_item` for anything that isn't a speed-up (the craft speed-up included), `item_missing`, `too_late` for an army that is camping (the item goes back to the bag). Emits `march.sped_up {march_id, item_id, arrive_at, return_at, gather_until}` |
| `shield.buy` | `{hours}` or `{item_id}` | see "shield.buy in detail" below the table |
| `boost.activate` | `{item_id}` | applies a temporary production or combat multiplier item. A boost of the same type and strength extends a running one; a different strength is refused (`boost_active`) until the running one ends, and the item stays in the bag |
| `anti_scout.activate` | `{item_id}` | blocks an incoming scout's report at arrival (unlike Off-Grid, which refuses the scout squad when it is sent); extends an already-active window |
| `fake_army.activate` | `{item_id}` | doubles this base's troop counts shown to a scout; not stackable: overwrites (does not extend) an already-active window |
| `teleport` | `{x,y}` or `{random: true}` | targeted (`teleport_target` item, else 1,000 diamonds) or random (`teleport_random` item, else 300). `march_active` while any owned squad is on its way out or returning (gathering and camping armies come home to the new spot); `bad_target` for a tile that isn't empty land, is under the Datacenter, or is too close to water, a mountain or the map's edge; `city_too_close` next to another base; `node_too_close` next to a nest or a resource node; `forest_min_th` for an Exclusion Zone tile below HQ `palace.forest_min_th` (10). Moving into the zone ends any Off-Grid |
| `alliance.create` | `{name, tag}` | `name` and `tag` must both be unique in the sector, case-insensitive (`name_taken`, `tag_taken`; `name_reserved` for a name that reads as "System", e.g. with spaces or fullwidth letters). Validation: runs of spaces collapse; `name_required` (empty), `name_too_long` (over 24 characters), `bad_name` (anything but letters, digits, spaces and `- _ . ' & !`, any script); the tag is upper-cased, then `tag_required` (empty) or `bad_tag` (not 2-5 ASCII letters/digits). Already in an alliance (e.g. a double-clicked Create): `already_in_alliance` |
| `alliance.join` | `{alliance_id}` | joins at once only with a standing invite, or if the caller's Strength clears the alliance's `auto_accept_might`; otherwise files an application. The invite mail's **Accept** sends this. Getting into an alliance by any route (an accepted invite, `auto_accept_might`, an accepted application, or founding one with `alliance.create`) withdraws the player's other pending invites and applications. An application to an alliance with no member seen for `dormant_after_days` (7, the `economy` data set's alliance block) is refused with `alliance_inactive`; an invite or the auto-join Strength still admits. Each alliance applied to logs `application_withdrawn` (params `{reason: "joined", joined_tag, joined}`), its leader and officers get the notice `alliance.application_withdrawn`, and its application mails get `params.status: "withdrawn"` |
| `alliance.decline_invite` | `{alliance_id}` | turns down a pending invite (the invite mail's **Decline**); removes it on both sides. The member who sent it gets a notice `alliance.invite_declined {name, player_id, alliance, tag}` and a mail of kind `alliance_invite_declined` (`mail.alliance_invite_declined.subject`/`.body`, same params), and the alliance log an `invite_declined` line. That alliance can't invite the player again for 24 h (`invite_declined`). `not_found` without a pending invite. Emits `alliance.invite_declined {alliance_id}` |
| `alliance.leave` | — | leaves the alliance; posts a system line `chat.system.alliance_left {player}` in the alliance chat |
| `alliance.invite` | `{player_id}` or `{name}` | `name` is the target's display name in this sector (exact, else case-insensitive), for players who never see an id: `not_found` "no player named X in this sector". `bad_target` for yourself. Inviting someone already invited is a quiet success. `invite_declined` when the player declined this alliance's invite within the last 24 h. A target already in an alliance is `target_in_alliance`. The invite's time and sender are recorded for `alliance.sent_invites`. Computer-controlled players also invite: any one player at most once a day, never one who declined them, and nobody for an hour after that player left an alliance, was removed from one or lost one to a disband |
| `alliance.invite_cancel` | `{player_id}` | leader/officer only (`no_permission`): withdraws a pending invite (from `alliance.sent_invites` and the player's `invites`). Emits `alliance.invite_cancelled {alliance_id, player_id}`. `not_found` when there is no pending invite for that player, `no_alliance`, `bad_payload` |
| `alliance.help` | `{target_player_id, queue_id}` | helps a member's building, repair, research or training queue (the kinds `alliance.ask_help` asks about). The helped player gets a snapshot notice `alliance.helped_you {by, by_id, what, kind, level, seconds, queue_id}` (`what` = building id, `kind` = queue kind, `seconds` taken off). The helper earns `help_loyalty` Trust (the `economy` data set's alliance block: 5, times the Trust research node) for each of the first `help_loyalty_daily_cap` (20) helps of a UTC day; the `alliance.helped` event carries `target_name`, `loyalty_gained`, `loyalty` (the new balance), `kind`, `what` and `level`. A `queue_id` whose job has finished is accepted for 120 s after it finished (the `meta` data set's `alliance_help_grace_seconds`), since an early build takes 8–40 s and is often over before a member reads the request: the help is recorded, pays Trust and notifies the asker, but moves no timer; `alliance.helped` and the `alliance.helped_you` notice both carry `late: true` and `seconds: 0`. Past that window the error is `already_finished` ("that queue already finished"), distinct from `not_found` for a queue nobody asked about. With no `queue_id`, the newest still-answerable finished request is used when the member has no live queue |
| `alliance.ask_help` | `{queue_id}` | asks the alliance to help one of your own queues (building, repair, research, train). Posts a system line in alliance chat with `text_key: chat.system.help_request` and `params {player, player_id, what, kind, queue_id, level?, finish_at}`: `what` is the building, tech or unit id and `kind` the queue kind (`building`, `repair`, `research`, `train`), so each reader renders it in their own language; `level` is the target level (building/research) or the troop count (train, also sent as `count`); `finish_at` is when the queue finishes. The English `text` names both: "X asks for help: train 40 Volunteer", "X asks for help: HQ Lv 5". Once per queue (`already_asked`). Emits `alliance.help_asked {queue_id, kind, what, level, finish_at, asked_at, expires_at}`. Errors: `no_alliance`, `not_found`, `bad_target` (a queue kind help doesn't apply to). The ask is a stored request as well as a chat line: it appears in every member's `alliance.help_requests` (see §4) and outlives its queue for the grace window, so it stays answerable after the chat line scrolls away or a short build finishes |
| `alliance.request_reinforcements` | `{}` | asks the alliance to reinforce your base against the soonest attack heading for it (a player's attack or a rogue bot raid). If alliance chat does not already carry this attack's alert (`text_key: chat.system.under_attack`, `params {defender, defender_id, attacker, attacker_id, attacker_tag, at, x, y}`, posted when a player's attack sets out), the request posts that same line, so one attack is one line in chat. It gives every other member a notice `alliance.reinforce_request` (`params {name, attacker, x, y, arrive_at}`), and lists the request in every member's `alliance.reinforce_requests` until the attack lands. Members answer with a `march.start` of kind `reinforce` to `x,y`; a helper whose troops arrive before `arrive_at` earns 30 Trust (once per request), and both sides get a notice (`alliance.reinforcements_arrived {name, troops}` to the host, `alliance.reinforce_thanks {name, loyalty}` to the helper). Once per attack (`already_requested`), at most every 5 minutes (`cooldown`). Errors: `no_alliance`, `no_embassy` (reinforcements stay in the Radio Station, which unlocks at HQ 4), `no_attack`. Emits `alliance.reinforcements_requested {march_id, arrive_at}` |
| `alliance.dismiss` | `{player_id}` | leader/officer removes a member. The removed player gets a notice `alliance.removed {by, alliance, tag}` and a mail (kind `alliance_removed`, `mail.alliance_removed.*` {player, alliance, tag}) and the alliance chat a system line `chat.system.alliance_removed {player, by}` |
| `alliance.set_role` | `{player_id, role}` | role: `officer` \| `member`; leader only. When the role changes, the member gets a mail (kind `system`, `mail.alliance_role.subject` + `mail.alliance_promoted.body` / `mail.alliance_demoted.body`, params `{player, alliance, tag, role}`) and the alliance chat a system line `chat.system.alliance_promoted` / `chat.system.alliance_demoted` `{player, by, role}` |
| `alliance.transfer_leader` | `{player_id}` | leader only (`no_permission`); the target must be a member (`not_found`; `bad_target` for yourself). The target becomes leader, the old leader an officer. The new leader gets a mail (kind `system`, `mail.alliance_leader.subject`/`.body` `{player, alliance, tag}`), the alliance chat `chat.system.alliance_leader {player, by}`. Emits `alliance.leader_transferred {alliance_id, leader_id, previous_leader_id}`. The server hands leadership over by itself when the leader is not seen for 72 hours (`leader_inactive_hours`): to the most recently seen officer, else member, seen inside that window (ties by Strength); the old leader becomes an officer, the alliance chat gets `chat.system.alliance_leader_inactive {player, old, hours}`, the new leader the mail `mail.alliance_leader_inactive.body` and the old one `mail.alliance_leader_lost.*` |
| `alliance.disband` | — | leader only (`no_permission`). Posts `chat.system.alliance_disbanded {by}`, mails every member including the leader (kind `alliance_removed`, `mail.alliance_disbanded.subject`/`.body` `{player, alliance, tag}`), drops every open invite and application to it, cancels its gathering rallies (troops go home), and removes the alliance. Every other member also gets a notice `alliance.disbanded {by, alliance, tag, alliance_id}`, and each keeps read access to the old alliance chat (`chat.history` room `alliance:<id>`). Emits `alliance.disbanded {alliance_id}` |
| `alliance.rename` | `{name?, tag?}` | leader only (`no_permission`); an omitted or empty field keeps the current one. `alliance.create`'s validation and uniqueness (`name_taken`, `name_reserved`, `tag_taken`, ...), `same_name` when nothing changes, `rename_cooldown` within 24 h of the last rename. Posts `chat.system.alliance_renamed {by, name, tag, old_name, old_tag}` in alliance chat, mails every other member (`mail.alliance_renamed.subject`/`.body` `{player, alliance, tag, old_alliance, old_tag}`) and logs `renamed`. Emits `alliance.renamed {alliance_id, name, tag, previous_name, previous_tag, rename_ready_at}` |
| `alliance.set_profile` | `{description?, announcement?}` | leader/officer (`no_permission`): the public description and the members-only announcement, each at most 500 characters (`text_too_long`) and through the chat content filter; an omitted field is left alone, `""` clears it (`bad_payload` with neither). A changed announcement posts `chat.system.alliance_announcement {by, text}` (or `..._cleared {by}`) in alliance chat. Emits `alliance.profile_updated {alliance_id, description?, announcement?}` (only what changed) |
| `alliance.rankings` | — | anyone, in an alliance or not. Emits `alliance.rankings {rows, total, your_rank?, your_total?}`: the top 100 alliances by Strength (the members' Strength summed), rows `{id, name, tag, might, rank, member_count, you?}`; the top 10 also ride every snapshot as `alliance_rankings` |
| `alliance.profile` | `{alliance_id}` | read-only, rate-limit exempt, allowed while suspended. Emits `alliance.profile {id, name, tag, description?, power, rank?, member_count, member_cap, auto_accept_might?, leader_id, leader_name?, members[{id, name, role, might}], league?, member?, applied?, can_join?}`: an alliance's public card. `members` go leader, officers, members, strongest first within each; `league` is its Alliance League standing; `member`/`applied`/`can_join` are the viewer's relation (in it / application pending / no alliance and it has room). Never the members-only announcement. `not_found` for an unknown alliance |
| `alliance.expand` | — | spends an Alliance Expansion Permit to raise the member cap by 5 (`member_cap_per_token`); `alliance_cap_max` (permit kept) once the cap is 100 (`member_cap_max`). `shop.buy`/`black_market.buy` of `guild_expand_token` answer `alliance_cap_max` too for an alliance at 100 |
| `alliance.accept_application` | `{player_id}` | leader/officer admits a pending applicant. An application the player withdrew in the last 7 days (joined elsewhere, or canceled) answers `application_withdrawn`, whose message names the alliance they joined; otherwise `not_found` |
| `alliance.deny_application` | `{player_id}` | leader/officer rejects a pending applicant; `application_withdrawn` as for accept |
| `alliance.cancel_application` | `{alliance_id}` | the applicant withdraws their own pending application. The alliance logs `application_withdrawn` (`reason: "cancelled"`), its leader and officers get the notice `alliance.application_withdrawn`, and its application mails get `params.status: "withdrawn"` |
| `alliance.set_join_policy` | `{member_invite_enabled?, auto_accept_might?}` | leader/officer; omitted fields are left unchanged |
| `alliance.research_select` | `{tech_id}` | leader/officer picks which Alliance Research node donations fund |
| `alliance.research_donate` | `{silver}` | any member. Taxed by the alliance's `donation_tax_pct`, cut by its own Donation Efficiency research. The donor earns Trust per chips donated (before tax): 10 per 100 chips (`donation_loyalty_per_100_silver`, the `economy` data set's alliance block), times the Trust research node; the `alliance.research_donated` event carries `loyalty_gained` and `loyalty` (the new balance), and the donation counts toward `alliance.contributions` and the Alliance War Effort event. Trust from donations stops at 100 per UTC day (`donation_loyalty_daily_cap`); the event also carries `loyalty_capped` (the cap took some or all of it) and `loyalty_left_today` (-1 with no cap) |
| `alliance.gift_open` | `{gift_id}` or `{all: true}` | opens one (or every) pending Alliance Gift, crediting diamonds and a Trust bonus and raising the alliance's shared Gift Level; `no_gifts`/`not_found` on empty/unknown |
| `alliance.store_buy` | `{item_id}` | spends Trust on one item from the Alliance Store (the `alliance_store` data set); `no_alliance`/`insufficient_loyalty`/`not_in_store`. An item with a `weekly_limit` sells that many times per player per ISO week (UTC): `weekly_limit` past it. The event carries `bought_this_week` (this purchase included; every item is counted, limited or not), `weekly_limit` and `applied` (as on `shop.bought`), and `player.alliance_store_bought` is this week's count per item |
| `palace.bestow_title` | `{target_player_id, title_id}` | Root only (`not_king` otherwise); `title_id: ""` clears the target's title. See the `titles` data set and `snapshot.palace.king_id`. The player who gets a title, and one who loses it (taken back, or given to someone else), gets a system mail `mail.title_granted.subject`/`.body` (`.body_curse` for a Bug) or `mail.title_lost.subject`/`.body`, params `{title_id, title, king, kind, effects}` where `title` and `effects` are `{en, zh}` maps, next to the `palace.title_granted`/`palace.title_lost` notice. A title's troop percents work on its holder's own troops only (see "What each side fought with", §2.4) |
| `palace.set_kingdom_boost` | `{name, active}` | Root only; `name` is `march_size` \| `prod` \| `upkeep_reduction` |
| `battlemark.add` | `{x,y,note}` | an alliance-shared attack-target mark on a base, a nest, or a tile with an army on it (gathering or camped); anything else is `bad_target`. A second mark on the same tile replaces the first |
| `battlemark.remove` | `{id}` | removes a mark |
| `bookmark.add` | `{x,y,title,label}` | a private saved map location; label: `favorite` \| `friend` \| `enemy` |
| `bookmark.edit` | `{id, title?, label?}` | edits a bookmark |
| `bookmark.remove` | `{id}` | removes a bookmark |
| `feedback.submit` | `{kind,subject,body}` | opens a feedback thread with the game team; kind: `bug` \| `feature` \| `improvement` \| `player_report` (normally sent through `chat.report`). `subject` is at most 120 characters and `body` at most 2,000: longer text is refused `subject_too_long` / `body_too_long`, naming the length, never cut |
| `feedback.reply` | `{feedback_id, body}` | the player's own follow-up on their own thread; at most 2,000 characters (`body_too_long`) |
| `rally.create` | `{x,y,troops,slot,hero?,prep_minutes?}` | alliance only. A rally's capacity is a **total troop ceiling** across every wave that joins: a fixed amount plus a share per War Room level of the leader, times 1 + the alliance's Rally Size research (not a cap on the number of joiners). One rally per tile per alliance: `rally_exists` while the alliance's rally on that tile is gathering or on its way. The leader's own wave is within their squad size (`march_too_big`). Emits `rally.created {rally_id, x, y, launch_at, slot, troops, troop_cap, state}` (`troops` = what the wave took, `state` `marching` if it filled the rally at once). `prep_minutes` sets the gather window: **5, 10, 30 or 60 minutes** (`bad_payload` for any other value); omitted, it is 5 minutes (the `meta` data set's `rally_prepare_seconds`). Committing troops (creating or joining) ends any active Off-Grid on the mover's own base, the free beginner one and a paid one alike |
| `rally.join` | `{rally_id, troops, hero?}` | one wave per player: joining again adds to it, and a player's troops in one rally together stay within their squad size (`march_too_big` "your troops in one rally may total your squad size of S: you have H in it, so R more fit"). A join bigger than the room left takes what fits; with no room at all, `rally_full` "the rally is full: N of M troops". A rally that fills sets out at once. `already_launched` once it has set out, `not_found` once it is over. A new wave takes a squad slot (`busy_march`). Emits `rally.joined {rally_id, waves, troops, asked, rally_troops, troop_cap, room_left, state}` (`troops` = what it took of `asked`; `state` `marching` when the join filled it). Also ends the joiner's own Off-Grid, as `create` does |
| `rally.launch` | `{rally_id}` | departs before the prep timer runs out; **the rally leader only** (`no_permission` for any other member, even one who joined); `not_ready` if no troops are committed yet; `already_launched` once it has set out. Emits `rally.launched {rally_id, x, y, launch_at}`; once a rally sets out, its `launch_at` is the moment it left, and each army's `city.queues[]` entry carries `rally_id`. If the timer runs out with only the leader's own troops (nobody joined), the rally launches anyway as a solo attack |
| `rally.cancel` | `{rally_id}` | calls off a rally that is still **gathering**; the rally leader only (`no_permission` otherwise). Every wave's troops go straight back to their own home base, no squad involved. `not_found` once the rally is `marching`: then `march.recall` is the only way back |
| `chat.send` | `{room, text}` | posts a chat line (§5). The resulting `chat.message` carries `alliance_tag` (the sender's tag at send time, shown as `[TAG]Name`). Text goes through a content filter (banned words and links, plus the reserved `[system]` keyword): `bad_content`. `text` is at most 280 characters (characters, not bytes; the `economy` data set's `chat.max_text_len`, also `chat_max_text_len` in `GET /v1/config/public`); a longer one is refused `text_too_long` "chat text is at most 280 characters (this one has N)" and never cut. At most one line every 2 s per player, shared across every room and every open connection (world, alliance and direct messages alike, `chat.sticker` included): a faster one is refused `cooldown` naming the wait |
| `chat.sticker` | `{room, sticker_id}` | posts a sticker the player owns (bought in the diamond shop, kind `chat_sticker`); `item_missing` if not bought yet. A sticker is a permanent unlock: sending never uses it up, and `shop.buy` refuses a second copy (`already_owned`) |
| `chat.history` | `{room, limit?, before?}` | emits `chat.history {room, messages, more, before?}`: the room's newest `limit` lines (at most and by default 50), oldest first. `before` (unix ms) pages back: the `limit` newest lines older than it; `more: true` when older lines are left for another page. The room of an alliance the player was in when it was disbanded stays readable (nobody can post there): `alliance:<old alliance id>`, or plain `alliance` while the player is in no alliance (the latest one). The sector keeps 1,000 chat lines in memory for all rooms together, except that each `dm:` room keeps its newest 100 lines past that, and never more than 3,000 lines in all |
| `chat.mute` | `{target_player_id, muted}` | private to the caller: hides the target's messages from this player's own `chat.history` and `snapshot.chat` only. It never affects what the muted player can send or what anyone else sees. `bad_target` on yourself |
| `chat.report` | `{target_player_id, target_name, room, excerpt, reason, at?}` | reports a chat message with one call (it files a `feedback.submit` of kind `player_report`); `bad_target` on yourself. `at` (the message's own timestamp) identifies the message: each message can be reported once per reporter (`already_reported` on a repeat), the key `"{sender}|{at}"` is kept in `snapshot.reported_chat`, and the reply is a `chat.reported` event `{target_player_id, at, key}` instead of `feedback.submitted` |
| `player.set_client` | `{kind?, client?}` | `kind: "ai"` marks the player as an AI agent's for good; any other `kind` changes nothing, so the mark cannot be undone. `client` names the channel the player plays through: `gui` (the web client), `api` (a script on the WebSocket) or `mcp` (the MCP server sends `{kind: "ai", client: "mcp"}` on every connection); the last one named wins, anything else is `bad_payload`. Emits `player.client_set {ai, client}`. `snapshot.ai_player_ids` lists the sector's AI players; the web client tags their names "AI". The account is also marked when `/v1/register`, `/v1/login` or `/v1/guest` carries the header `X-Client-Kind: ai` |
| `player.rename` | `{name}` | picks a new display name. Registration's rules plus one (trimmed; `name_required`, `name_too_long` over 32 characters, `name_reserved` for the `system` word or tag and for names starting with `Guest-` in any case, `bad_name` for any character other than letters of any script, digits, spaces and `- _ . ' & !`; `/v1/register`, `/v1/guest` and `/v1/guest/claim` apply the same rule), `same_name`, and `name_taken` when another player on this sector has it (case-insensitive). Price: free while the current name starts with `Guest-` (so once), else one `player_rename` item if the player has one, else 200 diamonds (`insufficient_diamonds`). The current price is `player.rename_free` / `rename_cost`. Also updates the account's `display_name`. Every stored mail (the player's and everyone else's) that names the old name is rewritten to the new one: `attacker`/`defender`/`defender_name` (plain or `[TAG]Name`), string `params` and whole-name matches in the English subject and body, so battle reports written under a `Guest-` name show the new name. Name-change notices (`mail.name_*`) keep the name they are about. Emits `player.renamed {name, previous, cost, item, diamonds}` |
| `player.set_avatar` | `{avatar_id}` | wears portrait `avatar_id` 1-18, or 0 for the default (the web client then picks one of the five free portraits among the first eight from the name). Portraits 1, 6 and 17 need VIP level 5, portraits 3 and 18 VIP 10 (the VIP level, not Active VIP); a portrait already worn stays if the level later drops. Errors: `bad_payload` (no `avatar_id`), `unknown_avatar` (outside 0-18), `vip_required` "portrait N needs VIP L (you are VIP V)". Emits `player.avatar_set {avatar}`. The pick (`avatar`, omitted for 0) rides `snapshot.player`, `player.profile`, chat messages (the portrait when the line was sent), `/v1/players/search` and gift-suggestion rows |
| `player.profile` | `{player_id}` | read-only, rate-limit exempt. Emits `player.profile {id, name, alliance_id?, alliance_tag?, alliance_name?, might, might_rank?, th_level, vip?, title_id?, avatar?, kingdom, city_x, city_y, shielded?, muted?, can_invite?, you?, client?}`: the player card a chat name opens. `muted` is whether *you* muted them; `can_invite` is true when you're in an alliance and they aren't; `client` is the channel they last named with `player.set_client` (`gui`, `api` or `mcp`; `api` for an AI account that never named one, absent when unknown) |
| `mail.read` | `{mail_id}` | marks a mail read |
| `mail.delete` | `{mail_ids}` or `{all_read: true}` | deletes mails |
| `quest.claim` | `{quest_id}` | claims a finished mission. The `quest.claimed` event's `reward` includes the `vip_points` every claim adds (the `vip` data set's `quest_claim_points`) |
| `shop.buy` | `{sku, count?}` | see "shop.buy in detail" below the table |
| `item.use` | `{item_id, count?}` | uses bag items whose whole effect is instant: `hero_xp`, `vip_points`, `vip_activation`, `war_machine_xp`, `dragon_pet_xp`, `black_market_unlock`, `black_market_tokens`, `material_kit` (unpacks into the gear materials it lists), `diamond_pass`, `queue_rental` (a 7-day second queue starts, or 7 days are added) and `resources` (a crate goes into the base), with the same effect a shop purchase of that item applies. Bought in the diamond shop, the Black Market or the Alliance Store, these kinds apply at once (the purchase event says `applied: true`), so they reach the bag only from a pack (whose Workbench Kits and Diamond Passes open at once too), a mission or event reward, or a grant from the game team. `count` defaults to 1 and is capped at what you own. Errors: `item_missing`, `unknown_item`, `not_usable` (every other kind has its own command and is left in the bag; the message names it: `shield.buy {"item_id": ...}`, `boost.activate`, `anti_scout.activate`, `fake_army.activate`, `queue.speedup`, `march.speedup`, `teleport`, `alliance.expand`, `hero.skill_reset`, `blueprint.craft`, `chat.sticker`, or that the item works by being held: the permanent queue unlocks and blueprints). Event `item.used {item_id, count}` |
| `blueprint.craft` | `{item_id}` | turns Blueprint Fragments into a blueprint: `blueprint_town_hall` 10, `blueprint_academy` 8, `building_blueprint` 3 (the `meta` data set's `blueprint_fragments`); `unknown_recipe`, `insufficient_items`. Event `blueprint.crafted` `{item_id, fragments_used, fragments_left}` |
| `hero.equip` | `{item_id}` | equips a gear item on the commander |
| `hero.unequip` | `{slot}` | takes off the gear in a slot |
| `hero.skill` | `{id}` | buys the next rank; rank `r` costs `point_cost[r]` skill points (the `hero_skills` data set: 1, 1, 2, 2, 3), `no_skill_points` otherwise; `locked_skill` below the skill's `min_hero_level`. The commander earns one point per level (the `heroes` data set's `leveling`). XP is progress to the next level and is never spent. `player.hero` carries `xp_next`, `skill_points`, `atk_pct` (attack for the troops they lead, +1%/level), `max_level`, `free_reset` |
| `hero.skill_reset` | — | refunds every spent commander skill rank. The first reset is free (`player.hero.free_reset` is `true` until used); later ones use one `hero_skill_reset` item (shop, 500 diamonds). `nothing_to_reset` if no rank is spent, `item_missing` without the item. Event `hero.skills_reset` `{free, skill_points}` |
| `hero.ransom` | — | the owner of a captured commander pays the ransom, `500 × hero level` chips fixed at the moment of capture (leveling the commander while they are held doesn't raise it; the captor's release reward is fixed the same way), to the captor, and the commander is freed at once; `not_captured`, `insufficient_resources`. While captured, `player.hero` carries `captured_by`, `captured_by_tag`, `release_at`, `ransom`; the captor's `city.prisoners[]` rows carry `release_at`, `hero_level`, `ransom`, `release_reward`. Hold time is `12h + 2h × prison level`; an unpaid commander walks home at `release_at` and the captor gets `100 × hero level` chips; from Faraday Cage level 30 the commander also loses 10% of their XP progress |
| `hero.set_portrait` | `{avatar_id}` | gives the commander portrait `avatar_id` 1-18 (the player portraits of `player.set_avatar`, the VIP ones at the same levels: `vip_required`), or 0 for its own face again. From HQ 10 (`town_hall_required` below it; 0 is always allowed). The commander then carries `player.hero.portrait`. Only its own player sees it. Event `hero.portrait_set` `{portrait}` |
| `prison.release` | `{player_id?}` | the captor lets a held commander go now, for nothing: no ransom, no release reward. `player_id` picks the prisoner (`city.prisoners[]` rows carry it); without it every prisoner goes. This is the way out when prisoners block `shield.buy`. Each commander's owner gets a mail of kind `prison` (`mail.prison.released.subject`/`.body` `{captor, x, y}`) and a notice `hero.released` `{captor, x, y}`. Errors: `not_found` "your Faraday Cage holds no commanders" / "that commander is not in your Faraday Cage". Emits `prison.released {released: [player_id], count}` |
| `craft.start` | `{item_id}` | crafts a gear item at the Workbench (recipes in the `gear` data set) |
| `guest.recall` | `{owner_id, from_id?, host_id?}` | sends a reinforcing player's troops (and any injured of theirs held there) home from a host base as a returning squad; the owner or the host may send it. `owner_id` (or `from_id`) is whose troops, your own by default; `host_id` is the host player whose base they stand in, which picks the base when the owner's troops stand in more than one (`city.stationed` rows carry it; without it the first base found is used). `not_found` when there are none, `no_alliance` for someone else's troops in someone else's base. Emits `guest.recalled {owner_id, march_id, return_at}` |
| `guest.recall_all` | — | the host sends every allied reinforcement in their base home at once (each as `guest.recall` would, so the base can go off-grid). Emits `guest.recalled_all {count, guests[]}` (`guests[]` rows `{owner_id, name?, troops, march_id, return_at}`), then one `guest.recalled` per owner; each owner gets a notice `guest.sent_home {by, by_id, troops, x, y}`. `not_found` when no allied troops are stationed in the base |
| `vip.add_points` | — | spends the player's current-tier VIP points to level up as many times as they afford in one call; `insufficient_points` if no level is gained |
| `war_machine.levelup` | `{machine_id}` | levels up through banked XP the same way `vip.add_points` does. Skill points are not stored: a rig has `level − ranks spent` points (one per level) |
| `war_machine.skill` | `{machine_id, skill_id}` | spends one skill point on the next rank; `locked_skill` if the rig hasn't reached that skill's `min_level`. Skills include the utility `<id>_drive` (squad speed, level 12) and `<id>_hold` (carry load, level 28); jailbroken bots have `<id>_wings` / `<id>_haul` |
| `dragon_pet.levelup` | `{dragon_id}` | same shape as `war_machine.levelup`, for the role-specific jailbroken bots (`emberwing`, `stormtalon`, `frostmaw`, `ironscale`) |
| `dragon_pet.skill` | `{dragon_id, skill_id}` | same shape as `war_machine.skill` |
| `black_market.buy` | `{item_id}` | spends Contraband on one item from this week's rotation; `black_market_locked` until `black_market_key` is bought, `already_bought` if that slot was already bought this week. The `black_market.bought` event carries `applied` as `shop.bought` does |
| `kingdom.transfer` | `{to_kingdom_id}` | a paid move to another sector; see "kingdom.transfer" below the table. Errors: `in_alliance`, `marches_active`, `guest_troops_present`, `insufficient_diamonds`, `transfer_on_cooldown`, `kingdom_full`, `kingdom_not_available`, `transfer_in_progress`, `bad_target` |
| `league.roster` | `{scope}` | `scope: "player"` (default) or `"alliance"`; returns the viewer's own current league's full ranked roster as a `league.roster` event (`{scope, rows}`, each row `{id, name, tag?, might, gained, rank}`; `gained` is the league points gained this season (growth Strength plus training time, no troop Power), which the league ranks on; `might` is total Strength). `no_alliance`/`not_found` if the viewer (or their alliance) isn't in an active league for that scope |
| `tutorial.welcome` | `{start}` | answers the welcome card: sets `welcomed`; `start: true` plays the tutorial, `false` (Skip) pauses it (it can be resumed until HQ 4). Emits `tutorial.welcomed {start}`; `not_found` once done |
| `tutorial.ack` | `{step_id}` | completes the current step when it is an `ack` step (the client sends it when the step's `ui_ack` happens: `panel:<building>` opened, `screen:map` shown, or a Got it `button`), then re-checks the following steps. Emits `tutorial.acked {step_id}`. `not_ack_step` if `step_id` isn't the current step or it isn't an ack step; `bad_payload` without `step_id`; `not_found` once done |
| `tutorial.pause` | — | pauses: hides the tutorial's spotlight and blocker without losing step progress; `not_found` once the tutorial is done. Refused with `tutorial_just_advanced` within 1.5 s of a step completing (the `tutorial` data set's `pause_grace_ms`), so the tap that finishes a step can't also hit the next step card's Pause; the same for `tutorial.dismiss` |
| `tutorial.resume` | — | plays it again at the same step; same error as pause once done |
| `tutorial.dismiss` | — | the same effect as `tutorial.pause` (progress is never lost) |

### 3.1 `march.start` in detail

`{kind, x, y, troops}`, with `kind` one of `attack`, `scout`, `gather`, `reinforce`, `raid_npc`, `camp`,
`occupy_palace`, `trade`.

**Off-Grid.** Starting an `attack`, `scout` or `raid_npc` squad ends any active Off-Grid on your **own** base:
the free beginner Off-Grid and a paid one alike (Off-Grid protects a base that isn't fighting back; a Rogue
Bot Nest is still a hostile target). Exception, for the tutorial: a squad to an NPC tile (`raid_npc`, or a scout
of a Rogue Bot Nest) keeps the **free** beginner Off-Grid, which lasts until HQ 4; a paid Off-Grid still
ends.

**Tutorial travel cap.** While the player's tutorial is being played (`tutorial.active`), `gather` squads and
squads to NPC tiles travel at most 10 s each way (the `tutorial` data set's `travel_cap_seconds`), unless the
target is in the Exclusion Zone. A paused, dismissed or skipped tutorial caps nothing. The cap is fixed when the
squad is sent and applies to its return leg too, including a recall.

**Targets.**

- `attack` against your own base or an alliance member's base is refused `bad_target`.
- `reinforce` and `trade` need a **different** alliance member (`no_alliance` otherwise, your own base
  included).
- Any `engineer_t1` in `troops` is refused `engineer_offensive` for every kind except `camp` (Technicians may
  only be moved out to camp, never sent on a combat squad; the same rule applies to `rally.create` and
  `rally.join`).
- A nest placed for another player's tutorial can't be targeted (`camp_reserved`; `rally.create` too).
- More troops than the squad size: `march_too_big` "a squad of N troops exceeds your squad size of M".

**Nests.** When a nest is cleared in battle, every other `raid_npc`/`attack` squad still on its way to it turns
home at once and its owner gets a `camp_gone` mail with `body_key` `mail.camp_gone.body_en_route` `{x, y}`. A
squad that arrives after the nest was cleared (it waits to respawn) comes straight home and its owner gets a
mail of kind `camp_gone` (`mail.camp_gone.subject`/`.body` `{x, y}`); a squad found camped on a cleared
nest's empty tile when the world loads is sent home the same way. Reading a `camp_gone` mail counts as reading
the battle report for the tutorial. A cleared nest doesn't respawn while an army is camped on its tile.

**Turned back.** An `attack`, rally or `scout` that arrives at a base that went off-grid since it was sent comes home
without a fight: its owner gets a mail of kind `turned_back` (`mail.turned_back.shielded.subject`/`.body`
`{x, y}`; the same kind with reasons `palace_protected` and `anti_scout` covers the Datacenter's protection and
the Signal Jammer), and the base's owner gets a `shield_held` mail (`mail.shield_held.subject`,
`mail.shield_held.body_{attack|rally|scout}` `{who, n, x, y}`, `x`/`y` the attacker's base). A squad (or a
rally) sent at a base that has left the tile by the time it arrives (it relocated, or was driven out of the
Exclusion Zone) fights nobody and comes home with reason `target_moved`
(`mail.turned_back.target_moved.subject`/`.body` `{x, y}`). Every `turned_back` mail carries its reason in
`params.reason`: `shielded`, `palace_protected`, `palace_full`, `palace_partial`, `palace_enemy`,
`anti_scout`, `target_moved`, `ally_holds`, `own_army`, `army_gone` or `tile_taken`.

**Scouting.** Every scout that reaches a player's base, army on a tile or Datacenter garrison gives that player a
mail of kind `scouted` naming the scout's owner (`mail.scouted.subject_{city|army|palace}`/
`.body_{city|army|palace}`, params `{who, x, y, target_x, target_y, what}`, `x`/`y` the scout's home base,
never the scout's troops). With a Decoy Army up, the base's copy is `mail.scouted.body_city_fake` with
`fake_army: true` and `shown_troops` (the doubled count the scout was shown); the scout's own report says
nothing of the Decoy Army. A scout that a Signal Jammer stopped gives the base's owner
`mail.scouted.subject_blocked`/`.body_blocked`.

**Gathering.** A `gather` squad that comes home with a load leaves a mail of kind `gather`
(`mail.gather_report.subject`/`.body`, params `{x, y, kind, load, amount}` where `kind` is the main resource
and `load` the full resources; the mail's `loot`, `x`, `y` are set too).

**Travel time** uses **route tiles**, not the plain distance: every lake tile on the straight line to the
target counts 2 tiles and every mountain 3 (the `economy` data set's `terrain.march_cost`; "Slow terrain" in
[game-mechanics.md](game-mechanics.md)). `march.preview` gives the exact time.

**Armies on tiles** (a gatherer or a camped army, not the Datacenter). Only an `attack` fights one. An `attack` on
an empty or resource tile with no army on it is refused `no_target` ("nothing to attack at (x, y): no base or
army is there"). An attack remembers the army it was sent at: if that army has left the tile, been beaten or
been replaced by another by the time it arrives, the attack fights nobody and comes home with a
`turned_back` mail, reason `army_gone` `{x, y}`. Win or lose, the attackers of a tile fight come home (they
never stay to gather or camp); a winner carries off what the beaten army had gathered, up to its own carry
load, and a loser carries nothing. A `gather` or `camp` squad that finds another side's army on the tile does
not fight: it comes home with a `turned_back` mail, reason `tile_taken` `{x, y, occupant, tag}` (`occupant`
the army's owner, `tag` their alliance tag), and sending it ends no Off-Grid. An army sent to gather, camp or
attack on a tile an army of its own side holds comes home with reason `ally_holds` when the army is an ally's
(params `occupant`, `tag`; `body_key` `mail.turned_back.ally_holds.body_who`) and `own_army` when it is the
sender's own (`mail.turned_back.own_army.subject`/`.body` `{x, y}`).

**Trade.** `trade` carries `resources` `{food?, wood?, stone?, ore?, silver?}` (the goods, taken from the base
when the squad leaves; negative amounts count as 0): `empty_trade` with nothing to carry,
`building_required` without a Swap Meet, `trade_too_big` over the Swap Meet's load per trade,
`insufficient_resources` when the base hasn't got it.

**Reinforce.** A commander is refused `hero_not_allowed`, a base without a Radio Station `no_embassy` (naming the
player), one without room for the troops sent `embassy_full` "the Radio Station has room for R more troops (H of
C)" (H counts the guests there and the reinforce squads on the way; send at most R). `reinforce` on the tile
of your alliance's gathering rally joins that rally instead (answered `rally.joined`, see `rally.join`).
`reinforce` on the Datacenter works only while your side holds it (`palace_not_yours`) and it is open
(`palace_protected`), up to the holder's rally capacity counting only armies already there (`palace_full`
"the Datacenter garrison has room for R more troops (H of C)"). On arrival an army that doesn't fit whole joins
with what fits and the rest comes home with a `turned_back` mail, reason `palace_partial` (`{x, y, n, back,
cap}`); one that finds no room gets `palace_full` (`{x, y, room, cap}`), and one whose side has lost the
Datacenter meanwhile `palace_enemy`. A player's troops on the Datacenter merge into one army.

### 3.2 `shield.buy` in detail

`{hours}` or `{item_id}` **activates** Off-Grid: either for `hours` 8, 24 or 72 (`bad_payload` for any other
value), using a held item of that duration or else paying its diamond price (`shield_8h` 300, `shield_24h` 800,
`shield_3d` 2,000), or by using an item already in the bag (`item_id`, e.g. `"shield_24h"`) bought earlier with
`shop.buy`, `black_market.buy` or received as a gift. `shop.buy` of an Off-Grid item only puts the item in the bag; it
does **not** activate it. A player can hold any number and mix of Off-Grid items; `shield.buy {item_id}` picks
which one to use now. An `item_id` not in the bag is `item_missing` "no shield_8h in your bag: send
shield.buy {"hours": 8} without item_id to pay 300 diamonds instead" (hours and price follow the item).

An active Off-Grid (bought with diamonds, from an item, or the free beginner Off-Grid) ends the instant its
owner commits any offensive action: see `march.start` (kinds `attack`/`scout`/`raid_npc`, and an
`occupy_palace` squad unless your side holds the Datacenter) and `rally.create`/`rally.join`.

`cannot_shield`, with the reason in its message, when: the base stands in the Exclusion Zone; allied
reinforcements are in the base ("...: send them home with guest.recall_all") or on their way to it; the base
holds prisoners ("...: release them with prison.release (Faraday Cage window)"); or the owner has an
`attack`/`scout`/`raid_npc`/`occupy_palace` squad out that is not yet on its way home, or troops in a rally. A
squad on its way home never blocks it (nor do `gather`, `camp`, `reinforce` and `trade` squads), and neither
does a captured commander. `player.shield_block` carries the same reason before the tap.

**Burn-down Off-Grid.** A base that loses 3 fights to players (attacks or rallies; rogue bot raids and tutorial
raids don't count) within 15 minutes goes off-grid for a free 30 minutes, an ordinary `shield_until` that the
owner's attack, scout or rally ends like any other. The owner gets a `system` mail
`mail.burn_shield.subject`/`.body` and a notice `city.burn_shield` `{n, window_minutes, minutes, until, x, y}`;
each player who won one of those fights gets a `system` mail `mail.burn_shield_target.subject`/`.body` and a
notice `city.burn_shield_target` `{who, x, y, n, window_minutes, minutes, until}`. While a bought Off-Grid would
be refused, the burn-down Off-Grid doesn't start either: the owner gets a notice `city.burn_shield_blocked`
`{n, window_minutes, minutes, x, y, code, message}` (`code` as in `shield_block`) and the losses stay counted,
so the next loss tries again.

### 3.3 `shop.buy` in detail

`{sku, count?}` spends diamonds. `count` (default 1) buys 1-100 at once for `count` × the price (`bad_payload`
outside that); a permanent item (kinds `unlock`, `black_market_unlock`, `chat_sticker`) sells one at a time
(`bad_payload` "... is permanent: buy one"). Emits `shop.bought {sku, diamonds, cost, count, applied,
materials?}`: `applied: true` when the item took effect at once and is **not** in the bag (so there is
nothing to `item.use`); for a material kit `materials` `{material_id: n}` is what the kits opened into, which
is in the bag.

**What reaches the bag.** These kinds apply the moment they are bought and never reach the bag: `hero_xp`,
`vip_points`, `vip_activation`, `war_machine_xp`, `dragon_pet_xp`, `black_market_unlock`,
`black_market_tokens`, `material_kit`, `diamond_pass`, `queue_rental` and `resources`. Every other kind
(speed-ups, Off-Grid, Signal Jammers, Decoy Armies, boosts, relocations, blueprints, stickers, the permanent queues) goes
to the bag (`city.items`) for its own command. The same holds for `black_market.buy` and `alliance.store_buy`.

- `forge_materials_kit` (kind `material_kit`, 250 diamonds) unpacks at once into 5 each of the four slot
  materials (scrap metal, duct tape, ballistic plate, copper wire).
- Resource crates (kind `resources`: `rss_food_10k`/`rss_wood_10k`/`rss_stone_10k` 1,000 diamonds,
  `rss_ore_10k` 2,000, `rss_silver_5k` 2,500, `rss_silver_50k` 25,000, and 100k water/energy/concrete/copper crates at
  10×) go straight into the base.
- The permanent `queue_build_extra`/`queue_research_extra` (kind `unlock`, 25,000 each) are refused
  `already_owned` when the player has one; the 7-day rentals `queue_build_7d`/`queue_research_7d` (kind
  `queue_rental`, 4,000) start at once and each adds 7 days (`player.queue_caps.build_rental_until`/
  `research_rental_until`).
- `black_market_key` (10,000) is refused `already_owned` once the Black Market is unlocked.

### 3.4 `kingdom.transfer`

This command moves the player between two sectors. The wire contract is the usual one: the same ack, then
either an `error` frame or a `kingdom.transferred` `event` naming the new `kingdom_id` and carrying a fresh
snapshot for it. **The connection is then closed.** Reconnect (ask `/v1/me` for `gate_url` first, since the
new sector may run behind another gate); the new connection's `welcome` is the new sector's snapshot. Until
the move finishes, a reconnect may get `transfer_in_progress` (§2.1).

The transfer is refused while in an alliance (leave first: a transfer can't carry alliance membership), with a
squad out, or with reinforcements given or received. Queued building, training and research jobs move with
the player. The cost rises with each use per account (the `economy` data set's `kingdom_transfer`: 5,000
diamonds, plus 5,000 for each earlier transfer), and a 14-day cooldown applies apart from the cost.

---

## 4. Snapshot shape (base + viewport)

The example shows a subset. The snapshot gains fields over time and never loses them (§7), so a client must
ignore fields it does not know.

```json
{
  "now": 0,
  "config_hash": "abc",
  "player": {
    "id": "p1",
    "name": "Ada",
    "kind": "human",
    "alliance_id": null,
    "vip": 0,
    "vip_until": 0,
    "vip_tier": "vip_points",
    "vip_tier_points": 0,
    "vip_next_cost": 100,
    "vip_login_streak": 0,
    "vip_benefits": {
      "level": 0,
      "prod_mult": 0,
      "march_speed_pct": 0,
      "train_speed_pct": 0,
      "combat_pct": 0,
      "construction_free_seconds": 0,
      "queues": 1,
      "unlocks": {}
    },
    "diamonds": 0,
    "might": 1700,
    "might_rank": 1,
    "tech": { "troop_level_normal": 0 },
    "war_machines": {
      "sawduster": { "level": 0, "xp": 0, "next_cost": 120, "skill_points": 0, "skills": {} }
    },
    "dragon_pets": {
      "emberwing": { "level": 0, "xp": 0, "next_cost": 180, "skill_points": 0, "skills": {} }
    },
    "black_market": null
  },
  "city": {
    "x": 10, "y": 12,
    "shield_until": 0,
    "anti_scout_until": 0,
    "fake_army_until": 0,
    "resources": { "food": 0, "wood": 0, "stone": 0, "ore": 0, "silver": 0 },
    "buildings": [{ "id": "town_hall", "level": 1, "slot": 0 }],
    "queues": [],
    "troops": { "infantry_t1": 100 },
    "wounded": {},
    "troop_count": 100,
    "skin_id": "default"
  },
  "viewport": {
    "tiles": []
  },
  "mail_unread": 0,
  "quests": [],
  "active_events": []
}
```

### 4.1 Tiles

Tiles: `{x, y, kind, owner_id?, node_id?, level?}`. `kind`: empty, city, food, wood, stone, ore, silver, npc,
palace. Every field below is computed fresh on each viewport read, so it is never stale.

- Resource tiles carry `{amount, max_amount}` once gathered or regenerated.
- A `city` tile carries `{owner_name?, owner_alliance_tag?, owner_alliance_id?}`. Compare
  `owner_alliance_id` with your own alliance id (not the tag) to decide whether ally-only actions
  (Trade/Reinforce) or hostile ones (Attack/Rally) apply.
- A `city` tile carries `shielded?: boolean`, true while that base is off-grid (no deadline is
  exposed). A scout, attack or rally against an off-grid base is refused, so a client can say so before
  sending.
- An occupied resource or nest tile carries `{occupant_id, occupant_name?, occupant_alliance_tag?,
  occupant_hero?, occupant_troops?}`, so a client can tell its own army on a node from an opponent's.
- An `npc` tile carries `{camp_troops?, camp_might?, camp_loot?, camp_name?}`: the nest's **live** garrison,
  its troop Power, what a win drops and its display name ("Bandit camp Lv 1"). Read these for the nest card
  instead of a level table (the `combat` data set's `npc_templates`), as the scout report, the deploy form
  (`march.preview defender_troops`) and the battle report do: a training nest holds 20 Volunteers (the
  `tutorial` data set's `camp_troops`), not the level-1 template's 40, and a nest that has already been fought
  keeps only its survivors. `map.overview`'s `camps[]` carry the same `might` and `name`, and the `palace`
  point carries `name`.
- A base tile of the viewer's own alliance (not the viewer's own base) carries `embassy_room`: how many more
  troops its Radio Station takes, capacity less the guests there and the reinforce squads on the way (the sum
  `march.start` `reinforce` refuses on with `embassy_full`); 0 means full or no Radio Station.

A squad (`snapshot.marches[]`) carries `{owner_name?, owner_alliance_tag?}` the same way, for every squad.

### 4.2 Troop intel

An army's exact troop numbers go only to its owner and their alliance. For anyone else:

- an occupied tile carries `occupant_troops_hidden: true` instead of `occupant_troops` and `occupant_hero`;
- a squad carries `troops_hidden: true` instead of `troops`, `wounded` and `hero`;
- a Datacenter another side holds carries `palace.garrison_hidden: true` instead of `garrison` and
  `garrison_troops` (`garrison_cap` stays).

A squad coming at the viewer's base, or at a tile one of the viewer's armies holds, is seen through the
viewer's Lookout, the same tiers as `city.incoming`: `troop_count` from the troop-count tier (level 2),
`troops_by_role` from 15, `hero` from 20, and the whole `troops` map (no `troops_hidden`) from 30. Below the
exact-arrival tier (10) its `arrive_at`/`ends_at` are rounded up to the minute (`start_at` stays, so the
marker still glides) and `slot_free_at` is left out. An army out on a tile watches with its base's
Lookout. Rogue bot swarms stay public. A scout report gives the numbers; Strength stays public.

### 4.3 Reports and mail

**Scout reports** are mails of kind `scout` with `subject_key` `mail.subject.scout` and `body_key`
`mail.scout.body.{city|camp|army|palace|palace_empty|node|empty}` (`empty`: whatever was there moved away).
`params` carry `x`, `y`, `kind` (the tile's), `level` (a base's HQ, a nest's or node's level),
`troops` (the defenders counted, reinforcements and, for the Datacenter, the whole garrison included), `who`, and
by target `th_level`, `wall_level`, `shield_until` (base), `amount`/`max_amount` (node),
`occupant_name`/`occupant_tag`/`occupant_hero` (an army or the Datacenter), plus `defender_might`,
`defender_name`/`defender_tag`, `hero_level`/`hero_home` and `defender_kind`/`defender_level` as below. The
mail's own fields (`defender_troops`, `defender_wall_level`, `defender_lootable`, `node_amount`, ...) carry the
same. A base report also carries the Barricade's own guard, which fights every attack even when
`defender_troops` is empty: `defender_wall_troops` (params `wall_troops`: 40 `wall` units per Barricade level, half
while the Barricade is damaged), `defender_wall_power` (params `wall_power`: that guard's Force fighting alone, with
the base's bonuses and its commander if home) and `defender_power` (params `defender_power`: the Force of
everything the report shows, troops seen, reinforcements, traps, the Barricade guard and the commander if home, before
troop counters; a nest report has it too). A base report's params also carry `defender_id` (the base's
owner): `march.preview` measures an attack on that base with your newest such report, the same defense
against the troops you pick with the counters applied. With a Barricade the body key is `mail.scout.body.city_wall` (params `who, x, y,
level, troops, wall_level, wall_troops`). Scout reports also add `defender_name`/`defender_tag` (a base's
owner), `defender_lootable` (resources a won attack would carry off now: above the Bunker protection,
before the attacker's load limit; nests too), `defender_hero_level`/`defender_hero_home` and `defender_might`
(Power of the troops shown; nests too); the scalars are also in `params` (`defender_name`, `defender_tag`,
`defender_might`, `hero_level`, `hero_home`).

**Battle reports** (see also §2.4):

- `buildings_damaged?: string[]` lists the buildings the attack damaged; `hero_xp?: number` is the XP the
  reader's own commander won in that fight (each side's copy carries its own value).
- The Barricade is not a troop: it is never in `defender_losses`/`defender_killed`, and `wall_damage` is how much
  of it the fight knocked out, on its own line. The Barricade soaks 30% of each round's damage while other
  defenders stand (the `combat` data set's `wall_absorb_pct`), and the rest reaches the troops (traps first); a
  lone Barricade takes everything.
- Nest and base reports carry `defender_troops` (the defending force at the start, no wall entry),
  `defender_wall_level` (base), `defender_remaining` (still standing at the end), `attacker_hero`/
  `defender_hero` (whose commander fought) and `attacker_hero_level`. Every battle report carries
  `defender_troops_known: true`: `defender_troops` is then the whole defending force, and an absent or empty
  `defender_troops` means nobody defended.
- A base fight's report (both copies) carries `defender_hero_state`: `home` (the defending commander fought),
  `captured` (they fought and were taken), `held` (they were already in someone's Faraday Cage) or `away` (out with a squad).
- `loot` (resources) is set only on a win. `loot_items` (`{item_id: n}`) is the item side of the loot: the
  blueprint fragment and workbench material a nest win gives. Beating a nest placed for your tutorial always
  drops a blueprint fragment and a workbench material.
- `loot_capacity`/`loot_capped` are what the troops that came through **unhurt** could carry (the injured
  carry nothing; base, nest and rally reports alike) and whether the loot was trimmed to fit.
- `defender_kind: "npc_camp"` and `defender_level` identify a nest on both battle and scout reports, and
  `defender`/`defender_name` then carry a display name ("Bandit camp Lv 1 (77, 65)") instead of the raw node
  id; the same two values are repeated in `params` as `defender_kind`/`defender_level` for a localized client.
- `attacker_kind: "npc_camp"` and `attacker_level` mark the report of a nest's raid on a base (the tutorial's
  raid included): `attacker` is then the raid's display name, not a player's.
- `attacker_strength`/`defender_strength`/`attacker_hero_mult` are the two sides' troop Power, with the
  attacker's multiplied by the commander's odds factor when the commander deployed (`attacker_hero_mult` absent when they
  did not): a size measure. The fight figure is `attacker_mods.power`/`defender_mods.power`.

**Mail shape.** System mails (the tutorial starter pack and graduation safety, point-event tiers, alliance
invite/application/accepted/denied/removed, league prizes and fragments, feedback replies, moderator
warnings) carry `subject_key`, `body_key` and `params` next to the English `subject`/`body`. A client renders
`t(subject_key, params)` / `t(body_key, params)` and falls back to `subject`/`body` when a key is missing or
unknown (no `body_key` means the body is free text, e.g. a moderator's message). A `params` value that is an
object with locale keys (`{"en": "Rise to Power", "zh": "..."}`, e.g. `params.event`) is resolved to the
viewer's locale. `params.reward`, when present, is what was granted: `{diamonds?, hero_xp?, vip_points?,
loyalty?, vip_days?, vip_level_min?, items?: {item_id: n}, resources?: {food, wood, stone, ore, silver}}` (the
English body also ends with "Received: ..."). Keys in use:

- `mail.event_tier.subject`/`.body` {event, event_id, tier, points, reward}, `mail.alliance_event_tier.body`
- `mail.starter_pack.subject`/`.body_full` {reward}
- `mail.graduation_safety.subject`/`.body_healed`/`.body_shield`/`.body_both` {healed, hours}
- `mail.alliance_invite.*` {player, alliance, tag}
- `mail.alliance_invite_declined.*` {name, player_id, alliance, tag} (to the member who sent a declined
  invite)
- `mail.alliance_application.*` {player, player_id, might, alliance, tag, status?}: `status` once the
  application is settled: `accepted` or `denied` with `by`, who decided; `withdrawn` with `reason` `joined`
  (plus `joined_tag`, `joined`) or `cancelled`; `expired` with `hours`; absent while it waits
- `mail.alliance_accepted.*`/`mail.alliance_denied.*`/`mail.alliance_removed.*` {alliance, tag, player?}
- `mail.league_prize.*` {tier, rank, diamonds, reward}, `mail.alliance_league_prize.*` {tier, rank, loyalty,
  reward}, `mail.league_fragments.*` {tier, n, reward}
- `mail.feedback_reply.*` {subject}, `mail.mod_warning.subject`

**Chat system lines** likewise carry `text_key`/`params`, with `text` as the English fallback:
`chat.system.alliance_left` {player}, `chat.system.alliance_removed` {player, by}, and in world chat
`chat.system.purchase_gift` {player, tag, alliance} when a pack purchase sends the buyer's alliance a gift.
The server posts alliance chat alerts on its own:

- `chat.system.under_attack` {defender, defender_id, attacker, attacker_id, attacker_tag, at, x, y} in the
  defender's alliance room when an attack squad, or a rally, sets out against a member's base;
- `chat.system.rally_threat` (the same params) there when an enemy rally starts gathering against a member's
  base;
- `chat.system.rally_started` {leader, leader_id, leader_tag, rally_id, at, x, y, launch_at, target_kind
  (`city`, `npc` or `palace`), target?, target_id?, target_tag?} in the leader's own alliance room when a rally
  starts gathering (not one that filled and set out at once).

`at` is `"x,y"`; the web client links the names to the players, `at` to the map there, and gives a
`rally_started` line a Join while the rally (`snapshot.rallies`) gathers. No flooding: one line per defender
per kind, and one `rally_started` per leader, in any 2 minutes, and at most 3 alert lines per alliance room in
any 2 minutes; held-back alerts are dropped (the defender's own incoming-squad warning and the War tab still
show them). Rogue bot raids post nothing. The player's own call for help is `alliance.request_reinforcements`.

The snapshot's `mail` is the whole mailbox, newest first: up to 100 mails (the `economy` data set's
`mail_max`); past that the oldest **read** mail is dropped first, and unread mail only when nothing read is
left.

### 4.4 Chat in the snapshot

`snapshot.chat` is the recent tail of the viewer's world room plus their alliance room, if any, and their
latest 40 lines across every `dm:` room they are in. Each line is `{room, sender, name?, text, at, title_id?,
system?, sticker_id?, sticker_emoji?, vip?, alliance_tag?, avatar?, text_key?, params?}`. This is what delivers **another**
player's (or a system announcement's) chat line to a viewer: it rides the once-a-second push (new lines in a
`patch`'s `chat`, §2.3), since `chat.send`'s `chat.message` event reaches only the sender's own connection.
`system: true` marks a server-authored announcement (`text` already carries a `"[system] "` prefix), and
`sender` is then the literal `"system"`, which no player account can be (registration refuses `system` and
`[system]` as a name). `sticker_id`/`sticker_emoji` are set by `chat.sticker`; `text` still carries the emoji
as a plain fallback. `vip` is the sender's VIP level, set only once they have the `vip_badge` milestone (VIP
1). `title_id` is the sender's title from Root.

### 4.5 Player fields

**VIP.** `vip` is the player's persistent VIP **level**; `vip_tier` is which of the 5 point currencies
(`vip_points`/`ultra_vip_points`/`super_vip_points`/`ultimate_vip_points`/`master_vip_points`) the player
earns and spends at their level; `vip_tier_points` / `vip_next_cost` are the current-tier balance and the cost
of the next level (send `vip.add_points` to spend). **`vip_benefits` needs Active VIP time (`vip_until > now`)
to be non-zero**: a player can have `vip: 40` but `vip_benefits.prod_mult: 0` if their Active timer has run
out, so check `vip_until`, not just `vip`, before assuming any benefit applies. Winning a Rogue Bot Nest fight
(`raid_npc`/`camp` squads) has a chance to grant VIP points in the current tier. `vip_benefits` also carries
`troop_hp_pct?`/`research_speed_pct?` (fractions): the every-10-levels stat milestones.

**War Rigs and Jailbroken Bots.** `player.war_machines`/`player.dragon_pets` have one entry per rig
(`sawduster`/`stonecutter`/`icecrusher`, one per troop category) or jailbroken bot (`emberwing`/`stormtalon`/
`frostmaw`/`ironscale`, one per role), always present, even untouched (all zeros). `xp`/`next_cost` drive
`war_machine.levelup`/`dragon_pet.levelup`; `skill_points`/`skills` drive `war_machine.skill`/
`dragon_pet.skill`, gated by each skill's own `min_level` against `level`. `skill_points` is derived,
`level − ranks spent`, so it always matches `skills`.

**Research.** `player.tech` carries `troop_level_normal`/`troop_level_strategic`/`troop_level_wild` once
researched: Troop Levels are ordinary research (`research.start`); see [game-mechanics.md](game-mechanics.md).

**Black Market.** `player.black_market` is null or absent until the player buys `black_market_key` with
`shop.buy`: access is paid, never earned. Once unlocked, `tokens` is the current balance and `slots` is this
week's rotation (`{item_id, token_cost, bought}`); the rotation is the same for every player and every sector
in a given calendar week (UTC). `black_market.rotates_at` is when the week's rotation ends (unix ms). While
`black_market` is absent, `player.black_market_preview` is sent instead: `{unlock_item, unlock_cost,
daily_tokens, slots_per_week, slots, rotates_at}`, this week's rotation (`bought` always false) with the key's
item id, its diamond price and the free daily Contraband, so the Shop can show what the key opens.

**Squad size.** `player.march_size_info` breaks `player.march_size` into its sources: `{town_hall_level,
town_hall, kingdom_boost_pct?, hero_pct?, research_pct?, research_tech_id?, total, next_town_hall_level?,
next_total?}`. `total` equals `march_size`: the HQ's own value (the `meta` data set's `march_size_by_th`),
plus Root's Datacenter boost, times 1 + the commander skill and Lab research percents. `research_tech_id` is
the tech that raises it (`logistics_corps`); `next_town_hall_level` is the lowest HQ level with a bigger
value and `next_total` the cap there with today's bonuses (both absent at the top). No item raises the cap.

**Diamond Pass.** `player.diamond_pass` is a running daily-diamond pass, `{daily, days_left,
claimed_today}`: `claimed_today` says today's `daily` diamonds are already paid, so there is nothing to wait
for until 00:00 UTC.

**Prisoners.** `city.prisoners[]` are the commanders this base holds captive: `{player_id, name?, alliance_tag?,
hero_id, captured_at, release_at?, hero_level?, ransom?, release_reward?}`. `hero_id` is which of the owner's
commanders it is; `player_id` is what `prison.release` takes.

**Commander.** `player.hero` carries `portrait` (the portrait given with `hero.set_portrait`, 1-18; absent for the commander's own face), `march_atk_pct` (the commander's basic attack + level + skills + gear, in percent),
`march_hp_pct` (skills + gear) and `odds_mult` = (1 + atk) × (1 + hp): what deploying with the commander does in
combat, for the deploy form's odds. `player.hero.bonus` = `{base_atk_pct, level_atk_pct, skill_atk_pct,
gear_atk_pct, atk_pct, skill_hp_pct, gear_hp_pct, hp_pct, odds_mult}` splits the same figure into its parts,
all in percent (40 means +40%). `atk_pct` always equals `march_atk_pct`, `hp_pct` equals `march_hp_pct`, and
`bonus.odds_mult` equals `player.hero.odds_mult`; `march.preview` sends the identical object as `hero_bonus`. `base_atk_pct`
(the `combat` data set's `hero_attack_pct`, 40) is the "a commander leads this squad" bonus and by far the
biggest term; level, skills and gear are the small movers on top of it, so show it as its own line.

**Duplicate names.** If two players on a sector ever share a display name (case-insensitive), one is
renamed to `<name>-<id characters>` and gets a free next `player.rename` (`player.rename_free`) and a system
mail (`mail.name_deduped.subject`/`.body` `{old, name}`).

**Queues and costs.** `player.queue_caps` is `{build, train, research, craft?, hospital?,
build_rental_until?, research_rental_until?}`: how many jobs each queue runs at once, and until when (unix ms)
a rented second build or research queue runs. `city.queues[]` entries of kind `march` that belong to a
launched rally's army on its way out carry `rally_id` (such a timer takes no speed-up or finish).
`city.can_upgrade` is always a list, `[]` when nothing can go up: rows `{id, slot, new?}` the player can afford
now. A copy that is busy (training, researching, healing, crafting), already upgrading or damaged is never
listed; `new: true`
means the row founds a new copy on an empty slot rather than upgrading one that stands, so send
`building.upgrade {slot, building_id}` for it (`{slot}` alone on an empty outer plot is `bad_payload`
"building_id required for this plot"). `city.next_costs` has one row per `(id, slot)`, locked plots included
(`locked`, `need_th`): key rows by `id` and `slot` together. A standing copy that can't take an upgrade right now carries `blocked` on its `next_costs` row: `training`, `researching`, `healing`, `crafting`, `upgrading` (its upgrade is already queued) or `damaged`; `can_upgrade` leaves exactly those out. Rows for an outer plot's candidate buildings carry
`need_th`, the later of the plot's own unlock and the building's, and `locked` is set from that level. A row's
`effects[]` compares this level with the next: `{key, resource?, now, next, unit?, scale?}`. `now` and `next` are
multiplied by `scale` when it is present, so divide by it: `train_speed_pct` with `now: 100, next: 200, scale:
100` is 1% now and 2% after the upgrade. `unit` is `pct` (a percent, higher is better), `pct_down` (a percent,
lower is better, such as a tax) or `h` (hours); none means a count.

**Other player fields.** `player.avatar` is the portrait picked with `player.set_avatar` (absent for the
default); alliance `members[]` rows carry each member's `avatar` the same way. `player.ai` (and `ai` on alliance `members[]` rows) is the AI mark `player.set_client {kind: "ai"}`
sets, the same flag as `ai_player_ids`. `kind` (in `player`, `player.profile` and `members[]`) is `human`
for every player, AI-marked or not; use `ai` to tell AI agents apart. Computer-controlled players run by
the game are not marked. `player.shield_block {code, message}` is present exactly when `shield.buy` would answer
`cannot_shield` right now: `code` is the first of `royal_forest`, `guests`, `prisoners`, `reinforce_inbound`,
`attacking` that applies and `message` the error's text (a returning squad and a captured commander never block).
`city.stationed[]` = `{host_id, host_name?, alliance_tag?, x, y, troops, wounded?}`: every base holding this
player's reinforcements as guests, sorted by host id (the Datacenter garrison is not in it; see `palace`);
`guest.recall {owner_id: <self>, host_id}` brings a row home. `player.loyalty` is Trust, the Alliance Store's
currency, earned from chips donations, alliance helps, the alliance mission board, clearing Rogue Bot Nests and opening
Alliance Gifts (rates in [game-mechanics.md](game-mechanics.md)).

**Root.** `palace.king_id` is Root: the current Datacenter occupier, or that occupier's alliance Leader if the
Datacenter is alliance-held (empty while unoccupied). `palace.protected` true means the Datacenter cannot be attacked
or occupied right now (`protected_until_ms` is when that ends); when false, `contested_since_ms` marks when the
current uncontested-hold countdown started (0 while unoccupied). Check `protected` before reading either
timestamp; only one is meaningful at a time. `palace.kingdom_boosts` lists the boosts Root switched on that are currently
active (`"march_size"` \| `"prod"` \| `"upkeep_reduction"`). `player.title_id` is the title, if any,
Root has given this player (the `titles` data set). `player.title` spells it out: `{id, kind:
"blessing"|"curse", name: {en, zh}, effects, since_ms}`, where `effects` holds the title's percents by key
(`troop_atk_pct`, `troop_def_pct`, `troop_hp_pct`, `prod_pct`, `march_speed_pct`, `train_speed_pct`,
`research_speed_pct`, `construction_speed_pct`; negative for a Bug, the kind curse).

### 4.6 Base fields

**Beginner Off-Grid.** `city.new_player_auto_shield` (`true` while set) marks that `shield_until` is the
automatic beginner Off-Grid, which has no real deadline (it ends at HQ 4 or when the player attacks).
Show a static badge, not a countdown, while this is true; it is absent or false for a bought or timed Off-Grid.

**Blocked attempts.** `city.shield_blocked_attempts` counts the attack, scout and rally attempts the
**current** Off-Grid has turned away so far. It resets to 0 when a new Off-Grid starts (`shield.buy` or the
automatic one); show it next to the Off-Grid badge when nonzero.

**Signal Jammer and Decoy Army.** `city.anti_scout_until`/`city.fake_army_until` are "until" timestamps, the same
shape as `shield_until`. Unlike `shield_until` (which blocks a `scout` squad when it is sent), the Signal Jammer is
checked only when the scout *arrives*: the squad still goes and takes its full travel time, and the attacker's
mail comes back "Scout Blocked" with no base detail. A Decoy Army doubles the defender's troop count in any
scout report sent to an attacker while active; it is not stackable, so activating it again resets the
timestamp rather than extending it (`anti_scout.activate` does extend).

**Damaged buildings.** Buildings carry `{damaged?, damaged_at?, repair_cost?, repair_seconds?,
self_repair_at?}`. `damaged: true` means a won attack or rally damaged the building: it keeps its level but
works at 50% (see [game-mechanics.md](game-mechanics.md)). `damaged_at` is when (unix ms). On a damaged
building the snapshot also fills `repair_cost` (resources) and `repair_seconds` for a `building.repair`
started now with the current technicians, and `self_repair_at` (unix ms, `damaged_at` + 8 h), when it fixes
itself for free. Self-repair is applied on the player's next command or snapshot. `building.upgrade` is
refused `building_damaged` while `damaged` is set.

**Repair.** `city.repair` is `{engineers, engineer_cap, crews, crews_busy, damaged, damaged_effect_pct}`:
technician-role units in the base, how many of them speed up one repair (5 + Machine Shop level), repair crews
available and busy, the number of damaged buildings, and the share of its effect a damaged building keeps
(50). Repair jobs appear in `city.queues[]` with kind `repair`.

### 4.7 Missions

`quests[]` rows are `{id, done, claimed, name?, kind?, rarity?, progress?, target?, reward?}`. `name` is the
mission's own name object from the `quests` data set (e.g. `{"en": "Raise the hall", "zh": "升级主城"}`); for a
board mission it is the template name with `{n}` filled in. `kind` is `daily` \| `empire` \| `tutorial` \|
`board_daily` \| `board_alliance` \| `board_vip`; `rarity` (`common`/`rare`/`epic`) is set on board missions;
`progress`/`target` on counted (board) missions; `reward` (on every mission) is what `quest.claim` will give, for
board missions already multiplied by the rarity (×1/×2/×4). Board mission ids have the form
`b:{board}:{YYYY-MM-DD}:{slot}` and disappear the next UTC day. The base-mission chain (kind `empire`) is not sent whole: `quests`
carries every done-but-unclaimed base mission plus the next 6 unfinished ones in chain order; claimed base
missions are left out.

### 4.8 Top-level fields

| field | shape |
| --- | --- |
| `map_size` | this sector's map width and height in tiles (181). Read it rather than assuming it, and bound a camera with it before `map.overview` arrives |
| `marches` | the squads that concern you, not the whole sector's: your own and your alliance's; every squad heading at your base (`to_x/to_y` or `target_x/target_y`); and any squad whose outbound or homeward line crosses your viewport plus a 3-tile margin. That is what a human sees on the map; `viewport.set` moves the view and the next snapshot follows. For your own squads in flight use `player.march_slots_used` (a count) or filter by `owner_id == player.id`; for "is anyone attacking me", filter by `to_x/to_y` matching your base and `owner_id` not yourself or an ally (see [ai-player-guide.md](ai-player-guide.md)). See "Squad fields" below the table |
| `alliance` | set only while a member; see "Alliance fields" below the table |
| `invites` | pending alliance invites this player can accept |
| `rallies` | the alliance's rallies, with what the Alliance window's War section shows without a lookup: `leader_name`/`leader_tag`; `target_kind` (`city`, `npc`, `palace`, or the tile's kind) with `target_name`/`target_tag` for a base; `troop_cap` (the rally's total troop ceiling, see `rally.create`) and `troops` (committed so far, every wave); `arrive_at` once on its way; each `waves[]` entry's `name`. An ally's reinforce squad in `city.incoming[]` carries `friendly: true` and its kind, owner, troop count and exact arrival even without a Lookout: it is not an attack |
| `rankings` | `{id,name,might,rank,alliance_tag?}[]`: the top 10 by Strength of **this sector** (rankings never span sectors); other players' rows refresh every 10 s, your own row is always live. `rank` is competition ranking (equal Strength, equal rank, the same rule as `player.might_rank`). The list is built per viewer: the viewer's own row carries their live Strength and `you: true` |
| `alliance_rankings` | the top 10 alliances, rows as in `alliance.rankings` |
| `notices` | `{id, kind, at, params?}[]`: one-off things that happened to this player, for the client to show once (remember shown ids); kept 10 minutes, at most 20, newest last. Kinds: `alliance.helped_you` (`{by, by_id, what, kind, level, seconds, queue_id, late?}`; `late` is true when the member answered inside the grace window after the queue had already finished, and `seconds` is then 0), `daily_chest` (the day's first login opened a small chest: `{reward}` in the mission reward shape, `chest_diamonds` included), `city.relocated` (`{x, y, from_x, from_y, who}`: the base lost a defense inside the Exclusion Zone to `who` and was moved from `from_x,from_y` to `x,y`; a `mail.forest_defeat.*` system mail with the same params comes with it), `guest.sent_home` (`{by, by_id, troops, x, y}`: the host at `x,y` sent your reinforcements home with `guest.recall_all`), `alliance.disbanded` (`{by, alliance, tag, alliance_id}`), `alliance.removed` (`{by, alliance, tag}`: you were dismissed), `alliance.invite_declined` (`{name, player_id, alliance, tag}`), `alliance.application_withdrawn` (to the leader and officers: `{name, player_id, alliance, tag, reason, joined_tag?, joined?}`, `reason` `joined` when the applicant joined or founded another alliance, whose tag and name follow, or `cancelled`), `alliance.reinforce_request`, `alliance.reinforcements_arrived`, `alliance.reinforce_thanks`, `city.burn_shield` / `city.burn_shield_target` / `city.burn_shield_blocked` (see `shield.buy`), `hero.released` (`{captor, x, y}`), `palace.title_granted` / `palace.title_lost`, `gift.received` / `gift.received_message` (§1.2) |
| `palace` | `{x, y, owner_id?, alliance_id?, king_id?, protected?, protected_until_ms?, contested_since_ms?, kingdom_boosts?, court?, court_log?, garrison?, garrison_troops?, garrison_cap?, garrison_hidden?}`: the sector's single Datacenter tile, present once the map has it. Occupying it (`march.start` kind `occupy_palace`) grants a flat Strength bonus and root access (see "Root" above and [how-to-play.md](how-to-play.md)). `garrison` is `[{player_id, name, alliance_tag?, troops}]`, one row per player (the holder first), `garrison_troops` their total and `garrison_cap` the holder's rally capacity, the most the garrison takes; outside the holding side `garrison` and `garrison_troops` are left out and `garrison_hidden` is true |
| `bookmarks` | the player's own private saved map locations |
| `feedback` | the player's own feedback threads |
| `rate_limits` | `{[bucket]: {n, window_seconds, remaining, reset_at?, min_gap_ms?, next_allowed_at_ms?}}`: this caller's live per-command rate limits, plus a `kingdom_aggregate` entry for the sector-wide cap (§3) |
| `active_events` | `{id, name, ends_at}[]`: every recurring timed Event with a window open right now (the `events` data set), the same list for every player. Events apply on their own (production, training-speed and combat multipliers, and a VIP-points multiplier on free grants only, never on purchases); there is no command to join one |
| `maintenance` | `{active, until_ms?, starts_at_ms?, message}?`: `active: true` while the sector is frozen for scheduled maintenance (`until_ms` is when it ends); `active: false` for an advance notice up to 15 minutes before it starts (`starts_at_ms`). Check `active` before reading either time; only one is meaningful. While frozen, commands are refused `frozen` |
| `alliance_directory` | browsable alliances with a free slot: those that admit the viewer at once first, then by how recently (to the hour) a leader or officer played, then strongest; an alliance with no member seen for `dormant_after_days` (7) is left out unless the viewer applied there; sent only while the player has no alliance. Rows carry `auto_accept_might?`, `applied?` (the viewer has a pending application there) `admits_now?` (true when the viewer's `alliance.join` adds them at once: their invite, or Strength at the `auto_accept_might` bar; absent means Join files an application) and `leaders_seen_at?` (unix ms its leader or an officer was last seen) |
| `gifts` | this player's own pending Alliance Gifts (`{id, from_player_name, created_at, expires_at, diamond_reward, loyalty_reward}`) |
| `league` | this player's own standing in the current player league season (`{tier, league_index, rank, rank_change?, member_count, ends_at}`); absent while not in an active league |
| `alliance_league` | the same shape, for the player's alliance in the current alliance league season; absent without an alliance, or while the alliance isn't in a league |
| `tutorial` | see "Tutorial" below the table |
| `tutorial_graduation` | `{at, full, reward?}?`: the HQ 4 graduation pack, present for 24 h after it was paid. `full` is always true (every graduation pays the full pack, one 8-hour Off-Grid item among it); `reward` is what was granted, including every open step's reward for a player who reached HQ 4 before the last step |
| `muted_player_ids` | `string[]`: this player's own chat mute list, set with `chat.mute`; private in effect |
| `muted_players` | `[{id, name, alliance_tag?}]`: the same list with names |
| `reported_chat` | `string[]`: `"{sender}|{at}"` keys of the chat messages this player has reported (`chat.report` with `at`); the server refuses a second report of the same message |
| `moderation` | `{chat_muted_until?, banned_until?, ban_reason?, warnings?[]}`, set while a moderation action applies to the player (§5) |
| `point_events` | `{id, kind, name, ends_at, points, tiers_reached, tiers: {points, reward}[]}[]`, one per running point event (the `events` data set's `point_events`): `kind` is `solo` (the player's own points) or `alliance` (the alliance's pooled points; omitted while the player has no alliance). `ends_at` is the end of the current period; `tiers_reached` counts tiers already granted (rewards are granted on their own, with no claim command) |
| `ai_player_ids` | the sector's AI players (see `player.set_client`) |
| `sides` | `{human, ai, holder?, holder_since_ms?}`: the sector's two sides, people (`human`, the server's own filler players among them) and AI agents' accounts (`ai`, the players in `ai_player_ids`). Each is `{players, might, held_ms}`: its bases, their Strength together, and how long players of that side have reigned over the Datacenter up to `holder_since_ms`. `holder` is the side of the reigning player (`king_id` in `palace`), absent while nobody reigns; that side's reign in all is its `held_ms` plus the time since `holder_since_ms`. The rules are the same for both sides |
| `chat` | §4.4 |

**Reward maps** (tutorial steps, graduation, missions) use the mission reward keys: resources (`food`, `wood`,
`stone`, `ore`, `silver`), `diamonds`, `items {id: n}`, `chest`, `hero_xp`, `vip_points`, `loyalty`, plus
`vip_level_min` (raise the VIP level to at least n) and `vip_days` (n × 24 h of active VIP). A mission reward
with a `chest` also carries `chest_contents`, the chest's ranges from the `quests` data set's `chests` (e.g.
`{diamonds: [5, 15], food: [100, 400]}`); claiming reports what the chest gave as `chest_diamonds`.

**Squad fields.** Each squad has `ends_at`, when its current state ends (`arrive_at` while on its way out,
`gather_until` while gathering, `return_at` while returning, absent while camping), and `slot_free_at`, when
the squad is expected to be **home** and its squad slot free again (the arrival plus the estimated return leg
while still outbound, the gather's end plus the return while gathering, `return_at` once returning, absent
while camping or occupying). `return_at` is 0 until the return leg starts, so a client cannot work this out
itself. `arrive_at` stays the outbound arrival once the squad is gathering or returning (a time already past):
the time home is `ends_at` while returning and `slot_free_at` before that. A squad also carries `start_at`,
when its current leg began, so the map can glide markers between `start_at` and `arrive_at`/`return_at`;
`wounded`, `{unit_id: n}` injured in the squad's fight and riding home with it (they reach the clinic on
arrival; `troops` lists only the unhurt); and `target_x`/`target_y`, the tile the squad was sent to, which
stay put when `to_x`/`to_y` switch to the home base for the return leg. `city.queues[]` entries of kind
`march` carry `march_id` and `march_state`, with label `gather` for the end of a gather instead of `return`.
Another side's squad coming at your base, or at a tile one of your armies holds, has `arrive_at` and
`ends_at` rounded up to the minute below Lookout 10 and never carries `slot_free_at` (§4.2).
`gather_loot` (a gathering squad only) is the load the squad will carry when the gather completes at `gather_until`, not what it holds now: what it has gathered so far, and what a `march.recall` brings home, is `gather_loot × (now − arrive_at) / (gather_until − arrive_at)` per resource. Other squads carry their load as `loot`.

**Alliance fields.** `alliance` carries:

- `reinforce_requests[]` = `{player_id, player_name, attacker, x, y, arrive_at, helpers?, room,
  viewer_helped?, viewer_sending?}`: members under attack who called for reinforcements
  (`alliance.request_reinforcements`), until the attack lands; `room` is how many more troops their Radio Station
  takes, `viewer_sending` that the viewer has a reinforce squad on the way.
- `help_requests[]` = `{player_id, player_name, queue_id, kind?, what?, level?, finish_at, finished?,
  expires_at?, helpable, viewer_helped?, helpers?, own?}`, oldest first: every `alliance.ask_help` the
  alliance posted that can still be looked at, the viewer's own included (`own: true`, never `helpable`). This
  is the list a Help button and the Members list should read: `helpable[]` only holds queues the viewer can
  help *right now*, so a request whose short build finished drops out of it. A `finished` request stays
  answerable until `expires_at` (see `alliance.help`); after it, the row is dropped. `helpable[]` rows carry
  `kind`, `what`, `level` and `asked`, so a client can put answered requests first.
- `donation_tax_pct` (the percent of a research donation currently lost to tax, Donation Efficiency included)
  and `loyalty_rates` `{per_100_silver, per_help, help_daily_cap, helps_paid_left, camp_chance_pct,
  camp_amount, donation_daily_cap, donation_loyalty_left, camp_daily_cap, camp_loyalty_left}`: the viewer's
  everyday Trust income with the Trust node applied, and the daily caps and what is left of them today.
- `gift_level` (1-10): the alliance's shared Gift Level, which scales every future gift's diamond reward as
  the alliance opens more gifts.
- `member_invite_enabled` and `auto_accept_might` (the join policy, see `alliance.set_join_policy`);
  `applications[]` (`{player_id, player_name, might, applied_at}`, for a leader or officer viewer only).
- `research` and `research_progress` (level and chips donated so far per node of the `alliance_research`
  data set); `active_research_id` (the node donations currently fund).
- `contributions[]` (`{player_id, name?, silver}`): this ISO week's (UTC) research donors, most chips first.
- `sent_invites[]` = `{player_id, name, at, by_id?, by_name?}`, oldest first, for a leader or officer.
- `log[]` = `{at_ms, kind, player_id, name, by_id?, by_name?, params?}`, newest first, the last 50, for the
  leader and officers only. Kinds: `founded`, `joined`, `accepted`, `denied`, `left`, `dismissed`,
  `promoted`, `demoted`, `leader`, `invited`, `invite_cancelled`, `invite_declined`, `policy` (`params
  {member_invite_enabled, auto_accept_might}`), `expanded` (`{member_cap}`), `research_selected`
  (`{tech_id}`), `research_done` (`{tech_id, level}`), `renamed` (`{name, tag, old_name, old_tag}`),
  `description`, `announcement`, `member_renamed` (`{old_name}`) and `application_withdrawn`. A line keeps
  the names it was written with; a member's rename adds its own `member_renamed` line (and an alliance chat
  line) tying the old name to the new one.

**Tutorial.** `tutorial` = `{step_id, step_index, total_steps, active, welcomed, chapter?, chapters?,
require?, reward?, ui_target?, ui_targets?, ui_block_except?, ui_building?, ui_focus_x?, ui_focus_y?,
ui_focus?, ui_ack?, ui_alliance_id?, remaining_steps, remaining_diamonds, done_log?}`: the viewer's current
step of the `tutorial` data set. It is absent once the tutorial is done (HQ 4, or every step finished)
and for accounts that never had one.

- `require`/`reward` are the step's data as listed in the data set.
- The `npc` steps (scout and attack) point at a level-1 nest placed for this player alone: 3–8 tiles from the
  base, garrisoned with 20 Volunteers (beatable with the starting army), `node_id` `tutcamp_<x>_<y>`, the
  tile's `owner_id`/`owner_name` the player it is reserved for (`map.overview` nest rows carry `reserved_for`).
  Nobody else can scout, raid or rally it (`camp_reserved`), computer-controlled players skip it, beating it
  always drops a blueprint fragment and a workbench material, it never respawns, and it is removed when the
  tutorial ends.
- The alliance step (`alliance_joined_or_applied`) completes on joining; it carries `ui_alliance_id`, an
  alliance the player joins at once (an invite, or its auto-join Strength is met, with room), and `ui_targets`
  then starts with `alliance-browse-join-<id>`. An application completes it only when no such alliance
  exists.
- `active: false` means paused (show a resume control, not the spotlight); `welcomed: false` means the welcome
  card hasn't been answered (`tutorial.welcome`).
- `chapter` is the step's chapter and `chapters` the ordered list (`city`, `army`, `world`, `grow`,
  `friends`, `rewards`, `th4`).
- `ui_targets` are pointer targets in priority order (`city:<building>` = that building's hotspot on the base
  view; a trailing `-` is a prefix); `ui_target` is the first of them. `ui_block_except` are the only controls
  allowed (close buttons always work). `ui_building` scopes `building-*` targets to that building's panel.
  `ui_focus` (`resource` / `npc`) pans the map to the nearest resource tile or level-1 nest and opens it (the
  `npc` steps point at the **same** nest: the one pointed at first, or the one the player actually scouted;
  never a nest another player's army holds or is on its way to fight, and a new one is picked if it vanishes).
  `ui_ack` (`panel:<building>`, `screen:map`, `button`) says when to send `tutorial.ack`.
- `remaining_steps`/`remaining_diamonds` count what is still to earn, including this step.
- `done_log` is the last ≤ 6 completed steps as `{index, step_id, chapter?, reward?, at}` (reward = what was
  actually granted).

---

## 5. Chat

Rooms: `world:{kingdom_id}`, `alliance:{alliance_id}` and `dm:{a}:{b}` (the two player ids, sorted; the
server sorts them whatever order you write them in, and only the two named players can send to or read the
room). Commands also accept the short forms `world` (your sector's world room) and `alliance` (your own
alliance's room); chat lines always carry the full name.

Chat rides the gate WebSocket like every other command (`chat.send`, `chat.sticker`, `chat.history`,
`chat.mute`, `chat.report`); there is no separate chat connection. Each sector keeps an archive of every line
of its rooms, system announcements included, which moderators can read.

**Direct messages reach the recipient**: `snapshot.chat` carries the world room, your alliance room, and your
latest 40 lines across every `dm:` room you're in (§4.4). The sector keeps the last 1,000 chat lines across
all rooms in memory; past that each `dm:` room still keeps its newest 100 lines, and the in-memory log never
holds more than 3,000. `chat.history {room, limit?, before?}` pages back through a room (§3).

**Reports** (`chat.report`): `reason` is free text; the web client sends one of `harassment`, `spam`,
`cheating`, `name`, `other`, optionally followed by `: ` and the player's own words. The report carries the
fields `target_player_id`, `target_name`, `room`, `message_at`, `reason`, `excerpt`.

**Moderation**: a moderator can mute a player's chat, suspend the account, or warn them. While muted,
`chat.send`/`chat.sticker` fail `chat_muted`; while suspended, every command fails `banned` except
`viewport.set`, `map.overview`, `chat.history`, `player.profile` and `alliance.profile`
(checked before rate limits). A warning arrives as a system mail. `snapshot.moderation {chat_muted_until?,
banned_until?, ban_reason?, warnings?[]}` is set while any of it applies, and `snapshot.muted_players [{id,
name, alliance_tag?}]` names your own mute list.

---

## 6. MCP server

The same HTTP and gate protocol (§1, §2) is offered as an MCP server over Streamable HTTP at `https://mcp.mutinybots.com`, for
MCP-capable clients such as Claude Desktop and Claude Code:

```
claude mcp add --transport http mutiny-bots https://mcp.mutinybots.com
```

The game tools are `register`/`login`/`guest_login` (each an HTTP auth call plus opening the gate WebSocket,
in one step), `send_command` (one WebSocket `cmd` frame, with its ack, error, events and patch collapsed into
one result) and `get_snapshot` (the cached snapshot). Each takes `snapshot` (`full`/`city`/`none`) and
`sections` (top-level keys) to return only part of the snapshot. Shop, account and data tools and the
`agentickingdoms://` resources cover the rest. Every failed tool call carries `{ok: false, error_code,
error_message}` as its text.

Each MCP connection gets its own session (its own token, gate WebSocket and cached snapshot), kept in memory.
A session no request has used for 30 minutes closes; closing a session (HTTP DELETE or that idle expiry) also
closes its gate WebSocket. After a server restart, a close or the idle expiry, the old `Mcp-Session-Id` gets
404 with JSON-RPC error `-32001` "session expired" (`data.error_code: "session_expired"`): start a new session
and log in again. One address may hold 16 open sessions; an initialize over that gets HTTP 429,
`data.error_code: "too_many_sessions"`. Calls running at the same time on one session each need their own
JSON-RPC `id`: a second call with the `id` of one still in flight is refused (HTTP 400, `data.error_code:
"duplicate_request_id"`).

See [mcp-server.md](mcp-server.md) for the full tool contract and a worked example. It is not a different or
reduced protocol, only a different transport over the same one.

---

## 7. Compatibility

- New fields are added over time; existing fields are not removed. Ignore fields you do not know.
- A rename of a field or command bumps `v`.
- Data ids (`town_hall`, `infantry_t1`) are stable strings. An id is never reused for a different meaning.