@flighthq/particles 0.1.0

package/src/curve.test.ts

@@ -0,0 +1,327 @@
+import { createParticleEmitter } from '@flighthq/sprite';
+import type { TextureAtlas } from '@flighthq/types';
+
+import {
+  buildParticleColorCurve,
+  buildParticleCurve,
+  lerpHsvDirect,
+  lerpHsvInPlace,
+  particleColorCurveFromKeyframes,
+  particleColorCurveToKeyframes,
+  particleCurveFromKeyframes,
+  particleCurveToKeyframes,
+  sampleParticleColorCurve,
+  sampleParticleCurve,
+} from './curve';
+import { createParticleEmitterConfig } from './particleEmitterConfig';
+import { createParticleEmitterState } from './particleEmitterState';
+import { updateParticleEmitter } from './updateParticleEmitter';
+
+function makeAtlas(): TextureAtlas {
+  return {
+    image: null,
+    regions: [{ id: 0, x: 0, y: 0, width: 32, height: 32, pivotX: null, pivotY: null }],
+  } as TextureAtlas;
+}
+
+describe('buildParticleColorCurve', () => {
+  it('bakes an RGB function into an interleaved LUT', () => {
+    const lut = buildParticleColorCurve((t) => [t, 0, 1 - t], 3);
+    expect(lut.length).toBe(9);
+    expect(lut[0]).toBe(0); // R at t=0
+    expect(lut[2]).toBe(1); // B at t=0
+  });
+});
+
+describe('buildParticleCurve', () => {
+  it('bakes a scalar function into a LUT sampled at the endpoints', () => {
+    const lut = buildParticleCurve((t) => t * t, 5);
+    expect(lut.length).toBe(5);
+    expect(lut[0]).toBe(0);
+    expect(lut[4]).toBe(1);
+    expect(sampleParticleCurve(lut, 0.5)).toBeCloseTo(0.25, 1);
+  });
+});
+
+describe('lerpHsvDirect', () => {
+  it('interpolates from red to green through yellow at t=0.5', () => {
+    const out = [0, 0, 0];
+    // Red → Green: at t=0.5, hue should be ~yellow (1/12 of hue circle)
+    lerpHsvDirect(out, 0, 1, 0, 0, 0, 1, 0, 0.5);
+    // Yellow = R≈1, G≈1, B≈0
+    expect(out[0]).toBeGreaterThan(0.7); // R
+    expect(out[1]).toBeGreaterThan(0.7); // G
+    expect(out[2]).toBeCloseTo(0, 2); // B
+  });
+
+  it('takes the short arc when interpolating hues', () => {
+    // From blue (hue=2/3) to red (hue=0) — short arc goes through magenta (hue≈5/6), not through green
+    const out = [0, 0, 0];
+    lerpHsvDirect(out, 0, 0, 0, 1, 1, 0, 0, 0.5);
+    // At midpoint (magenta direction): R should be high, G low
+    expect(out[0]).toBeGreaterThan(0.5); // R is prominent
+    expect(out[1]).toBeCloseTo(0, 2); // no green in blue/red short arc
+  });
+
+  it('writes at the given offset', () => {
+    const out = [9, 9, 9, 0, 0, 0];
+    lerpHsvDirect(out, 3, 1, 0, 0, 1, 0, 0, 0);
+    expect(out[3]).toBeCloseTo(1); // red at t=0
+    expect(out[4]).toBeCloseTo(0);
+    expect(out[5]).toBeCloseTo(0);
+  });
+});
+
+describe('lerpHsvInPlace', () => {
+  it('interpolates RGB values stored in birth/death arrays via HSV at the given offset', () => {
+    const colorsOut = [0, 0, 0];
+    const birth = new Float32Array([1, 0, 0]); // red
+    const death = new Float32Array([0, 1, 0]); // green
+    lerpHsvInPlace(colorsOut, 0, birth, death, 0.5);
+    // Red (hue=0) → green (hue=1/3) at t=0.5 → yellow (hue≈1/6)
+    expect(colorsOut[0]).toBeGreaterThan(0.5); // R dominant
+    expect(colorsOut[1]).toBeGreaterThan(0.5); // G dominant
+    expect(colorsOut[2]).toBeCloseTo(0, 2); // no blue
+  });
+
+  it('returns birth color at t=0 and death color at t=1', () => {
+    const birth = new Float32Array([0.2, 0.4, 0.6]);
+    const death = new Float32Array([0.6, 0.4, 0.2]);
+    const out0 = [0, 0, 0];
+    lerpHsvInPlace(out0, 0, birth, death, 0);
+    expect(out0[0]).toBeCloseTo(0.2, 3);
+    expect(out0[1]).toBeCloseTo(0.4, 3);
+    expect(out0[2]).toBeCloseTo(0.6, 3);
+    const out1 = [0, 0, 0];
+    lerpHsvInPlace(out1, 0, birth, death, 1);
+    expect(out1[0]).toBeCloseTo(0.6, 3);
+    expect(out1[1]).toBeCloseTo(0.4, 3);
+    expect(out1[2]).toBeCloseTo(0.2, 3);
+  });
+
+  it('reads and writes at the specified offset', () => {
+    const birth = new Float32Array([9, 9, 9, 1, 0, 0]); // offset 3 = red
+    const death = new Float32Array([9, 9, 9, 0, 1, 0]); // offset 3 = green
+    const out = [9, 9, 9, 0, 0, 0];
+    lerpHsvInPlace(out, 3, birth, death, 0);
+    expect(out[0]).toBe(9); // slots before offset unchanged
+    expect(out[3]).toBeCloseTo(1); // red at t=0
+    expect(out[4]).toBeCloseTo(0);
+    expect(out[5]).toBeCloseTo(0);
+  });
+});
+
+describe('lifetime curves in updateParticleEmitter', () => {
+  function spawnOne(configOverrides: Parameters<typeof createParticleEmitterConfig>[0]) {
+    const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+    const state = createParticleEmitterState();
+    const config = createParticleEmitterConfig({
+      spawnRate: 1,
+      lifetimeMin: 1,
+      lifetimeMax: 1,
+      speedMin: 0,
+      speedMax: 0,
+      ...configOverrides,
+    });
+    updateParticleEmitter(emitter, state, config, 1); // spawn one particle
+    return { emitter, state, config };
+  }
+
+  it('alphaCurve drives alpha non-linearly over lifetime', () => {
+    // A curve that is 1 at birth, dips to 0 at mid-life, back to 1 at death.
+    const { emitter, state, config } = spawnOne({ alphaCurve: [1, 0, 1] });
+    updateParticleEmitter(emitter, state, config, 0.5); // → mid-life
+    expect(emitter.data.alphas[0]).toBeCloseTo(0, 2);
+  });
+
+  it('colorCurve overrides the start/end gradient', () => {
+    // green at birth, red at death (interleaved RGB).
+    const { emitter, state, config } = spawnOne({
+      colorCurve: [0, 1, 0, 1, 0, 0],
+      colorStartR: 0.123, // would be used by the linear path; curve must win
+    });
+    updateParticleEmitter(emitter, state, config, 0.5);
+    expect(emitter.data.colors[0]).toBeCloseTo(0.5); // R halfway
+    expect(emitter.data.colors[1]).toBeCloseTo(0.5); // G halfway
+  });
+
+  it('scaleCurve multiplies the spawn scale', () => {
+    const { emitter, state, config } = spawnOne({
+      scaleMin: 2,
+      scaleMax: 2,
+      scaleCurve: [1, 0.5, 0], // shrink to nothing
+    });
+    updateParticleEmitter(emitter, state, config, 0.5); // mid-life → factor 0.5
+    expect(emitter.data.transforms[3]).toBeCloseTo(1, 2); // 2 * 0.5
+  });
+
+  it('sets curve-driven values at spawn time (t=0)', () => {
+    const { emitter } = spawnOne({ alphaCurve: [0.25, 1] });
+    expect(emitter.data.alphas[0]).toBeCloseTo(0.25, 2);
+  });
+});
+
+describe('particleColorCurveFromKeyframes', () => {
+  it('bakes an RGB timeline through its middle stop', () => {
+    const lut = particleColorCurveFromKeyframes([
+      { time: 0, r: 1, g: 0, b: 0 },
+      { time: 0.5, r: 0, g: 1, b: 0 },
+      { time: 1, r: 0, g: 0, b: 1 },
+    ]);
+    const out = [0, 0, 0];
+    sampleParticleColorCurve(out, 0, lut, 0.5);
+    expect(out[1]).toBeGreaterThan(0.8); // green at mid
+  });
+
+  it('an empty keyframe list yields a flat transparent curve', () => {
+    const lut = particleColorCurveFromKeyframes([]);
+    const out = [9, 9, 9];
+    sampleParticleColorCurve(out, 0, lut, 0.5);
+    expect(out).toEqual([0, 0, 0]);
+  });
+});
+
+describe('particleColorCurveToKeyframes', () => {
+  it('emits one RGB keyframe per LUT sample at uniform times', () => {
+    const keys = particleColorCurveToKeyframes([1, 0, 0, 0, 0, 1]); // red → blue
+    expect(keys).toEqual([
+      { time: 0, r: 1, g: 0, b: 0 },
+      { time: 1, r: 0, g: 0, b: 1 },
+    ]);
+  });
+
+  it('round-trips a baked color curve back to keyframes', () => {
+    const lut = particleColorCurveFromKeyframes([
+      { time: 0, r: 1, g: 0, b: 0 },
+      { time: 1, r: 0, g: 0, b: 1 },
+    ]);
+    const keys = particleColorCurveToKeyframes(lut);
+    expect(keys[0]).toEqual({ time: 0, r: 1, g: 0, b: 0 });
+    expect(keys[keys.length - 1]).toEqual({ time: 1, r: 0, g: 0, b: 1 });
+  });
+
+  it('handles empty and single-entry LUTs', () => {
+    expect(particleColorCurveToKeyframes([])).toEqual([]);
+    expect(particleColorCurveToKeyframes([0.2, 0.4, 0.6])).toEqual([{ time: 0, r: 0.2, g: 0.4, b: 0.6 }]);
+  });
+});
+
+describe('particleCurveFromKeyframes', () => {
+  it('interpolates a 3-stop scalar timeline through its middle stop', () => {
+    const lut = particleCurveFromKeyframes([
+      { time: 0, value: 0 },
+      { time: 0.5, value: 1 },
+      { time: 1, value: 0 },
+    ]);
+    expect(sampleParticleCurve(lut, 0)).toBeCloseTo(0, 2);
+    expect(sampleParticleCurve(lut, 0.5)).toBeGreaterThan(0.9);
+    expect(sampleParticleCurve(lut, 1)).toBeCloseTo(0, 2);
+  });
+
+  it('sorts unsorted keyframes by time', () => {
+    const lut = particleCurveFromKeyframes([
+      { time: 1, value: 10 },
+      { time: 0, value: 0 },
+    ]);
+    expect(sampleParticleCurve(lut, 0)).toBeCloseTo(0, 1);
+    expect(sampleParticleCurve(lut, 1)).toBeCloseTo(10, 1);
+  });
+
+  it('handles non-normalized key times by clamping at the ends', () => {
+    const lut = particleCurveFromKeyframes([
+      { time: 0.25, value: 2 },
+      { time: 0.75, value: 6 },
+    ]);
+    expect(sampleParticleCurve(lut, 0)).toBeCloseTo(2, 1); // below first key → first value
+    expect(sampleParticleCurve(lut, 1)).toBeCloseTo(6, 1); // above last key → last value
+    expect(sampleParticleCurve(lut, 0.5)).toBeCloseTo(4, 1); // midway between keys
+  });
+
+  it('a single keyframe yields a constant curve', () => {
+    const lut = particleCurveFromKeyframes([{ time: 0.5, value: 3 }]);
+    expect(sampleParticleCurve(lut, 0)).toBeCloseTo(3);
+    expect(sampleParticleCurve(lut, 1)).toBeCloseTo(3);
+  });
+
+  it('an empty keyframe list yields a flat zero curve', () => {
+    const lut = particleCurveFromKeyframes([]);
+    expect(sampleParticleCurve(lut, 0)).toBe(0);
+    expect(sampleParticleCurve(lut, 1)).toBe(0);
+  });
+});
+
+describe('particleCurveToKeyframes', () => {
+  it('emits one keyframe per LUT sample at uniform times', () => {
+    const keys = particleCurveToKeyframes([0, 0.5, 1]);
+    expect(keys).toEqual([
+      { time: 0, value: 0 },
+      { time: 0.5, value: 0.5 },
+      { time: 1, value: 1 },
+    ]);
+  });
+
+  it('round-trips a baked scalar curve back to keyframes', () => {
+    const lut = particleCurveFromKeyframes([
+      { time: 0, value: 0 },
+      { time: 1, value: 10 },
+    ]);
+    const keys = particleCurveToKeyframes(lut);
+    expect(keys[0]).toEqual({ time: 0, value: 0 });
+    expect(keys[keys.length - 1]).toEqual({ time: 1, value: 10 });
+    // Reconstructing from the keyframes reproduces the original samples.
+    expect(sampleParticleCurve(particleCurveFromKeyframes(keys, lut.length), 0.5)).toBeCloseTo(
+      sampleParticleCurve(lut, 0.5),
+      5,
+    );
+  });
+
+  it('handles empty and single-entry LUTs', () => {
+    expect(particleCurveToKeyframes([])).toEqual([]);
+    expect(particleCurveToKeyframes([7])).toEqual([{ time: 0, value: 7 }]);
+  });
+});
+
+describe('sampleParticleColorCurve', () => {
+  it('interpolates interleaved RGB channels', () => {
+    const lut = [1, 0, 0, 0, 0, 1]; // red → blue
+    const out = [0, 0, 0];
+    sampleParticleColorCurve(out, 0, lut, 0.5);
+    expect(out[0]).toBeCloseTo(0.5); // R
+    expect(out[1]).toBeCloseTo(0); // G
+    expect(out[2]).toBeCloseTo(0.5); // B
+  });
+
+  it('writes at the given offset', () => {
+    const lut = [0.2, 0.4, 0.6];
+    const out = [9, 9, 9, 9, 9];
+    sampleParticleColorCurve(out, 2, lut, 0);
+    expect(out[2]).toBeCloseTo(0.2);
+    expect(out[3]).toBeCloseTo(0.4);
+    expect(out[4]).toBeCloseTo(0.6);
+  });
+});
+
+describe('sampleParticleCurve', () => {
+  it('returns endpoints at t=0 and t=1', () => {
+    const lut = [0, 0.5, 1];
+    expect(sampleParticleCurve(lut, 0)).toBe(0);
+    expect(sampleParticleCurve(lut, 1)).toBe(1);
+  });
+
+  it('linearly interpolates between samples', () => {
+    const lut = [0, 1]; // straight line 0→1
+    expect(sampleParticleCurve(lut, 0.25)).toBeCloseTo(0.25);
+    expect(sampleParticleCurve(lut, 0.5)).toBeCloseTo(0.5);
+  });
+
+  it('clamps out-of-range t', () => {
+    const lut = [2, 4];
+    expect(sampleParticleCurve(lut, -1)).toBe(2);
+    expect(sampleParticleCurve(lut, 5)).toBe(4);
+  });
+
+  it('handles empty and single-entry curves', () => {
+    expect(sampleParticleCurve([], 0.5)).toBe(0);
+    expect(sampleParticleCurve([7], 0.5)).toBe(7);
+  });
+});

