sindicate 0.1.0

package/README.md

@@ -0,0 +1,20 @@
+# SINDICATE
+
+**Open-world game engine for three.js WebGPU.** Streaming worlds, characters, mounts & vehicles, missions, ambient crowds — extracted from a shipped browser western (Dustwater) and consumed as an npm package by every game built on it.
+
+- **Design & migration plan:** [`ENGINE_DESIGN.md`](./ENGINE_DESIGN.md) — the adversarially-reviewed blueprint. Read it first.
+- **Contracts:** [`docs/contracts/`](./docs/contracts/) — the written interface each subsystem exposes and each game implements.
+- **Consumption:** games depend on `"sindicate": "github:<owner>/sindicate#vX.Y.Z"` (stable, lockfile-pinned) or `"file:../Sindicate"` (live engine hacking). Source ESM, no build step; `three` and `three-mesh-bvh` are peer dependencies.
+- **The rule:** engine code changes **only in this repo** — never copy engine files into a game to hack them.
+
+## Status
+
+Migration step 1 (of the plan in ENGINE_DESIGN.md §9): package scaffold + the verified-clean tier moved verbatim from western — core utils/quality/decals, collision + BVH worker, water/grass/wind/weather-uniform world modules, pooled shatter, and the patched FBXLoader (vendored; merges all FBX animation layers — pinned against three ^0.184).
+
+## Games on Sindicate
+
+| Game | Status |
+|---|---|
+| western (Dustwater) | migrating — strangler-fig branch `sindicate-port` |
+| fable (Aldenvale) | queued — ports after western reaches parity |
+| GTA-style (name TBD) | future — first born-on-the-engine game |

package/docs/contracts/README.md

