@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/treasure-hunt/TreasureHuntScene.ts

@@ -0,0 +1,586 @@
+// Treasure Hunt: Builds the wilderness and its bridges from cached meshes.
+import {
+  type Color,
+  type Entity,
+  extrude,
+  type GeometryPart,
+  merge,
+  type Model,
+  Path,
+  quat,
+  shapeGeometry,
+  type Texture,
+  tube,
+  type Vec3,
+  type World
+} from '@nayan-ui/engine';
+import type { EngineHud } from '../shared/EngineHud';
+import { getSceneInputInsets } from '../shared/EngineHud';
+import { cacheGameAsset, createGameMesh as createShape } from '../shared/EngineMeshes';
+import { toColor } from '../shared/EngineUtils';
+import { MINIMAP_SIZE, type NatureAssets, WORLD_EDGE } from './TreasureHuntConstants';
+import {
+  boulderGeometry,
+  caveGeometry,
+  diamondGeometry,
+  foliageGeometry,
+  grassGeometry,
+  riverGeometry,
+  type TerrainGeometry,
+  terrainGeometrySteps
+} from './TreasureHuntMeshes';
+import { placeContactShadow, spawnContactShadow } from './TreasureHuntModel';
+import {
+  type Bridge,
+  BRIDGE_POST_HEIGHT,
+  BRIDGE_POST_WIDTH,
+  bridgeBarriers,
+  groundHeight,
+  groundTilt,
+  isWalkable,
+  landscapeFor,
+  mapOverview,
+  type NatureMap,
+  type NatureState,
+  random,
+  riverWidth,
+  riverX,
+  surfaceAt,
+  toWorld
+} from './TreasureHuntRules';
+
+// Bridge construction.
+
+let meshes: { plank: Model; post: Model } | undefined;
+
+const part = (mesh: 'roundedBox' | 'cube' | 'cylinder', position: Vec3, scale: Vec3, color: Color): GeometryPart => ({
+  geometry: shapeGeometry(mesh),
+  position,
+  scale,
+  color
+});
+
+function prepareBridge() {
+  return cacheGameAsset('treasure-hunt/TreasureHuntScene:prepareBridge', () => prepareBridgeUncached());
+}
+
+function prepareBridgeUncached() {
+  meshes ??= {
+    plank: createShape(merge([part('roundedBox', [0, -0.08, 0], [0.43, 0.16, 5.6], [1, 1, 1])]), { center: false, shine: 0.12 }),
+    post: createShape(
+      merge([
+        part('roundedBox', [0, 0.5, 0], [0.16, BRIDGE_POST_HEIGHT, 0.16], [0.31, 0.35, 0.33]),
+        part('cube', [0, 0.04, 0], [BRIDGE_POST_WIDTH, 0.08, BRIDGE_POST_WIDTH], [0.16, 0.2, 0.2]),
+        part('roundedBox', [0, 1.08, 0], [0.2, 0.08, 0.2], [0.54, 0.57, 0.51]),
+        ...[-1, 1].flatMap((x) => [-1, 1].map((z) => part('cylinder', [x * 0.09, 0.09, z * 0.09], [0.035, 0.02, 0.035], [0.64, 0.64, 0.56])))
+      ]),
+      { center: false, shine: 0.55 }
+    )
+  };
+  return meshes;
+}
+
+/** Decks, supports and guardrails use the exact span and height sampled by movement. */
+export function spawnBridge(world: World, owner: Entity, map: NatureMap, bridge: Bridge, assets: NatureAssets) {
+  const mesh = prepareBridge(),
+    p = toWorld(map, bridge.x, bridge.z);
+  const root = world.spawn({ mesh: 'none', parent: owner, position: [p.x, bridge.y, p.z], rotation: quat.y(map.rotation), pickable: false });
+  const count = Math.ceil((bridge.halfLength * 2) / 0.43),
+    step = (bridge.halfLength * 2) / count;
+  for (let i = 0; i < count; i++)
+    world.spawn({
+      mesh: mesh.plank,
+      texture: assets.bark,
+      parent: root,
+      position: [-bridge.halfLength + (i + 0.5) * step, 0, 0],
+      scale: [step / 0.43, 1, (bridge.halfWidth * 2) / 5.6],
+      color: [1.4, 1.13, 0.81, 1],
+      pickable: false
+    });
+  for (const side of [-1, 1]) {
+    world.spawn({
+      mesh: 'cube',
+      parent: root,
+      position: [0, -0.28, side * 1.85],
+      scale: [bridge.halfLength * 2, 0.34, 0.22],
+      color: [0.23, 0.26, 0.24, 1],
+      pickable: false
+    });
+    for (const end of [-1, 1])
+      world.spawn({
+        mesh: 'cube',
+        parent: root,
+        position: [end * (bridge.halfLength - 0.65), -0.7, side * 1.85],
+        scale: [0.85, 1.3, 0.85],
+        texture: assets.stone,
+        color: [0.72, 0.75, 0.66, 1],
+        pickable: false
+      });
+  }
+  for (const barrier of bridgeBarriers(bridge)) {
+    if (barrier.kind === 'post') world.spawn({ mesh: mesh.post, parent: root, position: [barrier.x, 0, barrier.z], pickable: false });
+    else
+      for (const y of [0.48, 0.98])
+        world.spawn({
+          mesh: 'cube',
+          parent: root,
+          position: [barrier.x, y, barrier.z],
+          scale: [barrier.halfX * 2, 0.07, barrier.halfZ * 2],
+          color: [0.39, 0.43, 0.4, 1],
+          pickable: false
+        });
+  }
+}
+// Wilderness scene.
+
+export { spawnRobot, placeRobot } from './TreasureHuntModel';
+
+export type { RobotVisual } from './TreasureHuntModel';
+
+const WHITE: Color = [1, 1, 1, 1];
+
+interface NatureMeshes {
+  gem: Model;
+  trunks: Model[];
+  pine: Model[];
+  birch: Model[];
+  rocks: Model[];
+  grass: Model[];
+  cave: Model;
+}
+
+let natureMeshes: NatureMeshes | undefined;
+
+type TerrainModels = { meadow: Model; stone: Model; shore: Model; water: Model };
+const terrainMeshes = new Map<number, TerrainModels>();
+interface TerrainPreparation {
+  builder: Generator<void, TerrainGeometry>;
+  geometry?: TerrainGeometry;
+  models: Partial<TerrainModels>;
+}
+const terrainPreparations = new Map<number, TerrainPreparation>();
+function terrainPreparation(profile: number): TerrainPreparation {
+  let pending = terrainPreparations.get(profile);
+  if (!pending) {
+    pending = { builder: terrainGeometrySteps(profile), models: {} };
+    terrainPreparations.set(profile, pending);
+  }
+  return pending;
+}
+function advanceTerrain(pending: TerrainPreparation) {
+  if (pending.geometry) return;
+  const next = pending.builder.next();
+  if (next.done) pending.geometry = next.value;
+}
+function terrainPart(profile: number, pending: TerrainPreparation, part: keyof TerrainModels): Model {
+  return (pending.models[part] ??= cacheGameAsset(`treasure-terrain:${profile}:${part}`, () => {
+    if (part === 'water') return createShape(riverGeometry(landscapeFor(profile)), { center: false, shine: 0.85 });
+    while (!pending.geometry) advanceTerrain(pending);
+    return createShape(pending.geometry[part], { center: false });
+  }));
+}
+function* warmTerrain(profile: number): Iterable<() => void> {
+  if (terrainMeshes.has(profile)) return;
+  const pending = terrainPreparation(profile);
+  while (!pending.geometry) {
+    yield () => advanceTerrain(pending);
+    if (terrainMeshes.has(profile)) return;
+  }
+  for (const part of ['meadow', 'stone', 'shore', 'water'] as const) {
+    yield () => {
+      terrainPart(profile, pending, part);
+    };
+    if (terrainMeshes.has(profile)) return;
+  }
+  terrainMeshes.set(profile, pending.models as TerrainModels);
+  terrainPreparations.delete(profile);
+}
+
+function trunk(pine: boolean, style: number) {
+  const height = pine ? 9.4 : 8.2,
+    parts: GeometryPart[] = [
+      {
+        geometry: tube(
+          [
+            [0, -0.45, 0],
+            [0, -0.08, 0],
+            [0.03, 0.35, 0.02],
+            [0.08, 2, 0.08],
+            [-0.08, 4.4, 0],
+            [0.2, height, 0.1]
+          ],
+          { radius: (t) => 0.32 * (1 - t * 0.95), sides: 9, smoothness: 2 }
+        )
+      }
+    ];
+  for (let i = 0; i < 12; i++) {
+    const a = i * 2.4 + style,
+      y = 4.8 + i * (pine ? 0.33 : 0.24),
+      reach = pine ? (1 - i / 16) * 2.1 : 1.6;
+    parts.push({
+      geometry: tube(
+        [
+          [0, y, 0],
+          [Math.cos(a) * reach * 0.55, y + 0.15, Math.sin(a) * reach * 0.55],
+          [Math.cos(a) * reach, y + (pine ? -0.1 : 0.9), Math.sin(a) * reach]
+        ],
+        { radius: (t) => 0.065 * (1 - t * 0.98), sides: 5, smoothness: 1 }
+      )
+    });
+  }
+  return createShape(merge(parts), { center: false });
+}
+
+const natureCache = new Map<string, Model>();
+function natureMesh(key: string, build: () => Model): Model {
+  let model = natureCache.get(key);
+  if (!model) {
+    model = cacheGameAsset('treasure-hunt/TreasureHuntScene:' + key, build);
+    natureCache.set(key, model);
+  }
+  return model;
+}
+const gemMesh = () => natureMesh('gem', () => createShape(diamondGeometry(), { center: false, shine: 0.98 }));
+const trunkMesh = (pine: boolean, style: number) => natureMesh(`trunk:${pine}:${style}`, () => trunk(pine, style));
+const foliageMesh = (pine: boolean, style: number) =>
+  natureMesh(`foliage:${pine}:${style}`, () => createShape(foliageGeometry(pine, style), { center: false }));
+const rockMesh = (style: number) => natureMesh(`rock:${style}`, () => createShape(boulderGeometry(style), { center: false }));
+const grassMesh = (style: number) => natureMesh(`grass:${style}`, () => createShape(grassGeometry(style), { center: false }));
+const caveMesh = () => natureMesh('cave', () => createShape(caveGeometry(), { center: false }));
+
+export function prepareNature(): NatureMeshes {
+  natureMeshes ??= {
+    gem: gemMesh(),
+    trunks: [trunkMesh(true, 0), trunkMesh(false, 1)],
+    pine: Array.from({ length: 4 }, (_, i) => foliageMesh(true, i)),
+    birch: Array.from({ length: 4 }, (_, i) => foliageMesh(false, i)),
+    rocks: Array.from({ length: 4 }, (_, i) => rockMesh(i)),
+    grass: Array.from({ length: 4 }, (_, i) => grassMesh(i)),
+    cave: caveMesh()
+  };
+  return natureMeshes;
+}
+
+/** Reusable scenery only: terrain profiles and seeded maps are built for the chosen run. */
+export function* warmAssets(): Iterable<() => unknown> {
+  yield prepareBridge;
+  yield gemMesh;
+  yield () => trunkMesh(true, 0);
+  yield () => trunkMesh(false, 1);
+  for (let i = 0; i < 4; i++) {
+    yield () => foliageMesh(true, i);
+    yield () => foliageMesh(false, i);
+    yield () => rockMesh(i);
+    yield () => grassMesh(i);
+  }
+  yield caveMesh;
+}
+
+export function terrainModels(profile: number) {
+  let models = terrainMeshes.get(profile);
+  if (!models) {
+    const pending = terrainPreparation(profile);
+    models = {
+      meadow: terrainPart(profile, pending, 'meadow'),
+      stone: terrainPart(profile, pending, 'stone'),
+      shore: terrainPart(profile, pending, 'shore'),
+      water: terrainPart(profile, pending, 'water')
+    };
+    terrainMeshes.set(profile, models);
+    terrainPreparations.delete(profile);
+  }
+  return models;
+}
+
+export interface NatureVisual {
+  root: Entity;
+  water: Entity;
+  flow: number;
+}
+
+interface GrassPlacement {
+  position: Vec3;
+  scale: number;
+  yaw: number;
+  style: number;
+}
+interface GrassPreparation {
+  builder: Generator<void, GrassPlacement[]>;
+  placements?: GrassPlacement[];
+}
+const grassPlacements = new WeakMap<NatureMap, GrassPreparation>();
+
+function* scatterGrass(map: NatureMap): Generator<void, GrassPlacement[]> {
+  const rng = random(map.seed ^ 0x679be3);
+  const placements: GrassPlacement[] = [];
+  const cos = Math.cos(map.rotation),
+    sin = Math.sin(map.rotation);
+  for (let i = 0; i < 1900; i++) {
+    if (i && i % 64 === 0) yield;
+    const at = map.reachable[Math.floor(rng() * map.reachable.length)]!;
+    const x = at.x + (rng() - 0.5) * 2,
+      z = at.z + (rng() - 0.5) * 2;
+    const local = { x: x * cos - z * sin, z: x * sin + z * cos };
+    if (
+      surfaceAt(map, x, z) !== 'grass' ||
+      !isWalkable(map, x, z, 0.9) ||
+      Math.abs(local.x - riverX(map.landscape, local.z)) < riverWidth(map.landscape, local.z) + 1 ||
+      map.landscape.caves.some((c) => Math.abs(local.x - c.x) < 6 && Math.abs(local.z - c.z) < 11)
+    )
+      continue;
+    placements.push({ position: [x, groundHeight(map, x, z) - 0.02, z], scale: 0.7 + rng() * 0.7, yaw: rng() * Math.PI * 2, style: i % 4 });
+  }
+  return placements;
+}
+
+function grassPreparation(map: NatureMap): GrassPreparation {
+  let pending = grassPlacements.get(map);
+  if (!pending) {
+    pending = { builder: scatterGrass(map) };
+    grassPlacements.set(map, pending);
+  }
+  return pending;
+}
+
+function advanceGrass(pending: GrassPreparation) {
+  if (pending.placements) return;
+  const step = pending.builder.next();
+  if (step.done) pending.placements = step.value;
+}
+
+/** No second world or native entities: prepare only the next run's immutable scenery data. */
+export function* warmMapScenery(map: NatureMap): Iterable<() => void> {
+  const pending = grassPreparation(map);
+  while (!pending.placements) yield () => advanceGrass(pending);
+  yield () => {
+    minimapTiles(map);
+  };
+  yield* warmTerrain(map.landscape.profile);
+}
+
+/** A single owner root makes replay cleanup include every tree, grass blade and bridge. */
+export function spawnNature(world: World, map: NatureMap, assets: NatureAssets): NatureVisual {
+  const meshes = prepareNature(),
+    terrain = terrainModels(map.landscape.profile);
+  const root = world.spawn({ mesh: 'none', pickable: false });
+  const add = (mesh: Model | 'sphere', position: Vec3, scale: Vec3 | number = 1, color: Color = WHITE, texture?: Texture, yaw = 0) =>
+    world.spawn({ mesh, position, scale, color, texture, rotation: quat.y(yaw), parent: root, pickable: false });
+  const treeContact = (position: Vec3, scale: Vec3 | number) => {
+    const sx = typeof scale === 'number' ? scale : scale[0],
+      sz = typeof scale === 'number' ? scale : scale[2];
+    placeContactShadow(
+      world,
+      spawnContactShadow(world, root),
+      [position[0], groundHeight(map, position[0], position[2]) + 0.006, position[2]],
+      groundTilt(map, position[0], position[2]),
+      sx * 0.27,
+      sz * 0.27,
+      0.065
+    );
+  };
+  add(terrain.meadow, [0, 0, 0], 1, [0.85, 0.96, 0.77, 1], assets.meadow, map.rotation);
+  add(terrain.stone, [0, 0, 0], 1, [0.9, 0.94, 0.92, 1], assets.stone, map.rotation);
+  add(terrain.shore, [0, 0, 0], 1, [0.96, 0.78, 0.53, 1], assets.stone, map.rotation);
+  for (const bridge of map.landscape.bridges) spawnBridge(world, root, map, bridge, assets);
+  const water = add(terrain.water, [0, 0, 0], 1, [1.3, 1.3, 1.3, 0.94], assets.water, map.rotation);
+  for (const prop of map.props) {
+    const position: Vec3 = [prop.x, groundHeight(map, prop.x, prop.z) - 0.07, prop.z];
+    if (prop.kind === 'rock') add(meshes.rocks[prop.style]!, position, prop.scale, WHITE, assets.stone, prop.yaw);
+    else {
+      add(
+        meshes.trunks[prop.kind === 'pine' ? 0 : 1]!,
+        position,
+        prop.scale,
+        prop.kind === 'pine' ? [0.7, 0.65, 0.52, 1] : [1.35, 1.35, 1.24, 1],
+        assets.bark,
+        prop.yaw
+      );
+      add(meshes[prop.kind][prop.style]!, position, prop.scale, WHITE, prop.kind === 'pine' ? assets.pine : assets.leaves, prop.yaw);
+      treeContact(position, prop.scale);
+    }
+  }
+  for (const prop of map.decorations) {
+    const position: Vec3 = [prop.x, prop.y, prop.z];
+    if (prop.kind === 'rock') {
+      const color: Color = prop.area === 'horizon' ? [0.62, 0.69, 0.65, 1] : prop.area === 'cave-roof' ? [0.85, 0.9, 0.84, 1] : [0.8, 0.88, 0.8, 1];
+      add(meshes.rocks[prop.style]!, position, prop.scale, color, assets.stone, prop.yaw);
+    } else {
+      add(meshes.trunks[0]!, position, prop.scale, [0.7, 0.65, 0.52, 1], assets.bark, prop.yaw);
+      add(meshes.pine[prop.style]!, position, prop.scale, [0.7, 0.8, 0.74, 1], assets.pine, prop.yaw);
+      treeContact(position, prop.scale);
+    }
+  }
+  const grass = grassPreparation(map);
+  while (!grass.placements) advanceGrass(grass);
+  for (const placement of grass.placements) add(meshes.grass[placement.style]!, placement.position, placement.scale, WHITE, undefined, placement.yaw);
+  for (const cave of map.landscape.caves) {
+    const p = toWorld(map, cave.x, cave.z);
+    add(meshes.cave, [p.x, cave.y, p.z], 1, WHITE, assets.stone, map.rotation);
+  }
+  return { root, water, flow: 0 };
+}
+
+/** River motion shares the engine's existing frame tick. */
+export function animateNature(world: World, nature: NatureVisual, dt: number) {
+  nature.flow = (nature.flow + dt * 0.08) % 1;
+  world.set(nature.water, { textureRegion: [0, nature.flow, 1, 1 + nature.flow] });
+}
+
+export function spawnGem(world: World, x: number, y: number, z: number) {
+  return world.spawn({
+    mesh: prepareNature().gem,
+    position: [x, y + 0.9, z],
+    scale: 0.7,
+    color: [0.92, 1.02, 1.12, 1],
+    spin: [0, 0.85, 0],
+    bob: { amplitude: [0, 0.16, 0], speed: 2.5, phase: x + z },
+    pickable: false
+  });
+}
+
+// Screen-space minimap: the engine renders terrain, bridges and objective markers in its HUD world.
+const MAP_COLORS = { grass: '#649452', hill: '#b3b8ac', cave: '#777f77', river: '#38b8ee', shore: '#cdb785', bridge: '#f7d79a' };
+interface MinimapTile {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  color: Color;
+}
+const mapTiles = new WeakMap<NatureMap, MinimapTile[]>();
+interface MinimapMarker {
+  entity: Entity;
+  x: number;
+  z: number;
+  visible: boolean;
+}
+interface MinimapView {
+  map: NatureMap;
+  root: Entity;
+  player: Entity;
+  width: number;
+  offset: number;
+  x: number;
+  z: number;
+  yaw: number;
+  enemies: Map<number, MinimapMarker>;
+  gems: Map<number, MinimapMarker>;
+}
+const miniMaps = new WeakMap<EngineHud, MinimapView>();
+const mapAt = (value: number) => ((value + WORLD_EDGE) / (WORLD_EDGE * 2)) * MINIMAP_SIZE;
+let mapDot: Model | undefined;
+let mapArrow: Model | undefined;
+function minimapTiles(map: NatureMap): MinimapTile[] {
+  const cached = mapTiles.get(map);
+  if (cached) return cached;
+  const samples = mapOverview(map, MINIMAP_SIZE),
+    tiles: MinimapTile[] = [];
+  let previous = new Map<string, MinimapTile>();
+  for (let row = 0; row < MINIMAP_SIZE; row++) {
+    const next = new Map<string, MinimapTile>();
+    let start = 0;
+    while (start < MINIMAP_SIZE) {
+      const surface = samples[row * MINIMAP_SIZE + start];
+      let end = start + 1;
+      while (end < MINIMAP_SIZE && samples[row * MINIMAP_SIZE + end] === surface) end++;
+      if (surface) {
+        const key = `${start}:${end}:${surface}`,
+          above = previous.get(key);
+        if (above) {
+          above.height++;
+          next.set(key, above);
+        } else {
+          const tile = { x: start, y: row, width: end - start, height: 1, color: toColor(MAP_COLORS[surface]) };
+          tiles.push(tile);
+          next.set(key, tile);
+        }
+      }
+      start = end;
+    }
+    previous = next;
+  }
+  mapTiles.set(map, tiles);
+  return tiles;
+}
+export function drawMiniMap(hud: EngineHud, state: NatureState) {
+  if (!hud.ready) return;
+  let view = miniMaps.get(hud);
+  if (view?.map !== state.map) {
+    hud.clearLayer('minimap');
+    const root = hud.layer('minimap');
+    for (const tile of minimapTiles(state.map))
+      hud.rectangle(root, tile.x + tile.width / 2, -tile.y - tile.height / 2, tile.width, tile.height, tile.color);
+    for (const bridge of state.map.landscape.bridges) {
+      const p = toWorld(state.map, bridge.x, bridge.z);
+      const entity = hud.rectangle(
+        root,
+        mapAt(p.x),
+        -mapAt(p.z),
+        (bridge.halfLength / WORLD_EDGE) * MINIMAP_SIZE,
+        Math.max(3, (bridge.halfWidth / WORLD_EDGE) * MINIMAP_SIZE),
+        toColor(MAP_COLORS.bridge),
+        1
+      );
+      hud.world.set(entity, { rotation: quat.z(state.map.rotation) });
+    }
+    mapDot ??= cacheGameAsset('treasure-map-dot', () => createShape(extrude(new Path().addCircle(0, 0, 0.5), { depth: 0 }), { center: false }));
+    mapArrow ??= cacheGameAsset('treasure-map-arrow', () => createShape(extrude(Path.fromSVG('M-3 0H3L0 5Z'), { depth: 0 }), { center: false }));
+    const player = hud.world.spawn({ mesh: 'none', parent: root, pickable: false });
+    hud.world.spawn({ mesh: mapDot, parent: player, scale: 10, color: [1, 1, 1, 1], pickable: false });
+    hud.world.spawn({ mesh: mapDot, parent: player, position: [0, 0, 1], scale: 6, color: toColor('#173d28'), pickable: false });
+    hud.world.spawn({ mesh: mapArrow, parent: player, position: [0, 7, 1], color: [1, 1, 1, 1], pickable: false });
+    hud.text(root, 'N', MINIMAP_SIZE - 8, -8, 10, [1, 1, 1, 1]);
+    view = { map: state.map, root, player, width: NaN, offset: NaN, x: NaN, z: NaN, yaw: NaN, enemies: new Map(), gems: new Map() };
+    miniMaps.set(hud, view);
+  }
+  const { width, offset } = hud.viewport;
+  const updates = hud.world.transforms;
+  if (view.width !== width || view.offset !== offset) {
+    updates.position(view.root, width - MINIMAP_SIZE - 18, -(getSceneInputInsets(offset).top + 6), 5);
+    view.width = width;
+    view.offset = offset;
+  }
+  if (view.x !== state.player.x || view.z !== state.player.z || view.yaw !== state.yaw) {
+    const yaw = state.yaw - Math.PI;
+    updates.transform(view.player, mapAt(state.player.x), -mapAt(state.player.z), 4, 0, 0, Math.sin(yaw / 2), Math.cos(yaw / 2));
+    view.x = state.player.x;
+    view.z = state.player.z;
+    view.yaw = state.yaw;
+  }
+  for (const enemy of state.enemies) {
+    let marker = view.enemies.get(enemy.id);
+    if (!marker) {
+      marker = {
+        entity: hud.world.spawn({ mesh: mapDot!, parent: view.root, scale: 6, color: toColor('#ff6355'), pickable: false }),
+        x: NaN,
+        z: NaN,
+        visible: true
+      };
+      view.enemies.set(enemy.id, marker);
+    }
+    const visible = enemy.health > 0;
+    if (marker.x !== enemy.x || marker.z !== enemy.z || marker.visible !== visible) {
+      updates.position(marker.entity, mapAt(enemy.x), -mapAt(enemy.z), 2);
+      updates.scale(marker.entity, visible ? 6 : 0);
+      marker.x = enemy.x;
+      marker.z = enemy.z;
+      marker.visible = visible;
+    }
+  }
+  for (const gem of state.pickups) {
+    let marker = view.gems.get(gem.id);
+    if (!marker) {
+      const entity = hud.rectangle(view.root, mapAt(gem.x), -mapAt(gem.z), 5, 5, toColor('#bdffff'), 3);
+      updates.rotation(entity, 0, 0, Math.sin(Math.PI / 8), Math.cos(Math.PI / 8));
+      if (gem.taken) updates.scale(entity, 0);
+      else updates.scale(entity, 5, 5, 1);
+      marker = { entity, x: gem.x, z: gem.z, visible: !gem.taken };
+      view.gems.set(gem.id, marker);
+    } else if (marker.visible !== !gem.taken) {
+      if (gem.taken) updates.scale(marker.entity, 0);
+      else updates.scale(marker.entity, 5, 5, 1);
+      marker.visible = !gem.taken;
+    }
+  }
+  updates.flush();
+}

