sindicate 0.2.0 → 0.4.0

package/src/systems/pathFollow.js

@@ -0,0 +1,107 @@
+// pathFollow.js — the piece the ROAD travellers were missing.
+//
+// Enemies (enemy.js) and town wanderers (npc.js) already route AROUND static obstacles: they ask the
+// baked grid A* in nav.js for a path and follow its waypoints, with the whisker layer (entity.js
+// walkDir) only handling DYNAMIC dodging on top. The men and women OUT ON THE ROADS — travellers on
+// foot and the horsemen — never got wired to that A*. They aimed straight at the next road point and
+// let the whiskers swerve, which is a few metres of reactive side-step: fine for a person crossing the
+// street, useless against a fence PANEL that runs twenty metres. So a horseman met a paddock rail
+// leaving Dustwater, the whiskers could not find a way round a wall that long, and he rode into it and
+// kept riding into it (mountedTraveller had no give-up at all). Nick: "he keeps trying to ride through
+// it instead of turning to find a better route."
+//
+// This module is the shared bridge to the EXISTING grid A*, for both riders. It is deliberately small:
+//   steerCarrot  LOS-gate + follow. When the straight line to the goal is clear (the common case,
+//                every metre of open road), it does nothing and the caller aims straight — zero cost,
+//                identical behaviour. Only when the grid says the line is BLOCKED by static geometry
+//                does it hold an A* path around it and hand back a look-ahead "carrot" to steer at.
+//   mountedTurn  pure-pursuit turn with a real MINIMUM TURN RADIUS. The horse's TURN_RATE had no cap,
+//                so a boxed-in animal spun on the spot and snapped straight back into the rail; a
+//                wmax = speed/Rmin gives it an arc it has to follow, so it curves out and round.
+//
+// It allocates nothing in the hot path: module scratch objects, and the A* path array is only rebuilt
+// on a throttled re-path (nav.js reuses its own scratch inside path()).
+import { dist2D } from '../core/utils.js';
+
+const clamp = (v, a, b) => Math.max(a, Math.min(b, v));
+const _f = { x: 0, z: 0 }, _t = { x: 0, z: 0 };   // scratch endpoints handed to the nav queries
+
+export function angleDelta(a, b) { let d = a - b; while (d > Math.PI) d -= 2 * Math.PI; while (d < -Math.PI) d += 2 * Math.PI; return d; }
+
+// The nearer of a route's two ENDS. Both ends of every route are a settlement (data/travellers.js), so
+// this is the settlement whose baked grid should serve the traveller while he is near it — and it is
+// the same 80 m tile that settlement's own wanderers keyed their grid on, so the grid is SHARED, not
+// baked twice. Out in the middle of the road it is far from both ends and nav returns null → straight.
+export function nearestEndpoint(road, x, z) {
+  const a = road[0], b = road[road.length - 1];
+  return dist2D(x, z, a.x, a.z) <= dist2D(x, z, b.x, b.z) ? a : b;
+}
+
+// LOS-gated A* follow. Writes the point to aim at into `out` and returns true when it is steering along
+// a path (out ≠ the raw goal); returns false when the way is clear or ungridded and the caller should
+// aim straight at the goal itself. Path state lives on `s` under _rt* so it never collides with the
+// Character._navPath the wanderers/enemies use.
+//
+//   s        the traveller (any object — foot NPC or the MountedTraveller); holds _rtPath/_rtI/…
+//   centre   nearestEndpoint(): which settlement grid to use when no baked one already covers us
+//   cx,cz    where the agent is now       gx,gz  the raw goal (the lane target on the road)
+//   out      {x,z} written with the aim point
+//   opt.dt   frame time (throttles re-paths)   opt.arrive  waypoint-reached radius
+//   opt.lookahead  carrot distance ahead along the path (0 = aim at the current waypoint; horses use >0)
+export function steerCarrot(s, game, centre, cx, cz, gx, gz, out, opt = {}) {
+  out.x = gx; out.z = gz;
+  const nav = game.nav;
+  if (!nav) return false;
+  const wide = !!opt.wide;                           // horses test/route on the clearance grid
+  _f.x = cx; _f.z = cz; _t.x = gx; _t.z = gz;
+  const clear = nav.losHere(_f, _t, centre, wide);   // true = clear · false = blocked · null = no grid
+  if (clear !== false) { s._rtPath = null; return false; }   // clear / unknown → aim straight (no statics to route)
+
+  // A static obstacle sits across the line to the goal — keep (or refresh) an A* path around it.
+  s._rtRepathT = (s._rtRepathT ?? 0) - (opt.dt ?? 0);
+  const goalMoved = !s._rtGoal || dist2D(s._rtGoal.x, s._rtGoal.z, gx, gz) > 3;
+  if (!s._rtPath || goalMoved || s._rtRepathT <= 0) {
+    _f.x = cx; _f.z = cz; _t.x = gx; _t.z = gz;
+    const p = nav.pathHere(_f, _t, centre, wide);
+    if (p && p.length) {
+      s._rtPath = p; s._rtI = 0;
+      (s._rtGoal ??= { x: 0, z: 0 }).x = gx; s._rtGoal.z = gz;
+      s._rtRepathT = 0.75;
+    } else {
+      s._rtRepathT = 0.4;                            // grid still baking / unreachable — try again soon
+    }
+  }
+  const path = s._rtPath;
+  if (!path || !path.length) return false;           // nothing to follow yet → straight (+ caller's stuck backstop)
+
+  // advance past any waypoints we have reached
+  const arrive = opt.arrive ?? 1.2;
+  while (s._rtI < path.length - 1 && dist2D(cx, cz, path[s._rtI].x, path[s._rtI].z) <= arrive) s._rtI++;
+
+  const Ld = opt.lookahead ?? 0;
+  if (Ld <= 0) { out.x = path[s._rtI].x; out.z = path[s._rtI].z; return true; }
+  // CARROT: walk forward along the smoothed polyline accumulating look-ahead distance. Aiming a few
+  // metres down the path (not at the 0.8 m next node) is what stops a horse snapping between close
+  // waypoints — it reads the bend early and curves through it.
+  let ax = cx, az = cz, rem = Ld;
+  for (let i = s._rtI; i < path.length; i++) {
+    const wx = path[i].x, wz = path[i].z, seg = dist2D(ax, az, wx, wz);
+    if (seg >= rem || i === path.length - 1) {
+      const u = seg > 1e-6 ? clamp(rem / seg, 0, 1) : 1;
+      out.x = ax + (wx - ax) * u; out.z = az + (wz - az) * u;
+      return true;
+    }
+    rem -= seg; ax = wx; az = wz;
+  }
+  return true;
+}
+
+// Pure-pursuit turn toward (aimX,aimZ). Returns a turn RATE (rad/s) capped by a MINIMUM TURN RADIUS
+// (wmax = speed / Rmin) so the animal cannot pivot on the spot, plus a speed multiplier that reins it
+// in on a hard heading error so it slows and turns instead of overshooting straight into the obstacle.
+export function mountedTurn(heading, cx, cz, aimX, aimZ, speed, Rmin = 3.5, gain = 2.4) {
+  const desired = Math.atan2(aimX - cx, aimZ - cz);
+  const e = angleDelta(desired, heading);
+  const wmax = Math.max(0.3, speed / Rmin);
+  return { turn: clamp(e * gain, -wmax, wmax), speedMul: clamp(1 - Math.abs(e) / (Math.PI / 2), 0.35, 1), err: e };
+}

