@origingame/create-game 0.0.0-stage → 0.1.0

package/archetypes/runner/tests/frames.og.ts

@@ -0,0 +1,37 @@
+// The look, frame by frame: the title over the scrolling city, a coin's
+// pickup mid-run ("+10" rising from the popping coin, dust at the feet) and
+// the crash's hit stop (the courier flashing red on the crate, the view
+// shaking). Each is compared with references/<tier>/frames-<file> under
+// og-tests' tolerance (tests/frames.ts); `OG_FX_CAPTURE=1 og test .` records
+// them. The script has no dice in it: patterns are off, the coin and the
+// crate are placed.
+import { playtest } from "@origingame/engine/playtest";
+import { checkFrames } from "./frames.ts";
+import { OVER, RUNNING, runOf, tap } from "./lib.ts";
+
+const FILES = ["title.png", "coin.png", "crash.png"] as const;
+
+export default playtest({
+  name: "reference frames: title, a coin's pickup, the crash",
+  commands: [
+    "0.1:set:runner.Tuning.spawnInterval=60",
+    "0.3:screenshot:title.png",
+    tap(0.5),
+    "1.0:place:coin:-2",
+    "1.6:screenshot:coin.png",
+    "1.6:dump_entity:runner:coin.json",
+    "2.0:place:crate:1",
+    // The crate reaches the runner in tick 173; 2.95 s is three ticks into the eight-tick hit stop.
+    "2.95:screenshot:crash.png",
+    "2.95:dump_entity:runner:crash.json",
+    "3.0:quit",
+  ].join(";"),
+  check(run, t) {
+    t.equal(run.warnings.join("; "), "", "the script ran without warnings");
+    const coin = runOf(run, "coin.json");
+    t.ok(coin.phase === RUNNING && coin.coins === 1, "the coin frame is mid-run, just after the pickup");
+    const crash = runOf(run, "crash.json");
+    t.ok(crash.phase === OVER && crash.phaseTicks < 8, `the crash frame is inside the hit stop (${crash.phaseTicks} ticks after)`);
+    checkFrames(run, t, FILES, "frames-");
+  },
+});

package/archetypes/runner/tests/frames.ts

