@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/snakes-and-ladders/SnakesAndLaddersScene.ts

@@ -0,0 +1,515 @@
+// Everything Snakes and Ladders draws. An orthographic camera leaning back from straight down over a
+// wooden board; the board lies in the world's XY plane (x right, y up the board, z up off it), centred
+// on the origin, one board unit (the playing area's width) to `layout.size` world units (view points).
+// The board, its cells, frame, snakes, ladders and the start pad are one static mesh; the cell numbers
+// are ten digit meshes shared by every cell (one instanced draw each); the pawns, the die and their
+// shadows are entities of their own. 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,
+  tube,
+  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 { flatGlyphMesh, GLYPH_ADVANCE, GLYPH_WIDTH } from '../shared/EngineGlyphs';
+import { noise } from '../shared/EngineMeadow';
+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_SIZE,
+  CELL_PALETTE,
+  cellCenter,
+  DIE_SIZE,
+  DIE_Y,
+  FINISH_CELL,
+  LADDER_AT,
+  type LadderData,
+  LADDERS,
+  type Layout,
+  NUMBER_COLOR,
+  PLAYER_COLOR,
+  RIM,
+  SNAKE_AT,
+  type SnakeData,
+  SNAKES,
+  STAR_NUMBER_COLOR,
+  START_CELL,
+  START_X,
+  START_Z,
+  TILE_TOP,
+  TILT,
+  TOKEN_HEIGHT,
+  WINNING_POSITION
+} from './SnakesAndLaddersConstants';
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+const meshes = new Map<string, Model>();
+const cached = (key: string, build: () => Model) => {
+  let m = meshes.get(key);
+  if (!m) {
+    m = cacheGameAsset('snakes-and-ladders/SnakesAndLaddersScene:' + key, build);
+    meshes.set(key, m);
+  }
+  return m;
+};
+type RGB = [number, number, number];
+const rgb = (css: string): RGB => {
+  const [r, g, b] = toColor(css);
+  return [r, g, b];
+};
+const mix = (a: RGB, b: RGB, t: number): RGB => [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t];
+const shade = (c: RGB, k: number): RGB => [c[0] * k, c[1] * k, c[2] * k];
+const smooth = (a: number, b: number, x: number) => {
+  const t = Math.min(1, Math.max(0, (x - a) / (b - a)));
+  return t * t * (3 - 2 * t);
+};
+const sphere = () => shapeGeometry('sphere');
+const cube = () => shapeGeometry('cube');
+/** Stands a lathe (built around +y) up off the board (+z). */
+const STAND_UP = quat.x(Math.PI / 2);
+type V2 = [number, number];
+const along = (a: V2, b: V2, t: number): V2 => [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t];
+
+// ── Snakes ────────────────────────────────────────────────────────────
+
+const SNAKE_POINTS = 30;
+const snakeRadius = (t: number) => 0.0135 * (0.8 + 0.2 * smooth(0, 0.15, t)) * (1 - 0.85 * smooth(0.5, 1, t));
+
+/**
+ * A snake's spine from its head (t = 0) to its tail tip (t = 1): an S-curve across the board, on the
+ * cells (with `raised`, at the height of its round body, before the board flattens it onto them).
+ */
+export function snakePath(s: SnakeData, raised = false): Vec3[] {
+  const head = cellCenter(s.head);
+  const tail = cellCenter(s.tail);
+  const dx = tail[0] - head[0];
+  const dy = tail[1] - head[1];
+  const d = Math.hypot(dx, dy);
+  const perp: V2 = [-dy / d, dx / d];
+  const waves = Math.max(2, Math.round(d / 0.15));
+  const amp = Math.min(0.042, d * 0.14);
+  return Array.from({ length: SNAKE_POINTS }, (_, i) => {
+    const t = i / (SNAKE_POINTS - 1);
+    const [x, y] = along(head, tail, t);
+    const w = amp * Math.sin(Math.PI * waves * t) * (1 - 0.6 * t);
+    return [x + perp[0] * w, y + perp[1] * w, raised ? snakeRadius(t) * 0.8 : TILE_TOP] as Vec3;
+  });
+}
+
+/** A snake's parts, heights measured from the cells' top (the board flattens them onto it). */
+function snakeParts(s: SnakeData): GeometryPart[] {
+  const path = snakePath(s, true);
+  const base = rgb(s.color);
+  const accent = rgb(s.accent);
+  const belly = rgb(s.belly);
+  const length = Math.hypot(path[0]![0] - path[SNAKE_POINTS - 1]![0], path[0]![1] - path[SNAKE_POINTS - 1]![1]);
+  const bands = Math.max(6, Math.round(length * 55));
+  const body = tube(path, {
+    radius: snakeRadius,
+    sides: 12,
+    smoothness: 4,
+    color: ({ v, normal: n, position: p }) => {
+      const band = 0.5 + 0.5 * Math.cos(Math.PI * 2 * bands * v);
+      let c = mix(base, accent, smooth(0.62, 0.86, band));
+      if (n[2] > 0.55 && band < 0.22) c = mix(c, belly, 0.55); // pale saddles along the back
+      if (n[2] < -0.2) c = belly;
+      return shade(c, 0.9 + 0.2 * noise(p[0] * 160, p[1] * 160));
+    }
+  });
+
+  // The head: a flattened wedge past the neck, looking away from the body
+  const [hx, hy] = cellCenter(s.head);
+  const neck = path[2]!;
+  const hd: V2 = [hx - neck[0], hy - neck[1]];
+  const hl = Math.hypot(hd[0], hd[1]) || 1;
+  hd[0] /= hl;
+  hd[1] /= hl;
+  const side: V2 = [-hd[1], hd[0]];
+  const angle = Math.atan2(hd[1], hd[0]);
+  const yaw = quat.z(angle);
+  const at = (forward: number, across: number, z: number): Vec3 => [
+    hx + hd[0] * forward + side[0] * across,
+    hy + hd[1] * forward + side[1] * across,
+    z
+  ];
+  const headColor = mix(base, accent, 0.25);
+  const parts: GeometryPart[] = [
+    { geometry: body },
+    { geometry: sphere(), position: at(0.006, 0, 0.011), scale: [0.05, 0.038, 0.022], rotation: yaw, color: [...headColor, 1] },
+    { geometry: sphere(), position: at(0.022, 0, 0.009), scale: [0.03, 0.027, 0.017], rotation: yaw, color: [...headColor, 1] }
+  ];
+  for (const k of [1, -1]) {
+    parts.push(
+      { geometry: sphere(), position: at(0.008, 0.012 * k, 0.019), scale: 0.012, color: [1, 1, 0.92, 1] },
+      { geometry: sphere(), position: at(0.01, 0.0125 * k, 0.0245), scale: [0.004, 0.008, 0.004], rotation: yaw, color: [0.05, 0.05, 0.05, 1] },
+      { geometry: sphere(), position: at(0.012, 0.011 * k, 0.026), scale: 0.0022, color: [1, 1, 1, 1] },
+      { geometry: sphere(), position: at(0.033, 0.0055 * k, 0.016), scale: 0.0032, color: [0.08, 0.06, 0.05, 1] }
+    );
+  }
+  // A forked tongue flicking out
+  const red: RGB = [0.85, 0.08, 0.12];
+  parts.push({ geometry: tube([at(0.034, 0, 0.007), at(0.05, 0, 0.007)], { radius: 0.0017, sides: 6, color: red }) });
+  for (const k of [1, -1])
+    parts.push({ geometry: tube([at(0.049, 0, 0.007), at(0.058, 0.0055 * k, 0.007)], { radius: 0.0014, sides: 6, color: red }) });
+  return parts;
+}
+
+// ── Ladders ───────────────────────────────────────────────────────────
+
+const RAIL_GAP = 0.019; // from the ladder's middle to a rail
+const RAIL_Z = 0.005; // above the cells' top, before the board flattens the ladder onto it
+
+/** A ladder's parts, heights measured from the cells' top (the board flattens them onto it). */
+function ladderParts(l: LadderData): GeometryPart[] {
+  const a = cellCenter(l.bottom);
+  const b = cellCenter(l.top);
+  const d = Math.hypot(b[0] - a[0], b[1] - a[1]);
+  const u: V2 = [(b[0] - a[0]) / d, (b[1] - a[1]) / d];
+  const p: V2 = [-u[1], u[0]];
+  const wood = rgb(l.color);
+  const light = rgb(l.highlight);
+  const grain = ({ v, normal: n }: { v: number; normal: Vec3 }): Color => {
+    const g = 0.5 + 0.5 * Math.sin(v * d * 260 + noise(v * d * 40, 3) * 5);
+    return shade(mix(wood, light, g * 0.45 + Math.max(0, n[2]) * 0.3), 1);
+  };
+  const ext = 0.014;
+  const parts: GeometryPart[] = [1, -1].map((k) => ({
+    geometry: tube(
+      [
+        [a[0] - u[0] * ext + p[0] * RAIL_GAP * k, a[1] - u[1] * ext + p[1] * RAIL_GAP * k, RAIL_Z],
+        [b[0] + u[0] * ext + p[0] * RAIL_GAP * k, b[1] + u[1] * ext + p[1] * RAIL_GAP * k, RAIL_Z]
+      ],
+      { radius: 0.0045, sides: 8, smoothness: Math.max(8, Math.round(d * 90)), color: grain }
+    )
+  }));
+  const rungs = Math.max(3, Math.floor(d / 0.045));
+  for (let r = 1; r <= rungs; r++) {
+    const [x, y] = along(a, b, r / (rungs + 1));
+    parts.push({
+      geometry: tube(
+        [
+          [x - p[0] * RAIL_GAP, y - p[1] * RAIL_GAP, RAIL_Z + 0.0008],
+          [x + p[0] * RAIL_GAP, y + p[1] * RAIL_GAP, RAIL_Z + 0.0008]
+        ],
+        { radius: 0.0032, sides: 8, color: mix(wood, light, 0.6) }
+      )
+    });
+  }
+  return parts;
+}
+
+/** The ladder's line, from its foot to its top, on the cells where a pawn climbs it. */
+export function ladderPath(l: LadderData): Vec3[] {
+  const [ax, ay] = cellCenter(l.bottom);
+  const [bx, by] = cellCenter(l.top);
+  return [
+    [ax, ay, TILE_TOP],
+    [bx, by, TILE_TOP]
+  ];
+}
+
+// ── The board ─────────────────────────────────────────────────────────
+
+const CELL = 1 / BOARD_SIZE;
+
+function cellColor(cell: number): RGB {
+  const i = cell - 1;
+  let c = rgb(CELL_PALETTE[(Math.floor(i / BOARD_SIZE) + (i % BOARD_SIZE)) % CELL_PALETTE.length]!);
+  if (cell === 1) c = rgb(START_CELL);
+  else if (cell === WINNING_POSITION) c = rgb(FINISH_CELL);
+  return c;
+}
+
+/** How much of their height the snakes and ladders keep: pressed flat onto the cells, like a printed board. */
+const FLAT = 0.05;
+/** How thin the flat layers are (cells, star, start pad). */
+const SKIN = 0.0004;
+/**
+ * The flat layers' heights above the cells' top, far enough apart that the depth test always knows
+ * which is in front (closer, the numbers and the snakes flicker into each other where they overlap),
+ * yet well under a pixel on screen: numbers, then the snakes and ladders over them, then pawn shadows.
+ */
+const DIGITS_Z = TILE_TOP + 0.002;
+const ART_Z = TILE_TOP + 0.004;
+export const SHADOW_Z = TILE_TOP + 0.008;
+/** Pawns stand on top of the flat layers (their shadows included), not sunk into them. */
+const PAWN_LIFT = SHADOW_Z + 0.001 - TILE_TOP;
+const pawnAt = (l: Layout, p: Vec3) => toWorld(l, p[0], p[1], p[2] + PAWN_LIFT);
+
+/**
+ * The board, all flat (only the pawns and the die stand up in 3D): a slim frame round the grout, the
+ * hundred cells, the snakes and ladders pressed onto them, the star on the last cell and the start pad.
+ */
+const boardMesh = () =>
+  cached('snl-board', () => {
+    const outer = 1 + RIM * 2;
+    const frame = rgb('#5C4033');
+    const flat = (z: number, scale: Vec3) => ({ position: [0, 0, z] as Vec3, scale });
+    const parts: GeometryPart[] = [
+      // The frame (the board's edge) and the grout showing between the cells, flush under them
+      { geometry: cube(), ...flat(TILE_TOP - 0.006, [outer, outer, SKIN]), color: [...frame, 1] },
+      { geometry: cube(), ...flat(TILE_TOP - 0.003, [1, 1, SKIN]), color: [...rgb('#CBB894'), 1] }
+    ];
+    for (let cell = 1; cell <= WINNING_POSITION; cell++) {
+      const [x, y] = cellCenter(cell);
+      parts.push({
+        geometry: cube(),
+        position: [x, y, TILE_TOP - SKIN / 2],
+        scale: [CELL - 0.005, CELL - 0.005, SKIN],
+        color: [...cellColor(cell), 1]
+      });
+    }
+    // A gold star on the last cell
+    const [fx, fy] = cellCenter(WINNING_POSITION);
+    parts.push({
+      geometry: extrude(new Path().addStar(0, 0, 0.5, 0.22), { depth: 0.12 }),
+      position: [fx, fy - 0.012, DIGITS_Z],
+      scale: [0.042, 0.042, 0.004],
+      color: [...rgb('#FFC107'), 1]
+    });
+    // The start pad: a flat wooden disc for the pawns before their first move
+    parts.push({ geometry: extrude(new Path().addCircle(0, 0, 0.08), { depth: SKIN, color: rgb('#A1887F') }), position: [START_X, DIE_Y, START_Z] });
+    // Snakes and ladders, pressed onto the cells
+    const art = merge([...LADDERS.flatMap(ladderParts), ...SNAKES.flatMap(snakeParts)]);
+    parts.push({ geometry: art, position: [0, 0, ART_Z], scale: [1, 1, FLAT] });
+    // Matte, like printed card: no glossy highlight on the board (the pawns and die keep theirs)
+    return createShape(merge(parts), { center: false, shine: 0 });
+  });
+
+// ── Cell numbers: the shared 3D glyphs ────────────────────────────────
+
+const DIGIT_SCALE = 0.027; // a digit's height on the board
+
+/** Each cell's number near its top edge, as children of the board. */
+function spawnNumbers(world: World, board: Entity) {
+  const dark = toColor(NUMBER_COLOR);
+  const gold = toColor(STAR_NUMBER_COLOR);
+  for (let cell = 1; cell <= WINNING_POSITION; cell++) {
+    const [x, y] = cellCenter(cell);
+    const text = String(cell);
+    const width = text.length * GLYPH_ADVANCE - (GLYPH_ADVANCE - GLYPH_WIDTH);
+    for (let i = 0; i < text.length; i++) {
+      world.spawn({
+        mesh: flatGlyphMesh(text[i]!),
+        parent: board,
+        position: [x + (-width / 2 + GLYPH_WIDTH / 2 + i * GLYPH_ADVANCE) * DIGIT_SCALE, y + CELL * 0.24, DIGITS_Z],
+        scale: DIGIT_SCALE,
+        color: cell === 1 || cell === WINNING_POSITION ? gold : dark,
+        pickable: false
+      });
+    }
+  }
+}
+
+// ── Pawns, the die, shadows ───────────────────────────────────────────
+
+/** A glossy pawn, one unit tall, standing on the origin. */
+const pawnMesh = () =>
+  cached('snl-pawn', () =>
+    createShape(
+      merge([
+        {
+          geometry: lathe(
+            [
+              [0.001, 0],
+              [0.42, 0],
+              [0.44, 0.04],
+              [0.42, 0.1],
+              [0.31, 0.14],
+              [0.25, 0.2],
+              [0.19, 0.42],
+              [0.15, 0.58],
+              [0.27, 0.61],
+              [0.27, 0.66],
+              [0.14, 0.69]
+            ],
+            { segments: 32 }
+          )
+        },
+        { geometry: sphere(), position: [0, 0.84, 0], scale: 0.4 }
+      ]),
+      { center: false, shine: 0.65 }
+    )
+  );
+
+/** 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('snl-disc', () => createShape(extrude(new Path().addCircle(0, 0, 0.5), { depth: 0 })));
+const ringMesh = () =>
+  cached('snl-ring', () => createShape(extrude(new Path().addCircle(0, 0, 0.5).addCircle(0, 0, 0.42), { depth: 0, fillRule: 'evenodd' })));
+
+// ── Spawning ──────────────────────────────────────────────────────────
+
+const SHADOW: Color = [0, 0, 0, 0.22];
+const BACKDROP_DEPTH = 25; // below the board, in world units
+
+export type Scene = {
+  backdrop: Entity;
+  board: Entity;
+  tokens: [Entity, Entity];
+  shadows: [Entity, Entity];
+  die: Entity;
+  dieShadow: Entity;
+  ring: Entity;
+};
+
+/** Board units to world units (view points). */
+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 });
+
+/** Points the camera at the board so it lands where the layout puts it. */
+export const aimCamera = (camera: Camera, l: Layout) => aimTilted(camera, tiltView(l));
+
+export function buildScene(world: World, l: Layout, theme: GameTheme): 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 });
+  spawnNumbers(world, board);
+  const token = (color: string) =>
+    world.spawn({ mesh: pawnMesh(), rotation: STAND_UP, scale: TOKEN_HEIGHT * l.size, color: toColor(color), pickable: false });
+  const shadow = () => world.spawn({ mesh: discMesh(), scale: 0.052 * 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, pickable: false });
+  return { backdrop, board, tokens: [token(PLAYER_COLOR), token(AI_COLOR)], shadows: [shadow(), shadow()], die, dieShadow, ring };
+}
+
+export function removeScene(world: World, s: Scene) {
+  for (const e of [s.backdrop, s.board, ...s.tokens, ...s.shadows, s.die, s.dieShadow, s.ring]) world.despawn(e);
+}
+
+export function setSceneTheme(world: World, s: Scene, theme: GameTheme) {
+  setBackdropTheme(world, s.backdrop, theme);
+}
+
+// ── Motion ────────────────────────────────────────────────────────────
+
+export const dieRest = (l: Layout): Vec3 => toWorld(l, 0, DIE_Y, DIE_SIZE / 2);
+
+/** 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
+  });
+}
+
+/** The gold ring under the die pulses while it's the player's roll. */
+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 });
+}
+
+/** A pawn's place on a board point (x, y) at height z, and its shadow's under it. */
+export function placeToken(world: World, l: Layout, s: Scene, who: number, at: Vec3) {
+  world.stopAnimation(s.tokens[who]!);
+  world.stopAnimation(s.shadows[who]!);
+  world.set(s.tokens[who]!, { position: pawnAt(l, at) });
+  world.set(s.shadows[who]!, { position: toWorld(l, at[0] + 0.006, at[1] - 0.006, SHADOW_Z) });
+}
+
+/**
+ * Moves a pawn through board points (x, y, z) in `time` seconds, along a smooth curve; with `hop`, it
+ * arcs up between them. Its shadow follows along the board.
+ */
+export function moveToken(world: World, l: Layout, s: Scene, who: number, points: Vec3[], time: number, hop = 0) {
+  const token = s.tokens[who]!;
+  const shadow = s.shadows[who]!;
+  const end = points[points.length - 1]!;
+  const keys = hop
+    ? [
+        { position: pawnAt(l, [(points[0]![0] + end[0]) / 2, (points[0]![1] + end[1]) / 2, Math.max(points[0]![2], end[2]) + hop]), at: 0.5 },
+        { position: pawnAt(l, end), at: 1 }
+      ]
+    : points.slice(1).map((p, i) => ({ position: pawnAt(l, p), at: (i + 1) / (points.length - 1) }));
+  world.stopAnimation(token);
+  world.stopAnimation(shadow);
+  world.animate(token, keys, { duration: time, path: 'smooth', easing: hop ? 'linear' : 'easeInOut' });
+  world.animate(shadow, { position: toWorld(l, end[0] + 0.006, end[1] - 0.006, SHADOW_Z) }, { duration: time, easing: hop ? 'linear' : 'easeInOut' });
+}
+
+/** The pawn whose turn it is bobs gently. */
+export function bobToken(world: World, l: Layout, s: Scene, who: number | null) {
+  s.tokens.forEach((t, i) => world.set(t, { bob: i === who ? { amplitude: [0, 0, 0.008 * l.size], speed: 6 } : null }));
+}
+
+/** A snake's bite: the pawn shakes and the board jolts. */
+export function snakeBite(world: World, l: Layout, s: Scene, camera: Camera, who: number) {
+  world.animate(s.tokens[who]!, { shake: 0.01 * l.size }, { duration: 0.3 });
+  camera.shake = 0.008 * l.size;
+}
+
+/** Sparkles at a board point (a ladder's top). */
+export function sparkle(world: World, l: Layout, at: Vec3) {
+  effects.sparkle(world, {
+    position: toWorld(l, at[0], at[1], at[2] + 0.03),
+    count: 16,
+    size: 0.009 * l.size,
+    speed: 0.25 * l.size,
+    lifetime: 0.6,
+    colors: [toColor('#FFD54F'), toColor('#FFF59D'), toColor('#FFFFFF')]
+  });
+}
+
+/** Confetti over the winning pawn. */
+export function confetti(world: World, l: Layout, at: Vec3) {
+  effects.confetti(world, {
+    position: toWorld(l, at[0], at[1], at[2] + 0.06),
+    count: 48,
+    size: 0.012 * l.size,
+    speed: 0.7 * l.size,
+    lifetime: 1.3,
+    gravity: -1.2 * l.size,
+    colors: ['#FF5252', '#FFD740', '#69F0AE', '#448AFF'].map((c) => toColor(c))
+  });
+}
+
+/** The line a pawn slides down a snake (head to tail) or climbs a ladder (foot to top), in board points. */
+const slidePaths = new Map<number, Vec3[] | null>();
+export function slidePath(from: number): Vec3[] | null {
+  if (slidePaths.has(from)) return slidePaths.get(from)!;
+  const snake = SNAKE_AT.get(from);
+  const ladder = LADDER_AT.get(from);
+  const path = snake ? snakePath(snake).filter((_, i) => i % 3 === 0 || i === SNAKE_POINTS - 1) : ladder ? ladderPath(ladder) : null;
+  if (snake || ladder) slidePaths.set(from, path);
+  return path;
+}

