datawhale/whale-town-front
3
2
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore：清理临时文档文件

Browse Source 
- 删除迁移完成标记文件 MIGRATION_COMPLETE.md
- 删除重构说明文件 REFACTORING.md
- 删除结构对比文件 STRUCTURE_COMPARISON.md
- 删除临时文档 cloude.md
This commit is contained in:
moyin
2026-01-02 00:57:53 +08:00
parent fdedb21cbd
commit fca3eb79dd
4 changed files with 0 additions and 793 deletions
Download Patch File Download Diff File Expand all files Collapse all files

235
MIGRATION_COMPLETE.md
View File

@@ -1,235 +0,0 @@
# ✅ 项目结构重构完成报告
## 📅 完成时间
2025-12-31
## 🎉 重构成功
项目已成功从混乱的文件结构重构为清晰、模块化的架构！
---
## 📊 最终结构总览
```
whale-town-front/
├── _Core/ ✅ [框架层] 全局单例和系统
├── Scenes/ ✅ [玩法层] 游戏世界实体
├── UI/ ✅ [界面层] 所有UI界面
├── Assets/ ✅ [资源层] 美术资源
├── Config/ ✅ [配置层] 静态数据
├── Utils/ ✅ [工具层] 工具类
├── Tests/ ✅ [测试层] 测试脚本
└── docs/ 📄 项目文档
```
---
## ✅ 已完成的迁移
### 1️⃣ 框架层 (_Core/)
- ✅ `GameManager.gd` → `_Core/managers/`
- ✅ `SceneManager.gd` → `_Core/managers/` (已更新路径)
- ✅ `NetworkManager.gd` → `_Core/managers/`
- ✅ `ResponseHandler.gd` → `_Core/managers/`
- ✅ `EventSystem.gd` → `_Core/systems/`
### 2️⃣ 场景层 (Scenes/)
- ✅ `scenes/main_scene.tscn` → `Scenes/Maps/main_scene.tscn`
- ✅ `scripts/scenes/MainScene.gd` → `Scenes/Maps/MainScene.gd`
- ✅ `scenes/prefabs/` → `Scenes/Components/`
### 3️⃣ 界面层 (UI/)
- ✅ `scenes/auth_scene.tscn` → `UI/Windows/LoginWindow.tscn`
- ✅ `scripts/scenes/AuthScene.gd` → `UI/Windows/AuthScene.gd`
- ✅ `assets/ui/chinese_theme.tres` → `UI/Theme/MainTheme.tres`
- ✅ `assets/fonts/` → `UI/Theme/Fonts/`
### 4️⃣ 配置层 (Config/)
- ✅ `data/configs/game_config.json` → `Config/game_config.json`
- ✅ `data/localization/zh_CN.json` → `Config/zh_CN.json`
### 5️⃣ 工具层 (Utils/)
- ✅ `core/utils/StringUtils.gd` → `Utils/StringUtils.gd`
### 6️⃣ 资源层 (Assets/)
- ✅ `assets/sprites/` → `Assets/Sprites/`
- ✅ `assets/audio/` → `Assets/Audio/`
- ✅ 其他资源文件保留在 `assets/`（待后续整理）
### 7️⃣ 构建脚本
- ✅ `scripts/build_web.sh` → `./build_web.sh`
- ✅ `scripts/serve_web.sh` → `./serve_web.sh`
---
## 🗑️ 已删除的旧目录
- ❌ `core/` - 已迁移到 `_Core/`
- ❌ `module/` - 空目录，未使用
- ❌ `scripts/` - 脚本已内联到场景目录
- ❌ `scenes/` - 已迁移到 `Scenes/` 和 `UI/`
- ❌ `data/` - 配置已移至 `Config/`
---
## 🔧 已更新的配置
### project.godot
```ini
✅ run/main_scene="res://Scenes/Maps/main_scene.tscn"
✅ GameManager="*res://_Core/managers/GameManager.gd"
✅ SceneManager="*res://_Core/managers/SceneManager.gd"
✅ EventSystem="*res://_Core/systems/EventSystem.gd"
✅ NetworkManager="*res://_Core/managers/NetworkManager.gd"
✅ ResponseHandler="*res://_Core/managers/ResponseHandler.gd"
```
### SceneManager.gd
```gdscript
✅ "main": "res://Scenes/Maps/main_scene.tscn"
✅ "auth": "res://UI/Windows/LoginWindow.tscn"
```
### 测试文件
```gdscript
✅ tests/auth/enhanced_toast_test.gd - 已更新脚本路径
✅ tests/auth/auth_ui_test.tscn - 已更新场景路径
```
---
## 📚 创建的文档
1. **REFACTORING.md** - 详细的重构文档
- 迁移映射表
- 设计原则
- 注意事项
- 后续建议
2. **STRUCTURE_COMPARISON.md** - 结构对比分析
- 旧结构问题分析
- 新结构优势说明
- 对比表格
- 团队协作改进
---
## 🎯 关键改进
### 清晰的分层
- **_Core**: 框架代码，全局系统
- **Scenes**: 游戏世界，地图和实体
- **UI**: 所有界面，HUD和弹窗
- **Config**: 静态数据，策划可编辑
- **Utils**: 通用工具函数库
### 组件化设计
```gdscript
Scenes/Components/ // 可复用组件
├── characters/ // 角色预制体
├── effects/ // 特效预制体
├── items/ // 物品预制体
└── ui/ // UI预制体
```
### 场景内聚
- 每个 `.tscn` 配套一个 `.gd`
- 脚本紧邻场景文件
- 符合 Godot 原生习惯
### UI 独立化
```
UI/
├── Windows/ // 模态窗口（登录、设置）
├── HUD/ // 常驻界面（聊天框）
├── Dialog/ // 对话系统
└── Theme/ // 全局样式
```
---
## ⚠️ 后续步骤
### 必做事项
- [ ] 在 Godot 编辑器中打开项目，让编辑器重新索引文件
- [ ] 测试主场景加载: `Scenes/Maps/main_scene.tscn`
- [ ] 验证登录窗口: `UI/Windows/LoginWindow.tscn`
- [ ] 测试所有自动加载脚本
- [ ] 运行完整测试套件
### 建议优化
- [ ] 补充 `Scenes/Components/` 下的可复用组件
- [ ] 完善 `UI/HUD/` 和 `UI/Dialog/`
- [ ] 添加 `Scenes/Entities/Player/` 玩家实体
- [ ] 将硬编码数值移至 `Config/`
### 代码审查
- [ ] 检查是否还有硬编码的旧路径
- [ ] 验证所有 `.import` 文件正常
- [ ] 确认网络连接功能正常
- [ ] 验证 UI 主题显示正确
---
## 🎓 团队协作指南
### 工作目录划分
```
🎨 美术组 → Assets/Sprites/, Assets/Audio/
📋 策划组 → Config/
💻 前端程序 → UI/, Scenes/Entities/
⚙️ 后端程序 → _Core/, Utils/
🧪 测试组 → Tests/
```
### Git 提交建议
```bash
# 按目录分类提交
git add _Core/
git commit -m "refactor: 迁移核心框架代码到 _Core/"
git add Scenes/
git commit -m "refactor: 重组场景文件到 Scenes/"
git add UI/
git commit -m "refactor: 独立 UI 界面到 UI/"
```
---
## 📈 预期收益
### 可维护性提升
- 🟢 目录职责清晰，降低认知负担
- 🟢 新人快速定位文件
- 🟢 减少代码冲突
### 开发效率提升
- 🟢 组件复用更容易
- 🟢 团队协作更流畅
- 🟢 代码审查更高效
### 符合最佳实践
- ✅ Godot 官方推荐结构
- ✅ 场景内聚原则
- ✅ 组件化设计思想
- ✅ 配置与代码分离
---
## 🎉 总结
**重构完成！** 项目现在拥有：
- ✅ 清晰的 6 层架构
- ✅ 符合 Godot 最佳实践
- ✅ 易于维护和扩展
- ✅ 团队协作友好
感谢您的耐心！如有问题，请查看详细文档：
- [REFACTORING.md](./REFACTORING.md) - 重构详情
- [STRUCTURE_COMPARISON.md](./STRUCTURE_COMPARISON.md) - 结构对比
---
**下一步：在 Godot 编辑器中打开项目并测试！** 🚀

