@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/shared/EngineBackdrop.ts

@@ -0,0 +1,300 @@
+import { type Entity, type Geometry, type Model, type World } from '@nayan-ui/engine';
+import { type GamePattern, gamePattern, PATTERN_GRID_COLOR, type PatternGradient, type PatternShape } from '../../helpers/GamePatternData';
+import type { GameTheme } from '../../services/ThemeService';
+// The Playtura game background (theme color plus the rainbow pattern), built by the Nayan engine with
+// no original. The pattern (helpers/GamePatternData) is turned into one opaque mesh whose vertex colors are
+// what the original pattern composites to at each point: the gradients on a fine grid, the shapes and grid
+// lines layered on top with the layers under them baked in. One draw call, nothing to blend each frame.
+// Shared by the engine games' scenes and the modal cards (BackdropCard).
+import { getScreenDimensions } from '../../services/UtilsService';
+import { cacheGameAsset, createGameMesh as createShape } from './EngineMeshes';
+import { frontLight, toColor } from './EngineUtils';
+
+type RGBA = [number, number, number, number];
+
+/** Any front light works: these flat meshes face the camera, which it lights at exactly 1. */
+export const BACKDROP_LIGHT = frontLight([0, 0, 1], 1);
+
+const GRID_STEP = 16; // points between gradient samples (stops are ~100pt apart)
+const SEGMENTS = 40; // around a circle
+const CORNER_SEGMENTS = 6;
+const LAYER_GAP = 0.05; // depth between layers, toward the camera
+
+// ── Compositing (original's: stops interpolated unpremultiplied, layers source-over, group opacity) ──
+
+function gradientAt(g: PatternGradient, stops: RGBA[], x: number, y: number): RGBA {
+  const dx = g.end[0] - g.start[0];
+  const dy = g.end[1] - g.start[1];
+  const t = Math.max(0, Math.min(1, ((x - g.start[0]) * dx + (y - g.start[1]) * dy) / (dx * dx + dy * dy)));
+  const p = t * (stops.length - 1);
+  const i = Math.min(stops.length - 2, Math.floor(p));
+  const f = p - i;
+  const a = stops[i]!;
+  const b = stops[i + 1]!;
+  return [a[0] + (b[0] - a[0]) * f, a[1] + (b[1] - a[1]) * f, a[2] + (b[2] - a[2]) * f, a[3] + (b[3] - a[3]) * f];
+}
+
+function contains(s: PatternShape, x: number, y: number) {
+  switch (s.kind) {
+    case 'circle':
+      return (x - s.cx) ** 2 + (y - s.cy) ** 2 <= s.r * s.r;
+    case 'rrect':
+      return x >= s.x && x <= s.x + s.w && y >= s.y && y <= s.y + s.h;
+    default:
+      return Math.abs(x - s.cx) + Math.abs(y - s.cy) <= s.size / 2;
+  }
+}
+
+/** Composites a pattern point: the gradients, then the shapes up to `layers` (index), then `top` if given. */
+class Compositor {
+  private readonly stops: RGBA[][];
+  private readonly colors: RGBA[];
+  private readonly gridColor = toColor(PATTERN_GRID_COLOR) as RGBA;
+  private readonly bg: RGBA;
+
+  constructor(
+    private readonly pattern: GamePattern,
+    background: string,
+    private readonly opacity: number
+  ) {
+    this.stops = pattern.gradients.map((g) => g.colors.map((c) => toColor(c) as RGBA));
+    this.colors = pattern.shapes.map((s) => toColor(s.color) as RGBA);
+    this.bg = toColor(background) as RGBA;
+  }
+
+  /** Final RGB at (x, y) with shapes [0, shapes) under it, plus shape `self` (or the grid) on top. */
+  at(x: number, y: number, shapes: number, self: number | 'grid' | null): [number, number, number] {
+    // Premultiplied accumulation of the pattern group
+    let r = 0;
+    let g = 0;
+    let b = 0;
+    let a = 0;
+    const over = (c: RGBA) => {
+      const k = 1 - c[3];
+      r = c[0] * c[3] + r * k;
+      g = c[1] * c[3] + g * k;
+      b = c[2] * c[3] + b * k;
+      a = c[3] + a * k;
+    };
+    this.pattern.gradients.forEach((grad, i) => over(gradientAt(grad, this.stops[i]!, x, y)));
+    for (let i = 0; i < shapes; i++) if (contains(this.pattern.shapes[i]!, x, y)) over(this.colors[i]!);
+    if (typeof self === 'number') over(this.colors[self]!);
+    else if (self === 'grid') over(this.gridColor);
+    // The group at the theme's pattern opacity over the background color
+    const o = this.opacity;
+    return [r * o + this.bg[0] * (1 - a * o), g * o + this.bg[1] * (1 - a * o), b * o + this.bg[2] * (1 - a * o)];
+  }
+}
+
+// ── Mesh ──────────────────────────────────────────────────────────────
+
+class MeshBuilder {
+  vertices: number[] = [];
+  indices: number[] = [];
+  /** A vertex at pattern point (x, y) (y down), depth z. */
+  vertex(x: number, y: number, z: number, [r, g, b]: [number, number, number]) {
+    this.vertices.push(x, -y, z, 0, 0, 1, r, g, b, 0, 0);
+    return this.vertices.length / 11 - 1;
+  }
+  /** A quad from its corners, counter-clockwise seen from the camera (y up). */
+  quad(a: number, b: number, c: number, d: number) {
+    this.indices.push(a, b, c, a, c, d);
+  }
+  geometry(): Geometry {
+    return { vertices: new Float32Array(this.vertices), indices: new Uint32Array(this.indices) };
+  }
+}
+
+/** A shape's outline in pattern points (y down), counter-clockwise with y up (as the camera sees it). */
+function outline(s: PatternShape): [number, number][] {
+  if (s.kind === 'circle') {
+    return Array.from({ length: SEGMENTS }, (_, k) => {
+      const t = (-k / SEGMENTS) * Math.PI * 2;
+      return [s.cx + Math.cos(t) * s.r, s.cy + Math.sin(t) * s.r] as [number, number];
+    });
+  }
+  if (s.kind === 'diamond') {
+    const h = s.size / 2;
+    return [
+      [s.cx + h, s.cy],
+      [s.cx, s.cy - h],
+      [s.cx - h, s.cy],
+      [s.cx, s.cy + h]
+    ];
+  }
+  const r = Math.min(s.r, s.w / 2, s.h / 2);
+  // Corner centres (y down) with each arc's start angle, counter-clockwise with y up: bottom-right,
+  // top-right, top-left, bottom-left. Each arc turns a quarter; y down flips the sine.
+  const corners: [number, number, number][] = [
+    [s.x + s.w - r, s.y + s.h - r, -Math.PI / 2],
+    [s.x + s.w - r, s.y + r, 0],
+    [s.x + r, s.y + r, Math.PI / 2],
+    [s.x + r, s.y + s.h - r, Math.PI]
+  ];
+  const points: [number, number][] = [];
+  for (const [cx, cy, from] of corners) {
+    for (let k = 0; k <= CORNER_SEGMENTS; k++) {
+      const t = from + (k / CORNER_SEGMENTS) * (Math.PI / 2);
+      points.push([cx + Math.cos(t) * r, cy - Math.sin(t) * r]);
+    }
+  }
+  return points;
+}
+
+function centreOf(s: PatternShape): [number, number] {
+  return s.kind === 'rrect' ? [s.x + s.w / 2, s.y + s.h / 2] : [s.cx, s.cy];
+}
+
+function buildGeometry(pattern: GamePattern, background: string, opacity: number, withGrid = true): Geometry {
+  const m = new MeshBuilder();
+  const c = new Compositor(pattern, background, opacity);
+  const { width, height, shapes } = pattern;
+  const grid = withGrid ? pattern.grid : [];
+
+  // The gradients on a grid
+  const nx = Math.ceil(width / GRID_STEP);
+  const ny = Math.ceil(height / GRID_STEP);
+  const first = m.vertices.length / 11;
+  for (let j = 0; j <= ny; j++) {
+    const y = Math.min(height, j * GRID_STEP);
+    for (let i = 0; i <= nx; i++) {
+      const x = Math.min(width, i * GRID_STEP);
+      m.vertex(x, y, 0, c.at(x, y, 0, null));
+    }
+  }
+  const at = (i: number, j: number) => first + j * (nx + 1) + i;
+  for (let j = 0; j < ny; j++) for (let i = 0; i < nx; i++) m.quad(at(i, j + 1), at(i + 1, j + 1), at(i + 1, j), at(i, j));
+
+  // Each shape as a fan, above the ones before it
+  shapes.forEach((s, k) => {
+    const z = (k + 1) * LAYER_GAP;
+    const [cx, cy] = centreOf(s);
+    const centre = m.vertex(cx, cy, z, c.at(cx, cy, k, k));
+    const ring = outline(s).map(([x, y]) => m.vertex(x, y, z, c.at(x, y, k, k)));
+    ring.forEach((v, i) => m.indices.push(centre, v, ring[(i + 1) % ring.length]!));
+  });
+
+  // The grid lines, split along their length so the colors under them follow
+  const z = (shapes.length + 1) * LAYER_GAP;
+  for (const line of grid) {
+    const long = Math.max(line.w, line.h);
+    const steps = Math.max(1, Math.ceil(long / GRID_STEP));
+    const vertical = line.h > line.w;
+    let prev: [number, number] | null = null;
+    for (let s = 0; s <= steps; s++) {
+      const t = Math.min(long, s * GRID_STEP);
+      // The two edge points across the line at distance t along it
+      const p: [number, number, number, number] = vertical
+        ? [line.x, line.y + t, line.x + line.w, line.y + t]
+        : [line.x + t, line.y, line.x + t, line.y + line.h];
+      const a = m.vertex(p[0], p[1], z, c.at(p[0], p[1], shapes.length, 'grid'));
+      const b = m.vertex(p[2], p[3], z, c.at(p[2], p[3], shapes.length, 'grid'));
+      if (prev) {
+        // Vertical: prev is above (smaller y). Horizontal: prev is to the left.
+        if (vertical) m.quad(a, b, prev[1], prev[0]);
+        else m.quad(prev[1], b, a, prev[0]);
+      }
+      prev = [a, b];
+    }
+  }
+  return m.geometry();
+}
+
+// One mesh per theme and window size: mesh ids are app-wide and limited, and they last for the app.
+const meshes = new Map<string, Model>();
+
+/** The background mesh in pattern space: x right, y up from the window's top-left (y runs to -height). */
+export function backdropMesh(theme: GameTheme): Model {
+  const { width, height } = getScreenDimensions();
+  const key = `${theme.BACKGROUND}:${theme.PATTERN_OPACITY}:${Math.round(width)}x${Math.round(height)}`;
+  let mesh = meshes.get(key);
+  if (!mesh) {
+    mesh = cacheGameAsset(`backdrop:${key}`, () =>
+      createShape(buildGeometry(gamePattern(width, height), theme.BACKGROUND, theme.PATTERN_OPACITY), { center: false })
+    );
+    meshes.set(key, mesh);
+  }
+  return mesh;
+}
+
+const FLOATS = 11;
+
+/** Keeps the parts of `geometry` inside a convex polygon (x, y as stored, counter-clockwise), interpolating every vertex attribute. */
+function clipGeometry({ vertices, indices }: Geometry, poly: [number, number][]): Geometry {
+  type V = number[];
+  const out: number[] = [];
+  const outIdx: number[] = [];
+  const read = (i: number): V => Array.from(vertices.subarray(i * FLOATS, i * FLOATS + FLOATS));
+  for (let t = 0; t < indices.length; t += 3) {
+    let shape: V[] = [read(indices[t]!), read(indices[t + 1]!), read(indices[t + 2]!)];
+    for (let e = 0; e < poly.length && shape.length > 0; e++) {
+      const [ax, ay] = poly[e]!;
+      const [bx, by] = poly[(e + 1) % poly.length]!;
+      const side = (v: V) => (bx - ax) * (v[1]! - ay) - (by - ay) * (v[0]! - ax);
+      const next: V[] = [];
+      for (let i = 0; i < shape.length; i++) {
+        const p = shape[i]!;
+        const q = shape[(i + 1) % shape.length]!;
+        const sp = side(p);
+        const sq = side(q);
+        if (sp >= 0) next.push(p);
+        if (sp >= 0 !== sq >= 0) {
+          const f = sp / (sp - sq);
+          next.push(p.map((x, k) => x + (q[k]! - x) * f));
+        }
+      }
+      shape = next;
+    }
+    if (shape.length < 3) continue;
+    const base = out.length / FLOATS;
+    for (const v of shape) out.push(...v);
+    for (let i = 1; i + 1 < shape.length; i++) outIdx.push(base, base + i, base + i + 1);
+  }
+  return { vertices: new Float32Array(out), indices: new Uint32Array(outIdx) };
+}
+
+/**
+ * A modal card's background: the window pattern's top-left `width` x `height` (its gradients and
+ * shapes, without the grid lines), cut to a rounded rectangle of corner `radius`. Same space as
+ * `backdropMesh` (from the top-left, y up).
+ */
+export function cardBackdropMesh(theme: GameTheme, width: number, height: number, radius: number): Model {
+  const win = getScreenDimensions();
+  const [w, h] = [Math.round(width), Math.round(height)];
+  const key = `card-nogrid:${theme.BACKGROUND}:${theme.PATTERN_OPACITY}:${Math.round(win.width)}x${Math.round(win.height)}:${w}x${h}:${radius}`;
+  let mesh = meshes.get(key);
+  if (!mesh) {
+    const r = Math.min(radius, w / 2, h / 2);
+    // The rounded rectangle, counter-clockwise with y up (stored y = -pattern y)
+    const poly: [number, number][] = [];
+    const corners: [number, number, number][] = [
+      [w - r, -h + r, -Math.PI / 2],
+      [w - r, -r, 0],
+      [r, -r, Math.PI / 2],
+      [r, -h + r, Math.PI]
+    ];
+    for (const [cx, cy, from] of corners) {
+      for (let k = 0; k <= CORNER_SEGMENTS; k++) {
+        const t = from + (k / CORNER_SEGMENTS) * (Math.PI / 2);
+        poly.push([cx + Math.cos(t) * r, cy + Math.sin(t) * r]);
+      }
+    }
+    const full = buildGeometry(gamePattern(win.width, win.height), theme.BACKGROUND, theme.PATTERN_OPACITY, false);
+    mesh = createShape(clipGeometry(full, poly), { center: false });
+    meshes.set(key, mesh);
+  }
+  return mesh;
+}
+
+/**
+ * The background behind a centred, one-unit-per-point scene `width` x `height` (the view's size), at
+ * depth `z`: the pattern starts at the view's top-left, as the original screens draw it.
+ */
+export function spawnBackdrop(world: World, width: number, height: number, z: number, theme: GameTheme): Entity {
+  return world.spawn({ mesh: backdropMesh(theme), position: [-width / 2, height / 2, z], color: [1, 1, 1, 1], pickable: false });
+}
+
+/** Repaints a backdrop for a new theme. */
+export function setBackdropTheme(world: World, backdrop: Entity, theme: GameTheme) {
+  world.set(backdrop, { mesh: backdropMesh(theme) });
+}

