🐋 WhaleTown - 现代化像素游戏
一个基于 Godot 4.5 引擎开发的企业级 2D 像素风游戏，采用模块化架构设计，集成完整的用户认证系统和游戏核心功能。
🎯 项目简介
WhaleTown 是一个功能完整的现代化像素游戏，具有以下特色：
- 🏗️ 企业级架构 - 模块化设计，高度解耦，易于扩展
- 🔐 完整认证系统 - 登录、注册、邮箱验证、密码管理
- 🎮 丰富游戏功能 - 角色系统、场景管理、事件通信
- 🌐 网络通信 - RESTful API集成，支持实时数据交互
- 📚 企业级文档 - 18个文档，覆盖开发全流程
- 🧪 完整测试体系 - API测试、UI测试、性能测试
- 🚀 一键部署 - 支持Web、桌面多平台发布
🚀 5分钟快速体验
📋 准备工作
你需要安装：
- Godot Engine 4.5+ - 游戏引擎
- Git - 版本控制工具
🛠️ 启动项目
# 1️⃣ 获取项目
git clone <repository-url>
cd whale-town
# 2️⃣ 打开项目
# 双击 project.godot 文件，或在Godot编辑器中选择"导入项目"
# 3️⃣ 运行游戏
# 在Godot编辑器中按 F5 或点击"运行项目"按钮
🎉 成功！ 你应该看到游戏的认证界面
🎮 体验功能
- 注册新用户 - 体验完整的邮箱验证流程
- 登录系统 - 尝试用户名/邮箱登录
- 游戏界面 - 探索主游戏场景
🧪 测试API（可选）
# 安装Python依赖
pip install requests
# 快速API测试
python tests/api/quick_test.py
# 完整功能测试
python tests/api/api_client_test.py
📚 新手开发指南
🎯 第一步：了解项目
⚠️ 重要：开始开发前必读
🎯 第二步：学习规范
代码质量保证
- 📝 命名规范 - 统一命名标准
- 🏛️ 架构与通信规范 - 组件通信方式
- 💬 代码注释规范 - 注释标准
- 🔄 Git提交规范 - 版本控制规范
🎯 第三步：开始开发
技术实现指导
🎯 第四步：高级开发
进阶技能
🎯 第五步：项目发布
部署和运维
- 🌐 Web部署指南 - 完整部署流程
🏗️ 项目架构一览
📁 目录结构
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/ | 全局事件通信系统 | 架构规范 |
| GameManager | _Core/managers/ | 游戏状态管理器 | 实现细节 |
| SceneManager | _Core/managers/ | 场景切换管理器 | 场景设计 |
| NetworkManager | _Core/managers/ | 网络请求管理器 | 网络管理器 |
| ProjectPaths | _Core/ | 路径统一管理工具 | 项目结构 |
🎮 核心功能
🔐 用户认证系统
完整的用户管理功能
- ✅ 用户注册（用户名+邮箱验证）
- ✅ 多方式登录（用户名/邮箱/验证码）
- ✅ 密码管理（修改/重置）
- ✅ 表单验证（实时验证+友好提示）
- ✅ 错误处理（网络异常+业务错误）
技术特色
- 📱 响应式UI设计
- 🔄 实时表单验证
- ⏰ 验证码冷却机制
- 🎨 流畅动画效果
🎮 游戏核心系统
模块化游戏架构
- 🎭 场景管理系统
- 🔄 事件通信系统
- 🎯 状态管理系统
- 🌐 网络通信系统
开发友好特性
- 🧩 高度模块化
- 📝 完整文档覆盖
- 🧪 测试用例齐全
- 🔧 开发工具完善
🧪 测试系统
🔬 测试类型
| 测试类型 | 工具 | 覆盖范围 | 文档 |
|---|---|---|---|
| API测试 | Python脚本 | 17个接口全覆盖 | 测试指南 |
| UI测试 | Godot场景 | 认证流程完整测试 | 认证测试 |
| 单元测试 | GUT框架 | 核心组件测试 | 测试指南 |
🚀 快速测试
# 🔌 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 场景
🚀 部署发布
🖥️ 桌面版本
# 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版本
# 使用自动化脚本
scripts/build_web.bat # Windows
scripts/build_web.sh # Linux/macOS
# 本地测试
scripts/serve_web.bat # 启动本地服务器
详细部署流程: Web部署指南
📊 项目统计
📚 文档系统
| 类别 | 文档数 | 完成度 |
|---|---|---|
| 项目入门 | 3 | 100% |
| 开发规范 | 5 | 100% |
| 技术实现 | 4 | 100% |
| 高级开发 | 3 | 100% |
| 部署运维 | 1 | 100% |
| 功能模块 | 2 | 100% |
| 总计 | 18 | 100% |
🧪 测试覆盖
- API接口: 17个接口 ✅
- 认证流程: 完整测试 ✅
- 错误处理: 边界测试 ✅
- 性能监控: 帧率/内存 ✅
🤝 参与贡献
🌟 贡献方式
- 🐛 Bug修复 - 发现并修复问题
- ✨ 新功能 - 添加有价值的功能
- 📚 文档改进 - 完善项目文档
- 🧪 测试用例 - 提高代码覆盖率
- 🎨 UI/UX改进 - 提升用户体验
📋 贡献流程
# 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
📖 开发规范
必读文档：
🙏 贡献者致谢
感谢所有为 WhaleTown 项目做出贡献的开发者们！详细的贡献者信息和统计请查看：
📞 获取帮助
🔍 问题解决
| 问题类型 | 解决方案 |
|---|---|
| 🤔 不知道从哪开始 | 项目入门总览 |
| 🏗️ 不理解项目架构 | 项目结构说明 |
| 🔧 开发环境问题 | 项目设置指南 |
| 📝 不知道怎么命名 | 命名规范 |
| 🔄 组件通信问题 | 架构与通信规范 |
| 🌐 API调用问题 | API接口文档 |
| 🧪 测试相关问题 | 测试指南 |
| 🚀 部署发布问题 | Web部署指南 |
📚 文档导航
💬 联系方式
- 项目地址: Gitea Repository
- 问题反馈: Issues
- 功能建议: Discussions
📄 许可证
本项目采用 MIT License 开源协议。