@origingame/engine 0.2.0 → 0.4.0

package/src/node/run.ts

@@ -5,7 +5,8 @@
 //   bun src/node/run.ts --entry <game.js|.ts> [--root <project>] [--ticks N] [--seed S]
 //       [--setup action[:arg...]]... [--commands "t:action[:args];..."] [--out <dir>]
 //       [--port P] [--size WxH] [--realtime] [--watch <bundle.js>] [--no-render]
-//       [--audio null|device|<out.wav>] [--platform-store <file.json>] [--clock <UTC ms>] [--locale <tag>] [--json]
+//       [--audio null|device|<out.wav>] [--platform-store <file.json>] [--clock <UTC ms>] [--locale <tag>]
+//       [--trace <out.json> [--trace-append]] [--room ws://127.0.0.1:P/<room>] [--json]
 //
 // - Without --commands, --port or --watch: advance --ticks N at once and print
 //   the world hash (M2's hello world).
@@ -19,11 +20,21 @@
 //   through the probe's `reload` (snapshot, swap, restore), printing one JSON
 //   line per reload with the latency from the file write to the first frame
 //   of the new bundle.
+// - With --room: the engine joins that room through `og relay` (og.platform's
+//   rooms, og.net's lockstep), the link pumped around every frame, and the run
+//   takes frames (never one big advance), so a tick lockstep holds waits for
+//   the other players' inputs; it ends at `quit`, --ticks or the script's end.
 // - Without a renderer (no usable adapter, as in the platform's engine and
 //   probe sandboxes, or OG_RENDERER=none) the run is the same run: the play
 //   surface keeps --size, a `screenshot` writes no PNG and is listed in
 //   --json's `unchecked` ("no renderer, frame unchecked"), the tier is
 //   `none`, and the exit status does not change.
+// - With --trace: the run in the Chrome trace format (src/trace.ts and
+//   crates/og-runtime/src/trace.rs have the threads): each tick with its
+//   systems, each frame with its render passes' CPU encoding and their GPU
+//   time, each load, og-lanes' jobs on their pool threads, every span where
+//   it ran; --trace-append adds them to the file og wrote first (its
+//   metadata, its origin and the cook's spans).
 
 import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -32,7 +43,8 @@ import { pathToFileURL } from "node:url";
 import { loadNativeHost, native } from "./index.ts";
 import { openAudio, type AudioSink } from "./audio.ts";
 import { nativePlatform } from "./platform.ts";
-import { beginBundle, createEngine, fixedClock, type Engine, type GameToken } from "../runtime.ts";
+import { Trace, unixMs, type TraceDocument } from "../trace.ts";
+import { beginBundle, boundHost, createEngine, fixedClock, type Engine, type GameToken } from "../runtime.ts";
 
 const argv = process.argv.slice(2);
 let entry = "";
@@ -51,6 +63,9 @@ let audioOut = "null";
 let platformStore: string | undefined;
 let locale: string | undefined;
 let clock: number | undefined;
+let tracePath: string | undefined;
+let traceAppend = false;
+let room: string | undefined;
 const setup: string[] = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i]!;
