# 前端 · 子游戏开发指导文档

> 本套文档是 **gameabc 平台前端模板框架(`gameabc-framework`)** 下「子游戏前端」开发的通用指导与规范。
> 它讲清楚四件事：**前端怎么分层运行**、**界面怎么用精灵与组件搭**、**事件/动画/音频/Spine 怎么用**、**怎么和服务端收发包并启动一局**。
>
> 文中以「麻将」一类房卡棋牌作举例，但 `gameabc-framework` 是**游戏中立**的通用框架，所有结论不绑定具体玩法。
> 新开发者按本套文档即可理解前端运作、从模板派生出一个子游戏并写出符合规范的代码。

---

## 这套文档写给谁

- **新接手子游戏前端的开发者**：先读 01、02 建立全局认知，再按 03、04 动手，05 随时回查。
- **正在开发/维护某子游戏前端的开发者**：02–05 是日常手册与红线。
- **做代码审查的人**：05 是审查清单来源。

## 阅读顺序

| 篇 | 文档 | 解决什么问题 |
|----|------|--------------|
| 00 | 本文 README | 这套文档是什么、怎么读 |
| — | [红线速查.md](./红线速查.md) | **一页纸分层模型 + 红线清单**（由 `CLAUDE.md` 常驻加载，改代码前先对照） |
| 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、框架中立、常量集中、组件生命周期、**数据驱动架构（前端无状态机/视图=服务端快照投影/本地 UI 态白名单）**、组件数据与表现延后、data.success、模块职责、测试 |
| 06 | [06-子游戏接入模式与Hooks外置.md](./06-子游戏接入模式与Hooks外置.md) | 内联模式 vs Hooks 外置模式、三契约文件可改性、退化为纯转发壳 + SubGameHooks 委托、subgame-entry 模板 |

建议第一次**从 01 顺序读到 05**；之后把 02–05 当手册随用随查。06 在接入新游戏或迁移到 Hooks 外置模式时选读。

---

## 一页纸与红线

**分层模型与红线清单已独立成篇：[红线速查.md](./红线速查.md)。**

该文件由 `CLAUDE.md` 通过 `@import` 常驻每次会话上下文，是红线的权威源；本 README 只负责导航，不重复抄写红线（避免两处不同步）。红线的完整细节见 [05-开发规范与红线.md](./05-开发规范与红线.md)。

---

## 与既有文档的关系

- 服务端的对应文档见 [服务端开发指导文档](../../server/development-guide/)；前端「成败标志 `data.success`」「收发包链路」与之同源，互为对照。
- 子游戏前端各层可能另有局部说明文档；本套是总纲，与之不冲突时以本套的通用原则为准。
- **平台无关的通用工程与架构规范**（分层、可扩展模式、配置化、数据权威、反模式与审查清单）见 [工程与架构通则](../../games/engineering/)：本套讲前端接入与红线，工程通则讲前后端通用的设计方法论，互补阅读。