初始化仓库：友乐/gameabc 房卡游戏平台脚手架（client + server + docs）

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-07-01 18:13:26 +08:00
commit 594820d393
655 changed files with 310861 additions and 0 deletions
@@ -0,0 +1,75 @@
+# 前端 · 子游戏开发指导文档
+
+> 本套文档是 **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 组件化、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、模块职责、测试 |
+
+建议第一次**从 01 顺序读到 05**；之后把 02–05 当手册随用随查。
+
+---
+
+## 一页纸：前端分层模型
+
+```
+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+ 等交替段）。
+- **常量集中、禁硬编码**：精灵 ID/图片资源 ID/坐标尺寸/动画时长/音效 ID 一律定义在对应常量文件，业务代码引用，**不内联裸值**。
+- **组件走 BaseComponent**：UI 组件继承 `BaseComponent`，事件用 `this.addEventListener` 注册（`destroy()` 自动清理，防泄漏）；动态精灵/定时器在 `onDestroy` 清理。
+- **数据优先、表现延后**：收到推送先改数据模型，再播动画，动画回调里刷新静态界面；动画期间**不改数据**。即使不播动画，重画函数也能据本地数据还原正确界面。
+- **成败只认 `data.success`**：前端一律 `if (!data.success)` 判成败，**不**用 `status`/`code`，**不**写 `status` 兼容兜底。
+- **收发包走统一通道**：发包经统一发送封装（底层 `RpcHelper` 自动注入平台字段），收包统一分发（一 rpc 一处理器）；业务逻辑放处理器，**不**写进 `Game_Modify.*`。
+- **shared 只读**：`01_SubGame/codes/shared/` 是服务端 `shared/` 的同步副本，**不在前端改**，改服务端权威源后跑同步脚本。
+
+---
+
+## 与既有文档的关系
+
+- 服务端的对应文档在 [`server/docs/development-guide/`](../../../server/docs/development-guide/)；前端「成败标志 `data.success`」「收发包链路」与之同源，互为对照。
+- 子游戏前端各层可能另有局部说明文档；本套是总纲，与之不冲突时以本套的通用原则为准。
+</content>