@origingame/engine 0.2.0 → 0.3.0

package/src/node/playtest-run.ts

@@ -16,10 +16,12 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { bundleGame } from "./build.ts";
-import { FrameUnchecked, PLAYTEST_CLOCK, type PlaytestChecks, type PlaytestDesc, type PlaytestRun } from "../playtest.ts";
+import { FrameUnchecked, PLAYTEST_CLOCK, type PlaytestChecks, type PlaytestDesc, type PlaytestLockstep, type PlaytestRun } from "../playtest.ts";
+import { loadNativeHost, native } from "./index.ts";
 
 declare const Bun: {
   spawnSync(cmd: string[], o?: { cwd?: string; stdout?: string; stderr?: string }): { exitCode: number; stdout: Uint8Array; stderr: Uint8Array };
+  spawn(cmd: string[], o?: { stdout?: string; stderr?: string }): { exited: Promise<number>; stdout: ReadableStream<Uint8Array>; stderr: ReadableStream<Uint8Array> };
 };
 
 const argv = process.argv.slice(2);
@@ -45,7 +47,7 @@ mkdirSync(out, { recursive: true });
 const t0 = performance.now();
 const failures: string[] = [];
 let checks = 0;
-// Checks made inside t.frame (with a renderer): what a run without one leaves out.
+// Checks made inside t.frame and region or frame expectations (with a renderer): what a run without one leaves out.
 let frameChecks = 0;
 // Every screenshot taken without a renderer, by the file it would have written, in order.
 const unchecked: string[] = [];
@@ -84,7 +86,7 @@ if (!b.ok) {
   finish();
 }
 const desc = ((await import(pathToFileURL(bundled).href)) as { default?: PlaytestDesc }).default;
