@codexo/exojs 0.7.12 → 0.8.0

package/dist/esm/particles/modules/ScaleOverLifetime.js

@@ -0,0 +1,59 @@
+import { UpdateModule } from './UpdateModule.js';
+
+/// <reference types="@webgpu/types" />
+const lookupSize = 256;
+/**
+ * Sets every live particle's scale to a curve sampled at the particle's
+ * current lifetime ratio. Both axes share one curve — for non-uniform
+ * scaling layer two ScaleOverLifetime modules with separate `axis` filters
+ * (or extend with a per-axis variant).
+ *
+ * Common patterns: shrink-to-zero (start at 1, end at 0), pulse (sine-like
+ * curve up to peak then down), slow-grow (linear ramp).
+ *
+ * GPU-eligible: the curve is uploaded once as a 256-tap 1D R32F texture and
+ * sampled with linear filtering on the GPU — no curve evaluation cost in
+ * the inner loop.
+ */
+class ScaleOverLifetime extends UpdateModule {
+    curve;
+    constructor(curve) {
+        super();
+        this.curve = curve;
+    }
+    apply(system, _dt) {
+        const { scaleX, scaleY, elapsed, lifetime, liveCount } = system;
+        const curve = this.curve;
+        for (let i = 0; i < liveCount; i++) {
+            const t = elapsed[i] / lifetime[i];
+            const s = curve.evaluate(t);
+            scaleX[i] = s;
+            scaleY[i] = s;
+        }
+    }
+    wgsl() {
+        return {
+            key: 'ScaleOverLifetime',
+            textures: [{ name: 'curve', format: 'r32float' }],
+            body: `
+                let scaleT = clamp(timing[idx].x / max(timing[idx].y, 0.000001), 0.0, 1.0);
+                let scaleSample = textureSampleLevel(u_ScaleOverLifetime_curve, u_ScaleOverLifetime_curve_sampler, scaleT, 0.0).r;
+                scales[idx] = vec2<f32>(scaleSample, scaleSample);
+            `,
+        };
+    }
+    uploadTextures(device, textures) {
+        const texture = textures.get('curve');
+        if (texture === undefined) {
+            return;
+        }
+        const data = new Float32Array(lookupSize);
+        for (let i = 0; i < lookupSize; i++) {
+            data[i] = this.curve.evaluate(i / (lookupSize - 1));
+        }
+        device.queue.writeTexture({ texture }, data.buffer, { offset: 0, bytesPerRow: lookupSize * 4, rowsPerImage: 1 }, { width: lookupSize, height: 1, depthOrArrayLayers: 1 });
+    }
+}
+
+export { ScaleOverLifetime };
+//# sourceMappingURL=ScaleOverLifetime.js.map

package/dist/esm/particles/modules/ScaleOverLifetime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScaleOverLifetime.js","sources":["../../../../../src/particles/modules/ScaleOverLifetime.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAAA;AAOA,MAAM,UAAU,GAAG,GAAG;AAEtB;;;;;;;;;;;;AAYG;AACG,MAAO,iBAAkB,SAAQ,YAAY,CAAA;AACxC,IAAA,KAAK;AAEZ,IAAA,WAAA,CAAmB,KAAY,EAAA;AAC3B,QAAA,KAAK,EAAE;AACP,QAAA,IAAI,CAAC,KAAK,GAAG,KAAK;IACtB;IAEgB,KAAK,CAAC,MAAsB,EAAE,GAAW,EAAA;AACrD,QAAA,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,MAAM;AAC/D,QAAA,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK;AAExB,QAAA,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE;YAChC,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;YAClC,MAAM,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;AAE3B,YAAA,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;AACb,YAAA,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;QACjB;IACJ;IAEgB,IAAI,GAAA;QAChB,OAAO;AACH,YAAA,GAAG,EAAE,mBAAmB;YACxB,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AACjD,YAAA,IAAI,EAAE;;;;AAIL,YAAA,CAAA;SACJ;IACL;IAEgB,cAAc,CAAC,MAAiB,EAAE,QAAyC,EAAA;QACvF,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC;AAErC,QAAA,IAAI,OAAO,KAAK,SAAS,EAAE;YACvB;QACJ;AAEA,QAAA,MAAM,IAAI,GAAG,IAAI,YAAY,CAAC,UAAU,CAAC;AAEzC,QAAA,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,EAAE,CAAC,EAAE,EAAE;AACjC,YAAA,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,IAAI,UAAU,GAAG,CAAC,CAAC,CAAC;QACvD;AAEA,QAAA,MAAM,CAAC,KAAK,CAAC,YAAY,CACrB,EAAE,OAAO,EAAE,EACX,IAAI,CAAC,MAAqB,EAC1B,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,EAAE,UAAU,GAAG,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,EAC3D,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE,kBAAkB,EAAE,CAAC,EAAE,CAC1D;IACL;AACH;;;;"}

