222 lines
19 KiB
Markdown
222 lines
19 KiB
Markdown
# Dungeon Sweeper — 总体架构文档
|
||
|
||
## 文档状态
|
||
|
||
- 版本：3.0（依赖规则形态——分层/目录归属/数据流/原则；模块级归属登记与模块对接口契约均不进本文：前者归代码文件头注，后者规范源单点＝各系统 GDD、执法＝静态扫描域与契约测试）
|
||
- 引擎：Godot 4.7.2-stable（GDScript 单语言；2026-09-07 锁定）
|
||
- 评审模式：solo（`review-mode.txt`——门禁按 solo 跳过）
|
||
- 覆盖 GDD：现行全集（根索引＝`design/gdd/02-系统清单.md`，文档树构成以根索引为准）
|
||
- 事实源地位：本文是架构约束的唯一权威（分层/目录归属/数据流/架构原则）；写权限＝用户专属（agent 与技能只读）
|
||
- 实现实证：`game/`（完整游戏开发版本；本文分层与所有权经实现验证）。测试层级＝冒烟/单元/系统三级＋UI 探针与渲染 golden，识别三元组权威＝`design/engineering/test-conventions.md`「测试层三元组」节
|
||
|
||
---
|
||
|
||
## 引擎知识缺口摘要
|
||
|
||
- 引擎事实现行事实源＝`design/engineering/engine-reference/godot/`（VERSION / breaking-changes / deprecated-apis / current-best-practices 四件）——迁移核实结论、语义变化与编码注意一律查那里，本文不重复。
|
||
- 渲染器与窗口基座＝gl_compatibility + 1280×800；UI/渲染域为引擎风险集中地，采纳引擎增量前对照 engine-reference 核实。
|
||
- 写码纪律不变：不确定的 API 一律查 `docs.godotengine.org/en/4.7/` 核实后再用。
|
||
|
||
---
|
||
|
||
## 系统分层图
|
||
|
||
20 系统按 `design/gdd/02-系统清单.md` 依赖分层表映射到标准五层。实现已验证该分层（core/ 纯逻辑零 UI 依赖 headless 可跑、presentation/ 组合根模式）。
|
||
|
||
```
|
||
┌────────────────────────────────────────────────────────────┐
|
||
│ 呈现层 │
|
||
│ D1 HUD 与界面框架 (MVP) · B5 战斗表现 │
|
||
│ D4 音频 (Beta) · D5 教学引导 (Beta) │
|
||
├────────────────────────────────────────────────────────────┤
|
||
│ 功能层 │
|
||
│ B1 战斗结算编排 (MVP) · C1 关卡节点地图 │
|
||
│ C2 冒险结构 · C3 难度曲线 · C4 元进度 (Alpha) │
|
||
├────────────────────────────────────────────────────────────┤
|
||
│ 核心层 │
|
||
│ A1 扫雷棋盘生成 · A2 排雷玩法规则 · B2 敌人系统 │
|
||
│ B4 地图战斗资源 · A5 扫雷秘宝 │
|
||
├────────────────────────────────────────────────────────────┤
|
||
│ 基础层 │
|
||
│ D2 数据配置与数值表 · A3 行动经济 · A4 地形变异 │
|
||
│ B3 增益/状态系统 · D3 存档序列化 (Alpha) · D6 设置/本地化│
|
||
├────────────────────────────────────────────────────────────┤
|
||
│ 平台层 │
|
||
│ Godot 4.7.2 引擎 API 面（GDScript / Resource / │
|
||
│ SceneTree / Control / InputEvent）——无游戏系统 │
|
||
└────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
> 层名对照：基础层＝Foundation、核心层＝Core、功能层＝Feature、呈现层＝Presentation、平台层＝Platform——本文一律用中文名；跨文档与代码目录仍见英文名（`game/core/`、`game/presentation/` 等目录名不改）。
|
||
|
||
| 系统 | 层 | 里程碑 | headless 约束 | 引擎风险域 |
|
||
|---|---|---|---|---|
|
||
| D2 数据配置 | 基础层 | MVP | ✅ 完整可跑 | LOW（Resource/.tres 基线稳定） |
|
||
| A3 行动经济 | 基础层 | MVP | ✅ 完整可跑 | LOW（纯逻辑） |
|
||
| A4 地形变异 | 基础层 | MVP | ✅ 完整可跑 | LOW（纯逻辑） |
|
||
| B3 状态系统 | 基础层 | MVP | ✅ 完整可跑 | LOW（RefCounted 纯逻辑） |
|
||
| A1 棋盘生成 | 核心层 | MVP | ✅ 完整可跑 | LOW（纯逻辑） |
|
||
| A2 排雷规则 | 核心层 | MVP | ✅ 完整可跑 | LOW（零表读取零 UI） |
|
||
| B2 敌人系统 | 核心层 | MVP | ✅ 完整可跑 | LOW（纯逻辑） |
|
||
| B4 地图战斗资源 | 核心层 | MVP | ✅ 完整可跑 | LOW（纯逻辑） |
|
||
| B1 战斗结算编排 | 功能层 | MVP | ✅ 完整可跑（禁 await） | LOW（纯逻辑） |
|
||
| C1 关卡节点地图 | 功能层 | MVP | ✅ | LOW |
|
||
| C2 冒险结构 | 功能层 | MVP | ✅ | LOW |
|
||
| C3 难度曲线 | 功能层 | MVP | ✅ | LOW |
|
||
| C4 元进度 | 功能层 | Alpha | ✅ | LOW |
|
||
| D1 HUD | 呈现层 | MVP | ❌（UI 层——场景级探针测试承载） | **MEDIUM**（Control/Input/文本域） |
|
||
| B5 战斗表现 | 呈现层 | 切片后立项（未实装，前置战斗表现美术测试） | ❌ | **MEDIUM**（Animation/Tween/渲染） |
|
||
| D4 音频 / D5 教学 | 呈现层 | Beta（与游戏内容无关者一律排 Beta） | 部分 | LOW-MEDIUM |
|
||
| D3 存档序列化 | 基础层 | Alpha | ✅ | LOW |
|
||
| D6 设置/本地化 | 基础层 | 完整愿景 | ✅ | LOW |
|
||
|
||
**依赖分层与唯一回边**：A2 只外发三事件（cell_revealed / flag_judged / round_end），B4/B1 订阅后回调——A2 不依赖任何下游（TD-SYSTEM-BOUNDARY 裁决，全项目唯一允许回边）。
|
||
|
||
---
|
||
|
||
## 目录归属
|
||
|
||
> 目录＝层级的物理承载：同一目录内的文件同层级、同受该层约束属性管辖，职责各自独立、归各文件头注（`##` 文档注释）承载；领域不做目录切分，仅当领域大到内部再需要一层时才立子目录。命名遵循 `design/engineering/code-conventions.md`：领域命名、禁 ID 前缀。逻辑依赖层级（基础/核心/功能/呈现）见「系统分层图」——`game/core/` 一目录内按依赖层级再分三段，层级约束由分层图与架构原则承载，目录不再切分。
|
||
|
||
| 目录 | 层级作用 | 该层约束属性 |
|
||
|---|---|---|
|
||
| `game/core/` | 全部玩法逻辑的承载（配置、RNG、存档域件、棋盘生成、排雷规则、经济与账本、效果引擎、战斗编排、关卡与冒险域件）——依赖逻辑层级内分基础/核心/功能三段，见分层图 | 纯逻辑：零 Control/场景引用、构造注入、fail-fast、`--headless --script` 完整可跑、玩法数值零字面量（读 `game/data/tables`）、随机只经封闭流 |
|
||
| `game/core/settlement/` | 领域子目录——战斗结算五段段件（领域大到内部再需要一层时切分的在案先例） | 同 core；段类可直接 new() 单测、段类对编排器零引用 |
|
||
| `game/presentation/` | 呈现层——全部 Control/CanvasLayer、输入→意图翻译、组合根装配 | 视图零核心写调用（信号外发为主）、组合根＝核心写调用唯一出口、呈现数据只走成文快照面；引擎风险域对照 breaking-changes |
|
||
| `game/data/` | 数据承载——玩法数值表（tables/*.tres）与字段契约（schemas/*.gd），对应基础层 D2 数据配置 | 数值单一事实源；表值直接改变游戏运行结果 |
|
||
| `game/tests/` | 测试域——冒烟/单元/系统三闸承载 | 依赖只经 autoload 边界与场景契约两类入口；禁反向依赖呈现层实现内部 |
|
||
| `game/probe/` | 探针域——场景级探针与取证探针 | 同测试域边界；在闸件与手动测量件两分 |
|
||
| `game/sim/` | 测量域——MC/调参/数值验证驱动件 | 不入 CI、用户手动发起、随机显式定种 |
|
||
|
||
**依赖单向性**：上层可消费下层，禁止反向（C3 禁调用 A1 生成、D1 不直调 A3、A2/B3/B4 零相互直调）。全项目唯一回边＝A2 事件订阅面。
|
||
|
||
---
|
||
|
||
## 呈现层装配与会话生命周期
|
||
|
||
### 三屏壳与组合根
|
||
|
||
- 呈现场景拆为三屏壳：MenuScreen（开始菜单屏）／CampScreen（营地屏）／AdventureScreen（冒险屏——内含关卡地图与战斗两容器）。
|
||
- 屏成员寻址经界面注册面（ui_registry）：探针与消费方走 `main.ui.<域容器>.<句柄>` 合同寻址；句柄清单与合同细节归 ui_registry 头注承载。
|
||
- 局态一律住 RunScope 节点，禁在屏/视图侧持有局态引用。
|
||
|
||
### 视觉层装配合同
|
||
|
||
- **树序＝登记序＝z 序**，同源派生；层序唯一事实源＝`main.gd` 的 `LAYER_CONTRACT` 常量表（kind 五类：shell／modal／state／node／float）。
|
||
- 全仓唯一落位口＝`_apply_layer_contract()`（装配尾统一排序+登记）；散落 `move_child` 由冒烟源码断言判红；**改层序只改合同表**。
|
||
- 具体层清单不复制进本文（双写失同步禁令）——查现行层项直接读 `main.gd`。
|
||
|
||
### 会话生命周期（RunScope）
|
||
|
||
- `run_scope.gd`＝纯状态承载 Node：零信号连接、零视图构建、零核心写调用（连接只在组合根，组合根经 `run_scope.X` 读写）。
|
||
- 会话更替机制：`_begin_session()` 新建会话节点挂树、旧会话节点**整节点 `queue_free()`**——无独立收束函数，跨局字段清理靠节点释放机制。
|
||
- **存活性矩阵**（九阶段 × 五引用面；执行判据＝系统测试 V3a–V3i）：
|
||
|
||
| 阶段 | run_scope | adventure | runner | settlement |
|
||
|---|---|---|---|---|
|
||
| ① 闲时 | 在树（闲时会话） | null | null | null |
|
||
| ② 开局停点 | 在树 | alive | alive | null |
|
||
| ③ 战斗中 | 在树 | alive | alive | alive |
|
||
| ④ 结算后（胜利停点）／⑤ 选路页 | 在树 | alive | alive | both |
|
||
| ⑥ 终局面 | 在树 | alive | alive | null |
|
||
| ⑦ 回菜单收束 | 新闲时会话即刻在树（旧会话已释放——无真空窗） | null | null | null |
|
||
| ⑧ 各模态开合后 | 闲时会话零扰动 | null | null | null |
|
||
| ⑨ 两连局+续玩断点 | 换全新会话在树 | alive | both | both |
|
||
|
||
- 三态记号：**alive**＝应有实例、**null**＝必须缺位（实测非空判红）、**both**＝按分支可空可活。对象有值但已失效一律判「悬挂」红。
|
||
|
||
### 模态编排（ModalFlow/ModalStack）
|
||
|
||
- `modal_flow.gd`＝模态编排纯逻辑类：开合编排（遮挡记账单口＋演播后排窗挂起）／棋盘输入锁谓词／角标置灰谓词三职责；可直接 `new()` 单测。
|
||
- 互斥排除语义随层登记（`register(node, tags)`）；其余层零标签。
|
||
|
||
---
|
||
|
||
## 测试与质量域
|
||
|
||
> 定位：本节只写测试域的架构事实。测试工具手册与各闸判定口径的事实源＝`game/tests/README.md`；闸清单与改动域划分的唯一出处＝`tools/run_all_gates.sh`（脚本即清单）；测试怎么写、怎么算合格＝`design/engineering/test-conventions.md`；静态扫描域 S 系规则的规则全集与动机＝`game/tests/README.md`「Static Scan」节。全量验证＝合回后远端 CI；开发期义务＝改完即测（process-conventions §4）。
|
||
|
||
### 测试域依赖约束
|
||
|
||
测试域禁止反向依赖呈现层具体实现。五闸及其调用的探针场景、审计脚本只允许依赖两类边界：
|
||
|
||
1. **autoload 边界**——ConfigDB / RngService 的公开面（--script 模式不加载 autoload 且不注册全局标识符，测试文件自带显式实例化夹具）；
|
||
2. **场景契约**——探针场景的信号外发面与视图单元接口（信号外发、setter 只读注入），禁直引呈现层实现内部。
|
||
|
||
测试域是所有层的消费方，进入方式限于上述两类边界；除此之外的依赖方向一律与「目录归属」节依赖单向性同规。
|
||
|
||
---
|
||
|
||
## 数据流
|
||
|
||
### 1. 帧更新路径（2D 回合制：无逐帧玩法逻辑）
|
||
|
||
```
|
||
Input（鼠标）→ D1 输入翻译 → 意图对象 → A2.settle_batch（唯一提交入口）
|
||
→ A3.try_spend（原子扣减）→ A2 棋盘效果（挖/连锁/封印/移动）→ 三事件外发
|
||
→ [棋盘渲染：D1 BoardView 按事件增量重绘；无事件帧 = 静态 + 动效]
|
||
→ 轮次结束 → A3 Waiting → B1 结算编排（段序七段）→ 明细步骤流 → D1 结算屏逐行呈现
|
||
```
|
||
|
||
- 回合制下每帧只做：输入采样、呈现刷新、动效推进——**玩法状态只在意图事务内变更**（单意图帧输入收集：stop 点击终结当帧）。
|
||
- 无跨线程玩法数据流（Godot 主线程假设）；A1 生成若引入 WorkerThread，join 必须先于任何快照切出（既定约束）。
|
||
|
||
### 2. 事件/信号路径（系统间通信，无紧耦合）
|
||
|
||
```
|
||
A2 ──cell_revealed / flag_judged / round_end(棋盘路径)──▶ B1（轮 facts 缓冲）
|
||
A3 ──round_end(stopped 直发，payload 同构)──────────────▶ B1
|
||
B1 ──notify_settlement_done(next_round_mode) / notify_combat_end──▶ A3
|
||
B1 ──apply_effect / apply_damage / grant / 伤害单据 submit…──▶ B3/B2/B4（唯一调用方）
|
||
B1 ──install_board / retire_board──▶ A2 B1 ──generate(L,D)──▶ A1
|
||
D1 ◀──呈现数据源：A2 事件流 / B1 步骤流 / A3 ap-rap / ConfigDB display_name
|
||
```
|
||
|
||
- **事件载体（已定）**：组合根直连信号接线 + B1 Waiting 相位触发（不依赖事件到达序）；autoload 全局事件总线已否决（2026-09-12，沿革见 git 历史）——单线程回合制沿用组合根直连（KISS）。选型理由＝可回放（架构原则 3）：同步直连让调用顺序显式可见，「同种子逐位相同」才可断言；事件驱动形态服务的是并发/IO 场景对外部不确定时序的反应性，与本作「顺序确定」的需求相反。
|
||
- 事件规范序：A2 发射序＝触发格 BFS、8 邻行主序；事件序契约 `flag_judged` < `round_end` 全路径统一。
|
||
- **呈现层订阅禁令（切片缺陷教训固化）**：呈现层永不直接订阅排雷玩法／行动经济的事件流，只订战斗结算步骤流与 `level_runner`——核心事件形态变化不得直接冲击界面。
|
||
|
||
### 3. 存档/读档路径
|
||
|
||
- 存档系统已实装：格式、三槽位、断点域与迁移链的现行契约以 `design/gdd/systems/表现与支撑/存档序列化.md`（owner）为准。
|
||
- RNG 快照契约（约束，现行成立）：断点续玩回填＝master_seed + 各流 scope 计数器；快照切出须发生在无正在执行中的 open_stream 实例时（scope 事件边界外——切点＝board install 边界）；SAVE_FORMAT_VERSION 高版本拒读。
|
||
|
||
### 4. 打包与字体（CJK 随包发行）
|
||
|
||
CJK 字体随包发行并设为 theme 默认字体——运行时默认字体无中文字形。此项是 HUD 框架正式化的硬性前置，同时进导出 checklist 核对项。
|
||
|
||
### 5. 初始化顺序
|
||
|
||
```
|
||
进程启动
|
||
→ autoload 实例化：ConfigDB → RngService → SaveManager → MetaProgression（顺序固定；核心类为普通类、由组合根按局实例化）
|
||
→ ConfigDB._ready()：load_tables 加载 + 校验（致命通道；失败 = 构建中止 + 错误清单）
|
||
→ 主场景（D1 组合根）装配视图单元 + 信号接线
|
||
→ C2 begin_run：RngService.set_master_seed()（唯一接线方；两流计数器全零前提）
|
||
→ B1.begin_battle(encounter)：set_reload_gate(true) → B3 开域 → B2 spawn → A2 install_board(A1.generate) + B4 roll_board（恰一次）→ A3 notify_round_start
|
||
→ 挖掘循环 …… → battle_over 清理序列 → set_reload_gate(false)
|
||
→ 关卡末：通关结算（钥石/GP/专长 level_clear 渠道——现行语义归 冒险结构 GDD）
|
||
```
|
||
|
||
**启动后置条件**（执行判据事实源在 `game/tests/system_test.gd`）：
|
||
|
||
1. ConfigDB 就绪且表已载（`is_ready` + hero 表在座）。
|
||
2. 系统设置已落引擎态——Master 音量 mute/volume_db＝settings_store 现值；减动效开关＝`UiKit.motion_scale`。
|
||
3. 启动态菜单可见（boot 后自树顶向下第一个可见内容层＝开始层）。
|
||
4. 续玩钮可见态恒等于断点在档态（双向）。
|
||
5. 闲时会话已在树（`run_scope` 永非 null 契约的启动侧证明）。
|
||
6. 调试浮窗 boot 不自动开（菜单优先）＋调试入口全局浮层角标 boot 可见。
|
||
---
|
||
|
||
## 架构原则
|
||
|
||
1. **核心层纯逻辑、headless 完整可跑**——核心层/功能层玩法逻辑零 Control/场景引用、零 UI 依赖；`--headless --script` 可跑完整战斗。输入是意图对象、输出是事件流/步骤流，D1 与输入设备皆可替换。
|
||
2. **单一事实源与零字面量**——玩法数值只存在于 `data/tables/*.tres`，经 ConfigDB 类型化单点读取；代码零玩法数值字面量；参数禁止跨系统复制（D2 Rule 1/2）。
|
||
3. **封闭 RNG 与可回放**——玩法代码零随机；一切随机经 RngService 具名封闭流（增流走 P1 评审）；同种子 + 同输入序列 ⇒ 事件流/步骤流逐位相同（结算禁 await，B1 承重约束）。
|
||
4. **编排唯一性与事件面封闭**——战斗域跨系统调用权集中 B1（静态扫描承载）；A2 三事件面封闭即负空间；每格受理、每雷转化、每次推进、每次衰减各恰一次。
|
||
5. **fail-fast + 零特判**——数据错误一律致命中止（错误数值上线比崩溃更伤）；API 非法＝拒绝 + 诊断不静默；变异零运行时分支（行为差异全部由生成端约束保证）。
|
||
6. **依赖单向 + 组合根模式**——层间单向依赖、唯一回边＝A2 事件订阅面；核心写调用唯一发生在组合根；禁上帝对象。
|
||
7. **呈现层契约成文**——面向呈现的信号载荷必须有成文 schema；模态覆盖层必须有"打开时遮挡物隐藏"场景级断言；场景级 UI 探针测试为标配（切片缺陷教训沉淀）。
|
||
8. **系统无状态**——效果引擎这类系统零运行时可变状态：数据由宿主对象持有并随宿主生灭，状态按参数传入系统，系统只做判定。系统实例不持计数器——计数器住桶（round/battle/level/adventure 四桶，EffectContext 引用束），桶住宿主。
|
||
9. **停点权威在核心层**——玩家决策停点（选路、三选一、商店、恢复这类）的推进守卫住核心层状态机：停点未兑付，推进口一律拒绝（零自动推进契约）；呈现层模态只做开合与输入锁——阻塞是两层结构，核心守卫为权威、模态为体验；停点态是核心状态、随断点序列化，headless 跑批与真实局同一套规则，中断续玩恢复到同一停点。
|