joywayerandClaude Opus 5
b6c9af25e5
对象 → 节点(坐标/锚点/九宫格/帧引用/flags/legacy), 层 → LayerDoc(bucket/背景/分组)。 manifest 含 ObjectID 全局索引 —— 子系统 C 移植 1773 处 set_self 调用的承重依赖。 真实数据回归护栏: 55 界面 / 991 节点, 一个对象都不得丢。 真实数据里有 10 个对象(如 3067/3068/3075/3076/3087/3088/3089/3145/388/3265)的 FrameIndex 超出其图的帧数(多帧图重导后帧数变少但对象未同步)——不抛错中止、不静默 钳到末帧,而是回退帧1 + 打 flags.frameIndexOutOfRange + 收进 convertAll 返回的 warnings 清单(objectId/layerId/imageFileId/frameIndex/frameCount/reason),真实 数据护栏钉死 warnings.length===10,数量漂移会被人工看到。另补一条背景判定用例: 非首位的满屏对象不应被误判为背景,钉住"层内首个+满屏"而非"只要满屏"的规则。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Monorepo 工具链
所有命令在 cocoscreator_projects/ 下用 npm run <script> 执行。
| 命令 | 作用 |
|---|---|
npm run new-game <name> |
从 templates/game-seed 克隆一个子游戏工程到 games/<name>，重置身份、铺 game/ 骨架、挂 framework junction |
npm run setup-links |
为 games/* 重建 assets/framework junction（clone 仓库后必跑一次） |
npm run check-cocos |
校验所有子游戏工程的 creator.version 与宿主 YouleNexus 一致（不一致退出码 1） |
npm run bump-cocos <version> |
批量改宿主+所有子游戏的 creator.version（之后仍需逐个用编辑器打开迁移） |
npm test |
运行工具链全部单元测试 |
npm run check-skin <name> |
校验子游戏 assets/game/override/ 是否合法（孤儿/尺寸不一致/Spine 缺件），不构建，秒级反馈 |
npm run build-game <name> [-- --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/<name>/assets/game/；协议一律引用docs/protocol/（spec §0.1）。 - 皮肤在构建期合成，不是运行时覆盖。子游戏把同名替换资源放
assets/game/override/， 路径须与framework/ui/逐字对应；只换内容、不带.meta（尺寸须一致），确需改尺寸才走 带 meta 的例外通道。详见 spec2026-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 不穿透）：
node -e "require('fs').rmSync('games/<name>', { recursive: true, force: true })"
或先单独移除 junction（rmdir games/<name>/assets/framework）再删工程目录。