@origingame/create-game 0.0.0-stage → 0.1.0

package/archetypes/rhythm/src/ui.ts

@@ -0,0 +1,421 @@
+// Three-Lane Beat's screens on og.ui and the skin in assets/skins/lanebeat
+// (the engine's sci-fi pack): the title, the HUD (the score and the groove
+// top left, Pause top right, the combo and its multiplier beside the
+// highway), the pause menu, the settings with the offset, the calibration
+// and the results. Screens change through a wipe (a fade with reduced
+// motion). Every string is a key of assets/strings/*.ogt.
+//
+// The Ui system also starts a play (the count-in, then bar 1), pauses it
+// (the band stops, the clock freezes) and resumes it on the beat it paused
+// on after a new count-in (the stems continue part-way), ends it with the results, and
+// keeps the settings and the best score in og.platform.
+
+import { og, defineSystem } from "@origingame/engine";
+import type { Value, World } from "@origingame/engine";
+import { Game, Phase, Prefs, Tuning } from "./components.ts";
+import { beatAt, beatLength, lazyTuning, must, worldTime } from "./systems.ts";
+
+export const LANGUAGES = [
+  { code: "en", key: "lang.en" },
+  { code: "zh-CN", key: "lang.zh" },
+] as const;
+
+/** 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, xl: 24 } 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 play: the counts cleared, the count-in from the next beat, then bar 1 (or `fromBar`). */
+export function begin(world: World, g: GameV, fromBar = 1): void {
+  const t = lazyTuning(world);
+  const len = beatLength(g);
+  const now = worldTime(world);
+  g.phase = Phase.Play;
+  g.paused = false;
+  g.pausedAt = -1;
+  g.score = 0;
+  g.combo = 0;
+  g.maxCombo = 0;
+  g.perfect = 0;
+  g.great = 0;
+  g.good = 0;
+  g.miss = 0;
+  g.hits = 0;
+  g.judged = 0;
+  g.taps = 0;
+  g.scheduled = 0;
+  g.groove = t.grooveStart;
+  g.failed = false;
+  g.cleared = false;
+  g.over = false;
+  g.endAt = 0;
+  g.newBest = false;
+  g.lastJudgement = -1;
+  g.countShown = -1;
+  g.resetNotes = true;
+  g.stopBand = true;
+  // The first bar starts countInBeats after the next whole tick: the clicks lead in.
+  const from = (Math.max(1, Math.min(g.bars, fromBar)) - 1) * 4;
+  g.fromBeat = from;
+  g.countTo = Math.ceil((now + 0.25) * 60) / 60 + t.countInBeats * len;
+  g.songStart = g.countTo - from * len;
+  g.bandFrom = from / 4 + 1;
+  g.bandBeat = from;
+  g.scheduleUpTo = from + t.scrollBeats + 1;
+}
+
+/** Pause: the clock freezes where it is, the band stops. */
+export function pause(world: World, g: GameV): void {
+  if (g.phase !== Phase.Play || g.paused || g.over) return;
+  g.paused = true;
+  g.pausedAt = worldTime(world);
+  g.stopBand = true;
+}
+
+/** Resume on the beat it was paused on, after a new count-in: the stems sounding then continue from where they were (AudioSource.startOffset). */
+export function resume(world: World, g: GameV): void {
+  if (!g.paused) return;
+  const t = lazyTuning(world);
+  const len = beatLength(g);
+  const from = Math.max(0, beatAt(g, g.pausedAt));
+  const now = worldTime(world);
+  const countTo = Math.ceil((now + 0.25) * 60) / 60 + t.countInBeats * len;
+  g.songStart = countTo - from * len;
+  g.countTo = countTo;
+  g.bandFrom = Math.floor(from / 4) + 1;
+  g.bandBeat = from;
+  g.scheduleUpTo = Math.ceil(from) + t.scrollBeats + 1;
+  g.countShown = -1;
+  g.paused = false;
+  g.pausedAt = -1;
+}
+
+/** Calibration: the clock clicks every beat from the next one; taps measure the offset. */
+export function calibrate(world: World, g: GameV): void {
+  g.phase = Phase.Calibrate;
+  g.calTaps = 0;
+  g.calSum = 0;
+  g.stopBand = true;
+  g.songStart = Math.ceil((worldTime(world) + 0.5) * 60) / 60;
+}
+
+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, offsetMs: p.offsetMs };
+}
+
+function saveSettings(world: World, p: PrefsV): void {
+  must(og.platform.saveSettings(world, prefsValue(p)));
+  p.saves += 1;
+}
+
+/** og.platform: the settings and the best score asked for on tick 0; the best written at the revision read. */
+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, "best");
+    g.bestRequest = 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;
+        if (typeof s.offsetMs === "number") p.offsetMs = s.offsetMs;
+        const at = LANGUAGES.findIndex((l) => l.code === s.language);
+        if (at >= 0) setLanguage(world, p, at);
+        applyPrefs(world, p);
+      }
+    }
+  }
+  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?: number | null; revision?: number } | null;
+      if (typeof d?.value === "number") g.best = Math.max(g.best, d.value);
+      if (typeof d?.revision === "number") g.bestRevision = d.revision;
+    }
+  }
+  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;
+    }
+  }
+}
+
+/** The play is over: the results, the best kept, the score on the board, the telemetry. */
+function finish(world: World, g: GameV): void {
+  g.phase = Phase.Results;
+  g.stopBand = true;
+  if (g.cleared && g.score > g.best) {
+    g.best = g.score;
+    g.newBest = true;
+    const w = og.platform.storeSet(world, { key: "best", value: g.score, revision: g.bestRevision });
+    if (w.ok) g.bestWrite = w.value;
+  }
+  if (g.cleared) must2(og.platform.leaderboardSubmit(world, { board: "neon-pulse", score: g.score }));
+  must(og.platform.telemetry(world, "song.over", { cleared: g.cleared, score: g.score, accuracy: accuracy(g), maxCombo: g.maxCombo, miss: g.miss }));
+}
+
+function must2(r: { ok: true } | { ok: false; reason: string }): void {
+  if (!r.ok) throw new Error(r.reason);
+}
+
+/** Accuracy, 0 to 100: a Perfect counts whole, a Great 70 %, a Good 40 %, a Miss nothing. */
+export function accuracy(g: GameV): number {
+  if (g.judged === 0) return 100;
+  return Math.round((1000 * (g.perfect + 0.7 * g.great + 0.4 * g.good)) / g.judged) / 10;
+}
+
+/** The grade of a cleared song by its accuracy. */
+export function grade(acc: number): string {
+  return acc >= 95 ? "S" : acc >= 85 ? "A" : acc >= 70 ? "B" : acc >= 50 ? "C" : "D";
+}
+
+function capsule(id: string, build: () => void): void {
+  og.ui.row(id, { gap: S.sm, 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 t = lazyTuning(world);
+  const vp = og.ui.frameViewport();
+  const phone = vp.width < vp.height;
+  // The pad and the arrows play the lanes; they move the focus only on the pause menu.
+  og.ui.setNavigation(g.paused || g.settingsOpen);
+  og.ui.anchor("Status", { anchor: "topLeft", direction: "column", gap: S.sm }, () => {
+    capsule("Score", () => {
+      og.ui.label("Label", say(world, "hud.score"), { step: "caption", color: { token: "fgMuted" }, nowrap: true });
+      og.ui.counter("Value", g.score, { step: "xl", font: "display", durationMs: 300, width: px(phone ? 104 : 130) });
+    });
+    capsule("Groove", () => {
+      og.ui.label("Label", say(world, "hud.groove"), { step: "caption", color: { token: "fgMuted" }, nowrap: true });
+      og.ui.meter("Bar", g.groove, 1, { kind: "health", width: px(phone ? 90 : 130) });
+    });
+  });
+  let paused = false;
+  og.ui.anchor("Corner", { anchor: "topRight" }, () => {
+    if (og.ui.actionButton("Pause", say(world, "hud.pause"), { icon: "pause", size: 48 }).clicked) paused = true;
+  });
+  if (paused) pause(world, g);
+  // The combo beside the highway (above it on a phone): the count and its multiplier's progress.
+  const multiplier = Math.min(4, 1 + Math.floor(g.combo / t.comboStep));
+  og.ui.anchor("Combo", { anchor: phone ? "top" : "right", offsetY: phone ? 64 : 40, offsetX: phone ? 0 : -48, direction: "column", cross: "center", gap: S.xxs }, () => {
+    og.ui.counter("Count", g.combo, { step: "displaySm", font: "display", durationMs: 120, align: "center", width: px(96) });
+    og.ui.row("Head", { gap: S.xs, cross: "center" }, () => {
+      og.ui.label("Label", say(world, "hud.combo"), { step: "caption", color: { token: "fgMuted" }, nowrap: true });
+      og.ui.label("Multiplier", say(world, "hud.multiplier", { n: multiplier }), { step: "caption", color: { token: "accent" }, nowrap: true });
+    });
+    og.ui.meter("Next", multiplier >= 4 ? 1 : (g.combo % t.comboStep) / t.comboStep, 1, { width: px(96) });
+  });
+}
+
+function settings(world: World, g: GameV, p: PrefsV): void {
+  let done = false;
+  let cal = false;
+  const before = JSON.stringify(prefsValue(p));
+  const m = og.ui.modal("Settings", g.settingsOpen, { title: say(world, "settings.title"), width: px(Math.min(440, og.ui.frameViewport().width - 32)) }, () => {
+    const slider = (id: string, key: string, value: number, min = 0, max = 1, step = 0.05, shown = (v: number) => `${Math.round(v * 100)}`): 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, { min, max, step }).value;
+        og.ui.label("Value", shown(out), { width: px(64), 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);
+    p.offsetMs = slider("Offset", "settings.offset", p.offsetMs, -200, 200, 5, (v) => say(world, "settings.ms", { n: Math.round(v) }));
+    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, gap: S.sm, align: "end" }, () => {
+      if (g.phase === Phase.Title && og.ui.button("Calibrate", say(world, "settings.calibrate")).clicked) cal = true;
+      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 || cal || m.dismissed)) {
+    g.settingsOpen = false;
+    saveSettings(world, p);
+    if (cal) calibrate(world, g);
+  }
+}
+
+/** The calibration: tap on the clicks; the mean error of eight taps is the offset. */
+function calibration(world: World, g: GameV, p: PrefsV): void {
+  let done = false;
+  let again = false;
+  const measured = g.calTaps > 0 ? g.calSum / g.calTaps : p.offsetMs;
+  const m = og.ui.modal("Calibration", true, { title: say(world, "cal.title"), width: px(Math.min(420, og.ui.frameViewport().width - 32)) }, () => {
+    og.ui.label("Body", say(world, "cal.body"), { width: grow });
+    og.ui.row("Taps", { width: grow, gap: S.md, cross: "center" }, () => {
+      og.ui.label("Count", say(world, "cal.taps", { n: g.calTaps }), { nowrap: true, width: grow });
+      og.ui.label("Offset", say(world, "cal.offset", { n: Math.round(measured) }), { font: "mono", nowrap: true, color: { token: "accent" } });
+    });
+    og.ui.meter("Progress", g.calTaps, 8, { width: grow });
+    og.ui.row("Actions", { width: grow, gap: S.sm, align: "end" }, () => {
+      if (og.ui.button("Again", say(world, "cal.reset")).clicked) again = true;
+      if (og.ui.button("Done", say(world, "cal.done"), { variant: "primary" }).clicked) done = true;
+    });
+  });
+  if (again) {
+    g.calTaps = 0;
+    g.calSum = 0;
+  }
+  if (done || m.dismissed) {
+    if (done && g.calTaps >= 4) {
+      p.offsetMs = Math.round(measured);
+      saveSettings(world, p);
+    }
+    g.phase = Phase.Title;
+    g.stopBand = true;
+  }
+}
+
+/** The results: cleared (with a grade) or failed, the counts, the best. */
+function results(world: World, g: GameV): "again" | "title" | null {
+  let chose: "again" | "title" | null = null;
+  const acc = accuracy(g);
+  og.ui.modal("Results", true, { title: say(world, g.cleared ? "results.cleared" : "results.failed"), locked: true, width: px(Math.min(420, og.ui.frameViewport().width - 32)) }, () => {
+    og.ui.row("Mark", { width: grow, align: "center", gap: S.md, cross: "center" }, () => {
+      og.ui.transition("Grade", true, { kind: "pop" }, () => og.ui.label("Letter", g.cleared ? grade(acc) : "–", { step: "displayMd", font: "display", color: { token: g.cleared ? "accent" : "fgMuted" } }));
+      if (g.newBest) og.ui.label("NewBest", say(world, "results.newBest"), { color: { token: "accent" }, nowrap: true });
+    });
+    og.ui.column("Stats", { width: grow, gap: 0 }, () => {
+      og.ui.keyValue("Score", say(world, "results.score"), `${g.score}`, true);
+      og.ui.keyValue("Accuracy", say(world, "results.accuracy"), say(world, "results.percent", { n: acc }), true);
+      og.ui.keyValue("Combo", say(world, "results.combo"), `${g.maxCombo}`, true);
+      og.ui.keyValue("Perfect", say(world, "results.perfect"), `${g.perfect}`, true);
+      og.ui.keyValue("Great", say(world, "results.great"), `${g.great}`, true);
+      og.ui.keyValue("Good", say(world, "results.good"), `${g.good}`, true);
+      og.ui.keyValue("Miss", say(world, "results.miss"), `${g.miss}`, true);
+    });
+    og.ui.label("Best", say(world, "results.best", { n: g.best }), { color: { token: "fgMuted" }, align: "center", width: grow });
+    og.ui.row("Actions", { width: grow, gap: S.sm }, () => {
+      if (og.ui.button("Again", say(world, "results.again"), { variant: "primary", width: grow }).clicked) chose = "again";
+      if (og.ui.button("Title", say(world, "results.title"), { width: grow }).clicked) chose = "title";
+    });
+  });
+  return chose;
+}
+
+/** The screens, the layout for the surface, the buses, the platform's answers, the play's start, pause and end. */
+export const Ui = defineSystem("Ui", { reads: [Tuning, og.Input, og.Gamepad], writes: [Game, Prefs, og.Camera, og.Audio] }, (_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 layout: 10 m tall and three 1.5 m lanes on a wide screen; 7.2 m across a portrait one with 2 m lanes.
+  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 portrait = vp.width < vp.height;
+    const height = portrait ? (7.2 * vp.height) / vp.width : 10;
+    const cam = world.resource(og.Camera);
+    if (cam.ok) cam.value.height = height;
+    g.laneW = portrait ? 2 : 1.5;
+    g.hitY = -height / 2 + (portrait ? 2.6 : 1.8);
+    g.topY = height / 2 - (portrait ? 2.4 : 0.2);
+  }
+  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 input = world.resource(og.Input);
+  const pad = world.resource(og.Gamepad);
+  if (g.phase === Phase.Play && !g.paused && input.ok && pad.ok && (input.value.pressed("Escape") || input.value.pressed("KeyP") || pad.value.pressed("start"))) pause(world, g);
+  if (g.phase === Phase.Play && g.over) finish(world, g);
+
+  const screen = g.phase === Phase.Title ? "title" : g.phase === Phase.Play ? "play" : g.phase === Phase.Results ? "results" : "calibrate";
+  const shown = og.ui.screenTransition("Screens", screen, { kind: p.reducedMotion ? "fade" : "wipe", durationMs: 500 }).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: "calibrate", label: say(world, "title.calibrate") },
+        { 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") begin(world, g);
+    if (!g.settingsOpen && r.selected === "calibrate") calibrate(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: "restart", label: say(world, "pause.restart") },
+        { id: "settings", label: say(world, "pause.settings") },
+        { id: "quit", label: say(world, "pause.quit") },
+      ],
+    });
+    if (m.selected === "resume") resume(world, g);
+    if (m.selected === "restart") begin(world, g);
+    if (m.selected === "settings") g.settingsOpen = true;
+    if (m.selected === "quit") {
+      g.paused = false;
+      g.pausedAt = -1;
+      g.phase = Phase.Title;
+      g.stopBand = true;
+    }
+  } else if (shown === "results") {
+    og.ui.setNavigation(true);
+    const c = results(world, g);
+    if (c === "again") begin(world, g);
+    if (c === "title") g.phase = Phase.Title;
+  } else {
+    og.ui.setNavigation(true);
+    calibration(world, g, p);
+  }
+  settings(world, g, p);
+  if (g.language !== p.language) g.language = p.language;
+});