package/dist/esm/particles/modules/SpawnModule.d.ts

@@ -0,0 +1,30 @@
+import type { ParticleSystem } from '@/particles/ParticleSystem';
+/**
+ * Per-frame particle spawner. Subclasses decide how many particles to emit
+ * each tick (rate-based, burst, on-demand) and write their initial values
+ * directly into the system's typed-array slots.
+ *
+ * Implementation pattern:
+ *
+ * ```ts
+ * apply(system, dt) {
+ *     const count = this.computeSpawnCount(dt);
+ *     for (let i = 0; i < count; i++) {
+ *         const slot = system.spawn();
+ *         if (slot < 0) break;          // capacity exhausted
+ *         system.posX[slot] = ...;
+ *         system.velX[slot] = ...;
+ *         system.lifetime[slot] = ...;
+ *         // ...etc
+ *     }
+ * }
+ * ```
+ *
+ * Spawn modules run before integration each frame. Multiple modules can be
+ * registered on one system and execute in registration order.
+ */
+export declare abstract class SpawnModule {
+    abstract apply(system: ParticleSystem, dt: number): void;
+    /** Optional cleanup hook called from `ParticleSystem.destroy`. */
+    destroy(): void;
+}

package/dist/esm/particles/modules/SpawnModule.js

@@ -0,0 +1,31 @@
+/**
+ * Per-frame particle spawner. Subclasses decide how many particles to emit
+ * each tick (rate-based, burst, on-demand) and write their initial values
+ * directly into the system's typed-array slots.
+ *
+ * Implementation pattern:
+ *
+ * ```ts
+ * apply(system, dt) {
+ *     const count = this.computeSpawnCount(dt);
+ *     for (let i = 0; i < count; i++) {
+ *         const slot = system.spawn();
+ *         if (slot < 0) break;          // capacity exhausted
+ *         system.posX[slot] = ...;
+ *         system.velX[slot] = ...;
+ *         system.lifetime[slot] = ...;
+ *         // ...etc
+ *     }
+ * }
+ * ```
+ *
+ * Spawn modules run before integration each frame. Multiple modules can be
+ * registered on one system and execute in registration order.
+ */
+class SpawnModule {
+    /** Optional cleanup hook called from `ParticleSystem.destroy`. */
+    destroy() { }
+}
+
+export { SpawnModule };
+//# sourceMappingURL=SpawnModule.js.map

package/dist/esm/particles/modules/SpawnModule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpawnModule.js","sources":["../../../../../src/particles/modules/SpawnModule.ts"],"sourcesContent":[null],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;AAuBG;MACmB,WAAW,CAAA;;AAGtB,IAAA,OAAO,KAAU;AAC3B;;;;"}

package/dist/esm/particles/modules/SpawnOnDeath.d.ts

@@ -0,0 +1,24 @@
+import { DeathModule } from './DeathModule';
+import type { ParticleSystem } from '@/particles/ParticleSystem';
+import type { SpawnModule } from './SpawnModule';
+/**
+ * Sub-emitter: triggers a child {@link SpawnModule} on a target system at
+ * the dying particle's position. Use for explosion-on-impact, sparks at
+ * end-of-life, multi-stage VFX.
+ *
+ * The child module receives a synthesized `dt` of 0 — it must spawn
+ * immediately rather than rely on rate accumulation. {@link BurstSpawn}
+ * works naturally; {@link RateSpawn} is the wrong fit here.
+ *
+ * Position is the only field forwarded — child distributions decide
+ * everything else. To keep child particles riding the parent's velocity,
+ * configure the child's velocity distribution to match.
+ */
+export declare class SpawnOnDeath extends DeathModule {
+    targetSystem: ParticleSystem;
+    spawner: SpawnModule;
+    /** Number of times to invoke the spawner per dying particle. Default 1. */
+    count: number;
+    constructor(targetSystem: ParticleSystem, spawner: SpawnModule, count?: number);
+    onDeath(parent: ParticleSystem, slot: number): void;
+}

