npm - @mar7th/firework - Versions diffs - 1.0.0 - Mend

@mar7th/firework 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (41) hide show

package/404.html +25 -0
package/LICENSE +21 -0
package/advanced-guide.html +135 -0
package/api-download.html +164 -0
package/demo.html +83 -0
package/dist-lib/spark-fireworks.js +875 -0
package/dist-lib/spark-fireworks.umd.cjs +1 -0
package/docs/api-guide.md +750 -0
package/docs/performance-optimization-plan.md +396 -0
package/examples/production.html +203 -0
package/favicon.jpg +0 -0
package/guide.html +89 -0
package/index.html +60 -0
package/package.json +38 -0
package/script/script1.js +34 -0
package/script/script2.js +38 -0
package/script/script3.js +63 -0
package/script/script4.js +51 -0
package/script/script5.js +55 -0
package/scripts/copy-dist-lib.mjs +4 -0
package/src/app.js +49 -0
package/src/config/defaults.js +302 -0
package/src/core/Firework.js +213 -0
package/src/core/FireworksSimulator.js +439 -0
package/src/core/Particle.js +174 -0
package/src/core/ParticleSystem.js +56 -0
package/src/core/Renderer.js +44 -0
package/src/demo.js +298 -0
package/src/effects/BackgroundManager.js +100 -0
package/src/pages.css +388 -0
package/src/pages.js +1 -0
package/src/plugin.js +9 -0
package/src/styles.css +544 -0
package/src/ui/ControlPanel.js +205 -0
package/src/ui/PerformancePanel.js +23 -0
package/src/ui/PresetManager.js +128 -0
package/src/utils/color.js +54 -0
package/src/utils/eventBus.js +21 -0
package/src/utils/math.js +29 -0
package/vite.config.js +17 -0
package/vite.lib.config.js +19 -0

package/404.html ADDED Viewed

@@ -0,0 +1,25 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="refresh" content="0; url=/" />
+    <link rel="icon" type="image/jpeg" href="/favicon.jpg" />
+    <title>页面未找到</title>
+    <script>
+      window.location.replace("/");
+    </script>
+    <script>
+      var _hmt = _hmt || [];
+      (function() {
+        var hm = document.createElement("script");
+        hm.src = "https://hm.baidu.com/hm.js?c39438c75acf24e0e70a36e03a29e613";
+        var s = document.getElementsByTagName("script")[0];
+        s.parentNode.insertBefore(hm, s);
+      })();
+    </script>
+  </head>
+  <body>
+    <p>页面未找到，正在返回首页。<a href="/">返回首页</a></p>
+  </body>
+</html>

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 yiguo, march7th.online
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/advanced-guide.html ADDED Viewed