package/archetypes/rhythm/tests/band.og.ts

@@ -0,0 +1,45 @@
+// The song on og.Music's clock: the count-in's four clicks are started at
+// the four beats before bar 1, the drums on bar 1's line, and every stem
+// after that on its own bar line from og.MusicBeat (the bass and the chords
+// at bar 5, the lead at bar 9), each to the sample (AudioSource.startAt
+// is the bar's exact world time); the notes come onto the highway beats
+// ahead of their time.
+import { playtest } from "@origingame/engine/playtest";
+import { game, songStart, sorted } from "./lib.ts";
+
+const t0 = songStart(1.0);
+const bar = (n: number) => t0 + (n - 1) * 2;
+
+interface Src { components: { "og.AudioSource": { startAt: number; playing: boolean }; Stem: { starts: number } } }
+
+export default playtest({
+  name: "the clicks, the drums and every stem start on their beats and bar lines",
+  commands: sorted([
+    // Nothing is pressed here, so the groove must not run out.
+    "0.9:set:Tuning.grooveLoss=0",
+    "1.0:play",
+    "1.15:dump_entity:stem-click0:click0.json",
+    "1.15:dump_entity:stem-click3:click3.json",
+    "1.15:dump_entity:stem-drums:drums1.json",
+    `${(bar(5) + 0.1).toFixed(3)}:dump_entity:stem-bass0:bass.json`,
+    `${(bar(5) + 0.1).toFixed(3)}:dump_entity:stem-chords0:chords.json`,
+    `${(bar(5) + 0.1).toFixed(3)}:dump_entity:stem-drums:drums5.json`,
+    `${(bar(9) + 0.1).toFixed(3)}:dump_entity:stem-leadA:lead.json`,
+    `${(bar(9) + 0.1).toFixed(3)}:get:Game:bar9.json`,
+    `${(bar(9) + 0.2).toFixed(3)}:quit`,
+  ]),
+  check(run, t) {
+    t.equal(run.warnings.join("; "), "", "the script ran without warnings");
+    const src = (f: string) => run.json<Src>(f).components["og.AudioSource"];
+    const near = (a: number, b: number) => Math.abs(a - b) < 1e-6;
+    t.ok(near(src("click0.json").startAt, t0 - 2), `the first click at ${(t0 - 2).toFixed(3)} s, four beats before bar 1`);
+    t.ok(near(src("click3.json").startAt, t0 - 0.5), "the fourth a beat before it");
+    t.ok(near(src("drums1.json").startAt, t0), `the drums on bar 1's line (${t0.toFixed(3)} s)`);
+    t.ok(near(src("bass.json").startAt, bar(5)) && src("bass.json").playing, `the bass on bar 5's line (${bar(5).toFixed(3)} s)`);
+    t.ok(near(src("chords.json").startAt, bar(5)), "the chords with it");
+    t.ok(near(src("drums5.json").startAt, bar(5)), "the drums restarted on bar 5's line too");
+    t.equal(run.json<Src>("drums5.json").components.Stem.starts, 5, "five bars, five starts of the one-bar drums");
+    t.ok(near(src("lead.json").startAt, bar(9)), `the lead on bar 9's line (${bar(9).toFixed(3)} s)`);
+    t.equal(game(run, "bar9.json").miss, game(run, "bar9.json").judged, "(nothing pressed: every note judged so far a Miss)");
+  },
+});

