SpineParticlesWeb/Document/网页粒子系统阶段三.md

网页粒子系统 · 阶段三

阶段定位：粒子属性与外观资源定版
完成日期：2026-08-28
工程目录：/Users/tianmokeji/Desktop/SpineParticle
技术栈：Vue 3 + TypeScript + Pinia + PixiJS 7 + Vite

---

一、阶段结论

阶段三已完成以下两块核心能力：

1. 粒子属性面板：初始生命周期、速度、缩放、旋转，以及生命周期内速度、缩放、旋转，均已形成统一、可复用的调节结构，并接入粒子计算。
2. 外观与资源面板：支持多图片资源混合发射、每张图片独立的占比、缩放、轴心、颜色、混合模式和透明度；生命周期颜色已升级为可编辑的多色渐变。

当前项目已经具备较完整的“参数编辑 → 实时预览 → 固定帧录制/回放”闭环。接下来不建议继续扩充同一面板，而应进入修改器完善、工程保存/加载和导出准备。

---

二、粒子属性模块完成情况

2.1 粒子初始参数

属性	已支持模式	补充说明
初始生命周期	固定、随机	曲线选项已按最终需求移除
初始速度	固定、随机	实时影响粒子初速度
初始缩放	固定、随机	支持统一缩放与 XY 分离
初始旋转	固定、随机、发射方向	发射方向模式可设置角度偏移

初始参数使用统一的 ParticleAttributeControl.vue，避免每种属性重复实现模式按钮、数值范围和曲线区域。

2.2 生命周期内属性

• 生命周期内速度：独立开关，支持固定、随机、曲线倍率。
• 生命周期内缩放：独立开关，支持固定、随机、曲线，并支持统一与 XY 分离。
• 生命周期内旋转：独立开关，支持固定、随机、曲线旋转速度。
• 曲线调节结果已经接入 ParticleEmitter.update()，不再是只改变界面的空配置。
• 每个曲线编辑器右侧均提供重置按钮，可恢复该属性的默认曲线。
• 随机种子支持手动输入和快速生成；它是场景对象下的全局属性，控制初始属性、资源选择和修改器随机采样，包括 0 在内的任意整数种子均可复现相同发射序列。

2.3 曲线编辑器

当前曲线编辑器支持：

• 拖动关键点；
• 双击空白处新增关键点；
• 双击关键点删除；
• 最少保留两个关键点；
• 按属性传入不同默认曲线并单独重置；
• 生命周期横轴与归一化数值纵轴求值。

---

三、外观与资源模块完成情况

3.1 系统透明度

• 支持固定透明度和生命周期曲线透明度。
• 固定模式直接使用固定值，不再受到透明度曲线影响。
• 曲线模式复用 CurveEditor.vue，支持关键点编辑和重置。

3.2 多图片资源

每个粒子系统默认使用 star.png，并支持：

• 点击缩略图选择本地 PNG、JPEG、WebP 或 GIF 图片；
• 通过右上角 ＋ 添加多张图片资源；
• 每次发射按资源占比随机选择图片；
• 单资源时占比强制为 100%；
• 多资源时总占比始终保持 100%；
• 可锁定某张图片的当前占比，调整其他资源时只重新分配未锁定资源；
• 每张图片独立设置缩放和轴心 X/Y；
• 删除资源后自动重新分配占比；
• 重置资源卡后恢复默认图片、名称、缩放、轴心、颜色、混合模式、透明度和占比状态。

粒子状态中记录 resourceId，录制和回放时能够恢复对应的贴图与轴心，不会全部退回默认图片。

3.3 每张图片独立颜色

每张资源卡独立支持：

• 固定色；
• 生命周期颜色；
• 正常、相加、相乘、滤色四种混合模式。

固定色可通过系统颜色选择器或十六进制输入框精确设置。输入支持：

• #71ffae；
• 71ffae；
• #fff 等三位简写。

无效颜色值不会覆盖当前颜色。

3.4 生命周期多色渐变

新增 ColorGradientEditor.vue，生命周期颜色不再局限于起始色和结束色，而是支持任意数量色标：

