# 🐋 Whale Town - 像素游戏前端客户端

> 一个基于 Godot 4.5 引擎开发的现代化 2D 像素风游戏前端，采用模块化架构设计，集成完整的用户认证系统、实时通信和游戏核心功能。

[![Godot](https://img.shields.io/badge/Godot-4.5.1-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)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)](https://godotengine.org/download)

## 🎯 项目简介

Whale Town 是一个功能完整的像素游戏前端客户端，采用模块化架构设计：

- 🔐 **用户认证系统** - 完整的登录、注册、密码管理、邮箱验证界面
- 🎮 **游戏核心功能** - 角色系统、战斗系统、对话系统、背包系统
- 🌐 **实时通信** - WebSocket集成，支持实时多人交互
- 🎨 **现代化UI** - 响应式界面设计，支持多分辨率适配
- 🧪 **完整测试体系** - UI测试、API测试、性能测试全覆盖
- 📱 **跨平台支持** - Windows、Linux、macOS、移动端
- 🔧 **模块化架构** - 高度解耦的组件系统，易于扩展和维护

---

## 🚀 快速开始

### 📋 环境要求

- **Godot Engine** >= 4.5.0 (推荐 4.5.1)(https://godotengine.org/download)
- **Python** >= 3.7.0 (用于API测试，可选)
- **Git** >= 2.0.0

### 🛠️ 安装与运行

```bash
# 1. 克隆项目
git clone <repository-url>
cd whale-town

# 2. 使用Godot编辑器打开项目
# 双击 project.godot 文件或在Godot编辑器中导入项目

# 3. 运行项目
# 按F5或点击"运行"按钮启动游戏
```

🎉 **游戏启动成功！** 进入认证界面开始体验

### 🧪 快速测试

```bash
# API接口测试
python tests/api/simple_api_test.py

# 完整功能测试
python tests/api/api_test.py --verbose
```

**测试内容：**
- ✅ 用户认证流程测试
- ✅ API接口连通性测试
- ✅ 错误处理和边界条件测试
- ✅ 网络通信功能测试

---

## 🎓 新开发者指南

### 第一步：了解项目规范 📚

**⚠️ 重要：在开始开发前，请务必阅读以下文档**

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**

---

## �[️ 技术栈

### 🎮 游戏引擎
- **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>