@mar7th/firework 1.0.0

package/src/core/FireworksSimulator.js

@@ -0,0 +1,439 @@
+import { builtInPresets, defaultConfig, sanitizeConfig } from "../config/defaults.js";
+import { EventBus } from "../utils/eventBus.js";
+import { random } from "../utils/math.js";
+import { BackgroundManager } from "../effects/BackgroundManager.js";
+import { FireworkFactory } from "./Firework.js";
+import { ParticleSystem } from "./ParticleSystem.js";
+import { Renderer } from "./Renderer.js";
+
+export class FireworksSimulator {
+  constructor(options = {}) {
+    const canvas = resolveCanvas(options.canvasId ?? options.canvas);
+    if (!canvas) {
+      throw new Error("FireworksSimulator requires a valid canvas or canvasId.");
+    }
+
+    this.canvas = canvas;
+    this.prefersReducedMotion =
+      options.prefersReducedMotion ??
+      window.matchMedia?.("(prefers-reduced-motion: reduce)")?.matches ??
+      false;
+    this.initialConfig = this.createInitialConfig(options.config);
+    this.config = { ...this.initialConfig };
+    this.eventBus = options.eventBus ?? new EventBus();
+    this.onConfigChange = options.onConfigChange ?? (() => {});
+    this.onFpsChange = options.onFpsChange ?? (() => {});
+    this.onLowFps = options.onLowFps ?? (() => {});
+    this.advancedMode = Boolean(options.advancedMode);
+    this.createParticles = typeof options.createParticles === "function" ? options.createParticles : null;
+
+    this.backgroundManager = new BackgroundManager();
+    this.renderer = new Renderer(canvas, this.backgroundManager);
+    this.fireworkFactory = new FireworkFactory(() => this.config);
+    this.particleSystem = new ParticleSystem(this.fireworkFactory);
+    this.shells = [];
+
+    this.paused = false;
+    this.destroyed = false;
+    this.lastTime = performance.now();
+    this.autoTimer = 0;
+    this.fpsFrames = 0;
+    this.fpsElapsed = 0;
+    this.lowFpsTime = 0;
+    this.warnedAboutPerformance = false;
+
+    this.handlePointerDown = this.handlePointerDown.bind(this);
+    this.handleKeyDown = this.handleKeyDown.bind(this);
+    this.handleResize = this.resize.bind(this);
+    this.handleVisibilityChange = this.handleVisibilityChange.bind(this);
+    this.animate = this.animate.bind(this);
+
+    if (options.clickToLaunch !== false) {
+      this.canvas.addEventListener("pointerdown", this.handlePointerDown);
+    }
+    if (options.keyboard !== false) {
+      this.canvas.addEventListener("keydown", this.handleKeyDown);
+    }
+    if (options.autoResize !== false) {
+      window.addEventListener("resize", this.handleResize);
+    }
+    if (options.pauseOnHidden !== false) {
+      document.addEventListener("visibilitychange", this.handleVisibilityChange);
+    }
+
+    this.resize();
+    this.renderer.clearFrame(this.config, true);
+
+    if (options.initialLaunch !== false) {
+      window.setTimeout(() => {
+        if (this.destroyed) return;
+        this.launch(this.renderer.width * 0.34, this.renderer.height * 0.42);
+        this.launch(this.renderer.width * 0.62, this.renderer.height * 0.34);
+      }, 300);
+    }
+
+    this.animationId = requestAnimationFrame(this.animate);
+  }
+
+  createInitialConfig(config = {}) {
+    const nextConfig = {
+      ...defaultConfig,
+      ...(this.prefersReducedMotion
+        ? {
+            particleCount: 70,
+            initialSpeedMin: 1.4,
+            initialSpeedMax: 4.2,
+            autoLaunch: false,
+            enableTrails: false
+          }
+        : {}),
+      ...config
+    };
+    this.normalizeAutoLaunchIntervalPriority(nextConfig, config);
+    return sanitizeConfig(nextConfig);
+  }
+
+  getConfig() {
+    return { ...this.config };
+  }
+
+  setConfig(partialConfig = {}) {
+    const nextConfig = { ...this.config, ...partialConfig };
+    this.normalizeAutoLaunchIntervalPriority(nextConfig, partialConfig);
+    this.config = sanitizeConfig(nextConfig);
+    this.notifyConfigChange();
+    this.renderer.clearFrame(this.config, true);
+    return this.getConfig();
+  }
+
+  selectPreset(presetId) {
+    if (presetId === "default") {
+      return this.setConfig(defaultConfig);
+    }
+
+    const normalizedId = presetId?.startsWith?.("builtin:")
+      ? presetId.replace("builtin:", "")
+      : presetId;
+    const preset = builtInPresets[normalizedId];
+    if (!preset) {
+      throw new Error(`Unknown preset: ${presetId}`);
+    }
+
+    return this.setConfig({ ...defaultConfig, ...preset.config });
+  }
+
+  resetConfig(nextInitialConfig) {
+    if (nextInitialConfig) {
+      this.initialConfig = this.createInitialConfig(nextInitialConfig);
+    }
+    this.config = { ...this.initialConfig };
+    this.clearParticles();
+    this.autoTimer = 0;
+    this.warnedAboutPerformance = false;
+    this.notifyConfigChange();
+    this.renderer.clearFrame(this.config, true);
+    return this.getConfig();
+  }
+
+  startAutoPlay(interval) {
+    const nextConfig = { autoLaunch: true };
+    if (Number.isFinite(Number(interval))) {
+      Object.assign(nextConfig, this.normalizeAutoPlayIntervalInput(interval));
+    }
+    return this.setConfig(nextConfig);
+  }
+
+  stopAutoPlay() {
+    return this.setConfig({ autoLaunch: false });
+  }
+
+  setAutoPlay(enabled, interval) {
+    return enabled ? this.startAutoPlay(interval) : this.stopAutoPlay();
+  }
+
+  setAdvancedMode(enabled, createParticles) {
+    this.advancedMode = Boolean(enabled);
+    if (typeof createParticles === "function") {
+      this.createParticles = createParticles;
+    }
+  }
+
+  setParticleCreator(createParticles) {
+    this.createParticles = typeof createParticles === "function" ? createParticles : null;
+  }
+
+  clearParticles() {
+    this.particleSystem.clear();
+    this.shells.length = 0;
+    this.renderer.clearFrame(this.config, true);
+  }
+
+  launch(x, y, options = {}) {
+    const withShell = options.withShell ?? this.config.showLaunchTrail;
+    this.launchAt(x, y, withShell);
+  }
+
+  launchRandom() {
+    const x = random(this.renderer.width * 0.16, this.renderer.width * 0.84);
+    const y = random(this.renderer.height * 0.16, this.renderer.height * 0.62);
+    this.launchAt(x, y, this.config.showLaunchTrail);
+  }
+
+  pause() {
+    this.paused = true;
+  }
+
+  resume() {
+    this.paused = false;
+    this.lastTime = performance.now();
+  }
+
+  togglePause() {
+    if (this.paused) this.resume();
+    else this.pause();
+    return this.paused;
+  }
+
+  resize() {
+    this.renderer.resize();
+    this.renderer.clearFrame(this.config, true);
+  }
+
+  setBackgroundImage(file, onDone, onError) {
+    this.backgroundManager.setImage(
+      file,
+      () => {
+        this.setConfig({ backgroundType: "image" });
+        onDone?.();
+      },
+      onError
+    );
+  }
+
+  destroy() {
+    this.destroyed = true;
+    cancelAnimationFrame(this.animationId);
+    this.canvas.removeEventListener("pointerdown", this.handlePointerDown);
+    this.canvas.removeEventListener("keydown", this.handleKeyDown);
+    window.removeEventListener("resize", this.handleResize);
+    document.removeEventListener("visibilitychange", this.handleVisibilityChange);
+  }
+
+  on(event, callback) {
+    return this.eventBus.on(event, callback);
+  }
+
+  launchAt(x, y, withShell = true) {
+    if (withShell && this.config.showLaunchTrail) {
+      this.shells.push(this.fireworkFactory.createLaunch(x, this.renderer.height + 16, x, y));
+      return;
+    }
+    this.particleSystem.addExplosion(this.createExplosionParticles(x, y));
+  }
+
+  createExplosionParticles(x, y) {
+    if (!this.advancedMode || !this.createParticles) {
+      return this.fireworkFactory.createExplosion(x, y);
+    }
+
+    const { particles, scopedConfig } = this.parseAdvancedResult(this.createParticles(this.getCanvasData(x, y)));
+    if (!Array.isArray(particles)) {
+      return [];
+    }
+
+    return particles.map((particle) => this.normalizeParticle(particle, x, y, scopedConfig));
+  }
+
+  parseAdvancedResult(result) {
+    if (Array.isArray(result)) {
+      return {
+        particles: result,
+        scopedConfig: null
+      };
+    }
+
+    if (result && typeof result === "object" && Array.isArray(result.particles)) {
+      return {
+        particles: result.particles,
+        scopedConfig: result.config ? sanitizeConfig({ ...this.config, ...result.config }) : null
+      };
+    }
+
+    return {
+      particles: [],
+      scopedConfig: null
+    };
+  }
+
+  getCanvasData(x, y) {
+    return {
+      canvas: this.canvas,
+      ctx: this.renderer.ctx,
+      x,
+      y,
+      width: this.renderer.width,
+      height: this.renderer.height,
+      pixelRatio: this.renderer.pixelRatio,
+      config: this.getConfig(),
+      random
+    };
+  }
+
+  normalizeParticle(particle, x, y, scopedConfig = null) {
+    const fallbackConfig = scopedConfig || this.config;
+    const secondaryBurstConfig =
+      particle.secondaryBurstConfig && typeof particle.secondaryBurstConfig === "object"
+        ? this.normalizeSecondaryBurstConfig(particle.secondaryBurstConfig, fallbackConfig)
+        : null;
+
+    return {
+      x: Number.isFinite(particle.x) ? particle.x : x,
+      y: Number.isFinite(particle.y) ? particle.y : y,
+      vx: Number.isFinite(particle.vx) ? particle.vx : 0,
+      vy: Number.isFinite(particle.vy) ? particle.vy : 0,
+      size: Number.isFinite(particle.size) ? particle.size : fallbackConfig.particleMinSize,
+      life: Number.isFinite(particle.life) ? particle.life : fallbackConfig.particleLife,
+      startColor: particle.startColor || particle.color || fallbackConfig.colorStart,
+      endColor: particle.endColor || particle.color || fallbackConfig.colorEnd,
+      textureType: particle.textureType || fallbackConfig.textureType,
+      rotationVelocity: Number.isFinite(particle.rotationVelocity)
+        ? particle.rotationVelocity
+        : random(-fallbackConfig.rotationSpeed, fallbackConfig.rotationSpeed),
+      secondaryEligible: Boolean(particle.secondaryEligible),
+      secondaryBurstConfig,
+      config: scopedConfig
+    };
+  }
+
+  normalizeSecondaryBurstConfig(config, fallbackConfig) {
+    const sanitized = sanitizeConfig({
+      ...fallbackConfig,
+      ...config,
+      enableSecondaryBurst: false
+    });
+    const partial = { enableSecondaryBurst: false };
+
+    for (const key of Object.keys(config)) {
+      if (key === "enableSecondaryBurst") continue;
+      if (key in sanitized) {
+        partial[key] = sanitized[key];
+      }
+    }
+
+    return partial;
+  }
+
+  animate(now) {
+    if (this.destroyed) return;
+
+    const deltaMs = Math.min(50, now - this.lastTime);
+    this.lastTime = now;
+
+    if (!this.paused) {
+      const step = deltaMs / 16.6667;
+      this.renderer.clearFrame(this.config);
+
+      for (let i = this.shells.length - 1; i >= 0; i -= 1) {
+        if (this.shells[i].update(step)) {
+          const shell = this.shells.splice(i, 1)[0];
+          this.particleSystem.addExplosion(this.createExplosionParticles(shell.targetX, shell.targetY));
+        }
+      }
+
+      this.particleSystem.update(step, this.config);
+      this.renderer.draw(this.config, this.particleSystem, this.shells);
+
+      if (this.config.autoLaunch) {
+        this.autoTimer += deltaMs;
+        if (this.autoTimer >= this.getAutoLaunchIntervalMs()) {
+          this.autoTimer = 0;
+          this.launchRandom();
+        }
+      }
+
+      this.updateFps(deltaMs);
+    }
+
+    this.animationId = requestAnimationFrame(this.animate);
+  }
+
+  updateFps(deltaMs) {
+    this.fpsFrames += 1;
+    this.fpsElapsed += deltaMs;
+    if (this.fpsElapsed < 500) return;
+
+    const fps = Math.round((this.fpsFrames * 1000) / this.fpsElapsed);
+    this.onFpsChange(fps);
+    this.eventBus.emit("fps:change", fps);
+
+    this.lowFpsTime = fps < 45 ? this.lowFpsTime + this.fpsElapsed : 0;
+    if (this.lowFpsTime > 2200 && !this.warnedAboutPerformance) {
+      this.warnedAboutPerformance = true;
+      this.config.particleCount = Math.max(60, Math.round(this.config.particleCount * 0.72));
+      this.notifyConfigChange();
+      this.onLowFps(this.getConfig());
+      this.eventBus.emit("performance:low-fps", this.getConfig());
+    }
+
+    this.fpsFrames = 0;
+    this.fpsElapsed = 0;
+  }
+
+  notifyConfigChange() {
+    const snapshot = this.getConfig();
+    this.onConfigChange(snapshot);
+    this.eventBus.emit("simulator:config-change", { config: snapshot });
+  }
+
+  handlePointerDown(event) {
+    const rect = this.canvas.getBoundingClientRect();
+    this.launch(event.clientX - rect.left, event.clientY - rect.top);
+  }
+
+  handleKeyDown(event) {
+    if (event.code === "Space") {
+      event.preventDefault();
+      this.togglePause();
+    } else if (event.code === "Enter") {
+      event.preventDefault();
+      this.launchRandom();
+    }
+  }
+
+  handleVisibilityChange() {
+    if (document.hidden) {
+      this.pause();
+    } else {
+      this.lastTime = performance.now();
+    }
+  }
+
+  getAutoLaunchIntervalMs() {
+    const intervalSeconds = Number(this.config.autoLaunchIntervalSeconds);
+    if (Number.isFinite(intervalSeconds)) {
+      return intervalSeconds * 1000;
+    }
+    return this.config.autoInterval;
+  }
+
+  normalizeAutoPlayIntervalInput(interval) {
+    const value = Number(interval);
+    return value > 10 ? { autoInterval: value } : { autoLaunchIntervalSeconds: value };
+  }
+
+  normalizeAutoLaunchIntervalPriority(nextConfig, sourceConfig) {
+    if ("autoInterval" in sourceConfig && !("autoLaunchIntervalSeconds" in sourceConfig)) {
+      delete nextConfig.autoLaunchIntervalSeconds;
+    }
+    if ("autoLaunchIntervalSeconds" in sourceConfig && !("autoInterval" in sourceConfig)) {
+      delete nextConfig.autoInterval;
+    }
+  }
+}
+
+function resolveCanvas(canvasOrId) {
+  if (typeof canvasOrId === "string") {
+    return document.getElementById(canvasOrId);
+  }
+  return canvasOrId;
+}

