@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/tic-tac-toe/TicTacToeGame.ts

@@ -0,0 +1,200 @@
+// Tic Tac Toe's play, with no React: build a game with `createGame`, give it a layout, `start` it and
+// `tick` it every frame. You are O and go first: tap an empty cell. The robot (X) answers half a second
+// later. Three in a row wins; a full board is a draw; the three-minute clock running out loses.
+//
+// The rules and the robot are the original store's (TicTacToeRules.ts); the robot's think and the clock run
+// on the game's own clock, so Stop or leaving can't let a late move into the next game.
+import { type Camera, type DragEvent, World } from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import { aimTilted, unproject } from '../shared/EngineTilt';
+import { cellAt, DRAW_SCORE, type Layout, LOSE_SCORE, ROBOT_DELAY, TIME_BONUS, TIME_LIMIT, WIN_SCORE } from './TicTacToeConstants';
+import { type Board, emptyBoard, type Player, robotMove, winningLine } from './TicTacToeRules';
+import { buildScene, clearPieces, hideGhost, markWin, place, removeScene, type Scene, setSceneTheme, showGhost, shrug } from './TicTacToeScene';
+
+export type Phase = 'ready' | 'playing' | 'over';
+/** How a game ended. */
+export type Result = 'win' | 'lose' | 'draw' | 'timeout';
+/** place / robot: a piece down; win / lose / draw: how a move ended it (a timeout is silent, as in the original game). */
+export type GameEvent = 'place' | 'robot' | 'win' | 'lose' | 'draw';
+
+const WORLD_CAPACITY = 240; // the board (border, cells, bars ~40), nine pieces and shadows, 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,
+    board: emptyBoard() as Board,
+    turn: 'O' as Player,
+    result: null as Result | null,
+    finalScore: 0,
+    line: null as readonly [number, number, number] | null,
+    /** The countdown lives in the engine (Rust), advanced by world.update. */
+    get timeLeft() {
+      return world.scoreboard.shownSeconds;
+    },
+    /** A finger down on a cell (shown as a ghost O until it lifts). */
+    press: -1,
+    // UI hooks, set by the screen.
+    onPhase: (_p: Phase) => {},
+    onTurn: (_p: Player) => {},
+    onTime: (_t: number) => {},
+    onEvent: (_e: GameEvent) => {}
+  };
+  world.scoreboard.reset(0, TIME_LIMIT);
+  world.scoreboard.handlers = {
+    onSecond: (t) => g.onTime(t),
+    onTimeUp: () => g.phase === 'playing' && end(g, 'timeout')
+  };
+  return g;
+}
+export type Game = ReturnType<typeof createGame>;
+
+/** A finished game's score: the result's points, plus a bonus for the time left (a win's full, a draw's half). */
+export const scoreFor = (r: Result | null, timeLeft: number) =>
+  r === 'win' ? WIN_SCORE + Math.max(0, timeLeft) * TIME_BONUS : r === 'draw' ? DRAW_SCORE + Math.max(0, timeLeft) * (TIME_BONUS / 2) : LOSE_SCORE;
+/** The game-over card's score. */
+export const shownScore = (g: { result: Result | null; finalScore: number }) => (g.result ? g.finalScore : LOSE_SCORE);
+
+// ── Scene ─────────────────────────────────────────────────────────────
+
+/** Lays the board 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.board);
+  if (g.line) markWin(g.world, l, g.scene, g.line);
+}
+
+export function setTheme(g: Game, theme: GameTheme) {
+  g.theme = theme;
+  if (g.layout && g.scene) setSceneTheme(g.world, g.layout, g.scene, theme);
+}
+
+// ── Run ───────────────────────────────────────────────────────────────
+
+function clear(g: Game) {
+  g.world.cancelTimers();
+  g.board = emptyBoard();
+  g.turn = 'O';
+  g.result = null;
+  g.line = null;
+  g.world.scoreboard.reset(0, TIME_LIMIT);
+  g.press = -1;
+  if (g.scene) clearPieces(g.world, g.scene);
+  g.onTurn('O');
+  g.onTime(TIME_LIMIT);
+}
+
+/** A fresh board, your move first. */
+export function start(g: Game) {
+  if (g.phase !== 'ready') return;
+  clear(g);
+  g.world.scoreboard.startCountdown(TIME_LIMIT);
+  g.phase = 'playing';
+  g.onPhase('playing');
+}
+
+/** An empty board, not started (Stop, Play Again). The world, and the GPU view drawing it, are kept. */
+export function reset(g: Game) {
+  clear(g);
+  g.phase = 'ready';
+  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(dt);
+}
+
+function end(g: Game, result: Result) {
+  g.result = result;
+  g.world.cancelTimers();
+  g.world.scoreboard.stop();
+  g.finalScore = scoreFor(result, g.timeLeft);
+  g.press = -1;
+  if (g.scene) hideGhost(g.world, g.scene);
+  g.phase = 'over';
+  g.onPhase('over');
+}
+
+// ── Moves ─────────────────────────────────────────────────────────────
+
+/** A piece on a cell, and what it does: three in a row, a full board, or the other side's turn. */
+function put(g: Game, i: number, who: Player) {
+  g.board[i] = who;
+  const { layout: l, scene: s } = g;
+  if (l && s) place(g.world, l, s, i, who);
+  g.onEvent(who === 'O' ? 'place' : 'robot');
+  const line = winningLine(g.board);
+  if (line) {
+    g.line = line;
+    if (l && s) markWin(g.world, l, s, line);
+    g.onEvent(who === 'O' ? 'win' : 'lose');
+    end(g, who === 'O' ? 'win' : 'lose');
+    return;
+  }
+  if (g.board.every((c) => c !== null)) {
+    if (l && s) shrug(g.world, l, s);
+    g.onEvent('draw');
+    end(g, 'draw');
+    return;
+  }
+  g.turn = who === 'O' ? 'X' : 'O';
+  g.onTurn(g.turn);
+}
+
+/** Your move on a cell, if it's your turn and the cell is empty; the robot answers after its think. */
+export function play(g: Game, i: number) {
+  if (g.phase !== 'playing' || g.turn !== 'O' || g.board[i] !== null || i < 0 || i > 8) return;
+  put(g, i, 'O');
+  if (g.phase !== 'playing') return;
+  g.world.after(ROBOT_DELAY, () => {
+    if (g.phase !== 'playing' || g.turn !== 'X') return;
+    const move = robotMove(g.board);
+    if (move >= 0) put(g, move, 'X');
+  });
+}
+
+// ── The finger ────────────────────────────────────────────────────────
+
+/** The cell under a view point (on the board's surface), or -1. */
+export function cellUnder(g: Game, x: number, y: number): number {
+  const l = g.layout;
+  if (!l) return -1;
+  const [wx, wy] = unproject(l, x, y, 1);
+  return cellAt(l, wx, wy);
+}
+
+/** A finger down on an empty cell shows a ghost O there; lifting on the same cell plays it. */
+export function drag(g: Game, { phase, x, y }: DragEvent) {
+  const { layout: l, scene: s } = g;
+  const i = cellUnder(g, x, y);
+  const open = g.phase === 'playing' && g.turn === 'O' && i >= 0 && g.board[i] === null;
+  if (phase === 'start') {
+    g.press = open ? i : -1;
+  } else if (i !== g.press) {
+    g.press = -1; // slid off: no move
+  }
+  if (phase === 'end') {
+    const at = g.press;
+    g.press = -1;
+    if (s) hideGhost(g.world, s);
+    if (at >= 0) play(g, at);
+    return;
+  }
+  if (l && s) {
+    if (g.press >= 0) showGhost(g.world, l, s, g.press);
+    else hideGhost(g.world, s);
+  }
+}