package/src/systems/platform.js

@@ -0,0 +1,484 @@
+// A MOVING FLOOR. Sprint at a stagecoach, jump, and land on the roof — and then stay on it while
+// she rolls and turns underneath you. The coach is the first client; a boxcar is the same problem
+// and a train is a line of them, so this is a PRIMITIVE, not a coach feature.
+//
+// THE RIDER IS LOGICALLY PARENTED, NOT REPARENTED. While he is up there, the thing that is true
+// about him is (lx, ly, lz) — where he stands in the platform's OWN frame. His world position is
+// DERIVED from that once a frame, AFTER the platform has moved (postUpdate). That is the whole
+// trick, and it is why standing still on a coach at a gallop does not drift: nothing is integrated,
+// no delta is accumulated, and the yaw ORBIT falls out for free — a man on the back of a coach that
+// turns is simply re-derived at the rotated point, which is exactly what happens to him.
+//
+// He is NOT added to the coach's Object3D. coach.js:426 says why, and it still holds: collision,
+// the camera, the aim and the law's line of sight all read player.position, and a player who is
+// secretly a child of a moving group is a player none of them can find. So his position stays a
+// real world position, every frame, and everything else in the game keeps working on the roof —
+// the capsule, the locomotion FSM, the gun, the dodge. He is a man standing on a coach, not a
+// passenger: `aboard` (player.js:513) is the OTHER thing, and the two can never both be set.
+//
+// ORDER. main.js ticks the player BEFORE the coaches, so nothing inside player.update() may depend
+// on where the coach ends up this frame — and nothing does, because everything he does up there is
+// said in LOCAL terms. postUpdate() runs after the coaches and the trains have moved, turns the
+// local coords back into a world position, and hands him his camera at that final position (which
+// is why _camera is a separate method — player.js:755).
+import * as THREE from 'three/webgpu';
+import { clamp } from '../core/utils.js';
+
+// Gravity, as the capsule controller applies it (world.js:347). The mantle impulse is solved
+// against it, so if one changes the other must.
+const GRAV = 20;
+
+// THE LEDGE CATCH, and it is load-bearing — the numbers do not otherwise meet.
+// A flat-out sprint jump takes off at vy = 7.2 × 1.33 = 9.576 m/s (player.js:1141), so the FEET
+// reach v²/2g = 2.29m. The coach roof is at 2.71m. A running jump is 0.42m SHORT of it and always
+// will be, so a man who gets his feet up level with the roof lip catches it and pulls himself up.
+// MANTLE_REACH is how far below the deck the lip can still be grabbed: 0.85 clears the 0.42m
+// deficit with room for a coach standing on ground higher than yours.
+const MANTLE_REACH = 0.85;
+// ...but ONLY at the top of the arc. At the top of the coach's body (1.86m — where the hull ends,
+// see coach.js) a sprint jump is still travelling upward at 4.4 m/s, so a 2.0 ceiling cannot fire
+// as a free boost off the ground: you have to have actually got up there.
+const MANTLE_VY = 2.0;
+const MANTLE_CLEAR = 0.12;   // how far above the lip the vault carries him — a hand's breadth, no more
+const MANTLE_PULL = 1.5;     // m/s of inward drag, so he comes up OVER the rail and not beside it
+const MANTLE_LOCK = 0.4;     // seconds: no re-trigger, and the body hull lets him through while it runs
+const GRAB = 0.50;           // ≈ the player's capsule radius (0.45): you catch the lip from against the flank
+
+// LANDING. The test is SWEPT — feet above the plane at the top of the frame, below it at the
+// bottom — so a 20 m/s fall (0.33m in a frame) cannot tunnel through a zero-thickness deck.
+const LAND_PAD = 0.20;       // ...plus however far the platform moved last frame: main.js ticks the
+                             // player BEFORE the coaches, so the transform this test reads is one
+                             // frame stale (17cm at a gallop, 27cm at line speed on a train).
+const RELEASE_PAD = 0.30;    // and you keep the deck until you are 30cm off it. Acquire tight,
+                             // release loose, or the roof edge strobes grounded/airborne and the
+                             // locomotion FSM flickers between run and jumpIdle.
+const STEP_UP = 0.45;        // walk up onto a deck this much higher (a tender to a footplate)...
+const STEP_DOWN = 0.60;      // ...and stay glued to one this much lower as she crests a rise.
+
+// A TELEPORT IS NOT A MOVE. Coach._rejoinRoute (coach.js:485) can snap her 20m back onto the route
+// line in a single frame; a train car can be stabled 400m underground (train.js). She goes without
+// him. A legitimate frame at the gallop, at the 0.1s dt clamp, is 1.05m — and a route terminus
+// swings her ~0.25 rad in ONE frame (coach.js:381 eases yaw per frame, not per second), which is
+// violent but real, so the yaw threshold must sit well above it.
+const TELE_XZ = 2.0, TELE_Y = 2.0, TELE_YAW = 0.5;
+
+// The lens, not the man. The position orbit and his body yaw are carried IN FULL — that is
+// physically what the coach does to you — but the CAMERA is rate-limited, so a terminus reversal
+// reads as a swing rather than an 14° snap in one frame.
+const CAM_YAW_RATE = 2.5;    // rad/s
+
+const AIR_BLEED = 0.25;      // seconds: how fast inherited speed dies once his feet are down again.
+                             // There is NO bleed in the air — a jump off a moving coach is pure
+                             // ballistics, which is what makes "jump straight up and land back on
+                             // her" true, and what flings you when you jump off a galloping team.
+const COL_GRACE = 0.25;      // he keeps ignoring his own platform's collider box for this long after
+                             // leaving it — a train car's box is banded to its own ROOF (train.js),
+                             // so without it stepping off one would shove him out of the flank.
+
+const _v = new THREE.Vector3();
+const _v2 = new THREE.Vector3();
+const _m = new THREE.Matrix4();
+
+const wrapPi = (a) => { while (a > Math.PI) a -= Math.PI * 2; while (a < -Math.PI) a += Math.PI * 2; return a; };
+const inRect = (d, lx, lz, pad) => lx > d.x0 - pad && lx < d.x1 + pad && lz > d.z0 - pad && lz < d.z1 + pad;
+
+export class PlatformRegistry {
+  constructor(game) {
+    this.game = game;
+    this.hosts = [];
+  }
+
+  // The host contract is duck-typed on purpose — the same shape a train car can be registered with
+  // from OUTSIDE its own file:
+  //   root    a Group whose position and rotation.y are the platform (pitch/roll tolerated)
+  //   owner   whoever it belongs to — the identity a look-ahead exempts its own roof rider by
+  //   decks   local-space rects with a flat top: {x0,x1,z0,z1,y,surface}. Highest wins.
+  //   hull    optional local box that pushes an airborne man OUT of the body (never a bullet)
+  //   cols    its entries in world/town.js's `colliders` — skipped for whoever is riding it
+  //   mantle  how far below a deck its lip can be caught (0 = no ledge catch)
+  //   radius  broadphase reach from the root, XZ
+  register(spec) {
+    const h = {
+      root: spec.root,
+      owner: spec.owner ?? null,
+      decks: spec.decks ?? [],
+      hull: spec.hull ?? null,
+      cols: spec.cols ?? null,
+      mantle: spec.mantle ?? MANTLE_REACH,
+      radius: spec.radius ?? 4,
+      enabled: spec.enabled ?? (() => true),
+      // The registry measures the platform's own per-frame delta itself, from a snapshot it takes
+      // at the end of every postUpdate. The owner therefore needs no per-frame hook and no
+      // bookkeeping — which is the only reason a train car can be registered without editing
+      // train.js at all.
+      px: 0, py: 0, pz: 0, pry: 0, pm: new THREE.Matrix4(),
+      dx: 0, dy: 0, dz: 0, dyaw: 0,
+      vx: 0, vy: 0, vz: 0, yawRate: 0,
+      teleported: false,
+    };
+    this._snap(h);
+    this.hosts.push(h);
+    return h;
+  }
+
+  unregister(host) {
+    const i = this.hosts.indexOf(host);
+    if (i < 0) return;
+    const p = this.game.player;
+    if (p?.platform?.host === host) this.leave(p, 'drop');
+    this.hosts.splice(i, 1);
+  }
+
+  // Who is carrying him — the accessor a coach's look-ahead asks, so it does not brake for the man
+  // standing on its own roof. Handed out rather than compared by identity, because a train car is
+  // proxied into game.coaches.coaches as a plain object and the identities would not line up.
+  carrier(entity) { return entity?.platform?.host.owner ?? null; }
+
+  // ── local ↔ world ────────────────────────────────────────────────────────────────────────────
+  // The yaw-only fast path is the same rotate-the-offset arithmetic the coach already uses for its
+  // riders and its horse colliders (coach.js:314-322/345), and its exact inverse. A platform that
+  // PITCHES (a train car on a bank/grade: train.js sets rotation.order='YXZ' and writes rotation.x)
+  // takes the matrix path instead — a flat deck plane read through a yaw-only frame is wrong by
+  // halfLength·sin(pitch), which is half a metre at the end of a 17m carriage.
+  _pitched(h) { return Math.abs(h.root.rotation.x) + Math.abs(h.root.rotation.z) > 1e-4; }
+
+  _toWorld(h, lx, ly, lz, out) {
+    if (this._pitched(h)) {
+      h.root.updateWorldMatrix(true, false);
+      return out.set(lx, ly, lz).applyMatrix4(h.root.matrixWorld);
+    }
+    const p = h.root.position, ry = h.root.rotation.y;
+    const c = Math.cos(ry), s = Math.sin(ry);
+    return out.set(p.x + lx * c + lz * s, p.y + ly, p.z - lx * s + lz * c);
+  }
+
+  // ...the same point through LAST frame's transform. Only the vertical is ever wanted (what the
+  // deck under his boots did while he stood still), and that is what keeps the visual-height
+  // smoother honest — see postUpdate.
+  _toWorldPrev(h, lx, ly, lz, out) {
+    if (this._pitched(h)) return out.set(lx, ly, lz).applyMatrix4(h.pm);
+    const c = Math.cos(h.pry), s = Math.sin(h.pry);
+    return out.set(h.px + lx * c + lz * s, h.py + ly, h.pz - lx * s + lz * c);
+  }
+
+  _toLocal(h, wx, wy, wz, out) {
+    if (this._pitched(h)) {
+      h.root.updateWorldMatrix(true, false);
+      _m.copy(h.root.matrixWorld).invert();
+      return out.set(wx, wy, wz).applyMatrix4(_m);
+    }
+    const p = h.root.position, ry = h.root.rotation.y;
+    const c = Math.cos(ry), s = Math.sin(ry);
+    const dx = wx - p.x, dz = wz - p.z;
+    return out.set(dx * c - dz * s, wy - p.y, dx * s + dz * c);
+  }
+
+  _near(h, x, z) {
+    const p = h.root.position;
+    const dx = x - p.x, dz = z - p.z;
+    const r = h.radius + 2;
+    return dx * dx + dz * dz < r * r;
+  }
+
+  _snap(h) {
+    const p = h.root.position;
+    h.px = p.x; h.py = p.y; h.pz = p.z; h.pry = h.root.rotation.y;
+    if (this._pitched(h)) { h.root.updateWorldMatrix(true, false); h.pm.copy(h.root.matrixWorld); }
+  }
+
+  _measure(h, dt) {
+    const p = h.root.position;
+    h.dx = p.x - h.px; h.dy = p.y - h.py; h.dz = p.z - h.pz;
+    h.dyaw = wrapPi(h.root.rotation.y - h.pry);
+    h.teleported = Math.abs(h.dx) + Math.abs(h.dz) > TELE_XZ || Math.abs(h.dy) > TELE_Y || Math.abs(h.dyaw) > TELE_YAW;
+    // the velocities SURVIVE a teleport frame: the last sane ones are what a rider thrown off by
+    // one takes with him
+    if (!h.teleported && dt > 1e-5) {
+      h.vx = h.dx / dt; h.vy = h.dy / dt; h.vz = h.dz / dt; h.yawRate = h.dyaw / dt;
+    }
+  }
+
+  // How fast the platform is moving THE POINT HE IS STANDING ON — the translation plus the
+  // tangential term of the yaw. (Check: a man at local +X on a platform whose yaw increases is
+  // swung toward -Z, and this gives (0, -yawRate·offX). Correct.)
+  _velAt(h, wx, wz, out) {
+    const p = h.root.position;
+    const ox = wx - p.x, oz = wz - p.z;
+    return out.set(h.vx + h.yawRate * oz, h.vy, h.vz - h.yawRate * ox);
+  }
+
+  // ── the deck search ──────────────────────────────────────────────────────────────────────────
+  // The HIGHEST deck under his feet wins, across every platform — so walking from one train car to
+  // the next is a rebind on the same frame, with no airborne frame and no release. `ride` is the
+  // one he is already on, and only IT gets the release pad: acquire tight, release loose.
+  _deckUnder(wx, feetY, wz, ride) {
+    let best = null;
+    for (const h of this.hosts) {
+      if (!h.enabled() || !this._near(h, wx, wz)) continue;
+      this._toLocal(h, wx, feetY, wz, _v);
+      for (const d of h.decks) {
+        const mine = ride && ride.host === h && ride.deck === d;
+        if (!inRect(d, _v.x, _v.z, mine ? RELEASE_PAD : 0)) continue;
+        const y = this._toWorld(h, _v.x, d.y, _v.z, _v2).y;
+        if (y > feetY + STEP_UP || y < feetY - STEP_DOWN) continue;
+        if (!best || y > best.y) best = { host: h, deck: d, y, lx: _v.x, lz: _v.z };
+      }
+    }
+    return best;
+  }
+
+  // ── getting on ───────────────────────────────────────────────────────────────────────────────
+  // Called from player.js right after the capsule solve, and ONLY when he is not already riding.
+  // `prevFeetY` is his height at the top of the frame, so the plane test is over the whole frame's
+  // vertical sweep rather than an instant.
+  tryLand(e, prevFeetY, wasAir) {
+    if (!e.rideable || e.platform || !e.alive) return;
+    const fx = e.position.x, fy = e.position.y, fz = e.position.z;
+    let best = null, mantle = null;
+    for (const h of this.hosts) {
+      if (!h.enabled() || h.teleported || !this._near(h, fx, fz)) continue;
+      this._toLocal(h, fx, fy, fz, _v);
+      const lx = _v.x, lz = _v.z;
+      // the transform is one frame stale (the coaches move after the player), so forgive the
+      // footprint by however far she actually travelled in that frame
+      const pad = LAND_PAD + Math.abs(h.dx) + Math.abs(h.dz);
+      for (const d of h.decks) {
+        const y = this._toWorld(h, lx, d.y, lz, _v2).y;
+        // DOWN through the plane: the ordinary landing. `h.dy` is in the test because the deck can
+        // come UP past a man who is falling — a coach cresting a rise into a jumper — and he was
+        // above it before she moved, which still counts.
+        const down = e.vy <= 0.01 && prevFeetY >= y - 0.02 - Math.max(0, h.dy) && fy < y;
+        // UP through it: he is finishing a vault (below), and pulling yourself onto a roof does not
+        // require you to fall onto it afterwards.
+        const up = e._mantleT > 0 && e.vy > 0 && prevFeetY < y && fy >= y - 0.02;
+        if ((down || up) && inRect(d, lx, lz, pad)) {
+          if (!best || y > best.y) best = { host: h, deck: d, y, lx, lz };
+          continue;
+        }
+        // THE LEDGE. Feet up level with the lip, at the top of the arc, and inside the footprint by
+        // a capsule's reach: he catches it. Gated on MANTLE_VY so it cannot be a free boost taken
+        // off the ground beside her — see the constants.
+        if (!wasAir && !e.airborne) continue;
+        if (e._mantleT > 0 || e.vy > MANTLE_VY || h.mantle <= 0) continue;
+        if (fy < y - h.mantle || fy >= y - 0.02) continue;
+        if (!inRect(d, lx, lz, GRAB)) continue;
+        if (!mantle || y > mantle.y) mantle = { host: h, deck: d, y, lx, lz };
+      }
+    }
+    if (best) { this._board(e, best); return; }
+    if (mantle) this._vault(e, mantle);
+  }
+
+  _vault(e, m) {
+    const gap = m.y - e.position.y;
+    e.vy = Math.sqrt(2 * GRAV * (gap + MANTLE_CLEAR));
+    e._mantleT = MANTLE_LOCK;
+    // Take her speed with you or she rolls out from under the vault — at a trot she covers 0.4m in
+    // the 0.12s it takes him to get his feet over the lip. Plus a drag INWARD, so he comes up over
+    // the rail rather than beside it.
+    this._velAt(m.host, e.position.x, e.position.z, _v2);
+    const d = m.deck;
+    const cx = clamp(m.lx, d.x0, d.x1) - m.lx, cz = clamp(m.lz, d.z0, d.z1) - m.lz;
+    const len = Math.hypot(cx, cz);
+    const ix = len > 1e-3 ? cx / len : 0, iz = len > 1e-3 ? cz / len : 0;
+    const ry = m.host.root.rotation.y, c = Math.cos(ry), s = Math.sin(ry);
+    e._airVX = _v2.x + (ix * c + iz * s) * MANTLE_PULL;
+    e._airVZ = _v2.z + (-ix * s + iz * c) * MANTLE_PULL;
+  }
+
+  _board(e, b) {
+    e.position.y = b.y;
+    this._toLocal(b.host, e.position.x, e.position.y, e.position.z, _v);
+    b.lx = _v.x; b.lz = _v.z;
+    e.vy = 0;
+    e.airborne = false;
+    e._capGrounded = false;     // the capsule's snap-to-ground pass (world.js:314) must never
+                                // raycast a man off a roof onto the dirt below
+    e._airVX = 0; e._airVZ = 0; // his flight is over: no 1.5m skid across the roof
+    e._mantleT = 0;
+    e.platform = {
+      host: b.host, deck: b.deck,
+      lx: b.lx, ly: b.deck.y, lz: b.lz,
+      yawDebt: 0, vx: 0, vy: 0, vz: 0, fresh: true,
+    };
+    e._skipCols = b.host.cols; e._skipT = COL_GRACE;
+    if (e._visualY === undefined) e._visualY = e.position.y;
+  }
+
+  // ── staying on ───────────────────────────────────────────────────────────────────────────────
+  // Replaces world.moveCapsule while he is riding: no gravity, no terrain, no BVH — the deck IS the
+  // floor. He still gets the 2D collider pass (props, trees, a hitching rail) so the road can still
+  // scrape him off, with his own platform's box skipped.
+  deckMove(e, hx, hz, dt) {
+    const ride = e.platform;
+    const W = this.game.world;
+    if (!ride.host.enabled() || ride.host.teleported || !e.alive) {
+      this.leave(e, 'drop');
+      return W.moveCapsule(e, hx, hz, dt);
+    }
+    // jump() runs at the END of player.update, after this — so a positive vy here is the first
+    // frame of a jump that was taken ON the deck, and he is ballistic from now on.
+    if (e.vy > 0.01) {
+      this.leave(e, 'jump');
+      return W.moveCapsule(e, hx, hz, dt);
+    }
+    // WHERE HE STANDS IS A LOCAL FACT. Start from his deck coords put through the platform's
+    // transform as it is RIGHT NOW — never from his last world position. The two are the same
+    // number in the ordinary tick, but only this one is immune to the platform having been moved
+    // by something other than its own update: an out-of-band transform is then a carry, which is
+    // what it is, instead of quietly becoming local drift that slides him off the back.
+    const r = e.capsuleR ?? e.radius ?? 0.45;
+    this._toWorld(ride.host, ride.lx, ride.ly, ride.lz, _v);
+    const feetY = _v.y;
+    let wx = _v.x + hx, wz = _v.z + hz;
+    const air = feetY - W.groundAt(wx, wz);
+    const c = W.collide(wx, wz, r, air, feetY, e._skipCols);
+    wx = c.x; wz = c.z;
+
+    const found = this._deckUnder(wx, feetY, wz, ride);
+    if (!found) {
+      // he has walked off the edge. Not a fall from a standstill: he goes with her.
+      e.position.x = wx; e.position.z = wz;
+      this.leave(e, 'step');
+      e.vy = Math.min(e.vy, 0);
+      return W.moveCapsule(e, 0, 0, dt);
+    }
+    if (found.host !== ride.host || found.deck !== ride.deck) {
+      ride.host = found.host; ride.deck = found.deck; ride.yawDebt = 0; ride.fresh = true;
+      e._skipCols = found.host.cols;
+    }
+    ride.lx = found.lx; ride.lz = found.lz; ride.ly = found.deck.y;
+    e.position.set(wx, found.y, wz);
+    e.vy = 0;
+    e.airborne = false;
+    e._capGrounded = false;
+    e._skipT = COL_GRACE;
+    return true;
+  }
+
+  // The dodge burst (player.js:564) goes through Character.move → moveCapsule, which would drop him
+  // off the roof onto the terrain. On a deck it is a plain local displacement instead.
+  step(e, dx, dz) {
+    if (!e.platform) return;
+    this.deckMove(e, dx, dz, 0);
+  }
+
+  // ── getting off ──────────────────────────────────────────────────────────────────────────────
+  // Every exit funnels through here so they cannot drift apart: jumping off, walking off the edge,
+  // the platform dropping him, and sitting down on the box as her driver.
+  //   'jump' / 'step'  — you keep her speed. Jump off a galloping team and you are FLUNG.
+  //   'aboard'         — you are sitting down on her; player.js's aboard path takes over.
+  //   'drop'           — she teleported, was stabled, or you died. No inheritance from a lie.
+  leave(e, why) {
+    const ride = e.platform;
+    if (!ride) return;
+    e.platform = null;
+    e._capGrounded = false;
+    e._skipT = COL_GRACE;
+    if (why === 'jump' || why === 'step') {
+      e._airVX = clamp(ride.vx, -18, 18);
+      e._airVZ = clamp(ride.vz, -18, 18);
+      e.airborne = true;
+      e._visualY = undefined;        // let the smoother re-latch wherever he lands (Coach.alight:465)
+    } else {
+      e._airVX = 0; e._airVZ = 0;
+      e._skipCols = null; e._skipT = 0;
+      if (why !== 'aboard') e._visualY = undefined;
+    }
+    ride.host.owner?.onRiderLeave?.(e);
+  }
+
+  // ── the carry ────────────────────────────────────────────────────────────────────────────────
+  // main.js calls this AFTER the coaches and the trains have moved, and unconditionally — with the
+  // map open the platform has not moved, the delta is zero, and this degrades to handing him his
+  // camera. It is idempotent: the snapshot is retaken at the end, so a second call in the same
+  // frame measures a zero delta and carries nothing twice.
+  postUpdate(dt, input, camera) {
+    const p = this.game.player;
+    const riding = !!p?.platform;
+    for (const h of this.hosts) this._measure(h, dt);
+
+    if (riding) {
+      const ride = p.platform;
+      const h = ride.host;
+      if (!p.alive || p.riding?.mounted || p.aboard || !h.enabled() || h.teleported) {
+        this.leave(p, 'drop');
+      } else {
+        // where the deck under his boots WAS, before she moved — the platform's own vertical motion,
+        // measured at his feet
+        const wasY = this._toWorldPrev(h, ride.lx, ride.ly, ride.lz, _v2).y;
+        this._toWorld(h, ride.lx, ride.ly, ride.lz, p.position);
+        const deckDY = p.position.y - wasY;
+
+        p.heading += h.dyaw;
+        p.root.rotation.y = p.heading;
+        // the lens is rate-limited where the body is not: coach.js eases her yaw PER FRAME, so a
+        // route terminus reverses her by ~0.25 rad in one of them. Pay the debt off over a few.
+        ride.yawDebt += h.dyaw;
+        const step = clamp(ride.yawDebt, -CAM_YAW_RATE * dt, CAM_YAW_RATE * dt);
+        p.camYaw += step;
+        ride.yawDebt -= step;
+
+        this._velAt(h, p.position.x, p.position.z, _v);
+        const k = ride.fresh ? 1 : Math.min(1, dt * 20);   // a couple of frames of smoothing, so one
+        ride.vx += (_v.x - ride.vx) * k;                   // noisy frame cannot fling him
+        ride.vy += (_v.y - ride.vy) * k;
+        ride.vz += (_v.z - ride.vz) * k;
+        ride.fresh = false;
+
+        // THE VISUAL HEIGHT. player.js's smoother eases the drawn feet DOWN toward the real ones
+        // over micro-bumps, and the camera is driven from it (player.js:763). Left alone on a coach
+        // it would smooth HER descent as if it were a bump in his path: on a downhill he would be
+        // drawn hanging above the roof for as long as the hill lasted, and the camera with him. So
+        // the deck's own rise and fall is added to it at the same instant it lands in his feet —
+        // then the only thing left in (feet - _visualY) is HIS motion relative to the deck, which
+        // on a flat roof is nothing at all. The smoother keeps its real job (a step between decks)
+        // and contributes no error to a moving one.
+        if (p._visualY === undefined) p._visualY = p.position.y;
+        else p._visualY += deckDY;
+        const py = p.position.y;
+        if (Math.abs(py - p._visualY) > 1.5) p._visualY = py;
+        else p._visualY += (py - p._visualY) * Math.min(1, dt * 12);
+        if (p.model) p.model.position.y = (p._baseModelY2 ?? 0) + (p._visualY - py);
+      }
+    }
+
+    for (const h of this.hosts) this._snap(h);
+
+    // ONE camera update per frame, always. player.update skips its own when he is riding (its
+    // position would be a frame behind the coach he is standing on); it runs it itself on the frame
+    // he leaves. A dead man's camera is left where it was, exactly as player.update leaves it.
+    if (riding && p.alive) p._camera(dt, input, camera);
+  }
+
+  // ── the body ─────────────────────────────────────────────────────────────────────────────────
+  // The coach's collider box stops at the footboard (coach.js:341: y1 = root.y + 1.55) so that a
+  // bullet aimed at the driver does not die on the chassis — which leaves the CABIN, between the
+  // footboard and the roof, as a metre-high hole a mistimed jump sails straight into. This is that
+  // wall: entity-only, never pushed into world/town.js's `colliders`, so it cannot stop a round.
+  // Mistime the jump and you smack into the side of the coach and fall, which is the honest answer.
+  hullPush(e) {
+    if (!e.rideable || e.platform || e._mantleT > 0 || !e.alive) return;
+    const r = e.capsuleR ?? e.radius ?? 0.45;
+    for (const h of this.hosts) {
+      const hull = h.hull;
+      if (!hull || !h.enabled() || !this._near(h, e.position.x, e.position.z)) continue;
+      const y0 = h.root.position.y + hull.y0, y1 = h.root.position.y + hull.y1;
+      // the same band test world.collide uses (world.js:254): feet above the top or a whole body
+      // below the bottom and the box is not there
+      if (e.position.y > y1 || e.position.y + 1.8 < y0) continue;
+      this._toLocal(h, e.position.x, e.position.y, e.position.z, _v);
+      const cx = (hull.x0 + hull.x1) / 2, cz = (hull.z0 + hull.z1) / 2;
+      const ex = (hull.x1 - hull.x0) / 2 + r, ez = (hull.z1 - hull.z0) / 2 + r;
+      const lx = _v.x - cx, lz = _v.z - cz;
+      if (Math.abs(lx) >= ex || Math.abs(lz) >= ez) continue;
+      // push out of the nearest face
+      const px = ex - Math.abs(lx), pz = ez - Math.abs(lz);
+      const nx = px < pz ? (lx < 0 ? -ex : ex) : lx;
+      const nz = px < pz ? lz : (lz < 0 ? -ez : ez);
+      this._toWorld(h, nx + cx, _v.y, nz + cz, _v2);
+      e.position.x = _v2.x;
+      e.position.z = _v2.z;
+    }
+  }
+}