@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/pipe-connect/PipeConnectScene.ts

@@ -0,0 +1,271 @@
+// Everything Pipe Connect draws: a board (themed, as the original board) of tiles, each with a chrome pipe
+// piece lying on it (straight, bend, tee or cross, flanged where it opens), a green source tank and an
+// orange drain, seen from a little in front of straight down (shared/EngineTilt: an orthographic camera
+// leaning back, one world unit per point). A tapped pipe swings round a quarter turn; the pipes the
+// water reaches turn water-blue one after another out from the source; a solve pulses them all. Each
+// piece kind is one mesh, so every pipe on the board is an instance of one of six.
+import {
+  type Color,
+  effects,
+  type Entity,
+  extrude,
+  type GeometryPart,
+  lathe,
+  merge,
+  type Model,
+  Path,
+  quat,
+  shapeGeometry,
+  tube,
+  type Vec3,
+  type World
+} from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import { setBackdropTheme, spawnBackdrop } from '../shared/EngineBackdrop';
+import { cacheGameAsset, createGameMesh as createShape } from '../shared/EngineMeshes';
+import { placeTiltedBackdrop } from '../shared/EngineTilt';
+import { toColor } from '../shared/EngineUtils';
+import { cellCentre, COLORS, FLOW_STEP, type Layout, PipeType, TURN_TIME, WIN_STEP } from './PipeConnectConstants';
+import type { PipeCell } from './PipeConnectRules';
+
+const meshes = new Map<string, Model>();
+const cached = (key: string, build: () => Model) => {
+  let m = meshes.get(key);
+  if (!m) {
+    m = cacheGameAsset('pipe-connect/PipeConnectScene:' + key, build);
+    meshes.set(key, m);
+  }
+  return m;
+};
+const STAND_UP = quat.x(Math.PI / 2);
+const BOARD_DEPTH = 10;
+const BACKDROP_DEPTH = 25;
+const TILE_HEIGHT = 3;
+const R = 0.15; // a pipe's radius, of a cell
+const FLANGE: Color = [0.52, 0.56, 0.62, 1];
+
+/** A quarter turn clockwise per rotation step, as seen on the board. */
+export const pieceRotation = (rotation: number) => quat.z((-rotation * Math.PI) / 2);
+
+// ── Pieces (one cell across, lying on the tile, at rotation 0) ────────
+
+type Arm = [number, number]; // a side's direction from the centre
+const UP: Arm = [0, 1];
+const RIGHT: Arm = [1, 0];
+const DOWN: Arm = [0, -1];
+const LEFT: Arm = [-1, 0];
+
+const flange = ([dx, dy]: Arm): GeometryPart => ({
+  geometry: tube(
+    [
+      [dx * 0.4, dy * 0.4, R],
+      [dx * 0.5, dy * 0.5, R]
+    ],
+    { radius: R * 1.3, sides: 16, smoothness: 1 }
+  ),
+  color: FLANGE
+});
+const arm = ([dx, dy]: Arm): GeometryPart => ({
+  geometry: tube(
+    [
+      [0, 0, R],
+      [dx * 0.5, dy * 0.5, R]
+    ],
+    { radius: R, sides: 16, smoothness: 2 }
+  )
+});
+const hub = (): GeometryPart => ({ geometry: shapeGeometry('sphere'), position: [0, 0, R], scale: R * 2.3 });
+
+const PIECES: Partial<Record<PipeType, () => GeometryPart[]>> = {
+  [PipeType.STRAIGHT]: () => [
+    {
+      geometry: tube(
+        [
+          [0, 0.5, R],
+          [0, -0.5, R]
+        ],
+        { radius: R, sides: 16, smoothness: 2 }
+      )
+    },
+    flange(UP),
+    flange(DOWN)
+  ],
+  // A bend from the top round to the right, a quarter circle about the top-right corner
+  [PipeType.CORNER]: () => [
+    {
+      geometry: tube(
+        Array.from({ length: 9 }, (_, i): Vec3 => {
+          const a = Math.PI + (i / 8) * (Math.PI / 2);
+          return [0.5 + 0.5 * Math.cos(a), 0.5 + 0.5 * Math.sin(a), R];
+        }),
+        { radius: R, sides: 16, smoothness: 3 }
+      )
+    },
+    flange(UP),
+    flange(RIGHT)
+  ],
+  [PipeType.T_SHAPE]: () => [arm(UP), arm(DOWN), arm(RIGHT), hub(), flange(UP), flange(DOWN), flange(RIGHT)],
+  [PipeType.CROSS]: () => [arm(UP), arm(DOWN), arm(LEFT), arm(RIGHT), hub(), flange(UP), flange(DOWN), flange(LEFT), flange(RIGHT)]
+};
+
+const pieceMesh = (type: PipeType) =>
+  cached(`pc-${type}`, () => {
+    if (type === PipeType.SOURCE || type === PipeType.SINK) return endMesh(type === PipeType.SOURCE);
+    return createShape(merge(PIECES[type]!()), { center: false, shine: 0.75 });
+  });
+
+/** The source (a tank with a valve wheel) or the sink (a drain funnel), with a stub out of every side. */
+function endMesh(source: boolean): Model {
+  const stubs = [UP, RIGHT, DOWN, LEFT].flatMap((a) => [{ ...arm(a), color: [0.82, 0.85, 0.9, 1] as Color }, flange(a)]);
+  const body: GeometryPart = source
+    ? {
+        geometry: lathe(
+          [
+            [0.001, 0.5],
+            [0.24, 0.49],
+            [0.3, 0.44],
+            [0.32, 0.06],
+            [0.3, 0]
+          ],
+          { segments: 28 }
+        ),
+        rotation: STAND_UP
+      }
+    : {
+        geometry: lathe(
+          [
+            [0.001, 0.14],
+            [0.12, 0.15],
+            [0.18, 0.36],
+            [0.36, 0.42],
+            [0.34, 0.3],
+            [0.26, 0]
+          ],
+          { segments: 28 }
+        ),
+        rotation: STAND_UP
+      };
+  const extra: GeometryPart[] = source
+    ? [
+        {
+          geometry: tube(
+            Array.from({ length: 17 }, (_, i): Vec3 => [Math.cos((i / 16) * Math.PI * 2) * 0.17, Math.sin((i / 16) * Math.PI * 2) * 0.17, 0.56]),
+            { radius: 0.03, sides: 8, smoothness: 2 }
+          ),
+          color: [0.85, 0.15, 0.12, 1]
+        },
+        { geometry: shapeGeometry('cube'), position: [0, 0, 0.53], scale: [0.04, 0.04, 0.07], color: [0.6, 0.6, 0.6, 1] }
+      ]
+    : [{ geometry: shapeGeometry('sphere'), position: [0, 0, 0.15], scale: [0.2, 0.2, 0.02], color: [0.1, 0.06, 0.05, 1] }];
+  return createShape(merge([...stubs, body, ...extra]), { center: false, shine: 0.6 });
+}
+
+const panelMesh = (size: number, radius: number) =>
+  cached(`pc-panel:${size}:${radius}`, () =>
+    createShape(extrude(new Path().addRoundedRect(-size / 2, -size / 2, size, size, radius), { depth: BOARD_DEPTH }), { shine: 0.2 })
+  );
+
+// ── Spawning ──────────────────────────────────────────────────────────
+
+export type Scene = { backdrop: Entity; panel: Entity; tiles: Entity[]; pieces: (Entity | null)[] };
+
+const panelColor = (theme: GameTheme) => toColor(theme.mode === 'classic' ? COLORS.CLASSIC_BOARD : theme.BOARD.SURFACE);
+const tileColor = (theme: GameTheme) => toColor(theme.mode === 'classic' ? COLORS.CLASSIC_CELL : theme.BOARD.CELL_EMPTY);
+const DRY = toColor(COLORS.PIPE);
+const WET = toColor(COLORS.WATER);
+/** A piece's paint: the source green, the sink orange, other pipes steel-blue dry and water-blue wet. */
+export const pieceColor = (cell: PipeCell, wet: boolean): Color =>
+  cell.type === PipeType.SOURCE ? toColor(COLORS.SOURCE) : cell.type === PipeType.SINK ? toColor(COLORS.SINK) : wet ? WET : DRY;
+
+export function buildScene(world: World, l: Layout, theme: GameTheme, grid: PipeCell[][], wet: ReadonlySet<string>): Scene {
+  const backdrop = spawnBackdrop(world, l.width, l.height, -BACKDROP_DEPTH, theme);
+  placeTiltedBackdrop(world, backdrop, l, BACKDROP_DEPTH);
+  const panel = world.spawn({
+    mesh: panelMesh(l.board, theme.mode === 'classic' ? 16 : 8),
+    position: [0, 0, -BOARD_DEPTH / 2],
+    color: panelColor(theme),
+    pickable: false
+  });
+  const tiles: Entity[] = [];
+  const pieces: (Entity | null)[] = [];
+  const tile = tileColor(theme);
+  for (const row of grid)
+    for (const cell of row) {
+      const [x, y] = cellCentre(l, cell.row, cell.col);
+      tiles.push(
+        world.spawn({
+          mesh: 'roundedBox',
+          position: [x, y, TILE_HEIGHT / 2],
+          scale: [l.cell - 2, l.cell - 2, TILE_HEIGHT],
+          color: tile,
+          pickable: false
+        })
+      );
+      pieces.push(
+        cell.type === PipeType.EMPTY
+          ? null
+          : world.spawn({
+              mesh: pieceMesh(cell.type),
+              position: [x, y, TILE_HEIGHT],
+              rotation: pieceRotation(cell.rotation),
+              scale: l.cell,
+              color: pieceColor(cell, wet.has(cell.id)),
+              pickable: false
+            })
+      );
+    }
+  return { backdrop, panel, tiles, pieces };
+}
+
+export function removeScene(world: World, s: Scene) {
+  for (const e of [s.backdrop, s.panel, ...s.tiles, ...s.pieces]) if (e != null) world.despawn(e);
+}
+
+export function setSceneTheme(world: World, l: Layout, s: Scene, theme: GameTheme) {
+  setBackdropTheme(world, s.backdrop, theme);
+  world.set(s.panel, { mesh: panelMesh(l.board, theme.mode === 'classic' ? 16 : 8), color: panelColor(theme) });
+  const tile = tileColor(theme);
+  for (const t of s.tiles) world.set(t, { color: tile });
+}
+
+// ── Motion ────────────────────────────────────────────────────────────
+
+/** A pipe swings a quarter turn clockwise into its new rotation, overshooting a touch. */
+export function turnPiece(world: World, e: Entity, rotation: number) {
+  world.animate(e, { rotation: pieceRotation(rotation) }, { duration: TURN_TIME, easing: 'back' });
+}
+
+/**
+ * The water's reach changed: pipes it now reaches fill one after another out from the source (`order`
+ * is each one's place along the path, `base` the first new one's), and pipes it left drain at once.
+ */
+export function flow(world: World, l: Layout, e: Entity, cell: PipeCell, wet: boolean, order: number, base: number) {
+  if (!wet) {
+    world.animate(e, { color: pieceColor(cell, false) }, { duration: 0.15 });
+    return;
+  }
+  const delay = Math.max(0, order - base) * FLOW_STEP;
+  world.animate(e, { color: pieceColor(cell, true) }, { duration: 0.12, delay });
+  world.animate(e, [{ scale: l.cell * 1.07, at: 0.4 }, { scale: l.cell }], { duration: 0.22, delay });
+}
+
+/** Solved: every pipe the water runs through pulses, out from the source. */
+export function winPulse(world: World, l: Layout, e: Entity, order: number) {
+  world.animate(e, [{ scale: l.cell * 1.12, at: 0.4 }, { scale: l.cell }], { duration: 0.25, delay: order * WIN_STEP });
+}
+
+/** A splash of water at the sink when it fills. */
+export function splash(world: World, l: Layout, row: number, col: number) {
+  const [x, y] = cellCentre(l, row, col);
+  effects.splash(world, {
+    position: [x, y, l.cell * 0.4],
+    count: 24,
+    size: l.cell * 0.09,
+    speed: l.cell * 4,
+    direction: [0, 0, 1],
+    spread: 1.1,
+    lifetime: 0.7,
+    gravity: -l.cell * 9,
+    colors: [toColor('#4FC3F7'), toColor('#81D4FA'), [1, 1, 1, 1]]
+  });
+}

