@origingame/engine 0.0.0-stage → 0.1.0

package/src/ui-kit/huds.ts

@@ -0,0 +1,303 @@
+// HUDs: platformer, shooter, puzzle, idle/incremental and racing, each a
+// set of anchored groups over the game in the safe area, plus the touch
+// controls they show on phones and tablets. HUDs turn keyboard and gamepad
+// navigation off (the keys move the player); Back still answers `paused`,
+// except under an open dialog, which keeps it (og.ui.back).
+
+import type * as Api from "@origingame/engine";
+import { kit } from "./bind.ts";
+import { all, capsule, clock, fit, fmt, frame, grow, iconOr, lapTime, px, token } from "./util.ts";
+
+type Hud = { paused: boolean; action: string | null; moveX: number; moveY: number; held: string[] };
+
+function hud(): Hud {
+  kit.setNavigation(false);
+  return { paused: kit.back(), action: null, moveX: 0, moveY: 0, held: [] };
+}
+
+function pauseButton(out: Hud, label = "Pause"): void {
+  const r = kit.actionButton("Pause", label, { size: 44, icon: "pause" });
+  if (r.clicked) out.paused = true;
+}
+
+/** A big number with a small caption under it. */
+function stat(id: string, value: string, caption: string, step: Api.TypeStepName = "xl3", align: Api.TextAlign = "start"): void {
+  kit.column(id, { gap: 0, cross: align === "end" ? "end" : align === "center" ? "center" : "start" }, () => {
+    kit.label("Value", value, { step, font: "mono", nowrap: true, align });
+    kit.label("Caption", caption, { step: "meta", color: token("fgMuted"), nowrap: true, align });
+  });
+}
+
+/** Touch controls: a d-pad or a stick bottom left, action buttons bottom right. */
+function touchControls(out: Hud, desc: { dpad?: boolean; buttons: ReadonlyArray<{ id: string; label: string; primary?: boolean; icon?: string }> }): void {
+  const { t } = frame();
+  kit.anchor("TouchMove", { anchor: "bottomLeft" }, () => {
+    if (desc.dpad) {
+      const d = kit.dpad("Dpad", {});
+      out.moveX = (d.right ? 1 : 0) - (d.left ? 1 : 0);
+      out.moveY = (d.down ? 1 : 0) - (d.up ? 1 : 0);
+    } else {
+      const j = kit.joystick("Stick", {});
+      out.moveX = j.x;
+      out.moveY = j.y;
+    }
+  });
+  kit.anchor("TouchActions", { anchor: "bottomRight", gap: t.md, cross: "end" }, () => {
+    for (const b of desc.buttons) {
+      const r = kit.actionButton(b.id, b.label, { primary: b.primary ?? false, icon: b.icon ?? "", size: b.primary ? 76 : 60 });
+      if (r.pressed) out.held.push(b.id);
+      if (r.clicked) out.action = b.id;
+    }
+  });
+}
+
+export function platformerHud(id: string, desc: Api.PlatformerHudDesc = {}): Api.HudResult {
+  const { t, touch } = frame();
+  const out = hud();
+  // What the game leaves out is not drawn: no hearts with maxLives 0 (and
+  // no health bar), no coins or score capsule without coins or score.
+  const health = desc.health ?? null;
+  const maxLives = desc.maxLives ?? 3;
+  const coins = desc.coins ?? null;
+  const score = desc.score ?? null;
+  if (health !== null || maxLives > 0 || desc.level) {
+    kit.anchor(`${id}.left`, { anchor: "topLeft", direction: "column", gap: t.sm }, () => {
+      if (health !== null) capsule("Lives", () => kit.meter("Health", health, 1, { width: px(120) }));
+      else if (maxLives > 0) {
+        capsule("Lives", () => {
+          for (let i = 0; i < maxLives; i++) iconOr(kit.idi("Life", i), "heart", 20, token(i < (desc.lives ?? 0) ? "danger" : "fillStrong"));
+        });
+      }
+      if (desc.level) kit.label("Level", desc.level, { step: "meta", color: token("fgMuted"), nowrap: true });
+    });
+  }
+  if (desc.timeLeft !== null && desc.timeLeft !== undefined) {
+    const low = desc.timeLeft <= 10;
+    kit.anchor(`${id}.top`, { anchor: "top" }, () => {
+      capsule("Timer", () => kit.label("Time", clock(desc.timeLeft!), { step: "lg", font: "mono", color: token(low ? "danger" : "fg"), nowrap: true }));
+    });
+  }
+  kit.anchor(`${id}.right`, { anchor: "topRight", gap: t.sm, cross: "center" }, () => {
+    if (coins !== null) {
+      capsule("Coins", () => {
+        iconOr("Coin", "coin", 20, token("accent"));
+        kit.label("Count", fmt(coins), { font: "mono", nowrap: true });
+      });
+    }
+    if (score !== null) capsule("Score", () => kit.label("Points", fmt(score), { font: "mono", nowrap: true }));
+    pauseButton(out);
+  });
+  if ((desc.touch ?? false) && touch) touchControls(out, { dpad: true, buttons: [{ id: "jump", label: "Jump", primary: true }] });
+  return out;
+}
+
+/** A crosshair at the centre: four short strokes and a gap. */
+function crosshair(): void {
+  const ink = token("fg", 0.9);
+  const bar = (id: string, w: number, h: number): void => kit.image(id, { tint: ink, width: px(w), height: px(h) });
+  kit.anchor("Crosshair", { anchor: "center", direction: "column", cross: "center", gap: 6 }, () => {
+    bar("N", 2, 8);
+    kit.row("Mid", { gap: 14, cross: "center" }, () => {
+      bar("W", 8, 2);
+      bar("E", 8, 2);
+    });
+    bar("S", 2, 8);
+  });
+}
+
+export function shooterHud(id: string, desc: Api.ShooterHudDesc = {}): Api.HudResult {
+  const { t, touch } = frame();
+  const out = hud();
+  const showTouch = (desc.touch ?? false) && touch;
+  const maxHealth = desc.maxHealth ?? 100;
+  const health = desc.health ?? 0;
+  // Vitals sit bottom left, or top left when the stick takes that corner.
+  kit.anchor(`${id}.vitals`, { anchor: showTouch ? "topLeft" : "bottomLeft", direction: "column", gap: t.xs, width: px(240) }, () => {
+    kit.meter("Health", health, maxHealth, { kind: "health", label: `${Math.ceil(health)}`, width: grow() });
+    if ((desc.maxArmor ?? 0) > 0) kit.meter("Armor", desc.armor ?? 0, desc.maxArmor!, { color: token("info"), label: `${Math.ceil(desc.armor ?? 0)}`, width: grow() });
+  });
+  if (desc.map && !showTouch) kit.anchor(`${id}.map`, { anchor: "topLeft" }, () => kit.minimap("Map", desc.map!));
+  kit.anchor(`${id}.top`, { anchor: "topRight", gap: t.sm, cross: "center" }, () => {
+    capsule("Kills", () => {
+      kit.label("Count", fmt(desc.kills ?? 0), { font: "mono", nowrap: true });
+      kit.label("Unit", "kills", { step: "meta", color: token("fgMuted"), nowrap: true });
+    });
+    pauseButton(out);
+  });
+ kit.anchor(`${id}.ammo`, { anchor: showTouch ? "topRight" : "bottomRight", offsetY: showTouch ? 56 : 0, direction: "column", cross: "end", gap: t.xs }, () => {
+    const mag = desc.magazine ?? 0;
+    const ammo = desc.ammo ?? 0;
+    kit.row("Rounds", { gap: t.xs, cross: "end" }, () => {
+      kit.label("Ammo", `${ammo}`, { step: "xl5", font: "mono", color: token(mag > 0 && ammo <= Math.floor(mag / 4) ? "warn" : "fg"), nowrap: true });
+      kit.label("Reserve", `/ ${desc.reserve ?? 0}`, { step: "lg", font: "mono", color: token("fgMuted"), nowrap: true });
+    });
+    if (desc.weapon) kit.label("Weapon", desc.weapon, { step: "meta", color: token("fgMuted"), nowrap: true });
+  });
+  const abilities = desc.abilities ?? [];
+  if (abilities.length > 0) {
+    // Above the touch controls when they show, else along the bottom edge.
+    kit.anchor(`${id}.abilities`, showTouch ? { anchor: "right", direction: "column", gap: t.md, offsetY: 120 } : { anchor: "bottom", gap: t.md }, () => {
+      abilities.forEach((a, i) => {
+        const r = kit.cooldown(a.id ?? kit.idi("Ability", i), a.remaining ?? 0, { label: a.key ?? "", icon: a.icon ?? "", size: 56 });
+        if (r.clicked) out.action = a.id ?? `ability${i}`;
+      });
+    });
+  }
+  if (desc.crosshair ?? true) crosshair();
+  if (showTouch) touchControls(out, { buttons: [{ id: "fire", label: "Fire", primary: true }] });
+  return out;
+}
+
+export function puzzleHud(id: string, desc: Api.PuzzleHudDesc = {}): Api.HudResult {
+  const { t } = frame();
+  const out = hud();
+  const target = Math.max(1, desc.target ?? 1000);
+  const score = desc.score ?? 0;
+  const marks = desc.stars && desc.stars.length > 0 ? desc.stars : [Math.round(target / 3), Math.round((2 * target) / 3), target];
+  kit.anchor(`${id}.left`, { anchor: "topLeft", direction: "column", gap: t.xs }, () => {
+    if (desc.level) kit.label("Level", desc.level, { step: "meta", color: token("fgMuted"), nowrap: true });
+    if (desc.moves !== null && desc.moves !== undefined) stat("Moves", `${desc.moves}`, "moves left", "xl3");
+  });
+  kit.anchor(`${id}.score`, { anchor: "top", direction: "column", cross: "center", gap: t.xs, width: px(260) }, () => {
+    kit.label("Score", fmt(score), { step: "displaySm", font: "display", align: "center", width: grow() });
+    kit.meter("Progress", score, target, { kind: "accent", width: grow(), segments: 3 });
+    kit.row("Stars", { gap: t.sm, cross: "center" }, () => {
+      marks.slice(0, 3).forEach((m, i) => iconOr(kit.idi("Star", i), "star", 20, token(score >= m ? "accent" : "fillStrong")));
+      kit.label("Target", `Target ${fmt(target)}`, { step: "meta", color: token("fgMuted"), nowrap: true });
+    });
+  });
+  kit.anchor(`${id}.right`, { anchor: "topRight", gap: t.sm, cross: "center" }, () => {
+    if (desc.timeLeft !== null && desc.timeLeft !== undefined) {
+      capsule("Timer", () => kit.label("Time", clock(desc.timeLeft!), { font: "mono", color: token(desc.timeLeft! <= 10 ? "danger" : "fg"), nowrap: true }));
+    }
+    pauseButton(out);
+  });
+  return out;
+}
+
+export function idleHud(id: string, desc: Api.IdleHudDesc = {}): Api.HudResult {
+  const { t, phone } = frame();
+  const out = hud();
+  const currencies = desc.currencies ?? [];
+  const generators = desc.generators ?? [];
+  kit.anchor(`${id}.wallet`, { anchor: "top", gap: t.sm, cross: "center" }, () => {
+    currencies.forEach((c, i) => {
+      capsule(c.id ?? kit.idi("Currency", i), () => {
+        if (c.icon) iconOr("Icon", c.icon, 20, token("accent"));
+        kit.label("Amount", fmt(c.amount ?? 0), { step: i === 0 ? "lg" : "body", font: "mono", nowrap: true });
+        if ((c.perSecond ?? 0) !== 0) kit.label("Rate", `+${fmt(c.perSecond ?? 0)}/s`, { step: "meta", color: token("success"), nowrap: true });
+      }, { height: i === 0 ? t.controlLg : t.controlMd });
+    });
+    pauseButton(out);
+  });
+  if (desc.tapLabel !== "") {
+    kit.anchor(`${id}.tap`, { anchor: phone ? "top" : "center", offsetY: phone ? 96 : 0, offsetX: phone ? 0 : -150 }, () => {
+      const r = kit.actionButton("Tap", desc.tapLabel ?? "Tap", { primary: true, size: phone ? 120 : 160 });
+      if (r.clicked) out.action = "tap";
+    });
+  }
+  const listHeight = phone ? Math.min(320, frame().viewport.height * 0.45) : Math.min(420, frame().viewport.height - 160);
+  kit.anchor(`${id}.shop`, { anchor: phone ? "bottom" : "right", width: phone ? grow() : px(340) }, () => {
+    kit.panel("Generators", { width: grow(), padding: all(t.sm), gap: t.xs }, () => {
+      kit.list("List", { count: generators.length, rowHeight: 64, gap: t.xs, height: fit(0, listHeight), width: grow() }, (i) => {
+        const g = generators[i]!;
+        if (g.icon) iconOr("Icon", g.icon, 32, token("fg"));
+        kit.column("Text", { width: grow(), gap: t.xxs }, () => {
+          kit.row("Head", { gap: t.sm, cross: "center", width: grow() }, () => {
+            kit.label("Name", g.name ?? g.id ?? "", { step: "lg", nowrap: true, width: grow() });
+            kit.badge("Level", `Lv ${g.level ?? 0}`, "neutral");
+          });
+          kit.meter("Cycle", g.progress ?? 0, 1, { kind: "accent", height: 4, width: grow() });
+        });
+        const buy = kit.button("Buy", fmt(g.cost ?? 0), { size: "small", variant: g.affordable ? "primary" : "secondary", disabled: !g.affordable }) as Api.Response;
+        if (buy.clicked) out.action = `buy:${g.id ?? i}`;
+      });
+    });
+  });
+  return out;
+}
+
+/** A delta in seconds, signed with the ASCII minus every pack's charset holds: `-0.412`, `+1.050`. */
+function deltaText(seconds: number): string {
+  const a = Math.abs(seconds);
+  const body = a >= 60 ? lapTime(a) : a.toFixed(3);
+  return `${seconds < 0 ? "-" : "+"}${body}`;
+}
+
+/** A delta's ink: ahead (negative) success, behind danger, even muted. */
+function deltaInk(seconds: number): Api.Paint {
+  return token(seconds < 0 ? "success" : seconds > 0 ? "danger" : "fgMuted");
+}
+
+export function racingHud(id: string, desc: Api.RacingHudDesc = {}): Api.HudResult {
+  const { t, touch, phone } = frame();
+  const out = hud();
+  const showTouch = (desc.touch ?? false) && touch;
+  const racers = desc.racers ?? 8;
+  const boost = (desc.boostMeter ?? true) ? (desc.boost ?? 0) : null;
+  const boostLabel = desc.boostLabel ?? "Boost";
+  kit.anchor(`${id}.place`, { anchor: "topLeft", gap: t.lg }, () => {
+    // A time trial (racers 0) has no place.
+    if (racers > 0) {
+      kit.row("Position", { gap: t.xxs, cross: "end" }, () => {
+        kit.label("Place", `${desc.position ?? 1}`, { step: "displayXl", font: "display", nowrap: true });
+        kit.label("Of", `/${racers}`, { step: "xl", font: "mono", color: token("fgMuted"), nowrap: true });
+      });
+    }
+    stat("Lap", `${Math.min(desc.lap ?? 1, desc.laps ?? 3)}/${desc.laps ?? 3}`, desc.lapLabel ?? "lap", "xl3");
+  });
+  kit.anchor(`${id}.times`, { anchor: "topRight", direction: "column", cross: "end", gap: t.xxs }, () => {
+    kit.row("Top", { gap: t.sm, cross: "center" }, () => {
+      kit.label("Time", clock(desc.time ?? 0, true), { step: "xl", font: "mono", nowrap: true });
+      pauseButton(out, desc.pauseLabel ?? "Pause");
+    });
+    const delta = desc.delta ?? null;
+    if (delta !== null) kit.label("Delta", deltaText(delta), { step: "lg", font: "mono", color: deltaInk(delta), nowrap: true });
+    if (desc.best !== null && desc.best !== undefined) {
+      kit.label("Best", (desc.bestLabel ?? "Best {best}").replaceAll("{best}", clock(desc.best, true)), { step: "meta", font: "mono", color: token("fgMuted"), nowrap: true });
+    }
+    const splits = desc.splits ?? [];
+    if (splits.length > 0) {
+      kit.column("Splits", { gap: 0, cross: "end" }, () => {
+        splits.forEach((sp, i) => {
+          kit.row(kit.idi("Split", i), { gap: t.sm, cross: "center" }, () => {
+            kit.label("Label", sp.label ?? "", { step: "meta", color: token("fgMuted"), nowrap: true });
+            const time = sp.time ?? null;
+            kit.label("Time", time === null ? "-:--.---" : lapTime(time), { step: "meta", font: "mono", color: token(time === null ? "fgSubtle" : "fg"), nowrap: true });
+            const d = sp.delta ?? null;
+            if (d !== null) kit.label("Delta", deltaText(d), { step: "meta", font: "mono", color: deltaInk(d), nowrap: true });
+          });
+        });
+      });
+    }
+    if (desc.map) kit.minimap("Map", { ...desc.map, size: phone ? 112 : (desc.map.size ?? 140) });
+  });
+  kit.anchor(`${id}.dash`, { anchor: showTouch ? "bottom" : "bottomRight", offsetY: showTouch ? -120 : 0, direction: "column", cross: "end", gap: t.xs, width: px(220) }, () => {
+    kit.row("Speed", { gap: t.sm, cross: "end", width: grow(), align: "end" }, () => {
+      kit.label("Value", `${Math.round(desc.speed ?? 0)}`, { step: "displayXl2", font: "display", nowrap: true });
+      kit.column("Side", { cross: "end" }, () => {
+        kit.label("Gear", desc.gear ?? "N", { step: "xl", font: "mono", color: token("accentInk"), nowrap: true });
+        kit.label("Unit", desc.unit ?? "km/h", { step: "meta", color: token("fgMuted"), nowrap: true });
+      });
+    });
+    kit.meter("Rev", desc.speed ?? 0, desc.maxSpeed ?? 300, { kind: "accent", width: grow(), height: 6 });
+    if (boost !== null) kit.meter("Boost", boost, 1, { color: token("info"), label: boostLabel, width: grow(), segments: 4 });
+  });
+  if (showTouch) {
+    kit.anchor("Steer", { anchor: "bottomLeft", gap: t.md }, () => {
+      const l = kit.actionButton("left", desc.leftLabel ?? "Left", { size: 72 });
+      const r = kit.actionButton("right", desc.rightLabel ?? "Right", { size: 72 });
+      out.moveX = (r.pressed ? 1 : 0) - (l.pressed ? 1 : 0);
+    });
+    kit.anchor("Pedals", { anchor: "bottomRight", gap: t.md, cross: "end" }, () => {
+      const pedals = [{ id: "brake", label: desc.brakeLabel ?? "Brake", primary: false }];
+      if (boost !== null) pedals.push({ id: "boost", label: boostLabel, primary: true });
+      for (const b of pedals) {
+        const r = kit.actionButton(b.id, b.label, { primary: b.primary, size: b.primary ? 84 : 64 });
+        if (r.pressed) out.held.push(b.id);
+        if (r.clicked) out.action = b.id;
+      }
+    });
+  }
+  return out;
+}

