@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/perfect-circle/PerfectCircle.tsx

@@ -0,0 +1,74 @@
+// Perfect Circle's screen, on the Nayan engine: the plate, the guide ring and the drawn neon stroke are
+// one 3D scene (an orthographic camera looking straight down, so the guide is a true circle), under
+// Playtura's scoreboard, controls and modals. The play is in PerfectCircleGame.ts (the scoring in
+// PerfectCircleRules.ts), what it draws in PerfectCircleScene.ts.
+//
+// One world serves the whole visit: Start, Stop and Try Again clear the plate in place and a theme
+// change repaints it, so the GPU view is never rebuilt. The stroke is instances of the engine's
+// built-in shapes, so drawing builds no meshes; JS reads the finger and steps the world once a frame.
+import { useMemo } from 'react';
+import { HapticType } from '../../services/HapticsService';
+import { GAME_SOUNDS } from '../../services/SoundsService';
+import { GAME_IDS } from '../../services/UtilsService';
+import { engineGame, EngineGameScreen } from '../shared/EngineGameScreen';
+import { toRgb } from '../shared/EngineUtils';
+import { useEngineGame } from '../shared/useEngineGame';
+import { useLiveState } from '../shared/useLiveState';
+import { COLORS, getLayout, LIGHT } from './PerfectCircleConstants';
+import { createGame, dispose, drag, reset, setLayout, setTheme, start, tick } from './PerfectCircleGame';
+import { levelOf } from './PerfectCircleRules';
+
+const SOUNDS = GAME_SOUNDS.PERFECT_CIRCLE;
+
+export const PerfectCircle = engineGame(GAME_IDS.PERFECT_CIRCLE, (props) => {
+  const [accuracy, setAccuracy] = useLiveState(0);
+
+  // Win or lose when the round's scored; the score is the accuracy x 100, as before
+  const { theme, status, screen, gameOver } = useEngineGame(props, {
+    gameId: GAME_IDS.PERFECT_CIRCLE,
+    create: createGame,
+    start,
+    reset,
+    dispose,
+    tick,
+    setTheme,
+    resize: (g, width, height, offset) => {
+      const l = getLayout(width, height, offset);
+      setLayout(g, l);
+      return l.radius * 2;
+    },
+    drag,
+    reportScore: (g) => Math.round(g.accuracy * 100),
+    sounds: SOUNDS,
+    onStart: (fx) => fx(SOUNDS.START, HapticType.SUCCESS),
+    onOver: (fx, status) => fx(status === 'win' ? SOUNDS.SUCCESS : SOUNDS.FAIL, status === 'win' ? HapticType.SUCCESS : HapticType.ERROR),
+    wire: (g, fx) => {
+      g.onAccuracy = setAccuracy;
+      g.onEvent = (event) => {
+        if (event === 'begin') fx(null, HapticType.LIGHT);
+        else if (event === 'end') fx(SOUNDS.DRAW_END, HapticType.MEDIUM);
+      };
+    }
+  });
+
+  const background = useMemo(() => toRgb(theme.BACKGROUND), [theme.BACKGROUND]);
+  const level = levelOf(accuracy);
+
+  return (
+    <EngineGameScreen
+      {...screen}
+      light={LIGHT}
+      background={background}
+      // The accuracy, cyan once there is one (light mode keeps the theme's dark text, for contrast)
+      columns={[{ label: 'ACCURACY', value: String(accuracy), valueColor: accuracy > 0 && theme.mode !== 'light' ? COLORS.UI : undefined }]}
+      subtext="Draw perfect circle!"
+      gameOver={gameOver({
+        title: status === 'win' ? level.label.toUpperCase() : 'NOT QUITE!',
+        message: status === 'win' ? `${accuracy}% accuracy - Amazing circle!` : `${accuracy}% accuracy - Need >70% to win`,
+        scoreLabel: 'Final Score',
+        score: accuracy,
+        buttonText: 'Try Again'
+      })}
+    />
+  );
+});