@@ -79,6 +94,9 @@ for (let i = 0; i < argv.length; i++) {
   else if (a === "--platform-store") platformStore = resolve(next());
   else if (a === "--locale") locale = next();
   else if (a === "--clock") clock = Number(next());
+  else if (a === "--trace") tracePath = resolve(next());
+  else if (a === "--trace-append") traceAppend = true;
+  else if (a === "--room") room = next();
   else if (a === "--headless") {
     // Native runs are always headless; accepted for `og run --headless`.
   } else fail(`unknown argument '${a}'`);
@@ -97,6 +115,17 @@ if (port !== undefined && (!Number.isInteger(port) || port < 0 || port > 65535))
 
 loadNativeHost();
 const extras = native();
+
+// --trace: the Chrome trace (src/trace.ts), continuing og's prelude (the cook) when appending.
+const trace = tracePath
+  ? new Trace({ producer: "og run --trace", process: "og run", ...(traceAppend && existsSync(tracePath) ? { prior: JSON.parse(readFileSync(tracePath, "utf8")) as Partial<TraceDocument> } : {}) })
+  : undefined;
+/** Takes the engine's spans (each where it ran) onto the trace; `last` waits for the GPU's frames in flight. */
+function takeTrace(engineId: number, last = false): void {
+  if (!trace) return;
+  const taken = extras.og_node_trace_take(engineId, last);
+  trace.append(taken, unixMs());
+}
 let version = 0;
 /**
  * Import a bundle as a fresh module. A re-import goes through a copy under
@@ -131,15 +160,22 @@ function projectProfile(text: string | undefined): "2d" | "3d" | undefined {
 }
 
 const game = await importGame(entry);
+// Loads made while the engine is created (its boot scene's) are traced too.
+const BEFORE_ENGINE = 0xffffffff;
+if (tracePath) extras.og_node_trace(BEFORE_ENGINE, true);
 const project = projectText(root);
 const profile = projectProfile(project);
-const probing = commands !== undefined || port !== undefined || watchFile !== undefined;
+const probing = commands !== undefined || port !== undefined || watchFile !== undefined || room !== undefined;
 // With a renderer, GameDesc.start runs once it is attached (as the web Worker
 // does), so og.render.capabilities reports the play surface's size there.
 const deferStart = probing && render;
 const created = createEngine(game, { ...(seed === undefined ? {} : { seed }), ...(root ? { root } : {}), ...(project === undefined ? {} : { project }), ...(profile ? { profile } : {}), ...(locale ? { locale } : {}), ...(deferStart ? { deferStart } : {}) });
 if (!created.ok) fail(`${entry}: ${created.reason}`);
 const engine: Engine = created.value;
+if (tracePath) {
+  extras.og_node_trace(engine.id, true);
+  extras.og_node_trace(BEFORE_ENGINE, false);
+}
 // og.platform: the local store, in memory unless --platform-store names a file;
 // its clock the system's, or with --clock one that starts there and moves with the ticks.
 if (clock !== undefined) engine.setClock(fixedClock(engine, clock));
@@ -216,6 +252,23 @@ if (port !== undefined) {
   process.stdout.write(`probe: ws://127.0.0.1:${listening}/probe\n`);
 }
 
+if (room !== undefined) {
+  const linked = JSON.parse(extras.og_node_room_connect(engine.id, room)) as { ok: boolean; reason?: string };
+  if (!linked.ok) fail(`--room ${room}: ${linked.reason}`);
+  // The relay joins the room the URL names: wait for its answer before the first tick.
+  for (let i = 0; i < 2000 && (JSON.parse(abiRoomInfo()) as { state: string }).state !== "in"; i++) {
+    extras.og_node_room_pump(engine.id);
+    await new Promise((r) => setTimeout(r, 1));
+  }
+}
+
+function abiRoomInfo(): string {
+  return boundHost()!.abi.og_platform_room_info(engine.id);
+}
+
+type NetStatus = { running: boolean; startTick: number | null; waits: number; desync: number | null };
+const netStatus = (): NetStatus => JSON.parse(boundHost()!.abi.og_net_status(engine.id)) as NetStatus;
+
 let untilTick = -1;
 if (commands !== undefined) {
   const report = engine.probe.commands(commands) as { scheduled: number; untilTick: number; warnings: string[] } | null;
@@ -286,7 +339,9 @@ if (!probing) {
     }
     const elapsed = realtime ? performance.now() - last : tickMs;
     last = performance.now();
+    if (room !== undefined) extras.og_node_room_pump(engine.id);
     const answer = engine.frame(elapsed);
+    if (room !== undefined) extras.og_node_room_pump(engine.id);
     if (!answer.ok) {
       frameFailed = answer.reason ?? "the frame failed";
       break;
@@ -297,6 +352,7 @@ if (!probing) {
     }
     sink.pump();
     if (listening !== undefined) extras.og_node_probe_serve(engine.id);
+    takeTrace(engine.id);
     drain();
     const tick = answer.tick ?? 0;
     if (answer.quit) {
@@ -310,10 +366,22 @@ if (!probing) {
     const left = answer.pending ?? (tick > untilTick ? 0 : 1);
     if (ticks === undefined && commands !== undefined && listening === undefined && !watchFile && left === 0) break;
     if (realtime || listening !== undefined || watchFile) await sleep(Math.max(0, tickMs - (performance.now() - last)));
+    // In a room a frame that took no tick waits for the other players' inputs,
+    // and outside lockstep (its lobby, or a game that leaves it off) the run
+    // keeps the tick's pace with the other peers: an unpaced lobby would
+    // spend the run's --ticks before they arrive.
+    else if (room !== undefined && (answer.ticks ?? 0) === 0) await sleep(1);
+    else if (room !== undefined && !netStatus().running) await sleep(Math.max(0, tickMs - (performance.now() - last)));
   }
 }
 const ms = performance.now() - t0;
 drain();
+if (tracePath) {
+  takeTrace(engine.id, true);
+  mkdirSync(dirname(tracePath), { recursive: true });
+  writeFileSync(tracePath, JSON.stringify(trace!.document()));
+  outputs.push(tracePath);
+}
 let wavSha256: string | undefined;
 if (audioMode === "capture") {
   const wavPath = resolve(audioOut);
@@ -327,6 +395,8 @@ const audioStats = sink.stats();
 sink.close();
 if (frameFailed) process.stderr.write(`og run: ${frameFailed}\n`);
 const dump = engine.probe.dump({ what: "world" }) as unknown as { hash: string; entities: number; tick: number; systems?: SystemTimes };
+// The script's expectations (`expect:` steps): a failure fails the run.
+const expectations = engine.probe.expectations();
 // og polish's order statistics (src/node/polish.ts), so the two agree.
 const percentile = (xs: number[], q: number): number => {
   if (xs.length === 0) return 0;
@@ -359,19 +429,30 @@ const summary = {
   ticks: ticks ?? dump.tick,
   tick: dump.tick,
   hash: dump.hash,
+  // og.net's shared hash: the world without this peer's session, what lockstep peers compare.
+  netHash: JSON.parse(boundHost()!.abi.og_net_hash(engine.id)) as string,
+  // With --room: lockstep's state at the end (the tick it started, the waits, the first divergent tick).
+  ...(room !== undefined ? { lockstep: netStatus() } : {}),
   entities: dump.entities,
   advanceMs: +ms.toFixed(2),
   frames,
   systems,
   runtime: typeof Bun !== "undefined" ? `bun ${Bun.version}` : `node ${process.version}`,
   tier,
+  // Whether the device timed each render pass on the GPU (RenderCapabilities.gpuTimestamps): the trace's gpu thread and ProbeTimings.gpuPasses.
+  gpuTimestamps: (JSON.parse(boundHost()!.abi.og_render_capabilities(engine.id)) as { gpuTimestamps?: boolean }).gpuTimestamps ?? false,
   quit,
   unchecked,
   audio: { mode: audioMode, commands: audioStats.commands, receivedHash: audioStats.receivedHash, wavSha256 },
   outputs,
   warnings,
+  expectations,
 };
 if (asJson) process.stdout.write(JSON.stringify(summary) + "\n");
-else process.stdout.write(`tick ${dump.tick} hash ${dump.hash} entities ${dump.entities}\n`);
+else {
+  process.stdout.write(`tick ${dump.tick} hash ${dump.hash} entities ${dump.entities}\n`);
+  if (expectations.results.length > 0) process.stdout.write(`expectations: ${expectations.passed} passed, ${expectations.failed} failed, ${expectations.unchecked} unchecked\n`);
+}
 if (listening !== undefined) extras.og_node_probe_close(engine.id);
-process.exit(frameFailed ? 1 : 0);
+if (room !== undefined) extras.og_node_room_close(engine.id);
+process.exit(frameFailed || expectations.failed > 0 ? 1 : 0);

package/src/p2.ts

@@ -1,4 +1,4 @@
-// The phase 2 modules' namespaces (IDL `terrain`): thin calls into the host's binding symbols,
+// The phase 2 and depth modules' namespaces (IDL `terrain`, `stream`, `path`, `timeline`): thin calls into the host's binding symbols,
 // typed by the generated declarations through index.ts.
 
 import type { HostAbi } from "./generated/abi.ts";
@@ -33,3 +33,21 @@ export const stream = Object.freeze({
   budget: (world: W) => parse(abi().og_stream_budget(world.id)),
   setBudget: (world: W, bytes: number) => parse(abi().og_stream_set_budget(world.id, bytes)),
 });
+
+// Depth S2 (IDL `path`, `timeline`).
+export const path = Object.freeze({
+  create: (world: W, desc?: unknown) => parse(abi().og_path_create(world.id, json(desc))),
+  find: (world: W, name: string) => parse(abi().og_path_find(world.id, name)),
+  sample: (world: W, p: number, t: number) => parse(abi().og_path_sample(world.id, p, t)),
+  length: (world: W, p: number) => parse(abi().og_path_length(world.id, p)),
+  nearest: (world: W, p: number, point: unknown) =>
+    parse(abi().og_path_nearest(world.id, p, JSON.stringify(point))),
+});
+
+export const timeline = Object.freeze({
+  info: (world: W, asset: number) => parse(abi().og_timeline_info(world.id, asset)),
+  play: (world: W, entity: number) => parse(abi().og_timeline_play(world.id, entity)),
+  pause: (world: W, entity: number) => parse(abi().og_timeline_pause(world.id, entity)),
+  seek: (world: W, entity: number, time: number) => parse(abi().og_timeline_seek(world.id, entity, time)),
+  stop: (world: W, entity: number) => parse(abi().og_timeline_stop(world.id, entity)),
+});

package/src/platform-local.ts

@@ -28,6 +28,8 @@ export interface PlatformHost {
   /** `player`, `local` or `none` (og.platform.info). */
   readonly host: string;
   readonly capabilities: readonly string[];
+  /** The Player hello's UTC milliseconds, sampled when this host attaches. */
+  readonly time?: number | undefined;
   /** Handle calls in order; answer every one but `telemetry`, now or later. */
   handle(calls: readonly PlatformCall[], answer: (request: number, result: PlatformAnswer) => void): void;
 }

