@call-me-sensei/toonlab 0.2.0 → 0.3.1

package/src/vfxgen/core/spriteShapes.js

@@ -0,0 +1,98 @@
+// Shared TSL sprite shapes — the "texture set" of the VFX cluster, drawn as
+// signed-distance/analytic masks on a unit quad instead of any image asset
+// (same zero-texture policy as texgen). Every helper takes `p`, the quad UV
+// remapped to [-1, 1] (`uv().mul(2).sub(1)`), and returns a 0..1 mask node.
+//
+// Trig-only on purpose: these run in the one-shot backbone's fragment shader
+// on both WebGPU and the WebGL2 fallback, so no texture fetches, no loops,
+// no derivatives.
+
+import {
+  abs, atan, clamp, cos, float, floor, fract, length, max, mix, pow, sin, smoothstep, vec2,
+} from 'three/tsl';
+
+/** Soft radial dot: 1 at center → 0 at the rim; `hardness` sharpens the core. */
+export function softDot(p, hardness = 1.8) {
+  return pow(clamp(length(p).oneMinus(), 0.0, 1.0), hardness);
+}
+
+/** Hot-core dot: soft halo plus a tight bright center (sparks, embers). */
+export function emberDot(p) {
+  const d = length(p);
+  const halo = pow(clamp(d.oneMinus(), 0.0, 1.0), 1.6);
+  const core = pow(clamp(d.oneMinus(), 0.0, 1.0), 6.0);
+  return halo.mul(0.55).add(core);
+}
+
+/**
+ * N-point star flash (the anime hit star): a radial falloff whose rim is
+ * modulated by cos(spikes·θ), plus a hot center. `spikes` may be a node
+ * (per-instance attribute) or a number.
+ */
+export function starburst(p, spikes, sharpness = 3.0) {
+  const angle = atan(p.y, p.x);
+  const lobe = pow(abs(cos(angle.mul(spikes).mul(0.5))), sharpness);
+  const radius = length(p);
+  const arm = clamp(radius.div(mix(0.18, 1.0, lobe)).oneMinus(), 0.0, 1.0);
+  const core = pow(clamp(radius.mul(3.2).oneMinus(), 0.0, 1.0), 2.0);
+  return clamp(arm.mul(arm).add(core), 0.0, 1.0);
+}
+
+/**
+ * Ring band centered at `radius01` (0..1 of the quad) with soft `thickness`
+ * (number or node — per-instance attributes welcome). Expanding shockwaves/
+ * scorch rings animate `radius01` from the vertex side by growing the QUAD
+ * and keeping the band fixed — this stays static.
+ */
+export function ringBand(p, radius01 = 0.72, thickness = 0.16) {
+  const width = float(thickness);
+  const d = abs(length(p).sub(radius01));
+  return smoothstep(width, width.mul(0.25), d);
+}
+
+/**
+ * Blobby toon puff: a circle whose rim wobbles with two angular harmonics
+ * seeded per particle — chunky hand-drawn smoke, no noise texture. Returns
+ * the SIGNED coverage (>0 inside), thresholded by the caller so cutout and
+ * soft variants can share it.
+ */
+export function puffBlob(p, seed, wobble = 0.18) {
+  const angle = atan(p.y, p.x);
+  const rim = sin(angle.mul(3.0).add(seed.mul(37.0))).mul(0.6)
+    .add(sin(angle.mul(5.0).sub(seed.mul(91.0))).mul(0.4));
+  const radius = rim.mul(wobble).add(0.82);
+  return radius.sub(length(p));
+}
+
+/**
+ * Rising flame lick mask for the fireball core: a circle stretched upward
+ * whose rim is eaten by upward-scrolling sine licks. `t` animates; `seed`
+ * de-syncs projectiles. Returns 0..1 coverage, ~1 in the body, feathering
+ * through the licks.
+ */
+export function flameLicks(p, t, seed) {
+  // Flames read taller than wide; bias the field downward so the base is round
+  // and the licks live on top.
+  const q = vec2(p.x, p.y.mul(0.78).add(0.12)).toVar();
+  const angle = atan(q.y, q.x);
+  const licks = sin(angle.mul(5.0).add(t.mul(9.0)).add(seed.mul(53.0))).mul(0.5)
+    .add(sin(angle.mul(9.0).sub(t.mul(13.0)).add(seed.mul(17.0))).mul(0.3));
+  // Licks only bite where the shape points up (angle ≈ +90°).
+  const upBias = smoothstep(-0.2, 0.9, q.y.div(max(length(q), 1e-3)));
+  const rim = licks.mul(0.16).mul(upBias).add(0.8);
+  return smoothstep(0.12, -0.08, length(q).sub(rim));
+}
+
+/**
+ * Quantizes a 0..1 fade into `bands` cel steps (top step = 1, bottom = 0).
+ * `bands` may be a node or a number; bands ≤ 1 collapses to a hard cut.
+ */
+export function celBands(fade, bands) {
+  const steps = max(bands, 1.0);
+  return clamp(floor(clamp(fade, 0.0, 1.0).mul(steps)).div(max(steps.sub(1.0), 1.0)), 0.0, 1.0);
+}
+
+/** Cheap per-fragment hash sparkle in 0..1 (grain for dust, glitter). */
+export function hashSparkle(p, seed) {
+  return fract(sin(p.x.mul(127.1).add(p.y.mul(311.7)).add(seed.mul(74.7))).mul(43758.5453));
+}

