Yeomai/SpineParticlesWeb

Fork 0

Files

T

tianmo 3a7c0b4092 导出数据转spine

2026-09-07 21:29:15 +08:00

3.8 KiB

Raw Blame History

离线预览器

1. 目标

预览器在不调用 Spine Editor、不开启网络的情况下直接读取：

.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 使用版本号和结构体大小实现向前兼容：

dtsRuntimeGetApiVersion
dtsRuntimeCreate
dtsRuntimeDestroy
dtsRuntimeLoad
dtsRuntimeGetMetadata
dtsRuntimeGetAnimations
dtsRuntimeGetSkins
dtsRuntimeSetAnimation
dtsRuntimeSetSkin
dtsRuntimeSeek
dtsRuntimeUpdate
dtsRuntimeBuildFrame
dtsRuntimeGetLastError

设计规则：

调用方提供结构体 size。
插件返回的内存由插件释放。
错误不能以 C++ 异常越过 ABI。
所有字符串为 UTF-8，并带长度。
插件的所有上游符号默认隐藏。
主程序校验插件文件和 ABI 版本后才加载。

4. 统一绘制数据

插件输出与 Runtime 版本无关的 draw list：

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. 播放状态

每个预览会话保存：

selectedAnimation
selectedSkin
loop
playbackSpeed
time
paused
camera
background
debugFlags

切换资源组时保留各组会话，避免用户往返查看时丢失位置。

Seek 需要确定性：先恢复 setup pose，再从动画起点应用到目标时间，不能依赖累积浮点步进得到任意帧。

8. 错误隔离

首版采用动态插件；技术原型评估损坏 SKEL 是否可能使上游 Runtime 崩溃。如果无法通过输入边界检查和测试降低风险，发布版改为每个版本一个 helper process：

UI ↔ local IPC ↔ preview-worker-4_2

是否进程隔离由原型的崩溃与模糊测试结果决定，不在未验证前锁死。

9. 性能目标

普通单骨骼资源首次预览在本地 SSD 上目标小于 1 秒。
预览默认 60 FPS；窗口不可见时暂停刷新。
大资源限制最大纹理尺寸、顶点数、附件数和单帧命令数。
纹理解码在线程池执行，OpenGL 创建在渲染线程执行。
切换动画不重复加载 Atlas 纹理。

10. 预览验收

五个版本官方示例的选定动画与官方参考视觉一致。
动画名、Skin 名和时长与 Runtime 数据一致。
PMA/Straight Alpha 无明显黑边或白边。
Mesh、Clipping、双颜色 Tint 和混合模式分别有测试样本。
缺失纹理不会导致崩溃，并能在画布上定位缺失项。
拔网后所有预览功能保持可用。

3.8 KiB Raw Blame History Unescape Escape