@nayan-ui/games 1.19.0 → 1.20.0

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

@@ -0,0 +1,79 @@
+// Sliding Numbers' rules, with no React or engine: the 3 x 3 board (eight numbered tiles and a gap),
+// shuffled by random slides from solved so it's always solvable, which tiles can slide, and whether
+// it's solved. Ported from the original store (games/sliding-numbers).
+
+export const GRID = 3;
+const CELLS = GRID * GRID;
+
+/** Tile ids 0..8 (8 is the gap, value 0); each tile's cell, row-major. */
+export type Tile = { id: number; value: number; row: number; col: number };
+export type Board = { tiles: Tile[]; emptyRow: number; emptyCol: number };
+
+const DIRS = [
+  [-1, 0],
+  [1, 0],
+  [0, -1],
+  [0, 1]
+] as const;
+const NEIGHBORS = Array.from({ length: CELLS }, (_, i) => {
+  const r = Math.floor(i / GRID),
+    c = i % GRID;
+  return DIRS.filter(([dr, dc]) => r + dr >= 0 && r + dr < GRID && c + dc >= 0 && c + dc < GRID).map(([dr, dc]) => (r + dr) * GRID + c + dc);
+});
+
+/** A fresh board shuffled by 200 random slides of the gap, as the original store did (the same random draws). */
+export function shuffled(): Board {
+  const tiles: Tile[] = Array.from({ length: CELLS }, (_, i) => ({
+    id: i,
+    value: i === CELLS - 1 ? 0 : i + 1,
+    row: Math.floor(i / GRID),
+    col: i % GRID
+  }));
+  let er = GRID - 1;
+  let ec = GRID - 1;
+  const byCell = tiles.slice();
+  const gap = tiles[CELLS - 1]!;
+  for (let m = 0; m < 200; m++) {
+    const empty = er * GRID + ec;
+    const valid = NEIGHBORS[empty]!;
+    const next = valid[Math.floor(Math.random() * valid.length)]!;
+    const nr = Math.floor(next / GRID);
+    const nc = next % GRID;
+    const moving = byCell[next]!;
+    byCell[empty] = moving;
+    byCell[next] = gap;
+    gap.row = nr;
+    gap.col = nc;
+    moving.row = er;
+    moving.col = ec;
+    er = nr;
+    ec = nc;
+  }
+  return { tiles, emptyRow: er, emptyCol: ec };
+}
+
+export const tileAt = (b: Board, row: number, col: number) => b.tiles.find((t) => t.row === row && t.col === col) ?? null;
+
+/** Whether a tile is beside the gap (and so can slide into it). */
+export function canSlide(b: Board, t: Tile) {
+  if (t.value === 0) return false;
+  return Math.abs(t.row - b.emptyRow) + Math.abs(t.col - b.emptyCol) === 1;
+}
+
+/** Slides a tile into the gap (already checked). */
+export function slide(b: Board, t: Tile) {
+  const gap = b.tiles.find((x) => x.value === 0)!;
+  const [r, c] = [t.row, t.col];
+  t.row = b.emptyRow;
+  t.col = b.emptyCol;
+  gap.row = r;
+  gap.col = c;
+  b.emptyRow = r;
+  b.emptyCol = c;
+}
+
+/** Every tile home: 1..8 in reading order, the gap bottom right. */
+export const solved = (b: Board) =>
+  b.tiles.every((t) =>
+    t.value === 0 ? t.row === GRID - 1 && t.col === GRID - 1 : t.row === Math.floor((t.value - 1) / GRID) && t.col === (t.value - 1) % GRID
+  );

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