package/src/games/space-fighter/SpaceFighter.tsx

@@ -0,0 +1,74 @@
+// Space Fighter's screen, on the Nayan engine: deep space, the ship and the asteroid belts are one 3D
+// scene (a perspective camera looking out into space), under Playtura's scoreboard, controls and
+// modals. The rules are in SpaceFighterGame.ts, what it draws in SpaceFighterScene.ts.
+//
+// One world serves the whole visit: Start, Stop and Play Again reset it in place, so the GPU view is
+// never rebuilt. Rocks tumble, stars drift and the exhausts flicker in the engine's Rust core; JS runs
+// the field (a handful of boxes) and steps 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 { livesColumn, scoreColumn, timerColumn } from '../shared/EngineHud';
+import { toRgb } from '../shared/EngineUtils';
+import { useEngineGame } from '../shared/useEngineGame';
+import { useLiveState } from '../shared/useLiveState';
+import { BACKGROUND, DAY_BACKGROUND, getLayout, LIGHT, LIVES, TIME_LIMIT } from './SpaceFighterConstants';
+import { createGame, dispose, drag, type GameEvent, reset, setLayout, setTheme, start, tick } from './SpaceFighterGame';
+
+const SOUNDS = GAME_SOUNDS.SPACE_FIGHTER;
+const NIGHT_RGB = toRgb(BACKGROUND);
+const DAY_RGB = toRgb(DAY_BACKGROUND);
+
+/** Each event's sound and haptic, as the original version played them. */
+const FEEDBACK: Record<GameEvent, { sound: (typeof SOUNDS)[keyof typeof SOUNDS]; haptic: HapticType }> = {
+  grab: { sound: SOUNDS.GRAB, haptic: HapticType.MEDIUM },
+  release: { sound: SOUNDS.RELEASE, haptic: HapticType.LIGHT },
+  dodge: { sound: SOUNDS.DODGE, haptic: HapticType.LIGHT },
+  hit: { sound: SOUNDS.COLLISION, haptic: HapticType.HEAVY }
+};
+
+export const SpaceFighter = engineGame(GAME_IDS.SPACE_FIGHTER, (props) => {
+  const [score, setScore] = useLiveState(0);
+  const [lives, setLives] = useLiveState(LIVES);
+  const [timeLeft, setTimeLeft] = useLiveState(TIME_LIMIT);
+
+  // A win when the time runs out, a loss with no lives left
+  const { theme, status, screen, gameOver } = useEngineGame(props, {
+    gameId: GAME_IDS.SPACE_FIGHTER,
+    create: createGame,
+    setTheme,
+    start,
+    reset,
+    dispose,
+    tick,
+    resize: (g, width, height, offset) => setLayout(g, getLayout(width, height, offset)),
+    drag,
+    sounds: SOUNDS,
+    onStart: (fx) => fx(SOUNDS.START, HapticType.SUCCESS),
+    onOver: (fx, s) => fx(s === 'win' ? SOUNDS.WIN : SOUNDS.GAME_OVER, s === 'win' ? HapticType.SUCCESS : HapticType.ERROR),
+    wire: (g, fx) => {
+      g.onScore = setScore;
+      g.onLives = setLives;
+      g.onTime = setTimeLeft;
+      g.onEvent = (event) => fx(FEEDBACK[event].sound, FEEDBACK[event].haptic);
+    }
+  });
+
+  return (
+    <EngineGameScreen
+      {...screen}
+      light={LIGHT}
+      background={theme.mode === 'dark' ? NIGHT_RGB : DAY_RGB}
+      columns={[scoreColumn(score), livesColumn(lives, LIVES), timerColumn(timeLeft, theme, 0)]}
+      subtext="Navigate through space!"
+      gameOver={gameOver({
+        title: 'GAME OVER',
+        message: status === 'win' ? 'You survived the asteroid field!' : 'Your ship was destroyed!',
+        scoreLabel: 'Final Score',
+        score,
+        buttonText: 'Fly Again!'
+      })}
+    />
+  );
+});

