@nayan-ui/games 1.18.0 → 1.20.0

package/src/games/shared/useEngineGame.ts

@@ -0,0 +1,240 @@
+// Everything an engine game's screen does besides its own HUD, in one hook: makes the game once and
+// disposes it on leave, follows the theme, keeps the phase and result, plays sounds and haptics with
+// the current settings, reports each game exactly once (win / lose when it ends, cancel on Stop or on
+// leaving mid-game), and hands back the props EngineGameScreen needs.
+//
+//   const { game, theme, phase, won, fx, screen, gameOver } = useEngineGame(props, {
+//     gameId: GAME_IDS.MY_GAME, create: createGame, reset, start, dispose, tick, setTheme,
+//     wire: (g, fx) => { g.onScore = setScore; g.onHit = () => fx(SOUNDS.HIT, HapticType.LIGHT); }
+//   });
+//   return <EngineGameScreen {...screen} columns={...} subtext="..." gameOver={gameOver({ title: ... })} />;
+import { useEffect, useLayoutEffect, useRef } from 'react';
+import type { Camera, DragEvent, World } from '@nayan-ui/engine';
+import { type HapticType, playHaptic } from '../../services/HapticsService';
+import { playSound, preloadGameSounds, preloadSounds, type SoundConfig, stopAllSounds } from '../../services/SoundsService';
+import { type GameTheme, resolveGameTheme } from '../../services/ThemeService';
+import type { GameProps } from '../../services/UtilsService';
+import type { EngineGameScreenProps } from './EngineGameScreen';
+import type { EngineHud, GameOverCard, HudFeedback } from './EngineHud';
+import { useGameResource } from './useGameResource';
+import { useLiveState } from './useLiveState';
+
+type Phase = 'ready' | 'playing' | 'over';
+/** How an ended game came out; a draw is reported as a cancel. */
+export type GameResult = 'win' | 'lose' | 'draw';
+
+/** What every engine game's state exposes to its screen. */
+export type EngineGameModel = {
+  world: World | null;
+  camera: Camera;
+  score?: number;
+  phase: Phase;
+  won?: boolean;
+  onPhase: (phase: Phase) => void;
+  hudFeedback?: HudFeedback;
+};
+
+/** Plays a sound and/or a haptic, each only if the player has it switched on. */
+export type Feedback = (sound?: SoundConfig | null, haptic?: HapticType | null) => void;
+
+export type EngineGameSpec<G extends EngineGameModel> = {
+  gameId: string;
+  create: (theme: GameTheme) => G;
+  start: (g: G) => void;
+  reset: (g: G) => void;
+  /** What Play Again does; `reset` by default. */
+  replay?: (g: G) => void;
+  dispose: (g: G) => void;
+  tick?: (g: G, dt: number) => void;
+  hud?: (g: G, hud: EngineHud) => void;
+  setTheme?: (g: G, theme: GameTheme) => void;
+  setActive?: (g: G, active: boolean) => void;
+  resize?: (g: G, width: number, height: number, offset: number) => number | void;
+  drag?: (g: G, e: DragEvent) => void;
+  tap?: (g: G, x: number, y: number) => void;
+  /** How an ended game came out (reported, and returned as `status`); from `g.won` by default. */
+  outcome?: (g: G) => GameResult;
+  /** The score reported with a result; `g.score` by default. */
+  reportScore?: (g: G, status: 'win' | 'lose' | 'cancel') => number;
+  /** Optional game-specific completion metrics, sampled at the same time as the final score. */
+  reportData?: (g: G, status: 'win' | 'lose' | 'cancel') => Record<string, unknown>;
+  /** Hooks the game's events up to React state and feedback; called once. May return a cleanup, run on leaving. */
+  wire?: (g: G, fx: Feedback) => void | (() => void);
+  /** Cached ahead of the first sound. */
+  sounds?: Record<string, SoundConfig>;
+  /** Feedback on Start / Stop. */
+  onStart?: (fx: Feedback) => void;
+  onStop?: (fx: Feedback) => void;
+  onPlayAgain?: (fx: Feedback) => void;
+  /** Feedback as the game ends, beyond what its own events play. */
+  onOver?: (fx: Feedback, status: GameResult, game: G) => void;
+  /** Lets an ending play out (ms) before the game-over card covers it. */
+  resultsDelay?: (status: GameResult) => number;
+};
+
+type ScreenProps = Pick<
+  EngineGameScreenProps,
+  | 'onActiveChange'
+  | 'feedback'
+  | 'gameId'
+  | 'settings'
+  | 'onSettingsChange'
+  | 'onShare'
+  | 'onShowLeaderboard'
+  | 'bannerAd'
+  | 'source'
+  | 'camera'
+  | 'onUpdate'
+  | 'onResize'
+  | 'onDrag'
+  | 'onTap'
+  | 'playing'
+  | 'onStart'
+  | 'onStop'
+>;
+
+export function useEngineGame<G extends EngineGameModel>(
+  props: GameProps & { settings: NonNullable<GameProps['settings']> },
+  spec: EngineGameSpec<G>
+) {
+  const { settings } = props;
+  const theme = resolveGameTheme(settings.theme);
+  // Live state: the result and the game-over card show the moment the game ends, however busy the frame loop is
+  const [phase, setPhase] = useLiveState<Phase>('ready', 0);
+  const [status, setStatus] = useLiveState<GameResult>('lose', 0);
+  const [showResults, setShowResults] = useLiveState(false, 0);
+
+  // The latest props and spec, for the handlers made once below
+  const latest = useRef({ props, spec });
+  latest.current = { props, spec };
+
+  const session = useGameResource(
+    () => {
+      const game = spec.create(theme);
+      let reported = false;
+      let disposed = false;
+      const fx: Feedback = (sound, haptic) => {
+        if (disposed || latest.current.props.settings.isVisible) return;
+        const { enableSounds, enableHaptics } = latest.current.props.settings;
+        if (sound) playSound(sound, enableSounds);
+        if (haptic != null) playHaptic(haptic, enableHaptics);
+      };
+      const report = (status: 'win' | 'lose' | 'cancel') => {
+        if (reported) return;
+        reported = true;
+        const score = latest.current.spec.reportScore?.(game, status) ?? game.score ?? 0;
+        const additionalData = latest.current.spec.reportData?.(game, status);
+        latest.current.props.onEndGame?.({ status, score: score.toString(), ...(additionalData ? { additionalData } : {}) });
+      };
+      // The result is set with the phase, so the card never shows the previous game's
+      game.onPhase = (next) => {
+        if (next === 'over') {
+          const result = latest.current.spec.outcome?.(game) ?? (game.won ? 'win' : 'lose');
+          setStatus(result);
+          report(result === 'draw' ? 'cancel' : result);
+          latest.current.spec.onOver?.(fx, result, game);
+        }
+        setPhase(next);
+      };
+      const s = () => latest.current.spec;
+      const handlers = {
+        onActiveChange: (active: boolean) => s().setActive?.(game, active),
+        onUpdate: (dt: number, hud?: EngineHud) => {
+          s().tick?.(game, dt);
+          if (hud) s().hud?.(game, hud);
+        },
+        onResize: (w: number, h: number, offset: number) => s().resize?.(game, w, h, offset),
+        onDrag: (e: DragEvent) => s().drag?.(game, e),
+        onTap: (x: number, y: number) => s().tap?.(game, x, y),
+        onStart: () => {
+          stopAllSounds();
+          reported = false;
+          s().start(game);
+          s().onStart?.(fx);
+        },
+        onStop: () => {
+          stopAllSounds();
+          report('cancel');
+          s().onStop?.(fx);
+          s().reset(game);
+        },
+        playAgain: () => {
+          stopAllSounds();
+          reported = false;
+          latest.current.props.onReplayGame?.();
+          (s().replay ?? s().reset)(game);
+          s().onPlayAgain?.(fx);
+        }
+      };
+      return {
+        game,
+        fx,
+        report,
+        handlers,
+        closeFeedback: () => {
+          disposed = true;
+          stopAllSounds();
+        }
+      };
+    },
+    (session) => {
+      const { game, fx } = session;
+      // Wire once; a real unmount reports cancellation and releases the native world.
+      // Direct component consumers don't go through GameLoaders; warm their effects too.
+      preloadGameSounds(spec.gameId);
+      if (spec.sounds) preloadSounds(spec.sounds);
+      const cleanup = spec.wire?.(game, fx);
+      return () => {
+        session.closeFeedback();
+        cleanup?.();
+        if (game.phase === 'playing') session.report('cancel');
+        latest.current.spec.dispose(game);
+      };
+    }
+  );
+  const { game, fx, handlers } = session;
+
+  // create(theme) already applied the initial theme. Rebuilding it on mount used to
+  // create and immediately destroy a second board in games without their own guard.
+  const appliedTheme = useRef(theme);
+  useLayoutEffect(() => {
+    if (appliedTheme.current === theme) return;
+    appliedTheme.current = theme;
+    latest.current.spec.setTheme?.(game, theme);
+  }, [game, theme]);
+
+  // The card shows at once, or after the ending has played out
+  useEffect(() => {
+    if (phase !== 'over') return setShowResults(false);
+    const delay = latest.current.spec.resultsDelay?.(status) ?? 0;
+    if (!delay) return setShowResults(true);
+    const t = setTimeout(() => setShowResults(true), delay);
+    return () => clearTimeout(t);
+  }, [phase, status, setShowResults]);
+
+  const screen: ScreenProps = {
+    gameId: spec.gameId,
+    feedback: game.hudFeedback,
+    onActiveChange: handlers.onActiveChange,
+    settings,
+    onSettingsChange: props.onSettingsChange,
+    onShare: props.onShareScreenshot ?? props.onShare,
+    onShowLeaderboard: props.onShowLeaderboard,
+    bannerAd: props.bannerAd,
+    source: game.world,
+    camera: game.camera,
+    onUpdate: handlers.onUpdate,
+    onResize: spec.resize ? handlers.onResize : undefined,
+    onDrag: spec.drag ? handlers.onDrag : undefined,
+    onTap: spec.tap ? handlers.onTap : undefined,
+    playing: phase === 'playing',
+    onStart: handlers.onStart,
+    onStop: handlers.onStop
+  };
+
+  /** The game-over card once it's due (Play Again and Share are filled in), else null. */
+  const gameOver = (card: Omit<GameOverCard, 'onPlayAgain' | 'onShare'>): GameOverCard | null =>
+    showResults ? { ...card, onPlayAgain: handlers.playAgain, onShare: props.onShareScreenshot } : null;
+
+  return { game, theme, phase, status, fx, screen, gameOver };
+}