package/src/playtest.ts

@@ -52,6 +52,42 @@ export interface PlaytestRun {
   wav(file: string): { rate: number; frames: number; peak: number; rms: number };
   /** The runs of PlaytestDesc.then, in order, each with its own files (empty without `then`). */
   readonly then: readonly PlaytestRun[];
+  /** og.net's shared hash at the end (og.net.hash): the world without this process's session, what lockstep peers compare. */
+  readonly netHash: string;
+  /** With PlaytestDesc.room: og.net.status at the end (running, the start tick, the seats, the first divergent tick); null outside a room. */
+  readonly lockstep: PlaytestLockstep | null;
+  /** With PlaytestDesc.room: the room's other processes (peer scripts 1, 2, ...), each with its own files; empty outside a room. */
+  readonly peers: readonly PlaytestRun[];
+}
+
+/** og.net.status of a playtest process in a room, at its end. */
+export interface PlaytestLockstep {
+  readonly running: boolean;
+  readonly peer: number | null;
+  readonly startTick: number | null;
+  readonly players: number | null;
+  readonly waits: number;
+  /** The first divergent tick, once og.Desync was sent. */
+  readonly desync: number | null;
+}
+
+/** PlaytestDesc.room: the script's processes play together in one room. */
+export interface PlaytestRoom {
+  /** How many processes join the room (2 to 16). */
+  readonly players: number;
+  /** Each process's script by its place (0 is the playtest's own `commands`); a process without one runs `commands`. */
+  readonly commands?: readonly string[];
+  /** The room's name in the relay (default `playtest`). */
+  readonly name?: string;
+  /**
+   * The tick every process stops at (`og run --ticks`), when the scripts do not end first: their
+   * `netHash` there is what lockstep makes equal. Leave it out to end each script by its `quit`
+   * (or its last step). A script's steps are on the room's shared ticks once lockstep runs (a
+   * peer that takes the authority's snapshot at the start moves to its tick and its steps stay
+   * on theirs, a step whose tick it jumped past running at once), so a `quit` or an `expect` at
+   * tick t runs at tick t on every peer.
+   */
+  readonly ticks?: number;
 }
 
 /** The checks a playtest makes; a playtest that made none fails. */