package/dist/esm/particles/modules/SpawnOnDeath.js

@@ -0,0 +1,47 @@
+import { DeathModule } from './DeathModule.js';
+
+/**
+ * Sub-emitter: triggers a child {@link SpawnModule} on a target system at
+ * the dying particle's position. Use for explosion-on-impact, sparks at
+ * end-of-life, multi-stage VFX.
+ *
+ * The child module receives a synthesized `dt` of 0 — it must spawn
+ * immediately rather than rely on rate accumulation. {@link BurstSpawn}
+ * works naturally; {@link RateSpawn} is the wrong fit here.
+ *
+ * Position is the only field forwarded — child distributions decide
+ * everything else. To keep child particles riding the parent's velocity,
+ * configure the child's velocity distribution to match.
+ */
+class SpawnOnDeath extends DeathModule {
+    targetSystem;
+    spawner;
+    /** Number of times to invoke the spawner per dying particle. Default 1. */
+    count;
+    constructor(targetSystem, spawner, count = 1) {
+        super();
+        this.targetSystem = targetSystem;
+        this.spawner = spawner;
+        this.count = count;
+    }
+    onDeath(parent, slot) {
+        const target = this.targetSystem;
+        const x = parent.posX[slot];
+        const y = parent.posY[slot];
+        // Snapshot the target's pre-spawn count so we can apply the
+        // position to whichever slots the spawner adds.
+        const before = target.liveCount;
+        for (let n = 0; n < this.count; n++) {
+            this.spawner.apply(target, 0);
+        }
+        const added = target.liveCount - before;
+        for (let i = 0; i < added; i++) {
+            const dst = before + i;
+            target.posX[dst] += x;
+            target.posY[dst] += y;
+        }
+    }
+}
+
+export { SpawnOnDeath };
+//# sourceMappingURL=SpawnOnDeath.js.map

package/dist/esm/particles/modules/SpawnOnDeath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpawnOnDeath.js","sources":["../../../../../src/particles/modules/SpawnOnDeath.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAIA;;;;;;;;;;;;AAYG;AACG,MAAO,YAAa,SAAQ,WAAW,CAAA;AAClC,IAAA,YAAY;AACZ,IAAA,OAAO;;AAGP,IAAA,KAAK;AAEZ,IAAA,WAAA,CAAmB,YAA4B,EAAE,OAAoB,EAAE,QAAgB,CAAC,EAAA;AACpF,QAAA,KAAK,EAAE;AACP,QAAA,IAAI,CAAC,YAAY,GAAG,YAAY;AAChC,QAAA,IAAI,CAAC,OAAO,GAAG,OAAO;AACtB,QAAA,IAAI,CAAC,KAAK,GAAG,KAAK;IACtB;IAEgB,OAAO,CAAC,MAAsB,EAAE,IAAY,EAAA;AACxD,QAAA,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY;QAChC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;QAC3B,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;;;AAI3B,QAAA,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS;AAE/B,QAAA,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;YACjC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QACjC;AAEA,QAAA,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,GAAG,MAAM;AAEvC,QAAA,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE;AAC5B,YAAA,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC;AAEtB,YAAA,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;AACrB,YAAA,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;QACzB;IACJ;AACH;;;;"}

package/dist/esm/particles/modules/Turbulence.d.ts

@@ -0,0 +1,30 @@
+import { UpdateModule } from './UpdateModule';
+import type { ParticleSystem } from '@/particles/ParticleSystem';
+import type { WgslContribution } from './WgslContribution';
+/**
+ * Adds a smooth pseudo-random force field that animates over time.
+ * Implemented as 2D value noise with cubic Hermite smoothing — sampled
+ * twice per particle (offset to decorrelate x and y components) and scaled
+ * by `strength`. The field evolves at `timeScale` units per second; lower
+ * values produce slow-moving currents, higher values produce buzzy chaos.
+ *
+ * `frequency` controls the spatial granularity: small values (≈ 0.005)
+ * yield broad swirls across the playfield, large values (≈ 0.1) produce
+ * tight per-particle jitter.
+ *
+ * Use cases: smoke turbulence, organic swirls, wind eddies, dust haze.
+ * Pair with {@link Drag} to keep particle velocities bounded.
+ *
+ * GPU-eligible. The noise function is identical on CPU and GPU so visual
+ * results match across backends (modulo float precision).
+ */
+export declare class Turbulence extends UpdateModule {
+    strength: number;
+    frequency: number;
+    timeScale: number;
+    private _time;
+    constructor(strength: number, frequency?: number, timeScale?: number);
+    apply(system: ParticleSystem, dt: number): void;
+    wgsl(): WgslContribution;
+    writeUniforms(view: DataView, offset: number, dt: number): void;
+}

