@call-me-sensei/toonlab 0.3.0 → 0.4.19

package/src/ambientfx/particleBackbone.js

@@ -1,493 +0,0 @@
-// The ONE shared GPU particle system behind every ambient effect. Same
-// architecture as StylizedGrassField: an InstancedBufferGeometry over a unit
-// quad, per-instance attributes filled once per (rare) window re-emission,
-// and ALL motion computed in the TSL vertex shader as a pure function of
-// time — zero per-frame CPU work per particle, works on WebGPU and the
-// WebGL2 fallback alike.
-//
-// Draw calls: the five effects share THREE meshes, grouped by blend state —
-// that is the real GPU boundary, not the effect:
-//   cutout — petals + leaves     (alpha-test, depth-writing, double-sided)
-//   glow   — fireflies + pollen  (additive, no depth write, emissive/unlit)
-//   soft   — mist                (alpha blend, no depth write)
-// Within a group the per-instance `kind` attribute selects the motion
-// program (flutter-fall / tumble-fall / hover-blink / curl-drift / scroll),
-// so adding an effect never adds a draw. A single backbone draw for all five
-// was rejected: cutout needs depth writes that would occlude through the
-// additive glows, and mist's alpha blend cannot share either state.
-//
-// Budget: ≤ 20k instances of 2 triangles with trig-only vertex work and
-// mostly-discard flat fragments — far under the 0.5 ms cluster budget.
-
-import * as THREE from 'three';
-import { NodeMaterial } from 'three/webgpu';
-import {
-  abs, attribute, cameraPosition, cameraProjectionMatrix, cameraViewMatrix, clamp, cos, Discard,
-  distance, exp, float, Fn, fract, length, max, mix, modelWorldMatrix, normalize, positionLocal,
-  pow, rotate, sin, smoothstep, step, uniform, uv, varying, vec2, vec3, vec4,
-} from 'three/tsl';
-
-// --- deterministic randomness (shared with emitters + verify script) --------
-
-/** Chris Wellons' lowbias32: uint32 -> well-mixed uint32. */
-export function lowbias32(x) {
-  let h = x >>> 0;
-  h = Math.imul(h ^ (h >>> 16), 0x7feb352d) >>> 0;
-  h = Math.imul(h ^ (h >>> 15), 0x846ca68b) >>> 0;
-  return (h ^ (h >>> 16)) >>> 0;
-}
-
-/** Mixes two uint32 seeds into one (order-sensitive). */
-export function hashCombine(a, b) {
-  return lowbias32((a >>> 0) ^ (Math.imul(b >>> 0, 0x9e3779b9) >>> 0));
-}
-
-/** mulberry32 PRNG: uint32 seed -> () => [0, 1). No Math.random anywhere. */
-export function mulberry32(seed) {
-  let state = (Math.trunc(seed) || 1) >>> 0;
-  return () => {
-    state = (state + 0x6d2b79f5) >>> 0;
-    let t = state;
-    t = Math.imul(t ^ (t >>> 15), t | 1);
-    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-  };
-}
-
-// --- effect/window constants -------------------------------------------------
-
-/** Backbone kind ids — the per-instance `iData.w` attribute. */
-export const EFFECT_KIND = Object.freeze({ petals: 0, leaves: 1, fireflies: 2, pollen: 3, mist: 4 });
-
-/** Which blend-group mesh each kind renders in. */
-export const GROUP_FOR_KIND = Object.freeze({
-  petals: 'cutout', leaves: 'cutout', fireflies: 'glow', pollen: 'glow', mist: 'soft',
-});
-
-// Follow-window geometry. Emission fills the full windowRadius disk; the
-// visual fade ends before (radius − recenter·radius), so by the time the
-// window re-centers, every cell that appears or drops is already past the
-// fade — mathematically no pop is possible (see stylizedAmbientFx).
-export const FADE_START_FRACTION = 0.55;
-export const FADE_END_FRACTION = 0.8;
-export const RECENTER_FRACTION = 0.18;
-
-/** CPU mirror of the shader's wind drift heading (for hosts and verify). */
-export function windDriftVector(windDirection) {
-  const x = Number(windDirection?.[0]) || 0;
-  const z = Number(windDirection?.[1]) || 0;
-  const len = Math.hypot(x, z) || 1;
-  return [x / len, z / len];
-}
-
-// --- geometry helpers --------------------------------------------------------
-
-const FLOATS_PER_INSTANCE = { iSpawn: 3, iData: 4, iColor: 3, iAux: 4 };
-
-function createGroupGeometry(capacity) {
-  const quad = new THREE.PlaneGeometry(1, 1);
-  const geometry = new THREE.InstancedBufferGeometry();
-  geometry.index = quad.index;
-  geometry.setAttribute('position', quad.attributes.position);
-  geometry.setAttribute('uv', quad.attributes.uv);
-  for (const [name, itemSize] of Object.entries(FLOATS_PER_INSTANCE)) {
-    geometry.setAttribute(name, new THREE.InstancedBufferAttribute(
-      new Float32Array(Math.max(capacity, 1) * itemSize), itemSize));
-  }
-  geometry.instanceCount = 0;
-  // Instances span the whole follow window wherever it goes.
-  geometry.boundingSphere = new THREE.Sphere(new THREE.Vector3(), 1e5);
-  return geometry;
-}
-
-/**
- * Creates the three blend-group meshes plus their shared uniforms.
- * `settings` is a createAmbientFxSettings() result — only uniform-backed
- * values are read here; emission is the caller's job (see emitters.js).
- *
- * Returned groups expose `setInstances(records)` where each record is
- * `{ x, y, z, seed, phase, size, kind, r, g, b, range, rate, gateJitter,
- * windResponse }` — the emitters produce exactly this shape.
- */
-export function createParticleBackbone(settings) {
-  const shared = settings.shared;
-  const u = {
-    uCamRight: uniform(new THREE.Vector3(1, 0, 0)),
-    uCamUp: uniform(new THREE.Vector3(0, 1, 0)),
-    uCenter: uniform(new THREE.Vector2(0, 0)),
-    uFireflyIntensity: uniform(settings.fireflies.intensity),
-    uFogColor: uniform(new THREE.Color(0.66, 0.8, 0.94)),
-    uFogDensity: uniform(0),
-    uFogFalloff: uniform(400),
-    uFogFloorY: uniform(0),
-    uGateFireflies: uniform(1),
-    uGateLeaves: uniform(1),
-    uGateMist: uniform(1),
-    uGatePetals: uniform(1),
-    uGatePollen: uniform(1),
-    uMistOpacity: uniform(settings.mist.opacity),
-    uPollenBacklit: uniform(settings.pollen.backlitStrength),
-    uSunDirection: uniform(new THREE.Vector3(...shared.sunDirection).normalize()),
-    uTime: uniform(0),
-    uWindDir: uniform(new THREE.Vector2(shared.windDirection[0], shared.windDirection[1])),
-    uWindSpeed: uniform(shared.windSpeed),
-    uWindStrength: uniform(shared.windStrength),
-    uWindowRadius: uniform(shared.windowRadius),
-  };
-
-  // Mirror of the environment shader's world-height fog (same formula as the
-  // forest impostors' _fogUniforms): dense near the world floor, thinning
-  // with altitude, exponential in view distance. Density 0 disables.
-  const heightFogFactor = (worldPos) => {
-    const heightFalloff = exp(
-      max(worldPos.y.sub(u.uFogFloorY), 0.0).div(max(u.uFogFalloff, 0.001)).negate());
-    const depthTerm = exp(distance(worldPos, cameraPosition).mul(u.uFogDensity).negate()).oneMinus();
-    return clamp(depthTerm.mul(heightFalloff), 0.0, 1.0);
-  };
-
-  // Shared per-instance plumbing: window edge fade around the live follow
-  // center + staggered time-gate fade (each particle owns a threshold, so a
-  // gate ramping 0→1 pops particles in one by one instead of all at once).
-  const windowFade = (worldSpawnXZ) => {
-    const dist = length(worldSpawnXZ.sub(u.uCenter));
-    return smoothstep(
-      u.uWindowRadius.mul(FADE_START_FRACTION),
-      u.uWindowRadius.mul(FADE_END_FRACTION),
-      dist,
-    ).oneMinus();
-  };
-  const gateFade = (weight, jitter) =>
-    clamp(weight.mul(1.15).sub(jitter.mul(0.96)).div(0.12), 0.0, 1.0);
-
-  const buildMaterial = (name, build) => {
-    const material = new NodeMaterial();
-    material.name = name;
-    build(material);
-    material.uniforms = u; // GLSL-style named access, matching the grass idiom
-    return material;
-  };
-
-  // ---- cutout group: petals (flutter-fall) + leaves (tumble-fall) ----------
-  const cutoutMaterial = buildMaterial('AmbientFxCutout', (material) => {
-    material.side = THREE.DoubleSide;
-    material.fog = true; // scene.fog linear layer; height fog added below
-
-    const vUv = uv();
-    const vColor = varying(vec3(), 'vFxColor');
-    const vSeed = varying(float(), 'vFxSeed');
-    const vKind = varying(float(), 'vFxKind');
-    const vWorldPos = varying(vec3(), 'vFxWorldPos');
-
-    material.vertexNode = Fn(() => {
-      const iSpawn = attribute('iSpawn', 'vec3');
-      const iData = attribute('iData', 'vec4');
-      const iAux = attribute('iAux', 'vec4');
-      const seed = iData.x;
-      const isLeaf = step(0.5, iData.w).toVar();
-      vSeed.assign(seed);
-      vKind.assign(iData.w);
-      vColor.assign(attribute('iColor', 'vec3'));
-
-      const t = u.uTime;
-      const windDir = normalize(u.uWindDir.add(vec2(1e-4, 0.0))).toVar();
-      const windAmp = u.uWindStrength.mul(iAux.w).toVar();
-
-      // Looping fall: each particle forever re-falls its own span (spawn
-      // height → ground, precomputed by the emitter). The loop ends collapse
-      // the quad so respawns at the top are invisible, never a pop.
-      const fallSpan = max(iAux.x, 0.5);
-      const fallSpeed = mix(0.5, 1.0, fract(seed.mul(19.7))).mul(mix(1.0, 1.4, isLeaf));
-      const progress = fract(iData.y.add(t.mul(fallSpeed).div(fallSpan))).toVar();
-      const drop = progress.mul(fallSpan).toVar();
-
-      // Side-to-side flutter (petals rock, leaves slide) + downwind advection
-      // that accumulates over the fall + a traveling gust kick for leaves.
-      const ph = t.mul(mix(1.4, 2.3, fract(seed.mul(7.7)))).add(seed.mul(41.0)).toVar();
-      const amp = iAux.y.mul(mix(0.32, 0.5, fract(seed.mul(3.3)))).toVar();
-      const perp = vec2(windDir.y.negate(), windDir.x);
-      const sway = perp.mul(sin(ph).mul(amp))
-        .add(windDir.mul(sin(ph.mul(0.77).add(1.3)).mul(amp).mul(0.6)))
-        .toVar();
-      const gust = sin(iSpawn.xz.dot(windDir).mul(0.15).sub(t.mul(u.uWindSpeed).mul(1.5)))
-        .mul(0.5).add(0.5);
-      const advect = windDir.mul(
-        windAmp.mul(drop).mul(1.6).add(gust.mul(windAmp).mul(isLeaf).mul(1.4)),
-      );
-
-      // Orientation: petals rock around a lazy yaw; leaves tumble end over
-      // end — this rotation is what makes tiny quads read as leaves/petals.
-      const yaw = seed.mul(6.2831).add(t.mul(iAux.y).mul(mix(0.6, 1.1, isLeaf)));
-      const pitch = mix(
-        sin(ph.mul(1.13)).mul(0.8).mul(iAux.y).add(1.1),
-        t.mul(iAux.y).mul(2.4).add(seed.mul(6.2831)),
-        isLeaf,
-      );
-      const roll = sin(ph.mul(0.71).add(seed.mul(9.0))).mul(0.6);
-
-      // Fades multiply into the quad SIZE: a degenerate quad rasterizes
-      // nothing, so gated/out-of-window particles cost zero fragments.
-      const worldSpawn = modelWorldMatrix.mul(vec4(iSpawn, 1.0)).xyz.toVar();
-      const endFade = smoothstep(0.0, 0.06, progress)
-        .mul(smoothstep(0.92, 1.0, progress).oneMinus());
-      const gateW = mix(u.uGatePetals, u.uGateLeaves, isLeaf);
-      const scale = iData.z
-        .mul(endFade)
-        .mul(windowFade(worldSpawn.xz))
-        .mul(gateFade(gateW, iAux.z))
-        .toVar();
-
-      // PlaneGeometry corners live in local XY; rotate the scaled quad.
-      const offset = rotate(positionLocal.mul(scale), vec3(pitch, yaw, roll));
-      const position = vec3(
-        iSpawn.x.add(sway.x).add(advect.x),
-        iSpawn.y.sub(drop),
-        iSpawn.z.add(sway.y).add(advect.y),
-      ).add(offset);
-      const worldPosition = modelWorldMatrix.mul(vec4(position, 1.0));
-      vWorldPos.assign(worldPosition.xyz);
-      return cameraProjectionMatrix.mul(cameraViewMatrix).mul(worldPosition);
-    })();
-
-    material.fragmentNode = Fn(() => {
-      const isLeaf = step(0.5, vKind);
-      const p = vUv.mul(2.0).sub(1.0).toVar();
-      // Petal: ellipse with a notch at the outer edge (the classic sakura
-      // dimple). Leaf: narrower pointed ellipse with a midrib.
-      const petalMask = length(p.mul(vec2(1.0, 1.12)))
-        .add(smoothstep(0.35, 0.0, abs(p.x)).mul(max(p.y, 0.0)).mul(0.45));
-      const leafMask = length(p.mul(vec2(1.5, 1.0)));
-      Discard(mix(petalMask, leafMask, isLeaf).greaterThan(1.0));
-
-      const color = vColor.mul(fract(vSeed.mul(5.1)).mul(0.16).add(0.92)).toVar();
-      color.mulAssign(smoothstep(0.12, 0.0, abs(p.x)).mul(isLeaf).mul(0.16).oneMinus());
-      // Backlit translucency toward the sun — same trick as the grass tips.
-      const viewDirection = normalize(cameraPosition.sub(vWorldPos));
-      const backlit = pow(clamp(viewDirection.dot(normalize(u.uSunDirection).negate()), 0.0, 1.0), 3.0);
-      color.addAssign(color.mul(backlit).mul(0.3));
-
-      const fogged = mix(color, u.uFogColor, heightFogFactor(vWorldPos));
-      return vec4(fogged, 1.0);
-    })();
-  });
-
-  // ---- glow group: fireflies (hover-blink) + pollen (curl drift) ----------
-  // Emissive/unlit by design (fireflies ARE light sources) and additive, so
-  // scene fog must not tint them toward the fog color — a fog-colored glow
-  // quad ADDS fog-colored light. Instead both fog layers only DIM the glow.
-  const glowMaterial = buildMaterial('AmbientFxGlow', (material) => {
-    material.transparent = true;
-    material.blending = THREE.AdditiveBlending;
-    material.depthWrite = false;
-    material.fog = false;
-
-    const vUv = uv();
-    const vColor = varying(vec3(), 'vFxColor');
-    const vSeed = varying(float(), 'vFxSeed');
-    const vKind = varying(float(), 'vFxKind');
-    const vRate = varying(float(), 'vFxRate');
-    const vFade = varying(float(), 'vFxFade');
-    const vWorldPos = varying(vec3(), 'vFxWorldPos');
-
-    material.vertexNode = Fn(() => {
-      const iSpawn = attribute('iSpawn', 'vec3');
-      const iData = attribute('iData', 'vec4');
-      const iAux = attribute('iAux', 'vec4');
-      const seed = iData.x;
-      const isPollen = step(2.5, iData.w).toVar();
-      vSeed.assign(seed);
-      vKind.assign(iData.w);
-      vRate.assign(iAux.y);
-      vColor.assign(attribute('iColor', 'vec3'));
-
-      const t = u.uTime;
-      // Layered-sine wander: fireflies patrol a small pocket of air, pollen
-      // swirls in a lazier, larger orbit keyed to its position (reads as a
-      // shared drift field without paying for real curl noise).
-      const a = mix(0.7, 1.3, fract(seed.mul(3.1)));
-      const b = mix(0.7, 1.3, fract(seed.mul(5.7)));
-      const c = mix(0.7, 1.3, fract(seed.mul(9.3)));
-      const speed = mix(0.5, 0.24, isPollen);
-      const wander = vec3(
-        sin(t.mul(speed).mul(a).add(seed.mul(40.0)).add(iSpawn.z.mul(isPollen).mul(0.4))),
-        sin(t.mul(speed).mul(0.8).mul(b).add(seed.mul(71.0))).mul(0.55),
-        cos(t.mul(speed).mul(0.9).mul(c).add(seed.mul(23.0)).add(iSpawn.x.mul(isPollen).mul(0.35))),
-      ).mul(iAux.x).toVar();
-      // Bounded, oscillating downwind slide — never walks off the window.
-      const windDir = normalize(u.uWindDir.add(vec2(1e-4, 0.0)));
-      const slide = sin(t.mul(0.22).add(iData.y.mul(6.2831))).mul(0.5).add(0.5)
-        .mul(u.uWindStrength).mul(iAux.w).mul(6.0);
-      wander.x.addAssign(windDir.x.mul(slide));
-      wander.z.addAssign(windDir.y.mul(slide));
-
-      const anchor = iSpawn.add(wander).toVar();
-      const worldSpawn = modelWorldMatrix.mul(vec4(iSpawn, 1.0)).xyz;
-      const gateW = mix(u.uGateFireflies, u.uGatePollen, isPollen);
-      const fade = windowFade(worldSpawn.xz).mul(gateFade(gateW, iAux.z)).toVar();
-      vFade.assign(fade);
-
-      // Camera-facing billboard from CPU-fed basis vectors (backend-safe).
-      const scale = iData.z.mul(step(0.001, fade)).mul(fade.mul(0.35).add(0.65));
-      const position = anchor
-        .add(u.uCamRight.mul(positionLocal.x).mul(scale))
-        .add(u.uCamUp.mul(positionLocal.y).mul(scale));
-      const worldPosition = modelWorldMatrix.mul(vec4(position, 1.0));
-      vWorldPos.assign(worldPosition.xyz);
-      return cameraProjectionMatrix.mul(cameraViewMatrix).mul(worldPosition);
-    })();
-
-    material.fragmentNode = Fn(() => {
-      const isPollen = step(2.5, vKind);
-      const t = u.uTime;
-      const d = length(vUv.mul(2.0).sub(1.0)).toVar();
-      const halo = pow(clamp(d.oneMinus(), 0.0, 1.0), 1.8).toVar();
-      const core = pow(clamp(d.oneMinus(), 0.0, 1.0), 6.0).toVar();
-
-      // Blink: the product of two incommensurate sines thresholded gives the
-      // irregular firefly pulse; a small floor keeps a faint ember between
-      // blinks so motes never teleport visually.
-      const blinkT = sin(t.mul(vRate).mul(1.1).add(vSeed.mul(251.0))).mul(0.5).add(0.5)
-        .mul(sin(t.mul(vRate).mul(0.37).add(vSeed.mul(97.0))).mul(0.5).add(0.5));
-      const blink = smoothstep(0.22, 0.55, blinkT).mul(0.94).add(0.06);
-
-      // Pollen: steady soft twinkle + strong boost looking toward the sun.
-      const viewDirection = normalize(cameraPosition.sub(vWorldPos));
-      const backlit = pow(clamp(viewDirection.dot(normalize(u.uSunDirection).negate()), 0.0, 1.0), 2.5);
-      const twinkle = sin(t.mul(vRate).add(vSeed.mul(151.0))).mul(0.18).add(0.82);
-      // Base bright enough to sparkle over sunlit grass; backlit doubles it.
-      const pollenBrightness = twinkle.mul(backlit.mul(u.uPollenBacklit).mul(2.2).add(0.85));
-
-      const brightness = mix(blink.mul(u.uFireflyIntensity).mul(2.0), pollenBrightness, isPollen);
-      const rgb = vColor.mul(halo).add(vec3(1.0).mul(core).mul(mix(0.8, 0.25, isPollen)))
-        .mul(brightness)
-        .mul(vFade)
-        .mul(heightFogFactor(vWorldPos).oneMinus());
-      return vec4(rgb, halo);
-    })();
-  });
-
-  // ---- soft group: mist wisps (horizontal scroll) ---------------------------
-  const softMaterial = buildMaterial('AmbientFxSoft', (material) => {
-    material.transparent = true;
-    material.depthWrite = false;
-    material.fog = true;
-
-    const vUv = uv();
-    const vColor = varying(vec3(), 'vFxColor');
-    const vSeed = varying(float(), 'vFxSeed');
-    const vFade = varying(float(), 'vFxFade');
-    const vWorldPos = varying(vec3(), 'vFxWorldPos');
-
-    material.vertexNode = Fn(() => {
-      const iSpawn = attribute('iSpawn', 'vec3');
-      const iData = attribute('iData', 'vec4');
-      const iAux = attribute('iAux', 'vec4');
-      const seed = iData.x;
-      vSeed.assign(seed);
-      vColor.assign(attribute('iColor', 'vec3'));
-
-      const t = u.uTime;
-      const windDir = normalize(u.uWindDir.add(vec2(1e-4, 0.0)));
-      // Scroll a wisp downwind across its span, wrap, fade at both ends.
-      const s = fract(iData.y.add(t.mul(u.uWindSpeed).mul(iAux.w).mul(0.02))).toVar();
-      const travel = s.sub(0.5).mul(iAux.x);
-      const bob = sin(t.mul(iAux.y).add(seed.mul(37.0))).mul(0.22);
-      const anchor = vec3(
-        iSpawn.x.add(windDir.x.mul(travel)),
-        iSpawn.y.add(bob),
-        iSpawn.z.add(windDir.y.mul(travel)),
-      ).toVar();
-
-      const worldSpawn = modelWorldMatrix.mul(vec4(iSpawn, 1.0)).xyz;
-      const endFade = smoothstep(0.0, 0.18, s).mul(smoothstep(0.82, 1.0, s).oneMinus());
-      const fade = windowFade(worldSpawn.xz)
-        .mul(gateFade(u.uGateMist, iAux.z))
-        .mul(endFade)
-        .toVar();
-      vFade.assign(fade);
-
-      // Y-axis billboard: wisps stay upright and face the camera in plan
-      // only, so they read as layers of ground haze from any walk-height view.
-      const toCam = cameraPosition.sub(anchor);
-      const right = normalize(vec3(toCam.z, 0.0, toCam.x.negate()).add(vec3(1e-4, 0.0, 0.0)));
-      const width = iData.z.mul(fract(seed.mul(2.7)).mul(2.6).add(4.0));
-      const grow = step(0.001, fade);
-      const position = anchor
-        .add(right.mul(positionLocal.x).mul(width).mul(grow))
-        .add(vec3(0.0, 1.0, 0.0).mul(positionLocal.y.add(0.35)).mul(iData.z).mul(grow));
-      const worldPosition = modelWorldMatrix.mul(vec4(position, 1.0));
-      vWorldPos.assign(worldPosition.xyz);
-      return cameraProjectionMatrix.mul(cameraViewMatrix).mul(worldPosition);
-    })();
-
-    material.fragmentNode = Fn(() => {
-      const t = u.uTime;
-      const p = vUv.mul(2.0).sub(1.0);
-      const body = pow(clamp(length(p.mul(vec2(1.0, 1.2))).oneMinus(), 0.0, 1.0), 1.5);
-      // Two drifting ripples across the quad break the "airbrushed ellipse"
-      // read into something wispy without a noise texture.
-      const ripple = sin(vUv.x.mul(9.0).add(t.mul(0.4)).add(vSeed.mul(63.0))).mul(0.5).add(0.5)
-        .mul(sin(vUv.x.mul(4.0).sub(t.mul(0.23)).add(vSeed.mul(29.0))).mul(0.5).add(0.5));
-      const alpha = body
-        .mul(ripple.mul(0.5).add(0.62))
-        .mul(u.uMistOpacity)
-        .mul(fract(vSeed.mul(9.3)).mul(0.3).add(0.7))
-        .mul(vFade);
-
-      const lit = mix(vColor.mul(0.94), vColor.mul(1.08), vUv.y);
-      const fogged = mix(lit, u.uFogColor, heightFogFactor(vWorldPos));
-      return vec4(fogged, alpha);
-    })();
-  });
-
-  const buildGroup = (id, material, capacity, renderOrder) => {
-    const mesh = new THREE.Mesh(createGroupGeometry(capacity), material);
-    mesh.name = `AmbientFx${id[0].toUpperCase()}${id.slice(1)}`;
-    mesh.frustumCulled = false;
-    mesh.renderOrder = renderOrder;
-    const group = {
-      capacity: Math.max(capacity, 1),
-      count: 0,
-      id,
-      mesh,
-      setInstances(records) {
-        if (records.length > group.capacity) {
-          group.capacity = Math.ceil(records.length * 1.3);
-          for (const [name, itemSize] of Object.entries(FLOATS_PER_INSTANCE)) {
-            mesh.geometry.setAttribute(name, new THREE.InstancedBufferAttribute(
-              new Float32Array(group.capacity * itemSize), itemSize));
-          }
-        }
-        const spawn = mesh.geometry.attributes.iSpawn;
-        const data = mesh.geometry.attributes.iData;
-        const color = mesh.geometry.attributes.iColor;
-        const aux = mesh.geometry.attributes.iAux;
-        records.forEach((r, i) => {
-          spawn.array[i * 3] = r.x; spawn.array[i * 3 + 1] = r.y; spawn.array[i * 3 + 2] = r.z;
-          data.array[i * 4] = r.seed; data.array[i * 4 + 1] = r.phase;
-          data.array[i * 4 + 2] = r.size; data.array[i * 4 + 3] = r.kind;
-          color.array[i * 3] = r.r; color.array[i * 3 + 1] = r.g; color.array[i * 3 + 2] = r.b;
-          aux.array[i * 4] = r.range; aux.array[i * 4 + 1] = r.rate;
-          aux.array[i * 4 + 2] = r.gateJitter; aux.array[i * 4 + 3] = r.windResponse;
-        });
-        spawn.needsUpdate = data.needsUpdate = color.needsUpdate = aux.needsUpdate = true;
-        mesh.geometry.instanceCount = records.length;
-        group.count = records.length;
-      },
-      dispose() {
-        mesh.geometry.dispose();
-        material.dispose();
-      },
-    };
-    return group;
-  };
-
-  return {
-    groups: {
-      cutout: buildGroup('cutout', cutoutMaterial, 2048, 1),
-      // Mist under the glows so fireflies shine THROUGH the haze layer.
-      soft: buildGroup('soft', softMaterial, 64, 2),
-      glow: buildGroup('glow', glowMaterial, 1024, 3),
-    },
-    uniforms: u,
-  };
-}