@@ -91,6 +127,14 @@ export interface PlaytestDesc {
   readonly seed?: number;
   /** The render target, `WIDTHxHEIGHT` (default 1280x720). */
   readonly size?: string;
+  /**
+   * `action[:args];...` run once through the command channel after `start`, before the first
+   * tick (`og run --setup`), in every process of the playtest: the stand-ins for what a host does
+   * around the game, such as `cover:12,12,40,40`, the published page's Back over the play surface
+   * (`Viewport.covered`), so the frames lay out as the page's. Not part of `commands`: the
+   * published page plays a script without it and covers itself.
+   */
+  readonly setup?: string;
   /** Run the script this many times in fresh processes (default 1) and report every end hash in `run.hashes`: a determinism check. The files are the first run's. */
   readonly runs?: number;
   /**
@@ -106,9 +150,25 @@ export interface PlaytestDesc {
    * process has its own store in memory.
    */
   readonly store?: "keep";
-  /** More processes after the script, in order, each a fresh `og run` (a relaunch): their runs are `run.then`. */
+  /**
+   * Play the script in a room (docs/design.md §2.8, §2.10): the playtest starts a relay
+   * (`og relay`, in its own process) and runs `players` processes at once, each `og run
+   * --room ws://127.0.0.1:P/<name>` with its own script (`room.commands[i]`, else `commands`)
+   * and its own files. The first is the run; the others are `run.peers`. Every process stops
+   * at `room.ticks`, or at its script's `quit`, which lands on one tick of the room for all.
+   * `runs` is refused with it; each `then` step relaunches every process at once into a room of
+   * its own (`<name>.then-<n>`), each running the step's script, its runs in `run.then[n].peers`;
+   * `store: "keep"` keeps one store per place across them.
+   */
+  readonly room?: PlaytestRoom;
+  /** More processes after the script, in order, each a fresh `og run` (a relaunch): their runs are `run.then`. With `room`, every place of the room relaunches at once. */
   readonly then?: readonly PlaytestStep[];
-  readonly check: (run: PlaytestRun, t: PlaytestChecks) => void | Promise<void>;
+  /**
+   * Checks over what the run wrote. Optional when the script carries `expect:` steps: each
+   * expectation is a check (a failed one fails the playtest with its tick and observed value,
+   * a frame one without a renderer is unchecked), so a playtest can be its script alone.
+   */
+  readonly check?: (run: PlaytestRun, t: PlaytestChecks) => void | Promise<void>;
 }
 
 /** A later process of a playtest (`PlaytestDesc.then`). */
