@call-me-sensei/toonlab 0.3.1 → 0.4.20

package/src/vfxgen/INTEGRATION.md

@@ -1,145 +0,0 @@
-# Gameplay VFX (vfxgen) — integration notes
-
-The `src/vfxgen/` cluster is self-contained and ALREADY wired into the shared
-files (unlike the ambientfx handoff doc, nothing here is pending):
-
-- `src/index.js` — root re-export (`export * from './vfxgen/index.js'`)
-- `package.json` — `"./vfxgen"` subpath export + `verify:vfxgen` script
-  (also folded into `verify:all`)
-- `vite.config.js` — `'vfxgen'` package alias + `vfxArena` build input
-- `scripts/generate-settings-reference.mjs` — Gameplay VFX module entry
-- `labs/shared/sceneHub.js` — `vfxLab` + `vfxArena` hub entries
-- Demo/reference app: `examples/vfx-arena/` (headless gates on
-  `document.body.dataset`: `vfxArenaReady`, `vfxLiveGlow`, `vfxLivePuff`,
-  `vfxDrawCalls`, `vfxSpawns`)
-- **Designer: VFX Lab at `/vfx-lab/`** (`labs/vfx-lab/`) — the interactive
-  authoring surface: category rail (weapon / magic / movement / shared),
-  schema-driven panels generated from `VFX_SETTING_FIELD_SCHEMA`, preset
-  picker, gameplay trigger bar (hotkeys 1–5, click-to-aim fireballs, `L`
-  loop, `R` reseed), and Export → recipe JSON / paste-ready
-  `createVfxSystem` code. Share links carry the recipe in `?vfxRecipe=`.
-  Headless gates: `vfxLabReady`, `uiReady`, plus the arena stats above.
-
-## Layout (categorized)
-
-```
-src/vfxgen/
-  vfxSettings.js        DEFAULT_VFX_SETTINGS + groups + field schema
-  vfxPresets.js         'default' + 'call_me_sensei' + registerVfxPreset()
-  vfxSystem.js          createVfxSystem — event-driven runtime, pools, clock
-  core/                 rendering machinery (no gameplay knowledge)
-    burstBackbone.js    ring-buffer one-shot GPU particles, 2 draw calls
-                        (kinds: spark, ember, flash, ground ring, puff,
-                        camera-facing shockwave)
-    trailRibbon.js      swept-arc ribbon (slash trails, limb smears) —
-                        reference-style SOLID two-band surface (body +
-                        white leading edge), tail ERODES (hard dissolving
-                        cutoff, inner edge first) instead of alpha-fading,
-                        Catmull-Rom smoothed centerline (SUBDIV spline
-                        points per raw frame sample), charged-edge flash
-                        on the newest segments
-    projectileCore.js   pooled flame-core billboard
-    spriteShapes.js     TSL SDF sprite masks (zero textures)
-    vfxRandom.js        seeded PRNG trio (internal, not re-exported)
-  effects/              PURE builders: (settings, rng, options) → records
-    weaponEffects.js    emitImpact, emitSlashSparkle
-    magicEffects.js     emitFireballEmbers, emitFireballExplosion
-    movementEffects.js  emitFootstep, emitLanding
-  weapons/
-    stylizedWeapons.js  procedural weapons (sword, greatsword, spear,
-                        dagger, hammer): mesh + trail anchors + weight profile
-  moves/
-    moveLibrary.js      PURE authored move data — phases + pose keys + VFX
-                        event tracks (slash, overhead, thrust, spin, plunge)
-    moveController.js   plays a move on a weapon, fires its events into vfx
-```
-
-## Weapons + moves (the batteries-included motion layer)
-
-The VFX rides real motion: a move is authored phase data (`windup → strike
-→ recover`; the plunge is the full Dragoon decomposition `crouch → leap →
-apex → dive → landfall → recover`), each phase carrying its VFX beats
-(trail on/off, impact, landing, dust). Weapon `weight` scales timing and
-hit power — the same `overhead` reads as a dagger flick or a hammer commit.
-
-```js
-import {
-  createMoveController, createStylizedWeapon, createVfxSystem,
-} from '@call-me-sensei/toonlab/vfxgen';
-
-const weapon = createStylizedWeapon({ type: 'greatsword' });
-characterHand.add(weapon.root);            // or an actor anchor group
-const attack = createMoveController({ weapon, vfx, groundY: 0 });
-attack.play('overhead');                    // on the attack input
-attack.update(delta);                       // per frame, before vfx.update
-```
-
-Own animations stay first-class: skip the controller and drive
-`vfx.spawn('slash', { follow: bone, base, tip })` from your clips — the
-move library is default motion, not a requirement. External weapon meshes
-slot in by providing the same `{ root, anchors, profile }` shape.
-
-Categories: **weapon** (`slash`, `impact`) · **magic** (`fireball`) ·
-**movement** (`footstep`, `landing`). `VFX_CATEGORIES` in vfxSettings.js is
-the canonical map; new effects should join a category (or add one) and keep
-their emission logic as a pure builder in `effects/`.
-
-## Host usage (standalone — works in any Three.js scene)
-
-```js
-import { createVfxSystem } from '@call-me-sensei/toonlab/vfxgen';
-
-const vfx = createVfxSystem({
-  seed: 42,
-  preset: 'call_me_sensei',
-  heightAt: world?.collision?.groundHeight ?? terrain?.heightAt, // fireball ground hits
-});
-scene.add(vfx.root);
-
-// per frame, before render:
-vfx.update(delta, camera);
-
-// gameplay events:
-const trail = vfx.spawn('slash', { follow: weaponBone, base: [0, 0.5, 0], tip: [0, 1.3, 0] });
-trail.stop();                                             // when the swing anim ends
-vfx.spawn('impact', { at, normal, power: 1 });
-const bolt = vfx.spawn('fireball', { from, velocity, onHit });
-vfx.spawn('footstep', { at, dir: velocityXZ });
-vfx.spawn('landing', { at, power: fallSpeed / 6 });
-
-// world look integration:
-vfx.setDistanceFog({ color, density, falloff, floorY }); // same params as forest/water
-vfx.setTimeScale(0);                                      // hit-stop
-```
-
-Budgets: all one-shot bursts render in **two draw calls** (glow + puff ring
-buffers, `shared.maxParticles` instances total); each live slash ribbon and
-fireball core adds one small draw, bounded by `shared.maxTrails` /
-`shared.maxProjectiles`. Everything is `userData.waterExclude` — transient
-flashes are not worth re-rendering the water passes.
-
-## Deferred follow-ups (deliberate)
-
-- **`createStylizedWorld({ vfx })` wiring** — mirror the ambientfx option:
-  construct the system with the world's `heightAt` + follow target, call
-  `vfx.setDistanceFog` from the world's height-fog params, tick it inside
-  `world.update`. Waiting until a real consumer (mini-game / runtime spine)
-  exists so the option surface is shaped by actual use.
-- **Limb smears** — `createTrailRibbon` already supports any Object3D +
-  anchor pair; a character-side helper that arms ribbons from bone names
-  belongs in `src/character/` when procedural animation lands.
-- **Catalog entries** — effects are runtime events, not spawnable assets;
-  if the catalog ever grows an "effects" shelf, register preset spawns, not
-  meshes.
-
-## Verification
-
-- `npm run verify:vfxgen` — node-only: determinism (same seed + same spawn
-  script → bit-identical buffers), ring-buffer budgets, lifecycle (expiry,
-  ribbon pooling, ground detonation + onHit), look overrides, hit-stop, and
-  the pure builders' geometry contracts.
-- Visual: drive `examples/vfx-arena/?hud=0` headlessly (Playwright,
-  `--enable-unsafe-webgpu --enable-gpu`), wait for
-  `dataset.vfxArenaReady === 'true'`, screenshot several beats, and LOOK at
-  them (slash = crescent arc, impact = star + spark streaks, fireball =
-  two-band flame + ember trail, detonation = ring + smoke column).

