datawhale/whale-town-front
3
2
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f527fa3c3888914986e80ea2385c48db5c1394a4
whale-town-front/README.md
moyin fa360e1c78 docs：更新项目文档以反映新的结构变更 
- 更新 README.md 中的项目结构说明
- 修订项目结构说明文档，反映最新的目录组织
- 确保文档与实际项目结构保持同步
2026-01-02 00:59:25 +08:00

395 lines
14 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 🐋 WhaleTown - 现代化像素游戏
> 一个基于 Godot 4.5 引擎开发的企业级 2D 像素风游戏，采用模块化架构设计，集成完整的用户认证系统和游戏核心功能。
[![Godot](https://img.shields.io/badge/Godot-4.5+-blue.svg)](https://godotengine.org/)
[![GDScript](https://img.shields.io/badge/GDScript-Latest-green.svg)](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/index.html)
[![Documentation](https://img.shields.io/badge/Documentation-Complete-brightgreen.svg)](./docs/)
[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS%20%7C%20Web-lightgrey.svg)](https://godotengine.org/download)
## 🎯 项目简介
WhaleTown 是一个功能完整的现代化像素游戏，具有以下特色：
- 🏗️ **企业级架构** - 模块化设计，高度解耦，易于扩展
- 🔐 **完整认证系统** - 登录、注册、邮箱验证、密码管理
- 🎮 **丰富游戏功能** - 角色系统、场景管理、事件通信
- 🌐 **网络通信** - RESTful API集成，支持实时数据交互
- 📚 **企业级文档** - 18个文档，覆盖开发全流程
- 🧪 **完整测试体系** - API测试、UI测试、性能测试
- 🚀 **一键部署** - 支持Web、桌面多平台发布
---
## 🚀 5分钟快速体验
### 📋 准备工作
**你需要安装：**
- [Godot Engine 4.5+](https://godotengine.org/download) - 游戏引擎
- [Git](https://git-scm.com/) - 版本控制工具
### 🛠️ 启动项目
```bash
# 1️⃣ 获取项目
git clone <repository-url>
cd whale-town
# 2️⃣ 打开项目
# 双击 project.godot 文件，或在Godot编辑器中选择"导入项目"
# 3️⃣ 运行游戏
# 在Godot编辑器中按 F5 或点击"运行项目"按钮
```
🎉 **成功！** 你应该看到游戏的认证界面
### 🎮 体验功能
1. **注册新用户** - 体验完整的邮箱验证流程
2. **登录系统** - 尝试用户名/邮箱登录
3. **游戏界面** - 探索主游戏场景
### 🧪 测试API（可选）
```bash
# 安装Python依赖
pip install requests
# 快速API测试
python tests/api/quick_test.py
# 完整功能测试
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编程助手专用文档
### 🎯 第二步：学习规范
**代码质量保证**
1. **[📝 命名规范](docs/02-开发规范/命名规范.md)** - 统一命名标准
2. **[🏛️ 架构与通信规范](docs/02-开发规范/架构与通信规范.md)** - 组件通信方式
3. **[💬 代码注释规范](docs/02-开发规范/代码注释规范.md)** - 注释标准
4. **[🔄 Git提交规范](docs/02-开发规范/Git提交规范.md)** - 版本控制规范
### 🎯 第三步：开始开发
**技术实现指导**
1. **[🔧 实现细节规范](docs/03-技术实现/实现细节规范.md)** - 游戏对象实现
2. **[🌐 API接口文档](docs/03-技术实现/API接口文档.md)** - 后端接口使用
3. **[🧪 测试指南](docs/03-技术实现/测试指南.md)** - 测试方法和工具
### 🎯 第四步：高级开发
**进阶技能**
1. **[🚀 性能优化指南](docs/04-高级开发/性能优化指南.md)** - 性能调优
2. **[🎬 场景设计规范](docs/04-高级开发/场景设计规范.md)** - 场景架构
3. **[🧩 模块开发指南](docs/04-高级开发/模块开发指南.md)** - 模块化开发
### 🎯 第五步：项目发布
**部署和运维**
1. **[🌐 Web部署指南](docs/05-部署运维/Web部署指南.md)** - 完整部署流程
---
## 🏗️ 项目架构一览
### 📁 目录结构
```
WhaleTown/ # 🐋 项目根目录
├── 📚 docs/ # 📖 完整文档系统（18个文档）
│ ├── 01-项目入门/ # 👋 新人必读
│ ├── 02-开发规范/ # 📋 编码标准
│ ├── 03-技术实现/ # 🔧 开发指导
│ ├── 04-高级开发/ # 🚀 进阶技巧
│ ├── 05-部署运维/ # 🌐 发布部署
│ ├── 06-功能模块/ # 🎮 功能文档
│ └── AI_docs/ # 🤖 AI专用文档（执行规范、代码模板）
├── 🔧 _Core/ # ⚙️ 核心底层实现
│ ├── managers/ # 🎯 全局管理器（游戏状态、场景、网络等）
│ ├── systems/ # 🔄 系统组件（事件系统、输入系统等）
│ ├── components/ # 🧩 基础组件实现
│ ├── utils/ # <20> 核件心工具类（字符串处理、数学计算等）
│ ├── EventNames.gd # 📝 事件名称定义
│ └── ProjectPaths.gd # <20> 路径组统一管理
├── 🎬 scenes/ # 🎭 场景与视觉呈现
│ ├── maps/ # <20>️ 地图一场景（游戏关卡、世界地图）
│ ├── 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脚本
```
### 🔧 核心架构说明
| 目录 | 作用 | 详细说明 |
|------|------|----------|
| **_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) |
---
## 🎮 核心功能
### 🔐 用户认证系统
**完整的用户管理功能**
- ✅ 用户注册（用户名+邮箱验证）
- ✅ 多方式登录（用户名/邮箱/验证码）
- ✅ 密码管理（修改/重置）
- ✅ 表单验证（实时验证+友好提示）
- ✅ 错误处理（网络异常+业务错误）
**技术特色**
- 📱 响应式UI设计
- 🔄 实时表单验证
- ⏰ 验证码冷却机制
- 🎨 流畅动画效果
### 🎮 游戏核心系统
**模块化游戏架构**
- 🎭 场景管理系统
- 🔄 事件通信系统
- 🎯 状态管理系统
- 🌐 网络通信系统
**开发友好特性**
- 🧩 高度模块化
- 📝 完整文档覆盖
- 🧪 测试用例齐全
- 🔧 开发工具完善
---
## 🧪 测试系统
### 🔬 测试类型
| 测试类型 | 工具 | 覆盖范围 | 文档 |
|----------|------|----------|------|
| **API测试** | Python脚本 | 17个接口全覆盖 | [测试指南](docs/03-技术实现/测试指南.md) |
| **UI测试** | Godot场景 | 认证流程完整测试 | [认证测试](docs/06-功能模块/auth/认证测试指南.md) |
| **单元测试** | GUT框架 | 核心组件测试 | [测试指南](docs/03-技术实现/测试指南.md) |
### 🚀 快速测试
```bash
# 🔌 API接口测试（30秒）
python tests/api/quick_test.py
# 🔍 完整功能测试（2-3分钟）
python tests/api/api_client_test.py
# 🎮 UI交互测试（在Godot中运行）
# 打开 tests/auth/auth_ui_test.tscn 场景
```
---
## 🚀 部署发布
### 🖥️ 桌面版本
```bash
# Windows
godot --export "Windows Desktop" build/WhaleTown.exe
# Linux
godot --export "Linux/X11" build/WhaleTown.x86_64
# macOS
godot --export "macOS" build/WhaleTown.app
```
### 🌐 Web版本
```bash
# 使用自动化脚本
scripts/build_web.bat # Windows
scripts/build_web.sh # Linux/macOS
# 本地测试
scripts/serve_web.bat # 启动本地服务器
```
**详细部署流程**: [Web部署指南](docs/05-部署运维/Web部署指南.md)
---
## 📊 项目统计
### 📚 文档系统
| 类别 | 文档数 | 完成度 |
|------|--------|--------|
| 项目入门 | 3 | 100% |
| 开发规范 | 5 | 100% |
| 技术实现 | 4 | 100% |
| 高级开发 | 3 | 100% |
| 部署运维 | 1 | 100% |
| 功能模块 | 2 | 100% |
| **总计** | **18** | **100%** |
### 🧪 测试覆盖
- **API接口**: 17个接口 ✅
- **认证流程**: 完整测试 ✅
- **错误处理**: 边界测试 ✅
- **性能监控**: 帧率/内存 ✅
---
## 🤝 参与贡献
### 🌟 贡献方式
1. **🐛 Bug修复** - 发现并修复问题
2. **✨ 新功能** - 添加有价值的功能
3. **📚 文档改进** - 完善项目文档
4. **🧪 测试用例** - 提高代码覆盖率
5. **🎨 UI/UX改进** - 提升用户体验
### 📋 贡献流程
```bash
# 1️⃣ Fork项目到你的账户
# 2️⃣ 克隆到本地
git clone <your-fork-url>
cd whale-town
# 3️⃣ 创建功能分支
git checkout -b feature/your-feature
# 4️⃣ 开发功能（遵循项目规范）
# 参考: docs/02-开发规范/
# 5️⃣ 添加测试用例
# 参考: docs/03-技术实现/测试指南.md
# 6️⃣ 提交代码
git commit -m "feat：添加新功能"
# 参考: docs/02-开发规范/Git提交规范.md
# 7️⃣ 推送分支
git push origin feature/your-feature
# 8️⃣ 创建Pull Request
```
### 📖 开发规范
**必读文档**：
- [命名规范](docs/02-开发规范/命名规范.md) - 代码命名标准
- [Git提交规范](docs/02-开发规范/Git提交规范.md) - 提交信息格式
- [代码注释规范](docs/02-开发规范/代码注释规范.md) - 注释标准
### 🙏 贡献者致谢
感谢所有为 WhaleTown 项目做出贡献的开发者们！详细的贡献者信息和统计请查看：
**[📖 贡献者详细信息](docs/CONTRIBUTORS.md)**
---
## 📞 获取帮助
### 🔍 问题解决
| 问题类型 | 解决方案 |
|----------|----------|
| **🤔 不知道从哪开始** | [项目入门总览](docs/01-项目入门/README.md) |
| **🏗️ 不理解项目架构** | [项目结构说明](docs/01-项目入门/项目结构说明.md) |
| **🔧 开发环境问题** | [项目设置指南](docs/01-项目入门/项目设置指南.md) |
| **📝 不知道怎么命名** | [命名规范](docs/02-开发规范/命名规范.md) |
| **🔄 组件通信问题** | [架构与通信规范](docs/02-开发规范/架构与通信规范.md) |
| **🌐 API调用问题** | [API接口文档](docs/03-技术实现/API接口文档.md) |
| **🧪 测试相关问题** | [测试指南](docs/03-技术实现/测试指南.md) |
| **🚀 部署发布问题** | [Web部署指南](docs/05-部署运维/Web部署指南.md) |
### 📚 文档导航
- **[📖 完整文档中心](docs/README.md)** - 所有文档的导航页面
- **[📋 文档更新日志](docs/CHANGELOG.md)** - 文档版本变更记录
### 💬 联系方式
- **项目地址**: [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">
**🐋 WhaleTown - 企业级像素游戏开发框架**
*让游戏开发更简单，让代码质量更优秀*
[⭐ Star](https://gitea.xinghangee.icu/datawhale/whale-town) | [🍴 Fork](https://gitea.xinghangee.icu/datawhale/whale-town/fork) | [📖 文档](./docs/) | [🐛 反馈](https://gitea.xinghangee.icu/datawhale/whale-town/issues)
**文档版本**: v1.2.0 | **最后更新**: 2025-12-31
</div>
Reference in New Issue View Git Blame Copy Permalink