sindicate 0.1.0 → 0.4.0

package/docs/api/wind-weather-uniforms.md

@@ -0,0 +1,105 @@
+# Wind & Weather Uniforms
+
+Modules: `src/world/wind.js`, `src/world/weatherUniforms.js`
+Both are re-exported from the engine root (`src/index.js`).
+
+Together these two files are the single source of weather truth for the whole scene. `Wind` is a global wind simulation ticked once per frame on the CPU; `weatherUniforms.js` is a set of module-level TSL uniform singletons that carry the current weather/sky state into every shader that opts in. Everything that should lean on the weather reads from here instead of rolling its own — CPU consumers (e.g. tumbleweeds) read `wind.vx/vz` directly, GPU consumers (grass sway, rain slant, water tint, ground wetness) read the shared uniforms.
+
+## Why uniforms decouple build order
+
+The uniforms are **module-level singletons** created at import time. Terrain, grass, water, and the Weather/sky systems may be constructed in any order — some materials are built before the weather system exists, some after — but because every one of them imports the *same* uniform node objects, they all reference identical GPU state no matter who was built first. The writer (Weather, sky, `Wind`) just mutates `.value` each frame and every material that baked the node into its shader graph sees the change. No registration step, no "pass the weather system into the terrain constructor" plumbing, no ordering constraint.
+
+## Exports — `world/wind.js`
+
+### `class Wind`
+
+One slowly-wandering heading plus a gusting strength. Deterministic layered sines drive both the drift and the gusts — smooth, no per-frame RNG jerks, and identical after a reload.
+
+```js
+const wind = new Wind();   // publishes initial state to uWindDir/uWindStr immediately
+wind.update(dt);           // call once per frame; dt in seconds
+```
+
+**`constructor()`** — initializes state and immediately publishes to the shared uniforms (so shaders see sane wind even before the first `update`).
+
+**`update(dt)`** — advances the internal clock, recomputes heading/gust/speed, republishes. Call exactly once per frame.
+
+Instance fields (all readable; treat as read-only outside the class):
+
+| Field | Meaning |
+|---|---|
+| `t` | accumulated sim time (seconds) |
+| `baseAngle` | the PREVAILING heading, fixed at `0.7` rad (~SE-ish); the wind only veers gently around it |
+| `angle` | current heading the wind blows **toward** — radians on the ground plane, `atan2(z, x)` convention. Oscillates `baseAngle ± ~0.47` rad (~±27°) |
+| `base` | mean speed, `1.6` m/s — a light breeze for the CPU consumers, not a gale |
+| `gust` | current gust factor, swells and lulls between ~`0.12` and ~`1.05` |
+| `speed` | current speed, `base * (0.5 + 0.85 * gust)` ≈ 0.96–2.36 m/s |
+| `x`, `z` | unit heading components (`cos(angle)`, `sin(angle)`) |
+| `vx`, `vz` | velocity in m/s (`x * speed`, `z * speed`) — what CPU consumers integrate against |
+
+**`_publish()`** *(private)* — copies `x/z` into `uWindDir` and `gust` into `uWindStr`. Called from the constructor and every `update`; you never call it yourself.
+
+## Exports — `world/weatherUniforms.js`
+
+Every export is a `uniform(...)` node from `three/tsl` (three/webgpu build). Writers mutate `.value` on the CPU; readers compose the node into TSL material graphs.
+
+| Uniform | Initial value | Range / meaning | Written by | Read by |
+|---|---|---|---|---|
+| `uWet` | `0` | 0 dry … 1 soaked — rain darkens the ground | Weather system, **eased** each frame so the ground soaks/dries gradually | `grass.js` (blade colour darkens toward ×0.7 when soaked); terrain ground darkening, puddles, and sheen (per source comments — host-game side) |
+| `uCover` | `0` | 0 bare … 1 snow-covered | Weather system, eased so snow builds/melts gradually | `grass.js` (whitens blade tips toward `vec3(0.95, 0.96, 1.0)`); up-facing terrain whitening (host-game side) |
+| `uDayness` | `1` | 0 night … 1 day | `sky.js` (host-game side) | UNLIT baked-albedo materials (impostors) — dims them so they stop glowing at night |
+| `uSkyCol` | `Color(0x7fb2e5)` | current sky-phase zenith colour | `sky.js` | `water.js` — underwater inscatter tint, sky-reflection gradient, and a luminance clamp so water doesn't glow at dusk/night |
+| `uHorizonCol` | `Color(0xdfe9d8)` | current horizon colour | `sky.js` | `water.js` reflections — water tracks day/dusk/night for free |
+| `uSunDir` | `Vector3(0.3, 0.8, 0.3)` | current key-light direction (sun by day, **moon by night**) | sky/lighting (host-game side) | `grass.js` backlight (`dot(viewDir, uSunDir)^4` rim on blade tips), etc. |
+| `uRain` | `0` | 0 dry … 1 downpour — the rain **falling right now** | Weather system | splash effects (host-game side). See gotcha below — this is deliberately *not* `uWet` |
+| `uRainT` | `0` | seconds, running **while it rains** — the ground's rain clock | Weather system | puddle ripple rings on the ground, so they beat in time with the rain actually falling |
+| `uCloudiness` | `0` | 0 fair … 1 storm deck | `weather.js` — **leads** the rain/snow | sky/cloud rendering, so the sky thickens *before* precipitation and clears after |
+| `uWindDir` | `Vector2(1, 0)` | unit heading the wind blows **toward**, on the ground plane (XZ) | `world/wind.js`, every frame | `grass.js` sway direction + gust-front advection; rain slant (host-game side) |
+| `uWindStr` | `0.4` | 0 calm … ~1 gusting | `world/wind.js`, every frame | `grass.js` gust amplitude; rain slant scaling. CPU consumers (tumbleweeds) read `wind.vx/vz` instead |
+
+In this repository the in-engine importers are `wind.js` (writer), `grass.js`, and `water.js`. The Weather/sky/terrain writers and readers named in the source comments live host-game side (the systems ported onto the engine); the whole point of the singleton design is that they wire up to these exact nodes whenever they're built.
+
+## Usage example
+
+A frame loop driving the wind, a CPU consumer riding it, and a custom TSL material opting into the shared weather:
+
+```js
+import * as THREE from 'three/webgpu';
+import { mix, float } from 'three/tsl';
+import { Wind, uWet, uWindDir, uWindStr } from 'sindicate';
+
+const wind = new Wind(); // uniforms are already valid after this line
+
+// A custom material that darkens when the ground is soaked and shivers with the
+// global gusts — same weather every other material sees, regardless of when
+// this material was built relative to the Weather system.
+const mat = new THREE.MeshStandardNodeMaterial();
+mat.colorNode = baseAlbedo.mul(mix(float(1.0), float(0.7), uWet));
+// ...positionNode can offset along uWindDir scaled by uWindStr for sway...
+
+function tick(dt) {
+  wind.update(dt); // once per frame, before consumers integrate
+
+  // CPU consumer: roll a prop downwind
+  crate.position.x += wind.vx * dt * 0.2;
+  crate.position.z += wind.vz * dt * 0.2;
+
+  // Host-game weather system easing a shared value (shaders pick it up next draw)
+  uWet.value += (stormTargetWet - uWet.value) * Math.min(1, dt * 0.3);
+}
+```
+
+## Gotchas
+
+- **Veer, don't circle (bug history).** `Wind.update` sets the heading *directly* as prevailing ± a bounded oscillation (~±27°). The old code *integrated* sines (`angle += … * dt`); the low-frequency term summed to several radians over time and swept the wind all the way around the compass ("pushed things in a 360, weird"). If you touch the heading math, keep it a bounded function of `t`, never an accumulation.
+- **`uRain` is not `uWet`, and the difference is the whole point.** The ground stays dark and slick for a good while after a storm passes (`uWet` eases down slowly), but the moment the rain stops, drops stop landing (`uRain` drops). Splashes read `uRain`; puddles and sheen read `uWet`. Don't collapse them into one value.
+- **Why `uRainT` exists at all.** The Weather system had a `uTime` of its own, but it was private to the rain particles — the ground could not see it, so the puddle rings could not move. `uRainT` is the shared rain clock: it only advances while it rains, so ground ripples beat in time with the falling rain.
+- **`uCloudiness` leads precipitation.** The weather system raises cloudiness *before* rain/snow starts and clears it after they stop, so the sky thickens ahead of a storm. Preserve that lead if you write your own weather driver.
+- **Wind speed is tuned, not physical.** `base = 1.6` m/s is deliberately a light breeze — at higher values the tumbleweeds "rolled too fast". Retune consumers, not the shared wind, if something moves at the wrong speed.
+- **`angle` is the heading the wind blows TOWARD** (radians on the XZ ground plane, `atan2(z, x)`), and `uWindDir` follows the same convention. Note `uWindDir` is a `Vector2` where `.y` holds world **Z** — grass uses `uWindDir.y` for its Z sway.
+- **`uWindStr` publishes the raw gust factor** (`wind.gust`, 0.12–1.05), not `wind.speed`. Shader consumers scale it themselves; CPU consumers wanting real velocity must use `wind.vx/vz`.
+- **Deterministic on purpose.** The wind is layered sines of `t` with no RNG — smooth (no per-frame jerks) and identical after a reload. Don't add randomness to it.
+- **Tick once, early.** Call `wind.update(dt)` exactly once per frame, before anything integrates against `vx/vz`, or CPU and GPU consumers will see different wind for that frame. The constructor publishes too, so uniforms are never stale-default even before the first update.
+- **Ease the weather uniform writes.** `uWet`/`uCover` are meant to be eased toward targets each frame (soak/dry, build/melt), not snapped — materials render whatever `.value` holds, so a snap is a visible pop.
+- **`uSunDir` is the key light, not literally the sun** — it points at the moon at night. Grass backlight and similar effects rely on it always being the current key light.
+- **Water clamps `uSkyCol` luminance** (floor 0.22) so lit water doesn't go pitch black when the sky colour goes near-black at night, and doesn't glow white at dusk — keep sky colours flowing through `uSkyCol`/`uHorizonCol` rather than baking them into water.

