@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/tile-home/TileHomeScene.ts

@@ -0,0 +1,154 @@
+// Everything Tile Home draws. Orthographic camera, one world unit per point, looking down -z: x right
+// and y up from the view's centre. Each tile is an invisible root at its centre carrying its body (a
+// rounded raised block shared with Candy Crush), its 3D fruit and its "covered" shade. Layers
+// sit far enough apart in depth that a tile always draws over the fruit of the tile under it.
+import { type Entity, extrude, type Geometry, type Model, Path, type Vec3, type World } from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import { spawnBackdrop } from '../shared/EngineBackdrop';
+import { spawnRaisedBlock } from '../shared/EngineBlocks';
+import type { Fruit, FruitKind } from '../shared/EngineFruits';
+import { cacheGameAsset, createGameMesh as createShape } from '../shared/EngineMeshes';
+import { toColor } from '../shared/EngineUtils';
+import {
+  CLASSIC_BOARD,
+  CLASSIC_SLOT,
+  CLASSIC_SLOT_BORDER,
+  CLASSIC_TRAY,
+  CLASSIC_TRAY_BORDER,
+  type Layout,
+  SLOT_CAPACITY,
+  slotOrigin,
+  TILE_FACE,
+  TILE_THICKNESS
+} from './TileHomeConstants';
+
+// Depth, toward the camera (the camera sits at 500 and sees 500 deep)
+export const Z_BACKDROP = 1;
+const Z_PANELS = 4;
+const Z_LAYER = 120; // between board layers: more than a fruit is deep
+const Z_TILE_BASE = 20;
+export const Z_FLYING = 420;
+const FRUIT_LIFT = 32; // the fruit's centre above its tile's face
+const SHADE_LIFT = 70; // the covered shade, over the fruit
+
+export const layerZ = (layer: number) => Z_TILE_BASE + layer * Z_LAYER;
+export const trayZ = Z_TILE_BASE;
+
+/** A view point (from the top-left) at depth `z`, in world space. */
+export const toWorld = (l: Layout, x: number, y: number, z = 0): Vec3 => [x - l.width / 2, l.height / 2 - y, z];
+
+// ── Meshes (made once per size: mesh ids are app-wide and limited) ────
+
+const meshes = new Map<string, Model>();
+const cached = (key: string, build: () => Model) => {
+  let m = meshes.get(key);
+  if (!m) {
+    m = cacheGameAsset('tile-home/TileHomeScene:' + key, build);
+    meshes.set(key, m);
+  }
+  return m;
+};
+
+type Rgb = [number, number, number];
+/** Flat geometry for a path drawn in points (y down), each vertex painted by `paint(x, y)`, at depth z. */
+function flatLayer(path: Path, z: number, paint: (x: number, y: number) => Rgb): Geometry {
+  const g = extrude(path, { depth: 0, fillRule: 'evenodd' });
+  const v = g.vertices;
+  for (let i = 0; i < v.length; i += 11) {
+    const [r, gr, b] = paint(v[i]!, -v[i + 1]!);
+    v[i + 2] = z;
+    v[i + 6] = r;
+    v[i + 7] = gr;
+    v[i + 8] = b;
+  }
+  return g;
+}
+
+const shadeMesh = (t: number) =>
+  cached(`shade:${t}`, () =>
+    createShape(
+      flatLayer(new Path().addRoundedRect(0, 0, t, t, 8), 0, () => [1, 1, 1]),
+      { center: false }
+    )
+  );
+/** A flat rounded rectangle from its top-left; with `rim`, only its outline. */
+const panelMesh = (w: number, h: number, r: number, rim = 0) =>
+  cached(`panel:${w}:${h}:${r}:${rim}`, () => {
+    const path = new Path().addRoundedRect(0, 0, w, h, r);
+    if (rim > 0) path.addRoundedRect(rim, rim, w - rim * 2, h - rim * 2, r - rim);
+    return createShape(
+      flatLayer(path, 0, () => [1, 1, 1]),
+      { center: false }
+    );
+  });
+
+// ── Board and tray ────────────────────────────────────────────────────
+
+export type Scenery = Entity[];
+
+/** The background, the board panel and the tray with its empty slots, for a theme. */
+export function buildScenery(world: World, l: Layout, theme: GameTheme): Scenery {
+  const classic = theme.mode === 'classic';
+  const out: Entity[] = [spawnBackdrop(world, l.width, l.height, Z_BACKDROP, theme)];
+  const panel = (x: number, y: number, w: number, h: number, r: number, color: string, rim = 0, z = Z_PANELS) =>
+    out.push(world.spawn({ mesh: panelMesh(w, h, r, rim), position: toWorld(l, x, y, z), color: toColor(color), pickable: false }));
+
+  const boardRadius = classic ? 16 : 8;
+  panel(l.boardLeft, l.boardTop, l.boardWidth, l.boardHeight, boardRadius, classic ? CLASSIC_BOARD : theme.BOARD.SURFACE);
+  if (!classic) panel(l.boardLeft, l.boardTop, l.boardWidth, l.boardHeight, boardRadius, theme.BOARD.BORDER, 1, Z_PANELS + 0.2);
+
+  const trayRadius = classic ? 12 : 8;
+  panel(l.trayLeft, l.trayTop, l.trayWidth, l.trayHeight, trayRadius, classic ? CLASSIC_TRAY : theme.BOARD.SURFACE);
+  panel(l.trayLeft, l.trayTop, l.trayWidth, l.trayHeight, trayRadius, classic ? CLASSIC_TRAY_BORDER : theme.BOARD.BORDER, 1, Z_PANELS + 0.2);
+  for (let i = 0; i < SLOT_CAPACITY; i++) {
+    const [x, y] = slotOrigin(l, i);
+    panel(x, y, l.slot, l.slot, 8, classic ? CLASSIC_SLOT : theme.BOARD.CELL_EMPTY, 0, Z_PANELS + 0.4);
+    panel(x, y, l.slot, l.slot, 8, classic ? CLASSIC_SLOT_BORDER : theme.BOARD.BORDER, 1.5, Z_PANELS + 0.6);
+  }
+  return out;
+}
+
+// ── Tiles ─────────────────────────────────────────────────────────────
+
+export type TileEntities = { root: Entity; shade: Entity; fruit: Entity | null; /** Body and fruit, for the match flash. */ parts: Entity[] };
+
+/**
+ * A tile at view point (cx, cy) (its centre), depth z: body, fruit and a hidden shade. Without its
+ * fruit model yet (still being built), the tile shows straight away and the fruit is added later.
+ */
+export function spawnTile(world: World, l: Layout, fruit: Fruit | undefined, cx: number, cy: number, z: number, scale: number): TileEntities {
+  const t = l.tile;
+  const corner: Vec3 = [-t / 2, t / 2, 0]; // children are drawn from the tile's top-left
+  const depth = t * TILE_THICKNESS;
+  const root = world.spawn({ mesh: 'none', position: toWorld(l, cx, cy, z), scale, pickable: false });
+  // The face sits at the root's depth (the fruit and shade are placed from it); the body runs back from it.
+  const body = spawnRaisedBlock(world, {
+    parent: root,
+    position: [0, 0, -depth / 2],
+    size: [t, t, depth],
+    color: toColor(TILE_FACE),
+    gloss: false,
+    shadow: false
+  });
+  const shade = world.spawn({ mesh: shadeMesh(t), parent: root, position: [corner[0], corner[1], SHADE_LIFT], color: [0, 0, 0, 0], pickable: false });
+  const fruitEntity = fruit ? addTileFruit(world, l, root, fruit, false) : null;
+  return { root, shade, fruit: fruitEntity, parts: fruitEntity == null ? [body] : [body, fruitEntity] };
+}
+
+/** Puts `fruit` on a tile's face (filling it, centred on its bounding box, a point above the middle like the original icon); `pop` springs it in. */
+export function addTileFruit(world: World, l: Layout, root: Entity, fruit: Fruit, pop: boolean): Entity {
+  const s = l.fruit / Math.max(fruit.whole.size[0], fruit.whole.size[1]);
+  const e = world.spawn({
+    mesh: fruit.whole,
+    parent: root,
+    position: [-fruit.center[0] * s, 1 - fruit.center[1] * s, FRUIT_LIFT - fruit.center[2] * s],
+    scale: pop ? 0 : s,
+    color: [1, 1, 1, 1],
+    pickable: false
+  });
+  if (pop) world.animate(e, { scale: s }, { duration: 0.22, easing: 'back' });
+  return e;
+}
+
+/** The fruit models built so far (they arrive one kind at a time). */
+export type FruitModels = Partial<Record<FruitKind, Fruit>>;

