@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/dots-and-boxes/DotsAndBoxes.tsx

@@ -0,0 +1,83 @@
+// Dots and Boxes' screen, on the Nayan engine: the board, studs, lines and claimed boxes are one 3D scene
+// (an orthographic camera leaning back over the board), under Playtura's scoreboard, controls and
+// modals. The rules and the AI are in DotsAndBoxesGame.ts, what it draws in DotsAndBoxesScene.ts.
+//
+// One world serves the whole visit: Start, Stop and Play Again reset it in place and a theme change
+// repaints the board, so the GPU view is never rebuilt. Lines and boxes animate in the engine's Rust
+// core; JS hit-tests taps and steps the AI's clock and the world once a frame.
+import { HapticType } from '../../services/HapticsService';
+import { GAME_SOUNDS } from '../../services/SoundsService';
+import { GAME_IDS } from '../../services/UtilsService';
+import { engineGame, EngineGameScreen } from '../shared/EngineGameScreen';
+import { type HudColumn, textColumn } from '../shared/EngineHud';
+import { useEngineGame } from '../shared/useEngineGame';
+import { useLiveState } from '../shared/useLiveState';
+import { getLayout, LIGHT, OPPONENT_COLOR, PLAYER_COLOR } from './DotsAndBoxesConstants';
+import { createGame, dispose, reset, setLayout, setTheme, start, tap, tick, type Turn } from './DotsAndBoxesGame';
+
+const SOUNDS = GAME_SOUNDS.DOTS_AND_BOXES;
+
+const playerColumn = (label: string, color: string, score: number, active: boolean): HudColumn => ({
+  label,
+  value: score.toLocaleString(),
+  color: active ? color : undefined,
+  valueColor: color
+});
+
+export const DotsAndBoxes = engineGame(GAME_IDS.DOTS_AND_BOXES, (props) => {
+  const [scores, setScores] = useLiveState<[number, number]>([0, 0]);
+  const [turn, setTurn] = useLiveState<Turn>('player');
+
+  // Win or lose when the last line is drawn
+  const { status, screen, gameOver } = useEngineGame(props, {
+    gameId: GAME_IDS.DOTS_AND_BOXES,
+    create: createGame,
+    start,
+    reset,
+    dispose,
+    tick,
+    setTheme,
+    resize: (g, width, height, offset) => {
+      const l = getLayout(width, height, offset);
+      setLayout(g, l);
+      return l.boardSize;
+    },
+    tap,
+    reportScore: (g) => g.playerScore,
+    sounds: SOUNDS,
+    onStart: (fx) => fx(SOUNDS.START, HapticType.MEDIUM),
+    onOver: (fx, s) =>
+      fx(s === 'draw' ? GAME_SOUNDS.DRAW : s === 'win' ? SOUNDS.WIN : SOUNDS.LOSE, s === 'win' ? HapticType.SUCCESS : HapticType.HEAVY),
+    wire: (g, fx) => {
+      g.onScores = (player, opponent) => setScores([player, opponent]);
+      g.onTurn = setTurn;
+      g.onEvent = (event, who) => {
+        const mine = who === 'player';
+        if (event === 'box') fx(mine ? SOUNDS.BOX_CLAIMED : SOUNDS.OPPONENT_BOX, mine ? HapticType.MEDIUM : HapticType.WARNING);
+        else fx(mine ? SOUNDS.PLAYER_LINE : SOUNDS.OPPONENT_LINE, HapticType.LIGHT);
+      };
+    }
+  });
+
+  const yours = turn === 'player';
+
+  return (
+    <EngineGameScreen
+      {...screen}
+      light={LIGHT}
+      columns={[
+        playerColumn('YOU', PLAYER_COLOR, scores[0], yours),
+        textColumn('TURN', yours ? 'Your Turn' : 'AI Thinking...', yours ? PLAYER_COLOR : OPPONENT_COLOR),
+        playerColumn('AI', OPPONENT_COLOR, scores[1], !yours)
+      ]}
+      subtext="Complete boxes to win!"
+      gameOver={gameOver({
+        title: status === 'win' ? 'YOU WON!' : 'YOU LOST!',
+        message: `Final score: ${scores[0]} - ${scores[1]}`,
+        scoreLabel: status === 'win' ? 'You Won!' : 'You Lost',
+        score: scores[0],
+        buttonText: status === 'win' ? 'Play Again!' : 'Try Again!'
+      })}
+    />
+  );
+});