package/src/vfxgen/core/burstBackbone.js

@@ -1,380 +0,0 @@
-// The ONE shared GPU system behind every one-shot burst in the VFX cluster
-// (sparks, embers, hit flashes, ground rings, dust puffs). Same architecture
-// as the ambientfx particle backbone: an InstancedBufferGeometry over a unit
-// quad and ALL motion computed in the TSL vertex shader as a pure function of
-// (uTime − birth) — after the spawn-time attribute write, a burst costs zero
-// CPU per frame, on WebGPU and the WebGL2 fallback alike.
-//
-// Where ambientfx re-emits a follow window, this is a RING BUFFER: spawns
-// write records at a cursor and expired instances collapse to degenerate
-// quads in the vertex shader (zero fragments) until overwritten. Draw calls:
-// every effect shares TWO meshes, grouped by blend state —
-//   glow — sparks + embers + flashes + rings  (additive, no depth write)
-//   puff — dust/smoke puffs                   (alpha blend, no depth write)
-// Within a group the per-instance `kind` attribute selects the motion
-// program (ballistic / buoyant-wander / flash-pop / ground-ring / puff), so
-// adding an effect never adds a draw.
-
-import * as THREE from 'three';
-import { NodeMaterial } from 'three/webgpu';
-import {
-  attribute, cameraPosition, cameraProjectionMatrix, cameraViewMatrix, clamp, cos, Discard,
-  distance, exp, float, Fn, max, mix, normalize, positionLocal, pow, sin, smoothstep, step,
-  uniform, uv, varying, vec2, vec3, vec4,
-} from 'three/tsl';
-
-import { emberDot, puffBlob, ringBand, softDot, starburst } from './spriteShapes.js';
-
-/** Backbone kind ids — the per-instance `iData.w` attribute. `ring` lies
- * flat on the ground (scorch); `shockwave` is the same expanding band but
- * camera-facing (the action-RPG hit circle). */
-export const BURST_KIND = Object.freeze({
-  spark: 0, ember: 1, flash: 2, ring: 3, puff: 4, shockwave: 5,
-});
-
-/** Which blend-group mesh each kind renders in. */
-export const GROUP_FOR_BURST_KIND = Object.freeze({
-  spark: 'glow', ember: 'glow', flash: 'glow', ring: 'glow', puff: 'puff', shockwave: 'glow',
-});
-
-// --- geometry ----------------------------------------------------------------
-
-const FLOATS_PER_INSTANCE = { iSpawn: 3, iVel: 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;
-  // Bursts happen anywhere in the world; never let culling clip a hit flash.
-  geometry.boundingSphere = new THREE.Sphere(new THREE.Vector3(), 1e5);
-  return geometry;
-}
-
-/**
- * Creates the two blend-group meshes plus their shared uniforms.
- *
- * Each group exposes `emit(records)` where a record is
- * `{ x, y, z, vx, vy, vz, seed, birth, lifetime, kind, r, g, b,
- *    size0, size1, gravity, extra }` — the effects/ builders produce exactly
- * this shape. `extra` is kind-specific: spark → streak stretch, ember →
- * wander radius, flash → star spikes, ring → band thickness, puff → spin.
- */
-export function createBurstBackbone(settings) {
-  const capacity = Math.max(settings?.shared?.maxParticles ?? 4096, 64);
-  // Glow kinds outnumber puffs in practice (sparks + embers per burst vs a
-  // handful of dust quads); split the budget accordingly.
-  const glowCapacity = Math.ceil(capacity * 0.75);
-  const puffCapacity = Math.max(capacity - glowCapacity, 32);
-
-  const u = {
-    uCamRight: uniform(new THREE.Vector3(1, 0, 0)),
-    uCamUp: uniform(new THREE.Vector3(0, 1, 0)),
-    uFogColor: uniform(new THREE.Color(0.66, 0.8, 0.94)),
-    uFogDensity: uniform(0),
-    uFogFalloff: uniform(400),
-    uFogFloorY: uniform(0),
-    uTime: uniform(0),
-  };
-
-  // Mirror of the environment shader's world-height fog (same formula as the
-  // ambientfx backbone) so bursts haze out with the terrain. Density 0 = off.
-  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 lifecycle: progress 0..1 over the lifetime, and an
-  // alive gate that multiplies into quad SIZE — a degenerate quad rasterizes
-  // nothing, so expired ring-buffer slots cost zero fragments.
-  const lifecycle = () => {
-    const iData = attribute('iData', 'vec4');
-    const age = u.uTime.sub(iData.y).toVar();
-    const lifetime = max(iData.z, 1e-3);
-    const progress = clamp(age.div(lifetime), 0.0, 1.0).toVar();
-    // −5 ms tolerance: float32 rounding of birth vs the clock must never
-    // hide a burst on its own spawn frame (hit flashes land THIS frame).
-    const alive = step(-0.005, age)
-      .mul(step(age.div(lifetime), 0.9995).toVar())
-      .mul(step(1e-3, iData.z));
-    return { age, alive, progress, seed: iData.x, kind: iData.w };
-  };
-
-  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;
-  };
-
-  // ---- glow group: spark (ballistic) + ember (buoyant wander) + flash
-  // (scale pop) + ring (ground expand) — additive, emissive by design -------
-  const glowMaterial = buildMaterial('VfxBurstGlow', (material) => {
-    material.transparent = true;
-    material.blending = THREE.AdditiveBlending;
-    material.depthWrite = false;
-    material.fog = false; // both fog layers only DIM the glow (see ambientfx)
-
-    const vUv = uv();
-    const vColor = varying(vec3(), 'vVfxColor');
-    const vSeed = varying(float(), 'vVfxSeed');
-    const vKind = varying(float(), 'vVfxKind');
-    const vProgress = varying(float(), 'vVfxProgress');
-    const vExtra = varying(float(), 'vVfxExtra');
-    const vWorldPos = varying(vec3(), 'vVfxWorldPos');
-
-    material.vertexNode = Fn(() => {
-      const iSpawn = attribute('iSpawn', 'vec3');
-      const iVel = attribute('iVel', 'vec3');
-      const iAux = attribute('iAux', 'vec4');
-      const { age, alive, progress, seed, kind } = lifecycle();
-      vSeed.assign(seed);
-      vKind.assign(kind);
-      vProgress.assign(progress);
-      vExtra.assign(iAux.w);
-      vColor.assign(attribute('iColor', 'vec3'));
-
-      const isEmber = step(0.5, kind).mul(step(kind, 1.5));
-      const isFlash = step(1.5, kind).mul(step(kind, 2.5));
-      const isRing = step(2.5, kind).mul(step(kind, 3.5)); // ground scorch only
-      const isShock = step(4.5, kind); // camera-facing hit circle
-      const isRingLike = max(isRing, isShock);
-      const isBallistic = step(kind, 1.5); // spark or ember
-
-      // Ballistic center: p = p0 + v·t − ½g·t²ŷ. Ember "gravity" is negative
-      // (buoyant), so the same program rises; its wander adds a curl-ish
-      // drift that grows over life (extra = wander radius).
-      const wander = vec3(
-        sin(age.mul(3.1).add(seed.mul(41.0))),
-        0.0,
-        cos(age.mul(2.6).add(seed.mul(23.0))),
-      ).mul(iAux.w).mul(progress).mul(isEmber);
-      const center = iSpawn
-        .add(iVel.mul(age).mul(isBallistic))
-        .sub(vec3(0.0, 1.0, 0.0).mul(iAux.z).mul(age).mul(age).mul(0.5).mul(isBallistic))
-        .add(wander)
-        .toVar();
-
-      // Size envelope per kind. Flash pops out fast and dies before the end
-      // of its lifetime; the ring eases outward (shockwave decelerating).
-      const easeOut = progress.oneMinus().pow(3.0).oneMinus();
-      const sizeBallistic = mix(iAux.x, iAux.y, progress);
-      const sizeFlash = iAux.x
-        .mul(smoothstep(0.0, 0.22, progress).mul(0.65).add(0.35))
-        .mul(smoothstep(1.0, 0.55, progress));
-      const sizeRing = mix(iAux.x, iAux.y, easeOut);
-      const scale = mix(mix(sizeBallistic, sizeFlash, isFlash), sizeRing, isRingLike)
-        .mul(alive)
-        .toVar();
-
-      // Sparks stretch into streaks along their CURRENT velocity projected
-      // into the camera plane — rotation built from the normalized 2D vector,
-      // no atan needed. Everything else keeps the plain billboard basis.
-      const velNow = iVel.sub(vec3(0.0, iAux.z.mul(age), 0.0));
-      const projected = vec2(velNow.dot(u.uCamRight), velNow.dot(u.uCamUp)).add(vec2(1e-4, 0.0));
-      const isSpark = step(kind, 0.5);
-      const dir = mix(vec2(1.0, 0.0), normalize(projected), isSpark).toVar();
-      const stretch = mix(1.0, max(iAux.w, 1.0), isSpark);
-      const local = vec2(positionLocal.x.mul(stretch), positionLocal.y).toVar();
-      const rotated = vec2(
-        local.x.mul(dir.x).sub(local.y.mul(dir.y)),
-        local.x.mul(dir.y).add(local.y.mul(dir.x)),
-      );
-      const billboardOffset = u.uCamRight.mul(rotated.x).add(u.uCamUp.mul(rotated.y));
-      // Scorch rings lie flat on the ground (quad local XY → world XZ);
-      // shockwaves keep the camera-facing billboard basis.
-      const flatOffset = vec3(positionLocal.x, 0.0, positionLocal.y.negate());
-      const offset = mix(billboardOffset, flatOffset, isRing).mul(scale);
-
-      const worldPosition = vec4(center.add(offset), 1.0);
-      vWorldPos.assign(worldPosition.xyz);
-      return cameraProjectionMatrix.mul(cameraViewMatrix).mul(worldPosition);
-    })();
-
-    material.fragmentNode = Fn(() => {
-      const p = vUv.mul(2.0).sub(1.0).toVar();
-      const isEmber = step(0.5, vKind).mul(step(vKind, 1.5));
-      const isFlash = step(1.5, vKind).mul(step(vKind, 2.5));
-      const isRing = step(2.5, vKind);
-      const isSpark = step(vKind, 0.5);
-
-      // Ring band thins as it expands (vExtra = starting thickness).
-      const thickness = max(vExtra.mul(vProgress.mul(0.6).oneMinus()), 0.02);
-      const mask = softDot(p, 2.2).mul(isSpark)
-        .add(emberDot(p).mul(isEmber))
-        .add(starburst(p, vExtra, 3.0).mul(isFlash))
-        .add(ringBand(p, 0.72, thickness).mul(isRing))
-        .toVar();
-
-      // Brightness envelopes: sparks/embers cool, the flash dies fast, the
-      // ring fades as it runs out of energy.
-      const fade = vProgress.oneMinus();
-      const brightness = pow(fade, 1.5).mul(isSpark)
-        .add(fade.mul(isEmber))
-        .add(smoothstep(1.0, 0.45, vProgress).mul(isFlash))
-        .add(pow(fade, 1.2).mul(isRing));
-
-      const rgb = vColor.mul(mask).mul(brightness)
-        .mul(heightFogFactor(vWorldPos).oneMinus());
-      return vec4(rgb, mask.mul(brightness));
-    })();
-  });
-
-  // ---- puff group: chunky toon dust/smoke — alpha blend, matter not light --
-  const puffMaterial = buildMaterial('VfxBurstPuff', (material) => {
-    material.transparent = true;
-    material.depthWrite = false;
-    material.fog = true;
-
-    const vUv = uv();
-    const vColor = varying(vec3(), 'vVfxColor');
-    const vSeed = varying(float(), 'vVfxSeed');
-    const vProgress = varying(float(), 'vVfxProgress');
-    const vSpin = varying(float(), 'vVfxSpin');
-    const vAge = varying(float(), 'vVfxAge');
-    const vWorldPos = varying(vec3(), 'vVfxWorldPos');
-
-    material.vertexNode = Fn(() => {
-      const iSpawn = attribute('iSpawn', 'vec3');
-      const iVel = attribute('iVel', 'vec3');
-      const iAux = attribute('iAux', 'vec4');
-      const { age, alive, progress, seed } = lifecycle();
-      vSeed.assign(seed);
-      vProgress.assign(progress);
-      vSpin.assign(iAux.w);
-      vAge.assign(age);
-      vColor.assign(attribute('iColor', 'vec3'));
-
-      // Decelerating launch (dust loses momentum fast) + gravity term the
-      // emitters use as gentle rise (negative) or settle (positive).
-      const decel = progress.mul(0.55).oneMinus();
-      const center = iSpawn
-        .add(iVel.mul(age).mul(decel))
-        .sub(vec3(0.0, 1.0, 0.0).mul(iAux.z).mul(age).mul(age).mul(0.5))
-        .toVar();
-
-      // Puffs GROW as they fade — the classic smoke read.
-      const easeOut = progress.oneMinus().pow(2.0).oneMinus();
-      const scale = mix(iAux.x, iAux.y, easeOut).mul(alive);
-      const position = center
-        .add(u.uCamRight.mul(positionLocal.x).mul(scale))
-        .add(u.uCamUp.mul(positionLocal.y).mul(scale));
-      const worldPosition = vec4(position, 1.0);
-      vWorldPos.assign(worldPosition.xyz);
-      return cameraProjectionMatrix.mul(cameraViewMatrix).mul(worldPosition);
-    })();
-
-    material.fragmentNode = Fn(() => {
-      // Slow tumble sells hand-drawn smoke; rotate the sample space, not the
-      // quad, so the billboard basis stays camera-true.
-      const spinAngle = vAge.mul(vSpin).add(vSeed.mul(6.2831));
-      const c = cos(spinAngle);
-      const s = sin(spinAngle);
-      const p0 = vUv.mul(2.0).sub(1.0).toVar();
-      const p = vec2(p0.x.mul(c).sub(p0.y.mul(s)), p0.x.mul(s).add(p0.y.mul(c))).toVar();
-
-      const blob = puffBlob(p, vSeed, 0.2);
-      Discard(blob.lessThan(0.0));
-      const coverage = smoothstep(0.0, 0.14, blob);
-
-      // Two-tone toon shading (lit top, shaded belly) + a stepped-ish fade so
-      // the dissolve reads as cel steps rather than an airbrush.
-      const shade = mix(0.8, 1.12, smoothstep(-0.7, 0.7, p0.y));
-      const fade = vProgress.oneMinus();
-      const alpha = coverage
-        .mul(smoothstep(0.0, 0.12, fade))
-        .mul(pow(fade, 0.75))
-        .mul(0.88);
-
-      const lit = vColor.mul(shade);
-      const fogged = mix(lit, u.uFogColor, heightFogFactor(vWorldPos));
-      return vec4(fogged, alpha);
-    })();
-  });
-
-  const buildGroup = (id, material, groupCapacity, renderOrder) => {
-    const mesh = new THREE.Mesh(createGroupGeometry(groupCapacity), material);
-    mesh.name = `VfxBurst${id[0].toUpperCase()}${id.slice(1)}`;
-    mesh.frustumCulled = false;
-    mesh.renderOrder = renderOrder;
-    // CPU mirror of each slot's lifecycle so stats/verify can count live
-    // instances without reading GPU state. Float64 on purpose: float32
-    // rounding can push a birth a hair past the clock and make a just-spawned
-    // instance read as unborn.
-    const birth = new Float64Array(groupCapacity);
-    const lifetime = new Float64Array(groupCapacity);
-    const group = {
-      capacity: groupCapacity,
-      cursor: 0,
-      highWater: 0,
-      id,
-      mesh,
-      /** Writes records at the ring cursor; oldest slots recycle first. */
-      emit(records) {
-        const spawn = mesh.geometry.attributes.iSpawn;
-        const vel = mesh.geometry.attributes.iVel;
-        const data = mesh.geometry.attributes.iData;
-        const color = mesh.geometry.attributes.iColor;
-        const aux = mesh.geometry.attributes.iAux;
-        for (const r of records) {
-          const i = group.cursor;
-          spawn.array[i * 3] = r.x; spawn.array[i * 3 + 1] = r.y; spawn.array[i * 3 + 2] = r.z;
-          vel.array[i * 3] = r.vx ?? 0; vel.array[i * 3 + 1] = r.vy ?? 0; vel.array[i * 3 + 2] = r.vz ?? 0;
-          data.array[i * 4] = r.seed; data.array[i * 4 + 1] = r.birth;
-          data.array[i * 4 + 2] = r.lifetime; 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.size0; aux.array[i * 4 + 1] = r.size1;
-          aux.array[i * 4 + 2] = r.gravity ?? 0; aux.array[i * 4 + 3] = r.extra ?? 0;
-          birth[i] = r.birth;
-          lifetime[i] = r.lifetime;
-          group.cursor = (i + 1) % group.capacity;
-          group.highWater = Math.min(Math.max(group.highWater, i + 1), group.capacity);
-        }
-        if (records.length > 0) {
-          spawn.needsUpdate = vel.needsUpdate = data.needsUpdate = true;
-          color.needsUpdate = aux.needsUpdate = true;
-          mesh.geometry.instanceCount = group.highWater;
-        }
-      },
-      /** Instances still inside their lifetime at clock `now`. */
-      liveCount(now) {
-        let live = 0;
-        for (let i = 0; i < group.highWater; i += 1) {
-          if (lifetime[i] > 0 && now - birth[i] >= 0 && now - birth[i] < lifetime[i]) live += 1;
-        }
-        return live;
-      },
-      clear() {
-        lifetime.fill(0);
-        mesh.geometry.attributes.iData.array.fill(0);
-        mesh.geometry.attributes.iData.needsUpdate = true;
-        group.cursor = 0;
-        group.highWater = 0;
-        mesh.geometry.instanceCount = 0;
-      },
-      dispose() {
-        mesh.geometry.dispose();
-        material.dispose();
-      },
-    };
-    return group;
-  };
-
-  return {
-    groups: {
-      // Dust under the glows so sparks and flashes shine THROUGH the smoke.
-      puff: buildGroup('puff', puffMaterial, puffCapacity, 4),
-      glow: buildGroup('glow', glowMaterial, glowCapacity, 5),
-    },
-    uniforms: u,
-  };
-}