package/src/games/tic-tac-toe/TicTacToeRules.ts

@@ -0,0 +1,103 @@
+// Tic Tac Toe's rules, with no React or engine: lines, the winner, and the robot's move. Ported from
+// the original store (games/tic-tac-toe): you are O and go first. The robot (X) takes an available win,
+// but sometimes overlooks your threats and usually plays casually instead of looking ahead.
+
+export type Player = 'X' | 'O';
+export type Cell = Player | null;
+export type Board = Cell[];
+
+export const LINES = [
+  [0, 1, 2],
+  [3, 4, 5],
+  [6, 7, 8],
+  [0, 3, 6],
+  [1, 4, 7],
+  [2, 5, 8],
+  [0, 4, 8],
+  [2, 4, 6]
+] as const;
+
+export const emptyBoard = (): Board => Array<Cell>(9).fill(null);
+
+/** The line three in a row, if there is one. */
+export function winningLine(b: Board): readonly [number, number, number] | null {
+  for (const line of LINES) {
+    const [a, c, d] = line;
+    if (b[a] && b[a] === b[c] && b[a] === b[d]) return line;
+  }
+  return null;
+}
+export const winnerOf = (b: Board): Player | null => {
+  const line = winningLine(b);
+  return line ? b[line[0]]! : null;
+};
+
+const empties = (b: Board) => b.flatMap((c, i) => (c === null ? [i] : []));
+
+/** How often the robot misses your threat of three in a row. */
+const MISS_BLOCK = 0.4;
+/** How often the robot, with no win or block on the board, plays any free cell instead of its best. */
+const SLIP = 0.7;
+
+/** The board's worth to the robot with `turn` to move, played out perfectly: sooner wins score higher. */
+function minimax(b: Board, turn: Player, depth: number, cache: Map<number, number>): number {
+  let code = 0;
+  for (const cell of b) code = code * 3 + (cell === 'X' ? 1 : cell === 'O' ? 2 : 0);
+  const key = code * 32 + depth * 2 + (turn === 'X' ? 1 : 0);
+  const cached = cache.get(key);
+  if (cached !== undefined) return cached;
+  const w = winnerOf(b);
+  if (w === 'X') return 10 - depth;
+  if (w === 'O') return depth - 10;
+  let best = turn === 'X' ? -Infinity : Infinity;
+  let found = false;
+  for (let i = 0; i < b.length; i++) {
+    if (b[i] !== null) continue;
+    found = true;
+    b[i] = turn;
+    const v = minimax(b, turn === 'X' ? 'O' : 'X', depth + 1, cache);
+    b[i] = null;
+    best = turn === 'X' ? Math.max(best, v) : Math.min(best, v);
+  }
+  const value = found ? best : 0;
+  cache.set(key, value);
+  return value;
+}
+
+const pick = (cells: number[]) => cells[Math.floor(Math.random() * cells.length)]!;
+
+/** A forgiving opponent that takes wins, sometimes misses blocks, and occasionally looks ahead. */
+export function robotMove(b: Board): number {
+  const free = empties(b);
+  if (!free.length) return -1;
+  const completes = (who: Player) =>
+    free.filter((i) => {
+      const t = [...b];
+      t[i] = who;
+      return winnerOf(t) === who;
+    });
+  const win = completes('X')[0];
+  if (win !== undefined) return win;
+  const blocks = completes('O');
+  if (blocks.length) {
+    const alternatives = free.filter((i) => !blocks.includes(i));
+    // Commit to an overlooked threat: falling through to minimax would just find the block again.
+    if (alternatives.length && Math.random() < MISS_BLOCK) return pick(alternatives);
+    return pick(blocks);
+  }
+  if (Math.random() < SLIP) return pick(free);
+  const t = [...b];
+  const cache = new Map<number, number>(); // discarded after this decision; no growing app-wide table
+  let best = -Infinity;
+  let moves: number[] = [];
+  for (const i of free) {
+    t[i] = 'X';
+    const v = minimax(t, 'O', 1, cache);
+    t[i] = null;
+    if (v > best) {
+      best = v;
+      moves = [i];
+    } else if (v === best) moves.push(i);
+  }
+  return pick(moves);
+}

