@guinetik/gcanvas 1.0.0

package/test/particle/emitter.test.js

@@ -0,0 +1,204 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { ParticleEmitter } from "../../src/particle/emitter";
+import { Particle } from "../../src/particle/particle";
+
+describe("ParticleEmitter", () => {
+  describe("constructor", () => {
+    it("should initialize with default values", () => {
+      const emitter = new ParticleEmitter();
+
+      expect(emitter.rate).toBe(10);
+      expect(emitter.position).toEqual({ x: 0, y: 0, z: 0 });
+      expect(emitter.spread).toEqual({ x: 0, y: 0, z: 0 });
+      expect(emitter.velocity).toEqual({ x: 0, y: 0, z: 0 });
+      expect(emitter.velocitySpread).toEqual({ x: 0, y: 0, z: 0 });
+      expect(emitter.lifetime).toEqual({ min: 1, max: 2 });
+      expect(emitter.size).toEqual({ min: 1, max: 1 });
+      expect(emitter.color).toEqual({ r: 255, g: 255, b: 255, a: 1 });
+      expect(emitter.shape).toBe("circle");
+      expect(emitter.active).toBe(true);
+    });
+
+    it("should accept custom options", () => {
+      const emitter = new ParticleEmitter({
+        rate: 50,
+        position: { x: 100, y: 200 },
+        velocity: { y: -100 },
+        lifetime: { min: 0.5, max: 1.5 },
+        size: { min: 2, max: 5 },
+        color: { r: 255, g: 0, b: 0, a: 0.8 },
+        shape: "square",
+        active: false,
+      });
+
+      expect(emitter.rate).toBe(50);
+      expect(emitter.position).toEqual({ x: 100, y: 200, z: 0 });
+      expect(emitter.velocity).toEqual({ x: 0, y: -100, z: 0 });
+      expect(emitter.lifetime).toEqual({ min: 0.5, max: 1.5 });
+      expect(emitter.size).toEqual({ min: 2, max: 5 });
+      expect(emitter.color).toEqual({ r: 255, g: 0, b: 0, a: 0.8 });
+      expect(emitter.shape).toBe("square");
+      expect(emitter.active).toBe(false);
+    });
+  });
+
+  describe("emit", () => {
+    it("should initialize particle with emitter settings", () => {
+      const emitter = new ParticleEmitter({
+        position: { x: 100, y: 200, z: 50 },
+        velocity: { x: 10, y: -20, z: 5 },
+        lifetime: { min: 2, max: 2 },
+        size: { min: 3, max: 3 },
+        color: { r: 128, g: 64, b: 32, a: 0.5 },
+        shape: "triangle",
+      });
+
+      const p = new Particle();
+      emitter.emit(p);
+
+      expect(p.x).toBe(100);
+      expect(p.y).toBe(200);
+      expect(p.z).toBe(50);
+      expect(p.vx).toBe(10);
+      expect(p.vy).toBe(-20);
+      expect(p.vz).toBe(5);
+      expect(p.lifetime).toBe(2);
+      expect(p.size).toBe(3);
+      expect(p.color).toEqual({ r: 128, g: 64, b: 32, a: 0.5 });
+      expect(p.shape).toBe("triangle");
+      expect(p.age).toBe(0);
+      expect(p.alive).toBe(true);
+    });
+
+    it("should apply position spread", () => {
+      const emitter = new ParticleEmitter({
+        position: { x: 0, y: 0, z: 0 },
+        spread: { x: 100, y: 100, z: 100 },
+      });
+
+      // Mock Math.random to return predictable values
+      const mockRandom = vi.spyOn(Math, "random");
+      mockRandom.mockReturnValue(0.5); // Mid-point = 0 spread
+
+      const p = new Particle();
+      emitter.emit(p);
+
+      // With Math.random() = 0.5, spread = (0.5 - 0.5) * 2 * spread = 0
+      expect(p.x).toBe(0);
+      expect(p.y).toBe(0);
+      expect(p.z).toBe(0);
+
+      mockRandom.mockRestore();
+    });
+
+    it("should apply velocity spread", () => {
+      const emitter = new ParticleEmitter({
+        velocity: { x: 100 },
+        velocitySpread: { x: 50 },
+      });
+
+      const mockRandom = vi.spyOn(Math, "random");
+      mockRandom.mockReturnValue(0); // (0 - 0.5) * 2 * 50 = -50
+
+      const p = new Particle();
+      emitter.emit(p);
+
+      expect(p.vx).toBe(50); // 100 + (-50)
+
+      mockRandom.mockRestore();
+    });
+
+    it("should randomize lifetime within range", () => {
+      const emitter = new ParticleEmitter({
+        lifetime: { min: 1, max: 3 },
+      });
+
+      const mockRandom = vi.spyOn(Math, "random");
+      mockRandom.mockReturnValue(0.5);
+
+      const p = new Particle();
+      emitter.emit(p);
+
+      expect(p.lifetime).toBe(2); // 1 + 0.5 * (3 - 1)
+
+      mockRandom.mockRestore();
+    });
+
+    it("should randomize size within range", () => {
+      const emitter = new ParticleEmitter({
+        size: { min: 2, max: 10 },
+      });
+
+      const mockRandom = vi.spyOn(Math, "random");
+      mockRandom.mockReturnValue(0.25);
+
+      const p = new Particle();
+      emitter.emit(p);
+
+      expect(p.size).toBe(4); // 2 + 0.25 * (10 - 2)
+
+      mockRandom.mockRestore();
+    });
+  });
+
+  describe("update", () => {
+    it("should return 0 when inactive", () => {
+      const emitter = new ParticleEmitter({ rate: 100, active: false });
+
+      expect(emitter.update(1)).toBe(0);
+    });
+
+    it("should return 0 when rate is 0", () => {
+      const emitter = new ParticleEmitter({ rate: 0 });
+
+      expect(emitter.update(1)).toBe(0);
+    });
+
+    it("should emit particles based on rate", () => {
+      const emitter = new ParticleEmitter({ rate: 10 }); // 10 particles/second
+
+      // 0.2 seconds should spawn 2 particles
+      const count = emitter.update(0.2);
+
+      expect(count).toBe(2);
+    });
+
+    it("should accumulate time between frames", () => {
+      const emitter = new ParticleEmitter({ rate: 10 }); // interval = 0.1s
+
+      // First frame: 0.05s (not enough for a particle)
+      expect(emitter.update(0.05)).toBe(0);
+
+      // Second frame: 0.05s more (total 0.1s = 1 particle)
+      expect(emitter.update(0.05)).toBe(1);
+    });
+
+    it("should handle high frame rates correctly", () => {
+      const emitter = new ParticleEmitter({ rate: 60 });
+
+      // One frame at 60fps = ~0.0167s
+      // At 60 particles/second, interval = 0.0167s, so 1 particle per frame
+      let total = 0;
+      for (let i = 0; i < 60; i++) {
+        total += emitter.update(1 / 60);
+      }
+
+      expect(total).toBe(60);
+    });
+  });
+
+  describe("reset", () => {
+    it("should reset the emission timer", () => {
+      const emitter = new ParticleEmitter({ rate: 10 });
+
+      // Accumulate some time
+      emitter.update(0.05);
+      expect(emitter._timer).toBeGreaterThan(0);
+
+      // Reset
+      emitter.reset();
+
+      expect(emitter._timer).toBe(0);
+    });
+  });
+});