package/src/games/play-with-tua/PlayWithTua.tsx

@@ -0,0 +1,123 @@
+import { memo, useCallback, useEffect, useRef, useState } from 'react';
+import { audio, type LoadedModel, type Voice } from '@nayan-ui/engine';
+import { HapticType } from '../../services/HapticsService';
+import { GAME_SOUNDS, playSoundVoice } from '../../services/SoundsService';
+import { GAME_IDS, type GameProps } from '../../services/UtilsService';
+import { engineGame, EngineGameScreen } from '../shared/EngineGameScreen';
+import { scoreColumn, textColumn } from '../shared/EngineHud';
+import { GameLoading } from '../shared/GameLoading';
+import { GameLoadingTransition } from '../shared/GameLoadingTransition';
+import { useEngineGame } from '../shared/useEngineGame';
+import { useLiveState } from '../shared/useLiveState';
+import { PLAY_WITH_TUA_ACTIONS, PLAY_WITH_TUA_LIGHT, type PlayWithTuaAnimation } from './PlayWithTuaConstants';
+import { createGame, cycleMove, dispose, drag, reset, resize, selectMove, setAudible, setTheme, start, tick } from './PlayWithTuaGame';
+import { getCachedCharacter, loadCharacter } from './PlayWithTuaModel';
+
+const SFX = GAME_SOUNDS.PLAY_WITH_TUA;
+
+interface RunProps extends GameProps {
+  settings: NonNullable<GameProps['settings']>;
+  model: LoadedModel;
+}
+const Run = memo(function PlayWithTuaRun(props: RunProps) {
+  const [score, setScore] = useLiveState(0, 0);
+  const [move, setMove] = useLiveState<PlayWithTuaAnimation>('standing', 0);
+  const settingsRef = useRef(props.settings);
+  settingsRef.current = props.settings;
+  const { game, screen } = useEngineGame(props, {
+    gameId: GAME_IDS.PLAY_WITH_TUA,
+    create: (initialTheme) => createGame(props.model, initialTheme),
+    start,
+    reset,
+    dispose,
+    tick,
+    resize,
+    drag,
+    setTheme,
+    sounds: SFX,
+    reportData: (g) => ({ action: g.move, moves: g.score }),
+    wire: (g, feedback) => {
+      const voices: Voice[] = [];
+      g.onSilence = () => {
+        for (const voice of voices) audio.stop(voice);
+        voices.length = 0;
+      };
+      g.onSound = (cue) => {
+        const settings = settingsRef.current;
+        const voice = playSoundVoice(SFX[cue.sound], g.audible && settings.enableSounds && !settings.isVisible);
+        if (voice != null) {
+          voices.push(voice);
+          if (voices.length > 12) audio.stop(voices.shift());
+        }
+      };
+      g.onScore = setScore;
+      g.onMove = (action) => {
+        setMove(action);
+        if (g.phase === 'playing') feedback(action === 'standing' ? SFX.STANDING : null, HapticType.LIGHT);
+      };
+      return () => g.onSilence();
+    },
+    onStart: (feedback) => feedback(SFX.START, HapticType.LIGHT)
+  });
+  const onAudioChange = useCallback((audible: boolean) => setAudible(game, audible), [game]);
+  const choose = (action: PlayWithTuaAnimation) => {
+    if (props.settings.isVisible) return;
+    if (game.phase === 'ready') screen.onStart();
+    selectMove(game, action);
+  };
+  return (
+    <EngineGameScreen
+      {...screen}
+      light={PLAY_WITH_TUA_LIGHT}
+      quality="auto"
+      onAudioChange={onAudioChange}
+      gameOver={null}
+      onTap={() => {
+        if (game.phase === 'ready') screen.onStart();
+        cycleMove(game);
+      }}
+      columns={[scoreColumn(score, 'MOVES'), textColumn('ACTION', PLAY_WITH_TUA_ACTIONS.find((action) => action.id === move)!.label)]}
+      subtext="Tap for next action · Drag to rotate"
+      choices={PLAY_WITH_TUA_ACTIONS.map((action) => ({
+        id: action.id,
+        label: action.label,
+        selected: action.id === move,
+        onPress: () => choose(action.id)
+      }))}
+    />
+  );
+});
+
+export const PlayWithTua = engineGame(GAME_IDS.PLAY_WITH_TUA, (props) => {
+  const [model, setModel] = useState<LoadedModel | null>(getCachedCharacter);
+  const [error, setError] = useState<string | null>(null);
+  useEffect(() => {
+    if (model) return;
+    let alive = true;
+    loadCharacter()
+      .then((loaded) => {
+        if (alive) setModel(loaded);
+      })
+      .catch((failure: unknown) => {
+        if (alive) setError(failure instanceof Error ? failure.message : String(failure));
+      });
+    return () => {
+      alive = false;
+    };
+  }, [model]);
+  return (
+    <GameLoadingTransition
+      ready={!!model}
+      loader={
+        <GameLoading
+          gameId={GAME_IDS.PLAY_WITH_TUA}
+          theme={props.settings.theme}
+          offset={props.settings.offset}
+          error={!!error}
+          message={error ?? undefined}
+        />
+      }>
+      {model && <Run {...props} model={model} />}
+    </GameLoadingTransition>
+  );
+});