package/src/games/perfect-circle/PerfectCircleConstants.ts

@@ -0,0 +1,52 @@
+// Perfect Circle's colors, feel and layout. The guide circle is placed and sized as the original game
+// placed it (half the game width across, a little below the middle of the screen), so scores carry over.
+import { getScoreBoardTop } from '../shared/EngineHud';
+import type { TiltView } from '../shared/EngineTilt';
+import { frontLight, gameWidthFor } from '../shared/EngineUtils';
+
+// ── Feel ──────────────────────────────────────────────────────────────
+
+export const MIN_POINT_DISTANCE = 4; // points closer than this to the last are skipped, as the original stroke
+export const STROKE_RADIUS = 2.5; // the drawn tube's radius (the original stroke was 4 wide)
+export const FIT_TRACE_TIME = 0.65; // the best-fit circle traces round after the verdict
+export const TINT_TIME = 0.38;
+
+// ── Colors ────────────────────────────────────────────────────────────
+
+export const COLORS = {
+  STROKE: '#00d4ff',
+  SUCCESS: '#4ecca3',
+  FAIL: '#ff6b6b',
+  GUIDE: '#ffffff',
+  UI: '#00d4ff'
+} as const;
+
+// ── The scene ─────────────────────────────────────────────────────────
+
+/**
+ * The camera looks straight down: the guide must be a true circle on screen, since the drawing is
+ * scored in view points. The depth shows in the plate's bevel, the raised guide ring and the round tube.
+ */
+export const TILT = 0;
+export const LIGHT = frontLight([-0.4, 0.55, 1], 0.45);
+
+// ── Layout (view points) ──────────────────────────────────────────────
+
+const SCOREBOARD_HEIGHT = 82;
+const CONTROLS_HEIGHT = 120;
+
+export type Layout = TiltView & { cx: number; cy: number; radius: number };
+
+/**
+ * The guide circle: half the game width (the view less 30 points, at most 500) across, centred 55
+ * points below the middle of the screen, as the original canvas put it. On a screen too short for that, it
+ * shrinks and moves to fit between the scoreboard and the controls.
+ */
+export function getLayout(width: number, height: number, offset: number): Layout {
+  let radius = gameWidthFor(width) / 2;
+  const top = getScoreBoardTop(offset) + SCOREBOARD_HEIGHT + 8;
+  const bottom = height - CONTROLS_HEIGHT;
+  if (bottom - top < radius * 2) radius = Math.max(60, (bottom - top) / 2);
+  const cy = Math.min(Math.max(height / 2 + 55, top + radius), bottom - radius);
+  return { width, height, centerY: height / 2, tilt: TILT, cx: width / 2, cy, radius };
+}

package/src/games/perfect-circle/PerfectCircleGame.ts

