From 24e05189c975b12b9f8d4bc5e83a369900694f06 Mon Sep 17 00:00:00 2001 From: Joywayer Date: Thu, 27 Aug 2026 20:57:19 +0800 Subject: [PATCH] =?UTF-8?q?docs(spec):=20Spine=20=E8=A7=84=E5=88=99?= =?UTF-8?q?=E6=94=B9=E6=8C=89=20Cocos=20=E5=8E=9F=E7=94=9F=E8=B5=84?= =?UTF-8?q?=E6=BA=90=E6=A8=A1=E5=9E=8B=EF=BC=8C=E8=B4=B4=E5=9B=BE=E8=B1=81?= =?UTF-8?q?=E5=85=8D=E5=90=8C=E5=B0=BA=E5=AF=B8=E7=BA=A6=E6=9D=9F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 旧项目自行集成 Spine 是 gameabc 引擎缺陷所致，对新框架无参考价值。 Cocos 用 sp.SkeletonData 复合资源；区域坐标记在 .atlas 内而非 .meta， 故 Spine 贴图可变尺寸，校验须跳过尺寸检查以免误报。 新增待实测项 4：整套替换后 uuid 关联是否自洽。 Co-Authored-By: Claude Opus 5 (1M context) --- .../specs/2026-08-27-ui-asset-and-skin-design.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/superpowers/specs/2026-08-27-ui-asset-and-skin-design.md b/docs/superpowers/specs/2026-08-27-ui-asset-and-skin-design.md index e4bc022..42e3918 100644 --- a/docs/superpowers/specs/2026-08-27-ui-asset-and-skin-design.md +++ b/docs/superpowers/specs/2026-08-27-ui-asset-and-skin-design.md @@ -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 [--platform android] | 1 | Cocos 3.8.8 的 Auto Atlas 确在**构建期**打包，构建前替换散图能被正确纳入图集 | 造一个 `.pac` 目录，替换其中一张散图后构建，检查产物图集内容 | 改为"图集整体作为覆盖单位"，由子游戏提供整套 plist+png | | 2 | 例外通道中，除顶层 `uuid` 外，图片 `.meta` 的 `subMetas`（spriteFrame 子 uuid）是否亦需同步覆写 | 用尺寸不同的图走例外通道，检查 Prefab 引用是否仍有效 | 合成脚本一并覆写 subMetas 的 uuid | | 3 | `build-workspace//library/` 跨次构建复用是否可靠，资源被替换后增量导入是否正确刷新 | 连续两次 build-game，第二次改动 override，比对产物 | 放弃缓存，每次全量导入（仅影响耗时） | +| 4 | Cocos 的 `sp.SkeletonData` 在"整套替换内容、保留全部 `.meta`"后引用是否仍自洽（骨骼数据 ↔ atlas ↔ 贴图的 uuid 关联记在何处） | 用一套不同的 Spine 资源整套替换，检查场景内动画是否正常播放 | Spine 改走组件替换通道（子游戏注册自己的 `sp.Skeleton` 节点），不走资源覆盖 | ---