@origingame/create-game 0.0.0-stage → 0.1.1

package/archetypes/roguelike/src/ui.ts

@@ -0,0 +1,350 @@
+// Lamp Dive's screens on og.ui and the skin in assets/skins/lampdive (the
+// engine's pixel pack in tomb colours): the title, the HUD (health, strike,
+// armour and gold in the top-left corner, the floor and pause in the
+// top-right, the draught and, on a touch screen, Wait and a d-pad along the
+// bottom), the pause menu, the settings dialog and the run's summary when
+// the lamp goes out or the relic is taken. Screens change through a
+// dissolve (a fade with reduced motion). Every string is a key of
+// assets/strings/*.ogt.
+//
+// The Ui system also starts dives (a fresh seed from og.Rng), ends them a
+// beat after the lamp goes out or the relic is taken, sizes the camera for
+// the surface, sets the buses and keeps the settings and the dive record
+// in og.platform (the record written at the revision read, and merged when
+// another device wrote it first).
+
+import { og, defineSystem } from "@origingame/engine";
+import type { Value, World } from "@origingame/engine";
+import { FOES, Game, Phase, Prefs, Tuning } from "./components.ts";
+import { lazyTuning, must, OVER_DELAY } from "./systems.ts";
+
+export const LANGUAGES = [
+  { code: "en", key: "lang.en" },
+  { code: "zh-CN", key: "lang.zh" },
+] as const;
+
+/** The floors of a dive. */
+export const FLOORS = 2;
+
+/** The tokens' spacing scale in CSS px (og.ui.frameTheme answers it too, but builds the whole theme each call). */
+const S = { xxs: 2, xs: 4, sm: 8, md: 12, lg: 16 } as const;
+
+type GameV = Value<typeof Game>;
+type PrefsV = Value<typeof Prefs>;
+
+export function say(world: World, key: string, args?: Record<string, string | number>): string {
+  return og.i18n.t(world, key, args);
+}
+
+const grow = { kind: "grow" } as const;
+const px = (n: number) => ({ kind: "fixed", px: n }) as const;
+
+/** A new dive: a fresh seed, the lamp-bearer whole, floor 1 carved on this tick. */
+export function startDive(world: World, g: GameV): void {
+  const t = lazyTuning(world);
+  const rng = world.resource(og.Rng);
+  g.seed = rng.ok ? rng.value.integer(1, 1_000_000_000) : 1;
+  g.phase = Phase.Play;
+  g.paused = false;
+  g.won = false;
+  g.floor = 1;
+  g.deepest = 1;
+  g.hpMax = t.heroHp;
+  g.hp = t.heroHp;
+  g.attack = t.heroAttack;
+  g.armour = 0;
+  g.lamp = t.lamp;
+  g.potions = 1;
+  g.gold = 0;
+  g.kills = 0;
+  g.hits = 0;
+  g.hurts = 0;
+  g.finds = 0;
+  g.turns = 0;
+  g.killedBy = -1;
+  g.overTicks = 0;
+  g.lock = 0;
+  g.queued = 0;
+  g.foesTurn = false;
+  g.newRecord = false;
+  g.build = true;
+  g.dives += 1;
+  saveRecord(world, g);
+}
+
+/** The dive record ({dives, relics}) written at the revision it was read at. */
+function saveRecord(world: World, g: GameV): void {
+  const r = og.platform.storeSet(world, { key: "record", value: { dives: g.dives, relics: g.relics }, revision: g.recordRevision });
+  if (r.ok) g.recordWrite = r.value;
+}
+
+function applyPrefs(world: World, p: PrefsV): void {
+  const audio = world.resource(og.Audio);
+  if (audio.ok) {
+    audio.value.master = p.master;
+    audio.value.music = p.music;
+    audio.value.sfx = p.effects;
+    audio.value.ui = p.effects;
+  }
+}
+
+function setLanguage(world: World, p: PrefsV, index: number): void {
+  p.language = Math.max(0, Math.min(LANGUAGES.length - 1, index));
+  og.i18n.setLocale(world, LANGUAGES[p.language]!.code);
+}
+
+function prefsValue(p: PrefsV) {
+  return { masterVolume: p.master, musicVolume: p.music, sfxVolume: p.effects, language: LANGUAGES[p.language]!.code, reducedMotion: p.reducedMotion };
+}
+
+/**
+ * og.platform: the settings and the record asked for on tick 0 and applied
+ * when they answer; a record write refused for a stale revision (another
+ * device dived meanwhile) is read again, merged (the stored counts plus
+ * what this device added since it last read or wrote them) and written at
+ * the new revision.
+ */
+function platform(world: World, g: GameV, p: PrefsV): void {
+  if (world.tick === 0) {
+    p.loadRequest = og.platform.loadSettings(world);
+    const r = og.platform.storeGet(world, "record");
+    g.recordRequest = r.ok ? r.value : 0;
+    return;
+  }
+  if (p.loadRequest !== 0) {
+    const r = og.platform.result(world, p.loadRequest);
+    if (r !== null) {
+      p.loadRequest = 0;
+      const s = ((r.ok ? r.data : null) as { value?: Record<string, unknown> } | null)?.value ?? null;
+      if (s && typeof s === "object") {
+        if (typeof s.masterVolume === "number") p.master = s.masterVolume;
+        if (typeof s.musicVolume === "number") p.music = s.musicVolume;
+        if (typeof s.sfxVolume === "number") p.effects = s.sfxVolume;
+        if (typeof s.reducedMotion === "boolean") p.reducedMotion = s.reducedMotion;
+        const at = LANGUAGES.findIndex((l) => l.code === s.language);
+        if (at >= 0) setLanguage(world, p, at);
+        applyPrefs(world, p);
+      }
+    }
+  }
+  if (g.recordRequest !== 0) {
+    const r = og.platform.result(world, g.recordRequest);
+    if (r !== null) {
+      g.recordRequest = 0;
+      const d = (r.ok ? r.data : null) as { value?: { dives?: number; relics?: number } | null; revision?: number } | null;
+      // The stored counts plus what this device added since it last read or wrote them.
+      const dives = d?.value?.dives ?? 0;
+      const relics = d?.value?.relics ?? 0;
+      g.dives = dives + g.dives - g.recordDives;
+      g.relics = relics + g.relics - g.recordRelics;
+      g.recordDives = dives;
+      g.recordRelics = relics;
+      if (typeof d?.revision === "number") g.recordRevision = d.revision;
+      if (g.recordMerge) {
+        g.recordMerge = false;
+        saveRecord(world, g);
+      }
+    }
+  }
+  if (g.recordWrite !== 0) {
+    const r = og.platform.result(world, g.recordWrite);
+    if (r !== null) {
+      g.recordWrite = 0;
+      if (r.ok) {
+        g.recordRevision = (r.data as { revision: number }).revision;
+        g.recordDives = g.dives;
+        g.recordRelics = g.relics;
+      }
+      else if (r.error?.code === "conflict") {
+        // Someone else wrote the record: read it again and write the merge.
+        g.recordConflicts += 1;
+        g.recordMerge = true;
+        const again = og.platform.storeGet(world, "record");
+        g.recordRequest = again.ok ? again.value : 0;
+      }
+    }
+  }
+}
+
+function capsule(id: string, build: () => void): void {
+  og.ui.row(id, { gap: S.xs, cross: "center", padding: { left: S.sm, top: S.xs, right: S.md, bottom: S.xs }, frame: "capsule", background: { token: "surface" } }, build);
+}
+
+function hud(world: World, g: GameV): void {
+  const vp = og.ui.frameViewport();
+  const touch = vp.coarsePointer;
+  og.ui.setNavigation(false);
+  og.ui.anchor("Status", { anchor: "topLeft", direction: "column", gap: S.sm }, () => {
+    capsule("Health", () => {
+      og.ui.icon("Heart", "heart", { size: 22, tint: { token: g.hp * 3 <= g.hpMax ? "danger" : "fg" } });
+      og.ui.meter("Bar", g.hp, g.hpMax, { kind: "health", label: `${g.hp}/${g.hpMax}`, width: px(touch ? 110 : 150) });
+    });
+    capsule("Stats", () => {
+      og.ui.icon("Sword", "sword", { size: 20 });
+      og.ui.counter("Attack", g.attack, { font: "mono", width: px(22) });
+      og.ui.icon("Shield", "shield", { size: 20 });
+      og.ui.counter("Armour", g.armour, { font: "mono", width: px(22) });
+      og.ui.icon("Coin", "coin", { size: 20, tint: { token: "accent" } });
+      og.ui.counter("Gold", g.gold, { font: "mono", width: px(40) });
+    });
+  });
+  let paused = false;
+  og.ui.anchor("Depth", { anchor: "topRight", gap: S.sm, cross: "center" }, () => {
+    capsule("Floor", () => og.ui.label("Label", say(world, "hud.floor", { n: g.floor, total: FLOORS }), { step: "lg", nowrap: true }));
+    if (og.ui.actionButton("Pause", say(world, "hud.pause"), { icon: "pause", size: 48 }).clicked) paused = true;
+  });
+  if (paused) g.paused = true;
+  og.ui.anchor("Hands", { anchor: "bottomLeft", gap: S.md, cross: "end" }, () => {
+    og.ui.column("Flask", { cross: "center", gap: S.xxs }, () => {
+      if (og.ui.actionButton("Drink", say(world, "hud.drink"), { icon: "potion", size: 60 }).clicked) g.padDrink = true;
+      // A refused draught (the Hero system, after this one, refused it last tick) shakes the flask once, with the error sound (og-ui §6).
+      if (g.refusedTick === world.tick - 1) og.ui.shake({ sound: true });
+      og.ui.label("Count", `× ${g.potions}`, { font: "mono", nowrap: true });
+    });
+    if (touch && og.ui.actionButton("Wait", say(world, "hud.wait"), { icon: "clock", size: 52 }).clicked) g.padWait = true;
+  });
+  let dir = 0;
+  if (touch) {
+    og.ui.anchor("Move", { anchor: "bottomRight" }, () => {
+      const d = og.ui.dpad("Pad", { size: 150 });
+      dir = d.up ? 1 : d.right ? 2 : d.down ? 3 : d.left ? 4 : 0;
+    });
+  }
+  if (dir !== g.padDir) g.padDir = dir;
+}
+
+function settings(world: World, g: GameV, p: PrefsV): void {
+  let done = false;
+  const before = JSON.stringify(prefsValue(p));
+  const m = og.ui.modal("Settings", g.settingsOpen, { title: say(world, "settings.title"), width: px(Math.min(420, og.ui.frameViewport().width - 32)) }, () => {
+    const slider = (id: string, key: string, value: number): number => {
+      let out = value;
+      og.ui.row(id, { width: grow, gap: S.md, cross: "center" }, () => {
+        og.ui.label("Label", say(world, key), { width: px(110), nowrap: true });
+        out = og.ui.slider("Slider", value, { step: 0.05 }).value;
+        og.ui.label("Value", `${Math.round(out * 100)}`, { width: px(40), align: "end", font: "mono", nowrap: true });
+      });
+      return out;
+    };
+    p.master = slider("Master", "settings.master", p.master);
+    p.music = slider("Music", "settings.music", p.music);
+    p.effects = slider("Effects", "settings.effects", p.effects);
+    og.ui.label("LanguageLabel", say(world, "settings.language"), { color: { token: "fgMuted" } });
+    const r = og.ui.radio("Language", LANGUAGES.map((l) => say(world, l.key)), p.language, { horizontal: true });
+    if (r.selected !== p.language) setLanguage(world, p, r.selected);
+    p.reducedMotion = og.ui.toggle("Motion", p.reducedMotion, say(world, "settings.motion")).on;
+    og.ui.row("Footer", { width: grow, align: "end" }, () => {
+      if (og.ui.button("Done", say(world, "settings.done"), { variant: "primary" }).clicked) done = true;
+    });
+  });
+  if (JSON.stringify(prefsValue(p)) !== before) applyPrefs(world, p);
+  if (g.settingsOpen && (done || m.dismissed)) {
+    g.settingsOpen = false;
+    must(og.platform.saveSettings(world, prefsValue(p)));
+    p.saves += 1;
+  }
+}
+
+/** The run's summary: how it ended, how deep, how long, what fell, what was found. */
+function summary(world: World, g: GameV): "again" | "menu" | null {
+  let chose: "again" | "menu" | null = null;
+  og.ui.modal("Summary", g.phase === Phase.Over, { title: g.won ? say(world, "over.won") : say(world, "over.lost", { n: g.floor }), locked: true, width: px(Math.min(400, og.ui.frameViewport().width - 32)) }, () => {
+    og.ui.row("Mark", { width: grow, align: "center" }, () => {
+      og.ui.transition("Icon", true, { kind: "pop" }, () => og.ui.icon("Glyph", g.won ? "crown" : "skull", { size: 48, tint: { token: g.won ? "accent" : "fgMuted" } }));
+      if (g.won && g.overTicks === OVER_DELAY + 20) og.ui.burst({ count: 12 });
+    });
+    og.ui.column("Stats", { width: grow, gap: 0 }, () => {
+      og.ui.keyValue("Floor", say(world, "over.floor"), `${g.deepest}/${FLOORS}`, true);
+      og.ui.keyValue("Turns", say(world, "over.turns"), `${g.turns}`, true);
+      og.ui.keyValue("Kills", say(world, "over.kills"), `${g.kills}`, true);
+      og.ui.keyValue("Gold", say(world, "over.gold"), `${g.gold}`, true);
+      og.ui.keyValue("Finds", say(world, "over.finds"), `${g.finds}`, true);
+      if (!g.won) og.ui.keyValue("By", say(world, "over.by"), say(world, g.killedBy >= 0 ? `foe.${FOES[g.killedBy]}` : "foe.none"), false);
+    });
+    og.ui.label("Record", say(world, "over.record", { dives: g.dives, relics: g.relics }), { color: { token: "fgMuted" }, align: "center", width: grow });
+    og.ui.row("Actions", { width: grow, gap: S.sm }, () => {
+      if (og.ui.button("Again", say(world, "over.again"), { variant: "primary", width: grow }).clicked) chose = "again";
+      if (og.ui.button("Menu", say(world, "over.menu"), { width: grow }).clicked) chose = "menu";
+    });
+  });
+  return chose;
+}
+
+/** The screens, the dive's start and end, the camera, the buses, the platform's answers. */
+export const Ui = defineSystem("Ui", { reads: [Tuning], writes: [Game, Prefs, og.Camera, og.Audio, og.Rng] }, (_q, time, world) => {
+  const game = world.resource(Game);
+  const prefs = world.resource(Prefs);
+  if (!game.ok || !prefs.ok) return;
+  const g = game.value;
+  const p = prefs.value;
+  platform(world, g, p);
+  if (time.tick === 0) applyPrefs(world, p);
+  // The camera: 13 cells tall on a wide screen, 10 cells across a portrait one.
+  const vp = og.ui.frameViewport();
+  if (vp.width > 0 && (vp.width !== g.viewW || vp.height !== g.viewH)) {
+    g.viewW = vp.width;
+    g.viewH = vp.height;
+    const cam = world.resource(og.Camera);
+    if (cam.ok) cam.value.height = vp.width < vp.height ? (10 * vp.height) / vp.width : 13;
+  }
+  const hold = g.phase === Phase.Play && (g.paused || g.settingsOpen);
+  if (hold !== g.held) {
+    must(og.time.setScale(world, hold ? 0 : 1));
+    g.held = hold;
+  }
+  // A beat after the lamp goes out or the relic is taken, the summary.
+  if (g.phase === Phase.Play && (g.hp <= 0 || g.won)) {
+    g.overTicks += 1;
+    if (g.overTicks === OVER_DELAY) {
+      g.phase = Phase.Over;
+      if (g.won) g.relics += 1;
+      saveRecord(world, g);
+      must(og.platform.telemetry(world, "dive.over", { won: g.won, floor: g.deepest, turns: g.turns, kills: g.kills, gold: g.gold }));
+    }
+  } else if (g.phase === Phase.Over) g.overTicks += 1;
+
+  const screen = g.phase === Phase.Title ? "title" : g.phase === Phase.Play ? "play" : "over";
+  const shown = og.ui.screenTransition("Screens", screen, { kind: p.reducedMotion ? "fade" : "dissolve", durationMs: 600 }).shown;
+  if (shown !== "title") g.leftTitle = true;
+  if (shown === "title") {
+    og.ui.setNavigation(true);
+    const r = og.ui.mainMenu("Title", {
+      title: say(world, "title.name"),
+      subtitle: say(world, "title.tagline"),
+      items: [
+        { id: "play", label: say(world, "title.play"), primary: true },
+        { id: "settings", label: say(world, "title.settings") },
+      ],
+      footer: say(world, "title.footer"),
+      // The title the game opens on is built settled: the web draws it behind the play gate, where
+      // the skin's entrance would stand part-way until the tap (og-platform-sdk §3). Later titles enter.
+      instant: !g.leftTitle,
+    });
+    if (!g.settingsOpen && r.selected === "play") startDive(world, g);
+    if (r.selected === "settings") g.settingsOpen = true;
+  } else if (shown === "play") {
+    hud(world, g);
+    const m = og.ui.pauseMenu("Pause", {
+      open: g.paused && !g.settingsOpen,
+      title: say(world, "pause.title"),
+      items: [
+        { id: "resume", label: say(world, "pause.resume"), primary: true },
+        { id: "settings", label: say(world, "pause.settings") },
+        { id: "quit", label: say(world, "pause.quit") },
+      ],
+    });
+    if (m.selected === "resume") g.paused = false;
+    if (m.selected === "settings") g.settingsOpen = true;
+    if (m.selected === "quit") {
+      g.paused = false;
+      g.phase = Phase.Title;
+    }
+  } else {
+    og.ui.setNavigation(true);
+    const c = summary(world, g);
+    if (c === "again") startDive(world, g);
+    if (c === "menu") g.phase = Phase.Title;
+  }
+  settings(world, g, p);
+  if (g.language !== p.language) g.language = p.language;
+});

