@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/fruit-ninja/FruitNinjaScene.ts

@@ -0,0 +1,319 @@
+import {
+  type Color,
+  effects,
+  type Entity,
+  extrude,
+  merge,
+  type Model,
+  Path,
+  quat,
+  shapeGeometry,
+  type TransformBatch,
+  tube,
+  type Vec3,
+  type World
+} from '@nayan-ui/engine';
+import { lighten } from '../../services/GamesConstants';
+import type { Fruit, FruitKind } from '../shared/EngineFruits';
+import { cacheGameAsset, createGameMesh as createShape } from '../shared/EngineMeshes';
+// Everything Fruit Ninja throws, slices and swipes, in front of its 3D world (FruitNinjaWorld). Positions
+// come in screen points (y down) and land on the play plane a few metres ahead of the camera, where the
+// original game drew them; sizes and speeds are scaled to metres there.
+// Fruit are EngineFruits' 3D models (each also modelled in halves for slicing), the bomb and the star
+// are built here once; all are shared meshes, as mesh ids are app-wide and limited. A thrown item is an
+// invisible root at its centre (it spins about it) carrying the model.
+// Sliced halves and splashes fly on their own in the engine's Rust core (velocity, gravity, lifetime).
+import { toColor } from '../shared/EngineUtils';
+import {
+  BLADE_POINTS,
+  BOMB_COLORS,
+  FRAME_TIME,
+  type Layout,
+  PIECE_LIFETIME,
+  PIECE_SPREAD,
+  SPAWN_FROM,
+  SPAWN_SPRING,
+  STAR_COLORS,
+  TRAIL_FADE
+} from './FruitNinjaConstants';
+import { at, facing, planeVector, PLAY_DEPTH, pointSize, type View3D } from './FruitNinjaWorld';
+
+const HIDDEN = 0;
+const PER_SECOND = 1 / FRAME_TIME; // the physics is per frame; the engine's motion is per second
+/** The trail floats this far in front of the play plane, so it's drawn over the fruit it cuts. */
+const TRAIL_DEPTH = PLAY_DEPTH - 0.35;
+
+// ── Models (built once per app: mesh ids last for the whole app) ──────
+
+export type ItemKind = { kind: 'fruit'; fruit: FruitKind } | { kind: 'bomb' } | { kind: 'star' };
+export type Models = { fruits: Record<FruitKind, Fruit>; bomb: Model; spark: Model; star: Model; disc: Model };
+
+let extras: Omit<Models, 'fruits'> | undefined;
+/** The bomb, its fuse spark, the star and a flat disc (glows, trail joints). Needs the native core. */
+export function buildModels(fruits: Record<FruitKind, Fruit>): Models {
+  extras ??= cacheGameAsset('fruit-ninja/extras', () => ({
+    // A dark glossy ball with a cap and a curling fuse
+    bomb: createShape(
+      merge([
+        { geometry: shapeGeometry('sphere'), color: [0.13, 0.14, 0.17] },
+        { geometry: shapeGeometry('cylinder'), position: [0, 0.5, 0], scale: [0.26, 0.14, 0.26], color: [0.35, 0.37, 0.42] },
+        {
+          geometry: tube(
+            [
+              [0, 0.55, 0],
+              [0.04, 0.7, 0],
+              [0.14, 0.78, 0],
+              [0.22, 0.76, 0]
+            ],
+            { radius: 0.035 }
+          ),
+          color: [0.76, 0.6, 0.38]
+        }
+      ]),
+      { fit: 1, shine: 0.7 }
+    ),
+    spark: createShape(shapeGeometry('sphere')),
+    star: createShape(extrude(new Path().addStar(0, 0, 0.5, 0.22, 5), { depth: 0.22, color: toColor(STAR_COLORS[0]) }), { fit: 1, shine: 0.6 }),
+    disc: createShape(extrude(new Path().addCircle(0, 0, 0.5), { depth: 0 }))
+  }));
+  return { fruits, ...extras };
+}
+
+// ── Thrown items ──────────────────────────────────────────────────────
+
+const SPARK: Color = [3, 2.1, 0.6]; // above 1: self-lit
+const WHITE: Color = [1, 1, 1, 1];
+
+/** A model's offset and scale so it fills `size` metres, centred on its bounding box. */
+function fitted(model: Model, size: number, center: Vec3 = [0, 0, 0]) {
+  const s = size / Math.max(model.size[0], model.size[1]);
+  return { scale: s, position: [-center[0] * s, -center[1] * s, -center[2] * s] as Vec3 };
+}
+
+/**
+ * A thrown item at screen point (x, y) (its centre), springing up to full size and spinning: `spin` is
+ * its turn per frame in the picture's plane (clockwise positive, as original), plus a little tumble.
+ */
+export function spawnItem(world: World, v: View3D, l: Layout, m: Models, item: ItemKind, x: number, y: number, spin: number): Entity {
+  const tumble = (Math.random() - 0.5) * 3;
+  const size = l.size * pointSize(v);
+  const root = world.spawn({
+    mesh: 'none',
+    position: at(v, x, y),
+    scale: SPAWN_FROM,
+    spin: [tumble * 0.4, tumble, -spin * PER_SECOND],
+    pickable: false
+  });
+  world.animate(root, { scale: 1 }, { spring: SPAWN_SPRING });
+  const add = (mesh: Model, f: ReturnType<typeof fitted>, color: Color = WHITE) =>
+    world.spawn({ mesh, parent: root, position: f.position, scale: f.scale, color, pickable: false });
+  if (item.kind === 'fruit') {
+    const fruit = m.fruits[item.fruit];
+    add(fruit.whole, fitted(fruit.whole, size, fruit.center));
+  } else {
+    if (item.kind === 'bomb') {
+      add(m.bomb, fitted(m.bomb, size * 0.92));
+      const spark = world.spawn({
+        mesh: m.spark,
+        parent: root,
+        position: [size * 0.2, size * 0.36, 0],
+        scale: size * 0.1,
+        color: SPARK,
+        pickable: false
+      });
+      world.animate(spark, { scale: size * 0.16 }, { duration: 0.12, repeat: 'forever', yoyo: true });
+    } else {
+      add(m.star, fitted(m.star, size * 0.95), toColor(STAR_COLORS[0]));
+    }
+  }
+  return root;
+}
+
+const itemPosition: [number, number, number] = [0, 0, 0];
+export function placeItem(world: World, v: View3D, root: Entity, x: number, y: number, updates?: TransformBatch) {
+  const k = pointSize(v);
+  const dy = (v.height / 2 - y) * k;
+  itemPosition[0] = v.eye[0] + v.forward[0] * v.playDepth + (x - v.width / 2) * k;
+  itemPosition[1] = v.eye[1] + v.forward[1] * v.playDepth + dy * v.up[1];
+  itemPosition[2] = v.eye[2] + v.forward[2] * v.playDepth + dy * v.up[2];
+  if (updates) updates.position(root, itemPosition[0], itemPosition[1], itemPosition[2]);
+  else world.set(root, { position: itemPosition });
+}
+
+// ── Slicing ───────────────────────────────────────────────────────────
+
+const SPLASH_FRUIT = (juice: Color): Color[] => [juice, [Math.min(1, juice[0] + 0.25), Math.min(1, juice[1] + 0.25), Math.min(1, juice[2] + 0.25)]];
+const BOMB_BURST = BOMB_COLORS.map((c) => toColor(c));
+const STAR_BURST = STAR_COLORS.map((c) => toColor(c));
+const STAR_SPARK = toColor(lighten(STAR_COLORS[0], 0.5));
+
+/**
+ * The blade cuts an item at screen (x, y), moving (vx, vy) points per frame, along screen direction
+ * (dx, dy). A fruit falls apart in two halves split along the stroke, pushed apart and tumbling, under a
+ * splash of its juice; a star bursts into gold; a bomb explodes.
+ */
+export function sliceItem(
+  world: World,
+  v: View3D,
+  l: Layout,
+  m: Models,
+  root: Entity,
+  item: ItemKind,
+  x: number,
+  y: number,
+  vx: number,
+  vy: number,
+  dx: number,
+  dy: number
+) {
+  world.despawn(root);
+  const k = pointSize(v);
+  const size = l.size * k;
+  const centre = at(v, x, y);
+  const near = at(v, x, y, PLAY_DEPTH - size * 0.5); // just in front of it, toward the camera
+  const fall = l.gravity * PER_SECOND * PER_SECOND; // points per second², down the screen
+  const gravity = planeVector(v, 0, fall);
+  if (item.kind === 'fruit') {
+    const fruit = m.fruits[item.fruit];
+    // The cut runs along the stroke; the halves part across it (the normal, in screen points, y down)
+    const len = Math.hypot(dx, dy) || 1;
+    const nx = dy / len;
+    const ny = -dx / len;
+    const cut = facing(v, Math.atan2(-ny, nx));
+    const f = fitted(fruit.whole, size, fruit.center);
+    [-1, 1].forEach((side, i) => {
+      const half = world.spawn({
+        mesh: 'none',
+        position: centre,
+        // pieces[0] turned so its cut faces +x is the left half; pieces[1] the other way
+        rotation: quat.multiply(cut, quat.y(side < 0 ? Math.PI / 2 : -Math.PI / 2)),
+        velocity: planeVector(v, (vx + side * nx * PIECE_SPREAD) * PER_SECOND, (vy + side * ny * PIECE_SPREAD) * PER_SECOND),
+        acceleration: gravity,
+        spin: [0, 0, side * 2.5],
+        lifetime: PIECE_LIFETIME,
+        pickable: false
+      });
+      world.spawn({ mesh: fruit.pieces[i]!, parent: half, position: f.position, scale: f.scale, color: WHITE, pickable: false });
+    });
+    effects.splash(world, {
+      position: near,
+      count: 14,
+      size: size * 0.09,
+      speed: size * 5,
+      lifetime: 0.55,
+      gravity: -fall * k * 0.6,
+      colors: SPLASH_FRUIT(fruit.juice)
+    });
+    return;
+  }
+  const bomb = item.kind === 'bomb';
+  if (bomb)
+    effects.explosion(world, {
+      position: near,
+      count: 16,
+      size: size * 0.7,
+      speed: size * 2.6,
+      lifetime: 0.6,
+      gravity: -fall * k * 0.5,
+      debris: BOMB_BURST,
+      flash: false
+    });
+  else
+    effects.sparkle(world, {
+      position: near,
+      count: 16,
+      size: size * 0.1,
+      speed: size * 6,
+      lifetime: 0.6,
+      gravity: -fall * k * 0.3,
+      colors: STAR_BURST,
+      flash: false
+    });
+  // A flash that swells and fades, facing the camera: orange for the bomb, white-gold for the star
+  const flash = world.spawn({
+    mesh: m.disc,
+    position: at(v, x, y, PLAY_DEPTH - size),
+    rotation: facing(v),
+    scale: size,
+    color: bomb ? [2, 1.1, 0.3, 0.85] : [STAR_SPARK[0] * 2, STAR_SPARK[1] * 2, STAR_SPARK[2] * 2, 0.8],
+    pickable: false
+  });
+  world.animate(flash, { scale: size * (bomb ? 3.2 : 2.2), color: [2, bomb ? 0.8 : 1.8, 0.2, 0] }, { duration: bomb ? 0.4 : 0.3 }).then(() => {
+    if (world.has(flash)) world.despawn(flash);
+  });
+}
+
+// ── Blade trail ───────────────────────────────────────────────────────
+
+/**
+ * The blade's trail, as Falling Sticks draws its finger: glowing beads through the last touch points,
+ * shrinking toward the tail. It remembers how many beads are showing and whether they are fading, so a
+ * redraw sets only the beads that change (one native call each) and stops animations only after a fade.
+ */
+export type Trail = { beads: Entity[]; shown: number; fading: boolean };
+
+const BEAD_SIZE = 7; // points, the newest bead
+// Self-lit white (channels above 1), so the sun and the night don't shade it
+const BEAD: Color = [1.6, 1.6, 1.6, 0.75];
+const FADED: Color = [1.6, 1.6, 1.6, 0];
+
+export function spawnTrail(world: World): Trail {
+  return {
+    beads: Array.from({ length: BLADE_POINTS }, () => world.spawn({ mesh: 'sphere', scale: HIDDEN, color: BEAD, pickable: false })),
+    shown: 0,
+    fading: false
+  };
+}
+
+/** Draws the trail through the first `n` points of `xs`, `ys` (screen points, oldest first). */
+export function drawTrail(world: World, v: View3D, t: Trail, xs: ArrayLike<number>, ys: ArrayLike<number>, n: number) {
+  const updates = world.transforms;
+  const count = Math.min(n, t.beads.length);
+  if (t.fading) {
+    for (let i = 0; i < t.shown; i++) world.stopAnimation(t.beads[i]!);
+    t.fading = false;
+  }
+  // `at` inlined: the plane's centre and metres per point once, then no allocation per bead
+  const m = pointSize(v, TRAIL_DEPTH);
+  const centre = at(v, v.width / 2, v.height / 2, TRAIL_DEPTH);
+  const size = BEAD_SIZE * m;
+  for (let i = 0; i < count; i++) {
+    const j = n - 1 - i;
+    const dx = (xs[j]! - v.width / 2) * m;
+    const dy = (v.height / 2 - ys[j]!) * m;
+    const bead = t.beads[i]!;
+    updates.position(bead, centre[0] + dx, centre[1] + dy * v.up[1], centre[2] + dy * v.up[2]);
+    updates.scale(bead, size * (1 - i / BLADE_POINTS));
+    updates.color(bead, BEAD[0], BEAD[1], BEAD[2], BEAD[3] ?? 1);
+  }
+  for (let i = count; i < t.shown; i++) updates.scale(t.beads[i]!, HIDDEN);
+  t.shown = count;
+  updates.flush();
+}
+
+/** The finger lifted: the trail shrinks and fades out where it is. */
+export function fadeTrail(world: World, t: Trail) {
+  if (!t.shown) return;
+  world.animate(t.beads.slice(0, t.shown), { color: FADED, scale: HIDDEN }, { duration: TRAIL_FADE });
+  t.fading = true;
+}
+
+export function hideTrail(world: World, t: Trail) {
+  const updates = world.transforms;
+  for (let i = 0; i < t.shown; i++) {
+    if (t.fading) world.stopAnimation(t.beads[i]!);
+    updates.scale(t.beads[i]!, HIDDEN);
+  }
+  updates.flush();
+  t.shown = 0;
+  t.fading = false;
+}
+
+export function removeTrail(world: World, t: Trail) {
+  for (const e of t.beads) world.despawn(e);
+}
+
+/** Reusable assets; the game loader advances one builder per frame. */
+export function* warmAssets(): Iterable<() => unknown> {
+  yield () => buildModels({} as Record<FruitKind, Fruit>);
+}

