@gtanczyk/diorama 0.0.0-stage → 0.1.0

package/app/src/play/rig.ts

@@ -0,0 +1,172 @@
+// rig.json: a cut-out figure (parts + joints) and the walk it can do. `diorama rig` writes it; the
+// runtime poses it every frame. All coordinates are in the figure's own image, facing right, y down.
+// No Node imports: the browser bundles this file.
+import { z } from 'zod';
+
+const XY = z.tuple([z.number(), z.number()]);
+
+export const PART_NAMES = ['farArm', 'farThigh', 'farShin', 'farBoot', 'nearThigh', 'nearShin', 'nearBoot', 'torso', 'nearArm'] as const;
+export type PartName = (typeof PART_NAMES)[number];
+
+export const Rig = z.object({
+  size: XY,
+  /** Sole row: where the feet stand. */
+  ground: z.number(),
+  /** Head top to sole, px. */
+  height: z.number(),
+  hip: XY,
+  shoulder: z.object({ near: XY, far: XY }),
+  leg: z.object({
+    near: z.object({ knee: XY, ankle: XY }),
+    far: z.object({ knee: XY, ankle: XY }),
+  }),
+  /** Drawn back to front; `at` is the part image's top-left in the figure. */
+  parts: z.array(z.object({ name: z.enum(PART_NAMES), file: z.string(), at: XY })),
+  /**
+   * The walk drawn ahead as a sheet (src/scene/warp.ts): `frames` cells of one cycle, then the standing figure, each
+   * `cell` px (the rig's size times `scale`). Present, the parts are not used.
+   */
+  sheet: z.object({ file: z.string(), cols: z.number(), rows: z.number(), frames: z.number(), cell: XY, scale: z.number() }).optional(),
+  /** The walk measured when it was made (src/scene/rig-check.ts): not ok, the figure slides as one piece instead. */
+  check: z.object({ ok: z.boolean(), holes: z.number(), loose: z.number(), why: z.string().optional() }).optional(),
+});
+export type Rig = z.infer<typeof Rig>;
+
+type P = [number, number];
+/** Where each part goes this frame: rotate by `turn` about `from`, then move `from` to `to`. */
+export type PartPose = { from: P; to: P; turn: number };
+export type Pose = Record<PartName, PartPose>;
+
+/** The sheet cell for walk phase `phase`, or the standing cell. */
+export function sheetCell(sheet: NonNullable<Rig['sheet']>, phase: number, walking: boolean): number {
+  return walking ? Math.floor((((phase % 1) + 1) % 1) * sheet.frames) % sheet.frames : sheet.frames;
+}
+
+/** Distance the figure travels per walk cycle, as a share of its height. */
+export const CYCLE = 0.55;
+const STANCE = 0.6;
+const LIFT = 0.06;
+const ARM_SWING = 0.32;
+
+const sub = (a: P, b: P): P => [a[0] - b[0], a[1] - b[1]];
+const len = (a: P) => Math.hypot(a[0], a[1]);
+const angle = (a: P) => Math.atan2(a[1], a[0]);
+const smooth = (u: number) => u * u * (3 - 2 * u);
+
+/** Ankle offset from the hip (dx) and lift above the ground for one leg at phase p (0 = heel strike). */
+export function footAt(p: number, step: number): { dx: number; lift: number } {
+  p = ((p % 1) + 1) % 1;
+  if (p < STANCE) return { dx: step / 2 - (step * p) / STANCE, lift: 0 };
+  const u = (p - STANCE) / (1 - STANCE);
+  return { dx: -step / 2 + step * smooth(u), lift: Math.sin(Math.PI * u) };
+}
+
+/** Knee position for a two-bone leg from hip to ankle target, knee bending forward (+x). */
+export function solveKnee(hip: P, target: P, thigh: number, shin: number): { knee: P; ankle: P } {
+  let d = sub(target, hip);
+  const reach = len(d);
+  const max = (thigh + shin) * 0.999;
+  if (reach > max) d = [(d[0] * max) / reach, (d[1] * max) / reach];
+  const r = Math.min(len(d), max);
+  const ankle: P = [hip[0] + d[0], hip[1] + d[1]];
+  // Law of cosines for the thigh's angle off the hip-ankle line.
+  const cos = Math.max(-1, Math.min(1, (thigh * thigh + r * r - shin * shin) / (2 * thigh * r || 1)));
+  const a = angle(d) - Math.acos(cos);
+  return { knee: [hip[0] + thigh * Math.cos(a), hip[1] + thigh * Math.sin(a)], ankle };
+}
+
+/**
+ * The pose at walk phase `phase` (cycles, any real), or standing when `walking` is false.
+ * The near leg strikes at phase 0, the far leg half a cycle later.
+ */
+export function pose(rig: Rig, phase: number, walking: boolean): Pose {
+  const H = rig.height;
+  const step = CYCLE * STANCE * H;
+  const legs = (['near', 'far'] as const).map((side) => {
+    const rest = rig.leg[side];
+    const thigh = len(sub(rest.knee, rig.hip));
+    const shin = len(sub(rest.ankle, rest.knee));
+    const ankleUp = rig.ground - rest.ankle[1];
+    const foot = walking ? footAt(phase + (side === 'far' ? 0.5 : 0), step) : { dx: (side === 'near' ? 0.03 : -0.03) * H, lift: 0 };
+    return { side, rest, thigh, shin, ankleUp, foot };
+  });
+  // The hip sinks just enough for every planted foot to reach the ground: the bob of a walk.
+  let hipY = rig.hip[1];
+  for (const l of legs) {
+    if (l.foot.lift > 0) continue;
+    const vertical = Math.sqrt(Math.max(0, (0.985 * (l.thigh + l.shin)) ** 2 - l.foot.dx ** 2));
+    hipY = Math.max(hipY, rig.ground - l.ankleUp - vertical);
+  }
+  const hip: P = [rig.hip[0], hipY];
+  const drop = hipY - rig.hip[1];
+  const out = {} as Pose;
+  for (const l of legs) {
+    const target: P = [hip[0] + l.foot.dx, rig.ground - l.ankleUp - l.foot.lift * LIFT * H];
+    const { knee, ankle } = solveKnee(hip, target, l.thigh, l.shin);
+    const thighTurn = angle(sub(knee, hip)) - angle(sub(l.rest.knee, rig.hip));
+    const shinTurn = angle(sub(ankle, knee)) - angle(sub(l.rest.ankle, l.rest.knee));
+    const name = l.side === 'near' ? 'near' : 'far';
+    out[`${name}Thigh`] = { from: rig.hip, to: hip, turn: thighTurn };
+    out[`${name}Shin`] = { from: l.rest.knee, to: knee, turn: shinTurn };
+    // A planted boot stays flat on the ground; a swinging one follows the shin a little.
+    out[`${name}Boot`] = { from: l.rest.ankle, to: ankle, turn: l.foot.lift > 0 ? shinTurn * 0.5 : 0 };
+  }
+  const swing = (side: 'near' | 'far') => {
+    const dx = legs.find((l) => l.side === side)!.foot.dx;
+    return walking ? (ARM_SWING * dx) / (step / 2) : 0;
+  };
+  const lift = (p: P): P => [p[0], p[1] + drop];
+  out.torso = { from: rig.hip, to: hip, turn: 0 };
+  // Each arm swings against its own side's leg: near leg forward, near arm back (clockwise).
+  out.nearArm = { from: rig.shoulder.near, to: lift(rig.shoulder.near), turn: swing('near') };
+  out.farArm = { from: rig.shoulder.far, to: lift(rig.shoulder.far), turn: swing('far') };
+  return out;
+}
+
+const THIGH_SWING = 0.3;
+const KNEE_BEND = 0.55;
+const ARM_TURN = 0.22;
+
+const turnAbout = (p: P, about: P, a: number): P => {
+  const c = Math.cos(a);
+  const s = Math.sin(a);
+  const d = sub(p, about);
+  return [about[0] + c * d[0] - s * d[1], about[1] + s * d[0] + c * d[1]];
+};
+
+/**
+ * A walk told in angles from the painted stance, not reached by solving for foot targets: each thigh swings a
+ * little either side of where it was painted and the knee bends while the foot is up. Whatever the painting's
+ * stance (feet wide apart, boots up to the knee), no limb turns further than THIGH_SWING + KNEE_BEND, so a figure
+ * warped as one mesh (src/scene/warp.ts) bends without folding over itself. The planted foot stays on the ground.
+ */
+export function swingPose(rig: Rig, phase: number): Pose {
+  const out = {} as Pose;
+  const legs = (['near', 'far'] as const).map((side) => {
+    const p = (((phase + (side === 'far' ? 0.5 : 0)) % 1) + 1) % 1;
+    // Forward is anticlockwise for a figure facing right (y down): the thigh comes forward for heel strike at 0.
+    const thigh = -THIGH_SWING * Math.cos(2 * Math.PI * p);
+    const lifted = p > 0.5 ? Math.sin(Math.PI * (p - 0.5) / 0.5) : 0;
+    const shin = thigh + KNEE_BEND * lifted;
+    const rest = rig.leg[side];
+    const knee = turnAbout(rest.knee, rig.hip, thigh);
+    const ankleAt: P = [knee[0] + Math.cos(shin) * (rest.ankle[0] - rest.knee[0]) - Math.sin(shin) * (rest.ankle[1] - rest.knee[1]), knee[1] + Math.sin(shin) * (rest.ankle[0] - rest.knee[0]) + Math.cos(shin) * (rest.ankle[1] - rest.knee[1])];
+    return { side, thigh, shin, knee, ankle: ankleAt, lifted, rest };
+  });
+  // The body sinks so the planted foot (the one not lifted, or the lower) stays on the ground.
+  const planted = legs.reduce((a, b) => (a.lifted < b.lifted || (a.lifted === b.lifted && a.ankle[1] > b.ankle[1]) ? a : b));
+  const drop = planted.rest.ankle[1] - planted.ankle[1];
+  const down = (q: P): P => [q[0], q[1] + drop];
+  const hip = down(rig.hip);
+  for (const l of legs) {
+    out[`${l.side}Thigh`] = { from: rig.hip, to: hip, turn: l.thigh };
+    out[`${l.side}Shin`] = { from: l.rest.knee, to: down(l.knee), turn: l.shin };
+    // A planted boot stays flat; a lifted one tips with the shin a little.
+    out[`${l.side}Boot`] = { from: l.rest.ankle, to: down(l.ankle), turn: l.lifted * l.shin * 0.5 };
+  }
+  out.torso = { from: rig.hip, to: hip, turn: 0 };
+  const arm = ARM_TURN * Math.cos(2 * Math.PI * phase);
+  out.nearArm = { from: rig.shoulder.near, to: down(rig.shoulder.near), turn: arm };
+  out.farArm = { from: rig.shoulder.far, to: down(rig.shoulder.far), turn: -arm };
+  return out;
+}