package/src/games/tic-tac-toe/TicTacToeScene.ts

@@ -0,0 +1,245 @@
+// Everything Tic Tac Toe draws: the board (a wooden board with a sunken well and raised wooden grid
+// bars in the classic theme, the theme's board and cells otherwise), glossy 3D pieces (an X of two
+// rounded bars, an O ring) that drop onto their cells with a little settle, a ghost O under the finger
+// before it lifts, and a gold bar laid across a winning line. Seen from a little in front of straight
+// down (shared/EngineTilt: an orthographic camera leaning back, one world unit per point).
+import { type Color, effects, type Entity, extrude, merge, type Model, Path, quat, tube, type Vec3, type World } from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import { setBackdropTheme, spawnBackdrop } from '../shared/EngineBackdrop';
+import { popBurst } from '../shared/EngineBlasts';
+import { cacheGameAsset, createGameMesh as createShape } from '../shared/EngineMeshes';
+import { placeTiltedBackdrop } from '../shared/EngineTilt';
+import { toColor } from '../shared/EngineUtils';
+import { cellCentre, COLORS, type Layout } from './TicTacToeConstants';
+import type { Player } from './TicTacToeRules';
+
+const meshes = new Map<string, Model>();
+const cached = (key: string, build: () => Model) => {
+  let m = meshes.get(key);
+  if (!m) {
+    m = cacheGameAsset('tic-tac-toe/TicTacToeScene:' + key, build);
+    meshes.set(key, m);
+  }
+  return m;
+};
+const BOARD_DEPTH = 12;
+const BACKDROP_DEPTH = 30;
+const STROKE = 0.075; // a piece's tube radius, of a cell
+const SPAN = 0.23; // an X's half-reach, an O's radius, of a cell
+const BAR = 0.1; // the grid bars' height above the board, of a cell
+const WIN_GOLD = toColor(COLORS.WIN);
+
+// ── Meshes (one cell across) ──────────────────────────────────────────
+
+/** An X: two crossed bars with round ends, lying on the board. */
+const xMesh = () =>
+  cached('ttt-x-v2', () => {
+    const bar = (a: Vec3, b: Vec3) => ({ geometry: tube([a, b], { radius: STROKE, sides: 16, smoothness: 2, caps: true }) });
+    return createShape(merge([bar([-SPAN, -SPAN, STROKE], [SPAN, SPAN, STROKE]), bar([SPAN, -SPAN, STROKE * 1.02], [-SPAN, SPAN, STROKE * 1.02])]), {
+      center: false,
+      shine: 0.75
+    });
+  });
+
+/** An O: a ring lying on the board. */
+const oMesh = () =>
+  cached('ttt-o-v2', () => {
+    const pts: Vec3[] = Array.from({ length: 41 }, (_, i) => {
+      const a = (i / 40) * Math.PI * 2;
+      return [Math.cos(a) * SPAN, Math.sin(a) * SPAN, STROKE];
+    });
+    return createShape(tube(pts, { radius: STROKE, sides: 16, smoothness: 2, caps: false }), { center: false, shine: 0.75 });
+  });
+
+const panelMesh = (w: number, radius: number, depth: number, shine = 0) =>
+  cached(`ttt-panel:${w}:${radius}:${depth}:${shine}`, () =>
+    createShape(extrude(new Path().addRoundedRect(-w / 2, -w / 2, w, w, radius), { depth }), { shine })
+  );
+
+// ── Spawning ──────────────────────────────────────────────────────────
+
+export type Scene = {
+  backdrop: Entity;
+  /** The board's frame, well and surface, its cells and grid bars (rebuilt on a theme change). */
+  board: Entity[];
+  pieces: (Entity | null)[];
+  ghost: Entity;
+  line: Entity | null;
+};
+
+const pieceColor = (p: Player) => toColor(p === 'X' ? COLORS.X : COLORS.O);
+
+function spawnBoard(world: World, l: Layout, theme: GameTheme): Entity[] {
+  const out: Entity[] = [];
+  const add = (o: Parameters<World['spawn']>[0]) => out.push(world.spawn({ pickable: false, ...o }));
+  const outer = l.size + l.pad * 2;
+  const classic = theme.mode === 'classic';
+  const barW = Math.max(6, l.cell * 0.075);
+  const barH = l.cell * BAR;
+  if (classic) {
+    // The classic wooden board, as the original board
+    add({ mesh: panelMesh(outer, 14, BOARD_DEPTH), position: [0, 0, -BOARD_DEPTH / 2], color: toColor(COLORS.FRAME) });
+    add({ mesh: panelMesh(l.size + 4, 10, 1), position: [0, 0, 0.4], color: toColor(COLORS.WELL) });
+    add({ mesh: panelMesh(l.size, 6, 1), position: [0, 0, 0.8], color: toColor(COLORS.SURFACE) });
+    for (let i = 0; i < 9; i++)
+      if ((Math.floor(i / 3) + i) % 2 === 1) {
+        const [x, y] = cellCentre(l, i);
+        add({ mesh: 'cube', position: [x, y, 1.3], scale: [l.cell, l.cell, 0.02], color: toColor(COLORS.SURFACE_ALT) });
+      }
+  } else {
+    // The theme's board and its raised cells
+    add({ mesh: panelMesh(outer, 8, BOARD_DEPTH), position: [0, 0, -BOARD_DEPTH / 2], color: toColor(theme.BOARD.SURFACE) });
+    for (let i = 0; i < 9; i++) {
+      const [x, y] = cellCentre(l, i);
+      add({ mesh: panelMesh(Math.round(l.cell - barW * 2), 10, 3), position: [x, y, 1.5], scale: 1, color: toColor(theme.BOARD.CELL_EMPTY) });
+    }
+  }
+  // The grid: two rounded bars each way standing proud of the board, their ends set in from its edge
+  const grid: Color = toColor(classic ? COLORS.GRID : theme.BOARD.GRID_LINE);
+  const shadow: Color = [0, 0, 0, 0.18];
+  const length = l.size - l.cell * 0.16;
+  const across = quat.z(Math.PI / 2);
+  for (const k of [-0.5, 0.5]) {
+    // A soft shadow under each bar, then the bar (a capsule, along its y)
+    add({ mesh: 'capsule', position: [k * l.cell + barW * 0.25, -barW * 0.25, 1.05], scale: [barW * 1.5, length, 0.6], color: shadow });
+    add({
+      mesh: 'capsule',
+      position: [barW * 0.25, k * l.cell - barW * 0.25, 1.05],
+      rotation: across,
+      scale: [barW * 1.5, length, 0.6],
+      color: shadow
+    });
+    add({ mesh: 'capsule', position: [k * l.cell, 0, 1 + barH / 2], scale: [barW, length, barH], color: grid });
+    add({ mesh: 'capsule', position: [0, k * l.cell, 1 + barH / 2], rotation: across, scale: [barW, length, barH], color: grid });
+  }
+  return out;
+}
+
+export function buildScene(world: World, l: Layout, theme: GameTheme, board: (Player | null)[]): Scene {
+  const backdrop = spawnBackdrop(world, l.width, l.height, -BACKDROP_DEPTH, theme);
+  placeTiltedBackdrop(world, backdrop, l, BACKDROP_DEPTH);
+  const ghost = world.spawn({ mesh: oMesh(), scale: 0, color: toColor(COLORS.O, 0.35), pickable: false });
+  const s: Scene = { backdrop, board: spawnBoard(world, l, theme), pieces: Array(9).fill(null), ghost, line: null };
+  board.forEach((p, i) => {
+    if (p) place(world, l, s, i, p, false);
+  });
+  return s;
+}
+
+export function removeScene(world: World, s: Scene) {
+  for (const e of [s.backdrop, ...s.board, ...s.pieces, s.ghost, s.line]) if (e != null) world.despawn(e);
+}
+
+export function setSceneTheme(world: World, l: Layout, s: Scene, theme: GameTheme) {
+  setBackdropTheme(world, s.backdrop, theme);
+  for (const e of s.board) world.despawn(e);
+  s.board = spawnBoard(world, l, theme);
+}
+
+const BOARD_TOP = 1;
+
+// ── Pieces ────────────────────────────────────────────────────────────
+
+/** A piece on a cell: it grows out of the cell with a little turn and settles (or is just there). */
+export function place(world: World, l: Layout, s: Scene, i: number, p: Player, animate = true) {
+  const [x, y] = cellCentre(l, i);
+  const e = world.spawn({
+    mesh: p === 'X' ? xMesh() : oMesh(),
+    position: [x, y, BOARD_TOP],
+    rotation: quat.z(animate ? (p === 'X' ? -0.6 : 0.6) : 0),
+    scale: animate ? 0 : l.cell,
+    color: pieceColor(p),
+    pickable: false
+  });
+  // Its soft shadow on the board, riding with it
+  world.spawn({
+    mesh: 'sphere',
+    parent: e,
+    position: [0.04, -0.04, 0.01],
+    scale: [SPAN * 2.5, SPAN * 2.5, 0.01],
+    color: [0, 0, 0, 0.2],
+    pickable: false
+  });
+  if (animate) {
+    // Grows out of its cell, overshoots a touch and settles, turning straight as it comes
+    world.animate(e, [{ scale: l.cell * 1.18, at: 0.6 }, { scale: l.cell * 0.94, at: 0.82 }, { scale: l.cell }], {
+      duration: 0.36,
+      easing: 'easeOut'
+    });
+    world.animate(e, { rotation: [0, 0, 0, 1] }, { duration: 0.3, easing: 'easeOut' });
+    world.after(0.2, () => popBurst(world, { position: [x, y, BOARD_TOP + l.cell * 0.15], size: l.cell * 0.7, color: pieceColor(p), count: 7 }));
+  }
+  s.pieces[i] = e;
+  hideGhost(world, s);
+}
+
+/** A faint O over an empty cell while a finger rests on it. */
+export function showGhost(world: World, l: Layout, s: Scene, i: number) {
+  const [x, y] = cellCentre(l, i);
+  world.set(s.ghost, { position: [x, y, BOARD_TOP + 0.5], scale: l.cell * 0.92 });
+  world.animate(s.ghost, { scale: l.cell * 0.98 }, { duration: 0.5, repeat: 'forever', yoyo: true, easing: 'easeInOut' });
+}
+export function hideGhost(world: World, s: Scene) {
+  world.stopAnimation(s.ghost);
+  world.set(s.ghost, { scale: 0 });
+}
+
+/** Three in a row: they turn gold and hop, and a gold bar is laid across them, glowing softly. */
+export function markWin(world: World, l: Layout, s: Scene, line: readonly [number, number, number]) {
+  line.forEach((i, k) => {
+    const e = s.pieces[i];
+    if (e == null) return;
+    const [x, y] = cellCentre(l, i);
+    world.animate(e, { color: WIN_GOLD }, { duration: 0.25, delay: k * 0.08 });
+    world.animate(e, [{ position: [x, y, BOARD_TOP + l.cell * 0.35], at: 0.4 }, { position: [x, y, BOARD_TOP] }], {
+      duration: 0.45,
+      delay: k * 0.08,
+      easing: 'easeOut'
+    });
+  });
+  const [ax, ay] = cellCentre(l, line[0]);
+  const [bx, by] = cellCentre(l, line[2]);
+  const len = Math.hypot(bx - ax, by - ay) + l.cell * 0.5;
+  const angle = Math.atan2(by - ay, bx - ax);
+  const r = l.cell * 0.07;
+  const z = BOARD_TOP + STROKE * l.cell * 2 + r;
+  // A capsule lies along its y; turned to run along the line
+  const rotation = quat.z(angle - Math.PI / 2);
+  s.line = world.spawn({
+    mesh: 'capsule',
+    position: [(ax + bx) / 2, (ay + by) / 2, z],
+    rotation,
+    scale: [r * 2, 0.01, r * 2],
+    color: [1.6, 1.25, 0.3, 1],
+    pickable: false
+  });
+  world.animate(s.line, { scale: [r * 2, len, r * 2] }, { duration: 0.32, delay: 0.15, easing: 'easeOut' });
+  world.animate(s.line, { color: [1.2, 0.95, 0.25, 1] }, { duration: 0.6, delay: 0.5, easing: 'easeInOut', repeat: 'forever', yoyo: true });
+  effects.sparkle(world, {
+    position: [(ax + bx) / 2, (ay + by) / 2, z + 4],
+    count: 30,
+    size: l.cell * 0.06,
+    speed: l.cell * 2.5,
+    lifetime: 0.7,
+    gravity: -l.cell * 2,
+    colors: ['#FFD54F', '#FFC107', '#FFFFFF'].map((c) => toColor(c))
+  });
+}
+
+/** A draw: every piece gives a little shrug. */
+export function shrug(world: World, l: Layout, s: Scene) {
+  for (const e of s.pieces) if (e != null) world.animate(e, { shake: l.cell * 0.04 }, { duration: 0.4 });
+}
+
+/** A fresh board: the pieces lift off and fade, and the win bar goes. */
+export function clearPieces(world: World, s: Scene) {
+  for (const e of s.pieces)
+    if (e != null) {
+      world.stopAnimation(e);
+      world.set(e, { lifetime: 0.25 });
+    }
+  s.pieces = Array(9).fill(null);
+  if (s.line != null) world.despawn(s.line);
+  s.line = null;
+  hideGhost(world, s);
+}

