🐋 whaleTown

一个使用 Godot 4.5 引擎开发的现代化像素游戏项目，集成了完整的用户认证系统和API接口。

🎮 项目信息

• 引擎版本: Godot 4.5.1
• 渲染器: Forward Plus
• 项目类型: 2D 像素游戏
• 架构模式: 模块化 + 事件驱动
• 后端集成: RESTful API + 用户认证

🚀 快速开始

环境要求

• Godot Engine 4.5+
• Python 3.7+ (用于API测试和Web服务器)

运行项目

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

# 2. 使用Godot编辑器打开项目
# 3. 按F5运行或点击"运行"按钮

# 4. 测试API接口（可选）
python tests/api/simple_api_test.py

Web版本部署

# Windows用户
scripts\build_web.bat      # 导出Web版本
scripts\serve_web.bat      # 启动本地测试服务器

# Linux/macOS用户
./scripts/build_web.sh     # 导出Web版本
./scripts/serve_web.sh     # 启动本地测试服务器

详细部署指南请查看: Web部署完整指南

🏗️ 项目架构

核心设计理念

• 场景独立性 - 每个场景都是独立的功能模块
• 高度解耦 - 通过事件系统和管理器通信
• 组件复用 - 可复用组件统一管理
• 标准化 - 统一的命名规范和目录结构
• 测试驱动 - 完整的测试体系和文档

目录结构

whaleTown/
├── 🎬 scenes/           # 游戏场景
│   ├── auth_scene.tscn     # 用户认证场景
│   ├── main_scene.tscn     # 主游戏场景
│   └── prefabs/            # 预制体组件
├── 🔧 core/             # 核心系统（自动加载）
│   ├── managers/           # 全局管理器
│   ├── systems/            # 系统组件
│   └── utils/              # 工具类
├── 📝 scripts/          # 业务逻辑脚本
│   ├── scenes/             # 场景脚本
│   ├── network/            # 网络相关
│   ├── build_web.bat       # Windows Web导出脚本
│   ├── build_web.sh        # Linux/macOS Web导出脚本
│   ├── serve_web.bat       # Windows 本地服务器
│   ├── serve_web.sh        # Linux/macOS 本地服务器
│   └── ui/                 # UI组件脚本
├── 🧩 module/           # 可复用模块
│   ├── UI/                 # UI组件模块
│   ├── Character/          # 角色模块
│   ├── Combat/             # 战斗模块
│   ├── Dialogue/           # 对话模块
│   └── Inventory/          # 背包模块
├── 🎨 assets/           # 游戏资源
│   ├── sprites/            # 精灵图资源
│   ├── audio/              # 音频文件
│   ├── ui/                 # UI界面资源
│   ├── fonts/              # 字体资源
│   ├── materials/          # 材质资源
│   └── shaders/            # 着色器资源
├── 📊 data/             # 配置数据
│   ├── configs/            # 游戏配置
│   ├── localization/       # 本地化文件
│   ├── characters/         # 角色数据
│   ├── items/              # 物品数据
│   ├── levels/             # 关卡数据
│   └── dialogues/          # 对话数据
├── 🧪 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提交规范

核心系统

项目包含以下自动加载的核心系统：

• GameManager - 全局游戏状态管理
• SceneManager - 场景切换管理
• EventSystem - 事件通信系统

使用示例：

# 状态管理
GameManager.change_state(GameManager.GameState.IN_GAME)

# 场景切换
SceneManager.change_scene("battle")

# 事件通信
EventSystem.emit_event("player_health_changed", 80)
EventSystem.connect_event("player_died", _on_player_died)

✨ 主要功能

🔐 用户认证系统

• 用户注册 - 支持邮箱验证码验证
• 用户登录 - 多种登录方式（用户名/邮箱/手机号）
• 密码管理 - 密码重置和修改功能
• GitHub OAuth - 第三方登录集成
• 错误处理 - 完整的错误提示和频率限制

🌐 Web版本部署

• 自动化导出 - 一键导出Web版本
• 本地测试服务器 - 内置HTTP服务器用于测试
• 生产环境配置 - 完整的服务器配置指南
• 跨平台支持 - Windows、Linux、macOS全平台支持
• 性能优化 - 资源压缩和加载优化

🎮 游戏功能

• 主场景 - 游戏主界面和菜单系统
• 认证场景 - 完整的登录注册界面
• 状态管理 - 用户状态和游戏状态管理
• 网络通信 - RESTful API集成

🧪 测试体系

• API测试 - 完整的接口测试脚本
• UI测试 - 认证界面的交互测试
• 错误场景 - 边界条件和异常处理测试

🔧 开发规范

命名规范

• 场景文件: 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和测试文档

• 🔌 API接口文档 - 完整的API说明和测试指南
• 🔐 认证系统文档 - 用户认证相关文档
• 🧪 API测试指南 - API测试使用方法
• 🎮 认证UI测试 - UI测试场景说明

🛠️ 开发指南

添加新场景

1. 在 scenes/ 创建场景文件
2. 在 scripts/scenes/ 创建对应脚本
3. 在 SceneManager 中注册场景路径
4. 使用 SceneManager.change_scene() 切换

创建可复用组件

1. 在 module/ 对应分类下创建组件
2. 实现标准接口
3. 通过 EventSystem 与其他模块通信
4. 在 scenes/prefabs/ 创建预制体

资源管理

• 图片资源放入 assets/sprites/ 对应分类
• 音频文件放入 assets/audio/ 对应分类
• UI资源放入 assets/ui/ 对应分类
• 配置文件放入 data/configs/
• 遵循命名规范，使用英文小写+下划线

API接口测试

项目提供了完整的Python测试脚本来验证API接口：

# 快速测试API连通性
python tests/api/simple_api_test.py

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

# 自定义服务器地址测试
python tests/api/simple_api_test.py https://your-api-server.com

测试脚本会验证：

• ✅ 应用状态检查
• ✅ 用户注册和登录功能
• ✅ 邮箱验证码发送和验证
• ✅ 错误处理和频率限制（429错误）
• ✅ 管理员功能和权限控制
• ✅ 用户状态管理
• ✅ 安全功能测试

📖 查看 API测试文档 了解详细使用方法

认证UI测试

项目还提供了Godot内置的UI测试场景：

1. 在Godot编辑器中打开 tests/auth/auth_ui_test.tscn
2. 运行场景进行交互式测试
3. 测试各种错误场景和边界条件

📖 查看 认证UI测试文档 了解详细使用方法

🔧 技术栈

• 游戏引擎: Godot 4.5.1
• 脚本语言: GDScript
• 架构模式: 模块化 + 事件驱动
• 状态管理: 单例管理器模式
• 通信机制: 全局事件系统
• API集成: RESTful API + JSON
• 测试框架: Python + Godot内置测试

🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 遵循项目的命名规范和架构设计
4. 添加相应的测试用例
5. 更新相关文档
6. 提交更改 (git commit -m 'feat：添加某个功能')
7. 推送到分支 (git push origin feature/AmazingFeature)
8. 开启 Pull Request

贡献类型

• 🐛 Bug修复
• ✨ 新功能开发
• 📚 文档改进
• 🧪 测试用例
• 🎨 UI/UX改进
• ⚡ 性能优化

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情

---

🎯 项目状态

• ✅ 基础架构搭建完成
• ✅ 用户认证系统完成
• ✅ API接口集成完成
• ✅ 测试体系建立完成
• ✅ 文档体系完善
• 🚧 游戏核心玩法开发中
• 🚧 更多功能模块开发中

最后更新: 2025-12-24