# 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 |