@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/ludo-king/LudoKingRules.ts

@@ -0,0 +1,143 @@
+// Ludo King's rules, with no React or engine. A token's `progress` tells the whole story: -1 in the
+// yard, 0..50 round the shared track (from the player's entry), 51..56 up its home column, 56 home.
+// A six brings a token out; you must land on 56 exactly to finish; landing on an opponent off a safe
+// cell sends it back. Scoring (3,000 a finished token plus its progress) matches the original version.
+import {
+  CENTER,
+  ENTRY,
+  HOME_STRETCH,
+  HOME_YARDS,
+  MAIN_PATH,
+  type PlayerColor,
+  SAFE_POSITIONS,
+  TOKENS_PER_PLAYER,
+  TRACK_LENGTH
+} from './LudoKingConstants';
+
+export type Token = {
+  id: string;
+  player: PlayerColor;
+  /** -1 yard, 0..56 along the route (56 = home). */
+  progress: number;
+};
+
+export type Player = { color: PlayerColor; tokens: Token[]; isAI: boolean; finishedTokens: number };
+export type GamePhase = 'rolling' | 'moving' | 'ai_turn' | 'over';
+
+export const isInYard = (t: Token) => t.progress < 0;
+export const isFinished = (t: Token) => t.progress >= TRACK_LENGTH;
+
+export const rollDice = () => Math.floor(Math.random() * 6) + 1;
+
+export function createPlayers(you: PlayerColor, ai: PlayerColor[]): Player[] {
+  const make = (color: PlayerColor, isAI: boolean): Player => ({
+    color,
+    isAI,
+    finishedTokens: 0,
+    tokens: Array.from({ length: TOKENS_PER_PLAYER }, (_, i) => ({ id: `${color}-${i}`, player: color, progress: -1 }))
+  });
+  return [make(you, false), ...ai.map((c) => make(c, true))];
+}
+
+/** The absolute index on the shared track for a token `steps` from its entry (0..50). */
+export const mainIndexAt = (player: PlayerColor, steps: number) => (ENTRY[player] + steps) % 52;
+
+export function canMove(token: Token, dice: number): boolean {
+  if (isFinished(token)) return false;
+  if (isInYard(token)) return dice === 6;
+  return token.progress + dice <= TRACK_LENGTH;
+}
+
+export const movableTokens = (player: Player, dice: number) => player.tokens.filter((t) => canMove(t, dice));
+
+/** The grid cell a token stands on now. */
+export function tokenCell(token: Token): { row: number; col: number } {
+  if (isFinished(token)) return CENTER;
+  if (isInYard(token)) {
+    const i = Number(token.id.split('-')[1]);
+    return HOME_YARDS[token.player][i] ?? CENTER;
+  }
+  if (token.progress <= 50) return MAIN_PATH[mainIndexAt(token.player, token.progress)]!;
+  return HOME_STRETCH[token.player][token.progress - 51]!;
+}
+
+/** The cells a token passes through for a move of `dice` (for the hop animation), start included. */
+export function journey(token: Token, dice: number): { row: number; col: number }[] {
+  const cells = [tokenCell(token)];
+  if (isInYard(token)) {
+    cells.push(MAIN_PATH[ENTRY[token.player]]!);
+    return cells;
+  }
+  for (let k = 1; k <= dice; k++) {
+    const p = token.progress + k;
+    cells.push(p >= TRACK_LENGTH ? CENTER : p <= 50 ? MAIN_PATH[mainIndexAt(token.player, p)]! : HOME_STRETCH[token.player][p - 51]!);
+  }
+  return cells;
+}
+
+/** Applies a move, returning the moved token and any opponent token it captured. */
+export function moveToken(token: Token, dice: number, players: Player[]): { moved: Token; captured: Token | null } {
+  const moved: Token = { ...token };
+  if (isInYard(token)) {
+    moved.progress = 0; // onto the entry cell
+  } else {
+    moved.progress = token.progress + dice;
+  }
+  let captured: Token | null = null;
+  // Capture only on the shared track, off a safe cell
+  if (moved.progress >= 0 && moved.progress <= 50) {
+    const landed = mainIndexAt(moved.player, moved.progress);
+    if (!SAFE_POSITIONS.includes(landed)) {
+      for (const p of players) {
+        if (p.color === token.player) continue;
+        for (const other of p.tokens) {
+          if (!isInYard(other) && !isFinished(other) && other.progress <= 50 && mainIndexAt(other.player, other.progress) === landed) {
+            captured = other;
+            break;
+          }
+        }
+        if (captured) break;
+      }
+    }
+  }
+  return { moved, captured };
+}
+
+export const isGameOver = (players: Player[]) => players.some((p) => p.finishedTokens === TOKENS_PER_PLAYER);
+export const getWinner = (players: Player[]) => players.find((p) => p.finishedTokens === TOKENS_PER_PLAYER) ?? null;
+
+/** The AI's pick: a weighted score per move, best 70% of the time (as the original medium AI). */
+export function selectAIMove(player: Player, dice: number, players: Player[]): Token | null {
+  const options = movableTokens(player, dice);
+  if (!options.length) return null;
+  const scored = options.map((token) => {
+    let score = 0;
+    const { moved, captured } = moveToken(token, dice, players);
+    if (captured) score += 100;
+    if (isInYard(token) && dice === 6) score += 50;
+    if (isFinished(moved)) score += 200;
+    if (!isInYard(token) && !isFinished(token)) score += moved.progress;
+    if (!isFinished(moved) && moved.progress <= 50 && SAFE_POSITIONS.includes(mainIndexAt(moved.player, moved.progress))) score += 30;
+    if (!isFinished(moved) && moved.progress <= 50 && !SAFE_POSITIONS.includes(mainIndexAt(moved.player, moved.progress))) {
+      const landed = mainIndexAt(moved.player, moved.progress);
+      for (const opp of players) {
+        if (opp.color === player.color) continue;
+        for (const t of opp.tokens) {
+          if (isInYard(t) || isFinished(t) || t.progress > 50) continue;
+          const dist = (landed - mainIndexAt(t.player, t.progress) + 52) % 52;
+          if (dist <= 6) score -= 20;
+        }
+      }
+    }
+    return { token, score };
+  });
+  scored.sort((a, b) => b.score - a.score);
+  if (Math.random() < 0.3 && scored.length > 1) return scored[Math.floor(Math.random() * scored.length)]!.token;
+  return scored[0]!.token;
+}
+
+export function calculateScore(player: Player): number {
+  let score = player.finishedTokens * 3000;
+  for (const t of player.tokens) if (!isInYard(t) && !isFinished(t)) score += Math.round(t.progress * 30);
+  return score;
+}