package/src/deterministic.test.ts

@@ -0,0 +1,54 @@
+import { createRandomSource } from '@flighthq/math';
+import { createParticleEmitter } from '@flighthq/sprite';
+import type { TextureAtlas } from '@flighthq/types';
+
+import { createParticleEmitterConfig } from './particleEmitterConfig';
+import { createParticleEmitterState } from './particleEmitterState';
+import { stepParticleEmitter } from './stepParticleEmitter';
+
+function makeAtlas(): TextureAtlas {
+  return {
+    image: null,
+    regions: [{ id: 0, x: 0, y: 0, width: 32, height: 32, pivotX: null, pivotY: null }],
+  } as unknown as TextureAtlas;
+}
+
+describe('deterministic replay', () => {
+  it('produces byte-identical SoA buffers from two identically-seeded emitters', () => {
+    const atlas = makeAtlas();
+    const config = createParticleEmitterConfig({
+      spawnRate: 20,
+      maxParticles: 100,
+      lifetimeMin: 0.5,
+      lifetimeMax: 2,
+      speedMin: 50,
+      speedMax: 150,
+      spread: Math.PI,
+      gravityY: 100,
+    });
+
+    const emitterA = createParticleEmitter({ data: { atlas } });
+    const stateA = createParticleEmitterState(createRandomSource(42));
+
+    const emitterB = createParticleEmitter({ data: { atlas } });
+    const stateB = createParticleEmitterState(createRandomSource(42));
+
+    const steps = [0.016, 0.033, 0.016, 0.05, 0.016, 0.016, 0.033, 0.016];
+    for (const dt of steps) {
+      stepParticleEmitter(emitterA, stateA, config, dt);
+      stepParticleEmitter(emitterB, stateB, config, dt);
+    }
+
+    expect(emitterA.data.particleCount).toBeGreaterThan(0);
+    expect(emitterA.data.particleCount).toBe(emitterB.data.particleCount);
+
+    const count = emitterA.data.particleCount;
+    expect(emitterA.data.transforms.subarray(0, count * 4)).toEqual(emitterB.data.transforms.subarray(0, count * 4));
+    expect(emitterA.data.alphas.subarray(0, count)).toEqual(emitterB.data.alphas.subarray(0, count));
+    expect(emitterA.data.colors.subarray(0, count * 3)).toEqual(emitterB.data.colors.subarray(0, count * 3));
+    expect(emitterA.data.velocities.subarray(0, count * 2)).toEqual(emitterB.data.velocities.subarray(0, count * 2));
+    expect(stateA.lifetimes.subarray(0, count * 2)).toEqual(stateB.lifetimes.subarray(0, count * 2));
+    expect(stateA.velocities.subarray(0, count * 2)).toEqual(stateB.velocities.subarray(0, count * 2));
+    expect(stateA.scales.subarray(0, count)).toEqual(stateB.scales.subarray(0, count));
+  });
+});

