导出数据转spine
This commit is contained in:
tianmo
@@ -0,0 +1,146 @@
|
||||
# 产品需求
|
||||
|
||||
## 1. 产品目标
|
||||
|
||||
DateToSpine 帮助用户批量处理仅保留运行时导出文件、但缺失原始 `.spine` 工程的资源。软件需要在转换前验证资源并显示可交互动画预览，用户确认后才调用本地 Spine Editor 生成可编辑工程。
|
||||
|
||||
产品目标是“尽可能恢复可编辑工程”，不是承诺字节级还原原工程。运行时导出时已经丢失的数据无法凭空恢复。
|
||||
|
||||
## 2. 用户前提
|
||||
|
||||
- 用户对待处理资源拥有合法使用和转换权限。
|
||||
- 用户电脑已安装并激活 Spine Editor。
|
||||
- 需要生成 `.spine` 时，本地已有与资源主/次版本相匹配的 Editor 版本。
|
||||
- 未安装 Editor 时，软件仍可扫描、校验、配对和预览，但不能生成 `.spine`。
|
||||
|
||||
## 3. 支持范围
|
||||
|
||||
### 3.1 骨骼数据
|
||||
|
||||
| 格式 | 支持状态 | 说明 |
|
||||
|---|---|---|
|
||||
| `.json` | 正式支持 | 必须通过 Spine schema 识别，不能把普通 JSON 当作骨骼数据 |
|
||||
| `.skel` | 正式支持 | 按导出版本选择匹配 Runtime 和 Editor |
|
||||
| `.skel.bytes` | 候选兼容 | 通过内容识别，扩展名支持在技术原型后决定 |
|
||||
|
||||
### 3.2 Spine 版本
|
||||
|
||||
| 版本 | 支持级别 |
|
||||
|---|---|
|
||||
| 3.8.20+ | 正式支持 |
|
||||
| 3.8.0—3.8.19 | 尽力识别，不作正式保证 |
|
||||
| 4.0.x | 正式支持 |
|
||||
| 4.1.x | 正式支持 |
|
||||
| 4.2.x | 正式支持 |
|
||||
| 4.3.x | 正式支持 |
|
||||
| 3.7.x 及更早 | 不支持 |
|
||||
|
||||
### 3.3 Atlas 与纹理页
|
||||
|
||||
- `.atlas`、`.atlas.txt`
|
||||
- 单页和多页 Atlas
|
||||
- PNG
|
||||
- JPG/JPEG
|
||||
- WebP
|
||||
- 同一 Atlas 中不同扩展名的多页纹理
|
||||
- Straight Alpha 和 Premultiplied Alpha
|
||||
|
||||
其他图片格式通过可扩展解码接口保留未来支持空间，但不属于首版承诺。
|
||||
|
||||
## 4. 主用户流程
|
||||
|
||||
主界面只暴露四个动作：
|
||||
|
||||
1. 用户把完整导出资源或资源文件夹拖入窗口。
|
||||
2. 软件自动配对并显示预览；有多套资源时用顶部下拉框切换。
|
||||
3. 用户用底部下拉框切换动画。
|
||||
4. 用户点击“一键转换为 .spine”并选择保存位置。
|
||||
|
||||
版本检测、Atlas 配对、图片处理、Editor 验证和结果校验均在后台自动完成。只有自动找不到 Spine Editor 时，才要求用户指定 Spine 应用或可执行文件路径。普通流程不提供 Editor 管理页或技术参数面板。
|
||||
|
||||
## 5. 功能需求
|
||||
|
||||
### 5.1 扫描与配对
|
||||
|
||||
- 支持文件、文件夹和批量拖放。
|
||||
- 支持递归扫描，允许配置最大深度。
|
||||
- 根据 Atlas 中声明的页面名查找纹理，不能只依赖同名前缀。
|
||||
- 根据附件 path、文件名、目录距离和名称前缀对数据与 Atlas 评分。
|
||||
- 自动结果必须显示置信度。
|
||||
- 歧义配对必须由用户确认，不能静默选择。
|
||||
- 单个失败组不能终止整个批次。
|
||||
|
||||
### 5.2 预览
|
||||
|
||||
- 默认循环播放，支持动画切换。
|
||||
- 画布自动适应窗口。
|
||||
- 支持 Mesh、权重、Clipping、双颜色 Tint 和四种混合模式。
|
||||
- 显示缺失纹理、版本错误和 Runtime 加载错误。
|
||||
|
||||
### 5.3 Editor 管理
|
||||
|
||||
- 自动查找常见安装位置。
|
||||
- 自动查找失败时才显示路径选择器，支持自定义应用、可执行文件或安装目录。
|
||||
- 支持一个安装入口对应多个本地可用版本。
|
||||
- 转换前执行实际版本探测。
|
||||
- 不读取、存储或传输 Spine 激活码。
|
||||
|
||||
### 5.4 批量转换
|
||||
|
||||
- 默认串行调用 Spine Editor，扫描和静态校验可并行。
|
||||
- 支持停止等待中的任务和取消当前子进程。
|
||||
- 支持跳过、自动重命名和覆盖策略。
|
||||
- 默认不覆盖输入文件。
|
||||
- 正式结果验证通过前只写入任务临时目录。
|
||||
- 每组资源产生可读日志和机器可读报告。
|
||||
|
||||
## 6. 恢复能力边界
|
||||
|
||||
通常可恢复：骨骼、Slots、Skins、Attachments、约束、动画、Deform、事件和绘制顺序。
|
||||
|
||||
如果源文件导出时未启用 Nonessential data，可能永久缺失：
|
||||
|
||||
- 骨骼颜色和图标
|
||||
- Mesh 手工边
|
||||
- 编辑器辅助信息
|
||||
- 部分附件原始尺寸
|
||||
- 原工程图片和音频目录设置
|
||||
- 编辑器视图与工作区状态
|
||||
|
||||
报告必须区分：
|
||||
|
||||
- 完整恢复
|
||||
- 主体恢复但缺少 Nonessential data
|
||||
- 工程生成成功但图片关联需要注意
|
||||
- 转换失败
|
||||
|
||||
## 7. 非功能需求
|
||||
|
||||
- macOS 和 Windows 功能一致。
|
||||
- 运行时完全离线，不依赖 CDN 或在线服务。
|
||||
- 支持中文、空格、Unicode 和较长路径。
|
||||
- 所有外部进程使用参数数组启动，不能拼接 shell 命令。
|
||||
- 崩溃或取消不能留下半成品覆盖正式结果。
|
||||
- 日志不能包含用户授权信息或不必要的绝对路径。
|
||||
- 普通操作错误必须以用户可理解的语言呈现。
|
||||
|
||||
## 8. 首版不包含
|
||||
|
||||
- Spine 3.7 及更早版本。
|
||||
- 绕过 Spine Editor 授权或下载 Editor。
|
||||
- 自行生成或逆向写入 `.spine` 格式。
|
||||
- 动画编辑功能。
|
||||
- 云端转换、资源上传或账号系统。
|
||||
- 将官方示例资产打包给最终用户。
|
||||
|
||||
## 9. 产品验收标准
|
||||
|
||||
- 五个目标版本均可完成 JSON、SKEL 的预览和转换测试。
|
||||
- 断网环境可完成已准备版本的完整流程。
|
||||
- PNG、JPG/JPEG、WebP 页面可预览。
|
||||
- 纹理只允许使用匹配版本 Spine Editor 的官方 Texture Unpacker 解包。
|
||||
- 生成物能被匹配版本 Editor 重新读取。
|
||||
- 骨骼、Skin、附件、动画和事件数量通过语义核对。
|
||||
- 原始输入不被修改。
|
||||
- 单任务失败不影响批次其他任务。
|
||||
- 最终安装包不含官方测试资源和 Spine Editor。
|
||||
@@ -0,0 +1,217 @@
|
||||
# 系统架构
|
||||
|
||||
## 1. 技术基线
|
||||
|
||||
| 项目 | 选择 |
|
||||
|---|---|
|
||||
| 语言 | C++20（第三方 Runtime target 可使用其原生标准） |
|
||||
| UI | Qt 6 Widgets |
|
||||
| 预览画布 | `QOpenGLWidget` + 自研批次渲染器 |
|
||||
| 构建 | CMake 3.25+、CMake Presets |
|
||||
| Windows 编译器 | Visual Studio 2022 / MSVC v143 |
|
||||
| macOS 编译器 | Apple Clang |
|
||||
| 进程管理 | `QProcess` |
|
||||
| 设置存储 | `QSettings` |
|
||||
| JSON | Qt JSON |
|
||||
| 图片加载 | Qt Image plugins，随程序离线部署 |
|
||||
| 测试 | Qt Test 或 Catch2，原型结束时二选一 |
|
||||
|
||||
CMake 只用于开发构建，不是最终用户的运行依赖。Windows 可以使用 Visual Studio Generator 或 Ninja + MSVC。
|
||||
|
||||
## 2. 分层结构
|
||||
|
||||
```text
|
||||
UI
|
||||
├─ 资源组表格
|
||||
├─ 预览与播放控制
|
||||
├─ Editor 管理
|
||||
└─ 任务、日志与报告
|
||||
↓
|
||||
Application Services
|
||||
├─ ScanService
|
||||
├─ PreviewService
|
||||
├─ EditorRegistry
|
||||
├─ RecoveryCoordinator
|
||||
└─ ReportService
|
||||
↓
|
||||
Domain
|
||||
├─ AssetGroup
|
||||
├─ SpineVersion
|
||||
├─ EditorInstallation
|
||||
├─ RecoveryJob
|
||||
└─ RecoveryResult
|
||||
↓
|
||||
Infrastructure
|
||||
├─ Filesystem / Process
|
||||
├─ Runtime Plugin Host
|
||||
├─ Spine CLI Adapter
|
||||
├─ Atlas Unpackers
|
||||
└─ Output Publisher
|
||||
```
|
||||
|
||||
UI 只表达状态和用户意图，不能直接调用 Spine CLI 或解析 Atlas。
|
||||
|
||||
## 3. 建议目录
|
||||
|
||||
```text
|
||||
DateToSpine/
|
||||
CMakeLists.txt
|
||||
CMakePresets.json
|
||||
cmake/
|
||||
docs/
|
||||
licenses/
|
||||
resources/
|
||||
icons/
|
||||
shaders/
|
||||
translations/
|
||||
src/
|
||||
app/
|
||||
domain/
|
||||
scan/
|
||||
atlas/
|
||||
editor/
|
||||
preview/
|
||||
recovery/
|
||||
report/
|
||||
platform/
|
||||
macos/
|
||||
windows/
|
||||
ui/
|
||||
util/
|
||||
runtime-api/
|
||||
runtime-plugins/
|
||||
spine38/
|
||||
spine40/
|
||||
spine41/
|
||||
spine42/
|
||||
spine43/
|
||||
third_party/
|
||||
spine-runtimes/
|
||||
licenses/
|
||||
tests/
|
||||
unit/
|
||||
integration/
|
||||
compatibility/
|
||||
manifests/
|
||||
fixtures/
|
||||
generated/
|
||||
external/
|
||||
packaging/
|
||||
macos/
|
||||
windows/
|
||||
```
|
||||
|
||||
`tests/fixtures/external/` 用于本地准备的官方测试资源，不进入发行包。
|
||||
|
||||
## 4. 多版本 Runtime 隔离
|
||||
|
||||
五套 Runtime 不能直接链接进同一个主程序命名空间。每个版本编译成独立动态模块，并隐藏所有上游 C++ 符号，只导出稳定的 DateToSpine C ABI。
|
||||
|
||||
```text
|
||||
dts-runtime-3_8
|
||||
dts-runtime-4_0
|
||||
dts-runtime-4_1
|
||||
dts-runtime-4_2
|
||||
dts-runtime-4_3
|
||||
```
|
||||
|
||||
公共 ABI 只允许：
|
||||
|
||||
- 固定宽度整数
|
||||
- POD 结构体
|
||||
- UTF-8 字节串
|
||||
- 不透明句柄
|
||||
- 显式长度的数组
|
||||
- 函数指针回调
|
||||
|
||||
禁止跨模块传递 Qt 对象、STL 容器、异常或 Spine Runtime 类。
|
||||
|
||||
每个适配模块承担：
|
||||
|
||||
- 对应版本 JSON/SKEL 读取
|
||||
- Atlas 绑定
|
||||
- 动画状态推进
|
||||
- Skin/Animation 查询和切换
|
||||
- 把绘制结果转换为统一顶点、索引和 draw command
|
||||
- 把上游错误转换为统一错误码
|
||||
|
||||
## 5. 预览渲染边界
|
||||
|
||||
Runtime 插件负责骨骼计算和裁剪；主程序渲染器负责：
|
||||
|
||||
- 纹理创建和缓存
|
||||
- 顶点/索引上传
|
||||
- Shader
|
||||
- Blend mode
|
||||
- 相机、背景和调试覆盖层
|
||||
- DPI 和窗口生命周期
|
||||
|
||||
Runtime 不直接创建 Qt 或 OpenGL 对象。这使 Runtime 适配可独立测试，也避免上下文所有权问题。
|
||||
|
||||
## 6. Spine CLI 边界
|
||||
|
||||
所有 Editor 调用必须经过 `ISpineCli`：
|
||||
|
||||
```text
|
||||
probe installation
|
||||
probe version
|
||||
import data
|
||||
export normalized json
|
||||
unpack atlas
|
||||
inspect project
|
||||
```
|
||||
|
||||
实现要求：
|
||||
|
||||
- 使用 `QProcess::setProgram` 和 `setArguments`。
|
||||
- 不经过 shell。
|
||||
- 每次调用有超时、取消令牌、工作目录和独立日志。
|
||||
- 只终止本软件启动的子进程。
|
||||
- 对 Windows 优先选择 `Spine.com`。
|
||||
- 对 macOS 把 `.app` 规范化为内部可执行文件。
|
||||
|
||||
## 7. 任务并发
|
||||
|
||||
- 扫描、哈希、图片头校验可以在线程池执行。
|
||||
- OpenGL 资源操作只在所属渲染线程执行。
|
||||
- Spine Editor 调用默认全局串行。
|
||||
- Spine 官方 Atlas 解包与工程导入全局串行，并受任务取消状态约束。
|
||||
- 每个恢复任务有独立临时目录和取消状态。
|
||||
|
||||
## 8. 文件长度和复杂度约束
|
||||
|
||||
自研代码执行以下软上限，超过时必须在评审中说明或拆分：
|
||||
|
||||
| 文件类型 | 建议上限 |
|
||||
|---|---:|
|
||||
| 头文件 | 200 行 |
|
||||
| 普通 `.cpp` | 350 行 |
|
||||
| UI `.cpp` | 450 行 |
|
||||
| 单元测试文件 | 500 行 |
|
||||
|
||||
同时执行：
|
||||
|
||||
- 一个类只有一个主要职责。
|
||||
- `MainWindow` 不包含解析、转换和进程逻辑。
|
||||
- 禁止无边界的 `Utils` 类。
|
||||
- 平台代码不得散落到业务模块。
|
||||
- 版本差异留在 Runtime adapter 和 version policy 中。
|
||||
- 第三方上游源码保持原样，位于 `third_party/`，不纳入自研文件行数限制。
|
||||
|
||||
CI 将检查自研源文件行数、循环依赖和禁止目录引用。
|
||||
|
||||
## 9. 可测试性
|
||||
|
||||
核心依赖使用小接口注入：
|
||||
|
||||
```text
|
||||
IFileSystem
|
||||
IProcessRunner
|
||||
ISpineCli
|
||||
IRuntimePlugin
|
||||
IAtlasUnpacker
|
||||
IClock
|
||||
IReportSink
|
||||
```
|
||||
|
||||
单元测试不启动真实 Editor；集成和兼容测试才调用本地 Spine Editor。
|
||||
@@ -0,0 +1,193 @@
|
||||
# 版本识别与 Spine Editor 检测
|
||||
|
||||
## 1. 目标
|
||||
|
||||
在用户确认转换前，软件必须回答：
|
||||
|
||||
1. 资源由哪个 Spine 主/次版本导出？
|
||||
2. 本机是否有可以处理该版本的 Spine Editor？
|
||||
3. 配置路径是否指向可用的 Spine CLI？
|
||||
4. 在断网状态下，该版本是否能实际启动和导入？
|
||||
|
||||
路径存在不等于 Editor 可用。当前实现先读取本机 Spine 更新缓存，只把已经存在的精确版本视为可转换；转换时再次执行同一门禁。
|
||||
|
||||
## 2. 资源版本识别
|
||||
|
||||
### 2.1 JSON
|
||||
|
||||
读取 `skeleton.spine` 字段，并同时验证最小 Spine schema：
|
||||
|
||||
- 根对象
|
||||
- `bones` 数组
|
||||
- 可选 `slots`、`skins`、`animations`
|
||||
- 版本字段格式
|
||||
|
||||
只解析识别所需的小范围数据。无 Spine schema 的业务 JSON 必须忽略。
|
||||
|
||||
### 2.2 SKEL
|
||||
|
||||
识别顺序：
|
||||
|
||||
1. 对二进制头执行有界读取，尝试提取 hash 和版本字符串。
|
||||
2. 用候选版本 Runtime 插件执行只读探测。
|
||||
3. 必要时用已配置 Editor 的 info 命令验证。
|
||||
4. 多个版本都失败则要求用户选择版本，并标记为未确认。
|
||||
|
||||
解析必须限制字符串长度、数组大小和文件大小，损坏文件不能导致无限分配。
|
||||
|
||||
## 3. Editor 数据模型
|
||||
|
||||
```text
|
||||
EditorInstallation
|
||||
id
|
||||
displayName
|
||||
platform
|
||||
userSelectedPath
|
||||
canonicalExecutable
|
||||
discoverySource
|
||||
lastVerifiedAt
|
||||
baseVersion
|
||||
signatureStatus
|
||||
capabilities[]
|
||||
|
||||
EditorCapability
|
||||
versionLine // 3.8, 4.0, 4.1, 4.2, 4.3
|
||||
launchSelector // 可选 -u 参数或独立 executable
|
||||
status
|
||||
lastProbeResult
|
||||
```
|
||||
|
||||
同一个安装入口可以声明多个本地版本能力；多个安装入口也可以映射到同一版本。用户可为每个版本选择首选项。
|
||||
|
||||
## 4. 自动发现
|
||||
|
||||
### 4.1 macOS
|
||||
|
||||
优先位置：
|
||||
|
||||
```text
|
||||
/Applications/Spine.app
|
||||
~/Applications/Spine.app
|
||||
```
|
||||
|
||||
补充来源：
|
||||
|
||||
- 系统应用索引
|
||||
- 当前会话已知应用路径
|
||||
- 历史用户配置
|
||||
|
||||
用户选择 `.app` 时规范化为：
|
||||
|
||||
```text
|
||||
Spine.app/Contents/MacOS/Spine
|
||||
```
|
||||
|
||||
不递归扫描整个磁盘。
|
||||
|
||||
### 4.2 Windows
|
||||
|
||||
发现来源：
|
||||
|
||||
- HKLM/HKCU 安装与卸载注册信息
|
||||
- `Program Files`、`Program Files (x86)` 常见位置
|
||||
- `PATH`
|
||||
- 开始菜单快捷方式目标
|
||||
- 历史用户配置
|
||||
|
||||
CLI 优先选择 `Spine.com`。如果用户选择 `Spine.exe`，查找同目录同名 `.com`；找不到时允许保存，但状态为“GUI 路径，CLI 待验证”。
|
||||
|
||||
## 5. 自定义路径
|
||||
|
||||
用户可选择：
|
||||
|
||||
- macOS `.app`
|
||||
- 内部 Spine 可执行文件
|
||||
- Windows `Spine.com` 或 `Spine.exe`
|
||||
- 包含上述文件的目录
|
||||
|
||||
保存前执行路径规范化：
|
||||
|
||||
- 解析相对路径
|
||||
- 清理多余分隔符
|
||||
- 保留用户显示路径
|
||||
- 保存 canonical path
|
||||
- 记录文件标识和修改时间，用于发现安装被替换
|
||||
|
||||
路径移动或升级后，不自动删除旧配置，而是标记失效并允许重新定位。
|
||||
|
||||
## 6. 验证步骤
|
||||
|
||||
### 6.1 静态验证
|
||||
|
||||
- 文件存在且不是目录。
|
||||
- 当前用户可执行。
|
||||
- macOS bundle 结构或 Windows 同目录文件合理。
|
||||
- 可选检查平台签名；旧版签名异常只警告，不直接否定合法安装。
|
||||
|
||||
### 6.2 基础进程验证
|
||||
|
||||
使用参数数组执行 `--version`，捕获：
|
||||
|
||||
- 退出码
|
||||
- 标准输出和错误输出
|
||||
- 启动耗时
|
||||
- 报告版本
|
||||
|
||||
设置短超时，只终止该次探测进程。
|
||||
|
||||
### 6.3 版本能力验证
|
||||
|
||||
对用户配置的目标版本执行实际启动探测。若使用 `-u <version>` 选择器：
|
||||
|
||||
- 只允许已确认在本地缓存中存在的精确版本，例如资源线为 4.3 时选择本地最新的 `4.3.23`。
|
||||
- 不使用 `--force`。
|
||||
- 不使用 `latest`、`stable`、`beta` 或 `x.x.xx` 版本选择器。
|
||||
- 不由 DateToSpine 发起下载。
|
||||
- 缓存缺失时不启动 Spine Launcher，直接报告“本地未缓存目标版本”，从源头避免 Launcher 下载。
|
||||
- 启动进程前再次检查精确缓存文件，避免检测后被移动导致意外联网。
|
||||
|
||||
当前 macOS 检查 `~/Library/Application Support/Spine/updates`，Windows 检查 `%APPDATA%/Spine/updates` 和 `%LOCALAPPDATA%/Spine/updates`。后续若 Spine 改变缓存结构，需要同步更新并重新做断网回归。
|
||||
|
||||
### 6.4 导入冒烟测试
|
||||
|
||||
在用户点击“深度验证”或首次转换前，可在临时目录执行小型导入：
|
||||
|
||||
- 输入与版本匹配的最小测试数据。
|
||||
- 输出到临时目录。
|
||||
- 验证退出码和 `.spine` 可再次读取。
|
||||
- 完成立即清理临时结果。
|
||||
|
||||
发行版不能使用未获再分发确认的官方测试资产作为内置冒烟样本；需要自有最小样本或仅对用户当前资源执行验证。
|
||||
|
||||
## 7. 状态与用户提示
|
||||
|
||||
```text
|
||||
Available
|
||||
PathMissing
|
||||
NotExecutable
|
||||
NotSpine
|
||||
CliCompanionMissing
|
||||
VersionMismatch
|
||||
VersionNotPrepared
|
||||
NotActivated
|
||||
ProbeTimedOut
|
||||
PermissionDenied
|
||||
LaunchFailed
|
||||
Unknown
|
||||
```
|
||||
|
||||
每个状态需要：
|
||||
|
||||
- 用户可读说明
|
||||
- 技术详情
|
||||
- 可执行的修复建议
|
||||
- 是否允许预览
|
||||
- 是否允许转换
|
||||
|
||||
资源全部载入后，主界面顶部直接显示当前资源的结果，例如“可转换 · Spine 4.3.23”或“缺少 Spine 4.1”。自动检测失败时，转换按钮才变为“指定 Spine 路径”。
|
||||
|
||||
## 8. 离线要求
|
||||
|
||||
DateToSpine 本身不联网。完整转换成立的前提是对应 Editor 版本已经在本机准备好并能在断网时运行。
|
||||
|
||||
离线验收必须在网络被禁用的独立测试环境进行，不能只通过代码审查推断。
|
||||
@@ -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 输出摘要；成功时弹窗显示完整输出目录。
|
||||
@@ -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 和混合模式分别有测试样本。
|
||||
- 缺失纹理不会导致崩溃，并能在画布上定位缺失项。
|
||||
- 拔网后所有预览功能保持可用。
|
||||
@@ -0,0 +1,67 @@
|
||||
# Atlas 官方解包设计
|
||||
|
||||
## 1. 唯一实现
|
||||
|
||||
纹理恢复只调用用户本机、已授权且与数据版本匹配的 Spine Editor Texture Unpacker。项目不实现 Atlas 裁切、旋转、透明边恢复或图片重采样，也不存在自研兼容解包路径。
|
||||
|
||||
```text
|
||||
本地匹配版本 Spine Texture Unpacker
|
||||
↓
|
||||
输出校验
|
||||
↓
|
||||
失败并向用户显示具体原因
|
||||
```
|
||||
|
||||
官方解包失败、输出缺失或校验失败时，任务直接失败，不尝试以另一套图片算法生成看似成功的结果。
|
||||
|
||||
## 2. 官方调用
|
||||
|
||||
```text
|
||||
Spine -u <本地精确缓存版本>
|
||||
-i <Atlas 纹理页目录>
|
||||
-o <临时 images 目录>
|
||||
-c <Atlas 文件>
|
||||
```
|
||||
|
||||
- 只允许精确的本地缓存版本，禁止 `latest`、通配版本和强制下载参数。
|
||||
- 原始 Atlas 与纹理页保持只读。
|
||||
- 输出先写入任务临时目录，验证成功后再发布。
|
||||
- 记录退出码与进程输出；成功退出后仍检查是否实际生成图片。
|
||||
- 最终结果不复制原始 `.atlas` 和打包纹理页。
|
||||
|
||||
## 3. PMA 处理
|
||||
|
||||
PMA 转换同样交给官方 Texture Unpacker：
|
||||
|
||||
- 开启“去除预乘 Alpha”时，原样传入源 Atlas，由 Spine 根据 `pma: true` 执行官方转换。
|
||||
- 关闭时，仅建立临时 Atlas 元数据副本并把 `pma: true` 改为 `pma: false`，使官方解包器保留打包像素。
|
||||
- 不再由 Qt 解码、逐像素处理或重新保存解包图片，避免 JPEG/WebP 二次有损编码以及错误的重复去预乘。
|
||||
|
||||
## 4. Atlas Scale 与工程导入
|
||||
|
||||
Texture Unpacker 输出的是 Atlas 实际打包尺寸。例如页面声明 `scale: 0.5` 时，解出的图片也是原图的一半像素尺寸，这不是压缩错误。
|
||||
|
||||
生成工程时必须把同一 Atlas 传给官方导入参数：
|
||||
|
||||
```text
|
||||
Spine -u <本地精确缓存版本>
|
||||
-i <骨骼 JSON 或 SKEL>
|
||||
-s <Atlas 的 scale 数值>
|
||||
-o <目标 .spine>
|
||||
--import
|
||||
```
|
||||
|
||||
`-s <数值>` 让 Editor 按 Atlas 的打包比例缩放骨骼、附件和动画数据。使用数值是为了兼容 3.8—4.3；旧版 Editor 不接受 Atlas 路径作为 `-s` 的值。遗漏此参数会形成“附件位置沿用原始坐标、解包图片却是半尺寸”的工程，表现为局部图片缩小和脱节。
|
||||
|
||||
多页 Atlas 必须使用一致的 `scale`；未声明时按 `1.0`。若各页比例不同，任务会说明原因并停止，避免生成内部尺寸不一致的工程。
|
||||
|
||||
## 5. 验证与失败规则
|
||||
|
||||
每次解包后至少检查：
|
||||
|
||||
- 进程正常结束。
|
||||
- `images/` 中存在可识别的图片输出。
|
||||
- 最终 `.spine` 文件存在且非空。
|
||||
- 3.8、4.0、4.1、4.2、4.3 均使用对应版本 Editor 做导入回归。
|
||||
|
||||
任何一步失败都弹窗显示所属阶段和 Spine 返回的原因，不切换到非官方实现。
|
||||
@@ -0,0 +1,195 @@
|
||||
# 测试策略
|
||||
|
||||
## 1. 测试目标
|
||||
|
||||
测试需要证明四件事：
|
||||
|
||||
1. 每个目标版本使用正确 Runtime 和 Editor。
|
||||
2. 预览结果在语义和视觉上正确。
|
||||
3. 生成 `.spine` 后运行时主体数据没有意外丢失。
|
||||
4. 断网、损坏输入和批量失败情况下行为安全。
|
||||
|
||||
## 2. 测试层级
|
||||
|
||||
### 2.1 单元测试
|
||||
|
||||
不启动 Spine Editor：
|
||||
|
||||
- 版本字符串解析
|
||||
- Spine JSON schema 识别
|
||||
- SKEL 头部有界探测
|
||||
- Atlas parser
|
||||
- 自动配对评分
|
||||
- 路径规范化和逃逸防护
|
||||
- 输出重名策略
|
||||
- 恢复状态机
|
||||
- 报告序列化
|
||||
- Editor 命令参数生成
|
||||
|
||||
### 2.2 组件测试
|
||||
|
||||
- 每个 Runtime 插件独立加载相应版本资源。
|
||||
- Texture Provider 解码 PNG、JPG、WebP。
|
||||
- 统一 draw list 校验。
|
||||
- 官方解包结果的尺寸、Alpha 与 golden image 对比。
|
||||
- Editor Locator 使用模拟注册信息和目录结构。
|
||||
|
||||
### 2.3 Editor 集成测试
|
||||
|
||||
需要本地已激活的 Spine Editor：
|
||||
|
||||
- `--version` 探测
|
||||
- JSON 导入
|
||||
- SKEL 导入
|
||||
- Atlas 官方解包
|
||||
- 临时工程导出规范化 JSON
|
||||
- 最终 `.spine` 可重新读取
|
||||
- 取消、超时和错误码映射
|
||||
|
||||
### 2.4 端到端测试
|
||||
|
||||
从目录扫描开始，经过预览、确认、解包、导入、验证和发布。检查输入目录完全未改变。
|
||||
|
||||
## 3. 版本矩阵
|
||||
|
||||
每个版本至少覆盖：
|
||||
|
||||
| 版本 | JSON | SKEL | 预览 | 官方解包 | 工程生成 | 语义回读 |
|
||||
|---|---:|---:|---:|---:|---:|---:|
|
||||
| 3.8.20+ | 必测 | 必测 | 必测 | 必测 | 必测 | 必测 |
|
||||
| 4.0.x | 必测 | 必测 | 必测 | 必测 | 必测 | 必测 |
|
||||
| 4.1.x | 必测 | 必测 | 必测 | 必测 | 必测 | 必测 |
|
||||
| 4.2.x | 必测 | 必测 | 必测 | 必测 | 必测 | 必测 |
|
||||
| 4.3.x | 必测 | 必测 | 必测 | 必测 | 必测 | 必测 |
|
||||
|
||||
## 4. 功能样本矩阵
|
||||
|
||||
- Region
|
||||
- Unweighted/Weighted/Linked Mesh
|
||||
- IK、Transform、Path constraints
|
||||
- Clipping
|
||||
- Deform
|
||||
- Draw order
|
||||
- Events
|
||||
- 多动画、多 Skin
|
||||
- Two Color Tint
|
||||
- Normal/Additive/Multiply/Screen
|
||||
- 单页、多页 Atlas
|
||||
- PMA、Straight Alpha
|
||||
- PNG、JPG/JPEG、WebP
|
||||
- Atlas scale
|
||||
- Polygon packing
|
||||
|
||||
不要求一个样本覆盖所有功能，采用可追踪的样本能力清单。
|
||||
|
||||
## 5. 官方测试资源
|
||||
|
||||
开发阶段从官方 `EsotericSoftware/spine-runtimes` 仓库各版本分支取得对应样例：
|
||||
|
||||
```text
|
||||
3.8
|
||||
4.0
|
||||
4.1
|
||||
4.2
|
||||
4.3
|
||||
```
|
||||
|
||||
每份资源由 manifest 记录：
|
||||
|
||||
```text
|
||||
case id
|
||||
source repository
|
||||
branch
|
||||
commit hash
|
||||
relative paths
|
||||
data version
|
||||
features
|
||||
expected animations/skins/counts
|
||||
license reference
|
||||
sha256
|
||||
```
|
||||
|
||||
规则：
|
||||
|
||||
- 不用 4.3 资源测试旧 Runtime。
|
||||
- 测试基于固定 commit，不追随浮动分支。
|
||||
- 官方资源只放在开发测试缓存或 CI 临时空间。
|
||||
- `tests/fixtures/external/` 不进入发行打包输入。
|
||||
- 发行产物检查中把官方资源文件名和哈希作为禁止项。
|
||||
- 未经许可确认，不把官方资源提交到对外发布制品。
|
||||
|
||||
## 6. 自有与生成测试数据
|
||||
|
||||
除官方样例外，创建可自由分发的最小数据用于：
|
||||
|
||||
- 安装后冒烟测试
|
||||
- 损坏输入测试
|
||||
- Unicode 路径测试
|
||||
- 极限尺寸测试
|
||||
- 输出命名冲突测试
|
||||
|
||||
生成数据的来源、生成脚本和许可必须清晰。若生成 `.spine`/导出数据需要 Spine Editor，构建产物仍按许可审查。
|
||||
|
||||
## 7. 视觉回归
|
||||
|
||||
在固定 viewport、背景、时间点、Skin 和动画下截图：
|
||||
|
||||
- 与批准的 golden image 比较。
|
||||
- 对 JPG/WebP 使用合理像素误差。
|
||||
- 对 Alpha 边缘增加专门区域检测。
|
||||
- 单独测试 PMA 黑边、Straight Alpha 白边问题。
|
||||
- GPU 差异造成的小量误差采用阈值，不使用完全逐字节相等。
|
||||
|
||||
## 8. 语义回归
|
||||
|
||||
转换前后生成规范摘要并比较：
|
||||
|
||||
```text
|
||||
bones
|
||||
slots
|
||||
skins
|
||||
attachments by type
|
||||
constraints by type
|
||||
animations and duration
|
||||
events
|
||||
deform timelines
|
||||
draw-order timelines
|
||||
```
|
||||
|
||||
Nonessential 数据单独报告，不与运行时语义失败混合。
|
||||
|
||||
## 9. 异常与安全测试
|
||||
|
||||
- 截断 SKEL
|
||||
- 超长字符串和伪造数组长度
|
||||
- 深层/异常 JSON
|
||||
- Atlas 路径逃逸
|
||||
- 重复 region 和页面
|
||||
- 缺失或损坏图片
|
||||
- 巨大图片和解压炸弹式输入
|
||||
- Editor 路径失效
|
||||
- Editor 未激活
|
||||
- 子进程卡住、崩溃、返回非零
|
||||
- 用户在各阶段取消
|
||||
- 输出目录无权限或空间不足
|
||||
|
||||
## 10. 离线测试
|
||||
|
||||
在 macOS 和 Windows 上分别执行：
|
||||
|
||||
1. 准备并验证对应 Editor 版本。
|
||||
2. 禁用网络接口或在隔离环境阻断网络。
|
||||
3. 启动 DateToSpine。
|
||||
4. 完成扫描、预览、官方解包、生成和回读。
|
||||
5. 记录任何网络连接尝试。
|
||||
6. 确认不存在 CDN、在线字体、在线 Shader、更新或遥测依赖。
|
||||
|
||||
## 11. 发行物检查
|
||||
|
||||
对最终 `.app/.dmg/.exe/installer` 解包检查：
|
||||
|
||||
- 不含官方测试素材。
|
||||
- 不含 Spine Editor。
|
||||
- 包含 Runtime License 和 Third-Party Notices。
|
||||
- 包含所需 Qt 图片插件，WebP 在断网环境可用。
|
||||
- 不含开发日志、绝对源码路径、测试缓存或调试密钥。
|
||||
@@ -0,0 +1,133 @@
|
||||
# 离线、打包与许可
|
||||
|
||||
## 1. 离线定义
|
||||
|
||||
DateToSpine 的“全功能离线”定义为：
|
||||
|
||||
- 应用本身不建立网络连接。
|
||||
- 不使用 CDN、远程字体、远程 Shader、WebView 在线页面或在线 API。
|
||||
- 不在运行时下载 Qt、Runtime、图片解码器或其他依赖。
|
||||
- 不上传用户资源、路径、日志或统计数据。
|
||||
- 不包含自动更新和联网遥测。
|
||||
- 用户已经准备好的匹配版本 Spine Editor 可在断网环境中完成转换。
|
||||
|
||||
Spine Editor 是外部前置软件。DateToSpine 不控制 Editor 自身的授权策略，但必须在断网验收中验证既有激活和已缓存版本能够完成流程。
|
||||
|
||||
## 2. 构建期与运行期网络
|
||||
|
||||
- 开发机可以联网取得依赖和官方测试资源。
|
||||
- 正式依赖必须锁定版本和校验值。
|
||||
- 可复现构建应支持从内部或本地依赖缓存构建。
|
||||
- 最终应用运行时不得使用网络。
|
||||
- CI 下载的官方测试资源不进入打包阶段的输入集合。
|
||||
|
||||
## 3. macOS 打包
|
||||
|
||||
目标：
|
||||
|
||||
- Apple Silicon 原生包。
|
||||
- Intel 或 Universal 2 是否首发，由原型性能和构建环境决定。
|
||||
- `.app` 和 `.dmg`。
|
||||
- Qt framework、platform plugin、image plugin、Runtime 插件和本地资源完整部署。
|
||||
- 正式发行执行代码签名和 notarization；这是发布流程，不是最终应用运行时联网依赖。
|
||||
|
||||
应用不得修改用户的 Spine.app 或其缓存。
|
||||
|
||||
## 4. Windows 打包
|
||||
|
||||
目标：
|
||||
|
||||
- Windows 10/11 x64。
|
||||
- MSVC 2022 v143。
|
||||
- 使用 `/MD` 与 Qt 官方构建一致。
|
||||
- 部署 MSVC Runtime、Qt platform plugin、imageformats 和 Runtime 插件。
|
||||
- 安装包格式在原型后从 MSIX、WiX/MSI 或 Inno Setup 中确定。
|
||||
- 正式发行建议代码签名。
|
||||
|
||||
最终用户不需要安装 CMake、Visual Studio 或 Qt SDK。
|
||||
|
||||
## 5. Runtime 许可
|
||||
|
||||
项目集成官方 Spine Runtimes 时必须遵守：
|
||||
|
||||
- [Spine Runtimes License Agreement](https://esotericsoftware.com/spine-runtimes-license)
|
||||
- [Spine Editor License Agreement](https://esotericsoftware.com/spine-editor-license)
|
||||
|
||||
发行前需要法务或产品负责人确认最终分发模式。技术实现至少保证：
|
||||
|
||||
- `licenses/` 保存完整、未修改的 Runtime 许可文本。
|
||||
- 安装包包含 Runtime 许可和版权声明。
|
||||
- About/关于 页面提供第三方许可入口。
|
||||
- 不隐藏用户需要合法 Spine 许可的前提。
|
||||
- 不分发 Spine Editor、激活信息或 Editor 更新文件。
|
||||
- Runtime 插件不作为通用 SDK 对外提供开发接口。
|
||||
|
||||
## 6. 官方测试资源
|
||||
|
||||
已确认规则：
|
||||
|
||||
- 官方 GitHub 仓库资源只用于开发、兼容性测试和 CI。
|
||||
- 官方测试资源不进入最终安装包。
|
||||
- 打包清单不包含 `tests/fixtures/external/`。
|
||||
- 发行检查使用路径、文件名和 SHA-256 禁止列表防止误打包。
|
||||
- 测试报告可记录资源 case id 和哈希，但不嵌入资源文件。
|
||||
|
||||
## 7. 第三方依赖清单
|
||||
|
||||
每个依赖记录：
|
||||
|
||||
```text
|
||||
name
|
||||
version/commit
|
||||
source URL
|
||||
license
|
||||
modified or unmodified
|
||||
linked statically or dynamically
|
||||
included platforms
|
||||
notices path
|
||||
```
|
||||
|
||||
至少包括：
|
||||
|
||||
- Qt 6
|
||||
- Spine Runtimes 3.8/4.0/4.1/4.2/4.3
|
||||
- 测试框架
|
||||
- 可能引入的日志或打包依赖
|
||||
|
||||
新增依赖必须经过：离线可部署性、许可证、维护状态、体积和安全评审。
|
||||
|
||||
## 8. 网络禁止措施
|
||||
|
||||
- 不链接应用层 HTTP 客户端，除非未来需求重新评审。
|
||||
- 资源加载器只接受本地文件协议。
|
||||
- 代码扫描阻止 CDN URL 和动态依赖下载逻辑。
|
||||
- 集成测试在网络阻断环境运行。
|
||||
- 打包后执行连接监控测试。
|
||||
|
||||
文档中的官方链接仅供人阅读，不会被应用自动访问。
|
||||
|
||||
## 9. 发行目录白名单
|
||||
|
||||
打包采取白名单而不是“复制整个构建目录”：
|
||||
|
||||
```text
|
||||
application executable
|
||||
Qt runtime libraries/plugins
|
||||
dts runtime plugins
|
||||
icons/translations/shaders
|
||||
licenses/notices
|
||||
user documentation
|
||||
```
|
||||
|
||||
明确排除：
|
||||
|
||||
```text
|
||||
tests/
|
||||
official sample assets
|
||||
source repository metadata
|
||||
developer caches
|
||||
temporary recovery jobs
|
||||
Spine Editor binaries
|
||||
activation information
|
||||
debug-only symbols（独立保存，不进入普通安装包）
|
||||
```
|
||||
@@ -0,0 +1,131 @@
|
||||
# 开发计划
|
||||
|
||||
## 1. 开发原则
|
||||
|
||||
- 先验证风险，再建设完整 UI。
|
||||
- 每个阶段有可运行结果和退出标准。
|
||||
- 未通过技术关卡时不扩大代码量掩盖问题。
|
||||
- 文档、测试和代码同步更新。
|
||||
- 当前文档批准后才进入功能开发。
|
||||
|
||||
## 2. 阶段 0：技术原型
|
||||
|
||||
### 目标
|
||||
|
||||
验证决定产品能否成立的核心问题。
|
||||
|
||||
### 工作项
|
||||
|
||||
1. 在 macOS 上发现并验证已安装 Spine Editor。
|
||||
2. 验证自定义 `.app`/可执行文件路径。
|
||||
3. 调用 3.8、4.0、4.1、4.2、4.3 本地版本。
|
||||
4. 为五个版本各构建最小 `spine-cpp` adapter。
|
||||
5. 用 JSON、SKEL、Atlas 和纹理加载一帧预览数据。
|
||||
6. 验证 QOpenGLWidget 绘制 Region、Mesh、Clipping 和混合模式。
|
||||
7. 验证官方 Texture Unpacker。
|
||||
8. 验证 SKEL → 临时 `.spine` → JSON → 设置 images → 最终 `.spine`。
|
||||
9. 验证断网运行。
|
||||
10. 在 Windows/MSVC 至少完成构建和 Editor CLI 冒烟测试。
|
||||
|
||||
### 技术关卡
|
||||
|
||||
- 五套 Runtime 可以隔离构建并通过统一 ABI 加载。
|
||||
- 五个版本至少各有一个 JSON/SKEL 可预览。
|
||||
- 本地 Editor 路径和版本能可靠识别。
|
||||
- JSON/SKEL 可以生成可回读 `.spine`。
|
||||
- 图片路径能自动关联，或明确证明需要采用哪种降级方案。
|
||||
- 官方解包和 PMA 行为被记录。
|
||||
- 断网时已准备版本可执行完整流程。
|
||||
|
||||
任何关卡失败都先更新架构决策，不进入大规模 UI 开发。
|
||||
|
||||
## 3. 阶段 1：工程骨架与领域模型
|
||||
|
||||
- CMake Presets 和平台 toolchain。
|
||||
- 目录、target 和第三方依赖边界。
|
||||
- `AssetGroup`、`SpineVersion`、`RecoveryJob`。
|
||||
- 文件系统、进程和报告接口。
|
||||
- 基础错误码和状态机。
|
||||
- 单元测试框架和 CI 基线。
|
||||
- 自研代码行数检查。
|
||||
|
||||
退出标准：macOS/Windows Debug 与 Release 构建通过，核心模型测试通过。
|
||||
|
||||
## 4. 阶段 2：扫描、配对与预检
|
||||
|
||||
- 递归扫描。
|
||||
- JSON/SKEL 版本识别。
|
||||
- Atlas parser。
|
||||
- 页面解析和图片校验。
|
||||
- 资源组配对评分。
|
||||
- 手动修正模型。
|
||||
- Unicode、长路径和安全边界。
|
||||
|
||||
退出标准：官方样例和异常样例能形成确定、可解释的资源组。
|
||||
|
||||
## 5. 阶段 3：离线预览器
|
||||
|
||||
- 五个 Runtime 插件完整实现。
|
||||
- Texture Provider。
|
||||
- OpenGL 批次渲染。
|
||||
- 动画、Skin、Seek、速度控制。
|
||||
- 调试显示。
|
||||
- 视觉回归测试。
|
||||
|
||||
退出标准：五个版本功能矩阵通过，拔网预览正常。
|
||||
|
||||
## 6. 阶段 4：Editor 管理与转换
|
||||
|
||||
- macOS/Windows 自动发现。
|
||||
- 自定义路径 UI。
|
||||
- 版本能力映射。
|
||||
- Spine CLI 封装。
|
||||
- JSON/SKEL 导入。
|
||||
- 图片路径规范化。
|
||||
- 语义回读验证。
|
||||
- 原子发布和恢复报告。
|
||||
|
||||
退出标准：五个版本端到端转换通过，输入未改变。
|
||||
|
||||
## 7. 阶段 5：Atlas 解包
|
||||
|
||||
- 官方解包器唯一流程。
|
||||
- 官方结果验证。
|
||||
- PMA、Scale、rotate、offset、多页和 polygon packing。
|
||||
- PNG/JPG/WebP 测试。
|
||||
|
||||
退出标准：官方解包与失败原因可观察、可报告，且各版本具有视觉回归。
|
||||
|
||||
## 8. 阶段 6：批处理和用户体验
|
||||
|
||||
- 任务队列、取消和失败隔离。
|
||||
- 批量重名策略。
|
||||
- 进度、日志和错误建议。
|
||||
- 设置迁移和会话恢复。
|
||||
- 中英文界面。
|
||||
- 无障碍和高 DPI 检查。
|
||||
|
||||
## 9. 阶段 7：发布准备
|
||||
|
||||
- macOS/Windows 安装包。
|
||||
- Qt 和图片插件部署。
|
||||
- Runtime 许可与 Third-Party Notices。
|
||||
- 官方测试资源排除检查。
|
||||
- 离线端到端测试。
|
||||
- 签名、公证和干净机器安装测试。
|
||||
- 性能、内存和损坏输入测试。
|
||||
|
||||
## 10. 建议评审点
|
||||
|
||||
每阶段完成后提交：
|
||||
|
||||
- 功能演示
|
||||
- 自动测试结果
|
||||
- 新增风险
|
||||
- 文件长度报告
|
||||
- 依赖与许可变更
|
||||
- 下一阶段范围
|
||||
|
||||
## 11. 编码顺序建议
|
||||
|
||||
开始开发后的第一个提交不应是完整项目 UI，而应是阶段 0 的最小原型和实验记录。技术原型通过后，再固化公共接口和正式目录。
|
||||
@@ -0,0 +1,102 @@
|
||||
# 风险与架构决策
|
||||
|
||||
## 1. 风险台账
|
||||
|
||||
| ID | 风险 | 影响 | 应对 |
|
||||
|---|---|---|---|
|
||||
| R-01 | 不同 Spine 版本二进制格式不兼容 | 错误预览或导入失败 | 五套匹配 Runtime；Editor 主/次版本强校验 |
|
||||
| R-02 | 3.8 早期格式变化 | 部分 3.8 文件无法读取 | 正式范围从 3.8.20 开始；旧文件尽力识别 |
|
||||
| R-03 | SKEL 不含可直接修改的图片路径 | 生成工程显示 Missing | Editor 双重导入/导出原型；输出布局降级方案 |
|
||||
| R-04 | 五套 Runtime 符号/API 冲突 | 无法链接或运行不稳定 | 独立动态模块、隐藏符号、稳定 C ABI |
|
||||
| R-05 | 损坏输入使 Runtime 崩溃 | 主程序退出 | 有界预检、模糊测试；必要时改 helper process |
|
||||
| R-06 | Spine Launcher 缺少目标缓存版本 | 离线转换失败 | 版本能力预检；不自动下载；明确修复提示 |
|
||||
| R-07 | Editor 自身的联网或授权行为 | 离线验收失败 | 真正断网测试；明确前置条件；不修改或绕过 Editor |
|
||||
| R-08 | PMA/WebP 边缘错误 | 预览或解包出现色边 | 格式矩阵与 Alpha 视觉回归；Alpha 处理交给官方解包器 |
|
||||
| R-09 | Polygon-packed Mesh 难以还原原图 | 图片包含邻近像素或裁切错误 | 仅使用官方解包器；失败时报告限制并终止 |
|
||||
| R-10 | 官方测试素材误入安装包 | 许可与体积风险 | 打包白名单、哈希禁止清单、发行物解包检查 |
|
||||
| R-11 | Qt/Runtime 许可遗漏 | 无法合规发行 | 依赖清单、licenses、About 页面、发行关卡 |
|
||||
| R-12 | 自定义路径和 Unicode 处理错误 | Editor 无法启动 | 参数数组、canonical path、双平台路径测试 |
|
||||
| R-13 | 巨大资源耗尽内存 | 卡死或崩溃 | 输入限制、预算检查、按需解码、可取消任务 |
|
||||
| R-14 | 跨补丁 Editor 行为变化 | 同一主/次版本结果不同 | 记录实际补丁；固定测试矩阵；报告转换环境 |
|
||||
|
||||
## 2. 已接受架构决策
|
||||
|
||||
### ADR-001：生成 `.spine` 使用官方 Editor
|
||||
|
||||
- 状态：接受
|
||||
- 决策：调用本地已授权 Spine Editor，不自行写 `.spine`。
|
||||
- 原因：`.spine` 是编辑工程格式；官方 CLI 已提供数据导入能力。
|
||||
|
||||
### ADR-002：版本范围为 3.8.20+ 至 4.3
|
||||
|
||||
- 状态：接受
|
||||
- 决策：3.8.20+、4.0、4.1、4.2、4.3；不支持 3.8 以下。
|
||||
- 原因：覆盖目标游戏资源，同时控制旧格式维护成本。
|
||||
|
||||
### ADR-003：预览进入首版
|
||||
|
||||
- 状态：接受
|
||||
- 决策：用户确认转换前必须可离线预览。
|
||||
- 原因：避免批量生成后才发现配对、Scale、Alpha 或版本错误。
|
||||
|
||||
### ADR-004：每个主/次版本独立 Runtime
|
||||
|
||||
- 状态：接受
|
||||
- 决策：五个 Runtime 插件，通过统一 C ABI 接入。
|
||||
- 原因：官方要求 Runtime 与数据主/次版本同步，API 也会变化。
|
||||
|
||||
### ADR-005：仅使用官方 Atlas 解包
|
||||
|
||||
- 状态：接受
|
||||
- 决策：官方 Texture Unpacker 是唯一纹理解包实现；失败时任务失败。
|
||||
- 原因：官方对自身 Atlas、PMA、旋转和多边形打包语义最权威，且软件以前置正版 Spine 为使用条件。
|
||||
|
||||
### ADR-006：运行期全离线
|
||||
|
||||
- 状态：接受
|
||||
- 决策：无 CDN、下载、遥测、资源上传和在线 API。
|
||||
- 原因：资源敏感性、稳定性和用户要求。
|
||||
|
||||
### ADR-007：官方测试资源不发行
|
||||
|
||||
- 状态：接受
|
||||
- 决策：官方资源只用于开发/CI，最终安装包不包含。
|
||||
- 原因：用户明确要求，并减少许可与安装体积风险。
|
||||
|
||||
### ADR-008：Qt 6 + CMake + MSVC/Apple Clang
|
||||
|
||||
- 状态：接受
|
||||
- 决策：主程序 C++20，CMake 3.25+，Windows MSVC v143。
|
||||
- 原因：跨平台 UI、进程管理、图片插件和成熟构建生态。
|
||||
|
||||
## 3. 原型后待决策事项
|
||||
|
||||
### ADR-P01：Runtime 插件还是 helper process
|
||||
|
||||
默认先验证动态插件。若损坏文件可导致不可接受的进程级崩溃，则采用 helper process 隔离。
|
||||
|
||||
### ADR-P02：macOS 架构
|
||||
|
||||
首发 Apple Silicon 或 Universal 2，根据目标用户和五套 Runtime 构建成本决定。
|
||||
|
||||
### ADR-P03：测试框架
|
||||
|
||||
Qt Test 与 Catch2 二选一，以 Runtime 插件和参数化兼容矩阵的便利性为主要标准。
|
||||
|
||||
### ADR-P04：SKEL 图片路径自动化方案
|
||||
|
||||
由 Editor 双重导入/导出原型结果决定正式流程及是否存在可接受降级。
|
||||
|
||||
### ADR-P05：Windows 安装器
|
||||
|
||||
在 MSIX、WiX/MSI、Inno Setup 中选择，需满足离线安装、签名和干净卸载。
|
||||
|
||||
## 4. 决策变更规则
|
||||
|
||||
变更已接受决策时必须记录：
|
||||
|
||||
- 变更原因
|
||||
- 新证据或测试结果
|
||||
- 对范围、兼容性和许可的影响
|
||||
- 数据迁移或设置迁移方案
|
||||
- 负责人和日期
|
||||
@@ -0,0 +1,93 @@
|
||||
# 阶段 0 技术原型记录
|
||||
|
||||
## 记录日期
|
||||
|
||||
2026-09-07
|
||||
|
||||
## 当前结论
|
||||
|
||||
首批工程骨架已经建立并在 macOS Apple Silicon 上通过构建测试。此阶段证明多版本 Runtime 隔离、基础输入识别、本地 Editor 发现和跨平台进程抽象可以按既定架构继续推进；尚未证明完整动画预览或 `.spine` 恢复流程。
|
||||
|
||||
## 本机环境
|
||||
|
||||
- Apple Clang 17
|
||||
- CMake 4.4.3（项目最低要求仍为 3.25）
|
||||
- Ninja 1.13.2
|
||||
- Qt Base 6.11.2
|
||||
- Qt Image Formats 6.11.2
|
||||
- Spine Launcher 4.3.06 Apple Silicon
|
||||
- Launcher 当前观察到启动 Spine Editor 3.8.99 Professional
|
||||
|
||||
只安装 Qt Base 与 Qt Image Formats，没有安装 Qt WebEngine、Location、NetworkAuth 等与产品无关的 Qt 元组件。
|
||||
|
||||
## 固定 Runtime 提交
|
||||
|
||||
| Runtime | 官方分支 | 提交 |
|
||||
|---|---|---|
|
||||
| 3.8 | `3.8` | `8b4844bd4b193ba9e54487ed397a777993cbad56` |
|
||||
| 4.0 | `4.0` | `425ce416bb218b28caeec47b317aa57cd7140375` |
|
||||
| 4.1 | `4.1` | `77a5db0ec6d16331f5efbaa7662bba9355bd3424` |
|
||||
| 4.2 | `4.2` | `e7dc1435fa4a0083ab431f1b28e083c14a1f5c68` |
|
||||
| 4.3 | `4.3` | `4309c05c287d3f15da778e68f5d2a483fe10a6a3` |
|
||||
|
||||
当前只展开各分支的 `spine-cpp` 源码。4.3 官方 Spineboy 资源仅用于开发测试，不进入安装目标和发行包。
|
||||
|
||||
## 已实现
|
||||
|
||||
- CMake/C++20 工程和 macOS、Windows Preset。
|
||||
- 标准 C++ 核心库，不依赖 Qt。
|
||||
- Spine 版本值对象和正式支持范围判断。
|
||||
- JSON 最小 Spine schema 与版本探测。
|
||||
- SKEL 二进制头部 hash/version 有界读取。
|
||||
- Atlas 多页、page、region、PMA、scale、rotate、bounds/legacy 字段基础解析。
|
||||
- macOS 常见 Spine 路径发现和 `.app` 规范化。
|
||||
- Windows 常见路径骨架和 `.exe` → `.com` 规范化。
|
||||
- 不经过 shell 的 POSIX/Windows 子进程执行器。
|
||||
- 超时后终止本软件启动的整个子进程树。
|
||||
- Launcher 版本与实际 Editor 版本分离解析。
|
||||
- 五个 Runtime 独立静态目标和动态 adapter。
|
||||
- 稳定 C ABI 版本与 metadata 加载验证。
|
||||
- 极简 Qt 桌面外壳：资源拖放/选择、资源切换、动画切换和一键转换。
|
||||
- Editor 自动发现；仅在自动发现失败时请求自定义路径。
|
||||
- 4.3 Runtime 已实际加载官方 JSON、SKEL 和 Atlas，并输出动画/Skin/骨骼元数据。
|
||||
- 4.3 Runtime 已输出裁剪后的纹理三角形，Qt 画布可循环播放并切换真实动画。
|
||||
- 4.3 beta 后缀版本和新版 SKEL 文件头识别。
|
||||
- CLI：Editor 发现、路径探测、数据版本检查。
|
||||
|
||||
## 构建与测试结果
|
||||
|
||||
- `cmake --preset macos-debug`：通过。
|
||||
- `cmake --build --preset macos-debug`：通过。
|
||||
- 五个官方 Runtime：通过 Apple Clang 编译。
|
||||
- 五个 Runtime adapter：通过动态加载和 ABI/版本检查。
|
||||
- 核心单元测试：全部通过。
|
||||
- 官方 Spineboy JSON/SKEL 真实加载测试：通过，识别到 11 个动画。
|
||||
- Qt 应用 offscreen 启动冒烟测试：通过。
|
||||
|
||||
Spine 4.3 上游源码在 Apple Clang 下产生一条未覆盖枚举值的 warning。第三方源码没有被修改，该警告暂不影响构建，后续记录在上游警告基线中。
|
||||
|
||||
## 实际 Editor 探测发现
|
||||
|
||||
直接执行本机 `Spine --version` 时先报告 Launcher 4.3.06，随后启动 3.8.99 Professional。旧版 launcher 在当前系统产生字体兼容警告，并且探测可能长时间不退出。
|
||||
|
||||
因此代码已经采用：
|
||||
|
||||
- 分离解析 Launcher 和 Editor 版本。
|
||||
- 探测超时。
|
||||
- 进程树终止。
|
||||
- “已观察到 Spine 但探测超时”独立状态。
|
||||
|
||||
仅看到 Launcher 版本不能代表目标 Editor 版本可用。
|
||||
|
||||
## 尚未完成的阶段 0 关卡
|
||||
|
||||
1. 对 3.8—4.2 执行真实资源预览。
|
||||
2. 目标 Editor 版本选择与离线缓存能力验证。
|
||||
3. 官方 Texture Unpacker 调用与结果验证。
|
||||
4. JSON/SKEL 到 `.spine` 的端到端恢复。
|
||||
5. SKEL 图片路径双重导入/导出方案验证。
|
||||
6. Windows MSVC 构建与真实 Editor 测试。
|
||||
|
||||
## 下一步
|
||||
|
||||
先扩展 Runtime C ABI，以 4.3 adapter 实现真实资源加载、动画/Skin 元数据与 draw list；通过后把版本差异分别适配到 4.2、4.1、4.0 和 3.8。随后接 Qt OpenGL 预览画布，再进入 Editor 导入和官方解包流水线。
|
||||
@@ -0,0 +1,26 @@
|
||||
# 极简界面阶段记录
|
||||
|
||||
## 交互结论
|
||||
|
||||
主界面已经收敛为“拖入、预览、切换动画、一键转换”。版本号、文件格式、校验状态和 Editor 管理等技术信息不再常驻显示。
|
||||
|
||||
## 当前可查看产出
|
||||
|
||||
- 空状态支持拖入 `.json`、`.skel`、`.atlas`、纹理或整个目录。
|
||||
- 多套资源通过顶部单一选择框切换。
|
||||
- 4.3 官方 Spineboy JSON/SKEL 可读取，动画选择框显示 11 个真实动画。
|
||||
- 当前画布已使用官方 4.3 Runtime 绘制真实骨骼姿态，并默认循环播放 `idle`。
|
||||
- 动画下拉框会实际切换 Runtime 动画，不再只是显示名称。
|
||||
- “一键转换为 .spine”按钮已接入本地 Spine Editor 自动发现和异步导入入口。
|
||||
- 自动发现 Editor 失败时才弹出路径选择，不再提供独立管理窗口。
|
||||
- 软件没有网络请求。
|
||||
|
||||
界面截图：`阶段产出/极简界面-资源已载入.png`。
|
||||
|
||||
## 尚未宣称完成
|
||||
|
||||
- 当前真实动画渲染已覆盖 4.3，3.8—4.2 尚未接入统一绘制接口。
|
||||
- 一键转换入口已形成，但官方解包、图片路径恢复和生成物回读验证尚未串成最终流水线。
|
||||
- 3.8—4.2 Runtime 仍需补齐真实数据加载和绘制接口。
|
||||
|
||||
这些未完成项不会通过增加设置页面暴露给用户，仍保持后台自动化和极简主流程。
|
||||
@@ -0,0 +1,40 @@
|
||||
# 4.3 动画预览阶段记录
|
||||
|
||||
## 阶段结果
|
||||
|
||||
4.3 官方 Runtime 已从“只读资源信息”升级为真实动画绘制。主界面现在会直接显示骨骼角色，而不是整张 Atlas 纹理。
|
||||
|
||||
## 已实现
|
||||
|
||||
- Runtime ABI 增加动画选择、逐帧更新和绘制命令接口。
|
||||
- 4.3 adapter 创建 `Skeleton`、`AnimationState` 和 `SkeletonRenderer`。
|
||||
- 输出世界坐标、UV、颜色、索引、纹理路径和混合模式。
|
||||
- Runtime 内部完成 Mesh 和 Clipping 处理。
|
||||
- Qt 独立预览画布按纹理三角形绘制并自动适应窗口。
|
||||
- 支持 Normal、Additive、Multiply、Screen 四种混合模式映射。
|
||||
- 默认循环播放动画列表第一项；列表为空时保持静态姿态，不启动动画播放。
|
||||
- 用户切换下拉框时立即切换动画并循环播放。
|
||||
- 预览画布尺寸独立于每帧骨骼边界；首次加载后锁定视口，动画过程不再忽大忽小。
|
||||
- 默认以画布可容纳的最大比例显示，并保留少量安全边距。
|
||||
- 滚动鼠标中键时，以鼠标所在位置为中心缩放画布。
|
||||
- 单击鼠标中键时重置缩放和画布位置。
|
||||
- 按住鼠标右键拖动时平移画布；右键短按时回到中心。
|
||||
- 软件绘制路径消除了逐三角形抗锯齿造成的 Mesh 接缝。
|
||||
|
||||
## 测试证据
|
||||
|
||||
官方 Spineboy 4.3 JSON 测试已经验证：
|
||||
|
||||
- 动画可被选择。
|
||||
- 每帧能产生绘制命令、顶点和三角形索引。
|
||||
- 绘制命令引用的纹理文件存在。
|
||||
- 时间推进后世界坐标确实发生变化。
|
||||
- JSON 和 SKEL 仍能重复加载。
|
||||
|
||||
阶段截图：`阶段产出/骨骼动画预览-4.3.png`。
|
||||
|
||||
固定画布截图：`阶段产出/固定画布最大显示-4.3.png`。
|
||||
|
||||
## 后续范围
|
||||
|
||||
下一步复用相同 ABI 分别适配 4.2、4.1、4.0 和 3.8。各版本仍使用独立官方 Runtime，不把跨版本差异塞入界面代码。
|
||||
@@ -0,0 +1,81 @@
|
||||
# 离线转换与多版本回归记录
|
||||
|
||||
## 1. 本阶段结果
|
||||
|
||||
- 资源载入完成后自动检测匹配版本线，并在顶部显示是否可转换。
|
||||
- 4.3 资源在本机使用已缓存的 Spine `4.3.23`，不再把资源导出补丁号直接传给 Launcher。
|
||||
- 只传精确缓存版本；禁止 `latest`、通配版本和 `--force`。
|
||||
- 缓存缺失时不启动 Spine，转换任务内部也会二次拦截。
|
||||
- 成功和失败都显示弹窗；失败弹窗包含具体阶段与进程输出摘要。
|
||||
- 最终结果只包含 `.spine` 和 `images/`，不包含原始 Atlas 或打包纹理页。
|
||||
- 底部增加“去除预乘 Alpha”开关，默认关闭。
|
||||
|
||||
界面产出：[离线转换与去预乘开关.png](阶段产出/离线转换与去预乘开关.png)
|
||||
|
||||
## 2. 输出结构
|
||||
|
||||
```text
|
||||
选择的输出位置/
|
||||
spineboy-pro/
|
||||
spineboy-pro.spine
|
||||
images/
|
||||
head.png
|
||||
torso.png
|
||||
...
|
||||
```
|
||||
|
||||
同名目录存在时使用 `-2`、`-3` 后缀。所有内容先写入同一输出磁盘的临时目录，校验成功后再整体发布；失败不会留下伪成功目录。
|
||||
|
||||
## 3. Alpha 处理
|
||||
|
||||
官方 CLI 没有独立的去预乘开关，而是读取 Atlas 的 `pma` 值。为让 3.8—4.3 具有统一、可控的行为：
|
||||
|
||||
1. 原始 Atlas 与纹理页始终只读。
|
||||
2. 开启开关时原样传入 Atlas，由官方 Texture Unpacker 根据 `pma` 完成转换。
|
||||
3. 关闭开关时建立临时 Atlas 元数据副本，将 `pma:true` 改为 `pma:false`，再由官方解包器保留打包像素。
|
||||
4. 不使用 Qt 对输出图片做逐像素变换或重新编码。
|
||||
5. 临时 Atlas 随任务工作区清理，不进入结果目录。
|
||||
|
||||
## 4. 工程图片尺寸问题
|
||||
|
||||
已确认根因不是官方解包器压缩图片。测试 Atlas 声明 `scale: 0.5`，官方解包得到的 `head.png` 为 136×149、`front-shin.png` 为 41×92，符合实际打包尺寸。旧流程导入骨骼数据时没有传 Atlas Scale，导致附件坐标保持原始尺寸，而图片只有打包尺寸，于是局部图片缩小、脱节。
|
||||
|
||||
修复后的工程导入读取 Atlas 的 `scale`，再增加 `-s <数值>`，由匹配版本 Spine Editor 统一缩放骨骼、附件与动画数据。使用数值可以兼容不接受 Atlas 路径参数的 4.0 等旧版 Editor。
|
||||
|
||||
## 5. 多版本预览回归
|
||||
|
||||
每条版本线使用对应官方 `spine-cpp` 和该分支的 Spineboy 开发样本。样本仅用于开发测试，不进入安装包。
|
||||
|
||||
| 版本 | JSON | SKEL | 动画选择 | 绘制帧 |
|
||||
|---|---|---|---|---|
|
||||
| 3.8 | 通过 | 通过 | 通过 | 通过 |
|
||||
| 4.0 | 通过 | 通过 | 通过 | 通过 |
|
||||
| 4.1 | 通过 | 通过 | 通过 | 通过 |
|
||||
| 4.2 | 通过 | 通过 | 通过 | 通过 |
|
||||
| 4.3 | 通过 | 通过 | 通过 | 通过 |
|
||||
|
||||
3.8—4.1 共享一个旧版绘制适配层，4.2 和 4.3 使用各自 Runtime 自带的 `SkeletonRenderer`，避免将版本差异堆叠到主界面代码。
|
||||
|
||||
### 5.1 旧版 UV 方向修正
|
||||
|
||||
3.8—4.2 的 Runtime 输出沿用 Y 轴向上的世界坐标，而当前 Qt 画布以左上角为原点。适配层在输出预览顶点时对这些版本执行 `y = -y`；旧版 UV 已经与 Runtime 的三角形顶点顺序配套，不能再次翻转。4.3 已符合当前预览器方向，不执行该转换。
|
||||
|
||||
修复后截图：[旧版预览方向修复-4.2.png](阶段产出/旧版预览方向修复-4.2.png)
|
||||
|
||||
## 6. 本机实际转换回归
|
||||
|
||||
所有命令均选择已经存在的精确缓存版本：
|
||||
|
||||
| 资源线 | 本地 Editor | JSON 导入 | SKEL 导入 | 解包图片数 |
|
||||
|---|---:|---:|---:|---:|
|
||||
| 3.8 | 3.8.99 | 前一轮通过；本轮缓存不可用 | 前一轮通过；本轮缓存不可用 | 40（前一轮） |
|
||||
| 4.0 | 4.0.64 | 55,295 字节 | 58,616 字节 | 40 |
|
||||
| 4.1 | 4.1.24 | 55,483 字节 | 58,908 字节 | 40 |
|
||||
| 4.2 | 4.2.43 | 50,811 字节 | 54,940 字节 | 40 |
|
||||
| 4.3 | 4.3.23 | 49,603 字节 | 49,905 字节 | 40 |
|
||||
|
||||
4.2 A/B 回导验证：未传比例时 `hip.y=247.27`、前胫骨长度为 `128.77`；传 `-s 0.5` 后分别为 `123.64` 和 `64.39`，Mesh 顶点也同步减半，而图片维持官方解包尺寸。这说明工程数据与图片比例已恢复一致。
|
||||
|
||||
本轮 3.8 缓存文件在回归前已不可用，ARM Launcher 无法加载旧 x86 版本，因此遵守离线约束，没有尝试联网补齐。3.8 官方样本不声明 Atlas `scale`，修复路径会使用 `1.0`，与原导入行为一致；待本机重新具备可运行的 3.8 Editor 后仍需补跑本轮实机导入。
|
||||
|
||||
自动测试与完整构建通过。官方测试资源仍位于开发期 `third_party` 目录，安装规则只复制 Runtime 许可文件。
|
||||
@@ -0,0 +1,61 @@
|
||||
# DateToSpine 开发文档
|
||||
|
||||
## 文档状态
|
||||
|
||||
- 状态：技术原型开发中，极简主界面已形成
|
||||
- 文档基线：2026-09-07
|
||||
- 当前目录包含设计文档、C++/Qt 工程、Runtime 适配器和自动测试
|
||||
|
||||
## 产品概述
|
||||
|
||||
DateToSpine 是一个面向 macOS 和 Windows 的离线桌面工具，用于扫描、预览并批量恢复 Spine 游戏运行时资源：
|
||||
|
||||
```text
|
||||
.skel/.json + .atlas/.atlas.txt + texture pages
|
||||
↓
|
||||
可编辑的 .spine 工程
|
||||
```
|
||||
|
||||
软件内置匹配版本的官方 `spine-cpp` Runtime 以实现转换前预览。生成 `.spine` 时，用户电脑必须已经安装、激活并准备好与资源版本匹配的 Spine Editor。
|
||||
|
||||
## 已确认的产品决策
|
||||
|
||||
1. 正式支持 Spine `3.8.20+`、`4.0.x`、`4.1.x`、`4.2.x`、`4.3.x`。
|
||||
2. 不支持 Spine 3.8 以下版本。
|
||||
3. 转换前必须支持离线预览，用户确认后才生成 `.spine`。
|
||||
4. 五个 Spine 主/次版本使用各自对应的官方 Runtime。
|
||||
5. 生成 `.spine` 必须调用本地已授权的 Spine Editor，不自行编写或逆向 `.spine` 文件。
|
||||
6. Atlas 纹理只使用 Spine 官方 Texture Unpacker 解包，不提供自研兜底。
|
||||
7. 软件运行期不使用 CDN、在线 API、在线依赖下载、遥测或资源上传。
|
||||
8. 官方测试资源仅用于开发和 CI 测试，不进入最终安装包。
|
||||
9. 最终安装包只携带 Runtime 许可、第三方许可和必要声明，不携带 Spine Editor 或官方示例资源。
|
||||
10. 自研源文件按职责拆分，禁止出现数千行的业务代码文件。
|
||||
11. 主界面只保留拖入资源、预览/动画切换和一键转换；仅在 Editor 自动识别失败时请求路径。
|
||||
|
||||
## 文档索引
|
||||
|
||||
- [01-产品需求.md](01-产品需求.md)：产品范围、用户流程和验收标准
|
||||
- [02-系统架构.md](02-系统架构.md)：技术架构、模块边界和代码约束
|
||||
- [03-版本识别与编辑器检测.md](03-版本识别与编辑器检测.md)：版本识别、本地 Editor 检测和自定义路径
|
||||
- [04-恢复流水线.md](04-恢复流水线.md)：恢复流水线、输出规则和错误处理
|
||||
- [05-离线预览器.md](05-离线预览器.md)：多版本 Runtime 与离线预览器
|
||||
- [06-图集解包设计.md](06-图集解包设计.md)：官方唯一解包、PMA 与 Atlas Scale 设计
|
||||
- [07-测试策略.md](07-测试策略.md)：测试矩阵、官方测试资源管理和验收
|
||||
- [08-离线打包与许可.md](08-离线打包与许可.md)：离线、发行与许可要求
|
||||
- [09-开发计划.md](09-开发计划.md)：阶段计划、技术关卡与完成定义
|
||||
- [10-风险与架构决策.md](10-风险与架构决策.md)：风险台账与架构决策记录
|
||||
- [11-阶段0技术原型记录.md](11-阶段0技术原型记录.md)：首批代码、构建证据和后续关卡
|
||||
- [12-极简界面阶段记录.md](12-极简界面阶段记录.md)：精简后的界面范围、当前产出与未完成项
|
||||
- [13-四点三动画预览记录.md](13-四点三动画预览记录.md)：4.3 真实骨骼绘制、动画切换和测试证据
|
||||
- [14-离线转换与多版本回归记录.md](14-离线转换与多版本回归记录.md)：本地版本门禁、完整输出、PMA 开关和 3.8—4.3 回归证据
|
||||
|
||||
## 官方参考资料
|
||||
|
||||
- [Spine Command Line Interface](https://en.esotericsoftware.com/spine-command-line-interface)
|
||||
- [Importing skeleton data](https://esotericsoftware.com/blog/Importing-skeleton-data)
|
||||
- [Spine versioning](https://esotericsoftware.com/spine-versioning)
|
||||
- [spine-cpp Runtime Documentation](https://esotericsoftware.com/spine-cpp)
|
||||
- [Spine JSON format](https://esotericsoftware.com/spine-json-format)
|
||||
- [Spine binary format](https://esotericsoftware.com/spine-binary-format)
|
||||
- [Spine Runtimes repository](https://github.com/EsotericSoftware/spine-runtimes)
|
||||
- [Spine Runtimes License](https://esotericsoftware.com/spine-runtimes-license)
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 130 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 387 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 134 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 169 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 952 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 124 KiB |
Reference in New Issue
Block a user