sindicate 0.2.0 → 0.5.0

package/src/systems/traveller.js

@@ -0,0 +1,254 @@
+// ROAD WALKERS — the men and women who are actually going somewhere.
+//
+// A Traveller IS AN NPC. That is the whole design, and everything good about this file falls out of
+// it: he lives in game.npcs, so combat.js's bullet loop and melee arc find him, crime.js counts him
+// as a witness and calls his killing a MURDER, loot.js spills his purse, alarmTown scatters him with
+// the rest of the street, the stagecoach's look-ahead (coach.js _blocked) brakes for him, and
+// entity.js's whisker steering makes the townsfolk walk round him. Not one of those systems needed a
+// line adding. He is a townsman whose beat happens to be forty minutes long.
+//
+// The one thing he does differently is WHERE HE WALKS: NPC's wanderUpdate strolls a route of street
+// points, and his overrides it with a road. So this file is the road, and nothing else.
+//
+// PERF CONTRACT (main.js:118 / npc.js): built ONCE on the loading screen, resident and scene-attached
+// for life. Nothing here adds, removes or toggles a skinned mesh — Character.update's own distance +
+// frustum cull is the only thing that hides him.
+import { NPC } from './npc.js';
+// road routes are GAME data: setTravellerRoutes(routes)
+let ROUTES = [];
+export function setTravellerRoutes(r) { ROUTES = r ?? []; }
+import { steerCarrot, nearestEndpoint } from './pathFollow.js';
+import { dist2D, tmpV1, tmpV2 } from '../core/utils.js';
+
+const _faim = { x: 0, z: 0 };   // scratch: the point steerCarrot hands a foot traveller to aim at
+
+// ── WHAT A ROAD TRAVELLER IS. Shared with mountedTraveller.js, because a horseman keeps to the same
+//    side of the same road, in the same daylight, and pays the same rent. One definition, two riders.
+
+// HOW FAR OFF YOU SEE A MAN ON THE OPEN ROAD.
+//
+// A townsman is culled at 45/70/110 m by quality (core/quality.js entityCull) and that is right for a
+// town: there is a building in front of him. A road traveller is out on a flat plain with a mile of
+// nothing either side, and a man who winks out of existence at seventy metres of empty desert is the
+// most expensive thing in this file — you notice him GO.
+//
+// So he gets further. But it is a MULTIPLE of the quality cull, not a number that ignores it: 45 m on
+// a low machine is 45 m for a reason, and a rule that hands a weak GPU thirty extra skinned bodies at
+// 140 m is not a rule, it is a bug with a comment. 1.6x, capped: low 72 m, medium 112 m, high 140 m.
+const CULL_MULT = 1.6;
+const CULL_MAX = 140;
+export const roadCull = (game) => Math.min(CULL_MAX, (game.quality?.entityCull ?? 70) * CULL_MULT);
+
+// KEEP RIGHT — 3.6 m off the centreline, and the number is arithmetic, not taste.
+//
+// The stagecoach drives 1.15 m right of the centreline (coach.js LANE) and brakes for anything inside
+// a 2.0 m half-width corridor ahead of her (CORRIDOR). A traveller at 3.6 m is 2.45 m off her line —
+// so she OVERTAKES him at a canter instead of crawling behind him for the length of the county, and
+// passes about a metre and a quarter from his elbow. Meeting him head-on she is on the other side of
+// the road entirely (her right is his left): 4.75 m apart. And the road's carriageway is graded
+// full-strength out to 3.5 m and paints dirt to ~10 (terrainData rawHeight), so 3.6 m is the SHOULDER
+// of the road, which is exactly where a man on foot walks and where a horse is ridden.
+export const LANE = 3.6;
+
+// THE WORKING DAY. The sky runs 24 game-hours per 15 real minutes (world/sky.js), so this is 8 real
+// minutes of road traffic and 4½ of empty road — the right ratio for a county whose night is supposed
+// to feel like something.
+export const DAWN = 6.5, DUSK = 19.5;
+
+// PAST THIS HE IS NOT WORTH A BVH SWEEP. It is the same 45 m at which entity.js's walkDir already
+// switches its whisker probes off, so beyond it the capsule controller is sweeping the world BVH for a
+// man walking down the middle of a graded, empty, dead-straight road — buying nothing. Terrain-follow
+// only out there, exactly as horse.js does for its ambient grazers ("NO BVH… a needless cost").
+export const BVH_R = 45;
+
+// A MAN ON THE RAILS WHEN A TRAIN IS COMING — see railShut() at the bottom.
+const XING_CLEAR = 12;
+const XING_FLEE = 3;
+
+const ARRIVE = 2.2;         // waypoints are 20-30 m apart (world/scale.js dens): this never skips a leg
+const BLOCKED_ARRIVE = 3.4; // …but if something is parked on the waypoint, take the next leg instead
+
+// WHERE HE AIMS: the waypoint, shoved onto HIS right-hand side of the road. Two travellers walking
+// opposite ways each keep their own right, so they pass each other rather than through each other.
+// `dir` is which way along the polyline he is going, so a man on the way back is on the other side of
+// the road — which is the whole of "keep right", and it comes out of the arithmetic for free.
+//
+// `spot` is his own personal patch of verge, applied only AT THE TWO ENDS OF A ROUTE. Nine of the
+// county's routes start on the same vertex — Dustwater's crossroads — so without it, come dusk, nine
+// travellers walk home and stand INSIDE one another in the middle of the street.
+//
+// IT IS EXPRESSED IN THE ROAD'S OWN FRAME, AND THAT IS NOT A STYLE CHOICE. `out` may only ever push
+// him FURTHER from the centreline, never toward it, because a man standing all night inside the
+// stagecoach's braking corridor (coach.js: 2.0 m half-width about a line 1.15 m right of centre) is a
+// coach that brakes at ten at night and is still standing there at dawn. A world-space jitter could
+// put him at x = 0.1 on the main street. This one cannot: the nearest he can ever stand to the
+// centreline is LANE itself, which is 2.45 m clear of her line. See verify-travellers.mjs [10].
+// …and at a CORNER the offset is MITERED — the bisector of the leg coming in and the leg going out,
+// which is how a polyline is offset and how a man actually walks a bend. Take the incoming leg alone
+// and he holds his old side of the road right up to the fork and then swings across it: at Ott's
+// track, which meets the street at 108 degrees, that put him 1.1 m from the centreline — in the
+// stagecoach's braking corridor, in the middle of a junction. The bisector cuts it to 2.1 m.
+export function laneTarget(out, road, i, dir, lane = LANE, spot = null) {
+  const b = road[i];
+  const leg = (from, to) => {
+    if (!from || !to) return null;
+    const x = to.x - from.x, z = to.z - from.z, L = Math.hypot(x, z);
+    return L < 1e-6 ? null : { x: x / L, z: z / L };
+  };
+  const inL = leg(road[i - dir], b) ?? leg(b, road[i + dir]);        // arriving at i…
+  const outL = leg(b, road[i + dir]) ?? inL;                          // …and leaving it
+  if (!inL) return out.set(b.x, 0, b.z);
+  let dx = inL.x + outL.x, dz = inL.z + outL.z;
+  const B = Math.hypot(dx, dz);
+  if (B < 0.2) { dx = inL.x; dz = inL.z; }                            // a hairpin: the bisector collapses
+  else { dx /= B; dz /= B; }
+  const end = spot && (i === 0 || i === road.length - 1);   // …only where they pile up
+  const off = lane + (end ? spot.out : 0);                  // out = AWAY from the road, never toward it
+  const along = end ? spot.along : 0;                       // …and spread up and down the verge
+  return out.set(b.x + dz * off + dx * along, 0, b.z - dx * off + dz * along);   // (dz, -dx) — the right-hand normal
+}
+
+// NOBODY IS STANDING ON THE RAILS WHEN A TRAIN COMES.
+//
+// train.js already parks a CrossingGuard — a coach-shaped blocker — on the level crossing whenever a
+// train is closing on it, because a blocker is the only language coach.js speaks. A man is not a coach
+// and cannot be told to brake, so he is told in HIS language: the same flee the whole street uses when
+// a shot goes off, pointed AT the crossing so it carries him away from it. He gets 12 s of warning
+// (train.js CROSS_WARN is 190 m at line speed) and 12 m to cover at a run of 3.6 m/s. Returns the
+// shut crossing he is standing on, or null.
+export function railShut(game, x, z) {
+  for (const gd of game.trains?.guards ?? []) {
+    if (gd.shut && dist2D(x, z, gd.at.x, gd.at.z) <= XING_CLEAR) return gd;
+  }
+  return null;
+}
+
+export class Traveller extends NPC {
+  constructor(game, def, clips) {
+    const rt = ROUTES[def.route];
+    if (!rt) throw new Error(`[traveller] ${def.id}: no such route '${def.route}'`);
+    const last = rt.pts.length - 1;
+    const wp = Math.max(0, Math.min(last, Math.round((def.start ?? 0) * last)));
+    const p = rt.pts[wp];
+    // A roam disc of ZERO radius. It is what makes NPC's constructor put him on his own road rather
+    // than on Dustwater's street route, and what gives Character._navHome a sensible centre if
+    // anything ever asks him to path. He never roams it — wanderUpdate is overridden below.
+    super(game, { ...def, roam: { x: p.x, z: p.z, r: 0 } }, clips);
+
+    this.road = rt.pts;              // these vertices ARE terrainData's road vertices (data/travellers.js)
+    this.built = rt.built;           // …and where they run through a town, where the BVH stays on
+    this.routeName = def.route;
+    this.dir = def.dir ?? 1;
+    this._wp = Math.max(0, Math.min(last, wp + this.dir));   // the waypoint he is walking toward
+    this.speed = def.speed ?? 1.7;
+    this.pauseT = 0;
+    this.spot = { out: Math.random() * 2.5, along: (Math.random() - 0.5) * 12 };   // his own bit of the verge
+    this.setPosition(p.x, game.world.groundAt(p.x, p.z), p.z);
+    this.heading = Math.atan2(rt.pts[this._wp].x - p.x, rt.pts[this._wp].z - p.z);
+    this.root.rotation.y = this.heading;
+  }
+
+  // Character.update reads cullDist instead of quality.entityCull; npc.js reads aiRange as the range
+  // at which the AI sleeps. They are THE SAME NUMBER on purpose, so he walks for exactly as long as he
+  // is drawn. Get it wrong the other way and you have a man frozen mid-stride in the middle of an
+  // empty road, which is worse than not having him at all.
+  get cullDist() { return roadCull(this.game); }
+  get aiRange() { return this.cullDist; }
+
+  // THE ROAD. This replaces NPC's street-wander wholesale; everything above it in NPC.update — the
+  // cull, the sleep, the fear of a hunting outlaw, the flee, the reel after a bullet, the death, the
+  // murder report, the purse — is inherited untouched.
+  wanderUpdate(dt, player, pd) {
+    const g = this.game;
+    const xing = railShut(g, this.position.x, this.position.z);
+    if (xing) { this.scare(xing.at.x, xing.at.z, XING_FLEE, true); return; }   // get off the crossing
+
+    // DUSK AND DAWN. He does not stand where he is until sunrise — a man asleep in the middle of the
+    // ore road is a scarecrow. Both ends of every route are a settlement, so at dusk he turns for the
+    // NEARER one, walks to it, and stands there until it is light. That is why the roads empty at
+    // night: not because the AI stopped, but because everybody went home.
+    const hour = g.world.sky?.hour ?? 10;
+    const day = hour >= DAWN && hour < DUSK;
+    const last = this.road.length - 1;
+    if (day !== this._day) {
+      this._day = day;
+      if (!day) this.dir = this._wp * 2 <= last ? -1 : 1;                              // turn for the nearer end
+      else if (this._home) { this._home = false; this.dir = this._wp <= 0 ? 1 : -1; }  // …and set out again
+    }
+    if (this._home || this.pauseT > 0) {
+      // STANDING — but never standing INSIDE something. A route end (or a pause spot) can sit a
+      // hair inside a fence/prop, and a stood man runs no capsule move to push him out — the soak
+      // caught the ranch-road walker wintering inside Dustwater's east paddock rail. Correct once
+      // per stand; the flag rearms when he walks.
+      if (!this._standFixed) {
+        this._standFixed = true;
+        const c = this.game.world.collide(this.position.x, this.position.z, 0.4, 0, this.position.y);
+        if (c && Math.hypot(c.x - this.position.x, c.z - this.position.z) > 0.02) {
+          this.position.x = c.x; this.position.z = c.z;
+        }
+      }
+      if (this.pauseT > 0) this.pauseT -= dt;
+      this.socialIdle(dt);
+      return;
+    }
+    this._standFixed = false;
+
+    // tmpV2, not tmpV1: `dir` below is built in tmpV1 FROM this, and one shared scratch vector holding
+    // both the target and the direction to it is a bug waiting for someone to reorder two lines.
+    const t = laneTarget(tmpV2, this.road, this._wp, this.dir, LANE, this.spot);
+    const td = dist2D(this.position.x, this.position.z, t.x, t.z);
+    // Arrive EARLY when something is parked on the waypoint (a cart, another walker): take the next
+    // leg rather than pressing into whatever is sitting on the point.
+    if (td <= (this._steerBlockAhead ? BLOCKED_ARRIVE : ARRIVE)) { this._advance(); return; }
+
+    // STUCK. moveCapsule slides along static geometry, it does not path around it, so a building
+    // corner or a hitching rail can stop a man dead against a waypoint he will never reach. Skip the
+    // leg rather than tread water beside it for the rest of the game.
+    this._stuckT = (this._stuckT ?? 0) + dt;
+    if (this._stuckT >= 1.4) {
+      const moved = dist2D(this.position.x, this.position.z, this._lastX ?? this.position.x, this._lastZ ?? this.position.z);
+      this._lastX = this.position.x; this._lastZ = this.position.z; this._stuckT = 0;
+      if (moved < 0.5) { this._advance(); return; }
+    }
+
+    // The BVH is on inside 45 m of the player — and ALWAYS where the road runs through a town, whoever
+    // is watching. A man who walks through the front of the store because you were sixty metres away
+    // is not a saving. (data/travellers.js `built`.)
+    if (pd < BVH_R || this.built[this._wp]) {
+      // STATIC obstacles (a hitching rail, a building corner, a fence across the verge) are routed
+      // AROUND via the settlement's baked grid A*; the whiskers below then handle only DYNAMIC dodging
+      // (people, carts). When the way to the lane target is clear this is free and aims straight at it.
+      let ax = t.x, az = t.z;
+      const centre = nearestEndpoint(this.road, this.position.x, this.position.z);
+      if (steerCarrot(this, g, centre, this.position.x, this.position.z, t.x, t.z, _faim, { dt, arrive: ARRIVE })) { ax = _faim.x; az = _faim.z; }
+      const dir = tmpV1.set(ax - this.position.x, 0, az - this.position.z).normalize();
+      const sd = this.walkDir(dir, dt);                        // whiskers: swerve round people and props
+      this.move(sd, this.speed * (this._steerSlow ? 0.55 : 1), dt);
+      this.faceToward(this.position.x + sd.x, this.position.z + sd.z, dt);
+    } else {
+      this._rtPath = null;                                     // open road: no statics to route around
+      const dir = tmpV1.set(t.x - this.position.x, 0, t.z - this.position.z).normalize();
+      const s = this.speed * dt;                               // terrain-follow only, no BVH
+      this.position.x += dir.x * s;
+      this.position.z += dir.z * s;
+      this.position.y = g.world.groundAt(this.position.x, this.position.z);
+      this.vy = 0;                                             // the capsule takes over again inside 45 m
+      this.faceToward(this.position.x + dir.x, this.position.z + dir.z, dt);
+    }
+    this.play('walk');
+  }
+
+  // On to the next waypoint. At the end of the road he turns round and takes a breath — unless he is
+  // going home for the night, in which case he has arrived, and he stands.
+  _advance() {
+    const next = this._wp + this.dir;
+    if (next < 0 || next >= this.road.length) {
+      if (!this._day) { this._home = true; return; }
+      this.dir = -this.dir;
+      this.pauseT = 2 + Math.random() * 4;
+      this._wp += this.dir;
+      return;
+    }
+    this._wp = next;
+  }
+}

