713 lines
22 KiB
Markdown
713 lines
22 KiB
Markdown
# SpineParticle · Spine JSON 导出设计标准规范
|
||
|
||
> 文档性质：导出功能开发、验收与后续维护的唯一对齐基线
|
||
> 规范状态：已完成产品规则对齐，导出设置面板已实现，JSON 导出逻辑尚未开始
|
||
> 目标格式：Spine JSON 4.2
|
||
> 主要用途：将导出 JSON 重新导入 Spine 编辑器继续编辑
|
||
> 最后更新：2026-08-31
|
||
|
||
---
|
||
|
||
## 一、规范目的
|
||
|
||
本规范用于固定 SpineParticle 的 Spine JSON 导出范围、骨架结构、动画烘焙、资源引用、拖尾蒙皮、关键帧压缩和导出设置语义，避免后续开发因上下文丢失或实现人员变化而偏离已确认规则。
|
||
|
||
后续实现若与本文冲突，应先重新确认并更新本文，不能仅在代码中改变既定语义。
|
||
|
||
---
|
||
|
||
## 二、导出目标与边界
|
||
|
||
### 2.1 导出目标
|
||
|
||
导出结果是一个能够由 Spine 4.2 识别，并能重新导入 Spine 编辑器继续编辑的 JSON 骨架动画文件。
|
||
|
||
导出数据必须满足：
|
||
|
||
1. 粒子表现不依赖 SpineParticle 编辑器运行时；
|
||
2. 粒子、序列帧、颜色、透明度、缩放、旋转、拖尾等表现被转换为 Spine 原生骨骼、插槽、附件与动画时间轴；
|
||
3. 与其他场景模块发生关联的粒子表现必须烘焙为独立动画数据；
|
||
4. 文件结构优先兼顾可编辑性、动画精度和合理体积；
|
||
5. 导出后使用 Spine 4.2 Runtime 进行结构解析验证。
|
||
|
||
### 2.2 导出内容
|
||
|
||
只导出场景中的粒子系统相关内容：
|
||
|
||
- 粒子系统骨骼；
|
||
- 粒子图片插槽和 Region 附件；
|
||
- 粒子位移、旋转、缩放动画；
|
||
- 粒子颜色和透明度动画；
|
||
- 粒子图片与序列帧附件切换；
|
||
- 拖尾骨骼链；
|
||
- 拖尾加权 Mesh、颜色、透明度和资源切换；
|
||
- 项目中的“所属动画”及其粒子时间轴。
|
||
|
||
### 2.3 不导出的内容
|
||
|
||
以下场景对象本身不进入 JSON：
|
||
|
||
- 碰撞体；
|
||
- 路径；
|
||
- 已加载的 Spine 对象；
|
||
- 原 Spine 对象中的骨骼、插槽、皮肤、图片和动画；
|
||
- 编辑器辅助线、网格、背景图、骨骼预览点和调试显示。
|
||
|
||
这些模块若影响了粒子运动，必须只烘焙其最终结果，不能在导出 JSON 中保留对原对象的引用。
|
||
|
||
### 2.4 场景显隐规则
|
||
|
||
- 场景对象小眼睛关闭的粒子系统不导出；
|
||
- 显示状态正常的粒子系统参与导出；
|
||
- 碰撞、路径和 Spine 对象无论是否显示都不作为对象导出；
|
||
- 若可见粒子系统的模拟依赖有效的碰撞、路径或 Spine 跟随，其最终影响仍应被烘焙。
|
||
|
||
---
|
||
|
||
## 三、格式依据与版本规则
|
||
|
||
### 3.1 格式依据
|
||
|
||
实现时依次以以下内容作为格式依据：
|
||
|
||
1. Spine 官方 GitHub 仓库中的 Spine 4.2 JSON 示例；
|
||
2. 项目当前使用的 `@esotericsoftware/spine-core 4.2.119` JSON 解析器；
|
||
3. 项目已有的 Spine 4.2 官方导出样本；
|
||
4. Spine 官方 JSON 格式说明。
|
||
|
||
官方中文说明中的部分示例仍使用 Spine 3.8，不能直接照搬旧版字段。实现必须重点核对 Spine 4.2 的：
|
||
|
||
- `skins` 结构；
|
||
- `rgba` 插槽时间轴；
|
||
- `attachments` 动画结构；
|
||
- 加权 Mesh 顶点编码；
|
||
- 附件切换；
|
||
- 多动画结构；
|
||
- Draw Order 字段命名；
|
||
- Sequence 附件及时间轴结构。
|
||
|
||
### 3.2 版本范围
|
||
|
||
第一版只支持：
|
||
|
||
```text
|
||
Spine 4.2
|
||
```
|
||
|
||
设置面板保留下拉框，以便以后扩展版本，但第一版不得提供没有真实兼容实现的 4.0、4.1 或其他版本选项。
|
||
|
||
---
|
||
|
||
## 四、整体 JSON 结构
|
||
|
||
导出 JSON 的主要结构为：
|
||
|
||
```text
|
||
skeleton
|
||
bones
|
||
slots
|
||
skins
|
||
animations
|
||
```
|
||
|
||
不输出无关约束、碰撞体或路径附件。
|
||
|
||
推荐骨架层级：
|
||
|
||
```text
|
||
root
|
||
├─ ParticleSystem1
|
||
│ ├─ _particle_000
|
||
│ ├─ _particle_001
|
||
│ ├─ _particle_000_trail_1_0
|
||
│ │ └─ _particle_000_trail_1_1
|
||
│ │ └─ ...
|
||
│ └─ ...
|
||
└─ ...
|
||
```
|
||
|
||
每个粒子系统必须作为 `root` 下的独立父骨骼，粒子骨骼统一使用简洁的 `_particle_000` 样式并归入对应系统。所有骨骼、插槽和附件名称仍须全局唯一；多系统发生重名时只为后续同名骨骼追加最短编号后缀。
|
||
|
||
---
|
||
|
||
## 五、Setup Pose 标准
|
||
|
||
### 5.1 普通骨骼
|
||
|
||
除拖尾子骨骼链外，所有导出骨骼的 Setup Pose 使用统一默认值：
|
||
|
||
```text
|
||
x = 0
|
||
y = 0
|
||
rotation = 0
|
||
scaleX = 1
|
||
scaleY = 1
|
||
```
|
||
|
||
粒子系统在编辑器中的位置、旋转和缩放不写入普通骨骼 Setup Pose，必须进入对应动画时间轴。
|
||
|
||
### 5.2 拖尾骨骼链例外
|
||
|
||
拖尾是加权 Mesh 的绑定骨骼链。为了保证导入 Spine 后初始蒙皮结构正确：
|
||
|
||
- 拖尾链保持正常父子层级；
|
||
- 子骨骼保留合理的绑定位置和骨骼长度；
|
||
- 子骨骼不能全部重叠在原点；
|
||
- 动画帧中的拖尾世界状态转换为相对父骨骼的局部位移和局部旋转；
|
||
- 拖尾链根独立于粒子图片骨骼的旋转和缩放，避免粒子图片变换意外污染拖尾蒙皮。
|
||
|
||
### 5.3 Setup Pose 可见性
|
||
|
||
所有蒙皮绑定完成后的粒子 Region 和拖尾 Mesh 在 Setup Pose 中默认透明度为 0，避免导入 Spine 后干扰已有图像显示。
|
||
|
||
动画开始后，由附件切换和 `rgba` 时间轴恢复正确图片、颜色与透明度。
|
||
|
||
---
|
||
|
||
## 六、粒子到 Spine 数据的映射
|
||
|
||
| SpineParticle 数据 | Spine 4.2 数据 |
|
||
|---|---|
|
||
| 粒子系统 | 系统根骨骼 |
|
||
| 粒子池槽位或独立出生粒子 | 粒子骨骼 |
|
||
| 粒子图片 | Region 附件 |
|
||
| 粒子图片显示层 | Slot |
|
||
| 粒子位置 | Bone Translate Timeline |
|
||
| 粒子旋转 | Bone Rotate Timeline |
|
||
| 粒子缩放 | Bone Scale Timeline |
|
||
| 粒子颜色与透明度 | Slot RGBA Timeline |
|
||
| 粒子出生、死亡、假死 | Attachment 与 RGBA Timeline |
|
||
| 多图片资源 | 同一 Slot 下的多个 Region 附件 |
|
||
| 序列帧 | Attachment Timeline 切换 Region |
|
||
| 混合模式 | Slot Blend |
|
||
| 拖尾 | 加权 Mesh + 拖尾骨骼链 |
|
||
| 拖尾颜色与透明度 | 拖尾 Slot RGBA Timeline |
|
||
| 所属动画 | `animations` 下的动画名称 |
|
||
|
||
---
|
||
|
||
## 七、粒子骨骼与对象池
|
||
|
||
### 7.1 开启骨骼对象池
|
||
|
||
开启时：
|
||
|
||
- 按粒子系统最大同时存活数量建立固定粒子骨骼池；
|
||
- 粒子死亡后骨骼可供后续粒子复用；
|
||
- 图片 Slot 和对应拖尾骨骼链随粒子骨骼一起复用；
|
||
- 文件骨骼数量和时间轴体积应显著小于不复用模式；
|
||
- 复用前后通过 Attachment 和 RGBA 关键帧明确隐藏、显示及切换资源。
|
||
|
||
### 7.2 关闭骨骼对象池
|
||
|
||
关闭时：
|
||
|
||
- 每一次逻辑粒子出生建立独立骨骼；
|
||
- 已死亡粒子的骨骼不再分配给后续粒子；
|
||
- 动画较长或发射率较高时允许产生大量骨骼；
|
||
- 界面无需阻止，但导出前可以提示预计骨骼数量和文件体积。
|
||
|
||
### 7.3 循环动画例外
|
||
|
||
纯循环持续动画必须保证循环衔接帧两端的粒子身份稳定。即使关闭对象池，也必须为跨越循环接缝的粒子维持稳定骨骼映射，避免循环首尾出现身份跳变。
|
||
|
||
---
|
||
|
||
## 八、图片与序列帧
|
||
|
||
### 8.1 图片文件
|
||
|
||
导出功能不复制、不下载、不嵌入 PNG，也不生成 Atlas。
|
||
|
||
JSON 只负责输出正确的图片资源路径。用户将在 Spine 中重新扫描并指定图片文件夹。
|
||
|
||
禁止把以下编辑器内部地址写入附件路径：
|
||
|
||
- Data URL；
|
||
- Blob URL；
|
||
- 浏览器临时对象地址；
|
||
- 本机绝对文件路径。
|
||
|
||
### 8.2 图片路径
|
||
|
||
设置中的图片路径，例如：
|
||
|
||
```text
|
||
./images/
|
||
```
|
||
|
||
写入 `skeleton.images`。
|
||
|
||
附件 `path` 只写相对于图片文件夹的资源路径，不重复附加 `./images/`。附件路径应：
|
||
|
||
- 保留资源子文件夹结构；
|
||
- 统一使用 `/`；
|
||
- 清理重复的 `./`；
|
||
- 使用稳定文件名；
|
||
- 默认使用不含图片扩展名的 Spine 资源路径；
|
||
- 检测并提示重复路径。
|
||
|
||
### 8.3 图片缺失
|
||
|
||
图片缺失不阻止导出。
|
||
|
||
- 仍然输出对应 Region 或 Mesh 附件；
|
||
- 保留用户可识别的文件名和路径；
|
||
- Spine 中允许显示缺失图片，用户可根据文件名补充文件；
|
||
- 能取得图片原始尺寸时写入真实尺寸；
|
||
- 完全无法取得尺寸时写入安全占位尺寸并给出提示；
|
||
- 缺图、路径重复或占位尺寸属于警告，不直接取消 JSON 下载。
|
||
|
||
### 8.4 图片尺寸、缩放和锚点
|
||
|
||
- Region `width/height` 使用图片原始像素尺寸；
|
||
- 粒子资源缩放已经体现在粒子骨骼 Scale 动画中，不得重复乘到图片尺寸；
|
||
- Pixi 锚点转换为 Region 相对骨骼中心的偏移；
|
||
- 转换时必须处理 Spine 数学坐标 Y 向上与 Pixi 屏幕坐标 Y 向下的差异；
|
||
- 实现后必须使用非中心锚点和旋转状态进行视觉对照。
|
||
|
||
### 8.5 序列帧
|
||
|
||
一组序列帧始终只使用一根粒子骨骼，不因图片数量增加骨骼。
|
||
|
||
第一版不依赖 Spine 原生 Sequence 命名约束，而采用：
|
||
|
||
- 每张序列图片建立独立 Region 附件；
|
||
- 使用 Attachment Timeline 切换当前 Region；
|
||
- 按烘焙后的最终图片索引输出，不在导出端重新推演播放模式。
|
||
|
||
需要完整支持：
|
||
|
||
- 单次－尾帧消失；
|
||
- 单次－尾帧固定；
|
||
- 正向循环；
|
||
- 反向循环。
|
||
|
||
---
|
||
|
||
## 九、拖尾加权 Mesh 标准
|
||
|
||
### 9.1 禁止项
|
||
|
||
拖尾不得使用逐帧 `attachments → deform` 时间轴作为正式导出方案。
|
||
|
||
### 9.2 正式结构
|
||
|
||
拖尾直接转换为：
|
||
|
||
```text
|
||
拖尾骨骼链 + 加权 Mesh + 骨骼动画
|
||
```
|
||
|
||
复用项目现有拖尾数据：
|
||
|
||
- `trailGridRows / trailGridCols` 生成网格拓扑；
|
||
- 当前三角形索引写入 `triangles`；
|
||
- 当前 UV 与图片旋转写入 `uvs`；
|
||
- `trailSkinWeights` 中的 `boneA / boneB / weight` 转换为 Spine 加权 Mesh 顶点编码；
|
||
- `trailState.bones` 转换为拖尾骨骼链动画；
|
||
- 拖尾资源切换使用同一拖尾 Slot 下的多个 Mesh 附件和 Attachment Timeline；
|
||
- 拖尾颜色和透明度使用拖尾 Slot 的 RGBA Timeline。
|
||
|
||
### 9.3 拖尾动画映射
|
||
|
||
- 拖尾长度由骨骼链各节点位置体现；
|
||
- 拖尾方向由骨骼旋转体现；
|
||
- 拖尾宽度由骨骼垂直缩放体现；
|
||
- 拖尾形状曲线进入 Mesh 的绑定顶点分布；
|
||
- 拖尾图片旋转进入 UV；
|
||
- 拖尾头部必须与粒子最终渲染位置一致；
|
||
- 每帧世界状态转换为父子骨骼局部状态后再写入时间轴。
|
||
|
||
### 9.4 权重标准
|
||
|
||
- 每个顶点使用项目已有的相邻骨骼影响关系；
|
||
- 每个顶点权重和必须在允许误差内等于 1；
|
||
- 骨骼索引必须对应最终 `bones` 数组顺序；
|
||
- 不允许引用不存在或被排除的骨骼；
|
||
- 导出后需要检查弯曲、宽度变化、资源旋转和粒子旋转情况下的拖尾形态。
|
||
|
||
---
|
||
|
||
## 十、外部关联烘焙
|
||
|
||
### 10.1 通用规则
|
||
|
||
所有导出动画先执行一次独立、确定性的离线烘焙：
|
||
|
||
1. 使用当前粒子系统随机种子重置模拟；
|
||
2. 按导出 FPS 逐帧推进；
|
||
3. 计算路径跟随、Spine 骨骼跟随、碰撞和全部修改器；
|
||
4. 记录粒子和拖尾最终渲染状态；
|
||
5. 将外部对象影响转换为系统根或粒子骨骼动画；
|
||
6. JSON 中不保留任何外部对象引用。
|
||
|
||
### 10.2 碰撞
|
||
|
||
- 不导出碰撞体；
|
||
- 碰撞造成的位置、速度方向、暂停、销毁和反弹结果进入最终粒子动画；
|
||
- 碰撞突变前后必须保留关键帧，不能跨越突变进行平滑压缩。
|
||
|
||
### 10.3 路径跟随
|
||
|
||
- 不导出路径对象或 Path Constraint；
|
||
- 本地空间跟随烘焙为系统根运动与粒子局部运动；
|
||
- 世界空间跟随烘焙为粒子最终世界运动，已出生粒子不能错误继承后续路径移动；
|
||
- 路径方向和旋转表现按画布最终结果写入。
|
||
|
||
### 10.4 Spine 骨骼跟随
|
||
|
||
- 不导出原 Spine 对象或原目标骨骼；
|
||
- 跟随位置和用户设置的偏移进入最终动画；
|
||
- 不额外继承原 Spine 骨骼的缩放和旋转，保持编辑器现有语义；
|
||
- 目标失效时按编辑器当前默认回退逻辑处理。
|
||
|
||
### 10.5 坐标空间
|
||
|
||
不能只读取粒子局部快照直接输出。每帧必须组合：
|
||
|
||
```text
|
||
粒子局部状态
|
||
+ 系统根变换
|
||
+ 当前帧跟随目标产生的有效变换
|
||
= 最终可导出状态
|
||
```
|
||
|
||
同时统一处理 Pixi Y 向下与 Spine Y 向上的坐标转换、旋转方向和父子局部变换。
|
||
|
||
---
|
||
|
||
## 十一、动画归属与时长
|
||
|
||
### 11.1 多动画
|
||
|
||
一个 JSON 包含项目中的多个“所属动画”：
|
||
|
||
```json
|
||
"animations": {
|
||
"animation": {},
|
||
"animation2": {},
|
||
"start": {},
|
||
"loop": {},
|
||
"end": {}
|
||
}
|
||
```
|
||
|
||
- 每个粒子系统只写入它所属的动画；
|
||
- 多个粒子系统可以属于同一动画；
|
||
- 同一动画时长取参与导出的粒子系统中最长者；
|
||
- 较短系统到达末帧后保持符合自身模式的末帧状态；
|
||
- Spine、碰撞体和路径自身时长不参与导出动画时长计算。
|
||
|
||
### 11.2 空动画
|
||
|
||
空动画是否保留遵循“排除无内容动画”设置：
|
||
|
||
- 设置关闭：所属动画列表中的空动画仍输出为 `{}`；
|
||
- 设置开启：没有任何可见粒子动画内容的动画不写入 JSON。
|
||
|
||
### 11.3 循环持续三段动画
|
||
|
||
- 启动段、纯循环段和结束段按用户当前保存的状态导出；
|
||
- 循环衔接帧的粒子身份和视觉状态必须稳定；
|
||
- 纯循环段保留假死粒子的骨骼身份，并通过附件隐藏或透明度 0 表现死亡；
|
||
- 循环首尾接缝不得因关键帧精简产生卡顿或突变；
|
||
- 延迟时间保持现有循环持续语义；
|
||
- 所属动画命名继续沿用编辑器已有逻辑，不由导出器自动改名。
|
||
|
||
### 11.4 时间端点
|
||
|
||
- 时间为 `frameIndex / exportFps`；
|
||
- 时间轴包含可选择的最后端点帧；
|
||
- 循环动画允许保留首尾相同的末端点；
|
||
- 时长不足完整导出帧时按规则向上取整，不能截断最长寿命粒子或拖尾。
|
||
|
||
---
|
||
|
||
## 十二、关键帧烘焙与压缩
|
||
|
||
### 12.1 总体策略
|
||
|
||
采用：
|
||
|
||
```text
|
||
完整逐帧烘焙 → 分类 → 安全精简 → 误差验证
|
||
```
|
||
|
||
不能先减少采样再模拟，也不能简单每隔固定帧保留一帧。
|
||
|
||
### 12.2 离散数据
|
||
|
||
以下数据不能进行数值插值，只保留变化点并使用阶跃语义：
|
||
|
||
- 粒子出生和死亡；
|
||
- 图片显示和隐藏；
|
||
- 粒子图片资源切换；
|
||
- 序列帧附件切换；
|
||
- 拖尾资源切换；
|
||
- 混合模式变化；
|
||
- 假死状态切换。
|
||
|
||
连续多帧相同附件或相同状态只输出第一次变化关键帧。
|
||
|
||
### 12.3 连续数据
|
||
|
||
以下数据先逐帧烘焙，再进行误差受控精简：
|
||
|
||
- 粒子位置；
|
||
- 粒子旋转；
|
||
- 粒子缩放；
|
||
- 粒子颜色和透明度；
|
||
- 拖尾骨骼位置；
|
||
- 拖尾骨骼旋转；
|
||
- 拖尾宽度缩放。
|
||
|
||
精简器检查删除中间关键帧后，Spine 插值结果是否仍在误差范围内。采用以下视觉容差：
|
||
|
||
| 数据 | 建议容差 |
|
||
|---|---:|
|
||
| 粒子位置 | 0.05–0.1 像素（当前实现取 0.1） |
|
||
| 拖尾骨骼位置 | 0.05–0.1 像素（当前实现取 0.1） |
|
||
| 旋转 | 0.01° |
|
||
| 缩放 | 0.01 |
|
||
| 透明度 | 0.01 |
|
||
| RGB | 单通道 1/255 |
|
||
|
||
出生、死亡、附件切换、碰撞突变和循环接缝仍强制保留，不允许跨边界压缩。
|
||
|
||
### 12.4 强制保留点
|
||
|
||
以下位置不得跨越压缩：
|
||
|
||
- 粒子出生帧；
|
||
- 粒子死亡帧；
|
||
- 附件显示、隐藏和切换帧；
|
||
- 碰撞、反弹、暂停和销毁前后；
|
||
- 运动方向突然变化处；
|
||
- 拖尾出现和消失处；
|
||
- 循环首尾衔接区域；
|
||
- 延迟段和正式运动段边界；
|
||
- 旋转角度展开产生的边界。
|
||
|
||
### 12.5 旋转处理
|
||
|
||
压缩前先进行角度展开。例如：
|
||
|
||
```text
|
||
358° → 1° → 4°
|
||
```
|
||
|
||
应转换为：
|
||
|
||
```text
|
||
358° → 361° → 364°
|
||
```
|
||
|
||
避免 Spine 插值时反向旋转一整圈。
|
||
|
||
### 12.6 插值曲线设置
|
||
|
||
- `线性 (Linear)`：连续数据使用线性插值和线性误差精简；
|
||
- `平滑贝塞尔 (Smooth Bézier)`：对连续段拟合贝塞尔，并逐帧检查误差；
|
||
- 贝塞尔拟合不满足容差时必须增加关键帧，不能牺牲精度；
|
||
- 离散数据、突变点、碰撞边界和循环接缝不受平滑贝塞尔设置影响。
|
||
|
||
---
|
||
|
||
## 十三、导出设置标准
|
||
|
||
导出设置是全局编辑器设置，不属于单个粒子系统。必须参与：
|
||
|
||
- 保存配置；
|
||
- 加载配置；
|
||
- 预设加载；
|
||
- 撤回；
|
||
- 旧配置默认值补齐。
|
||
|
||
### 13.1 设置项与默认值
|
||
|
||
| 设置 | 默认值 | 规则 |
|
||
|---|---|---|
|
||
| 图片路径 | `./images/` | 写入 `skeleton.images` |
|
||
| Spine 版本 | `Spine 4.2` | 第一版唯一选项 |
|
||
| 关键帧插值曲线 | `线性 (Linear)` | 可切换平滑贝塞尔 |
|
||
| 导出 FPS | `30` | 支持 1～240 的正整数 |
|
||
| 不写 fps | 关闭 | 只省略 `skeleton.fps` 元数据 |
|
||
| 整数帧对齐 | 开启 | 关键帧位于导出 FPS 的整数帧网格 |
|
||
| 骨骼对象池 | 开启 | 复用粒子骨骼和拖尾链 |
|
||
| 排除无内容动画 | 关闭 | 关闭时保留空动画 `{}` |
|
||
| 默认文件名 | `SpineParticle.json` | 浏览器处理重复下载名称 |
|
||
|
||
### 13.2 导出 FPS 语义
|
||
|
||
修改导出 FPS 时保持动画实际秒数不变。
|
||
|
||
例如：
|
||
|
||
```text
|
||
30f / 30 FPS = 1 秒
|
||
60f / 60 FPS = 1 秒
|
||
```
|
||
|
||
不能在导出 60 FPS 时仍只输出 30 帧并把动画缩短为 0.5 秒。
|
||
|
||
“不写 fps”仅省略 Spine JSON 中的 FPS 元数据，内部烘焙、采样和时间换算仍使用导出 FPS。
|
||
|
||
### 13.3 整数帧对齐
|
||
|
||
开启时：
|
||
|
||
```text
|
||
time = integerFrame / exportFps
|
||
```
|
||
|
||
不能产生小数帧位置。无法整除的尾端时长向上取整，同时保持需要完成的粒子生命周期和拖尾状态。
|
||
|
||
---
|
||
|
||
## 十四、命名与文件规则
|
||
|
||
### 14.1 默认文件名
|
||
|
||
```text
|
||
SpineParticle.json
|
||
```
|
||
|
||
### 14.2 名称安全
|
||
|
||
导出器必须：
|
||
|
||
- 为系统、粒子、拖尾、Slot 和 Attachment 生成稳定名称；
|
||
- 处理空名称、重复名称和非法路径分隔符；
|
||
- 保留用户所属动画名称；
|
||
- 不在没有必要时修改用户可见的图片文件名；
|
||
- 保证同一配置、同一种子和同一导出设置产生稳定命名。
|
||
|
||
---
|
||
|
||
## 十五、代码结构标准
|
||
|
||
导出功能必须使用独立文件，不能把大量逻辑继续堆入 `ParticlePanel.vue`、`Stage.vue` 或 Store。
|
||
|
||
推荐结构：
|
||
|
||
```text
|
||
src/export/
|
||
├─ spineExportSettings.ts
|
||
├─ spineJsonTypes.ts
|
||
├─ particleExportBaker.ts
|
||
├─ spineMeshBuilder.ts
|
||
├─ spineKeyframeReducer.ts
|
||
├─ spineJsonExporter.ts
|
||
└─ spineJsonValidator.ts
|
||
```
|
||
|
||
职责：
|
||
|
||
- `spineExportSettings.ts`：导出设置类型、默认值和旧配置补齐；
|
||
- `spineJsonTypes.ts`：Spine 4.2 JSON 类型；
|
||
- `particleExportBaker.ts`：确定性逐帧模拟和外部关联解除；
|
||
- `spineMeshBuilder.ts`：拖尾骨骼链、权重、UV 和三角形生成；
|
||
- `spineKeyframeReducer.ts`：离散合并和连续时间轴误差精简；
|
||
- `spineJsonExporter.ts`：组装 Skeleton、Bones、Slots、Skins 和 Animations；
|
||
- `spineJsonValidator.ts`：导出前后结构验证和警告。
|
||
|
||
界面中的“导出Spine Json”按钮只负责调用导出入口、显示结果和下载文件。
|
||
|
||
---
|
||
|
||
## 十六、验证与验收标准
|
||
|
||
### 16.1 结构验证
|
||
|
||
导出前检查：
|
||
|
||
- 骨骼名称唯一；
|
||
- 父骨骼先于子骨骼；
|
||
- Slot 引用的骨骼存在；
|
||
- Skin 引用的 Slot 存在；
|
||
- Attachment Timeline 引用的附件存在；
|
||
- Mesh 骨骼索引有效；
|
||
- Mesh 权重和正确；
|
||
- UV、顶点和三角形索引数量匹配；
|
||
- 动画时间递增；
|
||
- 颜色为有效 RGBA；
|
||
- 所有数字有限，不出现 `NaN` 或 `Infinity`。
|
||
|
||
### 16.2 Runtime 验证
|
||
|
||
生成 JSON 后，使用项目内 Spine 4.2 Runtime 进行一次解析验证。解析失败时不应下载伪成功文件，应显示明确错误位置。
|
||
|
||
图片缺失不属于 JSON 结构失败，只显示警告。
|
||
|
||
### 16.3 视觉验证
|
||
|
||
至少对以下帧进行编辑器画布与导出结果对照：
|
||
|
||
- 第一帧；
|
||
- 粒子第一次出生帧；
|
||
- 最大粒子数量附近；
|
||
- 图片或序列帧切换帧；
|
||
- 碰撞发生前后；
|
||
- 路径或 Spine 跟随运动中间帧；
|
||
- 拖尾明显弯曲帧；
|
||
- 最后一帧；
|
||
- 纯循环首帧和末帧。
|
||
|
||
对照内容包括：
|
||
|
||
- 粒子数量；
|
||
- 粒子位置；
|
||
- 旋转与缩放；
|
||
- 图片资源；
|
||
- 颜色与透明度；
|
||
- 绘制顺序；
|
||
- 拖尾位置、方向、宽度和弯曲；
|
||
- 循环接缝。
|
||
|
||
### 16.4 文件体积验收
|
||
|
||
- 优先通过对象池、重复状态合并和误差受控关键帧精简减小文件；
|
||
- 拖尾必须使用加权 Mesh，不能用逐帧 Deform 换取实现简单；
|
||
- 不能为了缩小文件破坏碰撞、噪声、序列帧或循环精度；
|
||
- 对象池关闭时允许文件显著增大，但应给出预计规模提示。
|
||
|
||
---
|
||
|
||
## 十七、当前实施状态
|
||
|
||
截至本文落盘：
|
||
|
||
1. 导出范围、格式目标和关键规则已对齐；
|
||
2. 导出设置面板已实现；
|
||
3. 导出设置已接入保存、加载、预设、撤回和旧配置补齐；
|
||
4. 默认文件名已定义为 `SpineParticle.json`；
|
||
5. “导出Spine Json”按钮尚未接入 JSON 生成；
|
||
6. 正式导出代码必须等待用户明确的“开始”指令后实施；
|
||
7. 开始实现前应下载并核对 Spine 官方 GitHub 仓库中的 Spine 4.2 加权 Mesh 和多动画 JSON 示例。
|
||
|
||
---
|
||
|
||
## 十八、禁止偏离项摘要
|
||
|
||
以下规则未经重新确认不得改变：
|
||
|
||
1. 只导出可见粒子系统；
|
||
2. 不导出碰撞体、路径和原 Spine 对象；
|
||
3. 外部关联必须烘焙为独立动画；
|
||
4. 第一版只支持 Spine 4.2；
|
||
5. 图片文件不导出，只写正确路径；
|
||
6. 缺图不阻止导出；
|
||
7. 序列帧只使用一根粒子骨骼；
|
||
8. 拖尾必须使用加权 Mesh 和拖尾骨骼链；
|
||
9. 拖尾不得正式导出为逐帧 Deform；
|
||
10. 先逐帧烘焙，再安全精简关键帧；
|
||
11. Setup Pose 普通骨骼位移和旋转为 0、缩放为 1；
|
||
12. 拖尾子骨骼保留正确绑定链位置；
|
||
13. Setup Pose 图片和 Mesh 默认透明度为 0；
|
||
14. 修改 FPS 时保持实际秒数不变；
|
||
15. 空动画是否保留遵循“排除无内容动画”；
|
||
16. 默认文件名为 `SpineParticle.json`；
|
||
17. 导出功能必须拆分为独立代码模块；
|
||
18. 导出主要用途是重新导入 Spine 编辑器继续编辑。
|