# Spine 网页端粒子系统 · 开发计划(定稿 v1.0,已确认)

> **已确认的决策**
> - 产品形态:**独立编辑器/演示站**
> - 技术栈:**Vue 3 + Vite + TypeScript + Pinia**
> - Spine 预览运行时:**@pixi/spine + PixiJS 8**(主打 4.2,兼容 3.8/4.0/4.1 预览)
> - 粒子系统:自研轻量粒子池(预览用,勿黑盒库)
> - 导出:**A 方案 —— 工程配置 JSON**(不产出 Spine 动画 JSON;先做 A,MVP 优先,架构为后续 B 预留)
> - 部署:**纯前端静态构建 → Netlify/Vercel/GitHub Pages**,零后端

---

## 一、目标

让没有粒子系统的 Spine 动画,能在网页端**可视化地叠加粒子特效**。用户在网页里:
1. 上传/加载 Spine 骨骼动画(`.json + .atlas + .png`)或内置示例;
2. 在骨骼上配置粒子发射器(可**跟随骨骼**、调各种参数、应用预设);
3. **实时预览**效果;
4. 保存为"工程配置 JSON",下次可再次加载编辑。

> 对标:喵喵 Spine Particle / Spine Particle Studio。**注意**:本次范围是"编辑器+预览+存配置",暂不做那两个站的"导出 Spine 动画 JSON"核心烘焙功能(那属 B 方案,列为后续扩展,见第八节)。

---

## 一·补充、参考站实测核对(已于浏览器读取确认)

