@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/candy-crush/CandyCrushGame.ts

@@ -0,0 +1,477 @@
+// Candy Crush's rules, with no React: build a run with `createGame`, give it a layout, `start` it and
+// `tick` it every frame. Swipe a candy into a neighbour; the swap stays if it lines up 3 or more of a
+// color (in a row or column), else they bump and go back. Matches clear for 50 a candy, the candies
+// above fall into the gaps, new ones drop in, and any matches that makes cascade at 1.25x per step.
+// Lining up 5 leaves a color bomb: swap it with any candy to clear every candy of that color.
+// Score as much as you can before the timer runs out (every finished run counts as a win).
+import { type Camera, type Entity, type Vec3, World } from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import { introPlayed } from '../shared/EngineUtils';
+import {
+  BOMB,
+  BOMB_MATCH,
+  BOMB_MULTIPLIER,
+  CANDY_TYPES,
+  CELL_GAP,
+  CLEAR_RIPPLE,
+  COMBO_MULTIPLIER,
+  FALL_SPRING,
+  FALL_TIME,
+  GRID_SIZE,
+  INTRO_COL_STAGGER,
+  INTRO_ROW_STAGGER,
+  type Layout,
+  LIFT_SCALE,
+  LIFT_SPRING,
+  MATCH_TIME,
+  MIN_MATCH,
+  NUDGE_DISTANCE,
+  NUDGE_SPRING,
+  NUDGE_TIME,
+  POINTS_PER_CANDY,
+  RETURN_SPRING,
+  SWAP_TIME,
+  TIME_LIMIT,
+  WARNING_TIMES,
+  ZAP_TIME
+} from './CandyCrushConstants';
+import {
+  buildScenery,
+  candyPosition,
+  crushCandy,
+  dragZ,
+  popInBomb,
+  removeScenery,
+  type Scenery,
+  setSceneryTheme,
+  spawnCandy,
+  zap
+} from './CandyCrushScene';
+
+export type Phase = 'ready' | 'playing' | 'over';
+export type Direction = 'up' | 'down' | 'left' | 'right';
+
+type Candy = { type: number; row: number; col: number; root: Entity | null };
+type Grid = (Candy | null)[];
+
+const WORLD_CAPACITY = 1000; // 49 candies (a color bomb is 7 parts), candies on their way out, zaps, scenery, bursts
+
+const at = (row: number, col: number) => row * GRID_SIZE + col;
+const randomType = () => Math.floor(Math.random() * CANDY_TYPES);
+
+/** Would a candy of `type` at (row, col) line up 3 with what's already placed? */
+function wouldMatch(grid: Grid, row: number, col: number, type: number) {
+  const run = (dr: number, dc: number) => {
+    let n = 0;
+    for (let r = row + dr, c = col + dc; r >= 0 && r < GRID_SIZE && c >= 0 && c < GRID_SIZE; r += dr, c += dc) {
+      if (grid[at(r, c)]?.type !== type) break;
+      n++;
+    }
+    return n;
+  };
+  return 1 + run(0, -1) + run(0, 1) >= MIN_MATCH || 1 + run(-1, 0) + run(1, 0) >= MIN_MATCH;
+}
+
+/** A random board with (almost always) no matches to start: each cell gets 10 tries at a safe color. */
+function generateGrid(): Grid {
+  const grid: Grid = new Array(GRID_SIZE * GRID_SIZE).fill(null);
+  for (let row = 0; row < GRID_SIZE; row++) {
+    for (let col = 0; col < GRID_SIZE; col++) {
+      let type = randomType();
+      for (let tries = 1; tries < 10 && wouldMatch(grid, row, col, type); tries++) type = randomType();
+      grid[at(row, col)] = { type, row, col, root: null };
+    }
+  }
+  return grid;
+}
+
+/** Every candy in a straight run of 3+ of one color (across rows, then down columns), and the runs of 5+ (each leaves a color bomb). */
+function findMatches(grid: Grid): { matched: Candy[]; fives: Candy[][] } {
+  const found = new Set<Candy>();
+  const fives: Candy[][] = [];
+  const scan = (cell: (line: number, i: number) => Candy | null) => {
+    for (let line = 0; line < GRID_SIZE; line++) {
+      let i = 0;
+      while (i < GRID_SIZE) {
+        const first = cell(line, i);
+        let end = i + 1;
+        while (first && first.type !== BOMB && end < GRID_SIZE && cell(line, end)?.type === first.type) end++;
+        if (first && first.type !== BOMB && end - i >= MIN_MATCH) {
+          for (let k = i; k < end; k++) found.add(cell(line, k)!);
+          if (end - i >= BOMB_MATCH) fives.push(Array.from({ length: end - i }, (_, k) => cell(line, i + k)!));
+        }
+        i = end;
+      }
+    }
+  };
+  scan((row, col) => grid[at(row, col)] ?? null);
+  scan((col, row) => grid[at(row, col)] ?? null);
+  return { matched: [...found], fives };
+}
+
+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 g = {
+    world,
+    camera,
+    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;
+    },
+    /** Game clock, seconds: drives the delayed steps (they pause with the frame loop). */
+    time: 0,
+    grid: generateGrid(),
+    /** A swap is resolving (matches, falls, cascades): no new moves until it settles. */
+    busy: false,
+    combo: 0,
+    /** The candy under the finger. */
+    dragging: null as Candy | null,
+    /** The next board to appear rains 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) => {},
+    onSelect: () => {},
+    onSwap: () => {},
+    onInvalid: () => {},
+    onMatch: (_combo: number) => {},
+    /** A color bomb was made. */
+    onBomb: () => {},
+    /** A color bomb went off. */
+    onBlast: () => {},
+    onWarning: (_secondsLeft: number) => {},
+    onTimeUp: () => {}
+  };
+  world.scoreboard.reset(0, TIME_LIMIT);
+  world.scoreboard.handlers = {
+    onSecond: (t) => {
+      g.onTime(t);
+      if (t > 0 && (WARNING_TIMES as readonly number[]).includes(t)) g.onWarning(t);
+    },
+    onTimeUp: () => g.phase === 'playing' && end(g)
+  };
+  return g;
+}
+export type Game = ReturnType<typeof createGame>;
+
+const after = (g: Game, seconds: number, run: () => void) => g.world.after(seconds, run);
+
+// ── Scene ─────────────────────────────────────────────────────────────
+
+/** 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) {
+  if (g.scenery) removeScenery(g.world, g.scenery);
+  g.layout = l;
+  g.camera.ortho = l.height / 2;
+  g.scenery = buildScenery(g.world, l, g.theme);
+  g.dragging = null;
+  spawnAll(g);
+}
+
+/** A new theme: the background and board are repainted; the candies and the run carry on. */
+export function setTheme(g: Game, theme: GameTheme) {
+  g.theme = theme;
+  if (g.layout && g.scenery && !g.world.isDisposed) setSceneryTheme(g.world, g.layout, g.scenery, theme);
+}
+
+function despawnCandy(g: Game, c: Candy) {
+  if (c.root != null) g.world.despawn(c.root); // its parts go with it
+  c.root = null;
+}
+
+/** (Re)creates every candy at its cell; a new board rains in, column by column, bottom rows first. */
+function spawnAll(g: Game) {
+  const l = g.layout;
+  if (!l) return;
+  const intro = g.intro;
+  if (intro) g.introAge = 0;
+  for (const c of g.grid) {
+    if (!c) continue;
+    despawnCandy(g, c);
+    if (!intro) {
+      c.root = spawnCandy(g.world, l, c.type, candyPosition(l, c.row, c.col), 1);
+      continue;
+    }
+    c.root = spawnCandy(g.world, l, c.type, candyPosition(l, c.row - 2, c.col), 0);
+    const delay = c.col * INTRO_COL_STAGGER + (GRID_SIZE - 1 - c.row) * INTRO_ROW_STAGGER;
+    g.world.animate(c.root, { position: candyPosition(l, c.row, c.col) }, { spring: FALL_SPRING, delay });
+    g.world.animate(c.root, { scale: 1 }, { duration: FALL_TIME * 0.6, delay, easing: 'back' });
+  }
+}
+
+// ── Run ───────────────────────────────────────────────────────────────
+
+export function start(g: Game) {
+  if (g.phase !== 'ready') return;
+  g.phase = 'playing';
+  g.world.scoreboard.startCountdown(TIME_LIMIT);
+  g.onPhase('playing');
+}
+
+/** A new board and timer (Stop, Play Again). The world, and the GPU view drawing it, are kept. */
+export function reset(g: Game) {
+  g.world.cancelTimers(); // a cascade in progress stops here, so it can't touch the new board
+  for (const c of g.grid) if (c) despawnCandy(g, c);
+  g.grid = generateGrid();
+  g.busy = false;
+  g.combo = 0;
+  g.dragging = null;
+  g.intro = true;
+  spawnAll(g);
+  g.world.scoreboard.reset(0, TIME_LIMIT);
+  g.phase = 'ready';
+  g.onScore(0);
+  g.onTime(TIME_LIMIT);
+  g.onPhase('ready');
+}
+
+export function dispose(g: Game) {
+  g.world.cancelTimers();
+  g.world.dispose();
+}
+
+/** Time up. A cascade still resolving plays out on screen, but scores no more. */
+function end(g: Game) {
+  g.world.scoreboard.stop();
+  if (g.dragging) release(g);
+  g.phase = 'over';
+  g.onTimeUp();
+  g.onPhase('over');
+}
+
+export function tick(g: Game, dt: number) {
+  if (g.world.isDisposed) return;
+  introPlayed(g, dt);
+  g.time += dt;
+  g.world.update(dt);
+}
+
+// ── Touch ─────────────────────────────────────────────────────────────
+
+/** The board cell under a view point, or null (cells own the gap after them, as on the original board). */
+function cellAt(l: Layout, x: number, y: number): [number, number] | null {
+  const col = Math.floor((x - l.boardLeft - CELL_GAP) / l.step);
+  const row = Math.floor((y - l.boardTop - CELL_GAP) / l.step);
+  return row < 0 || row >= GRID_SIZE || col < 0 || col >= GRID_SIZE ? null : [row, col];
+}
+
+/** Finger down: the candy under it lifts and follows the finger. */
+export function touchStart(g: Game, x: number, y: number) {
+  const l = g.layout;
+  if (!l || g.phase !== 'playing' || g.busy) return;
+  const cell = cellAt(l, x, y);
+  const candy = cell ? g.grid[at(cell[0], cell[1])] : null;
+  if (!candy || candy.root == null) return;
+  g.dragging = candy;
+  g.onSelect();
+  g.world.stopAnimation(candy.root);
+  g.world.set(candy.root, { position: candyPosition(l, candy.row, candy.col, dragZ(l)) });
+  g.world.animate(candy.root, { scale: LIFT_SCALE }, { spring: LIFT_SPRING });
+}
+
+export function touchMove(g: Game, dx: number, dy: number) {
+  const l = g.layout;
+  const c = g.dragging;
+  if (!l || !c || c.root == null) return;
+  const home = candyPosition(l, c.row, c.col, dragZ(l));
+  g.world.set(c.root, { position: [home[0] + dx, home[1] - dy, home[2]] });
+}
+
+/** Finger up: a long enough drag swaps toward its main direction; otherwise the candy settles back. */
+export function touchEnd(g: Game, dx: number, dy: number, cancelled = false) {
+  const c = g.dragging;
+  const l = g.layout;
+  if (!c || !l) return;
+  g.dragging = null;
+  const ax = Math.abs(dx);
+  const ay = Math.abs(dy);
+  if (!cancelled && g.phase === 'playing' && Math.max(ax, ay) > l.swipeThreshold) {
+    swap(g, c, ax > ay ? (dx > 0 ? 'right' : 'left') : dy > 0 ? 'down' : 'up');
+  } else {
+    settle(g, c);
+  }
+}
+
+function release(g: Game) {
+  const c = g.dragging;
+  g.dragging = null;
+  if (c) settle(g, c);
+}
+
+/** Springs a candy back to its cell at rest size. */
+function settle(g: Game, c: Candy) {
+  const l = g.layout;
+  if (!l || c.root == null) return;
+  g.world.animate(c.root, { position: candyPosition(l, c.row, c.col) }, { spring: RETURN_SPRING });
+  g.world.animate(c.root, { scale: 1 }, { spring: RETURN_SPRING });
+}
+
+const STEP: Record<Direction, [number, number]> = { up: [-1, 0], down: [1, 0], left: [0, -1], right: [0, 1] };
+
+function place(g: Game, c: Candy, row: number, col: number) {
+  c.row = row;
+  c.col = col;
+  g.grid[at(row, col)] = c;
+}
+
+function swap(g: Game, a: Candy, dir: Direction) {
+  const l = g.layout!;
+  const w = g.world;
+  const [dr, dc] = STEP[dir];
+  const row = a.row + dr;
+  const col = a.col + dc;
+  const b = row >= 0 && row < GRID_SIZE && col >= 0 && col < GRID_SIZE ? g.grid[at(row, col)] : null;
+  if (!b || g.busy) {
+    if (!b && !g.busy) g.onInvalid();
+    settle(g, a);
+    return;
+  }
+  const [ar, ac] = [a.row, a.col];
+  place(g, a, row, col);
+  place(g, b, ar, ac);
+  const bomb = a.type === BOMB ? a : b.type === BOMB ? b : null;
+
+  if (bomb || findMatches(g.grid).matched.length) {
+    // The two glide past each other (the dragged one from under the finger), then the board resolves.
+    g.busy = true;
+    g.combo = 0;
+    if (a.root != null) {
+      w.animate(a.root, { position: candyPosition(l, a.row, a.col) }, { duration: SWAP_TIME, easing: 'easeOut' });
+      w.animate(a.root, { scale: 1 }, { spring: RETURN_SPRING });
+    }
+    if (b.root != null) w.animate(b.root, { position: candyPosition(l, b.row, b.col) }, { duration: SWAP_TIME, easing: 'easeOut' });
+    g.onSwap();
+    after(g, SWAP_TIME, () => (bomb ? blastColor(g, bomb, bomb === a ? b : a) : resolve(g, [a, b])));
+    return;
+  }
+
+  // No match: undo it. The dragged candy springs home and the other bumps toward it and back.
+  place(g, b, row, col);
+  place(g, a, ar, ac);
+  settle(g, a);
+  const root = b.root;
+  if (root != null) {
+    const home = candyPosition(l, b.row, b.col);
+    const bump: Vec3 = [home[0] - dc * NUDGE_DISTANCE * l.step, home[1] + dr * NUDGE_DISTANCE * l.step, home[2]];
+    w.animate(root, { position: bump }, { duration: NUDGE_TIME, easing: 'easeOut' }).then(() => {
+      if (b.root === root && g.dragging !== b) w.animate(root, { position: home }, { spring: NUDGE_SPRING });
+    });
+  }
+  g.onInvalid();
+}
+
+// ── Resolving ─────────────────────────────────────────────────────────
+
+/**
+ * Clears the board's matches, scores them, then drops candies in; repeats until nothing matches. Each
+ * run of 5+ leaves a color bomb: where the swapped candy (`moved`) landed, else in the run's middle.
+ */
+function resolve(g: Game, moved: readonly Candy[] = []) {
+  const l = g.layout;
+  const { matched, fives } = findMatches(g.grid);
+  if (!l || !matched.length) {
+    g.busy = false;
+    g.combo = 0;
+    return;
+  }
+  g.combo++;
+  if (g.phase === 'playing') {
+    g.onScore(g.world.scoreboard.add(Math.floor(matched.length * POINTS_PER_CANDY * Math.pow(COMBO_MULTIPLIER, g.combo - 1))));
+  }
+  g.onMatch(g.combo);
+
+  const bombs = new Set(fives.map((run) => run.find((c) => moved.includes(c)) ?? run[Math.floor(run.length / 2)]!));
+  const w = g.world;
+  // Clears ripple out from where the swap landed (a cascade's, from its first match), as in Block Blast
+  const origin = moved.find((c) => matched.includes(c)) ?? matched[0]!;
+  for (const c of matched) {
+    if (bombs.has(c)) continue;
+    g.grid[at(c.row, c.col)] = null;
+    crush(g, l, c, Math.hypot(c.row - origin.row, c.col - origin.col) * CLEAR_RIPPLE);
+  }
+  for (const c of bombs) {
+    if (c.root != null) w.despawn(c.root);
+    c.type = BOMB;
+    c.root = spawnCandy(w, l, BOMB, candyPosition(l, c.row, c.col), 1);
+    popInBomb(w, c.root);
+  }
+  if (bombs.size) g.onBomb();
+  const ripple = Math.max(...matched.map((c) => Math.hypot(c.row - origin.row, c.col - origin.col))) * CLEAR_RIPPLE;
+  after(g, MATCH_TIME + ripple, () => {
+    drop(g);
+    after(g, FALL_TIME, () => resolve(g));
+  });
+}
+
+/** A candy leaves the board: it crushes (after `delay`) and is despawned once gone. */
+function crush(g: Game, l: Layout, c: Candy, delay: number) {
+  const root = c.root;
+  c.root = null;
+  if (root == null) return;
+  crushCandy(g.world, l, root, c.type, candyPosition(l, c.row, c.col), MATCH_TIME * 0.95, delay).then(() => {
+    g.world.despawn(root);
+  });
+}
+
+/**
+ * A color bomb swapped with a candy: every candy of that color is zapped and crushed with the bomb
+ * (another bomb: every candy on the board), at double points; then the board falls and resolves.
+ */
+function blastColor(g: Game, bomb: Candy, other: Candy) {
+  const l = g.layout;
+  if (!l) return;
+  const all = other.type === BOMB;
+  const targets = g.grid.filter((c): c is Candy => !!c && c !== bomb && (all || c.type === other.type));
+  g.combo = 1;
+  if (g.phase === 'playing') g.onScore(g.world.scoreboard.add((targets.length + 1) * POINTS_PER_CANDY * BOMB_MULTIPLIER));
+  g.onBlast();
+  const from = candyPosition(l, bomb.row, bomb.col);
+  const stagger = Math.min(0.012, 0.3 / Math.max(1, targets.length));
+  targets.forEach((c, i) => {
+    zap(g.world, l, from, candyPosition(l, c.row, c.col), all ? BOMB : c.type, i * stagger);
+    g.grid[at(c.row, c.col)] = null;
+    crush(g, l, c, ZAP_TIME + i * stagger);
+  });
+  g.grid[at(bomb.row, bomb.col)] = null;
+  crush(g, l, bomb, ZAP_TIME);
+  after(g, ZAP_TIME + targets.length * stagger + MATCH_TIME, () => {
+    drop(g);
+    after(g, FALL_TIME, () => resolve(g));
+  });
+}
+
+/** Gravity per column: the candies left fall to the bottom, new ones grow in as they drop into the top. */
+function drop(g: Game) {
+  const l = g.layout;
+  if (!l) return;
+  const w = g.world;
+  for (let col = 0; col < GRID_SIZE; col++) {
+    let row = GRID_SIZE - 1;
+    for (let r = GRID_SIZE - 1; r >= 0; r--) {
+      const c = g.grid[at(r, col)];
+      if (!c) continue;
+      g.grid[at(r, col)] = null;
+      place(g, c, row, col);
+      if (r !== row && c.root != null) w.animate(c.root, { position: candyPosition(l, row, col) }, { spring: FALL_SPRING });
+      row--;
+    }
+    for (; row >= 0; row--) {
+      const c: Candy = { type: randomType(), row, col, root: null };
+      g.grid[at(row, col)] = c;
+      c.root = spawnCandy(w, l, c.type, candyPosition(l, row - 1, col), 0);
+      w.animate(c.root, { position: candyPosition(l, row, col) }, { spring: FALL_SPRING });
+      w.animate(c.root, { scale: 1 }, { duration: FALL_TIME * 0.6, easing: 'back' });
+    }
+  }
+}

