@flighthq/particles 0.1.0

package/dist/validateParticleEmitterConfig.js

@@ -0,0 +1,206 @@
+import { createParticleEmitterConfig } from './particleEmitterConfig';
+// Every numeric field of ParticleEmitterConfig. Kept as a typed tuple so the
+// validate/sanitize passes can iterate without missing a field as the config grows.
+const NUMERIC_FIELDS = [
+    'alphaEnd',
+    'alphaStart',
+    'burstCount',
+    'burstInterval',
+    'duration',
+    'colorEndB',
+    'colorEndG',
+    'colorEndR',
+    'colorEndVarianceB',
+    'colorEndVarianceG',
+    'colorEndVarianceR',
+    'colorStartB',
+    'colorStartG',
+    'colorStartR',
+    'colorStartVarianceB',
+    'colorStartVarianceG',
+    'colorStartVarianceR',
+    'directionX',
+    'directionY',
+    'emitterHeight',
+    'emitterRadius',
+    'emitterWidth',
+    'frameCount',
+    'frameRate',
+    'gravityX',
+    'gravityY',
+    'lifetimeMax',
+    'lifetimeMin',
+    'maxParticles',
+    'regionIdMax',
+    'regionIdMin',
+    'rotationSpeedMax',
+    'rotationSpeedMin',
+    'scaleEnd',
+    'scaleMax',
+    'scaleMin',
+    'speedMax',
+    'speedMin',
+    'spawnRate',
+    'spread',
+    'velocityInheritance',
+];
+// Fields that must never be negative — a negative value is either meaningless
+// (a count, a rate, a duration) or actively breaks the simulation.
+const NON_NEGATIVE_FIELDS = [
+    'burstCount',
+    'burstInterval',
+    'duration',
+    'emitterHeight',
+    'emitterRadius',
+    'emitterWidth',
+    'frameRate',
+    'lifetimeMin',
+    'lifetimeMax',
+    'maxParticles',
+    'scaleMax',
+    'scaleMin',
+    'speedMax',
+    'speedMin',
+    'spawnRate',
+];
+/** Return a copy of the config with every value coerced to something the
+ *  simulation can run safely: non-finite numbers fall back to their defaults,
+ *  negative counts/rates/sizes are clamped to 0, integer fields are floored, and
+ *  `frameCount` is forced to >= 1. Range inversions (e.g. lifetimeMin > max) are
+ *  left intact since they simulate correctly — use {@link validateParticleEmitterConfig}
+ *  to surface those to the author. Safe to call on partial input. */
+export function normalizeParticleEmitterConfig(config) {
+    const out = createParticleEmitterConfig(config);
+    const defaults = createParticleEmitterConfig();
+    // Replace any non-finite numeric field with its canonical default.
+    const mutable = out;
+    const defaultsRec = defaults;
+    for (const field of NUMERIC_FIELDS) {
+        if (!Number.isFinite(mutable[field]))
+            mutable[field] = defaultsRec[field];
+    }
+    return {
+        ...out,
+        // Drop any curve that is empty or contains a non-finite sample so it can never
+        // inject NaN — the simulation falls back to its linear interpolation path.
+        alphaCurve: isFiniteCurve(out.alphaCurve) ? out.alphaCurve : null,
+        colorCurve: isFiniteCurve(out.colorCurve) ? out.colorCurve : null,
+        scaleCurve: isFiniteCurve(out.scaleCurve) ? out.scaleCurve : null,
+        maxParticles: Math.max(0, Math.floor(out.maxParticles)),
+        burstCount: Math.max(0, Math.floor(out.burstCount)),
+        burstInterval: Math.max(0, out.burstInterval),
+        duration: Math.max(0, out.duration),
+        frameCount: Math.max(1, Math.floor(out.frameCount)),
+        frameRate: Math.max(0, out.frameRate),
+        regionIdMin: Math.max(0, Math.floor(out.regionIdMin)),
+        regionIdMax: Math.max(Math.max(0, Math.floor(out.regionIdMin)), Math.floor(out.regionIdMax)),
+        spawnRate: Math.max(0, out.spawnRate),
+        lifetimeMin: Math.max(0, out.lifetimeMin),
+        lifetimeMax: Math.max(0, out.lifetimeMax),
+        speedMin: Math.max(0, out.speedMin),
+        speedMax: Math.max(0, out.speedMax),
+        scaleMin: Math.max(0, out.scaleMin),
+        scaleMax: Math.max(0, out.scaleMax),
+        emitterRadius: Math.max(0, out.emitterRadius),
+        emitterWidth: Math.max(0, out.emitterWidth),
+        emitterHeight: Math.max(0, out.emitterHeight),
+    };
+}
+/** Report problems in a particle config without modifying it — for asset-import
+ *  validation, editor inspectors, or CI checks on authored effects. Returns an
+ *  empty array for a clean config. Use {@link normalizeParticleEmitterConfig} to
+ *  get a corrected config for safe runtime use. */
+export function validateParticleEmitterConfig(config) {
+    const issues = [];
+    for (const field of NUMERIC_FIELDS) {
+        const value = config[field];
+        if (!Number.isFinite(value)) {
+            issues.push({ field, message: `${field} must be a finite number (got ${String(value)})`, severity: 'error' });
+        }
+    }
+    for (const field of NON_NEGATIVE_FIELDS) {
+        const value = config[field];
+        if (Number.isFinite(value) && value < 0) {
+            issues.push({ field, message: `${field} must not be negative (got ${value})`, severity: 'warning' });
+        }
+    }
+    // A non-positive maximum lifetime means particles die the frame they spawn.
+    if (Number.isFinite(config.lifetimeMax) && config.lifetimeMax <= 0) {
+        issues.push({
+            field: 'lifetimeMax',
+            message: 'lifetimeMax must be > 0 or particles die instantly',
+            severity: 'warning',
+        });
+    }
+    // A non-positive cap means the emitter can never hold a particle.
+    if (Number.isFinite(config.maxParticles) && config.maxParticles <= 0) {
+        issues.push({
+            field: 'maxParticles',
+            message: 'maxParticles must be >= 1 or nothing ever spawns',
+            severity: 'warning',
+        });
+    }
+    if (Number.isFinite(config.frameCount) && config.frameCount < 1) {
+        issues.push({ field: 'frameCount', message: 'frameCount must be >= 1', severity: 'warning' });
+    }
+    // Inverted min/max ranges still simulate (the spawn interpolation handles a > b)
+    // but almost always indicate an authoring mistake.
+    reportInvertedRange(issues, config, 'lifetimeMin', 'lifetimeMax');
+    reportInvertedRange(issues, config, 'speedMin', 'speedMax');
+    reportInvertedRange(issues, config, 'scaleMin', 'scaleMax');
+    reportInvertedRange(issues, config, 'rotationSpeedMin', 'rotationSpeedMax');
+    reportUnitRange(issues, config, 'alphaStart');
+    reportUnitRange(issues, config, 'alphaEnd');
+    reportCurve(issues, config.alphaCurve, 'alphaCurve', 1);
+    reportCurve(issues, config.colorCurve, 'colorCurve', 3);
+    reportCurve(issues, config.scaleCurve, 'scaleCurve', 1);
+    return issues;
+}
+function isFiniteCurve(curve) {
+    if (curve == null || curve.length === 0)
+        return false;
+    for (let i = 0; i < curve.length; i++) {
+        if (!Number.isFinite(curve[i]))
+            return false;
+    }
+    return true;
+}
+function reportCurve(issues, curve, field, stride) {
+    if (curve == null)
+        return;
+    if (curve.length === 0) {
+        issues.push({ field, message: `${field} is empty and will be ignored`, severity: 'warning' });
+        return;
+    }
+    if (curve.length % stride !== 0) {
+        issues.push({
+            field,
+            message: `${field} length (${curve.length}) is not a multiple of ${stride}`,
+            severity: 'warning',
+        });
+    }
+    for (let i = 0; i < curve.length; i++) {
+        if (!Number.isFinite(curve[i])) {
+            issues.push({ field, message: `${field} contains a non-finite sample at index ${i}`, severity: 'error' });
+            break;
+        }
+    }
+}
+function reportInvertedRange(issues, config, minField, maxField) {
+    const min = config[minField];
+    const max = config[maxField];
+    if (Number.isFinite(min) && Number.isFinite(max) && min > max) {
+        issues.push({
+            field: minField,
+            message: `${minField} (${min}) is greater than ${maxField} (${max})`,
+            severity: 'warning',
+        });
+    }
+}
+function reportUnitRange(issues, config, field) {
+    const value = config[field];
+    if (Number.isFinite(value) && (value < 0 || value > 1)) {
+        issues.push({ field, message: `${field} (${value}) is outside the expected 0–1 range`, severity: 'warning' });
+    }
+}
+//# sourceMappingURL=validateParticleEmitterConfig.js.map