package/src/games/shared/useGameResource.ts

@@ -0,0 +1,21 @@
+import { useEffect, useRef } from 'react';
+
+/** Keep native resources through React's effect replay; release them after a real unmount. */
+export function useGameResource<T>(create: () => T, connect: (value: T) => () => void): T {
+  const resource = useRef<{ value: T; users: number; cleanup?: () => void } | null>(null);
+  resource.current ??= { value: create(), users: 0 };
+  const current = resource.current;
+  useEffect(() => {
+    current.users++;
+    current.cleanup ??= connect(current.value);
+    return () => {
+      current.users--;
+      queueMicrotask(() => {
+        if (current.users !== 0) return;
+        current.cleanup?.();
+        current.cleanup = undefined;
+      });
+    };
+  }, [current]); // eslint-disable-line react-hooks/exhaustive-deps
+  return current.value;
+}

package/src/games/shared/useLiveState.ts

@@ -0,0 +1,58 @@
+// `useState` for what a game shows while its frame loop runs (score, timer, lives, phase, the result).
+// React runs ordinary state updates as normal-priority tasks; when every frame takes its whole slot
+// (a busy, slower device) those wait until they expire, about 5 s, so the scoreboard and the
+// game-over card lagged by seconds. An external store's updates render on React's synchronous lane
+// instead, straight after the task that made them. Changes are published at most every
+// `minInterval` ms (the latest value always lands), so a score changing every frame doesn't
+// re-render every frame.
+import { useRef, useSyncExternalStore } from 'react';
+
+type SetState<T> = (next: T | ((previous: T) => T)) => void;
+
+/** Updates at most this often by default (ms): the scoreboard still reads as live. */
+const MIN_INTERVAL = 100;
+
+type Store<T> = { get: () => T; subscribe: (listener: () => void) => () => void; set: SetState<T> };
+
+function createStore<T>(initial: T, minInterval: number): Store<T> {
+  let shown = initial;
+  let latest = initial;
+  let last = -Infinity;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const listeners = new Set<() => void>();
+  const publish = () => {
+    timer = null;
+    last = Date.now();
+    if (Object.is(shown, latest)) return;
+    shown = latest;
+    for (const listener of listeners) listener();
+  };
+  return {
+    get: () => shown,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+        if (!listeners.size && timer) {
+          clearTimeout(timer);
+          timer = null;
+        }
+      };
+    },
+    set: (next) => {
+      latest = typeof next === 'function' ? (next as (previous: T) => T)(latest) : next;
+      if (timer) return;
+      const wait = minInterval - (Date.now() - last);
+      if (wait <= 0) publish();
+      else timer = setTimeout(publish, wait);
+    }
+  };
+}
+
+/** Like `useState`, but its updates show at once even while the frame loop keeps the JS thread busy (see above). */
+export function useLiveState<T>(initial: T | (() => T), minInterval = MIN_INTERVAL): [T, SetState<T>] {
+  const store = useRef<Store<T> | null>(null);
+  if (!store.current) store.current = createStore(typeof initial === 'function' ? (initial as () => T)() : initial, minInterval);
+  const value = useSyncExternalStore(store.current.subscribe, store.current.get);
+  return [value, store.current.set];
+}