@@ -0,0 +1,153 @@
+// Perfect Circle's play, with no React: build a game with `createGame`, give it a layout, `start` it and
+// `tick` it every frame. Press Start, then draw one circle round the guide with one finger; lifting it
+// scores the stroke (original's scoring, in PerfectCircleRules.ts) and ends the round: 80% or more wins.
+import { type Camera, type DragEvent, World } from '@nayan-ui/engine';
+import type { GameTheme } from '../../services/ThemeService';
+import { aimTilted } from '../shared/EngineTilt';
+import { type Layout, MIN_POINT_DISTANCE } from './PerfectCircleConstants';
+import { accuracyOf, fitCircle, MIN_POINTS, type Point, WIN_ACCURACY } from './PerfectCircleRules';
+import { beginStroke, buildScene, clearStroke, endStroke, extendStroke, removeScene, type Scene, setSceneTheme, verdict } from './PerfectCircleScene';
+
+export type Phase = 'ready' | 'playing' | 'over';
+/** begin / end: the finger went down / lifted; scored: the stroke's accuracy is in (not for one too short to count). */
+export type GameEvent = 'begin' | 'end' | 'scored';
+
+const WORLD_CAPACITY = 3000; // two entities a stroke point, the trace, the plate and ring, and the bursts
+const MAX_POINTS = 1400; // a stroke stops growing past this (several times round the guide)
+
+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 };
+  return {
+    world,
+    camera,
+    theme,
+    layout: null as Layout | null,
+    scene: null as Scene | null,
+    phase: 'ready' as Phase,
+    /** The stroke so far (view points, kept inside the guide), and whether a finger is drawing it. */
+    points: [] as Point[],
+    drawing: false,
+    accuracy: 0,
+    won: false,
+    fit: null as { cx: number; cy: number; r: number } | null,
+    // UI hooks, set by the screen.
+    onPhase: (_p: Phase) => {},
+    onAccuracy: (_a: number) => {},
+    onEvent: (_e: GameEvent) => {}
+  };
+}
+export type Game = ReturnType<typeof createGame>;
+
+// ── Scene ─────────────────────────────────────────────────────────────
+
+/** Lays the plate out for the view (first layout, header height, rotation); a stroke on it is cleared. */
+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);
+  // A drawing mid-stroke or on the result belongs to the old layout: start the round's stroke afresh
+  g.drawing = false;
+  if (g.phase !== 'over') g.points = [];
+}
+
+export function setTheme(g: Game, theme: GameTheme) {
+  g.theme = theme;
+  if (g.scene) setSceneTheme(g.world, g.scene, theme);
+}
+
+// ── Run ───────────────────────────────────────────────────────────────
+
+export function start(g: Game) {
+  if (g.phase !== 'ready') return;
+  reset(g);
+  g.phase = 'playing';
+  g.onPhase('playing');
+}
+
+/** An empty plate, not started (Stop, Play Again). The world, and the GPU view drawing it, are kept. */
+export function reset(g: Game) {
+  g.points = [];
+  g.drawing = false;
+  g.accuracy = 0;
+  g.won = false;
+  g.fit = null;
+  if (g.scene) clearStroke(g.world, g.scene);
+  g.onAccuracy(0);
+  if (g.phase !== 'ready') {
+    g.phase = 'ready';
+    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);
+}
+
+// ── The finger ────────────────────────────────────────────────────────
+
+/** A point kept inside the guide circle, as the original stroke clamped it. */
+function clamp(l: Layout, x: number, y: number): Point {
+  const dx = x - l.cx;
+  const dy = y - l.cy;
+  const d2 = dx * dx + dy * dy;
+  if (d2 <= l.radius * l.radius) return { x, y };
+  const k = l.radius / Math.sqrt(d2);
+  return { x: l.cx + dx * k, y: l.cy + dy * k };
+}
+
+/** One stroke per round: down starts it, every move of 4 points or more adds to it, lifting scores it. */
+export function drag(g: Game, { phase, x, y }: DragEvent) {
+  const { layout: l, scene: s } = g;
+  if (!l) return;
+  if (phase === 'start') {
+    if (g.phase !== 'playing' || g.drawing) return;
+    const p = clamp(l, x, y);
+    g.points = [p];
+    g.drawing = true;
+    if (s) beginStroke(g.world, l, s, p);
+    g.onEvent('begin');
+    return;
+  }
+  if (!g.drawing) return;
+  if (phase === 'move') {
+    const last = g.points[g.points.length - 1]!;
+    // The distance is from the last kept point to the raw finger, as the original stroke measured it
+    if ((x - last.x) ** 2 + (y - last.y) ** 2 < MIN_POINT_DISTANCE * MIN_POINT_DISTANCE || g.points.length >= MAX_POINTS) return;
+    const p = clamp(l, x, y);
+    g.points.push(p);
+    if (s) extendStroke(g.world, l, s, last, p);
+    return;
+  }
+  // Lifted (or the system took the touch): score what was drawn
+  g.drawing = false;
+  if (s) endStroke(g.world, s);
+  g.onEvent('end');
+  finish(g);
+}
+
+/** Scores the stroke against the guide and ends the round. */
+function finish(g: Game) {
+  const l = g.layout!;
+  if (g.points.length < MIN_POINTS) {
+    // Too short to be a circle: a loss; the shared phase callback supplies the verdict cue.
+    g.accuracy = 0;
+    g.won = false;
+  } else {
+    g.accuracy = accuracyOf(g.points, { centerX: l.cx, centerY: l.cy, radius: l.radius });
+    const fit = fitCircle(g.points);
+    g.fit = Number.isFinite(fit.radius) && fit.radius > 0 ? { cx: fit.centerX, cy: fit.centerY, r: fit.radius } : null;
+    g.won = g.accuracy >= WIN_ACCURACY;
+    g.onAccuracy(g.accuracy);
+    g.onEvent('scored');
+  }
+  if (g.scene) verdict(g.world, l, g.scene, g.won, g.fit, g.theme);
+  g.phase = 'over';
+  g.onPhase('over');
+}