@@ -0,0 +1,193 @@
+// Everything Sliding Numbers draws: the board (a wooden board with a sunken well and nine recessed
+// slots in the classic theme, the theme's board and cells otherwise) and the eight raised tiles, each
+// in its own color with its number and its word standing on top in 3D letters. Seen from a little in
+// front of straight down (shared/EngineTilt: an orthographic camera leaning back, one world unit per
+// point). Every tile is a root (unscaled, so its letters keep their shape) carrying its block and letters.
+import { type Color, effects, type Entity, extrude, type Model, Path, type Vec3, type World } from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import { setBackdropTheme, spawnBackdrop } from '../shared/EngineBackdrop';
+import { spawnRaisedBlock } from '../shared/EngineBlocks';
+import { flatGlyphMesh, GLYPH_ADVANCE } from '../shared/EngineGlyphs';
+import { cacheGameAsset, createGameMesh as createShape } from '../shared/EngineMeshes';
+import { placeTiltedBackdrop } from '../shared/EngineTilt';
+import { toColor } from '../shared/EngineUtils';
+import { cellCentre, COLORS, type Layout, NUMBER_WORDS, PRESS_SCALE, SLIDE_TIME, TILE_COLORS, TILE_HEIGHT } from './SlidingNumbersConstants';
+import type { Tile } from './SlidingNumbersRules';
+
+const meshes = new Map<string, Model>();
+const cached = (key: string, build: () => Model) => {
+  let m = meshes.get(key);
+  if (!m) {
+    m = cacheGameAsset('sliding-numbers/SlidingNumbersScene:' + key, build);
+    meshes.set(key, m);
+  }
+  return m;
+};
+const BOARD_DEPTH = 12;
+const BACKDROP_DEPTH = 30;
+const SURFACE = 1; // the board's top, where the tiles stand
+
+const panelMesh = (w: number, radius: number, depth: number) =>
+  cached(`sn-panel:${w}:${radius}:${depth}`, () =>
+    createShape(extrude(new Path().addRoundedRect(-w / 2, -w / 2, w, w, radius), { depth }), { shine: 0.25 })
+  );
+
+// ── Spawning ──────────────────────────────────────────────────────────
+
+/** A tile: its root (moved), and its block (pressed, tinted). */
+type TileView = { root: Entity; block: Entity };
+export type Scene = { backdrop: Entity; board: Entity[]; tiles: Map<number, TileView> };
+
+const tileTop = (l: Layout) => SURFACE + l.tile * TILE_HEIGHT;
+const at = (l: Layout, row: number, col: number): Vec3 => {
+  const [x, y] = cellCentre(l, row, col);
+  return [x, y, SURFACE];
+};
+
+function spawnBoard(world: World, l: Layout, theme: GameTheme): Entity[] {
+  const out: Entity[] = [];
+  const add = (o: Parameters<World['spawn']>[0]) => out.push(world.spawn({ pickable: false, ...o }));
+  const outer = l.size + l.pad * 2;
+  const classic = theme.mode === 'classic';
+  add({
+    mesh: panelMesh(outer, classic ? 16 : 8, BOARD_DEPTH),
+    position: [0, 0, -BOARD_DEPTH / 2],
+    color: toColor(classic ? COLORS.FRAME : theme.BOARD.SURFACE)
+  });
+  if (classic) add({ mesh: panelMesh(l.size + 8, 10, 1), position: [0, 0, 0.2], color: toColor(COLORS.WELL) });
+  // A slot under every cell: where the gap shows
+  for (let r = 0; r < 3; r++)
+    for (let c = 0; c < 3; c++) {
+      const [x, y] = cellCentre(l, r, c);
+      add({
+        mesh: panelMesh(l.tile, Math.min(10, l.tile * 0.12), 1),
+        position: [x, y, 0.5],
+        color: toColor(classic ? COLORS.SLOT : theme.BOARD.CELL_EMPTY)
+      });
+    }
+  return out;
+}
+
+/** A tile's number (large) and word (small) in solid white 3D letters on its top, each over a dark copy (the tile's own deep shade) offset below it, embossed. */
+function spawnLabel(world: World, l: Layout, root: Entity, value: number) {
+  const white = toColor(COLORS.NUMBER);
+  const [r, g, b] = toColor(TILE_COLORS[value - 1]!);
+  const deep: Color = [r * 0.45, g * 0.45, b * 0.45, 1];
+  // On the block's face
+  const top = tileTop(l) - SURFACE;
+  // Printed flat and matte (crisp from straight above), over a dark copy offset down-right
+  const letter = (ch: string, x: number, y: number, size: number) => {
+    const off = Math.max(1, size * 0.05);
+    world.spawn({ mesh: flatGlyphMesh(ch), parent: root, position: [x + off, y - off, top + 0.3], scale: size, color: deep, pickable: false });
+    world.spawn({ mesh: flatGlyphMesh(ch), parent: root, position: [x, y, top + 0.6], scale: size, color: white, pickable: false });
+  };
+  letter(String(value), 0, l.tile * 0.07, l.tile * 0.32);
+  const word = NUMBER_WORDS[value]!;
+  const small = l.tile * 0.11;
+  const step = small * GLYPH_ADVANCE;
+  [...word].forEach((ch, i) => letter(ch, (i - (word.length - 1) / 2) * step, -l.tile * 0.24, small));
+}
+
+export function buildScene(world: World, l: Layout, theme: GameTheme, tiles: Tile[]): Scene {
+  const backdrop = spawnBackdrop(world, l.width, l.height, -BACKDROP_DEPTH, theme);
+  placeTiltedBackdrop(world, backdrop, l, BACKDROP_DEPTH);
+  const s: Scene = { backdrop, board: spawnBoard(world, l, theme), tiles: new Map() };
+  const h = l.tile * TILE_HEIGHT;
+  for (const t of tiles) {
+    if (t.value === 0) continue;
+    const root = world.spawn({ mesh: 'none', position: at(l, t.row, t.col), pickable: false });
+    // A bevelled block, as Candy Crush's (matte), without a shadow
+    const block = spawnRaisedBlock(world, {
+      parent: root,
+      position: [0, 0, h / 2],
+      size: [l.tile, l.tile, h],
+      color: toColor(TILE_COLORS[t.value - 1]!),
+      gloss: false,
+      shadow: false
+    });
+    spawnLabel(world, l, root, t.value);
+    s.tiles.set(t.id, { root, block });
+  }
+  return s;
+}
+
+export function removeScene(world: World, s: Scene) {
+  for (const e of [s.backdrop, ...s.board, ...Array.from(s.tiles.values(), (t) => t.root)]) world.despawn(e);
+}
+
+export function setSceneTheme(world: World, l: Layout, s: Scene, theme: GameTheme) {
+  setBackdropTheme(world, s.backdrop, theme);
+  for (const e of s.board) world.despawn(e);
+  s.board = spawnBoard(world, l, theme);
+}
+
+// ── Motion ────────────────────────────────────────────────────────────
+
+/** A tile glides to its cell (or is put there at once). */
+export function placeTile(world: World, l: Layout, s: Scene, t: Tile, animate = true) {
+  const v = s.tiles.get(t.id);
+  if (!v) return;
+  if (animate) world.animate(v.root, { position: at(l, t.row, t.col) }, { duration: SLIDE_TIME, easing: 'easeOut' });
+  else {
+    world.stopAnimation(v.root);
+    world.set(v.root, { position: at(l, t.row, t.col) });
+  }
+}
+
+/** A finger down on a tile sinks it a little; lifting brings it back. */
+export function press(world: World, s: Scene, id: number, down: boolean) {
+  const v = s.tiles.get(id);
+  if (!v) return;
+  const k = down ? PRESS_SCALE : 1;
+  world.animate(v.root, { scale: k }, { duration: down ? 0.08 : 0.14, easing: down ? 'easeOut' : 'back' });
+}
+
+/** A tile that can't move (not beside the gap): a quick shake. */
+export function shake(world: World, l: Layout, s: Scene, id: number) {
+  const v = s.tiles.get(id);
+  if (v) world.animate(v.root, { shake: l.tile * 0.05 }, { duration: 0.25 });
+}
+
+/** Solved: the tiles hop in a wave across the board, and confetti bursts over it. */
+export function celebrate(world: World, l: Layout, s: Scene, tiles: Tile[]) {
+  for (const t of tiles) {
+    const v = s.tiles.get(t.id);
+    if (!v) continue;
+    const [x, y, z] = at(l, t.row, t.col);
+    world.animate(
+      v.root,
+      [
+        { position: [x, y, z + l.tile * 0.35], scale: 1.04, at: 0.4 },
+        { position: [x, y, z], scale: 1 }
+      ],
+      { duration: 0.45, delay: SLIDE_TIME + (t.row + t.col) * 0.07, easing: 'easeOut' }
+    );
+  }
+  effects.confetti(world, {
+    position: [0, 0, l.tile],
+    count: 60,
+    size: l.tile * 0.08,
+    speed: l.size * 1.4,
+    lifetime: 1.3,
+    gravity: -l.size * 2.4,
+    colors: TILE_COLORS.slice(0, 4).map((c) => toColor(c))
+  });
+}
+
+/** Out of time: the tiles dim. */
+export function dim(world: World, s: Scene, tiles: Tile[]) {
+  for (const t of tiles) {
+    const v = s.tiles.get(t.id);
+    if (!v) continue;
+    const c = toColor(TILE_COLORS[t.value - 1]!);
+    world.animate(v.block, { color: [c[0] * 0.5, c[1] * 0.5, c[2] * 0.55, 1] }, { duration: 0.4 });
+  }
+}
+
+/** Back to their own colors (a new game). */
+export function undim(world: World, s: Scene, tiles: Tile[]) {
+  for (const t of tiles) {
+    const v = s.tiles.get(t.id);
+    if (v) world.set(v.block, { color: toColor(TILE_COLORS[t.value - 1]!) });
+  }
+}