package/dist/esm/particles/modules/Turbulence.js

@@ -0,0 +1,122 @@
+import { UpdateModule } from './UpdateModule.js';
+
+/**
+ * Adds a smooth pseudo-random force field that animates over time.
+ * Implemented as 2D value noise with cubic Hermite smoothing — sampled
+ * twice per particle (offset to decorrelate x and y components) and scaled
+ * by `strength`. The field evolves at `timeScale` units per second; lower
+ * values produce slow-moving currents, higher values produce buzzy chaos.
+ *
+ * `frequency` controls the spatial granularity: small values (≈ 0.005)
+ * yield broad swirls across the playfield, large values (≈ 0.1) produce
+ * tight per-particle jitter.
+ *
+ * Use cases: smoke turbulence, organic swirls, wind eddies, dust haze.
+ * Pair with {@link Drag} to keep particle velocities bounded.
+ *
+ * GPU-eligible. The noise function is identical on CPU and GPU so visual
+ * results match across backends (modulo float precision).
+ */
+class Turbulence extends UpdateModule {
+    strength;
+    frequency;
+    timeScale;
+    _time = 0;
+    constructor(strength, frequency = 0.01, timeScale = 1) {
+        super();
+        this.strength = strength;
+        this.frequency = frequency;
+        this.timeScale = timeScale;
+    }
+    apply(system, dt) {
+        this._time += dt * this.timeScale;
+        const t = this._time;
+        const f = this.frequency;
+        const s = this.strength * dt;
+        const { posX, posY, velX, velY, liveCount } = system;
+        for (let i = 0; i < liveCount; i++) {
+            const x = posX[i] * f;
+            const y = posY[i] * f;
+            const nx = valueNoise2(x + t, y);
+            const ny = valueNoise2(x, y + t + 17.31);
+            velX[i] += (nx * 2 - 1) * s;
+            velY[i] += (ny * 2 - 1) * s;
+        }
+    }
+    wgsl() {
+        return {
+            key: 'Turbulence',
+            uniforms: [
+                { name: 'strength', type: 'f32' },
+                { name: 'frequency', type: 'f32' },
+                { name: 'time', type: 'f32' },
+                { name: '_pad0', type: 'f32' },
+            ],
+            prelude: `
+fn exojs_turbulence_hash21(p: vec2<f32>) -> f32 {
+    let n = sin(dot(p, vec2<f32>(127.1, 311.7))) * 43758.5453;
+    return fract(n);
+}
+
+fn exojs_turbulence_valueNoise2(x: f32, y: f32) -> f32 {
+    let xi = floor(x);
+    let yi = floor(y);
+    let xf = x - xi;
+    let yf = y - yi;
+    let u = xf * xf * (3.0 - 2.0 * xf);
+    let v = yf * yf * (3.0 - 2.0 * yf);
+    let a = exojs_turbulence_hash21(vec2<f32>(xi, yi));
+    let b = exojs_turbulence_hash21(vec2<f32>(xi + 1.0, yi));
+    let c = exojs_turbulence_hash21(vec2<f32>(xi, yi + 1.0));
+    let d = exojs_turbulence_hash21(vec2<f32>(xi + 1.0, yi + 1.0));
+    let ab = a + (b - a) * u;
+    let cd = c + (d - c) * u;
+    return ab + (cd - ab) * v;
+}
+            `,
+            body: `
+                let turbF = modules.u_Turbulence.frequency;
+                let turbT = modules.u_Turbulence.time;
+                let turbS = modules.u_Turbulence.strength * dt;
+                let turbX = positions[idx].x * turbF;
+                let turbY = positions[idx].y * turbF;
+                let turbNx = exojs_turbulence_valueNoise2(turbX + turbT, turbY);
+                let turbNy = exojs_turbulence_valueNoise2(turbX, turbY + turbT + 17.31);
+                velocities[idx] = velocities[idx] + vec2<f32>(turbNx * 2.0 - 1.0, turbNy * 2.0 - 1.0) * turbS;
+            `,
+        };
+    }
+    writeUniforms(view, offset, dt) {
+        // GPU mode: apply() never runs, so advance _time here once per frame.
+        // CPU mode: apply() already advances _time before update finishes,
+        // and writeUniforms is not called → no double-advance.
+        this._time += dt * this.timeScale;
+        view.setFloat32(offset + 0, this.strength, true);
+        view.setFloat32(offset + 4, this.frequency, true);
+        view.setFloat32(offset + 8, this._time, true);
+        view.setFloat32(offset + 12, 0, true);
+    }
+}
+function hash21(x, y) {
+    let n = Math.sin(x * 127.1 + y * 311.7) * 43758.5453;
+    n = n - Math.floor(n);
+    return n;
+}
+function valueNoise2(x, y) {
+    const xi = Math.floor(x);
+    const yi = Math.floor(y);
+    const xf = x - xi;
+    const yf = y - yi;
+    const u = xf * xf * (3 - 2 * xf);
+    const v = yf * yf * (3 - 2 * yf);
+    const a = hash21(xi, yi);
+    const b = hash21(xi + 1, yi);
+    const c = hash21(xi, yi + 1);
+    const d = hash21(xi + 1, yi + 1);
+    const ab = a + (b - a) * u;
+    const cd = c + (d - c) * u;
+    return ab + (cd - ab) * v;
+}
+
+export { Turbulence };
+//# sourceMappingURL=Turbulence.js.map

