whale-town-front/README.md

🐋 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/      - 对话系统

团队协作

• 美术组: 主要在 Assets/ 工作
• 策划组: 主要在 Config/ 工作
• 程序组: 主要在 _Core/, Scenes/, UI/ 工作
• 测试组: 主要在 Tests/ 工作

✨ 主要功能

🔐 用户认证系统

• 用户注册 - 支持邮箱验证码验证
• 用户登录 - 多种登录方式（用户名/邮箱/手机号）
• 密码管理 - 密码重置和修改功能
• 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和测试文档

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

🛠️ 开发指南

添加新场景

1. 在 Scenes/ 对应分类下创建场景文件
2. 脚本文件紧邻场景文件存放（场景内聚原则）
3. 在 _Core/managers/SceneManager.gd 中注册场景路径
4. 使用 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")

创建可复用组件

1. 在 Scenes/Components/ 创建组件场景
2. 实现标准接口，保持组件独立性
3. 通过 EventSystem 与其他模块通信
4. 组件可以被任何场景实例化复用

添加UI界面

1. 模态窗口 → 放入 UI/Windows/
2. 常驻界面 → 放入 UI/HUD/
3. 对话系统 → 放入 UI/Dialog/
4. 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

第一步：了解项目规范 📚

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

1. 项目结构详解 🏗️

   • 理解模块化架构设计
   • 掌握目录组织规则
   • 学习组件通信机制

2. 命名规范 📝

   • 场景、脚本、节点命名规则
   • 资源文件命名标准
   • 变量和函数命名约定

3. 代码注释规范 💬

   • 注释标准和最佳实践
   • AI辅助开发指南
   • 文档生成规范

4. 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实现组件间通信
• 📦 清晰分层 - 场景层 → 业务层 → 核心层
• 🧪 测试友好 - 完整的测试覆盖和文档

第三步：体验核心功能 🎮

1. 用户认证系统 🔐

   • 邮箱验证码注册
   • 多方式登录（用户名/邮箱/手机号）
   • 密码重置功能

2. 游戏核心系统 🎮

   • 场景管理和切换
   • 角色状态管理
   • 实时网络通信

3. 开发工具 🛠️

   • 内置测试场景
   • API测试脚本
   • 性能监控工具

第四步：开始贡献 🤝

1. Fork项目 到你的账户
2. 创建功能分支：git checkout -b feature/your-feature
3. 遵循规范开发（参考文档）
4. 添加测试用例：确保功能正确性
5. 提交代码：git commit -m "feat：添加新功能"
6. 创建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安装包（规划中）

---

📚 文档中心

🎯 新手必读

1. 项目结构详解 - 架构设计和组织规则
2. 命名规范 - 代码和资源命名标准
3. 代码注释规范 - 注释标准和AI辅助
4. Git提交规范 - 版本控制最佳实践

📖 功能文档

• 用户认证系统 - 认证流程和界面设计
• API接口文档 - 完整的API使用指南
• 测试指南 - 测试用例和使用方法

🏗️ 开发指南

• 模块开发指南 - 如何创建新模块
• 场景设计规范 - 场景架构和最佳实践
• 性能优化指南 - 性能调优技巧

---

🤝 贡献者

感谢所有为项目做出贡献的开发者！

🏆 核心团队

• moyin - 核心开发者
• jianuo - 核心开发者
• angjustinl - 核心开发者

查看完整贡献者名单：docs/CONTRIBUTORS.md

🌟 如何贡献

我们欢迎所有形式的贡献：

1. 🐛 Bug修复 - 发现并修复问题
2. ✨ 新功能 - 添加有价值的功能
3. 📚 文档改进 - 完善项目文档
4. 🧪 测试用例 - 提高代码覆盖率
5. 🎨 UI/UX改进 - 提升用户体验
6. ⚡ 性能优化 - 优化游戏性能

贡献流程：

1. Fork项目 → 2. 创建分支 → 3. 开发功能 → 4. 提交PR

---

📞 联系我们

• 项目地址: Gitea Repository
• 问题反馈: Issues
• 功能建议: Discussions

📄 许可证

本项目采用 MIT License 开源协议。

---

🐋 Whale Town - 让像素世界更精彩！

Made with ❤️ by the Whale Town Team

⭐ Star | 🍴 Fork | 📖 Docs | 🐛 Issues

======= - ✅ 基础架构搭建完成 - ✅ 项目结构重构完成（2025-12-31） - ✅ 用户认证系统完成 - ✅ API接口集成完成 - ✅ 测试体系建立完成 - ✅ 文档体系完善 - 🚧 游戏核心玩法开发中 - 🚧 更多功能模块开发中

最后更新: 2025-12-31

重要更新: 项目已完成架构重构，采用新的分层结构。详见 REFACTORING.md

whale-town-front/main