@mar7th/firework 1.0.0

package/docs/api-guide.md

@@ -0,0 +1,750 @@
+# SparkFireworks API 使用指南
+
+本文档说明如何在页面中以插件方式使用烟花模拟器 API，包括初始化、参数设置、发射控制、预设、高级模式脚本和自定义粒子格式。
+
+## 1. 构建与引入
+
+先构建可在生产页面直接引入的库文件：
+
+```bash
+npm run build:lib
+```
+
+构建产物在：
+
+```text
+dist-lib/spark-fireworks.umd.cjs
+dist-lib/spark-fireworks.js
+```
+
+普通 HTML 页面可以这样引入：
+
+```html
+<canvas id="fireworks"></canvas>
+
+<script src="./dist-lib/spark-fireworks.umd.cjs"></script>
+<script>
+  const fireworks = SparkFireworks.create("fireworks", {
+    particleCount: 240,
+    explosionShape: "sphere"
+  });
+</script>
+```
+
+也可以传入 canvas DOM：
+
+```js
+const canvas = document.getElementById("fireworks");
+const fireworks = SparkFireworks.create(canvas, {
+  particleCount: 240
+});
+```
+
+## 2. 初始化方式
+
+`SparkFireworks.create(canvas, configOrOptions)` 会返回一个烟花控制器对象。
+
+简单配置：
+
+```js
+const fireworks = SparkFireworks.create("fireworks", {
+  particleCount: 300,
+  colorStart: "#ffd166",
+  colorEnd: "#ef476f"
+});
+```
+
+完整 options 配置：
+
+```js
+const fireworks = SparkFireworks.create("fireworks", {
+  config: {
+    particleCount: 300,
+    explosionShape: "heart"
+  },
+  advancedMode: false,
+  createParticles(canvasData) {
+    return [];
+  },
+  onFpsChange(fps) {
+    console.log("FPS", fps);
+  },
+  onConfigChange(config) {
+    console.log("config changed", config);
+  },
+  onLowFps(config) {
+    console.log("low fps", config);
+  }
+});
+```
+
+## 3. 常用控制方法
+
+### 发射烟花
+
+直接在指定坐标发射：
+
+```js
+fireworks.launch(300, 200);
+```
+
+带升空轨迹：
+
+```js
+fireworks.launch(300, 200, { withShell: true });
+```
+
+不带升空轨迹，直接爆炸：
+
+```js
+fireworks.launch(300, 200, { withShell: false });
+```
+
+随机坐标发射：
+
+```js
+fireworks.launchRandom();
+```
+
+自定义随机坐标：
+
+```js
+function launchRandom() {
+  const rect = canvas.getBoundingClientRect();
+  const x = rect.width * (0.16 + Math.random() * 0.68);
+  const y = rect.height * (0.16 + Math.random() * 0.46);
+  fireworks.launch(x, y, { withShell: true });
+}
+```
+
+### 自动播放
+
+开始自动播放：
+
+```js
+fireworks.startAutoPlay();
+```
+
+指定自动播放间隔，单位秒：
+
+```js
+fireworks.startAutoPlay(0.7);
+```
+
+停止自动播放：
+
+```js
+fireworks.stopAutoPlay();
+```
+
+按布尔值设置：
+
+```js
+fireworks.setAutoPlay(true, 0.9);
+fireworks.setAutoPlay(false);
+```
+
+### 暂停、恢复、清除
+
+```js
+fireworks.pause();
+fireworks.resume();
+const paused = fireworks.togglePause();
+fireworks.clearParticles();
+```
+
+### 重置配置
+
+恢复初始化时的配置：
+
+```js
+fireworks.resetConfig();
+```
+
+用一组新配置作为新的初始化配置：
+
+```js
+fireworks.resetConfig({
+  particleCount: 180,
+  explosionShape: "ring",
+  colorStart: "#4cc9f0",
+  colorEnd: "#80ffdb"
+});
+```
+
+### 修改参数
+
+局部修改参数：
+
+```js
+fireworks.setConfig({
+  gravity: 0.12,
+  damping: 0.986,
+  colorStart: "#48d6c2"
+});
+```
+
+读取当前配置：
+
+```js
+const config = fireworks.getConfig();
+```
+
+### 选择内置预设
+
+```js
+fireworks.selectPreset("classic-gold");
+fireworks.selectPreset("aurora");
+fireworks.selectPreset("fountain");
+fireworks.selectPreset("ghost");
+fireworks.selectPreset("meteor");
+fireworks.selectPreset("heart");
+```
+
+恢复默认预设：
+
+```js
+fireworks.selectPreset("default");
+```
+
+## 4. 配置参数
+
+下面是常用参数和含义。
+
+### 粒子基础
+
+```js
+{
+  particleCount: 180,       // 每次爆炸粒子数，10~1000
+  particleMinSize: 2.5,     // 最小粒子尺寸
+  particleMaxSize: 7,       // 最大粒子尺寸
+  sizeEndMultiplier: 0.35   // 生命周期结束时的尺寸比例
+}
+```
+
+### 运动参数
+
+```js
+{
+  gravity: 0.18,            // 重力，正数向下，负数向上
+  damping: 0.982,           // 速度衰减，越小阻力越强
+  initialSpeedMin: 2.8,     // 初始最小速度
+  initialSpeedMax: 8.2,     // 初始最大速度
+  particleLife: 94,         // 粒子生命周期，单位约等于帧
+  rotationSpeed: 0.025,     // 旋转速度
+  colorShiftRate: 0.035     // 颜色变化速率
+}
+```
+
+### 视觉参数
+
+```js
+{
+  colorStart: "#ffd166",    // 起始颜色
+  colorEnd: "#ef476f",      // 结束颜色
+  useRandomColors: false,   // 是否随机颜色
+  textureType: "circle",    // circle | square | star | heart
+  glowIntensity: 0.75       // 辉光强度
+}
+```
+
+### 特效参数
+
+```js
+{
+  explosionShape: "sphere",     // sphere | ring | starburst | flower | willow | scatter | heart
+  enableSecondaryBurst: false,  // 是否二次爆炸
+  secondaryBurstRatio: 0.2,     // 二次爆炸粒子比例，0-1
+  enableTrails: true,           // 粒子是否带拖尾
+  showLaunchTrail: true,        // 是否显示升空轨迹
+  windEnabled: false,           // 是否开启风场
+  windX: 0,                     // 水平风
+  windY: 0,                     // 垂直风
+  flicker: true,                // 是否闪烁
+  fadeTrail: 0.18               // 画面残影拖尾，越小拖尾越长
+}
+```
+
+### 自动播放
+
+```js
+{
+  autoLaunch: false,        // 是否自动发射
+  autoLaunchIntervalSeconds: 0.9, // 自动发射间隔，秒
+  autoInterval: 900         // 兼容旧版本，自动发射间隔，毫秒
+}
+```
+
+### 背景
+
+```js
+{
+  backgroundType: "starfield",  // solid | linear | radial | starfield | image
+  backgroundColor: "#060912",
+  backgroundColor2: "#10243a",
+  backgroundImageMode: "cover"  // cover | contain | tile
+}
+```
+
+## 5. 完整初始化参数示例
+
+```js
+const fireworks = SparkFireworks.create("fireworks", {
+  particleCount: 260,
+  particleMinSize: 2.5,
+  particleMaxSize: 7,
+  sizeEndMultiplier: 0.35,
+
+  gravity: 0.18,
+  damping: 0.982,
+  initialSpeedMin: 2.8,
+  initialSpeedMax: 8.2,
+  particleLife: 94,
+  rotationSpeed: 0.025,
+  colorShiftRate: 0.035,
+
+  colorStart: "#ffd166",
+  colorEnd: "#ef476f",
+  useRandomColors: false,
+  textureType: "circle",
+  glowIntensity: 0.75,
+
+  explosionShape: "sphere",
+  enableSecondaryBurst: false,
+  secondaryBurstRatio: 0.2,
+  enableTrails: true,
+  showLaunchTrail: true,
+  windEnabled: false,
+  windX: 0,
+  windY: 0,
+  flicker: true,
+  fadeTrail: 0.18,
+
+  autoLaunch: false,
+  autoLaunchIntervalSeconds: 0.9,
+  autoInterval: 900,
+
+  backgroundType: "starfield",
+  backgroundColor: "#060912",
+  backgroundColor2: "#10243a",
+  backgroundImageMode: "cover"
+});
+```
+
+## 6. 高级模式
+
+普通模式下，发射前会根据当前配置自动生成粒子。
+
+高级模式下，发射前不再使用默认粒子生成逻辑，而是调用用户传入的 `createParticles(canvasData)`，由它返回一组粒子。
+
+### 创建时开启高级模式
+
+```js
+const fireworks = SparkFireworks.create("fireworks", {
+  config: {
+    enableTrails: true,
+    glowIntensity: 1
+  },
+  advancedMode: true,
+  createParticles(canvasData) {
+    const particles = [];
+
+    for (let i = 0; i < 200; i += 1) {
+      const angle = Math.random() * Math.PI * 2;
+      const speed = 2 + Math.random() * 8;
+
+      particles.push({
+        x: canvasData.x,
+        y: canvasData.y,
+        vx: Math.cos(angle) * speed,
+        vy: Math.sin(angle) * speed,
+        size: 2 + Math.random() * 4,
+        life: 80,
+        startColor: "#48d6c2",
+        endColor: "#ffffff",
+        textureType: "star",
+        rotationVelocity: 0.03,
+        secondaryEligible: false
+      });
+    }
+
+    return particles;
+  }
+});
+```
+
+### 运行时开启或关闭
+
+```js
+fireworks.setAdvancedMode(true);
+fireworks.setAdvancedMode(false);
+```
+
+同时传入新的粒子生成函数：
+
+```js
+fireworks.setAdvancedMode(true, function createParticles(canvasData) {
+  return [];
+});
+```
+
+只替换粒子生成函数，不改变高级模式开关：
+
+```js
+fireworks.setParticleCreator(function createParticles(canvasData) {
+  return [];
+});
+```
+
+### 页面脚本输入框写法
+
+项目示例页面右侧的“高级脚本”输入框要求写完整函数：
+
+```js
+function createParticles(canvasData) {
+  const particles = [];
+  const count = 360;
+
+  for (let i = 0; i < count; i += 1) {
+    const angle = (i / count) * Math.PI * 2;
+    const speed = 3 + Math.random() * 6;
+
+    particles.push({
+      x: canvasData.x,
+      y: canvasData.y,
+      vx: Math.cos(angle) * speed,
+      vy: Math.sin(angle) * speed,
+      size: 2 + Math.random() * 5,
+      life: 90,
+      startColor: "#48d6c2",
+      endColor: "#ef476f",
+      textureType: "star",
+      rotationVelocity: 0.02,
+      secondaryEligible: false
+    });
+  }
+
+  return particles;
+}
+```
+
+注意：
+
+- 必须声明名为 `createParticles` 的函数。
+- 可以直接返回粒子数组，也可以返回 `{ config, particles }`。
+- 返回数组时，数组元素是粒子对象。
+- 返回 `{ config, particles }` 时，`config` 只作用于本次播放生成的粒子，不会修改全局配置面板。
+- 高级脚本写好后，必须开启“高级模式”才会在发射时生效。
+- 该脚本通过 `new Function` 编译执行，只适合本地或可信页面使用，不要让不可信用户提交脚本。
+
+### 高级脚本携带本次播放配置
+
+如果希望某一次自定义烟花使用独立的重力、拖尾、辉光、风场等全局参数，可以返回对象：
+
+```js
+function createParticles(canvasData) {
+  const particles = [];
+
+  for (let i = 0; i < 260; i += 1) {
+    const angle = (i / 260) * Math.PI * 2;
+    const speed = 3 + Math.random() * 6;
+
+    particles.push({
+      x: canvasData.x,
+      y: canvasData.y,
+      vx: Math.cos(angle) * speed,
+      vy: Math.sin(angle) * speed,
+      size: 2 + Math.random() * 4,
+      life: 90,
+      color: "#ffffff",
+      textureType: "star"
+    });
+  }
+
+  return {
+    config: {
+      gravity: 0.04,
+      damping: 0.99,
+      enableTrails: true,
+      fadeTrail: 0.08,
+      glowIntensity: 1.3,
+      flicker: true,
+      sizeEndMultiplier: 0.2,
+      colorShiftRate: 0.05,
+      windEnabled: true,
+      windX: 0.06,
+      windY: 0,
+      textureType: "star"
+    },
+    particles
+  };
+}
+```
+
+这里的 `config` 是本次发射的局部配置：
+
+- 会合并当前全局配置后用于本次粒子。
+- 不会调用 `setConfig()`，也不会改右侧控制面板。
+- 会跟随这些粒子后续更新和绘制，直到这些粒子消失。
+- 二次爆炸产生的子粒子也会继承这份局部配置。
+
+局部 `config` 适合覆盖这些运行时参数：
+
+```js
+{
+  gravity,
+  damping,
+  enableTrails,
+  fadeTrail,
+  glowIntensity,
+  flicker,
+  sizeEndMultiplier,
+  colorShiftRate,
+  windEnabled,
+  windX,
+  windY,
+  textureType,
+  enableSecondaryBurst,
+  secondaryBurstRatio
+}
+```
+
+不建议把 `backgroundType`、`backgroundColor`、`autoLaunch`、`autoLaunchIntervalSeconds`、`autoInterval` 这类页面级设置放在局部 `config` 里；它们应继续通过 `fireworks.setConfig()` 设置。
+
+## 7. canvasData 参数
+
+高级脚本会接收 `canvasData`：
+
+```js
+{
+  canvas,      // canvas DOM
+  ctx,         // CanvasRenderingContext2D
+  x,           // 本次发射目标 x
+  y,           // 本次发射目标 y
+  width,       // 当前画布 CSS 宽度
+  height,      // 当前画布 CSS 高度
+  pixelRatio,  // 像素比
+  config,      // 当前配置快照
+  random       // 工具函数 random(min, max)
+}
+```
+
+示例：
+
+```js
+function createParticles(canvasData) {
+  const speed = canvasData.random(3, 9);
+  return [
+    {
+      x: canvasData.width / 2,
+      y: canvasData.height / 2,
+      vx: speed,
+      vy: -speed,
+      size: 5,
+      life: 100,
+      startColor: canvasData.config.colorStart,
+      endColor: canvasData.config.colorEnd
+    }
+  ];
+}
+```
+
+## 8. 自定义粒子字段
+
+高级模式返回的 `particles` 数组里，每个粒子对象支持这些字段：
+
+```js
+{
+  x: 300,                    // 初始 x
+  y: 200,                    // 初始 y
+  vx: 4,                     // 水平速度
+  vy: -3,                    // 垂直速度
+  size: 4,                   // 初始大小
+  life: 90,                  // 生命周期
+  startColor: "#48d6c2",     // 起始颜色
+  endColor: "#ef476f",       // 结束颜色
+  color: "#ffffff",          // 可选，同时作为 startColor/endColor 的简写
+  textureType: "star",       // circle | square | star | heart
+  rotationVelocity: 0.02,    // 旋转速度
+  secondaryEligible: false,  // 是否允许二次爆炸
+  secondaryBurstConfig: null // 可选，二次爆炸覆盖配置；默认继承当前粒子效果
+}
+```
+
+字段补全规则：
+
+- 未传 `x/y` 时使用本次发射坐标。
+- 未传 `vx/vy` 时默认为 `0`。
+- 未传 `size/life` 时使用当前配置。
+- 未传 `startColor/endColor` 时使用当前配置。
+- 传了 `color` 但没传 `startColor/endColor` 时，会用 `color` 作为颜色。
+- 未传 `textureType` 时使用当前配置。
+- 未传 `rotationVelocity` 时根据当前 `rotationSpeed` 随机。
+- `secondaryBurstConfig` 只影响该粒子的二次爆炸，并会强制关闭 `enableSecondaryBurst`，不会触发三次爆炸。
+
+`secondaryBurstConfig` 只需要写要覆盖的字段，例如：
+
+```js
+{
+  secondaryEligible: true,
+  secondaryBurstConfig: {
+    particleCount: 36,
+    textureType: "star",
+    colorStart: "#ffffff",
+    colorEnd: "#48d6c2",
+    explosionShape: "ring"
+  }
+}
+```
+
+## 9. 高级脚本示例：爱心爆炸
+
+```js
+function createParticles(canvasData) {
+  const particles = [];
+  const count = 260;
+
+  for (let i = 0; i < count; i += 1) {
+    const t = Math.random() * Math.PI * 2;
+    const hx = 16 * Math.pow(Math.sin(t), 3);
+    const hy = -(
+      13 * Math.cos(t) -
+      5 * Math.cos(2 * t) -
+      2 * Math.cos(3 * t) -
+      Math.cos(4 * t)
+    );
+    const length = Math.hypot(hx, hy) || 1;
+    const speed = 3 + Math.random() * 5;
+
+    particles.push({
+      x: canvasData.x + hx * 1.8,
+      y: canvasData.y + hy * 1.8,
+      vx: (hx / length) * speed,
+      vy: (hy / length) * speed,
+      size: 2 + Math.random() * 4,
+      life: 90 + Math.random() * 30,
+      startColor: "#ff4d6d",
+      endColor: "#ffd6e0",
+      textureType: "heart"
+    });
+  }
+
+  return particles;
+}
+```
+
+## 10. 高级脚本示例：喷泉
+
+```js
+function createParticles(canvasData) {
+  const particles = [];
+  const count = 180;
+
+  for (let i = 0; i < count; i += 1) {
+    const angle = -Math.PI / 2 + (Math.random() - 0.5) * 0.75;
+    const speed = 5 + Math.random() * 8;
+
+    particles.push({
+      x: canvasData.x,
+      y: canvasData.y,
+      vx: Math.cos(angle) * speed,
+      vy: Math.sin(angle) * speed,
+      size: 2 + Math.random() * 3,
+      life: 70 + Math.random() * 40,
+      startColor: "#f7f3a1",
+      endColor: "#fca311",
+      textureType: "star"
+    });
+  }
+
+  return particles;
+}
+```
+
+## 11. 事件与回调
+
+初始化时可以传回调：
+
+```js
+const fireworks = SparkFireworks.create("fireworks", {
+  onFpsChange(fps) {
+    fpsLabel.textContent = `FPS ${fps}`;
+  },
+  onConfigChange(config) {
+    console.log(config);
+  },
+  onLowFps(config) {
+    console.warn("low fps", config);
+  }
+});
+```
+
+也可以监听内部事件：
+
+```js
+const off = fireworks.on("fps:change", (fps) => {
+  console.log(fps);
+});
+
+off();
+```
+
+## 12. 背景图片
+
+通过文件对象设置背景图片：
+
+```js
+input.addEventListener("change", () => {
+  const file = input.files[0];
+  fireworks.setBackgroundImage(
+    file,
+    () => console.log("background loaded"),
+    (message) => console.error(message)
+  );
+});
+```
+
+随后可以设置：
+
+```js
+fireworks.setConfig({
+  backgroundType: "image",
+  backgroundImageMode: "cover"
+});
+```
+
+## 13. 销毁实例
+
+页面卸载或不再使用时：
+
+```js
+fireworks.destroy();
+```
+
+它会取消动画帧，并移除内部绑定的事件监听。
+
+## 14. 最小完整示例
+
+```html
+<canvas id="fireworks" style="width:100vw;height:100vh;display:block"></canvas>
+<button id="launch">发射</button>
+
+<script src="./dist-lib/spark-fireworks.umd.cjs"></script>
+<script>
+  const canvas = document.getElementById("fireworks");
+  const fireworks = SparkFireworks.create(canvas, {
+    particleCount: 220,
+    colorStart: "#ffd166",
+    colorEnd: "#ef476f"
+  });
+
+  document.getElementById("launch").onclick = () => {
+    const rect = canvas.getBoundingClientRect();
+    fireworks.launch(
+      rect.width * (0.2 + Math.random() * 0.6),
+      rect.height * (0.15 + Math.random() * 0.45),
+      { withShell: true }
+    );
+  };
+</script>
+```