whale-town-front/开发规范.md

🎯 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

  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
• 示例:

  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. 📝 代码模板 (实体模式)

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提交规范

---

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