package/docs/contracts/render.md

@@ -0,0 +1,32 @@
+# Contract: render & scene
+
+**Status:** draft (step 3 — extraction from western main.js in progress).
+
+## The facet
+
+- `engine.render.scene` — attach/detach root for game objects (systems stop touching a raw `game.scene`).
+- `engine.render.camera` — read access. Writing the camera happens ONLY in the camera-overrides phase (time-feel contract §7); anything else is an ordering bug by definition.
+- `engine.render.frustum` — the per-frame culling frustum, built ONCE per unpaused frame after camera-overrides. **May be null; null means "don't cull".** Consumers must treat null as visible — the engine nulls it deliberately when a stale frustum would mis-cull (e.g. a hand-ticked NPC during a paused dialogue whose two-shot faces away from last frame's camera).
+- `engine.render.project(v3, out2)` — world→screen for HUD nameplates/markers (UI never does its own matrix math).
+- `engine.render.post` — the PostProcessing instance; `post.gradeAmount` is the game's one live dial (renderer API doc).
+
+## The single render path
+
+`renderFrame()` is the ONE call that puts pixels on screen — shared by the boot warm-up and the loop tick. Never add a second render call: every code path that renders must pay the same pipeline state, or the first frame through the "other" path compiles pipelines mid-play.
+
+## Exposure write-gating
+
+`renderer.toneMappingExposure` (and any renderer-level uniform-adjacent state) is written **only when the value actually changes**. Redundant writes are not free on WebGPU — the gate lives engine-side so games can "set" exposure every frame safely.
+
+## Warm-up phases (PERF LAW, mechanical)
+
+Boot runs, behind the loading screen, in order:
+1. `warmTextures()` — GPU pre-upload of every cached texture (kills ~75ms first-sight upload hitches).
+2. `warmRenderHidden()` / `warmUpFX()` — force-visible + `compileAsync` every hidden, culled, or count-0 pipeline (pooled VFX, UI-triggered materials) so NO pipeline compiles after boot.
+3. The 360° settle sweep — the camera sweeps a full turn rendering via `renderFrame()`, initializing per-object GPU state along every bearing.
+
+A dev-mode watchdog flags any pipeline compile after warm-up completes, with a stack — that's a spawned-uncached asset or a lazily-built material, and it WILL become a multi-second WebGPU freeze on a player's machine.
+
+## Freeze profiler
+
+The engine stamps phase timings each frame into a ring buffer; a frame over budget dumps the per-phase breakdown (and, with the dev plugin, sinks JSONL to disk). Games get it for free — it exists because "the game hitched once on my machine" is otherwise undebuggable.

package/docs/contracts/time-feel.md

@@ -0,0 +1,52 @@
+# Contract: time & feel
+
+**Status:** draft (step 3 — extraction from western main.js in progress). Field names final, wiring lands with the Engine base.
+
+## The two clocks
+
+Every frame has TWO dt values, and using the wrong one is a shipped-bug class:
+
+- **`rawDt`** — wall-clock frame time, never scaled. Consumers: camera look, aim IK (aiming stays crisp inside slow-mo), the fps meter (scaled dt inflates it during hit-stop), and any *meter that must drain in real time* (a slow-mo meter timed in slow-mo drains 3× slower the instant it activates — the engine's slow-mo system runs on rawDt for exactly this reason).
+- **`dt`** — the world dt: `rawDt × Π(timeScale contributions)`, clamped at 0.1s. Drives mixers, physics, AI, projectiles, VFX, game-time timers.
+
+## timeScale contributions (the multiplier chain)
+
+Systems never write loop fields. They register contributors; the engine multiplies them in registration order each frame *after* the pre-scale phase:
+
+```js
+engine.time.addTimeScale(() => (hitstopActive ? 0.12 : 1))   // combat's hit-stop
+engine.time.addTimeScale(() => slowMo.scale)                  // Dead-Eye-style slow-mo
+```
+
+- Contributors run every frame; return 1 when inactive.
+- Systems that *decide* the frame's scale (e.g. slow-mo reading its meter) update in the **pre-scale phase** on rawDt, so the scale they return lands on THIS frame, not the next.
+- `engine.time.worldDtScale` exposes the product (read-only; the dev drive-bus asserts on it).
+
+## Game-time timers
+
+`engine.time.after(seconds, fn)` — one-shots that tick on **world dt inside the unpaused guard**: they freeze with the pause menu (a pause can never eat a death-beat landing) and stretch under slow-mo. Not setTimeout. Errors in `fn` are caught and logged, never thrown into the loop.
+
+`engine.time.playSeconds` — accumulated unpaused world time (save-slot playtime readout).
+
+## Feel write APIs
+
+- `engine.feel.hitstop(seconds)` — refreshes the hit-stop window (max with current, never additive stacking).
+- `engine.feel.shake(strength)` — camera shake impulse, consumed by the camera phase.
+
+## Frame phases (execution order is the contract)
+
+1. **frame-start** — clock advance, input `pollGamepad(ui.anyPanelOpen)`.
+2. **pre-scale** *(rawDt)* — systems that produce this frame's timeScale.
+3. **scale** — multiplier chain → world dt.
+4. **ui-modal** — global keys, panel nav, modal key routing (see ui contract). May consume input.
+5. **sim** *(world dt, skipped when paused)* — timers, world update, then game-registered sim hooks in registration order.
+6. **actors** — player update (writes the follow camera), then game actor hooks. Runs even paused (movement is pause-gated inside the player; a hand-ticked NPC keeps breathing during dialogue).
+7. **camera-overrides** — ordered, **last writer wins**, after everything that can move a platform or a vehicle seat: dialogue two-shot → scripted scenes → cinematics (each registered with an order key). The engine builds the culling frustum AFTER this phase, once, when unpaused (`engine.render.frustum`; null while a stale frustum would mis-cull — see render contract).
+8. **late-sim** *(unpaused)* — combat resolution, missions, crowd systems, ambient ticks.
+9. **render** — exposure write-gating, `renderFrame()` (the ONE render path shared by boot warm-up and the loop), freeze-profiler phase stamps.
+
+The pause predicate is supplied by the ui facet (`ui.anyPanelOpen`) and holds phases 5 and 8; 6, 7 and 9 always run.
+
+## Why this shape
+
+Western's main.js encoded all of the above as a single 400-line closure with ordering comments ("It runs HERE — not one line earlier"). The phases make the ordering *structural*: a system registered in the wrong phase is a visible design error, not a subtle frame-lag bug discovered in play.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sindicate",
-  "version": "0.1.0",
+  "version": "0.4.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

@@ -0,0 +1,184 @@
+// Character animation state machine over THREE.AnimationMixer,
+// with automatic retargeting per character rig.
+import * as THREE from 'three/webgpu';
+import { buildRetargetContext, retargetClip } from './retarget.js';
+// 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 })
+// Unregistered, clips play untrimmed and every Animator needs explicit clipRigs.
+let CLIP_TIMING = {};
+let CLIP_RIGS = null;
+export function setClipDefaults({ timing = null, rigs = null } = {}) {
+  if (timing) CLIP_TIMING = timing;
+  if (rigs) CLIP_RIGS = rigs;
+}
+
+export class Animator {
+  get needsRetarget() { return true; }   // RawAnimator says no (see the bottom of this file)
+
+  // clipRigs: optional { clipName -> sourceRigKey }. A clip is authored against ONE
+  // skeleton's bind pose; clips from a foreign pack (different bind, same bone names)
+  // must retarget from THAT bind or they play folded in half. One ctx per source rig.
+  constructor(root, clips, clipRigs = null) {
+    this.mixer = new THREE.AnimationMixer(root);
+    this.root = root;
+    this.clipRigs = clipRigs ?? CLIP_RIGS;
+    this._ctxByRig = new Map();
+    // A RawAnimator's clips target the model's OWN skeleton, so it needs no retarget context —
+    // and building one THREW if no source rig had been registered yet. In the game that was
+    // invisible (the player registers the Synty rig long before a horse loads); anywhere else —
+    // a bench that only wants a horse — it was a hard crash on construction. Ask, don't assume.
+    this.ctx = this.needsRetarget ? this._ctxFor(null) : null;   // (other code reads .ctx)
+    this.actions = {};
+    this.current = null;
+    this.currentName = null;
+    this._overlay = null;
+    for (const [name, clip] of Object.entries(clips)) this.register(name, clip);
+
+    // completion callbacks are PER-ACTION (action._onceDone), not a shared slot: with a
+    // single slot, any play({once}) stomped the PREVIOUS one-shot's pending callback —
+    // e.g. a bow release during a dodge wiped the dodge's busy=false and soft-locked
+    // the player. Per-action, each one-shot can only ever replace its own callback.
+    this.mixer.addEventListener('finished', (e) => {
+      const cb = e.action._onceDone;
+      e.action._onceDone = null;
+      cb?.();
+    });
+  }
+
+  _ctxFor(rigKey) {
+    const k = rigKey ?? '__default';
+    let c = this._ctxByRig.get(k);
+    if (!c) { c = buildRetargetContext(this.root, rigKey); this._ctxByRig.set(k, c); }
+    return c;
+  }
+
+  register(name, clip) {
+    const ctx = this._ctxFor(this.clipRigs?.[name] ?? null);
+    const action = this.mixer.clipAction(retargetClip(clip, ctx));
+    this.actions[name] = action;
+  }
+
+  // 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) {
+    const src = this.actions[srcName];
+    if (!src) return;
+    const clip = src.getClip().clone();
+    clip.tracks = clip.tracks.filter((t) => keepFn(t.name.replace(/\.(position|quaternion|scale)$/, '')));
+    clip.name = name;
+    this.actions[name] = this.mixer.clipAction(clip);
+  }
+
+  // A persistent overlay action that plays ALONGSIDE the base FSM action (play()
+  // only fades `this.current`, never the overlay). Non-overlapping tracks compose.
+  //
+  // WEIGHTS MUST SUM TO 1 ON EVERY BONE, ALWAYS. three's PropertyMixer fills any
+  // cumulative-weight deficit from the binding's ORIGINAL saved value — captured at the
+  // mixer's first activation, i.e. the model's BIND POSE. So a weight gap does not blend
+  // between two poses: it blends toward a T-POSE. A 0.12s overlay fadeOut racing a 0.18s
+  // base fadeIn dipped the sum to ~0.58 and flashed the arms 42% toward T-pose on every
+  // aim release. Hence: overlay swaps of the SAME mask crossfade (sum stays 1); starting
+  // or dropping an overlay is INSTANT, and the caller switches the base to/from the
+  // complementary mask in the SAME frame. A hard pose cut is survivable; a T-pose is not.
+  setOverlay(name, opts = {}) {
+    const next = name ? this.actions[name] : null;
+    const prev = this._overlay;
+    if (prev === next && !opts.restart) return next;
+    if (next) {
+      next.reset();                                  // reset() calls stopFading() — so it MUST come first
+      if (opts.once) { next.setLoop(THREE.LoopOnce, 1); next.clampWhenFinished = true; }
+      else next.setLoop(THREE.LoopRepeat, Infinity);
+      next.enabled = true;
+      next.setEffectiveWeight(1);
+      next.play();
+      // same-mask swap (aim -> fire -> aim): crossFadeFrom keeps the pair summing to 1
+      if (prev && prev !== next && opts.fade) next.crossFadeFrom(prev, opts.fade, false);
+      else if (prev && prev !== next) { prev.stop(); prev.setEffectiveWeight(0); }
+    } else if (prev) {
+      // DROPPING the overlay. stop() zeroes its weight instantly — but the base is still the
+      // LOWER-only mask for a beat, so the upper body is left with ZERO cumulative weight and
+      // three fills it from the bind pose: a ~0.2s T-POSE flash at the end of every one-shot.
+      // Instead fade it out over EXACTLY the duration the caller fades its full-body base in
+      // (opts.fade). Upper: overlay(1-t) + base(t) = 1. Lower: lowerBase(1-t) + base(t) = 1.
+      const d = opts.fade ?? 0;
+      if (d > 0) prev.fadeOut(d);
+      else { prev.stop(); prev.setEffectiveWeight(0); }
+    }
+    this._overlay = next;
+    return next;
+  }
+
+  // play(name) — loop. play(name, {once, fade, timeScale, onDone}) — one-shot.
+  // startFrac (0..1) skips into the clip past wind-up. CLIP_TIMING (tuned via
+  // /anim.html) supplies per-clip start/speed DEFAULTS; explicit opts override.
+  play(name, opts = {}) {
+    const action = this.actions[name];
+    if (!action) return null;
+    const tm = CLIP_TIMING[name] || {};
+    const once = opts.once ?? false;
+    const fade = opts.fade ?? 0.18;
+    const restart = opts.restart ?? false;
+    const onDone = opts.onDone ?? null;
+    const startFrac = opts.startFrac ?? tm.start ?? 0;
+    const timeScale = opts.timeScale ?? tm.speed ?? 1;
+    if (this.currentName === name && !restart && !once) return action;
+
+    action.reset();
+    if (startFrac > 0) action.time = action.getClip().duration * startFrac;
+    action.timeScale = timeScale;
+    if (once) {
+      action.setLoop(THREE.LoopOnce, 1);
+      action.clampWhenFinished = true;
+      action._onceDone = onDone;
+    } else {
+      action.setLoop(THREE.LoopRepeat, Infinity);
+      action._onceDone = null; // re-played as a loop: drop any stale one-shot callback
+    }
+    action.fadeIn(fade).play();
+    if (this.current && this.current !== action) this.current.fadeOut(fade);
+    this.current = action;
+    this.currentName = name;
+    this._curTiming = tm;       // for end-trim handling in update()
+    this._curOnce = once;
+    return action;
+  }
+
+  stopAll() {
+    this.mixer.stopAllAction();
+    this.current = null;
+    this.currentName = null;
+    this._overlay = null;
+  }
+
+  update(dt) {
+    this.mixer.update(dt);
+    // CLIP_TIMING end-trim: cut the tail of the clip. One-shots clamp at `end`
+    // (and fire onDone there); loops cycle back to `start`.
+    const a = this.current, tm = this._curTiming;
+    if (a && tm && tm.end != null && tm.end < 1) {
+      const dur = a.getClip().duration;
+      if (a.time >= tm.end * dur) {
+        if (this._curOnce) {
+          a.time = tm.end * dur;
+          a.paused = true;
+          const cb = a._onceDone; a._onceDone = null; cb?.();
+        } else {
+          a.time = (tm.start ?? 0) * dur;
+        }
+      }
+    }
+  }
+}
+
+// Self-animated rigs (PolyPerfect creatures, like the horse): the clips target the
+// model's OWN skeleton, so registration skips the Synty retarget entirely — everything
+// else (play/overlay/once-callbacks/end-trim) behaves identically.
+export class RawAnimator extends Animator {
+  get needsRetarget() { return false; }   // its clips already speak this skeleton's language
+
+  register(name, clip) {
+    this.actions[name] = this.mixer.clipAction(clip);
+  }
+}