@origingame/engine 0.0.0-stage → 0.1.0

package/src/p2.ts

@@ -0,0 +1,35 @@
+// The phase 2 modules' namespaces (IDL `terrain`): 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 terrain = Object.freeze({
+  load: (world: W, path: string) => parse(abi().og_terrain_load(world.id, path)),
+  sample: (world: W, desc?: unknown) => parse(abi().og_terrain_sample(world.id, json(desc))),
+  bounds: (world: W, data: number, origin?: unknown, quaternion?: unknown, scale?: unknown) =>
+    parse(abi().og_terrain_bounds(world.id, data, json(origin), json(quaternion), json(scale))),
+  edit: (world: W, data: number, brush?: unknown) => parse(abi().og_terrain_edit(world.id, data, json(brush))),
+  layer: (world: W, data: number, index: number) => parse(abi().og_terrain_layer(world.id, data, index)),
+  setLayer: (world: W, data: number, index: number, layer?: unknown) =>
+    parse(abi().og_terrain_set_layer(world.id, data, index, json(layer))),
+});
+
+export const stream = Object.freeze({
+  status: (world: W, group: string) => parse(abi().og_stream_status(world.id, group)),
+  request: (world: W, group: string) => parse(abi().og_stream_request(world.id, group)),
+  release: (world: W, group: string) => parse(abi().og_stream_release(world.id, group)),
+  budget: (world: W) => parse(abi().og_stream_budget(world.id)),
+  setBudget: (world: W, bytes: number) => parse(abi().og_stream_set_budget(world.id, bytes)),
+});

package/src/platform-local.ts