package/src/core/Particle.js

@@ -0,0 +1,174 @@
+import { clamp, lerp, random } from "../utils/math.js";
+import { mixColor, rgbToCss } from "../utils/color.js";
+
+export class Particle {
+  active = false;
+
+  reset(options) {
+    this.active = true;
+    this.x = options.x;
+    this.y = options.y;
+    this.vx = options.vx;
+    this.vy = options.vy;
+    this.size = options.size;
+    this.maxLife = options.life;
+    this.life = options.life;
+    this.startColor = options.startColor;
+    this.endColor = options.endColor;
+    this.textureType = options.textureType;
+    this.config = options.config || null;
+    this.rotation = random(0, Math.PI * 2);
+    this.rotationVelocity = options.rotationVelocity;
+    this.secondaryEligible = options.secondaryEligible;
+    this.secondaryBurstConfig = options.secondaryBurstConfig || null;
+    this.secondaryTriggered = false;
+    this.flickerSeed = random(0, 1000);
+    this.trail = [];
+  }
+
+  update(step, config) {
+    if (!this.active) return null;
+    const runtimeConfig = this.config || config;
+
+    const windX = runtimeConfig.windEnabled ? runtimeConfig.windX : 0;
+    const windY = runtimeConfig.windEnabled ? runtimeConfig.windY : 0;
+
+    this.vx += windX * step;
+    this.vy += (runtimeConfig.gravity + windY) * step;
+    this.vx *= Math.pow(runtimeConfig.damping, step);
+    this.vy *= Math.pow(runtimeConfig.damping, step);
+
+    this.x += this.vx * step;
+    this.y += this.vy * step;
+    this.rotation += this.rotationVelocity * step;
+    this.life -= step;
+
+    if (runtimeConfig.enableTrails) {
+      this.trail.push({ x: this.x, y: this.y, life: this.life });
+      if (this.trail.length > 8) this.trail.shift();
+    } else {
+      this.trail.length = 0;
+    }
+
+    if (
+      runtimeConfig.enableSecondaryBurst &&
+      this.secondaryEligible &&
+      !this.secondaryTriggered &&
+      this.life < this.maxLife * 0.52
+    ) {
+      this.secondaryTriggered = true;
+      this.active = false;
+      return {
+        x: this.x,
+        y: this.y,
+        source: {
+          startColor: this.startColor,
+          endColor: this.endColor,
+          textureType: this.textureType,
+          size: this.size,
+          maxLife: this.maxLife,
+          config: runtimeConfig,
+          secondaryBurstConfig: this.secondaryBurstConfig
+        }
+      };
+    }
+
+    if (this.life <= 0) {
+      this.active = false;
+    }
+
+    return null;
+  }
+
+  draw(ctx, config) {
+    if (!this.active) return;
+    const runtimeConfig = this.config || config;
+
+    const lifeRatio = clamp(this.life / this.maxLife, 0, 1);
+    const age = 1 - lifeRatio;
+    const size = lerp(this.size * runtimeConfig.sizeEndMultiplier, this.size, lifeRatio);
+    const colorT = clamp(age + runtimeConfig.colorShiftRate * age * 8, 0, 1);
+    const color = mixColor(this.startColor, this.endColor, colorT);
+    let alpha = lifeRatio;
+
+    if (runtimeConfig.flicker) {
+      alpha *= 0.72 + Math.abs(Math.sin(this.flickerSeed + this.life * 0.34)) * 0.34;
+    }
+
+    if (runtimeConfig.enableTrails && this.trail.length > 1) {
+      this.drawTrail(ctx, color, alpha, size);
+    }
+
+    ctx.save();
+    ctx.translate(this.x, this.y);
+    ctx.rotate(this.rotation);
+    ctx.fillStyle = rgbToCss(color, alpha);
+    ctx.shadowColor = rgbToCss(color, alpha);
+    ctx.shadowBlur = 18 * runtimeConfig.glowIntensity;
+    drawTexture(ctx, this.textureType || runtimeConfig.textureType, size);
+    ctx.restore();
+  }
+
+  drawTrail(ctx, color, alpha, size) {
+    ctx.save();
+    ctx.lineCap = "round";
+    ctx.lineJoin = "round";
+
+    for (let i = 1; i < this.trail.length; i += 1) {
+      const previous = this.trail[i - 1];
+      const current = this.trail[i];
+      const t = i / this.trail.length;
+      ctx.strokeStyle = rgbToCss(color, alpha * t * 0.26);
+      ctx.lineWidth = Math.max(1, size * t * 0.8);
+      ctx.beginPath();
+      ctx.moveTo(previous.x, previous.y);
+      ctx.lineTo(current.x, current.y);
+      ctx.stroke();
+    }
+
+    ctx.restore();
+  }
+}
+
+function drawTexture(ctx, type, size) {
+  if (type === "square") {
+    ctx.fillRect(-size, -size, size * 2, size * 2);
+    return;
+  }
+
+  if (type === "star") {
+    drawStar(ctx, 5, size * 1.45, size * 0.58);
+    return;
+  }
+
+  if (type === "heart") {
+    drawHeart(ctx, size * 1.25);
+    return;
+  }
+
+  ctx.beginPath();
+  ctx.arc(0, 0, size, 0, Math.PI * 2);
+  ctx.fill();
+}
+
+function drawStar(ctx, points, outerRadius, innerRadius) {
+  ctx.beginPath();
+  for (let i = 0; i < points * 2; i += 1) {
+    const radius = i % 2 === 0 ? outerRadius : innerRadius;
+    const angle = (i * Math.PI) / points - Math.PI / 2;
+    const x = Math.cos(angle) * radius;
+    const y = Math.sin(angle) * radius;
+    if (i === 0) ctx.moveTo(x, y);
+    else ctx.lineTo(x, y);
+  }
+  ctx.closePath();
+  ctx.fill();
+}
+
+function drawHeart(ctx, size) {
+  ctx.beginPath();
+  ctx.moveTo(0, size * 0.5);
+  ctx.bezierCurveTo(size * 1.25, -size * 0.35, size * 0.65, -size * 1.35, 0, -size * 0.62);
+  ctx.bezierCurveTo(-size * 0.65, -size * 1.35, -size * 1.25, -size * 0.35, 0, size * 0.5);
+  ctx.fill();
+}

