moyin
1ff677b3b2
新的目录结构: 01-项目入门/ # 新人必读，项目基础 02-开发规范/ # 编码标准和规范 03-技术实现/ # 具体开发指导 04-高级开发/ # 进阶开发技巧 05-部署运维/ # 发布和部署 06-功能模块/ # 特定功能文档 新增导航文档: - docs/README.md - 完整的文档导航和使用指南 - 各目录下的README.md - 分类说明和使用指导 优化效果: - 开发者可以按阶段快速定位需要的文档 - 新人有清晰的学习路径 - 不同角色有针对性的文档推荐 - 提供了问题导向的快速查找功能
🐋 Whale Town - 像素游戏前端客户端
一个基于 Godot 4.5 引擎开发的现代化 2D 像素风游戏前端，采用模块化架构设计，集成完整的用户认证系统、实时通信和游戏核心功能。
🎯 项目简介
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
🛠️ 安装与运行
# 1. 克隆项目
git clone <repository-url>
cd whale-town
# 2. 使用Godot编辑器打开项目
# 双击 project.godot 文件或在Godot编辑器中导入项目
# 3. 运行项目
# 按F5或点击"运行"按钮启动游戏
🎉 游戏启动成功！ 进入认证界面开始体验
🧪 快速测试
# API接口测试
python tests/api/simple_api_test.py
# 完整功能测试
python tests/api/api_test.py --verbose
测试内容：
- ✅ 用户认证流程测试
- ✅ API接口连通性测试
- ✅ 错误处理和边界条件测试
- ✅ 网络通信功能测试
🎓 新开发者指南
第一步：了解项目规范 📚
⚠️ 重要：在开始开发前，请务必阅读以下文档
-
项目结构详解 🏗️
- 理解模块化架构设计
- 掌握目录组织规则
- 学习组件通信机制
-
命名规范 📝
- 场景、脚本、节点命名规则
- 资源文件命名标准
- 变量和函数命名约定
-
代码注释规范 💬
- 注释标准和最佳实践
- 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 开源协议。