package/archetypes/roguelike/tests/flow.og.ts

@@ -0,0 +1,54 @@
+// The core loop through real input: Dive on the title starts a dive on a
+// fresh seed; then seed 7's first floor (the same start as Dive, with a
+// known seed) is walked with the arrows: up the corridor (each step a
+// turn, the lamp lighting what it reaches), a bump into the stone (no
+// turn), then on up into the rats coming to meet the lamp (walking into a
+// foe strikes it), and Q drinks the flask.
+import { playtest } from "@origingame/engine/playtest";
+import { component, game, PLAY, press, presses, tap, TITLE } from "./lib.ts";
+
+export default playtest({
+  name: "a dive from the title: steps, a bump, the lamp's light, strikes and a draught",
+  commands: [
+    "0.3:get:Game:title.json",
+    "0.9:screenshot:title.png",
+    tap("play", 1.0),
+    "1.4:get:Game:started.json",
+    "1.45:dive:7",
+    "1.5:get:Game:start7.json",
+    presses(["ArrowUp", "ArrowUp", "ArrowUp", "ArrowUp"], 1.6),
+    press("ArrowLeft", 2.7),
+    "3.0:get:Game:walked.json",
+    presses(Array(12).fill("ArrowUp"), 3.1),
+    "6.2:get:Game:fought.json",
+    "6.25:screenshot:fought.png",
+    press("KeyQ", 6.3),
+    "6.7:get:Game:drank.json",
+    "6.7:dump_entity:hero:hero.json",
+    "6.8:quit",
+  ].join(";"),
+  check(run, t) {
+    t.equal(run.warnings.join("; "), "", "the script ran without warnings");
+    t.ok(run.quit, "the script reached quit");
+    t.equal(game(run, "title.json").phase, TITLE, "the game opens on the title");
+    const started = game(run, "started.json");
+    t.equal(started.phase, PLAY, "Dive started a dive");
+    t.ok(started.seed !== 0 && started.seed !== 1, `on a fresh seed (${started.seed})`);
+    t.ok(started.floor === 1 && started.hp === 20 && started.potions === 1 && started.dives === 1, "on floor 1 with full health and one draught");
+    t.ok(started.lit > 0, `the lamp lights the first room (${started.lit} cells)`);
+    const s7 = game(run, "start7.json");
+    t.equal(`${s7.heroX},${s7.heroY}`, "4,15", "seed 7 starts the lamp-bearer in its first room");
+    const walked = game(run, "walked.json");
+    t.equal(`${walked.heroX},${walked.heroY}`, "4,11", "four presses walked four cells up the corridor");
+    t.equal(walked.turns, 4, "four steps, four turns; the bump into the stone took none");
+    t.ok(walked.seen > s7.seen, `the lamp lit new cells on the way (${s7.seen} → ${walked.seen})`);
+    t.equal(component<{ bumps: number }>(run, "hero.json", "Hero").bumps >= 1, true, "the stone refused the step to the left");
+    const fought = game(run, "fought.json");
+    t.ok(fought.hits >= 2 && fought.kills >= 1, `walking into the rats struck them (${fought.hits} strikes, ${fought.kills} felled)`);
+    t.ok(fought.hurts >= 1 && fought.hp < 20, `the rats struck back (${fought.hurts} times, health ${fought.hp})`);
+    t.ok(fought.heroY < 11, "and the lamp-bearer pressed on up");
+    const drank = game(run, "drank.json");
+    t.equal(drank.potions, fought.potions - 1, "Q drank the draught");
+    t.ok(drank.hp > fought.hp, `and it healed (${fought.hp} → ${drank.hp})`);
+  },
+});

