@gtanczyk/diorama 0.0.0-stage → 0.1.0

package/app/src/play/parallax.ts

@@ -0,0 +1,200 @@
+// Parallax: a place drawn as a real diorama, a painted backdrop and cut-out cards standing on its floor.
+// The floor is a plane, so how far a spot moves when the camera sways grows with its distance below the
+// horizon; a card moves as the floor row it stands on. No Node imports: the browser bundles this file.
+import type { Geometry, Occluder } from './geometry.ts';
+
+/** How far (px) the bottom row moves against the horizon at a full camera swing. Kept small: a diorama, not a flyby. */
+export const PARALLAX_PX = 22;
+/** Vertical swing is half the horizontal one; eyes move sideways more than up and down. */
+const VERTICAL = 0.5;
+
+export type Camera = { x: number; y: number };
+
+/** 0 at the horizon (and above it, the painted backdrop), 1 at the bottom of the frame. */
+export function disparity(g: Geometry, y: number): number {
+  const { horizonY } = g.scale;
+  const span = Math.max(1, g.frame.height - horizonY);
+  return Math.min(1.25, Math.max(0, (y - horizonY) / span));
+}
+
+/** The depth that stays put while the camera sways: the middle of the walkable floor, where the hero lives. */
+export function pivot(g: Geometry): number {
+  let sum = 0;
+  let n = 0;
+  g.walk.forEach((row, r) => {
+    for (let c = 0; c < row.length; c++) if (row[c] === '#') (sum += disparity(g, (r + 0.5) * g.cell)), n++;
+  });
+  return n ? sum / n : 0.5;
+}
+
+export type Parallax = { cam: Camera; pivot: number; px: number };
+
+/** The shift of anything standing on the floor at feetY (its own pixels all move with it). */
+export function shiftAt(g: Geometry, p: Parallax, feetY: number): [number, number] {
+  const d = disparity(g, feetY) - p.pivot;
+  return [p.cam.x * p.px * d, p.cam.y * p.px * VERTICAL * d];
+}
+
+/** The floor row a card stands on: its base, its support's for a thing on top, the frame's bottom for a framing one. */
+export function cardY(g: Geometry, occ: Occluder, byKey: (key: string) => Occluder | undefined): number {
+  if (occ.front) return g.frame.height;
+  const under = occ.on ? byKey(occ.on) : undefined;
+  return under && under !== occ ? under.baseY : occ.baseY;
+}
+
+/**
+ * The backdrop's two pieces as canvas transforms [a, b, c, d, e, f] (x' = a x + c y + e, y' = b x + d y + f):
+ * above the horizon it only slides; below, the floor shears, near rows sliding more than far ones.
+ */
+export function backdropTransforms(g: Geometry, p: Parallax): { above: number[]; below: number[] } {
+  const h = g.scale.horizonY;
+  const span = Math.max(1, g.frame.height - h);
+  const kx = (p.cam.x * p.px) / span;
+  const ky = (p.cam.y * p.px * VERTICAL) / span;
+  const [ax, ay] = [-p.cam.x * p.px * p.pivot, -p.cam.y * p.px * VERTICAL * p.pivot];
+  return { above: [1, 0, 0, 1, ax, ay], below: [1, 0, kx, 1 + ky, ax - kx * h, ay - ky * h] };
+}
+
+/** Where a point of the floor seen on screen at (x, y) lies in the painting. */
+export function floorPoint(g: Geometry, p: Parallax, x: number, y: number): [number, number] {
+  const { above, below } = backdropTransforms(g, p);
+  let py = (y - below[5]) / below[3];
+  if (py < g.scale.horizonY) py = y - above[5];
+  const [dx] = py < g.scale.horizonY ? [above[4]] : [below[2] * py + below[4]];
+  return [x - dx, py];
+}
+
+/** The zoom that keeps the frame's edges covered at a full swing in any direction. */
+export function overscan(g: Geometry, p: Parallax): number {
+  const reach = Math.max(p.pivot, disparity(g, g.frame.height) - p.pivot) * p.px;
+  return 1 + Math.max((2 * reach) / g.frame.width, (2 * reach * VERTICAL) / g.frame.height);
+}
+
+/**
+ * Where a panning camera's middle goes along one axis: `want`, moved as little as it takes to keep each span of
+ * `keep` ([from, to], the hero first, then where they walk and the thing they were sent to) inside the view, `half`
+ * either side of the middle, `margin` in from its edges, and never further than `room` from `centre`. A span that
+ * cannot fit with the ones before it is let go: the hero is kept first.
+ */
+export function panTo(want: number, centre: number, room: number, half: number, margin: number, keep: Array<[number, number]>): number {
+  let lo = centre - room;
+  let hi = centre + room;
+  for (const [a, b] of keep) {
+    const l = Math.max(lo, b - half + margin);
+    const h = Math.min(hi, a + half - margin);
+    if (l > h) continue;
+    [lo, hi] = [l, h];
+  }
+  return Math.max(lo, Math.min(hi, want));
+}
+
+/** Gaps up to this many px between stacked pieces of one thing are painted over by its card. */
+export const STACK_GAP = 48;
+
+/**
+ * Cards for a parallax place: SAM often cuts one thing into pieces stacked in the same columns (a post's
+ * cap and its foot, with the rope coil between them missed). Each such stack becomes one card, standing
+ * where its lowest piece meets the floor; `stacked` marks cards whose gaps the runtime fills in.
+ */
+export function stackCards(occluders: Occluder[]): Array<Occluder & { stacked?: boolean }> {
+  const out: Array<Occluder & { stacked?: boolean }> = occluders.map((o) => ({ ...o }));
+  const overlap = (a: Occluder, b: Occluder) => Math.min(a.box[2], b.box[2]) - Math.max(a.box[0], b.box[0]);
+  for (let merged = true; merged; ) {
+    merged = false;
+    for (const lo of out) {
+      const up = out.find((u) => u !== lo && u.thing && u.thing === lo.thing && !u.front && !lo.front && !u.on && !lo.on
+        && u.box[3] <= lo.box[1] + 4 && lo.box[1] - u.box[3] <= STACK_GAP
+        && overlap(u, lo) > 0.5 * Math.min(u.box[2] - u.box[0], lo.box[2] - lo.box[0]));
+      if (!up) continue;
+      lo.box = [Math.min(lo.box[0], up.box[0]), up.box[1], Math.max(lo.box[2], up.box[2]), lo.box[3]];
+      lo.stacked = true;
+      out.splice(out.indexOf(up), 1);
+      merged = true;
+      break;
+    }
+  }
+  return out;
+}
+
+/**
+ * Per walk-grid column, the row where the walkable floor ends at the back (smoothed). The backdrop between
+ * the horizon and that row is taken as standing upright there (a quay wall, a railing, the far side of a
+ * room), so it slides as one piece with the floor's back edge instead of leaning with the floor's shear.
+ */
+export function backEdge(g: Geometry, smooth = 7): Float32Array {
+  const cols = Math.max(...g.walk.map((r) => r.length));
+  const raw = new Float32Array(cols).fill(NaN);
+  for (let c = 0; c < cols; c++) {
+    const r = g.walk.findIndex((row) => row[c] === '#');
+    if (r >= 0) raw[c] = r * g.cell;
+  }
+  const valid = [...raw.keys()].filter((c) => !Number.isNaN(raw[c]));
+  if (!valid.length) return raw.fill(g.scale.horizonY);
+  for (let c = 0; c < cols; c++) {
+    if (!Number.isNaN(raw[c])) continue;
+    const near = valid.reduce((a, b) => (Math.abs(b - c) < Math.abs(a - c) ? b : a));
+    raw[c] = raw[near];
+  }
+  // A wide moving average: neighbouring columns must slide by nearly the same amount, or the wall tears.
+  const out = new Float32Array(cols);
+  for (let c = 0; c < cols; c++) {
+    let sum = 0;
+    let n = 0;
+    for (let d = -smooth; d <= smooth; d++) {
+      const k = Math.min(cols - 1, Math.max(0, c + d));
+      sum += raw[k];
+      n++;
+    }
+    out[c] = Math.max(g.scale.horizonY, sum / n);
+  }
+  return out;
+}
+
+/** The far view as flats: the sky (drawn still) and flats farthest first, each a cut-out at `box` in the frame. */
+export type Layers = {
+  sky: string | null;
+  flats: Array<{ file: string; box: [number, number, number, number] }>;
+  /** Water to set flowing: an opaque texture over `box` (carried past the banks), its soft mask, and which way it runs on screen (unit vector; [0, 0] still; left to right when missing). */
+  water?: { tex: string; mask: string; box: [number, number, number, number]; flow?: [number, number] };
+  /** Painted fog to set drifting: a soft copy over `box` (carried past its edges), its mask, which way (-1 left, 1 right, null with the wind) and how fast. */
+  mist?: { tex: string; mask: string; box: [number, number, number, number]; drift?: -1 | 0 | 1 | null; speed?: number };
+  /** Painted smoke to set curling: each plume a feathered copy of the painting over `box`. */
+  smoke?: Array<{ file: string; box: [number, number, number, number] }>;
+  /** Boats painted on the water (not cards), each a feathered copy of the painting over `box`, to rock on the swell. */
+  floats?: Array<{ file: string; box: [number, number, number, number] }>;
+  /** Painted waterfalls to set pouring: each a feathered copy of the fall over `box`. */
+  falls?: Array<{ file: string; box: [number, number, number, number] }>;
+  /** Painted animals as small cards to swim (in the water) or fly (in the air), and which way each faces (1 right). */
+  critters?: Array<{ file: string; box: [number, number, number, number]; medium: 'water' | 'air'; facing: 1 | -1 }>;
+  /** The painted clouds as bands (bottom first) to drift with the wind at their own speeds, cut to `clip` over `box`; `keep`: what stays put in the sky. */
+  clouds?: { box: [number, number, number, number]; clip: string; keep?: string; bands: Array<{ file: string; box: [number, number, number, number]; speed: number }> };
+};
+
+/**
+ * How far each far flat slides, as a disparity: spread evenly between the horizon (the sky, still) and the
+ * nearest upright band, so each flat sits clearly behind the next. Stage flats, not measured distances.
+ */
+export function flatDisparities(g: Geometry, edge: Float32Array, count: number): number[] {
+  const nearest = Math.max(0.2, disparity(g, Math.min(...edge)));
+  return Array.from({ length: count }, (_, k) => (0.85 * nearest * (k + 1)) / (count + 1));
+}
+
+/**
+ * The far flats left to draw once boats rock: a flat cut around the same boat as a float (most of its box
+ * inside the float's) would stay still under it, so the eye sees the painted boat stand and only a ghost
+ * of its edges move. The float carries the boat; the sky under it already has the boat painted out.
+ */
+export function flatsUnderFloats<F extends { box: [number, number, number, number] }>(
+  flats: F[], floats: Array<{ box: [number, number, number, number] }> | undefined,
+): F[] {
+  if (!floats?.length) return flats;
+  const area = (b: number[]) => Math.max(0, b[2] - b[0]) * Math.max(0, b[3] - b[1]);
+  const inside = (a: number[], b: number[]) =>
+    area([Math.max(a[0], b[0]), Math.max(a[1], b[1]), Math.min(a[2], b[2]), Math.min(a[3], b[3])]) / Math.max(1, area(a));
+  return flats.filter((f) => !floats.some((fl) => inside(f.box, fl.box) > 0.6));
+}
+
+/** The shift of something at disparity d (see shiftAt, which takes a floor row). */
+export function shiftAtDisparity(p: Parallax, d: number): [number, number] {
+  return [p.cam.x * p.px * (d - p.pivot), p.cam.y * p.px * VERTICAL * (d - p.pivot)];
+}

