@nayan-ui/games 1.20.0 → 1.21.0

package/src/games/block-blast/BlockBlastGame.ts

@@ -1,471 +0,0 @@
-// Block Blast's rules, with no React: build a run with `createGame`, give it a layout, `start` it and
-// `tick` it every frame. Drag a tray piece onto the 9x9 board; full rows and columns clear. Survive the
-// timer to win; run out of room for every tray piece and it's over. The screen listens through `on…`.
-import { type Camera, type Color, type Entity, World } from '@nayan-ui/engine';
-import type { GameTheme } from '../../services/ThemeService';
-import { setBackdropTheme } from '../shared/EngineBackdrop';
-import { popAndBurst } from '../shared/EngineBlasts';
-import {
-  BLOCK_COLORS,
-  BLOCK_SHAPES,
-  CELL_GAP,
-  CLEAR_RIPPLE,
-  CLEAR_TIME,
-  DEAL_TIME,
-  DRAG_LIFT,
-  FLASH_AMOUNT,
-  FLASH_TIME,
-  flat,
-  GAME_DURATION,
-  GRID_SIZE,
-  type Layout,
-  LIFT_TIME,
-  NEXT_PIECES_COUNT,
-  PICKUP_SPRING,
-  POINTS_PER_BLOCK,
-  POINTS_PER_LINE,
-  RETURN_TIME,
-  tint,
-  toColor,
-  TRAY_SCALE
-} from './BlockBlastConstants';
-import {
-  blockBurst,
-  blockScale,
-  type Board,
-  type BoardColors,
-  buildBoard,
-  colorBoard,
-  dragZ,
-  setOverlay,
-  spawnBlock,
-  spawnPiece,
-  toWorld,
-  trayZ
-} from './BlockBlastScene';
-
-export type Phase = 'ready' | 'playing' | 'over';
-
-type Shape = readonly (readonly number[])[];
-type Piece = { shape: Shape; css: string; color: Color; root: Entity | null };
-type Drag = {
-  slot: number;
-  /** Finger offset from the piece's centre at pickup, so the piece doesn't jump to the finger. */
-  offsetX: number;
-  offsetY: number;
-  x: number;
-  y: number;
-  liftedAt: number;
-  /** Drop target: top-left cell, or null when not over the board. */
-  row: number | null;
-  col: number | null;
-  valid: boolean;
-  returning: boolean;
-  drawnX?: number;
-  drawnY?: number;
-};
-
-const CELLS = GRID_SIZE * GRID_SIZE;
-const WORLD_CAPACITY = 1600; // board + overlays (~330), blocks (81), tray, and blast particles
-
-const randomPiece = (): Piece => {
-  const shape = BLOCK_SHAPES[Math.floor(Math.random() * BLOCK_SHAPES.length)]!;
-  const css = BLOCK_COLORS[Math.floor(Math.random() * BLOCK_COLORS.length)]!;
-  return { shape, css, color: toColor(css), root: null };
-};
-
-const easeOutCubic = (t: number) => 1 - Math.pow(1 - t, 3);
-
-export function createGame(theme: GameTheme) {
-  const world = new World(WORLD_CAPACITY);
-  const camera: Camera = { eye: [0, 0, 200], target: [0, 0, 0], fov: 1, ortho: 1 };
-  const g = {
-    world,
-    camera,
-    colors: theme.BOARD as BoardColors,
-    /** For the screen background (theme color and pattern, see EngineBackdrop). */
-    theme,
-    layout: null as Layout | null,
-    board: null as Board | null,
-    phase: 'ready' as Phase,
-    time: 0,
-    /** 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,
-    /** Each cell's color (css, for the line-clear sound check), or null. */
-    grid: new Array<string | null>(CELLS).fill(null),
-    gridColors: new Array<Color | null>(CELLS).fill(null),
-    blocks: new Array<Entity | null>(CELLS).fill(null),
-    pieces: Array.from({ length: NEXT_PIECES_COUNT }, randomPiece),
-    drag: null as Drag | null,
-    /** What each preview overlay shows, so a hover only touches the cells that changed. */
-    ghostShown: new Array<Color | null>(CELLS).fill(null),
-    previewColors: new Map<string, Color>(),
-    highlightShown: new Array<boolean>(CELLS).fill(false),
-    // UI hooks, set by the screen.
-    onPhase: (_p: Phase) => {},
-    onScore: (_s: number) => {},
-    onTime: (_t: number) => {},
-    onPick: () => {},
-    onInvalid: () => {},
-    onPlace: () => {},
-    onClear: (_lines: number) => {},
-    onGameOver: () => {}
-  };
-  world.scoreboard.reset(0, GAME_DURATION);
-  world.scoreboard.handlers = {
-    onSecond: (t) => g.onTime(t),
-    onTimeUp: () => g.phase === 'playing' && end(g, true)
-  };
-  return g;
-}
-export type Game = ReturnType<typeof createGame>;
-
-// ── Scene ─────────────────────────────────────────────────────────────
-
-/** Lays the scene out for the view (first layout, rotation, header height): rebuilt from the run's state. */
-export function setLayout(g: Game, l: Layout) {
-  const w = g.world;
-  cancelDrag(g);
-  if (g.board) {
-    const b = g.board;
-    for (const e of [b.backdrop, b.rim, b.panel, ...b.empties, ...b.highlights, ...b.ghosts]) w.despawn(e);
-  }
-  for (let i = 0; i < CELLS; i++) {
-    if (g.blocks[i] != null) w.despawn(g.blocks[i]!);
-    const color = g.gridColors[i];
-    g.blocks[i] = color ? spawnBlock(w, l, Math.floor(i / GRID_SIZE), i % GRID_SIZE, color) : null;
-  }
-  g.layout = l;
-  g.camera.ortho = l.height / 2;
-  g.board = buildBoard(w, l, g.colors, g.theme);
-  g.ghostShown.fill(null);
-  g.highlightShown.fill(false);
-  g.pieces.forEach((p, slot) => placeInTray(g, p, slot, false));
-}
-
-/** Repaints the board and background for a new theme without touching the run. */
-export function setTheme(g: Game, theme: GameTheme) {
-  g.colors = theme.BOARD;
-  g.theme = theme;
-  if (g.board) {
-    colorBoard(g.world, g.board, g.colors);
-    setBackdropTheme(g.world, g.board.backdrop, theme);
-  }
-}
-
-function placeInTray(g: Game, p: Piece, slot: number, pop: boolean) {
-  const l = g.layout;
-  if (!l) return;
-  if (p.root != null) g.world.despawn(p.root);
-  p.root = spawnPiece(g.world, l, p.shape, p.color, l.slots[slot]!, pop ? 0 : TRAY_SCALE);
-  if (pop) g.world.animate(p.root, { scale: TRAY_SCALE }, { duration: DEAL_TIME, easing: 'back' });
-}
-
-// ── Run ───────────────────────────────────────────────────────────────
-
-export function start(g: Game) {
-  if (g.phase !== 'ready') return;
-  g.phase = 'playing';
-  g.world.scoreboard.startCountdown(GAME_DURATION);
-  g.onPhase('playing');
-}
-
-/** A fresh board and tray (Stop, Play Again). The world, and the GPU view drawing it, are kept. */
-export function reset(g: Game) {
-  cancelDrag(g);
-  for (let i = 0; i < CELLS; i++) {
-    if (g.blocks[i] != null) g.world.despawn(g.blocks[i]!);
-    g.blocks[i] = null;
-    g.grid[i] = null;
-    g.gridColors[i] = null;
-  }
-  for (const p of g.pieces) if (p.root != null) g.world.despawn(p.root);
-  g.pieces = Array.from({ length: NEXT_PIECES_COUNT }, randomPiece);
-  g.pieces.forEach((p, slot) => placeInTray(g, p, slot, true));
-  g.world.scoreboard.reset(0, GAME_DURATION);
-  g.won = false;
-  g.phase = 'ready';
-  g.onScore(0);
-  g.onTime(GAME_DURATION);
-  g.onPhase('ready');
-}
-
-export function dispose(g: Game) {
-  g.world.dispose();
-}
-
-function end(g: Game, won: boolean) {
-  g.world.scoreboard.stop();
-  cancelDrag(g);
-  g.won = won;
-  g.phase = 'over';
-  if (!won) g.onGameOver();
-  g.onPhase('over');
-}
-
-export function tick(g: Game, dt: number) {
-  if (g.world.isDisposed) return;
-  g.time += dt;
-  // The held piece follows the finger, lifting above it just after pickup.
-  const d = g.drag;
-  const l = g.layout;
-  const root = d ? g.pieces[d.slot]?.root : null;
-  if (d && l && root != null && !d.returning) {
-    const lift = DRAG_LIFT * easeOutCubic(Math.min(1, (g.time - d.liftedAt) / LIFT_TIME));
-    const x = d.x - d.offsetX,
-      y = d.y - d.offsetY - lift;
-    if (x !== d.drawnX || y !== d.drawnY) {
-      d.drawnX = x;
-      d.drawnY = y;
-      g.world.set(root, { position: toWorld(l, x, y, dragZ) });
-    }
-  }
-  g.world.update(dt);
-}
-
-// ── Rules ─────────────────────────────────────────────────────────────
-
-function fits(g: Game, shape: Shape, row: number, col: number) {
-  for (let r = 0; r < shape.length; r++) {
-    const line = shape[r]!;
-    for (let c = 0; c < line.length; c++) {
-      if (line[c] !== 1) continue;
-      const gr = row + r;
-      const gc = col + c;
-      if (gr < 0 || gr >= GRID_SIZE || gc < 0 || gc >= GRID_SIZE || g.grid[gr * GRID_SIZE + gc] !== null) return false;
-    }
-  }
-  return true;
-}
-
-function anyMoveLeft(g: Game) {
-  for (const p of g.pieces) {
-    for (let row = 0; row < GRID_SIZE; row++) for (let col = 0; col < GRID_SIZE; col++) if (fits(g, p.shape, row, col)) return true;
-  }
-  return false;
-}
-
-/** Rows and columns that would be full with `extra` cells filled too. */
-function fullLines(g: Game, extra?: Set<number>) {
-  const filled = (i: number) => g.grid[i] !== null || !!extra?.has(i);
-  const rows: number[] = [];
-  const cols: number[] = [];
-  for (let i = 0; i < GRID_SIZE; i++) {
-    let row = true;
-    let col = true;
-    for (let j = 0; j < GRID_SIZE && (row || col); j++) {
-      if (row && !filled(i * GRID_SIZE + j)) row = false;
-      if (col && !filled(j * GRID_SIZE + i)) col = false;
-    }
-    if (row) rows.push(i);
-    if (col) cols.push(i);
-  }
-  return { rows, cols };
-}
-
-function cellsOf(shape: Shape, row: number, col: number) {
-  const cells: number[] = [];
-  shape.forEach((line, r) => line.forEach((v, c) => v === 1 && cells.push((row + r) * GRID_SIZE + col + c)));
-  return cells;
-}
-
-function place(g: Game, slot: number, row: number, col: number) {
-  const l = g.layout!;
-  const w = g.world;
-  const piece = g.pieces[slot]!;
-  const cells = cellsOf(piece.shape, row, col);
-  // The piece lands as board blocks, with a short white glint.
-  const placed: Entity[] = [];
-  for (const i of cells) {
-    g.grid[i] = piece.css;
-    g.gridColors[i] = piece.color;
-    const block = spawnBlock(w, l, Math.floor(i / GRID_SIZE), i % GRID_SIZE, tint(piece.color, FLASH_AMOUNT));
-    g.blocks[i] = block;
-    placed.push(block);
-  }
-  w.animate(placed, { color: piece.color }, { duration: FLASH_TIME });
-  g.world.scoreboard.add(cells.length * POINTS_PER_BLOCK);
-  // Refill the slot in place, so the other pieces stay where the player left them.
-  if (piece.root != null) w.despawn(piece.root);
-  g.pieces[slot] = randomPiece();
-  placeInTray(g, g.pieces[slot]!, slot, true);
-  g.onPlace();
-
-  const { rows, cols } = fullLines(g);
-  const lines = rows.length + cols.length;
-  if (lines > 0) {
-    const clearing = new Set<number>();
-    for (const r of rows) for (let c = 0; c < GRID_SIZE; c++) clearing.add(r * GRID_SIZE + c);
-    for (const c of cols) for (let r = 0; r < GRID_SIZE; r++) clearing.add(r * GRID_SIZE + c);
-    // Each block pops and bursts in turn, rippling out from where the piece landed (as Tile Home's matches)
-    const landedRow = cells.reduce((sum, i) => sum + Math.floor(i / GRID_SIZE), 0) / cells.length;
-    const landedCol = cells.reduce((sum, i) => sum + (i % GRID_SIZE), 0) / cells.length;
-    for (const i of clearing) {
-      const row = Math.floor(i / GRID_SIZE);
-      const col = i % GRID_SIZE;
-      const delay = Math.hypot(row - landedRow, col - landedCol) * CLEAR_RIPPLE;
-      const color = g.gridColors[i];
-      const block = g.blocks[i];
-      if (block != null && color) {
-        popAndBurst(w, block, { scale: blockScale(l), color, delay, duration: CLEAR_TIME }, blockBurst(l, row, col, color)).then(() =>
-          w.despawn(block)
-        );
-      }
-      g.blocks[i] = null;
-      g.grid[i] = null;
-      g.gridColors[i] = null;
-    }
-    g.world.scoreboard.add(lines * POINTS_PER_LINE);
-    g.onClear(lines);
-  }
-  g.onScore(g.score);
-  if (!anyMoveLeft(g)) end(g, false);
-}
-
-// ── Dragging ──────────────────────────────────────────────────────────
-
-/** Finger down: picks up the tray piece under it (anywhere in its slot). */
-export function dragStart(g: Game, x: number, y: number) {
-  const l = g.layout;
-  if (!l || g.phase !== 'playing' || g.drag) return;
-  if (y < l.trayTop - 20 || y > l.trayTop + l.trayHeight + 20) return;
-  const slot = l.slots.findIndex(([sx]) => Math.abs(x - sx) <= l.slotWidth / 2);
-  const root = slot >= 0 ? g.pieces[slot]?.root : null;
-  if (root == null) return;
-  const [sx, sy] = l.slots[slot]!;
-  g.onPick();
-  g.drag = { slot, offsetX: x - sx, offsetY: y - sy, x, y, liftedAt: g.time, row: null, col: null, valid: false, returning: false };
-  g.world.stopAnimation(root);
-  g.world.animate(root, { scale: 1 }, { spring: PICKUP_SPRING });
-}
-
-export function dragMove(g: Game, x: number, y: number) {
-  const d = g.drag;
-  const l = g.layout;
-  if (!d || !l || d.returning) return;
-  d.x = x;
-  d.y = y;
-  // The drop target is where the lifted piece is drawn: its top-left cell, snapped to the nearest.
-  const shape = g.pieces[d.slot]!.shape;
-  const rows = shape.length;
-  const cols = shape[0]?.length ?? 0;
-  const cx = x - d.offsetX;
-  const cy = y - d.offsetY - DRAG_LIFT;
-  const half = l.step / 2;
-  const over = cx > l.boardLeft - half && cx < l.boardLeft + l.boardSize + half && cy > l.boardTop - half && cy < l.boardTop + l.boardSize + half;
-  // First cell's centre (cx - (cols - 1) / 2 * step) against cell 0's centre (boardLeft + gap + cell / 2)
-  const col = over ? Math.round((cx - (cols * l.step) / 2 - CELL_GAP / 2 - l.boardLeft) / l.step) : null;
-  const row = over ? Math.round((cy - (rows * l.step) / 2 - CELL_GAP / 2 - l.boardTop) / l.step) : null;
-  if (row === d.row && col === d.col) return;
-  d.row = row;
-  d.col = col;
-  d.valid = row !== null && col !== null && fits(g, shape, row, col);
-  showPreview(g);
-}
-
-/** Finger up: drops the piece if it fits, otherwise it flies back to its slot. */
-export function dragEnd(g: Game) {
-  const d = g.drag;
-  const l = g.layout;
-  if (!d || !l || d.returning) return;
-  if (d.valid && d.row !== null && d.col !== null && g.phase === 'playing') {
-    g.drag = null;
-    clearPreview(g);
-    place(g, d.slot, d.row, d.col);
-    return;
-  }
-  if (g.phase === 'playing' && d.row !== null && d.col !== null) g.onInvalid();
-  d.returning = true;
-  clearPreview(g);
-  const root = g.pieces[d.slot]?.root;
-  if (root == null) {
-    g.drag = null;
-    return;
-  }
-  const [sx, sy] = l.slots[d.slot]!;
-  g.world.animate(root, { position: toWorld(l, sx, sy, trayZ(l)), scale: TRAY_SCALE }, { duration: RETURN_TIME }).then(() => {
-    if (g.drag === d) g.drag = null;
-  });
-}
-
-/** Puts a held piece straight back (game over, Stop, relayout). */
-function cancelDrag(g: Game) {
-  const d = g.drag;
-  if (!d) return;
-  g.drag = null;
-  clearPreview(g);
-  const l = g.layout;
-  const root = g.pieces[d.slot]?.root;
-  if (!l || root == null) return;
-  const [sx, sy] = l.slots[d.slot]!;
-  g.world.stopAnimation(root);
-  g.world.set(root, { position: toWorld(l, sx, sy, trayZ(l)), scale: TRAY_SCALE });
-}
-
-// ── Drop preview ──────────────────────────────────────────────────────
-
-// Scratch for the next preview; applyPreview only touches overlays whose content changed (a hover
-// changes a handful of cells, not all 81).
-const ghosts = new Array<Color | null>(CELLS);
-const highlights = new Array<boolean>(CELLS);
-
-function showPreview(g: Game) {
-  const d = g.drag;
-  ghosts.fill(null);
-  highlights.fill(false);
-  if (d && d.row !== null && d.col !== null) {
-    const piece = g.pieces[d.slot]!;
-    const css = d.valid ? piece.css : g.colors.CELL_INVALID;
-    const key = `${css}:${d.valid}`;
-    let ghost = g.previewColors.get(key);
-    if (!ghost) {
-      ghost = flat(toColor(css, d.valid ? 0.5 : 0.3));
-      g.previewColors.set(key, ghost);
-    }
-    const covered = new Set<number>();
-    piece.shape.forEach((line, r) =>
-      line.forEach((v, c) => {
-        const gr = d.row! + r;
-        const gc = d.col! + c;
-        if (v !== 1 || gr < 0 || gr >= GRID_SIZE || gc < 0 || gc >= GRID_SIZE) return;
-        ghosts[gr * GRID_SIZE + gc] = ghost;
-        covered.add(gr * GRID_SIZE + gc);
-      })
-    );
-    // Light up the lines this drop would complete, so the player sees the clear coming.
-    if (d.valid) {
-      const { rows, cols } = fullLines(g, covered);
-      for (const r of rows) for (let c = 0; c < GRID_SIZE; c++) highlights[r * GRID_SIZE + c] = true;
-      for (const c of cols) for (let r = 0; r < GRID_SIZE; r++) highlights[r * GRID_SIZE + c] = true;
-    }
-  }
-  applyPreview(g);
-}
-
-function clearPreview(g: Game) {
-  ghosts.fill(null);
-  highlights.fill(false);
-  applyPreview(g);
-}
-
-function applyPreview(g: Game) {
-  const b = g.board;
-  if (!b) return;
-  const highlight = flat(toColor(g.colors.CELL_HIGHLIGHT));
-  for (let i = 0; i < CELLS; i++) {
-    if (ghosts[i] !== g.ghostShown[i]) {
-      g.ghostShown[i] = ghosts[i]!;
-      setOverlay(g.world, b.ghosts[i]!, ghosts[i]!);
-    }
-    if (highlights[i] !== g.highlightShown[i]) {
-      g.highlightShown[i] = highlights[i]!;
-      setOverlay(g.world, b.highlights[i]!, highlights[i] ? highlight : null);
-    }
-  }
-}

