@nayan-ui/games 1.18.0 → 1.20.0

package/src/games/shared/EngineHud.ts

@@ -0,0 +1,815 @@
+// Playtura's scoreboard and game controls drawn by the engine, as a GameView `overlay`: the same panel,
+// columns, start/stop button and trophy/share buttons as ScoreBoardContainer and GameControlButton, but
+// rendered in Rust with the scene, so React re-renders nothing while a game runs. Overlay space is in
+// points from the view's top-left, y up (screen y is negated), z toward the viewer.
+import { type Color, type Entity, extrude, type Font, loadFont, measureText, type Model, Path, World } from '@nayan-ui/engine';
+import { PLAY_PATH, SHARE_PATH, TROPHY_PATH } from '../../helpers/IconPaths';
+import type { GameTheme } from '../../services/ThemeService';
+import { formatTime, getGameDimensions } from '../../services/UtilsService';
+import { cardBackdropMesh } from './EngineBackdrop';
+import { fitControlSubtitle } from './EngineControlText';
+import { cacheGameAsset, createGameMesh as createShape } from './EngineMeshes';
+import { gameWidthFor, toColor } from './EngineUtils';
+
+const CAPACITY = 900;
+const BOARD_PAD_V = 14;
+const BOARD_RADIUS = 18;
+// Font sizes and letter spacing in points, as ScoreBoardContainer / GameControlButton / GameOverModal
+const LABEL_SIZE = 12;
+const VALUE_SIZE = 24;
+const LABEL_SPACING = 1.2;
+const BOARD_HEIGHT = BOARD_PAD_V * 2 + 12 + 4 + 24;
+const ROW_PAD_V = 20;
+const ROW_PAD_H = 16;
+const ROW_GAP = 20;
+const MAIN_HEIGHT = 60;
+const ICON_SIZE = 56;
+const BUTTON_TEXT = 16;
+const BUTTON_SUBTEXT = 10;
+const PULSE = 1.05;
+const PRESSED = 0.95;
+// The game-over card (GameOverModal's layout)
+const Z_OVER = 40;
+const CARD_PAD = 20;
+const TROPHY = 48;
+const TITLE_SIZE = 28;
+const MESSAGE_SIZE = 14;
+const SCORE_LABEL_SIZE = 13;
+const SCORE_SIZE = 44;
+const PROMPT_SIZE = 15;
+const PLAY_SIZE = 17;
+const SHARE_SIZE = 16;
+const RESULT_BUTTON = 52;
+const COUNT_DELAY = 0.2;
+const COUNT_TIME = 0.9;
+const SHARE_PROMPT = 'Share your goals with your family and friends and challenge them to beat your score!';
+
+/** A scoreboard column: text (optionally colored), or `lives` drawn as hearts. */
+export type HudColumn = { label: string; value: string; color?: string; valueColor?: string; lives?: { count: number; max: number } };
+
+/** Top edge of the scoreboard; `offset` is the height of the host app's header, 0 when there is none. */
+export const getScoreBoardTop = (offset = 0) => (offset > 0 ? offset + 15 : 15);
+/** Insets for a React touch surface over the scene, leaving the native HUD's controls reachable. */
+export const getSceneInputInsets = (offset = 0) => ({
+  top: getScoreBoardTop(offset) + BOARD_HEIGHT + 10,
+  bottom: ROW_PAD_V + MAIN_HEIGHT + 10 + 5
+});
+
+/** The usual columns. */
+export const scoreColumn = (score: number, label = 'SCORE', format: (n: number) => string = (n) => n.toLocaleString()): HudColumn => ({
+  label,
+  value: format(score)
+});
+/** Time as m:ss, red at or under `lowAt` seconds (0: only at zero). */
+export const timerColumn = (seconds: number, theme: GameTheme, lowAt = 30, label = 'TIMER'): HudColumn => {
+  const s = Math.max(0, Math.ceil(seconds));
+  return { label, value: formatTime(s), valueColor: s <= lowAt ? theme.DANGER : undefined };
+};
+export const livesColumn = (count: number, max: number, label = 'LIVES'): HudColumn => ({ label, value: `${count}/${max}`, lives: { count, max } });
+export const textColumn = (label: string, value: string | number, color?: string): HudColumn => ({ label, value: String(value), color });
+
+const HEART_PATH =
+  'M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z';
+const HEART_SIZE = 20;
+const HEART_GAP = 2;
+const HEART_ON = '#E53935';
+const HEART_OFF = '#2B2B2B';
+export type HudButton = 'main' | 'leaderboard' | 'share' | 'choice';
+export type HudActions = { onStart: () => void; onStop: () => void; onShare?: () => void; onShowLeaderboard?: () => void };
+
+type Rect = { id: HudButton; x: number; y: number; w: number; h: number; root: Entity; action?: () => void };
+
+export type GameOverCard = {
+  title: string;
+  message?: string;
+  scoreLabel: string;
+  score: number;
+  formatter?: (score: number) => string;
+  buttonText: string;
+  onPlayAgain: () => void;
+  onShare?: () => void;
+};
+export interface HudChoice {
+  id: string;
+  label: string;
+  selected?: boolean;
+  onPress: () => void;
+}
+
+/** Events coalesce until the next engine frame; consuming them never triggers a React render. */
+export interface HudFeedback {
+  flash?: boolean;
+  message?: string;
+}
+
+type Over = {
+  card: GameOverCard;
+  root: Entity;
+  scoreParent: Entity;
+  scoreY: number;
+  scoreText: string;
+  scoreEntity: Entity | null;
+  elapsed: number;
+  buttons: Rect[];
+  /** Where the banner ad goes, in points from the view's top. */
+  bannerTop: number;
+  bannerWidth: number;
+};
+
+const meshes = new Map<string, Model>();
+const cached = (key: string, build: () => Model) => {
+  let m = meshes.get(key);
+  if (!m) {
+    m = cacheGameAsset('shared/EngineHud:' + key, build);
+    meshes.set(key, m);
+  }
+  return m;
+};
+/** A flat rounded rectangle centred on the origin (sizes are rounded so few meshes are made). */
+const panelMesh = (w: number, h: number, r: number) => {
+  const [rw, rh] = [Math.round(w), Math.round(h)];
+  return cached(`hud-panel:${rw}:${rh}:${r}`, () =>
+    createShape(extrude(new Path().addRoundedRect(-rw / 2, -rh / 2, rw, rh, Math.min(r, rw / 2, rh / 2)), { depth: 0 }), { center: false })
+  );
+};
+/** The outline of panelMesh(w, h, r), `bw` thick (a border, so translucent faces aren't tinted by it). */
+const ringMesh = (w: number, h: number, r: number, bw: number) => {
+  const [rw, rh] = [Math.round(w), Math.round(h)];
+  return cached(`hud-ring:${rw}:${rh}:${r}:${bw}`, () => {
+    const outer = Math.min(r, rw / 2, rh / 2);
+    const path = new Path()
+      .addRoundedRect(-rw / 2, -rh / 2, rw, rh, outer)
+      .addRoundedRect(-rw / 2 + bw, -rh / 2 + bw, rw - bw * 2, rh - bw * 2, Math.max(0, outer - bw));
+    return createShape(extrude(path, { depth: 0, fillRule: 'evenodd' }), { center: false });
+  });
+};
+/** The RN icons' own outlines (Icons.tsx), flat, one unit across at their widest. */
+const iconMesh = (key: string, d: string) => cached(`hud-icon:${key}`, () => createShape(extrude(Path.fromSVG(d), { depth: 0 }), { fit: 1 }));
+const trophyMesh = () => iconMesh('trophy', TROPHY_PATH);
+const shareMesh = () => iconMesh('share', SHARE_PATH);
+const playMesh = () => iconMesh('play', PLAY_PATH);
+const heartMesh = () => iconMesh('heart', HEART_PATH);
+// How much of each icon's 512 box its outline fills, so `size` matches the RN icon's size.
+const TROPHY_INK = 448 / 512;
+const SHARE_INK = 415 / 512;
+const PLAY_INK = 332 / 512;
+
+type Fonts = { semi: Font; regular: Font };
+type Weight = keyof Fonts;
+let fonts: Fonts | null = null;
+let fontsLoading: Promise<Fonts> | null = null;
+// Glyphs share the engine's 4,096 app-wide mesh ids with models. Prewarm common HUD characters in
+// one weight; the font builds other Unicode symbols only when a label actually needs them.
+const HUD_CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz.,:!?'%/+-·×÷…";
+/** Inter SemiBold for all HUD text, flat (depth 0) like normal text: loaded once per app. */
+export function loadHudFonts(): Promise<Fonts> {
+  fontsLoading ??= loadFont(require('../../assets/fonts/Inter-SemiBold.ttf'), { depth: 0, chars: HUD_CHARS }).then(
+    (semi) => (fonts = { semi, regular: semi })
+  );
+  return fontsLoading;
+}
+
+/** A line's width in points at font size `size`, with `spacing` points between letters. */
+function textWidth(text: string, size: number, spacing = 0, weight: Weight = 'semi'): number {
+  const font = fonts?.[weight];
+  if (!font) return 0;
+  return measureText(font, text, { letterSpacing: spacing / size }) * size;
+}
+
+/** Words broken into lines at most `max` points wide. */
+function wrap(text: string, size: number, max: number, weight: Weight): string[] {
+  const lines: string[] = [];
+  let line = '';
+  for (const word of text.split(/\s+/)) {
+    const next = line ? `${line} ${word}` : word;
+    if (line && textWidth(next, size, 0, weight) > max) {
+      lines.push(line);
+      line = word;
+    } else line = next;
+  }
+  if (line) lines.push(line);
+  return lines;
+}
+
+const columnKey = (c: HudColumn) =>
+  `${c.value}\u0000${c.color ?? ''}\u0000${c.valueColor ?? ''}\u0000${c.lives ? `${c.lives.count}/${c.lives.max}` : ''}`;
+
+/** Text centred on (x, y) in its parent at font size `size` (points), `spacing` points between letters. */
+function spawnText(
+  world: World,
+  parent: Entity,
+  text: string,
+  x: number,
+  y: number,
+  size: number,
+  color: Color,
+  spacing = 0,
+  weight: Weight = 'semi',
+  tabular = false
+): Entity {
+  return world.spawn({
+    text,
+    font: fonts![weight],
+    parent,
+    position: [x, y, 2],
+    scale: size,
+    color,
+    letterSpacing: spacing / size,
+    tabular,
+    pickable: false
+  });
+}
+
+/** The engine-drawn scoreboard and controls. Feed it state; pass `world` as GameView's `overlay`. */
+export class EngineHud {
+  readonly world: World;
+  private theme: GameTheme;
+  private size = { width: 0, height: 0, offset: 0 };
+  private columns: HudColumn[] = [];
+  private playing = false;
+  private subtext = 'Begin playing!';
+  private actions: HudActions = { onStart: () => {}, onStop: () => {} };
+  private board: Entity | null = null;
+  private controls: Entity | null = null;
+  private values: { entity: Entity; key: string; x: number; y: number }[] = [];
+  private buttons: Rect[] = [];
+  private pressed: Rect | null = null;
+  private over: Over | null = null;
+  private overReserve = 0;
+  private disposed = false;
+  private feedback: { root: Entity; flash: Entity | null; message: Entity | null; text: string } | null = null;
+
+  private waiting: GameOverCard | null = null;
+  private layers = new Map<string, Entity>();
+  private choices: HudChoice[] = [];
+  private choiceRoot: Entity | null = null;
+  private choiceButtons: Rect[] = [];
+  private choicePage = 0;
+
+  get ready() {
+    return !this.disposed && !!fonts && this.size.width > 0;
+  }
+  get viewport() {
+    return this.size;
+  }
+  layer(key: string): Entity {
+    let root = this.layers.get(key);
+    if (root === undefined) {
+      root = this.world.spawn({ mesh: 'none', position: [0, 0, 5], pickable: false });
+      this.layers.set(key, root);
+    }
+    return root;
+  }
+  clearLayer(key: string) {
+    const root = this.layers.get(key);
+    if (root !== undefined) this.world.despawn(root);
+    this.layers.delete(key);
+  }
+  text(parent: Entity, text: string, x: number, y: number, size: number, color: Color): Entity {
+    return spawnText(this.world, parent, text, x, y, size, color);
+  }
+  rectangle(parent: Entity, x: number, y: number, width: number, height: number, color: Color, z = 0): Entity {
+    return this.world.spawn({ mesh: panelMesh(1, 1, 0), parent, position: [x, y, z], scale: [width, height, 1], color, pickable: false });
+  }
+  setChoices(choices: HudChoice[]) {
+    const changed =
+      choices.length !== this.choices.length ||
+      choices.some((item, i) => {
+        const previous = this.choices[i];
+        return item.id !== previous?.id || item.label !== previous.label || item.selected !== previous.selected;
+      });
+    this.choices = choices;
+    if (changed) this.buildChoices();
+  }
+  private buildChoices() {
+    if (this.choiceRoot !== null) this.world.despawn(this.choiceRoot);
+    this.choiceRoot = null;
+    this.choiceButtons = [];
+    if (!this.ready || !this.choices.length) return;
+    const { width, height } = this.size;
+    const pageSize = 3;
+    const pages = Math.ceil(this.choices.length / pageSize);
+    this.choicePage = Math.min(this.choicePage, pages - 1);
+    const root = this.world.spawn({ mesh: 'none', position: [0, 0, 6], pickable: false });
+    this.choiceRoot = root;
+    const w = Math.min(width - 24, 500),
+      gap = 6,
+      cell = (w - gap * 4) / 5;
+    const cy = height - getSceneInputInsets().bottom - 22;
+    const draw = (label: string, index: number, action: () => void, selected = false) => {
+      const x = (width - w) / 2 + cell / 2 + index * (cell + gap);
+      const panel = this.panel(root, x, cy, cell, 36, 12, selected ? this.theme.SOLID : this.theme.SURFACE);
+      spawnText(
+        this.world,
+        panel,
+        label,
+        0,
+        0,
+        Math.min(12, (cell - 8) / Math.max(1, label.length) / 0.65),
+        toColor(selected ? this.theme.ON_SOLID : this.theme.TEXT)
+      );
+      this.choiceButtons.push({ id: 'choice', x: x - cell / 2, y: cy - 18, w: cell, h: 36, root: panel, action });
+    };
+    draw('<', 0, () => {
+      this.choicePage = (this.choicePage + pages - 1) % pages;
+      this.buildChoices();
+    });
+    this.choices
+      .slice(this.choicePage * pageSize, (this.choicePage + 1) * pageSize)
+      .forEach((item, i) => draw(item.label, i + 1, () => this.choices.find((choice) => choice.id === item.id)?.onPress(), item.selected));
+    draw('>', 4, () => {
+      this.choicePage = (this.choicePage + 1) % pages;
+      this.buildChoices();
+    });
+  }
+
+  constructor(theme: GameTheme, capacity = CAPACITY) {
+    this.world = new World(capacity);
+    this.theme = theme;
+    // Everything is drawn once the fonts are in (immediately after the first visit)
+    loadHudFonts()
+      .then(() => {
+        if (this.disposed) return;
+        this.buildBoard();
+        this.buildControls();
+        this.buildChoices();
+        if (this.waiting) this.buildOver(this.waiting, true);
+        this.waiting = null;
+      })
+      .catch((error: unknown) => console.error(`EngineHud: ${error instanceof Error ? error.message : String(error)}`));
+  }
+
+  setActions(actions: HudActions) {
+    const changed = !!actions.onShare !== !!this.actions.onShare || !!actions.onShowLeaderboard !== !!this.actions.onShowLeaderboard;
+    this.actions = actions;
+    if (changed) this.buildControls();
+  }
+
+  layout(width: number, height: number, offset: number) {
+    if (width === this.size.width && height === this.size.height && offset === this.size.offset) return;
+    this.size = { width, height, offset };
+    this.layoutFeedback();
+    this.buildBoard();
+    this.buildControls();
+    this.buildChoices();
+    if (this.over) this.buildOver(this.over.card, false);
+  }
+
+  setTheme(theme: GameTheme) {
+    if (theme === this.theme) return;
+    this.theme = theme;
+    this.clearFeedback();
+    this.buildBoard();
+    this.buildControls();
+    this.buildChoices();
+    if (this.over) this.buildOver(this.over.card, false);
+  }
+
+  /** The scoreboard's columns; only values that changed are redrawn. */
+  setColumns(columns: HudColumn[]) {
+    const sameLabels = columns.length === this.columns.length && columns.every((c, i) => c.label === this.columns[i]!.label);
+    this.columns = columns;
+    if (!sameLabels || this.values.length !== columns.length) return this.buildBoard();
+    columns.forEach((c, i) => {
+      const v = this.values[i]!;
+      const key = columnKey(c);
+      if (v.key === key || this.disposed || this.board === null) return;
+      this.world.despawn(v.entity);
+      v.entity = this.spawnValue(this.board, c, v.x, v.y);
+      v.key = key;
+    });
+  }
+
+  setPlaying(playing: boolean, subtext = this.subtext) {
+    if (playing === this.playing && subtext === this.subtext) return;
+    this.playing = playing;
+    this.subtext = subtext;
+    this.buildControls();
+  }
+
+  update(dt: number, feedback?: HudFeedback) {
+    if (this.disposed) return;
+    if (feedback) this.showFeedback(feedback);
+    const o = this.over;
+    if (o && o.elapsed < COUNT_DELAY + COUNT_TIME) {
+      o.elapsed += dt;
+      const t = Math.min(1, Math.max(0, (o.elapsed - COUNT_DELAY) / COUNT_TIME));
+      this.setOverScore(Math.round(o.card.score * (1 - (1 - t) ** 3)));
+    }
+    this.world.update(dt);
+  }
+
+  private showFeedback(feedback: HudFeedback) {
+    if (!this.size.width || !fonts) return;
+    if (!this.over && !this.waiting && (feedback.flash || feedback.message)) {
+      const effects = (this.feedback ??= {
+        root: this.world.spawn({ mesh: 'none', position: [0, 0, Z_OVER - 5], pickable: false }),
+        flash: null,
+        message: null,
+        text: ''
+      });
+      if (feedback.flash) {
+        effects.flash ??= this.world.spawn({ mesh: panelMesh(1, 1, 0), parent: effects.root, pickable: false });
+        const color = toColor(this.theme.DANGER, 0.6);
+        this.world.stopAnimation(effects.flash);
+        this.world.set(effects.flash, { color });
+        this.world.animate(effects.flash, { color: [color[0], color[1], color[2], 0] }, { duration: 0.4 });
+      }
+      if (feedback.message) {
+        if (effects.text !== feedback.message && effects.message !== null) {
+          this.world.despawn(effects.message);
+          effects.message = null;
+        }
+        const color = toColor(this.theme.SCORE_HIGHLIGHT);
+        effects.text = feedback.message;
+        effects.message ??= spawnText(this.world, effects.root, effects.text, 0, 0, 30, color);
+        this.world.stopAnimation(effects.message);
+        this.world.set(effects.message, { color });
+        this.world.animate(effects.message, { color: [color[0], color[1], color[2], 0] }, { duration: 0.9 });
+      }
+      this.layoutFeedback();
+    }
+    feedback.flash = false;
+    feedback.message = undefined;
+  }
+
+  private layoutFeedback() {
+    const effects = this.feedback;
+    if (!effects) return;
+    const { width, height, offset } = this.size;
+    if (effects.flash !== null) this.world.set(effects.flash, { position: [width / 2, -height / 2, 0], scale: [width, height, 1] });
+    if (effects.message !== null) this.world.set(effects.message, { position: [width / 2, -(getScoreBoardTop(offset) + BOARD_HEIGHT + 14 + 15), 2] });
+  }
+
+  private clearFeedback() {
+    if (this.feedback && !this.disposed) this.world.despawn(this.feedback.root);
+    this.feedback = null;
+  }
+
+  /** Shows the game-over card over everything (it takes every touch until hidden). */
+  showGameOver(card: GameOverCard) {
+    this.clearFeedback();
+    const o = this.over;
+    if (o && o.card.title === card.title && o.card.message === card.message && o.card.score === card.score && !!o.card.onShare === !!card.onShare) {
+      o.card = card; // fresh callbacks only
+      return;
+    }
+    if (!fonts) this.waiting = card;
+    else this.buildOver(card, true);
+  }
+
+  hideGameOver() {
+    this.waiting = null;
+    if (!this.over) return;
+    if (!this.disposed) this.world.despawn(this.over.root);
+    if (this.pressed && this.over.buttons.includes(this.pressed)) this.pressed = null;
+    this.over = null;
+  }
+
+  /** Where an RN banner ad sits under the card's buttons (null: no card). */
+  get gameOverBanner(): { top: number; width: number } | null {
+    return this.over ? { top: this.over.bannerTop, width: this.over.bannerWidth } : null;
+  }
+
+  /** Room left in the card for the banner ad (its measured height), in points. */
+  setGameOverReserve(height: number) {
+    if (Math.abs(height - this.overReserve) < 1) return;
+    this.overReserve = height;
+    if (this.over) this.buildOver(this.over.card, false);
+  }
+
+  /** GameView's onOverlayTouch: true when a button took the touch. */
+  touch = (phase: 'start' | 'move' | 'end' | 'cancel', x: number, y: number): boolean => {
+    if (phase === 'start') {
+      const list = this.over ? this.over.buttons : [...this.buttons, ...this.choiceButtons];
+      const hit = list.find((b) => x >= b.x && x <= b.x + b.w && y >= b.y && y <= b.y + b.h);
+      if (!hit) return this.over !== null; // the card is modal
+      this.pressed = hit;
+      this.world.animate(hit.root, { scale: PRESSED }, { duration: 0.08 });
+      return true;
+    }
+    if (phase === 'move' || !this.pressed) return true;
+    const b = this.pressed;
+    this.pressed = null;
+    const inside = x >= b.x - 10 && x <= b.x + b.w + 10 && y >= b.y - 10 && y <= b.y + b.h + 10;
+    this.release(b);
+    if (phase === 'end' && inside) {
+      if (b.action) b.action();
+      else this.fire(b.id);
+    }
+    return true;
+  };
+
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.world.dispose();
+  }
+
+  private release(b: Rect) {
+    if (b.id === 'main' && !this.playing && !b.action) this.pulse(b.root);
+    else this.world.animate(b.root, { scale: 1 }, { duration: 0.12 });
+  }
+
+  private pulse(root: Entity) {
+    this.world.set(root, { scale: 1 });
+    this.world.animate(root, { scale: PULSE }, { duration: 1, repeat: 'forever', yoyo: true });
+  }
+
+  private fire(id: HudButton) {
+    if (id === 'main') {
+      if (this.playing) this.clearFeedback();
+      (this.playing ? this.actions.onStop : this.actions.onStart)();
+    } else if (id === 'share') this.actions.onShare?.();
+    else this.actions.onShowLeaderboard?.();
+  }
+
+  /** A themed button panel (border behind the face) under a root at its centre. */
+  private panel(
+    parent: Entity | null,
+    cx: number,
+    cy: number,
+    w: number,
+    h: number,
+    r: number,
+    face = this.theme.SURFACE,
+    border = this.theme.BORDER
+  ): Entity {
+    const t = this.theme;
+    const root = this.world.spawn({ mesh: 'none', ...(parent !== null && { parent }), position: [cx, -cy, 0], pickable: false });
+    const bw = t.BORDER_WIDTH ?? 0;
+    if (bw > 0) this.world.spawn({ mesh: ringMesh(w, h, r, bw), parent: root, position: [0, 0, 0.5], color: toColor(border), pickable: false });
+    this.world.spawn({ mesh: panelMesh(w - bw * 2, h - bw * 2, r - bw), parent: root, position: [0, 0, 0], color: toColor(face), pickable: false });
+    return root;
+  }
+
+  private setOverScore(value: number) {
+    const o = this.over;
+    if (!o) return;
+    const text = (o.card.formatter ?? ((n: number) => n.toLocaleString()))(value);
+    if (text === o.scoreText && o.scoreEntity !== null) return;
+    if (o.scoreEntity !== null) this.world.despawn(o.scoreEntity);
+    o.scoreText = text;
+    o.scoreEntity = spawnText(this.world, o.scoreParent, text, 0, o.scoreY, SCORE_SIZE, toColor(this.theme.SCORE_HIGHLIGHT), 0, 'semi', true);
+  }
+
+  /** The card, laid out top to bottom as GameOverModal; `animate` plays its entrance. */
+  private buildOver(card: GameOverCard, animate: boolean) {
+    const counted = this.over && !animate ? this.over.elapsed : 0;
+    this.hideGameOver();
+    const { width, height } = this.size;
+    if (this.disposed || !width || !fonts) return;
+    const t = this.theme;
+    const w = Math.min(getGameDimensions().width, width - 30);
+    const inner = w - CARD_PAD * 2;
+    const message = card.message ? wrap(card.message, MESSAGE_SIZE, inner, 'regular') : [];
+    const prompt = card.onShare ? wrap(SHARE_PROMPT, PROMPT_SIZE, inner + 30, 'regular') : [];
+    // Heights, top to bottom
+    const titleH = 34;
+    const scoreH = 16 + 16 + 4 + 52 + 16;
+    const h =
+      CARD_PAD +
+      TROPHY +
+      8 +
+      titleH +
+      (message.length ? 4 + message.length * 20 + 16 : 20) +
+      scoreH +
+      24 +
+      (prompt.length ? prompt.length * 25 + 5 + 12 : 0) +
+      RESULT_BUTTON +
+      (this.overReserve > 0 ? 12 + this.overReserve : 0) +
+      CARD_PAD;
+    const top = Math.max(10, (height - h) / 2);
+    const cx = width / 2;
+
+    const root = this.world.spawn({ mesh: 'none', position: [0, 0, Z_OVER], pickable: false });
+    const backdrop = this.world.spawn({
+      mesh: panelMesh(width, height, 0),
+      parent: root,
+      position: [width / 2, -height / 2, 0],
+      color: animate ? toColor(t.OVERLAY, 0) : toColor(t.OVERLAY),
+      pickable: false
+    });
+    // The card: the game background pattern (as BackdropCard), cut to its rounded corners
+    const box = this.world.spawn({ mesh: 'none', parent: root, position: [cx, -(top + h / 2), 2], pickable: false });
+    this.world.spawn({
+      mesh: cardBackdropMesh(t, w, h, 16),
+      parent: box,
+      position: [-Math.round(w) / 2, Math.round(h) / 2, 0],
+      color: [1, 1, 1, 1],
+      pickable: false
+    });
+    // Children of the card are placed from its centre: screen y below the card's top -> local y
+    const ly = (y: number) => h / 2 - y;
+    const group = (y: number) => this.world.spawn({ mesh: 'none', parent: box, position: [0, ly(y), 1], pickable: false });
+    let y = CARD_PAD;
+
+    const trophy = group(y + TROPHY / 2);
+    this.world.spawn({ mesh: trophyMesh(), parent: trophy, position: [0, 0, 0], scale: TROPHY * TROPHY_INK, color: [1, 1, 1, 1], pickable: false });
+    y += TROPHY + 8;
+    spawnText(this.world, group(y + titleH / 2), card.title, 0, 0, TITLE_SIZE, toColor(t.TEXT), 1);
+    y += titleH;
+    if (message.length) {
+      y += 4;
+      for (const line of message) {
+        spawnText(this.world, group(y + 10), line, 0, 0, MESSAGE_SIZE, toColor(t.TEXT_SUBTLE), 0, 'regular');
+        y += 20;
+      }
+      y += 16;
+    } else y += 20;
+
+    const scoreAt = ly(y + scoreH / 2);
+    const scoreGroup = group(y + scoreH / 2);
+    const sw = Math.max(200, Math.min(inner, 260));
+    const scorePanel = this.panel(scoreGroup, 0, 0, sw, scoreH, 16);
+    spawnText(this.world, scorePanel, card.scoreLabel.toUpperCase(), 0, scoreH / 2 - 16 - 8, SCORE_LABEL_SIZE, toColor(t.TEXT_SUBTLE), 1, 'semi');
+    const scoreY = -scoreH / 2 + 16 + 26;
+    y += scoreH + 24;
+
+    const actionsAt = ly(y);
+    const actions = group(y);
+    let ay = 0; // screen points below the actions' top
+    for (const line of prompt) {
+      spawnText(this.world, actions, line, 0, -(ay + 12.5), PROMPT_SIZE, toColor(t.TEXT_SUBTLE), 0, 'regular');
+      ay += 25;
+    }
+    if (prompt.length) ay += 5 + 12;
+    const buttons: Rect[] = [];
+    const rowY = ay + RESULT_BUTTON / 2;
+    const left = -inner / 2;
+    const shareW = card.onShare ? ((inner - 10) * 2) / 5 : 0;
+    const playW = card.onShare ? inner - 10 - shareW : inner;
+    const addButton = (
+      x: number,
+      bw: number,
+      face: string,
+      border: string,
+      label: string,
+      size: number,
+      weight: Weight,
+      color: Color,
+      mesh: Model,
+      ink: number,
+      action: () => void
+    ) => {
+      const b = this.panel(actions, x + bw / 2, rowY, bw, RESULT_BUTTON, 26, face, border);
+      // Icon (18) + gap (8) + label, centred as a row
+      const fittedSize = Math.min(size, (size * (bw - 44)) / Math.max(1, textWidth(label, size, 0.5, weight)));
+      const textW = textWidth(label, fittedSize, 0.5, weight);
+      const iconX = -(textW + 26) / 2 + 9;
+      this.world.spawn({ mesh, parent: b, position: [iconX, 0, 2], scale: 18 * ink, color, pickable: false });
+      spawnText(this.world, b, label, iconX + 9 + 8 + textW / 2, 0, fittedSize, color, 0.5, weight);
+      // Screen rect: the actions group's top is at screen `top + y`
+      buttons.push({ id: 'main', x: cx + x, y: top + y + rowY - RESULT_BUTTON / 2, w: bw, h: RESULT_BUTTON, root: b, action });
+    };
+    if (card.onShare)
+      addButton(left, shareW, t.SURFACE, t.BORDER, 'Share', SHARE_SIZE, 'semi', toColor(t.TEXT), shareMesh(), SHARE_INK, () =>
+        this.over?.card.onShare?.()
+      );
+    addButton(
+      left + (card.onShare ? shareW + 10 : 0),
+      playW,
+      t.SOLID,
+      t.SOLID,
+      card.buttonText,
+      PLAY_SIZE,
+      'semi',
+      toColor(t.ON_SOLID),
+      playMesh(),
+      PLAY_INK,
+      () => this.over?.card.onPlayAgain()
+    );
+    ay += RESULT_BUTTON;
+
+    this.over = {
+      card,
+      root,
+      scoreParent: scorePanel,
+      scoreY,
+      scoreText: '',
+      scoreEntity: null,
+      elapsed: counted,
+      buttons,
+      bannerTop: top + y + ay + 12,
+      bannerWidth: inner
+    };
+    this.setOverScore(animate ? 0 : card.score);
+
+    if (!animate) return;
+    // GameOverModal's entrance: fade the backdrop, spring the card, punch the trophy, lift score then actions
+    this.world.animate(backdrop, { color: toColor(t.OVERLAY) }, { duration: 0.16 });
+    this.world.set(box, { scale: 0.85 });
+    this.world.animate(box, { scale: 1 }, { spring: 'bouncy' });
+    this.world.set(trophy, { scale: 0 });
+    this.world.animate(trophy, [{ scale: 1.18 }, { scale: 1 }], { delay: 0.09, duration: 0.35, easing: 'back' });
+    for (const [g, at, delay] of [
+      [scoreGroup, scoreAt, 0.2],
+      [actions, actionsAt, 0.33]
+    ] as const) {
+      this.world.set(g, { position: [0, at - 18, 1] });
+      this.world.animate(g, { position: [0, at, 1] }, { delay, spring: true });
+    }
+  }
+
+  private buildBoard() {
+    if (this.disposed) return;
+    if (this.board !== null) this.world.despawn(this.board);
+    this.board = null;
+    this.values = [];
+    const { width, offset } = this.size;
+    if (!width || !fonts) return;
+    const w = gameWidthFor(width);
+    const top = getScoreBoardTop(offset);
+    const board = this.panel(null, width / 2, top + BOARD_HEIGHT / 2, w, BOARD_HEIGHT, BOARD_RADIUS);
+    this.board = board;
+    const n = this.columns.length;
+    const labelY = BOARD_HEIGHT / 2 - BOARD_PAD_V - 6;
+    const valueY = -BOARD_HEIGHT / 2 + BOARD_PAD_V + 12;
+    const label = toColor(this.theme.LABEL);
+    this.columns.forEach((c, i) => {
+      const x = -w / 2 + (w * (i + 0.5)) / n;
+      spawnText(this.world, board, c.label, x, labelY, LABEL_SIZE, c.color ? toColor(c.color) : label, LABEL_SPACING, 'semi');
+      this.values.push({ entity: this.spawnValue(board, c, x, valueY), key: columnKey(c), x, y: valueY });
+    });
+  }
+
+  /** The same primary control for keyboard input, including the results card. */
+  activatePrimary() {
+    if (!this.ready) return;
+    if (this.over) this.over.card.onPlayAgain();
+    else this.fire('main');
+  }
+
+  /** A column's value: its text, or a row of hearts. */
+  private spawnValue(board: Entity, c: HudColumn, x: number, y: number): Entity {
+    if (!c.lives)
+      return spawnText(this.world, board, c.value, x, y, VALUE_SIZE, toColor(c.valueColor ?? c.color ?? this.theme.TEXT), 0, 'semi', true);
+    const { count, max } = c.lives;
+    const row = this.world.spawn({ mesh: 'none', parent: board, position: [x, y, 2], pickable: false });
+    const columnWidth = gameWidthFor(this.size.width) / this.columns.length - 12;
+    const heartSize = Math.min(HEART_SIZE, Math.max(6, (columnWidth - (max - 1) * HEART_GAP) / Math.max(1, max)));
+    const step = heartSize + HEART_GAP;
+    for (let i = 0; i < max; i++) {
+      const hx = (i - (max - 1) / 2) * step;
+      this.world.spawn({
+        mesh: heartMesh(),
+        parent: row,
+        position: [hx, 0, 0],
+        scale: heartSize,
+        color: toColor(i < count ? HEART_ON : HEART_OFF),
+        pickable: false
+      });
+    }
+    return row;
+  }
+
+  private buildControls() {
+    if (this.disposed) return;
+    if (this.controls !== null) this.world.despawn(this.controls);
+    this.controls = null;
+    this.buttons = [];
+    this.pressed = null;
+    const { width, height } = this.size;
+    if (!width || !fonts) return;
+    const rowW = Math.min(getGameDimensions().width, width);
+    const left = (width - rowW) / 2 + ROW_PAD_H;
+    const right = (width + rowW) / 2 - ROW_PAD_H;
+    const cy = height - 5 - ROW_PAD_V - MAIN_HEIGHT / 2;
+    const controls = this.world.spawn({ mesh: 'none', position: [0, 0, 10], pickable: false });
+    this.controls = controls;
+    const text = toColor(this.theme.TEXT);
+    let mainLeft = left;
+    let mainRight = right;
+    const icon = (id: HudButton, x: number, mesh: Model, ink: number) => {
+      const root = this.panel(controls, x, cy, ICON_SIZE, ICON_SIZE, ICON_SIZE / 2);
+      this.world.spawn({ mesh, parent: root, position: [0, 0, 2], scale: 24 * ink, color: text, pickable: false });
+      this.buttons.push({ id, x: x - ICON_SIZE / 2, y: cy - ICON_SIZE / 2, w: ICON_SIZE, h: ICON_SIZE, root });
+    };
+    if (this.actions.onShowLeaderboard) {
+      icon('leaderboard', left + ICON_SIZE / 2, trophyMesh(), TROPHY_INK);
+      mainLeft += ICON_SIZE + ROW_GAP;
+    }
+    if (this.actions.onShare) {
+      icon('share', right - ICON_SIZE / 2, shareMesh(), SHARE_INK);
+      mainRight -= ICON_SIZE + ROW_GAP;
+    }
+    const mw = mainRight - mainLeft;
+    const mx = (mainLeft + mainRight) / 2;
+    const main = this.panel(controls, mx, cy, mw, MAIN_HEIGHT, 30);
+    spawnText(this.world, main, this.playing ? 'STOP GAME' : 'START GAME', 0, 7, BUTTON_TEXT, text, 1);
+    const subtitle = fitControlSubtitle(this.playing ? 'Stop current game' : this.subtext, Math.max(0, mw - 24), (value) =>
+      textWidth(value, BUTTON_SUBTEXT, 0.5)
+    );
+    spawnText(this.world, main, subtitle, 0, -12, BUTTON_SUBTEXT, toColor(this.theme.LABEL), 0.5, 'semi');
+    this.buttons.push({ id: 'main', x: mainLeft, y: cy - MAIN_HEIGHT / 2, w: mw, h: MAIN_HEIGHT, root: main });
+    if (!this.playing) this.pulse(main);
+  }
+}
+
+/** Reusable assets; the game loader advances one builder per frame. */
+export function* warmAssets(): Iterable<() => unknown> {
+  yield trophyMesh;
+  yield shareMesh;
+  yield playMesh;
+  yield heartMesh;
+}