@@ -0,0 +1,211 @@
+// The local platform: og.platform's calls answered from a JSON document the
+// host keeps (the native host's file, the browser's own storage). It is the
+// native host's platform and the web shell's fallback when no Player
+// answers. Store keys carry revisions and refuse a stale write with
+// `conflict`; leaderboards keep each name's best and rank in the board's
+// order; Origin Point and AI marks are recorded (a local balance, a list),
+// never sent anywhere; telemetry is kept as the last 200 events.
+
+/** One platform call, as og_platform_take lists it. */
+export interface PlatformCall {
+  readonly request: number;
+  readonly method: string;
+  readonly args: Record<string, unknown>;
+  readonly tick: number;
+}
+
+/** An answer, as og_platform_answer takes it. */
+export type PlatformAnswer = (
+  | { readonly ok: true; readonly data: unknown }
+  | { readonly ok: false; readonly error: { readonly code: string; readonly message: string; readonly retryable: boolean; readonly revision?: number } }
+) & {
+  /** The answering host's clock, UTC ms (a Player that sends its time); the engine's host clock fills it in otherwise. */
+  readonly time?: number;
+};
+
+/** What answers an engine's platform calls. */
+export interface PlatformHost {
+  /** `player`, `local` or `none` (og.platform.info). */
+  readonly host: string;
+  readonly capabilities: readonly string[];
+  /** Handle calls in order; answer every one but `telemetry`, now or later. */
+  handle(calls: readonly PlatformCall[], answer: (request: number, result: PlatformAnswer) => void): void;
+}
+
+/** Every method the local platform answers. */
+export const LOCAL_CAPABILITIES = ["store.get", "store.set", "store.list", "leaderboard.submit", "leaderboard.top", "leaderboard.around", "telemetry", "point", "ai.mark"] as const;
+
+export interface LocalDocument {
+  version: 1;
+  player: string;
+  store: Record<string, { value: unknown; revision: number }>;
+  boards: Record<string, { order: "asc" | "desc"; entries: Array<{ name: string; score: number }> }>;
+  points: { balance: number; grants: Array<{ reason: string; amount: number; tick: number }> };
+  marks: Array<{ kind: string; label: string; model?: string; tick: number }>;
+  events: Array<{ name: string; attrs: Record<string, unknown>; tick: number }>;
+}
+
+/** Where the document lives: a file natively, localStorage in a browser, memory in tests. */
+export interface LocalPersistence {
+  load(): string | null;
+  save(text: string): void;
+}
+
+export function emptyDocument(player = "You"): LocalDocument {
+  return { version: 1, player, store: {}, boards: {}, points: { balance: 0, grants: [] }, marks: [], events: [] };
+}
+
+function readDocument(text: string | null): LocalDocument {
+  if (!text) return emptyDocument();
+  try {
+    const d = JSON.parse(text) as Partial<LocalDocument>;
+    const e = emptyDocument(typeof d.player === "string" ? d.player : "You");
+    return { ...e, ...d, points: { ...e.points, ...(d.points ?? {}) }, version: 1 } as LocalDocument;
+  } catch {
+    return emptyDocument();
+  }
+}
+
+export const fail = (code: string, message: string): PlatformAnswer => ({
+  ok: false,
+  error: { code, message, retryable: ["offline", "timeout", "unavailable", "rate_limited"].includes(code) },
+});
+
+const okData = (data: unknown): PlatformAnswer => ({ ok: true, data });
+
+/** A refused conditional write: `conflict`, with the revision the key is at now. */
+export const conflict = (message: string, revision: number): PlatformAnswer => ({ ok: false, error: { code: "conflict", message, retryable: false, revision } });
+
+/** Ranked entries of a board, best first. */
+export function ranked(order: "asc" | "desc", entries: ReadonlyArray<{ name: string; score: number }>, me: string) {
+  const sorted = [...entries].sort((a, b) => (order === "asc" ? a.score - b.score : b.score - a.score) || (a.name < b.name ? -1 : 1));
+  return sorted.map((e, i) => ({ rank: i + 1, name: e.name, score: e.score, me: e.name === me }));
+}
+
+/** Answers one call against the document (mutating it). */
+export function answerLocally(doc: LocalDocument, call: PlatformCall): PlatformAnswer | null {
+  const a = call.args;
+  switch (call.method) {
+    case "store.get": {
+      const key = String(a["key"]);
+      const slot = doc.store[key];
+      return okData({ key, value: slot?.value ?? null, revision: slot?.revision ?? 0 });
+    }
+    case "store.set": {
+      const key = String(a["key"]);
+      const want = Number(a["revision"] ?? 0);
+      const slot = doc.store[key];
+      const have = slot?.revision ?? 0;
+      // `create`: only a key never written (the Player's revision 0).
+      if (a["create"] === true ? have !== 0 : want > 0 && want !== have) return conflict(`'${key}' is at revision ${have}${a["create"] === true ? ", not new" : `, not ${want}`}: read it again and merge`, have);
+      doc.store[key] = { value: a["value"] ?? null, revision: have + 1 };
+      return okData({ key, revision: have + 1 });
+    }
+    case "store.list":
+      return okData({ keys: Object.keys(doc.store).sort().map((key) => ({ key, revision: doc.store[key]!.revision })) });
+    case "leaderboard.submit": {
+      const name = String(a["board"] ?? "main");
+      const board = (doc.boards[name] ??= { order: a["order"] === "asc" ? "asc" : "desc", entries: [] });
+      const score = Number(a["score"]);
+      const mine = board.entries.find((e) => e.name === doc.player);
+      const better = (x: number, y: number) => (board.order === "asc" ? x < y : x > y);
+      if (!mine) board.entries.push({ name: doc.player, score });
+      else if (better(score, mine.score)) mine.score = score;
+      const me = ranked(board.order, board.entries, doc.player).find((e) => e.me)!;
+      return okData({ board: name, rank: me.rank, best: me.score });
+    }
+    case "leaderboard.top":
+    case "leaderboard.around": {
+      const name = String(a["board"] ?? "main");
+      const board = doc.boards[name];
+      const count = Math.max(1, Math.min(100, Number(a["count"] ?? 10)));
+      const all = board ? ranked(board.order, board.entries, doc.player) : [];
+      const me = all.find((e) => e.me) ?? null;
+      let entries = all.slice(0, count);
+      if (call.method === "leaderboard.around" && me) {
+        const start = Math.max(0, Math.min(all.length - count, me.rank - 1 - Math.floor(count / 2)));
+        entries = all.slice(start, start + count);
+      }
+      return okData({ board: name, order: board?.order ?? "desc", entries, me });
+    }
+    case "telemetry":
+      doc.events.push({ name: String(a["name"]), attrs: (a["attrs"] as Record<string, unknown>) ?? {}, tick: call.tick });
+      if (doc.events.length > 200) doc.events.splice(0, doc.events.length - 200);
+      return null;
+    case "point": {
+      const amount = Math.max(1, Math.min(1000, Number(a["amount"] ?? 1)));
+      doc.points.balance += amount;
+      doc.points.grants.push({ reason: String(a["reason"]), amount, tick: call.tick });
+      return okData({ granted: amount, balance: doc.points.balance });
+    }
+    case "ai.mark":
+      doc.marks.push({ kind: String(a["kind"]), label: String(a["label"]), ...(typeof a["model"] === "string" ? { model: a["model"] } : {}), tick: call.tick });
+      return okData({ marked: true });
+    default:
+      return fail("invalid", `unknown platform method '${call.method}'`);
+  }
+}
+
+/** The local platform over a persistence: every call answered at once, the document saved after each batch. */
+export function localPlatform(persistence: LocalPersistence = memoryPersistence()): PlatformHost & { document(): LocalDocument } {
+  let doc = readDocument(persistence.load());
+  return {
+    host: "local",
+    capabilities: LOCAL_CAPABILITIES,
+    document: () => doc,
+    handle(calls, answer) {
+      doc = readDocument(persistence.load());
+      const answers: Array<[number, PlatformAnswer]> = [];
+      for (const c of calls) {
+        const r = answerLocally(doc, c);
+        if (r) answers.push([c.request, r]);
+      }
+      persistence.save(JSON.stringify(doc, null, 2));
+      for (const [request, r] of answers) answer(request, r);
+    },
+  };
+}
+
+/** A document kept in memory only. */
+export function memoryPersistence(initial: LocalDocument | null = null): LocalPersistence {
+  let text: string | null = initial ? JSON.stringify(initial) : null;
+  return { load: () => text, save: (t) => void (text = t) };
+}
+
+/** No platform at all: every call is `unavailable`. */
+export const noPlatform: PlatformHost = {
+  host: "none",
+  capabilities: [],
+  handle(calls, answer) {
+    for (const c of calls) if (c.method !== "telemetry") answer(c.request, fail("unavailable", "no platform host is attached to this engine (the shell attaches the Player or local storage; og run a local store)"));
+  },
+};
+
+/** The document in the browser's localStorage under `key` (memory only where storage is refused). */
+export function storagePersistence(key: string): LocalPersistence {
+  const store = (() => {
+    try {
+      return (globalThis as { localStorage?: { getItem(k: string): string | null; setItem(k: string, v: string): void } }).localStorage ?? null;
+    } catch {
+      return null;
+    }
+  })();
+  let memory: string | null = null;
+  return {
+    load: () => {
+      try {
+        return store ? store.getItem(key) : memory;
+      } catch {
+        return memory;
+      }
+    },
+    save: (text) => {
+      memory = text;
+      try {
+        store?.setItem(key, text);
+      } catch {
+        /* storage full or refused: memory keeps it for this page */
+      }
+    },
+  };
+}

