Game config
| Field | Default | |
|---|---|---|
key | — | A URL path segment |
kind | — | The model discriminator |
mode | match | Or table |
players | 2 | Match: exact roster. Table: maximum seats |
rules | — | Opaque to the session; validated by the model |
turnTimeoutMs | — | Alarm-enforced. Null waits indefinitely |
leaderboard | — | { board, points: { win, draw, loss } } |
Session phases
What each one admits, and how a session moves between them, is sessions and lifecycle.
| Phase | |
|---|---|
open | Waiting for the roster |
active | Play underway |
resolved | Terminal |
abandoned | Terminal — the deadline passed unfinished, or a management client closed it |
The config is snapshotted at creation. A later edit cannot change a session in flight.
The model interface
Writing your own is the page on implementing it. Routes below are shaped like every route in the kit and refuse with an ordinary error code.
interface GameModel<Config, State> {
kind: string;
config: z.ZodType<Config>;
state: z.ZodType<State>;
minPlayers?: number; // default 2
maxPlayers?: number; // undefined = unbounded
movesBalances?: boolean; // emits ledger effects; needs ledger composed
action?: z.ZodType; // one player's move, checked before apply
view?: z.ZodType; // what redact returns, for clients
init(ctx): State;
apply(ctx, state, playerId, action): ApplyResult<State>;
isComplete(ctx, state): boolean;
resolve(ctx, state): ResolveResult;
redact(ctx, state, viewerId, revealed): unknown;
onJoin?(ctx, state, playerId): ApplyResult<State>; // table
onLeave?(ctx, state, playerId): ApplyResult<State>; // table
}action and view are what a client in any engine reads. Both are published in the Worker’s asyncapi.json as <gameKey>.action and <gameKey>.view. A declared action refuses a malformed move with validation/invalid_input before apply runs; view is never parsed on the way out. The socket contract has the rule.
The context
| Field | |
|---|---|
sessionId | Build stable ledger refs from it |
config | Already validated |
players | Join order — and turn order |
now | From the object. Never read a clock in a model |
random | The seeded stream |
Purity rules
| May draw randomness | May touch a database | |
|---|---|---|
init | Yes | No |
apply | Yes | No |
resolve | No | No |
redact | No | No |
A model declares ledger effects; the object settles them.
Ledger effects
{ op: "hold", userId, currency, amount, ref }
{ op: "capture", ref, amount?, memo? }
{ op: "release", ref }
{ op: "credit", userId, currency, amount, ref, memo? }
{ op: "debit", userId, currency, amount, ref, memo? }
{ op: "transfer", … }Every effect carries a ref. A deterministic model re-emits the same refs on a replay, so a payout pays once.
A hold a player cannot cover rejects the action, and the transition is never persisted.
Randomness
| Seed | 128 bits at creation. Secret until terminal |
seedHash | SHA-256, committed up front in the view’s fairness |
| Cursor | Advanced as a model draws; persisted by the object |
ctx.random.next() // float in [0, 1)
ctx.random.int(1, 6)
ctx.random.pick(items)Routes
Every one requires authentication. A session reads only for its members; who reads a session has the rule.
| Route | |
|---|---|
POST /multiplayer/games/:game | |
POST /multiplayer/sessions/:id/join | Anyone who holds an open session’s id |
POST /multiplayer/sessions/:id/action | The body is the action, checked against the game’s action schema when it declares one. Current members |
POST /multiplayer/sessions/:id/leave | Table. Anyone who ever joined. Closes the leaver’s sockets |
POST /multiplayer/sessions/:id/close | Table. Current members. Settles every seat out first, so a bet still open is released |
GET /multiplayer/sessions/:id | Your redacted view. Current members only |
GET /multiplayer/sessions/:id/result | Once terminal. Anyone who ever joined, a player who left included. voidedAt says when it was voided, null while it counts |
GET /multiplayer/sessions/:id/socket | WebSocket. Offer pithy.multiplayer.v1; frames are the socket contract. Current members |
Management
With the control plane composed, a management client sees the games in play and how they ended, and acts on them with its own credential. Every path sits under admin/, so none can collide with a player route, and each is built from the mounted basePath.
| Route | Scope | |
|---|---|---|
GET /multiplayer/admin/sessions | multiplayer:sessions:read | The sessions in flight, newest first: game, phase, players and age. Takes game, phase (open or active), cursor and limit |
GET /multiplayer/admin/sessions/:id | multiplayer:sessions:read | One session, read from its Durable Object: the players, everyone who ever joined, who is connected, the deadline and how it ended. Never the game’s state |
GET /multiplayer/admin/results | multiplayer:sessions:read | The results, most recently ended first: status, players, scores, winner or draw, and any void with what each consumer did. Takes game, voided, cursor and limit |
POST /multiplayer/admin/sessions/:id/close | multiplayer:sessions:moderate | End a session in flight with no result. It turns abandoned |
POST /multiplayer/admin/results/:id/void | multiplayer:sessions:moderate | Void a result, then take it back out of every composed consumer. :id is the session’s id |
A session is a Durable Object addressed by its id, so multiplayer keeps an index. Each session writes a row to pithy_multiplayer_sessions when it opens, rewrites it as its roster and phase move, and deletes it when it ends: resolved, abandoned by its deadline, closed by its players, or closed by a management client. A session in flight before the index existed joins it at its next join, leave or phase change.
Each act takes an idempotencyKey and a required reason. A replayed key answers replayed: true, changes nothing and emits nothing. A blank reason is refused before anything is written.
Close settles a table’s seats out first, releasing what each still holds, as their leaving would. Every member then gets a last state frame whose outcome.closedReason is the reason you sent, and their sockets close. Write the reason for the players. A session that already ended is multiplayer/invalid_transition (409).
Void marks the result void, then calls each composed consumer with its id: @pithy-sh/leaderboard removes the entries the result put on a board, and @pithy-sh/rating recalculates every player whose outcomes carried it. The response lists each consumer as done or failed, with its own report. A consumer that threw, is too old to void, or is no longer composed is failed with its error, never folded into success, and the void stands. A consumer not composed in this Worker is absent.
A retry runs only what did not finish. A new key on a void with a consumer still failed or pending runs those consumers again, and marks them pending while it does. Voiding a result already void with every consumer done changes nothing. While a void or a retry may still be running — a consumer pending, and the key holding the void spent less than 15 minutes ago — a new key is core/conflict, and changes and spends nothing, so no consumer runs beside itself. Every key a void or a retry was sent with stays spent in pithy_multiplayer_void_keys: sent again it is a replay, and on another result it is core/conflict.
Each act that changed something writes one audit event, multiplayer/session_closed or multiplayer/result_voided, with the connection, the session, the game, the players and the reason. The read is all GETs, so pithy dashboard connect grants it by default; the acts are POSTs and never are.
Error codes
| Code | |
|---|---|
multiplayer/session_not_found | |
multiplayer/game_not_found | |
multiplayer/not_a_member | 403. The session does not admit you for this route |
multiplayer/session_full | |
multiplayer/invalid_move | The action is illegal |
multiplayer/invalid_transition | Legal in general, wrong right now |
validation/invalid_input | The action does not match the game’s action schema, or a socket frame does not match its schema |
Bindings and storage
SESSIONS | The MultiplayerSession Durable Object, with its class-migration tag |
DB | pithy_multiplayer_results, the durable result row. pithy_multiplayer_sessions, the index of sessions in flight. pithy_multiplayer_void_keys, every key a void was sent with |
Session and game state live in the object’s own SQLite-backed storage, capped at 10 GB per object, Zod-validated on every read.
A person’s data is anonymized, not erased. When an account is purged, their id in every result they played in is replaced, so the other players’ results stay. A session still in flight that they play in is closed with no result, the other players told why, and leaves the index. Account lifecycle has every capability’s part.
Cost facts
| WebSocket messages | 20:1 billing ratio |
| Duration | The full 128 MB, and only while awake |
| Hibernation | A session waiting on a turn bills no duration |
As of 2026-07-16. Cloudflare’s pricing page is the authority.
A single setInterval forfeits hibernation entirely.
License
MIT.