@homie-rocks/studio 0.35.1 → 0.36.0

package/rules/types.ts

@@ -0,0 +1,63 @@
+/** The build specialises these faces from a game's declarations; the runtime still checks every write. */
+import type { Vec3, BodyDef, Fields } from './rules.ts';
+import type { math } from './math.ts';
+
+export type Point = { readonly x: number; readonly y: number; readonly z?: number };
+export type ReadonlyState<T> = T extends object ? { readonly [K in keyof T]: ReadonlyState<T[K]> } : T;
+export type WriteState<T> = T extends Vec3 ? keyof T extends keyof Vec3 ? Point : { [K in keyof T]: WriteState<T[K]> } : T extends object ? { [K in keyof T]: WriteState<T[K]> } : T;
+type Payload<T> = {} extends T ? [data?: WriteState<T>] : [data: WriteState<T>];
+type Query<T> = ReadonlyState<Omit<T, 'input'>>;
+export interface Goal { readonly goal: string; readonly args: Readonly<Record<string, unknown>>; readonly from: 'brain' | 'floor'; readonly at: number; readonly asked: boolean; readonly state: 'active' | 'done' | 'failed' }
+export interface GuideDecision { goal?: string | null; args?: Record<string, unknown>; say?: string | null; sayArgs?: Record<string, unknown> }
+export interface GuideRequest { readonly k: string; readonly args: Readonly<Record<string, unknown>>; readonly from: number; readonly at: number }
+export type GuideView<V, G = Goal, A = GuideRequest> = ReadonlyState<V> & { readonly goal: G | null; readonly asks: readonly A[] };
+export interface Player<G = Goal> { readonly seat: number; readonly owner: string; readonly driver: 'person' | 'bot' | 'ai'; readonly away: boolean; readonly goal: G | null }
+export type Self<F, M, I, K extends string, P extends boolean, G = Goal> = F & {
+  readonly id: string; readonly kind: K; readonly pos: Vec3; get vel(): Vec3; set vel(value: Point); get heading(): Vec3; set heading(value: Point); readonly grounded: boolean;
+  readonly motion: M; readonly input: ReadonlyState<I>;
+} & (P extends true ? Player<G> : {});
+export interface Hit { readonly entity?: string; readonly at: Point; readonly normal: Vec3; readonly dist?: number }
+export type Area = { sphere: { at: Point; r: number } } | { box: { min: Point; max: Point } } | { cone: { at: Point; dir: Point; r: number; angle: number } };
+export interface MapView { readonly name: string; spot(name: string): Vec3 | undefined; spots(name: string): readonly Vec3[] }
+export interface Clock { readonly tick: number; readonly dt: number; ticks(seconds: number): number; readonly math: typeof math }
+export interface Round { readonly n: number; readonly phase: 'live' | 'over'; readonly endsAt: number }
+export type World<E, F, S, V, C, A, T, Room extends boolean = false> = Clock & {
+  readonly tune: ReadonlyState<T>; readonly map: MapView; readonly stage: string; readonly level: number; readonly levelMax: number;
+  readonly shared: Room extends true ? S : ReadonlyState<S>;
+  readonly round: Round & (Room extends true ? { end(): void } : {});
+  random(): number;
+  send<K extends keyof E>(target: string, event: K, ...data: Payload<E[K]>): void;
+  sendRoom<K extends keyof E>(event: K, ...data: Payload<E[K]>): void;
+  sendArea<K extends keyof E>(area: Area, event: K, ...data: Payload<E[K]>): void;
+  after<K extends keyof E>(ticks: number, event: K, ...data: Payload<E[K]>): void;
+  emit<K extends keyof F>(effect: K, at: Point | string, ...data: Payload<F[K]>): void;
+  spawn<K extends keyof C>(kind: K, at: Point, fields?: Partial<WriteState<C[K]>>): string;
+  near<K extends keyof V>(at: Point, radius: number, kind: K): readonly Query<V[K]>[];
+  near(at: Point, radius: number): readonly Query<V[keyof V]>[];
+  inBox<K extends keyof V>(box: { min: Point; max: Point }, kind: K): readonly Query<V[K]>[];
+  inBox(box: { min: Point; max: Point }): readonly Query<V[keyof V]>[];
+  ray(from: Point, direction: Point, max: number): (Hit & { readonly dist: number }) | undefined;
+  ask<K extends keyof A>(name: K, state: WriteState<A[K]>): boolean;
+} & (Room extends true ? { announce<K extends keyof E>(event: K, ...data: Payload<E[K]>): void; finish(): void } : {
+  goalDone(ok?: boolean): void;
+  despawn(self: Exclude<V[keyof V], Player>): void;
+  place(self: V[keyof V], at: Point, options?: { vel?: Point; heading?: Point }): void;
+  sweep(self: V[keyof V], delta: Point, options?: { ignore?: readonly string[] }): Hit | undefined;
+});
+export type EventData<T> = ReadonlyState<T>;
+export type Undeliverable<E> = { [K in keyof E]: { to: string; event: K; data: E[K] } }[keyof E];
+export type BuiltIns<E = Record<string, never>> = { arrive: { why: 'join' | 'spawn' }; leave: {}; takeover: {}; undeliverable: Undeliverable<E>; answer: { ask: string; by: string; picks: Readonly<Record<string, unknown>>; why?: string } };
+export type RoomEvents<E = Record<string, never>> = RoundEvents & { seatJoined: { seat: number; id: string; driver: 'person' | 'bot' | 'ai'; owner: string; took: boolean }; seatAway: { seat: number; id: string; away: boolean }; seatLeft: { seat: number; id: string }; answer: BuiltIns['answer']; undeliverable: BuiltIns<E>['undeliverable'] };
+export type RoundEvents = { roundStart: { n: number }; roundOver: { n: number; results: readonly { seat: number; id: string; driver: 'person' | 'bot' | 'ai'; score: number; place: number }[] } };
+type GuideWorld<W> = Pick<W, Extract<keyof W, 'tick' | 'dt' | 'ticks' | 'math' | 'map' | 'tune' | 'stage' | 'level' | 'levelMax' | 'round' | 'shared' | 'near' | 'inBox' | 'ray'>>;
+export type Entity<W, S, I, E, C, V, Answer = BuiltIns['answer'], G = Goal, A = GuideRequest, D = GuideDecision> = {
+  player?: true | { away?: 'neutral' | 'think'; leave?: 'despawn' | 'bot' }; fields?: Fields; motion?: Fields; input?: Fields; body?: BodyDef;
+  tick?: (world: W, self: S) => void;
+  think?: (world: W, self: S) => Partial<I>;
+  on?: { [K in keyof (Omit<E, keyof BuiltIns> & Omit<BuiltIns<E>, 'answer'> & { answer: Answer })]?: (world: W, self: S, event: EventData<(Omit<E, keyof BuiltIns> & Omit<BuiltIns<E>, 'answer'> & { answer: Answer })[K]>) => void };
+  commands?: { [K in keyof C]?: (world: W, self: S, event: EventData<C[K]>) => void };
+  onRoom?: { [K in keyof (E & RoundEvents)]?: (world: W, self: S, event: EventData<(E & RoundEvents)[K]>) => void };
+  guide?: { view: (world: GuideWorld<W>, self: ReadonlyState<Omit<S, 'input'>>) => V; floor?: (world: W, self: S, view: GuideView<V, G, A>) => D };
+};
+export interface MoveBody<M> { get pos(): Vec3; set pos(value: Point); get vel(): Vec3; set vel(value: Point); get heading(): Vec3; set heading(value: Point); grounded: boolean; readonly motion: M }
+export type MoveContext<T, M> = Clock & { readonly tune: ReadonlyState<T>; readonly map: MapView & { sweep(body: MoveBody<M>, delta: Point): Hit | undefined } };