@@ -0,0 +1,134 @@
+// The reference-frame check: decode the PNGs a run wrote and compare them
+// with references/<tier>/ under og-tests' tolerance (a channel off by more
+// than 32/255 is an outlier; fail above 0.5 % outliers or an RGB RMSE above
+// 0.01). A tier without its own references compares with `metal` and says
+// so. `OG_FX_CAPTURE=1 og test .` records this tier's references instead.
+// (Copied from templates/fx-showcase/tests/frames.ts, so the archetype stands alone.)
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { inflateSync } from "node:zlib";
+import type { PlaytestChecks, PlaytestRun } from "@origingame/engine/playtest";
+
+export interface Image {
+  width: number;
+  height: number;
+  /** RGBA8 rows. */
+  rgba: Uint8Array;
+}
+
+/** An 8-bit RGB or RGBA, non-interlaced PNG, unfiltered. */
+export function decodePng(bytes: Uint8Array): Image {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let at = 8;
+  let width = 0;
+  let height = 0;
+  let channels = 4;
+  const idat: Uint8Array[] = [];
+  while (at < bytes.length) {
+    const len = view.getUint32(at);
+    const type = String.fromCharCode(...bytes.subarray(at + 4, at + 8));
+    const data = bytes.subarray(at + 8, at + 8 + len);
+    if (type === "IHDR") {
+      width = view.getUint32(at + 8);
+      height = view.getUint32(at + 12);
+      const depth = data[8]!;
+      const color = data[9]!;
+      if (depth !== 8 || (color !== 6 && color !== 2) || data[12] !== 0) throw new Error(`unsupported PNG (depth ${depth}, colour ${color}, interlace ${data[12]})`);
+      channels = color === 6 ? 4 : 3;
+    } else if (type === "IDAT") idat.push(data);
+    else if (type === "IEND") break;
+    at += 12 + len;
+  }
+  const raw = inflateSync(Buffer.concat(idat));
+  const stride = width * channels;
+  const out = new Uint8Array(width * height * 4);
+  const prev = new Uint8Array(stride);
+  const cur = new Uint8Array(stride);
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (stride + 1)]!;
+    const line = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1));
+    for (let i = 0; i < stride; i++) {
+      const a = i >= channels ? cur[i - channels]! : 0;
+      const b = prev[i]!;
+      const c = i >= channels ? prev[i - channels]! : 0;
+      let v = line[i]!;
+      if (filter === 1) v += a;
+      else if (filter === 2) v += b;
+      else if (filter === 3) v += (a + b) >> 1;
+      else if (filter === 4) {
+        const p = a + b - c;
+        const pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+        v += pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+      }
+      cur[i] = v & 255;
+    }
+    for (let x = 0; x < width; x++) {
+      for (let k = 0; k < 4; k++) out[(y * width + x) * 4 + k] = k < channels ? cur[x * channels + k]! : 255;
+    }
+    prev.set(cur);
+  }
+  return { width, height, rgba: out };
+}
+
+/** og-tests' rule: outlier fraction and RGB RMSE between two equal-size frames. */
+export function difference(a: Image, b: Image): { outliers: number; rmse: number } {
+  if (a.width !== b.width || a.height !== b.height) return { outliers: 1, rmse: 1 };
+  let outliers = 0;
+  let sum = 0;
+  const n = a.width * a.height;
+  for (let p = 0; p < n; p++) {
+    let out = false;
+    for (let k = 0; k < 3; k++) {
+      const d = Math.abs(a.rgba[p * 4 + k]! - b.rgba[p * 4 + k]!);
+      if (d > 32) out = true;
+      const f = d / 255;
+      sum += f * f;
+    }
+    if (out) outliers++;
+  }
+  return { outliers: outliers / n, rmse: Math.sqrt(sum / (n * 3)) };
+}
+
+/** The playtest's output directory (the bundled playtest runs from it). */
+export function outDir(): string {
+  return dirname(fileURLToPath(import.meta.url));
+}
+
+/** The project's references/, from its og-out/test/<name>/. */
+export function referencesDir(): string {
+  return resolve(outDir(), "..", "..", "..", "references");
+}
+
+/** Compares each screenshot with its reference (`<prefix><file>`), or records it. */
+export function checkFrames(run: PlaytestRun, t: PlaytestChecks, files: readonly string[], prefix: string): void {
+  // Read only where there is a renderer: without one (tier `none`) each frame is
+  // reported "no renderer, frame unchecked" and every other check still runs.
+  t.frame(files, () => {
+    const refs = referencesDir();
+    t.ok(existsSync(refs) || process.env.OG_FX_CAPTURE !== undefined, `the references directory exists at ${refs}`);
+    const own = join(refs, run.tier);
+    const capture = process.env.OG_FX_CAPTURE !== undefined;
+    for (const f of files) {
+      const actual = join(outDir(), f);
+      // Each file on its own: this tier's reference where it has one, metal's otherwise.
+      const mine = join(own, prefix + f);
+      const ref = capture || existsSync(mine) ? mine : join(refs, "metal", prefix + f);
+      if (ref !== mine) process.stdout.write(`  note: no ${run.tier} reference for ${prefix}${f}; comparing with metal\n`);
+      if (capture) {
+        mkdirSync(own, { recursive: true });
+        copyFileSync(actual, ref);
+        t.ok(true, `recorded ${ref}`);
+        continue;
+      }
+      if (!existsSync(ref)) {
+        t.ok(false, `${ref} is missing: record it with OG_FX_CAPTURE=1 og test .`);
+        continue;
+      }
+      const d = difference(decodePng(readFileSync(actual)), decodePng(readFileSync(ref)));
+      process.stdout.write(`  ${f}: ${(d.outliers * 100).toFixed(3)} % outliers, RMSE ${d.rmse.toFixed(5)} against ${ref}\n`);
+      t.ok(d.outliers <= 0.005 && d.rmse <= 0.01, `${f} matches ${prefix}${f}: ${(d.outliers * 100).toFixed(3)} % outliers (≤ 0.5 %), RMSE ${d.rmse.toFixed(5)} (≤ 0.01)`);
+    }
+  });
+}

package/archetypes/runner/tests/jump.og.ts

