joywayerandClaude Opus 4.8
46f65de7ed
- 强化「常量集中、禁硬编码」（05 §4 / README 红线速查 / 05 §11 审查表）： 明确 UI 代码禁止任何硬编码 id/裸值，覆盖精灵/群组/图层/图片/声音/Spine 等全部 id 与资源，一律用对应常量；补 Spine→Spine 动作配置映射。 - 新增「显隐走 showXxx/hideXxx 接口」（02 §3 范式第4条 / 05 §9 红线 / README 红线速查 / 05 §11 审查表）：UI 组件及零件的精灵/群组显隐必须由组件 暴露的 showXxx/hideXxx 控制，禁止别处直接用其精灵/群组 id 去 show/hide， 否则绕过组件、状态分散、重连刷新不一致（与 UI 组件专职一脉相承）。 - 显隐条同进 README 红线速查（@import 常驻层）；未改任何小节标题， 链接/锚点审计通过。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
83 lines
8.1 KiB
Markdown
83 lines
8.1 KiB
Markdown
# 前端 · 子游戏开发指导文档
|
||
|
||
> 本套文档是 **gameabc 平台前端模板框架(`gameabc-framework`)** 下「子游戏前端」开发的通用指导与规范。
|
||
> 它讲清楚四件事：**前端怎么分层运行**、**界面怎么用精灵与组件搭**、**事件/动画/音频/Spine 怎么用**、**怎么和服务端收发包并启动一局**。
|
||
>
|
||
> 文中以「麻将」一类房卡棋牌作举例，但 `gameabc-framework` 是**游戏中立**的通用框架，所有结论不绑定具体玩法。
|
||
> 新开发者按本套文档即可理解前端运作、从模板派生出一个子游戏并写出符合规范的代码。
|
||
|
||
---
|
||
|
||
## 这套文档写给谁
|
||
|
||
- **新接手子游戏前端的开发者**：先读 01、02 建立全局认知，再按 03、04 动手，05 随时回查。
|
||
- **正在开发/维护某子游戏前端的开发者**：02–05 是日常手册与红线。
|
||
- **做代码审查的人**：05 是审查清单来源。
|
||
|
||
## 阅读顺序
|
||
|
||
| 篇 | 文档 | 解决什么问题 |
|
||
|----|------|--------------|
|
||
| 00 | 本文 README | 这套文档是什么、怎么读、红线速查 |
|
||
| 01 | [01-前端架构与运行环境.md](./01-前端架构与运行环境.md) | 双运行时/ES5、平台/框架/子游戏三层、新旧架构并存、目录与加载顺序 |
|
||
| 02 | [02-渲染与UI组件体系.md](./02-渲染与UI组件体系.md) | 精灵 ID 体系、SpriteManager 分层、资源常量组织、BaseComponent 组件化、组件数据/set-refresh 范式、UIManager 场景、动态列表 |
|
||
| 03 | [03-事件·动画·音频·Spine.md](./03-事件·动画·音频·Spine.md) | EventBus、AnimationManager+配置、AudioManager+音效资源、SpineMgr 全链路 |
|
||
| 04 | [04-网络对接与启动编排.md](./04-网络对接与启动编排.md) | 发包链路（RpcHelper 注入平台字段）、收包统一分发、新旧架构对接边界、启动编排、处理器/管理器职责 |
|
||
| 05 | [05-开发规范与红线.md](./05-开发规范与红线.md) | 可编辑范围、ES5、框架中立、常量集中、组件生命周期、服务端权威/组件数据/表现延后、data.success、模块职责、测试 |
|
||
| 06 | [06-子游戏接入模式与Hooks外置.md](./06-子游戏接入模式与Hooks外置.md) | 内联模式 vs Hooks 外置模式、三契约文件可改性、退化为纯转发壳 + SubGameHooks 委托、subgame-entry 模板 |
|
||
|
||
建议第一次**从 01 顺序读到 05**；之后把 02–05 当手册随用随查。06 在接入新游戏或迁移到 Hooks 外置模式时选读。
|
||
|
||
---
|
||
|
||
## 一页纸：前端分层模型
|
||
|
||
```
|
||
gameabc.min.js（引擎，js/vendor，第三方）
|
||
▲
|
||
GameABCUtils（core，唯一直接调引擎原生 API 的模块）
|
||
▲
|
||
SpriteManager（core，业务级精灵 API：ID 校验 + 单位换算） EventBus / AnimationManager / AudioManager / SpineMgr（system）
|
||
▲ ▲
|
||
BaseComponent / UIManager（ui，组件化与场景） ← gameabc-framework（游戏中立，可复用）
|
||
══════════════════════════════════════════════════════════════════════════
|
||
01_SubGame/codes（子游戏实例，单向依赖框架；内部结构由子游戏自行组织）
|
||
shared 前后端共享算法（与服务端同源，脚本同步，只读）
|
||
══════════════════════════════════════════════════════════════════════════
|
||
旧受限对接层（平台入口，尽量不改）
|
||
00/01/02_SubGame_*.js → Game_Modify.StartWar / Reconnect / _ReceiveData / appStart
|
||
```
|
||
|
||
- **框架（gameabc-framework）**：游戏中立，提供精灵/组件/事件/动画/音频/Spine 通用能力，可被任何子游戏复用。
|
||
- **子游戏（01_SubGame/codes）**：单向依赖框架，在其内部自由组织实现（目录/文件命名由子游戏自定，仅 `shared/` 为只读同步副本）。
|
||
- **旧受限对接层**：平台框架的固定入口（`Game_Modify.*`），把平台事件转交给新架构，**尽量不改**（详见 01/04）。
|
||
|
||
---
|
||
|
||
## 红线速查（详见 05）
|
||
|
||
- **可编辑范围**：前端平台代码 `js/00_Surface/` 禁改；受限接口文件 `01_SubGame/00_/01_/02_SubGame_*.js` 不新增接口、尽量不改；其余在 `gameabc-framework/`、`01_SubGame/codes/` 内开发。
|
||
- **严格 ES5**：用 `var`/`function`/`Object.create`，禁 `let`/`const`/箭头/模板串/`class`。
|
||
- **框架游戏中立**：`gameabc-framework/` 内**不得**出现任何具体玩法逻辑或专属常量；玩法专属的事件/资源/配置一律定义在子游戏侧（如玩法事件在子游戏的事件常量文件里追加到 `EventBus.Events`）。
|
||
- **精灵只走 SpriteManager**：UI 代码**禁止**直接调 `GameABCUtils` 或引擎原生 API；ID 必须落在规定范围（精灵 1001–3000、群组 ≥201、图层 101–200/弹窗 301–400，另有 501–600、701+ 备用段，框架保留 1–1000 及 3001+ 等交替段）。
|
||
- **常量集中、禁硬编码**：UI 代码**禁止任何硬编码 id / 裸值**——精灵 ID / 群组 ID / 图层 ID / 图片资源 ID / 声音 ID / Spine 资源 / 坐标尺寸 / 动画时长 / 事件名 一律定义在对应常量文件、只引用常量。
|
||
- **服务端权威、前端只展示**：核心运算与胜负裁定以服务端为准、数据以服务端为权威；前端只做界面展示与玩家交互，本地数据仅为渲染副本，不做权威计算。
|
||
- **组件走 BaseComponent**：UI 组件继承 `BaseComponent`，事件用 `this.addEventListener` 注册（`destroy()` 自动清理，防泄漏）；动态精灵/定时器在 `onDestroy` 清理。
|
||
- **组件数据自持 + set-refresh**：组件自有数据集中 `this.data`；每个 UI/零件有 `setXxx`(只写数据)/`refreshXxx`(只据数据画)对，组件有总 `refresh()` 可据数据重建界面。
|
||
- **UI 组件专职自己的界面**：每个界面的数据与渲染只由其对应 UI 组件实现；别的模块要改/刷该界面一律**调该组件的公开接口**（`setXxx`/`refreshXxx`/语义方法），**禁止**在别处重复实现重叠或类似的界面数据/渲染逻辑。
|
||
- **显隐走 `showXxx`/`hideXxx`**：UI 组件/零件的精灵、群组显隐必须由组件暴露的 `showXxx`/`hideXxx` 接口控制；**禁止**别处直接用其精灵 ID/群组 ID 去 `SpriteManager.show/hide` 控显隐。
|
||
- **数据优先、表现延后**：收到推送先 `setXxx` 写数据、再播动画；动画的开始/结束/出错回调里**只刷界面、不写核心数据**。即使动画缺失/卡住/出错，数据、逻辑、界面仍正确、互不影响。
|
||
- **重连即重画（断线重连 + 硬刷新都要处理）**：重连/页面重载的本质是**恢复数据 → 调各 UI 组件 set-refresh 恢复数据与界面状态**，复用同一条重画路径，不为重连单写一套渲染（详见 04 §3.3、05 §6）。
|
||
- **成败只认 `data.success`**：前端一律 `if (!data.success)` 判成败，**不**用 `status`/`code`，**不**写 `status` 兼容兜底。
|
||
- **收发包走统一通道**：发包经统一发送封装（底层 `RpcHelper` 自动注入平台字段），收包统一分发（一 rpc 一处理器）；业务逻辑放处理器，**不**写进 `Game_Modify.*`。
|
||
- **shared 只读**：`01_SubGame/codes/shared/` 是服务端 `shared/` 的同步副本，**不在前端改**，改服务端权威源后跑同步脚本。
|
||
|
||
---
|
||
|
||
## 与既有文档的关系
|
||
|
||
- 服务端的对应文档见 [服务端开发指导文档](../../server/development-guide/)；前端「成败标志 `data.success`」「收发包链路」与之同源，互为对照。
|
||
- 子游戏前端各层可能另有局部说明文档；本套是总纲，与之不冲突时以本套的通用原则为准。
|
||
- **平台无关的通用工程与架构规范**（分层、可扩展模式、配置化、数据权威、反模式与审查清单）见 [工程与架构通则](../../games/engineering/)：本套讲前端接入与红线，工程通则讲前后端通用的设计方法论，互补阅读。
|
||
</content>
|