@@ -124,8 +184,9 @@ export const PLAYTEST_CLOCK = 1767225600000;
 
 /** Declare a playtest: the default export of a `tests/*.og.ts` file. */
 export function playtest(desc: PlaytestDesc): PlaytestDesc {
-  if (!desc.name || !desc.commands || typeof desc.check !== "function") {
-    throw new Error("playtest({ name, commands, check }) needs all three");
+  const expects = /(^|;)\s*[\d.]+:expect:/.test(desc.commands ?? "");
+  if (!desc.name || !desc.commands || (typeof desc.check !== "function" && !expects)) {
+    throw new Error("playtest({ name, commands, check }) needs all three (check may be left out when the commands carry expect: steps)");
   }
   return Object.freeze({ ...desc });
 }

package/src/runtime.ts

@@ -42,6 +42,8 @@ export interface ColumnSpec {
   readonly stride: number;
   /** The stride is each field's capacity (`str(32)`), not the kind's. */
   readonly capacity?: boolean;
+  /** The list factory (`list(u32(), 8)`): no kind of its own, a list field's kind is its element's. */
+  readonly list?: boolean;
 }
 
 export const COLUMNS: ReadonlyMap<string, ColumnSpec> = new Map(
@@ -122,6 +124,8 @@ export interface FieldSpec {
   readonly options: Record<string, unknown>;
   /** A `str` field's capacity in bytes. */
   readonly capacity?: number;
+  /** A list field's capacity in elements (`list(u32(), 8)`); `kind` is the element's. */
+  readonly list?: number;
 }
 
 export interface Token {
@@ -138,6 +142,7 @@ function fieldList(fields: Readonly<Record<string, FieldSpec>>): unknown[] {
     default: spec?.default,
     options: spec?.options ?? {},
     ...(spec?.capacity === undefined ? {} : { capacity: spec.capacity }),
+    ...(spec?.list === undefined ? {} : { list: spec.list }),
   }));
 }
 
@@ -150,13 +155,18 @@ export function defineRecord(kind: "component" | "resource", name: string, field
   return token;
 }
 