package/rules/view.ts

@@ -1,3 +1,5 @@
+import { rulesOutput } from '../netplay/rules-output.mjs';
+import { rulesCaps, rulesRates } from '../worker/limits.mjs';
 /*
  * view.ts — what a rules game's view imports: the room, as a browser sees it.
  * =============================================================================
@@ -6,10 +8,10 @@
  *   import type rules from './rules';
  *   const room = openRoom<typeof rules>();
  *
- * A game is rules plus view. The rules run on the server; the view draws what it is told and sends what the player
+ * A game is rules plus view. The rules run in one host runtime; the view draws what it is told and sends what the player
  * presses. `openRoom` starts the netplay helper (netplay/netplay.ts), joins the room the play page names and returns
  * at once: `room.status` moves from `connecting` to `playing`. The rules are imported for their types only, so none
- * of their code is in the view's bundle; the build hands this library their declarations as data (`setGame`), and it
+ * of their code is imported by the game's view; the build supplies declarations and an optional local host loader, and it
  * unpacks every frame from them. A view never packs or unpacks state.
  *
  *   room.me                 the player's own body
@@ -39,19 +41,20 @@ import type { useAgents, Vocabulary, AskButton } from '../agents/agents.ts';
 let agentFactory: typeof useAgents | null = null;
 export function setAgentFactory(factory: typeof useAgents): void { agentFactory = factory; }
 import { createNetplay } from '../netplay/netplay.ts';
-import type { Netplay, NetplayOptions, RoundInfo, Snapshot, StepEntry } from '../netplay/netplay.ts';
+import type { Netplay, NetplayOptions, RulesHostFactory, RoundInfo, Snapshot, StepEntry } from '../netplay/netplay.ts';
+import { lab } from '../lab/lab.ts';
 import { exposePort } from '../port/probe.ts';
-import { BudgetError, G, brand } from './guard.ts';
-import { math, sweepMap } from './math.ts';
-import { coerce, coerceFields, dir, num, thawFields, unpackEntity, unpackFields, unpackVec, vec3 } from './pack.ts';
+import { BudgetError } from './guard.ts';
+import { moveContext } from './math.ts';
+import { coerce, dir, stepMove, thawFields, unpackEntity, unpackFields, unpackVec, vec3 } from './pack.ts';
 import type { Unpacked } from './pack.ts';
 import type { FieldList, MoveFn, Schema, Vec3 } from './rules.ts';
 
 /** What the build hands the view library for one game: its declarations, its public tunables and its map. No code. */
 export interface GameData { vocab?: Vocabulary; id: string; schema: Schema; tune: Record<string, unknown>; map: { name?: string; bounds: { min: unknown; max: unknown }; boxes?: unknown[]; circles?: unknown[]; spots?: Record<string, unknown[]> } }
