docs(spec): detail theme and single-game packaging
This commit is contained in:
@@ -284,6 +284,46 @@ GameHost 生命周期与 GameSession 一致。dispose 后继续调用必须显
|
||||
|
||||
子游戏通过 ViewModel 给公共 UI 提供纯数据；禁止查找公共 Prefab 节点、改写组件或依赖节点层级。
|
||||
|
||||
#### 9.2.1 界面所有权判定
|
||||
|
||||
每个界面区域在实现前必须归入且只能归入以下一种所有权：
|
||||
|
||||
- 平台公共界面：所有游戏语义相同，由 framework 提供完整 Prefab、Presenter 和默认主题。
|
||||
- 平台界面扩展槽：主体语义公共，局部展示因玩法不同，由 framework 定义 Slot 和生命周期，游戏提供 Slot 内容。
|
||||
- 游戏专属界面：规则、状态和交互都属于玩法，完整放在 `assets/game`，framework 只负责进入、退出和公共遮罩层。
|
||||
|
||||
禁止把完整公共 Prefab 复制到每款游戏后长期修改。若大多数游戏都必须替换同一公共区域，说明边界划分错误，应把该区域降为 Slot 或重新归类为游戏专属界面。
|
||||
|
||||
#### 9.2.2 主题解析规则
|
||||
|
||||
主题只在 Composition Root 创建应用时解析一次，不在运行时切换。解析顺序固定：
|
||||
|
||||
```text
|
||||
FrameworkThemeDefaults（完整值集）
|
||||
-> GameThemeDelta（只声明差异）
|
||||
-> 生成只读 EffectiveTheme
|
||||
```
|
||||
|
||||
- `FrameworkThemeDefaults` 是所有公共 Token 的唯一默认来源，必须提供完整值，不允许下游猜默认值。
|
||||
- `GameThemeDelta` 只能覆盖公开 Token；出现未知 Token、错误类型或无效资源键时构建失败。
|
||||
- `EffectiveTheme` 创建后只读，同一运行周期不可被游戏或 UI 改写。
|
||||
- GameEntry 未声明某个可选覆盖，明确表示使用 FrameworkThemeDefaults；这是主题来源定义的合成语义，不属于下游兜底。
|
||||
- theme 文件不得 import framework UI 实现或引用公共 Prefab 节点。
|
||||
|
||||
`SemanticAssetKey` 同样采用完整默认映射 + 游戏差量映射。SDK 中只出现逻辑键和纯数据描述；Cocos UUID、SpriteFrame、Prefab 等引擎对象由 framework 的资源适配器解析，不泄漏到纯 contracts。
|
||||
|
||||
#### 9.2.3 Extension Slot 契约
|
||||
|
||||
每个 Slot 必须定义：
|
||||
|
||||
- 稳定 Slot ID 和用途。
|
||||
- 输入 ViewModel 的字段、类型和更新时机。
|
||||
- 挂载层级、尺寸约束和可见性所有者。
|
||||
- create/attach/update/detach/dispose 生命周期。
|
||||
- 资源加载和释放责任。
|
||||
|
||||
游戏只返回自身 Slot 工厂或逻辑资源地址，不获得 framework 父节点之外的节点引用。framework 在 detach/dispose 后不得继续调用 Slot；游戏 Slot 不得访问兄弟 Slot 或公共 Prefab 内部节点。
|
||||
|
||||
### 9.3 路径覆盖的定位
|
||||
|
||||
现有 `assets/game/override` 构建期合成机制保留，用于已迁移皮肤和必须保持 UUID 的资源替换，但定位为兼容通道：
|
||||
@@ -305,6 +345,16 @@ GameHost 生命周期与 GameSession 一致。dispose 后继续调用必须显
|
||||
- 子游戏私有内容只在 `games/<name>/assets/game`。
|
||||
- 所有工程使用同一 Cocos Creator 版本。
|
||||
|
||||
`templates/game-seed` 是薄模板，不包含 framework 副本。它只包含：
|
||||
|
||||
- Cocos 工程身份和必要 settings。
|
||||
- `assets/app/CompositionRoot.ts` 固定组合入口。
|
||||
- 可编译的 `assets/game/GameEntry.ts`、空主题差量和游戏目录骨架。
|
||||
- framework junction 的预期挂载位置。
|
||||
- SDK conformance、import-boundary 和主题校验测试骨架。
|
||||
|
||||
`new-game` 从薄模板创建工程、生成新 UUID 并建立 junction。模板创建后，游戏团队只维护 `assets/game`；不得在工程内形成第二份 framework 源码。
|
||||
|
||||
### 10.2 发布期
|
||||
|
||||
沿用现有 `build-game <name>` 和 materialize 思路：
|
||||
@@ -327,6 +377,20 @@ dist/<name>/<name>.zip
|
||||
|
||||
发布链路不依赖 junction。构建脚本直接从 framework 真源和所选游戏复制实体文件。
|
||||
|
||||
构建步骤和输入所有权固定为：
|
||||
|
||||
1. 根据显式 game name 解析唯一 `games/<name>`，不存在、重复或名称非法立即失败。
|
||||
2. 校验宿主与所选游戏 Cocos 版本一致。
|
||||
3. 创建 `build-workspace/<name>`；复制所选游戏工程，但跳过 junction、缓存和历史 build。
|
||||
4. 从 `YouleNexus/assets/framework` 复制当前 framework 实体文件。
|
||||
5. 校验工作区 assets 顶层只包含薄模板允许项、`framework` 和当前 `game`；禁止出现其它游戏目录或入口。
|
||||
6. 解析 GameEntry、ThemeDelta、SemanticAssetMap 和 Slot 声明，生成只读有效配置。
|
||||
7. 仅在工作区执行 legacy override 合成，随后执行孤儿、尺寸、meta、Spine 和资源键校验。
|
||||
8. 调用 Cocos Creator CLI 构建这个自包含工程。
|
||||
9. 对实际构建产物执行内容和依赖审计，通过后才生成 ZIP。
|
||||
|
||||
构建工具不得先把所有游戏聚合到一个 Cocos 工程再依赖引擎裁剪；“其它游戏从未进入构建工作区”是包隔离的第一保证。
|
||||
|
||||
### 10.3 ZIP 验收
|
||||
|
||||
每个 ZIP 必须：
|
||||
@@ -338,12 +402,39 @@ dist/<name>/<name>.zip
|
||||
- 包含 `build-info.json`，至少记录 game、framework commit、Cocos 版本、构建时间、目标平台和资源合成摘要。
|
||||
- 通过资源引用、入口唯一性、脚本编译、敏感文件和其它游戏残留审计。
|
||||
|
||||
`build-info.json` 还应记录：
|
||||
|
||||
- Game SDK contract digest。
|
||||
- EffectiveTheme digest。
|
||||
- GameEntry route/game identity 摘要。
|
||||
- override 命中数量和无效覆盖数量。
|
||||
- ZIP 文件清单 digest。
|
||||
|
||||
Package Audit 至少执行：
|
||||
|
||||
- 输入审计：工作区没有其它 `games/<name>` 的 GameEntry、主题或资源。
|
||||
- 入口审计：只有一个有效 GameEntry 和一个 Composition Root。
|
||||
- 依赖审计：所有动态资源地址都能在当前 ZIP 解析，不指向远程 framework 或其它游戏。
|
||||
- 身份审计：从 monorepo 游戏清单取得其它游戏 key，扫描产物路径、manifest 和配置，不得命中。
|
||||
- 完整性审计：ZIP 解压后可从发布入口启动；`build-info.json` 与实际内容 digest 一致。
|
||||
|
||||
审计失败时不得生成或覆盖正式 dist ZIP；失败产物只保留在明确的临时诊断目录。
|
||||
|
||||
## 11. framework 升级模型
|
||||
|
||||
### 11.1 普通升级
|
||||
|
||||
framework 的代码、公共 Prefab、公共资源和默认主题都在唯一真源修改。只要 Game SDK、ThemeToken、SemanticAssetKey 和 Slot 契约保持兼容，各子游戏源码无需修改，只需分别与新 framework 重新构建 ZIP。
|
||||
|
||||
不同升级类型的影响规则：
|
||||
|
||||
- framework 代码实现：运行 framework 测试、外部黄金回放和全部游戏 conformance；游戏不复制代码。
|
||||
- 公共 Prefab 内部结构：只要 ViewModel/Slot 契约不变，游戏不可见；执行公共界面视觉与交互回归。
|
||||
- 公共默认资源：重新生成 EffectiveTheme；对所有游戏执行资源键和 legacy override 影响检查。
|
||||
- 新增公开 ThemeToken/AssetKey：必须同时在 FrameworkThemeDefaults 提供权威默认值，旧游戏无需修改。
|
||||
- 删除或改变公开 Token/AssetKey/Slot：属于破坏性升级，不能作为普通升级合并。
|
||||
- Cocos Creator 版本：按 §11.3 整体升级，不允许单个游戏先行长期分叉。
|
||||
|
||||
升级门禁：
|
||||
|
||||
```text
|
||||
@@ -411,6 +502,8 @@ framework tests
|
||||
|
||||
- ViewModel/Slot contract 测试。
|
||||
- 资源覆盖和 SemanticAssetKey 完整性检查。
|
||||
- ThemeDelta 合成顺序、未知 Token、错误类型和 EffectiveTheme 只读测试。
|
||||
- Slot create/attach/update/detach/dispose 顺序与重复销毁测试。
|
||||
- 已迁移 Prefab 的关键视觉和交互回归。
|
||||
- 每游戏 Cocos 构建矩阵。
|
||||
- ZIP 内容、唯一 GameEntry、无其它游戏残留和自包含运行审计。
|
||||
|
||||
Reference in New Issue
Block a user