package/src/games/treasure-hunt/TreasureHunt.tsx

@@ -0,0 +1,206 @@
+// Treasure Hunt: Shared screen, minimap and swipe surface.
+import { memo, useCallback, useEffect, useMemo, useState } from 'react';
+import { StyleSheet, View } from 'react-native';
+import { haptics } from '@nayan-ui/engine';
+import { GAME_SOUNDS } from '../../services/SoundsService';
+import { GAME_IDS, type GameProps } from '../../services/UtilsService';
+import { engineGame, EngineGameScreen } from '../shared/EngineGameScreen';
+import { getSceneInputInsets, livesColumn, scoreColumn, textColumn } from '../shared/EngineHud';
+import { type EngineContact, EngineTouchSurface } from '../shared/EngineTouchSurface';
+import { GameLoading } from '../shared/GameLoading';
+import { GameLoadingTransition } from '../shared/GameLoadingTransition';
+import { useEngineGame } from '../shared/useEngineGame';
+import { useLiveState } from '../shared/useLiveState';
+import {
+  ENEMY_COUNT,
+  type GameAssets,
+  GEM_GOAL,
+  getCachedAssets,
+  loadAssets,
+  MAX_HEALTH,
+  MINIMAP_SIZE,
+  NATURE_LIGHT,
+  NIGHT_LIGHT,
+  NIGHT_SKY,
+  SKY
+} from './TreasureHuntConstants';
+import { endSwipe, moveSwipe, resetSwipe, startSwipe, type SwipeInput } from './TreasureHuntControls';
+import { clearInput, createGame, dispose, punch, reset, start, update } from './TreasureHuntGame';
+import { type NatureState } from './TreasureHuntRules';
+import { drawMiniMap } from './TreasureHuntScene';
+
+// Shared game screen.
+
+type RunProps = GameProps & { settings: NonNullable<GameProps['settings']>; assets: GameAssets };
+
+const Run = memo(function TreasureHuntRun(props: RunProps) {
+  const { settings } = props;
+  const [hud, setHud] = useLiveState<HudState | null>(null, 0);
+  const [error, setError] = useState<string | null>(null);
+  const { game, theme, phase, status, screen, gameOver } = useEngineGame(props, {
+    gameId: GAME_IDS.TREASURE_HUNT,
+    create: () => createGame(props.assets),
+    start,
+    reset,
+    dispose,
+    tick: update,
+    hud: (g, hud) => drawMiniMap(hud, g.state),
+    resultsDelay: (result) => (result === 'win' ? 1500 : 1200),
+    reportData: (g) => ({ gems: g.state.gems, defeated: g.state.defeated, seconds: Math.floor(g.state.time) }),
+    sounds: GAME_SOUNDS.TREASURE_HUNT,
+    onStart: (fx) => fx(GAME_SOUNDS.TREASURE_HUNT.START),
+    onOver: (fx, result) => {
+      if (result !== 'win') fx(GAME_SOUNDS.TREASURE_HUNT.LOSE);
+    },
+    wire: (g) => {
+      g.onChange = () => setHud({ ...snapshot(g.state), preparing: g.preparing });
+      g.onChange();
+    }
+  });
+
+  useEffect(() => {
+    haptics.enabled = settings.enableHaptics;
+  }, [settings.enableHaptics]);
+  useEffect(
+    () => () => {
+      haptics.enabled = true;
+    },
+    []
+  );
+
+  const onAudioChange = useCallback(
+    (audible: boolean) => {
+      if (audible) return;
+      clearInput(game);
+      game.footsteps.stop();
+      game.movementReference.active = false;
+    },
+    [game]
+  );
+
+  const onTap = useCallback(() => punch(game), [game]);
+  const onError = useCallback((failure: Error) => setError(failure.message), []);
+  const inputInsets = useMemo(() => getSceneInputInsets(settings.offset), [settings.offset]);
+  const night = theme.mode === 'dark';
+  const preparing = game.preparing;
+  const loading = preparing && !!game.nextRun;
+  const playing = phase === 'playing' && !preparing;
+
+  return (
+    <EngineGameScreen
+      {...screen}
+      onStart={() => {
+        if (!game.preparing) screen.onStart();
+      }}
+      hudCapacity={MINIMAP_SIZE * MINIMAP_SIZE + 1024}
+      light={night ? NIGHT_LIGHT : NATURE_LIGHT}
+      background={night ? NIGHT_SKY : SKY}
+      fog={0.006}
+      errorMessage={error ?? undefined}
+      onAudioChange={onAudioChange}
+      onError={onError}
+      columns={[
+        scoreColumn(hud?.score ?? 0),
+        livesColumn(hud?.health ?? MAX_HEALTH, MAX_HEALTH, 'HEALTH'),
+        textColumn('GEMS', `${hud?.gems ?? 0}/${GEM_GOAL}`),
+        textColumn('ROBOTS', `${hud?.defeated ?? 0}/${ENEMY_COUNT}`)
+      ]}
+      subtext="Swipe to explore · Tap to punch"
+      gameOver={gameOver({
+        title: status === 'win' ? 'FOREST EXPLORED!' : 'EXPEDITION OVER',
+        message: `${hud?.gems ?? 0} diamonds found and ${hud?.defeated ?? 0} robots defeated.`,
+        scoreLabel: 'Adventure score',
+        score: hud?.score ?? 0,
+        buttonText: 'Explore Again!'
+      })}>
+      <SwipeNavigation input={game.swipe} enabled={playing && !settings.isVisible && !error} onTap={onTap} insets={inputInsets} />
+      <View pointerEvents={loading ? 'auto' : 'none'} style={StyleSheet.absoluteFill}>
+        <GameLoadingTransition
+          ready={!loading}
+          loader={<GameLoading gameId={GAME_IDS.TREASURE_HUNT} theme={settings.theme} offset={settings.offset} visible={!settings.isVisible} />}>
+          {null}
+        </GameLoadingTransition>
+      </View>
+    </EngineGameScreen>
+  );
+});
+
+/** Shared Playtura chrome and lifecycle around the imported explorer and procedural wilderness. */
+export const TreasureHunt = engineGame(GAME_IDS.TREASURE_HUNT, (props) => {
+  const [assets, setAssets] = useState<GameAssets | null>(getCachedAssets);
+  const [error, setError] = useState<string | null>(null);
+  useEffect(() => {
+    if (assets) return;
+    let alive = true;
+    loadAssets()
+      .then((loaded) => {
+        if (alive) setAssets(loaded);
+      })
+      .catch((failure: unknown) => {
+        if (alive) setError(failure instanceof Error ? failure.message : String(failure));
+      });
+    return () => {
+      alive = false;
+    };
+  }, [assets]);
+  return (
+    <GameLoadingTransition
+      ready={!!assets}
+      loader={
+        <GameLoading
+          gameId={GAME_IDS.TREASURE_HUNT}
+          theme={props.settings.theme}
+          offset={props.settings.offset}
+          error={!!error}
+          message={error ?? undefined}
+        />
+      }>
+      {assets && <Run {...props} assets={assets} />}
+    </GameLoadingTransition>
+  );
+});
+
+// HUD metrics.
+
+interface HudState {
+  preparing?: boolean;
+  health: number;
+  gems: number;
+  defeated: number;
+  score: number;
+}
+function snapshot(state: NatureState): HudState {
+  return { health: state.health, gems: state.gems, defeated: state.defeated, score: state.score };
+}
+
+// Touch surface.
+
+interface SwipeNavigationProps {
+  input: SwipeInput;
+  enabled: boolean;
+  onTap: () => void;
+  insets: { top: number; bottom: number };
+}
+
+const SwipeNavigation = memo(function SwipeNavigation({ input, enabled, onTap, insets }: SwipeNavigationProps) {
+  const onStart = useCallback(
+    (contact: EngineContact) => {
+      startSwipe(input, contact, contact.timeStamp);
+    },
+    [input]
+  );
+  const onMove = useCallback(
+    (contact: EngineContact) => {
+      moveSwipe(input, contact);
+    },
+    [input]
+  );
+  const onEnd = useCallback(
+    (contact: EngineContact) => {
+      if (endSwipe(input, contact, contact.timeStamp) && enabled) onTap();
+    },
+    [input, enabled, onTap]
+  );
+  const onCancel = useCallback(() => resetSwipe(input), [input]);
+  return <EngineTouchSurface enabled={enabled} insets={insets} onStart={onStart} onMove={onMove} onEnd={onEnd} onCancel={onCancel} />;
+});

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