package/dist/validateParticleEmitterConfig.js.map

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

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@flighthq/particles",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/geometry": "0.1.0",
+    "@flighthq/math": "0.1.0",
+    "@flighthq/node": "0.1.0",
+    "@flighthq/signals": "0.1.0",
+    "@flighthq/sprite": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Particle system: emitter simulation and typed-array-backed particle primitives",
+  "sideEffects": false
+}

package/src/applyParticleCollisions.test.ts

@@ -0,0 +1,191 @@
+import { createParticleEmitter } from '@flighthq/sprite';
+import type { TextureAtlas } from '@flighthq/types';
+
+import { applyParticleCollisions, applyParticleObjectCollisions } from './applyParticleCollisions';
+import { createParticleEmitterConfig } from './particleEmitterConfig';
+import { createParticleEmitterState } from './particleEmitterState';
+import { createParticleObjectsState } from './particleObjectsState';
+import { updateParticleEmitter } from './updateParticleEmitter';
+import type { ParticleObject } from './updateParticleObjects';
+
+function makeAtlas(): TextureAtlas {
+  return {
+    image: null,
+    regions: [{ id: 0, x: 0, y: 0, width: 32, height: 32, pivotX: null, pivotY: null }],
+  } as TextureAtlas;
+}
+
+// Spawn one particle, then place it at a known position with a known velocity.
+function place(px: number, py: number, vx: number, vy: number) {
+  const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+  const state = createParticleEmitterState();
+  const config = createParticleEmitterConfig({
+    spawnRate: 1,
+    lifetimeMin: 100,
+    lifetimeMax: 100,
+    speedMin: 0,
+    speedMax: 0,
+  });
+  updateParticleEmitter(emitter, state, config, 1);
+  emitter.data.transforms[0] = px;
+  emitter.data.transforms[1] = py;
+  state.velocities[0] = vx;
+  state.velocities[1] = vy;
+  return { emitter, state };
+}
+
+describe('applyParticleCollisions', () => {
+  describe('circle', () => {
+    it('exclude mode keeps a particle outside the disc', () => {
+      const { emitter, state } = place(5, 0, -10, 0); // inside radius-10 disc at origin, moving inward
+      applyParticleCollisions(emitter, state, [
+        { kind: 'CircleCollider', x: 0, y: 0, radius: 10, mode: 'exclude', restitution: 1 },
+      ]);
+      const d = Math.hypot(emitter.data.transforms[0], emitter.data.transforms[1]);
+      expect(d).toBeCloseTo(10); // pushed to the surface
+      expect(state.velocities[0]).toBeCloseTo(10); // bounced outward
+    });
+
+    it('contain mode keeps a particle inside the boundary', () => {
+      const { emitter, state } = place(20, 0, 10, 0); // outside radius-10 boundary, moving further out
+      applyParticleCollisions(emitter, state, [{ kind: 'CircleCollider', x: 0, y: 0, radius: 10, mode: 'contain' }]);
+      const d = Math.hypot(emitter.data.transforms[0], emitter.data.transforms[1]);
+      expect(d).toBeCloseTo(10);
+    });
+  });
+
+  describe('integration', () => {
+    it('settles a falling particle onto a floor over multiple frames', () => {
+      const { emitter, state } = place(0, 480, 0, 0);
+      const config = createParticleEmitterConfig({ spawnRate: 0, lifetimeMin: 100, lifetimeMax: 100, gravityY: 2000 });
+      const floor = [{ kind: 'PlaneCollider' as const, nx: 0, ny: -1, distance: -500 }];
+      for (let i = 0; i < 60; i++) {
+        updateParticleEmitter(emitter, state, config, 1 / 60);
+        applyParticleCollisions(emitter, state, floor);
+      }
+      expect(emitter.data.transforms[1]).toBeLessThanOrEqual(500 + 1e-3); // never falls through
+      expect(emitter.data.transforms[1]).toBeCloseTo(500, 0); // resting on the floor
+    });
+
+    it('is a no-op with no colliders', () => {
+      const { emitter, state } = place(0, 520, 0, 100);
+      applyParticleCollisions(emitter, state, []);
+      expect(emitter.data.transforms[1]).toBe(520);
+    });
+  });
+
+  describe('plane (floor)', () => {
+    it('pushes a penetrating particle back to the surface and stops it (restitution 0)', () => {
+      // Floor at y = 500, valid region is y <= 500 (normal points up = -y).
+      const { emitter, state } = place(0, 520, 0, 100); // 20px below floor, moving down
+      applyParticleCollisions(emitter, state, [{ kind: 'PlaneCollider', nx: 0, ny: -1, distance: -500 }]);
+      expect(emitter.data.transforms[1]).toBeCloseTo(500); // snapped to surface
+      expect(state.velocities[1]).toBeCloseTo(0); // normal velocity killed
+    });
+
+    it('bounces with restitution', () => {
+      const { emitter, state } = place(0, 520, 0, 100);
+      applyParticleCollisions(emitter, state, [
+        { kind: 'PlaneCollider', nx: 0, ny: -1, distance: -500, restitution: 0.5 },
+      ]);
+      expect(state.velocities[1]).toBeCloseTo(-50); // 100 down → 50 up
+    });
+
+    it('applies friction to the tangential component', () => {
+      const { emitter, state } = place(0, 520, 80, 100);
+      applyParticleCollisions(emitter, state, [
+        { kind: 'PlaneCollider', nx: 0, ny: -1, distance: -500, friction: 0.25 },
+      ]);
+      expect(state.velocities[0]).toBeCloseTo(60); // 80 * (1 - 0.25)
+    });
+
+    it('leaves particles above the floor untouched', () => {
+      const { emitter, state } = place(0, 100, 0, 100);
+      applyParticleCollisions(emitter, state, [{ kind: 'PlaneCollider', nx: 0, ny: -1, distance: -500 }]);
+      expect(emitter.data.transforms[1]).toBe(100);
+      expect(state.velocities[1]).toBe(100);
+    });
+  });
+
+  describe('rect', () => {
+    it('contain mode clamps particles to the bounds and reflects velocity', () => {
+      // Box centered (0,0), 100×100 → bounds ±50.
+      const { emitter, state } = place(80, 0, 30, 0);
+      applyParticleCollisions(emitter, state, [
+        { kind: 'RectangleCollider', x: 0, y: 0, width: 100, height: 100, mode: 'contain', restitution: 1 },
+      ]);
+      expect(emitter.data.transforms[0]).toBeCloseTo(50);
+      expect(state.velocities[0]).toBeCloseTo(-30);
+    });
+
+    it('exclude mode pushes a particle out of a solid box along the shallowest axis', () => {
+      // Particle just inside the right edge of a box centered (0,0), 100×100.
+      const { emitter, state } = place(40, 0, 0, 0);
+      applyParticleCollisions(emitter, state, [
+        { kind: 'RectangleCollider', x: 0, y: 0, width: 100, height: 100, mode: 'exclude' },
+      ]);
+      expect(emitter.data.transforms[0]).toBeCloseTo(50); // pushed out the near (right) edge
+    });
+  });
+});
+
+function makeObject(): ParticleObject {
+  return {
+    alpha: 1,
+    blendMode: null,
+    colorTransform: null,
+    rotation: 0,
+    scaleX: 1,
+    scaleY: 1,
+    visible: true,
+    x: 0,
+    y: 0,
+  } as unknown as ParticleObject;
+}
+
+// Build an object-pool collision scenario: a single live object at (px,py) with
+// velocity (vx,vy) in slot 0; slot 1 is left dead.
+function placeObject(px: number, py: number, vx: number, vy: number) {
+  const objects = [makeObject(), makeObject()];
+  const state = createParticleObjectsState(2);
+  state.lifetimes[1] = 0; // slot 0 age
+  state.lifetimes[1 * 2 + 1] = 0; // slot 1 maxAge = 0 → dead
+  state.lifetimes[0 * 2 + 1] = 100; // slot 0 maxAge > 0 → alive
+  objects[0].x = px;
+  objects[0].y = py;
+  state.velocities[0] = vx;
+  state.velocities[1] = vy;
+  return { objects, state };
+}
+
+describe('applyParticleObjectCollisions', () => {
+  it('pushes a live object back onto a floor plane and kills its normal velocity', () => {
+    const { objects, state } = placeObject(0, 520, 0, 100); // below floor y=500, moving down
+    applyParticleObjectCollisions(objects, state, [{ kind: 'PlaneCollider', nx: 0, ny: -1, distance: -500 }]);
+    expect(objects[0].y).toBeCloseTo(500); // snapped to surface
+    expect(state.velocities[1]).toBeCloseTo(0); // normal velocity killed
+  });
+
+  it('bounces a live object with restitution', () => {
+    const { objects, state } = placeObject(0, 520, 0, 100);
+    applyParticleObjectCollisions(objects, state, [
+      { kind: 'PlaneCollider', nx: 0, ny: -1, distance: -500, restitution: 0.5 },
+    ]);
+    expect(state.velocities[1]).toBeCloseTo(-50); // 100 down → 50 up
+  });
+
+  it('skips dead slots', () => {
+    const { objects, state } = placeObject(0, 100, 0, 0); // slot 0 above the floor → untouched
+    objects[1].x = 0;
+    objects[1].y = 520; // dead slot 1 is below the floor but must be ignored
+    applyParticleObjectCollisions(objects, state, [{ kind: 'PlaneCollider', nx: 0, ny: -1, distance: -500 }]);
+    expect(objects[1].y).toBe(520); // dead object left where it was
+  });
+
+  it('is a no-op with no colliders', () => {
+    const { objects, state } = placeObject(0, 520, 0, 100);
+    applyParticleObjectCollisions(objects, state, []);
+    expect(objects[0].y).toBe(520);
+    expect(state.velocities[1]).toBe(100);
+  });
+});

