Multiplayer reference

Game config

Session phases

What each one admits, and how a session moves between them, is sessions and lifecycle.

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

  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
}

The context

Purity rules

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

ctx.random.next()        // float in [0, 1)
ctx.random.int(1, 6)
ctx.random.pick(items)

Routes

Every one requires authentication.

Error codes

Bindings and storage

Session and game state live in the object’s own SQLite-backed storage, capped at 10 GB per object, Zod-validated on every read.

Cost facts

As of 2026-07-16. Cloudflare’s pricing page is the authority.

A single setInterval forfeits hibernation entirely.

License

MIT.