package/app/src/play/path.ts

@@ -0,0 +1,262 @@
+// Walking on the geometry grid: snap a click to the floor, find a route, straighten it.
+// No Node imports: the browser bundles this file.
+import type { Geometry } from './geometry.ts';
+
+export type Point = [number, number];
+
+/** Cells in from the floor's edge that count as roomy: a walk keeps this far in where the floor allows. */
+const ROOMY = 3;
+/** The extra cost of a step onto a cell 0, 1, 2... cells in from the edge. */
+const RIM_COST = [0, 2, 0.6, 0];
+
+export class WalkGrid {
+  readonly cols: number;
+  readonly rows: number;
+  readonly cell: number;
+  private open: Uint8Array;
+
+  constructor(g: Pick<Geometry, 'cell' | 'walk'>) {
+    this.cell = g.cell;
+    this.rows = g.walk.length;
+    this.cols = Math.max(...g.walk.map((r) => r.length));
+    this.open = new Uint8Array(this.cols * this.rows);
+    g.walk.forEach((row, r) => {
+      for (let c = 0; c < row.length; c++) if (row[c] === '#') this.open[r * this.cols + c] = 1;
+    });
+  }
+
+  isOpen(c: number, r: number): boolean {
+    return c >= 0 && r >= 0 && c < this.cols && r < this.rows && this.open[r * this.cols + c] === 1;
+  }
+
+  walkable(x: number, y: number): boolean {
+    return this.isOpen(Math.floor(x / this.cell), Math.floor(y / this.cell));
+  }
+
+  centre(c: number, r: number): Point {
+    return [(c + 0.5) * this.cell, (r + 0.5) * this.cell];
+  }
+
+  /** The walkable cell nearest to (x, y), as a cell centre, or the point itself when it is walkable. */
+  snap(x: number, y: number): Point | undefined {
+    if (this.walkable(x, y)) return [x, y];
+    const c0 = Math.floor(x / this.cell);
+    const r0 = Math.floor(y / this.cell);
+    const limit = Math.max(this.cols, this.rows);
+    for (let ring = 1; ring < limit; ring++) {
+      let best: Point | undefined;
+      let bestD = Infinity;
+      for (let r = r0 - ring; r <= r0 + ring; r++) {
+        for (let c = c0 - ring; c <= c0 + ring; c++) {
+          if (Math.max(Math.abs(r - r0), Math.abs(c - c0)) !== ring || !this.isOpen(c, r)) continue;
+          const [cx, cy] = this.centre(c, r);
+          const d = (cx - x) ** 2 + (cy - y) ** 2;
+          if (d < bestD) [best, bestD] = [[cx, cy], d];
+        }
+      }
+      if (best) return best;
+    }
+    return undefined;
+  }
+
+  /** True when every sample along the segment is on walkable floor. */
+  clear(a: Point, b: Point): boolean {
+    const steps = Math.ceil(Math.hypot(b[0] - a[0], b[1] - a[1]) / (this.cell / 3));
+    for (let i = 0; i <= steps; i++) {
+      const t = steps ? i / steps : 0;
+      if (!this.walkable(a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t)) return false;
+    }
+    return true;
+  }
+
+  /**
+   * Where a held direction (keys or a pad) takes a walker next, `step` long, or undefined when nothing is open that way.
+   * Straight on if the floor is clear; else it slides along the wall (the two axes, then 45 degrees either side); else,
+   * facing a gap a little to one side, it sidesteps toward the gap (up to two cells), so a doorway or a narrow way
+   * between two things lets the walker through instead of snagging on a corner.
+   */
+  steer(from: Point, dir: Point, step: number): Point | undefined {
+    const n = Math.hypot(dir[0], dir[1]);
+    if (!n) return undefined;
+    const [ux, uy] = [dir[0] / n, dir[1] / n];
+    // A walker standing just off the floor (on a cell's edge, or left there by a talk) steers from the floor beside it.
+    const at = this.walkable(...from) ? from : this.snap(...from);
+    if (!at) return undefined;
+    const to = (p: Point, vx: number, vy: number, len: number): Point => [p[0] + vx * len, p[1] + vy * len];
+    const ways: Point[] = [[ux, uy], [Math.sign(ux), 0], [0, Math.sign(uy)], [ux - uy, uy + ux], [ux + uy, uy - ux]];
+    for (const [x, y] of ways) {
+      const l = Math.hypot(x, y);
+      if (!l) continue;
+      const t = to(at, x / l, y / l, step);
+      if (this.clear(at, t)) return t;
+    }
+    // A gap to one side: the nearest sidestep from which the way ahead is clear.
+    for (let d = this.cell / 4; d <= this.cell * 2; d += this.cell / 4) {
+      for (const [px, py] of [[-uy, ux], [uy, -ux]] as Point[]) {
+        const side = to(at, px, py, d);
+        if (this.clear(at, side) && this.clear(side, to(side, ux, uy, step))) return to(at, px, py, Math.min(d, step));
+      }
+    }
+    return undefined;
+  }
+
+  private edges: Uint8Array | undefined;
+
+  /** Per cell, how many cells it is from the floor's edge (1 on the edge), up to ROOMY. */
+  private edge(): Uint8Array {
+    if (this.edges) return this.edges;
+    const out = new Uint8Array(this.cols * this.rows);
+    for (let r = 0; r < this.rows; r++) {
+      for (let c = 0; c < this.cols; c++) {
+        if (!this.isOpen(c, r)) continue;
+        let d = 1;
+        for (; d < ROOMY; d++) {
+          let shut = false;
+          for (let k = -d; k <= d && !shut; k++) shut = !this.isOpen(c + k, r - d) || !this.isOpen(c + k, r + d) || !this.isOpen(c - d, r + k) || !this.isOpen(c + d, r + k);
+          if (shut) break;
+        }
+        out[r * this.cols + c] = d;
+      }
+    }
+    return (this.edges = out);
+  }
+
+  private edgeAt(x: number, y: number): number {
+    const c = Math.floor(x / this.cell);
+    const r = Math.floor(y / this.cell);
+    return this.isOpen(c, r) ? this.edge()[r * this.cols + c] : 0;
+  }
+
+  /**
+   * True when the segment is on the floor and, but within a cell or two of `ends`, `need` cells or more in from its
+   * edge: a walk across a bridge keeps to the middle of the deck, not its rim over the water.
+   */
+  private roomyLine(a: Point, b: Point, need: number, ends: Point[]): boolean {
+    const steps = Math.ceil(Math.hypot(b[0] - a[0], b[1] - a[1]) / (this.cell / 3));
+    for (let i = 0; i <= steps; i++) {
+      const t = steps ? i / steps : 0;
+      const [x, y] = [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t];
+      const e = this.edgeAt(x, y);
+      if (!e) return false;
+      if (e < need && !ends.some(([ex, ey]) => Math.hypot(ex - x, ey - y) <= 2.5 * this.cell)) return false;
+    }
+    return true;
+  }
+
+  /**
+   * A* over 8 neighbours without cutting corners, then string-pulled. Empty when unreachable. Cells on the floor's
+   * edge cost more, so the walk keeps off the rim of a deck or a bank, and straightening keeps the room it found.
+   */
+  route(from: Point, to: Point): Point[] {
+    const a = this.snap(...from);
+    const b = this.snap(...to);
+    if (!a || !b) return [];
+    if (this.roomyLine(a, b, ROOMY, [a, b])) return [b];
+    const edge = this.edge();
+    const cols = this.cols;
+    const start = Math.floor(a[1] / this.cell) * cols + Math.floor(a[0] / this.cell);
+    const goal = Math.floor(b[1] / this.cell) * cols + Math.floor(b[0] / this.cell);
+    const g = new Float64Array(cols * this.rows).fill(Infinity);
+    const came = new Int32Array(cols * this.rows).fill(-1);
+    const closed = new Uint8Array(cols * this.rows);
+    const heap = new MinHeap();
+    const h = (i: number) => Math.hypot((i % cols) - (goal % cols), Math.floor(i / cols) - Math.floor(goal / cols));
+    g[start] = 0;
+    heap.push(start, h(start));
+    while (heap.size) {
+      const i = heap.pop();
+      if (i === goal) break;
+      if (closed[i]) continue;
+      closed[i] = 1;
+      const c = i % cols;
+      const r = Math.floor(i / cols);
+      for (let dr = -1; dr <= 1; dr++) {
+        for (let dc = -1; dc <= 1; dc++) {
+          if ((!dr && !dc) || !this.isOpen(c + dc, r + dr)) continue;
+          if (dr && dc && (!this.isOpen(c + dc, r) || !this.isOpen(c, r + dr))) continue;
+          const j = (r + dr) * cols + c + dc;
+          const cost = g[i] + (dr && dc ? Math.SQRT2 : 1) * (1 + RIM_COST[edge[j]]);
+          if (cost < g[j]) {
+            g[j] = cost;
+            came[j] = i;
+            heap.push(j, cost + h(j));
+          }
+        }
+      }
+    }
+    if (came[goal] < 0) return [];
+    const cells: Point[] = [];
+    for (let i = goal; i !== start; i = came[i]) cells.push(this.centre(i % cols, Math.floor(i / cols)));
+    cells.reverse();
+    cells[cells.length - 1] = b;
+    return this.pull(a, cells);
+  }
+
+  /** Drops every waypoint the walker can skip in a straight line that keeps as far in from the edge as the route did. */
+  private pull(from: Point, points: Point[]): Point[] {
+    const out: Point[] = [];
+    const ends = [from, points[points.length - 1]];
+    const room = points.map(([x, y]) => (ends.some(([ex, ey]) => Math.hypot(ex - x, ey - y) <= 2.5 * this.cell) ? ROOMY : this.edgeAt(x, y)));
+    let at = from;
+    let i = 0;
+    while (i < points.length) {
+      let far = i;
+      for (let j = points.length - 1; j > i; j--) {
+        let need = ROOMY;
+        for (let k = i; k <= j; k++) need = Math.min(need, room[k]);
+        if (this.roomyLine(at, points[j], need, ends)) {
+          far = j;
+          break;
+        }
+      }
+      out.push(points[far]);
+      at = points[far];
+      i = far + 1;
+    }
+    return out;
+  }
+}
+
+class MinHeap {
+  private items: number[] = [];
+  private keys: number[] = [];
+  get size() {
+    return this.items.length;
+  }
+  push(item: number, key: number) {
+    this.items.push(item);
+    this.keys.push(key);
+    let i = this.items.length - 1;
+    while (i > 0) {
+      const p = (i - 1) >> 1;
+      if (this.keys[p] <= key) break;
+      this.swap(i, p);
+      i = p;
+    }
+  }
+  pop(): number {
+    const top = this.items[0];
+    const lastItem = this.items.pop()!;
+    const lastKey = this.keys.pop()!;
+    if (this.items.length) {
+      this.items[0] = lastItem;
+      this.keys[0] = lastKey;
+      let i = 0;
+      for (;;) {
+        const l = 2 * i + 1;
+        const r = l + 1;
+        let m = i;
+        if (l < this.keys.length && this.keys[l] < this.keys[m]) m = l;
+        if (r < this.keys.length && this.keys[r] < this.keys[m]) m = r;
+        if (m === i) break;
+        this.swap(i, m);
+        i = m;
+      }
+    }
+    return top;
+  }
+  private swap(a: number, b: number) {
+    [this.items[a], this.items[b]] = [this.items[b], this.items[a]];
+    [this.keys[a], this.keys[b]] = [this.keys[b], this.keys[a]];
+  }
+}