• 点击 ＋ 在当前最大色标间隔中添加颜色；
• 双击色带，在指定生命周期位置添加颜色；
• 拖动色标调整位置；
• 输入 0～100 的百分比精确设置位置；
• 使用颜色选择器或十六进制输入框精确调色；
• 双击色标或点击删除按钮移除色标；
• 最少保留两个色标；
• 粒子颜色按生命周期依次经过全部色标。

预览阶段使用线性 RGB 插值计算相邻色标间的颜色。

3.5 每张图片独立透明度

每张资源卡支持三种模式：

模式	行为
关闭	跟随粒子系统透明度设置
固定	使用该图片自己的固定透明度，不受系统透明度曲线影响
曲线	使用该图片自己的生命周期透明度曲线

独立曲线同样支持关键点编辑、曲线模式选择和恢复默认曲线。

---

四、界面与交互修正

• 左侧属性面板、右上画布和右下时间轴固定占满浏览器视口。
• 页面根节点禁止产生额外纵向滚动，只有各自面板内部滚动。
• 修复展开属性内容后页面下方出现大面积空白的问题。
• 曲线重置按钮统一放在曲线面板右侧，不覆盖绘图区。
• 所有数字输入框隐藏浏览器自带的上下微调箭头。
• 数值仍可通过滑块、直接输入和键盘方向键调节。
• 图片占比锁定、删除、重置等状态均提供禁用和高亮反馈。

---

五、核心数据与运行逻辑

5.1 ParticleImageResource

图片资源已经从简单路径扩展为完整的独立配置单元，主要包含：

• 资源标识、纹理、名称、目录、预览地址；
• 占比与锁定状态；
• 缩放与轴心；
• 固定色或生命周期渐变；
• 混合模式；
• 独立透明度模式、固定值和曲线。

5.2 发射与更新

1. spawnOne() 根据占比选择图片资源。
2. 创建粒子时应用该资源的纹理、轴心、缩放、初始颜色和混合模式。
3. update() 根据粒子的 resourceId 查找资源配置。
4. 每帧更新该资源的生命周期颜色、独立透明度和混合模式。
5. capture() / apply() 记录并恢复资源标识，保证时间轴回放一致。

5.3 旧配置兼容

ensureEmitterConfig() 会为热更新对象或旧工程配置补齐新增字段，包括图片权重、锁定、颜色渐变和独立透明度，避免 undefined 进入粒子计算。

---

六、本阶段新增或重点调整的文件

文件	作用
src/views/ParticleAttributeControl.vue	复用固定、随机、曲线和发射方向属性结构
src/views/ColorGradientEditor.vue	多色生命周期渐变编辑器
src/views/CurveEditor.vue	曲线关键点编辑与默认曲线重置
src/views/NumSlider.vue	滑块与数字输入，支持禁用状态
src/views/ParticlePanel.vue	粒子属性及外观资源面板
src/core/particleEmitter.ts	属性、图片权重、颜色、透明度的实际运行逻辑
src/views/Stage.vue	默认纹理注入、多资源录制/回放配置监听
src/style.css	视口滚动约束、数字微调箭头统一隐藏

---

七、验证结果

本阶段进行了浏览器交互测试和生产构建验证，已确认：

• 三个生命周期属性同时展开不会产生页面级额外滚动；
• 固定透明度不受曲线影响；
• 多图片能够同时发射并正确恢复贴图；
• 单图片为 100%，多图片总占比为 100%；
• 三资源场景下锁定 33%，将第二项调为 50%，第三项自动变为 17%；
• 资源卡重置可恢复缩放 1、轴心 0.5/0.5 和全部外观默认值；
• 不同资源可分别使用不同颜色、混合模式和透明度；
• 多色渐变可新增第三个色标并精确修改颜色与位置；
• 固定色和色标颜色的十六进制输入可同步到颜色控件；
• npm run build 通过；
• git diff --check 通过。

Vite 仍会提示主包大于 500 kB，这是体积警告，不影响当前运行。

---

八、当前边界与已知风险