package/src/vfxgen/core/trailRibbon.js

@@ -0,0 +1,272 @@
+// Motion-trail ribbon for weapon swings — tuned to the reference-class
+// action-RPG look (Genshin-style): a SOLID, unlit, two-band surface (flat
+// saturated body + crisp white leading edge) whose tail ERODES with a hard
+// dissolving cutoff instead of fading translucent, over a Catmull-Rom
+// smoothed centerline so fast arcs stay round instead of polygonal. The
+// newest segments flash white along the blade — the "charged edge" while
+// the swing is live.
+//
+// Each frame the CPU appends ONE raw pair of world-space vertices (blade
+// base and tip) and the sampler expands it into SUBDIV spline-interpolated
+// pairs; the fragment shader erodes each written segment by its age. CPU
+// cost per active trail per frame: ~40 floats and a small memmove.
+
+import * as THREE from 'three';
+import { NodeMaterial } from 'three/webgpu';
+import {
+  attribute, cameraPosition, clamp, distance, exp, Fn, max, mix, smoothstep,
+  positionWorld, uniform, vec3, vec4,
+} from 'three/tsl';
+
+import { celBands } from './spriteShapes.js';
+
+const baseScratch = new THREE.Vector3();
+const tipScratch = new THREE.Vector3();
+const crScratch = new THREE.Vector3();
+
+/** Catmull-Rom point for control points p0..p3 at t in [0,1], into `out`. */
+function catmullRom(out, p0, p1, p2, p3, t) {
+  const t2 = t * t;
+  const t3 = t2 * t;
+  for (const axis of ['x', 'y', 'z']) {
+    out[axis] = 0.5 * (
+      2 * p1[axis]
+      + (-p0[axis] + p2[axis]) * t
+      + (2 * p0[axis] - 5 * p1[axis] + 4 * p2[axis] - p3[axis]) * t2
+      + (-p0[axis] + 3 * p1[axis] - 3 * p2[axis] + p3[axis]) * t3
+    );
+  }
+  return out;
+}
+
+// Spline points emitted per raw frame sample — the smoothing factor.
+const SUBDIV = 3;
+
+/**
+ * One pooled ribbon. `sharedUniforms` is the burst backbone's uniform set —
+ * the ribbon reads uTime and the fog quartet from it so every VFX layer
+ * shares one clock and one fog state.
+ */
+export function createTrailRibbon({ segments = 96, sharedUniforms }) {
+  const capacity = Math.max(Math.round(segments), 8);
+  const vertexCount = capacity * 2;
+  const u = sharedUniforms;
+
+  const geometry = new THREE.BufferGeometry();
+  const positions = new Float32Array(vertexCount * 3);
+  // Per-vertex (birth, edge): edge 0 = blade base, 1 = tip.
+  const trailData = new Float32Array(vertexCount * 2);
+  geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3).setUsage(THREE.DynamicDrawUsage));
+  geometry.setAttribute('aTrail', new THREE.BufferAttribute(trailData, 2).setUsage(THREE.DynamicDrawUsage));
+  const indices = new Uint16Array((capacity - 1) * 6);
+  for (let i = 0; i < capacity - 1; i += 1) {
+    const v = i * 2;
+    indices.set([v, v + 1, v + 2, v + 2, v + 1, v + 3], i * 6);
+  }
+  geometry.setIndex(new THREE.BufferAttribute(indices, 1));
+  geometry.setDrawRange(0, 0);
+  geometry.boundingSphere = new THREE.Sphere(new THREE.Vector3(), 1e5);
+
+  // Per-ribbon look uniforms — pooled ribbons re-tint on acquire.
+  const look = {
+    uBands: uniform(6),
+    uBodyColor: uniform(new THREE.Color(1.0, 0.78, 0.2)),
+    uEdgeBandColor: uniform(new THREE.Color(1, 1, 1)),
+    uIntensity: uniform(1),
+    uLifetime: uniform(0.3),
+  };
+
+  const material = new NodeMaterial();
+  material.name = 'VfxTrailRibbon';
+  material.transparent = true;
+  material.depthWrite = false;
+  material.side = THREE.DoubleSide;
+  material.fog = false;
+  // Positions are written in world space; the default vertex path is correct
+  // with the mesh at identity. Only the fragment is custom.
+  material.fragmentNode = Fn(() => {
+    const trail = attribute('aTrail', 'vec2');
+    const age = u.uTime.sub(trail.x);
+    const fade = clamp(age.div(max(look.uLifetime, 1e-3)), 0.0, 1.0).oneMinus();
+
+    // EROSION, not transparency: the surface stays solid and the tail
+    // dissolves with a hard swept cutoff, inner (base) edge first — that
+    // tapering crescent is the reference read. Partially quantizing the
+    // sweep into cel bands gives the stepped hand-drawn tail.
+    const fadeStepped = mix(fade, celBands(fade, look.uBands), 0.4);
+    const erode = smoothstep(0.0, 0.12,
+      fadeStepped.mul(1.2).sub(trail.y.oneMinus().mul(0.22)));
+
+    // Two hard bands across the width: white leading edge, saturated body.
+    const band = smoothstep(0.7, 0.84, trail.y);
+    const color = mix(look.uBodyColor, look.uEdgeBandColor, band).toVar();
+    // Newest segments flash white along the blade — the live charged edge.
+    color.assign(mix(color, vec3(1.0), smoothstep(0.05, 0.0, age).mul(0.85)));
+    color.mulAssign(look.uIntensity);
+
+    // Solid surfaces join the fog by TINT (like the dust), not by dimming.
+    const heightFalloff = exp(
+      max(positionWorld.y.sub(u.uFogFloorY), 0.0).div(max(u.uFogFalloff, 0.001)).negate());
+    const depthTerm = exp(distance(positionWorld, cameraPosition).mul(u.uFogDensity).negate()).oneMinus();
+    const fogged = mix(color, u.uFogColor, clamp(depthTerm.mul(heightFalloff), 0.0, 1.0));
+
+    return vec4(fogged, erode.mul(0.96));
+  })();
+  material.uniforms = look;
+
+  const mesh = new THREE.Mesh(geometry, material);
+  mesh.name = 'VfxTrailRibbon';
+  mesh.frustumCulled = false;
+  mesh.renderOrder = 6;
+
+  let samples = 0;
+  let active = false;
+  let lastBirth = -Infinity;
+  let lastRawTime = -Infinity;
+  let follow = null;
+  const baseAnchor = new THREE.Vector3();
+  const tipAnchor = new THREE.Vector3(0, 1, 0);
+  const minStep = 0.015;
+  // Rolling raw history for the spline: [older, prev, newest].
+  const rawBase = [new THREE.Vector3(), new THREE.Vector3(), new THREE.Vector3()];
+  const rawTip = [new THREE.Vector3(), new THREE.Vector3(), new THREE.Vector3()];
+  let rawCount = 0;
+
+  const writeSample = (index, base, tip, birth) => {
+    positions.set([base.x, base.y, base.z, tip.x, tip.y, tip.z], index * 6);
+    trailData.set([birth, 0, birth, 1], index * 4);
+  };
+
+  const appendPair = (base, tip, birth) => {
+    if (samples === capacity) {
+      positions.copyWithin(0, 6);
+      trailData.copyWithin(0, 4);
+      samples -= 1;
+    }
+    writeSample(samples, base, tip, birth);
+    samples += 1;
+  };
+
+  const markDirty = () => {
+    geometry.setDrawRange(0, Math.max(samples - 1, 0) * 6);
+    geometry.attributes.position.needsUpdate = true;
+    geometry.attributes.aTrail.needsUpdate = true;
+  };
+
+  const pushRaw = (base, tip) => {
+    rawBase[0].copy(rawBase[1]); rawBase[1].copy(rawBase[2]); rawBase[2].copy(base);
+    rawTip[0].copy(rawTip[1]); rawTip[1].copy(rawTip[2]); rawTip[2].copy(tip);
+    rawCount = Math.min(rawCount + 1, 3);
+  };
+
+  const ribbon = {
+    mesh,
+
+    get active() { return active; },
+    get samples() { return samples; },
+
+    /**
+     * Arms the ribbon on a followed Object3D. `base`/`tip` are LOCAL anchor
+     * points on the followed object (blade root and blade tip).
+     */
+    begin({ follow: target, base = [0, 0, 0], tip = [0, 1, 0], color, coreColor, lifetime, bands, intensity } = {}) {
+      follow = target ?? null;
+      baseAnchor.fromArray(base);
+      tipAnchor.fromArray(tip);
+      if (Array.isArray(color)) look.uBodyColor.value.setRGB(...color, THREE.SRGBColorSpace);
+      if (Array.isArray(coreColor)) look.uEdgeBandColor.value.setRGB(...coreColor, THREE.SRGBColorSpace);
+      if (Number.isFinite(lifetime)) look.uLifetime.value = Math.max(lifetime, 0.02);
+      if (Number.isFinite(bands)) look.uBands.value = Math.max(Math.round(bands), 1);
+      if (Number.isFinite(intensity)) look.uIntensity.value = Math.max(intensity, 0);
+      samples = 0;
+      rawCount = 0;
+      geometry.setDrawRange(0, 0);
+      active = true;
+      mesh.visible = true;
+      return ribbon;
+    },
+
+    /**
+     * Per frame while active: sample the followed object's anchors in world
+     * space; when the tip moved, append SUBDIV spline-smoothed segment pairs
+     * between the previous and current raw samples. Returns the tip position
+     * (for the sparkle emitter) or null when idle.
+     */
+    sample(now) {
+      if (!active || !follow?.isObject3D) return null;
+      follow.updateWorldMatrix(true, false);
+      const base = baseScratch.copy(baseAnchor).applyMatrix4(follow.matrixWorld);
+      const tip = tipScratch.copy(tipAnchor).applyMatrix4(follow.matrixWorld);
+
+      if (rawCount > 0) {
+        const prevTip = rawTip[2];
+        const moved = prevTip.distanceToSquared(tip);
+        if (moved < minStep * minStep) {
+          // Blade at rest: refresh the head so the ribbon stays attached.
+          if (samples > 0) {
+            writeSample(samples - 1, base, tip, now);
+            markDirty();
+          }
+          lastBirth = now;
+          lastRawTime = now;
+          return tip;
+        }
+      }
+
+      if (rawCount < 2) {
+        // Not enough history to spline yet — lay the raw pair directly.
+        pushRaw(base, tip);
+        appendPair(base, tip, now);
+      } else {
+        const prevTime = Number.isFinite(lastRawTime) ? lastRawTime : now;
+        pushRaw(base, tip);
+        // Spline between prev (p1) and newest (p2); p3 extrapolates forward.
+        for (let step = 1; step <= SUBDIV; step += 1) {
+          const t = step / SUBDIV;
+          const birth = prevTime + (now - prevTime) * t;
+          const b = catmullRom(crScratch.clone(), rawBase[0], rawBase[1], rawBase[2],
+            crScratch.copy(rawBase[2]).multiplyScalar(2).sub(rawBase[1]), t);
+          const bx = b.x; const by = b.y; const bz = b.z;
+          const tpoint = catmullRom(crScratch, rawTip[0], rawTip[1], rawTip[2],
+            tipScratch.copy(rawTip[2]).multiplyScalar(2).sub(rawTip[1]), t);
+          appendPair({ x: bx, y: by, z: bz }, tpoint, birth);
+        }
+      }
+      lastBirth = now;
+      lastRawTime = now;
+      markDirty();
+      return tipScratch.copy(tipAnchor).applyMatrix4(follow.matrixWorld);
+    },
+
+    /** Stops appending; the written arc erodes out over its lifetime. */
+    stop() {
+      active = false;
+      follow = null;
+      return ribbon;
+    },
+
+    /** True once inactive AND every written segment has fully faded. */
+    isDead(now) {
+      return !active && now - lastBirth > look.uLifetime.value + 0.05;
+    },
+
+    /** Pool reset — hides the mesh without disposing GPU resources. */
+    reset() {
+      active = false;
+      follow = null;
+      samples = 0;
+      rawCount = 0;
+      lastBirth = -Infinity;
+      lastRawTime = -Infinity;
+      geometry.setDrawRange(0, 0);
+      mesh.visible = false;
+    },
+
+    dispose() {
+      geometry.dispose();
+      material.dispose();
+    },
+  };
+  mesh.visible = false;
+  return ribbon;
+}