package/app/src/play/shadow.ts

@@ -0,0 +1,253 @@
+// shadow: a person's cast shadow on the painted ground, using its depth map (geometry.depth). Every ground
+// pixel becomes a 3D point; a ray from it toward the sun either crosses the person or not. The person is a
+// flat card standing at the feet, turned to face the sun, carrying the figure's silhouette. So the shadow
+// breaks over each step, climbs a wall in its way and drops off a quay, where the flat shear can't.
+// No Node imports: the browser bundles this file.
+import type { Geometry } from './geometry.ts';
+
+/** A 1.62 m person is personPx tall: the scale's unit (PERSON_M in src/scene/scale.ts). */
+const PERSON_M = 1.62;
+/** depth.png's layout (DEPTH_SCALE and DEPTH_UNIT in src/scene/depthmap.ts). */
+export const DEPTH_SCALE = 2;
+export const DEPTH_UNIT = 16;
+/** Ground within about this many metres past the feet is taken as level with them (see shadowAt). */
+const CONTACT_M = 0.25;
+/**
+ * Away from the feet, a surface that is neither a thing nor floor-like catches no shadow: floor-like is no
+ * steeper than FLOOR_SLOPE (metres up per metre across, a few px up the screen) and, off the floor masks,
+ * within FLOOR_RISE_M of the feet's level (a puddle, the water below a quay). Within NEAR_M of the feet any
+ * surface does (the quay's edge they stand on, a wall at their back). So a fog bank or a ship in the mist,
+ * which the depth model reads as a wall, and the ferry's side a floor mask took in, stay clean.
+ */
+const FLOOR_SLOPE = 1;
+const FLOOR_RISE_M = 0.5;
+const NEAR_M = 0.6;
+
+/** The depth map as floor rows below the horizon per pixel, at 1 / DEPTH_SCALE of the frame. */
+export type Depth = { w: number; h: number; rows: Float32Array };
+
+/** Decodes depth.png's pixels (RGBA, R high byte, G low byte) into rows below the horizon. */
+export function decodeDepth(rgba: Uint8ClampedArray | Uint8Array, w: number, h: number): Depth {
+  const rows = new Float32Array(w * h);
+  for (let i = 0; i < w * h; i++) rows[i] = ((rgba[i * 4] << 8) | rgba[i * 4 + 1]) / DEPTH_UNIT;
+  return { w, h, rows };
+}
+
+/** The sun for one person standing at (x, y): where they stand in 3D, and the light's way. */
+export type Sun = {
+  /** Camera height in metres; f is the focal length in px (any fixed value: only ratios reach the screen). */
+  camH: number;
+  f: number;
+  hor: number;
+  halfW: number;
+  /** The feet: across, into the picture, up (metres). */
+  feet: [number, number, number];
+  /** Horizontal unit vector the light travels along, and the one across it (pointing screen right). */
+  along: [number, number];
+  across: [number, number];
+  /** Rise of a sun ray per metre along the ground. */
+  rise: number;
+};
+
+/** The camera the depth map was measured with: what pointAt needs. */
+export type View = Pick<Sun, 'camH' | 'f' | 'hor' | 'halfW'>;
+
+export function viewOf(g: Geometry): View {
+  return { camH: PERSON_M / g.scale.pxPerY, f: g.frame.width, hor: g.scale.horizonY, halfW: g.frame.width / 2 };
+}
+
+/** The frame pixel a 3D point (across, into, up) is seen at: pointAt the other way. */
+export function toScreen(v: View, p: [number, number, number]): [number, number] | undefined {
+  if (p[1] <= 0.01) return undefined;
+  const zn = p[1] / v.f;
+  return [v.halfW + p[0] / zn, v.hor + (v.camH - p[2]) / zn];
+}
+
+/** Metres (across, into, up) of the depth pixel under frame pixel (x, y); undefined past the map. */
+export function pointAt(d: Depth, sun: Pick<Sun, 'camH' | 'f' | 'hor' | 'halfW'>, x: number, y: number): [number, number, number] | undefined {
+  const c = Math.floor(x / DEPTH_SCALE);
+  const r = Math.floor(y / DEPTH_SCALE);
+  if (c < 0 || r < 0 || c >= d.w || r >= d.h) return undefined;
+  const rows = d.rows[r * d.w + c];
+  if (rows <= 0) return undefined;
+  const zn = sun.camH / rows;
+  return [(x - sun.halfW) * zn, zn * sun.f, sun.camH - (y - sun.hor) * zn];
+}
+
+/**
+ * The sun for a person with feet at (x, y) and px tall. light.dir is how shadows run on screen and
+ * light.length how long they are per height there, as the painting shows them: both are turned into a
+ * direction on the ground and a sun height by projecting the ground near the feet.
+ */
+export function sunFor(g: Geometry, d: Depth, light: NonNullable<Geometry['light']>, x: number, y: number, px: number): Sun | undefined {
+  const hor = g.scale.horizonY;
+  const base = viewOf(g);
+  if (y - hor < 4) return undefined;
+  // The feet: the depth just above them (the floor they stand on), averaged across a few px.
+  const near = [-3, 0, 3].map((dx) => pointAt(d, base, x + dx, y - 2)).filter((p): p is [number, number, number] => !!p);
+  if (!near.length) return undefined;
+  const feet = [0, 1, 2].map((i) => near.reduce((s, p) => s + p[i], 0) / near.length) as [number, number, number];
+  // A point on the feet's level seen at screen (sx, sy), and back.
+  const drop = base.camH - feet[2];
+  const ground = (sx: number, sy: number): [number, number] => {
+    const zn = drop / Math.max(0.5, sy - hor);
+    return [(sx - base.halfW) * zn, zn * base.f];
+  };
+  const screen = (gx: number, gz: number): [number, number] => {
+    const zn = gz / base.f;
+    return [base.halfW + gx / zn, hor + drop / zn];
+  };
+  const n = Math.hypot(light.dir[0], light.dir[1]) || 1;
+  const [dx, dy] = [light.dir[0] / n, light.dir[1] / n];
+  const at = ground(x, y);
+  const step = ground(x + dx * 8, Math.max(hor + 1, y + dy * 8));
+  const len = Math.hypot(step[0] - at[0], step[1] - at[1]);
+  if (!(len > 0)) return undefined;
+  const along: [number, number] = [(step[0] - at[0]) / len, (step[1] - at[1]) / len];
+  let across: [number, number] = [-along[1], along[0]];
+  if (across[0] < 0) across = [-across[0], -across[1]];
+  // How far along the ground a head's shadow lands to sit length * px away on screen.
+  const want = light.length * px;
+  let [lo, hi] = [0, 400];
+  for (let i = 0; i < 30; i++) {
+    const s = (lo + hi) / 2;
+    const gz = at[1] + along[1] * s;
+    const [sx, sy] = gz > 0.01 ? screen(at[0] + along[0] * s, gz) : [Infinity, hor];
+    if (Math.hypot(sx - x, sy - y) < want) lo = s;
+    else hi = s;
+  }
+  const reach = (lo + hi) / 2;
+  if (!(reach > 0.01)) return undefined;
+  return { ...base, feet, along, across, rise: PERSON_M / reach };
+}
+
+/** The figure's silhouette (alpha only): w x h px, feet at (ox, oy), px per metre. */
+export type Silhouette = { alpha: Uint8ClampedArray; w: number; h: number; ox: number; oy: number; perM: number };
+
+/**
+ * Where a person's shadow can land, at the depth map's size: 2 on the things standing in the place (owner:
+ * their pixels, as thingShadows takes them), 1 on the floors (geometry.zone, else the walk cells), 0 on the
+ * rest, which catches it only where it looks like floor or right by the feet (see shadowAt). The depth model
+ * reads a fog bank or a ship in the mist as a wall a few metres away, and a shadow on it is a ghost in the air.
+ */
+export function catchers(d: Depth, g: Geometry, owner?: Uint8Array): Uint8Array {
+  const on = owner ? owner.map((o) => (o ? 2 : 0)) : new Uint8Array(d.w * d.h);
+  const grid = g.zone ?? g.walk;
+  for (let r = 0; r < d.h; r++) {
+    const row = grid[Math.floor((r * DEPTH_SCALE + 1) / g.cell)];
+    if (!row) continue;
+    for (let c = 0; c < d.w; c++) {
+      const ch = row[Math.floor((c * DEPTH_SCALE + 1) / g.cell)];
+      if (ch && ch !== '.' && !on[r * d.w + c]) on[r * d.w + c] = 1;
+    }
+  }
+  return on;
+}
+
+/**
+ * Whether something stands between the 3D point p and the card the way the light comes (`past` metres
+ * back along it, rising with it): the ray is walked on the depth map, and a step that goes behind a surface
+ * seen there, by less than `thick` metres, is blocked. So a shadow that climbs a booth stops on it and
+ * never shows again on the floor behind the booth.
+ */
+function blocked(d: Depth, sun: Sun, p: [number, number, number], past: number, thick = 1.2): boolean {
+  const e: [number, number, number] = [p[0] - sun.along[0] * past, p[1] - sun.along[1] * past, p[2] + past * sun.rise];
+  const [ps, es] = [toScreen(sun, p), toScreen(sun, e)];
+  if (!ps || !es) return false;
+  const n = Math.min(32, Math.max(4, Math.ceil(Math.hypot(es[0] - ps[0], es[1] - ps[1]) / (2 * DEPTH_SCALE))));
+  for (let k = 1; k < n; k++) {
+    const t = k / n;
+    // Not the point's own surface, nor the ground at the feet the card stands on.
+    if (t * past < 0.15 || (1 - t) * past < 0.3) continue;
+    const q: [number, number, number] = [p[0] + (e[0] - p[0]) * t, p[1] + (e[1] - p[1]) * t, p[2] + (e[2] - p[2]) * t];
+    const s = toScreen(sun, q);
+    if (!s) continue;
+    const surf = pointAt(d, sun, s[0], s[1]);
+    if (surf && q[1] > surf[1] + 0.1 && q[1] < surf[1] + thick) return true;
+  }
+  return false;
+}
+
+/**
+ * How much of the person's shadow falls on frame pixel (x, y), 0..1. With `on` (catchers) it lands on the
+ * things and floors, not on the backdrop. Anything standing between the pixel and the person keeps it off.
+ */
+export function shadowAt(d: Depth, sun: Sun, sil: Silhouette, x: number, y: number, on?: Uint8Array): number {
+  const p = pointAt(d, sun, x, y);
+  if (!p) return 0;
+  const [rx, rz] = [p[0] - sun.feet[0], p[1] - sun.feet[1]];
+  const catches = on ? on[Math.floor(y / DEPTH_SCALE) * d.w + Math.floor(x / DEPTH_SCALE)] : 2;
+  if (catches !== 2 && Math.hypot(rx, rz) > NEAR_M) {
+    if (!catches && Math.abs(p[2] - sun.feet[2]) > FLOOR_RISE_M) return 0;
+    const q = pointAt(d, sun, x, y - 8 * DEPTH_SCALE);
+    if (q && q[2] - p[2] > FLOOR_SLOPE * Math.hypot(q[0] - p[0], q[1] - p[1])) return 0;
+  }
+  // How far past the person this point is, the way the light goes: points before the card are lit.
+  const past = rx * sun.along[0] + rz * sun.along[1];
+  if (past <= 0.02) return 0;
+  const side = rx * sun.across[0] + rz * sun.across[1];
+  // Where on the card the ray from this point back toward the sun crosses it.
+  // Close to the feet the ground counts as level with them: the depth map is soft at a ledge, and a shadow
+  // must stay joined to the feet; farther out every step and drop shapes it.
+  const near = Math.min(1, Math.max(0, (past - CONTACT_M) / CONTACT_M));
+  const up = (p[2] - sun.feet[2]) * near * near * (3 - 2 * near) + past * sun.rise;
+  if (up < 0) return 0;
+  const sx = Math.round(sil.ox + side * sil.perM);
+  const sy = Math.round(sil.oy - up * sil.perM);
+  if (sx < 0 || sy < 0 || sx >= sil.w || sy >= sil.h) return 0;
+  const a = sil.alpha[sy * sil.w + sx] / 255;
+  return a > 0 && blocked(d, sun, p, past) ? 0 : a;
+}
+
+/**
+ * The shadows painted things (a tent, a bench) cast from a fire or a lamp standing on the floor at frame
+ * pixel `at`, its light `up` metres high and `shift` metres to the side. Worked out on the depth map: each
+ * floor point looks back along its ray to the light and lies in shadow where the ray passes behind a
+ * caster's pixels (owner, at the depth map's size), within `thick` metres of the surface seen there. Every
+ * `cell` depth pixels one value 0..1, fading out `reach` metres from the light like the light itself.
+ */
+export function thingShadows(
+  d: Depth,
+  g: Geometry,
+  owner: Uint8Array,
+  at: [number, number],
+  { up, shift = 0, cell = 2, reach = 4 * PERSON_M, thick = 1.2 }: { up: number; shift?: number; cell?: number; reach?: number; thick?: number },
+): { w: number; h: number; cell: number; alpha: Float32Array } {
+  const v = viewOf(g);
+  const S = DEPTH_SCALE;
+  const [w, h] = [Math.ceil(d.w / cell), Math.ceil(d.h / cell)];
+  const alpha = new Float32Array(w * h);
+  // The light on the floor plane under it, raised.
+  const zn = v.camH / Math.max(1, at[1] - v.hor);
+  const L: [number, number, number] = [(at[0] - v.halfW) * zn + shift, zn * v.f, up];
+  const Ls = toScreen(v, L);
+  if (!Ls) return { w, h, cell, alpha };
+  for (let r = 0; r < h; r++) for (let c = 0; c < w; c++) {
+    const [fx, fy] = [(c * cell + cell / 2) * S, (r * cell + cell / 2) * S];
+    const dc = Math.floor(fx / S);
+    const dr = Math.floor(fy / S);
+    // A caster's own pixels are drawn over its shadow anyway.
+    if (dr >= d.h || dc >= d.w || owner[dr * d.w + dc]) continue;
+    const p = pointAt(d, v, fx, fy);
+    if (!p || p[2] > up - 0.05) continue;
+    const dist = Math.hypot(L[0] - p[0], L[1] - p[1]);
+    if (dist >= reach || dist < 0.1) continue;
+    const n = Math.min(64, Math.max(6, Math.ceil(Math.hypot(Ls[0] - fx, Ls[1] - fy) / (1.5 * S))));
+    for (let k = 1; k < n; k++) {
+      const t = k / n;
+      // Not the floor point's own surface: a few cm along before anything counts.
+      if (t * dist < 0.08) continue;
+      const q: [number, number, number] = [p[0] + (L[0] - p[0]) * t, p[1] + (L[1] - p[1]) * t, p[2] + (L[2] - p[2]) * t];
+      const s = toScreen(v, q);
+      if (!s) continue;
+      const [qc, qr] = [Math.floor(s[0] / S), Math.floor(s[1] / S)];
+      if (qc < 0 || qr < 0 || qc >= d.w || qr >= d.h || !owner[qr * d.w + qc]) continue;
+      const surf = pointAt(d, v, s[0], s[1]);
+      if (surf && q[1] > surf[1] - 0.05 && q[1] < surf[1] + thick) {
+        alpha[r * w + c] = 1 - dist / reach;
+        break;
+      }
+    }
+  }
+  return { w, h, cell, alpha };
+}

