@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/maze-runner/MazeRunnerConstants.ts

@@ -0,0 +1,65 @@
+// Maze Runner's rules, colors, timings and layout. The maze size, clock and scoring match the original
+// version (games/maze-runner), so scores carry over.
+import { getScoreBoardTop } from '../shared/EngineHud';
+import type { TiltView } from '../shared/EngineTilt';
+import { frontLight, gameWidthFor } from '../shared/EngineUtils';
+
+// ── Rules ─────────────────────────────────────────────────────────────
+
+export const GRID = 14; // 14 x 14 cells
+export const GAME_DURATION = 120; // seconds
+/** A win scores by its time against the full three minutes. */
+export const BASE_SCORE = 100;
+export const GAME_OVER_DELAY = 0.5; // the game-over card shows this long after the end, as the original game
+
+// ── Colors ────────────────────────────────────────────────────────────
+
+export const COLORS = {
+  WALLS: ['#7A4A24', '#8B4513', '#A0522D', '#9A5B2E'],
+  WALL_TOP: '#D2A06A',
+  BALL: '#4ECDC4',
+  BALL_BAND: '#FFFFFF',
+  BALL_DOT: '#2C8C86',
+  START: '#4CAF50',
+  START_INNER: '#81C784',
+  GOAL: '#FF5722',
+  GOAL_INNER: '#FF8A65'
+} as const;
+
+// ── The scene ─────────────────────────────────────────────────────────
+
+/** Directly overhead so raised walls do not obscure the maze's passages. */
+export const TILT = 0;
+/** Overhead light, with cast shadows disabled by frontLight. */
+export const LIGHT = frontLight([0, 0, 1], 0.45);
+/** A wall's thickness and height, and the ball's size, of a cell. */
+export const WALL_THICKNESS = 0.14;
+export const WALL_HEIGHT = 0.42;
+export const BALL_SIZE = 0.56;
+
+// ── Layout (view points) ──────────────────────────────────────────────
+
+const SCOREBOARD_HEIGHT = 82;
+const CONTROLS_HEIGHT = 120;
+/** The board's rim round the maze, in points: it counts toward the max width. */
+export const BORDER = 6;
+const MIN_SIZE = 240;
+const MAX_SIZE = 600; // as the original maze (the game width, at most 500, now always binds first)
+
+export type Layout = TiltView & { n: number; cell: number; size: number };
+
+/** The maze square as big as the game area allows, viewed directly overhead. */
+export function getLayout(width: number, height: number, offset: number): Layout {
+  const top = getScoreBoardTop(offset) + SCOREBOARD_HEIGHT;
+  const room = Math.max(MIN_SIZE, height - top - CONTROLS_HEIGHT);
+  // The tilted square takes size * cos(tilt) of the view's height, plus its walls' height above the far edge
+  const fromHeight = room / (Math.cos(TILT) + (WALL_HEIGHT / GRID) * Math.sin(TILT));
+  const size =
+    Math.floor(Math.max(MIN_SIZE, Math.min(MAX_SIZE, (gameWidthFor(width) - BORDER * 2) / (1 + WALL_THICKNESS / GRID), fromHeight)) / GRID) * GRID;
+  return { width, height, tilt: TILT, centerY: top + room / 2, n: GRID, cell: size / GRID, size };
+}
+
+/** A cell's centre (or any point in cells: 0.5 is the middle of the first column / row), in world units. */
+export function cellPoint(l: Layout, cx: number, cy: number): [number, number] {
+  return [cx * l.cell - l.size / 2, l.size / 2 - cy * l.cell];
+}

package/src/games/maze-runner/MazeRunnerGame.ts