package/src/vfxgen/core/vfxRandom.js

@@ -0,0 +1,29 @@
+// Deterministic randomness for the VFX cluster. Same trio as ambientfx and
+// fauna — duplicated on purpose (each cluster stays self-contained), and NOT
+// re-exported from the cluster index so the root package surface doesn't
+// grow another ambiguous `hashCombine`.
+
+/** 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;
+  };
+}

package/src/vfxgen/effects/emitHelpers.js

@@ -0,0 +1,37 @@
+// Tiny shared math for the effect builders. Every builder in effects/ is a
+// PURE function of (settings, rng, spawn options, clock) → backbone records,
+// so the verify script exercises them in Node with no renderer; keep it that
+// way — no THREE, no TSL, no Date/Math.random in this folder.
+
+/** Linear interpolation. */
+export function lerp(a, b, t) {
+  return a + (b - a) * t;
+}
+
+/** Uniform point on the unit sphere from two rng draws. */
+export function randUnitVector(rng) {
+  const z = rng() * 2 - 1;
+  const theta = rng() * Math.PI * 2;
+  const r = Math.sqrt(Math.max(1 - z * z, 0));
+  return [r * Math.cos(theta), z, r * Math.sin(theta)];
+}
+
+/** Per-particle color variation: scales the whole rgb by 1 ± amount. */
+export function jitterColor(rgb, rng, amount = 0.08) {
+  const scale = 1 + (rng() * 2 - 1) * amount;
+  return [rgb[0] * scale, rgb[1] * scale, rgb[2] * scale];
+}
+
+/** Normalizes a [x, y, z] array; falls back to +Y for degenerate input. */
+export function normalized(v, fallback = [0, 1, 0]) {
+  const x = Number(v?.[0]) || 0;
+  const y = Number(v?.[1]) || 0;
+  const z = Number(v?.[2]) || 0;
+  const len = Math.hypot(x, y, z);
+  return len > 1e-6 ? [x / len, y / len, z / len] : [...fallback];
+}
+
+/** Merges per-spawn overrides over a settings group (shallow — look knobs). */
+export function withOverrides(group, overrides) {
+  return overrides && typeof overrides === 'object' ? { ...group, ...overrides } : group;
+}

