@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/arrows/ArrowsGame.ts

@@ -0,0 +1,735 @@
+// Arrows' rules, with no React: build a run with `createGame`, give it a layout, `start` it and `tick`
+// it every frame. The board is a 12 x 16 grid tiled by bent arrows. Tap an arrow whose way out (the
+// straight line ahead of its head, to the board edge) is clear and it flies off for 500; tap a blocked
+// one and it shakes, and the arrow in its way pulses. Clear the board to win (with a time bonus); run
+// out of time and it's over with no score. Boards are generated exactly as in the original version.
+import { type Camera, type Entity, World } from '@nayan-ui/engine';
+import { calculateTimeBasedScore } from '../../services/ScoringService';
+import type { GameTheme } from '../../services/ThemeService';
+import { setBackdropTheme } from '../shared/EngineBackdrop';
+import { introPlayed } from '../shared/EngineUtils';
+import {
+  DIR_DC,
+  DIR_DR,
+  Direction,
+  DRAW_IN_STAGGER,
+  DRAW_IN_TIME,
+  FLY_TIME,
+  GRID_COLS,
+  GRID_ROWS,
+  type Layout,
+  POINTS_PER_ARROW,
+  TIME_LIMIT,
+  TOTAL_CELLS
+} from './ArrowsConstants';
+import {
+  arrowColor,
+  type ArrowView,
+  buildScenery,
+  flashBlocked,
+  type Flight,
+  pulseBlocker,
+  pulseBoard,
+  type Scenery,
+  setArrowColor,
+  spawnArrow,
+  spawnDot,
+  spawnFlight,
+  stepFlight
+} from './ArrowsScene';
+
+export type Phase = 'ready' | 'playing' | 'over';
+
+/** A cell on an arrow's path. */
+export interface Waypoint {
+  row: number;
+  col: number;
+}
+
+/** A bent arrow: the cells it runs through, tail first, and the way its head points off the board. */
+export interface Arrow {
+  id: number;
+  waypoints: Waypoint[];
+  exitDir: Direction;
+}
+
+// ── Board generation ──────────────────────────────────────────────────
+
+const idx = (row: number, col: number) => row * GRID_COLS + col;
+
+// Shuffle an array in-place (Fisher-Yates)
+const shuffle = <T>(arr: T[]): T[] => {
+  for (let i = arr.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [arr[i], arr[j]] = [arr[j]!, arr[i]!];
+  }
+  return arr;
+};
+
+// Check if the exit ray from the last waypoint of an arrow is clear
+// (no other arrow's cell lies on the straight ray to the board edge).
+const isExitClear = (cellToArrowId: (number | null)[], arrow: Arrow): boolean => {
+  const last = arrow.waypoints[arrow.waypoints.length - 1]!;
+  const dr = DIR_DR[arrow.exitDir]!;
+  const dc = DIR_DC[arrow.exitDir]!;
+  let r = last.row + dr;
+  let c = last.col + dc;
+  while (r >= 0 && r < GRID_ROWS && c >= 0 && c < GRID_COLS) {
+    const occupant = cellToArrowId[idx(r, c)];
+    if (occupant !== null && occupant !== arrow.id) return false;
+    r += dr;
+    c += dc;
+  }
+  return true;
+};
+
+// Get the direction from cell A to adjacent cell B
+const dirBetween = (a: Waypoint, b: Waypoint): Direction => {
+  const dr = b.row - a.row;
+  const dc = b.col - a.col;
+  if (dr === -1) return Direction.UP;
+  if (dr === 1) return Direction.DOWN;
+  if (dc === 1) return Direction.RIGHT;
+  return Direction.LEFT;
+};
+
+// Get the direction from flat cell index a to adjacent flat cell index b
+const dirBetweenCells = (a: number, b: number): Direction => {
+  const d = b - a;
+  if (d === -GRID_COLS) return Direction.UP;
+  if (d === GRID_COLS) return Direction.DOWN;
+  if (d === 1) return Direction.RIGHT;
+  return Direction.LEFT;
+};
+
+const toWaypoint = (ci: number): Waypoint => ({ row: Math.floor(ci / GRID_COLS), col: ci % GRID_COLS });
+
+// --- Board Generation ---
+// Creates multi-segment arrows that fill the entire grid.
+// Algorithm: reverse peeling with random walks.
+// 1. Start with all cells unassigned.
+// 2. Repeatedly pick an unassigned cell, do a random walk through unassigned
+//    neighbors until we reach a cell that has a clear exit ray to the board edge
+//    (through already-assigned/removed cells).
+// 3. Mark all cells in the walk as one arrow.
+// This guarantees solvability: arrows are created in removal order.
+const generateBoardOnce = (): { arrows: Arrow[]; cellToArrowId: (number | null)[]; count: number } => {
+  const assigned = new Uint8Array(TOTAL_CELLS); // 1 = cell belongs to an arrow already removed
+  const cellToArrowId: (number | null)[] = new Array(TOTAL_CELLS).fill(null);
+  const arrows: Arrow[] = [];
+  let arrowId = 0;
+  let remaining = TOTAL_CELLS;
+
+  // Check if a ray from (row, col) in dir reaches the board edge through assigned cells
+  const rayClearOfUnassigned = (row: number, col: number, dir: Direction): boolean => {
+    const dr = DIR_DR[dir]!;
+    const dc = DIR_DC[dir]!;
+    let r = row + dr;
+    let c = col + dc;
+    while (r >= 0 && r < GRID_ROWS && c >= 0 && c < GRID_COLS) {
+      if (!assigned[idx(r, c)]) return false;
+      r += dr;
+      c += dc;
+    }
+    return true;
+  };
+
+  // Min/max path length for visual variety (3 to 14 cells)
+  const MIN_PATH = 3;
+  const MAX_PATH = 14;
+
+  // Walk scratch buffers, reused for every walk instead of allocating a Set + arrays per try.
+  // walkStamp[ci] === walkId marks cells already on the current walk.
+  const walkStamp = new Int32Array(TOTAL_CELLS);
+  let walkId = 0;
+  const path = new Int16Array(MAX_PATH);
+  const neighbors = new Int16Array(4);
+
+  // True if the ray from head in dir passes through the current walk — rejects confusing
+  // U-shaped arrows whose arrowhead points back into their own body.
+  const exitRayHitsWalk = (head: number, dir: Direction): boolean => {
+    const dr = DIR_DR[dir]!;
+    const dc = DIR_DC[dir]!;
+    let r = Math.floor(head / GRID_COLS) + dr;
+    let c = (head % GRID_COLS) + dc;
+    while (r >= 0 && r < GRID_ROWS && c >= 0 && c < GRID_COLS) {
+      if (walkStamp[idx(r, c)] === walkId) return true;
+      r += dr;
+      c += dc;
+    }
+    return false;
+  };
+
+  // Unassigned cells (order is irrelevant: start cells are drawn from it uniformly at random).
+  // Kept up to date on each new arrow instead of rebuilding + reshuffling all 192 cells per arrow.
+  const unassignedList = new Int16Array(TOTAL_CELLS);
+  const unassignedPos = new Int16Array(TOTAL_CELLS);
+  let unassignedCount = 0;
+  const rebuildUnassigned = () => {
+    unassignedCount = 0;
+    for (let ci = 0; ci < TOTAL_CELLS; ci++) {
+      if (!assigned[ci]) {
+        unassignedPos[ci] = unassignedCount;
+        unassignedList[unassignedCount++] = ci;
+      }
+    }
+  };
+  const swapUnassigned = (i: number, j: number) => {
+    const a = unassignedList[i]!;
+    const b = unassignedList[j]!;
+    unassignedList[i] = b;
+    unassignedList[j] = a;
+    unassignedPos[b] = i;
+    unassignedPos[a] = j;
+  };
+  rebuildUnassigned();
+
+  while (remaining > 0) {
+    if (unassignedCount === 0) break;
+
+    // Try to build a path starting from a random unassigned cell. Drawing each next start
+    // with a lazy Fisher-Yates step gives the same uniformly random try order as shuffling
+    // the whole candidate list up front, but only pays for the starts actually tried.
+    let built = false;
+
+    for (let k = 0; k < unassignedCount; k++) {
+      swapUnassigned(k, k + Math.floor(Math.random() * (unassignedCount - k)));
+      const start = unassignedList[k]!;
+
+      // Random walk: grow a path from `start`
+      walkId++;
+      path[0] = start;
+      walkStamp[start] = walkId;
+      let len = 1;
+
+      // Try to extend the path
+      let current = start;
+      const targetLen = MIN_PATH + Math.floor(Math.random() * (MAX_PATH - MIN_PATH + 1));
+
+      while (len < targetLen) {
+        const row = Math.floor(current / GRID_COLS);
+        const col = current % GRID_COLS;
+        let n = 0;
+        for (let d = 0; d < 4; d++) {
+          const dr = DIR_DR[d]!;
+          const dc = DIR_DC[d]!;
+          const nr = row + dr;
+          const nc = col + dc;
+          if (nr < 0 || nr >= GRID_ROWS || nc < 0 || nc >= GRID_COLS) continue;
+          const ni = idx(nr, nc);
+          if (!assigned[ni] && walkStamp[ni] !== walkId) neighbors[n++] = ni;
+        }
+        if (n === 0) break;
+        const next = neighbors[Math.floor(Math.random() * n)]!;
+        path[len++] = next;
+        walkStamp[next] = walkId;
+        current = next;
+      }
+
+      // Only accept a STRAIGHT exit: the arrowhead must continue the direction of
+      // the last segment (no turn at the last cell). Try the forward orientation
+      // first, then the reversed one. Require at least 2 cells; otherwise try another
+      // start. Single-cell leftovers are absorbed into a neighbour below.
+      if (len < 2) continue;
+      const lastCell = path[len - 1]!;
+      const firstCell = path[0]!;
+      let exitDir: Direction | null = null;
+      let reversed = false;
+
+      // Forward: exit continues (prev -> last) straight off the board
+      const contDir = dirBetweenCells(path[len - 2]!, lastCell);
+      if (rayClearOfUnassigned(Math.floor(lastCell / GRID_COLS), lastCell % GRID_COLS, contDir) && !exitRayHitsWalk(lastCell, contDir)) {
+        exitDir = contDir;
+      } else {
+        // Reversed: exit continues (path[1] -> first) straight off the board
+        const contDirRev = dirBetweenCells(path[1]!, firstCell);
+        if (rayClearOfUnassigned(Math.floor(firstCell / GRID_COLS), firstCell % GRID_COLS, contDirRev) && !exitRayHitsWalk(firstCell, contDirRev)) {
+          exitDir = contDirRev;
+          reversed = true;
+        }
+      }
+
+      if (exitDir === null) continue;
+
+      // Create the arrow and mark all cells as assigned
+      const waypoints: Waypoint[] = new Array(len);
+      for (let i = 0; i < len; i++) {
+        const ci = path[reversed ? len - 1 - i : i]!;
+        waypoints[i] = toWaypoint(ci);
+        assigned[ci] = 1;
+        cellToArrowId[ci] = arrowId;
+        remaining--;
+        // Swap-remove from the unassigned list
+        swapUnassigned(unassignedPos[ci]!, unassignedCount - 1);
+        unassignedCount--;
+      }
+      arrows.push({ id: arrowId, waypoints, exitDir });
+      arrowId++;
+      built = true;
+      break;
+    }
+
+    // No >=2 path could be built this pass: absorb every remaining cell into an
+    // adjacent existing arrow so that no single-cell arrow is left.
+    // Strategy 1: prepend onto an adjacent arrow's TAIL (keeps head exit unchanged).
+    // Strategy 2: append onto an adjacent arrow's HEAD and recompute exit dir.
+    // Both are solvability-safe since the leftover was unassigned when the host
+    // arrow was created, so its exit ray was validated without this cell.
+    if (!built) {
+      for (let r = 0; r < GRID_ROWS; r++) {
+        for (let c = 0; c < GRID_COLS; c++) {
+          const ci = idx(r, c);
+          if (assigned[ci]) continue;
+
+          let merged = false;
+
+          // Strategy 1: prepend onto adjacent arrow's tail
+          for (const d of shuffle([0, 1, 2, 3])) {
+            const dr = DIR_DR[d]!;
+            const dc = DIR_DC[d]!;
+            const nr = r + dr;
+            const nc = c + dc;
+            if (nr < 0 || nr >= GRID_ROWS || nc < 0 || nc >= GRID_COLS) continue;
+            const nid = cellToArrowId[idx(nr, nc)];
+            if (nid === null || nid === undefined) continue;
+            const host = arrows[nid]!;
+            const tail = host.waypoints[0]!;
+            if (tail.row === nr && tail.col === nc) {
+              host.waypoints.unshift({ row: r, col: c });
+              assigned[ci] = 1;
+              cellToArrowId[ci] = host.id;
+              remaining--;
+              merged = true;
+              break;
+            }
+          }
+
+          // Strategy 2: append onto adjacent arrow's head and recompute exit dir
+          if (!merged) {
+            for (const d of shuffle([0, 1, 2, 3])) {
+              const dr = DIR_DR[d]!;
+              const dc = DIR_DC[d]!;
+              const nr = r + dr;
+              const nc = c + dc;
+              if (nr < 0 || nr >= GRID_ROWS || nc < 0 || nc >= GRID_COLS) continue;
+              const nid = cellToArrowId[idx(nr, nc)];
+              if (nid === null || nid === undefined) continue;
+              const host = arrows[nid]!;
+              const head = host.waypoints[host.waypoints.length - 1]!;
+              if (head.row !== nr || head.col !== nc) continue;
+              // New exit must be the straight continuation from old head → new cell
+              const newExitDir = dirBetween(head, { row: r, col: c });
+              if (rayClearOfUnassigned(r, c, newExitDir)) {
+                host.waypoints.push({ row: r, col: c });
+                host.exitDir = newExitDir;
+                assigned[ci] = 1;
+                cellToArrowId[ci] = host.id;
+                remaining--;
+                merged = true;
+                break;
+              }
+            }
+          }
+
+          if (!merged) {
+            // Strategy 3: pair with an adjacent unassigned cell to make a 2-cell arrow
+            let created = false;
+            for (const d of shuffle([0, 1, 2, 3])) {
+              const dr = DIR_DR[d]!;
+              const dc = DIR_DC[d]!;
+              const nr = r + dr;
+              const nc = c + dc;
+              if (nr < 0 || nr >= GRID_ROWS || nc < 0 || nc >= GRID_COLS) continue;
+              if (assigned[idx(nr, nc)]) continue;
+              const exitD = dirBetween({ row: r, col: c }, { row: nr, col: nc });
+              if (rayClearOfUnassigned(nr, nc, exitD)) {
+                const wp: Waypoint[] = [
+                  { row: r, col: c },
+                  { row: nr, col: nc }
+                ];
+                arrows.push({ id: arrowId, waypoints: wp, exitDir: exitD });
+                assigned[ci] = 1;
+                cellToArrowId[ci] = arrowId;
+                const nci = idx(nr, nc);
+                assigned[nci] = 1;
+                cellToArrowId[nci] = arrowId;
+                remaining -= 2;
+                arrowId++;
+                created = true;
+                break;
+              }
+            }
+            if (!created) {
+              // Strategy 4: force-merge at tail or head of ANY adjacent arrow.
+              // Only tail (prepend) and head (append) are safe — mid-path splice
+              // would create non-adjacent segments that render as diagonals.
+              for (const d of shuffle([0, 1, 2, 3])) {
+                const dr = DIR_DR[d]!;
+                const dc = DIR_DC[d]!;
+                const nr = r + dr;
+                const nc = c + dc;
+                if (nr < 0 || nr >= GRID_ROWS || nc < 0 || nc >= GRID_COLS) continue;
+                const nid = cellToArrowId[idx(nr, nc)];
+                if (nid === null || nid === undefined) continue;
+                const host = arrows[nid]!;
+                const tail = host.waypoints[0]!;
+                const head = host.waypoints[host.waypoints.length - 1]!;
+                if (tail.row === nr && tail.col === nc) {
+                  // Prepend at tail — keeps head exit unchanged
+                  host.waypoints.unshift({ row: r, col: c });
+                  assigned[ci] = 1;
+                  cellToArrowId[ci] = host.id;
+                  remaining--;
+                  created = true;
+                  break;
+                }
+                if (head.row === nr && head.col === nc) {
+                  // Append at head — recompute exit direction
+                  const newExitDir = dirBetween(head, { row: r, col: c });
+                  host.waypoints.push({ row: r, col: c });
+                  host.exitDir = newExitDir;
+                  assigned[ci] = 1;
+                  cellToArrowId[ci] = host.id;
+                  remaining--;
+                  created = true;
+                  break;
+                }
+              }
+            }
+            if (!created) {
+              // Absolute last resort (should never happen on a connected grid)
+              assigned[ci] = 1;
+              remaining--;
+            }
+          }
+        }
+      }
+      rebuildUnassigned();
+    }
+  }
+
+  return { arrows, cellToArrowId, count: arrows.length };
+};
+
+// Simulate solving: repeatedly find an arrow whose exit ray is clear, remove it.
+// If all arrows can be removed in some order the board is solvable.
+// (Removing an arrow never blocks another, so the sweep order doesn't affect the result.)
+const isBoardSolvable = (arrows: Arrow[], cellToArrowId: (number | null)[]): boolean => {
+  const map = cellToArrowId.slice(); // working copy
+  let pending = arrows.slice();
+  while (pending.length > 0) {
+    const stillBlocked: Arrow[] = [];
+    for (const arrow of pending) {
+      if (isExitClear(map, arrow)) {
+        for (const wp of arrow.waypoints) {
+          map[idx(wp.row, wp.col)] = null;
+        }
+      } else {
+        stillBlocked.push(arrow);
+      }
+    }
+    if (stillBlocked.length === pending.length) return false;
+    pending = stillBlocked;
+  }
+  return true;
+};
+
+// Check that no arrow's exit ray passes through its own waypoints (confusing visually).
+const noSelfFacing = (arrows: Arrow[]): boolean => {
+  // stamp[ci] === arrow index + 1 marks that arrow's cells (no per-arrow Set)
+  const stamp = new Int32Array(TOTAL_CELLS);
+  for (let a = 0; a < arrows.length; a++) {
+    const arrow = arrows[a]!;
+    const mark = a + 1;
+    for (const wp of arrow.waypoints) stamp[idx(wp.row, wp.col)] = mark;
+    const head = arrow.waypoints[arrow.waypoints.length - 1]!;
+    const dr = DIR_DR[arrow.exitDir]!;
+    const dc = DIR_DC[arrow.exitDir]!;
+    let r = head.row + dr;
+    let c = head.col + dc;
+    while (r >= 0 && r < GRID_ROWS && c >= 0 && c < GRID_COLS) {
+      if (stamp[idx(r, c)] === mark) return false;
+      r += dr;
+      c += dc;
+    }
+  }
+  return true;
+};
+
+// Cells the generator's last-resort branch skipped have no arrow and render as empty dots.
+const countEmptyCells = (cellToArrowId: (number | null)[]): number => {
+  let empty = 0;
+  for (const id of cellToArrowId) if (id === null) empty++;
+  return empty;
+};
+
+// Generate a solvable board with no self-facing arrows, no deadlocks and every cell covered by an arrow.
+// About a third of raw boards are fully covered, so this usually succeeds in ~5 attempts (<1ms).
+const MIN_ARROW_LEN = 2;
+const MAX_BOARD_ATTEMPTS = 200;
+const generateBoard = (): { arrows: Arrow[]; cellToArrowId: (number | null)[]; count: number } => {
+  let fallback: ReturnType<typeof generateBoardOnce> | null = null;
+  let fallbackEmpty = Infinity;
+  for (let attempt = 0; attempt < MAX_BOARD_ATTEMPTS; attempt++) {
+    const board = generateBoardOnce();
+    if (
+      !board.arrows.every((a) => a.waypoints.length >= MIN_ARROW_LEN) ||
+      !noSelfFacing(board.arrows) ||
+      !isBoardSolvable(board.arrows, board.cellToArrowId)
+    ) {
+      continue;
+    }
+    const empty = countEmptyCells(board.cellToArrowId);
+    if (empty === 0) return board;
+    if (empty < fallbackEmpty) {
+      fallback = board;
+      fallbackEmpty = empty;
+    }
+  }
+  // Practically unreachable: keep the valid board with the fewest empty cells
+  return fallback ?? generateBoardOnce();
+};
+
+// ── Run ───────────────────────────────────────────────────────────────
+
+const WORLD_CAPACITY = 1600; // arrow parts (~2 per cell plus heads), 192 dots, flights, scenery
+
+export function createGame(theme: GameTheme) {
+  const world = new World(WORLD_CAPACITY);
+  const camera: Camera = { eye: [0, 0, 400], target: [0, 0, 0], fov: 1, ortho: 1 };
+  const board = generateBoard();
+  const g = {
+    world,
+    camera,
+    theme,
+    color: arrowColor(theme),
+    layout: null as Layout | null,
+    scenery: null as Scenery | null,
+    phase: 'ready' as Phase,
+    /** Score and the countdown live in the engine (Rust), advanced by world.update. */
+    get score() {
+      return world.scoreboard.score;
+    },
+    get timeLeft() {
+      return world.scoreboard.shownSeconds;
+    },
+    won: false,
+    /** By id; null once flown. */
+    arrows: board.arrows as (Arrow | null)[],
+    cellToArrowId: board.cellToArrowId,
+    remaining: board.count,
+    views: [] as (ArrowView | null)[],
+    dots: [] as Entity[],
+    flights: [] as Flight[],
+    /** The next board to appear draws itself in. */
+    intro: true,
+    /** Game seconds the current intro has been playing (-1 until its board spawns). */
+    introAge: -1,
+    // UI hooks, set by the screen.
+    onPhase: (_p: Phase) => {},
+    onScore: (_s: number) => {},
+    onTime: (_t: number) => {},
+    onRemaining: (_n: number) => {},
+    onClear: () => {},
+    onBlocked: () => {},
+    onWin: () => {},
+    onLose: () => {}
+  };
+  world.scoreboard.reset(0, TIME_LIMIT);
+  world.scoreboard.handlers = {
+    onSecond: (t) => g.onTime(t),
+    onTimeUp: () => g.phase === 'playing' && end(g, false)
+  };
+  return g;
+}
+export type Game = ReturnType<typeof createGame>;
+
+/** Lays the scene out for the view (first layout, header height, rotation): rebuilt from the run's state. */
+export function setLayout(g: Game, l: Layout) {
+  const w = g.world;
+  if (g.scenery) {
+    w.despawn(g.scenery.backdrop);
+    w.despawn(g.scenery.board); // its arrows, dots and flights go with it
+  }
+  g.flights = [];
+  g.layout = l;
+  g.camera.ortho = l.height / 2;
+  g.scenery = buildScenery(w, l, g.theme, g.intro);
+  spawnBoard(g);
+}
+
+/** A new theme: the background is repainted and the arrows recolored; the run carries on. */
+export function setTheme(g: Game, theme: GameTheme) {
+  g.theme = theme;
+  g.color = arrowColor(theme);
+  if (!g.scenery || g.world.isDisposed) return;
+  setBackdropTheme(g.world, g.scenery.backdrop, theme);
+  for (const v of g.views) if (v) setArrowColor(g.world, v, g.color);
+}
+
+/** (Re)creates the arrows and empty-cell dots from the run's state; a new board draws itself in. */
+function spawnBoard(g: Game) {
+  const l = g.layout;
+  const s = g.scenery;
+  if (!l || !s) return;
+  const intro = g.intro;
+  if (intro) g.introAge = 0;
+  g.views = g.arrows.map((a) => (a ? spawnArrow(g.world, l, s.board, a, g.color, intro ? introDelay(a) : null) : null));
+  g.dots = [];
+  for (let ci = 0; ci < TOTAL_CELLS; ci++) {
+    if (g.cellToArrowId[ci] === null) g.dots.push(spawnDot(g.world, l, s.board, Math.floor(ci / GRID_COLS), ci % GRID_COLS));
+  }
+}
+
+/** Arrow starts are spread over the first part of the draw-in. */
+const introDelay = (a: Arrow) => ((a.id % 12) / 12) * DRAW_IN_STAGGER * DRAW_IN_TIME;
+
+function clearBoard(g: Game) {
+  const w = g.world;
+  for (const v of g.views) if (v) w.despawn(v.root);
+  for (const d of g.dots) w.despawn(d);
+  for (const f of g.flights) w.despawn(f.root);
+  g.views = [];
+  g.dots = [];
+  g.flights = [];
+}
+
+function newBoard(g: Game) {
+  clearBoard(g);
+  const board = generateBoard();
+  g.arrows = board.arrows;
+  g.cellToArrowId = board.cellToArrowId;
+  g.remaining = board.count;
+  g.intro = true;
+  spawnBoard(g);
+}
+
+export function start(g: Game) {
+  if (g.phase !== 'ready') return;
+  if (g.remaining <= 0) {
+    newBoard(g);
+    g.onRemaining(g.remaining);
+  }
+  g.phase = 'playing';
+  g.world.scoreboard.startCountdown(TIME_LIMIT);
+  g.onPhase('playing');
+}
+
+/** A new board and timer (Stop, Play Again), drawing itself in. The world and its GPU view are kept. */
+export function reset(g: Game) {
+  newBoard(g);
+  g.world.scoreboard.reset(0, TIME_LIMIT);
+  g.won = false;
+  g.phase = 'ready';
+  g.onScore(0);
+  g.onTime(TIME_LIMIT);
+  g.onRemaining(g.remaining);
+  g.onPhase('ready');
+}
+
+export function dispose(g: Game) {
+  g.flights = [];
+  g.world.dispose();
+}
+
+function end(g: Game, won: boolean) {
+  g.world.scoreboard.stop();
+  g.won = won;
+  g.phase = 'over';
+  if (won) {
+    g.onWin();
+  } else {
+    // Time up: in-flight arrows are wiped and the run scores nothing (the last arrow of a win flies on).
+    for (const f of g.flights) g.world.despawn(f.root);
+    g.flights = [];
+    g.world.scoreboard.set(0);
+    g.onScore(0);
+    g.onLose();
+  }
+  g.onPhase('over');
+}
+
+export function tick(g: Game, dt: number) {
+  if (g.world.isDisposed) return;
+  introPlayed(g, dt);
+  const l = g.layout;
+  if (l && g.flights.length) {
+    // Clamped so a resume (or a long frame) finishes a flight rather than skipping it
+    const step = Math.min(dt, 0.05);
+    let kept = 0;
+    for (const flight of g.flights) if (stepFlight(g.world, l, flight, step, FLY_TIME)) g.flights[kept++] = flight;
+    g.flights.length = kept;
+  }
+  g.world.update(dt);
+}
+
+// ── Tapping ───────────────────────────────────────────────────────────
+
+/** The first arrow on `arrow`'s way out: the one that blocks it. */
+function findBlocker(g: Game, arrow: Arrow): Arrow | null {
+  const head = arrow.waypoints[arrow.waypoints.length - 1]!;
+  const dr = DIR_DR[arrow.exitDir]!;
+  const dc = DIR_DC[arrow.exitDir]!;
+  let r = head.row + dr;
+  let c = head.col + dc;
+  while (r >= 0 && r < GRID_ROWS && c >= 0 && c < GRID_COLS) {
+    const occupant = g.cellToArrowId[idx(r, c)];
+    if (occupant !== null && occupant !== undefined && occupant !== arrow.id) return g.arrows[occupant] ?? null;
+    r += dr;
+    c += dc;
+  }
+  return null;
+}
+
+/** A tap: the arrow under it flies off if its way out is clear, or shakes if it's blocked. */
+export function tap(g: Game, x: number, y: number) {
+  const l = g.layout;
+  const s = g.scenery;
+  if (!l || !s || g.phase !== 'playing') return;
+  // Cells own half the gap around them, plus a little, as on the original board
+  const lx = x - l.boardLeft + l.hitMargin;
+  const ly = y - l.boardTop + l.hitMargin;
+  if (lx < 0 || ly < 0) return;
+  const col = Math.floor(lx / l.stride);
+  const row = Math.floor(ly / l.stride);
+  if (row >= GRID_ROWS || col >= GRID_COLS) return;
+  const id = g.cellToArrowId[idx(row, col)];
+  if (id === null || id === undefined) return;
+  const arrow = g.arrows[id];
+  if (!arrow) return;
+
+  const w = g.world;
+  if (!isExitClear(g.cellToArrowId, arrow)) {
+    const view = g.views[id];
+    if (view) flashBlocked(w, view, g.color);
+    const blocker = findBlocker(g, arrow);
+    const blockerView = blocker && g.views[blocker.id];
+    if (blockerView) pulseBlocker(w, blockerView, g.color);
+    g.onBlocked();
+    return;
+  }
+
+  // Off it goes: its cells empty (each shows a dot once the tail has passed) and it flies.
+  for (const wp of arrow.waypoints) {
+    g.cellToArrowId[idx(wp.row, wp.col)] = null;
+    g.dots.push(spawnDot(w, l, s.board, wp.row, wp.col));
+  }
+  g.arrows[id] = null;
+  const view = g.views[id];
+  if (view) w.despawn(view.root);
+  g.views[id] = null;
+  g.flights.push(spawnFlight(w, l, s.board, arrow));
+
+  g.remaining -= 1;
+  g.world.scoreboard.add(POINTS_PER_ARROW);
+  g.onRemaining(g.remaining);
+  g.onClear();
+  if (g.remaining <= 0) {
+    g.world.scoreboard.set(calculateTimeBasedScore(TIME_LIMIT - g.timeLeft, TIME_LIMIT, g.score));
+    g.onScore(g.score);
+    pulseBoard(w, s.board);
+    end(g, true);
+    return;
+  }
+  g.onScore(g.score);
+}