@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/pac-man/PacManRules.ts

@@ -0,0 +1,255 @@
+// Pac-Man's rules, with no React or engine: the maze, Pac-Man's grid move, the four ghosts' targeting
+// AI, dots, pellets and the fruit. Ported from the original version (games/pac-man/PacManService), the same
+// moves in the same order, so the game plays and scores the same.
+import {
+  CellType,
+  COLS,
+  type Direction,
+  DIRECTIONS,
+  GHOST_SCATTER,
+  GHOST_START,
+  GhostMode,
+  GhostName,
+  OPPOSITE,
+  PACMAN_MAZE,
+  PACMAN_START,
+  ROWS
+} from './PacManConstants';
+
+export type Position = { x: number; y: number };
+
+export type Pacman = { x: number; y: number; direction: Direction; nextDirection: Direction };
+
+export type Ghost = {
+  name: GhostName;
+  x: number;
+  y: number;
+  direction: Direction;
+  mode: GhostMode;
+  previousMode: GhostMode;
+  /** Seconds of fright left. */
+  frightenedTimer: number;
+  isFlashing: boolean;
+};
+
+export type Fruit = { x: number; y: number } | null;
+
+export type Maze = { cells: number[][]; dotsRemaining: number; totalDots: number };
+
+const GHOST_DIRS: Direction[] = ['UP', 'DOWN', 'LEFT', 'RIGHT'];
+
+// ── Setup ─────────────────────────────────────────────────────────────
+
+export function initMaze(): Maze {
+  const cells = PACMAN_MAZE.map((row) => [...row]);
+  let dots = 0;
+  for (const row of cells) for (const c of row) if (c === CellType.DOT || c === CellType.POWER_PELLET) dots++;
+  return { cells, dotsRemaining: dots, totalDots: dots };
+}
+
+export const initPacman = (): Pacman => ({ x: PACMAN_START.x, y: PACMAN_START.y, direction: 'LEFT', nextDirection: 'LEFT' });
+
+const makeGhost = (name: GhostName, mode: GhostMode): Ghost => ({
+  name,
+  x: GHOST_START[name].x,
+  y: GHOST_START[name].y,
+  direction: 'UP',
+  mode,
+  previousMode: GhostMode.SCATTER,
+  frightenedTimer: 0,
+  isFlashing: false
+});
+
+export const initGhosts = (): Ghost[] => [
+  makeGhost(GhostName.BLINKY, GhostMode.SCATTER),
+  makeGhost(GhostName.PINKY, GhostMode.IN_HOUSE),
+  makeGhost(GhostName.INKY, GhostMode.IN_HOUSE),
+  makeGhost(GhostName.CLYDE, GhostMode.IN_HOUSE)
+];
+
+// ── Moving ────────────────────────────────────────────────────────────
+
+export function canMove(cells: number[][], x: number, y: number): boolean {
+  if (y < 0 || y >= ROWS) return false;
+  if (x < 0 || x >= COLS) return true; // the side tunnel
+  const cell = cells[y]?.[x];
+  return cell !== CellType.WALL && cell !== CellType.GHOST_DOOR;
+}
+
+export function canGhostMove(cells: number[][], x: number, y: number, ghost: Ghost): boolean {
+  if (y < 0 || y >= ROWS) return false;
+  if (x < 0 || x >= COLS) return true;
+  const cell = cells[y]?.[x];
+  if (cell === CellType.GHOST_DOOR) return ghost.mode === GhostMode.LEAVING_HOUSE || ghost.mode === GhostMode.EATEN;
+  return cell !== CellType.WALL;
+}
+
+/** One cell forward, taking the queued turn when it opens up. Returns whether the maze wrapped round the side. */
+export function stepPacman(p: Pacman, cells: number[][]): { moved: boolean; wrapped: boolean } {
+  if (p.nextDirection !== p.direction) {
+    const nd = DIRECTIONS[p.nextDirection];
+    if (canMove(cells, p.x + nd.x, p.y + nd.y)) p.direction = p.nextDirection;
+  }
+  const dir = DIRECTIONS[p.direction];
+  let nx = p.x + dir.x;
+  const ny = p.y + dir.y;
+  let wrapped = false;
+  if (nx < 0) {
+    nx = COLS - 1;
+    wrapped = true;
+  } else if (nx >= COLS) {
+    nx = 0;
+    wrapped = true;
+  }
+  if (canMove(cells, nx, ny)) {
+    p.x = nx;
+    p.y = ny;
+    return { moved: true, wrapped };
+  }
+  return { moved: false, wrapped: false };
+}
+
+/** Eats whatever is on a cell. */
+export function eatAt(maze: Maze, x: number, y: number): { points: number; pellet: boolean } | null {
+  const row = maze.cells[y];
+  if (!row) return null;
+  if (row[x] === CellType.DOT) {
+    row[x] = CellType.EMPTY;
+    maze.dotsRemaining--;
+    return { points: 100, pellet: false };
+  }
+  if (row[x] === CellType.POWER_PELLET) {
+    row[x] = CellType.EMPTY;
+    maze.dotsRemaining--;
+    return { points: 500, pellet: true };
+  }
+  return null;
+}
+
+// ── Ghost AI (as the original version) ────────────────────────────────────
+
+function chaseTarget(ghost: Ghost, pacman: Pacman, blinky: Position | null): Position {
+  const d = DIRECTIONS[pacman.direction];
+  switch (ghost.name) {
+    case GhostName.BLINKY:
+      return { x: pacman.x, y: pacman.y };
+    case GhostName.PINKY:
+      return {
+        x: Math.max(0, Math.min(COLS - 1, pacman.x + d.x * 4)),
+        y: Math.max(0, Math.min(ROWS - 1, pacman.y + d.y * 4))
+      };
+    case GhostName.INKY:
+      if (blinky) {
+        const ax = pacman.x + d.x * 2;
+        const ay = pacman.y + d.y * 2;
+        return {
+          x: Math.max(0, Math.min(COLS - 1, ax + (ax - blinky.x))),
+          y: Math.max(0, Math.min(ROWS - 1, ay + (ay - blinky.y)))
+        };
+      }
+      return { x: pacman.x, y: pacman.y };
+    case GhostName.CLYDE: {
+      const dist = Math.abs(pacman.x - ghost.x) + Math.abs(pacman.y - ghost.y);
+      return dist > 8 ? { x: pacman.x, y: pacman.y } : GHOST_SCATTER[GhostName.CLYDE];
+    }
+    default:
+      return { x: pacman.x, y: pacman.y };
+  }
+}
+
+const wrap = (x: number) => (x < 0 ? COLS - 1 : x >= COLS ? 0 : x);
+
+function candidates(cells: number[][], ghost: Ghost, output: Direction[]): number {
+  output.length = 0;
+  const back = OPPOSITE[ghost.direction];
+  for (const dir of GHOST_DIRS) {
+    const d = DIRECTIONS[dir];
+    if (dir !== back && canGhostMove(cells, ghost.x + d.x, ghost.y + d.y, ghost)) output.push(dir);
+  }
+  if (!output.length) {
+    const d = DIRECTIONS[back];
+    if (canGhostMove(cells, ghost.x + d.x, ghost.y + d.y, ghost)) output.push(back);
+  }
+  return output.length;
+}
+const ghostDirections: Direction[] = [];
+
+function toward(cells: number[][], ghost: Ghost, tx: number, ty: number): Ghost {
+  const g = { ...ghost };
+  if (!candidates(cells, ghost, ghostDirections)) return g;
+  let best = ghostDirections[0]!,
+    bestD = Infinity;
+  for (const dir of ghostDirections) {
+    const step = DIRECTIONS[dir];
+    const dx = ghost.x + step.x - tx,
+      dy = ghost.y + step.y - ty;
+    const d = dx * dx + dy * dy;
+    if (d < bestD) {
+      bestD = d;
+      best = dir;
+    }
+  }
+  const delta = DIRECTIONS[best];
+  g.x = wrap(ghost.x + delta.x);
+  g.y = ghost.y + delta.y;
+  g.direction = best;
+  return g;
+}
+
+function randomly(cells: number[][], ghost: Ghost): Ghost {
+  const g = { ...ghost };
+  if (!candidates(cells, ghost, ghostDirections)) return g;
+  const dir = ghostDirections[Math.floor(Math.random() * ghostDirections.length)]!;
+  const delta = DIRECTIONS[dir];
+  g.x = wrap(ghost.x + delta.x);
+  g.y = ghost.y + delta.y;
+  g.direction = dir;
+  return g;
+}
+
+/** One cell of ghost movement, by its mode. `blinky` is Blinky's cell before this step (Inky aims off it). */
+export function moveGhost(cells: number[][], ghost: Ghost, pacman: Pacman, blinky: Position | null): Ghost {
+  switch (ghost.mode) {
+    case GhostMode.IN_HOUSE:
+      return { ...ghost };
+    case GhostMode.LEAVING_HOUSE: {
+      const g = { ...ghost };
+      if (ghost.y > 7) {
+        g.y--;
+        g.direction = 'UP';
+      } else {
+        g.mode = GhostMode.SCATTER;
+        g.direction = 'LEFT';
+      }
+      return g;
+    }
+    case GhostMode.EATEN:
+      return toward(cells, ghost, 9, 9);
+    case GhostMode.FRIGHTENED:
+      return randomly(cells, ghost);
+    case GhostMode.SCATTER: {
+      const t = GHOST_SCATTER[ghost.name];
+      return toward(cells, ghost, t.x, t.y);
+    }
+    case GhostMode.CHASE: {
+      const t = chaseTarget(ghost, pacman, blinky);
+      return toward(cells, ghost, t.x, t.y);
+    }
+    default:
+      return { ...ghost };
+  }
+}
+
+export function frightenGhosts(ghosts: Ghost[], duration: number): Ghost[] {
+  return ghosts.map((g) =>
+    g.mode === GhostMode.EATEN || g.mode === GhostMode.IN_HOUSE
+      ? g
+      : { ...g, previousMode: g.mode, mode: GhostMode.FRIGHTENED, frightenedTimer: duration, isFlashing: false, direction: OPPOSITE[g.direction] }
+  );
+}
+
+export const releaseGhost = (g: Ghost): Ghost => (g.mode === GhostMode.IN_HOUSE ? { ...g, mode: GhostMode.LEAVING_HOUSE } : g);
+
+export const reachedHouse = (g: Ghost): Ghost => (g.mode === GhostMode.EATEN && g.x === 9 && g.y === 9 ? { ...g, mode: GhostMode.LEAVING_HOUSE } : g);
+
+export const collides = (p: Pacman, g: Ghost) => p.x === g.x && p.y === g.y;