package/src/games/perfect-circle/PerfectCircleRules.ts

@@ -0,0 +1,111 @@
+// Perfect Circle's scoring, with no React or engine: how round a drawn stroke is, against the guide
+// circle. Ported line for line from the original service (games/perfect-circle), so scores carry over:
+// a least-squares (Kasa) circle fit, then a closed-stroke and coverage check, then a weighted mix of
+// shape consistency, radius, centre and closure. Points are view points (y down).
+
+export type Point = { x: number; y: number };
+export type Circle = { centerX: number; centerY: number; radius: number };
+
+export const MIN_POINTS = 20; // fewer and it isn't a circle at all
+export const WIN_ACCURACY = 80; // the result counts as a win from here, as the original game decided
+export const SUCCESS_ACCURACY = 70; // and its "success" sound plays from here
+
+/** The circle that best fits the points (least squares), or the centroid's average radius if they're degenerate. */
+export function fitCircle(points: Point[]): Circle {
+  const n = points.length;
+  let sumX = 0,
+    sumY = 0,
+    sumX2 = 0,
+    sumY2 = 0,
+    sumXY = 0,
+    sumX3 = 0,
+    sumY3 = 0,
+    sumX2Y = 0,
+    sumXY2 = 0;
+  for (const p of points) {
+    const x = p.x,
+      y = p.y;
+    const x2 = x * x,
+      y2 = y * y;
+    sumX += x;
+    sumY += y;
+    sumX2 += x2;
+    sumY2 += y2;
+    sumXY += x * y;
+    sumX3 += x2 * x;
+    sumY3 += y2 * y;
+    sumX2Y += x2 * y;
+    sumXY2 += x * y2;
+  }
+  const A = n * sumX2 - sumX * sumX;
+  const B = n * sumXY - sumX * sumY;
+  const C = n * sumY2 - sumY * sumY;
+  const D = 0.5 * (n * sumX3 + n * sumXY2 - sumX * sumX2 - sumX * sumY2);
+  const E = 0.5 * (n * sumX2Y + n * sumY3 - sumY * sumX2 - sumY * sumY2);
+  const denom = A * C - B * B;
+  let centerX: number, centerY: number;
+  if (Math.abs(denom) < 1e-10) {
+    centerX = sumX / n;
+    centerY = sumY / n;
+  } else {
+    centerX = (D * C - B * E) / denom;
+    centerY = (A * E - B * D) / denom;
+  }
+  let radiusSum = 0;
+  for (const p of points) radiusSum += Math.sqrt((p.x - centerX) ** 2 + (p.y - centerY) ** 2);
+  return { centerX, centerY, radius: radiusSum / n };
+}
+
+/** How much of a full turn the stroke went round the centre (0..1). */
+function angularCoverage(points: Point[], centerX: number, centerY: number): number {
+  if (points.length < 2) return 0;
+  let previous = Math.atan2(points[0]!.y - centerY, points[0]!.x - centerX);
+  let total = 0;
+  for (let i = 1; i < points.length; i++) {
+    const angle = Math.atan2(points[i]!.y - centerY, points[i]!.x - centerX);
+    let diff = angle - previous;
+    previous = angle;
+    while (diff > Math.PI) diff -= 2 * Math.PI;
+    while (diff < -Math.PI) diff += 2 * Math.PI;
+    total += Math.abs(diff);
+  }
+  return Math.min(total / (2 * Math.PI), 1);
+}
+
+/** The stroke's accuracy (0..100) against the guide circle (centre and radius in view points). */
+export function accuracyOf(points: Point[], guide: Circle): number {
+  if (points.length < MIN_POINTS) return 0;
+  const { centerX, centerY, radius } = fitCircle(points);
+  if (radius < 30) return 0;
+  const start = points[0]!;
+  const end = points[points.length - 1]!;
+  // Closed: the ends must meet within 15% of the guide's radius
+  const closureDistance = Math.sqrt((end.x - start.x) ** 2 + (end.y - start.y) ** 2);
+  const maxAllowedGap = guide.radius * 0.15;
+  if (closureDistance > maxAllowedGap) return 0;
+  // And it must go at least 85% of the way round
+  if (angularCoverage(points, centerX, centerY) < 0.85) return 0;
+  const radiusAccuracyScore = Math.max(0, 100 * (1 - Math.abs(radius - guide.radius) / guide.radius));
+  const centerDiff = Math.sqrt((centerX - guide.centerX) ** 2 + (centerY - guide.centerY) ** 2);
+  const centerAccuracyScore = Math.max(0, 100 * (1 - centerDiff / guide.radius));
+  let totalDeviation = 0;
+  for (const p of points) {
+    const dist = Math.sqrt((p.x - centerX) ** 2 + (p.y - centerY) ** 2);
+    totalDeviation += Math.abs(dist - radius) / radius;
+  }
+  const shapeConsistencyScore = Math.max(0, 100 * (1 - (totalDeviation / points.length) * 2));
+  const closureScore = 100 * (1 - closureDistance / maxAllowedGap);
+  const accuracy = shapeConsistencyScore * 0.6 + radiusAccuracyScore * 0.15 + centerAccuracyScore * 0.15 + closureScore * 0.1;
+  return Math.round(Math.min(100, Math.max(0, accuracy)));
+}
+
+/** The accuracy levels the game-over card names, best first. */
+export const ACCURACY_LEVELS = [
+  { min: 95, label: 'PERFECT!' },
+  { min: 90, label: 'EXCELLENT!' },
+  { min: 85, label: 'GREAT!' },
+  { min: 80, label: 'GOOD!' },
+  { min: 70, label: 'NICE TRY!' },
+  { min: 0, label: 'KEEP TRYING!' }
+] as const;
+export const levelOf = (accuracy: number) => ACCURACY_LEVELS.find((l) => accuracy >= l.min) ?? ACCURACY_LEVELS[ACCURACY_LEVELS.length - 1]!;