### 站1:喵喵 Spine Particle v0.14.1
- 保存/加载配置;**场景对象=粒子系统**(名称/所属动画/系统X/Y/旋转/ScaleX/ScaleY/**参与碰撞 Collision Filter+碰撞标签**)
- 发射:爆发/持续、延迟(秒/帧)、数量、形状(点/圆/矩形/锥体/**轨道**)、方向(随机/固定角度世界/局部/跟随轨道)
- 属性:初始速度/生命周期/缩放(统一与XY分离)/旋转(各支持 固定/随机/**曲线**)、生命周期内变化
- 外观:透明度(固定/曲线,跟随导出/强制线性/强制贝塞尔)、图片(单图/序列/子文件夹)、颜色(固定色/生命周期)、混合模式(正常/相加/相乘/滤色)、缩放/轴心/独立透明度
- 修改器:**发射器跟随**/移动噪声/重力/风力/力场(吸斥)/拖尾
- **导出 Spine JSON**(Spine 3.8/4.0/4.1/4.2、关键帧插值线性/贝塞尔/阶跃、导出FPS、整数帧对齐、**骨骼对象池**、导出骨架、排除无内容动画、图片路径)
- 操作:中键平移、Ctrl+滚轮缩放、Ctrl+Z 撤销、G/L 全局局部坐标、时间轴
- 附:页面头部含**官方飞书文档** <https://ecn2wbmd52pg.feishu.cn/docx/I0rVdOWMoofdzDxZGxDcKOqZnVb>

### 站2:Spine Particle Studio
- 系统列表/名称/粒子位置X/Y/发射器旋转
- 贴图:模式(单图/序列帧/雪碧图)、**内置贴图**(发光星/柔光点/发光环/六角雪花/十字火花/闪耀菱形)+ 自定义上传
- 发射:爆发/持续、方向/吸收(向外/向内)、数量、延迟、总时长、循环/无缝循环/**预热**、形状(点/圆/矩形/扇形)、发射角度/偏移
- 粒子属性:速度/生命/透明度/缩放(固定/随机/曲线,且带**曲线绘制器** 基础值/重置/START/LIFE TIME/END)、初始旋转模式(固定/随机/方向)、旋转模式(速度/曲线)、颜色(固定/生命周期)、混合模式
- 物理与随机:速度抑制/重力/抖动/移动噪声/吸引力场/**碰撞与阻碍物**/随机种子/路径跟随/死亡触发/**拖尾子粒子**(主粒子<20)
- 背景:参考图/上传背景/显示背景/透明度
- **导出 Spine JSON**(Spine 3.8/4.0/4.1/4.2、导出FPS、图片路径)、UI 主题、撤回0/10

### 两站共性(确认)
> 都是一个**粒子特效编辑器**:可视化配置 → 实时预览 → **导出为 Spine 骨骼动画 JSON** 供并入 Spine 工程。站1 更强调"骨骼跟随+骨骼对象池+曲线插值";站2 更强调"内置贴图+物理+拖尾子粒子+曲线绘制器"。

### 对本次 A 方案的定位(重要)
> 本次(A 方案)做的是完整"编辑器+实时预览+工程配置 JSON 存取",**不含**上述"导出 Spine JSON 烘焙"。两者的功能清单(属性/发射/修改器/贴图)在**预览层**基本一致,只是导出层不同;因此做 A 时,除导出外其余功能均按上述清单实现,架构为 B(导出)预留,见第八节。

---

## 二、核心功能清单

| 模块 | 明细 |
|---|---|
| 资源加载 | 上传 `.json+.atlas+.png` / 内置示例(`sample.json` 4.2.43 可当测试数据) |
| 动画控制 | 播放/暂停/停止、循环、动画切换、时间缩放、皮肤切换、骨架缩放/位移 |
| **粒子系统** | 发射器(爆发/持续)、发射形状(点/圆/矩形/扇形/锥体)、发射方向/角度、粒子数量、延迟、时长 |
| 粒子属性 | 速度/生命/透明度/缩放/旋转(各支持 固定/随机/曲线)、颜色(固定/生命周期)、混合模式 |
| **骨骼跟随** | 发射器绑定到某根骨骼/插槽,原点随骨骼逐帧更新(核心特性) |
| 修改器(可选增强) | 重力、风力、移动噪声、拖尾、力场 |
| 贴图资源 | 内置(发光星/柔光点/发光环/雪花/火花/菱形)+ 用户上传;支持 单图/序列帧/雪碧图 |
| 编辑器 UI | 场景对象(粒子层)管理、参数面板(滑块/颜色选择/曲线编辑)、预设模板 |
| 保存/加载 | 导出/导入**工程配置 JSON**;支持撤销/重做、随机种子 |
| 操作习惯 | 中键平移、滚轮缩放 |

---

## 三、技术选型

| 层 | 选型 |
|---|---|
| 前端 | Vue 3 + Vite + TypeScript + Pinia |
| Spine 渲染(预览) | @pixi/spine(runtime-4.2 主,兼容 3.8/4.0/4.1)+ PixiJS 8 |
| 粒子预览 | 自研粒子池(Pixi ParticleContainer / 自定义 WebGL 精灵) |
| 状态 | Pinia |
| 部署 | Vite 静态构建 → 静态托管 |

---

## 四、核心设计(预览层)

- 编辑器画布 = Spine 骨骼渲染 + 若干 `ParticleEmitter`。
- `ParticleEmitter` 管理一个池化粒子容器;每帧:发射原点 = 所属骨骼世界坐标 + 偏移 → 发射粒子 → 更新(位置/速度/重力/寿命/颜色/旋转/alpha)→ 渲染。
- 参数用**归一化数据模型**描述(固定 = 定值 / 随机 = [min,max] / 曲线 = 贝塞尔控制点),同一份模型驱动预览渲染与将来导出。
- 贴图:内置一组 + 用户上传;支持单图/序列帧/雪碧图。

---

## 五、代码结构(建议)

```
SpineParticle/
├─ index.html
├─ vite.config.ts
├─ package.json
├─ src/
│  ├─ main.ts
│  ├─ App.vue
│  ├─ core/
│  │  ├─ spineLoader.ts          # json/atlas/png 加载解析、多版本
│  │  ├─ particleEmitter.ts      # 预览粒子发射器(池化)
│  │  ├─ particleSystem.ts       # 多发射器/帧更新/骨骼跟随
│  │  ├─ curves.ts               # 固定/随机/贝塞尔 求值
│  │  ├─ presets.ts              # 内置贴图 + 预设模板
│  │  └─ types.ts                # 数据模型 + 工程配置结构
│  ├─ views/
│  │  ├─ Stage.vue               # 场景/预览画布
│  │  ├─ AnimationPanel.vue      # 动画控制
│  │  ├─ ParticlePanel.vue       # 粒子层列表 + 参数面板
│  │  └─ PresetPicker.vue        # 预设模板
│  └─ store/
│     └─ particleStore.ts        # spine 资源 + 粒子层状态
└─ 开发计划.md
```

---

## 六、开发阶段(先 MVP 后增强)

| 阶段 | 内容 | 产出 |
|---|---|---|
| **0 需求确认** | 完成(本计划定稿) | — |
| **1 技术验证 Spike** | pixi-spine 加载 `sample.json` 并播放;**一个粒子点跟随 `symbols` 骨骼** | 最小可演示 |
| **2 Spine 预览核心** | 资源加载(上传+内置)、动画/皮肤/缩放/控制、时间轴 | 可操作现有骨骼 |
| **3 粒子预览引擎** | 粒子池、发射器、基础参数、曲线求值、**骨骼跟随** | 骨骼上长出粒子 |
| **4 编辑器 UI** | 场景对象管理、参数面板(滑块/颜色/曲线)、内置贴图+预设 | 可视化编辑 |
| **5 保存/加载** | 导出/导入工程配置 JSON、撤销/重做、随机种子 | 可保存/分享 |
| **6 部署上线** | Vite 构建 → 静态托管,验证 URL | 线上可用 |

> 每阶段都有可运行成果,可随时停下验收。

---

## 七、验收标准(阶段 6 完成时)

- 打开网页 → 加载内置示例(或用你的 `sample.json`)→ 播放动画;
- 在任意骨骼上添加粒子层 → 粒子**跟随骨骼**运动;
- 通过面板调节速率/寿命/速度/颜色/缩放/alpha/重力等 → 实时可见;
- 切换预设 vs 自定义 → 生效;
- 保存工程配置 → 刷新后加载还原;
- 部署到静态托管,公网可访问。

---

## 八、后续扩展(本次不做,已明确后置)

**用户决策:不做烘焙导出,本次只做预览。烘焙这一"大头功能"放后续做。**

- **烘焙导出(后置大目标,即 B 方案)**:把粒子效果**烘焙导出为 Spine 骨骼动画 JSON**(对象池骨骼、逐帧采样、曲线插值线性/贝塞尔/阶跃、fps/整数帧对齐、多版本 3.8/4.0/4.1/4.2 schema)。本项目的"归一化数据模型 + 骨骼跟随"已为此预留,将来平滑接入,无需推翻现有架构。
- 物理系统补充:碰撞体/阻碍物、路径跟随、死亡触发、拖尾子粒子、物理吸引力场。
- 多版本**导出**支持(预览层面本项目已支持多版本)。

> 本次 A 方案与 B 方案只在"导出层"不同:预览层的功能清单(属性/发射/修改器/贴图)两者一致,因此当前实现的每一项都会成为将来 B 方案的直接输入。

---

## 附:交付物

- 一个可运行、可部署的 Vue 3 单页应用(代码 + `package.json`);
- 支持上传 Spine 资源、可视化配置粒子、骨骼跟随、实时预览、存/取配置;
- 开发计划本文件。

---

> ⚠️ 由于需在浏览器里实际调 spine + 粒子渲染与交互,**建议边开发边在浏览器里目视验收**,因此在阶段 1 用你的 `sample.json` 做技术验证(Spike)是关键第一步。