package/src/games/pac-man/PacManScene.ts

@@ -0,0 +1,387 @@
+// Everything Pac-Man draws, on the Nayan engine: a walled maze lying in the world's XY plane seen from
+// a little in front of straight down (shared/EngineTilt), the dots and power pellets glinting in its
+// corridors, Pac-Man as a solid yellow disc with a chomping wedge of a mouth, the four ghosts as classic
+// domed ghosts with wavy skirts and eyes, and the fruit. The maze (base and raised walls) is one static mesh; the dots are small
+// spheres despawned as they're eaten; Pac-Man, the ghosts and the fruit are their own little rigs.
+import {
+  effects,
+  type Entity,
+  extrude,
+  type GeometryPart,
+  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 { createGameMesh as createShape } from '../shared/EngineMeshes';
+import { placeTiltedBackdrop } from '../shared/EngineTilt';
+import { toColor } from '../shared/EngineUtils';
+import {
+  CellType,
+  COLORS,
+  COLS,
+  type Direction,
+  GHOST_COLORS,
+  GHOST_LIST,
+  GhostMode,
+  GhostName,
+  gridPoint,
+  type Layout,
+  PACMAN_MAZE,
+  ROWS
+} from './PacManConstants';
+
+const BOARD_DEPTH = 0.18; // the base slab, in cell units
+const WALL_H = 0.62; // raised wall height, in cell units
+const BACKDROP_DEPTH = 24;
+
+const cube = () => shapeGeometry('cube');
+
+// ── Static maze mesh (cell units; spawned at scale = cell) ────────────
+
+let boardModel: Model | null = null;
+function boardMesh(): Model {
+  if (boardModel) return boardModel;
+  const halfX = COLS / 2;
+  const halfY = ROWS / 2;
+  const wall = toColor(COLORS.WALL);
+  const edge = toColor(COLORS.WALL_EDGE);
+  const base = toColor(COLORS.BOARD);
+  const parts: GeometryPart[] = [{ geometry: cube(), position: [0, 0, -BOARD_DEPTH / 2], scale: [COLS, ROWS, BOARD_DEPTH], color: base }];
+  for (let y = 0; y < ROWS; y++) {
+    for (let x = 0; x < COLS; x++) {
+      if (PACMAN_MAZE[y]![x] !== CellType.WALL) continue;
+      const cx = x + 0.5 - halfX;
+      const cy = halfY - (y + 0.5);
+      parts.push({ geometry: cube(), position: [cx, cy, WALL_H / 2], scale: [1, 1, WALL_H], color: wall });
+      parts.push({ geometry: cube(), position: [cx, cy, WALL_H + 0.01], scale: [0.78, 0.78, 0.04], color: edge });
+    }
+  }
+  boardModel = createShape(merge(parts), { center: false, shine: 0.25 });
+  return boardModel;
+}
+
+// ── Scene ─────────────────────────────────────────────────────────────
+
+type GhostRig = { root: Entity; body: Entity; eyes: [Entity, Entity]; pupils: [Entity, Entity] };
+
+export type Scene = {
+  backdrop: Entity;
+  board: Entity;
+  dots: Map<number, Entity>;
+  pacman: Entity;
+  mouth: Entity;
+  /** The mouth's full size (world units): it chomps between almost shut and this. */
+  mouthSize: number;
+  ghosts: Record<GhostName, GhostRig>;
+  fruit: Entity | null;
+};
+
+const dotKey = (x: number, y: number) => y * COLS + x;
+const worldAt = (l: Layout, cx: number, cy: number, z: number): Vec3 => {
+  const [x, y] = gridPoint(l, cx, cy);
+  return [x, y, z];
+};
+
+/** The mouth wedge turns so it opens the way Pac-Man heads. */
+const MOUTH_ANGLE: Record<Direction, number> = { RIGHT: Math.PI / 2, LEFT: -Math.PI / 2, UP: Math.PI, DOWN: 0, NONE: Math.PI / 2 };
+const mouthRotation = (d: Direction): Quat => quat.z(MOUTH_ANGLE[d]);
+
+function spawnDots(world: World, l: Layout, s: Scene) {
+  const dotZ = l.cell * 0.22;
+  for (let y = 0; y < ROWS; y++) {
+    for (let x = 0; x < COLS; x++) {
+      const cell = PACMAN_MAZE[y]![x];
+      if (cell === CellType.DOT) {
+        s.dots.set(
+          dotKey(x, y),
+          world.spawn({
+            mesh: 'sphere',
+            position: worldAt(l, x + 0.5, y + 0.5, dotZ),
+            scale: l.cell * 0.17,
+            color: toColor(COLORS.DOT),
+            pickable: false
+          })
+        );
+      } else if (cell === CellType.POWER_PELLET) {
+        s.dots.set(
+          dotKey(x, y),
+          world.spawn({
+            mesh: 'sphere',
+            position: worldAt(l, x + 0.5, y + 0.5, l.cell * 0.3),
+            scale: l.cell * 0.46,
+            color: toColor(COLORS.PELLET),
+            bob: { amplitude: [0, 0, l.cell * 0.08], speed: 5 },
+            pickable: false
+          })
+        );
+      }
+    }
+  }
+}
+
+// ── Characters: the classic flat shapes lying on the board, in solid colours ──
+
+/** A colour lit from within at full strength: it shows the same solid hue whatever the light. */
+const solid = (css: string): [number, number, number, number] => {
+  const [r, g, b] = toColor(css);
+  const k = 2 / Math.max(r, g, b, 0.01);
+  return [r * k, g * k, b * k, 1];
+};
+/** How thick the flat characters are, and where their top face sits, as fractions of their size. */
+const THICK = 0.3;
+/** Each character's root floats half its size up; its flat body sits on the board below it. */
+const BODY_Z = -0.5 + THICK / 2;
+const TOP_Z = BODY_Z + THICK / 2 + 0.01;
+
+let pacModel: Model | null = null;
+let mouthModel: Model | null = null;
+let ghostModel: Model | null = null;
+let discModel: Model | null = null;
+/** Pac-Man's body: a disc one unit across. */
+const pacMesh = () => (pacModel ??= createShape(extrude(new Path().addCircle(0, 0, 0.5), { depth: THICK })));
+/** His mouth: a wedge from the centre opening toward -y (turned to face his way), in the board's colour. */
+const mouthMesh = () => {
+  if (mouthModel) return mouthModel;
+  const path = new Path().moveTo(0, 0);
+  const half = 0.62; // radians either side
+  for (let i = 0; i <= 8; i++) {
+    const a = -half + (i / 8) * half * 2;
+    path.lineTo(Math.sin(a) * 0.56, Math.cos(a) * 0.56); // the path's y runs down: +y here is -y in the world
+  }
+  path.close();
+  mouthModel = createShape(extrude(path, { depth: 0 }), { center: false });
+  return mouthModel;
+};
+/** A ghost: a domed head, straight sides and a wavy skirt, one unit across. */
+const ghostMesh = () => {
+  if (ghostModel) return ghostModel;
+  const pts: [number, number][] = []; // world-up y
+  for (let i = 0; i <= 16; i++) {
+    const a = (i / 16) * Math.PI;
+    pts.push([Math.cos(a) * 0.5, 0.05 + Math.sin(a) * 0.5]);
+  }
+  pts.push([-0.5, -0.38]);
+  // The skirt: three points hanging down, with notches between
+  const bumps = 3;
+  for (let i = 0; i <= bumps * 2; i++) pts.push([-0.5 + (i / (bumps * 2)) * 1, i % 2 ? -0.5 : -0.36]);
+  pts.push([0.5, -0.38]);
+  const path = new Path().moveTo(pts[0]![0], -pts[0]![1]);
+  for (const [x, y] of pts.slice(1)) path.lineTo(x, -y);
+  path.close();
+  ghostModel = createShape(extrude(path, { depth: THICK }));
+  return ghostModel;
+};
+const flatDisc = () => (discModel ??= createShape(extrude(new Path().addCircle(0, 0, 0.5), { depth: 0 })));
+
+function spawnPacman(world: World, l: Layout): { pacman: Entity; mouth: Entity } {
+  const d = l.cell * 0.86;
+  const pacman = world.spawn({ mesh: 'none', position: worldAt(l, 9.5, 15.5, d / 2), pickable: false });
+  world.spawn({ mesh: pacMesh(), parent: pacman, position: [0, 0, BODY_Z * d], scale: d, color: solid(COLORS.PACMAN), pickable: false });
+  const mouth = world.spawn({
+    mesh: mouthMesh(),
+    parent: pacman,
+    position: [0, 0, TOP_Z * d],
+    rotation: mouthRotation('LEFT'),
+    scale: d,
+    color: toColor(COLORS.BOARD),
+    pickable: false
+  });
+  return { pacman, mouth };
+}
+
+function spawnGhost(world: World, l: Layout, name: GhostName): GhostRig {
+  const d = l.cell * 0.86;
+  const root = world.spawn({ mesh: 'none', position: worldAt(l, 9.5, 7.5, d * 0.5), pickable: false });
+  const body = world.spawn({
+    mesh: ghostMesh(),
+    parent: root,
+    position: [0, 0, BODY_Z * d],
+    scale: d,
+    color: solid(GHOST_COLORS[name]),
+    pickable: false
+  });
+  const eye = (sx: number) =>
+    world.spawn({
+      mesh: flatDisc(),
+      parent: root,
+      position: [sx * d * 0.19, d * 0.1, TOP_Z * d],
+      scale: [d * 0.26, d * 0.32, 1],
+      color: solid(COLORS.EYE),
+      pickable: false
+    });
+  const pupil = (sx: number) =>
+    world.spawn({
+      mesh: flatDisc(),
+      parent: root,
+      position: [sx * d * 0.19, d * 0.06, (TOP_Z + 0.01) * d],
+      scale: d * 0.13,
+      color: solid(COLORS.PUPIL),
+      pickable: false
+    });
+  return { root, body, eyes: [eye(-1), eye(1)], pupils: [pupil(-1), pupil(1)] };
+}
+
+export function buildScene(world: World, l: Layout, theme: GameTheme): Scene {
+  const backdrop = spawnBackdrop(world, l.width, l.height, -BACKDROP_DEPTH, theme);
+  placeTiltedBackdrop(world, backdrop, l, BACKDROP_DEPTH);
+  const board = world.spawn({ mesh: boardMesh(), scale: l.cell, color: [1, 1, 1, 1], pickable: false });
+  const { pacman, mouth } = spawnPacman(world, l);
+  const ghosts = {} as Record<GhostName, GhostRig>;
+  for (const name of GHOST_LIST) ghosts[name] = spawnGhost(world, l, name);
+  const scene: Scene = { backdrop, board, dots: new Map(), pacman, mouth, mouthSize: l.cell * 0.86, ghosts, fruit: null };
+  spawnDots(world, l, scene);
+  return scene;
+}
+
+export function removeScene(world: World, s: Scene) {
+  world.despawn(s.backdrop);
+  world.despawn(s.board);
+  for (const e of s.dots.values()) world.despawn(e);
+  world.despawn(s.pacman);
+  for (const name of GHOST_LIST) world.despawn(s.ghosts[name].root);
+  if (s.fruit != null) world.despawn(s.fruit);
+}
+
+export function setSceneTheme(world: World, s: Scene, theme: GameTheme) {
+  setBackdropTheme(world, s.backdrop, theme);
+}
+
+// ── Dots, pellets, fruit ──────────────────────────────────────────────
+
+export function eatDot(world: World, s: Scene, x: number, y: number) {
+  const e = s.dots.get(dotKey(x, y));
+  if (e != null) {
+    world.despawn(e);
+    s.dots.delete(dotKey(x, y));
+  }
+}
+
+export function clearDots(world: World, s: Scene) {
+  for (const e of s.dots.values()) world.despawn(e);
+  s.dots.clear();
+}
+
+export function placeFruit(world: World, l: Layout, s: Scene, fruit: { x: number; y: number } | null) {
+  if (s.fruit != null) {
+    world.despawn(s.fruit);
+    s.fruit = null;
+  }
+  if (!fruit) return;
+  const d = l.cell * 0.7;
+  const root = world.spawn({
+    mesh: 'none',
+    position: worldAt(l, fruit.x + 0.5, fruit.y + 0.5, d / 2),
+    bob: { amplitude: [0, 0, l.cell * 0.1], speed: 4 },
+    pickable: false
+  });
+  world.spawn({ mesh: 'sphere', parent: root, scale: d, color: toColor(COLORS.FRUIT), pickable: false });
+  world.spawn({
+    mesh: 'cylinder',
+    parent: root,
+    position: [0, d * 0.1, d * 0.5],
+    scale: [d * 0.08, d * 0.4, d * 0.08],
+    color: toColor(COLORS.FRUIT_STEM),
+    pickable: false
+  });
+  world.set(root, { scale: 0.01 });
+  world.animate(root, { scale: 1 }, { duration: 0.25, easing: 'back' });
+  s.fruit = root;
+}
+
+export function fruitEaten(world: World, l: Layout, s: Scene, x: number, y: number) {
+  effects.sparkle(world, {
+    position: worldAt(l, x + 0.5, y + 0.5, l.cell * 0.5),
+    count: 18,
+    size: l.cell * 0.12,
+    speed: l.cell * 5,
+    lifetime: 0.5,
+    gravity: -l.cell * 8,
+    colors: [toColor('#FF5252'), toColor('#FFCDD2'), [1, 1, 1, 1]]
+  });
+  placeFruit(world, l, s, null);
+}
+
+// ── Pac-Man ───────────────────────────────────────────────────────────
+
+/** Moves Pac-Man to a cell: gliding over `time`, or snapping across the side tunnel. */
+export function movePacman(world: World, l: Layout, s: Scene, cx: number, cy: number, dir: Direction, time: number, snap: boolean) {
+  const d = l.cell * 0.86;
+  const pos = worldAt(l, cx + 0.5, cy + 0.5, d / 2);
+  world.set(s.mouth, { rotation: mouthRotation(dir) });
+  if (snap) world.set(s.pacman, { position: pos });
+  else world.animate(s.pacman, { position: pos }, { duration: time, easing: 'linear' });
+}
+
+export function setPacman(world: World, l: Layout, s: Scene, cx: number, cy: number, dir: Direction) {
+  const d = l.cell * 0.86;
+  world.stopAnimation(s.pacman);
+  world.set(s.pacman, { position: worldAt(l, cx + 0.5, cy + 0.5, d / 2) });
+  world.set(s.mouth, { rotation: mouthRotation(dir) });
+}
+
+/** The mouth chomps open and shut while Pac-Man moves. */
+export function startChomp(world: World, s: Scene, chompTime: number) {
+  world.stopAnimation(s.mouth);
+  world.set(s.mouth, { scale: s.mouthSize * 0.05 });
+  world.animate(s.mouth, { scale: s.mouthSize }, { duration: chompTime, easing: 'easeInOut', repeat: 'forever', yoyo: true });
+}
+
+/** The mouth stops, half open (his look at rest). */
+export function stopChomp(world: World, s: Scene) {
+  world.stopAnimation(s.mouth);
+  world.set(s.mouth, { scale: s.mouthSize * 0.6 });
+}
+
+/** Pac-Man caught: a flash of yellow sparks where he stood. */
+export function pacmanHit(world: World, l: Layout, cx: number, cy: number) {
+  effects.explosion(world, {
+    position: worldAt(l, cx + 0.5, cy + 0.5, l.cell * 0.5),
+    count: 26,
+    size: l.cell * 0.5,
+    speed: l.cell * 4,
+    lifetime: 0.6,
+    colors: [toColor('#FFE000'), toColor('#FFB000')]
+  });
+}
+
+// ── Ghosts ────────────────────────────────────────────────────────────
+
+const ghostLook = (mode: GhostMode, name: GhostName, flashing: boolean) => {
+  if (mode === GhostMode.FRIGHTENED) return solid(flashing ? COLORS.FRIGHTENED_FLASH : COLORS.FRIGHTENED);
+  return solid(GHOST_COLORS[name]);
+};
+
+export function moveGhost(world: World, l: Layout, s: Scene, name: GhostName, cx: number, cy: number, time: number, snap: boolean) {
+  const d = l.cell * 0.86;
+  const pos = worldAt(l, cx + 0.5, cy + 0.5, d * 0.5);
+  const rig = s.ghosts[name];
+  if (snap) world.set(rig.root, { position: pos });
+  else world.animate(rig.root, { position: pos }, { duration: time, easing: 'linear' });
+}
+
+/** A ghost's colour and body (just the eyes race home when eaten) for its mode. */
+export function dressGhost(world: World, l: Layout, s: Scene, name: GhostName, mode: GhostMode, flashing: boolean) {
+  const d = l.cell * 0.86;
+  const rig = s.ghosts[name];
+  const eaten = mode === GhostMode.EATEN;
+  world.set(rig.body, { scale: eaten ? 0 : d, color: ghostLook(mode, name, flashing) });
+}
+
+export function ghostEaten(world: World, l: Layout, cx: number, cy: number) {
+  effects.sparkle(world, {
+    position: worldAt(l, cx + 0.5, cy + 0.5, l.cell * 0.5),
+    count: 16,
+    size: l.cell * 0.12,
+    speed: l.cell * 4,
+    lifetime: 0.4,
+    gravity: -l.cell * 6,
+    colors: [toColor('#80DEFF'), [1, 1, 1, 1]]
+  });
+}