# 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 返回的原因，不切换到非官方实现。