package/src/ui-kit/index.ts

@@ -0,0 +1,36 @@
+// The UI kit: og.ui's game widget set (host calls and their callback sugar)
+// and the screen templates, merged into og.ui by the package entry. Every
+// member is declared in crates/og-api/api.ogt (module `ui`); the templates
+// are `host false` functions written here over the calls.
+
+import { widgets } from "./bind.ts";
+import { platformerHud, shooterHud, puzzleHud, idleHud, racingHud } from "./huds.ts";
+import { alertDialog, confirmDialog, loadingScreen, mainMenu, pauseMenu, resultsScreen } from "./menus.ts";
+import { settingsScreen } from "./settings.ts";
+import { inventoryScreen, leaderboardScreen, levelSelect, shopScreen } from "./store.ts";
+import { cutscene, tutorialOverlay } from "./story.ts";
+
+export { settingsWithDefaults } from "./settings.ts";
+export { fmt, clock } from "./util.ts";
+
+export const uiKit = Object.freeze({
+  ...widgets,
+  mainMenu,
+  pauseMenu,
+  settingsScreen,
+  platformerHud,
+  shooterHud,
+  puzzleHud,
+  idleHud,
+  racingHud,
+  cutscene,
+  shopScreen,
+  inventoryScreen,
+  levelSelect,
+  resultsScreen,
+  leaderboardScreen,
+  tutorialOverlay,
+  loadingScreen,
+  confirmDialog,
+  alertDialog,
+});

