forked from moyin/whale-town-front
Merge pull request 'feature/project-structure-refactor' (#7) from feature/project-structure-refactor into main
Reviewed-on: datawhale/whale-town-front#7
This commit is contained in:
@@ -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 编辑器中打开项目并测试！** 🚀
|
||||
78
README.md
78
README.md
@@ -75,6 +75,7 @@ python tests/api/api_client_test.py
|
||||
1. **[📖 项目入门总览](docs/01-项目入门/README.md)** - 5分钟了解项目
|
||||
2. **[🏗️ 项目结构说明](docs/01-项目入门/项目结构说明.md)** - 理解架构设计
|
||||
3. **[⚙️ 项目设置指南](docs/01-项目入门/项目设置指南.md)** - 配置开发环境
|
||||
4. **[🤖 AI开发指南](docs/AI_docs/README.md)** - AI编程助手专用文档
|
||||
|
||||
### 🎯 第二步：学习规范
|
||||
|
||||
@@ -121,34 +122,65 @@ WhaleTown/ # 🐋 项目根目录
|
||||
│ ├── 03-技术实现/ # 🔧 开发指导
|
||||
│ ├── 04-高级开发/ # 🚀 进阶技巧
|
||||
│ ├── 05-部署运维/ # 🌐 发布部署
|
||||
│ └── 06-功能模块/ # 🎮 功能文档
|
||||
├── 🎬 scenes/ # 🎭 游戏场景
|
||||
│ ├── Maps/ # 🗺️ 地图场景
|
||||
│ └── Components/ # 🧩 组件预制体
|
||||
├── 🔧 _Core/ # ⚙️ 核心系统
|
||||
│ ├── managers/ # 🎯 全局管理器
|
||||
│ ├── systems/ # 🔄 系统组件
|
||||
│ ├── 06-功能模块/ # 🎮 功能文档
|
||||
│ └── AI_docs/ # 🤖 AI专用文档（执行规范、代码模板）
|
||||
├── 🔧 _Core/ # ⚙️ 核心底层实现
|
||||
│ ├── managers/ # 🎯 全局管理器（游戏状态、场景、网络等）
|
||||
│ ├── systems/ # 🔄 系统组件（事件系统、输入系统等）
|
||||
│ ├── components/ # 🧩 基础组件实现
|
||||
│ ├── utils/ # <20> 核件心工具类（字符串处理、数学计算等）
|
||||
│ ├── EventNames.gd # 📝 事件名称定义
|
||||
│ └── ProjectPaths.gd # 📂 路径统一管理
|
||||
├── 🎨 UI/ # 🖼️ 用户界面
|
||||
│ └── Windows/ # 🪟 窗口界面
|
||||
├── 🔨 Utils/ # 🔨 工具类
|
||||
├── 🎮 module/ # 🧩 功能模块
|
||||
├── 🎨 assets/ # 🖼️ 游戏资源
|
||||
├── ⚙️ Config/ # 📋 配置文件
|
||||
├── 🧪 tests/ # 🔬 测试文件
|
||||
└── 🌐 web_assets/ # 🌍 Web部署资源
|
||||
│ └── ProjectPaths.gd # <EFBFBD> 路径组统一管理
|
||||
├── 🎬 scenes/ # 🎭 场景与视觉呈现
|
||||
│ ├── maps/ # <EFBFBD>️ 地图一场景（游戏关卡、世界地图）
|
||||
│ ├── characters/ # 👤 人物场景（角色、NPC、敌人）
|
||||
│ ├── ui/ # 🖼️ UI界面场景（菜单、HUD、对话框）
|
||||
│ ├── effects/ # ✨ 特效场景（粒子效果、动画）
|
||||
│ └── prefabs/ # 🧩 预制体组件
|
||||
├── 🎨 assets/ # 🖼️ 静态资源存储
|
||||
│ ├── sprites/ # 🎨 精灵图片（角色、物品、环境）
|
||||
│ ├── audio/ # 🎵 音频资源（音乐、音效）
|
||||
│ ├── fonts/ # 🔤 字体文件
|
||||
│ ├── materials/ # 🎭 材质资源
|
||||
│ ├── shaders/ # 🌈 着色器文件
|
||||
│ ├── ui/ # 🖼️ UI素材（按钮、图标、背景）
|
||||
│ └── icon/ # 📱 应用图标
|
||||
├── ⚙️ Config/ # 📋 配置文件管理
|
||||
│ ├── game_config.json # 🎮 游戏配置（难度、设置等）
|
||||
│ ├── zh_CN.json # 🌐 本地化配置
|
||||
│ └── environment/ # 🔧 环境配置（开发、测试、生产）
|
||||
├── 🧪 tests/ # 🔬 测试文件系统
|
||||
│ ├── unit/ # 🔍 单元测试（组件功能测试）
|
||||
│ ├── integration/ # 🔗 集成测试（系统交互测试）
|
||||
│ ├── performance/ # ⚡ 性能测试（帧率、内存优化）
|
||||
│ └── api/ # 🌐 API接口测试
|
||||
└── 🌐 web_assets/ # 🌍 Web导出资源
|
||||
├── html/ # 📄 HTML模板文件
|
||||
├── css/ # 🎨 样式文件
|
||||
└── js/ # 📜 JavaScript脚本
|
||||
```
|
||||
|
||||
### 🔧 核心组件
|
||||
### 🔧 核心架构说明
|
||||
|
||||
| 组件 | 作用 | 文档链接 |
|
||||
| 目录 | 作用 | 详细说明 |
|
||||
|------|------|----------|
|
||||
| **EventSystem** | 全局事件通信 | [架构规范](docs/02-开发规范/架构与通信规范.md) |
|
||||
| **GameManager** | 游戏状态管理 | [实现细节](docs/03-技术实现/实现细节规范.md) |
|
||||
| **SceneManager** | 场景切换管理 | [场景设计](docs/04-高级开发/场景设计规范.md) |
|
||||
| **NetworkManager** | 网络请求管理 | [网络管理器](docs/03-技术实现/网络管理器设置.md) |
|
||||
| **ProjectPaths** | 路径统一管理 | [项目结构](docs/01-项目入门/项目结构说明.md) |
|
||||
| **_Core** | 🔧 功能实现与组件实现 | 项目最基本的底层实现，包含所有核心系统和基础组件 |
|
||||
| **scenes** | 🎭 场景与视觉呈现 | 包含地图场景、人物场景等一系列视觉呈现部分，主要是UI的实现 |
|
||||
| **assets** | 🎨 静态资源存储 | 所有静态资源的存储，包括图片、音乐、视频、贴图等素材 |
|
||||
| **Config** | ⚙️ 配置文件管理 | 主要用来配置各类环境，包括游戏设置、本地化等配置 |
|
||||
| **tests** | 🧪 测试文件系统 | 放置所有对应组件的测试代码，方便快速进行功能性与性能测试 |
|
||||
| **web_assets** | 🌐 Web导出资源 | 专门用于Web平台导出的相关资源和配置文件 |
|
||||
| **docs/AI_docs** | 🤖 AI专用文档 | 专门为AI编程助手准备的执行规范和代码模板，提升vibe coding效率 |
|
||||
|
||||
### 🎮 核心组件
|
||||
|
||||
| 组件 | 位置 | 作用 | 文档链接 |
|
||||
|------|------|------|----------|
|
||||
| **EventSystem** | _Core/systems/ | 全局事件通信系统 | [架构规范](docs/02-开发规范/架构与通信规范.md) |
|
||||
| **GameManager** | _Core/managers/ | 游戏状态管理器 | [实现细节](docs/03-技术实现/实现细节规范.md) |
|
||||
| **SceneManager** | _Core/managers/ | 场景切换管理器 | [场景设计](docs/04-高级开发/场景设计规范.md) |
|
||||
| **NetworkManager** | _Core/managers/ | 网络请求管理器 | [网络管理器](docs/03-技术实现/网络管理器设置.md) |
|
||||
| **ProjectPaths** | _Core/ | 路径统一管理工具 | [项目结构](docs/01-项目入门/项目结构说明.md) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
222
REFACTORING.md
222
REFACTORING.md
@@ -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)
|
||||
|
||||
---
|
||||
|
||||
**重构完成！项目现在拥有清晰的架构，易于维护和扩展。** 🎉
|
||||
@@ -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 最佳实践！** 🎉
|
||||
@@ -1 +0,0 @@
|
||||
uid://bs1vy3ierj66t
|
||||
@@ -1 +0,0 @@
|
||||
uid://csxag1y8yq57j
|
||||
@@ -31,8 +31,8 @@ const SCENES_ITEM_COMPONENTS = SCENES_COMPONENTS + "items/"
|
||||
# ============================================================================
|
||||
# UI路径
|
||||
# ============================================================================
|
||||
const UI_ROOT = "res://UI/"
|
||||
const UI_WINDOWS = UI_ROOT + "Windows/"
|
||||
const UI_ROOT = "res://scenes/ui/"
|
||||
const UI_WINDOWS = UI_ROOT
|
||||
|
||||
# ============================================================================
|
||||
# 资源路径
|
||||
@@ -69,7 +69,7 @@ const TESTS_AUTH = TESTS_ROOT + "auth/"
|
||||
# ============================================================================
|
||||
# 工具路径
|
||||
# ============================================================================
|
||||
const UTILS_ROOT = "res://Utils/"
|
||||
const UTILS_ROOT = "res://_Core/utils/"
|
||||
|
||||
# ============================================================================
|
||||
# 模块路径
|
||||
|
||||
2
_Core/components/.gitkeep
Normal file
2
_Core/components/.gitkeep
Normal file
@@ -0,0 +1,2 @@
|
||||
# 基础组件实现目录
|
||||
# 存放项目的基础组件类
|
||||
@@ -11,13 +11,13 @@ var is_changing_scene: bool = false
|
||||
|
||||
# 场景路径映射
|
||||
var scene_paths: Dictionary = {
|
||||
"main": "res://Scenes/Maps/main_scene.tscn",
|
||||
"auth": "res://UI/Windows/LoginWindow.tscn",
|
||||
"game": "res://Scenes/Maps/game_scene.tscn",
|
||||
"battle": "res://Scenes/Maps/battle_scene.tscn",
|
||||
"inventory": "res://UI/Windows/InventoryWindow.tscn",
|
||||
"shop": "res://UI/Windows/ShopWindow.tscn",
|
||||
"settings": "res://UI/Windows/SettingsWindow.tscn"
|
||||
"main": "res://scenes/maps/main_scene.tscn",
|
||||
"auth": "res://scenes/ui/LoginWindow.tscn",
|
||||
"game": "res://scenes/maps/game_scene.tscn",
|
||||
"battle": "res://scenes/maps/battle_scene.tscn",
|
||||
"inventory": "res://scenes/ui/InventoryWindow.tscn",
|
||||
"shop": "res://scenes/ui/ShopWindow.tscn",
|
||||
"settings": "res://scenes/ui/SettingsWindow.tscn"
|
||||
}
|
||||
|
||||
func _ready():
|
||||
|
||||
2
_Core/utils/.gitkeep
Normal file
2
_Core/utils/.gitkeep
Normal file
@@ -0,0 +1,2 @@
|
||||
# 核心工具类目录
|
||||
# 存放字符串处理、数学计算等工具类
|
||||
@@ -196,4 +196,4 @@ static func get_relative_time_until(utc_time_str: String) -> String:
|
||||
if minutes > 0:
|
||||
return "%d小时%d分钟后" % [hours, minutes]
|
||||
else:
|
||||
return "%d小时后" % hours
|
||||
return "%d小时后" % hours
|
||||
1
_Core/utils/StringUtils.gd.uid
Normal file
1
_Core/utils/StringUtils.gd.uid
Normal file
@@ -0,0 +1 @@
|
||||
uid://bu8onmk6q8wic
|
||||
96
claude.md
Normal file
96
claude.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# 🎯 CLAUDE.md - WhaleTown Project Instructions
|
||||
|
||||
## 1. Project Vision & Context
|
||||
- **Project**: "WhaleTown" - A 2D top-down pixel art RPG.
|
||||
- **Engine**: Godot 4.2+ (Strictly NO Godot 3.x syntax).
|
||||
- **Architecture**: Strictly layered: `_Core` (Framework), `Scenes` (Gameplay), `UI` (Interface).
|
||||
- **Core Principle**: "Signal Up, Call Down". High decoupling via `EventSystem`.
|
||||
|
||||
## 2. 🛠 Command Reference & Setup
|
||||
- **Input Map (Required Configuration)**:
|
||||
- `move_left`, `move_right`, `move_up`, `move_down` (WASD / Arrows)
|
||||
- `interact` (E Key / Space)
|
||||
- `pause` (ESC)
|
||||
- **Run Game**: `godot --path .`
|
||||
- **Run Tests (GUT)**: `godot --headless -s addons/gut/gut_cmdline.gd -gdir=res://tests/ -ginclude_subdirs`
|
||||
- **Init Structure**: `mkdir -p _Core/managers _Core/systems Scenes/Maps Scenes/Entities Scenes/Components UI/Windows UI/HUD Assets/Sprites tests/unit tests/integration`
|
||||
|
||||
## 3. 📂 File Path Rules (STRICT LOWERCASE)
|
||||
*Claude: Root folders MUST be lowercase. Scripts and Scenes MUST stay together.*
|
||||
- **Core Managers**: `_Core/managers/[Name].gd`
|
||||
- **Core Systems**: `_Core/systems/[Name].gd`
|
||||
- **Entities**: `Scenes/Entities/[EntityName]/[EntityName].tscn` (Script `.gd` in same folder).
|
||||
- **Maps**: `Scenes/Maps/[map_name].tscn`
|
||||
- **Components**: `Scenes/Components/[ComponentName].gd` (Reusable logic nodes).
|
||||
- **UI Windows**: `UI/Windows/[WindowName].tscn`
|
||||
- **Tests**: `tests/[unit|integration]/test_[name].gd` (Folder is lowercase `tests`).
|
||||
|
||||
## 4. 📋 Coding Standards (The Law)
|
||||
- **Type Safety**: ALWAYS use strict static typing: `var speed: float = 100.0`, `func _ready() -> void`.
|
||||
- **Naming Conventions**:
|
||||
- `class_name PascalCase` at the top of every script.
|
||||
- Variables/Functions: `snake_case`. Constants: `SCREAMING_SNAKE_CASE`.
|
||||
- Private members: Prefix with underscore `_` (e.g., `var _health: int`).
|
||||
- **Node Access**: Use `%UniqueName` for UI and internal scene components.
|
||||
- **Signals**: Use "Signal Up, Call Down". Parent calls child methods; Child emits signals.
|
||||
- **Forbidden Patterns**:
|
||||
- ❌ NO `yield()` -> Use `await`.
|
||||
- ❌ NO `get_node()` in `_process` -> Cache with `@onready`.
|
||||
- ❌ NO Linear Filter -> All Sprite2D/TileMap resources MUST use **Nearest** filter.
|
||||
|
||||
## 5. 🏛 Architecture & Communication
|
||||
- **EventSystem**: Use `_Core/systems/EventSystem.gd` for cross-module messaging.
|
||||
- **Event Registry**: Use `class_name EventNames` in `_Core/EventNames.gd`.
|
||||
```gdscript
|
||||
class_name EventNames
|
||||
const PLAYER_MOVED = "player_moved"
|
||||
const INTERACT_PRESSED = "interact_pressed"
|
||||
const NPC_TALKED = "npc_talked"
|
||||
Singletons: Only GameManager, SceneManager, EventSystem allowed as Autoloads.
|
||||
Decoupling: Low-level entities MUST NOT reference GameManager. Use events.
|
||||
6. 🏗 Implementation Details
|
||||
Player: CharacterBody2D. Must include Camera2D with position_smoothing_enabled = true.
|
||||
NPC/Interactables: Use Area2D named InteractionArea. Trigger via EventSystem.
|
||||
TileMap Layers:
|
||||
Layer 0: Ground (No collision).
|
||||
Layer 1: Obstacles (Physics Layer enabled).
|
||||
Layer 2: Decoration (Y-Sort enabled).
|
||||
Camera: Must auto-calculate limits via TileMap.get_used_rect().
|
||||
7. 🧪 Testing Requirements (MANDATORY)
|
||||
Coverage: Every Manager/System in _Core/ MUST have a GUT test.
|
||||
Naming: Test files must start with test_ and extend GutTest.
|
||||
Example:
|
||||
code
|
||||
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. 🧘 The Zen of Development
|
||||
Juice or Death: Every interaction (UI popup, NPC talk) MUST have a Tween placeholder.
|
||||
Zero Magic Numbers: All speeds/timers MUST be @export or defined in Config/.
|
||||
Simplicity: If a function does two things, split it.
|
||||
Back of the Fence: Hidden logic (like ResponseHandler.gd) must be as clean as the HUD.
|
||||
9. 📝 Code Template (Entity Pattern)
|
||||
code
|
||||
Gdscript
|
||||
extends CharacterBody2D
|
||||
class_name Player
|
||||
|
||||
# 1. Exports & Constants
|
||||
@export var move_speed: float = 200.0
|
||||
|
||||
# 2. Node References
|
||||
@onready var sprite: Sprite2D = %Sprite2D
|
||||
|
||||
# 3. Lifecycle
|
||||
func _physics_process(delta: float) -> void:
|
||||
_move(delta)
|
||||
|
||||
# 4. Private Methods
|
||||
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()
|
||||
123
cloude.md
123
cloude.md
@@ -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提交规范
|
||||
|
||||
---
|
||||
|
||||
**记住：代码质量是游戏成功的基础！**
|
||||
@@ -20,15 +20,12 @@
|
||||
|
||||
```
|
||||
WhaleTown/
|
||||
├── 🔧 _Core/ # [框架层] 核心系统和管理器
|
||||
├── 🎬 scenes/ # [游戏层] 游戏场景和组件
|
||||
├── 🎨 UI/ # [界面层] 用户界面
|
||||
├── 🖼️ assets/ # [资源层] 美术资源
|
||||
├── ⚙️ Config/ # [配置层] 游戏配置和数据
|
||||
├── 🛠️ Utils/ # [工具层] 通用工具脚本
|
||||
├── 🧪 tests/ # [测试层] 测试文件
|
||||
├── 🚀 tools/ # [构建层] 构建和部署工具
|
||||
├── 🌐 web_assets/ # [发布层] Web版本资源
|
||||
├── 🔧 _Core/ # [核心层] 功能实现与组件实现，项目最基本的底层实现
|
||||
├── 🎬 scenes/ # [场景层] 场景与视觉呈现，包含地图、人物等视觉部分
|
||||
├── 🎨 assets/ # [资源层] 静态资源存储，包括图片、音乐、视频、贴图等
|
||||
├── ⚙️ Config/ # [配置层] 配置文件管理，用于配置各类环境
|
||||
├── 🧪 tests/ # [测试层] 测试文件系统，放置所有组件的测试代码
|
||||
├── 🌐 web_assets/ # [发布层] Web导出资源，专门用于Web平台导出
|
||||
└── 📚 docs/ # [文档层] 项目文档
|
||||
```
|
||||
|
||||
@@ -36,9 +33,9 @@ WhaleTown/
|
||||
|
||||
## 📁 详细目录结构
|
||||
|
||||
### 1. 🔧 框架层 (_Core/)
|
||||
### 1. 🔧 核心层 (_Core/)
|
||||
> **负责团队**: 开发团队
|
||||
> **职责**: 游戏底层框架，全局管理器和核心系统
|
||||
> **职责**: 功能实现与组件实现，项目最基本的底层实现
|
||||
|
||||
```
|
||||
_Core/
|
||||
@@ -47,15 +44,25 @@ _Core/
|
||||
│ ├── SceneManager.gd # 场景切换管理
|
||||
│ ├── NetworkManager.gd # 网络通信管理
|
||||
│ └── ResponseHandler.gd # API响应处理
|
||||
└── systems/ # 核心系统
|
||||
└── EventSystem.gd # 全局事件系统
|
||||
├── systems/ # 核心系统
|
||||
│ └── EventSystem.gd # 全局事件系统
|
||||
├── components/ # 基础组件实现
|
||||
│ ├── BaseCharacter.gd # 基础角色组件
|
||||
│ ├── BaseItem.gd # 基础物品组件
|
||||
│ └── BaseUI.gd # 基础UI组件
|
||||
├── utils/ # 🔨 核心工具类
|
||||
│ ├── StringUtils.gd # 字符串处理工具
|
||||
│ ├── MathUtils.gd # 数学计算工具
|
||||
│ └── PixelUtils.gd # 像素风游戏专用工具
|
||||
├── EventNames.gd # 事件名称定义
|
||||
└── ProjectPaths.gd # 路径统一管理
|
||||
```
|
||||
|
||||
**特点**:
|
||||
- 自动加载 (AutoLoad) 单例
|
||||
- 全局可访问
|
||||
- 与具体游戏逻辑无关
|
||||
- 提供基础服务
|
||||
- 全局可访问的核心功能
|
||||
- 与具体游戏逻辑无关的底层实现
|
||||
- 提供基础服务和组件框架
|
||||
|
||||
**使用示例**:
|
||||
```gdscript
|
||||
@@ -69,167 +76,206 @@ SceneManager.change_scene("main")
|
||||
EventSystem.emit_event("player_moved", {"position": Vector2(100, 200)})
|
||||
```
|
||||
|
||||
### 2. 🎬 游戏层 (scenes/)
|
||||
### 2. 🎬 场景层 (scenes/)
|
||||
> **负责团队**: 开发团队
|
||||
> **职责**: 游戏场景、实体和可复用组件
|
||||
> **职责**: 场景与视觉呈现，包含地图场景、人物场景等一系列视觉呈现的部分
|
||||
|
||||
```
|
||||
scenes/
|
||||
├── Maps/ # 游戏地图场景
|
||||
│ ├── main_scene.tscn # 主游戏场景
|
||||
│ └── MainScene.gd # 主场景脚本
|
||||
└── Components/ # 可复用组件
|
||||
├── characters/ # 角色组件
|
||||
├── effects/ # 特效组件
|
||||
├── items/ # 物品组件
|
||||
└── ui/ # UI组件
|
||||
├── maps/ # 地图场景
|
||||
│ ├── main_world.tscn # 主世界地图
|
||||
│ ├── dungeon_01.tscn # 地牢场景
|
||||
│ └── town_center.tscn # 城镇中心
|
||||
├── characters/ # 人物场景
|
||||
│ ├── player/ # 玩家角色
|
||||
│ │ ├── Player.tscn # 玩家场景
|
||||
│ │ └── Player.gd # 玩家脚本
|
||||
│ ├── npcs/ # NPC角色
|
||||
│ └── enemies/ # 敌人角色
|
||||
├── ui/ # UI界面场景
|
||||
│ ├── menus/ # 菜单界面
|
||||
│ ├── hud/ # 游戏HUD
|
||||
│ └── dialogs/ # 对话框
|
||||
├── effects/ # 特效场景
|
||||
│ ├── particles/ # 粒子效果
|
||||
│ └── animations/ # 动画效果
|
||||
└── prefabs/ # 预制体组件
|
||||
├── items/ # 物品预制体
|
||||
└── interactive/ # 交互对象预制体
|
||||
```
|
||||
|
||||
**设计原则**:
|
||||
- **场景内聚**: 脚本紧邻场景文件存放
|
||||
- **组件化**: 可复用组件统一管理
|
||||
- **模块化**: 按功能类型分类组织
|
||||
- **分类明确**: 按功能类型（地图、人物、UI、特效）分类
|
||||
- **模块化**: 可复用的预制体统一管理
|
||||
- **视觉导向**: 主要负责游戏的视觉呈现和UI实现
|
||||
|
||||
### 3. 🎨 界面层 (UI/)
|
||||
> **负责团队**: 开发团队 + 美术团队协作
|
||||
> **职责**: 用户界面和主题管理
|
||||
|
||||
```
|
||||
UI/
|
||||
├── Windows/ # 模态窗口
|
||||
│ ├── LoginWindow.tscn # 登录窗口
|
||||
│ └── AuthScene.gd # 认证场景脚本
|
||||
└── Theme/ # 全局主题
|
||||
├── MainTheme.tres # 主题资源
|
||||
└── Fonts/ # 字体文件
|
||||
└── msyh.ttc # 微软雅黑字体
|
||||
```
|
||||
|
||||
**组织方式**:
|
||||
- **Windows/**: 模态窗口和对话框
|
||||
- **Theme/**: 统一的UI主题和样式
|
||||
- **Fonts/**: 字体资源管理
|
||||
|
||||
### 4. 🖼️ 资源层 (assets/)
|
||||
### 3. 🎨 资源层 (assets/)
|
||||
> **负责团队**: 美术团队
|
||||
> **职责**: 所有美术资源和素材
|
||||
> **职责**: 所有静态资源的存储，包括图片、音乐、视频、贴图等素材
|
||||
|
||||
```
|
||||
assets/
|
||||
├── sprites/ # 精灵图资源
|
||||
│ ├── characters/ # 角色精灵
|
||||
│ ├── effects/ # 特效精灵
|
||||
│ ├── environment/ # 环境精灵
|
||||
│ └── icon/ # 图标资源
|
||||
├── sprites/ # 精灵图片资源
|
||||
│ ├── characters/ # 角色精灵（玩家、NPC、敌人）
|
||||
│ ├── environment/ # 环境精灵（地形、建筑、装饰）
|
||||
│ ├── items/ # 物品精灵（道具、装备、收集品）
|
||||
│ ├── effects/ # 特效精灵（爆炸、魔法、粒子）
|
||||
│ └── ui/ # UI精灵（按钮、图标、边框）
|
||||
├── audio/ # 音频资源
|
||||
│ ├── music/ # 背景音乐
|
||||
│ ├── sounds/ # 音效
|
||||
│ └── voice/ # 语音
|
||||
├── ui/ # UI专用资源
|
||||
│ ├── auth/ # 认证界面资源
|
||||
│ │ ├── bg_auth_scene.png # 认证背景
|
||||
│ │ └── login_frame_smart_transparent.png
|
||||
│ ├── chinese_theme.tres # 中文主题
|
||||
│ └── datawhale_logo.png # 项目Logo
|
||||
│ ├── music/ # 背景音乐（BGM）
|
||||
│ ├── sounds/ # 音效（SFX）
|
||||
│ └── voice/ # 语音（对话、旁白）
|
||||
├── fonts/ # 字体文件
|
||||
│ ├── pixel_fonts/ # 像素风字体
|
||||
│ └── ui_fonts/ # UI专用字体
|
||||
├── materials/ # 材质资源
|
||||
└── shaders/ # 着色器
|
||||
│ ├── pixel_materials/ # 像素风材质
|
||||
│ └── shader_materials/ # 着色器材质
|
||||
├── shaders/ # 着色器文件
|
||||
│ ├── pixel_shaders/ # 像素风着色器
|
||||
│ └── effect_shaders/ # 特效着色器
|
||||
├── ui/ # UI专用资源
|
||||
│ ├── themes/ # UI主题
|
||||
│ ├── icons/ # 图标资源
|
||||
│ └── backgrounds/ # 背景图片
|
||||
└── icon/ # 应用图标
|
||||
├── icon.svg # 矢量图标
|
||||
└── icon.png # 位图图标
|
||||
```
|
||||
|
||||
**美术团队工作流程**:
|
||||
1. 按分类将资源放入对应目录
|
||||
2. 遵循命名规范 (snake_case)
|
||||
3. 确保资源格式符合Godot要求
|
||||
4. 配置正确的导入设置 (像素艺术使用最近邻过滤)
|
||||
**像素风游戏资源特点**:
|
||||
- **像素完美**: 所有精灵使用像素完美设置（Filter: Off, Mipmaps: Off）
|
||||
- **统一风格**: 保持一致的像素密度和调色板
|
||||
- **分辨率标准**: 建议使用16x16、32x32等标准像素尺寸
|
||||
- **动画帧**: 角色动画使用精灵表（Sprite Sheet）组织
|
||||
|
||||
### 5. ⚙️ 配置层 (Config/)
|
||||
### 4. ⚙️ 配置层 (Config/)
|
||||
> **负责团队**: 策划团队
|
||||
> **职责**: 游戏配置、数据和本地化
|
||||
> **职责**: 配置文件管理，主要用来配置各类环境
|
||||
|
||||
```
|
||||
Config/
|
||||
├── game_config.json # 游戏主配置
|
||||
└── zh_CN.json # 中文本地化
|
||||
├── zh_CN.json # 中文本地化
|
||||
├── environment/ # 环境配置
|
||||
│ ├── development.json # 开发环境配置
|
||||
│ ├── testing.json # 测试环境配置
|
||||
│ └── production.json # 生产环境配置
|
||||
├── gameplay/ # 游戏玩法配置
|
||||
│ ├── character_stats.json # 角色属性配置
|
||||
│ ├── item_database.json # 物品数据库
|
||||
│ └── level_config.json # 关卡配置
|
||||
└── localization/ # 本地化配置
|
||||
├── en_US.json # 英文本地化
|
||||
├── zh_CN.json # 中文本地化
|
||||
└── ja_JP.json # 日文本地化
|
||||
```
|
||||
|
||||
**策划团队工作内容**:
|
||||
- **游戏数值配置**: 角色属性、物品数据、关卡参数
|
||||
- **本地化文本**: 多语言文本翻译和管理
|
||||
- **游戏平衡**: 数值平衡和游戏性调整
|
||||
**配置文件特点**:
|
||||
- **环境分离**: 开发、测试、生产环境配置分离
|
||||
- **数据驱动**: 游戏数值通过配置文件控制
|
||||
- **本地化支持**: 多语言文本管理
|
||||
- **热更新**: 支持运行时配置更新
|
||||
|
||||
**配置文件示例**:
|
||||
```json
|
||||
// game_config.json
|
||||
{
|
||||
"player": {
|
||||
"move_speed": 200.0,
|
||||
"max_health": 100,
|
||||
"jump_height": 400.0
|
||||
},
|
||||
"game": {
|
||||
"target_fps": 60,
|
||||
"auto_save_interval": 300
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 6. 🛠️ 工具层 (Utils/)
|
||||
### 5. 🧪 测试层 (tests/)
|
||||
> **负责团队**: 开发团队
|
||||
> **职责**: 通用工具和辅助脚本
|
||||
|
||||
```
|
||||
Utils/
|
||||
└── StringUtils.gd # 字符串处理工具
|
||||
```
|
||||
|
||||
**特点**:
|
||||
- 纯函数，无依赖
|
||||
- 可被任何层调用
|
||||
- 提供通用功能
|
||||
|
||||
### 7. 🧪 测试层 (tests/)
|
||||
> **负责团队**: 开发团队
|
||||
> **职责**: 质量保证和自动化测试
|
||||
> **职责**: 测试文件系统，放置所有对应组件的测试代码，方便快速进行功能性与性能测试
|
||||
|
||||
```
|
||||
tests/
|
||||
├── api/ # API接口测试
|
||||
├── auth/ # 认证功能测试
|
||||
├── unit/ # 单元测试
|
||||
│ ├── core/ # 核心组件测试
|
||||
│ ├── characters/ # 角色组件测试
|
||||
│ └── systems/ # 系统功能测试
|
||||
├── integration/ # 集成测试
|
||||
└── performance/ # 性能测试
|
||||
│ ├── scene_transitions/ # 场景切换测试
|
||||
│ ├── save_load/ # 存档系统测试
|
||||
│ └── network/ # 网络功能测试
|
||||
├── performance/ # 性能测试
|
||||
│ ├── framerate/ # 帧率测试
|
||||
│ ├── memory/ # 内存使用测试
|
||||
│ └── loading_times/ # 加载时间测试
|
||||
├── api/ # API接口测试
|
||||
│ ├── auth_tests.py # 认证接口测试
|
||||
│ └── game_api_tests.py # 游戏API测试
|
||||
└── ui/ # UI功能测试
|
||||
├── menu_tests/ # 菜单测试
|
||||
└── dialog_tests/ # 对话框测试
|
||||
```
|
||||
|
||||
### 8. 🚀 构建层 (tools/)
|
||||
> **负责团队**: 开发团队/DevOps
|
||||
> **职责**: 构建脚本和部署工具
|
||||
**测试类型说明**:
|
||||
- **单元测试**: 测试单个组件的功能正确性
|
||||
- **集成测试**: 测试组件间的交互和协作
|
||||
- **性能测试**: 监控游戏性能指标，确保流畅运行
|
||||
- **API测试**: 验证网络接口的正确性和稳定性
|
||||
- **UI测试**: 测试用户界面的交互和响应
|
||||
|
||||
```
|
||||
tools/
|
||||
├── build_web.bat # Windows Web构建脚本
|
||||
├── build_web.sh # Linux/macOS Web构建脚本
|
||||
├── serve_web.bat # Windows 本地服务器
|
||||
├── serve_web.sh # Linux/macOS 本地服务器
|
||||
└── README.md # 工具使用说明
|
||||
```
|
||||
|
||||
### 9. 🌐 发布层 (web_assets/)
|
||||
### 6. 🌐 Web导出层 (web_assets/)
|
||||
> **负责团队**: 自动生成
|
||||
> **职责**: Web版本发布资源
|
||||
> **职责**: Web导出资源，专门用于Web平台导出的相关资源和配置文件
|
||||
|
||||
```
|
||||
web_assets/
|
||||
├── index.html # Web版本入口
|
||||
├── index.js # Godot Web导出JS
|
||||
├── index.wasm # WebAssembly文件
|
||||
├── index.pck # 游戏资源包
|
||||
└── [其他Web资源] # 图标、配置等
|
||||
├── html/ # HTML模板文件
|
||||
│ ├── index.html # Web版本入口页面
|
||||
│ └── loading.html # 加载页面模板
|
||||
├── css/ # 样式文件
|
||||
│ ├── game.css # 游戏样式
|
||||
│ └── loading.css # 加载样式
|
||||
├── js/ # JavaScript脚本
|
||||
│ ├── game_loader.js # 游戏加载器
|
||||
│ └── utils.js # 工具函数
|
||||
├── icons/ # Web应用图标
|
||||
│ ├── favicon.ico # 网站图标
|
||||
│ └── app_icons/ # PWA应用图标
|
||||
└── config/ # Web配置文件
|
||||
├── manifest.json # PWA清单文件
|
||||
└── service-worker.js # 服务工作者
|
||||
```
|
||||
|
||||
### 10. 📚 文档层 (docs/)
|
||||
**Web导出特点**:
|
||||
- **PWA支持**: 支持渐进式Web应用功能
|
||||
- **响应式设计**: 适配不同屏幕尺寸
|
||||
- **加载优化**: 优化资源加载和缓存策略
|
||||
- **跨平台兼容**: 确保在各种浏览器中正常运行
|
||||
|
||||
### 7. 📚 文档层 (docs/)
|
||||
> **负责团队**: 全体团队
|
||||
> **职责**: 项目文档和开发指南
|
||||
|
||||
```
|
||||
docs/
|
||||
├── 01-项目入门/ # 新人必读文档
|
||||
├── 02-开发规范/ # 编码标准文档
|
||||
├── 03-技术实现/ # 开发指导文档
|
||||
├── 04-高级开发/ # 进阶技巧文档
|
||||
├── 05-部署运维/ # 发布部署文档
|
||||
├── 06-功能模块/ # 功能文档
|
||||
└── AI_docs/ # 🤖 AI专用文档
|
||||
├── README.md # AI文档总览
|
||||
├── architecture_guide.md # 架构执行指南
|
||||
├── coding_standards.md # 代码风格规范
|
||||
├── templates/ # 代码模板库
|
||||
│ ├── components.md # 组件模板集合
|
||||
│ ├── managers.md # 管理器模板集合
|
||||
│ └── ui_templates.md # UI模板集合
|
||||
├── workflows/ # 工作流程指南
|
||||
│ ├── feature_development.md # 功能开发流程
|
||||
│ ├── bug_fixing.md # Bug修复流程
|
||||
│ └── testing_workflow.md # 测试执行流程
|
||||
└── quick_reference/ # 快速参考手册
|
||||
├── code_snippets.md # 常用代码片段
|
||||
├── api_reference.md # API快速参考
|
||||
└── troubleshooting.md # 故障排除指南
|
||||
```
|
||||
|
||||
**AI_docs特点**:
|
||||
- **结构化执行**: 每个文档都包含可直接执行的步骤和代码模板
|
||||
- **标准化规范**: 为AI编程助手提供统一的开发标准和最佳实践
|
||||
- **模板驱动**: 提供完整的代码模板，确保代码一致性和质量
|
||||
- **工作流导向**: 包含详细的开发工作流程，提升AI协作效率
|
||||
|
||||
```
|
||||
docs/
|
||||
├── 01-项目入门/ # 新人必读
|
||||
@@ -245,18 +291,18 @@ docs/
|
||||
## 🤝 团队协作指南
|
||||
|
||||
### 开发团队 🎮
|
||||
**主要工作区域**: `_Core/`, `scenes/`, `UI/`, `Utils/`, `tests/`
|
||||
**主要工作区域**: `_Core/`, `scenes/`, `tests/`
|
||||
|
||||
**日常工作流程**:
|
||||
1. 在 `_Core/` 中开发核心系统和管理器
|
||||
2. 在 `scenes/` 中创建游戏场景和组件
|
||||
3. 在 `UI/` 中实现用户界面
|
||||
4. 在 `Utils/` 中编写通用工具
|
||||
5. 在 `tests/` 中编写测试用例
|
||||
1. 在 `_Core/` 中开发核心系统、管理器、基础组件和工具类
|
||||
2. 在 `scenes/` 中创建游戏场景、角色、UI界面和特效
|
||||
3. 在 `tests/` 中编写各类测试用例确保代码质量
|
||||
|
||||
**协作要点**:
|
||||
- 遵循架构设计原则，使用事件系统通信
|
||||
- 遵循架构设计原则，使用事件系统进行模块通信
|
||||
- 保持代码模块化和可复用性
|
||||
- 将通用工具类放在 `_Core/utils/` 中统一管理
|
||||
- 针对像素风游戏特点优化性能
|
||||
- 及时编写测试和文档
|
||||
|
||||
### 美术团队 🎨
|
||||
@@ -264,28 +310,30 @@ docs/
|
||||
|
||||
**日常工作流程**:
|
||||
1. 按分类整理美术资源到 `assets/` 对应目录
|
||||
2. 遵循命名规范，使用 snake_case 命名
|
||||
3. 配置正确的Godot导入设置
|
||||
4. 与开发团队协作调整UI资源
|
||||
2. 确保像素艺术风格的一致性和像素完美
|
||||
3. 配置正确的Godot导入设置（关闭过滤、禁用Mipmaps）
|
||||
4. 与开发团队协作调整UI和游戏资源
|
||||
|
||||
**协作要点**:
|
||||
- 严格按照目录结构组织资源
|
||||
- 确保资源格式和质量符合要求
|
||||
- 及时与开发团队沟通资源需求
|
||||
**像素风游戏特殊要求**:
|
||||
- 严格遵循像素完美原则
|
||||
- 保持统一的像素密度和调色板
|
||||
- 使用标准像素尺寸（16x16、32x32等）
|
||||
- 精灵动画使用精灵表组织
|
||||
|
||||
### 策划团队 📋
|
||||
**主要工作区域**: `Config/`
|
||||
|
||||
**日常工作流程**:
|
||||
1. 在 `Config/` 中维护游戏配置文件
|
||||
2. 管理游戏数值和平衡性调整
|
||||
1. 在 `Config/` 中维护游戏配置和数值平衡
|
||||
2. 管理多环境配置（开发、测试、生产）
|
||||
3. 负责本地化文本的翻译和维护
|
||||
4. 与开发团队协作实现游戏功能
|
||||
4. 设计游戏玩法和关卡数据
|
||||
|
||||
**协作要点**:
|
||||
- 使用JSON格式编写配置文件
|
||||
- 保持配置文件的结构清晰
|
||||
- 保持配置文件的结构清晰和可维护性
|
||||
- 及时更新本地化文本
|
||||
- 与开发团队协作实现数据驱动的游戏功能
|
||||
|
||||
---
|
||||
|
||||
@@ -320,15 +368,24 @@ docs/
|
||||
### 资源管理规范
|
||||
- 所有资源必须放在 `assets/` 对应分类目录下
|
||||
- 使用描述性的文件名，避免使用数字编号
|
||||
- 像素艺术资源必须关闭过滤 (Filter: Off)
|
||||
- **像素艺术资源必须关闭过滤** (Filter: Off, Mipmaps: Off)
|
||||
- 保持统一的像素密度和调色板
|
||||
- 使用标准像素尺寸（16x16、32x32、64x64等）
|
||||
- 及时清理不使用的资源文件
|
||||
|
||||
### 代码组织规范
|
||||
- 脚本文件与场景文件放在同一目录
|
||||
- 使用事件系统实现模块间通信
|
||||
- 使用事件系统实现模块间通信，避免直接引用
|
||||
- 保持单一职责原则，避免过度耦合
|
||||
- 针对像素风游戏优化性能（避免浮点数位置、使用整数坐标）
|
||||
- 及时编写注释和文档
|
||||
|
||||
### 像素风游戏特殊规范
|
||||
- **像素完美**: 确保所有精灵在整数坐标上渲染
|
||||
- **统一风格**: 保持一致的像素密度和艺术风格
|
||||
- **性能优化**: 使用对象池管理频繁创建销毁的对象
|
||||
- **分辨率适配**: 使用像素完美的缩放方式适配不同分辨率
|
||||
|
||||
---
|
||||
|
||||
**记住：良好的项目结构是团队协作成功的基础！**
|
||||
0
docs/AI_docs/.gitkeep
Normal file
0
docs/AI_docs/.gitkeep
Normal file
238
docs/AI_docs/quick_reference/troubleshooting.md
Normal file
238
docs/AI_docs/quick_reference/troubleshooting.md
Normal file
@@ -0,0 +1,238 @@
|
||||
# 🔧 故障排除指南
|
||||
|
||||
> AI编程助手专用：常见问题的快速解决方案
|
||||
|
||||
## 🚨 常见错误及解决方案
|
||||
|
||||
### 1. UID无效警告
|
||||
|
||||
**错误信息**:
|
||||
```
|
||||
WARNING: scene/resources/resource_format_text.cpp:444 - res://path/to/file.tscn:X - ext_resource, invalid UID: uid://xxxxx - using text path instead: res://path/to/script.gd
|
||||
```
|
||||
|
||||
**原因**: 文件移动后，Godot的UID缓存没有更新，导致UID引用失效。
|
||||
|
||||
**解决方案**:
|
||||
```gdscript
|
||||
# 方法1: 移除无效的UID，使用文本路径
|
||||
# 将这行：
|
||||
[ext_resource type="Script" uid="uid://invalid_uid" path="res://path/to/script.gd" id="1_script"]
|
||||
|
||||
# 改为：
|
||||
[ext_resource type="Script" path="res://path/to/script.gd" id="1_script"]
|
||||
```
|
||||
|
||||
**预防措施**:
|
||||
- 移动文件时使用Godot编辑器的文件系统面板
|
||||
- 避免直接在文件系统中移动.gd和.tscn文件
|
||||
- 移动文件后重新导入项目
|
||||
|
||||
### 2. 脚本路径错误
|
||||
|
||||
**错误信息**:
|
||||
```
|
||||
ERROR: Failed to load script "res://old/path/Script.gd" with error "File not found".
|
||||
```
|
||||
|
||||
**解决方案**:
|
||||
```gdscript
|
||||
# 检查并更新所有.tscn文件中的脚本路径
|
||||
# 使用搜索替换功能批量更新：
|
||||
|
||||
# 旧路径 → 新路径
|
||||
"res://UI/Windows/" → "res://scenes/ui/"
|
||||
"res://Utils/" → "res://_Core/utils/"
|
||||
"res://Scenes/Maps/" → "res://scenes/maps/"
|
||||
```
|
||||
|
||||
### 3. AutoLoad路径错误
|
||||
|
||||
**错误信息**:
|
||||
```
|
||||
ERROR: Cannot load autoload: res://old/path/Manager.gd
|
||||
```
|
||||
|
||||
**解决方案**:
|
||||
```ini
|
||||
# 在 project.godot 中更新 AutoLoad 路径
|
||||
[autoload]
|
||||
GameManager="*res://_Core/managers/GameManager.gd"
|
||||
SceneManager="*res://_Core/managers/SceneManager.gd"
|
||||
EventSystem="*res://_Core/systems/EventSystem.gd"
|
||||
```
|
||||
|
||||
### 4. 资源加载失败
|
||||
|
||||
**错误信息**:
|
||||
```
|
||||
ERROR: Failed to load resource "res://old/path/resource.png".
|
||||
```
|
||||
|
||||
**解决方案**:
|
||||
```gdscript
|
||||
# 检查资源路径是否正确
|
||||
# 使用 ResourceLoader.exists() 验证路径
|
||||
func load_resource_safely(path: String):
|
||||
if not ResourceLoader.exists(path):
|
||||
push_error("Resource not found: %s" % path)
|
||||
return null
|
||||
|
||||
return load(path)
|
||||
```
|
||||
|
||||
## 🔍 调试技巧
|
||||
|
||||
### 1. 路径验证
|
||||
```gdscript
|
||||
# 验证文件是否存在
|
||||
func verify_file_exists(file_path: String) -> bool:
|
||||
return FileAccess.file_exists(file_path)
|
||||
|
||||
# 验证资源是否存在
|
||||
func verify_resource_exists(resource_path: String) -> bool:
|
||||
return ResourceLoader.exists(resource_path)
|
||||
|
||||
# 打印当前工作目录
|
||||
func print_current_directory():
|
||||
print("Current directory: ", OS.get_executable_path().get_base_dir())
|
||||
```
|
||||
|
||||
### 2. 场景加载调试
|
||||
```gdscript
|
||||
# 安全的场景加载
|
||||
func load_scene_safely(scene_path: String) -> PackedScene:
|
||||
if not ResourceLoader.exists(scene_path):
|
||||
push_error("Scene file not found: %s" % scene_path)
|
||||
return null
|
||||
|
||||
var scene = load(scene_path) as PackedScene
|
||||
if scene == null:
|
||||
push_error("Failed to load scene: %s" % scene_path)
|
||||
return null
|
||||
|
||||
return scene
|
||||
```
|
||||
|
||||
### 3. 节点引用调试
|
||||
```gdscript
|
||||
# 安全的节点获取
|
||||
func get_node_safely(node_path: String) -> Node:
|
||||
var node = get_node_or_null(node_path)
|
||||
if node == null:
|
||||
push_warning("Node not found: %s" % node_path)
|
||||
return node
|
||||
|
||||
# 检查@onready变量是否正确初始化
|
||||
func _ready():
|
||||
# 验证所有@onready节点
|
||||
if not some_button:
|
||||
push_error("some_button not found - check node path")
|
||||
if not some_label:
|
||||
push_error("some_label not found - check node path")
|
||||
```
|
||||
|
||||
## 🛠️ 项目结构问题
|
||||
|
||||
### 1. 文件移动后的检查清单
|
||||
- [ ] 更新.tscn文件中的脚本路径
|
||||
- [ ] 更新project.godot中的AutoLoad路径
|
||||
- [ ] 更新代码中的硬编码路径
|
||||
- [ ] 清理Godot缓存文件
|
||||
- [ ] 重新导入项目
|
||||
|
||||
### 2. 缓存清理命令
|
||||
```bash
|
||||
# Windows PowerShell
|
||||
Remove-Item -Recurse -Force ".godot\uid_cache.bin"
|
||||
Remove-Item -Recurse -Force ".godot\global_script_class_cache.cfg"
|
||||
|
||||
# Linux/macOS
|
||||
rm -rf .godot/uid_cache.bin
|
||||
rm -rf .godot/global_script_class_cache.cfg
|
||||
```
|
||||
|
||||
### 3. 路径常量管理
|
||||
```gdscript
|
||||
# 在 _Core/ProjectPaths.gd 中定义所有路径
|
||||
class_name ProjectPaths
|
||||
|
||||
# 核心路径
|
||||
const CORE_ROOT = "res://_Core/"
|
||||
const MANAGERS_PATH = CORE_ROOT + "managers/"
|
||||
const SYSTEMS_PATH = CORE_ROOT + "systems/"
|
||||
const UTILS_PATH = CORE_ROOT + "utils/"
|
||||
|
||||
# 场景路径
|
||||
const SCENES_ROOT = "res://scenes/"
|
||||
const UI_PATH = SCENES_ROOT + "ui/"
|
||||
const MAPS_PATH = SCENES_ROOT + "maps/"
|
||||
|
||||
# 使用示例
|
||||
var scene_path = ProjectPaths.UI_PATH + "LoginWindow.tscn"
|
||||
```
|
||||
|
||||
## 🎯 性能问题
|
||||
|
||||
### 1. 内存泄漏检测
|
||||
```gdscript
|
||||
# 监控节点数量
|
||||
func _ready():
|
||||
print("Initial node count: ", get_tree().get_node_count())
|
||||
|
||||
func _exit_tree():
|
||||
print("Final node count: ", get_tree().get_node_count())
|
||||
|
||||
# 检查未释放的资源
|
||||
func check_resource_leaks():
|
||||
print("Resource count: ", ResourceLoader.get_resource_list().size())
|
||||
```
|
||||
|
||||
### 2. 帧率监控
|
||||
```gdscript
|
||||
# 在 _Core/managers/PerformanceManager.gd
|
||||
extends Node
|
||||
|
||||
var frame_count: int = 0
|
||||
var fps_timer: float = 0.0
|
||||
|
||||
func _process(delta: float):
|
||||
frame_count += 1
|
||||
fps_timer += delta
|
||||
|
||||
if fps_timer >= 1.0:
|
||||
var fps = frame_count / fps_timer
|
||||
if fps < 30:
|
||||
push_warning("Low FPS detected: %.1f" % fps)
|
||||
|
||||
frame_count = 0
|
||||
fps_timer = 0.0
|
||||
```
|
||||
|
||||
## 🔧 开发工具问题
|
||||
|
||||
### 1. Godot编辑器崩溃
|
||||
**解决方案**:
|
||||
1. 备份项目文件
|
||||
2. 删除.godot文件夹
|
||||
3. 重新打开项目
|
||||
4. 重新导入所有资源
|
||||
|
||||
### 2. 脚本编辑器问题
|
||||
**解决方案**:
|
||||
```gdscript
|
||||
# 检查脚本语法
|
||||
# 使用 Godot 内置的语法检查器
|
||||
# 或者在命令行中运行：
|
||||
# godot --check-only script.gd
|
||||
```
|
||||
|
||||
### 3. 场景编辑器问题
|
||||
**解决方案**:
|
||||
- 检查场景文件是否损坏
|
||||
- 重新创建有问题的场景
|
||||
- 使用版本控制恢复到工作版本
|
||||
|
||||
---
|
||||
|
||||
**💡 提示**: 遇到问题时，首先检查Godot的输出面板和调试器，它们通常会提供详细的错误信息和解决建议。
|
||||
617
docs/AI_docs/templates/managers.md
Normal file
617
docs/AI_docs/templates/managers.md
Normal file
@@ -0,0 +1,617 @@
|
||||
# 🎯 管理器模板集合
|
||||
|
||||
> AI编程助手专用：各类管理器的标准化代码模板
|
||||
|
||||
## 🎮 游戏管理器模板
|
||||
|
||||
### 基础游戏管理器
|
||||
```gdscript
|
||||
# _Core/managers/GameManager.gd
|
||||
extends Node
|
||||
|
||||
## 游戏状态管理器
|
||||
## 负责管理游戏的全局状态、玩家数据和游戏流程
|
||||
|
||||
# 信号定义
|
||||
signal game_state_changed(old_state: GameState, new_state: GameState)
|
||||
signal player_data_updated(data: Dictionary)
|
||||
signal game_paused()
|
||||
signal game_resumed()
|
||||
|
||||
# 游戏状态枚举
|
||||
enum GameState {
|
||||
LOADING,
|
||||
MENU,
|
||||
PLAYING,
|
||||
PAUSED,
|
||||
GAME_OVER,
|
||||
SETTINGS
|
||||
}
|
||||
|
||||
# 常量定义
|
||||
const SAVE_FILE_PATH: String = "user://game_save.dat"
|
||||
const CONFIG_FILE_PATH: String = "res://Config/game_config.json"
|
||||
|
||||
# 导出变量
|
||||
@export var debug_mode: bool = false
|
||||
@export var auto_save_interval: float = 30.0
|
||||
|
||||
# 公共变量
|
||||
var current_state: GameState = GameState.LOADING
|
||||
var is_paused: bool = false
|
||||
var game_time: float = 0.0
|
||||
|
||||
# 玩家数据
|
||||
var player_data: Dictionary = {
|
||||
"level": 1,
|
||||
"experience": 0,
|
||||
"coins": 100,
|
||||
"health": 100,
|
||||
"max_health": 100,
|
||||
"energy": 100,
|
||||
"max_energy": 100
|
||||
}
|
||||
|
||||
# 私有变量
|
||||
var _auto_save_timer: Timer
|
||||
var _game_config: Dictionary = {}
|
||||
|
||||
func _ready() -> void:
|
||||
_initialize_manager()
|
||||
_setup_auto_save()
|
||||
_load_game_config()
|
||||
change_state(GameState.MENU)
|
||||
|
||||
func _process(delta: float) -> void:
|
||||
if current_state == GameState.PLAYING and not is_paused:
|
||||
game_time += delta
|
||||
|
||||
## 改变游戏状态
|
||||
func change_state(new_state: GameState) -> void:
|
||||
if current_state == new_state:
|
||||
return
|
||||
|
||||
var old_state = current_state
|
||||
_exit_state(old_state)
|
||||
current_state = new_state
|
||||
_enter_state(new_state)
|
||||
|
||||
game_state_changed.emit(old_state, new_state)
|
||||
|
||||
if debug_mode:
|
||||
print("[GameManager] State changed: %s -> %s" % [old_state, new_state])
|
||||
|
||||
## 暂停游戏
|
||||
func pause_game() -> void:
|
||||
if current_state != GameState.PLAYING:
|
||||
return
|
||||
|
||||
is_paused = true
|
||||
get_tree().paused = true
|
||||
game_paused.emit()
|
||||
|
||||
## 恢复游戏
|
||||
func resume_game() -> void:
|
||||
if not is_paused:
|
||||
return
|
||||
|
||||
is_paused = false
|
||||
get_tree().paused = false
|
||||
game_resumed.emit()
|
||||
|
||||
## 更新玩家数据
|
||||
func update_player_data(key: String, value) -> void:
|
||||
if not player_data.has(key):
|
||||
push_warning("Unknown player data key: %s" % key)
|
||||
return
|
||||
|
||||
player_data[key] = value
|
||||
player_data_updated.emit(player_data)
|
||||
|
||||
if debug_mode:
|
||||
print("[GameManager] Player data updated: %s = %s" % [key, value])
|
||||
|
||||
## 获取玩家数据
|
||||
func get_player_data(key: String = ""):
|
||||
if key.is_empty():
|
||||
return player_data.duplicate()
|
||||
|
||||
return player_data.get(key, null)
|
||||
|
||||
## 保存游戏数据
|
||||
func save_game() -> bool:
|
||||
var save_data = {
|
||||
"player_data": player_data,
|
||||
"game_time": game_time,
|
||||
"current_state": current_state,
|
||||
"timestamp": Time.get_unix_time_from_system()
|
||||
}
|
||||
|
||||
var file = FileAccess.open(SAVE_FILE_PATH, FileAccess.WRITE)
|
||||
if file == null:
|
||||
push_error("Failed to open save file for writing")
|
||||
return false
|
||||
|
||||
file.store_string(JSON.stringify(save_data))
|
||||
file.close()
|
||||
|
||||
if debug_mode:
|
||||
print("[GameManager] Game saved successfully")
|
||||
|
||||
return true
|
||||
|
||||
## 加载游戏数据
|
||||
func load_game() -> bool:
|
||||
if not FileAccess.file_exists(SAVE_FILE_PATH):
|
||||
if debug_mode:
|
||||
print("[GameManager] No save file found")
|
||||
return false
|
||||
|
||||
var file = FileAccess.open(SAVE_FILE_PATH, FileAccess.READ)
|
||||
if file == null:
|
||||
push_error("Failed to open save file for reading")
|
||||
return false
|
||||
|
||||
var json_text = file.get_as_text()
|
||||
file.close()
|
||||
|
||||
var json = JSON.new()
|
||||
var parse_result = json.parse(json_text)
|
||||
if parse_result != OK:
|
||||
push_error("Failed to parse save file JSON")
|
||||
return false
|
||||
|
||||
var save_data = json.data
|
||||
|
||||
# 恢复玩家数据
|
||||
if save_data.has("player_data"):
|
||||
player_data = save_data.player_data
|
||||
player_data_updated.emit(player_data)
|
||||
|
||||
# 恢复游戏时间
|
||||
if save_data.has("game_time"):
|
||||
game_time = save_data.game_time
|
||||
|
||||
if debug_mode:
|
||||
print("[GameManager] Game loaded successfully")
|
||||
|
||||
return true
|
||||
|
||||
# 私有方法
|
||||
func _initialize_manager() -> void:
|
||||
# 设置进程模式为总是处理（即使暂停时也能工作）
|
||||
process_mode = Node.PROCESS_MODE_ALWAYS
|
||||
|
||||
func _setup_auto_save() -> void:
|
||||
_auto_save_timer = Timer.new()
|
||||
add_child(_auto_save_timer)
|
||||
_auto_save_timer.wait_time = auto_save_interval
|
||||
_auto_save_timer.timeout.connect(_on_auto_save_timeout)
|
||||
_auto_save_timer.start()
|
||||
|
||||
func _load_game_config() -> void:
|
||||
if not FileAccess.file_exists(CONFIG_FILE_PATH):
|
||||
push_warning("Game config file not found")
|
||||
return
|
||||
|
||||
var file = FileAccess.open(CONFIG_FILE_PATH, FileAccess.READ)
|
||||
if file == null:
|
||||
push_error("Failed to open game config file")
|
||||
return
|
||||
|
||||
var json_text = file.get_as_text()
|
||||
file.close()
|
||||
|
||||
var json = JSON.new()
|
||||
var parse_result = json.parse(json_text)
|
||||
if parse_result != OK:
|
||||
push_error("Failed to parse game config JSON")
|
||||
return
|
||||
|
||||
_game_config = json.data
|
||||
|
||||
func _enter_state(state: GameState) -> void:
|
||||
match state:
|
||||
GameState.LOADING:
|
||||
# 加载游戏资源
|
||||
pass
|
||||
GameState.MENU:
|
||||
# 显示主菜单
|
||||
pass
|
||||
GameState.PLAYING:
|
||||
# 开始游戏逻辑
|
||||
_auto_save_timer.start()
|
||||
GameState.PAUSED:
|
||||
# 暂停游戏
|
||||
_auto_save_timer.stop()
|
||||
GameState.GAME_OVER:
|
||||
# 游戏结束处理
|
||||
save_game()
|
||||
GameState.SETTINGS:
|
||||
# 显示设置界面
|
||||
pass
|
||||
|
||||
func _exit_state(state: GameState) -> void:
|
||||
match state:
|
||||
GameState.PLAYING:
|
||||
# 退出游戏时自动保存
|
||||
save_game()
|
||||
|
||||
func _on_auto_save_timeout() -> void:
|
||||
if current_state == GameState.PLAYING:
|
||||
save_game()
|
||||
```
|
||||
|
||||
## 🌐 网络管理器模板
|
||||
|
||||
### HTTP请求管理器
|
||||
```gdscript
|
||||
# _Core/managers/NetworkManager.gd
|
||||
extends Node
|
||||
|
||||
## 网络请求管理器
|
||||
## 负责处理所有HTTP请求和网络通信
|
||||
|
||||
# 信号定义
|
||||
signal request_completed(request_id: String, success: bool, data: Dictionary)
|
||||
signal connection_status_changed(is_connected: bool)
|
||||
|
||||
# 常量定义
|
||||
const BASE_URL: String = "https://api.example.com"
|
||||
const TIMEOUT_DURATION: float = 10.0
|
||||
const MAX_RETRIES: int = 3
|
||||
|
||||
# 请求状态枚举
|
||||
enum RequestStatus {
|
||||
PENDING,
|
||||
SUCCESS,
|
||||
FAILED,
|
||||
TIMEOUT,
|
||||
CANCELLED
|
||||
}
|
||||
|
||||
# 公共变量
|
||||
var is_connected: bool = false
|
||||
var active_requests: Dictionary = {}
|
||||
|
||||
# 私有变量
|
||||
var _http_client: HTTPClient
|
||||
var _request_counter: int = 0
|
||||
|
||||
func _ready() -> void:
|
||||
_initialize_network()
|
||||
_check_connection()
|
||||
|
||||
## 发送GET请求
|
||||
func send_get_request(endpoint: String, headers: Dictionary = {}) -> String:
|
||||
return _send_request(HTTPClient.METHOD_GET, endpoint, "", headers)
|
||||
|
||||
## 发送POST请求
|
||||
func send_post_request(endpoint: String, data: Dictionary, headers: Dictionary = {}) -> String:
|
||||
var json_data = JSON.stringify(data)
|
||||
return _send_request(HTTPClient.METHOD_POST, endpoint, json_data, headers)
|
||||
|
||||
## 发送PUT请求
|
||||
func send_put_request(endpoint: String, data: Dictionary, headers: Dictionary = {}) -> String:
|
||||
var json_data = JSON.stringify(data)
|
||||
return _send_request(HTTPClient.METHOD_PUT, endpoint, json_data, headers)
|
||||
|
||||
## 发送DELETE请求
|
||||
func send_delete_request(endpoint: String, headers: Dictionary = {}) -> String:
|
||||
return _send_request(HTTPClient.METHOD_DELETE, endpoint, "", headers)
|
||||
|
||||
## 取消请求
|
||||
func cancel_request(request_id: String) -> bool:
|
||||
if not active_requests.has(request_id):
|
||||
return false
|
||||
|
||||
var request_data = active_requests[request_id]
|
||||
if request_data.http_request:
|
||||
request_data.http_request.cancel_request()
|
||||
|
||||
_cleanup_request(request_id, RequestStatus.CANCELLED)
|
||||
return true
|
||||
|
||||
## 检查网络连接状态
|
||||
func check_connection() -> void:
|
||||
_check_connection()
|
||||
|
||||
# 私有方法
|
||||
func _initialize_network() -> void:
|
||||
_http_client = HTTPClient.new()
|
||||
|
||||
func _send_request(method: HTTPClient.Method, endpoint: String, data: String, headers: Dictionary) -> String:
|
||||
var request_id = _generate_request_id()
|
||||
var full_url = BASE_URL + endpoint
|
||||
|
||||
# 创建HTTP请求节点
|
||||
var http_request = HTTPRequest.new()
|
||||
add_child(http_request)
|
||||
|
||||
# 设置请求超时
|
||||
http_request.timeout = TIMEOUT_DURATION
|
||||
|
||||
# 连接完成信号
|
||||
http_request.request_completed.connect(_on_request_completed.bind(request_id))
|
||||
|
||||
# 准备请求头
|
||||
var request_headers = ["Content-Type: application/json"]
|
||||
for key in headers:
|
||||
request_headers.append("%s: %s" % [key, headers[key]])
|
||||
|
||||
# 存储请求信息
|
||||
active_requests[request_id] = {
|
||||
"http_request": http_request,
|
||||
"method": method,
|
||||
"url": full_url,
|
||||
"status": RequestStatus.PENDING,
|
||||
"retry_count": 0,
|
||||
"start_time": Time.get_time_dict_from_system()
|
||||
}
|
||||
|
||||
# 发送请求
|
||||
var error = http_request.request(full_url, request_headers, method, data)
|
||||
if error != OK:
|
||||
push_error("Failed to send HTTP request: %d" % error)
|
||||
_cleanup_request(request_id, RequestStatus.FAILED)
|
||||
return ""
|
||||
|
||||
return request_id
|
||||
|
||||
func _generate_request_id() -> String:
|
||||
_request_counter += 1
|
||||
return "req_%d_%d" % [Time.get_time_dict_from_system().hour * 3600 + Time.get_time_dict_from_system().minute * 60 + Time.get_time_dict_from_system().second, _request_counter]
|
||||
|
||||
func _on_request_completed(request_id: String, result: int, response_code: int, headers: PackedStringArray, body: PackedByteArray) -> void:
|
||||
if not active_requests.has(request_id):
|
||||
return
|
||||
|
||||
var request_data = active_requests[request_id]
|
||||
var success = false
|
||||
var response_data = {}
|
||||
|
||||
# 解析响应
|
||||
if response_code >= 200 and response_code < 300:
|
||||
success = true
|
||||
var body_text = body.get_string_from_utf8()
|
||||
|
||||
if not body_text.is_empty():
|
||||
var json = JSON.new()
|
||||
var parse_result = json.parse(body_text)
|
||||
if parse_result == OK:
|
||||
response_data = json.data
|
||||
else:
|
||||
response_data = {"raw_response": body_text}
|
||||
else:
|
||||
# 处理错误响应
|
||||
var body_text = body.get_string_from_utf8()
|
||||
response_data = {
|
||||
"error": "HTTP Error %d" % response_code,
|
||||
"response_code": response_code,
|
||||
"raw_response": body_text
|
||||
}
|
||||
|
||||
# 发送完成信号
|
||||
request_completed.emit(request_id, success, response_data)
|
||||
|
||||
# 清理请求
|
||||
_cleanup_request(request_id, RequestStatus.SUCCESS if success else RequestStatus.FAILED)
|
||||
|
||||
func _cleanup_request(request_id: String, status: RequestStatus) -> void:
|
||||
if not active_requests.has(request_id):
|
||||
return
|
||||
|
||||
var request_data = active_requests[request_id]
|
||||
|
||||
# 移除HTTP请求节点
|
||||
if request_data.http_request:
|
||||
request_data.http_request.queue_free()
|
||||
|
||||
# 从活动请求中移除
|
||||
active_requests.erase(request_id)
|
||||
|
||||
func _check_connection() -> void:
|
||||
# 简单的连接检查（可以改为ping服务器）
|
||||
var old_status = is_connected
|
||||
is_connected = true # 这里可以实现实际的连接检查逻辑
|
||||
|
||||
if old_status != is_connected:
|
||||
connection_status_changed.emit(is_connected)
|
||||
```
|
||||
|
||||
## 🎵 音频管理器模板
|
||||
|
||||
### 音频系统管理器
|
||||
```gdscript
|
||||
# _Core/managers/AudioManager.gd
|
||||
extends Node
|
||||
|
||||
## 音频管理器
|
||||
## 负责管理游戏中的音乐和音效播放
|
||||
|
||||
# 信号定义
|
||||
signal music_finished()
|
||||
signal sound_effect_finished(sound_name: String)
|
||||
|
||||
# 音频类型枚举
|
||||
enum AudioType {
|
||||
MUSIC,
|
||||
SOUND_EFFECT,
|
||||
UI_SOUND,
|
||||
VOICE
|
||||
}
|
||||
|
||||
# 常量定义
|
||||
const MUSIC_PATH: String = "res://assets/audio/music/"
|
||||
const SOUND_PATH: String = "res://assets/audio/sounds/"
|
||||
const VOICE_PATH: String = "res://assets/audio/voice/"
|
||||
|
||||
# 导出变量
|
||||
@export var master_volume: float = 1.0
|
||||
@export var music_volume: float = 0.7
|
||||
@export var sfx_volume: float = 0.8
|
||||
@export var voice_volume: float = 0.9
|
||||
|
||||
# 音频播放器
|
||||
var music_player: AudioStreamPlayer
|
||||
var sfx_players: Array[AudioStreamPlayer] = []
|
||||
var voice_player: AudioStreamPlayer
|
||||
|
||||
# 当前播放状态
|
||||
var current_music: String = ""
|
||||
var is_music_playing: bool = false
|
||||
var active_sounds: Dictionary = {}
|
||||
|
||||
func _ready() -> void:
|
||||
_initialize_audio_players()
|
||||
_load_audio_settings()
|
||||
|
||||
## 播放背景音乐
|
||||
func play_music(music_name: String, fade_in: bool = true) -> void:
|
||||
var music_path = MUSIC_PATH + music_name + ".ogg"
|
||||
|
||||
if not ResourceLoader.exists(music_path):
|
||||
push_warning("Music file not found: %s" % music_path)
|
||||
return
|
||||
|
||||
# 停止当前音乐
|
||||
if is_music_playing:
|
||||
stop_music(fade_in)
|
||||
await get_tree().create_timer(0.5).timeout
|
||||
|
||||
# 加载并播放新音乐
|
||||
var audio_stream = load(music_path)
|
||||
music_player.stream = audio_stream
|
||||
music_player.volume_db = linear_to_db(music_volume * master_volume)
|
||||
|
||||
if fade_in:
|
||||
_fade_in_music()
|
||||
else:
|
||||
music_player.play()
|
||||
|
||||
current_music = music_name
|
||||
is_music_playing = true
|
||||
|
||||
## 停止背景音乐
|
||||
func stop_music(fade_out: bool = true) -> void:
|
||||
if not is_music_playing:
|
||||
return
|
||||
|
||||
if fade_out:
|
||||
_fade_out_music()
|
||||
else:
|
||||
music_player.stop()
|
||||
is_music_playing = false
|
||||
current_music = ""
|
||||
|
||||
## 播放音效
|
||||
func play_sound_effect(sound_name: String, volume_override: float = -1.0) -> void:
|
||||
var sound_path = SOUND_PATH + sound_name + ".ogg"
|
||||
|
||||
if not ResourceLoader.exists(sound_path):
|
||||
push_warning("Sound file not found: %s" % sound_path)
|
||||
return
|
||||
|
||||
# 获取可用的音效播放器
|
||||
var player = _get_available_sfx_player()
|
||||
if player == null:
|
||||
push_warning("No available sound effect player")
|
||||
return
|
||||
|
||||
# 加载并播放音效
|
||||
var audio_stream = load(sound_path)
|
||||
player.stream = audio_stream
|
||||
|
||||
var final_volume = volume_override if volume_override > 0 else sfx_volume
|
||||
player.volume_db = linear_to_db(final_volume * master_volume)
|
||||
|
||||
player.play()
|
||||
active_sounds[sound_name] = player
|
||||
|
||||
## 设置主音量
|
||||
func set_master_volume(volume: float) -> void:
|
||||
master_volume = clamp(volume, 0.0, 1.0)
|
||||
_update_all_volumes()
|
||||
|
||||
## 设置音乐音量
|
||||
func set_music_volume(volume: float) -> void:
|
||||
music_volume = clamp(volume, 0.0, 1.0)
|
||||
if is_music_playing:
|
||||
music_player.volume_db = linear_to_db(music_volume * master_volume)
|
||||
|
||||
## 设置音效音量
|
||||
func set_sfx_volume(volume: float) -> void:
|
||||
sfx_volume = clamp(volume, 0.0, 1.0)
|
||||
_update_sfx_volumes()
|
||||
|
||||
# 私有方法
|
||||
func _initialize_audio_players() -> void:
|
||||
# 创建音乐播放器
|
||||
music_player = AudioStreamPlayer.new()
|
||||
add_child(music_player)
|
||||
music_player.finished.connect(_on_music_finished)
|
||||
|
||||
# 创建多个音效播放器（支持同时播放多个音效）
|
||||
for i in range(8):
|
||||
var sfx_player = AudioStreamPlayer.new()
|
||||
add_child(sfx_player)
|
||||
sfx_players.append(sfx_player)
|
||||
|
||||
# 创建语音播放器
|
||||
voice_player = AudioStreamPlayer.new()
|
||||
add_child(voice_player)
|
||||
|
||||
func _get_available_sfx_player() -> AudioStreamPlayer:
|
||||
for player in sfx_players:
|
||||
if not player.playing:
|
||||
return player
|
||||
return null
|
||||
|
||||
func _fade_in_music() -> void:
|
||||
music_player.volume_db = linear_to_db(0.01)
|
||||
music_player.play()
|
||||
|
||||
var tween = create_tween()
|
||||
tween.tween_method(_set_music_volume_db, 0.01, music_volume * master_volume, 1.0)
|
||||
|
||||
func _fade_out_music() -> void:
|
||||
var tween = create_tween()
|
||||
tween.tween_method(_set_music_volume_db, music_volume * master_volume, 0.01, 1.0)
|
||||
tween.tween_callback(_stop_music_after_fade)
|
||||
|
||||
func _set_music_volume_db(volume: float) -> void:
|
||||
music_player.volume_db = linear_to_db(volume)
|
||||
|
||||
func _stop_music_after_fade() -> void:
|
||||
music_player.stop()
|
||||
is_music_playing = false
|
||||
current_music = ""
|
||||
|
||||
func _update_all_volumes() -> void:
|
||||
if is_music_playing:
|
||||
music_player.volume_db = linear_to_db(music_volume * master_volume)
|
||||
_update_sfx_volumes()
|
||||
|
||||
func _update_sfx_volumes() -> void:
|
||||
for player in sfx_players:
|
||||
if player.playing:
|
||||
player.volume_db = linear_to_db(sfx_volume * master_volume)
|
||||
|
||||
func _load_audio_settings() -> void:
|
||||
# 从配置文件加载音频设置
|
||||
pass
|
||||
|
||||
func _on_music_finished() -> void:
|
||||
is_music_playing = false
|
||||
current_music = ""
|
||||
music_finished.emit()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**🎯 使用说明**:
|
||||
1. 选择合适的管理器模板
|
||||
2. 根据具体需求修改类名和功能
|
||||
3. 确保在project.godot中配置为AutoLoad
|
||||
4. 遵循项目的命名规范和代码风格
|
||||
5. 添加必要的错误处理和日志记录
|
||||
363
docs/AI_docs/workflows/feature_development.md
Normal file
363
docs/AI_docs/workflows/feature_development.md
Normal file
@@ -0,0 +1,363 @@
|
||||
# 🚀 功能开发流程
|
||||
|
||||
> AI编程助手专用：新功能开发的标准化工作流程
|
||||
|
||||
## 🎯 开发流程概览
|
||||
|
||||
### 阶段1: 需求分析 → 阶段2: 架构设计 → 阶段3: 代码实现 → 阶段4: 测试验证 → 阶段5: 文档更新
|
||||
|
||||
---
|
||||
|
||||
## 📋 阶段1: 需求分析
|
||||
|
||||
### 1.1 理解需求
|
||||
```markdown
|
||||
**必须明确的问题:**
|
||||
- 功能的具体作用是什么？
|
||||
- 涉及哪些用户交互？
|
||||
- 需要哪些数据和状态管理？
|
||||
- 与现有功能的关系如何？
|
||||
```
|
||||
|
||||
### 1.2 需求分类
|
||||
```gdscript
|
||||
# 功能类型分类
|
||||
enum FeatureType {
|
||||
CORE_SYSTEM, # 核心系统功能 → 放在 _Core/
|
||||
GAME_SCENE, # 游戏场景功能 → 放在 scenes/
|
||||
UI_COMPONENT, # UI组件功能 → 放在 scenes/ui/
|
||||
ASSET_RELATED, # 资源相关功能 → 涉及 assets/
|
||||
CONFIG_DRIVEN # 配置驱动功能 → 涉及 Config/
|
||||
}
|
||||
```
|
||||
|
||||
### 1.3 依赖分析
|
||||
- 需要哪些现有管理器？
|
||||
- 需要创建新的管理器吗？
|
||||
- 需要新的事件定义吗？
|
||||
- 需要新的配置文件吗？
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ 阶段2: 架构设计
|
||||
|
||||
### 2.1 确定文件位置
|
||||
```gdscript
|
||||
# 根据功能类型确定文件位置
|
||||
match feature_type:
|
||||
FeatureType.CORE_SYSTEM:
|
||||
# _Core/managers/ 或 _Core/systems/
|
||||
var file_path = "_Core/managers/YourManager.gd"
|
||||
|
||||
FeatureType.GAME_SCENE:
|
||||
# scenes/maps/, scenes/characters/, scenes/effects/
|
||||
var file_path = "scenes/characters/YourCharacter.gd"
|
||||
|
||||
FeatureType.UI_COMPONENT:
|
||||
# scenes/ui/
|
||||
var file_path = "scenes/ui/YourWindow.gd"
|
||||
```
|
||||
|
||||
### 2.2 设计接口
|
||||
```gdscript
|
||||
# 定义公共接口
|
||||
class_name YourFeature
|
||||
|
||||
# 信号定义（对外通信）
|
||||
signal feature_initialized()
|
||||
signal feature_state_changed(new_state: String)
|
||||
|
||||
# 公共方法（供其他模块调用）
|
||||
func initialize(config: Dictionary) -> bool
|
||||
func get_state() -> String
|
||||
func cleanup() -> void
|
||||
```
|
||||
|
||||
### 2.3 事件设计
|
||||
```gdscript
|
||||
# 在 _Core/EventNames.gd 中添加新事件
|
||||
const YOUR_FEATURE_STARTED: String = "your_feature_started"
|
||||
const YOUR_FEATURE_COMPLETED: String = "your_feature_completed"
|
||||
const YOUR_FEATURE_ERROR: String = "your_feature_error"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💻 阶段3: 代码实现
|
||||
|
||||
### 3.1 创建基础结构
|
||||
```gdscript
|
||||
# 使用标准模板创建文件
|
||||
# 参考: docs/AI_docs/templates/components.md
|
||||
|
||||
extends Node # 或其他合适的基类
|
||||
|
||||
## [功能描述]
|
||||
## 负责[具体职责]
|
||||
|
||||
# 信号定义
|
||||
signal feature_ready()
|
||||
|
||||
# 枚举定义
|
||||
enum FeatureState {
|
||||
UNINITIALIZED,
|
||||
INITIALIZING,
|
||||
READY,
|
||||
ERROR
|
||||
}
|
||||
|
||||
# 常量定义
|
||||
const CONFIG_PATH: String = "res://Config/your_feature_config.json"
|
||||
|
||||
# 导出变量
|
||||
@export var debug_mode: bool = false
|
||||
|
||||
# 公共变量
|
||||
var current_state: FeatureState = FeatureState.UNINITIALIZED
|
||||
|
||||
# 私有变量
|
||||
var _config_data: Dictionary = {}
|
||||
|
||||
func _ready() -> void:
|
||||
initialize()
|
||||
```
|
||||
|
||||
### 3.2 实现核心逻辑
|
||||
```gdscript
|
||||
## 初始化功能
|
||||
func initialize() -> bool:
|
||||
if current_state != FeatureState.UNINITIALIZED:
|
||||
push_warning("Feature already initialized")
|
||||
return false
|
||||
|
||||
current_state = FeatureState.INITIALIZING
|
||||
|
||||
# 加载配置
|
||||
if not _load_config():
|
||||
current_state = FeatureState.ERROR
|
||||
return false
|
||||
|
||||
# 连接事件
|
||||
_connect_events()
|
||||
|
||||
# 执行初始化逻辑
|
||||
_perform_initialization()
|
||||
|
||||
current_state = FeatureState.READY
|
||||
feature_ready.emit()
|
||||
return true
|
||||
|
||||
func _load_config() -> bool:
|
||||
# 配置加载逻辑
|
||||
return true
|
||||
|
||||
func _connect_events() -> void:
|
||||
# 事件连接逻辑
|
||||
EventSystem.connect_event("related_event", _on_related_event)
|
||||
|
||||
func _perform_initialization() -> void:
|
||||
# 具体初始化逻辑
|
||||
pass
|
||||
```
|
||||
|
||||
### 3.3 错误处理
|
||||
```gdscript
|
||||
func _handle_error(error_message: String) -> void:
|
||||
push_error("[YourFeature] %s" % error_message)
|
||||
current_state = FeatureState.ERROR
|
||||
|
||||
# 发送错误事件
|
||||
EventSystem.emit_event(EventNames.YOUR_FEATURE_ERROR, {
|
||||
"message": error_message,
|
||||
"timestamp": Time.get_unix_time_from_system()
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 阶段4: 测试验证
|
||||
|
||||
### 4.1 创建测试文件
|
||||
```gdscript
|
||||
# tests/unit/test_your_feature.gd
|
||||
extends "res://addons/gut/test.gd"
|
||||
|
||||
## YourFeature 单元测试
|
||||
|
||||
var your_feature: YourFeature
|
||||
|
||||
func before_each():
|
||||
your_feature = preload("res://_Core/managers/YourFeature.gd").new()
|
||||
add_child(your_feature)
|
||||
|
||||
func after_each():
|
||||
your_feature.queue_free()
|
||||
|
||||
func test_initialization():
|
||||
# 测试初始化
|
||||
var result = your_feature.initialize()
|
||||
assert_true(result, "Feature should initialize successfully")
|
||||
assert_eq(your_feature.current_state, YourFeature.FeatureState.READY)
|
||||
|
||||
func test_error_handling():
|
||||
# 测试错误处理
|
||||
# 模拟错误条件
|
||||
pass
|
||||
```
|
||||
|
||||
### 4.2 集成测试
|
||||
```gdscript
|
||||
# tests/integration/test_your_feature_integration.gd
|
||||
extends "res://addons/gut/test.gd"
|
||||
|
||||
## YourFeature 集成测试
|
||||
|
||||
func test_feature_with_event_system():
|
||||
# 测试与事件系统的集成
|
||||
var event_received = false
|
||||
|
||||
EventSystem.connect_event("your_feature_started", func(data): event_received = true)
|
||||
|
||||
# 触发功能
|
||||
# 验证事件是否正确发送
|
||||
assert_true(event_received, "Event should be emitted")
|
||||
```
|
||||
|
||||
### 4.3 性能测试
|
||||
```gdscript
|
||||
# tests/performance/test_your_feature_performance.gd
|
||||
extends "res://addons/gut/test.gd"
|
||||
|
||||
## YourFeature 性能测试
|
||||
|
||||
func test_initialization_performance():
|
||||
var start_time = Time.get_time_dict_from_system()
|
||||
|
||||
# 执行功能
|
||||
your_feature.initialize()
|
||||
|
||||
var end_time = Time.get_time_dict_from_system()
|
||||
var duration = _calculate_duration(start_time, end_time)
|
||||
|
||||
# 验证性能要求（例如：初始化应在100ms内完成）
|
||||
assert_lt(duration, 0.1, "Initialization should complete within 100ms")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 阶段5: 文档更新
|
||||
|
||||
### 5.1 更新API文档
|
||||
```markdown
|
||||
# 在 docs/AI_docs/quick_reference/api_reference.md 中添加
|
||||
|
||||
## YourFeature API
|
||||
|
||||
### 初始化
|
||||
```gdscript
|
||||
var feature = YourFeature.new()
|
||||
feature.initialize(config_dict)
|
||||
```
|
||||
|
||||
### 主要方法
|
||||
- `initialize(config: Dictionary) -> bool` - 初始化功能
|
||||
- `get_state() -> FeatureState` - 获取当前状态
|
||||
- `cleanup() -> void` - 清理资源
|
||||
|
||||
### 事件
|
||||
- `feature_ready` - 功能准备就绪
|
||||
- `feature_state_changed(new_state)` - 状态改变
|
||||
```
|
||||
|
||||
### 5.2 更新使用示例
|
||||
```gdscript
|
||||
# 在 docs/AI_docs/quick_reference/code_snippets.md 中添加
|
||||
|
||||
## YourFeature 使用示例
|
||||
|
||||
### 基本使用
|
||||
```gdscript
|
||||
# 创建和初始化
|
||||
var feature = YourFeature.new()
|
||||
add_child(feature)
|
||||
|
||||
# 连接信号
|
||||
feature.feature_ready.connect(_on_feature_ready)
|
||||
|
||||
# 初始化
|
||||
var config = {"setting1": "value1"}
|
||||
feature.initialize(config)
|
||||
|
||||
func _on_feature_ready():
|
||||
print("Feature is ready to use")
|
||||
```
|
||||
```
|
||||
|
||||
### 5.3 更新架构文档
|
||||
```markdown
|
||||
# 在 docs/AI_docs/architecture_guide.md 中更新
|
||||
|
||||
## 新增功能: YourFeature
|
||||
|
||||
### 位置
|
||||
- 文件路径: `_Core/managers/YourFeature.gd`
|
||||
- AutoLoad: 是/否
|
||||
- 依赖: EventSystem, ConfigManager
|
||||
|
||||
### 职责
|
||||
- 负责[具体职责描述]
|
||||
- 管理[相关数据/状态]
|
||||
- 提供[对外接口]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ 开发检查清单
|
||||
|
||||
### 代码质量检查
|
||||
- [ ] 遵循命名规范（PascalCase类名，snake_case变量名）
|
||||
- [ ] 所有变量和函数都有类型注解
|
||||
- [ ] 添加了适当的注释和文档字符串
|
||||
- [ ] 实现了错误处理和边界检查
|
||||
- [ ] 使用事件系统进行模块间通信
|
||||
|
||||
### 架构一致性检查
|
||||
- [ ] 文件放在正确的目录中
|
||||
- [ ] 如果是管理器，已配置AutoLoad
|
||||
- [ ] 事件名称已添加到EventNames.gd
|
||||
- [ ] 配置文件已放在Config/目录
|
||||
- [ ] 遵循项目的架构原则
|
||||
|
||||
### 测试覆盖检查
|
||||
- [ ] 编写了单元测试
|
||||
- [ ] 编写了集成测试（如果需要）
|
||||
- [ ] 编写了性能测试（如果是核心功能）
|
||||
- [ ] 所有测试都能通过
|
||||
- [ ] 测试覆盖了主要功能和边界情况
|
||||
|
||||
### 文档更新检查
|
||||
- [ ] 更新了API参考文档
|
||||
- [ ] 添加了使用示例
|
||||
- [ ] 更新了架构文档
|
||||
- [ ] 更新了相关的工作流程文档
|
||||
|
||||
---
|
||||
|
||||
## 🔄 迭代优化
|
||||
|
||||
### 代码审查要点
|
||||
1. **功能完整性**: 是否满足所有需求？
|
||||
2. **性能表现**: 是否存在性能瓶颈？
|
||||
3. **错误处理**: 是否处理了所有可能的错误情况？
|
||||
4. **代码可读性**: 代码是否清晰易懂？
|
||||
5. **测试覆盖**: 测试是否充分？
|
||||
|
||||
### 持续改进
|
||||
- 收集用户反馈
|
||||
- 监控性能指标
|
||||
- 定期重构优化
|
||||
- 更新文档和示例
|
||||
|
||||
---
|
||||
|
||||
**🎯 记住**: 这个流程确保了功能开发的质量和一致性。严格遵循每个阶段的要求，将大大提高开发效率和代码质量。
|
||||
@@ -11,7 +11,7 @@ config_version=5
|
||||
[application]
|
||||
|
||||
config/name="whaleTown"
|
||||
run/main_scene="res://Scenes/Maps/main_scene.tscn"
|
||||
run/main_scene="res://scenes/maps/main_scene.tscn"
|
||||
config/features=PackedStringArray("4.5", "Forward Plus")
|
||||
config/icon="res://icon.svg"
|
||||
|
||||
|
||||
@@ -1 +0,0 @@
|
||||
# 保持目录结构 - 角色预制体目录
|
||||
@@ -1 +0,0 @@
|
||||
# 保持目录结构 - 特效预制体目录
|
||||
@@ -1 +0,0 @@
|
||||
# 保持目录结构 - 物品预制体目录
|
||||
@@ -1 +0,0 @@
|
||||
# 保持目录结构 - UI预制体目录
|
||||
2
scenes/Maps/.gitkeep
Normal file
2
scenes/Maps/.gitkeep
Normal file
@@ -0,0 +1,2 @@
|
||||
# 地图场景目录
|
||||
# 存放游戏关卡、世界地图等地图场景
|
||||
@@ -113,4 +113,4 @@ func _input(event):
|
||||
get_tree().quit()
|
||||
GameState.MAIN_GAME:
|
||||
# 在游戏中按ESC可能显示菜单或返回登录
|
||||
show_auth_scene()
|
||||
show_auth_scene()
|
||||
@@ -1 +1 @@
|
||||
uid://blp30m0tuach8
|
||||
uid://cn2xjgj3h847p
|
||||
|
||||
@@ -1,28 +1,14 @@
|
||||
[gd_scene load_steps=4 format=3 uid="uid://4ptgx76y83mx"]
|
||||
[gd_scene load_steps=3 format=3 uid="uid://21a49e14a0c58d7941d04142a5bf9ddc"]
|
||||
|
||||
[ext_resource type="Texture2D" uid="uid://bx17oy8lvaca4" path="res://assets/ui/auth/bg_auth_scene.png" id="1_background"]
|
||||
[ext_resource type="PackedScene" uid="uid://by7m8snb4xllf" path="res://UI/Windows/LoginWindow.tscn" id="2_main"]
|
||||
[ext_resource type="Script" uid="uid://blp30m0tuach8" path="res://Scenes/Maps/MainScene.gd" id="3_script"]
|
||||
[ext_resource type="Script" path="res://scenes/maps/MainScene.gd" id="1_script"]
|
||||
[ext_resource type="PackedScene" uid="uid://by7m8snb4xllf" path="res://scenes/ui/LoginWindow.tscn" id="2_main"]
|
||||
|
||||
[node name="Main" type="Control"]
|
||||
layout_mode = 3
|
||||
anchors_preset = 15
|
||||
anchor_right = 1.0
|
||||
anchor_bottom = 1.0
|
||||
grow_horizontal = 2
|
||||
grow_vertical = 2
|
||||
script = ExtResource("3_script")
|
||||
|
||||
[node name="BackgroundImage" type="TextureRect" parent="."]
|
||||
layout_mode = 1
|
||||
anchors_preset = 15
|
||||
anchor_right = 1.0
|
||||
anchor_bottom = 1.0
|
||||
grow_horizontal = 2
|
||||
grow_vertical = 2
|
||||
texture = ExtResource("1_background")
|
||||
expand_mode = 1
|
||||
stretch_mode = 6
|
||||
script = ExtResource("1_script")
|
||||
|
||||
[node name="AuthScene" parent="." instance=ExtResource("2_main")]
|
||||
layout_mode = 1
|
||||
@@ -33,24 +19,12 @@ layout_mode = 1
|
||||
anchors_preset = 15
|
||||
anchor_right = 1.0
|
||||
anchor_bottom = 1.0
|
||||
grow_horizontal = 2
|
||||
grow_vertical = 2
|
||||
|
||||
[node name="UIOverlay" type="ColorRect" parent="MainGameUI"]
|
||||
layout_mode = 1
|
||||
anchors_preset = 15
|
||||
anchor_right = 1.0
|
||||
anchor_bottom = 1.0
|
||||
grow_horizontal = 2
|
||||
grow_vertical = 2
|
||||
color = Color(0, 0, 0, 0.3)
|
||||
|
||||
[node name="TopBar" type="Panel" parent="MainGameUI"]
|
||||
layout_mode = 1
|
||||
anchors_preset = 10
|
||||
anchor_right = 1.0
|
||||
offset_bottom = 60.0
|
||||
grow_horizontal = 2
|
||||
|
||||
[node name="HBoxContainer" type="HBoxContainer" parent="MainGameUI/TopBar"]
|
||||
layout_mode = 1
|
||||
@@ -61,26 +35,16 @@ offset_left = 20.0
|
||||
offset_top = 10.0
|
||||
offset_right = -20.0
|
||||
offset_bottom = -10.0
|
||||
grow_horizontal = 2
|
||||
grow_vertical = 2
|
||||
|
||||
[node name="WelcomeLabel" type="Label" parent="MainGameUI/TopBar/HBoxContainer"]
|
||||
layout_mode = 2
|
||||
size_flags_horizontal = 3
|
||||
theme_override_colors/font_color = Color(1, 1, 1, 1)
|
||||
text = "🐋 欢迎来到鲸鱼镇！"
|
||||
vertical_alignment = 1
|
||||
|
||||
[node name="UserLabel" type="Label" parent="MainGameUI/TopBar/HBoxContainer"]
|
||||
layout_mode = 2
|
||||
theme_override_colors/font_color = Color(1, 1, 1, 1)
|
||||
text = "当前用户: [用户名]"
|
||||
horizontal_alignment = 2
|
||||
size_flags_horizontal = 3
|
||||
text = "当前用户: "
|
||||
vertical_alignment = 1
|
||||
|
||||
[node name="LogoutButton" type="Button" parent="MainGameUI/TopBar/HBoxContainer"]
|
||||
layout_mode = 2
|
||||
text = "退出"
|
||||
text = "登出"
|
||||
|
||||
[node name="MainContent" type="Control" parent="MainGameUI"]
|
||||
layout_mode = 1
|
||||
@@ -88,80 +52,29 @@ anchors_preset = 15
|
||||
anchor_right = 1.0
|
||||
anchor_bottom = 1.0
|
||||
offset_top = 60.0
|
||||
grow_horizontal = 2
|
||||
grow_vertical = 2
|
||||
|
||||
[node name="CenterContainer" type="CenterContainer" parent="MainGameUI/MainContent"]
|
||||
layout_mode = 1
|
||||
anchors_preset = 15
|
||||
anchor_right = 1.0
|
||||
anchor_bottom = 1.0
|
||||
grow_horizontal = 2
|
||||
grow_vertical = 2
|
||||
|
||||
[node name="VBoxContainer" type="VBoxContainer" parent="MainGameUI/MainContent/CenterContainer"]
|
||||
custom_minimum_size = Vector2(600, 400)
|
||||
layout_mode = 2
|
||||
|
||||
[node name="GameTitle" type="Label" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer"]
|
||||
layout_mode = 2
|
||||
theme_override_colors/font_color = Color(1, 1, 1, 1)
|
||||
theme_override_font_sizes/font_size = 24
|
||||
text = "🏘️ 鲸鱼镇主界面"
|
||||
horizontal_alignment = 1
|
||||
|
||||
[node name="HSeparator" type="HSeparator" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer"]
|
||||
layout_mode = 2
|
||||
|
||||
[node name="GameMenuGrid" type="GridContainer" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer"]
|
||||
layout_mode = 2
|
||||
size_flags_vertical = 3
|
||||
columns = 2
|
||||
|
||||
[node name="ExploreButton" type="Button" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/GameMenuGrid"]
|
||||
custom_minimum_size = Vector2(280, 80)
|
||||
layout_mode = 2
|
||||
text = "🗺️ 探索小镇"
|
||||
|
||||
[node name="InventoryButton" type="Button" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/GameMenuGrid"]
|
||||
custom_minimum_size = Vector2(280, 80)
|
||||
layout_mode = 2
|
||||
text = "🎒 背包物品"
|
||||
|
||||
[node name="ShopButton" type="Button" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/GameMenuGrid"]
|
||||
custom_minimum_size = Vector2(280, 80)
|
||||
layout_mode = 2
|
||||
text = "🏪 商店购物"
|
||||
|
||||
[node name="FriendsButton" type="Button" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/GameMenuGrid"]
|
||||
custom_minimum_size = Vector2(280, 80)
|
||||
layout_mode = 2
|
||||
text = "👥 好友列表"
|
||||
|
||||
[node name="HSeparator2" type="HSeparator" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer"]
|
||||
layout_mode = 2
|
||||
|
||||
[node name="StatusPanel" type="Panel" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer"]
|
||||
custom_minimum_size = Vector2(0, 120)
|
||||
layout_mode = 2
|
||||
custom_minimum_size = Vector2(400, 150)
|
||||
|
||||
[node name="StatusContainer" type="VBoxContainer" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/StatusPanel"]
|
||||
[node name="StatusContainer" type="MarginContainer" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/StatusPanel"]
|
||||
layout_mode = 1
|
||||
anchors_preset = 15
|
||||
anchor_right = 1.0
|
||||
anchor_bottom = 1.0
|
||||
offset_left = 20.0
|
||||
offset_top = 10.0
|
||||
offset_top = 20.0
|
||||
offset_right = -20.0
|
||||
offset_bottom = -10.0
|
||||
grow_horizontal = 2
|
||||
grow_vertical = 2
|
||||
|
||||
[node name="StatusTitle" type="Label" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/StatusPanel/StatusContainer"]
|
||||
layout_mode = 2
|
||||
theme_override_colors/font_color = Color(1, 1, 1, 1)
|
||||
text = "📊 玩家状态"
|
||||
horizontal_alignment = 1
|
||||
offset_bottom = -20.0
|
||||
|
||||
[node name="StatusGrid" type="GridContainer" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/StatusPanel/StatusContainer"]
|
||||
layout_mode = 2
|
||||
@@ -169,20 +82,40 @@ columns = 2
|
||||
|
||||
[node name="LevelLabel" type="Label" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/StatusPanel/StatusContainer/StatusGrid"]
|
||||
layout_mode = 2
|
||||
theme_override_colors/font_color = Color(1, 1, 1, 1)
|
||||
text = "等级: 1"
|
||||
|
||||
[node name="CoinsLabel" type="Label" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/StatusPanel/StatusContainer/StatusGrid"]
|
||||
layout_mode = 2
|
||||
theme_override_colors/font_color = Color(1, 1, 1, 1)
|
||||
text = "金币: 100"
|
||||
|
||||
[node name="ExpLabel" type="Label" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/StatusPanel/StatusContainer/StatusGrid"]
|
||||
layout_mode = 2
|
||||
theme_override_colors/font_color = Color(1, 1, 1, 1)
|
||||
text = "经验: 0/100"
|
||||
|
||||
[node name="EnergyLabel" type="Label" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/StatusPanel/StatusContainer/StatusGrid"]
|
||||
layout_mode = 2
|
||||
theme_override_colors/font_color = Color(1, 1, 1, 1)
|
||||
text = "体力: 100/100"
|
||||
|
||||
[node name="GameMenuGrid" type="GridContainer" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer"]
|
||||
layout_mode = 2
|
||||
columns = 2
|
||||
|
||||
[node name="ExploreButton" type="Button" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/GameMenuGrid"]
|
||||
layout_mode = 2
|
||||
custom_minimum_size = Vector2(150, 50)
|
||||
text = "🗺️ 探索小镇"
|
||||
|
||||
[node name="InventoryButton" type="Button" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/GameMenuGrid"]
|
||||
layout_mode = 2
|
||||
custom_minimum_size = Vector2(150, 50)
|
||||
text = "🎒 背包"
|
||||
|
||||
[node name="ShopButton" type="Button" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/GameMenuGrid"]
|
||||
layout_mode = 2
|
||||
custom_minimum_size = Vector2(150, 50)
|
||||
text = "🏪 商店"
|
||||
|
||||
[node name="FriendsButton" type="Button" parent="MainGameUI/MainContent/CenterContainer/VBoxContainer/GameMenuGrid"]
|
||||
layout_mode = 2
|
||||
custom_minimum_size = Vector2(150, 50)
|
||||
text = "👥 好友"
|
||||
2
scenes/characters/.gitkeep
Normal file
2
scenes/characters/.gitkeep
Normal file
@@ -0,0 +1,2 @@
|
||||
# 人物场景目录
|
||||
# 存放角色、NPC、敌人等人物相关场景
|
||||
2
scenes/effects/.gitkeep
Normal file
2
scenes/effects/.gitkeep
Normal file
@@ -0,0 +1,2 @@
|
||||
# 特效场景目录
|
||||
# 存放粒子效果、动画等特效场景
|
||||
2
scenes/prefabs/.gitkeep
Normal file
2
scenes/prefabs/.gitkeep
Normal file
@@ -0,0 +1,2 @@
|
||||
# 预制体组件目录
|
||||
# 存放可复用的预制体组件
|
||||
2
scenes/prefabs/characters/.gitkeep
Normal file
2
scenes/prefabs/characters/.gitkeep
Normal file
@@ -0,0 +1,2 @@
|
||||
# 角色预制体目录
|
||||
# 存放可复用的角色组件预制体
|
||||
2
scenes/prefabs/effects/.gitkeep
Normal file
2
scenes/prefabs/effects/.gitkeep
Normal file
@@ -0,0 +1,2 @@
|
||||
# 特效预制体目录
|
||||
# 存放可复用的特效组件预制体
|
||||
2
scenes/prefabs/items/.gitkeep
Normal file
2
scenes/prefabs/items/.gitkeep
Normal file
@@ -0,0 +1,2 @@
|
||||
# 物品预制体目录
|
||||
# 存放可复用的物品组件预制体
|
||||
2
scenes/prefabs/ui/.gitkeep
Normal file
2
scenes/prefabs/ui/.gitkeep
Normal file
@@ -0,0 +1,2 @@
|
||||
# UI预制体目录
|
||||
# 存放可复用的UI组件预制体
|
||||
2
scenes/ui/.gitkeep
Normal file
2
scenes/ui/.gitkeep
Normal file
@@ -0,0 +1,2 @@
|
||||
# UI界面场景目录
|
||||
# 存放菜单、HUD、对话框等UI界面场景
|
||||
@@ -1029,4 +1029,4 @@ func _exit_tree():
|
||||
|
||||
func _input(event):
|
||||
if event.is_action_pressed("ui_cancel"):
|
||||
get_tree().quit()
|
||||
get_tree().quit()
|
||||
1
scenes/ui/AuthScene.gd.uid
Normal file
1
scenes/ui/AuthScene.gd.uid
Normal file
@@ -0,0 +1 @@
|
||||
uid://b514h2wuido0h
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
[ext_resource type="Texture2D" uid="uid://bx17oy8lvaca4" path="res://assets/ui/auth/bg_auth_scene.png" id="1_background"]
|
||||
[ext_resource type="Texture2D" uid="uid://de4q4s1gxivtf" path="res://assets/ui/auth/login_frame_smart_transparent.png" id="2_frame"]
|
||||
[ext_resource type="Script" uid="uid://bs1vy3ierj66t" path="res://UI/Windows/AuthScene.gd" id="3_script"]
|
||||
[ext_resource type="Script" path="res://scenes/ui/AuthScene.gd" id="3_script"]
|
||||
|
||||
[sub_resource type="StyleBoxEmpty" id="StyleBoxEmpty_1"]
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
[gd_scene load_steps=4 format=3 uid="uid://bvn8y7x2qkqxe"]
|
||||
|
||||
[ext_resource type="Script" uid="uid://ddb8v5c6aeqe7" path="res://tests/auth/auth_ui_test.gd" id="1_test_script"]
|
||||
[ext_resource type="PackedScene" uid="uid://by7m8snb4xllf" path="res://UI/Windows/LoginWindow.tscn" id="2_auth_scene"]
|
||||
[ext_resource type="PackedScene" uid="uid://by7m8snb4xllf" path="res://scenes/ui/LoginWindow.tscn" id="2_auth_scene"]
|
||||
|
||||
[sub_resource type="StyleBoxFlat" id="StyleBoxFlat_feedback_info"]
|
||||
bg_color = Color(0.2, 0.5, 0.8, 0.9)
|
||||
|
||||
@@ -6,7 +6,7 @@ class_name EnhancedToastTest
|
||||
|
||||
# 测试新增的错误码处理
|
||||
func test_new_error_codes():
|
||||
var auth_scene = preload("res://UI/Windows/AuthScene.gd").new()
|
||||
var auth_scene = preload("res://scenes/ui/AuthScene.gd").new()
|
||||
|
||||
# 测试验证码登录失败
|
||||
var verification_login_error = {
|
||||
|
||||
Reference in New Issue
Block a user