package/archetypes/rhythm/tests/calibrate.og.ts

@@ -0,0 +1,49 @@
+// Latency calibration: on the calibration screen the clock clicks every
+// beat; eight taps, each four ticks (67 ms) after its click, measure an
+// offset of 67 ms; Done saves it. Then a play whose every press is 67 ms
+// late is judged Perfect throughout, where without the offset each would
+// be a Great.
+import { playtest } from "@origingame/engine/playtest";
+import { BEAT, chart, game, type PlatformDump, play, press, songStart, sorted, tap, TITLE } from "./lib.ts";
+
+const notes = chart();
+/** The `calibrate` command at 1.0 s: clicks from the next whole tick half a second on, every beat. */
+const c0 = Math.ceil((1.0 + 0.5) * 60) / 60;
+const late = 4 / 60;
+const t0 = songStart(7.0);
+
+interface Src { components: { "og.AudioSource": { startAt: number } } }
+
+export default playtest({
+  name: "eight taps 67 ms late calibrate a 67 ms offset, and a late play is judged Perfect",
+  commands: sorted([
+    "1.0:calibrate",
+    ...Array.from({ length: 8 }, (_, k) => press("KeyS", c0 + (k + 1) * BEAT + late)),
+    `${(c0 + 2.1 * BEAT).toFixed(3)}:dump_entity:stem-click3:click.json`,
+    `${(c0 + 8.6 * BEAT).toFixed(3)}:get:Game:measured.json`,
+    `${(c0 + 8.6 * BEAT).toFixed(3)}:screenshot:calibrate.png`,
+    tap("Done", 5.9),
+    "6.5:get:Game:done.json",
+    "6.5:get:Prefs:prefs.json",
+    "6.5:dump_platform:platform.json",
+    "7.0:play",
+    ...play(notes, t0, 0, 8, late),
+    `${(t0 + 7.9 * BEAT).toFixed(3)}:get:Game:played.json`,
+    `${(t0 + 8 * BEAT).toFixed(3)}:quit`,
+  ]),
+  check(run, t) {
+    t.equal(run.warnings.join("; "), "", "the script ran without warnings");
+    const click = run.json<Src>("click.json").components["og.AudioSource"].startAt;
+    t.ok(Math.abs((click - c0) / BEAT - Math.round((click - c0) / BEAT)) < 1e-6, `the clicks are started on the beats (${click.toFixed(3)} s)`);
+    const m = game(run, "measured.json");
+    t.equal(m.calTaps, 8, "eight taps measured");
+    t.ok(Math.abs(m.calSum / 8 - late * 1000) < 0.5, `each ${(late * 1000).toFixed(1)} ms after its click (${(m.calSum / 8).toFixed(1)})`);
+    t.equal(game(run, "done.json").phase, TITLE, "Done went back to the title");
+    const prefs = run.json<{ value: { offsetMs: number } }>("prefs.json").value;
+    t.equal(prefs.offsetMs, 67, "the offset is 67 ms");
+    const pd = run.json<PlatformDump>("platform.json");
+    t.ok(pd.calls.some((c) => c.method === "store.set" && (c.args["value"] as { offsetMs?: number } | undefined)?.offsetMs === 67), "and was saved with the settings");
+    const p = game(run, "played.json");
+    t.equal(p.perfect, 8, "eight presses 67 ms late were all Perfect");
+  },
+});