@@ -0,0 +1,22 @@
+# Sindicate contracts
+
+One page per facet/interface. A contract states: what the facet exposes, who owns each piece of state (single writer), what a game must register, and what events flow. Integration knowledge lives **here**, never as "see main.js:748" prose.
+
+These documents are the real deliverable of design principle P1 ("areas are tweakable in isolation" — ENGINE_DESIGN.md §2). A system that needs something not in its facet has found a design bug, not a workaround.
+
+## Planned contracts (filled in as each migration step lands — §9)
+
+| Contract | Covers | Lands with |
+|---|---|---|
+| `world.md` | heightAt/riverInfo/groundAt/navFloorAt/segmentBlocked/moveCapsule oracles, WorldDescription, cook fingerprints | step 4 |
+| `entities.md` | every named collection (player, npcs, enemies, horses, vehicles, children, interactables…), single-writer ownership, registration API | step 5 |
+| `input.md` | down/hit/consume, bindings tables, UI-modal suppression + edge priming | step 2 |
+| `events.md` | event vocabulary (entity:killed, crime:report, …) — reactions only; sync queries belong to services | step 5 |
+| `time-feel.md` | dt chain, game-time timers, timeScale contributions (hitstop/slow-mo), shake write API | step 3 |
+| `render.md` | scene attach/detach, camera (read), frustum (read), world-to-screen, quality-apply write path | step 3 |
+| `services.md` | synchronous query surfaces: economy, flags, nav, platforms, spawn factory, hit-interceptors | step 5 |
+| `assets.md` | AssetPolicy, RigDescriptors, atlas rules, clip manifests, warm registry (PERF LAW) | step 2 |
+| `ui.md` | modality (anyPanelOpen, modal key routing, close-consumes-key), theme tokens, panel nav | step 6 |
+| `audio.md` | sfx/music/ambience catalogues, venue ducking, volume persistence | step 6 |
+| `persistence.md` | slot management, game-registered serializers, storage namespacing | step 5 |
+| `quality.md` | presets, AutoTuner, per-game storage key | step 2 |

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "sindicate",
+  "version": "0.1.0",
+  "description": "Sindicate — open-world game engine for three.js WebGPU. Streaming worlds, characters, mounts & vehicles, missions, crowds.",
+  "type": "module",
+  "main": "src/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nickaccent/Sindicate-Engine"
+  },
+  "keywords": [
+    "three",
+    "threejs",
+    "webgpu",
+    "game-engine",
+    "open-world",
+    "streaming",
+    "engine"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./*": "./src/*"
+  },
+  "files": [
+    "src",
+    "tools",
+    "docs",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "three": "^0.184.0",
+    "three-mesh-bvh": "^0.9.10"
+  },
+  "license": "UNLICENSED"
+}

package/src/core/decalField.js

@@ -0,0 +1,151 @@
+// DecalField — portable ground/surface decals for the unity-vfx-webgpu format.
+// Lays flat textured quads (blood splats, scorch marks, magic sigils, footprints)
+// on the surface they are projected onto, oriented to the surface normal, with
+// fade-in/out over life and a ring-buffer budget. NO game-specific code.
+//
+// These are simple laid-flat quads, NOT true projected decals (no mesh-conforming
+// UV projection) — cheap, WebGPU-safe, and enough for a flat-ish ground surface.
+import * as THREE from 'three/webgpu';
+
+const _FWD = new THREE.Vector3(0, 0, 1);   // PlaneGeometry faces +Z by default
+const _n = new THREE.Vector3();
+const _q = new THREE.Quaternion();
+const _spin = new THREE.Quaternion();
+
+const rand = (r) => r[0] + Math.random() * (r[1] - r[0]);
+
+export class DecalField {
+  // scene: a THREE.Scene (or any Object3D container).
+  // loadTexture(nameOrUrl) -> Promise<Texture>. textureBase resolves bare basenames
+  //   to `${base}/${name}.png` (norm maps too); absent = basename passed through.
+  // max: ring-buffer budget — the oldest decal is evicted when the (max+1)th is added.
+  constructor(scene, { loadTexture, textureBase = '', max = 128 } = {}) {
+    this.scene = scene;
+    this._loadTexture = loadTexture;
+    this.textureBase = textureBase;
+    this.max = max;
+    this.recipes = {};
+    this.textures = {};   // basename -> THREE.Texture (albedo + optional normal)
+    this.items = [];      // active decals, oldest first (ring buffer)
+  }
+
+  _src(name) {
+    if (!name) return null;
+    return this.textureBase
+      ? (this.textureBase.endsWith('/') ? this.textureBase + name : this.textureBase + '/' + name) + '.png'
+      : name;
+  }
+
+  // pre-resolve every decal texture (and normal map) referenced by the recipes
+  async load(decalRecipes) {
+    this.recipes = decalRecipes || {};
+    const names = new Set();
+    for (const d of Object.values(this.recipes)) {
+      if (d.tex) names.add(d.tex);
+      if (d.norm) names.add(d.norm);
+    }
+    for (const n of names) {
+      if (this.textures[n]) continue;
+      try { this.textures[n] = await this._loadTexture(this._src(n)); }
+      catch { this.textures[n] = null; console.warn('[decal] missing tex', n); }
+    }
+  }
+
+  // Lay a decal named `name` at world `pos`, oriented so its face points along
+  // `normal`. scale multiplies the authored size; rot overrides the recipe's
+  // rotation ('rand' | degrees); color multiplies the authored tint.
+  add(name, { pos, normal = [0, 1, 0], scale = 1, rot, color } = {}) {
+    const def = this.recipes[name];
+    if (!def) return null;
+
+    // ---- geometry: a quad sized in metres (square unless aspect = w/h) ----
+    const base = rand(def.sz || [1, 1]) * scale;
+    const aspect = def.aspect || 1;
+    const geo = new THREE.PlaneGeometry(base * aspect, base);
+
+    // ---- tint: recipe tint × caller colour ----
+    let cr = 1, cg = 1, cb = 1, ca = 1;
+    const tn = def.tint || [1, 1, 1, 1];
+    cr = tn[0]; cg = tn[1]; cb = tn[2]; ca = tn[3];
+    if (color != null) {
+      if (Array.isArray(color)) { cr *= color[0]; cg *= color[1]; cb *= color[2]; if (color[3] != null) ca *= color[3]; }
+      else { const c = color.isColor ? color : new THREE.Color(color); cr *= c.r; cg *= c.g; cb *= c.b; }
+    }
+
+    // polygonOffset beats z-fighting against the surface it lies on; depthWrite off
+    // + transparent so overlapping splats blend instead of clipping each other.
+    const blending = def.blend === 'a' ? THREE.AdditiveBlending : THREE.NormalBlending;
+    const mat = new THREE.MeshBasicMaterial({
+      map: def.tex ? this.textures[def.tex] ?? null : null,
+      transparent: true, depthWrite: false, blending,
+      polygonOffset: true, polygonOffsetFactor: -4, polygonOffsetUnits: -4,
+      side: THREE.DoubleSide, fog: false,
+    });
+    mat.color.setRGB(cr, cg, cb);
+
+    const mesh = new THREE.Mesh(geo, mat);
+
+    // ---- orient the quad to the surface normal, then spin about it ----
+    _n.set(normal[0], normal[1], normal[2]);
+    if (_n.lengthSq() < 1e-8) _n.set(0, 1, 0);
+    _n.normalize();
+    _q.setFromUnitVectors(_FWD, _n);
+    let ang = 0;
+    const spec = rot != null ? rot : def.rot;
+    if (spec === 'rand') ang = Math.random() * Math.PI * 2;
+    else if (typeof spec === 'number') ang = spec * Math.PI / 180;
+    if (ang) { _spin.setFromAxisAngle(_n, ang); _q.premultiply(_spin); }
+    mesh.quaternion.copy(_q);
+
+    // lift along the normal to avoid z-fighting (default 0.02m)
+    const yOff = def.yOffset != null ? def.yOffset : 0.02;
+    mesh.position.set(pos.x ?? pos[0], pos.y ?? pos[1], pos.z ?? pos[2]).addScaledVector(_n, yOff);
+
+    // ---- fade bookkeeping: life 0/null = persistent (fades in, never out) ----
+    const life = def.life || 0;
+    const fadeIn = def.fade ? def.fade[0] : 0;
+    const fadeOut = def.fade ? def.fade[1] : 0;
+    const d = { mesh, age: 0, life, fadeIn, fadeOut, baseAlpha: ca };
+    // spawn at the correct first-frame alpha (0 if fading in) so it never pops
+    mat.opacity = fadeIn > 0 ? 0 : ca;
+
+    this.scene.add(mesh);
+    this.items.push(d);
+    // ring buffer: evict the oldest beyond budget
+    while (this.items.length > this.max) this._dispose(this.items.shift());
+
+    return { decal: d, remove: () => this._remove(d) };
+  }
+
+  _dispose(d) {
+    if (!d) return;
+    this.scene.remove(d.mesh);
+    d.mesh.geometry.dispose();
+    d.mesh.material.dispose();
+  }
+
+  _remove(d) {
+    const i = this.items.indexOf(d);
+    if (i >= 0) { this.items.splice(i, 1); this._dispose(d); }
+  }
+
+  update(dt) {
+    for (let i = this.items.length - 1; i >= 0; i--) {
+      const d = this.items[i];
+      d.age += dt;
+      let a = d.baseAlpha;
+      if (d.fadeIn > 0 && d.age < d.fadeIn) a *= d.age / d.fadeIn;
+      if (d.life > 0) {
+        if (d.age >= d.life) { this.items.splice(i, 1); this._dispose(d); continue; }
+        const remain = d.life - d.age;
+        if (d.fadeOut > 0 && remain < d.fadeOut) a *= Math.max(0, remain / d.fadeOut);
+      }
+      d.mesh.material.opacity = a;
+    }
+  }
+
+  clear() {
+    for (const d of this.items) this._dispose(d);
+    this.items.length = 0;
+  }
+}

package/src/core/quality.js

@@ -0,0 +1,109 @@
+// Graphics quality presets + auto-downgrade for weaker machines.
+// pixelRatio and culling apply live; antialias applies on next reload.
+const KEY = 'aldenvale_quality';
+
+export const PRESETS = {
+  low: {
+    label: 'Low',
+    pixelRatio: 1,
+    antialias: false,
+    shadows: false,
+    shadowSize: 512,
+    entityCull: 45,       // hide+freeze characters beyond this (m)
+    animHalfRate: 22,     // beyond this, animate every other frame
+    animMidRate: 33,      // beyond this, every 3rd frame (every 4th near the cull edge)
+    maxLamps: 2,
+    fogScale: 0.45,       // pulls fog in = less overdraw
+    cameraFar: 200,
+  },
+  medium: {
+    label: 'Medium',
+    pixelRatio: 1.5,
+    antialias: true,
+    shadows: false,   // shadow mapping retired (again — re-landed solo): the pass is a SECOND
+    shadowSize: 1024, // full scene render EVERY frame (~7.5ms; r184 ignores the renderer-level
+                      // throttle flags). Characters get blob discs (world/blobShadows.js).
+    entityCull: 70,
+    animHalfRate: 32,
+    animMidRate: 48,
+    maxLamps: 6,
+    fogScale: 0.8,
+    cameraFar: 420,
+  },
+  high: {
+    label: 'High',
+    pixelRatio: 1.5, // was 2 — full retina cost ~1.5ms/frame for imperceptible gain at TRAA
+    antialias: true,
+    shadows: false,   // retired — see medium
+    shadowSize: 2048,
+    entityCull: 110,
+    animHalfRate: 55,
+    animMidRate: 80,
+    maxLamps: 15,
+    fogScale: 1,
+    cameraFar: 800,
+  },
+};
+
+export function getQualityName() {
+  const q = localStorage.getItem(KEY);
+  return PRESETS[q] ? q : 'medium';     // safe default; auto-tuner adjusts
+}
+export function getQuality() { return PRESETS[getQualityName()]; }
+export function setQualityName(name) { if (PRESETS[name]) localStorage.setItem(KEY, name); }
+
+// Apply everything that can change live.
+export function applyQuality(game, name) {
+  setQualityName(name);
+  const q = PRESETS[name];
+  const r = game.renderer;
+  r.setPixelRatio(Math.min(window.devicePixelRatio, q.pixelRatio));
+  r.setSize(window.innerWidth, window.innerHeight);
+  // NOTE: shadows are configured once at startup (renderer.js / sky.js).
+  // Mutating shadow maps live corrupts the WebGPU backend's shadow state
+  // and the sun renders everything as shadowed (world goes dark at noon).
+  game.camera.far = q.cameraFar;
+  game.camera.updateProjectionMatrix();
+  game.quality = q;
+  game.qualityName = name;
+  game.__traa = true; // live A/B override only — TRAA now exists solely when opted in via ?traa (renderer.wantsTRAA); default is the plain render path on every tier
+  if (game.world) {
+    game.world.quality = q;
+    if (game.world.sky) game.world.sky.fogScale = q.fogScale;
+  }
+}
+
+// Rolling fps monitor: steps quality down when the machine can't keep up.
+export class AutoTuner {
+  constructor(game) {
+    this.game = game;
+    this.acc = 0;
+    this.frames = 0;
+    this.grace = 6;            // ignore the first seconds (loading hitches)
+    this.done = false;
+  }
+  update(dt) {
+    if (this.done) return;
+    if (this.grace > 0) { this.grace -= dt; return; }
+    this.acc += dt;
+    this.frames++;
+    if (this.acc < 5) return;
+    const fps = this.frames / this.acc;
+    this.acc = 0; this.frames = 0;
+    const order = ['high', 'medium', 'low'];
+    const cur = order.indexOf(this.game.qualityName);
+    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
+      this.badRun = (this.badRun ?? 0) + 1;
+      if (this.badRun >= 2) {
+        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);
+      }
+    } else if (fps >= 24) {
+      this.done = true;        // stable — stop fiddling
+    }
+  }
+}

package/src/core/utils.js

@@ -0,0 +1,48 @@
+// Small shared helpers.
+import * as THREE from 'three/webgpu';
+import { ImprovedNoise } from 'three/addons/math/ImprovedNoise.js';
+
+export const noise = new ImprovedNoise();
+
+// Deterministic pseudo-random for reproducible world generation.
+export function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function () {
+    a |= 0; a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+export function fbm(x, z, octaves = 4, lacunarity = 2, gain = 0.5, scale = 0.01) {
+  let amp = 1, freq = scale, sum = 0, norm = 0;
+  for (let i = 0; i < octaves; i++) {
+    sum += amp * noise.noise(x * freq, z * freq, 7.31 + i * 13.7);
+    norm += amp;
+    amp *= gain;
+    freq *= lacunarity;
+  }
+  return sum / norm;
+}
+
+export function clamp(v, a, b) { return Math.min(b, Math.max(a, v)); }
+export function lerp(a, b, t) { return a + (b - a) * t; }
+export function smoothstep(a, b, t) {
+  const x = clamp((t - a) / (b - a), 0, 1);
+  return x * x * (3 - 2 * x);
+}
+export function dist2D(ax, az, bx, bz) { const dx = ax - bx, dz = az - bz; return Math.sqrt(dx * dx + dz * dz); } // hypot is 5-10x slower in V8 — this is THE hot distance helper
+
+// Shortest-arc angle lerp for smooth turning.
+export function angleLerp(a, b, t) {
+  let d = (b - a) % (Math.PI * 2);
+  if (d > Math.PI) d -= Math.PI * 2;
+  if (d < -Math.PI) d += Math.PI * 2;
+  return a + d * t;
+}
+
+export const tmpV1 = new THREE.Vector3();
+export const tmpV2 = new THREE.Vector3();
+export const tmpV3 = new THREE.Vector3();
+export const tmpQ1 = new THREE.Quaternion();

package/src/index.js

@@ -0,0 +1,31 @@
+// Sindicate — open-world game engine for three.js WebGPU.
+//
+// Games import subsystems directly ('sindicate/core/utils.js') or via this
+// barrel. Source ESM, no build step: the game's bundler compiles engine
+// sources, so you can step into engine code while debugging a game.
+//
+// Migration status (see ENGINE_DESIGN.md §9): step 1 — the verified-clean
+// tier, moved verbatim from the western game. Refactors (config injection,
+// facet contracts) land in later steps; step 1 files are byte-identical to
+// their proven originals on purpose.
+
+// core — math/utils, quality presets + auto-tuner, decals
+export * from './core/utils.js';
+export { PRESETS, getQuality, getQualityName, setQualityName, applyQuality, AutoTuner } from './core/quality.js';
+export { DecalField } from './core/decalField.js';
+
+// world — collision (sync + worker BVH), water materials, grass, wind, shared weather uniforms
+export * from './world/collision.js';
+export * from './world/water.js';
+export * from './world/grass.js';
+export * from './world/wind.js';
+export * from './world/weatherUniforms.js';
+export * from './world/waterNoise.js';
+
+// systems — pooled debris shatter
+export * from './systems/shatter.js';
+
+// vendor — patched FBXLoader (merges ALL FBX animation layers per stack;
+// stock three drops all but the first and multi-layer Synty packs T-pose).
+// Pinned against three ^0.184 — re-verify on every three upgrade.
+export { FBXLoader } from './vendor/FBXLoader.js';

package/src/systems/shatter.js

@@ -0,0 +1,94 @@
+// Physics-y debris shatter: when a pot/urn is smashed we clone the pack's real vase-shard meshes
+// (SM_Prop_Vase_Shard_01..04), fling them out with a little velocity + spin, let gravity drop them,
+// bounce + settle on the floor, then fade them away. Pure CPU integration on a tiny pool — no engine,
+// no per-shard lights, nothing resident (the meshes are added on smash and removed when faded).
+import * as THREE from 'three/webgpu';
+
+const G = 17;              // gravity (m/s²-ish, tuned for snappy low-poly debris)
+const REST = 0.34;         // floor bounce restitution
+const FRICTION = 0.62;     // horizontal speed kept per bounce
+const SETTLE_HOLD = 1.4;   // seconds a settled shard lingers before fading
+const FADE = 1.1;          // fade-out duration
+
+export class Shatter {
+  constructor(scene) { this.scene = scene; this.pieces = []; }
+
+  // pos: world Vector3 (base of the pot). frags: array of template Object3D to clone (the shards).
+  // floorY: Y the shards rest on. opts.count = how many shards to throw.
+  // Templates carrying userData.pivot (pre-fractured smashables) spawn at their true
+  // position INSIDE the prop and fly outward from its centre, so the prop visibly
+  // breaks apart along its fracture planes instead of debris materialising at a point.
+  // opts.dir (unit Vector3) carries the blow through; opts.ry = the prop's yaw.
+  burst(pos, frags, { count = 8, floorY = pos.y, spread = 2.4, up = 3.2, scale = 1, dir = null, ry = 0 } = {}) {
+    if (!frags || !frags.length) return;
+    const cy = Math.cos(ry), sy = Math.sin(ry);
+    for (let i = 0; i < count; i++) {
+      const tmpl = frags[i % frags.length];
+      const m = tmpl.clone(true);
+      // independent material instances so each shard fades on its own
+      m.traverse((o) => { if (o.material) o.material = Array.isArray(o.material) ? o.material.map((x) => x.clone()) : o.material.clone(); });
+      m.scale.multiplyScalar(scale);
+      const pivot = tmpl.userData?.pivot;
+      let vel;
+      if (pivot) {
+        const px = (pivot.x * cy + pivot.z * sy) * scale, pz = (pivot.z * cy - pivot.x * sy) * scale;
+        m.position.set(pos.x + px, pos.y + pivot.y * scale, pos.z + pz);
+        m.rotation.set(0, ry, 0);                                  // shards start in the prop's rest orientation
+        const ol = Math.hypot(px, pz) || 1;
+        vel = new THREE.Vector3((px / ol) * spread * (0.4 + Math.random() * 0.6), up * (0.35 + Math.random() * 0.55), (pz / ol) * spread * (0.4 + Math.random() * 0.6));
+        m.userData.spinScale = 0.55;                               // chunky prop shards tumble slower than pot slivers
+      } else {
+        m.position.copy(pos).add(new THREE.Vector3((Math.random() - 0.5) * 0.35, 0.25 + Math.random() * 0.45, (Math.random() - 0.5) * 0.35));
+        m.rotation.set(Math.random() * 6.28, Math.random() * 6.28, Math.random() * 6.28);
+        vel = new THREE.Vector3((Math.random() - 0.5) * spread, up * (0.55 + Math.random() * 0.7), (Math.random() - 0.5) * spread);
+      }
+      if (dir) vel.addScaledVector(dir, spread * (0.5 + Math.random() * 0.4)); // the blow carries through
+      this.scene.add(m);
+      const ss = m.userData.spinScale ?? 1;
+      this.pieces.push({
+        m, floorY: floorY + 0.04 + Math.random() * 0.04, // settle just above the floor (slight stack)
+        vel,
+        spin: new THREE.Vector3((Math.random() - 0.5) * 9 * ss, (Math.random() - 0.5) * 9 * ss, (Math.random() - 0.5) * 9 * ss),
+        rest: false, settleT: 0,
+      });
+    }
+  }
+
+  update(dt) {
+    if (!this.pieces.length) return;
+    dt = Math.min(dt, 0.04);
+    for (let i = this.pieces.length - 1; i >= 0; i--) {
+      const p = this.pieces[i];
+      if (!p.rest) {
+        p.vel.y -= G * dt;
+        p.m.position.addScaledVector(p.vel, dt);
+        p.m.rotation.x += p.spin.x * dt; p.m.rotation.y += p.spin.y * dt; p.m.rotation.z += p.spin.z * dt;
+        if (p.m.position.y <= p.floorY) {
+          p.m.position.y = p.floorY;
+          p.vel.y = -p.vel.y * REST;
+          p.vel.x *= FRICTION; p.vel.z *= FRICTION;
+          p.spin.multiplyScalar(0.45);
+          if (Math.abs(p.vel.y) < 0.7 && p.vel.x * p.vel.x + p.vel.z * p.vel.z < 0.4) { p.rest = true; p.spin.set(0, 0, 0); }
+        }
+      } else {
+        p.settleT += dt;
+        if (p.settleT > SETTLE_HOLD) {
+          const a = 1 - (p.settleT - SETTLE_HOLD) / FADE;
+          p.m.traverse((o) => { if (o.material) { o.material.transparent = true; o.material.depthWrite = false; o.material.opacity = a < 0 ? 0 : a; } });
+          if (a <= 0) { this.scene.remove(p.m); disposeMats(p.m); this.pieces.length && this.pieces.splice(i, 1); }
+        }
+      }
+    }
+  }
+
+  clear() { for (const p of this.pieces) { this.scene.remove(p.m); disposeMats(p.m); } this.pieces.length = 0; }
+}
+
+// shards clone their materials per piece (independent fades) — free them on removal
+// (geometry is SHARED with the templates and must never be disposed here)
+function disposeMats(root) {
+  root.traverse((o) => {
+    const mats = Array.isArray(o.material) ? o.material : (o.material ? [o.material] : []);
+    for (const m of mats) m.dispose?.();
+  });
+}