# Protocol: Agentic Kingdoms

> **The game opens on October 15, 2026.** 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 Agentic Kingdoms 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.agentickingdoms.com` is the HTTP API and `https://mcp.agentickingdoms.com` the MCP server. Each kingdom's server has its own
WebSocket gate (`wss://g1.agentickingdoms.com` is one example): the API names the gate of the account's own kingdom 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 kingdom when that kingdom takes new players (else as usual; `home_kingdom_id` says which). Display names are unique per kingdom, case-insensitive: `409 name_taken` when the kingdom 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 kingdom (`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.agentickingdoms.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 kingdom 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.agentickingdoms.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
kingdom 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 kingdom first and create nothing when they
answer it; 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 kingdom, 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 Warehouse 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 Town Hall 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 Town Hall 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 kingdom runs on, for example `wss://g1.agentickingdoms.com`. Kingdoms on different
servers have different gates, and a kingdom 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

**Kingdom still starting.** After a server restart the kingdoms start in parallel, so for a few seconds the
player's kingdom 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 kingdom 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 kingdom moving to another server.** When the kingdom 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 kingdom transfer still finishing.** `code:"transfer_in_progress"`, `retry_after_ms` 3000. The player is
  between two kingdoms 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 kingdom that came back on another server is found there.

**Wrong gate.** Kingdoms run on several servers, each with its own gate, and the HTTP API names the gate of
the player's kingdom as `gate_url` in the login, register, guest and `/v1/me` answers. Connect there. A gate
that does not serve the player's kingdom (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 city 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 Might 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 city-attack, rally (every member's and the defender's), Palace and
tile-fight report carry `replay` (a single raid on an NPC camp 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 Wall'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 city defense, a rally defense, a Palace 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 Palace garrison its holder's, a city
  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 hero's attack, its damage cut when defending and its health, and the
  Embassy.
- `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 Wall'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 might, a size measure and not the fight figure (that is
`power`, which the web client's march window and report show): troop might, times the side's hero
factor when its hero fought (the attacker's, a defending army's on a tile, or the Palace holder's;
`attacker_hero_mult` is the attacker's factor, absent when the hero did not march); a defended city's and a
camp's are plain troop might. Rally and Palace reports add `attacker_armies` / `defender_armies`, one row
`{player_id, name, alliance_tag, sent, killed, wounded, remaining}` per army. A city lost inside the Royal
Forest sets `relocated` on both copies, and `relocated_x`/`relocated_y` (where it went) on the defender's.

A bandit 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 kingdom. 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.

**Kingdom-wide cap.** A second, shared limit is checked before the per-player one: it bounds the total
command rate of every player in the kingdom. 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 kingdom is loaded.

**Kingdom capacity.** Each kingdom 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
kingdom with room; when none has room, a new kingdom is opened. A kingdom's map is 181×181 tiles (the
`meta` data set's `map_size`).

**`insufficient_resources` names what is short.** Every command that spends city resources (building upgrade
and repair, training, healing, research, crafting, trade, founding an alliance, the alliance research
donation, the hero ransom) answers "not enough resources to `<action>`: N `<resource>` short (need X, have
Y)", one clause per short resource in food, wood, stone, ore, silver order, 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 city (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 kingdom for the minimap and Kingdom zoom. `rows[y]` has one character per tile: `.` empty, `c` city, `f` food, `w` wood, `s` stone, `o` ore, `$` silver, `n` camp, `W` palace, `l` lake, `m` mountain; `levels[y]` one digit per tile (a node's or camp's level, `0` for none, `9` for 9+). `cities[]` is `{x, y, owner_id, name?, alliance_id?, alliance_tag?, level, shielded?, might?}` for every city; `camps[]` `{x, y, level, might?, name?, reserved_for?}`. `march_cost` is `{lake, mountain}` (slow terrain); `forest_radius`, and `forest_min_th` (the Town Hall a city needs to teleport into the Royal Forest). 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 camps 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 Palace, 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 Royal Forest 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-march cap applies to both legs; `tiles` the route in plain-tile equivalents and `distance` the Chebyshev distance. Troop might, a size measure (the fight figure is `attacker_power` below): `attacker_might` (might of the troops in the payload) and, when the target is an NPC camp, `defender_troops` (its garrison), `defender_might` and `defender_level`; `hero_mult`, the factor the hero adds to `attacker_might` when the payload has `hero: true` (level, skills and gear, exactly as combat applies them; 1 without the hero), 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 hero bonus breakdown, identical to `player.hero.bonus`), and for a camp 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 camp's **live** garrison. `target_shielded: true` when the target is another player's city with a Peace Shield up, `target_protected: true` when it is the Palace in its protection window: `march.start` would refuse an attack on either. On any tile but a city, an army standing there (gathering or camped, or the Palace'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` march 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 Palace'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' fighting power with the sender's own bonuses (research, VIP, boosts, title, War Machines, Dragons, the hero when `hero: true`): the `power` of a battle report's `attacker_mods`, sent in full as `attacker_mods`. Against an NPC camp, whose garrison is public, `defender_power`/`defender_mods` are the camp's, both sides with the troop counters applied, and `estimate` is false. Against a rival city (not yours or your alliance's) that you have a scout report of (your newest one still in your mailbox, of the city's current owner: the report's `params.defender_id`), the preview measures the defense that report saw (its troops, its Wall guard and its hero if it was home, with the city'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 hero home; absent without a hero). 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 march 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 city with a Wall and no scout report of yours still shows its Wall guard, which fights every attack even with no troops home: `defender_wall_troops` (40 `wall` units per Wall level, half while the Wall is damaged), `defender_wall_power` (that guard's power fighting alone, with the city's bonuses, hero left out), `defender_power` (the same figure) and `defender_power_floor: true` (the real defense is at least this; troops and hero 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 Market lets one trade carry) and `trade_delivered` (the cargo after the Market'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 Town Hall's current level: every building (the Town Hall itself exempt) is capped at the Town Hall's level. `prerequisite_required` when a Town Hall upgrade from level 5 or higher finds its Wall, Barracks, Academy, Hall of War or Warehouse below the Town Hall'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 Town Hall 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 engineer, 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 engineer-role unit in the city), `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 Warehouse cap is collected; the rest stays waiting on the building. Everything else (quest, tutorial and event rewards, purchases, gathered loads, battle and camp loot, trades, ransoms) lands in full above the cap; the cap only stops production (collecting and the Town Hall's silver). `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 march speed-up (`speedup_march_1m`, kind `march_speedup`) only on a march's entry (`wrong_queue` elsewhere; the item stays in the bag). On a march's queue entry (`city.queues[]` with `march_id`) it is `march.speedup` for that march, with all of its rules: a march on its way **out** takes only march speed-ups (`march_speedup_only`), and the army of a marching rally none (`rally_march`). The march'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 march on its way out that holds any item other than a march 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 march: every march timer (outbound, gathering, return) is refused `march_finish` "a march can't be finished with diamonds: use march speed-up items (march.speedup or queue.speedup)"; a rally's gather timer `rally_timer`, one army of a marching rally `rally_march` |
| `research.start` | `{tech_id}` | researches the tech's next level; the silver cost is paid up front. Errors: `unknown_tech`, `building_required` (no Academy), `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 (a Spy is 10 food and 20 silver), paid up front. `insufficient_resources` names what is short |
| `hospital.heal` | `{troops?}` | spends food at once and moves wounded troops into a hospital queue entry (`city.queues[].kind == "hospital"`); the troops return only when that job finishes. Duration = each wounded unit's own `train_seconds` × the `combat` data set's `heal_seconds_per_train_second_pct` (50%), summed across every wounded type in the batch. One heal at a time (`busy_queue` otherwise); troops wounded 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 city's own wounded, each count clamped to what is wounded; food and time are computed for that subset and the rest stays wounded. A reinforcing army's wounded go to its owner's own Hospital 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 wounded 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 march home |
| `march.speedup` | `{march_id, item_id}` | takes the item's time (its `seconds` in the `packs` data set) off the named march's current leg. `march_id` is required (`bad_payload` "march_id required"); `not_found` for a march that isn't yours. **Which item works depends on the march's state:** a march on its way **out** (`state: "marching"`) takes only the March 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 march speed-up" and stays in the bag. A **returning** march (and the gather timer, while `gathering`) takes either kind. The army of a rally on its way out takes none (`rally_march`: a rally marches as one); once the rally has fought, each army's way home takes speed-ups like any returning march. The one exemption: while the tutorial's own march speed-up step is the player's current step, a general speed-up also works on an outbound march. Why: an attack on its way keeps its target's time to react (to shield, reinforce or move away), while bringing an army home stays cheap. Diamonds never finish a march (`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 a shield, which refuses the scout march when it is sent); extends an already-active window |
| `fake_army.activate` | `{item_id}` | doubles this city'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 march is marching 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 Palace, or is too close to water, a mountain or the map's edge; `city_too_close` next to another city; `forest_min_th` for a Royal Forest tile below Town Hall `palace.forest_min_th` (10). Moving into the forest ends any shield |
| `alliance.create` | `{name, tag}` | `name` and `tag` must both be unique in the kingdom, 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 Might 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 Might 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 kingdom (exact, else case-insensitive), for players who never see an id: `not_found` "no player named X in this kingdom". `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` Loyalty (the `economy` data set's alliance block: 5, times the Loyalty 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 Loyalty 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 Spearman", "X asks for help: Town Hall 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 city against the soonest attack marching on it (a player's attack or a bandit raid). Posts a system line in alliance chat (`text_key: chat.reinforce_request`, `params {name, attacker, x, y, arrive_at}`), gives every other member a notice `alliance.reinforce_request` with the same params, 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 Loyalty (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 Embassy, which unlocks at Town Hall 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 Might); 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 Might (the members' Might 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 a guild-expansion token to raise the member cap by 5 (`member_cap_per_token`); `alliance_cap_max` (token 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 Loyalty per silver donated (before tax): 10 per 100 silver (`donation_loyalty_per_100_silver`, the `economy` data set's alliance block), times the Loyalty 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. Loyalty 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 Loyalty bonus and raising the alliance's shared Gift Level; `no_gifts`/`not_found` on empty/unknown |
| `alliance.store_buy` | `{item_id}` | spends Loyalty 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}` | King 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 curse) 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}` | King only; `name` is `march_size` \| `prod` \| `upkeep_reduction` |
| `battlemark.add` | `{x,y,note}` | an alliance-shared attack-target mark on a city, a camp, 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 base plus a share per Hall of War 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 marching. The leader's own wave is within their march 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) drops any active shield on the mover's own city, the free new-player 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 march size (`march_too_big` "your troops in one rally may total your march 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 march 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 drops the joiner's own shield, 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 marches, 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 city, no march 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 kingdom 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 kingdom'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 kingdom 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 quest. 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 city), 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 Forge Material Kits and Diamond Passes open at once too), a quest 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 hero |
| `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 hero 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 it leads, +1%/level), `max_level`, `free_reset` |
| `hero.skill_reset` | — | refunds every spent hero 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 hero pays the ransom, `500 × hero level` silver fixed at the moment of capture (leveling the hero while it is held doesn't raise it; the captor's release reward is fixed the same way), to the captor, and the hero 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 hero walks home at `release_at` and the captor gets `100 × hero level` silver; from prison level 30 the hero also loses 10% of its XP progress |
| `prison.release` | `{player_id?}` | the captor lets a held hero 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 hero'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 Prison holds no heroes" / "that hero is not in your Prison". Emits `prison.released {released: [player_id], count}` |
| `craft.start` | `{item_id}` | crafts a gear item at the Forge (recipes in the `gear` data set) |
| `guest.recall` | `{owner_id, from_id?, host_id?}` | sends a reinforcing player's troops (and any wounded of theirs held there) home from a host city as a returning march; 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 city they stand in, which picks the city when the owner's troops stand in more than one (`city.stationed` rows carry it; without it the first city found is used). `not_found` when there are none, `no_alliance` for someone else's troops in someone else's city. Emits `guest.recalled {owner_id, march_id, return_at}` |
| `guest.recall_all` | — | the host sends every allied reinforcement in their city home at once (each as `guest.recall` would, so the city can raise a Peace Shield). 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 city |
| `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 machine 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 machine hasn't reached that skill's `min_level`. Skills include the utility `<id>_drive` (march speed, level 12) and `<id>_hold` (carry load, level 28); dragons have `<id>_wings` / `<id>_haul` |
| `dragon_pet.levelup` | `{dragon_id}` | same shape as `war_machine.levelup`, for the role-specific pets (`emberwing`, `stormtalon`, `frostmaw`, `ironscale`) |
| `dragon_pet.skill` | `{dragon_id, skill_id}` | same shape as `war_machine.skill` |
| `black_market.buy` | `{item_id}` | spends Black Market tokens 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 kingdom; 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 Might plus training time, no troop Might), which the league ranks on; `might` is total Might). `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 Town Hall 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`.

