docs: 新增 Cocos Creator 平台框架与子游戏架构设计 spec
Monorepo + junction 共享框架、6 层单向依赖零耦合、配置+资源覆盖换肤、 种子工程克隆建子游戏、Cocos 版本全 monorepo 统一升级。 接口（IGameModule/GameContext）方向已定、精确签名待后续细化。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
@@ -0,0 +1,232 @@
|
||||
# Cocos Creator 平台框架与子游戏架构设计
|
||||
|
||||
- **日期**：2026-06-28
|
||||
- **状态**：设计已确认，待转实施计划（writing-plans）
|
||||
- **范围**：友乐棋牌平台在 Cocos Creator 下的新一代「平台框架 + 子游戏」架构
|
||||
- **宿主工程**：`cocoscreator_projects/YouleNexus`（Cocos Creator 3.8.8）
|
||||
|
||||
---
|
||||
|
||||
## 0. 第一准则：服务器零改动
|
||||
|
||||
任何前端开发都必须完全遵循前后端数据包的协议与数据结构，做到**服务器零改动**。这是不可逾越的最高准则，优先于一切其它考量：协议信封、`route`/`rpc` 命名、字段名与类型、`roomtype` 配置数组、`deskinfo` 快照结构等，必须与现有协议逐字节对齐（依据 `docs/protocol/`）。本设计的所有取舍都不得违反此准则。
|
||||
|
||||
## 1. 目标与非目标
|
||||
|
||||
### 目标
|
||||
1. **框架现代化**：TypeScript、响应式状态、编译期协议校验、高性能、高可扩展。
|
||||
2. **框架与子游戏零耦合**：依赖单向，框架不感知任何子游戏；子游戏只通过受限边界与框架交互。
|
||||
3. **框架更新方便传播**：框架改代码或界面后，所有子游戏无需「拷贝/同步」即可获得更新。
|
||||
4. **消灭旧架构痛点**：旧架构模板与子游戏一对一、开发新子游戏需拷贝整份模板、更新极繁琐。
|
||||
|
||||
### 非目标
|
||||
- 不做运行时大厅聚合 / 子游戏热插拔（部署形态为「各子游戏独立构建发布独立包」）。
|
||||
- 本期不重写服务器、不改协议。
|
||||
|
||||
### 关键决策记录
|
||||
| 维度 | 决策 |
|
||||
|---|---|
|
||||
| 部署形态 | 各子游戏独立构建发布独立包，但共享同一份框架源（非运行时大厅） |
|
||||
| 框架边界 | 逻辑 + 平台界面（Prefab/场景/图集）+ 可换肤主题 |
|
||||
| 仓库组织 | Monorepo + 符号链接（junction）共享框架 |
|
||||
| YouleNexus 角色 | 框架本体的开发/演示/回归宿主工程 |
|
||||
| 换肤机制 | 配置 + 资源覆盖为主，插槽为辅 |
|
||||
| 新建子游戏 | 脚本从「种子工程模板」全自动克隆 |
|
||||
| Cocos 版本 | 全 monorepo 统一，升级即协调发布 |
|
||||
|
||||
## 2. Monorepo 布局与「框架更新即时传播」
|
||||
|
||||
### 物理布局
|
||||
```
|
||||
cocoscreator_projects/
|
||||
├─ YouleNexus/ # 框架宿主工程（开发 + 演示 + 回归测试框架本体）
|
||||
│ └─ assets/
|
||||
│ ├─ framework/ # ★框架本体（唯一真源，被各子游戏 junction 引用）
|
||||
│ │ ├─ core/ net/ protocol/ platform/ ui/ sdk/
|
||||
│ └─ _dev/ # 框架自测：mock server、mock 子游戏、调试场景（不发布）
|
||||
│
|
||||
├─ games/ # 各子游戏工程（每个都是独立可构建发布的 Cocos 工程）
|
||||
│ ├─ <game>/
|
||||
│ │ └─ assets/
|
||||
│ │ ├─ framework ──►(junction) ../../../YouleNexus/assets/framework
|
||||
│ │ └─ game/ # 子游戏私有：IGameModule 实现 + theme + override + 对局资源
|
||||
│ └─ …
|
||||
│
|
||||
└─ templates/
|
||||
└─ game-seed/ # 最小但完整的空 Cocos 工程种子（new-game 克隆源）
|
||||
```
|
||||
|
||||
### 更新传播机制
|
||||
- 框架只有**一份真源**（`YouleNexus/assets/framework`）。各子游戏工程的 `assets/framework` 是指向它的 **Windows junction**（`mklink /J`，免管理员）。
|
||||
- 改框架代码或界面 → 同一份物理文件 → 所有子游戏工程**即时可见**，无需拷贝/同步/bump 版本。
|
||||
- 资源 `.meta` 随真源共享，**UUID 全局稳定唯一**，跨工程引用不错乱；各工程仅 `library/` 编译缓存独立。
|
||||
- **取舍（已确认接受）**：框架默认即时同步到所有子游戏，改框架要对所有子游戏负责（不做「子游戏锁定框架版本」）。
|
||||
|
||||
### 配套工程化措施
|
||||
1. **`scripts/setup-links`**（Node）：junction 内容不被 git 跟踪，团队成员 clone 后跑一次，按 `games/*` 自动重建所有 junction；新建子游戏也用它接入。
|
||||
2. **`.gitignore`**：忽略各子游戏的 `assets/framework`（junction 本体）、所有 `library/` `temp/` `build/`。
|
||||
|
||||
## 3. 框架内部分层与零耦合规则
|
||||
|
||||
框架 `assets/framework/` 内分 6 层，**依赖严格单向**（上层依赖下层，下层永不反向，框架永不 import 子游戏）：
|
||||
|
||||
```
|
||||
sdk/ 子游戏对接边界（子游戏只认这一层 + core 类型）
|
||||
IGameModule 接口 · 平台→子游戏回调钩子 · 暴露给子游戏的 API facade
|
||||
ui/ 平台界面：登录/大厅/房间/通用弹窗 Prefab+场景 · 主题/换肤系统
|
||||
platform/ 平台业务：响应式 Store（RoomStore=Desk / PlayerStore=C_Player / AppStore=GameData）
|
||||
+ 登录/房间/重连流程编排
|
||||
protocol/ 协议契约：route/rpc 常量 · 收发包 TS 类型 · 平台 RPC 封装(send/handle)
|
||||
net/ 传输：NetClient(WebSocket) · Envelope 双层拆包 · 心跳/30s超时/重连轮询
|
||||
core/ 基座：EventBus · 协议类型定义 · 座位↔视图转换 · 常量/工具
|
||||
```
|
||||
|
||||
### 对应旧架构映射（保证协议红线不破）
|
||||
- `net` + `protocol` ← 旧 `09_Net` / `00_minhttp` / `02_Const`
|
||||
- `platform` ← 旧 `04_Data` / `06_Player` / `07_Desk` / `12_Logic`
|
||||
- `ui` ← 旧 `11_GameUI`
|
||||
- `sdk` ← 旧 `01_SubGame` 钩子契约（`Game_Modify` / `02_SubGame_Input`），但反转为接口
|
||||
|
||||
### 零耦合三条硬规则
|
||||
1. **依赖单向 + 框架不知道任何子游戏存在**：框架代码不得出现任何子游戏名/类型；子游戏通过 `sdk` 注册自己。
|
||||
2. **通信只走两条道**：① 子游戏实现 `IGameModule` 被框架调用；② 子游戏通过 `sdk` facade 调用框架能力。不允许子游戏直接 import `platform`/`net` 内部实现。
|
||||
3. **状态归属清晰**：框架持有 `Desk`/`C_Player`/`GameData`（响应式 Store）；子游戏持有自己的对局态（手牌/出牌/轮次）于自身命名空间，并实现 `serialize()/restore(deskinfo)` 供断线重连。
|
||||
|
||||
### 高扩展点
|
||||
- `protocol` 用 TS 类型结构化收发包，编译期校验，对齐协议零改。
|
||||
- `platform` Store 响应式驱动 UI（状态变 → UI 自动刷新），告别旧的手动刷 UI。
|
||||
- 新增平台 RPC = 加一个 typed handler，不动其它层；新增子游戏 = 注册一个 `IGameModule`，框架零改动。
|
||||
|
||||
## 4. 数据流与 sdk 接口契约
|
||||
|
||||
### 一条收发包的完整流向（单条 WebSocket，平台与对局复用）
|
||||
```
|
||||
收包 WebSocket frame
|
||||
→ net 外层拆包 + 过滤 @toconcon/@serverheartbeat + JSON.parse → Envelope{route,rpc,data}
|
||||
→ Router route ∈ {agent,room,platform} ─► protocol handler ─► 更新 platform Store ─► UI 响应式自动刷新
|
||||
route = <game route> ─► sdk ─► activeGame.onReceive(rpc,data) ─► 子游戏对局态 ─► 对局UI刷新
|
||||
发包 平台操作: platformApi.xxx() ─► protocol 编码 ─► net.send
|
||||
对局操作: ctx.net.send(route,rpc,data) ─► net.send （同一条连接）
|
||||
```
|
||||
|
||||
### 接口契约（方向已定，精确签名待后续细化）
|
||||
|
||||
> **说明**：以下接口的**方向与边界已确认**（子游戏被 `IGameModule` 调用、通过 `GameContext` 调用框架）；**精确的方法签名、字段、能力面将在后续专门的接口设计中细化**，本 spec 不敲死。
|
||||
|
||||
子游戏实现（框架调用子游戏）—— `IGameModule`（示意）：
|
||||
```ts
|
||||
interface IGameModule {
|
||||
readonly route: string; // 本游戏 game route，框架据此路由对局包
|
||||
onEnter(ctx: GameContext): void; // 进入牌桌场景，拿到框架能力句柄
|
||||
onExit(): void;
|
||||
onReceive(rpc: string, data: any): void; // 框架派发非平台包，子游戏 switch(rpc)
|
||||
onReconnect(deskinfo: any): void; // login 响应 isbattle==1 时恢复对局
|
||||
serialize?(): any; // 对局快照（可选）
|
||||
// 平台事件钩子（默认空实现，按需覆写）：onPlayerJoin/onPlayerLeave/onReady/onDissolve/onOffline/...
|
||||
}
|
||||
```
|
||||
|
||||
框架暴露给子游戏（子游戏调用框架）—— `GameContext` facade（示意）：
|
||||
```ts
|
||||
interface GameContext {
|
||||
net: { send(route: string, rpc: string, data: object): void };
|
||||
room: ReadonlyRoomStore; // 只读 Desk
|
||||
player: ReadonlyPlayerStore; // 只读 C_Player / 座位玩家
|
||||
ui: PlatformUI; // toast / dialog / 通用弹窗
|
||||
events: EventBus;
|
||||
seat: { toView(mySeat: number, target: number): number }; // 替代旧 ChangeToStatus
|
||||
}
|
||||
```
|
||||
|
||||
关键点：子游戏拿到的是**只读 Store + 受限 facade**，不能触碰 `net`/`platform` 内部，强制零耦合。
|
||||
|
||||
## 5. 换肤/覆盖机制（配置 + 资源覆盖为主，插槽为辅）
|
||||
|
||||
子游戏所有定制都落在自己的 `game/` 私有目录，**框架真源一字节不改**——这是「换肤」与「框架可更新」共存的前提。
|
||||
|
||||
1. **主题配置**：每个子游戏 `game/theme.ts` 声明主色/字体/图集替换映射/关键布局参数。框架 UI 组件全部「皮肤无关」，从 `ThemeProvider` 读值渲染，不写死样式。可改范围 = 框架预留的「皮肤变量」集合。
|
||||
2. **资源覆盖层**：框架加载资源统一走 `AssetResolver.load(logicalPath)`，**先查 `game/override/<logicalPath>`，命中即用，否则回退 `framework/ui/default/<logicalPath>`**。子游戏放同逻辑路径资源即可替换，无需改框架。
|
||||
3. **插槽**：框架关键 Prefab 预留具名挂载点 `<Slot name="xxx">`，子游戏在注册阶段声明往该槽注入自己的 Prefab。仅用于结构级深度定制，日常换肤不碰。
|
||||
|
||||
**冲突与更新策略**：
|
||||
- 子游戏覆盖物全在 `game/`，与框架真源物理隔离 → `git pull` 框架更新不产生资源冲突。
|
||||
- 框架维护一份「**皮肤变量 + 可覆盖逻辑路径 + 插槽**」契约清单（约定即 API）；改这份契约属 breaking change，需走版本说明通知子游戏。
|
||||
- **取舍（已确认接受）**：框架须主动把 UI 抽象成「皮肤无关 + 变量/覆盖点」，增加框架自身开发成本，换取零冲突换肤。
|
||||
|
||||
## 6. 协议红线、错误处理、测试、技术栈
|
||||
|
||||
### 协议红线保障（第一准则的技术落地）
|
||||
- `protocol/` 用 TS 类型把每个收发包结构化（字段名/类型/`roomtype`/`deskinfo`），编译期挡住字段写错。
|
||||
- `net` 支持收发包**录制/回放**：存盘真实包流，框架改版后回放比对，确保协议行为不漂移。
|
||||
- 一份「协议一致性测试」对照 `docs/protocol/` 各章，作为框架 CI 红线门禁。
|
||||
|
||||
### 错误处理（高可用）
|
||||
- **网络**：30s 收包超时看门狗 + 断线候选服务器轮询重连（对齐旧 `Logic`）；重连后重发 `player_login`、按 `isbattle` 走 `onReconnect`。
|
||||
- **故障隔离**：子游戏 `onReceive`/钩子用 try-catch 包裹，子游戏抛错不拖垮框架（平台连接与大厅存活），错误进统一日志。
|
||||
- **资源**：`AssetResolver` 覆盖缺失 → 回退默认 → 仍缺 → 占位资源 + 告警，不黑屏。
|
||||
|
||||
### 测试（依托 YouleNexus 宿主工程）
|
||||
- `YouleNexus/assets/_dev/` 挂 **mock server + mock 子游戏**，独立跑通登录/大厅/房间/对局/重连全流程，作为框架回归基准。
|
||||
- `core/net/protocol` 纯逻辑做单元测试（拆包、心跳、编解码、座位换算）。
|
||||
- 子游戏可对自己的 `IGameModule` 单测（喂 rpc 包断言对局态），不依赖真服务器。
|
||||
|
||||
### 技术栈
|
||||
- **TypeScript**（Cocos 3.8 标配）；轻量**响应式 Store**（自研薄封装或极小库，避免重依赖）；不引大型框架，保证高性能/低耦合。
|
||||
|
||||
## 7. 新建子游戏流程（脚本从种子工程全自动克隆）
|
||||
|
||||
> 事实：Cocos Creator 无官方 CLI 凭空生成全新工程，工程须从一份已有工程复制而来。故采用「种子工程模板」克隆。
|
||||
|
||||
仓库维护 `templates/game-seed/`——最小但完整的 Cocos 工程，预配统一引擎版本、构建平台设置、屏幕适配、引擎模块裁剪。
|
||||
|
||||
```
|
||||
scripts/new-game <name>
|
||||
1. 复制 templates/game-seed/ → games/<name>/
|
||||
2. 改 package.json 的 name；重新生成 project uuid
|
||||
3. 删 library/ temp/（首次打开由编辑器重建）
|
||||
4. 建 assets/framework junction → 指向 YouleNexus 真源
|
||||
5. 铺 assets/game/ 骨架：IGameModule 空实现 + theme.ts + override/ 目录（新资源分配全新 meta uuid）
|
||||
6. 打印「用 Cocos Creator 打开 games/<name>」
|
||||
```
|
||||
|
||||
- 复制的只是**极薄的空工程外壳**（不含框架，框架靠 junction），与旧架构「拷贝整份模板+逻辑」有本质区别。
|
||||
- 种子工程需随 Cocos 版本升级维护一次；克隆时正确重置 project/资源 uuid（实现时按 3.8 实际字段验证）。
|
||||
|
||||
## 8. Cocos 版本升级
|
||||
|
||||
### 根本约束（已确认接受）
|
||||
framework 真源含**带版本的序列化资源**（`.prefab`/`.scene`/`.meta`）与按某版引擎 API 写的脚本，且被多工程 junction 共享同一份物理文件。Cocos 跨版本资源格式/meta/API 可能不兼容。故：
|
||||
|
||||
> **所有共享 framework 的工程，Cocos 版本必须统一，不能分叉。** 这是 symlink 共享资源换「即时同步」的代价。引擎版本声明于各工程 `package.json` 的 `creator.version`。
|
||||
|
||||
### 升级标准流程（一次「协调发布」，在 git 升级分支上做）
|
||||
```
|
||||
1. 框架宿主先行：用新版 Cocos 打开 YouleNexus → 执行工程迁移 → 跑 _dev mock 回归，确认框架在新版正常
|
||||
2. 升种子工程：templates/game-seed 的 creator.version 同步升新版（新子游戏天然新版，零额外操作）
|
||||
3. 逐个升子游戏：每个 games/<name>
|
||||
① 改 package.json 的 creator.version → 新版
|
||||
② 用新版 Cocos Creator 打开，让编辑器执行迁移（library 重建、按新版重新导入 framework 资源）
|
||||
③ 跑该子游戏回归
|
||||
4. 全部子游戏验证通过 → 合并升级分支
|
||||
```
|
||||
第 3 步「迁移」是编辑器行为，无法纯脚本完成——每个工程都需用新版编辑器打开一次。
|
||||
|
||||
### 工具化与防错
|
||||
- `scripts/check-cocos-version`：扫描 `games/*` 与 YouleNexus 的 `creator.version` 是否一致，不一致告警；接进 `setup-links` 与 CI，防止误用旧版打开改写资源。
|
||||
- `scripts/bump-cocos <version>`：批量改各工程 `package.json` 版本字段（不替代编辑器迁移）。
|
||||
- 版本粒度：补丁级（3.8.8→3.8.9）通常资源兼容、风险低；跨次版本/大版本（3.8→3.9）走完整迁移回归。
|
||||
|
||||
## 9. 待后续细化项（不阻塞本设计）
|
||||
1. **`IGameModule` / `GameContext` 精确签名**：方法集、字段、能力面（是否含录像/语音/AI 托管等通用能力）——专门的接口设计轮次敲定。
|
||||
2. **皮肤变量 / 可覆盖逻辑路径 / 插槽 契约清单**：框架 UI 抽象时逐项确定并文档化。
|
||||
3. **响应式 Store 选型**：自研薄封装 vs 极小第三方库。
|
||||
4. **种子工程的 uuid 重置细节**：按 Cocos 3.8.8 实际字段验证 project 与资源 uuid 的生成。
|
||||
5. **协议层 TS 类型**：依 `docs/protocol/` 逐章把收发包结构落为 interface。
|
||||
|
||||
## 10. 风险与缓解
|
||||
| 风险 | 缓解 |
|
||||
|---|---|
|
||||
| junction 不被 git 跟踪，团队成员环境缺链接 | `setup-links` 一键重建；文档与 CI 校验 |
|
||||
| Cocos 版本误分叉导致共享资源损坏 | `check-cocos-version` 告警 + 升级走协调发布流程 |
|
||||
| 框架改动波及全部子游戏 | 框架 CI 回归 + 协议一致性门禁；breaking change 走版本说明 |
|
||||
| 皮肤变量预留不足，子游戏被迫改框架 | 维护契约清单，深度定制走插槽；按需扩充变量 |
|
||||
Reference in New Issue
Block a user