@nayan-ui/games 1.18.0 → 1.20.0

package/src/games/bluk/BlukScene.ts

@@ -0,0 +1,514 @@
+// Everything Bluk draws: a deep sky (themed, as the original sky) with stars, far rock spires in the haze and
+// soft clouds drifting slowly behind, the rugged rock pillars (stone layers under a grassy cap that
+// droops over the edges, a gold sweet spot set into each top), the
+// little block character (a body in the block's color, arms and legs, a round head with eyes and a
+// smile), the aiming arc's dots, landing dust and the perfect ring. An orthographic camera looks a
+// little down and from the right at the course (one world unit per view point, y up).
+import {
+  type Camera,
+  type Color,
+  effects,
+  type Entity,
+  extrude,
+  merge,
+  type Model,
+  Path,
+  type Quat,
+  quat,
+  recolor,
+  shapeGeometry,
+  tube,
+  type Vec3,
+  type World
+} from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import { noise } from '../shared/EngineMeadow';
+import { cacheGameAsset, createGameMesh as createShape } from '../shared/EngineMeshes';
+import { toColor } from '../shared/EngineUtils';
+import { BLOCK_COLORS, COLORS, type Config, PITCH, SKIES, type Sky, SKY_POSITIONS, TRAJECTORY_DOTS, YAW } from './BlukConstants';
+import type { Pillar } from './BlukRules';
+
+const meshes = new Map<string, Model>();
+const cached = (key: string, build: () => Model) => {
+  let m = meshes.get(key);
+  if (!m) {
+    m = cacheGameAsset('bluk/BlukScene:' + key, build);
+    meshes.set(key, m);
+  }
+  return m;
+};
+const EYE_DISTANCE = 300;
+const SKY_DEPTH = 220;
+const TOWER_DEPTH = 150;
+const FLAT_UP: Quat = quat.x(-Math.PI / 2);
+const rgb = (css: string): [number, number, number] => {
+  const [r, g, b] = toColor(css);
+  return [r, g, b];
+};
+
+/** The theme's sky: the built-in one, its base following the theme's background (as the original scene). */
+export function skyFor(theme: GameTheme): Sky {
+  if (theme.mode === 'classic') return SKIES.classic;
+  const sky = SKIES[theme.isDark ? 'dark' : 'light'];
+  const base = sky.stops[0] === sky.stops[sky.stops.length - 1] ? sky.stops[0] : null;
+  return { ...sky, stops: sky.stops.map((s) => (s === base ? theme.BACKGROUND : s)) };
+}
+
+// ── Meshes ────────────────────────────────────────────────────────────
+
+/** The sky: a vertical gradient, one unit square (top edge at y = 0.5), facing the camera. */
+const skyMesh = (sky: Sky) =>
+  cached(`bluk-sky:${sky.stops.join(',')}`, () => {
+    const stops = sky.stops.map(rgb);
+    const g = recolor(extrude(new Path().addRect(-0.5, -0.5, 1, 1), { depth: 0 }), ({ position }) => {
+      const t = Math.min(1, Math.max(0, 0.5 - position[1]));
+      let k = 0;
+      while (k < SKY_POSITIONS.length - 2 && t > SKY_POSITIONS[k + 1]!) k++;
+      const a = SKY_POSITIONS[k]!;
+      const b = SKY_POSITIONS[k + 1]!;
+      const f = (t - a) / (b - a || 1);
+      const ca = stops[k]!;
+      const cb = stops[k + 1]!;
+      return [ca[0] + (cb[0] - ca[0]) * f, ca[1] + (cb[1] - ca[1]) * f, ca[2] + (cb[2] - ca[2]) * f, 1];
+    });
+    return createShape(g, { center: false });
+  });
+
+/**
+ * The character, one block tall, feet on y = 0, facing the camera (+z). Its shirt (torso and sleeves) is
+ * white and tinted per block color; everything else (skin, hair, trousers, shoes, face) keeps its own.
+ */
+const bodyMesh = () =>
+  cached('bluk-body-v2', () => {
+    const sleeve = (side: number) => ({
+      geometry: tube(
+        [
+          [side * 0.13, 0.68, 0],
+          [side * 0.19, 0.6, 0.01]
+        ],
+        { radius: 0.055, sides: 12, caps: true }
+      )
+    });
+    return createShape(
+      merge([
+        // A rounded torso, broader at the chest, tapering to the waist
+        {
+          geometry: tube(
+            [
+              [0, 0.42, 0],
+              [0, 0.56, 0],
+              [0, 0.7, 0]
+            ],
+            { radius: (t) => 0.1 + 0.035 * Math.sin(Math.PI * Math.min(1, t * 1.3)), sides: 18, caps: true }
+          ),
+          scale: [1.25, 1, 0.85]
+        },
+        sleeve(-1),
+        sleeve(1)
+      ]),
+      { center: false, shine: 0.3 }
+    );
+  });
+const headMesh = () =>
+  cached('bluk-head-v2', () => {
+    const skin = toColor(COLORS.SKIN);
+    const trousers: Color = [0.2, 0.26, 0.42, 1];
+    const shoe: Color = [0.16, 0.12, 0.1, 1];
+    const hair: Color = [0.24, 0.15, 0.09, 1];
+    const limb = (a: Vec3, b: Vec3, r: number, color: Color) => ({ geometry: tube([a, b], { radius: r, sides: 12, caps: true }), color });
+    const smile: Vec3[] = Array.from({ length: 9 }, (_, i) => {
+      const a = Math.PI * 1.2 + (Math.PI * 0.6 * i) / 8;
+      return [Math.cos(a) * 0.05, 0.835 + Math.sin(a) * 0.035, 0.15];
+    });
+    const parts = [
+      // Legs in trousers, a belt, and shoes
+      limb([-0.055, 0.44, 0], [-0.065, 0.07, 0.01], 0.05, trousers),
+      limb([0.055, 0.44, 0], [0.065, 0.07, 0.01], 0.05, trousers),
+      {
+        geometry: shapeGeometry('roundedBox'),
+        position: [0, 0.43, 0] as Vec3,
+        scale: [0.25, 0.04, 0.2] as Vec3,
+        color: [0.18, 0.14, 0.12, 1] as Color
+      },
+      { geometry: shapeGeometry('roundedBox'), position: [-0.068, 0.035, 0.03] as Vec3, scale: [0.09, 0.07, 0.16] as Vec3, color: shoe },
+      { geometry: shapeGeometry('roundedBox'), position: [0.068, 0.035, 0.03] as Vec3, scale: [0.09, 0.07, 0.16] as Vec3, color: shoe },
+      // Forearms and hands
+      limb([-0.19, 0.6, 0.01], [-0.22, 0.47, 0.03], 0.04, skin),
+      limb([0.19, 0.6, 0.01], [0.22, 0.47, 0.03], 0.04, skin),
+      { geometry: shapeGeometry('sphere'), position: [-0.225, 0.45, 0.035] as Vec3, scale: 0.075, color: skin },
+      { geometry: shapeGeometry('sphere'), position: [0.225, 0.45, 0.035] as Vec3, scale: 0.075, color: skin },
+      // Neck and head, ears, nose
+      limb([0, 0.7, 0], [0, 0.76, 0], 0.04, skin),
+      { geometry: shapeGeometry('sphere'), position: [0, 0.86, 0] as Vec3, scale: [0.27, 0.3, 0.27] as Vec3, color: skin },
+      { geometry: shapeGeometry('sphere'), position: [-0.135, 0.86, 0] as Vec3, scale: [0.05, 0.08, 0.05] as Vec3, color: skin },
+      { geometry: shapeGeometry('sphere'), position: [0.135, 0.86, 0] as Vec3, scale: [0.05, 0.08, 0.05] as Vec3, color: skin },
+      {
+        geometry: shapeGeometry('sphere'),
+        position: [0, 0.855, 0.135] as Vec3,
+        scale: [0.04, 0.05, 0.04] as Vec3,
+        color: [skin[0] * 0.92, skin[1] * 0.86, skin[2] * 0.82, 1] as Color
+      },
+      // Hair: a cap over the top and back of the head, with a fringe
+      { geometry: shapeGeometry('sphere'), position: [0, 0.92, -0.015] as Vec3, scale: [0.29, 0.22, 0.29] as Vec3, color: hair },
+      { geometry: shapeGeometry('roundedBox'), position: [0.02, 0.965, 0.11] as Vec3, scale: [0.2, 0.05, 0.06] as Vec3, color: hair },
+      // Eyes (whites, irises, pupils, a glint), brows and a smile
+      ...[-1, 1].flatMap((side) => [
+        {
+          geometry: shapeGeometry('sphere'),
+          position: [side * 0.05, 0.885, 0.118] as Vec3,
+          scale: [0.055, 0.06, 0.03] as Vec3,
+          color: [1, 1, 1, 1] as Color
+        },
+        {
+          geometry: shapeGeometry('sphere'),
+          position: [side * 0.05, 0.882, 0.13] as Vec3,
+          scale: [0.034, 0.038, 0.015] as Vec3,
+          color: [0.27, 0.45, 0.62, 1] as Color
+        },
+        {
+          geometry: shapeGeometry('sphere'),
+          position: [side * 0.05, 0.882, 0.137] as Vec3,
+          scale: [0.018, 0.02, 0.01] as Vec3,
+          color: toColor(COLORS.PUPIL)
+        },
+        { geometry: shapeGeometry('sphere'), position: [side * 0.05 + 0.008, 0.89, 0.142] as Vec3, scale: 0.008, color: [1.4, 1.4, 1.4, 1] as Color },
+        {
+          geometry: shapeGeometry('roundedBox'),
+          position: [side * 0.05, 0.925, 0.125] as Vec3,
+          rotation: quat.z(side * -0.15),
+          scale: [0.05, 0.011, 0.012] as Vec3,
+          color: hair
+        }
+      ]),
+      { geometry: tube(smile, { radius: 0.007, sides: 6, caps: true }), color: toColor(COLORS.SMILE) }
+    ];
+    return createShape(merge(parts), { center: false, shine: 0.25 });
+  });
+/** A flat ring one unit across, lying face up. */
+const ringMesh = () =>
+  cached('bluk-ring', () =>
+    createShape(extrude(new Path().addCircle(0, 0, 0.5).addCircle(0, 0, 0.42), { depth: 0, fillRule: 'evenodd' }), { center: false })
+  );
+
+/**
+ * A rugged rock column one unit across and deep, its top at y = 0 running down to y = -1: stacked stone
+ * layers, each a little uneven in width and shade, with darker seams between them (tinted per pillar).
+ */
+const rockMesh = () =>
+  cached('bluk-rock', () => {
+    const layers = 26;
+    const parts = [];
+    for (let i = 0; i < layers; i++) {
+      const y = -(i + 0.5) / layers;
+      const jx = (noise(i * 3.1, 1.7) - 0.5) * 0.12;
+      const jz = (noise(i * 2.3, 8.9) - 0.5) * 0.12;
+      const k = 0.78 + 0.3 * noise(i * 1.9, 4.2);
+      parts.push({
+        geometry: shapeGeometry('roundedBox'),
+        position: [jx * 0.3, y, jz * 0.3] as Vec3,
+        scale: [1 + jx, 1 / layers - 0.004, 1 + jz] as Vec3,
+        color: [k, k, k, 1] as Color
+      });
+      parts.push({
+        geometry: shapeGeometry('cube'),
+        position: [0, y - 0.5 / layers, 0] as Vec3,
+        scale: [0.97, 0.004, 0.97] as Vec3,
+        color: [0.45, 0.45, 0.45, 1] as Color
+      });
+    }
+    return createShape(merge(parts), { center: false, shine: 0.12 });
+  });
+/** A grassy cap one unit across and deep, sitting on y = 0: a turf slab with tufts drooping over its edges. */
+const capMesh = () =>
+  cached('bluk-cap', () => {
+    const grass = toColor(COLORS.GRASS);
+    const dark = toColor(COLORS.GRASS_DARK);
+    const moss = toColor(COLORS.MOSS);
+    const parts = [
+      { geometry: shapeGeometry('roundedBox'), position: [0, 0.5, 0] as Vec3, scale: [1.06, 1, 1.06] as Vec3, color: grass },
+      { geometry: shapeGeometry('roundedBox'), position: [0, -0.1, 0] as Vec3, scale: [1.02, 0.4, 1.02] as Vec3, color: moss }
+    ];
+    // Tufts hanging over the front and side edges
+    for (let i = 0; i < 9; i++) {
+      const x = -0.46 + i * 0.115;
+      const drop = 0.5 + 0.9 * noise(i * 2.7, 3.3);
+      parts.push({
+        geometry: shapeGeometry('roundedBox'),
+        position: [x, -drop / 2 + 0.1, 0.5] as Vec3,
+        scale: [0.09, drop, 0.06] as Vec3,
+        color: i % 2 ? dark : grass
+      });
+    }
+    for (const side of [-1, 1])
+      for (let i = 0; i < 6; i++) {
+        const z = -0.4 + i * 0.16;
+        const drop = 0.4 + 0.8 * noise(i * 3.9 + side, 7.1);
+        parts.push({
+          geometry: shapeGeometry('roundedBox'),
+          position: [side * 0.52, -drop / 2 + 0.1, z] as Vec3,
+          scale: [0.06, drop, 0.1] as Vec3,
+          color: i % 2 ? grass : dark
+        });
+      }
+    return createShape(merge(parts), { center: false, shine: 0.08 });
+  });
+/** A soft cloud, one unit across: a cluster of puffs, flat-bottomed. */
+const cloudMesh = () =>
+  cached('bluk-cloud', () =>
+    createShape(
+      merge(
+        [
+          [0, 0, 0.5],
+          [-0.28, -0.06, 0.38],
+          [0.3, -0.05, 0.4],
+          [-0.12, 0.12, 0.42],
+          [0.14, 0.14, 0.36],
+          [0.45, -0.1, 0.26],
+          [-0.48, -0.1, 0.26]
+        ].map(([x, y, r]) => ({ geometry: shapeGeometry('sphere'), position: [x!, y!, 0] as Vec3, scale: [r!, r! * 0.75, r! * 0.6] as Vec3 }))
+      ),
+      { center: false, shine: 0 }
+    )
+  );
+
+// ── Spawning ──────────────────────────────────────────────────────────
+
+type PillarView = { root: Entity };
+type Decor = { entity: Entity; x: number; y: number; z: number };
+export type Scene = {
+  sky: Entity;
+  towers: Decor[];
+  frameX?: number;
+  frameWidth?: number;
+  frameHeight?: number;
+  pillars: Map<string, PillarView>;
+  block: Entity;
+  figure: Entity;
+  body: Entity;
+  dots: Entity[];
+  ring: Entity;
+};
+
+/** World point for a course point (x along the world, y down in the view). */
+export const toWorld = (x: number, y: number, z = 0): Vec3 => [x, -y, z];
+
+function spawnPillar(world: World, c: Config, p: Pillar): PillarView {
+  const bottom = c.height + 400; // runs down past the bottom of the view
+  const h = bottom - p.topY;
+  const d = p.width * 0.85;
+  const root = world.spawn({ mesh: 'none', position: toWorld(p.worldX, p.topY), pickable: false });
+  const add = (o: Parameters<World['spawn']>[0]) => world.spawn({ parent: root, pickable: false, ...o });
+  // The rock column, its grassy cap, and the gold sweet spot set into the turf
+  add({ mesh: rockMesh(), position: [0, -3, 0], scale: [p.width, h, d], color: toColor(COLORS.ROCK) });
+  add({ mesh: capMesh(), position: [0, -5, 0], scale: [p.width, 6, d], color: [1, 1, 1, 1] });
+  add({ mesh: 'roundedBox', position: [0, 1.2, 0], scale: [c.sweetSpotWidth + 8, 1.2, d * 0.62], color: toColor(COLORS.SWEET_RECESS) });
+  add({ mesh: 'roundedBox', position: [0, 1.8, 0], scale: [c.sweetSpotWidth, 1, d * 0.42], color: [1.5, 1.3, 0.25, 1] });
+  return { root };
+}
+
+export function buildScene(world: World, c: Config, theme: GameTheme, pillars: Pillar[], block: [number, number], colorIndex: number): Scene {
+  const sky = skyFor(theme);
+  const skyEntity = world.spawn({ mesh: skyMesh(sky), scale: [c.width * 2.4, c.height * 1.8, 1], pickable: false });
+  // Stars (riding with the sky: infinitely far) and far ghost towers (drifting at a tenth of the course's pace)
+  if (sky.stars) {
+    let seed = 7;
+    const rnd = () => {
+      const x = Math.sin(seed++ * 12.9898) * 43758.5453;
+      return x - Math.floor(x);
+    };
+    for (let i = 0; i < 48; i++) {
+      const a = 0.4 + rnd() * 0.9;
+      world.spawn({
+        mesh: 'sphere',
+        parent: skyEntity,
+        // Across the view's upper 64% (the sky is centred a tenth of the view above the view's centre)
+        position: [(rnd() - 0.5) * 0.9, (0.4 - rnd() * 0.64) / 1.8, 0.5],
+        scale: [(1.2 + rnd() * 2.4) / (c.width * 2.4), (1.2 + rnd() * 2.4) / (c.height * 1.8), 0.01],
+        color: [1.4 * a, 1.3 * a, 1.6 * a, 1],
+        pickable: false
+      });
+    }
+  }
+  // Far off: rock spires in the haze (drifting slower than the course), and nearer soft clouds
+  const towers: Decor[] = [];
+  const haze = toColor(sky.tower);
+  for (let i = 0; i < 10; i++) {
+    const x = (i / 10) * c.width * 1.8 - c.width * 0.2;
+    const top = c.height * (0.3 + ((i * 37) % 11) * 0.025);
+    const w = 22 + ((i * 53) % 20);
+    const h = c.height * 1.3 - top;
+    const far = i % 2 === 0;
+    const k = far ? 1 : 0.85;
+    const entity = world.spawn({
+      mesh: rockMesh(),
+      position: [x, -top, -TOWER_DEPTH * (far ? 1 : 0.7)],
+      scale: [w, h, w],
+      color: [haze[0] * k, haze[1] * k, haze[2] * k, 1],
+      pickable: false
+    });
+    towers.push({ entity, x, y: -top, z: -TOWER_DEPTH * (far ? 1 : 0.7) });
+  }
+  const cloud: Color = sky.stars ? [0.55, 0.52, 0.75, 0.35] : [1, 1, 1, 0.85];
+  for (let i = 0; i < 6; i++) {
+    const x = (i / 6) * c.width * 1.8 - c.width * 0.2;
+    const y = c.height * (0.1 + ((i * 29) % 7) * 0.04);
+    const size = 60 + ((i * 41) % 50);
+    const entity = world.spawn({
+      mesh: cloudMesh(),
+      position: [x, -y, -TOWER_DEPTH * 0.4],
+      scale: [size, size * 0.6, size * 0.5],
+      color: cloud,
+      pickable: false
+    });
+    towers.push({ entity, x, y: -y, z: -TOWER_DEPTH * 0.4 });
+  }
+  const s: Scene = {
+    sky: skyEntity,
+    towers,
+    pillars: new Map(),
+    block: world.spawn({ mesh: 'none', position: toWorld(block[0], block[1]), pickable: false }),
+    figure: 0 as Entity,
+    body: 0 as Entity,
+    dots: [],
+    ring: world.spawn({ mesh: ringMesh(), rotation: FLAT_UP, scale: 0, color: [1.6, 1.4, 0.3, 0], pickable: false })
+  };
+  // The character: its feet at the block's bottom, so a squash keeps them on the pillar
+  s.figure = world.spawn({ mesh: 'none', parent: s.block, position: [0, -c.blockSize / 2, 0], scale: c.blockSize, pickable: false });
+  s.body = world.spawn({ mesh: bodyMesh(), parent: s.figure, color: toColor(BLOCK_COLORS[colorIndex]!), pickable: false });
+  world.spawn({ mesh: headMesh(), parent: s.figure, pickable: false });
+  const dot = toColor(COLORS.TRAJECTORY);
+  for (let i = 0; i <= TRAJECTORY_DOTS; i++)
+    s.dots.push(world.spawn({ mesh: 'sphere', scale: 0, color: [dot[0] * 1.4, dot[1] * 1.4, dot[2] * 1.4, 0.92], pickable: false }));
+  syncPillars(world, c, s, pillars);
+  return s;
+}
+
+export function removeScene(world: World, s: Scene) {
+  for (const e of [s.sky, ...s.towers.map((t) => t.entity), ...Array.from(s.pillars.values(), (p) => p.root), s.block, ...s.dots, s.ring])
+    world.despawn(e);
+}
+
+/** Keeps the pillars in step with the course: new ones appear, dropped ones go. */
+export function syncPillars(world: World, c: Config, s: Scene, pillars: Pillar[]) {
+  const live = new Set(pillars.map((p) => p.id));
+  for (const [id, v] of s.pillars)
+    if (!live.has(id)) {
+      world.despawn(v.root);
+      s.pillars.delete(id);
+    }
+  for (const p of pillars) if (!s.pillars.has(p.id)) s.pillars.set(p.id, spawnPillar(world, c, p));
+}
+
+/** Points the camera at the course scrolled `camX` along, the sky and towers following. */
+export function frame(world: World, c: Config, s: Scene, camera: Camera, camX: number) {
+  if (s.frameX === camX && s.frameWidth === c.width && s.frameHeight === c.height) return;
+  s.frameX = camX;
+  s.frameWidth = c.width;
+  s.frameHeight = c.height;
+  const updates = world.transforms;
+  const tx = camX + c.width / 2;
+  const ty = -c.height / 2;
+  const cp = Math.cos(PITCH);
+  camera.target = [tx, ty, 0];
+  camera.eye = [tx + Math.sin(YAW) * cp * EYE_DISTANCE, ty + Math.sin(PITCH) * EYE_DISTANCE, Math.cos(YAW) * cp * EYE_DISTANCE];
+  camera.ortho = c.height / 2;
+  updates.position(s.sky, tx - Math.sin(YAW) * SKY_DEPTH, ty + c.height * 0.1 - Math.sin(PITCH) * SKY_DEPTH, -SKY_DEPTH);
+  for (const t of s.towers) {
+    // A tenth of the course's pace, wrapping round so there are always some in view
+    const span = c.width * 1.8;
+    let x = t.x + camX * 0.9;
+    x = camX - c.width * 0.2 + ((((x - camX + c.width * 0.2) % span) + span) % span);
+    updates.position(t.entity, x - Math.sin(YAW) * TOWER_DEPTH * 0.6, t.y, t.z);
+  }
+  updates.flush();
+}
+
+// ── The block ─────────────────────────────────────────────────────────
+
+/** The block at its centre (course point), tilted `tilt` (radians, clockwise on screen). */
+export function placeBlock(world: World, s: Scene, x: number, y: number, tilt: number) {
+  world.set(s.block, { position: toWorld(x, y), rotation: quat.z(-tilt) });
+}
+
+/** The character's squash (above 0 stretches it tall, below squashes it flat), set at once. */
+export function squash(world: World, c: Config, s: Scene, q: number) {
+  const k = c.blockSize;
+  world.set(s.figure, { scale: [k * (1 - q * 0.6), k * (1 + q), k * (1 - q * 0.6)] });
+}
+const squashed = (c: Config, q: number): Vec3 => [c.blockSize * (1 - q * 0.6), c.blockSize * (1 + q), c.blockSize * (1 - q * 0.6)];
+
+/** Springing out of the crouch into a quick stretch, for a launch. */
+export function stretch(world: World, c: Config, s: Scene) {
+  world.animate(s.figure, [{ scale: squashed(c, 0.14), at: 0.26 }, { scale: squashed(c, 0) }], { duration: 0.35, easing: 'easeInOut' });
+}
+
+/** Relaxing a crouch that didn't jump. */
+export function relax(world: World, c: Config, s: Scene) {
+  world.animate(s.figure, { scale: squashed(c, 0) }, { duration: 0.16, easing: 'easeOut' });
+}
+
+/** A landing: the tilt eases out, the character squashes and springs back, dust puffs up, and on a perfect one a gold ring spreads. */
+export function land(world: World, c: Config, s: Scene, x: number, topY: number, perfect: boolean, colorIndex: number) {
+  world.animate(s.block, { rotation: [0, 0, 0, 1] }, { duration: 0.22, easing: 'easeOut' });
+  world.animate(s.figure, [{ scale: squashed(c, -0.2), at: 0.2 }, { scale: squashed(c, 0) }], { duration: 0.36, easing: 'back' });
+  world.set(s.body, { color: toColor(BLOCK_COLORS[colorIndex]!) });
+  effects.dust(world, {
+    position: toWorld(x, topY, 6),
+    count: 10,
+    size: c.blockSize * 0.22,
+    speed: c.blockSize * 1.6,
+    lifetime: 0.48,
+    direction: [0, 1, 0],
+    spread: 1.3,
+    color: [0.85, 0.9, 0.95, 0.6],
+    endSize: 1.8
+  });
+  if (perfect) {
+    world.stopAnimation(s.ring);
+    world.set(s.ring, { position: toWorld(x, topY - 1.5), scale: c.blockSize * 0.4, color: [1.6, 1.4, 0.3, 0.9] });
+    world.animate(s.ring, { scale: c.blockSize * 2.6, color: [1.6, 1.4, 0.3, 0] }, { duration: 0.56, easing: 'easeOut' });
+    effects.sparkle(world, {
+      position: toWorld(x, topY - 4, 6),
+      count: 20,
+      size: c.blockSize * 0.08,
+      speed: c.blockSize * 3,
+      lifetime: 0.6,
+      gravity: -c.blockSize * 4,
+      colors: [
+        [1, 0.83, 0.17, 1],
+        [1, 1, 1, 1]
+      ]
+    });
+  }
+}
+
+/** Off the edge: the block tumbles forward and fades as it drops into the void. */
+export function fall(world: World, s: Scene, tilt: number, colorIndex: number) {
+  const c = toColor(BLOCK_COLORS[colorIndex]!);
+  world.animate(s.block, { rotation: quat.z(-(tilt + 1.6)) }, { duration: 0.42, easing: 'easeIn' });
+  world.animate(s.body, { color: [c[0], c[1], c[2], 0] }, { duration: 0.3 });
+  world.animate(s.figure, { scale: 0.01 }, { duration: 0.3, delay: 0.1, easing: 'easeIn' });
+}
+
+/** The block whole again, at rest and in a color (a new board). */
+export function resetBlock(world: World, c: Config, s: Scene, colorIndex: number) {
+  for (const e of [s.block, s.figure, s.body, s.ring]) world.stopAnimation(e);
+  world.set(s.block, { rotation: [0, 0, 0, 1] });
+  world.set(s.figure, { scale: squashed(c, 0) });
+  world.set(s.body, { color: toColor(BLOCK_COLORS[colorIndex]!) });
+  world.set(s.ring, { scale: 0 });
+}
+
+// ── The aim ───────────────────────────────────────────────────────────
+
+/** The preview arc: a dot at each point (course coordinates), shrinking along it; the rest hidden. */
+export function showArc(world: World, c: Config, s: Scene, pts: number[]) {
+  const n = pts.length / 2;
+  for (let i = 0; i < s.dots.length; i++) {
+    if (i < n) {
+      const r = c.blockSize * (0.16 - (0.08 * i) / Math.max(1, n));
+      world.set(s.dots[i]!, { position: toWorld(pts[i * 2]!, pts[i * 2 + 1]!, 4), scale: r });
+    } else world.set(s.dots[i]!, { scale: 0 });
+  }
+}
+export const hideArc = (world: World, c: Config, s: Scene) => showArc(world, c, s, []);