@@ -0,0 +1,266 @@
+// Treasure Hunt: Tuning, animation metadata and cached assets.
+import { type Light, type SoundBank, type Texture } from '@nayan-ui/engine';
+import source from '../../assets/models/explorer/source.json';
+import type { HumanAssets } from './TreasureHuntModel';
+
+// Combat poses and timing.
+/** Shared strike timing and offline skeletal choreography for the imported explorer. */
+export const HUMAN_PUNCH_TIME = 0.52;
+
+export const HUMAN_CONTACT_TIME = 0.16;
+
+export const HUMAN_GUARD_TIME = 1.15;
+
+type Vector = [number, number, number];
+
+interface HandTarget {
+  pos: Vector;
+  pole: Vector;
+  dir: Vector;
+  palm: Vector;
+}
+
+export interface CombatPose {
+  bones: Record<string, Vector>;
+  root: { ground: boolean };
+  ik?: { Left: HandTarget; Right: HandTarget };
+  thumbs?: { Left: number; Right: number };
+  blend?: { sample: CombatPose; w: number };
+}
+
+interface CombatClip {
+  id: string;
+  name: string;
+  category: 'Actions';
+  duration: number;
+  loop: boolean;
+  sample(time: number): CombatPose;
+}
+
+const smooth = (value: number) => {
+  const t = Math.max(0, Math.min(1, value));
+  return t * t * (3 - 2 * t);
+};
+
+function curve(time: number, times: number[], values: number[]) {
+  if (time <= times[0]!) return values[0]!;
+  for (let i = 1; i < times.length; i++)
+    if (time <= times[i]!) {
+      const t = smooth((time - times[i - 1]!) / (times[i]! - times[i - 1]!));
+      return values[i - 1]! + (values[i]! - values[i - 1]!) * t;
+    }
+  return values.at(-1)!;
+}
+
+/** Both hands share a planted stance. Only the striking shoulder, torso and arm change sides. */
+export function fightingPose(hand: 'Left' | 'Right' | null, time: number): CombatPose {
+  const times = [0, 0.075, HUMAN_CONTACT_TIME, 0.185, 0.32, 0.44, HUMAN_PUNCH_TIME];
+  const extension = hand ? curve(time, times, [0, -0.06, 1, 0.96, 0.18, 0, 0]) : 0;
+  const turn = hand ? curve(time, times, [0, -7, 18, 16, 4, 0, 0]) * (hand === 'Right' ? 1 : -1) : 0;
+  const breathing = hand ? 0 : Math.sin((time / 1.3) * Math.PI * 2) * 0.35;
+  const bones: Record<string, Vector> = {
+    Hips: [0, 0, 0],
+    Spine: [3 + Math.max(0, extension) * 5, 0, 0],
+    Spine1: [4 + Math.max(0, extension) * 2 + breathing, turn * 0.65, 0],
+    Spine2: [2 + breathing * 0.5, turn * 0.35, -Math.max(0, extension) * (hand === 'Right' ? -1.5 : 1.5)],
+    Neck: [-2, -turn * 0.3, 0],
+    Head: [-4, -turn * 0.7, 0],
+    LeftUpLeg: [9, 0, 3],
+    RightUpLeg: [-5, 0, -3],
+    LeftLeg: [-14, 0, 0],
+    RightLeg: [-9, 0, 0],
+    LeftFoot: [5, 0, 0],
+    RightFoot: [7, 0, 0]
+  };
+  for (const side of ['Left', 'Right'] as const) {
+    for (const finger of ['Index', 'Middle', 'Ring', 'Pinky']) {
+      bones[`${side}Hand${finger}1`] = [80, 0, 0];
+      bones[`${side}Hand${finger}2`] = [100, 0, 0];
+      bones[`${side}Hand${finger}3`] = [65, 0, 0];
+    }
+    bones[`${side}HandThumb2`] = [45, 0, 0];
+    bones[`${side}HandThumb3`] = [55, 0, 0];
+  }
+  const target = (side: 'Left' | 'Right'): HandTarget => {
+    const sign = side === 'Left' ? 1 : -1,
+      strike = hand === side ? extension : 0;
+    return {
+      pos: [sign * (0.155 - strike * 0.075), 0.015 - Math.max(0, strike) * 0.05, 0.235 + strike * 0.37],
+      pole: [sign * 0.7, -0.65, 0.12],
+      dir: [0, 0.15 * (1 - Math.max(0, strike)), 1],
+      palm: [-sign * (1 - Math.max(0, strike)), -Math.max(0, strike), 0]
+    };
+  };
+  return { bones, root: { ground: true }, ik: { Left: target('Left'), Right: target('Right') }, thumbs: { Left: 1, Right: 1 } };
+}
+
+export function createCombatClips(idle: { sample(time: number): CombatPose }): CombatClip[] {
+  const punch = (side: 'Left' | 'Right', entry = false): CombatClip => ({
+    id: entry ? 'explorer_punch_start' : `explorer_punch_${side.toLowerCase()}`,
+    name: entry ? 'Fight entry punch' : `${side} straight punch`,
+    category: 'Actions',
+    duration: HUMAN_PUNCH_TIME,
+    loop: false,
+    sample: (time) => {
+      const pose = fightingPose(side, time);
+      return entry && time < 0.075 ? { ...pose, blend: { sample: idle.sample(0), w: 1 - smooth(time / 0.075) } } : pose;
+    }
+  });
+  return [
+    punch('Right', true),
+    punch('Right'),
+    punch('Left'),
+    { id: 'explorer_guard', name: 'Boxing guard', category: 'Actions', duration: 1.3, loop: true, sample: (time) => fightingPose(null, time) },
+    {
+      id: 'explorer_guard_exit',
+      name: 'Lower guard',
+      category: 'Actions',
+      duration: 0.18,
+      loop: false,
+      sample: (time) => ({ ...fightingPose(null, 0), blend: { sample: idle.sample(0), w: smooth(time / 0.18) } })
+    }
+  ];
+}
+// Explorer animation clips and cadence.
+
+export const HUMAN_HEIGHT = source.height;
+
+export const HUMAN_CAMERA_HEIGHT = source.cameraHeight;
+
+export const HUMAN_CLIPS = source.clips;
+
+export type HumanAnimation = keyof typeof HUMAN_CLIPS;
+
+export const HUMAN_CLIP_TIME = Object.fromEntries(Object.entries(HUMAN_CLIPS).map(([name, clip]) => [name, clip.duration])) as Record<
+  HumanAnimation,
+  number
+>;
+
+export const HUMAN_LOOPS = new Set<HumanAnimation>((Object.keys(HUMAN_CLIPS) as HumanAnimation[]).filter((name) => HUMAN_CLIPS[name].loop));
+
+/** Hysteresis stops tiny gesture changes from repeatedly switching walk and run. */
+export function locomotionAnimation(speed: number, previous: HumanAnimation | null = null): 'idle' | 'walk' | 'run' {
+  if (speed < 0.05) return 'idle';
+  return speed >= (previous === 'run' ? 3.2 : 3.8) ? 'run' : 'walk';
+}
+
+/** A margin around cadence buckets prevents finger noise from repeatedly rebuilding native tracks. */
+export function locomotionRate(speed: number, previous?: number): number {
+  const bounded = Math.max(0.65, Math.min(1.6, speed));
+  if (previous !== undefined && Math.abs(bounded - previous) < 0.18) return previous;
+  return Math.max(0.65, Math.min(1.6, Math.round(speed * 4) / 4));
+}
+
+// Game tuning and lighting.
+
+export const WORLD_EDGE = 128;
+
+export const TERRAIN_PROFILES = 16;
+export const MINIMAP_SIZE = 124;
+
+export const MAX_HEALTH = 5;
+
+export const GEM_GOAL = 24;
+
+export const POINTS_GEM = 200;
+export const POINTS_ROBOT_HIT = 50;
+export const POINTS_ROBOT_DEFEAT = 300;
+export const POINTS_HEALTH_BONUS = 400;
+
+export const PLAYER_SPEED = 6;
+
+export const PLAYER_RADIUS = 0.5;
+
+export const MOVEMENT_START = 0.08;
+
+export const MOVEMENT_STOP = 0.04;
+
+export const ATTACK_RANGE = 1.9;
+
+export const ATTACK_COOLDOWN = HUMAN_PUNCH_TIME;
+
+export const ATTACK_HIT_TIME = HUMAN_CONTACT_TIME;
+
+export const ENEMY_COUNT = 8;
+
+export const SKY = [0.62, 0.77, 0.86] as const;
+
+export const NATURE_LIGHT: Light = {
+  direction: [-0.55, 0.85, -0.3],
+  ambient: 0.5,
+  shadows: true,
+  shadowExtent: 30,
+  color: [1.15, 1.09, 0.94]
+};
+
+export const NIGHT_SKY = [0.07, 0.13, 0.2] as const;
+
+export const NIGHT_LIGHT: Light = {
+  ...NATURE_LIGHT,
+  ambient: 0.52,
+  color: [0.8, 0.95, 1.08]
+};
+
+export interface Point {
+  x: number;
+  z: number;
+}
+
+// Cached textures, model and sounds, shared by every run.
+export interface NatureAssets {
+  meadow: Texture;
+  stone: Texture;
+  bark: Texture;
+  pine: Texture;
+  leaves: Texture;
+  water: Texture;
+}
+export interface GameAssets extends NatureAssets {
+  human: HumanAssets;
+}
+type SoundName = 'gem' | 'punch' | 'impact' | 'defeat' | 'hurt' | 'win' | 'footstepWalk' | 'footstepRun';
+export let sounds: SoundBank<SoundName> | undefined;
+let assetsLoading: Promise<GameAssets> | undefined;
+let cachedAssets: GameAssets | null = null;
+/** Use fulfilled prepared resources on the first render, without another loading frame. */
+export const getCachedAssets = (): GameAssets | null => cachedAssets;
+/** Load native resources once; tuning and rules remain usable without a native renderer. */
+export function loadAssets(): Promise<GameAssets> {
+  assetsLoading ??= (async () => {
+    const [{ audio, loadTexture }, { loadHumanAssets }] = await Promise.all([import('@nayan-ui/engine'), import('./TreasureHuntModel')]);
+    sounds ??= audio.load({
+      gem: require('../../assets/sfx/coin.wav'),
+      punch: require('../../assets/sfx/swoosh.wav'),
+      impact: require('../../assets/sfx/clang.wav'),
+      defeat: require('../../assets/sfx/boom.wav'),
+      hurt: require('../../assets/sfx/hurt.wav'),
+      win: require('../../assets/sfx/win.wav'),
+      footstepWalk: require('../../assets/sfx/footstep_walk.wav'),
+      footstepRun: require('../../assets/sfx/footstep_run.wav')
+    });
+    // The mixer reports individual decode failures; audio is optional for the visual loader.
+    void sounds.ready.catch(() => {});
+    const [meadow, stone, bark, pine, leaves, water, human] = await Promise.all([
+      loadTexture(require('../../assets/textures/meadow.jpg')),
+      loadTexture(require('../../assets/textures/limestone.jpg')),
+      loadTexture(require('../../assets/textures/bark.jpg')),
+      loadTexture(require('../../assets/textures/pine.png')),
+      loadTexture(require('../../assets/textures/leaves.png')),
+      loadTexture(require('../../assets/textures/river.jpg')),
+      loadHumanAssets()
+    ]);
+    // SoundBank starts loading above and safely ignores voices until ready. It must not hold up
+    // the explorer and landscape; the game loading screen awaits audio after the visual builders.
+    cachedAssets = { meadow, stone, bark, pine, leaves, water, human };
+    return cachedAssets;
+  })().catch((error: unknown) => {
+    assetsLoading = undefined;
+    throw error;
+  });
+  return assetsLoading;
+}
+
+/** Start the explorer and terrain downloads together, without serial idle/network round trips. */
+export function* warmAssets(): Iterable<() => unknown> {
+  yield loadAssets;
+}