forked from datawhale/whale-town-front
302 lines
10 KiB
Markdown
302 lines
10 KiB
Markdown
# 🐋 whaleTown
|
||
|
||
一个使用 Godot 4.5 引擎开发的现代化像素游戏项目，集成了完整的用户认证系统和API接口。
|
||
|
||
## 🎮 项目信息
|
||
|
||
- **引擎版本**: Godot 4.5.1
|
||
- **渲染器**: Forward Plus
|
||
- **项目类型**: 2D 像素游戏
|
||
- **架构模式**: 模块化 + 事件驱动
|
||
- **后端集成**: RESTful API + 用户认证
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 环境要求
|
||
- [Godot Engine 4.5+](https://godotengine.org/download)
|
||
- Python 3.7+ (用于API测试和Web服务器)
|
||
|
||
### 运行项目
|
||
```bash
|
||
# 1. 克隆项目
|
||
git clone <repository-url>
|
||
cd whale-town
|
||
|
||
# 2. 使用Godot编辑器打开项目
|
||
# 3. 按F5运行或点击"运行"按钮
|
||
|
||
# 4. 测试API接口（可选）
|
||
python tests/api/simple_api_test.py
|
||
```
|
||
|
||
### Web版本部署
|
||
```bash
|
||
# Windows用户
|
||
scripts\build_web.bat # 导出Web版本
|
||
scripts\serve_web.bat # 启动本地测试服务器
|
||
|
||
# Linux/macOS用户
|
||
./scripts/build_web.sh # 导出Web版本
|
||
./scripts/serve_web.sh # 启动本地测试服务器
|
||
```
|
||
|
||
详细部署指南请查看: [Web部署完整指南](docs/web_deployment_guide.md)
|
||
|
||
## 🏗️ 项目架构
|
||
|
||
### 核心设计理念
|
||
- **场景独立性** - 每个场景都是独立的功能模块
|
||
- **高度解耦** - 通过事件系统和管理器通信
|
||
- **组件复用** - 可复用组件统一管理
|
||
- **标准化** - 统一的命名规范和目录结构
|
||
- **测试驱动** - 完整的测试体系和文档
|
||
|
||
### 目录结构
|
||
```
|
||
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提交规范
|
||
```
|
||
|
||
### 核心系统
|
||
项目包含以下自动加载的核心系统：
|
||
|
||
- **GameManager** - 全局游戏状态管理
|
||
- **SceneManager** - 场景切换管理
|
||
- **EventSystem** - 事件通信系统
|
||
|
||
使用示例：
|
||
```gdscript
|
||
# 状态管理
|
||
GameManager.change_state(GameManager.GameState.IN_GAME)
|
||
|
||
# 场景切换
|
||
SceneManager.change_scene("battle")
|
||
|
||
# 事件通信
|
||
EventSystem.emit_event("player_health_changed", 80)
|
||
EventSystem.connect_event("player_died", _on_player_died)
|
||
```
|
||
|
||
## ✨ 主要功能
|
||
|
||
### 🔐 用户认证系统
|
||
- **用户注册** - 支持邮箱验证码验证
|
||
- **用户登录** - 多种登录方式（用户名/邮箱/手机号）
|
||
- **密码管理** - 密码重置和修改功能
|
||
- **GitHub OAuth** - 第三方登录集成
|
||
- **错误处理** - 完整的错误提示和频率限制
|
||
|
||
### 🌐 Web版本部署
|
||
- **自动化导出** - 一键导出Web版本
|
||
- **本地测试服务器** - 内置HTTP服务器用于测试
|
||
- **生产环境配置** - 完整的服务器配置指南
|
||
- **跨平台支持** - Windows、Linux、macOS全平台支持
|
||
- **性能优化** - 资源压缩和加载优化
|
||
|
||
### 🎮 游戏功能
|
||
- **主场景** - 游戏主界面和菜单系统
|
||
- **认证场景** - 完整的登录注册界面
|
||
- **状态管理** - 用户状态和游戏状态管理
|
||
- **网络通信** - RESTful API集成
|
||
|
||
### 🧪 测试体系
|
||
- **API测试** - 完整的接口测试脚本
|
||
- **UI测试** - 认证界面的交互测试
|
||
- **错误场景** - 边界条件和异常处理测试
|
||
|
||
## 🔧 开发规范
|
||
|
||
### 命名规范
|
||
- **场景文件**: `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/` 创建场景文件
|
||
2. 在 `scripts/scenes/` 创建对应脚本
|
||
3. 在 `SceneManager` 中注册场景路径
|
||
4. 使用 `SceneManager.change_scene()` 切换
|
||
|
||
### 创建可复用组件
|
||
1. 在 `module/` 对应分类下创建组件
|
||
2. 实现标准接口
|
||
3. 通过 `EventSystem` 与其他模块通信
|
||
4. 在 `scenes/prefabs/` 创建预制体
|
||
|
||
### 资源管理
|
||
- 图片资源放入 `assets/sprites/` 对应分类
|
||
- 音频文件放入 `assets/audio/` 对应分类
|
||
- UI资源放入 `assets/ui/` 对应分类
|
||
- 配置文件放入 `data/configs/`
|
||
- 遵循命名规范，使用英文小写+下划线
|
||
|
||
### API接口测试
|
||
项目提供了完整的Python测试脚本来验证API接口：
|
||
|
||
```bash
|
||
# 快速测试API连通性
|
||
python tests/api/simple_api_test.py
|
||
|
||
# 完整的API功能测试
|
||
python tests/api/api_test.py --verbose
|
||
|
||
# 自定义服务器地址测试
|
||
python tests/api/simple_api_test.py https://your-api-server.com
|
||
```
|
||
|
||
测试脚本会验证：
|
||
- ✅ 应用状态检查
|
||
- ✅ 用户注册和登录功能
|
||
- ✅ 邮箱验证码发送和验证
|
||
- ✅ 错误处理和频率限制（429错误）
|
||
- ✅ 管理员功能和权限控制
|
||
- ✅ 用户状态管理
|
||
- ✅ 安全功能测试
|
||
|
||
📖 查看 [API测试文档](tests/api/README.md) 了解详细使用方法
|
||
|
||
### 认证UI测试
|
||
项目还提供了Godot内置的UI测试场景：
|
||
|
||
1. 在Godot编辑器中打开 `tests/auth/auth_ui_test.tscn`
|
||
2. 运行场景进行交互式测试
|
||
3. 测试各种错误场景和边界条件
|
||
|
||
📖 查看 [认证UI测试文档](tests/auth/README.md) 了解详细使用方法
|
||
|
||
## 🔧 技术栈
|
||
|
||
- **游戏引擎**: Godot 4.5.1
|
||
- **脚本语言**: GDScript
|
||
- **架构模式**: 模块化 + 事件驱动
|
||
- **状态管理**: 单例管理器模式
|
||
- **通信机制**: 全局事件系统
|
||
- **API集成**: RESTful API + JSON
|
||
- **测试框架**: Python + Godot内置测试
|
||
|
||
## 🤝 贡献指南
|
||
|
||
1. Fork 项目
|
||
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
|
||
3. 遵循项目的命名规范和架构设计
|
||
4. 添加相应的测试用例
|
||
5. 更新相关文档
|
||
6. 提交更改 (`git commit -m 'feat：添加某个功能'`)
|
||
7. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||
8. 开启 Pull Request
|
||
|
||
### 贡献类型
|
||
- 🐛 Bug修复
|
||
- ✨ 新功能开发
|
||
- 📚 文档改进
|
||
- 🧪 测试用例
|
||
- 🎨 UI/UX改进
|
||
- ⚡ 性能优化
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情
|
||
|
||
---
|
||
|
||
## 🎯 项目状态
|
||
|
||
- ✅ 基础架构搭建完成
|
||
- ✅ 用户认证系统完成
|
||
- ✅ API接口集成完成
|
||
- ✅ 测试体系建立完成
|
||
- ✅ 文档体系完善
|
||
- 🚧 游戏核心玩法开发中
|
||
- 🚧 更多功能模块开发中
|
||
|
||
**最后更新**: 2025-12-24
|