@origingame/engine 0.2.0 → 0.4.0

package/shell/page.ts

@@ -18,7 +18,9 @@
 // - the error card (§6): the reason, the last 200 log lines and the world
 //   dump (state in a publish build), with Reload and Copy report;
 // - the probe: `globalThis.__runtime_probe__` (protocol 5, every member a
-//   Promise, plus `lanes`, `memory()` (what the engine holds), `boot`
+//   Promise, plus `lanes`, `memory()` (what the engine holds), `trace()`
+//   and `saveTrace()` (the run's Chrome trace; `?trace` records from the
+//   boot), `boot`
 //   (where the Worker's boot went) and
 //   `error`: what stopped the engine, a panic with its tick and lane, an
 //   error or a hang) and the platform's `og-probe`
@@ -34,7 +36,7 @@ import { pollGamepads } from "../src/web/gamepad.ts";
 import { mountWire } from "./wire.ts";
 import { connectPlayer } from "./player.ts";
 import { connectPage, pageGame, type PageConnection, type PageInfo } from "./transport.ts";
-import { deferredPlatform, HELLO_WAIT_MS, playerPlatform, storagePersistence } from "./platform.ts";
+import { deferredPlatform, HELLO_WAIT_MS, playerPlatform, playerRooms, storagePersistence } from "./platform.ts";
 import { localPlatform, memoryPersistence, type PlatformHost } from "../src/platform-local.ts";
 
 /** The page's configuration (`<script type="application/json" id="og-config">`, written by og build). */
