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

扫雷推理层 + 自动战斗结算的两段式回合 Roguelike。个人开发，MVP 优先管线。设计入口（独立版 GDD）：design/gdd/gdd.md · 概念：design/gdd/game-concept.md · 支柱：design/gdd/game-pillars.md · 系统索引：design/gdd/systems-index.md

Technology Stack

Engine: Godot 4.7.2
Language: GDScript
Build System: SCons (engine), Godot Export Templates
Asset Pipeline: Godot Import System + custom resource pipeline

Engine Version Reference

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

Project Layout

design/gdd/ — 独立版入口 gdd.md（6 节讲清游戏：概念/循环/系统清单/规模/美术/不做清单——人类读者与 30 秒 pitch 的入口层，只导航不另立事实）+ 概念、支柱、系统索引、逐系统 GDD（lean 模板：.claude/docs/templates/game-design-document.md；2026-09-13 前的旧版全文备份在 design/gdd/legacy-2026-09-13/）
design/registry/entities.yaml — 跨系统事实登记表（已锁数值；仅 owner GDD 可修订，冲突须显式提出）
design/gdd/reviews/ — design-review 日志（含 delta 复核清单）
production/ — stage、session-state、gate-checks
prototypes/ — dungeon-sweeper-vertical-slice/ 垂直切片（概念 demo 已删除，验证报告留档 docs/prototype-report-minesweeper-battle-concept.md）

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-09 评审确立，勿违反）：GDD、评审输出、日志与一切沟通中禁止自造黑话——比喻性生造词、只有作者自己懂的缩略语（反例："非雾腿""双闸"）。只能使用（a）人人可懂的直白语言，或（b）游戏行业通用专业术语（如 flood fill、战争迷雾、连锁展开、结算、增益/减伤）。需要指代新概念时，用直白描述性短语（正例："剔除雾格后的可推理率""两项达标判据"）；确需给新概念命名时，首次出现处必须附一句白话定义并登记 design/registry 术语条目——不得让读者猜测比喻含义。（2026-09-14 增补）自造词的唯一例外 = 玩家在游戏里也会看到的专属名词（道具名、界面用语，如"显影尘""探巢摆钟"）——文档内部的机制概念不得造词，一律直白描述。
文档形态纪律（2026-09-13 评审确立，勿违反）：GDD 及一切设计文档遵循 lean 格式——模板 .claude/docs/templates/game-design-document.md，门禁 tools/gdd_lint.py（新文档与每次修订后必须 PASS）。六条硬规则：① 散文段 ≤240 字，全文表格占比 ≥60%；② 枚举、数值边界、边界情况、依赖一律表格；流程一律字符画（代码块）或出口分发表，禁止散文描述步骤；③ 体验锚点用关键词（支柱 | 关键词 | 机制承诺表），禁长篇情绪描述；④ 公式结论先行——先一行加粗结论，再"推导"小标题放公式代码块、Variables 表与验算表，公式本体必须保留（推理证明不可省）；⑤ 修订历史只写文末「版本历史」表——正文禁止 ~~删除线~~、"（作废）"、"（日期+评审/修订/拍板）"式注记；义务台账、拍板记录、registry 回执等审计元数据入 design/registry 或附录，不入正文。评审发现写 review log，正文只收干净的现行规则；⑥ 规则两段式：人话先行、举证在后（可读性承重条款）：核心规则/玩法/系统按两段写——人话阶段：作用于哪个系统、在什么情况下、谁触发、触发后发生什么；效果与情况用枚举表列出；举证阶段：逐效果给出计算方法/公式（就地给出或指向公式节）；纯流程规则明写"无计算"。读者测试：没读过本文档的人能否回答"管的是谁？什么时候？会发生什么？"——答不出就重写。规则名禁止纯名词短语（反例："获取路由""编排被动性"）；编号引用（AC-x / F-x / EC-x / 义务×）不进人话，只进举证与依据。（2026-09-14 用户拍板增补）：R2 表格占比阈值已由 60% 放宽至 30%（防铺开职责由 R1/R9 承担）——既有 13 份 GDD 按旧口径继续成立，不回改。
两件套纪律（2026-09-14 用户拍板，新系统 GDD 即日生效）：新系统设计文档写一对——design/gdd/[system].md 只装结论（设计目的/系统范围[负责·不负责]/核心循环/领域章节×2–6/依赖与输出/P0 最小闭环/P1·P2 后置表/调参表/验收标准/版本历史），设计推演（候选取舍、机理、为什么）装 design/gdd/analysis/[system].md（每个问题四段：广度分析→深度分析→综合判断；不入 lint 门禁，钩子豁免）。判据：正文出现超过一行的"为什么"即违规——挪 analysis。优先级诚实条款：后置 ≠ 删除，复活后置行 = 修订 GDD，禁止静默加回。数值默认后置：正文定规则/域/单位，平衡值进数据表（provisional 必须标注）。既有 13 份 GDD 维持 lean v1 形态不回改；模板 v2 与 analysis 骨架见 .claude/docs/templates/game-design-document.md。 ⑦ 树形文档体系与一页纸节点（导航承重条款）：全部设计文档构成一棵树——根索引 systems-index 承载整棵树的形状与每个节点的一句话概要，读者靠索引决定进入哪个节点，索引必须随文档增删同步维护。树内每个节点（GDD 内的每一节、每条规则、每张公式）内容控制在一页纸内（直接内容 ≤80 行，tools/gdd_lint.py R9 强制）：装不下就拆成子节点，禁止铺开；节点内顺序 = 人话 → 表格枚举 → 字符流程图 → 举证公式。session-state 条目纪律：production/session-state/active.md 每条进度 ≤3 行（粗体键 + 短句），详情一律外链到对应 GDD/报告/日志，禁止把定稿摘要、义务清单、回写清单整段塞进条目。

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

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

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

8.0 KiB Raw Blame History Unescape Escape

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