@nayan-ui/games 1.18.0 → 1.20.0

package/src/games/whack-a-mole/WhackAMoleConstants.ts

@@ -0,0 +1,94 @@
+// Whack a Mole's rules, timings and layout. Rules, timings and scoring match the original version
+// (games/whack-a-mole), so scores carry over.
+import { getScoreBoardTop } from '../shared/EngineHud';
+import { makeView, type MeadowOptions, rayThrough, type View3D } from '../shared/EngineMeadow';
+import { gameWidthFor } from '../shared/EngineUtils';
+
+// ── Rules ─────────────────────────────────────────────────────────────
+
+export const GRID = 3; // holes a side
+export const HOLES = GRID * GRID;
+export const TIME_LIMIT = 120; // seconds; surviving them is the end of every game (always a win)
+export const POINTS_PER_MOLE = 500;
+export const TIME_WARNING = 10; // seconds left when the warning sounds
+
+// ── Timings (seconds, as the original version) ────────────────────────────
+
+export const FIRST_SPAWN = 1;
+export const SPAWN_MAX = 1.5;
+export const SPAWN_MIN = 1.05; // 30% faster than the longest gap
+export const MOLE_UP_TIME = 2; // a mole stays up this long, then ducks back (a miss)
+
+// ── The scene (metres) ────────────────────────────────────────────────
+
+export const EYE_HEIGHT = 1.6;
+/** Rows are further apart in depth than columns across, so the perspective doesn't squash them together. */
+export const ROW_SPACING = 1.6; // x the column spacing
+export const HOLE_RADIUS = 0.36; // x the column spacing
+export const MOLE_HEIGHT = 0.62; // x the column spacing: how far a mole rises out of its hole
+
+// ── Layout ────────────────────────────────────────────────────────────
+
+const SCOREBOARD_HEIGHT = 82;
+const CONTROLS_HEIGHT = 175; // room under the near row: the holes sit well clear of the controls
+const SKY_BELOW_SCOREBOARD = 45; // points of sky and treeline showing under the scoreboard
+const SIDE_MARGIN = 14;
+const MAX_FAR_Z = 5.3; // metres: the far row's rims stay in front of the meadow's rocks and bushes (6 m on)
+
+export type Layout = {
+  width: number;
+  height: number;
+  view: View3D;
+  /** Metres between neighbouring holes across; rows are `ROW_SPACING` times that apart. */
+  spacing: number;
+  /** Metres from the eye to the near row. */
+  nearZ: number;
+  /** Each hole's centre on the ground, row 0 (furthest) first, left to right. */
+  holes: [number, number, number][];
+};
+
+/**
+ * The camera at eye height looking across a lawn: the horizon a little under the scoreboard (sky,
+ * hills and the treeline above it), the near row's rims just above the controls, the grid as wide as
+ * fits the screen.
+ */
+export function getLayout(width: number, height: number, offset: number): Layout {
+  const horizonY = getScoreBoardTop(offset) + SCOREBOARD_HEIGHT + SKY_BELOW_SCOREBOARD;
+  const view = makeView(width, height, { eyeHeight: EYE_HEIGHT, horizon: horizonY / height, playDepth: 3 });
+  // Where the bottom of the near row's rims meets the ground
+  const ray = rayThrough(view, width / 2, height - CONTROLS_HEIGHT);
+  const bottomZ = -(EYE_HEIGHT / -ray[1]) * ray[2]; // metres ahead
+  // The near row spans at most the game width (the view less 30, at most 500)
+  const edge = Math.min(width - SIDE_MARGIN, width / 2 + gameWidthFor(width) / 2);
+  // The widest spacing that keeps the near row's outer rims on screen
+  let lo = 0.05;
+  let hi = 3;
+  for (let i = 0; i < 40; i++) {
+    const s = (lo + hi) / 2;
+    const [x] = toScreen(view, [s * (1 + HOLE_RADIUS), 0, -(bottomZ + s * HOLE_RADIUS)]);
+    if (x > edge) hi = s;
+    else lo = s;
+  }
+  // ...and in front of the meadow's rocks and bushes
+  const spacing = Math.min(lo, (MAX_FAR_Z - bottomZ) / (HOLE_RADIUS * 2 + (GRID - 1) * ROW_SPACING));
+  const nearZ = bottomZ + spacing * HOLE_RADIUS;
+  const holes: [number, number, number][] = [];
+  for (let row = 0; row < GRID; row++)
+    for (let col = 0; col < GRID; col++) holes.push([(col - 1) * spacing, 0, -(nearZ + (GRID - 1 - row) * spacing * ROW_SPACING)]);
+  return { width, height, view, spacing, nearZ, holes };
+}
+
+/** Where a world point appears in the view (screen points). */
+export function toScreen(v: View3D, p: readonly [number, number, number]): [number, number] {
+  const d = [p[0] - v.eye[0], p[1] - v.eye[1], p[2] - v.eye[2]] as const;
+  const depth = d[0] * v.forward[0] + d[1] * v.forward[1] + d[2] * v.forward[2];
+  const up = d[0] * v.up[0] + d[1] * v.up[1] + d[2] * v.up[2];
+  const k = v.height / 2 / (v.tanHalf * Math.max(depth, 1e-3));
+  return [v.width / 2 + d[0] * k, v.height / 2 - up * k];
+}
+
+/** The meadow around the lawn: the sun and clouds in the strip of sky above the horizon. */
+export function meadowFor(l: Layout): MeadowOptions {
+  const horizon = l.view.horizon;
+  return { sun: [0.82, horizon * 0.55], clouds: [0.02, horizon * 0.8], hotAirBalloons: 1 };
+}