package/src/games/play-with-tua/PlayWithTuaConstants.ts

@@ -0,0 +1,70 @@
+import type { Light } from '@nayan-ui/engine';
+import type { GAME_SOUNDS } from '../../services/SoundsService';
+
+/** Clip IDs are also the names embedded in play-with-tua.glb for other glTF viewers. */
+export const PLAY_WITH_TUA_ANIMATIONS = {
+  standing: { duration: 9.6, loop: true },
+  walking: { duration: 3.75, loop: true },
+  running: { duration: 3, loop: true },
+  jumping: { duration: 2.5, loop: false },
+  waving: { duration: 2.7, loop: false },
+  winking: { duration: 1.65, loop: false },
+  dancing: { duration: 5.25, loop: true },
+  laughing: { duration: 3.6, loop: true },
+  fighting: { duration: 7.8, loop: false },
+  falling: { duration: 4.25, loop: false }
+} as const;
+export type PlayWithTuaAnimation = keyof typeof PLAY_WITH_TUA_ANIMATIONS;
+export interface ActionSoundCue {
+  at: number;
+  sound: keyof typeof GAME_SOUNDS.PLAY_WITH_TUA;
+  once?: boolean;
+}
+/** Contact times sampled from the shipped GLB: no JS skinning or timers during playback. */
+export const PLAY_WITH_TUA_SOUND_CUES: Readonly<Record<PlayWithTuaAnimation, readonly ActionSoundCue[]>> = {
+  standing: [],
+  walking: [0.63, 1.13, 1.63, 2.13, 2.63, 3.12].map((at) => ({ at, sound: 'WALKING' })),
+  running: [0.37, 0.67, 0.97, 1.27, 1.57, 1.87, 2.17, 2.47, 2.8].map((at) => ({ at, sound: 'RUNNING' })),
+  jumping: [
+    { at: 0.42, sound: 'JUMPING' },
+    { at: 1.45, sound: 'LAND' }
+  ],
+  waving: [{ at: 0.25, sound: 'WAVING' }],
+  winking: [{ at: 0.5, sound: 'WINKING' }],
+  dancing: [{ at: 0, sound: 'DANCING', once: true }],
+  laughing: [
+    { at: 0.65, sound: 'LAUGHING' },
+    { at: 1.9, sound: 'LAUGHING' }
+  ],
+  fighting: [
+    ...[0.73, 1.43, 2.75, 3.03, 3.78].map((at) => ({ at, sound: 'FIGHTING' as const })),
+    { at: 5.1, sound: 'JUMPING' },
+    { at: 5.72, sound: 'FIGHTING' },
+    { at: 6.35, sound: 'LAND' }
+  ],
+  falling: [
+    { at: 0.25, sound: 'STUMBLE' },
+    { at: 0.8, sound: 'FALLING' }
+  ]
+};
+/** Feet at y=0, facing +Z. Scale the spawned entity for other sizes. */
+export const PLAY_WITH_TUA_HEIGHT = 3.2;
+
+export const PLAY_WITH_TUA_MODEL_SCALE = 1.21;
+export const PLAY_WITH_TUA_CAMERA_HEIGHT = 1.7 * PLAY_WITH_TUA_MODEL_SCALE;
+export const PLAY_WITH_TUA_WORLD_CAPACITY = 16;
+
+export const PLAY_WITH_TUA_ACTIONS: readonly { id: PlayWithTuaAnimation; label: string }[] = [
+  { id: 'standing', label: 'Standing' },
+  { id: 'waving', label: 'Waving' },
+  { id: 'winking', label: 'Winking' },
+  { id: 'walking', label: 'Walking' },
+  { id: 'running', label: 'Running' },
+  { id: 'jumping', label: 'Jumping' },
+  { id: 'dancing', label: 'Dancing' },
+  { id: 'laughing', label: 'Laughing' },
+  { id: 'fighting', label: 'Fighting' },
+  { id: 'falling', label: 'Falling' }
+];
+export const PLAY_WITH_TUA_LIGHT: Light = { direction: [-0.5, 1, 1], ambient: 0.72, shadows: true, shadowExtent: 5 };
+export const PLAY_WITH_TUA_CONTROLS_HEIGHT = 156;