222
REFACTORING.md
View File

@@ -1,222 +0,0 @@
# 项目结构重构文档
## 📅 重构时间
2025-12-31
## 🎯 重构目标
将项目从混乱的文件结构重构为清晰、模块化的架构，采用 Godot 最佳实践。
## 📊 重构前后对比
### 旧结构问题
```
❌ core/ - 概念模糊，混合了框架和业务逻辑
❌ module/ - 空壳目录，设计未落地
❌ scripts/ - 与 scenes/ 重复，脚本分散
❌ scenes/ - 场景、预制体、脚本混在一起
❌ data/ - 配置和运行时数据不分
```
### 新结构优势
```
✅ _Core/ - 框架层：全局单例和系统
✅ Scenes/ - 玩法层：按游戏世界组织
✅ UI/ - 界面层：独立的UI管理
✅ Assets/ - 资源层：纯美术资源
✅ Config/ - 配置层：静态数据
✅ Utils/ - 工具层：通用函数库
```
## 🏗️ 新的目录结构
```
res://
├── _Core/ # [框架层] 游戏的底层框架，单例，全局管理器
│ ├── managers/ # 游戏管理器
│ │ ├── GameManager.gd # 游戏状态管理
│ │ ├── SceneManager.gd # 场景管理（已更新路径）
│ │ ├── NetworkManager.gd # 网络通信
│ │ └── ResponseHandler.gd # API响应处理
│ ├── systems/ # 核心系统
│ │ └── EventSystem.gd # 事件系统
│ └── singletons/ # 其他单例（待扩展）
│
├── Scenes/ # [玩法层] 具体的游戏场景、实体、地图
│ ├── Maps/ # 地图场景
│ │ └── main_scene.tscn # 主游戏场景
│ ├── Entities/ # 游戏实体
│ │ ├── Player/ # 玩家实体
│ │ ├── NPC/ # NPC实体
│ │ └── Interactables/ # 交互物
│ └── Components/ # 可复用组件
│
├── UI/ # [界面层] 所有UI相关的预制体和逻辑
│ ├── HUD/ # 抬头显示（常驻）
│ ├── Windows/ # 模态窗口
│ │ └── LoginWindow.tscn # 登录窗口（原auth_scene.tscn）
│ ├── Dialog/ # 对话系统
│ └── Theme/ # 全局样式
│ ├── MainTheme.tres # 主主题
│ └── Fonts/ # 字体文件
│
├── Assets/ # [资源层] 美术、音频、字体
│ ├── Sprites/ # 精灵图
│ ├── Audio/ # 音频
│ └── Fonts/ # 字体
│
├── Config/ # [配置层] 游戏配置文件
│ ├── game_config.json # 游戏配置
│ └── zh_CN.json # 中文本地化
│
├── Utils/ # [工具层] 通用辅助脚本
│ └── StringUtils.gd # 字符串工具
│
└── Tests/ # [测试层] 单元测试脚本
├── api/ # API测试
├── auth/ # 认证测试
├── integration/ # 集成测试
├── performance/ # 性能测试
└── unit/ # 单元测试
```
## 🔄 迁移映射表
| 旧路径 | 新路径 | 说明 |
|--------|--------|------|
| `core/managers/*` | `_Core/managers/` | 框架层管理器 |
| `core/systems/*` | `_Core/systems/` | 框架层系统 |
| `core/utils/*` | `Utils/` | 工具类 |
| `scenes/main_scene.tscn` | `Scenes/Maps/main_scene.tscn` | 主游戏场景 |
| `scenes/auth_scene.tscn` | `UI/Windows/LoginWindow.tscn` | 登录窗口 |
| `data/configs/*.json` | `Config/` | 配置文件 |
| `data/localization/*.json` | `Config/` | 本地化配置 |
| `assets/ui/chinese_theme.tres` | `UI/Theme/MainTheme.tres` | UI主题 |
| `assets/fonts/*` | `UI/Theme/Fonts/` | 字体文件 |
## ✂️ 已删除的目录
- ❌ `core/` - 已迁移到 `_Core/`
- ❌ `module/` - 空目录，未使用
- ❌ `scripts/` - 脚本应内联到场景目录
- ❌ `scenes/` - 已迁移到 `Scenes/` 和 `UI/`
- ❌ `data/` - 配置已移至 `Config/`
## 🔧 已更新的配置文件
### project.godot
```ini
# 更新主场景路径
run/main_scene="res://Scenes/Maps/main_scene.tscn"
# 更新自动加载路径
GameManager="*res://_Core/managers/GameManager.gd"
SceneManager="*res://_Core/managers/SceneManager.gd"
EventSystem="*res://_Core/systems/EventSystem.gd"
NetworkManager="*res://_Core/managers/NetworkManager.gd"
ResponseHandler="*res://_Core/managers/ResponseHandler.gd"
```
### SceneManager.gd
```gdscript
# 更新场景路径映射
var scene_paths: Dictionary = {
"main": "res://Scenes/Maps/main_scene.tscn",
"auth": "res://UI/Windows/LoginWindow.tscn",
# ... 其他场景路径
}
```
### 测试文件
- `tests/auth/enhanced_toast_test.gd` - 已更新脚本路径
- `tests/auth/auth_ui_test.tscn` - 已更新场景路径
## 🎨 设计原则
### 1. 清晰的分层
- **_Core**: 框架代码，与具体游戏逻辑无关
- **Scenes**: 游戏世界，地图和实体
- **UI**: 所有界面，HUD和弹窗
- **Config**: 静态数据，策划可编辑
### 2. 组件化设计
```gdscript
# 可复用组件放在 Scenes/Components/
Scenes/Components/
├── InteractableArea.tscn # 让任何物体"可交互"
├── MovementSync.gd # 网络位置同步
└── NameTag3D.tscn # 头顶名字条
```
### 3. 场景内聚
- 每个 .tscn 配套一个 .gd
- 脚本紧邻场景文件存放
- 符合 Godot 原生开发习惯
### 4. 职责单一
```
UI/Windows/ - 模态窗口（登录、设置、商店）
UI/HUD/ - 常驻界面（聊天框、状态栏）
UI/Dialog/ - 对话系统
```
## 🚀 后续建议
### 待完善的功能
1. **组件化开发**
- 创建 `Scenes/Components/` 下的可复用组件
- 使用组合优于继承的设计模式
2. **UI 独立化**
- 补充 `UI/HUD/` 下的常驻界面
- 创建 `UI/Dialog/` 对话系统
3. **场景管理**
- 补充更多地图场景到 `Scenes/Maps/`
- 添加玩家实体到 `Scenes/Entities/Player/`
4. **配置驱动**
- 将硬编码的数值移到 `Config/`
- 使用 Resource 文件管理游戏数据
### 团队协作
- **美术组**: 主要在 `Assets/` 工作
- **策划组**: 主要在 `Config/` 工作
- **程序组**: 主要在 `_Core/`, `Scenes/`, `UI/` 工作
- **测试组**: 主要在 `Tests/` 工作
## 📝 迁移检查清单
- [x] 创建新的目录结构
- [x] 迁移核心管理器
- [x] 迁移工具类
- [x] 迁移场景文件
- [x] 分离 UI 界面
- [x] 迁移配置文件
- [x] 重组资源文件
- [x] 更新 project.godot
- [x] 更新路径引用
- [x] 清理旧目录
- [ ] 在 Godot 编辑器中测试场景加载
- [ ] 验证所有自动加载脚本正常工作
- [ ] 测试网络连接功能
- [ ] 验证 UI 主题显示
## ⚠️ 注意事项
1. **场景引用更新**: 所有旧场景的引用都已更新，但建议在 Godot 编辑器中重新打开项目，让编辑器重新索引文件
2. **.import 文件**: 移动资源文件后，Godot 可能会重新生成 .import 文件，这是正常的
3. **版本控制**: 如果使用 Git，旧文件的删除会在下次提交时体现
4. **测试覆盖**: 迁移后建议运行完整的测试套件确保功能正常
## 🎓 参考资料
- [Godot 官方项目组织建议](https://docs.godotengine.org/en/stable/tutorials/best_practices/project_organization.html)
- [GDScript 场景组织](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_basics.html#scenes-and-scripts)
- [ECS 架构模式](https://github.com/SmitUS/Pine-Tree-ECS-For-Godot-4)
---
**重构完成！项目现在拥有清晰的架构，易于维护和扩展。** 🎉

213
STRUCTURE_COMPARISON.md
View File

@@ -1,213 +0,0 @@
# 🏗️ 项目结构对比
## 旧结构 ❌
```
whale-town-front/
├── core/ # ❌ 概念模糊
│ ├── managers/ # - 框架代码？
│ ├── systems/ # - 还是业务逻辑？
│ └── utils/ # - 边界不清
├── module/ # ❌ 空壳目录（无 .gd 文件）
│ ├── Character/
│ ├── Combat/
│ ├── Dialogue/
│ ├── Inventory/
│ └── UI/
├── scenes/ # ❌ 混乱的组织
│ ├── auth_scene.tscn
│ ├── main_scene.tscn
│ ├── Components/
│ ├── Entities/
│ ├── Maps/
│ └── prefabs/
├── scripts/ # ❌ 与 scenes/ 重复
│ ├── characters/
│ ├── scenes/
│ ├── ui/
│ └── network/
├── data/ # ❌ 配置和数据混在一起
│ ├── configs/
│ ├── characters/
│ ├── dialogues/
│ └── localization/
├── assets/ # ✅ 相对清晰
│ ├── audio/
│ ├── fonts/
│ ├── icon/
│ ├── materials/
│ ├── shaders/
│ ├── sprites/
│ └── ui/
├── tests/ # ✅ 结构良好
│ ├── api/
│ ├── auth/
│ ├── integration/
│ ├── performance/
│ └── unit/
└── docs/
```
**问题总结：**
1. 🔴 脚本分散：`scripts/` 和 `scenes/` 都有脚本，职责不清
2. 🔴 空壳模块：`module/` 目录存在但无实际代码
3. 🔴 场景混乱：场景文件、预制体、脚本平级放置
4. 🔴 分层不明：`core/`, `module/`, `scripts/` 三层交叉
5. 🔴 数据混杂：`data/` 既包含配置也包含运行时数据
---
## 新结构 ✅
```
whale-town-front/
├── _Core/ # ✅ 框架层 - 清晰的单例和系统
│ ├── managers/ # - 全局管理器
│ ├── systems/ # - 核心系统
│ └── singletons/ # - 其他单例
│
├── Scenes/ # ✅ 玩法层 - 按游戏世界组织
│ ├── Maps/ # - 地图场景
│ │ └── main_scene.tscn
│ ├── Entities/ # - 游戏实体
│ │ ├── Player/ # - 玩家
│ │ ├── NPC/ # - NPC
│ │ └── Interactables/ # - 交互物
│ └── Components/ # - 可复用组件
│
├── UI/ # ✅ 界面层 - 独立的UI管理
│ ├── HUD/ # - 抬头显示（常驻）
│ ├── Windows/ # - 模态窗口
│ │ └── LoginWindow.tscn # (原 auth_scene)
│ ├── Dialog/ # - 对话系统
│ └── Theme/ # - 全局样式
│ ├── MainTheme.tres
│ └── Fonts/
│
├── Assets/ # ✅ 资源层 - 纯美术资源
│ ├── Sprites/ # - 精灵图
│ ├── Audio/ # - 音频
│ └── Fonts/ # - 字体
│
├── Config/ # ✅ 配置层 - 静态数据
│ ├── game_config.json
│ └── zh_CN.json
│
├── Utils/ # ✅ 工具层 - 通用函数库
│ └── StringUtils.gd
│
├── Tests/ # ✅ 测试层 - 完整的测试覆盖
│ ├── api/
│ ├── auth/
│ ├── integration/
│ ├── performance/
│ └── unit/
│
└── docs/ # 📄 项目文档
└── web_deployment_guide.md
```
**改进总结：**
1. 🟢 **分层清晰**: 框架、玩法、界面、资源、配置、工具各司其职
2. 🟢 **场景内聚**: .tscn 和 .gd 成对出现，逻辑紧耦合场景
3. 🟢 **UI 独立**: 所有界面统一管理，避免和游戏场景混淆
4. 🟢 **配置分离**: Config 只存放静态数据，策划可直接编辑
5. 🟢 **组件化**: Scenes/Components/ 提供可复用的逻辑组件
---
## 📊 核心改进对比表
| 维度 | 旧结构 | 新结构 | 改进效果 |
|:---:|:---:|:---:|:---:|
| **目录层级** | 8层 | 6层 | ✅ 更扁平 |
| **脚本管理** | 分散在2处 | 集中在场景内 | ✅ 内聚性高 |
| **UI 组织** | 混在 scenes/ | 独立 UI/ | ✅ 职责清晰 |
| **框架代码** | core/ 概念模糊 | _Core/ 明确 | ✅ 边界清楚 |
| **配置管理** | data/ 混杂 | Config/ 专职 | ✅ 策划友好 |
| **可维护性** | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ✅ 提升67% |
| **学习曲线** | ⭐⭐ | ⭐⭐⭐⭐ | ✅ 新人友好 |
---
## 🎯 Godot 最佳实践对照
### ✅ 符合 Godot 规范
- [x] 场景脚本内聚（.tscn + .gd 相邻）
- [x] 使用 autoload 全局单例
- [x] 组件化设计（可复用的 Components/）
- [x] 资源独立管理（Assets/）
- [x] 配置与代码分离（Config/）
### 🔧 待完善项
- [ ] 补充 Scenes/Components/ 下的可复用组件
- [ ] 完善事件系统的使用
- [ ] 添加 SaveSystem 到 _Core/systems/
- [ ] 实现资源热重载机制
---
## 📈 团队协作改进
### 角色与目录对应
```
┌─────────────────┬─────────────────────────────────┐
│ 角色 │ 主要工作目录 │
├─────────────────┼─────────────────────────────────┤
│ 🎨 美术组 │ Assets/Sprites/, Assets/Audio/ │
│ 📋 策划组 │ Config/ │
│ 💻 前端程序 │ UI/, Scenes/Entities/ │
│ ⚙️ 后端程序 │ _Core/, Utils/ │
│ 🧪 测试组 │ Tests/ │
└─────────────────┴─────────────────────────────────┘
```
### 协作优势
1. **减少冲突**: 不同角色在不同目录工作
2. **职责清晰**: 每个目录有明确的负责人
3. **易于审查**: PR 可以按目录分类评审
4. **快速定位**: 新人快速找到相关文件
---
## 🚀 扩展性对比
### 旧结构的扩展问题
```gdscript
// 添加新功能时需要在多个地方修改
module/FeatureName/ // ❌ 需要创建
scenes/feature_scene/ // ❌ 需要创建
scripts/feature_logic/ // ❌ 需要创建
data/feature_config/ // ❌ 需要创建
```
### 新结构的扩展方式
```gdscript
// 添加新功能只需要：
Scenes/Entities/NewFeature/ // ✅ 场景+逻辑一体
Config/feature_config.json // ✅ 配置独立
```
---
## 📚 参考架构
这个新结构参考了业界最佳实践：
- **Godot 官方**: [Project Organization](https://docs.godotengine.org/en/stable/tutorials/best_practices/project_organization.html)
- **Unity 模式**: Assets/Scenes/Scripts 分离
- **ECS 架构**: Entities + Components 思想
- **微服务思维**: 按功能域而非技术分层
---
## 🎓 学习资源
如果你是新人，这里有一些学习路径：
1. **先熟悉目录** → 查看 [REFACTORING.md](./REFACTORING.md)
2. **理解核心系统** → 阅读 `_Core/systems/EventSystem.gd`
3. **学习场景管理** → 查看 `_Core/managers/SceneManager.gd`
4. **研究 UI 结构** → 打开 `UI/Windows/LoginWindow.tscn`
5. **运行测试** → 执行 `Tests/` 下的测试用例
---
**结论：新结构更加清晰、模块化、易于维护，符合 Godot 最佳实践！** 🎉

123
cloude.md
View File

@@ -1,123 +0,0 @@
# 🎯 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提交规范
---
**记住：代码质量是游戏成功的基础！**