1. 本地图片只存在于当前运行内存：目前使用 Data URL 和 Pixi Texture，尚未实现工程文件持久化、重新加载或资源打包。
2. 仅支持单张静态纹理资源：序列帧、雪碧图和视频纹理尚未实现。
3. 曲线模式目前主要是配置语义：界面提供“跟随导出 / 线性 / 贝塞尔”，当前预览求值仍以关键点间线性插值为主，贝塞尔求值和导出规则需要后续统一实现。
4. 渐变使用线性 RGB 插值：暂未提供颜色空间选择、独立 Alpha 色标或 HDR 颜色。
5. 修改器完成度不一致：重力、风力、力场和阻尼已有运行逻辑；移动噪声、拖尾、碰撞、路径跟随仍需实现或补齐。
6. 粒子池上限固定为 400：复杂多系统场景需要性能压测和可配置上限。
7. 工程配置没有正式版本协议：当前仅通过字段补齐兼容旧对象，进入保存/加载阶段前应定义 schema version 和迁移规则。
8. 缺少自动化测试：当前以 TypeScript 构建和浏览器交互验证为主。

---

九、下一步开发建议

优先级 P0：工程保存与加载

建议优先建立正式的工程配置格式，这是后续预设、分享和导出的基础。

• 定义 ProjectSchema 和 schemaVersion；
• 将 Pixi Texture 等运行时对象与可序列化配置分离；
• 保存图片资源信息和颜色/曲线/渐变数据；
• 支持导出、导入工程 JSON；
• 明确本地图片的持久化方案：Data URL 内嵌、ZIP 工程包或 File System Access API；
• 为旧版本配置提供迁移函数。

优先级 P1：修改器模块定版

按现有面板顺序继续开发，避免跨模块扩散：

1. 移动噪声：确定噪声类型、频率、强度和种子关系；
2. 重力、风力、力场：复核数学坐标系下的方向与单位；
3. 拖尾：先定义数据结构与性能上限，再做渲染；
4. 碰撞：从简单矩形/圆形碰撞体开始；
5. 路径跟随：与场景对象中的轨道路径统一设计。

优先级 P2：撤销/重做与预设

• 建立配置级历史记录，不记录每帧粒子状态；
• 支持 Ctrl/Cmd + Z、Ctrl/Cmd + Shift + Z；
• 为火花、烟雾、雪花、光点等建立预设；
• 预设只保存可序列化配置和资源引用。

优先级 P3：曲线与渐变能力统一

• 抽离统一的曲线求值模块；
• 真正实现线性、贝塞尔、阶跃插值；
• 明确“跟随导出”在预览阶段的行为；
• 为颜色渐变增加可选 Alpha 色标；
• 让曲线和渐变共享键盘操作、选中和删除规则。

优先级 P4：导出准备

• 固化 ParticleState 到逻辑骨骼关键帧的映射；
• 明确图片资源、混合模式和颜色时间轴在 Spine 版本中的表达；
• 先输出内部中间格式，再适配 Spine 3.8 / 4.0 / 4.1 / 4.2；
• 对固定帧采样、整数帧对齐和对象池骨骼数量进行验证。

工程质量建议

• 将 EmitterConfig、资源类型、曲线工具拆分到独立文件；
• 为占比重分配、曲线求值、颜色渐变和配置迁移增加单元测试；
• 对 1、5、20 个系统及 400 粒子上限进行性能测试；
• 在进入导出阶段前处理 Vite 主包体积和按需加载。

---

十、下一阶段推荐验收目标

建议把阶段四定义为：修改器完善 + 工程配置保存/加载。

阶段四完成时应满足：

1. 当前工程可保存为带版本号的配置文件；
2. 刷新页面后导入配置，可恢复全部系统、图片资源、颜色、曲线和渐变；
3. 自定义图片有明确的持久化方案，不依赖旧页面内存；
4. 移动噪声、重力、风力、力场和阻尼行为经过坐标方向验证；
5. 拖尾、碰撞和路径跟随明确为“已实现”或“正式后置”，不再处于含糊占位状态；
6. 关键数据算法具备基础自动化测试。

完成这些后，再进入 Spine JSON 烘焙导出会更稳妥，且无需反复修改当前已经定版的粒子属性与外观资源面板。