package/src/games/play-with-tua/PlayWithTuaGame.ts

@@ -0,0 +1,167 @@
+import { type DragEvent, type LoadedModel, type MutableQuat, quat, World } from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import {
+  type ActionSoundCue,
+  PLAY_WITH_TUA_ACTIONS,
+  PLAY_WITH_TUA_ANIMATIONS,
+  PLAY_WITH_TUA_SOUND_CUES,
+  PLAY_WITH_TUA_WORLD_CAPACITY,
+  type PlayWithTuaAnimation
+} from './PlayWithTuaConstants';
+import { playAnimation } from './PlayWithTuaModel';
+import { buildScene, layoutScene, type Scene, setSceneTheme } from './PlayWithTuaScene';
+
+export interface Game extends Scene {
+  world: World;
+  phase: 'ready' | 'playing';
+  score: number;
+  move: PlayWithTuaAnimation;
+  angle: number;
+  dragStart: number;
+  dragging: boolean;
+  inputTop: number;
+  inputBottom: number;
+  audible: boolean;
+  moveTime: number;
+  soundTime: number;
+  onSound: (cue: ActionSoundCue) => void;
+  onSilence: () => void;
+  onPhase: (phase: 'ready' | 'playing' | 'over') => void;
+  onScore: (score: number) => void;
+  onMove: (move: PlayWithTuaAnimation) => void;
+}
+
+export function createGame(model: LoadedModel, theme: GameTheme): Game {
+  const world = new World(PLAY_WITH_TUA_WORLD_CAPACITY);
+  try {
+    const game: Game = {
+      world,
+      ...buildScene(world, model, theme),
+      phase: 'ready',
+      score: 0,
+      move: 'standing',
+      angle: 0,
+      dragStart: 0,
+      dragging: false,
+      inputTop: 0,
+      inputBottom: Infinity,
+      audible: false,
+      moveTime: 0,
+      soundTime: 0,
+      onSound: () => {},
+      onSilence: () => {},
+      onPhase: () => {},
+      onScore: () => {},
+      onMove: () => {}
+    };
+    return game;
+  } catch (error) {
+    world.dispose();
+    throw error;
+  }
+}
+
+export function reset(g: Game) {
+  if (g.world.isDisposed) return;
+  g.onSilence();
+  g.moveTime = g.soundTime = 0;
+  g.phase = 'ready';
+  g.score = 0;
+  g.move = 'standing';
+  g.angle = 0;
+  g.dragStart = 0;
+  g.dragging = false;
+  g.world.set(g.character, { rotation: quat.identity });
+  playAnimation(g.world, g.character, 'standing', { speed: 0, time: 0, fade: 0 });
+  g.onMove(g.move);
+  g.onScore(g.score);
+  g.onPhase(g.phase);
+}
+
+export function start(g: Game) {
+  if (g.world.isDisposed || g.phase === 'playing') return;
+  g.phase = 'playing';
+  g.moveTime = g.soundTime = 0;
+  playAnimation(g.world, g.character, 'standing', { time: 0, fade: 0.15 });
+  g.onPhase(g.phase);
+}
+
+export function selectMove(g: Game, move: PlayWithTuaAnimation) {
+  if (g.world.isDisposed || g.phase !== 'playing') return;
+  // Like the previous playground, a selected action repeats until another is chosen.
+  if (!playAnimation(g.world, g.character, move, { loop: true, time: 0, fade: 0.18 })) return;
+  g.onSilence();
+  g.moveTime = 0;
+  g.soundTime = -1e-6;
+  g.move = move;
+  if (move !== 'standing') g.onScore(++g.score);
+  g.onMove(move);
+}
+
+export function cycleMove(g: Game) {
+  const index = PLAY_WITH_TUA_ACTIONS.findIndex((action) => action.id === g.move);
+  selectMove(g, PLAY_WITH_TUA_ACTIONS[(index + 1) % PLAY_WITH_TUA_ACTIONS.length]!.id);
+}
+
+// Scratch for the drag turn (world.set copies it).
+const TURN: MutableQuat = [0, 0, 0, 1];
+
+export function drag(g: Game, event: DragEvent) {
+  if (event.phase === 'start') {
+    g.dragging = event.y >= g.inputTop && event.y <= g.inputBottom;
+    if (g.dragging) g.dragStart = g.angle;
+  }
+  if (!g.dragging) return;
+  g.angle = event.cancelled ? g.dragStart : g.dragStart + event.dx * 0.01;
+  g.world.set(g.character, { rotation: quat.y(g.angle, TURN) });
+  if (event.phase === 'end') g.dragging = false;
+}
+
+export function resize(g: Game, width: number, height: number, offset: number) {
+  const bounds = layoutScene(g, width, height, offset);
+  g.inputTop = bounds.top;
+  g.inputBottom = bounds.bottom;
+}
+
+export function setTheme(g: Game, theme: GameTheme) {
+  setSceneTheme(g.world, g, theme);
+}
+
+export function tick(g: Game, dt: number) {
+  if (g.world.isDisposed) return;
+  // Match the native world's three-step (50 ms) catch-up limit, including on slow devices.
+  const elapsed = Number.isFinite(dt) ? Math.max(0, Math.min(0.05, dt)) : 0;
+  g.world.update(elapsed);
+  if (g.phase !== 'playing' || elapsed <= 0) return;
+  const previous = g.soundTime;
+  g.moveTime += elapsed;
+  g.soundTime = g.moveTime;
+  if (!g.audible) return;
+  const duration = PLAY_WITH_TUA_ANIMATIONS[g.move].duration;
+  let latest: ActionSoundCue | undefined;
+  let latestTime = -Infinity;
+  for (const cue of PLAY_WITH_TUA_SOUND_CUES[g.move]) {
+    const cycle = cue.once ? 0 : Math.floor((g.moveTime - cue.at) / duration);
+    const at = cycle * duration + cue.at;
+    if (cycle >= 0 && at > previous && at <= g.moveTime && g.moveTime - at < 0.12 && at > latestTime) {
+      latest = cue;
+      latestTime = at;
+    }
+  }
+  if (latest) g.onSound(latest);
+}
+export function setAudible(g: Game, audible: boolean) {
+  if (g.world.isDisposed || g.audible === audible) return;
+  g.audible = audible;
+  if (!audible) g.onSilence();
+  else if (g.phase === 'playing' && g.move === 'dancing') {
+    g.onSound({ at: g.moveTime, sound: 'DANCING', once: true });
+    g.soundTime = g.moveTime;
+  }
+}
+export function dispose(g: Game) {
+  if (g.world.isDisposed) return;
+  g.onSilence();
+  g.audible = false;
+  g.world.dispose();
+}