package/src/emitParticleBurst.test.ts

@@ -0,0 +1,103 @@
+import { createRandomSource } from '@flighthq/math';
+import { createParticleEmitter } from '@flighthq/sprite';
+import type { TextureAtlas } from '@flighthq/types';
+
+import { emitParticleBurst } from './emitParticleBurst';
+import { createParticleEmitterConfig } from './particleEmitterConfig';
+import { createParticleEmitterState } from './particleEmitterState';
+import { updateParticleEmitter } from './updateParticleEmitter';
+
+function makeAtlas(): TextureAtlas {
+  return {
+    image: null,
+    regions: [{ id: 0, x: 0, y: 0, width: 32, height: 32, pivotX: null, pivotY: null }],
+  } as TextureAtlas;
+}
+
+describe('emitParticleBurst', () => {
+  it('spawns the requested count at the given point', () => {
+    const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+    const state = createParticleEmitterState();
+    const config = createParticleEmitterConfig({ speedMin: 0, speedMax: 0, lifetimeMin: 10, lifetimeMax: 10 });
+    const n = emitParticleBurst(emitter, state, config, 8, 200, 300);
+    expect(n).toBe(8);
+    expect(emitter.data.particleCount).toBe(8);
+    // With zero speed and a point emitter, every particle sits at the burst point.
+    for (let i = 0; i < 8; i++) {
+      expect(emitter.data.transforms[i * 4]).toBeCloseTo(200);
+      expect(emitter.data.transforms[i * 4 + 1]).toBeCloseTo(300);
+    }
+  });
+
+  it('respects maxParticles and returns the actual spawn count', () => {
+    const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+    const state = createParticleEmitterState();
+    const config = createParticleEmitterConfig({ maxParticles: 5, lifetimeMin: 10, lifetimeMax: 10 });
+    expect(emitParticleBurst(emitter, state, config, 100, 0, 0)).toBe(5);
+    expect(emitter.data.particleCount).toBe(5);
+  });
+
+  it('adds to existing particles rather than replacing them', () => {
+    const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+    const state = createParticleEmitterState();
+    const config = createParticleEmitterConfig({ maxParticles: 100, lifetimeMin: 10, lifetimeMax: 10 });
+    emitParticleBurst(emitter, state, config, 3, 0, 0);
+    emitParticleBurst(emitter, state, config, 4, 0, 0);
+    expect(emitter.data.particleCount).toBe(7);
+  });
+
+  it("does not touch the emitter's continuous-emission bookkeeping", () => {
+    const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+    const state = createParticleEmitterState();
+    const config = createParticleEmitterConfig({ lifetimeMin: 10, lifetimeMax: 10 });
+    emitParticleBurst(emitter, state, config, 3, 0, 0);
+    expect(state.spawnAccumulator).toBe(0);
+    expect(state.emitterAge).toBe(0);
+  });
+
+  it('is deterministic with a seeded state', () => {
+    const run = (): number[] => {
+      const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+      const state = createParticleEmitterState(createRandomSource(99));
+      const config = createParticleEmitterConfig({
+        speedMin: 10,
+        speedMax: 200,
+        spread: Math.PI,
+        lifetimeMin: 1,
+        lifetimeMax: 5,
+      });
+      emitParticleBurst(emitter, state, config, 10, 0, 0);
+      return Array.from(state.velocities.slice(0, 20));
+    };
+    expect(run()).toEqual(run());
+  });
+
+  it('composes into a death sub-emitter via onDeath (explosion on expiry)', () => {
+    // Parent: short-lived particles. Child: a burst spawned where each parent dies.
+    const parent = createParticleEmitter({ data: { atlas: makeAtlas() } });
+    const parentState = createParticleEmitterState();
+    const parentConfig = createParticleEmitterConfig({
+      spawnRate: 5,
+      lifetimeMin: 0.5,
+      lifetimeMax: 0.5,
+      speedMin: 0,
+      speedMax: 0,
+    });
+
+    const child = createParticleEmitter({ data: { atlas: makeAtlas() } });
+    const childState = createParticleEmitterState();
+    const childConfig = createParticleEmitterConfig({ maxParticles: 1000, lifetimeMin: 10, lifetimeMax: 10 });
+
+    let deaths = 0;
+    const onDeath = (x: number, y: number): void => {
+      deaths++;
+      emitParticleBurst(child, childState, childConfig, 6, x, y);
+    };
+
+    // Run long enough for the parent particles to spawn and then expire.
+    for (let i = 0; i < 30; i++) updateParticleEmitter(parent, parentState, parentConfig, 1 / 30, { onDeath });
+
+    expect(deaths).toBeGreaterThan(0);
+    expect(child.data.particleCount).toBe(deaths * 6); // 6 child particles per parent death
+  });
+});