package/src/games/snake-3d/Snake3D.tsx

@@ -0,0 +1,76 @@
+// Snake 3D's screen, on the Nayan engine: the board, the snake and its food are one 3D scene (an
+// orthographic camera leaning back over the board), under Playtura's scoreboard, controls and modals.
+// The play is in Snake3DGame.ts (the rules in Snake3DRules.ts), what it draws in Snake3DScene.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. JS steps the snake (a few numbers) on the
+// game's own clock and glides it every frame; gulps, bursts and the crash animate in the Rust core.
+import { HapticType } from '../../services/HapticsService';
+import { GAME_SOUNDS } from '../../services/SoundsService';
+import { GAME_IDS } from '../../services/UtilsService';
+import { engineGame, EngineGameScreen } from '../shared/EngineGameScreen';
+import { scoreColumn, timerColumn } from '../shared/EngineHud';
+import { useEngineGame } from '../shared/useEngineGame';
+import { useLiveState } from '../shared/useLiveState';
+import { getLayout, LIGHT, TIME_LIMIT } from './Snake3DConstants';
+import { createGame, dispose, drag, type GameEvent, reset, setLayout, setTheme, start, tick } from './Snake3DGame';
+
+const SOUNDS = GAME_SOUNDS.SNAKE_3D;
+
+/** Each event's sound and haptic, as the original version played them. */
+const FEEDBACK: Record<GameEvent, { sound: (typeof SOUNDS)[keyof typeof SOUNDS]; haptic: HapticType }> = {
+  eat: { sound: SOUNDS.EAT, haptic: HapticType.MEDIUM },
+  special: { sound: SOUNDS.SPECIAL, haptic: HapticType.HEAVY },
+  crash: { sound: SOUNDS.COLLISION, haptic: HapticType.HEAVY }
+};
+
+const scoreText = (s: number) => `${s}`;
+
+export const Snake3D = engineGame(GAME_IDS.SNAKE_3D, (props) => {
+  const [score, setScore] = useLiveState(0);
+  const [time, setTime] = useLiveState(TIME_LIMIT);
+
+  const { theme, screen, gameOver } = useEngineGame(props, {
+    gameId: GAME_IDS.SNAKE_3D,
+    create: createGame,
+    start,
+    reset,
+    dispose,
+    tick,
+    setTheme,
+    resize: (g, width, height, offset) => {
+      const l = getLayout(width, height, offset);
+      setLayout(g, l);
+      return l.size + l.cell;
+    },
+    drag,
+    // It always ends as a loss (a crash or time up), as in the original game
+    outcome: () => 'lose',
+    sounds: SOUNDS,
+    onStart: (fx) => fx(SOUNDS.START),
+    onStop: (fx) => fx(null, HapticType.LIGHT),
+    onOver: (fx, _status, g) => fx(g.timeLeft <= 0 ? SOUNDS.TIME_UP : SOUNDS.GAME_OVER, HapticType.ERROR),
+    wire: (g, fx) => {
+      g.onScore = setScore;
+      g.onTime = setTime;
+      g.onEvent = (event) => fx(FEEDBACK[event].sound, FEEDBACK[event].haptic);
+    }
+  });
+
+  return (
+    <EngineGameScreen
+      {...screen}
+      light={LIGHT}
+      columns={[scoreColumn(score), timerColumn(time, theme, 0)]}
+      subtext="Swipe to steer!"
+      gameOver={gameOver({
+        title: 'GAME OVER',
+        message: 'You hit the wall or yourself!',
+        scoreLabel: 'Final Score',
+        score,
+        formatter: scoreText,
+        buttonText: 'Play Again!'
+      })}
+    />
+  );
+});

