@homie-rocks/studio 0.45.3 → 0.46.0

package/rules/host.ts

@@ -56,9 +56,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 +78,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 +99,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;
@@ -111,7 +119,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;
@@ -164,19 +172,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 +258,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;
@@ -459,7 +496,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 +517,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 +533,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;
       }
@@ -634,7 +689,17 @@ export function createHost(o: HostOptions): Host {
   function tick(now: number): void {
     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) { stop(); o.onEnd?.('storage-or-tick-failed', { tick: core.tick }); return; }
+    }
     if (ended) return;
     if (!faulted && core.stats.ticksCut === cut) { failingSince = null; return; }
     if (failingSince === null) failingSince = now;
@@ -730,7 +795,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 +837,20 @@ 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] });
+    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]) => !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] });
   }
   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,6 +876,17 @@ 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 viewRadiusM() { return c.settings.view?.radiusM ?? null; },
     get tick() { return core.tick; },
@@ -807,7 +894,9 @@ export function createHost(o: HostOptions): Host {
     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;

package/rules/rules.ts

@@ -61,6 +61,7 @@ export interface Field {
   readonly init?: unknown;
   /** On one integer field of a player's body: this is the score a round's results rank by. */
   readonly score?: true;
+  readonly durable?: boolean;
   readonly visibility?: 'owner' | 'server' | 'results';
   /** `text`: the most characters. `list` and `map`: the most entries. */
   readonly max?: number;
@@ -69,11 +70,11 @@ export interface Field {
   /** `struct`: its fields, in order. */
   readonly fields?: Readonly<Record<string, Field>>;
 }
-export interface FieldOptions { init?: unknown; score?: boolean; visibility?: 'owner' | 'server' | 'results' }
+export interface FieldOptions { durable?: boolean; init?: unknown; score?: boolean; visibility?: 'owner' | 'server' | 'results' }
 export type Fields = Readonly<Record<string, Field>>;
 
 const made = (t: FieldKind, o: FieldOptions | undefined, extra: Partial<Field> = {}): Field =>
-  Object.freeze({ t, ...extra, ...(o?.visibility ? {visibility:o.visibility} : {}), ...(o && o.init !== undefined ? { init: o.init } : {}), ...(o && o.score === true ? { score: true as const } : {}) });
+  Object.freeze({ t, ...extra, ...(o?.durable !== undefined ? {durable:o.durable} : {}), ...(o?.visibility ? {visibility:o.visibility} : {}), ...(o && o.init !== undefined ? { init: o.init } : {}), ...(o && o.score === true ? { score: true as const } : {}) });
 const plain = (t: FieldKind) => (o?: FieldOptions): Field => made(t, o);
 
 /**
@@ -167,7 +168,7 @@ export interface RulesDef {
     records?: RoundRecords;
     historySeconds?: number;
     start?: RoomHandler;
-    join?: (ctx: any, player: { seat: number; driver: 'person' | 'bot' | 'ai'; owner: string }) => { kind: string; at: Vec3; heading?: Vec3; fields?: Record<string, unknown>; motion?: Record<string, unknown> };
+    join?: (ctx: any, player: { seat: number; driver: 'person' | 'bot' | 'ai'; owner: string; character?: Character | null }) => { kind: string; at: Vec3; heading?: Vec3; fields?: Record<string, unknown>; motion?: Record<string, unknown> };
     on?: Record<string, RoomHandler>;
   };
   asks?: Record<string, AskDef>;
@@ -189,9 +190,14 @@ export function defineMove<M extends Record<string, MoveFn>>(def: M): M {
 
 /* ------------------------------------------------------------------ settings (game.json "room") */
 
+export interface Character { kind: string; at: Vec3; heading: Vec3; fields: Record<string, unknown>; motion: Record<string, unknown> }
+
 export interface RoomSettings {
   host: 'server' | 'browser';
   offline: boolean;
+  /** Persistent rooms retain their committed world until explicitly replaced. */
+  lifetime?: 'match' | 'persistent';
+  characters?: boolean;
   tickHz: number;
   inputHz: number;
   /** Omit the radius to send the whole room. No implicit visibility or bandwidth cap. */
@@ -232,12 +238,16 @@ export function roomSettings(raw: unknown): { settings: RoomSettings; problems:
     if (!Number.isFinite(n) || n < 0) { problems.push(`"room.${name}" is a number, zero or more; using its default`); return d; }
     return n;
   };
-  const known = new Set(['host', 'offline', 'tickHz', 'inputHz', 'durability', 'budget', 'predict', 'view']);
+  const known = new Set(['host', 'offline', 'tickHz', 'inputHz', 'durability', 'budget', 'predict', 'view', 'lifetime', 'characters']);
   for (const key of Object.keys(r)) if (!known.has(key)) problems.push(`"room.${key}" is not a setting (host, offline, tickHz, inputHz, durability, budget, predict, view)`);
   let host: 'server' | 'browser' = 'server';
   if (r.host !== undefined) { if (r.host === 'server' || r.host === 'browser') host = r.host; else problems.push('"room.host" is "server" or "browser"; using "server"'); }
-  let offline = true;
-  if (r.offline !== undefined) { if (typeof r.offline === 'boolean') offline = r.offline; else problems.push('"room.offline" is true or false; using true'); }
+  if (r.lifetime !== undefined && !['match', 'persistent'].includes(r.lifetime)) problems.push('"room.lifetime" is "match" or "persistent"');
+  if (r.lifetime === 'persistent' && host !== 'server') problems.push('"room.lifetime: persistent" needs room.host "server"');
+  if (r.characters !== undefined && typeof r.characters !== 'boolean') problems.push('"room.characters" is true or false');
+  if (r.characters === true && r.lifetime !== 'persistent') problems.push('"room.characters" needs room.lifetime "persistent"');
+  let offline = r.lifetime !== 'persistent';
+  if (r.offline !== undefined) { if (typeof r.offline === 'boolean') offline = r.offline; else problems.push(`"room.offline" is true or false; using ${offline}`); }
   const tickHz = whole('tickHz', r.tickHz, 1, 60, 20);
   const inputHz = whole('inputHz', r.inputHz, 1, tickHz, tickHz);
   if (host === 'browser' && r.view?.radiusM != null) problems.push('"room.view.radiusM" needs room.host "server"; browser hosting sends the whole room');
@@ -248,9 +258,9 @@ export function roomSettings(raw: unknown): { settings: RoomSettings; problems:
   const p = r.predict && typeof r.predict === 'object' ? r.predict : {};
   return {
     settings: {
-      host, offline, tickHz, inputHz,
+      host, offline, tickHz, inputHz, ...(r.lifetime === 'persistent' ? { lifetime: 'persistent' as const } : {}), ...(r.characters === true ? { characters: true } : {}),
       view: { radiusM: r.view?.radiusM === null ? null : num('view.radiusM', r.view?.radiusM, null), ...(r.view?.precisionM !== undefined ? { precisionM: num('view.precisionM', r.view.precisionM, 0) as number } : {}), ...(r.view?.nearM !== undefined ? { nearM: num('view.nearM', r.view.nearM, null) } : {}), ...(r.view?.farHz !== undefined ? { farHz: whole('view.farHz', r.view.farHz, 1, tickHz, tickHz) } : {}) },
-      durability: { movementSeconds: whole('durability.movementSeconds', r.durability?.movementSeconds, 1, 60, 1) },
+      durability: { movementSeconds: whole('durability.movementSeconds', r.durability?.movementSeconds, 1, 60, r.lifetime === 'persistent' ? 30 : 1) },
       budget: { tick: Math.max(1, Math.floor(num('budget.tick', r.budget?.tick, budgetFor(tickHz)) as number)) },
       predict: { ...(p.idleHold === true ? {idleHold:true} : {}), catchM: num('predict.catchM', p.catchM, null), catchUp: num('predict.catchUp', p.catchUp, 1.25) as number, snapM: num('predict.snapM', p.snapM, null), blendMs: num('predict.blendMs', p.blendMs, 100) as number, interpMs: num('predict.interpMs', p.interpMs, null) },
     },
@@ -403,6 +413,7 @@ function cleanField(fd: unknown, where: string, inInput: boolean): Field {
   const init = own(x, 'init');
   return Object.freeze({
     t: x.t,
+    ...(x.durable ? {durable:true} : {}),
     ...(x.visibility ? {visibility:x.visibility} : {}),
     ...(x.t === 'text' || x.t === 'list' || x.t === 'map' ? { max: x.max } : {}),
     ...(x.t === 'list' || x.t === 'map' ? { of: cleanField(x.of, `${where} (its entries)`, false) } : {}),
@@ -416,6 +427,7 @@ function checkField(fd: unknown, where: string, inInput: boolean): void {
   if (!x || typeof x !== 'object' || typeof x.t !== 'string' || !TYPES.has(x.t)) throw new Error(`${where} is not a field type: declare it with f (f.u16(), f.vec3(), f.list(f.ref(), 8)…)`);
   if ((x.t === 'press' || x.t === 'pulse') && !inInput) throw new Error(`${where}: f.press() is for input only (a button that fires once)`);
   if (inInput && !(INTS.has(x.t) || x.t === 'bit' || x.t === 'press' || x.t === 'pulse' || x.t === 'fix')) throw new Error(`${where}: an input field is a whole number, f.fix(), f.bit() or f.press()`);
+  if (x.durable !== undefined && (typeof x.durable !== 'boolean' || inInput || !/^(entities\.[^.]+\.fields|shared)\.[^.]+$/.test(where))) throw new Error(`${where}: durable belongs on a top-level state field`);
   if (x.visibility !== undefined && !/^entities\.[^.]+\.fields\.[^.]+$/.test(where)) throw new Error(`${where}: visibility belongs on a top-level entity field`);
   if (x.visibility !== undefined && (!['owner','server','results'].includes(x.visibility) || inInput)) throw new Error(`${where}: visibility is owner, server or results on state fields only`);
   if (x.t === 'text' && !(Number.isInteger(x.max) && (x.max as number) >= 1 && (x.max as number) <= 4096)) throw new Error(`${where}: f.text(max) needs its largest length, 1 to 4096 characters`);
@@ -489,6 +501,7 @@ export function compileRules(def: RulesDef, env: CompileEnv = {}): Compiled {
   const dims = d.space?.dims;
   if (dims !== 2 && dims !== 3) throw new Error('rules name their space: space: { dims: 2 } or { dims: 3 }');
   const settings = env.settings ?? ROOM_DEFAULTS;
+  if (settings.characters && Object.values(d.entities ?? {}).some(e => typeof e.player === 'object' && e.player.leave === 'bot')) throw new Error('Account characters return on leaving; player.leave must be despawn');
   const map = env.map ?? compileMap({ bounds: { min: [-32, -32], max: [32, 32] } });
   if (dims === 2 && (map.spheres.length || map.capsules.length || map.heightTiles.length)) throw new Error('spheres, capsules and height tiles need space.dims: 3');
   if (dims === 3 && map.bounds.max.z <= map.bounds.min.z) throw new Error('a 3D map needs bounds with positive height');

package/worker/characters.mjs

@@ -0,0 +1,41 @@
+/** Characters belong to existing player account IDs. Only trusted room code calls this store.
+ * A lease never expires: a delayed room cannot spend a second copy after a timeout.
+ * The existing Table namespace supplies per-account objects; no new database or hand-entered ID.
+ */
+export function characterStore(storage) {
+  const sql = storage.sql;
+  sql.exec('CREATE TABLE IF NOT EXISTS characters (game TEXT PRIMARY KEY, data TEXT NOT NULL)');
+  const read = game => JSON.parse(sql.exec('SELECT data FROM characters WHERE game = ?', game).toArray()[0]?.data ?? 'null');
+  const write = (game, value) => sql.exec('INSERT INTO characters(game,data) VALUES (?,?) ON CONFLICT(game) DO UPDATE SET data=excluded.data', game, JSON.stringify(value));
+  return {
+    read,
+    acquire(game, holder, schema) {
+      return storage.transactionSync(() => {
+        const row = read(game) ?? { lease: 0, holder: null, character: null, schema };
+        if (row.schema !== schema) return { ok: false, error: 'character-schema-changed' };
+        if (row.holder && row.holder !== holder) return { ok: false, error: 'character-held', holder: row.holder };
+        if (!row.holder) { row.holder = holder; row.lease += 1; write(game, row); }
+        return { ok: true, ...row };
+      });
+    },
+    return(game, holder, lease, character) {
+      return storage.transactionSync(() => {
+        const row = read(game);
+        if (!row || lease > row.lease) throw new Error('Unknown character lease');
+        // Lost acknowledgement or an older room: success means retire that outbox,
+        // never apply an old return to a newer lease.
+        if (lease < row.lease || !row.holder) return { ok: true };
+        if (row.holder !== holder) throw new Error('Wrong character holder');
+        write(game, { ...row, holder: null, character });
+        return { ok: true };
+      });
+    },
+  };
+}
+
+export async function characterRequest(env, account, body) {
+  const object = env.TABLE.get(env.TABLE.idFromName(`__player/${account}`));
+  const response = await object.fetch('https://player/__character', { method: 'POST', body: JSON.stringify(body) });
+  if (!response.ok) throw new Error('Character storage unavailable');
+  return response.json();
+}

package/worker/functions-schema.mjs

@@ -53,3 +53,19 @@ ALTER TABLE customer_offers ADD COLUMN expires_at INTEGER NOT NULL DEFAULT 0;
 CREATE INDEX customer_offers_expiry ON customer_offers(expires_at);
 ${FUNCTIONS_MIGRATION.slice(FUNCTIONS_MIGRATION.indexOf('CREATE TRIGGER')).replace(/CREATE TRIGGER (\w+)/g, 'DROP TRIGGER IF EXISTS $1; CREATE TRIGGER $1').replace(/ON (shop_orders|purchase_orders|meta|mcp_audit)\n?WHEN /g, 'ON $1 WHEN ').replace(/WHEN OLD.paid_at/g, "WHEN EXISTS (SELECT 1 FROM function_subscriptions WHERE type='order.paid') AND OLD.paid_at").replace(/WHEN OLD.status/g, "WHEN EXISTS (SELECT 1 FROM function_subscriptions WHERE type='order.refunded') AND OLD.status").replace(/ON app_records BEGIN/g, "ON app_records WHEN EXISTS (SELECT 1 FROM function_subscriptions WHERE type='record.changed') BEGIN").replace(/WHEN NEW.key/g, "WHEN EXISTS (SELECT 1 FROM function_subscriptions WHERE type='payment.refunded') AND NEW.key").replace(/WHEN NEW.outcome/g, "WHEN EXISTS (SELECT 1 FROM function_subscriptions WHERE type='tool.called') AND NEW.outcome").replace(/INTO studio_events(?= VALUES|\n SELECT)/g,'INTO studio_events(id,type,data,at)')}
 `;
+
+// SQLite may evaluate AND operands in either order. Guard parsing itself: meta also
+// holds plain strings, including the key used to sign player room tickets.
+export const FUNCTIONS_META_MIGRATION_FILE = '0020_function_meta.sql';
+export const FUNCTIONS_META_MIGRATION = ['INSERT', 'UPDATE'].map(op => `
+DROP TRIGGER IF EXISTS money_function_refund_${op.toLowerCase()};
+CREATE TRIGGER money_function_refund_${op.toLowerCase()} AFTER ${op} ON meta
+WHEN CASE WHEN NEW.key LIKE 'shop-money:%:refund:%' AND json_valid(NEW.value)
+THEN EXISTS (SELECT 1 FROM function_subscriptions WHERE type='payment.refunded')
+ AND json_extract(NEW.value,'$.status')='succeeded'
+ AND NOT EXISTS (SELECT 1 FROM studio_events WHERE id='refund:' || json_extract(NEW.value,'$.id'))
+ELSE 0 END BEGIN
+ INSERT OR IGNORE INTO studio_events(id,type,data,at)
+ SELECT 'refund:' || json_extract(NEW.value,'$.id'),'payment.refunded',
+ json_object('refund',json_extract(NEW.value,'$.id'),'payment',json_extract(NEW.value,'$.payment_intent'),'amount',json_extract(NEW.value,'$.amount'),'currency',json_extract(NEW.value,'$.currency')),json_extract(NEW.value,'$.at')*1000;
+END;`).join('\n');