sindicate 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,121 @@
 # Changelog
 
+## 0.18.0 — two regressions, caught from outside
+
+Everything here came from a third game running against 0.17.0 and reporting back. One fix I
+shipped broken, one fix I shipped incomplete, and both were found by a consumer rather than by
+me. Nothing else changed, and western and fable do not move.
+
+### Fixed
+
+- **`RETRIGGER_AT` was undeclared** (`core/anim.js`), so 0.17.0's own one-shot guard threw a
+  `ReferenceError` on the exact path it was written to protect — re-triggering a one-shot that is
+  still playing. Western was affected too: a revolver re-triggering its fire clip does that on
+  every second shot. Frame-hook isolation caught it rather than killing the frame, which is the
+  only reason it was not immediately fatal, but the one-shot silently did not play.
+- **A split answer's overlay ran as an infinite loop.** `setOverlay` defaults to
+  `LoopRepeat/Infinity`, and the `{ base, overlay }` shape did not say otherwise, so a reload
+  overlay played for ever. The answer is now `{ base, overlay, once }`. It cannot be inferred: a
+  reload or holster overlay is a one-shot, a held aim pose must loop, and both are legitimate
+  answers to the same question.
+
+### Changed
+
+- `locomotionClip` may answer `{ base, overlay, once }` as well as a clip name — a body split is
+  two simultaneous answers and one name cannot express both — and the engine now asks BEFORE
+  dropping the overlay rather than after. Dropping it first rewound the overlay sixty times a
+  second, which a game could only stop by patching `setOverlay`. A string answer behaves exactly
+  as in 0.17.0; `null`/`undefined` still mean the engine owns the slot.
+
+### The lesson, recorded because it caused both
+
+Both regressions survived because I verified the wrong layer. `node --check` passes on an
+undeclared identifier — it is a runtime `ReferenceError`, not a syntax error — and a test that
+watches what was *asked for* is blind to what the ask *did*. The tests now drive the real
+per-frame sequence and watch the animation across more than one clip length. An edit anchored on
+`import * as THREE from 'three';` also silently matches nothing in a file that imports from
+`'three/webgpu'`, which is how the constant went missing in the first place.
+
+## 0.17.0 — towns, and a third game's report card
+
+Two halves. Cities — the thing the road system was always for. And the first pass through
+`ISSUES.md`, raised from building a **third** game (MilitaryGame/"Blacksand", a military game on
+Synty + Kubold + Kevin Iglesias packs) against 0.16.0 as a published dependency rather than a
+file link. Every fix in that half defaults to exactly the previous behaviour, so western and
+fable do not move.
+
+### Cities (new: `world/cityPlan.js`, `world/settlement.js`, `world/mapWorld.js`)
+
+- `world/cityPlan.js` — a settlement as a street grid whose faces are BLOCKS, zoned. Terrain is a
+  veto: water and slope reject a cell outright, population decides how many of the survivors get
+  built on, and the town grows outward from its middle so it is one place rather than a rash of
+  hamlets. Junctions are classified by arm count — and two arms is **not one case**: two opposite
+  arms are a street running through, two perpendicular are a corner.
+- `world/settlement.js` — `planBlockFrontage` fills the blocks, which is the step Kiwi's own
+  `BlockData` marks "for building placement later" and never took. Buildings stand on the block
+  boundary facing the street; a model's odds decay as it is used, so a pack of sixteen renders as
+  sixteen rather than five. `hasFrontage` refuses motorways and dual carriageways outright —
+  nothing in the world fronts one.
+- `world/mapWorld.js` — several places and the roads between them. A city exposes `exits`, shaped
+  like a road-kit socket, so `buildRoadLink` joins town to motorway with no special case.
+- `world/roadLink.js` — extrudes a **cross-section with height in it** when a socket carries one:
+  kerb, gutter and raised footway are in the profile, not laid separately. Four surfaces on their
+  own texels, and the past-the-kerb rule that decides which is which.
+- `world/roadTerrain.js` — a corridor now declares whether it carries tarmac (`deck: false` for
+  pure earthwork), and coverage stops at the ends of a line instead of claiming a half-disc of
+  phantom road beyond them.
+
+**The lesson that cost the most, recorded because it will recur:** the earthworks were tuned by
+eye against a height FUNCTION, while every fault lived in the drawn LATTICE. Between two vertices
+straddling a cut the mesh interpolates straight across, so 12 cm of clearance vanishes on a 3.8 m
+cell. Kiwi's own figures — a 1.0 m road bed and a 5 m skirt — are an order of magnitude bigger
+than the ones guessed here for exactly that reason.
+
+### Reported by a third game (`ISSUES.md`, all 14 items)
+
+- **A guarded object is not a guarded method.** `game.audio?.loadSamples(map)` guards `audio`
+  alone; 59 call sites across 13 files had the same shape. And frame hooks ran unguarded, so one
+  throw silently killed every system registered after it — reported as grenades hanging in
+  mid-air with frozen fuses, four systems from a footstep sound. Hooks are now isolated, and a
+  hook that throws eight times is retired rather than logged at 60 Hz.
+- **Masks follow their source clip.** A game re-registering a logical clip (a weapon switch) kept
+  masks pointing at the boot weapon for ever. And a one-shot re-triggered faster than it plays is
+  no longer restarted — 200 restarts over 19 s becomes 34.
+- **`climbing.js` referenced an undeclared `REACH`**, so its proximity-mount path threw on sight;
+  it also read only fable's `world.castle.ladders`. Both fixed, plus `setLadders()`.
+- **`createCar()` spawned from the default ride height** while every later frame used the
+  configured one — a vehicle at 0.9 started 0.56 m low and popped up.
+- Perf timers are both held and cleared; an unset `qualityName` no longer answers a BAD framerate
+  by stepping quality **up**.
+- Dead `setTrainContent` keys say so; an unknown walk-hump is scenery rather than a crash, with
+  `setHumpDims()` to teach it.
+
+### Declared overrides (new: `core/overrides.js`)
+
+Named decisions a game may answer for itself, registered at construction and never patched at
+runtime. It overrides **decisions, not methods** — `play`'s signature is implementation shape and
+will move; "what should the body be playing?" is a question with a stable contract. Registering
+nothing, or answering `null`, is byte-identical to before. Unknown names and non-functions throw
+at construction; an override that throws at runtime is caught and the engine's own answer used.
+
+First point: `locomotionClip`. The full-body clip per gun state is right for western's gunslinger
+pack and wrong for Kubold's rifle set, which has one standing reload — so walking into a reload
+stopped the legs dead.
+
+### Also injected rather than assumed
+
+- `AudioSystem` takes an `sfxManifest`; western's list is exported as `DUSTWATER_SFX(dirs)`.
+- Seated-pose assets take `setSeatedContent({ rig, clips, audioDir })` — a soldier in a tank hatch
+  wants the same retarget as a rider on a horse.
+- The weapon table derives from what the game registered. Only three lines ever named western's
+  weapons, and they were what made the constructor throw without both `revolver` and `rifle`.
+
+### Notes
+
+- True N-slot weapons, the seat/occupant abstraction, and `city` support in `roadAssert` are
+  deliberately **not** in this release. Each is scheduled rather than landed opportunistically.
+- The city modules are new and may still move before 1.0.
+
 ## 0.16.0 — driving on it
 
 ### A car (new: `vehicle/`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sindicate",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Sindicate — open-world game engine for three.js WebGPU. Streaming worlds, characters, mounts & vehicles, missions, crowds.",
   "type": "module",
   "main": "src/index.js",