package/src/games/ludo-king/LudoKingScene.ts

@@ -0,0 +1,397 @@
+// Everything Ludo King draws, on the Nayan engine. An orthographic camera leans back over the classic
+// cross board, which lies in the world's XY plane (x right, y up, z up off it), one board unit (its
+// width) to `layout.size` view points. The board — frame, four homes, the cross of path tiles, the
+// coloured home columns and the centre star — is one static mesh; the eight pawns and the die are
+// their own entities. Every mesh is built once (mesh ids are app-wide and limited).
+import {
+  type Camera,
+  type Color,
+  effects,
+  type Entity,
+  extrude,
+  type GeometryPart,
+  lathe,
+  merge,
+  type Model,
+  Path,
+  type Quat,
+  quat,
+  shapeGeometry,
+  type Vec3,
+  type World
+} from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import { setBackdropTheme, spawnBackdrop } from '../shared/EngineBackdrop';
+import { dieMesh, dieRotation as sharedDieRotation, rollDie as rollSharedDie } from '../shared/EngineDice';
+import { cacheGameAsset, createGameMesh as createShape } from '../shared/EngineMeshes';
+import { aimTilted, placeTiltedBackdrop, type TiltView } from '../shared/EngineTilt';
+import { toColor } from '../shared/EngineUtils';
+import {
+  AI_COLOR,
+  BOARD_FRAME,
+  BOARD_WHITE,
+  cellPoint,
+  CENTER,
+  DIE_SIZE,
+  DIE_Y,
+  ENTRY,
+  GRID,
+  HOME_STRETCH,
+  HOME_YARDS,
+  type Layout,
+  MAIN_PATH,
+  PLAYER_COLOR,
+  PLAYER_COLORS,
+  type PlayerColor,
+  RIM,
+  SAFE_POSITIONS,
+  STAR_COLOR,
+  TILE_TOP,
+  TILT,
+  TOKEN_HEIGHT
+} from './LudoKingConstants';
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+const meshes = new Map<string, Model>();
+const cached = (key: string, build: () => Model) => {
+  let m = meshes.get(key);
+  if (!m) {
+    m = cacheGameAsset('ludo-king/LudoKingScene:' + key, build);
+    meshes.set(key, m);
+  }
+  return m;
+};
+const rgb = (css: string): [number, number, number] => {
+  const [r, g, b] = toColor(css);
+  return [r, g, b];
+};
+const cube = () => shapeGeometry('cube');
+const sphere = () => shapeGeometry('sphere');
+const STAND_UP = quat.x(Math.PI / 2);
+const CELL = 1 / GRID;
+
+// ── The board (board units; spawned at scale = size) ──────────────────
+
+const HOME_CORNER: { color: PlayerColor; row: number; col: number }[] = [
+  { color: 'blue', row: 0, col: 0 },
+  { color: 'red', row: 0, col: 9 },
+  { color: 'green', row: 9, col: 0 },
+  { color: 'yellow', row: 9, col: 9 }
+];
+
+// The board is flat, like a printed board (only the pawns and the die stand up in 3D): thin layers at
+// heights just far enough apart that the depth test always knows which is on top, yet well under a
+// pixel on screen. From the bottom: the frame, the white board, the home squares, the track tiles and
+// the centre, then the yards' rings and stars, then their white centres.
+const SKIN = 0.0004;
+const LAYER = 0.002;
+const layerZ = (k: number) => TILE_TOP - LAYER * 4 + LAYER * k;
+/** Above every layer of the board: pawn shadows, then the pawns and hint rings over them. */
+export const SHADOW_Z = layerZ(6);
+export const PAWN_Z = layerZ(7);
+
+/** The lines between cells: each cell sits on a square of this colour, a little bigger, showing round its edge. */
+const GRID_LINE: [number, number, number] = [0.55, 0.53, 0.62];
+
+function tile(parts: GeometryPart[], row: number, col: number, color: [number, number, number], inset = 0.92) {
+  const [x, y] = cellPoint(row, col);
+  parts.push({ geometry: cube(), position: [x, y, layerZ(2)], scale: [CELL, CELL, SKIN], color: [...GRID_LINE, 1] });
+  parts.push({ geometry: cube(), position: [x, y, layerZ(3)], scale: [CELL * inset, CELL * inset, SKIN], color: [...color, 1] });
+}
+
+const disc = (r: number) => extrude(new Path().addCircle(0, 0, r), { depth: SKIN });
+
+function boardMesh(): Model {
+  return cached('ludo-board', () => {
+    const outer = 1 + RIM * 2;
+    const frame = rgb(BOARD_FRAME);
+    const white = rgb(BOARD_WHITE);
+    const parts: GeometryPart[] = [
+      { geometry: cube(), position: [0, 0, layerZ(0)], scale: [outer, outer, SKIN], color: [...frame, 1] },
+      { geometry: cube(), position: [0, 0, layerZ(1)], scale: [1, 1, SKIN], color: [...white, 1] }
+    ];
+    // Four home bases: a coloured square, a white yard inside it, and four rings where the pawns wait
+    for (const { color, row, col } of HOME_CORNER) {
+      const c = rgb(PLAYER_COLORS[color]);
+      const [cx, cy] = cellPoint(row + 2.5, col + 2.5);
+      const size = 6 * CELL;
+      parts.push({ geometry: cube(), position: [cx, cy, layerZ(2)], scale: [size, size, SKIN], color: [...c, 1] });
+      parts.push({ geometry: cube(), position: [cx, cy, layerZ(3)], scale: [size * 0.68, size * 0.68, SKIN], color: [...white, 1] });
+      for (const yard of HOME_YARDS[color]) {
+        const [yx, yy] = cellPoint(yard.row, yard.col);
+        parts.push({ geometry: disc(0.5), position: [yx, yy, layerZ(4)], scale: [CELL * 1.5, CELL * 1.5, 1], color: [...c, 1] });
+        parts.push({ geometry: disc(0.5), position: [yx, yy, layerZ(5)], scale: [CELL * 0.9, CELL * 0.9, 1], color: [...white, 1] });
+      }
+    }
+    // The 52 shared track cells, a star on the safe ones
+    MAIN_PATH.forEach((cell, i) => {
+      const owner = (Object.keys(ENTRY) as PlayerColor[]).find((p) => ENTRY[p] === i);
+      const color = owner ? rgb(PLAYER_COLORS[owner]) : white;
+      tile(parts, cell.row, cell.col, color);
+      if (SAFE_POSITIONS.includes(i) && !owner) {
+        const [x, y] = cellPoint(cell.row, cell.col);
+        parts.push({
+          geometry: extrude(new Path().addStar(0, 0, 0.5, 0.22), { depth: SKIN }),
+          position: [x, y, layerZ(4)],
+          scale: [CELL * 0.7, CELL * 0.7, 1],
+          color: [...rgb(STAR_COLOR), 1]
+        });
+      }
+    });
+    // Coloured home columns, in exactly the player's colour (as their home, start cell and centre triangle)
+    for (const color of ['blue', 'red', 'green', 'yellow'] as PlayerColor[]) {
+      const c = rgb(PLAYER_COLORS[color]);
+      for (const cell of HOME_STRETCH[color]) tile(parts, cell.row, cell.col, c);
+    }
+    // The centre: four triangles meeting at the origin, each a player's colour (path y is drawn down)
+    // Its corners are the cell edges round the middle 3 x 3 (rows and columns 6 to 8): cellPoint gives
+    // a cell's centre, so half a cell out from the corner cells' centres
+    const corners = {
+      tl: cellPoint(5.5, 5.5),
+      tr: cellPoint(5.5, 8.5),
+      bl: cellPoint(8.5, 5.5),
+      br: cellPoint(8.5, 8.5)
+    };
+    const tri = (a: [number, number], b: [number, number], color: string) =>
+      parts.push({
+        geometry: extrude(
+          new Path().addPolygon([
+            [0, 0],
+            [a[0], -a[1]],
+            [b[0], -b[1]]
+          ]),
+          { depth: SKIN }
+        ),
+        position: [0, 0, layerZ(3)],
+        color: [...rgb(color), 1]
+      });
+    tri(corners.tl, corners.tr, PLAYER_COLORS.red); // top
+    tri(corners.tr, corners.br, PLAYER_COLORS.yellow); // right
+    tri(corners.br, corners.bl, PLAYER_COLORS.green); // bottom
+    tri(corners.bl, corners.tl, PLAYER_COLORS.blue); // left
+    // Matte, like printed card: no glossy highlight on the board (the pawns and die keep theirs)
+    return createShape(merge(parts), { center: false, shine: 0 });
+  });
+}
+
+// ── Pawn and die meshes ───────────────────────────────────────────────
+
+const pawnMesh = () =>
+  cached('ludo-pawn', () =>
+    createShape(
+      merge([
+        {
+          geometry: lathe(
+            [
+              [0.001, 0],
+              [0.42, 0],
+              [0.44, 0.04],
+              [0.42, 0.1],
+              [0.3, 0.14],
+              [0.24, 0.2],
+              [0.18, 0.44],
+              [0.15, 0.58],
+              [0.27, 0.61],
+              [0.27, 0.66],
+              [0.14, 0.69]
+            ],
+            { segments: 28 }
+          )
+        },
+        { geometry: sphere(), position: [0, 0.84, 0], scale: 0.42 }
+      ]),
+      { center: false, shine: 0.6 }
+    )
+  );
+
+/** The die showing `value` toward the camera (shared/EngineDice), turned `twist` round its up axis. */
+export const dieRotation = (value: number, twist = 0): Quat => sharedDieRotation(TILT, value, twist);
+
+const discMesh = () => cached('ludo-disc', () => createShape(extrude(new Path().addCircle(0, 0, 0.5), { depth: 0 })));
+const ringMesh = () =>
+  cached('ludo-ring', () => createShape(extrude(new Path().addCircle(0, 0, 0.5).addCircle(0, 0, 0.4), { depth: 0, fillRule: 'evenodd' })));
+
+// ── Scene ─────────────────────────────────────────────────────────────
+
+const SHADOW: Color = [0, 0, 0, 0.22];
+const BACKDROP_DEPTH = 25;
+
+export type Scene = {
+  backdrop: Entity;
+  board: Entity;
+  tokens: Map<string, Entity>;
+  tokenAt: Map<Entity, string>;
+  bobbing: Set<string>;
+  shadows: Map<string, Entity>;
+  die: Entity;
+  dieShadow: Entity;
+  ring: Entity;
+  hints: Entity[];
+};
+
+export const toWorld = (l: Layout, x: number, y: number, z: number): Vec3 => [x * l.size, y * l.size, z * l.size];
+const tiltView = (l: Layout): TiltView => ({ width: l.width, height: l.height, centerY: l.centerY, tilt: TILT });
+export const aimCamera = (camera: Camera, l: Layout) => aimTilted(camera, tiltView(l));
+export const dieRest = (l: Layout): Vec3 => toWorld(l, 0, DIE_Y, DIE_SIZE / 2);
+
+export function buildScene(world: World, l: Layout, theme: GameTheme, tokenIds: { id: string; color: PlayerColor }[]): Scene {
+  const backdrop = spawnBackdrop(world, l.width, l.height, -BACKDROP_DEPTH, theme);
+  placeTiltedBackdrop(world, backdrop, tiltView(l), BACKDROP_DEPTH);
+  const board = world.spawn({ mesh: boardMesh(), scale: l.size, color: [1, 1, 1, 1], pickable: false });
+  const tokens = new Map<string, Entity>();
+  const tokenAt = new Map<Entity, string>();
+  const shadows = new Map<string, Entity>();
+  for (const { id, color } of tokenIds) {
+    const e = world.spawn({ mesh: pawnMesh(), rotation: STAND_UP, scale: TOKEN_HEIGHT * l.size, color: toColor(PLAYER_COLORS[color]) });
+    tokens.set(id, e);
+    tokenAt.set(e, id);
+    shadows.set(id, world.spawn({ mesh: discMesh(), scale: 0.05 * l.size, color: SHADOW, pickable: false }));
+  }
+  const dieShadow = world.spawn({
+    mesh: discMesh(),
+    position: toWorld(l, 0.012, DIE_Y - 0.01, 0.001),
+    scale: [DIE_SIZE * 1.25 * l.size, DIE_SIZE * 1.1 * l.size, 1],
+    color: SHADOW,
+    pickable: false
+  });
+  const ring = world.spawn({ mesh: ringMesh(), position: toWorld(l, 0, DIE_Y, 0.002), scale: 0, color: [1, 0.78, 0.15, 0.85], pickable: false });
+  const die = world.spawn({ mesh: dieMesh(), position: dieRest(l), rotation: dieRotation(1), scale: DIE_SIZE * l.size });
+  const hints = Array.from({ length: 4 }, () => world.spawn({ mesh: ringMesh(), scale: 0, color: [1, 0.85, 0.2, 0.9], pickable: false }));
+  return { backdrop, board, tokens, tokenAt, bobbing: new Set(), shadows, die, dieShadow, ring, hints };
+}
+
+export function removeScene(world: World, s: Scene) {
+  world.despawn(s.backdrop);
+  world.despawn(s.board);
+  for (const e of s.tokens.values()) world.despawn(e);
+  for (const e of s.shadows.values()) world.despawn(e);
+  world.despawn(s.die);
+  world.despawn(s.dieShadow);
+  world.despawn(s.ring);
+  for (const e of s.hints) world.despawn(e);
+}
+
+export function setSceneTheme(world: World, s: Scene, theme: GameTheme) {
+  setBackdropTheme(world, s.backdrop, theme);
+}
+
+// ── Tokens ────────────────────────────────────────────────────────────
+
+/** When players share a cell they shoulder apart a little. */
+export function placeToken(world: World, l: Layout, s: Scene, id: string, cell: { row: number; col: number }, offset = 0) {
+  const [x, y] = cellPoint(cell.row, cell.col);
+  const token = s.tokens.get(id)!;
+  const shadow = s.shadows.get(id)!;
+  world.stopAnimation(token);
+  world.stopAnimation(shadow);
+  world.set(token, { position: toWorld(l, x + offset, y, PAWN_Z) });
+  world.set(shadow, { position: toWorld(l, x + offset + 0.006, y - 0.006, SHADOW_Z) });
+}
+
+/** Hops a token through a run of cells. */
+export function hopToken(world: World, l: Layout, s: Scene, id: string, cells: { row: number; col: number }[], time: number) {
+  const token = s.tokens.get(id)!;
+  const shadow = s.shadows.get(id)!;
+  const pts = cells.map((c) => cellPoint(c.row, c.col));
+  const keys = pts.slice(1).map((p, i) => ({ position: toWorld(l, p[0], p[1], PAWN_Z + 0.03), at: (i + 1) / (pts.length - 1) }));
+  const last = pts[pts.length - 1]!;
+  world.stopAnimation(token);
+  world.stopAnimation(shadow);
+  world.animate(token, keys, { duration: time, path: 'smooth', easing: 'easeInOut' });
+  world.animate(shadow, { position: toWorld(l, last[0] + 0.006, last[1] - 0.006, SHADOW_Z) }, { duration: time });
+}
+
+export function bobToken(world: World, l: Layout, s: Scene, ids: string[]) {
+  const next = new Set(ids);
+  for (const [id, e] of s.tokens)
+    if (next.has(id) !== s.bobbing.has(id)) world.set(e, { bob: next.has(id) ? { amplitude: [0, 0, 0.01 * l.size], speed: 6 } : null });
+  s.bobbing = next;
+}
+
+export function showHints(world: World, l: Layout, s: Scene, cells: { row: number; col: number }[]) {
+  const size = CELL * 1.5 * l.size;
+  s.hints.forEach((e, i) => {
+    const cell = cells[i];
+    if (!cell) {
+      world.stopAnimation(e);
+      world.set(e, { scale: 0 });
+      return;
+    }
+    const [x, y] = cellPoint(cell.row, cell.col);
+    world.set(e, { position: toWorld(l, x, y, PAWN_Z), scale: size });
+    world.stopAnimation(e);
+    world.animate(e, { scale: size * 1.2 }, { duration: 0.6, easing: 'easeInOut', repeat: 'forever', yoyo: true });
+  });
+}
+
+// ── The die ───────────────────────────────────────────────────────────
+
+/** The die is tossed, tumbles and bounces to rest showing `value` (shared/EngineDice). */
+export function rollDie(world: World, l: Layout, s: Scene, value: number, time: number, disposed?: () => boolean) {
+  rollSharedDie(world, {
+    die: s.die,
+    shadow: s.dieShadow,
+    rest: dieRest(l),
+    shadowAt: toWorld(l, 0.012, DIE_Y - 0.01, 0.001),
+    shadowScale: [DIE_SIZE * 1.25 * l.size, DIE_SIZE * 1.1 * l.size, 1],
+    size: DIE_SIZE * l.size,
+    tilt: TILT,
+    value,
+    duration: time,
+    disposed
+  });
+}
+
+export function showRollHint(world: World, l: Layout, s: Scene, on: boolean) {
+  world.stopAnimation(s.ring);
+  if (!on) {
+    world.set(s.ring, { scale: 0 });
+    return;
+  }
+  const size = DIE_SIZE * 1.55 * l.size;
+  world.set(s.ring, { scale: size });
+  world.animate(s.ring, { scale: size * 1.15 }, { duration: 0.6, easing: 'easeInOut', repeat: 'forever', yoyo: true });
+}
+
+// ── Bursts ────────────────────────────────────────────────────────────
+
+export function captureBurst(world: World, l: Layout, cell: { row: number; col: number }) {
+  const [x, y] = cellPoint(cell.row, cell.col);
+  effects.sparkle(world, {
+    position: toWorld(l, x, y, TILE_TOP + 0.03),
+    count: 18,
+    size: 0.01 * l.size,
+    speed: 0.4 * l.size,
+    lifetime: 0.5,
+    gravity: -0.6 * l.size,
+    colors: [toColor('#FFF59D'), toColor('#FF7043'), [1, 1, 1, 1]]
+  });
+}
+
+export function finishBurst(world: World, l: Layout) {
+  const [x, y] = cellPoint(CENTER.row, CENTER.col);
+  effects.sparkle(world, {
+    position: toWorld(l, x, y, TILE_TOP + 0.04),
+    count: 20,
+    size: 0.011 * l.size,
+    speed: 0.4 * l.size,
+    lifetime: 0.6,
+    colors: [toColor('#FFD54F'), toColor('#FFF59D'), [1, 1, 1, 1]]
+  });
+}
+
+export function confetti(world: World, l: Layout, winner: PlayerColor) {
+  const [x, y] = cellPoint(CENTER.row, CENTER.col);
+  effects.confetti(world, {
+    position: toWorld(l, x, y, TILE_TOP + 0.08),
+    count: 48,
+    size: 0.012 * l.size,
+    speed: 0.7 * l.size,
+    lifetime: 1.3,
+    gravity: -1.2 * l.size,
+    colors: [winner === 'green' ? PLAYER_COLOR : AI_COLOR, PLAYER_COLORS.yellow, PLAYER_COLORS.green, PLAYER_COLORS.blue, '#FFFFFF'].map((c) =>
+      toColor(c)
+    )
+  });
+}

