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

refactor：重构项目架构为分层结构

Browse Source 
## 🏗️ 主要变更

### 目录结构重构
- 将 core/ 迁移到 _Core/（框架层）
- 将 scenes/ 重构为 Scenes/（玩法层）和 UI/（界面层）
- 将 data/ 迁移到 Config/（配置层）
- 添加 Assets/ 资源层和 Utils/ 工具层
- 将 scripts/ 迁移到 tools/（开发工具）

### 架构分层
- **_Core/**: 框架层 - 全局单例和管理器
- **Scenes/**: 玩法层 - 游戏场景和实体
- **UI/**: 界面层 - HUD、窗口、对话系统
- **Assets/**: 资源层 - 精灵图、音频、字体
- **Config/**: 配置层 - 游戏配置和本地化
- **Utils/**: 工具层 - 通用辅助脚本

### 文件更新
- 更新 project.godot 中的所有路径引用
- 更新自动加载脚本路径
- 更新测试文件的引用路径
- 添加 REFACTORING.md 详细说明
- 添加 MIGRATION_COMPLETE.md 迁移完成标记
- 更新 README.md 反映新架构

### 设计原则
- ✅ 清晰的分层（框架/玩法/界面）
- ✅ 场景内聚（脚本紧邻场景文件）
- ✅ 组件化设计（可复用组件）
- ✅ 职责单一（每个目录职责明确）

## 📋 详细信息
查看 REFACTORING.md 了解完整的重构说明和迁移映射表

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
王浩
2025-12-31 11:36:01 +08:00
parent b1f3c0feff
commit 0b533189ec
93 changed files with 1466 additions and 470 deletions
Download Patch File Download Diff File Expand all files Collapse all files

280
README.md
View File

@@ -32,12 +32,12 @@ python tests/api/simple_api_test.py
### Web版本部署
```bash
# Windows用户
scripts\build_web.bat # 导出Web版本
scripts\serve_web.bat # 启动本地测试服务器
tools\build_web.bat # 导出Web版本
tools\serve_web.bat # 启动本地测试服务器
# Linux/macOS用户
./scripts/build_web.sh # 导出Web版本
./scripts/serve_web.sh # 启动本地测试服务器
./tools/build_web.sh # 导出Web版本
./tools/serve_web.sh # 启动本地测试服务器
```
详细部署指南请查看: [Web部署完整指南](docs/web_deployment_guide.md)
@@ -45,7 +45,9 @@ scripts\serve_web.bat # 启动本地测试服务器
## 🏗️ 项目架构
### 核心设计理念
- **场景独立性** - 每个场景都是独立的功能模块
项目采用 **分层架构** 和 **组件化设计**，遵循 Godot 最佳实践：
- **清晰的分层** - 框架层、玩法层、界面层明确分离
- **场景内聚** - 脚本紧邻场景文件，符合 Godot 原生开发习惯
- **高度解耦** - 通过事件系统和管理器通信
- **组件复用** - 可复用组件统一管理
- **标准化** - 统一的命名规范和目录结构
@@ -54,79 +56,169 @@ scripts\serve_web.bat # 启动本地测试服务器
### 目录结构
```
whaleTown/
├── 🎬 scenes/ # 游戏场景
│ ├── auth_scene.tscn # 用户认证场景
│ ├── main_scene.tscn # 主游戏场景
│ └── prefabs/ # 预制体组件
├── 🔧 core/ # 核心系统（自动加载）
│ ├── managers/ # 全局管理器
│ ├── systems/ # 系统组件
│ └── utils/ # 工具类
├── 📝 scripts/ # 业务逻辑脚本
│ ├── scenes/ # 场景脚本
│ ├── network/ # 网络相关
│ ├── build_web.bat # Windows Web导出脚本
│ ├── build_web.sh # Linux/macOS Web导出脚本
│ ├── serve_web.bat # Windows 本地服务器
│ ├── serve_web.sh # Linux/macOS 本地服务器
│ └── ui/ # UI组件脚本
├── 🧩 module/ # 可复用模块
│ ├── UI/ # UI组件模块
│ ├── Character/ # 角色模块
│ ├── Combat/ # 战斗模块
│ ├── Dialogue/ # 对话模块
│ └── Inventory/ # 背包模块
├── 🎨 assets/ # 游戏资源
│ ├── sprites/ # 精灵图资源
│ ├── audio/ # 音频文件
│ ├── ui/ # UI界面资源
│ ├── fonts/ # 字体资源
│ ├── materials/ # 材质资源
│ └── shaders/ # 着色器资源
├── 📊 data/ # 配置数据
│ ├── configs/ # 游戏配置
│ ├── localization/ # 本地化文件
│ ├── characters/ # 角色数据
│ ├── items/ # 物品数据
│ ├── levels/ # 关卡数据
│ └── dialogues/ # 对话数据
├── 🧪 tests/ # 测试文件
│ ├── api/ # API接口测试
│ ├── auth/ # 认证UI测试
│ ├── unit/ # 单元测试
│ ├── integration/ # 集成测试
│ └── performance/ # 性能测试
└── 📚 docs/ # 项目文档
├── auth/ # 认证相关文档
├── api-documentation.md # API接口文档
├── web_deployment_guide.md # Web部署完整指南
├── web_deployment_changelog.md # Web部署更新日志
├── project_structure.md # 项目结构说明
├── naming_convention.md # 命名规范
├── code_comment_guide.md # 代码注释规范
└── git_commit_guide.md # Git提交规范
├── _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 # 登录窗口
│ ├── Dialog/ # 对话系统
│ └── Theme/ # 全局样式
│ ├── MainTheme.tres # 主主题
│ └── Fonts/ # 字体文件
│
├── Assets/ # [资源层] 美术、音频、字体
│ ├── Sprites/ # 精灵图
│ │ ├── icon/ # 图标
│ │ ├── materials/ # 材质
│ │ ├── shaders/ # 着色器
│ │ └── sprites/ # 精灵图
│ ├── Audio/ # 音频
│ └── Fonts/ # 字体
│
├── Config/ # [配置层] 游戏配置文件
│ ├── game_config.json # 游戏配置
│ └── zh_CN.json # 中文本地化
│
├── Utils/ # [工具层] 通用辅助脚本
│ └── StringUtils.gd # 字符串工具
│
├── Tests/ # [测试层] 单元测试脚本
│ ├── api/ # API接口测试
│ ├── auth/ # 认证UI测试
│ ├── unit/ # 单元测试
│ ├── integration/ # 集成测试
│ └── performance/ # 性能测试
│
├── docs/ # 项目文档
│ ├── auth/ # 认证相关文档
│ ├── api-documentation.md # API接口文档
│ ├── web_deployment_guide.md # Web部署完整指南
│ ├── web_deployment_changelog.md # Web部署更新日志
│ ├── project_structure.md # 项目结构说明
│ ├── naming_convention.md # 命名规范
│ ├── code_comment_guide.md # 代码注释规范
│ └── git_commit_guide.md # Git提交规范
│
├── tools/ # 开发工具和脚本
│ ├── build_web.bat # Windows Web导出脚本
│ ├── build_web.sh # Linux/macOS Web导出脚本
│ ├── serve_web.bat # Windows 本地服务器
│ └── serve_web.sh # Linux/macOS 本地服务器
│
├── REFACTORING.md # 项目结构重构文档
└── MIGRATION_COMPLETE.md # 迁移完成标记
```
### 架构层次说明
#### 1. 框架层 (_Core/)
- **职责**: 游戏的底层框架，与具体游戏逻辑无关
- **内容**: 单例管理器、核心系统
- **特点**: 自动加载，全局可访问
- **命名**: 使用下划线前缀 `_Core` 表示这是核心框架代码
#### 2. 玩法层 (Scenes/)
- **职责**: 游戏世界，地图和实体
- **内容**: 游戏场景、角色、NPC、交互物
- **特点**: 场景内聚，脚本紧邻场景文件
- **组织**: 按游戏世界的实体类型分类
#### 3. 界面层 (UI/)
- **职责**: 所有界面，HUD和弹窗
- **内容**: 常驻界面、模态窗口、对话系统、主题样式
- **特点**: 独立于游戏场景，便于UI开发和维护
- **组织**: 按界面类型和用途分类
#### 4. 资源层 (Assets/)
- **职责**: 纯美术资源
- **内容**: 精灵图、音频、字体等
- **特点**: 与代码分离，便于美术组独立工作
- **组织**: 按资源类型分类
#### 5. 配置层 (Config/)
- **职责**: 静态数据，策划可编辑
- **内容**: 游戏配置、本地化文件
- **特点**: 数据驱动，便于调整游戏参数
- **格式**: JSON 文件
#### 6. 工具层 (Utils/)
- **职责**: 通用辅助脚本
- **内容**: 工具函数库
- **特点**: 可被任何层调用
- **原则**: 无依赖，纯函数
### 核心系统
项目包含以下自动加载的核心系统：
项目包含以下自动加载的核心系统（位于 [_Core/](./_Core/)）：
- **GameManager** - 全局游戏状态管理
- **SceneManager** - 场景切换管理
- **SceneManager** - 场景切换管理
- **EventSystem** - 事件通信系统
- **NetworkManager** - 网络通信管理
- **ResponseHandler** - API响应处理
使用示例：
```gdscript
# 状态管理
GameManager.change_state(GameManager.GameState.IN_GAME)
# 场景切换
SceneManager.change_scene("battle")
# 场景切换（已更新路径）
SceneManager.change_scene("main") # → res://Scenes/Maps/main_scene.tscn
# 事件通信
EventSystem.emit_event("player_health_changed", 80)
EventSystem.connect_event("player_died", _on_player_died)
```
### 设计原则
#### 1. 清晰的分层
- **_Core**: 框架代码，与具体游戏逻辑无关
- **Scenes**: 游戏世界，地图和实体
- **UI**: 所有界面，HUD和弹窗
- **Config**: 静态数据，策划可编辑
#### 2. 组件化设计
可复用组件放在 `Scenes/Components/` 下，使用组合优于继承的设计模式：
- InteractableArea.tscn - 让任何物体"可交互"
- MovementSync.gd - 网络位置同步
- NameTag3D.tscn - 头顶名字条
#### 3. 场景内聚
- 每个 .tscn 配套一个 .gd
- 脚本紧邻场景文件存放
- 符合 Godot 原生开发习惯
#### 4. 职责单一
```
UI/Windows/ - 模态窗口（登录、设置、商店）
UI/HUD/ - 常驻界面（聊天框、状态栏）
UI/Dialog/ - 对话系统
```
### 团队协作
- **美术组**: 主要在 [Assets/](./Assets/) 工作
- **策划组**: 主要在 [Config/](./Config/) 工作
- **程序组**: 主要在 [_Core/](./_Core/), [Scenes/](./Scenes/), [UI/](./UI/) 工作
- **测试组**: 主要在 [Tests/](./Tests/) 工作
## ✨ 主要功能
### 🔐 用户认证系统
@@ -135,6 +227,7 @@ EventSystem.connect_event("player_died", _on_player_died)
- **密码管理** - 密码重置和修改功能
- **GitHub OAuth** - 第三方登录集成
- **错误处理** - 完整的错误提示和频率限制
- **UI界面**: [UI/Windows/LoginWindow.tscn](UI/Windows/LoginWindow.tscn)
### 🌐 Web版本部署
- **自动化导出** - 一键导出Web版本
@@ -144,14 +237,14 @@ EventSystem.connect_event("player_died", _on_player_died)
- **性能优化** - 资源压缩和加载优化
### 🎮 游戏功能
- **主场景** - 游戏主界面和菜单系统
- **主场景** - 游戏主界面和菜单系统 ([Scenes/Maps/main_scene.tscn](Scenes/Maps/main_scene.tscn))
- **认证场景** - 完整的登录注册界面
- **状态管理** - 用户状态和游戏状态管理
- **网络通信** - RESTful API集成
- **网络通信** - RESTful API集成 ([_Core/managers/NetworkManager.gd](_Core/managers/NetworkManager.gd))
### 🧪 测试体系
- **API测试** - 完整的接口测试脚本
- **UI测试** - 认证界面的交互测试
- **API测试** - 完整的接口测试脚本 ([Tests/api/](Tests/api/))
- **UI测试** - 认证界面的交互测试 ([Tests/auth/](Tests/auth/))
- **错误场景** - 边界条件和异常处理测试
## 🔧 开发规范
@@ -201,24 +294,54 @@ git commit -m "docs：更新项目文档"
## 🛠️ 开发指南
### 添加新场景
1. 在 `scenes/` 创建场景文件
2. 在 `scripts/scenes/` 创建对应脚本
3. 在 `SceneManager` 中注册场景路径
4. 使用 `SceneManager.change_scene()` 切换
1. 在 [Scenes/](./Scenes/) 对应分类下创建场景文件
2. 脚本文件紧邻场景文件存放（场景内聚原则）
3. 在 [_Core/managers/SceneManager.gd](_Core/managers/SceneManager.gd) 中注册场景路径
4. 使用 `SceneManager.change_scene()` 切换场景
示例：
```gdscript
# 在 SceneManager.gd 中注册
var scene_paths: Dictionary = {
"battle": "res://Scenes/Maps/battle_scene.tscn",
"shop": "res://UI/Windows/ShopWindow.tscn",
}
# 使用
SceneManager.change_scene("battle")
```
### 创建可复用组件
1. 在 `module/` 对应分类下创建组件
2. 实现标准接口
3. 通过 `EventSystem` 与其他模块通信
4. 在 `scenes/prefabs/` 创建预制体
1. 在 [Scenes/Components/](./Scenes/Components/) 创建组件场景
2. 实现标准接口，保持组件独立性
3. 通过 [EventSystem](_Core/systems/EventSystem.gd) 与其他模块通信
4. 组件可以被任何场景实例化复用
### 添加UI界面
1. **模态窗口** → 放入 [UI/Windows/](./UI/Windows/)
2. **常驻界面** → 放入 [UI/HUD/](./UI/HUD/)
3. **对话系统** → 放入 [UI/Dialog/](./UI/Dialog/)
4. UI脚本紧邻场景文件，保持内聚
### 资源管理
- 图片资源放入 `assets/sprites/` 对应分类
- 音频文件放入 `assets/audio/` 对应分类
- UI资源放入 `assets/ui/` 对应分类
- 配置文件放入 `data/configs/`
- **精灵图** → 放入 [Assets/Sprites/](./Assets/Sprites/) 对应分类
- **音频文件** → 放入 [Assets/Audio/](./Assets/Audio/) 对应分类
- **字体文件** → 放入 [UI/Theme/Fonts/](./UI/Theme/Fonts/)
- **配置文件** → 放入 [Config/](./Config/)
- 遵循命名规范，使用英文小写+下划线
### 路径映射参考
| 功能类型 | 旧路径 | 新路径 |
|---------|--------|--------|
| 核心管理器 | `core/managers/` | [_Core/managers/](_Core/managers/) |
| 游戏场景 | `scenes/main_scene.tscn` | [Scenes/Maps/main_scene.tscn](Scenes/Maps/main_scene.tscn) |
| 登录界面 | `scenes/auth_scene.tscn` | [UI/Windows/LoginWindow.tscn](UI/Windows/LoginWindow.tscn) |
| 配置文件 | `data/configs/` | [Config/](Config/) |
| 工具类 | `core/utils/` | [Utils/](Utils/) |
详细的重构说明请查看：[REFACTORING.md](REFACTORING.md)
### API接口测试
项目提供了完整的Python测试脚本来验证API接口：
@@ -291,6 +414,7 @@ python tests/api/simple_api_test.py https://your-api-server.com
## 🎯 项目状态
- ✅ 基础架构搭建完成
- ✅ 项目结构重构完成（2025-12-31）
- ✅ 用户认证系统完成
- ✅ API接口集成完成
- ✅ 测试体系建立完成
@@ -298,4 +422,6 @@ python tests/api/simple_api_test.py https://your-api-server.com
- 🚧 游戏核心玩法开发中
- 🚧 更多功能模块开发中
**最后更新**: 2025-12-24
**最后更新**: 2025-12-31
**重要更新**: 项目已完成架构重构，采用新的分层结构。详见 [REFACTORING.md](REFACTORING.md)