sindicate 0.1.0 → 0.4.0

package/src/systems/vfx.js

@@ -0,0 +1,472 @@
+// VFX: legacy sprite bursts + a faithful interpreter for the POLYGON Particle FX
+// pack's Unity ParticleSystem recipes (data/fxRecipes.js — extracted straight from
+// the prefab YAML). Each recipe is 1-4 coordinated emitters: burst/rate emission
+// from shaped volumes (sphere/hemisphere/cone/circle/edge/box), alpha+colour
+// gradients and size curves over particle lifetime, gravity/damping/noise, and a
+// renderer that is either a textured billboard or one of the pack's FX meshes
+// (e.g. blood gouts are FX_Sphere mesh particles, stun stars an FX_Star mesh —
+// not sprites).
+import * as THREE from 'three/webgpu';
+import { loadTexture, loadModel } from '../core/assets.js';
+// Particle recipes are GAME data (Unity-pack-derived) — register at boot:
+//   registerFxRecipes(FX_RECIPES)
+let FX_RECIPES = {};
+export function registerFxRecipes(recipes) { FX_RECIPES = recipes ?? {}; }
+import { DecalField } from '../core/decalField.js';
+
+const P = '/assets/particles';
+const GRAV = 9.81; // unity gravityModifier is a multiplier on physics gravity
+const Z2 = [0, 0];
+
+// Ground blood decals — four matte splats cut from the Biostart "Blood VFX Kit" atlas
+// (imported via ~/Sites/unity-vfx-webgpu). Laid flat where a foe falls; fade after ~30s.
+const BLOOD_DECALS = {
+  bloodSplat1: { tex: 'BloodSplat_1', sz: [0.65, 1.0], life: 32, fade: [0, 7], rot: 'rand', tint: [0.82, 0.72, 0.72, 0.92], yOffset: 0.04 },
+  bloodSplat2: { tex: 'BloodSplat_2', sz: [0.6, 0.9], life: 32, fade: [0, 7], rot: 'rand', tint: [0.82, 0.72, 0.72, 0.92], yOffset: 0.04 },
+  bloodSplat3: { tex: 'BloodSplat_3', sz: [0.8, 1.2], life: 32, fade: [0, 7], rot: 'rand', tint: [0.82, 0.72, 0.72, 0.92], yOffset: 0.04 },
+  bloodSplat4: { tex: 'BloodSplat_4', sz: [0.75, 1.1], life: 32, fade: [0, 7], rot: 'rand', tint: [0.82, 0.72, 0.72, 0.92], yOffset: 0.04 },
+};
+const BLOOD_KEYS = Object.keys(BLOOD_DECALS);
+const _e = new THREE.Euler();
+const _q = new THREE.Quaternion();
+const _v = new THREE.Vector3();
+const _v2 = new THREE.Vector3();
+
+const rand = (r) => r[0] + Math.random() * (r[1] - r[0]);
+
+// piecewise-linear gradient stops [[t, ...vals]] — Unity clamps outside the keys
+function sampleStop(stops, t, ch) {
+  const first = stops[0], last = stops[stops.length - 1];
+  if (t <= first[0]) return first[ch];
+  if (t >= last[0]) return last[ch];
+  for (let i = 1; i < stops.length; i++) {
+    if (t <= stops[i][0]) {
+      const a = stops[i - 1], b = stops[i];
+      const u = (t - a[0]) / (b[0] - a[0] || 1);
+      return a[ch] + (b[ch] - a[ch]) * u;
+    }
+  }
+  return last[ch];
+}
+
+// 9-sample size-over-lifetime LUT (Hermite curve baked at extract time)
+function sampleLut(lut, t) {
+  const x = Math.min(Math.max(t, 0), 1) * 8;
+  const i = Math.floor(x);
+  if (i >= 8) return lut[8];
+  return lut[i] + (lut[i + 1] - lut[i]) * (x - i);
+}
+
+export class VFX {
+  constructor(scene) {
+    this.scene = scene;
+    this.active = [];    // legacy sprite bursts
+    this.playing = [];   // live recipe instances (emission drivers)
+    this.rp = [];        // live recipe particles
+    this.textures = {};
+    this.fxMesh = {};    // FX mesh name -> geometry at native metre scale
+    this.protoMats = new Map(); // (map,blend) -> prototype SpriteMaterial (see _spriteMat)
+    // vendored from ~/Sites/unity-vfx-webgpu — laid-flat ground decals (blood pools)
+    this.decals = new DecalField(scene, { loadTexture, textureBase: `${P}/blood`, max: 80 });
+  }
+
+  // Recipe billboards CLONE a boot-made prototype instead of constructing fresh
+  // materials mid-update — sprite materials born inside the update loop with the
+  // recipe's full constructor args never render under WebGPU (their opacity
+  // writes don't take), while clones of a plain proven material always do.
+  _spriteMat(map, blending) {
+    const key = (map?.uuid ?? 'none') + blending;
+    let proto = this.protoMats.get(key);
+    if (!proto) {
+      proto = new THREE.SpriteMaterial({ map, transparent: true, depthWrite: false, blending });
+      this.protoMats.set(key, proto);
+    }
+    return proto.clone();
+  }
+
+  async load() {
+    const names = ['star_06', 'flame_01', 'smoke_04', 'light_01', 'muzzle_01', 'spark_04', 'circle_05', 'twirl_01'];
+    for (const n of names) this.textures[n] = await loadTexture(`${P}/${n}.png`);
+    // Synty Particle FX pack sprites (legacy shorthand keys)
+    const synty = {
+      sSmoke: 'PolygonParticles_Smoke_01', sSparkle: 'PolygonParticles_Sparkle',
+      sSpot: 'PolygonParticles_Soft_Spot', sRing: 'PolygonParticles_Ring_02',
+      sBolt: 'PolygonParticles_Lightning_02', sFumes: 'PolygonParticles_Fumes_02',
+      sSwipe: 'PolygonParticles_Swipe_01', sCircle: 'PolygonParticles_Circle_01',
+    };
+    for (const [k, f] of Object.entries(synty)) {
+      try { this.textures[k] = await loadTexture(`${P}/synty/${f}.png`); } catch { /* optional */ }
+    }
+    // every texture + FX mesh the recipes reference, under their pack names
+    const texNames = new Set(), meshNames = new Set();
+    for (const emitters of Object.values(FX_RECIPES)) {
+      for (const e of emitters) {
+        if (e.tex && e.tex !== 'soft') texNames.add(e.tex);
+        if (e.mesh) meshNames.add(e.mesh);
+      }
+    }
+    this.textures.soft = this.textures.light_01; // unity Default-Particle stand-in
+    for (const n of texNames) {
+      if (this.textures[n]) continue;
+      try { this.textures[n] = await loadTexture(`${P}/synty/${n}.png`); } catch { console.warn('[vfx] missing tex', n); }
+    }
+    // FX meshes at NATIVE metre scale (loadModel applies the cm→m factor to the
+    // group; bake it into the geometry so unity's meshSize × particleSize holds).
+    // Pivots matter (beams grow from their base) — no recentring, no normalizing.
+    for (const n of meshNames) {
+      try {
+        const m = await loadModel(`/assets/fx/${n}.fbx`);
+        m.updateMatrixWorld(true);
+        let geo = null;
+        m.traverse((o) => { if (!geo && o.isMesh) geo = o.geometry.clone().applyMatrix4(o.matrixWorld); });
+        if (geo) this.fxMesh[n] = geo;
+      } catch { console.warn('[vfx] missing mesh', n); }
+    }
+    this._warm();
+    await this.decals.load(BLOOD_DECALS);
+  }
+
+  // one resident object per material/pipeline variant, parked under the map, so
+  // boot's compileAsync builds the WebGPU pipelines — not the first cast mid-fight
+  _warm() {
+    const g = new THREE.Group();
+    g.name = 'vfxwarm';
+    g.position.set(0, -800, -50);
+    const tex = this.textures.sSparkle ?? this.textures.star_06;
+    const geo = this.fxMesh.FX_Cylinder_01 ?? new THREE.PlaneGeometry(0.1, 0.1);
+    const mk = (mat) => { const o = mat.isSpriteMaterial ? new THREE.Sprite(mat) : new THREE.Mesh(geo, mat); o.scale.setScalar(0.01); g.add(o); };
+    mk(new THREE.SpriteMaterial({ map: tex, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending }));
+    mk(new THREE.SpriteMaterial({ map: tex, transparent: true, depthWrite: false }));
+    // muzzle flash sprite variant — compiled at boot, never on the first shot
+    mk(new THREE.SpriteMaterial({ map: this.textures.muzzle_01 ?? tex, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending }));
+    mk(new THREE.MeshBasicMaterial({ map: tex, transparent: true, depthWrite: false, blending: THREE.AdditiveBlending, side: THREE.DoubleSide, fog: false }));
+    mk(new THREE.MeshBasicMaterial({ transparent: true, depthWrite: false, blending: THREE.AdditiveBlending, side: THREE.DoubleSide, fog: false }));
+    mk(new THREE.MeshBasicMaterial({ transparent: true, depthWrite: false, side: THREE.DoubleSide, fog: false }));
+    this.scene.add(g);
+  }
+
+  // ---- recipe playback -------------------------------------------------------
+  // scale grows/shrinks the whole effect; color multiplies the authored colours
+  // (tier tints); speed is Unity's simulationSpeed (2 = plays in half the time);
+  // density multiplies particle counts; sizeMul fattens particles without
+  // widening the emitter. Returns a {stop} handle for looping recipes.
+  playFx(name, { pos, scale = 1, color = null, yaw = 0, loopFor = Infinity, speed = 1, density = 1, sizeMul = 1 } = {}) {
+    const def = FX_RECIPES[name];
+    if (!def) return null;
+    const inst = {
+      def, x: pos.x, y: pos.y, z: pos.z, scale, yaw, speed, den: density, szm: sizeMul,
+      col: color != null ? new THREE.Color(color) : null,
+      t: 0, stopAt: loopFor,
+      st: def.map(() => ({ fired: 0, acc: 0 })),
+    };
+    this.playing.push(inst);
+    return { stop: () => { inst.stopAt = 0; } };
+  }
+
+  _spawnR(e, inst) {
+    const sc = inst.scale;
+    const sh = e.shape;
+    // ---- sample the emitter shape: local position + outward direction ----
+    let px = 0, py = 0, pz = 0, dx = 0, dy = 0, dz = 1;
+    if (sh) {
+      const vol = sh.thick === 0 ? 1 : Math.cbrt(Math.random()); // 0 = shell only
+      switch (sh.t) {
+        case 'sphere': case 'sphereShell': {
+          _v.set(Math.random() * 2 - 1, Math.random() * 2 - 1, Math.random() * 2 - 1).normalize();
+          dx = _v.x; dy = _v.y; dz = _v.z;
+          const rr = (sh.r || 0) * vol;
+          px = dx * rr; py = dy * rr; pz = dz * rr;
+          break;
+        }
+        case 'hemisphere': case 'hemisphereShell': {
+          _v.set(Math.random() * 2 - 1, Math.random() * 2 - 1, Math.random()).normalize();
+          dx = _v.x; dy = _v.y; dz = Math.abs(_v.z);
+          const rr = (sh.r || 0) * vol;
+          px = dx * rr; py = dy * rr; pz = dz * rr;
+          break;
+        }
+        case 'cone': case 'coneShell': case 'coneVolume': {
+          const a = (sh.ang * Math.PI / 180) * Math.sqrt(Math.random());
+          const phi = Math.random() * Math.PI * 2;
+          dx = Math.sin(a) * Math.cos(phi); dy = Math.sin(a) * Math.sin(phi); dz = Math.cos(a);
+          const rr = (sh.r || 0) * Math.sqrt(Math.random());
+          const phi2 = Math.random() * Math.PI * 2;
+          px = Math.cos(phi2) * rr; py = Math.sin(phi2) * rr;
+          break;
+        }
+        case 'circle': case 'circleEdge': {
+          const phi = Math.random() * Math.PI * 2;
+          dx = Math.cos(phi); dy = Math.sin(phi); dz = 0;
+          const rr = (sh.r || 0) * (sh.thick === 0 ? 1 : Math.sqrt(Math.random()));
+          px = dx * rr; py = dy * rr;
+          break;
+        }
+        case 'edge': {
+          px = (Math.random() * 2 - 1) * (sh.r || 0);
+          dx = 0; dy = 1; dz = 0;
+          break;
+        }
+        case 'box': case 'boxShell': case 'boxEdge': {
+          const b = sh.box || [1, 1, 1];
+          px = (Math.random() - 0.5) * b[0]; py = (Math.random() - 0.5) * b[1]; pz = (Math.random() - 0.5) * b[2];
+          break;
+        }
+        default: {
+          _v.set(Math.random() * 2 - 1, Math.random() * 2 - 1, Math.random() * 2 - 1).normalize();
+          dx = _v.x; dy = _v.y; dz = _v.z;
+        }
+      }
+      const rot = sh.rot;
+      if (rot && (rot[0] || rot[1] || rot[2])) {
+        _e.set(rot[0] * Math.PI / 180, rot[1] * Math.PI / 180, rot[2] * Math.PI / 180);
+        _q.setFromEuler(_e);
+        _v.set(px, py, pz).applyQuaternion(_q); px = _v.x; py = _v.y; pz = _v.z;
+        _v.set(dx, dy, dz).applyQuaternion(_q); dx = _v.x; dy = _v.y; dz = _v.z;
+      }
+    }
+    if (inst.yaw) {
+      const c = Math.cos(inst.yaw), s = Math.sin(inst.yaw);
+      let t = px * c + pz * s; pz = -px * s + pz * c; px = t;
+      t = dx * c + dz * s; dz = -dx * s + dz * c; dx = t;
+    }
+    // ---- particle start values ----
+    const life = Math.max(0.05, rand(e.life));
+    const speed = rand(e.spd || Z2) * sc;
+    const size = rand(e.sz) * sc * inst.szm;
+    const sizeY = e.szY ? rand(e.szY) * sc * inst.szm : size;
+    const sizeZ = e.szZ ? rand(e.szZ) * sc * inst.szm : size; // beams stretch mesh particles along Z
+    let cr = e.col[0], cg = e.col[1], cb = e.col[2], ca = e.col[3];
+    if (e.col2) {
+      const m = Math.random();
+      cr += (e.col2[0] - cr) * m; cg += (e.col2[1] - cg) * m; cb += (e.col2[2] - cb) * m; ca += (e.col2[3] - ca) * m;
+    }
+    const tint = e.tint;
+    if (tint) { cr *= tint[0]; cg *= tint[1]; cb *= tint[2]; ca *= tint[3]; }
+    if (inst.col) { cr *= inst.col.r; cg *= inst.col.g; cb *= inst.col.b; }
+    const map = e.tex ? this.textures[e.tex] ?? null : null;
+    const blending = e.blend === 'a' ? THREE.AdditiveBlending : THREE.NormalBlending;
+    const isMesh = e.render === 'm';
+    // construct at the REAL first-frame alpha, never 0 — a sprite material born at
+    // opacity 0 inside the update loop never becomes visible under WebGPU (its
+    // later opacity writes don't take; a fresh material with the same values does)
+    const a0 = ca * (e.aK ? sampleStop(e.aK, 0, 1) : 1);
+    let o, mat;
+    if (isMesh) {
+      const geo = this.fxMesh[e.mesh];
+      if (!geo) return;
+      mat = new THREE.MeshBasicMaterial({
+        map, transparent: true, opacity: a0, depthWrite: false, blending,
+        side: THREE.DoubleSide, fog: false,
+      });
+      o = new THREE.Mesh(geo, mat);
+      // directional effects (yaw set) keep the emitter's axes so Z-stretched
+      // beam segments point down-range; radial ones get a random spin
+      o.rotation.y = e.rot0 ? rand(e.rot0) : (inst.yaw || Math.random() * Math.PI * 2);
+      o.scale.set(size, sizeY, sizeZ);
+    } else {
+      mat = this._spriteMat(map, blending);
+      mat.opacity = a0;
+      if (e.rot0) mat.rotation = rand(e.rot0);
+      o = new THREE.Sprite(mat);
+      o.scale.set(size, sizeY, 1);
+    }
+    mat.color.setRGB(cr, cg, cb);
+    const ep = e.p;
+    o.position.set(
+      inst.x + (ep ? ep[0] * sc : 0) + px * sc,
+      inst.y + (ep ? ep[1] * sc : 0) + py * sc,
+      inst.z + (ep ? ep[2] * sc : 0) + pz * sc
+    );
+    // unity renderer pivot (fractions of size) lifts e.g. the lightning bolt so
+    // it strikes DOWN onto the point instead of straddling it. sprite.center is
+    // a no-show under WebGPU, so it's a world-Y offset, kept in sync with the
+    // size curve in update(). Must come after position.set — it's additive.
+    if (!isMesh && e.pivot) o.position.y += e.pivot[1] * sizeY;
+    this.scene.add(o);
+    const vel = e.vel;
+    this.rp.push({
+      o, m: mat, isMesh, ts: inst.speed,
+      vx: dx * speed + (vel ? rand(vel[0]) * sc : 0),
+      vy: dy * speed + (vel ? rand(vel[1]) * sc : 0),
+      vz: dz * speed + (vel ? rand(vel[2]) * sc : 0),
+      age: 0, life, sz: size, szY: sizeY, szZ: sizeZ,
+      cr, cg, cb, ca,
+      aK: e.aK ?? null, cK: e.cK ?? null, szK: e.szK ?? null,
+      pvY: !isMesh && e.pivot ? e.pivot[1] : 0, pvOff: !isMesh && e.pivot ? e.pivot[1] * sizeY : 0,
+      rotV: e.rotV ? rand(e.rotV) : 0,
+      grav: (e.grav || 0) * GRAV * sc,
+      damp: e.damp || 0,
+      noise: e.noise ?? null, ph: Math.random() * 6.283,
+    });
+  }
+
+  // ---- legacy sprite bursts (hits, sparks, ambience one-liners) ---------------
+  spawn({ tex = 'star_06', pos, vel = null, count = 6, size = 0.5, life = 0.6, color = 0xffffff, gravity = 0, spread = 1.2, fade = true, additive = true }) {
+    for (let i = 0; i < count; i++) {
+      const mat = new THREE.SpriteMaterial({
+        map: this.textures[tex],
+        color,
+        transparent: true,
+        depthWrite: false,
+        blending: additive ? THREE.AdditiveBlending : THREE.NormalBlending,
+      });
+      const s = new THREE.Sprite(mat);
+      s.position.copy(pos);
+      s.position.x += (Math.random() - 0.5) * 0.3;
+      s.position.y += (Math.random() - 0.5) * 0.3 + 0.2;
+      s.position.z += (Math.random() - 0.5) * 0.3;
+      const sc = size * (0.6 + Math.random() * 0.8);
+      s.scale.setScalar(sc);
+      const v = vel
+        ? vel.clone()
+        : new THREE.Vector3((Math.random() - 0.5) * spread, Math.random() * spread, (Math.random() - 0.5) * spread);
+      this.scene.add(s);
+      this.active.push({ s, v, life, age: 0, gravity, fade, size: sc });
+    }
+  }
+
+  // ---- game effects — pack recipes with game-tuned scale/tint -----------------
+  hit(pos) {
+    this.spawn({ tex: 'star_06', pos, count: 6, size: 0.45, life: 0.3, color: 0xffd080, spread: 3 });
+    this.playFx('impact_small', { pos, scale: 1.2, speed: 2 });
+  }
+  spark(pos, size = 0.6) {
+    this.spawn({ tex: 'spark_04', pos, count: 10, size, life: 0.35, color: 0xfff0a0, spread: 4 });
+  }
+  // hit SQUIRT: a vivid directional jet of blood — fat gouts + a spray of fine droplets,
+  // launched along `dir` (defaults up-and-out) and arcing down hard under gravity.
+  // `mult` scales the droplet count — a bladed slash sprays ~2× a bare-fist punch.
+  blood(pos, dir = null, mult = 1) {
+    const d = (dir && dir.lengthSq() > 1e-6) ? _v.copy(dir).normalize() : _v.set(0, 0.55, 0.5).normalize();
+    const perp = _v2.set(-d.z, 0, d.x).normalize();
+    const dx = d.x, dy = d.y, dz = d.z, px = perp.x, pz = perp.z;
+    const shoot = (n, spdMin, spdMax, szMin, szMax, spread, col) => {
+      for (let i = 0; i < n; i++) {
+        const spd = spdMin + Math.random() * (spdMax - spdMin);
+        const s1 = (Math.random() - 0.5) * spread, s2 = (Math.random() - 0.15) * spread;
+        const v = new THREE.Vector3(
+          dx * spd + px * s1 + (Math.random() - 0.5) * spread * 0.4,
+          dy * spd + s2,
+          dz * spd + pz * s1 + (Math.random() - 0.5) * spread * 0.4,
+        );
+        this.spawn({ tex: 'circle_05', pos, vel: v, count: 1, size: szMin + Math.random() * (szMax - szMin), life: 0.4 + Math.random() * 0.3, color: col, gravity: 13, additive: false });
+      }
+    };
+    shoot(Math.round(16 * mult), 1.3, 3.0, 0.03, 0.06, 1.4, 0xd11818); // fine droplets (~3-6cm), vivid red
+    shoot(Math.round(5 * mult), 0.8, 1.8, 0.06, 0.1, 0.8, 0xa81212);   // fatter gouts (~6-10cm)
+  }
+  // a lasting pool of blood on the ground where a foe fell (normal = surface up)
+  bloodDecal(pos, normal = [0, 1, 0]) {
+    this.decals.add(BLOOD_KEYS[(Math.random() * BLOOD_KEYS.length) | 0], { pos, normal });
+  }
+
+  // muzzle flash (WESTERN_CONTRACT pin): a one-frame muzzle_01 star nudged down-range
+  // + a brief additive glow. ~0.06s, sprites only — NO point light (the light count
+  // never changes mid-session, so a flash light would need a resident pool for nothing).
+  muzzleFlash(pos, dir = null) {
+    const at = dir ? pos.clone().addScaledVector(dir, 0.1) : pos.clone();
+    const vel = dir ? dir.clone().multiplyScalar(0.6) : null;
+    this.spawn({ tex: 'muzzle_01', pos: at, vel, count: 1, size: 0.42, life: 0.06, color: 0xffdf9a, spread: 0 });
+    this.spawn({ tex: this.textures.sSpot ? 'sSpot' : 'light_01', pos: at, count: 1, size: 1.1, life: 0.08, color: 0xffb860, spread: 0 });
+  }
+
+  update(dt) {
+    this.decals.update(dt);
+    // ---- recipe instances drive emission ----
+    for (let i = this.playing.length - 1; i >= 0; i--) {
+      const inst = this.playing[i];
+      const idt = dt * (inst.speed || 1);
+      inst.t += idt;
+      let alive = false;
+      for (let ei = 0; ei < inst.def.length; ei++) {
+        const e = inst.def[ei], st = inst.st[ei];
+        const lt = inst.t - (e.delay || 0);
+        if (lt < 0) { alive = true; continue; }
+        const bursts = e.bursts;
+        if (bursts) {
+          for (let b = 0; b < bursts.length; b++) {
+            if (!(st.fired & (1 << b)) && lt >= bursts[b][0]) {
+              st.fired |= 1 << b;
+              const n0 = Math.round(bursts[b][1] * inst.den);
+              for (let n = 0; n < n0; n++) this._spawnR(e, inst);
+            }
+          }
+          if (st.fired !== (1 << bursts.length) - 1) alive = true;
+        }
+        if (e.rate) {
+          const emitting = e.loop ? inst.t < inst.stopAt : lt <= e.dur;
+          if (emitting) {
+            st.acc += e.rate * inst.den * idt;
+            while (st.acc >= 1) { st.acc -= 1; this._spawnR(e, inst); }
+            alive = true;
+          }
+        }
+        if (!e.loop && lt <= e.dur) alive = true;
+      }
+      if (!alive) this.playing.splice(i, 1);
+    }
+    // ---- recipe particles ----
+    for (let i = this.rp.length - 1; i >= 0; i--) {
+      const p = this.rp[i];
+      const pdt = dt * (p.ts || 1); // per-particle sim clock (playFx speed)
+      p.age += pdt;
+      if (p.age >= p.life) {
+        this.scene.remove(p.o);
+        p.m.dispose();
+        this.rp.splice(i, 1);
+        continue;
+      }
+      const t = p.age / p.life;
+      p.vy -= p.grav * pdt;
+      if (p.damp) {
+        const d = Math.max(0, 1 - p.damp * 3 * pdt);
+        p.vx *= d; p.vy *= d; p.vz *= d;
+      }
+      let mx = p.vx, my = p.vy, mz = p.vz;
+      if (p.noise) {
+        const w = p.noise[0], f = p.noise[1] * 7;
+        mx += Math.sin(p.age * f + p.ph) * w;
+        my += Math.sin(p.age * f * 0.83 + p.ph * 2.1) * w;
+        mz += Math.cos(p.age * f * 1.13 + p.ph) * w;
+      }
+      p.o.position.x += mx * pdt; p.o.position.y += my * pdt; p.o.position.z += mz * pdt;
+      p.m.opacity = p.ca * (p.aK ? sampleStop(p.aK, t, 1) : 1 - t);
+      if (p.cK) {
+        p.m.color.setRGB(
+          p.cr * sampleStop(p.cK, t, 1),
+          p.cg * sampleStop(p.cK, t, 2),
+          p.cb * sampleStop(p.cK, t, 3)
+        );
+      }
+      const s = p.szK ? sampleLut(p.szK, t) : 1;
+      if (p.isMesh) {
+        p.o.scale.set(p.sz * s, p.szY * s, p.szZ * s);
+        if (p.rotV) p.o.rotation.y += p.rotV * pdt;
+      } else {
+        p.o.scale.set(p.sz * s, p.szY * s, 1);
+        if (p.pvY) { // keep the pivot offset tracking the size curve
+          const off = p.pvY * p.szY * s;
+          p.o.position.y += off - p.pvOff;
+          p.pvOff = off;
+        }
+        if (p.rotV) p.m.rotation += p.rotV * pdt;
+      }
+    }
+    // ---- legacy sprites ----
+    for (let i = this.active.length - 1; i >= 0; i--) {
+      const p = this.active[i];
+      p.age += dt;
+      if (p.age >= p.life) {
+        this.scene.remove(p.s);
+        p.s.material.dispose();
+        this.active.splice(i, 1);
+        continue;
+      }
+      p.v.y -= p.gravity * dt;
+      p.s.position.addScaledVector(p.v, dt);
+      const t = p.age / p.life;
+      if (p.fade) p.s.material.opacity = 1 - t;
+      p.s.scale.setScalar(p.size * (1 + t * 0.6));
+    }
+  }
+}