package/src/games/dots-and-boxes/DotsAndBoxesConstants.ts

@@ -0,0 +1,77 @@
+// Dots and Boxes' rules, colors, timings and layout. The grid, rules, AI and scoring match the original
+// version (games/dots-and-boxes), 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_SIZE = 6; // boxes a side (7 x 7 dots)
+export const BOX_POINTS = 2000;
+
+// ── Colors ────────────────────────────────────────────────────────────
+
+export const PLAYER_COLOR = '#34D399';
+export const OPPONENT_COLOR = '#F87171';
+export const DOT_COLOR = '#D5DCE6'; // brushed steel studs
+export const CLASSIC_BOARD = 'rgba(255, 255, 255, 0.25)';
+export const CLASSIC_RIM = 'rgba(255, 255, 255, 0.3)';
+export const CLASSIC_SLOT = 'rgba(255, 255, 255, 0.3)';
+
+// ── Timings (seconds) ─────────────────────────────────────────────────
+
+export const AI_FIRST_DELAY = 1; // after your move, before the AI's first line
+export const AI_CHAIN_DELAY = 0.8; // between the AI's lines while it keeps closing boxes
+export const LINE_TIME = 0.22; // a line rises and grows out from its middle
+export const BOX_TIME = 0.32; // a claimed box rises out of the board
+
+// ── The scene ─────────────────────────────────────────────────────────
+
+/** The camera leans back this far from straight down, so the studs, rods and tiles read as 3D. */
+export const TILT = 0.3;
+/** Lit from the upper left; surfaces facing up off the board (+z) keep their exact color. */
+export const LIGHT = frontLight([-0.4, 0.35, 1], 0.5);
+
+// ── Layout (view points) ──────────────────────────────────────────────
+
+const SCOREBOARD_HEIGHT = 82;
+const CONTROLS_HEIGHT = 110;
+const PADDING = 22; // from the board's edge to the outer dots, as the original board
+
+export type Layout = TiltView & {
+  boardSize: number;
+  /** From the board's edge to the outer dots' centres. */
+  padding: number;
+  /** Between neighbouring dots. */
+  cell: number;
+  dotRadius: number;
+  lineWidth: number;
+  /** Height of the board's top face. */
+  boardTop: number;
+};
+
+/** The board as wide as the game area, centred between the scoreboard and the controls. */
+export function getLayout(width: number, height: number, offset: number): Layout {
+  const top = getScoreBoardTop(offset) + SCOREBOARD_HEIGHT;
+  const room = Math.max(200, height - top - CONTROLS_HEIGHT);
+  const boardSize = Math.min(gameWidthFor(width), room / Math.cos(TILT));
+  const cell = (boardSize - PADDING * 2) / GRID_SIZE;
+  return {
+    width,
+    height,
+    tilt: TILT,
+    centerY: top + room / 2,
+    boardSize,
+    padding: PADDING,
+    cell,
+    dotRadius: Math.max(6, cell * 0.12),
+    lineWidth: Math.max(6, cell * 0.12),
+    boardTop: 0
+  };
+}
+
+/** A dot's centre on the board (row 0 along the top), in world units. */
+export function dotPoint(l: Layout, row: number, col: number): [number, number] {
+  const half = l.boardSize / 2;
+  return [-half + l.padding + col * l.cell, half - l.padding - row * l.cell];
+}

package/src/games/dots-and-boxes/DotsAndBoxesGame.ts