package/src/playtest.ts

@@ -0,0 +1,131 @@
+// Playtest scripts (`tests/*.og.ts`): a command script run headless through
+// `og run --commands`, then checks over what the run wrote. `og test` runs
+// every one in its own process and fails a playtest that made no check.
+//
+// Without a renderer (the platform's engine and probe sandboxes carry none;
+// `OG_RENDERER=none` makes any machine so) the run is the same run, but a
+// `screenshot` writes no PNG: the checks that read a frame go inside
+// `t.frame(files, () => ...)`, which runs them with a renderer and otherwise
+// reports each file "no renderer, frame unchecked" and passes. Frames are
+// verified where there is a renderer: the author's machine, the
+// browser-check sandbox, an executor with a GPU.
+//
+//   import { playtest } from "@origingame/engine/playtest";
+//   export default playtest({
+//     name: "the trickster spins after S",
+//     commands: "0.5:type:s;2.0:screenshot:spin.png;2.2:dump_entity:trickster:t.json;2.5:quit",
+//     check(run, t) {
+//       t.ok(run.quit, "the script reached quit");
+//       t.ok(run.json<{ components: Record<string, { speed: number }> }>("t.json").components.Spin!.speed > 0, "Spin started");
+//       t.frame("spin.png", () => t.equal(run.png("spin.png").width, 1280, "the frame is 1280 wide"));
+//     },
+//   });
+
+/** What one headless run produced. */
+export interface PlaytestRun {
+  /** The tick the run ended on. */
+  readonly tick: number;
+  /** The world hash at the end, hex. */
+  readonly hash: string;
+  /** The end hash of every run (`PlaytestDesc.runs`), the first being `hash`: equal hashes are a replay that matched. */
+  readonly hashes: readonly string[];
+  readonly entities: number;
+  /** Whether a `quit` step ran. */
+  readonly quit: boolean;
+  /** The renderer tier (`metal`, `vulkan`, `webgpu`, ..., `none` without a renderer). */
+  readonly tier: string;
+  /** Whether the run had a renderer: without one (`tier` `none`) a `screenshot` writes no PNG. */
+  readonly rendered: boolean;
+  /** The screenshots the run took without a renderer, by the file each would have written: frames unchecked. */
+  readonly unchecked: readonly string[];
+  /** Every file the commands wrote, by its `Output::file_name()` (`smoke.png`, `dump_world-000132.json`). */
+  readonly files: readonly string[];
+  /** Warnings the command channel and the probe logged, each naming the fix. */
+  readonly warnings: readonly string[];
+  /** A written JSON output, parsed. Throws when the run wrote no such file. */
+  json<T = unknown>(file: string): T;
+  /** A written PNG's size. Throws when the run wrote no such file (and, for a screenshot taken without a renderer, a FrameUnchecked: read frames inside `t.frame`). */
+  png(file: string): { width: number; height: number; bytes: number };
+  /** A written text output. */
+  text(file: string): string;
+  /** A written WAV (`listen`): its rate, frames, peak and RMS (16-bit PCM read back, both channels). */
+  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[];
+}
+
+/** The checks a playtest makes; a playtest that made none fails. */
+export interface PlaytestChecks {
+  ok(condition: unknown, what: string): void;
+  equal<T>(actual: T, expected: T, what: string): void;
+  near(actual: number, expected: number, tolerance: number, what: string): void;
+  /**
+   * The checks that read frames (`run.png`, a decoded screenshot, a comparison with
+   * references/): `check` runs when the playtest had a renderer. Without one it does not run,
+   * each of `files` is reported "no renderer, frame unchecked", and the playtest passes on its
+   * other checks. Every check outside `t.frame` runs either way.
+   */
+  frame(files: string | readonly string[], check: () => void): void;
+}
+
+/**
+ * What reading a screenshot the run took without a renderer throws. A check function stopped by
+ * one passes with its frame unchecked (the checks after it did not run, and the report says so):
+ * put frame checks inside `t.frame` so every other check runs.
+ */
+export class FrameUnchecked extends Error {
+  readonly file: string;
+  constructor(file: string) {
+    super(`${file}: no renderer, frame unchecked`);
+    this.name = "FrameUnchecked";
+    this.file = file;
+  }
+}
+
+export interface PlaytestDesc {
+  /** One line on what the playtest proves. */
+  readonly name: string;
+  /** `t:action[:args];...`, as `og run --commands`. End it with `quit`. */
+  readonly commands: string;
+  /** The replay seed; omitted is GameDesc.seed. */
+  readonly seed?: number;
+  /** The render target, `WIDTHxHEIGHT` (default 1280x720). */
+  readonly size?: 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;
+  /**
+   * The host's clock at tick 0, UTC milliseconds (`og run --clock`): og.platform.now and the
+   * answers' times start there and move with the ticks, so a playtest is reproducible.
+   * Omitted is 1767225600000 (2026-01-01T00:00:00Z).
+   */
+  readonly clock?: number;
+  /**
+   * `keep`: every process of this playtest (the script, its `runs` and its `then` steps)
+   * answers og.platform from one local store, `<out>/.store/platform.json` (a dot name, which no step's output may take), empty when the playtest
+   * starts, so a later process sees what an earlier one saved (a relaunch). Omitted: each
+   * 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`. */
+  readonly then?: readonly PlaytestStep[];
+  readonly check: (run: PlaytestRun, t: PlaytestChecks) => void | Promise<void>;
+}
+
+/** A later process of a playtest (`PlaytestDesc.then`). */
+export interface PlaytestStep {
+  /** Its own script, as PlaytestDesc.commands. */
+  readonly commands: string;
+  /** Its clock at its tick 0, UTC ms; omitted is the playtest's clock. */
+  readonly clock?: number;
+}
+
+/** The clock a playtest's processes start at when it names none: 2026-01-01T00:00:00Z. */
+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");
+  }
+  return Object.freeze({ ...desc });
+}