@origingame/create-game 0.0.0-stage → 0.1.0

package/archetypes/tower-defense/src/ui.ts

@@ -0,0 +1,382 @@
+// Path Guard's screens on og.ui and the skin in assets/skins/pathguard:
+// the title, the HUD (the light and the coins in the top-left corner, the
+// wave and pause in the top-right, the plant tray on the right on a wide
+// screen and along the bottom on a phone), the pause menu, the settings
+// dialog and the end card. Screens change through an iris (a fade with
+// reduced motion). Every string is a key of assets/strings/*.ogt.
+//
+// The Ui system also frames the camera on the field for the surface (the
+// field beside the tray on a wide screen, between the HUD rows on a
+// phone), sets the buses from the settings and reads and writes the
+// settings and the best score through og.platform.
+
+import { og, defineSystem } from "@origingame/engine";
+import type { Entity, Value, World } from "@origingame/engine";
+import { Game, Phase, Plant, PLANTS, Prefs, Tuning } from "./components.ts";
+import { COLS, cost, lazyTuning, ROWS, WAVES } from "./systems.ts";
+
+/** The languages the settings offer, each named in its own language. */
+export const LANGUAGES = [
+  { code: "en", key: "lang.en" },
+  { code: "zh-CN", key: "lang.zh" },
+] as const;
+
+type GameV = Value<typeof Game>;
+type TuneV = Value<typeof Tuning>;
+type PrefsV = Value<typeof Prefs>;
+/**
+ * The tokens' spacing scale in CSS px (the same at every density). og.ui's
+ * frameTheme answers it too, but builds the whole theme each call (about a
+ * millisecond), so the screens read it from here.
+ */
+const SPACE = { xxs: 2, xs: 4, sm: 8, md: 12, lg: 16, xl: 24 } as const;
+type Theme = { readonly space: typeof SPACE };
+const THEME: Theme = { space: SPACE };
+
+/** A string of the active locale (og.i18n). */
+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;
+
+function must(r: { ok: true } | { ok: false; reason: string }): void {
+  if (!r.ok) throw new Error(r.reason);
+}
+
+/** The phone layouts: a portrait or landscape phone. */
+function phone(): boolean {
+  const b = og.ui.frameViewport().breakpoint;
+  return b === "phonePortrait" || b === "phoneLandscape";
+}
+
+/** The sheet frame of a plant, for the tray's pictures. */
+const PICTURE = [8, 11, 14] as const;
+function uvOf(frame: number): [number, number, number, number] {
+  return [(frame % 8) / 8, Math.floor(frame / 8) / 3, ((frame % 8) + 1) / 8, (Math.floor(frame / 8) + 1) / 3];
+}
+
+/** A new round: the field cleared, the purse and the light full, the first wave three seconds off. */
+export function startRound(world: World, g: GameV, t: TuneV): void {
+  g.phase = Phase.Play;
+  g.paused = false;
+  g.won = false;
+  g.rounds += 1;
+  g.lives = t.startLives;
+  g.gold = t.startGold;
+  g.wave = 0;
+  g.inWave = false;
+  g.toSpawn = 0;
+  g.spawned = 0;
+  g.breakTicks = 180;
+  g.callNext = false;
+  g.kills = 0;
+  g.leaks = 0;
+  g.placed = 0;
+  g.refused = 0;
+  g.shots = 0;
+  g.score = 0;
+  g.newBest = false;
+  g.selected = Plant.Thorn;
+  g.cursorX = 4;
+  g.cursorY = 9;
+  const grid = g.grid as unknown as never;
+  for (let y = 1; y < ROWS - 1; y++) {
+    for (let x = 1; x < COLS - 1; x++) {
+      must(og.tilemap.setTile(world, { entity: g.map as unknown as Entity, layer: "pads", x, y, tile: -1 }));
+      must(og.nav.setCost(world, grid, x, ROWS - 1 - y, 1));
+    }
+  }
+  // The Plants and Visitors systems clear their rows on their next run.
+  g.reset = true;
+  g.pendingPlants = 0;
+}
+
+/** Frames the camera on the field for this surface: beside the tray on a wide screen, between the HUD rows on a phone. */
+function frameCamera(world: World, g: GameV): void {
+  const vp = og.ui.frameViewport();
+  if (vp.width <= 0 || vp.height <= 0 || (vp.width === g.viewW && vp.height === g.viewH && vp.safeArea.top === g.viewTop)) return;
+  g.viewW = vp.width;
+  g.viewH = vp.height;
+  g.viewTop = vp.safeArea.top;
+  const cam = world.resource(og.Camera);
+  if (!cam.ok) return;
+  const portrait = vp.width < vp.height;
+  // The rectangle the field may use, in CSS pixels: room for the HUD's rows and the tray.
+  const top = vp.safeArea.top + (portrait ? 84 : 76);
+  const bottom = vp.safeArea.bottom + (portrait ? 176 : 24);
+  const right = vp.safeArea.right + (portrait ? 0 : 200);
+  const left = vp.safeArea.left + (portrait ? 0 : 200);
+  const w = vp.width - left - right;
+  const h = vp.height - top - bottom;
+  const scale = Math.min(w / (COLS + 0.4), h / (ROWS + 0.4));
+  const cx = left + w / 2;
+  const cy = top + h / 2;
+  const c = cam.value;
+  c.orthographic = true;
+  c.height = vp.height / scale;
+  c.position = { x: COLS / 2 - (cx - vp.width / 2) / scale, y: ROWS / 2 + (cy - vp.height / 2) / scale, z: 50 };
+}
+
+/** The settings applied: the buses, the language, the motion. */
+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);
+}
+
+/** The settings as og.platform.saveSettings keeps them. */
+function prefsValue(p: PrefsV) {
+  return { masterVolume: p.master, musicVolume: p.music, sfxVolume: p.effects, language: LANGUAGES[p.language]!.code, reducedMotion: p.reducedMotion };
+}
+
+/** The first ticks: ask for the settings and the best score; apply each when it answers. A best written at a stale revision is read again and the higher written back. */
+function platform(world: World, g: GameV, p: PrefsV): void {
+  if (world.tick === 0) {
+    p.loadRequest = og.platform.loadSettings(world);
+    const b = og.platform.storeGet(world, "best");
+    g.bestRequest = b.ok ? b.value : 0;
+    return;
+  }
+  if (p.loadRequest !== 0) {
+    const r = og.platform.result(world, p.loadRequest);
+    if (r !== null) {
+      p.loadRequest = 0;
+      p.loaded = true;
+      const v = (r.ok ? r.data : null) as { value?: Record<string, unknown> } | null;
+      const s = v?.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);
+      }
+    }
+  }
+  if (g.bestRequest !== 0) {
+    const r = og.platform.result(world, g.bestRequest);
+    if (r !== null) {
+      g.bestRequest = 0;
+      const d = (r.ok ? r.data : null) as { value?: unknown; revision?: number } | null;
+      if (d && typeof d.value === "number") g.best = Math.max(g.best, d.value);
+      if (d && typeof d.revision === "number") g.bestRevision = d.revision;
+      // A best this device holds above the stored one (a write refused as stale) is written again at the revision just read.
+      if (d && g.best > (typeof d.value === "number" ? d.value : 0)) {
+        const w = og.platform.storeSet(world, { key: "best", value: g.best, revision: g.bestRevision });
+        if (w.ok) g.bestWrite = w.value;
+      }
+    }
+  }
+  if (g.bestWrite !== 0) {
+    const r = og.platform.result(world, g.bestWrite);
+    if (r !== null) {
+      g.bestWrite = 0;
+      if (r.ok) g.bestRevision = (r.data as { revision: number }).revision;
+      else if (r.error?.code === "conflict") {
+        // Another device wrote `best` meanwhile: read it again; the answer keeps the higher and writes it back.
+        const again = og.platform.storeGet(world, "best");
+        g.bestRequest = again.ok ? again.value : 0;
+      }
+    }
+  }
+}
+
+/** One HUD capsule: an icon and a number counting to its value. */
+function capsule(t: Theme, id: string, icon: string, value: number, tone: "accent" | "danger" | "fg"): void {
+  og.ui.row(id, { gap: t.space.xs, cross: "center", padding: { left: t.space.sm, top: t.space.xs, right: t.space.md, bottom: t.space.xs }, frame: "capsule", background: { token: "surface" }, radius: 999 }, () => {
+    og.ui.icon("Icon", icon, { size: 26, tint: { token: tone === "fg" ? "fg" : tone } });
+    og.ui.counter("Value", value, { step: "xl", font: "display", durationMs: 300, width: px(56), align: "center" });
+  });
+}
+
+function hud(world: World, theme: Theme, g: GameV, t: TuneV): void {
+  const small = phone();
+  og.ui.setNavigation(false);
+  og.ui.anchor("Purse", { anchor: "topLeft", gap: theme.space.sm }, () => {
+    capsule(theme, "Light", "heart", g.lives, g.lives <= 3 ? "danger" : "fg");
+    capsule(theme, "Coins", "coin", g.gold, "accent");
+    // A refused placement shakes the purse once, with the error sound (og-ui §6).
+    if (g.refusedTick === world.tick) og.ui.shake({ sound: true });
+  });
+  let paused = false;
+  og.ui.anchor("Waves", { anchor: "topRight", gap: theme.space.sm, cross: "center" }, () => {
+    og.ui.row("Wave", { cross: "center", padding: { left: theme.space.md, top: theme.space.xs, right: theme.space.md, bottom: theme.space.xs }, frame: "capsule", background: { token: "surface" }, radius: 999 }, () => {
+      og.ui.label("Label", say(world, "hud.wave", { n: Math.max(1, g.wave), total: WAVES.length }), { step: "lg", font: "display", nowrap: true });
+    });
+    if (og.ui.actionButton("Pause", say(world, "hud.pause"), { icon: "pause", size: 48 }).clicked) paused = true;
+  });
+  if (paused) g.paused = true;
+  // The tray: the three plants, the selected one in the accent, an unaffordable one disabled; and the next wave.
+  og.ui.anchor("Tray", { anchor: small ? "bottom" : "right", direction: small ? "row" : "column", gap: theme.space.sm, cross: "center" }, () => {
+    PLANTS.forEach((name, kind) => {
+      const price = cost(t, kind);
+      const chosen = g.selected === kind;
+      og.ui.column(og.ui.idi("Plant", kind), { cross: "center", gap: theme.space.xxs, padding: { left: theme.space.sm, top: theme.space.xs, right: theme.space.sm, bottom: theme.space.sm }, frame: "card", background: { token: "surface" }, radius: 18 }, () => {
+        og.ui.row("Top", { cross: "center", gap: theme.space.xs }, () => {
+          og.ui.image("Picture", { texture: g.sheet as unknown as never, uv: uvOf(PICTURE[kind]!), width: px(small ? 32 : 44), height: px(small ? 32 : 44) });
+          // The price: muted when the purse covers it, in danger's ink when it does not.
+          og.ui.label("Price", `${price}`, { step: "lg", font: "display", color: { token: g.gold >= price ? "fgMuted" : "danger" }, nowrap: true, width: px(40), align: "center" });
+        });
+        if (og.ui.button("Pick", say(world, `tower.${name}`), { variant: chosen ? "primary" : "secondary", size: small ? "medium" : "small", width: px(small ? 86 : 104) }).clicked) g.selected = kind;
+      });
+    });
+    if (!small) callButton(world, g, small);
+  });
+  // On a phone the call for the next wave sits over the tray, in the thumb's reach.
+  if (small) og.ui.anchor("Call", { anchor: "bottom", offsetY: -112 }, () => callButton(world, g, small));
+  if (g.wave === 0 && !small) {
+    og.ui.anchor("Hint", { anchor: "bottom", padding: { left: theme.space.md, top: theme.space.xs, right: theme.space.md, bottom: theme.space.xs }, frame: "capsule", background: { token: "surface" }, radius: 999 }, () => {
+      og.ui.label("Text", say(world, "hud.hint"), { nowrap: true });
+    });
+  }
+}
+
+/** The next wave, early: shown in the break, with the seconds left (an early call pays them as coins). */
+function callButton(world: World, g: GameV, small: boolean): void {
+  if (g.inWave || g.wave >= WAVES.length) return;
+  const secs = Math.ceil(g.breakTicks / 60);
+  if (og.ui.button("Next", `${say(world, "hud.next")} ${secs}`, { variant: "secondary", size: small ? "medium" : "medium" }).clicked) g.callNext = true;
+}
+
+/** The settings dialog: volumes, language, motion; saved through og.platform when it closes. */
+function settings(world: World, theme: Theme, 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: theme.space.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 end card: won or lost, stars by the light left, the score counting up, the best, the round's numbers. */
+function endCard(world: World, theme: Theme, g: GameV, t: TuneV): "retry" | "menu" | null {
+  let chose: "retry" | "menu" | null = null;
+  const stars = !g.won ? 0 : g.lives >= t.startLives - 1 ? 3 : g.lives * 2 >= t.startLives ? 2 : 1;
+  const since = world.tick - g.overTick;
+  og.ui.modal("End", g.phase === Phase.Over, { title: say(world, g.won ? "over.won" : "over.lost"), locked: true, width: px(Math.min(400, og.ui.frameViewport().width - 32)) }, () => {
+    og.ui.row("Stars", { width: grow, align: "center", gap: theme.space.sm }, () => {
+      for (let k = 0; k < 3; k++) {
+        const lit = k < stars && since >= 20 + k * 12;
+        og.ui.transition(og.ui.idi("Star", k), true, { kind: "scale" }, () => {
+          og.ui.icon("Mark", "star", { size: 40, tint: { token: lit ? "accent" : "fillStrong" } });
+        });
+        if (lit && since === 20 + k * 12) og.ui.burst({ count: 10 });
+      }
+    });
+    og.ui.counter("Score", g.score, { from: 0, durationMs: 900, step: "displayMd", font: "display", align: "center", width: grow });
+    og.ui.row("BestRow", { width: grow, align: "center", gap: theme.space.sm, cross: "center" }, () => {
+      og.ui.label("Best", say(world, "over.best", { n: g.best }), { color: { token: "fgMuted" }, nowrap: true });
+      if (g.newBest) og.ui.transition("NewBest", since > 50, { kind: "pop" }, () => og.ui.badge("Badge", say(world, "over.newBest"), "accent"));
+    });
+    og.ui.column("Stats", { width: grow, gap: 0 }, () => {
+      og.ui.keyValue("Waves", say(world, "over.waves"), `${g.won ? g.wave : Math.max(0, g.wave - 1)}/${WAVES.length}`, true);
+      og.ui.keyValue("Kills", say(world, "over.kills"), `${g.kills}`, true);
+      og.ui.keyValue("Lives", say(world, "over.lives"), `${g.lives}/${t.startLives}`, true);
+    });
+    og.ui.row("Actions", { width: grow, gap: theme.space.sm }, () => {
+      if (og.ui.button("Retry", say(world, "over.retry"), { variant: "primary", width: grow }).clicked) chose = "retry";
+      if (og.ui.button("Menu", say(world, "over.menu"), { width: grow }).clicked) chose = "menu";
+    });
+  });
+  return chose;
+}
+
+/** The screens, the camera's framing, the buses, the platform's answers. */
+export const Ui = defineSystem("Ui", { reads: [Tuning], writes: [Game, Prefs, og.Camera, og.Audio], after: ["Visitors"] }, (_q, time, world) => {
+  const game = world.resource(Game);
+  const prefs = world.resource(Prefs);
+  if (!game.ok || !prefs.ok) return;
+  const g = game.value;
+  const t = lazyTuning(world);
+  const p = prefs.value;
+  platform(world, g, p);
+  if (time.tick === 0) applyPrefs(world, p);
+  frameCamera(world, g);
+  // Paused: the garden holds (time scale 0); playing: it runs at 1 (og-feel §3: never left below 1).
+  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;
+  }
+
+  const theme = THEME;
+  const screen = g.phase === Phase.Title ? "title" : g.phase === Phase.Play ? "play" : "over";
+  const shown = og.ui.screenTransition("Screens", screen, { kind: p.reducedMotion ? "fade" : "iris", 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") startRound(world, g, t);
+    if (r.selected === "settings") g.settingsOpen = true;
+  } else if (shown === "play") {
+    hud(world, theme, g, t);
+    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 = endCard(world, theme, g, t);
+    if (c === "retry") startRound(world, g, t);
+    if (c === "menu") g.phase = Phase.Title;
+  }
+  settings(world, theme, g, p);
+  if (g.language !== p.language) g.language = p.language;
+});

package/archetypes/tower-defense/tests/flow.og.ts

@@ -0,0 +1,56 @@
+// The core loop through real input: Play on the title, a hedge picked on
+// the tray and tapped onto the lawn (the tap also moves the cursor there),
+// two thorns set beside it with the keys (1, the arrows, Space), then the first wave: visitors come through the gate and
+// walk to the doorstep, the thorns see them (og.ai), shoot, and every
+// visitor turned away pays its bounty.
+import { playtest } from "@origingame/engine/playtest";
+import { game, PLAY, play, press, TITLE, tap, tapCell } from "./lib.ts";
+
+export default playtest({
+  name: "title, plants set by tap and by keys, the first wave walks in and is shot down",
+  commands: [
+    "0.3:screenshot:title.png",
+    "0.4:get:Game:title.json",
+    play(0.5),
+    tap("Plant#2/Pick", 1.3),
+    tapCell(4, 4, 1.5),
+    press("Digit1", 1.8),
+    press("ArrowLeft", 2.3),
+    press("Space", 2.4),
+    press("ArrowRight", 2.5),
+    press("ArrowRight", 2.6),
+    press("Space", 2.7),
+    "2.9:get:Game:set.json",
+    "2.95:screenshot:play.png",
+    "3.9:dump_entity:visitor-0:walker.json",
+    "4.2:dump_entity:visitor-0:walker2.json",
+    "8.0:screenshot:wave.png",
+    "13.0:get:Game:fought.json",
+    "13.1: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 set = game(run, "set.json");
+    t.equal(set.phase, PLAY, "Play started a round");
+    t.equal(set.placed, 3, "a hedge by tap and two thorns by keys");
+    t.equal(set.gold, 150 - 10 - 50 - 50, "each plant took its price");
+    t.equal(set.selected, 0, "1 picked the thorn back");
+    t.ok(set.cursorX === 5 && set.cursorY === 4, `the tap put the cursor on (4, 4) and the arrows walked it to (5, 4) (${set.cursorX}, ${set.cursorY})`);
+    t.equal(set.refused, 0, "nothing was refused");
+    const a = run.json<{ components: Record<string, { position?: number[]; seeking?: boolean }> }>("walker.json").components;
+    const b = run.json<{ components: Record<string, { position?: number[] }> }>("walker2.json").components;
+    t.equal(a["og.NavAgent"]!.seeking, true, "the first visitor walks the flow field");
+    const step = Math.hypot(b["og.Transform"]!.position![0]! - a["og.Transform"]!.position![0]!, b["og.Transform"]!.position![1]! - a["og.Transform"]!.position![1]!);
+    t.ok(step > 0.25 && step < 0.5, `it walks at a beetle's pace (${step.toFixed(2)} m in 0.3 s)`);
+    const fought = game(run, "fought.json");
+    t.equal(fought.wave, 1, "the first wave came");
+    t.ok(fought.shots >= 6, `the thorns shot at what they saw (${fought.shots} shots)`);
+    t.ok(fought.kills >= 3, `visitors were turned away (${fought.kills})`);
+    t.ok(fought.gold > set.gold, `bounties filled the purse (${set.gold} to ${fought.gold})`);
+    t.frame(["title.png", "play.png", "wave.png"], () => {
+      for (const f of ["title.png", "play.png", "wave.png"]) t.equal(run.png(f).width, 1280, `${f} is 1280 wide`);
+    });
+  },
+});

package/archetypes/tower-defense/tests/frames.og.ts

@@ -0,0 +1,31 @@
+// Three frames at 1280×720 compared with references/<tier>/: the title over
+// the garden, the first wave in a small maze (a thorn shooting, a frosted
+// visitor, the cursor and its range), and the won round's end card.
+// `OG_FX_CAPTURE=1 og test .` records this tier's references.
+import { playtest } from "@origingame/engine/playtest";
+import { checkFrames } from "./frames.ts";
+
+const FILES = ["title.png", "wave.png", "end.png"];
+
+export default playtest({
+  name: "the title, a wave in the maze and the end card match their reference frames",
+  size: "1280x720",
+  commands: [
+    "0.5:screenshot:title.png",
+    "0.6:begin",
+    "0.7:plant:hedge:4:4",
+    "0.7:plant:thorn:3:4",
+    "0.7:plant:frost:5:4",
+    "6.0:screenshot:wave.png",
+    "6.1:win",
+    "8.0:screenshot:end.png",
+    "8.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/tower-defense/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)`);
+    }
+  });
+}