package/src/audio/synth.js

@@ -10,9 +10,24 @@
 //   new AudioSystem({ sfx, muted, sfxDirs, storageKey })
 
 
+// The default manifest: western's recorded SFX, kept here rather than inline in loadSfx() so
+// that a game replacing it can still see — and reuse — what the engine used to assume.
+export function DUSTWATER_SFX({ combat: C, ui: U } = {}) {
+  const map = {};
+  for (let i = 1; i <= 6; i++) { map[`swing${i}`] = `${C}/swing${i}.wav`; map[`hit${i}`] = `${C}/hit${i}.wav`; }
+  for (let i = 1; i <= 3; i++) map[`block${i}`] = `${C}/block${i}.wav`;
+  for (let i = 1; i <= 4; i++) map[`boom${i}`] = `${C}/boom${i}.wav`;
+  map.uiclick1 = `${U}/uiclick1.wav`;
+  for (let i = 1; i <= 2; i++) map[`coin${i}`] = `${U}/coin${i}.wav`;
+  for (let i = 1; i <= 3; i++) map[`orb${i}`] = `${U}/orb${i}.wav`;
+  for (const e of ['heal', 'quest', 'questDone', 'renown', 'levelup']) map[`${e}1`] = `${U}/${e}1.wav`;
+  return map;
+}
+
 export class AudioSystem {
-  constructor({ sfx = {}, muted = [], sfxDirs = { combat: '/assets/audio/combat', ui: '/assets/audio/ui' }, storageKey = 'av_volSfx' } = {}) {
+  constructor({ sfx = {}, muted = [], sfxDirs = { combat: '/assets/audio/combat', ui: '/assets/audio/ui' }, storageKey = 'av_volSfx', sfxManifest = null } = {}) {
     this._sfx = sfx;
+    this._sfxManifest = sfxManifest;
     this._muted = new Set(muted);
     this._sfxDirs = sfxDirs;
     this._storageKey = storageKey;
@@ -127,19 +142,22 @@ export class AudioSystem {
     src.start(t0); src.stop(t0 + dur);
   }
 
-  // Lazily load all recorded SFX (combat swing/hit/block/boom + ui/coin/orb/heal/quest/level-up).
-  // Called from ensure() once the context exists; sample() no-ops until they finish decoding.
+  // Lazily load all recorded SFX. Called from ensure() once the context exists; sample()
+  // no-ops until they finish decoding.
+  //
+  // WHICH SAMPLES EXIST IS GAME DATA. This built a fixed list of western's names — swing1..6,
+  // hit1..6, block1..3, boom1..4, and the UI cues — and ensure() calls it unconditionally, so
+  // a game with different audio took about thirty 404s on its first sound and had no way to
+  // stop it but overriding the method. The class comment already said recorded SFX are "GAME
+  // data — pass at construction", and `sfx` and `sfxDirs` already arrive that way; the loader
+  // simply did not follow.
+  //
+  // `sfxManifest` is either a { name: url } map or a function of the sfx dirs returning one.
+  // Absent, it is western's list exactly as before — so western and fable do not move.
   loadSfx() {
-    const C = this._sfxDirs.combat, U = this._sfxDirs.ui;
-    const map = {};
-    for (let i = 1; i <= 6; i++) { map[`swing${i}`] = `${C}/swing${i}.wav`; map[`hit${i}`] = `${C}/hit${i}.wav`; }
-    for (let i = 1; i <= 3; i++) map[`block${i}`] = `${C}/block${i}.wav`;
-    for (let i = 1; i <= 4; i++) map[`boom${i}`] = `${C}/boom${i}.wav`;
-    map.uiclick1 = `${U}/uiclick1.wav`;
-    for (let i = 1; i <= 2; i++) map[`coin${i}`] = `${U}/coin${i}.wav`;
-    for (let i = 1; i <= 3; i++) map[`orb${i}`] = `${U}/orb${i}.wav`;
-    for (const e of ['heal', 'quest', 'questDone', 'renown', 'levelup']) map[`${e}1`] = `${U}/${e}1.wav`;
-    this.loadSamples(map);
+    const m = this._sfxManifest;
+    const map = typeof m === 'function' ? m(this._sfxDirs) : (m ?? DUSTWATER_SFX(this._sfxDirs));
+    this.loadSamples(map ?? {});
   }
 
   // gainMul (default 1) scales the sound's volume — the hook for distance-attenuated one-shots: a

package/src/core/anim.js

@@ -2,6 +2,11 @@
 // with automatic retargeting per character rig.
 import * as THREE from 'three/webgpu';
 import { buildRetargetContext, retargetClip } from './retarget.js';
+
+// How far a one-shot must have played before another play() will restart it, as a fraction of
+// its duration. Below this the call is ignored and the clip runs on — see play(). A caller may
+// override per call with `retrigger`.
+const RETRIGGER_AT = 0.5;
 // Per-clip timing (start/speed/end trims) and the clip->source-rig table are GAME
 // DATA, not engine code — a game registers them once at boot:
 //   setClipDefaults({ timing: CLIP_TIMING, rigs: CLIP_RIGS })
@@ -57,12 +62,24 @@ export class Animator {
     const ctx = this._ctxFor(this.clipRigs?.[name] ?? null);
     const action = this.mixer.clipAction(retargetClip(clip, ctx));
     this.actions[name] = action;
+    // A MASK IS DERIVED FROM A CLIP, so re-registering the clip must rebuild it. Masks were
+    // snapshotted at build time and never invalidated, so a game that re-registers a logical
+    // name later — one that swaps weapons by re-registering `gunFire`, say — kept masks
+    // pointing at whatever was loaded at boot. Every weapon then fired and reloaded like the
+    // one you spawned with, silently and for ever. The engine created the derivations, so it
+    // is the engine's job to know them.
+    for (const d of this._derived?.get(name) ?? []) this.registerMasked(d.name, name, d.keepFn);
   }
 
   // Build a bone-masked copy of an already-registered clip (keeps only tracks whose
   // bone passes keepFn). Used to split locomotion across body halves — e.g. legs
   // from `walk` + torso/arms from `blockLoop` so you can walk with the guard up.
   registerMasked(name, srcName, keepFn) {
+    // remembered so register() can rebuild it — see the note there
+    const list = (this._derived ??= new Map()).get(srcName) ?? [];
+    if (!list.some((d) => d.name === name)) list.push({ name, keepFn });
+    this._derived.set(srcName, list);
+
     const src = this.actions[srcName];
     if (!src) return;
     const clip = src.getClip().clone();
@@ -125,6 +142,16 @@ export class Animator {
     const timeScale = opts.timeScale ?? tm.speed ?? 1;
     if (this.currentName === name && !restart && !once) return action;
 
+    // A ONE-SHOT RE-TRIGGERED FASTER THAN IT PLAYS IS NOT A ONE-SHOT. One-shots deliberately
+    // skip the early return above so each call restarts them, which is right for a revolver
+    // and wrong for an M4: at a 0.095 s rate a 1 s full-body fire clip restarts ten times a
+    // second and the whole body jitters. Let it run unless it has advanced far enough to be
+    // worth restarting, or the caller insists with `restart`.
+    if (once && !restart && this.current === action && action.isRunning()) {
+      const dur = action.getClip().duration || 0;
+      if (dur > 0 && action.time < dur * (opts.retrigger ?? RETRIGGER_AT)) return action;
+    }
+
     action.reset();
     if (startFrac > 0) action.time = action.getClip().duration * startFrac;
     action.timeScale = timeScale;

package/src/core/engine.js

@@ -16,9 +16,13 @@
 //   engine.start()                               // hands the loop to the renderer
 import * as THREE from 'three/webgpu';
 import { tune } from './tune.js';
+import { Overrides } from './overrides.js';
+
+// how many times a frame hook may throw before the engine stops calling it
+const HOOK_THROW_LIMIT = 8;
 
 export class Engine {
-  constructor({ renderer, scene, camera, input, post = null, isPaused = () => false, isUiModal = () => false }) {
+  constructor({ renderer, scene, camera, input, post = null, isPaused = () => false, isUiModal = () => false, overrides = null }) {
     this.renderer = renderer;
     this.scene = scene;
     this.camera = camera;
@@ -26,6 +30,10 @@ export class Engine {
     this.post = post;
     this.isPaused = isPaused;
     this.isUiModal = isUiModal;
+    // NAMED DECISIONS A GAME MAY ANSWER FOR ITSELF — see core/overrides.js. Passing nothing
+    // is byte-identical to before; an unknown name or a non-function throws here, at
+    // construction, rather than at frame 900.
+    this.overrides = new Overrides(overrides);
 
     // time
     this.rawDt = 0;
@@ -148,12 +156,26 @@ export class Engine {
   start() {
     this._clockLast = performance.now();
     this.renderer.setAnimationLoop(this.tick);
-    // auto perf log — first at 6s (past load hitches), then periodic
-    setTimeout(() => { this.perfReport(); this._perfTimer = setInterval(() => this.perfReport(), 15000); }, 6000);
+    // auto perf log — first at 6s (past load hitches), then periodic.
+    //
+    // BOTH TIMERS ARE HELD, and start() clears whatever is already running. stop() used to
+    // clear only the interval — so stopping inside the first six seconds left the timeout to
+    // fire afterwards and install an interval nothing would ever clear, and calling start()
+    // twice stacked a timeout and an interval each time.
+    this._stopPerfTimers();
+    this._perfDelay = setTimeout(() => {
+      this._perfDelay = null;
+      this.perfReport();
+      this._perfTimer = setInterval(() => this.perfReport(), 15000);
+    }, 6000);
   }
   stop() {
     this.renderer.setAnimationLoop(null);
-    if (this._perfTimer) clearInterval(this._perfTimer);
+    this._stopPerfTimers();
+  }
+  _stopPerfTimers() {
+    if (this._perfDelay) { clearTimeout(this._perfDelay); this._perfDelay = null; }
+    if (this._perfTimer) { clearInterval(this._perfTimer); this._perfTimer = null; }
   }
 
   _tick() {
@@ -196,7 +218,30 @@ export class Engine {
 
     // MAIN PHASE — the game's ordered hooks. Pause-gating of individual blocks is the
     // hook's business (ctx.paused); ordering between hooks is registration order.
-    for (const fn of this._hooks.frame) fn(ctx);
+    //
+    // EACH HOOK IS ISOLATED. Unguarded, one hook that throws takes every hook registered
+    // AFTER it down with it, in silence — and the symptom surfaces wherever those systems
+    // were doing their work, which is nowhere near the throw. A game reported thrown grenades
+    // hanging in mid-air with frozen fuses; the cause was a footstep sound, four systems
+    // earlier. That is expensive to diagnose and cheap to prevent, and the timer loop just
+    // above has always done it this way.
+    //
+    // A hook that keeps throwing is retired rather than logged every frame at 60 Hz — the
+    // first stack trace is the useful one, and the thousandth buries it.
+    for (const fn of this._hooks.frame) {
+      if (this._hookFailed?.has(fn)) continue;
+      try {
+        fn(ctx);
+      } catch (e) {
+        (this._hookThrows ??= new Map()).set(fn, (this._hookThrows.get(fn) ?? 0) + 1);
+        const n = this._hookThrows.get(fn);
+        if (n === 1) console.error('[frame hook] threw — later hooks still ran:', e);
+        if (n >= HOOK_THROW_LIMIT) {
+          (this._hookFailed ??= new Set()).add(fn);
+          console.error(`[frame hook] threw ${n} times, retiring it. Fix the trace above.`);
+        }
+      }
+    }
 
     this.renderFrame();
     stamps.render = performance.now();

package/src/core/overrides.js

@@ -0,0 +1,88 @@
+// DECLARED OVERRIDES — named decisions a game may answer for itself.
+//
+// The engine makes decisions internally. Most are right for every game; some are right only for
+// the game the engine grew out of. When a game's content differs, it has had one option: reach
+// in and patch the method that makes the decision. That works, and it is coupled to signatures,
+// call order and private fields the game does not own, so it breaks silently on any minor. It
+// does not compose either — if two games patch the same method for different reasons, both
+// break and neither loudly.
+//
+//   const engine = new Engine({
+//     …,
+//     overrides: {
+//       locomotionClip: ({ moving, aiming, reloading, has }) =>
+//         reloading && !has('gunReloadWalk') ? 'gunReload' : null,   // null = engine decides
+//     },
+//   });
+//
+// FOUR PROPERTIES MAKE THIS WORTH MORE THAN FORMALISED MONKEY-PATCHING:
+//
+// 1. IT OVERRIDES DECISIONS, NOT METHODS. `override('Animator.play', fn)` would only legalise
+//    the fragility — `play`'s signature is implementation shape and will move. A decision is a
+//    QUESTION, and questions have stable contracts. Every design gap this exists to close is a
+//    question the engine currently answers with a hardcoded string.
+//
+// 2. THE DEFAULT IS TODAY'S BEHAVIOUR. Registering nothing is byte-identical. That is what
+//    makes it safe to add decision points to code that two shipped games depend on: returning
+//    `null` or `undefined` from an override also means "engine decides", so a handler that
+//    only cares about one case does not have to reimplement the rest.
+//
+// 3. NARROW AND DECLARED. Every point is listed in POINTS below with its signature. A game
+//    needing something that is not there has found the next one to add — which is a design
+//    conversation, not a silent patch.
+//
+// 4. IT FAILS AT REGISTRATION, NOT AT FRAME 900. An unknown name or a non-function is thrown
+//    at construction, where the stack trace points at the mistake.
+
+// Every decision point the engine will ask about. `args` documents what the handler receives;
+// `returns` what it may answer, where null/undefined always means "engine decides".
+export const POINTS = {
+  locomotionClip: {
+    args: '{ moving, sprinting, aiming, reloading, holstering, drawn, weapon, animator, has }',
+    returns: 'a clip name, or { base, overlay, once } when the body is split, or null to let '
+           + 'the engine choose. A split needs TWO simultaneous answers — a legs-only base and '
+           + 'an upper-body overlay — which a single name cannot express. `once` says whether '
+           + 'that overlay is a one-shot (a reload, a holster) or a held pose that loops (an '
+           + 'aim): it cannot be inferred, and both are legitimate answers to this question.',
+    why: 'western\'s gunslinger pack has a full-body clip for every gun state. Kubold\'s rifle '
+       + 'set has one standing reload and no walking reload, so a game on it needs the legs to '
+       + 'keep moving through a reload the engine would otherwise stop dead.',
+  },
+};
+
+export class Overrides {
+  constructor(map = {}) {
+    this._fns = new Map();
+    for (const [name, fn] of Object.entries(map ?? {})) {
+      if (!POINTS[name]) {
+        throw new Error(`[overrides] unknown decision point "${name}". Known: `
+          + `${Object.keys(POINTS).join(', ')}. A point that should exist and does not is a `
+          + 'design change, not a config typo.');
+      }
+      if (typeof fn !== 'function') {
+        throw new TypeError(`[overrides] "${name}" must be a function, got ${typeof fn}. `
+          + `It is asked: ${POINTS[name].args} -> ${POINTS[name].returns}`);
+      }
+      this._fns.set(name, fn);
+    }
+  }
+
+  has(name) { return this._fns.has(name); }
+
+  // Ask the game. Returns undefined when nothing is registered, when the handler declines by
+  // returning null/undefined, or when it throws — a broken override must not take the frame
+  // with it, and one bad answer per name is worth exactly one trace.
+  ask(name, args) {
+    const fn = this._fns.get(name);
+    if (!fn) return undefined;
+    try {
+      return fn(args) ?? undefined;
+    } catch (e) {
+      if (!(this._threw ??= new Set()).has(name)) {
+        this._threw.add(name);
+        console.error(`[overrides] "${name}" threw — the engine's own answer is being used:`, e);
+      }
+      return undefined;
+    }
+  }
+}

package/src/core/quality.js

@@ -95,7 +95,11 @@ export class AutoTuner {
     const fps = this.frames / this.acc;
     this.acc = 0; this.frames = 0;
     const order = ['high', 'medium', 'low'];
-    const cur = order.indexOf(this.game.qualityName);
+    // WHAT ARE WE RUNNING? A game that never set `qualityName` gave indexOf(undefined) = -1,
+    // which passes the "can still step down" test and makes the next preset order[0] — so a
+    // bad framerate stepped quality UP, and paid applyQuality's setPixelRatio+setSize hitch to
+    // do it. Unknown means the top preset: that is what a game gets if it never chose.
+    const cur = Math.max(0, order.indexOf(this.game.qualityName ?? order[0]));
     if (fps < 24 && cur < order.length - 1) {
       // two consecutive bad windows before acting — applyQuality's setPixelRatio+setSize
       // is itself a big hitch, so a single loading burst must not trigger it mid-play
@@ -104,7 +108,7 @@ export class AutoTuner {
         this.badRun = 0;
         const next = order[cur + 1];
         applyQuality(this.game, next);
-        this.game.ui?.toast(`Performance: graphics set to ${PRESETS[next].label} (change in Esc menu)`, 4200);
+        this.game.ui?.toast?.(`Performance: graphics set to ${PRESETS[next].label} (change in Esc menu)`, 4200);
       }
     } else if (fps >= 24) {
       this.done = true;        // stable — stop fiddling

package/src/systems/climbing.js

@@ -18,6 +18,9 @@ export function setClimbContent({ faceSign = null } = {}) { if (faceSign != null
 const clamp = (v, a, b) => Math.min(b, Math.max(a, v));
 const _axis = new THREE.Vector3(), _face = new THREE.Vector3();
 
+// how close the player must be to a ladder's base to mount it, in metres
+const LADDER_REACH = 2.2;
+
 export class Climbing {
   constructor(player) {
     this.player = player;
@@ -138,11 +141,24 @@ export class Climbing {
   }
 
   // ---- fable-lineage conveniences (unioned): ladder scan + input-driven mount ----
-  _ladders() { return this.game.world?.castle?.ladders || null; }
+  //
+  // WHEREVER THE GAME KEEPS THEM. This read `world.castle.ladders` alone — a fable dungeon
+  // path — while this file's own header says ladders come from `world.ladders`. Two of the
+  // three consumers therefore had no ladders at all, and nothing said so. Both are accepted;
+  // a game may also hand them over directly with `setLadders()`.
+  _ladders() {
+    return this._own ?? this.game.world?.ladders ?? this.game.world?.castle?.ladders ?? null;
+  }
+
+  // a game that keeps its ladders somewhere else entirely can just pass them in
+  setLadders(list) { this._own = list?.length ? list : null; }
 
   nearby() {
     const ls = this._ladders(); if (!ls || !ls.length) return null;
-    const p = this.player.position; let best = null, bd = REACH * REACH;
+    // REACH was never declared — anywhere in the package — so this threw a ReferenceError the
+    // moment a non-empty ladder list existed, and tryMount() calls it unconditionally. The
+    // whole feature was unusable rather than merely misconfigured.
+    const p = this.player.position; let best = null, bd = LADDER_REACH * LADDER_REACH;
     for (const l of ls) {
       const dy = p.y - l.base.y;
       if (dy < -1.0 || dy > l.height + 1.0) continue;

package/src/systems/coach.js

@@ -490,7 +490,7 @@ class Coach {
     const people = [];   // { x, z, ent } — ent null for the player (a coach does not shout the player aside)
     const p = this.game.player;
     const pp = p?.position ?? p?.root?.position;
-    const mine = this.rider?.player === p || this.game.platforms?.carrier(p) === this;
+    const mine = this.rider?.player === p || this.game.platforms?.carrier?.(p) === this;
     if (pp && !mine) people.push({ x: pp.x, z: pp.z, ent: null });
     for (const n of this.game.npcs ?? []) {
       if (!n.alive) continue;             // a coach drives over a body. It does not queue behind one
@@ -591,7 +591,7 @@ class Coach {
   board(player, kind) {
     // a man who sits down is no longer a man standing on the roof (and `aboard` writes his position
     // from the seat, so the two states must never both be live)
-    this.game.platforms?.leave(player, 'aboard');
+    this.game.platforms?.leave?.(player, 'aboard');
     this.rider = { player, kind };
     // POINT THE CAMERA WHERE SHE IS GOING. It orbits the player at camYaw, and camYaw is whatever
     // you happened to be looking at when you climbed up — so you took the reins and found yourself
@@ -954,7 +954,7 @@ export class CoachLine {
         // A THING YOU CAN STAND ON. The registry measures her motion itself, so this is the whole
         // of it — no per-frame hook, nothing for the coach to remember, and the same four lines
         // will put a man on a boxcar. `cols` is what he stops being pushed by while he is up there.
-        c.plat = this.game.platforms?.register({
+        c.plat = this.game.platforms?.register?.({
           root: c.root, owner: c, decks: [ROOF], hull: HULL,
           cols: c.myCols, radius: 4,
         });

package/src/systems/combat.js

@@ -130,7 +130,7 @@ export class Combat {
     p.dodgeT = 1.6;                 // i-frames — nothing interrupts an execution
     p.comboStep = 0; p.comboWindow = 0;
     p.attackCooldown = 0.3;
-    this.game.audio?.play('swingHeavy');
+    this.game.audio?.play?.('swingHeavy');
     p.animator.play('punchUpper', {
       once: true, fade: 0.08, timeScale: 0.9,   // slower = weightier than the combo upper
       onDone: () => { p.busy = false; p.dodgeT = Math.min(p.dodgeT, 0.1); },
@@ -150,8 +150,8 @@ export class Combat {
     this.game.vfx.blood(e.position.clone().setY(e.position.y + 1.2), bdir, 2);
     this.game.hitstopT = Math.max(this.game.hitstopT ?? 0, 0.22);    // the big crunch (kills are 0.13)
     this.game.shake(0.75);
-    this.game.audio?.play('hit');
-    this.game.ui?.showDamage(e, shown);
+    this.game.audio?.play?.('hit');
+    this.game.ui?.showDamage?.(e, shown);
   }
 
   // ONE fist-vs-body test. `e` is anything with the SHOOTABLE-PEOPLE contract — an outlaw, or a
@@ -177,7 +177,7 @@ export class Combat {
     this.game.vfx.blood(e.position.clone().setY(e.position.y + 1.2), bdir, 1);
     // hit-stop: a breath on connect, a longer one on the killing blow
     this.game.hitstopT = Math.max(this.game.hitstopT ?? 0, !e.alive ? 0.13 : heavy ? 0.09 : 0.045);
-    this.game.ui?.showDamage(e, Math.round(dmg));
+    this.game.ui?.showDamage?.(e, Math.round(dmg));
     return true;
   }
 
@@ -209,7 +209,7 @@ export class Combat {
     p.comboStep = (step + 1) % combo.length;
     p.comboWindow = 1.1;
     p.attackCooldown = heavy ? 0.25 : 0.12;
-    this.game.audio?.play(heavy ? 'swingHeavy' : 'swing');
+    this.game.audio?.play?.(heavy ? 'swingHeavy' : 'swing');
 
     p.animator.play(anim, {
       once: true, fade: 0.07, timeScale: heavy ? 1.2 : 1.5,
@@ -242,12 +242,12 @@ export class Combat {
         if (this._meleeHit(n, dmg, heavy, range, arc)) hitAny = true;
       }
       // smashables share the swing arc — crates/barrels/bottles break on any hit
-      if (this.game.smashables?.tryMelee(p.position, p.heading, range, arc)) hitAny = true;
+      if (this.game.smashables?.tryMelee?.(p.position, p.heading, range, arc)) hitAny = true;
       if (hitAny) {
-        this.game.audio?.play('hit');
+        this.game.audio?.play?.('hit');
         this.game.shake(0.3);
       } else {
-        this.game.audio?.play('whoosh');
+        this.game.audio?.play?.('whoosh');
       }
     });
   }
@@ -295,7 +295,7 @@ export class Combat {
   // bullet met the world: dirt/wood/stone all share the dust kick v1; the whine is rationed
   _worldImpact(pr) {
     this.game.vfx?.playFx?.('impact_dirt', { pos: pr.obj.position, scale: 1 });
-    if (Math.random() < 0.3) this.game.audio?.play('ricochet');
+    if (Math.random() < 0.3) this.game.audio?.play?.('ricochet');
   }
 
   // ONE BULLET-VS-BODY TEST, for every kind of body there is: the outlaws (combat.enemies), the
@@ -328,23 +328,23 @@ export class Combat {
     if (hitY >= BODY.head) {
       const at = e.position.clone().setY(e.position.y + 1.62);
       e.takeDamage(e.maxHealth * 10, by.position, { knockback: 0.35, attacker: by });
-      this.game.ui?.showDamage(e, 'HEADSHOT');
+      this.game.ui?.showDamage?.(e, 'HEADSHOT');
       this.game.vfx.hit(at);
       this.game.vfx.blood(at, pr.dir.clone().setY(pr.dir.y + 0.5), 2.6);   // it makes a mess
-      this.game.audio?.play('hit');
+      this.game.audio?.play?.('hit');
       this.game.shakeT = Math.max(this.game.shakeT ?? 0, 0.12);
     } else {
       e.takeDamage(pr.damage, by.position, { knockback: 0.15, attacker: by });
-      this.game.ui?.showDamage(e, Math.round(pr.damage));
+      this.game.ui?.showDamage?.(e, Math.round(pr.damage));
       this.game.vfx.hit(e.position.clone().setY(e.position.y + 1.1));
       this._fleshImpact(pr, e);
-      this.game.audio?.play('hit');
+      this.game.audio?.play?.('hit');
     }
     // THE RETICLE GOES RED — but only for the man holding the gun. An outlaw's round finding a
     // townsman is not YOUR hit and must not be reported as one; at 40m in bright desert the blood
     // spray is four pixels and the mark is the only honest answer to "did I connect?".
     if (by === this.game.player) {
-      this.game.ui?.hitMark(!e.alive);
+      this.game.ui?.hitMark?.(!e.alive);
       // WHAT THE COUNTY KNOWS ABOUT YOU. Every man you put down is one the next one has heard about,
       // and the men they send after that are better shots (enemy.js, AIM). It is the only progression
       // this game keeps, and it is kept HERE because this is the one place a death by your hand is
@@ -470,7 +470,7 @@ export class Combat {
       // must not: `noEvict` bodies lie in the dirt where they fell, resident for life, costing one
       // distanceTo a frame past the cull. It is also better fiction — a cleared camp looks cleared.
       if (e.dead && !e.noEvict) {
-        this.game.vatRoster?.release(e.vatProxy);
+        this.game.vatRoster?.release?.(e.vatProxy);
         this.game.scene.remove(e.root);
         e.spawner?.alive.splice(e.spawner.alive.indexOf(e), 1);
         this.enemies.splice(i, 1);
@@ -555,10 +555,10 @@ export class Combat {
           }
         }
         // bullets smash props they fly into (bottles on the saloon rail)
-        if (!dead && this.game.smashables?.tryPoint(pr.obj.position, 0.75, pr.dir)) dead = true;
+        if (!dead && this.game.smashables?.tryPoint?.(pr.obj.position, 0.75, pr.dir)) dead = true;
         // THE COUNTY'S GAME. Deer and wolf are VAT herd instances, not entities — hunting.js owns
         // the sphere test, the death take, and the carcass the round leaves behind.
-        if (!dead && this.game.hunting?.bulletHit(pr, _prevPos)) dead = true;
+        if (!dead && this.game.hunting?.bulletHit?.(pr, _prevPos)) dead = true;
       } else if (!dead && p.alive && pr.obj.position.distanceTo(tmpV1.copy(p.position).setY(p.position.y + 1.2)) < 0.9) {
         p.takeDamage(pr.damage, pr.shooter?.position ?? pr.obj.position);
         this._fleshImpact(pr, p);

package/src/systems/crime.js

@@ -228,7 +228,7 @@ export class Crime {
     if (lv === this.level) return;
     this.level = lv;
     if (lv > before) {
-      this.game.audio?.play('aggro');
+      this.game.audio?.play?.('aggro');
       // the grace beat between "they know" and the first badge appearing — short at high stars
       this._dispatchT = lv >= 3 ? 1.2 : 2.5;
       const line = ['', 'A deputy is asking after you.', 'The sheriff has men on the street.',
@@ -567,13 +567,13 @@ export class Crime {
 // 5. REPORTING (combat.js's job, not main.js's). combat.js must call, from the friendly-bullet /
 //    melee paths, when a CIVILIAN (townsfolk NPC or coach rider — anything with .civilian) is hit:
 //
-//        this.game.crime?.report('assault', e.position);         // hurt a civilian
-//        this.game.crime?.report('murder', e.position);          // killed a civilian
-//        this.game.crime?.report('coachRobbery', e.position);    // killed a coach driver/mate/fare
+//        this.game.crime?.report?.('assault', e.position);         // hurt a civilian
+//        this.game.crime?.report?.('murder', e.position);          // killed a civilian
+//        this.game.crime?.report?.('coachRobbery', e.position);    // killed a coach driver/mate/fare
 //
 //    and loot.js, when a corpse is robbed:
 //
-//        game.crime?.report('robbery', corpse.position);
+//        game.crime?.report?.('robbery', corpse.position);
 //
 //    Killing a LAWMAN needs NO call — Crime watches its own pool and reports it itself. (If
 //    combat.js reports it anyway, a 0.6s de-dup window in report() swallows the double.)