package/src/ui-kit/menus.ts

@@ -0,0 +1,187 @@
+// Menus and dialogs: the title screen, pause, confirm, alert, loading and
+// results. Each is one call per tick: data in, what happened out.
+
+import type * as Api from "@origingame/engine";
+import { kit } from "./bind.ts";
+import { all, clock, fmt, frame, iconOr, lapTime, menuItems, px, grow, token } from "./util.ts";
+
+/** The buttons of a menu in a column; answers the chosen id. With `autofocus` its first enabled item takes the focus when the menu appears (og-ui §4: what opens takes the focus). */
+function menuColumn(id: string, items: ReturnType<typeof menuItems>, width: Api.Size, autofocus = false): string | null {
+  const { t } = frame();
+  let chosen: string | null = null;
+  const first = autofocus ? items.findIndex((i) => !i.disabled) : -1;
+  kit.column(id, { width, gap: t.sm, cross: "stretch" }, () => {
+    items.forEach((item, k) => {
+      const r = kit.button(item.id, item.label, {
+        variant: item.primary ? "primary" : "secondary",
+        size: "large",
+        disabled: item.disabled,
+        width: grow(),
+        autofocus: k === first,
+      }) as Api.Response;
+      if (r.clicked) chosen = item.id;
+    });
+  });
+  return chosen;
+}
+
+export function mainMenu(id: string, desc: Api.MainMenuDesc = {}): Api.MenuResult {
+  const { t, phone } = frame();
+  const items = menuItems(desc.items, [["play", "Play"]]);
+  let chosen: string | null = null;
+  kit.anchor(id, {
+    anchor: phone ? "bottom" : "center",
+    direction: "column",
+    gap: t.xl,
+    cross: "center",
+    width: phone ? grow() : px(380),
+    padding: all(phone ? t.lg : t.xl),
+    background: token("materialThick"),
+    radius: t.panel,
+    instant: desc.instant ?? false,
+  }, () => {
+    kit.column("Heading", { gap: t.xs, cross: "center", width: grow() }, () => {
+      kit.label("Title", desc.title ?? "", { step: phone ? "displayMd" : "displayLg", font: "display", align: "center", width: grow(), heading: true });
+      if (desc.subtitle) kit.label("Subtitle", desc.subtitle, { color: token("fgMuted"), align: "center", width: grow() });
+    });
+    // A title menu is not a dialog, so it takes the focus itself: Enter and the pad's A answer at once.
+    chosen = menuColumn("Items", items, grow(), true);
+    if (desc.footer) kit.label("Footer", desc.footer, { step: "meta", color: token("fgSubtle"), align: "center", width: grow() });
+  });
+  if (chosen !== null) desc.onSelect?.(chosen);
+  return { selected: chosen };
+}
+
+export function pauseMenu(id: string, desc: Api.PauseMenuDesc = {}): Api.MenuResult {
+  const items = menuItems(desc.items, [["resume", "Resume"], ["settings", "Settings"], ["quit", "Quit to menu"]]);
+  let chosen: string | null = null;
+  const m = kit.modal(id, desc.open ?? false, { title: desc.title ?? "Paused", width: px(Math.min(340, frame().viewport.width - 32)) }, () => {
+    chosen = menuColumn("Items", items, grow());
+  });
+  if (m.dismissed) chosen = "resume";
+  if (chosen !== null) desc.onSelect?.(chosen);
+  return { selected: chosen };
+}
+
+export function confirmDialog(id: string, desc: Api.ConfirmDesc = {}): Api.ConfirmResult {
+  const { t } = frame();
+  let confirmed = false;
+  let cancelled = false;
+  const m = kit.modal(id, desc.open ?? false, { title: desc.title ?? "" }, () => {
+    if (desc.message) kit.richText("Message", desc.message, { step: "reading", color: token("fgMuted"), width: grow() });
+    kit.row("Actions", { width: grow(), gap: t.sm, align: "end", padding: { left: 0, top: t.sm, right: 0, bottom: 0 } }, () => {
+      if ((kit.button("Cancel", desc.cancelLabel ?? "Cancel", {}) as Api.Response).clicked) cancelled = true;
+      if ((kit.button("Confirm", desc.confirmLabel ?? "Confirm", { variant: desc.danger ? "danger" : "primary" }) as Api.Response).clicked) confirmed = true;
+    });
+  });
+  if (m.dismissed) cancelled = true;
+  return { confirmed, cancelled };
+}
+
+export function alertDialog(id: string, desc: Api.AlertDesc = {}): boolean {
+  const { t } = frame();
+  let done = false;
+  const m = kit.modal(id, desc.open ?? false, { title: desc.title ?? "" }, () => {
+    if (desc.message) kit.richText("Message", desc.message, { step: "reading", color: token("fgMuted"), width: grow() });
+    kit.row("Actions", { width: grow(), align: "end", padding: { left: 0, top: t.sm, right: 0, bottom: 0 } }, () => {
+      if ((kit.button("Ok", desc.okLabel ?? "OK", { variant: "primary" }) as Api.Response).clicked) done = true;
+    });
+  });
+  return done || m.dismissed;
+}
+
+export function loadingScreen(id: string, desc: Api.LoadingDesc = {}): void {
+  const { t } = frame();
+  const tips = desc.tips ?? [];
+  const tip = tips.length > 0 ? tips[Math.floor(kit.seconds() / Math.max(1, desc.tipSeconds ?? 4)) % tips.length]! : "";
+  kit.modal(id, true, { locked: true, bare: true, backdrop: token("bg"), transition: "fade", width: px(Math.min(380, frame().viewport.width - 32)) }, () => {
+    kit.label("Title", desc.title ?? "Loading", { step: "xl", align: "center", width: grow(), heading: true });
+    const p = desc.progress;
+    if (p === null || p === undefined) {
+      kit.spinner("Spinner", 0);
+    } else {
+      // A real value only: the bar never runs ahead of what loaded.
+      kit.row("Bar", { width: grow(), gap: t.md, cross: "center" }, () => {
+        kit.progress("Progress", p, { width: grow() });
+        kit.label("Percent", `${Math.floor(Math.max(0, Math.min(1, p)) * 100)}%`, { step: "meta", font: "mono", color: token("fgMuted"), nowrap: true });
+      });
+    }
+    if (tip) kit.label("Tip", tip, { step: "reading", color: token("fgMuted"), align: "center", width: grow() });
+  });
+}
+
+/** Stars landing one by one: k appears 0.3 s after k-1, from the screen's opening; an earned one bursts. */
+function stars(id: string, earned: number, max: number, since: number, size: number): void {
+  const { t } = frame();
+  kit.row(id, { gap: t.sm, cross: "center" }, () => {
+    for (let k = 0; k < max; k++) {
+      const shown = kit.seconds() - since >= 0.3 * (k + 1);
+      const on = k < earned;
+      kit.transition(kit.idi("Star", k), shown, { kind: "scale", instant: false }, () => {
+        iconOr("Mark", "star", size, token(on ? "accent" : "fillStrong"));
+        if (on) kit.burst({ delayMs: 120 });
+      });
+      if (!shown) kit.spacer(kit.idi("Gap", k), px(size));
+    }
+  });
+}
+
+export function resultsScreen(id: string, desc: Api.ResultsDesc = {}): Api.MenuResult {
+  const { t, phone } = frame();
+  const open = desc.open ?? false;
+  // When it opened, in UI seconds (-1 while closed): the count-up and the stars run from there.
+  let since = kit.memory(`${id}.since`, -1);
+  if (!open) since = -1;
+  else if (since < 0) since = kit.seconds();
+  kit.remember(`${id}.since`, since);
+  const items = menuItems(desc.actions, [["retry", "Retry"], ["next", "Next"], ["menu", "Menu"]]);
+  let chosen: string | null = null;
+  const score = desc.score ?? 0;
+  const time = desc.format === "time";
+  // The score counts up over 0.9 s from the opening; "New best" pops in when it lands.
+  const landed = open && kit.seconds() - since >= 0.9;
+  // A time is lower-is-better (a best of 0 is none); points higher-is-better.
+  const prior = desc.best ?? 0;
+  const best = time ? (desc.newBest ? (prior > 0 ? Math.min(prior, score) : score) : prior) : Math.max(prior, desc.newBest ? score : 0);
+  kit.modal(id, open, { title: desc.title ?? "Level complete", locked: true, width: px(Math.min(phone ? 360 : 420, frame().viewport.width - 32)) }, () => {
+    const max = desc.maxStars ?? 3;
+    if (max > 0) kit.row("StarRow", { width: grow(), align: "center" }, () => stars("Stars", desc.stars ?? 0, max, since, 44));
+    kit.column("ScoreBlock", { width: grow(), cross: "center", gap: t.xxs }, () => {
+      if (desc.scoreLabel) kit.label("ScoreLabel", desc.scoreLabel, { step: "meta", color: token("fgMuted"), align: "center", width: grow(), nowrap: true });
+      if (time) {
+        // A time counts up as a clock (ease-out cubic over the same 0.9 s), the headline in m:ss.mmm.
+        const k = open ? Math.min(1, Math.max(0, (kit.seconds() - since) / 0.9)) : 1;
+        const shown = score * (1 - (1 - k) ** 3);
+        kit.label("Score", k >= 1 ? lapTime(score) : clock(shown, true), { step: "displayLg", font: "display", align: "center", width: grow(), nowrap: true });
+      } else {
+        kit.counter("Score", score, { from: 0, durationMs: 900, step: "displayLg", font: "display", align: "center", width: grow() });
+      }
+      if (!time || best > 0 || desc.newBest) {
+        kit.row("BestRow", { gap: t.sm, cross: "center" }, () => {
+          if (!time || best > 0) kit.label("Best", (desc.bestLabel ?? "Best {best}").replaceAll("{best}", time ? lapTime(best) : fmt(best)), { step: "meta", color: token("fgMuted"), nowrap: true });
+          if (desc.newBest) kit.transition("Reveal", landed, { kind: "pop" }, () => kit.badge("NewBest", desc.newBestLabel ?? "New best", "accent"));
+        });
+      }
+    });
+    const stats = desc.stats ?? [];
+    if (stats.length > 0) {
+      kit.column("Stats", { width: grow(), gap: 0 }, () => {
+        stats.forEach((s, i) => kit.keyValue(kit.idi("Stat", i), s.label ?? "", s.value ?? "", true));
+      });
+    }
+    kit.row("Actions", { width: grow(), gap: t.sm, wrap: phone }, () => {
+      for (const item of items) {
+        const r = kit.button(item.id, item.label, { variant: item.primary ? "primary" : "secondary", width: grow(), disabled: item.disabled }) as Api.Response;
+        if (r.clicked) chosen = item.id;
+      }
+    });
+    if (desc.shareText) {
+      if ((kit.button("Share", desc.shareLabel ?? "Share", { variant: "quiet", width: grow() }) as Api.Response).clicked) {
+        chosen = "share";
+        desc.onShare?.(desc.shareText);
+      }
+    }
+  });
+  return { selected: chosen };
+}
+