package/src/games/shared/EngineBlasts.ts

@@ -0,0 +1,136 @@
+// Game blasts that need meshes from the games' asset cache: the cleared-piece pop's glow disc and
+// the baton catch. The particle effects themselves (confetti, sparkle, shatter, splash, sparks,
+// explosion, dust, flash) and the swell-and-shrink pop live in the engine as `effects`.
+import { type Color, effects, type Entity, extrude, type Model, Path, type PopOptions, type Quat, type Vec3, type World } from '@nayan-ui/engine';
+import { cacheGameAsset, createGameMesh as createShape } from './EngineMeshes';
+
+export type PopBurstOptions = {
+  /** Where the beads fly out from (a little in front of the piece reads best). */
+  position: Vec3;
+  /** The piece's size across, which the burst scales with. */
+  size: number;
+  /** The piece's color. */
+  color: Color;
+  /** Depth of the glow (behind the piece, in front of the board). Default the burst's own depth. */
+  glowZ?: number;
+  /** Beads and glints, about. Default 8. */
+  count?: number;
+};
+
+const WHITE: Color = [1, 1, 1, 1];
+const fade = (c: Color): [number, number, number, number] => [c[0], c[1], c[2], 0];
+
+let disc: Model | null = null;
+/** A flat disc one unit across, facing +z. */
+const discMesh = () =>
+  cacheGameAsset('shared/EngineBlasts:discMesh', () => (disc ??= createShape(extrude(new Path().addCircle(0, 0, 0.5), { depth: 0 }))));
+
+/** Bright beads and glints in the piece's color and white, over a glow that swells and fades behind it. */
+export function popBurst(world: World, o: PopBurstOptions) {
+  const [r, g, b] = o.color;
+  effects.sparkle(world, {
+    position: o.position,
+    count: o.count ?? 8,
+    size: o.size * 0.2,
+    speed: o.size * 6,
+    lifetime: 0.45,
+    colors: [o.color, WHITE],
+    flash: false
+  });
+  const glow = world.spawn({
+    mesh: discMesh(),
+    position: [o.position[0], o.position[1], o.glowZ ?? o.position[2]],
+    scale: o.size * 0.85,
+    color: [r, g, b, 0.6],
+    pickable: false
+  });
+  world.animate(glow, { scale: o.size * 2.8, color: [r, g, b, 0] }, { duration: 0.28 }).then(() => {
+    if (world.has(glow)) world.despawn(glow);
+  });
+}
+
+/** Both: the piece pops away and bursts as it swells. Resolves when it's gone (despawning it is the caller's). */
+export function popAndBurst(world: World, entity: Entity, pop: PopOptions, burst: PopBurstOptions): Promise<void> {
+  const delay = pop.delay ?? 0;
+  const duration = pop.duration ?? effects.POP_TIME;
+  if (delay > 0) world.after(delay + duration * 0.12, () => popBurst(world, burst));
+  else popBurst(world, burst);
+  return effects.pop(world, entity, pop);
+}
+
+let stickChip: Model | null = null;
+let catchRing: Model | null = null;
+const stickChipMesh = () =>
+  cacheGameAsset(
+    'shared/EngineBlasts:stickChipMesh',
+    () => (stickChip ??= createShape(extrude(new Path().addRoundedRect(-0.5, -0.09, 1, 0.18, 0.07), { depth: 0.16 }), { shine: 0.25 }))
+  );
+const catchRingMesh = () =>
+  cacheGameAsset(
+    'shared/EngineBlasts:catchRingMesh',
+    () => (catchRing ??= createShape(extrude(new Path().addCircle(0, 0, 0.5).addCircle(0, 0, 0.465), { depth: 0, fillRule: 'evenodd' })))
+  );
+
+/** A baton catch: a full-body pop, expanding ring, colorful splinters and two tip sprays. */
+export function stickBlast(world: World, entity: Entity, o: { position: Vec3; rotation: Quat; scale: Vec3; color: Color }): Promise<void> {
+  const [length, width] = o.scale;
+  const [x, y, z, w] = o.rotation;
+  const axis: Vec3 = [1 - 2 * (y * y + z * z), 2 * (x * y + w * z), 2 * (x * z - w * y)];
+  const normal: Vec3 = [2 * (x * z + w * y), 2 * (y * z - w * x), 1 - 2 * (x * x + y * y)];
+  const at = (along: number, lift = 0): Vec3 => [
+    o.position[0] + axis[0] * length * along + normal[0] * lift,
+    o.position[1] + axis[1] * length * along + normal[1] * lift,
+    o.position[2] + axis[2] * length * along + normal[2] * lift
+  ];
+  const done = popAndBurst(
+    world,
+    entity,
+    { scale: o.scale, color: o.color, duration: 0.32 },
+    {
+      position: at(0, width * 0.6),
+      size: Math.max(width * 1.6, length * 0.24),
+      color: o.color,
+      count: 14
+    }
+  );
+  stickChip = stickChipMesh();
+  effects.shatter(world, {
+    position: at(0, width * 0.4),
+    mesh: stickChip,
+    count: 7,
+    size: length * 0.16,
+    speed: length * 2,
+    lifetime: 0.5,
+    gravity: -length * 4,
+    colors: [o.color, effects.pale(o.color, 0.4, 1)],
+    flash: false,
+    dust: false
+  });
+  for (const side of [-1, 1])
+    effects.sparks(world, {
+      position: at(side * 0.32, width * 0.5),
+      count: 4,
+      size: width * 0.18,
+      speed: length * 2.5,
+      lifetime: 0.35,
+      gravity: -length * 1.5,
+      direction: [axis[0] * side, axis[1] * side, axis[2] * side],
+      spread: 0.9,
+      colors: [o.color, WHITE],
+      flash: false
+    });
+  catchRing = catchRingMesh();
+  const color = effects.pale(o.color, 0.45, 0.9);
+  const ring = world.spawn({ mesh: catchRing, position: at(0, width * 0.8), rotation: o.rotation, scale: width * 1.8, color, pickable: false });
+  world.animate(ring, { scale: length * 1.1, color: fade(color) }, { duration: 0.32, easing: 'easeOut' }).then(() => {
+    if (world.has(ring)) world.despawn(ring);
+  });
+  return done;
+}
+
+/** Reusable assets; the game loader advances one builder per frame. */
+export function* warmAssets(): Iterable<() => unknown> {
+  yield discMesh;
+  yield stickChipMesh;
+  yield catchRingMesh;
+}