package/app/src/play/preview.ts

@@ -0,0 +1,71 @@
+// A rough geometry.json made from layout.json alone, so a place can be walked before its masks exist.
+// Everything here is the plan, not the painting, so it is marked preview and every thing coarse.
+import type { Layout } from '../scene/layout.ts';
+import type { Place } from '../world/schema.ts';
+import type { Geometry } from './geometry.ts';
+import { WalkGrid, type Point } from './path.ts';
+
+const CELL = 8;
+
+function inside(poly: Array<[number, number]>, x: number, y: number): boolean {
+  let hit = false;
+  for (let i = 0, j = poly.length - 1; i < poly.length; j = i++) {
+    const [xi, yi] = poly[i];
+    const [xj, yj] = poly[j];
+    if (yi > y !== yj > y && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi) hit = !hit;
+  }
+  return hit;
+}
+
+/** px per y of a 1.62 m person, fitted to the things' heights with the horizon fixed. */
+function fitScale(layout: Layout): number {
+  let num = 0;
+  let den = 0;
+  for (const t of layout.things) {
+    const d = t.footY - layout.horizon;
+    if (d <= 20 || t.metres <= 0) continue;
+    const want = (t.height * 1.62) / t.metres;
+    num += want * d;
+    den += d * d;
+  }
+  const c = den ? num / den : 0.5;
+  return Math.min(4, Math.max(0.15, c));
+}
+
+export function previewGeometry(layout: Layout, place: Place, frame = { width: 1200, height: 896 }): Geometry {
+  const cols = Math.ceil(frame.width / CELL);
+  const rows = Math.ceil(frame.height / CELL);
+  const roles = new Map(place.things.map((t) => [t.key, t.role]));
+  const solid = layout.things.filter((t) => roles.get(t.key) !== 'npc');
+  const walk: string[] = [];
+  const zone: string[] = [];
+  for (let r = 0; r < rows; r++) {
+    let w = '';
+    let z = '';
+    for (let c = 0; c < cols; c++) {
+      const x = (c + 0.5) * CELL;
+      const y = (r + 0.5) * CELL;
+      const floor = layout.floors.findIndex((f) => inside(f.outline, x, y));
+      // A thing's footprint: the floor under its lower third, as deep as a third of its width.
+      const blocked = solid.some((t) => Math.abs(x - t.x) < t.width * 0.45 && y <= t.footY + 2 && y >= t.footY - Math.max(10, t.width / 3));
+      w += floor >= 0 && !blocked ? '#' : '.';
+      z += floor >= 0 ? String(floor) : '.';
+    }
+    walk.push(w);
+    zone.push(z);
+  }
+  const grid = new WalkGrid({ cell: CELL, walk });
+  const near = (x: number, y: number): Point => grid.snap(x, y) ?? [x, y];
+  const box = (t: Layout['things'][number]): [number, number, number, number] => [t.x - t.width / 2, t.footY - t.height, t.x + t.width / 2, t.footY];
+  return {
+    frame,
+    cell: CELL,
+    walk,
+    zone,
+    scale: { horizonY: layout.horizon, pxPerY: fitScale(layout), source: 'layout' },
+    start: near(frame.width / 2, frame.height - 120),
+    things: layout.things.map((t) => ({ key: t.key, role: roles.get(t.key), box: box(t), stand: near(t.x, t.footY + 14), coarse: true })),
+    occluders: solid.map((t) => ({ key: t.key, thing: t.key, box: box(t), baseY: t.footY })),
+    preview: true,
+  };
+}

