@homie-rocks/studio 0.45.3 → 0.46.2

package/netplay/netplay.ts

@@ -529,6 +529,7 @@ export interface NetStats {
   offline: boolean;
   rtt: number | null;
   offset: number;
+  telemetrySource: 'server' | 'browser' | 'offline' | 'disconnected';
   snapHzIn: number;
   snapHzOut: number;
   inputHzIn: number;
@@ -550,6 +551,8 @@ export interface NetStats {
   stateKeys: number;
   peers: number;
   reconnects: number;
+  /** Most recent loss, retained after recovery so a brief reconnect is diagnosable. */
+  lastDisconnect?: { at: number; why: string; code: number | null; reason: string | null; silentMs: number };
   /** Revision 9: times a link that was up went down (a reconnect that worked on the first knock counts once). */
   drops?: number;
   /** Revision 9: where this browser stands with its room. */
@@ -1695,6 +1698,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
   let ws: WebSocketLike | null = null;
   let attempt = 0;
   let reconnects = 0;
+  let lastDisconnect: NetStats['lastDisconnect'];
   let drops = 0;
   let heartbeats = 0;
   /** My welcome gave me back the seat my token named (the same player), and a newer build is live (section 23). */
@@ -1777,6 +1781,9 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
   let playableSent = false;
   let autoArmed = false;
   let snapSeen = false;
+  /** The newest tick this socket has been sent (rules games): said on inputs and pings as `g`, so a Gate that
+   * finds this player far behind the room sends it fewer, fresher frames instead of every one late. */
+  let gotTick: number | null = null;
   let loadingAt = 0;
   const createdAt = (typeof performance !== 'undefined' ? performance.now() : Date.now());
   const arrived: ArrivalInfo = { mode: arrival, by: null, playableMs: null, explicitMs: null, lateMs: null };
@@ -2619,6 +2626,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     if (wasOffline && rulesGame) rulesNotice('Connection restored. Joining the online round.');
     offline = false;
     connected = true;
+    gotTick = null;
     downSince = 0;
     attempt = 0;
     if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
@@ -2764,6 +2772,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     if (Array.isArray(m['c'])) s.c = m['c'] as ControlWire[];
     if (m['hb'] === 1) s.hb = 1;
     if (typeof m['e'] === 'number') s.e = m['e'];
+    if (!local && rulesGame) gotTick = s.k;
     if (acceptSnap(s, bytes, true, local)) { emit('snapshot', s); if (!snapSeen) { snapSeen = true; autoPlayable(); } }
   }
 
@@ -2881,7 +2890,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     pingsOut.set(c, c);
     if (pingsOut.size > 16) { const first = pingsOut.keys().next().value; if (first !== undefined) pingsOut.delete(first); }
     // A hidden host's yield is behind its checkpoint in the sender: the relay hears of the hidden tab after both.
-    raw({ t: 'ping', c, hid: hidden() && !rulesSender?.handing, ...(rulesGame ? { readySpeed } : {}) });
+    raw({ t: 'ping', c, hid: hidden() && !rulesSender?.handing, ...(rulesGame ? { readySpeed } : {}), ...(gotTick !== null ? { g: gotTick } : {}) });
   }
 
   function sendCheckpoint(): void {
@@ -2939,12 +2948,13 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
   function statsNow(): NetStats {
     const t = wall();
     return {
+      telemetrySource: offline ? 'offline' : !connected ? 'disconnected' : opts.rulesHost?.mode === 'server' ? 'server' : 'browser',
       role, seat, host, connected, offline, rtt, offset: Math.round(offset),
       snapHzIn: snapIn.hz(t), snapHzOut: snapOut.hz(t), inputHzIn: inputIn.hz(t), inputHzOut: inputOut.hz(t), idleInputsSkipped: idleSkipped,
       lastSnapBytes, maxSnapBytes, bytesInPerS: perSecond(bytesIn), bytesOutPerS: perSecond(bytesOut),
       interpDelay: Math.round(interpDelay()), snapAgeP90: Math.round(ageP90), starvedPct: +starvedPct.toFixed(3), rejectedSnaps,
       owned: api.owned, pending: sentHist.length, stateKeys: stateMap.size,
-      peers: peers.size, reconnects, drops, link, heartbeats, promotions, round: roundInfo ? roundInfo.n : null,
+      peers: peers.size, reconnects, lastDisconnect, drops, link, heartbeats, promotions, round: roundInfo ? roundInfo.n : null,
       decides: { asked: decideStats.asked, ai: decideStats.ai, local: decideStats.local, floor: decideStats.floor, msP50: [...decideStats.ms].sort((x, y) => x - y)[Math.floor(decideStats.ms.length / 2)] ?? null },
     };
   }
@@ -2980,8 +2990,10 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
     else paintLink();
   }
 
