@nayan-ui/games 1.18.0 → 1.20.0

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

@@ -0,0 +1,280 @@
+import { type Camera, type Entity, type Vec3, type Voice } from '@nayan-ui/engine';
+// Treasure Hunt: Pure swipe, camera and footstep helpers used by the engine tick.
+import { HUMAN_CAMERA_HEIGHT, type HumanAnimation, MOVEMENT_START, MOVEMENT_STOP, type Point } from './TreasureHuntConstants';
+import { caveAt, groundHeight, type NatureInput, type NatureMap, solidClearance, toLocal } from './TreasureHuntRules';
+
+// Swipe input.
+
+export interface SwipeContact {
+  identifier: number | string;
+  pageX: number;
+  pageY: number;
+}
+
+interface TapContact {
+  x: number;
+  y: number;
+  time: number;
+  dragged: boolean;
+}
+
+export interface SwipeInput {
+  x: number;
+  y: number;
+  filtered: { x: number; y: number };
+  filterActive: boolean;
+  touchId: SwipeContact['identifier'] | null;
+  startX: number;
+  startY: number;
+  contacts: Map<SwipeContact['identifier'], TapContact>;
+}
+
+const DEAD_ZONE = 8;
+
+const RUN_DISTANCE = 80;
+
+const TAP_DURATION = 280;
+
+const INPUT_RESPONSE = 0.035;
+
+export const createSwipeInput = (): SwipeInput => ({
+  x: 0,
+  y: 0,
+  filtered: { x: 0, y: 0 },
+  filterActive: false,
+  touchId: null,
+  startX: 0,
+  startY: 0,
+  contacts: new Map()
+});
+
+function stopMovement(input: SwipeInput) {
+  input.x = input.y = 0;
+  input.filtered.x = input.filtered.y = 0;
+  input.filterActive = false;
+  input.touchId = null;
+  input.startX = input.startY = 0;
+}
+
+export function resetSwipe(input: SwipeInput) {
+  stopMovement(input);
+  input.contacts.clear();
+}
+
+export function startSwipe(input: SwipeInput, touch: SwipeContact, time = 0) {
+  if (!Number.isFinite(touch.pageX + touch.pageY) || input.contacts.has(touch.identifier)) return;
+  input.contacts.set(touch.identifier, { x: touch.pageX, y: touch.pageY, time, dragged: false });
+  if (input.touchId !== null) return;
+  input.touchId = touch.identifier;
+  input.startX = touch.pageX;
+  input.startY = touch.pageY;
+  input.x = input.y = 0;
+  input.filtered.x = input.filtered.y = 0;
+  input.filterActive = false;
+}
+
+export function moveSwipe(input: SwipeInput, touch: SwipeContact) {
+  const contact = input.contacts.get(touch.identifier);
+  if (contact && Math.hypot(touch.pageX - contact.x, touch.pageY - contact.y) > DEAD_ZONE) contact.dragged = true;
+  if (input.touchId === null || input.touchId !== touch.identifier) return;
+  const dx = touch.pageX - input.startX,
+    dy = touch.pageY - input.startY,
+    distance = Math.hypot(dx, dy);
+  if (!Number.isFinite(distance) || distance <= DEAD_ZONE) {
+    input.x = input.y = 0;
+    return;
+  }
+  // Follow an overshooting finger so a long drag does not trap the control origin far behind it.
+  if (distance > RUN_DISTANCE) {
+    input.startX = touch.pageX - (dx / distance) * RUN_DISTANCE;
+    input.startY = touch.pageY - (dy / distance) * RUN_DISTANCE;
+  }
+  const amount = Math.min(1, (distance - DEAD_ZONE) / (RUN_DISTANCE - DEAD_ZONE));
+  const strength = amount * amount * (3 - 2 * amount);
+  input.x = (dx / distance) * strength;
+  input.y = (-dy / distance) * strength;
+}
+
+/** Sample once per engine frame: touch delivery frequency cannot introduce steering steps. */
+export function sampleSwipe(input: SwipeInput, elapsed: number): { x: number; y: number } {
+  if (input.touchId === null) {
+    input.filtered.x = input.filtered.y = 0;
+    input.filterActive = false;
+    return input.filtered;
+  }
+  const dt = Math.max(0, Math.min(0.05, elapsed)),
+    blend = 1 - Math.exp(-dt / INPUT_RESPONSE);
+  input.filtered.x += (input.x - input.filtered.x) * blend;
+  input.filtered.y += (input.y - input.filtered.y) * blend;
+  const strength = Math.hypot(input.filtered.x, input.filtered.y);
+  if (strength >= MOVEMENT_START) input.filterActive = true;
+  else if (strength < MOVEMENT_STOP) input.filterActive = false;
+  return input.filterActive ? input.filtered : STILL;
+}
+
+const STILL = { x: 0, y: 0 };
+
+/** A swipe, long hold or cancelled gesture never becomes a punch when the finger lifts. */
+export function endSwipe(input: SwipeInput, touch: SwipeContact, time = 0): boolean {
+  const contact = input.contacts.get(touch.identifier);
+  const elapsed = contact ? time - contact.time : Infinity;
+  const tapped =
+    !!contact &&
+    !contact.dragged &&
+    elapsed >= 0 &&
+    elapsed <= TAP_DURATION &&
+    Math.hypot(touch.pageX - contact.x, touch.pageY - contact.y) <= DEAD_ZONE;
+  input.contacts.delete(touch.identifier);
+  if (touch.identifier === input.touchId) stopMovement(input);
+  return tapped;
+}
+// Rear camera and explorer-relative movement.
+
+export const FOLLOW_OFFSET: Vec3 = [0, 0.8, 4.1];
+
+const HEAD_HEIGHT = HUMAN_CAMERA_HEIGHT;
+
+export function createNatureCamera(target: Entity, spawn: Point, yaw = 0, map?: NatureMap): Camera {
+  const camera: Camera = { eye: [0, 0, 0], target: [0, 0, 0], fov: 0.95, follow: { target, offset: FOLLOW_OFFSET, smoothing: 0.045 } };
+  resetNatureCamera(camera, spawn, yaw, map);
+  return camera;
+}
+
+/** Stay behind the facing direction, lift over rising ground and pull in under cave roofs. */
+export function updateNatureCamera(camera: Camera, yaw: number, map?: NatureMap, player?: Point, dt = 0) {
+  if (!camera.follow) return;
+  const backX = -Math.sin(yaw),
+    backZ = -Math.cos(yaw);
+  let distance = FOLLOW_OFFSET[2],
+    lift = FOLLOW_OFFSET[1];
+  if (map && player) {
+    const floor = groundHeight(map, player.x, player.z),
+      cave = caveAt(map, player.x, player.z);
+    if (cave) lift = 0.65;
+    for (; distance >= 1.5; distance -= 0.25) {
+      let clear = true,
+        requiredLift = lift;
+      for (let sample = 1; sample <= 12; sample++) {
+        const t = sample / 12,
+          x = player.x + backX * distance * t,
+          z = player.z + backZ * distance * t;
+        requiredLift = Math.max(requiredLift, (groundHeight(map, x, z) + 0.6 - floor - HEAD_HEIGHT) / t);
+        const local = toLocal(map, x, z);
+        for (const tunnel of map.landscape.caves) {
+          const dx = Math.abs(local.x - tunnel.x);
+          const within = dx < 5.8 && Math.abs(local.z - tunnel.z) <= tunnel.length / 2 + 0.1;
+          const eyeY = floor + HEAD_HEIGHT + lift * t;
+          if (within && eyeY < tunnel.y + 7 && (dx > 2.8 || eyeY > tunnel.y + 4.7 * Math.sqrt(Math.max(0, 1 - (dx / 3.5) ** 2)) - 0.35))
+            clear = false;
+        }
+        const eyeY = floor + HEAD_HEIGHT + lift * t;
+        if (solidClearance(map.obstacleCells, x, z, 0.35, eyeY - 0.35, eyeY + 0.35) < 0) clear = false;
+      }
+      if (cave && requiredLift > lift + 0.1) clear = false;
+      if (clear) {
+        lift = Math.min(5, requiredLift);
+        break;
+      }
+    }
+  }
+  if (dt > 0) {
+    const previous = camera.follow.offset,
+      previousDistance = Math.hypot(previous[0], previous[2]);
+    const response = distance < previousDistance ? 0.055 : 0.2;
+    distance = previousDistance + (distance - previousDistance) * (1 - Math.exp(-dt / response));
+    lift = previous[1] + (lift - previous[1]) * (1 - Math.exp(-dt / 0.12));
+    if (map && player) {
+      const floor = groundHeight(map, player.x, player.z);
+      lift = Math.max(lift, groundHeight(map, player.x + backX * distance, player.z + backZ * distance) + 0.35 - floor - HEAD_HEIGHT);
+    }
+  }
+  camera.follow.offset = [backX * distance, lift, backZ * distance];
+}
+
+export function resetNatureCamera(camera: Camera, spawn: Point, yaw = 0, map?: NatureMap) {
+  updateNatureCamera(camera, yaw, map, spawn);
+  const y = (map ? groundHeight(map, spawn.x, spawn.z) : 0) + HEAD_HEIGHT;
+  const offset = camera.follow?.offset ?? FOLLOW_OFFSET;
+  camera.target = [spawn.x, y, spawn.z];
+  camera.eye = [spawn.x + offset[0], y + offset[1], spawn.z + offset[2]];
+  camera.shake = 0;
+}
+
+export interface MovementReference {
+  active: boolean;
+  yaw: number;
+}
+
+/**
+ * Use the explorer's facing when a swipe gesture begins. Holding a direction keeps a steady world
+ * heading while the camera turns behind the explorer; recalculating against the rotating view every
+ * frame would turn a held sideways input into an endless spin. Ending the swipe rebases the next gesture to the explorer.
+ */
+export function explorerRelativeInput(input: NatureInput, explorerYaw: number, reference: MovementReference): NatureInput {
+  if (Math.hypot(input.x, input.y) <= MOVEMENT_STOP) {
+    reference.active = false;
+    return input;
+  }
+  if (!reference.active) {
+    reference.yaw = explorerYaw;
+    reference.active = true;
+  }
+  const sin = Math.sin(reference.yaw);
+  const cos = Math.cos(reference.yaw);
+  // The imported explorer faces +Z; his right is local -X (also screen-right from behind).
+  return { ...input, x: -cos * input.x + sin * input.y, y: -sin * input.x - cos * input.y };
+}
+// Footstep cadence.
+
+type FootstepSound = 'footstepWalk' | 'footstepRun';
+
+interface FootstepPlayback {
+  play: (name: FootstepSound, options: { volume: number; pitch: number; pan: number }) => Voice | null;
+  stop: (voice: Voice | null) => void;
+}
+
+interface FootstepMotion {
+  animation: HumanAnimation | null;
+  from: number;
+  to: number;
+  speed: number;
+  audible: boolean;
+}
+
+// Heel/forefoot landings in the imported CMU gait cycles, rather than an independent timer.
+const CONTACTS = { walk: [0.44, 0.94], run: [0.22, 0.72] } as const;
+
+/** One short native voice per landing. No timers, loop gaps or delayed playback after stopping. */
+export function createFootsteps(playback: FootstepPlayback) {
+  let voice: Voice | null = null;
+  let cooldown = 0;
+  let variation = 0;
+  const stop = () => {
+    playback.stop(voice);
+    voice = null;
+    cooldown = 0;
+  };
+  return {
+    stop,
+    update(motion: FootstepMotion, dt: number) {
+      cooldown = Math.max(0, cooldown - Math.max(0, Math.min(0.05, dt)));
+      const { animation, from, to, speed, audible } = motion;
+      if (!audible || speed < 0.15 || (animation !== 'walk' && animation !== 'run')) {
+        stop();
+        return;
+      }
+      if (from === to || cooldown > 0) return;
+      const contact = CONTACTS[animation].findIndex((phase) => (from < to ? phase > from && phase <= to : phase > from || phase <= to));
+      if (contact < 0) return;
+      playback.stop(voice);
+      const running = animation === 'run';
+      voice = playback.play(running ? 'footstepRun' : 'footstepWalk', {
+        volume: (running ? 0.5 : 0.35) * Math.min(1, speed / (running ? 4 : 1.6)),
+        pitch: [0.97, 1.02, 1, 1.04][variation++ % 4]!,
+        pan: contact === 0 ? -0.06 : 0.06
+      });
+      // Avoid double impacts when switching gaits near a landing.
+      cooldown = 0.17;
+    }
+  };
+}

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