package/dist/esm/particles/modules/Turbulence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Turbulence.js","sources":["../../../../../src/particles/modules/Turbulence.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/esm/particles/modules/UpdateModule.d.ts

@@ -0,0 +1,95 @@
+import type { ParticleSystem } from '@/particles/ParticleSystem';
+import type { WgslContribution } from './WgslContribution';
+/**
+ * Per-frame, per-batch mutator. Operates on the system's SoA storage
+ * directly — typically a single tight loop over `[0, system.liveCount)`
+ * that reads/writes the relevant `Float32Array`s.
+ *
+ * Implementations must always provide a CPU `apply()`. To make a module
+ * GPU-eligible (executed inside the system's composite compute shader on
+ * WebGPU backends), additionally implement {@link wgsl} and
+ * {@link writeUniforms}. Modules that declare a {@link WgslContribution}
+ * may also opt to declare a 1D texture binding via the `textures` field
+ * (used by `Curve` / `Gradient`-driven modules) — in which case
+ * {@link uploadTextures} runs once at compile time to upload the data.
+ *
+ * Implementation pattern (CPU-only module):
+ *
+ * ```ts
+ * class MyModule extends UpdateModule {
+ *     apply(system, dt) {
+ *         const { velX, velY, liveCount } = system;
+ *         for (let i = 0; i < liveCount; i++) { velX[i] *= 0.99; velY[i] *= 0.99; }
+ *     }
+ * }
+ * ```
+ *
+ * Implementation pattern (GPU-eligible module):
+ *
+ * ```ts
+ * class MyForce extends UpdateModule {
+ *     constructor(public ax: number, public ay: number) { super(); }
+ *
+ *     apply(system, dt) {
+ *         const { velX, velY, liveCount } = system;
+ *         for (let i = 0; i < liveCount; i++) { velX[i] += this.ax * dt; velY[i] += this.ay * dt; }
+ *     }
+ *
+ *     wgsl(): WgslContribution {
+ *         return {
+ *             key: 'MyForce',
+ *             uniforms: [{ name: 'ax', type: 'f32' }, { name: 'ay', type: 'f32' }],
+ *             body: `velX[idx] += u_MyForce.ax * dt; velY[idx] += u_MyForce.ay * dt;`,
+ *         };
+ *     }
+ *
+ *     writeUniforms(view, offset) {
+ *         view.setFloat32(offset + 0, this.ax, true);
+ *         view.setFloat32(offset + 4, this.ay, true);
+ *     }
+ * }
+ * ```
+ *
+ * If *any* registered update module on a system lacks `wgsl()`, the system
+ * forces CPU mode regardless of backend — preserving the contract that
+ * `apply()` is always honoured. Built-in modules ship both
+ * implementations; custom modules can opt into GPU acceleration at their
+ * authors' discretion.
+ *
+ * Update modules run after integration each frame. Multiple modules execute
+ * in registration order; later modules see the effects of earlier ones.
+ */
+export declare abstract class UpdateModule {
+    abstract apply(system: ParticleSystem, dt: number): void;
+    /**
+     * Override to declare a GPU contribution. Returning a {@link WgslContribution}
+     * makes this module GPU-eligible; omitting (or returning undefined)
+     * forces CPU mode for any system that uses this module.
+     */
+    wgsl?(): WgslContribution;
+    /**
+     * Write this module's current uniform values into the shared uniform
+     * buffer at `byteOffset`. Layout must match the field declarations
+     * returned by {@link wgsl} (in the same order).
+     *
+     * Receives the current frame `dt` (seconds). Modules tracking
+     * accumulated time (e.g. noise/turbulence) should advance their
+     * internal counter here to stay in sync when running in GPU mode
+     * (where {@link apply} is not called).
+     *
+     * Required when {@link wgsl} declares uniforms. Called every frame by
+     * the system before dispatching compute.
+     */
+    writeUniforms?(view: DataView, byteOffset: number, dt: number): void;
+    /**
+     * Upload texture data (Curve/Gradient lookup tables) to the GPU at
+     * compile time. Receives the GPUDevice and a map of texture bindings
+     * keyed by the `name` in {@link WgslContribution.textures}. Called once
+     * after pipeline creation.
+     *
+     * Required when {@link wgsl} declares textures.
+     */
+    uploadTextures?(device: GPUDevice, textures: ReadonlyMap<string, GPUTexture>): void;
+    /** Optional cleanup hook called from `ParticleSystem.destroy`. */
+    destroy(): void;
+}