-function builtinFields(fields: ReadonlyArray<{ name: string; column?: string; type?: string; default?: unknown }>): Record<string, FieldSpec> {
+type DeclField = { name: string; column?: string; type?: string; default?: unknown; list?: number };
+
+function builtinFields(fields: ReadonlyArray<DeclField>): Record<string, FieldSpec> {
   const out: Record<string, FieldSpec> = {};
-  for (const f of fields) out[f.name] = Object.freeze({ kind: f.column ?? f.type ?? "", default: f.default, options: Object.freeze({}) });
+  for (const f of fields) {
+    const spec = { kind: f.column ?? f.type ?? "", default: f.default, options: Object.freeze({}) };
+    out[f.name] = Object.freeze(f.list === undefined ? spec : { ...spec, list: f.list });
+  }
   return out;
 }
 
-type Decl = { name: string; schema: string; fields: Array<{ name: string; column?: string; type?: string; default?: unknown }> };
+type Decl = { name: string; schema: string; fields: Array<DeclField> };
 
 /** The engine-owned tokens on `og`, under their schema names (`og.Transform`). */
 export const BUILTINS: Readonly<Record<string, Token>> = Object.freeze(
@@ -316,7 +326,9 @@ function layoutOf(component: Token): { names: string[]; kinds: ColumnSpec[] } {
       const kind = COLUMNS.get(field.kind);
       if (!kind) throw new Error(`'${component.name}.${n}' is not a column field`);
       // A str column's stride is the field's capacity: one byte lane per byte.
-      return kind.capacity ? { ...kind, stride: field.capacity ?? 0 } : kind;
+      if (kind.capacity) return { ...kind, stride: field.capacity ?? 0 };
+      // A list's is its element's, once for the count and once per element.
+      return field.list === undefined ? kind : { ...kind, stride: kind.stride * (field.list + 1) };
     });
     layouts.set(component, (l = { names, kinds }));
   }