@@ -0,0 +1,271 @@
+// Dots and Boxes' rules, with no React: build a game with `createGame`, give it a layout, `start` it and
+// `tick` it every frame. You (green) and the AI (red) take turns drawing a line between two neighbouring
+// dots; closing a box's fourth side claims it (2,000 points) and earns another line. When every line is
+// drawn, you win with more boxes than the AI (a tie is a loss, as in the original version).
+//
+// The AI completes a box when it can, otherwise draws a line that doesn't hand you one, otherwise any
+// line. Its moves wait on the game's own clock, advanced by `tick`: a reset drops what's pending, so
+// nothing can land in the next game, and it all pauses with the view.
+import { type Camera, type Entity, World } from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import { aimTilted, unproject } from '../shared/EngineTilt';
+import { AI_CHAIN_DELAY, AI_FIRST_DELAY, BOX_POINTS, dotPoint, GRID_SIZE, type Layout } from './DotsAndBoxesConstants';
+import {
+  type Board,
+  buildBoard,
+  celebrate,
+  type LineKind,
+  type Owner,
+  removeBoard,
+  setBoardTheme,
+  showSlot,
+  spawnRod,
+  spawnTile
+} from './DotsAndBoxesScene';
+
+export type Phase = 'ready' | 'playing' | 'over';
+export type Turn = 'player' | 'opponent';
+export type GameEvent = 'line' | 'box';
+
+const G = GRID_SIZE;
+const H_COUNT = (G + 1) * G; // horizontal lines: G + 1 rows of G
+const LINE_COUNT = H_COUNT * 2; // and as many vertical: G rows of G + 1
+const WORLD_CAPACITY = 800; // studs (49), grooves and rods (84 each), tiles (36), the board, and bursts
+const MAX_STEP = 0.1;
+const HIT_REACH = 0.4; // of a cell: how far from a line a tap still picks it
+
+type Line = { kind: LineKind; row: number; col: number };
+/** Every line, horizontal ones first (row by row), then vertical. */
+const LINES: readonly Line[] = Array.from({ length: LINE_COUNT }, (_, i) =>
+  i < H_COUNT
+    ? { kind: 'h', row: Math.floor(i / G), col: i % G }
+    : { kind: 'v', row: Math.floor((i - H_COUNT) / (G + 1)), col: (i - H_COUNT) % (G + 1) }
+);
+const hIndex = (row: number, col: number) => row * G + col;
+const vIndex = (row: number, col: number) => H_COUNT + row * (G + 1) + col;
+/** The (one or two) boxes each line borders. */
+const BORDERS: readonly number[][] = LINES.map(({ kind, row, col }) => {
+  const boxes: number[] = [];
+  if (kind === 'h') {
+    if (row > 0) boxes.push((row - 1) * G + col);
+    if (row < G) boxes.push(row * G + col);
+  } else {
+    if (col > 0) boxes.push(row * G + col - 1);
+    if (col < G) boxes.push(row * G + col);
+  }
+  return boxes;
+});
+
+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 };
+  return {
+    world,
+    camera,
+    theme,
+    layout: null as Layout | null,
+    board: null as Board | null,
+    phase: 'ready' as Phase,
+    turn: 'player' as Turn,
+    /** Who drew each line (0 = nobody yet). */
+    lines: new Uint8Array(LINE_COUNT),
+    /** Who claimed each box (0 = nobody yet). */
+    boxes: new Uint8Array(G * G),
+    sideCounts: new Uint8Array(G * G),
+    drawn: 0,
+    rods: [] as Entity[],
+    tiles: [] as Entity[],
+    playerScore: 0,
+    opponentScore: 0,
+    won: false,
+    // UI hooks, set by the screen.
+    onPhase: (_p: Phase) => {},
+    onScores: (_player: number, _opponent: number) => {},
+    onTurn: (_t: Turn) => {},
+    onEvent: (_e: GameEvent, _who: Turn) => {}
+  };
+}
+export type Game = ReturnType<typeof createGame>;
+
+const after = (g: Game, seconds: number, run: () => void) => g.world.after(seconds, run);
+const sidesDrawn = (g: Game, box: number) => g.sideCounts[box]!;
+
+// ── Scene ─────────────────────────────────────────────────────────────
+
+/** Lays the scene out for the view (first layout, header height, rotation): rebuilt from the game's state. */
+export function setLayout(g: Game, l: Layout) {
+  clearPieces(g);
+  if (g.board) removeBoard(g.world, g.board);
+  g.layout = l;
+  aimTilted(g.camera, l);
+  g.board = buildBoard(g.world, l, g.theme, LINES);
+  // What's been played so far, without the animations
+  g.lines.forEach((owner, i) => owner && drawLine(g, i, owner as Owner, false));
+  g.boxes.forEach((owner, b) => owner && drawTile(g, b, owner as Owner, false));
+}
+
+export function setTheme(g: Game, theme: GameTheme) {
+  g.theme = theme;
+  if (g.layout && g.board) setBoardTheme(g.world, g.layout, g.board, theme);
+}
+
+function clearPieces(g: Game) {
+  for (const e of [...g.rods, ...g.tiles]) g.world.despawn(e);
+  g.rods = [];
+  g.tiles = [];
+}
+
+function drawLine(g: Game, i: number, owner: Owner, animate: boolean) {
+  const { layout: l, board: b } = g;
+  if (!l || !b) return;
+  const { kind, row, col } = LINES[i]!;
+  showSlot(g.world, b, i, false);
+  g.rods.push(spawnRod(g.world, l, kind, row, col, owner, animate));
+}
+
+function drawTile(g: Game, box: number, owner: Owner, animate: boolean) {
+  if (!g.layout) return;
+  g.tiles.push(spawnTile(g.world, g.layout, Math.floor(box / G), box % G, owner, animate));
+}
+
+// ── Run ───────────────────────────────────────────────────────────────
+
+export function start(g: Game) {
+  if (g.phase !== 'ready') return;
+  g.phase = 'playing';
+  g.onPhase('playing');
+}
+
+/** A fresh board (Stop, Play Again). The world, and the GPU view drawing it, are kept. */
+export function reset(g: Game) {
+  g.world.cancelTimers();
+  clearPieces(g);
+  if (g.board) for (let i = 0; i < LINE_COUNT; i++) showSlot(g.world, g.board, i, true);
+  g.lines.fill(0);
+  g.sideCounts.fill(0);
+  g.boxes.fill(0);
+  g.drawn = 0;
+  g.turn = 'player';
+  g.playerScore = 0;
+  g.opponentScore = 0;
+  g.won = false;
+  g.phase = 'ready';
+  g.onScores(0, 0);
+  g.onTurn('player');
+  g.onPhase('ready');
+}
+
+export function dispose(g: Game) {
+  g.world.dispose();
+}
+
+export function tick(g: Game, dt: number) {
+  if (g.world.isDisposed) return;
+  g.world.update(Math.min(dt, MAX_STEP));
+}
+
+// ── Moves ─────────────────────────────────────────────────────────────
+
+/** The open line nearest a view point, if the point is close enough to it. */
+export function lineAt(g: Game, x: number, y: number): number | null {
+  const l = g.layout;
+  if (!l) return null;
+  const [wx, wy] = unproject(l, x, y, 0);
+  const [ox, oy] = dotPoint(l, 0, 0);
+  // In cells from the top-left dot: c across, r down
+  const c = (wx - ox) / l.cell;
+  const r = (oy - wy) / l.cell;
+  let best: number | null = null;
+  let bestDistance = HIT_REACH;
+  const consider = (index: number, distance: number) => {
+    if (!g.lines[index] && distance < bestDistance) {
+      best = index;
+      bestDistance = distance;
+    }
+  };
+  const hr = Math.round(r);
+  const hc = Math.floor(c);
+  if (hr >= 0 && hr <= G && hc >= 0 && hc < G) consider(hIndex(hr, hc), Math.abs(r - hr));
+  const vr = Math.floor(r);
+  const vc = Math.round(c);
+  if (vr >= 0 && vr < G && vc >= 0 && vc <= G) consider(vIndex(vr, vc), Math.abs(c - vc));
+  return best;
+}
+
+/** A tap: draws the line under it on your turn. */
+export function tap(g: Game, x: number, y: number) {
+  if (g.phase !== 'playing' || g.turn !== 'player') return;
+  const line = lineAt(g, x, y);
+  if (line == null) return;
+  const claimed = play(g, line, 'player');
+  if (g.phase !== 'playing' || claimed > 0) return;
+  setTurn(g, 'opponent');
+  after(g, AI_FIRST_DELAY, () => aiMove(g));
+}
+
+/** Draws a line, claims any box it closes and scores it. Returns the boxes claimed. */
+function play(g: Game, line: number, who: Turn): number {
+  const owner: Owner = who === 'player' ? 1 : 2;
+  g.lines[line] = owner;
+  g.drawn++;
+  drawLine(g, line, owner, true);
+  let claimed = 0;
+  for (const box of BORDERS[line]!) {
+    g.sideCounts[box]!++;
+    if (!g.boxes[box] && sidesDrawn(g, box) === 4) {
+      g.boxes[box] = owner;
+      drawTile(g, box, owner, true);
+      claimed++;
+    }
+  }
+  if (who === 'player') g.playerScore += claimed * BOX_POINTS;
+  else g.opponentScore += claimed * BOX_POINTS;
+  if (claimed) g.onScores(g.playerScore, g.opponentScore);
+  g.onEvent(claimed ? 'box' : 'line', who);
+  if (g.drawn === LINE_COUNT) end(g);
+  return claimed;
+}
+
+function aiMove(g: Game) {
+  if (g.phase !== 'playing' || g.turn !== 'opponent') return;
+  const line = chooseLine(g);
+  if (line == null) {
+    setTurn(g, 'player');
+    return;
+  }
+  const claimed = play(g, line, 'opponent');
+  if (g.phase !== 'playing') return;
+  if (claimed > 0) after(g, AI_CHAIN_DELAY, () => aiMove(g));
+  else setTurn(g, 'player');
+}
+
+/** Close a box if it can; otherwise a line that leaves no box on three sides; otherwise any line. */
+function chooseLine(g: Game): number | null {
+  const open: number[] = [];
+  for (let i = 0; i < LINE_COUNT; i++) if (!g.lines[i]) open.push(i);
+  if (!open.length) return null;
+  const closing = open.find((i) => BORDERS[i]!.some((b) => sidesDrawn(g, b) === 3));
+  if (closing !== undefined) return closing;
+  const safe = open.filter((i) => BORDERS[i]!.every((b) => sidesDrawn(g, b) !== 2));
+  const pool = safe.length ? safe : open;
+  return pool[Math.floor(Math.random() * pool.length)]!;
+}
+
+function setTurn(g: Game, turn: Turn) {
+  g.turn = turn;
+  g.onTurn(turn);
+}
+
+function end(g: Game) {
+  g.world.cancelTimers();
+  let mine = 0;
+  let theirs = 0;
+  for (const owner of g.boxes) {
+    if (owner === 1) mine++;
+    else if (owner === 2) theirs++;
+  }
+  g.won = mine > theirs;
+  g.phase = 'over';
+  if (g.won && g.layout) celebrate(g.world, g.layout);
+  g.onPhase('over');
+}

