chore: initial commit

2026-09-14 18:18:49 +08:00
commit ddd2960fa6
@@ -0,0 +1,71 @@
+# Technical Preferences
+
+## Engine & Language
+
+- **Engine**: Godot 4.7.2-stable（2026-09-07 锁定；4.7 分支最新维护版）
+- **Language**: GDScript（唯一项目语言——与 `design/gdd/d2-data-config.md` 实现级规约一致：二补数回绕语义、`--headless --script` 冒烟、autoload/.tres 体系）
+- **Renderer**: 2D 项目；Forward+ / gl_compatibility 的选择留实现期 ADR
+- **Headless 约束**: Core 层玩法逻辑必须 `godot --headless --script` 可完整运行（D2 Rule 7 工程债）
+
+## Naming Conventions (GDScript)
+
+- Classes: PascalCase（`PlayerController`）
+- Variables/functions: snake_case（`move_speed`）
+- Signals: snake_case 过去式（`health_changed`）
+- Files: snake_case 对应类名（`player_controller.gd`）
+- Scenes: PascalCase 对应根节点（`PlayerController.tscn`）
+- Constants: UPPER_SNAKE_CASE（`MAX_HEALTH`）
+- Autoload 单例: PascalCase——**`ConfigDB`、`RngService` 已由 D2 GDD 定名，勿改**
+
+## Input & Platform
+
+- **Target Platforms**: PC (Steam)
+- **Input Methods**: Keyboard/Mouse（主——挖/旗/移动为鼠标驱动），Gamepad（Partial）
+- **Primary Input**: Keyboard/Mouse
+- **Gamepad Support**: Partial（Steam 上架建议支持，非 MVP 门禁）
+- **Touch Support**: None
+- **Platform Notes**: 回合制可全点击驱动，无 hover-only 交互；UI 需兼容纯鼠标完成全部操作
+
+## Performance Budgets（2D 回合制默认值，实现期可调）
+
+- Target FPS: 60
+- Frame Budget: 16.6 ms
+- Draw Calls: < 200（棋盘格子 + 数字标签同屏；超出再谈合批）
+- Memory: < 500 MB
+- Headless 冒烟全套: < 30 s
+
+## Testing
+
+- **现行载体**: `godot --headless --script` 冒烟框架——脚本 extends SceneTree 以获得 `quit(code)`；该模式下 autoload 须由脚本显式实例化（D2 GDD 决策，AC 套件执行前提）
+- **gdUnit4**: 是否引入并迁移冒烟用例 → Technical Setup 阶段决策（d2-data-config.md OQ1，未决）
+- **测试通道**: `load_tables(root, collect_only=true)` + `--data-root=` 夹具注入（仅 debug 构建）；致命类用例按独立进程"调用 → 期望退出码"枚举
+
+## Forbidden Patterns
+
+[TO BE CONFIGURED]
+
+## Allowed Libraries
+
+[TO BE CONFIGURED——仅在实际集成时登记，不预填]
+（gdUnit4 若在 Technical Setup 引入，届时登记于此。）
+
+## Engine Specialists
+
+- **Primary**: godot-specialist
+- **Language/Code Specialist**: godot-gdscript-specialist（全部 .gd 文件）
+- **Shader Specialist**: godot-shader-specialist（.gdshader、VisualShader）
+- **UI Specialist**: godot-specialist（无专职 UI specialist）
+- **Additional Specialists**: godot-gdextension-specialist（仅 GDExtension/原生插件）
+- **Routing Notes**: 架构决策/ADR 校验/跨切面审查走 primary；.gd 代码质量、信号架构、静态类型、GDScript 惯用法走 GDScript 审查；材质/着色器走 shader specialist。
+- **本工具链映射**: 上述 specialist 以 general-purpose 子 agent + `godot-master` 技能承载（无独立 agent 类型注册）。
+
+### File Extension Routing
+
+| 文件类型 | Specialist |
+|---|---|
+| 游戏代码（.gd） | godot-gdscript-specialist |
+| 着色器（.gdshader / VisualShader） | godot-shader-specialist |
+| UI（Control / CanvasLayer） | godot-specialist |
+| 场景/资源（.tscn / .tres） | godot-specialist |
+| 原生扩展（.gdextension / C++） | godot-gdextension-specialist |
+| 架构审查 | godot-specialist |
@@ -0,0 +1,152 @@
+<!-- 模板 v2（2026-09-14）：参考 analysis/design 两件套重构，覆盖 design-system 内置骨架。
+     design.md 只写结论；设计推演（候选取舍/机理/理由）写 companion：
+     design/gdd/analysis/[system-name].md（骨架见本文件末尾注释）。
+     门禁：tools/gdd_lint.py（design.md 写作时逐条对照，提交前必须 PASS；
+     analysis 件以推演散文为主，不入 GDD 门禁）。
+     门禁对应：段落 ≤240 字(R1) · 表格占比 ≥30%(R2) · 无修订注记(R3) · 版本历史(R4)
+               · 流程节含图(R5) · 括号跨度 ≤80(R7) · 节点 ≤80 行(R9)。 -->
+
+# [系统名称]
+
+> **状态**：In Design · **版本**：v1 · [日期]
+> **一句话**：[这个系统做什么，一句话，≤30 字]
+> **推演件**：`design/gdd/analysis/[system-name].md`（本文件只收结论，理由在那里）
+
+## 设计目的
+
+<!-- 一段定位（≤3 行）+ 3-5 条编号体验承诺（玩家视角一句话）。
+     玩家看不见的基础设施系统：体验承诺改为"它让谁、在哪一步、省掉什么"。 -->
+
+[一段定位：这个系统为什么存在，游戏少了它会失去什么。]
+
+1. [玩家视角体验承诺]
+2. [体验承诺]
+3. [体验承诺]
+
+## 系统范围
+
+<!-- 边界优先条款：两份清单是本 GDD 最承重的内容——实现者靠"不负责"判断票面。
+     与 systems-index 依赖分层保持一致；划给邻系统的条目注明归属。 -->
+
+负责：
+
+- [能力/数据/规则]
+
+不负责：
+
+- [明确不做/划给谁的内容——括注归属系统]
+
+## 核心循环
+
+<!-- 主流程 mermaid 或字符画（``` 围栏）；分支/结局用出口分发表。禁止散文描述步骤。 -->
+
+```mermaid
+flowchart TD
+  A["起点"] --> B["..."]
+```
+
+| 结局 | 触发 | 结果 |
+|---|---|---|
+| | | |
+
+## [领域章节]（按系统自定义 2–6 节）
+
+<!-- 系统的实体内容按领域拆节（参考写法：地块状态 / 水规则 / 出战输出）。
+     每节形态：状态/枚举/字段一律表格；规则一律编号人话句（谁·何时·做什么），
+     边界内联在句尾（"不做 X""不返还 Y"）；每节末尾可加一行"设计意图"（≤1 行），
+     更长的理由去 analysis 件。 -->
+
+### [小节名]
+
+| 状态 | 含义 | 玩家/系统可做 |
+|---|---|---|
+| | | |
+
+规则：
+
+1. [谁]在[什么情况]下[做什么]；[边界：不做 X]。
+2. [规则二]。
+
+设计意图：[一行；为什么是这条而不是别的——超过一行去 analysis。]
+
+## 依赖与输出
+
+<!-- 上游/下游一张表：系统 | 性质(hard/soft) | 接口要点（一行）。
+     数值单一事实源纪律不变：已锁数值进 design/registry，正文只引用不复述。 -->
+
+| 方向 | 系统 | 性质 | 接口要点 |
+|---|---|---|---|
+| 上游 | | | |
+| 下游 | | | |
+
+## P0 最小闭环
+
+<!-- 编号步骤，从玩家动作到结果回收，≤8 步。写不出 8 步内的闭环 = 范围没收敛，
+     回系统范围节砍。 -->
+
+1. [玩家/系统动作]
+2. [……]
+3. [结果回流到循环起点]
+
+## P1 / P2 后置
+
+<!-- 优先级诚实条款：本期不做但已经想到的，全部落表并给后置原因。
+     后置 ≠ 删除；复活任何一行 = 修订本 GDD，不许静默加回。 -->
+
+| 优先级 | 内容 | 后置原因 |
+|---|---|---|
+| P1 | [内容] | [为什么现在不做——通常是要先验证 P0 的某个前提] |
+| P2 | [内容] | [理由] |
+
+## 调参表（无独立数值的系统可省）
+
+<!-- 全部可调参数：字段 | 域 | 默认 | owner。默认值 provisional 必须标注；
+     已锁数值以 design/registry 为准，本表只登记字段与域，不复述锁值。 -->
+
+| 字段 | 域 | 默认 | owner | 说明 |
+|---|---|---|---|---|
+| | | | | |
+
+## 验收标准
+
+<!-- 默认形态：目标 | 验证问题——每条可由真人一局内回答。
+     项目若直接从 GDD 实现并以冒烟验收（如本项目），改用 Given-When-Then 表；
+     AC/规则/公式编号只出现在举证与依据列，不进人话。 -->
+
+| 目标 | 验证问题 |
+|---|---|
+| [P0 闭环成立] | [玩家能否……/当……时系统是否……] |
+| | |
+
+## 版本历史
+
+| 版本 | 日期 | 改动 |
+|---|---|---|
+| v1 | [日期] | 初始版本 |
+
+<!-- ==================== companion 模板 ====================
+     写入 design/gdd/analysis/[system-name].md（不入 lint；每次写入后无需 PASS）：
+
+# [系统名称] 设计推演
+
+> 状态：concluded · 本文只装"为什么"——design.md 只收本文的结论。
+> 修订时新增问题节，不删旧节（历史即依据）。
+
+## 问题：[一句设计问题]？
+
+### 广度分析
+
+- [候选 A：收益 + 代价]
+- [候选 B：收益 + 代价]
+- [候选 C：……]
+
+### 深度分析
+
+[1-2 段机理与约束分析，每段 ≤3 行。]
+
+### 综合判断
+
+[定论一段。design.md 对应章节只应出现这里的结论，不复述理由。]
+
+（按需重复「问题」节，每系统 2–4 个为宜；琐碎系统可只写一节。）
+==================================================================== -->