package/src/games/snake-3d/Snake3DConstants.ts

@@ -0,0 +1,61 @@
+// Snake 3D's timings, colors and layout. Rules and scoring (in Snake3DRules.ts) match the original version
+// (games/snake-3d), so scores carry over.
+import { getScoreBoardTop } from '../shared/EngineHud';
+import type { TiltView } from '../shared/EngineTilt';
+import { frontLight, gameWidthFor } from '../shared/EngineUtils';
+import { GRID } from './Snake3DRules';
+
+// ── Timing ────────────────────────────────────────────────────────────
+
+export const TIME_LIMIT = 300; // seconds: five minutes
+/** One move every 300 ms, the original game's fixed speed. */
+export const TICK_MS = 300;
+/** A long frame counts for at most this much, so the snake never jumps two cells or fast-forwards. */
+export const MAX_FRAME_MS = 100;
+export const SWIPE = 15; // points a finger must travel for a turn (the original pan's threshold)
+
+// ── Colors ────────────────────────────────────────────────────────────
+
+export const COLORS = {
+  HEAD: '#00c853',
+  BODY: '#00a344',
+  TAIL: '#008035',
+  BELLY: '#7CF2A8',
+  EYE: '#FFFFFF',
+  PUPIL: '#111111',
+  TONGUE: '#E53935',
+  SPECIAL: '#ffa502',
+  CRASH: '#ff4757',
+  CLASSIC_BOARD: 'rgba(255, 255, 255, 0.30)',
+  CLASSIC_DARK: 'rgba(255, 255, 255, 0.10)',
+  CLASSIC_RIM: 'rgba(255, 255, 255, 0.55)'
+} as const;
+
+// ── The scene ─────────────────────────────────────────────────────────
+
+/** The camera looks straight down at the board. */
+export const TILT = 0;
+/** Lit from the upper left; surfaces facing up off the board (+z) keep their exact color. */
+export const LIGHT = frontLight([-0.4, 0.5, 1], 0.45);
+
+// ── Layout (view points) ──────────────────────────────────────────────
+
+const SCOREBOARD_HEIGHT = 82;
+const CONTROLS_HEIGHT = 120;
+const RIM = 0.5; // the rim round the board, of a cell
+
+export type Layout = TiltView & { cell: number; size: number };
+
+/** The board as wide as the screen allows (as the original board, which filled the width), smaller if the screen is short. */
+export function getLayout(width: number, height: number, offset: number): Layout {
+  const top = getScoreBoardTop(offset) + SCOREBOARD_HEIGHT;
+  const room = Math.max(200, height - top - CONTROLS_HEIGHT);
+  const fromWidth = gameWidthFor(width) / (GRID + RIM * 2);
+  const fromHeight = room / (Math.cos(TILT) * (GRID + RIM * 2) + Math.sin(TILT) * 1.5);
+  // Not rounded to whole points, so the board (rim included) spans exactly the game width when the height allows
+  const cell = Math.max(8, Math.min(fromWidth, fromHeight));
+  return { width, height, tilt: TILT, centerY: top + room / 2, cell, size: cell * GRID };
+}
+
+/** A grid point (cells, 0.5 = the middle of the first) on the board, in world units. */
+export const gridPoint = (l: Layout, x: number, y: number): [number, number] => [x * l.cell - l.size / 2, l.size / 2 - y * l.cell];

