# 🎯 WhaleTown 项目开发规范

## 1. 项目愿景与背景
- **项目名称**: "WhaleTown" - 一个2D俯视角像素风RPG游戏
- **引擎**: Godot 4.2+ (严格禁止使用Godot 3.x语法)
- **架构**: 严格分层架构：`_Core`(框架层)、`Scenes`(游戏层)、`UI`(界面层)
- **核心原则**: "信号向上，调用向下"。通过`EventSystem`实现高度解耦

## 2. 🛠 命令参考与设置
- **输入映射 (必需配置)**:
  - `move_left`, `move_right`, `move_up`, `move_down` (WASD / 方向键)
  - `interact` (E键 / 空格键)
  - `pause` (ESC键)
- **运行游戏**: `godot --path .`
- **运行测试 (GUT)**: `godot --headless -s addons/gut/gut_cmdline.gd -gdir=res://tests/ -ginclude_subdirs`
- **初始化结构**: `mkdir -p _Core/managers _Core/systems Scenes/Maps Scenes/Entities Scenes/Components UI/Windows UI/HUD Assets/Sprites tests/unit tests/integration`

## 3. 📂 文件路径规则 (严格小写)
*注意：根目录文件夹必须小写。脚本和场景必须放在一起。*
- **核心管理器**: `_Core/managers/[Name].gd`
- **核心系统**: `_Core/systems/[Name].gd`
- **实体**: `Scenes/Entities/[EntityName]/[EntityName].tscn` (脚本`.gd`放在同一文件夹)
- **地图**: `Scenes/Maps/[map_name].tscn`
- **组件**: `Scenes/Components/[ComponentName].gd` (可复用逻辑节点)
- **UI窗口**: `UI/Windows/[WindowName].tscn`
- **测试**: `tests/[unit|integration]/test_[name].gd` (文件夹名为小写`tests`)

## 4. 📋 编码标准 (必须遵守)
- **类型安全**: 始终使用严格静态类型：`var speed: float = 100.0`, `func _ready() -> void`
- **命名约定**: 
  - 每个脚本顶部必须有`class_name PascalCase`
  - 变量/函数：`snake_case`。常量：`SCREAMING_SNAKE_CASE`
  - 私有成员：使用下划线前缀`_` (例如：`var _health: int`)
- **节点访问**: 对UI和内部场景组件使用`%UniqueName`
- **信号**: 使用"信号向上，调用向下"原则。父节点调用子节点方法；子节点发出信号
- **禁止模式**:
  - ❌ 禁止使用`yield()` -> 使用`await`
  - ❌ 禁止在`_process`中使用`get_node()` -> 使用`@onready`缓存
  - ❌ 禁止线性过滤 -> 所有Sprite2D/TileMap资源必须使用**最近邻**过滤

## 5. 🏛 架构与通信
- **事件系统**: 使用`_Core/systems/EventSystem.gd`进行跨模块消息传递
- **事件注册**: 在`_Core/EventNames.gd`中使用`class_name EventNames`
  ```gdscript
  class_name EventNames
  const PLAYER_MOVED = "player_moved"
  const INTERACT_PRESSED = "interact_pressed"
  const NPC_TALKED = "npc_talked"
  ```
- **单例**: 只允许GameManager、SceneManager、EventSystem作为自动加载
- **解耦**: 底层实体不得直接引用GameManager。使用事件系统

## 6. 🏗 实现细节
- **玩家**: 使用CharacterBody2D。必须包含Camera2D，设置`position_smoothing_enabled = true`
- **NPC/交互物**: 使用名为InteractionArea的Area2D。通过EventSystem触发
- **TileMap图层**:
  - 图层0：地面 (无碰撞)
  - 图层1：障碍物 (启用物理层)
  - 图层2：装饰 (启用Y排序)
- **相机**: 必须通过`TileMap.get_used_rect()`自动计算边界

## 7. 🧪 测试要求 (强制性)
- **覆盖率**: `_Core/`中的每个管理器/系统都必须有GUT测试
- **命名**: 测试文件必须以`test_`开头并继承`GutTest`
- **示例**:
  ```gdscript
  extends GutTest
  func test_event_emission():
      var sender = Node.new()
      watch_signals(EventSystem)
      EventSystem.emit_event(EventNames.PLAYER_MOVED, {})
      assert_signal_emitted(EventSystem, "event_raised")
  ```

## 8. 🧘 开发哲学
- **流畅体验**: 每个交互(UI弹窗、NPC对话)都必须有Tween动画占位符
- **零魔法数字**: 所有速度/计时器必须使用`@export`或在`Config/`中定义
- **简洁性**: 如果一个函数做两件事，就拆分它
- **隐藏逻辑**: 隐藏的逻辑(如ResponseHandler.gd)必须和HUD一样干净

## 9. 📝 代码模板 (实体模式)
```gdscript
extends CharacterBody2D
class_name Player

# 1. 导出变量与常量
@export var move_speed: float = 200.0

# 2. 节点引用
@onready var sprite: Sprite2D = %Sprite2D

# 3. 生命周期
func _physics_process(delta: float) -> void:
    _move(delta)

# 4. 私有方法
func _move(_delta: float) -> void:
    var dir := Input.get_vector("move_left", "move_right", "move_up", "move_down")
    velocity = dir * move_speed
    move_and_slide()
```

## 10. 🎨 UI设计规范
- **响应式布局**: 使用Anchor和Margin实现自适应
- **主题统一**: 所有UI组件使用统一主题资源
- **动画效果**: 界面切换必须有过渡动画
- **无障碍支持**: 支持键盘导航

## 11. 🔧 性能优化
- **对象池**: 频繁创建销毁的对象使用对象池
- **视锥剔除**: 只渲染可见区域的对象
- **批量处理**: 合并相似的渲染调用
- **内存管理**: 及时释放不需要的资源

## 12. 📚 最佳实践
- **模块化**: 功能拆分为独立模块
- **可测试**: 设计易于测试的代码结构
- **文档化**: 为复杂逻辑添加详细注释
- **版本控制**: 遵循Git提交规范

---

**记住：代码质量是游戏成功的基础！**