package/archetypes/roguelike/tests/foes.og.ts

@@ -0,0 +1,45 @@
+// The foes' minds (assets/ai/foe.ogt on og.ai): a rat that sees the lamp
+// hunts it along og.nav's path, a cell a turn, and strikes once beside it;
+// the lamp-bearer's strikes land on a rat (a hit stop, the number) and the
+// second fells it. Seed 7's first floor has a rat at (6, 7).
+import { playtest } from "@origingame/engine/playtest";
+import { foe, game, press, presses } from "./lib.ts";
+
+export default playtest({
+  name: "a rat hunts and strikes; two strikes fell it",
+  commands: [
+    "0.3:dive:7",
+    "0.5:warp:3:7",
+    "0.6:get:Foes:before.json",
+    presses(["Space", "Space"], 0.7),
+    "1.3:get:Foes:closer.json",
+    presses(["Space", "Space"], 1.4),
+    "2.0:get:Game:struck.json",
+    "2.2:dive:7",
+    "2.4:warp:5:7",
+    press("ArrowRight", 2.6),
+    "2.75:get:Game:hit.json",
+    "2.75:dump_entity:foe-0:hit-foe.json",
+    presses(["ArrowRight", "ArrowRight"], 2.9),
+    "3.6:get:Game:felled.json",
+    "3.6:get:Foes:felled-foes.json",
+    "3.7:quit",
+  ].join(";"),
+  check(run, t) {
+    t.equal(run.warnings.join("; "), "", "the script ran without warnings");
+    const [x0, y0] = foe(run, "before.json", 0);
+    t.equal(`${x0},${y0}`, "6,7", "the rat stands at (6, 7)");
+    const [x1] = foe(run, "closer.json", 0);
+    t.ok(x1 < x0, `two turns waited, it came along the row toward the lamp (x ${x0} → ${x1})`);
+    const struck = game(run, "struck.json");
+    t.ok(struck.hurts >= 1 && struck.hp < struck.hpMax, `beside the lamp-bearer it struck (${struck.hurts} strikes, health ${struck.hp})`);
+    const hit = game(run, "hit.json");
+    t.equal(hit.hits, 1, "walking into it struck it");
+    const rat = run.json<{ components: { Foe: { hp: number; hpMax: number; active: boolean } } }>("hit-foe.json").components.Foe;
+    t.ok(rat.active && rat.hp < rat.hpMax, `the strike took its health (${rat.hp}/${rat.hpMax})`);
+    const felled = game(run, "felled.json");
+    t.equal(felled.kills, 1, "the second strike felled it");
+    t.equal(foe(run, "felled-foes.json", 0).join(","), "-1,-1", "and it left the board");
+    t.equal(`${felled.heroX},${felled.heroY}`, "6,7", "the third press stepped where it stood");
+  },
+});

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