package/src/games/space-fighter/SpaceFighterConstants.ts

@@ -0,0 +1,86 @@
+import type { Light } from '@nayan-ui/engine';
+// Space Fighter's rules, physics, timings and layout. Rules, scoring and sizing match the original version
+// (games/space-fighter): everything is in screen points, scaled from a 390 x 844 phone, so the field
+// takes the same time to cross and the gaps are as wide on every device.
+import { getScoreBoardTop } from '../shared/EngineHud';
+
+// ── Rules ─────────────────────────────────────────────────────────────
+
+export const TIME_LIMIT = 120; // seconds; surviving them wins
+export const LIVES = 3;
+export const DODGE_POINTS = 500; // a pair of asteroid belts passed
+export const HIT_COOLDOWN = 2; // seconds of blinking safety after a hit
+
+// ── Sizes and speeds (points, at the 390 x 844 base) ──────────────────
+
+const BASE_WIDTH = 390;
+const BASE_HEIGHT = 844;
+const TABLET_WIDTH = 640;
+const SHIP_SIZE = { phone: 28, tablet: 22 }; // the ship's hitbox, a square
+const BELT_HEIGHT = { phone: 80, tablet: 60 }; // each belt's depth down the screen
+const GAP = 120; // the opening between a pair's belts
+const SPAWN_INTERVAL = { phone: 1.5, tablet: 1.8 }; // seconds, at the base height
+const FALL_SPEED = 3.5; // points per 16 ms frame, at the base height
+const GAP_VARIANCE = 0.15; // of the width: how far the opening wanders from the centre
+const MIN_EDGE = 0.08; // of the width: the narrowest a belt gets
+const SPAWN_ABOVE = 0.3; // of the height: where a pair starts, above the top edge
+
+export const BASE_FRAME = 0.016; // the fall speed is per this much time
+export const MAX_FRAME = 0.064; // a long frame moves the field at most this much
+
+// ── The scene ─────────────────────────────────────────────────────────
+
+/** How far ahead of the camera the game plays, in world units: screen points map onto this plane. */
+export const PLAY_DEPTH = 12;
+export const FOV = 0.9;
+export const BACKGROUND = '#050311'; // night: deep black space
+export const DAY_BACKGROUND = '#A8DCF7'; // day (light mode): a bright daytime sky
+/** A cool starlight from the upper left, a touch of violet in the shadows. */
+export const LIGHT: Light = { direction: [-0.45, 0.6, 0.65], ambient: 0.38, shadows: false, color: [1.05, 1.02, 1.1] };
+
+// ── Layout ────────────────────────────────────────────────────────────
+
+export type Layout = {
+  width: number;
+  height: number;
+  offset: number;
+  /** World units per screen point on the play plane. */
+  k: number;
+  shipSize: number;
+  shipY: number;
+  beltHeight: number;
+  gap: number;
+  spawnInterval: number;
+  /** Points per second. */
+  fallSpeed: number;
+  spawnY: number;
+  /** Where the scoreboard ends, for the start hint. */
+  scoreboardBottom: number;
+};
+
+export function getLayout(width: number, height: number, offset: number): Layout {
+  const tablet = width > TABLET_WIDTH;
+  const sx = width / BASE_WIDTH;
+  const sy = height / BASE_HEIGHT;
+  return {
+    width,
+    height,
+    offset,
+    k: (2 * PLAY_DEPTH * Math.tan(FOV / 2)) / height,
+    shipSize: Math.round((tablet ? SHIP_SIZE.tablet : SHIP_SIZE.phone) * sx),
+    shipY: height * (offset > 0 ? 0.77 : 0.68),
+    beltHeight: Math.round((tablet ? BELT_HEIGHT.tablet : BELT_HEIGHT.phone) * sy),
+    gap: Math.round(GAP * sx),
+    spawnInterval: (tablet ? SPAWN_INTERVAL.tablet : SPAWN_INTERVAL.phone) / sy,
+    fallSpeed: (FALL_SPEED * sy) / BASE_FRAME,
+    spawnY: -Math.round(height * SPAWN_ABOVE),
+    scoreboardBottom: getScoreBoardTop(offset) + 82
+  };
+}
+
+/** Where a pair's opening goes: near the centre, wandering a little, never squeezing a belt off the edge. */
+export function gapLeft(l: Layout, random = Math.random) {
+  const centre = l.width / 2 + (random() - 0.5) * 2 * l.width * GAP_VARIANCE;
+  const minEdge = Math.round(l.width * MIN_EDGE);
+  return Math.max(minEdge, Math.min(centre - l.gap / 2, l.width - l.gap - minEdge));
+}