Kettle API

This guide is for developers who want to put a game or interactive app on Kettle. It covers what Kettle does for you, how to plug in a server, how clients connect over HTTP and WebSocket, and the SDK calls that wrap it all. Everything here is taken from the code as it stands; when the code changes, this file changes with it.

Why build on Kettle

Every online game rebuilds the same plumbing before it can test a single idea. Kettle ships that plumbing, tested, so a team writes only the parts that make its game different.

Good fit: session-based multiplayer for 1 to 8 players per room (co-op, party, turn-based, asynchronous challenges), small studios, and games that want near-zero idle cost.

Not a fit today: fast shooters that need UDP or sub-50 ms authority, MMO-scale shared worlds, voice chat, and anything needing purchases, leaderboards or cloud saves before those modules land (see the roadmap below).

Getting started

These steps create a game server from the reference game that ships with Kettle.

1. Copy workers/api-reference into your project and rename it.
2. Replace ClickRoom with your own Room subclass (see "Writing a room").
3. List your room types in createKettle({ roomTypes }) and in createRoomHost({ ... }).
4. Set two secrets: JWT_SECRET and JOIN_SECRET (in .dev.vars locally, wrangler secret put when deployed).
5. Run pnpm dev. Your server answers on http://127.0.0.1:8787.
6. In a client, sign in, create a room, connect, and send intents (see "SDKs").

The Worker needs these bindings (from workers/api-reference/wrangler.jsonc):

{
  "durable_objects": {
    "bindings": [
      { "name": "LOBBY", "class_name": "LobbyDO" },
      { "name": "ROOM_HOST", "class_name": "RoomHost" }
    ]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["LobbyDO", "RoomHost"] }],
  "d1_databases": [{ "binding": "DB", "database_name": "my-game", "database_id": "…", "migrations_dir": "migrations" }]
}

Copy Kettle's migrations/ into your project (the D1 tables for accounts) and add your own after them.

Authentication

Clients start with an anonymous account. The access token goes in an Authorization: Bearer header on every authenticated call.

POST /v1/auth/anon → a new player and a session:

{ "player_id": "3f0c…-uuid", "access_token": "eyJ…", "refresh_token": "…", "expires_in": 900 }

POST /v1/auth/refresh with { "refresh_token": "…" } → the same shape, or 401 {"error":"bad_token"}.

Keep the same player across launches. Store the refresh token wherever your game keeps secrets, and sign in with it next time:

• Godot: sign_in(saved_refresh), saving every token from session_changed.
• TS: signIn(savedRefresh), then save session.refresh_token.

The SDK rotates the token and starts a new anonymous player only if the server refuses it; with no answer (offline) it fails once and doesn't wait twice. Without this, each launch is a new player with an empty inventory.

Account linking (Apple, Google, Game Center, Play Games, email)

A refresh token lives on one device. To keep an account across devices and reinstalls, the player links a provider identity to it, then signs in with that identity on the new device. Kettle verifies each credential itself and stores only the provider's user id (for email, a keyed hash of the address).

import { createKettle, defineLinks } from "@kettle/server-core";
export const links = defineLinks({
  apple: { audiences: ["com.example.game"] },               // bundle ids / services ids (aud)
  google: { clientIds: ["123-abc.apps.googleusercontent.com"] },
  gamecenter: { bundleIds: ["com.example.game"], maxAgeSec: 600 },
  playgames: { clientId: "123-web.apps.googleusercontent.com", secretEnv: "PLAYGAMES_SECRET" },
  email: { from: "My Game <codes@example.com>", perAddressPerHour: 3, perIpPerHour: 10, maxTries: 5, codeTtlSec: 600 },
});
export default createKettle({ game: "my-game", /* … */ links });

Routes (errors are {error, reason?}; reason names the failed check, e.g. signature, audience, issuer, expired, nonce, public_key_url):

No merge. When an identity already belongs to another player, Kettle doesn't combine their data. The client asks: "use that account" (signin; this device's anonymous player is left behind) or "keep this one" (link with takeover; the other player loses that link). See ADR-013.

On the shared platform, put the non-secret ids in a <G>_LINKS var (the defineLinks options as JSON, e.g. {"apple":{"audiences":["com.example.game"]},"email":{"from":"My Game <codes@example.com>"}}) and the secrets in <G>_LINKS_SECRET, <G>_PLAYGAMES_SECRET and <G>_RESEND_KEY (else a shared RESEND_KEY). Secret names are fixed there, so a game never reads another's.

Tests and special deploys can replace the provider fetch: defineLinks({ fetch }) or setLinksFetch(fn) (also clears the key caches).

HTTP endpoints

All bodies are JSON. Errors return { "error": "<code>" } with the status shown.

/v1/geo never stores anything and needs no device permission. Use it only to suggest something nearby, and always let the player choose.

Real-time protocol

Every WebSocket frame is one JSON envelope, at most 16 KB:

{ "v": 1, "t": "intent", "id": 42, "ts": 1760486400000, "d": { } }

v is the protocol version, t the message type, ts the sender's clock in ms, d the payload and id optional. Games may add their own types, namespaced as "<game>.<name>"; Kettle checks only the envelope for those.

Connection lifecycle

1. Get a ticket from POST /v1/rooms or POST /v1/rooms/join, then open a WebSocket to its ws_url within 60 seconds.
2. Send hello with your protocol version.
3. Receive welcome with your seat, the server time, a resume token and the full room state.
4. Answer every ping with a pong that echoes server_ts. The first few pings come quickly so the server learns your round-trip time right away.
5. Send intent messages; each gets an ack with the same seq.
6. Apply snapshot (full state) and delta (changes) to keep your copy of the room state current.
7. If the socket drops, request a new ticket with the same room code and say hello again. Within 30 seconds you get your old seat back.

Say hello once per connection (a second one gets bad_message), within 15 seconds of connecting (a socket still waiting after that is closed with 4003 when others connect). A room accepts at most 2 × maxPlayers + 4 sockets at once; more get 503 room busy. After a server restart, seats come back marked disconnected and are reclaimed after the resume window if their players don't return.

Messages

State deltas

changes is a list of operations. Each one is safe to apply twice, so applying a delta on top of a newer snapshot stays correct.

A path is an array of keys and indexes, for example ["stations", 2, "queue"]. The SDKs apply deltas for you; @kettle/protocol exports applyDelta and diff if you write your own client.

Errors and close codes

Writing a room

A room is a class with a few hooks. It holds your game state and rules; Kettle handles everything about connections. Room files must not import Cloudflare APIs (ADR-003), so a cheaper host can run the same classes later.

Override protected options to change the defaults:

Fair timing

timing carries receivedAt, rttMs and actionDelayMs = min(rttMs / 2, latencyCapMs). For anything judged on timing (hitting a beat, stopping a meter), judge the action at receivedAt − actionDelayMs rather than at arrival. In load tests this gave players at 0, 50, 150 and 300 ms round trips the same results. The cap stops a player from gaining by faking lag.

Game routes and telemetry