package/src/games/fruit-ninja/FruitNinjaWorld.ts

@@ -0,0 +1,17 @@
+// Fruit Ninja's world: the shared 3D meadow (EngineMeadow) framed for it. The camera stands at eye
+// height with the horizon a little below the middle of the screen, and the fruit fly on a plane 3.6 m
+// ahead, close enough that the ground never passes in front of them. The big oak and pine frame the
+// play area, with grass and flowers right in front.
+import type { Entity, World } from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import { makeView as meadowView, spawnWorld as spawnMeadow, type View3D } from '../shared/EngineMeadow';
+
+export { at, backgroundFor, cameraFor, facing, lightFor, planeVector, pointSize, type View3D } from '../shared/EngineMeadow';
+
+/** Metres from the eye to the play plane. */
+export const PLAY_DEPTH = 3.6;
+
+export const makeView = (width: number, height: number): View3D =>
+  meadowView(width, height, { eyeHeight: 1.6, horizon: 0.62, playDepth: PLAY_DEPTH });
+
+export const spawnWorld = (world: World, v: View3D, theme: GameTheme): Entity[] => spawnMeadow(world, v, theme);

package/src/games/game-2048/Game2048.tsx

@@ -0,0 +1,84 @@
+// 2048's 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
+// Game2048Game.ts (the grid's rules in Game2048Rules.ts), what it draws in Game2048Scene.ts.
+//
+// One world serves the whole visit: Start, Stop and Play Again reset it in place and a theme change
+// rebuilds just the board, so the GPU view is never rebuilt. Tiles glide, merge and pop in the engine's
+// Rust core; JS reads the swipe and steps the clock and the world once a frame.
+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_TIME, getLayout, LIGHT } from './Game2048Constants';
+import { createGame, dispose, drag, type GameEvent, reset, type Result, setLayout, setTheme, start, tick } from './Game2048Game';
+
+const SOUNDS = GAME_SOUNDS.GAME_2048;
+
+/** Each event's sound and haptic, as the original store played them. */
+const FEEDBACK: Record<GameEvent, { sound: (typeof SOUNDS)[keyof typeof SOUNDS]; haptic: HapticType }> = {
+  move: { sound: SOUNDS.TILE_MOVE, haptic: HapticType.LIGHT },
+  merge: { sound: SOUNDS.TILE_MERGE, haptic: HapticType.MEDIUM },
+  invalid: { sound: SOUNDS.INVALID_MOVE, haptic: HapticType.WARNING },
+  win: { sound: SOUNDS.WIN, haptic: HapticType.SUCCESS },
+  stuck: { sound: SOUNDS.GAME_OVER, haptic: HapticType.ERROR }
+};
+
+/** The game-over card for each ending: title, message, score label, button. */
+const CARDS: Record<Result, { title: string; message: string; label: string; button: string }> = {
+  win: { title: 'YOU WON!', message: 'You reached 1024!', label: 'Score', button: 'Continue Playing!' },
+  timeout: { title: 'TIME UP!', message: 'You ran out of time!', label: "Time's Up!", button: 'Play Again!' },
+  stuck: { title: 'NO MOVES LEFT!', message: 'The board is full!', label: 'Board Full!', button: 'Play Again!' }
+};
+
+export const Game2048 = engineGame(GAME_IDS.GAME_2048, (props) => {
+  const [time, setTime] = useLiveState(GAME_TIME);
+
+  // A win (scored by the time left) or a loss as it ends
+  const { game, theme, status, screen, gameOver } = useEngineGame(props, {
+    gameId: GAME_IDS.GAME_2048,
+    create: createGame,
+    start,
+    reset,
+    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,
+    outcome: (g) => (g.result === 'win' ? 'win' : 'lose'),
+    sounds: SOUNDS,
+    onStart: (fx) => fx(SOUNDS.START, HapticType.SELECTION),
+    onStop: (fx) => fx(null, HapticType.SELECTION),
+    onOver: (fx, _status, g) => {
+      if (g.result === 'timeout') fx(SOUNDS.TIME_UP, HapticType.ERROR);
+    },
+    wire: (g, fx) => {
+      g.onTime = setTime;
+      g.onEvent = (event) => fx(FEEDBACK[event].sound, FEEDBACK[event].haptic);
+    }
+  });
+
+  const card = CARDS[game.result ?? 'timeout'];
+
+  return (
+    <EngineGameScreen
+      {...screen}
+      light={LIGHT}
+      columns={[timerColumn(time, theme, 0)]}
+      subtext="Swipe to play"
+      gameOver={gameOver({
+        title: card.title,
+        message: card.message,
+        scoreLabel: card.label,
+        score: status === 'win' ? game.score : 0,
+        buttonText: card.button
+      })}
+    />
+  );
+});