package/src/world/blobShadows.js

@@ -0,0 +1,109 @@
+// Blob shadows: one InstancedMesh of soft dark discs under every nearby character.
+// This REPLACES sun shadow mapping (retired 2026-07-10) — the shadow pass was a second
+// full scene render every frame (~7.5ms CPU measured at Oakhollow; r184's ShadowNode
+// ignores the renderer-level throttle flags, so it ran every frame despite the
+// every-2nd-frame needsUpdate toggle). One draw call, no extra pass, resident for life
+// (the WebGPU rule: never create/destroy meshes at runtime — parked slots are scale-0).
+import * as THREE from 'three/webgpu';
+
+const CAP = 160;      // discs available per frame (player + everything close); extras just go discless
+const RANGE = 55;     // only characters this close get a disc — beyond that it's sub-pixel anyway
+// WHO GETS THE DISCS WHEN THERE ARE NOT ENOUGH. The fill used to stop at the first CAP bodies in
+// ARRAY ORDER — which was harmless with fourteen townsfolk and a disaster with a hundred and fifty:
+// Dustwater's residents are registered first, so they would take every disc in the pool and the
+// place you were actually standing in would have none. RANGE already drops everything far away;
+// what is left is sorted NEAREST-FIRST, so the discs that get dropped are the ones behind you.
+const _cand = [];     // reused every frame — no per-frame allocation in the hot path
+
+export class BlobShadows {
+  constructor(game) {
+    this.game = game;
+
+    // soft radial disc, generated — no asset, no loader
+    const S = 64;
+    const cnv = document.createElement('canvas');
+    cnv.width = cnv.height = S;
+    const ctx = cnv.getContext('2d');
+    const grad = ctx.createRadialGradient(S / 2, S / 2, S * 0.08, S / 2, S / 2, S / 2);
+    grad.addColorStop(0, 'rgba(0,0,0,0.40)');
+    grad.addColorStop(0.65, 'rgba(0,0,0,0.22)');
+    grad.addColorStop(1, 'rgba(0,0,0,0)');
+    ctx.fillStyle = grad;
+    ctx.fillRect(0, 0, S, S);
+    const tex = new THREE.CanvasTexture(cnv);
+
+    const geo = new THREE.PlaneGeometry(1, 1);
+    geo.rotateX(-Math.PI / 2);
+    const mat = new THREE.MeshBasicMaterial({ map: tex, transparent: true, depthWrite: false });
+    // hover the ground without z-fighting it (same trick as the road decals)
+    mat.polygonOffset = true;
+    mat.polygonOffsetFactor = -2;
+    mat.polygonOffsetUnits = -2;
+
+    const mesh = this.mesh = new THREE.InstancedMesh(geo, mat, CAP);
+    mesh.name = 'blobShadows';
+    mesh.frustumCulled = false;   // instances follow the whole near field; RANGE is the cull
+    mesh.matrixAutoUpdate = false;
+    mesh.renderOrder = 2;         // after terrain, before water foam/fx transparents
+    game.scene.add(mesh);
+
+    this._m = new THREE.Matrix4();
+    this._zero = new THREE.Matrix4().makeScale(0, 0, 0);
+  }
+
+  update() {
+    const g = this.game;
+    const p = g.player?.position;
+    if (!p) return;
+    const m = this._m, mesh = this.mesh;
+    _cand.length = 0;
+    // NO DISC WITHOUT A BODY OVER IT. RANGE is 55 m; the entity cull is 45 m at low quality
+    // (core/quality.js), so the ten metres between the two used to lay a shadow on the sand under a
+    // man the cull had already hidden. Fourteen townsfolk never caught it out; a hundred and fifty
+    // ring every settlement with ownerless shadows. Take whichever line is nearer.
+    const range = Math.min(RANGE, g.quality?.entityCull ?? RANGE);
+    const r2 = range * range;
+    const put = (pos, r) => {
+      if (!pos) return;
+      const dx = pos.x - p.x, dz = pos.z - p.z;
+      const d2 = dx * dx + dz * dz;
+      if (d2 > r2) return;
+      _cand.push(d2, pos, r);
+    };
+    for (const h of g.horses ?? []) put(h.position, 1.9);
+    // …AND A MAN IN A SADDLE THROWS NO DISC OF HIS OWN. A mounted traveller (game/mountedTraveller.js)
+    // is an ordinary NPC in game.npcs — that is what makes him shootable, lootable and a witness — but
+    // his `position` is the SADDLE, a metre and a half off the dirt, and `put` lays the disc at
+    // position.y + 4 cm. So he would hang a shadow in mid-air over a horse that is already throwing one.
+    for (const n of g.npcs ?? []) { if (!n.seated) put(n.position, n.child ? 0.62 : 0.95); }   // a child throws a child's shadow
+    for (const e of g.combat?.enemies ?? []) { if (!e.dead) put(e.position, 0.95); }
+    for (const t of g.travellers ?? []) put(t.position, 0.95);
+
+    // the player always has one; the rest go nearest-first
+    let i = 0;
+    m.makeScale(1.05, 1, 1.05); m.setPosition(p.x, p.y + 0.04, p.z);
+    mesh.setMatrixAt(i++, m);
+    const n = _cand.length / 3;
+    if (n > CAP - 1) {   // more bodies in range than discs: sort so the near ones win
+      const idx = (this._idx ??= []);
+      idx.length = n;
+      for (let k = 0; k < n; k++) idx[k] = k;
+      idx.sort((a, b) => _cand[a * 3] - _cand[b * 3]);
+      for (let k = 0; k < n && i < CAP; k++) {
+        const b = idx[k] * 3, pos = _cand[b + 1], r = _cand[b + 2];
+        m.makeScale(r, 1, r);
+        m.setPosition(pos.x, pos.y + 0.04, pos.z);   // .position sits at foot height; +4cm clears the ground plane
+        mesh.setMatrixAt(i++, m);
+      }
+    } else {
+      for (let b = 0; b < _cand.length && i < CAP; b += 3) {
+        const pos = _cand[b + 1], r = _cand[b + 2];
+        m.makeScale(r, 1, r);
+        m.setPosition(pos.x, pos.y + 0.04, pos.z);
+        mesh.setMatrixAt(i++, m);
+      }
+    }
+    for (; i < CAP; i++) mesh.setMatrixAt(i, this._zero);   // park the rest — scale-0 draws nothing
+    mesh.instanceMatrix.needsUpdate = true;
+  }
+}

