sindicate 0.11.0 → 0.13.0

package/src/world/bridgeSplice.js

@@ -0,0 +1,176 @@
+// THE BRIDGE SPLICER (world splits, step 3) — every road x river crossing becomes a deck.
+// Moved verbatim from the games (their copies were byte-identical except two spacing
+// numbers, parameterized below): find crossings, drop hits an existing deck already
+// carries, dedupe widest-first, then splice the road STRAIGHT across the channel on a
+// perpendicular chord — clear-bank anchors, collinear approach legs, rejoin points walked
+// along the old road, chord mids at chordStep, long legs re-densified under legGate. Runs
+// to a FIXED POINT (a splice can create a new crossing), then pushes any surviving road
+// vertex out of the water to the near bank.
+//
+// MUTATES `roads` IN PLACE — call it before anything snapshots them (chunk indices, road
+// benches, registrations: the same import-order law both counties already live by).
+// Returns the BRIDGE_SPOTS array: { ax, az, bx, bz, x, z, w } chord anchors + centre +
+// local channel half-width; the games' bridge builders and deck holds read it from there.
+//
+// chordStep/legGate: western runs 28/30 (the travellers' ≤30 m route-leg law — see its
+// verify-travellers note); fable runs 36/40 (its minimap's 74 m window). Inserted points
+// are collinear on the chord, so roadDistance, the paint and the terrain are bit-identical
+// under either spacing — only where the walkers get their waypoints changes.
+// Headless by law: no imports at all.
+
+function segInt(a, b, c, d) { // 2D segment intersection → {x,z,t (road param),u (river param)}
+  const rx = b.x - a.x, rz = b.z - a.z, sx = d.x - c.x, sz = d.z - c.z;
+  const denom = rx * sz - rz * sx;
+  if (Math.abs(denom) < 1e-9) return null;
+  const t = ((c.x - a.x) * sz - (c.z - a.z) * sx) / denom;
+  const u = ((c.x - a.x) * rz - (c.z - a.z) * rx) / denom;
+  if (t < 0 || t > 1 || u < 0 || u > 1) return null;
+  return { x: a.x + rx * t, z: a.z + rz * t, t, u };
+}
+
+function walkRoad(road, i, t, dist) { // walk `dist` m along the polyline → {x,z,seg,clamped}
+  let seg = i, tt = t, remaining = Math.abs(dist), clamped = false;
+  const dir = Math.sign(dist) || 1;
+  while (remaining > 0) {
+    const a = road[seg], b = road[seg + 1];
+    if (!a || !b) break;
+    const len = Math.hypot(b.x - a.x, b.z - a.z) || 1e-6;
+    const along = dir > 0 ? (1 - tt) * len : tt * len;
+    if (along >= remaining) { tt += dir * (remaining / len); break; }
+    remaining -= along;
+    seg += dir; tt = dir > 0 ? 0 : 1;
+    if (seg < 0 || seg >= road.length - 1) { seg = Math.max(0, Math.min(road.length - 2, seg)); tt = dir > 0 ? 1 : 0; clamped = true; break; }
+  }
+  const a = road[seg], b = road[seg + 1];
+  return { x: a.x + (b.x - a.x) * tt, z: a.z + (b.z - a.z) * tt, seg, clamped };
+}
+
+export function spliceBridges(roads, rivers, { chordStep = 28, legGate = 30, approach = 14, margin = 5, pushClear = 6 } = {}) {
+  // metres of dry margin OUTSIDE the nearest river channel (negative = inside the water).
+  const riverClearance = (x, z) => {
+    let best = Infinity;
+    for (const R of rivers) {
+      for (let i = 0; i < R.pts.length - 1; i++) {
+        const a = R.pts[i], b = R.pts[i + 1];
+        const dx = b.x - a.x, dz = b.z - a.z;
+        const len2 = dx * dx + dz * dz || 1e-9;
+        let t = ((x - a.x) * dx + (z - a.z) * dz) / len2;
+        t = t < 0 ? 0 : t > 1 ? 1 : t;
+        const d = Math.hypot(x - (a.x + dx * t), z - (a.z + dz * t));
+        const ww = R.ww[i] + (R.ww[Math.min(i + 1, R.ww.length - 1)] - R.ww[i]) * t;
+        best = Math.min(best, d - ww);
+      }
+    }
+    return best;
+  };
+
+  const BRIDGE_SPOTS = [];
+  const deckVerts = new Set();
+  for (let pass = 0; pass < 4; pass++) {
+    const hits = [];
+    roads.forEach((road, ri) => {
+      for (let i = 0; i < road.length - 1; i++)
+        for (const R of rivers)
+          for (let j = 0; j < R.pts.length - 1; j++) {
+            const h = segInt(road[i], road[i + 1], R.pts[j], R.pts[j + 1]);
+            if (h) hits.push({ ...h, ri, i, w: R.ww[j] + (R.ww[Math.min(j + 1, R.ww.length - 1)] - R.ww[j]) * h.u });
+          }
+    });
+    const carried = (h) => BRIDGE_SPOTS.some((s) => {
+      const dx = s.bx - s.ax, dz = s.bz - s.az, l2 = dx * dx + dz * dz || 1e-9;
+      let t = ((h.x - s.ax) * dx + (h.z - s.az) * dz) / l2; t = t < 0 ? 0 : t > 1 ? 1 : t;
+      return Math.hypot(h.x - (s.ax + dx * t), h.z - (s.az + dz * t)) < 8;
+    });
+    hits.sort((a, b) => b.w - a.w);
+    const keep = [];
+    for (const h of hits) if (!carried(h) && !keep.some((k) => Math.hypot(k.x - h.x, k.z - h.z) < Math.max(24, k.w * 1.6))) keep.push(h);
+    if (!keep.length) break; // fixed point — every crossing is bridged
+    keep.sort((a, b) => (b.ri - a.ri) || (b.i - a.i));
+    const splicedFrom = new Map();
+    for (const h of keep) {
+      const road = roads[h.ri];
+      const bound = splicedFrom.get(h.ri) ?? road.length;
+      if (h.i + 1 >= bound) continue;
+      let rv = { x: 1, z: 0 }, bd = Infinity;
+      for (const R of rivers) for (let i = 0; i < R.pts.length - 1; i++) {
+        const a = R.pts[i], b = R.pts[i + 1];
+        const dx = b.x - a.x, dz = b.z - a.z, len2 = dx * dx + dz * dz || 1e-9;
+        let t = ((h.x - a.x) * dx + (h.z - a.z) * dz) / len2; t = t < 0 ? 0 : t > 1 ? 1 : t;
+        const d = Math.hypot(h.x - (a.x + dx * t), h.z - (a.z + dz * t));
+        if (d < bd) { bd = d; const l = Math.hypot(dx, dz) || 1e-9; rv = { x: dx / l, z: dz / l }; }
+      }
+      let px = -rv.z, pz = rv.x;
+      const rd = { x: road[h.i + 1].x - road[h.i].x, z: road[h.i + 1].z - road[h.i].z };
+      if (px * rd.x + pz * rd.z < 0) { px = -px; pz = -pz; }
+      const clearOut = (sgn) => {
+        const cap = h.w + (h.w > 7 ? 80 : 24);
+        let d = h.w + margin;
+        while (d < cap && riverClearance(h.x + sgn * px * d, h.z + sgn * pz * d) < margin) d += 2;
+        return d < cap ? d : h.w + margin;
+      };
+      const dA = clearOut(-1), dB = clearOut(1);
+      const iA = { x: h.x - px * dA, z: h.z - pz * dA }, iB = { x: h.x + px * dB, z: h.z + pz * dB };
+      const aA = { x: iA.x - px * approach, z: iA.z - pz * approach };
+      const aB = { x: iB.x + px * approach, z: iB.z + pz * approach };
+      const rejoin = (sgn, ref) => {
+        const base = (sgn < 0 ? dA : dB) + approach + 12;
+        let P = null;
+        for (let d = base; d <= base + 60; d += 4) {
+          P = walkRoad(road, h.i, h.t, sgn * d);
+          if (P.clamped || ((P.x - ref.x) * px + (P.z - ref.z) * pz) * sgn >= 4) return P;
+        }
+        return P;
+      };
+      const A = rejoin(-1, aA), B = rejoin(1, aB);
+      if (A.clamped && B.clamped) continue;
+      let to = B.clamped ? road.length - 1 : B.seg;
+      const from = A.clamped ? 0 : A.seg + 1;
+      const joinB = to >= bound;
+      if (joinB) to = bound - 1;
+      if (to < from - 1) continue;
+      const start = A.clamped ? iA : aA, end = B.clamped ? iB : aB;
+      const ins = [];
+      if (!A.clamped && Math.hypot(A.x - start.x, A.z - start.z) > 0.01) ins.push({ x: A.x, z: A.z });
+      ins.push(start);
+      const runL = Math.hypot(end.x - start.x, end.z - start.z);
+      for (let d = chordStep; d < runL - 4; d += chordStep) {
+        const mid = { x: start.x + px * d, z: start.z + pz * d };
+        ins.push(mid); deckVerts.add(mid);
+      }
+      ins.push(end);
+      if (!B.clamped && !joinB && Math.hypot(B.x - end.x, B.z - end.z) > 0.01) ins.push({ x: B.x, z: B.z });
+      for (let k = ins.length - 1; k > 0; k--) {
+        const p = ins[k - 1], q = ins[k];
+        const L = Math.hypot(q.x - p.x, q.z - p.z);
+        if (L > legGate) {
+          const n = Math.ceil(L / chordStep), legMids = [];
+          for (let s = 1; s < n; s++) legMids.push({ x: p.x + (q.x - p.x) * s / n, z: p.z + (q.z - p.z) * s / n });
+          ins.splice(k, 0, ...legMids);
+        }
+      }
+      road.splice(from, to - from + 1, ...ins);
+      splicedFrom.set(h.ri, from);
+      deckVerts.add(start); deckVerts.add(end);
+      BRIDGE_SPOTS.push({ ax: iA.x, az: iA.z, bx: iB.x, bz: iB.z, x: (iA.x + iB.x) / 2, z: (iA.z + iB.z) / 2, w: h.w });
+    }
+  }
+  // Final pass: any road vertex still INSIDE a channel is pushed to the near bank.
+  for (const road of roads) for (const v of road) {
+    if (deckVerts.has(v)) continue;
+    let best = Infinity, nx = 0, nz = 0;
+    for (const R of rivers) for (let i = 0; i < R.pts.length - 1; i++) {
+      const a = R.pts[i], b = R.pts[i + 1];
+      const dx = b.x - a.x, dz = b.z - a.z, len2 = dx * dx + dz * dz || 1e-9;
+      let t = ((v.x - a.x) * dx + (v.z - a.z) * dz) / len2; t = t < 0 ? 0 : t > 1 ? 1 : t;
+      const cxp = a.x + dx * t, czp = a.z + dz * t;
+      const d = Math.hypot(v.x - cxp, v.z - czp);
+      const ww = R.ww[i] + (R.ww[Math.min(i + 1, R.ww.length - 1)] - R.ww[i]) * t;
+      if (d - ww < best) { best = d - ww; nx = cxp; nz = czp; }
+    }
+    if (best >= pushClear) continue;
+    const d = Math.hypot(v.x - nx, v.z - nz) || 1e-6;
+    const k = (pushClear - best) / d;
+    v.x += (v.x - nx) * k; v.z += (v.z - nz) * k;
+  }
+  return BRIDGE_SPOTS;
+}