package/src/games/whack-a-mole/WhackAMoleGame.ts

@@ -0,0 +1,233 @@
+// Whack a Mole's rules, with no React: build a game with `createGame`, give it a layout, `start` it and
+// `tick` it every frame. Moles pop up in random free holes (the first after a second, then every
+// 1.05 to 1.5 seconds) and duck back after two; tap one to whack it for 500 points. When the two
+// minutes run out the game ends, always a win, with whatever was scored.
+//
+// Every timer (the clock, spawns, each mole's two seconds) runs on the game's own clock, advanced by
+// `tick`: a stop or reset drops what's pending, so nothing lands in the next game, and it all pauses
+// with the view.
+import { type Camera, World } from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import { cameraFor } from '../shared/EngineMeadow';
+import {
+  FIRST_SPAWN,
+  HOLES,
+  type Layout,
+  MOLE_UP_TIME,
+  POINTS_PER_MOLE,
+  SPAWN_MAX,
+  SPAWN_MIN,
+  TIME_LIMIT,
+  TIME_WARNING,
+  toScreen
+} from './WhackAMoleConstants';
+import { bonk, buildScene, duck, hideAll, hitEffect, missEffect, moleTop, popUp, removeScene, type Scene, thud } from './WhackAMoleScene';
+
+export type Phase = 'ready' | 'playing' | 'over';
+export type GameEvent = 'spawn' | 'hit' | 'miss' | 'empty' | 'warning';
+
+const WORLD_CAPACITY = 1000; // the meadow (~350), the lawn's props (~110), holes and moles, bursts
+const MAX_STEP = 0.1;
+
+export function createGame(theme: GameTheme) {
+  const world = new World(WORLD_CAPACITY);
+  // Placed for the view on the first layout; GameView reads this object every frame
+  const camera: Camera = { eye: [0, 1.6, 0], target: [0, 1, -3], fov: 0.9 };
+  const g = {
+    world,
+    camera,
+    theme,
+    layout: null as Layout | null,
+    hitLayout: null as Layout | null,
+    hitZones: [] as { rim: [number, number]; up: [number, number]; down: [number, number]; reach: number }[],
+    scene: null as Scene | null,
+    phase: 'ready' as Phase,
+    /** Score and the countdown live in the engine (Rust), advanced by world.update. */
+    get score() {
+      return world.scoreboard.score;
+    },
+    get timeLeft() {
+      return world.scoreboard.shownSeconds;
+    },
+    /** Which holes have a mole up, and when each one ducks back (game clock). */
+    up: new Array<boolean>(HOLES).fill(false),
+    hideAt: new Array<number>(HOLES).fill(0),
+    nextSpawn: 0,
+    /** Seconds on the game's clock, for spawns and each mole's time up. */
+    clock: 0,
+    // UI hooks, set by the screen.
+    onPhase: (_p: Phase) => {},
+    onScore: (_s: number) => {},
+    onTime: (_t: number) => {},
+    onEvent: (_e: GameEvent) => {}
+  };
+  world.scoreboard.reset(0, TIME_LIMIT);
+  world.scoreboard.handlers = {
+    onScore: (s) => g.onScore(s),
+    onSecond: (t) => {
+      g.onTime(t);
+      if (t === TIME_WARNING && g.phase === 'playing') g.onEvent('warning');
+    },
+    onTimeUp: () => g.phase === 'playing' && end(g)
+  };
+  return g;
+}
+export type Game = ReturnType<typeof createGame>;
+
+// ── Scene ─────────────────────────────────────────────────────────────
+
+/** Lays the world out for the view (first layout, header height, rotation): rebuilt from the game's state. */
+export function setLayout(g: Game, l: Layout) {
+  if (g.scene) removeScene(g.world, g.scene);
+  g.layout = l;
+  const cam = cameraFor(l.view);
+  g.camera.eye = cam.eye;
+  g.camera.target = cam.target;
+  g.camera.fov = cam.fov;
+  g.scene = buildScene(g.world, l, g.theme);
+  g.up.forEach((up, i) => up && g.scene && g.world.set(g.scene.moles[i]!, { position: [l.holes[i]![0], 0, l.holes[i]![2]] }));
+}
+
+/** A new theme: day or night (the screen swaps the light); the game carries on. */
+export function setTheme(g: Game, theme: GameTheme) {
+  if (theme === g.theme) return;
+  g.theme = theme;
+  if (g.layout && !g.world.isDisposed) setLayout(g, g.layout);
+}
+
+// ── Run ───────────────────────────────────────────────────────────────
+
+export function start(g: Game) {
+  if (g.phase !== 'ready') return;
+  g.phase = 'playing';
+  g.nextSpawn = g.clock + FIRST_SPAWN;
+  g.world.scoreboard.startCountdown(TIME_LIMIT);
+  g.onPhase('playing');
+}
+
+/** Back to a fresh, unstarted game (Stop, Play Again). The world, and the GPU view drawing it, are kept. */
+export function reset(g: Game) {
+  g.world.cancelTimers();
+  clearMoles(g);
+  g.world.scoreboard.reset(0, TIME_LIMIT);
+  g.phase = 'ready';
+  g.onScore(0);
+  g.onTime(TIME_LIMIT);
+  g.onPhase('ready');
+}
+
+export function dispose(g: Game) {
+  g.world.dispose();
+}
+
+function clearMoles(g: Game) {
+  g.up.fill(false);
+  if (g.layout && g.scene) hideAll(g.world, g.layout, g.scene);
+}
+
+export function tick(g: Game, dt: number) {
+  if (g.world.isDisposed) return;
+  g.clock += Math.min(dt, MAX_STEP);
+  if (g.phase === 'playing') {
+    // Moles that weren't hit in time duck back
+    for (let i = 0; g.phase === 'playing' && i < HOLES; i++) {
+      if (g.up[i] && g.clock >= g.hideAt[i]!) {
+        g.up[i] = false;
+        if (g.layout && g.scene) duck(g.world, g.layout, g.scene, i);
+        g.onEvent('miss');
+      }
+    }
+    if (g.phase === 'playing' && g.clock >= g.nextSpawn) {
+      spawn(g);
+      g.nextSpawn = g.clock + SPAWN_MIN + Math.random() * (SPAWN_MAX - SPAWN_MIN);
+    }
+  }
+  g.world.update(dt);
+}
+
+/** A mole up in a random free hole. */
+function spawn(g: Game) {
+  const free: number[] = [];
+  for (let i = 0; i < HOLES; i++) if (!g.up[i]) free.push(i);
+  if (!free.length) return;
+  const hole = free[Math.floor(Math.random() * free.length)]!;
+  g.up[hole] = true;
+  g.hideAt[hole] = g.clock + MOLE_UP_TIME;
+  if (g.layout && g.scene) popUp(g.world, g.layout, g.scene, hole);
+  g.onEvent('spawn');
+}
+
+function end(g: Game) {
+  g.world.cancelTimers();
+  g.world.scoreboard.stop();
+  clearMoles(g);
+  g.phase = 'over';
+  g.onPhase('over');
+}
+
+// ── Taps ──────────────────────────────────────────────────────────────
+
+/** Distance from point p to the segment a..b. */
+function toSegment(p: [number, number], a: [number, number], b: [number, number]) {
+  const dx = b[0] - a[0];
+  const dy = b[1] - a[1];
+  const t = dx || dy ? Math.max(0, Math.min(1, ((p[0] - a[0]) * dx + (p[1] - a[1]) * dy) / (dx * dx + dy * dy))) : 0;
+  return Math.hypot(p[0] - (a[0] + dx * t), p[1] - (a[1] + dy * t));
+}
+
+/**
+ * The hole a view point is over: its rim, or the mole standing in it. Each hole's zone reaches half way
+ * to its neighbours in its row (the far row's are smaller, as it looks), and the nearest one wins.
+ */
+export function holeAt(g: Game, x: number, y: number): number | null {
+  const l = g.layout;
+  if (!l) return null;
+  if (g.hitLayout !== l) {
+    const top = moleTop(l);
+    g.hitZones = l.holes.map((hole) => {
+      const rim = toScreen(l.view, hole);
+      return {
+        rim,
+        reach: Math.abs(toScreen(l.view, [hole[0] + l.spacing, 0, hole[2]])[0] - rim[0]) * 0.5,
+        up: toScreen(l.view, [hole[0], top, hole[2]]),
+        down: toScreen(l.view, [hole[0], l.spacing * 0.15, hole[2]])
+      };
+    });
+    g.hitLayout = l;
+  }
+  let best: number | null = null;
+  let bestScore = 1;
+  const point: [number, number] = [x, y];
+  g.hitZones.forEach(({ rim, up, down, reach }, i) => {
+    const head = g.up[i] ? up : down;
+    const score = toSegment(point, rim, head) / reach;
+    if (score < bestScore) {
+      best = i;
+      bestScore = score;
+    }
+  });
+  return best;
+}
+
+/** A tap: a hit lands on the hole under it at once, whacking the mole if one's up. */
+export function tap(g: Game, x: number, y: number) {
+  if (g.phase !== 'playing') return;
+  const hole = holeAt(g, x, y);
+  if (hole == null) return;
+  const { layout: l, scene: s } = g;
+  if (!g.up[hole]) {
+    g.onEvent('empty');
+    if (l) {
+      thud(g.world, l, hole);
+      missEffect(g.world, l, hole);
+    }
+    return;
+  }
+  g.up[hole] = false;
+  g.world.scoreboard.add(POINTS_PER_MOLE);
+  g.onEvent('hit');
+  if (l && s) {
+    bonk(g.world, l, s, hole);
+    hitEffect(g.world, l, hole);
+  }
+}

