@flighthq/particles 0.1.0 → 0.2.0

package/src/deterministic.test.ts

@@ -1,54 +0,0 @@
-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

@@ -1,103 +0,0 @@
-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/prewarmParticleEmitter.test.ts

@@ -1,68 +0,0 @@
-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

@@ -1,113 +0,0 @@
-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;
-}