diff --git a/client/js/gameabc-framework/templates/subgame-entry/SubGameHooks.template.js b/client/js/gameabc-framework/templates/subgame-entry/SubGameHooks.template.js index 9e24e23..cc9ea22 100644 --- a/client/js/gameabc-framework/templates/subgame-entry/SubGameHooks.template.js +++ b/client/js/gameabc-framework/templates/subgame-entry/SubGameHooks.template.js @@ -1,7 +1,7 @@ // ============================================================================ // SubGameHooks.template.js —— 子游戏接入入口（复制为 codes/SubGameHooks.js 后填实现） // 平台契约文件(00/01/02 转发壳)会把同名平台接口转发到这里。只需实现【本游戏需要的】hook， -// 未实现的接口由转发壳走平台默认(B)或空操作(A)。严格 ES5。 +// 未实现的接口由转发壳走空操作(A)/平台默认返回值(B)/模板默认 UI 渲染(D)。严格 ES5。 // 接口清单与默认值见 spec §9 / 文档 06。 // ============================================================================ @@ -199,8 +199,21 @@ var SubGameHooks = window.SubGameHooks || {}; // [B] getMaxPlayerCount(roomtype)：获取房间最大玩家数量；无 hook 时默认：return Game_Config.Max.PlayerCnt || 4。 // SubGameHooks.getMaxPlayerCount = function (roomtype) { /* ... */ }; -// [B] updatePlayerInfoUI(targetSeat)：更新玩家信息 UI；无 hook 时默认：return false（让平台默认处理）。 +// [D] updatePlayerInfoUI(targetSeat)：更新指定座位玩家信息 UI；无 hook 时模板提供【可变人数】默认渲染 +// （头像/昵称/分数随人数 2/3/4 贴合各玩家，布局见 01 的 Game_Modify.PLAYER_INFO_LAYOUT）。子游戏可用 hook 完全接管。 // SubGameHooks.updatePlayerInfoUI = function (targetSeat) { /* ... */ }; +// ===== Game_Modify.*（桌面聊天/语音气泡，3） ===== +// 以下接口无 hook 时，模板提供【可变人数】默认渲染（气泡随人数贴合各玩家，布局见 01 的 Game_Modify.BUBBLE_LAYOUT）。 + +// [D] ShowChat(seat, text)：显示桌面文字聊天气泡（seat 为绝对座位）。 +// SubGameHooks.ShowChat = function (seat, text) { /* ... */ }; + +// [D] gameui_play_voice(uiIndex)：播放桌面语音气泡（uiIndex 为相对显示位序）。 +// SubGameHooks.gameui_play_voice = function (uiIndex) { /* ... */ }; + +// [D] gameui_stop_voice(uiIndex)：停止桌面语音气泡。 +// SubGameHooks.gameui_stop_voice = function (uiIndex) { /* ... */ }; + window.SubGameHooks = SubGameHooks; if (typeof module !== 'undefined' && module.exports) { module.exports = SubGameHooks; } diff --git a/docs/client/development-guide/06-子游戏接入模式与Hooks外置.md b/docs/client/development-guide/06-子游戏接入模式与Hooks外置.md index b0edb83..3b9a43e 100644 --- a/docs/client/development-guide/06-子游戏接入模式与Hooks外置.md +++ b/docs/client/development-guide/06-子游戏接入模式与Hooks外置.md @@ -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 之后、三文件之前加载 | diff --git a/docs/client/development-guide/README.md b/docs/client/development-guide/README.md index ebb6396..adc3bc9 100644 --- a/docs/client/development-guide/README.md +++ b/docs/client/development-guide/README.md @@ -72,4 +72,5 @@ BaseComponent / UIManager（ui，组件化与场景） ← gameabc-framework（ - 服务端的对应文档在 [`server/docs/development-guide/`](../../../server/docs/development-guide/)；前端「成败标志 `data.success`」「收发包链路」与之同源，互为对照。 - 子游戏前端各层可能另有局部说明文档；本套是总纲，与之不冲突时以本套的通用原则为准。 +- **平台无关的通用工程与架构规范**（分层、可扩展模式、配置化、数据权威、反模式与审查清单）见 [`docs/engineering/`](../../../docs/engineering/)：本套讲前端接入与红线，`engineering/` 讲前后端通用的设计方法论，互补阅读。