package/src/games/snake-3d/Snake3DGame.ts

@@ -0,0 +1,192 @@
+// Snake 3D's play, with no React: build a game with `createGame`, give it a layout, `start` it and
+// `tick` it every frame. Swipe to turn; eat the apple (1,000) or the gold star (2,000, gone after 10
+// seconds) to grow; the walls and your own body end the game, and so does the five-minute clock.
+//
+// The snake moves one cell every 300 ms on the game's own clock, exactly as the original physics stepped it
+// (Snake3DRules.ts), and glides between cells every frame.
+import { type Camera, type DragEvent, World } from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import { aimTilted } from '../shared/EngineTilt';
+import { type Layout, MAX_FRAME_MS, SWIPE, TICK_MS, TIME_LIMIT } from './Snake3DConstants';
+import { freshState, generateFood, POINTS_PER_FOOD, POINTS_PER_SPECIAL_FOOD, step, turn } from './Snake3DRules';
+import { buildScene, crash, drawSnake, faceHead, flick, gulp, placeFood, removeScene, resetSnake, type Scene, setSceneTheme } from './Snake3DScene';
+
+export type Phase = 'ready' | 'playing' | 'over';
+/** eat / special: food eaten; crash: a wall or the body. */
+export type GameEvent = 'eat' | 'special' | 'crash';
+
+const WORLD_CAPACITY = 1000; // up to 400 beads and their joints, the board, the food, and bursts
+
+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 st = freshState();
+  const g = {
+    world,
+    camera,
+    theme,
+    layout: null as Layout | null,
+    scene: null as Scene | null,
+    phase: 'ready' as Phase,
+    st,
+    /** The cells as of the move before last, for the glide. */
+    prev: st.snake.slice(),
+    pending: 0,
+    /** 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;
+    },
+    /** Seconds on the game's clock (the bonus food's expiry runs on it, so a pause can't expire it). */
+    clock: 0,
+    moves: 0,
+    /** Where the current drag stretch began (each 15 points one way is a swipe). */
+    anchor: null as [number, number] | null,
+    // UI hooks, set by the screen.
+    onPhase: (_p: Phase) => {},
+    onScore: (_s: number) => {},
+    onTime: (_t: number) => {},
+    onEvent: (_e: GameEvent) => {}
+  };
+  world.scoreboard.reset(0, TIME_LIMIT);
+  world.scoreboard.handlers = {
+    onScore: (s) => g.onScore(s),
+    onSecond: (t) => g.onTime(t),
+    onTimeUp: () => g.phase === 'playing' && end(g)
+  };
+  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);
+  faceHead(g.world, g.scene, g.st.direction);
+  draw(g);
+}
+
+export function setTheme(g: Game, theme: GameTheme) {
+  g.theme = theme;
+  if (g.layout && g.scene) setSceneTheme(g.world, g.layout, g.scene, theme);
+}
+
+function draw(g: Game) {
+  const { layout: l, scene: s } = g;
+  if (!l || !s) return;
+  drawSnake(g.world, l, s, g.prev, g.st.snake, g.phase === 'playing' ? g.pending / TICK_MS : 1);
+  placeFood(g.world, l, s, g.st.food);
+}
+
+// ── Run ───────────────────────────────────────────────────────────────
+
+/** The snake back in the middle heading right, no food (the idle board, Stop, Play Again). */
+function home(g: Game) {
+  g.st = freshState();
+  g.prev = g.st.snake.slice();
+  g.pending = 0;
+  g.world.scoreboard.reset(0, TIME_LIMIT);
+  if (g.layout && g.scene) {
+    resetSnake(g.world, g.layout, g.scene);
+    faceHead(g.world, g.scene, 'RIGHT');
+  }
+}
+
+export function start(g: Game) {
+  if (g.phase !== 'ready') return;
+  home(g);
+  g.st.food = generateFood(g.st.snake, false, 1, g.clock);
+  g.st.nextFoodId = 2;
+  g.world.scoreboard.startCountdown(TIME_LIMIT);
+  g.phase = 'playing';
+  draw(g);
+  g.onScore(0);
+  g.onTime(TIME_LIMIT);
+  g.onPhase('playing');
+}
+
+/** Stop and Play Again: the idle board. The world, and the GPU view drawing it, are kept. */
+export function reset(g: Game) {
+  home(g);
+  g.phase = 'ready';
+  g.anchor = null;
+  draw(g);
+  g.onScore(0);
+  g.onTime(TIME_LIMIT);
+  g.onPhase('ready');
+}
+
+export function dispose(g: Game) {
+  g.world.dispose();
+}
+
+export function tick(g: Game, dt: number) {
+  if (g.world.isDisposed) return;
+  g.clock += Math.min(dt, 0.25);
+  if (g.phase === 'playing') {
+    g.pending += Math.min(dt * 1000, MAX_FRAME_MS);
+    if (g.pending >= TICK_MS) {
+      g.pending -= TICK_MS;
+      move(g);
+    }
+    draw(g);
+  }
+  g.world.update(dt);
+}
+
+function move(g: Game) {
+  const { layout: l, scene: s } = g;
+  const before = g.st.snake.slice();
+  const r = step(g.st, g.clock);
+  if (r.crash) {
+    // The snake stays where it was
+    g.prev = g.st.snake.slice();
+    g.pending = 0;
+    if (l && s) {
+      faceHead(g.world, s, g.st.direction);
+      crash(g.world, l, s, g.camera);
+    }
+    g.onEvent('crash');
+    end(g);
+    return;
+  }
+  g.prev = before;
+  if (++g.moves % 9 === 0 && s) flick(g.world, s);
+  if (r.ate) {
+    g.world.scoreboard.add(r.ate.isSpecial ? POINTS_PER_SPECIAL_FOOD : POINTS_PER_FOOD);
+    if (l && s) gulp(g.world, l, s, r.ate);
+    g.onEvent(r.ate.isSpecial ? 'special' : 'eat');
+  }
+}
+
+function end(g: Game) {
+  g.world.scoreboard.stop();
+  g.phase = 'over';
+  g.anchor = null;
+  g.onPhase('over');
+}
+
+// ── The finger ────────────────────────────────────────────────────────
+
+/** Swipes anywhere turn the snake: each stretch of 15 points one way is a turn, so one drag can chain them. */
+export function drag(g: Game, { phase, x, y, cancelled }: DragEvent) {
+  if (phase === 'start') {
+    g.anchor = [x, y];
+    return;
+  }
+  const a = g.anchor;
+  if (phase === 'end') g.anchor = null;
+  if (phase === 'end' && cancelled) return;
+  if (!a || g.phase !== 'playing') return;
+  const dx = x - a[0];
+  const dy = y - a[1];
+  if (Math.abs(dx) <= SWIPE && Math.abs(dy) <= SWIPE) return;
+  turn(g.st, Math.abs(dx) > Math.abs(dy) ? (dx > 0 ? 'RIGHT' : 'LEFT') : dy > 0 ? 'DOWN' : 'UP');
+  g.anchor = phase === 'end' ? null : [x, y];
+}