package/src/games/whack-a-mole/WhackAMole.tsx

@@ -0,0 +1,79 @@
+// Whack a Mole's screen, on the Nayan engine: the meadow, the lawn of holes, the moles and the mallet
+// are one 3D scene (a perspective camera at eye height looking across the lawn), under Playtura's
+// scoreboard, controls and modals. The rules are in WhackAMoleGame.ts, what it draws in
+// WhackAMoleScene.ts.
+//
+// One world serves the whole visit: Start, Stop and Play Again reset it in place, so the GPU view is
+// never rebuilt. Moles, the mallet and the bursts animate in the engine's Rust core; JS runs the
+// game's clock, hit-tests taps and steps the world once a frame.
+import { useMemo } from 'react';
+import { HapticType } from '../../services/HapticsService';
+import { GAME_SOUNDS } from '../../services/SoundsService';
+import { GAME_IDS } from '../../services/UtilsService';
+import { engineGame, EngineGameScreen } from '../shared/EngineGameScreen';
+import { scoreColumn, timerColumn } from '../shared/EngineHud';
+import { backgroundFor, lightFor } from '../shared/EngineMeadow';
+import { useEngineGame } from '../shared/useEngineGame';
+import { useLiveState } from '../shared/useLiveState';
+import { getLayout, TIME_LIMIT } from './WhackAMoleConstants';
+import { createGame, dispose, type GameEvent, reset, setLayout, setTheme, start, tap, tick } from './WhackAMoleGame';
+
+const SOUNDS = GAME_SOUNDS.WHACK_A_MOLE;
+
+/** Each event's sound and haptic, as the original version played them. */
+const FEEDBACK: Record<GameEvent, { sound: (typeof SOUNDS)[keyof typeof SOUNDS]; haptic: HapticType }> = {
+  spawn: { sound: SOUNDS.SPAWN, haptic: HapticType.LIGHT },
+  hit: { sound: SOUNDS.HIT, haptic: HapticType.HEAVY },
+  miss: { sound: SOUNDS.MISS, haptic: HapticType.LIGHT },
+  empty: { sound: SOUNDS.EMPTY_TAP, haptic: HapticType.MEDIUM },
+  warning: { sound: SOUNDS.TIME_WARNING, haptic: HapticType.WARNING }
+};
+
+export const WhackAMole = engineGame(GAME_IDS.WHACK_A_MOLE, (props) => {
+  const [score, setScore] = useLiveState(0);
+  const [timeLeft, setTimeLeft] = useLiveState(TIME_LIMIT);
+
+  const { theme, screen, gameOver } = useEngineGame(props, {
+    gameId: GAME_IDS.WHACK_A_MOLE,
+    create: createGame,
+    start,
+    reset,
+    dispose,
+    tick,
+    setTheme,
+    resize: (g, width, height, offset) => setLayout(g, getLayout(width, height, offset)),
+    tap,
+    // A win (whatever was scored) when the time runs out
+    outcome: () => 'win',
+    sounds: SOUNDS,
+    onStart: (fx) => fx(SOUNDS.START, HapticType.SUCCESS),
+    onStop: (fx) => fx(null, HapticType.MEDIUM),
+    onOver: (fx) => fx(SOUNDS.GAME_OVER, HapticType.ERROR),
+    wire: (g, fx) => {
+      g.onScore = setScore;
+      g.onTime = setTimeLeft;
+      g.onEvent = (event) => fx(FEEDBACK[event].sound, FEEDBACK[event].haptic);
+    }
+  });
+
+  // Sunlight by day, moonlight at night (the world's colors follow the theme too)
+  const light = useMemo(() => lightFor(theme), [theme]);
+  const background = useMemo(() => backgroundFor(theme), [theme]);
+
+  return (
+    <EngineGameScreen
+      {...screen}
+      light={light}
+      background={background}
+      columns={[scoreColumn(score), timerColumn(timeLeft, theme, 0)]}
+      subtext="Whack moles to score!"
+      gameOver={gameOver({
+        title: 'TIME UP!',
+        message: 'Great whacking!',
+        scoreLabel: 'Final Score',
+        score,
+        buttonText: 'Whack Again!'
+      })}
+    />
+  );
+});