@flighthq/particles 0.1.0

package/src/particleEmitterState.test.ts

@@ -0,0 +1,113 @@
+import { createRandomSource } from '@flighthq/math';
+import { createParticleEmitter } from '@flighthq/sprite';
+import type { TextureAtlas } from '@flighthq/types';
+
+import { createParticleEmitterConfig } from './particleEmitterConfig';
+import { createParticleEmitterState, ensureParticleEmitterStateCapacity } from './particleEmitterState';
+import { updateParticleEmitter } from './updateParticleEmitter';
+
+// Runs a short emitter simulation seeded from `seed` and returns the live particle transforms, so a
+// seeded state can be shown to simulate reproducibly (the seeded RNG now lives in @flighthq/math).
+function simulate(seed: number): number[] {
+  const emitter = createParticleEmitter({
+    data: {
+      atlas: {
+        image: null,
+        regions: [{ id: 0, x: 0, y: 0, width: 32, height: 32, pivotX: null, pivotY: null }],
+      } as TextureAtlas,
+    },
+  });
+  const state = createParticleEmitterState(createRandomSource(seed));
+  const config = createParticleEmitterConfig({
+    spawnRate: 20,
+    maxParticles: 100,
+    lifetimeMin: 0.5,
+    lifetimeMax: 1.5,
+    speedMin: 10,
+    speedMax: 200,
+    spread: Math.PI,
+    emitterShape: 'circle',
+    emitterRadius: 25,
+    colorStartVarianceR: 0.5,
+  });
+  for (let f = 0; f < 30; f++) updateParticleEmitter(emitter, state, config, 1 / 60);
+  return Array.from(emitter.data.transforms.slice(0, emitter.data.particleCount * 4));
+}
+
+describe('createParticleEmitterState', () => {
+  it('seeded identically, two states simulate bit-for-bit identically', () => {
+    expect(simulate(42)).toEqual(simulate(42));
+  });
+
+  it('diverges under different seeds', () => {
+    expect(simulate(42)).not.toEqual(simulate(43));
+  });
+
+  it('returns empty arrays, zero accumulator, burstTimer=0, and NaN prev position', () => {
+    const state = createParticleEmitterState();
+    expect(state.lifetimes).toBeInstanceOf(Float32Array);
+    expect(state.lifetimes.length).toBe(0);
+    expect(state.velocities).toBeInstanceOf(Float32Array);
+    expect(state.velocities.length).toBe(0);
+    expect(state.scales).toBeInstanceOf(Float32Array);
+    expect(state.scales.length).toBe(0);
+    expect(state.rotationSpeeds).toBeInstanceOf(Float32Array);
+    expect(state.rotationSpeeds.length).toBe(0);
+    expect(state.colorBirth).toBeInstanceOf(Float32Array);
+    expect(state.colorDeath).toBeInstanceOf(Float32Array);
+    expect(state.spawnAccumulator).toBe(0);
+    expect(state.burstTimer).toBe(0);
+    expect(isNaN(state.prevX)).toBe(true);
+    expect(isNaN(state.prevY)).toBe(true);
+  });
+
+  it('returns a new object each call', () => {
+    const a = createParticleEmitterState();
+    const b = createParticleEmitterState();
+    expect(a).not.toBe(b);
+  });
+});
+
+describe('ensureParticleEmitterStateCapacity', () => {
+  it('grows the per-particle arrays to hold at least `capacity` particles', () => {
+    const state = createParticleEmitterState();
+    ensureParticleEmitterStateCapacity(state, 10, false);
+    expect(state.lifetimes.length).toBeGreaterThanOrEqual(10 * 2);
+    expect(state.velocities.length).toBeGreaterThanOrEqual(10 * 2);
+    expect(state.scales.length).toBeGreaterThanOrEqual(10);
+    expect(state.rotationSpeeds.length).toBeGreaterThanOrEqual(10);
+  });
+
+  it('leaves the color arrays empty when the emitter has no color variance', () => {
+    const state = createParticleEmitterState();
+    ensureParticleEmitterStateCapacity(state, 8, false);
+    expect(state.colorBirth.length).toBe(0);
+    expect(state.colorDeath.length).toBe(0);
+  });
+
+  it('grows the color arrays only when color variance is requested', () => {
+    const state = createParticleEmitterState();
+    ensureParticleEmitterStateCapacity(state, 8, true);
+    expect(state.colorBirth.length).toBeGreaterThanOrEqual(8 * 3);
+    expect(state.colorDeath.length).toBeGreaterThanOrEqual(8 * 3);
+  });
+
+  it('is a no-op when already large enough', () => {
+    const state = createParticleEmitterState();
+    ensureParticleEmitterStateCapacity(state, 16, false);
+    const lifetimes = state.lifetimes;
+    const velocities = state.velocities;
+    ensureParticleEmitterStateCapacity(state, 4, false); // smaller request → no reallocation
+    expect(state.lifetimes).toBe(lifetimes);
+    expect(state.velocities).toBe(velocities);
+  });
+
+  it('back-fills color arrays for an already-sized state when variance turns on', () => {
+    const state = createParticleEmitterState();
+    ensureParticleEmitterStateCapacity(state, 8, false); // sized, no color
+    expect(state.colorBirth.length).toBe(0);
+    ensureParticleEmitterStateCapacity(state, 8, true); // same capacity, now wants color
+    expect(state.colorBirth.length).toBeGreaterThanOrEqual(8 * 3);
+    expect(state.colorDeath.length).toBeGreaterThanOrEqual(8 * 3);
+  });
+});