package/src/games/candy-crush/CandyCrushScene.ts

@@ -0,0 +1,209 @@
+// Everything Candy Crush draws. Orthographic camera, one world unit per point, looking down -z: x right
+// and y up from the view's centre. Depth (toward the camera): the game background, the board panel and
+// its empty cells, the candies, a dragged candy. Each candy is an invisible root at its cell's centre
+// carrying a matte raised block (shared/EngineBlocks, as Block Blast's, without its gloss or shadow),
+// so moves, swells and shrinks animate the root alone. Every part is a shared mesh: mesh ids are
+// app-wide and limited. The engine doesn't clip, so new candies grow in as they drop rather
+// than fall from behind the board's top edge.
+import { type Color, type Entity, extrude, loft, type Model, Path, quat, type Vec3, type World } from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import { setBackdropTheme, spawnBackdrop } from '../shared/EngineBackdrop';
+import { popAndBurst } from '../shared/EngineBlasts';
+import { spawnRaisedBlock } from '../shared/EngineBlocks';
+import { cacheGameAsset, createGameMesh as createShape } from '../shared/EngineMeshes';
+import { toColor } from '../shared/EngineUtils';
+import {
+  BOMB,
+  CANDY_COLORS,
+  CELL_GAP,
+  cellCenter,
+  CLASSIC_BOARD,
+  CLASSIC_BORDER,
+  CLASSIC_CELL,
+  CLASSIC_RADIUS,
+  GRID_SIZE,
+  type Layout,
+  THEMED_RADIUS
+} from './CandyCrushConstants';
+
+const Z_BACKDROP = -20;
+const Z_BOARD = 0;
+const Z_CELLS = 0.2;
+const Z_RIM = 0.4;
+
+/** A view point (from the top-left) at depth `z`, in world space. */
+export const toWorld = (l: Layout, x: number, y: number, z = 0): Vec3 => [x - l.width / 2, l.height / 2 - y, z];
+
+const candyDepth = (l: Layout) => l.cell * 0.4;
+const candyZ = (l: Layout) => Z_RIM + candyDepth(l) / 2 + 1;
+export const dragZ = (l: Layout) => candyZ(l) + candyDepth(l) * 2;
+
+/** Where the candy at (row, col) rests (row may be negative: above the board). */
+export const candyPosition = (l: Layout, row: number, col: number, z = candyZ(l)): Vec3 => {
+  const [x, y] = cellCenter(l, row, col);
+  return toWorld(l, x, y, z);
+};
+
+// ── Meshes (registered once per size: mesh ids are app-wide and limited) ──
+
+const meshes = new Map<string, Model>();
+const mesh = (key: string, build: () => Model) => {
+  let m = meshes.get(key);
+  if (!m) {
+    m = cacheGameAsset('candy-crush/CandyCrushScene:' + key, build);
+    meshes.set(key, m);
+  }
+  return m;
+};
+/** A flat rounded square from its top-left; with `rim`, only its outline. */
+const panelMesh = (size: number, radius: number, rim = 0) =>
+  mesh(`panel:${size}:${radius}:${rim}`, () => {
+    const path = new Path().addRoundedRect(0, 0, size, size, radius);
+    if (rim > 0) path.addRoundedRect(rim, rim, size - rim * 2, size - rim * 2, radius - rim);
+    return createShape(extrude(path, { depth: 0, fillRule: 'evenodd' }), { center: false });
+  });
+/** All 49 empty cells in one flat mesh, from the board's top-left. */
+const cellsMesh = (l: Layout) =>
+  mesh(`candy-cells:${l.cell}`, () => {
+    const path = new Path();
+    for (let r = 0; r < GRID_SIZE; r++)
+      for (let c = 0; c < GRID_SIZE; c++) path.addRoundedRect(CELL_GAP + c * l.step, CELL_GAP + r * l.step, l.cell, l.cell, l.cell * 0.2);
+    return createShape(extrude(path, { depth: 0 }), { center: false });
+  });
+
+// ── Board ─────────────────────────────────────────────────────────────
+
+export type Scenery = { backdrop: Entity; parts: Entity[] };
+
+/** The board panel, its empty cells and its border, for a theme. */
+function spawnBoard(world: World, l: Layout, theme: GameTheme): Entity[] {
+  const classic = theme.mode === 'classic';
+  const radius = classic ? CLASSIC_RADIUS : THEMED_RADIUS;
+  const origin = (z: number) => toWorld(l, l.boardLeft, l.boardTop, z);
+  const flat = (m: Model, z: number, color: string) => world.spawn({ mesh: m, position: origin(z), color: toColor(color), pickable: false });
+  return [
+    flat(panelMesh(l.boardSize, radius), Z_BOARD, classic ? CLASSIC_BOARD : theme.BOARD.SURFACE),
+    flat(cellsMesh(l), Z_CELLS, classic ? CLASSIC_CELL : theme.BOARD.CELL_EMPTY),
+    flat(panelMesh(l.boardSize, radius, 1.5), Z_RIM, classic ? CLASSIC_BORDER : theme.BOARD.BORDER)
+  ];
+}
+
+export function buildScenery(world: World, l: Layout, theme: GameTheme): Scenery {
+  return { backdrop: spawnBackdrop(world, l.width, l.height, Z_BACKDROP, theme), parts: spawnBoard(world, l, theme) };
+}
+
+export function removeScenery(world: World, s: Scenery) {
+  world.despawn(s.backdrop);
+  for (const e of s.parts) world.despawn(e);
+}
+
+/** A new theme: the background is repainted and the board rebuilt in its colors. */
+export function setSceneryTheme(world: World, l: Layout, s: Scenery, theme: GameTheme) {
+  setBackdropTheme(world, s.backdrop, theme);
+  for (const e of s.parts) world.despawn(e);
+  s.parts = spawnBoard(world, l, theme);
+}
+
+// ── Candies ───────────────────────────────────────────────────────────
+
+const BODY = CANDY_COLORS.map((c) => toColor(c));
+const WHITE: Color = [1, 1, 1, 1];
+const BOMB_BURST: Color = [1, 0.85, 0.4, 1];
+const WHITE_HOT: Color = [2, 2, 2, 1]; // above 1 glows, as the shared pop's flash
+/** Each candy's block (by its root), which flashes as the candy pops. */
+const blocks = new Map<Entity, Entity>();
+export const candyColor = (type: number) => (type === BOMB ? BOMB_BURST : BODY[type % BODY.length]!);
+
+let bomb: Model | null = null;
+/**
+ * The color bomb's block: the same bevelled block as the others, its colors baked in, blending smoothly
+ * from one block color at each corner (top-left, top-right, bottom-right, bottom-left) to the next.
+ */
+function bombMesh(): Model {
+  if (bomb) return bomb;
+  const corner = (i: number) => BODY[i % BODY.length]!;
+  const [tl, tr, br, bl] = [corner(0), corner(1), corner(2), corner(3)];
+  const lerp = (a: Color, b: Color, t: number): Color => [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t, 1];
+  const blend = ([x, y]: Vec3): Color => {
+    const u = Math.max(0, Math.min(1, x + 0.5));
+    const v = Math.max(0, Math.min(1, y + 0.5));
+    return lerp(lerp(bl, br, u), lerp(tl, tr, u), v);
+  };
+  bomb = createShape(
+    loft(
+      [
+        { z: -0.5, bottom: -0.5, top: 0.5, width: 0.5, square: 7 },
+        { z: 0.2, bottom: -0.5, top: 0.5, width: 0.5, square: 7 },
+        { z: 0.4, bottom: -0.465, top: 0.465, width: 0.465, square: 6.5 },
+        { z: 0.5, bottom: -0.39, top: 0.39, width: 0.39, square: 5.5 }
+      ],
+      { around: 64, smoothness: 3, color: blend }
+    ),
+    { center: false }
+  );
+  return bomb;
+}
+
+/**
+ * A candy at view-world `position`, `scale` of full size. A color bomb is a block blending all the
+ * colors, gently pulsing so it stands out.
+ */
+export function spawnCandy(world: World, l: Layout, type: number, position: Vec3, scale: number): Entity {
+  const size = l.cell - 4; // the original body's 2 point inset
+  const depth = candyDepth(l);
+  const root = world.spawn({ mesh: 'none', position, scale, pickable: false });
+  if (type !== BOMB) {
+    blocks.set(
+      root,
+      spawnRaisedBlock(world, { parent: root, position: [0, 0, 0], size: [size, size, depth], color: candyColor(type), gloss: false, shadow: false })
+    );
+    return root;
+  }
+  const block = world.spawn({ mesh: bombMesh(), parent: root, scale: [size, size, depth], color: WHITE, pickable: false });
+  blocks.set(root, block);
+  world.animate(block, { scale: [size * 1.07, size * 1.07, depth] }, { duration: 0.5, repeat: 'forever', yoyo: true, easing: 'easeInOut' });
+  return root;
+}
+
+/** A color bomb just made: it grows in where its match was, with a little overshoot. */
+export function popInBomb(world: World, root: Entity) {
+  world.animate(root, [{ scale: 0.3 }, { scale: 1.25, at: 0.6 }, { scale: 1 }], { duration: 0.35, easing: 'easeOut' });
+}
+
+/** A thin zap from a color bomb to a block it clears, fading. */
+export function zap(world: World, l: Layout, from: Vec3, to: Vec3, type: number, delay: number) {
+  const dx = to[0] - from[0];
+  const dy = to[1] - from[1];
+  const angle = Math.atan2(dy, dx);
+  const length = Math.hypot(dx, dy);
+  const [r, g, b] = type === BOMB ? [1, 1, 1] : candyColor(type);
+  const z = from[2] + candyDepth(l);
+  world.after(delay, () => {
+    const bar = world.spawn({
+      mesh: 'cube',
+      position: [(from[0] + to[0]) / 2, (from[1] + to[1]) / 2, z],
+      rotation: quat.z(angle),
+      scale: [length, l.cell * 0.08, 1],
+      color: [r, g, b, 0.9],
+      pickable: false
+    });
+    world.animate(bar, { scale: [length, 0.01, 1], color: [r, g, b, 0] }, { duration: 0.3 }).then(() => {
+      if (world.has(bar)) world.despawn(bar);
+    });
+  });
+}
+
+/** A matched candy pops as Block Blast's blocks do (shared/EngineBlasts): it swells, flashes white, settles and shrinks away, bursting in its color over a fading glow. Resolves when it's gone. */
+export function crushCandy(world: World, l: Layout, root: Entity, type: number, at: Vec3, duration: number, delay = 0): Promise<void> {
+  const color = type === BOMB ? BOMB_BURST : candyColor(type);
+  const block = blocks.get(root);
+  blocks.delete(root);
+  if (block != null)
+    world.animate(block, [{ color: WHITE_HOT, at: 0.33 }, { color: type === BOMB ? WHITE : color }], { duration: duration * 0.3, delay });
+  return popAndBurst(
+    world,
+    root,
+    { scale: 1, delay, duration },
+    { position: [at[0], at[1], at[2] + candyDepth(l)], size: l.cell, color, glowZ: Z_RIM + 0.2 }
+  );
+}