package/src/core/ParticleSystem.js

@@ -0,0 +1,56 @@
+import { MAX_PARTICLES } from "../config/defaults.js";
+import { Particle } from "./Particle.js";
+
+export class ParticleSystem {
+  constructor(factory, maxParticles = MAX_PARTICLES) {
+    this.factory = factory;
+    this.pool = Array.from({ length: maxParticles }, () => new Particle());
+    this.activeCount = 0;
+  }
+
+  spawn(options) {
+    const particle = this.pool.find((item) => !item.active);
+    if (!particle) return false;
+    particle.reset(options);
+    this.activeCount += 1;
+    return true;
+  }
+
+  addExplosion(particles) {
+    for (const particle of particles) {
+      this.spawn(particle);
+    }
+  }
+
+  update(step, config) {
+    const subBursts = [];
+    let active = 0;
+
+    for (const particle of this.pool) {
+      if (!particle.active) continue;
+      const burst = particle.update(step, config);
+      if (burst) subBursts.push(burst);
+      if (particle.active) active += 1;
+    }
+
+    this.activeCount = active;
+
+    for (const burst of subBursts.slice(0, 12)) {
+      this.addExplosion(this.factory.createSubExplosion(burst.x, burst.y, burst.source));
+    }
+  }
+
+  draw(ctx, config) {
+    for (const particle of this.pool) {
+      particle.draw(ctx, config);
+    }
+  }
+
+  clear() {
+    for (const particle of this.pool) {
+      particle.active = false;
+      particle.trail.length = 0;
+    }
+    this.activeCount = 0;
+  }
+}