@@ -0,0 +1,32 @@
+// Three frames at 1280×720 compared with references/<tier>/: the title over
+// the lit first room, seed 7's corridor after a strike (the lamp's light,
+// the fog remembered behind, a rat), and the summary when the lamp went
+// out. `OG_FX_CAPTURE=1 og test .` records this tier's references.
+import { playtest } from "@origingame/engine/playtest";
+import { checkFrames } from "./frames.ts";
+import { press, presses } from "./lib.ts";
+
+const FILES = ["title.png", "dive.png", "over.png"];
+
+export default playtest({
+  name: "the title, the lamp in the tomb and the summary match their reference frames",
+  size: "1280x720",
+  commands: [
+    "0.9:screenshot:title.png",
+    "0.95:dive:7",
+    presses(Array(7).fill("ArrowUp"), 1.15),
+    "3.65:screenshot:dive.png",
+    "3.75:hp:1",
+    "3.75:warp:6:7",
+    press("Space", 3.85),
+    "6.0:screenshot:over.png",
+    "6.1:quit",
+  ].join(";"),
+  check(run, t) {
+    t.equal(run.warnings.join("; "), "", "the script ran without warnings");
+    t.frame(FILES, () => {
+      for (const f of FILES) t.equal(run.png(f).width, 1280, `${f} is 1280 wide`);
+    });
+    checkFrames(run, t, FILES, "");
+  },
+});

package/archetypes/roguelike/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)`);
+    }
+  });
+}