From bed9b4f35d9a38a704cfac08adc38ee8687e20a8 Mon Sep 17 00:00:00 2001 From: Joywayer Date: Thu, 27 Aug 2026 22:48:03 +0800 Subject: [PATCH] =?UTF-8?q?docs(tools):=20=E7=9A=AE=E8=82=A4=E4=B8=8E?= =?UTF-8?q?=E6=9E=84=E5=BB=BA=E6=B5=81=E6=B0=B4=E7=BA=BF=E6=96=87=E6=A1=A3?= =?UTF-8?q?,=20=E5=9B=9E=E5=A1=AB=20library=20=E7=BC=93=E5=AD=98=E5=AE=9E?= =?UTF-8?q?=E6=B5=8B=E7=BB=93=E8=AE=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5 (1M context) --- cocoscreator_projects/scripts/README.md | 9 +++++++++ .../specs/2026-08-27-ui-asset-and-skin-design.md | 2 +- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/cocoscreator_projects/scripts/README.md b/cocoscreator_projects/scripts/README.md index fce472f..26a27d8 100644 --- a/cocoscreator_projects/scripts/README.md +++ b/cocoscreator_projects/scripts/README.md @@ -9,11 +9,20 @@ | `npm run check-cocos` | 校验所有子游戏工程的 `creator.version` 与宿主 `YouleNexus` 一致（不一致退出码 1） | | `npm run bump-cocos ` | 批量改宿主+所有子游戏的 `creator.version`（之后仍需逐个用编辑器打开迁移） | | `npm test` | 运行工具链全部单元测试 | +| `npm run check-skin ` | 校验子游戏 `assets/game/override/` 是否合法（孤儿/尺寸不一致/Spine 缺件），不构建，秒级反馈 | +| `npm run build-game [-- --platform android]` | 完整构建流水线：版本校验 → 实体化到 `build-workspace/` → 皮肤合成 → Cocos CLI 构建 → 写 `build-info.json` | ## 关键约束 - **framework 真源**唯一存放于 `YouleNexus/assets/framework`；各子游戏的 `assets/framework` 是指向它的 junction（不入库，见根 `.gitignore`）。clone 后跑 `setup-links` 重建。 - **Cocos 版本必须全 monorepo 统一**（junction 共享同一份资源，跨版本不兼容）。升级走 `bump-cocos` + 逐工程编辑器迁移，详见 spec §8。 - 子游戏私有内容只放 `games//assets/game/`；协议一律引用 `docs/protocol/`（spec §0.1）。 +- **皮肤在构建期合成**，不是运行时覆盖。子游戏把同名替换资源放 `assets/game/override/`， + 路径须与 `framework/ui/` 逐字对应；只换内容、不带 `.meta`（尺寸须一致），确需改尺寸才走 + 带 meta 的例外通道。详见 spec `2026-08-27-ui-asset-and-skin-design.md`。 +- **框架真源全程只读**：合成只发生在 `build-workspace/` 的临时工程副本里。 +- **发布链路不依赖 junction**：`build-game` 直接从 `YouleNexus/assets/framework` 拷贝真源， + CI clone 后无需先跑 `setup-links`。 +- 构建需环境变量 `COCOS_CREATOR` 指向 Cocos Creator 可执行文件（唯一来源，勿在脚本硬编码）。 ## ⚠️ 删除子游戏工程的注意事项 子游戏的 `assets/framework` 是指向框架真源的 junction。**不要用 `rm -rf` 删除整个子游戏工程**——git-bash 的 `rm -rf` 可能穿透 junction 误删框架真源。请用 Node 安全删除（对 junction 不穿透）： 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 dc6d01e..123b1b3 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 @@ -319,7 +319,7 @@ npm run build-game [--platform android] |---|---|---|---|---| | 1 | Cocos 3.8.8 的 Auto Atlas 确在**构建期**打包，构建前替换散图能被正确纳入图集 | 造一个 `.pac` 目录，替换其中一张散图后构建，检查产物图集内容 | 改为"图集整体作为覆盖单位"，由子游戏提供整套 plist+png | ⏸ **阻塞（非证伪）**。真正卡住的不是"构建能否跑完"，而是**"造不出一个真实的 Auto Atlas 资产"**：MCP `asset.create` 只支持 `url`/`content`/`overwrite`，没有资产类型参数；对 `.pac` 命名文件夹做 `refresh`/`reimport` 也不会把 `importer` 从 `"directory"` 转成 `"auto-atlas"`，多次独立尝试一致。（`editor.build`/`editor.open_build_panel` 确实也只打开构建面板要求人工点击——但项目自己的 `build-game.mjs` 已实现走 `CocosCreator.exe --project --build "platform=..."` 的官方无头 CLI 构建，不经过 MCP；只是本机 `COCOS_CREATOR` 未配置、也未定位到编辑器可执行文件，这条路本身也未验证可用，且即便可用也不能替代"创建 Auto Atlas"这一步——那始终是编辑器 Assets 面板 `Create > Auto Atlas` 的菜单命令，CLI 构建帮不上。）需人工在编辑器 GUI 内手动执行该菜单命令后再复测。**在此之前不得默认本假设成立去推进 Task 3 的图集相关设计。** | | 2 | 例外通道中，除顶层 `uuid` 外，图片 `.meta` 的 `subMetas`（spriteFrame 子 uuid）是否亦需同步覆写 | 用尺寸不同的图走例外通道，检查 Prefab 引用是否仍有效 | 合成脚本一并覆写 subMetas 的 uuid | 🟡 **部分验证，范围窄于本行原意**。实测的是更基础的前提：保留原 `.meta`、只换图片内容（同尺寸）后刷新，顶层 `uuid` 与全部 `subMetas.uuid` 均未变化；换成 128×128（仍不提供新 `.meta`，未走例外通道）后刷新，顶层 `uuid` 依旧不变，且 sprite-frame 子 meta 的 `width`/`height`/`rawWidth`/`rawHeight`/`vertices`/`uv` 被 Cocos 自动重算为 128×128（前后 meta 全文见 task-2-report.md）。**未验证**的是本行字面所指的例外通道场景（override 自带一份独立生成的 `.meta`，合成脚本只覆写顶层 `uuid`，问 `subMetas` 里的子 uuid 要不要也同步覆写）——因待验证项 1 阻塞、无法在真实 `.pac` 图集环境下复测，这条更精确的问题仍待专项验证。spec §3.2 的例外通道设计**维持不变**，不降级、不简化。 | -| 3 | `build-workspace//library/` 跨次构建复用是否可靠，资源被替换后增量导入是否正确刷新 | 连续两次 build-game，第二次改动 override，比对产物 | 放弃缓存，每次全量导入（仅影响耗时） | 未测——不在 Task 2 的 Step 1-8 范围内。`build-game.mjs` 本身已在本任务执行期间落地（`134f4c8`），但"连续两次构建、比对产物"这一实测动作未做，留待专项验证。 | +| 3 | `build-workspace//library/` 跨次构建复用是否可靠，资源被替换后增量导入是否正确刷新 | 连续两次 build-game，第二次改动 override，比对产物 | 放弃缓存，每次全量导入（仅影响耗时） | ⏸ **阻塞：缺构建环境**（2026-08-27，Task 8）。实测需要 `COCOS_CREATOR` 环境变量指向 Cocos Creator 3.8.8 可执行文件——本机未配置该变量，且 `where.exe CocosCreator.exe` 未能在 PATH 上定位到编辑器可执行文件，`build-game.mjs` 的实际构建步骤（内部调用 `CocosCreator.exe --project --build "platform=..."`）无法执行，因而无法运行"连续两次 build-game 比对耗时/产物"的实测动作。此外，`buildGame` 当前实现每次都会 `rmSync` 整个构建工作区（含 `library/`）后重新实体化，即便环境就绪，字面意义上的"library 跨次复用"在现有实现下也不成立——`library` 目录会随工作区一起被清空重建，第二次构建拿到的是全新的 `library`，不存在缓存复用可言。故本行结论有两层：(a) 环境阻塞，实测动作未能执行；(b) 静态阅读代码可确认现有实现未实现"保留 library 复用"的设计，若要验证复用效果需先改造 `buildGame` 为"不整体 rmSync 工作区、只刷新 assets"，这已超出本任务范围，留作 spec 结尾「后续计划衔接」中已列出的独立任务。**在此之前不得默认 library 复用已生效或已失效去做性能相关决策。** | | 4 | Cocos 的 `sp.SkeletonData` 在"整套替换内容、保留全部 `.meta`"后引用是否仍自洽（骨骼数据 ↔ atlas ↔ 贴图的 uuid 关联记在何处） | 用一套不同的 Spine 资源整套替换，检查场景内动画是否正常播放 | Spine 改走组件替换通道（子游戏注册自己的 `sp.Skeleton` 节点），不走资源覆盖 | ⏸ **阻塞：仓库无 Spine 素材**。`projects/*/assets/spine/` 全部为空，无任何可用 Spine 导出资源。`cocos_spine` 工具的全部 action（`info`/`list_animations`/`list_skins`/`set_animation`/`set_skin`/`set_property`/`set_data`/`add_socket`/`remove_socket`）都要求场景内已存在带 `sp.Skeleton` 组件的节点，无法凭空验证。已在 `framework/ui/README.md` 加提示，待第一套真实 Spine 资源到位后专项验证，**不假定其可行**。 | ---