# Dungeon Sweeper（扫雷 × 自动战斗 闯关 Roguelike）

扫雷推理层 + 自动战斗结算的两段式回合 Roguelike。个人开发，MVP 优先管线。
设计入口：`design/gdd/02-系统清单.md`（循环式新骨架根索引）· 概念：`design/gdd/00-游戏概念.md` · 旧版 GDD 归档（只读参考）：`design/archive/gdd-2026-09-14/`

## Technology Stack

- **Engine**: Godot 4.7.2
- **Godot 可执行文件（本机固定路径，2026-09-15 登记）**：`D:\code\godot\Godot_v4.7.2-stable_win64_console.exe`（headless / 命令行一律用 console 版；编辑器版为同目录 `Godot_v4.7.2-stable_win64.exe`）
- **Language**: GDScript
- **Build System**: SCons (engine), Godot Export Templates
- **Asset Pipeline**: Godot Import System + custom resource pipeline

## 运行与验证（垂直切片）

工作目录 = 切片目录本身（含 `project.godot` 的那一层）：

- 冒烟（全量 headless 断言）：`D:\code\godot\Godot_v4.7.2-stable_win64_console.exe --headless --path . --script res://smoke/smoke_all.gd`
- 场景级探针（呈现层回归）：`…console.exe --headless --path . res://smoke/ui_probe.tscn`；另有 `ui_tune_probe.tscn`（数值调整板）与 `ui_click_probe.tscn`（合成鼠标事件行为探针）
- 调参期批量工具：`--script res://smoke/level_monte_carlo.gd`（关卡期望扫描）· `--script res://smoke/reward_expectation.gd`（奖励获取期望）
- 交付前纪律：smoke + 全部场景探针全绿（见下方代码规范·测试条）

## Engine Version Reference

@docs/engine-reference/godot/VERSION.md

## Project Layout

- `design/gdd/` — 现行设计文档（2026-09-14 重建的循环式新骨架）：6 份顶层文档（`00-游戏概念` / `01-核心循环` / `02-系统清单`〔根索引〕 / `03-内容规模` / `04-美术音频方向` / `05-不做清单`）+ `systems/` 按四个循环组织子系统文档（排雷循环 / 战斗循环 / 冒险循环 / 表现与支撑），子系统一律中文见名知意命名、不带编号前缀；文档增删必须同步 `02-系统清单.md`
- `design/archive/gdd-2026-09-14/` — 旧版 GDD 体系归档（只读参考，不再维护，不作事实引用）
- `design/registry/entities.yaml` — 跨系统事实登记表（已锁数值；仅 owner 文档可修订，冲突须显式提出）
- `production/` — stage、session-state、gate-checks
- `prototypes/` — `dungeon-sweeper-vertical-slice/` 垂直切片（概念 demo 已删除，验证报告留档 `docs/prototype-report-minesweeper-battle-concept.md`）
- `docs/` — 代码规范（`code-conventions.md`）· **文档写作规范（`doc-conventions.md`，写文档前必读）** · 架构与 ADR（`architecture/`）· 引擎参考（`engine-reference/`）

## Conventions（评审确立，勿违反）

- **数值单一事实源**：全部玩法数值存 `data/tables/`（.tres），经 `ConfigDB` autoload 类型化单点读取；玩法代码禁止数值字面量与自建 `load()` 表路径（D2 Rule 1/2）
- **RNG 单点**：禁止 `randomize()`/自建 RandomNumberGenerator——随机只经 `RngService` 封闭命名流（D2 Rule 5）
- **Core 层零 UI 依赖**：完整战斗必须可 `godot --headless --script` 运行（D2 Rule 7）
- **fail-fast**：数据校验错误一律致命中止，无软回退（D2 Rule 6）
- **spec-AC 一致性**：规约与验收标准不得在同一输入上给出不同答案——D2 两轮评审确立的阻塞标准，所有 GDD 同尺度
- GDD 评审纪律：`/design-review` 必须在独立会话跑（与 `/design-system` 隔离）
- **文档写作规范（2026-09-14 成文，写任何文档前必读）**：在编写、修改任何设计文档之前，必须先通读 `docs/doc-conventions.md`（全文权威——整合原用语纪律〔2026-09-09〕、文档形态纪律〔2026-09-13〕、两件套与树形文档体系纪律〔2026-09-14〕、新骨架过渡口径〔2026-09-14〕，并新增可读性第一纪律）。要点：**可读性第一**——读者测试三问（管的是谁/什么？什么情况下？会发生什么？）答不出就重写该节；白话完整句、散文讲道理、表格放数据；禁自造黑话（唯一例外 = 玩家可见专属名词）；树形文档体系，文档增删必须同步根索引 `design/gdd/02-系统清单.md`；节点一页纸以内；每个子系统一份设计文档、不建 analysis 推演件；正文只写现行规则，修订只进文末「版本历史」表；跨文档引用纪律（单点定义 / 规范名唯一 / 引用不转述 / 反向边登记 / 删除概念 SOP）见该文第 7 节；已锁数值事实源 = `design/registry/entities.yaml` 与 `data/tables/`。旧体系 lean 格式与 `gdd_lint` 门禁仅用于解读归档（`design/archive/gdd-2026-09-14/`），不约束现行文档。

## 代码规范（写代码前必读，2026-09-11 用户拍板成文）

**在编写、修改任何代码之前，必须先通读 `docs/code-conventions.md`**——该文档由用户指出的真实陋习与缺陷逐条成文，含结构/契约/测试/语言/数值/流程六类硬性纪律与本项目反面案例对照表。摘要（全文以文档为准）：

- **结构**：禁止上帝对象；功能以类封装；views →(信号)→ 组合根 →(写调用)→ core 依赖单向；核心写调用只在组合根发生
- **命名**：领域命名，禁止系统 ID 前缀（a1_/b1_/c1_）进入文件名与类名（子系统中文规范名 ↔ 英文代号对照表见 `design/gdd/02-系统清单.md`）；核心文件头注必须带「实现 GDD」溯源行；禁止事实约定——未成文的约定当场补条文
- **契约**：信号/事件契约成文，状态机每条迁移路径都必须发事件（缺事件 = 软锁）；跨层标识符语义单一（位置 ≠ 句柄）；模态覆盖层打开必须隐藏遮挡物
- **测试**：每个可交互 UI 区域必须配套场景级探针（只有 core AC 不算有测试）；缺陷修复必须沉淀回归断言；提交前 smoke + 全部场景探针全绿
- **数值**：期望值必须标明尺度（每格/每板/每战/每关）；调参先测量后复测；单尺度校准必须跨尺度推演；用户拍板外的细节零发挥，列"待拍板"等裁决