package/src/particleObjectsState.test.ts

@@ -0,0 +1,34 @@
+import { createParticleObjectsState, ensureParticleObjectsStateCapacity } from './particleObjectsState';
+
+describe('createParticleObjectsState', () => {
+  it('allocates arrays sized to capacity', () => {
+    const state = createParticleObjectsState(10);
+    expect(state.lifetimes.length).toBe(20);
+    expect(state.velocities.length).toBe(20);
+    expect(state.spawnAccumulator).toBe(0);
+  });
+
+  it('all lifetime slots start as dead (maxAge = 0)', () => {
+    const state = createParticleObjectsState(5);
+    for (let i = 0; i < 5; i++) {
+      expect(state.lifetimes[i * 2 + 1]).toBe(0);
+    }
+  });
+});
+
+describe('ensureParticleObjectsStateCapacity', () => {
+  it('does not reallocate when already large enough', () => {
+    const state = createParticleObjectsState(10);
+    const { lifetimes, velocities } = state;
+    ensureParticleObjectsStateCapacity(state, 10);
+    expect(state.lifetimes).toBe(lifetimes);
+    expect(state.velocities).toBe(velocities);
+  });
+
+  it('grows arrays when capacity is insufficient', () => {
+    const state = createParticleObjectsState(5);
+    ensureParticleObjectsStateCapacity(state, 20);
+    expect(state.lifetimes.length).toBeGreaterThanOrEqual(40);
+    expect(state.velocities.length).toBeGreaterThanOrEqual(40);
+  });
+});

package/src/prewarmParticleEmitter.test.ts

@@ -0,0 +1,68 @@
+import { createParticleEmitter } from '@flighthq/sprite';
+import type { TextureAtlas } from '@flighthq/types';
+
+import { createParticleEmitterConfig } from './particleEmitterConfig';
+import { createParticleEmitterState } from './particleEmitterState';
+import { prewarmParticleEmitter } from './prewarmParticleEmitter';
+
+function makeAtlas(): TextureAtlas {
+  return {
+    image: null,
+    regions: [{ id: 0, x: 0, y: 0, width: 32, height: 32, pivotX: null, pivotY: null }],
+  } as TextureAtlas;
+}
+
+describe('prewarmParticleEmitter', () => {
+  it('produces live particles after warming for one lifetime', () => {
+    const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+    const state = createParticleEmitterState();
+    const config = createParticleEmitterConfig({ spawnRate: 20, lifetimeMin: 1, lifetimeMax: 1 });
+    prewarmParticleEmitter(emitter, state, config, 1);
+    expect(emitter.data.particleCount).toBeGreaterThan(0);
+  });
+
+  it('does not exceed maxParticles', () => {
+    const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+    const state = createParticleEmitterState();
+    const config = createParticleEmitterConfig({ spawnRate: 1000, maxParticles: 10, lifetimeMin: 10, lifetimeMax: 10 });
+    prewarmParticleEmitter(emitter, state, config, 5);
+    expect(emitter.data.particleCount).toBeLessThanOrEqual(10);
+  });
+
+  it('accepts a custom stepDeltaTime and still produces particles', () => {
+    const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+    const state = createParticleEmitterState();
+    const config = createParticleEmitterConfig({ spawnRate: 10, lifetimeMin: 5, lifetimeMax: 5 });
+    prewarmParticleEmitter(emitter, state, config, 1, 1 / 30);
+    expect(emitter.data.particleCount).toBeGreaterThan(0);
+  });
+
+  it('fires onSpawn callback during warm-up', () => {
+    const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+    const state = createParticleEmitterState();
+    const config = createParticleEmitterConfig({ spawnRate: 5, lifetimeMin: 10, lifetimeMax: 10 });
+    let spawned = 0;
+    prewarmParticleEmitter(emitter, state, config, 1, 1 / 60, {
+      onSpawn: () => {
+        spawned++;
+      },
+    });
+    expect(spawned).toBeGreaterThan(0);
+  });
+
+  it('leaves emitter unmodified when duration is zero', () => {
+    const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+    const state = createParticleEmitterState();
+    const config = createParticleEmitterConfig({ spawnRate: 100, lifetimeMin: 1, lifetimeMax: 1 });
+    prewarmParticleEmitter(emitter, state, config, 0);
+    expect(emitter.data.particleCount).toBe(0);
+  });
+
+  it('does not hang when stepDeltaTime is zero (falls back to a single step)', () => {
+    const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+    const state = createParticleEmitterState();
+    const config = createParticleEmitterConfig({ spawnRate: 10, lifetimeMin: 10, lifetimeMax: 10 });
+    prewarmParticleEmitter(emitter, state, config, 1, 0);
+    expect(emitter.data.particleCount).toBeGreaterThan(0);
+  });
+});

