优化聊天气泡文档
This commit is contained in:
@@ -87,7 +87,7 @@ Hooks 外置模式下，职责分为三层，单向向下：
|
||||
各消息处理器 / 收发包 / 战绩等业务模块 / UIManager 扩展 ...
|
||||
```
|
||||
|
||||
**数据流**：平台调 `Game_Modify.X(args)` → 转发壳查 `SubGameHooks.X` → 存在则委托子游戏实现并返回其结果；不存在则执行平台默认（B 类）或空操作（A 类）。
|
||||
**数据流**：平台调 `Game_Modify.X(args)` → 转发壳查 `SubGameHooks.X` → 存在则委托子游戏实现并返回其结果；不存在则执行空操作(A)/平台默认返回值(B)/模板默认 UI 渲染(D)。
|
||||
|
||||
**兼容性原因**：平台只认全局接口名，不关心实现在哪。老游戏不定义 `SubGameHooks`、三文件实心实现 → 照跑；新游戏用转发壳三文件 + `SubGameHooks` → 也跑。无需任何运行期判断。
|
||||
|
||||
@@ -108,7 +108,7 @@ Hooks 外置模式下，职责分为三层，单向向下：
|
||||
|
||||
1. **复制四个模板文件**到新游戏目录。
|
||||
2. **三个转发壳直接用，不改**：`00/01/02_SubGame_*.template.js` 复制后重命名，原样放入 `01_SubGame/`。
|
||||
3. **填充 SubGameHooks**：将 `SubGameHooks.template.js` 重命名为 `codes/SubGameHooks.js`，在其中实现本游戏需要的 hook（不需要的 hook 留空函数或删除，A 类无 hook 默认 no-op，B 类无 hook 返回平台默认值）。
|
||||
3. **填充 SubGameHooks**：将 `SubGameHooks.template.js` 重命名为 `codes/SubGameHooks.js`，在其中实现本游戏需要的 hook（不需要的 hook 留空函数或删除，A 类无 hook 默认 no-op，B 类无 hook 返回平台默认值，D 类无 hook 由模板渲染可变人数默认 UI）。
|
||||
4. **index.html 加载**：按既有顺序在原 `00_/01_/02_SubGame_*.js` 的位置加载新三文件，并在 `codes/` 相应位置加载 `SubGameHooks.js`（在其所依赖的 controllers/handlers 之后）。
|
||||
|
||||
### index.html 加载顺序要点
|
||||
@@ -123,7 +123,7 @@ Hooks 外置模式下，职责分为三层，单向向下：
|
||||
|
||||
## 4. 转发壳范式
|
||||
|
||||
转发壳按「无 hook 时的默认行为」分三类，必须**逐一覆盖全部 63 个接口**（见 §6）。
|
||||
转发壳按「无 hook 时的默认行为」分四类，必须**逐一覆盖全部平台接口**（见 §6）。
|
||||
|
||||
### A 类 — 纯子游戏行为（无 hook 即 no-op）
|
||||
|
||||
@@ -188,6 +188,14 @@ Game_Modify.CreateRoomData = []; // 创建房间数据
|
||||
Game_Modify.game_config = {}; // 游戏配置
|
||||
```
|
||||
|
||||
### D 类 — 模板默认 UI 渲染（可变人数）
|
||||
|
||||
少数 UI 接口无 hook 时，模板不止 no-op，而是提供一套**可变人数**的默认渲染（随房间 2/3/4 人自适应各玩家位）：`updatePlayerInfoUI`（玩家头像/昵称/分数）、`ShowChat`（桌面文字聊天气泡）、`gameui_play_voice` / `gameui_stop_voice`（桌面语音气泡）。
|
||||
|
||||
- 渲染只用平台全局数据（`Desk`/`C_Player`/`Game_Config`），并一律经框架 `SpriteManager` 操作精灵，**不引用 codes、不直接调引擎原语**。
|
||||
- 座位→显示位的映射（2/3 人时精灵槽 ≠ 物理布局位）由内部助手统一解析，保证头像面板与聊天/语音气泡落在同一玩家位。
|
||||
- **布局配置挂在 `Game_Modify` 下**（01 配置区，与 C 类配置数据同处）：玩家信息用 `Game_Modify.PLAYER_INFO_LAYOUT`、聊天/语音气泡用 `Game_Modify.BUBBLE_LAYOUT`；子游戏可调这些坐标，或用同名 hook 完全接管该 UI。
|
||||
|
||||
---
|
||||
|
||||
## 5. Hook 命名约定
|
||||
@@ -218,15 +226,18 @@ SubGameHooks.hallAppStart = function () {
|
||||
|
||||
## 6. 接口覆盖要求
|
||||
|
||||
转发壳必须**逐个覆盖全部平台接口**，遗漏会导致新游戏某平台调用落空（静默失败）。接口分三组，总计 **63 个**：
|
||||
转发壳必须**逐个覆盖全部平台接口**，遗漏会导致新游戏某平台调用落空（静默失败）。接口分组如下：
|
||||
|
||||
| 来源 | 数量 | 说明 |
|
||||
|------|------|------|
|
||||
| `gameHallImport.*` | 9 | 大厅相关；其中 `appStart` 对应 `SubGameHooks.hallAppStart`（加 `hall` 前缀） |
|
||||
| `Game_Modify.*`（事件/交互，01 段） | 9 | 精灵事件类默认 no-op，改用框架 `SpriteEventController` |
|
||||
| `Game_Modify.*`（生命周期/回调，02 段） | 45 | 多为 A 类 no-op，少量 B 类需给平台默认返回值 |
|
||||
| `Game_Modify.*`（桌面聊天/语音气泡） | 3 | `ShowChat` / `gameui_play_voice` / `gameui_stop_voice`；D 类，模板提供可变人数默认渲染 |
|
||||
|
||||
覆盖原则：**A 类无 hook 即 no-op；B 类无 hook 须返回有意义的平台默认值**（如玩家数、离开上限、房间文案等），而非静默返回 `undefined`。各接口的具体分类与默认值以平台接入 spec 为权威，接入时逐一核对。
|
||||
前三组共 63 项以平台接入 spec §9 为权威；桌面聊天/语音 3 项由本模板补充转发并提供可变人数默认。
|
||||
|
||||
覆盖原则：**A 类无 hook 即 no-op；B 类无 hook 须返回有意义的平台默认值**（如玩家数、离开上限、房间文案），**D 类无 hook 由模板按可变人数渲染默认 UI**（玩家信息/聊天/语音气泡，布局配置在 `Game_Modify`），均不应静默返回 `undefined`。各接口的具体分类与默认值以 spec 为权威，接入时逐一核对。
|
||||
|
||||
---
|
||||
|
||||
@@ -265,7 +276,7 @@ SubGameHooks.hallAppStart = function () {
|
||||
|
||||
| 验证项 | 方法 |
|
||||
|--------|------|
|
||||
| 接口不遗漏 | grep 对比三文件原定义与转发壳一一对应（63 个） |
|
||||
| 接口不遗漏 | grep 对比三文件原定义与转发壳一一对应（基础 63 项 + 桌面气泡 3 项） |
|
||||
| 签名不变 | 检查平台调用处参数与转发壳参数列表一致 |
|
||||
| 行为等价 | 逐接口黑盒测试（开局/重连/战绩/离开等主流程） |
|
||||
| 配置值完整 | `Game_Config.*` 与配置区数据均已保留 |
|
||||
@@ -284,7 +295,7 @@ SubGameHooks.hallAppStart = function () {
|
||||
| **配置值留配置文件** | `Game_Config.*` 和配置区数据（`Type_1/2/CreateRoomData` 等）不得塞进 `SubGameHooks`，保留在对应配置位置 |
|
||||
| **hook 签名必须与平台接口一致** | 平台按位置传参，转发壳以相同参数透传给 hook，hook 签名不得偏移 |
|
||||
| **二选一，不混用** | 同一接口不允许在三文件内联实现与 `SubGameHooks` 中同时存在 |
|
||||
| **转发壳必须全覆盖** | 转发壳须覆盖全部 63 个接口，遗漏会导致平台调用落空（静默失败） |
|
||||
| **转发壳必须全覆盖** | 转发壳须覆盖全部平台接口（基础 63 项 + 桌面聊天/语音气泡 3 项），遗漏会导致平台调用落空（静默失败） |
|
||||
| **严格 ES5** | `SubGameHooks.js` 与所有 codes 文件一律 ES5，禁 `let`/`const`/箭头函数等 |
|
||||
| **加载顺序正确** | `SubGameHooks.js` 须在其依赖的 controllers/handlers 之后、三文件之前加载 |
|
||||
|
||||
|
||||
@@ -72,4 +72,5 @@ BaseComponent / UIManager（ui，组件化与场景） ← gameabc-framework（
|
||||
|
||||
- 服务端的对应文档在 [`server/docs/development-guide/`](../../../server/docs/development-guide/)；前端「成败标志 `data.success`」「收发包链路」与之同源，互为对照。
|
||||
- 子游戏前端各层可能另有局部说明文档；本套是总纲，与之不冲突时以本套的通用原则为准。
|
||||
- **平台无关的通用工程与架构规范**（分层、可扩展模式、配置化、数据权威、反模式与审查清单）见 [`docs/engineering/`](../../../docs/engineering/)：本套讲前端接入与红线，`engineering/` 讲前后端通用的设计方法论，互补阅读。
|
||||
</content>
|
||||
|
||||
Reference in New Issue
Block a user