package/src/particleEmitterConfig.test.ts

@@ -0,0 +1,65 @@
+import { createParticleEmitterConfig } from './particleEmitterConfig';
+
+describe('createParticleEmitterConfig', () => {
+  it('returns defaults when called with no arguments', () => {
+    const config = createParticleEmitterConfig();
+    expect(config.alphaEnd).toBe(0);
+    expect(config.alphaStart).toBe(1);
+    expect(config.burstCount).toBe(0);
+    expect(config.burstInterval).toBe(0);
+    expect(config.duration).toBe(0);
+    expect(config.loop).toBe(true);
+    expect(config.colorEndR).toBe(1);
+    expect(config.colorEndG).toBe(1);
+    expect(config.colorEndB).toBe(1);
+    expect(config.colorStartR).toBe(1);
+    expect(config.colorStartG).toBe(1);
+    expect(config.colorStartB).toBe(1);
+    expect(config.directionX).toBe(0);
+    expect(config.directionY).toBe(-1);
+    expect(config.emitterShape).toBe('point');
+    expect(config.emitterRadius).toBe(0);
+    expect(config.emitterWidth).toBe(0);
+    expect(config.emitterHeight).toBe(0);
+    expect(config.frameCount).toBe(1);
+    expect(config.frameRate).toBe(12);
+    expect(config.gravityX).toBe(0);
+    expect(config.gravityY).toBe(0);
+    expect(config.lifetimeMax).toBe(1);
+    expect(config.lifetimeMin).toBe(0.5);
+    expect(config.maxParticles).toBe(1000);
+    expect(config.regionIdMax).toBe(1);
+    expect(config.regionIdMin).toBe(0);
+    expect(config.rotationSpeedMin).toBe(0);
+    expect(config.rotationSpeedMax).toBe(0);
+    expect(config.scaleEnd).toBe(1);
+    expect(config.velocityInheritance).toBe(0);
+    expect(config.worldSpace).toBe(false);
+    expect(config.blendMode).toBeNull();
+    expect(config.colorStartVarianceR).toBe(0);
+    expect(config.colorStartVarianceG).toBe(0);
+    expect(config.colorStartVarianceB).toBe(0);
+    expect(config.colorEndVarianceR).toBe(0);
+    expect(config.colorEndVarianceG).toBe(0);
+    expect(config.colorEndVarianceB).toBe(0);
+    expect(config.scaleMax).toBe(1);
+    expect(config.scaleMin).toBe(1);
+    expect(config.speedMax).toBe(100);
+    expect(config.speedMin).toBe(50);
+    expect(config.spawnRate).toBe(10);
+    expect(config.spread).toBe(Math.PI);
+  });
+
+  it('overrides individual fields', () => {
+    const config = createParticleEmitterConfig({ spawnRate: 60, maxParticles: 500 });
+    expect(config.spawnRate).toBe(60);
+    expect(config.maxParticles).toBe(500);
+    expect(config.alphaEnd).toBe(0); // other fields still default
+  });
+
+  it('returns a new object each call', () => {
+    const a = createParticleEmitterConfig();
+    const b = createParticleEmitterConfig();
+    expect(a).not.toBe(b);
+  });
+});