package/src/games/dots-and-boxes/DotsAndBoxesScene.ts

@@ -0,0 +1,249 @@
+// Everything Dots and Boxes draws: a board panel (themed, as the original board) lying in the world's XY
+// plane under a camera leaning back from straight down (shared/EngineTilt), one world unit per view
+// point. Steel studs mark the dots; each open line is a faint groove between two studs; a played line
+// is a glossy rod in its player's color that rises and grows out from its middle; a claimed box is a
+// glossy tile rising out of the board. Studs, grooves, rods and tiles each share one mesh, so every kind
+// is one instanced draw. Meshes are built once per size: mesh ids are app-wide and limited.
+import { type Color, effects, type Entity, extrude, lathe, merge, type Model, Path, quat, shapeGeometry, tube, type World } from '@nayan-ui/engine';
+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 {
+  BOX_TIME,
+  CLASSIC_BOARD,
+  CLASSIC_RIM,
+  CLASSIC_SLOT,
+  DOT_COLOR,
+  dotPoint,
+  GRID_SIZE,
+  type Layout,
+  LINE_TIME,
+  OPPONENT_COLOR,
+  PLAYER_COLOR
+} from './DotsAndBoxesConstants';
+
+export type Owner = 1 | 2; // you, the AI
+export type LineKind = 'h' | 'v';
+
+const meshes = new Map<string, Model>();
+const cached = (key: string, build: () => Model) => {
+  let m = meshes.get(key);
+  if (!m) {
+    m = cacheGameAsset('dots-and-boxes/DotsAndBoxesScene:' + key, build);
+    meshes.set(key, m);
+  }
+  return m;
+};
+const STAND_UP = quat.x(Math.PI / 2);
+const ACROSS = quat.z(0);
+const DOWN = quat.z(Math.PI / 2);
+const BOARD_DEPTH = 10;
+const BACKDROP_DEPTH = 25;
+const ownerColor = (o: Owner) => toColor(o === 1 ? PLAYER_COLOR : OPPONENT_COLOR);
+const glow = (c: Color, k: number): Color => [c[0] * k, c[1] * k, c[2] * k, 1];
+
+// ── Meshes ────────────────────────────────────────────────────────────
+
+/** The board: a slab with rounded corners, its top face at z = 0. */
+const panelMesh = (size: number, radius: number) =>
+  cached(`dab-panel:${size.toFixed(1)}:${radius}`, () =>
+    createShape(extrude(new Path().addRoundedRect(-size / 2, -size / 2, size, size, radius), { depth: BOARD_DEPTH }), { shine: 0.25 })
+  );
+const rimMesh = (size: number, radius: number) =>
+  cached(`dab-rim:${size.toFixed(1)}:${radius}`, () =>
+    createShape(
+      extrude(
+        new Path()
+          .addRoundedRect(-size / 2, -size / 2, size, size, radius)
+          .addRoundedRect(-size / 2 + 1.5, -size / 2 + 1.5, size - 3, size - 3, radius - 1.5),
+        { depth: 0, fillRule: 'evenodd' }
+      )
+    )
+  );
+/** An open line: a flat rounded groove `length` long, along x. */
+const slotMesh = (length: number, width: number) =>
+  cached(`dab-slot:${length.toFixed(1)}:${width.toFixed(1)}`, () =>
+    createShape(extrude(new Path().addRoundedRect(-length / 2, -width / 2, length, width, width / 2), { depth: 0 }))
+  );
+/** A steel stud, one unit across, standing on the origin. */
+const studMesh = () =>
+  cached('dab-stud', () =>
+    createShape(
+      lathe(
+        [
+          [0.001, 0],
+          [0.5, 0],
+          [0.5, 0.22],
+          [0.46, 0.38],
+          [0.34, 0.52],
+          [0.16, 0.6],
+          [0.001, 0.62]
+        ],
+        { segments: 24 }
+      ),
+      { center: false, shine: 0.85 }
+    )
+  );
+/** A played line: a rod one unit long and across, along x. */
+const rodMesh = () =>
+  cached('dab-rod', () =>
+    createShape(
+      tube(
+        [
+          [-0.5, 0, 0],
+          [0.5, 0, 0]
+        ],
+        { radius: 0.5, sides: 16, smoothness: 1 }
+      ),
+      { shine: 0.7 }
+    )
+  );
+/** A claimed box: a rounded tile one unit across and tall, a raised face on a darker base. */
+const tileMesh = () =>
+  cached('dab-tile', () =>
+    createShape(
+      merge([
+        { geometry: shapeGeometry('roundedBox', { color: [0.78, 0.78, 0.78] }), position: [0, 0, 0.5] },
+        { geometry: shapeGeometry('roundedBox'), position: [0, 0, 0.62], scale: [0.72, 0.72, 0.9] }
+      ]),
+      { center: false, shine: 0.55 }
+    )
+  );
+
+// ── Lines and boxes ───────────────────────────────────────────────────
+
+/** A line's middle on the board, and its length. */
+function linePlace(l: Layout, kind: LineKind, row: number, col: number) {
+  const [ax, ay] = dotPoint(l, row, col);
+  const [bx, by] = kind === 'h' ? dotPoint(l, row, col + 1) : dotPoint(l, row + 1, col);
+  return { x: (ax + bx) / 2, y: (ay + by) / 2 };
+}
+
+export function boxCentre(l: Layout, row: number, col: number): [number, number] {
+  const [x, y] = dotPoint(l, row, col);
+  return [x + l.cell / 2, y - l.cell / 2];
+}
+
+const tileSize = (l: Layout): [number, number, number] => [l.cell * 0.76, l.cell * 0.76, l.cell * 0.14];
+
+// ── Spawning ──────────────────────────────────────────────────────────
+
+export type Board = {
+  backdrop: Entity;
+  panel: Entity;
+  rim: Entity | null;
+  studs: Entity[];
+  /** One per line, in the game's line order. */
+  slots: Entity[];
+};
+
+const slotColor = (theme: GameTheme) => toColor(theme.mode === 'classic' ? CLASSIC_SLOT : theme.BOARD.CELL_HIGHLIGHT);
+
+/** The backdrop, the board and its rim, the studs and every line's groove. `lines` lists them in the game's order. */
+export function buildBoard(world: World, l: Layout, theme: GameTheme, lines: readonly { kind: LineKind; row: number; col: number }[]): Board {
+  const classic = theme.mode === 'classic';
+  const radius = classic ? 16 : 8;
+  const backdrop = spawnBackdrop(world, l.width, l.height, -BACKDROP_DEPTH, theme);
+  placeTiltedBackdrop(world, backdrop, l, BACKDROP_DEPTH);
+  const panel = world.spawn({
+    mesh: panelMesh(l.boardSize, radius),
+    position: [0, 0, -BOARD_DEPTH / 2],
+    color: toColor(classic ? CLASSIC_BOARD : theme.BOARD.SURFACE),
+    pickable: false
+  });
+  const rimColor = toColor(classic ? CLASSIC_RIM : theme.BOARD.BORDER);
+  const rim = rimColor[3]! > 0 ? world.spawn({ mesh: rimMesh(l.boardSize, radius), position: [0, 0, 0.2], color: rimColor, pickable: false }) : null;
+  const studs: Entity[] = [];
+  const steel = toColor(DOT_COLOR);
+  for (let row = 0; row <= GRID_SIZE; row++)
+    for (let col = 0; col <= GRID_SIZE; col++) {
+      const [x, y] = dotPoint(l, row, col);
+      studs.push(world.spawn({ mesh: studMesh(), position: [x, y, 0], rotation: STAND_UP, scale: l.dotRadius * 2, color: steel, pickable: false }));
+    }
+  const slot = slotMesh(l.cell - l.dotRadius * 2.4, l.lineWidth * 0.75);
+  const color = slotColor(theme);
+  const slots = lines.map(({ kind, row, col }) => {
+    const { x, y } = linePlace(l, kind, row, col);
+    return world.spawn({ mesh: slot, position: [x, y, 0.3], rotation: kind === 'h' ? ACROSS : DOWN, color, pickable: false });
+  });
+  return { backdrop, panel, rim, studs, slots };
+}
+
+export function removeBoard(world: World, b: Board) {
+  for (const e of [b.backdrop, b.panel, ...(b.rim != null ? [b.rim] : []), ...b.studs, ...b.slots]) world.despawn(e);
+}
+
+/** A new theme: backdrop, board, rim and grooves repainted; the studs, rods and tiles keep their colors. */
+export function setBoardTheme(world: World, l: Layout, b: Board, theme: GameTheme) {
+  const classic = theme.mode === 'classic';
+  const radius = classic ? 16 : 8;
+  setBackdropTheme(world, b.backdrop, theme);
+  world.set(b.panel, { mesh: panelMesh(l.boardSize, radius), color: toColor(classic ? CLASSIC_BOARD : theme.BOARD.SURFACE) });
+  if (b.rim != null) world.despawn(b.rim);
+  const rimColor = toColor(classic ? CLASSIC_RIM : theme.BOARD.BORDER);
+  b.rim = rimColor[3]! > 0 ? world.spawn({ mesh: rimMesh(l.boardSize, radius), position: [0, 0, 0.2], color: rimColor, pickable: false }) : null;
+  const color = slotColor(theme);
+  for (const s of b.slots) world.set(s, { color });
+}
+
+/** A played line's rod; with `animate`, it drops in and grows out from its middle with a bright flash. */
+export function spawnRod(world: World, l: Layout, kind: LineKind, row: number, col: number, owner: Owner, animate: boolean): Entity {
+  const { x, y } = linePlace(l, kind, row, col);
+  const w = l.lineWidth;
+  const color = ownerColor(owner);
+  const rest: [number, number, number] = [x, y, w / 2];
+  const rod = world.spawn({
+    mesh: rodMesh(),
+    position: animate ? [x, y, w * 2.5] : rest,
+    rotation: kind === 'h' ? ACROSS : DOWN,
+    scale: [animate ? w : l.cell, w, w],
+    color: animate ? glow(color, 1.6) : color,
+    pickable: false
+  });
+  if (animate) {
+    world.animate(rod, { scale: [l.cell, w, w] }, { duration: LINE_TIME, easing: 'back' });
+    world.animate(rod, { position: rest }, { duration: LINE_TIME, easing: 'bounce' });
+    world.animate(rod, { color }, { duration: LINE_TIME * 2 });
+  }
+  return rod;
+}
+
+/** A claimed box's tile; with `animate`, it springs up out of the board and throws a little confetti. */
+export function spawnTile(world: World, l: Layout, row: number, col: number, owner: Owner, animate: boolean): Entity {
+  const [x, y] = boxCentre(l, row, col);
+  const color = ownerColor(owner);
+  const tile = world.spawn({ mesh: tileMesh(), position: [x, y, 0], scale: animate ? [0.01, 0.01, 0.01] : tileSize(l), color, pickable: false });
+  if (animate) {
+    world.animate(tile, { scale: tileSize(l) }, { duration: BOX_TIME, easing: 'back' });
+    effects.sparkle(world, {
+      position: [x, y, l.cell * 0.2],
+      count: 12,
+      size: l.cell * 0.08,
+      speed: l.cell * 3,
+      lifetime: 0.5,
+      gravity: -l.cell * 6,
+      colors: [color, glow(color, 1.3), [1, 1, 1, 1]]
+    });
+  }
+  return tile;
+}
+
+/** Confetti over the board when you win. */
+export function celebrate(world: World, l: Layout) {
+  effects.confetti(world, {
+    position: [0, 0, l.cell],
+    count: 60,
+    size: l.cell * 0.12,
+    speed: l.boardSize * 1.4,
+    lifetime: 1.4,
+    gravity: -l.boardSize * 2.4,
+    colors: ['#34D399', '#FFD740', '#448AFF', '#FF5252'].map((c) => toColor(c))
+  });
+}
+
+/** Hides a line's groove under its rod (or shows it again on a reset). */
+export function showSlot(world: World, b: Board, index: number, on: boolean) {
+  world.set(b.slots[index]!, { scale: on ? 1 : 0 });
+}