280 lines
12 KiB
Markdown
280 lines
12 KiB
Markdown
# 网页粒子系统 · 阶段三
|
||
|
||
> 阶段定位：**粒子属性与外观资源定版**
|
||
> 完成日期：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 烘焙导出会更稳妥，且无需反复修改当前已经定版的粒子属性与外观资源面板。
|