package/app/src/play/sound.ts

@@ -0,0 +1,51 @@
+import type { LipSync } from './lipsync.ts';
+// What the play page gets to mix a world's sound, and the mixing rules as pure functions.
+// No Node imports: the browser bundles this file.
+
+export type SoundKind = 'music' | 'bed' | 'loop' | 'step' | 'shot';
+
+export type SoundData = {
+  /** Sound id → file (relative to the world) and how loud it sits. */
+  files: Record<string, { file: string; kind: SoundKind; level: number; slices?: Array<[number, number]> }>;
+  music?: string;
+  places: Record<string, {
+    bed?: string;
+    loops: Array<{ id: string; thing: string; level: number; when: string[] }>;
+    /** Footstep sound id per floor index (the digit in geometry.zone). */
+    zones: Array<string | null>;
+  }>;
+  /** Trigger ("take", "click", "exit:cliff-path", "use:cold-lamp", "talk", "ending") → sound id. */
+  shots: Record<string, string>;
+  /** Spoken lines (diorama voices): the text the page says → its recording. */
+  lines?: Record<string, { file: string; seconds: number; speaker?: string; lipsync?: LipSync }>;
+  /** Speaker-specific recordings; older worlds can still use lines keyed only by text. */
+  bySpeaker?: Record<string, NonNullable<SoundData['lines']>>;
+};
+
+export function spokenLine(sound: SoundData | undefined, text: string, speaker?: string) {
+  return (speaker ? sound?.bySpeaker?.[speaker]?.[text] : undefined) ?? sound?.lines?.[text];
+}
+
+/** Mixer gain per kind and level, before distance: the bed sits under loops, music under both. */
+export const BUS: Record<SoundKind, number> = { music: 0.32, bed: 0.55, loop: 0.8, step: 0.55, shot: 0.85 };
+const LEVEL = [0, 0.55, 1, 1.5];
+
+export const levelGain = (kind: SoundKind, level: number) => BUS[kind] * (LEVEL[level] ?? 1);
+
+/**
+ * Where a thing's loop sits for a hero at (hx, hy): pan from where the thing is on screen,
+ * gain falling off with distance in hero heights, never fully silent so the place still has it.
+ */
+export function placeSound(thingX: number, thingY: number, hx: number, hy: number, viewX: number, width: number, heroPx: number): { pan: number; gain: number } {
+  const pan = Math.max(-0.8, Math.min(0.8, (thingX - viewX) / (width / 2)));
+  const d = Math.hypot(thingX - hx, (thingY - hy) * 1.6) / Math.max(40, heroPx);
+  const gain = 0.2 + 0.8 / (1 + (d / 2.5) ** 2);
+  return { pan: Math.round(pan * 1000) / 1000, gain: Math.round(gain * 1000) / 1000 };
+}
+
+/** The floor index under (x, y) from geometry.zone, or -1. */
+export function zoneAt(zone: string[] | undefined, cell: number, x: number, y: number): number {
+  const row = zone?.[Math.floor(y / cell)];
+  const ch = row?.[Math.floor(x / cell)];
+  return ch && ch >= '0' && ch <= '9' ? Number(ch) : -1;
+}

