@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/flappy-bird/FlappyBirdScene.ts

@@ -0,0 +1,630 @@
+// Everything Flappy Bird flies through, in front of its 3D meadow (EngineMeadow). Positions come in
+// screen points (y down) and land on the play plane ahead of the camera, where the original game drew them;
+// sizes are scaled to metres there. The bird is a chubby 3D bird (egg body, belly, cheek, eye, beak,
+// crest, tail, feet) with two flapping wings, a blinking eyelid and a squash on every flap; pipes are glossy green tubes with lipped caps; the walls are
+// laid brick by brick over mortar. Each is a root turned to face the camera, so its parts are placed in
+// screen-like local axes. Every part is a shared mesh: mesh ids are app-wide and limited.
+import {
+  type Color,
+  effects,
+  type Entity,
+  extrude,
+  type Geometry,
+  lathe,
+  merge,
+  type Model,
+  type MutableQuat,
+  Path,
+  quat,
+  recolor,
+  shapeGeometry,
+  type TransformBatch,
+  tube,
+  type Vec3,
+  type World
+} from '@nayan-ui/engine';
+import { at, facing, pointSize, type View3D } from '../shared/EngineMeadow';
+import { cacheGameAsset, createGameMesh as createShape } from '../shared/EngineMeshes';
+import { toColor } from '../shared/EngineUtils';
+import { BIRD_SIZE, BRICK_HEIGHT, BRICK_WIDTH, type Layout, PIPE_WIDTH } from './FlappyBirdConstants';
+
+// ── Meshes ────────────────────────────────────────────────────────────
+
+const meshes = new Map<string, Model>();
+const cached = (key: string, build: () => Model) => {
+  let m = meshes.get(key);
+  if (!m) {
+    m = cacheGameAsset('flappy-bird/FlappyBirdScene:' + key, build);
+    meshes.set(key, m);
+  }
+  return m;
+};
+type RGB = [number, number, number];
+const rgb = (css: string): RGB => {
+  const [r, g, b] = toColor(css);
+  return [r, g, b];
+};
+const mix = (a: RGB, b: RGB, t: number): RGB => [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t];
+const sphere = () => shapeGeometry('sphere');
+/** A cone along +x (the beak), from a lathe around y turned a quarter. */
+const beakPart = (length: number, radius: number, color: RGB, position: Vec3, tilt: number) => ({
+  geometry: lathe(
+    [
+      [radius, 0],
+      [radius * 0.6, length * 0.5],
+      [0.001, length]
+    ],
+    { segments: 12, color }
+  ),
+  position,
+  rotation: quat.multiply(quat.z(tilt), quat.z(-Math.PI / 2))
+});
+
+const clamp01 = (x: number) => Math.max(0, Math.min(1, x));
+const smoothstep = (x: number) => {
+  const t = clamp01(x);
+  return t * t * (3 - 2 * t);
+};
+const BODY_TOP = rgb('#FFE14D');
+const BODY_BOTTOM = rgb('#FFAA1F');
+const BELLY = rgb('#FFF4CC');
+const BLUSH = rgb('#FF8C9A');
+const FEATHER = rgb('#F08A12');
+
+/** A tapered feather along `points`, flattened into a blade. */
+const feather = (points: Vec3[], radius: number, color: RGB) =>
+  tube(points, {
+    radius: (t) => radius * Math.max(0.08, 1 - t * 0.85),
+    shape: (a) => 0.35 + 0.65 * Math.abs(Math.cos(a * Math.PI * 2)),
+    sides: 8,
+    smoothness: 5,
+    color: [...color, 1] as Color
+  });
+
+/**
+ * The bird's body (without its wings, eyelid or squash), one unit long, facing +x (right), its front
+ * toward +z (the camera): a chubby egg, yellow fading to orange below, a cream belly and pink cheek,
+ * a big eye, a two-part beak, curling crest feathers, a fanned tail and tucked feet.
+ */
+const birdMesh = () =>
+  cached('fb-bird', () => {
+    // The egg: round at the head (+x), a little narrower at the tail
+    const profile: [number, number][] = Array.from({ length: 17 }, (_, i) => {
+      const t = i / 16;
+      return [Math.max(0.001, 0.47 * Math.sin(Math.PI * t) ** 0.75 * (1 - 0.16 * t)), 0.5 - t];
+    });
+    const egg = merge([{ geometry: lathe(profile, { segments: 28 }), rotation: quat.z(-Math.PI / 2), scale: [1, 0.92, 0.86] }]);
+    const body = recolor(egg, ({ position: [x, y, z] }) => {
+      let c = mix(BODY_BOTTOM, BODY_TOP, clamp01(0.5 + y * 1.3 + x * 0.25));
+      // Cream belly on the front and underside
+      c = mix(c, BELLY, smoothstep((0.06 - y) * 4) * smoothstep(z * 3 + 0.3) * smoothstep((x + 0.32) * 3) * 0.95);
+      // A pink cheek under the eye
+      c = mix(c, BLUSH, smoothstep(1 - Math.hypot(x - 0.2, y + 0.06, z - 0.33) / 0.11) * 0.8);
+      return [...c, 1] as Color;
+    });
+    return createShape(
+      merge([
+        { geometry: body },
+        // Eye: white, a black pupil looking ahead, a glint
+        { geometry: sphere(), position: [0.22, 0.15, 0.26], scale: 0.32, color: [1, 1, 1] },
+        { geometry: sphere(), position: [0.3, 0.16, 0.38], scale: 0.15, color: rgb('#151515') },
+        { geometry: sphere(), position: [0.33, 0.2, 0.445], scale: 0.05, color: [1, 1, 1] },
+        // Beak: upper and lower halves
+        beakPart(0.3, 0.1, rgb('#FF7B3A'), [0.4, 0.0, 0.06], 0.12),
+        beakPart(0.24, 0.08, rgb('#D9531A'), [0.39, -0.07, 0.06], -0.2),
+        // Crest: three curling feathers
+        {
+          geometry: feather(
+            [
+              [0.02, 0.36, 0],
+              [0.0, 0.52, 0],
+              [-0.1, 0.6, 0]
+            ],
+            0.07,
+            rgb('#FF9500')
+          )
+        },
+        {
+          geometry: feather(
+            [
+              [0.1, 0.36, 0.02],
+              [0.12, 0.5, 0.02],
+              [0.06, 0.6, 0.02]
+            ],
+            0.06,
+            rgb('#FFB300')
+          )
+        },
+        {
+          geometry: feather(
+            [
+              [-0.06, 0.34, -0.02],
+              [-0.14, 0.46, -0.02],
+              [-0.24, 0.5, -0.02]
+            ],
+            0.055,
+            FEATHER
+          )
+        },
+        // Tail: three broad, round-tipped feathers fanned back
+        ...[0.2, 0.02, -0.16].map((tilt, i) => ({
+          geometry: tube(
+            [
+              [-0.34, 0.02, 0],
+              [-0.52, 0.04 + tilt * 0.6, 0],
+              [-0.68, 0.06 + tilt, 0]
+            ],
+            {
+              radius: (t) => 0.13 * (0.55 + 0.45 * Math.sin(Math.PI * (0.25 + t * 0.6))),
+              shape: (a) => 0.45 + 0.55 * Math.abs(Math.cos(a * Math.PI * 2)),
+              sides: 10,
+              smoothness: 5,
+              color: [...mix(FEATHER, rgb('#C2600A'), i * 0.35), 1] as Color
+            }
+          )
+        })),
+        // Feet tucked under
+        ...[0.12, -0.12].map((z) => ({
+          geometry: feather(
+            [
+              [0.02, -0.36, z],
+              [-0.08, -0.46, z],
+              [-0.2, -0.48, z]
+            ],
+            0.035,
+            rgb('#FF7B3A')
+          )
+        }))
+      ]),
+      { center: false, shine: 0.35 }
+    );
+  });
+
+/** A wing, pivoting at its root (the origin) and reaching back (-x): a rounded feather paddle with a scalloped trailing edge. */
+const wingMesh = (far: boolean) =>
+  cached(`fb-wing:${far}`, () => {
+    // Points in world-up y (the path's y runs down)
+    const pts: [number, number][] = [
+      [0.06, 0.06],
+      [-0.12, 0.14],
+      [-0.34, 0.12],
+      [-0.56, 0.02],
+      [-0.5, -0.04],
+      [-0.55, -0.09],
+      [-0.44, -0.11],
+      [-0.47, -0.17],
+      [-0.34, -0.17],
+      [-0.12, -0.12],
+      [0.06, -0.05]
+    ];
+    const path = new Path().moveTo(pts[0]![0], -pts[0]![1]);
+    for (const [x, y] of pts.slice(1)) path.lineTo(x, -y);
+    path.close();
+    const [root, tip] = far ? [rgb('#B86A08'), rgb('#D9901F')] : [rgb('#F59E0B'), rgb('#FFD35C')];
+    return createShape(
+      recolor(extrude(path, { depth: 0.07 }), ({ position: [x] }) => [...mix(root, tip, clamp01(-x / 0.55)), 1] as Color),
+      { center: false, shine: 0.25 }
+    );
+  });
+
+/** The eyelid: a ball in the body's color over the eye, shown only while blinking. */
+const lidMesh = () => cached('fb-lid', () => createShape(merge([{ geometry: sphere(), color: BODY_TOP }]), { shine: 0.35 }));
+
+/** A unit pipe body: an open tube one unit across and tall, centred, with vertical shading baked in. */
+const pipeMesh = () =>
+  cached('fb-pipe', () =>
+    createShape(
+      lathe(
+        [
+          [0.5, -0.5],
+          [0.5, 0.5]
+        ],
+        { segments: 24, color: rgb('#4CA840') }
+      ),
+      { center: false, shine: 0.55 }
+    )
+  );
+/** The cap: a wider, short lipped ring, closed at the end facing the gap (+y), one unit tall, centred. */
+const capMesh = () =>
+  cached('fb-cap', () =>
+    createShape(
+      merge([
+        {
+          geometry: lathe(
+            [
+              [0.001, 0.5],
+              [0.5, 0.5],
+              [0.52, 0.42],
+              [0.52, -0.42],
+              [0.5, -0.5]
+            ],
+            { segments: 24, color: rgb('#3A8A2A') }
+          )
+        },
+        // A dark opening, so the pipe reads as hollow
+        { geometry: sphere(), position: [0, 0.5, 0], scale: [0.78, 0.02, 0.78], color: rgb('#123d10') }
+      ]),
+      { center: false, shine: 0.6 }
+    )
+  );
+
+/** Bricks along a row repeat their shades every this many, so the scrolling walls can wrap seamlessly. */
+const SHADE_PERIOD = 12;
+/** A brick's shade, from its row and its column (wrapped to the period): the same brick always looks the same. */
+function brickShade(row: number, col: number): RGB {
+  const c = ((col % SHADE_PERIOD) + SHADE_PERIOD) % SHADE_PERIOD;
+  const n = Math.sin(row * 127.1 + c * 311.7) * 43758.5453;
+  const t = n - Math.floor(n);
+  const base = rgb('#9E5428');
+  return t < 0.5 ? mix(rgb('#6E3412'), base, t * 2) : mix(base, rgb('#B8693A'), (t - 0.5) * 2);
+}
+
+/**
+ * A wall block in its own frame: x across (centred), y running into the wall away from the play area,
+ * z toward the camera (the back face at 0, the front at `thickness`). `w` and `h` are screen points at
+ * `k` metres per point. A stone coping runs along the edge facing the play area; above it, bricks in
+ * running bond, each a slightly different shade, face the front over a mortar core.
+ */
+function wallGeometry(w: number, h: number, k: number, thickness: number): Geometry {
+  const bw = BRICK_WIDTH * k;
+  const bh = BRICK_HEIGHT * k;
+  const width = w * k;
+  const height = h * k;
+  const coping = COPING * k;
+  const relief = bh * 0.35; // how far a brick stands proud of the mortar
+  const mortar = 0.12 * bh;
+  const parts: { geometry: Geometry; position: Vec3; scale: Vec3; color: RGB }[] = [];
+  const box = (x0: number, x1: number, y0: number, y1: number, z0: number, z1: number, color: RGB) =>
+    parts.push({
+      geometry: shapeGeometry('cube'),
+      position: [(x0 + x1) / 2, (y0 + y1) / 2, (z0 + z1) / 2],
+      scale: [x1 - x0, y1 - y0, z1 - z0],
+      color
+    });
+  // The mortar core, the full depth of the wall (it hides the pipes' ends inside it)
+  box(-width / 2, width / 2, coping, height, 0, thickness, rgb('#3a1d0c'));
+  // The coping: a pale stone ledge, overhanging the face a little
+  box(-width / 2, width / 2, 0, coping, -0.01, thickness + relief + 0.025, rgb('#c8b896'));
+  box(-width / 2, width / 2, coping * 0.78, coping, thickness + relief + 0.005, thickness + relief + 0.03, rgb('#a9987a'));
+  const rows = Math.ceil((height - coping) / bh);
+  for (let r = 0; r < rows; r++) {
+    const y0 = coping + r * bh;
+    const y1 = Math.min(height, y0 + bh);
+    const shift = r % 2 ? bw / 2 : 0;
+    for (let c = 0, x = -width / 2 - shift; x < width / 2; c++, x += bw) {
+      // Clip the end bricks to the wall's edges (they're off screen)
+      const x0 = Math.max(x, -width / 2);
+      const x1 = Math.min(x + bw, width / 2);
+      if (x1 - x0 <= mortar || y1 - y0 <= mortar) continue;
+      box(x0 + mortar / 2, x1 - mortar / 2, y0 + mortar / 2, y1 - mortar / 2, thickness - 0.01, thickness + relief, brickShade(r, c));
+    }
+  }
+  return merge(parts);
+}
+
+// ── Placement ─────────────────────────────────────────────────────────
+
+/** Local offset (metres) of screen point (x, y) from the root's screen point, in the root's facing axes. */
+const local = (k: number, dx: number, dy: number, dz = 0): Vec3 => [dx * k, -dy * k, dz];
+
+// ── Walls ─────────────────────────────────────────────────────────────
+
+const CAP_HEIGHT = 26;
+const CAP_OVER = 5;
+const COPING = 12; // points
+/** Points the walls reach past the screen's edge (the perspective shows a little more of a near face). */
+const WALL_MARGIN = 160;
+/** Points the pipes run on into the walls, so where they meet is inside the brickwork. */
+const PIPE_INTO_WALL = 220;
+
+/** The bottom wall's depth: its back face just behind the pipes, its front just ahead, so a pipe passes through it. */
+const wallDepth = (v: View3D) => {
+  const pipeRadius = ((PIPE_WIDTH + CAP_OVER * 2 * (PIPE_WIDTH / 60)) / 2) * pointSize(v);
+  return { back: v.playDepth + pipeRadius + 0.04, thickness: pipeRadius * 2 + 0.08, front: v.playDepth - pipeRadius - 0.04 };
+};
+
+/**
+ * A prism: the convex outline `profile` ((z, y) points, z toward the camera) swept along x from `x0` to
+ * `x1`, with flat faces turned outward. For shapes the cubes can't make: the top wall's sloped underside.
+ */
+function prism(profile: [number, number][], x0: number, x1: number, color: RGB): Geometry {
+  const vertices: number[] = [];
+  const indices: number[] = [];
+  const cz = profile.reduce((a, p) => a + p[0], 0) / profile.length;
+  const cy = profile.reduce((a, p) => a + p[1], 0) / profile.length;
+  const centre: Vec3 = [(x0 + x1) / 2, cy, cz];
+  const face = (pts: Vec3[]) => {
+    const [a, b, c] = pts as [Vec3, Vec3, Vec3];
+    const u: Vec3 = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
+    const w: Vec3 = [c[0] - a[0], c[1] - a[1], c[2] - a[2]];
+    let n: Vec3 = [u[1] * w[2] - u[2] * w[1], u[2] * w[0] - u[0] * w[2], u[0] * w[1] - u[1] * w[0]];
+    const mid = pts.reduce<Vec3>((m, p) => [m[0] + p[0] / pts.length, m[1] + p[1] / pts.length, m[2] + p[2] / pts.length], [0, 0, 0]);
+    if (n[0] * (mid[0] - centre[0]) + n[1] * (mid[1] - centre[1]) + n[2] * (mid[2] - centre[2]) < 0) {
+      pts = [...pts].reverse();
+      n = [-n[0], -n[1], -n[2]];
+    }
+    const len = Math.hypot(n[0], n[1], n[2]) || 1;
+    const first = vertices.length / 11;
+    for (const p of pts) vertices.push(p[0], p[1], p[2], n[0] / len, n[1] / len, n[2] / len, color[0], color[1], color[2], 0, 0);
+    for (let i = 1; i + 1 < pts.length; i++) indices.push(first, first + i, first + i + 1);
+  };
+  face(profile.map(([z, y]) => [x0, y, z] as Vec3));
+  face(profile.map(([z, y]) => [x1, y, z] as Vec3));
+  profile.forEach(([z, y], i) => {
+    const [z2, y2] = profile[(i + 1) % profile.length]!;
+    face([
+      [x0, y, z],
+      [x1, y, z],
+      [x1, y2, z2],
+      [x0, y2, z2]
+    ]);
+  });
+  return { vertices: new Float32Array(vertices), indices: new Uint32Array(indices) };
+}
+
+/**
+ * The top wall, in its own frame (x across, y up, z toward the camera, the origin on its front edge).
+ * The camera looks up at it, so a flat underside would show as a dark band below the bricks. Instead
+ * the underside rises toward the back along the camera's line of sight through the edge (`slope`
+ * metres up per metre back), so it's never seen: the stone coping's front comes right down to the line
+ * and the pipes run straight up into it, as they rise out of the bottom wall's ledge.
+ */
+function topWallGeometry(w: number, h: number, k: number, slope: number): Geometry {
+  const bw = BRICK_WIDTH * k;
+  const bh = BRICK_HEIGHT * k;
+  const width = w * k;
+  const height = h * k;
+  const coping = COPING * k;
+  const relief = bh * 0.35;
+  const lip = relief + 0.025; // the coping stands this far proud of the core, the bricks a little less
+  const depth = 0.25;
+  const mortar = 0.12 * bh;
+  const s = slope * 1.05; // a hair steeper than the sight line, so the underside is always hidden
+  const x0 = -width / 2;
+  const x1 = width / 2;
+  const parts: { geometry: Geometry; position?: Vec3; scale?: Vec3; color?: RGB }[] = [
+    // The mortar core behind the bricks
+    {
+      geometry: prism(
+        [
+          [-lip, s * lip],
+          [-lip, height],
+          [-depth, height],
+          [-depth, s * depth]
+        ],
+        x0,
+        x1,
+        rgb('#3a1d0c')
+      )
+    },
+    // The stone coping along the edge, with a darker drip line on its face
+    {
+      geometry: prism(
+        [
+          [0, 0],
+          [0, coping],
+          [-lip, coping],
+          [-lip, s * lip]
+        ],
+        x0,
+        x1,
+        rgb('#c8b896')
+      )
+    },
+    { geometry: shapeGeometry('cube'), position: [0, coping * 0.11, 0.004], scale: [width, coping * 0.22, 0.008], color: rgb('#a9987a') }
+  ];
+  const rows = Math.ceil((height - coping) / bh);
+  for (let r = 0; r < rows; r++) {
+    const y0 = coping + r * bh;
+    const y1 = Math.min(height, y0 + bh);
+    const shift = r % 2 ? bw / 2 : 0;
+    for (let c = 0, x = x0 - shift; x < x1; c++, x += bw) {
+      const bx0 = Math.max(x, x0);
+      const bx1 = Math.min(x + bw, x1);
+      if (bx1 - bx0 <= mortar || y1 - y0 <= mortar) continue;
+      parts.push({
+        geometry: shapeGeometry('cube'),
+        position: [(bx0 + bx1) / 2, (y0 + y1) / 2, -lip + relief / 2],
+        scale: [bx1 - bx0 - mortar, y1 - y0 - mortar, relief + 0.01],
+        color: brickShade(r + 7, c)
+      });
+    }
+  }
+  return merge(parts);
+}
+
+export type Walls = { top: Entity; bottom: Entity };
+
+export function spawnWalls(world: World, v: View3D, l: Layout): Walls {
+  const { back, front, thickness } = wallDepth(v);
+  const kb = pointSize(v, back);
+  const kf = pointSize(v, front);
+  // How steeply the sight line through the top wall's edge climbs, per metre away from the camera
+  const slope = ((l.height / 2 - l.topWall) / (l.height / 2)) * v.tanHalf;
+  // Wide enough to cover the screen at any point of a wrap: the screen, one shade period, and a margin
+  const width = l.width + SHADE_PERIOD * BRICK_WIDTH + BRICK_WIDTH * 4;
+  const top = cached(`fb-top-wall:${Math.round(l.width)}x${Math.round(l.topWall)}:${kf.toFixed(6)}:${slope.toFixed(5)}`, () =>
+    createShape(topWallGeometry(width, l.topWall + WALL_MARGIN, kf, slope), { center: false, shine: 0.05 })
+  );
+  const bottomHeight = l.height - l.bottomWallTop;
+  const bottom = cached(`fb-wall:${Math.round(l.width)}x${Math.round(bottomHeight)}:${kb.toFixed(6)}:${thickness.toFixed(4)}`, () =>
+    createShape(wallGeometry(width, bottomHeight + WALL_MARGIN, kb, thickness), { center: false, shine: 0.05 })
+  );
+  const walls = {
+    top: world.spawn({ mesh: top, color: [1, 1, 1, 1], pickable: false }),
+    // The bottom wall is the block turned over: it runs down from its line, its ledge facing up
+    bottom: world.spawn({ mesh: bottom, color: [1, 1, 1, 1], pickable: false })
+  };
+  placeWalls(world, v, l, walls, 0);
+  return walls;
+}
+
+/**
+ * Scrolls the walls with the pipes. They move at the pipes' speed in the world (the pipes pass through
+ * them, so they stay put against the bricks), which on screen is a touch slower for the deeper bottom
+ * wall: real parallax. Each wraps by a whole shade period, where its bricks look exactly the same.
+ */
+export function placeWalls(world: World, v: View3D, l: Layout, walls: Walls, scroll: number) {
+  const { back, front } = wallDepth(v);
+  const travelled = scroll * pointSize(v); // metres the pipes have moved
+  const place = (wall: Entity, line: number, depth: number, turn: number) => {
+    const period = SHADE_PERIOD * BRICK_WIDTH * pointSize(v, depth);
+    const centre = at(v, l.width / 2 + (SHADE_PERIOD * BRICK_WIDTH) / 2, line, depth);
+    world.set(wall, { position: [centre[0] - (travelled % period), centre[1], centre[2]], rotation: facing(v, turn) });
+  };
+  // The top wall's front edge, the bottom wall's back edge, sit on their collision lines
+  place(walls.top, l.topWall, front, 0);
+  place(walls.bottom, l.bottomWallTop, back, Math.PI);
+}
+
+// ── Pipes ─────────────────────────────────────────────────────────────
+
+/** A pair of pipes: the top one comes out of the top wall down to the gap, the bottom one up out of the bottom wall. */
+export function spawnPipe(world: World, v: View3D, l: Layout, x: number, gapTop: number, gapBottom: number): Entity {
+  const k = pointSize(v);
+  const s = PIPE_WIDTH / 60;
+  const capH = CAP_HEIGHT * s;
+  const capW = PIPE_WIDTH + CAP_OVER * 2 * s;
+  const cx = x + PIPE_WIDTH / 2;
+  const root = world.spawn({ mesh: 'none', position: at(v, cx, 0), rotation: facing(v), pickable: false });
+  const add = (mesh: Model, y: number, height: number, width: number, flip = false) =>
+    world.spawn({
+      mesh,
+      parent: root,
+      position: local(k, 0, y),
+      scale: [width * k, height * k, width * k],
+      ...(flip ? { rotation: quat.z(Math.PI) } : {}),
+      color: [1, 1, 1, 1],
+      pickable: false
+    });
+  const topEnd = Math.max(l.topWall, Math.min(gapTop, l.bottomWallTop));
+  const bottomStart = Math.max(l.topWall, Math.min(gapBottom, l.bottomWallTop));
+  const topStart = l.topWall - PIPE_INTO_WALL;
+  const bottomEnd = l.bottomWallTop + PIPE_INTO_WALL;
+  if (topEnd - l.topWall > 0.5) {
+    add(pipeMesh(), (topStart + topEnd) / 2, topEnd - topStart, PIPE_WIDTH);
+    add(capMesh(), topEnd - capH / 2, capH, capW, true); // its open end faces down into the gap
+  }
+  if (l.bottomWallTop - bottomStart > 0.5) {
+    add(pipeMesh(), (bottomStart + bottomEnd) / 2, bottomEnd - bottomStart, PIPE_WIDTH);
+    add(capMesh(), bottomStart + capH / 2, capH, capW);
+  }
+  return root;
+}
+
+export function placePipe(world: World, v: View3D, root: Entity, x: number, updates?: TransformBatch) {
+  const position = at(v, x + PIPE_WIDTH / 2, 0);
+  if (updates) updates.position(root, position[0], position[1], position[2]);
+  else world.set(root, { position });
+}
+
+// ── The bird ──────────────────────────────────────────────────────────
+
+export type BirdView = { root: Entity; body: Entity; wing: Entity; farWing: Entity; lid: Entity; size: number };
+
+/** Where the eye sits on the body, and its size (body units). */
+const EYE: Vec3 = [0.22, 0.15, 0.27];
+const EYE_SIZE = 0.34;
+
+/** The bird, its body centred on screen point (x, y). In the ready state it hovers, bobbing gently. */
+export function spawnBird(world: World, v: View3D, x: number, y: number): BirdView {
+  const size = BIRD_SIZE * pointSize(v);
+  const root = world.spawn({ mesh: 'none', position: at(v, x, y), rotation: facing(v), pickable: false });
+  // The far wing behind the body (it peeks out on the upstroke), the near one in front
+  const farWing = world.spawn({
+    mesh: wingMesh(true),
+    parent: root,
+    position: [-size * 0.04, size * 0.04, -size * 0.3],
+    scale: size,
+    color: [1, 1, 1, 1],
+    pickable: false
+  });
+  const body = world.spawn({ mesh: birdMesh(), parent: root, scale: size, color: [1, 1, 1, 1], pickable: false });
+  const lid = world.spawn({
+    mesh: lidMesh(),
+    parent: root,
+    position: [EYE[0] * size, EYE[1] * size, EYE[2] * size],
+    scale: 0,
+    color: [1, 1, 1, 1],
+    pickable: false
+  });
+  const wing = world.spawn({
+    mesh: wingMesh(false),
+    parent: root,
+    position: [-size * 0.02, -size * 0.04, size * 0.38],
+    scale: size,
+    color: [1, 1, 1, 1],
+    pickable: false
+  });
+  return { root, body, wing, farWing, lid, size };
+}
+
+const NEAR_WING_TILT = quat.x(-0.25);
+const FAR_WING_TILT = quat.x(0.25);
+const wingTurn: MutableQuat = [0, 0, 0, 1];
+
+/** Moves the bird: leaning by `tilt`, the wings lifted by `lift` (radians: up positive), the far one a beat behind. */
+export function placeBird(world: World, v: View3D, b: BirdView, x: number, y: number, tilt: number, lift: number, farLift = lift) {
+  world.set(b.root, { position: at(v, x, y), rotation: facing(v, -tilt) });
+  world.set(b.wing, { rotation: quat.multiply(NEAR_WING_TILT, quat.z(-lift, wingTurn), wingTurn) });
+  world.set(b.farWing, { rotation: quat.multiply(FAR_WING_TILT, quat.z(-farLift, wingTurn), wingTurn) });
+}
+
+/** The squash and stretch of a flap: the body stretches up as it pushes off, then settles. */
+export function flapPop(world: World, b: BirdView) {
+  const s = b.size;
+  world.stopAnimation(b.body);
+  world.animate(b.body, [{ scale: [s * 0.86, s * 1.16, s], at: 0.3 }, { scale: [s * 1.05, s * 0.96, s], at: 0.65 }, { scale: s }], {
+    duration: 0.26,
+    easing: 'easeOut'
+  });
+}
+
+/** A blink: the lid closes over the eye and opens again. */
+export function blink(world: World, b: BirdView) {
+  const s = b.size * EYE_SIZE;
+  world.animate(b.lid, [{ scale: [s, s, s], at: 0.4 }, { scale: [s, s, s], at: 0.6 }, { scale: 0 }], { duration: 0.16, easing: 'linear' });
+}
+
+/** Knocked silly by a crash: a shake, eyes half shut, wings drooping. */
+export function dazeBird(world: World, b: BirdView) {
+  const s = b.size * EYE_SIZE;
+  world.stopAnimation(b.lid);
+  world.set(b.lid, { scale: [s, s * 0.55, s], position: [EYE[0] * b.size, (EYE[1] + 0.06) * b.size, EYE[2] * b.size] });
+  world.animate(b.root, { shake: b.size * 0.12 }, { duration: 0.35 });
+}
+
+/** Back to normal after a crash (a new run). */
+export function wakeBird(world: World, b: BirdView) {
+  world.stopAnimation(b.lid);
+  world.set(b.lid, { scale: 0, position: [EYE[0] * b.size, EYE[1] * b.size, EYE[2] * b.size] });
+}
+
+/** A gentle hover while waiting to start (none while flying). */
+export function hoverBird(world: World, b: BirdView, on: boolean, v: View3D) {
+  const amplitude = BIRD_SIZE * pointSize(v) * 0.12;
+  world.set(b.root, { bob: on ? { amplitude: [0, amplitude, 0], speed: 3.2 } : null });
+}
+
+// ── The crash ─────────────────────────────────────────────────────────
+
+const FEATHERS: Color[] = ['#FFD700', '#FF8C00', '#FFE850', '#FFFFFF', '#A0522D'].map((c) => toColor(c));
+
+/** Feathers fly and a puff of dust where the bird hit. */
+export function crashBurst(world: World, v: View3D, x: number, y: number) {
+  const k = pointSize(v);
+  const size = BIRD_SIZE * k;
+  const where = at(v, x, y, v.playDepth - size * 0.6);
+  effects.shatter(world, {
+    position: where,
+    count: 16,
+    mesh: 'sphere',
+    size: size * 0.12,
+    speed: size * 7,
+    lifetime: 0.7,
+    gravity: -size * 18,
+    colors: FEATHERS,
+    dust: false
+  });
+  effects.dust(world, { position: where, count: 5, size: size * 0.9, speed: size * 2, lifetime: 0.5, color: [1, 1, 1, 0.75] });
+}