@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/colors-sort/ColorsSortConstants.ts

@@ -0,0 +1,119 @@
+// Colors Sort's rules, sizes, timings and layout. Rules, scoring and sizes match the original version
+// (games/colors-sort), so scores carry over.
+import { getScoreBoardTop } from '../shared/EngineHud';
+import type { TiltView } from '../shared/EngineTilt';
+import { frontLight, gameWidthFor } from '../shared/EngineUtils';
+
+// ── Rules ─────────────────────────────────────────────────────────────
+
+export const COLORS = ['#FF4444', '#32CD32', '#4169E1', '#FFD700', '#00CED1'] as const; // red, green, blue, yellow, cyan
+export const PIECES_PER_COLOR = 4;
+export const TUBES = 6; // five full, one empty
+export const CAPACITY = PIECES_PER_COLOR + 1; // a spare slot to shuffle with
+export const TIME_LIMIT = 120; // seconds
+export const SCORE_BASE = 100; // calculateTimeBasedScore's base, as before
+
+// ── Sizes (points; tablets get the original version's larger set) ─────────
+
+const PHONE = {
+  tubeWidth: 80,
+  tubeHeight: 240,
+  border: 4,
+  pieceWidth: 64,
+  pieceHeight: 35,
+  pieceGap: 5,
+  padBottom: 4,
+  columnGap: 15,
+  rowGap: 15,
+  lift: 15
+};
+const TABLET = {
+  tubeWidth: 112,
+  tubeHeight: 336,
+  border: 5,
+  pieceWidth: 82,
+  pieceHeight: 50,
+  pieceGap: 7,
+  padBottom: 6,
+  columnGap: 20,
+  rowGap: 20,
+  lift: 20
+};
+const TABLET_WIDTH = 640;
+const COLUMNS = 3;
+
+// ── Feel (seconds) ────────────────────────────────────────────────────
+
+export const LIFT_TIME = 0.18;
+export const MOVE_TIME = 0.36; // up out of one tube, across, and down into the other
+export const SHAKE_TIME = 0.3;
+
+// ── The scene ─────────────────────────────────────────────────────────
+
+/** The camera looks down a little from in front, so the tubes' mouths and the pieces' tops show. */
+export const TILT = -0.3;
+/** Lit from the upper left; surfaces facing the camera (+z) keep their exact color. */
+export const LIGHT = frontLight([-0.4, 0.55, 1], 0.5);
+
+// ── Layout ────────────────────────────────────────────────────────────
+
+const SCOREBOARD_HEIGHT = 82;
+const CONTROLS_HEIGHT = 110;
+const SHELF_HEIGHT = 12; // the rack each row stands on
+
+export type Layout = TiltView & {
+  /** Every size below is already scaled to fit. */
+  tubeRadius: number;
+  tubeHeight: number;
+  pieceRadius: number;
+  pieceHeight: number;
+  pieceGap: number;
+  padBottom: number;
+  lift: number;
+  shelfHeight: number;
+  /** Each tube's base centre in the world (x right, y up, z toward the camera). */
+  tubes: [number, number][];
+  /** The rows' shelves: their top-face y and width. */
+  shelves: { y: number; width: number }[];
+};
+
+/** Two rows of three tubes on shelves, as big as the original grid (smaller if the screen is short), centred under the scoreboard. */
+export function getLayout(width: number, height: number, offset: number): Layout {
+  const base = width > TABLET_WIDTH ? TABLET : PHONE;
+  const tilt = TILT;
+  const cos = Math.cos(tilt);
+  const top = getScoreBoardTop(offset) + SCOREBOARD_HEIGHT + 16;
+  const room = Math.max(240, height - top - CONTROLS_HEIGHT);
+  const gridWidth = COLUMNS * base.tubeWidth + (COLUMNS - 1) * base.columnGap;
+  // Rows: each a tube (plus the lifted piece's headroom) on a shelf
+  const rowHeight = base.tubeHeight + base.lift + base.pieceHeight * 0.6 + SHELF_HEIGHT;
+  // ...plus what the tilt shows of the tubes' and shelves' depth (front edge down, back edge up)
+  const gridHeight = (2 * rowHeight + base.rowGap) * cos + base.tubeWidth * 1.6 * Math.abs(Math.sin(tilt));
+  const s = Math.min(1, gameWidthFor(width) / (gridWidth + base.columnGap * 2), room / gridHeight);
+  const centerY = top + room / 2;
+  const view: TiltView = { width, height, centerY, tilt };
+  const gridSpan = (2 * rowHeight + base.rowGap) * s;
+  // World y of each row's tube bases, from the top row down (the grid centred on the origin)
+  const bases = [gridSpan / 2 - rowHeight * s + SHELF_HEIGHT * s, gridSpan / 2 - rowHeight * s * 2 - base.rowGap * s + SHELF_HEIGHT * s];
+  const pitch = (base.tubeWidth + base.columnGap) * s;
+  const tubes: [number, number][] = [];
+  for (const y of bases) for (let c = 0; c < COLUMNS; c++) tubes.push([(c - 1) * pitch, y]);
+  return {
+    ...view,
+    tubeRadius: (base.tubeWidth / 2) * s,
+    tubeHeight: base.tubeHeight * s,
+    pieceRadius: (base.pieceWidth / 2) * s,
+    pieceHeight: base.pieceHeight * s,
+    pieceGap: base.pieceGap * s,
+    padBottom: (base.border + base.padBottom) * s,
+    lift: base.lift * s,
+    shelfHeight: SHELF_HEIGHT * s,
+    tubes,
+    shelves: bases.map((y) => ({ y, width: gridWidth * s + base.columnGap * s * 2 }))
+  };
+}
+
+/** Where the piece `slot` places up from a tube's bottom sits (its base), in world y. */
+export const slotY = (l: Layout, tube: number, slot: number) => l.tubes[tube]![1] + l.padBottom + slot * (l.pieceHeight + l.pieceGap);
+/** Where a picked-up piece hovers: just out of its tube's mouth. */
+export const hoverY = (l: Layout, tube: number) => l.tubes[tube]![1] + l.tubeHeight + l.lift;

