@origingame/engine 0.2.0 → 0.3.0

package/src/web/shell.ts

@@ -30,6 +30,7 @@ import { laneChoice } from "./lanes.ts";
 import { createRpcRings, readFrames, waitForFrames, writeFrame, type RpcRings } from "./rpc-ring.ts";
 import { localPlatform, storagePersistence, type PlatformCall, type PlatformHost } from "../platform-local.ts";
 import type { BootPhases } from "./worker.ts";
+import type { TraceDocument } from "../trace.ts";
 
 export interface ShellOptions {
   /** The play surface. Its pixel size is set from its CSS size and the device pixel ratio. */
@@ -78,6 +79,8 @@ export interface ShellOptions {
   readonly locale?: string;
   /** What answers og.platform's calls; default: the browser's own storage (`setPlatform` changes it, a Player bridge for instance). */
   readonly platform?: PlatformHost;
+  /** Record the run's trace from the boot on, the boot scene's loads included (`trace()` reads it; `trace("start")` begins one later). */
+  readonly trace?: boolean;
 }
 
 /** The pixel size of a canvas laid out at `cssWidth`×`cssHeight` on this display, with the DPR cap. */
@@ -93,6 +96,17 @@ export const PAGE_PREFERENCES = [
   ["reducedTransparency", "(prefers-reduced-transparency: reduce)"],
 ] as const;
 
+/**
+ * What carries og.platform's rooms on the web (docs/design.md §2.8): the engine's room ops
+ * (`{ op: "create" | "join" | "leave" | "send", ... }`, og-net's protocol) in, its room events
+ * (`joined`, `peer_joined`, `peer_left`, `message`, `left`, `error`) out, in order.
+ */
+export interface RoomHost {
+  /** og.platform.roomInfo's `host`: `player` for the Player's rooms. */
+  readonly host: string;
+  handle(ops: readonly Record<string, unknown>[], deliver: (events: unknown[]) => void): void;
+}
+
 /** The page's motion, contrast and transparency preferences and the platform's editing keys, as the viewport carries them to og-ui. */
 export function pagePreferences(): { reducedMotion: boolean; highContrast: boolean; reducedTransparency: boolean; macKeys: boolean } {
   const query = (q: string) => globalThis.matchMedia?.(q).matches ?? false;
@@ -203,6 +217,7 @@ export class Shell {
   /** When the deadline was last looked at: a late look means the page itself was blocked. */
   #watched = 0;
   #watchdog: ReturnType<typeof setInterval> | undefined;
+  #rooms: RoomHost | null = null;
   #platform: PlatformHost = localPlatform(storagePersistence(`og.platform:${globalThis.location?.pathname ?? "/"}`));
 
   private constructor(worker: Worker, ready: Ready, rpc: RpcRings | undefined) {
@@ -250,6 +265,14 @@ export class Shell {
         this.#answer(m.frame);
         return;
       }
+      if (m.type === "room") {
+        const ops = (m as unknown as { ops: Record<string, unknown>[] }).ops ?? [];
+        const deliver = (events: unknown[]) => worker.postMessage({ type: "room-events", events });
+        if (this.#rooms) this.#rooms.handle(ops, deliver);
+        // No room host: what asked for a room hears so (the engine refuses first while its host is none).
+        else deliver(ops.filter((o) => o["op"] === "create" || o["op"] === "join").map((o) => ({ type: "error", op: o["op"], code: "unavailable", message: "this page carries no rooms" })));
+        return;
+      }
       if (m.type === "platform") {
         const calls = (m as unknown as { calls: PlatformCall[] }).calls ?? [];
         this.#platform.handle(calls, (request, answer) => worker.postMessage({ type: "platform-answer", request, answer }));
@@ -347,6 +370,7 @@ export class Shell {
         locale: options.locale ?? globalThis.navigator?.language,
         ...(options.expect ? { expect: options.expect } : {}),
         ...(options.prime ? { prime: true } : {}),
+        ...(options.trace ? { trace: true } : {}),
         viewport: { width: canvas.clientWidth || canvas.width / dpr, height: canvas.clientHeight || canvas.height / dpr, dpr, coarsePointer: globalThis.matchMedia?.("(pointer: coarse)").matches ?? false, ...pagePreferences() },
       },
       [offscreen],
@@ -416,6 +440,27 @@ export class Shell {
   }
 
   /** Call the engine in the Worker: `advance`, `command`, `hash`, `frame`, or `probe` with a member name. */
+  /**
+   * The run's trace in the Chrome trace format, as `og run --trace` writes it natively (src/trace.ts):
+   * buffered in the engine Worker, taken here. `take` (the default) answers the document so far (null
+   * when no trace is recorded), `start` begins one (`ShellOptions.trace` starts one at the boot),
+   * `stop` ends it.
+   */
+  trace(action: "take" | "start" | "stop" = "take"): Promise<TraceDocument | null | boolean> {
+    return this.call("trace", action) as Promise<TraceDocument | null | boolean>;
+  }
+
+  /** Saves the trace so far as a JSON file the browser downloads (`name`, default `trace.json`): open it in Perfetto. False when none is recorded. */
+  async saveTrace(name = "trace.json"): Promise<boolean> {
+    const doc = await this.trace("take");
+    if (!doc || typeof doc !== "object") return false;
+    const url = URL.createObjectURL(new Blob([JSON.stringify(doc)], { type: "application/json" }));
+    const a = Object.assign(document.createElement("a"), { href: url, download: name });
+    a.click();
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+    return true;
+  }
+
   call(method: string, ...args: unknown[]): Promise<unknown> {
     if (this.#stopped) return Promise.reject(this.#stopped);
     const id = this.#next++;
@@ -425,6 +470,19 @@ export class Shell {
     });
   }
 
+  /**
+   * What carries og.platform's rooms from now on (og.platform.roomInfo's `host`); null for
+   * none, where roomCreate and roomJoin are refused. A host already carrying a room keeps it
+   * until its `left`: the engine is told the new host only for its next room. `link` is the room
+   * a Play link named (`?room=<id>`, the play page passes it): the engine joins it once, itself,
+   * as soon as a host carries rooms (og.RoomJoined answers, as for roomJoin; with none it says
+   * this page carries no rooms), and og.platform.roomInfo's `link` names it.
+   */
+  setRooms(host: RoomHost | null, link?: string): void {
+    this.#rooms = host;
+    this.worker.postMessage({ type: "room-host", host: host ? host.host : "none", ...(link ? { join: link } : {}) });
+  }
+
   /** What answers og.platform's calls from now on (og.platform.info reports its host and capabilities). */
   setPlatform(host: PlatformHost): void {
     this.#platform = host;

package/src/web/worker.ts

@@ -44,7 +44,7 @@
 // Worker's animation frames while the clock played, so isolated pages never
 // answered.
 
-import { createEngine, systemClock, type Engine, type GameToken } from "../runtime.ts";
+import { boundHost, createEngine, systemClock, type Engine, type GameToken } from "../runtime.ts";
 import type { PlatformAnswer, PlatformHost } from "../platform-local.ts";
 import { loadWebHost, type WebGlue } from "./host.ts";
 import { drainRing, stampAt, type InjectedInput } from "./input.ts";
@@ -53,6 +53,7 @@ import { readFrames, waitForFrames, writeFrame, type RpcRings } from "./rpc-ring
 import { loadBasisTranscoder, transcodeKtx2, TEXTURE_FORMATS, type BasisTranscoder, type TextureFormat } from "./basis.ts";
 import type { HostError } from "./shell.ts";
 import { PlatformCounter, settle, SETTLE_FIRST_MS, SETTLE_MS } from "./settle.ts";
+import { Trace, unixMs } from "../trace.ts";
 
 interface Start {
   type: "start";
@@ -92,6 +93,8 @@ interface Start {
    * game's first screen (its UI is built by ticks), then the ticks that apply the platform's answers to it (settle.ts).
    */
   prime?: boolean;
+  /** Record the run's trace from the boot on (src/trace.ts; the shell's `trace()` reads it). */
+  trace?: boolean;
 }
 
 type Viewport = { width: number; height: number; dpr: number; safeArea?: Record<string, number>; covered?: Record<string, number>; coarsePointer?: boolean; reducedMotion?: boolean; highContrast?: boolean; reducedTransparency?: boolean; macKeys?: boolean };
@@ -113,9 +116,26 @@ type Message =
   | { type: "resize"; width: number; height: number; viewport: Viewport }
   | { type: "platform-answer"; request: number; answer: PlatformAnswer }
   | { type: "platform-host"; host: string; capabilities: string[] }
+  | { type: "room-events"; events: unknown[] }
+  | { type: "room-host"; host: string; join?: string }
   | AudioMessage
   | AudioLatencyMessage;
 
+/**
+ * Rooms (docs/design.md §2.8): the engine's room ops (og_room_take) go to the
+ * page as `room` messages, which the shell's room host carries (the Player's
+ * room.*, docs/platform-asks.md #16); the page's `room-events` come back
+ * through og_room_deliver, in order, and `room-host` names what carries them.
+ * Ops are taken after every frame and after events are delivered, so
+ * lockstep's inputs leave on the frame that made them.
+ */
+function pumpRoom(engine: Engine): void {
+  const host = boundHost();
+  if (!host) return;
+  const ops = JSON.parse(host.abi.og_room_take(engine.id)) as unknown[];
+  if (ops.length > 0) self.postMessage({ type: "room", ops });
+}
+
 /** og.platform's host in the Worker: the calls go to the page (counted), whose answers come back as `platform-answer`. */
 function toPage(host: string, capabilities: readonly string[], counter: PlatformCounter): PlatformHost {
   return {
@@ -159,12 +179,21 @@ export interface WebExtras {
   og_web_memory?(engine: number): string;
   /** Make one pipeline no frame used yet (og-render's Renderer::warm); false when none is left. */
   og_web_warm?(engine: number): boolean;
+  /** `og render`'s every-frame capture (development builds): the display frame drawn last as RGBA8 rows at the canvas's size; empty until its readback lands. */
+  og_web_render_frame?(engine: number): Uint8Array;
   /** The first Rust panic recorded (JSON: kind, message, location, tick, lane), or `null`. */
   og_web_panic?(): string;
   /** Test hook: the next item at a lanes site panics (in a lane when the call splits). */
   og_web_lanes_fault?(site: string): boolean;
+  /** The trace (crates/og-runtime/src/trace.rs): on or off for an engine (0xffffffff: the loads before one exists). */
+  og_web_trace?(engine: number, on: boolean): void;
+  /** The trace's spans since the last take: `{ now, events }`, Chrome trace events on the engine's clock. */
+  og_web_trace_take?(engine: number, last: boolean): string;
 }
 
+/** The trace's key for loads made before the engine exists (og-runtime's `BEFORE_ENGINE`). */
+const TRACE_BEFORE_ENGINE = 0xffffffff;
+
 /** Where the runtime asks for a bundle's files: `<root>/cooked/<file>` (crates/og-runtime/src/assets.rs). */
 export function cookedDir(root: string): string {
   return `${root.replace(/\/+$/, "")}/cooked`;
@@ -514,6 +543,9 @@ export function startWorker(game: GameToken): void {
     phaseAt = now;
   };
   const firstFrameMessage = () => ({ type: "frame", first: true, boot: { ...boot, at: Math.round(performance.now()) } });
+  /** What the trace's document records beside its events: the renderer's tier and the lanes. */
+  let lastTier = "none";
+  let lanesState: unknown = null;
   let glueRef: (WebGlue & WebExtras & WebAudioGlue) | null = null;
   let audio: WorkerAudio | null = null;
   /** Captures waiting for their readback (requested on tick N, answered on N + 1). */
@@ -592,7 +624,21 @@ export function startWorker(game: GameToken): void {
   };
 
   /** What a frame's answer tells the shell: the UI's focused text control (text-input.ts), a copy, and the accessibility tree when it changed (a11y.ts). */
+  /** The run's trace while one is recorded (src/trace.ts): taken after every frame, so the engine holds a frame's spans at most. */
+  let trace: Trace | null = null;
+  const takeTrace = (last = false) => {
+    if (!trace || !engine || !glueRef?.og_web_trace_take) return;
+    trace.append(glueRef.og_web_trace_take(engine.id, last), unixMs());
+  };
+  const traceOn = (on: boolean) => {
+    if (!engine || !glueRef?.og_web_trace) return false;
+    if (on && !trace) trace = new Trace({ producer: "og web trace", process: "og web" });
+    if (!on) trace = null;
+    glueRef.og_web_trace(engine.id, on);
+    return true;
+  };
   const relay = (answered: ReturnType<Engine["frame"]>) => {
+    takeTrace();
     if (!answered.ok) return;
     const target = JSON.stringify(answered.text ?? null);
     if (target !== textTarget) {
@@ -676,6 +722,7 @@ export function startWorker(game: GameToken): void {
         }
         behind = answered.behind ?? 0;
         relay(answered);
+        pumpRoom(engine);
         if (typeof answered.tick === "number") lastTick = answered.tick;
         if (!firstFrame && answered.rendered !== false) {
           firstFrame = true;
@@ -777,11 +824,25 @@ export function startWorker(game: GameToken): void {
   };
 
   const calls: Record<string, (e: Engine, args: unknown[]) => unknown> = {
-    advance: (e, [n]) => e.advance(Number(n)),
+    // A harness's ticks carry the room as the page's own frames do: lockstep's inputs leave with them.
+    advance: (e, [n]) => {
+      const answered = e.advance(Number(n));
+      pumpRoom(e);
+      return answered;
+    },
     command: (e, [action, args]) => e.command(String(action), (args as string[]) ?? []),
     hash: (e) => e.hash(),
     /** What the engine holds (ProbeMemory: the wasm linear memory, the counted heap, the world, streaming, audio), in every build. */
     memory: (e) => JSON.parse(glueRef?.og_web_memory?.(e.id) ?? "null"),
+    /**
+     * The display frame drawn last as RGBA8 rows (the probe's Capture::frame,
+     * `og render`'s every-frame capture), or null until its readback lands: the
+     * first call turns the keeping of frames on; ask again before the next frame.
+     */
+    renderFrame: (e) => {
+      const rgba = glueRef?.og_web_render_frame?.(e.id);
+      return rgba && rgba.length > 0 ? rgba : null;
+    },
     /** What the lanes did so far (crates/og-runtime/src/lanes.rs `report`). */
     lanes: () => JSON.parse(glueRef?.og_web_lanes?.() ?? "null"),
     /** Test hook: the next item at lanes site `site` panics (og_web_lanes_fault); false when the module has no such hook or site. */
@@ -789,8 +850,14 @@ export function startWorker(game: GameToken): void {
     frame: (e, [ms]) => {
       const answered = e.frame(Number(ms));
       relay(answered);
+      pumpRoom(e);
       return answered;
     },
+    /** og.net on this page: og.net.status (lockstep running, its start tick, the seats, the first divergent tick) and the shared hash, as `og run --json` reports them natively (`lockstep`, `netHash`). */
+    net: (e) => {
+      const abi = boundHost()!.abi;
+      return { status: JSON.parse(abi.og_net_status(e.id)), hash: JSON.parse(abi.og_net_hash(e.id)), room: JSON.parse(abi.og_platform_room_info(e.id)) };
+    },
     // The frames played since the last reset (at most FRAME_RECORDS, oldest first); `true` resets.
     timings: (_, [reset]) => {
       const n = Math.min(recorded, FRAME_RECORDS);
@@ -799,6 +866,22 @@ export function startWorker(game: GameToken): void {
       if (reset) recorded = 0;
       return answer;
     },
+    /**
+     * The run's trace (src/trace.ts): `start` begins one (dropping any), `stop` ends it, `take` (the
+     * default) answers the document so far, a Chrome trace as `og run --trace` writes it; null when
+     * none is recorded or the module cannot trace.
+     */
+    trace: (_, [action]) => {
+      const a = String(action ?? "take");
+      if (a === "start") {
+        traceOn(false);
+        return traceOn(true);
+      }
+      if (a === "stop") return traceOn(false);
+      if (!trace) return null;
+      takeTrace(true);
+      return trace.document({ tier: lastTier, lanes: lanesState });
+    },
     probe: (e, [member, ...rest]) => {
       const f = (e.probe as unknown as Record<string, unknown>)[String(member)];
       if (typeof f !== "function") throw new TypeError(`probe has no member '${String(member)}'`);
@@ -870,6 +953,8 @@ export function startWorker(game: GameToken): void {
           installFetcher(glue, fetched.manifest ?? "", data.basis, () => (rendering && engine ? engine.id : null));
         }
         phase("bundle");
+        // A trace from the boot on records the boot scene's loads too.
+        if (data.trace) glue.og_web_trace?.(TRACE_BEFORE_ENGINE, true);
         const created = createEngine(game, {
           ...(data.seed === undefined ? {} : { seed: data.seed }),
           ...(data.root === undefined ? {} : { root: data.root }),
@@ -881,6 +966,10 @@ export function startWorker(game: GameToken): void {
         });
         if (!created.ok) throw new Error(created.reason);
         engine = created.value;
+        if (data.trace) {
+          traceOn(true);
+          glue.og_web_trace?.(TRACE_BEFORE_ENGINE, false);
+        }
         // og.platform: calls go to the page, which answers them (the Player, or the browser's storage).
         // The time is the browser's until the Player's answers carry its own (docs/platform-asks.md).
         engine.setClock(systemClock("browser"));
@@ -896,6 +985,8 @@ export function startWorker(game: GameToken): void {
           rendering = true;
         }
         phase("attach");
+        lastTier = tier;
+        lanesState = lanes;
         // The textures go to the renderer's encodings, so after it is attached (the game starts later).
         const loaded = fetched ? await transcodeBundle(glue, rendering ? engine.id : null, fetched, data.basis, progress, data.expect ? received : undefined) : null;
         phase("transcode");
@@ -983,6 +1074,16 @@ export function startWorker(game: GameToken): void {
       platformCounter.answered();
     }
     if (data.type === "platform-host") engine.attachPlatform(toPage(data.host, data.capabilities, platformCounter));
+    if (data.type === "room-host") {
+      boundHost()?.abi.og_room_set_host(engine.id, JSON.stringify({ host: data.host, ...(data.join ? { join: data.join } : {}) }));
+      // A Play link's join leaves now, not with the next frame (the page may be behind its gate).
+      pumpRoom(engine);
+    }
+    if (data.type === "room-events") {
+      const abi = boundHost()?.abi;
+      for (const event of data.events) abi?.og_room_deliver(engine.id, JSON.stringify(event));
+      pumpRoom(engine);
+    }
     if (data.type === "play") {
       playing = data.on;
       last = 0;