@@ -0,0 +1,176 @@
+// Maze Runner's play, with no React: build a game with `createGame`, give it a layout, `start` it and
+// `tick` it every frame. Swipe anywhere to roll the ball: it rolls down a corridor until a wall, turns
+// at the next junction open the way you last swiped, and reverses at once on a swipe back. Reach the
+// exit, bottom right, inside three minutes to win (the quicker, the higher the score).
+//
+// The maze and the roll are the original version's (MazeRunnerRules.ts), rolled on the same display frames.
+import { type Camera, type DragEvent, World } from '@nayan-ui/engine';
+import { calculateTimeBasedScore } from '../../services/ScoringService';
+import type { GameTheme } from '../../services/ThemeService';
+import { aimTilted } from '../shared/EngineTilt';
+import { BASE_SCORE, GAME_DURATION, GAME_OVER_DELAY, GRID, type Layout } from './MazeRunnerConstants';
+import { generateMaze, homeRoll, roll, rollAt, swipe } from './MazeRunnerRules';
+import { buildScene, bump, celebrate, placeBall, removeScene, resetBall, type Scene, setMaze, setSceneTheme, timeUp } from './MazeRunnerScene';
+
+/** ready: the maze waits; playing: rolling; over: won or lost (the game-over card comes up a beat later, through `onCard`). */
+export type Phase = 'ready' | 'playing' | 'over';
+/** turn: a swipe taken; bump: rolled into a wall; win / lose: how it ended. */
+export type GameEvent = 'turn' | 'bump' | 'win' | 'lose';
+
+const WORLD_CAPACITY = 300; // about 60 walls, the board, pads, ball, and the bursts
+
+export function createGame(theme: GameTheme) {
+  const world = new World(WORLD_CAPACITY);
+  const camera: Camera = { eye: [0, 0, 240], target: [0, 0, 0], fov: 1, ortho: 1 };
+  const g = {
+    world,
+    camera,
+    theme,
+    layout: null as Layout | null,
+    scene: null as Scene | null,
+    phase: 'ready' as Phase,
+    open: generateMaze(GRID),
+    ball: homeRoll(),
+    /** Where the ball was last drawn (in cells), so its turn follows how far it rolled. */
+    drawn: [0.5, 0.5] as [number, number],
+    /** Running: the clock's ticking and swipes roll the ball (false from the moment it ends). */
+    running: false,
+    /** Seconds played and the score: the clock and score live in the engine (Rust), advanced by world.update. */
+    get elapsed() {
+      return GAME_DURATION - world.scoreboard.shownSeconds;
+    },
+    get score() {
+      return world.scoreboard.score;
+    },
+    won: false,
+    // UI hooks, set by the screen.
+    onPhase: (_p: Phase) => {},
+    onCard: () => {},
+    onTime: (_remaining: number) => {},
+    onEvent: (_e: GameEvent) => {}
+  };
+  world.scoreboard.reset(0, GAME_DURATION);
+  world.scoreboard.handlers = {
+    onSecond: (t) => g.onTime(t),
+    onTimeUp: () => g.running && end(g, false)
+  };
+  return g;
+}
+export type Game = ReturnType<typeof createGame>;
+
+// ── Scene ─────────────────────────────────────────────────────────────
+
+/** Lays the maze out for the view (first layout, header height, rotation): rebuilt where things stand. */
+export function setLayout(g: Game, l: Layout) {
+  if (g.scene) removeScene(g.world, g.scene);
+  g.layout = l;
+  aimTilted(g.camera, l);
+  g.scene = buildScene(g.world, l, g.theme, g.open);
+  const [x, y] = rollAt(g.ball);
+  placeBall(g.world, l, g.scene, x, y, x, y);
+  g.drawn = [x, y];
+}
+
+export function setTheme(g: Game, theme: GameTheme) {
+  g.theme = theme;
+  if (g.layout && g.scene) setSceneTheme(g.world, g.layout, g.scene, theme);
+}
+
+function drawBall(g: Game) {
+  const { layout: l, scene: s } = g;
+  if (!l || !s) return;
+  const [x, y] = rollAt(g.ball);
+  placeBall(g.world, l, s, x, y, g.drawn[0], g.drawn[1]);
+  g.drawn = [x, y];
+}
+
+/** The ball home on the start pad, still (Start, Stop, a new maze). */
+function home(g: Game) {
+  g.ball = homeRoll();
+  g.world.cancelTimers();
+  if (g.layout && g.scene) resetBall(g.world, g.layout, g.scene);
+  drawBall(g);
+}
+
+// ── Run ───────────────────────────────────────────────────────────────
+
+/** Starts on the maze already shown, the ball at the start. */
+export function start(g: Game) {
+  if (g.phase !== 'ready') return;
+  home(g);
+  g.world.scoreboard.reset();
+  g.world.scoreboard.startCountdown(GAME_DURATION);
+  g.won = false;
+  g.running = true;
+  g.phase = 'playing';
+  g.onTime(GAME_DURATION);
+  g.onPhase('playing');
+}
+
+/** Stop: the same maze, the ball back at the start, not running (as the original game). */
+export function stop(g: Game) {
+  g.running = false;
+  g.world.scoreboard.reset(0, GAME_DURATION);
+  g.won = false;
+  g.phase = 'ready';
+  home(g);
+  g.onTime(GAME_DURATION);
+  g.onPhase('ready');
+}
+
+/** Play Again: a new maze rises, the ball at the start, not running. */
+export function newMaze(g: Game) {
+  g.open = generateMaze(GRID);
+  if (g.layout && g.scene) setMaze(g.world, g.layout, g.scene, g.open, true);
+  stop(g);
+}
+
+export function dispose(g: Game) {
+  g.world.dispose();
+}
+
+export function tick(g: Game, dt: number) {
+  if (g.world.isDisposed) return;
+  if (g.running && g.layout) {
+    const { bumped, reached } = roll(g.ball, g.open, GRID, dt * 1000);
+    if (bumped) {
+      if (g.scene) bump(g.world, g.layout, g.scene);
+      g.onEvent('bump');
+    }
+    drawBall(g);
+    if (reached && reached[0] === GRID - 1 && reached[1] === GRID - 1) {
+      g.world.scoreboard.set(calculateTimeBasedScore(g.elapsed, GAME_DURATION, BASE_SCORE));
+      end(g, true);
+    }
+  }
+  g.world.update(dt);
+}
+
+/** The run's over: its feedback and the result now, the card a beat later (as the original game's half-second wait). */
+function end(g: Game, won: boolean) {
+  g.world.scoreboard.stop();
+  g.running = false;
+  g.won = won;
+  const { layout: l, scene: s } = g;
+  if (l && s) {
+    if (won) celebrate(g.world, l, s);
+    else timeUp(g.world, s);
+  }
+  g.phase = 'over';
+  g.onPhase('over');
+  g.onEvent(won ? 'win' : 'lose');
+  g.world.after(GAME_OVER_DELAY, () => g.onCard());
+}
+
+// ── The finger ────────────────────────────────────────────────────────
+
+/** Swipes anywhere: each stretch of a drag one way is a swipe, so one drag can chain turns. */
+export function drag(g: Game, e: DragEvent) {
+  if (e.phase === 'start') {
+    g.ball.anchorX = e.x;
+    g.ball.anchorY = e.y;
+    return;
+  }
+  if (!g.running) return;
+  if (swipe(g.ball, e.x, e.y)) g.onEvent('turn');
+}