package/src/stepParticleEmitter.test.ts

@@ -0,0 +1,113 @@
+import { createParticleEmitter } from '@flighthq/sprite';
+import type { ParticleCollider, ParticleForce, ParticleObject, TextureAtlas } from '@flighthq/types';
+
+import { createParticleEmitterConfig } from './particleEmitterConfig';
+import { createParticleEmitterState } from './particleEmitterState';
+import { createParticleObjectsState } from './particleObjectsState';
+import { stepParticleEmitter, stepParticleObjects } 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('stepParticleEmitter', () => {
+  it('spawns particles when called with no forces or colliders', () => {
+    const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+    const state = createParticleEmitterState();
+    const config = createParticleEmitterConfig({ spawnRate: 10, maxParticles: 100 });
+    stepParticleEmitter(emitter, state, config, 1);
+    expect(emitter.data.particleCount).toBe(10);
+  });
+
+  it('applies wind force before update — particle receives velocity from wind', () => {
+    const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+    const state = createParticleEmitterState();
+    const config = createParticleEmitterConfig({
+      spawnRate: 1,
+      lifetimeMin: 10,
+      lifetimeMax: 10,
+      speedMin: 0,
+      speedMax: 0,
+      spread: 0,
+      directionX: 0,
+      directionY: -1,
+    });
+    // Spawn one particle first
+    stepParticleEmitter(emitter, state, config, 1);
+    expect(emitter.data.particleCount).toBe(1);
+    // Now step with a wind force pushing right
+    const wind: ParticleForce = { kind: 'WindForce', x: 200, y: 0 };
+    stepParticleEmitter(emitter, state, config, 1, [wind]);
+    // After wind: vx starts at 0, gets +200 from wind in applyForces, then particle moves right
+    const x = emitter.data.transforms[0];
+    expect(x).toBeGreaterThan(0);
+  });
+
+  it('resolves collisions after update — particle stays above a plane at y=0', () => {
+    const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+    const state = createParticleEmitterState();
+    const config = createParticleEmitterConfig({
+      spawnRate: 1,
+      lifetimeMin: 10,
+      lifetimeMax: 10,
+      speedMin: 100,
+      speedMax: 100,
+      spread: 0,
+      directionX: 0,
+      directionY: 1, // moving downward
+      gravityY: 0,
+    });
+    stepParticleEmitter(emitter, state, config, 1);
+    // Particle moves down; plane at y=0 (normal pointing up = (0,-1), distance 0)
+    const plane: ParticleCollider = { kind: 'PlaneCollider', nx: 0, ny: -1, distance: 0, restitution: 1, friction: 0 };
+    stepParticleEmitter(emitter, state, config, 1, undefined, [plane]);
+    // Particle should be reflected above y=0
+    const y = emitter.data.transforms[1];
+    expect(y).toBeGreaterThanOrEqual(-1e-4); // at or above plane
+  });
+
+  it('passes callbacks down to updateParticleEmitter', () => {
+    const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+    const state = createParticleEmitterState();
+    const config = createParticleEmitterConfig({ spawnRate: 3, lifetimeMin: 10, lifetimeMax: 10 });
+    let spawnCount = 0;
+    stepParticleEmitter(emitter, state, config, 1, undefined, undefined, { onSpawn: () => spawnCount++ });
+    expect(spawnCount).toBe(3);
+  });
+
+  it('is a no-op for zero deltaTime', () => {
+    const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+    const state = createParticleEmitterState();
+    const config = createParticleEmitterConfig({ spawnRate: 10, lifetimeMin: 10, lifetimeMax: 10 });
+    stepParticleEmitter(emitter, state, config, 0);
+    expect(emitter.data.particleCount).toBe(0);
+  });
+});
+
+describe('stepParticleObjects', () => {
+  it('spawns into dead slots when called with no forces or colliders', () => {
+    const objects = Array.from({ length: 10 }, makeObject);
+    const state = createParticleObjectsState(10);
+    const config = createParticleEmitterConfig({ spawnRate: 5, lifetimeMin: 10, lifetimeMax: 10 });
+    stepParticleObjects(objects, state, config, 1);
+    const visible = objects.filter((o) => o.visible).length;
+    expect(visible).toBe(5);
+  });
+});
+
+function makeObject(): ParticleObject {
+  return {
+    alpha: 1,
+    blendMode: null,
+    colorTransform: null,
+    rotation: 0,
+    scaleX: 1,
+    scaleY: 1,
+    visible: false,
+    x: 0,
+    y: 0,
+  } as unknown as ParticleObject;
+}