package/src/vfxgen/core/projectileCore.js

@@ -1,92 +0,0 @@
-// The fireball's flame-core billboard: one pooled quad per projectile in
-// flight, shaded by an analytic two-band toon flame (no texture, no noise
-// fetch — angular sine licks over an SDF body, same policy as spriteShapes).
-// vfxSystem moves the center uniform each frame; everything else is a pure
-// function of the shared clock.
-
-import * as THREE from 'three';
-import { NodeMaterial } from 'three/webgpu';
-import {
-  cameraProjectionMatrix, cameraViewMatrix, clamp, Discard, Fn, length, mix, positionLocal,
-  sin, smoothstep, step, uniform, uv, vec2, vec4,
-} from 'three/tsl';
-
-import { flameLicks } from './spriteShapes.js';
-
-/**
- * One pooled projectile core. `sharedUniforms` is the burst backbone's set
- * (uTime + camera billboard basis) so the flame animates on the same clock.
- */
-export function createProjectileCore({ sharedUniforms }) {
-  const u = sharedUniforms;
-  const look = {
-    uCenter: uniform(new THREE.Vector3()),
-    uCoreColor: uniform(new THREE.Color(1.0, 0.95, 0.6)),
-    uFlameColor: uniform(new THREE.Color(1.0, 0.45, 0.12)),
-    uIntensity: uniform(1.2),
-    uSeed: uniform(0),
-    uSize: uniform(0.42),
-  };
-
-  const material = new NodeMaterial();
-  material.name = 'VfxProjectileCore';
-  material.transparent = true;
-  material.blending = THREE.AdditiveBlending;
-  material.depthWrite = false;
-  material.fog = false;
-
-  material.vertexNode = Fn(() => {
-    // Camera-facing billboard around the CPU-fed center; quad is 1×1 so the
-    // world size is uSize · 2 across.
-    const position = look.uCenter
-      .add(u.uCamRight.mul(positionLocal.x).mul(look.uSize).mul(2.0))
-      .add(u.uCamUp.mul(positionLocal.y).mul(look.uSize).mul(2.0));
-    return cameraProjectionMatrix.mul(cameraViewMatrix).mul(vec4(position, 1.0));
-  })();
-
-  material.fragmentNode = Fn(() => {
-    const p = uv().mul(2.0).sub(1.0).toVar();
-    const t = u.uTime.add(look.uSeed.mul(37.0));
-    const body = flameLicks(p, t, look.uSeed).toVar();
-    Discard(body.lessThan(0.01));
-
-    // Two hard toon bands: hot core inside, flame skin outside, plus a
-    // flicker so the ball feels alive even in a straight throw.
-    const hot = smoothstep(0.7, 0.15, length(p.mul(vec2(1.0, 0.9))));
-    const banded = mix(look.uFlameColor, look.uCoreColor, step(0.55, hot));
-    const flicker = sin(t.mul(11.0)).mul(0.06).add(0.97);
-    const alpha = clamp(body, 0.0, 1.0).mul(look.uIntensity).mul(flicker);
-    return vec4(banded.mul(alpha), alpha);
-  })();
-  material.uniforms = look;
-
-  const mesh = new THREE.Mesh(new THREE.PlaneGeometry(1, 1), material);
-  mesh.name = 'VfxProjectileCore';
-  mesh.frustumCulled = false;
-  mesh.renderOrder = 7;
-  mesh.visible = false;
-
-  return {
-    mesh,
-    uniforms: look,
-    /** Re-tints and shows the core for a new projectile. */
-    arm({ coreColor, flameColor, coreSize, intensity, seed } = {}) {
-      if (Array.isArray(coreColor)) look.uCoreColor.value.setRGB(...coreColor, THREE.SRGBColorSpace);
-      if (Array.isArray(flameColor)) look.uFlameColor.value.setRGB(...flameColor, THREE.SRGBColorSpace);
-      if (Number.isFinite(coreSize)) look.uSize.value = Math.max(coreSize, 0.01);
-      if (Number.isFinite(intensity)) look.uIntensity.value = Math.max(intensity, 0);
-      if (Number.isFinite(seed)) look.uSeed.value = seed;
-      mesh.visible = true;
-    },
-    setCenter(position) {
-      look.uCenter.value.copy(position);
-    },
-    reset() {
-      mesh.visible = false;
-    },
-    dispose() {
-      mesh.geometry.dispose();
-      material.dispose();
-    },
-  };
-}