package/src/world/clouds.js

@@ -0,0 +1,61 @@
+// PROCEDURAL CLOUD MATERIAL for the dome-anchored quads (sky.js owns the InstancedMesh + drift).
+// Each quad is ONE soft cumulus built from FBM noise — three octaves of the shared tiling noise texture,
+// shaped by a round envelope so it reads as a discrete puff, given lumpy self-shading for depth, and
+// ADVECTED DOWNWIND on the global wind so the shapes stream and evolve instead of sitting dead. No two
+// clouds repeat (each seeds its noise off its instance index). This replaces the old single radial-blob
+// sprite that made all 52 clouds identical flat discs.
+//
+// `tint` (vec3 uniform) and `opacity` (float uniform) are written each frame by sky.js — the phase/weather
+// colour (white by day, dusk hues at sunset, slate under a storm, dimmed at night) and the deck's alpha.
+import * as THREE from 'three/webgpu';
+import { uv, texture, float, vec2, mix, smoothstep, length, hash, instanceIndex, time, uniform, attribute } from 'three/tsl';
+import { uCloudiness, uWindDir } from './weatherUniforms.js';
+import { waterNoiseTexture } from './waterNoise.js';
+
+export function buildCloudMaterial() {
+  const tint = uniform(new THREE.Color(1, 1, 1));
+  const opacity = uniform(0.6);
+  const noiseTex = waterNoiseTexture();
+  const mat = new THREE.MeshBasicNodeMaterial({ transparent: true, depthWrite: false, fog: false, side: THREE.DoubleSide });
+
+  const seed = hash(instanceIndex);                 // per-cloud offsets → no two puffs alike
+  const seed2 = hash(instanceIndex.add(37));
+  const nScale = hash(instanceIndex.add(7)).mul(0.8).add(0.55);   // per-cloud NOISE FREQUENCY — kept low so the edge is LUMPY, not stringy
+  const wisp = hash(instanceIndex.add(23)).mul(0.12).sub(0.02);   // per-cloud rim bias: − fuller, + softer/thinner rim
+  const p = uv();                                   // 0..1 across the quad
+  const r = length(p.sub(0.5)).mul(2.0);            // 0 at the centre … ~1.4 at the corner
+
+  const drift = uWindDir.mul(time.mul(0.004));      // stream the noise field DOWNWIND (vec2)
+  const q = p.mul(nScale).add(vec2(seed, seed2)).add(drift);
+  const n1 = texture(noiseTex, q).r;
+  const n2 = texture(noiseTex, q.mul(2.3).add(vec2(seed2, seed))).r;
+  const n3 = texture(noiseTex, q.mul(4.9).add(vec2(seed, seed2).mul(2.0))).r;
+  const fbm = n1.mul(0.55).add(n2.mul(0.30)).add(n3.mul(0.15));   // ~0..1
+
+  const thick = uCloudiness.mul(0.28);              // a storm deck grows bigger + fuller
+  // SOLID cotton body with a CAULIFLOWER ragged edge: the noise perturbs the silhouette RADIUS, it does
+  // NOT hollow out the middle. (Driving opacity by fbm across the whole cloud punched transparent holes
+  // through the body and left the thin stringy smears.) The internal fbm is kept only for the lumpy
+  // self-shading below, so the billows still catch light without the body going see-through.
+  const edge = r.add(fbm.sub(0.5).mul(0.5));
+  const body = smoothstep(float(0.98).add(wisp), float(0.46).sub(thick.mul(0.3)), edge);
+  // FLAT BASE: clip the rounded bottom off along a near-horizontal (faintly wavy) line, so each cloud
+  // reads as a real cumulus sitting on its condensation level rather than a cotton ball. p.y is the
+  // cloud's world-vertical (sky.js orients the quad's +Y to world-up), so low p.y = the base.
+  const baseCut = smoothstep(float(0.26), float(0.42), p.y.add(fbm.sub(0.5).mul(0.08)));
+  const dens = body.mul(baseCut);
+
+  // lumpy self-shading: denser core catches more light, the fluffed edges fall into soft shadow — reads
+  // as volume/depth without a per-quad light direction (the quads are billboarded + rolled every which way)
+  // DIRECTIONAL LIGHT. sky.js orients each quad so its +Y is WORLD-UP, so the TOP of the cloud is its
+  // sunlit CROWN and the bottom is the self-shadowed flat BASE; `aSun` (per cloud, −1 sun-left … +1
+  // sun-right) shifts the bright side toward the sun's azimuth. fbm ruffles the gradient so it reads as
+  // lumpy billows catching light, not a flat ramp. (Was a flat lumpiness with no sense of light direction.)
+  const aSun = attribute('aSun', 'float');
+  const crown = p.y.mul(1.1).add(fbm.sub(0.5).mul(0.5)).add(aSun.mul(p.x.sub(0.5)).mul(0.7)).sub(0.05).clamp(0, 1);
+  const shade = mix(float(0.5), float(1.2), crown);
+
+  mat.colorNode = tint.mul(shade);
+  mat.opacityNode = dens.mul(opacity);
+  return { material: mat, tint, opacity };
+}