Compare commits
1 Commits
29c6740870
...
feature/lo
| Author | SHA1 | Date | |
|---|---|---|---|
| d623c705b6 |
13
.claude/settings.local.json
Normal file
13
.claude/settings.local.json
Normal file
@@ -0,0 +1,13 @@
|
|||||||
|
{
|
||||||
|
"permissions": {
|
||||||
|
"allow": [
|
||||||
|
"WebFetch(domain:whaletownend.xinghangee.icu)",
|
||||||
|
"mcp__ide__getDiagnostics",
|
||||||
|
"Bash(dir /s /b *.gd)",
|
||||||
|
"Bash(findstr:*)",
|
||||||
|
"Bash(del nul)",
|
||||||
|
"Bash(git checkout:*)",
|
||||||
|
"Bash(git add:*)"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
55
.gitignore
vendored
55
.gitignore
vendored
@@ -1,58 +1,3 @@
|
|||||||
# Godot 4+ specific ignores
|
# Godot 4+ specific ignores
|
||||||
.godot/
|
.godot/
|
||||||
/android/
|
/android/
|
||||||
|
|
||||||
# Python cache files
|
|
||||||
__pycache__/
|
|
||||||
*.pyc
|
|
||||||
*.pyo
|
|
||||||
*.pyd
|
|
||||||
.Python
|
|
||||||
*.so
|
|
||||||
|
|
||||||
# IDE and editor files
|
|
||||||
.vscode/
|
|
||||||
.idea/
|
|
||||||
*.swp
|
|
||||||
*.swo
|
|
||||||
*~
|
|
||||||
|
|
||||||
# OS generated files
|
|
||||||
.DS_Store
|
|
||||||
.DS_Store?
|
|
||||||
._*
|
|
||||||
.Spotlight-V100
|
|
||||||
.Trashes
|
|
||||||
ehthumbs.db
|
|
||||||
Thumbs.db
|
|
||||||
|
|
||||||
# Godot executable files (should not be in version control)
|
|
||||||
Godot/
|
|
||||||
*.exe
|
|
||||||
*.app
|
|
||||||
*.dmg
|
|
||||||
|
|
||||||
# Logs and temporary files
|
|
||||||
*.log
|
|
||||||
*.tmp
|
|
||||||
*.temp
|
|
||||||
|
|
||||||
# Build outputs
|
|
||||||
build/
|
|
||||||
dist/
|
|
||||||
*.zip
|
|
||||||
*.tar.gz
|
|
||||||
|
|
||||||
# Environment files
|
|
||||||
.env
|
|
||||||
.env.local
|
|
||||||
.env.*.local
|
|
||||||
|
|
||||||
# Test coverage reports
|
|
||||||
coverage/
|
|
||||||
*.coverage
|
|
||||||
.nyc_output/
|
|
||||||
|
|
||||||
# Dependency directories
|
|
||||||
node_modules/
|
|
||||||
vendor/
|
|
||||||
|
|||||||
15
.vscode/launch.json
vendored
Normal file
15
.vscode/launch.json
vendored
Normal file
@@ -0,0 +1,15 @@
|
|||||||
|
{
|
||||||
|
"version": "0.2.0",
|
||||||
|
"configurations": [
|
||||||
|
{
|
||||||
|
"name": "GDScript Godot",
|
||||||
|
"type": "godot",
|
||||||
|
"request": "launch",
|
||||||
|
"project": "${workspaceFolder}",
|
||||||
|
"port": 6007,
|
||||||
|
"address": "127.0.0.1",
|
||||||
|
"launch_game_instance": true,
|
||||||
|
"launch_scene": false
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
3
.vscode/settings.json
vendored
Normal file
3
.vscode/settings.json
vendored
Normal file
@@ -0,0 +1,3 @@
|
|||||||
|
{
|
||||||
|
"godotTools.editorPath.godot4": "d:\\software\\godot\\Godot_v4.5.1-stable_win64.exe"
|
||||||
|
}
|
||||||
@@ -1,29 +0,0 @@
|
|||||||
{
|
|
||||||
"game": {
|
|
||||||
"name": "whaleTown",
|
|
||||||
"version": "1.0.0",
|
|
||||||
"debug_mode": true
|
|
||||||
},
|
|
||||||
"network": {
|
|
||||||
"api_base_url": "https://whaletownend.xinghangee.icu",
|
|
||||||
"timeout": 30,
|
|
||||||
"retry_count": 3
|
|
||||||
},
|
|
||||||
"ui": {
|
|
||||||
"default_font_size": 14,
|
|
||||||
"toast_duration": 2.0,
|
|
||||||
"transition_duration": 0.3
|
|
||||||
},
|
|
||||||
"gameplay": {
|
|
||||||
"auto_save_interval": 300,
|
|
||||||
"max_inventory_slots": 50,
|
|
||||||
"default_player_stats": {
|
|
||||||
"level": 1,
|
|
||||||
"coins": 100,
|
|
||||||
"exp": 0,
|
|
||||||
"max_exp": 100,
|
|
||||||
"energy": 100,
|
|
||||||
"max_energy": 100
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
@@ -1,36 +0,0 @@
|
|||||||
{
|
|
||||||
"ui": {
|
|
||||||
"login": "登录",
|
|
||||||
"register": "注册",
|
|
||||||
"username": "用户名",
|
|
||||||
"password": "密码",
|
|
||||||
"email": "邮箱",
|
|
||||||
"confirm_password": "确认密码",
|
|
||||||
"verification_code": "验证码",
|
|
||||||
"send_code": "发送验证码",
|
|
||||||
"forgot_password": "忘记密码",
|
|
||||||
"enter_town": "进入小镇",
|
|
||||||
"logout": "退出登录"
|
|
||||||
},
|
|
||||||
"messages": {
|
|
||||||
"login_success": "登录成功！正在进入鲸鱼镇...",
|
|
||||||
"register_success": "注册成功！欢迎加入鲸鱼镇",
|
|
||||||
"network_error": "网络连接失败，请检查网络连接",
|
|
||||||
"invalid_username": "用户名只能包含字母、数字和下划线",
|
|
||||||
"invalid_email": "请输入有效的邮箱地址",
|
|
||||||
"password_too_short": "密码长度至少8位",
|
|
||||||
"password_mismatch": "两次输入的密码不一致",
|
|
||||||
"verification_code_sent": "验证码已发送到您的邮箱，请查收"
|
|
||||||
},
|
|
||||||
"game": {
|
|
||||||
"level": "等级",
|
|
||||||
"coins": "金币",
|
|
||||||
"experience": "经验",
|
|
||||||
"energy": "体力",
|
|
||||||
"explore": "探索小镇",
|
|
||||||
"inventory": "背包",
|
|
||||||
"shop": "商店",
|
|
||||||
"friends": "好友",
|
|
||||||
"settings": "设置"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
460
README.md
460
README.md
@@ -1,395 +1,101 @@
|
|||||||
# 🐋 WhaleTown - 现代化像素游戏
|
# whaleTown
|
||||||
|
|
||||||
> 一个基于 Godot 4.5 引擎开发的企业级 2D 像素风游戏，采用模块化架构设计，集成完整的用户认证系统和游戏核心功能。
|
一个使用 Godot 4.5 引擎开发的游戏项目。
|
||||||
|
|
||||||
[](https://godotengine.org/)
|
## 项目信息
|
||||||
[](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/index.html)
|
|
||||||
[](./docs/)
|
|
||||||
[](https://godotengine.org/download)
|
|
||||||
|
|
||||||
## 🎯 项目简介
|
- **引擎版本**: Godot 4.5
|
||||||
|
- **渲染器**: Forward Plus
|
||||||
|
- **项目类型**: 2D 游戏
|
||||||
|
|
||||||
WhaleTown 是一个功能完整的现代化像素游戏，具有以下特色：
|
## 项目结构
|
||||||
|
|
||||||
- 🏗️ **企业级架构** - 模块化设计，高度解耦，易于扩展
|
```
|
||||||
- 🔐 **完整认证系统** - 登录、注册、邮箱验证、密码管理
|
whaleTown/
|
||||||
- 🎮 **丰富游戏功能** - 角色系统、场景管理、事件通信
|
├── addons/ # Godot 插件目录
|
||||||
- 🌐 **网络通信** - RESTful API集成，支持实时数据交互
|
├── assets/ # 游戏资源文件（图片、音频等）
|
||||||
- 📚 **企业级文档** - 18个文档，覆盖开发全流程
|
├── data/ # 游戏数据文件（配置、关卡数据等）
|
||||||
- 🧪 **完整测试体系** - API测试、UI测试、性能测试
|
├── docs/ # 项目文档
|
||||||
- 🚀 **一键部署** - 支持Web、桌面多平台发布
|
├── scenes/ # 游戏场景文件
|
||||||
|
│ └── main_scene.tscn # 主场景
|
||||||
|
├── scripts/ # GDScript 脚本文件
|
||||||
|
├── tests/ # 测试文件
|
||||||
|
├── icon.svg # 项目图标
|
||||||
|
└── project.godot # Godot 项目配置文件
|
||||||
|
```
|
||||||
|
|
||||||
---
|
## 开始使用
|
||||||
|
|
||||||
## 🚀 5分钟快速体验
|
### 前置要求
|
||||||
|
|
||||||
### 📋 准备工作
|
- [Godot Engine 4.5](https://godotengine.org/download) 或更高版本
|
||||||
|
|
||||||
**你需要安装：**
|
### 运行项目
|
||||||
- [Godot Engine 4.5+](https://godotengine.org/download) - 游戏引擎
|
|
||||||
- [Git](https://git-scm.com/) - 版本控制工具
|
|
||||||
|
|
||||||
### 🛠️ 启动项目
|
1. 克隆或下载此项目
|
||||||
|
2. 使用 Godot 编辑器打开项目
|
||||||
|
3. 在编辑器中点击"运行"按钮或按 F5 键启动游戏
|
||||||
|
|
||||||
|
### 开发指南
|
||||||
|
|
||||||
|
- **场景文件**: 所有场景文件存放在 `scenes/` 目录
|
||||||
|
- **脚本文件**: 所有 GDScript 脚本存放在 `scripts/` 目录
|
||||||
|
- **资源文件**: 图片、音频等资源存放在 `assets/` 目录
|
||||||
|
- **游戏数据**: 配置文件、关卡数据等存放在 `data/` 目录
|
||||||
|
|
||||||
|
### 命名规范
|
||||||
|
|
||||||
|
本项目遵循统一的命名规范以保持代码一致性：
|
||||||
|
|
||||||
|
**核心规则**：
|
||||||
|
|
||||||
|
- **场景文件**：`下划线_scene.tscn` 或 `下划线_prefab.tscn`
|
||||||
|
- 示例：`main_scene.tscn`、`player_prefab.tscn`
|
||||||
|
- **脚本文件**：`PascalCase.gd`（大驼峰）
|
||||||
|
- 示例：`PlayerController.gd`、`UI_MainMenu.gd`
|
||||||
|
- **节点名称**：`camelCase`（小驼峰）
|
||||||
|
- 示例：`playerHpBar`、`startButton`
|
||||||
|
- **变量/函数**：`camelCase`（小驼峰）
|
||||||
|
- 示例：`var moveSpeed`、`func getPlayerPos()`
|
||||||
|
- **常量**：`UPPER_CASE`（全大写 + 下划线）
|
||||||
|
- 示例：`const MAX_HEALTH = 100`
|
||||||
|
- **资源文件**：`lower_case`（小写 + 下划线）
|
||||||
|
- 示例：`bg_main_menu.png`、`sound_jump.wav`
|
||||||
|
|
||||||
|
📖 查看完整的 [命名规范文档](docs/naming_convention.md)
|
||||||
|
|
||||||
|
### Git 提交规范
|
||||||
|
|
||||||
|
本项目遵循统一的 Git 提交信息格式：`<类型>：<描述>`
|
||||||
|
|
||||||
|
**常用提交类型**：
|
||||||
|
|
||||||
|
- `init`：项目初始化
|
||||||
|
- `feat`：新增功能
|
||||||
|
- `fix`：修复 Bug
|
||||||
|
- `docs`：文档更新
|
||||||
|
- `scene`：场景文件相关
|
||||||
|
- `asset`：资源文件相关
|
||||||
|
- `ui`：UI 界面相关
|
||||||
|
- `gameplay`：游戏玩法相关
|
||||||
|
- `refactor`：代码重构
|
||||||
|
- `perf`：性能优化
|
||||||
|
|
||||||
|
**提交示例**：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 1️⃣ 获取项目
|
git commit -m "init：项目初始化，搭建Godot文件结构"
|
||||||
git clone <repository-url>
|
git commit -m "feat：实现玩家角色的移动和跳跃"
|
||||||
cd whale-town
|
git commit -m "fix：修复敌人穿墙的碰撞问题"
|
||||||
|
git commit -m "scene：创建战斗场景并配置相机"
|
||||||
# 2️⃣ 打开项目
|
|
||||||
# 双击 project.godot 文件，或在Godot编辑器中选择"导入项目"
|
|
||||||
|
|
||||||
# 3️⃣ 运行游戏
|
|
||||||
# 在Godot编辑器中按 F5 或点击"运行项目"按钮
|
|
||||||
```
|
```
|
||||||
|
|
||||||
🎉 **成功！** 你应该看到游戏的认证界面
|
📖 查看完整的 [Git 提交规范文档](docs/git_commit_guide.md)
|
||||||
|
|
||||||
### 🎮 体验功能
|
## 贡献
|
||||||
|
|
||||||
1. **注册新用户** - 体验完整的邮箱验证流程
|
欢迎提交 Issue 和 Pull Request！
|
||||||
2. **登录系统** - 尝试用户名/邮箱登录
|
|
||||||
3. **游戏界面** - 探索主游戏场景
|
|
||||||
|
|
||||||
### 🧪 测试API（可选）
|
## 许可证
|
||||||
|
|
||||||
```bash
|
[在此添加许可证信息]
|
||||||
# 安装Python依赖
|
|
||||||
pip install requests
|
|
||||||
|
|
||||||
# 快速API测试
|
|
||||||
python tests/api/quick_test.py
|
|
||||||
|
|
||||||
# 完整功能测试
|
|
||||||
python tests/api/api_client_test.py
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📚 新手开发指南
|
|
||||||
|
|
||||||
### 🎯 第一步：了解项目
|
|
||||||
|
|
||||||
**⚠️ 重要：开始开发前必读**
|
|
||||||
|
|
||||||
1. **[📖 项目入门总览](docs/01-项目入门/README.md)** - 5分钟了解项目
|
|
||||||
2. **[🏗️ 项目结构说明](docs/01-项目入门/项目结构说明.md)** - 理解架构设计
|
|
||||||
3. **[⚙️ 项目设置指南](docs/01-项目入门/项目设置指南.md)** - 配置开发环境
|
|
||||||
4. **[🤖 AI开发指南](docs/AI_docs/README.md)** - AI编程助手专用文档
|
|
||||||
|
|
||||||
### 🎯 第二步：学习规范
|
|
||||||
|
|
||||||
**代码质量保证**
|
|
||||||
|
|
||||||
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)** - 完整部署流程
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🏗️ 项目架构一览
|
|
||||||
|
|
||||||
### 📁 目录结构
|
|
||||||
|
|
||||||
```
|
|
||||||
WhaleTown/ # 🐋 项目根目录
|
|
||||||
├── 📚 docs/ # 📖 完整文档系统（18个文档）
|
|
||||||
│ ├── 01-项目入门/ # 👋 新人必读
|
|
||||||
│ ├── 02-开发规范/ # 📋 编码标准
|
|
||||||
│ ├── 03-技术实现/ # 🔧 开发指导
|
|
||||||
│ ├── 04-高级开发/ # 🚀 进阶技巧
|
|
||||||
│ ├── 05-部署运维/ # 🌐 发布部署
|
|
||||||
│ ├── 06-功能模块/ # 🎮 功能文档
|
|
||||||
│ └── AI_docs/ # 🤖 AI专用文档（执行规范、代码模板）
|
|
||||||
├── 🔧 _Core/ # ⚙️ 核心底层实现
|
|
||||||
│ ├── managers/ # 🎯 全局管理器（游戏状态、场景、网络等）
|
|
||||||
│ ├── systems/ # 🔄 系统组件（事件系统、输入系统等）
|
|
||||||
│ ├── components/ # 🧩 基础组件实现
|
|
||||||
│ ├── utils/ # <20> 核件心工具类（字符串处理、数学计算等）
|
|
||||||
│ ├── EventNames.gd # 📝 事件名称定义
|
|
||||||
│ └── ProjectPaths.gd # <20> 路径组统一管理
|
|
||||||
├── 🎬 scenes/ # 🎭 场景与视觉呈现
|
|
||||||
│ ├── maps/ # <20>️ 地图一场景（游戏关卡、世界地图）
|
|
||||||
│ ├── characters/ # 👤 人物场景（角色、NPC、敌人）
|
|
||||||
│ ├── ui/ # 🖼️ UI界面场景（菜单、HUD、对话框）
|
|
||||||
│ ├── effects/ # ✨ 特效场景（粒子效果、动画）
|
|
||||||
│ └── prefabs/ # 🧩 预制体组件
|
|
||||||
├── 🎨 assets/ # 🖼️ 静态资源存储
|
|
||||||
│ ├── sprites/ # 🎨 精灵图片（角色、物品、环境）
|
|
||||||
│ ├── audio/ # 🎵 音频资源（音乐、音效）
|
|
||||||
│ ├── fonts/ # 🔤 字体文件
|
|
||||||
│ ├── materials/ # 🎭 材质资源
|
|
||||||
│ ├── shaders/ # 🌈 着色器文件
|
|
||||||
│ ├── ui/ # 🖼️ UI素材（按钮、图标、背景）
|
|
||||||
│ └── icon/ # 📱 应用图标
|
|
||||||
├── ⚙️ Config/ # 📋 配置文件管理
|
|
||||||
│ ├── game_config.json # 🎮 游戏配置（难度、设置等）
|
|
||||||
│ ├── zh_CN.json # 🌐 本地化配置
|
|
||||||
│ └── environment/ # 🔧 环境配置（开发、测试、生产）
|
|
||||||
├── 🧪 tests/ # 🔬 测试文件系统
|
|
||||||
│ ├── unit/ # 🔍 单元测试（组件功能测试）
|
|
||||||
│ ├── integration/ # 🔗 集成测试（系统交互测试）
|
|
||||||
│ ├── performance/ # ⚡ 性能测试（帧率、内存优化）
|
|
||||||
│ └── api/ # 🌐 API接口测试
|
|
||||||
└── 🌐 web_assets/ # 🌍 Web导出资源
|
|
||||||
├── html/ # 📄 HTML模板文件
|
|
||||||
├── css/ # 🎨 样式文件
|
|
||||||
└── js/ # 📜 JavaScript脚本
|
|
||||||
```
|
|
||||||
|
|
||||||
### 🔧 核心架构说明
|
|
||||||
|
|
||||||
| 目录 | 作用 | 详细说明 |
|
|
||||||
|------|------|----------|
|
|
||||||
| **_Core** | 🔧 功能实现与组件实现 | 项目最基本的底层实现，包含所有核心系统和基础组件 |
|
|
||||||
| **scenes** | 🎭 场景与视觉呈现 | 包含地图场景、人物场景等一系列视觉呈现部分，主要是UI的实现 |
|
|
||||||
| **assets** | 🎨 静态资源存储 | 所有静态资源的存储，包括图片、音乐、视频、贴图等素材 |
|
|
||||||
| **Config** | ⚙️ 配置文件管理 | 主要用来配置各类环境，包括游戏设置、本地化等配置 |
|
|
||||||
| **tests** | 🧪 测试文件系统 | 放置所有对应组件的测试代码，方便快速进行功能性与性能测试 |
|
|
||||||
| **web_assets** | 🌐 Web导出资源 | 专门用于Web平台导出的相关资源和配置文件 |
|
|
||||||
| **docs/AI_docs** | 🤖 AI专用文档 | 专门为AI编程助手准备的执行规范和代码模板，提升vibe coding效率 |
|
|
||||||
|
|
||||||
### 🎮 核心组件
|
|
||||||
|
|
||||||
| 组件 | 位置 | 作用 | 文档链接 |
|
|
||||||
|------|------|------|----------|
|
|
||||||
| **EventSystem** | _Core/systems/ | 全局事件通信系统 | [架构规范](docs/02-开发规范/架构与通信规范.md) |
|
|
||||||
| **GameManager** | _Core/managers/ | 游戏状态管理器 | [实现细节](docs/03-技术实现/实现细节规范.md) |
|
|
||||||
| **SceneManager** | _Core/managers/ | 场景切换管理器 | [场景设计](docs/04-高级开发/场景设计规范.md) |
|
|
||||||
| **NetworkManager** | _Core/managers/ | 网络请求管理器 | [网络管理器](docs/03-技术实现/网络管理器设置.md) |
|
|
||||||
| **ProjectPaths** | _Core/ | 路径统一管理工具 | [项目结构](docs/01-项目入门/项目结构说明.md) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎮 核心功能
|
|
||||||
|
|
||||||
### 🔐 用户认证系统
|
|
||||||
|
|
||||||
**完整的用户管理功能**
|
|
||||||
- ✅ 用户注册（用户名+邮箱验证）
|
|
||||||
- ✅ 多方式登录（用户名/邮箱/验证码）
|
|
||||||
- ✅ 密码管理（修改/重置）
|
|
||||||
- ✅ 表单验证（实时验证+友好提示）
|
|
||||||
- ✅ 错误处理（网络异常+业务错误）
|
|
||||||
|
|
||||||
**技术特色**
|
|
||||||
- 📱 响应式UI设计
|
|
||||||
- 🔄 实时表单验证
|
|
||||||
- ⏰ 验证码冷却机制
|
|
||||||
- 🎨 流畅动画效果
|
|
||||||
|
|
||||||
### 🎮 游戏核心系统
|
|
||||||
|
|
||||||
**模块化游戏架构**
|
|
||||||
- 🎭 场景管理系统
|
|
||||||
- 🔄 事件通信系统
|
|
||||||
- 🎯 状态管理系统
|
|
||||||
- 🌐 网络通信系统
|
|
||||||
|
|
||||||
**开发友好特性**
|
|
||||||
- 🧩 高度模块化
|
|
||||||
- 📝 完整文档覆盖
|
|
||||||
- 🧪 测试用例齐全
|
|
||||||
- 🔧 开发工具完善
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🧪 测试系统
|
|
||||||
|
|
||||||
### 🔬 测试类型
|
|
||||||
|
|
||||||
| 测试类型 | 工具 | 覆盖范围 | 文档 |
|
|
||||||
|----------|------|----------|------|
|
|
||||||
| **API测试** | Python脚本 | 17个接口全覆盖 | [测试指南](docs/03-技术实现/测试指南.md) |
|
|
||||||
| **UI测试** | Godot场景 | 认证流程完整测试 | [认证测试](docs/06-功能模块/auth/认证测试指南.md) |
|
|
||||||
| **单元测试** | GUT框架 | 核心组件测试 | [测试指南](docs/03-技术实现/测试指南.md) |
|
|
||||||
|
|
||||||
### 🚀 快速测试
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 🔌 API接口测试（30秒）
|
|
||||||
python tests/api/quick_test.py
|
|
||||||
|
|
||||||
# 🔍 完整功能测试（2-3分钟）
|
|
||||||
python tests/api/api_client_test.py
|
|
||||||
|
|
||||||
# 🎮 UI交互测试（在Godot中运行）
|
|
||||||
# 打开 tests/auth/auth_ui_test.tscn 场景
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🚀 部署发布
|
|
||||||
|
|
||||||
### 🖥️ 桌面版本
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 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
|
|
||||||
# 使用自动化脚本
|
|
||||||
scripts/build_web.bat # Windows
|
|
||||||
scripts/build_web.sh # Linux/macOS
|
|
||||||
|
|
||||||
# 本地测试
|
|
||||||
scripts/serve_web.bat # 启动本地服务器
|
|
||||||
```
|
|
||||||
|
|
||||||
**详细部署流程**: [Web部署指南](docs/05-部署运维/Web部署指南.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📊 项目统计
|
|
||||||
|
|
||||||
### 📚 文档系统
|
|
||||||
|
|
||||||
| 类别 | 文档数 | 完成度 |
|
|
||||||
|------|--------|--------|
|
|
||||||
| 项目入门 | 3 | 100% |
|
|
||||||
| 开发规范 | 5 | 100% |
|
|
||||||
| 技术实现 | 4 | 100% |
|
|
||||||
| 高级开发 | 3 | 100% |
|
|
||||||
| 部署运维 | 1 | 100% |
|
|
||||||
| 功能模块 | 2 | 100% |
|
|
||||||
| **总计** | **18** | **100%** |
|
|
||||||
|
|
||||||
### 🧪 测试覆盖
|
|
||||||
|
|
||||||
- **API接口**: 17个接口 ✅
|
|
||||||
- **认证流程**: 完整测试 ✅
|
|
||||||
- **错误处理**: 边界测试 ✅
|
|
||||||
- **性能监控**: 帧率/内存 ✅
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🤝 参与贡献
|
|
||||||
|
|
||||||
### 🌟 贡献方式
|
|
||||||
|
|
||||||
1. **🐛 Bug修复** - 发现并修复问题
|
|
||||||
2. **✨ 新功能** - 添加有价值的功能
|
|
||||||
3. **📚 文档改进** - 完善项目文档
|
|
||||||
4. **🧪 测试用例** - 提高代码覆盖率
|
|
||||||
5. **🎨 UI/UX改进** - 提升用户体验
|
|
||||||
|
|
||||||
### 📋 贡献流程
|
|
||||||
|
|
||||||
```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) 开源协议。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
<div align="center">
|
|
||||||
|
|
||||||
**🐋 WhaleTown - 企业级像素游戏开发框架**
|
|
||||||
|
|
||||||
*让游戏开发更简单，让代码质量更优秀*
|
|
||||||
|
|
||||||
[⭐ 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)
|
|
||||||
|
|
||||||
**文档版本**: v1.2.0 | **最后更新**: 2025-12-31
|
|
||||||
|
|
||||||
</div>
|
|
||||||
|
|||||||
@@ -1,58 +0,0 @@
|
|||||||
# ============================================================================
|
|
||||||
# 事件名称定义 - 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 +0,0 @@
|
|||||||
uid://qn0imbklx1m0
|
|
||||||
@@ -1,107 +0,0 @@
|
|||||||
# ============================================================================
|
|
||||||
# 项目路径配置 - 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://scenes/ui/"
|
|
||||||
const UI_WINDOWS = UI_ROOT
|
|
||||||
|
|
||||||
# ============================================================================
|
|
||||||
# 资源路径
|
|
||||||
# ============================================================================
|
|
||||||
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://_Core/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 +0,0 @@
|
|||||||
uid://dybcuscku7tyl
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
# 基础组件实现目录
|
|
||||||
# 存放项目的基础组件类
|
|
||||||
@@ -1,50 +0,0 @@
|
|||||||
extends Node
|
|
||||||
|
|
||||||
# 游戏管理器 - 全局游戏状态管理
|
|
||||||
# 单例模式，管理游戏的整体状态和生命周期
|
|
||||||
|
|
||||||
signal game_state_changed(new_state: GameState)
|
|
||||||
|
|
||||||
enum GameState {
|
|
||||||
LOADING, # 加载中
|
|
||||||
AUTH, # 认证状态
|
|
||||||
MAIN_MENU, # 主菜单
|
|
||||||
IN_GAME, # 游戏中
|
|
||||||
PAUSED, # 暂停
|
|
||||||
SETTINGS # 设置
|
|
||||||
}
|
|
||||||
|
|
||||||
var current_state: GameState = GameState.LOADING
|
|
||||||
var previous_state: GameState = GameState.LOADING
|
|
||||||
var current_user: String = ""
|
|
||||||
var game_version: String = "1.0.0"
|
|
||||||
|
|
||||||
func _ready():
|
|
||||||
print("GameManager 初始化完成")
|
|
||||||
change_state(GameState.AUTH)
|
|
||||||
|
|
||||||
func change_state(new_state: GameState):
|
|
||||||
if current_state == new_state:
|
|
||||||
return
|
|
||||||
|
|
||||||
previous_state = current_state
|
|
||||||
current_state = new_state
|
|
||||||
|
|
||||||
print("游戏状态变更: ", GameState.keys()[previous_state], " -> ", GameState.keys()[current_state])
|
|
||||||
game_state_changed.emit(new_state)
|
|
||||||
|
|
||||||
func get_current_state() -> GameState:
|
|
||||||
return current_state
|
|
||||||
|
|
||||||
func get_previous_state() -> GameState:
|
|
||||||
return previous_state
|
|
||||||
|
|
||||||
func set_current_user(username: String):
|
|
||||||
current_user = username
|
|
||||||
print("当前用户设置为: ", username)
|
|
||||||
|
|
||||||
func get_current_user() -> String:
|
|
||||||
return current_user
|
|
||||||
|
|
||||||
func is_user_logged_in() -> bool:
|
|
||||||
return not current_user.is_empty()
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
uid://cd8fn73ysjxh8
|
|
||||||
@@ -1,443 +0,0 @@
|
|||||||
extends Node
|
|
||||||
|
|
||||||
# 网络请求管理器 - 统一处理所有HTTP请求
|
|
||||||
|
|
||||||
# 信号定义
|
|
||||||
signal request_completed(request_id: String, success: bool, data: Dictionary)
|
|
||||||
signal request_failed(request_id: String, error_type: String, message: String)
|
|
||||||
|
|
||||||
# API配置
|
|
||||||
const API_BASE_URL = "https://whaletownend.xinghangee.icu"
|
|
||||||
const DEFAULT_TIMEOUT = 30.0
|
|
||||||
|
|
||||||
# 请求类型枚举
|
|
||||||
enum RequestType {
|
|
||||||
GET,
|
|
||||||
POST,
|
|
||||||
PUT,
|
|
||||||
DELETE,
|
|
||||||
PATCH
|
|
||||||
}
|
|
||||||
|
|
||||||
# 错误类型枚举
|
|
||||||
enum ErrorType {
|
|
||||||
NETWORK_ERROR, # 网络连接错误
|
|
||||||
TIMEOUT_ERROR, # 请求超时
|
|
||||||
PARSE_ERROR, # JSON解析错误
|
|
||||||
HTTP_ERROR, # HTTP状态码错误
|
|
||||||
BUSINESS_ERROR # 业务逻辑错误
|
|
||||||
}
|
|
||||||
|
|
||||||
# 请求状态
|
|
||||||
class RequestInfo:
|
|
||||||
var id: String
|
|
||||||
var url: String
|
|
||||||
var method: RequestType
|
|
||||||
var headers: PackedStringArray
|
|
||||||
var body: String
|
|
||||||
var timeout: float
|
|
||||||
var start_time: float
|
|
||||||
var http_request: HTTPRequest
|
|
||||||
var callback: Callable
|
|
||||||
|
|
||||||
func _init(request_id: String, request_url: String, request_method: RequestType,
|
|
||||||
request_headers: PackedStringArray = [], request_body: String = "",
|
|
||||||
request_timeout: float = DEFAULT_TIMEOUT):
|
|
||||||
id = request_id
|
|
||||||
url = request_url
|
|
||||||
method = request_method
|
|
||||||
headers = request_headers
|
|
||||||
body = request_body
|
|
||||||
timeout = request_timeout
|
|
||||||
start_time = Time.get_time_dict_from_system().hour * 3600 + Time.get_time_dict_from_system().minute * 60 + Time.get_time_dict_from_system().second
|
|
||||||
|
|
||||||
# 活动请求管理
|
|
||||||
var active_requests: Dictionary = {}
|
|
||||||
var request_counter: int = 0
|
|
||||||
|
|
||||||
func _ready():
|
|
||||||
print("NetworkManager 已初始化")
|
|
||||||
|
|
||||||
# ============ 公共API接口 ============
|
|
||||||
|
|
||||||
# 发送GET请求
|
|
||||||
func get_request(endpoint: String, callback: Callable = Callable(), timeout: float = DEFAULT_TIMEOUT) -> String:
|
|
||||||
return send_request(endpoint, RequestType.GET, [], "", callback, timeout)
|
|
||||||
|
|
||||||
# 发送POST请求
|
|
||||||
func post_request(endpoint: String, data: Dictionary, callback: Callable = Callable(), timeout: float = DEFAULT_TIMEOUT) -> String:
|
|
||||||
var body = JSON.stringify(data)
|
|
||||||
var headers = ["Content-Type: application/json"]
|
|
||||||
return send_request(endpoint, RequestType.POST, headers, body, callback, timeout)
|
|
||||||
|
|
||||||
# 发送PUT请求
|
|
||||||
func put_request(endpoint: String, data: Dictionary, callback: Callable = Callable(), timeout: float = DEFAULT_TIMEOUT) -> String:
|
|
||||||
var body = JSON.stringify(data)
|
|
||||||
var headers = ["Content-Type: application/json"]
|
|
||||||
return send_request(endpoint, RequestType.PUT, headers, body, callback, timeout)
|
|
||||||
|
|
||||||
# 发送DELETE请求
|
|
||||||
func delete_request(endpoint: String, callback: Callable = Callable(), timeout: float = DEFAULT_TIMEOUT) -> String:
|
|
||||||
return send_request(endpoint, RequestType.DELETE, [], "", callback, timeout)
|
|
||||||
|
|
||||||
# ============ 认证相关API ============
|
|
||||||
|
|
||||||
# 用户登录
|
|
||||||
func login(identifier: String, password: String, callback: Callable = Callable()) -> String:
|
|
||||||
var data = {
|
|
||||||
"identifier": identifier,
|
|
||||||
"password": password
|
|
||||||
}
|
|
||||||
return post_request("/auth/login", data, callback)
|
|
||||||
|
|
||||||
# 验证码登录
|
|
||||||
func verification_code_login(identifier: String, verification_code: String, callback: Callable = Callable()) -> String:
|
|
||||||
var data = {
|
|
||||||
"identifier": identifier,
|
|
||||||
"verification_code": verification_code
|
|
||||||
}
|
|
||||||
return post_request("/auth/verification-code-login", data, callback)
|
|
||||||
|
|
||||||
# 发送登录验证码
|
|
||||||
func send_login_verification_code(identifier: String, callback: Callable = Callable()) -> String:
|
|
||||||
var data = {"identifier": identifier}
|
|
||||||
return post_request("/auth/send-login-verification-code", data, callback)
|
|
||||||
|
|
||||||
# 用户注册
|
|
||||||
func register(username: String, password: String, nickname: String, email: String = "",
|
|
||||||
email_verification_code: String = "", callback: Callable = Callable()) -> String:
|
|
||||||
var data = {
|
|
||||||
"username": username,
|
|
||||||
"password": password,
|
|
||||||
"nickname": nickname
|
|
||||||
}
|
|
||||||
|
|
||||||
if email != "":
|
|
||||||
data["email"] = email
|
|
||||||
if email_verification_code != "":
|
|
||||||
data["email_verification_code"] = email_verification_code
|
|
||||||
|
|
||||||
return post_request("/auth/register", data, callback)
|
|
||||||
|
|
||||||
# 发送邮箱验证码
|
|
||||||
func send_email_verification(email: String, callback: Callable = Callable()) -> String:
|
|
||||||
var data = {"email": email}
|
|
||||||
return post_request("/auth/send-email-verification", data, callback)
|
|
||||||
|
|
||||||
# 验证邮箱
|
|
||||||
func verify_email(email: String, verification_code: String, callback: Callable = Callable()) -> String:
|
|
||||||
var data = {
|
|
||||||
"email": email,
|
|
||||||
"verification_code": verification_code
|
|
||||||
}
|
|
||||||
return post_request("/auth/verify-email", data, callback)
|
|
||||||
|
|
||||||
# 获取应用状态
|
|
||||||
func get_app_status(callback: Callable = Callable()) -> String:
|
|
||||||
return get_request("/", callback)
|
|
||||||
|
|
||||||
# 重新发送邮箱验证码
|
|
||||||
func resend_email_verification(email: String, callback: Callable = Callable()) -> String:
|
|
||||||
var data = {"email": email}
|
|
||||||
return post_request("/auth/resend-email-verification", data, callback)
|
|
||||||
|
|
||||||
# 忘记密码 - 发送重置验证码
|
|
||||||
func forgot_password(identifier: String, callback: Callable = Callable()) -> String:
|
|
||||||
var data = {"identifier": identifier}
|
|
||||||
return post_request("/auth/forgot-password", data, callback)
|
|
||||||
|
|
||||||
# 重置密码
|
|
||||||
func reset_password(identifier: String, verification_code: String, new_password: String, callback: Callable = Callable()) -> String:
|
|
||||||
var data = {
|
|
||||||
"identifier": identifier,
|
|
||||||
"verification_code": verification_code,
|
|
||||||
"new_password": new_password
|
|
||||||
}
|
|
||||||
return post_request("/auth/reset-password", data, callback)
|
|
||||||
|
|
||||||
# 修改密码
|
|
||||||
func change_password(user_id: String, old_password: String, new_password: String, callback: Callable = Callable()) -> String:
|
|
||||||
var data = {
|
|
||||||
"user_id": user_id,
|
|
||||||
"old_password": old_password,
|
|
||||||
"new_password": new_password
|
|
||||||
}
|
|
||||||
return put_request("/auth/change-password", data, callback)
|
|
||||||
|
|
||||||
# GitHub OAuth登录
|
|
||||||
func github_login(github_id: String, username: String, nickname: String, email: String, avatar_url: String = "", callback: Callable = Callable()) -> String:
|
|
||||||
var data = {
|
|
||||||
"github_id": github_id,
|
|
||||||
"username": username,
|
|
||||||
"nickname": nickname,
|
|
||||||
"email": email
|
|
||||||
}
|
|
||||||
|
|
||||||
if avatar_url != "":
|
|
||||||
data["avatar_url"] = avatar_url
|
|
||||||
|
|
||||||
return post_request("/auth/github", data, callback)
|
|
||||||
|
|
||||||
# ============ 核心请求处理 ============
|
|
||||||
|
|
||||||
# 发送请求的核心方法
|
|
||||||
func send_request(endpoint: String, method: RequestType, headers: PackedStringArray,
|
|
||||||
body: String, callback: Callable, timeout: float) -> String:
|
|
||||||
# 生成请求ID
|
|
||||||
request_counter += 1
|
|
||||||
var request_id = "req_" + str(request_counter)
|
|
||||||
|
|
||||||
# 构建完整URL
|
|
||||||
var full_url = API_BASE_URL + endpoint
|
|
||||||
|
|
||||||
# 创建HTTPRequest节点
|
|
||||||
var http_request = HTTPRequest.new()
|
|
||||||
add_child(http_request)
|
|
||||||
|
|
||||||
# 设置超时
|
|
||||||
http_request.timeout = timeout
|
|
||||||
|
|
||||||
# 创建请求信息
|
|
||||||
var request_info = RequestInfo.new(request_id, full_url, method, headers, body, timeout)
|
|
||||||
request_info.http_request = http_request
|
|
||||||
request_info.callback = callback
|
|
||||||
|
|
||||||
# 存储请求信息
|
|
||||||
active_requests[request_id] = request_info
|
|
||||||
|
|
||||||
# 连接信号
|
|
||||||
http_request.request_completed.connect(func(result: int, response_code: int, response_headers: PackedStringArray, response_body: PackedByteArray):
|
|
||||||
_on_request_completed(request_id, result, response_code, response_headers, response_body)
|
|
||||||
)
|
|
||||||
|
|
||||||
# 发送请求
|
|
||||||
var godot_method = _convert_to_godot_method(method)
|
|
||||||
var error = http_request.request(full_url, headers, godot_method, body)
|
|
||||||
|
|
||||||
print("=== 发送网络请求 ===")
|
|
||||||
print("请求ID: ", request_id)
|
|
||||||
print("URL: ", full_url)
|
|
||||||
print("方法: ", RequestType.keys()[method])
|
|
||||||
print("Headers: ", headers)
|
|
||||||
print("Body: ", body if body.length() < 200 else body.substr(0, 200) + "...")
|
|
||||||
print("发送结果: ", error)
|
|
||||||
|
|
||||||
if error != OK:
|
|
||||||
print("请求发送失败，错误代码: ", error)
|
|
||||||
_handle_request_error(request_id, ErrorType.NETWORK_ERROR, "网络请求发送失败: " + str(error))
|
|
||||||
return ""
|
|
||||||
|
|
||||||
return request_id
|
|
||||||
|
|
||||||
# 请求完成回调
|
|
||||||
func _on_request_completed(request_id: String, result: int, response_code: int,
|
|
||||||
headers: PackedStringArray, body: PackedByteArray):
|
|
||||||
print("=== 网络请求完成 ===")
|
|
||||||
print("请求ID: ", request_id)
|
|
||||||
print("结果: ", result)
|
|
||||||
print("状态码: ", response_code)
|
|
||||||
print("响应头: ", headers)
|
|
||||||
|
|
||||||
# 获取请求信息
|
|
||||||
if not active_requests.has(request_id):
|
|
||||||
print("警告: 未找到请求ID ", request_id)
|
|
||||||
return
|
|
||||||
|
|
||||||
var _request_info = active_requests[request_id]
|
|
||||||
var response_text = body.get_string_from_utf8()
|
|
||||||
|
|
||||||
print("响应体长度: ", body.size(), " 字节")
|
|
||||||
print("响应内容: ", response_text if response_text.length() < 500 else response_text.substr(0, 500) + "...")
|
|
||||||
|
|
||||||
# 处理网络连接失败
|
|
||||||
if response_code == 0:
|
|
||||||
_handle_request_error(request_id, ErrorType.NETWORK_ERROR, "网络连接失败，请检查网络连接")
|
|
||||||
return
|
|
||||||
|
|
||||||
# 解析JSON响应
|
|
||||||
var json = JSON.new()
|
|
||||||
var parse_result = json.parse(response_text)
|
|
||||||
if parse_result != OK:
|
|
||||||
_handle_request_error(request_id, ErrorType.PARSE_ERROR, "服务器响应格式错误")
|
|
||||||
return
|
|
||||||
|
|
||||||
var response_data = json.data
|
|
||||||
|
|
||||||
# 处理响应
|
|
||||||
_handle_response(request_id, response_code, response_data)
|
|
||||||
|
|
||||||
# 处理响应 - 支持API v1.1.1的状态码
|
|
||||||
func _handle_response(request_id: String, response_code: int, data: Dictionary):
|
|
||||||
var request_info = active_requests[request_id]
|
|
||||||
|
|
||||||
# 检查业务成功标志
|
|
||||||
var success = data.get("success", true) # 默认true保持向后兼容
|
|
||||||
var error_code = data.get("error_code", "")
|
|
||||||
var message = data.get("message", "")
|
|
||||||
|
|
||||||
# 判断请求是否成功
|
|
||||||
var is_success = false
|
|
||||||
|
|
||||||
# HTTP成功状态码且业务成功
|
|
||||||
if (response_code >= 200 and response_code < 300) and success:
|
|
||||||
is_success = true
|
|
||||||
# 特殊情况：206测试模式 - 根据API文档，这是成功的测试模式响应
|
|
||||||
elif response_code == 206 and error_code == "TEST_MODE_ONLY":
|
|
||||||
is_success = true
|
|
||||||
print("🧪 测试模式响应: ", message)
|
|
||||||
# 201创建成功
|
|
||||||
elif response_code == 201:
|
|
||||||
is_success = true
|
|
||||||
|
|
||||||
if is_success:
|
|
||||||
print("✅ 请求成功: ", request_id)
|
|
||||||
# 发送成功信号
|
|
||||||
request_completed.emit(request_id, true, data)
|
|
||||||
|
|
||||||
# 调用回调函数
|
|
||||||
if request_info.callback.is_valid():
|
|
||||||
request_info.callback.call(true, data, {})
|
|
||||||
else:
|
|
||||||
print("❌ 请求失败: ", request_id, " - HTTP:", response_code, " 错误码:", error_code, " 消息:", message)
|
|
||||||
|
|
||||||
# 确定错误类型
|
|
||||||
var error_type = _determine_error_type(response_code, error_code)
|
|
||||||
|
|
||||||
# 发送失败信号
|
|
||||||
request_failed.emit(request_id, ErrorType.keys()[error_type], message)
|
|
||||||
|
|
||||||
# 调用回调函数
|
|
||||||
if request_info.callback.is_valid():
|
|
||||||
var error_info = {
|
|
||||||
"response_code": response_code,
|
|
||||||
"error_code": error_code,
|
|
||||||
"message": message,
|
|
||||||
"error_type": error_type
|
|
||||||
}
|
|
||||||
request_info.callback.call(false, data, error_info)
|
|
||||||
|
|
||||||
# 清理请求
|
|
||||||
_cleanup_request(request_id)
|
|
||||||
|
|
||||||
# 处理请求错误
|
|
||||||
func _handle_request_error(request_id: String, error_type: ErrorType, message: String):
|
|
||||||
print("❌ 请求错误: ", request_id, " - ", message)
|
|
||||||
|
|
||||||
# 发送错误信号
|
|
||||||
request_failed.emit(request_id, ErrorType.keys()[error_type], message)
|
|
||||||
|
|
||||||
# 调用回调函数
|
|
||||||
if active_requests.has(request_id):
|
|
||||||
var request_info = active_requests[request_id]
|
|
||||||
if request_info.callback.is_valid():
|
|
||||||
var error_info = {
|
|
||||||
"error_type": error_type,
|
|
||||||
"message": message
|
|
||||||
}
|
|
||||||
request_info.callback.call(false, {}, error_info)
|
|
||||||
|
|
||||||
# 清理请求
|
|
||||||
_cleanup_request(request_id)
|
|
||||||
|
|
||||||
# 确定错误类型 - 支持更多状态码
|
|
||||||
func _determine_error_type(response_code: int, error_code: String) -> ErrorType:
|
|
||||||
# 根据错误码判断
|
|
||||||
match error_code:
|
|
||||||
"SERVICE_UNAVAILABLE":
|
|
||||||
return ErrorType.BUSINESS_ERROR
|
|
||||||
"TOO_MANY_REQUESTS":
|
|
||||||
return ErrorType.BUSINESS_ERROR
|
|
||||||
"TEST_MODE_ONLY":
|
|
||||||
return ErrorType.BUSINESS_ERROR
|
|
||||||
"SEND_EMAIL_VERIFICATION_FAILED", "REGISTER_FAILED":
|
|
||||||
# 这些可能是409冲突或其他业务错误
|
|
||||||
return ErrorType.BUSINESS_ERROR
|
|
||||||
_:
|
|
||||||
# 根据HTTP状态码判断
|
|
||||||
match response_code:
|
|
||||||
409: # 资源冲突
|
|
||||||
return ErrorType.BUSINESS_ERROR
|
|
||||||
206: # 测试模式
|
|
||||||
return ErrorType.BUSINESS_ERROR
|
|
||||||
429: # 频率限制
|
|
||||||
return ErrorType.BUSINESS_ERROR
|
|
||||||
_:
|
|
||||||
if response_code >= 400 and response_code < 500:
|
|
||||||
return ErrorType.HTTP_ERROR
|
|
||||||
elif response_code >= 500:
|
|
||||||
return ErrorType.HTTP_ERROR
|
|
||||||
else:
|
|
||||||
return ErrorType.BUSINESS_ERROR
|
|
||||||
|
|
||||||
# 清理请求资源
|
|
||||||
func _cleanup_request(request_id: String):
|
|
||||||
if active_requests.has(request_id):
|
|
||||||
var request_info = active_requests[request_id]
|
|
||||||
|
|
||||||
# 移除HTTPRequest节点
|
|
||||||
if is_instance_valid(request_info.http_request):
|
|
||||||
request_info.http_request.queue_free()
|
|
||||||
|
|
||||||
# 从活动请求中移除
|
|
||||||
active_requests.erase(request_id)
|
|
||||||
|
|
||||||
print("🧹 清理请求: ", request_id)
|
|
||||||
|
|
||||||
# 转换请求方法
|
|
||||||
func _convert_to_godot_method(method: RequestType) -> HTTPClient.Method:
|
|
||||||
match method:
|
|
||||||
RequestType.GET:
|
|
||||||
return HTTPClient.METHOD_GET
|
|
||||||
RequestType.POST:
|
|
||||||
return HTTPClient.METHOD_POST
|
|
||||||
RequestType.PUT:
|
|
||||||
return HTTPClient.METHOD_PUT
|
|
||||||
RequestType.DELETE:
|
|
||||||
return HTTPClient.METHOD_DELETE
|
|
||||||
RequestType.PATCH:
|
|
||||||
return HTTPClient.METHOD_PATCH
|
|
||||||
_:
|
|
||||||
return HTTPClient.METHOD_GET
|
|
||||||
|
|
||||||
# ============ 工具方法 ============
|
|
||||||
|
|
||||||
# 取消请求
|
|
||||||
func cancel_request(request_id: String) -> bool:
|
|
||||||
if active_requests.has(request_id):
|
|
||||||
print("🚫 取消请求: ", request_id)
|
|
||||||
_cleanup_request(request_id)
|
|
||||||
return true
|
|
||||||
return false
|
|
||||||
|
|
||||||
# 取消所有请求
|
|
||||||
func cancel_all_requests():
|
|
||||||
print("🚫 取消所有请求")
|
|
||||||
var request_ids = active_requests.keys()
|
|
||||||
for request_id in request_ids:
|
|
||||||
cancel_request(request_id)
|
|
||||||
|
|
||||||
# 获取活动请求数量
|
|
||||||
func get_active_request_count() -> int:
|
|
||||||
return active_requests.size()
|
|
||||||
|
|
||||||
# 检查请求是否活动
|
|
||||||
func is_request_active(request_id: String) -> bool:
|
|
||||||
return active_requests.has(request_id)
|
|
||||||
|
|
||||||
# 获取请求信息
|
|
||||||
func get_request_info(request_id: String) -> Dictionary:
|
|
||||||
if active_requests.has(request_id):
|
|
||||||
var info = active_requests[request_id]
|
|
||||||
return {
|
|
||||||
"id": info.id,
|
|
||||||
"url": info.url,
|
|
||||||
"method": RequestType.keys()[info.method],
|
|
||||||
"start_time": info.start_time,
|
|
||||||
"timeout": info.timeout
|
|
||||||
}
|
|
||||||
return {}
|
|
||||||
|
|
||||||
func _notification(what):
|
|
||||||
if what == NOTIFICATION_WM_CLOSE_REQUEST:
|
|
||||||
# 应用关闭时取消所有请求
|
|
||||||
cancel_all_requests()
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
uid://dr7v30wheetca
|
|
||||||
@@ -1,590 +0,0 @@
|
|||||||
extends Node
|
|
||||||
|
|
||||||
# 响应处理器 - 统一处理API响应和错误
|
|
||||||
|
|
||||||
# 响应处理结果
|
|
||||||
class ResponseResult:
|
|
||||||
var success: bool
|
|
||||||
var message: String
|
|
||||||
var toast_type: String # "success" 或 "error"
|
|
||||||
var data: Dictionary
|
|
||||||
var should_show_toast: bool
|
|
||||||
var custom_action: Callable
|
|
||||||
|
|
||||||
func _init():
|
|
||||||
success = false
|
|
||||||
message = ""
|
|
||||||
toast_type = "error"
|
|
||||||
data = {}
|
|
||||||
should_show_toast = true
|
|
||||||
custom_action = Callable()
|
|
||||||
|
|
||||||
# 错误码映射表 - 根据API v1.1.1更新
|
|
||||||
const ERROR_CODE_MESSAGES = {
|
|
||||||
# 登录相关
|
|
||||||
"LOGIN_FAILED": "登录失败",
|
|
||||||
"VERIFICATION_CODE_LOGIN_FAILED": "验证码错误或已过期",
|
|
||||||
"EMAIL_NOT_VERIFIED": "请先验证邮箱",
|
|
||||||
|
|
||||||
# 注册相关
|
|
||||||
"REGISTER_FAILED": "注册失败",
|
|
||||||
|
|
||||||
# 验证码相关
|
|
||||||
"SEND_CODE_FAILED": "发送验证码失败",
|
|
||||||
"SEND_LOGIN_CODE_FAILED": "发送登录验证码失败",
|
|
||||||
"SEND_EMAIL_VERIFICATION_FAILED": "发送邮箱验证码失败",
|
|
||||||
"RESEND_EMAIL_VERIFICATION_FAILED": "重新发送验证码失败",
|
|
||||||
"EMAIL_VERIFICATION_FAILED": "邮箱验证失败",
|
|
||||||
"RESET_PASSWORD_FAILED": "重置密码失败",
|
|
||||||
"CHANGE_PASSWORD_FAILED": "修改密码失败",
|
|
||||||
"VERIFICATION_CODE_EXPIRED": "验证码已过期",
|
|
||||||
"VERIFICATION_CODE_INVALID": "验证码无效",
|
|
||||||
"VERIFICATION_CODE_ATTEMPTS_EXCEEDED": "验证码尝试次数过多",
|
|
||||||
"VERIFICATION_CODE_RATE_LIMITED": "验证码发送过于频繁",
|
|
||||||
"VERIFICATION_CODE_HOURLY_LIMIT": "验证码每小时发送次数已达上限",
|
|
||||||
|
|
||||||
# 用户状态相关
|
|
||||||
"USER_NOT_FOUND": "用户不存在",
|
|
||||||
"INVALID_IDENTIFIER": "请输入有效的邮箱或手机号",
|
|
||||||
"USER_STATUS_UPDATE_FAILED": "用户状态更新失败",
|
|
||||||
|
|
||||||
# 系统状态相关
|
|
||||||
"TEST_MODE_ONLY": "测试模式",
|
|
||||||
"TOO_MANY_REQUESTS": "请求过于频繁，请稍后再试",
|
|
||||||
"SERVICE_UNAVAILABLE": "系统维护中，请稍后再试",
|
|
||||||
|
|
||||||
# 权限相关
|
|
||||||
"UNAUTHORIZED": "未授权访问",
|
|
||||||
"FORBIDDEN": "权限不足",
|
|
||||||
"ADMIN_LOGIN_FAILED": "管理员登录失败",
|
|
||||||
|
|
||||||
# 其他
|
|
||||||
"VALIDATION_FAILED": "参数验证失败",
|
|
||||||
"UNSUPPORTED_MEDIA_TYPE": "不支持的请求格式",
|
|
||||||
"REQUEST_TIMEOUT": "请求超时"
|
|
||||||
}
|
|
||||||
|
|
||||||
# HTTP状态码消息映射 - 根据API v1.1.1更新
|
|
||||||
const HTTP_STATUS_MESSAGES = {
|
|
||||||
200: "请求成功",
|
|
||||||
201: "创建成功",
|
|
||||||
206: "测试模式",
|
|
||||||
400: "请求参数错误",
|
|
||||||
401: "认证失败",
|
|
||||||
403: "权限不足",
|
|
||||||
404: "资源不存在",
|
|
||||||
408: "请求超时",
|
|
||||||
409: "资源冲突",
|
|
||||||
415: "不支持的媒体类型",
|
|
||||||
429: "请求过于频繁",
|
|
||||||
500: "服务器内部错误",
|
|
||||||
503: "服务不可用"
|
|
||||||
}
|
|
||||||
|
|
||||||
# ============ 主要处理方法 ============
|
|
||||||
|
|
||||||
# 处理登录响应
|
|
||||||
func handle_login_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
|
|
||||||
if success:
|
|
||||||
result.success = true
|
|
||||||
result.message = "登录成功！正在进入鲸鱼镇..."
|
|
||||||
result.toast_type = "success"
|
|
||||||
result.data = data
|
|
||||||
|
|
||||||
# 自定义动作：延迟发送登录成功信号
|
|
||||||
result.custom_action = func():
|
|
||||||
await Engine.get_main_loop().create_timer(1.0).timeout
|
|
||||||
# 这里可以发送登录成功信号或执行其他逻辑
|
|
||||||
else:
|
|
||||||
result = _handle_login_error(data, error_info)
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
# 处理验证码登录响应
|
|
||||||
func handle_verification_code_login_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
|
|
||||||
if success:
|
|
||||||
result.success = true
|
|
||||||
result.message = "验证码登录成功！正在进入鲸鱼镇..."
|
|
||||||
result.toast_type = "success"
|
|
||||||
result.data = data
|
|
||||||
|
|
||||||
result.custom_action = func():
|
|
||||||
await Engine.get_main_loop().create_timer(1.0).timeout
|
|
||||||
# 登录成功后的处理逻辑
|
|
||||||
else:
|
|
||||||
result = _handle_verification_code_login_error(data, error_info)
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
# 处理发送验证码响应 - 支持邮箱冲突检测
|
|
||||||
func handle_send_verification_code_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
|
|
||||||
if success:
|
|
||||||
var error_code = data.get("error_code", "")
|
|
||||||
if error_code == "TEST_MODE_ONLY":
|
|
||||||
result.success = true
|
|
||||||
result.message = "🧪 测试模式：验证码已生成，请查看控制台"
|
|
||||||
result.toast_type = "success"
|
|
||||||
|
|
||||||
# 在控制台显示验证码
|
|
||||||
if data.has("data") and data.data.has("verification_code"):
|
|
||||||
print("🔑 测试模式验证码: ", data.data.verification_code)
|
|
||||||
result.message += "\n验证码: " + str(data.data.verification_code)
|
|
||||||
else:
|
|
||||||
result.success = true
|
|
||||||
result.message = "📧 验证码已发送到您的邮箱，请查收"
|
|
||||||
result.toast_type = "success"
|
|
||||||
|
|
||||||
# 开发环境下显示验证码
|
|
||||||
if data.has("data") and data.data.has("verification_code"):
|
|
||||||
print("🔑 开发环境验证码: ", data.data.verification_code)
|
|
||||||
else:
|
|
||||||
result = _handle_send_code_error(data, error_info)
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
# 处理发送登录验证码响应
|
|
||||||
func handle_send_login_code_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
|
|
||||||
if success:
|
|
||||||
var error_code = data.get("error_code", "")
|
|
||||||
if error_code == "TEST_MODE_ONLY":
|
|
||||||
result.success = true
|
|
||||||
result.message = "测试模式：登录验证码已生成，请查看控制台"
|
|
||||||
result.toast_type = "success"
|
|
||||||
|
|
||||||
if data.has("data") and data.data.has("verification_code"):
|
|
||||||
print("测试模式登录验证码: ", data.data.verification_code)
|
|
||||||
else:
|
|
||||||
result.success = true
|
|
||||||
result.message = "登录验证码已发送，请查收"
|
|
||||||
result.toast_type = "success"
|
|
||||||
|
|
||||||
if data.has("data") and data.data.has("verification_code"):
|
|
||||||
print("开发环境登录验证码: ", data.data.verification_code)
|
|
||||||
else:
|
|
||||||
result = _handle_send_login_code_error(data, error_info)
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
# 处理注册响应
|
|
||||||
func handle_register_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
|
|
||||||
if success:
|
|
||||||
result.success = true
|
|
||||||
result.message = "注册成功！欢迎加入鲸鱼镇"
|
|
||||||
result.toast_type = "success"
|
|
||||||
result.data = data
|
|
||||||
|
|
||||||
# 自定义动作：清空表单，切换到登录界面
|
|
||||||
result.custom_action = func():
|
|
||||||
# 这里可以执行清空表单、切换界面等操作
|
|
||||||
pass
|
|
||||||
else:
|
|
||||||
result = _handle_register_error(data, error_info)
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
# 处理邮箱验证响应
|
|
||||||
func handle_verify_email_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
|
|
||||||
if success:
|
|
||||||
result.success = true
|
|
||||||
result.message = "邮箱验证成功，正在注册..."
|
|
||||||
result.toast_type = "success"
|
|
||||||
result.data = data
|
|
||||||
else:
|
|
||||||
result = _handle_verify_email_error(data, error_info)
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
# 处理重新发送邮箱验证码响应
|
|
||||||
func handle_resend_email_verification_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
|
|
||||||
if success:
|
|
||||||
var error_code = data.get("error_code", "")
|
|
||||||
if error_code == "TEST_MODE_ONLY":
|
|
||||||
result.success = true
|
|
||||||
result.message = "🧪 测试模式：验证码已重新生成，请查看控制台"
|
|
||||||
result.toast_type = "success"
|
|
||||||
|
|
||||||
if data.has("data") and data.data.has("verification_code"):
|
|
||||||
print("🔑 测试模式重新发送验证码: ", data.data.verification_code)
|
|
||||||
else:
|
|
||||||
result.success = true
|
|
||||||
result.message = "📧 验证码已重新发送到您的邮箱，请查收"
|
|
||||||
result.toast_type = "success"
|
|
||||||
|
|
||||||
if data.has("data") and data.data.has("verification_code"):
|
|
||||||
print("🔑 开发环境重新发送验证码: ", data.data.verification_code)
|
|
||||||
else:
|
|
||||||
result = _handle_resend_email_verification_error(data, error_info)
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
# 处理忘记密码响应
|
|
||||||
func handle_forgot_password_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
|
|
||||||
if success:
|
|
||||||
var error_code = data.get("error_code", "")
|
|
||||||
if error_code == "TEST_MODE_ONLY":
|
|
||||||
result.success = true
|
|
||||||
result.message = "🧪 测试模式：重置验证码已生成，请查看控制台"
|
|
||||||
result.toast_type = "success"
|
|
||||||
|
|
||||||
if data.has("data") and data.data.has("verification_code"):
|
|
||||||
print("🔑 测试模式重置验证码: ", data.data.verification_code)
|
|
||||||
else:
|
|
||||||
result.success = true
|
|
||||||
result.message = "📧 重置验证码已发送，请查收"
|
|
||||||
result.toast_type = "success"
|
|
||||||
|
|
||||||
if data.has("data") and data.data.has("verification_code"):
|
|
||||||
print("🔑 开发环境重置验证码: ", data.data.verification_code)
|
|
||||||
else:
|
|
||||||
result = _handle_forgot_password_error(data, error_info)
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
# 处理重置密码响应
|
|
||||||
func handle_reset_password_response(success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
|
|
||||||
if success:
|
|
||||||
result.success = true
|
|
||||||
result.message = "🔒 密码重置成功，请使用新密码登录"
|
|
||||||
result.toast_type = "success"
|
|
||||||
result.data = data
|
|
||||||
else:
|
|
||||||
result = _handle_reset_password_error(data, error_info)
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
# ============ 错误处理方法 ============
|
|
||||||
|
|
||||||
# 处理登录错误
|
|
||||||
func _handle_login_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
var error_code = data.get("error_code", "")
|
|
||||||
var message = data.get("message", "登录失败")
|
|
||||||
|
|
||||||
match error_code:
|
|
||||||
"LOGIN_FAILED":
|
|
||||||
# 根据消息内容进一步判断用户状态
|
|
||||||
if "账户已锁定" in message or "locked" in message.to_lower():
|
|
||||||
result.message = "账户已被锁定，请联系管理员"
|
|
||||||
elif "账户已禁用" in message or "banned" in message.to_lower():
|
|
||||||
result.message = "账户已被禁用，请联系管理员"
|
|
||||||
elif "账户待审核" in message or "pending" in message.to_lower():
|
|
||||||
result.message = "账户待审核，请等待管理员审核"
|
|
||||||
elif "邮箱未验证" in message or "inactive" in message.to_lower():
|
|
||||||
result.message = "请先验证邮箱后再登录"
|
|
||||||
else:
|
|
||||||
result.message = "用户名或密码错误，请检查后重试"
|
|
||||||
_:
|
|
||||||
result.message = _get_error_message(error_code, message, error_info)
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
# 处理验证码登录错误
|
|
||||||
func _handle_verification_code_login_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
var error_code = data.get("error_code", "")
|
|
||||||
var message = data.get("message", "验证码登录失败")
|
|
||||||
|
|
||||||
match error_code:
|
|
||||||
"VERIFICATION_CODE_LOGIN_FAILED":
|
|
||||||
result.message = "验证码错误或已过期"
|
|
||||||
"EMAIL_NOT_VERIFIED":
|
|
||||||
result.message = "邮箱未验证，请先验证邮箱后再使用验证码登录"
|
|
||||||
"USER_NOT_FOUND":
|
|
||||||
result.message = "用户不存在，请先注册"
|
|
||||||
"INVALID_IDENTIFIER":
|
|
||||||
result.message = "请输入有效的邮箱或手机号"
|
|
||||||
_:
|
|
||||||
result.message = _get_error_message(error_code, message, error_info)
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
# 处理发送验证码错误 - 支持邮箱冲突检测和频率限制
|
|
||||||
func _handle_send_code_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
var error_code = data.get("error_code", "")
|
|
||||||
var message = data.get("message", "发送验证码失败")
|
|
||||||
var response_code = error_info.get("response_code", 0)
|
|
||||||
|
|
||||||
match error_code:
|
|
||||||
"SEND_EMAIL_VERIFICATION_FAILED":
|
|
||||||
# 检查是否是邮箱冲突（409状态码）
|
|
||||||
if response_code == 409:
|
|
||||||
result.message = "⚠️ 邮箱已被注册，请使用其他邮箱或直接登录"
|
|
||||||
result.toast_type = "error"
|
|
||||||
elif "邮箱格式" in message:
|
|
||||||
result.message = "📧 请输入有效的邮箱地址"
|
|
||||||
else:
|
|
||||||
result.message = message
|
|
||||||
"TOO_MANY_REQUESTS":
|
|
||||||
# 处理频率限制，提供重试建议
|
|
||||||
result.toast_type = "error"
|
|
||||||
|
|
||||||
# 如果有throttle_info，显示更详细的信息
|
|
||||||
if data.has("throttle_info"):
|
|
||||||
var throttle_info = data.throttle_info
|
|
||||||
var reset_time = throttle_info.get("reset_time", "")
|
|
||||||
if reset_time != "":
|
|
||||||
var relative_time = StringUtils.get_relative_time_until(reset_time)
|
|
||||||
var local_time = StringUtils.format_utc_to_local_time(reset_time)
|
|
||||||
result.message = "⏰ 验证码发送过于频繁"
|
|
||||||
result.message += "\n请" + relative_time + "再试"
|
|
||||||
result.message += "\n重试时间: " + local_time
|
|
||||||
else:
|
|
||||||
result.message = "⏰ 验证码发送过于频繁，请稍后再试"
|
|
||||||
else:
|
|
||||||
result.message = "⏰ 验证码发送过于频繁，请稍后再试"
|
|
||||||
"VERIFICATION_CODE_RATE_LIMITED":
|
|
||||||
result.message = "⏰ 验证码发送过于频繁，请稍后再试"
|
|
||||||
"VERIFICATION_CODE_HOURLY_LIMIT":
|
|
||||||
result.message = "⏰ 每小时发送次数已达上限，请稍后再试"
|
|
||||||
_:
|
|
||||||
result.message = _get_error_message(error_code, message, error_info)
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
# 处理发送登录验证码错误
|
|
||||||
func _handle_send_login_code_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
var error_code = data.get("error_code", "")
|
|
||||||
var message = data.get("message", "发送登录验证码失败")
|
|
||||||
|
|
||||||
match error_code:
|
|
||||||
"SEND_LOGIN_CODE_FAILED":
|
|
||||||
if "用户不存在" in message:
|
|
||||||
result.message = "用户不存在，请先注册"
|
|
||||||
else:
|
|
||||||
result.message = "发送登录验证码失败"
|
|
||||||
"USER_NOT_FOUND":
|
|
||||||
result.message = "用户不存在，请先注册"
|
|
||||||
"INVALID_IDENTIFIER":
|
|
||||||
result.message = "请输入有效的邮箱或手机号"
|
|
||||||
_:
|
|
||||||
result.message = _get_error_message(error_code, message, error_info)
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
# 处理注册错误 - 支持409冲突状态码
|
|
||||||
func _handle_register_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
var error_code = data.get("error_code", "")
|
|
||||||
var message = data.get("message", "注册失败")
|
|
||||||
var response_code = error_info.get("response_code", 0)
|
|
||||||
|
|
||||||
match error_code:
|
|
||||||
"REGISTER_FAILED":
|
|
||||||
# 检查409冲突状态码
|
|
||||||
if response_code == 409:
|
|
||||||
if "邮箱已存在" in message or "邮箱已被使用" in message:
|
|
||||||
result.message = "📧 邮箱已被注册，请使用其他邮箱或直接登录"
|
|
||||||
elif "用户名已存在" in message or "用户名已被使用" in message:
|
|
||||||
result.message = "👤 用户名已被使用，请换一个"
|
|
||||||
else:
|
|
||||||
result.message = "⚠️ 资源冲突：" + message
|
|
||||||
elif "邮箱验证码" in message or "verification_code" in message:
|
|
||||||
result.message = "🔑 请先获取并输入邮箱验证码"
|
|
||||||
elif "用户名" in message:
|
|
||||||
result.message = "👤 用户名格式不正确"
|
|
||||||
elif "邮箱" in message:
|
|
||||||
result.message = "📧 邮箱格式不正确"
|
|
||||||
elif "密码" in message:
|
|
||||||
result.message = "🔒 密码格式不符合要求"
|
|
||||||
elif "验证码" in message:
|
|
||||||
result.message = "🔑 验证码错误或已过期"
|
|
||||||
else:
|
|
||||||
result.message = message
|
|
||||||
_:
|
|
||||||
result.message = _get_error_message(error_code, message, error_info)
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
# 处理邮箱验证错误
|
|
||||||
func _handle_verify_email_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
var error_code = data.get("error_code", "")
|
|
||||||
var message = data.get("message", "邮箱验证失败")
|
|
||||||
|
|
||||||
match error_code:
|
|
||||||
"EMAIL_VERIFICATION_FAILED":
|
|
||||||
if "验证码错误" in message:
|
|
||||||
result.message = "🔑 验证码错误"
|
|
||||||
elif "验证码已过期" in message:
|
|
||||||
result.message = "🔑 验证码已过期，请重新获取"
|
|
||||||
else:
|
|
||||||
result.message = message
|
|
||||||
"VERIFICATION_CODE_INVALID":
|
|
||||||
result.message = "🔑 验证码错误或已过期"
|
|
||||||
"VERIFICATION_CODE_EXPIRED":
|
|
||||||
result.message = "🔑 验证码已过期，请重新获取"
|
|
||||||
_:
|
|
||||||
result.message = _get_error_message(error_code, message, error_info)
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
# 处理网络测试响应
|
|
||||||
func handle_network_test_response(success: bool, _data: Dictionary, _error_info: Dictionary = {}) -> ResponseResult:
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
|
|
||||||
if success:
|
|
||||||
result.success = true
|
|
||||||
result.message = "🌐 网络连接正常"
|
|
||||||
result.toast_type = "success"
|
|
||||||
else:
|
|
||||||
result.success = false
|
|
||||||
result.message = "🌐 网络连接异常"
|
|
||||||
result.toast_type = "error"
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
# 处理重新发送邮箱验证码错误
|
|
||||||
func _handle_resend_email_verification_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
var error_code = data.get("error_code", "")
|
|
||||||
var message = data.get("message", "重新发送验证码失败")
|
|
||||||
|
|
||||||
match error_code:
|
|
||||||
"RESEND_EMAIL_VERIFICATION_FAILED":
|
|
||||||
if "邮箱已验证" in message:
|
|
||||||
result.message = "📧 邮箱已验证，无需重复验证"
|
|
||||||
else:
|
|
||||||
result.message = message
|
|
||||||
_:
|
|
||||||
result.message = _get_error_message(error_code, message, error_info)
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
# 处理忘记密码错误
|
|
||||||
func _handle_forgot_password_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
var error_code = data.get("error_code", "")
|
|
||||||
var message = data.get("message", "发送重置验证码失败")
|
|
||||||
|
|
||||||
match error_code:
|
|
||||||
"SEND_CODE_FAILED":
|
|
||||||
if "用户不存在" in message:
|
|
||||||
result.message = "👤 用户不存在，请检查邮箱或手机号"
|
|
||||||
else:
|
|
||||||
result.message = message
|
|
||||||
"USER_NOT_FOUND":
|
|
||||||
result.message = "👤 用户不存在，请检查邮箱或手机号"
|
|
||||||
_:
|
|
||||||
result.message = _get_error_message(error_code, message, error_info)
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
# 处理重置密码错误
|
|
||||||
func _handle_reset_password_error(data: Dictionary, error_info: Dictionary) -> ResponseResult:
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
var error_code = data.get("error_code", "")
|
|
||||||
var message = data.get("message", "重置密码失败")
|
|
||||||
|
|
||||||
match error_code:
|
|
||||||
"RESET_PASSWORD_FAILED":
|
|
||||||
if "验证码" in message:
|
|
||||||
result.message = "🔑 验证码错误或已过期"
|
|
||||||
else:
|
|
||||||
result.message = message
|
|
||||||
_:
|
|
||||||
result.message = _get_error_message(error_code, message, error_info)
|
|
||||||
|
|
||||||
return result
|
|
||||||
|
|
||||||
# ============ 工具方法 ============
|
|
||||||
|
|
||||||
# 获取错误消息 - 支持更多状态码和错误处理
|
|
||||||
func _get_error_message(error_code: String, original_message: String, error_info: Dictionary) -> String:
|
|
||||||
# 优先使用错误码映射
|
|
||||||
if ERROR_CODE_MESSAGES.has(error_code):
|
|
||||||
return ERROR_CODE_MESSAGES[error_code]
|
|
||||||
|
|
||||||
# 处理频率限制
|
|
||||||
if error_code == "TOO_MANY_REQUESTS":
|
|
||||||
return _handle_rate_limit_message(original_message, error_info)
|
|
||||||
|
|
||||||
# 处理维护模式
|
|
||||||
if error_code == "SERVICE_UNAVAILABLE":
|
|
||||||
return _handle_maintenance_message(original_message, error_info)
|
|
||||||
|
|
||||||
# 处理测试模式
|
|
||||||
if error_code == "TEST_MODE_ONLY":
|
|
||||||
return "🧪 测试模式：" + original_message
|
|
||||||
|
|
||||||
# 根据HTTP状态码处理
|
|
||||||
if error_info.has("response_code"):
|
|
||||||
var response_code = error_info.response_code
|
|
||||||
match response_code:
|
|
||||||
409:
|
|
||||||
return "⚠️ 资源冲突：" + original_message
|
|
||||||
206:
|
|
||||||
return "🧪 测试模式：" + original_message
|
|
||||||
429:
|
|
||||||
return "⏰ 请求过于频繁，请稍后再试"
|
|
||||||
_:
|
|
||||||
if HTTP_STATUS_MESSAGES.has(response_code):
|
|
||||||
return HTTP_STATUS_MESSAGES[response_code] + "：" + original_message
|
|
||||||
|
|
||||||
# 返回原始消息
|
|
||||||
return original_message if original_message != "" else "操作失败"
|
|
||||||
|
|
||||||
# 处理频率限制消息
|
|
||||||
func _handle_rate_limit_message(message: String, _error_info: Dictionary) -> String:
|
|
||||||
# 可以根据throttle_info提供更详细的信息
|
|
||||||
return message + "，请稍后再试"
|
|
||||||
|
|
||||||
# 处理维护模式消息
|
|
||||||
func _handle_maintenance_message(_message: String, _error_info: Dictionary) -> String:
|
|
||||||
# 可以根据maintenance_info提供更详细的信息
|
|
||||||
return "系统维护中，请稍后再试"
|
|
||||||
|
|
||||||
# 通用响应处理器 - 支持更多操作类型
|
|
||||||
func handle_response(operation_type: String, success: bool, data: Dictionary, error_info: Dictionary = {}) -> ResponseResult:
|
|
||||||
match operation_type:
|
|
||||||
"login":
|
|
||||||
return handle_login_response(success, data, error_info)
|
|
||||||
"verification_code_login":
|
|
||||||
return handle_verification_code_login_response(success, data, error_info)
|
|
||||||
"send_code":
|
|
||||||
return handle_send_verification_code_response(success, data, error_info)
|
|
||||||
"send_login_code":
|
|
||||||
return handle_send_login_code_response(success, data, error_info)
|
|
||||||
"register":
|
|
||||||
return handle_register_response(success, data, error_info)
|
|
||||||
"verify_email":
|
|
||||||
return handle_verify_email_response(success, data, error_info)
|
|
||||||
"resend_email_verification":
|
|
||||||
return handle_resend_email_verification_response(success, data, error_info)
|
|
||||||
"forgot_password":
|
|
||||||
return handle_forgot_password_response(success, data, error_info)
|
|
||||||
"reset_password":
|
|
||||||
return handle_reset_password_response(success, data, error_info)
|
|
||||||
"network_test":
|
|
||||||
return handle_network_test_response(success, data, error_info)
|
|
||||||
_:
|
|
||||||
# 通用处理
|
|
||||||
var result = ResponseResult.new()
|
|
||||||
if success:
|
|
||||||
result.success = true
|
|
||||||
result.message = "✅ 操作成功"
|
|
||||||
result.toast_type = "success"
|
|
||||||
else:
|
|
||||||
result.success = false
|
|
||||||
result.message = _get_error_message(data.get("error_code", ""), data.get("message", "操作失败"), error_info)
|
|
||||||
result.toast_type = "error"
|
|
||||||
return result
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
uid://nseguk2ytiw6
|
|
||||||
@@ -1,75 +0,0 @@
|
|||||||
extends Node
|
|
||||||
|
|
||||||
# 场景管理器 - 负责场景切换和管理
|
|
||||||
# 提供场景切换的统一接口
|
|
||||||
|
|
||||||
signal scene_changed(scene_name: String)
|
|
||||||
signal scene_change_started(scene_name: String)
|
|
||||||
|
|
||||||
var current_scene_name: String = ""
|
|
||||||
var is_changing_scene: bool = false
|
|
||||||
|
|
||||||
# 场景路径映射
|
|
||||||
var scene_paths: Dictionary = {
|
|
||||||
"main": "res://scenes/maps/main_scene.tscn",
|
|
||||||
"auth": "res://scenes/ui/LoginWindow.tscn",
|
|
||||||
"game": "res://scenes/maps/game_scene.tscn",
|
|
||||||
"battle": "res://scenes/maps/battle_scene.tscn",
|
|
||||||
"inventory": "res://scenes/ui/InventoryWindow.tscn",
|
|
||||||
"shop": "res://scenes/ui/ShopWindow.tscn",
|
|
||||||
"settings": "res://scenes/ui/SettingsWindow.tscn"
|
|
||||||
}
|
|
||||||
|
|
||||||
func _ready():
|
|
||||||
print("SceneManager 初始化完成")
|
|
||||||
|
|
||||||
func change_scene(scene_name: String, use_transition: bool = true):
|
|
||||||
if is_changing_scene:
|
|
||||||
print("场景切换中，忽略新的切换请求")
|
|
||||||
return false
|
|
||||||
|
|
||||||
if not scene_paths.has(scene_name):
|
|
||||||
print("错误: 未找到场景 ", scene_name)
|
|
||||||
return false
|
|
||||||
|
|
||||||
var scene_path = scene_paths[scene_name]
|
|
||||||
print("开始切换场景: ", current_scene_name, " -> ", scene_name)
|
|
||||||
|
|
||||||
is_changing_scene = true
|
|
||||||
scene_change_started.emit(scene_name)
|
|
||||||
|
|
||||||
if use_transition:
|
|
||||||
await show_transition()
|
|
||||||
|
|
||||||
var error = get_tree().change_scene_to_file(scene_path)
|
|
||||||
if error != OK:
|
|
||||||
print("场景切换失败: ", error)
|
|
||||||
is_changing_scene = false
|
|
||||||
return false
|
|
||||||
|
|
||||||
current_scene_name = scene_name
|
|
||||||
is_changing_scene = false
|
|
||||||
scene_changed.emit(scene_name)
|
|
||||||
|
|
||||||
if use_transition:
|
|
||||||
await hide_transition()
|
|
||||||
|
|
||||||
print("场景切换完成: ", scene_name)
|
|
||||||
return true
|
|
||||||
|
|
||||||
func get_current_scene_name() -> String:
|
|
||||||
return current_scene_name
|
|
||||||
|
|
||||||
func register_scene(scene_name: String, scene_path: String):
|
|
||||||
scene_paths[scene_name] = scene_path
|
|
||||||
print("注册场景: ", scene_name, " -> ", scene_path)
|
|
||||||
|
|
||||||
func show_transition():
|
|
||||||
# TODO: 实现场景切换过渡效果
|
|
||||||
print("显示场景切换过渡效果")
|
|
||||||
await get_tree().create_timer(0.2).timeout
|
|
||||||
|
|
||||||
func hide_transition():
|
|
||||||
# TODO: 隐藏场景切换过渡效果
|
|
||||||
print("隐藏场景切换过渡效果")
|
|
||||||
await get_tree().create_timer(0.2).timeout
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
uid://d3l286ti5gqhw
|
|
||||||
@@ -1,80 +0,0 @@
|
|||||||
extends Node
|
|
||||||
|
|
||||||
# 全局事件系统 - 提供解耦的事件通信机制
|
|
||||||
# 允许不同模块之间通过事件进行通信，避免直接依赖
|
|
||||||
|
|
||||||
# 事件监听器存储
|
|
||||||
var event_listeners: Dictionary = {}
|
|
||||||
|
|
||||||
func _ready():
|
|
||||||
print("EventSystem 初始化完成")
|
|
||||||
|
|
||||||
# 注册事件监听器
|
|
||||||
func connect_event(event_name: String, callback: Callable, target: Node = null):
|
|
||||||
if not event_listeners.has(event_name):
|
|
||||||
event_listeners[event_name] = []
|
|
||||||
|
|
||||||
var listener_info = {
|
|
||||||
"callback": callback,
|
|
||||||
"target": target
|
|
||||||
}
|
|
||||||
|
|
||||||
event_listeners[event_name].append(listener_info)
|
|
||||||
print("注册事件监听器: ", event_name, " -> ", callback)
|
|
||||||
|
|
||||||
# 移除事件监听器
|
|
||||||
func disconnect_event(event_name: String, callback: Callable, target: Node = null):
|
|
||||||
if not event_listeners.has(event_name):
|
|
||||||
return
|
|
||||||
|
|
||||||
var listeners = event_listeners[event_name]
|
|
||||||
for i in range(listeners.size() - 1, -1, -1):
|
|
||||||
var listener = listeners[i]
|
|
||||||
if listener.callback == callback and listener.target == target:
|
|
||||||
listeners.remove_at(i)
|
|
||||||
print("移除事件监听器: ", event_name, " -> ", callback)
|
|
||||||
break
|
|
||||||
|
|
||||||
# 发送事件
|
|
||||||
func emit_event(event_name: String, data: Variant = null):
|
|
||||||
print("发送事件: ", event_name, " 数据: ", data)
|
|
||||||
|
|
||||||
if not event_listeners.has(event_name):
|
|
||||||
return
|
|
||||||
|
|
||||||
var listeners = event_listeners[event_name]
|
|
||||||
for listener_info in listeners:
|
|
||||||
var target = listener_info.target
|
|
||||||
var callback = listener_info.callback
|
|
||||||
|
|
||||||
# 检查目标节点是否仍然有效
|
|
||||||
if target != null and not is_instance_valid(target):
|
|
||||||
continue
|
|
||||||
|
|
||||||
# 调用回调函数
|
|
||||||
if data != null:
|
|
||||||
callback.call(data)
|
|
||||||
else:
|
|
||||||
callback.call()
|
|
||||||
|
|
||||||
# 清理无效的监听器
|
|
||||||
func cleanup_invalid_listeners():
|
|
||||||
for event_name in event_listeners.keys():
|
|
||||||
var listeners = event_listeners[event_name]
|
|
||||||
for i in range(listeners.size() - 1, -1, -1):
|
|
||||||
var listener = listeners[i]
|
|
||||||
var target = listener.target
|
|
||||||
if target != null and not is_instance_valid(target):
|
|
||||||
listeners.remove_at(i)
|
|
||||||
print("清理无效监听器: ", event_name)
|
|
||||||
|
|
||||||
# 获取事件监听器数量
|
|
||||||
func get_listener_count(event_name: String) -> int:
|
|
||||||
if not event_listeners.has(event_name):
|
|
||||||
return 0
|
|
||||||
return event_listeners[event_name].size()
|
|
||||||
|
|
||||||
# 清空所有事件监听器
|
|
||||||
func clear_all_listeners():
|
|
||||||
event_listeners.clear()
|
|
||||||
print("清空所有事件监听器")
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
uid://bfheblucmti24
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
# 核心工具类目录
|
|
||||||
# 存放字符串处理、数学计算等工具类
|
|
||||||
@@ -1,199 +0,0 @@
|
|||||||
class_name StringUtils
|
|
||||||
|
|
||||||
# 字符串工具类 - 提供常用的字符串处理功能
|
|
||||||
|
|
||||||
# 验证邮箱格式
|
|
||||||
static func is_valid_email(email: String) -> bool:
|
|
||||||
var regex = RegEx.new()
|
|
||||||
regex.compile("^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$")
|
|
||||||
return regex.search(email) != null
|
|
||||||
|
|
||||||
# 验证用户名格式（字母、数字、下划线）
|
|
||||||
static func is_valid_username(username: String) -> bool:
|
|
||||||
if username.is_empty() or username.length() > 50:
|
|
||||||
return false
|
|
||||||
|
|
||||||
var regex = RegEx.new()
|
|
||||||
regex.compile("^[a-zA-Z0-9_]+$")
|
|
||||||
return regex.search(username) != null
|
|
||||||
|
|
||||||
# 验证密码强度
|
|
||||||
static func validate_password_strength(password: String) -> Dictionary:
|
|
||||||
var result = {"valid": false, "message": "", "strength": 0}
|
|
||||||
|
|
||||||
if password.length() < 8:
|
|
||||||
result.message = "密码长度至少8位"
|
|
||||||
return result
|
|
||||||
|
|
||||||
if password.length() > 128:
|
|
||||||
result.message = "密码长度不能超过128位"
|
|
||||||
return result
|
|
||||||
|
|
||||||
var has_letter = false
|
|
||||||
var has_digit = false
|
|
||||||
var has_special = false
|
|
||||||
|
|
||||||
for i in range(password.length()):
|
|
||||||
var character = password[i]
|
|
||||||
if character >= 'a' and character <= 'z' or character >= 'A' and character <= 'Z':
|
|
||||||
has_letter = true
|
|
||||||
elif character >= '0' and character <= '9':
|
|
||||||
has_digit = true
|
|
||||||
elif character in "!@#$%^&*()_+-=[]{}|;:,.<>?":
|
|
||||||
has_special = true
|
|
||||||
|
|
||||||
var strength = 0
|
|
||||||
if has_letter:
|
|
||||||
strength += 1
|
|
||||||
if has_digit:
|
|
||||||
strength += 1
|
|
||||||
if has_special:
|
|
||||||
strength += 1
|
|
||||||
if password.length() >= 12:
|
|
||||||
strength += 1
|
|
||||||
|
|
||||||
result.strength = strength
|
|
||||||
|
|
||||||
if not (has_letter and has_digit):
|
|
||||||
result.message = "密码必须包含字母和数字"
|
|
||||||
return result
|
|
||||||
|
|
||||||
result.valid = true
|
|
||||||
result.message = "密码强度: " + ["弱", "中", "强", "很强"][min(strength - 1, 3)]
|
|
||||||
return result
|
|
||||||
|
|
||||||
# 截断字符串
|
|
||||||
static func truncate(text: String, max_length: int, suffix: String = "...") -> String:
|
|
||||||
if text.length() <= max_length:
|
|
||||||
return text
|
|
||||||
return text.substr(0, max_length - suffix.length()) + suffix
|
|
||||||
|
|
||||||
# 首字母大写
|
|
||||||
static func capitalize_first(text: String) -> String:
|
|
||||||
if text.is_empty():
|
|
||||||
return text
|
|
||||||
return text[0].to_upper() + text.substr(1)
|
|
||||||
|
|
||||||
# 转换为标题格式（每个单词首字母大写）
|
|
||||||
static func to_title_case(text: String) -> String:
|
|
||||||
var words = text.split(" ")
|
|
||||||
var result = []
|
|
||||||
for word in words:
|
|
||||||
if not word.is_empty():
|
|
||||||
result.append(capitalize_first(word.to_lower()))
|
|
||||||
return " ".join(result)
|
|
||||||
|
|
||||||
# 移除HTML标签
|
|
||||||
static func strip_html_tags(html: String) -> String:
|
|
||||||
var regex = RegEx.new()
|
|
||||||
regex.compile("<[^>]*>")
|
|
||||||
return regex.sub(html, "", true)
|
|
||||||
|
|
||||||
# 格式化文件大小
|
|
||||||
static func format_file_size(bytes: int) -> String:
|
|
||||||
var units = ["B", "KB", "MB", "GB", "TB"]
|
|
||||||
var size = float(bytes)
|
|
||||||
var unit_index = 0
|
|
||||||
|
|
||||||
while size >= 1024.0 and unit_index < units.size() - 1:
|
|
||||||
size /= 1024.0
|
|
||||||
unit_index += 1
|
|
||||||
|
|
||||||
if unit_index == 0:
|
|
||||||
return str(int(size)) + " " + units[unit_index]
|
|
||||||
else:
|
|
||||||
return "%.1f %s" % [size, units[unit_index]]
|
|
||||||
|
|
||||||
# 将UTC时间字符串转换为本地时间显示
|
|
||||||
static func format_utc_to_local_time(utc_time_str: String) -> String:
|
|
||||||
# 解析UTC时间字符串 (格式: 2025-12-25T11:23:52.175Z)
|
|
||||||
var regex = RegEx.new()
|
|
||||||
regex.compile("(\\d{4})-(\\d{2})-(\\d{2})T(\\d{2}):(\\d{2}):(\\d{2})")
|
|
||||||
var result = regex.search(utc_time_str)
|
|
||||||
|
|
||||||
if result == null:
|
|
||||||
return utc_time_str # 如果解析失败，返回原字符串
|
|
||||||
|
|
||||||
# 提取时间组件
|
|
||||||
var year = int(result.get_string(1))
|
|
||||||
var month = int(result.get_string(2))
|
|
||||||
var day = int(result.get_string(3))
|
|
||||||
var hour = int(result.get_string(4))
|
|
||||||
var minute = int(result.get_string(5))
|
|
||||||
var second = int(result.get_string(6))
|
|
||||||
|
|
||||||
# 创建UTC时间字典
|
|
||||||
var utc_dict = {
|
|
||||||
"year": year,
|
|
||||||
"month": month,
|
|
||||||
"day": day,
|
|
||||||
"hour": hour,
|
|
||||||
"minute": minute,
|
|
||||||
"second": second
|
|
||||||
}
|
|
||||||
|
|
||||||
# 转换为Unix时间戳（UTC）
|
|
||||||
var utc_timestamp = Time.get_unix_time_from_datetime_dict(utc_dict)
|
|
||||||
|
|
||||||
# 获取本地时间（Godot会自动处理时区转换）
|
|
||||||
var local_dict = Time.get_datetime_dict_from_unix_time(utc_timestamp)
|
|
||||||
|
|
||||||
# 格式化为易读的本地时间
|
|
||||||
return "%04d年%02d月%02d日 %02d:%02d:%02d" % [
|
|
||||||
local_dict.year,
|
|
||||||
local_dict.month,
|
|
||||||
local_dict.day,
|
|
||||||
local_dict.hour,
|
|
||||||
local_dict.minute,
|
|
||||||
local_dict.second
|
|
||||||
]
|
|
||||||
|
|
||||||
# 获取相对时间描述（多少分钟后）
|
|
||||||
static func get_relative_time_until(utc_time_str: String) -> String:
|
|
||||||
# 解析UTC时间字符串
|
|
||||||
var regex = RegEx.new()
|
|
||||||
regex.compile("(\\d{4})-(\\d{2})-(\\d{2})T(\\d{2}):(\\d{2}):(\\d{2})")
|
|
||||||
var result = regex.search(utc_time_str)
|
|
||||||
|
|
||||||
if result == null:
|
|
||||||
return "时间格式错误"
|
|
||||||
|
|
||||||
# 提取时间组件
|
|
||||||
var year = int(result.get_string(1))
|
|
||||||
var month = int(result.get_string(2))
|
|
||||||
var day = int(result.get_string(3))
|
|
||||||
var hour = int(result.get_string(4))
|
|
||||||
var minute = int(result.get_string(5))
|
|
||||||
var second = int(result.get_string(6))
|
|
||||||
|
|
||||||
# 创建UTC时间字典
|
|
||||||
var utc_dict = {
|
|
||||||
"year": year,
|
|
||||||
"month": month,
|
|
||||||
"day": day,
|
|
||||||
"hour": hour,
|
|
||||||
"minute": minute,
|
|
||||||
"second": second
|
|
||||||
}
|
|
||||||
|
|
||||||
# 转换为Unix时间戳
|
|
||||||
var target_timestamp = Time.get_unix_time_from_datetime_dict(utc_dict)
|
|
||||||
var current_timestamp = Time.get_unix_time_from_system()
|
|
||||||
|
|
||||||
# 计算时间差（秒）
|
|
||||||
var diff_seconds = target_timestamp - current_timestamp
|
|
||||||
|
|
||||||
if diff_seconds <= 0:
|
|
||||||
return "现在可以重试"
|
|
||||||
elif diff_seconds < 60:
|
|
||||||
return "%d秒后" % diff_seconds
|
|
||||||
elif diff_seconds < 3600:
|
|
||||||
var minutes = int(diff_seconds / 60)
|
|
||||||
return "%d分钟后" % minutes
|
|
||||||
else:
|
|
||||||
var hours = int(diff_seconds / 3600)
|
|
||||||
var minutes = int((diff_seconds % 3600) / 60)
|
|
||||||
if minutes > 0:
|
|
||||||
return "%d小时%d分钟后" % [hours, minutes]
|
|
||||||
else:
|
|
||||||
return "%d小时后" % hours
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
uid://bu8onmk6q8wic
|
|
||||||
0
assets/.gitkeep
Normal file
0
assets/.gitkeep
Normal file
@@ -1 +0,0 @@
|
|||||||
# 保持目录结构 - 音乐资源目录
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
# 保持目录结构 - 音效资源目录
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
# 保持目录结构 - 语音资源目录
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
# 保持目录结构 - 音乐资源目录
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
# 保持目录结构 - 音效资源目录
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
# 保持目录结构 - 语音资源目录
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
# 保持目录结构 - 字体资源目录
|
|
||||||
Binary file not shown.
@@ -1,41 +0,0 @@
|
|||||||
[remap]
|
|
||||||
|
|
||||||
importer="font_data_dynamic"
|
|
||||||
type="FontFile"
|
|
||||||
uid="uid://ce7ujbeobblyr"
|
|
||||||
path="res://.godot/imported/msyh.ttc-1f7944f6d1cff8092894a3525ec5156c.fontdata"
|
|
||||||
|
|
||||||
[deps]
|
|
||||||
|
|
||||||
source_file="res://assets/fonts/msyh.ttc"
|
|
||||||
dest_files=["res://.godot/imported/msyh.ttc-1f7944f6d1cff8092894a3525ec5156c.fontdata"]
|
|
||||||
|
|
||||||
[params]
|
|
||||||
|
|
||||||
Rendering=null
|
|
||||||
antialiasing=1
|
|
||||||
generate_mipmaps=false
|
|
||||||
disable_embedded_bitmaps=true
|
|
||||||
multichannel_signed_distance_field=false
|
|
||||||
msdf_pixel_range=8
|
|
||||||
msdf_size=48
|
|
||||||
allow_system_fallback=true
|
|
||||||
force_autohinter=false
|
|
||||||
modulate_color_glyphs=false
|
|
||||||
hinting=1
|
|
||||||
subpixel_positioning=4
|
|
||||||
keep_rounding_remainders=true
|
|
||||||
oversampling=0.0
|
|
||||||
Fallbacks=null
|
|
||||||
fallbacks=[]
|
|
||||||
Compress=null
|
|
||||||
compress=false
|
|
||||||
preload=[{
|
|
||||||
"chars": "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz!@#$%^&*()_+-=[]{}|;':\",./<>?`~一二三四五六七八九十百千万亿用户名密码登录注册验证码邮箱小镇鲸鱼欢迎来到开始你的之旅请输入不能为空获取发送忘记返回居民身份确认再次已被使用换个等待分钟后试稍后正在创建账户测试模式生成查看控制台网络连接失败系统维护中升级稍后再试频繁联系管理员禁用审核先邮箱后使用成功进入镇错误或过期未找到存在",
|
|
||||||
"glyphs": [],
|
|
||||||
"name": "Web预加载",
|
|
||||||
"size": Vector2i(16, 0)
|
|
||||||
}]
|
|
||||||
language_support={}
|
|
||||||
script_support={}
|
|
||||||
opentype_features={}
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 13 KiB |
@@ -1,40 +0,0 @@
|
|||||||
[remap]
|
|
||||||
|
|
||||||
importer="texture"
|
|
||||||
type="CompressedTexture2D"
|
|
||||||
uid="uid://bwy5r7soxi76a"
|
|
||||||
path="res://.godot/imported/icon144.png-ae9d1f30a88beaab449c2cad89283dd3.ctex"
|
|
||||||
metadata={
|
|
||||||
"vram_texture": false
|
|
||||||
}
|
|
||||||
|
|
||||||
[deps]
|
|
||||||
|
|
||||||
source_file="res://assets/icon/icon144.png"
|
|
||||||
dest_files=["res://.godot/imported/icon144.png-ae9d1f30a88beaab449c2cad89283dd3.ctex"]
|
|
||||||
|
|
||||||
[params]
|
|
||||||
|
|
||||||
compress/mode=0
|
|
||||||
compress/high_quality=false
|
|
||||||
compress/lossy_quality=0.7
|
|
||||||
compress/uastc_level=0
|
|
||||||
compress/rdo_quality_loss=0.0
|
|
||||||
compress/hdr_compression=1
|
|
||||||
compress/normal_map=0
|
|
||||||
compress/channel_pack=0
|
|
||||||
mipmaps/generate=false
|
|
||||||
mipmaps/limit=-1
|
|
||||||
roughness/mode=0
|
|
||||||
roughness/src_normal=""
|
|
||||||
process/channel_remap/red=0
|
|
||||||
process/channel_remap/green=1
|
|
||||||
process/channel_remap/blue=2
|
|
||||||
process/channel_remap/alpha=3
|
|
||||||
process/fix_alpha_border=true
|
|
||||||
process/premult_alpha=false
|
|
||||||
process/normal_map_invert_y=false
|
|
||||||
process/hdr_as_srgb=false
|
|
||||||
process/hdr_clamp_exposure=false
|
|
||||||
process/size_limit=0
|
|
||||||
detect_3d/compress_to=1
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 644 B |
Binary file not shown.
|
Before Width: | Height: | Size: 18 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 1.7 KiB |
@@ -1,40 +0,0 @@
|
|||||||
[remap]
|
|
||||||
|
|
||||||
importer="texture"
|
|
||||||
type="CompressedTexture2D"
|
|
||||||
uid="uid://dt24j6p0cijqo"
|
|
||||||
path="res://.godot/imported/icon32.png-9a0aceb23d191139c34540a188bf8c91.ctex"
|
|
||||||
metadata={
|
|
||||||
"vram_texture": false
|
|
||||||
}
|
|
||||||
|
|
||||||
[deps]
|
|
||||||
|
|
||||||
source_file="res://assets/icon/icon32.png"
|
|
||||||
dest_files=["res://.godot/imported/icon32.png-9a0aceb23d191139c34540a188bf8c91.ctex"]
|
|
||||||
|
|
||||||
[params]
|
|
||||||
|
|
||||||
compress/mode=0
|
|
||||||
compress/high_quality=false
|
|
||||||
compress/lossy_quality=0.7
|
|
||||||
compress/uastc_level=0
|
|
||||||
compress/rdo_quality_loss=0.0
|
|
||||||
compress/hdr_compression=1
|
|
||||||
compress/normal_map=0
|
|
||||||
compress/channel_pack=0
|
|
||||||
mipmaps/generate=false
|
|
||||||
mipmaps/limit=-1
|
|
||||||
roughness/mode=0
|
|
||||||
roughness/src_normal=""
|
|
||||||
process/channel_remap/red=0
|
|
||||||
process/channel_remap/green=1
|
|
||||||
process/channel_remap/blue=2
|
|
||||||
process/channel_remap/alpha=3
|
|
||||||
process/fix_alpha_border=true
|
|
||||||
process/premult_alpha=false
|
|
||||||
process/normal_map_invert_y=false
|
|
||||||
process/hdr_as_srgb=false
|
|
||||||
process/hdr_clamp_exposure=false
|
|
||||||
process/size_limit=0
|
|
||||||
detect_3d/compress_to=1
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 78 KiB |
@@ -1,40 +0,0 @@
|
|||||||
[remap]
|
|
||||||
|
|
||||||
importer="texture"
|
|
||||||
type="CompressedTexture2D"
|
|
||||||
uid="uid://dt817lem3dwee"
|
|
||||||
path="res://.godot/imported/icon512.png-1c1c4b424489de87a542c89bec6eb15b.ctex"
|
|
||||||
metadata={
|
|
||||||
"vram_texture": false
|
|
||||||
}
|
|
||||||
|
|
||||||
[deps]
|
|
||||||
|
|
||||||
source_file="res://assets/icon/icon512.png"
|
|
||||||
dest_files=["res://.godot/imported/icon512.png-1c1c4b424489de87a542c89bec6eb15b.ctex"]
|
|
||||||
|
|
||||||
[params]
|
|
||||||
|
|
||||||
compress/mode=0
|
|
||||||
compress/high_quality=false
|
|
||||||
compress/lossy_quality=0.7
|
|
||||||
compress/uastc_level=0
|
|
||||||
compress/rdo_quality_loss=0.0
|
|
||||||
compress/hdr_compression=1
|
|
||||||
compress/normal_map=0
|
|
||||||
compress/channel_pack=0
|
|
||||||
mipmaps/generate=false
|
|
||||||
mipmaps/limit=-1
|
|
||||||
roughness/mode=0
|
|
||||||
roughness/src_normal=""
|
|
||||||
process/channel_remap/red=0
|
|
||||||
process/channel_remap/green=1
|
|
||||||
process/channel_remap/blue=2
|
|
||||||
process/channel_remap/alpha=3
|
|
||||||
process/fix_alpha_border=true
|
|
||||||
process/premult_alpha=false
|
|
||||||
process/normal_map_invert_y=false
|
|
||||||
process/hdr_as_srgb=false
|
|
||||||
process/hdr_clamp_exposure=false
|
|
||||||
process/size_limit=0
|
|
||||||
detect_3d/compress_to=1
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 4.5 KiB |
@@ -1,40 +0,0 @@
|
|||||||
[remap]
|
|
||||||
|
|
||||||
importer="texture"
|
|
||||||
type="CompressedTexture2D"
|
|
||||||
uid="uid://ci42rd5qe6icl"
|
|
||||||
path="res://.godot/imported/icon64.png-da8a1a20e3bf4dcf06c8ff6c558caaff.ctex"
|
|
||||||
metadata={
|
|
||||||
"vram_texture": false
|
|
||||||
}
|
|
||||||
|
|
||||||
[deps]
|
|
||||||
|
|
||||||
source_file="res://assets/icon/icon64.png"
|
|
||||||
dest_files=["res://.godot/imported/icon64.png-da8a1a20e3bf4dcf06c8ff6c558caaff.ctex"]
|
|
||||||
|
|
||||||
[params]
|
|
||||||
|
|
||||||
compress/mode=0
|
|
||||||
compress/high_quality=false
|
|
||||||
compress/lossy_quality=0.7
|
|
||||||
compress/uastc_level=0
|
|
||||||
compress/rdo_quality_loss=0.0
|
|
||||||
compress/hdr_compression=1
|
|
||||||
compress/normal_map=0
|
|
||||||
compress/channel_pack=0
|
|
||||||
mipmaps/generate=false
|
|
||||||
mipmaps/limit=-1
|
|
||||||
roughness/mode=0
|
|
||||||
roughness/src_normal=""
|
|
||||||
process/channel_remap/red=0
|
|
||||||
process/channel_remap/green=1
|
|
||||||
process/channel_remap/blue=2
|
|
||||||
process/channel_remap/alpha=3
|
|
||||||
process/fix_alpha_border=true
|
|
||||||
process/premult_alpha=false
|
|
||||||
process/normal_map_invert_y=false
|
|
||||||
process/hdr_as_srgb=false
|
|
||||||
process/hdr_clamp_exposure=false
|
|
||||||
process/size_limit=0
|
|
||||||
detect_3d/compress_to=1
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 150 KiB |
@@ -1,40 +0,0 @@
|
|||||||
[remap]
|
|
||||||
|
|
||||||
importer="texture"
|
|
||||||
type="CompressedTexture2D"
|
|
||||||
uid="uid://cnw6e3wmy0ea4"
|
|
||||||
path="res://.godot/imported/image(1).png-c89cc92103e50aaba40bf38c797be77f.ctex"
|
|
||||||
metadata={
|
|
||||||
"vram_texture": false
|
|
||||||
}
|
|
||||||
|
|
||||||
[deps]
|
|
||||||
|
|
||||||
source_file="res://assets/icon/image(1).png"
|
|
||||||
dest_files=["res://.godot/imported/image(1).png-c89cc92103e50aaba40bf38c797be77f.ctex"]
|
|
||||||
|
|
||||||
[params]
|
|
||||||
|
|
||||||
compress/mode=0
|
|
||||||
compress/high_quality=false
|
|
||||||
compress/lossy_quality=0.7
|
|
||||||
compress/uastc_level=0
|
|
||||||
compress/rdo_quality_loss=0.0
|
|
||||||
compress/hdr_compression=1
|
|
||||||
compress/normal_map=0
|
|
||||||
compress/channel_pack=0
|
|
||||||
mipmaps/generate=false
|
|
||||||
mipmaps/limit=-1
|
|
||||||
roughness/mode=0
|
|
||||||
roughness/src_normal=""
|
|
||||||
process/channel_remap/red=0
|
|
||||||
process/channel_remap/green=1
|
|
||||||
process/channel_remap/blue=2
|
|
||||||
process/channel_remap/alpha=3
|
|
||||||
process/fix_alpha_border=true
|
|
||||||
process/premult_alpha=false
|
|
||||||
process/normal_map_invert_y=false
|
|
||||||
process/hdr_as_srgb=false
|
|
||||||
process/hdr_clamp_exposure=false
|
|
||||||
process/size_limit=0
|
|
||||||
detect_3d/compress_to=1
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 91 KiB |
@@ -1,40 +0,0 @@
|
|||||||
[remap]
|
|
||||||
|
|
||||||
importer="texture"
|
|
||||||
type="CompressedTexture2D"
|
|
||||||
uid="uid://c7v22i1hgo1x6"
|
|
||||||
path="res://.godot/imported/image.png-3f16548595ba9fb08c5e50ef3251d148.ctex"
|
|
||||||
metadata={
|
|
||||||
"vram_texture": false
|
|
||||||
}
|
|
||||||
|
|
||||||
[deps]
|
|
||||||
|
|
||||||
source_file="res://assets/icon/image.png"
|
|
||||||
dest_files=["res://.godot/imported/image.png-3f16548595ba9fb08c5e50ef3251d148.ctex"]
|
|
||||||
|
|
||||||
[params]
|
|
||||||
|
|
||||||
compress/mode=0
|
|
||||||
compress/high_quality=false
|
|
||||||
compress/lossy_quality=0.7
|
|
||||||
compress/uastc_level=0
|
|
||||||
compress/rdo_quality_loss=0.0
|
|
||||||
compress/hdr_compression=1
|
|
||||||
compress/normal_map=0
|
|
||||||
compress/channel_pack=0
|
|
||||||
mipmaps/generate=false
|
|
||||||
mipmaps/limit=-1
|
|
||||||
roughness/mode=0
|
|
||||||
roughness/src_normal=""
|
|
||||||
process/channel_remap/red=0
|
|
||||||
process/channel_remap/green=1
|
|
||||||
process/channel_remap/blue=2
|
|
||||||
process/channel_remap/alpha=3
|
|
||||||
process/fix_alpha_border=true
|
|
||||||
process/premult_alpha=false
|
|
||||||
process/normal_map_invert_y=false
|
|
||||||
process/hdr_as_srgb=false
|
|
||||||
process/hdr_clamp_exposure=false
|
|
||||||
process/size_limit=0
|
|
||||||
detect_3d/compress_to=1
|
|
||||||
BIN
assets/login/enter.png
Normal file
BIN
assets/login/enter.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 183 KiB |
@@ -2,16 +2,16 @@
|
|||||||
|
|
||||||
importer="texture"
|
importer="texture"
|
||||||
type="CompressedTexture2D"
|
type="CompressedTexture2D"
|
||||||
uid="uid://cj0tify76qrst"
|
uid="uid://cswuqnhiiypb2"
|
||||||
path="res://.godot/imported/index.png-d064c09a6315f5da70b1876a63391d16.ctex"
|
path="res://.godot/imported/enter.png-ed3d67e95e66053ad0fb61054985bfb8.ctex"
|
||||||
metadata={
|
metadata={
|
||||||
"vram_texture": false
|
"vram_texture": false
|
||||||
}
|
}
|
||||||
|
|
||||||
[deps]
|
[deps]
|
||||||
|
|
||||||
source_file="res://web_assets/index.png"
|
source_file="res://assets/login/enter.png"
|
||||||
dest_files=["res://.godot/imported/index.png-d064c09a6315f5da70b1876a63391d16.ctex"]
|
dest_files=["res://.godot/imported/enter.png-ed3d67e95e66053ad0fb61054985bfb8.ctex"]
|
||||||
|
|
||||||
[params]
|
[params]
|
||||||
|
|
||||||
BIN
assets/login/login-bg.png
Normal file
BIN
assets/login/login-bg.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 840 KiB |
@@ -2,16 +2,16 @@
|
|||||||
|
|
||||||
importer="texture"
|
importer="texture"
|
||||||
type="CompressedTexture2D"
|
type="CompressedTexture2D"
|
||||||
uid="uid://bqg5e8qn1j74u"
|
uid="uid://byw73r2dt6xb8"
|
||||||
path="res://.godot/imported/icon16.png-3099ad8a609f90c382508b9c073ffd76.ctex"
|
path="res://.godot/imported/login-bg.png-3f4c0c8160ab08ab0791dc1de267dd7a.ctex"
|
||||||
metadata={
|
metadata={
|
||||||
"vram_texture": false
|
"vram_texture": false
|
||||||
}
|
}
|
||||||
|
|
||||||
[deps]
|
[deps]
|
||||||
|
|
||||||
source_file="res://assets/icon/icon16.png"
|
source_file="res://assets/login/login-bg.png"
|
||||||
dest_files=["res://.godot/imported/icon16.png-3099ad8a609f90c382508b9c073ffd76.ctex"]
|
dest_files=["res://.godot/imported/login-bg.png-3f4c0c8160ab08ab0791dc1de267dd7a.ctex"]
|
||||||
|
|
||||||
[params]
|
[params]
|
||||||
|
|
||||||
BIN
assets/login/whaletown.png
Normal file
BIN
assets/login/whaletown.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 218 KiB |
@@ -2,16 +2,16 @@
|
|||||||
|
|
||||||
importer="texture"
|
importer="texture"
|
||||||
type="CompressedTexture2D"
|
type="CompressedTexture2D"
|
||||||
uid="uid://drpllpsjdiaex"
|
uid="uid://bqvel7n6dfo1d"
|
||||||
path="res://.godot/imported/icon180.png-20a9d7b98bfb315dd470e3635f315a17.ctex"
|
path="res://.godot/imported/whaletown.png-c44c9408e8b817d0db57fd8eec9de194.ctex"
|
||||||
metadata={
|
metadata={
|
||||||
"vram_texture": false
|
"vram_texture": false
|
||||||
}
|
}
|
||||||
|
|
||||||
[deps]
|
[deps]
|
||||||
|
|
||||||
source_file="res://assets/icon/icon180.png"
|
source_file="res://assets/login/whaletown.png"
|
||||||
dest_files=["res://.godot/imported/icon180.png-20a9d7b98bfb315dd470e3635f315a17.ctex"]
|
dest_files=["res://.godot/imported/whaletown.png-c44c9408e8b817d0db57fd8eec9de194.ctex"]
|
||||||
|
|
||||||
[params]
|
[params]
|
||||||
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
# 保持目录结构 - 材质资源目录
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
# 保持目录结构 - 着色器资源目录
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
# 保持目录结构 - 角色精灵资源目录
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
# 保持目录结构 - 特效精灵资源目录
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
# 保持目录结构 - 环境精灵资源目录
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
# 保持目录结构 - 材质资源目录
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
# 保持目录结构 - 着色器资源目录
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
# 保持目录结构 - 角色精灵资源目录
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
# 保持目录结构 - 特效精灵资源目录
|
|
||||||
@@ -1 +0,0 @@
|
|||||||
# 保持目录结构 - 环境精灵资源目录
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 5.7 MiB |
@@ -1,40 +0,0 @@
|
|||||||
[remap]
|
|
||||||
|
|
||||||
importer="texture"
|
|
||||||
type="CompressedTexture2D"
|
|
||||||
uid="uid://bx17oy8lvaca4"
|
|
||||||
path="res://.godot/imported/bg_auth_scene.png-818065fcc20397e855c75507c1313623.ctex"
|
|
||||||
metadata={
|
|
||||||
"vram_texture": false
|
|
||||||
}
|
|
||||||
|
|
||||||
[deps]
|
|
||||||
|
|
||||||
source_file="res://assets/ui/auth/bg_auth_scene.png"
|
|
||||||
dest_files=["res://.godot/imported/bg_auth_scene.png-818065fcc20397e855c75507c1313623.ctex"]
|
|
||||||
|
|
||||||
[params]
|
|
||||||
|
|
||||||
compress/mode=0
|
|
||||||
compress/high_quality=false
|
|
||||||
compress/lossy_quality=0.7
|
|
||||||
compress/uastc_level=0
|
|
||||||
compress/rdo_quality_loss=0.0
|
|
||||||
compress/hdr_compression=1
|
|
||||||
compress/normal_map=0
|
|
||||||
compress/channel_pack=0
|
|
||||||
mipmaps/generate=false
|
|
||||||
mipmaps/limit=-1
|
|
||||||
roughness/mode=0
|
|
||||||
roughness/src_normal=""
|
|
||||||
process/channel_remap/red=0
|
|
||||||
process/channel_remap/green=1
|
|
||||||
process/channel_remap/blue=2
|
|
||||||
process/channel_remap/alpha=3
|
|
||||||
process/fix_alpha_border=true
|
|
||||||
process/premult_alpha=false
|
|
||||||
process/normal_map_invert_y=false
|
|
||||||
process/hdr_as_srgb=false
|
|
||||||
process/hdr_clamp_exposure=false
|
|
||||||
process/size_limit=0
|
|
||||||
detect_3d/compress_to=1
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 587 KiB |
@@ -1,40 +0,0 @@
|
|||||||
[remap]
|
|
||||||
|
|
||||||
importer="texture"
|
|
||||||
type="CompressedTexture2D"
|
|
||||||
uid="uid://de4q4s1gxivtf"
|
|
||||||
path="res://.godot/imported/login_frame_smart_transparent.png-e5d0fd05b4713ddd3beae8223f2abb80.ctex"
|
|
||||||
metadata={
|
|
||||||
"vram_texture": false
|
|
||||||
}
|
|
||||||
|
|
||||||
[deps]
|
|
||||||
|
|
||||||
source_file="res://assets/ui/auth/login_frame_smart_transparent.png"
|
|
||||||
dest_files=["res://.godot/imported/login_frame_smart_transparent.png-e5d0fd05b4713ddd3beae8223f2abb80.ctex"]
|
|
||||||
|
|
||||||
[params]
|
|
||||||
|
|
||||||
compress/mode=0
|
|
||||||
compress/high_quality=false
|
|
||||||
compress/lossy_quality=0.7
|
|
||||||
compress/uastc_level=0
|
|
||||||
compress/rdo_quality_loss=0.0
|
|
||||||
compress/hdr_compression=1
|
|
||||||
compress/normal_map=0
|
|
||||||
compress/channel_pack=0
|
|
||||||
mipmaps/generate=false
|
|
||||||
mipmaps/limit=-1
|
|
||||||
roughness/mode=0
|
|
||||||
roughness/src_normal=""
|
|
||||||
process/channel_remap/red=0
|
|
||||||
process/channel_remap/green=1
|
|
||||||
process/channel_remap/blue=2
|
|
||||||
process/channel_remap/alpha=3
|
|
||||||
process/fix_alpha_border=true
|
|
||||||
process/premult_alpha=false
|
|
||||||
process/normal_map_invert_y=false
|
|
||||||
process/hdr_as_srgb=false
|
|
||||||
process/hdr_clamp_exposure=false
|
|
||||||
process/size_limit=0
|
|
||||||
detect_3d/compress_to=1
|
|
||||||
@@ -1,7 +0,0 @@
|
|||||||
[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"]
|
|
||||||
|
|
||||||
[resource]
|
|
||||||
resource_local_to_scene = true
|
|
||||||
default_font = ExtResource("1_ftb5w")
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 6.7 KiB |
@@ -1,40 +0,0 @@
|
|||||||
[remap]
|
|
||||||
|
|
||||||
importer="texture"
|
|
||||||
type="CompressedTexture2D"
|
|
||||||
uid="uid://gr7vud1lee4m"
|
|
||||||
path="res://.godot/imported/datawhale_logo.png-ddb5e2c04419eb84cfa8605bcbf64fbd.ctex"
|
|
||||||
metadata={
|
|
||||||
"vram_texture": false
|
|
||||||
}
|
|
||||||
|
|
||||||
[deps]
|
|
||||||
|
|
||||||
source_file="res://assets/ui/datawhale_logo.png"
|
|
||||||
dest_files=["res://.godot/imported/datawhale_logo.png-ddb5e2c04419eb84cfa8605bcbf64fbd.ctex"]
|
|
||||||
|
|
||||||
[params]
|
|
||||||
|
|
||||||
compress/mode=0
|
|
||||||
compress/high_quality=false
|
|
||||||
compress/lossy_quality=0.7
|
|
||||||
compress/uastc_level=0
|
|
||||||
compress/rdo_quality_loss=0.0
|
|
||||||
compress/hdr_compression=1
|
|
||||||
compress/normal_map=0
|
|
||||||
compress/channel_pack=0
|
|
||||||
mipmaps/generate=false
|
|
||||||
mipmaps/limit=-1
|
|
||||||
roughness/mode=0
|
|
||||||
roughness/src_normal=""
|
|
||||||
process/channel_remap/red=0
|
|
||||||
process/channel_remap/green=1
|
|
||||||
process/channel_remap/blue=2
|
|
||||||
process/channel_remap/alpha=3
|
|
||||||
process/fix_alpha_border=true
|
|
||||||
process/premult_alpha=false
|
|
||||||
process/normal_map_invert_y=false
|
|
||||||
process/hdr_as_srgb=false
|
|
||||||
process/hdr_clamp_exposure=false
|
|
||||||
process/size_limit=0
|
|
||||||
detect_3d/compress_to=1
|
|
||||||
96
claude.md
96
claude.md
@@ -1,96 +0,0 @@
|
|||||||
# 🎯 CLAUDE.md - WhaleTown Project Instructions
|
|
||||||
|
|
||||||
## 1. Project Vision & Context
|
|
||||||
- **Project**: "WhaleTown" - A 2D top-down pixel art RPG.
|
|
||||||
- **Engine**: Godot 4.2+ (Strictly NO Godot 3.x syntax).
|
|
||||||
- **Architecture**: Strictly layered: `_Core` (Framework), `Scenes` (Gameplay), `UI` (Interface).
|
|
||||||
- **Core Principle**: "Signal Up, Call Down". High decoupling via `EventSystem`.
|
|
||||||
|
|
||||||
## 2. 🛠 Command Reference & Setup
|
|
||||||
- **Input Map (Required Configuration)**:
|
|
||||||
- `move_left`, `move_right`, `move_up`, `move_down` (WASD / Arrows)
|
|
||||||
- `interact` (E Key / Space)
|
|
||||||
- `pause` (ESC)
|
|
||||||
- **Run Game**: `godot --path .`
|
|
||||||
- **Run Tests (GUT)**: `godot --headless -s addons/gut/gut_cmdline.gd -gdir=res://tests/ -ginclude_subdirs`
|
|
||||||
- **Init Structure**: `mkdir -p _Core/managers _Core/systems Scenes/Maps Scenes/Entities Scenes/Components UI/Windows UI/HUD Assets/Sprites tests/unit tests/integration`
|
|
||||||
|
|
||||||
## 3. 📂 File Path Rules (STRICT LOWERCASE)
|
|
||||||
*Claude: Root folders MUST be lowercase. Scripts and Scenes MUST stay together.*
|
|
||||||
- **Core Managers**: `_Core/managers/[Name].gd`
|
|
||||||
- **Core Systems**: `_Core/systems/[Name].gd`
|
|
||||||
- **Entities**: `Scenes/Entities/[EntityName]/[EntityName].tscn` (Script `.gd` in same folder).
|
|
||||||
- **Maps**: `Scenes/Maps/[map_name].tscn`
|
|
||||||
- **Components**: `Scenes/Components/[ComponentName].gd` (Reusable logic nodes).
|
|
||||||
- **UI Windows**: `UI/Windows/[WindowName].tscn`
|
|
||||||
- **Tests**: `tests/[unit|integration]/test_[name].gd` (Folder is lowercase `tests`).
|
|
||||||
|
|
||||||
## 4. 📋 Coding Standards (The Law)
|
|
||||||
- **Type Safety**: ALWAYS use strict static typing: `var speed: float = 100.0`, `func _ready() -> void`.
|
|
||||||
- **Naming Conventions**:
|
|
||||||
- `class_name PascalCase` at the top of every script.
|
|
||||||
- Variables/Functions: `snake_case`. Constants: `SCREAMING_SNAKE_CASE`.
|
|
||||||
- Private members: Prefix with underscore `_` (e.g., `var _health: int`).
|
|
||||||
- **Node Access**: Use `%UniqueName` for UI and internal scene components.
|
|
||||||
- **Signals**: Use "Signal Up, Call Down". Parent calls child methods; Child emits signals.
|
|
||||||
- **Forbidden Patterns**:
|
|
||||||
- ❌ NO `yield()` -> Use `await`.
|
|
||||||
- ❌ NO `get_node()` in `_process` -> Cache with `@onready`.
|
|
||||||
- ❌ NO Linear Filter -> All Sprite2D/TileMap resources MUST use **Nearest** filter.
|
|
||||||
|
|
||||||
## 5. 🏛 Architecture & Communication
|
|
||||||
- **EventSystem**: Use `_Core/systems/EventSystem.gd` for cross-module messaging.
|
|
||||||
- **Event Registry**: Use `class_name EventNames` in `_Core/EventNames.gd`.
|
|
||||||
```gdscript
|
|
||||||
class_name EventNames
|
|
||||||
const PLAYER_MOVED = "player_moved"
|
|
||||||
const INTERACT_PRESSED = "interact_pressed"
|
|
||||||
const NPC_TALKED = "npc_talked"
|
|
||||||
Singletons: Only GameManager, SceneManager, EventSystem allowed as Autoloads.
|
|
||||||
Decoupling: Low-level entities MUST NOT reference GameManager. Use events.
|
|
||||||
6. 🏗 Implementation Details
|
|
||||||
Player: CharacterBody2D. Must include Camera2D with position_smoothing_enabled = true.
|
|
||||||
NPC/Interactables: Use Area2D named InteractionArea. Trigger via EventSystem.
|
|
||||||
TileMap Layers:
|
|
||||||
Layer 0: Ground (No collision).
|
|
||||||
Layer 1: Obstacles (Physics Layer enabled).
|
|
||||||
Layer 2: Decoration (Y-Sort enabled).
|
|
||||||
Camera: Must auto-calculate limits via TileMap.get_used_rect().
|
|
||||||
7. 🧪 Testing Requirements (MANDATORY)
|
|
||||||
Coverage: Every Manager/System in _Core/ MUST have a GUT test.
|
|
||||||
Naming: Test files must start with test_ and extend GutTest.
|
|
||||||
Example:
|
|
||||||
code
|
|
||||||
Gdscript
|
|
||||||
extends GutTest
|
|
||||||
func test_event_emission():
|
|
||||||
var sender = Node.new()
|
|
||||||
watch_signals(EventSystem)
|
|
||||||
EventSystem.emit_event(EventNames.PLAYER_MOVED, {})
|
|
||||||
assert_signal_emitted(EventSystem, "event_raised")
|
|
||||||
8. 🧘 The Zen of Development
|
|
||||||
Juice or Death: Every interaction (UI popup, NPC talk) MUST have a Tween placeholder.
|
|
||||||
Zero Magic Numbers: All speeds/timers MUST be @export or defined in Config/.
|
|
||||||
Simplicity: If a function does two things, split it.
|
|
||||||
Back of the Fence: Hidden logic (like ResponseHandler.gd) must be as clean as the HUD.
|
|
||||||
9. 📝 Code Template (Entity Pattern)
|
|
||||||
code
|
|
||||||
Gdscript
|
|
||||||
extends CharacterBody2D
|
|
||||||
class_name Player
|
|
||||||
|
|
||||||
# 1. Exports & Constants
|
|
||||||
@export var move_speed: float = 200.0
|
|
||||||
|
|
||||||
# 2. Node References
|
|
||||||
@onready var sprite: Sprite2D = %Sprite2D
|
|
||||||
|
|
||||||
# 3. Lifecycle
|
|
||||||
func _physics_process(delta: float) -> void:
|
|
||||||
_move(delta)
|
|
||||||
|
|
||||||
# 4. Private Methods
|
|
||||||
func _move(_delta: float) -> void:
|
|
||||||
var dir := Input.get_vector("move_left", "move_right", "move_up", "move_down")
|
|
||||||
velocity = dir * move_speed
|
|
||||||
move_and_slide()
|
|
||||||
0
data/.gitkeep
Normal file
0
data/.gitkeep
Normal file
0
docs/.gitkeep
Normal file
0
docs/.gitkeep
Normal file
@@ -1,85 +0,0 @@
|
|||||||
# 📖 项目入门
|
|
||||||
|
|
||||||
> **适用人群**: 新加入项目的开发者
|
|
||||||
> **使用时机**: 项目开始前，环境搭建阶段
|
|
||||||
> **质量等级**: A级 ⭐⭐⭐⭐⭐
|
|
||||||
|
|
||||||
这个目录包含了新人入门必读的基础文档，帮助你快速了解项目并搭建开发环境。
|
|
||||||
|
|
||||||
## 📋 阅读顺序
|
|
||||||
|
|
||||||
### 第一步：了解项目 🏗️
|
|
||||||
**[项目结构说明.md](项目结构说明.md)**
|
|
||||||
- 项目整体架构设计
|
|
||||||
- 目录组织规则和命名规范
|
|
||||||
- 各层级职责说明
|
|
||||||
- 核心组件介绍
|
|
||||||
|
|
||||||
### 第二步：配置环境 ⚙️
|
|
||||||
**[项目设置指南.md](项目设置指南.md)**
|
|
||||||
- Godot编辑器配置
|
|
||||||
- AutoLoad单例设置
|
|
||||||
- 输入映射配置（已预配置）
|
|
||||||
- 开发环境验证
|
|
||||||
|
|
||||||
## ✅ 完成检查
|
|
||||||
|
|
||||||
阅读完本目录的文档后，你应该能够：
|
|
||||||
- [ ] 理解项目的整体架构和设计理念
|
|
||||||
- [ ] 成功配置Godot开发环境
|
|
||||||
- [ ] 了解核心组件的作用和使用方式
|
|
||||||
- [ ] 运行项目并进行基本测试
|
|
||||||
- [ ] 验证所有AutoLoad单例正常工作
|
|
||||||
- [ ] 确认游戏输入控制正常响应
|
|
||||||
|
|
||||||
## 🎮 输入控制说明
|
|
||||||
|
|
||||||
项目已预配置以下输入映射：
|
|
||||||
- **移动控制**: `move_left` (A/←), `move_right` (D/→), `move_up` (W/↑), `move_down` (S/↓)
|
|
||||||
- **交互控制**: `interact` (E键), `jump` (空格键)
|
|
||||||
|
|
||||||
这些输入映射已经在 `project.godot` 中配置完成，无需额外设置。
|
|
||||||
|
|
||||||
## 🚨 常见启动问题
|
|
||||||
|
|
||||||
### 问题1: 游戏无法响应输入
|
|
||||||
**原因**: 项目文件损坏或配置丢失
|
|
||||||
**解决**: 重新克隆项目，确保 `project.godot` 文件完整
|
|
||||||
|
|
||||||
### 问题2: 控制台出现"Invalid action"错误
|
|
||||||
**原因**: 输入映射配置丢失
|
|
||||||
**解决**: 检查 `project.godot` 文件中的 `[input]` 部分是否完整
|
|
||||||
|
|
||||||
### 问题3: AutoLoad单例报错
|
|
||||||
**原因**: AutoLoad配置不正确或文件路径错误
|
|
||||||
**解决**: 参考 [项目设置指南.md](项目设置指南.md) 验证配置
|
|
||||||
|
|
||||||
### 问题4: EventSystem相关错误
|
|
||||||
**原因**: 缺少 `_Core/EventNames.gd` 文件
|
|
||||||
**解决**: 确保项目包含完整的 `_Core` 目录结构
|
|
||||||
|
|
||||||
## 🔗 下一步
|
|
||||||
|
|
||||||
完成项目入门后，建议继续阅读：
|
|
||||||
- [02-开发规范](../02-开发规范/) - 学习编码标准和架构规范
|
|
||||||
- [03-技术实现](../03-技术实现/) - 开始具体功能开发
|
|
||||||
|
|
||||||
## 💡 小贴士
|
|
||||||
|
|
||||||
- **项目已预配置完成** - 输入映射和核心组件都已设置好
|
|
||||||
- 遇到问题时，先查看对应文档的"常见问题"部分
|
|
||||||
- 建议在实际操作中边读边做，加深理解
|
|
||||||
- 可以将重要的配置信息做笔记备用
|
|
||||||
- 完成每个步骤后，建议运行项目验证配置是否正确
|
|
||||||
- 重点关注 `_Core` 目录中的核心组件，它们是项目的基础
|
|
||||||
|
|
||||||
## 🛠️ 核心组件预览
|
|
||||||
|
|
||||||
项目包含以下核心组件，在后续开发中会频繁使用：
|
|
||||||
- **EventSystem** - 全局事件通信系统
|
|
||||||
- **GameManager** - 游戏状态管理
|
|
||||||
- **SceneManager** - 场景切换管理
|
|
||||||
- **NetworkManager** - 网络请求管理
|
|
||||||
- **ProjectPaths** - 统一路径管理
|
|
||||||
|
|
||||||
详细使用方法请参考 [架构与通信规范](../02-开发规范/架构与通信规范.md)。
|
|
||||||
@@ -1,157 +0,0 @@
|
|||||||
# 输入映射配置指南
|
|
||||||
|
|
||||||
本文档说明了WhaleTown项目的输入映射配置要求和设置方法。
|
|
||||||
|
|
||||||
## 🎮 必需的输入映射
|
|
||||||
|
|
||||||
### 基础移动控制
|
|
||||||
- **`move_left`** - 向左移动
|
|
||||||
- 推荐按键：A键、左方向键
|
|
||||||
- **`move_right`** - 向右移动
|
|
||||||
- 推荐按键：D键、右方向键
|
|
||||||
- **`move_up`** - 向上移动
|
|
||||||
- 推荐按键：W键、上方向键
|
|
||||||
- **`move_down`** - 向下移动
|
|
||||||
- 推荐按键：S键、下方向键
|
|
||||||
|
|
||||||
### 交互控制
|
|
||||||
- **`interact`** - 交互动作
|
|
||||||
- 推荐按键：E键、空格键
|
|
||||||
- **`pause`** - 暂停游戏
|
|
||||||
- 推荐按键：ESC键
|
|
||||||
|
|
||||||
## ⚙️ Godot编辑器配置步骤
|
|
||||||
|
|
||||||
### 1. 打开输入映射设置
|
|
||||||
1. 在Godot编辑器中打开 `Project` → `Project Settings`
|
|
||||||
2. 切换到 `Input Map` 标签
|
|
||||||
|
|
||||||
### 2. 添加输入动作
|
|
||||||
对于每个必需的输入动作：
|
|
||||||
|
|
||||||
1. 在 `Action` 输入框中输入动作名称（如 `move_left`）
|
|
||||||
2. 点击 `Add` 按钮
|
|
||||||
3. 点击新添加动作右侧的 `+` 按钮
|
|
||||||
4. 按下对应的按键进行绑定
|
|
||||||
5. 重复步骤3-4添加备用按键
|
|
||||||
|
|
||||||
### 3. 配置示例
|
|
||||||
|
|
||||||
```
|
|
||||||
move_left:
|
|
||||||
- Key: A
|
|
||||||
- Key: Left Arrow
|
|
||||||
|
|
||||||
move_right:
|
|
||||||
- Key: D
|
|
||||||
- Key: Right Arrow
|
|
||||||
|
|
||||||
move_up:
|
|
||||||
- Key: W
|
|
||||||
- Key: Up Arrow
|
|
||||||
|
|
||||||
move_down:
|
|
||||||
- Key: S
|
|
||||||
- Key: Down Arrow
|
|
||||||
|
|
||||||
interact:
|
|
||||||
- Key: E
|
|
||||||
- Key: Space
|
|
||||||
|
|
||||||
pause:
|
|
||||||
- Key: Escape
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔧 代码中的使用方法
|
|
||||||
|
|
||||||
### 移动输入检测
|
|
||||||
```gdscript
|
|
||||||
func _physics_process(delta: float) -> void:
|
|
||||||
# 获取移动向量
|
|
||||||
var direction := Input.get_vector(
|
|
||||||
"move_left", "move_right",
|
|
||||||
"move_up", "move_down"
|
|
||||||
)
|
|
||||||
|
|
||||||
# 应用移动
|
|
||||||
velocity = direction * move_speed
|
|
||||||
move_and_slide()
|
|
||||||
```
|
|
||||||
|
|
||||||
### 交互输入检测
|
|
||||||
```gdscript
|
|
||||||
func _input(event: InputEvent) -> void:
|
|
||||||
if event.is_action_pressed("interact"):
|
|
||||||
_handle_interaction()
|
|
||||||
|
|
||||||
if event.is_action_pressed("pause"):
|
|
||||||
_toggle_pause()
|
|
||||||
```
|
|
||||||
|
|
||||||
### 连续输入检测
|
|
||||||
```gdscript
|
|
||||||
func _process(delta: float) -> void:
|
|
||||||
# 检测持续按下的按键
|
|
||||||
if Input.is_action_pressed("interact"):
|
|
||||||
_continuous_interaction(delta)
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📱 手柄支持（可选）
|
|
||||||
|
|
||||||
### 推荐手柄映射
|
|
||||||
- **左摇杆** - 移动控制
|
|
||||||
- **A按钮/X按钮** - 交互
|
|
||||||
- **Start按钮** - 暂停
|
|
||||||
|
|
||||||
### 配置方法
|
|
||||||
1. 在Input Map中为每个动作添加手柄输入
|
|
||||||
2. 使用 `Joypad Button` 或 `Joypad Axis` 进行绑定
|
|
||||||
|
|
||||||
## ✅ 验证配置
|
|
||||||
|
|
||||||
### 测试脚本
|
|
||||||
创建一个简单的测试脚本验证输入配置：
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
extends Node
|
|
||||||
|
|
||||||
func _ready() -> void:
|
|
||||||
print("输入映射测试开始...")
|
|
||||||
_test_input_actions()
|
|
||||||
|
|
||||||
func _test_input_actions() -> void:
|
|
||||||
var required_actions = [
|
|
||||||
"move_left", "move_right", "move_up", "move_down",
|
|
||||||
"interact", "pause"
|
|
||||||
]
|
|
||||||
|
|
||||||
for action in required_actions:
|
|
||||||
if InputMap.has_action(action):
|
|
||||||
print("✅ ", action, " - 已配置")
|
|
||||||
else:
|
|
||||||
print("❌ ", action, " - 未配置")
|
|
||||||
|
|
||||||
func _input(event: InputEvent) -> void:
|
|
||||||
# 实时显示输入事件
|
|
||||||
for action in InputMap.get_actions():
|
|
||||||
if event.is_action_pressed(action):
|
|
||||||
print("按下: ", action)
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🚨 常见问题
|
|
||||||
|
|
||||||
### Q: 输入没有响应怎么办？
|
|
||||||
A: 检查以下几点：
|
|
||||||
1. 确认输入动作名称拼写正确
|
|
||||||
2. 验证按键是否正确绑定
|
|
||||||
3. 检查代码中是否正确使用了动作名称
|
|
||||||
|
|
||||||
### Q: 如何添加自定义输入？
|
|
||||||
A: 按照相同步骤在Input Map中添加新的动作，并在代码中使用对应的动作名称。
|
|
||||||
|
|
||||||
### Q: 手柄不工作怎么办？
|
|
||||||
A: 确保手柄已连接，并在Input Map中正确配置了手柄按钮映射。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**注意：输入映射配置是游戏正常运行的基础，请确保所有必需的输入动作都已正确配置！**
|
|
||||||
@@ -1,391 +0,0 @@
|
|||||||
# WhaleTown 项目结构说明
|
|
||||||
|
|
||||||
本文档详细说明了 WhaleTown 项目的文件结构设计，采用分层架构模式，确保团队协作高效且代码结构清晰。
|
|
||||||
|
|
||||||
## 🎯 设计理念
|
|
||||||
|
|
||||||
### 核心原则
|
|
||||||
- **分层架构**：框架层、游戏层、界面层明确分离
|
|
||||||
- **团队协作**：策划、美术、开发三类角色各司其职
|
|
||||||
- **高度解耦**：通过事件系统实现组件间通信
|
|
||||||
- **组件复用**：可复用组件统一管理
|
|
||||||
- **标准化**：统一的命名规范和目录结构
|
|
||||||
|
|
||||||
### 团队协作模式
|
|
||||||
- **🎮 开发团队** - 主要工作在 `_Core/`、`scenes/`、`UI/`、`Utils/`
|
|
||||||
- **🎨 美术团队** - 主要工作在 `assets/`
|
|
||||||
- **📋 策划团队** - 主要工作在 `Config/`
|
|
||||||
|
|
||||||
## 🏗️ 项目架构概览
|
|
||||||
|
|
||||||
```
|
|
||||||
WhaleTown/
|
|
||||||
├── 🔧 _Core/ # [核心层] 功能实现与组件实现，项目最基本的底层实现
|
|
||||||
├── 🎬 scenes/ # [场景层] 场景与视觉呈现，包含地图、人物等视觉部分
|
|
||||||
├── 🎨 assets/ # [资源层] 静态资源存储，包括图片、音乐、视频、贴图等
|
|
||||||
├── ⚙️ Config/ # [配置层] 配置文件管理，用于配置各类环境
|
|
||||||
├── 🧪 tests/ # [测试层] 测试文件系统，放置所有组件的测试代码
|
|
||||||
├── 🌐 web_assets/ # [发布层] Web导出资源，专门用于Web平台导出
|
|
||||||
└── 📚 docs/ # [文档层] 项目文档
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📁 详细目录结构
|
|
||||||
|
|
||||||
### 1. 🔧 核心层 (_Core/)
|
|
||||||
> **负责团队**: 开发团队
|
|
||||||
> **职责**: 功能实现与组件实现，项目最基本的底层实现
|
|
||||||
|
|
||||||
```
|
|
||||||
_Core/
|
|
||||||
├── managers/ # 全局管理器
|
|
||||||
│ ├── GameManager.gd # 游戏状态管理
|
|
||||||
│ ├── SceneManager.gd # 场景切换管理
|
|
||||||
│ ├── NetworkManager.gd # 网络通信管理
|
|
||||||
│ └── ResponseHandler.gd # API响应处理
|
|
||||||
├── systems/ # 核心系统
|
|
||||||
│ └── EventSystem.gd # 全局事件系统
|
|
||||||
├── components/ # 基础组件实现
|
|
||||||
│ ├── BaseCharacter.gd # 基础角色组件
|
|
||||||
│ ├── BaseItem.gd # 基础物品组件
|
|
||||||
│ └── BaseUI.gd # 基础UI组件
|
|
||||||
├── utils/ # 🔨 核心工具类
|
|
||||||
│ ├── StringUtils.gd # 字符串处理工具
|
|
||||||
│ ├── MathUtils.gd # 数学计算工具
|
|
||||||
│ └── PixelUtils.gd # 像素风游戏专用工具
|
|
||||||
├── EventNames.gd # 事件名称定义
|
|
||||||
└── ProjectPaths.gd # 路径统一管理
|
|
||||||
```
|
|
||||||
|
|
||||||
**特点**:
|
|
||||||
- 自动加载 (AutoLoad) 单例
|
|
||||||
- 全局可访问的核心功能
|
|
||||||
- 与具体游戏逻辑无关的底层实现
|
|
||||||
- 提供基础服务和组件框架
|
|
||||||
|
|
||||||
**使用示例**:
|
|
||||||
```gdscript
|
|
||||||
# 游戏状态管理
|
|
||||||
GameManager.change_state(GameManager.GameState.IN_GAME)
|
|
||||||
|
|
||||||
# 场景切换
|
|
||||||
SceneManager.change_scene("main")
|
|
||||||
|
|
||||||
# 事件通信
|
|
||||||
EventSystem.emit_event("player_moved", {"position": Vector2(100, 200)})
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. 🎬 场景层 (scenes/)
|
|
||||||
> **负责团队**: 开发团队
|
|
||||||
> **职责**: 场景与视觉呈现，包含地图场景、人物场景等一系列视觉呈现的部分
|
|
||||||
|
|
||||||
```
|
|
||||||
scenes/
|
|
||||||
├── maps/ # 地图场景
|
|
||||||
│ ├── main_world.tscn # 主世界地图
|
|
||||||
│ ├── dungeon_01.tscn # 地牢场景
|
|
||||||
│ └── town_center.tscn # 城镇中心
|
|
||||||
├── characters/ # 人物场景
|
|
||||||
│ ├── player/ # 玩家角色
|
|
||||||
│ │ ├── Player.tscn # 玩家场景
|
|
||||||
│ │ └── Player.gd # 玩家脚本
|
|
||||||
│ ├── npcs/ # NPC角色
|
|
||||||
│ └── enemies/ # 敌人角色
|
|
||||||
├── ui/ # UI界面场景
|
|
||||||
│ ├── menus/ # 菜单界面
|
|
||||||
│ ├── hud/ # 游戏HUD
|
|
||||||
│ └── dialogs/ # 对话框
|
|
||||||
├── effects/ # 特效场景
|
|
||||||
│ ├── particles/ # 粒子效果
|
|
||||||
│ └── animations/ # 动画效果
|
|
||||||
└── prefabs/ # 预制体组件
|
|
||||||
├── items/ # 物品预制体
|
|
||||||
└── interactive/ # 交互对象预制体
|
|
||||||
```
|
|
||||||
|
|
||||||
**设计原则**:
|
|
||||||
- **场景内聚**: 脚本紧邻场景文件存放
|
|
||||||
- **分类明确**: 按功能类型（地图、人物、UI、特效）分类
|
|
||||||
- **模块化**: 可复用的预制体统一管理
|
|
||||||
- **视觉导向**: 主要负责游戏的视觉呈现和UI实现
|
|
||||||
|
|
||||||
### 3. 🎨 资源层 (assets/)
|
|
||||||
> **负责团队**: 美术团队
|
|
||||||
> **职责**: 所有静态资源的存储，包括图片、音乐、视频、贴图等素材
|
|
||||||
|
|
||||||
```
|
|
||||||
assets/
|
|
||||||
├── sprites/ # 精灵图片资源
|
|
||||||
│ ├── characters/ # 角色精灵（玩家、NPC、敌人）
|
|
||||||
│ ├── environment/ # 环境精灵（地形、建筑、装饰）
|
|
||||||
│ ├── items/ # 物品精灵（道具、装备、收集品）
|
|
||||||
│ ├── effects/ # 特效精灵（爆炸、魔法、粒子）
|
|
||||||
│ └── ui/ # UI精灵（按钮、图标、边框）
|
|
||||||
├── audio/ # 音频资源
|
|
||||||
│ ├── music/ # 背景音乐（BGM）
|
|
||||||
│ ├── sounds/ # 音效（SFX）
|
|
||||||
│ └── voice/ # 语音（对话、旁白）
|
|
||||||
├── fonts/ # 字体文件
|
|
||||||
│ ├── pixel_fonts/ # 像素风字体
|
|
||||||
│ └── ui_fonts/ # UI专用字体
|
|
||||||
├── materials/ # 材质资源
|
|
||||||
│ ├── pixel_materials/ # 像素风材质
|
|
||||||
│ └── shader_materials/ # 着色器材质
|
|
||||||
├── shaders/ # 着色器文件
|
|
||||||
│ ├── pixel_shaders/ # 像素风着色器
|
|
||||||
│ └── effect_shaders/ # 特效着色器
|
|
||||||
├── ui/ # UI专用资源
|
|
||||||
│ ├── themes/ # UI主题
|
|
||||||
│ ├── icons/ # 图标资源
|
|
||||||
│ └── backgrounds/ # 背景图片
|
|
||||||
└── icon/ # 应用图标
|
|
||||||
├── icon.svg # 矢量图标
|
|
||||||
└── icon.png # 位图图标
|
|
||||||
```
|
|
||||||
|
|
||||||
**像素风游戏资源特点**:
|
|
||||||
- **像素完美**: 所有精灵使用像素完美设置（Filter: Off, Mipmaps: Off）
|
|
||||||
- **统一风格**: 保持一致的像素密度和调色板
|
|
||||||
- **分辨率标准**: 建议使用16x16、32x32等标准像素尺寸
|
|
||||||
- **动画帧**: 角色动画使用精灵表（Sprite Sheet）组织
|
|
||||||
|
|
||||||
### 4. ⚙️ 配置层 (Config/)
|
|
||||||
> **负责团队**: 策划团队
|
|
||||||
> **职责**: 配置文件管理，主要用来配置各类环境
|
|
||||||
|
|
||||||
```
|
|
||||||
Config/
|
|
||||||
├── game_config.json # 游戏主配置
|
|
||||||
├── zh_CN.json # 中文本地化
|
|
||||||
├── environment/ # 环境配置
|
|
||||||
│ ├── development.json # 开发环境配置
|
|
||||||
│ ├── testing.json # 测试环境配置
|
|
||||||
│ └── production.json # 生产环境配置
|
|
||||||
├── gameplay/ # 游戏玩法配置
|
|
||||||
│ ├── character_stats.json # 角色属性配置
|
|
||||||
│ ├── item_database.json # 物品数据库
|
|
||||||
│ └── level_config.json # 关卡配置
|
|
||||||
└── localization/ # 本地化配置
|
|
||||||
├── en_US.json # 英文本地化
|
|
||||||
├── zh_CN.json # 中文本地化
|
|
||||||
└── ja_JP.json # 日文本地化
|
|
||||||
```
|
|
||||||
|
|
||||||
**配置文件特点**:
|
|
||||||
- **环境分离**: 开发、测试、生产环境配置分离
|
|
||||||
- **数据驱动**: 游戏数值通过配置文件控制
|
|
||||||
- **本地化支持**: 多语言文本管理
|
|
||||||
- **热更新**: 支持运行时配置更新
|
|
||||||
|
|
||||||
### 5. 🧪 测试层 (tests/)
|
|
||||||
> **负责团队**: 开发团队
|
|
||||||
> **职责**: 测试文件系统，放置所有对应组件的测试代码，方便快速进行功能性与性能测试
|
|
||||||
|
|
||||||
```
|
|
||||||
tests/
|
|
||||||
├── unit/ # 单元测试
|
|
||||||
│ ├── core/ # 核心组件测试
|
|
||||||
│ ├── characters/ # 角色组件测试
|
|
||||||
│ └── systems/ # 系统功能测试
|
|
||||||
├── integration/ # 集成测试
|
|
||||||
│ ├── scene_transitions/ # 场景切换测试
|
|
||||||
│ ├── save_load/ # 存档系统测试
|
|
||||||
│ └── network/ # 网络功能测试
|
|
||||||
├── performance/ # 性能测试
|
|
||||||
│ ├── framerate/ # 帧率测试
|
|
||||||
│ ├── memory/ # 内存使用测试
|
|
||||||
│ └── loading_times/ # 加载时间测试
|
|
||||||
├── api/ # API接口测试
|
|
||||||
│ ├── auth_tests.py # 认证接口测试
|
|
||||||
│ └── game_api_tests.py # 游戏API测试
|
|
||||||
└── ui/ # UI功能测试
|
|
||||||
├── menu_tests/ # 菜单测试
|
|
||||||
└── dialog_tests/ # 对话框测试
|
|
||||||
```
|
|
||||||
|
|
||||||
**测试类型说明**:
|
|
||||||
- **单元测试**: 测试单个组件的功能正确性
|
|
||||||
- **集成测试**: 测试组件间的交互和协作
|
|
||||||
- **性能测试**: 监控游戏性能指标，确保流畅运行
|
|
||||||
- **API测试**: 验证网络接口的正确性和稳定性
|
|
||||||
- **UI测试**: 测试用户界面的交互和响应
|
|
||||||
|
|
||||||
### 6. 🌐 Web导出层 (web_assets/)
|
|
||||||
> **负责团队**: 自动生成
|
|
||||||
> **职责**: Web导出资源，专门用于Web平台导出的相关资源和配置文件
|
|
||||||
|
|
||||||
```
|
|
||||||
web_assets/
|
|
||||||
├── html/ # HTML模板文件
|
|
||||||
│ ├── index.html # Web版本入口页面
|
|
||||||
│ └── loading.html # 加载页面模板
|
|
||||||
├── css/ # 样式文件
|
|
||||||
│ ├── game.css # 游戏样式
|
|
||||||
│ └── loading.css # 加载样式
|
|
||||||
├── js/ # JavaScript脚本
|
|
||||||
│ ├── game_loader.js # 游戏加载器
|
|
||||||
│ └── utils.js # 工具函数
|
|
||||||
├── icons/ # Web应用图标
|
|
||||||
│ ├── favicon.ico # 网站图标
|
|
||||||
│ └── app_icons/ # PWA应用图标
|
|
||||||
└── config/ # Web配置文件
|
|
||||||
├── manifest.json # PWA清单文件
|
|
||||||
└── service-worker.js # 服务工作者
|
|
||||||
```
|
|
||||||
|
|
||||||
**Web导出特点**:
|
|
||||||
- **PWA支持**: 支持渐进式Web应用功能
|
|
||||||
- **响应式设计**: 适配不同屏幕尺寸
|
|
||||||
- **加载优化**: 优化资源加载和缓存策略
|
|
||||||
- **跨平台兼容**: 确保在各种浏览器中正常运行
|
|
||||||
|
|
||||||
### 7. 📚 文档层 (docs/)
|
|
||||||
> **负责团队**: 全体团队
|
|
||||||
> **职责**: 项目文档和开发指南
|
|
||||||
|
|
||||||
```
|
|
||||||
docs/
|
|
||||||
├── 01-项目入门/ # 新人必读文档
|
|
||||||
├── 02-开发规范/ # 编码标准文档
|
|
||||||
├── 03-技术实现/ # 开发指导文档
|
|
||||||
├── 04-高级开发/ # 进阶技巧文档
|
|
||||||
├── 05-部署运维/ # 发布部署文档
|
|
||||||
├── 06-功能模块/ # 功能文档
|
|
||||||
└── AI_docs/ # 🤖 AI专用文档
|
|
||||||
├── README.md # AI文档总览
|
|
||||||
├── architecture_guide.md # 架构执行指南
|
|
||||||
├── coding_standards.md # 代码风格规范
|
|
||||||
├── templates/ # 代码模板库
|
|
||||||
│ ├── components.md # 组件模板集合
|
|
||||||
│ ├── managers.md # 管理器模板集合
|
|
||||||
│ └── ui_templates.md # UI模板集合
|
|
||||||
├── workflows/ # 工作流程指南
|
|
||||||
│ ├── feature_development.md # 功能开发流程
|
|
||||||
│ ├── bug_fixing.md # Bug修复流程
|
|
||||||
│ └── testing_workflow.md # 测试执行流程
|
|
||||||
└── quick_reference/ # 快速参考手册
|
|
||||||
├── code_snippets.md # 常用代码片段
|
|
||||||
├── api_reference.md # API快速参考
|
|
||||||
└── troubleshooting.md # 故障排除指南
|
|
||||||
```
|
|
||||||
|
|
||||||
**AI_docs特点**:
|
|
||||||
- **结构化执行**: 每个文档都包含可直接执行的步骤和代码模板
|
|
||||||
- **标准化规范**: 为AI编程助手提供统一的开发标准和最佳实践
|
|
||||||
- **模板驱动**: 提供完整的代码模板，确保代码一致性和质量
|
|
||||||
- **工作流导向**: 包含详细的开发工作流程，提升AI协作效率
|
|
||||||
|
|
||||||
```
|
|
||||||
docs/
|
|
||||||
├── 01-项目入门/ # 新人必读
|
|
||||||
├── 02-开发规范/ # 编码标准
|
|
||||||
├── 03-技术实现/ # 开发指导
|
|
||||||
├── 04-高级开发/ # 进阶技巧
|
|
||||||
├── 05-部署运维/ # 发布部署
|
|
||||||
└── 06-功能模块/ # 功能文档
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🤝 团队协作指南
|
|
||||||
|
|
||||||
### 开发团队 🎮
|
|
||||||
**主要工作区域**: `_Core/`, `scenes/`, `tests/`
|
|
||||||
|
|
||||||
**日常工作流程**:
|
|
||||||
1. 在 `_Core/` 中开发核心系统、管理器、基础组件和工具类
|
|
||||||
2. 在 `scenes/` 中创建游戏场景、角色、UI界面和特效
|
|
||||||
3. 在 `tests/` 中编写各类测试用例确保代码质量
|
|
||||||
|
|
||||||
**协作要点**:
|
|
||||||
- 遵循架构设计原则，使用事件系统进行模块通信
|
|
||||||
- 保持代码模块化和可复用性
|
|
||||||
- 将通用工具类放在 `_Core/utils/` 中统一管理
|
|
||||||
- 针对像素风游戏特点优化性能
|
|
||||||
- 及时编写测试和文档
|
|
||||||
|
|
||||||
### 美术团队 🎨
|
|
||||||
**主要工作区域**: `assets/`
|
|
||||||
|
|
||||||
**日常工作流程**:
|
|
||||||
1. 按分类整理美术资源到 `assets/` 对应目录
|
|
||||||
2. 确保像素艺术风格的一致性和像素完美
|
|
||||||
3. 配置正确的Godot导入设置（关闭过滤、禁用Mipmaps）
|
|
||||||
4. 与开发团队协作调整UI和游戏资源
|
|
||||||
|
|
||||||
**像素风游戏特殊要求**:
|
|
||||||
- 严格遵循像素完美原则
|
|
||||||
- 保持统一的像素密度和调色板
|
|
||||||
- 使用标准像素尺寸（16x16、32x32等）
|
|
||||||
- 精灵动画使用精灵表组织
|
|
||||||
|
|
||||||
### 策划团队 📋
|
|
||||||
**主要工作区域**: `Config/`
|
|
||||||
|
|
||||||
**日常工作流程**:
|
|
||||||
1. 在 `Config/` 中维护游戏配置和数值平衡
|
|
||||||
2. 管理多环境配置（开发、测试、生产）
|
|
||||||
3. 负责本地化文本的翻译和维护
|
|
||||||
4. 设计游戏玩法和关卡数据
|
|
||||||
|
|
||||||
**协作要点**:
|
|
||||||
- 使用JSON格式编写配置文件
|
|
||||||
- 保持配置文件的结构清晰和可维护性
|
|
||||||
- 及时更新本地化文本
|
|
||||||
- 与开发团队协作实现数据驱动的游戏功能
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔄 开发工作流
|
|
||||||
|
|
||||||
### 新功能开发流程
|
|
||||||
1. **需求分析** - 明确功能需求和设计方案
|
|
||||||
2. **架构设计** - 确定涉及的模块和接口
|
|
||||||
3. **资源准备** - 美术团队准备相关资源
|
|
||||||
4. **配置设置** - 策划团队配置相关数据
|
|
||||||
5. **代码实现** - 开发团队实现功能逻辑
|
|
||||||
6. **测试验证** - 编写测试用例验证功能
|
|
||||||
7. **文档更新** - 更新相关文档说明
|
|
||||||
|
|
||||||
### 版本发布流程
|
|
||||||
1. **功能完成** - 所有计划功能开发完成
|
|
||||||
2. **测试通过** - 所有测试用例通过
|
|
||||||
3. **资源整理** - 美术资源整理完成
|
|
||||||
4. **配置确认** - 策划配置确认无误
|
|
||||||
5. **构建发布** - 使用 `tools/` 中的脚本构建
|
|
||||||
6. **部署上线** - 部署到目标环境
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📋 最佳实践
|
|
||||||
|
|
||||||
### 目录命名规范
|
|
||||||
- **文件夹**: 使用 PascalCase (如: `Config/`, `Utils/`)
|
|
||||||
- **文件**: 使用 snake_case (如: `main_scene.tscn`, `game_config.json`)
|
|
||||||
- **脚本类**: 使用 PascalCase (如: `GameManager.gd`)
|
|
||||||
|
|
||||||
### 资源管理规范
|
|
||||||
- 所有资源必须放在 `assets/` 对应分类目录下
|
|
||||||
- 使用描述性的文件名，避免使用数字编号
|
|
||||||
- **像素艺术资源必须关闭过滤** (Filter: Off, Mipmaps: Off)
|
|
||||||
- 保持统一的像素密度和调色板
|
|
||||||
- 使用标准像素尺寸（16x16、32x32、64x64等）
|
|
||||||
- 及时清理不使用的资源文件
|
|
||||||
|
|
||||||
### 代码组织规范
|
|
||||||
- 脚本文件与场景文件放在同一目录
|
|
||||||
- 使用事件系统实现模块间通信，避免直接引用
|
|
||||||
- 保持单一职责原则，避免过度耦合
|
|
||||||
- 针对像素风游戏优化性能（避免浮点数位置、使用整数坐标）
|
|
||||||
- 及时编写注释和文档
|
|
||||||
|
|
||||||
### 像素风游戏特殊规范
|
|
||||||
- **像素完美**: 确保所有精灵在整数坐标上渲染
|
|
||||||
- **统一风格**: 保持一致的像素密度和艺术风格
|
|
||||||
- **性能优化**: 使用对象池管理频繁创建销毁的对象
|
|
||||||
- **分辨率适配**: 使用像素完美的缩放方式适配不同分辨率
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**记住：良好的项目结构是团队协作成功的基础！**
|
|
||||||
@@ -1,142 +0,0 @@
|
|||||||
# 项目设置指南
|
|
||||||
|
|
||||||
本文档指导你完成WhaleTown项目的Godot编辑器配置，确保开发环境正确设置。
|
|
||||||
|
|
||||||
## 🎯 AutoLoad 配置
|
|
||||||
|
|
||||||
项目已经预配置了以下AutoLoad单例，你可以验证配置是否正确：
|
|
||||||
|
|
||||||
### 1. 打开项目设置
|
|
||||||
1. 在Godot编辑器中打开 `Project` → `Project Settings`
|
|
||||||
2. 切换到 `AutoLoad` 标签
|
|
||||||
|
|
||||||
### 2. 验证AutoLoad配置
|
|
||||||
确认以下单例已正确配置：
|
|
||||||
|
|
||||||
| 名称 | 路径 | 单例 |
|
|
||||||
|------|------|------|
|
|
||||||
| GameManager | `res://_Core/managers/GameManager.gd` | ✅ |
|
|
||||||
| SceneManager | `res://_Core/managers/SceneManager.gd` | ✅ |
|
|
||||||
| EventSystem | `res://_Core/systems/EventSystem.gd` | ✅ |
|
|
||||||
| NetworkManager | `res://_Core/managers/NetworkManager.gd` | ✅ |
|
|
||||||
| ResponseHandler | `res://_Core/managers/ResponseHandler.gd` | ✅ |
|
|
||||||
|
|
||||||
### 3. 如果需要手动添加AutoLoad
|
|
||||||
如果某个AutoLoad缺失，可以手动添加：
|
|
||||||
|
|
||||||
1. 点击 `Add` 按钮
|
|
||||||
2. 设置以下信息：
|
|
||||||
- **Path**: 对应的脚本路径
|
|
||||||
- **Name**: 单例名称
|
|
||||||
- **Singleton**: ✅ 勾选
|
|
||||||
3. 点击 `Add` 确认
|
|
||||||
|
|
||||||
## ⚙️ 其他重要设置
|
|
||||||
|
|
||||||
### 主题配置
|
|
||||||
项目使用自定义中文主题：
|
|
||||||
- **路径**: `assets/ui/chinese_theme.tres`
|
|
||||||
- **字体**: 微软雅黑 (`assets/fonts/msyh.ttc`)
|
|
||||||
|
|
||||||
### 主场景设置
|
|
||||||
- **主场景**: `res://Scenes/Maps/main_scene.tscn`
|
|
||||||
- **窗口大小**: 1376x768
|
|
||||||
- **窗口模式**: 全屏模式
|
|
||||||
|
|
||||||
### 渲染设置
|
|
||||||
- **渲染器**: GL Compatibility (兼容性优先)
|
|
||||||
- **拉伸模式**: Canvas Items
|
|
||||||
- **拉伸比例**: Expand
|
|
||||||
|
|
||||||
## 🧪 验证设置
|
|
||||||
|
|
||||||
### 1. 测试AutoLoad单例
|
|
||||||
在任何脚本中可以直接使用：
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
func _ready():
|
|
||||||
# 测试GameManager
|
|
||||||
print("游戏状态: ", GameManager.get_current_state())
|
|
||||||
|
|
||||||
# 测试SceneManager
|
|
||||||
print("当前场景: ", SceneManager.get_current_scene_name())
|
|
||||||
|
|
||||||
# 测试EventSystem
|
|
||||||
EventSystem.emit_event("test_event", {"message": "Hello World"})
|
|
||||||
|
|
||||||
# 测试NetworkManager
|
|
||||||
var request_id = NetworkManager.login("test_user", "test_password")
|
|
||||||
print("网络请求ID: ", request_id)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. 检查控制台输出
|
|
||||||
运行项目后，检查控制台是否有以下信息：
|
|
||||||
- ✅ 没有AutoLoad相关错误
|
|
||||||
- ✅ 各个管理器初始化成功
|
|
||||||
- ✅ 主题和字体加载正常
|
|
||||||
|
|
||||||
### 3. 测试场景切换
|
|
||||||
```gdscript
|
|
||||||
# 测试场景管理器
|
|
||||||
func test_scene_manager():
|
|
||||||
# 切换到主场景
|
|
||||||
SceneManager.change_scene("main")
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔧 常见问题排查
|
|
||||||
|
|
||||||
### 问题1: AutoLoad脚本找不到
|
|
||||||
**症状**: 控制台显示"Cannot load script"错误
|
|
||||||
|
|
||||||
**解决方案**:
|
|
||||||
1. 检查脚本文件是否存在于指定路径
|
|
||||||
2. 确认脚本文件没有语法错误
|
|
||||||
3. 重新导入项目 (`Project` → `Reload Current Project`)
|
|
||||||
|
|
||||||
### 问题2: 单例无法访问
|
|
||||||
**症状**: 代码中无法访问GameManager等单例
|
|
||||||
|
|
||||||
**解决方案**:
|
|
||||||
1. 确认AutoLoad配置中勾选了"Singleton"
|
|
||||||
2. 重启Godot编辑器
|
|
||||||
3. 检查脚本中是否有拼写错误
|
|
||||||
|
|
||||||
### 问题3: 主题显示异常
|
|
||||||
**症状**: 界面字体或样式显示不正确
|
|
||||||
|
|
||||||
**解决方案**:
|
|
||||||
1. 检查 `assets/ui/chinese_theme.tres` 文件是否存在
|
|
||||||
2. 确认字体文件 `assets/fonts/msyh.ttc` 已正确导入
|
|
||||||
3. 在项目设置中重新设置自定义主题
|
|
||||||
|
|
||||||
### 问题4: 网络请求失败
|
|
||||||
**症状**: NetworkManager调用失败
|
|
||||||
|
|
||||||
**解决方案**:
|
|
||||||
1. 检查网络连接
|
|
||||||
2. 确认API地址配置正确
|
|
||||||
3. 查看ResponseHandler是否正常工作
|
|
||||||
|
|
||||||
## 📋 配置检查清单
|
|
||||||
|
|
||||||
完成设置后，请检查以下项目：
|
|
||||||
|
|
||||||
- [ ] 所有AutoLoad单例配置正确
|
|
||||||
- [ ] 主场景可以正常启动
|
|
||||||
- [ ] 控制台没有错误信息
|
|
||||||
- [ ] 自定义主题加载正常
|
|
||||||
- [ ] 中文字体显示正确
|
|
||||||
- [ ] 网络管理器可以正常调用
|
|
||||||
- [ ] 事件系统工作正常
|
|
||||||
- [ ] 场景管理器可以切换场景
|
|
||||||
|
|
||||||
## 🚀 下一步
|
|
||||||
|
|
||||||
配置完成后，建议继续阅读：
|
|
||||||
- [输入映射配置](输入映射配置.md) - 设置游戏控制
|
|
||||||
- [命名规范](../02-开发规范/命名规范.md) - 学习编码规范
|
|
||||||
- [架构与通信规范](../02-开发规范/架构与通信规范.md) - 理解项目架构
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**💡 提示**: 如果遇到问题，可以参考 [测试指南](../03-技术实现/测试指南.md) 进行更详细的功能验证。
|
|
||||||
@@ -1,105 +0,0 @@
|
|||||||
# 📋 开发规范
|
|
||||||
|
|
||||||
> **适用人群**: 所有开发者
|
|
||||||
> **使用时机**: 编码过程中，代码审查时
|
|
||||||
|
|
||||||
这个目录包含了项目的所有编码标准和开发规范，确保团队代码风格一致，架构设计统一。
|
|
||||||
|
|
||||||
## 📚 规范文档
|
|
||||||
|
|
||||||
### 基础规范 📝
|
|
||||||
**[命名规范.md](命名规范.md)**
|
|
||||||
- 文件、类、变量、函数命名标准
|
|
||||||
- 资源文件命名规则
|
|
||||||
- 目录结构命名约定
|
|
||||||
|
|
||||||
**[代码注释规范.md](代码注释规范.md)**
|
|
||||||
- 注释格式和标准
|
|
||||||
- 文档生成规范
|
|
||||||
- AI辅助开发指南
|
|
||||||
|
|
||||||
**[Git提交规范.md](Git提交规范.md)**
|
|
||||||
- 提交信息格式标准
|
|
||||||
- 分支管理策略
|
|
||||||
- 代码审查流程
|
|
||||||
|
|
||||||
### 架构规范 🏗️
|
|
||||||
**[架构与通信规范.md](架构与通信规范.md)**
|
|
||||||
- 分层架构设计原则
|
|
||||||
- EventSystem事件系统使用
|
|
||||||
- 组件间通信标准
|
|
||||||
- 单例管理规范
|
|
||||||
|
|
||||||
### 质量标准 ⭐
|
|
||||||
**[开发哲学与最佳实践.md](开发哲学与最佳实践.md)**
|
|
||||||
- 项目开发理念
|
|
||||||
- 代码质量标准
|
|
||||||
- 最佳实践指导
|
|
||||||
- 代码审查清单
|
|
||||||
|
|
||||||
## 🎯 使用指南
|
|
||||||
|
|
||||||
### 新人学习路径
|
|
||||||
1. **命名规范** - 学会正确命名
|
|
||||||
2. **架构与通信规范** - 理解项目架构
|
|
||||||
3. **开发哲学与最佳实践** - 掌握质量标准
|
|
||||||
4. **代码注释规范** - 学会写好注释
|
|
||||||
5. **Git提交规范** - 规范版本控制
|
|
||||||
|
|
||||||
### 日常开发参考
|
|
||||||
- 编码时参考 **命名规范** 和 **架构规范**
|
|
||||||
- 提交代码前检查 **最佳实践** 清单
|
|
||||||
- 写注释时遵循 **注释规范**
|
|
||||||
- 提交时遵循 **Git规范**
|
|
||||||
|
|
||||||
### 代码审查要点
|
|
||||||
- [ ] 命名是否符合规范
|
|
||||||
- [ ] 架构设计是否合理
|
|
||||||
- [ ] 代码质量是否达标
|
|
||||||
- [ ] 注释是否完整清晰
|
|
||||||
- [ ] 提交信息是否规范
|
|
||||||
|
|
||||||
## ⚠️ 重要提醒
|
|
||||||
|
|
||||||
### 强制性规范
|
|
||||||
以下规范是**强制性**的，必须严格遵守：
|
|
||||||
- 文件和目录命名规范
|
|
||||||
- EventSystem通信规范
|
|
||||||
- 类型安全要求
|
|
||||||
- Git提交格式
|
|
||||||
|
|
||||||
### 建议性规范
|
|
||||||
以下规范是**建议性**的，推荐遵循：
|
|
||||||
- 代码注释的详细程度
|
|
||||||
- 函数长度和复杂度
|
|
||||||
- 性能优化建议
|
|
||||||
|
|
||||||
## 🔄 规范更新
|
|
||||||
|
|
||||||
### 更新原则
|
|
||||||
- 规范变更需要团队讨论
|
|
||||||
- 重大变更需要文档化说明
|
|
||||||
- 保持向后兼容性
|
|
||||||
|
|
||||||
### 更新流程
|
|
||||||
1. 提出规范变更建议
|
|
||||||
2. 团队讨论和评审
|
|
||||||
3. 更新相关文档
|
|
||||||
4. 通知所有开发者
|
|
||||||
|
|
||||||
## 🤝 团队协作
|
|
||||||
|
|
||||||
### 规范执行
|
|
||||||
- 代码审查时严格检查规范遵循情况
|
|
||||||
- 定期进行规范培训和分享
|
|
||||||
- 鼓励团队成员提出改进建议
|
|
||||||
|
|
||||||
### 问题反馈
|
|
||||||
如果发现规范问题或有改进建议：
|
|
||||||
- 创建Issue讨论
|
|
||||||
- 在团队会议中提出
|
|
||||||
- 通过PR提交改进方案
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**记住：规范不是束缚，而是团队协作的基础！**
|
|
||||||
@@ -1,433 +0,0 @@
|
|||||||
# GDScript 代码注释规范
|
|
||||||
|
|
||||||
本文档详细说明了 whaleTown 项目中 GDScript 代码的注释规范，旨在提高代码可读性和维护性。
|
|
||||||
|
|
||||||
## 目录
|
|
||||||
|
|
||||||
- [基本原则](#基本原则)
|
|
||||||
- [文件头注释](#文件头注释)
|
|
||||||
- [类和函数注释](#类和函数注释)
|
|
||||||
- [变量注释](#变量注释)
|
|
||||||
- [行内注释](#行内注释)
|
|
||||||
- [特殊注释标记](#特殊注释标记)
|
|
||||||
- [AI辅助注释指南](#ai辅助注释指南)
|
|
||||||
|
|
||||||
## 基本原则
|
|
||||||
|
|
||||||
### 注释的目的
|
|
||||||
- **解释为什么**，而不是解释做什么
|
|
||||||
- **提供上下文**，帮助理解代码意图
|
|
||||||
- **记录重要决策**和设计考虑
|
|
||||||
- **警告潜在问题**和注意事项
|
|
||||||
|
|
||||||
### 注释质量标准
|
|
||||||
- 简洁明了，避免冗余
|
|
||||||
- 使用中文，保持一致性
|
|
||||||
- 及时更新，与代码同步
|
|
||||||
- 避免显而易见的注释
|
|
||||||
|
|
||||||
## 文件头注释
|
|
||||||
|
|
||||||
每个 GDScript 文件都应该包含文件头注释，说明文件的用途和基本信息。
|
|
||||||
|
|
||||||
### 标准格式
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# ============================================================================
|
|
||||||
# 文件名: PlayerController.gd
|
|
||||||
# 作用: 玩家角色控制器，处理玩家输入和移动逻辑
|
|
||||||
#
|
|
||||||
# 主要功能:
|
|
||||||
# - 处理键盘和手柄输入
|
|
||||||
# - 控制角色移动和跳跃
|
|
||||||
# - 管理角色状态切换
|
|
||||||
# - 处理碰撞检测
|
|
||||||
#
|
|
||||||
# 依赖: MovementComponent, AnimationComponent
|
|
||||||
# 作者: [开发者名称]
|
|
||||||
# 创建时间: 2024-12-24
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
extends CharacterBody2D
|
|
||||||
```
|
|
||||||
|
|
||||||
### 管理器类文件头
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# ============================================================================
|
|
||||||
# 游戏管理器 - GameManager.gd
|
|
||||||
#
|
|
||||||
# 全局单例管理器，负责游戏状态管理和生命周期控制
|
|
||||||
#
|
|
||||||
# 核心职责:
|
|
||||||
# - 游戏状态切换 (加载、认证、游戏中、暂停等)
|
|
||||||
# - 用户信息管理
|
|
||||||
# - 全局配置访问
|
|
||||||
# - 系统初始化和清理
|
|
||||||
#
|
|
||||||
# 使用方式:
|
|
||||||
# GameManager.change_state(GameManager.GameState.IN_GAME)
|
|
||||||
# GameManager.set_current_user("player123")
|
|
||||||
#
|
|
||||||
# 注意事项:
|
|
||||||
# - 作为自动加载单例，全局可访问
|
|
||||||
# - 状态变更会触发 game_state_changed 信号
|
|
||||||
# ============================================================================
|
|
||||||
|
|
||||||
extends Node
|
|
||||||
```
|
|
||||||
## 类和函数注释
|
|
||||||
|
|
||||||
### 类注释
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# 玩家数据类
|
|
||||||
#
|
|
||||||
# 存储和管理玩家的基本属性和状态信息
|
|
||||||
# 支持数据序列化和反序列化，用于存档系统
|
|
||||||
class_name PlayerData
|
|
||||||
|
|
||||||
# 武器组件类
|
|
||||||
#
|
|
||||||
# 为角色提供武器功能，包括攻击、换弹、特殊技能等
|
|
||||||
# 可以挂载到任何具有攻击能力的角色上
|
|
||||||
#
|
|
||||||
# 使用示例:
|
|
||||||
# var weapon = WeaponComponent.new()
|
|
||||||
# weapon.setup_weapon("sword", 50)
|
|
||||||
# add_child(weapon)
|
|
||||||
class_name WeaponComponent
|
|
||||||
```
|
|
||||||
|
|
||||||
### 函数注释格式
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# 处理玩家输入并更新移动状态
|
|
||||||
#
|
|
||||||
# 参数:
|
|
||||||
# delta: float - 帧时间间隔
|
|
||||||
#
|
|
||||||
# 返回值: 无
|
|
||||||
#
|
|
||||||
# 注意事项:
|
|
||||||
# - 需要在 _physics_process 中调用
|
|
||||||
# - 会自动处理重力和碰撞
|
|
||||||
func handle_movement(delta: float) -> void:
|
|
||||||
|
|
||||||
# 验证用户输入的邮箱格式
|
|
||||||
#
|
|
||||||
# 参数:
|
|
||||||
# email: String - 待验证的邮箱地址
|
|
||||||
#
|
|
||||||
# 返回值:
|
|
||||||
# Dictionary - 包含验证结果和错误信息
|
|
||||||
# {
|
|
||||||
# "valid": bool, # 是否有效
|
|
||||||
# "message": String # 错误信息（如果无效）
|
|
||||||
# }
|
|
||||||
#
|
|
||||||
# 使用示例:
|
|
||||||
# var result = validate_email("test@example.com")
|
|
||||||
# if result.valid:
|
|
||||||
# print("邮箱格式正确")
|
|
||||||
static func validate_email(email: String) -> Dictionary:
|
|
||||||
```
|
|
||||||
## 变量注释
|
|
||||||
|
|
||||||
### 成员变量注释
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# 玩家基础属性
|
|
||||||
@export var max_health: int = 100 # 最大生命值
|
|
||||||
@export var move_speed: float = 200.0 # 移动速度 (像素/秒)
|
|
||||||
@export var jump_force: float = -400.0 # 跳跃力度 (负值向上)
|
|
||||||
|
|
||||||
# 状态管理
|
|
||||||
var current_health: int # 当前生命值
|
|
||||||
var is_grounded: bool = false # 是否在地面上
|
|
||||||
var can_double_jump: bool = true # 是否可以二段跳
|
|
||||||
|
|
||||||
# 节点引用 - 在 _ready() 中初始化
|
|
||||||
@onready var sprite: Sprite2D = $Sprite2D
|
|
||||||
@onready var collision: CollisionShape2D = $CollisionShape2D
|
|
||||||
@onready var animation_player: AnimationPlayer = $AnimationPlayer
|
|
||||||
|
|
||||||
# 私有变量 - 内部使用
|
|
||||||
var _velocity: Vector2 = Vector2.ZERO # 当前速度向量
|
|
||||||
var _last_direction: int = 1 # 最后面向方向 (1=右, -1=左)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 常量注释
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# 游戏配置常量
|
|
||||||
const GRAVITY: float = 980.0 # 重力加速度 (像素/秒²)
|
|
||||||
const MAX_FALL_SPEED: float = 1000.0 # 最大下落速度
|
|
||||||
const COYOTE_TIME: float = 0.1 # 土狼时间 (离开平台后仍可跳跃的时间)
|
|
||||||
|
|
||||||
# 输入动作名称
|
|
||||||
const ACTION_MOVE_LEFT: String = "move_left"
|
|
||||||
const ACTION_MOVE_RIGHT: String = "move_right"
|
|
||||||
const ACTION_JUMP: String = "jump"
|
|
||||||
|
|
||||||
# 动画名称常量
|
|
||||||
const ANIM_IDLE: String = "idle"
|
|
||||||
const ANIM_WALK: String = "walk"
|
|
||||||
const ANIM_JUMP: String = "jump"
|
|
||||||
const ANIM_FALL: String = "fall"
|
|
||||||
```
|
|
||||||
|
|
||||||
## 行内注释
|
|
||||||
|
|
||||||
### 复杂逻辑注释
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
func update_movement(delta: float):
|
|
||||||
# 处理水平移动输入
|
|
||||||
var input_direction = Input.get_axis("move_left", "move_right")
|
|
||||||
|
|
||||||
if input_direction != 0:
|
|
||||||
velocity.x = input_direction * move_speed
|
|
||||||
_last_direction = sign(input_direction) # 记录面向方向
|
|
||||||
else:
|
|
||||||
# 应用摩擦力，逐渐停止
|
|
||||||
velocity.x = move_toward(velocity.x, 0, friction * delta)
|
|
||||||
|
|
||||||
# 应用重力 (只在空中时)
|
|
||||||
if not is_on_floor():
|
|
||||||
velocity.y += gravity * delta
|
|
||||||
velocity.y = min(velocity.y, max_fall_speed) # 限制最大下落速度
|
|
||||||
|
|
||||||
# 处理跳跃输入
|
|
||||||
if Input.is_action_just_pressed("jump"):
|
|
||||||
if is_on_floor():
|
|
||||||
velocity.y = jump_force # 普通跳跃
|
|
||||||
elif can_double_jump:
|
|
||||||
velocity.y = jump_force * 0.8 # 二段跳 (力度稍小)
|
|
||||||
can_double_jump = false
|
|
||||||
|
|
||||||
# 重置二段跳能力
|
|
||||||
if is_on_floor() and not can_double_jump:
|
|
||||||
can_double_jump = true
|
|
||||||
```
|
|
||||||
|
|
||||||
### 临时解决方案注释
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
func handle_collision(body: Node2D):
|
|
||||||
# TODO: 重构碰撞处理逻辑，当前实现过于复杂
|
|
||||||
# FIXME: 在某些情况下会出现重复碰撞检测
|
|
||||||
# HACK: 临时解决方案，等待 Godot 4.6 修复相关 bug
|
|
||||||
|
|
||||||
if body.has_method("take_damage"):
|
|
||||||
# NOTE: 伤害计算需要考虑护甲和抗性
|
|
||||||
var damage = calculate_damage(base_damage)
|
|
||||||
body.take_damage(damage)
|
|
||||||
```
|
|
||||||
## 特殊注释标记
|
|
||||||
|
|
||||||
使用标准化的标记来标识不同类型的注释：
|
|
||||||
|
|
||||||
### 标记类型
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# TODO: 待实现的功能
|
|
||||||
# TODO: 添加音效播放功能
|
|
||||||
# TODO: 实现存档系统
|
|
||||||
|
|
||||||
# FIXME: 需要修复的问题
|
|
||||||
# FIXME: 内存泄漏问题，需要及时释放资源
|
|
||||||
# FIXME: 在低帧率下移动不流畅
|
|
||||||
|
|
||||||
# HACK: 临时解决方案
|
|
||||||
# HACK: 绕过 Godot 引擎的已知 bug
|
|
||||||
# HACK: 临时方案，等待更好的实现
|
|
||||||
|
|
||||||
# NOTE: 重要说明
|
|
||||||
# NOTE: 此函数会修改全局状态，谨慎使用
|
|
||||||
# NOTE: 性能敏感代码，避免频繁调用
|
|
||||||
|
|
||||||
# WARNING: 警告信息
|
|
||||||
# WARNING: 不要在 _ready() 之前调用此函数
|
|
||||||
# WARNING: 此操作不可逆，请确认后执行
|
|
||||||
|
|
||||||
# OPTIMIZE: 性能优化点
|
|
||||||
# OPTIMIZE: 可以使用对象池优化内存分配
|
|
||||||
# OPTIMIZE: 考虑使用缓存提高查询效率
|
|
||||||
```
|
|
||||||
|
|
||||||
### 版本和兼容性标记
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# @since 1.0.0 - 添加基础移动功能
|
|
||||||
# @deprecated 使用 new_movement_system() 替代
|
|
||||||
# @godot_version 4.5+ - 需要 Godot 4.5 或更高版本
|
|
||||||
# @platform_specific Windows/Linux - 仅在桌面平台可用
|
|
||||||
```
|
|
||||||
|
|
||||||
## AI辅助注释指南
|
|
||||||
|
|
||||||
### 为AI提供的注释模板
|
|
||||||
|
|
||||||
当需要AI帮助补充注释时，请使用以下模板：
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# [AI_COMMENT_REQUEST]
|
|
||||||
# 请为以下函数添加详细注释，包括：
|
|
||||||
# - 功能描述
|
|
||||||
# - 参数说明
|
|
||||||
# - 返回值说明
|
|
||||||
# - 使用示例
|
|
||||||
# - 注意事项
|
|
||||||
func complex_function(param1: String, param2: int) -> Dictionary:
|
|
||||||
# 复杂的业务逻辑...
|
|
||||||
pass
|
|
||||||
```
|
|
||||||
|
|
||||||
### AI注释补充规则
|
|
||||||
|
|
||||||
1. **保持一致性** - 遵循项目现有的注释风格
|
|
||||||
2. **关注业务逻辑** - 重点解释业务含义，而非语法
|
|
||||||
3. **提供上下文** - 说明函数在整个系统中的作用
|
|
||||||
4. **标注复杂度** - 对复杂算法提供额外说明
|
|
||||||
|
|
||||||
### 示例：AI补充前后对比
|
|
||||||
|
|
||||||
**补充前：**
|
|
||||||
```gdscript
|
|
||||||
func calculate_damage(base_damage: int, armor: int, resistance: float) -> int:
|
|
||||||
var final_damage = base_damage
|
|
||||||
final_damage -= armor
|
|
||||||
final_damage *= (1.0 - resistance)
|
|
||||||
return max(1, final_damage)
|
|
||||||
```
|
|
||||||
|
|
||||||
**AI补充后：**
|
|
||||||
```gdscript
|
|
||||||
# 计算最终伤害值
|
|
||||||
#
|
|
||||||
# 根据基础伤害、护甲值和抗性计算实际造成的伤害
|
|
||||||
# 伤害计算公式: (基础伤害 - 护甲) × (1 - 抗性)
|
|
||||||
#
|
|
||||||
# 参数:
|
|
||||||
# base_damage: int - 基础伤害值
|
|
||||||
# armor: int - 目标护甲值 (减少固定伤害)
|
|
||||||
# resistance: float - 目标抗性 (0.0-1.0, 减少百分比伤害)
|
|
||||||
#
|
|
||||||
# 返回值:
|
|
||||||
# int - 最终伤害值 (最小为1，确保至少造成1点伤害)
|
|
||||||
#
|
|
||||||
# 使用示例:
|
|
||||||
# var damage = calculate_damage(100, 20, 0.3) # 结果: 56
|
|
||||||
#
|
|
||||||
# 注意事项:
|
|
||||||
# - 护甲为负值时会增加伤害
|
|
||||||
# - 抗性超过1.0时可能导致负伤害，但会被限制为1
|
|
||||||
func calculate_damage(base_damage: int, armor: int, resistance: float) -> int:
|
|
||||||
var final_damage = base_damage
|
|
||||||
final_damage -= armor # 减去护甲值
|
|
||||||
final_damage *= (1.0 - resistance) # 应用抗性
|
|
||||||
return max(1, final_damage) # 确保最小伤害为1
|
|
||||||
```
|
|
||||||
## 注释最佳实践
|
|
||||||
|
|
||||||
### 什么时候需要注释
|
|
||||||
|
|
||||||
**必须添加注释的情况：**
|
|
||||||
- 复杂的算法和业务逻辑
|
|
||||||
- 非显而易见的设计决策
|
|
||||||
- 临时解决方案和已知问题
|
|
||||||
- 公共API和接口函数
|
|
||||||
- 性能敏感的代码段
|
|
||||||
- 平台特定或版本特定的代码
|
|
||||||
|
|
||||||
**不需要注释的情况：**
|
|
||||||
- 显而易见的代码 (`var count = 0 # 计数器` ❌)
|
|
||||||
- 重复函数名的注释 (`func get_name() -> String: # 获取名称` ❌)
|
|
||||||
- 过时或错误的注释
|
|
||||||
|
|
||||||
### 注释维护原则
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# ✅ 好的注释 - 解释为什么这样做
|
|
||||||
# 使用二分查找提高大数组的查询效率
|
|
||||||
# 当数组长度超过100时，线性查找性能会显著下降
|
|
||||||
func binary_search(array: Array, target: Variant) -> int:
|
|
||||||
|
|
||||||
# ❌ 坏的注释 - 重复代码内容
|
|
||||||
# 遍历数组查找目标值
|
|
||||||
func linear_search(array: Array, target: Variant) -> int:
|
|
||||||
```
|
|
||||||
|
|
||||||
### 团队协作注释
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# 多人协作时的注释规范
|
|
||||||
class_name NetworkManager
|
|
||||||
|
|
||||||
# @author: 张三 - 网络连接模块
|
|
||||||
# @author: 李四 - 数据同步模块
|
|
||||||
# @reviewer: 王五 - 代码审查
|
|
||||||
# @last_modified: 2024-12-24
|
|
||||||
|
|
||||||
# 网络连接状态枚举
|
|
||||||
#
|
|
||||||
# 定义了客户端与服务器的连接状态
|
|
||||||
# 状态转换: DISCONNECTED -> CONNECTING -> CONNECTED -> DISCONNECTED
|
|
||||||
enum ConnectionState {
|
|
||||||
DISCONNECTED, # 未连接
|
|
||||||
CONNECTING, # 连接中
|
|
||||||
CONNECTED, # 已连接
|
|
||||||
RECONNECTING # 重连中 - @added by 李四 2024-12-20
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## 注释检查清单
|
|
||||||
|
|
||||||
在提交代码前，请检查以下项目：
|
|
||||||
|
|
||||||
### 文件级别检查
|
|
||||||
- [ ] 文件头注释完整（文件名、作用、主要功能）
|
|
||||||
- [ ] 依赖关系说明清楚
|
|
||||||
- [ ] 作者和创建时间已填写
|
|
||||||
|
|
||||||
### 函数级别检查
|
|
||||||
- [ ] 公共函数有完整的参数和返回值说明
|
|
||||||
- [ ] 复杂函数有使用示例
|
|
||||||
- [ ] 特殊情况和注意事项已标注
|
|
||||||
|
|
||||||
### 代码级别检查
|
|
||||||
- [ ] 复杂逻辑有行内注释说明
|
|
||||||
- [ ] 魔法数字有常量定义和注释
|
|
||||||
- [ ] TODO/FIXME 标记有明确的处理计划
|
|
||||||
|
|
||||||
### 质量检查
|
|
||||||
- [ ] 注释内容准确，与代码一致
|
|
||||||
- [ ] 中文表达清晰，无错别字
|
|
||||||
- [ ] 注释格式符合项目规范
|
|
||||||
|
|
||||||
## 注释工具和插件
|
|
||||||
|
|
||||||
### Godot编辑器设置
|
|
||||||
```
|
|
||||||
# 在 Godot 编辑器中设置注释快捷键
|
|
||||||
# 编辑器设置 -> 快捷键 -> 注释/取消注释: Ctrl+/
|
|
||||||
```
|
|
||||||
|
|
||||||
### 推荐的注释插件
|
|
||||||
- **GDScript Language Server** - 提供注释语法高亮
|
|
||||||
- **Code Formatter** - 自动格式化注释
|
|
||||||
- **Documentation Generator** - 自动生成API文档
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 总结
|
|
||||||
|
|
||||||
良好的注释是代码质量的重要组成部分。遵循本规范可以：
|
|
||||||
|
|
||||||
1. **提高代码可读性** - 帮助团队成员快速理解代码
|
|
||||||
2. **降低维护成本** - 减少后期修改和调试时间
|
|
||||||
3. **促进知识传承** - 保留设计思路和业务逻辑
|
|
||||||
4. **支持AI辅助开发** - 为AI提供更好的上下文信息
|
|
||||||
|
|
||||||
记住：**好的注释解释为什么，而不是做什么。**
|
|
||||||
@@ -1,406 +0,0 @@
|
|||||||
# 开发哲学与最佳实践
|
|
||||||
|
|
||||||
本文档阐述了WhaleTown项目的开发哲学和编程最佳实践，旨在指导团队创造高质量、可维护的代码。
|
|
||||||
|
|
||||||
## 🧘 开发哲学
|
|
||||||
|
|
||||||
### 核心理念
|
|
||||||
- **用户体验至上** - 每个功能都要考虑用户感受
|
|
||||||
- **代码即文档** - 代码应该自解释，清晰易懂
|
|
||||||
- **简洁胜于复杂** - 优先选择简单直接的解决方案
|
|
||||||
- **质量重于速度** - 宁可慢一点，也要做对
|
|
||||||
|
|
||||||
### 设计原则
|
|
||||||
|
|
||||||
#### 1. 流畅体验 (Juice or Death)
|
|
||||||
每个用户交互都必须有视觉反馈和动画效果：
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# ✅ 正确：为UI交互添加动画
|
|
||||||
func show_dialog() -> void:
|
|
||||||
dialog.modulate.a = 0.0
|
|
||||||
dialog.scale = Vector2(0.8, 0.8)
|
|
||||||
dialog.visible = true
|
|
||||||
|
|
||||||
var tween = create_tween()
|
|
||||||
tween.parallel().tween_property(dialog, "modulate:a", 1.0, 0.3)
|
|
||||||
tween.parallel().tween_property(dialog, "scale", Vector2.ONE, 0.3)
|
|
||||||
tween.set_ease(Tween.EASE_OUT)
|
|
||||||
tween.set_trans(Tween.TRANS_BACK)
|
|
||||||
|
|
||||||
# ❌ 错误：没有动画的生硬切换
|
|
||||||
func show_dialog() -> void:
|
|
||||||
dialog.visible = true # 突然出现，体验差
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 2. 零魔法数字 (Zero Magic Numbers)
|
|
||||||
所有数值都应该有明确的含义和来源：
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# ✅ 正确：使用导出变量或配置文件
|
|
||||||
@export var move_speed: float = 200.0
|
|
||||||
@export var jump_height: float = 400.0
|
|
||||||
@export var health_max: int = 100
|
|
||||||
|
|
||||||
# 或从配置文件加载
|
|
||||||
const CONFIG_PATH = "res://data/player_config.json"
|
|
||||||
var config_data: Dictionary
|
|
||||||
|
|
||||||
func _ready() -> void:
|
|
||||||
config_data = load_config(CONFIG_PATH)
|
|
||||||
move_speed = config_data.get("move_speed", 200.0)
|
|
||||||
|
|
||||||
# ❌ 错误：硬编码的魔法数字
|
|
||||||
func _physics_process(delta: float) -> void:
|
|
||||||
velocity.x = input_direction.x * 200 # 200是什么？
|
|
||||||
if position.y > 1000: # 1000代表什么？
|
|
||||||
respawn()
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 3. 函数单一职责
|
|
||||||
每个函数只做一件事，做好一件事：
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# ✅ 正确：职责分离
|
|
||||||
func handle_player_input() -> void:
|
|
||||||
var input_direction = get_input_direction()
|
|
||||||
apply_movement(input_direction)
|
|
||||||
check_interaction_input()
|
|
||||||
|
|
||||||
func get_input_direction() -> Vector2:
|
|
||||||
return Input.get_vector("move_left", "move_right", "move_up", "move_down")
|
|
||||||
|
|
||||||
func apply_movement(direction: Vector2) -> void:
|
|
||||||
velocity = direction * move_speed
|
|
||||||
move_and_slide()
|
|
||||||
|
|
||||||
func check_interaction_input() -> void:
|
|
||||||
if Input.is_action_just_pressed("interact"):
|
|
||||||
try_interact()
|
|
||||||
|
|
||||||
# ❌ 错误：一个函数做太多事
|
|
||||||
func handle_everything() -> void:
|
|
||||||
# 处理输入
|
|
||||||
var direction = Input.get_vector("move_left", "move_right", "move_up", "move_down")
|
|
||||||
# 处理移动
|
|
||||||
velocity = direction * move_speed
|
|
||||||
move_and_slide()
|
|
||||||
# 处理交互
|
|
||||||
if Input.is_action_just_pressed("interact"):
|
|
||||||
# 检查交互对象
|
|
||||||
var interactables = get_nearby_interactables()
|
|
||||||
# 执行交互
|
|
||||||
for obj in interactables:
|
|
||||||
obj.interact()
|
|
||||||
# 更新UI
|
|
||||||
update_health_bar()
|
|
||||||
# 播放音效
|
|
||||||
play_footstep_sound()
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 4. 隐藏复杂性
|
|
||||||
复杂的逻辑应该被封装，对外提供简洁的接口：
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# ✅ 正确：封装复杂逻辑
|
|
||||||
class_name NetworkManager
|
|
||||||
|
|
||||||
func login(username: String, password: String, callback: Callable) -> int:
|
|
||||||
return _make_request("POST", "/auth/login", {
|
|
||||||
"username": username,
|
|
||||||
"password": password
|
|
||||||
}, callback)
|
|
||||||
|
|
||||||
func _make_request(method: String, endpoint: String, data: Dictionary, callback: Callable) -> int:
|
|
||||||
# 复杂的网络请求逻辑被隐藏
|
|
||||||
var request = HTTPRequest.new()
|
|
||||||
var request_id = _generate_request_id()
|
|
||||||
|
|
||||||
# 设置请求头、处理认证、错误重试等复杂逻辑
|
|
||||||
_setup_request_headers(request)
|
|
||||||
_handle_authentication(request)
|
|
||||||
_setup_retry_logic(request, callback)
|
|
||||||
|
|
||||||
return request_id
|
|
||||||
|
|
||||||
# 使用时非常简洁
|
|
||||||
func _on_login_button_pressed() -> void:
|
|
||||||
NetworkManager.login(username_input.text, password_input.text, _on_login_response)
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📋 编码最佳实践
|
|
||||||
|
|
||||||
### 1. 类型安全
|
|
||||||
始终使用严格的类型声明：
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# ✅ 正确：明确的类型声明
|
|
||||||
var player_health: int = 100
|
|
||||||
var move_speed: float = 200.0
|
|
||||||
var player_name: String = "Player"
|
|
||||||
var inventory_items: Array[Item] = []
|
|
||||||
var config_data: Dictionary = {}
|
|
||||||
|
|
||||||
func calculate_damage(base_damage: int, multiplier: float) -> int:
|
|
||||||
return int(base_damage * multiplier)
|
|
||||||
|
|
||||||
# ❌ 错误：缺少类型信息
|
|
||||||
var health = 100 # 类型不明确
|
|
||||||
var speed = 200 # 可能是int也可能是float
|
|
||||||
|
|
||||||
func calculate_damage(base, mult): # 参数类型不明确
|
|
||||||
return base * mult # 返回类型不明确
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. 错误处理
|
|
||||||
主动处理可能的错误情况：
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# ✅ 正确：完善的错误处理
|
|
||||||
func load_save_file(file_path: String) -> Dictionary:
|
|
||||||
if not FileAccess.file_exists(file_path):
|
|
||||||
push_warning("存档文件不存在: " + file_path)
|
|
||||||
return {}
|
|
||||||
|
|
||||||
var file = FileAccess.open(file_path, FileAccess.READ)
|
|
||||||
if file == null:
|
|
||||||
push_error("无法打开存档文件: " + file_path)
|
|
||||||
return {}
|
|
||||||
|
|
||||||
var json_string = file.get_as_text()
|
|
||||||
file.close()
|
|
||||||
|
|
||||||
if json_string.is_empty():
|
|
||||||
push_warning("存档文件为空: " + file_path)
|
|
||||||
return {}
|
|
||||||
|
|
||||||
var json = JSON.new()
|
|
||||||
var parse_result = json.parse(json_string)
|
|
||||||
if parse_result != OK:
|
|
||||||
push_error("存档文件JSON格式错误: " + file_path)
|
|
||||||
return {}
|
|
||||||
|
|
||||||
return json.data
|
|
||||||
|
|
||||||
# ❌ 错误：没有错误处理
|
|
||||||
func load_save_file(file_path: String) -> Dictionary:
|
|
||||||
var file = FileAccess.open(file_path, FileAccess.READ)
|
|
||||||
var json_string = file.get_as_text()
|
|
||||||
file.close()
|
|
||||||
var json = JSON.new()
|
|
||||||
json.parse(json_string)
|
|
||||||
return json.data # 任何步骤出错都会崩溃
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. 资源管理
|
|
||||||
及时释放不需要的资源：
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# ✅ 正确：资源管理
|
|
||||||
class_name AudioManager
|
|
||||||
|
|
||||||
var audio_players: Array[AudioStreamPlayer] = []
|
|
||||||
var max_concurrent_sounds: int = 10
|
|
||||||
|
|
||||||
func play_sound(sound: AudioStream, volume: float = 0.0) -> void:
|
|
||||||
# 清理已完成的音频播放器
|
|
||||||
_cleanup_finished_players()
|
|
||||||
|
|
||||||
# 限制并发音频数量
|
|
||||||
if audio_players.size() >= max_concurrent_sounds:
|
|
||||||
_stop_oldest_player()
|
|
||||||
|
|
||||||
var player = AudioStreamPlayer.new()
|
|
||||||
add_child(player)
|
|
||||||
player.stream = sound
|
|
||||||
player.volume_db = volume
|
|
||||||
player.finished.connect(_on_audio_finished.bind(player))
|
|
||||||
player.play()
|
|
||||||
|
|
||||||
audio_players.append(player)
|
|
||||||
|
|
||||||
func _cleanup_finished_players() -> void:
|
|
||||||
audio_players = audio_players.filter(func(player): return player.playing)
|
|
||||||
|
|
||||||
func _on_audio_finished(player: AudioStreamPlayer) -> void:
|
|
||||||
audio_players.erase(player)
|
|
||||||
player.queue_free()
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. 性能优化
|
|
||||||
编写高效的代码：
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# ✅ 正确：性能优化的代码
|
|
||||||
class_name EnemyManager
|
|
||||||
|
|
||||||
var enemies: Array[Enemy] = []
|
|
||||||
var update_timer: float = 0.0
|
|
||||||
const UPDATE_INTERVAL: float = 0.1 # 每100ms更新一次
|
|
||||||
|
|
||||||
func _process(delta: float) -> void:
|
|
||||||
update_timer += delta
|
|
||||||
if update_timer >= UPDATE_INTERVAL:
|
|
||||||
_update_enemies(update_timer)
|
|
||||||
update_timer = 0.0
|
|
||||||
|
|
||||||
func _update_enemies(delta_time: float) -> void:
|
|
||||||
# 只更新屏幕附近的敌人
|
|
||||||
var camera_pos = get_viewport().get_camera_2d().global_position
|
|
||||||
var screen_size = get_viewport().get_visible_rect().size
|
|
||||||
|
|
||||||
for enemy in enemies:
|
|
||||||
if _is_enemy_near_screen(enemy, camera_pos, screen_size):
|
|
||||||
enemy.update_ai(delta_time)
|
|
||||||
|
|
||||||
func _is_enemy_near_screen(enemy: Enemy, camera_pos: Vector2, screen_size: Vector2) -> bool:
|
|
||||||
var distance = enemy.global_position.distance_to(camera_pos)
|
|
||||||
var max_distance = screen_size.length() * 0.6 # 屏幕对角线的60%
|
|
||||||
return distance <= max_distance
|
|
||||||
|
|
||||||
# ❌ 错误：性能问题
|
|
||||||
func _process(delta: float) -> void:
|
|
||||||
# 每帧更新所有敌人，无论是否可见
|
|
||||||
for enemy in enemies:
|
|
||||||
enemy.update_ai(delta) # 可能有数百个敌人
|
|
||||||
# 每帧进行复杂计算
|
|
||||||
var path = enemy.find_path_to_player()
|
|
||||||
enemy.follow_path(path)
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🎯 代码审查标准
|
|
||||||
|
|
||||||
### 审查清单
|
|
||||||
在提交代码前，请检查以下项目：
|
|
||||||
|
|
||||||
#### 功能性
|
|
||||||
- [ ] 代码实现了预期功能
|
|
||||||
- [ ] 处理了边界情况和错误情况
|
|
||||||
- [ ] 添加了必要的测试用例
|
|
||||||
|
|
||||||
#### 可读性
|
|
||||||
- [ ] 变量和函数名称清晰明确
|
|
||||||
- [ ] 代码结构逻辑清晰
|
|
||||||
- [ ] 添加了必要的注释
|
|
||||||
|
|
||||||
#### 性能
|
|
||||||
- [ ] 避免了不必要的计算
|
|
||||||
- [ ] 正确管理了资源生命周期
|
|
||||||
- [ ] 使用了合适的数据结构
|
|
||||||
|
|
||||||
#### 规范性
|
|
||||||
- [ ] 遵循了项目命名规范
|
|
||||||
- [ ] 使用了正确的类型声明
|
|
||||||
- [ ] 符合架构设计原则
|
|
||||||
|
|
||||||
### 代码示例评分
|
|
||||||
|
|
||||||
#### 优秀代码示例 (A级)
|
|
||||||
```gdscript
|
|
||||||
extends CharacterBody2D
|
|
||||||
class_name Player
|
|
||||||
|
|
||||||
## 玩家角色控制器
|
|
||||||
##
|
|
||||||
## 负责处理玩家输入、移动和基础交互
|
|
||||||
## 使用事件系统与其他组件通信
|
|
||||||
|
|
||||||
@export_group("Movement")
|
|
||||||
@export var move_speed: float = 200.0
|
|
||||||
@export var acceleration: float = 1000.0
|
|
||||||
@export var friction: float = 800.0
|
|
||||||
|
|
||||||
@export_group("Interaction")
|
|
||||||
@export var interaction_range: float = 50.0
|
|
||||||
|
|
||||||
@onready var sprite: Sprite2D = %Sprite2D
|
|
||||||
@onready var animation_player: AnimationPlayer = %AnimationPlayer
|
|
||||||
@onready var interaction_area: Area2D = %InteractionArea
|
|
||||||
|
|
||||||
var _current_interactable: Interactable = null
|
|
||||||
|
|
||||||
func _ready() -> void:
|
|
||||||
_setup_interaction_area()
|
|
||||||
_connect_signals()
|
|
||||||
|
|
||||||
func _physics_process(delta: float) -> void:
|
|
||||||
_handle_movement(delta)
|
|
||||||
|
|
||||||
func _input(event: InputEvent) -> void:
|
|
||||||
if event.is_action_pressed("interact"):
|
|
||||||
_try_interact()
|
|
||||||
|
|
||||||
func _handle_movement(delta: float) -> void:
|
|
||||||
var input_direction := _get_movement_input()
|
|
||||||
_apply_movement(input_direction, delta)
|
|
||||||
_update_animation(input_direction)
|
|
||||||
|
|
||||||
func _get_movement_input() -> Vector2:
|
|
||||||
return Input.get_vector("move_left", "move_right", "move_up", "move_down")
|
|
||||||
|
|
||||||
func _apply_movement(direction: Vector2, delta: float) -> void:
|
|
||||||
if direction != Vector2.ZERO:
|
|
||||||
velocity = velocity.move_toward(direction * move_speed, acceleration * delta)
|
|
||||||
else:
|
|
||||||
velocity = velocity.move_toward(Vector2.ZERO, friction * delta)
|
|
||||||
|
|
||||||
move_and_slide()
|
|
||||||
|
|
||||||
func _update_animation(direction: Vector2) -> void:
|
|
||||||
if direction.length() > 0.1:
|
|
||||||
animation_player.play("walk")
|
|
||||||
sprite.flip_h = direction.x < 0
|
|
||||||
else:
|
|
||||||
animation_player.play("idle")
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 需要改进的代码 (C级)
|
|
||||||
```gdscript
|
|
||||||
extends CharacterBody2D
|
|
||||||
|
|
||||||
var speed = 200
|
|
||||||
var player
|
|
||||||
var enemies = []
|
|
||||||
|
|
||||||
func _ready():
|
|
||||||
player = self
|
|
||||||
|
|
||||||
func _process(delta):
|
|
||||||
var dir = Vector2()
|
|
||||||
if Input.is_action_pressed("ui_left"):
|
|
||||||
dir.x -= 1
|
|
||||||
if Input.is_action_pressed("ui_right"):
|
|
||||||
dir.x += 1
|
|
||||||
if Input.is_action_pressed("ui_up"):
|
|
||||||
dir.y -= 1
|
|
||||||
if Input.is_action_pressed("ui_down"):
|
|
||||||
dir.y += 1
|
|
||||||
|
|
||||||
velocity = dir * speed
|
|
||||||
move_and_slide()
|
|
||||||
|
|
||||||
for enemy in enemies:
|
|
||||||
if position.distance_to(enemy.position) < 100:
|
|
||||||
print("near enemy")
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🚀 持续改进
|
|
||||||
|
|
||||||
### 重构指导原则
|
|
||||||
1. **小步快跑** - 每次只重构一小部分
|
|
||||||
2. **测试保护** - 重构前确保有测试覆盖
|
|
||||||
3. **功能不变** - 重构不改变外部行为
|
|
||||||
4. **逐步优化** - 持续改进代码质量
|
|
||||||
|
|
||||||
### 技术债务管理
|
|
||||||
```gdscript
|
|
||||||
# 使用TODO注释标记技术债务
|
|
||||||
# TODO: 重构这个函数，职责过多
|
|
||||||
# FIXME: 这里有性能问题，需要优化
|
|
||||||
# HACK: 临时解决方案，需要找到更好的方法
|
|
||||||
# NOTE: 这里的逻辑比较复杂，需要详细注释
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**记住：优秀的代码不仅能工作，更要易于理解、维护和扩展。追求代码质量是每个开发者的责任！**
|
|
||||||
@@ -1,280 +0,0 @@
|
|||||||
# 架构与通信规范
|
|
||||||
|
|
||||||
本文档定义了WhaleTown项目的架构设计原则和组件间通信规范。
|
|
||||||
|
|
||||||
## 🏛️ 架构设计原则
|
|
||||||
|
|
||||||
### 核心原则
|
|
||||||
- **"信号向上，调用向下"** - 父节点调用子节点方法，子节点发出信号通知父节点
|
|
||||||
- **高度解耦** - 通过事件系统实现组件间通信，避免直接依赖
|
|
||||||
- **分层架构** - 严格的三层架构：框架层、游戏层、界面层
|
|
||||||
- **单一职责** - 每个组件只负责一个明确的功能
|
|
||||||
|
|
||||||
### 分层架构详解
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────────────────────────┐
|
|
||||||
│ UI Layer (界面层) │
|
|
||||||
│ UI/Windows/, UI/HUD/ │
|
|
||||||
├─────────────────────────────────────┤
|
|
||||||
│ Scenes Layer (游戏层) │
|
|
||||||
│ Scenes/Maps/, Scenes/Entities/ │
|
|
||||||
├─────────────────────────────────────┤
|
|
||||||
│ _Core Layer (框架层) │
|
|
||||||
│ _Core/managers/, _Core/systems/ │
|
|
||||||
└─────────────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔄 事件系统 (EventSystem)
|
|
||||||
|
|
||||||
### 事件系统位置
|
|
||||||
- **文件路径**: `_Core/systems/EventSystem.gd`
|
|
||||||
- **自动加载**: 必须设置为AutoLoad单例
|
|
||||||
- **作用**: 全局事件总线，实现跨模块通信
|
|
||||||
|
|
||||||
### 事件命名规范
|
|
||||||
所有事件名称必须在 `_Core/EventNames.gd` 中定义：
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# _Core/EventNames.gd
|
|
||||||
class_name EventNames
|
|
||||||
|
|
||||||
# 玩家相关事件
|
|
||||||
const PLAYER_MOVED = "player_moved"
|
|
||||||
const PLAYER_HEALTH_CHANGED = "player_health_changed"
|
|
||||||
const PLAYER_DIED = "player_died"
|
|
||||||
|
|
||||||
# 交互事件
|
|
||||||
const INTERACT_PRESSED = "interact_pressed"
|
|
||||||
const NPC_TALKED = "npc_talked"
|
|
||||||
const ITEM_COLLECTED = "item_collected"
|
|
||||||
|
|
||||||
# UI事件
|
|
||||||
const UI_BUTTON_CLICKED = "ui_button_clicked"
|
|
||||||
const DIALOG_OPENED = "dialog_opened"
|
|
||||||
const DIALOG_CLOSED = "dialog_closed"
|
|
||||||
|
|
||||||
# 游戏状态事件
|
|
||||||
const GAME_PAUSED = "game_paused"
|
|
||||||
const GAME_RESUMED = "game_resumed"
|
|
||||||
const SCENE_CHANGED = "scene_changed"
|
|
||||||
```
|
|
||||||
|
|
||||||
### 事件使用方法
|
|
||||||
|
|
||||||
#### 发送事件
|
|
||||||
```gdscript
|
|
||||||
# 发送简单事件
|
|
||||||
EventSystem.emit_event(EventNames.PLAYER_MOVED)
|
|
||||||
|
|
||||||
# 发送带数据的事件
|
|
||||||
EventSystem.emit_event(EventNames.PLAYER_HEALTH_CHANGED, {
|
|
||||||
"old_health": 80,
|
|
||||||
"new_health": 60,
|
|
||||||
"damage": 20
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 监听事件
|
|
||||||
```gdscript
|
|
||||||
func _ready() -> void:
|
|
||||||
# 连接事件监听
|
|
||||||
EventSystem.connect_event(EventNames.PLAYER_DIED, _on_player_died)
|
|
||||||
EventSystem.connect_event(EventNames.ITEM_COLLECTED, _on_item_collected)
|
|
||||||
|
|
||||||
func _on_player_died(data: Dictionary = {}) -> void:
|
|
||||||
print("玩家死亡，游戏结束")
|
|
||||||
# 处理玩家死亡逻辑
|
|
||||||
|
|
||||||
func _on_item_collected(data: Dictionary) -> void:
|
|
||||||
var item_name = data.get("item_name", "未知物品")
|
|
||||||
print("收集到物品: ", item_name)
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 断开事件监听
|
|
||||||
```gdscript
|
|
||||||
func _exit_tree() -> void:
|
|
||||||
# 节点销毁时断开事件监听
|
|
||||||
EventSystem.disconnect_event(EventNames.PLAYER_DIED, _on_player_died)
|
|
||||||
EventSystem.disconnect_event(EventNames.ITEM_COLLECTED, _on_item_collected)
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🎯 单例管理器
|
|
||||||
|
|
||||||
### 允许的自动加载单例
|
|
||||||
项目中允许以下五个核心单例：
|
|
||||||
|
|
||||||
1. **GameManager** - 游戏状态管理
|
|
||||||
- 路径: `_Core/managers/GameManager.gd`
|
|
||||||
- 职责: 游戏状态、场景数据、全局配置
|
|
||||||
|
|
||||||
2. **SceneManager** - 场景管理
|
|
||||||
- 路径: `_Core/managers/SceneManager.gd`
|
|
||||||
- 职责: 场景切换、场景生命周期
|
|
||||||
|
|
||||||
3. **EventSystem** - 事件系统
|
|
||||||
- 路径: `_Core/systems/EventSystem.gd`
|
|
||||||
- 职责: 全局事件通信
|
|
||||||
|
|
||||||
4. **NetworkManager** - 网络管理
|
|
||||||
- 路径: `_Core/managers/NetworkManager.gd`
|
|
||||||
- 职责: HTTP请求、API调用、网络状态管理
|
|
||||||
|
|
||||||
5. **ResponseHandler** - 响应处理
|
|
||||||
- 路径: `_Core/managers/ResponseHandler.gd`
|
|
||||||
- 职责: 统一响应处理、错误处理、用户反馈
|
|
||||||
|
|
||||||
### 单例使用规范
|
|
||||||
```gdscript
|
|
||||||
# ✅ 正确：高层组件可以访问单例
|
|
||||||
func _ready() -> void:
|
|
||||||
var current_scene = SceneManager.get_current_scene()
|
|
||||||
var game_state = GameManager.get_game_state()
|
|
||||||
|
|
||||||
# ❌ 错误：底层实体不应直接访问GameManager
|
|
||||||
# 在Player.gd或NPC.gd中避免这样做：
|
|
||||||
func _ready() -> void:
|
|
||||||
GameManager.register_player(self) # 不推荐
|
|
||||||
|
|
||||||
# ✅ 正确：使用事件系统
|
|
||||||
func _ready() -> void:
|
|
||||||
EventSystem.emit_event(EventNames.PLAYER_SPAWNED, {"player": self})
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔗 组件通信模式
|
|
||||||
|
|
||||||
### 1. 父子通信
|
|
||||||
```gdscript
|
|
||||||
# 父节点调用子节点方法（向下调用）
|
|
||||||
func _on_button_pressed() -> void:
|
|
||||||
child_component.activate()
|
|
||||||
child_component.set_data(some_data)
|
|
||||||
|
|
||||||
# 子节点发出信号通知父节点（向上信号）
|
|
||||||
# 在子节点中：
|
|
||||||
signal component_activated(data: Dictionary)
|
|
||||||
signal component_finished()
|
|
||||||
|
|
||||||
func _some_action() -> void:
|
|
||||||
component_activated.emit({"status": "active"})
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. 兄弟组件通信
|
|
||||||
```gdscript
|
|
||||||
# 通过共同的父节点中转
|
|
||||||
# 或使用事件系统
|
|
||||||
func _notify_sibling() -> void:
|
|
||||||
EventSystem.emit_event(EventNames.COMPONENT_MESSAGE, {
|
|
||||||
"sender": self,
|
|
||||||
"message": "Hello sibling!"
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. 跨场景通信
|
|
||||||
```gdscript
|
|
||||||
# 使用事件系统进行跨场景通信
|
|
||||||
func _change_scene_with_data() -> void:
|
|
||||||
EventSystem.emit_event(EventNames.SCENE_DATA_TRANSFER, {
|
|
||||||
"target_scene": "battle_scene",
|
|
||||||
"player_data": player_data
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🚫 禁止的通信模式
|
|
||||||
|
|
||||||
### 1. 直接节点引用
|
|
||||||
```gdscript
|
|
||||||
# ❌ 错误：直接获取其他场景的节点
|
|
||||||
func _bad_communication() -> void:
|
|
||||||
var other_scene = get_tree().get_first_node_in_group("other_scene")
|
|
||||||
other_scene.do_something() # 强耦合，难以维护
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. 全局变量传递
|
|
||||||
```gdscript
|
|
||||||
# ❌ 错误：使用全局变量传递状态
|
|
||||||
# 在autoload中：
|
|
||||||
var global_player_data = {} # 避免这种做法
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. 循环依赖
|
|
||||||
```gdscript
|
|
||||||
# ❌ 错误：A依赖B，B又依赖A
|
|
||||||
# ComponentA.gd
|
|
||||||
var component_b: ComponentB
|
|
||||||
|
|
||||||
# ComponentB.gd
|
|
||||||
var component_a: ComponentA # 循环依赖
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📋 通信最佳实践
|
|
||||||
|
|
||||||
### 1. 事件数据结构
|
|
||||||
```gdscript
|
|
||||||
# 使用结构化的事件数据
|
|
||||||
EventSystem.emit_event(EventNames.PLAYER_ATTACK, {
|
|
||||||
"attacker": self,
|
|
||||||
"target": target_enemy,
|
|
||||||
"damage": damage_amount,
|
|
||||||
"attack_type": "melee",
|
|
||||||
"timestamp": Time.get_time_dict_from_system()
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. 错误处理
|
|
||||||
```gdscript
|
|
||||||
func _on_event_received(data: Dictionary) -> void:
|
|
||||||
# 验证数据完整性
|
|
||||||
if not data.has("required_field"):
|
|
||||||
push_error("事件数据缺少必需字段: required_field")
|
|
||||||
return
|
|
||||||
|
|
||||||
# 安全地获取数据
|
|
||||||
var value = data.get("optional_field", default_value)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. 性能考虑
|
|
||||||
```gdscript
|
|
||||||
# 避免在_process中频繁发送事件
|
|
||||||
var last_position: Vector2
|
|
||||||
func _process(delta: float) -> void:
|
|
||||||
if global_position.distance_to(last_position) > 10.0:
|
|
||||||
EventSystem.emit_event(EventNames.PLAYER_MOVED, {
|
|
||||||
"position": global_position
|
|
||||||
})
|
|
||||||
last_position = global_position
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🧪 测试通信系统
|
|
||||||
|
|
||||||
### 单元测试示例
|
|
||||||
```gdscript
|
|
||||||
extends GutTest
|
|
||||||
|
|
||||||
func test_event_emission():
|
|
||||||
# 监听事件
|
|
||||||
watch_signals(EventSystem)
|
|
||||||
|
|
||||||
# 发送事件
|
|
||||||
EventSystem.emit_event(EventNames.PLAYER_MOVED, {"x": 100, "y": 200})
|
|
||||||
|
|
||||||
# 验证事件发送
|
|
||||||
assert_signal_emitted(EventSystem, "event_raised")
|
|
||||||
|
|
||||||
func test_event_data():
|
|
||||||
var received_data: Dictionary
|
|
||||||
|
|
||||||
# 连接事件监听
|
|
||||||
EventSystem.connect_event(EventNames.TEST_EVENT, func(data): received_data = data)
|
|
||||||
|
|
||||||
# 发送测试数据
|
|
||||||
var test_data = {"test": "value"}
|
|
||||||
EventSystem.emit_event(EventNames.TEST_EVENT, test_data)
|
|
||||||
|
|
||||||
# 验证数据传递
|
|
||||||
assert_eq(received_data, test_data)
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**记住：良好的架构设计是项目成功的基石！遵循这些通信规范可以确保代码的可维护性和扩展性。**
|
|
||||||
@@ -1,963 +0,0 @@
|
|||||||
# Pixel Game Server API 文档
|
|
||||||
|
|
||||||
**版本**: 1.1.1
|
|
||||||
**更新时间**: 2025-12-25
|
|
||||||
|
|
||||||
## 🚨 后端对前端的提示与注意点
|
|
||||||
|
|
||||||
### 重要提醒
|
|
||||||
1. **邮箱冲突检测**: 发送邮箱验证码前会检查邮箱是否已被注册，已注册邮箱返回409状态码
|
|
||||||
2. **HTTP状态码**: 所有接口根据业务结果返回正确状态码（409冲突、400参数错误、401认证失败等）
|
|
||||||
3. **验证码有效期**: 所有验证码有效期为5分钟
|
|
||||||
4. **频率限制**: 验证码发送限制1次/分钟，注册限制10次/5分钟
|
|
||||||
5. **测试模式**: 开发环境下邮件服务返回206状态码，验证码在响应中返回
|
|
||||||
6. **冷却时间自动清除**: 注册、密码重置、验证码登录成功后会自动清除验证码冷却时间，方便后续操作
|
|
||||||
|
|
||||||
### 错误处理规范
|
|
||||||
- **409 Conflict**: 资源冲突（用户名、邮箱已存在）
|
|
||||||
- **400 Bad Request**: 参数错误、验证码错误
|
|
||||||
- **401 Unauthorized**: 认证失败、密码错误
|
|
||||||
- **429 Too Many Requests**: 频率限制
|
|
||||||
- **206 Partial Content**: 测试模式（验证码未真实发送）
|
|
||||||
|
|
||||||
### 前端开发建议
|
|
||||||
1. 根据HTTP状态码进行错误处理，不要只依赖success字段
|
|
||||||
2. 邮箱注册流程：先发送验证码 → 检查409冲突 → 使用验证码注册
|
|
||||||
3. 测试模式下验证码在响应中返回，生产环境需用户查收邮件
|
|
||||||
4. 实现重试机制处理429频率限制错误
|
|
||||||
5. 注册/重置密码成功后，验证码冷却时间会自动清除，可立即发送新验证码
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📋 API接口列表
|
|
||||||
|
|
||||||
### 应用状态接口
|
|
||||||
- `GET /` - 获取应用状态
|
|
||||||
|
|
||||||
### 用户认证接口
|
|
||||||
- `POST /auth/login` - 用户登录
|
|
||||||
- `POST /auth/register` - 用户注册
|
|
||||||
- `POST /auth/github` - GitHub OAuth登录
|
|
||||||
- `POST /auth/verification-code-login` - 验证码登录
|
|
||||||
- `POST /auth/send-login-verification-code` - 发送登录验证码
|
|
||||||
- `POST /auth/forgot-password` - 发送密码重置验证码
|
|
||||||
- `POST /auth/reset-password` - 重置密码
|
|
||||||
- `PUT /auth/change-password` - 修改密码
|
|
||||||
- `POST /auth/send-email-verification` - 发送邮箱验证码
|
|
||||||
- `POST /auth/verify-email` - 验证邮箱验证码
|
|
||||||
- `POST /auth/resend-email-verification` - 重新发送邮箱验证码
|
|
||||||
|
|
||||||
### 管理员接口
|
|
||||||
- `POST /admin/auth/login` - 管理员登录
|
|
||||||
- `GET /admin/users` - 获取用户列表
|
|
||||||
- `GET /admin/users/:id` - 获取用户详情
|
|
||||||
- `POST /admin/users/:id/reset-password` - 管理员重置用户密码
|
|
||||||
- `GET /admin/logs/runtime` - 获取运行时日志
|
|
||||||
- `GET /admin/logs/archive` - 获取归档日志
|
|
||||||
|
|
||||||
### 用户管理接口
|
|
||||||
- `PUT /admin/users/:id/status` - 修改用户状态
|
|
||||||
- `POST /admin/users/batch-status` - 批量修改用户状态
|
|
||||||
- `GET /admin/users/status-stats` - 获取用户状态统计
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🧪 API接口详细说明与测试用例
|
|
||||||
### 1. 获取应用状态
|
|
||||||
|
|
||||||
**接口**: `GET /`
|
|
||||||
|
|
||||||
#### 成功响应 (200)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"service": "Pixel Game Server",
|
|
||||||
"version": "1.1.1",
|
|
||||||
"status": "running",
|
|
||||||
"timestamp": "2025-12-25T10:27:44.352Z",
|
|
||||||
"uptime": 8,
|
|
||||||
"environment": "development",
|
|
||||||
"storage_mode": "database"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 2. 用户登录
|
|
||||||
|
|
||||||
**接口**: `POST /auth/login`
|
|
||||||
|
|
||||||
#### 请求体
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"identifier": "testuser",
|
|
||||||
"password": "password123"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 成功响应 (200)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"user": {
|
|
||||||
"id": "1",
|
|
||||||
"username": "testuser",
|
|
||||||
"nickname": "测试用户",
|
|
||||||
"email": "test@example.com",
|
|
||||||
"phone": null,
|
|
||||||
"avatar_url": null,
|
|
||||||
"role": 1,
|
|
||||||
"created_at": "2025-12-17T10:00:00.000Z"
|
|
||||||
},
|
|
||||||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
|
||||||
"is_new_user": false,
|
|
||||||
"message": "登录成功"
|
|
||||||
},
|
|
||||||
"message": "登录成功"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 认证失败响应 (401)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "用户名、邮箱或手机号不存在",
|
|
||||||
"error_code": "LOGIN_FAILED"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 密码错误响应 (401)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "密码错误",
|
|
||||||
"error_code": "LOGIN_FAILED"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 3. 用户注册
|
|
||||||
|
|
||||||
**接口**: `POST /auth/register`
|
|
||||||
|
|
||||||
#### 请求体（无邮箱）
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"username": "newuser",
|
|
||||||
"password": "password123",
|
|
||||||
"nickname": "新用户"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 请求体（带邮箱验证）
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"username": "newuser",
|
|
||||||
"password": "password123",
|
|
||||||
"nickname": "新用户",
|
|
||||||
"email": "newuser@example.com",
|
|
||||||
"email_verification_code": "123456"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 成功响应 (201)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"user": {
|
|
||||||
"id": "2",
|
|
||||||
"username": "newuser",
|
|
||||||
"nickname": "新用户",
|
|
||||||
"email": "newuser@example.com",
|
|
||||||
"phone": null,
|
|
||||||
"avatar_url": null,
|
|
||||||
"role": 1,
|
|
||||||
"created_at": "2025-12-17T10:00:00.000Z"
|
|
||||||
},
|
|
||||||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
|
||||||
"is_new_user": true,
|
|
||||||
"message": "注册成功"
|
|
||||||
},
|
|
||||||
"message": "注册成功"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 用户名冲突响应 (409)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "用户名已存在",
|
|
||||||
"error_code": "REGISTER_FAILED"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 邮箱冲突响应 (409)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "邮箱已存在",
|
|
||||||
"error_code": "REGISTER_FAILED"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 验证码错误响应 (400)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "验证码不存在或已过期",
|
|
||||||
"error_code": "REGISTER_FAILED"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 4. 发送邮箱验证码
|
|
||||||
|
|
||||||
**接口**: `POST /auth/send-email-verification`
|
|
||||||
|
|
||||||
#### 请求体
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"email": "test@example.com"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 成功响应 (200) - 生产环境
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"is_test_mode": false
|
|
||||||
},
|
|
||||||
"message": "验证码已发送，请查收邮件"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 测试模式响应 (206) - 开发环境
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"data": {
|
|
||||||
"verification_code": "123456",
|
|
||||||
"is_test_mode": true
|
|
||||||
},
|
|
||||||
"message": "⚠️ 测试模式：验证码已生成但未真实发送。请在控制台查看验证码，或配置邮件服务以启用真实发送。",
|
|
||||||
"error_code": "TEST_MODE_ONLY"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 邮箱冲突响应 (409)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "邮箱已被注册，请使用其他邮箱或直接登录",
|
|
||||||
"error_code": "SEND_EMAIL_VERIFICATION_FAILED"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 频率限制响应 (429)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "验证码发送过于频繁，请1分钟后再试",
|
|
||||||
"error_code": "TOO_MANY_REQUESTS",
|
|
||||||
"throttle_info": {
|
|
||||||
"limit": 1,
|
|
||||||
"window_seconds": 60,
|
|
||||||
"current_requests": 1,
|
|
||||||
"reset_time": "2025-12-25T10:07:37.056Z"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
---
|
|
||||||
|
|
||||||
### 5. 验证码登录
|
|
||||||
|
|
||||||
**接口**: `POST /auth/verification-code-login`
|
|
||||||
|
|
||||||
#### 请求体
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"identifier": "test@example.com",
|
|
||||||
"verification_code": "123456"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 成功响应 (200)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"user": {
|
|
||||||
"id": "1",
|
|
||||||
"username": "testuser",
|
|
||||||
"nickname": "测试用户",
|
|
||||||
"email": "test@example.com",
|
|
||||||
"phone": null,
|
|
||||||
"avatar_url": null,
|
|
||||||
"role": 1,
|
|
||||||
"created_at": "2025-12-17T10:00:00.000Z"
|
|
||||||
},
|
|
||||||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
|
||||||
"is_new_user": false,
|
|
||||||
"message": "验证码登录成功"
|
|
||||||
},
|
|
||||||
"message": "验证码登录成功"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 验证码错误响应 (401)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "验证码验证失败",
|
|
||||||
"error_code": "VERIFICATION_CODE_LOGIN_FAILED"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 用户不存在响应 (404)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "用户不存在，请先注册账户",
|
|
||||||
"error_code": "VERIFICATION_CODE_LOGIN_FAILED"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 6. 发送登录验证码
|
|
||||||
|
|
||||||
**接口**: `POST /auth/send-login-verification-code`
|
|
||||||
|
|
||||||
#### 请求体
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"identifier": "test@example.com"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 成功响应 (200) - 生产环境
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"is_test_mode": false
|
|
||||||
},
|
|
||||||
"message": "验证码已发送，请查收"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 测试模式响应 (206) - 开发环境
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"data": {
|
|
||||||
"verification_code": "654321",
|
|
||||||
"is_test_mode": true
|
|
||||||
},
|
|
||||||
"message": "⚠️ 测试模式：验证码已生成但未真实发送。请在控制台查看验证码，或配置邮件服务以启用真实发送。",
|
|
||||||
"error_code": "TEST_MODE_ONLY"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 用户不存在响应 (404)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "用户不存在",
|
|
||||||
"error_code": "SEND_LOGIN_CODE_FAILED"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 7. 发送密码重置验证码
|
|
||||||
|
|
||||||
**接口**: `POST /auth/forgot-password`
|
|
||||||
|
|
||||||
#### 请求体
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"identifier": "test@example.com"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 成功响应 (200) - 生产环境
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"is_test_mode": false
|
|
||||||
},
|
|
||||||
"message": "验证码已发送，请查收"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 测试模式响应 (206) - 开发环境
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"data": {
|
|
||||||
"verification_code": "789012",
|
|
||||||
"is_test_mode": true
|
|
||||||
},
|
|
||||||
"message": "⚠️ 测试模式：验证码已生成但未真实发送。请在控制台查看验证码，或配置邮件服务以启用真实发送。",
|
|
||||||
"error_code": "TEST_MODE_ONLY"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 用户不存在响应 (404)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "用户不存在",
|
|
||||||
"error_code": "SEND_CODE_FAILED"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 8. 重置密码
|
|
||||||
|
|
||||||
**接口**: `POST /auth/reset-password`
|
|
||||||
|
|
||||||
#### 请求体
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"identifier": "test@example.com",
|
|
||||||
"verification_code": "789012",
|
|
||||||
"new_password": "newpassword123"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 成功响应 (200)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"message": "密码重置成功"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 验证码错误响应 (400)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "验证码验证失败",
|
|
||||||
"error_code": "RESET_PASSWORD_FAILED"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 9. 修改密码
|
|
||||||
|
|
||||||
**接口**: `PUT /auth/change-password`
|
|
||||||
|
|
||||||
#### 请求体
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"user_id": "1",
|
|
||||||
"old_password": "oldpassword123",
|
|
||||||
"new_password": "newpassword123"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 成功响应 (200)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"message": "密码修改成功"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 旧密码错误响应 (401)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "旧密码错误",
|
|
||||||
"error_code": "CHANGE_PASSWORD_FAILED"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
---
|
|
||||||
|
|
||||||
### 10. GitHub OAuth登录
|
|
||||||
|
|
||||||
**接口**: `POST /auth/github`
|
|
||||||
|
|
||||||
#### 请求体
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"github_id": "12345678",
|
|
||||||
"username": "octocat",
|
|
||||||
"nickname": "The Octocat",
|
|
||||||
"email": "octocat@github.com",
|
|
||||||
"avatar_url": "https://github.com/images/error/octocat_happy.gif"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 成功响应 (200) - 已存在用户
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"user": {
|
|
||||||
"id": "3",
|
|
||||||
"username": "octocat",
|
|
||||||
"nickname": "The Octocat",
|
|
||||||
"email": "octocat@github.com",
|
|
||||||
"phone": null,
|
|
||||||
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
|
|
||||||
"role": 1,
|
|
||||||
"created_at": "2025-12-17T10:00:00.000Z"
|
|
||||||
},
|
|
||||||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
|
||||||
"is_new_user": false,
|
|
||||||
"message": "GitHub登录成功"
|
|
||||||
},
|
|
||||||
"message": "GitHub登录成功"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 成功响应 (200) - 新用户注册
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"user": {
|
|
||||||
"id": "4",
|
|
||||||
"username": "octocat_1",
|
|
||||||
"nickname": "The Octocat",
|
|
||||||
"email": "octocat@github.com",
|
|
||||||
"phone": null,
|
|
||||||
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
|
|
||||||
"role": 1,
|
|
||||||
"created_at": "2025-12-17T10:00:00.000Z"
|
|
||||||
},
|
|
||||||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
|
||||||
"is_new_user": true,
|
|
||||||
"message": "GitHub账户绑定成功"
|
|
||||||
},
|
|
||||||
"message": "GitHub账户绑定成功"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 11. 验证邮箱验证码
|
|
||||||
|
|
||||||
**接口**: `POST /auth/verify-email`
|
|
||||||
|
|
||||||
#### 请求体
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"email": "test@example.com",
|
|
||||||
"verification_code": "123456"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 成功响应 (200)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"message": "邮箱验证成功"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 验证码错误响应 (400)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "验证码错误",
|
|
||||||
"error_code": "EMAIL_VERIFICATION_FAILED"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 12. 重新发送邮箱验证码
|
|
||||||
|
|
||||||
**接口**: `POST /auth/resend-email-verification`
|
|
||||||
|
|
||||||
#### 请求体
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"email": "test@example.com"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 成功响应 (200) - 生产环境
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"is_test_mode": false
|
|
||||||
},
|
|
||||||
"message": "验证码已重新发送，请查收邮件"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 测试模式响应 (206) - 开发环境
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"data": {
|
|
||||||
"verification_code": "456789",
|
|
||||||
"is_test_mode": true
|
|
||||||
},
|
|
||||||
"message": "⚠️ 测试模式：验证码已生成但未真实发送。请在控制台查看验证码，或配置邮件服务以启用真实发送。",
|
|
||||||
"error_code": "TEST_MODE_ONLY"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 邮箱已验证响应 (400)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "邮箱已验证，无需重复验证",
|
|
||||||
"error_code": "RESEND_EMAIL_VERIFICATION_FAILED"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 13. 管理员登录
|
|
||||||
|
|
||||||
**接口**: `POST /admin/auth/login`
|
|
||||||
|
|
||||||
#### 请求体
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"username": "admin",
|
|
||||||
"password": "Admin123456"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 成功响应 (200)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"admin": {
|
|
||||||
"id": "1",
|
|
||||||
"username": "admin",
|
|
||||||
"nickname": "管理员",
|
|
||||||
"role": 0
|
|
||||||
},
|
|
||||||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
|
||||||
"expires_in": 28800,
|
|
||||||
"message": "管理员登录成功"
|
|
||||||
},
|
|
||||||
"message": "管理员登录成功"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 认证失败响应 (401)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "用户名或密码错误",
|
|
||||||
"error_code": "ADMIN_LOGIN_FAILED"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 权限不足响应 (403)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "权限不足，需要管理员权限",
|
|
||||||
"error_code": "ADMIN_LOGIN_FAILED"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
---
|
|
||||||
|
|
||||||
### 14. 获取用户列表
|
|
||||||
|
|
||||||
**接口**: `GET /admin/users`
|
|
||||||
|
|
||||||
#### 查询参数
|
|
||||||
- `page`: 页码（可选，默认1）
|
|
||||||
- `limit`: 每页数量（可选，默认10）
|
|
||||||
- `status`: 用户状态筛选（可选）
|
|
||||||
|
|
||||||
#### 成功响应 (200)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"users": [
|
|
||||||
{
|
|
||||||
"id": "1",
|
|
||||||
"username": "testuser",
|
|
||||||
"nickname": "测试用户",
|
|
||||||
"email": "test@example.com",
|
|
||||||
"phone": null,
|
|
||||||
"role": 1,
|
|
||||||
"status": "active",
|
|
||||||
"email_verified": true,
|
|
||||||
"created_at": "2025-12-17T10:00:00.000Z",
|
|
||||||
"updated_at": "2025-12-17T10:00:00.000Z"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"pagination": {
|
|
||||||
"page": 1,
|
|
||||||
"limit": 10,
|
|
||||||
"total": 1,
|
|
||||||
"pages": 1
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"message": "用户列表获取成功"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 15. 获取用户详情
|
|
||||||
|
|
||||||
**接口**: `GET /admin/users/:id`
|
|
||||||
|
|
||||||
#### 成功响应 (200)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"user": {
|
|
||||||
"id": "1",
|
|
||||||
"username": "testuser",
|
|
||||||
"nickname": "测试用户",
|
|
||||||
"email": "test@example.com",
|
|
||||||
"phone": null,
|
|
||||||
"role": 1,
|
|
||||||
"status": "active",
|
|
||||||
"email_verified": true,
|
|
||||||
"github_id": null,
|
|
||||||
"avatar_url": null,
|
|
||||||
"created_at": "2025-12-17T10:00:00.000Z",
|
|
||||||
"updated_at": "2025-12-17T10:00:00.000Z"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"message": "用户详情获取成功"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 用户不存在响应 (404)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "用户不存在",
|
|
||||||
"error_code": "USER_NOT_FOUND"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 16. 管理员重置用户密码
|
|
||||||
|
|
||||||
**接口**: `POST /admin/users/:id/reset-password`
|
|
||||||
|
|
||||||
#### 请求体
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"new_password": "newpassword123"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 成功响应 (200)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"message": "用户密码重置成功"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 用户不存在响应 (404)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "用户不存在",
|
|
||||||
"error_code": "USER_NOT_FOUND"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 17. 修改用户状态
|
|
||||||
|
|
||||||
**接口**: `PUT /admin/users/:id/status`
|
|
||||||
|
|
||||||
#### 请求体
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"status": "locked",
|
|
||||||
"reason": "违规操作"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 成功响应 (200)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"user": {
|
|
||||||
"id": "1",
|
|
||||||
"username": "testuser",
|
|
||||||
"status": "locked",
|
|
||||||
"updated_at": "2025-12-17T10:00:00.000Z"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"message": "用户状态修改成功"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 状态值无效响应 (400)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"message": "无效的用户状态值",
|
|
||||||
"error_code": "USER_STATUS_UPDATE_FAILED"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 18. 批量修改用户状态
|
|
||||||
|
|
||||||
**接口**: `POST /admin/users/batch-status`
|
|
||||||
|
|
||||||
#### 请求体
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"user_ids": ["1", "2", "3"],
|
|
||||||
"status": "active",
|
|
||||||
"reason": "批量激活"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 成功响应 (200)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"updated_count": 3,
|
|
||||||
"failed_count": 0,
|
|
||||||
"results": [
|
|
||||||
{
|
|
||||||
"user_id": "1",
|
|
||||||
"success": true,
|
|
||||||
"new_status": "active"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"user_id": "2",
|
|
||||||
"success": true,
|
|
||||||
"new_status": "active"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"user_id": "3",
|
|
||||||
"success": true,
|
|
||||||
"new_status": "active"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
},
|
|
||||||
"message": "批量状态修改完成"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 19. 获取用户状态统计
|
|
||||||
|
|
||||||
**接口**: `GET /admin/users/status-stats`
|
|
||||||
|
|
||||||
#### 成功响应 (200)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"stats": {
|
|
||||||
"active": 15,
|
|
||||||
"inactive": 3,
|
|
||||||
"locked": 2,
|
|
||||||
"banned": 1,
|
|
||||||
"deleted": 0,
|
|
||||||
"pending": 5
|
|
||||||
},
|
|
||||||
"total": 26
|
|
||||||
},
|
|
||||||
"message": "用户状态统计获取成功"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 20. 获取运行时日志
|
|
||||||
|
|
||||||
**接口**: `GET /admin/logs/runtime`
|
|
||||||
|
|
||||||
#### 查询参数
|
|
||||||
- `lines`: 日志行数（可选，默认100）
|
|
||||||
- `level`: 日志级别（可选）
|
|
||||||
|
|
||||||
#### 成功响应 (200)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"logs": [
|
|
||||||
"[2025-12-25 18:27:35] LOG [NestApplication] Nest application successfully started",
|
|
||||||
"[2025-12-25 18:27:35] LOG [RouterExplorer] Mapped {/, GET} route"
|
|
||||||
],
|
|
||||||
"total_lines": 2,
|
|
||||||
"timestamp": "2025-12-25T10:27:44.352Z"
|
|
||||||
},
|
|
||||||
"message": "运行时日志获取成功"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 21. 获取归档日志
|
|
||||||
|
|
||||||
**接口**: `GET /admin/logs/archive`
|
|
||||||
|
|
||||||
#### 查询参数
|
|
||||||
- `date`: 日期（YYYY-MM-DD格式，可选）
|
|
||||||
- `download`: 是否下载（可选）
|
|
||||||
|
|
||||||
#### 成功响应 (200)
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"files": [
|
|
||||||
{
|
|
||||||
"filename": "app-2025-12-24.log",
|
|
||||||
"size": 1024,
|
|
||||||
"created_at": "2025-12-24T00:00:00.000Z"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"total_files": 1
|
|
||||||
},
|
|
||||||
"message": "归档日志列表获取成功"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📊 版本更新记录
|
|
||||||
|
|
||||||
### v1.1.2 (2025-12-25)
|
|
||||||
- **验证码冷却优化**: 注册、密码重置、验证码登录成功后自动清除验证码冷却时间
|
|
||||||
- **用户体验提升**: 成功操作后可立即发送新的验证码，无需等待冷却时间
|
|
||||||
- **代码健壮性**: 冷却时间清除失败不影响主要业务流程
|
|
||||||
|
|
||||||
### v1.1.1 (2025-12-25)
|
|
||||||
- **邮箱冲突检测优化**: 发送邮箱验证码前检查邮箱是否已被注册
|
|
||||||
- **用户体验提升**: 避免向已注册邮箱发送无用验证码
|
|
||||||
- **错误处理改进**: 返回409 Conflict状态码和明确错误信息
|
|
||||||
|
|
||||||
### v1.1.0 (2025-12-25)
|
|
||||||
- **新增验证码登录功能**: 支持邮箱验证码登录
|
|
||||||
- **HTTP状态码修复**: 所有接口返回正确的业务状态码
|
|
||||||
- **完善错误处理**: 统一错误响应格式和错误代码
|
|
||||||
@@ -1,120 +0,0 @@
|
|||||||
# 🔧 技术实现
|
|
||||||
|
|
||||||
> **适用人群**: 正在开发功能的程序员
|
|
||||||
> **使用时机**: 具体功能开发时
|
|
||||||
|
|
||||||
这个目录包含了具体的技术实现指导，帮助开发者快速实现各种游戏功能和系统集成。
|
|
||||||
|
|
||||||
## 📋 实现指南
|
|
||||||
|
|
||||||
### 核心实现 🎮
|
|
||||||
**[实现细节规范.md](实现细节规范.md)**
|
|
||||||
- 玩家角色实现标准
|
|
||||||
- NPC交互系统实现
|
|
||||||
- TileMap图层配置规范
|
|
||||||
- 交互物品实现模板
|
|
||||||
- 性能优化要求
|
|
||||||
|
|
||||||
### 网络集成 🌐
|
|
||||||
**[API接口文档.md](API接口文档.md)**
|
|
||||||
- 完整的后端API接口说明
|
|
||||||
- 请求格式和响应格式
|
|
||||||
- 错误码和处理方式
|
|
||||||
- 认证和权限管理
|
|
||||||
|
|
||||||
**[网络管理器设置.md](网络管理器设置.md)**
|
|
||||||
- NetworkManager配置方法
|
|
||||||
- 网络请求封装使用
|
|
||||||
- 错误处理机制
|
|
||||||
- 响应数据处理
|
|
||||||
|
|
||||||
### 质量保证 🧪
|
|
||||||
**[测试指南.md](测试指南.md)**
|
|
||||||
- API接口测试方法
|
|
||||||
- Python测试脚本使用
|
|
||||||
- Godot内置测试
|
|
||||||
- 测试用例编写
|
|
||||||
|
|
||||||
## 🎯 开发流程
|
|
||||||
|
|
||||||
### 功能开发标准流程
|
|
||||||
1. **需求分析** - 明确功能需求和技术方案
|
|
||||||
2. **架构设计** - 参考实现细节规范设计架构
|
|
||||||
3. **编码实现** - 按照规范编写代码
|
|
||||||
4. **接口集成** - 使用API文档进行后端集成
|
|
||||||
5. **功能测试** - 使用测试指南验证功能
|
|
||||||
6. **代码审查** - 检查规范遵循情况
|
|
||||||
|
|
||||||
### 常见开发场景
|
|
||||||
|
|
||||||
#### 🎮 实现新的游戏角色
|
|
||||||
1. 阅读 [实现细节规范.md](实现细节规范.md) 中的角色实现部分
|
|
||||||
2. 使用提供的代码模板创建角色
|
|
||||||
3. 配置相机和交互系统
|
|
||||||
4. 测试移动和交互功能
|
|
||||||
|
|
||||||
#### 🌐 集成新的API接口
|
|
||||||
1. 查看 [API接口文档.md](API接口文档.md) 了解接口规范
|
|
||||||
2. 使用 [网络管理器设置.md](网络管理器设置.md) 配置网络请求
|
|
||||||
3. 实现数据处理和错误处理
|
|
||||||
4. 使用 [测试指南.md](测试指南.md) 验证接口功能
|
|
||||||
|
|
||||||
#### 🗺️ 创建新的游戏场景
|
|
||||||
1. 参考 [实现细节规范.md](实现细节规范.md) 中的TileMap配置
|
|
||||||
2. 设置正确的图层结构和碰撞检测
|
|
||||||
3. 配置相机边界和Y排序
|
|
||||||
4. 添加交互物品和NPC
|
|
||||||
|
|
||||||
## 🔍 问题排查
|
|
||||||
|
|
||||||
### 常见问题类型
|
|
||||||
|
|
||||||
#### 网络相关问题
|
|
||||||
- **API调用失败** → 检查 [API接口文档.md](API接口文档.md) 中的接口格式
|
|
||||||
- **网络超时** → 参考 [网络管理器设置.md](网络管理器设置.md) 的超时配置
|
|
||||||
- **数据解析错误** → 查看响应格式和错误处理
|
|
||||||
|
|
||||||
#### 游戏对象问题
|
|
||||||
- **角色移动异常** → 检查 [实现细节规范.md](实现细节规范.md) 中的移动实现
|
|
||||||
- **交互不响应** → 验证InteractionArea配置和事件系统
|
|
||||||
- **相机边界错误** → 检查TileMap边界计算
|
|
||||||
|
|
||||||
#### 性能问题
|
|
||||||
- **帧率下降** → 参考性能优化要求
|
|
||||||
- **内存泄漏** → 检查资源管理和对象生命周期
|
|
||||||
|
|
||||||
### 调试技巧
|
|
||||||
1. **使用Godot调试器** - 设置断点调试代码逻辑
|
|
||||||
2. **查看控制台输出** - 关注错误和警告信息
|
|
||||||
3. **使用测试脚本** - 编写简单测试验证功能
|
|
||||||
4. **性能分析** - 使用Godot的性能分析工具
|
|
||||||
|
|
||||||
## 📚 参考资源
|
|
||||||
|
|
||||||
### 内部资源
|
|
||||||
- [02-开发规范](../02-开发规范/) - 编码规范和架构设计
|
|
||||||
- [04-高级开发](../04-高级开发/) - 进阶开发技巧
|
|
||||||
- [06-功能模块](../06-功能模块/) - 特定功能实现
|
|
||||||
|
|
||||||
### 外部资源
|
|
||||||
- [Godot官方文档](https://docs.godotengine.org/)
|
|
||||||
- [GDScript语言参考](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/)
|
|
||||||
- [Godot最佳实践](https://docs.godotengine.org/en/stable/tutorials/best_practices/)
|
|
||||||
|
|
||||||
## 💡 开发建议
|
|
||||||
|
|
||||||
### 效率提升
|
|
||||||
- 使用代码模板快速创建标准结构
|
|
||||||
- 善用Godot的场景实例化功能
|
|
||||||
- 合理使用@export变量进行配置
|
|
||||||
- 充分利用事件系统解耦组件
|
|
||||||
|
|
||||||
### 质量保证
|
|
||||||
- 每个功能都要编写对应测试
|
|
||||||
- 定期进行代码审查
|
|
||||||
- 关注性能指标和内存使用
|
|
||||||
- 保持代码简洁和可读性
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**记住：好的实现不仅要功能正确，更要易于维护和扩展！**
|
|
||||||
@@ -1,388 +0,0 @@
|
|||||||
# 实现细节规范
|
|
||||||
|
|
||||||
本文档详细说明了WhaleTown项目中各种游戏对象的具体实现要求和技术细节。
|
|
||||||
|
|
||||||
## 🎮 玩家实现规范
|
|
||||||
|
|
||||||
### 基础要求
|
|
||||||
- **节点类型**: 必须使用 `CharacterBody2D`
|
|
||||||
- **移动系统**: 使用 `move_and_slide()` 方法
|
|
||||||
- **相机集成**: 必须包含 `Camera2D` 子节点
|
|
||||||
|
|
||||||
### 玩家节点结构
|
|
||||||
```
|
|
||||||
Player (CharacterBody2D)
|
|
||||||
├── Sprite2D # 玩家精灵
|
|
||||||
├── CollisionShape2D # 碰撞形状
|
|
||||||
├── Camera2D # 玩家相机
|
|
||||||
│ └── [相机配置]
|
|
||||||
├── InteractionArea (Area2D) # 交互检测区域
|
|
||||||
│ └── CollisionShape2D
|
|
||||||
└── AnimationPlayer # 动画播放器
|
|
||||||
```
|
|
||||||
|
|
||||||
### 相机配置要求
|
|
||||||
```gdscript
|
|
||||||
# Player.gd 中的相机设置
|
|
||||||
@onready var camera: Camera2D = $Camera2D
|
|
||||||
|
|
||||||
func _ready() -> void:
|
|
||||||
# 必须启用位置平滑
|
|
||||||
camera.position_smoothing_enabled = true
|
|
||||||
camera.position_smoothing_speed = 5.0
|
|
||||||
|
|
||||||
# 设置相机边界（基于TileMap）
|
|
||||||
_setup_camera_limits()
|
|
||||||
|
|
||||||
func _setup_camera_limits() -> void:
|
|
||||||
# 获取当前场景的TileMap
|
|
||||||
var tilemap = get_tree().get_first_node_in_group("tilemap")
|
|
||||||
if tilemap and tilemap is TileMap:
|
|
||||||
var used_rect = tilemap.get_used_rect()
|
|
||||||
var tile_size = tilemap.tile_set.tile_size
|
|
||||||
|
|
||||||
# 计算世界坐标边界
|
|
||||||
camera.limit_left = used_rect.position.x * tile_size.x
|
|
||||||
camera.limit_top = used_rect.position.y * tile_size.y
|
|
||||||
camera.limit_right = used_rect.end.x * tile_size.x
|
|
||||||
camera.limit_bottom = used_rect.end.y * tile_size.y
|
|
||||||
```
|
|
||||||
|
|
||||||
### 移动实现模板
|
|
||||||
```gdscript
|
|
||||||
extends CharacterBody2D
|
|
||||||
class_name Player
|
|
||||||
|
|
||||||
@export var move_speed: float = 200.0
|
|
||||||
@export var acceleration: float = 1000.0
|
|
||||||
@export var friction: float = 1000.0
|
|
||||||
|
|
||||||
@onready var sprite: Sprite2D = $Sprite2D
|
|
||||||
@onready var camera: Camera2D = $Camera2D
|
|
||||||
|
|
||||||
func _ready() -> void:
|
|
||||||
# 设置相机
|
|
||||||
camera.position_smoothing_enabled = true
|
|
||||||
_setup_camera_limits()
|
|
||||||
|
|
||||||
func _physics_process(delta: float) -> void:
|
|
||||||
_handle_movement(delta)
|
|
||||||
|
|
||||||
func _handle_movement(delta: float) -> void:
|
|
||||||
# 获取输入方向
|
|
||||||
var input_direction := Input.get_vector(
|
|
||||||
"move_left", "move_right",
|
|
||||||
"move_up", "move_down"
|
|
||||||
)
|
|
||||||
|
|
||||||
# 应用移动
|
|
||||||
if input_direction != Vector2.ZERO:
|
|
||||||
velocity = velocity.move_toward(input_direction * move_speed, acceleration * delta)
|
|
||||||
else:
|
|
||||||
velocity = velocity.move_toward(Vector2.ZERO, friction * delta)
|
|
||||||
|
|
||||||
move_and_slide()
|
|
||||||
|
|
||||||
# 发送移动事件
|
|
||||||
if velocity.length() > 0:
|
|
||||||
EventSystem.emit_event(EventNames.PLAYER_MOVED, {
|
|
||||||
"position": global_position,
|
|
||||||
"velocity": velocity
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🤖 NPC实现规范
|
|
||||||
|
|
||||||
### 基础要求
|
|
||||||
- **节点类型**: 使用 `CharacterBody2D` 或 `StaticBody2D`
|
|
||||||
- **交互区域**: 必须包含名为 `InteractionArea` 的 `Area2D`
|
|
||||||
- **事件通信**: 通过 `EventSystem` 触发交互
|
|
||||||
|
|
||||||
### NPC节点结构
|
|
||||||
```
|
|
||||||
NPC (CharacterBody2D)
|
|
||||||
├── Sprite2D # NPC精灵
|
|
||||||
├── CollisionShape2D # 物理碰撞
|
|
||||||
├── InteractionArea (Area2D) # 交互检测区域
|
|
||||||
│ └── CollisionShape2D # 交互碰撞形状
|
|
||||||
├── DialogueComponent # 对话组件
|
|
||||||
└── AnimationPlayer # 动画播放器
|
|
||||||
```
|
|
||||||
|
|
||||||
### NPC实现模板
|
|
||||||
```gdscript
|
|
||||||
extends CharacterBody2D
|
|
||||||
class_name NPC
|
|
||||||
|
|
||||||
@export var npc_name: String = "NPC"
|
|
||||||
@export var dialogue_resource: DialogueResource
|
|
||||||
|
|
||||||
@onready var interaction_area: Area2D = $InteractionArea
|
|
||||||
@onready var sprite: Sprite2D = $Sprite2D
|
|
||||||
|
|
||||||
signal interaction_available(npc: NPC)
|
|
||||||
signal interaction_unavailable(npc: NPC)
|
|
||||||
|
|
||||||
func _ready() -> void:
|
|
||||||
# 连接交互区域信号
|
|
||||||
interaction_area.body_entered.connect(_on_interaction_area_entered)
|
|
||||||
interaction_area.body_exited.connect(_on_interaction_area_exited)
|
|
||||||
|
|
||||||
# 监听交互事件
|
|
||||||
EventSystem.connect_event(EventNames.INTERACT_PRESSED, _on_interact_pressed)
|
|
||||||
|
|
||||||
func _on_interaction_area_entered(body: Node2D) -> void:
|
|
||||||
if body.is_in_group("player"):
|
|
||||||
interaction_available.emit(self)
|
|
||||||
# 显示交互提示
|
|
||||||
_show_interaction_hint()
|
|
||||||
|
|
||||||
func _on_interaction_area_exited(body: Node2D) -> void:
|
|
||||||
if body.is_in_group("player"):
|
|
||||||
interaction_unavailable.emit(self)
|
|
||||||
# 隐藏交互提示
|
|
||||||
_hide_interaction_hint()
|
|
||||||
|
|
||||||
func _on_interact_pressed(data: Dictionary = {}) -> void:
|
|
||||||
# 检查玩家是否在交互范围内
|
|
||||||
if _is_player_in_range():
|
|
||||||
start_dialogue()
|
|
||||||
|
|
||||||
func start_dialogue() -> void:
|
|
||||||
EventSystem.emit_event(EventNames.NPC_TALKED, {
|
|
||||||
"npc": self,
|
|
||||||
"npc_name": npc_name,
|
|
||||||
"dialogue": dialogue_resource
|
|
||||||
})
|
|
||||||
|
|
||||||
func _is_player_in_range() -> bool:
|
|
||||||
var bodies = interaction_area.get_overlapping_bodies()
|
|
||||||
for body in bodies:
|
|
||||||
if body.is_in_group("player"):
|
|
||||||
return true
|
|
||||||
return false
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🗺️ TileMap图层规范
|
|
||||||
|
|
||||||
### 图层配置要求
|
|
||||||
TileMap必须按以下标准配置图层：
|
|
||||||
|
|
||||||
#### 图层0：地面层 (Ground)
|
|
||||||
- **用途**: 地面纹理、道路、草地等
|
|
||||||
- **碰撞**: 禁用物理层
|
|
||||||
- **渲染**: 最底层渲染
|
|
||||||
- **Y排序**: 禁用
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# 设置地面层
|
|
||||||
var ground_layer = tilemap.get_layer(0)
|
|
||||||
tilemap.set_layer_name(0, "Ground")
|
|
||||||
tilemap.set_layer_enabled(0, true)
|
|
||||||
tilemap.set_layer_y_sort_enabled(0, false)
|
|
||||||
# 不设置物理层
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 图层1：障碍层 (Obstacles)
|
|
||||||
- **用途**: 墙壁、树木、建筑等不可通过的障碍
|
|
||||||
- **碰撞**: 启用物理层
|
|
||||||
- **渲染**: 中间层
|
|
||||||
- **Y排序**: 禁用
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# 设置障碍层
|
|
||||||
tilemap.set_layer_name(1, "Obstacles")
|
|
||||||
tilemap.set_layer_enabled(1, true)
|
|
||||||
tilemap.set_layer_y_sort_enabled(1, false)
|
|
||||||
# 设置物理层用于碰撞检测
|
|
||||||
tilemap.set_layer_physics_enabled(1, true)
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 图层2：装饰层 (Decoration)
|
|
||||||
- **用途**: 装饰物、前景元素
|
|
||||||
- **碰撞**: 根据需要设置
|
|
||||||
- **渲染**: 最上层
|
|
||||||
- **Y排序**: 启用（重要！）
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# 设置装饰层
|
|
||||||
tilemap.set_layer_name(2, "Decoration")
|
|
||||||
tilemap.set_layer_enabled(2, true)
|
|
||||||
tilemap.set_layer_y_sort_enabled(2, true) # 启用Y排序
|
|
||||||
tilemap.set_layer_y_sort_origin(2, 16) # 设置排序原点
|
|
||||||
```
|
|
||||||
|
|
||||||
### TileMap设置模板
|
|
||||||
```gdscript
|
|
||||||
extends TileMap
|
|
||||||
class_name GameTileMap
|
|
||||||
|
|
||||||
func _ready() -> void:
|
|
||||||
# 设置TileMap为tilemap组
|
|
||||||
add_to_group("tilemap")
|
|
||||||
|
|
||||||
# 配置图层
|
|
||||||
_setup_layers()
|
|
||||||
|
|
||||||
# 通知相机系统更新边界
|
|
||||||
EventSystem.emit_event(EventNames.TILEMAP_READY, {
|
|
||||||
"tilemap": self,
|
|
||||||
"used_rect": get_used_rect()
|
|
||||||
})
|
|
||||||
|
|
||||||
func _setup_layers() -> void:
|
|
||||||
# 确保有足够的图层
|
|
||||||
while get_layers_count() < 3:
|
|
||||||
add_layer(-1)
|
|
||||||
|
|
||||||
# 配置地面层 (0)
|
|
||||||
set_layer_name(0, "Ground")
|
|
||||||
set_layer_y_sort_enabled(0, false)
|
|
||||||
|
|
||||||
# 配置障碍层 (1)
|
|
||||||
set_layer_name(1, "Obstacles")
|
|
||||||
set_layer_y_sort_enabled(1, false)
|
|
||||||
set_layer_physics_enabled(1, true)
|
|
||||||
|
|
||||||
# 配置装饰层 (2)
|
|
||||||
set_layer_name(2, "Decoration")
|
|
||||||
set_layer_y_sort_enabled(2, true)
|
|
||||||
set_layer_y_sort_origin(2, tile_set.tile_size.y / 2)
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🎯 交互物实现规范
|
|
||||||
|
|
||||||
### 可收集物品
|
|
||||||
```gdscript
|
|
||||||
extends Area2D
|
|
||||||
class_name CollectibleItem
|
|
||||||
|
|
||||||
@export var item_name: String = "Item"
|
|
||||||
@export var item_value: int = 1
|
|
||||||
|
|
||||||
@onready var sprite: Sprite2D = $Sprite2D
|
|
||||||
@onready var collision: CollisionShape2D = $CollisionShape2D
|
|
||||||
|
|
||||||
func _ready() -> void:
|
|
||||||
body_entered.connect(_on_body_entered)
|
|
||||||
|
|
||||||
func _on_body_entered(body: Node2D) -> void:
|
|
||||||
if body.is_in_group("player"):
|
|
||||||
collect_item(body)
|
|
||||||
|
|
||||||
func collect_item(collector: Node2D) -> void:
|
|
||||||
# 发送收集事件
|
|
||||||
EventSystem.emit_event(EventNames.ITEM_COLLECTED, {
|
|
||||||
"item_name": item_name,
|
|
||||||
"item_value": item_value,
|
|
||||||
"collector": collector,
|
|
||||||
"position": global_position
|
|
||||||
})
|
|
||||||
|
|
||||||
# 播放收集动画
|
|
||||||
_play_collect_animation()
|
|
||||||
|
|
||||||
func _play_collect_animation() -> void:
|
|
||||||
var tween = create_tween()
|
|
||||||
tween.parallel().tween_property(self, "scale", Vector2.ZERO, 0.3)
|
|
||||||
tween.parallel().tween_property(self, "modulate:a", 0.0, 0.3)
|
|
||||||
await tween.finished
|
|
||||||
queue_free()
|
|
||||||
```
|
|
||||||
|
|
||||||
### 可交互对象
|
|
||||||
```gdscript
|
|
||||||
extends StaticBody2D
|
|
||||||
class_name InteractableObject
|
|
||||||
|
|
||||||
@export var interaction_text: String = "按E交互"
|
|
||||||
@export var can_interact: bool = true
|
|
||||||
|
|
||||||
@onready var interaction_area: Area2D = $InteractionArea
|
|
||||||
@onready var sprite: Sprite2D = $Sprite2D
|
|
||||||
|
|
||||||
var player_in_range: bool = false
|
|
||||||
|
|
||||||
func _ready() -> void:
|
|
||||||
interaction_area.body_entered.connect(_on_interaction_area_entered)
|
|
||||||
interaction_area.body_exited.connect(_on_interaction_area_exited)
|
|
||||||
EventSystem.connect_event(EventNames.INTERACT_PRESSED, _on_interact_pressed)
|
|
||||||
|
|
||||||
func _on_interaction_area_entered(body: Node2D) -> void:
|
|
||||||
if body.is_in_group("player") and can_interact:
|
|
||||||
player_in_range = true
|
|
||||||
_show_interaction_prompt()
|
|
||||||
|
|
||||||
func _on_interaction_area_exited(body: Node2D) -> void:
|
|
||||||
if body.is_in_group("player"):
|
|
||||||
player_in_range = false
|
|
||||||
_hide_interaction_prompt()
|
|
||||||
|
|
||||||
func _on_interact_pressed(data: Dictionary = {}) -> void:
|
|
||||||
if player_in_range and can_interact:
|
|
||||||
interact()
|
|
||||||
|
|
||||||
func interact() -> void:
|
|
||||||
# 子类重写此方法实现具体交互逻辑
|
|
||||||
print("与 ", name, " 交互")
|
|
||||||
|
|
||||||
EventSystem.emit_event(EventNames.OBJECT_INTERACTED, {
|
|
||||||
"object": self,
|
|
||||||
"interaction_type": "default"
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🎨 资源过滤设置
|
|
||||||
|
|
||||||
### 纹理过滤规范
|
|
||||||
所有像素艺术资源必须使用最近邻过滤：
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# 在导入设置中或代码中设置
|
|
||||||
func _setup_pixel_perfect_texture(texture: Texture2D) -> void:
|
|
||||||
if texture is ImageTexture:
|
|
||||||
var image = texture.get_image()
|
|
||||||
image.generate_mipmaps(false)
|
|
||||||
# 在导入设置中设置Filter为Off
|
|
||||||
```
|
|
||||||
|
|
||||||
### 导入设置模板
|
|
||||||
对于所有精灵资源，在导入设置中：
|
|
||||||
- **Filter**: Off (关闭)
|
|
||||||
- **Mipmaps**: Off (关闭)
|
|
||||||
- **Fix Alpha Border**: On (开启)
|
|
||||||
|
|
||||||
## 🔧 性能优化要求
|
|
||||||
|
|
||||||
### 节点缓存
|
|
||||||
```gdscript
|
|
||||||
# ✅ 正确：使用@onready缓存节点引用
|
|
||||||
@onready var sprite: Sprite2D = $Sprite2D
|
|
||||||
@onready var collision: CollisionShape2D = $CollisionShape2D
|
|
||||||
|
|
||||||
func _process(delta: float) -> void:
|
|
||||||
sprite.modulate.a = 0.5 # 使用缓存的引用
|
|
||||||
|
|
||||||
# ❌ 错误：在_process中重复获取节点
|
|
||||||
func _process(delta: float) -> void:
|
|
||||||
$Sprite2D.modulate.a = 0.5 # 每帧都要查找节点
|
|
||||||
```
|
|
||||||
|
|
||||||
### 事件频率控制
|
|
||||||
```gdscript
|
|
||||||
# 控制事件发送频率
|
|
||||||
var last_event_time: float = 0.0
|
|
||||||
const EVENT_INTERVAL: float = 0.1 # 100ms间隔
|
|
||||||
|
|
||||||
func _process(delta: float) -> void:
|
|
||||||
var current_time = Time.get_time_dict_from_system()
|
|
||||||
if current_time - last_event_time >= EVENT_INTERVAL:
|
|
||||||
EventSystem.emit_event(EventNames.POSITION_UPDATE, {
|
|
||||||
"position": global_position
|
|
||||||
})
|
|
||||||
last_event_time = current_time
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**记住：遵循这些实现细节规范可以确保游戏对象的一致性和性能！**
|
|
||||||
@@ -1,312 +0,0 @@
|
|||||||
# API接口测试指南
|
|
||||||
|
|
||||||
**更新日期**: 2025-12-25
|
|
||||||
**适用版本**: API v1.1.1
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎯 测试概述
|
|
||||||
|
|
||||||
本指南提供了完整的API接口测试方案，包括Godot内置测试和独立的Python测试脚本，确保在不同环境下都能有效验证API功能。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📋 测试工具对比
|
|
||||||
|
|
||||||
| 测试工具 | 适用场景 | 优势 | 使用难度 |
|
|
||||||
|----------|----------|------|----------|
|
|
||||||
| **Python快速测试** | 日常检查 | 快速、简单 | ⭐ |
|
|
||||||
| **Python完整测试** | 全面验证 | 覆盖全面、详细 | ⭐⭐ |
|
|
||||||
| **Godot内置测试** | 引擎环境 | 真实环境、UI测试 | ⭐⭐⭐ |
|
|
||||||
| **简单连接测试** | 基础检查 | 最小依赖 | ⭐ |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🚀 快速开始
|
|
||||||
|
|
||||||
### 1. Python测试（推荐）
|
|
||||||
|
|
||||||
#### 安装依赖
|
|
||||||
```bash
|
|
||||||
cd tests/api
|
|
||||||
pip install -r requirements.txt
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 运行快速测试
|
|
||||||
```bash
|
|
||||||
# Windows
|
|
||||||
run_tests.bat
|
|
||||||
|
|
||||||
# Linux/Mac
|
|
||||||
./run_tests.sh
|
|
||||||
|
|
||||||
# 或直接运行
|
|
||||||
python quick_test.py
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Godot测试
|
|
||||||
|
|
||||||
#### 运行API测试脚本
|
|
||||||
```gdscript
|
|
||||||
# 在Godot中运行
|
|
||||||
var api_test = preload("res://scripts/network/ApiTestScript.gd").new()
|
|
||||||
add_child(api_test)
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 运行UI测试
|
|
||||||
```bash
|
|
||||||
# 打开Godot项目
|
|
||||||
# 运行 tests/auth/auth_ui_test.tscn 场景
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📊 测试类型详解
|
|
||||||
|
|
||||||
### 1. 快速测试 (`quick_test.py`)
|
|
||||||
|
|
||||||
**用途**: 日常开发中的快速验证
|
|
||||||
**时间**: 约30秒
|
|
||||||
**覆盖**: 基础API端点
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python tests/api/quick_test.py
|
|
||||||
```
|
|
||||||
|
|
||||||
**测试内容**:
|
|
||||||
- ✅ 服务器状态检查
|
|
||||||
- ✅ 邮箱验证码发送
|
|
||||||
- ✅ 用户登录/注册
|
|
||||||
- ✅ 基础错误处理
|
|
||||||
|
|
||||||
### 2. 完整测试 (`api_client_test.py`)
|
|
||||||
|
|
||||||
**用途**: 发布前的全面验证
|
|
||||||
**时间**: 约2-3分钟
|
|
||||||
**覆盖**: 所有业务流程
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python tests/api/api_client_test.py
|
|
||||||
```
|
|
||||||
|
|
||||||
**测试内容**:
|
|
||||||
- 🔄 完整的用户注册流程
|
|
||||||
- 🔄 邮箱验证流程
|
|
||||||
- 🔄 登录流程（密码+验证码）
|
|
||||||
- 🔄 密码重置流程
|
|
||||||
- 🔄 错误场景测试
|
|
||||||
- 🔄 频率限制测试
|
|
||||||
|
|
||||||
### 3. Godot内置测试
|
|
||||||
|
|
||||||
**用途**: 引擎环境下的真实测试
|
|
||||||
**时间**: 根据测试场景而定
|
|
||||||
**覆盖**: UI交互和网络请求
|
|
||||||
|
|
||||||
#### API测试脚本
|
|
||||||
```gdscript
|
|
||||||
# 文件: scripts/network/ApiTestScript.gd
|
|
||||||
# 功能: 验证NetworkManager和ResponseHandler
|
|
||||||
```
|
|
||||||
|
|
||||||
#### UI测试场景
|
|
||||||
```gdscript
|
|
||||||
# 文件: tests/auth/auth_ui_test.tscn
|
|
||||||
# 功能: 测试认证界面的各种响应情况
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔧 测试配置
|
|
||||||
|
|
||||||
### API服务器配置
|
|
||||||
```python
|
|
||||||
# 默认配置
|
|
||||||
API_BASE_URL = "https://whaletownend.xinghangee.icu"
|
|
||||||
|
|
||||||
# 本地开发配置
|
|
||||||
API_BASE_URL = "http://localhost:3000"
|
|
||||||
```
|
|
||||||
|
|
||||||
### 测试数据配置
|
|
||||||
```python
|
|
||||||
# 测试用户信息
|
|
||||||
TEST_EMAIL = "test@example.com"
|
|
||||||
TEST_USERNAME = "testuser"
|
|
||||||
TEST_PASSWORD = "password123"
|
|
||||||
```
|
|
||||||
|
|
||||||
### 超时配置
|
|
||||||
```python
|
|
||||||
DEFAULT_TIMEOUT = 30 # 秒
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📈 测试结果解读
|
|
||||||
|
|
||||||
### 成功标志
|
|
||||||
- ✅ **测试通过** - 功能正常
|
|
||||||
- 🧪 **测试模式** - 开发环境，验证码在响应中返回
|
|
||||||
- 🔑 **获取验证码** - 成功获取到测试验证码
|
|
||||||
|
|
||||||
### 警告标志
|
|
||||||
- ⚠️ **资源冲突** - 409状态码，用户名/邮箱已存在
|
|
||||||
- ⏰ **频率限制** - 429状态码，请求过于频繁
|
|
||||||
|
|
||||||
### 错误标志
|
|
||||||
- ❌ **测试失败** - 功能异常，需要检查
|
|
||||||
- 🔌 **连接失败** - 网络问题或服务器不可用
|
|
||||||
- 📊 **状态码异常** - HTTP状态码不符合预期
|
|
||||||
|
|
||||||
### 示例输出解读
|
|
||||||
```
|
|
||||||
🧪 测试: 发送邮箱验证码
|
|
||||||
📡 POST https://whaletownend.xinghangee.icu/auth/send-email-verification
|
|
||||||
📦 数据: {"email": "test@example.com"}
|
|
||||||
📊 状态码: 206
|
|
||||||
🧪 测试模式响应
|
|
||||||
🔑 验证码: 123456
|
|
||||||
✅ 测试通过
|
|
||||||
```
|
|
||||||
|
|
||||||
**解读**:
|
|
||||||
- 请求成功发送到正确的端点
|
|
||||||
- 返回206状态码表示测试模式
|
|
||||||
- 成功获取验证码123456
|
|
||||||
- 整体测试通过
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🐛 故障排除
|
|
||||||
|
|
||||||
### 常见问题及解决方案
|
|
||||||
|
|
||||||
#### 1. 连接失败
|
|
||||||
**症状**: `❌ 连接失败` 或 `网络连接异常`
|
|
||||||
|
|
||||||
**解决方案**:
|
|
||||||
```bash
|
|
||||||
# 检查网络连接
|
|
||||||
ping whaletownend.xinghangee.icu
|
|
||||||
|
|
||||||
# 检查服务器状态
|
|
||||||
curl https://whaletownend.xinghangee.icu
|
|
||||||
|
|
||||||
# 检查防火墙设置
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 2. 频率限制
|
|
||||||
**症状**: `⏰ 请求过于频繁` 或 `429状态码`
|
|
||||||
|
|
||||||
**解决方案**:
|
|
||||||
- 等待冷却时间（通常1分钟）
|
|
||||||
- 使用不同的测试邮箱
|
|
||||||
- 检查API频率限制配置
|
|
||||||
|
|
||||||
#### 3. 验证码错误
|
|
||||||
**症状**: `验证码错误或已过期`
|
|
||||||
|
|
||||||
**解决方案**:
|
|
||||||
- 确保使用最新获取的验证码
|
|
||||||
- 检查验证码是否在5分钟有效期内
|
|
||||||
- 在测试模式下使用响应中返回的验证码
|
|
||||||
|
|
||||||
#### 4. 参数验证失败
|
|
||||||
**症状**: `400状态码` 或 `参数验证失败`
|
|
||||||
|
|
||||||
**解决方案**:
|
|
||||||
- 检查请求参数格式
|
|
||||||
- 确认必填字段都已提供
|
|
||||||
- 验证邮箱、用户名格式是否正确
|
|
||||||
|
|
||||||
#### 5. Python依赖问题
|
|
||||||
**症状**: `ModuleNotFoundError: No module named 'requests'`
|
|
||||||
|
|
||||||
**解决方案**:
|
|
||||||
```bash
|
|
||||||
# 安装依赖
|
|
||||||
pip install requests
|
|
||||||
|
|
||||||
# 或使用requirements.txt
|
|
||||||
pip install -r tests/api/requirements.txt
|
|
||||||
|
|
||||||
# 检查Python版本
|
|
||||||
python --version
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📝 测试最佳实践
|
|
||||||
|
|
||||||
### 1. 测试前准备
|
|
||||||
- 确认API服务器正常运行
|
|
||||||
- 检查网络连接稳定
|
|
||||||
- 准备测试数据（邮箱、用户名等）
|
|
||||||
|
|
||||||
### 2. 测试执行
|
|
||||||
- 按照从简单到复杂的顺序执行测试
|
|
||||||
- 记录测试结果和异常情况
|
|
||||||
- 对失败的测试进行重试验证
|
|
||||||
|
|
||||||
### 3. 测试后分析
|
|
||||||
- 分析测试结果，识别问题模式
|
|
||||||
- 更新测试用例覆盖新发现的场景
|
|
||||||
- 文档化测试发现的问题和解决方案
|
|
||||||
|
|
||||||
### 4. 持续集成
|
|
||||||
- 将测试脚本集成到CI/CD流程
|
|
||||||
- 设置自动化测试触发条件
|
|
||||||
- 建立测试结果通知机制
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔄 测试流程建议
|
|
||||||
|
|
||||||
### 开发阶段
|
|
||||||
1. **快速测试** - 每次代码修改后运行
|
|
||||||
2. **功能测试** - 新功能开发完成后运行
|
|
||||||
3. **回归测试** - 修复bug后运行
|
|
||||||
|
|
||||||
### 测试阶段
|
|
||||||
1. **完整测试** - 每日构建后运行
|
|
||||||
2. **压力测试** - 定期运行频率限制测试
|
|
||||||
3. **兼容性测试** - 不同环境下运行测试
|
|
||||||
|
|
||||||
### 发布阶段
|
|
||||||
1. **预发布测试** - 生产环境部署前运行
|
|
||||||
2. **冒烟测试** - 生产环境部署后运行
|
|
||||||
3. **监控测试** - 生产环境持续监控
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📚 相关文档
|
|
||||||
|
|
||||||
- [API文档](api-documentation.md) - 完整的API接口说明
|
|
||||||
- [API更新日志](api_update_log.md) - 最新的API变更记录
|
|
||||||
- [项目结构说明](project_structure.md) - 项目整体架构
|
|
||||||
- [网络管理器设置](network_manager_setup.md) - Godot网络配置
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🤝 贡献指南
|
|
||||||
|
|
||||||
### 添加新测试
|
|
||||||
1. 在对应的测试文件中添加新的测试方法
|
|
||||||
2. 遵循现有的测试模式和命名规范
|
|
||||||
3. 添加适当的错误处理和结果验证
|
|
||||||
4. 更新相关文档
|
|
||||||
|
|
||||||
### 报告问题
|
|
||||||
1. 提供详细的错误信息和复现步骤
|
|
||||||
2. 包含测试环境信息（Python版本、操作系统等）
|
|
||||||
3. 附上相关的日志和截图
|
|
||||||
|
|
||||||
### 改进建议
|
|
||||||
1. 提出测试覆盖的改进建议
|
|
||||||
2. 优化测试执行效率的方案
|
|
||||||
3. 增强测试结果可读性的想法
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**测试愉快！🎉**
|
|
||||||
@@ -1,362 +0,0 @@
|
|||||||
# NetworkManager 设置指南
|
|
||||||
|
|
||||||
## 概述
|
|
||||||
|
|
||||||
NetworkManager 是一个统一的网络请求管理器，提供了简洁的API接口和统一的错误处理机制。配合 ResponseHandler，可以大大简化网络请求的处理逻辑。
|
|
||||||
|
|
||||||
## 🚀 快速设置
|
|
||||||
|
|
||||||
### 1. 设置AutoLoad
|
|
||||||
|
|
||||||
在Godot编辑器中：
|
|
||||||
|
|
||||||
1. 打开 `Project` → `Project Settings`
|
|
||||||
2. 切换到 `AutoLoad` 标签
|
|
||||||
3. 添加新的AutoLoad：
|
|
||||||
- **Path**: `res://_Core/managers/NetworkManager.gd`
|
|
||||||
- **Name**: `NetworkManager`
|
|
||||||
- **Singleton**: ✅ 勾选
|
|
||||||
|
|
||||||
### 2. 项目设置文件配置
|
|
||||||
|
|
||||||
在 `project.godot` 文件中会自动添加：
|
|
||||||
|
|
||||||
```ini
|
|
||||||
[autoload]
|
|
||||||
|
|
||||||
NetworkManager="*res://_Core/managers/NetworkManager.gd"
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. 验证设置
|
|
||||||
|
|
||||||
在任何脚本中可以直接使用：
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
func _ready():
|
|
||||||
# 直接访问全局单例
|
|
||||||
var request_id = NetworkManager.login("username", "password", callback)
|
|
||||||
print("请求ID: ", request_id)
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📚 使用方法
|
|
||||||
|
|
||||||
### 基本用法
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# 1. 简单的GET请求
|
|
||||||
var request_id = NetworkManager.get_app_status(func(success, data, error_info):
|
|
||||||
if success:
|
|
||||||
print("应用状态: ", data)
|
|
||||||
else:
|
|
||||||
print("获取状态失败: ", error_info)
|
|
||||||
)
|
|
||||||
|
|
||||||
# 2. 用户登录
|
|
||||||
NetworkManager.login("username", "password", func(success, data, error_info):
|
|
||||||
if success:
|
|
||||||
print("登录成功: ", data.data.user.username)
|
|
||||||
else:
|
|
||||||
print("登录失败: ", error_info.message)
|
|
||||||
)
|
|
||||||
|
|
||||||
# 3. 发送验证码
|
|
||||||
NetworkManager.send_email_verification("test@example.com", func(success, data, error_info):
|
|
||||||
if success:
|
|
||||||
print("验证码已发送")
|
|
||||||
else:
|
|
||||||
print("发送失败: ", error_info.message)
|
|
||||||
)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 配合ResponseHandler使用
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# 在回调函数中使用ResponseHandler处理响应
|
|
||||||
func _on_login_response(success: bool, data: Dictionary, error_info: Dictionary):
|
|
||||||
# 使用ResponseHandler统一处理
|
|
||||||
var result = ResponseHandler.handle_login_response(success, data, error_info)
|
|
||||||
|
|
||||||
# 显示Toast消息
|
|
||||||
show_toast(result.message, result.success)
|
|
||||||
|
|
||||||
# 执行自定义动作
|
|
||||||
if result.custom_action.is_valid():
|
|
||||||
result.custom_action.call()
|
|
||||||
|
|
||||||
# 处理成功情况
|
|
||||||
if result.success:
|
|
||||||
# 登录成功的处理逻辑
|
|
||||||
login_success.emit(username)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 全局事件监听
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
func _ready():
|
|
||||||
# 监听全局网络事件
|
|
||||||
NetworkManager.request_completed.connect(_on_global_request_completed)
|
|
||||||
NetworkManager.request_failed.connect(_on_global_request_failed)
|
|
||||||
|
|
||||||
func _on_global_request_completed(request_id: String, success: bool, data: Dictionary):
|
|
||||||
print("全局请求完成: ", request_id)
|
|
||||||
# 可以在这里隐藏全局加载指示器
|
|
||||||
|
|
||||||
func _on_global_request_failed(request_id: String, error_type: String, message: String):
|
|
||||||
print("全局请求失败: ", request_id, " - ", message)
|
|
||||||
# 可以在这里显示全局错误提示
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔧 高级功能
|
|
||||||
|
|
||||||
### 请求管理
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# 取消特定请求
|
|
||||||
var request_id = NetworkManager.login("user", "pass", callback)
|
|
||||||
NetworkManager.cancel_request(request_id)
|
|
||||||
|
|
||||||
# 取消所有请求
|
|
||||||
NetworkManager.cancel_all_requests()
|
|
||||||
|
|
||||||
# 检查请求状态
|
|
||||||
if NetworkManager.is_request_active(request_id):
|
|
||||||
print("请求仍在进行中")
|
|
||||||
|
|
||||||
# 获取活动请求数量
|
|
||||||
print("当前活动请求: ", NetworkManager.get_active_request_count())
|
|
||||||
```
|
|
||||||
|
|
||||||
### 自定义请求
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# 发送自定义POST请求
|
|
||||||
var custom_data = {
|
|
||||||
"custom_field": "custom_value"
|
|
||||||
}
|
|
||||||
var request_id = NetworkManager.post_request("/custom/endpoint", custom_data, func(success, data, error_info):
|
|
||||||
print("自定义请求完成")
|
|
||||||
)
|
|
||||||
|
|
||||||
# 发送自定义GET请求
|
|
||||||
NetworkManager.get_request("/custom/data", func(success, data, error_info):
|
|
||||||
print("获取自定义数据")
|
|
||||||
)
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📋 API接口列表
|
|
||||||
|
|
||||||
### 认证相关
|
|
||||||
|
|
||||||
| 方法 | 参数 | 说明 |
|
|
||||||
|------|------|------|
|
|
||||||
| `login(identifier, password, callback)` | 用户标识符、密码、回调函数 | 用户登录 |
|
|
||||||
| `verification_code_login(identifier, code, callback)` | 用户标识符、验证码、回调函数 | 验证码登录 |
|
|
||||||
| `send_login_verification_code(identifier, callback)` | 用户标识符、回调函数 | 发送登录验证码 |
|
|
||||||
| `register(username, password, nickname, email, code, callback)` | 注册信息、回调函数 | 用户注册 |
|
|
||||||
| `send_email_verification(email, callback)` | 邮箱、回调函数 | 发送邮箱验证码 |
|
|
||||||
| `verify_email(email, code, callback)` | 邮箱、验证码、回调函数 | 验证邮箱 |
|
|
||||||
|
|
||||||
### 通用请求
|
|
||||||
|
|
||||||
| 方法 | 参数 | 说明 |
|
|
||||||
|------|------|------|
|
|
||||||
| `get_request(endpoint, callback, timeout)` | 端点、回调函数、超时时间 | GET请求 |
|
|
||||||
| `post_request(endpoint, data, callback, timeout)` | 端点、数据、回调函数、超时时间 | POST请求 |
|
|
||||||
| `put_request(endpoint, data, callback, timeout)` | 端点、数据、回调函数、超时时间 | PUT请求 |
|
|
||||||
| `delete_request(endpoint, callback, timeout)` | 端点、回调函数、超时时间 | DELETE请求 |
|
|
||||||
|
|
||||||
### 请求管理
|
|
||||||
|
|
||||||
| 方法 | 参数 | 说明 |
|
|
||||||
|------|------|------|
|
|
||||||
| `cancel_request(request_id)` | 请求ID | 取消特定请求 |
|
|
||||||
| `cancel_all_requests()` | 无 | 取消所有请求 |
|
|
||||||
| `is_request_active(request_id)` | 请求ID | 检查请求是否活动 |
|
|
||||||
| `get_active_request_count()` | 无 | 获取活动请求数量 |
|
|
||||||
| `get_request_info(request_id)` | 请求ID | 获取请求详细信息 |
|
|
||||||
|
|
||||||
## 🎯 ResponseHandler 使用
|
|
||||||
|
|
||||||
### 支持的响应类型
|
|
||||||
|
|
||||||
| 方法 | 说明 |
|
|
||||||
|------|------|
|
|
||||||
| `handle_login_response()` | 处理登录响应 |
|
|
||||||
| `handle_verification_code_login_response()` | 处理验证码登录响应 |
|
|
||||||
| `handle_send_verification_code_response()` | 处理发送验证码响应 |
|
|
||||||
| `handle_send_login_code_response()` | 处理发送登录验证码响应 |
|
|
||||||
| `handle_register_response()` | 处理注册响应 |
|
|
||||||
| `handle_verify_email_response()` | 处理邮箱验证响应 |
|
|
||||||
| `handle_network_test_response()` | 处理网络测试响应 |
|
|
||||||
| `handle_response(operation_type, ...)` | 通用响应处理 |
|
|
||||||
|
|
||||||
### ResponseResult 结构
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
class ResponseResult:
|
|
||||||
var success: bool # 是否成功
|
|
||||||
var message: String # 显示消息
|
|
||||||
var toast_type: String # Toast类型 ("success" 或 "error")
|
|
||||||
var data: Dictionary # 响应数据
|
|
||||||
var should_show_toast: bool # 是否显示Toast
|
|
||||||
var custom_action: Callable # 自定义动作
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔄 迁移指南
|
|
||||||
|
|
||||||
### 从旧版AuthScene迁移
|
|
||||||
|
|
||||||
#### 旧代码：
|
|
||||||
```gdscript
|
|
||||||
func send_login_request(username: String, password: String):
|
|
||||||
var url = API_BASE_URL + "/auth/login"
|
|
||||||
var headers = ["Content-Type: application/json"]
|
|
||||||
var body = JSON.stringify({
|
|
||||||
"username": username,
|
|
||||||
"password": password
|
|
||||||
})
|
|
||||||
|
|
||||||
current_request_type = "login"
|
|
||||||
|
|
||||||
var error = http_request.request(url, headers, HTTPClient.METHOD_POST, body)
|
|
||||||
if error != OK:
|
|
||||||
show_toast('网络请求失败', false)
|
|
||||||
restore_button(login_btn, "密码登录")
|
|
||||||
current_request_type = ""
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 新代码：
|
|
||||||
```gdscript
|
|
||||||
func send_login_request(username: String, password: String):
|
|
||||||
NetworkManager.login(username, password, _on_login_response)
|
|
||||||
|
|
||||||
func _on_login_response(success: bool, data: Dictionary, error_info: Dictionary):
|
|
||||||
var result = ResponseHandler.handle_login_response(success, data, error_info)
|
|
||||||
show_toast(result.message, result.success)
|
|
||||||
|
|
||||||
if result.success:
|
|
||||||
login_success.emit(username)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 迁移步骤
|
|
||||||
|
|
||||||
1. **设置AutoLoad**：按照上述步骤设置NetworkManager为AutoLoad
|
|
||||||
2. **替换请求方法**：将直接的HTTP请求替换为NetworkManager调用
|
|
||||||
3. **统一响应处理**：使用ResponseHandler处理所有响应
|
|
||||||
4. **移除重复代码**：删除重复的错误处理和请求构建代码
|
|
||||||
5. **测试功能**：确保所有功能正常工作
|
|
||||||
|
|
||||||
## 🧪 测试
|
|
||||||
|
|
||||||
### 单元测试示例
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
extends GutTest
|
|
||||||
|
|
||||||
func test_network_manager_login():
|
|
||||||
var network_manager = NetworkManager.new()
|
|
||||||
var callback_called = false
|
|
||||||
var callback_success = false
|
|
||||||
|
|
||||||
var callback = func(success, data, error_info):
|
|
||||||
callback_called = true
|
|
||||||
callback_success = success
|
|
||||||
|
|
||||||
var request_id = network_manager.login("testuser", "password", callback)
|
|
||||||
|
|
||||||
assert_ne(request_id, "", "应该返回有效的请求ID")
|
|
||||||
|
|
||||||
# 等待请求完成
|
|
||||||
await get_tree().create_timer(2.0).timeout
|
|
||||||
|
|
||||||
assert_true(callback_called, "回调函数应该被调用")
|
|
||||||
```
|
|
||||||
|
|
||||||
### 集成测试
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
func test_complete_login_flow():
|
|
||||||
# 1. 发送登录验证码
|
|
||||||
var code_sent = false
|
|
||||||
NetworkManager.send_login_verification_code("test@example.com", func(success, data, error_info):
|
|
||||||
code_sent = success
|
|
||||||
)
|
|
||||||
|
|
||||||
await get_tree().create_timer(1.0).timeout
|
|
||||||
assert_true(code_sent, "验证码应该发送成功")
|
|
||||||
|
|
||||||
# 2. 使用验证码登录
|
|
||||||
var login_success = false
|
|
||||||
NetworkManager.verification_code_login("test@example.com", "123456", func(success, data, error_info):
|
|
||||||
login_success = success
|
|
||||||
)
|
|
||||||
|
|
||||||
await get_tree().create_timer(1.0).timeout
|
|
||||||
assert_true(login_success, "验证码登录应该成功")
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔍 调试
|
|
||||||
|
|
||||||
### 启用详细日志
|
|
||||||
|
|
||||||
在NetworkManager中，所有请求都会输出详细的调试信息：
|
|
||||||
|
|
||||||
```
|
|
||||||
=== 发送网络请求 ===
|
|
||||||
请求ID: req_1
|
|
||||||
URL: https://whaletownend.xinghangee.icu/auth/login
|
|
||||||
方法: POST
|
|
||||||
Headers: ["Content-Type: application/json"]
|
|
||||||
Body: {"username":"testuser","password":"password123"}
|
|
||||||
发送结果: 0
|
|
||||||
|
|
||||||
=== 网络请求完成 ===
|
|
||||||
请求ID: req_1
|
|
||||||
结果: 0
|
|
||||||
状态码: 200
|
|
||||||
响应头: ["content-type: application/json"]
|
|
||||||
响应体长度: 156 字节
|
|
||||||
响应内容: {"success":true,"data":{"user":{"username":"testuser"}}}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 常见问题
|
|
||||||
|
|
||||||
1. **请求ID为空**：检查NetworkManager是否正确设置为AutoLoad
|
|
||||||
2. **回调未调用**：检查网络连接和API地址是否正确
|
|
||||||
3. **解析错误**：检查服务器返回的JSON格式是否正确
|
|
||||||
|
|
||||||
## 📈 性能优化
|
|
||||||
|
|
||||||
### 请求池管理
|
|
||||||
|
|
||||||
NetworkManager自动管理请求资源：
|
|
||||||
- 自动清理完成的请求
|
|
||||||
- 防止内存泄漏
|
|
||||||
- 支持请求取消
|
|
||||||
|
|
||||||
### 最佳实践
|
|
||||||
|
|
||||||
1. **及时取消不需要的请求**
|
|
||||||
2. **使用合适的超时时间**
|
|
||||||
3. **避免同时发送大量请求**
|
|
||||||
4. **在场景切换时取消活动请求**
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
func _exit_tree():
|
|
||||||
# 场景退出时取消所有请求
|
|
||||||
NetworkManager.cancel_all_requests()
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🎉 总结
|
|
||||||
|
|
||||||
使用NetworkManager和ResponseHandler的优势：
|
|
||||||
|
|
||||||
- ✅ **代码简洁**：一行代码发送请求
|
|
||||||
- ✅ **统一处理**：所有错误情况统一处理
|
|
||||||
- ✅ **易于维护**：网络逻辑与UI逻辑分离
|
|
||||||
- ✅ **功能强大**：支持请求管理、超时、取消等
|
|
||||||
- ✅ **调试友好**：详细的日志和错误信息
|
|
||||||
- ✅ **类型安全**：明确的回调参数类型
|
|
||||||
- ✅ **可扩展**：易于添加新的API接口
|
|
||||||
|
|
||||||
通过这套统一的网络管理系统，你的项目将拥有更好的代码结构和更强的可维护性！
|
|
||||||
@@ -1,617 +0,0 @@
|
|||||||
# 场景设计规范
|
|
||||||
|
|
||||||
本文档定义了 Whale Town 项目中场景设计的标准和最佳实践。
|
|
||||||
|
|
||||||
## 🎯 设计原则
|
|
||||||
|
|
||||||
### 核心原则
|
|
||||||
1. **功能独立** - 每个场景都是独立的功能单元
|
|
||||||
2. **职责单一** - 一个场景只负责一个主要功能
|
|
||||||
3. **可复用性** - 场景组件应该能够在其他场景中复用
|
|
||||||
4. **标准化** - 统一的场景结构和命名规范
|
|
||||||
5. **性能优先** - 优化场景性能，避免不必要的资源消耗
|
|
||||||
|
|
||||||
### 场景分类
|
|
||||||
- **主要场景** - 游戏的核心功能场景（主菜单、游戏场景、设置等）
|
|
||||||
- **UI场景** - 纯界面场景（对话框、HUD、菜单等）
|
|
||||||
- **游戏场景** - 包含游戏逻辑的场景（关卡、战斗、探索等）
|
|
||||||
- **工具场景** - 开发和测试用的场景
|
|
||||||
|
|
||||||
## 🏗️ 场景结构
|
|
||||||
|
|
||||||
### 标准目录结构
|
|
||||||
```
|
|
||||||
scenes/
|
|
||||||
├── 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 # 认证场景
|
|
||||||
```
|
|
||||||
|
|
||||||
### 场景命名规范
|
|
||||||
- **主场景**: `SceneName.tscn` (PascalCase)
|
|
||||||
- **组件预制体**: `ComponentName.tscn` (PascalCase)
|
|
||||||
- **脚本文件**: `SceneName.gd` (PascalCase)
|
|
||||||
- **节点名称**: `NodeName` (PascalCase) 或 `nodeName` (camelCase)
|
|
||||||
|
|
||||||
## 📝 场景设计模板
|
|
||||||
|
|
||||||
### 主场景结构模板
|
|
||||||
|
|
||||||
```
|
|
||||||
SceneName (Control/Node2D)
|
|
||||||
├── Background (TextureRect/Sprite2D) # 背景
|
|
||||||
├── UI (CanvasLayer) # UI层
|
|
||||||
│ ├── HUD (Control) # 游戏HUD
|
|
||||||
│ ├── Menu (Control) # 菜单界面
|
|
||||||
│ └── Dialog (Control) # 对话框
|
|
||||||
├── Game (Node2D) # 游戏内容层
|
|
||||||
│ ├── Player (CharacterBody2D) # 玩家
|
|
||||||
│ ├── NPCs (Node2D) # NPC容器
|
|
||||||
│ ├── Items (Node2D) # 物品容器
|
|
||||||
│ └── Effects (Node2D) # 特效容器
|
|
||||||
├── Audio (Node) # 音频管理
|
|
||||||
│ ├── BGM (AudioStreamPlayer) # 背景音乐
|
|
||||||
│ └── SFX (AudioStreamPlayer2D) # 音效
|
|
||||||
└── Systems (Node) # 系统组件
|
|
||||||
├── CameraController (Node) # 相机控制
|
|
||||||
├── InputHandler (Node) # 输入处理
|
|
||||||
└── StateManager (Node) # 状态管理
|
|
||||||
```
|
|
||||||
|
|
||||||
### 场景脚本模板
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# SceneName.gd
|
|
||||||
extends Control # 或 Node2D，根据场景类型选择
|
|
||||||
class_name SceneName
|
|
||||||
|
|
||||||
# 场景信息
|
|
||||||
const SCENE_NAME = "SceneName"
|
|
||||||
const SCENE_VERSION = "1.0.0"
|
|
||||||
|
|
||||||
# 场景状态
|
|
||||||
enum SceneState {
|
|
||||||
LOADING,
|
|
||||||
READY,
|
|
||||||
ACTIVE,
|
|
||||||
PAUSED,
|
|
||||||
TRANSITIONING
|
|
||||||
}
|
|
||||||
|
|
||||||
var current_state: SceneState = SceneState.LOADING
|
|
||||||
|
|
||||||
# 节点引用
|
|
||||||
@onready var background: TextureRect = $Background
|
|
||||||
@onready var ui_layer: CanvasLayer = $UI
|
|
||||||
@onready var game_layer: Node2D = $Game
|
|
||||||
@onready var audio_manager: Node = $Audio
|
|
||||||
@onready var systems: Node = $Systems
|
|
||||||
|
|
||||||
# 场景数据
|
|
||||||
var scene_data: Dictionary = {}
|
|
||||||
var is_initialized: bool = false
|
|
||||||
|
|
||||||
# 信号定义
|
|
||||||
signal scene_ready
|
|
||||||
signal scene_state_changed(old_state: SceneState, new_state: SceneState)
|
|
||||||
signal scene_data_updated(key: String, value)
|
|
||||||
|
|
||||||
func _ready():
|
|
||||||
"""场景初始化"""
|
|
||||||
print("初始化场景: ", SCENE_NAME)
|
|
||||||
|
|
||||||
# 初始化场景
|
|
||||||
await initialize_scene()
|
|
||||||
|
|
||||||
# 设置场景状态
|
|
||||||
change_state(SceneState.READY)
|
|
||||||
|
|
||||||
# 发送场景就绪信号
|
|
||||||
scene_ready.emit()
|
|
||||||
|
|
||||||
func initialize_scene():
|
|
||||||
"""初始化场景组件"""
|
|
||||||
# 加载场景数据
|
|
||||||
await load_scene_data()
|
|
||||||
|
|
||||||
# 初始化UI
|
|
||||||
initialize_ui()
|
|
||||||
|
|
||||||
# 初始化游戏组件
|
|
||||||
initialize_game_components()
|
|
||||||
|
|
||||||
# 初始化音频
|
|
||||||
initialize_audio()
|
|
||||||
|
|
||||||
# 初始化系统
|
|
||||||
initialize_systems()
|
|
||||||
|
|
||||||
# 连接信号
|
|
||||||
connect_signals()
|
|
||||||
|
|
||||||
is_initialized = true
|
|
||||||
|
|
||||||
func load_scene_data():
|
|
||||||
"""加载场景数据"""
|
|
||||||
# 从配置文件或网络加载场景数据
|
|
||||||
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:
|
|
||||||
var json_string = file.get_as_text()
|
|
||||||
file.close()
|
|
||||||
|
|
||||||
var json = JSON.new()
|
|
||||||
if json.parse(json_string) == OK:
|
|
||||||
scene_data = json.data
|
|
||||||
else:
|
|
||||||
print("警告: 场景数据JSON格式错误: ", data_path)
|
|
||||||
|
|
||||||
# 等待一帧确保所有节点都已初始化
|
|
||||||
await get_tree().process_frame
|
|
||||||
|
|
||||||
func initialize_ui():
|
|
||||||
"""初始化UI组件"""
|
|
||||||
if ui_layer:
|
|
||||||
# 初始化UI组件
|
|
||||||
for child in ui_layer.get_children():
|
|
||||||
if child.has_method("initialize"):
|
|
||||||
child.initialize()
|
|
||||||
|
|
||||||
func initialize_game_components():
|
|
||||||
"""初始化游戏组件"""
|
|
||||||
if game_layer:
|
|
||||||
# 初始化游戏组件
|
|
||||||
for child in game_layer.get_children():
|
|
||||||
if child.has_method("initialize"):
|
|
||||||
child.initialize()
|
|
||||||
|
|
||||||
func initialize_audio():
|
|
||||||
"""初始化音频"""
|
|
||||||
if audio_manager:
|
|
||||||
# 设置背景音乐
|
|
||||||
if scene_data.has("bgm"):
|
|
||||||
play_bgm(scene_data.bgm)
|
|
||||||
|
|
||||||
func initialize_systems():
|
|
||||||
"""初始化系统组件"""
|
|
||||||
if systems:
|
|
||||||
# 初始化系统组件
|
|
||||||
for child in systems.get_children():
|
|
||||||
if child.has_method("initialize"):
|
|
||||||
child.initialize()
|
|
||||||
|
|
||||||
func connect_signals():
|
|
||||||
"""连接信号"""
|
|
||||||
# 连接场景内部信号
|
|
||||||
# 连接全局事件
|
|
||||||
EventSystem.connect_event("game_paused", _on_game_paused)
|
|
||||||
EventSystem.connect_event("game_resumed", _on_game_resumed)
|
|
||||||
|
|
||||||
func change_state(new_state: SceneState):
|
|
||||||
"""改变场景状态"""
|
|
||||||
if current_state == new_state:
|
|
||||||
return
|
|
||||||
|
|
||||||
var old_state = current_state
|
|
||||||
current_state = new_state
|
|
||||||
|
|
||||||
print("场景状态变更: %s -> %s" % [SceneState.keys()[old_state], SceneState.keys()[new_state]])
|
|
||||||
|
|
||||||
# 处理状态变更
|
|
||||||
_handle_state_change(old_state, new_state)
|
|
||||||
|
|
||||||
# 发送状态变更信号
|
|
||||||
scene_state_changed.emit(old_state, new_state)
|
|
||||||
|
|
||||||
func _handle_state_change(old_state: SceneState, new_state: SceneState):
|
|
||||||
"""处理状态变更"""
|
|
||||||
match new_state:
|
|
||||||
SceneState.LOADING:
|
|
||||||
_on_enter_loading_state()
|
|
||||||
SceneState.READY:
|
|
||||||
_on_enter_ready_state()
|
|
||||||
SceneState.ACTIVE:
|
|
||||||
_on_enter_active_state()
|
|
||||||
SceneState.PAUSED:
|
|
||||||
_on_enter_paused_state()
|
|
||||||
SceneState.TRANSITIONING:
|
|
||||||
_on_enter_transitioning_state()
|
|
||||||
|
|
||||||
func _on_enter_loading_state():
|
|
||||||
"""进入加载状态"""
|
|
||||||
# 显示加载界面
|
|
||||||
pass
|
|
||||||
|
|
||||||
func _on_enter_ready_state():
|
|
||||||
"""进入就绪状态"""
|
|
||||||
# 场景准备完成
|
|
||||||
pass
|
|
||||||
|
|
||||||
func _on_enter_active_state():
|
|
||||||
"""进入活跃状态"""
|
|
||||||
# 开始游戏逻辑
|
|
||||||
pass
|
|
||||||
|
|
||||||
func _on_enter_paused_state():
|
|
||||||
"""进入暂停状态"""
|
|
||||||
# 暂停游戏逻辑
|
|
||||||
get_tree().paused = true
|
|
||||||
|
|
||||||
func _on_enter_transitioning_state():
|
|
||||||
"""进入转换状态"""
|
|
||||||
# 场景转换中
|
|
||||||
pass
|
|
||||||
|
|
||||||
func play_bgm(bgm_path: String):
|
|
||||||
"""播放背景音乐"""
|
|
||||||
var bgm_player = audio_manager.get_node("BGM") as AudioStreamPlayer
|
|
||||||
if bgm_player and FileAccess.file_exists(bgm_path):
|
|
||||||
var audio_stream = load(bgm_path)
|
|
||||||
bgm_player.stream = audio_stream
|
|
||||||
bgm_player.play()
|
|
||||||
|
|
||||||
func play_sfx(sfx_path: String, position: Vector2 = Vector2.ZERO):
|
|
||||||
"""播放音效"""
|
|
||||||
var sfx_player = audio_manager.get_node("SFX") as AudioStreamPlayer2D
|
|
||||||
if sfx_player and FileAccess.file_exists(sfx_path):
|
|
||||||
var audio_stream = load(sfx_path)
|
|
||||||
sfx_player.stream = audio_stream
|
|
||||||
if position != Vector2.ZERO:
|
|
||||||
sfx_player.global_position = position
|
|
||||||
sfx_player.play()
|
|
||||||
|
|
||||||
func update_scene_data(key: String, value):
|
|
||||||
"""更新场景数据"""
|
|
||||||
scene_data[key] = value
|
|
||||||
scene_data_updated.emit(key, value)
|
|
||||||
|
|
||||||
func get_scene_data(key: String, default_value = null):
|
|
||||||
"""获取场景数据"""
|
|
||||||
return scene_data.get(key, default_value)
|
|
||||||
|
|
||||||
func cleanup():
|
|
||||||
"""清理场景资源"""
|
|
||||||
print("清理场景: ", SCENE_NAME)
|
|
||||||
|
|
||||||
# 断开信号连接
|
|
||||||
EventSystem.disconnect_event("game_paused", _on_game_paused)
|
|
||||||
EventSystem.disconnect_event("game_resumed", _on_game_resumed)
|
|
||||||
|
|
||||||
# 清理组件
|
|
||||||
if ui_layer:
|
|
||||||
for child in ui_layer.get_children():
|
|
||||||
if child.has_method("cleanup"):
|
|
||||||
child.cleanup()
|
|
||||||
|
|
||||||
if game_layer:
|
|
||||||
for child in game_layer.get_children():
|
|
||||||
if child.has_method("cleanup"):
|
|
||||||
child.cleanup()
|
|
||||||
|
|
||||||
if systems:
|
|
||||||
for child in systems.get_children():
|
|
||||||
if child.has_method("cleanup"):
|
|
||||||
child.cleanup()
|
|
||||||
|
|
||||||
# 停止音频
|
|
||||||
if audio_manager:
|
|
||||||
var bgm_player = audio_manager.get_node("BGM") as AudioStreamPlayer
|
|
||||||
if bgm_player:
|
|
||||||
bgm_player.stop()
|
|
||||||
|
|
||||||
# 事件处理
|
|
||||||
func _on_game_paused():
|
|
||||||
"""游戏暂停事件"""
|
|
||||||
if current_state == SceneState.ACTIVE:
|
|
||||||
change_state(SceneState.PAUSED)
|
|
||||||
|
|
||||||
func _on_game_resumed():
|
|
||||||
"""游戏恢复事件"""
|
|
||||||
if current_state == SceneState.PAUSED:
|
|
||||||
change_state(SceneState.ACTIVE)
|
|
||||||
get_tree().paused = false
|
|
||||||
|
|
||||||
# 输入处理
|
|
||||||
func _input(event):
|
|
||||||
"""处理输入事件"""
|
|
||||||
if current_state != SceneState.ACTIVE:
|
|
||||||
return
|
|
||||||
|
|
||||||
# 处理场景特定的输入
|
|
||||||
_handle_scene_input(event)
|
|
||||||
|
|
||||||
func _handle_scene_input(event):
|
|
||||||
"""处理场景特定输入"""
|
|
||||||
# 在子类中重写此方法
|
|
||||||
pass
|
|
||||||
|
|
||||||
# 生命周期方法
|
|
||||||
func _process(delta):
|
|
||||||
"""每帧更新"""
|
|
||||||
if current_state == SceneState.ACTIVE:
|
|
||||||
_update_scene(delta)
|
|
||||||
|
|
||||||
func _update_scene(delta):
|
|
||||||
"""更新场景逻辑"""
|
|
||||||
# 在子类中重写此方法
|
|
||||||
pass
|
|
||||||
|
|
||||||
func _physics_process(delta):
|
|
||||||
"""物理更新"""
|
|
||||||
if current_state == SceneState.ACTIVE:
|
|
||||||
_physics_update_scene(delta)
|
|
||||||
|
|
||||||
func _physics_update_scene(delta):
|
|
||||||
"""物理更新场景逻辑"""
|
|
||||||
# 在子类中重写此方法
|
|
||||||
pass
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🎨 UI设计规范
|
|
||||||
|
|
||||||
### UI层级结构
|
|
||||||
```
|
|
||||||
UI (CanvasLayer)
|
|
||||||
├── Background (Control) # UI背景
|
|
||||||
├── MainContent (Control) # 主要内容
|
|
||||||
│ ├── Header (Control) # 头部区域
|
|
||||||
│ ├── Body (Control) # 主体区域
|
|
||||||
│ └── Footer (Control) # 底部区域
|
|
||||||
├── Overlay (Control) # 覆盖层
|
|
||||||
│ ├── Loading (Control) # 加载界面
|
|
||||||
│ ├── Dialog (Control) # 对话框
|
|
||||||
│ └── Toast (Control) # 提示消息
|
|
||||||
└── Debug (Control) # 调试信息
|
|
||||||
```
|
|
||||||
|
|
||||||
### UI组件规范
|
|
||||||
1. **响应式设计** - 使用Anchor和Margin实现自适应布局
|
|
||||||
2. **主题统一** - 使用统一的主题资源
|
|
||||||
3. **动画效果** - 添加适当的过渡动画
|
|
||||||
4. **无障碍支持** - 考虑键盘导航和屏幕阅读器
|
|
||||||
|
|
||||||
### UI脚本模板
|
|
||||||
```gdscript
|
|
||||||
# UIComponent.gd
|
|
||||||
extends Control
|
|
||||||
class_name UIComponent
|
|
||||||
|
|
||||||
signal ui_action(action_name: String, data: Dictionary)
|
|
||||||
|
|
||||||
@export var auto_initialize: bool = true
|
|
||||||
@export var animation_duration: float = 0.3
|
|
||||||
|
|
||||||
var is_visible: bool = false
|
|
||||||
var is_initialized: bool = false
|
|
||||||
|
|
||||||
func _ready():
|
|
||||||
if auto_initialize:
|
|
||||||
initialize()
|
|
||||||
|
|
||||||
func initialize():
|
|
||||||
"""初始化UI组件"""
|
|
||||||
if is_initialized:
|
|
||||||
return
|
|
||||||
|
|
||||||
# 设置初始状态
|
|
||||||
modulate.a = 0.0
|
|
||||||
visible = false
|
|
||||||
|
|
||||||
# 连接信号
|
|
||||||
_connect_signals()
|
|
||||||
|
|
||||||
is_initialized = true
|
|
||||||
|
|
||||||
func show_ui(animated: bool = true):
|
|
||||||
"""显示UI"""
|
|
||||||
if is_visible:
|
|
||||||
return
|
|
||||||
|
|
||||||
visible = true
|
|
||||||
is_visible = true
|
|
||||||
|
|
||||||
if animated:
|
|
||||||
var tween = create_tween()
|
|
||||||
tween.tween_property(self, "modulate:a", 1.0, animation_duration)
|
|
||||||
else:
|
|
||||||
modulate.a = 1.0
|
|
||||||
|
|
||||||
func hide_ui(animated: bool = true):
|
|
||||||
"""隐藏UI"""
|
|
||||||
if not is_visible:
|
|
||||||
return
|
|
||||||
|
|
||||||
is_visible = false
|
|
||||||
|
|
||||||
if animated:
|
|
||||||
var tween = create_tween()
|
|
||||||
tween.tween_property(self, "modulate:a", 0.0, animation_duration)
|
|
||||||
await tween.finished
|
|
||||||
visible = false
|
|
||||||
else:
|
|
||||||
modulate.a = 0.0
|
|
||||||
visible = false
|
|
||||||
|
|
||||||
func _connect_signals():
|
|
||||||
"""连接信号"""
|
|
||||||
# 在子类中重写
|
|
||||||
pass
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🎮 游戏场景规范
|
|
||||||
|
|
||||||
### 游戏场景结构
|
|
||||||
```
|
|
||||||
GameScene (Node2D)
|
|
||||||
├── Background (ParallaxBackground) # 背景层
|
|
||||||
├── Environment (Node2D) # 环境层
|
|
||||||
│ ├── Terrain (TileMap) # 地形
|
|
||||||
│ ├── Props (Node2D) # 道具
|
|
||||||
│ └── Decorations (Node2D) # 装饰
|
|
||||||
├── Entities (Node2D) # 实体层
|
|
||||||
│ ├── Player (CharacterBody2D) # 玩家
|
|
||||||
│ ├── NPCs (Node2D) # NPC
|
|
||||||
│ ├── Enemies (Node2D) # 敌人
|
|
||||||
│ └── Items (Node2D) # 物品
|
|
||||||
├── Effects (Node2D) # 特效层
|
|
||||||
│ ├── Particles (Node2D) # 粒子效果
|
|
||||||
│ └── Animations (Node2D) # 动画效果
|
|
||||||
└── Camera (Camera2D) # 相机
|
|
||||||
```
|
|
||||||
|
|
||||||
### 性能优化
|
|
||||||
1. **对象池** - 重用频繁创建销毁的对象
|
|
||||||
2. **视锥剔除** - 只渲染可见区域的对象
|
|
||||||
3. **LOD系统** - 根据距离调整细节级别
|
|
||||||
4. **批量处理** - 合并相似的渲染调用
|
|
||||||
|
|
||||||
## 🔧 场景管理
|
|
||||||
|
|
||||||
### 场景切换
|
|
||||||
```gdscript
|
|
||||||
# 使用SceneManager进行场景切换
|
|
||||||
SceneManager.change_scene("game_scene", {
|
|
||||||
"level": 1,
|
|
||||||
"player_data": player_data
|
|
||||||
})
|
|
||||||
|
|
||||||
# 带过渡效果的场景切换
|
|
||||||
SceneManager.change_scene_with_transition("battle_scene", {
|
|
||||||
"enemy_data": enemy_data
|
|
||||||
}, "fade")
|
|
||||||
```
|
|
||||||
|
|
||||||
### 场景数据传递
|
|
||||||
```gdscript
|
|
||||||
# 发送场景数据
|
|
||||||
var scene_data = {
|
|
||||||
"player_level": 10,
|
|
||||||
"inventory": player_inventory,
|
|
||||||
"quest_progress": quest_data
|
|
||||||
}
|
|
||||||
SceneManager.change_scene("next_scene", scene_data)
|
|
||||||
|
|
||||||
# 接收场景数据
|
|
||||||
func _on_scene_data_received(data: Dictionary):
|
|
||||||
if data.has("player_level"):
|
|
||||||
player_level = data.player_level
|
|
||||||
if data.has("inventory"):
|
|
||||||
load_inventory(data.inventory)
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🧪 场景测试
|
|
||||||
|
|
||||||
### 测试场景创建
|
|
||||||
```gdscript
|
|
||||||
# TestScene.gd
|
|
||||||
extends "res://scenes/BaseScene.gd"
|
|
||||||
|
|
||||||
func _ready():
|
|
||||||
super._ready()
|
|
||||||
|
|
||||||
# 设置测试环境
|
|
||||||
setup_test_environment()
|
|
||||||
|
|
||||||
# 运行测试用例
|
|
||||||
run_test_cases()
|
|
||||||
|
|
||||||
func setup_test_environment():
|
|
||||||
"""设置测试环境"""
|
|
||||||
# 创建测试数据
|
|
||||||
# 设置测试状态
|
|
||||||
pass
|
|
||||||
|
|
||||||
func run_test_cases():
|
|
||||||
"""运行测试用例"""
|
|
||||||
test_scene_initialization()
|
|
||||||
test_ui_interactions()
|
|
||||||
test_game_logic()
|
|
||||||
|
|
||||||
func test_scene_initialization():
|
|
||||||
"""测试场景初始化"""
|
|
||||||
assert(is_initialized, "场景应该已初始化")
|
|
||||||
assert(current_state == SceneState.READY, "场景状态应该为READY")
|
|
||||||
|
|
||||||
func test_ui_interactions():
|
|
||||||
"""测试UI交互"""
|
|
||||||
# 模拟用户输入
|
|
||||||
# 验证UI响应
|
|
||||||
pass
|
|
||||||
|
|
||||||
func test_game_logic():
|
|
||||||
"""测试游戏逻辑"""
|
|
||||||
# 测试游戏规则
|
|
||||||
# 验证状态变化
|
|
||||||
pass
|
|
||||||
```
|
|
||||||
|
|
||||||
### 性能测试
|
|
||||||
```gdscript
|
|
||||||
# 性能监控
|
|
||||||
func _process(delta):
|
|
||||||
super._process(delta)
|
|
||||||
|
|
||||||
# 监控帧率
|
|
||||||
var fps = Engine.get_frames_per_second()
|
|
||||||
if fps < 30:
|
|
||||||
print("警告: 帧率过低: ", fps)
|
|
||||||
|
|
||||||
# 监控内存使用
|
|
||||||
var memory_usage = OS.get_static_memory_usage_by_type()
|
|
||||||
if memory_usage > 100 * 1024 * 1024: # 100MB
|
|
||||||
print("警告: 内存使用过高: ", memory_usage / 1024 / 1024, "MB")
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📚 最佳实践
|
|
||||||
|
|
||||||
### 代码组织
|
|
||||||
1. **单一职责** - 每个场景只负责一个主要功能
|
|
||||||
2. **模块化** - 将复杂功能拆分为独立组件
|
|
||||||
3. **可测试** - 设计易于测试的场景结构
|
|
||||||
4. **文档化** - 为场景添加详细的文档说明
|
|
||||||
|
|
||||||
### 性能优化
|
|
||||||
1. **延迟加载** - 按需加载资源和组件
|
|
||||||
2. **对象复用** - 使用对象池管理频繁创建的对象
|
|
||||||
3. **批量操作** - 合并相似的操作减少开销
|
|
||||||
4. **内存管理** - 及时释放不需要的资源
|
|
||||||
|
|
||||||
### 用户体验
|
|
||||||
1. **响应式设计** - 支持不同分辨率和设备
|
|
||||||
2. **流畅动画** - 添加适当的过渡效果
|
|
||||||
3. **错误处理** - 优雅处理异常情况
|
|
||||||
4. **加载提示** - 为长时间操作提供进度反馈
|
|
||||||
|
|
||||||
## 🔍 常见问题
|
|
||||||
|
|
||||||
### Q: 如何处理场景间的数据传递？
|
|
||||||
A: 使用SceneManager的场景切换方法传递数据，或通过全局单例存储共享数据。
|
|
||||||
|
|
||||||
### Q: 场景性能如何优化？
|
|
||||||
A: 使用对象池、视锥剔除、LOD系统，避免在_process中执行重复计算。
|
|
||||||
|
|
||||||
### Q: 如何调试场景问题？
|
|
||||||
A: 使用Godot的远程调试器，添加性能监控，编写场景测试用例。
|
|
||||||
|
|
||||||
### Q: 场景切换如何添加过渡效果？
|
|
||||||
A: 使用SceneManager的过渡系统，或自定义Tween动画实现过渡效果。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**记住：良好的场景设计是游戏体验的基础！**
|
|
||||||
@@ -1,507 +0,0 @@
|
|||||||
# 性能优化指南
|
|
||||||
|
|
||||||
本文档提供 Whale Town 项目的性能优化策略和最佳实践。
|
|
||||||
|
|
||||||
## 🎯 优化目标
|
|
||||||
|
|
||||||
### 性能指标
|
|
||||||
- **帧率**: 保持60FPS稳定运行
|
|
||||||
- **内存使用**: 控制在合理范围内
|
|
||||||
- **加载时间**: 场景切换<2秒
|
|
||||||
- **响应时间**: UI交互<100ms
|
|
||||||
|
|
||||||
### 优化原则
|
|
||||||
1. **测量优先** - 先测量再优化
|
|
||||||
2. **渐进优化** - 逐步改进性能
|
|
||||||
3. **平衡取舍** - 在质量和性能间平衡
|
|
||||||
4. **用户体验** - 优化用户感知性能
|
|
||||||
|
|
||||||
## 🔧 渲染优化
|
|
||||||
|
|
||||||
### 纹理优化
|
|
||||||
```gdscript
|
|
||||||
# 使用合适的纹理格式
|
|
||||||
# 小图标使用 RGBA8
|
|
||||||
# 大背景使用 DXT1/DXT5
|
|
||||||
# UI元素使用 RGBA4444
|
|
||||||
|
|
||||||
# 纹理压缩设置
|
|
||||||
func optimize_texture_import():
|
|
||||||
# 在导入设置中启用压缩
|
|
||||||
# 设置合适的最大尺寸
|
|
||||||
# 启用Mipmaps（3D纹理）
|
|
||||||
pass
|
|
||||||
```
|
|
||||||
|
|
||||||
### 批处理优化
|
|
||||||
```gdscript
|
|
||||||
# 合并相同材质的对象
|
|
||||||
# 使用MultiMesh渲染大量相同对象
|
|
||||||
func create_multimesh_instances():
|
|
||||||
var multimesh = MultiMesh.new()
|
|
||||||
multimesh.transform_format = MultiMesh.TRANSFORM_2D
|
|
||||||
multimesh.instance_count = 100
|
|
||||||
|
|
||||||
var mesh_instance = MeshInstance2D.new()
|
|
||||||
mesh_instance.multimesh = multimesh
|
|
||||||
add_child(mesh_instance)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 视锥剔除
|
|
||||||
```gdscript
|
|
||||||
# 只渲染可见区域的对象
|
|
||||||
func update_visibility():
|
|
||||||
var camera = get_viewport().get_camera_2d()
|
|
||||||
var screen_rect = get_viewport_rect()
|
|
||||||
|
|
||||||
for child in get_children():
|
|
||||||
if child is Node2D:
|
|
||||||
var visible = screen_rect.intersects(child.get_rect())
|
|
||||||
child.visible = visible
|
|
||||||
```
|
|
||||||
|
|
||||||
## 💾 内存优化
|
|
||||||
|
|
||||||
### 对象池模式
|
|
||||||
```gdscript
|
|
||||||
# ObjectPool.gd
|
|
||||||
class_name ObjectPool
|
|
||||||
extends Node
|
|
||||||
|
|
||||||
var pools: Dictionary = {}
|
|
||||||
|
|
||||||
func get_object(type: String) -> Node:
|
|
||||||
if not pools.has(type):
|
|
||||||
pools[type] = []
|
|
||||||
|
|
||||||
var pool = pools[type]
|
|
||||||
if pool.size() > 0:
|
|
||||||
return pool.pop_back()
|
|
||||||
else:
|
|
||||||
return _create_new_object(type)
|
|
||||||
|
|
||||||
func return_object(obj: Node, type: String):
|
|
||||||
obj.reset() # 重置对象状态
|
|
||||||
pools[type].append(obj)
|
|
||||||
|
|
||||||
func _create_new_object(type: String) -> Node:
|
|
||||||
match type:
|
|
||||||
"Bullet":
|
|
||||||
return preload(ProjectPaths.get_component_path("effects", "Bullet")).instantiate()
|
|
||||||
"Enemy":
|
|
||||||
return preload(ProjectPaths.get_component_path("characters", "Enemy")).instantiate()
|
|
||||||
_:
|
|
||||||
return null
|
|
||||||
```
|
|
||||||
|
|
||||||
### 资源管理
|
|
||||||
```gdscript
|
|
||||||
# ResourceManager.gd
|
|
||||||
class_name ResourceManager
|
|
||||||
extends Node
|
|
||||||
|
|
||||||
var loaded_resources: Dictionary = {}
|
|
||||||
var resource_usage: Dictionary = {}
|
|
||||||
|
|
||||||
func load_resource(path: String) -> Resource:
|
|
||||||
if loaded_resources.has(path):
|
|
||||||
resource_usage[path] += 1
|
|
||||||
return loaded_resources[path]
|
|
||||||
|
|
||||||
var resource = load(path)
|
|
||||||
loaded_resources[path] = resource
|
|
||||||
resource_usage[path] = 1
|
|
||||||
return resource
|
|
||||||
|
|
||||||
func unload_resource(path: String):
|
|
||||||
if resource_usage.has(path):
|
|
||||||
resource_usage[path] -= 1
|
|
||||||
if resource_usage[path] <= 0:
|
|
||||||
loaded_resources.erase(path)
|
|
||||||
resource_usage.erase(path)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 内存监控
|
|
||||||
```gdscript
|
|
||||||
# MemoryMonitor.gd
|
|
||||||
extends Node
|
|
||||||
|
|
||||||
func _ready():
|
|
||||||
# 每秒检查一次内存使用
|
|
||||||
var timer = Timer.new()
|
|
||||||
timer.wait_time = 1.0
|
|
||||||
timer.timeout.connect(_check_memory)
|
|
||||||
add_child(timer)
|
|
||||||
timer.start()
|
|
||||||
|
|
||||||
func _check_memory():
|
|
||||||
var memory_usage = OS.get_static_memory_usage_by_type()
|
|
||||||
var total_memory = OS.get_static_memory_peak_usage()
|
|
||||||
|
|
||||||
print("内存使用: ", memory_usage / 1024 / 1024, "MB")
|
|
||||||
print("峰值内存: ", total_memory / 1024 / 1024, "MB")
|
|
||||||
|
|
||||||
# 内存使用过高时触发垃圾回收
|
|
||||||
if total_memory > 200 * 1024 * 1024: # 200MB
|
|
||||||
print("触发垃圾回收")
|
|
||||||
# 清理不必要的资源
|
|
||||||
_cleanup_resources()
|
|
||||||
|
|
||||||
func _cleanup_resources():
|
|
||||||
# 清理缓存
|
|
||||||
# 卸载未使用的资源
|
|
||||||
# 强制垃圾回收
|
|
||||||
pass
|
|
||||||
```
|
|
||||||
|
|
||||||
## ⚡ 脚本优化
|
|
||||||
|
|
||||||
### 避免频繁计算
|
|
||||||
```gdscript
|
|
||||||
# ❌ 错误示例：每帧计算
|
|
||||||
func _process(delta):
|
|
||||||
var distance = global_position.distance_to(target.global_position)
|
|
||||||
if distance < 100:
|
|
||||||
attack_target()
|
|
||||||
|
|
||||||
# ✅ 正确示例：缓存计算结果
|
|
||||||
var cached_distance: float = 0.0
|
|
||||||
var distance_update_timer: float = 0.0
|
|
||||||
|
|
||||||
func _process(delta):
|
|
||||||
distance_update_timer += delta
|
|
||||||
if distance_update_timer >= 0.1: # 每100ms更新一次
|
|
||||||
cached_distance = global_position.distance_to(target.global_position)
|
|
||||||
distance_update_timer = 0.0
|
|
||||||
|
|
||||||
if cached_distance < 100:
|
|
||||||
attack_target()
|
|
||||||
```
|
|
||||||
|
|
||||||
### 优化循环
|
|
||||||
```gdscript
|
|
||||||
# ❌ 错误示例：嵌套循环
|
|
||||||
func find_nearest_enemy():
|
|
||||||
var nearest = null
|
|
||||||
var min_distance = INF
|
|
||||||
|
|
||||||
for enemy in enemies:
|
|
||||||
for player in players:
|
|
||||||
var distance = enemy.global_position.distance_to(player.global_position)
|
|
||||||
if distance < min_distance:
|
|
||||||
min_distance = distance
|
|
||||||
nearest = enemy
|
|
||||||
|
|
||||||
# ✅ 正确示例：优化算法
|
|
||||||
func find_nearest_enemy():
|
|
||||||
var player_pos = player.global_position
|
|
||||||
var nearest = null
|
|
||||||
var min_distance = INF
|
|
||||||
|
|
||||||
for enemy in enemies:
|
|
||||||
var distance = enemy.global_position.distance_squared_to(player_pos)
|
|
||||||
if distance < min_distance:
|
|
||||||
min_distance = distance
|
|
||||||
nearest = enemy
|
|
||||||
```
|
|
||||||
|
|
||||||
### 事件优化
|
|
||||||
```gdscript
|
|
||||||
# 使用信号代替轮询
|
|
||||||
# ❌ 错误示例：轮询检查
|
|
||||||
func _process(delta):
|
|
||||||
if player.health <= 0:
|
|
||||||
game_over()
|
|
||||||
|
|
||||||
# ✅ 正确示例：事件驱动
|
|
||||||
func _ready():
|
|
||||||
player.health_changed.connect(_on_health_changed)
|
|
||||||
|
|
||||||
func _on_health_changed(new_health: int):
|
|
||||||
if new_health <= 0:
|
|
||||||
game_over()
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🎮 游戏逻辑优化
|
|
||||||
|
|
||||||
### 状态机优化
|
|
||||||
```gdscript
|
|
||||||
# StateMachine.gd
|
|
||||||
class_name StateMachine
|
|
||||||
extends Node
|
|
||||||
|
|
||||||
var current_state: State
|
|
||||||
var states: Dictionary = {}
|
|
||||||
|
|
||||||
func change_state(state_name: String):
|
|
||||||
if current_state:
|
|
||||||
current_state.exit()
|
|
||||||
|
|
||||||
current_state = states[state_name]
|
|
||||||
current_state.enter()
|
|
||||||
|
|
||||||
func _process(delta):
|
|
||||||
if current_state:
|
|
||||||
current_state.update(delta)
|
|
||||||
```
|
|
||||||
|
|
||||||
### AI优化
|
|
||||||
```gdscript
|
|
||||||
# EnemyAI.gd
|
|
||||||
extends Node
|
|
||||||
|
|
||||||
var update_interval: float = 0.2 # 每200ms更新一次AI
|
|
||||||
var update_timer: float = 0.0
|
|
||||||
|
|
||||||
func _process(delta):
|
|
||||||
update_timer += delta
|
|
||||||
if update_timer >= update_interval:
|
|
||||||
update_ai()
|
|
||||||
update_timer = 0.0
|
|
||||||
|
|
||||||
func update_ai():
|
|
||||||
# AI逻辑更新
|
|
||||||
# 路径寻找
|
|
||||||
# 决策制定
|
|
||||||
pass
|
|
||||||
```
|
|
||||||
|
|
||||||
### 碰撞检测优化
|
|
||||||
```gdscript
|
|
||||||
# 使用空间分区优化碰撞检测
|
|
||||||
class_name SpatialGrid
|
|
||||||
extends Node
|
|
||||||
|
|
||||||
var grid_size: int = 64
|
|
||||||
var grid: Dictionary = {}
|
|
||||||
|
|
||||||
func add_object(obj: Node2D):
|
|
||||||
var grid_pos = Vector2(
|
|
||||||
int(obj.global_position.x / grid_size),
|
|
||||||
int(obj.global_position.y / grid_size)
|
|
||||||
)
|
|
||||||
|
|
||||||
if not grid.has(grid_pos):
|
|
||||||
grid[grid_pos] = []
|
|
||||||
|
|
||||||
grid[grid_pos].append(obj)
|
|
||||||
|
|
||||||
func get_nearby_objects(pos: Vector2) -> Array:
|
|
||||||
var grid_pos = Vector2(
|
|
||||||
int(pos.x / grid_size),
|
|
||||||
int(pos.y / grid_size)
|
|
||||||
)
|
|
||||||
|
|
||||||
var nearby = []
|
|
||||||
for x in range(-1, 2):
|
|
||||||
for y in range(-1, 2):
|
|
||||||
var check_pos = grid_pos + Vector2(x, y)
|
|
||||||
if grid.has(check_pos):
|
|
||||||
nearby.append_array(grid[check_pos])
|
|
||||||
|
|
||||||
return nearby
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🌐 网络优化
|
|
||||||
|
|
||||||
### 数据压缩
|
|
||||||
```gdscript
|
|
||||||
# NetworkManager.gd
|
|
||||||
func send_player_data(data: Dictionary):
|
|
||||||
# 只发送变化的数据
|
|
||||||
var delta_data = get_changed_data(data)
|
|
||||||
|
|
||||||
# 压缩数据
|
|
||||||
var compressed = compress_data(delta_data)
|
|
||||||
|
|
||||||
# 发送数据
|
|
||||||
send_to_server(compressed)
|
|
||||||
|
|
||||||
func compress_data(data: Dictionary) -> PackedByteArray:
|
|
||||||
var json_string = JSON.stringify(data)
|
|
||||||
var bytes = json_string.to_utf8_buffer()
|
|
||||||
return bytes.compress(FileAccess.COMPRESSION_GZIP)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 批量更新
|
|
||||||
```gdscript
|
|
||||||
# 批量发送网络更新
|
|
||||||
var pending_updates: Array = []
|
|
||||||
var update_timer: float = 0.0
|
|
||||||
|
|
||||||
func _process(delta):
|
|
||||||
update_timer += delta
|
|
||||||
if update_timer >= 0.05: # 每50ms发送一次
|
|
||||||
if pending_updates.size() > 0:
|
|
||||||
send_batch_updates(pending_updates)
|
|
||||||
pending_updates.clear()
|
|
||||||
update_timer = 0.0
|
|
||||||
|
|
||||||
func queue_update(update_data: Dictionary):
|
|
||||||
pending_updates.append(update_data)
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📊 性能监控
|
|
||||||
|
|
||||||
### FPS监控
|
|
||||||
```gdscript
|
|
||||||
# FPSMonitor.gd
|
|
||||||
extends Control
|
|
||||||
|
|
||||||
@onready var fps_label: Label = $FPSLabel
|
|
||||||
var fps_history: Array = []
|
|
||||||
|
|
||||||
func _process(delta):
|
|
||||||
var current_fps = Engine.get_frames_per_second()
|
|
||||||
fps_history.append(current_fps)
|
|
||||||
|
|
||||||
if fps_history.size() > 60: # 保留60帧历史
|
|
||||||
fps_history.pop_front()
|
|
||||||
|
|
||||||
var avg_fps = 0
|
|
||||||
for fps in fps_history:
|
|
||||||
avg_fps += fps
|
|
||||||
avg_fps /= fps_history.size()
|
|
||||||
|
|
||||||
fps_label.text = "FPS: %d (平均: %d)" % [current_fps, avg_fps]
|
|
||||||
|
|
||||||
# FPS过低时警告
|
|
||||||
if avg_fps < 30:
|
|
||||||
modulate = Color.RED
|
|
||||||
elif avg_fps < 50:
|
|
||||||
modulate = Color.YELLOW
|
|
||||||
else:
|
|
||||||
modulate = Color.WHITE
|
|
||||||
```
|
|
||||||
|
|
||||||
### 性能分析器
|
|
||||||
```gdscript
|
|
||||||
# Profiler.gd
|
|
||||||
class_name Profiler
|
|
||||||
extends Node
|
|
||||||
|
|
||||||
var timers: Dictionary = {}
|
|
||||||
|
|
||||||
func start_timer(name: String):
|
|
||||||
timers[name] = Time.get_time_dict_from_system()
|
|
||||||
|
|
||||||
func end_timer(name: String) -> float:
|
|
||||||
if not timers.has(name):
|
|
||||||
return 0.0
|
|
||||||
|
|
||||||
var start_time = timers[name]
|
|
||||||
var end_time = Time.get_time_dict_from_system()
|
|
||||||
|
|
||||||
var duration = (end_time.hour * 3600 + end_time.minute * 60 + end_time.second) - \
|
|
||||||
(start_time.hour * 3600 + start_time.minute * 60 + start_time.second)
|
|
||||||
|
|
||||||
timers.erase(name)
|
|
||||||
return duration
|
|
||||||
|
|
||||||
# 使用示例
|
|
||||||
func expensive_function():
|
|
||||||
Profiler.start_timer("expensive_function")
|
|
||||||
|
|
||||||
# 执行耗时操作
|
|
||||||
for i in range(10000):
|
|
||||||
pass
|
|
||||||
|
|
||||||
var duration = Profiler.end_timer("expensive_function")
|
|
||||||
print("函数执行时间: ", duration, "秒")
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🛠️ 调试工具
|
|
||||||
|
|
||||||
### 性能调试面板
|
|
||||||
```gdscript
|
|
||||||
# DebugPanel.gd
|
|
||||||
extends Control
|
|
||||||
|
|
||||||
@onready var memory_label: Label = $VBox/MemoryLabel
|
|
||||||
@onready var fps_label: Label = $VBox/FPSLabel
|
|
||||||
@onready var objects_label: Label = $VBox/ObjectsLabel
|
|
||||||
|
|
||||||
func _process(delta):
|
|
||||||
# 更新内存使用
|
|
||||||
var memory = OS.get_static_memory_usage_by_type()
|
|
||||||
memory_label.text = "内存: %.1f MB" % (memory / 1024.0 / 1024.0)
|
|
||||||
|
|
||||||
# 更新FPS
|
|
||||||
fps_label.text = "FPS: %d" % Engine.get_frames_per_second()
|
|
||||||
|
|
||||||
# 更新对象数量
|
|
||||||
var object_count = get_tree().get_node_count()
|
|
||||||
objects_label.text = "对象数: %d" % object_count
|
|
||||||
```
|
|
||||||
|
|
||||||
### 热点分析
|
|
||||||
```gdscript
|
|
||||||
# HotspotAnalyzer.gd
|
|
||||||
extends Node
|
|
||||||
|
|
||||||
var function_calls: Dictionary = {}
|
|
||||||
var function_times: Dictionary = {}
|
|
||||||
|
|
||||||
func profile_function(func_name: String, callable: Callable):
|
|
||||||
var start_time = Time.get_time_dict_from_system()
|
|
||||||
|
|
||||||
callable.call()
|
|
||||||
|
|
||||||
var end_time = Time.get_time_dict_from_system()
|
|
||||||
var duration = (end_time.hour * 3600 + end_time.minute * 60 + end_time.second) - \
|
|
||||||
(start_time.hour * 3600 + start_time.minute * 60 + start_time.second)
|
|
||||||
|
|
||||||
if not function_calls.has(func_name):
|
|
||||||
function_calls[func_name] = 0
|
|
||||||
function_times[func_name] = 0.0
|
|
||||||
|
|
||||||
function_calls[func_name] += 1
|
|
||||||
function_times[func_name] += duration
|
|
||||||
|
|
||||||
func print_profile_report():
|
|
||||||
print("=== 性能分析报告 ===")
|
|
||||||
for func_name in function_calls.keys():
|
|
||||||
var calls = function_calls[func_name]
|
|
||||||
var total_time = function_times[func_name]
|
|
||||||
var avg_time = total_time / calls
|
|
||||||
|
|
||||||
print("%s: 调用%d次, 总时间%.3fs, 平均%.3fs" % [func_name, calls, total_time, avg_time])
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📚 最佳实践
|
|
||||||
|
|
||||||
### 开发阶段
|
|
||||||
1. **早期优化** - 在设计阶段考虑性能
|
|
||||||
2. **渐进开发** - 逐步添加功能并测试性能
|
|
||||||
3. **定期测试** - 定期进行性能测试
|
|
||||||
4. **文档记录** - 记录性能优化决策
|
|
||||||
|
|
||||||
### 测试阶段
|
|
||||||
1. **多设备测试** - 在不同性能设备上测试
|
|
||||||
2. **压力测试** - 测试极限情况下的性能
|
|
||||||
3. **长时间测试** - 测试内存泄漏和性能衰减
|
|
||||||
4. **用户测试** - 收集真实用户的性能反馈
|
|
||||||
|
|
||||||
### 发布阶段
|
|
||||||
1. **性能监控** - 监控线上性能指标
|
|
||||||
2. **快速响应** - 快速修复性能问题
|
|
||||||
3. **持续优化** - 根据数据持续优化
|
|
||||||
4. **版本对比** - 对比不同版本的性能表现
|
|
||||||
|
|
||||||
## 🔍 常见问题
|
|
||||||
|
|
||||||
### Q: 如何识别性能瓶颈？
|
|
||||||
A: 使用Godot的内置分析器，添加自定义性能监控，分析FPS和内存使用情况。
|
|
||||||
|
|
||||||
### Q: 内存使用过高怎么办？
|
|
||||||
A: 检查资源加载，使用对象池，及时释放不需要的对象，优化纹理大小。
|
|
||||||
|
|
||||||
### Q: 如何优化大量对象的渲染？
|
|
||||||
A: 使用MultiMesh批处理，实现视锥剔除，使用LOD系统，合并相同材质的对象。
|
|
||||||
|
|
||||||
### Q: 网络延迟如何优化？
|
|
||||||
A: 减少网络请求频率，压缩传输数据，使用预测和插值，实现客户端预测。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**记住：性能优化是一个持续的过程，需要在开发的各个阶段都保持关注！**
|
|
||||||
@@ -1,464 +0,0 @@
|
|||||||
# 模块开发指南
|
|
||||||
|
|
||||||
本文档详细说明如何在 Whale Town 项目中开发新的游戏模块。
|
|
||||||
|
|
||||||
## 🎯 模块设计原则
|
|
||||||
|
|
||||||
### 核心原则
|
|
||||||
1. **单一职责** - 每个模块只负责一个特定的游戏功能
|
|
||||||
2. **高内聚低耦合** - 模块内部紧密相关，模块间松散耦合
|
|
||||||
3. **可复用性** - 模块应该能在不同场景中复用
|
|
||||||
4. **标准化接口** - 统一的模块接口和通信方式
|
|
||||||
5. **测试友好** - 模块应该易于测试和调试
|
|
||||||
|
|
||||||
### 模块分类
|
|
||||||
- **UI模块** - 用户界面组件和交互逻辑
|
|
||||||
- **游戏逻辑模块** - 角色、战斗、对话等核心功能
|
|
||||||
- **系统模块** - 存档、设置、网络等系统功能
|
|
||||||
- **工具模块** - 通用工具和辅助功能
|
|
||||||
|
|
||||||
## 🏗️ 模块结构
|
|
||||||
|
|
||||||
### 标准目录结构
|
|
||||||
```
|
|
||||||
module/YourModule/
|
|
||||||
├── YourModule.gd # 主模块脚本
|
|
||||||
├── components/ # 子组件
|
|
||||||
│ ├── Component1.gd
|
|
||||||
│ └── Component2.gd
|
|
||||||
├── data/ # 模块数据
|
|
||||||
│ ├── module_config.json
|
|
||||||
│ └── default_data.json
|
|
||||||
├── scenes/ # 模块场景
|
|
||||||
│ ├── YourModule.tscn
|
|
||||||
│ └── components/
|
|
||||||
├── tests/ # 模块测试
|
|
||||||
│ ├── test_your_module.gd
|
|
||||||
│ └── test_components.gd
|
|
||||||
└── README.md # 模块文档
|
|
||||||
```
|
|
||||||
|
|
||||||
### 文件命名规范
|
|
||||||
- **主模块脚本**: `ModuleName.gd` (PascalCase)
|
|
||||||
- **组件脚本**: `ComponentName.gd` (PascalCase)
|
|
||||||
- **场景文件**: `module_name.tscn` (snake_case)
|
|
||||||
- **数据文件**: `snake_case.json`
|
|
||||||
- **测试文件**: `test_module_name.gd`
|
|
||||||
|
|
||||||
## 📝 模块开发步骤
|
|
||||||
|
|
||||||
### 第一步：创建模块结构
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 创建模块目录
|
|
||||||
mkdir module/YourModule
|
|
||||||
cd module/YourModule
|
|
||||||
|
|
||||||
# 创建子目录
|
|
||||||
mkdir components data scenes tests
|
|
||||||
|
|
||||||
# 创建主要文件
|
|
||||||
touch YourModule.gd
|
|
||||||
touch README.md
|
|
||||||
touch data/module_config.json
|
|
||||||
```
|
|
||||||
|
|
||||||
### 第二步：实现模块接口
|
|
||||||
|
|
||||||
每个模块都应该实现标准的模块接口：
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# YourModule.gd
|
|
||||||
extends Node
|
|
||||||
class_name YourModule
|
|
||||||
|
|
||||||
# 模块信息
|
|
||||||
const MODULE_NAME = "YourModule"
|
|
||||||
const MODULE_VERSION = "1.0.0"
|
|
||||||
const MODULE_AUTHOR = "Your Name"
|
|
||||||
|
|
||||||
# 模块状态
|
|
||||||
enum ModuleState {
|
|
||||||
UNINITIALIZED,
|
|
||||||
INITIALIZING,
|
|
||||||
READY,
|
|
||||||
ERROR
|
|
||||||
}
|
|
||||||
|
|
||||||
var current_state: ModuleState = ModuleState.UNINITIALIZED
|
|
||||||
var config: Dictionary = {}
|
|
||||||
var is_enabled: bool = true
|
|
||||||
|
|
||||||
# 必需接口方法
|
|
||||||
func initialize() -> bool:
|
|
||||||
"""初始化模块"""
|
|
||||||
current_state = ModuleState.INITIALIZING
|
|
||||||
|
|
||||||
# 加载配置
|
|
||||||
if not _load_config():
|
|
||||||
current_state = ModuleState.ERROR
|
|
||||||
return false
|
|
||||||
|
|
||||||
# 初始化组件
|
|
||||||
if not _initialize_components():
|
|
||||||
current_state = ModuleState.ERROR
|
|
||||||
return false
|
|
||||||
|
|
||||||
# 注册事件监听
|
|
||||||
_register_events()
|
|
||||||
|
|
||||||
current_state = ModuleState.READY
|
|
||||||
return true
|
|
||||||
|
|
||||||
func cleanup():
|
|
||||||
"""清理模块资源"""
|
|
||||||
_unregister_events()
|
|
||||||
_cleanup_components()
|
|
||||||
current_state = ModuleState.UNINITIALIZED
|
|
||||||
|
|
||||||
func get_module_info() -> Dictionary:
|
|
||||||
"""获取模块信息"""
|
|
||||||
return {
|
|
||||||
"name": MODULE_NAME,
|
|
||||||
"version": MODULE_VERSION,
|
|
||||||
"author": MODULE_AUTHOR,
|
|
||||||
"state": current_state,
|
|
||||||
"enabled": is_enabled
|
|
||||||
}
|
|
||||||
|
|
||||||
# 私有方法
|
|
||||||
func _load_config() -> bool:
|
|
||||||
"""加载模块配置"""
|
|
||||||
var config_path = ProjectPaths.get_module_config_path(MODULE_NAME)
|
|
||||||
if not FileAccess.file_exists(config_path):
|
|
||||||
print("警告: 模块配置文件不存在: ", config_path)
|
|
||||||
return true # 使用默认配置
|
|
||||||
|
|
||||||
var file = FileAccess.open(config_path, FileAccess.READ)
|
|
||||||
if file == null:
|
|
||||||
print("错误: 无法读取配置文件: ", config_path)
|
|
||||||
return false
|
|
||||||
|
|
||||||
var json_string = file.get_as_text()
|
|
||||||
file.close()
|
|
||||||
|
|
||||||
var json = JSON.new()
|
|
||||||
var parse_result = json.parse(json_string)
|
|
||||||
if parse_result != OK:
|
|
||||||
print("错误: 配置文件JSON格式错误: ", config_path)
|
|
||||||
return false
|
|
||||||
|
|
||||||
config = json.data
|
|
||||||
return true
|
|
||||||
|
|
||||||
func _initialize_components() -> bool:
|
|
||||||
"""初始化子组件"""
|
|
||||||
# 在这里初始化模块的子组件
|
|
||||||
return true
|
|
||||||
|
|
||||||
func _cleanup_components():
|
|
||||||
"""清理子组件"""
|
|
||||||
# 在这里清理模块的子组件
|
|
||||||
pass
|
|
||||||
|
|
||||||
func _register_events():
|
|
||||||
"""注册事件监听"""
|
|
||||||
# 使用EventSystem注册需要监听的事件
|
|
||||||
# EventSystem.connect_event("event_name", _on_event_handler)
|
|
||||||
pass
|
|
||||||
|
|
||||||
func _unregister_events():
|
|
||||||
"""取消事件监听"""
|
|
||||||
# 取消所有事件监听
|
|
||||||
# EventSystem.disconnect_event("event_name", _on_event_handler)
|
|
||||||
pass
|
|
||||||
```
|
|
||||||
|
|
||||||
### 第三步：创建模块配置
|
|
||||||
|
|
||||||
```json
|
|
||||||
// data/module_config.json
|
|
||||||
{
|
|
||||||
"module_name": "YourModule",
|
|
||||||
"version": "1.0.0",
|
|
||||||
"enabled": true,
|
|
||||||
"dependencies": [],
|
|
||||||
"settings": {
|
|
||||||
"auto_initialize": true,
|
|
||||||
"debug_mode": false
|
|
||||||
},
|
|
||||||
"resources": {
|
|
||||||
"textures": [],
|
|
||||||
"sounds": [],
|
|
||||||
"data_files": []
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 第四步：实现具体功能
|
|
||||||
|
|
||||||
根据模块类型实现具体功能：
|
|
||||||
|
|
||||||
#### UI模块示例
|
|
||||||
```gdscript
|
|
||||||
# UI模块应该继承Control或其子类
|
|
||||||
extends Control
|
|
||||||
class_name UIModule
|
|
||||||
|
|
||||||
signal ui_event_triggered(event_name: String, data: Dictionary)
|
|
||||||
|
|
||||||
func show_ui():
|
|
||||||
"""显示UI"""
|
|
||||||
visible = true
|
|
||||||
# 播放显示动画
|
|
||||||
_play_show_animation()
|
|
||||||
|
|
||||||
func hide_ui():
|
|
||||||
"""隐藏UI"""
|
|
||||||
# 播放隐藏动画
|
|
||||||
_play_hide_animation()
|
|
||||||
await get_tree().create_timer(0.3).timeout
|
|
||||||
visible = false
|
|
||||||
|
|
||||||
func _play_show_animation():
|
|
||||||
"""播放显示动画"""
|
|
||||||
var tween = create_tween()
|
|
||||||
modulate.a = 0.0
|
|
||||||
tween.tween_property(self, "modulate:a", 1.0, 0.3)
|
|
||||||
|
|
||||||
func _play_hide_animation():
|
|
||||||
"""播放隐藏动画"""
|
|
||||||
var tween = create_tween()
|
|
||||||
tween.tween_property(self, "modulate:a", 0.0, 0.3)
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 游戏逻辑模块示例
|
|
||||||
```gdscript
|
|
||||||
# 游戏逻辑模块
|
|
||||||
extends Node
|
|
||||||
class_name GameLogicModule
|
|
||||||
|
|
||||||
signal state_changed(old_state: String, new_state: String)
|
|
||||||
signal data_updated(data_type: String, new_data: Dictionary)
|
|
||||||
|
|
||||||
var module_data: Dictionary = {}
|
|
||||||
var current_state: String = "idle"
|
|
||||||
|
|
||||||
func process_game_logic(delta: float):
|
|
||||||
"""处理游戏逻辑"""
|
|
||||||
match current_state:
|
|
||||||
"idle":
|
|
||||||
_process_idle_state(delta)
|
|
||||||
"active":
|
|
||||||
_process_active_state(delta)
|
|
||||||
"paused":
|
|
||||||
_process_paused_state(delta)
|
|
||||||
|
|
||||||
func change_state(new_state: String):
|
|
||||||
"""改变模块状态"""
|
|
||||||
var old_state = current_state
|
|
||||||
current_state = new_state
|
|
||||||
state_changed.emit(old_state, new_state)
|
|
||||||
|
|
||||||
func update_data(data_type: String, new_data: Dictionary):
|
|
||||||
"""更新模块数据"""
|
|
||||||
module_data[data_type] = new_data
|
|
||||||
data_updated.emit(data_type, new_data)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 第五步：添加测试
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# tests/test_your_module.gd
|
|
||||||
extends GutTest
|
|
||||||
|
|
||||||
var module: YourModule
|
|
||||||
|
|
||||||
func before_each():
|
|
||||||
module = YourModule.new()
|
|
||||||
add_child(module)
|
|
||||||
|
|
||||||
func after_each():
|
|
||||||
module.queue_free()
|
|
||||||
|
|
||||||
func test_module_initialization():
|
|
||||||
assert_true(module.initialize(), "模块应该能够正确初始化")
|
|
||||||
assert_eq(module.current_state, YourModule.ModuleState.READY, "初始化后状态应该为READY")
|
|
||||||
|
|
||||||
func test_module_cleanup():
|
|
||||||
module.initialize()
|
|
||||||
module.cleanup()
|
|
||||||
assert_eq(module.current_state, YourModule.ModuleState.UNINITIALIZED, "清理后状态应该为UNINITIALIZED")
|
|
||||||
|
|
||||||
func test_module_info():
|
|
||||||
var info = module.get_module_info()
|
|
||||||
assert_true(info.has("name"), "模块信息应该包含名称")
|
|
||||||
assert_true(info.has("version"), "模块信息应该包含版本")
|
|
||||||
assert_eq(info.name, "YourModule", "模块名称应该正确")
|
|
||||||
```
|
|
||||||
|
|
||||||
### 第六步：编写文档
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# YourModule 模块
|
|
||||||
|
|
||||||
## 功能描述
|
|
||||||
简要描述模块的主要功能和用途。
|
|
||||||
|
|
||||||
## 使用方法
|
|
||||||
```gdscript
|
|
||||||
# 创建和初始化模块
|
|
||||||
var your_module = YourModule.new()
|
|
||||||
add_child(your_module)
|
|
||||||
your_module.initialize()
|
|
||||||
|
|
||||||
# 使用模块功能
|
|
||||||
your_module.some_function()
|
|
||||||
```
|
|
||||||
|
|
||||||
## API参考
|
|
||||||
### 公共方法
|
|
||||||
- `initialize() -> bool` - 初始化模块
|
|
||||||
- `cleanup()` - 清理模块资源
|
|
||||||
- `get_module_info() -> Dictionary` - 获取模块信息
|
|
||||||
|
|
||||||
### 信号
|
|
||||||
- `signal_name(param: Type)` - 信号描述
|
|
||||||
|
|
||||||
## 配置选项
|
|
||||||
描述模块的配置选项和默认值。
|
|
||||||
|
|
||||||
## 依赖关系
|
|
||||||
列出模块的依赖项。
|
|
||||||
|
|
||||||
## 注意事项
|
|
||||||
使用模块时需要注意的事项。
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔧 模块集成
|
|
||||||
|
|
||||||
### 在场景中使用模块
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# 在场景脚本中使用模块
|
|
||||||
extends Control
|
|
||||||
|
|
||||||
var inventory_module: InventoryModule
|
|
||||||
var dialogue_module: DialogueModule
|
|
||||||
|
|
||||||
func _ready():
|
|
||||||
# 创建并初始化模块
|
|
||||||
inventory_module = InventoryModule.new()
|
|
||||||
add_child(inventory_module)
|
|
||||||
inventory_module.initialize()
|
|
||||||
|
|
||||||
dialogue_module = DialogueModule.new()
|
|
||||||
add_child(dialogue_module)
|
|
||||||
dialogue_module.initialize()
|
|
||||||
|
|
||||||
# 连接模块事件
|
|
||||||
inventory_module.item_selected.connect(_on_item_selected)
|
|
||||||
dialogue_module.dialogue_finished.connect(_on_dialogue_finished)
|
|
||||||
|
|
||||||
func _on_item_selected(item_data: Dictionary):
|
|
||||||
print("选中物品: ", item_data.name)
|
|
||||||
|
|
||||||
func _on_dialogue_finished():
|
|
||||||
print("对话结束")
|
|
||||||
```
|
|
||||||
|
|
||||||
### 模块间通信
|
|
||||||
|
|
||||||
推荐使用EventSystem进行模块间通信：
|
|
||||||
|
|
||||||
```gdscript
|
|
||||||
# 发送事件
|
|
||||||
EventSystem.emit_event("inventory_item_used", {
|
|
||||||
"item_id": "potion_001",
|
|
||||||
"quantity": 1
|
|
||||||
})
|
|
||||||
|
|
||||||
# 监听事件
|
|
||||||
EventSystem.connect_event("inventory_item_used", _on_item_used)
|
|
||||||
|
|
||||||
func _on_item_used(data: Dictionary):
|
|
||||||
print("使用了物品: ", data.item_id)
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🧪 测试和调试
|
|
||||||
|
|
||||||
### 单元测试
|
|
||||||
每个模块都应该有对应的单元测试：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 运行模块测试
|
|
||||||
godot --headless --script tests/test_your_module.gd
|
|
||||||
```
|
|
||||||
|
|
||||||
### 调试技巧
|
|
||||||
1. **使用print语句** - 在关键位置添加调试输出
|
|
||||||
2. **断点调试** - 在Godot编辑器中设置断点
|
|
||||||
3. **状态监控** - 实时监控模块状态变化
|
|
||||||
4. **事件追踪** - 记录事件的发送和接收
|
|
||||||
|
|
||||||
### 性能监控
|
|
||||||
```gdscript
|
|
||||||
# 性能监控示例
|
|
||||||
func _process(delta):
|
|
||||||
var start_time = Time.get_time_dict_from_system()
|
|
||||||
|
|
||||||
# 执行模块逻辑
|
|
||||||
process_module_logic(delta)
|
|
||||||
|
|
||||||
var end_time = Time.get_time_dict_from_system()
|
|
||||||
var execution_time = (end_time.hour * 3600 + end_time.minute * 60 + end_time.second) - \
|
|
||||||
(start_time.hour * 3600 + start_time.minute * 60 + start_time.second)
|
|
||||||
|
|
||||||
if execution_time > 0.016: # 超过16ms
|
|
||||||
print("警告: 模块执行时间过长: ", execution_time, "秒")
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📚 最佳实践
|
|
||||||
|
|
||||||
### 代码质量
|
|
||||||
1. **遵循命名规范** - 使用清晰、一致的命名
|
|
||||||
2. **添加详细注释** - 解释复杂逻辑和设计决策
|
|
||||||
3. **错误处理** - 妥善处理各种异常情况
|
|
||||||
4. **资源管理** - 及时释放不需要的资源
|
|
||||||
|
|
||||||
### 性能优化
|
|
||||||
1. **避免频繁的内存分配** - 重用对象和数据结构
|
|
||||||
2. **合理使用信号** - 避免过多的信号连接
|
|
||||||
3. **批量处理** - 将多个操作合并处理
|
|
||||||
4. **延迟加载** - 按需加载资源和数据
|
|
||||||
|
|
||||||
### 可维护性
|
|
||||||
1. **模块化设计** - 保持模块的独立性
|
|
||||||
2. **版本控制** - 记录模块的版本变化
|
|
||||||
3. **文档更新** - 及时更新模块文档
|
|
||||||
4. **向后兼容** - 考虑API的向后兼容性
|
|
||||||
|
|
||||||
## 🔍 常见问题
|
|
||||||
|
|
||||||
### Q: 如何处理模块依赖？
|
|
||||||
A: 在模块配置中声明依赖，在初始化时检查依赖是否满足。
|
|
||||||
|
|
||||||
### Q: 模块间如何共享数据？
|
|
||||||
A: 使用EventSystem传递数据，或通过GameManager等全局管理器。
|
|
||||||
|
|
||||||
### Q: 如何调试模块问题？
|
|
||||||
A: 使用Godot的调试工具，添加日志输出，编写单元测试。
|
|
||||||
|
|
||||||
### Q: 模块性能如何优化？
|
|
||||||
A: 避免在_process中执行重复计算，使用对象池，合理管理资源。
|
|
||||||
|
|
||||||
## 📖 参考资料
|
|
||||||
|
|
||||||
- [Godot官方文档](https://docs.godotengine.org/)
|
|
||||||
- [项目命名规范](./naming_convention.md)
|
|
||||||
- [代码注释规范](./code_comment_guide.md)
|
|
||||||
- [Git提交规范](./git_commit_guide.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**记住：好的模块设计是项目成功的关键！**
|
|
||||||
@@ -1,553 +0,0 @@
|
|||||||
# Web部署完整指南
|
|
||||||
|
|
||||||
**版本**: 1.0.0
|
|
||||||
**更新时间**: 2025-12-25
|
|
||||||
**适用于**: Godot 4.5+ 项目
|
|
||||||
|
|
||||||
## 📋 目录
|
|
||||||
|
|
||||||
1. [导出准备](#导出准备)
|
|
||||||
2. [Godot编辑器配置](#godot编辑器配置)
|
|
||||||
3. [自动化导出脚本](#自动化导出脚本)
|
|
||||||
4. [本地测试](#本地测试)
|
|
||||||
5. [生产环境部署](#生产环境部署)
|
|
||||||
6. [服务器配置](#服务器配置)
|
|
||||||
7. [性能优化](#性能优化)
|
|
||||||
8. [常见问题解决](#常见问题解决)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🚀 导出准备
|
|
||||||
|
|
||||||
### 系统要求
|
|
||||||
- Godot 4.5+
|
|
||||||
- Python 3.x（用于本地测试服务器）
|
|
||||||
- Web服务器（Apache/Nginx/IIS等）
|
|
||||||
|
|
||||||
### 项目结构检查
|
|
||||||
确保项目结构完整：
|
|
||||||
```
|
|
||||||
whaleTown/
|
|
||||||
├── assets/ # 游戏资源
|
|
||||||
├── core/ # 核心系统
|
|
||||||
├── scenes/ # 场景文件
|
|
||||||
├── scripts/ # 脚本文件
|
|
||||||
├── docs/ # 文档
|
|
||||||
├── build/ # 导出目录（自动创建）
|
|
||||||
└── project.godot # 项目配置
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ⚙️ Godot编辑器配置
|
|
||||||
|
|
||||||
### 1. 下载导出模板
|
|
||||||
1. 打开Godot编辑器
|
|
||||||
2. 点击 `Project` → `Export...`
|
|
||||||
3. 点击 `Manage Export Templates...`
|
|
||||||
4. 点击 `Download and Install` 下载Godot 4.5导出模板
|
|
||||||
5. 等待下载完成
|
|
||||||
|
|
||||||
### 2. 创建Web导出预设
|
|
||||||
1. 在Export窗口中点击 `Add...`
|
|
||||||
2. 选择 `Web` 平台
|
|
||||||
3. 配置以下设置：
|
|
||||||
|
|
||||||
#### 基本设置
|
|
||||||
```
|
|
||||||
Name: Web
|
|
||||||
Export Path: build/web/index.html
|
|
||||||
Runnable: ✓ 启用
|
|
||||||
Dedicated Server: ✗ 禁用
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Web选项
|
|
||||||
```
|
|
||||||
Variant: release
|
|
||||||
Vram Texture Compression: ✓ 启用
|
|
||||||
Export Type: Regular
|
|
||||||
Custom HTML Shell: res://web_assets/custom_shell.html
|
|
||||||
Head Include: (留空，已在自定义模板中配置)
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 高级选项
|
|
||||||
```
|
|
||||||
Custom HTML Shell: res://web_assets/custom_shell.html
|
|
||||||
Progressive Web App: ✓ 启用（可选）
|
|
||||||
Icon 144x144: res://icon.svg
|
|
||||||
Icon 180x180: res://icon.svg
|
|
||||||
Icon 512x512: res://icon.svg
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. 项目设置优化
|
|
||||||
在 `Project Settings` 中配置：
|
|
||||||
|
|
||||||
#### 渲染设置
|
|
||||||
```
|
|
||||||
Rendering > Renderer:
|
|
||||||
- Rendering Method: gl_compatibility
|
|
||||||
- Rendering Method Mobile: gl_compatibility
|
|
||||||
|
|
||||||
Rendering > Textures:
|
|
||||||
- VRAM Compression > Import ETC2 ASTC: ✓
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 网络设置
|
|
||||||
```
|
|
||||||
Network > SSL:
|
|
||||||
- Certificates Bundle: (如果需要HTTPS API调用)
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔧 自动化导出脚本
|
|
||||||
|
|
||||||
### Windows批处理脚本
|
|
||||||
|
|
||||||
创建 `scripts/build_web.bat`：
|
|
||||||
```batch
|
|
||||||
@echo off
|
|
||||||
setlocal enabledelayedexpansion
|
|
||||||
|
|
||||||
echo ========================================
|
|
||||||
echo 鲸鱼镇 Web版本导出工具
|
|
||||||
echo ========================================
|
|
||||||
echo.
|
|
||||||
|
|
||||||
REM 配置变量
|
|
||||||
set "PROJECT_NAME=whaleTown"
|
|
||||||
set "BUILD_DIR=build\web"
|
|
||||||
set "GODOT_PATH=C:\Program Files\Godot\Godot.exe"
|
|
||||||
set "EXPORT_PRESET=Web"
|
|
||||||
|
|
||||||
REM 检查Godot是否存在
|
|
||||||
if not exist "%GODOT_PATH%" (
|
|
||||||
echo [错误] 未找到Godot可执行文件: %GODOT_PATH%
|
|
||||||
echo 请修改脚本中的GODOT_PATH变量
|
|
||||||
pause
|
|
||||||
exit /b 1
|
|
||||||
)
|
|
||||||
|
|
||||||
REM 创建构建目录
|
|
||||||
echo [信息] 创建构建目录...
|
|
||||||
if not exist "build" mkdir "build"
|
|
||||||
if not exist "%BUILD_DIR%" mkdir "%BUILD_DIR%"
|
|
||||||
|
|
||||||
REM 清理旧文件
|
|
||||||
echo [信息] 清理旧的导出文件...
|
|
||||||
if exist "%BUILD_DIR%\*" del /q "%BUILD_DIR%\*"
|
|
||||||
|
|
||||||
REM 导出项目
|
|
||||||
echo [信息] 开始导出Web版本...
|
|
||||||
echo 导出路径: %BUILD_DIR%\index.html
|
|
||||||
echo.
|
|
||||||
|
|
||||||
"%GODOT_PATH%" --headless --export-release "%EXPORT_PRESET%" "%BUILD_DIR%\index.html"
|
|
||||||
|
|
||||||
if %ERRORLEVEL% neq 0 (
|
|
||||||
echo [错误] 导出失败！错误代码: %ERRORLEVEL%
|
|
||||||
pause
|
|
||||||
exit /b %ERRORLEVEL%
|
|
||||||
)
|
|
||||||
|
|
||||||
REM 复制额外文件
|
|
||||||
echo [信息] 复制配置文件...
|
|
||||||
copy "web\*.json" "%BUILD_DIR%\" >nul 2>&1
|
|
||||||
copy "web\*.ico" "%BUILD_DIR%\" >nul 2>&1
|
|
||||||
|
|
||||||
REM 生成部署信息
|
|
||||||
echo [信息] 生成部署信息...
|
|
||||||
echo {> "%BUILD_DIR%\deploy_info.json"
|
|
||||||
echo "project": "%PROJECT_NAME%",>> "%BUILD_DIR%\deploy_info.json"
|
|
||||||
echo "version": "1.0.0",>> "%BUILD_DIR%\deploy_info.json"
|
|
||||||
echo "build_time": "%date% %time%",>> "%BUILD_DIR%\deploy_info.json"
|
|
||||||
echo "platform": "web">> "%BUILD_DIR%\deploy_info.json"
|
|
||||||
echo }>> "%BUILD_DIR%\deploy_info.json"
|
|
||||||
|
|
||||||
echo.
|
|
||||||
echo ========================================
|
|
||||||
echo 导出完成！
|
|
||||||
echo ========================================
|
|
||||||
echo 导出位置: %BUILD_DIR%\
|
|
||||||
echo 文件大小:
|
|
||||||
for %%f in ("%BUILD_DIR%\*") do echo %%~nxf: %%~zf bytes
|
|
||||||
|
|
||||||
echo.
|
|
||||||
echo 下一步:
|
|
||||||
echo 1. 运行 scripts\serve_web.bat 进行本地测试
|
|
||||||
echo 2. 将 %BUILD_DIR%\ 目录上传到Web服务器
|
|
||||||
echo.
|
|
||||||
pause
|
|
||||||
```
|
|
||||||
|
|
||||||
### 本地测试服务器脚本
|
|
||||||
|
|
||||||
创建 `scripts/serve_web.bat`：
|
|
||||||
```batch
|
|
||||||
@echo off
|
|
||||||
setlocal enabledelayedexpansion
|
|
||||||
|
|
||||||
echo ========================================
|
|
||||||
echo 鲸鱼镇 本地Web服务器
|
|
||||||
echo ========================================
|
|
||||||
echo.
|
|
||||||
|
|
||||||
set "BUILD_DIR=build\web"
|
|
||||||
set "PORT=8000"
|
|
||||||
|
|
||||||
REM 检查导出文件
|
|
||||||
if not exist "%BUILD_DIR%\index.html" (
|
|
||||||
echo [错误] 未找到Web导出文件！
|
|
||||||
echo 请先运行 scripts\build_web.bat 导出项目
|
|
||||||
echo.
|
|
||||||
pause
|
|
||||||
exit /b 1
|
|
||||||
)
|
|
||||||
|
|
||||||
REM 检查Python
|
|
||||||
python --version >nul 2>&1
|
|
||||||
if %ERRORLEVEL% neq 0 (
|
|
||||||
echo [错误] 未找到Python！
|
|
||||||
echo 请安装Python 3.x: https://python.org
|
|
||||||
echo.
|
|
||||||
pause
|
|
||||||
exit /b 1
|
|
||||||
)
|
|
||||||
|
|
||||||
REM 显示文件信息
|
|
||||||
echo [信息] Web文件信息:
|
|
||||||
for %%f in ("%BUILD_DIR%\*") do (
|
|
||||||
set "size=%%~zf"
|
|
||||||
set /a "size_mb=!size!/1024/1024"
|
|
||||||
echo %%~nxf: !size_mb! MB
|
|
||||||
)
|
|
||||||
|
|
||||||
echo.
|
|
||||||
echo [信息] 启动本地服务器...
|
|
||||||
echo 端口: %PORT%
|
|
||||||
echo 目录: %BUILD_DIR%
|
|
||||||
echo.
|
|
||||||
echo ========================================
|
|
||||||
echo 在浏览器中访问: http://localhost:%PORT%
|
|
||||||
echo 按 Ctrl+C 停止服务器
|
|
||||||
echo ========================================
|
|
||||||
echo.
|
|
||||||
|
|
||||||
REM 切换到构建目录并启动服务器
|
|
||||||
cd "%BUILD_DIR%"
|
|
||||||
python -m http.server %PORT%
|
|
||||||
|
|
||||||
echo.
|
|
||||||
echo 服务器已停止
|
|
||||||
pause
|
|
||||||
```
|
|
||||||
|
|
||||||
### Linux/macOS脚本
|
|
||||||
|
|
||||||
创建 `scripts/build_web.sh`：
|
|
||||||
```bash
|
|
||||||
#!/bin/bash
|
|
||||||
|
|
||||||
echo "========================================"
|
|
||||||
echo " 鲸鱼镇 Web版本导出工具"
|
|
||||||
echo "========================================"
|
|
||||||
echo
|
|
||||||
|
|
||||||
# 配置变量
|
|
||||||
PROJECT_NAME="whaleTown"
|
|
||||||
BUILD_DIR="build/web"
|
|
||||||
GODOT_PATH="/usr/local/bin/godot" # 根据实际安装路径修改
|
|
||||||
EXPORT_PRESET="Web"
|
|
||||||
|
|
||||||
# 检查Godot
|
|
||||||
if [ ! -f "$GODOT_PATH" ]; then
|
|
||||||
echo "[错误] 未找到Godot: $GODOT_PATH"
|
|
||||||
echo "请修改脚本中的GODOT_PATH变量"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
# 创建构建目录
|
|
||||||
echo "[信息] 创建构建目录..."
|
|
||||||
mkdir -p "$BUILD_DIR"
|
|
||||||
|
|
||||||
# 清理旧文件
|
|
||||||
echo "[信息] 清理旧文件..."
|
|
||||||
rm -f "$BUILD_DIR"/*
|
|
||||||
|
|
||||||
# 导出项目
|
|
||||||
echo "[信息] 开始导出Web版本..."
|
|
||||||
"$GODOT_PATH" --headless --export-release "$EXPORT_PRESET" "$BUILD_DIR/index.html"
|
|
||||||
|
|
||||||
if [ $? -ne 0 ]; then
|
|
||||||
echo "[错误] 导出失败！"
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
# 生成部署信息
|
|
||||||
echo "[信息] 生成部署信息..."
|
|
||||||
cat > "$BUILD_DIR/deploy_info.json" << EOF
|
|
||||||
{
|
|
||||||
"project": "$PROJECT_NAME",
|
|
||||||
"version": "1.0.0",
|
|
||||||
"build_time": "$(date)",
|
|
||||||
"platform": "web"
|
|
||||||
}
|
|
||||||
EOF
|
|
||||||
|
|
||||||
echo
|
|
||||||
echo "========================================"
|
|
||||||
echo " 导出完成！"
|
|
||||||
echo "========================================"
|
|
||||||
echo "导出位置: $BUILD_DIR/"
|
|
||||||
echo
|
|
||||||
echo "下一步:"
|
|
||||||
echo "1. 运行 scripts/serve_web.sh 进行本地测试"
|
|
||||||
echo "2. 将 $BUILD_DIR/ 目录上传到Web服务器"
|
|
||||||
echo
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🌐 生产环境部署
|
|
||||||
|
|
||||||
### 1. 文件上传清单
|
|
||||||
确保上传以下文件到Web服务器：
|
|
||||||
```
|
|
||||||
build/web/
|
|
||||||
├── index.html # 主HTML文件
|
|
||||||
├── index.js # JavaScript引导文件
|
|
||||||
├── index.wasm # WebAssembly主文件
|
|
||||||
├── index.pck # Godot资源包
|
|
||||||
├── index.worker.js # Web Worker文件
|
|
||||||
├── favicon.ico # 网站图标
|
|
||||||
└── deploy_info.json # 部署信息（可选）
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. 目录权限设置
|
|
||||||
```bash
|
|
||||||
# Linux服务器权限设置
|
|
||||||
chmod 644 build/web/*
|
|
||||||
chmod 755 build/web/
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. 域名配置
|
|
||||||
- 确保域名正确解析到服务器
|
|
||||||
- 配置SSL证书（推荐使用Let's Encrypt）
|
|
||||||
- 设置CDN加速（可选）
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔧 服务器配置
|
|
||||||
|
|
||||||
### Apache配置 (.htaccess)
|
|
||||||
```apache
|
|
||||||
# MIME类型配置
|
|
||||||
AddType application/wasm .wasm
|
|
||||||
AddType application/octet-stream .pck
|
|
||||||
AddType application/javascript .js
|
|
||||||
|
|
||||||
# 启用压缩
|
|
||||||
<IfModule mod_deflate.c>
|
|
||||||
AddOutputFilterByType DEFLATE text/html text/css application/javascript application/wasm
|
|
||||||
AddOutputFilterByType DEFLATE application/json application/xml
|
|
||||||
</IfModule>
|
|
||||||
|
|
||||||
# 缓存控制
|
|
||||||
<IfModule mod_expires.c>
|
|
||||||
ExpiresActive On
|
|
||||||
ExpiresByType application/wasm "access plus 1 month"
|
|
||||||
ExpiresByType application/octet-stream "access plus 1 month"
|
|
||||||
ExpiresByType application/javascript "access plus 1 week"
|
|
||||||
ExpiresByType text/html "access plus 1 hour"
|
|
||||||
</IfModule>
|
|
||||||
|
|
||||||
# CORS配置（如果需要）
|
|
||||||
<IfModule mod_headers.c>
|
|
||||||
Header set Access-Control-Allow-Origin "*"
|
|
||||||
Header set Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
|
|
||||||
Header set Access-Control-Allow-Headers "Content-Type, Authorization"
|
|
||||||
|
|
||||||
# SharedArrayBuffer支持
|
|
||||||
Header set Cross-Origin-Embedder-Policy "require-corp"
|
|
||||||
Header set Cross-Origin-Opener-Policy "same-origin"
|
|
||||||
</IfModule>
|
|
||||||
|
|
||||||
# 安全配置
|
|
||||||
<IfModule mod_headers.c>
|
|
||||||
Header always set X-Content-Type-Options nosniff
|
|
||||||
Header always set X-Frame-Options DENY
|
|
||||||
Header always set X-XSS-Protection "1; mode=block"
|
|
||||||
</IfModule>
|
|
||||||
```
|
|
||||||
|
|
||||||
### Nginx配置
|
|
||||||
```nginx
|
|
||||||
server {
|
|
||||||
listen 80;
|
|
||||||
listen 443 ssl http2;
|
|
||||||
server_name yourdomain.com;
|
|
||||||
|
|
||||||
# SSL配置
|
|
||||||
ssl_certificate /path/to/certificate.crt;
|
|
||||||
ssl_certificate_key /path/to/private.key;
|
|
||||||
|
|
||||||
root /var/www/whaletown/build/web;
|
|
||||||
index index.html;
|
|
||||||
|
|
||||||
# MIME类型
|
|
||||||
location ~* \.wasm$ {
|
|
||||||
add_header Content-Type application/wasm;
|
|
||||||
expires 1M;
|
|
||||||
add_header Cache-Control "public, immutable";
|
|
||||||
}
|
|
||||||
|
|
||||||
location ~* \.pck$ {
|
|
||||||
add_header Content-Type application/octet-stream;
|
|
||||||
expires 1M;
|
|
||||||
add_header Cache-Control "public, immutable";
|
|
||||||
}
|
|
||||||
|
|
||||||
location ~* \.js$ {
|
|
||||||
add_header Content-Type application/javascript;
|
|
||||||
expires 1w;
|
|
||||||
}
|
|
||||||
|
|
||||||
# 压缩配置
|
|
||||||
gzip on;
|
|
||||||
gzip_vary on;
|
|
||||||
gzip_min_length 1024;
|
|
||||||
gzip_types
|
|
||||||
text/html
|
|
||||||
text/css
|
|
||||||
application/javascript
|
|
||||||
application/wasm
|
|
||||||
application/json;
|
|
||||||
|
|
||||||
# CORS配置
|
|
||||||
add_header Access-Control-Allow-Origin "*" always;
|
|
||||||
add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
|
|
||||||
add_header Access-Control-Allow-Headers "Content-Type, Authorization" always;
|
|
||||||
|
|
||||||
# SharedArrayBuffer支持
|
|
||||||
add_header Cross-Origin-Embedder-Policy "require-corp" always;
|
|
||||||
add_header Cross-Origin-Opener-Policy "same-origin" always;
|
|
||||||
|
|
||||||
# 安全头
|
|
||||||
add_header X-Content-Type-Options nosniff always;
|
|
||||||
add_header X-Frame-Options DENY always;
|
|
||||||
add_header X-XSS-Protection "1; mode=block" always;
|
|
||||||
|
|
||||||
# 主页面
|
|
||||||
location / {
|
|
||||||
try_files $uri $uri/ /index.html;
|
|
||||||
}
|
|
||||||
|
|
||||||
# API代理（如果需要）
|
|
||||||
location /api/ {
|
|
||||||
proxy_pass https://whaletownend.xinghangee.icu/;
|
|
||||||
proxy_set_header Host $host;
|
|
||||||
proxy_set_header X-Real-IP $remote_addr;
|
|
||||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
||||||
proxy_set_header X-Forwarded-Proto $scheme;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ⚡ 性能优化
|
|
||||||
|
|
||||||
### 1. 资源优化
|
|
||||||
- **纹理压缩**: 启用VRAM纹理压缩
|
|
||||||
- **音频压缩**: 使用OGG格式，调整比特率
|
|
||||||
- **模型优化**: 减少多边形数量，优化LOD
|
|
||||||
|
|
||||||
### 2. 代码优化
|
|
||||||
```gdscript
|
|
||||||
# 在Web平台禁用不必要的功能
|
|
||||||
func _ready():
|
|
||||||
if OS.has_feature("web"):
|
|
||||||
# 禁用文件系统操作
|
|
||||||
# 优化渲染设置
|
|
||||||
get_viewport().render_target_update_mode = Viewport.UPDATE_WHEN_VISIBLE
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. 加载优化
|
|
||||||
- 使用资源预加载
|
|
||||||
- 实现渐进式加载
|
|
||||||
- 显示加载进度
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🐛 常见问题解决
|
|
||||||
|
|
||||||
### 1. SharedArrayBuffer错误
|
|
||||||
**问题**: 控制台显示SharedArrayBuffer相关错误
|
|
||||||
**解决**: 配置正确的HTTP头：
|
|
||||||
```
|
|
||||||
Cross-Origin-Embedder-Policy: require-corp
|
|
||||||
Cross-Origin-Opener-Policy: same-origin
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. 文件加载失败
|
|
||||||
**问题**: WASM或PCK文件加载失败
|
|
||||||
**解决**:
|
|
||||||
- 检查MIME类型配置
|
|
||||||
- 确保文件路径正确
|
|
||||||
- 检查服务器权限
|
|
||||||
|
|
||||||
### 3. API请求失败
|
|
||||||
**问题**: 网络请求被CORS阻止
|
|
||||||
**解决**:
|
|
||||||
- 配置服务器CORS头
|
|
||||||
- 使用API代理
|
|
||||||
- 检查API服务器配置
|
|
||||||
|
|
||||||
### 4. 性能问题
|
|
||||||
**问题**: Web版本运行缓慢
|
|
||||||
**解决**:
|
|
||||||
- 启用WebGL2
|
|
||||||
- 优化资源大小
|
|
||||||
- 使用性能分析工具
|
|
||||||
|
|
||||||
### 5. 音频问题
|
|
||||||
**问题**: 音频无法播放
|
|
||||||
**解决**:
|
|
||||||
- 用户交互后才能播放音频
|
|
||||||
- 使用Web兼容的音频格式
|
|
||||||
- 检查浏览器音频策略
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📊 部署检查清单
|
|
||||||
|
|
||||||
### 导出前检查
|
|
||||||
- [ ] Godot导出模板已安装
|
|
||||||
- [ ] Web导出预设已配置
|
|
||||||
- [ ] 项目设置已优化
|
|
||||||
- [ ] 资源文件已压缩
|
|
||||||
|
|
||||||
### 部署前检查
|
|
||||||
- [ ] 所有文件已上传
|
|
||||||
- [ ] 服务器MIME类型已配置
|
|
||||||
- [ ] CORS设置已配置
|
|
||||||
- [ ] SSL证书已安装
|
|
||||||
|
|
||||||
### 部署后测试
|
|
||||||
- [ ] 页面正常加载
|
|
||||||
- [ ] 游戏功能正常
|
|
||||||
- [ ] 网络请求正常
|
|
||||||
- [ ] 音频播放正常
|
|
||||||
- [ ] 移动端兼容性
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📞 技术支持
|
|
||||||
|
|
||||||
如果遇到问题，请检查：
|
|
||||||
1. 浏览器开发者工具的控制台错误
|
|
||||||
2. 网络请求是否成功
|
|
||||||
3. 服务器配置是否正确
|
|
||||||
4. Godot版本是否兼容
|
|
||||||
|
|
||||||
**更新日志**: 查看 `docs/web_deployment_changelog.md`
|
|
||||||
@@ -1,324 +0,0 @@
|
|||||||
# 表单验证规范文档
|
|
||||||
|
|
||||||
## 概述
|
|
||||||
|
|
||||||
本文档详细说明了登录和注册表单的验证规则、UI交互规范和错误处理机制。
|
|
||||||
|
|
||||||
## 验证规则
|
|
||||||
|
|
||||||
### 1. 用户名验证
|
|
||||||
|
|
||||||
#### 规则
|
|
||||||
- **必填项**: 是
|
|
||||||
- **长度**: 1-50字符
|
|
||||||
- **格式**: 只能包含字母、数字和下划线
|
|
||||||
- **正则表达式**: `^[a-zA-Z0-9_]+$`
|
|
||||||
|
|
||||||
#### 错误提示
|
|
||||||
- 空值: "用户名不能为空"
|
|
||||||
- 长度不符: "用户名长度应为1-50字符"
|
|
||||||
- 格式错误: "用户名只能包含字母、数字和下划线"
|
|
||||||
|
|
||||||
### 2. 邮箱验证
|
|
||||||
|
|
||||||
#### 规则
|
|
||||||
- **必填项**: 是（注册时）
|
|
||||||
- **格式**: 标准邮箱格式
|
|
||||||
- **正则表达式**: `^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`
|
|
||||||
|
|
||||||
#### 错误提示
|
|
||||||
- 空值: "邮箱不能为空"
|
|
||||||
- 格式错误: "请输入有效的邮箱地址"
|
|
||||||
|
|
||||||
### 3. 密码验证
|
|
||||||
|
|
||||||
#### 规则
|
|
||||||
- **必填项**: 是
|
|
||||||
- **长度**: 8-128字符
|
|
||||||
- **复杂度**: 必须包含字母和数字
|
|
||||||
- **安全性**: 不允许纯数字或纯字母
|
|
||||||
|
|
||||||
#### 错误提示
|
|
||||||
- 空值: "密码不能为空"
|
|
||||||
- 长度不足: "密码长度至少8位"
|
|
||||||
- 长度超限: "密码长度不能超过128位"
|
|
||||||
- 复杂度不够: "密码必须包含字母和数字"
|
|
||||||
|
|
||||||
### 4. 确认密码验证
|
|
||||||
|
|
||||||
#### 规则
|
|
||||||
- **必填项**: 是（注册时）
|
|
||||||
- **一致性**: 必须与密码字段完全一致
|
|
||||||
|
|
||||||
#### 错误提示
|
|
||||||
- 空值: "确认密码不能为空"
|
|
||||||
- 不一致: "两次输入的密码不一致"
|
|
||||||
|
|
||||||
### 5. 验证码验证
|
|
||||||
|
|
||||||
#### 规则
|
|
||||||
- **必填项**: 是（注册时）
|
|
||||||
- **长度**: 6位数字
|
|
||||||
- **格式**: 纯数字
|
|
||||||
- **有效性**: 必须先获取验证码
|
|
||||||
|
|
||||||
#### 错误提示
|
|
||||||
- 空值: "验证码不能为空"
|
|
||||||
- 长度错误: "验证码必须是6位数字"
|
|
||||||
- 格式错误: "验证码必须是6位数字"
|
|
||||||
- 未获取: "请先获取邮箱验证码"
|
|
||||||
|
|
||||||
## UI交互规范
|
|
||||||
|
|
||||||
### 1. 必填项标识
|
|
||||||
|
|
||||||
所有必填字段都使用水平布局来显示标签、红色星号和右对齐的错误提示：
|
|
||||||
|
|
||||||
#### 结构设计
|
|
||||||
```
|
|
||||||
VBoxContainer (字段容器)
|
|
||||||
├── HBoxContainer (标签和错误提示容器)
|
|
||||||
│ ├── Label (字段名称)
|
|
||||||
│ ├── Label (红色星号 " *")
|
|
||||||
│ ├── Control (弹性空间) [size_flags_horizontal = 3]
|
|
||||||
│ └── Label (红色错误提示) [右对齐，默认隐藏]
|
|
||||||
└── LineEdit (输入框)
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 视觉效果
|
|
||||||
- **标签**: 黑色文本，如 "用户名"、"邮箱"、"密码"
|
|
||||||
- **星号**: 红色文本 `Color(1, 0.2, 0.2, 1)`，内容为 " *"
|
|
||||||
- **弹性空间**: Control节点，`size_flags_horizontal = 3`，占据剩余空间
|
|
||||||
- **错误提示**: 红色文本，12px字体，右对齐显示 (`horizontal_alignment = 2`)
|
|
||||||
- **布局**: 标签和星号左对齐，错误提示右对齐
|
|
||||||
|
|
||||||
#### 交互行为
|
|
||||||
- **正常状态**: 显示 `用户名 * `
|
|
||||||
- **错误状态**: 显示 `用户名 * 用户名不能为空`
|
|
||||||
- **输入时**: 错误提示自动隐藏，回到正常状态
|
|
||||||
|
|
||||||
#### 优势
|
|
||||||
- 错误提示右对齐，与输入框右边缘对齐，视觉更整齐
|
|
||||||
- 利用弹性空间实现左右分布，布局更美观
|
|
||||||
- 不占用额外的垂直空间
|
|
||||||
- 避免UI布局被拉长导致溢出
|
|
||||||
- 保持界面紧凑美观
|
|
||||||
- 红色星号和错误提示颜色一致，视觉统一
|
|
||||||
- 错误提示位置固定，不会因为文本长度变化而影响布局
|
|
||||||
|
|
||||||
### 2. 实时验证
|
|
||||||
|
|
||||||
#### 失焦验证
|
|
||||||
- 当用户离开输入框时（`focus_exited`）触发验证
|
|
||||||
- 立即显示相应的错误提示
|
|
||||||
- 错误提示显示在输入框下方
|
|
||||||
|
|
||||||
#### 输入时验证
|
|
||||||
- 当用户开始输入时（`text_changed`）隐藏错误提示
|
|
||||||
- 提供即时的视觉反馈
|
|
||||||
- 避免在用户输入过程中显示错误
|
|
||||||
|
|
||||||
### 3. 错误提示样式
|
|
||||||
|
|
||||||
#### 视觉设计
|
|
||||||
- **颜色**: 红色 `Color(1, 0.2, 0.2, 1)`
|
|
||||||
- **字体大小**: 12px
|
|
||||||
- **位置**: 输入框正下方
|
|
||||||
- **显示状态**: 默认隐藏，验证失败时显示
|
|
||||||
|
|
||||||
#### 错误信息特点
|
|
||||||
- 简洁明了，直接指出问题
|
|
||||||
- 提供解决建议
|
|
||||||
- 使用友好的语言
|
|
||||||
|
|
||||||
### 4. 按钮状态管理
|
|
||||||
|
|
||||||
#### 发送验证码按钮
|
|
||||||
- **正常状态**: "发送验证码"
|
|
||||||
- **冷却状态**: "重新发送(60)" (倒计时)
|
|
||||||
- **禁用状态**: 请求进行中时禁用
|
|
||||||
|
|
||||||
#### 提交按钮
|
|
||||||
- **正常状态**: 可点击
|
|
||||||
- **禁用状态**: 表单验证失败或请求进行中时禁用
|
|
||||||
- **加载状态**: 显示"正在注册..."等提示
|
|
||||||
|
|
||||||
## 验证流程
|
|
||||||
|
|
||||||
### 1. 登录表单验证流程
|
|
||||||
|
|
||||||
```
|
|
||||||
用户输入 → 失焦验证 → 显示错误(如有) → 点击登录 → 整体验证 → 提交请求
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 验证步骤
|
|
||||||
1. 检查用户名是否为空
|
|
||||||
2. 检查密码是否为空
|
|
||||||
3. 所有验证通过后提交登录请求
|
|
||||||
|
|
||||||
### 2. 注册表单验证流程
|
|
||||||
|
|
||||||
```
|
|
||||||
用户输入 → 失焦验证 → 显示错误(如有) → 获取验证码 → 输入验证码 → 点击注册 → 整体验证 → 邮箱验证 → 用户注册
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 验证步骤
|
|
||||||
1. 验证用户名格式和长度
|
|
||||||
2. 验证邮箱格式
|
|
||||||
3. 验证密码强度
|
|
||||||
4. 验证确认密码一致性
|
|
||||||
5. 验证验证码格式和有效性
|
|
||||||
6. 发送邮箱验证请求
|
|
||||||
7. 验证成功后发送注册请求
|
|
||||||
|
|
||||||
### 3. 验证码获取流程
|
|
||||||
|
|
||||||
```
|
|
||||||
输入邮箱 → 验证邮箱格式 → 检查冷却时间 → 发送验证码 → 开始冷却计时
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 冷却机制
|
|
||||||
- **冷却时间**: 60秒
|
|
||||||
- **按钮状态**: 显示倒计时
|
|
||||||
- **重复发送**: 冷却结束后可重新发送
|
|
||||||
|
|
||||||
## 错误处理机制
|
|
||||||
|
|
||||||
### 1. 客户端验证
|
|
||||||
|
|
||||||
#### 即时验证
|
|
||||||
- 在用户输入过程中提供即时反馈
|
|
||||||
- 防止用户提交无效数据
|
|
||||||
- 提升用户体验
|
|
||||||
|
|
||||||
#### 提交前验证
|
|
||||||
- 在发送请求前进行完整验证
|
|
||||||
- 确保所有必填项都已正确填写
|
|
||||||
- 避免无效的网络请求
|
|
||||||
|
|
||||||
### 2. 服务器验证
|
|
||||||
|
|
||||||
#### 后端验证
|
|
||||||
- 服务器端进行二次验证
|
|
||||||
- 处理服务器返回的错误信息
|
|
||||||
- 显示相应的错误提示
|
|
||||||
|
|
||||||
#### 网络错误处理
|
|
||||||
- 连接失败提示
|
|
||||||
- 超时处理
|
|
||||||
- 服务器错误提示
|
|
||||||
|
|
||||||
### 3. 用户引导
|
|
||||||
|
|
||||||
#### 错误恢复
|
|
||||||
- 清晰的错误提示
|
|
||||||
- 提供解决方案
|
|
||||||
- 引导用户正确操作
|
|
||||||
|
|
||||||
#### 成功反馈
|
|
||||||
- 注册成功提示
|
|
||||||
- 自动跳转到登录界面
|
|
||||||
- 自动填充用户名
|
|
||||||
|
|
||||||
## 代码实现
|
|
||||||
|
|
||||||
### 1. 验证函数
|
|
||||||
|
|
||||||
每个字段都有对应的验证函数：
|
|
||||||
- `validate_username(username: String) -> Dictionary`
|
|
||||||
- `validate_email(email: String) -> Dictionary`
|
|
||||||
- `validate_password(password: String) -> Dictionary`
|
|
||||||
- `validate_confirm_password(password: String, confirm: String) -> Dictionary`
|
|
||||||
- `validate_verification_code(code: String) -> Dictionary`
|
|
||||||
|
|
||||||
### 2. 事件处理
|
|
||||||
|
|
||||||
#### 失焦事件
|
|
||||||
- `_on_register_username_focus_exited()`
|
|
||||||
- `_on_register_email_focus_exited()`
|
|
||||||
- `_on_register_password_focus_exited()`
|
|
||||||
- `_on_register_confirm_focus_exited()`
|
|
||||||
- `_on_verification_focus_exited()`
|
|
||||||
|
|
||||||
#### 输入事件
|
|
||||||
- `_on_register_username_text_changed(new_text: String)`
|
|
||||||
- `_on_register_email_text_changed(new_text: String)`
|
|
||||||
- `_on_register_password_text_changed(new_text: String)`
|
|
||||||
- `_on_register_confirm_text_changed(new_text: String)`
|
|
||||||
- `_on_verification_text_changed(new_text: String)`
|
|
||||||
|
|
||||||
### 3. 整体验证
|
|
||||||
|
|
||||||
- `validate_login_form() -> bool`
|
|
||||||
- `validate_register_form() -> bool`
|
|
||||||
|
|
||||||
## 测试用例
|
|
||||||
|
|
||||||
### 1. 用户名测试
|
|
||||||
|
|
||||||
| 输入 | 预期结果 | 错误信息 |
|
|
||||||
|------|----------|----------|
|
|
||||||
| "" | 失败 | "用户名不能为空" |
|
|
||||||
| "a" | 成功 | - |
|
|
||||||
| "test_user123" | 成功 | - |
|
|
||||||
| "test@user" | 失败 | "用户名只能包含字母、数字和下划线" |
|
|
||||||
| "a".repeat(51) | 失败 | "用户名长度应为1-50字符" |
|
|
||||||
|
|
||||||
### 2. 邮箱测试
|
|
||||||
|
|
||||||
| 输入 | 预期结果 | 错误信息 |
|
|
||||||
|------|----------|----------|
|
|
||||||
| "" | 失败 | "邮箱不能为空" |
|
|
||||||
| "test@example.com" | 成功 | - |
|
|
||||||
| "invalid-email" | 失败 | "请输入有效的邮箱地址" |
|
|
||||||
| "test@" | 失败 | "请输入有效的邮箱地址" |
|
|
||||||
|
|
||||||
### 3. 密码测试
|
|
||||||
|
|
||||||
| 输入 | 预期结果 | 错误信息 |
|
|
||||||
|------|----------|----------|
|
|
||||||
| "" | 失败 | "密码不能为空" |
|
|
||||||
| "1234567" | 失败 | "密码长度至少8位" |
|
|
||||||
| "12345678" | 失败 | "密码必须包含字母和数字" |
|
|
||||||
| "abcdefgh" | 失败 | "密码必须包含字母和数字" |
|
|
||||||
| "abc12345" | 成功 | - |
|
|
||||||
|
|
||||||
### 4. 验证码测试
|
|
||||||
|
|
||||||
| 输入 | 预期结果 | 错误信息 |
|
|
||||||
|------|----------|----------|
|
|
||||||
| "" | 失败 | "验证码不能为空" |
|
|
||||||
| "12345" | 失败 | "验证码必须是6位数字" |
|
|
||||||
| "1234567" | 失败 | "验证码必须是6位数字" |
|
|
||||||
| "12345a" | 失败 | "验证码必须是6位数字" |
|
|
||||||
| "123456" | 成功 | - |
|
|
||||||
|
|
||||||
## 最佳实践
|
|
||||||
|
|
||||||
### 1. 用户体验
|
|
||||||
|
|
||||||
- **即时反馈**: 在用户输入时提供即时的视觉反馈
|
|
||||||
- **清晰提示**: 错误信息要简洁明了，易于理解
|
|
||||||
- **引导操作**: 通过UI引导用户完成正确的操作流程
|
|
||||||
|
|
||||||
### 2. 性能优化
|
|
||||||
|
|
||||||
- **避免过度验证**: 不在每次字符输入时都进行复杂验证
|
|
||||||
- **合理的验证时机**: 在失焦和提交时进行验证
|
|
||||||
- **缓存验证结果**: 避免重复验证相同的内容
|
|
||||||
|
|
||||||
### 3. 安全考虑
|
|
||||||
|
|
||||||
- **客户端+服务端**: 双重验证确保数据安全
|
|
||||||
- **敏感信息**: 密码等敏感信息不在客户端明文存储
|
|
||||||
- **防止暴力破解**: 验证码冷却机制防止频繁请求
|
|
||||||
|
|
||||||
### 4. 可维护性
|
|
||||||
|
|
||||||
- **模块化设计**: 每个验证规则独立成函数
|
|
||||||
- **统一的错误处理**: 使用统一的错误显示机制
|
|
||||||
- **可配置的规则**: 验证规则可以根据需求调整
|
|
||||||
|
|
||||||
## 更新日志
|
|
||||||
|
|
||||||
- **v1.0.0** (2025-12-24): 初始版本，包含完整的表单验证规范
|
|
||||||
@@ -1,283 +0,0 @@
|
|||||||
# 表单验证测试指南
|
|
||||||
|
|
||||||
## 测试概述
|
|
||||||
|
|
||||||
本文档提供了完整的表单验证功能测试步骤，确保所有验证规则和用户交互都能正常工作。
|
|
||||||
|
|
||||||
## 测试环境准备
|
|
||||||
|
|
||||||
### 1. 启动后端服务
|
|
||||||
```bash
|
|
||||||
# 确保后端服务运行在 https://whaletownend.xinghangee.icu
|
|
||||||
# 或者本地开发环境: http://localhost:3000
|
|
||||||
npm start
|
|
||||||
# 或者你的后端启动命令
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. 打开Godot项目
|
|
||||||
- 启动Godot编辑器
|
|
||||||
- 打开鲸鱼镇项目
|
|
||||||
- 运行主场景
|
|
||||||
|
|
||||||
## 登录表单测试
|
|
||||||
|
|
||||||
### 测试用例1: 必填项验证
|
|
||||||
|
|
||||||
#### 步骤
|
|
||||||
1. 点击"注册居民身份"进入登录界面
|
|
||||||
2. 不输入任何内容，直接点击用户名输入框外的区域
|
|
||||||
3. 不输入任何内容，直接点击密码输入框外的区域
|
|
||||||
4. 点击"进入小镇"或"密码登录"按钮
|
|
||||||
|
|
||||||
#### 预期结果
|
|
||||||
- 用户名输入框下方显示红色错误提示："用户名不能为空"
|
|
||||||
- 密码输入框下方显示红色错误提示："密码不能为空"
|
|
||||||
- 按钮点击无效，不会提交表单
|
|
||||||
|
|
||||||
### 测试用例2: 实时反馈
|
|
||||||
|
|
||||||
#### 步骤
|
|
||||||
1. 触发上述错误提示后
|
|
||||||
2. 在用户名输入框中输入任意字符
|
|
||||||
3. 在密码输入框中输入任意字符
|
|
||||||
|
|
||||||
#### 预期结果
|
|
||||||
- 开始输入时，对应的错误提示立即消失
|
|
||||||
- 提供即时的视觉反馈
|
|
||||||
|
|
||||||
### 测试用例3: 正常登录
|
|
||||||
|
|
||||||
#### 步骤
|
|
||||||
1. 输入有效的用户名："testuser"
|
|
||||||
2. 输入任意密码："password123"
|
|
||||||
3. 点击"进入小镇"
|
|
||||||
|
|
||||||
#### 预期结果
|
|
||||||
- 无错误提示显示
|
|
||||||
- 成功进入游戏主界面
|
|
||||||
- 显示用户名信息
|
|
||||||
|
|
||||||
## 注册表单测试
|
|
||||||
|
|
||||||
### 测试用例4: 用户名验证
|
|
||||||
|
|
||||||
#### 测试数据
|
|
||||||
| 输入 | 预期结果 | 错误信息 |
|
|
||||||
|------|----------|----------|
|
|
||||||
| (空) | 失败 | "用户名不能为空" |
|
|
||||||
| "test@user" | 失败 | "用户名只能包含字母、数字和下划线" |
|
|
||||||
| "a".repeat(51) | 失败 | "用户名长度应为1-50字符" |
|
|
||||||
| "test_user123" | 成功 | 无错误提示 |
|
|
||||||
|
|
||||||
#### 步骤
|
|
||||||
1. 点击"注册居民身份"
|
|
||||||
2. 依次输入上述测试数据
|
|
||||||
3. 每次输入后点击其他输入框（触发失焦验证）
|
|
||||||
|
|
||||||
### 测试用例5: 邮箱验证
|
|
||||||
|
|
||||||
#### 测试数据
|
|
||||||
| 输入 | 预期结果 | 错误信息 |
|
|
||||||
|------|----------|----------|
|
|
||||||
| (空) | 失败 | "邮箱不能为空" |
|
|
||||||
| "invalid-email" | 失败 | "请输入有效的邮箱地址" |
|
|
||||||
| "test@" | 失败 | "请输入有效的邮箱地址" |
|
|
||||||
| "test@example.com" | 成功 | 无错误提示 |
|
|
||||||
|
|
||||||
#### 步骤
|
|
||||||
1. 在邮箱输入框中依次输入测试数据
|
|
||||||
2. 每次输入后点击其他输入框
|
|
||||||
|
|
||||||
### 测试用例6: 密码验证
|
|
||||||
|
|
||||||
#### 测试数据
|
|
||||||
| 输入 | 预期结果 | 错误信息 |
|
|
||||||
|------|----------|----------|
|
|
||||||
| (空) | 失败 | "密码不能为空" |
|
|
||||||
| "1234567" | 失败 | "密码长度至少8位" |
|
|
||||||
| "12345678" | 失败 | "密码必须包含字母和数字" |
|
|
||||||
| "abcdefgh" | 失败 | "密码必须包含字母和数字" |
|
|
||||||
| "abc12345" | 成功 | 无错误提示 |
|
|
||||||
|
|
||||||
#### 步骤
|
|
||||||
1. 在密码输入框中依次输入测试数据
|
|
||||||
2. 每次输入后点击其他输入框
|
|
||||||
|
|
||||||
### 测试用例7: 确认密码验证
|
|
||||||
|
|
||||||
#### 步骤
|
|
||||||
1. 在密码框输入："abc12345"
|
|
||||||
2. 在确认密码框输入：""（空）
|
|
||||||
3. 点击其他输入框
|
|
||||||
4. 在确认密码框输入："different123"
|
|
||||||
5. 点击其他输入框
|
|
||||||
6. 在确认密码框输入："abc12345"
|
|
||||||
7. 点击其他输入框
|
|
||||||
|
|
||||||
#### 预期结果
|
|
||||||
- 步骤3: 显示"确认密码不能为空"
|
|
||||||
- 步骤5: 显示"两次输入的密码不一致"
|
|
||||||
- 步骤7: 无错误提示
|
|
||||||
|
|
||||||
### 测试用例8: 验证码功能
|
|
||||||
|
|
||||||
#### 步骤
|
|
||||||
1. 不输入邮箱，直接点击"发送验证码"
|
|
||||||
2. 输入无效邮箱"invalid"，点击"发送验证码"
|
|
||||||
3. 输入有效邮箱"test@example.com"，点击"发送验证码"
|
|
||||||
4. 立即再次点击"发送验证码"
|
|
||||||
5. 在验证码输入框输入"12345"（5位）
|
|
||||||
6. 在验证码输入框输入"12345a"（包含字母）
|
|
||||||
7. 在验证码输入框输入"123456"（正确格式）
|
|
||||||
|
|
||||||
#### 预期结果
|
|
||||||
- 步骤1: 邮箱框显示"邮箱不能为空"，聚焦到邮箱输入框
|
|
||||||
- 步骤2: 邮箱框显示"请输入有效的邮箱地址"
|
|
||||||
- 步骤3: 显示"正在发送验证码..."，按钮变为禁用状态
|
|
||||||
- 步骤4: 显示冷却提示"请等待 XX 秒后再次发送"
|
|
||||||
- 步骤5: 验证码框显示"验证码必须是6位数字"
|
|
||||||
- 步骤6: 验证码框显示"验证码必须是6位数字"
|
|
||||||
- 步骤7: 无错误提示
|
|
||||||
|
|
||||||
### 测试用例9: 完整注册流程
|
|
||||||
|
|
||||||
#### 步骤
|
|
||||||
1. 填写所有必填信息：
|
|
||||||
- 用户名: "testuser"
|
|
||||||
- 邮箱: "test@example.com"
|
|
||||||
- 密码: "password123"
|
|
||||||
- 确认密码: "password123"
|
|
||||||
2. 点击"发送验证码"
|
|
||||||
3. 查看控制台获取验证码
|
|
||||||
4. 输入验证码
|
|
||||||
5. 点击"注册"按钮
|
|
||||||
|
|
||||||
#### 预期结果
|
|
||||||
- 所有验证通过，无错误提示
|
|
||||||
- 显示"正在验证邮箱..."
|
|
||||||
- 显示"邮箱验证成功，正在注册..."
|
|
||||||
- 显示"注册成功！"
|
|
||||||
- 自动返回登录界面
|
|
||||||
- 用户名自动填入登录表单
|
|
||||||
|
|
||||||
## 边界情况测试
|
|
||||||
|
|
||||||
### 测试用例10: 网络异常
|
|
||||||
|
|
||||||
#### 步骤
|
|
||||||
1. 关闭后端服务
|
|
||||||
2. 尝试发送验证码
|
|
||||||
3. 尝试注册
|
|
||||||
|
|
||||||
#### 预期结果
|
|
||||||
- 显示"网络连接失败，请检查服务器是否启动"
|
|
||||||
- 按钮重新启用
|
|
||||||
|
|
||||||
### 测试用例11: 快速操作
|
|
||||||
|
|
||||||
#### 步骤
|
|
||||||
1. 快速连续点击"发送验证码"按钮
|
|
||||||
2. 快速连续点击"注册"按钮
|
|
||||||
|
|
||||||
#### 预期结果
|
|
||||||
- 按钮在请求期间被禁用
|
|
||||||
- 防止重复提交
|
|
||||||
|
|
||||||
### 测试用例12: 表单切换
|
|
||||||
|
|
||||||
#### 步骤
|
|
||||||
1. 在注册表单中输入信息并触发错误提示
|
|
||||||
2. 点击"返回登录"
|
|
||||||
3. 再次点击"注册居民身份"
|
|
||||||
|
|
||||||
#### 预期结果
|
|
||||||
- 切换到登录界面时，注册表单状态保持
|
|
||||||
- 再次进入注册界面时，表单被清空，错误提示被隐藏
|
|
||||||
|
|
||||||
## 性能测试
|
|
||||||
|
|
||||||
### 测试用例13: 响应速度
|
|
||||||
|
|
||||||
#### 步骤
|
|
||||||
1. 快速在各个输入框之间切换
|
|
||||||
2. 快速输入和删除文本
|
|
||||||
3. 观察错误提示的显示和隐藏速度
|
|
||||||
|
|
||||||
#### 预期结果
|
|
||||||
- 验证响应迅速，无明显延迟
|
|
||||||
- UI更新流畅，无卡顿现象
|
|
||||||
|
|
||||||
## 兼容性测试
|
|
||||||
|
|
||||||
### 测试用例14: 不同输入法
|
|
||||||
|
|
||||||
#### 步骤
|
|
||||||
1. 使用中文输入法输入用户名
|
|
||||||
2. 使用英文输入法输入用户名
|
|
||||||
3. 输入特殊字符
|
|
||||||
|
|
||||||
#### 预期结果
|
|
||||||
- 中文字符被正确验证为无效格式
|
|
||||||
- 英文字符正常通过验证
|
|
||||||
- 特殊字符按规则验证
|
|
||||||
|
|
||||||
## 测试检查清单
|
|
||||||
|
|
||||||
### 功能完整性
|
|
||||||
- [ ] 所有必填项都有红色星号标识
|
|
||||||
- [ ] 失焦验证正常工作
|
|
||||||
- [ ] 实时输入反馈正常
|
|
||||||
- [ ] 错误提示准确显示
|
|
||||||
- [ ] 验证码发送和验证功能正常
|
|
||||||
- [ ] 注册流程完整可用
|
|
||||||
|
|
||||||
### 用户体验
|
|
||||||
- [ ] 错误提示清晰易懂
|
|
||||||
- [ ] 按钮状态管理正确
|
|
||||||
- [ ] 表单切换流畅
|
|
||||||
- [ ] 成功反馈及时
|
|
||||||
|
|
||||||
### 错误处理
|
|
||||||
- [ ] 网络异常处理正确
|
|
||||||
- [ ] 服务器错误处理正确
|
|
||||||
- [ ] 边界情况处理正确
|
|
||||||
|
|
||||||
### 性能表现
|
|
||||||
- [ ] 验证响应速度快
|
|
||||||
- [ ] UI更新流畅
|
|
||||||
- [ ] 内存使用正常
|
|
||||||
|
|
||||||
## 测试报告模板
|
|
||||||
|
|
||||||
### 测试环境
|
|
||||||
- Godot版本:
|
|
||||||
- 操作系统:
|
|
||||||
- 后端服务状态:
|
|
||||||
- 测试时间:
|
|
||||||
|
|
||||||
### 测试结果
|
|
||||||
| 测试用例 | 状态 | 备注 |
|
|
||||||
|----------|------|------|
|
|
||||||
| 登录表单验证 | ✅/❌ | |
|
|
||||||
| 注册表单验证 | ✅/❌ | |
|
|
||||||
| 验证码功能 | ✅/❌ | |
|
|
||||||
| 网络异常处理 | ✅/❌ | |
|
|
||||||
| 完整注册流程 | ✅/❌ | |
|
|
||||||
|
|
||||||
### 发现的问题
|
|
||||||
1. 问题描述
|
|
||||||
- 重现步骤
|
|
||||||
- 预期结果
|
|
||||||
- 实际结果
|
|
||||||
- 严重程度
|
|
||||||
|
|
||||||
### 改进建议
|
|
||||||
1. 功能改进
|
|
||||||
2. 用户体验优化
|
|
||||||
3. 性能优化
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**测试完成日期**: ___________
|
|
||||||
**测试人员**: ___________
|
|
||||||
**测试版本**: v1.0.0
|
|
||||||
@@ -1,238 +0,0 @@
|
|||||||
# 🔧 故障排除指南
|
|
||||||
|
|
||||||
> AI编程助手专用：常见问题的快速解决方案
|
|
||||||
|
|
||||||
## 🚨 常见错误及解决方案
|
|
||||||
|
|
||||||
### 1. UID无效警告
|
|
||||||
|
|
||||||
**错误信息**:
|
|
||||||
```
|
|
||||||
WARNING: scene/resources/resource_format_text.cpp:444 - res://path/to/file.tscn:X - ext_resource, invalid UID: uid://xxxxx - using text path instead: res://path/to/script.gd
|
|
||||||
```
|
|
||||||
|
|
||||||
**原因**: 文件移动后，Godot的UID缓存没有更新，导致UID引用失效。
|
|
||||||
|
|
||||||
**解决方案**:
|
|
||||||
```gdscript
|
|
||||||
# 方法1: 移除无效的UID，使用文本路径
|
|
||||||
# 将这行：
|
|
||||||
[ext_resource type="Script" uid="uid://invalid_uid" path="res://path/to/script.gd" id="1_script"]
|
|
||||||
|
|
||||||
# 改为：
|
|
||||||
[ext_resource type="Script" path="res://path/to/script.gd" id="1_script"]
|
|
||||||
```
|
|
||||||
|
|
||||||
**预防措施**:
|
|
||||||
- 移动文件时使用Godot编辑器的文件系统面板
|
|
||||||
- 避免直接在文件系统中移动.gd和.tscn文件
|
|
||||||
- 移动文件后重新导入项目
|
|
||||||
|
|
||||||
### 2. 脚本路径错误
|
|
||||||
|
|
||||||
**错误信息**:
|
|
||||||
```
|
|
||||||
ERROR: Failed to load script "res://old/path/Script.gd" with error "File not found".
|
|
||||||
```
|
|
||||||
|
|
||||||
**解决方案**:
|
|
||||||
```gdscript
|
|
||||||
# 检查并更新所有.tscn文件中的脚本路径
|
|
||||||
# 使用搜索替换功能批量更新：
|
|
||||||
|
|
||||||
# 旧路径 → 新路径
|
|
||||||
"res://UI/Windows/" → "res://scenes/ui/"
|
|
||||||
"res://Utils/" → "res://_Core/utils/"
|
|
||||||
"res://Scenes/Maps/" → "res://scenes/maps/"
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. AutoLoad路径错误
|
|
||||||
|
|
||||||
**错误信息**:
|
|
||||||
```
|
|
||||||
ERROR: Cannot load autoload: res://old/path/Manager.gd
|
|
||||||
```
|
|
||||||
|
|
||||||
**解决方案**:
|
|
||||||
```ini
|
|
||||||
# 在 project.godot 中更新 AutoLoad 路径
|
|
||||||
[autoload]
|
|
||||||
GameManager="*res://_Core/managers/GameManager.gd"
|
|
||||||
SceneManager="*res://_Core/managers/SceneManager.gd"
|
|
||||||
EventSystem="*res://_Core/systems/EventSystem.gd"
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. 资源加载失败
|
|
||||||
|
|
||||||
**错误信息**:
|
|
||||||
```
|
|
||||||
ERROR: Failed to load resource "res://old/path/resource.png".
|
|
||||||
```
|
|
||||||
|
|
||||||
**解决方案**:
|
|
||||||
```gdscript
|
|
||||||
# 检查资源路径是否正确
|
|
||||||
# 使用 ResourceLoader.exists() 验证路径
|
|
||||||
func load_resource_safely(path: String):
|
|
||||||
if not ResourceLoader.exists(path):
|
|
||||||
push_error("Resource not found: %s" % path)
|
|
||||||
return null
|
|
||||||
|
|
||||||
return load(path)
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔍 调试技巧
|
|
||||||
|
|
||||||
### 1. 路径验证
|
|
||||||
```gdscript
|
|
||||||
# 验证文件是否存在
|
|
||||||
func verify_file_exists(file_path: String) -> bool:
|
|
||||||
return FileAccess.file_exists(file_path)
|
|
||||||
|
|
||||||
# 验证资源是否存在
|
|
||||||
func verify_resource_exists(resource_path: String) -> bool:
|
|
||||||
return ResourceLoader.exists(resource_path)
|
|
||||||
|
|
||||||
# 打印当前工作目录
|
|
||||||
func print_current_directory():
|
|
||||||
print("Current directory: ", OS.get_executable_path().get_base_dir())
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. 场景加载调试
|
|
||||||
```gdscript
|
|
||||||
# 安全的场景加载
|
|
||||||
func load_scene_safely(scene_path: String) -> PackedScene:
|
|
||||||
if not ResourceLoader.exists(scene_path):
|
|
||||||
push_error("Scene file not found: %s" % scene_path)
|
|
||||||
return null
|
|
||||||
|
|
||||||
var scene = load(scene_path) as PackedScene
|
|
||||||
if scene == null:
|
|
||||||
push_error("Failed to load scene: %s" % scene_path)
|
|
||||||
return null
|
|
||||||
|
|
||||||
return scene
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. 节点引用调试
|
|
||||||
```gdscript
|
|
||||||
# 安全的节点获取
|
|
||||||
func get_node_safely(node_path: String) -> Node:
|
|
||||||
var node = get_node_or_null(node_path)
|
|
||||||
if node == null:
|
|
||||||
push_warning("Node not found: %s" % node_path)
|
|
||||||
return node
|
|
||||||
|
|
||||||
# 检查@onready变量是否正确初始化
|
|
||||||
func _ready():
|
|
||||||
# 验证所有@onready节点
|
|
||||||
if not some_button:
|
|
||||||
push_error("some_button not found - check node path")
|
|
||||||
if not some_label:
|
|
||||||
push_error("some_label not found - check node path")
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🛠️ 项目结构问题
|
|
||||||
|
|
||||||
### 1. 文件移动后的检查清单
|
|
||||||
- [ ] 更新.tscn文件中的脚本路径
|
|
||||||
- [ ] 更新project.godot中的AutoLoad路径
|
|
||||||
- [ ] 更新代码中的硬编码路径
|
|
||||||
- [ ] 清理Godot缓存文件
|
|
||||||
- [ ] 重新导入项目
|
|
||||||
|
|
||||||
### 2. 缓存清理命令
|
|
||||||
```bash
|
|
||||||
# Windows PowerShell
|
|
||||||
Remove-Item -Recurse -Force ".godot\uid_cache.bin"
|
|
||||||
Remove-Item -Recurse -Force ".godot\global_script_class_cache.cfg"
|
|
||||||
|
|
||||||
# Linux/macOS
|
|
||||||
rm -rf .godot/uid_cache.bin
|
|
||||||
rm -rf .godot/global_script_class_cache.cfg
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. 路径常量管理
|
|
||||||
```gdscript
|
|
||||||
# 在 _Core/ProjectPaths.gd 中定义所有路径
|
|
||||||
class_name ProjectPaths
|
|
||||||
|
|
||||||
# 核心路径
|
|
||||||
const CORE_ROOT = "res://_Core/"
|
|
||||||
const MANAGERS_PATH = CORE_ROOT + "managers/"
|
|
||||||
const SYSTEMS_PATH = CORE_ROOT + "systems/"
|
|
||||||
const UTILS_PATH = CORE_ROOT + "utils/"
|
|
||||||
|
|
||||||
# 场景路径
|
|
||||||
const SCENES_ROOT = "res://scenes/"
|
|
||||||
const UI_PATH = SCENES_ROOT + "ui/"
|
|
||||||
const MAPS_PATH = SCENES_ROOT + "maps/"
|
|
||||||
|
|
||||||
# 使用示例
|
|
||||||
var scene_path = ProjectPaths.UI_PATH + "LoginWindow.tscn"
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🎯 性能问题
|
|
||||||
|
|
||||||
### 1. 内存泄漏检测
|
|
||||||
```gdscript
|
|
||||||
# 监控节点数量
|
|
||||||
func _ready():
|
|
||||||
print("Initial node count: ", get_tree().get_node_count())
|
|
||||||
|
|
||||||
func _exit_tree():
|
|
||||||
print("Final node count: ", get_tree().get_node_count())
|
|
||||||
|
|
||||||
# 检查未释放的资源
|
|
||||||
func check_resource_leaks():
|
|
||||||
print("Resource count: ", ResourceLoader.get_resource_list().size())
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. 帧率监控
|
|
||||||
```gdscript
|
|
||||||
# 在 _Core/managers/PerformanceManager.gd
|
|
||||||
extends Node
|
|
||||||
|
|
||||||
var frame_count: int = 0
|
|
||||||
var fps_timer: float = 0.0
|
|
||||||
|
|
||||||
func _process(delta: float):
|
|
||||||
frame_count += 1
|
|
||||||
fps_timer += delta
|
|
||||||
|
|
||||||
if fps_timer >= 1.0:
|
|
||||||
var fps = frame_count / fps_timer
|
|
||||||
if fps < 30:
|
|
||||||
push_warning("Low FPS detected: %.1f" % fps)
|
|
||||||
|
|
||||||
frame_count = 0
|
|
||||||
fps_timer = 0.0
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔧 开发工具问题
|
|
||||||
|
|
||||||
### 1. Godot编辑器崩溃
|
|
||||||
**解决方案**:
|
|
||||||
1. 备份项目文件
|
|
||||||
2. 删除.godot文件夹
|
|
||||||
3. 重新打开项目
|
|
||||||
4. 重新导入所有资源
|
|
||||||
|
|
||||||
### 2. 脚本编辑器问题
|
|
||||||
**解决方案**:
|
|
||||||
```gdscript
|
|
||||||
# 检查脚本语法
|
|
||||||
# 使用 Godot 内置的语法检查器
|
|
||||||
# 或者在命令行中运行：
|
|
||||||
# godot --check-only script.gd
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. 场景编辑器问题
|
|
||||||
**解决方案**:
|
|
||||||
- 检查场景文件是否损坏
|
|
||||||
- 重新创建有问题的场景
|
|
||||||
- 使用版本控制恢复到工作版本
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**💡 提示**: 遇到问题时，首先检查Godot的输出面板和调试器，它们通常会提供详细的错误信息和解决建议。
|
|
||||||
@@ -1,617 +0,0 @@
|
|||||||
# 🎯 管理器模板集合
|
|
||||||
|
|
||||||
> AI编程助手专用：各类管理器的标准化代码模板
|
|
||||||
|
|
||||||
## 🎮 游戏管理器模板
|
|
||||||
|
|
||||||
### 基础游戏管理器
|
|
||||||
```gdscript
|
|
||||||
# _Core/managers/GameManager.gd
|
|
||||||
extends Node
|
|
||||||
|
|
||||||
## 游戏状态管理器
|
|
||||||
## 负责管理游戏的全局状态、玩家数据和游戏流程
|
|
||||||
|
|
||||||
# 信号定义
|
|
||||||
signal game_state_changed(old_state: GameState, new_state: GameState)
|
|
||||||
signal player_data_updated(data: Dictionary)
|
|
||||||
signal game_paused()
|
|
||||||
signal game_resumed()
|
|
||||||
|
|
||||||
# 游戏状态枚举
|
|
||||||
enum GameState {
|
|
||||||
LOADING,
|
|
||||||
MENU,
|
|
||||||
PLAYING,
|
|
||||||
PAUSED,
|
|
||||||
GAME_OVER,
|
|
||||||
SETTINGS
|
|
||||||
}
|
|
||||||
|
|
||||||
# 常量定义
|
|
||||||
const SAVE_FILE_PATH: String = "user://game_save.dat"
|
|
||||||
const CONFIG_FILE_PATH: String = "res://Config/game_config.json"
|
|
||||||
|
|
||||||
# 导出变量
|
|
||||||
@export var debug_mode: bool = false
|
|
||||||
@export var auto_save_interval: float = 30.0
|
|
||||||
|
|
||||||
# 公共变量
|
|
||||||
var current_state: GameState = GameState.LOADING
|
|
||||||
var is_paused: bool = false
|
|
||||||
var game_time: float = 0.0
|
|
||||||
|
|
||||||
# 玩家数据
|
|
||||||
var player_data: Dictionary = {
|
|
||||||
"level": 1,
|
|
||||||
"experience": 0,
|
|
||||||
"coins": 100,
|
|
||||||
"health": 100,
|
|
||||||
"max_health": 100,
|
|
||||||
"energy": 100,
|
|
||||||
"max_energy": 100
|
|
||||||
}
|
|
||||||
|
|
||||||
# 私有变量
|
|
||||||
var _auto_save_timer: Timer
|
|
||||||
var _game_config: Dictionary = {}
|
|
||||||
|
|
||||||
func _ready() -> void:
|
|
||||||
_initialize_manager()
|
|
||||||
_setup_auto_save()
|
|
||||||
_load_game_config()
|
|
||||||
change_state(GameState.MENU)
|
|
||||||
|
|
||||||
func _process(delta: float) -> void:
|
|
||||||
if current_state == GameState.PLAYING and not is_paused:
|
|
||||||
game_time += delta
|
|
||||||
|
|
||||||
## 改变游戏状态
|
|
||||||
func change_state(new_state: GameState) -> void:
|
|
||||||
if current_state == new_state:
|
|
||||||
return
|
|
||||||
|
|
||||||
var old_state = current_state
|
|
||||||
_exit_state(old_state)
|
|
||||||
current_state = new_state
|
|
||||||
_enter_state(new_state)
|
|
||||||
|
|
||||||
game_state_changed.emit(old_state, new_state)
|
|
||||||
|
|
||||||
if debug_mode:
|
|
||||||
print("[GameManager] State changed: %s -> %s" % [old_state, new_state])
|
|
||||||
|
|
||||||
## 暂停游戏
|
|
||||||
func pause_game() -> void:
|
|
||||||
if current_state != GameState.PLAYING:
|
|
||||||
return
|
|
||||||
|
|
||||||
is_paused = true
|
|
||||||
get_tree().paused = true
|
|
||||||
game_paused.emit()
|
|
||||||
|
|
||||||
## 恢复游戏
|
|
||||||
func resume_game() -> void:
|
|
||||||
if not is_paused:
|
|
||||||
return
|
|
||||||
|
|
||||||
is_paused = false
|
|
||||||
get_tree().paused = false
|
|
||||||
game_resumed.emit()
|
|
||||||
|
|
||||||
## 更新玩家数据
|
|
||||||
func update_player_data(key: String, value) -> void:
|
|
||||||
if not player_data.has(key):
|
|
||||||
push_warning("Unknown player data key: %s" % key)
|
|
||||||
return
|
|
||||||
|
|
||||||
player_data[key] = value
|
|
||||||
player_data_updated.emit(player_data)
|
|
||||||
|
|
||||||
if debug_mode:
|
|
||||||
print("[GameManager] Player data updated: %s = %s" % [key, value])
|
|
||||||
|
|
||||||
## 获取玩家数据
|
|
||||||
func get_player_data(key: String = ""):
|
|
||||||
if key.is_empty():
|
|
||||||
return player_data.duplicate()
|
|
||||||
|
|
||||||
return player_data.get(key, null)
|
|
||||||
|
|
||||||
## 保存游戏数据
|
|
||||||
func save_game() -> bool:
|
|
||||||
var save_data = {
|
|
||||||
"player_data": player_data,
|
|
||||||
"game_time": game_time,
|
|
||||||
"current_state": current_state,
|
|
||||||
"timestamp": Time.get_unix_time_from_system()
|
|
||||||
}
|
|
||||||
|
|
||||||
var file = FileAccess.open(SAVE_FILE_PATH, FileAccess.WRITE)
|
|
||||||
if file == null:
|
|
||||||
push_error("Failed to open save file for writing")
|
|
||||||
return false
|
|
||||||
|
|
||||||
file.store_string(JSON.stringify(save_data))
|
|
||||||
file.close()
|
|
||||||
|
|
||||||
if debug_mode:
|
|
||||||
print("[GameManager] Game saved successfully")
|
|
||||||
|
|
||||||
return true
|
|
||||||
|
|
||||||
## 加载游戏数据
|
|
||||||
func load_game() -> bool:
|
|
||||||
if not FileAccess.file_exists(SAVE_FILE_PATH):
|
|
||||||
if debug_mode:
|
|
||||||
print("[GameManager] No save file found")
|
|
||||||
return false
|
|
||||||
|
|
||||||
var file = FileAccess.open(SAVE_FILE_PATH, FileAccess.READ)
|
|
||||||
if file == null:
|
|
||||||
push_error("Failed to open save file for reading")
|
|
||||||
return false
|
|
||||||
|
|
||||||
var json_text = file.get_as_text()
|
|
||||||
file.close()
|
|
||||||
|
|
||||||
var json = JSON.new()
|
|
||||||
var parse_result = json.parse(json_text)
|
|
||||||
if parse_result != OK:
|
|
||||||
push_error("Failed to parse save file JSON")
|
|
||||||
return false
|
|
||||||
|
|
||||||
var save_data = json.data
|
|
||||||
|
|
||||||
# 恢复玩家数据
|
|
||||||
if save_data.has("player_data"):
|
|
||||||
player_data = save_data.player_data
|
|
||||||
player_data_updated.emit(player_data)
|
|
||||||
|
|
||||||
# 恢复游戏时间
|
|
||||||
if save_data.has("game_time"):
|
|
||||||
game_time = save_data.game_time
|
|
||||||
|
|
||||||
if debug_mode:
|
|
||||||
print("[GameManager] Game loaded successfully")
|
|
||||||
|
|
||||||
return true
|
|
||||||
|
|
||||||
# 私有方法
|
|
||||||
func _initialize_manager() -> void:
|
|
||||||
# 设置进程模式为总是处理（即使暂停时也能工作）
|
|
||||||
process_mode = Node.PROCESS_MODE_ALWAYS
|
|
||||||
|
|
||||||
func _setup_auto_save() -> void:
|
|
||||||
_auto_save_timer = Timer.new()
|
|
||||||
add_child(_auto_save_timer)
|
|
||||||
_auto_save_timer.wait_time = auto_save_interval
|
|
||||||
_auto_save_timer.timeout.connect(_on_auto_save_timeout)
|
|
||||||
_auto_save_timer.start()
|
|
||||||
|
|
||||||
func _load_game_config() -> void:
|
|
||||||
if not FileAccess.file_exists(CONFIG_FILE_PATH):
|
|
||||||
push_warning("Game config file not found")
|
|
||||||
return
|
|
||||||
|
|
||||||
var file = FileAccess.open(CONFIG_FILE_PATH, FileAccess.READ)
|
|
||||||
if file == null:
|
|
||||||
push_error("Failed to open game config file")
|
|
||||||
return
|
|
||||||
|
|
||||||
var json_text = file.get_as_text()
|
|
||||||
file.close()
|
|
||||||
|
|
||||||
var json = JSON.new()
|
|
||||||
var parse_result = json.parse(json_text)
|
|
||||||
if parse_result != OK:
|
|
||||||
push_error("Failed to parse game config JSON")
|
|
||||||
return
|
|
||||||
|
|
||||||
_game_config = json.data
|
|
||||||
|
|
||||||
func _enter_state(state: GameState) -> void:
|
|
||||||
match state:
|
|
||||||
GameState.LOADING:
|
|
||||||
# 加载游戏资源
|
|
||||||
pass
|
|
||||||
GameState.MENU:
|
|
||||||
# 显示主菜单
|
|
||||||
pass
|
|
||||||
GameState.PLAYING:
|
|
||||||
# 开始游戏逻辑
|
|
||||||
_auto_save_timer.start()
|
|
||||||
GameState.PAUSED:
|
|
||||||
# 暂停游戏
|
|
||||||
_auto_save_timer.stop()
|
|
||||||
GameState.GAME_OVER:
|
|
||||||
# 游戏结束处理
|
|
||||||
save_game()
|
|
||||||
GameState.SETTINGS:
|
|
||||||
# 显示设置界面
|
|
||||||
pass
|
|
||||||
|
|
||||||
func _exit_state(state: GameState) -> void:
|
|
||||||
match state:
|
|
||||||
GameState.PLAYING:
|
|
||||||
# 退出游戏时自动保存
|
|
||||||
save_game()
|
|
||||||
|
|
||||||
func _on_auto_save_timeout() -> void:
|
|
||||||
if current_state == GameState.PLAYING:
|
|
||||||
save_game()
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🌐 网络管理器模板
|
|
||||||
|
|
||||||
### HTTP请求管理器
|
|
||||||
```gdscript
|
|
||||||
# _Core/managers/NetworkManager.gd
|
|
||||||
extends Node
|
|
||||||
|
|
||||||
## 网络请求管理器
|
|
||||||
## 负责处理所有HTTP请求和网络通信
|
|
||||||
|
|
||||||
# 信号定义
|
|
||||||
signal request_completed(request_id: String, success: bool, data: Dictionary)
|
|
||||||
signal connection_status_changed(is_connected: bool)
|
|
||||||
|
|
||||||
# 常量定义
|
|
||||||
const BASE_URL: String = "https://api.example.com"
|
|
||||||
const TIMEOUT_DURATION: float = 10.0
|
|
||||||
const MAX_RETRIES: int = 3
|
|
||||||
|
|
||||||
# 请求状态枚举
|
|
||||||
enum RequestStatus {
|
|
||||||
PENDING,
|
|
||||||
SUCCESS,
|
|
||||||
FAILED,
|
|
||||||
TIMEOUT,
|
|
||||||
CANCELLED
|
|
||||||
}
|
|
||||||
|
|
||||||
# 公共变量
|
|
||||||
var is_connected: bool = false
|
|
||||||
var active_requests: Dictionary = {}
|
|
||||||
|
|
||||||
# 私有变量
|
|
||||||
var _http_client: HTTPClient
|
|
||||||
var _request_counter: int = 0
|
|
||||||
|
|
||||||
func _ready() -> void:
|
|
||||||
_initialize_network()
|
|
||||||
_check_connection()
|
|
||||||
|
|
||||||
## 发送GET请求
|
|
||||||
func send_get_request(endpoint: String, headers: Dictionary = {}) -> String:
|
|
||||||
return _send_request(HTTPClient.METHOD_GET, endpoint, "", headers)
|
|
||||||
|
|
||||||
## 发送POST请求
|
|
||||||
func send_post_request(endpoint: String, data: Dictionary, headers: Dictionary = {}) -> String:
|
|
||||||
var json_data = JSON.stringify(data)
|
|
||||||
return _send_request(HTTPClient.METHOD_POST, endpoint, json_data, headers)
|
|
||||||
|
|
||||||
## 发送PUT请求
|
|
||||||
func send_put_request(endpoint: String, data: Dictionary, headers: Dictionary = {}) -> String:
|
|
||||||
var json_data = JSON.stringify(data)
|
|
||||||
return _send_request(HTTPClient.METHOD_PUT, endpoint, json_data, headers)
|
|
||||||
|
|
||||||
## 发送DELETE请求
|
|
||||||
func send_delete_request(endpoint: String, headers: Dictionary = {}) -> String:
|
|
||||||
return _send_request(HTTPClient.METHOD_DELETE, endpoint, "", headers)
|
|
||||||
|
|
||||||
## 取消请求
|
|
||||||
func cancel_request(request_id: String) -> bool:
|
|
||||||
if not active_requests.has(request_id):
|
|
||||||
return false
|
|
||||||
|
|
||||||
var request_data = active_requests[request_id]
|
|
||||||
if request_data.http_request:
|
|
||||||
request_data.http_request.cancel_request()
|
|
||||||
|
|
||||||
_cleanup_request(request_id, RequestStatus.CANCELLED)
|
|
||||||
return true
|
|
||||||
|
|
||||||
## 检查网络连接状态
|
|
||||||
func check_connection() -> void:
|
|
||||||
_check_connection()
|
|
||||||
|
|
||||||
# 私有方法
|
|
||||||
func _initialize_network() -> void:
|
|
||||||
_http_client = HTTPClient.new()
|
|
||||||
|
|
||||||
func _send_request(method: HTTPClient.Method, endpoint: String, data: String, headers: Dictionary) -> String:
|
|
||||||
var request_id = _generate_request_id()
|
|
||||||
var full_url = BASE_URL + endpoint
|
|
||||||
|
|
||||||
# 创建HTTP请求节点
|
|
||||||
var http_request = HTTPRequest.new()
|
|
||||||
add_child(http_request)
|
|
||||||
|
|
||||||
# 设置请求超时
|
|
||||||
http_request.timeout = TIMEOUT_DURATION
|
|
||||||
|
|
||||||
# 连接完成信号
|
|
||||||
http_request.request_completed.connect(_on_request_completed.bind(request_id))
|
|
||||||
|
|
||||||
# 准备请求头
|
|
||||||
var request_headers = ["Content-Type: application/json"]
|
|
||||||
for key in headers:
|
|
||||||
request_headers.append("%s: %s" % [key, headers[key]])
|
|
||||||
|
|
||||||
# 存储请求信息
|
|
||||||
active_requests[request_id] = {
|
|
||||||
"http_request": http_request,
|
|
||||||
"method": method,
|
|
||||||
"url": full_url,
|
|
||||||
"status": RequestStatus.PENDING,
|
|
||||||
"retry_count": 0,
|
|
||||||
"start_time": Time.get_time_dict_from_system()
|
|
||||||
}
|
|
||||||
|
|
||||||
# 发送请求
|
|
||||||
var error = http_request.request(full_url, request_headers, method, data)
|
|
||||||
if error != OK:
|
|
||||||
push_error("Failed to send HTTP request: %d" % error)
|
|
||||||
_cleanup_request(request_id, RequestStatus.FAILED)
|
|
||||||
return ""
|
|
||||||
|
|
||||||
return request_id
|
|
||||||
|
|
||||||
func _generate_request_id() -> String:
|
|
||||||
_request_counter += 1
|
|
||||||
return "req_%d_%d" % [Time.get_time_dict_from_system().hour * 3600 + Time.get_time_dict_from_system().minute * 60 + Time.get_time_dict_from_system().second, _request_counter]
|
|
||||||
|
|
||||||
func _on_request_completed(request_id: String, result: int, response_code: int, headers: PackedStringArray, body: PackedByteArray) -> void:
|
|
||||||
if not active_requests.has(request_id):
|
|
||||||
return
|
|
||||||
|
|
||||||
var request_data = active_requests[request_id]
|
|
||||||
var success = false
|
|
||||||
var response_data = {}
|
|
||||||
|
|
||||||
# 解析响应
|
|
||||||
if response_code >= 200 and response_code < 300:
|
|
||||||
success = true
|
|
||||||
var body_text = body.get_string_from_utf8()
|
|
||||||
|
|
||||||
if not body_text.is_empty():
|
|
||||||
var json = JSON.new()
|
|
||||||
var parse_result = json.parse(body_text)
|
|
||||||
if parse_result == OK:
|
|
||||||
response_data = json.data
|
|
||||||
else:
|
|
||||||
response_data = {"raw_response": body_text}
|
|
||||||
else:
|
|
||||||
# 处理错误响应
|
|
||||||
var body_text = body.get_string_from_utf8()
|
|
||||||
response_data = {
|
|
||||||
"error": "HTTP Error %d" % response_code,
|
|
||||||
"response_code": response_code,
|
|
||||||
"raw_response": body_text
|
|
||||||
}
|
|
||||||
|
|
||||||
# 发送完成信号
|
|
||||||
request_completed.emit(request_id, success, response_data)
|
|
||||||
|
|
||||||
# 清理请求
|
|
||||||
_cleanup_request(request_id, RequestStatus.SUCCESS if success else RequestStatus.FAILED)
|
|
||||||
|
|
||||||
func _cleanup_request(request_id: String, status: RequestStatus) -> void:
|
|
||||||
if not active_requests.has(request_id):
|
|
||||||
return
|
|
||||||
|
|
||||||
var request_data = active_requests[request_id]
|
|
||||||
|
|
||||||
# 移除HTTP请求节点
|
|
||||||
if request_data.http_request:
|
|
||||||
request_data.http_request.queue_free()
|
|
||||||
|
|
||||||
# 从活动请求中移除
|
|
||||||
active_requests.erase(request_id)
|
|
||||||
|
|
||||||
func _check_connection() -> void:
|
|
||||||
# 简单的连接检查（可以改为ping服务器）
|
|
||||||
var old_status = is_connected
|
|
||||||
is_connected = true # 这里可以实现实际的连接检查逻辑
|
|
||||||
|
|
||||||
if old_status != is_connected:
|
|
||||||
connection_status_changed.emit(is_connected)
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🎵 音频管理器模板
|
|
||||||
|
|
||||||
### 音频系统管理器
|
|
||||||
```gdscript
|
|
||||||
# _Core/managers/AudioManager.gd
|
|
||||||
extends Node
|
|
||||||
|
|
||||||
## 音频管理器
|
|
||||||
## 负责管理游戏中的音乐和音效播放
|
|
||||||
|
|
||||||
# 信号定义
|
|
||||||
signal music_finished()
|
|
||||||
signal sound_effect_finished(sound_name: String)
|
|
||||||
|
|
||||||
# 音频类型枚举
|
|
||||||
enum AudioType {
|
|
||||||
MUSIC,
|
|
||||||
SOUND_EFFECT,
|
|
||||||
UI_SOUND,
|
|
||||||
VOICE
|
|
||||||
}
|
|
||||||
|
|
||||||
# 常量定义
|
|
||||||
const MUSIC_PATH: String = "res://assets/audio/music/"
|
|
||||||
const SOUND_PATH: String = "res://assets/audio/sounds/"
|
|
||||||
const VOICE_PATH: String = "res://assets/audio/voice/"
|
|
||||||
|
|
||||||
# 导出变量
|
|
||||||
@export var master_volume: float = 1.0
|
|
||||||
@export var music_volume: float = 0.7
|
|
||||||
@export var sfx_volume: float = 0.8
|
|
||||||
@export var voice_volume: float = 0.9
|
|
||||||
|
|
||||||
# 音频播放器
|
|
||||||
var music_player: AudioStreamPlayer
|
|
||||||
var sfx_players: Array[AudioStreamPlayer] = []
|
|
||||||
var voice_player: AudioStreamPlayer
|
|
||||||
|
|
||||||
# 当前播放状态
|
|
||||||
var current_music: String = ""
|
|
||||||
var is_music_playing: bool = false
|
|
||||||
var active_sounds: Dictionary = {}
|
|
||||||
|
|
||||||
func _ready() -> void:
|
|
||||||
_initialize_audio_players()
|
|
||||||
_load_audio_settings()
|
|
||||||
|
|
||||||
## 播放背景音乐
|
|
||||||
func play_music(music_name: String, fade_in: bool = true) -> void:
|
|
||||||
var music_path = MUSIC_PATH + music_name + ".ogg"
|
|
||||||
|
|
||||||
if not ResourceLoader.exists(music_path):
|
|
||||||
push_warning("Music file not found: %s" % music_path)
|
|
||||||
return
|
|
||||||
|
|
||||||
# 停止当前音乐
|
|
||||||
if is_music_playing:
|
|
||||||
stop_music(fade_in)
|
|
||||||
await get_tree().create_timer(0.5).timeout
|
|
||||||
|
|
||||||
# 加载并播放新音乐
|
|
||||||
var audio_stream = load(music_path)
|
|
||||||
music_player.stream = audio_stream
|
|
||||||
music_player.volume_db = linear_to_db(music_volume * master_volume)
|
|
||||||
|
|
||||||
if fade_in:
|
|
||||||
_fade_in_music()
|
|
||||||
else:
|
|
||||||
music_player.play()
|
|
||||||
|
|
||||||
current_music = music_name
|
|
||||||
is_music_playing = true
|
|
||||||
|
|
||||||
## 停止背景音乐
|
|
||||||
func stop_music(fade_out: bool = true) -> void:
|
|
||||||
if not is_music_playing:
|
|
||||||
return
|
|
||||||
|
|
||||||
if fade_out:
|
|
||||||
_fade_out_music()
|
|
||||||
else:
|
|
||||||
music_player.stop()
|
|
||||||
is_music_playing = false
|
|
||||||
current_music = ""
|
|
||||||
|
|
||||||
## 播放音效
|
|
||||||
func play_sound_effect(sound_name: String, volume_override: float = -1.0) -> void:
|
|
||||||
var sound_path = SOUND_PATH + sound_name + ".ogg"
|
|
||||||
|
|
||||||
if not ResourceLoader.exists(sound_path):
|
|
||||||
push_warning("Sound file not found: %s" % sound_path)
|
|
||||||
return
|
|
||||||
|
|
||||||
# 获取可用的音效播放器
|
|
||||||
var player = _get_available_sfx_player()
|
|
||||||
if player == null:
|
|
||||||
push_warning("No available sound effect player")
|
|
||||||
return
|
|
||||||
|
|
||||||
# 加载并播放音效
|
|
||||||
var audio_stream = load(sound_path)
|
|
||||||
player.stream = audio_stream
|
|
||||||
|
|
||||||
var final_volume = volume_override if volume_override > 0 else sfx_volume
|
|
||||||
player.volume_db = linear_to_db(final_volume * master_volume)
|
|
||||||
|
|
||||||
player.play()
|
|
||||||
active_sounds[sound_name] = player
|
|
||||||
|
|
||||||
## 设置主音量
|
|
||||||
func set_master_volume(volume: float) -> void:
|
|
||||||
master_volume = clamp(volume, 0.0, 1.0)
|
|
||||||
_update_all_volumes()
|
|
||||||
|
|
||||||
## 设置音乐音量
|
|
||||||
func set_music_volume(volume: float) -> void:
|
|
||||||
music_volume = clamp(volume, 0.0, 1.0)
|
|
||||||
if is_music_playing:
|
|
||||||
music_player.volume_db = linear_to_db(music_volume * master_volume)
|
|
||||||
|
|
||||||
## 设置音效音量
|
|
||||||
func set_sfx_volume(volume: float) -> void:
|
|
||||||
sfx_volume = clamp(volume, 0.0, 1.0)
|
|
||||||
_update_sfx_volumes()
|
|
||||||
|
|
||||||
# 私有方法
|
|
||||||
func _initialize_audio_players() -> void:
|
|
||||||
# 创建音乐播放器
|
|
||||||
music_player = AudioStreamPlayer.new()
|
|
||||||
add_child(music_player)
|
|
||||||
music_player.finished.connect(_on_music_finished)
|
|
||||||
|
|
||||||
# 创建多个音效播放器（支持同时播放多个音效）
|
|
||||||
for i in range(8):
|
|
||||||
var sfx_player = AudioStreamPlayer.new()
|
|
||||||
add_child(sfx_player)
|
|
||||||
sfx_players.append(sfx_player)
|
|
||||||
|
|
||||||
# 创建语音播放器
|
|
||||||
voice_player = AudioStreamPlayer.new()
|
|
||||||
add_child(voice_player)
|
|
||||||
|
|
||||||
func _get_available_sfx_player() -> AudioStreamPlayer:
|
|
||||||
for player in sfx_players:
|
|
||||||
if not player.playing:
|
|
||||||
return player
|
|
||||||
return null
|
|
||||||
|
|
||||||
func _fade_in_music() -> void:
|
|
||||||
music_player.volume_db = linear_to_db(0.01)
|
|
||||||
music_player.play()
|
|
||||||
|
|
||||||
var tween = create_tween()
|
|
||||||
tween.tween_method(_set_music_volume_db, 0.01, music_volume * master_volume, 1.0)
|
|
||||||
|
|
||||||
func _fade_out_music() -> void:
|
|
||||||
var tween = create_tween()
|
|
||||||
tween.tween_method(_set_music_volume_db, music_volume * master_volume, 0.01, 1.0)
|
|
||||||
tween.tween_callback(_stop_music_after_fade)
|
|
||||||
|
|
||||||
func _set_music_volume_db(volume: float) -> void:
|
|
||||||
music_player.volume_db = linear_to_db(volume)
|
|
||||||
|
|
||||||
func _stop_music_after_fade() -> void:
|
|
||||||
music_player.stop()
|
|
||||||
is_music_playing = false
|
|
||||||
current_music = ""
|
|
||||||
|
|
||||||
func _update_all_volumes() -> void:
|
|
||||||
if is_music_playing:
|
|
||||||
music_player.volume_db = linear_to_db(music_volume * master_volume)
|
|
||||||
_update_sfx_volumes()
|
|
||||||
|
|
||||||
func _update_sfx_volumes() -> void:
|
|
||||||
for player in sfx_players:
|
|
||||||
if player.playing:
|
|
||||||
player.volume_db = linear_to_db(sfx_volume * master_volume)
|
|
||||||
|
|
||||||
func _load_audio_settings() -> void:
|
|
||||||
# 从配置文件加载音频设置
|
|
||||||
pass
|
|
||||||
|
|
||||||
func _on_music_finished() -> void:
|
|
||||||
is_music_playing = false
|
|
||||||
current_music = ""
|
|
||||||
music_finished.emit()
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**🎯 使用说明**:
|
|
||||||
1. 选择合适的管理器模板
|
|
||||||
2. 根据具体需求修改类名和功能
|
|
||||||
3. 确保在project.godot中配置为AutoLoad
|
|
||||||
4. 遵循项目的命名规范和代码风格
|
|
||||||
5. 添加必要的错误处理和日志记录
|
|
||||||
@@ -1,363 +0,0 @@
|
|||||||
# 🚀 功能开发流程
|
|
||||||
|
|
||||||
> AI编程助手专用：新功能开发的标准化工作流程
|
|
||||||
|
|
||||||
## 🎯 开发流程概览
|
|
||||||
|
|
||||||
### 阶段1: 需求分析 → 阶段2: 架构设计 → 阶段3: 代码实现 → 阶段4: 测试验证 → 阶段5: 文档更新
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📋 阶段1: 需求分析
|
|
||||||
|
|
||||||
### 1.1 理解需求
|
|
||||||
```markdown
|
|
||||||
**必须明确的问题:**
|
|
||||||
- 功能的具体作用是什么？
|
|
||||||
- 涉及哪些用户交互？
|
|
||||||
- 需要哪些数据和状态管理？
|
|
||||||
- 与现有功能的关系如何？
|
|
||||||
```
|
|
||||||
|
|
||||||
### 1.2 需求分类
|
|
||||||
```gdscript
|
|
||||||
# 功能类型分类
|
|
||||||
enum FeatureType {
|
|
||||||
CORE_SYSTEM, # 核心系统功能 → 放在 _Core/
|
|
||||||
GAME_SCENE, # 游戏场景功能 → 放在 scenes/
|
|
||||||
UI_COMPONENT, # UI组件功能 → 放在 scenes/ui/
|
|
||||||
ASSET_RELATED, # 资源相关功能 → 涉及 assets/
|
|
||||||
CONFIG_DRIVEN # 配置驱动功能 → 涉及 Config/
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 1.3 依赖分析
|
|
||||||
- 需要哪些现有管理器？
|
|
||||||
- 需要创建新的管理器吗？
|
|
||||||
- 需要新的事件定义吗？
|
|
||||||
- 需要新的配置文件吗？
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🏗️ 阶段2: 架构设计
|
|
||||||
|
|
||||||
### 2.1 确定文件位置
|
|
||||||
```gdscript
|
|
||||||
# 根据功能类型确定文件位置
|
|
||||||
match feature_type:
|
|
||||||
FeatureType.CORE_SYSTEM:
|
|
||||||
# _Core/managers/ 或 _Core/systems/
|
|
||||||
var file_path = "_Core/managers/YourManager.gd"
|
|
||||||
|
|
||||||
FeatureType.GAME_SCENE:
|
|
||||||
# scenes/maps/, scenes/characters/, scenes/effects/
|
|
||||||
var file_path = "scenes/characters/YourCharacter.gd"
|
|
||||||
|
|
||||||
FeatureType.UI_COMPONENT:
|
|
||||||
# scenes/ui/
|
|
||||||
var file_path = "scenes/ui/YourWindow.gd"
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2.2 设计接口
|
|
||||||
```gdscript
|
|
||||||
# 定义公共接口
|
|
||||||
class_name YourFeature
|
|
||||||
|
|
||||||
# 信号定义（对外通信）
|
|
||||||
signal feature_initialized()
|
|
||||||
signal feature_state_changed(new_state: String)
|
|
||||||
|
|
||||||
# 公共方法（供其他模块调用）
|
|
||||||
func initialize(config: Dictionary) -> bool
|
|
||||||
func get_state() -> String
|
|
||||||
func cleanup() -> void
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2.3 事件设计
|
|
||||||
```gdscript
|
|
||||||
# 在 _Core/EventNames.gd 中添加新事件
|
|
||||||
const YOUR_FEATURE_STARTED: String = "your_feature_started"
|
|
||||||
const YOUR_FEATURE_COMPLETED: String = "your_feature_completed"
|
|
||||||
const YOUR_FEATURE_ERROR: String = "your_feature_error"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 💻 阶段3: 代码实现
|
|
||||||
|
|
||||||
### 3.1 创建基础结构
|
|
||||||
```gdscript
|
|
||||||
# 使用标准模板创建文件
|
|
||||||
# 参考: docs/AI_docs/templates/components.md
|
|
||||||
|
|
||||||
extends Node # 或其他合适的基类
|
|
||||||
|
|
||||||
## [功能描述]
|
|
||||||
## 负责[具体职责]
|
|
||||||
|
|
||||||
# 信号定义
|
|
||||||
signal feature_ready()
|
|
||||||
|
|
||||||
# 枚举定义
|
|
||||||
enum FeatureState {
|
|
||||||
UNINITIALIZED,
|
|
||||||
INITIALIZING,
|
|
||||||
READY,
|
|
||||||
ERROR
|
|
||||||
}
|
|
||||||
|
|
||||||
# 常量定义
|
|
||||||
const CONFIG_PATH: String = "res://Config/your_feature_config.json"
|
|
||||||
|
|
||||||
# 导出变量
|
|
||||||
@export var debug_mode: bool = false
|
|
||||||
|
|
||||||
# 公共变量
|
|
||||||
var current_state: FeatureState = FeatureState.UNINITIALIZED
|
|
||||||
|
|
||||||
# 私有变量
|
|
||||||
var _config_data: Dictionary = {}
|
|
||||||
|
|
||||||
func _ready() -> void:
|
|
||||||
initialize()
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3.2 实现核心逻辑
|
|
||||||
```gdscript
|
|
||||||
## 初始化功能
|
|
||||||
func initialize() -> bool:
|
|
||||||
if current_state != FeatureState.UNINITIALIZED:
|
|
||||||
push_warning("Feature already initialized")
|
|
||||||
return false
|
|
||||||
|
|
||||||
current_state = FeatureState.INITIALIZING
|
|
||||||
|
|
||||||
# 加载配置
|
|
||||||
if not _load_config():
|
|
||||||
current_state = FeatureState.ERROR
|
|
||||||
return false
|
|
||||||
|
|
||||||
# 连接事件
|
|
||||||
_connect_events()
|
|
||||||
|
|
||||||
# 执行初始化逻辑
|
|
||||||
_perform_initialization()
|
|
||||||
|
|
||||||
current_state = FeatureState.READY
|
|
||||||
feature_ready.emit()
|
|
||||||
return true
|
|
||||||
|
|
||||||
func _load_config() -> bool:
|
|
||||||
# 配置加载逻辑
|
|
||||||
return true
|
|
||||||
|
|
||||||
func _connect_events() -> void:
|
|
||||||
# 事件连接逻辑
|
|
||||||
EventSystem.connect_event("related_event", _on_related_event)
|
|
||||||
|
|
||||||
func _perform_initialization() -> void:
|
|
||||||
# 具体初始化逻辑
|
|
||||||
pass
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3.3 错误处理
|
|
||||||
```gdscript
|
|
||||||
func _handle_error(error_message: String) -> void:
|
|
||||||
push_error("[YourFeature] %s" % error_message)
|
|
||||||
current_state = FeatureState.ERROR
|
|
||||||
|
|
||||||
# 发送错误事件
|
|
||||||
EventSystem.emit_event(EventNames.YOUR_FEATURE_ERROR, {
|
|
||||||
"message": error_message,
|
|
||||||
"timestamp": Time.get_unix_time_from_system()
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🧪 阶段4: 测试验证
|
|
||||||
|
|
||||||
### 4.1 创建测试文件
|
|
||||||
```gdscript
|
|
||||||
# tests/unit/test_your_feature.gd
|
|
||||||
extends "res://addons/gut/test.gd"
|
|
||||||
|
|
||||||
## YourFeature 单元测试
|
|
||||||
|
|
||||||
var your_feature: YourFeature
|
|
||||||
|
|
||||||
func before_each():
|
|
||||||
your_feature = preload("res://_Core/managers/YourFeature.gd").new()
|
|
||||||
add_child(your_feature)
|
|
||||||
|
|
||||||
func after_each():
|
|
||||||
your_feature.queue_free()
|
|
||||||
|
|
||||||
func test_initialization():
|
|
||||||
# 测试初始化
|
|
||||||
var result = your_feature.initialize()
|
|
||||||
assert_true(result, "Feature should initialize successfully")
|
|
||||||
assert_eq(your_feature.current_state, YourFeature.FeatureState.READY)
|
|
||||||
|
|
||||||
func test_error_handling():
|
|
||||||
# 测试错误处理
|
|
||||||
# 模拟错误条件
|
|
||||||
pass
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4.2 集成测试
|
|
||||||
```gdscript
|
|
||||||
# tests/integration/test_your_feature_integration.gd
|
|
||||||
extends "res://addons/gut/test.gd"
|
|
||||||
|
|
||||||
## YourFeature 集成测试
|
|
||||||
|
|
||||||
func test_feature_with_event_system():
|
|
||||||
# 测试与事件系统的集成
|
|
||||||
var event_received = false
|
|
||||||
|
|
||||||
EventSystem.connect_event("your_feature_started", func(data): event_received = true)
|
|
||||||
|
|
||||||
# 触发功能
|
|
||||||
# 验证事件是否正确发送
|
|
||||||
assert_true(event_received, "Event should be emitted")
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4.3 性能测试
|
|
||||||
```gdscript
|
|
||||||
# tests/performance/test_your_feature_performance.gd
|
|
||||||
extends "res://addons/gut/test.gd"
|
|
||||||
|
|
||||||
## YourFeature 性能测试
|
|
||||||
|
|
||||||
func test_initialization_performance():
|
|
||||||
var start_time = Time.get_time_dict_from_system()
|
|
||||||
|
|
||||||
# 执行功能
|
|
||||||
your_feature.initialize()
|
|
||||||
|
|
||||||
var end_time = Time.get_time_dict_from_system()
|
|
||||||
var duration = _calculate_duration(start_time, end_time)
|
|
||||||
|
|
||||||
# 验证性能要求（例如：初始化应在100ms内完成）
|
|
||||||
assert_lt(duration, 0.1, "Initialization should complete within 100ms")
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📚 阶段5: 文档更新
|
|
||||||
|
|
||||||
### 5.1 更新API文档
|
|
||||||
```markdown
|
|
||||||
# 在 docs/AI_docs/quick_reference/api_reference.md 中添加
|
|
||||||
|
|
||||||
## YourFeature API
|
|
||||||
|
|
||||||
### 初始化
|
|
||||||
```gdscript
|
|
||||||
var feature = YourFeature.new()
|
|
||||||
feature.initialize(config_dict)
|
|
||||||
```
|
|
||||||
|
|
||||||
### 主要方法
|
|
||||||
- `initialize(config: Dictionary) -> bool` - 初始化功能
|
|
||||||
- `get_state() -> FeatureState` - 获取当前状态
|
|
||||||
- `cleanup() -> void` - 清理资源
|
|
||||||
|
|
||||||
### 事件
|
|
||||||
- `feature_ready` - 功能准备就绪
|
|
||||||
- `feature_state_changed(new_state)` - 状态改变
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5.2 更新使用示例
|
|
||||||
```gdscript
|
|
||||||
# 在 docs/AI_docs/quick_reference/code_snippets.md 中添加
|
|
||||||
|
|
||||||
## YourFeature 使用示例
|
|
||||||
|
|
||||||
### 基本使用
|
|
||||||
```gdscript
|
|
||||||
# 创建和初始化
|
|
||||||
var feature = YourFeature.new()
|
|
||||||
add_child(feature)
|
|
||||||
|
|
||||||
# 连接信号
|
|
||||||
feature.feature_ready.connect(_on_feature_ready)
|
|
||||||
|
|
||||||
# 初始化
|
|
||||||
var config = {"setting1": "value1"}
|
|
||||||
feature.initialize(config)
|
|
||||||
|
|
||||||
func _on_feature_ready():
|
|
||||||
print("Feature is ready to use")
|
|
||||||
```
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5.3 更新架构文档
|
|
||||||
```markdown
|
|
||||||
# 在 docs/AI_docs/architecture_guide.md 中更新
|
|
||||||
|
|
||||||
## 新增功能: YourFeature
|
|
||||||
|
|
||||||
### 位置
|
|
||||||
- 文件路径: `_Core/managers/YourFeature.gd`
|
|
||||||
- AutoLoad: 是/否
|
|
||||||
- 依赖: EventSystem, ConfigManager
|
|
||||||
|
|
||||||
### 职责
|
|
||||||
- 负责[具体职责描述]
|
|
||||||
- 管理[相关数据/状态]
|
|
||||||
- 提供[对外接口]
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ✅ 开发检查清单
|
|
||||||
|
|
||||||
### 代码质量检查
|
|
||||||
- [ ] 遵循命名规范（PascalCase类名，snake_case变量名）
|
|
||||||
- [ ] 所有变量和函数都有类型注解
|
|
||||||
- [ ] 添加了适当的注释和文档字符串
|
|
||||||
- [ ] 实现了错误处理和边界检查
|
|
||||||
- [ ] 使用事件系统进行模块间通信
|
|
||||||
|
|
||||||
### 架构一致性检查
|
|
||||||
- [ ] 文件放在正确的目录中
|
|
||||||
- [ ] 如果是管理器，已配置AutoLoad
|
|
||||||
- [ ] 事件名称已添加到EventNames.gd
|
|
||||||
- [ ] 配置文件已放在Config/目录
|
|
||||||
- [ ] 遵循项目的架构原则
|
|
||||||
|
|
||||||
### 测试覆盖检查
|
|
||||||
- [ ] 编写了单元测试
|
|
||||||
- [ ] 编写了集成测试（如果需要）
|
|
||||||
- [ ] 编写了性能测试（如果是核心功能）
|
|
||||||
- [ ] 所有测试都能通过
|
|
||||||
- [ ] 测试覆盖了主要功能和边界情况
|
|
||||||
|
|
||||||
### 文档更新检查
|
|
||||||
- [ ] 更新了API参考文档
|
|
||||||
- [ ] 添加了使用示例
|
|
||||||
- [ ] 更新了架构文档
|
|
||||||
- [ ] 更新了相关的工作流程文档
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔄 迭代优化
|
|
||||||
|
|
||||||
### 代码审查要点
|
|
||||||
1. **功能完整性**: 是否满足所有需求？
|
|
||||||
2. **性能表现**: 是否存在性能瓶颈？
|
|
||||||
3. **错误处理**: 是否处理了所有可能的错误情况？
|
|
||||||
4. **代码可读性**: 代码是否清晰易懂？
|
|
||||||
5. **测试覆盖**: 测试是否充分？
|
|
||||||
|
|
||||||
### 持续改进
|
|
||||||
- 收集用户反馈
|
|
||||||
- 监控性能指标
|
|
||||||
- 定期重构优化
|
|
||||||
- 更新文档和示例
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**🎯 记住**: 这个流程确保了功能开发的质量和一致性。严格遵循每个阶段的要求，将大大提高开发效率和代码质量。
|
|
||||||
@@ -1,65 +0,0 @@
|
|||||||
# 文档更新日志
|
|
||||||
|
|
||||||
本文档记录了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)
|
|
||||||
@@ -1,122 +0,0 @@
|
|||||||
# 🤝 项目贡献者
|
|
||||||
|
|
||||||
感谢所有为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*
|
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user