🐋 Whale Town - 像素游戏前端客户端
一个基于 Godot 4.5 引擎开发的现代化 2D 像素风游戏前端，采用模块化架构设计，集成完整的用户认证系统、实时通信和游戏核心功能。
🎯 项目简介
Whale Town 是一个功能完整的像素游戏前端客户端，采用模块化架构设计：
- 🔐 用户认证系统 - 完整的登录、注册、密码管理、邮箱验证界面
- 🎮 游戏核心功能 - 角色系统、战斗系统、对话系统、背包系统
- 🌐 实时通信 - WebSocket集成，支持实时多人交互
- 🎨 现代化UI - 响应式界面设计，支持多分辨率适配
- 🧪 完整测试体系 - UI测试、API测试、性能测试全覆盖
- 📱 跨平台支持 - Windows、Linux、macOS、移动端
- 🔧 模块化架构 - 高度解耦的组件系统，易于扩展和维护
🚀 快速开始
<<<<<<< HEAD
📋 环境要求
- Godot Engine >= 4.5.0 (推荐 4.5.1)
- Python >= 3.7.0 (用于API测试，可选)
- Git >= 2.0.0
🛠️ 安装与运行
=======
环境要求
- Godot Engine 4.5+
- Python 3.7+ (用于API测试和Web服务器)
whale-town-front/main
# 1. 克隆项目
git clone <repository-url>
cd whale-town
# 2. 使用Godot编辑器打开项目
# 双击 project.godot 文件或在Godot编辑器中导入项目
# 3. 运行项目
# 按F5或点击"运行"按钮启动游戏
<<<<<<< HEAD 🎉 游戏启动成功！ 进入认证界面开始体验
🧪 快速测试
# API接口测试
=======
### Web版本部署
```bash
# Windows用户
tools\build_web.bat # 导出Web版本
tools\serve_web.bat # 启动本地测试服务器
# Linux/macOS用户
./tools/build_web.sh # 导出Web版本
./tools/serve_web.sh # 启动本地测试服务器
详细部署指南请查看: Web部署完整指南
🏗️ 项目架构
核心设计理念
项目采用 分层架构 和 组件化设计，遵循 Godot 最佳实践：
- 清晰的分层 - 框架层、玩法层、界面层明确分离
- 场景内聚 - 脚本紧邻场景文件，符合 Godot 原生开发习惯
- 高度解耦 - 通过事件系统和管理器通信
- 组件复用 - 可复用组件统一管理
- 标准化 - 统一的命名规范和目录结构
- 测试驱动 - 完整的测试体系和文档
目录结构
whaleTown/
├── _Core/ # [框架层] 游戏的底层框架，单例，全局管理器
│ ├── managers/ # 游戏管理器
│ │ ├── GameManager.gd # 游戏状态管理
│ │ ├── SceneManager.gd # 场景管理
│ │ ├── NetworkManager.gd # 网络通信
│ │ └── ResponseHandler.gd # API响应处理
│ ├── systems/ # 核心系统
│ │ └── EventSystem.gd # 事件系统
│ └── singletons/ # 其他单例（待扩展）
│
├── Scenes/ # [玩法层] 具体的游戏场景、实体、地图
│ ├── Maps/ # 地图场景
│ │ └── main_scene.tscn # 主游戏场景
│ ├── Entities/ # 游戏实体
│ │ ├── Player/ # 玩家实体
│ │ ├── NPC/ # NPC实体
│ │ └── Interactables/ # 交互物
│ └── Components/ # 可复用组件
│
├── UI/ # [界面层] 所有UI相关的预制体和逻辑
│ ├── HUD/ # 抬头显示（常驻）
│ ├── Windows/ # 模态窗口
│ │ └── LoginWindow.tscn # 登录窗口
│ ├── Dialog/ # 对话系统
│ └── Theme/ # 全局样式
│ ├── MainTheme.tres # 主主题
│ └── Fonts/ # 字体文件
│
├── Assets/ # [资源层] 美术、音频、字体
│ ├── Sprites/ # 精灵图
│ │ ├── icon/ # 图标
│ │ ├── materials/ # 材质
│ │ ├── shaders/ # 着色器
│ │ └── sprites/ # 精灵图
│ ├── Audio/ # 音频
│ └── Fonts/ # 字体
│
├── Config/ # [配置层] 游戏配置文件
│ ├── game_config.json # 游戏配置
│ └── zh_CN.json # 中文本地化
│
├── Utils/ # [工具层] 通用辅助脚本
│ └── StringUtils.gd # 字符串工具
│
├── 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提交规范
│
├── tools/ # 开发工具和脚本
│ ├── build_web.bat # Windows Web导出脚本
│ ├── build_web.sh # Linux/macOS Web导出脚本
│ ├── serve_web.bat # Windows 本地服务器
│ └── serve_web.sh # Linux/macOS 本地服务器
│
├── REFACTORING.md # 项目结构重构文档
└── MIGRATION_COMPLETE.md # 迁移完成标记
架构层次说明
1. 框架层 (_Core/)
- 职责: 游戏的底层框架，与具体游戏逻辑无关
- 内容: 单例管理器、核心系统
- 特点: 自动加载，全局可访问
- 命名: 使用下划线前缀
_Core表示这是核心框架代码
2. 玩法层 (Scenes/)
- 职责: 游戏世界，地图和实体
- 内容: 游戏场景、角色、NPC、交互物
- 特点: 场景内聚，脚本紧邻场景文件
- 组织: 按游戏世界的实体类型分类
3. 界面层 (UI/)
- 职责: 所有界面，HUD和弹窗
- 内容: 常驻界面、模态窗口、对话系统、主题样式
- 特点: 独立于游戏场景，便于UI开发和维护
- 组织: 按界面类型和用途分类
4. 资源层 (Assets/)
- 职责: 纯美术资源
- 内容: 精灵图、音频、字体等
- 特点: 与代码分离，便于美术组独立工作
- 组织: 按资源类型分类
5. 配置层 (Config/)
- 职责: 静态数据，策划可编辑
- 内容: 游戏配置、本地化文件
- 特点: 数据驱动，便于调整游戏参数
- 格式: JSON 文件
6. 工具层 (Utils/)
- 职责: 通用辅助脚本
- 内容: 工具函数库
- 特点: 可被任何层调用
- 原则: 无依赖，纯函数
核心系统
项目包含以下自动加载的核心系统（位于 _Core/）：
- GameManager - 全局游戏状态管理
- SceneManager - 场景切换管理
- EventSystem - 事件通信系统
- NetworkManager - 网络通信管理
- ResponseHandler - API响应处理
使用示例：
# 状态管理
GameManager.change_state(GameManager.GameState.IN_GAME)
# 场景切换（已更新路径）
SceneManager.change_scene("main") # → res://Scenes/Maps/main_scene.tscn
# 事件通信
EventSystem.emit_event("player_health_changed", 80)
EventSystem.connect_event("player_died", _on_player_died)
设计原则
1. 清晰的分层
- _Core: 框架代码，与具体游戏逻辑无关
- Scenes: 游戏世界，地图和实体
- UI: 所有界面，HUD和弹窗
- Config: 静态数据，策划可编辑
2. 组件化设计
可复用组件放在 Scenes/Components/ 下，使用组合优于继承的设计模式：
- InteractableArea.tscn - 让任何物体"可交互"
- MovementSync.gd - 网络位置同步
- NameTag3D.tscn - 头顶名字条
3. 场景内聚
- 每个 .tscn 配套一个 .gd
- 脚本紧邻场景文件存放
- 符合 Godot 原生开发习惯
4. 职责单一
UI/Windows/ - 模态窗口（登录、设置、商店）
UI/HUD/ - 常驻界面（聊天框、状态栏）
UI/Dialog/ - 对话系统
团队协作
✨ 主要功能
🔐 用户认证系统
- 用户注册 - 支持邮箱验证码验证
- 用户登录 - 多种登录方式（用户名/邮箱/手机号）
- 密码管理 - 密码重置和修改功能
- GitHub OAuth - 第三方登录集成
- 错误处理 - 完整的错误提示和频率限制
- UI界面: UI/Windows/LoginWindow.tscn
🌐 Web版本部署
- 自动化导出 - 一键导出Web版本
- 本地测试服务器 - 内置HTTP服务器用于测试
- 生产环境配置 - 完整的服务器配置指南
- 跨平台支持 - Windows、Linux、macOS全平台支持
- 性能优化 - 资源压缩和加载优化
🎮 游戏功能
- 主场景 - 游戏主界面和菜单系统 (Scenes/Maps/main_scene.tscn)
- 认证场景 - 完整的登录注册界面
- 状态管理 - 用户状态和游戏状态管理
- 网络通信 - RESTful API集成 (_Core/managers/NetworkManager.gd)
🧪 测试体系
- API测试 - 完整的接口测试脚本 (Tests/api/)
- UI测试 - 认证界面的交互测试 (Tests/auth/)
- 错误场景 - 边界条件和异常处理测试
🔧 开发规范
命名规范
- 场景文件:
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
git commit -m "feat：实现用户登录功能"
git commit -m "fix：修复429错误处理"
git commit -m "test：添加API接口测试"
git commit -m "docs：更新项目文档"
📚 项目文档
核心文档
- 📋 项目结构详解 - 完整的架构说明
- 📝 命名规范 - 详细的命名规则
- 💬 代码注释规范 - 注释标准和AI辅助指南
- 🔀 Git提交规范 - 提交信息标准
- 🌐 Web部署指南 - 完整的Web部署文档
API和测试文档
🛠️ 开发指南
添加新场景
- 在 Scenes/ 对应分类下创建场景文件
- 脚本文件紧邻场景文件存放（场景内聚原则）
- 在 _Core/managers/SceneManager.gd 中注册场景路径
- 使用
SceneManager.change_scene()切换场景
示例：
# 在 SceneManager.gd 中注册
var scene_paths: Dictionary = {
"battle": "res://Scenes/Maps/battle_scene.tscn",
"shop": "res://UI/Windows/ShopWindow.tscn",
}
# 使用
SceneManager.change_scene("battle")
创建可复用组件
- 在 Scenes/Components/ 创建组件场景
- 实现标准接口，保持组件独立性
- 通过 EventSystem 与其他模块通信
- 组件可以被任何场景实例化复用
添加UI界面
- 模态窗口 → 放入 UI/Windows/
- 常驻界面 → 放入 UI/HUD/
- 对话系统 → 放入 UI/Dialog/
- UI脚本紧邻场景文件，保持内聚
资源管理
- 精灵图 → 放入 Assets/Sprites/ 对应分类
- 音频文件 → 放入 Assets/Audio/ 对应分类
- 字体文件 → 放入 UI/Theme/Fonts/
- 配置文件 → 放入 Config/
- 遵循命名规范，使用英文小写+下划线
路径映射参考
| 功能类型 | 旧路径 | 新路径 |
|---|---|---|
| 核心管理器 | core/managers/ |
_Core/managers/ |
| 游戏场景 | scenes/main_scene.tscn |
Scenes/Maps/main_scene.tscn |
| 登录界面 | scenes/auth_scene.tscn |
UI/Windows/LoginWindow.tscn |
| 配置文件 | data/configs/ |
Config/ |
| 工具类 | core/utils/ |
Utils/ |
详细的重构说明请查看：REFACTORING.md
API接口测试
项目提供了完整的Python测试脚本来验证API接口：
# 快速测试API连通性
>>>>>>> whale-town-front/main
python tests/api/simple_api_test.py
# 完整功能测试
python tests/api/api_test.py --verbose
测试内容：
- ✅ 用户认证流程测试
- ✅ API接口连通性测试
- ✅ 错误处理和边界条件测试
- ✅ 网络通信功能测试
🎓 新开发者指南
<<<<<<< HEAD
第一步：了解项目规范 📚
⚠️ 重要：在开始开发前，请务必阅读以下文档
-
项目结构详解 🏗️
- 理解模块化架构设计
- 掌握目录组织规则
- 学习组件通信机制
-
命名规范 📝
- 场景、脚本、节点命名规则
- 资源文件命名标准
- 变量和函数命名约定
-
代码注释规范 💬
- 注释标准和最佳实践
- AI辅助开发指南
- 文档生成规范
-
Git提交规范 🔄
- 提交信息格式标准
- 分支管理策略
- 代码审查流程
第二步：熟悉项目架构 🏗️
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实现组件间通信
- 📦 清晰分层 - 场景层 → 业务层 → 核心层
- 🧪 测试友好 - 完整的测试覆盖和文档
第三步：体验核心功能 🎮
-
用户认证系统 🔐
- 邮箱验证码注册
- 多方式登录（用户名/邮箱/手机号）
- 密码重置功能
-
游戏核心系统 🎮
- 场景管理和切换
- 角色状态管理
- 实时网络通信
-
开发工具 🛠️
- 内置测试场景
- API测试脚本
- 性能监控工具
第四步：开始贡献 🤝
- Fork项目 到你的账户
- 创建功能分支：
git checkout -b feature/your-feature - 遵循规范开发（参考文档）
- 添加测试用例：确保功能正确性
- 提交代码：
git commit -m "feat：添加新功能" - 创建Pull Request
<EFBFBD>[️ 技术栈
🎮 游戏引擎
- 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测试 - 交互式界面测试场景
- 单元测试 - 组件和函数级别测试
- 集成测试 - 完整业务流程测试
- 性能测试 - 帧率和内存性能监控
📊 开发与测试
🔧 开发命令
# 启动Godot编辑器
godot --editor
# 运行项目（无编辑器）
godot --main-pack game.pck
# 导出项目
godot --export "Windows Desktop" game.exe
# 运行测试
godot --headless --script tests/run_tests.gd
🧪 测试命令
# 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测试: 认证流程完整测试 ✅
- 错误处理: 边界条件和异常测试 ✅
- 性能测试: 帧率和内存监控 ✅
🌍 部署配置
开发环境（默认）
# 本地开发配置
API_BASE_URL=http://localhost:3000
DEBUG_MODE=true
LOG_LEVEL=debug
生产环境
# 生产环境配置
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安装包（规划中）
📚 文档中心
🎯 新手必读
📖 功能文档
🏗️ 开发指南
🤝 贡献者
感谢所有为项目做出贡献的开发者！
🏆 核心团队
- moyin - 核心开发者
- jianuo - 核心开发者
- angjustinl - 核心开发者
查看完整贡献者名单：docs/CONTRIBUTORS.md
🌟 如何贡献
我们欢迎所有形式的贡献：
- 🐛 Bug修复 - 发现并修复问题
- ✨ 新功能 - 添加有价值的功能
- 📚 文档改进 - 完善项目文档
- 🧪 测试用例 - 提高代码覆盖率
- 🎨 UI/UX改进 - 提升用户体验
- ⚡ 性能优化 - 优化游戏性能
贡献流程：
- Fork项目 → 2. 创建分支 → 3. 开发功能 → 4. 提交PR
📞 联系我们
- 项目地址: Gitea Repository
- 问题反馈: Issues
- 功能建议: Discussions
📄 许可证
本项目采用 MIT License 开源协议。
======= - ✅ 基础架构搭建完成 - ✅ 项目结构重构完成（2025-12-31） - ✅ 用户认证系统完成 - ✅ API接口集成完成 - ✅ 测试体系建立完成 - ✅ 文档体系完善 - 🚧 游戏核心玩法开发中 - 🚧 更多功能模块开发中
最后更新: 2025-12-31
重要更新: 项目已完成架构重构，采用新的分层结构。详见 REFACTORING.md
whale-town-front/main