-  function lost(sock: WebSocketLike, why: string): void {
+  function lost(sock: WebSocketLike, why: string, event?: unknown): void {
     if (ws !== sock) return;
+    const detail = event && typeof event === 'object' ? event as { code?: unknown; reason?: unknown } : null;
+    lastDisconnect = { at: Date.now(), why, code: typeof detail?.code === 'number' ? detail.code : null, reason: typeof detail?.reason === 'string' ? detail.reason.slice(0, 160) : null, silentMs: Math.max(0, wall() - lastMsgAt) };
     ws = null;
     sock.onclose = null; sock.onmessage = null; sock.onerror = null; sock.onopen = null;
     if (why !== 'closed') { try { sock.close(4000, why); } catch { /* gone */ } }
@@ -3011,13 +3023,14 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       lastMsgAt = wall();
       raw({
         t: 'hello', rules: rulesGame, v: NETPLAY_VERSION, rev: NETPLAY_REVISION, token, name: name || undefined, device, want, canHost: asAgent && asAgent.hands === 'host' ? false : canHost, game: opts.game, max: opts.maxPlayers,
+        ...(rulesGame ? { coast: 1 } : {}),
         ...(watching ? { watch: true } : {}), ...(caps.size ? { caps: [...caps] } : {}), ...(asAgent ? { agent: asAgent } : {}),
         // Revision 9 (an older relay ignores both): the game's revision and what this build can do.
         ...(version ? { ver: version } : {}), ...(features.length ? { feat: features } : {}),
       });
     };
     sock.onmessage = (ev) => onMessage(ev.data);
-    sock.onclose = () => lost(sock, 'closed');
+    sock.onclose = (event) => lost(sock, 'closed', event);
     // Browsers follow an error with close; Node's WebSocket, on a refused connection, never does.
     sock.onerror = () => lost(sock, 'error');
   }
@@ -3415,7 +3428,7 @@ export function createNetplay<S = unknown, A = unknown, C = unknown>(opts: Netpl
       if (seat === null || !entries.length) return false;
       if (rulesHost && offline) { rulesHost.frame({ t: 'in', from: seat, e, k, s: entries, r }); return true; }
       if ((!rulesGame && role === 'host') || offline || !connected) return false;
-      if (!raw({ t: 'in', e, k, s: entries, r })) return false;
+      if (!raw({ t: 'in', e, k, s: entries, r, ...(gotTick !== null ? { g: gotTick } : {}) })) return false;
       inputOut.hit(wall());
       return true;
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.45.3",
+  "version": "0.46.2",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",
@@ -95,6 +95,7 @@
     }
   },
   "files": [
+    "docs/",
     "bin/",
     "lib/",
     "netplay/",
@@ -158,10 +159,11 @@
     "three": "0.185.1",
     "typescript": "5.9.3",
     "viem": "2.57.4",
+    "ws": "8.22.0",
     "zod": "4.3.6"
   },
   "scripts": {
     "test": "node --test --test-concurrency=2 --test-timeout=1800000 test/*.test.mjs",
-    "prepack": "node ../../scripts/authoring-guides.mjs --check"
+    "prepack": "node lib/build-identity.mjs --check && node ../../scripts/authoring-guides.mjs --check"
   }
 }

package/rules/core.ts

@@ -79,7 +79,7 @@ export const IGNORE_MAX = 16;
 export const ANSWER_MAX = 256;
 
 export type Driver = 'person' | 'bot' | 'ai';
-export interface SeatInfo { seat: number; driver: Driver; owner: string }
+export interface SeatInfo { seat: number; driver: Driver; owner: string; character?: import('./rules.ts').Character | null }
 /** One seat's step for a tick: its input values (already held to their types) and, for an owner-moved body, its claim. */
 export interface StepInput { values: Record<string, unknown>; claim?: { pos: Vec3; vel: Vec3; heading: Vec3; r: number } | null }
 export interface ResultRow { seat: number; id: string; driver: Driver; score: number; place: number }