package/src/games/shared/EngineBlocks.ts

@@ -0,0 +1,91 @@
+// The raised block every board game's pieces are made of (Block Blast's blocks, Candy Crush's candies,
+// Block Breaker's bricks, the number tiles): glossy and bevelled, face toward the camera (+z), with a
+// soft shadow on the board down and to the right of it (away from the games' top-left light). The
+// shadow is the block's child, so it moves, scales and pops with it; color changes leave it alone.
+import { type Color, type Entity, extrude, loft, type Model, Path, type Vec3, type World } from '@nayan-ui/engine';
+import { cacheGameAsset, createGameMesh as createShape } from './EngineMeshes';
+
+// One mesh per width : height ratio (rounded), one unit high: mesh ids are app-wide and limited.
+const ASPECT_STEP = 0.25;
+const blocks = new Map<string, Model>();
+/**
+ * A block `aspect` units wide, one high and one deep: straight sides, then a chamfer up to a slightly
+ * smaller face, so its edges catch the light. The chamfer is the same width on every side.
+ */
+function blockMesh(aspect: number, gloss: boolean): Model {
+  return cacheGameAsset('shared/EngineBlocks:blockMesh' + JSON.stringify([aspect, gloss]), () => blockMeshUncached(aspect, gloss));
+}
+
+function blockMeshUncached(aspect: number, gloss: boolean): Model {
+  const key = `${aspect}:${gloss}`;
+  let mesh = blocks.get(key);
+  if (!mesh) {
+    const w = aspect / 2;
+    mesh = createShape(
+      loft(
+        [
+          { z: -0.5, bottom: -0.5, top: 0.5, width: w, square: 7 },
+          { z: 0.2, bottom: -0.5, top: 0.5, width: w, square: 7 },
+          { z: 0.4, bottom: -0.465, top: 0.465, width: w - 0.035, square: 6.5 },
+          { z: 0.5, bottom: -0.39, top: 0.39, width: w - 0.11, square: 5.5 }
+        ],
+        { around: 40, smoothness: 2 }
+      ),
+      { center: false, shine: gloss ? 0.6 : 0 }
+    );
+    blocks.set(key, mesh);
+  }
+  return mesh;
+}
+
+let shadow: Model | null = null;
+/** A soft square one unit across, facing the camera: a block's shadow on the board. */
+const shadowMesh = () => (shadow ??= createShape(extrude(new Path().addRoundedRect(-0.5, -0.5, 1, 1, 0.16), { depth: 0 })));
+/** Down and to the right of its block, just behind it, in the block's own units. */
+const SHADOW_AT: Vec3 = [0.08, -0.11, -0.52];
+const SHADOW_SIZE = 1.04;
+const SHADOW: Color = [0, 0, 0, 0.3];
+
+const aspectOf = (size: Vec3) => Math.max(ASPECT_STEP, Math.round(size[0] / size[1] / ASPECT_STEP) * ASPECT_STEP);
+
+/** The scale that makes a block `size` (width, height, depth): for animating one back to full size (pops, grow-ins). */
+export const raisedBlockScale = (size: Vec3): Vec3 => [size[0] / aspectOf(size), size[1], size[2]];
+
+export type BlockOptions = {
+  /** The block's centre. */
+  position: Vec3;
+  /** Width, height and depth. */
+  size: Vec3;
+  color: Color;
+  parent?: Entity;
+  /** The block's scale as a fraction of `size` (0 to grow it in). Default 1. */
+  grow?: number;
+  /** A glossy finish (else matte). Default true. */
+  gloss?: boolean;
+  /** Its soft shadow on the board. Default true. */
+  shadow?: boolean;
+};
+
+/** A block and its shadow; the block is returned (scale, move, tint and despawn it as one). */
+export function spawnRaisedBlock(world: World, { position, size, color, parent, grow = 1, gloss = true, shadow = true }: BlockOptions): Entity {
+  const aspect = aspectOf(size);
+  const full = raisedBlockScale(size);
+  const block = world.spawn({
+    mesh: blockMesh(aspect, gloss),
+    parent,
+    position,
+    scale: [full[0] * grow, full[1] * grow, full[2] * grow],
+    color,
+    pickable: false
+  });
+  if (shadow)
+    world.spawn({
+      mesh: shadowMesh(),
+      parent: block,
+      position: SHADOW_AT,
+      scale: [aspect * SHADOW_SIZE, SHADOW_SIZE, 1],
+      color: SHADOW,
+      pickable: false
+    });
+  return block;
+}

package/src/games/shared/EngineControlText.ts

@@ -0,0 +1,17 @@
+/** Fit a short control subtitle into its measured inner width without splitting Unicode code points. */
+export function fitControlSubtitle(text: string, maxWidth: number, measure: (value: string) => number): string {
+  const words = text.trim().split(/\s+/).filter(Boolean);
+  const label = words.slice(0, 4).join(' ') + (words.length > 4 ? '…' : '');
+  if (!label || maxWidth <= 0) return '';
+  if (measure(label) <= maxWidth) return label;
+  if (measure('…') > maxWidth) return '';
+  const chars = Array.from(label.replace(/…$/, ''));
+  let lo = 0;
+  let hi = chars.length;
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    if (measure(chars.slice(0, mid).join('').trimEnd() + '…') <= maxWidth) lo = mid;
+    else hi = mid - 1;
+  }
+  return chars.slice(0, lo).join('').trimEnd() + '…';
+}