@@ -0,0 +1,135 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" type="image/jpeg" href="/favicon.jpg" />
+    <title>SparkFireworks 高级指导</title>
+    <script>
+      var _hmt = _hmt || [];
+      (function() {
+        var hm = document.createElement("script");
+        hm.src = "https://hm.baidu.com/hm.js?c39438c75acf24e0e70a36e03a29e613";
+        var s = document.getElementsByTagName("script")[0];
+        s.parentNode.insertBefore(hm, s);
+      })();
+    </script>
+    <script type="module" src="/src/pages.js"></script>
+  </head>
+  <body>
+    <main class="site-shell">
+      <nav class="site-nav" aria-label="站点导航">
+        <a class="brand" href="/">SparkFireworks</a>
+        <div class="nav-links">
+          <a href="/demo.html">功能演示</a>
+          <a href="/guide.html">使用指导</a>
+          <a href="/advanced-guide.html">高级指导</a>
+          <a href="/api-download.html">API 下载</a>
+        </div>
+      </nav>
+      <header class="page-title">
+        <h1>高级指导</h1>
+        <p>高级模式允许开发者完全接管粒子生成逻辑。你可以返回一组粒子，也可以返回 `{ config, particles }` 为本次爆炸指定局部运行参数。</p>
+      </header>
+      <section class="doc-section">
+        <h2>高级脚本入口</h2>
+        <p>脚本必须声明名为 `createParticles` 的函数。函数会收到 `canvasData`，并返回粒子数组或包含粒子数组的对象。</p>
+        <pre><code>function createParticles(canvasData) {
+  return [
+    {
+      x: canvasData.x,
+      y: canvasData.y,
+      vx: 4,
+      vy: -2,
+      size: 4,
+      life: 90,
+      startColor: "#48d6c2",
+      endColor: "#ffffff",
+      textureType: "circle",
+      rotationVelocity: 0,
+      secondaryEligible: false
+    }
+  ];
+}</code></pre>
+      </section>
+      <section class="doc-section">
+        <h2>canvasData</h2>
+        <ul>
+          <li><code>x</code> / <code>y</code>：本次发射目标点。</li>
+          <li><code>width</code> / <code>height</code>：画布尺寸。</li>
+          <li><code>canvas</code> / <code>ctx</code>：当前画布和 2D 上下文。</li>
+          <li><code>pixelRatio</code>：当前渲染像素比。</li>
+          <li><code>config</code>：当前全局配置快照。</li>
+          <li><code>random(min, max)</code>：项目内置随机数工具。</li>
+        </ul>
+      </section>
+      <section class="doc-section">
+        <h2>粒子字段</h2>
+        <ul>
+          <li><code>x</code>、<code>y</code>：初始位置。</li>
+          <li><code>vx</code>、<code>vy</code>：速度。</li>
+          <li><code>size</code>：初始大小。</li>
+          <li><code>life</code>：生命周期，数值越大存活越久。</li>
+          <li><code>startColor</code>、<code>endColor</code>：颜色渐变。</li>
+          <li><code>color</code>：简写字段，同时作为起止颜色。</li>
+          <li><code>textureType</code>：<code>circle</code>、<code>square</code>、<code>star</code>、<code>heart</code>。</li>
+          <li><code>rotationVelocity</code>：旋转速度。</li>
+          <li><code>secondaryEligible</code>：该粒子是否触发二次爆炸。</li>
+          <li><code>secondaryBurstConfig</code>：该粒子的二次爆炸覆盖配置。</li>
+        </ul>
+      </section>
+      <section class="doc-section">
+        <h2>局部 config</h2>
+        <p>返回 `{ config, particles }` 时，`config` 只作用于本次高级脚本爆炸，不会覆盖右侧控制面板。</p>
+        <pre><code>return {
+  config: {
+    gravity: 0,
+    damping: 0.99,
+    enableTrails: true,
+    glowIntensity: 1.1,
+    textureType: "star"
+  },
+  particles
+};</code></pre>
+      </section>
+      <section class="doc-section">
+        <h2>二次爆炸自定义</h2>
+        <p>默认二次爆炸会继承源粒子效果，并强制关闭三次爆炸。需要自定义时，为粒子添加 `secondaryBurstConfig`。</p>
+        <pre><code>{
+  secondaryEligible: true,
+  secondaryBurstConfig: {
+    particleCount: 36,
+    particleLife: 54,
+    initialSpeedMin: 1.7,
+    initialSpeedMax: 5.2,
+    colorStart: "#fff4a3",
+    colorEnd: "#ffffff",
+    textureType: "circle",
+    explosionShape: "sphere"
+  }
+}</code></pre>
+      </section>
+      <section class="doc-section">
+        <h2>当前五个示例脚本</h2>
+        <h3>script1.js：五角星爆炸</h3>
+        <p>沿五角星轮廓调整速度，适合学习如何用角度和半径控制整体形状。</p>
+        <h3>script2.js：爱心爆炸</h3>
+        <p>使用笛卡尔心形参数方程生成速度，适合学习数学曲线到烟花形状的映射。</p>
+        <h3>script3.js：核心圆与放射线</h3>
+        <p>分两组生成粒子：内部圆形光核和外部射线，适合学习分层组合效果。</p>
+        <h3>script4.js：彩虹多层圆</h3>
+        <p>多层不同半径和颜色的粒子环，适合学习层级颜色和速度同步扩散。</p>
+        <h3>script5.js：十二方向二次爆炸</h3>
+        <p>朝钟表 12 个方向发射红蓝粒子，并为每个粒子配置黄白二次爆炸，适合学习 `secondaryBurstConfig`。</p>
+        <p class="note">这些脚本可以在功能演示页的高级脚本下拉框中直接选择，也可以复制后继续修改。</p>
+      </section>
+    </main>
+  </body>
+</html>