package/src/games/perfect-circle/PerfectCircleScene.ts

@@ -0,0 +1,176 @@
+// Everything Perfect Circle draws: a round plate (themed, as the original guide's fill) with the guide
+// circle standing on it as a raised ring, the stroke drawn as a glowing neon tube (a rounded segment
+// for every step of the finger, joined by balls, all instances of the engine's built-in shapes: no
+// mesh is built as you draw), a glowing pen tip under the finger, and on the verdict the stroke tinted
+// green or red with the best-fit circle of the drawing traced round over it. The camera looks straight
+// down (one world unit per point), so the guide is a true circle on screen, as the scoring needs.
+import { type Color, effects, type Entity, type Model, quat, tube, 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 { placeTiltedBackdrop } from '../shared/EngineTilt';
+import { toColor } from '../shared/EngineUtils';
+import { COLORS, FIT_TRACE_TIME, type Layout, STROKE_RADIUS, TINT_TIME } from './PerfectCircleConstants';
+import type { Point } from './PerfectCircleRules';
+
+const meshes = new Map<string, Model>();
+const cached = (key: string, build: () => Model) => {
+  let m = meshes.get(key);
+  if (!m) {
+    m = cacheGameAsset('perfect-circle/PerfectCircleScene:' + key, build);
+    meshes.set(key, m);
+  }
+  return m;
+};
+const STAND_UP = quat.x(Math.PI / 2);
+const BACKDROP_DEPTH = 30;
+const PLATE_DEPTH = 6;
+const STROKE_Z = 4; // the tube's centre above the plate
+const FIT_SEGMENTS = 72;
+
+/** The guide: a ring of radius 1 with a tube `thickness` across (of the radius), lying on the plate. */
+const ringMesh = (thickness: number) =>
+  cached(`pc-ring:${thickness.toFixed(4)}`, () => {
+    const pts: Vec3[] = Array.from({ length: 97 }, (_, i) => {
+      const a = (i / 96) * Math.PI * 2;
+      return [Math.cos(a), Math.sin(a), 0];
+    });
+    return createShape(tube(pts, { radius: thickness / 2, sides: 12, smoothness: 2, caps: false }), { center: false, shine: 0.5 });
+  });
+
+/** A stroke's colour, a little self-lit so it reads as neon (channels above 1 glow). */
+const neon = (css: string): Color => {
+  const [r, g, b] = toColor(css);
+  return [r * 1.25, g * 1.25, b * 1.25, 1];
+};
+
+// ── Spawning ──────────────────────────────────────────────────────────
+
+export type Scene = {
+  backdrop: Entity;
+  plate: Entity;
+  ring: Entity;
+  tip: Entity;
+  /** The stroke's segments and joints, in drawing order. */
+  stroke: Entity[];
+  fit: Entity[];
+};
+
+/** A view point on the plate, in the world. */
+export const toWorld = (l: Layout, p: Point, z = STROKE_Z): Vec3 => [p.x - l.width / 2, l.height / 2 - p.y, z];
+
+const plateColor = (theme: GameTheme): Color => (theme.mode === 'classic' ? toColor(COLORS.GUIDE, 0.2) : toColor(theme.BOARD.SURFACE));
+const ringColor = (theme: GameTheme): Color => (theme.mode === 'classic' ? toColor(COLORS.GUIDE, 0.45) : toColor(theme.BOARD.BORDER));
+
+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 centre = toWorld(l, { x: l.cx, y: l.cy }, 0);
+  const d = l.radius * 2 + 10;
+  const plate = world.spawn({
+    mesh: 'cylinder',
+    position: [centre[0], centre[1], -PLATE_DEPTH / 2],
+    rotation: STAND_UP,
+    scale: [d, PLATE_DEPTH, d],
+    color: plateColor(theme),
+    pickable: false
+  });
+  const ring = world.spawn({
+    mesh: ringMesh(3 / l.radius),
+    position: [centre[0], centre[1], 1.5],
+    scale: l.radius,
+    color: ringColor(theme),
+    pickable: false
+  });
+  const tip = world.spawn({ mesh: 'sphere', scale: 0, color: neon(COLORS.STROKE), pickable: false });
+  return { backdrop, plate, ring, tip, stroke: [], fit: [] };
+}
+
+export function removeScene(world: World, s: Scene) {
+  for (const e of [s.backdrop, s.plate, s.ring, s.tip, ...s.stroke, ...s.fit]) world.despawn(e);
+}
+
+export function setSceneTheme(world: World, s: Scene, theme: GameTheme) {
+  setBackdropTheme(world, s.backdrop, theme);
+  world.set(s.plate, { color: plateColor(theme) });
+  world.set(s.ring, { color: ringColor(theme) });
+}
+
+// ── The stroke ────────────────────────────────────────────────────────
+
+/** A rounded bar from a to b (world points in the plate's plane), as a cylinder turned to lie along it. */
+function bar(world: World, a: Vec3, b: Vec3, radius: number, color: Color, scale = 1): Entity {
+  const dx = b[0] - a[0];
+  const dy = b[1] - a[1];
+  const len = Math.hypot(dx, dy);
+  return world.spawn({
+    mesh: 'cylinder',
+    position: [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2, a[2]],
+    rotation: quat.z(Math.atan2(dy, dx) - Math.PI / 2),
+    scale: [radius * 2 * scale, len * scale, radius * 2 * scale],
+    color,
+    pickable: false
+  });
+}
+
+/** The finger's first point: the pen tip comes down there. */
+export function beginStroke(world: World, l: Layout, s: Scene, p: Point) {
+  clearStroke(world, s);
+  const at = toWorld(l, p);
+  s.stroke.push(world.spawn({ mesh: 'sphere', position: at, scale: STROKE_RADIUS * 2, color: neon(COLORS.STROKE), pickable: false }));
+  world.stopAnimation(s.tip);
+  world.set(s.tip, { position: [at[0], at[1], at[2] + 1], color: neon(COLORS.STROKE) });
+  world.animate(s.tip, { scale: STROKE_RADIUS * 3.2 }, { duration: 0.12, easing: 'back' });
+}
+
+/** The stroke reaches a new point: a segment out to it and a joint there; the pen tip follows. */
+export function extendStroke(world: World, l: Layout, s: Scene, from: Point, to: Point) {
+  const a = toWorld(l, from);
+  const b = toWorld(l, to);
+  const c = neon(COLORS.STROKE);
+  s.stroke.push(bar(world, a, b, STROKE_RADIUS, c));
+  s.stroke.push(world.spawn({ mesh: 'sphere', position: b, scale: STROKE_RADIUS * 2, color: c, pickable: false }));
+  world.set(s.tip, { position: [b[0], b[1], b[2] + 1] });
+}
+
+/** The finger lifts: the pen tip goes. */
+export function endStroke(world: World, s: Scene) {
+  world.animate(s.tip, { scale: 0 }, { duration: 0.15 });
+}
+
+/** The verdict: the stroke tints to green or red with a pulse, and the best-fit circle traces round over it. */
+export function verdict(world: World, l: Layout, s: Scene, won: boolean, fit: { cx: number; cy: number; r: number } | null, theme: GameTheme) {
+  const c = neon(won ? COLORS.SUCCESS : COLORS.FAIL);
+  for (const e of s.stroke) world.animate(e, { color: c }, { duration: TINT_TIME, easing: 'easeOut' });
+  effects.sparkle(world, {
+    position: toWorld(l, { x: l.cx, y: l.cy }, 10),
+    count: won ? 50 : 14,
+    size: 3,
+    speed: l.radius * (won ? 2.2 : 1),
+    lifetime: 0.9,
+    colors: [c, [1, 1, 1, 1]],
+    flash: won
+  });
+  if (!fit) return;
+  const fitColor: Color = theme.mode === 'classic' ? [1, 1, 1, 0.6] : toColor(theme.TEXT, 0.6);
+  // From twelve o'clock round, as the original trace
+  for (let i = 0; i < FIT_SEGMENTS; i++) {
+    const a0 = -Math.PI / 2 + (i / FIT_SEGMENTS) * Math.PI * 2;
+    const a1 = -Math.PI / 2 + ((i + 1) / FIT_SEGMENTS) * Math.PI * 2;
+    const p0 = toWorld(l, { x: fit.cx + Math.cos(a0) * fit.r, y: fit.cy + Math.sin(a0) * fit.r }, STROKE_Z + 3);
+    const p1 = toWorld(l, { x: fit.cx + Math.cos(a1) * fit.r, y: fit.cy + Math.sin(a1) * fit.r }, STROKE_Z + 3);
+    const e = bar(world, p0, p1, 0.9, fitColor, 0.001);
+    const len = Math.hypot(p1[0] - p0[0], p1[1] - p0[1]);
+    world.animate(e, { scale: [1.8, len * 1.05, 1.8] }, { duration: 0.06, delay: TINT_TIME / 2 + (i / FIT_SEGMENTS) * FIT_TRACE_TIME });
+    s.fit.push(e);
+  }
+}
+
+/** Clears the stroke and the trace (a new game). */
+export function clearStroke(world: World, s: Scene) {
+  for (const e of [...s.stroke, ...s.fit]) world.despawn(e);
+  s.stroke = [];
+  s.fit = [];
+  world.stopAnimation(s.tip);
+  world.set(s.tip, { scale: 0 });
+}