package/src/games/sliding-numbers/SlidingNumbers.tsx

@@ -0,0 +1,71 @@
+// Sliding Numbers' screen, on the Nayan engine: the board and its tiles are one 3D scene (an
+// orthographic camera leaning back over the board), under Playtura's scoreboard, controls and modals.
+// The play is in SlidingNumbersGame.ts (the board's rules in SlidingNumbersRules.ts), what it draws in
+// SlidingNumbersScene.ts.
+//
+// One world serves the whole visit: Start, Stop and Play Again reset it in place (a new shuffle glides
+// the tiles to their places) and a theme change rebuilds just the board, so the GPU view is never
+// rebuilt. Tiles glide, sink and hop in the engine's Rust core; JS reads the finger and steps the clock.
+import { HapticType } from '../../services/HapticsService';
+import { GAME_SOUNDS } from '../../services/SoundsService';
+import { GAME_IDS, isTablet } from '../../services/UtilsService';
+import { engineGame, EngineGameScreen } from '../shared/EngineGameScreen';
+import { timerColumn } from '../shared/EngineHud';
+import { useEngineGame } from '../shared/useEngineGame';
+import { useLiveState } from '../shared/useLiveState';
+import { GAME_DURATION, getLayout, LIGHT } from './SlidingNumbersConstants';
+import { createGame, dispose, drag, newBoard, setLayout, setTheme, start, stop, tick } from './SlidingNumbersGame';
+
+const SOUNDS = GAME_SOUNDS.SLIDING_NUMBERS;
+
+export const SlidingNumbers = engineGame(GAME_IDS.SLIDING_NUMBERS, (props) => {
+  const [time, setTime] = useLiveState(GAME_DURATION);
+
+  // Win or lose as it ends
+  const { game, theme, status, screen, gameOver } = useEngineGame(props, {
+    gameId: GAME_IDS.SLIDING_NUMBERS,
+    create: createGame,
+    start,
+    // Stop: the same board, the clock back to five minutes
+    reset: stop,
+    // Play Again: a fresh shuffle, waiting for Start
+    replay: newBoard,
+    dispose,
+    tick,
+    setTheme,
+    resize: (g, width, height, offset) => {
+      const l = getLayout(width, height, offset, isTablet);
+      setLayout(g, l);
+      return l.size + l.pad * 2;
+    },
+    drag,
+    sounds: SOUNDS,
+    onStart: (fx) => fx(SOUNDS.START),
+    wire: (g, fx) => {
+      g.onTime = setTime;
+      // As the original game: a slide pops and buzzes; the end plays its sound; a blocked tile only shakes
+      g.onEvent = (event) => {
+        if (event === 'blocked') fx(SOUNDS.BLOCKED, HapticType.WARNING);
+        else if (event === 'move') fx(SOUNDS.MOVE, HapticType.LIGHT);
+        else if (event === 'win') fx(SOUNDS.WIN);
+        else if (event === 'lose') fx(SOUNDS.GAME_OVER);
+      };
+    }
+  });
+
+  return (
+    <EngineGameScreen
+      {...screen}
+      light={LIGHT}
+      columns={[timerColumn(time, theme)]}
+      subtext="Slide tiles to solve!"
+      gameOver={gameOver({
+        title: status === 'win' ? 'SOLVED!' : 'TIME UP!',
+        message: status === 'win' ? 'Puzzle completed!' : 'You ran out of time!',
+        scoreLabel: 'Score',
+        score: game.score,
+        buttonText: status === 'win' ? 'Play Again!' : 'Try Again!'
+      })}
+    />
+  );
+});