package/src/games/maze-runner/MazeRunnerRules.ts

@@ -0,0 +1,161 @@
+// Maze Runner's rules, with no React or engine: the maze (carved by randomized depth-first
+// backtracking from the top-left cell, so there's exactly one way through), which sides of each cell
+// are open, and the ball's roll: along a corridor until a wall, turning at the next junction that's
+// open the way last swiped (buffered, like Pac-Man), reversing at once on a swipe backwards. Ported
+// step for step from the original version's store and UI-thread physics (games/maze-runner).
+
+/** Directions: 0 none, 1 up, 2 right, 3 down, 4 left. A cell's open sides are a bitmask (1 << (dir - 1)). */
+export const NONE = 0;
+export const UP = 1;
+export const RIGHT = 2;
+export const DOWN = 3;
+export const LEFT = 4;
+
+export const ROLL_CELLS_PER_SEC = 5;
+export const SWIPE_PX = 16; // each stretch of this many points in one direction is a swipe
+export const FRAME_MS = 16.67;
+
+export const dirDX = (d: number) => (d === RIGHT ? 1 : d === LEFT ? -1 : 0);
+export const dirDY = (d: number) => (d === UP ? -1 : d === DOWN ? 1 : 0);
+const opposite = (d: number) => (d === NONE ? NONE : ((d + 1) % 4) + 1);
+
+/** Candidates carved per maze: the hardest one is kept. */
+const CANDIDATES = 24;
+
+/** How many cells the one way through runs, top-left to bottom-right (breadth first over the open sides). */
+function routeLength(open: number[], n: number): number {
+  const dist = new Array<number>(n * n).fill(-1);
+  dist[0] = 0;
+  const queue = [0];
+  for (let q = 0; q < queue.length; q++) {
+    const i = queue[q]!;
+    const x = i % n;
+    for (let direction = 0; direction < 4; direction++) {
+      const bit = 1 << direction;
+      const j = direction === 0 ? i - n : direction === 1 ? i + 1 : direction === 2 ? i + n : i - 1;
+      if (open[i]! & bit && dist[j] === -1 && !(bit === 2 && x === n - 1) && !(bit === 8 && x === 0)) {
+        dist[j] = dist[i]! + 1;
+        queue.push(j);
+      }
+    }
+  }
+  return dist[n * n - 1]!;
+}
+
+/** Junctions along the board: cells with three or more ways out, each a choice to get wrong. */
+const junctions = (open: number[]) => open.reduce((k, o) => k + ((o & 1) + ((o >> 1) & 1) + ((o >> 2) & 1) + ((o >> 3) & 1) >= 3 ? 1 : 0), 0);
+
+/** A fresh maze: the hardest of several carved ones, by the length of the way through and its choices. */
+export function generateMaze(n: number): number[] {
+  let best: number[] = [];
+  let bestScore = -1;
+  for (let c = 0; c < CANDIDATES; c++) {
+    const open = carveMaze(n);
+    const score = routeLength(open, n) + junctions(open) * 0.5;
+    if (score > bestScore) {
+      best = open;
+      bestScore = score;
+    }
+  }
+  return best;
+}
+
+/** One maze: each cell's open sides (row-major), carved as the original store carved it. */
+function carveMaze(n: number): number[] {
+  const open = new Array<number>(n * n).fill(0);
+  const visited = new Uint8Array(n * n);
+  const stack = [0];
+  const candidates = new Int32Array(4);
+  visited[0] = 1;
+  while (stack.length) {
+    const current = stack[stack.length - 1]!;
+    const x = current % n,
+      y = Math.floor(current / n);
+    let count = 0;
+    if (y > 0 && !visited[current - n]) candidates[count++] = current - n;
+    if (x < n - 1 && !visited[current + 1]) candidates[count++] = current + 1;
+    if (y < n - 1 && !visited[current + n]) candidates[count++] = current + n;
+    if (x > 0 && !visited[current - 1]) candidates[count++] = current - 1;
+    if (!count) {
+      stack.pop();
+      continue;
+    }
+    const next = candidates[Math.floor(Math.random() * count)]!;
+    if (next === current - 1) {
+      open[current]! |= 8;
+      open[next]! |= 2;
+    } else if (next === current + 1) {
+      open[current]! |= 2;
+      open[next]! |= 8;
+    } else if (next === current - n) {
+      open[current]! |= 1;
+      open[next]! |= 4;
+    } else {
+      open[current]! |= 4;
+      open[next]! |= 1;
+    }
+    visited[next] = 1;
+    stack.push(next);
+  }
+  return open;
+}
+
+export const isOpen = (open: number[], n: number, x: number, y: number, d: number) => ((open[y * n + x] ?? 0) & (1 << (d - 1))) !== 0;
+
+/** The ball's roll: the cell it last centred on, how far (0..1) it's gone toward the next, and which way. */
+export type Roll = { cx: number; cy: number; p: number; dir: number; queued: number; anchorX: number; anchorY: number };
+export const homeRoll = (): Roll => ({ cx: 0, cy: 0, p: 0, dir: NONE, queued: NONE, anchorX: 0, anchorY: 0 });
+
+/** A finger moved to (x, y): a swipe once it's gone SWIPE_PX one way from where the last began. Returns whether a new way was taken. */
+export function swipe(r: Roll, x: number, y: number): boolean {
+  const dx = x - r.anchorX;
+  const dy = y - r.anchorY;
+  const ax = Math.abs(dx);
+  const ay = Math.abs(dy);
+  if (ax < SWIPE_PX && ay < SWIPE_PX) return false;
+  const d = ax > ay ? (dx > 0 ? RIGHT : LEFT) : dy > 0 ? DOWN : UP;
+  r.anchorX = x;
+  r.anchorY = y;
+  if (d === r.queued || (d === r.dir && r.queued === NONE)) return false;
+  r.queued = d;
+  return true;
+}
+
+/** One display frame of rolling. Says whether the ball bumped a wall, and the cell it reached (if it reached one). */
+export function roll(r: Roll, open: number[], n: number, frameMs: number): { bumped: boolean; reached: [number, number] | null } {
+  let bumped = false;
+  let reached: [number, number] | null = null;
+  // Reverse mid-corridor at once
+  if (r.dir !== NONE && r.queued !== NONE && r.p > 0 && r.queued === opposite(r.dir)) {
+    r.cx += dirDX(r.dir);
+    r.cy += dirDY(r.dir);
+    r.p = 1 - r.p;
+    r.dir = r.queued;
+    r.queued = NONE;
+  }
+  // At a cell centre: take a buffered turn if that way is open, stop at a wall
+  if (r.p === 0) {
+    if (r.queued !== NONE && isOpen(open, n, r.cx, r.cy, r.queued)) {
+      r.dir = r.queued;
+      r.queued = NONE;
+    }
+    if (r.dir !== NONE && !isOpen(open, n, r.cx, r.cy, r.dir)) {
+      r.dir = NONE;
+      bumped = true;
+    }
+  }
+  if (r.dir !== NONE) {
+    // A long frame is clamped to three: never a fast-forward
+    r.p += (ROLL_CELLS_PER_SEC * Math.min(frameMs, FRAME_MS * 3)) / 1000;
+    if (r.p >= 1) {
+      r.cx += dirDX(r.dir);
+      r.cy += dirDY(r.dir);
+      r.p = 0;
+      reached = [r.cx, r.cy];
+    }
+  }
+  return { bumped, reached };
+}
+
+/** Where the ball is drawn, in cells (its centre: 0.5 is the middle of the first column / row). */
+export const rollAt = (r: Roll): [number, number] => [r.cx + dirDX(r.dir) * r.p + 0.5, r.cy + dirDY(r.dir) * r.p + 0.5];

