@homie-rocks/studio 0.58.0 → 0.58.2

package/rules/host.ts

@@ -31,6 +31,19 @@ import { stageTimings } from './timing.mjs';
  * timer would keep the `Table` in memory and billed), the clock stops, and a person who returns finds the tick it
  * paused on. Watchers and AI seats never keep the world ticking.
  *
+ * A ROOM NOBODY IS PLAYING RESTS. When every person here has stopped playing (nothing held, pressed or sent for the
+ * game's `room.restSeconds`, 60 by default, or every page in the background for ten seconds) and, unless the game
+ * asked for an away-from-keyboard pause, no AI has sent a command for as long, the clock stops as it does for an
+ * empty room, with everybody still connected: no timer is pending, so the `Table` hibernates. It is not charged for
+ * duration while it sleeps; a liveness alarm still wakes it about once a minute (one request, and the CPU of that
+ * short wake). A deliberate rest is restored under the same epoch and does not rewrite its save. With `room.rest:
+ * 'quiet'` (the default) the world must also have nothing of its own to do (no round clock, nothing waiting on the
+ * queue, nothing moving). `'idle'` rests regardless and pauses round clocks, timers, bots and AI with it.
+ * `'never'` never rests. The first input that holds or presses something, a command, an AI's command, a page coming
+ * to the front or a new arrival starts it again at the tick it rested on.
+ * Only browsers that said they understand resting (`rest` in their hello) let a room rest, and only when the caller
+ * asks for it (`onRest`: the server's Table, or an online browser host). A lasting world never rests.
+ *
  * THE CHAIN CANNOT BREAK. One rule holds whenever this module hands control back to its caller: A ROOM THAT IS RUNNING
  * HAS EXACTLY ONE TIMER PENDING, AND A ROOM THAT IS PAUSED OR ENDED HAS NONE. A running room with no timer would stand
  * still for good with its players connected and its object billed. So every way in (`wake`, `frame`, `start`,
@@ -89,6 +102,8 @@ export interface HostOptions {
   onTick?(): void;
   /** Suspend settled round breaks; the owner persists and wakes this deadline. */
   onRoundIdle?(until: number): void;
+  /** Rest a room nobody is playing (`true`), and start it again (`false`). Without it a room never rests. */
+  onRest?(resting: boolean): void;
   /** Only the shared server isolate can attribute timer lateness to another tick. */
   enforceOverrun?: boolean;
   log?(line: Record<string, unknown>): void;
@@ -115,6 +130,8 @@ export interface Host {
   readonly paused: boolean;
   readonly roundIdleUntil: number | null;
   wakeRound(): void;
+  /** Nobody is playing: the clock is stopped with people still here (see A ROOM NOBODY IS PLAYING RESTS). */
+  readonly resting: boolean;
   readonly people: number;
   readonly viewRadiusM: number | null;
   readonly privateDelivery: boolean;
@@ -157,6 +174,10 @@ interface SeatIn {
 
 /** Every tick failing (cut short by the budget, or faulted) for this long ends the room. */
 export const FAIL_MS = 2000;
+/** How long a room plays on with nobody playing before it rests, unless the game says otherwise (`room.restSeconds`). */
+export const REST_SECONDS = 60;
+/** How long a room plays on with every page in the background before it rests (never longer than `restSeconds`). */
+export const REST_HIDDEN_MS = 10_000;
 /** Every tick blamed for running longer than a period for this long ends the room. */
 export const OVERRUN_MS = 5000;
 
@@ -203,12 +224,13 @@ export function createHost(o: HostOptions): Host {
   // 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; roundIdleUntil?: 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;
+  const saved = o.restore ? fromBytes(o.restore) as { v: number; roundIdleUntil?: number; rest?: { on: boolean; at: [number, 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', 'characters', 'roundIdleUntil'].includes(k)));
+    check(Object.keys(saved).every(k => ['v', 'core', 'names', 'agents', 'guideViews', 'queues', 'inputs', 'characters', 'roundIdleUntil', 'rest'].includes(k)));
+    if (saved.rest !== undefined) check(saved.rest && typeof saved.rest.on === 'boolean' && Array.isArray(saved.rest.at) && saved.rest.at.length <= c.seats && saved.rest.at.every(row => Array.isArray(row) && row.length === 2 && uint(row[0]) && row[0] < c.seats && Number.isFinite(row[1])));
     check(saved.core && Array.isArray(saved.names) && Array.isArray(saved.queues));
     if (saved.roundIdleUntil !== undefined) check(Number.isFinite(saved.roundIdleUntil) && saved.roundIdleUntil >= 0 && saved.core.round[1] === 0 && !saved.core.overAt);
     if (saved.characters !== undefined) {
@@ -402,8 +424,23 @@ export function createHost(o: HostOptions): Host {
     }
   }
   let roundIdleUntil: number | null = o.onRoundIdle && Number.isFinite(saved?.roundIdleUntil) ? saved!.roundIdleUntil! : null;
+  /*
+   * Resting (A ROOM NOBODY IS PLAYING RESTS): how long a room plays on with nobody playing (0: never rests), whether it
+   * rests now, when each person last played, since when each page has been in the background, which browsers can rest,
+   * and when an AI with its own hands last played. A restored room that was resting rests on.
+   */
+  const restMode = c.settings.rest ?? 'quiet';
+  const restMs = o.onRest && !persistent && restMode !== 'never' ? Math.max(0, c.settings.restSeconds ?? REST_SECONDS) * 1000 : 0;
+  /** The world as the last rest check saw it (a quiet room must also be a still one). */
+  let stillAs = '';
+  let resting = restMs > 0 && saved?.rest?.on === true && roundIdleUntil === null;
+  const playedAt = new Map<number, number>(restMs ? saved?.rest?.at ?? [] : []);
+  const hiddenSince = new Map<number, number>();
+  const restful = new Set<number>();
+  let handsAt = -Infinity;
+  let restCheckAt = 0;
   let running = false;
-  let paused = Boolean(saved && (o.startPaused ?? o.restoreEpoch !== undefined));
+  let paused = !resting && Boolean(saved && (o.startPaused ?? o.restoreEpoch !== undefined));
   let ended = false;
   /** The pending timer, and whether there is one. `armed` is the truth: a clock may hand back any value as its handle. */
   let timer: unknown = null;
@@ -471,12 +508,96 @@ export function createHost(o: HostOptions): Host {
   }
   const people = (): number => { let n = 0; for (const person of present.values()) if (person) n += 1; return n; };
 
+  /* ---------------------------------------------------------------- resting */
+
+  /** Each kind's inputs at rest, one text a field: nothing held, nothing pressed. */
+  const restingInput = new Map<KindTable, string[]>();
+  /** Whether an input frame holds or presses anything (its newest entry's values, and a press in any entry). */
+  function engaged(kind: KindTable, rows: unknown[]): boolean {
+    let idle = restingInput.get(kind);
+    if (!idle) { const v = neutral(kind); idle = kind.input.map(([name]) => JSON.stringify(v[name])); restingInput.set(kind, idle); }
+    const last = rows.length - 1;
+    for (let n = 0; n < rows.length && n < 64; n += 1) {
+      const raw = rows[n];
+      if (!Array.isArray(raw)) return false;
+      for (let i = 0; i < kind.input.length; i += 1) {
+        const fd = kind.input[i][1];
+        if (fd.t === 'press') { if (raw[i + 1] === 1) return true; }
+        else if (n === last && fd.t !== 'pulse' && JSON.stringify(coerce(fd, raw[i + 1], c.dims)) !== idle[i]) return true;
+      }
+    }
+    return false;
+  }
+  /** Somebody played: a person (their seat) or an AI with its own hands. A resting room wakes. */
+  function played(seat: number, driver: Driver, now: number): void {
+    if (driver === 'person') playedAt.set(seat, now); else handsAt = now;
+    if (resting) wakeUp('played');
+  }
+  /**
+   * Nobody is playing: every person here has a resting browser and has not played for `restMs` (or hid their page),
+   * and, unless this is an away-from-keyboard pause, no AI has played for as long. A `quiet` room (the default)
+   * must also have nothing of its own to do: no running round clock, no event, timer, spawn or ask waiting, and a
+   * world that stood still since the last check (bots, physics and anything a `tick` handler moves keep it running).
+   * An `idle` room rests regardless, pausing all of that, guides included, until somebody plays.
+   */
+  function quiet(now: number): boolean {
+    // A command already sent keeps a quiet room awake. An idle room pauses AI with the people, so that command does
+    // not keep the pause from starting. A command that arrives while the room rests still wakes it (`played`).
+    if (restMode !== 'idle' && now - handsAt < restMs) return false;
+    let anyone = false;
+    for (const [seat, person] of present) {
+      if (!person) continue;
+      anyone = true;
+      if (!restful.has(seat)) return false;
+      const hid = hiddenSince.get(seat);
+      if (hid !== undefined && now - hid >= Math.min(restMs, REST_HIDDEN_MS)) continue;
+      if (now - (playedAt.get(seat) ?? now) < restMs) return false;
+    }
+    if (!anyone || restMode === 'idle') { stillAs = ''; return anyone; }
+    if (core.waiting() > 0) { stillAs = ''; return false; }
+    const was = stillAs;
+    stillAs = JSON.stringify([core.snapshot(), core.shared()]);
+    return was === stillAs;
+  }
+  /** The clock stops with everybody still here. The room is saved first, so the object may be put away at once. */
+  function rest(): void {
+    resting = true; running = false;
+    disarm();
+    log({ ev: 'host-rest', game: o.game, tick: core.tick, people: people() });
+    try { o.send({ t: 'rest', on: true }); checkpoint(true); o.onRest?.(true); } catch (error) { fault('rest', error); }
+  }
+  /** Somebody plays again: the room carries on from the tick it rested on, on a clock started now. */
+  function wakeUp(why: string): void {
+    if (!resting || ended) return;
+    resting = false; running = true; paused = false;
+    try {
+      const now = o.clock.now();
+      base = { ms: now, tick: core.tick };
+      overSince = null; blamed = false; failingSince = null; lastStart = now;
+      for (const q of queues.values()) q.lastFrameTick = core.tick;
+      o.send({ t: 'rest', on: false });
+      roundRebaseAt = -Infinity; publishRebase(now);
+      // The save on disk says it rests, and a rested save comes back under its own epoch. Once the room moves on it
+      // must not: a restart now restores this save, under a new epoch, as any crash does.
+      checkpoint(true);
+      log({ ev: 'host-wake', game: o.game, tick: core.tick, why });
+      o.onRest?.(false);
+    } catch (error) { fault('wake', error); } finally { keepTime(); }
+  }
+
   /* ---------------------------------------------------------------- frames in */
 
   function onIn(m: Record<string, unknown>): void {
     const seat = m.from;
-    if (!Number.isInteger(seat) || m.e !== epoch || !Array.isArray(m.s)) { stats.dropped += 1; return; }
+    if (!Number.isInteger(seat) || !Array.isArray(m.s)) { stats.dropped += 1; return; }
     const body = core.bodyOf(seat as number);
+    // Somebody playing is seen before the epoch is: the first touch after a rest (which a restore may have given a new
+    // epoch) wakes the room even when the frame itself is from before it. Read at most once a second a seat.
+    if (restMs && body && hasHands(seat as number, body.driver)) {
+      const now = o.clock.now();
+      if ((resting || now - (playedAt.get(seat as number) ?? -Infinity) >= 1000) && engaged(body.kind, m.s as unknown[])) played(seat as number, body.driver, now);
+    }
+    if (m.e !== epoch) { stats.dropped += 1; return; }
     if (!body || !hasHands(seat as number, body.driver)) return;
     const kind = body.kind;
     const q = queueOf(seat as number, kind);
@@ -504,7 +625,9 @@ export function createHost(o: HostOptions): Host {
       if (seq && r !== body.r && !action) continue;
       if (seq ? q.received?.includes(seq) : j <= q.newest) continue;
       // Too early: more than a second ahead. This entry and the rest of the frame are dropped.
-      if (j > K + tickHz) { stats.dropped += 1; break; }
+      // An entry more than a second ahead is still reported, as the furthest lead there is: a browser whose clock ran on
+      // (a rest, a stalled host clock) sets its clock again instead of being dropped without a word.
+      if (j > K + tickHz) { stats.dropped += 1; q.lead = Math.min(q.lead, 126); break; }
       if(j >= q.newest && lead < q.lead)q.lead=lead;
       q.newest = Math.max(q.newest,j);
       if(seq){q.received??=[];q.received.push(seq);if(q.received.length>256)q.received.shift();}
@@ -585,7 +708,13 @@ export function createHost(o: HostOptions): Host {
         core.seatAway(seat, false);
         if (!previous || previous.driver !== driver || previous.owner !== owner) queues.delete(seat);
         rosterText = '';
-        if (people() > 0) { if (!running && !paused) start(); else if (paused) resume(); }
+        // A socket the room restored after hibernating is the same person, still resting; anybody else has just come.
+        const now = o.clock.now();
+        // The relay says whether the browser understands resting: on the server's join, or on the peer a browser host hears.
+        if (m.rest === true || (p as { rest?: unknown }).rest === true) restful.add(seat); else restful.delete(seat);
+        if (m.hidden === true) { if (!hiddenSince.has(seat)) hiddenSince.set(seat, now); } else hiddenSince.delete(seat);
+        if (m.restored !== true || !playedAt.has(seat)) playedAt.set(seat, now);
+        if (people() > 0) { if (resting) { if (m.restored !== true) wakeUp('join'); } else if (!running && !paused) start(); else if (paused) resume(); }
         return;
       }
       case 'leave': {
@@ -598,9 +727,10 @@ export function createHost(o: HostOptions): Host {
           held.character = core.character(held.seat) ?? held.character;
           held.returning = true;
           core.seatLeave(held.seat);
-          tick(o.clock.now());
+          if (!resting) tick(o.clock.now());
         } else core.seatAway(m.seat as number, true);
-        if ((running || roundIdleUntil !== null) && people() === 0) pause();
+        playedAt.delete(m.seat as number); hiddenSince.delete(m.seat as number); restful.delete(m.seat as number);
+        if ((running || resting || roundIdleUntil !== null) && people() === 0) pause();
         return;
       }
       case 'free': {
@@ -609,16 +739,30 @@ 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);
+        playedAt.delete(m.seat as number); hiddenSince.delete(m.seat as number); restful.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());
+        if (held && !resting) tick(o.clock.now());
         rosterText = '';
+        if (resting && people() === 0) pause();
+        return;
+      }
+      case 'hidden': {
+        // A page went to the background, or came back (the relay hears it on the page's clock pings). Coming back wakes a
+        // resting room: somebody is looking at it again.
+        if (!Number.isInteger(m.seat) || !present.get(m.seat as number)) return;
+        const now = o.clock.now();
+        if (m.on === true) { if (!hiddenSince.has(m.seat as number)) hiddenSince.set(m.seat as number, now); }
+        else if (hiddenSince.delete(m.seat as number)) played(m.seat as number, 'person', now);
         return;
       }
       case 'ev': {
         // What a player sends is read as what it is: a kind or a command's name that is not a text is no kind and no command.
         const kind = typeof m.k === 'string' ? m.k : '';
+        // Anything a seated person sends (a command, a pulse, a line of chat) is somebody playing, and so is an AI's
+        // command, whichever hands it plays with: a resting room wakes for a guide as for a person.
+        if (restMs && Number.isInteger(m.from)) { const b = core.bodyOf(m.from as number); if (b && (present.get(m.from as number) || hasHands(m.from as number, b.driver) || kind === 'agent:do' || /^ask:/.test(kind))) played(m.from as number, present.get(m.from as number) ? 'person' : b.driver, o.clock.now()); }
         if (!Number.isInteger(m.from)) {
           if (m.from === null && SPEECH.test(kind)) o.send({ t: 'ev', from: null, k: kind, d: cleanSpeech(m.d) });
           return;
@@ -846,6 +990,9 @@ export function createHost(o: HostOptions): Host {
         running = false; disarm();
         try { o.store?.save(save()); o.onRoundIdle(roundIdleUntil); }
         catch (error) { fault('round-idle', error); stop(); o.onEnd?.('storage-or-tick-failed', { tick: core.tick }); }
+      } else if (restMs && running && now >= restCheckAt) {
+        restCheckAt = now + 1000;
+        if (quiet(now)) rest();
       }
       return;
     }
@@ -929,7 +1076,7 @@ export function createHost(o: HostOptions): Host {
   const self = { blame: (): void => { blamed = true; } };
 
   function start(): void {
-    if (running || ended || roundIdleUntil !== null) return;
+    if (running || resting || ended || roundIdleUntil !== null) return;
     running = true; paused = false;
     try {
       base = { ms: o.clock.now() + (firstTick ? o.startDelayMs ?? 0 : 0), tick: core.tick };
@@ -943,6 +1090,10 @@ export function createHost(o: HostOptions): Host {
   }
   function pause(): void {
     if (!running) {
+      // Everybody left a resting room: it is an empty room now, paused like one. People still here (a tab
+      // went to the background) stay resting. Ending it would start every clock while the next host restores
+      // the rest save and stays asleep, so the input that should wake the room is dropped.
+      if (resting) { if (people() > 0) return; resting = false; paused = true; log({ ev: 'host-pause', game: o.game, tick: core.tick }); try { o.send({ t: 'rest', on: false }); checkpoint(true); o.onPause?.(); } catch (error) { fault('onPause', error); } return; }
       if (roundIdleUntil !== null && !paused) { paused = true; checkpoint(true); o.onPause?.(); }
       return;
     }
@@ -953,7 +1104,7 @@ export function createHost(o: HostOptions): Host {
     try { checkpoint(true); o.onPause?.(); } catch (error) { fault('onPause', error); if (persistent) { stop(); o.onEnd?.('storage-or-tick-failed', { tick: core.tick }); } }
   }
   function resume(announceRound = true): void {
-    if (running || ended || !paused || roundIdleUntil !== null) return;
+    if (running || resting || ended || !paused || roundIdleUntil !== null) return;
     running = true; paused = false;
     try {
       // The room resumes at the tick it paused on: no tick is skipped and no timer fires for the gap.
@@ -986,7 +1137,7 @@ export function createHost(o: HostOptions): Host {
     } catch (error) { fault('announce', error); }
   }
   function stop(): void {
-    running = false; paused = false; ended = true;
+    running = false; paused = false; resting = false; ended = true;
     core.dispose();
     disarm();
     agents?.stop();
@@ -1002,7 +1153,7 @@ export function createHost(o: HostOptions): Host {
 
   function save(): Uint8Array {
     const reserved = new Set(core.bodies().filter(b => b.owner === 'reserved').map(b => b.seat));
-    return toBytes({ v: 1, ...(roundIdleUntil !== null ? { roundIdleUntil } : {}), ...(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] });
+    return toBytes({ v: 1, ...(roundIdleUntil !== null ? { roundIdleUntil } : {}), ...(restMs ? { rest: { on: resting, at: [...playedAt] } } : {}), ...(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) {
@@ -1048,8 +1199,10 @@ export function createHost(o: HostOptions): Host {
       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 || roundIdleUntil !== null) && people() === 0) pause();
+      playedAt.delete(held.seat); hiddenSince.delete(held.seat); restful.delete(held.seat);
+      if (held.seat >= 0) core.seatLeave(held.seat);
+      if (!resting) tick(o.clock.now());
+      if ((running || resting || roundIdleUntil !== null) && 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; },
@@ -1061,6 +1214,7 @@ export function createHost(o: HostOptions): Host {
     get paused() { return paused; },
     get roundIdleUntil() { return roundIdleUntil; },
     wakeRound,
+    get resting() { return resting; },
     get people() { return people(); },
     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.
@@ -1071,7 +1225,7 @@ export function createHost(o: HostOptions): Host {
       try { now = o.clock.now(); tick(now); } catch (error) { fault('tickNow', error); } finally { keepTime(); }
     },
     save,
-    facts: () => ({ timing: timing.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, resting, ended, armed, people: people(), tickHz, ...stats, core: { ...core.stats } }),
     core,
   };
 }

package/rules/rules.ts

@@ -214,6 +214,19 @@ export interface RoomSettings {
   predict: { idleHold?: boolean; catchM: number | null; catchUp: number; snapM: number | null; blendMs: number; interpMs: number | null };
   /** The studio's own pace on what one player sends, messages a second by frame kind (`in`, `ev`, ...). Absent: none. */
   rates?: Record<string, number>;
+  /**
+   * When a room with people in it rests (rules/host.ts): its clock stops, its people keep their sockets and seats, and
+   * the first input, command, AI command or returning page starts it again where it stopped.
+   *   'quiet' (absent): nobody has played for `restSeconds`, and the world has nothing of its own to do: no round clock
+   *                     running, no event, timer, spawn or ask waiting, nothing moving (bots, physics, tick handlers).
+   *   'idle':           nobody has played for `restSeconds`, whatever the world is doing: round clocks, timers, bots
+   *                     and AI pause with it (an away-from-keyboard pause, for arcade games where that is right).
+   *   'never':          never rests while somebody is here.
+   * Every page in the background counts as nobody playing after ten seconds. A lasting world never rests.
+   */
+  rest?: 'quiet' | 'idle' | 'never';
+  /** How long nobody plays before a room rests (`rest`). Absent: 60. 0: never rests. */
+  restSeconds?: number;
 }
 /**
  * The default `budget.tick`: 500,000 units at 20 ticks a second or fewer, and less at a faster rate, so a second of
@@ -247,8 +260,8 @@ 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', 'lifetime', 'characters', 'rates']);
-  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, rates)`);
+  const known = new Set(['host', 'offline', 'tickHz', 'inputHz', 'durability', 'budget', 'predict', 'view', 'lifetime', 'characters', 'rates', 'rest', 'restSeconds']);
+  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, rates, rest, restSeconds)`);
   let rates: Record<string, number> | undefined;
   if (r.rates !== undefined) {
     if (!r.rates || typeof r.rates !== 'object' || Array.isArray(r.rates)) problems.push('"room.rates" is an object of messages a second per player by kind ({ "in": 60 }); using none');
@@ -275,7 +288,7 @@ export function roomSettings(raw: unknown): { settings: RoomSettings; problems:
   const p = r.predict && typeof r.predict === 'object' ? r.predict : {};
   return {
     settings: {
-      host, offline, tickHz, inputHz, ...(rates ? { rates } : {}), ...(r.lifetime === 'persistent' ? { lifetime: 'persistent' as const } : {}), ...(r.characters === true ? { characters: true } : {}),
+      host, offline, tickHz, inputHz, ...(rates ? { rates } : {}), ...(r.rest !== undefined ? { rest: ['quiet', 'idle', 'never'].includes(r.rest) ? r.rest : (problems.push('"room.rest" is "quiet", "idle" or "never"; using "quiet"'), 'quiet') } : {}), ...(r.restSeconds !== undefined ? { restSeconds: whole('restSeconds', r.restSeconds, 0, 3600, 60) } : {}), ...(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, r.lifetime === 'persistent' ? 30 : 1) },
       budget: { tick: Math.max(1, Math.floor(num('budget.tick', r.budget?.tick, budgetFor(tickHz)) as number)) },

package/rules/view.ts

@@ -294,6 +294,9 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   let controlChanges: number[][] = [];
   let sentHistory: { t: number; row: number[] }[] = [];
   let hiddenSent = false;
+  /** The room rests (net.resting): when this page last sent the change that wakes it, and whether its clock is held. */
+  let restWokeAt = -Infinity;
+  let restHeld = false;
   const history = new Map<number, Mine>();
   let pending: { seq?: number; applied?: number; t: number; input: Readonly<Record<string, unknown>>; pulses?: Record<string, number>; pulseTicks?: Record<string, number> }[] = [];
   /** Valued pulses sent, numbered: the server's control row names the newest it has acted on (0.46.3). */
@@ -423,7 +426,7 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     leadAfter = clock() + 2 * rtt + period;
     base = { tick: continuousTick ?? k + Math.min(tickHz, Math.ceil(rtt / period + target) + sendEvery - 1), at: clock() };
     stepped = Math.max(k, Math.floor(base.tick) - (continuousTick === null ? 1 : 0));
-    entries = []; sentHistory = []; controlChanges = []; pending = []; history.clear(); replayHeld = {}; serverHeld = {}; held = {}; lastSent = ''; leads.length = 0; leadTarget = .5; leadMedian = 0; pressed = new Map(); pulseNumber = new Map(); heldTrack.clear(); if (reason !== 'lead') dropPredictions();
+    entries = []; sentHistory = []; controlChanges = []; pending = []; history.clear(); replayHeld = {}; serverHeld = {}; held = {}; lastSent = ''; leads.length = 0; leadTarget = .5; leadMedian = 0; pressed = new Map(); pulseNumber = new Map(); heldTrack.clear(); if (reason !== 'lead' && reason !== 'rest') dropPredictions();
     speed = 1; phases.length = 0; phases.push({ ...base, rate: 1 }); catchTick = null; offsets = []; headingBlend = null; correction.rebases += 1;
     const u = mine && latest?.ents.get(mine.id); if (u) adopt(u);
     if (mine) {
@@ -637,14 +640,16 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
   /**
    * The end of a send period (`sendEvery` ticks, counted from tick 0): one frame with the entries made in it, `k` the
    * period's first tick. A period with no entry sends nothing; after 250 ms without a frame the held values are sent
-   * again as an ordinary entry on the current tick.
+   * again as an ordinary entry on the current tick. A resting room (nobody played for a while) is sent nothing until
+   * an entry changes: that first change is what wakes it.
    */
   function flush(now: number, t: number): void {
     if (!mine) { entries = []; return; }
-    if (!entries.length && now - lastSendAt >= 250) keepalive(t);
+    const resting = net.resting();
+    if (!entries.length && now - lastSendAt >= 250 && !resting) keepalive(t);
     const marker = myKind()!.input.length + (myKind()!.owner ? 9 : 0);
     // A newer tick's acknowledgement cannot acknowledge a hole in the history.
-    if (!entries.length && !sentHistory.some(e => !applications.has(e.row[marker + 1]))) return;
+    if (!entries.length && (resting || !sentHistory.some(e => !applications.has(e.row[marker + 1])))) return;
     const k = Math.min(entries[0]?.t ?? t, t - (t % sendEvery));
     for (const entry of entries) {
       const old = sentHistory.findIndex(e => e.t === entry.t);
@@ -710,7 +715,9 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     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 && !net.rulesHosting)) return;
+    if (!mine || net.seat === null || (!net.connected && !net.rulesHosting)) return;
+    if (!hidden && net.resting()) { restPump(now); return; }
+    if (!base) 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.
@@ -736,6 +743,28 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
     }
   }
 
+  /**
+   * A resting room (nothing is simulated until somebody plays): this page's input clock stops with it, so what it
+   * sends next is stamped on the tick the room rested on, never seconds ahead of it. Nothing is stepped or sent until
+   * a control is held or pressed; then that input goes at once, as one entry on the next tick (again a second later
+   * if the room has not woken yet), and it wakes the room. The first snapshot after the room wakes sets the clock
+   * again (applySnapshot: no base), keeping what is predicted.
+   */
+  function restPump(now: number): void {
+    const kind = myKind();
+    base = null; restHeld = true;
+    if (!kind || now - restWokeAt < 1000) return;
+    const engaged = pressed.size > 0 || pulseQueue.length > 0 || kind.input.some(([name, fd]) => fd.t !== 'press' && fd.t !== 'pulse' && Number(coerce(fd, fd.t === 'held' ? heldNumber(sample[name], fd.init) : sample[name] ?? fd.init, dims)) !== Number(coerce(fd, fd.init, dims)));
+    if (!engaged) return;
+    restWokeAt = now;
+    const t = stepped + 1;
+    const values = kind.input.map(([name, fd]) => fd.t === 'press' ? (pressed.get(name) ? 1 : 0) : fd.t === 'pulse' ? 0 : fd.t === 'held' ? Number(coerce(fd, heldNumber(sample[name], fd.init), dims)) : Number(coerce(fd, sample[name] ?? fd.init, dims)));
+    pressed = new Map();
+    const claim = kind.owner ? [mine!.pos.x, mine!.pos.y, mine!.pos.z, mine!.vel.x, mine!.vel.y, mine!.vel.z, mine!.heading.x, mine!.heading.y, mine!.heading.z] : [];
+    entries = [{ t, row: [...values, ...claim, -471, ++inputSequence, 0] }]; lastSent = JSON.stringify([values, claim]);
+    lastSendAt = 0; flush(now, t);
+  }
+
   function onSnapshot(s: Snapshot<unknown>): void {
     const wasPumping = pumping;
     pumping = true;
@@ -780,7 +809,8 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
         returningUntil = 0;
       }
       if (placed || !base) {
-        adopt(me); rebase(f.k, changedEpoch ? 'epoch' : 'placement');
+        const rested = restHeld && !placed; restHeld = false;
+        adopt(me); rebase(f.k, changedEpoch ? 'epoch' : rested ? 'rest' : 'placement');
         if (placed) emit('placed', entityOf(me, true));
       } else if (kindOf.get(me.kind)?.owner) {
         mine!.motion = motionOf(me.kind, me.motion);
@@ -886,7 +916,9 @@ export function openRoom<R = unknown>(opts: OpenRoomOptions = {}): Room<R> {
         }
       }
       if (!latencyCalibrated && authorityRtt() > calibratedRtt + period && !Object.values(sample).some(Boolean) && !pending.some(e=>Object.values(e.input).some(Boolean))) { rebase(f.k, 'lead'); latencyCalibrated = true; }
-      if (row && row[3] !== -128 && base && clock() >= leadAfter) {
+      // The furthest lead there is: this clock is more than a second ahead of the room (its input is being dropped).
+      if (row && row[3] >= 126 && base && clock() >= leadAfter) rebase(f.k, 'lead');
+      else if (row && row[3] !== -128 && base && clock() >= leadAfter) {
         const now = clock(), rtt = authorityRtt();
         // A reported lead describes an input sent roughly one authority round trip ago. Remove that
         // clock's phase before measuring jitter; project the control median onto today's phase. Otherwise

package/starters/coin-dash/game.json

@@ -9,7 +9,8 @@
   "entry": "src/view.ts",
   "example": true,
   "room": {
-    "host": "server"
+    "host": "server",
+    "rest": "idle"
   },
   "landing": {
     "pitch": "Run for the coins. First one there takes it.",

package/starters/ember-vale/game.json

@@ -24,6 +24,7 @@
     }
   },
   "room": {
-    "host": "server"
+    "host": "server",
+    "rest": "idle"
   }
 }

package/starters/gem-rush/game.json

@@ -16,6 +16,7 @@
     }
   },
   "room": {
-    "host": "server"
+    "host": "server",
+    "rest": "idle"
   }
 }

package/starters/gem-rush-3d/game.json

@@ -21,6 +21,7 @@
     }
   },
   "room": {
-    "host": "server"
+    "host": "server",
+    "rest": "idle"
   }
 }

package/starters/hero-rush-3d/game.json

@@ -21,6 +21,7 @@
     }
   },
   "room": {
-    "host": "server"
+    "host": "server",
+    "rest": "idle"
   }
 }

package/worker/agents.mjs

@@ -363,6 +363,7 @@ export class HouseAgents {
     this.agents = [];
     this.decisions = [];
     this.alarmAt = null;
+    this.resting = false;
     this.lastAlarmAt = -Infinity;
     this.backoffUntil = 0;
     /** pass id → until: a guide the owner kicked stays out until its hold ends. */
@@ -423,7 +424,7 @@ export class HouseAgents {
     };
     this.agents.push(a);
     a.h = this.room.attach(a.conn);
-    a.h.onMessage(JSON.stringify({ t: 'hello', v: 1, rev: 7, device: 'desk', want: 'play', canHost: false, agent: { hands: 'host', role: 'guide' } }));
+    a.h.onMessage(JSON.stringify({ t: 'hello', v: 1, rev: 7, device: 'desk', want: 'play', canHost: false, rest: 1, agent: { hands: 'host', role: 'guide' } }));
     return !a.closed;
   }
 
@@ -449,7 +450,8 @@ export class HouseAgents {
     try { m = JSON.parse(text); } catch { return; }
     const now = this.now();
     switch (m.t) {
-      case 'welcome': a.seat = m.seat; if (typeof m.name === 'string') a.name = m.name; return;
+      case 'welcome': a.seat = m.seat; if (typeof m.name === 'string') a.name = m.name; if (m.rest === true) this.rest(true); return;
+      case 'rest': this.rest(m.on === true); return;
       case 'error':
         if (m.code === 'kicked') this.held.set(a.pass, Number(m.until) || now + 10 * 60_000);
         else if (['agents-off', 'agents-unsupported', 'agent-pass', 'room-closed', 'room-full', 'too-many'].includes(m.code)) this.backoffUntil = now + 60_000;
@@ -524,8 +526,19 @@ export class HouseAgents {
     return Math.max(a.lastCallAt + BRAIN_CADENCE.gapMs, cap);
   }
 
+  /**
+   * The room rested, or woke. While it rests, no guide thinks and none keeps an alarm: a think would be a command,
+   * and a command would wake the room. The next decision waits until somebody plays.
+   */
+  rest(on) {
+    this.resting = on === true;
+    if (this.resting) { this.alarmAt = null; return; }
+    this.schedule();
+  }
+
   /** One alarm for the room: the earliest due guide, never sooner than 3 s after the last alarm. */
   schedule() {
+    if (this.resting) return null;
     const now = this.now();
     let next = Infinity;
     for (const a of this.live()) if (a.seat !== null && a.dueAt !== Infinity && !a.inFlight) next = Math.min(next, Math.max(a.dueAt, this.readyAt(a, now)));
@@ -539,6 +552,7 @@ export class HouseAgents {
 
   /** The Durable Object's alarm: every guide due by now (or within 1.5 s) decides, then the next alarm is set. */
   async onAlarm() {
+    if (this.resting) { this.alarmAt = null; return 0; }
     const now = this.now();
     this.lastAlarmAt = now;
     this.alarmAt = null;
@@ -568,7 +582,7 @@ export class HouseAgents {
     const goalNow = a.view?.goal && typeof a.view.goal === 'object' ? a.view.goal : null;
     if (!asks.length && a.carry && now < a.carry.until && (!goalNow || (goalNow.goal === a.carry.goal && goalNow.state === 'active'))) {
       a.inFlight = false;
-      if (this.near(a) && !a.closed) this.due(a, now + BRAIN_CADENCE.everyMs, 'every 12 s');
+      if (!this.resting && this.near(a) && !a.closed) this.due(a, now + BRAIN_CADENCE.everyMs, 'every 12 s');
       return null;
     }
     if (a.carry && (now >= a.carry.until || (goalNow && (goalNow.goal !== a.carry.goal || goalNow.state !== 'active')))) a.carry = null;
@@ -584,6 +598,8 @@ export class HouseAgents {
     const newHere = [...a.seen].filter(([seat, at]) => now - at < 20_000 && players.includes(seat)).map(([seat]) => seat);
     const ctx = { view: a.view, me: { seat: a.seat }, goal: a.view?.goal ?? null, asks, party: a.party, speech: this.room.policy.speech, kids: this.room.policy.kids, quiet, players, avoid, said, newHere };
     const t = await think(vocab, { mode, brain: p, ctx, ms: BRAIN_CADENCE.timeoutMs, now: this.now });
+    // The room rested while the brain was thinking: drop the decision. Sending it would wake the room.
+    if (this.resting || a.closed) { a.inFlight = false; return null; }
     const { decision, provider, why, ms, cost } = t;
     if (t.engine) {
       this.calls += 1;
@@ -606,7 +622,7 @@ export class HouseAgents {
       ...(t.own && /\+floor$/.test(provider) ? { own: { goal: t.own.goal, args: t.own.args } } : {}), ...(t.p ? { p: t.p } : {}), ...(t.model ? { model: t.model } : {}),
     }].slice(-LOG_MAX);
     a.inFlight = false;
-    if (this.near(a) && !a.closed) this.due(a, now + BRAIN_CADENCE.everyMs, 'every 12 s');
+    if (!this.resting && this.near(a) && !a.closed) this.due(a, now + BRAIN_CADENCE.everyMs, 'every 12 s');
     return decision;
   }