@nayan-ui/games 1.18.0 → 1.20.0

package/src/games/stack-tower/StackTowerGame.ts

@@ -0,0 +1,236 @@
+// Stack Tower's rules, with no React: build a game with `createGame`, give it a layout, `start` it and
+// `tick` it every frame. A block slides across over the tower, from alternate sides; tap to drop it.
+// It stays at full width wherever it lands; at least 40% support scores 500, plus 250 times the streak for a
+// perfect one (within 3 points). Less than 40% support ends the round; surviving the
+// two minutes wins it. As the original version, ported from its service, store and timer.
+//
+// The slide, the clock and every delay run on the game's own clock, so a reset drops whatever's
+// pending and it all pauses with the view.
+import { type Camera, type Entity, World } from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import type { HudFeedback } from '../shared/EngineHud';
+import {
+  CAMERA_TIME,
+  FRAME_MS,
+  GAME_OVER_DELAY,
+  type Layout,
+  MAX_FRAMES,
+  MIN_OVERLAP_RATIO,
+  NEXT_BLOCK_DELAY,
+  PERFECT_BONUS,
+  PERFECT_THRESHOLD,
+  POINTS_PER_BLOCK,
+  TIME_LIMIT
+} from './StackTowerConstants';
+import { buildScene, frame, land, removeScene, type Scene, setSceneTheme, slideBlock, spawnBlock, tumble } from './StackTowerScene';
+
+export type Phase = 'ready' | 'playing' | 'over';
+/** place / perfect: a block set down; miss: it missed the tower. */
+export type GameEvent = 'place' | 'perfect' | 'miss';
+
+type Placed = { x: number; y: number; level: number; entity: Entity | null };
+type Moving = { x: number; y: number; direction: number; level: number; entity: Entity | null };
+
+const WORLD_CAPACITY = 600; // the tower, the backdrop, and the dust and sparkles
+
+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,
+    tower: [] as Placed[],
+    moving: null as Moving | null,
+    falling: null as Entity | null,
+    level: 0,
+    perfectCount: 0,
+    /** Score and the countdown live in the engine (Rust), advanced by world.update. */
+    get score() {
+      return world.scoreboard.score;
+    },
+    get timeRemaining() {
+      return world.scoreboard.shownSeconds;
+    },
+    won: false,
+    /** How far the view has scrolled down to follow the tower, and where it's heading. */
+    offset: 0,
+    offsetTarget: 0,
+    // UI hooks, set by the screen.
+    onPhase: (_p: Phase) => {},
+    onScore: (_s: number) => {},
+    onTime: (_t: number) => {},
+    hudFeedback: {} as HudFeedback,
+    onEvent: (_e: GameEvent) => {}
+  };
+  world.scoreboard.reset(0, TIME_LIMIT);
+  world.scoreboard.handlers = {
+    onScore: (s) => g.onScore(s),
+    onSecond: (t) => g.onTime(t),
+    // At zero the round is won
+    onTimeUp: () => g.phase === 'playing' && end(g, true)
+  };
+  return g;
+}
+export type Game = ReturnType<typeof createGame>;
+
+const after = (g: Game, seconds: number, run: () => void) => g.world.after(seconds, run);
+
+// ── Scene ─────────────────────────────────────────────────────────────
+
+/** Lays the tower out for the view (first layout, rotation): rebuilt from the game's state. */
+export function setLayout(g: Game, l: Layout) {
+  if (g.scene) removeScene(g.world, g.scene);
+  g.layout = l;
+  g.scene = buildScene(g.world, l, g.theme);
+  if (!g.tower.length) g.tower = [base(l)];
+  for (const b of g.tower) b.entity = spawnBlock(g.world, l, b.x, b.y, b.level);
+  if (g.moving) g.moving.entity = spawnBlock(g.world, l, g.moving.x, g.moving.y, g.moving.level);
+  frame(g.world, l, g.scene, g.camera, g.offset);
+}
+
+export function setTheme(g: Game, theme: GameTheme) {
+  g.theme = theme;
+  if (g.scene) setSceneTheme(g.world, g.scene, theme);
+}
+
+/** The base block, centred in the game area. */
+const base = (l: Layout): Placed => ({ x: l.left + (l.gameWidth - l.blockWidth) / 2, y: l.baseY, level: 0, entity: null });
+
+// ── Run ───────────────────────────────────────────────────────────────
+
+export function start(g: Game) {
+  if (g.phase !== 'ready' || !g.layout) return;
+  g.phase = 'playing';
+  g.level = 0;
+  g.perfectCount = 0;
+  g.world.scoreboard.reset();
+  g.world.scoreboard.startCountdown(TIME_LIMIT);
+  g.onScore(0);
+  g.onTime(TIME_LIMIT);
+  g.onPhase('playing');
+  spawnMoving(g, g.tower[g.tower.length - 1]!);
+}
+
+/** Back to the base block alone (Stop, Play Again). The world, and the GPU view drawing it, are kept. */
+export function reset(g: Game) {
+  g.world.cancelTimers();
+  for (const b of g.tower) if (b.entity != null) g.world.despawn(b.entity);
+  if (g.moving?.entity != null) g.world.despawn(g.moving.entity);
+  if (g.falling != null) g.world.despawn(g.falling);
+  g.falling = null;
+  g.moving = null;
+  g.level = 0;
+  g.perfectCount = 0;
+  g.world.scoreboard.reset(0, TIME_LIMIT);
+  g.won = false;
+  g.offset = 0;
+  g.offsetTarget = 0;
+  g.phase = 'ready';
+  const l = g.layout;
+  g.tower = l ? [base(l)] : [];
+  if (l) for (const b of g.tower) b.entity = spawnBlock(g.world, l, b.x, b.y, b.level);
+  g.hudFeedback.message = undefined;
+  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;
+  const l = g.layout;
+  // The slide, bouncing between the game area's edges
+  const m = g.moving;
+  if (l && m && g.phase === 'playing') {
+    const frames = Math.min((dt * 1000) / FRAME_MS, MAX_FRAMES);
+    const maxX = l.left + l.gameWidth - l.blockWidth;
+    let x = m.x + m.direction * l.speed * frames;
+    if (x <= l.left) {
+      x = l.left;
+      m.direction = 1;
+    } else if (x >= maxX) {
+      x = maxX;
+      m.direction = -1;
+    }
+    m.x = x;
+    if (m.entity != null) slideBlock(g.world, l, m.entity, m.x, m.y);
+  }
+  // The view follows the tower up, easing in
+  if (l && g.scene) {
+    g.offset += (g.offsetTarget - g.offset) * Math.min(1, dt / (CAMERA_TIME / 3));
+    frame(g.world, l, g.scene, g.camera, g.offset);
+  }
+  g.world.update(dt);
+}
+
+function end(g: Game, won: boolean) {
+  g.world.scoreboard.stop();
+  g.won = won;
+  g.phase = 'over';
+  g.onPhase('over');
+}
+
+/** The next block, one row up, sliding in from the side the level says. */
+function spawnMoving(g: Game, below: Placed) {
+  const l = g.layout;
+  if (!l) return;
+  g.level += 1;
+  const y = below.y - l.blockHeight;
+  const direction = g.level % 2 === 0 ? 1 : -1;
+  const x = direction === 1 ? l.left : l.left + l.gameWidth - l.blockWidth;
+  g.moving = { x, y, direction, level: g.level, entity: spawnBlock(g.world, l, x, y, g.level, true) };
+  // Scroll once the new row is above 40% of the way down the screen
+  const mid = l.height * 0.4;
+  if (y < mid) g.offsetTarget = mid - y;
+}
+
+// ── The tap ───────────────────────────────────────────────────────────
+
+/** A tap anywhere drops the sliding block where it is. */
+export function tap(g: Game) {
+  const l = g.layout;
+  const m = g.moving;
+  if (!l || !m || g.phase !== 'playing') return;
+  const top = g.tower[g.tower.length - 1]!;
+  g.moving = null;
+  const overlap = Math.min(m.x + l.blockWidth, top.x + l.blockWidth) - Math.max(m.x, top.x);
+  if (overlap < l.blockWidth * MIN_OVERLAP_RATIO) {
+    if (m.entity != null) {
+      tumble(g.world, l, m.entity, m.x, m.y, m.direction, m.level);
+      const e = m.entity;
+      g.falling = e;
+      after(g, 0.5, () => {
+        g.world.despawn(e);
+        g.falling = null;
+      });
+    }
+    g.onEvent('miss');
+    // The clock stops with the miss: it can't run out into a win before the round ends
+    g.world.scoreboard.stop();
+    after(g, GAME_OVER_DELAY, () => end(g, false));
+    return;
+  }
+  const perfect = Math.abs(overlap - l.blockWidth) <= PERFECT_THRESHOLD;
+  if (perfect) {
+    g.perfectCount += 1;
+    g.hudFeedback.message = 'PERFECT!';
+    g.onEvent('perfect');
+  } else {
+    g.perfectCount = 0;
+    g.onEvent('place');
+  }
+  const placed: Placed = { x: m.x, y: m.y, level: m.level, entity: m.entity };
+  g.tower.push(placed);
+  if (placed.entity != null) land(g.world, l, placed.entity, placed.x, placed.y, placed.level, perfect);
+  g.world.scoreboard.add(POINTS_PER_BLOCK + (perfect ? PERFECT_BONUS * g.perfectCount : 0));
+  after(g, NEXT_BLOCK_DELAY, () => {
+    if (g.phase === 'playing') spawnMoving(g, placed);
+  });
+}