package/src/games/snake-3d/Snake3DMotion.ts

@@ -0,0 +1,22 @@
+import type { Snake } from './Snake3DRules';
+
+/** A bead's position and travel tangent, in grid units. The body follows the head's curved path. */
+export function sampleSnakeMotion(prev: Snake, cur: Snake, index: number, fraction: number): [number, number, number, number] {
+  const i = index * 2;
+  const bx = cur[i]!;
+  const by = cur[i + 1]!;
+  const ax = prev[i] ?? bx;
+  const ay = prev[i + 1] ?? by;
+  const dx = bx - ax;
+  const dy = by - ay;
+  // A new tail bead stays put while the snake grows.
+  if (dx === 0 && dy === 0) return [bx, by, 0, 0];
+  const ix = prev[i + 2] === undefined ? dx : ax - prev[i + 2]!;
+  const iy = prev[i + 3] === undefined ? dy : ay - prev[i + 3]!;
+  const t = Math.max(0, Math.min(1, fraction));
+  // Cubic Hermite: enter with the previous direction and leave with this move's direction.
+  // Adjacent moves share their tangent, so neither the head nor the body snaps at a corner.
+  const a = t * (1 - t) * (1 - t);
+  const da = 1 - 4 * t + 3 * t * t;
+  return [ax + dx * t + (ix - dx) * a, ay + dy * t + (iy - dy) * a, dx + (ix - dx) * da, dy + (iy - dy) * da];
+}