package/src/systems/tumbleweeds.js

@@ -0,0 +1,92 @@
+// BLOWING TUMBLEWEEDS — a small pool of tumbleweeds that roll across the ground on the GLOBAL WIND
+// (world/wind.js), following the terrain, catching on fences and shouldered aside by walls, recycled
+// upwind whenever one blows too far from the player so there are always a few tumbling through view.
+// Mirrors the herd/casino cast pattern: one InstancedMesh built once at boot, ticked every frame.
+//
+// It reuses the geometry + atlas material of the town's own static tumbleweed prop (already built and
+// textured by town.js), so there is no second model load and it matches the world exactly.
+import * as THREE from 'three/webgpu';
+// register the terrain height query before update: setTumbleweedTerrain({ heightAt })
+let TT = { heightAt: () => 0 };
+export function setTumbleweedTerrain(t) { TT = { ...TT, ...t }; }
+
+const R = 0.318;             // measured tumbleweed radius (origin at its CENTRE → it rests at heightAt + R·scale)
+const COUNT = 14;            // how many are live at once
+const RING = 52;            // spawn ring radius around the player
+const CULL = 82;            // recycle once this far from the player (just past the spawn ring)
+const _m = new THREE.Matrix4(), _p = new THREE.Vector3(), _q = new THREE.Quaternion(), _s = new THREE.Vector3();
+const _ax = new THREE.Vector3(), _tv = new THREE.Vector3(), _push = new THREE.Vector3();
+const _UP = new THREE.Vector3(0, 1, 0);
+
+export class Tumbleweeds {
+  constructor(game) { this.game = game; this.weeds = []; }
+
+  async load() {
+    // borrow the town's tumbleweed geometry + material (no second load; guaranteed to match the world)
+    let geo = null, mat = null;
+    this.game.scene.traverse((o) => { if (!geo && o.isMesh && /Tumbleweed/i.test(o.name || '')) { geo = o.geometry; mat = o.material; } });
+    if (!geo) return this;   // the pack build has no tumbleweed → nothing to blow
+    this.mesh = new THREE.InstancedMesh(geo, mat, COUNT);
+    this.mesh.name = 'tumbleweeds:live';
+    this.mesh.frustumCulled = false; this.mesh.castShadow = false; this.mesh.receiveShadow = true;
+    this.game.scene.add(this.mesh);
+    const p = this.game.player?.position ?? { x: 0, z: 0 };
+    for (let i = 0; i < COUNT; i++) {
+      const w = { x: 0, z: 0, q: new THREE.Quaternion(), scl: 0.65 + Math.random() * 0.75, drag: 0.55 + Math.random() * 0.4, stuck: 0 };
+      this._respawn(w, p, true);
+      this.weeds.push(w); this._write(i, w);
+    }
+    this.mesh.instanceMatrix.needsUpdate = true;
+    return this;
+  }
+
+  // (re)place a weed. On first fill scatter it all round the player; after that drop it UPWIND (fanned to
+  // the sides) so it blows back across view rather than popping in beside you.
+  _respawn(w, p, initial) {
+    const wind = this.game.wind;
+    const toward = wind ? Math.atan2(wind.z, wind.x) : Math.random() * Math.PI * 2;
+    const a = initial ? Math.random() * Math.PI * 2 : (toward + Math.PI) + (Math.random() - 0.5) * 1.6;
+    const d = initial ? Math.random() * RING : RING * (0.7 + Math.random() * 0.5);
+    w.x = p.x + Math.cos(a) * d; w.z = p.z + Math.sin(a) * d;
+    w.q.setFromAxisAngle(_ax.set(Math.random() - 0.5, Math.random() - 0.5, Math.random() - 0.5).normalize() || _UP, Math.random() * 6.2832);
+    w.stuck = 0;
+  }
+
+  _write(i, w) {
+    _p.set(w.x, TT.heightAt(w.x, w.z) + R * w.scl, w.z);
+    this.mesh.setMatrixAt(i, _m.compose(_p, w.q, _s.setScalar(w.scl)));
+  }
+
+  update(dt) {
+    if (!this.mesh) return;
+    const p = this.game.player?.position, wind = this.game.wind;
+    if (!p || !wind) return;
+    dt = Math.min(dt, 0.05);
+    const world = this.game.world;
+    for (let i = 0; i < this.weeds.length; i++) {
+      const w = this.weeds[i];
+      const rad = R * w.scl;
+      let nx = w.x + wind.vx * w.drag * dt;
+      let nz = w.z + wind.vz * w.drag * dt;
+      // one call clears it of BOTH fence capsules/trees (it catches) AND building walls (it's shouldered
+      // aside) — the same push-out a coach uses. A weed pinned against a wall for a beat is recycled.
+      if (world?.solidPush) {
+        world.solidPush(nx, TT.heightAt(nx, nz) + rad, nz, rad, _push);
+        nx += _push.x; nz += _push.z;
+        if (_push.x * _push.x + _push.z * _push.z > 0.02) {
+          w.stuck += dt;
+          if (w.stuck > 2.2) { this._respawn(w, p, false); this._write(i, w); continue; }
+        } else w.stuck = 0;
+      }
+      const dx = nx - w.x, dz = nz - w.z, dist = Math.hypot(dx, dz);
+      if (dist > 1e-4) {                                   // roll: spin about the horizontal axis ⟂ to travel
+        _ax.copy(_UP).cross(_tv.set(dx, 0, dz)).normalize();
+        w.q.premultiply(_q.setFromAxisAngle(_ax, dist / rad));
+      }
+      w.x = nx; w.z = nz;
+      if ((w.x - p.x) ** 2 + (w.z - p.z) ** 2 > CULL * CULL) this._respawn(w, p, false);
+      this._write(i, w);
+    }
+    this.mesh.instanceMatrix.needsUpdate = true;
+  }
+}