package/app/src/play/reactions.ts

@@ -0,0 +1,92 @@
+// Shared, serializable reaction rules and movement triggers. No DOM, audio or model calls at play time.
+import { z } from 'zod';
+import { When } from '../story/schema.ts';
+import { holds, type State } from '../story/engine.ts';
+import type { Geometry } from './geometry.ts';
+
+export const Burst = z.object({
+  kind: z.enum(['dust', 'splash', 'snow', 'leaves', 'sparks']),
+  colour: z.string().regex(/^#[0-9a-fA-F]{6}$/),
+  strength: z.number().min(0.1).max(1),
+});
+export type Burst = z.infer<typeof Burst>;
+export const AreaRule = z.object({
+  key: z.string().min(1),
+  cells: z.array(z.string().regex(/^[.#]+$/)).min(1),
+  step: Burst.optional(),
+  enter: Burst.optional(),
+  when: When,
+  once: z.boolean().default(false),
+  cooldown: z.number().min(0.2).max(30).default(1.5),
+});
+export const Reactions = z.object({
+  version: z.literal(1),
+  source: z.string(),
+  scene: z.string(),
+  areas: z.array(AreaRule).max(8),
+  interactions: z.array(z.object({
+    key: z.string(), thing: z.string(),
+    // Exact matched story interaction, so a story edit cannot silently retarget an old effect.
+    action: z.string(),
+    at: z.tuple([z.number().min(0).max(1), z.number().min(0).max(1)]),
+    burst: Burst,
+    cooldown: z.number().min(0.2).max(30).default(1),
+  })).max(12),
+});
+export type Reactions = z.infer<typeof Reactions>;
+export type ReactionEvent = { rule: string; trigger: 'step' | 'enter' | 'interaction'; burst: Burst; x: number; y: number; depth: number; actor: object; step?: number };
+export type WalkPoint = { x: number; y: number; phase: number; foot?: number };
+
+export function inArea(area: z.infer<typeof AreaRule>, cell: number, x: number, y: number): boolean {
+  return area.cells[Math.floor(y / cell)]?.[Math.floor(x / cell)] === '#';
+}
+
+export class ReactionTriggers {
+  private clock = 0;
+  private used = new Set<string>();
+  private cooldowns = new Map<string, number>();
+  constructor(readonly rules: Reactions, readonly g: Geometry, private readonly emit: (event: ReactionEvent) => void) {}
+  update(dt: number) { this.clock += dt; }
+  reset() { this.cooldowns.clear(); }
+  private fire(rule: string, seconds: number, once: boolean, event: Omit<ReactionEvent, 'rule'>) {
+    if (this.used.has(rule) || this.clock < (this.cooldowns.get(rule) ?? -Infinity)) return;
+    if (once) this.used.add(rule);
+    this.cooldowns.set(rule, this.clock + seconds);
+    this.emit({ rule, ...event });
+  }
+  /** Called for each actually travelled path segment, including the last segment before stopping. */
+  move(actor: object, from: WalkPoint, to: WalkPoint, state: State) {
+    if (from.x === to.x && from.y === to.y) return;
+    const point = (t: number) => ({ x: from.x + (to.x - from.x) * t, y: from.y + (to.y - from.y) * t });
+    // Sample crossings more finely than the walk grid: even a small patch crossed in one frame fires.
+    const n = Math.max(1, Math.ceil(Math.hypot(to.x - from.x, to.y - from.y) / (this.g.cell / 2)));
+    for (const a of this.rules.areas) {
+      if (!holds(state, a.when)) continue;
+      if (a.enter) {
+        let inside = inArea(a, this.g.cell, from.x, from.y);
+        for (let i = 1; i <= n; i++) {
+          const p = point(i / n), next = inArea(a, this.g.cell, p.x, p.y);
+          if (next && !inside) this.fire(a.key, a.cooldown, a.once, { trigger: 'enter', burst: a.enter, ...p, depth: p.y, actor });
+          inside = next;
+        }
+      }
+      if (a.step && to.phase > from.phase) {
+        for (let step = Math.floor(from.phase * 2) + 1; step <= Math.floor(to.phase * 2); step++) {
+          const t = (step / 2 - from.phase) / (to.phase - from.phase), p = point(t);
+          if (inArea(a, this.g.cell, p.x, p.y)) this.emit({ rule: a.key, trigger: 'step', burst: a.step, step, ...p,
+            y: (from.foot ?? from.y) + ((to.foot ?? to.y) - (from.foot ?? from.y)) * t, depth: p.y, actor });
+        }
+      }
+    }
+  }
+  interact(action: string, actor: object, depth: (key: string) => number) {
+    for (const r of this.rules.interactions) {
+      if (r.action !== action) continue;
+      const thing = this.g.things.find((t) => t.key === r.thing);
+      if (!thing) continue;
+      const [x0, y0, x1, y1] = thing.box;
+      this.fire(r.key, r.cooldown, false, { trigger: 'interaction', burst: r.burst,
+        x: x0 + r.at[0] * (x1 - x0), y: y0 + r.at[1] * (y1 - y0), depth: depth(r.thing) + 8, actor });
+    }
+  }
+}