# Modes & accounts

**Owns:** Sandbox vs Ranked vs Rated mode catalogue, the Rated Elo method (ladders, continuous rating, exclusions, anti-collusion), accounts / API keys / one-army-per-mode rules, ranked unlock and rating (counts), fair-play principles, and the 100-player sandbox plan. Shipped board rules and timing constants stay in [rules.md](rules.md). Agent API surface: [api.md](api.md). Deploy / env: [ops.md](ops.md). Load numbers: [architecture.md](architecture.md).

**Positioning:** a game for AI **and** humans. The planned `1s` world is AI-first; copy never belittles humans.

---

## Mode catalogue

| Kind | Mode id | Cycle | Who can play | Status |
|---|---|---:|---|---|
| **Sandbox** | `10s` (public name **Sandbox**) | 5 s | Guests (no account) and registered | **Live** (today’s default world) |
| **Rated** | `rated` (public name **Rated**) | 5 s | Registered account (guests cannot); joined explicitly | **Live** — the Elo benchmark, [below](#rated--the-elo-benchmark) |
| **Ranked** | `1s` | 1 s | Registered account; unlocked (below) | **Planned** — not a world yet; AI-first |
| **Ranked** | `r10s` (label **Ranked 10 s**) | 10 s | Registered; unlocked | **Configured, feature-flagged** — separate board from Sandbox `10s` |
| **Ranked** | `1m` | 1 min | Registered; unlocked | Configured / flagged (keep existing `1m` state) |
| **Ranked** | `1h` | 1 h | Registered; unlocked | **Planned** — not a world yet |
| **Ranked** | `24h` | 24 h | Registered; unlocked | Configured / flagged (keep existing `24h` state) |

- Sandbox `10s` and Ranked `r10s` are **different modes** (separate boards / snapshots / player rows); the Sandbox is never named by its cooldown (“5s”); the cooldown is shown as a property (“5 s cooldown”). The mode table `GAME_MODES` in `packages/protocol/src/modes.ts` is the one source of id, public name, cooldown and ranked flag; labels and `/health` derive from it. The wire id `10s` is kept for compatibility (API keys, saved armies and stored data key on it); no alias is needed.
- **MVP:** only Sandbox is live. Ranked join stays off unless `RANKED_MODES_ENABLED=1` ([ops.md](ops.md)); while off, ranked modes are hidden from `/health` (`publicModes` and `modes`), `GET /api/worlds` and the OpenAPI world enum, but their code and config stay. Planned `1s` / `1h` stay config-only (no world) until implemented.
- Rule constants (cooldown length per world, ranges, exits, growth) live only in [rules.md](rules.md); this file owns *who* may enter which mode and *how* accounts bind.

Instantiable worlds today: `10s` (sandbox), `rated`, `r10s`, `1m`, `24h`. Guests may join **only** Sandbox. Further accounts / unlock work: job `5ecc67a1`.

---

## Accounts

- **Email registration** (unverified allowed). Normalise for dedupe: case-fold; Gmail-style strip dots and `+tag` on the local part. Unique claim on the normalised address applies immediately (MVP; reclaim / verify later — [tech-debt.md](tech-debt.md)). Register HTTP conflicts return opaque `conflict` (no username/email enumeration oracle).
- Existing IP limits stay (names as in [ops.md](ops.md) / server env): `GUEST_IDENTITIES_PER_IP_HOUR`, `SOCKETS_PER_IP`, `API_KEY_AUTH_FAILS_PER_IP_MIN`.
- **One army per account per game mode.** The control channel is bound **per mode**: UI **xor** API for that mode (an account may use UI in one mode and API in another). Joining the other channel while the army is **alive or hibernating** returns `channel_locked`; after the army is **dead** (mate / surrender / idle despawn) and not hibernating, the slot frees and either channel may join again.
- Retire `AGENTS_PER_ACCOUNT` (replaced by one-army-per-mode + one key).
- **API keys:** registered accounts only; **one active key per account**, valid in **every** game mode (not per-mode). Shown once at creation; hashed at rest. Creating again **rotates** the credential (old key revoked; agent identity and armies stay). DELETE revokes the agent. No player-run farms. The **house farm** is Sandbox-only and plays by the same rules as everyone else: **one account + one key per farm army** (bootstrap: `pnpm --filter @chessar/agents create-keys`, see [ops.md](ops.md#3-house-accounts--api-keys)).

---

## Ranked

- **Unlock** only after the account has given a **first check** and a **first mate** to **another account’s** army (not bots-only self-play unless those armies are other accounts). Guests have no account — check/mate against a guest does **not** count. Same-account (or missing-attacker) credit does not count.
- **Rating (now):** per-account counters `checksGiven` and `matesGiven` (increment on each qualifying `checkStarted` / `mated`). Unlocked ⇔ both ≥ 1. The Elo rating is a separate system: [Rated](#rated--the-elo-benchmark).
- **Join gate:** when `RANKED_MODES_ENABLED` is on, a registered account may join a ranked world only if unlocked; otherwise the join ack is `ranked_locked`. Guests stay `account_required` on ranked. Sandbox `10s` never checks unlock.
- **API:** `GET /api/me` includes `checksGiven`, `matesGiven`, `rankedUnlocked` for registered sessions (guests omit or null). Counters live on `accounts` (Postgres + memory store), not on the in-world player row.

---

## Rated — the Elo benchmark

A public, verifiable rating for AI agents (and, on a separate ladder, humans): builders and labs compare models by a number they can cite. Not behind `RANKED_MODES_ENABLED` and unrelated to the Ranked unlock above.

- **World:** `rated`, a separate board with the Sandbox rules and the same 5 s cooldown ([rules.md](rules.md)); the Sandbox is untouched. A registered account joins it explicitly (REST/MCP `join` with `world: "rated"`, socket `join` with `mode: "rated"`); guests get `account_required`. One army per account per mode applies as everywhere.
- **One continuous rating, never reset:** every identity starts at **1500** on its first rated game and keeps moving the same number on each ladder, across months and for good. Owner decision 2026-11-21: frequent resets (the first design was a monthly season) make a rating mean little, and a builder's number should keep its meaning over time. No per-day drift and no decay: an idle army keeps its rating and profile. **Freshness instead of a reset:** the ladder lists only armies with at least one rated game in the last **30 days** (`activeDays`); an idle one drops off the table and returns, rating intact, on its next game. There is no `season` parameter any more; a request that sends one is HTTP 400.
- **Result → rating change: pairwise Elo on mate outcomes.** A *game* is one rated result: when an army falls to a mate (the mate window held, or a check clock ran out), each army credited with it (`mated.by` and `assists`) beats the fallen army. Each result is a standard Elo update (K = 32, expected score `1 / (1 + 10^((Rb − Ra)/400))`) multiplied by a weight: `weight = 1 / raiders / (1 + earlier results of the pair in the last 30 days)`, where `raiders` is the number of eligible armies sharing the mate. Why this and not the alternatives: a free-for-all has no single winner, so placement or Glicko-2 needs a finished round, which this endless board does not have; pairwise Elo needs only the mate event, is the rating people already know, and the weight keeps a many-on-one dogpile from counting as many wins. Checks and captures do not rate: they are cheap and farmable, a mate is the unambiguous outcome.
- **Minimum games:** a rating is public (ranked) from **10** games in total; before that it is listed as `provisional` with no rank.
- **Ladders:** `agents` (API-key armies) and `humans` (session armies) are separate tables. A result needs both armies on the same ladder; a human beating an agent (or the reverse) rates neither. `open` (humans and agents together) comes later.
- **Baselines:** house (farm) armies, flagged own/test accounts and `INTERNAL_USERNAMES` (the *internal* rule of [metrics.md](metrics.md#definitions)) play the rated world as calibration, the way chess engines publish a reference pool. The farm runs `FARM_RATED_AGENTS` (default 5, one per style: smart, brawler, turtle, trickster, pack, …) there on top of its Sandbox floor ([ops.md](ops.md#scaling-the-farm)). They are rated like everyone, never ranked and never on `ranks`: `GET /api/leaderboard` lists them apart in `baselines` (`name`, `persona`, `rating`, `games`), so an external agent sees where it stands next to known opponents. Guests cannot play rated.
- **Anti-collusion:** armies of one account (one owner) gain nothing from each other: no result is stored. A repeated pairing is damped: the n-th result between the same two armies within a rolling 30 days (either direction) weighs `1/n`, so farming one friend converges to nothing, while a rivalry that went quiet for 30 days counts in full again. A result between two house armies counts a tenth (`HOUSE_PAIR_FACTOR`, `rating.ts`): baselines calibrate against outsiders, not by trading wins among themselves, and an external agent cannot move them that way. Baselines have no profile or badge of their own.
- **Daily cap:** each identity may take part in at most `RATED_GAMES_PER_DAY` (default **50**) rated games per UTC day; past it, a `join` or `respawn` that would start a new army in the rated world answers `rated_cap` until the next day (re-attaching to a living army is free). House (internal) armies are exempt, so the baselines never idle until midnight. It is the one free-tier hook: a paid tier raises this value, no new code path.
- **Verifiable:** every result is stored (winner, loser, raiders, weight, ratings before and after) in `rated_results`; a rating is the replay of all results in order, and `replayResults` (`apps/server/src/rating.ts`) rebuilds the whole table from them (given the identities of the house armies, whose results are damped). The ratings table is only the cached replay.
- **Read surface:** `GET /api/leaderboard`, `GET /api/agents/<name>`, the badge `GET /api/agents/<name>/badge.svg` and the MCP tool `leaderboard`: [api.md → Leaderboard](api.md#leaderboard). The ladder lists the public in-game name and, for agents, the owner's username.

---

## Principles

- **All armies are equal.** No bot/human special-casing and no hardcoded custom player rules in the game ([rules.md](rules.md) growth parity is the same for every army).
- **Fair-play text** (shipped on `/terms/` and the landing FAQ): equal armies, one army per account per mode, no player-run farms, one API key per registered account (valid in every mode). The Sandbox house farm is operator-run and plays by the same rules.
- **Enforcement — Later** (document only; build nothing now): player reports, mass bans, moderator armies, community hunting of offenders.
- **Private servers — Later / TODO** (document only; build nothing now): an account owner can host their own private world for friends or testing, using the same account/key. See also the [whitepaper roadmap](whitepaper.md#9-roadmap).

---

## Capacity goal — 100 players in the sandbox

**Goal (Andrius):** a playable Sandbox `10s` world with **100 concurrent armies** (humans + agents).

### What we already know

Load probe (PR #31, [architecture.md](architecture.md)): 100 agents × 10 min on `10s` peaked ~153 players; server RSS ≈ 42 MB; tick p95 ≈ 6.7 ms. That proves the **server** can host the count under bot load. It does **not** prove the **client** or the social surface stay usable with 100 armies on screen.

### Plan (lane owners)

| # | Work | Lane | Done when |
|---|---|---|---|
| 1 | Growth parity (spawn peers + recruit gate) | gameplay | Docs [#77](https://github.com/chessar-io/chessar.io/pull/77) merged; engine [#79](https://github.com/chessar-io/chessar.io/pull/79) |
| 2 | Local load: 100 sockets on Sandbox `10s`, ≥30 min; tick / RSS / bandwidth / FPS table | qa | Numbers on the qa sandbox job thread |
| 3 | Client audit at 100 armies: minimap, list / Find player, ranking, feed, chat, FPS | ui + qa | Findings → owning-lane jobs |
| 4 | Sandbox-only abuse ceiling notes (`SOCKETS_PER_IP` for harness); prod default unchanged unless head OK | ops | [ops.md](ops.md) lists the sandbox override |
| 5 | Launch kit once the sandbox holds 100 without console errors / unusable UI | growth | Posts in [seo.md](seo.md) |

### Success criteria (sandbox)

- 100 armies alive on local Sandbox `10s` for 30 min without crash or event-loop delay p99 > 100 ms.
- One browser client with all 100 visible: no sustained <20 FPS; no console errors; list / Find player usable.
- Growth parity live so top-1 material share stays bounded in bot churn (#79 balance comment).

### Out of scope here

Private Builder sandbox worlds (paid) and Arena seasons — [whitepaper.md](whitepaper.md#9-roadmap).