package/src/games/game-2048/Game2048Constants.ts

@@ -0,0 +1,68 @@
+// 2048's timings, colors and layout. The rules (in Game2048Rules.ts), the clock and the score match the
+// original version (games/game-2048), 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_TIME = 900; // seconds: 15 minutes
+export const MIN_SWIPE = 50; // points a finger must travel, as the original swipe
+export const SLIDE_TIME = 0.11; // tiles gliding to their cells, as the original slide
+export const MERGE_POP = 1.18;
+
+// ── Colors ────────────────────────────────────────────────────────────
+
+/** Each value's tile and number colors, as the original tiles (8192 and up share the dark one). */
+const TILES: Record<number, [string, string]> = {
+  2: ['#eee4da', '#776e65'],
+  4: ['#ede0c8', '#776e65'],
+  8: ['#f2b179', '#f9f6f2'],
+  16: ['#f59563', '#f9f6f2'],
+  32: ['#f67c5f', '#f9f6f2'],
+  64: ['#f65e3b', '#f9f6f2'],
+  128: ['#edcf72', '#f9f6f2'],
+  256: ['#edcc61', '#f9f6f2'],
+  512: ['#edc850', '#f9f6f2'],
+  1024: ['#edc53f', '#f9f6f2'],
+  2048: ['#edc22e', '#f9f6f2'],
+  4096: ['#3c3a32', '#f9f6f2']
+};
+export const tileColors = (value: number): [string, string] => TILES[value] ?? TILES[4096]!;
+
+export const COLORS = {
+  // The wooden board (classic), as the original board
+  FRAME: '#5c4033',
+  SLOT: '#3d2a1f'
+} as const;
+
+// ── The scene ─────────────────────────────────────────────────────────
+
+/** The camera looks straight down at the board. */
+export const TILT = 0;
+/** Evenly lit, straight from the camera and all ambient: every face keeps its exact color, with no shading or shadow anywhere. */
+export const LIGHT = frontLight([0, 0, 1], 1);
+/** A tile's height, of its width. */
+export const TILE_HEIGHT = 0.4;
+
+// ── 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 grid as wide as the game area (30 narrower than the screen, at most 500), smaller if the screen is short. */
+export function getLayout(width: number, height: number, offset: number, tablet: boolean): Layout {
+  const gap = 3;
+  const pad = tablet ? 10 : 8;
+  const top = getScoreBoardTop(offset) + SCOREBOARD_HEIGHT;
+  const room = Math.max(180, height - top - CONTROLS_HEIGHT);
+  const board = Math.max(180, Math.min(gameWidthFor(width), room / Math.cos(TILT) - 30));
+  const tile = Math.floor((board - pad * 2 - gap * 6) / 5);
+  const size = tile * 5 + gap * 6;
+  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 - 2) * l.pitch, (2 - row) * l.pitch];

