47 lines
8.0 KiB
Markdown
47 lines
8.0 KiB
Markdown
# 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 + 全部场景探针全绿
|
||
- **数值**：期望值必须标明尺度（每格/每板/每战/每关）；调参先测量后复测；单尺度校准必须跨尺度推演；用户拍板外的细节零发挥，列"待拍板"等裁决
|