package/src/games/bubble-shooter/BubbleShooter.tsx

@@ -0,0 +1,76 @@
+// Bubble Shooter's screen, on the Nayan engine: the board, bubbles, aim guide and shooter are one 3D
+// scene (an orthographic camera over glossy bubbles), under Playtura's scoreboard, controls and
+// modals. The rules are in BubbleShooterGame.ts, what it draws in BubbleShooterScene.ts.
+//
+// One world serves the whole visit: Start, Stop and Play Again deal a new board in place and a theme
+// change repaints it, so the GPU view is never rebuilt. Pops, loads and the board intro animate in the
+// engine's Rust core; JS moves the shot and aims, and steps the world 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, TIME_LIMIT } from './BubbleShooterConstants';
+import { aimAt, createGame, dispose, fire, reset, setLayout, setTheme, start, tick } from './BubbleShooterGame';
+
+const SFX = GAME_SOUNDS.BUBBLE_SHOOTER;
+
+export const BubbleShooter = engineGame(GAME_IDS.BUBBLE_SHOOTER, (props) => {
+  const [score, setScore] = useLiveState(0);
+  const [bubbles, setBubbles] = useLiveState(0);
+  const [timeLeft, setTimeLeft] = useLiveState(TIME_LIMIT);
+
+  // Win on a cleared board, lose when time runs out
+  const { theme, status, screen, gameOver } = useEngineGame(props, {
+    gameId: GAME_IDS.BUBBLE_SHOOTER,
+    create: createGame,
+    start,
+    reset,
+    dispose,
+    tick,
+    setTheme,
+    resize: (g, width, height, offset) => {
+      const layout = getLayout(width, height, offset);
+      setLayout(g, layout);
+      return layout.boardWidth;
+    },
+    // Drag to aim and let go to fire, or tap where to shoot
+    drag: (g, { phase, x, y, cancelled }) => {
+      if (phase !== 'end') aimAt(g, x, y);
+      else if (!cancelled) fire(g);
+    },
+    tap: (g, x, y) => {
+      aimAt(g, x, y);
+      fire(g);
+    },
+    sounds: SFX,
+    onStart: (fx) => fx(SFX.START, HapticType.SUCCESS),
+    wire: (g, fx) => {
+      g.onScore = setScore;
+      g.onTime = setTimeLeft;
+      g.onBubbles = setBubbles;
+      g.onShoot = () => fx(SFX.SHOOT, HapticType.LIGHT);
+      g.onPop = () => fx(SFX.POP, HapticType.SUCCESS);
+      g.onWin = () => fx(SFX.WIN, HapticType.SUCCESS);
+      g.onLose = () => fx(SFX.GAME_OVER, HapticType.ERROR);
+    }
+  });
+
+  return (
+    <EngineGameScreen
+      {...screen}
+      light={LIGHT}
+      columns={[scoreColumn(score), scoreColumn(bubbles, 'BUBBLES'), timerColumn(timeLeft, theme)]}
+      subtext="Match three colored bubbles!"
+      gameOver={gameOver({
+        title: status === 'win' ? 'YOU WON!' : 'GAME OVER',
+        message: status === 'win' ? 'All bubbles cleared!' : 'Great shooting!',
+        scoreLabel: 'Final Score',
+        score,
+        buttonText: 'Shoot Again!'
+      })}
+    />
+  );
+});