@@ -62,12 +64,14 @@ export interface ShellConfig {
 const PROBE_GLOBAL = "__runtime_probe__";
 const TIMINGS_GLOBAL = "__og_timings__";
 const REPLAY_SEED_PARAM = "replay-seed";
+const TRACE_PARAM = "trace";
 const LOG_LINES = 200;
 const INSTALL_DISMISSED = "og-install-dismissed";
 
 const MEMBERS = [
   "hello", "tick", "state", "advance", "pause", "resume", "input", "accepted", "pick", "entity",
   "bounds", "patch", "run", "capture", "sweep", "reload", "snapshot", "restore", "dump", "commands",
+  "describe", "expect", "expectations",
 ] as const;
 
 /** Positional protocol-5 arguments to JSON-RPC params, as og-probe reads them. */
@@ -91,6 +95,8 @@ export function probeParams(member: string, args: unknown[]): Record<string, unk
       return { width: args[0] ?? 0, height: args[1] ?? 0 };
     case "commands":
       return { script: args[0] };
+    case "expect":
+      return { what: args[0] };
     case "sweep":
     case "dump":
       return (args[0] as Record<string, unknown>) ?? {};
@@ -178,6 +184,9 @@ export interface PlayHandle {
 export async function play(): Promise<PlayHandle> {
   const config = readConfig();
   const query = new URLSearchParams(location.search);
+  // A Play link to a room (`?room=<id>`, docs/platform-asks.md #16): the engine joins it at load
+  // once a host carries rooms (the Player's room.*), og.RoomJoined answering as for roomJoin.
+  const roomLink = query.get("room") ?? undefined;
   const t0 = performance.now();
   const log = new LogTail();
   const playerEvents: import("./player.ts").PlayerEvents = {};
@@ -446,6 +455,8 @@ export async function play(): Promise<PlayHandle> {
       // Behind the gate, the first screen: one tick builds the game's UI (a harness keeps tick 0).
       prime: !harness,
       ...(seed === undefined ? {} : { seed }),
+      // `?trace`: the run's trace from the boot on (the probe's `trace()` and `saveTrace()` read it).
+      ...(query.has(TRACE_PARAM) ? { trace: true } : {}),
       profile: config.profile,
       ...(config.project === undefined ? {} : { project: config.project }),
       dprCap: config.dprCap,
@@ -494,8 +505,14 @@ export async function play(): Promise<PlayHandle> {
   // `boot`: where the Worker's boot went (src/web/worker.ts BootPhases), null before the first frame.
   Object.defineProperty(probe, "boot", { get: () => shell.boot, enumerable: true });
   for (const m of MEMBERS) probe[m] = (...args: unknown[]) => shell.probe(m, probeParams(m, args));
+  // `saveScene`: the wire's save_scene; a page writes no file, so it answers the text.
+  probe["saveScene"] = () => shell.probe("save_scene", { write: false });
   // `memory`: what the engine holds (ProbeMemory), from the Worker in every build (a publish probe has no `memory`).
   probe["memory"] = () => shell.call("memory");
+  // `trace`: the run's Chrome trace, as `og run --trace` writes it ("take", "start", "stop");
+  // `saveTrace`: the same, downloaded as a file (`?trace` records from the boot).
+  probe["trace"] = (action?: "take" | "start" | "stop") => shell.trace(action);
+  probe["saveTrace"] = (name?: string) => shell.saveTrace(name);
   (globalThis as Record<string, unknown>)[PROBE_GLOBAL] = Object.freeze(probe);
   // The played frames' display intervals and engine work, ms (`og run --device` reads them; `true` resets).
   (globalThis as Record<string, unknown>)[TIMINGS_GLOBAL] = (reset?: boolean) => shell.call("timings", reset === true);
@@ -576,6 +593,10 @@ export async function play(): Promise<PlayHandle> {
     helloForPlatform();
     // What it answers may have changed with this hello.
     shell.setPlatform(playerPlatform(player, platformStore));
+    // Rooms ride the Player's postMessage link (pushed events): a framed Player's, never the HTTP page's.
+    const rooms = playerRooms(player);
+    shell.setRooms(rooms, roomLink);
+    playerEvents.room = (e) => rooms?.push(e);
     pausedByPlayer = m.paused;
     if (m.started && phase === "gate") start();
   };
@@ -595,6 +616,9 @@ export async function play(): Promise<PlayHandle> {
   pausedByPlayer = player.paused;
   // A framed page (or the Stage overlay's own document) waits briefly for a Player's hello before drawing its own gate.
   if (linked && !byPlayer) await new Promise((r) => setTimeout(r, 300));
+  // A Play link to a room on a page no Player carries rooms for: the game hears why it is in none
+  // (og.RoomJoined, ok false); a Player's hello later joins it.
+  if (roomLink && !byPlayer) shell.setRooms(null, roomLink);
 
   // ── ready: reveal, then the gate ─────────────────────────────────────
   setProgress(1);

package/shell/platform.ts

@@ -24,16 +24,26 @@
 //   telemetry            an `event` named game.custom.<name>
 //   point                point.award { reason, amount } → { granted, balance }
 //   ai.mark              ai.mark { kind, label, model? } → { marked }
+//   rooms                room.create { name?, capacity? }, room.join { room, name? },
+//                        room.leave {}, room.send { to?, channel?, data? | bytes? }
+//                        (docs/platform-asks.md #16): a result only acknowledges
+//                        (a failed one becomes the engine's `error` event); every
+//                        room event arrives as a pushed `room` message in the
+//                        engine's own shape (joined, peer_joined, peer_left,
+//                        message, left), in order. A Player without room.join
+//                        carries no rooms: roomInfo's host is `none`.
 
 import { answerLocally, fail, localPlatform, type LocalDocument, type LocalPersistence, type PlatformAnswer, type PlatformCall, type PlatformHost } from "../src/platform-local.ts";
 export { storagePersistence } from "../src/platform-local.ts";
 import type { PlayerResult } from "./player.ts";
+import type { RoomHost } from "../src/web/shell.ts";
 
 /** The part of the Player link this needs (connectPlayer's answer). */
 export interface PlayerLink {
   readonly framed: boolean;
   readonly hosted: boolean;
   readonly capabilities: readonly string[];
+  readonly time?: number | undefined;
   request(method: string, args?: Record<string, unknown>): Promise<PlayerResult>;
   event(name: string, attrs?: Record<string, string | number | boolean | null>): void;
 }
@@ -160,6 +170,7 @@ export function playerPlatform(player: PlayerLink, local: LocalPersistence): Pla
   return {
     host: "player",
     capabilities,
+    time: player.time,
     handle(calls, answer) {
       // In order: a store write through the save reads it first, so calls never interleave.
       for (const call of calls) {
@@ -192,6 +203,9 @@ export function deferredPlatform(ready: Promise<PlatformHost>, capabilities: rea
   return {
     host: "player",
     capabilities,
+    get time() {
+      return real?.time;
+    },
     handle(calls, answer) {
       if (real) real.handle(calls, answer);
       else held.push([calls, answer]);
@@ -201,3 +215,40 @@ export function deferredPlatform(ready: Promise<PlatformHost>, capabilities: rea
 
 /** How long a framed page waits for a Player's hello before the browser's storage answers. */
 export const HELLO_WAIT_MS = 1500;
+
+/** The room ops the Player answers, by the engine's op name. */
+const ROOM_OPS: Record<string, string> = { create: "room.create", join: "room.join", leave: "room.leave", send: "room.send" };
+
+/**
+ * The Player's rooms (docs/platform-asks.md #16), or null for a Player that has none. Ops go
+ * to it in order without waiting (a send never waits for a join's answer: the Player queues
+ * them); `push` takes the events it pushes. A refused op becomes an `error` event naming it.
+ */
+export function playerRooms(player: PlayerLink): (RoomHost & { push(event: Record<string, unknown>): void }) | null {
+  if (!player.capabilities.includes("room.join")) return null;
+  let deliver: ((events: unknown[]) => void) | null = null;
+  return {
+    host: "player",
+    handle(ops, to) {
+      deliver = to;
+      for (const op of ops) {
+        const name = String(op["op"]);
+        const method = ROOM_OPS[name];
+        const { op: _op, ...args } = op;
+        if (!method || !player.capabilities.includes(method)) {
+          to([{ type: "error", op: name, code: "unavailable", message: `this Player answers no ${method ?? name}` }]);
+          continue;
+        }
+        void player.request(method, args).then(
+          (r) => {
+            if (!r.ok) deliver?.([{ type: "error", op: name, code: r.error.code, message: r.error.message }]);
+          },
+          (e: unknown) => deliver?.([{ type: "error", op: name, code: "offline", message: e instanceof Error ? e.message : String(e) }]),
+        );
+      }
+    },
+    push(event) {
+      deliver?.([event]);
+    },
+  };
+}

package/shell/player.ts

@@ -39,6 +39,8 @@ export interface PlayerEvents {
   gesture?(): void;
   pause?(): void;
   resume?(): void;
+  /** A room event the Player pushed (`kind: "room"`, docs/platform-asks.md #16): the engine's own shape. */
+  room?(event: Record<string, unknown>): void;
 }
 
 /** A short fingerprint of an error message: `[a-z0-9-]{1,64}` (FNV-1a of the first line, hex). */
@@ -57,9 +59,9 @@ export type PlayerResult =
   | { readonly ok: true; readonly data: unknown; readonly time?: number }
   | { readonly ok: false; readonly error: { readonly code: string; readonly message: string; readonly retryable: boolean; readonly status?: number; readonly revision?: number }; readonly time?: number };
 
-/** A message's `time` field, when it is a finite number. */
+/** A message's `time` field, when it is finite UTC milliseconds since the epoch. */
 export const timeOf = (m: Record<string, unknown>): { time?: number } =>
-  typeof m["time"] === "number" && Number.isFinite(m["time"]) ? { time: m["time"] } : {};
+  typeof m["time"] === "number" && Number.isFinite(m["time"]) && m["time"] >= 0 ? { time: m["time"] } : {};
 
 /** How long a call waits for its `result` before it fails with `timeout`. */
 export const CALL_TIMEOUT_MS = 15_000;
@@ -91,6 +93,7 @@ export function connectPlayer(events: PlayerEvents) {
   let started = false;
   let paused = false;
   let capabilities: readonly string[] = [];
+  let time: number | undefined;
   let nextCall = 1;
   const calls = new Map<string, (r: PlayerResult) => void>();
 
@@ -114,6 +117,7 @@ export function connectPlayer(events: PlayerEvents) {
         heard = true;
         if (m["started"] === true) started = true;
         paused = m["paused"] === true;
+        time = timeOf(m).time;
         capabilities = Array.isArray(m["capabilities"]) ? (m["capabilities"] as unknown[]).filter((c): c is string => typeof c === "string") : [];
         events.hello?.({ started: m["started"] === true, paused, capabilities });
         break;
@@ -156,6 +160,11 @@ export function connectPlayer(events: PlayerEvents) {
         paused = false;
         events.resume?.();
         break;
+      case "room": {
+        const event = m["event"];
+        if (event && typeof event === "object" && !Array.isArray(event)) events.room?.(event as Record<string, unknown>);
+        break;
+      }
     }
   };
   if (peer) addEventListener("message", onMessage);
@@ -189,6 +198,10 @@ export function connectPlayer(events: PlayerEvents) {
     get capabilities(): readonly string[] {
       return capabilities;
     },
+    /** The most recent hello's clock, before any calls have been answered. */
+    get time(): number | undefined {
+      return time;
+    },
     loading(value: number | null, label?: string) {
       if (readySent) return;
       if (value !== null) {

package/shell/transport.ts

@@ -139,6 +139,7 @@ export interface PageConnection {
   readonly started: boolean;
   readonly paused: boolean;
   readonly capabilities: readonly string[];
+  readonly time: number | undefined;
   readonly page: PageInfo | null;
   /** Resolves once the hello is answered (true) or failed (false). */
   readonly hello: Promise<boolean>;
@@ -249,6 +250,7 @@ export function connectPage(game: PageGame, env: TransportEnv, events: PlayerEve
   // ── hello ──
   let hosted = false;
   let capabilities: readonly string[] = [];
+  let time: number | undefined;
   let page: PageInfo | null = null;
   const str = (v: unknown) => (typeof v === "string" && v ? v : null);
   const hello = serial(async () => {
@@ -256,6 +258,7 @@ export function connectPage(game: PageGame, env: TransportEnv, events: PlayerEve
     const m = r.data;
     if (r.status !== 200 || !m || m["kind"] !== "hello") return false;
     hosted = true;
+    time = timeOf(m).time;
     capabilities = Array.isArray(m["capabilities"]) ? (m["capabilities"] as unknown[]).filter((c): c is string => typeof c === "string") : [];
     const p = (m["page"] ?? null) as Record<string, unknown> | null;
     page = p && typeof p === "object" ? { title: str(p["title"]), cover: str(p["cover"]), backdrop: str(p["backdrop"]), back: str(p["back"]), portal: str(p["portal"]) } : null;
@@ -446,6 +449,9 @@ export function connectPage(game: PageGame, env: TransportEnv, events: PlayerEve
     get capabilities() {
       return capabilities;
     },
+    get time() {
+      return time;
+    },
     get page() {
       return page;
     },

package/src/depth.ts

@@ -0,0 +1,71 @@
+// The depth wave's additions (IDL `render` geometry, lines, points and
+// raycast; `debug`): 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));
+
+// A typed array crosses the wire as a plain array (JSON.stringify writes
+// a Float32Array as an object keyed by index).
+const ATTRIBUTES = ["positions", "normals", "uvs", "colors", "tangents", "indices"] as const;
+function attributes(desc: unknown): string | undefined {
+  if (desc === undefined || desc === null || typeof desc !== "object") return json(desc);
+  const d: Record<string, unknown> = { ...(desc as Record<string, unknown>) };
+  for (const k of ATTRIBUTES) {
+    const v = d[k];
+    if (ArrayBuffer.isView(v)) d[k] = Array.from(v as unknown as ArrayLike<number>);
+  }
+  return JSON.stringify(d);
+}
+
+export const depthRender = Object.freeze({
+  bufferGeometry: (world: W, desc?: unknown) => parse(abi().og_render_buffer_geometry(world.id, attributes(desc))),
+  updateGeometry: (world: W, geometry: number, desc?: unknown) =>
+    parse(abi().og_render_update_geometry(world.id, geometry, attributes(desc))),
+  geometryInfo: (world: W, geometry: number) => parse(abi().og_render_geometry_info(world.id, geometry)),
+  cylinderGeometry: (world: W, desc?: unknown) => parse(abi().og_render_cylinder_geometry(world.id, json(desc))),
+  coneGeometry: (world: W, desc?: unknown) => parse(abi().og_render_cone_geometry(world.id, json(desc))),
+  capsuleGeometry: (world: W, desc?: unknown) => parse(abi().og_render_capsule_geometry(world.id, json(desc))),
+  torusGeometry: (world: W, desc?: unknown) => parse(abi().og_render_torus_geometry(world.id, json(desc))),
+  ringGeometry: (world: W, desc?: unknown) => parse(abi().og_render_ring_geometry(world.id, json(desc))),
+  circleGeometry: (world: W, desc?: unknown) => parse(abi().og_render_circle_geometry(world.id, json(desc))),
+  tubeGeometry: (world: W, desc?: unknown) => parse(abi().og_render_tube_geometry(world.id, json(desc))),
+  lines: (world: W, desc?: unknown) => parse(abi().og_render_lines(world.id, json(desc))),
+  points: (world: W, desc?: unknown) => parse(abi().og_render_points(world.id, json(desc))),
+  raycast: (world: W, ray: unknown, desc?: unknown) => parse(abi().og_render_raycast(world.id, JSON.stringify(ray), json(desc))),
+});
+
+export const debug = Object.freeze({
+  line: (world: W, from: unknown, to: unknown, desc?: unknown) =>
+    abi().og_debug_line(world.id, JSON.stringify(from), JSON.stringify(to), json(desc)),
+  box: (world: W, center: unknown, size: unknown, desc?: unknown) =>
+    abi().og_debug_box(world.id, JSON.stringify(center), JSON.stringify(size), json(desc)),
+  sphere: (world: W, center: unknown, radius: number, desc?: unknown) =>
+    abi().og_debug_sphere(world.id, JSON.stringify(center), radius, json(desc)),
+  arrow: (world: W, from: unknown, to: unknown, desc?: unknown) =>
+    abi().og_debug_arrow(world.id, JSON.stringify(from), JSON.stringify(to), json(desc)),
+  axes: (world: W, position: unknown, size: number, desc?: unknown) =>
+    abi().og_debug_axes(world.id, JSON.stringify(position), size, json(desc)),
+  text: (world: W, position: unknown, text: string, desc?: unknown) =>
+    abi().og_debug_text(world.id, JSON.stringify(position), text, json(desc)),
+  clear: (world: W) => abi().og_debug_clear(world.id),
+  setView: (world: W, view: string) => abi().og_debug_set_view(world.id, JSON.stringify(view)),
+  // A publish build answers every debug member with a refusal: the view is none there.
+  view: (world: W) => {
+    const v = parse<unknown>(abi().og_debug_view(world.id));
+    return typeof v === "string" ? v : "none";
+  },
+  setEnabled: (world: W, enabled: boolean) => abi().og_debug_set_enabled(world.id, enabled),
+  enabled: (world: W) => abi().og_debug_enabled(world.id),
+});

package/src/e6.ts

@@ -1,4 +1,4 @@
-// The E6 modules' namespaces (IDL `nav`, `ai`, `platform`, `i18n`): thin calls into the host's
+// The E6 modules' namespaces (IDL `nav`, `ai`, `platform`, `i18n`) and the depth wave's `net`: thin calls into the host's
 // binding symbols, typed by the generated declarations through index.ts.
 
 import type { HostAbi } from "./generated/abi.ts";
@@ -58,8 +58,39 @@ export const platform = Object.freeze({
   result: (world: W, request: number) => parse(abi().og_platform_result(world.id, request)),
   info: (world: W) => parse(abi().og_platform_info(world.id)),
   now: (world: W) => abi().og_platform_now(world.id),
+  roomCreate: (world: W, desc?: unknown) => parse(abi().og_platform_room_create(world.id, json(desc))),
+  roomJoin: (world: W, room: string) => parse(abi().og_platform_room_join(world.id, room)),
+  roomLeave: (world: W) => parse(abi().og_platform_room_leave(world.id)),
+  // Bytes cross as { "$og.bytes": base64 } (og-runtime net.rs BYTES_KEY).
+  roomSend: (world: W, data: unknown, to?: number) =>
+    parse(abi().og_platform_room_send(world.id, JSON.stringify(data instanceof Uint8Array ? { "$og.bytes": toBase64(data) } : (data ?? null)), to)),
+  roomPeers: (world: W) => parse(abi().og_platform_room_peers(world.id)),
+  roomInfo: (world: W) => parse(abi().og_platform_room_info(world.id)),
+  roomMessage: (world: W, message: number) => {
+    const m = parse<{ bytes: string | null } | null>(abi().og_platform_room_message(world.id, message));
+    return m && { ...m, bytes: typeof m.bytes === "string" ? fromBase64(m.bytes) : null };
+  },
 });
 
+export const net = Object.freeze({
+  submit: (world: W, input?: unknown) => parse(abi().og_net_submit(world.id, json(input))),
+  status: (world: W) => parse(abi().og_net_status(world.id)),
+  hash: (world: W) => parse<string>(abi().og_net_hash(world.id)),
+});
+
+function toBase64(bytes: Uint8Array): string {
+  let bin = "";
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]!);
+  return btoa(bin);
+}
+
+function fromBase64(text: string): Uint8Array {
+  const bin = atob(text);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
 export const i18n = Object.freeze({
   load: (world: W, path: string) => parse(abi().og_i18n_load(world.id, path)),
   setLocale: (world: W, locale: string) => parse(abi().og_i18n_set_locale(world.id, locale)),

package/src/env.d.ts

@@ -22,6 +22,7 @@ declare module "node:fs" {
   export function readFileSync(path: string): Uint8Array;
   export function readFileSync(path: string, encoding: string): string;
   export function writeFileSync(path: string, data: string | Uint8Array): void;
+  export function writeSync(fd: number, data: Uint8Array, offset?: number, length?: number): number;
   export function rmSync(path: string, options?: { recursive?: boolean; force?: boolean }): void;
   export function mkdirSync(path: string, options?: { recursive?: boolean }): void;
   export function copyFileSync(from: string, to: string): void;
@@ -51,6 +52,8 @@ declare module "bun:test" {
   export namespace test {
     /** The test runs unless `condition` holds (then it is reported skipped). */
     function skipIf(condition: boolean): (name: string, body: Body, timeout?: number) => void;
+    /** One test per row, the row spread into the body (`%s` in the name is the row's first value). */
+    function each<T extends readonly unknown[]>(rows: readonly T[]): (name: string, body: (...row: [...T]) => unknown, timeout?: number) => void;
   }
   export function describe(name: string, body: () => void): void;
   export function beforeAll(body: Body): void;
@@ -73,7 +76,8 @@ declare module "bun:test" {
     toThrow(pattern?: RegExp | string): void;
     not: Matchers;
   }
-  export function expect(value: unknown): Matchers;
+  /** `message` names the assertion in its failure (bun's custom failure message). */
+  export function expect(value: unknown, message?: string): Matchers;
 }
 
 declare const process: {