package/archetypes/rhythm/tests/clear.og.ts

@@ -0,0 +1,51 @@
+// The song's end and its results: from bar 21 (`play:21`, the earlier
+// notes skipped) every note is hit on time, the last chord on all three
+// lanes; a beat and a half later the results: cleared, grade S, 100 %
+// accuracy, the score, the best kept at the revision read and submitted to
+// the board, the play reported; Play again starts over from bar 1.
+import { playtest } from "@origingame/engine/playtest";
+import { chart, game, PLAY, type PlatformDump, play, RESULTS, songStart, sorted, tap, text } from "./lib.ts";
+
+const notes = chart();
+const t0 = songStart(1.0, 21);
+const last = notes[notes.length - 1]!.beat;
+const end = t0 + last * 0.5;
+
+export default playtest({
+  name: "bar 21 to the end hit on time: cleared, grade S, the best kept and submitted, Play again",
+  commands: sorted([
+    "1.0:play:21",
+    ...play(notes, t0, 80, last + 1),
+    `${(end + 0.2).toFixed(3)}:get:Game:last.json`,
+    `${(end + 2.4).toFixed(3)}:get:Game:results.json`,
+    `${(end + 2.4).toFixed(3)}:dump_ui:results-ui.json`,
+    `${(end + 2.4).toFixed(3)}:dump_platform:platform.json`,
+    `${(end + 2.45).toFixed(3)}:screenshot:results.png`,
+    tap("Again", +(end + 2.6).toFixed(3)),
+    `${(end + 3.2).toFixed(3)}:get:Game:again.json`,
+    `${(end + 3.3).toFixed(3)}:quit`,
+  ]),
+  check(run, t) {
+    t.equal(run.warnings.join("; "), "", "the script ran without warnings");
+    const expected = notes.filter((n) => n.beat >= 80).length;
+    const l = game(run, "last.json");
+    t.equal(l.notes, expected, `bar 21 on holds ${expected} notes`);
+    t.equal(l.perfect, expected, "every one Perfect");
+    t.equal(l.cleared, true, "the song is cleared");
+    t.equal(l.phase, PLAY, "the results wait a beat and a half");
+    const r = game(run, "results.json");
+    t.equal(r.phase, RESULTS, "then the results");
+    t.equal(text(run, "results-ui.json", "Letter"), "S", "grade S");
+    t.equal(text(run, "results-ui.json", "Value", "Accuracy"), "100%", "100 % accuracy");
+    t.equal(text(run, "results-ui.json", "Value", "Score"), `${r.score}`, "the score");
+    t.equal(r.newBest, true, "a new best");
+    const p = run.json<PlatformDump>("platform.json");
+    const best = p.calls.find((c) => c.method === "store.set" && c.args["key"] === "best");
+    t.equal(best?.args["value"], r.score, "the best was written");
+    t.equal(best?.result?.ok, true, "at the revision read");
+    t.ok(p.calls.some((c) => c.method === "leaderboard.submit" && c.args["score"] === r.score), "and submitted to the board");
+    t.ok(p.calls.some((c) => c.method === "telemetry" && c.args["name"] === "song.over"), "the play was reported");
+    const a = game(run, "again.json");
+    t.ok(a.phase === PLAY && a.score === 0 && a.judged === 0 && a.notes === notes.length, "Play again started over from bar 1");
+  },
+});