@@ -163,6 +163,7 @@ export interface Core {
   round(): Extract<CoreOut, { t: 'round' }>;
   bodies(): Body[];
   /** The body in a seat, as the host runtime needs it for the input protocol. */
+  character(seat: number): import('./rules.ts').Character | null;
   bodyOf(seat: number): { id: string; kind: KindTable; r: number; away: boolean; driver: Driver } | null;
   /** What happened since the last call: rounds, effects, a changed roster, changed shared state, a new epoch, a failure. */
   drain(): CoreOut[];
@@ -183,7 +184,7 @@ export interface Core {
  * `noted`: told, as it happens, of a value the rules wrote that the runtime changed to make it fit, or dropped (pack.ts
  * `Adjusted`; also `effect`, `think` and `decision`): the handler, what was done, the field's name and what was written.
  */
-export function createCore(c: Compiled, opts: { rewindTicks?: (seat: number)=>number; label?: (seat:number,driver:Driver)=>string; moved?: (kind: string, tick: number, input: Readonly<Record<string, unknown>>, before: import('./pack.ts').MoveBody, after: import('./pack.ts').MoveBody, geometry: import('./math.ts').MapShapes, id: string) => void; observe?: (kind: string, handler: string, error?: string) => void; noted?: (kind: string, handler: string, what: string, at: string, written: string) => void; seed?: number; epoch?: number; restore?: SavedCore | null; restoreEpoch?: number; stage?: string; decisions?: boolean } = {}): Core {
+export function createCore(c: Compiled, opts: { characterForSeat?: (seat: number) => import('./rules.ts').Character | null | undefined; characterSaved?: (seat: number, character: import('./rules.ts').Character) => void; rewindTicks?: (seat: number)=>number; label?: (seat:number,driver:Driver)=>string; moved?: (kind: string, tick: number, input: Readonly<Record<string, unknown>>, before: import('./pack.ts').MoveBody, after: import('./pack.ts').MoveBody, geometry: import('./math.ts').MapShapes, id: string) => void; observe?: (kind: string, handler: string, error?: string) => void; noted?: (kind: string, handler: string, what: string, at: string, written: string) => void; seed?: number; epoch?: number; restore?: SavedCore | null; restoreEpoch?: number; stage?: string; decisions?: boolean } = {}): Core {
   const dims = c.dims;
   const tickHz = c.settings.tickHz;
   const dt = 1 / tickHz;
@@ -838,7 +839,7 @@ export function createCore(c: Compiled, opts: { rewindTicks?: (seat: number)=>nu
     return rows;
   }
   function joinBody(info: SeatInfo): Ent | null {
-    const player = Object.freeze({ seat: info.seat, driver: info.driver, owner: info.owner });
+    const player = Object.freeze({ seat: info.seat, driver: info.driver, owner: info.owner, ...(info.character !== undefined ? { character: deepFreeze(info.character) } : {}) });
     let made: Ent | null = null;
     run('room', 'join', null, 'join', () => {
       // What room.join returns is read by its own data properties, and its fields are charged before they are held to their shapes.
@@ -864,6 +865,7 @@ export function createCore(c: Compiled, opts: { rewindTicks?: (seat: number)=>nu
     } else {
       if (e) {
         if (e.kind.on.leave) run(e.kind.name, 'on.leave', e, 'ent', () => e.kind.on.leave(world, e.self, Object.freeze({})));
+        opts.characterSaved?.(e.seat, JSON.parse(JSON.stringify({ kind: e.kind.name, at: e.pos, heading: e.heading, fields: e.f, motion: e.m })));
         e.dead = true; ents.delete(e.id);
       }
       seats.delete(s.seat);
@@ -975,7 +977,7 @@ export function createCore(c: Compiled, opts: { rewindTicks?: (seat: number)=>nu
       if (tick < restartAt) return;
       startMatch();
       // Seats stay through a finished match: every holder's body is made again, as if it had just joined.
-      for (const s of [...seats.values()]) { seats.delete(s.seat); if (s.driver !== 'bot') ops.push({ op: 'join', info: { seat: s.seat, driver: s.driver, owner: s.owner } }, ...(s.away ? [{ op: 'away' as const, seat: s.seat, away: true }] : [])); }
+      for (const s of [...seats.values()]) { seats.delete(s.seat); if (s.driver !== 'bot') ops.push({ op: 'join', info: { seat: s.seat, driver: s.driver, owner: s.owner, ...(opts.characterForSeat ? { character: opts.characterForSeat(s.seat) } : {}) } }, ...(s.away ? [{ op: 'away' as const, seat: s.seat, away: true }] : [])); }
       return;
     }
     if (restartAsked) { restartAsked = false; endAsked = false; startRound(); return; }
@@ -992,7 +994,10 @@ export function createCore(c: Compiled, opts: { rewindTicks?: (seat: number)=>nu
   function finishMatch(): void {
     finishing = false; restartAsked = false;
     out.push({ t: 'round', n: round.n, phase: 'over', endsAt: tick + Math.max(3, ticks(c.rounds ? c.rounds.breakSeconds : 0)), startedAt: round.startedAt, results: results() });
-    for (const e of ents.values()) e.dead = true;
+    for (const e of ents.values()) {
+      if (e.kind.player) opts.characterSaved?.(e.seat, JSON.parse(JSON.stringify({ kind: e.kind.name, at: e.pos, heading: e.heading, fields: e.f, motion: e.m })));
+      e.dead = true;
+    }
     ents.clear(); spawns = []; queue = []; pendingAsks = []; areas = []; fx = [];
     for (const s of seats.values()) s.id = null;
     shared = initFields(c.shared, dims); sharedChanged();
@@ -1456,7 +1461,7 @@ export function createCore(c: Compiled, opts: { rewindTicks?: (seat: number)=>nu
       if (!floorCall && value) guideViews.set(seat, value);
       return value;
     },
-    seatJoin: (info) => { ops.push({ op: 'join', info: { seat: info.seat, driver: info.driver, owner: String(info.owner ?? '').slice(0, 128) } }); },
+    seatJoin: (info) => { ops.push({ op: 'join', info: { seat: info.seat, driver: info.driver, owner: String(info.owner ?? '').slice(0, 128), ...(info.character !== undefined ? { character: info.character } : {}) } }); },
     seatAway: (seat, away) => { ops.push({ op: 'away', seat, away }); },
     seatLeave: (seat) => { ops.push({ op: 'leave', seat }); },
     setPolicy: (p) => { policy = normalizeCorePolicy(p); },
@@ -1477,6 +1482,7 @@ export function createCore(c: Compiled, opts: { rewindTicks?: (seat: number)=>nu
       return [[round.n, round.phase === 'live' ? 1 : 0, round.endsAt], list, ...(collision ? [collision] : [])];
     },
     shared: () => packFields(c.shared, shared, dims),
+    character: (seat) => { const e = playerBodies().find(e => e.seat === seat); return e ? JSON.parse(JSON.stringify({ kind: e.kind.name, at: e.pos, heading: e.heading, fields: e.f, motion: e.m })) : null; },
     bodies: () => playerBodies().map((e) => ({ seat: e.seat, id: e.id, kind: e.kind.name, driver: e.driver, owner: e.owner, away: e.away, score: e.kind.score ? Number(e.f[e.kind.score]) || 0 : 0, r: e.r })),
     bodyOf: (seat) => { const s = seats.get(seat); const e = s?.id ? ents.get(s.id) : null; return e ? { id: e.id, kind: e.kind, r: e.r, away: e.away, driver: e.driver } : null; },
     drain: () => { const o = out; out = []; return o; },

package/rules/host.ts

@@ -1,3 +1,4 @@
+import { stageTimings } from './timing.mjs';
 /*
  * host.ts — the host runtime: a rules module playing the host's part on the wire.
  * =============================================================================
@@ -56,9 +57,13 @@ export interface HostClock {
   setTimer(fn: () => void, ms: number): unknown;
   clearTimer(handle: unknown): void;
 }
+export interface CharacterLease {
+  account: string; lease: number; seat: number; character: import('./rules.ts').Character | null; returning?: boolean;
+}
 export interface HostOptions {
   game: string;
   record?(owner:string,key:string,value:Record<string,unknown>):void;
+  characterFor?(peer: Record<string, unknown>): CharacterLease | null;
   /** The build check compares a movement step before any tick handler can change it. */
   moved?: NonNullable<Parameters<typeof createCore>[1]>['moved'];
   /** Told of every handler as it ends, and what it threw if it threw (core.ts `observe`): the build check listens. */
@@ -74,7 +79,7 @@ export interface HostOptions {
   send(frame: Record<string, unknown>, text?: string): void;
   clock: HostClock;
   /** Synchronous save: the caller's storage output gate holds this tick's outgoing frames until confirmed. */
-  store?: { save(bytes: Uint8Array): void };
+  store?: { save(bytes: Uint8Array, commitment?: { force: boolean; seconds: number; tickHz: number; fields: { kinds: number[][]; shared: number[] } }): void };
   /** Table recovery reserves this epoch in storage before starting this host. Ordinary deterministic restores omit it. */
   restoreEpoch?: number;
   startDelayMs?: number;
@@ -95,6 +100,10 @@ export interface HostOptions {
   onEnd?(why: string, facts: Record<string, unknown>): void;
 }
 export interface Host {
+  readonly characters: ReadonlyMap<string, CharacterLease>;
+  characterReturned(account: string, lease: number): void;
+  releaseCharacter(account: string): void;
+  reserveCharacter(lease: CharacterLease): void;
   readonly tick: number;
   readonly epoch: number;
   readonly running: boolean;
@@ -104,6 +113,8 @@ export interface Host {
   readonly privateDelivery: boolean;
   projectSnapshot(snap: any, seat: number | null): any;
   readonly viewSettings: Compiled['settings']['view'];
+  /** The studio's own pace on player messages (`room.rates`), or null: Homie sets none. */
+  readonly rates: Record<string, number> | null;
   frame(m: Record<string, unknown>): void;
   /** Start the tick loop (the first person has joined). */
   start(): void;
@@ -111,7 +122,7 @@ export interface Host {
   resume(): void;
   /** Publish the round, the roster, the shared state and the capabilities again (a browser host's relay restarted). */
   announce(): void;
-  /** Stop for good: the room has ended. */
+  /** Stop for good: the room has ended. A lasting world whose storage is healthy checkpoints first, and that write can throw. */
   stop(): void;
   /** Run the next tick now, whatever the clock says (tests, and the build check's runs). Like the timer's own tick, it never throws. */
   tickNow(): void;
@@ -150,7 +161,7 @@ const SPEECH = /^(?:say|chat|emote)/i;
 /**
  * The overrun check's memory: the last few ticks that started in this isolate, whichever rooms' they were, each with
  * when it started. Time inside a Worker stands still while code runs, so a tick cannot time itself; but the start of
- * the next tick, in any room, shows how long it took. A tick that starts more than a period late blames the newest
+ * the next tick, in any room, gives a scheduling interval (including other work). A late callback suspects the newest
  * tick here that took more than a period: the one just before it, or, when that one was quick and was itself held up,
  * the one before that.
  */
@@ -164,19 +175,33 @@ function blameLate(now: number, period: number): void {
 
 export function createHost(o: HostOptions): Host {
   const c = o.compiled;
+  const persistent = c.settings.lifetime === 'persistent';
+  // Keep even effects and agent requests behind the same commit as their tick.
+  // Match rooms retain their existing save frequency and output behaviour.
+  const publish = o.send;
+  let pendingOutput: [Record<string, unknown>, string | undefined][] | null = null;
+  if (persistent) o = { ...o, send: (frame, text) => {
+    if (pendingOutput) pendingOutput.push([frame, text]); else publish(frame, text);
+  } };
+
   const period = 1000 / c.settings.tickHz;
   const tickHz = c.settings.tickHz;
   const lateTicks = Math.ceil(tickHz / 4);
   // A log that throws takes nothing down with it.
   const log = (line: Record<string, unknown>): void => { try { o.log?.(line); } catch { /* nothing to say it with */ } };
   const random = o.random ?? Math.random;
-  const saved = o.restore ? fromBytes(o.restore) as { v: number; core: SavedCore; names: [number, string][]; agents?: AgentsSaved; guideViews?: [number, { id: string; at: number; value: Record<string, unknown> }][]; queues: [number, Record<string, unknown>, StepInput['claim'], number, number][]; inputs?: [number, SeatIn][] } : null;
+  const saved = o.restore ? fromBytes(o.restore) as { v: number; characters?: CharacterLease[]; core: SavedCore; names: [number, string][]; agents?: AgentsSaved; guideViews?: [number, { id: string; at: number; value: Record<string, unknown> }][]; queues: [number, Record<string, unknown>, StepInput['claim'], number, number][]; inputs?: [number, SeatIn][] } : null;
   if (o.restore && (!saved || typeof saved !== 'object' || Array.isArray(saved))) throw new Error('saved host is not an object');
   if (saved) {
     const check = (ok: unknown): void => { if (!ok) throw new Error('saved host inputs are invalid'); };
     const uint = (n: unknown): boolean => Number.isSafeInteger(n) && (n as number) >= 0;
-    check(Object.keys(saved).every(k => ['v', 'core', 'names', 'agents', 'guideViews', 'queues', 'inputs'].includes(k)));
+    check(Object.keys(saved).every(k => ['v', 'core', 'names', 'agents', 'guideViews', 'queues', 'inputs', 'characters'].includes(k)));
     check(saved.core && Array.isArray(saved.names) && Array.isArray(saved.queues));
+    if (saved.characters !== undefined) {
+      check(c.settings.characters && Array.isArray(saved.characters));
+      check(new Set(saved.characters.map(c => c.account)).size === saved.characters.length);
+      for (const held of saved.characters) check(typeof held.account === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(held.account) && uint(held.lease) && held.lease > 0 && Number.isInteger(held.seat) && held.seat >= -1 && held.seat < c.seats && (held.returning === undefined || typeof held.returning === 'boolean'));
+    }
     if (saved.agents !== undefined) {
       const tables = ['goals', 'asks', 'avoid', 'sayAt', 'viewAt', 'floorAt', 'askAt'];
       check(saved.agents && Object.keys(saved.agents).every(k => tables.includes(k)));
@@ -236,12 +261,27 @@ export function createHost(o: HostOptions): Host {
   }
   if (saved && saved.v !== 1) throw new Error('this save was written by another version of the runtime');
   const measuredRtt = new Map<number, number>();
-  const core = createCore(c, { rewindTicks: seat => Math.ceil(((measuredRtt.get(seat) ?? 0) + 150 + period) / period), label: (seat,driver)=>nameOf(seat,driver), moved: o.moved, observe: o.observe, noted: o.noted, seed: Math.floor(random() * 4294967296) >>> 0, epoch: saved ? undefined : (Math.floor(random() * 4294967295) >>> 0) + 1, restore: saved?.core ?? null, restoreEpoch: o.restoreEpoch, stage: o.stage, decisions: !o.check });
+  const characters = new Map<string, CharacterLease>((saved?.characters ?? []).map(c => [c.account, c.returning ? { ...c, seat: -1 } : c]));
+  const characterOptions = c.settings.characters ? {
+    characterForSeat: (seat: number) => [...characters.values()].find(c => c.seat === seat && !c.returning)?.character,
+    characterSaved: (seat: number, character: import('./rules.ts').Character) => {
+      const held = [...characters.values()].find(c => c.seat === seat);
+      if (held) {
+        held.character = character;
+        // Once removed, a delayed return must never follow a new occupant of this seat.
+        if (held.returning) held.seat = -1;
+      }
+    },
+  } : {};
+  const core = createCore(c, { ...characterOptions, rewindTicks: seat => Math.ceil(((measuredRtt.get(seat) ?? 0) + 150 + period) / period), label: (seat,driver)=>nameOf(seat,driver), moved: o.moved, observe: o.observe, noted: o.noted, seed: Math.floor(random() * 4294967296) >>> 0, epoch: saved ? undefined : (Math.floor(random() * 4294967295) >>> 0) + 1, restore: saved?.core ?? null, restoreEpoch: o.restoreEpoch, stage: o.stage, decisions: !o.check });
   let epoch = core.epoch;
   if (saved && (o.startPaused ?? o.restoreEpoch !== undefined)) for (const body of core.bodies()) if (body.driver !== 'bot' && body.owner !== 'reserved') core.seatAway(body.seat, true);
   let lastSaveAt = o.clock.now();
   let saveTick = core.tick;
   let forceSave = false;
+  let storeBroken = false;
+  /** Which state fields the game declared durable, by kind and for the shared state: what a lasting world journals at once. */
+  const durableFields = { kinds: c.kinds.map(k => k.fields.flatMap(([,f],i) => f.durable ? [i] : [])), shared: c.shared.flatMap(([,f],i) => f.durable ? [i] : []) };
   let saveFailures = 0;
   let retrySaveAt = 0;
   let roundPhase = saved?.core.round[1] ?? 1;
@@ -358,6 +398,7 @@ export function createHost(o: HostOptions): Host {
   /** Where in a tick the runtime is, for the log line of a fault. */
   let phase = '';
   let faultLoggedAt = -Infinity;
+  const timing = stageTimings();
   const stats = { ticks: 0, late: 0, slips: 0, since: 0, ins: 0, dropped: 0, lateEntries: 0, loggedAt: 0, faults: 0, lastFault: '' };
   /** Something was thrown in the runtime itself: it is counted, and said in the log at most once a second. */
   function fault(where: string, error: unknown): void {
@@ -459,7 +500,16 @@ export function createHost(o: HostOptions): Host {
         // The relay numbers every stay in a seat (`occ`): the same number is the same holder, back.
         const owner = `p${Number.isInteger(p.occ) ? p.occ : typeof p.id === 'string' ? p.id.slice(0, 40) : seat}`;
         const previous = core.bodies().find((s) => s.seat === seat);
-        core.seatJoin({ seat, driver, owner });
+        const grant = driver === 'person' ? o.characterFor?.(p as Record<string, unknown>) : null;
+        if (c.settings.characters && driver === 'person' && !grant && o.characterFor) throw new Error('Character lease required');
+        let character = grant?.character;
+        if (grant) {
+          const held = characters.get(grant.account);
+          if (held && (held.lease !== grant.lease || held.returning || held.seat >= 0 && held.seat !== seat)) throw new Error('Character return is still pending');
+          character = held ? core.character(held.seat) ?? held.character : grant.character;
+          characters.set(grant.account, { ...grant, character: character ?? null, seat });
+        }
+        core.seatJoin({ seat, driver, owner, ...(grant ? { character } : {}) });
         core.seatAway(seat, false);
         if (!previous || previous.driver !== driver || previous.owner !== owner) queues.delete(seat);
         rosterText = '';
@@ -471,7 +521,13 @@ export function createHost(o: HostOptions): Host {
         for (const [id, p] of peers) if (p.seat === m.seat) peers.delete(id);
         present.delete(m.seat as number);
         queues.delete(m.seat as number);
-        core.seatAway(m.seat as number, true);
+        const held = [...characters.values()].find(c => c.seat === m.seat && !c.returning);
+        if (held) {
+          held.character = core.character(held.seat) ?? held.character;
+          held.returning = true;
+          core.seatLeave(held.seat);
+          tick(o.clock.now());
+        } else core.seatAway(m.seat as number, true);
         if (running && people() === 0) pause();
         return;
       }
@@ -481,7 +537,10 @@ export function createHost(o: HostOptions): Host {
         for (const [id, p] of peers) if (p.seat === m.seat) peers.delete(id);
         present.delete(m.seat as number);
         queues.delete(m.seat as number);
+        const held = [...characters.values()].find(c => c.seat === m.seat && !c.returning);
+        if (held) { held.character = core.character(held.seat) ?? held.character; held.returning = true; }
         core.seatLeave(m.seat as number);
+        if (held) tick(o.clock.now());
         rosterText = '';
         return;
       }
@@ -593,17 +652,26 @@ export function createHost(o: HostOptions): Host {
     }
     if (roundRebasePending) publishRebase(now);
     phase = 'step';
+    const rulesAt = timing.now();
     core.step(inputs, guideBeat);
+    timing.record('rules', rulesAt);
     phase = 'frames';
+    const framesAt = timing.now();
     const out = core.drain();
     handle(out, now);
+    timing.record('frames', framesAt);
     if (ended) return;
     phase = 'snapshot';
+    const snapshotAt = timing.now();
     const data = core.snapshot();
+    timing.record('snapshot', snapshotAt);
     const nextPhase = (data[0] as number[])[1];
     if (roundPhase === 1 && nextPhase === 0) forceSave = true;
     roundPhase = nextPhase;
+    const checkpointAt = timing.now();
     checkpoint(forceSave);
+    timing.record('checkpoint', checkpointAt);
+    const encodeAt = timing.now();
     // The control table: one row a seat, [seat, r, ack, lead].
     const rows: number[][] = [];
     for (const b of core.bodies()) {
@@ -616,13 +684,17 @@ export function createHost(o: HostOptions): Host {
     // apart to whoever interpolates between them. The stamp always rises: a replica drops one that does not.
     lastSt = Math.max(lastSt + 1, Math.round(Math.min(now, dueOf(core.tick))));
     const snap = { t: 'snap', from: null, e: epoch, k: core.tick, st: lastSt, d: data, c: rows };
-    o.send(snap, JSON.stringify(snap));
+    const encoded = JSON.stringify(snap);
+    timing.record('encode', encodeAt);
+    const sendAt = timing.now();
+    o.send(snap, encoded);
+    timing.record('send', sendAt);
     stats.ticks += 1;
     stats.since += 1;
     if (now - stats.loggedAt >= 10_000) {
       // Tick figures, one line every ten seconds, never a line a tick.
       const s = core.stats;
-      log({ ev: 'ticks', game: o.game, ...(o.build ? { build: o.build } : {}), tick: core.tick, ticks: stats.since, late: stats.late, slips: stats.slips, ins: stats.ins, lateEntries: stats.lateEntries, dropped: stats.dropped, errors: s.errors, budgetStops: s.budgetStops, cut: s.ticksCut, maxUnits: s.maxUnits, worst: s.worst, maxTickUnits: s.maxTickUnits, ...(s.lost ? { lost: s.lost } : {}), ...(stats.faults ? { faults: stats.faults, lastFault: stats.lastFault } : {}), ...(s.lastError ? { lastError: s.lastError } : {}) });
+      log({ ev: 'ticks', timing: timing.facts(), game: o.game, ...(o.build ? { build: o.build } : {}), tick: core.tick, ticks: stats.since, late: stats.late, slips: stats.slips, ins: stats.ins, lateEntries: stats.lateEntries, dropped: stats.dropped, errors: s.errors, budgetStops: s.budgetStops, cut: s.ticksCut, maxUnits: s.maxUnits, worst: s.worst, maxTickUnits: s.maxTickUnits, ...(s.lost ? { lost: s.lost } : {}), ...(stats.faults ? { faults: stats.faults, lastFault: stats.lastFault } : {}), ...(s.lastError ? { lastError: s.lastError } : {}) });
       stats.loggedAt = now; stats.since = 0; stats.late = 0; stats.ins = 0; stats.lateEntries = 0;
     }
   }
@@ -632,9 +704,21 @@ export function createHost(o: HostOptions): Host {
    * of the clock the room ends, and the log names the handler (or the fault).
    */
   function tick(now: number): void {
+    const tickAt = timing.now();
     const cut = core.stats.ticksCut;
     let faulted = false;
-    try { tickOnce(); } catch (error) { faulted = true; fault(`tick ${core.tick} (${phase})`, error); }
+    if (persistent) pendingOutput = [];
+    try {
+      tickOnce();
+      const committed = pendingOutput; pendingOutput = null;
+      if (committed && !ended) for (const [frame, text] of committed) publish(frame, text);
+    } catch (error) {
+      pendingOutput = null;
+      faulted = true; fault(`tick ${core.tick} (${phase})`, error);
+      // Never continue from uncommitted memory or retire the last good save.
+      if (persistent) { timing.record('tick', tickAt); stop(); o.onEnd?.('storage-or-tick-failed', { tick: core.tick }); return; }
+    }
+    timing.record('tick', tickAt);
     if (ended) return;
     if (!faulted && core.stats.ticksCut === cut) { failingSince = null; return; }
     if (failingSince === null) failingSince = now;
@@ -688,8 +772,13 @@ export function createHost(o: HostOptions): Host {
         if (overSince !== null) {
           overTicks += 1;
           if (2 * overBlamed < overTicks) overSince = null;
-          // A room whose ticks have run slow for five seconds of the clock ends, and the log names the handler that used the most units.
-          else if (now - overSince >= OVERRUN_MS) { end('overrun', { worst: core.stats.worst, maxUnits: core.stats.maxUnits, seconds: Math.round((now - overSince) / 100) / 10 }); return; }
+          // Late callbacks can catch up at the requested rate. End only a
+          // blamed room that also loses sustained throughput, not a healthy
+          // 20 Hz room whose callbacks arrive in pairs during admission/I/O.
+          else if (now - overSince >= OVERRUN_MS) {
+            if (overTicks * period < (now - overSince) * 0.9) { end('overrun', { worst: core.stats.worst, maxUnits: core.stats.maxUnits, seconds: Math.round((now - overSince) / 100) / 10 }); return; }
+            overSince = null;
+          }
         }
         if (o.enforceOverrun) recent.push({ who: self, at: now });
         if (recent.length > 8) recent.shift();
@@ -730,7 +819,7 @@ export function createHost(o: HostOptions): Host {
     // A pending timer would keep the object in memory and billed: the pause clears it.
     disarm();
     log({ ev: 'host-pause', game: o.game, tick: core.tick });
-    try { checkpoint(true); o.onPause?.(); } catch (error) { fault('onPause', error); }
+    try { checkpoint(true); o.onPause?.(); } catch (error) { fault('onPause', error); if (persistent) { stop(); o.onEnd?.('storage-or-tick-failed', { tick: core.tick }); } }
   }
   function resume(): void {
     if (running || ended || !paused) return;
@@ -772,9 +861,21 @@ export function createHost(o: HostOptions): Host {
   }
 
   function save(): Uint8Array {
-    return toBytes({ v: 1, core: core.save(), guideViews: [...guideViews], ...(agents ? { agents: agents.save() } : savedAgents ? { agents: savedAgents } : {}), names: [...names].filter(([seat]) => !core.bodies().some(b => b.seat === seat && b.owner === 'reserved')), queues: [...queues].map(([seat, q]) => [seat, q.held, q.claim, q.newest, q.ack]), inputs: [...queues] });
+    const reserved = new Set(core.bodies().filter(b => b.owner === 'reserved').map(b => b.seat));
+    return toBytes({ v: 1, ...(characters.size ? { characters: [...characters.values()] } : {}), core: core.save(), guideViews: [...guideViews], ...(agents ? { agents: agents.save() } : savedAgents ? { agents: savedAgents } : {}), names: [...names].filter(([seat]) => !reserved.has(seat)), queues: [...queues].map(([seat, q]) => [seat, q.held, q.claim, q.newest, q.ack]), inputs: [...queues] });
   }
   function checkpoint(force = false): void {
+    if (persistent) {
+      // An empty match break or an unjoined reservation has no body-removal callback.
+      for (const held of characters.values()) if (held.returning) held.seat = -1;
+      if (!o.store) return; // Local checks/offline simulation have no durable account.
+      // A write that threw leaves memory ahead of storage: nothing later may checkpoint it over the committed world.
+      storeBroken = true;
+      o.store.save(save(), { force, seconds: c.settings.durability.movementSeconds, tickHz, fields: durableFields });
+      storeBroken = false;
+      saveTick = core.tick; lastSaveAt = o.clock.now(); forceSave = false;
+      return;
+    }
     const seconds = c.settings.durability.movementSeconds;
     // Catch-up ticks can cover a second of play in less than a second of wall time. Bound both clocks.
     if (!o.store || !force && (core.tick === saveTick || o.clock.now() - lastSaveAt < seconds * 1000 && core.tick - saveTick < seconds * tickHz)) return;
@@ -800,21 +901,35 @@ export function createHost(o: HostOptions): Host {
         return [...row.slice(0,7),fields,...row.slice(8)];
       }),...snap.d.slice(2)]};
     },
+    get characters() { return characters; },
+    reserveCharacter(lease) { if (!characters.has(lease.account)) characters.set(lease.account, { ...lease }); },
+    releaseCharacter(account) {
+      const held = characters.get(account);
+      if (!held || held.returning || ended) return;
+      held.character = core.character(held.seat) ?? held.character; held.returning = true;
+      present.delete(held.seat); queues.delete(held.seat); names.delete(held.seat);
+      if (held.seat >= 0) core.seatLeave(held.seat); tick(o.clock.now());
+      if (running && people() === 0) pause();
+    },
+    characterReturned(account, lease) { if (characters.get(account)?.returning && characters.get(account)?.lease === lease) characters.delete(account); },
     get viewSettings() { return c.settings.view; },
+    get rates() { return c.settings.rates ?? null; },
     get viewRadiusM() { return c.settings.view?.radiusM ?? null; },
     get tick() { return core.tick; },
     get epoch() { return epoch; },
     get running() { return running; },
     get paused() { return paused; },
     get people() { return people(); },
-    frame, start, pause, resume, stop, announce,
+    frame, start, pause, resume, announce,
+    // An orderly stop of a lasting world folds what moved since the last checkpoint. One that follows a failed write, or arrives during one, writes nothing.
+    stop() { try { if (persistent && !ended && !storeBroken) checkpoint(true); } finally { stop(); } },
     tickNow: () => {
       if (ended) return;
       let now = lastStart;
       try { now = o.clock.now(); tick(now); } catch (error) { fault('tickNow', error); } finally { keepTime(); }
     },
     save,
-    facts: () => ({ tick: core.tick, epoch, running, paused, ended, armed, people: people(), tickHz, ...stats, core: { ...core.stats } }),
+    facts: () => ({ timing: timing.facts(), tick: core.tick, epoch, running, paused, ended, armed, people: people(), tickHz, ...stats, core: { ...core.stats } }),
     core,
   };
 }