sindicate 0.4.0 → 0.6.0

package/src/systems/roadGraph.js

@@ -0,0 +1,264 @@
+// GTA-style road routing. Build a GRAPH from the RN.roads polylines once (roads are static —
+// the graph is cached on first use / the loading screen, never rebuilt), then A* a path from
+// the player to a map waypoint so the minimap and the big map can draw a route that follows
+// the actual roads. The ROUTE portion is entirely on roads (the user's rule); only two short
+// off-road STUBS leave the net — you to the nearest road, and the road to the exact pin.
+//
+// Why a real graph and not fable's vertex-weld: western's roads MEET in three ways —
+//   1. a shared vertex (the east FORK; every branch mouth the county author landed on a trunk
+//      vertex at 0.00 m),
+//   2. a proper CROSSING (the trackside service road crosses the north road at x=0, mid-segment
+//      on both — no shared vertex there),
+//   3. a near-touch T (a mouth a few metres off a trunk).
+// nodeAt() welds (1); the pairwise MEET pass below splits both segments at (2)/(3) and threads a
+// shared node through the join, so the whole net is one connected graph. And route() snaps each
+// endpoint to the nearest point ON AN EDGE (mid-segment), not merely the nearest vertex, so you
+// join the road where you actually reach it, not at the next survey peg 30 m up the line.
+//
+// Headless-safe: imports only RN.roads + roadDistance (pure data/math). scripts/verify-roadgraph.mjs
+// exercises this exact module offline.
+// the road polylines + distance oracle are GAME data: setRoadNetwork({ roads, roadDistance })
+let RN = { roads: [], roadDistance: () => 1e9 };
+export function setRoadNetwork(n) { RN = { ...RN, ...n }; }
+
+const WELD = 3;          // coincident road vertices within 3 m are one junction node
+const TOUCH = 6;         // two roads passing within 6 m MEET (a crossing or a mouth on a trunk)
+const STUB_MIN = 4;      // an off-road stub shorter than this is just standing on the road — drop it
+const FAR = 600;         // an endpoint farther than this from ANY road has no sensible road route
+const CRUISE = 9;        // m/s, a steady canter (game/horse.js gaitFor) — for the ETA readout
+
+// ── geometry helpers (no allocation in the hot path) ─────────────────────────────────────────
+// closest point on segment a→b to (px,pz); returns param t∈[0,1] and the foot's coords + sq dist.
+function segClosest(px, pz, ax, az, bx, bz) {
+  const dx = bx - ax, dz = bz - az;
+  const L2 = dx * dx + dz * dz;
+  const t = L2 ? Math.max(0, Math.min(1, ((px - ax) * dx + (pz - az) * dz) / L2)) : 0;
+  const x = ax + dx * t, z = az + dz * t;
+  const ex = px - x, ez = pz - z;
+  return { t, x, z, d2: ex * ex + ez * ez };
+}
+// proper 2D intersection of segments a→b and c→d, or null if parallel / not crossing within both.
+function segInt(ax, az, bx, bz, cx, cz, dx, dz) {
+  const rx = bx - ax, rz = bz - az, sx = dx - cx, sz = dz - cz;
+  const den = rx * sz - rz * sx;
+  if (Math.abs(den) < 1e-9) return null;               // parallel — near-touch pass handles it
+  const t = ((cx - ax) * sz - (cz - az) * sx) / den;
+  const u = ((cx - ax) * rz - (cz - az) * rx) / den;
+  if (t < 0 || t > 1 || u < 0 || u > 1) return null;
+  return { t, u, x: ax + rx * t, z: az + rz * t };
+}
+
+// ── the graph ────────────────────────────────────────────────────────────────────────────────
+let G = null;   // { nodes:[{x,z,edges:[{to,d}]}], edges:[{a,b,ax,az,bx,bz,len}] }
+// A* scratch, sized to node-count + 2 synthetic endpoints, allocated ONCE and refilled per route.
+let _g, _f, _came, _open;
+
+function build() {
+  const nodes = [];
+  const grid = new Map();                              // spatial hash for welding coincident points
+  const key = (gx, gz) => gx + ',' + gz;
+  function nodeAt(x, z) {
+    const gx = Math.round(x / WELD), gz = Math.round(z / WELD);
+    for (let i = -1; i <= 1; i++) for (let j = -1; j <= 1; j++) {
+      const arr = grid.get(key(gx + i, gz + j));
+      if (arr) for (const id of arr) { const n = nodes[id]; if ((n.x - x) ** 2 + (n.z - z) ** 2 < WELD * WELD) return id; }
+    }
+    const id = nodes.length; nodes.push({ x, z, edges: [] });
+    const k = key(gx, gz); let a = grid.get(k); if (!a) grid.set(k, (a = [])); a.push(id);
+    return id;
+  }
+
+  // Flatten RN.roads into segments (each remembers its road, so we never MEET a road with itself),
+  // then find every place two DIFFERENT roads meet and record a shared point on both segments.
+  const segs = [];   // { ri, ax,az,bx,bz, meets:[{t,x,z}] }
+  RN.roads.forEach((road, ri) => {
+    for (let i = 0; i < road.length - 1; i++)
+      segs.push({ ri, ax: road[i].x, az: road[i].z, bx: road[i + 1].x, bz: road[i + 1].z, meets: [] });
+  });
+  for (let i = 0; i < segs.length; i++) {
+    const s = segs[i];
+    const s0x = Math.min(s.ax, s.bx) - TOUCH, s1x = Math.max(s.ax, s.bx) + TOUCH;
+    const s0z = Math.min(s.az, s.bz) - TOUCH, s1z = Math.max(s.az, s.bz) + TOUCH;
+    for (let j = i + 1; j < segs.length; j++) {
+      const t = segs[j];
+      if (t.ri === s.ri) continue;                     // a road meets OTHER roads, not itself
+      if (Math.max(t.ax, t.bx) < s0x || Math.min(t.ax, t.bx) > s1x ||
+          Math.max(t.az, t.bz) < s0z || Math.min(t.az, t.bz) > s1z) continue;   // AABB reject
+      const X = segInt(s.ax, s.az, s.bx, s.bz, t.ax, t.az, t.bx, t.bz);
+      if (X) {                                         // proper crossing — the SAME point on both
+        s.meets.push({ t: X.t, x: X.x, z: X.z });
+        t.meets.push({ t: X.u, x: X.x, z: X.z });
+        continue;
+      }
+      // near-touch: the closest of the four endpoint→segment approaches. If within TOUCH, the
+      // point on the TRUNK (the projection) is the junction; both segments get it (the mouth gets
+      // it at its own endpoint param, so a ≤TOUCH connector edge threads the join).
+      const cands = [
+        { on: t, m: segClosest(s.ax, s.az, t.ax, t.az, t.bx, t.bz), et: 0, es: s },
+        { on: t, m: segClosest(s.bx, s.bz, t.ax, t.az, t.bx, t.bz), et: 1, es: s },
+        { on: s, m: segClosest(t.ax, t.az, s.ax, s.az, s.bx, s.bz), et: 0, es: t },
+        { on: s, m: segClosest(t.bx, t.bz, s.ax, s.az, s.bx, s.bz), et: 1, es: t },
+      ];
+      let best = null;
+      for (const c of cands) if (!best || c.m.d2 < best.m.d2) best = c;
+      if (best.m.d2 < TOUCH * TOUCH) {
+        best.on.meets.push({ t: best.m.t, x: best.m.x, z: best.m.z });       // on the trunk
+        best.es.meets.push({ t: best.et, x: best.m.x, z: best.m.z });        // welded at the mouth
+      }
+    }
+  }
+
+  // Turn each segment into a node chain: endpoint A, its meets in order along the segment, endpoint
+  // B. Shared meet coords resolve (via nodeAt) to one id, so the two roads connect there.
+  for (const s of segs) {
+    const pts = [{ t: 0, x: s.ax, z: s.az }, ...s.meets, { t: 1, x: s.bx, z: s.bz }];
+    pts.sort((p, q) => p.t - q.t);
+    let prev = -1;
+    for (const p of pts) {
+      const id = nodeAt(p.x, p.z);
+      if (prev >= 0 && prev !== id) {
+        const a = nodes[prev], b = nodes[id];
+        const d = Math.hypot(a.x - b.x, a.z - b.z);
+        if (d > 1e-6) { a.edges.push({ to: id, d }); b.edges.push({ to: prev, d }); }
+      }
+      prev = id;
+    }
+  }
+
+  // A flat edge list for snapping (a point can join a road mid-segment, not just at a node).
+  const edges = [];
+  for (let a = 0; a < nodes.length; a++)
+    for (const e of nodes[a].edges)
+      if (a < e.to) {
+        const n = nodes[e.to];
+        edges.push({ a, b: e.to, ax: nodes[a].x, az: nodes[a].z, bx: n.x, bz: n.z, len: e.d });
+      }
+
+  G = { nodes, edges };
+  const cap = nodes.length + 2;                        // + SRC and DST synthetic endpoints
+  _g = new Float64Array(cap); _f = new Float64Array(cap);
+  _came = new Int32Array(cap); _open = new Uint8Array(cap);
+  return G;
+}
+
+// Build (or return) the road graph. Call on the loading screen to keep the first route cheap.
+export function ensureRoadGraph() { return G || build(); }
+
+// Nearest point ON THE ROAD NETWORK to (x,z): which edge, the foot's coords, and the distance.
+function nearestEdge(x, z) {
+  let bi = -1, bt = 0, bx = 0, bz = 0, bd2 = Infinity;
+  for (let i = 0; i < G.edges.length; i++) {
+    const e = G.edges[i];
+    const c = segClosest(x, z, e.ax, e.az, e.bx, e.bz);
+    if (c.d2 < bd2) { bd2 = c.d2; bi = i; bt = c.t; bx = c.x; bz = c.z; }
+  }
+  return { ei: bi, t: bt, x: bx, z: bz, dist: Math.sqrt(bd2) };
+}
+// Public snap helper (endpoint diagnostics / a future "you are here" dot on the road).
+export function nearestRoadPoint(x, z) {
+  if (!ensureRoadGraph().edges.length) return null;
+  const s = nearestEdge(x, z);
+  return { x: s.x, z: s.z, dist: s.dist };
+}
+
+const segLen = (pts) => { let l = 0; for (let i = 1; i < pts.length; i++) l += Math.hypot(pts[i].x - pts[i - 1].x, pts[i].z - pts[i - 1].z); return l; };
+
+// ROUTE. Snap both ends onto the nearest ROAD EDGE, A* between the snap points over the graph, and
+// return the path as world points [from]→[snap-on]→road nodes→[snap-off]→[to]. Robust: an island
+// waypoint, start==end, or a disconnected pair fall back to a straight dashed line — never a throw.
+// Returns { reachable, points:[{x,z}], segments:[{pts,style}], lengthM, roadLengthM, directM, detour, etaS }.
+export function route(fx, fz, tx, tz) {
+  ensureRoadGraph();
+  const directM = Math.hypot(tx - fx, tz - fz);
+  const straight = () => ({
+    reachable: false, points: [{ x: fx, z: fz }, { x: tx, z: tz }],
+    segments: [{ pts: [{ x: fx, z: fz }, { x: tx, z: tz }], style: 'dash' }],
+    lengthM: directM, roadLengthM: 0, directM, detour: 1, etaS: directM / CRUISE,
+  });
+  if (!G.edges.length || directM < 1e-3) return straight();
+
+  const S = nearestEdge(fx, fz), T = nearestEdge(tx, tz);
+  // Deep wilderness: an end too far from any road, or a hop-to-road longer than the whole trip,
+  // makes a road route nonsense — draw the honest crow-flies line instead.
+  if (S.dist > FAR || T.dist > FAR || S.dist + T.dist > directM) return straight();
+
+  const N = G.nodes.length, SRC = N, DST = N + 1, INF = Infinity;
+  const eS = G.edges[S.ei], eT = G.edges[T.ei];
+  const dist = (px, pz, qx, qz) => Math.hypot(px - qx, pz - qz);
+  const dSu = dist(S.x, S.z, eS.ax, eS.az), dSv = dist(S.x, S.z, eS.bx, eS.bz);
+  const dTp = dist(T.x, T.z, eT.ax, eT.az), dTq = dist(T.x, T.z, eT.bx, eT.bz);
+  const sameEdge = S.ei === T.ei;
+  const posX = (i) => i === SRC ? S.x : i === DST ? T.x : G.nodes[i].x;
+  const posZ = (i) => i === SRC ? S.z : i === DST ? T.z : G.nodes[i].z;
+  const h = (i) => Math.hypot(posX(i) - T.x, posZ(i) - T.z);
+
+  _g.fill(INF, 0, N + 2); _f.fill(INF, 0, N + 2); _came.fill(-1, 0, N + 2); _open.fill(0, 0, N + 2);
+  _g[SRC] = 0; _f[SRC] = h(SRC); _open[SRC] = 1;
+  let openCount = 1;
+  // synthetic adjacency: SRC → the two ends of its edge (and straight to DST if on the same edge);
+  // reaching either end of the target edge → DST. Base nodes use their own edge lists.
+  const relax = (cur, to, w) => {
+    const t = _g[cur] + w;
+    if (t < _g[to]) { _came[to] = cur; _g[to] = t; _f[to] = t + h(to); if (!_open[to]) { _open[to] = 1; openCount++; } }
+  };
+  while (openCount) {
+    let cur = -1, cf = INF;
+    for (let i = 0; i < N + 2; i++) if (_open[i] && _f[i] < cf) { cf = _f[i]; cur = i; }
+    if (cur < 0) break;
+    if (cur === DST) break;
+    _open[cur] = 0; openCount--;
+    if (cur === SRC) {
+      relax(SRC, eS.a, dSu); relax(SRC, eS.b, dSv);
+      if (sameEdge) relax(SRC, DST, dist(S.x, S.z, T.x, T.z));
+    } else {
+      for (const e of G.nodes[cur].edges) relax(cur, e.to, e.d);
+      if (cur === eT.a) relax(cur, DST, dTp);
+      if (cur === eT.b) relax(cur, DST, dTq);
+    }
+  }
+  if (_came[DST] < 0) return straight();                // graph disconnected between the two ends
+
+  // Reconstruct SRC→DST. SRC is the snap-on point, DST the snap-off point, base ids are road nodes.
+  const chain = [];
+  for (let c = DST; c >= 0; c = _came[c]) chain.push(c);
+  chain.reverse();
+  const road = chain.map((i) => ({ x: posX(i), z: posZ(i) }));   // [snap-on, road…, snap-off]
+
+  const points = [];
+  const push = (p) => { const l = points[points.length - 1]; if (!l || Math.hypot(l.x - p.x, l.z - p.z) > 1e-6) points.push(p); };
+  push({ x: fx, z: fz });
+  for (const p of road) push(p);
+  push({ x: tx, z: tz });
+
+  const segments = [];
+  const onFirst = road[0], onLast = road[road.length - 1];
+  if (Math.hypot(onFirst.x - fx, onFirst.z - fz) > STUB_MIN) segments.push({ pts: [{ x: fx, z: fz }, onFirst], style: 'dash' });
+  segments.push({ pts: road, style: 'solid' });
+  if (Math.hypot(onLast.x - tx, onLast.z - tz) > STUB_MIN) segments.push({ pts: [onLast, { x: tx, z: tz }], style: 'dash' });
+
+  const roadLengthM = segLen(road);
+  const lengthM = segments.reduce((l, s) => l + segLen(s.pts), 0);
+  // A road route that more than triples the crow-flies trip isn't helping — give the straight line.
+  if (lengthM > directM * 3 + 1) return straight();
+  return { reachable: true, points, segments, lengthM, roadLengthM, directM, detour: lengthM / Math.max(1e-6, directM), etaS: lengthM / CRUISE };
+}
+
+// Alias so a fable-derived drawer can call routeTo() unchanged.
+export const routeTo = route;
+
+// Distance from a point to the drawn route — the deviation check (re-route when the player strays
+// off the suggested road). Nearest approach to any segment of the route.
+export function distToRoute(r, x, z) {
+  if (!r?.segments) return Infinity;
+  let best = Infinity;
+  for (const seg of r.segments)
+    for (let i = 1; i < seg.pts.length; i++) {
+      const a = seg.pts[i - 1], b = seg.pts[i];
+      const c = segClosest(x, z, a.x, a.z, b.x, b.z);
+      if (c.d2 < best) best = c.d2;
+    }
+  return Math.sqrt(best);
+}
+
+// Re-export so callers verifying "is this point on a road" don't reach past this module.
+export const roadDistance = (...a) => RN.roadDistance(...a);