package/src/games/block-blast/BlockBlastScene.ts

@@ -1,156 +0,0 @@
-// Everything Block Blast draws. The camera is orthographic with one world unit per point, looking
-// down -z: x runs right and y runs up from the view's centre, so layout maths stays in screen points.
-// Depth comes from the glossy bevelled pieces, lit directly overhead without drop shadows.
-import { type Color, type Entity, extrude, type Model, Path, type Vec3, type World } from '@nayan-ui/engine';
-import type { GameTheme } from '../../services/ThemeService';
-import { spawnBackdrop } from '../shared/EngineBackdrop';
-import type { PopBurstOptions } from '../shared/EngineBlasts';
-import { raisedBlockScale, spawnRaisedBlock } from '../shared/EngineBlocks';
-import { createGameMesh as createShape } from '../shared/EngineMeshes';
-import { CELL_GAP, flat, GRID_SIZE, type Layout, toColor } from './BlockBlastConstants';
-
-// Depth order toward the camera
-const Z_BACKDROP = -20;
-const Z_BOARD = 0;
-const Z_EMPTY = 1.2;
-const Z_TRAY = 2;
-const Z_DRAG = 80;
-
-/** 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];
-
-/** Centre of a board cell, in view points. */
-export const cellCenter = (l: Layout, row: number, col: number): [number, number] => [
-  l.boardLeft + CELL_GAP + col * l.step + l.cell / 2,
-  l.boardTop + CELL_GAP + row * l.step + l.cell / 2
-];
-
-const blockZ = (l: Layout) => Z_EMPTY + l.depth / 2 + 0.4;
-const highlightZ = (l: Layout) => Z_EMPTY + l.depth + 2;
-const ghostZ = (l: Layout) => Z_EMPTY + l.depth + 3;
-export const trayZ = (l: Layout) => Z_TRAY + l.depth / 2;
-export const dragZ = Z_DRAG;
-
-export type BoardColors = GameTheme['BOARD'];
-
-/** The board: its panel and rim, the empty slots, and per-cell overlays for the drop preview. */
-export type Board = {
-  /** The game background (theme color and pattern), behind everything. */
-  backdrop: Entity;
-  rim: Entity;
-  panel: Entity;
-  empties: Entity[];
-  /** Lines the hovered drop would complete. */
-  highlights: Entity[];
-  /** The hovered piece's cells (its color, or the invalid color). */
-  ghosts: Entity[];
-};
-
-const HIDDEN = 0;
-const SHOWN = 1;
-// Corner radii, as the original board drew them
-const BOARD_RADIUS = 8;
-const CELL_RADIUS = 4;
-const RIM_WIDTH = 1;
-
-// Flat rounded rectangles in points (one-sided, facing the camera), made once per size: mesh ids are
-// app-wide and limited, and a device only ever needs one board size.
-const panels = new Map<string, Model>();
-function roundedPanel(size: number, radius: number, rim = 0): Model {
-  const key = `${size}:${radius}:${rim}`;
-  let mesh = panels.get(key);
-  if (!mesh) {
-    const path = new Path().addRoundedRect(0, 0, size, size, radius);
-    // A rim is the outline only: the inner rounded rect cuts it out.
-    if (rim > 0) path.addRoundedRect(rim, rim, size - rim * 2, size - rim * 2, radius - rim);
-    mesh = createShape(extrude(path, { depth: 0, fillRule: 'evenodd' }));
-    panels.set(key, mesh);
-  }
-  return mesh;
-}
-
-export function buildBoard(world: World, l: Layout, colors: BoardColors, theme: GameTheme): Board {
-  const centre = toWorld(l, l.boardLeft + l.boardSize / 2, l.boardTop + l.boardSize / 2);
-  const cellMesh = roundedPanel(l.cell, CELL_RADIUS);
-  const flatCell = (position: Vec3, scale: number) => world.spawn({ mesh: cellMesh, position, scale, color: [1, 1, 1, 0], pickable: false });
-  // The panel covers every cell plus the gap around them; the rim is drawn over its edge, like a stroke.
-  const panel = world.spawn({ mesh: roundedPanel(l.boardSize, BOARD_RADIUS), position: [centre[0], centre[1], Z_BOARD], pickable: false });
-  const rim = world.spawn({
-    mesh: roundedPanel(l.boardSize, BOARD_RADIUS, RIM_WIDTH),
-    position: [centre[0], centre[1], Z_BOARD + 0.5],
-    pickable: false
-  });
-  const empties: Entity[] = [];
-  const highlights: Entity[] = [];
-  const ghosts: Entity[] = [];
-  for (let row = 0; row < GRID_SIZE; row++) {
-    for (let col = 0; col < GRID_SIZE; col++) {
-      const [x, y] = cellCenter(l, row, col);
-      empties.push(flatCell(toWorld(l, x, y, Z_EMPTY), SHOWN));
-      highlights.push(flatCell(toWorld(l, x, y, highlightZ(l)), HIDDEN));
-      ghosts.push(flatCell(toWorld(l, x, y, ghostZ(l)), HIDDEN));
-    }
-  }
-  const backdrop = spawnBackdrop(world, l.width, l.height, Z_BACKDROP, theme);
-  const board = { backdrop, rim, panel, empties, highlights, ghosts };
-  colorBoard(world, board, colors);
-  return board;
-}
-
-/** Repaints the board for a theme (the run carries on). */
-export function colorBoard(world: World, b: Board, colors: BoardColors) {
-  world.set(b.rim, { color: flat(toColor(colors.BORDER)) });
-  world.set(b.panel, { color: flat(toColor(colors.SURFACE)) });
-  const empty = flat(toColor(colors.CELL_EMPTY));
-  for (const e of b.empties) world.set(e, { color: empty });
-}
-
-/** Shows or hides a preview overlay (`null` hides it). */
-export function setOverlay(world: World, overlay: Entity, color: Color | null) {
-  world.set(overlay, color ? { scale: SHOWN, color } : { scale: HIDDEN });
-}
-
-// ── Blocks (shared/EngineBlocks: glossy and bevelled, without drop shadows) ─────────
-
-const blockSize = (l: Layout): Vec3 => [l.cell, l.cell, l.depth];
-
-/** A block at `position`, under `parent` if given. */
-const spawnBlockAt = (world: World, l: Layout, position: Vec3, color: Color, parent?: Entity) =>
-  spawnRaisedBlock(world, { position, size: blockSize(l), color, parent, shadow: false });
-
-/** A placed block on the board. */
-export function spawnBlock(world: World, l: Layout, row: number, col: number, color: Color): Entity {
-  const [x, y] = cellCenter(l, row, col);
-  return spawnBlockAt(world, l, toWorld(l, x, y, blockZ(l)), color);
-}
-
-/** A piece: an invisible root at its centre with one block per cell, at `scale` of board size. */
-export function spawnPiece(
-  world: World,
-  l: Layout,
-  shape: readonly (readonly number[])[],
-  color: Color,
-  at: [number, number],
-  scale: number
-): Entity {
-  const rows = shape.length;
-  const cols = shape[0]?.length ?? 0;
-  const root = world.spawn({ mesh: 'none', position: toWorld(l, at[0], at[1], trayZ(l)), scale, pickable: false });
-  for (let r = 0; r < rows; r++) {
-    for (let c = 0; c < cols; c++) {
-      if (shape[r]?.[c] !== 1) continue;
-      spawnBlockAt(world, l, [(c - (cols - 1) / 2) * l.step, -(r - (rows - 1) / 2) * l.step, 0], color, root);
-    }
-  }
-  return root;
-}
-
-/** A board block's scale (for popping it away). */
-export const blockScale = (l: Layout): Vec3 => raisedBlockScale(blockSize(l));
-
-/** Where a cleared block's burst flies from (just in front of it) and glows (behind it, over its cell). */
-export function blockBurst(l: Layout, row: number, col: number, color: Color): PopBurstOptions {
-  const [x, y] = cellCenter(l, row, col);
-  const at = toWorld(l, x, y, blockZ(l));
-  return { position: [at[0], at[1], at[2] + l.depth * 2], size: l.cell, color, glowZ: Z_EMPTY + 0.3 };
-}