package/src/games/tile-home/TileHome.tsx

@@ -0,0 +1,92 @@
+// Tile Home's screen, on the Nayan engine: the board, tray, tiles and their 3D fruit are one scene
+// (an orthographic camera over raised 3D tiles), under Playtura's scoreboard, controls and modals. The rules
+// are in TileHomeGame.ts, what it draws in TileHomeScene.ts.
+//
+// One world serves the whole visit: Start, Stop and Play Again deal a new board in place and a theme
+// change repaints the scenery, so the GPU view is never rebuilt. The intro, flights, tray shuffles and
+// bursts animate in the engine's Rust core; JS only hit-tests taps and steps the world once a frame.
+import { HapticType } from '../../services/HapticsService';
+import { GAME_SOUNDS } from '../../services/SoundsService';
+import { formatTime, GAME_IDS } from '../../services/UtilsService';
+import { getFruit, isFruitBuilt } from '../shared/EngineFruits';
+import { engineGame, EngineGameScreen } from '../shared/EngineGameScreen';
+import { useEngineGame } from '../shared/useEngineGame';
+import { useLiveState } from '../shared/useLiveState';
+import { getLayout, LIGHT, POINTS_PER_SET, TILE_TYPES, TIME_LIMIT, TOTAL_SETS } from './TileHomeConstants';
+import { addFruit, createGame, dispose, reset, setLayout, setTheme, start, tap, tick } from './TileHomeGame';
+
+const SFX = GAME_SOUNDS.TILE_HOME;
+const formatScore = (score: number) => score.toLocaleString();
+const FRUIT_DETAIL = 0.25;
+
+export const TileHome = engineGame(GAME_IDS.TILE_HOME, (props) => {
+  const [score, setScore] = useLiveState(0);
+  const [timeLeft, setTimeLeft] = useLiveState(TIME_LIMIT);
+
+  // Win on a cleared board, lose on a full tray or time up
+  const { status, screen, gameOver } = useEngineGame(props, {
+    gameId: GAME_IDS.TILE_HOME,
+    create: createGame,
+    start,
+    reset,
+    dispose,
+    tick,
+    setTheme,
+    resize: (g, width, height, offset) => {
+      const l = getLayout(width, height, offset);
+      setLayout(g, l);
+      return l.boardWidth;
+    },
+    tap,
+    onStart: (fx) => fx(SFX.START, HapticType.MEDIUM),
+    wire: (g, fx) => {
+      g.onScore = setScore;
+      g.onTime = setTimeLeft;
+      g.onPick = () => fx(SFX.PICK, HapticType.LIGHT);
+      g.onMatch = () => fx(SFX.MATCH, HapticType.MEDIUM);
+      g.onWin = () => fx(SFX.WIN, HapticType.SUCCESS);
+      g.onLose = () => fx(SFX.GAME_OVER, HapticType.HEAVY);
+      // The board shows at once; each kind of fruit pops onto its tiles as its model is built. Models are
+      // built once per app (already-built ones go straight on), starting on the next frame and
+      // continuing one per frame so construction does not block the whole screen.
+      // 72 fruits about 60 points wide: light meshes (full detail would be over a million triangles).
+      const kinds = [...new Set(TILE_TYPES.map((t) => t.fruit))];
+      for (const kind of kinds) if (isFruitBuilt(kind, FRUIT_DETAIL)) addFruit(g, kind, getFruit(kind, FRUIT_DETAIL));
+      const queue = kinds.filter((kind) => !isFruitBuilt(kind, FRUIT_DETAIL));
+      let frame = 0;
+      const buildNext = () => {
+        const kind = queue.shift();
+        if (!kind || g.world.isDisposed) return;
+        addFruit(g, kind, getFruit(kind, FRUIT_DETAIL));
+        if (queue.length) frame = requestAnimationFrame(buildNext);
+      };
+      if (queue.length) frame = requestAnimationFrame(buildNext);
+      return () => {
+        if (frame) cancelAnimationFrame(frame);
+      };
+    }
+  });
+
+  const setsLeft = Math.max(0, TOTAL_SETS - Math.floor(score / POINTS_PER_SET));
+
+  return (
+    <EngineGameScreen
+      {...screen}
+      light={LIGHT}
+      columns={[
+        { label: 'SCORE', value: formatScore(score) },
+        { label: 'SETS', value: String(setsLeft) },
+        { label: 'TIME', value: formatTime(Math.max(0, Math.ceil(timeLeft))) }
+      ]}
+      subtext="Match tiles!"
+      gameOver={gameOver({
+        title: status === 'win' ? 'YOU WON!' : 'TIME UP!',
+        message: status === 'win' ? 'All tiles sorted home!' : 'You ran out of time!',
+        scoreLabel: status === 'win' ? 'You Won!' : 'Game Over',
+        score,
+        formatter: formatScore,
+        buttonText: status === 'win' ? 'Play Again!' : 'Try Again!'
+      })}
+    />
+  );
+});