sindicate 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sindicate",
-  "version": "0.17.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/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 })

package/src/core/overrides.js

@@ -39,7 +39,11 @@
 export const POINTS = {
   locomotionClip: {
     args: '{ moving, sprinting, aiming, reloading, holstering, drawn, weapon, animator, has }',
-    returns: 'a clip name to play, or null to let the engine choose',
+    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.',

package/src/systems/player.js

@@ -931,18 +931,41 @@ export class Player extends Character {
     // full-body clips — the holster timer still reads it, so it must still exist.)
     const gunPose = !!gunW && (this.aiming || this.reloading || this._drawT > 0 || this._gunRecoilT > 0);
     if (!this.busy && !this.airborne) {
-      if (this.animator._overlay) this.animator.setOverlay(null, { fade: BASE_FADE });
       // WHICH CLIP IS THE BODY PLAYING? A decision point (core/overrides.js), because the
       // answer below is right for a pack that has a full-body clip for every gun state and
       // wrong for one that does not: Kubold's rifle set has a single standing reload, so
       // `gunReloadWalk` maps onto it and walking into a reload stops the legs dead. A game
       // whose pack differs answers for itself; one that says nothing gets exactly this.
-      const chosen = this.game?.engine?.overrides?.ask('locomotionClip', {
+      //
+      // IT MAY ANSWER WITH BOTH HALVES. A body split is two simultaneous answers — a legs-only
+      // base AND an upper-body overlay — so a single clip name cannot express one. Returning
+      // `{ base, overlay }` says both. And the ask now happens BEFORE the overlay is dropped:
+      // dropping it first rewound the overlay sixty times a second, which a game could only
+      // stop by patching setOverlay. That patch was the last one Blacksand still carried.
+      const answer = this.game?.engine?.overrides?.ask('locomotionClip', {
         moving, sprinting, drawn: this.drawn, aiming: this.aiming,
         reloading: this.reloading, holstering: this._holstering,
         weapon: this.weapon, animator: this.animator,
         has: (n) => !!this.animator.actions[n],
       });
+      const chosen = typeof answer === 'string' ? answer : answer?.base ?? null;
+      const wantOverlay = typeof answer === 'object' && answer !== null ? answer.overlay ?? null : null;
+      // ONE-SHOT OR HELD? It cannot be inferred and the two are both legitimate answers to the
+      // same question: a reload or holster overlay plays once and stops, `gunAimUpper` is a
+      // held pose that must loop. setOverlay defaults to LoopRepeat/Infinity, so an unstated
+      // reload overlay ran for ever — the answer has to say.
+      const overlayOnce = typeof answer === 'object' && answer !== null ? !!answer.once : false;
+
+      // Only clear the overlay when nothing asked to keep one. `undefined` means the game did
+      // not answer at all, so the engine owns the slot exactly as before.
+      // setOverlay already returns early when the action is unchanged, so re-asserting the
+      // same overlay every frame costs nothing and cannot rewind it.
+      if (wantOverlay) {
+        this.animator.setOverlay(wantOverlay, { fade: BASE_FADE, once: overlayOnce });
+      } else if (this.animator._overlay) {
+        this.animator.setOverlay(null, { fade: BASE_FADE });
+      }
+
       if (chosen) this.animator.play(chosen);
       else if (this.drawn && gunW) {
         if (this.reloading) this.animator.play(moving ? 'gunReloadWalk' : 'gunReload');