@@ -0,0 +1,44 @@
+// Jumps: at a steady 6 m/s an obstacle placed at x=1 reaches the runner
+// (x=-5) one second later. A held press (a full jump, 1.9 m) clears a crate
+// and a fence; a tap (the 6-tick hop, 1.1 m) clears a crate but not a fence.
+import { playtest } from "@origingame/engine/playtest";
+import { OVER, RUNNING, positionOf, runOf, tap } from "./lib.ts";
+
+export default playtest({
+  name: "a full jump clears a crate and a fence; a hop clears a crate, not a fence",
+  commands: [
+    "0.1:set:runner.Tuning.spawnInterval=60",
+    "0.1:set:runner.Tuning.speedRamp=0",
+    tap(0.5),
+    // Crate 1 at t=1: arrives at t=2. Hold Space from 1.65 to 2.15: a full jump.
+    "1.0:place:crate:1",
+    "1.65:key_down:Space",
+    "1.9:dump_entity:runner:airborne.json",
+    "1.9:screenshot:jump.png",
+    "2.15:key_up:Space",
+    "2.6:dump_entity:runner:after-full.json",
+    // Crate 2 at t=3 arrives at t=4: a tap 12 ticks before is a hop over it.
+    "3.0:place:crate:1",
+    tap(3.8),
+    "4.6:dump_entity:runner:after-hop.json",
+    // Fence 1 at t=5: a full jump 18 ticks before its arrival clears it.
+    "5.0:place:fence:1",
+    "5.7:key_down:Space",
+    "6.2:key_up:Space",
+    "6.6:dump_entity:runner:after-fence.json",
+    // Fence 2 at t=7: a tap at the same moment as that full jump is a hop, too low for it.
+    "7.0:place:fence:1",
+    tap(7.7),
+    "8.6:dump_entity:runner:after-hop-fence.json",
+    "8.7:quit",
+  ].join(";"),
+  check(run, t) {
+    t.equal(run.warnings.join("; "), "", "the script ran without warnings");
+    const air = positionOf(run, "airborne.json");
+    t.ok(air.y > 1, `the held jump is high over the crate (feet at ${air.y.toFixed(2)} m)`);
+    t.equal(runOf(run, "after-full.json").phase, RUNNING, "the full jump cleared crate 1");
+    t.equal(runOf(run, "after-hop.json").phase, RUNNING, "the hop cleared crate 2");
+    t.equal(runOf(run, "after-fence.json").phase, RUNNING, "the full jump cleared fence 1");
+    t.equal(runOf(run, "after-hop-fence.json").phase, OVER, "the hop did not clear fence 2");
+  },
+});

package/archetypes/runner/tests/lib.ts

@@ -0,0 +1,42 @@
+// Shared readers for the runner's playtests: the runner row's components as
+// `dump_entity:runner:<file>` writes them.
+import type { PlaytestRun } from "@origingame/engine/playtest";
+
+export interface RunDump {
+  phase: number;
+  phaseTicks: number;
+  speed: number;
+  distance: number;
+  coins: number;
+  score: number;
+  best: number;
+  rounds: number;
+  grounded: boolean | number;
+}
+
+interface EntityDump {
+  components: Record<string, Record<string, unknown>>;
+}
+
+/** The runner's Run component from a dump_entity file. */
+export function runOf(run: PlaytestRun, file: string): RunDump {
+  const dump = run.json<EntityDump>(file);
+  const r = dump.components["Run"];
+  if (!r) throw new Error(`${file} has no Run component: ${Object.keys(dump.components).join(", ")}`);
+  return r as unknown as RunDump;
+}
+
+/** The runner's position (its feet; the hit box is centred 0.8125 m above) from a dump_entity file. */
+export function positionOf(run: PlaytestRun, file: string): { x: number; y: number } {
+  const dump = run.json<EntityDump>(file);
+  const t = (dump.components["og.Transform"] ?? dump.components["Transform"]) as { position: [number, number, number] } | undefined;
+  if (!t) throw new Error(`${file} has no Transform`);
+  return { x: t.position[0], y: t.position[1] };
+}
+
+export const TITLE = 0;
+export const RUNNING = 1;
+export const OVER = 2;
+
+/** A press of Space at t seconds (down, then up two ticks later): a tap, which is a hop. */
+export const tap = (t: number) => `${t}:key_down:Space;${(t + 0.034).toFixed(3)}:key_up:Space`;