package/dist/esm/particles/modules/UpdateModule.js

@@ -0,0 +1,66 @@
+/**
+ * Per-frame, per-batch mutator. Operates on the system's SoA storage
+ * directly — typically a single tight loop over `[0, system.liveCount)`
+ * that reads/writes the relevant `Float32Array`s.
+ *
+ * Implementations must always provide a CPU `apply()`. To make a module
+ * GPU-eligible (executed inside the system's composite compute shader on
+ * WebGPU backends), additionally implement {@link wgsl} and
+ * {@link writeUniforms}. Modules that declare a {@link WgslContribution}
+ * may also opt to declare a 1D texture binding via the `textures` field
+ * (used by `Curve` / `Gradient`-driven modules) — in which case
+ * {@link uploadTextures} runs once at compile time to upload the data.
+ *
+ * Implementation pattern (CPU-only module):
+ *
+ * ```ts
+ * class MyModule extends UpdateModule {
+ *     apply(system, dt) {
+ *         const { velX, velY, liveCount } = system;
+ *         for (let i = 0; i < liveCount; i++) { velX[i] *= 0.99; velY[i] *= 0.99; }
+ *     }
+ * }
+ * ```
+ *
+ * Implementation pattern (GPU-eligible module):
+ *
+ * ```ts
+ * class MyForce extends UpdateModule {
+ *     constructor(public ax: number, public ay: number) { super(); }
+ *
+ *     apply(system, dt) {
+ *         const { velX, velY, liveCount } = system;
+ *         for (let i = 0; i < liveCount; i++) { velX[i] += this.ax * dt; velY[i] += this.ay * dt; }
+ *     }
+ *
+ *     wgsl(): WgslContribution {
+ *         return {
+ *             key: 'MyForce',
+ *             uniforms: [{ name: 'ax', type: 'f32' }, { name: 'ay', type: 'f32' }],
+ *             body: `velX[idx] += u_MyForce.ax * dt; velY[idx] += u_MyForce.ay * dt;`,
+ *         };
+ *     }
+ *
+ *     writeUniforms(view, offset) {
+ *         view.setFloat32(offset + 0, this.ax, true);
+ *         view.setFloat32(offset + 4, this.ay, true);
+ *     }
+ * }
+ * ```
+ *
+ * If *any* registered update module on a system lacks `wgsl()`, the system
+ * forces CPU mode regardless of backend — preserving the contract that
+ * `apply()` is always honoured. Built-in modules ship both
+ * implementations; custom modules can opt into GPU acceleration at their
+ * authors' discretion.
+ *
+ * Update modules run after integration each frame. Multiple modules execute
+ * in registration order; later modules see the effects of earlier ones.
+ */
+class UpdateModule {
+    /** Optional cleanup hook called from `ParticleSystem.destroy`. */
+    destroy() { }
+}
+
+export { UpdateModule };
+//# sourceMappingURL=UpdateModule.js.map