package/src/games/play-with-tua/PlayWithTuaModel.ts

@@ -0,0 +1,42 @@
+import { loadModel } from '@nayan-ui/engine';
+import type { ClipOptions, Entity, LoadedModel, World } from '@nayan-ui/engine';
+import { PLAY_WITH_TUA_ANIMATIONS, PLAY_WITH_TUA_MODEL_SCALE, type PlayWithTuaAnimation } from './PlayWithTuaConstants';
+
+/** One mesh/texture/rig registration per session, shared across worlds and runs. */
+let modelLoading: Promise<LoadedModel> | undefined;
+let cachedCharacter: LoadedModel | null = null;
+export const getCachedCharacter = (): LoadedModel | null => cachedCharacter;
+
+export function loadCharacter(): Promise<LoadedModel> {
+  modelLoading ??= (async () => {
+    const model = await loadModel(require('../../assets/models/play-with-tua/play-with-tua.glb'), { center: false, shine: 0.08 });
+    if (model.jointCount !== 20 || Object.keys(PLAY_WITH_TUA_ANIMATIONS).some((name) => !model.animations.some((clip) => clip.name === name)))
+      throw Error('Play With Tua is missing its skeletal rig or animation clips');
+    cachedCharacter = model;
+    return model;
+  })().catch((error: unknown) => {
+    modelLoading = undefined;
+    throw error;
+  });
+  return modelLoading;
+}
+
+export function spawnCharacter(world: World, model: LoadedModel): Entity {
+  const character = world.spawn({
+    mesh: model,
+    scale: [PLAY_WITH_TUA_MODEL_SCALE, PLAY_WITH_TUA_MODEL_SCALE, PLAY_WITH_TUA_MODEL_SCALE],
+    pickable: false
+  });
+  playAnimation(world, character, 'standing', { speed: 0, time: 0, fade: 0 });
+  return character;
+}
+
+/** Native clip playback; independent poses per entity, with no JS vertex updates. */
+export function playAnimation(world: World, entity: Entity, animation: PlayWithTuaAnimation, options: ClipOptions = {}): boolean {
+  return world.playClip(entity, animation, { loop: PLAY_WITH_TUA_ANIMATIONS[animation].loop, ...options });
+}
+
+/** Reusable assets; the game loader advances one builder per frame. */
+export function* warmAssets(): Iterable<() => unknown> {
+  yield loadCharacter;
+}