package/src/games/stack-tower/StackTowerScene.ts

@@ -0,0 +1,186 @@
+// Everything Stack Tower draws: a tower of glossy, bevelled blocks (each a slab with real depth) on a
+// stone plinth, seen from a little above and in front (shared/EngineTilt: an orthographic camera
+// tipped forward, one world unit per point), over the themed backdrop. The camera scrolls up as the
+// tower grows. A placed block glows and puffs dust; a perfect one rings gold; a miss tumbles away.
+// Every block is the same mesh (one instanced draw), tinted per block.
+//
+// Tower positions are view points with y down (as the rules use, and as the original game drew them);
+// a block's front face is centred where the original game drew the block.
+import {
+  type Color,
+  effects,
+  type Entity,
+  extrude,
+  type Geometry,
+  merge,
+  type Model,
+  Path,
+  recolor,
+  shapeGeometry,
+  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 { aimTilted, placeTiltedBackdrop, type TiltView } from '../shared/EngineTilt';
+import { toColor } from '../shared/EngineUtils';
+import { BLOCK_COLORS, type Layout, MISS_TIME, SPAWN_FADE } from './StackTowerConstants';
+
+const meshes = new Map<string, Model>();
+const cached = (key: string, build: () => Model) => {
+  let m = meshes.get(key);
+  if (!m) {
+    m = cacheGameAsset('stack-tower/StackTowerScene:' + key, build);
+    meshes.set(key, m);
+  }
+  return m;
+};
+
+/** Shades a solid by which way each face looks: the top brightest, the front its color, the ends and underside darker. */
+const shadeFaces = (g: Geometry) =>
+  recolor(g, ({ normal: [x, y, z] }) => {
+    const k = y > 0.6 ? 1 : y < -0.6 ? 0.45 : Math.abs(x) > 0.6 ? 0.68 : z > 0.6 ? 0.88 : 0.7;
+    return [k, k, k, 1];
+  });
+
+/**
+ * A block `w` x `h` across its face and `d` deep: a solid slab with rounded corners, shaded face by
+ * face so its depth reads, with a bevelled lighter cap along the top.
+ */
+const blockMesh = (w: number, h: number, d: number) =>
+  cached(`st-block-v2:${w}:${h}:${d.toFixed(1)}`, () => {
+    const r = Math.min(4, h / 4);
+    const bevel = Math.min(2.5, h * 0.12);
+    return createShape(
+      merge([
+        { geometry: shadeFaces(extrude(new Path().addRoundedRect(-w / 2, -h / 2, w, h - bevel, r), { depth: d })) },
+        // The cap: a little narrower all round, so its edge reads as a bevel catching the light
+        { geometry: shapeGeometry('cube'), position: [0, h / 2 - bevel / 2, 0], scale: [w - bevel * 2, bevel, d - bevel * 2], color: [1, 1, 1, 1] }
+      ]),
+      { shine: 0.45 }
+    );
+  });
+
+const BACKDROP_DEPTH = 60;
+/** The camera stays this far from the tower in view, wherever it's scrolled: well inside its depth range. */
+const EYE_DISTANCE = 250;
+const PLINTH: Color = toColor('#4A4F66');
+
+export type Scene = { frameOffset?: number; backdrop: Entity; plinth: Entity; blocks: Entity[]; moving: Entity | null };
+
+/** The view the camera frames, scrolled down by `offset` points as the tower grows. */
+export const viewFor = (l: Layout, offset: number): TiltView => ({ width: l.width, height: l.height, centerY: l.height / 2 + offset, tilt: l.tilt });
+
+/** A block's face centre in the world, from its top-left in tower points. */
+export function blockAt(l: Layout, x: number, y: number): Vec3 {
+  return [x + l.blockWidth / 2 - l.width / 2, (l.height / 2 - (y + l.blockHeight / 2)) / Math.cos(l.tilt), 0];
+}
+
+export const blockColor = (level: number) => toColor(BLOCK_COLORS[level % BLOCK_COLORS.length]!);
+
+export function buildScene(world: World, l: Layout, theme: GameTheme): Scene {
+  const backdrop = spawnBackdrop(world, l.width, l.height, -BACKDROP_DEPTH, theme);
+  // Under the base block: a stone plinth reaching down past the screen's foot
+  const [bx, by] = blockAt(l, l.left + (l.gameWidth - l.blockWidth) / 2, l.baseY);
+  const plinthHeight = l.height;
+  const plinth = world.spawn({
+    mesh: 'roundedBox',
+    position: [bx, by - l.blockHeight / 2 - plinthHeight / 2, 0],
+    scale: [l.blockWidth * 1.35, plinthHeight, l.blockDepth * 1.3],
+    color: PLINTH,
+    pickable: false
+  });
+  return { backdrop, plinth, blocks: [], moving: null };
+}
+
+export function removeScene(world: World, s: Scene) {
+  for (const e of [s.backdrop, s.plinth, ...s.blocks, ...(s.moving != null ? [s.moving] : [])]) world.despawn(e);
+}
+
+export function setSceneTheme(world: World, s: Scene, theme: GameTheme) {
+  setBackdropTheme(world, s.backdrop, theme);
+}
+
+/** Frames the tower: the camera scrolled `offset` down, the backdrop kept fixed behind it. */
+export function frame(world: World, l: Layout, s: Scene, camera: Parameters<typeof aimTilted>[0], offset: number) {
+  if (s.frameOffset === offset) return;
+  s.frameOffset = offset;
+  const v = viewFor(l, offset);
+  aimTilted(camera, v);
+  // Slide the camera along its own line of sight back onto the tower's plane (z = 0): the picture is
+  // the same (it's orthographic) but the tower in view stays a fixed distance away, so blocks high up
+  // never cross the near plane and vanish.
+  const [ex, ey, ez] = camera.eye;
+  const [tx, ty, tz] = camera.target;
+  const len = Math.hypot(ex - tx, ey - ty, ez - tz);
+  const back: Vec3 = [(ex - tx) / len, (ey - ty) / len, (ez - tz) / len];
+  const t = -tz / back[2];
+  const q: Vec3 = [tx + back[0] * t, ty + back[1] * t, 0];
+  camera.target = [q[0], q[1], q[2]];
+  camera.eye = [q[0] + back[0] * EYE_DISTANCE, q[1] + back[1] * EYE_DISTANCE, q[2] + back[2] * EYE_DISTANCE];
+  placeTiltedBackdrop(world, s.backdrop, v, BACKDROP_DEPTH);
+}
+
+// ── Blocks ────────────────────────────────────────────────────────────
+
+export function spawnBlock(world: World, l: Layout, x: number, y: number, level: number, fadeIn = false): Entity {
+  const color = blockColor(level);
+  const e = world.spawn({
+    // As tall as its row on the tilted board (rows are blockHeight / cos apart), so stacked blocks meet with no gap
+    mesh: blockMesh(l.blockWidth, Math.round((l.blockHeight / Math.cos(l.tilt)) * 10) / 10, l.blockDepth),
+    position: blockAt(l, x, y),
+    color: fadeIn ? [color[0], color[1], color[2], 0] : color,
+    pickable: false
+  });
+  if (fadeIn) world.animate(e, { color }, { duration: SPAWN_FADE, easing: 'easeOut' });
+  return e;
+}
+
+export function slideBlock(world: World, l: Layout, e: Entity, x: number, y: number) {
+  world.set(e, { position: blockAt(l, x, y) });
+}
+
+/** A block set down: it flashes bright and puffs dust from under its ends; a perfect one also rings gold. */
+export function land(world: World, l: Layout, e: Entity, x: number, y: number, level: number, perfect: boolean) {
+  const color = blockColor(level);
+  const k = perfect ? 1.7 : 1.35;
+  world.animate(e, [{ color: [color[0] * k, color[1] * k, color[2] * k, 1], at: 0.2 }, { color }], { duration: 0.35 });
+  world.animate(e, [{ scale: [1.04, 0.92, 1.04], at: 0.3 }, { scale: 1 }], { duration: 0.2 });
+  const [cx, cy] = blockAt(l, x, y);
+  const foot = cy - l.blockHeight / 2;
+  for (const side of [-1, 1])
+    effects.dust(world, {
+      position: [cx + (side * l.blockWidth) / 2, foot, l.blockDepth * 0.3],
+      count: 4,
+      size: l.blockHeight * 0.7,
+      speed: l.blockHeight * 2,
+      direction: [side, 0.3, 0],
+      spread: 0.8,
+      lifetime: 0.4,
+      color: [1, 1, 1, 0.55]
+    });
+  if (perfect)
+    effects.sparkle(world, {
+      position: [cx, cy, l.blockDepth * 0.55],
+      count: 20,
+      size: l.blockHeight * 0.3,
+      speed: l.blockWidth * 1.4,
+      lifetime: 0.5,
+      colors: [toColor('#FFD700'), toColor('#FFF59D'), [1, 1, 1, 1]]
+    });
+}
+
+/** A missed block tumbles off the way it was sliding, fading as it goes. */
+export function tumble(world: World, l: Layout, e: Entity, x: number, y: number, direction: number, level: number) {
+  const [cx, cy] = blockAt(l, x, y);
+  const [r, g, b] = blockColor(level);
+  const side = direction >= 0 ? 1 : -1;
+  world.animate(
+    e,
+    { position: [cx + side * l.blockWidth * 0.5, cy - l.blockHeight * 8, l.blockDepth * 0.3] },
+    { duration: MISS_TIME, easing: 'easeIn' }
+  );
+  world.animate(e, { turn: [0.6, 0, -side * 1.4] }, { duration: MISS_TIME, easing: 'easeIn' });
+  world.animate(e, { color: [r, g, b, 0] }, { duration: MISS_TIME, easing: 'easeIn' });
+}

package/src/games/sudoku/Sudoku.tsx

@@ -0,0 +1,73 @@
+// Sudoku's screen, on the Nayan engine: the board, its cells and digits and the number keys are one 3D
+// scene (an orthographic camera leaning back over the board), under Playtura's scoreboard, controls and
+// modals. The play is in SudokuGame.ts (the puzzle and scoring in SudokuRules.ts), what it draws in
+// SudokuScene.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. Digits drop in and units flash in the
+// engine's Rust core; JS reads the finger and steps the clock once a frame.
+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, LOW_TIME, TIME_LIMIT } from './SudokuConstants';
+import { createGame, dispose, drag, type GameEvent, reset, setLayout, setTheme, start, tick } from './SudokuGame';
+
+const SOUNDS = GAME_SOUNDS.SUDOKU;
+
+/** Each event's sound and haptic, as the original version played them. */
+const FEEDBACK: Record<GameEvent, { sound: (typeof SOUNDS)[keyof typeof SOUNDS]; haptic: HapticType }> = {
+  place: { sound: SOUNDS.PLACE, haptic: HapticType.LIGHT },
+  wrong: { sound: SOUNDS.ERROR, haptic: HapticType.ERROR },
+  win: { sound: SOUNDS.WIN, haptic: HapticType.SUCCESS },
+  lose: { sound: SOUNDS.GAME_OVER, haptic: HapticType.ERROR }
+};
+
+export const Sudoku = engineGame(GAME_IDS.SUDOKU, (props) => {
+  const [score, setScore] = useLiveState(0);
+  const [time, setTime] = useLiveState(TIME_LIMIT);
+
+  // Win or lose as the game ends; Stop deals a fresh puzzle, as the original game
+  const { theme, status, screen, gameOver } = useEngineGame(props, {
+    gameId: GAME_IDS.SUDOKU,
+    create: createGame,
+    start,
+    reset,
+    dispose,
+    tick,
+    setTheme,
+    resize: (g, width, height, offset) => {
+      const l = getLayout(width, height, offset);
+      setLayout(g, l);
+      return l.board;
+    },
+    drag,
+    sounds: SOUNDS,
+    onStart: (fx) => fx(SOUNDS.START, HapticType.SUCCESS),
+    onStop: (fx) => fx(null, HapticType.MEDIUM),
+    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, LOW_TIME)]}
+      subtext="Complete the number grid!"
+      gameOver={gameOver({
+        title: status === 'win' ? 'SOLVED!' : 'GAME OVER',
+        message: status === 'win' ? 'Puzzle completed!' : 'Time ran out!',
+        scoreLabel: 'Final Score',
+        score,
+        buttonText: 'Solve Again!'
+      })}
+    />
+  );
+});