package/dist/esm/particles/modules/UpdateModule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"UpdateModule.js","sources":["../../../../../src/particles/modules/UpdateModule.ts"],"sourcesContent":[null],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DG;MACmB,YAAY,CAAA;;AAoCvB,IAAA,OAAO,KAAU;AAC3B;;;;"}

package/dist/esm/particles/modules/VelocityOverLifetime.d.ts

@@ -0,0 +1,30 @@
+import { UpdateModule } from './UpdateModule';
+import type { ParticleSystem } from '@/particles/ParticleSystem';
+import type { Curve } from '@/particles/distributions/Curve';
+import type { WgslContribution } from './WgslContribution';
+/**
+ * Multiplies every live particle's velocity by a curve sampled at the
+ * particle's current `elapsed / lifetime` ratio. The same scalar is applied
+ * to both axes — the direction is preserved, only the magnitude scales.
+ *
+ * Common patterns:
+ * - **Snappy spawn, slow drift:** `[0,1]→[1,0.1]` — fast initial motion
+ *   that decays over lifetime.
+ * - **Late acceleration:** `[0,0.2]→[1,1]` — particles ease in.
+ * - **Pulse:** sine-shaped curve for breathing-style motion.
+ *
+ * Note: the curve **replaces** velocity each frame relative to the previous
+ * frame's velocity, so the effect is multiplicative. Pair with `ApplyForce`
+ * if you want a constant external acceleration on top.
+ *
+ * GPU-eligible: uploads the curve as a 256-tap 1D R32F texture; sampled
+ * once per particle per frame.
+ */
+export declare class VelocityOverLifetime extends UpdateModule {
+    curve: Curve;
+    private _prevSample;
+    constructor(curve: Curve);
+    apply(system: ParticleSystem, _dt: number): void;
+    wgsl(): WgslContribution;
+    uploadTextures(device: GPUDevice, textures: ReadonlyMap<string, GPUTexture>): void;
+}

package/dist/esm/particles/modules/VelocityOverLifetime.js

@@ -0,0 +1,84 @@
+import { UpdateModule } from './UpdateModule.js';
+
+/// <reference types="@webgpu/types" />
+const lookupSize = 256;
+/**
+ * Multiplies every live particle's velocity by a curve sampled at the
+ * particle's current `elapsed / lifetime` ratio. The same scalar is applied
+ * to both axes — the direction is preserved, only the magnitude scales.
+ *
+ * Common patterns:
+ * - **Snappy spawn, slow drift:** `[0,1]→[1,0.1]` — fast initial motion
+ *   that decays over lifetime.
+ * - **Late acceleration:** `[0,0.2]→[1,1]` — particles ease in.
+ * - **Pulse:** sine-shaped curve for breathing-style motion.
+ *
+ * Note: the curve **replaces** velocity each frame relative to the previous
+ * frame's velocity, so the effect is multiplicative. Pair with `ApplyForce`
+ * if you want a constant external acceleration on top.
+ *
+ * GPU-eligible: uploads the curve as a 256-tap 1D R32F texture; sampled
+ * once per particle per frame.
+ */
+class VelocityOverLifetime extends UpdateModule {
+    curve;
+    _prevSample = new Float32Array(0);
+    constructor(curve) {
+        super();
+        this.curve = curve;
+    }
+    apply(system, _dt) {
+        const { velX, velY, elapsed, lifetime, liveCount } = system;
+        const curve = this.curve;
+        // Resize per-particle previous-sample cache once.
+        if (this._prevSample.length < system.capacity) {
+            this._prevSample = new Float32Array(system.capacity);
+            this._prevSample.fill(1);
+        }
+        const prev = this._prevSample;
+        for (let i = 0; i < liveCount; i++) {
+            const t = elapsed[i] / lifetime[i];
+            const sample = curve.evaluate(t);
+            const last = prev[i] === 0 ? 1 : prev[i];
+            const delta = sample / last;
+            velX[i] *= delta;
+            velY[i] *= delta;
+            prev[i] = sample === 0 ? 1e-6 : sample;
+        }
+    }
+    wgsl() {
+        // GPU path uses a different formulation: re-derive velocity from
+        // initial speed at t=0 by storing nothing — instead, scale relative
+        // to the previous sample stored in scales[idx] alpha? No — keep it
+        // simple and stateless: scale the integrated velocity by the
+        // *ratio* of (current sample) / (sample at previous frame's t).
+        // We approximate the previous t with `(elapsed - dt) / lifetime`.
+        return {
+            key: 'VelocityOverLifetime',
+            textures: [{ name: 'curve', format: 'r32float' }],
+            body: `
+                let velLifetime = max(timing[idx].y, 0.000001);
+                let velTNow = clamp(timing[idx].x / velLifetime, 0.0, 1.0);
+                let velTPrev = clamp((timing[idx].x - dt) / velLifetime, 0.0, 1.0);
+                let velSampleNow = textureSampleLevel(u_VelocityOverLifetime_curve, u_VelocityOverLifetime_curve_sampler, velTNow, 0.0).r;
+                let velSamplePrev = textureSampleLevel(u_VelocityOverLifetime_curve, u_VelocityOverLifetime_curve_sampler, velTPrev, 0.0).r;
+                let velRatio = velSampleNow / max(velSamplePrev, 0.000001);
+                velocities[idx] = velocities[idx] * velRatio;
+            `,
+        };
+    }
+    uploadTextures(device, textures) {
+        const texture = textures.get('curve');
+        if (texture === undefined) {
+            return;
+        }
+        const data = new Float32Array(lookupSize);
+        for (let i = 0; i < lookupSize; i++) {
+            data[i] = this.curve.evaluate(i / (lookupSize - 1));
+        }
+        device.queue.writeTexture({ texture }, data.buffer, { offset: 0, bytesPerRow: lookupSize * 4, rowsPerImage: 1 }, { width: lookupSize, height: 1, depthOrArrayLayers: 1 });
+    }
+}
+
+export { VelocityOverLifetime };
+//# sourceMappingURL=VelocityOverLifetime.js.map

