forked from datawhale/whale-town-front
720 lines
25 KiB
Markdown
720 lines
25 KiB
Markdown
# 🐋 Whale Town - 像素游戏前端客户端
|
||
|
||
> 一个基于 Godot 4.5 引擎开发的现代化 2D 像素风游戏前端，采用模块化架构设计，集成完整的用户认证系统、实时通信和游戏核心功能。
|
||
|
||
[](https://godotengine.org/)
|
||
[](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/index.html)
|
||
[](./LICENSE)
|
||
[](https://godotengine.org/download)
|
||
|
||
## 🎯 项目简介
|
||
|
||
Whale Town 是一个功能完整的像素游戏前端客户端，采用模块化架构设计：
|
||
|
||
- 🔐 **用户认证系统** - 完整的登录、注册、密码管理、邮箱验证界面
|
||
- 🎮 **游戏核心功能** - 角色系统、战斗系统、对话系统、背包系统
|
||
- 🌐 **实时通信** - WebSocket集成，支持实时多人交互
|
||
- 🎨 **现代化UI** - 响应式界面设计，支持多分辨率适配
|
||
- 🧪 **完整测试体系** - UI测试、API测试、性能测试全覆盖
|
||
- 📱 **跨平台支持** - Windows、Linux、macOS、移动端
|
||
- 🔧 **模块化架构** - 高度解耦的组件系统，易于扩展和维护
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
<<<<<<< HEAD
|
||
### 📋 环境要求
|
||
|
||
- **Godot Engine** >= 4.5.0 (推荐 4.5.1)
|
||
- **Python** >= 3.7.0 (用于API测试，可选)
|
||
- **Git** >= 2.0.0
|
||
|
||
### 🛠️ 安装与运行
|
||
=======
|
||
### 环境要求
|
||
- [Godot Engine 4.5+](https://godotengine.org/download)
|
||
- Python 3.7+ (用于API测试和Web服务器)
|
||
>>>>>>> whale-town-front/main
|
||
|
||
```bash
|
||
# 1. 克隆项目
|
||
git clone <repository-url>
|
||
cd whale-town
|
||
|
||
# 2. 使用Godot编辑器打开项目
|
||
# 双击 project.godot 文件或在Godot编辑器中导入项目
|
||
|
||
# 3. 运行项目
|
||
# 按F5或点击"运行"按钮启动游戏
|
||
```
|
||
|
||
<<<<<<< HEAD
|
||
🎉 **游戏启动成功！** 进入认证界面开始体验
|
||
|
||
### 🧪 快速测试
|
||
|
||
```bash
|
||
# API接口测试
|
||
=======
|
||
### Web版本部署
|
||
```bash
|
||
# Windows用户
|
||
tools\build_web.bat # 导出Web版本
|
||
tools\serve_web.bat # 启动本地测试服务器
|
||
|
||
# Linux/macOS用户
|
||
./tools/build_web.sh # 导出Web版本
|
||
./tools/serve_web.sh # 启动本地测试服务器
|
||
```
|
||
|
||
详细部署指南请查看: [Web部署完整指南](docs/web_deployment_guide.md)
|
||
|
||
## 🏗️ 项目架构
|
||
|
||
### 核心设计理念
|
||
项目采用 **分层架构** 和 **组件化设计**，遵循 Godot 最佳实践：
|
||
- **清晰的分层** - 框架层、玩法层、界面层明确分离
|
||
- **场景内聚** - 脚本紧邻场景文件，符合 Godot 原生开发习惯
|
||
- **高度解耦** - 通过事件系统和管理器通信
|
||
- **组件复用** - 可复用组件统一管理
|
||
- **标准化** - 统一的命名规范和目录结构
|
||
- **测试驱动** - 完整的测试体系和文档
|
||
|
||
### 目录结构
|
||
```
|
||
whaleTown/
|
||
├── _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** - 场景切换管理
|
||
- **EventSystem** - 事件通信系统
|
||
- **NetworkManager** - 网络通信管理
|
||
- **ResponseHandler** - API响应处理
|
||
|
||
使用示例：
|
||
```gdscript
|
||
# 状态管理
|
||
GameManager.change_state(GameManager.GameState.IN_GAME)
|
||
|
||
# 场景切换（已更新路径）
|
||
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/) 工作
|
||
|
||
## ✨ 主要功能
|
||
|
||
### 🔐 用户认证系统
|
||
- **用户注册** - 支持邮箱验证码验证
|
||
- **用户登录** - 多种登录方式（用户名/邮箱/手机号）
|
||
- **密码管理** - 密码重置和修改功能
|
||
- **GitHub OAuth** - 第三方登录集成
|
||
- **错误处理** - 完整的错误提示和频率限制
|
||
- **UI界面**: [UI/Windows/LoginWindow.tscn](UI/Windows/LoginWindow.tscn)
|
||
|
||
### 🌐 Web版本部署
|
||
- **自动化导出** - 一键导出Web版本
|
||
- **本地测试服务器** - 内置HTTP服务器用于测试
|
||
- **生产环境配置** - 完整的服务器配置指南
|
||
- **跨平台支持** - Windows、Linux、macOS全平台支持
|
||
- **性能优化** - 资源压缩和加载优化
|
||
|
||
### 🎮 游戏功能
|
||
- **主场景** - 游戏主界面和菜单系统 ([Scenes/Maps/main_scene.tscn](Scenes/Maps/main_scene.tscn))
|
||
- **认证场景** - 完整的登录注册界面
|
||
- **状态管理** - 用户状态和游戏状态管理
|
||
- **网络通信** - RESTful API集成 ([_Core/managers/NetworkManager.gd](_Core/managers/NetworkManager.gd))
|
||
|
||
### 🧪 测试体系
|
||
- **API测试** - 完整的接口测试脚本 ([Tests/api/](Tests/api/))
|
||
- **UI测试** - 认证界面的交互测试 ([Tests/auth/](Tests/auth/))
|
||
- **错误场景** - 边界条件和异常处理测试
|
||
|
||
## 🔧 开发规范
|
||
|
||
### 命名规范
|
||
- **场景文件**: `snake_case_scene.tscn` (如: `auth_scene.tscn`)
|
||
- **脚本文件**: `PascalCase.gd` (如: `AuthScene.gd`)
|
||
- **节点名称**: `camelCase` (如: `loginButton`)
|
||
- **变量/函数**: `camelCase` (如: `playerHealth`)
|
||
- **常量**: `UPPER_CASE` (如: `MAX_HEALTH`)
|
||
- **资源文件**: `snake_case` (如: `bg_auth_scene.png`)
|
||
|
||
### 代码注释规范
|
||
- **文件头注释**: 说明文件用途、主要功能和依赖关系
|
||
- **函数注释**: 包含参数说明、返回值和使用示例
|
||
- **复杂逻辑**: 添加行内注释解释业务逻辑和设计决策
|
||
- **特殊标记**: 使用 TODO、FIXME、NOTE 等标准标记
|
||
- **AI辅助**: 支持AI补充注释，提供详细的上下文信息
|
||
|
||
### Git 提交规范
|
||
使用格式：`<类型>：<描述>`
|
||
|
||
常用类型：`feat` `fix` `docs` `refactor` `scene` `asset` `ui` `test`
|
||
|
||
```bash
|
||
git commit -m "feat：实现用户登录功能"
|
||
git commit -m "fix：修复429错误处理"
|
||
git commit -m "test：添加API接口测试"
|
||
git commit -m "docs：更新项目文档"
|
||
```
|
||
|
||
## 📚 项目文档
|
||
|
||
### 核心文档
|
||
- 📋 [项目结构详解](docs/project_structure.md) - 完整的架构说明
|
||
- 📝 [命名规范](docs/naming_convention.md) - 详细的命名规则
|
||
- 💬 [代码注释规范](docs/code_comment_guide.md) - 注释标准和AI辅助指南
|
||
- 🔀 [Git提交规范](docs/git_commit_guide.md) - 提交信息标准
|
||
- 🌐 [Web部署指南](docs/web_deployment_guide.md) - 完整的Web部署文档
|
||
|
||
### API和测试文档
|
||
- 🔌 [API接口文档](docs/api-documentation.md) - 完整的API说明和测试指南
|
||
- 🔐 [认证系统文档](docs/auth/) - 用户认证相关文档
|
||
- 🧪 [API测试指南](tests/api/README.md) - API测试使用方法
|
||
- 🎮 [认证UI测试](tests/auth/README.md) - UI测试场景说明
|
||
|
||
## 🛠️ 开发指南
|
||
|
||
### 添加新场景
|
||
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. 在 [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/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接口：
|
||
|
||
```bash
|
||
# 快速测试API连通性
|
||
>>>>>>> whale-town-front/main
|
||
python tests/api/simple_api_test.py
|
||
|
||
# 完整功能测试
|
||
python tests/api/api_test.py --verbose
|
||
```
|
||
|
||
**测试内容：**
|
||
- ✅ 用户认证流程测试
|
||
- ✅ API接口连通性测试
|
||
- ✅ 错误处理和边界条件测试
|
||
- ✅ 网络通信功能测试
|
||
|
||
---
|
||
|
||
## 🎓 新开发者指南
|
||
|
||
<<<<<<< HEAD
|
||
### 第一步：了解项目规范 📚
|
||
|
||
**⚠️ 重要：在开始开发前，请务必阅读以下文档**
|
||
|
||
1. **[项目结构详解](./docs/project_structure.md)** 🏗️
|
||
- 理解模块化架构设计
|
||
- 掌握目录组织规则
|
||
- 学习组件通信机制
|
||
|
||
2. **[命名规范](./docs/naming_convention.md)** 📝
|
||
- 场景、脚本、节点命名规则
|
||
- 资源文件命名标准
|
||
- 变量和函数命名约定
|
||
|
||
3. **[代码注释规范](./docs/code_comment_guide.md)** 💬
|
||
- 注释标准和最佳实践
|
||
- AI辅助开发指南
|
||
- 文档生成规范
|
||
|
||
4. **[Git提交规范](./docs/git_commit_guide.md)** 🔄
|
||
- 提交信息格式标准
|
||
- 分支管理策略
|
||
- 代码审查流程
|
||
|
||
### 第二步：熟悉项目架构 🏗️
|
||
|
||
```
|
||
whaleTown/
|
||
├── 🎬 scenes/ # 游戏场景
|
||
│ ├── auth_scene.tscn # 🔐 用户认证场景
|
||
│ ├── main_scene.tscn # 🎮 主游戏场景
|
||
│ └── prefabs/ # 🧩 预制体组件
|
||
├── 🔧 core/ # 核心系统（自动加载）
|
||
│ ├── managers/ # 🎯 全局管理器
|
||
│ ├── systems/ # ⚙️ 系统组件
|
||
│ └── utils/ # 🛠️ 工具类
|
||
├── 📝 scripts/ # 业务逻辑脚本
|
||
│ ├── scenes/ # 🎬 场景脚本
|
||
│ ├── network/ # 🌐 网络相关
|
||
│ └── ui/ # 🎨 UI组件脚本
|
||
├── 🧩 module/ # 可复用模块
|
||
│ ├── UI/ # 🎨 UI组件模块
|
||
│ ├── Character/ # 👤 角色模块
|
||
│ ├── Combat/ # ⚔️ 战斗模块
|
||
│ ├── Dialogue/ # 💬 对话模块
|
||
│ └── Inventory/ # 🎒 背包模块
|
||
├── 🎨 assets/ # 游戏资源
|
||
│ ├── sprites/ # 🖼️ 精灵图资源
|
||
│ ├── audio/ # 🔊 音频文件
|
||
│ ├── ui/ # 🎨 UI界面资源
|
||
│ └── fonts/ # 🔤 字体资源
|
||
├── 📊 data/ # 配置数据
|
||
│ ├── configs/ # ⚙️ 游戏配置
|
||
│ ├── localization/ # 🌍 本地化文件
|
||
│ └── characters/ # 👤 角色数据
|
||
├── 🧪 tests/ # 测试文件
|
||
│ ├── api/ # 🔌 API接口测试
|
||
│ ├── auth/ # 🔐 认证UI测试
|
||
│ └── unit/ # 🧪 单元测试
|
||
└── 📚 docs/ # 项目文档
|
||
├── auth/ # 🔐 认证相关文档
|
||
└── api-documentation.md # 📖 API接口文档
|
||
```
|
||
|
||
**架构特点：**
|
||
- 🏗️ **模块化设计** - 按功能而非技术组织代码
|
||
- 🔄 **事件驱动** - 通过EventSystem实现组件间通信
|
||
- 📦 **清晰分层** - 场景层 → 业务层 → 核心层
|
||
- 🧪 **测试友好** - 完整的测试覆盖和文档
|
||
|
||
### 第三步：体验核心功能 🎮
|
||
|
||
1. **用户认证系统** 🔐
|
||
- 邮箱验证码注册
|
||
- 多方式登录（用户名/邮箱/手机号）
|
||
- 密码重置功能
|
||
|
||
2. **游戏核心系统** 🎮
|
||
- 场景管理和切换
|
||
- 角色状态管理
|
||
- 实时网络通信
|
||
|
||
3. **开发工具** 🛠️
|
||
- 内置测试场景
|
||
- API测试脚本
|
||
- 性能监控工具
|
||
|
||
### 第四步：开始贡献 🤝
|
||
|
||
1. **Fork项目** 到你的账户
|
||
2. **创建功能分支**：`git checkout -b feature/your-feature`
|
||
3. **遵循规范开发**（参考文档）
|
||
4. **添加测试用例**：确保功能正确性
|
||
5. **提交代码**：`git commit -m "feat：添加新功能"`
|
||
6. **创建Pull Request**
|
||
|
||
---
|
||
|
||
## <20>[️ 技术栈
|
||
|
||
### 🎮 游戏引擎
|
||
- **Godot Engine** `4.5.1` - 开源游戏引擎，支持2D/3D开发
|
||
- **GDScript** - Godot专用脚本语言，Python风格语法
|
||
- **Forward Plus** - 现代渲染管线，支持高质量光照
|
||
|
||
### 🏗️ 架构设计
|
||
- **模块化架构** - 按功能组织的可复用组件系统
|
||
- **事件驱动** - 基于EventSystem的松耦合通信
|
||
- **单例管理器** - GameManager、SceneManager等全局管理器
|
||
- **状态机模式** - 游戏状态和角色状态管理
|
||
|
||
### 🌐 网络通信
|
||
- **RESTful API** - 标准HTTP接口通信
|
||
- **JSON数据格式** - 轻量级数据交换格式
|
||
- **WebSocket** - 实时双向通信支持
|
||
- **错误处理** - 完整的网络异常处理机制
|
||
|
||
### 🎨 UI系统
|
||
- **响应式设计** - 支持多分辨率自适应
|
||
- **主题系统** - 统一的UI风格管理
|
||
- **动画系统** - 流畅的界面过渡效果
|
||
- **本地化支持** - 多语言界面切换
|
||
|
||
### 🧪 测试框架
|
||
- **Godot内置测试** - 场景和组件测试
|
||
- **Python测试脚本** - API接口自动化测试
|
||
- **性能监控** - 帧率和内存使用监控
|
||
- **错误追踪** - 完整的日志和错误报告
|
||
|
||
### 📱 跨平台支持
|
||
- **桌面平台** - Windows、Linux、macOS
|
||
- **移动平台** - Android、iOS（规划中）
|
||
- **Web平台** - HTML5导出支持（规划中）
|
||
|
||
---
|
||
|
||
## 🏗️ 核心功能
|
||
|
||
### 🔐 用户认证系统 (scenes/auth_scene.tscn)
|
||
- **多方式登录** - 用户名/邮箱/手机号
|
||
- **邮箱验证** - 完整的验证码流程和倒计时
|
||
- **密码安全** - 强度验证和安全提示
|
||
- **错误处理** - 友好的错误提示和状态管理
|
||
- **响应式UI** - 自适应布局和动画效果
|
||
|
||
### 🎮 游戏核心系统 (core/)
|
||
- **GameManager** - 全局游戏状态管理（LOADING、AUTH、IN_GAME等）
|
||
- **SceneManager** - 场景切换和生命周期管理
|
||
- **EventSystem** - 全局事件通信系统
|
||
- **StringUtils** - 字符串处理工具集
|
||
|
||
### 🧩 模块化组件 (module/)
|
||
- **UI组件** - 可复用的界面组件和动画
|
||
- **角色系统** - 角色数据和行为管理
|
||
- **战斗系统** - 战斗逻辑和技能系统
|
||
- **对话系统** - 对话树和文本显示
|
||
- **背包系统** - 物品管理和交互
|
||
|
||
### 🌐 网络通信 (scripts/network/)
|
||
- **API集成** - RESTful接口调用封装
|
||
- **实时通信** - WebSocket连接管理
|
||
- **数据同步** - 客户端服务器数据同步
|
||
- **离线处理** - 网络异常和离线模式
|
||
|
||
### 🧪 测试体系 (tests/)
|
||
- **API测试** - 完整的接口功能测试
|
||
- **UI测试** - 交互式界面测试场景
|
||
- **单元测试** - 组件和函数级别测试
|
||
- **集成测试** - 完整业务流程测试
|
||
- **性能测试** - 帧率和内存性能监控
|
||
|
||
---
|
||
|
||
## 📊 开发与测试
|
||
|
||
### 🔧 开发命令
|
||
|
||
```bash
|
||
# 启动Godot编辑器
|
||
godot --editor
|
||
|
||
# 运行项目（无编辑器）
|
||
godot --main-pack game.pck
|
||
|
||
# 导出项目
|
||
godot --export "Windows Desktop" game.exe
|
||
|
||
# 运行测试
|
||
godot --headless --script tests/run_tests.gd
|
||
```
|
||
|
||
### 🧪 测试命令
|
||
|
||
```bash
|
||
# API接口测试
|
||
python tests/api/simple_api_test.py
|
||
|
||
# 完整功能测试
|
||
python tests/api/api_test.py --verbose
|
||
|
||
# 自定义服务器测试
|
||
python tests/api/simple_api_test.py https://your-server.com
|
||
|
||
# UI交互测试
|
||
# 在Godot编辑器中运行 tests/auth/auth_ui_test.tscn
|
||
```
|
||
|
||
### 📈 测试覆盖率
|
||
- **API测试**: 17个接口全覆盖 ✅
|
||
- **UI测试**: 认证流程完整测试 ✅
|
||
- **错误处理**: 边界条件和异常测试 ✅
|
||
- **性能测试**: 帧率和内存监控 ✅
|
||
|
||
---
|
||
|
||
## 🌍 部署配置
|
||
|
||
### 开发环境（默认）
|
||
```bash
|
||
# 本地开发配置
|
||
API_BASE_URL=http://localhost:3000
|
||
DEBUG_MODE=true
|
||
LOG_LEVEL=debug
|
||
```
|
||
|
||
### 生产环境
|
||
```bash
|
||
# 生产环境配置
|
||
API_BASE_URL=https://your-api-server.com
|
||
DEBUG_MODE=false
|
||
LOG_LEVEL=info
|
||
ENABLE_ANALYTICS=true
|
||
```
|
||
|
||
### 导出设置
|
||
- **Windows**: 64位可执行文件
|
||
- **Linux**: AppImage格式
|
||
- **macOS**: .app应用包
|
||
- **Android**: APK安装包（规划中）
|
||
|
||
---
|
||
|
||
## 📚 文档中心
|
||
|
||
### 🎯 新手必读
|
||
1. **[项目结构详解](./docs/project_structure.md)** - 架构设计和组织规则
|
||
2. **[命名规范](./docs/naming_convention.md)** - 代码和资源命名标准
|
||
3. **[代码注释规范](./docs/code_comment_guide.md)** - 注释标准和AI辅助
|
||
4. **[Git提交规范](./docs/git_commit_guide.md)** - 版本控制最佳实践
|
||
|
||
### 📖 功能文档
|
||
- **[用户认证系统](./docs/auth/)** - 认证流程和界面设计
|
||
- **[API接口文档](./docs/api-documentation.md)** - 完整的API使用指南
|
||
- **[测试指南](./tests/api/README.md)** - 测试用例和使用方法
|
||
|
||
### 🏗️ 开发指南
|
||
- **[模块开发指南](./docs/module_development.md)** - 如何创建新模块
|
||
- **[场景设计规范](./docs/scene_design.md)** - 场景架构和最佳实践
|
||
- **[性能优化指南](./docs/performance_guide.md)** - 性能调优技巧
|
||
|
||
---
|
||
|
||
## 🤝 贡献者
|
||
|
||
感谢所有为项目做出贡献的开发者！
|
||
|
||
### 🏆 核心团队
|
||
- **[moyin](https://gitea.xinghangee.icu/moyin)** - 核心开发者
|
||
- **[jianuo](https://gitea.xinghangee.icu/jianuo)** - 核心开发者
|
||
- **[angjustinl](https://gitea.xinghangee.icu/ANGJustinl)** - 核心开发者
|
||
|
||
查看完整贡献者名单：[docs/CONTRIBUTORS.md](./docs/CONTRIBUTORS.md)
|
||
|
||
### 🌟 如何贡献
|
||
|
||
我们欢迎所有形式的贡献：
|
||
|
||
1. **🐛 Bug修复** - 发现并修复问题
|
||
2. **✨ 新功能** - 添加有价值的功能
|
||
3. **📚 文档改进** - 完善项目文档
|
||
4. **🧪 测试用例** - 提高代码覆盖率
|
||
5. **🎨 UI/UX改进** - 提升用户体验
|
||
6. **⚡ 性能优化** - 优化游戏性能
|
||
|
||
**贡献流程：**
|
||
1. Fork项目 → 2. 创建分支 → 3. 开发功能 → 4. 提交PR
|
||
|
||
---
|
||
|
||
## 📞 联系我们
|
||
|
||
- **项目地址**: [Gitea Repository](https://gitea.xinghangee.icu/datawhale/whale-town)
|
||
- **问题反馈**: [Issues](https://gitea.xinghangee.icu/datawhale/whale-town/issues)
|
||
- **功能建议**: [Discussions](https://gitea.xinghangee.icu/datawhale/whale-town/discussions)
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用 [MIT License](./LICENSE) 开源协议。
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
**🐋 Whale Town - 让像素世界更精彩！**
|
||
|
||
Made with ❤️ by the Whale Town Team
|
||
|
||
[⭐ Star](https://gitea.xinghangee.icu/datawhale/whale-town) | [🍴 Fork](https://gitea.xinghangee.icu/datawhale/whale-town/fork) | [📖 Docs](./docs/) | [🐛 Issues](https://gitea.xinghangee.icu/datawhale/whale-town/issues)
|
||
|
||
</div>
|
||
=======
|
||
- ✅ 基础架构搭建完成
|
||
- ✅ 项目结构重构完成（2025-12-31）
|
||
- ✅ 用户认证系统完成
|
||
- ✅ API接口集成完成
|
||
- ✅ 测试体系建立完成
|
||
- ✅ 文档体系完善
|
||
- 🚧 游戏核心玩法开发中
|
||
- 🚧 更多功能模块开发中
|
||
|
||
**最后更新**: 2025-12-31
|
||
|
||
**重要更新**: 项目已完成架构重构，采用新的分层结构。详见 [REFACTORING.md](REFACTORING.md)
|
||
>>>>>>> whale-town-front/main
|