Raw archive (K-2.01). Bind an R2 bucket as TELEMETRY_ARCHIVE on the Worker that consumes the telemetry queue (the platform, or a game's own Worker) and every batch is also kept as NDJSON, one object per game and hour: telemetry/<game>/<YYYY-MM-DD>/<HH>/<id>.ndjson ({game, name, ts, player, props} per line; player is the same pseudonymous hash Analytics Engine gets). A failed write leaves the batch un-acked, so it comes back. Set a lifecycle rule on the bucket to delete objects after 13 months.

Add HTTP endpoints without touching Kettle. Routes match before Kettle's own and receive the signed-in player id:

createKettle({
  // …
  routes: [{
    method: "POST", path: "/v1/runs/finish", auth: true,
    handler: async (req, env, { playerId }) => Response.json({ ok: true, playerId }),
  }],
  telemetry: { events: {
    session_start: { blobs: ["platform"] },
    level_end: { blobs: ["level"], doubles: ["stars", "seconds"] },
  } },
});

Telemetry accepts only declared event names and fields, with strings up to 96 characters. Each event becomes one Analytics Engine row: blobs [game, name, …declared blobs], doubles [ts, …declared doubles], and a hashed player id as the index. Bind TELEMETRY_QUEUE (Cloudflare Queues) and ANALYTICS (Analytics Engine) to store events; with neither bound, events are counted and dropped. Never declare fields that could hold personal data.

Economy

Currencies, items and upgrades the server owns (ADR-004). The game declares a catalog; Kettle checks it at startup.

const economy = defineEconomy({
  catalog: {
    items: [
      { id: "coins", kind: "currency", stackMax: 9999 },
      { id: "ticket", kind: "stack", stackMax: 5, overflow: "clamp", clientConsume: true },
      { id: "sword", kind: "instance", equipSlots: ["hand"], levels: { maxLevel: 3, xp: [10, 30] } },
      { id: "booster", kind: "instance", expires: { ttlSec: 3600 } },
      { id: "founder", kind: "entitlement" },
    ],
    exchanges: [
      { id: "buy_ticket", costs: [{ item: "coins", qty: 10 }], outputs: [{ item: "ticket" }], limits: { perDay: 3 } },
      { id: "upgrade_sword", costs: [{ item: "coins", qty: 5 }], target: { item: "sword" }, outputs: [{ xp: 10 }] },
      { id: "daily_chest", outputs: [{ random: [{ weight: 1, outputs: [{ item: "coins", qty: 5 }] }] }], limits: { perDay: 1 } },
    ],
  },
  policy: { iapForbiddenTags: ["gameplay"], grantAlertPerHour: 200 },
  hooks: { onLevel: (owner, instance, item, level) => {}, onAnomaly: (ownerHash, n) => {} },
  dayKey: (now) => myResetDay(now), // per-day limits; default the UTC date
});
export const RoomHost = createRoomHost({ shift: ShiftRoom }, { economy });
export default createKettle({ /* … */ economy });

Server code (game routes, rooms through this.economy) uses createEconomyStore(env.DB, economy): grant, consume, reserve → commit/release, revoke, addXp, exchange, equip, transfer, give, apply, inventory, sweep, and totals(owner, { sinceMs, reasons? }) (what was granted since a time, per item, optionally by reason, counting grants, game ops and gifts received: build daily earning caps on it), and spendLeft(owner) (the player's daily spend caps: {item: {per_day, spent, left}}).

Spend caps by age band. policy.spendCaps: { <item>: { under13?, "13to15"?, "16to17"?, adult?, unknown? } } caps how much of a currency or stack a player may spend per day (dayKey), by the age band they declared (unknown until they do; a band left out has no cap). Every spend path counts (client consume, exchanges, game ops, gifts, sales, holds; a released hold counts as unspent), so rooms and game routes can't get round it. Over the cap, the write fails with spend_cap (HTTP 409 on Kettle's routes) and nothing changes. GET /v1/inventory adds spend_caps (the same shape as spendLeft) when the player has any.

Game ops (apply(owner, op, meta)) are for a game's own rules on the server: read the inventory, decide, then write the whole outcome in one atomic step: { ifVersion?, consume?, grant?, update?: [{ instance, level?, attrs? }], remove?: [instanceIds] }. With ifVersion (the version you read), the write fails with stale if anything changed in between: read again and decide again. Instance attrs are capped at policy.maxAttrsBytes (4 KB) and checked by hooks.validateAttrs. A town builder keeps each building as an instance (level, attrs = position, build timer, production clock) and checks the timers against server time in its own route. give(from, to, { consume?, grant }, meta) makes one owner pay and another receive in one step (gifts). Every write takes an opKey: the same key never applies twice and returns the first answer. A room should hold what a run uses (reserve with holder: "room:<id>") and commit at the end, passing { holder, owner } so only that room's hold for that player can be settled (a mismatch answers not_found); if the room dies, the hold lapses after ttlMs and the items come back. Quantities and levels must be whole numbers from 1 to 1,000,000 on every call (bad_request otherwise), so a game route that passes a client's number through can't reverse a transfer or mint.

Clients can read, run declared exchanges, spend items marked clientConsume, and equip. They can never grant. Random outputs are allowed only in free exchanges, and items tagged in iapForbiddenTags can't be marked for real-money sale.

{ "ops": [
  { "op_key": "1792110727661-0603f281", "op": "consume", "item": "ticket", "qty": 1 },
  { "op_key": "1792110727662-9a1b2c3d", "op": "equip", "slot": "hand", "instance": "i_…" }
] }

Ops run in order and each answers on its own (ok, replay, or error). Expired items and lapsed holds are swept on every read and write, and by scheduled() if you add a cron trigger.

Visits and gifts

Players can look at another player's place (a home, a town, a shop: the game decides what its public document holds) and leave a gift. There are no messages: a gift is an id from the game's list.

export const visits = defineVisits({
  gifts: [{ id: "wave", grant: [{ item: "coins", qty: 2 }] },                     // free for the visitor
          { id: "flowers", cost: [{ item: "seeds", qty: 1 }], grant: [{ item: "fans", qty: 3 }] }],
  limits: { perVisitorPerDay: 10, perHostPerDay: 30, perPairPerDay: 1 },        // the economy's dayKey
  validateDoc: (doc) => isMyLayout(doc),                                         // no names or free text
});
createKettle({ ..., economy, visits });

The game's server publishes documents with createVisitsStore(env.DB, visits, economyStore, economy.dayKey).publish(playerId, doc, { listed }), usually right after its own rules changed the place, so a document always shows what really exists. Unlisted documents are reachable by id only. Set clientPublish: true only for documents that are pure decoration; it requires validateDoc. Gift lines are whole numbers, and every gift item must exist in your catalog (Kettle checks when it starts). A gift runs give (the visitor pays cost, the host receives grant) with the caller's op_key, so a resend is harmless. Gifts received count in the host's totals. Documents are capped at 32 KB (maxDocBytes).

Guilds

Players form guilds (crews, clubs, organizations: the game names them). A player is in at most one guild.

export const guilds = defineGuilds({
  maxMembers: 100,
  roles: [{ id: "leader" }, { id: "officer", can: ["accept", "kick", "promote", "settings"] }, { id: "member" }],  // highest first
  names: { parts: [["Red", "Blue", "Golden"], ["Foxes", "Owls", "Rockets"]] },   // or { validate: (name) => ... }
  emblems: ["star", "moon", "bolt"],
  feedKinds: ["milestone"],                                                      // kinds your server posts
  help: { maxNeed: 10, perHelperPerDay: 30, ttlMs: 24 * 3600_000 },
});
createKettle({ ..., guilds });                   // or createGameWorker({ ..., guilds }) on the platform

• No free text. A name is one word from each list in order (any case; stored with the list's spelling), or passes your validate. Emblems come from your list. Feed entries carry your declared kinds with ids and numbers only.
• Roles. The first role leads (one per guild, may do everything); the last is a new member's. A role's can lists accept (join requests), kick, promote and settings. You can only kick or re-role members ranked below you. The leader hands over leadership with role: "<leader id>" and steps down one rung; when the leader leaves, the highest-ranked, longest-standing member leads; the last member out disbands the guild.
• Joining. Open guilds take you up to maxMembers (checked in the same statement as the insert, so a rush can't overfill a guild); closed ones collect requests for a role with accept.
• Help. A member asks for help with one of their jobs (job: an id your game understands, need ≤ maxNeed). Others give one help each, up to the need and within perHelperPerDay. Kettle only counts: your server reads createGuildsStore(env.DB, guilds).helpFor(playerId, job), applies what help means in your game (a build finishing sooner), then closeHelp.
• Server-only data. setData(guildId, data) (≤ 2 KB public JSON: a level, held sites) and post(guildId, kind, actor, data) for feed entries. Clients can't call either.
• Guild-owned items. The economy's owners are generic: guildOwner(id) gives a guild its own balances and instances (shared research, a joint roster). Members contribute with give(player, guildOwner(id), ...) from your routes.

Apply migration 0006_guilds. See ADR-009.

World shards

Shared grid maps (call them regions, servers or realms in your game) of player plots, neutral sites and timed travels.

export const worlds = defineWorlds({
  grid: [200, 200], playersPerWorld: 300,
  sites: (worldId) => mySites(worldId),               // neutral sites of a new world: [{site_id, kind, x, y, data}]
  spacing: 3,                                         // free cells around plots and sites
  fog: { chunk: 8, revealRadius: 12 },                // fog of war in 8×8 chunks; 0 = no fog
  travel: { clientKinds: ["scout", "challenge"], blockedByShield: ["challenge"], maxActive: 3, msPerCell: 60_000 },
});
createGameWorker({ ..., worlds });                    // or createKettle({ ..., worlds })

• Joining gives a player one plot for good: in the newest world with room, at a free random cell at least spacing from other plots and sites (checked in the insert itself). When a world is full the next one opens with your sites(worldId).
• Fog. A new plot uncovers revealRadius cells around it; your server uncovers more with reveal(playerId, x, y, r) (a scout arriving). Map reads show only plots, sites and travels in uncovered chunks (and always your own).
• Travels start from the player's plot: clients may start your clientKinds (and pass your validate), your server any kind with an optional duration. A player has at most maxActive moving; blockedByShield kinds can't target a shielded plot. Kettle only times them: your server reads due(playerId) (or dueInWorld(id) from a cron), applies your rules (a challenge match, a scouting report) and records the outcome once with resolve(id, result). Players may recall a moving travel.
• Server-only: setDoc(playerId, doc) (≤ 1 KB public summary of a plot: a level, a banner id), setShield(playerId, until), setSite(world, site, owner, data) with owner { kind: "player" | "guild", id }. claimSite(world, site, owner, expect, data?) changes the owner only while it is still expect (null = unowned) and answers whether it did: first come, first served (a one-of-a-kind building, a contested venue). claimStatements(...) gives the same guard and update as statements for your game op's extra, so a payment and the claim land in one write (when someone else got there first, the op answers conflict). syncSites(world) adds sites your sites(worldId) gained in a game update to a world opened before it (existing sites keep owner and data).

Apply migration 0007_worlds.

Trades

Players swap items: one offers, the other accepts, and both sides move in one economy batch (store.swap), or nothing moves. Only items marked tradable: true in your catalog can change hands; instances keep their level and attrs.

export const trades = defineTrades({
  maxLines: 4, ttlMs: 24 * 3600_000,
  limits: { perDay: 5, minAccountAgeMs: 7 * 86_400_000, sameGuild: true, instanceCooldownMs: 3 * 86_400_000, openPerPlayer: 5 },
  value: { of: (lines) => myValue(lines), maxRatio: 2 },   // sides within 2:1; an empty side is worth 0, so no one-way funnels
  eligible: (playerId, inv) => (levelOf(inv.balances.xp ?? 0) >= 5 ? null : "level"),   // your rule; refusals answer 403
});
createGameWorker({ ..., economy, trades });              // needs economy (and guilds for sameGuild)

• Atomic, not escrowed: items aren't locked while an offer is open. Accepting checks both sides again (ownership, cooldowns, values, both players' daily caps) and swaps; the trade's state and the caps are asserted inside the same batch, so a trade completes once even when accepted twice at the same time (the second answer is a replay or not_open).
• Limits are yours: keep trades from becoming a real-money market (value bands, daily caps, account age, same guild, per-instance cooldown).
• Your server can also call economy.swap(a, b, aGives, bGives, { opKey }) directly. Apply migration 0008_trades.

Handles

A handle is a player's display name, built from your word lists: one word from each list, in order, plus an optional number. Nobody types a name, so a game for teens can show who made or traded something without moderating free text. Handles are unique per game, in any letter case.

export const handles = defineHandles({
  parts: [["Quiet", "Bright", "Lucky"], ["Fox", "Owl", "Crane"]],   // "Bright Owl"
  number: { min: 1, max: 99 },                                       // optional: "Bright Owl 42"
  changeCost: { item: "coins", qty: 50 },                            // optional, needs economy
});
createGameWorker({ ..., economy, handles });

GET /v1/handles/parts, GET /v1/handles/me, GET /v1/handles/suggest (a free one at random), POST /v1/handles {handle} (refusals bad_handle, handle_taken, insufficient), GET /v1/handles/lookup?h= ({player_id, handle}), GET /v1/handles?ids=a,b (up to 50). The first pick is free; a change is charged in the same batch as the update, so a lost race spends nothing. Server code can call createHandlesStore(env.DB, handles, economy) and canonicalHandle(handles, text). Apply migration 0010_handles.

Counters

Likes, plays and other counts on your own ids (ADR-011): defineCounters({ kinds: { like: { onePerPlayer: true }, play: { perPlayerPerDay: 3 }, score: { client: false } } }), passed as counters. POST /v1/counters/<kind>/<target> (body {on: false} takes a like back) → {count, mine}; GET /v1/counters/<kind>?targets=a,b → {counts, mine}; GET /v1/counters/<kind>/top?n=&days= (days 0 = all time). A double tap or retry counts once. Server code: createCountersStore(env.DB, counters).count/get/top. Apply migration 0011_counters_moderation.

Place vitality (K-ext.26)

A shared value per place (0..max) that players' play raises and a daily tick lowers, with named states by threshold, so a game can change a place for everyone as it thrives or struggles. Nobody can lower a place. defineVitality({ places: ["a", "b"], states: [{id: "low", min: 0}, {id: "ok", min: 40}], decayPerDay: 6, kinds: {visit: 1, help: 4}, perPlayerPerDay: 10, activeRef: 50, boostMax: 4, start: 50, max: 100 }), passed as vitality (createKettle or createGameWorker). GET /v1/vitality → {places: [{id, value, state}], states}. Server code contributes from the game's own routes: createVitalityStore(env.DB, vitality).contribute(place, playerId, kind) → {added, value, state}: a kind's points, times a quiet-day boost (activeRef / players who contributed yesterday, between 1 and boostMax, so a small region behaves like a busy one), capped by perPlayerPerDay per place. The Worker's cron runs tick() (the day's decay, once per day; missed days catch up). SDKs: Godot vitality(), TS vitality(). Apply migration 0022_vitality (vitality_contrib is player data: exported and erased).

Events (timed windows, scoped standings)

Recurring windows your game declares (a weekly region season, a weekend cup), with points per window, scope and entrant, ranks, and rewards claimed once (K-4.03).

export const events = defineEvents({ events: [
  { id: "region_season", periodMs: 7 * 86_400_000, anchorMs: 4 * 86_400_000 },              // Mondays 00:00 UTC
  { id: "weekend_cup", periodMs: 7 * 86_400_000, anchorMs: 9 * 86_400_000, lengthMs: 2 * 86_400_000 },
]});
createGameWorker({ ..., events });

• GET /v1/events → {now, events: [{id, window, start, end, open, previous: {window, start, end}}]}.
• Points and standings go through your routes, because only your game knows a player's scope (their world, their guild): createEventsStore(env.DB, events) gives add(event, scope, {kind, id}, points) (only while the window is open; null when closed), addStatements(...) for the extra of the op that earned the points, standings(event, window, scope, kind, {n, offset}) (ties share a rank), entry(event, window, scope, entrant) → {score, rank, total}.
• Rewards once: claimStatements(event, window, playerId, key) in the economy op that grants the reward; a second claim fails the batch (the op answers conflict). claimed(...) tells you first; claims(event, window, playerId) lists every key claimed (a pass track's tiers).
• Entrants have a kind (player, guild, or your own), so a player's points and their guild's tally can sit side by side. The cron prunes windows older than keepWindows (default 8). Apply migration 0012_events.

Push notifications and the inbox

Game-declared notices (no free text from players), queued by your server now or for later, delivered to an in-game inbox and to devices through providers your deploy plugs in (K-ext.18).

export const push = definePush({
  kinds: {
    build_done: { title: "{building} is finished", body: "Come and see it." },
    raided: { title: "Your concessions were raided!", body: "{who} got away with {coins} coins." },
    weekly_digest: { title: "Your week", body: "...", default: false },   // off unless the player turns it on
  },
  perPlayerPerDay: 12,
  providers: (env) => [/* your APNs / FCM / web push senders: { platform, send(token, msg) } */],
});
createGameWorker({ ..., push });   // the cron delivers due notices and prunes

• Routes: POST /v1/push/devices {platform, token}, POST /v1/push/devices/remove {token}, GET|POST /v1/push/prefs, GET /v1/push/inbox?n=, POST /v1/push/inbox/read {ids | all}. The inbox also delivers whatever is due for its reader, so it works without a cron.
• Server: createPushStore(env.DB, push) gives:
  • notify(playerId, kind, data, {at, collapse}), or notifyStatements(...) for a game op's extra so the notice is queued with what caused it.
  • A collapse key replaces a queued notice (a build hurried along re-times its notice). cancel(playerId, collapse) drops one.
  • Data values are numbers or strings of at most 64 characters.
• Providers: send(token, msg) answers ok, invalid (Kettle forgets the token) or retry. Without providers, notices still reach the inbox. Players switch kinds off, and perPlayerPerDay caps device pushes (the inbox gets the rest).
• Apply migration 0014_push. APNs and FCM senders aren't built in yet: they need your keys (APNs token auth, FCM HTTP v1 service account).

Reports and blocks (moderation v1)

defineModeration({ kinds: ["beat"], reasons: ["spam", "rude", "stolen"], hideAt: 3 }), passed as moderation (ADR-011). Players report a target with a reason id (no free text): POST /v1/reports {kind, target, reason} → {hidden}; one report per player per target, reportsPerDay per player. At hideAt distinct reporters the target is hidden. Your server decides what hidden means and can takedown / restore (that decision sticks): createModerationStore(env.DB, moderation).hidden(kind, targets). Blocks: POST /v1/blocks {player}, POST /v1/blocks/remove, GET /v1/blocks; blocked(a, b) on the server keeps two players apart. Staff review reports in the admin console's Reports tab (K-3.07): open, hidden and decided targets with their reasons, and Take down / Restore for game admins (audited; a console decision sticks the same way). For games on the shared platform the console writes through the platform's admin entrypoint, whose only write is POST /games/<g>/moderation {kind, target, hidden, by} (decideModeration).

Strikes and bans (K-3.05, migration 0021). defineModeration({ ..., strikes: { windowDays: 90, banAt: [{ strikes: 3, days: 1 }, { strikes: 5, days: 30 }, { strikes: 8 }] } }): staff (the console) or your server give strikes with one of your reason ids (or staff); strikes in the window ban automatically at the thresholds (no days: permanent; a longer ban in force is never shortened). A banned player gets 403 {error: "banned", until, reason} on refresh, provider sign-in and room, area and matchmaking joins, so their access ends within 15 minutes. GET /v1/me/standing tells the player. Server: createBansStore(env.DB, { ...moderation.strikes, reasons: moderation.reasons }) → strike, ban, unban, forgive, standing.

Listings (a player market)

Players sell tradable instances at fixed prices in one soft currency (ADR-012):

export const listings = defineListings({
  currency: "cash", feePct: 10, maxOpen: 10, ttlMs: 7 * 86_400_000,
  price: (item, attrs) => (item === "record" ? bandFor(attrs) : null),     // {min, max}; null = can't list
  eligible: (playerId, inv) => (levelOf(inv.balances.xp ?? 0) >= 5 ? null : "level"),
  // Optional: items that stand for moderated player content (hidden ones can't be listed or bought).
  moderated: (item, attrs) => (item === "print" ? { kind: "post", target: String(attrs?.post) } : null),
});
createGameWorker({ ..., economy, listings });

POST /v1/listings {instance, price}, GET /v1/listings?item=&attr=&value=&sort=cheap|new&n=&after=, GET /v1/listings/mine, POST /v1/listings/<id>/buy, POST /v1/listings/<id>/cancel. Atomic at buy: economy.sale(seller, buyer, instance, price, fee) pays, keeps the fee out of the economy and moves the instance in one batch; a listing sells once, and closes if the seller no longer has the item. With moderated, an item whose moderation target is hidden (a report threshold, a takedown in the game or the console) can't be listed, drops out of browse, and buying it answers 404 hidden; restoring the target brings its listings back. Apply migration 0013_listings.

Age bands and drop tables

export const drops = defineDrops({ tables: [
  { id: "club_pack", cost: [{ item: "pack_token", qty: 1 }], entries: [...], pity: { every: 30, tiers: ["epic", "legend"] } },
  { id: "star_pack", cost: [{ item: "stars", qty: 100 }], entries: [...], pity: { every: 30, tiers: ["epic", "legend"] },
    gates: { minAge: "adult", blockCountries: EU_COUNTRIES } },
]});
createGameWorker({ ..., economy, age: true, drops });

• Age bands: players declare one (POST /v1/me/age); it can be lowered but never raised by the client. getAgeBand(db, id) / ageAtLeast(band, min) for your own rules. Unknown = too young.
• Country: game routes get ctx.country (Cloudflare's view of the caller; signed through the platform). Unknown fails closed on tables with country rules.
• Odds: GET /v1/drops/<table> shows exact percentages from the weights the server draws with, the pity countdown, and available / why (age, region, region_unknown).
• Drawing: in your route, createDropsStore(env.DB, drops).decide(playerId, table, opKey, ctx.country) returns the entry, consume and extra statements; put them in your store.apply with what the entry means in your game, so a draw is paid, counted (pity) and granted once. For tables whose entries carry grant, open(economyStore, ...) does it all. Retries: logged(playerId + ":" + opKey).

Apply migration 0009_age_drops. See ADR-010.

Purchases (App Store and Google Play)

Real-money purchases, checked on the server and granted through the economy. The client never says what it bought: Kettle reads it from Apple's signed transaction or from Google's API.

export const purchases = definePurchases({
  products: [
    { id: "gems_500", apple: "com.example.gems500", google: "gems_500", grant: [{ item: "gems", qty: 500 }], usdCents: 499 },
    { id: "season_pass", apple: "com.example.pass1", google: "pass_1", grant: [{ item: "pass_s1" }], usdCents: 999 },
    { id: "kit_bundle", apple: "com.example.kits", google: "kits", grant: [{ item: "kit", qty: 3 }], usdCents: 299, kind: "non_consumable" },
  ],
  moneyCaps: { "13to15": 2000, "16to17": 5000 },          // US cents per UTC calendar month
  apple: { bundleIds: ["com.example.game"], environments: ["Production", "Sandbox"] },
  google: { packageName: "com.example.game" },
});
createGameWorker({ ..., economy, age: true, purchases });   // or createKettle({ ..., purchases })

• Catalog: every granted item must exist and be iap: true (policy.iapForbiddenTags still vetoes); Kettle checks at startup. kind defaults to consumable when a line is a currency or stack, else non_consumable; subscription is also accepted. gates: { minAge, blockCountries } work as on drop tables.
• Who may buy: under13 and players with no declared band are refused by default (refuseBands). moneyCaps counts usdCents, the game's own list price, never the store's local price, of granted and not refunded purchases in the current UTC month. Show GET /v1/purchases/products (or call POST /v1/purchases/check) before the store sheet.
• Account token: GET /v1/purchases/token gives a stable UUID per player (HMAC of the player id with PURCHASE_SECRET). Pass it as StoreKit 2 appAccountToken and Play Billing setObfuscatedAccountId; a purchase carrying another player's token is refused (wrong_account). requireAccountToken: true also refuses purchases without one.
• Apple: send Transaction.jwsRepresentation to POST /v1/purchases/apple. Kettle verifies it offline: the x5c chain (leaf, intermediate, root) must end at Apple Root CA - G3 (pinned by SHA-256), each certificate is signed by the next and valid at the transaction's signedDate, the intermediate is a CA, Apple's marker OIDs are present, and the JWS is ES256 signed by the leaf. Then bundleId, environment, productId and appAccountToken are checked and a revocationDate refuses it. Finish the StoreKit transaction once Kettle answers.
• Google: send { product, purchase_token } to POST /v1/purchases/google. Kettle signs in as the service account (GOOGLE_SERVICE_ACCOUNT), reads purchases.products (or purchases.subscriptionsv2), requires purchaseState purchased and a matching obfuscatedExternalAccountId, grants, then consumes consumables and acknowledges the rest. If Google doesn't answer the consume, acknowledged: false comes back and the next resend tries again.
• Once per transaction: the grant and the purchase row are one economy write keyed iap:<store>:<transaction id>. A resend by the same player replays (replay: true); the same transaction from another player answers 409 owned_elsewhere.
• Over a cap anyway: a verified purchase that arrives past the cap or a gate (a race between two devices, an old client that skipped the check) is still granted, because the store took the money. Its row is flagged (flagged: "money_cap", flags in purchases) for review, and the game may refund it in the store.
• Restore: POST /v1/purchases/restore takes up to 50 transactions. Ones never delivered are granted; for non-consumables and subscriptions the player already owns, entitlements and instances they lost are granted again (never currencies, never twice, and an instance traded to someone else doesn't count as lost). A transaction owned by another player answers owned_elsewhere (account linking is how a player gets back to the account that bought it).
• Refunds: point App Store Server Notifications V2 at https://<host>/<game>/v1/purchases/apple/notify; REFUND and REVOKE revoke the grant through store.revoke (signed payloads verified the same way). Point a Pub/Sub push subscription for Play real-time developer notifications at .../v1/purchases/google/notify?token=<RTDN_TOKEN>; a voidedPurchaseNotification revokes. Revocation is best effort: currency already spent can't be taken back, and what wasn't is stored in revoke_missing_json. A refunded purchase stops counting toward the month's cap.
• Testing: transactions from an Xcode StoreKit configuration file (environment Xcode) are signed by a local certificate and can't chain to Apple's root. Kettle accepts them only with environments: [..., "Xcode"] and allowXcode: true, and then checks nothing but the payload. Use it in dev and tests only, never in production. Sandbox transactions are verified like production ones. Tests can pin their own root with apple.rootSha256 and inject fetch for Google.

Secrets live where the routes run (the game's own Worker, or the game Worker on the shared platform): PURCHASE_SECRET (account tokens), GOOGLE_SERVICE_ACCOUNT (the service account's JSON key), RTDN_TOKEN (the push URL's token). Apply migration 0016_purchases. See ADR-014.

Leaderboards

export const leaderboards = defineLeaderboards({ boards: [
  { id: "daily_score", period: "daily", clientSubmit: true, minScore: 0, maxScore: 1000, validate: (s) => Number.isInteger(s) },
  { id: "season_wins", period: "all", keep: "latest" },          // only your server writes
]});
createKettle({ ..., leaderboards });            // or createGameWorker({ ..., leaderboards }) on the platform

• Periods: a period is a UTC day (2026-10-16), an ISO week (2026-W42) or all. Reads take period=current (the default), previous or a key.
• Scores: each player keeps their best score per period (keep: "best", higher is better unless sort: "asc"), or their last one (keep: "latest").
• Ranks: competition ranks, so ties share a rank. around=me lists the entries around the caller, and me is the caller's { rank, score, total }, or null.
• Friends (K-4.01): ?friends=1 ranks the board among the caller and their friends only (blocked ones left out); me.total is how many of them have a score. Needs the friends tables (migration 0017); defineFriends isn't required.
• Who writes: the game's server writes with createLeaderboardStore(env.DB, leaderboards).submit(board, playerId, score, data) from a room's end or a route. Clients may POST only to clientSubmit boards, which need maxScore or a validate hook. Use those for casual scores only; anything worth cheating for should be posted by your server.
• No names: entries show an anonymous tag (P-XXXXX) and your data object (at most 256 bytes: a character id, a flag), never names or free text.
• Retention: the Worker's cron prunes periods older than keepPeriods (daily boards 14, weekly 8). Apply migration 0005_leaderboards. See ADR-007.

Matchmaking

export const matchmaking = defineMatchmaking({ roomType: "duel", modes: ["duel"] });
createKettle({ ..., matchmaking });            // or createRoomHost(types, { matchmaking }) on the platform

• POST /v1/match {mode, profile} queues you (one ticket per player) or pairs you at once with the oldest waiting player of that mode: {ticket, state: "matched", join: {room_id, type, join_token, ws_url}}.
• GET /v1/match/<ticket>?mode= polls (about once a second keeps the ticket alive; it goes stale after staleMs, default 30 s): {state: "waiting" | "matched" | "gone", join?, waited_ms}. DELETE the same path cancels.
• The room is made with config {mode, matched: true, players: [{player, profile}, ...]}; your room validates the profiles in onCreate (throw to refuse) and can start once both have joined. First come, first served: no ratings yet. See ADR-015.

Areas (live presence)

Players in the same area of your world (a street, a map, a chunk: the game names it with a key) see each other move and emote, live. There is no free text: emotes are ids from your list, and a player's look is a small document of plain values (numbers, short ids, colours) that your game also checks.

export const areas = defineAreas({ emotes: ["wave", "cheer"], maxPerRoom: 30, validateLook: (l) => isMyAvatar(l) });
export const RoomHost = createRoomHost({ match: MatchRoom, area: AreaRoom }, { economy });
createKettle({ ..., areas });

Friends-only areas (K-4.01). defineAreas({ ..., friendsOnly: ["home."] }): a key home.<player id> belongs to that player, and only they and their friends (not blocked) may join; anyone else gets 403 friends_only. Use it for a player's home, base or room. It rides on the room host manifest, so it works on the shared platform too.

Area rooms are created only by POST /v1/areas/join, with your defineAreas settings: listing "area" in roomTypes does not let clients create one through POST /v1/rooms (they get unknown_room_type). Area settings are clamped (tickHz 1–20, maxPerRoom 1–100, maxLookBytes ≤ 4096), and look keys are lowercase words (no __proto__).

POST /v1/areas/join {key} (auth) returns a room ticket (room_id, shard, join_token, ws_url) for the first area room with space (maxPerRoom, then up to shards overflow rooms; area_full after that). Connect with the usual room WebSocket. Intents: {k: "pose", x, y, fx, fy, a} (up to 16 a second), {k: "emote", e}, {k: "look", look} (≤ 512 bytes, plain values only). State, at tickHz as deltas: {p: {<player_id>: [x, y, fx, fy, anim, emote, emote_at, look]}}; an emote shows for 3 s. Nothing is stored: leaving removes you. Godot: join_area(key), then connect_room(ticket), send_intent, state_changed.

Skirmish areas. Some areas can hold a friendly contest the server judges (tag, snowball fights): list their keys and Kettle adds hearts, blasts and knock-outs to those area rooms. Hits are decided by the room from its own copy of each player's pose; clients only say which way they blast.

export const areas = defineAreas({
  emotes: ["wave"],
  skirmish: {
    keys: ["arena:main", "zone_*"],   // exact keys, or prefixes ending in "*"
    hearts: 3, range: 6, arcDeg: 70,  // these are the defaults
    cooldownMs: 500, outMs: 3000, graceMs: 2000, maxSpeed: 9,
    lineOfSight: (key, ax, ay, bx, by) => !wallBetween(key, ax, ay, bx, by), // optional
  },
});

• POST /v1/areas/join adds the numbers to the room's config when the key matches (skirmishFor(areas.skirmish, key)). Rooms clamp them (hearts 1–20, range 0.5–100, arcDeg 1–360, cooldownMs 50–60000, outMs and graceMs 0–60000, maxSpeed 0.5–1000) and keep them across hibernation. On the platform they travel in the room host's manifest; lineOfSight stays on the AreaRoom class in the game's Worker (like validateLook), so deploy the game Worker before the platform.
• Intent {k: "blast", fx, fy}: a facing (normalised by the room). Refusals: not_skirmish (an ordinary area), bad_blast (zero or non-finite facing), out, cooldown. A blast counts for the blaster, then hits every other player who isn't out or in grace, within range of the blaster, and inside the arcDeg cone or within 0.8 units (point blank), and in sight when lineOfSight is given (a check that throws blocks the hit). A hit takes one heart and records the blaster; at 0 hearts the player is out for outMs, then comes back with full hearts and can't be hit for graceMs. Each knock-out adds one to the blaster's knocks.
• State gets one more key in skirmish areas (only there; p is unchanged): s: {<player_id>: [hearts, hits, blasts, out, knocks, last_by]}. out is 0 or 1, hits and blasts only grow (watch them change to play effects, like emote_at), last_by is the last blaster's player id or "". Deltas carry only what changed.
• Poses there can't move faster than maxSpeed units a second (time counted up to 1 s since the last pose); a faster pose is moved part of the way. The first pose after joining places the player anywhere, and while out a player may jump to their respawn point.
• Joining starts at full hearts; leaving forgets the player's row.

Busy areas: a join claims a seat on its shard (players plus tickets handed out in the last 15 s that haven't connected), so a burst of joins spreads over the shards instead of over-filling the first one.

Shared platform Worker

createKettlePlatform() (workers/platform) serves every game listed in KETTLE_GAMES (comma-separated ids) under /<game>: POST https://<platform>/<game>/v1/auth/anon, /<game>/v1/rooms, and so on. Each request runs through an ordinary createKettle handler with basePath: "/<game>", so room WebSocket URLs carry the prefix. GET /v1/health lists the games.

Forward tokens. Requests the platform passes to a game Worker carry x-kettle-forward, a 30-second token (typ: fwd) bound to the method, path, query string and a hash of the body. It's signed with <G>_FORWARD_SECRET when set (the game Worker's FORWARD_SECRET), else with the join secret; give each game its own.

Usage by game. Bind an Analytics Engine dataset as USAGE and Kettle writes one point per request: blobs [game, route class, status class] (route class: auth, rooms, ws, areas, t, inventory, visits, game, …; status class: 2xx, 4xx, 5xx, 101), doubles [1, latency ms]. On the platform it's written once per request, after any forward to the game Worker; a game's own createKettle Worker writes it too. The admin console reads it to split a shared Worker's requests and errors by game.

The platform holds no game data: room types, shard count, telemetry declarations and area settings come from the room host (createRoomHost(types, { name, shards, telemetry, areas, economy }), read with RoomHostDO.manifest(); name is the game's display name in the admin console). Deployment configs live in deploy/<name>/ (outside Kettle's code). Local dev runs both Workers in one session: wrangler dev -c deploy/realm8/wrangler.jsonc -c <game>/server/wrangler.jsonc.

Economy, visits and game routes run in the game's own Worker, with its catalog, hooks and database:

// The game Worker (bound by the platform as <G>_ROOMS by script name and <G>_APP as a service).
export const GameRooms = createRoomHost({ shift: ShiftRoom, area: AreaRoom }, { economy, areas, telemetry, shards: 64 });
export default createGameWorker({ economy, visits, friends, config, privacy, routes: [...myRoutes] });
export const KettleGameAdmin = createGameAdmin({ economy, config, privacy }); // bound as <G>_ADMIN

The platform still signs players in. It forwards /<game>/v1/inventory*, /v1/visits/* and any other /v1/* path it doesn't serve to <G>_APP, with the caller in a short-lived token signed with the game's join secret (x-kettle-forward, bound to the method and path); createGameWorker refuses requests without one, and route handlers get ctx.playerId as before. The game Worker binds the same D1 database as the platform's <G>_DB and runs the economy sweep on its own cron. Timed activities (builds, upgrades, production) are economy instances whose attributes hold server times, so a client that restarts reads the same finish times back. One telemetry queue serves every game: the platform's consumer files each event under its game's declarations.

Adding a game to the platform (the convention). The platform's KETTLE_GAMES is the one list of platform games; the admin console reads it (ADR-008). In the game's repo, give the room host a display name: createRoomHost(types, { name: "My Game", shards, telemetry, areas, economy }). In the platform deployment, add the KETTLE_GAMES entry, <G>_DB, <G>_ROOMS, <G>_APP and the secrets. Deploy, and the game shows up in the console within 5 minutes, for owners at once and for anyone else once invited. Don't add it to the admin deployment. Add an ADMIN_GAMES entry there only to count the room host's Durable Objects and its D1 in the game's cost (scripts, d1), or for a game that runs Kettle in its own Worker.

Adopting the October 2026 modules (each game). Friends, remote config, privacy, cloud saves, strikes and bans, and the console's writes are opt-in per game: apply migrations 0017–0021 (games that keep their own copy of the migrations copy them first), export KettleGameAdmin (createGameAdmin) from the game Worker and have the platform bind it as <G>_ADMIN, then turn on the modules the game wants. Until then the console is read-only for that game. The full checklist is in docs/runbooks/deploy.md ("For game repos").

Moving a game from its own Worker to the platform: keep the room host export; turn createKettle({...}) into createGameWorker({ economy, visits, routes }); move telemetry, areas and the shard count into createRoomHost's options and add its name; in the platform deployment add the game id to KETTLE_GAMES, <G>_ROOMS (script_name), <G>_APP (service), <G>_DB (the game's existing D1 database keeps its players) and the secrets <G>_JWT_SECRET (the game's current JWT_SECRET, so existing sessions stay valid) and <G>_JOIN_SECRET (= the game Worker's JOIN_SECRET); then point clients at https://<platform>/<game>. Keep the game's Worker on workers_dev: false so it's reachable only through the platform.

Friends and presence

defineFriends({ max: 200, statuses: ["online", "in_room"], presenceTtlSec: 120, minBand: "13to15" }), passed as friends (K-4.01, migration 0017_friends). Every player has a friend code (8 characters without look-alikes; POST /v1/friends/code replaces it). A request goes by code or by player id (from a handle look-up, a leaderboard row, a trade); asking someone who already asked you makes you friends at once. Friendships are mutual and capped on both sides (max, default 200), checked inside the same write so racing accepts can't overfill. A declined request can't be sent again for declineCooldownDays (7); unanswered ones expire after requestTtlDays (30; the cron prunes). Blocks (moderation) hide friends and refuse requests in either direction. With minBand set, only players of at least that age band send or receive requests, and a player without a declared band can't; refusals caused by the other side answer unavailable, so a player can't tell a block from an age gate.

Presence. While playing, the client sends POST /v1/friends/presence {status, room?} every minute or so: status is one of the game's ids (no free text; null = offline) and room an optional room code friends can join. Friends see it in GET /v1/friends for presenceTtlSec after the last heartbeat. hidden: true opts out (kept until changed), and friends then see nothing. Each heartbeat is one D1 write.

On the server: createFriendsStore(env.DB, friends) gives friendIds(player) and areFriends(a, b) for the game's own rules (gifts only to friends, a friends-only place).

Remote config and feature flags

defineConfig({ defaults, flags, check? }), passed as config (K-2.02, ADR-016, migration 0018_config). defaults holds every value the game reads (any JSON); flags names the features it can switch. Admins publish documents in the console's Config tab:

{ "values": { "shop": { "discount": 15 } },
  "flags": { "new_shop": { "on": true, "pct": 25, "platforms": ["ios"], "min_app": "1.4.0", "countries": ["DE", "FR"], "bands": ["adult"] } } }

A document must have the defaults' shape (only known keys, the same JSON types, nested objects checked the same way) and pass the game's check(values). Values are merged over the defaults key by key. A flag is on when on is true and every rule given matches: pct is a stable share of players per flag (signed-out callers only get 100 %), platforms (ios, android, web, windows, mac, linux, console, other), min_app compares dotted numbers, countries uses Cloudflare's view of the request, bands the player's declared age band.

Clients call GET /v1/config?platform=ios&app=1.4.2 (signed in for percentages and bands) and get { version, values, flags } with an ETag; sending it back as If-None-Match answers 304. Every publish is a new numbered version kept in the game's D1; making an older version (or 0, the defaults) live is a rollback. Publishing names the version the author saw, so two admins can't overwrite each other (stale). On the server, createConfigStore(env.DB, config).resolve(...) gives a room or route the same values.

Cloud saves

defineSaves({ slots: ["main", "settings"], inlineBytes: 16_384, maxBytes: 512_000, bucket: "SAVES", validate }), passed as saves (K-2.04, ADR-018, migration 0020_saves). Each player has the game's named slots, each holding one JSON document (an object or array) and a version.

• GET /v1/saves lists the slots; GET /v1/saves/<slot> reads one.
• POST /v1/saves/<slot> {data, base_version} writes when the slot is still at base_version (0 for the first save). If another device saved since, the answer is 409 {error: "conflict", current} with the newer save: merge by your game's rule and write again with current.version. Kettle never merges.
• Saves up to inlineBytes (default 16 KB) live in D1; larger ones (up to maxBytes, at most 900 KB) in the R2 bucket bound under bucket, written before the row moves and deleted when replaced. Without a bucket the cap is 64 KB.
• validate(slot, data) is your shape check (an error message refuses it with bad_save).
• Never put currencies, items or entitlements in a save: they live in the economy, where only the server grants.
• Export includes saves (R2 ones too) and deletion erases them, with privacy set.

Maps, 3D terrain and maps that change

Kettle serves map tiles from R2 through its CDN Worker (K-2.03, ADR-019): vector tiles (a Protomaps basemap extract) and height tiles for 3D terrain, Terrarium-encoded PNGs (metres = R×256 + G + B/256 − 32768; MapLibre reads them as raster-dem with encoding: "terrarium"). A game can change its maps during play: craters, sinkholes, a volcano's collapsed cone, a flattened building site.

Base archives are PMTiles files in the CDN bucket at tiles/<set>.pmtiles, built and uploaded with tools/tiles:

pnpm tiles extract --bbox -118.70,33.70,-117.90,34.35 --maxzoom 15 --out la.pmtiles   # vector, newest Protomaps build
pnpm tiles dem --bbox -118.70,33.70,-117.90,34.35 --minzoom 8 --maxzoom 13 --out la-dem.pmtiles   # heights, AWS Terrain Tiles
pnpm tiles upload --file la-dem.pmtiles --set la-dem --bucket kettle-cdn-staging

extract needs the pmtiles CLI; upload uses wrangler (files up to 300 MB; larger ones with rclone over R2's S3 API). Treat a set as immutable: the CDN caches TileJSON for an hour and tiles for a day, so upload changed data under a new set name. Credit the data where the map is shown: OpenStreetMap contributors for the basemap, the Terrain Tiles sources for heights (both are in the TileJSON attribution).

CDN routes (public, cached at the edge on the custom domain):

Declaring maps: defineMaps({ bucket: "MAPS", space: "<game id>", maps: { world: { dem: "la-dem", vector: "la", demZooms: [10, 13], attribution } }, maxTilesPerEdit: 256 }), passed as maps to createGameWorker / createKettle (and to createGameAdmin for the console), and to createRoomHost(types, { maps }) so rooms can edit (this.maps). The Worker that edits binds the CDN bucket as MAPS and sets CDN_URL (the CDN origin) in its vars. Migration 0023_maps (no player data).

Instances are created on first use (any id of lower-case letters, digits, _, -): one per world shard, season or match. Each has a version that every change bumps.

Each returns {version, tiles: [{layer, z, x, y}]}. An op is applied at every zoom in demZooms (each pixel evaluated at its geographic centre), and only tiles whose heights changed are written. More than maxTilesPerEdit tiles → edit_too_large; one edit at a time per instance (map_busy, retry). Broadcast the result from the room (a game message such as <game>.map with {map, instance, version, tiles}) so clients refetch just those tiles with the new ?v=.

Clients: GET /v1/maps/<map>/<instance> → {version, tilejson, layers: {dem, vector?}, overlay, attribution, dem_zooms} (tile templates on the CDN with ?v=); GET /v1/maps/<map>/<instance>/changes?since=<version> → {version, reset, edits: [{version, kind, tiles}]} for a client that was away (reset: true: refetch everything, e.g. after a reset or once the log, kept 30 days, no longer reaches back).

Content packs

Files a game downloads after install (levels, art, audio, Godot .pck packs), published as immutable versions and announced in a signed manifest (K-4.05, ADR-020, migration 0024_content). defineContent({ bucket: "MAPS", space: "<game id>", packs: ["levels", "music"] }), passed as content to createGameWorker / createKettle and createGameAdmin; the Worker binds the CDN bucket and sets CDN_URL, and holds the signing key as the secret CONTENT_KEY (keyEnv).

1. pnpm content keygen --out ./keys makes an RSA-2048 key: put content-key.pem in the game Worker (wrangler secret put CONTENT_KEY), bake content-public.pem into the game.
2. pnpm content upload --file levels.pck --space <game> --pack levels --version 1.2.0 --bucket kettle-cdn-staging stores it at content/<space>/<pack>/<version> and prints its SHA-256.
3. In the console's Content tab, register the version (Kettle reads the object and checks the hash; add a minimum app version and platforms if needed), then roll it out to a share of players (stable per player) or make it live for everyone; roll back or turn a pack off the same way.

GET /v1/content/manifest?platform=&app= (signed in) → {manifest, signature, key_id}: manifest is JSON text {space, generated_at, packs: [{id, version, url, sha256, size, min_app}]}, signature the base64 RSASSA-PKCS1-v1_5 / SHA-256 signature of exactly that text. A client checks the signature with its baked-in public key before parsing, downloads from url (the CDN; Range works for resuming) and checks the SHA-256 before using the file. Players outside a rollout share, or whose platform or app version a new version excludes, get the previous version. Versions are dotted numbers and never change once registered.

Privacy: data export and account deletion

definePrivacy({ graceDays: 7, tables, onDelete }), passed as privacy (K-4.06, ADR-017, migration 0019_privacy). Kettle keeps one inventory of every table that holds a player's rows (KETTLE_PLAYER_DATA; docs/privacy.md is the readable version); a test fails when a migration adds a player column it doesn't cover.

• GET /v1/me/export: the player's rows from every table, as JSON (a few times an hour; tokens and other secrets left out; at most 5,000 rows per table, truncated lists the rest).
• POST /v1/me/delete schedules deletion after graceDays (default 7, at most 25, so it's done within 30 days); POST /v1/me/delete/cancel undoes it until then; GET /v1/me/delete shows the date. The game's cron (the scheduled handler of createKettle or createGameWorker) erases due accounts in one D1 batch:
  • rows that are only the player's are deleted (account, sessions, links, age band, friends, blocks, inventory, scores, pushes, places, plots);
  • rows other players or money records need are kept with the player id replaced by a random deleted:… id: ledger lines and operations, store purchases, trades, listings, gifts, guild feed, paid draws;
  • open trades and listings are closed first, and a guild the player led passes to the next member (pass guilds to definePrivacy's store, as createKettle does).
• Your own tables: definePrivacy({ tables: [{ table: "g_saves", column: "player_id" }, { table: "g_scores", column: "player_id", erase: "anonymize" }] }); onDelete(db, playerId) returns extra statements for the same batch (or does other cleanup, such as R2 blobs).

The 7-day default grace period and the split between deleted and anonymized rows were approved by the platform owner on 2026-10-23. The raw telemetry archive (R2, K-2.01) holds only the pseudonymous player hash and is not rewritten on deletion; it ages out under the bucket's 13-month lifecycle rule (also approved). Games selling through the App Store or Google Play should turn privacy on: both stores require in-app account deletion.

A deleted player's access token keeps working until it expires (at most 15 minutes); the refresh token is gone, so the session ends there. Staff can export, schedule, cancel and (owners) erase at once from the console's Players tab.

SDKs

Both SDKs keep state current from welcome, snapshot and delta, answer pings, track round-trip time and reconnect when a room code is known, with exponential backoff and full jitter (a random wait up to 0.25 s, 0.5 s, … 8 s; 10 tries), so a deploy's dropped clients don't all come back at the same instant. After the last try the TS SDK calls room.onGaveUp("attempts") and Godot emits reconnect_failed("attempts").

TypeScript (@kettle/client-ts)

const kettle = new KettleClient("https://api.example.com/my-game", "web/1.0", "1.0.0");
await kettle.signInAnonymously();
const ticket = await kettle.createRoom("click");      // or kettle.joinRoom("K7PX3M")
const room = await kettle.connect(ticket);
room.on("delta", () => render(room.state));
room.sendIntent({ action: "click" });                 // returns seq

Godot (addons/kettle)

Add KettleClient as a node and set base_url.

Admin console

workers/admin (deployment deploy/realm8/admin.wrangler.jsonc, ADR-006) is one Worker serving three things:

• the public landing page at /;
• this guide at /docs/;
• the console at /console/, with its API at /admin-api/*.

Signing in. Admins sign in with an emailed link, sent through Estra Mail (MAIL_API_KEY), with Resend as the fallback (RESEND_API_KEY). There are no passwords. A session is a __Host- cookie (HttpOnly, Secure, SameSite=Strict). Writes also need the console's Origin and the x-kettle-admin header.

Roles:

• Platform owners (OWNER_EMAILS, a secret) see every game and invite admins.
• Game admins manage alerts and members, export data, grant and revoke items, publish config and schedule account deletion.
• Viewers read only.

A game you have no role in answers 404, the same as a game that doesn't exist.

Home (every signed-in admin). The console opens on an activity chart for all the games you can see: one line per game over 30 days (active players, new players or requests), each game in its own fixed colour (the same dot as in the top bar), with a crosshair tooltip, a legend that highlights a line and a table view. Below it, a tile per game with its latest number and trend; owners also get the month's cost overview there. API: GET /admin-api/activity?metric=active_players|signups|worker_requests|players_total&days=7..90 → {metric, days, series: [{id, name, values}], trend: {<game>: {now, prev, week}}, trend_all} (null for a day without numbers).

24-hour comparisons. The main numbers (new players, active players, requests, error rate, cost) carry a small arrow and % against the 24 hours before: accent when better, red when worse, grey under 1%. Estimated cost also shows the average list-price cost per hour over the last 24 hours (before free allowances), against the 24 hours before and the same 24 hours a week earlier. Player counts come from each game's own database; requests and cost come from hourly snapshots the collector keeps for 9 days, so those arrows appear after the first day of data and "vs last week" after eight. Each trend is {now, prev, week}, null where there is no data yet; GET /admin-api/games/<g>/dashboard returns one per metric under trend, and /admin-api/overview gives each game's cost_hour. Each trend also has usual, the median of the 7 complete days before; a number at least twice or at most half of it gets a "2.4× usual" badge (only above a small floor, so tiny games aren't flagged).

Game page, deeper views. Under the main numbers: monthly active players, stickiness (the last 24h's players ÷ the month's), requests per player and list-price cost per player per day, each against the 24h before. Last 24 hours, hour by hour draws the last 24 hours against the 24 before and the same hours a week earlier (active players, requests or cost per hour); a heatmap shows when players play over the last 7 days, in the viewer's local time. Players has new vs returning players per day and a retention table: of each day's new players, the share seen again on day 1, 2, 3, 7, 14 and 30. Cost by resource stacks the list-price cost per day of Workers, Durable Objects and D1. Player activity is read from the game's database (a refresh-token row is written on every sign-in and refresh, so a player who plays is seen about every 15 minutes); requests and cost per hour come from the collector's snapshots. APIs: GET /admin-api/games/<g>/hourly → {start, hours, active, requests, cost} (one value per hour, oldest first, null without data); GET /admin-api/games/<g>/players-insight → {retention_days, retention: [{day, size, back}], days: [{day, fresh, returning}], mau: {now, prev}}; the dashboard's cost_daily → {groups, days}.

Collector health (owners). Below the cost overview, one tick per hour for the last 48 hours: every source answered, some failed (hover for which), or no run recorded at all. GET /admin-api/collector → {start, slots: [{hour, runs, failed}]}. A run that crashes is recorded with a collector failure instead of leaving no trace. A player has a link of their own: #game=<g>&tab=players&player=<id>.

On-call (owners). On the home page: pager channels (an ntfy topic, Pushover, or a JSON webhook) with a test page each; alert rules can tick Page to reach them as well as email. Built-in health alerts page once a day per problem: the collector missed hours, a game's error rate is ≥ 3× its usual day, a burst of errors in the last hour, or cost per hour ≥ 2× usual. The panel also lists weekly D1 exports to R2 (opt-in) and recent health alerts. Runbooks: docs/runbooks/on-call.md, docs/runbooks/backups.md. API: GET|POST /admin-api/pager, POST /admin-api/pager/<id>/test, DELETE /admin-api/pager/<id> (owners).

What a game's page shows:

• Dashboard: signups and active players day by day, Cloudflare usage (Worker requests and errors, Durable Object requests and time, D1 rows and size), and the estimated cost this month with a projection. Cost is estimated from analytics and published prices. The account's included amounts are shared across games in proportion to use.
• Data browser: read-only browsing of the game's D1 tables, with sort, filter, paging and a "New signups" preset. refresh_tokens and internal tables are never shown. CSV export is limited to admins, capped at 50,000 rows, audited, and neutralises spreadsheet formulas.
• Alerts: email when cost (month to date or projected), usage, signups or active players, or the error rate crosses a threshold. Each alert sends at most once per day, or once per month for cost.

Which games it shows. Every game on the shared platform Worker appears on its own: bind the platform's KettlePlatformAdmin entrypoint as PLATFORM (a service binding with entrypoint: "KettlePlatformAdmin"; named entrypoints are reachable only through service bindings) and set PLATFORM_USAGE_DATASET to the platform's USAGE dataset. The console re-reads the platform's game list every 5 minutes and on each hourly run, takes names from createRoomHost's name (else the id), and reads a game's database through the platform, which runs only single SELECT statements. ADMIN_GAMES adds games that run elsewhere and the Worker scripts and D1 ids behind a game's cost (Durable Objects, D1); where both list a game, ADMIN_GAMES wins field by field. A <G>_DB binding on the console, when present, is used instead of the platform. New games show up for owners at once; admins and viewers still need to be invited.

Reports (review queue, K-3.07). The Reports tab lists what players reported (moderation, above): Open (reported, nobody has decided; auto-hidden ones first, then the most reported), Hidden and Decided, each target with its reason counts, and the individual reports in a side panel. Viewers read; game admins Take down or Restore, which marks the target decided (new reports no longer change it) and is written to the audit log. The console decides through the game's own <G>_DB when bound, else through the platform's single moderation write. Find the reported content itself in the data browser (the game's own tables). API: GET /admin-api/games/<g>/reports?state=open|hidden|decided&offset=, GET /admin-api/games/<g>/reports/<kind>/<target>, POST /admin-api/games/<g>/reports/<kind>/<target> {action: takedown|restore}.

Players (K-3.07). Find a player by id, the first characters of an id, or handle; see their account (created, last sign-in, age band, linked providers by name only), inventory, friends, guild, reports, purchases and a pending deletion, and page through their ledger with each line's reason and who made it. Game admins grant and revoke items from the game's catalog with a required note (both audited; the form's key makes a double submit apply once; revoke takes what's there and reports the rest), download the player's data and schedule or cancel deletion. Only platform owners erase at once. API: GET /admin-api/games/<g>/players?q=, GET …/players/<id>, GET …/players/<id>/ledger?before=, POST …/players/<id>/grant|revoke {items, note, op_key}, GET …/players/<id>/export, POST …/players/<id>/delete {action: schedule|cancel|now}, GET …/catalog.

Standing, saves and purchases (K-3.05, K-3.07). A player's page also shows their ban and strikes (game admins strike, ban for some days or for good, and unban, each with a note; audited), their save slots, and their store purchases. The Purchases tab lists every purchase newest first, with month totals (list-price revenue and refunds) and filters for refunded and flagged ones (granted past a money cap or age gate). API: POST …/players/<id>/strike|ban|unban {reason, days?, note}, GET …/moderation/reasons, GET …/players/<id>/purchases, GET /admin-api/games/<g>/purchases?state=granted|revoked&flagged=1&offset=.

Config (K-2.02). The versions with notes and authors, the live document and the game's defaults; admins edit a new version as JSON, Check it against the game's rules, see what changes against the live one, Publish, or make any earlier version (or the defaults) live again. All audited. API: GET /admin-api/games/<g>/config, GET …/config/<v>, POST …/config/check {doc}, POST …/config {doc, note, if_version}, POST …/config/activate {version, if_version}.

The game's admin entrypoint. Grants, config and deletion need the game's own code (its catalog, defaults and tables), so the game's Worker exports one more class and the console reaches it through a service binding:

export const KettleGameAdmin = createGameAdmin({ economy, config, privacy, guilds, moderation, saves });

A platform game is bound on the platform as <G>_ADMIN ({ "binding": "<G>_ADMIN", "service": "<game worker>", "entrypoint": "KettleGameAdmin" }); the platform's KettlePlatformAdmin forwards /games/<g>/admin/* to it. A game with its own Worker is bound the same way in the admin deployment. Without it the console reads as before and answers writes with game_admin_unbound. Named entrypoints are reachable only through service bindings (docs); the console checks roles and writes the audit log, and by (console:<admin id>) lands on the economy operation as its ref.

Free allowance (owners). The console home shows how far the Cloudflare account is into each included amount of the Workers Paid plan this billing cycle: Workers requests and CPU time, Durable Object requests, duration, SQLite rows read and written, and stored data, D1 rows read and written and storage, and KV, Queues and R2 once they're used. Each category has a bar with a tick per 10%, the projection to the reset (used so far plus the last 7 full days' daily average times the days left; storage stays at its latest size), how much over that would be and what it would cost, each game's share, and the projected bill ($5 base plus overage). The numbers are account-wide (every Worker, Durable Object and database in the account, the admin Worker too), since that's what Cloudflare bills. Included amounts reset on the subscription renewal date, read from the account subscriptions API (CF_API_TOKEN with Billing: Read), else from the BILLING_DAY var (1–28), else the calendar month with a warning. Each time a category passes another 10% (and the first time it's on pace to go over), owners get one email per collector run, and the step appears on the Milestones timeline: one lane per category across the cycle, a dot where each step was recorded (steps recorded within hours of each other share a dot), today's line, and the reset at the right; hover, focus or tap a dot for the day, time, steps and the amount used then. The steps start again each cycle. For Workers requests, CPU time and Durable Object requests, an expanded row also names the account's top Worker scripts and the game that owns each, so use outside the games' own scripts (the platform Worker, room hosts, the admin Worker) can be traced. API: GET /admin-api/allowance. Per-game cost estimates and cost alerts use the same billing cycle.

Data sources. An hourly cron collects from each game's D1 (<G>_DB or through the platform), the GraphQL Analytics API (CF_API_TOKEN with Account Analytics: Read and Billing: Read, plus CF_ACCOUNT_ID) and the USAGE dataset. Game ids appear only in the deployment's KETTLE_GAMES, ADMIN_GAMES and bindings.

Versioning, security and limits

• Protocol versions. Servers accept the current protocol version and the one before it. Clients that are too old get unsupported_version and should ask players to update.
• Pre-1.0. Until Kettle reaches 1.0, APIs can change between versions. Pin the commit you build against.
• Server authority. Clients send intents; only the server changes state. Never trust a client for scores or currency.
• Secrets. JWT_SECRET and JOIN_SECRET stay in Worker secrets, never in code or clients.
• Privacy. Kettle stores a player id and hashed refresh tokens. Location is city-level and never stored. Telemetry rejects undeclared fields. Players can export their data and delete their account (privacy); docs/privacy.md lists what is stored, why, and what deletion does.

Rate limits. Bind two Workers Rate Limiting namespaces and Kettle uses them: RATE_AUTH (keyed by client IP: POST /v1/auth/anon, /v1/auth/refresh, /v1/auth/signin, /v1/auth/email/*) and RATE_PLAYER (keyed by player: rooms, room codes, areas, telemetry). Over the limit, the route answers 429 {"error":"rate_limited"}. Keys carry the game id, so on the shared platform one binding serves every game. Without the bindings nothing is limited (local dev, tests).

"ratelimits": [
  { "name": "RATE_AUTH", "namespace_id": "8001", "simple": { "limit": 20, "period": 60 } },
  { "name": "RATE_PLAYER", "namespace_id": "8002", "simple": { "limit": 60, "period": 60 } }
]

Not available yet

These are planned but do not exist in code today. Don't build against them yet.