package/archetypes/rhythm/tests/fail.og.ts

@@ -0,0 +1,40 @@
+// The failure path: nothing is pressed; every note let past drains the
+// groove a tenth; the fifth Miss empties it from its half: the song fails
+// (a falling tone, the band stops) and the results say so, without a
+// grade or a best.
+import { playtest } from "@origingame/engine/playtest";
+import { chart, game, PLAY, RESULTS, songStart, sorted, text } from "./lib.ts";
+
+const notes = chart();
+const t0 = songStart(1.0);
+const fifth = notes[4]!.beat;
+
+export default playtest({
+  name: "five notes let pass empty the groove: the song fails and the results say so",
+  commands: sorted([
+    "1.0:play",
+    `${(t0 + notes[2]!.beat * 0.5 + 0.2).toFixed(3)}:get:Game:three.json`,
+    `${(t0 + fifth * 0.5 + 0.2).toFixed(3)}:get:Game:failed.json`,
+    `${(t0 + fifth * 0.5 + 0.25).toFixed(3)}:dump_entity:stem-drums:drums.json`,
+    `${(t0 + fifth * 0.5 + 2.2).toFixed(3)}:get:Game:results.json`,
+    `${(t0 + fifth * 0.5 + 2.2).toFixed(3)}:dump_ui:results-ui.json`,
+    `${(t0 + fifth * 0.5 + 2.25).toFixed(3)}:screenshot:failed.png`,
+    `${(t0 + fifth * 0.5 + 2.3).toFixed(3)}:quit`,
+  ]),
+  check(run, t) {
+    t.equal(run.warnings.join("; "), "", "the script ran without warnings");
+    const three = game(run, "three.json");
+    t.equal(three.miss, 3, "three notes passed: three Misses");
+    t.ok(Math.abs(three.groove - 0.2) < 1e-4, `the groove fell from 0.5 to 0.2 (${three.groove.toFixed(3)})`);
+    t.equal(three.phase, PLAY, "still playing");
+    const f = game(run, "failed.json");
+    t.equal(f.failed, true, "the fifth Miss emptied the groove: failed");
+    t.equal(f.groove, 0, "the groove is empty");
+    t.equal(run.json<{ components: { "og.AudioSource": { playing: boolean } } }>("drums.json").components["og.AudioSource"].playing, false, "the band stopped");
+    const r = game(run, "results.json");
+    t.equal(r.phase, RESULTS, "the results came up");
+    t.equal(text(run, "results-ui.json", "Title", "Panel"), "The groove slipped away", "they say the groove slipped away");
+    t.equal(text(run, "results-ui.json", "Letter"), "–", "with no grade");
+    t.equal(r.newBest, false, "and no best");
+  },
+});

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