package/src/games/maze-runner/MazeRunnerScene.ts

@@ -0,0 +1,245 @@
+// Everything Maze Runner draws: a maze board (themed, as the original board) walled with wooden walls that
+// stand up off it, a green start pad, an orange exit pad with a ring pulsing over it, and the striped
+// ball, which really rolls (it turns as it goes, so its stripe shows the way it's rolling). Seen from
+// directly overhead (shared/EngineTilt with zero tilt, one world unit per point).
+// Walls along one line are joined into one, so a maze is about 60 walls; every wall is
+// the built-in rounded box (one instanced draw).
+import { type Color, effects, type Entity, extrude, type Model, Path, type Quat, quat, recolor, shapeGeometry, type World } from '@nayan-ui/engine';
+import { PRIMARY_COLOR } from '../../services/GamesConstants';
+import type { GameTheme } from '../../services/ThemeService';
+import { setBackdropTheme, spawnBackdrop } from '../shared/EngineBackdrop';
+import { cacheGameAsset, createGameMesh as createShape } from '../shared/EngineMeshes';
+import { placeTiltedBackdrop } from '../shared/EngineTilt';
+import { toColor } from '../shared/EngineUtils';
+import { BALL_SIZE, BORDER, cellPoint, COLORS, type Layout, WALL_HEIGHT, WALL_THICKNESS } from './MazeRunnerConstants';
+import { DOWN, isOpen, RIGHT } from './MazeRunnerRules';
+
+const meshes = new Map<string, Model>();
+const cached = (key: string, build: () => Model) => {
+  let m = meshes.get(key);
+  if (!m) {
+    m = cacheGameAsset('maze-runner/MazeRunnerScene:' + key, build);
+    meshes.set(key, m);
+  }
+  return m;
+};
+const STAND_UP = quat.x(Math.PI / 2);
+const BOARD_DEPTH = 8;
+const BACKDROP_DEPTH = 25;
+const PAD_HEIGHT = 0.05; // of a cell
+/** The ball lit warm and a little self-lit when it reaches the exit. */
+const WIN_GLOW: Color = [1.3, 1.15, 0.55, 1];
+const RISE_STEP = 0.012; // a new maze's walls rise from the start outward, this much a cell
+
+// ── Meshes ────────────────────────────────────────────────────────────
+
+/** The ball: teal with a white band round it and two dark spots, so its roll shows. */
+const ballMesh = () =>
+  cached('mr-ball', () => {
+    const teal = toColor(COLORS.BALL);
+    const band = toColor(COLORS.BALL_BAND);
+    const dot = toColor(COLORS.BALL_DOT);
+    return createShape(
+      recolor(shapeGeometry('sphere'), ({ position: [x, y, z] }) => {
+        const r = Math.hypot(x, y, z) || 1;
+        if (Math.abs(z / r) < 0.2) return band;
+        if (Math.abs(x / r) > 0.86) return dot;
+        return teal;
+      }),
+      { shine: 0.9 }
+    );
+  });
+
+const panelMesh = (size: number, radius: number) =>
+  cached(`mr-panel:${size}:${radius}`, () =>
+    createShape(extrude(new Path().addRoundedRect(-size / 2, -size / 2, size, size, radius), { depth: BOARD_DEPTH }), { shine: 0.2 })
+  );
+
+// ── Spawning ──────────────────────────────────────────────────────────
+
+export type Scene = {
+  backdrop: Entity;
+  floor: Entity;
+  inner: Entity | null;
+  walls: Entity[];
+  pads: Entity[];
+  ring: Entity;
+  ball: Entity;
+  /** The ball's turn so far, from rolling. */
+  spin: Quat;
+};
+
+const floorColor = (theme: GameTheme): Color => toColor(theme.mode === 'classic' ? `${PRIMARY_COLOR}30` : theme.BOARD.SURFACE);
+
+/** A pad on a cell: a flat disc a little proud of the floor. */
+const pad = (world: World, l: Layout, cx: number, cy: number, size: number, color: string, z = 0) => {
+  const [x, y] = cellPoint(l, cx + 0.5, cy + 0.5);
+  const h = l.cell * PAD_HEIGHT;
+  return world.spawn({
+    mesh: 'cylinder',
+    position: [x, y, h / 2 + z],
+    rotation: STAND_UP,
+    scale: [l.cell * size, h, l.cell * size],
+    color: toColor(color),
+    pickable: false
+  });
+};
+
+export function buildScene(world: World, l: Layout, theme: GameTheme, open: number[]): Scene {
+  const backdrop = spawnBackdrop(world, l.width, l.height, -BACKDROP_DEPTH, theme);
+  placeTiltedBackdrop(world, backdrop, l, BACKDROP_DEPTH);
+  const classic = theme.mode === 'classic';
+  const floor = world.spawn({
+    mesh: panelMesh(l.size + BORDER * 2, classic ? 12 : 8),
+    position: [0, 0, -BOARD_DEPTH / 2],
+    color: floorColor(theme),
+    pickable: false
+  });
+  const inner = classic
+    ? world.spawn({ mesh: panelMesh(l.size, 8), position: [0, 0, -BOARD_DEPTH / 2 + 0.3], color: toColor(`${PRIMARY_COLOR}25`), pickable: false })
+    : null;
+  const last = l.n - 1;
+  const pads = [
+    pad(world, l, 0, 0, 0.72, COLORS.START),
+    pad(world, l, 0, 0, 0.32, COLORS.START_INNER, l.cell * PAD_HEIGHT),
+    pad(world, l, last, last, 0.72, COLORS.GOAL),
+    pad(world, l, last, last, 0.32, COLORS.GOAL_INNER, l.cell * PAD_HEIGHT)
+  ];
+  // A ring hovering over the exit, breathing as the original marker did
+  const [gx, gy] = cellPoint(l, last + 0.5, last + 0.5);
+  const ring = world.spawn({
+    mesh: 'torus',
+    position: [gx, gy, l.cell * 0.22],
+    rotation: STAND_UP,
+    scale: l.cell * 0.62,
+    color: toColor(COLORS.GOAL),
+    pickable: false
+  });
+  world.animate(ring, { scale: l.cell * 0.62 * 1.12 }, { duration: 0.9, easing: 'easeInOut', repeat: 'forever', yoyo: true });
+  const d = l.cell * BALL_SIZE;
+  const ball = world.spawn({ mesh: ballMesh(), scale: d, pickable: false });
+  const s: Scene = { backdrop, floor, inner, walls: [], pads, ring, ball, spin: [0, 0, 0, 1] };
+  setMaze(world, l, s, open, false);
+  return s;
+}
+
+export function removeScene(world: World, s: Scene) {
+  for (const e of [s.backdrop, s.floor, s.inner, ...s.walls, ...s.pads, s.ring, s.ball]) if (e != null) world.despawn(e);
+}
+
+export function setSceneTheme(world: World, l: Layout, s: Scene, theme: GameTheme) {
+  setBackdropTheme(world, s.backdrop, theme);
+  const classic = theme.mode === 'classic';
+  world.set(s.floor, { mesh: panelMesh(l.size + BORDER * 2, classic ? 12 : 8), color: floorColor(theme) });
+  if (s.inner != null) world.set(s.inner, { scale: classic ? 1 : 0 });
+}
+
+/**
+ * The maze's walls: every closed side, those along one line joined end to end. Each runs along a line
+ * between cells (row lines across, column lines down), from `from` to `to` (in cells).
+ */
+function wallRuns(open: number[], n: number) {
+  const runs: { across: boolean; line: number; from: number; to: number }[] = [];
+  const closed = (across: boolean, line: number, i: number) => {
+    // A row line's piece above cell (i, line); a column line's piece left of cell (line, i). The rim is always closed.
+    if (line === 0 || line === n) return true;
+    return across ? !isOpen(open, n, i, line - 1, DOWN) : !isOpen(open, n, line - 1, i, RIGHT);
+  };
+  for (const across of [true, false])
+    for (let line = 0; line <= n; line++) {
+      let start = -1;
+      for (let i = 0; i <= n; i++) {
+        const c = i < n && closed(across, line, i);
+        if (c && start < 0) start = i;
+        if (!c && start >= 0) {
+          runs.push({ across, line, from: start, to: i });
+          start = -1;
+        }
+      }
+    }
+  return runs;
+}
+
+/** Builds a maze's walls; on a new maze they rise out of the board, from the start corner outward. */
+export function setMaze(world: World, l: Layout, s: Scene, open: number[], animate: boolean) {
+  for (const w of s.walls) world.despawn(w);
+  s.walls = [];
+  const t = l.cell * WALL_THICKNESS;
+  const h = l.cell * WALL_HEIGHT;
+  wallRuns(open, l.n).forEach((r, k) => {
+    const mid = (r.from + r.to) / 2;
+    const [x, y] = r.across ? cellPoint(l, mid, r.line) : cellPoint(l, r.line, mid);
+    const len = (r.to - r.from) * l.cell + t;
+    const scale: [number, number, number] = r.across ? [len, t, h] : [t, len, h];
+    const color = toColor(COLORS.WALLS[k % COLORS.WALLS.length]!);
+    const e = world.spawn({
+      mesh: 'roundedBox',
+      position: [x, y, animate ? 0 : h / 2],
+      scale: animate ? [scale[0], scale[1], 0.01] : scale,
+      color,
+      pickable: false
+    });
+    if (animate) {
+      const delay = Math.hypot(r.across ? mid : r.line, r.across ? r.line : mid) * RISE_STEP * l.n;
+      world.animate(e, { position: [x, y, h / 2], scale }, { duration: 0.28, delay: delay * 0.25, easing: 'back' });
+    }
+    s.walls.push(e);
+  });
+}
+
+// ── The ball ──────────────────────────────────────────────────────────
+
+/** The ball at a point (in cells), turned by how far it rolled to get there from (px, py). */
+export function placeBall(world: World, l: Layout, s: Scene, cx: number, cy: number, px: number, py: number) {
+  const r = (l.cell * BALL_SIZE) / 2;
+  const [x, y] = cellPoint(l, cx, cy);
+  const [ox, oy] = cellPoint(l, px, py);
+  const dx = x - ox;
+  const dy = y - oy;
+  const dist = Math.hypot(dx, dy);
+  // Rolling on the board turns it about the axis across its way (up × motion)
+  if (dist > 1e-6) s.spin = quat.multiply(quat.axisAngle(-dy / dist, dx / dist, 0, dist / r), s.spin);
+  world.set(s.ball, { position: [x, y, r], rotation: s.spin });
+}
+
+/** Back to the start's look (a new game, or the preview). */
+export function resetBall(world: World, l: Layout, s: Scene) {
+  world.stopAnimation(s.ball);
+  world.set(s.ball, { scale: l.cell * BALL_SIZE, color: [1, 1, 1, 1] });
+}
+
+/** It ran into a wall: a little jolt. */
+export function bump(world: World, l: Layout, s: Scene) {
+  world.animate(s.ball, { shake: l.cell * 0.06 }, { duration: 0.18 });
+}
+
+/** The exit reached: the ball turns gold with a pop, and confetti bursts over the maze. */
+export function celebrate(world: World, l: Layout, s: Scene) {
+  const d = l.cell * BALL_SIZE;
+  world.set(s.ball, { color: WIN_GLOW });
+  world.animate(s.ball, [{ scale: d * 1.5, at: 0.4 }, { scale: d * 1.15 }], { duration: 0.5, easing: 'easeOut' });
+  const [gx, gy] = cellPoint(l, l.n - 0.5, l.n - 0.5);
+  effects.sparkle(world, {
+    position: [gx, gy, l.cell],
+    count: 30,
+    size: l.cell * 0.12,
+    speed: l.cell * 5,
+    lifetime: 1,
+    gravity: -l.cell * 6,
+    colors: ['#FFD700', '#4CAF50', '#2196F3', '#FF5722'].map((c) => toColor(c))
+  });
+  effects.confetti(world, {
+    position: [0, 0, l.cell],
+    count: 50,
+    size: l.cell * 0.14,
+    speed: l.size * 1.3,
+    lifetime: 1.3,
+    gravity: -l.size * 2.2,
+    colors: ['#FFD700', '#E91E63', '#4ECDC4', '#FFEB3B'].map((c) => toColor(c))
+  });
+}
+
+/** Out of time: the ball dims where it stopped. */
+export function timeUp(world: World, s: Scene) {
+  world.animate(s.ball, { color: [0.55, 0.55, 0.6, 1] }, { duration: 0.4 });
+}