package/src/games/whack-a-mole/WhackAMoleScene.ts

@@ -0,0 +1,349 @@
+// Everything Whack a Mole draws, in the shared 3D meadow (shared/EngineMeadow): a lawn of nine dirt
+// mounds round dark holes, a mole in each that springs up and ducks back, and a flash of impact
+// streaks and dust wherever you tap. The world is y-up and in metres; the holes and moles are sized by the
+// layout's spacing. Each kind of thing is one shared mesh (one instanced draw): mesh ids are app-wide
+// and limited, so each is built once.
+import {
+  type Color,
+  effects,
+  type Entity,
+  type GeometryPart,
+  lathe,
+  merge,
+  type Model,
+  quat,
+  shapeGeometry,
+  tube,
+  type Vec3,
+  type World
+} from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import { flowerMesh, noise, random, rockMesh, sceneryTint, spawnWorld, tuftMesh } from '../shared/EngineMeadow';
+import { cacheGameAsset, createGameMesh as createShape } from '../shared/EngineMeshes';
+import { toColor } from '../shared/EngineUtils';
+import { HOLE_RADIUS, type Layout, meadowFor, MOLE_HEIGHT } from './WhackAMoleConstants';
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+const meshes = new Map<string, Model>();
+const cached = (key: string, build: () => Model) => {
+  let m = meshes.get(key);
+  if (!m) {
+    m = cacheGameAsset('whack-a-mole/WhackAMoleScene:' + 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 tinted = (c: Color, t: Color): Color => [c[0] * t[0], c[1] * t[1], c[2] * t[2], c[3] ?? 1];
+
+// ── Meshes (unit sizes; entities scale them by the layout's spacing) ──
+
+/** A hole: a dark throat in a raised ring of loose soil, `HOLE_RADIUS` across at the rim, on the ground. */
+const moundMesh = () =>
+  cached('wam-mound', () => {
+    const soil = rgb('#7A4E2D');
+    const dry = rgb('#A27449');
+    const deep = rgb('#140B05');
+    const r = HOLE_RADIUS;
+    return createShape(
+      lathe(
+        [
+          [r * 1.75, 0],
+          [r * 1.45, r * 0.12],
+          [r * 1.12, r * 0.3],
+          [r * 0.95, r * 0.32],
+          [r * 0.8, r * 0.16],
+          [r * 0.66, r * 0.03],
+          [0.001, r * 0.015]
+        ],
+        {
+          segments: 40,
+          displace: (u, v) => (v < 0.6 ? 0.012 * Math.sin(u * Math.PI * 2 * 9) * Math.sin(v * Math.PI) : 0),
+          color: ({ position: p }) => {
+            const radius = Math.hypot(p[0], p[2]) / r;
+            const lumps = 0.82 + 0.36 * noise(p[0] * 40 + 5, p[2] * 40);
+            const c = mix(shade(soil, 0.65), dry, smooth(0.9, 1.15, radius) * (1 - smooth(1.3, 1.75, radius) * 0.6));
+            return shade(mix(deep, c, smooth(0.62, 0.92, radius)), lumps);
+          }
+        }
+      ),
+      { center: false, shine: 0.05 }
+    );
+  });
+
+/** A mole, about one unit tall and standing on the origin, facing the camera (+z): furry, pink-nosed, blinking out. */
+const moleMesh = () =>
+  cached('wam-mole', () => {
+    const fur = rgb('#7B5134');
+    const furDark = rgb('#4E3220');
+    const muzzle = rgb('#E8B48A');
+    const pink = rgb('#FF6F91');
+    const paw = rgb('#F2A99B');
+    const body = lathe(
+      [
+        [0.33, -0.45],
+        [0.36, 0.05],
+        [0.35, 0.4],
+        [0.3, 0.66],
+        [0.2, 0.84],
+        [0.001, 0.93]
+      ],
+      {
+        segments: 32,
+        color: ({ position: p, normal: n }) => {
+          // A paler belly toward the front, fur streaks all over
+          const front = smooth(0.35, 0.85, n[2]) * (1 - smooth(0.35, 0.6, p[1]));
+          const c = mix(mix(furDark, fur, smooth(-0.3, 0.6, p[1])), muzzle, front * 0.65);
+          return shade(c, 0.85 + 0.3 * noise(p[0] * 30 + p[1] * 8, p[2] * 30 + p[1] * 70));
+        }
+      }
+    );
+    const pair = (part: GeometryPart): GeometryPart[] => [part, { ...part, position: [-part.position![0], part.position![1], part.position![2]] }];
+    const whiskers: GeometryPart[] = [];
+    for (const side of [1, -1])
+      for (const [dy, dz] of [
+        [0.02, 0.04],
+        [-0.02, 0.0],
+        [-0.06, -0.03]
+      ] as [number, number][])
+        whiskers.push({
+          geometry: tube(
+            [
+              [side * 0.1, 0.62 + dy, 0.36],
+              [side * 0.24, 0.63 + dy * 1.6, 0.34 + dz],
+              [side * 0.36, 0.62 + dy * 2.4, 0.3 + dz]
+            ],
+            { radius: 0.006, sides: 4, smoothness: 4, color: [0.15, 0.1, 0.08] }
+          )
+        });
+    return createShape(
+      merge([
+        { geometry: body },
+        // Snout, nose, teeth
+        { geometry: sphere(), position: [0, 0.6, 0.27], scale: [0.25, 0.19, 0.22], color: [...muzzle, 1] },
+        { geometry: sphere(), position: [0, 0.65, 0.38], scale: [0.11, 0.085, 0.09], color: [...pink, 1] },
+        { geometry: sphere(), position: [0.02, 0.675, 0.42], scale: 0.025, color: [1, 1, 1, 1] },
+        ...pair({ geometry: shapeGeometry('roundedBox'), position: [0.025, 0.52, 0.355], scale: [0.04, 0.06, 0.02], color: [1, 1, 0.96, 1] }),
+        // Glossy black eyes with a glint, little ears, rosy cheeks
+        ...pair({ geometry: sphere(), position: [0.11, 0.77, 0.25], scale: 0.075, color: [0.04, 0.03, 0.03, 1] }),
+        ...pair({ geometry: sphere(), position: [0.095, 0.79, 0.285], scale: 0.022, color: [1, 1, 1, 1] }),
+        ...pair({ geometry: sphere(), position: [0.23, 0.84, 0.0], scale: [0.11, 0.09, 0.05], color: [...furDark, 1] }),
+        ...pair({ geometry: sphere(), position: [0.2, 0.6, 0.2], scale: [0.11, 0.08, 0.06], color: [...mix(muzzle, pink, 0.35), 1] }),
+        // Paws gripping the rim
+        ...pair({ geometry: sphere(), position: [0.2, 0.2, 0.3], scale: [0.17, 0.09, 0.15], color: [...paw, 1] }),
+        ...whiskers
+      ]),
+      { center: false, shine: 0.22 }
+    );
+  });
+
+// ── Spawning ──────────────────────────────────────────────────────────
+
+export type Scene = {
+  scenery: Entity[];
+  mounds: Entity[];
+  moles: Entity[];
+};
+
+const moleScale = (l: Layout) => (MOLE_HEIGHT * l.spacing) / 0.93;
+/** A mole's place: up out of its hole, or hidden below the ground. */
+export const molePosition = (l: Layout, hole: number, up: boolean): Vec3 => {
+  const [x, , z] = l.holes[hole]!;
+  return [x, up ? 0 : -moleScale(l) * 1.05, z];
+};
+/** The top of a mole that's up, for hit-testing and the hit's burst. */
+export const moleTop = (l: Layout) => moleScale(l) * 0.9;
+
+export function buildScene(world: World, l: Layout, theme: GameTheme): Scene {
+  const tint = sceneryTint(theme);
+  const scenery = spawnWorld(world, l.view, theme, { ...meadowFor(l), foreground: false });
+  // The lawn's own tufts, flowers and pebbles, kept off the holes
+  const rand = random(11);
+  const s = l.spacing;
+  const near = -l.holes[l.holes.length - 1]![2];
+  const far = -l.holes[0]![2];
+  const clear = (x: number, z: number) => l.holes.every(([hx, , hz]) => Math.hypot(x - hx, z - hz) > s * HOLE_RADIUS * 2);
+  const place = (mesh: Model, size: number | Vec3, color: Color, count: number, from: number, to: number) => {
+    for (let i = 0, tries = 0; i < count && tries < count * 8; tries++) {
+      const z = -(from + rand() * (to - from));
+      const x = (rand() * 2 - 1) * (-z * 0.62 + 0.4);
+      if (!clear(x, z)) continue;
+      scenery.push(
+        world.spawn({ mesh, position: [x, 0, z], scale: size, rotation: quat.y(rand() * 6.3), color: tinted(color, tint), pickable: false })
+      );
+      i++;
+    }
+  };
+  place(tuftMesh(), 0.9, [1, 1, 1, 1], 70, near - s, far + s * 1.4);
+  const petals = ['#FF6B9D', '#FFFFFF', '#FFD54F', '#B784FF', '#6FA8FF'].map((c) => toColor(c));
+  for (let i = 0; i < 5; i++) place(flowerMesh(), 0.8, petals[i]!, 5, near - s * 0.5, far + s * 1.4);
+  place(rockMesh(), [0.07, 0.05, 0.06], [0.85, 0.8, 0.75, 1], 14, near - s * 0.5, far + s);
+
+  const mounds = l.holes.map(([x, , z]) =>
+    world.spawn({
+      mesh: moundMesh(),
+      position: [x, 0, z],
+      scale: s,
+      rotation: quat.y(rand() * 6.3),
+      color: tinted([1, 1, 1, 1], tint),
+      pickable: false
+    })
+  );
+  const moles = l.holes.map((_, i) =>
+    world.spawn({ mesh: moleMesh(), position: molePosition(l, i, false), scale: moleScale(l), color: tinted([1, 1, 1, 1], tint), pickable: false })
+  );
+  return { scenery, mounds, moles };
+}
+
+export function removeScene(world: World, s: Scene) {
+  for (const e of [...s.scenery, ...s.mounds, ...s.moles]) world.despawn(e);
+}
+
+// ── Motion ────────────────────────────────────────────────────────────
+
+/** A mole springs up out of its hole and looks about. */
+export function popUp(world: World, l: Layout, s: Scene, hole: number) {
+  const mole = s.moles[hole]!;
+  world.stopAnimation(mole);
+  world.set(mole, { position: molePosition(l, hole, false), scale: moleScale(l), rotation: quat.y(0) });
+  world.animate(mole, { position: molePosition(l, hole, true) }, { spring: { stiffness: 200, damping: 15 } });
+  world.animate(mole, [{ rotation: quat.y(0.35), at: 0.3 }, { rotation: quat.y(-0.35), at: 0.8 }, { rotation: quat.y(0) }], {
+    duration: 1.6,
+    delay: 0.25,
+    easing: 'easeInOut'
+  });
+}
+
+/** A mole that wasn't hit ducks back down. */
+export function duck(world: World, l: Layout, s: Scene, hole: number) {
+  const mole = s.moles[hole]!;
+  world.stopAnimation(mole);
+  world.animate(mole, { position: molePosition(l, hole, false) }, { duration: 0.22, easing: 'easeIn' });
+}
+
+/** A whacked mole squashes flat, sees stars and sinks away. */
+export function bonk(world: World, l: Layout, s: Scene, hole: number) {
+  const mole = s.moles[hole]!;
+  const size = moleScale(l);
+  world.stopAnimation(mole);
+  world.animate(mole, [{ scale: [size * 1.25, size * 0.55, size * 1.25], at: 0.25 }, { scale: [size * 1.1, size * 0.7, size * 1.1] }], {
+    duration: 0.18
+  });
+  world.animate(mole, { position: molePosition(l, hole, false) }, { duration: 0.28, delay: 0.14, easing: 'easeIn' });
+  world.animate(mole, { scale: size }, { duration: 0.01, delay: 0.45 });
+  const [x, , z] = l.holes[hole]!;
+  effects.sparkle(world, {
+    position: [x, moleTop(l) * 0.75, z],
+    count: 14,
+    size: l.spacing * 0.06,
+    speed: l.spacing * 2.2,
+    direction: [0, 1, 0],
+    spread: 1.1,
+    lifetime: 0.55,
+    gravity: -l.spacing * 4,
+    colors: [toColor('#FFD700'), toColor('#FFF59D'), toColor('#FFA500')]
+  });
+}
+
+/** Dirt kicked up where a tap hits an empty hole. */
+export function thud(world: World, l: Layout, hole: number) {
+  const [x, , z] = l.holes[hole]!;
+  effects.shatter(world, {
+    position: [x, l.spacing * 0.05, z],
+    count: 8,
+    mesh: 'sphere',
+    size: l.spacing * 0.05,
+    speed: l.spacing * 1.6,
+    direction: [0, 1, 0],
+    spread: 1.2,
+    lifetime: 0.45,
+    gravity: -l.spacing * 6,
+    colors: [toColor('#7A4E2D'), toColor('#A27449')],
+    flash: false
+  });
+}
+
+// ── The hit ───────────────────────────────────────────────────────────
+
+const STREAK: Color = [2.2, 1.85, 0.7, 0.95]; // above 1: self-lit
+const FLASH: Color = [2.4, 2.1, 1.2, 0.8];
+const DUST: Color = [0.86, 0.74, 0.56, 0.6];
+
+/** A soft puff of dust kicked out round a hole, low and wide. */
+function dust(world: World, l: Layout, hole: number, amount: number) {
+  const [x, , z] = l.holes[hole]!;
+  const s = l.spacing;
+  effects.dust(world, {
+    position: [x, s * 0.05, z],
+    count: Math.round(10 * amount),
+    size: s * 0.22 * amount,
+    speed: s * 2.2 * amount,
+    direction: [0, 1, 0],
+    spread: 1.45,
+    lifetime: 0.5,
+    color: DUST,
+    endSize: 2.2
+  });
+}
+
+/**
+ * A whack: a hot flash flares behind the mole's head, eight impact streaks shoot out from it, comic
+ * style, and dust puffs out round the hole (the mole squashes and sees stars in `bonk`).
+ */
+export function hitEffect(world: World, l: Layout, hole: number) {
+  const [x, , z] = l.holes[hole]!;
+  const s = l.spacing;
+  const at: Vec3 = [x, moleTop(l) * 0.8, z + s * 0.2];
+  effects.flash(world, { position: at, color: FLASH, size: s * 0.5, lifetime: 0.16, endSize: 2.4 });
+  const spokes = 8;
+  const twist = Math.random() * Math.PI;
+  for (let i = 0; i < spokes; i++) {
+    const a = twist + (i / spokes) * Math.PI * 2;
+    const [cx, cy] = [Math.cos(a), Math.sin(a)];
+    const from = s * 0.32;
+    const to = s * (0.75 + (i % 2) * 0.2);
+    const streak = world.spawn({
+      mesh: 'cube',
+      position: [at[0] + cx * from, at[1] + cy * from, at[2]],
+      rotation: quat.z(a),
+      scale: [s * 0.2, s * 0.05, s * 0.02],
+      color: STREAK,
+      pickable: false
+    });
+    world
+      .animate(
+        streak,
+        { position: [at[0] + cx * to, at[1] + cy * to, at[2]], scale: [s * 0.04, s * 0.012, s * 0.02], color: [STREAK[0], STREAK[1], STREAK[2], 0] },
+        { duration: 0.26, easing: 'easeOut' }
+      )
+      .then(() => {
+        if (world.has(streak)) world.despawn(streak);
+      });
+  }
+  dust(world, l, hole, 1);
+}
+
+/** A miss: a smaller puff of dust with the dirt. */
+export function missEffect(world: World, l: Layout, hole: number) {
+  dust(world, l, hole, 0.6);
+}
+
+/** Every mole back underground (a reset or the end of a game). */
+export function hideAll(world: World, l: Layout, s: Scene) {
+  s.moles.forEach((m, i) => {
+    world.stopAnimation(m);
+    world.set(m, { position: molePosition(l, i, false), scale: moleScale(l), rotation: quat.y(0) });
+  });
+}

package/src/games/word-search/WordSearch.tsx

@@ -0,0 +1,18 @@
+// Word Search, on the Nayan engine: eight words hidden in a 10 x 10 grid of 3D letter tiles. The board,
+// rules and screen are shared with Number Search (search-grid/); this is what's Word Search's own.
+import { GAME_SOUNDS } from '../../services/SoundsService';
+import { GAME_IDS } from '../../services/UtilsService';
+import { createSearchGame } from '../search-grid/SearchGrid';
+import { WORDS } from './WordSearchWords';
+
+export const WordSearch = createSearchGame({
+  gameId: GAME_IDS.WORD_SEARCH,
+  list: WORDS,
+  alphabet: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ',
+  sounds: GAME_SOUNDS.WORD_SEARCH,
+  winTitle: 'ALL WORDS FOUND!',
+  winMessage: 'Great word hunting!',
+  startSubtext: 'Find hidden words!',
+  variant: 'word',
+  displayName: 'WordSearch'
+});