@@ -0,0 +1,54 @@
+// The core loop through real input: Play on the title starts the count-in
+// (four clicks, 4 3 2 1), then bar 1. The first two bars' eight notes are
+// hit with A S D on their times: eight Perfects, a combo of 8, 2,400
+// points, the groove rising. Bar 3's first note is hit 80 ms late (Great,
+// late), its second 120 ms early (Good, early), its third and fourth let
+// pass (two Misses, the combo broken); a press with no note near is only a
+// sound.
+import { playtest } from "@origingame/engine/playtest";
+import { BEAT, chart, game, KEYS, PLAY, play, press, songStart, sorted, tap, TITLE } from "./lib.ts";
+
+const notes = chart();
+const t0 = songStart(1.05);
+const bar3 = notes.filter((n) => n.beat >= 8 && n.beat < 12);
+
+export default playtest({
+  name: "Play, the count-in, perfect hits, a late Great, an early Good, misses and an empty press",
+  commands: sorted([
+    "0.3:get:Game:title.json",
+    tap("play", 1.0),
+    `${(t0 - 1.0).toFixed(3)}:get:Game:count.json`,
+    ...play(notes, t0, 0, 8),
+    `${(t0 + 7.8 * BEAT).toFixed(3)}:get:Game:perfect.json`,
+    `${(t0 + 7.8 * BEAT).toFixed(3)}:screenshot:play.png`,
+    press(KEYS[bar3[0]!.lane]!, t0 + bar3[0]!.beat * BEAT + 0.08),
+    press(KEYS[bar3[1]!.lane]!, t0 + bar3[1]!.beat * BEAT - 0.12),
+    `${(t0 + 9.6 * BEAT).toFixed(3)}:get:Game:early.json`,
+    press("KeyS", t0 + 10.5 * BEAT),
+    `${(t0 + 11.6 * BEAT).toFixed(3)}:get:Game:missed.json`,
+    `${(t0 + 11.7 * BEAT).toFixed(3)}:quit`,
+  ]),
+  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 count = game(run, "count.json");
+    t.equal(count.phase, PLAY, "Play started the count-in");
+    t.ok(Math.abs(count.songStart - t0) < 1e-6, `bar 1 starts at ${t0.toFixed(3)} s, four beats after the next tick`);
+    const p = game(run, "perfect.json");
+    t.equal(p.perfect, 8, "the first two bars' eight notes were Perfect");
+    t.equal(p.combo, 8, "a combo of 8");
+    t.equal(p.score, 8 * 300, "300 each at ×1");
+    t.ok(p.groove > 0.5, `the groove rose (${p.groove.toFixed(2)})`);
+    const e = game(run, "early.json");
+    t.equal(e.great, 1, "80 ms late was Great");
+    t.equal(e.good, 1, "120 ms early was Good");
+    t.equal(e.combo, 10, "the combo went on: 10");
+    const m = game(run, "missed.json");
+    t.equal(m.miss, 2, "the two notes let pass were Misses");
+    t.equal(m.combo, 0, "the combo broke");
+    t.equal(m.judged, 12, "twelve notes judged; the empty press judged nothing");
+    t.equal(m.taps, 11, "eleven presses heard");
+    t.frame("play.png", () => t.equal(run.png("play.png").width, 1280, "play.png captured"));
+  },
+});