导出数据转spine
This commit is contained in:
tianmo
@@ -0,0 +1,186 @@
|
||||
# 恢复流水线
|
||||
|
||||
## 1. 状态机
|
||||
|
||||
```text
|
||||
Discovered
|
||||
→ Grouped
|
||||
→ PreflightPassed
|
||||
→ PreviewReady
|
||||
→ UserConfirmed
|
||||
→ EditorVerified
|
||||
→ AtlasUnpacked
|
||||
→ ProjectImported
|
||||
→ ProjectVerified
|
||||
→ Published
|
||||
```
|
||||
|
||||
任一步骤失败进入 `Failed(stage, code, details)`。取消进入 `Cancelled`。失败与取消不能发布半成品。
|
||||
|
||||
## 2. 资源组
|
||||
|
||||
一个 `AssetGroup` 包含：
|
||||
|
||||
```text
|
||||
id
|
||||
skeletonDataPath
|
||||
skeletonFormat
|
||||
detectedVersion
|
||||
atlasPath
|
||||
atlasPages[]
|
||||
candidateScore
|
||||
scale
|
||||
alphaMode
|
||||
warnings[]
|
||||
```
|
||||
|
||||
Atlas 页面名是纹理配对的权威来源。文件前缀只作为寻找数据与 Atlas 关系的辅助信号。
|
||||
|
||||
## 3. 预检
|
||||
|
||||
转换前检查：
|
||||
|
||||
- 数据格式和版本
|
||||
- 版本是否在支持范围
|
||||
- Atlas 基础语法
|
||||
- 所有页面是否存在
|
||||
- 图片解码和尺寸
|
||||
- Atlas scale/PMA
|
||||
- 输出命名冲突
|
||||
- 目标 Editor 可用性
|
||||
- 临时目录和输出目录可写性
|
||||
- 磁盘空间粗略估计
|
||||
|
||||
预检不修改输入。
|
||||
|
||||
## 4. 用户确认边界
|
||||
|
||||
预览阶段不得生成正式 `.spine`。允许的临时操作仅包括：
|
||||
|
||||
- Runtime 加载
|
||||
- 图片解码
|
||||
- 静态校验
|
||||
- Editor 只读版本探测
|
||||
|
||||
只有用户点击“开始转换”后，才能调用导入和解包命令。
|
||||
|
||||
## 5. 临时工作区
|
||||
|
||||
```text
|
||||
job-<uuid>/
|
||||
source-links/
|
||||
normalized/
|
||||
unpacked-images/
|
||||
intermediate/
|
||||
logs/
|
||||
publish/
|
||||
```
|
||||
|
||||
- 优先使用复制或只读访问，不能修改源文件。
|
||||
- 是否允许安全硬链接作为优化，在跨平台验证后决定。
|
||||
- 每个任务独立，名称使用内部 UUID，避免用户文件名注入路径。
|
||||
|
||||
## 6. Atlas 解包
|
||||
|
||||
1. 只调用匹配版本 Spine Editor 的官方 Texture Unpacker。
|
||||
2. 校验页面、region 数量、输出尺寸和文件存在性。
|
||||
3. 官方失败或验证失败时终止任务并显示原因，不使用其他解包实现。
|
||||
4. 原始 `.atlas` 和打包纹理页只作为只读输入，不复制到最终结果。
|
||||
5. 工程导入必须读取 Atlas 的 `scale` 并使用 `-s <数值>`，使骨骼与官方解包图片采用相同打包比例。
|
||||
|
||||
详细规则见 `06-图集解包设计.md`。
|
||||
|
||||
## 7. JSON 输入工程生成
|
||||
|
||||
1. 复制 JSON 到临时目录。
|
||||
2. 保留所有未知字段。
|
||||
3. 仅在必要时更新临时副本中的 `skeleton.images` 相对路径。
|
||||
4. 使用匹配主/次版本的 Editor 导入。
|
||||
5. 输出临时 `.spine`。
|
||||
6. 使用 Editor info 或再次导出执行语义验证。
|
||||
|
||||
禁止修改源 JSON。
|
||||
|
||||
## 8. SKEL 输入工程生成
|
||||
|
||||
SKEL 的图片路径自动关联是技术原型重点。候选官方流程：
|
||||
|
||||
1. 匹配版本 Editor 把 SKEL 导入临时 `.spine`。
|
||||
2. Editor 从临时工程导出规范化 JSON。
|
||||
3. 在规范化 JSON 临时副本中设置 `skeleton.images`。
|
||||
4. 匹配版本 Editor 再导入为最终候选 `.spine`。
|
||||
5. 比较初次导入、规范化 JSON 和最终工程的语义计数。
|
||||
|
||||
此流程避免自行解析并序列化全部 SKEL，也避免修改未公开的 `.spine` 格式。
|
||||
|
||||
原型必须验证：
|
||||
|
||||
- 默认 JSON 导出是否保留全部运行时语义。
|
||||
- 动画曲线、Deform、Linked Mesh、约束和事件是否无损。
|
||||
- 图片相对路径是否被最终 `.spine` 保存。
|
||||
- 3.8—4.3 是否行为一致。
|
||||
|
||||
若某版本失败，保留“工程 + images 目录 + 首次打开路径提示”作为降级方案，但正式自动化验收前必须由产品方确认是否接受。
|
||||
|
||||
## 9. Scale 与 Alpha
|
||||
|
||||
- Atlas 显式 `scale` 优先。
|
||||
- 数据和 Atlas 都没有足够信息时，不猜测为确定值。
|
||||
- 可提供 1、0.5、0.25 等候选并让用户预览比较。
|
||||
- 用户可通过底部“去除预乘 Alpha”开关决定是否将解包图片转换为 Straight Alpha。
|
||||
- 为保证各版本行为一致，官方解包使用临时 Atlas 副本并关闭其自动去预乘；开关开启后由本地像素处理统一完成转换。
|
||||
- 临时 Atlas 不修改源文件，也不进入最终结果。
|
||||
|
||||
## 10. 结果验证
|
||||
|
||||
### 10.1 文件级
|
||||
|
||||
- `.spine` 存在且非空。
|
||||
- 所有预期图片存在且可解码。
|
||||
- 输出路径不逃逸目标目录。
|
||||
- 临时文件未混入正式结果。
|
||||
|
||||
### 10.2 语义级
|
||||
|
||||
至少比较：
|
||||
|
||||
- 骨骼数和名称
|
||||
- Slot 数和名称
|
||||
- Skin 数和名称
|
||||
- Attachment 类型与数量
|
||||
- 约束类型与数量
|
||||
- Animation 名称、数量和时长
|
||||
- Event 名称和数量
|
||||
- Deform timeline 存在性
|
||||
|
||||
Nonessential 缺失作为恢复等级，不作为运行时语义失败。
|
||||
|
||||
### 10.3 可读性
|
||||
|
||||
- 使用匹配 Editor 重新读取生成项目。
|
||||
- 捕获所有 warning/error。
|
||||
- 版本不匹配警告视为失败，除非用户启用实验模式。
|
||||
|
||||
## 11. 原子发布
|
||||
|
||||
验证通过后：
|
||||
|
||||
1. 在输出目录同一文件系统创建候选目录。
|
||||
2. 应用重名策略。
|
||||
3. 一次性重命名为正式结果。
|
||||
4. 覆盖时先备份或移入可恢复位置。
|
||||
5. 发布失败保留诊断，但不留下伪成功目录。
|
||||
|
||||
## 12. 输出结构
|
||||
|
||||
```text
|
||||
Output/
|
||||
hero/
|
||||
hero.spine
|
||||
images/
|
||||
body.png
|
||||
face/
|
||||
eye.png
|
||||
```
|
||||
|
||||
当前简化产品不输出原始 Atlas、打包纹理页、日志或恢复报告。发生错误时直接弹窗给出失败阶段和 Spine 输出摘要；成功时弹窗显示完整输出目录。
|
||||
Reference in New Issue
Block a user