package/src/core/Renderer.js

@@ -0,0 +1,44 @@
+export class Renderer {
+  constructor(canvas, backgroundManager) {
+    this.canvas = canvas;
+    this.ctx = canvas.getContext("2d", { alpha: false });
+    this.backgroundManager = backgroundManager;
+    this.width = 0;
+    this.height = 0;
+    this.pixelRatio = 1;
+  }
+
+  resize() {
+    const rect = this.canvas.getBoundingClientRect();
+    this.pixelRatio = Math.min(window.devicePixelRatio || 1, 2);
+    this.width = Math.max(1, Math.floor(rect.width));
+    this.height = Math.max(1, Math.floor(rect.height));
+    this.canvas.width = Math.floor(this.width * this.pixelRatio);
+    this.canvas.height = Math.floor(this.height * this.pixelRatio);
+    this.ctx.setTransform(this.pixelRatio, 0, 0, this.pixelRatio, 0, 0);
+    this.backgroundManager.resize(this.width, this.height);
+  }
+
+  clearFrame(config, forceFullBackground = false) {
+    if (!config.enableTrails || forceFullBackground) {
+      this.backgroundManager.draw(this.ctx, this.width, this.height, config);
+      return;
+    }
+
+    this.ctx.save();
+    this.ctx.globalCompositeOperation = "source-over";
+    this.ctx.fillStyle = `rgba(3, 6, 12, ${config.fadeTrail})`;
+    this.ctx.fillRect(0, 0, this.width, this.height);
+    this.ctx.restore();
+  }
+
+  draw(config, particleSystem, shells) {
+    this.ctx.save();
+    this.ctx.globalCompositeOperation = config.glowIntensity > 0 ? "lighter" : "source-over";
+    for (const shell of shells) {
+      shell.draw(this.ctx, config.showLaunchTrail);
+    }
+    particleSystem.draw(this.ctx, config);
+    this.ctx.restore();
+  }
+}