package/archetypes/runner/tests/records.og.ts

@@ -0,0 +1,43 @@
+// The runner on og.platform (here the native host's local store, in
+// memory for each run): the first tick asks the store for the best score,
+// a crash submits the score to the `main` board, files a `round.over`
+// event and, being a new best, saves it; `dump_platform` shows each call,
+// its tick and its answer.
+import { playtest } from "@origingame/engine/playtest";
+import { OVER, runOf, tap } from "./lib.ts";
+
+interface PlatformDump {
+  host: string;
+  calls: Array<{ method: string; args: Record<string, unknown>; tick: number; state: string; result?: { ok: boolean; data: Record<string, unknown> } }>;
+}
+
+export default playtest({
+  name: "the best score is read from the store, and a crash submits the score and saves the new best",
+  commands: [
+    tap(0.5),
+    "0.6:set:runner.Tuning.spawnInterval=60",
+    "2.2:place:crate:3",
+    "3.6:dump_entity:runner:over.json",
+    "3.7:dump_platform:platform.json",
+    "3.8:quit",
+  ].join(";"),
+  check(run, t) {
+    t.equal(run.warnings.join("; "), "", "the script ran without warnings");
+    const over = runOf(run, "over.json");
+    t.equal(over.phase, OVER, "the crate ended the round");
+    const p = run.json<PlatformDump>("platform.json");
+    t.equal(p.host, "local", "og run answers from its local store");
+    const of = (m: string) => p.calls.filter((c) => c.method === m);
+    const get = of("store.get")[0];
+    t.ok(get?.tick === 0 && get.args["key"] === "best", "tick 0 asks the store for `best`");
+    t.equal(get?.result?.data["value"], null, "nothing was stored before this run");
+    const submit = of("leaderboard.submit")[0];
+    t.equal(submit?.args["score"], over.score, `the crash submitted the score (${over.score})`);
+    t.equal(submit?.result?.data["rank"], 1, "the only run on the local board ranks first");
+    const set = of("store.set")[0];
+    t.equal(set?.args["value"], over.score, "the new best was saved");
+    t.equal(set?.result?.data["revision"], 1, "as the key's first revision");
+    t.equal(of("telemetry")[0]?.args["name"], "round.over", "a round.over event was filed");
+    t.equal(of("telemetry")[0]?.state, "sent", "one-way: nothing answers it");
+  },
+});

package/archetypes/runner/tests/replay.og.ts

@@ -0,0 +1,36 @@
+// Determinism: the same script twice, in fresh processes, ends on the same
+// world hash. It covers what the feel added to the world state: dice-made
+// patterns, jumps (stretch and squash tweens), a coin's pickup (its pop and
+// floating text), the run clip's footfalls (dust puffs), a crash (hit stop,
+// shake, knock-back, the flash) and a second round.
+import { playtest } from "@origingame/engine/playtest";
+import { OVER, RUNNING, runOf, tap } from "./lib.ts";
+
+export default playtest({
+  name: "replay: two runs of jumps, coins and a crash end on one hash",
+  runs: 2,
+  commands: [
+    tap(0.5),
+    "1.0:place:coin:-2",
+    "2.0:place:crate:1",
+    tap(2.8),
+    "3.6:dump_entity:runner:round1.json",
+    "4.0:place:fence:1",
+    "5.2:dump_entity:runner:crashed.json",
+    tap(5.8),
+    "6.4:key_down:Space",
+    "6.7:key_up:Space",
+    tap(7.6),
+    "9.0:dump_entity:runner:round2.json",
+    "9.1:quit",
+  ].join(";"),
+  check(run, t) {
+    t.equal(run.warnings.join("; "), "", "the script ran without warnings");
+    const round1 = runOf(run, "round1.json");
+    t.ok(round1.phase === RUNNING && round1.coins >= 1, `round one jumped the crate and took the coin (${round1.coins} coins)`);
+    t.equal(runOf(run, "crashed.json").phase, OVER, "the fence ended round one");
+    t.equal(runOf(run, "round2.json").rounds, 2, "round two started");
+    t.equal(run.hashes.length, 2, "the script ran twice");
+    t.equal(run.hashes[1], run.hashes[0], `both runs end on the same world hash (${run.hashes.join(" vs ")})`);
+  },
+});