package/src/games/sliding-numbers/SlidingNumbersConstants.ts

@@ -0,0 +1,65 @@
+// Sliding Numbers' timings, colors and layout. Rules and scores match the original version
+// (games/sliding-numbers), so scores carry over.
+import { getScoreBoardTop } from '../shared/EngineHud';
+import type { TiltView } from '../shared/EngineTilt';
+import { frontLight, gameWidthFor } from '../shared/EngineUtils';
+
+// ── Rules and timing ──────────────────────────────────────────────────
+
+export const GAME_DURATION = 300; // seconds
+export const SLIDE_TIME = 0.2; // a tile gliding into the gap, as the original slide
+export const PRESS_SCALE = 0.92; // a tile under the finger
+export const TAP_SLOP = 10; // points a finger may wander and still tap
+export const SWIPE = 18; // points a finger must travel for a swipe
+
+// ── Colors ────────────────────────────────────────────────────────────
+
+/** Tiles 1..8, as the original tiles. */
+export const TILE_COLORS = ['#FF6B6B', '#51CF66', '#339AF0', '#FCC419', '#CC5DE8', '#FF922B', '#22B8CF', '#F06595'] as const;
+export const NUMBER_WORDS = ['', 'ONE', 'TWO', 'THREE', 'FOUR', 'FIVE', 'SIX', 'SEVEN', 'EIGHT'] as const;
+export const COLORS = {
+  // The wooden board (classic), as the original board
+  FRAME: '#5c4033',
+  WELL: '#3a2518',
+  SLOT: '#2e1d12',
+  NUMBER: '#FFFFFF'
+} as const;
+
+// ── The scene ─────────────────────────────────────────────────────────
+
+/** The camera leans back from straight down, so the tiles stand up off the board. */
+export const TILT = 0; // straight down
+/** Lit straight on, with no light falling from the top: every face toward the camera keeps its exact color. */
+export const LIGHT = frontLight([0, 0, 1], 0.6);
+/** A tile's height, of its width. */
+export const TILE_HEIGHT = 0.4; // as deep as Candy Crush's blocks, of a tile
+
+// ── Layout (view points) ──────────────────────────────────────────────
+
+const SCOREBOARD_HEIGHT = 82;
+const CONTROLS_HEIGHT = 120;
+
+export type Layout = TiltView & { tile: number; gap: number; pitch: number; pad: number; size: number };
+
+/** The board as big as the original board (88% of the width, at most 340 points, 420 on a tablet), smaller if the screen is short. */
+export function getLayout(width: number, height: number, offset: number, tablet: boolean): Layout {
+  const gap = tablet ? 6 : 4;
+  const pad = tablet ? 18 : 14;
+  const top = getScoreBoardTop(offset) + SCOREBOARD_HEIGHT;
+  const room = Math.max(180, height - top - CONTROLS_HEIGHT);
+  // As wide as the game area (as every game: 30 narrower than the screen, at most 500), shorter if the screen is
+  const board = Math.max(150, Math.min(gameWidthFor(width), room / Math.cos(TILT) - 30));
+  const tile = Math.floor((board - pad * 2 - gap * 2) / 3);
+  const size = tile * 3 + gap * 2;
+  return { width, height, tilt: TILT, centerY: top + room / 2, tile, gap, pitch: tile + gap, pad, size };
+}
+
+/** A cell's centre on the board (row 0 along the top), in world units. */
+export const cellCentre = (l: Layout, row: number, col: number): [number, number] => [(col - 1) * l.pitch, (1 - row) * l.pitch];
+
+/** The cell under a board point, or null. */
+export function cellAt(l: Layout, x: number, y: number): [number, number] | null {
+  const col = Math.floor((x + l.size / 2) / l.pitch);
+  const row = Math.floor((l.size / 2 - y) / l.pitch);
+  return row < 0 || row > 2 || col < 0 || col > 2 ? null : [row, col];
+}