package/src/games/colors-sort/ColorsSortGame.ts

@@ -0,0 +1,246 @@
+// Colors Sort's rules, with no React: build a game with `createGame` (it deals a shuffled board), give
+// it a layout, `start` it and `tick` it every frame. Five colors of four pucks are shuffled into five
+// tubes, with a sixth left empty; each holds five. Tap a tube to pick up its top puck, tap another to
+// drop it there (any color on any color, as long as the tube isn't full), or the same one to put it
+// back. Gather every color into a tube of its own within two minutes to win.
+import { type Camera, type Entity, World } from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import { aimTilted, unproject } from '../shared/EngineTilt';
+import { CAPACITY, COLORS, hoverY, type Layout, PIECES_PER_COLOR, TIME_LIMIT, TUBES } from './ColorsSortConstants';
+import {
+  buildScene,
+  celebrate,
+  completeTube,
+  liftPiece,
+  lowerPiece,
+  movePiece,
+  removeScene,
+  type Scene,
+  setSceneTheme,
+  shakeTube,
+  showCork,
+  spawnPiece
+} from './ColorsSortScene';
+
+export type Phase = 'ready' | 'playing' | 'over';
+/** pick: a puck lifted; drop: a puck put back; move: one moved; refuse: an empty pick-up or a full tube; complete: all sorted. */
+export type GameEvent = 'pick' | 'drop' | 'move' | 'refuse' | 'complete';
+
+const WORLD_CAPACITY = 300; // tubes (6 parts each), pucks, the backdrop, and bursts
+
+/** A fresh shuffle: color indices, bottom to top, in each tube. */
+function deal(): number[][] {
+  const pieces = COLORS.flatMap((_, c) => Array<number>(PIECES_PER_COLOR).fill(c));
+  for (let i = pieces.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [pieces[i], pieces[j]] = [pieces[j]!, pieces[i]!];
+  }
+  return Array.from({ length: TUBES }, (_, t) => (t < COLORS.length ? pieces.splice(0, PIECES_PER_COLOR) : []));
+}
+
+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,
+    tubes: deal(),
+    /** Each tube's puck entities, parallel to `tubes`. */
+    pieces: [] as Entity[][],
+    selected: null as number | null,
+    /** Seconds played, and left: the countdown lives in the engine (Rust), advanced by world.update. */
+    get time() {
+      return TIME_LIMIT - world.scoreboard.shownSeconds;
+    },
+    get timeLeft() {
+      return world.scoreboard.shownSeconds;
+    },
+    timedOut: false,
+    // UI hooks, set by the screen.
+    onPhase: (_p: Phase) => {},
+    onTime: (_t: number) => {},
+    onEvent: (_e: GameEvent) => {}
+  };
+  world.scoreboard.reset(0, TIME_LIMIT);
+  world.scoreboard.handlers = {
+    onSecond: (t) => g.onTime(t),
+    onTimeUp: () => {
+      if (g.phase !== 'playing') return;
+      g.timedOut = true;
+      end(g);
+    }
+  };
+  return g;
+}
+export type Game = ReturnType<typeof createGame>;
+
+/** A tube holding a whole color (and nothing else). */
+const sorted = (tube: number[]) => tube.length === PIECES_PER_COLOR && tube.every((c) => c === tube[0]);
+
+/** Every color gathered: each tube empty, or one color only and all of it (or a full tube of it). */
+function solved(tubes: number[][]) {
+  const totals = new Map<number, number>();
+  for (const t of tubes) {
+    if (!t.length) continue;
+    if (!t.every((c) => c === t[0])) return false;
+    totals.set(t[0]!, (totals.get(t[0]!) ?? 0) + t.length);
+  }
+  return tubes.every((t) => !t.length || t.length === CAPACITY || t.length === totals.get(t[0]!));
+}
+
+// ── Scene ─────────────────────────────────────────────────────────────
+
+/** Lays the scene out for the view (first layout, header height, rotation): rebuilt from the board. */
+export function setLayout(g: Game, l: Layout) {
+  if (g.scene) removeScene(g.world, g.scene);
+  for (const e of g.pieces.flat()) g.world.despawn(e);
+  g.layout = l;
+  aimTilted(g.camera, l);
+  g.scene = buildScene(g.world, l, g.theme);
+  spawnPieces(g);
+}
+
+export function setTheme(g: Game, theme: GameTheme) {
+  g.theme = theme;
+  if (g.scene) setSceneTheme(g.world, g.scene, theme);
+}
+
+function spawnPieces(g: Game) {
+  const { layout: l, scene: s } = g;
+  if (!l || !s) return;
+  g.pieces = g.tubes.map((tube, t) => tube.map((color, slot) => spawnPiece(g.world, l, color, t, slot)));
+  // A picked-up puck stays up through a relayout
+  if (g.selected != null) {
+    const top = g.pieces[g.selected]![g.pieces[g.selected]!.length - 1];
+    if (top != null) liftPiece(g.world, l, top, g.selected);
+  }
+  g.tubes.forEach((tube, t) => showCork(g.world, l, s.tubes[t]!, t, sorted(tube)));
+}
+
+// ── Run ───────────────────────────────────────────────────────────────
+
+/** Plays the board that's showing. */
+export function start(g: Game) {
+  if (g.phase !== 'ready') return;
+  g.phase = 'playing';
+  g.world.scoreboard.startCountdown(TIME_LIMIT);
+  g.onTime(TIME_LIMIT);
+  g.onPhase('playing');
+}
+
+/** A freshly shuffled board, not started (Stop, Play Again). The world, and the GPU view drawing it, are kept. */
+export function reset(g: Game) {
+  for (const e of g.pieces.flat()) g.world.despawn(e);
+  g.tubes = deal();
+  g.selected = null;
+  g.world.scoreboard.reset(0, TIME_LIMIT);
+  g.timedOut = false;
+  g.phase = 'ready';
+  spawnPieces(g);
+  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.world.update(dt);
+}
+
+function end(g: Game) {
+  g.world.scoreboard.stop();
+  // A puck still in the air goes back into its tube
+  const { layout: l } = g;
+  if (l && g.selected != null) {
+    const t = g.selected;
+    const top = g.pieces[t]![g.pieces[t]!.length - 1];
+    if (top != null) lowerPiece(g.world, l, top, t, g.tubes[t]!.length - 1);
+  }
+  g.selected = null;
+  g.phase = 'over';
+  g.onPhase('over');
+}
+
+// ── Taps ──────────────────────────────────────────────────────────────
+
+/** The tube under a view point: its column, from just under its shelf to above its mouth (where a puck hovers). */
+export function tubeAt(g: Game, x: number, y: number): number | null {
+  const l = g.layout;
+  if (!l) return null;
+  const [wx, wy] = unproject(l, x, y, 0);
+  const pitch = l.tubes.length > 1 ? Math.abs(l.tubes[1]![0] - l.tubes[0]![0]) : l.tubeRadius * 3;
+  let best: number | null = null;
+  let bestDistance = Infinity;
+  l.tubes.forEach(([tx, ty], i) => {
+    if (Math.abs(wx - tx) > pitch / 2) return;
+    if (wy < ty - l.shelfHeight * 2 || wy > hoverY(l, i) + l.pieceHeight * 1.2) return;
+    const distance = Math.abs(wx - tx);
+    if (distance < bestDistance) {
+      best = i;
+      bestDistance = distance;
+    }
+  });
+  return best;
+}
+
+export function tap(g: Game, x: number, y: number) {
+  if (g.phase !== 'playing') return;
+  const t = tubeAt(g, x, y);
+  if (t != null) choose(g, t);
+}
+
+/** The tube tapped: pick up from it, put back into it, or move the lifted puck onto it. */
+export function choose(g: Game, t: number) {
+  const { layout: l, scene: s } = g;
+  if (!l || !s || g.phase !== 'playing') return;
+  const tube = g.tubes[t]!;
+  const pieces = g.pieces[t]!;
+  if (g.selected == null) {
+    if (!tube.length) {
+      shakeTube(g.world, l, s.tubes[t]!, pieces);
+      g.onEvent('refuse');
+      return;
+    }
+    g.selected = t;
+    liftPiece(g.world, l, pieces[pieces.length - 1]!, t);
+    g.onEvent('pick');
+    return;
+  }
+  const from = g.selected;
+  g.selected = null;
+  if (from === t) {
+    lowerPiece(g.world, l, pieces[pieces.length - 1]!, t, tube.length - 1);
+    g.onEvent('drop');
+    return;
+  }
+  // A full tube takes nothing more: the lifted puck goes home and the full tube shakes
+  if (tube.length >= CAPACITY) {
+    const home = g.pieces[from]!;
+    lowerPiece(g.world, l, home[home.length - 1]!, from, g.tubes[from]!.length - 1);
+    shakeTube(g.world, l, s.tubes[t]!, pieces);
+    g.onEvent('refuse');
+    return;
+  }
+  const color = g.tubes[from]!.pop()!;
+  const piece = g.pieces[from]!.pop()!;
+  tube.push(color);
+  pieces.push(piece);
+  movePiece(g.world, l, piece, from, t, tube.length - 1);
+  // Corks: on a tube that's just become a whole color, off one that no longer is
+  if (sorted(tube)) completeTube(g.world, l, s.tubes[t]!, t, color);
+  if (!sorted(g.tubes[from]!)) showCork(g.world, l, s.tubes[from]!, from, false);
+  if (solved(g.tubes)) {
+    g.onEvent('complete');
+    celebrate(g.world, l);
+    end(g);
+    return;
+  }
+  g.onEvent('move');
+}

