# 🐋 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)** - 配置开发环境

### 🎯 第二步：学习规范

**代码质量保证**

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-功能模块/           # 🎮 功能文档
├── 🎬 scenes/                # 🎭 游戏场景
│   ├── Maps/                 # 🗺️ 地图场景
│   └── Components/           # 🧩 组件预制体
├── 🔧 _Core/                 # ⚙️ 核心系统
│   ├── managers/             # 🎯 全局管理器
│   ├── systems/              # 🔄 系统组件
│   ├── EventNames.gd         # 📝 事件名称定义
│   └── ProjectPaths.gd       # 📂 路径统一管理
├── 🎨 UI/                    # 🖼️ 用户界面
│   └── Windows/              # 🪟 窗口界面
├── 🔨 Utils/                 # 🔨 工具类
├── 🎮 module/                # 🧩 功能模块
├── 🎨 assets/                # 🖼️ 游戏资源
├── ⚙️ Config/                # 📋 配置文件
├── 🧪 tests/                 # 🔬 测试文件
└── 🌐 web_assets/            # 🌍 Web部署资源
```

### 🔧 核心组件

| 组件 | 作用 | 文档链接 |
|------|------|----------|
| **EventSystem** | 全局事件通信 | [架构规范](docs/02-开发规范/架构与通信规范.md) |
| **GameManager** | 游戏状态管理 | [实现细节](docs/03-技术实现/实现细节规范.md) |
| **SceneManager** | 场景切换管理 | [场景设计](docs/04-高级开发/场景设计规范.md) |
| **NetworkManager** | 网络请求管理 | [网络管理器](docs/03-技术实现/网络管理器设置.md) |
| **ProjectPaths** | 路径统一管理 | [项目结构](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>