package/src/games/sliding-numbers/SlidingNumbersGame.ts

@@ -0,0 +1,192 @@
+// Sliding Numbers' play, with no React: build a game with `createGame`, give it a layout, `start` it and
+// `tick` it every frame. Tap a tile beside the gap (or swipe it toward the gap) to slide it in; put
+// 1 to 8 back in order inside five minutes to win (the quicker, the higher the score).
+//
+// The board's rules are the original store's (SlidingNumbersRules.ts); the clock runs on the game's own clock.
+import { type Camera, type DragEvent, World } from '@nayan-ui/engine';
+import { calculateTimeBasedScore } from '../../services/ScoringService';
+import type { GameTheme } from '../../services/ThemeService';
+import { aimTilted, unproject } from '../shared/EngineTilt';
+import { cellAt, GAME_DURATION, type Layout, SWIPE, TAP_SLOP, TILE_HEIGHT } from './SlidingNumbersConstants';
+import { type Board, canSlide, shuffled, slide, solved, type Tile, tileAt } from './SlidingNumbersRules';
+import { buildScene, celebrate, dim, placeTile, press, removeScene, type Scene, setSceneTheme, shake, undim } from './SlidingNumbersScene';
+
+export type Phase = 'ready' | 'playing' | 'over';
+/** move: a tile slid; blocked: a tile that can't move; win / lose: how it ended. */
+export type GameEvent = 'move' | 'blocked' | 'win' | 'lose';
+
+const WORLD_CAPACITY = 400; // the board and slots, eight tiles with their shadows and embossed letters, and the confetti
+
+export function createGame(theme: GameTheme) {
+  const world = new World(WORLD_CAPACITY);
+  const camera: Camera = { eye: [0, 0, 240], target: [0, 0, 0], fov: 1, ortho: 1 };
+  const g = {
+    world,
+    camera,
+    theme,
+    layout: null as Layout | null,
+    scene: null as Scene | null,
+    phase: 'ready' as Phase,
+    board: shuffled() as Board,
+    won: false,
+    /** Score and the countdown live in the engine (Rust), advanced by world.update. */
+    get score() {
+      return world.scoreboard.score;
+    },
+    get timeLeft() {
+      return world.scoreboard.shownSeconds;
+    },
+    /** A finger down on a tile: where, and which. */
+    press: null as { x: number; y: number; id: number } | null,
+    // UI hooks, set by the screen.
+    onPhase: (_p: Phase) => {},
+    onTime: (_t: number) => {},
+    onEvent: (_e: GameEvent) => {}
+  };
+  world.scoreboard.reset(0, GAME_DURATION);
+  world.scoreboard.handlers = {
+    onSecond: (t) => g.onTime(t),
+    onTimeUp: () => g.phase === 'playing' && end(g, false)
+  };
+  return g;
+}
+export type Game = ReturnType<typeof createGame>;
+
+// ── Scene ─────────────────────────────────────────────────────────────
+
+/** Lays the board out for the view (first layout, header height, rotation): rebuilt where things stand. */
+export function setLayout(g: Game, l: Layout) {
+  if (g.scene) removeScene(g.world, g.scene);
+  g.layout = l;
+  aimTilted(g.camera, l);
+  g.scene = buildScene(g.world, l, g.theme, g.board.tiles);
+}
+
+export function setTheme(g: Game, theme: GameTheme) {
+  g.theme = theme;
+  if (g.layout && g.scene) setSceneTheme(g.world, g.layout, g.scene, theme);
+}
+
+// ── Run ───────────────────────────────────────────────────────────────
+
+/** Starts on the board already shown. */
+export function start(g: Game) {
+  if (g.phase !== 'ready') return;
+  g.won = false;
+  g.world.scoreboard.reset();
+  g.world.scoreboard.startCountdown(GAME_DURATION);
+  g.phase = 'playing';
+  g.onTime(GAME_DURATION);
+  g.onPhase('playing');
+}
+
+/** Stop: the same board, the clock back to five minutes (as the original game). */
+export function stop(g: Game) {
+  g.press = null;
+  g.won = false;
+  g.world.scoreboard.reset(0, GAME_DURATION);
+  g.phase = 'ready';
+  if (g.scene) undim(g.world, g.scene, g.board.tiles);
+  g.onTime(GAME_DURATION);
+  g.onPhase('ready');
+}
+
+/** Play Again: a fresh shuffle, the tiles gliding to their new places. */
+export function newBoard(g: Game) {
+  g.board = shuffled();
+  const { layout: l, scene: s } = g;
+  if (l && s) {
+    undim(g.world, s, g.board.tiles);
+    for (const t of g.board.tiles) placeTile(g.world, l, s, t);
+  }
+  stop(g);
+}
+
+export function dispose(g: Game) {
+  g.world.dispose();
+}
+
+export function tick(g: Game, dt: number) {
+  if (g.world.isDisposed) return;
+  g.world.update(dt);
+}
+
+function end(g: Game, won: boolean) {
+  g.world.scoreboard.stop();
+  g.won = won;
+  if (!won) g.world.scoreboard.set(0);
+  g.phase = 'over';
+  if (g.press && g.layout && g.scene) press(g.world, g.scene, g.press.id, false);
+  g.press = null;
+  if (g.layout && g.scene) {
+    if (won) celebrate(g.world, g.layout, g.scene, g.board.tiles);
+    else dim(g.world, g.scene, g.board.tiles);
+  }
+  g.onPhase('over');
+  g.onEvent(won ? 'win' : 'lose');
+}
+
+// ── Moves ─────────────────────────────────────────────────────────────
+
+/** Slides a tile into the gap if it's beside it; shakes it if not. A solved board wins. */
+export function move(g: Game, t: Tile) {
+  if (g.phase !== 'playing' || t.value === 0) return;
+  const { layout: l, scene: s } = g;
+  if (!canSlide(g.board, t)) {
+    if (l && s) shake(g.world, l, s, t.id);
+    g.onEvent('blocked');
+    return;
+  }
+  slide(g.board, t);
+  if (l && s) placeTile(g.world, l, s, t);
+  g.onEvent('move');
+  if (solved(g.board)) {
+    // The time saved under five minutes, as the original score (on a base of 0)
+    g.world.scoreboard.set(calculateTimeBasedScore(GAME_DURATION - g.timeLeft, GAME_DURATION, 0));
+    end(g, true);
+  }
+}
+
+// ── The finger ────────────────────────────────────────────────────────
+
+/** The tile under a view point (on the tiles' tops), or null. */
+export function tileUnder(g: Game, x: number, y: number): Tile | null {
+  const l = g.layout;
+  if (!l) return null;
+  const [wx, wy] = unproject(l, x, y, 1 + l.tile * TILE_HEIGHT);
+  const cell = cellAt(l, wx, wy);
+  const t = cell ? tileAt(g.board, cell[0], cell[1]) : null;
+  return t && t.value !== 0 ? t : null;
+}
+
+/** A finger down sinks the tile under it; a tap slides it, and so does a swipe toward the gap. */
+export function drag(g: Game, { phase, x, y }: DragEvent) {
+  const { layout: l, scene: s } = g;
+  if (phase === 'start') {
+    const t = g.phase === 'playing' ? tileUnder(g, x, y) : null;
+    g.press = t ? { x, y, id: t.id } : null;
+    if (t && l && s) press(g.world, s, t.id, true);
+    return;
+  }
+  const p = g.press;
+  if (!p) return;
+  const t = g.board.tiles.find((k) => k.id === p.id)!;
+  const dx = x - p.x;
+  const dy = y - p.y;
+  // A swipe: once it's gone far enough one way, the tile slides if that way is the gap
+  const far = Math.hypot(dx, dy);
+  if (far >= SWIPE || phase === 'end') {
+    g.press = null;
+    if (l && s) press(g.world, s, p.id, false);
+    if (far < TAP_SLOP) return move(g, t); // a tap
+    if (far < SWIPE) return; // wandered, then let go
+    const horizontal = Math.abs(dx) > Math.abs(dy);
+    const toRow = t.row + (horizontal ? 0 : dy > 0 ? 1 : -1);
+    const toCol = t.col + (horizontal ? (dx > 0 ? 1 : -1) : 0);
+    if (toRow === g.board.emptyRow && toCol === g.board.emptyCol) move(g, t);
+    else {
+      if (l && s) shake(g.world, l, s, t.id);
+      g.onEvent('blocked');
+    }
+  }
+}