package/dist/esm/particles/modules/VelocityOverLifetime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"VelocityOverLifetime.js","sources":["../../../../../src/particles/modules/VelocityOverLifetime.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAAA;AAOA,MAAM,UAAU,GAAG,GAAG;AAEtB;;;;;;;;;;;;;;;;;AAiBG;AACG,MAAO,oBAAqB,SAAQ,YAAY,CAAA;AAC3C,IAAA,KAAK;AAEJ,IAAA,WAAW,GAAG,IAAI,YAAY,CAAC,CAAC,CAAC;AAEzC,IAAA,WAAA,CAAmB,KAAY,EAAA;AAC3B,QAAA,KAAK,EAAE;AACP,QAAA,IAAI,CAAC,KAAK,GAAG,KAAK;IACtB;IAEgB,KAAK,CAAC,MAAsB,EAAE,GAAW,EAAA;AACrD,QAAA,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,MAAM;AAC3D,QAAA,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK;;QAGxB,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,MAAM,CAAC,QAAQ,EAAE;YAC3C,IAAI,CAAC,WAAW,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC;AACpD,YAAA,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;QAC5B;AAEA,QAAA,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW;AAE7B,QAAA,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE;YAChC,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC;YAClC,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;AAChC,YAAA,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;AACxC,YAAA,MAAM,KAAK,GAAG,MAAM,GAAG,IAAI;AAE3B,YAAA,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK;AAChB,YAAA,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK;AAChB,YAAA,IAAI,CAAC,CAAC,CAAC,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,GAAG,MAAM;QAC1C;IACJ;IAEgB,IAAI,GAAA;;;;;;;QAOhB,OAAO;AACH,YAAA,GAAG,EAAE,sBAAsB;YAC3B,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AACjD,YAAA,IAAI,EAAE;;;;;;;;AAQL,YAAA,CAAA;SACJ;IACL;IAEgB,cAAc,CAAC,MAAiB,EAAE,QAAyC,EAAA;QACvF,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC;AAErC,QAAA,IAAI,OAAO,KAAK,SAAS,EAAE;YACvB;QACJ;AAEA,QAAA,MAAM,IAAI,GAAG,IAAI,YAAY,CAAC,UAAU,CAAC;AAEzC,QAAA,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,EAAE,CAAC,EAAE,EAAE;AACjC,YAAA,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,IAAI,UAAU,GAAG,CAAC,CAAC,CAAC;QACvD;AAEA,QAAA,MAAM,CAAC,KAAK,CAAC,YAAY,CACrB,EAAE,OAAO,EAAE,EACX,IAAI,CAAC,MAAqB,EAC1B,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,EAAE,UAAU,GAAG,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,EAC3D,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE,kBAAkB,EAAE,CAAC,EAAE,CAC1D;IACL;AACH;;;;"}