@@ -483,6 +495,9 @@ interface RecordField {
   readonly size: number;
   readonly readonly: boolean;
   readonly variants?: readonly string[];
+  /** A list's element kind (`f32`, `f64`, `u32`, `i32`, `handle`) and capacity in elements. */
+  readonly element?: string;
+  readonly capacity?: number;
 }
 
 interface RecordLayout {
@@ -599,9 +614,55 @@ const LANES: Readonly<Record<string, readonly string[]>> = {
   Color: ["r", "g", "b"],
 };
 
+/** Bytes of one lane of a list's element kind. */
+const LANE_SIZE: Readonly<Record<string, number>> = { f32: 4, f64: 8, u32: 4, i32: 4, handle: 8 };
+
+function readLane(v: DataView, o: number, element: string): number {
+  switch (element) {
+    case "f32": return v.getFloat32(o, true);
+    case "f64": return v.getFloat64(o, true);
+    case "u32": return v.getUint32(o, true);
+    case "i32": return v.getInt32(o, true);
+    default: return v.getUint32(o, true) + v.getUint32(o + 4, true) * 4294967296;
+  }
+}
+
+function writeLane(v: DataView, o: number, element: string, n: number): void {
+  switch (element) {
+    case "f32": return v.setFloat32(o, n, true);
+    case "f64": return v.setFloat64(o, n, true);
+    case "u32": return v.setUint32(o, n, true);
+    case "i32": return v.setInt32(o, n, true);
+    default:
+      v.setUint32(o, n % 4294967296, true);
+      v.setUint32(o + 4, Math.floor(n / 4294967296), true);
+  }
+}
+
+/** A list element checked as the engine's JSON path checks it; throws what it refuses. */
+function listElement(value: unknown, element: string, i: number): number {
+  const n = number(value, `element ${i}`);
+  const whole = (lo: number, hi: number, what: string) => {
+    if (!Number.isInteger(n) || n < lo || n > hi) throw new Error(`element ${i}: ${n} is not ${what}`);
+  };
+  if (element === "u32") whole(0, 4294967295, "a u32");
+  else if (element === "i32") whole(-2147483648, 2147483647, "an i32");
+  else if (element === "handle") whole(0, 9007199254740991, "a handle");
+  return n;
+}
+
 function decodeField(v: DataView, bytes: Uint8Array, f: RecordField): unknown {
   const o = f.offset;
   switch (f.kind) {
+    case "list": {
+      // A frozen copy: `push` throws instead of changing nothing.
+      const element = f.element ?? "f32";
+      const lane = LANE_SIZE[element] ?? 4;
+      const count = Math.min(readLane(v, o, element), f.capacity ?? 0);
+      const out: number[] = [];
+      for (let i = 0; i < count; i++) out.push(readLane(v, o + lane * (i + 1), element));
+      return Object.freeze(out);
+    }
     case "f32": return v.getFloat32(o, true);
     case "f64": return v.getFloat64(o, true);
     case "u32": return v.getUint32(o, true);
@@ -639,6 +700,23 @@ function number(value: unknown, what: string): number {
 function encodeField(v: DataView, bytes: Uint8Array, f: RecordField, value: unknown): void {
   const o = f.offset;
   switch (f.kind) {
+    case "list": {
+      // The whole list: an array, at most the capacity, every element checked before a byte moves.
+      const element = f.element ?? "f32";
+      const capacity = f.capacity ?? 0;
+      const items = value === null || value === undefined ? [] : value;
+      if (!Array.isArray(items)) throw new Error(`a list is written whole, as an array, got ${JSON.stringify(value)}`);
+      if (items.length > capacity) {
+        const kind = element === "handle" ? "Asset" : element;
+        throw new Error(`${items.length} elements and the field holds ${capacity}: remove ${items.length - capacity}, or declare the field list(${kind}(), ${items.length}) or larger`);
+      }
+      const lanes = items.map((x, i) => listElement(x, element, i));
+      const lane = LANE_SIZE[element] ?? 4;
+      bytes.fill(0, o, o + f.size);
+      writeLane(v, o, element, lanes.length);
+      lanes.forEach((n, i) => writeLane(v, o + lane * (i + 1), element, n));
+      return;
+    }
     case "f32": return v.setFloat32(o, number(value, "the value"), true);
     case "f64": return v.setFloat64(o, number(value, "the value"), true);
     case "u32": {
@@ -732,7 +810,9 @@ function recordHandle(world: WorldImpl, r: RecordCopy): object {
         if (!refresh(r)) {
           const answer = parse<Result<Record<string, unknown>>>(host!.abi.og_world_resource(id, name));
           if (!answer.ok) throw new Error(`${name}: ${answer.reason}`);
-          return (lastValue = answer.value[key]);
+          const value = answer.value[key];
+          // A list reads as a frozen copy on this path too.
+          return (lastValue = Array.isArray(value) ? Object.freeze(value) : value);
         }
       }
       return (lastValue = decodeField(r.view, r.bytes, field()));
@@ -1122,7 +1202,7 @@ export class Engine {
   /** Attach what answers og.platform's calls: the native host's local store, the web shell's Player bridge. */
   attachPlatform(host: PlatformHost): void {
     this.#platform = host;
-    abi().og_platform_set_host(this.id, JSON.stringify({ host: host.host, capabilities: host.capabilities, time: this.#clock.now(), clock: this.#clock.kind }));
+    abi().og_platform_set_host(this.id, JSON.stringify({ host: host.host, capabilities: host.capabilities, time: host.time ?? this.#clock.now(), clock: host.time === undefined ? this.#clock.kind : "player" }));
   }
 
   /** Set the clock og.platform tells the game (before attachPlatform, which tells it the time). */
@@ -1311,6 +1391,10 @@ function makeProbe(id: number) {
     commands: (script: string) => parse(a().og_engine_probe_commands(id, script)),
     listen: (seconds?: number) => parse(a().og_engine_probe_listen(id, seconds)),
     memory: () => parse(a().og_engine_probe_memory(id)),
+    describe: () => parse(a().og_engine_probe_describe(id)),
+    expect: (what: string) => parse(a().og_engine_probe_expect(id, what)),
+    expectations: () => parse(a().og_engine_probe_expectations(id)),
+    saveScene: (write?: boolean, spawned?: boolean) => parse(a().og_engine_probe_save_scene(id, write, spawned)),
   });
 }
 
@@ -1331,6 +1415,7 @@ export const render = Object.freeze({
     parse(abi().og_render_update_material(world.id, material, json(desc))),
   capabilities: (world: WorldImpl) => parse(abi().og_render_capabilities(world.id)),
   applyLook: (world: WorldImpl, look: number) => parse(abi().og_render_apply_look(world.id, look)),
+  applyQuality: (world: WorldImpl, preset: string) => parse(abi().og_render_apply_quality(world.id, preset)),
   look: (world: WorldImpl) => parse(abi().og_render_look(world.id)),
   text: (world: WorldImpl, desc?: unknown) => parse(abi().og_render_text(world.id, json(desc))),
   sprite: (world: WorldImpl, desc?: unknown) => parse(abi().og_render_sprite(world.id, json(desc))),
@@ -1363,17 +1448,21 @@ export const load = Object.freeze({
   environment: (world: WorldImpl, path: string) => parse(abi().og_load_environment(world.id, path)),
   emitter: (world: WorldImpl, path: string) => parse(abi().og_load_emitter(world.id, path)),
   shader: (world: WorldImpl, path: string) => parse(abi().og_load_shader(world.id, path)),
-  skin: (world: WorldImpl, path: string) => parse(abi().og_load_skin(world.id, path)),
+  style: (world: WorldImpl, path: string) => parse(abi().og_load_style(world.id, path)),
   look: (world: WorldImpl, path: string) => parse(abi().og_load_look(world.id, path)),
   lookInfo: (world: WorldImpl, look: number) => parse(abi().og_load_look_info(world.id, look)),
   palette: (world: WorldImpl, path: string) => parse(abi().og_load_palette(world.id, path)),
   soundInfo: (world: WorldImpl, sound: number) => parse(abi().og_load_sound_info(world.id, sound)),
+  video: (world: WorldImpl, path: string) => parse(abi().og_load_video(world.id, path)),
+  videoInfo: (world: WorldImpl, video: number) => parse(abi().og_load_video_info(world.id, video)),
   status: (world: WorldImpl, asset: number) => abi().og_load_status(world.id, asset),
   error: (world: WorldImpl, asset: number) => parse(abi().og_load_error(world.id, asset)),
   gltfInfo: (world: WorldImpl, asset: number) => parse(abi().og_load_gltf_info(world.id, asset)),
   animation: (world: WorldImpl, path: string) => parse(abi().og_load_animation(world.id, path)),
+  timeline: (world: WorldImpl, path: string) => parse(abi().og_load_timeline(world.id, path)),
   flipbook: (world: WorldImpl, path: string) => parse(abi().og_load_flipbook(world.id, path)),
   rig: (world: WorldImpl, path: string) => parse(abi().og_load_rig(world.id, path)),
+  rig2d: (world: WorldImpl, path: string) => parse(abi().og_load_rig2d(world.id, path)),
   tilemap: (world: WorldImpl, path: string) => parse(abi().og_load_tilemap(world.id, path)),
 });
 
@@ -1381,8 +1470,10 @@ export const anim = Object.freeze({
   graph: (world: WorldImpl, desc?: unknown) => parse(abi().og_anim_graph(world.id, json(desc))),
   humanoid: (world: WorldImpl, desc?: unknown) => parse(abi().og_anim_humanoid(world.id, json(desc))),
   retarget: (world: WorldImpl, desc?: unknown) => parse(abi().og_anim_retarget(world.id, json(desc))),
-  // One lookup for a flipbook's clips (an index, -1 when missing) and a
-  // loaded model's (og.load.animation: a ClipAsset, 0 when missing).
+  rig2dInfo: (world: WorldImpl, rig: number) => parse(abi().og_anim_rig2d_info(world.id, rig)),
+  skeleton2dBoxes: (world: WorldImpl, entity: number) => parse(abi().og_anim_skeleton2d_boxes(world.id, entity)),
+  // One lookup for a flipbook's or a 2D rig's clips (an index, -1 when
+  // missing) and a loaded model's (og.load.animation: a ClipAsset, 0 when missing).
   clip: (info: { clips?: ReadonlyArray<{ clip: number; name: string }>; skeleton?: number }, name: string): number =>
     info?.clips?.find((c) => c.name === name)?.clip ?? (info?.skeleton !== undefined ? 0 : -1),
 });

package/src/targets.ts

@@ -0,0 +1,28 @@
+// Depth S8's additions (IDL `render` render targets and custom post
+// passes, `load.post`): thin calls into the host's binding symbols, typed by
+// the generated declarations through index.ts.
+
+import type { HostAbi } from "./generated/abi.ts";
+import { boundHost } from "./runtime.ts";
+
+type W = { readonly id: number };
+
+function abi(): HostAbi<Uint32Array, unknown> {
+  const h = boundHost();
+  if (!h) throw new Error("no engine host is loaded: start the game through @origingame/engine's web or node loader");
+  return h.abi;
+}
+
+const parse = <T>(text: string): T => JSON.parse(text) as T;
+const json = (value: unknown): string | undefined => (value === undefined ? undefined : JSON.stringify(value));
+
+export const targetsRender = Object.freeze({
+  renderTarget: (world: W, desc?: unknown) => parse(abi().og_render_render_target(world.id, json(desc))),
+  setPostParam: (world: W, post: number, name: string, value: ReadonlyArray<number>) =>
+    parse(abi().og_render_set_post_param(world.id, post, name, JSON.stringify(value))),
+  postErrors: (world: W) => parse(abi().og_render_post_errors(world.id)),
+});
+
+export const targetsLoad = Object.freeze({
+  post: (world: W, path: string) => parse(abi().og_load_post(world.id, path)),
+});