SpineParticlesWeb/DateToSpine/docs/06-图集解包设计.md

Atlas 官方解包设计

1. 唯一实现

纹理恢复只调用用户本机、已授权且与数据版本匹配的 Spine Editor Texture Unpacker。项目不实现 Atlas 裁切、旋转、透明边恢复或图片重采样，也不存在自研兼容解包路径。

本地匹配版本 Spine Texture Unpacker
                 ↓
             输出校验
                 ↓
       失败并向用户显示具体原因

官方解包失败、输出缺失或校验失败时，任务直接失败，不尝试以另一套图片算法生成看似成功的结果。

2. 官方调用

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 传给官方导入参数：

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