-if (!desc || typeof desc.check !== "function") {
+if (!desc || !desc.commands) {
   failures.push(`${file} has no default export: export default playtest({ name, commands, check })`);
   finish();
 }
@@ -94,40 +96,118 @@ result.title = desc!.name;
 // The host's clock is pinned (PlaytestDesc.clock), so og.platform.now is
 // reproducible; `store: "keep"` shares one local store file between them,
 // kept under a dot name, which no step's output may take (an output named
-// `platform.json` once replaced it: hollowbell FINDINGS #18).
-const store = desc!.store === "keep" ? join(out, ".store", "platform.json") : undefined;
-if (store) mkdirSync(dirname(store), { recursive: true });
-const command = (commands: string, dir: string, clock: number) => {
+// `platform.json` once replaced it: hollowbell FINDINGS #18). In a room each
+// place has its own (`platform-<place>.json`): its processes run at once,
+// and a `then` step relaunches every place on its own store.
+const storeOf = (place: number): string | undefined => {
+  if (desc!.store !== "keep") return undefined;
+  const path = join(out, ".store", desc!.room && place > 0 ? `platform-${place}.json` : "platform.json");
+  mkdirSync(dirname(path), { recursive: true });
+  return path;
+};
+const command = (commands: string, dir: string, clock: number, room?: { url: string; ticks?: number | undefined; place: number }) => {
   const c = ["bun", join(here, "run.ts"), "--entry", entry!, "--commands", commands, "--out", dir, "--json", "--clock", String(clock)];
+  if (room) c.push("--room", room.url);
+  if (room?.ticks !== undefined) c.push("--ticks", String(room.ticks));
   if (root) c.push("--root", root);
   if (desc!.seed !== undefined) c.push("--seed", String(desc!.seed));
   if (desc!.size) c.push("--size", desc!.size);
+  const store = storeOf(room?.place ?? 0);
   if (store) c.push("--platform-store", store);
   return c;
 };
-type Summary = { tick: number; hash: string; entities: number; quit: boolean; tier: string; outputs: string[]; warnings: string[]; unchecked?: string[] };
+type ExpectResult = { tick: number; expect: string; kind: string; status: "pass" | "fail" | "unchecked"; expected: unknown; observed: unknown; reason: string };
+type Summary = {
+  tick: number;
+  hash: string;
+  netHash?: string;
+  lockstep?: PlaytestLockstep;
+  entities: number;
+  quit: boolean;
+  tier: string;
+  outputs: string[];
+  warnings: string[];
+  unchecked?: string[];
+  expectations?: { failed: number; results: ExpectResult[] };
+};
 const spawn = (c: string[], what: string): Summary | null => {
   const r = Bun.spawnSync(c, { stdout: "pipe", stderr: "pipe" });
-  const stdout = new TextDecoder().decode(r.stdout);
-  const stderr = new TextDecoder().decode(r.stderr);
+  return summarise(r.exitCode, new TextDecoder().decode(r.stdout), new TextDecoder().decode(r.stderr), what);
+};
+function summarise(exitCode: number, stdout: string, stderr: string, what: string): Summary | null {
   let summary: Summary | null = null;
   try {
     summary = JSON.parse(stdout.trim().split("\n").pop() ?? "");
   } catch {
     summary = null;
   }
-  if (r.exitCode !== 0 || !summary) {
-    failures.push(`${what} failed (exit ${r.exitCode}): ${stderr.trim() || stdout.trim()}`);
+  // A run whose only failure is its expectations exits 1 with its summary: each is a check.
+  const expectedOnly = exitCode === 1 && summary !== null && (summary.expectations?.failed ?? 0) > 0;
+  if ((exitCode !== 0 && !expectedOnly) || !summary) {
+    failures.push(`${what} failed (exit ${exitCode}): ${stderr.trim() || stdout.trim()}`);
     return null;
   }
+  for (const e of summary.expectations?.results ?? []) {
+    if (e.status === "unchecked") unchecked.push(`${what}: expect:${e.expect}`);
+    else {
+      checks++;
+      // A region or frame expectation read the frame: without a renderer it is unchecked.
+      if (e.kind === "region" || e.kind === "frame") frameChecks++;
+      if (e.status === "fail") failures.push(`${what}: expect:${e.expect} failed at tick ${e.tick}: expected ${JSON.stringify(e.expected)}, observed ${JSON.stringify(e.observed)}; ${e.reason}`);
+    }
+  }
   return summary;
-};
+}
 const clock = desc!.clock ?? PLAYTEST_CLOCK;
-const summary = spawn(command(desc!.commands, out, clock), "og run");
+
+// PlaytestDesc.room: a relay in this process, and every peer's process at
+// once, each joined to the room (the first is the run, the others its peers).
+// A `then` step relaunches every place at once into a room of its own
+// (`<name>.then-<n>`), each running the step's script: lockstep keeps the
+// steps on the room's shared ticks, so a `quit` ends every place on one tick.
+const room = desc!.room;
+const peerSummaries: Summary[] = [];
+let summary: Summary | null;
+let playRoom: ((name: string, scripts: (place: number) => string, dirOf: (place: number) => string, clock: number, what: string) => Promise<Summary[]>) | null = null;
+if (room) {
+  const players = Math.floor(room.players);
+  if (!(players >= 2 && players <= 16)) failures.push(`room.players is ${room.players}: a room playtest takes 2 to 16 processes`);
+  if ((desc!.runs ?? 1) > 1) failures.push("a room playtest takes no `runs`: its processes play at once (a relaunch is a `then` step)");
+  const name = room.name ?? "playtest";
+  if (room.ticks !== undefined && !(Number.isInteger(room.ticks) && room.ticks > 0)) failures.push(`room.ticks is ${room.ticks}: the tick every process stops at, a whole number above 0 (or leave it out and end the script with quit)`);
+  if (!/^[A-Za-z0-9._-]{1,54}$/.test(name)) failures.push(`room.name '${name}' is not a room id: 1 to 54 of letters, digits, '.', '_' and '-' (a then step's room adds .then-<n>)`);
+  if (failures.length > 0) finish();
+  loadNativeHost();
+  const relay = JSON.parse(native().og_node_relay_start(0)) as { ok: boolean; value?: number; reason?: string };
+  if (!relay.ok) {
+    failures.push(`the playtest's relay did not start: ${relay.reason}`);
+    finish();
+  }
+  playRoom = async (roomName, scripts, dirOf, at, what) => {
+    const url = `ws://127.0.0.1:${relay.value}/${roomName}`;
+    const results = await Promise.all(
+      Array.from({ length: players }, async (_, i) => {
+        const dir = dirOf(i);
+        mkdirSync(dir, { recursive: true });
+        const p = Bun.spawn(command(scripts(i), dir, at, { url, ticks: room.ticks, place: i }), { stdout: "pipe", stderr: "pipe" });
+        const [code, stdout, stderr] = await Promise.all([p.exited, new Response(p.stdout).text(), new Response(p.stderr).text()]);
+        return summarise(code, stdout, stderr, `${what} (peer ${i})`);
+      }),
+    );
+    if (results.some((r) => r === null)) finish();
+    return results as Summary[];
+  };
+  const results = await playRoom(name, (i) => room.commands?.[i] ?? desc!.commands, (i) => (i === 0 ? out : join(out, `peer-${i}`)), clock, "og run");
+  summary = results[0]!;
+  peerSummaries.push(...results.slice(1));
+  for (const [i, s] of peerSummaries.entries()) for (const f of s.unchecked ?? []) unchecked.push(`peer ${i + 1} ${f}`);
+} else summary = spawn(command(desc!.commands, out, clock), "og run");
 if (!summary) finish();
 const rendered = summary!.tier !== "none";
 unchecked.push(...(summary!.unchecked ?? []));
 result = { ...result, tick: summary!.tick, hash: summary!.hash, tier: summary!.tier, warnings: summary!.warnings };
+// A room's shared hashes, the run's first: equal ones are peers that stayed in step.
+if (room) result = { ...result, netHashes: [summary!, ...peerSummaries].map((s) => s.netHash ?? ""), lockstep: [summary!, ...peerSummaries].map((s) => s.lockstep ?? null) };
 // More runs of the same script (desc.runs), each in a fresh process into its
 // own directory: only their end hashes are kept.
 const hashes = [summary!.hash];
@@ -137,7 +217,7 @@ for (let i = 1; i < Math.max(1, Math.floor(desc!.runs ?? 1)); i++) {
 }
 result = { ...result, hashes };
 
-const runOf = (s: Summary, dir: string, later: readonly PlaytestRun[]): PlaytestRun => {
+const runOf = (s: Summary, dir: string, later: readonly PlaytestRun[], peers: readonly PlaytestRun[] = []): PlaytestRun => {
   const path = (f: string) => {
     const p = resolve(dir, f);
     if (!existsSync(p)) throw new Error(`the run wrote no ${f} (it wrote ${s.outputs.map((o) => o.slice(dir.length + 1)).join(", ") || "nothing"})`);
@@ -156,6 +236,9 @@ const runOf = (s: Summary, dir: string, later: readonly PlaytestRun[]): Playtest
     files: s.outputs.map((o) => o.slice(dir.length + 1)),
     warnings: s.warnings,
     then: later,
+    netHash: s.netHash ?? "",
+    lockstep: s.lockstep ?? null,
+    peers,
     json: <T>(f: string) => JSON.parse(readFileSync(path(f), "utf8")) as T,
     text: (f: string) => readFileSync(path(f), "utf8"),
     png: (f: string) => {
@@ -183,17 +266,30 @@ const runOf = (s: Summary, dir: string, later: readonly PlaytestRun[]): Playtest
     },
   };
 };
-// The later processes (desc.then), in order, after the script and its runs.
+// The later processes (desc.then), in order, after the script and its runs;
+// in a room every place again, at once (their runs are each step's `peers`).
 const later: PlaytestRun[] = [];
 for (const [i, step] of (desc!.then ?? []).entries()) {
   const dir = join(out, `then-${i + 1}`);
   mkdirSync(dir, { recursive: true });
+  if (playRoom) {
+    const peerDir = (p: number) => join(dir, `peer-${p}`);
+    const all = await playRoom(`${room!.name ?? "playtest"}.then-${i + 1}`, () => step.commands, (p) => (p === 0 ? dir : peerDir(p)), step.clock ?? clock, `then[${i}]`);
+    for (const [p, s] of all.entries()) for (const f of s.unchecked ?? []) unchecked.push(`then[${i}]${p > 0 ? ` peer ${p}` : ""} ${f}`);
+    later.push(runOf(all[0]!, dir, [], all.slice(1).map((s, p) => runOf(s, peerDir(p + 1), []))));
+    continue;
+  }
   const s = spawn(command(step.commands, dir, step.clock ?? clock), `then[${i}]`);
   if (!s) finish();
   for (const f of s!.unchecked ?? []) unchecked.push(`then[${i}] ${f}`);
   later.push(runOf(s!, dir, []));
 }
-const run = runOf(summary!, out, later);
+const run = runOf(
+  summary!,
+  out,
+  later,
+  peerSummaries.map((s, i) => runOf(s, join(out, `peer-${i + 1}`), [])),
+);
 // Every file a run took a screenshot for without a renderer, by name and by path.
 const missedPaths = new Set<string>([...(summary!.unchecked ?? []).map((f) => resolve(out, f)), ...later.flatMap((r, i) => r.unchecked.map((f) => resolve(join(out, `then-${i + 1}`), f)))]);
 const missedNames = new Set<string>([...(summary!.unchecked ?? []), ...later.flatMap((r) => r.unchecked)]);
@@ -240,7 +336,7 @@ function missedFrame(e: unknown): string | null {
   return null;
 }
 try {
-  await desc!.check(run, t);
+  if (desc!.check) await desc!.check(run, t);
 } catch (e) {
   const frame = missedFrame(e);
   if (frame !== null) notes.push(`the check read ${frame}, a frame taken without a renderer, and stopped there: the checks after it did not run (put frame checks in t.frame so every other check runs)`);

package/src/node/polish.ts

@@ -78,6 +78,8 @@ interface UiDump {
   tick: number;
   /** The surface the CSS-pixel bounds are on (dpr: device pixels per CSS pixel). */
   surface?: { width: number; height: number; dpr: number } | null;
+  /** The configured UI style's name: "" is the engine's placeholder, prototype. */
+  style?: string | null;
   elements: Array<{ id: string; parent: string; kind?: string; disabled?: boolean; clipped?: boolean; text: string; x: number; y: number; width: number; height: number }>;
 }
 
@@ -626,6 +628,14 @@ function measure(rec: RunRecord, frameDir: string, frames: number, relTo: string
   const tickIndex = new Map(s.map((p, i) => [p.tick, i]));
   const findings: Finding[] = [];
 
+  // The UI's style: a game that shows UI in the engine's placeholder has
+  // not chosen its own look (og-taste §1).
+  const dressed = rec.shots
+    .filter((shot) => shot.ui && existsSync(shot.ui))
+    .map((shot) => JSON.parse(readFileSync(shot.ui!, "utf8")) as UiDump)
+    .filter((ui) => ui.elements.length > 0 && typeof ui.style === "string");
+  if (dressed.some((ui) => ui.style === "")) findings.push({ measure: "UI style", where: rec.playtest, detail: "the UI draws in prototype, the engine's placeholder style (greys, square corners), not a style of the game's own", fix: "og-taste §1: name a style in the game's look (`ui \"<slug>\"` or `ui \"styles/<name>/style.ogt\"`), or extend a catalogue preset, which names one" });
+
   // Frames: contrast, text size, HUD.
   const shots: PlaytestMeasures["shots"] = [];
   const allTexts: Array<TextBox & { shot: string }> = [];
@@ -660,14 +670,14 @@ function measure(rec: RunRecord, frameDir: string, frames: number, relTo: string
   }
   const contrastPass = allTexts.filter((b) => b.contrast >= 4.5);
   const worstContrast = [...allTexts].sort((a, b) => a.contrast - b.contrast).slice(0, 3).map((b) => ({ shot: b.shot, id: b.id, text: b.text.slice(0, 40), ratio: b.contrast }));
-  for (const w of worstContrast.filter((w) => w.ratio < 4.5)) findings.push({ measure: "contrast", where: `${rec.playtest} ${w.shot}: \`${w.id}\` "${w.text}"`, detail: `${w.ratio}:1 between ink and ground (body text wants 4.5:1)`, fix: "og-taste §3 (value before hue): darken the ground or lighten the ink in the skin's palette, never per call" });
+  for (const w of worstContrast.filter((w) => w.ratio < 4.5)) findings.push({ measure: "contrast", where: `${rec.playtest} ${w.shot}: \`${w.id}\` "${w.text}"`, detail: `${w.ratio}:1 between ink and ground (body text wants 4.5:1)`, fix: "og-taste §3 (value before hue): darken the ground or lighten the ink in the style's palette, never per call" });
   const sized = allTexts.filter((b) => b.ink > 0);
   // Ink lines of at least 9 px are a 13 px face (x-height and caps to descenders).
   const sizePass = sized.filter((b) => b.ink >= 9);
   const smallest = [...sized].sort((a, b) => a.ink - b.ink).slice(0, 3).map((b) => ({ shot: b.shot, id: b.id, text: b.text.slice(0, 40), ink: b.ink }));
   for (const w of smallest.filter((w) => w.ink < 9)) findings.push({ measure: "text size", where: `${rec.playtest} ${w.shot}: \`${w.id}\` "${w.text}"`, detail: `ink lines ${w.ink} CSS px tall (a 13 px face's capitals and digits are about 9)`, fix: "og-taste §4 and §10.6: use the ramp's body step or larger for anything read on a phone" });
   if (gameplayShots > 0 && (worstShare > 15 || worstCentre > 5))
-    findings.push({ measure: "HUD occupancy", where: `${rec.playtest}`, detail: `the HUD covers up to ${worstShare} % of the surface and ${worstCentre} % of the central third`, fix: "og-taste §2 (the play surface is the hero; HUD weight): capsules in the corners, the centre third free" });
+    findings.push({ measure: "HUD occupancy", where: `${rec.playtest}`, detail: `the HUD covers up to ${worstShare} % of the surface and ${worstCentre} % of the central third`, fix: "og-taste §2 (the play surface is the hero; HUD weight): HUD boxes in the corners, the centre third free" });
 
   // UI motion, transitions and sounds.
   let screenChanges = 0, withMotion = 0, motionTicks = 0;
@@ -728,7 +738,7 @@ function measure(rec: RunRecord, frameDir: string, frames: number, relTo: string
     else if (median(lat) > 1) findings.push({ measure: "input latency", where: rec.playtest, detail: `the median input is answered ${median(lat)} ticks after the tick it landed (0 is the same tick)`, fix: "og-feel §1: read input and act in the same tick; buffer, do not queue" });
   }
   if (screenChanges > 0 && withMotion < screenChanges) findings.push({ measure: "screen transitions", where: rec.playtest, detail: `${screenChanges - withMotion} of ${screenChanges} screen changes had no motion in the 20 ticks around them`, fix: "og-taste §5 (screens change through a transition): og.ui.screenTransition, one kind per game" });
-  if (presses > 0 && pressesWithSound < presses) findings.push({ measure: "UI sounds", where: rec.playtest, detail: `${presses - pressesWithSound} of ${presses} UI presses played no sound on the ui bus`, fix: "og-taste §6 (feedback) and og-audio §3: give the skin or og.ui.configure its press and open sounds" });
+  if (presses > 0 && pressesWithSound < presses) findings.push({ measure: "UI sounds", where: rec.playtest, detail: `${presses - pressesWithSound} of ${presses} UI presses played no sound on the ui bus`, fix: "og-taste §6 (feedback) and og-audio §3: give the style or og.ui.configure its press and open sounds" });
 
   // Damage facts and their feedback.
   const moments: number[] = [];

package/src/node/render.ts

@@ -0,0 +1,291 @@
+// `og render` on the native host (docs/design.md §2.9): the game run
+// headless at its own tick, one frame read back every `rate / fps` ticks,
+// streamed to `og` (crates/og-cli/src/render.rs), which writes the frames,
+// encodes the video and draws the contact sheet. One process of two kinds:
+//
+//   bun src/node/render.ts --entry <game.js> [--root <project>] [--seed S] [--size WxH]
+//       [--commands "t:action[:args];..."] --fps F [--from <seconds>] [--warmup W]
+//       [--clock <UTC ms>] [--locale <tag>] [--out <dir>]
+//       a range:    --first I --count N [--restore <snapshot>] [--audio <out.wav>]
+//       the leader: --leader --end N [--snapshot <frame>:<file>]... [--audio <out.wav>]
+//
+// Frame i of the render shows the world at tick T0 + i·k, where T0 is
+// round(from · rate) and k = rate / fps (the fps must divide the tick rate).
+// - A range sends frames I to I + N - 1, after W warm-up frames on the same
+//   grid before it (drawn, not sent: the renderer's history, TAA and the
+//   adapted exposure, is then that of a run that drew them). Ticks between
+//   frames are simulated without drawing. With --restore it starts from the
+//   leader's render snapshot, taken at the first warm-up frame's tick,
+//   instead of simulating from tick 0. With --audio the capture mixer's
+//   WAV from tick 0 to the range's end is written there.
+// - The leader (`og render --jobs N`) simulates to frame N's tick without
+//   drawing, writing a render snapshot at the first warm-up tick of each
+//   --snapshot frame, and the WAV.
+//
+// Stdout carries records only: a little-endian u32 length, that many bytes
+// of JSON, then the JSON's `bytes` of payload. A frame is
+// `{kind:"frame", index, tick, time, width, height, sha256, bytes}` with its
+// RGBA8 rows; the last record is `{kind:"end", ...}`. Everything else
+// (the engine's log, warnings) goes to stderr. Outputs of the script's own
+// steps (screenshot, dump_*) are written under --out.
+
+import { mkdirSync, readFileSync, writeFileSync, writeSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { loadNativeHost, native } from "./index.ts";
+import { openAudio } from "./audio.ts";
+import { nativePlatform } from "./platform.ts";
+import { createEngine, fixedClock, type Engine, type GameToken } from "../runtime.ts";
+
+declare const Bun: { sleepSync(ms: number): void };
+
+const argv = process.argv.slice(2);
+let entry = "";
+let root: string | undefined;
+let seed: number | undefined;
+let commands: string | undefined;
+let size = { width: 1280, height: 720 };
+let fps = 0;
+let fromSeconds = 0;
+let first: number | undefined;
+let count: number | undefined;
+let warmup = 0;
+let restore: string | undefined;
+let audioOut: string | undefined;
+let leader = false;
+let end: number | undefined;
+let clock: number | undefined;
+let locale: string | undefined;
+let out: string | undefined;
+const snapshots: { frame: number; file: string }[] = [];
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i]!;
+  const next = () => {
+    const v = argv[++i];
+    if (v === undefined) fail(`${a} needs a value`);
+    return v!;
+  };
+  const whole = (v: string) => {
+    const n = Number(v);
+    if (!Number.isInteger(n) || n < 0) fail(`${a} takes a whole number, not '${v}'`);
+    return n;
+  };
+  if (a === "--entry") entry = next();
+  else if (a === "--root") root = resolve(next());
+  else if (a === "--seed") seed = whole(next());
+  else if (a === "--commands") commands = next();
+  else if (a === "--size") {
+    const m = /^(\d+)x(\d+)$/.exec(next());
+    if (!m) fail("--size takes WIDTHxHEIGHT, such as 1280x720");
+    size = { width: Number(m![1]), height: Number(m![2]) };
+  } else if (a === "--fps") fps = whole(next());
+  else if (a === "--from") {
+    fromSeconds = Number(next());
+    if (!(Number.isFinite(fromSeconds) && fromSeconds >= 0)) fail("--from takes seconds, 0 or more");
+  } else if (a === "--first") first = whole(next());
+  else if (a === "--count") count = whole(next());
+  else if (a === "--warmup") warmup = whole(next());
+  else if (a === "--restore") restore = resolve(next());
+  else if (a === "--audio") audioOut = resolve(next());
+  else if (a === "--leader") leader = true;
+  else if (a === "--end") end = whole(next());
+  else if (a === "--snapshot") {
+    const v = next();
+    const at = v.indexOf(":");
+    if (at <= 0) fail("--snapshot takes <frame>:<file>");
+    snapshots.push({ frame: whole(v.slice(0, at)), file: resolve(v.slice(at + 1)) });
+  } else if (a === "--clock") clock = Number(next());
+  else if (a === "--locale") locale = next();
+  else if (a === "--out") out = resolve(next());
+  else fail(`unknown argument '${a}'`);
+}
+
+function fail(reason: string): never {
+  process.stderr.write(`og render: ${reason}\n`);
+  process.exit(2);
+}
+
+if (!entry) fail("no game entry: pass --entry <file>");
+if (fps <= 0) fail("--fps takes frames per second, such as 30");
+if (leader ? end === undefined : first === undefined || count === undefined) fail("a range takes --first and --count, the leader --end");
+
+/** One record on stdout: length, JSON, payload. */
+function record(header: Record<string, unknown>, payload?: Uint8Array): void {
+  const json = new TextEncoder().encode(JSON.stringify({ ...header, bytes: payload?.length ?? 0 }));
+  const len = new Uint8Array(4);
+  new DataView(len.buffer).setUint32(0, json.length, true);
+  writeAll(len);
+  writeAll(json);
+  if (payload) writeAll(payload);
+}
+
+function writeAll(bytes: Uint8Array): void {
+  let at = 0;
+  while (at < bytes.length) {
+    try {
+      at += writeSync(1, bytes, at, bytes.length - at);
+    } catch (e) {
+      // A pipe that is full answers EAGAIN on a non-blocking descriptor: wait.
+      if ((e as { code?: string }).code !== "EAGAIN") throw e;
+      Bun.sleepSync(1);
+    }
+  }
+}
+
+loadNativeHost();
+const extras = native();
+const mod = (await import(pathToFileURL(resolve(entry)).href)) as { default?: GameToken };
+if (!mod.default) fail(`${entry} has no default export: export default og.game({ ... })`);
+const projectText = root ? (() => {
+  try {
+    return readFileSync(join(root, "project.ogt"), "utf8");
+  } catch {
+    return undefined;
+  }
+})() : undefined;
+const profile = projectText ? (/^\s*profile\s+"(2d|3d)"/m.exec(projectText)?.[1] as "2d" | "3d" | undefined) : undefined;
+const created = createEngine(mod.default!, {
+  ...(seed === undefined ? {} : { seed }),
+  ...(root ? { root } : {}),
+  ...(projectText === undefined ? {} : { project: projectText }),
+  ...(profile ? { profile } : {}),
+  ...(locale ? { locale } : {}),
+  deferStart: true,
+});
+if (!created.ok) fail(`${entry}: ${created.reason}`);
+const engine: Engine = created.value;
+if (clock !== undefined) engine.setClock(fixedClock(engine, clock));
+engine.attachPlatform(nativePlatform(undefined));
+
+const rate = engine.rate;
+if (rate % fps !== 0) {
+  const divisors = [];
+  for (let d = 1; d <= rate; d++) if (rate % d === 0) divisors.push(d);
+  const below = divisors.filter((d) => d < fps).pop();
+  const above = divisors.find((d) => d > fps);
+  fail(`--fps ${fps} does not divide the game's tick rate ${rate}: a frame would fall between ticks; the nearest that do are ${[below, above].filter((d) => d !== undefined).join(" and ")}`);
+}
+const step = rate / fps;
+const tickMs = 1000 / rate;
+const t0 = Math.round(fromSeconds * rate);
+/** The tick frame `i` shows. */
+const tickOf = (i: number): number => t0 + i * step;
+/** The tick a range starting at frame `i` starts drawing at (its first warm-up frame). */
+const warmTick = (i: number): number => Math.max(0, tickOf(i) - warmup * step);
+
+// The renderer: the leader attaches one too, so GameDesc.start sees the same
+// play surface (og.render.capabilities) in every process of the render.
+const attached = JSON.parse(extras.og_node_attach_offscreen(engine.id, size.width, size.height)) as { ok: boolean; value?: string; reason?: string };
+if (!attached.ok && !leader) fail(`no renderer (${attached.reason}): og render needs a headless renderer (og doctor)`);
+const tier = attached.ok ? attached.value! : "none";
+const started = engine.advance(0);
+if (!started.ok) fail(started.reason);
+
+const sink = (() => {
+  const opened = openAudio(engine.id, audioOut ? "capture" : "null");
+  if (!opened.ok) fail(`audio: ${opened.reason}`);
+  return opened.value;
+})();
+
+const warnings: string[] = [];
+function drain(): void {
+  for (const o of engine.takeOutputs()) {
+    if (!out) continue;
+    const path = resolve(out, o.file);
+    const inside = relative(out, path);
+    if (inside === "" || inside.startsWith(".." + sep) || inside === ".." || isAbsolute(inside)) continue;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, o.kind === "png" || o.kind === "wav" ? Uint8Array.from(atob(o.data), (c) => c.charCodeAt(0)) : o.data);
+    process.stderr.write(`tick ${o.tick} ${o.action}: wrote ${path}\n`);
+  }
+  for (const l of engine.takeLog()) {
+    const line = `${l.warning ? "WARN" : "INFO"} tick ${l.tick}: ${l.text}`;
+    if (l.warning) warnings.push(line);
+    process.stderr.write(line + "\n");
+  }
+}
+drain();
+
+if (commands !== undefined) {
+  const report = engine.probe.commands(commands) as { warnings: string[] } | null;
+  drain();
+  if (!report) fail("--commands: the script is malformed (the reason is above)");
+  for (const w of report!.warnings) {
+    warnings.push(`WARN ${w}`);
+    process.stderr.write(`WARN ${w}\n`);
+  }
+}
+if (restore) {
+  const r = JSON.parse(extras.og_node_render_restore(engine.id, readFileSync(restore))) as { ok: boolean; value?: number; reason?: string };
+  if (!r.ok) fail(`--restore ${restore}: ${r.reason}`);
+}
+
+let quit = false;
+const tick = (): number => engine.probe.tick();
+
+/** Simulate to tick `t` without drawing. */
+function simulate(t: number): void {
+  const n = t - tick();
+  if (n <= 0) return;
+  const r = engine.advance(n);
+  if (!r.ok) fail(r.reason);
+  sink.pump();
+  drain();
+  // The probe takes no tick after a `quit` step.
+  if (tick() < t) quit = true;
+}
+
+/** Bring the world to tick `t` and draw it there. */
+function drawAt(t: number): void {
+  if (t > tick()) simulate(t - 1);
+  if (quit) return;
+  const answer = engine.frame(t > tick() ? tickMs : 0);
+  if (!answer.ok) fail(answer.reason ?? "the frame failed");
+  sink.pump();
+  drain();
+  if (answer.quit) quit = true;
+  if (!answer.rendered) fail("the frame was not drawn");
+}
+
+if (leader) {
+  for (const s of [...snapshots].sort((a, b) => a.frame - b.frame)) {
+    const at = warmTick(s.frame);
+    simulate(at);
+    if (tick() !== at) fail(`the world stopped at tick ${tick()} before snapshot tick ${at} (a quit step?)`);
+    const blob = extras.og_node_render_snapshot(engine.id);
+    if (blob.length === 0) fail(`the engine refused a snapshot at tick ${at}`);
+    writeFileSync(s.file, blob);
+  }
+  simulate(tickOf(end!));
+} else {
+  const from = tickOf(first!);
+  // Warm-up frames on the frame grid before the range: drawn, not sent.
+  for (let t = Math.max(tick(), warmTick(first!)); t < from && !quit; t += step) drawAt(t);
+  let sent = 0;
+  for (let i = first!; i < first! + count! && !quit; i++) {
+    const t = tickOf(i);
+    drawAt(t);
+    if (quit) break;
+    const rgba = extras.og_node_render_frame(engine.id);
+    if (rgba.length !== size.width * size.height * 4) fail(`frame ${i} read back ${rgba.length} bytes, not ${size.width}x${size.height} RGBA`);
+    const sha256 = createHash("sha256").update(rgba).digest("hex");
+    record({ kind: "frame", index: i, tick: t, time: t / rate, width: size.width, height: size.height, sha256 }, rgba);
+    sent++;
+  }
+  // The audio runs to the range's end, the last frame's span included.
+  if (audioOut && !quit) simulate(tickOf(first! + count!));
+  if (sent < count!) warnings.push(`WARN the script quit at tick ${tick()}: ${sent} of ${count} frames`);
+}
+
+let wavSha256: string | undefined;
+if (audioOut) {
+  const wav = sink.wav();
+  mkdirSync(dirname(audioOut), { recursive: true });
+  writeFileSync(audioOut, wav);
+  wavSha256 = createHash("sha256").update(wav).digest("hex");
+}
+sink.close();
+const dump = engine.probe.dump({ what: "world" }) as unknown as { hash: string };
+record({ kind: "end", tick: tick(), hash: dump.hash, rate, fromTick: t0, step, tier, quit, warnings, wavSha256 });
+process.exit(0);