docs(spec): Spine 规则改按 Cocos 原生资源模型,贴图豁免同尺寸约束

旧项目自行集成 Spine 是 gameabc 引擎缺陷所致,对新框架无参考价值。
Cocos 用 sp.SkeletonData 复合资源;区域坐标记在 .atlas 内而非 .meta,
故 Spine 贴图可变尺寸,校验须跳过尺寸检查以免误报。
新增待实测项 4:整套替换后 uuid 关联是否自洽。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-27 20:57:19 +08:00
co-authored by Claude Opus 5
parent c826df1108
commit 24e05189c9
@@ -158,10 +158,16 @@ override 下每个文件的路径,必须能在 `framework/ui/` 下找到同路
| 同名、override 自带 `.meta`(**例外通道**) | ✅ 拷贝两者,把框架默认 meta 的 `uuid` 覆写进去 |
| 扩展名/格式不一致(png → jpg) | ❌ 报错中止 |
| **非图片**(音效 / 字体):同名替换 | ✅ 换内容,`.meta` 原封不动,**不做尺寸校验** |
| **Spine**:`.json` + `.atlas` + `.png` 三件套 | ✅ 须**整套一起**覆盖,缺任一件即 ❌ 报错中止 |
| **Spine**(`sp.SkeletonData`):骨骼数据 + atlas + 贴图 | ✅ 须**整套一起**覆盖,缺任一件即 ❌ 报错中止 |
| 框架有、子游戏未覆盖 | ✅ 正常,用默认(**不**强制全覆盖) |
**Spine 的特殊性**:三件套互相引用(`.json` 引 `.atlas`,`.atlas` 引 `.png`),只换其中一件会产生运行时错位或加载失败,且这种失败**不会在构建期暴露**。故强制整套覆盖,由校验兜住。
**Spine 的特殊性**:新框架使用 **Cocos 原生 Spine 支持**(`sp.Skeleton` / `sp.SkeletonData`)。
> 旧项目因 gameabc 引擎不支持 Spine 而自行集成(`SpineMgr.js` / `spine-canvas.js`),**该实现对新框架无参考价值**,资源组织方式不照搬。
在 Cocos 的资源模型里,`SkeletonData` 是一个由骨骼数据、atlas 与贴图共同构成的复合资源,三者互相引用(骨骼数据引 atlas,atlas 引贴图区域坐标)。只替换其中一件会导致运行时错位或加载失败,且这类失败**不会在构建期暴露**——故强制整套覆盖,由校验兜住。
**Spine 贴图豁免"同尺寸"约束**:普通图片要求同尺寸,是因为区域坐标记在 `.meta` 里;而 Spine 的区域坐标记在 `.atlas` 文件内,整套替换时三者自洽,故贴图尺寸可变。校验须对 Spine 贴图跳过尺寸检查,否则会误报。
**为什么必须保留 `.meta`**:UUID 存放在 `.meta` 中,删除后重新导入会生成新 UUID,导致框架 Prefab 对该资源的引用全部断裂。
@@ -313,6 +319,7 @@ npm run build-game <name> [--platform android]
| 1 | Cocos 3.8.8 的 Auto Atlas 确在**构建期**打包,构建前替换散图能被正确纳入图集 | 造一个 `.pac` 目录,替换其中一张散图后构建,检查产物图集内容 | 改为"图集整体作为覆盖单位",由子游戏提供整套 plist+png |
| 2 | 例外通道中,除顶层 `uuid` 外,图片 `.meta` 的 `subMetas`(spriteFrame 子 uuid)是否亦需同步覆写 | 用尺寸不同的图走例外通道,检查 Prefab 引用是否仍有效 | 合成脚本一并覆写 subMetas 的 uuid |
| 3 | `build-workspace/<name>/library/` 跨次构建复用是否可靠,资源被替换后增量导入是否正确刷新 | 连续两次 build-game,第二次改动 override,比对产物 | 放弃缓存,每次全量导入(仅影响耗时) |
| 4 | Cocos 的 `sp.SkeletonData` 在"整套替换内容、保留全部 `.meta`"后引用是否仍自洽(骨骼数据 ↔ atlas ↔ 贴图的 uuid 关联记在何处) | 用一套不同的 Spine 资源整套替换,检查场景内动画是否正常播放 | Spine 改走组件替换通道(子游戏注册自己的 `sp.Skeleton` 节点),不走资源覆盖 |
---