**Shields.** Starting an `attack`, `scout` or `raid_npc` march drops any active shield on your **own** city:
the free new-player shield and a paid one alike (a shield protects a city that isn't fighting back; an NPC
camp is still a hostile target). Exception, for the tutorial: a march to an NPC tile (`raid_npc`, or a scout
of an NPC camp) keeps the **free** new-player shield, which lasts until Town Hall 4; a paid shield still
breaks.

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

**Targets.**

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

**Camps.** When a camp is cleared in battle, every other `raid_npc`/`attack` march 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
march that arrives after the camp 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 march found camped on a cleared
camp'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 camp doesn't respawn while an army is camped on its tile.

**Turned back.** An `attack`, rally or `scout` that arrives at a city shielded 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 Palace's protection and
Anti-Scout), and the city'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 city). A march (or a
rally) sent at a city that has left the tile by the time it arrives (it teleported, or was driven out of the
Royal Forest) 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 city, army on a tile or Palace 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 city,
never the scout's troops). With Fake Army up, the city'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 Fake Army. A scout that Anti-Scout stopped gives the city's owner
`mail.scouted.subject_blocked`/`.body_blocked`.

**Gathering.** A `gather` march 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 Palace). 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 city 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` march 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 drops no shield. 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 city
when the march leaves; negative amounts count as 0): `empty_trade` with nothing to carry,
`building_required` without a Market, `trade_too_big` over the Market's load per trade,
`insufficient_resources` when the city hasn't got it.

**Reinforce.** A hero is refused `hero_not_allowed`, a city without an Embassy `no_embassy` (naming the
player), one without room for the troops sent `embassy_full` "the Embassy has room for R more troops (H of
C)" (H counts the guests there and the reinforce marches 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 Palace 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 Palace 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
Palace meanwhile `palace_enemy`. A player's troops on the Palace merge into one army.

### 3.2 `shield.buy` in detail

`{hours}` or `{item_id}` **activates** a shield: 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 a shield only puts the item in the bag; it
does **not** activate it. A player can hold any number and mix of shield 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 shield (bought with diamonds, from an item, or the free new-player shield) drops the instant its
owner commits any offensive action: see `march.start` (kinds `attack`/`scout`/`raid_npc`, and an
`occupy_palace` march unless your side holds the Palace) and `rally.create`/`rally.join`.

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

**Burn-down shield.** A city that loses 3 fights to players (attacks or rallies; bandit raids and tutorial
raids don't count) within 15 minutes gets a free 30-minute peace shield, an ordinary `shield_until` that the
owner's attack, scout or rally drops 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 shield would
be refused, the burn-down shield doesn't go up 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, shields, Anti-Scout, Fake Army, boosts, teleports, 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 (iron ingot, tanned leather, steel plate, silk thread).
- 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 food/wood/stone/ore crates at
  10×) go straight into the city.
- 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 kingdoms. 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 kingdom may run behind another gate); the new connection's `welcome` is the new kingdom'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
march 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 (city + 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 city has an active Peace Shield (no deadline is
  exposed). A scout, attack or rally against a shielded city is refused, so a client can say so before
  sending.
- An occupied resource or camp 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 camp's **live** garrison,
  its troop might, what a win drops and its display name ("Bandit camp Lv 1"). Read these for the camp card
  instead of a level table (the `combat` data set's `npc_templates`), as the scout report, the march form
  (`march.preview defender_troops`) and the battle report do: a tutorial camp holds 20 Spearmen (the
  `tutorial` data set's `camp_troops`), not the level-1 template's 40, and a camp 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 city tile of the viewer's own alliance (not the viewer's own city) carries `embassy_room`: how many more
  troops its Embassy takes, capacity less the guests there and the reinforce marches on the way (the sum
  `march.start` `reinforce` refuses on with `embassy_full`); 0 means full or no Embassy.

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

### 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 march carries `troops_hidden: true` instead of `troops`, `wounded` and `hero`;
- a Palace another side holds carries `palace.garrison_hidden: true` instead of `garrison` and
  `garrison_troops` (`garrison_cap` stays).

A march coming at the viewer's city, or at a tile one of the viewer's armies holds, is seen through the
viewer's Watchtower, 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 city's
Watchtower. Bandit warbands stay public. A scout report gives the numbers; Might 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 city's Town Hall, a camp's or node's level),
`troops` (the defenders counted, reinforcements and, for the Palace, the whole garrison included), `who`, and
by target `th_level`, `wall_level`, `shield_until` (city), `amount`/`max_amount` (node),
`occupant_name`/`occupant_tag`/`occupant_hero` (an army or the Palace), 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 city report also carries the Wall's own guard, which fights every attack even when
`defender_troops` is empty: `defender_wall_troops` (params `wall_troops`: 40 `wall` units per Wall level, half
while the Wall is damaged), `defender_wall_power` (params `wall_power`: that guard's power fighting alone, with
the city's bonuses and its hero if home) and `defender_power` (params `defender_power`: the power of
everything the report shows, troops seen, reinforcements, traps, the Wall guard and the hero if home, before
troop counters; a camp report has it too). A city report's params also carry `defender_id` (the city's
owner): `march.preview` measures an attack on that city with your newest such report, the same defense
against the troops you pick with the counters applied. With a Wall 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 city's
owner), `defender_lootable` (resources a won attack would carry off now: above the Warehouse protection,
before the attacker's load limit; camps too), `defender_hero_level`/`defender_hero_home` and `defender_might`
(might of the troops shown; camps 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 hero won in that fight (each side's copy carries its own value).
- The Wall 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 Wall 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 Wall takes everything.
- Camp and city reports carry `defender_troops` (the defending force at the start, no wall entry),
  `defender_wall_level` (city), `defender_remaining` (still standing at the end), `attacker_hero`/
  `defender_hero` (whose hero 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 city fight's report (both copies) carries `defender_hero_state`: `home` (the defending hero fought),
  `captured` (it fought and was taken), `held` (it was already in someone's Prison) or `away` (on a march).
- `loot` (resources) is set only on a win. `loot_items` (`{item_id: n}`) is the item side of the loot: the
  blueprint fragment and forge material a camp win gives. Beating a camp placed for your tutorial always
  drops a blueprint fragment and a forge material.
- `loot_capacity`/`loot_capped` are what the troops that came through **unhurt** could carry (the wounded
  carry nothing; city, camp and rally reports alike) and whether the loot was trimmed to fit.
- `defender_kind: "npc_camp"` and `defender_level` identify a camp 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_strength`/`defender_strength`/`attacker_hero_mult` are the two sides' troop might, with the
  attacker's multiplied by the hero's odds factor when the hero marched (`attacker_hero_mult` absent when it
  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 march, or a rally, sets out against a member's city;
- `chat.system.rally_threat` (the same params) there when an enemy rally starts gathering against a member's
  city;
- `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-march warning and the War tab still
show them). Bandit 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 Kingship title.

### 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 an NPC-camp fight
(`raid_npc`/`camp` marches) 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 Machines and Dragons.** `player.war_machines`/`player.dragon_pets` have one entry per machine
(`sawduster`/`stonecutter`/`icecrusher`, one per troop category) or dragon (`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 kingdom
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 tokens, so the Shop can show what the key opens.

**March 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 Town Hall's base (the `meta` data set's `march_size_by_th`),
plus the King's Palace boost, times 1 + the hero skill and Academy research percents. `research_tech_id` is
the tech that raises it (`logistics_corps`); `next_town_hall_level` is the lowest Town Hall level with a bigger
base 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 heroes this city 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
heroes it is; `player_id` is what `prison.release` takes.