-let current: { game: GameData; move: Record<string, MoveFn> } | null = null;
+let current: { game: GameData; move: Record<string, MoveFn>; load?: () => Promise<RulesHostFactory> } | null = null;
 /** Called by the build's own two lines at the top of a view's bundle, before the view's code runs. */
-export function setGame(game: GameData, move: Record<string, MoveFn> = {}): void { current = { game, move }; }
+export function setGame(game: GameData, move: Record<string, MoveFn> = {}, load?: () => Promise<RulesHostFactory>): void { current = { game, move, load }; }
 
 /** An entity as a view reads it: the built-in fields, the kind's declared fields by name, and its `motion`. */
 export interface Entity {
@@ -82,7 +85,7 @@ export interface Room<R = unknown> {
   follow(id: string | null): void;
   /** Extra values for the testing tools' receipts (`window.__homiePort`). */
   probe(extra: Record<string, () => unknown>): void;
-  /** A guide's ask buttons and a person's ask (today's relay frames; guides are driven by the server in a later release). */
+  /** A guide's ask buttons and a person's ask, handled by the room's rules host. */
   ask(id: string, askId: string, args?: Record<string, unknown>): void;
   askButtons(id: string, offer?: Record<string, unknown>): AskButton[];
   readonly tune: Readonly<Record<string, unknown>>;
@@ -110,8 +113,8 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   const period = 1000 / tickHz;
   const sendEvery = Math.ceil(tickHz / Math.max(1, schema.settings.inputHz));
   const clock = opts.now ?? ((): number => (typeof performance !== 'undefined' ? performance.now() : Date.now()));
-  const net = createNetplay<unknown, unknown, unknown>({ game: game.id, maxPlayers: schema.seats, snapshotHz: tickHz, ...opts.net, rules: true });
-  const agents = game.vocab && agentFactory ? agentFactory(net, game.vocab, { roles: ['guide', 'party'], view: () => ({}), manual: true }) : null;
+  const net = createNetplay<unknown, unknown, unknown>({ game: game.id, maxPlayers: schema.seats, snapshotHz: tickHz, heartbeatMs: 0, rulesHost: { mode: schema.settings.host, offline: schema.settings.offline, load: current?.load }, ...opts.net, rules: true, rulesLimits: { output: rulesOutput, bytes: rulesCaps(schema.seats), rates: rulesRates(tickHz, schema.seats) } });
+  const agents = game.vocab && agentFactory ? agentFactory(net, game.vocab, { roles: ['guide', 'party'], view: () => ({}), manual: true, viewOnly: true }) : null;
   const kindOf = new Map(schema.kinds.map((k) => [k.name, k]));
   const listeners = new Map<string, Set<(e: any) => void>>();
   const emit = (name: string, e: unknown): void => { for (const fn of listeners.get(name) ?? []) { try { fn(e); } catch (err) { console.warn(`[room] on('${name}')`, err); } } };
@@ -119,7 +122,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   const map = { bounds: { min: vecOf(game.map.bounds.min), max: vecOf(game.map.bounds.max) }, boxes: (game.map.boxes ?? []).map((b: any) => ({ min: vecOf(b.min), max: vecOf(b.max) })), circles: (game.map.circles ?? []).map((c: any) => ({ at: vecOf(c.at), r: Number(c.r) })) };
   const spots: Record<string, readonly Vec3[]> = {};
   for (const [key, list] of Object.entries(game.map.spots ?? {})) spots[key] = Object.freeze(list.map(vecOf));
-  const tune = Object.freeze({ ...game.tune });
+  const tune = Object.freeze({ ...(lab.rulesTune({ public: game.tune }).public as Record<string, unknown>) });
 
   let status: RoomStatus = 'connecting';
   let latest: Frame | null = null;
@@ -167,12 +170,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   const tickAt = (now: number): number => (base ? base.tick + (now - base.at) / period : 0);
   /** The tick `move` is being run for: the step just taken, or the one after it while the own body is drawn between ticks. */
   let moveTick = 0;
-  const moveCtx = brand(Object.freeze({
-    get tick() { return moveTick; }, dt: 1 / tickHz, tune, math,
-    // As the server's `ctx.ticks` reads it: a plain number, or nothing.
-    ticks: (seconds: unknown): number => { const s = num(seconds); const n = Math.round(s * tickHz); return s > 0 && Number.isFinite(n) ? Math.max(1, n) : 0; },
-    map: brand(Object.freeze({ name: game.map.name ?? 'main', spot: (name: string) => spots[name]?.[0], spots: (name: string) => spots[name] ?? Object.freeze([]), sweep: (body: any, delta: unknown) => sweepMap(map, body, delta, myKind()?.radius ?? 0, dims) })),
-  }));
+  const moveCtx = moveContext({ tick: () => moveTick, tickHz, tune, map, name: game.map.name ?? 'main', spots, radius: () => myKind()?.radius ?? 0, dims });
   function rebase(k: number): void {
     const rtt = net.stats().rtt ?? 100;
     base = { tick: k + Math.ceil(rtt / period + TARGET_LEAD) + sendEvery - 1, at: clock() };
@@ -190,12 +188,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     const fn = moves[kindName];
     if (!fn) return body;
     moveTick = t;
-    G.left = Math.max(1, Math.floor(schema.settings.budget.tick / 4));
-    try { fn(body, input, moveCtx); } catch (err) { if (!(err instanceof BudgetError)) console.warn('[room] move', err); }
-    G.left = Infinity;
-    // Rounded to 32-bit floats and held to the declared shapes, as the server does it: both hold the same numbers.
-    const list = kindOf.get(kindName)?.motion ?? [];
-    return { pos: vec3(body.pos, dims), vel: vec3(body.vel, dims), heading: dir(body.heading, dims), grounded: body.grounded === true, motion: thawFields(list, coerceFields(list, body.motion, dims)) };
+    return stepMove(fn, body, input, moveCtx, Math.max(1, Math.floor(schema.settings.budget.tick / 4)), kindOf.get(kindName)?.motion ?? [], dims, (err) => { if (!(err instanceof BudgetError)) console.warn('[room] move', err); });
   }
   /** The input values the last step held (a press is never held). */
   let held: Readonly<Record<string, unknown>> = Object.freeze({});
@@ -243,12 +236,12 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   }
   function pump(): void {
     if (closed) return;
-    if (net.offline) setStatus(net.closedWhy ? 'closed' : 'offline');
+    if (net.offline && !net.rulesHosting) setStatus(net.closedWhy ? 'closed' : 'offline');
     const now = clock();
     const hidden = typeof document !== 'undefined' && document.hidden === true;
     // Effects play for everyone who draws the room: a watcher has no body and still sees them.
     fire();
-    if (!mine || !base || net.seat === null || !net.connected) return;
+    if (!mine || !base || net.seat === null || (!net.connected && !net.rulesHosting)) return;
     if (hidden) {
       // A hidden tab's timers are too slow to keep input alive, and a body must not run on without its player:
       // one neutral entry at once (every field at its init, no press), then no more steps until the tab shows again.
@@ -306,7 +299,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   function roundNow(): RoomRound | null {
     if (!round || !latest) return null;
     // The room's clock now, from the newest snapshot: a view never turns a tick into time itself.
-    const serverTick = latest.k + (net.connected ? (clock() - latest.at) / period : 0);
+    const serverTick = latest.k + ((net.connected || net.rulesHosting) ? (clock() - latest.at) / period : 0);
     return { ...round, secondsLeft: round.endsAt ? Math.max(0, (round.endsAt - serverTick) / tickHz) : Infinity, ...(results ? { results } : {}) };
   }
   /** Effects wait for the tick they were emitted on to be drawn (an effect on the player's own body plays at once). */
@@ -323,7 +316,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   }
 
   net.on('snapshot', onSnapshot);
-  net.on('role', (e) => { if (e.snap) onSnapshot(e.snap); if (net.offline) setStatus(net.closedWhy ? 'closed' : 'offline'); });
+  net.on('role', (e) => { if (e.snap) onSnapshot(e.snap); if (net.offline && !net.rulesHosting) setStatus(net.closedWhy ? 'closed' : 'offline'); });
   net.on('link', (e) => {
     if (e.state === 'online') { base = null; if (status !== 'playing') setStatus('connecting'); } else if (e.state === 'closed') setStatus('closed'); else if (e.state === 'alone' || e.state === 'offline') setStatus('offline');
   });
@@ -335,10 +328,20 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
       return;
     }
     // A player's speech and emotes, and a guide's lines and goals, as the relay carries them today.
-    if (/^(?:say|chat|emote)/i.test(e.k) && !(agents && (e.d as { ai?: boolean })?.ai)) emit('say', { kind: e.k, seat: e.from, ...(e.d && typeof e.d === 'object' ? e.d as object : { text: e.d }) });
-    else if (e.k === 'agent:goal' && e.from === net.host?.seat) emit('goal', e.d);
-    else if (e.k === 'agent:ask' && e.from === net.host?.seat) emit('ask', e.d);
-    else if (/^ask:/.test(e.k)) emit('ask', { ask: e.k.slice(4), ...(e.d && typeof e.d === 'object' ? e.d as object : {}) });
+    if (/^(?:say|chat|emote)/i.test(e.k) && !(agents && (e.d as { ai?: boolean })?.ai)) {
+      const data = e.d && typeof e.d === 'object' ? e.d as Record<string, unknown> : { text: e.d };
+      emit('say', { ...data, kind: e.k, seat: e.from, slot: -1, line: typeof data.line === 'string' ? data.line : undefined, text: typeof data.text === 'string' ? data.text : '', args: {} });
+    }
+    else if (e.k === 'agent:goal' && e.from === null) {
+      const data = e.d as import('../agents/agents.ts').GoalEvent;
+      const goal = (g: import('../agents/agents.ts').Goal) => ({ ...g, asked: g.asked === true });
+      emit('goal', { ...data, goal: goal(data.goal), prev: data.prev ? goal(data.prev) : null });
+    }
+    else if (e.k === 'agent:ask' && e.from === null) emit('ask', e.d);
+    else if (/^ask:/.test(e.k)) {
+      const data = e.d && typeof e.d === 'object' ? e.d as Record<string, unknown> : {};
+      emit('ask', { ...data, ask: e.k.slice(4), k: e.k.slice(4), slot: typeof data.slot === 'number' ? data.slot : -1, from: e.from, at: clock(), args: data.args && typeof data.args === 'object' ? data.args : {} });
+    }
   });
 
   agents?.on('say', (e) => emit('say', e));
