forked from datawhale/whale-town-front
moyin
0edd1c740b
- 修复README.md中的emoji字符显示问题 - 移除文档质量评级系统 - 添加贡献者致谢部分，创建详细的CONTRIBUTORS.md - 创建核心系统文件EventNames.gd和ProjectPaths.gd - 更新项目配置文件project.godot，添加输入映射 - 完善各模块文档，修正路径引用问题 - 创建文档更新日志CHANGELOG.md - 优化文档结构和导航系统
123 lines
5.1 KiB
Markdown
123 lines
5.1 KiB
Markdown
# 🎯 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提交规范
|
||
|
||
---
|
||
|
||
**记住：代码质量是游戏成功的基础！** |