package/src/games/pipe-connect/PipeConnect.tsx

@@ -0,0 +1,69 @@
+// Pipe Connect's screen, on the Nayan engine: the board, tiles and pipes are one 3D scene (an
+// orthographic camera leaning back over the board), under Playtura's scoreboard, controls and modals.
+// The play is in PipeConnectGame.ts (the puzzles in PipeConnectRules.ts), what it draws in
+// PipeConnectScene.ts.
+//
+// One world serves the whole visit: Start, Stop and Play Again reset it in place and a theme change
+// repaints the board, so the GPU view is never rebuilt. Turns and the water's flow animate in the
+// engine's Rust core; JS hit-tests taps and steps the clock and the world once a frame.
+import { HapticType } from '../../services/HapticsService';
+import { GAME_SOUNDS } from '../../services/SoundsService';
+import { GAME_IDS, isTablet } from '../../services/UtilsService';
+import { engineGame, EngineGameScreen } from '../shared/EngineGameScreen';
+import { timerColumn } from '../shared/EngineHud';
+import { useEngineGame } from '../shared/useEngineGame';
+import { useLiveState } from '../shared/useLiveState';
+import { getLayout, gridSizeFor, LIGHT, TIME_LIMIT } from './PipeConnectConstants';
+import { createGame, dispose, reset, setLayout, setTheme, start, tap, tick } from './PipeConnectGame';
+
+const SOUNDS = GAME_SOUNDS.PIPE_CONNECT;
+// As the original game: the grid's size is fixed for the device
+const GRID_SIZE = gridSizeFor(isTablet);
+
+export const PipeConnect = engineGame(GAME_IDS.PIPE_CONNECT, (props) => {
+  const [time, setTime] = useLiveState(TIME_LIMIT);
+
+  // Win or lose when the puzzle ends
+  const { game, theme, status, screen, gameOver } = useEngineGame(props, {
+    gameId: GAME_IDS.PIPE_CONNECT,
+    create: (t) => createGame(t, GRID_SIZE),
+    start,
+    reset,
+    dispose,
+    tick,
+    setTheme,
+    resize: (g, width, height, offset) => {
+      const l = getLayout(width, height, offset, GRID_SIZE);
+      setLayout(g, l);
+      return l.board;
+    },
+    tap,
+    sounds: SOUNDS,
+    onStart: (fx) => fx(SOUNDS.START, HapticType.MEDIUM),
+    onStop: (fx) => fx(null, HapticType.MEDIUM),
+    // Its sound (and a time-up's haptic)
+    onOver: (fx, s) => {
+      if (s !== 'win') fx(SOUNDS.GAME_OVER, HapticType.HEAVY);
+    },
+    wire: (g, fx) => {
+      g.onTime = setTime;
+      g.onTurn = (solved) => fx(solved ? SOUNDS.COMPLETE : SOUNDS.ROTATE, solved ? HapticType.SUCCESS : HapticType.LIGHT);
+    }
+  });
+
+  return (
+    <EngineGameScreen
+      {...screen}
+      light={LIGHT}
+      columns={[timerColumn(time, theme, 0)]}
+      subtext="Connect the pipes!"
+      gameOver={gameOver({
+        title: status === 'win' ? 'CONNECTED!' : 'TIME UP!',
+        message: status === 'win' ? 'All pipes connected!' : 'You ran out of time!',
+        scoreLabel: 'Final Score',
+        score: game.score,
+        buttonText: 'Play Again!'
+      })}
+    />
+  );
+});