package/src/vfxgen/effects/magicEffects.js

@@ -0,0 +1,162 @@
+// Magic-category effects: the fireball's in-flight ember shed and its
+// detonation (flame sparks + star flash + smoke puffs + expanding scorch
+// ring). The projectile core itself is a pooled billboard mesh with the
+// flame shader — see vfxSystem.js; these builders supply every particle
+// around it.
+//
+// Every export is a pure builder: (settings, rng, options, clock) → backbone
+// records grouped by blend state ({ glow: [...], puff: [...] }).
+
+import { BURST_KIND } from '../core/burstBackbone.js';
+import { jitterColor, lerp, normalized, randUnitVector, withOverrides } from './emitHelpers.js';
+
+/**
+ * Embers shed along the flight path. vfxSystem accumulates `emberRate · dt`
+ * and calls this with the whole-ember count, positions jittered around the
+ * projectile, so shedding is framerate-independent and deterministic.
+ */
+export function emitFireballEmbers({ settings, rng, at, velocity = [0, 0, 0], count, now = 0, overrides = null }) {
+  const e = withOverrides(settings.fireball, overrides);
+  if (!e.enabled || count <= 0) return { glow: [], puff: [] };
+  const glow = [];
+  for (let i = 0; i < count; i += 1) {
+    const scatter = randUnitVector(rng);
+    const color = jitterColor(
+      rng() < 0.35 ? e.coreColor : e.flameColor, rng, 0.1);
+    const size = lerp(e.emberSize[0], e.emberSize[1], rng());
+    glow.push({
+      birth: now,
+      extra: lerp(0.08, 0.22, rng()), // wander radius
+      gravity: -2.2, // buoyant — embers rise off the trail
+      kind: BURST_KIND.ember,
+      lifetime: e.emberLifetime * lerp(0.7, 1.3, rng()),
+      r: color[0] * e.intensity, g: color[1] * e.intensity, b: color[2] * e.intensity,
+      seed: rng(),
+      size0: size, size1: size * 0.25,
+      // Drop out of the slipstream: a touch of counter-velocity plus scatter.
+      vx: scatter[0] * 0.6 - velocity[0] * 0.08,
+      vy: scatter[1] * 0.6 - velocity[1] * 0.08 + 0.4,
+      vz: scatter[2] * 0.6 - velocity[2] * 0.08,
+      x: at[0] + scatter[0] * e.coreSize * 0.5,
+      y: at[1] + scatter[1] * e.coreSize * 0.5,
+      z: at[2] + scatter[2] * e.coreSize * 0.5,
+    });
+  }
+  return { glow, puff: [] };
+}
+
+/**
+ * Detonation at a point: flame sparks + an 8-ish spike flash + rising smoke
+ * puffs + (optionally) the ground scorch ring. `power` defaults to the
+ * settings' explosionPower; `normal` orients the spark spray (pass the
+ * surface normal of whatever was hit).
+ */
+export function emitFireballExplosion({ settings, rng, at, normal = [0, 1, 0], power = null, now = 0, overrides = null }) {
+  const e = withOverrides(settings.fireball, overrides);
+  if (!e.enabled) return { glow: [], puff: [] };
+  const p = Math.max(Number(power ?? e.explosionPower) || 1, 0);
+  const n = normalized(normal);
+  const glow = [];
+  const puff = [];
+
+  // Flame sparks — like an impact burst but slower, larger, flame-colored.
+  const sparkCount = Math.round(14 * p);
+  for (let i = 0; i < sparkCount; i += 1) {
+    const scatter = randUnitVector(rng);
+    const dir = normalized([
+      n[0] + scatter[0], Math.abs(n[1] + scatter[1]) * 0.9, n[2] + scatter[2],
+    ]);
+    const speed = 4.5 * lerp(0.4, 1.2, rng()) * Math.sqrt(p);
+    const size = 0.09 * lerp(0.7, 1.4, rng()) * p ** 0.3;
+    const color = jitterColor(rng() < 0.4 ? e.coreColor : e.flameColor, rng, 0.1);
+    glow.push({
+      birth: now,
+      extra: 2.2,
+      gravity: 7,
+      kind: BURST_KIND.spark,
+      lifetime: lerp(0.3, 0.65, rng()),
+      r: color[0] * e.intensity, g: color[1] * e.intensity, b: color[2] * e.intensity,
+      seed: rng(),
+      size0: size, size1: size * 0.3,
+      vx: dir[0] * speed, vy: dir[1] * speed, vz: dir[2] * speed,
+      x: at[0], y: at[1], z: at[2],
+    });
+  }
+
+  glow.push({
+    birth: now,
+    extra: 8,
+    gravity: 0,
+    kind: BURST_KIND.flash,
+    lifetime: 0.22,
+    r: e.coreColor[0] * e.intensity * 1.6,
+    g: e.coreColor[1] * e.intensity * 1.6,
+    b: e.coreColor[2] * e.intensity * 1.6,
+    seed: rng(),
+    size0: 1.1 * Math.sqrt(p), size1: 0,
+    vx: 0, vy: 0, vz: 0,
+    x: at[0], y: at[1], z: at[2],
+  });
+
+  // Camera-facing blast circle — the same shockwave the impact burst uses,
+  // scaled up; it sells the detonation's concussion before the smoke rises.
+  glow.push({
+    birth: now,
+    extra: 0.2,
+    gravity: 0,
+    kind: BURST_KIND.shockwave,
+    lifetime: 0.38,
+    r: e.coreColor[0] * e.intensity * 0.9,
+    g: e.coreColor[1] * e.intensity * 0.9,
+    b: e.coreColor[2] * e.intensity * 0.9,
+    seed: rng(),
+    size0: 0.2, size1: 2.6 * Math.sqrt(p),
+    vx: 0, vy: 0, vz: 0,
+    x: at[0], y: at[1] + 0.4, z: at[2],
+  });
+
+  if (e.scorchRing) {
+    glow.push({
+      birth: now,
+      extra: 0.18, // starting band thickness
+      gravity: 0,
+      kind: BURST_KIND.ring,
+      lifetime: 0.55,
+      r: e.ringColor[0] * e.intensity,
+      g: e.ringColor[1] * e.intensity,
+      b: e.ringColor[2] * e.intensity,
+      seed: rng(),
+      size0: 0.3, size1: 2.4 * p,
+      vx: 0, vy: 0, vz: 0,
+      x: at[0], y: at[1] + 0.03, z: at[2],
+    });
+  }
+
+  // Smoke column: dark warm puffs rising off the blast.
+  const puffCount = Math.round(7 * p);
+  for (let i = 0; i < puffCount; i += 1) {
+    const scatter = randUnitVector(rng);
+    const shade = lerp(0.16, 0.3, rng());
+    const size = lerp(0.28, 0.5, rng()) * p ** 0.4;
+    puff.push({
+      birth: now,
+      extra: lerp(-2.5, 2.5, rng()), // spin
+      gravity: -1.4, // buoyant rise
+      kind: BURST_KIND.puff,
+      lifetime: lerp(0.7, 1.2, rng()),
+      r: shade * (1 + e.flameColor[0] * 0.4),
+      g: shade,
+      b: shade * 0.92,
+      seed: rng(),
+      size0: size * 0.5, size1: size * 1.9,
+      vx: scatter[0] * 1.4,
+      vy: Math.abs(scatter[1]) * 1.6 + 0.8,
+      vz: scatter[2] * 1.4,
+      x: at[0] + scatter[0] * 0.25,
+      y: at[1] + Math.abs(scatter[1]) * 0.2,
+      z: at[2] + scatter[2] * 0.25,
+    });
+  }
+
+  return { glow, puff };
+}