package/src/games/colors-sort/ColorsSortScene.ts

@@ -0,0 +1,315 @@
+// Everything Colors Sort draws: two wooden shelves of glass tubes, each holding a stack of glossy
+// colored pucks, seen from a little above (shared/EngineTilt: an orthographic camera tipped forward,
+// one world unit per point, y up, z toward the camera). A picked-up puck rises out of its tube and
+// hovers; a move flies it across into the other tube; a tube that holds a whole color gets a cork.
+// Each kind of thing is one shared mesh (one instanced draw): mesh ids are app-wide and limited.
+import { type Color, effects, type Entity, extrude, lathe, type Model, Path, type Vec3, type World } from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import { setBackdropTheme, spawnBackdrop } from '../shared/EngineBackdrop';
+import { noise } from '../shared/EngineMeadow';
+import { cacheGameAsset, createGameMesh as createShape } from '../shared/EngineMeshes';
+import { placeTiltedBackdrop } from '../shared/EngineTilt';
+import { toColor } from '../shared/EngineUtils';
+import { COLORS, hoverY, type Layout, LIFT_TIME, MOVE_TIME, SHAKE_TIME, slotY } from './ColorsSortConstants';
+
+// ── Meshes (unit sizes, scaled per entity) ────────────────────────────
+
+const meshes = new Map<string, Model>();
+const cached = (key: string, build: () => Model) => {
+  let m = meshes.get(key);
+  if (!m) {
+    m = cacheGameAsset('colors-sort/ColorsSortScene:' + key, build);
+    meshes.set(key, m);
+  }
+  return m;
+};
+type RGB = [number, number, number];
+const shade = (c: RGB, k: number): RGB => [c[0] * k, c[1] * k, c[2] * k];
+const smooth = (a: number, b: number, x: number) => {
+  const t = Math.min(1, Math.max(0, (x - a) / (b - a)));
+  return t * t * (3 - 2 * t);
+};
+
+/** A test tube: an open glass cylinder with a rounded bottom, one unit across and tall. */
+const glassMesh = () => cached('cs-glass', () => createShape(lathe(GLASS_PROFILE, { segments: 96 }), { center: false, shine: 0.9 }));
+/** The glass's profile (radius, height), bottom centre to mouth: the tube is this, turned. */
+const GLASS_PROFILE: [number, number][] = [
+  // The rounded bottom: a quarter ellipse, finely stepped so it (and the outline round it) curve smoothly
+  ...Array.from({ length: 25 }, (_, i): [number, number] => {
+    const a = (i / 24) * (Math.PI / 2);
+    return [Math.max(0.001, 0.5 * Math.sin(a)), 0.09 * (1 - Math.cos(a))];
+  }),
+  [0.5, 1]
+];
+/**
+ * The jar's outline from the front: a flat band hugging its sides and rounded bottom, open at the mouth.
+ * In units of the tube's width (`tall` is its height over its width), so the band is even all round.
+ */
+const outlineMesh = (tall: number) =>
+  cached(`cs-outline:${tall.toFixed(2)}`, () => {
+    const w = 0.035;
+    const inner = GLASS_PROFILE.map(([r, y]) => [r, y * tall] as [number, number]);
+    const curve = [
+      ...inner
+        .slice()
+        .reverse()
+        .map(([x, y]) => [-x, y] as [number, number]),
+      ...inner.slice(1)
+    ];
+    // Pushed out along each corner's normal (the bisector of its two edges)
+    const outer = curve.map(([x, y], i) => {
+      const [ax, ay] = curve[Math.max(0, i - 1)]!;
+      const [bx, by] = curve[Math.min(curve.length - 1, i + 1)]!;
+      const tx = bx - ax;
+      const ty = by - ay;
+      const len = Math.hypot(tx, ty) || 1;
+      return [x + (ty / len) * w, y - (tx / len) * w] as [number, number];
+    });
+    const ring = [...outer, ...curve.slice().reverse()].map(([x, y]) => [x, -y] as [number, number]);
+    return createShape(extrude(new Path().addPolygon(ring), { depth: 0 }), { center: false });
+  });
+/** A thin ring round the outside of a tube's mouth (one unit across, as tall as the entity's y scale). */
+const mouthRingMesh = () =>
+  cached('cs-mouth-ring', () =>
+    createShape(
+      lathe(
+        // A round tube in cross-section (a torus), so its edge reads as one soft line
+        Array.from({ length: 17 }, (_, i): [number, number] => {
+          const a = (i / 16) * Math.PI * 2;
+          return [0.59 + 0.03 * Math.cos(a), 0.5 + 0.5 * Math.sin(a)];
+        }),
+        { segments: 120 }
+      ),
+      { center: false, shine: 0.3 }
+    )
+  );
+/** The lip round a tube's mouth (a ring one unit across, its thickness set by the entity's y scale). */
+const rimMesh = () =>
+  cached('cs-rim', () =>
+    createShape(
+      lathe(
+        [
+          [0.5, 0],
+          [0.56, 0.1],
+          [0.56, 0.9],
+          [0.5, 1],
+          [0.5, 0]
+        ],
+        { segments: 96 }
+      ),
+      { center: false, shine: 0.8 }
+    )
+  );
+/** A puck: a rounded disc one unit across and tall, a touch brighter on top. */
+const puckMesh = () =>
+  cached('cs-puck', () =>
+    createShape(
+      lathe(
+        [
+          [0.001, 0],
+          [0.42, 0],
+          [0.5, 0.14],
+          [0.5, 0.86],
+          [0.42, 1],
+          [0.001, 1]
+        ],
+        { segments: 32, color: ({ position: p, normal: n }) => shade([1, 1, 1], 0.82 + 0.18 * smooth(0.2, 0.95, p[1]) + 0.12 * Math.max(0, n[1])) }
+      ),
+      { center: false, shine: 0.6 }
+    )
+  );
+/** A cork stopper: a tapered plug under a wider cap, one unit across and tall. */
+const corkMesh = () =>
+  cached('cs-cork', () =>
+    createShape(
+      lathe(
+        [
+          [0.001, 0],
+          [0.42, 0],
+          [0.46, 0.55],
+          [0.56, 0.58],
+          [0.58, 0.68],
+          [0.56, 1],
+          [0.001, 1]
+        ],
+        {
+          segments: 28,
+          color: ({ position: p }) => shade([0.78, 0.56, 0.34], 0.82 + 0.3 * noise(p[0] * 30 + p[1] * 9, p[2] * 30 + p[1] * 40))
+        }
+      ),
+      { center: false, shine: 0.1 }
+    )
+  );
+
+// ── Colors ────────────────────────────────────────────────────────────
+
+/** Clear glass: barely tinted, so the gems inside show at full color; the rim and glint outline the jar. */
+const glassColor = (theme: GameTheme): Color => (theme.mode === 'dark' ? [1, 1, 1, 0.05] : [1, 1, 1, 0.08]);
+/** The jar's outline: dark on light themes, light on dark, so the clear glass's edges always read. */
+const edgeColor = (theme: GameTheme): Color => (theme.mode === 'dark' ? [1, 1, 1, 0.55] : [0.1, 0.14, 0.22, 0.45]);
+const rimColor = (theme: GameTheme): Color => {
+  if (theme.mode === 'classic') return [1, 1, 1, 0.6];
+  const border = toColor(theme.BOARD.BORDER);
+  const [r, g, b, a] = border[3]! > 0 ? border : toColor(theme.BOARD.CELL_EMPTY);
+  return [r, g, b, Math.max(0.45, a ?? 0)];
+};
+export const pieceColor = (colorIndex: number) => toColor(COLORS[colorIndex]!);
+
+// ── Spawning ──────────────────────────────────────────────────────────
+
+const BACKDROP_DEPTH = 60;
+
+export type Tube = { glass: Entity; rim: Entity; streak: Entity; edges: Entity[]; cork: Entity };
+export type Scene = { backdrop: Entity; tubes: Tube[] };
+
+export function buildScene(world: World, l: Layout, theme: GameTheme): Scene {
+  const backdrop = spawnBackdrop(world, l.width, l.height, -BACKDROP_DEPTH, theme);
+  placeTiltedBackdrop(world, backdrop, l, BACKDROP_DEPTH);
+  const d = l.tubeRadius * 2;
+  const tubes = l.tubes.map(([x, y]) => ({
+    glass: world.spawn({ mesh: glassMesh(), position: [x, y, 0], scale: [d, l.tubeHeight, d], color: glassColor(theme), pickable: false }),
+    rim: world.spawn({
+      mesh: rimMesh(),
+      position: [x, y + l.tubeHeight - l.tubeRadius * 0.12, 0],
+      scale: [d, l.tubeRadius * 0.16, d],
+      color: rimColor(theme),
+      pickable: false
+    }),
+    // A glint running down the glass, front left
+    streak: world.spawn({
+      mesh: 'cube',
+      position: [x - l.tubeRadius * 0.55, y + l.tubeHeight * 0.55, l.tubeRadius * 0.86],
+      scale: [l.tubeRadius * 0.08, l.tubeHeight * 0.72, 0.5],
+      color: [1, 1, 1, 0.2],
+      pickable: false
+    }),
+    // Its outline: a band round the sides and rounded bottom, and a ring round the mouth
+    edges: [
+      world.spawn({ mesh: outlineMesh(l.tubeHeight / d), position: [x, y, 0], scale: [d, d, 1], color: edgeColor(theme), pickable: false }),
+      world.spawn({
+        mesh: mouthRingMesh(),
+        position: [x, y + l.tubeHeight - l.tubeRadius * 0.06, 0],
+        scale: [d, l.tubeRadius * 0.12, d],
+        color: edgeColor(theme),
+        pickable: false
+      })
+    ],
+    cork: world.spawn({ mesh: corkMesh(), position: [x, y + l.tubeHeight, 0], scale: 0, pickable: false })
+  }));
+  return { backdrop, tubes };
+}
+
+export function removeScene(world: World, s: Scene) {
+  for (const e of [s.backdrop, ...s.tubes.flatMap((t) => [t.glass, t.rim, t.streak, ...t.edges, t.cork])]) world.despawn(e);
+}
+
+export function setSceneTheme(world: World, s: Scene, theme: GameTheme) {
+  setBackdropTheme(world, s.backdrop, theme);
+  for (const t of s.tubes) {
+    world.set(t.glass, { color: glassColor(theme) });
+    world.set(t.rim, { color: rimColor(theme) });
+    for (const e of t.edges) world.set(e, { color: edgeColor(theme) });
+  }
+}
+
+// ── Pieces ────────────────────────────────────────────────────────────
+
+const pieceScale = (l: Layout): Vec3 => [l.pieceRadius * 2, l.pieceHeight, l.pieceRadius * 2];
+const at = (l: Layout, tube: number, y: number): Vec3 => [l.tubes[tube]![0], y, 0];
+
+export function spawnPiece(world: World, l: Layout, colorIndex: number, tube: number, slot: number): Entity {
+  return world.spawn({
+    mesh: puckMesh(),
+    position: at(l, tube, slotY(l, tube, slot)),
+    scale: pieceScale(l),
+    color: pieceColor(colorIndex),
+    pickable: false
+  });
+}
+
+/** Picked up: the top puck springs up out of its tube and hovers. */
+export function liftPiece(world: World, l: Layout, piece: Entity, tube: number) {
+  world.stopAnimation(piece);
+  world.animate(piece, { position: at(l, tube, hoverY(l, tube)) }, { spring: { stiffness: 260, damping: 18 } });
+  world.set(piece, { bob: { amplitude: [0, l.pieceHeight * 0.08, 0], speed: 5 } });
+}
+
+/** Put back: it drops into its own slot again. */
+export function lowerPiece(world: World, l: Layout, piece: Entity, tube: number, slot: number) {
+  world.set(piece, { bob: null });
+  world.stopAnimation(piece);
+  world.animate(piece, { position: at(l, tube, slotY(l, tube, slot)) }, { duration: LIFT_TIME, easing: 'easeIn' });
+}
+
+/** Moved: it flies over to the other tube's mouth, then drops in and settles with a bounce. */
+export function movePiece(world: World, l: Layout, piece: Entity, from: number, to: number, slot: number) {
+  world.set(piece, { bob: null });
+  world.stopAnimation(piece);
+  const high = Math.max(hoverY(l, from), hoverY(l, to));
+  world.animate(
+    piece,
+    [
+      { position: at(l, from, high), at: 0.2 },
+      { position: at(l, to, high), at: 0.55 },
+      { position: at(l, to, slotY(l, to, slot)), at: 1 }
+    ],
+    { duration: MOVE_TIME, path: 'smooth', easing: 'easeInOut' }
+  );
+}
+
+// ── Feedback ──────────────────────────────────────────────────────────
+
+/** A refused tap: the tube and what's in it shake. */
+export function shakeTube(world: World, l: Layout, t: Tube, pieces: Entity[]) {
+  world.animate([t.glass, t.rim, t.streak, ...t.edges, ...pieces], { shake: l.tubeRadius * 0.14 }, { duration: SHAKE_TIME });
+}
+
+/** A whole color in one tube: it pops, sparkles in that color and a cork drops into its mouth. */
+export function completeTube(world: World, l: Layout, t: Tube, tube: number, colorIndex: number) {
+  const [x, y] = l.tubes[tube]!;
+  const d = l.tubeRadius * 2;
+  world.animate(t.glass, [{ scale: [d * 1.06, l.tubeHeight * 1.03, d * 1.06], at: 0.4 }, { scale: [d, l.tubeHeight, d] }], { duration: 0.3 });
+  effects.sparkle(world, {
+    position: [x, y + l.tubeHeight, l.tubeRadius],
+    count: 16,
+    size: l.tubeRadius * 0.16,
+    speed: l.tubeRadius * 4,
+    direction: [0, 1, 0],
+    spread: 1,
+    lifetime: 0.6,
+    gravity: -l.tubeRadius * 6,
+    colors: [pieceColor(colorIndex), [1, 1, 1, 1], [1, 0.85, 0.3, 1]]
+  });
+  showCork(world, l, t, tube, true, true);
+}
+
+/** The cork in a sorted tube's mouth (dropping in, or simply there), or taken away. */
+export function showCork(world: World, l: Layout, t: Tube, tube: number, on: boolean, animate = false) {
+  const [x, y] = l.tubes[tube]!;
+  const size: Vec3 = [l.tubeRadius * 1.9, l.tubeRadius * 0.95, l.tubeRadius * 1.9];
+  const rest: Vec3 = [x, y + l.tubeHeight - size[1] * 0.5, 0];
+  world.stopAnimation(t.cork);
+  if (!on) {
+    world.set(t.cork, { scale: 0 });
+    return;
+  }
+  if (!animate) {
+    world.set(t.cork, { position: rest, scale: size });
+    return;
+  }
+  world.set(t.cork, { position: [x, rest[1] + l.tubeRadius * 2.5, 0], scale: size });
+  world.animate(t.cork, { position: rest }, { duration: 0.35, delay: 0.15, easing: 'bounce' });
+}
+
+/** Confetti over the shelves when everything's sorted. */
+export function celebrate(world: World, l: Layout) {
+  effects.confetti(world, {
+    position: [0, l.tubeHeight * 0.4, l.tubeRadius * 2],
+    count: 60,
+    size: l.tubeRadius * 0.2,
+    speed: l.tubeHeight * 2.2,
+    lifetime: 1.3,
+    gravity: -l.tubeHeight * 3.5,
+    colors: COLORS.slice(0, 4).map((c) => toColor(c))
+  });
+}