package/test/particle/particle-system.test.js

@@ -0,0 +1,310 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { ParticleSystem } from "../../src/particle/particle-system";
+import { ParticleEmitter } from "../../src/particle/emitter";
+import { Updaters } from "../../src/particle/updaters";
+import { Particle } from "../../src/particle/particle";
+
+// Mock the game object
+const createMockGame = () => ({
+  width: 800,
+  height: 600,
+});
+
+describe("ParticleSystem", () => {
+  let mockGame;
+
+  beforeEach(() => {
+    mockGame = createMockGame();
+  });
+
+  describe("constructor", () => {
+    it("should initialize with default values", () => {
+      const system = new ParticleSystem(mockGame);
+
+      expect(system.particles).toEqual([]);
+      expect(system.pool).toEqual([]);
+      expect(system.maxParticles).toBe(5000);
+      expect(system.emitters).toBeInstanceOf(Map);
+      expect(system.emitters.size).toBe(0);
+      expect(system.camera).toBeNull();
+      expect(system.depthSort).toBe(false);
+      expect(system.blendMode).toBe("source-over");
+      expect(system.worldSpace).toBe(false);
+      expect(system.particleCount).toBe(0);
+    });
+
+    it("should accept custom options", () => {
+      const mockCamera = { project: vi.fn() };
+      const system = new ParticleSystem(mockGame, {
+        maxParticles: 1000,
+        camera: mockCamera,
+        depthSort: true,
+        blendMode: "screen",
+        worldSpace: true,
+        updaters: [Updaters.velocity],
+      });
+
+      expect(system.maxParticles).toBe(1000);
+      expect(system.camera).toBe(mockCamera);
+      expect(system.depthSort).toBe(true);
+      expect(system.blendMode).toBe("screen");
+      expect(system.worldSpace).toBe(true);
+      expect(system.updaters).toEqual([Updaters.velocity]);
+    });
+  });
+
+  describe("emitter management", () => {
+    it("should add emitters", () => {
+      const system = new ParticleSystem(mockGame);
+      const emitter = new ParticleEmitter({ rate: 10 });
+
+      system.addEmitter("fire", emitter);
+
+      expect(system.emitters.has("fire")).toBe(true);
+      expect(system.getEmitter("fire")).toBe(emitter);
+    });
+
+    it("should remove emitters", () => {
+      const system = new ParticleSystem(mockGame);
+      const emitter = new ParticleEmitter({ rate: 10 });
+
+      system.addEmitter("fire", emitter);
+      system.removeEmitter("fire");
+
+      expect(system.emitters.has("fire")).toBe(false);
+    });
+
+    it("should return undefined for non-existent emitter", () => {
+      const system = new ParticleSystem(mockGame);
+
+      expect(system.getEmitter("nonexistent")).toBeUndefined();
+    });
+
+    it("should support chaining on addEmitter/removeEmitter", () => {
+      const system = new ParticleSystem(mockGame);
+      const emitter = new ParticleEmitter();
+
+      const result1 = system.addEmitter("test", emitter);
+      const result2 = system.removeEmitter("test");
+
+      expect(result1).toBe(system);
+      expect(result2).toBe(system);
+    });
+  });
+
+  describe("object pooling", () => {
+    it("should acquire particles from pool when available", () => {
+      const system = new ParticleSystem(mockGame);
+
+      // Add particle to pool
+      const pooledParticle = new Particle();
+      system.pool.push(pooledParticle);
+
+      const acquired = system.acquire();
+
+      expect(acquired).toBe(pooledParticle);
+      expect(system.pool.length).toBe(0);
+    });
+
+    it("should create new particle when pool is empty", () => {
+      const system = new ParticleSystem(mockGame);
+
+      const acquired = system.acquire();
+
+      expect(acquired).toBeInstanceOf(Particle);
+    });
+
+    it("should release particles back to pool", () => {
+      const system = new ParticleSystem(mockGame);
+      const particle = new Particle();
+      particle.x = 100;
+      particle.y = 200;
+
+      system.release(particle);
+
+      expect(system.pool.length).toBe(1);
+      expect(system.pool[0]).toBe(particle);
+      // Particle should be reset
+      expect(particle.x).toBe(0);
+      expect(particle.y).toBe(0);
+    });
+  });
+
+  describe("emit", () => {
+    it("should emit particles using emitter", () => {
+      const system = new ParticleSystem(mockGame);
+      const emitter = new ParticleEmitter({
+        position: { x: 100, y: 200 },
+      });
+
+      system.emit(5, emitter);
+
+      expect(system.particles.length).toBe(5);
+      // particleCount is updated after update() call
+    });
+
+    it("should not exceed maxParticles", () => {
+      const system = new ParticleSystem(mockGame, { maxParticles: 3 });
+      const emitter = new ParticleEmitter();
+
+      system.emit(10, emitter);
+
+      expect(system.particles.length).toBe(3);
+    });
+  });
+
+  describe("burst", () => {
+    it("should burst spawn with emitter instance", () => {
+      const system = new ParticleSystem(mockGame);
+      const emitter = new ParticleEmitter();
+
+      system.burst(5, emitter);
+
+      expect(system.particles.length).toBe(5);
+    });
+
+    it("should burst spawn with emitter name", () => {
+      const system = new ParticleSystem(mockGame);
+      const emitter = new ParticleEmitter();
+      system.addEmitter("explosion", emitter);
+
+      system.burst(5, "explosion");
+
+      expect(system.particles.length).toBe(5);
+    });
+
+    it("should do nothing with invalid emitter name", () => {
+      const system = new ParticleSystem(mockGame);
+
+      system.burst(5, "nonexistent");
+
+      expect(system.particles.length).toBe(0);
+    });
+  });
+
+  describe("update", () => {
+    it("should update particles with all updaters", () => {
+      const customUpdater = vi.fn();
+      const system = new ParticleSystem(mockGame, {
+        updaters: [customUpdater],
+      });
+
+      const emitter = new ParticleEmitter({ lifetime: { min: 10, max: 10 } });
+      system.emit(2, emitter);
+
+      system.update(0.016);
+
+      expect(customUpdater).toHaveBeenCalledTimes(2);
+    });
+
+    it("should remove dead particles", () => {
+      const system = new ParticleSystem(mockGame, {
+        updaters: [Updaters.lifetime],
+      });
+
+      const emitter = new ParticleEmitter({
+        lifetime: { min: 0.1, max: 0.1 },
+      });
+      system.emit(3, emitter);
+
+      // Large time step to kill particles
+      system.update(1);
+
+      expect(system.particles.length).toBe(0);
+    });
+
+    it("should return dead particles to pool", () => {
+      const system = new ParticleSystem(mockGame, {
+        updaters: [Updaters.lifetime],
+      });
+
+      const emitter = new ParticleEmitter({
+        lifetime: { min: 0.1, max: 0.1 },
+      });
+      system.emit(3, emitter);
+
+      system.update(1);
+
+      expect(system.pool.length).toBe(3);
+    });
+
+    it("should spawn particles from active emitters", () => {
+      const system = new ParticleSystem(mockGame);
+      const emitter = new ParticleEmitter({
+        rate: 100, // 100 per second
+        lifetime: { min: 10, max: 10 },
+      });
+      system.addEmitter("continuous", emitter);
+
+      system.update(0.1); // 10 particles expected
+
+      expect(system.particles.length).toBe(10);
+    });
+
+    it("should not spawn from inactive emitters", () => {
+      const system = new ParticleSystem(mockGame);
+      const emitter = new ParticleEmitter({
+        rate: 100,
+        active: false,
+      });
+      system.addEmitter("disabled", emitter);
+
+      system.update(0.1);
+
+      expect(system.particles.length).toBe(0);
+    });
+  });
+
+  describe("clear", () => {
+    it("should remove all particles", () => {
+      const system = new ParticleSystem(mockGame);
+      const emitter = new ParticleEmitter();
+      system.emit(10, emitter);
+
+      system.clear();
+
+      expect(system.particles.length).toBe(0);
+      expect(system.particleCount).toBe(0);
+    });
+
+    it("should return particles to pool", () => {
+      const system = new ParticleSystem(mockGame);
+      const emitter = new ParticleEmitter();
+      system.emit(10, emitter);
+
+      system.clear();
+
+      expect(system.pool.length).toBe(10);
+    });
+  });
+
+  describe("stats", () => {
+    it("should track particle count", () => {
+      const system = new ParticleSystem(mockGame);
+      const emitter = new ParticleEmitter({
+        lifetime: { min: 10, max: 10 },
+      });
+
+      expect(system.particleCount).toBe(0);
+
+      system.emit(5, emitter);
+      system.update(0);
+
+      expect(system.particleCount).toBe(5);
+    });
+
+    it("should track pool size", () => {
+      const system = new ParticleSystem(mockGame);
+
+      expect(system.poolSize).toBe(0);
+
+      const emitter = new ParticleEmitter({
+        lifetime: { min: 0.01, max: 0.01 },
+      });
+      system.emit(5, emitter);
+      system.update(1); // Kill all
+
+      expect(system.poolSize).toBe(5);
+    });
+  });
+});

