@homie-rocks/studio 0.35.0 → 0.36.0

package/netplay/rules-output.mjs

@@ -0,0 +1,85 @@
+import { takeRulesToken } from '../worker/limits.mjs';
+
+/**
+ * The hosting page's one way out for what its rules make. Reliable frames keep one order and each leaves as soon as
+ * its own kind has a token; only a snapshot may be superseded, and only a snapshot waits for the snapshot's token.
+ * Giving the role up is part of the same order: `handOver` follows the checkpoint through the queue and holds what
+ * is made after it until the relay answers, and `leave` sends the last checkpoint before the page goes.
+ */
+export function rulesOutput({ rates, send, now, setTimer = setTimeout, clearTimer = clearTimeout }) {
+  const buckets = new Map();
+  const queue = [];
+  let snapshot = null, timer = null, stopped = false, finishing = false, held = false;
+  function budget(m, force = false) {
+    const rate = rates[m.t];
+    if (!rate) throw new Error(`Unknown rules output: ${m.t}`);
+    // The relay drops a surplus snapshot and nothing else, so snapshots spend its whole rate: an on-time tick's leaves
+    // with the tick. Reliable kinds keep a fifth of theirs clear of transport jitter and late timers.
+    const ms = m.t === 'snap' ? takeRulesToken(buckets, m.t, rate, now(), 2) : takeRulesToken(buckets, m.t, rate * 0.8, now(), rate);
+    // The relay's bucket holds twice this one: a forced last checkpoint is inside it.
+    if (ms && force) { buckets.get(m.t).tokens -= 1; return 0; }
+    return ms;
+  }
+  function drain() {
+    if (timer !== null) { clearTimer(timer); timer = null; }
+    if (stopped || held) return;
+    let wait = Infinity;
+    while (queue.length) {
+      const m = queue[0];
+      if (m.rules !== true) { queue.shift(); held = true; send(m); return; }
+      const ms = budget(m);
+      if (ms) { wait = ms; break; }
+      send(queue.shift());
+    }
+    if (snapshot) {
+      const ms = budget(snapshot);
+      if (ms) wait = Math.min(wait, ms);
+      else { const m = snapshot; snapshot = null; send(m); }
+    }
+    if (finishing && !queue.length) { stopped = true; return; }
+    if (wait !== Infinity) timer = setTimer(drain, Math.max(1, wait));
+  }
+  return {
+    push(frame) {
+      if (stopped || finishing) return;
+      const m = { ...frame, rules: true };
+      if (m.t === 'snap') snapshot = m; else queue.push(m);
+      drain();
+    },
+    finish(frame) {
+      if (stopped || finishing) return;
+      finishing = true; held = false; snapshot = null; queue.push({ ...frame, rules: true });
+      drain();
+    },
+    /** `yield`, in its place behind the checkpoint. What the rules make after it waits for the relay's answer. */
+    handOver(frame) {
+      if (stopped || finishing) return;
+      queue.push({ ...frame, t: 'yield' });
+      drain();
+    },
+    /** True from `handOver` until its `yield` is on the wire: the relay must hear nothing else that moves the role. */
+    get handing() { return !stopped && queue.some((m) => m.rules !== true); },
+    /** True while a yield is queued or unanswered. */
+    get waiting() { return !stopped && (held || queue.some((m) => m.rules !== true)); },
+    /** The relay kept this page as the host: what was held goes out, in order. */
+    release() { if (held) { held = false; drain(); } },
+    /**
+     * The page is going (it closes, or its rules host is closed). Everything its allowance permits is sent, in order;
+     * a frame that cannot be is covered by the checkpoint, which goes last and always goes.
+     */
+    leave() {
+      if (stopped) return;
+      if (timer !== null) { clearTimer(timer); timer = null; }
+      let last = null, blocked = held;
+      for (const m of queue) {
+        if (m.t === 'ckpt') { last = m; continue; }
+        if (m.rules !== true) { blocked = true; continue; }
+        if (!blocked && !budget(m)) send(m); else blocked = true;
+      }
+      if (last) { budget(last, true); send(last); }
+      held = false; queue.length = 0; snapshot = null;
+    },
+    /** The relay moved the role: it takes nothing more from this page as the host. */
+    stop() { stopped = true; if (timer !== null) clearTimer(timer); timer = null; queue.length = 0; snapshot = null; },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",
@@ -119,7 +119,8 @@
     "meshoptimizer": "1.3.0",
     "puppeteer-core": "25.8.0",
     "sharp": "0.35.5",
-    "three": "0.185.1"
+    "three": "0.185.1",
+    "typescript": "5.9.3"
   },
   "scripts": {
     "test": "node --test test/*.test.mjs"

package/rules/browser.ts

@@ -0,0 +1,100 @@
+/*
+ * The browser's adapter for the one host runtime. The build puts it with the guarded rules, either in a browser
+ * host's bundle or in a server game's optional offline module. netplay owns elections and the transport; this file
+ * supplies the clock and translates the runtime's saved bytes to the relay's existing JSON checkpoint.
+ */
+import { createHost } from './host.ts';
+import { compileMap, compileRules } from './rules.ts';
+import type { RoomSettings, RulesDef } from './rules.ts';
+import { fromBytes, toBytes } from './pack.ts';
+import { lab } from '../lab/lab.ts';
+import type { RulesHostFactory, Peer } from '../netplay/netplay.ts';
+
+export interface BrowserGame {
+  id: string; build: string; tune: Record<string, unknown>; map: Parameters<typeof compileMap>[0];
+  settings: RoomSettings; seats: number; vocab?: import('../agents/agents.ts').Vocabulary;
+}
+
+/** The rules and their private tunables stay inside this factory: the view is handed only the loader. */
+export function browserHost(def: RulesDef, game: BrowserGame): RulesHostFactory {
+  return (o) => {
+    const tune = lab.rulesTune(game.tune);
+    const compiled = compileRules(def, { ...game, tune, map: compileMap(game.map, String((game.map as { name?: string }).name ?? 'main')) });
+    const checkpoint = o.restore as { rules?: string; data?: any } | null;
+    if (o.restore && (checkpoint?.rules !== game.build || !checkpoint.data || typeof checkpoint.data !== 'object')) throw new Error('invalid checkpoint');
+    // Check depth iteratively before clone/encoding can recurse on untrusted checkpoint data.
+    if (checkpoint) {
+      const pending: [unknown, number][] = [[checkpoint.data, 0]];
+      let nodes = 0;
+      while (pending.length) {
+        const [value, depth] = pending.pop()!;
+        if (depth > 64 || ++nodes > 500000) throw new Error('invalid checkpoint depth or size');
+        if (value && typeof value === 'object') for (const child of Object.values(value)) pending.push([child, depth + 1]);
+      }
+    }
+    const saved = checkpoint ? structuredClone(checkpoint.data) : null;
+    if (saved && o.peers && Array.isArray(saved.core?.ents) && Array.isArray(saved.core?.seats)) {
+      // Identity is the relay's word. The previous host's save can preserve game state, never seat authority.
+      const peers = new Map([...o.peers, ...(o.held ?? [])].filter((p) => p.seat !== null).map((p) => [p.seat, p]));
+      const policy = o.policy;
+      const count = (n: unknown): number => typeof n === 'number' && Number.isFinite(n) ? Math.max(0, Math.min(game.seats - 1, Math.floor(n))) : 0;
+      const reserved = policy?.kind === 'hybrid' || policy?.kind === 'beginner' ? Math.min(game.seats - 1, count(policy.aiSeats) + (policy.kind === 'beginner' ? count(policy.guides) : 0)) : 0;
+      const identity = (seat: number): [string, string] => {
+        const peer = peers.get(seat);
+        return peer ? [peer.agent ? 'ai' : 'person', `p${peer.occ ?? peer.id}`] : seat >= game.seats - reserved && seat < game.seats ? ['ai', 'reserved'] : ['bot', ''];
+      };
+      const sameHolder = (q: any): boolean => !Array.isArray(q) || saved.core.seats.some((s: any) => Array.isArray(s) && s[0] === q[0] && s[1] === identity(q[0])[0] && s[2] === identity(q[0])[1]);
+      if (Array.isArray(saved.queues)) saved.queues = saved.queues.filter(sameHolder);
+      if (Array.isArray(saved.inputs)) saved.inputs = saved.inputs.filter(sameHolder);
+      if (Array.isArray(saved.names)) saved.names = saved.names.filter((row: any) => {
+        if (!Array.isArray(row)) return true;
+        const previous = saved.core.seats.find((s: any) => Array.isArray(s) && s[0] === row[0]);
+        return !(previous && previous[2] !== 'reserved' && identity(row[0])[1] === 'reserved');
+      });
+      for (const w of [...saved.core.ents, ...(Array.isArray(saved.core.spawns) ? saved.core.spawns : [])]) {
+        if (!Array.isArray(w)) throw new Error('invalid checkpoint entity');
+        const next = identity(w[11]);
+        if (w[12] !== next[0] || w[13] !== next[1]) w[15] = null;
+        [w[12], w[13]] = next;
+      }
+      for (const w of saved.core.seats) { if (!Array.isArray(w)) throw new Error('invalid checkpoint seat'); [w[1], w[2]] = identity(w[0]); }
+      for (const item of Array.isArray(saved.core.queue) ? saved.core.queue : []) {
+        if (Array.isArray(item) && item[6] === 'roundOver' && Array.isArray(item[7]?.results))
+          for (const row of item[7].results) if (row && typeof row === 'object') row.driver = identity(row.seat)[0];
+      }
+      saved.core.ops = [];
+    }
+    // A new authority rebases every player's input clock. Timers, dice, entities and round still come from the save.
+
+    const host = createHost({
+      game: game.id, build: game.build, compiled, send: o.send, restore: saved ? toBytes(saved) : null,
+      stage: lab.stage ?? undefined, startPaused: false, restoreEpoch: (Math.floor(Math.random() * 4294967296) >>> 0) || 1,
+      clock: { now: o.now, setTimer: (fn, ms) => setTimeout(fn, ms), clearTimer: (h) => clearTimeout(h as ReturnType<typeof setTimeout>) },
+      onEnd: o.onEnd,
+    });
+    if (game.vocab) host.frame({ t: 'vocabulary', vocab: game.vocab });
+    const present = new Set<number>();
+    const sync = (peers: Peer[]): void => {
+      const next = new Set(peers.flatMap((p) => p.seat === null ? [] : [p.seat]));
+      for (const seat of present) if (!next.has(seat)) host.frame({ t: 'leave', seat });
+      for (const body of host.core.bodies()) if (body.driver !== 'bot' && body.owner !== 'reserved' && !next.has(body.seat)) host.core.seatAway(body.seat, true);
+      for (const peer of peers) if (peer.seat !== null) host.frame({ t: 'join', peer });
+      present.clear(); for (const seat of next) present.add(seat);
+    };
+    return {
+      frame: (m) => {
+        if (m.t === 'join') { const p = m.peer as { seat?: number }; if (typeof p?.seat === 'number') present.add(p.seat); }
+        if (m.t === 'leave' || m.t === 'free') present.delete(Number(m.seat));
+        host.frame(m);
+      },
+      sync,
+      // A restored room may be behind what its last host told the relay: the shared state is said again with the round.
+      start: () => { host.start(); if (saved) o.send({ t: 'state', k: 'shared', d: host.core.shared() }); },
+      stop: () => host.stop(),
+      pause: () => host.pause(), resume: () => host.resume(), announce: () => host.announce(),
+      save: () => ({ rules: game.build, data: fromBytes(host.save()) }),
+      get tick() { return host.tick; },
+      facts: () => host.facts(),
+    };
+  };
+}