package/src/games/maze-runner/MazeRunner.tsx

@@ -0,0 +1,88 @@
+// Maze Runner's screen, on the Nayan engine: the board, walls, pads and rolling ball are one 3D scene
+// (an orthographic camera directly above the maze), under Playtura's scoreboard, controls and
+// modals. The play is in MazeRunnerGame.ts (the maze and the roll in MazeRunnerRules.ts), what it
+// draws in MazeRunnerScene.ts.
+//
+// One world serves the whole visit: Start, Stop and Play Again reset it in place (a new maze's walls
+// rise in place) and a theme change repaints the board, so the GPU view is never rebuilt. JS rolls the
+// ball (a few numbers) and steps the world once a frame; the walls, pads and bursts animate in the
+// engine's Rust core.
+import { HapticType } from '../../services/HapticsService';
+import { GAME_SOUNDS } from '../../services/SoundsService';
+import { GAME_IDS } from '../../services/UtilsService';
+import { engineGame, EngineGameScreen } from '../shared/EngineGameScreen';
+import { timerColumn } from '../shared/EngineHud';
+import { useEngineGame } from '../shared/useEngineGame';
+import { useLiveState } from '../shared/useLiveState';
+import { BORDER, GAME_DURATION, getLayout, LIGHT, WALL_THICKNESS } from './MazeRunnerConstants';
+import { createGame, dispose, drag, type GameEvent, newMaze, setLayout, setTheme, start, stop, tick } from './MazeRunnerGame';
+
+const SOUNDS = GAME_SOUNDS.MAZE_RUNNER;
+
+/** Quiet turns and bounded collision feedback, with separate completion and timeout cues. */
+const FEEDBACK: Record<GameEvent, { sound?: (typeof SOUNDS)[keyof typeof SOUNDS]; haptic: HapticType }> = {
+  turn: { sound: SOUNDS.TURN, haptic: HapticType.LIGHT },
+  bump: { sound: SOUNDS.BUMP, haptic: HapticType.MEDIUM },
+  win: { sound: SOUNDS.COMPLETE, haptic: HapticType.SUCCESS },
+  lose: { sound: SOUNDS.GAME_OVER, haptic: HapticType.ERROR }
+};
+
+const timeUpText = () => 'You ran out of time!';
+
+export const MazeRunner = engineGame(GAME_IDS.MAZE_RUNNER, (props) => {
+  const [time, setTime] = useLiveState(GAME_DURATION);
+  const [showCard, setShowCard] = useLiveState(false);
+
+  // Win or lose as the run ends; the card comes up a beat later, through `onCard`
+  const { game, theme, status, screen, gameOver } = useEngineGame(props, {
+    gameId: GAME_IDS.MAZE_RUNNER,
+    create: createGame,
+    start,
+    // Stop: the same maze, the ball back at the start
+    reset: stop,
+    // Play Again: a new maze, waiting for Start
+    replay: newMaze,
+    dispose,
+    tick,
+    setTheme,
+    resize: (g, width, height, offset) => {
+      const l = getLayout(width, height, offset);
+      setLayout(g, l);
+      return l.size + l.cell * WALL_THICKNESS + BORDER * 2;
+    },
+    drag,
+    sounds: SOUNDS,
+    onStart: (fx) => {
+      setShowCard(false);
+      fx(SOUNDS.START, HapticType.MEDIUM);
+    },
+    onStop: (fx) => fx(null),
+    onPlayAgain: () => setShowCard(false),
+    wire: (g, fx) => {
+      g.onCard = () => setShowCard(true);
+      g.onTime = setTime;
+      g.onEvent = (event) => fx(FEEDBACK[event].sound, FEEDBACK[event].haptic);
+    }
+  });
+
+  return (
+    <EngineGameScreen
+      {...screen}
+      light={LIGHT}
+      columns={[timerColumn(time, theme)]}
+      subtext="Swipe to roll!"
+      gameOver={
+        showCard
+          ? gameOver({
+              title: status === 'win' ? 'MAZE COMPLETE!' : 'TIME UP!',
+              message: status === 'win' ? 'You found the exit!' : 'You ran out of time!',
+              scoreLabel: status === 'win' ? 'Score' : "Time's Up!",
+              score: game.score,
+              formatter: status === 'win' ? undefined : timeUpText,
+              buttonText: status === 'win' ? 'Navigate Again!' : 'Try Again!'
+            })
+          : null
+      }
+    />
+  );
+});