导出数据转spine
This commit is contained in:
tianmo
@@ -0,0 +1,156 @@
|
||||
# 离线预览器
|
||||
|
||||
## 1. 目标
|
||||
|
||||
预览器在不调用 Spine Editor、不开启网络的情况下直接读取：
|
||||
|
||||
```text
|
||||
.json/.skel + .atlas/.atlas.txt + texture pages
|
||||
```
|
||||
|
||||
用户通过预览确认资源配对、版本、Scale、Alpha、动画和 Skin 后，才进入转换。
|
||||
|
||||
## 2. Runtime 版本矩阵
|
||||
|
||||
| 数据 | Runtime 插件 |
|
||||
|---|---|
|
||||
| 3.8.20+ | `dts-runtime-3_8` |
|
||||
| 4.0.x | `dts-runtime-4_0` |
|
||||
| 4.1.x | `dts-runtime-4_1` |
|
||||
| 4.2.x | `dts-runtime-4_2` |
|
||||
| 4.3.x | `dts-runtime-4_3` |
|
||||
|
||||
每个插件基于官方仓库对应分支的 `spine-cpp`。Runtime 与数据主/次版本必须一致。
|
||||
|
||||
## 3. 公共插件 ABI
|
||||
|
||||
公共 API 使用版本号和结构体大小实现向前兼容：
|
||||
|
||||
```text
|
||||
dtsRuntimeGetApiVersion
|
||||
dtsRuntimeCreate
|
||||
dtsRuntimeDestroy
|
||||
dtsRuntimeLoad
|
||||
dtsRuntimeGetMetadata
|
||||
dtsRuntimeGetAnimations
|
||||
dtsRuntimeGetSkins
|
||||
dtsRuntimeSetAnimation
|
||||
dtsRuntimeSetSkin
|
||||
dtsRuntimeSeek
|
||||
dtsRuntimeUpdate
|
||||
dtsRuntimeBuildFrame
|
||||
dtsRuntimeGetLastError
|
||||
```
|
||||
|
||||
设计规则：
|
||||
|
||||
- 调用方提供结构体 `size`。
|
||||
- 插件返回的内存由插件释放。
|
||||
- 错误不能以 C++ 异常越过 ABI。
|
||||
- 所有字符串为 UTF-8，并带长度。
|
||||
- 插件的所有上游符号默认隐藏。
|
||||
- 主程序校验插件文件和 ABI 版本后才加载。
|
||||
|
||||
## 4. 统一绘制数据
|
||||
|
||||
插件输出与 Runtime 版本无关的 draw list：
|
||||
|
||||
```text
|
||||
PreviewFrame
|
||||
bounds
|
||||
vertices[]
|
||||
indices[]
|
||||
commands[]
|
||||
|
||||
DrawCommand
|
||||
textureHandle
|
||||
firstIndex
|
||||
indexCount
|
||||
blendMode
|
||||
premultipliedAlpha
|
||||
```
|
||||
|
||||
顶点至少包含：
|
||||
|
||||
- position
|
||||
- uv
|
||||
- light color
|
||||
- dark color
|
||||
|
||||
Clipping 优先在对应 Runtime/adapter 中完成，使主渲染器只处理最终三角形。
|
||||
|
||||
## 5. 纹理加载
|
||||
|
||||
主程序实现统一 Texture Provider：
|
||||
|
||||
- 根据 Atlas 页面路径读取本地文件。
|
||||
- 拒绝 HTTP/HTTPS 和 data URL。
|
||||
- 规范化相对路径并阻止目录逃逸。
|
||||
- 支持 PNG、JPG/JPEG、WebP。
|
||||
- 保留源 Alpha 模式元数据。
|
||||
- 缓存按 canonical path、修改时间和文件大小失效。
|
||||
|
||||
图片解码插件必须随安装包部署，不能在运行时下载。
|
||||
|
||||
## 6. 渲染功能
|
||||
|
||||
首版必须支持：
|
||||
|
||||
- Region 和 Mesh
|
||||
- Weighted Mesh、Linked Mesh
|
||||
- Clipping
|
||||
- Normal、Additive、Multiply、Screen
|
||||
- 单颜色和 Two Color Tint
|
||||
- PMA 和 Straight Alpha
|
||||
- 多页 Atlas
|
||||
- 高 DPI
|
||||
- 骨骼、Mesh、边界、裁剪调试层
|
||||
|
||||
Shader 作为本地资源随程序部署，并在构建期或启动期从本地加载。
|
||||
|
||||
## 7. 播放状态
|
||||
|
||||
每个预览会话保存：
|
||||
|
||||
```text
|
||||
selectedAnimation
|
||||
selectedSkin
|
||||
loop
|
||||
playbackSpeed
|
||||
time
|
||||
paused
|
||||
camera
|
||||
background
|
||||
debugFlags
|
||||
```
|
||||
|
||||
切换资源组时保留各组会话，避免用户往返查看时丢失位置。
|
||||
|
||||
Seek 需要确定性：先恢复 setup pose，再从动画起点应用到目标时间，不能依赖累积浮点步进得到任意帧。
|
||||
|
||||
## 8. 错误隔离
|
||||
|
||||
首版采用动态插件；技术原型评估损坏 SKEL 是否可能使上游 Runtime 崩溃。如果无法通过输入边界检查和测试降低风险，发布版改为每个版本一个 helper process：
|
||||
|
||||
```text
|
||||
UI ↔ local IPC ↔ preview-worker-4_2
|
||||
```
|
||||
|
||||
是否进程隔离由原型的崩溃与模糊测试结果决定，不在未验证前锁死。
|
||||
|
||||
## 9. 性能目标
|
||||
|
||||
- 普通单骨骼资源首次预览在本地 SSD 上目标小于 1 秒。
|
||||
- 预览默认 60 FPS；窗口不可见时暂停刷新。
|
||||
- 大资源限制最大纹理尺寸、顶点数、附件数和单帧命令数。
|
||||
- 纹理解码在线程池执行，OpenGL 创建在渲染线程执行。
|
||||
- 切换动画不重复加载 Atlas 纹理。
|
||||
|
||||
## 10. 预览验收
|
||||
|
||||
- 五个版本官方示例的选定动画与官方参考视觉一致。
|
||||
- 动画名、Skin 名和时长与 Runtime 数据一致。
|
||||
- PMA/Straight Alpha 无明显黑边或白边。
|
||||
- Mesh、Clipping、双颜色 Tint 和混合模式分别有测试样本。
|
||||
- 缺失纹理不会导致崩溃，并能在画布上定位缺失项。
|
||||
- 拔网后所有预览功能保持可用。
|
||||
Reference in New Issue
Block a user