package/src/world/geo.js

@@ -0,0 +1,53 @@
+// THE GEO TOOLKIT (world splits, step 1) — the terrain-math primitives both games carried
+// as byte-identical private copies: the fbm/ridged noise kit (fixed ImprovedNoise
+// permutation → deterministic, one shared instance is safe), the smoothstep/terrace
+// shapers, and the point-to-segment distance the polyline indices are built on.
+//
+// HEADLESS BY LAW: this module imports ONLY three/addons math — never three/webgpu —
+// because the games' terrainData files (its consumers) run in Node for offline solvers,
+// verify scripts and height-equivalence probes. Keep it that way.
+//
+// EQUIVALENCE CONTRACT: these bodies moved verbatim from western/fable terrainData.js.
+// Any numeric change here changes both counties' ground — prove a refactor with the
+// height-grid probe (441 samples per game) before shipping it.
+import { ImprovedNoise } from 'three/addons/math/ImprovedNoise.js';
+
+const noise = new ImprovedNoise();
+
+export function fbm(x, z, octaves = 4, lacunarity = 2, gain = 0.5, scale = 0.01) {
+  let amp = 1, freq = scale, sum = 0, norm = 0;
+  for (let i = 0; i < octaves; i++) {
+    sum += amp * noise.noise(x * freq, z * freq, 7.31 + i * 13.7);
+    norm += amp; amp *= gain; freq *= lacunarity;
+  }
+  return sum / norm;
+}
+
+export const clamp = (v, a, b) => Math.min(b, Math.max(a, v));
+export const lerp = (a, b, t) => a + (b - a) * t;
+export function smoothstep(a, b, t) { const x = clamp((t - a) / (b - a), 0, 1); return x * x * (3 - 2 * x); }
+
+// ~[0,1]: sharp crests, round valleys — mountain ranges and mesa fields
+export function ridged(x, z, octaves, lac, gain, scale) {
+  let amp = 0.5, freq = scale, sum = 0, norm = 0, prev = 1;
+  for (let i = 0; i < octaves; i++) {
+    let n = 1 - Math.abs(noise.noise(x * freq, z * freq, 41.7 + i * 7.3));
+    n *= n; n *= prev; sum += n * amp; norm += amp; prev = n; amp *= gain; freq *= lac;
+  }
+  return sum / norm;
+}
+
+// quantise to benches with a sharp riser — mesa walls, cliff bands
+export function terrace(h, step, sharp) {
+  const f = h / step, k = Math.floor(f), frac = f - k;
+  return (k + lerp(frac, smoothstep(0.5 - 0.5 * sharp, 0.5 + 0.5 * sharp, frac), sharp)) * step;
+}
+
+// distance from (px,pz) to segment a→b — the primitive under every polyline index
+export function segDist(px, pz, ax, az, bx, bz) {
+  const dx = bx - ax, dz = bz - az;
+  const len2 = dx * dx + dz * dz;
+  let t = len2 ? ((px - ax) * dx + (pz - az) * dz) / len2 : 0;
+  t = clamp(t, 0, 1);
+  return Math.hypot(px - (ax + dx * t), pz - (az + dz * t));
+}