package/api-download.html ADDED Viewed

@@ -0,0 +1,164 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" type="image/jpeg" href="/favicon.jpg" />
+    <title>SparkFireworks API 下载</title>
+    <script>
+      var _hmt = _hmt || [];
+      (function() {
+        var hm = document.createElement("script");
+        hm.src = "https://hm.baidu.com/hm.js?c39438c75acf24e0e70a36e03a29e613";
+        var s = document.getElementsByTagName("script")[0];
+        s.parentNode.insertBefore(hm, s);
+      })();
+    </script>
+    <script type="module" src="/src/pages.js"></script>
+  </head>
+  <body>
+    <main class="site-shell">
+      <nav class="site-nav" aria-label="站点导航">
+        <a class="brand" href="/">SparkFireworks</a>
+        <div class="nav-links">
+          <a href="/demo.html">功能演示</a>
+          <a href="/guide.html">使用指导</a>
+          <a href="/advanced-guide.html">高级指导</a>
+          <a href="/api-download.html">API 下载</a>
+        </div>
+      </nav>
+      <header class="page-title">
+        <h1>API 下载</h1>
+        <p>下载 `npm run build:lib` 生成的库文件，在自己的页面中通过 ESM 或 UMD 方式引入。</p>
+      </header>
+      <section class="doc-section">
+        <h2>构建产物</h2>
+        <div class="download-row">
+          <div>
+            <strong>ES Module</strong>
+            <p><code>dist-lib/spark-fireworks.js</code>，适合现代构建工具和 <code>&lt;script type="module"&gt;</code>。</p>
+          </div>
+          <a class="button-link primary" href="/dist-lib/spark-fireworks.js" download>下载 ESM</a>
+        </div>
+        <div class="download-row">
+          <div>
+            <strong>UMD</strong>
+            <p><code>dist-lib/spark-fireworks.umd.cjs</code>，适合直接挂载到浏览器全局变量 `SparkFireworks`。</p>
+          </div>
+          <a class="button-link" href="/dist-lib/spark-fireworks.umd.cjs" download>下载 UMD</a>
+        </div>
+      </section>
+      <section class="doc-section">
+        <h2>ESM 引入示例</h2>
+        <pre><code>&lt;canvas id="fireworks" style="width:100vw;height:100vh;display:block"&gt;&lt;/canvas&gt;
+&lt;scrip&#116; type="module"&gt;
+  import SparkFireworks from "./dist-lib/spark-fireworks.js";
+  const fireworks = SparkFireworks.create("fireworks", {
+    particleCount: 220,
+    colorStart: "#ffd166",
+    colorEnd: "#ef476f",
+    enableTrails: true
+  });
+  fireworks.launchRandom();
+&lt;/scrip&#116;&gt;</code></pre>
+      </section>
+      <section class="doc-section">
+        <h2>UMD 引入示例</h2>
+        <pre><code>&lt;canvas id="fireworks" style="width:100vw;height:100vh;display:block"&gt;&lt;/canvas&gt;
+&lt;scrip&#116; src="./dist-lib/spark-fireworks.umd.cjs"&gt;&lt;/scrip&#116;&gt;
+&lt;scrip&#116;&gt;
+  const fireworks = SparkFireworks.create("fireworks", {
+    autoLaunch: true,
+    autoLaunchIntervalSeconds: 0.9,
+    enableSecondaryBurst: false
+  });
+  document.addEventListener("click", () =&gt; fireworks.launchRandom());
+&lt;/scrip&#116;&gt;</code></pre>
+      </section>
+      <section class="doc-section">
+        <h2>通过 unpkg 直接使用</h2>
+        <p>发布到 npm 后，可以不下载文件，直接从 unpkg 引入固定版本的构建产物。</p>
+        <h3>ESM</h3>
+        <pre><code>&lt;canvas id="fireworks" style="width:100vw;height:100vh;display:block"&gt;&lt;/canvas&gt;
+&lt;scrip&#116; type="module"&gt;
+  import SparkFireworks from "https://unpkg.com/@mar7th/firework@1.0.0/dist-lib/spark-fireworks.js";
+  const fireworks = SparkFireworks.create("fireworks", {
+    autoLaunch: true,
+    enableTrails: true
+  });
+  fireworks.launchRandom();
+&lt;/scrip&#116;&gt;</code></pre>
+        <h3>UMD</h3>
+        <pre><code>&lt;canvas id="fireworks" style="width:100vw;height:100vh;display:block"&gt;&lt;/canvas&gt;
+&lt;scrip&#116; src="https://unpkg.com/@mar7th/firework@1.0.0/dist-lib/spark-fireworks.umd.cjs"&gt;&lt;/scrip&#116;&gt;
+&lt;scrip&#116;&gt;
+  const fireworks = SparkFireworks.create("fireworks", {
+    autoLaunch: true,
+    autoLaunchIntervalSeconds: 1
+  });
+&lt;/scrip&#116;&gt;</code></pre>
+        <p class="note">生产页面建议固定版本号，例如 `@1.0.0`，避免后续发布新版本时页面行为意外变化。</p>
+      </section>
+      <section class="doc-section">
+        <h2>通过 jsDelivr 直接使用</h2>
+        <p>也可以使用 jsDelivr 的 npm CDN 地址，引入方式和 unpkg 基本一致。</p>
+        <h3>ESM</h3>
+        <pre><code>&lt;canvas id="fireworks" style="width:100vw;height:100vh;display:block"&gt;&lt;/canvas&gt;
+&lt;scrip&#116; type="module"&gt;
+  import SparkFireworks from "https://cdn.jsdelivr.net/npm/@mar7th/firework@1.0.0/dist-lib/spark-fireworks.js";
+  const fireworks = SparkFireworks.create("fireworks", {
+    autoLaunch: true,
+    enableTrails: true
+  });
+  fireworks.launchRandom();
+&lt;/scrip&#116;&gt;</code></pre>
+        <h3>UMD</h3>
+        <pre><code>&lt;canvas id="fireworks" style="width:100vw;height:100vh;display:block"&gt;&lt;/canvas&gt;
+&lt;scrip&#116; src="https://cdn.jsdelivr.net/npm/@mar7th/firework@1.0.0/dist-lib/spark-fireworks.umd.cjs"&gt;&lt;/scrip&#116;&gt;
+&lt;scrip&#116;&gt;
+  const fireworks = SparkFireworks.create("fireworks", {
+    autoLaunch: true,
+    autoLaunchIntervalSeconds: 1
+  });
+&lt;/scrip&#116;&gt;</code></pre>
+        <p class="note">jsDelivr 也建议固定版本号；如果要测试最新版本，可以把 `@1.0.0` 换成 `@latest`。</p>
+      </section>
+      <section class="doc-section">
+        <h2>常用 API</h2>
+        <ul>
+          <li><code>SparkFireworks.create(canvasOrId, configOrOptions)</code>：创建控制器。</li>
+          <li><code>fireworks.launch(x, y, options)</code>：在指定位置发射。</li>
+          <li><code>fireworks.launchRandom()</code>：随机位置发射。</li>
+          <li><code>fireworks.startAutoPlay(seconds)</code> / <code>stopAutoPlay()</code>：自动播放控制。</li>
+          <li><code>fireworks.setConfig(partialConfig)</code>：更新配置。</li>
+          <li><code>fireworks.setAdvancedMode(enabled, createParticles)</code>：开启或关闭高级脚本模式。</li>
+          <li><code>fireworks.destroy()</code>：销毁实例并解绑事件。</li>
+        </ul>
+      </section>
+      <section class="doc-section">
+        <h2>重新构建</h2>
+        <p>如果你修改了源码，需要重新生成库文件：</p>
+        <pre><code>npm run build:lib</code></pre>
+        <p class="note">普通页面构建使用 `npm run build`；库文件构建使用 `npm run build:lib`。</p>
+      </section>
+    </main>
+  </body>
+</html>