package/src/applyParticleForces.test.ts

@@ -0,0 +1,174 @@
+import { createParticleEmitter } from '@flighthq/sprite';
+import type { TextureAtlas } from '@flighthq/types';
+
+import { applyParticleForces, applyParticleObjectForces } from './applyParticleForces';
+import { createParticleEmitterConfig } from './particleEmitterConfig';
+import { createParticleEmitterState } from './particleEmitterState';
+import { createParticleObjectsState } from './particleObjectsState';
+import { updateParticleEmitter } from './updateParticleEmitter';
+import type { ParticleObject } from './updateParticleObjects';
+import { updateParticleObjects } from './updateParticleObjects';
+
+function makeAtlas(): TextureAtlas {
+  return {
+    image: null,
+    regions: [{ id: 0, x: 0, y: 0, width: 32, height: 32, pivotX: null, pivotY: null }],
+  } as TextureAtlas;
+}
+
+// Spawn a single stationary particle at the origin and return its handles.
+function oneParticle() {
+  const emitter = createParticleEmitter({ data: { atlas: makeAtlas() } });
+  const state = createParticleEmitterState();
+  const config = createParticleEmitterConfig({
+    spawnRate: 1,
+    lifetimeMin: 100,
+    lifetimeMax: 100,
+    speedMin: 0,
+    speedMax: 0,
+  });
+  updateParticleEmitter(emitter, state, config, 1);
+  return { emitter, state };
+}
+
+describe('applyParticleForces', () => {
+  it('attractor pulls velocity toward the point', () => {
+    const { emitter, state } = oneParticle();
+    emitter.data.transforms[0] = 0;
+    emitter.data.transforms[1] = 0;
+    applyParticleForces(emitter, state, [{ kind: 'AttractorForce', x: 100, y: 0, strength: 50 }], 1);
+    expect(state.velocities[0]).toBeCloseTo(50); // accelerated +x toward (100,0)
+    expect(state.velocities[1]).toBeCloseTo(0);
+  });
+
+  it('negative-strength attractor repels', () => {
+    const { emitter, state } = oneParticle();
+    applyParticleForces(emitter, state, [{ kind: 'AttractorForce', x: 100, y: 0, strength: -50 }], 1);
+    expect(state.velocities[0]).toBeLessThan(0);
+  });
+
+  it('radius acts as a hard cutoff', () => {
+    const { emitter, state } = oneParticle();
+    emitter.data.transforms[0] = 0;
+    emitter.data.transforms[1] = 0;
+    state.velocities[0] = 42; // known baseline; an out-of-range force must not change it
+    state.velocities[1] = 7;
+    applyParticleForces(emitter, state, [{ kind: 'AttractorForce', x: 1000, y: 0, strength: 50, radius: 50 }], 1);
+    expect(state.velocities[0]).toBe(42); // 1000 px away, outside 50px radius
+    expect(state.velocities[1]).toBe(7);
+  });
+
+  it('vortex applies tangential velocity', () => {
+    const { emitter, state } = oneParticle();
+    emitter.data.transforms[0] = 10;
+    emitter.data.transforms[1] = 0;
+    applyParticleForces(emitter, state, [{ kind: 'VortexForce', x: 0, y: 0, strength: 20 }], 1);
+    expect(state.velocities[0]).toBeCloseTo(0);
+    expect(state.velocities[1]).toBeCloseTo(20); // perpendicular swirl
+  });
+
+  it('drag reduces existing velocity', () => {
+    const { emitter, state } = oneParticle();
+    state.velocities[0] = 100;
+    state.velocities[1] = 0;
+    applyParticleForces(emitter, state, [{ kind: 'DragForce', strength: 0.5 }], 1);
+    expect(state.velocities[0]).toBeCloseTo(50); // 100 - 0.5*100
+  });
+
+  it('wind adds constant acceleration', () => {
+    const { emitter, state } = oneParticle();
+    applyParticleForces(emitter, state, [{ kind: 'WindForce', x: 5, y: -3 }], 2);
+    expect(state.velocities[0]).toBeCloseTo(10); // 5 * deltaTime(2)
+    expect(state.velocities[1]).toBeCloseTo(-6);
+  });
+
+  it('turbulence is finite and deterministic for a given position', () => {
+    const a = oneParticle();
+    a.emitter.data.transforms[0] = 12.5;
+    a.emitter.data.transforms[1] = -7.5;
+    applyParticleForces(a.emitter, a.state, [{ kind: 'TurbulenceForce', strength: 100, scale: 0.1 }], 1);
+    const b = oneParticle();
+    b.emitter.data.transforms[0] = 12.5;
+    b.emitter.data.transforms[1] = -7.5;
+    applyParticleForces(b.emitter, b.state, [{ kind: 'TurbulenceForce', strength: 100, scale: 0.1 }], 1);
+    expect(Number.isFinite(a.state.velocities[0])).toBe(true);
+    expect(a.state.velocities[0]).toBe(b.state.velocities[0]); // deterministic
+    expect(a.state.velocities[1]).toBe(b.state.velocities[1]);
+  });
+
+  it('composes multiple forces additively', () => {
+    const { emitter, state } = oneParticle();
+    applyParticleForces(
+      emitter,
+      state,
+      [
+        { kind: 'WindForce', x: 10, y: 0 },
+        { kind: 'WindForce', x: 5, y: 0 },
+      ],
+      1,
+    );
+    expect(state.velocities[0]).toBeCloseTo(15);
+  });
+
+  it('is a no-op for an empty force list or zero deltaTime', () => {
+    const { emitter, state } = oneParticle();
+    state.velocities[0] = 42;
+    applyParticleForces(emitter, state, [], 1);
+    applyParticleForces(emitter, state, [{ kind: 'WindForce', x: 5, y: 0 }], 0);
+    expect(state.velocities[0]).toBe(42); // unchanged by either no-op call
+  });
+
+  it('integrates with the core update so attractors curve trajectories', () => {
+    const { emitter, state } = oneParticle();
+    const config = createParticleEmitterConfig({
+      spawnRate: 0,
+      speedMin: 0,
+      speedMax: 0,
+      lifetimeMin: 100,
+      lifetimeMax: 100,
+    });
+    const forces = [{ kind: 'AttractorForce' as const, x: 100, y: 0, strength: 200 }];
+    const startX = emitter.data.transforms[0];
+    for (let i = 0; i < 10; i++) {
+      applyParticleForces(emitter, state, forces, 1 / 60);
+      updateParticleEmitter(emitter, state, config, 1 / 60);
+    }
+    expect(emitter.data.transforms[0]).toBeGreaterThan(startX); // drifted toward the attractor
+  });
+});
+
+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;
+}
+
+describe('applyParticleObjectForces', () => {
+  it('applies forces only to live objects', () => {
+    const objects = [makeObject(), makeObject()];
+    const state = createParticleObjectsState(2);
+    const config = createParticleEmitterConfig({
+      spawnRate: 1,
+      lifetimeMin: 100,
+      lifetimeMax: 100,
+      speedMin: 0,
+      speedMax: 0,
+    });
+    updateParticleObjects(objects, state, config, 1); // spawn exactly one (spawnRate*deltaTime = 1)
+    const liveIndex = objects.findIndex((o) => o.visible);
+    const deadIndex = liveIndex === 0 ? 1 : 0;
+    objects[liveIndex].x = 0;
+    objects[liveIndex].y = 0;
+    applyParticleObjectForces(objects, state, [{ kind: 'WindForce', x: 7, y: 0 }], 1);
+    expect(state.velocities[liveIndex * 2]).toBeCloseTo(7);
+    expect(state.velocities[deadIndex * 2]).toBe(0); // dead slot untouched
+  });
+});