gplan-2/.claude/docs/technical-preferences.md

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