package/demo.html ADDED Viewed

@@ -0,0 +1,83 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" type="image/jpeg" href="/favicon.jpg" />
+    <title>烟花模拟器</title>
+    <script>
+      var _hmt = _hmt || [];
+      (function() {
+        var hm = document.createElement("script");
+        hm.src = "https://hm.baidu.com/hm.js?c39438c75acf24e0e70a36e03a29e613";
+        var s = document.getElementsByTagName("script")[0];
+        s.parentNode.insertBefore(hm, s);
+      })();
+    </script>
+  </head>
+  <body>
+    <main id="app" class="app-shell">
+      <section class="stage" aria-label="烟花模拟器工作区">
+        <canvas id="fireworksCanvas" aria-label="烟花模拟器画布" tabindex="0"></canvas>
+        <div class="top-bar">
+          <div class="action-group" aria-label="预设与配置">
+            <a class="toolbar-link" href="/">首页</a>
+            <select id="presetSelect" aria-label="选择预设"></select>
+            <button id="resetConfigButton" type="button">初始化设置</button>
+            <button id="savePresetButton" type="button">保存</button>
+            <button id="exportButton" type="button">导出</button>
+            <label class="file-button">
+              导入
+              <input id="importInput" type="file" accept="application/json" />
+            </label>
+            <button id="shareButton" type="button">分享</button>
+          </div>
+          <div class="action-group" aria-label="动画控制">
+            <span id="fpsCounter" class="metric">FPS --</span>
+            <button id="advancedModeButton" type="button" aria-pressed="false">高级模式</button>
+            <button id="autoButton" type="button" aria-pressed="false">自动</button>
+            <button id="pauseButton" type="button" aria-pressed="false">暂停</button>
+            <button id="clearButton" type="button">清除</button>
+          </div>
+        </div>
+        <div id="toast" class="toast" role="status" aria-live="polite"></div>
+      </section>
+      <aside class="control-panel" aria-label="烟花参数控制面板">
+        <div class="panel-header">
+          <div>
+            <h1>烟花模拟器</h1>
+            <p>点击画布发射，调整参数实时影响后续烟花与当前粒子。</p>
+          </div>
+          <button id="collapseButton" type="button" aria-expanded="true">收起</button>
+        </div>
+        <div id="controls" class="controls"></div>
+        <details class="control-section advanced-script-section" open>
+          <summary>高级脚本</summary>
+          <div class="section-body">
+            <p class="section-hint">
+              高级脚本仅提供给开发者使用；非开发者可以先尝试预设脚本，学习后再使用。二次爆炸自定义功能需要在高级模式自定义脚本中配置。
+            </p>
+            <label class="script-preset-control">
+              示例脚本
+              <select id="advancedScriptPresetSelect" aria-label="选择高级脚本示例"></select>
+            </label>
+            <textarea id="advancedScriptInput" spellcheck="false"></textarea>
+            <div class="button-grid">
+              <button id="applyAdvancedScriptButton" type="button">应用脚本</button>
+              <button id="resetAdvancedScriptButton" type="button">恢复示例</button>
+            </div>
+            <p id="advancedScriptStatus" class="script-status">脚本仅在高级模式开启后生效。</p>
+          </div>
+        </details>
+      </aside>
+    </main>
+    <script type="module" src="/src/demo.js"></script>
+  </body>
+</html>