package/test/particle/particle.test.js

@@ -0,0 +1,116 @@
+import { describe, it, expect } from "vitest";
+import { Particle } from "../../src/particle/particle";
+
+describe("Particle", () => {
+  describe("constructor", () => {
+    it("should initialize with default values", () => {
+      const p = new Particle();
+
+      // Position
+      expect(p.x).toBe(0);
+      expect(p.y).toBe(0);
+      expect(p.z).toBe(0);
+
+      // Velocity
+      expect(p.vx).toBe(0);
+      expect(p.vy).toBe(0);
+      expect(p.vz).toBe(0);
+
+      // Appearance
+      expect(p.size).toBe(1);
+      expect(p.color).toEqual({ r: 255, g: 255, b: 255, a: 1 });
+      expect(p.shape).toBe("circle");
+
+      // Lifecycle
+      expect(p.age).toBe(0);
+      expect(p.lifetime).toBe(1);
+      expect(p.alive).toBe(true);
+
+      // Custom data
+      expect(p.custom).toEqual({});
+    });
+  });
+
+  describe("reset", () => {
+    it("should reset all properties to defaults", () => {
+      const p = new Particle();
+
+      // Modify all properties
+      p.x = 100;
+      p.y = 200;
+      p.z = 300;
+      p.vx = 10;
+      p.vy = 20;
+      p.vz = 30;
+      p.size = 5;
+      p.color = { r: 100, g: 50, b: 25, a: 0.5 };
+      p.shape = "square";
+      p.age = 2;
+      p.lifetime = 5;
+      p.alive = false;
+      p.custom.foo = "bar";
+
+      // Reset
+      p.reset();
+
+      // Verify defaults
+      expect(p.x).toBe(0);
+      expect(p.y).toBe(0);
+      expect(p.z).toBe(0);
+      expect(p.vx).toBe(0);
+      expect(p.vy).toBe(0);
+      expect(p.vz).toBe(0);
+      expect(p.size).toBe(1);
+      expect(p.color).toEqual({ r: 255, g: 255, b: 255, a: 1 });
+      expect(p.shape).toBe("circle");
+      expect(p.age).toBe(0);
+      expect(p.lifetime).toBe(1);
+      expect(p.alive).toBe(true);
+      expect(p.custom).toEqual({});
+    });
+
+    it("should clear custom data", () => {
+      const p = new Particle();
+      p.custom.key1 = "value1";
+      p.custom.key2 = "value2";
+
+      p.reset();
+
+      expect(Object.keys(p.custom).length).toBe(0);
+    });
+  });
+
+  describe("progress", () => {
+    it("should calculate progress as age/lifetime", () => {
+      const p = new Particle();
+      p.lifetime = 4;
+      p.age = 1;
+
+      expect(p.progress).toBe(0.25);
+    });
+
+    it("should return 0 at birth", () => {
+      const p = new Particle();
+      p.lifetime = 2;
+      p.age = 0;
+
+      expect(p.progress).toBe(0);
+    });
+
+    it("should return 1 at death", () => {
+      const p = new Particle();
+      p.lifetime = 2;
+      p.age = 2;
+
+      expect(p.progress).toBe(1);
+    });
+
+    it("should handle zero lifetime", () => {
+      const p = new Particle();
+      p.lifetime = 0;
+      p.age = 0;
+
+      expect(p.progress).toBe(1);
+    });
+  });
+});