package/src/games/sudoku/SudokuConstants.ts

@@ -0,0 +1,127 @@
+// Sudoku's timings, colors and layout. Rules and scores (in SudokuRules.ts) match the original version
+// (games/sudoku), so scores carry over.
+import { getScoreBoardTop } from '../shared/EngineHud';
+import type { TiltView } from '../shared/EngineTilt';
+import { frontLight, gameWidthFor } from '../shared/EngineUtils';
+
+export const TIME_LIMIT = 15 * 60; // fifteen minutes
+export const LOW_TIME = 60; // the timer turns red from here
+export const FLASH_STEP = 0.028; // a completed unit's flash sweeps out from the cell placed, this much a cell
+export const TAP_SLOP = 12; // points a finger may wander and still tap
+
+// ── Colors (the original board's) ─────────────────────────────────────────
+
+export const COLORS = {
+  CELL: '#ffffff',
+  GIVEN: '#E8EAF6',
+  SELECTED: '#BBDEFB',
+  SAME_NUMBER: '#E3F2FD',
+  PEER: '#F3E5F5',
+  ERROR: '#FFCDD2',
+  TEXT_GIVEN: '#1a237e',
+  TEXT_PLACED: '#1565C0',
+  TEXT_ERROR: '#D32F2F',
+  LINES: '#1a237e', // the thin lines and thick box borders show through between the cells
+  FRAME: '#5c4033',
+  WELL: '#3a2518',
+  KEY: '#e8ddd0',
+  KEY_TEXT: '#3e2723',
+  KEY_REMAINING: '#8d6e63',
+  KEY_DISABLED: '#bdb5ad',
+  KEY_DISABLED_TEXT: '#9e9e9e'
+} 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 anywhere. */
+export const LIGHT = frontLight([0, 0, 1], 1);
+export const CELL_HEIGHT = 0.12; // of a cell
+export const KEY_HEIGHT = 0.3; // of a key's width
+
+// ── Layout (view points) ──────────────────────────────────────────────
+
+const SCOREBOARD_HEIGHT = 82;
+const CONTROLS_HEIGHT = 120;
+export const SPACING = 1.5; // between cells in a box
+export const BORDER = 3.5; // round and between the boxes
+const PAD = 8; // the board's rim
+const KEY_GAP = 4;
+const PAD_GAP = 16; // between the board and the keys
+
+export type Layout = TiltView & {
+  cell: number;
+  /** The grid's side (cells, lines and borders), the board's (with its rim), where the board's centre is (world y). */
+  grid: number;
+  board: number;
+  boardY: number;
+  /** The number keys: their width, height, pitch and the row's centre (world y). */
+  key: number;
+  keyH: number;
+  keyPitch: number;
+  keysY: number;
+};
+
+const gridSide = (cell: number) => cell * 9 + SPACING * 6 + BORDER * 4;
+
+/** Cells as big as the width allows (as the original grid), smaller if the screen is short; the keys spread under the board. */
+export function getLayout(width: number, height: number, offset: number): Layout {
+  const top = getScoreBoardTop(offset) + SCOREBOARD_HEIGHT;
+  const room = Math.max(260, height - top - CONTROLS_HEIGHT);
+  const usable = gameWidthFor(width);
+  const fromWidth = (usable - PAD * 2 - SPACING * 6 - BORDER * 4) / 9;
+  // The board, the gap and the key row (a key's height about 1.25 of a cell) fill the tilted room
+  const fromHeight = (room / Math.cos(TILT) - PAD * 2 - SPACING * 6 - BORDER * 4 - PAD_GAP) / (9 + 1.25);
+  const cell = Math.max(18, Math.floor(Math.min(fromWidth, fromHeight)));
+  const grid = gridSide(cell);
+  const board = grid + PAD * 2;
+  const key = Math.floor((board - KEY_GAP * 8) / 9);
+  const keyH = Math.round(Math.min(cell * 1.25, key * 1.3));
+  const total = board + PAD_GAP + keyH;
+  return {
+    width,
+    height,
+    tilt: TILT,
+    centerY: top + room / 2,
+    cell,
+    grid,
+    board,
+    boardY: total / 2 - board / 2,
+    key,
+    keyH,
+    keyPitch: key + KEY_GAP,
+    keysY: -total / 2 + keyH / 2
+  };
+}
+
+/** A cell's offset from the grid's top-left corner, along a row or down a column. */
+const along = (l: Layout, i: number) => BORDER + i * (l.cell + SPACING) + Math.floor(i / 3) * (BORDER - SPACING);
+
+/** A cell's centre, in world units. */
+export function cellCentre(l: Layout, row: number, col: number): [number, number] {
+  return [-l.grid / 2 + along(l, col) + l.cell / 2, l.boardY + l.grid / 2 - along(l, row) - l.cell / 2];
+}
+
+/** A number key's centre (n = 1..9), in world units. */
+export const keyCentre = (l: Layout, n: number): [number, number] => [(n - 5) * l.keyPitch, l.keysY];
+
+/** The cell a board point is on (a line between counts as the nearer cell), or null off the grid. */
+export function cellAt(l: Layout, x: number, y: number): [number, number] | null {
+  const gx = x + l.grid / 2;
+  const gy = l.boardY + l.grid / 2 - y;
+  if (gx < 0 || gy < 0 || gx > l.grid || gy > l.grid) return null;
+  const pick = (v: number) => {
+    let best = 0;
+    for (let i = 1; i < 9; i++) if (Math.abs(along(l, i) + l.cell / 2 - v) < Math.abs(along(l, best) + l.cell / 2 - v)) best = i;
+    return best;
+  };
+  return [pick(gy), pick(gx)];
+}
+
+/** The number key a point is on, or 0. */
+export function keyAt(l: Layout, x: number, y: number): number {
+  if (Math.abs(y - l.keysY) > l.keyH / 2 + 4) return 0;
+  const n = Math.round(x / l.keyPitch) + 5;
+  return n >= 1 && n <= 9 && Math.abs(x - (n - 5) * l.keyPitch) <= l.keyPitch / 2 ? n : 0;
+}