@nayan-ui/games 1.19.0 → 1.20.0

package/src/games/shared/EngineMeadow.ts

@@ -0,0 +1,725 @@
+// A sunlit 3D meadow for the Nayan engine games, seen through a perspective camera at eye height and
+// built to scale in metres (the engine's depth range is 500 and its shadows cover tens of metres).
+// The game itself plays on a plane a few metres in front of the camera, mapped so one screen point
+// there is exactly where a 2D game drew it: gameplay stays in screen points while everything around it
+// is real 3D. Each game frames it with a `Rig` (eye height, where the horizon sits, how far the play
+// plane is) and picks what's in it with `MeadowOptions`.
+//
+// The scene, back to front: a sky dome (its color gradient by elevation), the sun with a soft corona
+// (the moon and stars at night), drifting clouds, hot-air balloons far off, three hill ranges fading
+// into the haze, the grass meadow out to the horizon, a treeline, two big framing trees, bushes and
+// rocks, grass tufts and flowers. The sun casts shadows. Fog is off: the haze is painted into the hills
+// and ground, which keeps the sky its own color.
+import {
+  type Camera,
+  type Color,
+  type Entity,
+  type Geometry,
+  lathe,
+  type Light,
+  merge,
+  type Model,
+  type Quat,
+  quat,
+  recolor,
+  shapeGeometry,
+  tube,
+  type Vec3,
+  type World
+} from '@nayan-ui/engine';
+import { type GameTheme, NIGHT_SCENE } from '../../services/ThemeService';
+import { toColor } from '../shared/EngineUtils';
+import { cacheGameAsset, createGameMesh as createShape } from './EngineMeshes';
+
+// ── The camera rig ────────────────────────────────────────────────────
+
+const FOV = 0.9; // vertical, radians
+
+/** How a game frames the meadow. */
+export type Rig = {
+  /** Metres from the ground to the eye. Default 1.6. */
+  eyeHeight?: number;
+  /** How far down the screen the horizon sits, 0..1. Default 0.62. */
+  horizon?: number;
+  /** Metres from the eye to the play plane; keep it nearer than the ground at the screen's bottom edge. Default 3.6. */
+  playDepth?: number;
+};
+
+export type View3D = {
+  width: number;
+  height: number;
+  eye: Vec3;
+  /** Camera axes: looking along `forward`, `up` and `right` span the screen. */
+  forward: Vec3;
+  up: Vec3;
+  /** tan(fov / 2). */
+  tanHalf: number;
+  /** The camera's pitch up, radians. */
+  pitch: number;
+  horizon: number;
+  playDepth: number;
+};
+
+export function makeView(width: number, height: number, rig: Rig = {}): View3D {
+  const horizon = rig.horizon ?? 0.62;
+  const tanHalf = Math.tan(FOV / 2);
+  // A level horizon below centre: tilt up until the horizon's ray lands that far down the screen
+  const pitch = Math.atan((horizon - 0.5) * 2 * tanHalf);
+  return {
+    width,
+    height,
+    eye: [0, rig.eyeHeight ?? 1.6, 0],
+    forward: [0, Math.sin(pitch), -Math.cos(pitch)],
+    up: [0, Math.cos(pitch), Math.sin(pitch)],
+    tanHalf,
+    pitch,
+    horizon,
+    playDepth: rig.playDepth ?? 3.6
+  };
+}
+
+export function cameraFor(v: View3D): Camera {
+  const [x, y, z] = add(v.eye, scale(v.forward, v.playDepth));
+  return { eye: [v.eye[0], v.eye[1], v.eye[2]], target: [x, y, z], fov: FOV };
+}
+
+/** Metres per screen point on a plane `depth` metres ahead. */
+export const pointSize = (v: View3D, depth = v.playDepth) => (2 * depth * v.tanHalf) / v.height;
+
+/** Where screen point (x, y) lands on the plane `depth` metres ahead. */
+export function at(v: View3D, x: number, y: number, depth = v.playDepth): Vec3 {
+  const k = pointSize(v, depth);
+  const centre = add(v.eye, scale(v.forward, depth));
+  return [centre[0] + (x - v.width / 2) * k, centre[1] + (v.height / 2 - y) * k * v.up[1], centre[2] + (v.height / 2 - y) * k * v.up[2]];
+}
+
+/** A screen-plane vector (points per second, y down) in world metres per second at the play plane. */
+export function planeVector(v: View3D, dx: number, dy: number): Vec3 {
+  const k = pointSize(v);
+  return [dx * k, -dy * k * v.up[1], -dy * k * v.up[2]];
+}
+
+/** Turns something drawn facing +z to face the camera, then by `angle` in the screen's plane. */
+export function facing(v: View3D, angle = 0): Quat {
+  return quat.multiply(quat.x(v.pitch), quat.z(angle));
+}
+
+/** The direction from the eye through screen point (x, y). */
+export function rayThrough(v: View3D, x: number, y: number): Vec3 {
+  const sx = ((x - v.width / 2) / (v.height / 2)) * v.tanHalf;
+  const sy = ((v.height / 2 - y) / (v.height / 2)) * v.tanHalf;
+  return normalize(add(add(v.forward, [sx, 0, 0]), scale(v.up, sy)));
+}
+
+// ── Vectors ───────────────────────────────────────────────────────────
+
+export const add = (a: Vec3, b: Vec3): Vec3 => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+export const scale = (a: Vec3, k: number): Vec3 => [a[0] * k, a[1] * k, a[2] * k];
+const normalize = (a: Vec3): Vec3 => scale(a, 1 / (Math.hypot(a[0], a[1], a[2]) || 1));
+
+// ── Light and palette (day for classic and light, night for dark) ────
+
+const night = (theme: GameTheme) => theme.mode === 'dark';
+
+const DAY_LIGHT: Light = { direction: [0.55, 0.8, 0.45], ambient: 0.42, color: [1.08, 1.02, 0.94], shadows: true, shadowExtent: 22 };
+const NIGHT_LIGHT: Light = { direction: [-0.45, 0.75, 0.4], ambient: 0.64, color: [0.92, 0.95, 1.06], shadows: true, shadowExtent: 22 };
+export const lightFor = (theme: GameTheme): Light => (night(theme) ? NIGHT_LIGHT : DAY_LIGHT);
+
+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 SKY_DAY = { zenith: rgb('#2a73c0'), mid: rgb('#6aaee0'), horizon: rgb('#d8edf6') };
+const SKY_NIGHT = { zenith: rgb('#07061a'), mid: rgb(NIGHT_SCENE.SKY[1]), horizon: rgb(NIGHT_SCENE.SKY[3]) };
+/** What far-off things fade toward. */
+export const HAZE = rgb('#c6e0ec');
+/** Scenery is painted in day colors; at night it is dimmed and cooled on top of the moonlight. */
+const NIGHT_TINT: Color = [0.72, 0.76, 0.92, 1];
+const DAY_TINT: Color = [1, 1, 1, 1];
+/** The color multiplier scenery takes for a theme (night dims and cools it), for games adding their own. */
+export const sceneryTint = (theme: GameTheme): Color => (night(theme) ? NIGHT_TINT : DAY_TINT);
+
+// ── Deterministic noise (the same meadow every visit) ────────────────
+
+const hash = (x: number, y: number) => {
+  const s = Math.sin(x * 127.1 + y * 311.7) * 43758.5453;
+  return s - Math.floor(s);
+};
+const smooth = (t: number) => t * t * (3 - 2 * t);
+/** Value noise, 0..1. */
+export function noise(x: number, y: number) {
+  const ix = Math.floor(x);
+  const iy = Math.floor(y);
+  const fx = smooth(x - ix);
+  const fy = smooth(y - iy);
+  const a = hash(ix, iy);
+  const b = hash(ix + 1, iy);
+  const c = hash(ix, iy + 1);
+  const d = hash(ix + 1, iy + 1);
+  return a + (b - a) * fx + (c - a) * fy + (a - b - c + d) * fx * fy;
+}
+export const fbm = (x: number, y: number) => noise(x, y) * 0.55 + noise(x * 2.1, y * 2.1) * 0.3 + noise(x * 4.3, y * 4.3) * 0.15;
+export function random(seed: number) {
+  let s = seed >>> 0;
+  return () => {
+    s = (s + 0x6d2b79f5) >>> 0;
+    let t = s;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+// ── Geometry helpers ──────────────────────────────────────────────────
+
+class Mesh {
+  vertices: number[] = [];
+  indices: number[] = [];
+  vertex(p: Vec3, n: Vec3, c: RGB) {
+    this.vertices.push(p[0], p[1], p[2], n[0], n[1], n[2], c[0], c[1], c[2], 0, 0);
+    return this.vertices.length / 11 - 1;
+  }
+  /** A grid of rows x cols vertices from `point(i, j)`, triangles facing the camera (+z) or up. */
+  grid(rows: number, cols: number, point: (i: number, j: number) => { p: Vec3; n: Vec3; c: RGB }) {
+    const first = this.vertices.length / 11;
+    for (let i = 0; i < rows; i++)
+      for (let j = 0; j < cols; j++) {
+        const { p, n, c } = point(i, j);
+        this.vertex(p, n, c);
+      }
+    const id = (i: number, j: number) => first + i * cols + j;
+    for (let i = 0; i + 1 < rows; i++)
+      for (let j = 0; j + 1 < cols; j++) this.indices.push(id(i, j), id(i, j + 1), id(i + 1, j + 1), id(i, j), id(i + 1, j + 1), id(i + 1, j));
+  }
+  geometry(): Geometry {
+    return { vertices: new Float32Array(this.vertices), indices: new Uint32Array(this.indices) };
+  }
+}
+
+const meshes = new Map<string, Model>();
+const cached = (key: string, build: () => Model) => {
+  let m = meshes.get(key);
+  if (!m) {
+    m = cacheGameAsset('shared/EngineMeadow:' + key, build);
+    meshes.set(key, m);
+  }
+  return m;
+};
+
+// ── Sky ───────────────────────────────────────────────────────────────
+
+const SKY_RADIUS = 420;
+
+/**
+ * The sky: a curved band around the eye, its color by elevation. Its normals point at the light, so
+ * the shading the renderer applies is a known factor, divided out of the colors: it shows exactly them.
+ */
+function skyMesh(theme: GameTheme): Model {
+  const isNight = night(theme);
+  return cached(`meadow-sky:${isNight ? 'night' : 'day'}`, () => {
+    const light = lightFor(theme);
+    const n = normalize(light.direction);
+    const hemisphere = 0.6 + 0.4 * (n[1] * 0.5 + 0.5);
+    const lit = light.ambient * hemisphere + (1 - light.ambient);
+    const lc = light.color ?? [1, 1, 1];
+    const sky = isNight ? SKY_NIGHT : SKY_DAY;
+    const m = new Mesh();
+    const rows = 14;
+    const cols = 24;
+    m.grid(rows, cols, (i, j) => {
+      const elevation = -0.12 + (i / (rows - 1)) * 1.2; // radians, from just below the horizon up
+      const azimuth = -1.25 + (j / (cols - 1)) * 2.5;
+      const t = Math.max(0, elevation) / 1.08;
+      const c = t < 0.25 ? mix(sky.horizon, sky.mid, smooth(t / 0.25)) : mix(sky.mid, sky.zenith, smooth((t - 0.25) / 0.75));
+      return {
+        p: [
+          Math.sin(azimuth) * Math.cos(elevation) * SKY_RADIUS,
+          Math.sin(elevation) * SKY_RADIUS,
+          -Math.cos(azimuth) * Math.cos(elevation) * SKY_RADIUS
+        ],
+        n,
+        c: [Math.min(1, c[0] / (lit * lc[0])), Math.min(1, c[1] / (lit * lc[1])), Math.min(1, c[2] / (lit * lc[2]))]
+      };
+    });
+    // Rows run up and columns left to right as the eye sees them: the grid's winding already faces it
+    return createShape(m.geometry(), { center: false });
+  });
+}
+
+// ── Hills and ground ──────────────────────────────────────────────────
+
+/** Where the scene is: green rolling hills and a grass meadow, or sandstone mesas over a desert. */
+export type Biome = 'meadow' | 'desert';
+
+const HILLS: Record<Biome, { distance: number; height: number; roughness: number; colors: [string, string]; haze: number; mesa?: boolean }[]> = {
+  meadow: [
+    { distance: 250, height: 34, roughness: 0.012, colors: ['#5f8a6e', '#4b7560'], haze: 0.62 },
+    { distance: 150, height: 20, roughness: 0.02, colors: ['#4f8a4a', '#3b6e3c'], haze: 0.4 },
+    { distance: 85, height: 11, roughness: 0.035, colors: ['#4a8f3c', '#356f2c'], haze: 0.2 }
+  ],
+  // Flat-topped sandstone mesas, redder up close, paler and bluer far off
+  desert: [
+    { distance: 250, height: 40, roughness: 0.014, colors: ['#c7a07e', '#a9846a'], haze: 0.58, mesa: true },
+    { distance: 150, height: 26, roughness: 0.022, colors: ['#c9875a', '#a5643d'], haze: 0.36, mesa: true },
+    { distance: 85, height: 9, roughness: 0.04, colors: ['#ddb27a', '#c4925a'], haze: 0.16 }
+  ]
+};
+
+/** A range of hills: a wavy ridge `distance` metres out, shaded lighter at the ridge, faded into the haze. */
+function hillMesh(index: number, biome: Biome = 'meadow'): Model {
+  return cached(`meadow-hill:${biome}:${index}`, () => {
+    const h = HILLS[biome][index]!;
+    const ridge = rgb(h.colors[0]!);
+    const foot = rgb(h.colors[1]!);
+    const m = new Mesh();
+    const cols = 90;
+    const span = h.distance * 1.3;
+    m.grid(3, cols, (i, j) => {
+      const x = -span + (j / (cols - 1)) * span * 2;
+      const n = fbm(x * h.roughness + index * 7, index * 3.1);
+      // Mesas: steep sides and flat tops where the noise runs high
+      const top = h.height * (h.mesa ? Math.min(1, 0.25 + Math.max(0, n - 0.35) * 3.2) : 0.35 + 0.65 * n);
+      const y = i === 0 ? top : i === 1 ? top * 0.45 : -2;
+      const z = -h.distance - fbm(x * 0.01, index) * 20 + (i === 0 ? 0 : 4 * i);
+      const base = i === 0 ? ridge : mix(ridge, foot, i / 2);
+      return { p: [x, y, z], n: normalize([0, 0.55, 0.85]), c: mix(base, HAZE, h.haze) };
+    });
+    const g = m.geometry();
+    // The rows run down the hill: flip the winding so the faces look at the camera
+    for (let k = 0; k < g.indices.length; k += 3) {
+      const a = g.indices[k + 1]!;
+      g.indices[k + 1] = g.indices[k + 2]!;
+      g.indices[k + 2] = a;
+    }
+    return createShape(g, { center: false });
+  });
+}
+
+/** The meadow: grass patches in a few greens, fading into the haze toward the horizon. */
+function groundMesh(): Model {
+  return cached('meadow-ground', () => {
+    const light = rgb('#5fae3e');
+    const dark = rgb('#3c7f2a');
+    const dry = rgb('#9bb24a');
+    const m = new Mesh();
+    const rows = 46;
+    const cols = 40;
+    m.grid(rows, cols, (i, j) => {
+      // Dense near the camera, sparse far away; starting just ahead of the eye, so a game looking down
+      // steeply (Whack a Mole's lawn) still has grass under its nearest pieces
+      const z = -(Math.pow(1.13, i) - 1) * (246 / 243) - 0.3;
+      const half = 12 + -z * 1.25;
+      const x = -half + (j / (cols - 1)) * half * 2;
+      const n1 = fbm(x * 0.08, z * 0.08);
+      const n2 = noise(x * 0.5, z * 0.5);
+      let c = mix(dark, light, n1);
+      c = mix(c, dry, Math.max(0, n2 - 0.7) * 1.5);
+      const haze = 1 - Math.exp(-((-z / 170) ** 2));
+      return { p: [x, 0, z], n: [0, 1, 0], c: mix(c, HAZE, haze * 0.75) };
+    });
+    // Rows run away from the camera (up the screen), columns left to right: the grid's winding faces it
+    return createShape(m.geometry(), { center: false });
+  });
+}
+
+// ── Plants and rocks (each one unit-ish, scaled where they're placed) ──
+
+/** Leafy color: a few greens, darker underneath and toward the inside. */
+const leafy =
+  (light: RGB, dark: RGB, seed: number) =>
+  ({ position: p }: { position: Vec3 }): Color => {
+    const n = noise(p[0] * 9 + seed, p[1] * 9 + p[2] * 7);
+    return mix(dark, light, Math.min(1, Math.max(0, 0.25 + p[1] * 0.6 + n * 0.5)));
+  };
+
+/** A broad-leaved tree about one unit tall: a tapering trunk and a cloud of leafy clumps. */
+const oakMesh = () =>
+  cached('meadow-oak', () => {
+    const bark = rgb('#6b4423');
+    const sphere = shapeGeometry('sphere');
+    const clumps: [Vec3, number][] = [
+      [[0, 0.62, 0], 0.46],
+      [[-0.2, 0.54, 0.06], 0.32],
+      [[0.22, 0.56, -0.04], 0.34],
+      [[0.04, 0.82, 0.03], 0.32],
+      [[-0.12, 0.74, -0.14], 0.28],
+      [[0.14, 0.72, 0.16], 0.28],
+      [[-0.24, 0.68, -0.02], 0.24]
+    ];
+    const canopy = clumps.map(([position, size], i) => ({
+      geometry: recolor(shapeGeometry('sphere'), leafy(rgb('#6fbf4a'), rgb('#24602a'), i * 3.7)),
+      position,
+      scale: size
+    }));
+    return createShape(
+      merge([
+        {
+          geometry: tube(
+            [
+              [0, 0, 0],
+              [0.01, 0.25, 0],
+              [-0.02, 0.5, 0.01]
+            ],
+            { radius: (t) => 0.055 - t * 0.025, color: bark }
+          )
+        },
+        ...canopy,
+        { geometry: sphere, position: [0, 0.01, 0], scale: [0.14, 0.03, 0.14], color: rgb('#5a3a1e') }
+      ]),
+      { center: false, shine: 0.05 }
+    );
+  });
+
+/** A pine about one unit tall: a trunk and stacked cones, each a little narrower. */
+export const pineMesh = () =>
+  cached('meadow-pine', () => {
+    const tiers = [0, 1, 2, 3].map((i) => {
+      const base = 0.18 + i * 0.19;
+      const r = 0.3 - i * 0.06;
+      return {
+        geometry: recolor(
+          lathe(
+            [
+              [r, base],
+              [r * 0.55, base + 0.12],
+              [0.001, base + 0.3]
+            ],
+            { segments: 14 }
+          ),
+          leafy(rgb('#3f8a45'), rgb('#123d1d'), i * 5.1)
+        )
+      };
+    });
+    return createShape(
+      merge([
+        {
+          geometry: tube(
+            [
+              [0, 0, 0],
+              [0, 0.4, 0]
+            ],
+            { radius: (t) => 0.045 - t * 0.02, color: rgb('#5a3a22') }
+          )
+        },
+        ...tiers
+      ]),
+      { center: false }
+    );
+  });
+
+/** A bush about half a unit tall: a few overlapping leafy clumps. */
+export const bushMesh = () =>
+  cached('meadow-bush', () =>
+    createShape(
+      merge(
+        (
+          [
+            [[0, 0.22, 0], 0.5],
+            [[-0.24, 0.16, 0.05], 0.36],
+            [[0.25, 0.17, -0.03], 0.38],
+            [[0.05, 0.36, 0.04], 0.34]
+          ] as [Vec3, number][]
+        ).map(([position, size], i) => ({
+          geometry: recolor(shapeGeometry('sphere'), leafy(rgb('#77c24f'), rgb('#2d6b2a'), i * 2.3)),
+          position,
+          scale: [size, size * 0.8, size] as Vec3
+        }))
+      ),
+      { center: false, shine: 0.08 }
+    )
+  );
+
+/** A weathered grey boulder, one unit across. */
+export const rockMesh = () =>
+  cached('meadow-rock', () =>
+    createShape(
+      merge([
+        {
+          geometry: recolor(shapeGeometry('sphere'), ({ position: p }) => {
+            const g = 0.48 + noise(p[0] * 6, p[1] * 6 + p[2] * 4) * 0.22;
+            return [g, g * 0.98, g * 0.92];
+          }),
+          scale: [1, 0.55, 0.8],
+          position: [0, 0.18, 0]
+        }
+      ]),
+      { center: false, shine: 0.15 }
+    )
+  );
+
+/** A tuft of grass blades, about a third of a unit tall, dark at the root and sunlit at the tips. */
+export const tuftMesh = () =>
+  cached('meadow-tuft', () => {
+    const rand = random(7);
+    const blades = Array.from({ length: 7 }, () => {
+      const a = rand() * Math.PI * 2;
+      const lean = 0.05 + rand() * 0.08;
+      const h = 0.22 + rand() * 0.14;
+      const ox = (rand() - 0.5) * 0.08;
+      const oz = (rand() - 0.5) * 0.08;
+      return {
+        geometry: recolor(
+          tube(
+            [
+              [ox, 0, oz],
+              [ox + Math.cos(a) * lean * 0.4, h * 0.55, oz + Math.sin(a) * lean * 0.4],
+              [ox + Math.cos(a) * lean, h, oz + Math.sin(a) * lean]
+            ],
+            { radius: (t) => 0.014 * (1 - t), sides: 4, smoothness: 3 }
+          ),
+          ({ position: p }) => mix(rgb('#2f6e22'), rgb('#9ad466'), Math.min(1, p[1] / 0.3))
+        )
+      };
+    });
+    return createShape(merge(blades), { center: false });
+  });
+
+/** A little flower: white petals (tinted where it's placed) round a golden centre. */
+export const flowerMesh = () =>
+  cached('meadow-flower', () => {
+    const sphere = shapeGeometry('sphere');
+    const petals = [0, 1, 2, 3, 4].map((i) => {
+      const a = (i / 5) * Math.PI * 2;
+      return {
+        geometry: sphere,
+        position: [Math.cos(a) * 0.05, 0.2, Math.sin(a) * 0.05] as Vec3,
+        scale: [0.06, 0.025, 0.06] as Vec3,
+        color: [1, 1, 1] as Color
+      };
+    });
+    return createShape(
+      merge([
+        {
+          geometry: tube(
+            [
+              [0, 0, 0],
+              [0.01, 0.2, 0]
+            ],
+            { radius: 0.006, sides: 4, color: rgb('#3d7a2a') }
+          )
+        },
+        ...petals,
+        { geometry: sphere, position: [0, 0.21, 0], scale: 0.04, color: rgb('#ffd23f') }
+      ]),
+      { center: false }
+    );
+  });
+
+/** Hot-air balloon envelopes: alternating stripe colors round the envelope. */
+const HOT_AIR_PATTERNS: [string, string][] = [
+  ['#e8433b', '#ffd34d'],
+  ['#2f7ae5', '#ffffff'],
+  ['#7b4fd6', '#ff8a3d']
+];
+
+/** A hot-air balloon about one unit tall: a striped envelope, ropes and a wicker basket. */
+const hotAirBalloonMesh = (pattern: number) =>
+  cached(`meadow-hot-air:${pattern}`, () => {
+    const [a, b] = HOT_AIR_PATTERNS[pattern]!.map(rgb) as [RGB, RGB];
+    const envelope = lathe(
+      [
+        [0.08, 0.28],
+        [0.16, 0.36],
+        [0.3, 0.52],
+        [0.36, 0.66],
+        [0.35, 0.8],
+        [0.27, 0.93],
+        [0.12, 1],
+        [0.001, 1.01]
+      ],
+      { segments: 24, color: ({ u }) => (Math.floor(u * 12) % 2 ? a : b) }
+    );
+    const ropes = [0, 1, 2, 3].map((i) => {
+      const t = (i / 4) * Math.PI * 2 + Math.PI / 4;
+      return {
+        geometry: tube(
+          [
+            [Math.cos(t) * 0.075, 0.28, Math.sin(t) * 0.075],
+            [Math.cos(t) * 0.05, 0.12, Math.sin(t) * 0.05]
+          ],
+          { radius: 0.004, sides: 3, color: rgb('#5a4630') }
+        )
+      };
+    });
+    return createShape(
+      merge([
+        { geometry: envelope },
+        ...ropes,
+        { geometry: shapeGeometry('roundedBox'), position: [0, 0.08, 0], scale: [0.11, 0.08, 0.11], color: rgb('#8a5a2b') }
+      ]),
+      { center: false, shine: 0.25 }
+    );
+  });
+
+// ── The scene ─────────────────────────────────────────────────────────
+
+const FLOWER_COLORS: Color[] = ['#FF6B9D', '#FF5A5A', '#B784FF', '#6FA8FF', '#FF9F43', '#FFFFFF'].map((c) => toColor(c));
+
+/** What's in a game's meadow, and where the sun and clouds sit on its screen. */
+export type MeadowOptions = {
+  /** The sun (or moon), as fractions of the screen. Default [0.8, 0.2]. */
+  sun?: readonly [number, number];
+  /** The band of sky the clouds sit in, as fractions down the screen. Default [0.1, 0.42]. */
+  clouds?: readonly [number, number];
+  /** The big oak and pine framing the play area. Default true. */
+  framingTrees?: boolean;
+  /** Grass tufts and flowers right in front. Default true. */
+  foreground?: boolean;
+  /** Hot-air balloons drifting far off. Default 0. */
+  hotAirBalloons?: number;
+  /** Meadow (default) or desert. */
+  biome?: Biome;
+  /**
+   * The ground and everything standing on it (treeline, framing trees, bushes, rocks, foreground).
+   * Default true; a game that scrolls its own ground passes false and gets only the sky and far hills.
+   */
+  near?: boolean;
+  /** Trees, bushes, rocks and foreground plants on the ground. Default true. */
+  groundDetails?: boolean;
+};
+
+/** Spawns the whole world for a view and theme; returns every entity, to despawn on a new layout or theme. */
+export function spawnWorld(world: World, v: View3D, theme: GameTheme, options: MeadowOptions = {}): Entity[] {
+  const [sunX, sunY] = options.sun ?? [0.8, 0.2];
+  const [cloudTop, cloudBottom] = options.clouds ?? [0.1, 0.42];
+  const isNight = night(theme);
+  const tint = isNight ? NIGHT_TINT : DAY_TINT;
+  const shade = (c: Color): Color => [c[0] * tint[0], c[1] * tint[1], c[2] * tint[2], c[3] ?? 1];
+  const out: Entity[] = [];
+  const spawn = (mesh: Model | 'sphere' | 'puff', position: Vec3, size: Vec3 | number, color: Color, rotation?: Quat) =>
+    out.push(world.spawn({ mesh, position, scale: size, color, ...(rotation ? { rotation } : {}), pickable: false }));
+  const rand = random(42);
+  const yaw = (a: number) => quat.y(a);
+
+  // Sky, then the sun (or moon and stars) in it, up to the right as in the original scene
+  spawn(skyMesh(theme), v.eye, 1, [1, 1, 1, 1]);
+  const sunDir = rayThrough(v, v.width * sunX, v.height * sunY);
+  const sunAt = add(v.eye, scale(sunDir, 380));
+  if (isNight) {
+    spawn('puff', sunAt, 90, [1.3, 1.3, 1.9, 0.35]);
+    spawn('sphere', sunAt, 15, [2.1, 2.1, 2.3]);
+    for (let i = 0; i < 46; i++) {
+      const dir = rayThrough(v, rand() * v.width, rand() * v.height * v.horizon * 0.82);
+      spawn('sphere', add(v.eye, scale(dir, 395)), 0.7 + rand() * 1.1, [2, 2, 2.2]);
+    }
+  } else {
+    spawn('puff', sunAt, 170, [2.2, 1.9, 1.2, 0.5]);
+    spawn('puff', sunAt, 70, [2.4, 2.2, 1.6, 0.85]);
+    spawn('sphere', sunAt, 22, [2.6, 2.35, 1.7]);
+  }
+
+  // Clouds: soft puffs bunched together, drifting slowly
+  const cloudColor: Color = isNight ? [0.66, 0.68, 0.84, 0.88] : [1.18, 1.18, 1.22, 0.92];
+  for (let c = 0; c < 7; c++) {
+    const dir = rayThrough(
+      v,
+      (c / 6) * v.width * 1.1 - v.width * 0.05 + (rand() - 0.5) * 60,
+      v.height * (cloudTop + rand() * (cloudBottom - cloudTop))
+    );
+    const centre = add(v.eye, scale(dir, 200 + rand() * 120));
+    const size = 22 + rand() * 18;
+    for (let p = 0; p < 7; p++) {
+      const offset: Vec3 = [(rand() - 0.5) * size * 2.2, (rand() - 0.3) * size * 0.5, (rand() - 0.5) * size * 0.6];
+      out.push(
+        world.spawn({
+          mesh: 'puff',
+          position: add(centre, offset),
+          scale: size * (0.8 + rand() * 0.7),
+          color: cloudColor,
+          velocity: [0.12, 0, 0],
+          pickable: false
+        })
+      );
+    }
+  }
+
+  // Hills, far to near, then the meadow
+  const biome = options.biome ?? 'meadow';
+  HILLS[biome].forEach((_, i) => spawn(hillMesh(i, biome), [0, 0, 0], 1, shade([1, 1, 1, 1])));
+  const near = options.near ?? true;
+  const groundDetails = near && (options.groundDetails ?? true);
+  if (near) spawn(groundMesh(), [0, 0, 0], 1, shade([1, 1, 1, 1]));
+
+  // A treeline across the middle distance
+  for (let i = 0; groundDetails && i < 26; i++) {
+    const z = -(26 + rand() * 50);
+    const x = (rand() * 2 - 1) * (-z * 0.62 + 6);
+    const pine = rand() < 0.45;
+    const h = (pine ? 8 : 6) + rand() * 5;
+    spawn(
+      pine ? pineMesh() : oakMesh(),
+      [x, 0, z],
+      [h * (0.85 + rand() * 0.3), h, h * (0.85 + rand() * 0.3)],
+      shade([1, 1, 1, 1]),
+      yaw(rand() * 6.3)
+    );
+  }
+  // The two big trees framing the play area: an oak to the left, a pine to the right
+  if (groundDetails && (options.framingTrees ?? true)) {
+    spawn(oakMesh(), [-4.6, 0, -11], [8.5, 8, 8.5], shade([1, 1, 1, 1]), yaw(0.6));
+    spawn(pineMesh(), [5.2, 0, -14], [8, 12, 8], shade([1, 1, 1, 1]), yaw(1.9));
+  }
+
+  // Bushes and rocks in the middle ground
+  for (let i = 0; groundDetails && i < 16; i++) {
+    const z = -(7 + rand() * 24);
+    const x = (rand() * 2 - 1) * (-z * 0.55 + 2);
+    const s = 1 + rand() * 1.4;
+    spawn(bushMesh(), [x, 0, z], [s * 1.2, s, s * 1.2], shade([0.9 + rand() * 0.2, 1, 0.9, 1]), yaw(rand() * 6.3));
+  }
+  for (let i = 0; groundDetails && i < 7; i++) {
+    const z = -(6 + rand() * 20);
+    const x = (rand() * 2 - 1) * (-z * 0.5 + 1.5);
+    const s = 0.35 + rand() * 0.8;
+    spawn(rockMesh(), [x, 0, z], s, shade([1, 1, 1, 1]), yaw(rand() * 6.3));
+  }
+
+  // Hot-air balloons far off, drifting with the breeze and bobbing gently
+  for (let i = 0; i < (options.hotAirBalloons ?? 0); i++) {
+    const dir = rayThrough(v, v.width * (0.15 + 0.7 * rand()), v.height * (cloudTop + 0.05 + rand() * (cloudBottom - cloudTop)));
+    const where = add(v.eye, scale(dir, 70 + rand() * 60));
+    const size = 9 + rand() * 4;
+    out.push(
+      world.spawn({
+        mesh: hotAirBalloonMesh(i % HOT_AIR_PATTERNS.length),
+        position: where,
+        scale: size,
+        rotation: yaw(rand() * 6.3),
+        color: shade([1, 1, 1, 1]),
+        velocity: [0.25 + rand() * 0.2, 0, 0],
+        bob: { amplitude: [0, size * 0.06, 0], speed: 0.6 + rand() * 0.3, phase: rand() * 6.3 },
+        pickable: false
+      })
+    );
+  }
+
+  if (!groundDetails || !(options.foreground ?? true)) return out;
+  // Grass tufts and flowers in the foreground
+  for (let i = 0; i < 150; i++) {
+    const z = -(4.4 + Math.pow(rand(), 1.6) * 16);
+    const x = (rand() * 2 - 1) * (-z * 0.52 + 0.8);
+    const s = 0.9 + rand() * 0.9;
+    spawn(tuftMesh(), [x, 0, z], s, shade([1, 1, 1, 1]), yaw(rand() * 6.3));
+  }
+  for (let i = 0; i < 55; i++) {
+    const z = -(4.6 + Math.pow(rand(), 1.4) * 14);
+    const x = (rand() * 2 - 1) * (-z * 0.5 + 0.6);
+    const color = FLOWER_COLORS[Math.floor(rand() * FLOWER_COLORS.length)]!;
+    spawn(flowerMesh(), [x, 0, z], 0.9 + rand() * 0.6, shade(color), yaw(rand() * 6.3));
+  }
+  return out;
+}
+
+/** The clear color behind everything (only ever peeks out at the very edges). */
+export const backgroundFor = (theme: GameTheme): readonly [number, number, number] => (night(theme) ? SKY_NIGHT.horizon : SKY_DAY.horizon);
+
+/** Fixed scenery shared by the meadow games; seeded placement remains per run. */
+export function* warmAssets(theme: GameTheme, biomes: readonly Biome[] = ['meadow', 'desert']): Iterable<() => unknown> {
+  yield () => skyMesh(theme);
+  for (const biome of biomes) for (let i = 0; i < HILLS[biome].length; i++) yield () => hillMesh(i, biome);
+  for (const build of [groundMesh, oakMesh, pineMesh, bushMesh, rockMesh, tuftMesh, flowerMesh]) yield build;
+  for (let i = 0; i < HOT_AIR_PATTERNS.length; i++) yield () => hotAirBalloonMesh(i);
+}