package/src/vfxgen/effects/movementEffects.js

@@ -0,0 +1,87 @@
+// Movement-category effects: footstep dust puffs and the landing ring — the
+// ground-feedback layer that makes body movement read as WEIGHT. Both are
+// dust-only (puff group); movement feedback is matter, not light.
+//
+// Every export is a pure builder: (settings, rng, options, clock) → backbone
+// records grouped by blend state ({ glow: [...], puff: [...] }).
+
+import { BURST_KIND } from '../core/burstBackbone.js';
+import { jitterColor, lerp, normalized, withOverrides } from './emitHelpers.js';
+
+/**
+ * A footfall: a few small puffs kicked slightly backward from the travel
+ * direction (`dir`, optional XZ heading) and drifting up. Cheap enough to
+ * fire every step.
+ */
+export function emitFootstep({ settings, rng, at, dir = null, now = 0, overrides = null }) {
+  const e = withOverrides(settings.footstep, overrides);
+  if (!e.enabled) return { glow: [], puff: [] };
+  const heading = dir ? normalized([dir[0], 0, dir[2] ?? dir[1]]) : null;
+  const puff = [];
+  for (let i = 0; i < e.puffCount; i += 1) {
+    const angle = rng() * Math.PI * 2;
+    const radius = rng() * e.spread;
+    const size = lerp(e.sizeRange[0], e.sizeRange[1], rng());
+    const color = jitterColor(e.color, rng, 0.07);
+    // Kick opposite the heading (dust trails the foot), plus radial scatter.
+    const kick = heading ? 0.5 + rng() * 0.4 : 0;
+    puff.push({
+      birth: now,
+      extra: lerp(-3, 3, rng()), // spin
+      gravity: -0.5, // gentle rise
+      kind: BURST_KIND.puff,
+      lifetime: e.lifetime * lerp(0.75, 1.25, rng()),
+      r: color[0], g: color[1], b: color[2],
+      seed: rng(),
+      size0: size * 0.6, size1: size * 2.1,
+      vx: Math.cos(angle) * radius * 2 - (heading ? heading[0] * kick : 0),
+      vy: e.rise * lerp(0.5, 1.0, rng()),
+      vz: Math.sin(angle) * radius * 2 - (heading ? heading[2] * kick : 0),
+      x: at[0] + Math.cos(angle) * radius,
+      y: at[1] + 0.03,
+      z: at[2] + Math.sin(angle) * radius,
+    });
+  }
+  return { glow: [], puff };
+}
+
+/**
+ * A touch-down: a ring of puffs expanding radially from the landing point —
+ * the classic anime landing hit. `power` scales count and radius (1 = a hop,
+ * 2+ = a superhero landing).
+ */
+export function emitLanding({ settings, rng, at, power = 1, now = 0, overrides = null }) {
+  const e = withOverrides(settings.landing, overrides);
+  if (!e.enabled) return { glow: [], puff: [] };
+  const p = Math.max(Number(power) || 1, 0);
+  const count = Math.round(e.puffCount * p);
+  const radius = e.ringRadius * Math.sqrt(p);
+  const puff = [];
+  for (let i = 0; i < count; i += 1) {
+    // Even ring spacing with jitter — even spacing is what makes it a RING.
+    const angle = (i / Math.max(count, 1)) * Math.PI * 2 + (rng() - 0.5) * 0.5;
+    const size = lerp(e.sizeRange[0], e.sizeRange[1], rng()) * p ** 0.3;
+    const color = jitterColor(e.color, rng, 0.07);
+    const lifetime = e.lifetime * lerp(0.8, 1.2, rng());
+    // Launch speed tuned so the decelerating puff covers ~the ring radius
+    // over its life (backbone decel integrates to ~0.7 · v · lifetime).
+    const speed = radius / (0.7 * lifetime);
+    puff.push({
+      birth: now,
+      extra: lerp(-2.5, 2.5, rng()),
+      gravity: -0.3,
+      kind: BURST_KIND.puff,
+      lifetime,
+      r: color[0], g: color[1], b: color[2],
+      seed: rng(),
+      size0: size * 0.55, size1: size * 2.0,
+      vx: Math.cos(angle) * speed,
+      vy: 0.4 * lerp(0.6, 1.2, rng()),
+      vz: Math.sin(angle) * speed,
+      x: at[0] + Math.cos(angle) * 0.15,
+      y: at[1] + 0.04,
+      z: at[2] + Math.sin(angle) * 0.15,
+    });
+  }
+  return { glow: [], puff };
+}