@@ -0,0 +1,402 @@
+import { audio, type Camera, effects, type Entity, haptics, warmUpEngine, World } from '@nayan-ui/engine';
+import { playBankSound } from '../../services/SoundsService';
+import { popAndBurst } from '../shared/EngineBlasts';
+// Treasure Hunt: Run lifecycle, engine updates and gameplay feedback.
+import {
+  ATTACK_COOLDOWN,
+  type GameAssets,
+  HUMAN_CAMERA_HEIGHT,
+  HUMAN_CLIP_TIME,
+  HUMAN_GUARD_TIME,
+  locomotionAnimation,
+  MAX_HEALTH,
+  sounds
+} from './TreasureHuntConstants';
+import {
+  createFootsteps,
+  createNatureCamera,
+  createSwipeInput,
+  explorerRelativeInput,
+  type MovementReference,
+  resetNatureCamera,
+  resetSwipe,
+  sampleSwipe,
+  type SwipeInput,
+  updateNatureCamera
+} from './TreasureHuntControls';
+import { advanceHuman, type Human, placeHuman, playHuman, resetHuman, spawnHuman } from './TreasureHuntModel';
+import { createState, groundHeight, type NatureEvent, type NatureInput, type NatureState, peekNextMap, step, warmNextMap } from './TreasureHuntRules';
+import {
+  animateNature,
+  type NatureVisual,
+  placeRobot,
+  type RobotVisual,
+  spawnGem,
+  spawnNature,
+  spawnRobot,
+  warmMapScenery
+} from './TreasureHuntScene';
+
+// Run lifecycle and engine updates.
+
+export interface NatureGame {
+  readonly phase: 'ready' | 'playing' | 'over';
+  readonly score: number;
+  readonly won: boolean;
+  onPhase: (phase: 'ready' | 'playing' | 'over') => void;
+  world: World;
+  assets: GameAssets;
+  camera: Camera;
+  movementReference: MovementReference;
+  nature: NatureVisual;
+  state: NatureState;
+  human: Human;
+  footsteps: ReturnType<typeof createFootsteps>;
+  swipe: SwipeInput;
+  attackBuffer: number;
+  enemies: Map<number, RobotVisual>;
+  gems: Map<number, Entity>;
+  animationTime: number;
+  combatTime: number;
+  hudTime: number;
+  nextRun: Iterator<() => void> | null;
+  preparing: boolean;
+  prepareDelay: number;
+  onChange: () => void;
+}
+
+export function createGame(assets: GameAssets): NatureGame {
+  warmUpEngine();
+  const world = new World(6500);
+  try {
+    const state = createState();
+    const nature = spawnNature(world, state.map, assets);
+    const human = spawnHuman(world, [state.player.x, groundHeight(state.map, state.player.x, state.player.z), state.player.z], assets.human);
+    const cameraTarget = world.spawn({ mesh: 'none', parent: human.root, position: [0, HUMAN_CAMERA_HEIGHT, 0], pickable: false });
+    const game: NatureGame = {
+      get phase() {
+        return this.state.phase === 'ready' ? 'ready' : this.state.phase === 'won' || this.state.phase === 'lost' ? 'over' : 'playing';
+      },
+      get score() {
+        return this.state.score;
+      },
+      get won() {
+        return this.state.phase === 'won';
+      },
+      onPhase: () => {},
+      world,
+      assets,
+      camera: createNatureCamera(cameraTarget, state.player, state.yaw, state.map),
+      movementReference: { active: false, yaw: state.yaw },
+      nature,
+      state,
+      human,
+      footsteps: createFootsteps({ play: (name, options) => playBankSound(sounds, name, options) ?? null, stop: (voice) => audio.stop(voice) }),
+      swipe: createSwipeInput(),
+      attackBuffer: 0,
+      enemies: new Map(),
+      gems: new Map(),
+      animationTime: 0,
+      combatTime: 0,
+      hudTime: 0,
+      nextRun: null,
+      preparing: false,
+      prepareDelay: 0.3,
+      onChange: () => {}
+    };
+    rebuildActors(game);
+    game.nextRun = warmNextRun()[Symbol.iterator]();
+    return game;
+  } catch (error) {
+    world.dispose();
+    throw error;
+  }
+}
+
+function rebuildActors(game: NatureGame) {
+  clearInput(game);
+  game.footsteps.stop();
+  for (const robot of game.enemies.values()) game.world.despawn(robot.root);
+  for (const gem of game.gems.values()) game.world.despawn(gem);
+  game.enemies.clear();
+  game.gems.clear();
+  for (const enemy of game.state.enemies)
+    game.enemies.set(enemy.id, spawnRobot(game.world, enemy.x, groundHeight(game.state.map, enemy.x, enemy.z), enemy.z));
+  syncGems(game);
+  resetHuman(game.world, game.human);
+  placeHuman(game.world, game.human, game.state.map, game.state.player, game.state.yaw);
+  game.animationTime = 0;
+  game.combatTime = 0;
+  game.movementReference.active = false;
+  resetNatureCamera(game.camera, game.state.player, game.state.yaw, game.state.map);
+}
+
+function syncGems(game: NatureGame) {
+  for (const gem of game.state.pickups)
+    if (!gem.taken && !game.gems.has(gem.id)) game.gems.set(gem.id, spawnGem(game.world, gem.x, groundHeight(game.state.map, gem.x, gem.z), gem.z));
+}
+
+export function start(game: NatureGame) {
+  if (game.world.isDisposed || game.preparing || game.state.phase !== 'ready') return;
+  game.state.phase = 'playing';
+  game.prepareDelay = 0.3;
+  clearInput(game);
+  game.onPhase('playing');
+  game.onChange();
+}
+
+export function reset(game: NatureGame) {
+  if (game.world.isDisposed || game.preparing) return;
+  // Report/controls change immediately. A rapid Stop must never finish a cold terrain factory
+  // on the input callback; the existing frame loop finishes preparation behind the game loader.
+  clearInput(game);
+  game.footsteps.stop();
+  resetHuman(game.world, game.human);
+  if (!game.nextRun && !peekNextMap()) game.nextRun = warmNextRun()[Symbol.iterator]();
+  game.preparing = true;
+  game.prepareDelay = 0;
+  game.state.phase = 'ready';
+  game.state.score = game.state.gems = game.state.defeated = 0;
+  game.state.health = MAX_HEALTH;
+  game.onPhase('ready');
+  game.onChange();
+}
+
+function commitReset(game: NatureGame) {
+  game.nextRun?.return?.();
+  game.nextRun = null;
+  game.state = createState();
+  game.world.despawn(game.nature.root);
+  game.nature = spawnNature(game.world, game.state.map, game.assets);
+  rebuildActors(game);
+  game.hudTime = 0;
+  game.preparing = false;
+  game.prepareDelay = 0.3;
+  game.nextRun = warmNextRun()[Symbol.iterator]();
+  game.onPhase('ready');
+  game.onChange();
+}
+
+/** Advance one preparation batch per existing engine frame, including the idle Start screen. */
+function* warmNextRun(): Iterable<() => void> {
+  yield* warmNextMap();
+  const map = peekNextMap();
+  if (map) yield* warmMapScenery(map);
+}
+
+function prepareNextRun(game: NatureGame, dt: number) {
+  if (!game.nextRun || dt <= 0) return;
+  game.prepareDelay = Math.max(0, game.prepareDelay - dt);
+  if (game.prepareDelay > 0) return;
+  const deadline = performance.now() + 4;
+  for (let jobs = 0; jobs < 32 && game.nextRun; jobs++) {
+    const task = game.nextRun.next();
+    if (task.done) {
+      game.nextRun = null;
+      if (game.preparing) commitReset(game);
+      break;
+    }
+    task.value();
+    if (performance.now() >= deadline) break;
+  }
+}
+
+function feedback(game: NatureGame, event: NatureEvent) {
+  const { world, human } = game;
+  const y = groundHeight(game.state.map, event.x, event.z);
+  const position = [event.x, y + 0.9, event.z] as const;
+  switch (event.kind) {
+    case 'attack': {
+      const ready =
+        human.animation === 'combatIdle' || human.animation === 'punchStart' || human.animation === 'punchRight' || human.animation === 'punchLeft';
+      if (!ready) human.strikes = 0;
+      const animation = !ready ? 'punchStart' : human.strikes % 2 === 0 ? 'punchRight' : 'punchLeft';
+      human.strikes++;
+      playHuman(world, human, animation);
+      game.combatTime = HUMAN_GUARD_TIME;
+      game.animationTime = HUMAN_CLIP_TIME.punchRight;
+      playBankSound(sounds, 'punch', { volume: 0.35, pitch: 1.2 });
+      break;
+    }
+    case 'hit':
+    case 'defeated': {
+      playBankSound(sounds, event.kind === 'defeated' ? 'defeat' : 'impact', { volume: 0.5 });
+      const towardX = game.state.player.x - event.x,
+        towardZ = game.state.player.z - event.z;
+      const length = Math.hypot(towardX, towardZ) || 1;
+      effects.sparks(world, {
+        position: [event.x + (towardX / length) * 0.2, y + 1.45, event.z + (towardZ / length) * 0.2],
+        colors: [
+          [1.8, 0.65, 0.4, 1],
+          [1, 1.5, 2, 1]
+        ],
+        count: 12,
+        size: 0.1,
+        speed: 4,
+        lifetime: 0.3
+      });
+      haptics.impact(event.kind === 'defeated' ? 0.8 : 0.45);
+      if (event.kind === 'defeated' && event.id !== undefined) {
+        const robot = game.enemies.get(event.id);
+        if (robot) {
+          game.enemies.delete(event.id);
+          void popAndBurst(
+            world,
+            robot.root,
+            { scale: 1, color: [1, 0.4, 0.48, 1], duration: 0.3 },
+            { position, size: 1.2, color: [1, 0.4, 0.48, 1] }
+          ).then(() => world.despawn(robot.root));
+        }
+      }
+      break;
+    }
+    case 'gem': {
+      const gem = event.id === undefined ? undefined : game.gems.get(event.id);
+      if (gem !== undefined) {
+        // Keep a shrinking pickup in the map until it is despawned, so reset also cleans it up.
+        void popAndBurst(
+          world,
+          gem,
+          { scale: 0.7, color: [0.92, 1.02, 1.12, 1], duration: 0.2 },
+          { position, size: 0.6, color: [0.92, 1.02, 1.12, 1], count: 7 }
+        ).then(() => {
+          world.despawn(gem);
+          if (game.gems.get(event.id!) === gem) game.gems.delete(event.id!);
+        });
+      }
+      playBankSound(sounds, 'gem', { volume: 0.55 });
+      haptics.selection();
+      break;
+    }
+    case 'hurt':
+      playHuman(world, human, 'hit');
+      game.animationTime = HUMAN_CLIP_TIME.hit;
+      game.camera.shake = 0.25;
+      playBankSound(sounds, 'hurt', { volume: 0.5 });
+      haptics.impact(0.9);
+      break;
+    case 'won':
+      game.state.yaw = 0;
+      playHuman(world, human, 'celebrate');
+      effects.confetti(world, {
+        position: [event.x, y + 2, event.z],
+        colors: [
+          [0.4, 1.5, 1.8, 1],
+          [1.8, 1.2, 0.3, 1],
+          [1.5, 0.4, 0.8, 1]
+        ],
+        size: 0.17,
+        speed: 6,
+        count: 60,
+        lifetime: 2,
+        gravity: -3
+      });
+      playBankSound(sounds, 'win');
+      haptics.notify('success');
+      game.onPhase('over');
+      break;
+    case 'lost':
+      playHuman(world, human, 'fall');
+      haptics.notify('error');
+      game.onPhase('over');
+      break;
+  }
+}
+
+export function clearInput(game: NatureGame) {
+  resetSwipe(game.swipe);
+  game.attackBuffer = 0;
+}
+
+export function punch(game: NatureGame) {
+  if (game.state.phase === 'playing') game.attackBuffer = ATTACK_COOLDOWN + 0.1;
+}
+
+/** Shared screen frame callback: sample gestures and consume at most one buffered punch. */
+export function update(game: NatureGame, dt: number) {
+  const elapsed = Math.max(0, Math.min(0.05, dt));
+  const buffered = game.attackBuffer > 0;
+  const canPunch = elapsed > 0 && game.state.phase === 'playing' && game.state.attackCooldown <= elapsed;
+  const movement = sampleSwipe(game.swipe, elapsed);
+  tick(game, { x: movement.x, y: movement.y, attack: buffered }, dt);
+  game.attackBuffer = buffered && canPunch ? 0 : Math.max(0, game.attackBuffer - elapsed);
+}
+
+/** Called exclusively by GameView, which also suspends frames on AppState changes. */
+export function tick(game: NatureGame, input: NatureInput, elapsed: number) {
+  if (game.world.isDisposed) return;
+  const dt = Math.min(0.05, Math.max(0, elapsed));
+  if (game.preparing) {
+    game.world.update(0);
+    if (!game.nextRun && dt > 0) commitReset(game);
+    else prepareNextRun(game, dt);
+    if (!game.preparing) game.world.update(0);
+    return;
+  }
+  const events = step(game.state, explorerRelativeInput(input, game.state.yaw, game.movementReference), dt);
+  const { state, world } = game;
+  for (const event of events) feedback(game, event);
+  updateNatureCamera(game.camera, state.yaw, state.map, state.player, dt);
+  syncGems(game);
+  game.animationTime = Math.max(0, game.animationTime - dt);
+  game.combatTime = Math.max(0, game.combatTime - dt);
+  if (state.phase === 'playing' && game.animationTime === 0) {
+    if (game.combatTime > 0 && state.speed < 0.05) playHuman(world, game.human, 'combatIdle');
+    else if (game.human.animation === 'combatIdle' && state.speed < 0.05) {
+      playHuman(world, game.human, 'combatExit');
+      game.animationTime = HUMAN_CLIP_TIME.combatExit;
+      game.human.strikes = 0;
+    } else {
+      const animation = locomotionAnimation(state.speed, game.human.animation);
+      playHuman(world, game.human, animation, animation === 'run' ? state.speed / 4 : animation === 'walk' ? state.speed / 1.6 : 1);
+    }
+  }
+  const updates = world.transforms;
+  placeHuman(world, game.human, state.map, state.player, state.yaw, dt, updates);
+  for (const enemy of state.enemies) {
+    const visual = game.enemies.get(enemy.id);
+    if (visual)
+      placeRobot(
+        world,
+        visual,
+        enemy.x,
+        enemy.z,
+        groundHeight(state.map, enemy.x, enemy.z),
+        enemy.yaw,
+        enemy.windup,
+        enemy.stagger,
+        enemy.moving,
+        state.time,
+        updates
+      );
+  }
+  updates.flush();
+  animateNature(world, game.nature, dt);
+  const previousPhase = game.human.phase;
+  world.update(dt);
+  advanceHuman(game.human, dt);
+  game.footsteps.update(
+    {
+      animation: game.human.animation,
+      from: previousPhase,
+      to: game.human.phase,
+      speed: state.speed,
+      audible: state.phase === 'playing' && !audio.muted
+    },
+    dt
+  );
+  game.hudTime += dt;
+  if (events.length || game.hudTime >= 0.12) {
+    game.hudTime = 0;
+    game.onChange();
+  }
+  prepareNextRun(game, dt);
+}
+
+export function dispose(game: NatureGame) {
+  clearInput(game);
+  game.nextRun?.return?.();
+  game.nextRun = null;
+  game.footsteps.stop();
+  game.world.dispose();
+}