package/src/world/railFormation.js

@@ -0,0 +1,185 @@
+// THE RAIL FORMATION SOLVER (world splits, step 2) — the embankment IS the terrain.
+// Moved verbatim from western's terrainData: the navvy's algorithm that turns a centreline
+// over raw ground into a buildable formation, and the corridor index heightAt interrogates
+// 1.74M times per cold cook. Everything here is PURE MACHINERY — the county supplies the
+// nodes, the surveyed ground, the ruling grade and the weave (its applyRail composition
+// stays game-side, where the river guard and road bench live).
+//
+// HOW A LINE IS SOLVED, at every node of the centreline (~1 m apart):
+//   1. the game SURVEYS the ground into g[] (its own choice of surface — pads in, benches out)
+//   2. LEVEL THE YARDS — each contiguous `flat` run pulled to its own mean
+//   3. THE RULING GRADE — ceil/floor Lipschitz envelopes at maxGrade; their midpoint splits
+//      every obstacle evenly between a cutting and an embankment
+//   4. VERTICAL CURVES — a diffusion pass is a curve and cannot break the ruling grade
+//   5. optional WELD onto an already-solved line (one bed through the turnout, no seam)
+//   6. e[] — earthworks weight: 1 = full bench, 0 = past fillMax, flying on a trestle
+//
+// HEADLESS BY LAW, like geo.js: no three imports at all.
+import { clamp, lerp, smoothstep } from './geo.js';
+
+// Nearest point on a solved line: how far, and how high the formation is there.
+export function nearestOnLine(nodes, Y, x, z) {
+  let bd = Infinity, by = 0;
+  for (let i = 0; i < nodes.length - 1; i++) {
+    const a = nodes[i], b = nodes[i + 1];
+    const dx = b.x - a.x, dz = b.z - a.z, len2 = dx * dx + dz * dz || 1e-9;
+    const t = clamp(((x - a.x) * dx + (z - a.z) * dz) / len2, 0, 1);
+    const d = Math.hypot(x - (a.x + dx * t), z - (a.z + dz * t));
+    if (d < bd) { bd = d; by = lerp(Y[i], Y[i + 1], t); }
+  }
+  return { d: bd, y: by };
+}
+
+// nodes: [{x, z, s, w, flat}] — s = arc length, w = bed half-width, flat = yard node.
+// g: Float64Array of surveyed ground per node (the game samples its own surface).
+// mergeWith: { nodes, y } of an already-solved line to weld through the shared bed.
+// Returns { y, g, e }.
+export function solveFormation(nodes, g, { maxGrade, smooth = 90, mergeIn = 7, mergeOut = 32, fillMax, mergeWith = null }) {
+  const n = nodes.length;
+  g = Float64Array.from(g);
+
+  // ONE BED THROUGH THE TURNOUT: where this line is still in the other's bed, the ground
+  // it is surveyed on IS the other line's formation.
+  if (mergeWith) {
+    for (let i = 0; i < n; i++) {
+      const m = nearestOnLine(mergeWith.nodes, mergeWith.y, nodes[i].x, nodes[i].z);
+      g[i] = lerp(m.y, g[i], smoothstep(mergeIn, mergeOut, m.d));
+    }
+  }
+
+  // LEVEL THE YARDS — each contiguous run of `flat` nodes pulled to its own mean.
+  for (let i = 0; i < n; i++) {
+    if (!nodes[i].flat) continue;
+    let j = i; while (j < n && nodes[j].flat) j++;
+    let sum = 0; for (let k = i; k < j; k++) sum += g[k];
+    const mean = sum / (j - i);
+    for (let k = i; k < j; k++) g[k] = mean;
+    i = j;
+  }
+
+  // THE RULING GRADE — the two Lipschitz envelopes, and their midpoint.
+  const ceil = Float64Array.from(g), floor = Float64Array.from(g);
+  for (let i = 1; i < n; i++) {
+    const d = maxGrade * (nodes[i].s - nodes[i - 1].s);
+    ceil[i] = Math.max(ceil[i], ceil[i - 1] - d);      // may only FALL at the ruling grade
+    floor[i] = Math.min(floor[i], floor[i - 1] + d);   // may only RISE at it
+  }
+  for (let i = n - 2; i >= 0; i--) {
+    const d = maxGrade * (nodes[i + 1].s - nodes[i].s);
+    ceil[i] = Math.max(ceil[i], ceil[i + 1] - d);
+    floor[i] = Math.min(floor[i], floor[i + 1] + d);
+  }
+  const y = new Float64Array(n);
+  for (let i = 0; i < n; i++) y[i] = 0.5 * (ceil[i] + floor[i]);
+
+  // THE VERTICAL CURVES.
+  const tmp = new Float64Array(n);
+  for (let p = 0; p < smooth; p++) {
+    tmp.set(y);
+    for (let i = 1; i < n - 1; i++) y[i] = 0.25 * tmp[i - 1] + 0.5 * tmp[i] + 0.25 * tmp[i + 1];
+  }
+
+  // …and weld the result back onto the line it left — bit-identical through the shared bed.
+  if (mergeWith) {
+    for (let i = 0; i < n; i++) {
+      const m = nearestOnLine(mergeWith.nodes, mergeWith.y, nodes[i].x, nodes[i].z);
+      y[i] = lerp(m.y, y[i], smoothstep(mergeIn, mergeOut, m.d));
+    }
+  }
+
+  // HOW MUCH EARTH TO MOVE. Past fillMax the bank would be a wall — stop building and fly.
+  const e = new Float64Array(n);
+  for (let i = 0; i < n; i++) e[i] = 1 - smoothstep(fillMax, fillMax + 1.5, y[i] - g[i]);
+  return { y, g, e };
+}
+
+// THE CORRIDOR INDEX — chunked AABBs per line plus ONE box round the whole railway, because
+// the county is huge, the railway is a ribbon, and the common answer must cost four compares.
+// lines: { name: { nodes, y, e } }. Returns { railInfo, railDistance, records } — records is
+// the fixed scratch array (one record per line, rewritten in place, zero allocation per call)
+// the game's own corridor blend iterates.
+export function makeRailIndex(lines, { near, chunk = 32 } = {}) {
+  const chunks = [];
+  const box = { minX: Infinity, maxX: -Infinity, minZ: Infinity, maxZ: -Infinity };
+  const rl = {};
+  for (const name of Object.keys(lines)) {
+    rl[name] = { d: Infinity, y: 0, w: 0, e: 1 };
+    const { nodes: N, y: Y, e: E } = lines[name];
+    for (let i = 0; i < N.length - 1; i += chunk) {
+      const end = Math.min(i + chunk, N.length - 1);
+      let minX = Infinity, maxX = -Infinity, minZ = Infinity, maxZ = -Infinity;
+      for (let j = i; j <= end; j++) {
+        const p = N[j];
+        if (p.x < minX) minX = p.x; if (p.x > maxX) maxX = p.x;
+        if (p.z < minZ) minZ = p.z; if (p.z > maxZ) maxZ = p.z;
+      }
+      chunks.push({ name, N, Y, E, i0: i, i1: end, minX: minX - near, maxX: maxX + near, minZ: minZ - near, maxZ: maxZ + near });
+      box.minX = Math.min(box.minX, minX - near); box.maxX = Math.max(box.maxX, maxX + near);
+      box.minZ = Math.min(box.minZ, minZ - near); box.maxZ = Math.max(box.maxZ, maxZ + near);
+    }
+  }
+  const records = Object.values(rl);
+
+  function railInfo(x, z) {
+    for (const r of records) r.d = Infinity;
+    if (x < box.minX || x > box.maxX || z < box.minZ || z > box.maxZ) return rl;
+    for (const c of chunks) {
+      if (x < c.minX || x > c.maxX || z < c.minZ || z > c.maxZ) continue;
+      const R = rl[c.name], N = c.N, Y = c.Y, E = c.E;
+      for (let i = c.i0; i < c.i1; i++) {
+        const a = N[i], b = N[i + 1];
+        const dx = b.x - a.x, dz = b.z - a.z, len2 = dx * dx + dz * dz || 1e-9;
+        const t = clamp(((x - a.x) * dx + (z - a.z) * dz) / len2, 0, 1);
+        const d = Math.hypot(x - (a.x + dx * t), z - (a.z + dz * t));
+        if (d < R.d) {
+          R.d = d;
+          R.y = lerp(Y[i], Y[i + 1], t);
+          R.w = lerp(a.w, b.w, t);
+          R.e = lerp(E[i], E[i + 1], t);
+        }
+      }
+    }
+    return rl;
+  }
+
+  function railDistance(x, z) {
+    const r = railInfo(x, z);
+    let d = Infinity;
+    for (const name in r) if (r[name].d < d) d = r[name].d;
+    return d;
+  }
+
+  return { railInfo, railDistance, records };
+}
+
+// WHERE THE ROADS CROSS THE RAILS — found, not assumed: every road segment against every
+// rail segment. Returns [{x, z, y, tx, tz}] with y = the formation there and (tx,tz) the
+// rail's unit tangent (the axis the deck is measured along).
+export function findCrossings(roads, lines, { minSpacing = 30 } = {}) {
+  const xings = [];
+  const hit = (a, b, c, d) => {
+    const rx = b.x - a.x, rz = b.z - a.z, sx = d.x - c.x, sz = d.z - c.z;
+    const den = rx * sz - rz * sx;
+    if (Math.abs(den) < 1e-9) return null;
+    const t = ((c.x - a.x) * sz - (c.z - a.z) * sx) / den;
+    const u = ((c.x - a.x) * rz - (c.z - a.z) * rx) / den;
+    if (t < 0 || t > 1 || u < 0 || u > 1) return null;
+    return { x: a.x + rx * t, z: a.z + rz * t };
+  };
+  for (const road of roads) {
+    for (let i = 0; i < road.length - 1; i++) {
+      for (const name of Object.keys(lines)) {
+        const { nodes: N, y: Y } = lines[name];
+        for (let j = 0; j < N.length - 1; j++) {
+          const p = hit(road[i], road[i + 1], N[j], N[j + 1]);
+          if (p && !xings.some((q) => Math.hypot(q.x - p.x, q.z - p.z) < minSpacing)) {
+            const tx0 = N[j + 1].x - N[j].x, tz0 = N[j + 1].z - N[j].z;
+            const tl = Math.hypot(tx0, tz0) || 1;
+            xings.push({ x: p.x, z: p.z, y: nearestOnLine(N, Y, p.x, p.z).y, tx: tx0 / tl, tz: tz0 / tl });
+          }
+        }
+      }
+    }
+  }
+  return xings;
+}