package/src/particleEmitterSignals.test.ts

@@ -0,0 +1,125 @@
+import { createParticleEmitter } from '@flighthq/sprite';
+import type { TextureAtlas } from '@flighthq/types';
+
+import { createParticleEmitterConfig } from './particleEmitterConfig';
+import {
+  createParticleEmitterSignals,
+  enableParticleEmitterSignals,
+  getParticleEmitterSignals,
+} from './particleEmitterSignals';
+import { createParticleEmitterState } from './particleEmitterState';
+import { updateParticleEmitter } from './updateParticleEmitter';
+
+function makeAtlas(): TextureAtlas {
+  return {
+    image: null,
+    regions: [{ id: 0, x: 0, y: 0, width: 32, height: 32, pivotX: null, pivotY: null }],
+  } as unknown as TextureAtlas;
+}
+
+function spawnOne(configOverrides: Record<string, unknown> = {}) {
+  const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+  const state = createParticleEmitterState();
+  const config = createParticleEmitterConfig({
+    spawnRate: 1,
+    lifetimeMin: 1,
+    lifetimeMax: 1,
+    speedMin: 0,
+    speedMax: 0,
+    ...configOverrides,
+  });
+  return { emitter, state, config };
+}
+
+describe('createParticleEmitterSignals', () => {
+  it('creates a signals group with all three signal slots', () => {
+    const signals = createParticleEmitterSignals();
+    expect(signals.onParticleSpawn).toBeDefined();
+    expect(signals.onParticleDeath).toBeDefined();
+    expect(signals.onEmitterComplete).toBeDefined();
+  });
+});
+
+describe('enableParticleEmitterSignals', () => {
+  it('returns the same object on repeated calls', () => {
+    const state = createParticleEmitterState();
+    const a = enableParticleEmitterSignals(state);
+    const b = enableParticleEmitterSignals(state);
+    expect(a).toBe(b);
+  });
+
+  it('returns null from getParticleEmitterSignals before enablement', () => {
+    const state = createParticleEmitterState();
+    expect(getParticleEmitterSignals(state)).toBeNull();
+  });
+
+  it('returns non-null from getParticleEmitterSignals after enablement', () => {
+    const state = createParticleEmitterState();
+    enableParticleEmitterSignals(state);
+    expect(getParticleEmitterSignals(state)).not.toBeNull();
+  });
+});
+
+describe('getParticleEmitterSignals', () => {
+  it('returns null when signals have not been enabled', () => {
+    const state = createParticleEmitterState();
+    expect(getParticleEmitterSignals(state)).toBeNull();
+  });
+});
+
+describe('onEmitterComplete signal', () => {
+  it('fires once when a finite non-looping emitter completes', () => {
+    const { emitter, state } = spawnOne({ duration: 0.5, loop: false });
+    const config = createParticleEmitterConfig({
+      duration: 0.5,
+      loop: false,
+      spawnRate: 1,
+      lifetimeMin: 0.1,
+      lifetimeMax: 0.1,
+      speedMin: 0,
+      speedMax: 0,
+    });
+    const signals = enableParticleEmitterSignals(state);
+    const completes: number[] = [];
+    signals.onEmitterComplete.emit = () => completes.push(1);
+    updateParticleEmitter(emitter, state, config, 1); // spawn + age past duration
+    updateParticleEmitter(emitter, state, config, 1); // particles die → complete
+    expect(completes.length).toBeGreaterThan(0);
+  });
+
+  it('does not fire for infinite emitters', () => {
+    const { emitter, state, config } = spawnOne({ duration: 0, loop: true });
+    const signals = enableParticleEmitterSignals(state);
+    const completes: number[] = [];
+    signals.onEmitterComplete.emit = () => completes.push(1);
+    for (let i = 0; i < 10; i++) updateParticleEmitter(emitter, state, config, 1);
+    expect(completes.length).toBe(0);
+  });
+});
+
+describe('onParticleDeath signal', () => {
+  it('fires with the particle position when a particle dies', () => {
+    const { emitter, state, config } = spawnOne();
+    const signals = enableParticleEmitterSignals(state);
+    const deaths: Array<[number, number]> = [];
+    signals.onParticleDeath.emit = (x: number, y: number) => deaths.push([x, y]);
+    updateParticleEmitter(emitter, state, config, 1); // spawn
+    updateParticleEmitter(emitter, state, config, 1.1); // age past lifetime → death
+    expect(deaths.length).toBe(1);
+    expect(Number.isFinite(deaths[0][0])).toBe(true);
+  });
+});
+
+describe('onParticleSpawn signal', () => {
+  it('fires with spawn position and velocity when a particle is spawned', () => {
+    const { emitter, state, config } = spawnOne({ speedMin: 50, speedMax: 50 });
+    const signals = enableParticleEmitterSignals(state);
+    const spawns: Array<[number, number, number, number]> = [];
+    signals.onParticleSpawn.emit = (x: number, y: number, vx: number, vy: number) => spawns.push([x, y, vx, vy]);
+    updateParticleEmitter(emitter, state, config, 1);
+    expect(spawns.length).toBe(1);
+    const [, , vx, vy] = spawns[0];
+    // Speed must match config (allow sign variations by checking magnitude).
+    expect(Math.sqrt(vx * vx + vy * vy)).toBeCloseTo(50, 0);
+  });
+});