@@ -406,7 +409,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     self: () => { const m = meNow(); return m ? { x: m.pos.x, y: m.pos.y, z: m.pos.z } : null; },
     peer: (seat: number) => { if (!latest) return null; for (const u of latest.ents.values()) if (u.seat === seat) return { x: u.pos.x, y: u.pos.y, z: u.pos.z }; return null; },
     scores: () => roster().map((r) => ({ seat: r.seat, score: r.score })),
-    score: myScore, tick: () => latest?.k ?? 0, epoch: () => epoch, hosted: () => 'server', status: () => status,
+    score: myScore, tick: () => latest?.k ?? 0, epoch: () => epoch, hosted: () => net.rulesHosting ? 'browser' : schema.settings.host, status: () => status,
   });
   if (typeof window !== 'undefined') {
     exposePort(net as Netplay<unknown, unknown, unknown>, {

package/standalone/shell/shell.js

@@ -84,20 +84,22 @@
   /** The room's address on the studio's site: a friend opens it in any browser and lands in this room. */
   function linkOf(room) { return site + '/' + game + '/play?room=' + encodeURIComponent(room); }
 
+  var canOffline = !app.room || app.room.host === 'browser' || app.room.offline !== false;
+  noticeEl.querySelector('[data-notice-offline]').hidden = !canOffline;
   // What the button and its sheet say: the room, or plainly that this copy plays offline.
   function paint() {
     var alone = !state.online || (state.link && state.link.state === 'alone');
-    var word = !state.starts ? 'Finding a room…' : alone ? 'Playing offline · Try again' : state.link && state.link.state === 'reconnecting' ? 'Reconnecting…' : labelOf(state.room);
+    var word = !state.starts ? 'Finding a room…' : alone ? (canOffline ? 'Playing offline · Try again' : 'Connection needed · Try again') : state.link && state.link.state === 'reconnecting' ? 'Reconnecting…' : labelOf(state.room);
     ui.querySelector('[data-room-code]').textContent = word;
     ui.querySelector('[data-room-label]').textContent = state.online ? labelOf(state.room) : 'Offline';
     ui.querySelector('[data-room-state]').textContent = !site ? 'This copy has no online address' : alone ? 'No room answered' : '';
     // A copy the site has outgrown cannot invite anybody: a friend's browser would land on the newer version, which
     // this copy cannot join. The line about updating stands where the invite was.
-    ui.querySelector('[data-room-link]').textContent = state.outdated ? STALE : state.online ? linkOf(state.room).replace(/^https?:\/\//, '') : 'Your game and its bots are on this device.';
+    ui.querySelector('[data-room-link]').textContent = state.outdated ? STALE : state.online ? linkOf(state.room).replace(/^https?:\/\//, '') : (canOffline ? 'Your game and its bots are on this device.' : 'This game needs a connection.');
     ui.querySelector('[data-invite]').hidden = !state.online || state.outdated;
     ui.querySelector('[data-quick]').textContent = alone ? 'Try again' : 'Quick play';
     if (alone) ui.querySelector('[data-quick]').classList.add('primary'); else ui.querySelector('[data-quick]').classList.remove('primary');
-    ui.querySelector('[data-offline]').hidden = !state.online;
+    ui.querySelector('[data-offline]').hidden = !state.online || !canOffline;
     wake();
     tellRects();
   }
@@ -113,7 +115,7 @@
     try { if (typeof AbortController === 'function') { var ac = new AbortController(); opts.signal = ac.signal; setTimeout(function () { try { ac.abort(); } catch (e) {} }, 6000); } } catch (e) {}
     return fetch(site + '/' + game + '/api/lobby' + (q.length ? '?' + q.join('&') : ''), opts)
       .then(function (r) { return r.json(); })
-      .then(function (j) { return j && typeof j.room === 'string' && ROOM.test(j.room) ? j.room : null; })
+      .then(function (j) { if (j && j.error === 'stale') { state.outdated = true; flash(STALE); } return j && typeof j.room === 'string' && ROOM.test(j.room) ? j.room : null; })
       .catch(function () { return null; });
   }
 
@@ -165,7 +167,7 @@
       lobby().then(function (room) {
         state.finding = false;
         if (state.starts !== asked) return;
-        if (room) start(room); else { flash('No room answered: still playing offline.'); paint(); }
+        if (room) start(room); else { flash(state.outdated ? STALE : canOffline ? 'No room answered: still playing offline.' : 'This game needs a connection.'); paint(); }
       });
       return;
     }
@@ -184,7 +186,7 @@
   function go() { if (state.finding) return; var kept = remembered(); hide(); if (kept && site) start(kept); else find(); }
   function join(code) {
     if (!ROOM.test(code)) { flash('A room code is 1 to 32 letters, digits, - or _.'); return false; }
-    if (!site) { flash('This copy has no online address: it plays offline.'); return false; }
+    if (!site) { flash(canOffline ? 'This copy has no online address: it plays offline.' : 'This game needs an online address and a connection.'); return false; }
     remember(code); hide(); open(false); start(code);
     return true;
   }

package/worker/brain.mjs

@@ -1,3 +1,4 @@
+import { LIMITS } from './limits.mjs';
 /**
  * BRAINS (@homie-rocks/studio 0.17.0, NETPLAY.md section 18): what an AI guide decides, a few seconds at a time, and
  * only ever in the game's own words. Pure: no Worker import and no Node built-in, so the relay (room.mjs), the Table's
@@ -649,7 +650,7 @@ export async function clefDecide(env, { vocab, ctx = {}, model, ms = 8000, local
  *                                   8 questions; Choice 2 to 26 options, Score 2 to 10 levels, a yes/no; short words
  *   picksOf(answers, questions)     the answers as the game uses them: { tactic: 'surround', wave: false, pressure: 2.6 }
  */
-export const DECIDE = Object.freeze({ questions: 8, options: 26, levels: 10, words: 160, option: 40, stateBytes: 2048, bytes: 6144, gapMs: 3000, perMinute: 20, inFlight: 2, ms: 2500 });
+export const DECIDE = Object.freeze({ questions: 8, options: 26, levels: 10, words: 160, option: 40, stateBytes: 2048, bytes: LIMITS.decide, gapMs: 3000, perMinute: 20, inFlight: 2, ms: 2500 });
 const QID = /^[A-Za-z][A-Za-z0-9_.-]{0,39}$/;
 const OPT = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,39}$/;
 

package/worker/hosted.mjs

@@ -49,7 +49,7 @@ export function compiledFor(id) {
  */
 export function startHost(game, { send, log, onPause, onResume, onEnd, ...recovery }) {
   return createHost({
-    game, build: games.get(game)?.build ?? undefined, compiled: compiledFor(game), send, log, onPause, onResume, onEnd,
+    enforceOverrun: true, game, build: games.get(game)?.build ?? undefined, compiled: compiledFor(game), send, log, onPause, onResume, onEnd,
     clock: { now: () => Date.now(), setTimer: (fn, ms) => setTimeout(fn, ms), clearTimer: (h) => clearTimeout(h) },
     ...recovery,
   });

package/worker/index.mjs

@@ -1148,7 +1148,7 @@ async function route(request, env, ctx) {
       const cur = versionOf(meta?.netplay?.version) ?? '';
       const gv = versionOf(url.searchParams.get('gv')) ?? '';
       const stall = Number(meta?.netplay?.stallMs) || 0;
-      const target = `https://table/${sub}?game=${encodeURIComponent(game)}&room=${encodeURIComponent(room)}&max=${max}${b ? `&b=${b}` : ''}${who ? `&via=${encodeURIComponent(who)}` : ''}${sub === '__net' ? `&wp=${policy}${w ? '&w=1' : ''}` : ''}&pol=${encodeFacts(pol)}&chat=${encodeFacts(lean)}${acct ? '&acct=1' : ''}${member ? '&mem=1' : ''}${hub ? '&hub=1' : ''}${ag ? `&ag=${encodeFacts(ag)}` : ''}${badge ? `&bd=${encodeURIComponent(badge)}` : ''}&cur=${encodeURIComponent(cur)}${gv ? `&gv=${encodeURIComponent(gv)}` : ''}${stall ? `&stall=${stall}` : ''}${meta?.room?.host === 'server' ? '&host=server' : ''}`;
+      const target = `https://table/${sub}?game=${encodeURIComponent(game)}&room=${encodeURIComponent(room)}&max=${max}${b ? `&b=${b}` : ''}${who ? `&via=${encodeURIComponent(who)}` : ''}${sub === '__net' ? `&wp=${policy}${w ? '&w=1' : ''}` : ''}&pol=${encodeFacts(pol)}&chat=${encodeFacts(lean)}${acct ? '&acct=1' : ''}${member ? '&mem=1' : ''}${hub ? '&hub=1' : ''}${ag ? `&ag=${encodeFacts(ag)}` : ''}${badge ? `&bd=${encodeURIComponent(badge)}` : ''}&cur=${encodeURIComponent(cur)}${gv ? `&gv=${encodeURIComponent(gv)}` : ''}${stall ? `&stall=${stall}` : ''}${meta?.room?.contract ? `&rules=1&hz=${meta.room.tickHz ?? 20}` : ''}${meta?.room?.host === 'server' ? '&host=server' : ''}`;
       // The room's own failure to answer is told apart from the browser going away while it was connecting (a closed
       // tab, a reload racing its own socket): the second is a departure, said in one line with its room, never an
       // uncaught error with nothing on it.
@@ -1388,7 +1388,7 @@ export class Table {
         send: (m, text) => room.hostFrame(m, text),
         log: (line) => { if (line.ev === 'persist-failed') this.storageProblem(new Error(line.error)); else this.say(line); },
         onPause: () => { this.pauseFromRestore = false; this.pausedAt ??= Date.now(); this.armRoom(this.pausedAt + ROOM_PAUSE_MS); },
-        onResume: () => { this.pauseFromRestore = false; this.pausedAt = null; if (this.hostRt) { try { this.saveRoom(this.hostRt.save()); } catch { /* retry already scheduled */ } } this.retimeRound(); this.armRoom(Date.now() + ROOM_ALARM_MS); },
+        onResume: () => { this.pauseFromRestore = false; this.pausedAt = null; if (this.hostRt) { try { this.saveRoom(this.hostRt.save()); } catch { /* retry already scheduled */ } } this.armRoom(Date.now() + ROOM_ALARM_MS); },
         onEnd: (why) => this.endHosted(why),
       });
       room.setServerHost(this.hostRt);
@@ -1396,7 +1396,6 @@ export class Table {
       room.setCurrent(build.build);
       if (pauseWriteFailed) { try { this.saveRoom(this.hostRt.save()); } catch { /* the save retry retains the original absence */ } }
       if (saved) {
-        this.retimeRound();
         room.hostFrame({ t: 'state', k: 'shared', d: this.hostRt.core.shared() });
         room.hostFrame({ t: 'snap', from: null, e: epoch, k: this.hostRt.tick, st: Date.now(), d: this.hostRt.core.snapshot(), c: [] });
       }
@@ -1446,13 +1445,6 @@ export class Table {
     }
   }
 
-  retimeRound() {
-    if (!this.hostRt) return;
-    const r = this.hostRt.core.save().round;
-    const period = 1000 / hostedBuild(this.game).settings.tickHz;
-    this.room.hostFrame({ t: 'round', round: { ...this.room.lastRound, n: r[0], phase: r[1] ? 'live' : 'over', endsAt: Date.now() + (r[2] - this.hostRt.tick) * period, startedAt: Date.now() + (r[3] - this.hostRt.tick) * period } });
-  }
-
   storageProblem(error) {
     this.storageHealth = { ok: false, message: String(error?.message ?? error).slice(0, 160), since: this.storageHealth?.ok === false ? this.storageHealth.since : Date.now() };
     if (Date.now() < (this.storageLogAt ?? 0)) return;
@@ -1908,8 +1900,12 @@ export class Table {
       this.report();
       return json(res);
     }
+    room.rules = url.searchParams.get('rules') === '1';
+    // Any tick rate a game may declare (1 to 60): the relay's allowances are the page's, from the same table.
+    const hz = Number(url.searchParams.get('hz'));
+    room.tickHz = Number.isInteger(hz) && hz >= 1 && hz <= 60 ? hz : 20;
     // The owner's room size: a room already open takes it from the next visitor on.
-    if (room.seatCap !== max) room.setSeats(max, perAddress(max));
+    if (room.seatCap !== max || room.rules && room.maxPlayers !== max) room.setSeats(max, perAddress(max));
     // Revision 9: the game's own stall time and the build that is live now, the Worker's word with every socket.
     const said = url.searchParams.has('cur');
     if (said) { room.setStall(url.searchParams.get('stall')); room.setCurrent(url.searchParams.get('cur') || null); }

package/worker/limits.mjs

@@ -0,0 +1,41 @@
+/** Size caps for up to 16 seats: UTF-8 bytes in rules rooms, JSON string length in legacy rooms. */
+export const LIMITS = Object.freeze({
+  hello: 2048, snap: 16384, in: 2048, ev: 4096, ckpt: 65536, state: 8192, round: 8192, roster: 4096, ping: 256, other: 512,
+  // Room chat (revision 8): a typed line (280 characters, emoji count double), a reaction.
+  say: 1536, react: 256,
+  // A game's own decision (section 20): a few typed questions about its state.
+  decide: 6144,
+});
+/**
+ * What grows with the seats (every body, every result, every slot): the checkpoint, round and roster caps double
+ * for a room of 17 to 32 (revision 3). Measured: a 32-seat courier game's checkpoint reached 56 KB of the 64 KB
+ * a 16-seat room allows. The snapshot cap does not grow: 32 bodies are about 1.5 KB.
+ */
+export const GROWS = Object.freeze(['ckpt', 'round', 'roster']);
+export const capOf = (t, seats) => (LIMITS[t] ?? LIMITS.other) * (GROWS.includes(t) && seats > 16 ? 2 : 1);
+
+export const RATES = Object.freeze({ snap: 30, in: 60, ev: 30, ckpt: 4, state: 64, round: 4, roster: 8, ping: 8, other: 8, say: 4, react: 10, decide: 2 });
+/** `ev` per second by the sender's role: a screen is a spectator, and the host is somebody's phone. */
+export const EV_RATES = Object.freeze({ host: 30, replica: 10, screen: 2 });
+/** The keyed state channel: at most this many keys and bytes per room. */
+export const STATE_CAPS = Object.freeze({ keys: 64, bytes: 65536 });
+/** Runtime output only. Player allowances above remain unchanged. */
+export const RULES_FRAMES = Object.freeze(['snap', 'ckpt', 'state', 'ev', 'round', 'roster', 'decide', 'caps', 'rules-end']);
+export const rulesRates = (tickHz = 20, seats = 8) => ({
+  // A snapshot a tick, as the server sends, and a quarter over for the ticks a late timer runs together.
+  snap: Math.max(30, Math.ceil(tickHz * 1.25)), ckpt: 4, state: tickHz + 64,
+  ev: Math.ceil((tickHz + seats * EV_RATES.replica + 32) / 0.8), round: 8,
+  // A decision a tick is what one declared ask can make (the next waits for the answer), as on a server host.
+  roster: seats * 2 + 8, decide: Math.ceil((tickHz + seats * 5 + 8) / 0.8), caps: 4, 'rules-end': 4,
+});
+export const rulesCaps = seats => Object.fromEntries(RULES_FRAMES.map(t => [t, capOf(t, seats)]));
+/** Two seconds of headroom absorb timer stalls and transport batching. */
+export function takeRulesToken(buckets, kind, rate, now, burst = rate * 2) {
+  let b = buckets.get(kind);
+  if (!b) { b = { tokens: burst, at: now }; buckets.set(kind, b); }
+  b.tokens = Math.min(burst, b.tokens + Math.max(0, now - b.at) * rate / 1000);
+  b.at = now;
+  if (b.tokens + 1e-9 < 1) return Math.ceil((1 - b.tokens) * 1000 / rate);
+  b.tokens = Math.max(0, b.tokens - 1);
+  return 0;
+}

package/worker/pages.mjs

@@ -565,7 +565,8 @@ const SHELL_JS = String.raw`${BUILD_RETRY_JS}(function () {
       if (m.what === 'roster') state.roster = m.slots;
       // Stopped for good. Removed, or the room closed: the notice. A room with no place left at all: the same notice
       // with its own words, because "try another room" is the only thing a player can do about it.
-      if (m.what === 'closed') { state.closed = m.why; if (m.why === 'kicked' || m.why === 'room-closed' || m.why === 'agents-off') notice(m.why === 'kicked' ? 'kicked' : 'closed', m); else if (m.why === 'room-full' || m.why === 'too-many') notice('full', m); }
+      if (m.what === 'line') state.gameLine = typeof m.text === 'string' ? m.text.slice(0, 200) : null;
+      if (m.what === 'closed') { state.closed = m.why; if (typeof m.message === 'string') state.gameLine = m.message.slice(0, 200); if (m.why === 'kicked' || m.why === 'room-closed' || m.why === 'agents-off') notice(m.why === 'kicked' ? 'kicked' : 'closed', m); else if (m.why === 'room-full' || m.why === 'too-many') notice('full', m); }
       // A game's net.pickPlayer(seat): only an owner's page listens (its overlay opens that player's card).
       if (m.what === 'pick' && (m.seat === null || typeof m.seat === 'number')) { try { window.dispatchEvent(new CustomEvent('homie-pick', { detail: { seat: m.seat } })); } catch (e) {} }
       paint();
@@ -775,7 +776,8 @@ const SHELL_JS = String.raw`${BUILD_RETRY_JS}(function () {
     if (f && f.counts && f.counts.watchers) bits.push(f.counts.watchers + ' watching');
     if (state.full) bits.push('waiting for a seat');
     // Stopped for good: nothing is knocking any more, so it never says "reconnecting". What is true, in a word.
-    if (state.closed) bits.push({ replaced: 'opened in another tab', 'room-full': 'room full', 'too-many': 'room full', stale: 'updating…', kicked: 'removed from this room', 'room-closed': 'room closed', 'agents-off': 'room closed' }[state.closed] || 'disconnected: reload to play');
+    if (state.gameLine) bits.push(state.gameLine);
+    else if (state.closed) bits.push({ replaced: 'opened in another tab', 'room-full': 'room full', 'too-many': 'room full', stale: 'updating…', kicked: 'removed from this room', 'room-closed': 'room closed', 'agents-off': 'room closed' }[state.closed] || 'disconnected: reload to play');
     // The link (section 22): cut off from a room it was in and knocking again ("reconnecting" is true only then), or
     // playing by itself because the room never answered, or did not come back in time.
     else if (state.link && state.link.state === 'reconnecting') bits.push('reconnecting');