# 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 的例外通道。详见 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 不穿透）：

```bash
node -e "require('fs').rmSync('games/<name>', { recursive: true, force: true })"
```
或先单独移除 junction（`rmdir games/<name>/assets/framework`）再删工程目录。