package/src/ui-kit/settings.ts

@@ -0,0 +1,131 @@
+// The settings screen: Audio, Graphics, Controls and Language over the
+// game's GameSettings. The game owns the values (a resource, a save); the
+// screen answers the new ones every tick and calls the hooks: onChange on
+// every change (apply it at once), onSave when it closes after changes.
+
+import type * as Api from "@origingame/engine";
+import { kit } from "./bind.ts";
+import { frame, grow, px, token } from "./util.ts";
+
+type Settings = {
+  -readonly [K in keyof Required<Api.GameSettings>]: K extends "bindings" ? Api.KeyBinding[] : Required<Api.GameSettings>[K];
+};
+
+/** Every field of the settings, defaults filled in. */
+export function settingsWithDefaults(s: Api.GameSettings = {}): Settings {
+  return {
+    masterVolume: s.masterVolume ?? 1,
+    musicVolume: s.musicVolume ?? 0.8,
+    sfxVolume: s.sfxVolume ?? 1,
+    muted: s.muted ?? false,
+    quality: s.quality ?? "medium",
+    showFps: s.showFps ?? false,
+    reducedMotion: s.reducedMotion ?? false,
+    highContrast: s.highContrast ?? false,
+    vibration: s.vibration ?? true,
+    invertY: s.invertY ?? false,
+    sensitivity: s.sensitivity ?? 1,
+    language: s.language ?? "en",
+    bindings: [...(s.bindings ?? [])],
+  };
+}
+
+const QUALITIES: readonly Api.GraphicsQuality[] = ["low", "medium", "high"];
+
+/** A labelled slider row with its value at the end. */
+function sliderRow(id: string, label: string, value: number, desc: Api.SliderDesc, shown: string): number {
+  const { t, phone } = frame();
+  let out = value;
+  kit.row(id, { width: grow(), gap: t.md, cross: "center" }, () => {
+    kit.label("Label", label, { width: px(phone ? 96 : 140), nowrap: true });
+    const r = kit.slider("Slider", value, desc) as Api.SliderResult;
+    out = r.value;
+    kit.label("Value", shown, { width: px(48), align: "end", font: "mono", color: token("fgMuted"), nowrap: true });
+  });
+  return out;
+}
+
+export function settingsScreen(id: string, desc: Api.SettingsDesc = {}): Api.SettingsResult {
+  const { t, phone } = frame();
+  const before = settingsWithDefaults(desc.settings);
+  const s = settingsWithDefaults(desc.settings);
+  const languages = desc.languages ?? [];
+  // Every word is a field of the desc with its English default (og-i18n §2).
+  const tabs: Array<[key: string, label: string]> = [
+    ["audio", desc.audioLabel ?? "Audio"],
+    ["graphics", desc.graphicsLabel ?? "Graphics"],
+    ["controls", desc.controlsLabel ?? "Controls"],
+    ...(languages.length > 0 ? [["language", desc.languageLabel ?? "Language"] as [string, string]] : []),
+  ];
+  let tab = Math.min(kit.memory(`${id}.tab`, 0), tabs.length - 1);
+  let dirty = kit.memory(`${id}.dirty`, 0) !== 0;
+  let closed = false;
+  const width = phone ? grow() : px(Math.min(600, frame().viewport.width - 48));
+  const m = kit.modal(id, desc.open ?? false, { title: desc.title ?? "Settings", width, ignoreBackdrop: true }, () => {
+    // Tabs on a wide surface, a select on a phone (one selection grammar).
+    // The groups' names are the desc's too: a screen reader hears them in the game's language.
+    const labels = tabs.map(([, label]) => label);
+    const section = desc.sectionLabel ?? "Section";
+    const pick = phone
+      ? (kit.select("Section", labels, tab, { width: grow(), label: section }) as Api.ChoiceResult)
+      : (kit.tabs("Section", labels, tab, { fill: true, width: grow(), label: section }) as Api.ChoiceResult);
+    tab = pick.selected;
+    kit.column("Body", { width: grow(), gap: t.sm, height: px(phone ? 300 : 260) }, () => {
+      const pct = (v: number): string => `${Math.round(v * 100)}%`;
+      switch (tabs[tab]?.[0]) {
+        case "audio": {
+          s.masterVolume = sliderRow("Master", desc.masterLabel ?? "Master", s.masterVolume, { step: 0.05 }, pct(s.masterVolume));
+          s.musicVolume = sliderRow("Music", desc.musicLabel ?? "Music", s.musicVolume, { step: 0.05 }, pct(s.musicVolume));
+          s.sfxVolume = sliderRow("Effects", desc.effectsLabel ?? "Effects", s.sfxVolume, { step: 0.05 }, pct(s.sfxVolume));
+          s.muted = (kit.toggle("Mute", s.muted, desc.muteLabel ?? "Mute everything") as Api.ToggleResult).on;
+          break;
+        }
+        case "graphics": {
+          const quality = desc.qualityLabel ?? "Quality";
+          kit.label("QualityLabel", quality, { step: "meta", color: token("fgMuted") });
+          const levels = [desc.lowLabel ?? "Low", desc.mediumLabel ?? "Medium", desc.highLabel ?? "High"];
+          const q = kit.radio("Quality", levels, QUALITIES.indexOf(s.quality), { horizontal: !phone, label: quality });
+          s.quality = QUALITIES[q.selected] ?? "medium";
+          s.showFps = (kit.toggle("Fps", s.showFps, desc.fpsLabel ?? "Show frame rate") as Api.ToggleResult).on;
+          s.reducedMotion = (kit.toggle("Motion", s.reducedMotion, desc.motionLabel ?? "Reduce motion") as Api.ToggleResult).on;
+          s.highContrast = (kit.toggle("Contrast", s.highContrast, desc.contrastLabel ?? "High contrast") as Api.ToggleResult).on;
+          break;
+        }
+        case "controls": {
+          s.sensitivity = sliderRow("Sensitivity", desc.sensitivityLabel ?? "Sensitivity", s.sensitivity, { min: 0.1, max: 3, step: 0.1 }, s.sensitivity.toFixed(1));
+          s.invertY = kit.checkbox("Invert", s.invertY, desc.invertLabel ?? "Invert vertical look").on;
+          s.vibration = kit.checkbox("Vibration", s.vibration, desc.vibrationLabel ?? "Vibration").on;
+          if (s.bindings.length > 0) {
+            kit.divider("Rule", false);
+            kit.scroll("Bindings", { width: grow(), height: grow() }, () => {
+              s.bindings.forEach((b, i) => kit.keyValue(kit.idi("Binding", i), b.label ?? b.action ?? "", b.key ?? "", true));
+            });
+          }
+          break;
+        }
+        case "language": {
+          const at = Math.max(0, languages.findIndex((l) => l.code === s.language));
+          const r = kit.radio("Languages", languages.map((l) => l.label ?? l.code ?? ""), at, { label: desc.languagesLabel ?? "Languages" });
+          s.language = languages[r.selected]?.code ?? s.language;
+          break;
+        }
+      }
+    });
+    kit.row("Footer", { width: grow(), align: "end" }, () => {
+      if ((kit.button("Done", desc.doneLabel ?? "Done", { variant: "primary" }) as Api.Response).clicked) closed = true;
+    });
+  });
+  if (m.dismissed) closed = true;
+  const changed = JSON.stringify(s) !== JSON.stringify(before);
+  if (changed) {
+    dirty = true;
+    desc.onChange?.(s);
+  }
+  if (closed && dirty) {
+    desc.onSave?.(s);
+    dirty = false;
+  }
+  kit.remember(`${id}.tab`, tab);
+  kit.remember(`${id}.dirty`, dirty ? 1 : 0);
+  return { settings: s, changed, closed };
+}