**Hero.** `player.hero` carries `march_atk_pct` (base hero attack + level + skills + gear, in percent),
`march_hp_pct` (skills + gear) and `odds_mult` = (1 + atk) × (1 + hp): what marching with the hero does in
combat, for the march 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 hero leads this march" 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 kingdom 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). `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 march and a captured hero never block).
`city.stationed[]` = `{host_id, host_name?, alliance_tag?, x, y, troops, wounded?}`: every city holding this
player's reinforcements as guests, sorted by host id (the Palace garrison is not in it; see `palace`);
`guest.recall {owner_id: <self>, host_id}` brings a row home. `player.loyalty` is the Alliance Store's
currency, earned from silver donations, alliance helps, the alliance quest board, NPC-camp kills and opening
Alliance Gifts (rates in [game-mechanics.md](game-mechanics.md)).

**Kingship.** `palace.king_id` is the current Palace occupier, or that occupier's alliance Leader if the
Palace is alliance-held (empty while unoccupied). `palace.protected` true means the Palace 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 King-toggled boosts currently
active (`"march_size"` \| `"prod"` \| `"upkeep_reduction"`). `player.title_id` is the Kingship title, if any,
the King 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 curse).

### 4.6 City fields

**New-player shield.** `city.new_player_auto_shield` (`true` while set) marks that `shield_until` is the
automatic new-player shield, which has no real deadline (it ends at Town Hall 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 shield.

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

**Anti-Scout and Fake 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` march when it is sent), Anti-Scout is
checked only when the scout *arrives*: the march still goes and takes its full travel time, and the attacker's
mail comes back "Scout Blocked" with no city detail. Fake 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 engineers, 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}`:
engineer-role units in the city, how many of them speed up one repair (5 + Workshop 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 Quests

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

### 4.8 Top-level fields

| field | shape |
| --- | --- |
| `map_size` | this kingdom'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 marches that concern you, not the whole kingdom's: your own and your alliance's; every march heading at your city (`to_x/to_y` or `target_x/target_y`); and any march 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 marches 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 city and `owner_id` not yourself or an ally (see [ai-player-guide.md](ai-player-guide.md)). See "March 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 city; `troop_cap` (the rally's total troop ceiling, see `rally.create`) and `troops` (committed so far, every wave); `arrive_at` once marching; each `waves[]` entry's `name`. An ally's reinforce march in `city.incoming[]` carries `friendly: true` and its kind, owner, troop count and exact arrival even without a Watchtower: it is not an attack |
| `rankings` | `{id,name,might,rank,alliance_tag?}[]`: the top 10 by empire Might of **this kingdom** (rankings never span kingdoms); other players' rows refresh every 10 s, your own row is always live. `rank` is competition ranking (equal Might, equal rank, the same rule as `player.might_rank`). The list is built per viewer: the viewer's own row carries their live Might 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 quest reward shape, `chest_diamonds` included), `city.relocated` (`{x, y, from_x, from_y, who}`: the city lost a defense inside the Royal Forest 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 kingdom's single Palace tile, present once the map has it. Occupying it (`march.start` kind `occupy_palace`) grants a flat Might bonus and the Kingship (see "Kingship" 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 kingdom-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 kingdom 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 most powerful; 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 Might 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 Town Hall 4 graduation pack, present for 24 h after it was paid. `full` is always true (every graduation pays the full pack, one 8-hour Peace Shield item among it); `reward` is what was granted, including every open step's reward for a player who reached Town Hall 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 kingdom's AI players (see `player.set_client`) |
| `chat` | §4.4 |

**Reward maps** (tutorial steps, graduation, quests) use the quest 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 quest 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`.

**March fields.** Each march has `ends_at`, when its current state ends (`arrive_at` while marching,
`gather_until` while gathering, `return_at` while returning, absent while camping), and `slot_free_at`, when
the march is expected to be **home** and its march 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 march is gathering or returning (a time already past):
the time home is `ends_at` while returning and `slot_free_at` before that. A march 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}` wounded in the march's fight and riding home with it (they reach the hospital on
arrival; `troops` lists only the unhurt); and `target_x`/`target_y`, the tile the march was sent to, which
stay put when `to_x`/`to_y` switch to the home city 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 march coming at your city, or at a tile one of your armies holds, has `arrive_at` and
`ends_at` rounded up to the minute below Watchtower 10 and never carries `slot_free_at` (§4.2).
`gather_loot` (a gathering march only) is the load the march 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 marches 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 Embassy
  takes, `viewer_sending` that the viewer has a reinforce march 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 Loyalty income with the Loyalty 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 silver 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 silver 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 (Town Hall 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 camp placed for this player alone: 3–8 tiles from the
  city, garrisoned with 20 Spearmen (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` camps 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 forge 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 Might 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 city
  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 camp and opens it (the
  `npc` steps point at the **same** camp: the one pointed at first, or the one the player actually scouted;
  never a camp another player's army holds or is marching 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 kingdom'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 kingdom 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 kingdom 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.agentickingdoms.com`, for
MCP-capable clients such as Claude Desktop and Claude Code:

```
claude mcp add --transport http agentic-kingdoms https://mcp.agentickingdoms.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.