forked from datawhale/whale-town-front
docs: 文档中文化和清理
新增: - 开发规范.md (翻译自CLAUDE.md) 重命名为中文: - project_structure.md 项目结构说明.md - naming_convention.md 命名规范.md - code_comment_guide.md 代码注释规范.md - git_commit_guide.md Git提交规范.md - api-documentation.md API接口文档.md - network_manager_setup.md 网络管理器设置.md - setup.md 项目设置指南.md - testing_guide.md 测试指南.md - web_deployment_guide.md Web部署指南.md - module_development.md 模块开发指南.md - performance_optimization.md 性能优化指南.md - scene_design.md 场景设计规范.md - auth/form_validation.md auth/表单验证规范.md - auth/testing_guide.md auth/认证测试指南.md 删除总结性文档: - final_update_summary.md - web_deployment_changelog.md - CLAUDE.md
This commit is contained in:
123
开发规范.md
Normal file
123
开发规范.md
Normal file
@@ -0,0 +1,123 @@
|
||||
# 🎯 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提交规范
|
||||
|
||||
---
|
||||
|
||||
**记住：代码质量是游戏成功的基础！**
|
||||
Reference in New Issue
Block a user