package/app/src/play/weather.ts

@@ -0,0 +1,58 @@
+// weather.json: what falls on a place and where water drips, written by the weather step, read by the page.
+// Rain and snow fall over the whole frame (the "all" pseudo-mask); drops ring on water and puddles, splash on
+// the floors, and drip from the edges Spark names (eaves, a gutter, a cave ceiling).
+// No Node imports: the browser bundles this file.
+import { z } from 'zod';
+
+const XY = z.tuple([z.number(), z.number()]);
+
+export const Weather = z.object({
+  /** What falls from the sky now; none for a dry place (drips may still run, a leaking pipe in a cave). */
+  fall: z.enum(['none', 'rain', 'snow']),
+  /** 0.3 drizzle, 0.6 rain, 1 a downpour (or a blizzard). */
+  strength: z.number().min(0).max(1),
+  /** How far the fall slants: px across per px down, + to the right. */
+  wind: z.number().min(-1).max(1),
+  /** How much mist drifts over the place, 0 clear .. 1 thick fog. */
+  fog: z.number().min(0).max(1).default(0),
+  /** Edges water drips from: points along the edge, and where each drop lands (the floor row under it). */
+  drips: z.array(z.object({ phrase: z.string(), from: z.array(XY), to: z.array(z.number()) })).default([]),
+  /** Mask (relative to the place folder) of water and puddles, where drops ring. */
+  ripples: z.string().optional(),
+});
+export type Weather = z.infer<typeof Weather>;
+
+/** How the author wants a place's weather: places/<key>/weather-wish.json, set by the weather_set action, kept across rebuilds. */
+export const WeatherWish = z.object({
+  /** auto: as Spark reads the picture and the mood; otherwise this, whatever the picture says. */
+  fall: z.enum(['auto', 'none', 'rain', 'snow']).default('auto'),
+  strength: z.number().min(0).max(1).optional(),
+  /** Mist the author wants, 0..1; unset: as Spark reads it. */
+  fog: z.number().min(0).max(1).optional(),
+  /** What the author said ("water drips from the tavern sign"), handed to Spark. */
+  hint: z.string().optional(),
+});
+export type WeatherWish = z.infer<typeof WeatherWish>;
+
+/** Whether a place's words say something falls (rain, snow, a storm), so its painting leaves the fall to the page. */
+export function fallsIn(text: string): boolean {
+  return /\b(rain\w*|drizzl\w*|downpour|storm\w*|snow\w*|sleet|blizzard|shower\w*|deszcz\w*|ulew\w*|śnieg\w*|mżawk\w*)/i.test(text);
+}
+
+/** A small seeded random source (mulberry32), so a recorded run rains the same every time. */
+export function seeded(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+export function hashSeed(text: string): number {
+  let h = 2166136261;
+  for (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 16777619);
+  return h >>> 0;
+}