package/src/games/game-2048/Game2048Game.ts

@@ -0,0 +1,181 @@
+// 2048's play, with no React: build a game with `createGame`, give it a layout, `start` it and `tick` it
+// every frame. Swipe to slide every tile one way: equal tiles that meet merge. A new tile lands after
+// every slide that moves something. Reach 1024 inside fifteen minutes to win; running out of time, or
+// of moves, ends the game.
+//
+// The grid's rules are the original service's (Game2048Rules.ts); the store's scoring, sounds and timer
+// are kept: a win scores by the time left, 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 } from '../shared/EngineTilt';
+import { GAME_TIME, type Layout, MIN_SWIPE } from './Game2048Constants';
+import { addRandomTile, type Direction, emptyGrid, type Grid, moveTiles, reached, stuck, tilesOf } from './Game2048Rules';
+import { buildScene, bump, celebrate, dim, removeScene, resetTiles, type Scene, setSceneTheme, slideTiles } from './Game2048Scene';
+
+export type Phase = 'ready' | 'playing' | 'over';
+/** How a game ended. */
+export type Result = 'win' | 'timeout' | 'stuck';
+/** move / merge: a slide (and whether it merged); invalid: a swipe that moved nothing; win / stuck: how a slide ended it. */
+export type GameEvent = 'move' | 'merge' | 'invalid' | 'win' | 'stuck';
+
+const WORLD_CAPACITY = 400; // the board and 25 slots, up to 25 tiles with their digits and as many sliding out, and the confetti
+
+/** A fresh board with its two starting tiles (ids 1 and 2). */
+function freshGrid(): { grid: Grid; nextId: number } {
+  const grid = emptyGrid();
+  addRandomTile(grid, 1);
+  addRandomTile(grid, 2);
+  return { grid, nextId: 3 };
+}
+
+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 { grid, nextId } = freshGrid();
+  const g = {
+    world,
+    camera,
+    theme,
+    layout: null as Layout | null,
+    scene: null as Scene | null,
+    phase: 'ready' as Phase,
+    grid,
+    nextId,
+    result: null as Result | null,
+    /** 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, and whether its swipe has been taken. */
+    press: null as { swiped: boolean } | null,
+    // UI hooks, set by the screen.
+    onPhase: (_p: Phase) => {},
+    onTime: (_t: number) => {},
+    onEvent: (_e: GameEvent) => {}
+  };
+  world.scoreboard.reset(0, GAME_TIME);
+  world.scoreboard.handlers = {
+    onSecond: (t) => g.onTime(t),
+    onTimeUp: () => g.phase === 'playing' && end(g, 'timeout')
+  };
+  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, tilesOf(g.grid));
+  if (g.phase === 'over' && g.result !== 'win') dim(g.world, g.scene);
+}
+
+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, with fifteen minutes on the clock. */
+export function start(g: Game) {
+  if (g.phase !== 'ready') return;
+  g.world.scoreboard.reset();
+  g.world.scoreboard.startCountdown(GAME_TIME);
+  g.result = null;
+  g.phase = 'playing';
+  g.onTime(GAME_TIME);
+  g.onPhase('playing');
+}
+
+/** A fresh board, not started (Stop, Play Again, as the original game re-dealt both). */
+export function reset(g: Game) {
+  const { grid, nextId } = freshGrid();
+  g.grid = grid;
+  g.nextId = nextId;
+  g.result = null;
+  g.world.scoreboard.reset(0, GAME_TIME);
+  g.press = null;
+  g.phase = 'ready';
+  if (g.layout && g.scene) resetTiles(g.world, g.layout, g.scene, tilesOf(grid));
+  g.onTime(GAME_TIME);
+  g.onPhase('ready');
+}
+
+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, result: Result) {
+  g.world.scoreboard.stop();
+  g.result = result;
+  g.phase = 'over';
+  g.press = null;
+  if (g.layout && g.scene) {
+    if (result === 'win') celebrate(g.world, g.layout, g.scene);
+    else dim(g.world, g.scene);
+  }
+  g.onPhase('over');
+}
+
+// ── Moves ─────────────────────────────────────────────────────────────
+
+/** A slide one way, as the original store made it: a new tile if anything moved, then the win and stuck checks. */
+export function move(g: Game, direction: Direction) {
+  if (g.phase !== 'playing') return;
+  const { moved, score, ghosts } = moveTiles(g.grid, direction);
+  const { layout: l, scene: s } = g;
+  if (!moved) {
+    if (l && s) bump(g.world, l, s);
+    g.onEvent('invalid');
+    return;
+  }
+  addRandomTile(g.grid, g.nextId++);
+  const won = reached(g.grid);
+  const over = stuck(g.grid);
+  if (l && s) slideTiles(g.world, l, s, tilesOf(g.grid), ghosts);
+  g.onEvent('move');
+  if (score > 0) g.onEvent('merge');
+  if (won) {
+    // The time left against the fifteen minutes (on a base of 0)
+    g.world.scoreboard.set(calculateTimeBasedScore(g.timeLeft, GAME_TIME, 0));
+    g.onEvent('win');
+    end(g, 'win');
+  } else if (over) {
+    g.onEvent('stuck');
+    end(g, 'stuck');
+  }
+}
+
+// ── The finger ────────────────────────────────────────────────────────
+
+/** A swipe anywhere: taken the moment it's gone far enough (or on the lift), its longer way. */
+export function drag(g: Game, { phase, dx, dy }: DragEvent) {
+  if (phase === 'start') {
+    g.press = { swiped: false };
+    return;
+  }
+  const p = g.press;
+  if (!p || p.swiped) return;
+  const ax = Math.abs(dx);
+  const ay = Math.abs(dy);
+  let dir: Direction | null = null;
+  if (ax > ay && ax > MIN_SWIPE) dir = dx > 0 ? 'right' : 'left';
+  else if (ay > MIN_SWIPE) dir = dy > 0 ? 'down' : 'up';
+  if (phase === 'end') g.press = null;
+  if (!dir) return;
+  p.swiped = true;
+  move(g, dir);
+}