package/archetypes/runner/tests/sounds.og.ts

@@ -0,0 +1,43 @@
+// Sounds: the title is silent; a round's start, a jump, a coin and a crash
+// each play their own voice (the sfx-<bit> entity holds an og.AudioPlayback
+// while it plays), and the crash is heard in the mix.
+import { playtest } from "@origingame/engine/playtest";
+import { tap } from "./lib.ts";
+
+interface EntityDump {
+  components: Record<string, Record<string, unknown>>;
+}
+
+const VOICES = [
+  ["start.json", "the round's start"],
+  ["jump.json", "the jump"],
+  ["coin.json", "the coin"],
+  ["crash.json", "the crash"],
+] as const;
+
+export default playtest({
+  name: "a round's start, a jump, a coin and a crash each play their sound",
+  commands: [
+    "0.1:set:runner.Tuning.spawnInterval=60",
+    "0.45:listen:title.wav:0.3",
+    tap(0.5),
+    "0.7:dump_entity:sfx-8:start.json",
+    tap(1.2),
+    "1.25:dump_entity:sfx-1:jump.json",
+    "2.0:place:coin:-4.6",
+    "2.15:dump_entity:sfx-2:coin.json",
+    "2.6:place:crate:-4.6",
+    "2.8:dump_entity:sfx-4:crash.json",
+    "2.9:listen:crash.wav:0.3",
+    "3.0:quit",
+  ].join(";"),
+  check(run, t) {
+    t.equal(run.warnings.join("; "), "", "the script ran without warnings");
+    t.ok(run.wav("title.wav").peak < 0.001, `the title is silent (peak ${run.wav("title.wav").peak})`);
+    for (const [file, what] of VOICES) {
+      const d = run.json<EntityDump>(file);
+      t.ok("og.AudioPlayback" in d.components, `${what} plays its voice (${file}: ${Object.keys(d.components).join(", ")})`);
+    }
+    t.ok(run.wav("crash.wav").peak > 0.05, `the crash is heard (peak ${run.wav("crash.wav").peak})`);
+  },
+});

package/archetypes/runner/tests/tune.og.ts

@@ -0,0 +1,36 @@
+// Tune writes through the schema: `set:runner.Tuning.speed` changes the
+// start speed of the next round, `jumpHeight` and `timeToApex` the arc of a
+// full jump (og.PlatformerController's designer units).
+import { playtest } from "@origingame/engine/playtest";
+import { RUNNING, positionOf, runOf, tap } from "./lib.ts";
+
+export default playtest({
+  name: "set writes Tuning: start speed and jump height change the run",
+  commands: [
+    "0.1:set:runner.Tuning.spawnInterval=60",
+    "0.1:set:runner.Tuning.speedRamp=0",
+    "0.1:set:runner.Tuning.speed=10",
+    "0.1:set:runner.Tuning.jumpHeight=4",
+    "0.1:set:runner.Tuning.timeToApex=0.667",
+    "0.1:dump_entity:runner:tuning.json",
+    tap(0.5),
+    "1.5:dump_entity:runner:fast.json",
+    "1.6:key_down:Space",
+    // A full jump of height 4 m peaks after about 0.67 s.
+    "2.27:dump_entity:runner:apex.json",
+    "2.4:key_up:Space",
+    "2.5:quit",
+  ].join(";"),
+  check(run, t) {
+    t.equal(run.warnings.join("; "), "", "the script ran without warnings");
+    const tuning = run.json<{ components: { Tuning: { speed: number; jumpHeight: number } } }>("tuning.json").components.Tuning;
+    t.equal(tuning.speed, 10, "the start speed was set");
+    t.equal(tuning.jumpHeight, 4, "the jump height was set");
+    const fast = runOf(run, "fast.json");
+    t.equal(fast.phase, RUNNING, "running");
+    t.near(fast.speed, 10, 1e-4, "the round starts at the tuned speed");
+    t.near(fast.distance, 10, 0.4, `about 10 m in the first second (${fast.distance.toFixed(2)})`);
+    const apex = positionOf(run, "apex.json").y;
+    t.near(apex, 4, 0.15, `the jump peaks near the tuned 4 m (${apex.toFixed(2)} m)`);
+  },
+});