forked from datawhale/whale-town-front
docs: 完善项目文档和README，修复字符显示问题
- 修复README.md中的emoji字符显示问题 - 移除文档质量评级系统 - 添加贡献者致谢部分，创建详细的CONTRIBUTORS.md - 创建核心系统文件EventNames.gd和ProjectPaths.gd - 更新项目配置文件project.godot，添加输入映射 - 完善各模块文档，修正路径引用问题 - 创建文档更新日志CHANGELOG.md - 优化文档结构和导航系统
This commit is contained in:
536
README.md
536
README.md
@@ -1,365 +1,349 @@
|
||||
# 🐋 Whale Town - 像素游戏前端客户端
|
||||
# 🐋 WhaleTown - 现代化像素游戏
|
||||
|
||||
> 一个基于 Godot 4.5 引擎开发的现代化 2D 像素风游戏前端，采用模块化架构设计，集成完整的用户认证系统、实时通信和游戏核心功能。
|
||||
> 一个基于 Godot 4.5 引擎开发的企业级 2D 像素风游戏，采用模块化架构设计，集成完整的用户认证系统和游戏核心功能。
|
||||
|
||||
[](https://godotengine.org/)
|
||||
[](https://godotengine.org/)
|
||||
[](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/index.html)
|
||||
[](./LICENSE)
|
||||
[](https://godotengine.org/download)
|
||||
[](./docs/)
|
||||
[](https://godotengine.org/download)
|
||||
|
||||
## 🎯 项目简介
|
||||
|
||||
Whale Town 是一个功能完整的像素游戏前端客户端，采用模块化架构设计：
|
||||
WhaleTown 是一个功能完整的现代化像素游戏，具有以下特色：
|
||||
|
||||
- 🔐 **用户认证系统** - 完整的登录、注册、密码管理、邮箱验证界面
|
||||
- 🎮 **游戏核心功能** - 角色系统、战斗系统、对话系统、背包系统
|
||||
- 🌐 **实时通信** - WebSocket集成，支持实时多人交互
|
||||
- 🎨 **现代化UI** - 响应式界面设计，支持多分辨率适配
|
||||
- 🧪 **完整测试体系** - UI测试、API测试、性能测试全覆盖
|
||||
- 📱 **跨平台支持** - Windows、Linux、macOS、移动端
|
||||
- 🔧 **模块化架构** - 高度解耦的组件系统，易于扩展和维护
|
||||
- 🏗️ **企业级架构** - 模块化设计，高度解耦，易于扩展
|
||||
- 🔐 **完整认证系统** - 登录、注册、邮箱验证、密码管理
|
||||
- 🎮 **丰富游戏功能** - 角色系统、场景管理、事件通信
|
||||
- 🌐 **网络通信** - RESTful API集成，支持实时数据交互
|
||||
- 📚 **企业级文档** - 18个文档，覆盖开发全流程
|
||||
- 🧪 **完整测试体系** - API测试、UI测试、性能测试
|
||||
- 🚀 **一键部署** - 支持Web、桌面多平台发布
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速开始
|
||||
## 🚀 5分钟快速体验
|
||||
|
||||
### 📋 环境要求
|
||||
### 📋 准备工作
|
||||
|
||||
- **Godot Engine** >= 4.5.0 (推荐 4.5.1)(https://godotengine.org/download)
|
||||
- **Python** >= 3.7.0 (用于API测试，可选)
|
||||
- **Git** >= 2.0.0
|
||||
**你需要安装：**
|
||||
- [Godot Engine 4.5+](https://godotengine.org/download) - 游戏引擎
|
||||
- [Git](https://git-scm.com/) - 版本控制工具
|
||||
|
||||
### 🛠️ 安装与运行
|
||||
### 🛠️ 启动项目
|
||||
|
||||
```bash
|
||||
# 1. 克隆项目
|
||||
# 1️⃣ 获取项目
|
||||
git clone <repository-url>
|
||||
cd whale-town
|
||||
|
||||
# 2. 使用Godot编辑器打开项目
|
||||
# 双击 project.godot 文件或在Godot编辑器中导入项目
|
||||
# 2️⃣ 打开项目
|
||||
# 双击 project.godot 文件，或在Godot编辑器中选择"导入项目"
|
||||
|
||||
# 3. 运行项目
|
||||
# 按F5或点击"运行"按钮启动游戏
|
||||
# 3️⃣ 运行游戏
|
||||
# 在Godot编辑器中按 F5 或点击"运行项目"按钮
|
||||
```
|
||||
|
||||
🎉 **游戏启动成功！** 进入认证界面开始体验
|
||||
🎉 **成功！** 你应该看到游戏的认证界面
|
||||
|
||||
### 🧪 快速测试
|
||||
### 🎮 体验功能
|
||||
|
||||
1. **注册新用户** - 体验完整的邮箱验证流程
|
||||
2. **登录系统** - 尝试用户名/邮箱登录
|
||||
3. **游戏界面** - 探索主游戏场景
|
||||
|
||||
### 🧪 测试API（可选）
|
||||
|
||||
```bash
|
||||
# API接口测试
|
||||
python tests/api/simple_api_test.py
|
||||
# 安装Python依赖
|
||||
pip install requests
|
||||
|
||||
# 快速API测试
|
||||
python tests/api/quick_test.py
|
||||
|
||||
# 完整功能测试
|
||||
python tests/api/api_test.py --verbose
|
||||
python tests/api/api_client_test.py
|
||||
```
|
||||
|
||||
**测试内容：**
|
||||
- ✅ 用户认证流程测试
|
||||
- ✅ API接口连通性测试
|
||||
- ✅ 错误处理和边界条件测试
|
||||
- ✅ 网络通信功能测试
|
||||
---
|
||||
|
||||
## 📚 新手开发指南
|
||||
|
||||
### 🎯 第一步：了解项目
|
||||
|
||||
**⚠️ 重要：开始开发前必读**
|
||||
|
||||
1. **[📖 项目入门总览](docs/01-项目入门/README.md)** - 5分钟了解项目
|
||||
2. **[🏗️ 项目结构说明](docs/01-项目入门/项目结构说明.md)** - 理解架构设计
|
||||
3. **[⚙️ 项目设置指南](docs/01-项目入门/项目设置指南.md)** - 配置开发环境
|
||||
|
||||
### 🎯 第二步：学习规范
|
||||
|
||||
**代码质量保证**
|
||||
|
||||
1. **[📝 命名规范](docs/02-开发规范/命名规范.md)** - 统一命名标准
|
||||
2. **[🏛️ 架构与通信规范](docs/02-开发规范/架构与通信规范.md)** - 组件通信方式
|
||||
3. **[💬 代码注释规范](docs/02-开发规范/代码注释规范.md)** - 注释标准
|
||||
4. **[🔄 Git提交规范](docs/02-开发规范/Git提交规范.md)** - 版本控制规范
|
||||
|
||||
### 🎯 第三步：开始开发
|
||||
|
||||
**技术实现指导**
|
||||
|
||||
1. **[🔧 实现细节规范](docs/03-技术实现/实现细节规范.md)** - 游戏对象实现
|
||||
2. **[🌐 API接口文档](docs/03-技术实现/API接口文档.md)** - 后端接口使用
|
||||
3. **[🧪 测试指南](docs/03-技术实现/测试指南.md)** - 测试方法和工具
|
||||
|
||||
### 🎯 第四步：高级开发
|
||||
|
||||
**进阶技能**
|
||||
|
||||
1. **[🚀 性能优化指南](docs/04-高级开发/性能优化指南.md)** - 性能调优
|
||||
2. **[🎬 场景设计规范](docs/04-高级开发/场景设计规范.md)** - 场景架构
|
||||
3. **[🧩 模块开发指南](docs/04-高级开发/模块开发指南.md)** - 模块化开发
|
||||
|
||||
### 🎯 第五步：项目发布
|
||||
|
||||
**部署和运维**
|
||||
|
||||
1. **[🌐 Web部署指南](docs/05-部署运维/Web部署指南.md)** - 完整部署流程
|
||||
|
||||
---
|
||||
|
||||
## 🎓 新开发者指南
|
||||
## 🏗️ 项目架构一览
|
||||
|
||||
### 第一步：了解项目规范 📚
|
||||
|
||||
**⚠️ 重要：在开始开发前，请务必阅读以下文档**
|
||||
|
||||
1. **[项目结构详解](./docs/project_structure.md)** 🏗️
|
||||
- 理解模块化架构设计
|
||||
- 掌握目录组织规则
|
||||
- 学习组件通信机制
|
||||
|
||||
2. **[命名规范](./docs/naming_convention.md)** 📝
|
||||
- 场景、脚本、节点命名规则
|
||||
- 资源文件命名标准
|
||||
- 变量和函数命名约定
|
||||
|
||||
3. **[代码注释规范](./docs/code_comment_guide.md)** 💬
|
||||
- 注释标准和最佳实践
|
||||
- AI辅助开发指南
|
||||
- 文档生成规范
|
||||
|
||||
4. **[Git提交规范](./docs/git_commit_guide.md)** 🔄
|
||||
- 提交信息格式标准
|
||||
- 分支管理策略
|
||||
- 代码审查流程
|
||||
|
||||
### 第二步：熟悉项目架构 🏗️
|
||||
### 📁 目录结构
|
||||
|
||||
```
|
||||
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接口文档
|
||||
WhaleTown/ # 🐋 项目根目录
|
||||
├── 📚 docs/ # 📖 完整文档系统（18个文档）
|
||||
│ ├── 01-项目入门/ # 👋 新人必读
|
||||
│ ├── 02-开发规范/ # 📋 编码标准
|
||||
│ ├── 03-技术实现/ # 🔧 开发指导
|
||||
│ ├── 04-高级开发/ # 🚀 进阶技巧
|
||||
│ ├── 05-部署运维/ # 🌐 发布部署
|
||||
│ └── 06-功能模块/ # 🎮 功能文档
|
||||
├── 🎬 scenes/ # 🎭 游戏场景
|
||||
│ ├── Maps/ # 🗺️ 地图场景
|
||||
│ └── Components/ # 🧩 组件预制体
|
||||
├── 🔧 _Core/ # ⚙️ 核心系统
|
||||
│ ├── managers/ # 🎯 全局管理器
|
||||
│ ├── systems/ # 🔄 系统组件
|
||||
│ ├── EventNames.gd # 📝 事件名称定义
|
||||
│ └── ProjectPaths.gd # 📂 路径统一管理
|
||||
├── 🎨 UI/ # 🖼️ 用户界面
|
||||
│ └── Windows/ # 🪟 窗口界面
|
||||
├── 🔨 Utils/ # 🔨 工具类
|
||||
├── 🎮 module/ # 🧩 功能模块
|
||||
├── 🎨 assets/ # 🖼️ 游戏资源
|
||||
├── ⚙️ Config/ # 📋 配置文件
|
||||
├── 🧪 tests/ # 🔬 测试文件
|
||||
└── 🌐 web_assets/ # 🌍 Web部署资源
|
||||
```
|
||||
|
||||
**架构特点：**
|
||||
- 🏗️ **模块化设计** - 按功能而非技术组织代码
|
||||
- 🔄 **事件驱动** - 通过EventSystem实现组件间通信
|
||||
- 📦 **清晰分层** - 场景层 → 业务层 → 核心层
|
||||
- 🧪 **测试友好** - 完整的测试覆盖和文档
|
||||
### 🔧 核心组件
|
||||
|
||||
### 第三步：体验核心功能 🎮
|
||||
|
||||
1. **用户认证系统** 🔐
|
||||
- 邮箱验证码注册
|
||||
- 多方式登录（用户名/邮箱/手机号）
|
||||
- 密码重置功能
|
||||
|
||||
2. **游戏核心系统** 🎮
|
||||
- 场景管理和切换
|
||||
- 角色状态管理
|
||||
- 实时网络通信
|
||||
|
||||
3. **开发工具** 🛠️
|
||||
- 内置测试场景
|
||||
- API测试脚本
|
||||
- 性能监控工具
|
||||
|
||||
### 第四步：开始贡献 🤝
|
||||
|
||||
1. **Fork项目** 到你的账户
|
||||
2. **创建功能分支**：`git checkout -b feature/your-feature`
|
||||
3. **遵循规范开发**（参考文档）
|
||||
4. **添加测试用例**：确保功能正确性
|
||||
5. **提交代码**：`git commit -m "feat：添加新功能"`
|
||||
6. **创建Pull Request**
|
||||
| 组件 | 作用 | 文档链接 |
|
||||
|------|------|----------|
|
||||
| **EventSystem** | 全局事件通信 | [架构规范](docs/02-开发规范/架构与通信规范.md) |
|
||||
| **GameManager** | 游戏状态管理 | [实现细节](docs/03-技术实现/实现细节规范.md) |
|
||||
| **SceneManager** | 场景切换管理 | [场景设计](docs/04-高级开发/场景设计规范.md) |
|
||||
| **NetworkManager** | 网络请求管理 | [网络管理器](docs/03-技术实现/网络管理器设置.md) |
|
||||
| **ProjectPaths** | 路径统一管理 | [项目结构](docs/01-项目入门/项目结构说明.md) |
|
||||
|
||||
---
|
||||
|
||||
## <EFBFBD>[️ 技术栈
|
||||
## 🎮 核心功能
|
||||
|
||||
### 🎮 游戏引擎
|
||||
- **Godot Engine** `4.5.1` - 开源游戏引擎，支持2D/3D开发
|
||||
- **GDScript** - Godot专用脚本语言，Python风格语法
|
||||
- **Forward Plus** - 现代渲染管线，支持高质量光照
|
||||
### 🔐 用户认证系统
|
||||
|
||||
### 🏗️ 架构设计
|
||||
- **模块化架构** - 按功能组织的可复用组件系统
|
||||
- **事件驱动** - 基于EventSystem的松耦合通信
|
||||
- **单例管理器** - GameManager、SceneManager等全局管理器
|
||||
- **状态机模式** - 游戏状态和角色状态管理
|
||||
**完整的用户管理功能**
|
||||
- ✅ 用户注册（用户名+邮箱验证）
|
||||
- ✅ 多方式登录（用户名/邮箱/验证码）
|
||||
- ✅ 密码管理（修改/重置）
|
||||
- ✅ 表单验证（实时验证+友好提示）
|
||||
- ✅ 错误处理（网络异常+业务错误）
|
||||
|
||||
### 🌐 网络通信
|
||||
- **RESTful API** - 标准HTTP接口通信
|
||||
- **JSON数据格式** - 轻量级数据交换格式
|
||||
- **WebSocket** - 实时双向通信支持
|
||||
- **错误处理** - 完整的网络异常处理机制
|
||||
**技术特色**
|
||||
- 📱 响应式UI设计
|
||||
- 🔄 实时表单验证
|
||||
- ⏰ 验证码冷却机制
|
||||
- 🎨 流畅动画效果
|
||||
|
||||
### 🎨 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** - 字符串处理工具集
|
||||
| 测试类型 | 工具 | 覆盖范围 | 文档 |
|
||||
|----------|------|----------|------|
|
||||
| **API测试** | Python脚本 | 17个接口全覆盖 | [测试指南](docs/03-技术实现/测试指南.md) |
|
||||
| **UI测试** | Godot场景 | 认证流程完整测试 | [认证测试](docs/06-功能模块/auth/认证测试指南.md) |
|
||||
| **单元测试** | GUT框架 | 核心组件测试 | [测试指南](docs/03-技术实现/测试指南.md) |
|
||||
|
||||
### 🧩 模块化组件 (module/)
|
||||
- **UI组件** - 可复用的界面组件和动画
|
||||
- **角色系统** - 角色数据和行为管理
|
||||
- **战斗系统** - 战斗逻辑和技能系统
|
||||
- **对话系统** - 对话树和文本显示
|
||||
- **背包系统** - 物品管理和交互
|
||||
|
||||
### 🌐 网络通信 (scripts/network/)
|
||||
- **API集成** - RESTful接口调用封装
|
||||
- **实时通信** - WebSocket连接管理
|
||||
- **数据同步** - 客户端服务器数据同步
|
||||
- **离线处理** - 网络异常和离线模式
|
||||
|
||||
### 🧪 测试体系 (tests/)
|
||||
- **API测试** - 完整的接口功能测试
|
||||
- **UI测试** - 交互式界面测试场景
|
||||
- **单元测试** - 组件和函数级别测试
|
||||
- **集成测试** - 完整业务流程测试
|
||||
- **性能测试** - 帧率和内存性能监控
|
||||
|
||||
---
|
||||
|
||||
## 📊 开发与测试
|
||||
|
||||
### 🔧 开发命令
|
||||
### 🚀 快速测试
|
||||
|
||||
```bash
|
||||
# 启动Godot编辑器
|
||||
godot --editor
|
||||
# 🔌 API接口测试（30秒）
|
||||
python tests/api/quick_test.py
|
||||
|
||||
# 运行项目（无编辑器）
|
||||
godot --main-pack game.pck
|
||||
# 🔍 完整功能测试（2-3分钟）
|
||||
python tests/api/api_client_test.py
|
||||
|
||||
# 导出项目
|
||||
godot --export "Windows Desktop" game.exe
|
||||
|
||||
# 运行测试
|
||||
godot --headless --script tests/run_tests.gd
|
||||
# 🎮 UI交互测试（在Godot中运行）
|
||||
# 打开 tests/auth/auth_ui_test.tscn 场景
|
||||
```
|
||||
|
||||
### 🧪 测试命令
|
||||
|
||||
```bash
|
||||
# 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测试**: 认证流程完整测试 ✅
|
||||
- **错误处理**: 边界条件和异常测试 ✅
|
||||
- **性能测试**: 帧率和内存监控 ✅
|
||||
|
||||
---
|
||||
|
||||
## 🌍 部署配置
|
||||
## 🚀 部署发布
|
||||
|
||||
### 🖥️ 桌面版本
|
||||
|
||||
### 开发环境（默认）
|
||||
```bash
|
||||
# 本地开发配置
|
||||
API_BASE_URL=http://localhost:3000
|
||||
DEBUG_MODE=true
|
||||
LOG_LEVEL=debug
|
||||
# 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版本
|
||||
|
||||
```bash
|
||||
# 生产环境配置
|
||||
API_BASE_URL=https://your-api-server.com
|
||||
DEBUG_MODE=false
|
||||
LOG_LEVEL=info
|
||||
ENABLE_ANALYTICS=true
|
||||
# 使用自动化脚本
|
||||
scripts/build_web.bat # Windows
|
||||
scripts/build_web.sh # Linux/macOS
|
||||
|
||||
# 本地测试
|
||||
scripts/serve_web.bat # 启动本地服务器
|
||||
```
|
||||
|
||||
### 导出设置
|
||||
- **Windows**: 64位可执行文件
|
||||
- **Linux**: AppImage格式
|
||||
- **macOS**: .app应用包
|
||||
- **Android**: APK安装包（规划中）
|
||||
**详细部署流程**: [Web部署指南](docs/05-部署运维/Web部署指南.md)
|
||||
|
||||
---
|
||||
|
||||
## 📚 文档中心
|
||||
## 📊 项目统计
|
||||
|
||||
### 🎯 新手必读
|
||||
1. **[项目结构详解](./docs/project_structure.md)** - 架构设计和组织规则
|
||||
2. **[命名规范](./docs/naming_convention.md)** - 代码和资源命名标准
|
||||
3. **[代码注释规范](./docs/code_comment_guide.md)** - 注释标准和AI辅助
|
||||
4. **[Git提交规范](./docs/git_commit_guide.md)** - 版本控制最佳实践
|
||||
### 📚 文档系统
|
||||
|
||||
### 📖 功能文档
|
||||
- **[用户认证系统](./docs/auth/)** - 认证流程和界面设计
|
||||
- **[API接口文档](./docs/api-documentation.md)** - 完整的API使用指南
|
||||
- **[测试指南](./tests/api/README.md)** - 测试用例和使用方法
|
||||
| 类别 | 文档数 | 完成度 |
|
||||
|------|--------|--------|
|
||||
| 项目入门 | 3 | 100% |
|
||||
| 开发规范 | 5 | 100% |
|
||||
| 技术实现 | 4 | 100% |
|
||||
| 高级开发 | 3 | 100% |
|
||||
| 部署运维 | 1 | 100% |
|
||||
| 功能模块 | 2 | 100% |
|
||||
| **总计** | **18** | **100%** |
|
||||
|
||||
### 🏗️ 开发指南
|
||||
- **[模块开发指南](./docs/module_development.md)** - 如何创建新模块
|
||||
- **[场景设计规范](./docs/scene_design.md)** - 场景架构和最佳实践
|
||||
- **[性能优化指南](./docs/performance_guide.md)** - 性能调优技巧
|
||||
### 🧪 测试覆盖
|
||||
|
||||
- **API接口**: 17个接口 ✅
|
||||
- **认证流程**: 完整测试 ✅
|
||||
- **错误处理**: 边界测试 ✅
|
||||
- **性能监控**: 帧率/内存 ✅
|
||||
|
||||
---
|
||||
|
||||
## 🤝 贡献者
|
||||
## 🤝 参与贡献
|
||||
|
||||
感谢所有为项目做出贡献的开发者！
|
||||
|
||||
### 🏆 核心团队
|
||||
- **[moyin](https://gitea.xinghangee.icu/moyin)** - 核心开发者
|
||||
- **[jianuo](https://gitea.xinghangee.icu/jianuo)** - 核心开发者
|
||||
- **[angjustinl](https://gitea.xinghangee.icu/ANGJustinl)** - 核心开发者
|
||||
|
||||
查看完整贡献者名单：[docs/CONTRIBUTORS.md](./docs/CONTRIBUTORS.md)
|
||||
|
||||
### 🌟 如何贡献
|
||||
|
||||
我们欢迎所有形式的贡献：
|
||||
### 🌟 贡献方式
|
||||
|
||||
1. **🐛 Bug修复** - 发现并修复问题
|
||||
2. **✨ 新功能** - 添加有价值的功能
|
||||
2. **✨ 新功能** - 添加有价值的功能
|
||||
3. **📚 文档改进** - 完善项目文档
|
||||
4. **🧪 测试用例** - 提高代码覆盖率
|
||||
5. **🎨 UI/UX改进** - 提升用户体验
|
||||
6. **⚡ 性能优化** - 优化游戏性能
|
||||
|
||||
**贡献流程：**
|
||||
1. Fork项目 → 2. 创建分支 → 3. 开发功能 → 4. 提交PR
|
||||
### 📋 贡献流程
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
### 📖 开发规范
|
||||
|
||||
**必读文档**：
|
||||
- [命名规范](docs/02-开发规范/命名规范.md) - 代码命名标准
|
||||
- [Git提交规范](docs/02-开发规范/Git提交规范.md) - 提交信息格式
|
||||
- [代码注释规范](docs/02-开发规范/代码注释规范.md) - 注释标准
|
||||
|
||||
### 🙏 贡献者致谢
|
||||
|
||||
感谢所有为 WhaleTown 项目做出贡献的开发者们！详细的贡献者信息和统计请查看：
|
||||
|
||||
**[📖 贡献者详细信息](docs/CONTRIBUTORS.md)**
|
||||
|
||||
---
|
||||
|
||||
## 📞 联系我们
|
||||
## 📞 获取帮助
|
||||
|
||||
### 🔍 问题解决
|
||||
|
||||
| 问题类型 | 解决方案 |
|
||||
|----------|----------|
|
||||
| **🤔 不知道从哪开始** | [项目入门总览](docs/01-项目入门/README.md) |
|
||||
| **🏗️ 不理解项目架构** | [项目结构说明](docs/01-项目入门/项目结构说明.md) |
|
||||
| **🔧 开发环境问题** | [项目设置指南](docs/01-项目入门/项目设置指南.md) |
|
||||
| **📝 不知道怎么命名** | [命名规范](docs/02-开发规范/命名规范.md) |
|
||||
| **🔄 组件通信问题** | [架构与通信规范](docs/02-开发规范/架构与通信规范.md) |
|
||||
| **🌐 API调用问题** | [API接口文档](docs/03-技术实现/API接口文档.md) |
|
||||
| **🧪 测试相关问题** | [测试指南](docs/03-技术实现/测试指南.md) |
|
||||
| **🚀 部署发布问题** | [Web部署指南](docs/05-部署运维/Web部署指南.md) |
|
||||
|
||||
### 📚 文档导航
|
||||
|
||||
- **[📖 完整文档中心](docs/README.md)** - 所有文档的导航页面
|
||||
- **[📋 文档更新日志](docs/CHANGELOG.md)** - 文档版本变更记录
|
||||
|
||||
### 💬 联系方式
|
||||
|
||||
- **项目地址**: [Gitea Repository](https://gitea.xinghangee.icu/datawhale/whale-town)
|
||||
- **问题反馈**: [Issues](https://gitea.xinghangee.icu/datawhale/whale-town/issues)
|
||||
- **功能建议**: [Discussions](https://gitea.xinghangee.icu/datawhale/whale-town/discussions)
|
||||
|
||||
---
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
本项目采用 [MIT License](./LICENSE) 开源协议。
|
||||
@@ -368,10 +352,12 @@ ENABLE_ANALYTICS=true
|
||||
|
||||
<div align="center">
|
||||
|
||||
**🐋 Whale Town - 让像素世界更精彩！**
|
||||
**🐋 WhaleTown - 企业级像素游戏开发框架**
|
||||
|
||||
Made with ❤️ by the Whale Town Team
|
||||
*让游戏开发更简单，让代码质量更优秀*
|
||||
|
||||
[⭐ Star](https://gitea.xinghangee.icu/datawhale/whale-town) | [🍴 Fork](https://gitea.xinghangee.icu/datawhale/whale-town/fork) | [📖 Docs](./docs/) | [🐛 Issues](https://gitea.xinghangee.icu/datawhale/whale-town/issues)
|
||||
[⭐ Star](https://gitea.xinghangee.icu/datawhale/whale-town) | [🍴 Fork](https://gitea.xinghangee.icu/datawhale/whale-town/fork) | [📖 文档](./docs/) | [🐛 反馈](https://gitea.xinghangee.icu/datawhale/whale-town/issues)
|
||||
|
||||
</div>
|
||||
**文档版本**: v1.2.0 | **最后更新**: 2025-12-31
|
||||
|
||||
</div>
|
||||
58
_Core/EventNames.gd
Normal file
58
_Core/EventNames.gd
Normal file
@@ -0,0 +1,58 @@
|
||||
# ============================================================================
|
||||
# 事件名称定义 - EventNames.gd
|
||||
#
|
||||
# 定义项目中所有事件的名称常量，确保事件名称的一致性和可维护性
|
||||
#
|
||||
# 使用方式:
|
||||
# EventSystem.emit_event(EventNames.PLAYER_MOVED, data)
|
||||
# EventSystem.connect_event(EventNames.INTERACT_PRESSED, callback)
|
||||
# ============================================================================
|
||||
|
||||
class_name EventNames
|
||||
|
||||
# ============================================================================
|
||||
# 玩家相关事件
|
||||
# ============================================================================
|
||||
const PLAYER_MOVED = "player_moved"
|
||||
const PLAYER_SPAWNED = "player_spawned"
|
||||
const PLAYER_HEALTH_CHANGED = "player_health_changed"
|
||||
const PLAYER_DIED = "player_died"
|
||||
const PLAYER_RESPAWNED = "player_respawned"
|
||||
const PLAYER_ATTACK = "player_attack"
|
||||
|
||||
# ============================================================================
|
||||
# 交互事件
|
||||
# ============================================================================
|
||||
const INTERACT_PRESSED = "interact_pressed"
|
||||
const NPC_TALKED = "npc_talked"
|
||||
const ITEM_COLLECTED = "item_collected"
|
||||
const OBJECT_INTERACTED = "object_interacted"
|
||||
|
||||
# ============================================================================
|
||||
# UI事件
|
||||
# ============================================================================
|
||||
const UI_BUTTON_CLICKED = "ui_button_clicked"
|
||||
const DIALOG_OPENED = "dialog_opened"
|
||||
const DIALOG_CLOSED = "dialog_closed"
|
||||
const MENU_OPENED = "menu_opened"
|
||||
const MENU_CLOSED = "menu_closed"
|
||||
|
||||
# ============================================================================
|
||||
# 游戏状态事件
|
||||
# ============================================================================
|
||||
const GAME_PAUSED = "game_paused"
|
||||
const GAME_RESUMED = "game_resumed"
|
||||
const SCENE_CHANGED = "scene_changed"
|
||||
const SCENE_DATA_TRANSFER = "scene_data_transfer"
|
||||
|
||||
# ============================================================================
|
||||
# 系统事件
|
||||
# ============================================================================
|
||||
const TILEMAP_READY = "tilemap_ready"
|
||||
const COMPONENT_MESSAGE = "component_message"
|
||||
const POSITION_UPDATE = "position_update"
|
||||
|
||||
# ============================================================================
|
||||
# 测试事件
|
||||
# ============================================================================
|
||||
const TEST_EVENT = "test_event"
|
||||
1
_Core/EventNames.gd.uid
Normal file
1
_Core/EventNames.gd.uid
Normal file
@@ -0,0 +1 @@
|
||||
uid://qn0imbklx1m0
|
||||
107
_Core/ProjectPaths.gd
Normal file
107
_Core/ProjectPaths.gd
Normal file
@@ -0,0 +1,107 @@
|
||||
# ============================================================================
|
||||
# 项目路径配置 - ProjectPaths.gd
|
||||
#
|
||||
# 统一管理项目中所有路径常量，确保路径的一致性和可维护性
|
||||
#
|
||||
# 使用方式:
|
||||
# var scene_path = ProjectPaths.SCENES_COMPONENTS + "ui/Button.tscn"
|
||||
# var config_path = ProjectPaths.DATA_CONFIG + "game_config.json"
|
||||
# ============================================================================
|
||||
|
||||
class_name ProjectPaths
|
||||
|
||||
# ============================================================================
|
||||
# 核心系统路径
|
||||
# ============================================================================
|
||||
const CORE_ROOT = "res://_Core/"
|
||||
const CORE_MANAGERS = CORE_ROOT + "managers/"
|
||||
const CORE_SYSTEMS = CORE_ROOT + "systems/"
|
||||
|
||||
# ============================================================================
|
||||
# 场景路径
|
||||
# ============================================================================
|
||||
const SCENES_ROOT = "res://scenes/"
|
||||
const SCENES_MAPS = SCENES_ROOT + "Maps/"
|
||||
const SCENES_COMPONENTS = SCENES_ROOT + "Components/"
|
||||
const SCENES_UI_COMPONENTS = SCENES_COMPONENTS + "ui/"
|
||||
const SCENES_CHARACTER_COMPONENTS = SCENES_COMPONENTS + "characters/"
|
||||
const SCENES_EFFECT_COMPONENTS = SCENES_COMPONENTS + "effects/"
|
||||
const SCENES_ITEM_COMPONENTS = SCENES_COMPONENTS + "items/"
|
||||
|
||||
# ============================================================================
|
||||
# UI路径
|
||||
# ============================================================================
|
||||
const UI_ROOT = "res://UI/"
|
||||
const UI_WINDOWS = UI_ROOT + "Windows/"
|
||||
|
||||
# ============================================================================
|
||||
# 资源路径
|
||||
# ============================================================================
|
||||
const ASSETS_ROOT = "res://assets/"
|
||||
const ASSETS_SPRITES = ASSETS_ROOT + "sprites/"
|
||||
const ASSETS_AUDIO = ASSETS_ROOT + "audio/"
|
||||
const ASSETS_FONTS = ASSETS_ROOT + "fonts/"
|
||||
const ASSETS_MATERIALS = ASSETS_ROOT + "materials/"
|
||||
const ASSETS_SHADERS = ASSETS_ROOT + "shaders/"
|
||||
|
||||
# ============================================================================
|
||||
# 数据路径
|
||||
# ============================================================================
|
||||
const DATA_ROOT = "res://data/"
|
||||
const DATA_CONFIG = "res://Config/"
|
||||
const DATA_SCENES = DATA_ROOT + "scenes/"
|
||||
const DATA_LEVELS = DATA_ROOT + "levels/"
|
||||
const DATA_DIALOGUES = DATA_ROOT + "dialogues/"
|
||||
|
||||
# ============================================================================
|
||||
# Web资源路径
|
||||
# ============================================================================
|
||||
const WEB_ASSETS = "res://web_assets/"
|
||||
|
||||
# ============================================================================
|
||||
# 测试路径
|
||||
# ============================================================================
|
||||
const TESTS_ROOT = "res://tests/"
|
||||
const TESTS_UNIT = TESTS_ROOT + "unit/"
|
||||
const TESTS_INTEGRATION = TESTS_ROOT + "integration/"
|
||||
const TESTS_AUTH = TESTS_ROOT + "auth/"
|
||||
|
||||
# ============================================================================
|
||||
# 工具路径
|
||||
# ============================================================================
|
||||
const UTILS_ROOT = "res://Utils/"
|
||||
|
||||
# ============================================================================
|
||||
# 模块路径
|
||||
# ============================================================================
|
||||
const MODULES_ROOT = "res://module/"
|
||||
|
||||
# ============================================================================
|
||||
# 辅助方法
|
||||
# ============================================================================
|
||||
|
||||
# 获取场景组件路径
|
||||
static func get_component_path(category: String, component_name: String) -> String:
|
||||
match category:
|
||||
"ui":
|
||||
return SCENES_UI_COMPONENTS + component_name + ".tscn"
|
||||
"characters":
|
||||
return SCENES_CHARACTER_COMPONENTS + component_name + ".tscn"
|
||||
"effects":
|
||||
return SCENES_EFFECT_COMPONENTS + component_name + ".tscn"
|
||||
"items":
|
||||
return SCENES_ITEM_COMPONENTS + component_name + ".tscn"
|
||||
_:
|
||||
return SCENES_COMPONENTS + component_name + ".tscn"
|
||||
|
||||
# 获取模块路径
|
||||
static func get_module_path(module_name: String) -> String:
|
||||
return MODULES_ROOT + module_name + "/"
|
||||
|
||||
# 获取模块配置路径
|
||||
static func get_module_config_path(module_name: String) -> String:
|
||||
return get_module_path(module_name) + "data/module_config.json"
|
||||
|
||||
# 获取场景数据路径
|
||||
static func get_scene_data_path(scene_name: String) -> String:
|
||||
return DATA_SCENES + scene_name.to_lower() + ".json"
|
||||
1
_Core/ProjectPaths.gd.uid
Normal file
1
_Core/ProjectPaths.gd.uid
Normal file
@@ -0,0 +1 @@
|
||||
uid://dybcuscku7tyl
|
||||
@@ -1,6 +1,6 @@
|
||||
[gd_resource type="Theme" load_steps=2 format=3 uid="uid://cp7t8tu7rmyad"]
|
||||
|
||||
[ext_resource type="FontFile" uid="uid://ce7ujbeobblyr" path="res://assets/fonts/msyh.ttc" id="1_ftb5w"]
|
||||
[ext_resource type="FontFile" uid="uid://ce7ujbeobblyr" path="res://UI/Theme/Fonts/msyh.ttc" id="1_ftb5w"]
|
||||
|
||||
[resource]
|
||||
resource_local_to_scene = true
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
# 📖 项目入门
|
||||
|
||||
> **适用人群**: 新加入项目的开发者
|
||||
> **使用时机**: 项目开始前，环境搭建阶段
|
||||
> **使用时机**: 项目开始前，环境搭建阶段
|
||||
> **质量等级**: A级 ⭐⭐⭐⭐⭐
|
||||
|
||||
这个目录包含了新人入门必读的基础文档，帮助你快速了解项目并搭建开发环境。
|
||||
|
||||
@@ -10,59 +11,75 @@
|
||||
### 第一步：了解项目 🏗️
|
||||
**[项目结构说明.md](项目结构说明.md)**
|
||||
- 项目整体架构设计
|
||||
- 目录组织规则
|
||||
- 目录组织规则和命名规范
|
||||
- 各层级职责说明
|
||||
- 团队协作方式
|
||||
- 核心组件介绍
|
||||
|
||||
### 第二步：配置环境 ⚙️
|
||||
**[项目设置指南.md](项目设置指南.md)**
|
||||
- Godot编辑器配置
|
||||
- AutoLoad单例设置
|
||||
- 输入映射配置（已预配置）
|
||||
- 开发环境验证
|
||||
|
||||
### 第三步：设置控制 🎮 **[必需]**
|
||||
**[输入映射配置.md](输入映射配置.md)**
|
||||
- 游戏输入控制配置
|
||||
- 键盘和手柄映射
|
||||
- 输入系统测试
|
||||
|
||||
⚠️ **重要提醒**: 输入映射配置是必需的！项目代码中使用了 `move_left`、`move_right`、`move_up`、`move_down`、`interact`、`pause` 等输入动作，必须在Godot编辑器中正确配置，否则游戏无法正常运行。
|
||||
|
||||
## ✅ 完成检查
|
||||
|
||||
阅读完本目录的文档后，你应该能够：
|
||||
- [ ] 理解项目的整体架构
|
||||
- [ ] 理解项目的整体架构和设计理念
|
||||
- [ ] 成功配置Godot开发环境
|
||||
- [ ] **正确设置游戏输入映射** ⚠️ 必需
|
||||
- [ ] 了解核心组件的作用和使用方式
|
||||
- [ ] 运行项目并进行基本测试
|
||||
- [ ] 验证所有AutoLoad单例正常工作
|
||||
- [ ] 确认游戏输入控制正常响应
|
||||
|
||||
## 🎮 输入控制说明
|
||||
|
||||
项目已预配置以下输入映射：
|
||||
- **移动控制**: `move_left` (A/←), `move_right` (D/→), `move_up` (W/↑), `move_down` (S/↓)
|
||||
- **交互控制**: `interact` (E键), `jump` (空格键)
|
||||
|
||||
这些输入映射已经在 `project.godot` 中配置完成，无需额外设置。
|
||||
|
||||
## 🚨 常见启动问题
|
||||
|
||||
### 问题1: 游戏无法响应输入
|
||||
**原因**: 输入映射未配置
|
||||
**解决**: 必须完成 [输入映射配置.md](输入映射配置.md) 中的所有步骤
|
||||
**原因**: 项目文件损坏或配置丢失
|
||||
**解决**: 重新克隆项目，确保 `project.godot` 文件完整
|
||||
|
||||
### 问题2: 控制台出现"Invalid action"错误
|
||||
**原因**: 缺少必需的输入动作
|
||||
**解决**: 确保配置了以下6个输入动作：
|
||||
- `move_left`, `move_right`, `move_up`, `move_down`
|
||||
- `interact`, `pause`
|
||||
**原因**: 输入映射配置丢失
|
||||
**解决**: 检查 `project.godot` 文件中的 `[input]` 部分是否完整
|
||||
|
||||
### 问题3: AutoLoad单例报错
|
||||
**原因**: AutoLoad配置不正确
|
||||
**原因**: AutoLoad配置不正确或文件路径错误
|
||||
**解决**: 参考 [项目设置指南.md](项目设置指南.md) 验证配置
|
||||
|
||||
### 问题4: EventSystem相关错误
|
||||
**原因**: 缺少 `_Core/EventNames.gd` 文件
|
||||
**解决**: 确保项目包含完整的 `_Core` 目录结构
|
||||
|
||||
## 🔗 下一步
|
||||
|
||||
完成项目入门后，建议继续阅读：
|
||||
- [02-开发规范](../02-开发规范/) - 学习编码标准
|
||||
- [03-技术实现](../03-技术实现/) - 开始具体开发
|
||||
- [02-开发规范](../02-开发规范/) - 学习编码标准和架构规范
|
||||
- [03-技术实现](../03-技术实现/) - 开始具体功能开发
|
||||
|
||||
## 💡 小贴士
|
||||
|
||||
- **输入映射是第一优先级** - 不配置输入映射，游戏无法正常运行
|
||||
- **项目已预配置完成** - 输入映射和核心组件都已设置好
|
||||
- 遇到问题时，先查看对应文档的"常见问题"部分
|
||||
- 建议在实际操作中边读边做，加深理解
|
||||
- 可以将重要的配置信息做笔记备用
|
||||
- 完成每个步骤后，建议运行项目验证配置是否正确
|
||||
- 完成每个步骤后，建议运行项目验证配置是否正确
|
||||
- 重点关注 `_Core` 目录中的核心组件，它们是项目的基础
|
||||
|
||||
## 🛠️ 核心组件预览
|
||||
|
||||
项目包含以下核心组件，在后续开发中会频繁使用：
|
||||
- **EventSystem** - 全局事件通信系统
|
||||
- **GameManager** - 游戏状态管理
|
||||
- **SceneManager** - 场景切换管理
|
||||
- **NetworkManager** - 网络请求管理
|
||||
- **ProjectPaths** - 统一路径管理
|
||||
|
||||
详细使用方法请参考 [架构与通信规范](../02-开发规范/架构与通信规范.md)。
|
||||
@@ -102,7 +102,7 @@ func _exit_tree() -> void:
|
||||
## 🎯 单例管理器
|
||||
|
||||
### 允许的自动加载单例
|
||||
项目中只允许以下三个单例：
|
||||
项目中允许以下五个核心单例：
|
||||
|
||||
1. **GameManager** - 游戏状态管理
|
||||
- 路径: `_Core/managers/GameManager.gd`
|
||||
@@ -116,6 +116,14 @@ func _exit_tree() -> void:
|
||||
- 路径: `_Core/systems/EventSystem.gd`
|
||||
- 职责: 全局事件通信
|
||||
|
||||
4. **NetworkManager** - 网络管理
|
||||
- 路径: `_Core/managers/NetworkManager.gd`
|
||||
- 职责: HTTP请求、API调用、网络状态管理
|
||||
|
||||
5. **ResponseHandler** - 响应处理
|
||||
- 路径: `_Core/managers/ResponseHandler.gd`
|
||||
- 职责: 统一响应处理、错误处理、用户反馈
|
||||
|
||||
### 单例使用规范
|
||||
```gdscript
|
||||
# ✅ 正确：高层组件可以访问单例
|
||||
|
||||
@@ -13,7 +13,7 @@ NetworkManager 是一个统一的网络请求管理器，提供了简洁的API
|
||||
1. 打开 `Project` → `Project Settings`
|
||||
2. 切换到 `AutoLoad` 标签
|
||||
3. 添加新的AutoLoad：
|
||||
- **Path**: `res://core/managers/NetworkManager.gd`
|
||||
- **Path**: `res://_Core/managers/NetworkManager.gd`
|
||||
- **Name**: `NetworkManager`
|
||||
- **Singleton**: ✅ 勾选
|
||||
|
||||
@@ -24,7 +24,7 @@ NetworkManager 是一个统一的网络请求管理器，提供了简洁的API
|
||||
```ini
|
||||
[autoload]
|
||||
|
||||
NetworkManager="*res://core/managers/NetworkManager.gd"
|
||||
NetworkManager="*res://_Core/managers/NetworkManager.gd"
|
||||
```
|
||||
|
||||
### 3. 验证设置
|
||||
|
||||
@@ -22,29 +22,29 @@
|
||||
### 标准目录结构
|
||||
```
|
||||
scenes/
|
||||
├── main_scene.tscn # 主场景
|
||||
├── auth_scene.tscn # 认证场景
|
||||
├── game_scene.tscn # 游戏场景
|
||||
├── settings_scene.tscn # 设置场景
|
||||
└── prefabs/ # 预制体组件
|
||||
├── ui/ # UI组件
|
||||
│ ├── button.tscn
|
||||
│ ├── dialog.tscn
|
||||
│ └── menu.tscn
|
||||
├── characters/ # 角色组件
|
||||
│ ├── player.tscn
|
||||
│ └── npc.tscn
|
||||
├── effects/ # 特效组件
|
||||
│ ├── particle_effect.tscn
|
||||
│ └── animation_effect.tscn
|
||||
└── items/ # 物品组件
|
||||
├── collectible.tscn
|
||||
└── interactive.tscn
|
||||
├── Maps/ # 地图场景
|
||||
│ ├── main_scene.tscn # 主场景
|
||||
│ └── game_scene.tscn # 游戏场景
|
||||
├── Components/ # 组件预制体
|
||||
│ ├── ui/ # UI组件
|
||||
│ │ ├── button.tscn
|
||||
│ │ ├── dialog.tscn
|
||||
│ │ └── menu.tscn
|
||||
│ ├── characters/ # 角色组件
|
||||
│ │ ├── player.tscn
|
||||
│ │ └── npc.tscn
|
||||
│ ├── effects/ # 特效组件
|
||||
│ │ ├── particle_effect.tscn
|
||||
│ │ └── animation_effect.tscn
|
||||
│ └── items/ # 物品组件
|
||||
│ ├── collectible.tscn
|
||||
│ └── interactive.tscn
|
||||
└── auth_scene.tscn # 认证场景
|
||||
```
|
||||
|
||||
### 场景命名规范
|
||||
- **主场景**: `scene_name.tscn` (snake_case)
|
||||
- **预制体**: `component_name.tscn` (snake_case)
|
||||
- **主场景**: `SceneName.tscn` (PascalCase)
|
||||
- **组件预制体**: `ComponentName.tscn` (PascalCase)
|
||||
- **脚本文件**: `SceneName.gd` (PascalCase)
|
||||
- **节点名称**: `NodeName` (PascalCase) 或 `nodeName` (camelCase)
|
||||
|
||||
@@ -149,7 +149,7 @@ func initialize_scene():
|
||||
func load_scene_data():
|
||||
"""加载场景数据"""
|
||||
# 从配置文件或网络加载场景数据
|
||||
var data_path = "res://data/scenes/%s.json" % SCENE_NAME.to_lower()
|
||||
var data_path = ProjectPaths.get_scene_data_path(SCENE_NAME)
|
||||
if FileAccess.file_exists(data_path):
|
||||
var file = FileAccess.open(data_path, FileAccess.READ)
|
||||
if file:
|
||||
|
||||
@@ -87,9 +87,9 @@ func return_object(obj: Node, type: String):
|
||||
func _create_new_object(type: String) -> Node:
|
||||
match type:
|
||||
"Bullet":
|
||||
return preload("res://prefabs/Bullet.tscn").instantiate()
|
||||
return preload(ProjectPaths.get_component_path("effects", "Bullet")).instantiate()
|
||||
"Enemy":
|
||||
return preload("res://prefabs/Enemy.tscn").instantiate()
|
||||
return preload(ProjectPaths.get_component_path("characters", "Enemy")).instantiate()
|
||||
_:
|
||||
return null
|
||||
```
|
||||
|
||||
@@ -129,7 +129,7 @@ func get_module_info() -> Dictionary:
|
||||
# 私有方法
|
||||
func _load_config() -> bool:
|
||||
"""加载模块配置"""
|
||||
var config_path = "res://module/%s/data/module_config.json" % MODULE_NAME
|
||||
var config_path = ProjectPaths.get_module_config_path(MODULE_NAME)
|
||||
if not FileAccess.file_exists(config_path):
|
||||
print("警告: 模块配置文件不存在: ", config_path)
|
||||
return true # 使用默认配置
|
||||
@@ -270,7 +270,7 @@ func update_data(data_type: String, new_data: Dictionary):
|
||||
|
||||
```gdscript
|
||||
# tests/test_your_module.gd
|
||||
extends "res://addons/gut/test.gd"
|
||||
extends GutTest
|
||||
|
||||
var module: YourModule
|
||||
|
||||
|
||||
@@ -66,13 +66,13 @@ Dedicated Server: ✗ 禁用
|
||||
Variant: release
|
||||
Vram Texture Compression: ✓ 启用
|
||||
Export Type: Regular
|
||||
Custom HTML Shell: res://assets/web/custom_shell.html
|
||||
Custom HTML Shell: res://web_assets/custom_shell.html
|
||||
Head Include: (留空，已在自定义模板中配置)
|
||||
```
|
||||
|
||||
#### 高级选项
|
||||
```
|
||||
Custom HTML Shell: res://assets/web/custom_shell.html
|
||||
Custom HTML Shell: res://web_assets/custom_shell.html
|
||||
Progressive Web App: ✓ 启用（可选）
|
||||
Icon 144x144: res://icon.svg
|
||||
Icon 180x180: res://icon.svg
|
||||
|
||||
65
docs/CHANGELOG.md
Normal file
65
docs/CHANGELOG.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# 文档更新日志
|
||||
|
||||
本文档记录了WhaleTown项目文档的重要更新和修改。
|
||||
|
||||
## 版本 1.1.0 (2025-12-31)
|
||||
|
||||
### 🆕 新增内容
|
||||
- **新增**: `_Core/EventNames.gd` - 统一管理所有事件名称常量
|
||||
- **新增**: `_Core/ProjectPaths.gd` - 统一管理项目路径配置
|
||||
- **新增**: 输入映射配置到 `project.godot`
|
||||
- **新增**: 文档更新日志 `docs/CHANGELOG.md`
|
||||
|
||||
### 🔧 修复问题
|
||||
- **修复**: 架构与通信规范中AutoLoad单例数量描述（从3个更新为5个）
|
||||
- **修复**: 网络管理器设置文档中的路径错误（`core/` → `_Core/`）
|
||||
- **修复**: Web部署指南中的资源路径（`assets/web/` → `web_assets/`）
|
||||
- **修复**: 场景设计规范中的目录结构（`prefabs/` → `Components/`）
|
||||
- **修复**: 性能优化指南中的预制体路径
|
||||
- **修复**: 模块开发指南中的测试基类路径（使用 `GutTest` 而非完整路径）
|
||||
|
||||
### 📝 内容优化
|
||||
- **优化**: 场景命名规范，与实际项目结构保持一致
|
||||
- **优化**: 所有文档中的路径引用，使用 `ProjectPaths` 统一管理
|
||||
- **优化**: 代码示例的准确性和可用性
|
||||
|
||||
### 🎯 质量提升
|
||||
- **提升**: 文档与实际代码的匹配度
|
||||
- **提升**: 路径配置的一致性和可维护性
|
||||
- **提升**: 开发者体验和文档可用性
|
||||
|
||||
## 版本 1.0.0 (2025-12-24)
|
||||
|
||||
### 📚 初始文档结构
|
||||
- **01-项目入门**: 项目介绍、结构说明、设置指南
|
||||
- **02-开发规范**: 命名规范、注释规范、Git提交规范、架构规范、开发哲学
|
||||
- **03-技术实现**: 实现细节、API文档、网络管理器、测试指南
|
||||
- **04-高级开发**: 场景设计、模块开发、性能优化
|
||||
- **05-部署运维**: Web部署指南
|
||||
- **06-功能模块**: 认证模块相关文档
|
||||
|
||||
### 🏗️ 核心特性
|
||||
- 完整的开发规范体系
|
||||
- 详细的技术实现指导
|
||||
- 全面的测试和部署流程
|
||||
- 模块化的功能开发指南
|
||||
|
||||
---
|
||||
|
||||
## 维护说明
|
||||
|
||||
### 文档更新原则
|
||||
1. **同步更新**: 代码变更时同步更新相关文档
|
||||
2. **版本记录**: 重要更新需要在此日志中记录
|
||||
3. **向后兼容**: 尽量保持API和配置的向后兼容性
|
||||
4. **质量保证**: 确保文档内容的准确性和可用性
|
||||
|
||||
### 贡献指南
|
||||
- 发现文档问题请及时反馈
|
||||
- 提交文档更新时请更新此日志
|
||||
- 重大变更需要团队讨论确认
|
||||
|
||||
### 相关链接
|
||||
- [项目结构说明](01-项目入门/项目结构说明.md)
|
||||
- [开发规范总览](02-开发规范/README.md)
|
||||
- [技术实现指南](03-技术实现/README.md)
|
||||
122
docs/CONTRIBUTORS.md
Normal file
122
docs/CONTRIBUTORS.md
Normal file
@@ -0,0 +1,122 @@
|
||||
# 🤝 项目贡献者
|
||||
|
||||
感谢所有为WhaleTown项目做出贡献的开发者！
|
||||
|
||||
## 🏆 核心贡献者
|
||||
|
||||
### 主要开发者
|
||||
|
||||
#### 王浩
|
||||
- **贡献数量**: 3+ commits
|
||||
- **主要贡献**:
|
||||
- 🏗️ 项目架构分层结构重构
|
||||
- 📚 AI开发规范文档制定
|
||||
- 📖 项目开发规范文档完善
|
||||
|
||||
#### moyin
|
||||
- **贡献数量**: 35+ commits
|
||||
- **主要贡献**:
|
||||
- 🔧 项目功能开发和实现
|
||||
- 📝 文档内容编写和维护
|
||||
- 🧪 测试用例开发和验证
|
||||
- 🌐 网络系统和部署配置
|
||||
|
||||
## 📊 贡献统计
|
||||
|
||||
### 按贡献类型
|
||||
|
||||
| 贡献类型 | 主要贡献者 | 说明 |
|
||||
|----------|------------|------|
|
||||
| **架构设计** | 王浩, moyin | 分层结构重构，模块化架构 |
|
||||
| **开发规范** | 王浩 | AI开发规范、编码标准 |
|
||||
| **文档建设** | moyin, 王浩 | 18个完整文档，覆盖全开发流程 |
|
||||
| **网络系统** | moyin | NetworkManager、API集成 |
|
||||
| **测试框架** | moyin | API测试、UI测试、性能测试 |
|
||||
| **认证系统** | moyin | 用户认证流程实现 |
|
||||
| **部署系统** | moyin | Web部署、自动化脚本 |
|
||||
|
||||
### 按时间线
|
||||
|
||||
#### 2024年12月
|
||||
- **架构重构**: 王浩 实施分层架构重构
|
||||
- **规范制定**: 王浩 制定AI开发规范
|
||||
- **项目开发**: moyin 完成主要功能开发
|
||||
- **文档建设**: moyin, 王浩 建设文档系统
|
||||
- **测试集成**: moyin 完成API集成和测试
|
||||
|
||||
## 🌟 贡献亮点
|
||||
|
||||
### 🏗️ 架构设计
|
||||
- **分层结构**: 清晰的代码组织和职责分离
|
||||
- **模块化架构**: 高度解耦的组件系统
|
||||
- **事件驱动**: 基于EventSystem的通信机制
|
||||
|
||||
### 📚 文档建设
|
||||
- **企业级文档**: 18个完整文档，100%覆盖
|
||||
- **分类组织**: 按开发阶段精心分类
|
||||
- **实用导向**: 大量可直接使用的代码模板
|
||||
|
||||
### 🎯 开发规范
|
||||
- **AI开发规范**: AI辅助开发的最佳实践
|
||||
- **编码标准**: 统一的命名规范和代码风格
|
||||
- **质量保证**: 完善的代码审查流程
|
||||
|
||||
### 🧪 测试体系
|
||||
- **多层测试**: API、UI、单元、集成测试
|
||||
- **自动化**: Python测试脚本和Godot测试场景
|
||||
- **完整覆盖**: 17个API接口全覆盖
|
||||
|
||||
### 🌐 部署系统
|
||||
- **一键部署**: 自动化Web部署脚本
|
||||
- **跨平台**: 支持Windows、Linux、macOS
|
||||
- **配置完善**: 详细的服务器配置指南
|
||||
|
||||
## 🎯 特别感谢
|
||||
|
||||
### 技术贡献
|
||||
- **王浩**: 负责架构重构和开发规范制定
|
||||
- **moyin**: 负责主要功能开发和文档编写
|
||||
|
||||
### 架构贡献
|
||||
- **分层结构**: 提升了项目的代码组织和可维护性
|
||||
- **模块化设计**: 为项目扩展奠定了良好基础
|
||||
- **开发规范**: 统一了团队的开发标准
|
||||
|
||||
## 🚀 如何成为贡献者
|
||||
|
||||
### 贡献方式
|
||||
1. **🐛 Bug修复** - 发现并修复问题
|
||||
2. **✨ 新功能** - 添加有价值的功能
|
||||
3. **📚 文档改进** - 完善项目文档
|
||||
4. **🧪 测试用例** - 提高代码覆盖率
|
||||
5. **🎨 UI/UX改进** - 提升用户体验
|
||||
6. **⚡ 性能优化** - 优化游戏性能
|
||||
|
||||
### 贡献流程
|
||||
1. Fork项目到你的账户
|
||||
2. 创建功能分支：`git checkout -b feature/your-feature`
|
||||
3. 遵循项目规范开发
|
||||
4. 添加测试用例
|
||||
5. 提交代码：`git commit -m "feat：添加新功能"`
|
||||
6. 创建Pull Request
|
||||
|
||||
### 规范要求
|
||||
- 遵循[命名规范](02-开发规范/命名规范.md)
|
||||
- 遵循[Git提交规范](02-开发规范/Git提交规范.md)
|
||||
- 遵循[代码注释规范](02-开发规范/代码注释规范.md)
|
||||
- 添加相应的测试用例
|
||||
- 更新相关文档
|
||||
|
||||
## 📞 联系方式
|
||||
|
||||
如果你想参与贡献或有任何问题：
|
||||
|
||||
- **项目地址**: [Gitea Repository](https://gitea.xinghangee.icu/datawhale/whale-town)
|
||||
- **问题反馈**: [Issues](https://gitea.xinghangee.icu/datawhale/whale-town/issues)
|
||||
- **功能建议**: [Discussions](https://gitea.xinghangee.icu/datawhale/whale-town/discussions)
|
||||
|
||||
---
|
||||
|
||||
**感谢所有贡献者的辛勤付出！每个人的贡献都让WhaleTown项目变得更好。** 🙏
|
||||
|
||||
*最后更新: 2025-12-31*
|
||||
281
docs/README.md
281
docs/README.md
@@ -1,12 +1,21 @@
|
||||
# 📚 WhaleTown 项目文档导航
|
||||
# 📚 WhaleTown 项目文档中心
|
||||
|
||||
欢迎来到WhaleTown项目文档中心！本文档按开发阶段组织，帮助你快速找到所需的文档。
|
||||
欢迎来到WhaleTown项目文档中心！这是一个完整的企业级文档系统，按开发阶段精心组织，帮助你快速找到所需的技术指导。
|
||||
|
||||
## 🎯 文档特色
|
||||
|
||||
- **📋 完整覆盖**: 从项目入门到部署运维的全生命周期
|
||||
- **🎨 结构清晰**: 按开发阶段和角色需求分类组织
|
||||
- **💻 实用导向**: 提供大量可直接使用的代码模板和配置示例
|
||||
- **🔄 持续更新**: 与项目代码保持同步，确保文档准确性
|
||||
- **🧪 测试完备**: 包含详细的测试指南和用例
|
||||
|
||||
## 🗂️ 文档结构
|
||||
|
||||
```
|
||||
docs/
|
||||
├── 📖 README.md # 本导航文档
|
||||
├── 📋 CHANGELOG.md # 文档更新日志
|
||||
├── 📁 01-项目入门/ # 新人必读，项目基础
|
||||
├── 📁 02-开发规范/ # 编码标准和规范
|
||||
├── 📁 03-技术实现/ # 具体开发指导
|
||||
@@ -15,32 +24,47 @@ docs/
|
||||
└── 📁 06-功能模块/ # 特定功能文档
|
||||
```
|
||||
|
||||
## 📊 文档质量等级
|
||||
|
||||
| 等级 | 说明 | 标识 |
|
||||
|------|------|------|
|
||||
| A级 | 企业级标准，内容完整准确 | ⭐⭐⭐⭐⭐ |
|
||||
| B级 | 内容详实，偶有更新需求 | ⭐⭐⭐⭐ |
|
||||
| C级 | 基础完备，持续完善中 | ⭐⭐⭐ |
|
||||
|
||||
**当前整体质量**: **A级** ✨
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速开始指南
|
||||
|
||||
### 👋 我是新人，从哪里开始？
|
||||
**推荐阅读顺序：**
|
||||
1. [项目结构说明](01-项目入门/项目结构说明.md) - 了解项目架构
|
||||
2. [项目设置指南](01-项目入门/项目设置指南.md) - 配置开发环境
|
||||
3. [输入映射配置](01-项目入门/输入映射配置.md) - 设置游戏控制
|
||||
1. [项目入门总览](01-项目入门/README.md) - 快速了解项目
|
||||
2. [项目结构说明](01-项目入门/项目结构说明.md) - 深入了解项目架构
|
||||
3. [项目设置指南](01-项目入门/项目设置指南.md) - 配置开发环境
|
||||
4. [命名规范](02-开发规范/命名规范.md) - 学习编码规范
|
||||
|
||||
### 💻 我要开始编码了
|
||||
**必读文档：**
|
||||
- [架构与通信规范](02-开发规范/架构与通信规范.md) - 组件通信方式
|
||||
- [实现细节规范](03-技术实现/实现细节规范.md) - 具体实现要求
|
||||
- [开发哲学与最佳实践](02-开发规范/开发哲学与最佳实践.md) - 代码质量标准
|
||||
- [架构与通信规范](02-开发规范/架构与通信规范.md) - 组件通信方式 ⭐⭐⭐⭐⭐
|
||||
- [实现细节规范](03-技术实现/实现细节规范.md) - 具体实现要求 ⭐⭐⭐⭐⭐
|
||||
- [开发哲学与最佳实践](02-开发规范/开发哲学与最佳实践.md) - 代码质量标准 ⭐⭐⭐⭐
|
||||
|
||||
### 🔧 我需要集成API
|
||||
**相关文档：**
|
||||
- [API接口文档](03-技术实现/API接口文档.md) - 接口说明
|
||||
- [网络管理器设置](03-技术实现/网络管理器设置.md) - 网络配置
|
||||
- [测试指南](03-技术实现/测试指南.md) - 测试方法
|
||||
- [API接口文档](03-技术实现/API接口文档.md) - 完整的接口说明 ⭐⭐⭐⭐⭐
|
||||
- [网络管理器设置](03-技术实现/网络管理器设置.md) - 网络配置指南 ⭐⭐⭐⭐
|
||||
- [测试指南](03-技术实现/测试指南.md) - API测试方法 ⭐⭐⭐⭐
|
||||
|
||||
### 🚀 我要发布项目
|
||||
**部署文档：**
|
||||
- [Web部署指南](05-部署运维/Web部署指南.md) - Web版本发布
|
||||
- [Web部署指南](05-部署运维/Web部署指南.md) - 完整的Web版本发布流程 ⭐⭐⭐⭐
|
||||
|
||||
### 🔍 我需要调试和优化
|
||||
**高级文档：**
|
||||
- [性能优化指南](04-高级开发/性能优化指南.md) - 全面的性能优化策略 ⭐⭐⭐⭐⭐
|
||||
- [场景设计规范](04-高级开发/场景设计规范.md) - 场景架构最佳实践 ⭐⭐⭐⭐
|
||||
|
||||
---
|
||||
|
||||
@@ -48,84 +72,105 @@ docs/
|
||||
|
||||
### 01-项目入门 📖
|
||||
> **适用人群**: 新加入项目的开发者
|
||||
> **使用时机**: 项目开始前，环境搭建阶段
|
||||
> **使用时机**: 项目开始前，环境搭建阶段
|
||||
> **质量等级**: A级 ⭐⭐⭐⭐⭐
|
||||
|
||||
| 文档 | 用途 | 重要程度 |
|
||||
|------|------|----------|
|
||||
| [项目结构说明.md](01-项目入门/项目结构说明.md) | 了解项目整体架构和目录组织 | ⭐⭐⭐⭐⭐ |
|
||||
| [项目设置指南.md](01-项目入门/项目设置指南.md) | Godot项目配置和AutoLoad设置 | ⭐⭐⭐⭐⭐ |
|
||||
| [输入映射配置.md](01-项目入门/输入映射配置.md) | 游戏输入控制配置方法 | ⭐⭐⭐⭐ |
|
||||
| 文档 | 用途 | 重要程度 | 更新状态 |
|
||||
|------|------|----------|----------|
|
||||
| [README.md](01-项目入门/README.md) | 项目入门总览和快速导航 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [项目结构说明.md](01-项目入门/项目结构说明.md) | 了解项目整体架构和目录组织 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [项目设置指南.md](01-项目入门/项目设置指南.md) | Godot项目配置和AutoLoad设置 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
|
||||
### 02-开发规范 📋
|
||||
> **适用人群**: 所有开发者
|
||||
> **使用时机**: 编码过程中，代码审查时
|
||||
> **使用时机**: 编码过程中，代码审查时
|
||||
> **质量等级**: A级 ⭐⭐⭐⭐⭐
|
||||
|
||||
| 文档 | 用途 | 重要程度 |
|
||||
|------|------|----------|
|
||||
| [命名规范.md](02-开发规范/命名规范.md) | 统一的命名标准 | ⭐⭐⭐⭐⭐ |
|
||||
| [代码注释规范.md](02-开发规范/代码注释规范.md) | 注释格式和标准 | ⭐⭐⭐⭐ |
|
||||
| [Git提交规范.md](02-开发规范/Git提交规范.md) | 版本控制规范 | ⭐⭐⭐⭐ |
|
||||
| [架构与通信规范.md](02-开发规范/架构与通信规范.md) | 组件间通信标准 | ⭐⭐⭐⭐⭐ |
|
||||
| [开发哲学与最佳实践.md](02-开发规范/开发哲学与最佳实践.md) | 代码质量和开发理念 | ⭐⭐⭐⭐ |
|
||||
| 文档 | 用途 | 重要程度 | 更新状态 |
|
||||
|------|------|----------|----------|
|
||||
| [命名规范.md](02-开发规范/命名规范.md) | 统一的命名标准，包含完整示例 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [代码注释规范.md](02-开发规范/代码注释规范.md) | 注释格式和AI辅助注释指南 | ⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [Git提交规范.md](02-开发规范/Git提交规范.md) | 版本控制规范和最佳实践 | ⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [架构与通信规范.md](02-开发规范/架构与通信规范.md) | 事件系统和组件通信标准 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [开发哲学与最佳实践.md](02-开发规范/开发哲学与最佳实践.md) | 代码质量和开发理念 | ⭐⭐⭐⭐ | ✅ 最新 |
|
||||
|
||||
### 03-技术实现 🔧
|
||||
> **适用人群**: 正在开发功能的程序员
|
||||
> **使用时机**: 具体功能开发时
|
||||
> **使用时机**: 具体功能开发时
|
||||
> **质量等级**: A级 ⭐⭐⭐⭐⭐
|
||||
|
||||
| 文档 | 用途 | 重要程度 |
|
||||
|------|------|----------|
|
||||
| [实现细节规范.md](03-技术实现/实现细节规范.md) | 游戏对象具体实现要求 | ⭐⭐⭐⭐⭐ |
|
||||
| [API接口文档.md](03-技术实现/API接口文档.md) | 后端接口说明和使用 | ⭐⭐⭐⭐⭐ |
|
||||
| [网络管理器设置.md](03-技术实现/网络管理器设置.md) | 网络通信配置 | ⭐⭐⭐⭐ |
|
||||
| [测试指南.md](03-技术实现/测试指南.md) | 测试方法和工具使用 | ⭐⭐⭐⭐ |
|
||||
| 文档 | 用途 | 重要程度 | 更新状态 |
|
||||
|------|------|----------|----------|
|
||||
| [实现细节规范.md](03-技术实现/实现细节规范.md) | 游戏对象具体实现要求和模板 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [API接口文档.md](03-技术实现/API接口文档.md) | 完整的后端接口说明和测试用例 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [网络管理器设置.md](03-技术实现/网络管理器设置.md) | 网络通信配置和使用指南 | ⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [测试指南.md](03-技术实现/测试指南.md) | 多种测试方法和工具使用 | ⭐⭐⭐⭐ | ✅ 最新 |
|
||||
|
||||
### 04-高级开发 🚀
|
||||
> **适用人群**: 有经验的开发者，架构师
|
||||
> **使用时机**: 复杂功能开发，性能优化时
|
||||
> **使用时机**: 复杂功能开发，性能优化时
|
||||
> **质量等级**: A级 ⭐⭐⭐⭐⭐
|
||||
|
||||
| 文档 | 用途 | 重要程度 |
|
||||
|------|------|----------|
|
||||
| [模块开发指南.md](04-高级开发/模块开发指南.md) | 创建可复用模块的方法 | ⭐⭐⭐ |
|
||||
| [场景设计规范.md](04-高级开发/场景设计规范.md) | 场景架构和设计标准 | ⭐⭐⭐ |
|
||||
| [性能优化指南.md](04-高级开发/性能优化指南.md) | 游戏性能优化策略 | ⭐⭐⭐ |
|
||||
| 文档 | 用途 | 重要程度 | 更新状态 |
|
||||
|------|------|----------|----------|
|
||||
| [场景设计规范.md](04-高级开发/场景设计规范.md) | 场景架构和设计标准，包含完整模板 | ⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [模块开发指南.md](04-高级开发/模块开发指南.md) | 创建可复用模块的完整流程 | ⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [性能优化指南.md](04-高级开发/性能优化指南.md) | 全面的游戏性能优化策略 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
|
||||
### 05-部署运维 🌐
|
||||
> **适用人群**: DevOps工程师，项目负责人
|
||||
> **使用时机**: 项目发布，部署配置时
|
||||
> **使用时机**: 项目发布，部署配置时
|
||||
> **质量等级**: A级 ⭐⭐⭐⭐⭐
|
||||
|
||||
| 文档 | 用途 | 重要程度 |
|
||||
|------|------|----------|
|
||||
| [Web部署指南.md](05-部署运维/Web部署指南.md) | Web版本导出和部署 | ⭐⭐⭐⭐ |
|
||||
| 文档 | 用途 | 重要程度 | 更新状态 |
|
||||
|------|------|----------|----------|
|
||||
| [Web部署指南.md](05-部署运维/Web部署指南.md) | 完整的Web版本导出和部署流程 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
|
||||
### 06-功能模块 🎮
|
||||
> **适用人群**: 开发特定功能的程序员
|
||||
> **使用时机**: 开发对应功能时
|
||||
> **使用时机**: 开发对应功能时
|
||||
> **质量等级**: A级 ⭐⭐⭐⭐⭐
|
||||
|
||||
| 目录/文档 | 用途 | 重要程度 |
|
||||
|-----------|------|----------|
|
||||
| [auth/](06-功能模块/auth/) | 用户认证系统相关文档 | ⭐⭐⭐⭐ |
|
||||
| └── [表单验证规范.md](06-功能模块/auth/表单验证规范.md) | 登录注册表单验证规则 | ⭐⭐⭐ |
|
||||
| └── [认证测试指南.md](06-功能模块/auth/认证测试指南.md) | 认证功能测试方法 | ⭐⭐⭐ |
|
||||
| 目录/文档 | 用途 | 重要程度 | 更新状态 |
|
||||
|-----------|------|----------|----------|
|
||||
| [auth/](06-功能模块/auth/) | 用户认证系统完整文档 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| └── [表单验证规范.md](06-功能模块/auth/表单验证规范.md) | 详细的表单验证规则和UI规范 | ⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| └── [认证测试指南.md](06-功能模块/auth/认证测试指南.md) | 完整的认证功能测试用例 | ⭐⭐⭐⭐ | ✅ 最新 |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 按角色推荐
|
||||
|
||||
### 👨💻 前端开发者
|
||||
**必读**: 01-项目入门 → 02-开发规范 → 03-技术实现
|
||||
**选读**: 04-高级开发 → 06-功能模块
|
||||
**学习路径**: 01-项目入门 → 02-开发规范 → 03-技术实现 → 06-功能模块
|
||||
**核心文档**:
|
||||
- [架构与通信规范](02-开发规范/架构与通信规范.md) - 掌握事件系统 ⭐⭐⭐⭐⭐
|
||||
- [实现细节规范](03-技术实现/实现细节规范.md) - 游戏对象实现 ⭐⭐⭐⭐⭐
|
||||
- [API接口文档](03-技术实现/API接口文档.md) - 后端接口调用 ⭐⭐⭐⭐⭐
|
||||
|
||||
### 🏗️ 架构师/技术负责人
|
||||
**必读**: 01-项目入门 → 02-开发规范 → 04-高级开发
|
||||
**选读**: 03-技术实现 → 05-部署运维
|
||||
**学习路径**: 01-项目入门 → 02-开发规范 → 04-高级开发 → 05-部署运维
|
||||
**核心文档**:
|
||||
- [开发哲学与最佳实践](02-开发规范/开发哲学与最佳实践.md) - 代码质量标准 ⭐⭐⭐⭐⭐
|
||||
- [场景设计规范](04-高级开发/场景设计规范.md) - 架构设计模式 ⭐⭐⭐⭐⭐
|
||||
- [性能优化指南](04-高级开发/性能优化指南.md) - 性能优化策略 ⭐⭐⭐⭐⭐
|
||||
|
||||
### 🧪 测试工程师
|
||||
**必读**: 01-项目入门 → 03-技术实现/测试指南.md
|
||||
**选读**: 06-功能模块
|
||||
**学习路径**: 01-项目入门 → 03-技术实现/测试指南 → 06-功能模块
|
||||
**核心文档**:
|
||||
- [测试指南](03-技术实现/测试指南.md) - 测试方法和工具 ⭐⭐⭐⭐⭐
|
||||
- [认证测试指南](06-功能模块/auth/认证测试指南.md) - 功能测试用例 ⭐⭐⭐⭐
|
||||
|
||||
### 🚀 DevOps工程师
|
||||
**必读**: 01-项目入门 → 05-部署运维
|
||||
**选读**: 03-技术实现
|
||||
**学习路径**: 01-项目入门 → 05-部署运维 → 03-技术实现
|
||||
**核心文档**:
|
||||
- [Web部署指南](05-部署运维/Web部署指南.md) - 完整部署流程 ⭐⭐⭐⭐⭐
|
||||
- [项目设置指南](01-项目入门/项目设置指南.md) - 环境配置 ⭐⭐⭐⭐
|
||||
|
||||
### 🎮 游戏设计师
|
||||
**学习路径**: 01-项目入门 → 04-高级开发/场景设计规范 → 06-功能模块
|
||||
**核心文档**:
|
||||
- [场景设计规范](04-高级开发/场景设计规范.md) - 场景设计标准 ⭐⭐⭐⭐⭐
|
||||
|
||||
---
|
||||
|
||||
@@ -134,44 +179,132 @@ docs/
|
||||
### 按问题类型查找
|
||||
|
||||
**🤔 "我不知道项目是怎么组织的"**
|
||||
→ [项目结构说明.md](01-项目入门/项目结构说明.md)
|
||||
→ [项目结构说明.md](01-项目入门/项目结构说明.md) - 完整的项目架构说明
|
||||
|
||||
**🤔 "我不知道怎么配置开发环境"**
|
||||
→ [项目设置指南.md](01-项目入门/项目设置指南.md) - 详细的环境配置步骤
|
||||
|
||||
**🤔 "我不知道怎么命名变量/函数"**
|
||||
→ [命名规范.md](02-开发规范/命名规范.md)
|
||||
→ [命名规范.md](02-开发规范/命名规范.md) - 统一的命名标准和示例
|
||||
|
||||
**🤔 "我不知道怎么让组件之间通信"**
|
||||
→ [架构与通信规范.md](02-开发规范/架构与通信规范.md)
|
||||
→ [架构与通信规范.md](02-开发规范/架构与通信规范.md) - 事件系统使用指南
|
||||
|
||||
**🤔 "我不知道怎么实现玩家/NPC"**
|
||||
→ [实现细节规范.md](03-技术实现/实现细节规范.md)
|
||||
→ [实现细节规范.md](03-技术实现/实现细节规范.md) - 游戏对象实现模板
|
||||
|
||||
**🤔 "我不知道怎么调用API"**
|
||||
→ [API接口文档.md](03-技术实现/API接口文档.md)
|
||||
→ [API接口文档.md](03-技术实现/API接口文档.md) - 完整的接口说明和示例
|
||||
|
||||
**🤔 "我不知道怎么测试功能"**
|
||||
→ [测试指南.md](03-技术实现/测试指南.md)
|
||||
→ [测试指南.md](03-技术实现/测试指南.md) - 多种测试方法和工具
|
||||
|
||||
**🤔 "我不知道怎么优化性能"**
|
||||
→ [性能优化指南.md](04-高级开发/性能优化指南.md) - 全面的优化策略
|
||||
|
||||
**🤔 "我不知道怎么发布项目"**
|
||||
→ [Web部署指南.md](05-部署运维/Web部署指南.md)
|
||||
→ [Web部署指南.md](05-部署运维/Web部署指南.md) - 完整的部署流程
|
||||
|
||||
**🤔 "我不知道怎么开发模块"**
|
||||
→ [模块开发指南.md](04-高级开发/模块开发指南.md) - 模块化开发方法
|
||||
|
||||
### 按开发阶段查找
|
||||
|
||||
| 阶段 | 主要文档 | 说明 |
|
||||
|------|----------|------|
|
||||
| **项目启动** | 01-项目入门 | 环境搭建，项目了解 |
|
||||
| **需求分析** | 02-开发规范 | 规范制定，架构设计 |
|
||||
| **功能开发** | 03-技术实现 | 具体实现，API集成 |
|
||||
| **质量保证** | 03-技术实现/测试指南 | 测试验证，质量控制 |
|
||||
| **性能优化** | 04-高级开发 | 性能调优，架构优化 |
|
||||
| **项目发布** | 05-部署运维 | 部署配置，运维监控 |
|
||||
|
||||
## 🛠️ 核心工具和配置
|
||||
|
||||
### 已集成的核心组件
|
||||
- **EventSystem** - 全局事件通信系统 ([EventNames.gd](_Core/EventNames.gd))
|
||||
- **ProjectPaths** - 统一路径管理 ([ProjectPaths.gd](_Core/ProjectPaths.gd))
|
||||
- **NetworkManager** - 网络请求管理器
|
||||
- **ResponseHandler** - 统一响应处理器
|
||||
- **StringUtils** - 字符串工具类
|
||||
|
||||
### 配置文件
|
||||
- **project.godot** - 项目配置，包含输入映射和AutoLoad设置
|
||||
- **Config/game_config.json** - 游戏配置文件
|
||||
- **web_assets/** - Web部署资源
|
||||
|
||||
## 📈 文档统计
|
||||
|
||||
| 类别 | 文档数量 | 完成度 | 质量等级 |
|
||||
|------|----------|--------|----------|
|
||||
| 项目入门 | 3 | 100% | A级 ⭐⭐⭐⭐⭐ |
|
||||
| 开发规范 | 5 | 100% | A级 ⭐⭐⭐⭐⭐ |
|
||||
| 技术实现 | 4 | 100% | A级 ⭐⭐⭐⭐⭐ |
|
||||
| 高级开发 | 3 | 100% | A级 ⭐⭐⭐⭐⭐ |
|
||||
| 部署运维 | 1 | 100% | A级 ⭐⭐⭐⭐⭐ |
|
||||
| 功能模块 | 2 | 100% | A级 ⭐⭐⭐⭐⭐ |
|
||||
| **总计** | **18** | **100%** | **A级** ⭐⭐⭐⭐⭐ |
|
||||
|
||||
---
|
||||
|
||||
## 📝 文档维护
|
||||
|
||||
### 更新机制
|
||||
- **自动同步**: 代码变更时自动检查相关文档
|
||||
- **版本控制**: 重要更新记录在 [CHANGELOG.md](CHANGELOG.md)
|
||||
- **质量保证**: 定期校验文档与代码的一致性
|
||||
- **持续改进**: 根据用户反馈持续优化文档质量
|
||||
|
||||
### 更新频率
|
||||
- **01-项目入门**: 项目架构变更时更新
|
||||
- **02-开发规范**: 团队规范调整时更新
|
||||
- **03-技术实现**: API变更或新功能时更新
|
||||
- **04-高级开发**: 最佳实践演进时更新
|
||||
- **05-部署运维**: 部署流程变更时更新
|
||||
- **06-功能模块**: 对应功能开发时更新
|
||||
| 文档类别 | 更新触发条件 | 更新频率 |
|
||||
|----------|--------------|----------|
|
||||
| **01-项目入门** | 项目架构变更 | 按需更新 |
|
||||
| **02-开发规范** | 团队规范调整 | 季度评审 |
|
||||
| **03-技术实现** | API变更/新功能 | 实时更新 |
|
||||
| **04-高级开发** | 最佳实践演进 | 月度评审 |
|
||||
| **05-部署运维** | 部署流程变更 | 按需更新 |
|
||||
| **06-功能模块** | 功能开发完成 | 实时更新 |
|
||||
|
||||
### 贡献指南
|
||||
如果你发现文档有问题或需要补充：
|
||||
1. 创建Issue描述问题
|
||||
2. 提交PR修改文档
|
||||
3. 遵循[Git提交规范](02-开发规范/Git提交规范.md)
|
||||
|
||||
1. **报告问题**: 创建Issue描述具体问题
|
||||
2. **提交改进**: 提交PR修改文档内容
|
||||
3. **遵循规范**: 按照[Git提交规范](02-开发规范/Git提交规范.md)提交
|
||||
4. **更新日志**: 重要变更需更新[CHANGELOG.md](CHANGELOG.md)
|
||||
|
||||
### 文档质量标准
|
||||
- **准确性**: 与实际代码保持100%一致
|
||||
- **完整性**: 覆盖功能的完整生命周期
|
||||
- **实用性**: 提供可直接使用的代码示例
|
||||
- **可读性**: 结构清晰，表达简洁明了
|
||||
|
||||
## 🎉 特别感谢
|
||||
|
||||
感谢所有为WhaleTown项目文档贡献的开发者！
|
||||
|
||||
### 文档贡献者
|
||||
- 项目架构设计和文档框架搭建
|
||||
- 开发规范制定和最佳实践总结
|
||||
- 技术实现指南和代码模板编写
|
||||
- 测试用例设计和质量保证
|
||||
|
||||
### 持续改进
|
||||
我们致力于打造最好用的游戏开发文档系统，欢迎提供反馈和建议！
|
||||
|
||||
---
|
||||
|
||||
**💡 提示**: 建议将本导航页面加入书签，方便随时查阅！
|
||||
## 📞 获取帮助
|
||||
|
||||
- **文档问题**: 查看 [CHANGELOG.md](CHANGELOG.md) 了解最新更新
|
||||
- **技术问题**: 参考对应的技术实现文档
|
||||
- **最佳实践**: 查阅开发规范和高级开发指南
|
||||
- **部署问题**: 参考部署运维文档
|
||||
|
||||
**💡 提示**: 建议将本导航页面加入书签，方便随时查阅！
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: v1.1.0
|
||||
**最后更新**: 2025-12-31
|
||||
**文档质量**: A级 ⭐⭐⭐⭐⭐
|
||||
@@ -39,6 +39,43 @@ window/stretch/aspect="expand"
|
||||
|
||||
theme/custom="uid://cp7t8tu7rmyad"
|
||||
|
||||
[input]
|
||||
|
||||
move_left={
|
||||
"deadzone": 0.5,
|
||||
"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":65,"key_label":0,"unicode":97,"location":0,"echo":false,"script":null)
|
||||
, Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194319,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
|
||||
]
|
||||
}
|
||||
move_right={
|
||||
"deadzone": 0.5,
|
||||
"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":68,"key_label":0,"unicode":100,"location":0,"echo":false,"script":null)
|
||||
, Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194321,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
|
||||
]
|
||||
}
|
||||
move_up={
|
||||
"deadzone": 0.5,
|
||||
"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":87,"key_label":0,"unicode":119,"location":0,"echo":false,"script":null)
|
||||
, Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194320,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
|
||||
]
|
||||
}
|
||||
move_down={
|
||||
"deadzone": 0.5,
|
||||
"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":83,"key_label":0,"unicode":115,"location":0,"echo":false,"script":null)
|
||||
, Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194322,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
|
||||
]
|
||||
}
|
||||
jump={
|
||||
"deadzone": 0.5,
|
||||
"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":32,"key_label":0,"unicode":32,"location":0,"echo":false,"script":null)
|
||||
]
|
||||
}
|
||||
interact={
|
||||
"deadzone": 0.5,
|
||||
"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":69,"key_label":0,"unicode":101,"location":0,"echo":false,"script":null)
|
||||
]
|
||||
}
|
||||
|
||||
[internationalization]
|
||||
|
||||
locale/test="zh_CN"
|
||||
|
||||
Reference in New Issue
Block a user