sindicate 0.1.0 → 0.4.0

package/src/systems/trainCamera.js

@@ -0,0 +1,414 @@
+// THE TRAIN CAMERA — what riding a train is actually FOR.
+//
+// A passenger is not driving. He cannot steer it, he cannot stop it, and the whole value of the
+// journey is the one thing a third-person game normally refuses to show you: the train itself, from
+// outside, moving. So while he rides, the camera stops being a follow camera and becomes a CUTTING
+// ROOM — six shots on a loop, about five seconds each, which is GTA V's train and the right reference.
+//
+// THREE RULES. Every bug in here came from breaking one of them.
+//
+//   1. CUT, DO NOT EASE. The shots are sixty metres apart. Interpolating between two of them flies the
+//      lens through the middle of a boxcar at 40 m/s: it cannot be kept out of the geometry, and it
+//      does not read as an edit, it reads as a drone. So the cuts are HARD and the movement lives
+//      INSIDE each shot — a dolly in, a slow crane, a pan that lags its subject. That is what film does.
+//
+//   2. PLANT IT, DO NOT CHASE IT. Every lens position here is written EXACTLY — set(), never a lerp
+//      toward a moving target. Measured on the live game at 16 m/s, sampling 1800 frames of the whole
+//      cycle: the lens sits still in the loco's own frame to within 11 mm a frame (that 11 mm IS the
+//      dolly), the vertical never changes sign twice, and the look direction moves 0.02° a frame.
+//      A smoother chasing a body doing 16 m/s sits v/k metres behind it and every wobble in the frame
+//      time wobbles the lag — THAT is what "bouncing like mad" was. There was never anything to chase:
+//      the train's own transform is smooth, so a camera written straight off it is smooth too. The only
+//      thing low-passed in this file is the TERRAIN, because the ground under a lens doing 16 m/s is a
+//      lattice and sampling it raw is its own chatter.
+//
+//   3. IT IS FILMED AFTER THE IRON HAS MOVED. main.js updates the player at :673 and the trains at
+//      :692 — so any car transform read from inside player.update() is a frame old, which at 16 m/s is
+//      27 cm, resampled every frame against a frame time that jitters. That is a camera bolted to a
+//      carriage that is shivering. This rig runs from Player.aboardPost, at the END of the tick, once
+//      the train has actually moved. (platform.js's postUpdate exists for precisely this reason.)
+//      ...and it refreshes the matrices of the two cars it reads (see update): three only rebuilds
+//      matrixWorld at RENDER, and the loco's is otherwise only fresh by accident — the crew's IK solve
+//      walks updateWorldMatrix up through the loco root as a side effect. Shoot the driver and the
+//      fireman and that accident stops happening, which would put a frame of lag into every exterior
+//      shot in the middle of a train robbery.
+//
+// AND IT GETS OUT OF THE WAY. Aim, draw, take a round, stop at a platform, or press V, and it hands the
+// lens back to the ordinary follow camera in the SAME FRAME, with a snap and not a swoop. A cinematic
+// camera that traps a man who is being shot at is not a feature.
+import * as THREE from 'three/webgpu';
+
+// Module temporaries. Nothing in this file allocates after construction — it runs every frame at 120.
+const _p = new THREE.Vector3();    // where the lens goes
+const _t = new THREE.Vector3();    // what it looks at
+const _a = new THREE.Vector3();
+const _b = new THREE.Vector3();
+
+const GRACE = 1.1;      // seconds of ordinary follow camera after she starts to move, before the first
+                        // cut — you get to watch her pull out of the platform from your own seat.
+const ROLLING = 1.2;    // m/s. Below this she is standing at a call and the film is over: he wants his
+                        // own camera and his mouse back, to look about and to find the way off.
+const PASS_SPEED = 6;   // below this the trackside pass-by has nothing to pass, so it is skipped
+const BLOCK_CUT = 0.45; // seconds of a lost sightline before a shot gives up and cuts early. Long
+                        // enough that a lineside rock flicking through frame is a wipe, not a bug.
+
+// ── THE SHOTS ─────────────────────────────────────────────────────────────────────────────────
+// `dur` is per shot and deliberately not shared. A tight shot on a set of coupling rods outstays its
+// welcome in four seconds; a trackside pass-by needs seven, because a 55 m consist doing 16 m/s takes
+// three and a half of them just to go by. Average 5.4 s, which is the "about five" that was asked for.
+//
+// Each shot writes _p and _t and returns false if it cannot be taken right now (nothing to film, or a
+// wall in the way), in which case the rig moves on to the next one. `guard` means the shot's sightline
+// is worth testing against the world; the interior shots do not need it, because they are written in
+// the car's own frame and are inside it by construction.
+const SHOTS = [
+  // 1 ── THE SEAT. Establish that you are ON a train before you show him the train. Him on his bench in
+  // the right of frame with the county tearing past the glass at his shoulder, the saloon running away
+  // down the left, and the lens creeping in on him over the shot.
+  //
+  // The numbers are the carriage's, not a guess (train.js:145): bench pan 2.109, BACKREST TOP 2.653,
+  // roof 4.10, glass 2.319–3.640, seat.y 1.367 and his head bone seat.y + 1.556. The first version of
+  // this shot sat at seat.y + 1.30 = 2.667 — fourteen millimetres above the backrest — so a bench back
+  // filled the bottom half of the frame and you could not see the man or the window. It is at head
+  // height plus a shoulder now, which clears the backs by 0.66 m and looks down the car.
+  { id: 'seat', dur: 5.0, shot(r, k) {
+      const car = r.host.car, s = r.host.seat, f = r.fore();
+      if (car.kind === 'carriage') {
+        // Across the aisle, behind his shoulder, creeping in 0.75 m. x 0.75 and |z − his bench| < 2.6
+        // are INSIDE the saloon box (hx 1.30, y 1.93…4.10, z −6.5…7.3) by construction — this lens
+        // cannot clip the planking, because it is never outside it.
+        _p.set(0.75, s.y + 1.95, s.z - f * (2.55 - k * 0.75));
+        _t.set(s.x - 0.25, s.y + 1.52, s.z + f * 1.60);
+      } else {
+        // The roof rider. Outboard of his shoulder and well above the clerestory (4.747), looking
+        // along the train past him. Everything under this lens is roof; there is nothing to clip.
+        _p.set(3.05, 6.40, f * (-5.6 + k * 1.3));
+        _t.set(1.30, 4.80, f * 3.0);
+      }
+      car.root.localToWorld(_p);
+      car.root.localToWorld(_t);
+      return true;
+    } },
+
+  // 2 ── THE TRACKSIDE PASS-BY. The best one, and the reason the file exists. A camera is PLANTED
+  // beside the rails ahead of the train — on the line's own geometry, from the route it is actually
+  // running, not a guess off the loco's heading — and then it does not move an inch. The train comes
+  // to IT. It is the only shot here with no camera motion at all, and it is the one that sells the
+  // weight of the thing, because the only thing moving in frame is eighty tons of iron.
+  //
+  // The pan LAGS its subject. A real operator on a tripod cannot whip-pan an express through ninety
+  // degrees at twelve metres either: the train slides out of frame at the abeam point and he catches it
+  // up going away. That lag is the shot.
+  { id: 'trackside', dur: 7.0, guard: true, plant(r) {
+      const T = r.train;
+      if (T.speed < PASS_SPEED || !T.route) return false;
+      const R = T.route;
+      // 44 m of run-up: the loco reaches the lens at 2.7 s and the tail clears it at about 6.1 s, so
+      // the whole consist passes inside the shot instead of the shot ending halfway down the train.
+      const u = T.u + 44;
+      if (u > R.len + 30) return false;                 // she is about to berth: there is no pass-by
+      R.pos(u, _a); _a.y = R.height(u);
+      R.pos(u + 4, _b);                                  // the LINE's own tangent here, not the loco's
+      const dx = _b.x - _a.x, dz = _b.z - _a.z;
+      const L = Math.hypot(dx, dz) || 1;
+      const nx = dz / L, nz = -dx / L;                   // the perpendicular, in the six-foot's own frame
+      // Try both sides of the road. 12 m of standoff and 2.4 m of tripod: near enough that the loco
+      // fills the frame, far enough that it does not become a blur of planking.
+      for (let i = 0; i < 2; i++) {
+        const side = i ? -1 : 1;
+        const x = _a.x + nx * 12 * side, z = _a.z + nz * 12 * side;
+        if (r.world.waterDepthAt?.(x, z) > 0.25) continue;                 // not in the creek
+        const y = Math.max(r.world.groundAt(x, z) + 2.4, _a.y + 1.5);
+        _p.set(x, y, z);
+        r.aimCar(_t, r.host.car, 1.6);
+        // A camera INSIDE the station or the water tower cannot see the train it is pointing at, so
+        // the sightline test throws that plant out for us — no special case for the buildings.
+        if (!r.world.segmentBlocked(_p, _t)) { r.px = x; r.py = y; r.pz = z; return true; }
+      }
+      return false;
+    },
+    shot(r) {
+      _p.set(r.px, r.py, r.pz);
+      r.aimCar(_a, r.host.car, 1.6);
+      // ...and the shot is over the moment its subject is gone: his car forty metres past the lens is
+      // a camera filming an empty desert. Cut early rather than sit through it.
+      _b.set(_a.x - r.px, 0, _a.z - r.pz);
+      if (_b.x * r.fx + _b.z * r.fz > 40) return false;
+      _t.copy(_a);
+      return true;
+    } },
+
+  // 3 ── THE FOOTPLATE. Out on the running board ahead of the cab, looking BACK along the boiler at the
+  // driver in his window, with the smoke coming over the top of frame and the train trailing away
+  // behind him. It is outboard of the body (|x| 2.55 against a 1.64 half-width) and above the running
+  // board, so it is in fresh air on every axis.
+  //
+  // TWO SHOTS WERE THROWN AWAY TO GET THIS ONE, and both were photographed before the vote. The lens
+  // INSIDE the cab does frame the backhead, the gauges and both men — and the cab interior is unlit, so
+  // the top third of the frame is a black slab and the two of them are hard-cropped silhouettes. And
+  // the version looking FORWARD off the running board is a handsome shot of a boiler with the crew
+  // squarely behind the lens, which is a footplate shot with no footplate in it. This one has the man.
+  { id: 'footplate', dur: 5.0, guard: true, shot(r, k) {
+      const s = r.locoSide();
+      _p.set(s * 2.55, 3.45, 3.2 - k * 1.1);    // creeping back down the board toward him
+      _t.set(s * 0.95, 3.15, -5.4);             // the cab window, and the driver in it (crew z −4.95)
+      r.loco.root.localToWorld(_p);
+      r.loco.root.localToWorld(_t);
+      return true;
+    } },
+
+  // 4 ── THE WIDE. High and behind, far enough back to hold all 55 m of her at once with the smoke
+  // trailing off the stack — the shot that says "this is a train" and not "this is a carriage". It
+  // cranes down and in over the shot (24 m → 17 m up, 27 m → 16 m out), which is the only movement it
+  // needs: at this range the train's own progress does all the work.
+  { id: 'wide', dur: 5.5, guard: true, shot(r, k) {
+      const mid = r.train.len * 0.5;
+      r.along(_a, -mid, 0, 0);                              // the middle of the consist
+      const back = 46 - k * 4, out = 27 - k * 11, up = 24 - k * 7;
+      r.along(_p, -mid - back, r.side * out, up);
+      _p.y = Math.max(_p.y, r.floorAt(_p.x, _p.z, 5));      // never behind a ridge
+      _t.set(_a.x, _a.y + 2.2, _a.z);
+      return true;
+    } },
+
+  // 5 ── THE RODS. Mine, and it earns its place because a steam locomotive is the only vehicle in this
+  // game whose MECHANISM is worth filming: the drivers turn on distance rolled and the coupling rods
+  // reciprocate off the same number (train.js: radians = distance / radius), so they can never be out
+  // of step with the ground. Wheel height, four metres out, tracking forward along the running board.
+  // Ballast blurring, rods hammering. It is the shortest shot in the cycle on purpose — a tight
+  // mechanical hold is over in four seconds.
+  { id: 'rods', dur: 4.5, guard: true, shot(r, k) {
+      const s = r.locoSide();
+      _p.set(s * (4.8 - k * 1.2), 1.95, -3.6 + k * 3.6);
+      _t.set(s * 0.6, 1.35, -1.8);                          // the drivers (hub 0.93) and the rods above them
+      r.loco.root.localToWorld(_p);
+      r.loco.root.localToWorld(_t);
+      _p.y = Math.max(_p.y, r.floorAt(_p.x, _p.z, 0.7));    // a cutting must not swallow the lens
+      return true;
+    } },
+
+  // 6 ── THE LOW THREE-QUARTER. The lens runs ahead of her, low, off the shoulder of the track, and she
+  // comes ON to it — 24 m of clear air in front of the smokebox closing to 7, so the loco GROWS in
+  // frame while the camera holds its line. The only shot that gets the cowcatcher in your face.
+  //
+  // MEASURED FROM HER NOSE, and that is the whole of the fix. along() is written off the LEAD CAR'S
+  // CENTRE, and the first version of this shot asked for `train.len + d` — which is 85 m in front of
+  // the loco's middle — and then aimed at a point 50 m ahead of her. The result was a speck of a train
+  // on the horizon and four hundred square metres of sand, held for five and a half seconds. The lead
+  // car's half-length is the number that turns "forward of the lead car" into "clear of her buffers".
+  { id: 'front', dur: 5.5, guard: true, shot(r, k) {
+      if (r.train.reversed) return false;   // she is being propelled: what is coming at the lens is the
+                                            // arse end of a carriage, and that is not this shot
+      const nose = r.train.cars[0].len * 0.5;
+      const d = 24 - k * 17, out = r.side * (9.0 - k * 4.2);
+      r.along(_p, nose + d, out, 1.3);
+      _p.y = Math.max(_p.y, r.floorAt(_p.x, _p.z, 1.5));
+      r.along(_t, 3.0, 0, 2.3);                             // the smokebox, not the sky above it
+      return true;
+    } },
+];
+
+// ── THE RIG ───────────────────────────────────────────────────────────────────────────────────
+class TrainCamera {
+  constructor(train, host) {
+    this.train = train;
+    this.host = host;
+    this.game = train.game;
+    this.world = train.game.world;
+    this.i = 0;
+    this.t = 0;
+    this.grace = GRACE;
+    this.off = false;      // V: he wants his own camera back
+    this.side = 1;         // which flank the exterior shots stand on — chosen at each cut
+    this.blockT = 0;
+    this.floor = null;     // a LOW-PASSED ground height under the lens (see floorAt)
+    this.px = 0; this.py = 0; this.pz = 0;   // the trackside plant, in plain numbers: no vector to alias
+    this.fx = 0; this.fz = 1;                // the way she is going
+    this.was = null;       // the rider we set up for, so a re-board resets the cycle
+    this._planted = null;  // the shot whose plant() has been run for this take
+    this._held = false;
+    this._k = 0;
+    this._f = 0;
+  }
+
+  get loco() { return this.train.cars[0]; }
+
+  // +1 if the car the player is in has its own +Z pointing the way the train is travelling. Every
+  // "behind him" in the seat shot is written in car-local z and needs this, because a train that has
+  // reversed out of Bonebreak is running with its cars facing backwards.
+  fore() {
+    return Math.cos(this.host.car.root.rotation.y - this.train.travelYaw) >= 0 ? 1 : -1;
+  }
+
+  // `side` is chosen in the WORLD's terms (see cut). A locomotive that is propelling from the back of
+  // the train is turned end for end, so its own +X is the other flank — and a shot written in loco
+  // coordinates would stand on the town side of the line and film the back of the station.
+  locoSide() { return this.train.reversed ? -this.side : this.side; }
+
+  // A point in the TRAIN's frame: `f` metres forward of the LEAD CAR'S CENTRE, `s` to its right, `u`
+  // up. Taken off the leading car's own position, so it inherits the curve the train is actually on.
+  along(out, f, s, u) {
+    const lead = this.train.reversed ? this.train.cars[this.train.cars.length - 1] : this.train.cars[0];
+    const p = lead.root.position;
+    return out.set(p.x + this.fx * f + this.fz * s, p.y + u, p.z + this.fz * f - this.fx * s);
+  }
+
+  // Where a car IS, plus `up` — the aim point for anything filming the player's own coach.
+  aimCar(out, car, up) {
+    const p = car.root.position;
+    return out.set(p.x, p.y + up, p.z);
+  }
+
+  // THE GROUND, LOW-PASSED. A raw groundAt() under a lens doing 16 m/s samples the terrain lattice and
+  // steps with it, and a max() against a stepping floor is chatter — the exact thing this rig exists
+  // not to do. So the floor is a first-order lag (4/s): it still lifts the camera out of a rise, it
+  // just cannot buzz. Re-latched on every cut, because a cut may move the lens sixty metres.
+  floorAt(x, z, clear) {
+    const g = this.world.groundAt(x, z) + clear;
+    this.floor = this.floor == null ? g : this.floor + (g - this.floor) * this._k;
+    return this.floor;
+  }
+
+  cut(to) {
+    this.i = ((to ?? this.i + 1) % SHOTS.length + SHOTS.length) % SHOTS.length;
+    this.t = 0;
+    this.blockT = 0;
+    this.floor = null;
+    this._planted = null;
+    // WHICH FLANK THE EXTERIOR SHOTS STAND ON. The town is on the +z side of the line — that is the
+    // platform, the station building and the water tower, and it is the side train.js already steps
+    // you down onto (makeSeat: of the two sides, take the one nearer the town). So the lens takes the
+    // OTHER one: open desert, no building to bury it in, and the town in the background of the frame
+    // instead of pressed against the glass. The right-of-travel vector is (fz, −fx), so its z is
+    // −fx·side, and away from the town means driving that negative.
+    this.side = this.fx >= 0 ? 1 : -1;
+  }
+
+  // ── the one call player.js makes ────────────────────────────────────────────────────────────
+  // Returns TRUE when it owns the lens (and the mouse is dead), FALSE when it has handed it back.
+  update(dt, camera, player, input) {
+    const T = this.train;
+    // A NEW RIDE IS A NEW CYCLE. The rig lives on the seat host for the life of the game (no
+    // allocation on boarding, and none on alighting either), so it notices a change of rider itself
+    // and needs no hook in train.js's board/alight to do it.
+    if (this.was !== this.host.rider) {
+      this.was = this.host.rider;
+      this.i = 0; this.t = 0; this.grace = GRACE; this.off = false;
+      this.floor = null; this.blockT = 0; this._planted = null;
+    }
+
+    const ui = this.game.ui;
+    const menu = ui?.menuOpen || ui?.dialogueOpen;
+    if (!menu && input) {
+      // TRIANGLE works the lens from the pad (Nick): the pad synthesizes Triangle as KeyQ, and Q
+      // is free aboard — the weapon cycle lives in combatInputs, which the aboard path never runs.
+      if (input.hit('KeyV') || input.hit('KeyQ')) { this.off = !this.off; this.grace = 0; input.consume('KeyV'); input.consume('KeyQ'); }
+      if (input.hit('KeyC') && !this.off) { this.cut(); this.grace = 0; input.consume('KeyC'); }
+    }
+
+    // HAND IT BACK, INSTANTLY. He reached for the gun, he is reloading, he took a round, a fight
+    // started, he died, she has stopped at a platform, or he asked for it back.
+    //
+    // gunInputs does not run at all on the aboard path (player.js returns above it at :582), so
+    // `aiming` and `drawn` can never LATCH while he is sitting down — the RAW right button is the only
+    // honest test of "he is trying to bring the gun up", and it is the one that matters. (`drawn` is
+    // still tested, because a man can board with it already in his hand — and train.js's board() takes
+    // it off him for exactly that reason, so this is the belt to that pair of braces.)
+    const armed = player.aiming || player.drawn || player.reloading || player._drawT > 0
+      || (input?.acting && (input.held(2) || input.held(0)));
+    const fight = player._combatT > 0 || this.game._inCombat || !player.alive;
+    // ...and STANDING AT A CALL is not a journey. Cutting between six angles of a train that is not
+    // moving is a slideshow, and the man in it is trying to find the door: give him back his own
+    // camera and his mouse the moment she comes to a stand.
+    if (this.off || armed || fight || T.stabled || T.speed < ROLLING) {
+      this.hold(player);
+      return false;
+    }
+
+    if (this.grace > 0) { this.grace -= dt; this.hold(player); return false; }
+
+    // THE MATRICES OF THE TWO CARS THIS RIG READS. See rule 3 at the top: three rebuilds matrixWorld at
+    // render, and a shot written in a car's own frame off last frame's matrix is 27 cm of lag at line
+    // speed, jittering with the frame time. host.sync() has already refreshed the player's car; the
+    // LOCO's is only fresh as a side effect of its crew's IK solve, and the crew can be shot.
+    this.loco.root.updateWorldMatrix(false, false);
+
+    this._k = Math.min(1, dt * 4);
+    this.fx = Math.sin(T.travelYaw);
+    this.fz = Math.cos(T.travelYaw);
+
+    this.t += dt;
+    let S = SHOTS[this.i];
+
+    // Take the shot. A shot that cannot be taken (nothing to pass, no clear line, a loco on the wrong
+    // end of the train) is SKIPPED rather than shown — a camera pointing at sand for five seconds is
+    // worse than a shorter cycle. The bounded loop is the whole safety argument: it can never spin,
+    // and if every shot in the list refuses, the follow camera takes over.
+    for (let tries = 0; tries < SHOTS.length; tries++) {
+      S = SHOTS[this.i];
+      if (this._planted !== S) {
+        if (S.plant && !S.plant(this)) { this.cut(); continue; }
+        this._planted = S;
+      }
+      if (S.shot(this, Math.min(1, this.t / S.dur)) !== false) break;
+      this.cut();
+    }
+    if (this._planted !== SHOTS[this.i]) { this.hold(player); return false; }
+
+    // THE SIGHTLINE. A rock, a shed or the water tower between the lens and the train is a black frame,
+    // and the user WILL see it. Tested every third frame (it is a BVH raycast, and 25 ms of latency on
+    // a cut-away is invisible), and only after BLOCK_CUT of it, so a fence post flicking through frame
+    // is a wipe and not a bug.
+    if (S.guard) {
+      this._f++;
+      if (this._f % 3 === 0 && this.world.segmentBlocked(_p, _t)) this.blockT += dt * 3;
+      else this.blockT = Math.max(0, this.blockT - dt);
+      if (this.blockT > BLOCK_CUT) this.cut();
+    }
+
+    camera.position.copy(_p);
+    camera.lookAt(_t);
+    if (this.t >= S.dur) this.cut();
+    return true;
+  }
+
+  // Handing the lens back. The follow camera EASES toward its target (player.js: lerp on rdt*10), so
+  // without a snap it would swoop in from sixty metres away over half a second — with a gun in his hand
+  // and someone shooting at him. So it CUTS, and it cuts to a camera that is already behind his head:
+  // camYaw is re-derived from the car's CURRENT heading, because the carriage has been going round
+  // curves since he sat down and the yaw board() gave him is a minute stale.
+  //
+  // ...and the shot that was up is ABANDONED, not paused. Come back to it after ten seconds of a
+  // gunfight and its trackside tripod is a hundred and sixty metres behind the train, filming the
+  // desert. The take restarts from the top when the film does.
+  hold(player) {
+    if (this._held) return;
+    this._held = true;
+    this.t = 0;
+    this._planted = null;
+    this.floor = null;
+    player._camSnap = true;
+    player.camYaw = this.host.car.root.rotation.y + (this.host.seat?.ry ?? 0) + Math.PI;
+    player.camPitch = 0.06;
+  }
+}
+
+// The prompt, so the keys are discoverable without a manual. main.js renders whatever the interactable
+// hands it and splits on the first dash, so the leading "E —" is what lights up as the key cap.
+const PROMPT = 'E — Get off  ·  C next shot  ·  V free camera';
+
+// Hang a rig on a seat host. Built ONCE, on the loading screen, with the train — nothing here is
+// allocated when he boards. player.js calls host.camera() while he is aboard and falls back to the
+// ordinary follow camera the moment it answers false. A stagecoach host has no `camera` field at all,
+// which is exactly why the coach is untouched by any of this.
+export function attachTrainCamera(train, host) {
+  const rig = new TrainCamera(train, host);
+  host.cam = rig;
+  host.camPrompt = PROMPT;
+  host.camera = (dt, camera, player, input) => {
+    const on = rig.update(dt, camera, player, input);
+    if (on) rig._held = false;
+    return on;
+  };
+  return rig;
+}