fix/verification-code-button-state #5
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()
|
||||
886
README.md
886
README.md
@@ -1,693 +1,349 @@
|
||||
# 🐋 Whale Town - 像素游戏前端客户端
|
||||
# 🐋 WhaleTown - 现代化像素游戏
|
||||
|
||||
> 一个基于 Godot 4.5 引擎开发的现代化 2D 像素风游戏前端，采用模块化架构设计，集成完整的用户认证系统、实时通信和游戏核心功能。
|
||||
> 一个基于 Godot 4.5 引擎开发的企业级 2D 像素风游戏，采用模块化架构设计，集成完整的用户认证系统和游戏核心功能。
|
||||
|
||||
[](https://godotengine.org/)
|
||||
[](https://godotengine.org/)
|
||||
[](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/index.html)
|
||||
[](./LICENSE)
|
||||
[](https://godotengine.org/download)
|
||||
[](./docs/)
|
||||
[](https://godotengine.org/download)
|
||||
|
||||
## 🎯 项目简介
|
||||
|
||||
Whale Town 是一个功能完整的像素游戏前端客户端，采用模块化架构设计：
|
||||
WhaleTown 是一个功能完整的现代化像素游戏，具有以下特色：
|
||||
|
||||
- 🔐 **用户认证系统** - 完整的登录、注册、密码管理、邮箱验证界面
|
||||
- 🎮 **游戏核心功能** - 角色系统、战斗系统、对话系统、背包系统
|
||||
- 🌐 **实时通信** - WebSocket集成，支持实时多人交互
|
||||
- 🎨 **现代化UI** - 响应式界面设计，支持多分辨率适配
|
||||
- 🧪 **完整测试体系** - UI测试、API测试、性能测试全覆盖
|
||||
- 📱 **跨平台支持** - Windows、Linux、macOS、移动端
|
||||
- 🔧 **模块化架构** - 高度解耦的组件系统，易于扩展和维护
|
||||
- 🏗️ **企业级架构** - 模块化设计，高度解耦，易于扩展
|
||||
- 🔐 **完整认证系统** - 登录、注册、邮箱验证、密码管理
|
||||
- 🎮 **丰富游戏功能** - 角色系统、场景管理、事件通信
|
||||
- 🌐 **网络通信** - RESTful API集成，支持实时数据交互
|
||||
- 📚 **企业级文档** - 18个文档，覆盖开发全流程
|
||||
- 🧪 **完整测试体系** - API测试、UI测试、性能测试
|
||||
- 🚀 **一键部署** - 支持Web、桌面多平台发布
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速开始
|
||||
## 🚀 5分钟快速体验
|
||||
|
||||
<<<<<<< HEAD
|
||||
### 📋 环境要求
|
||||
### 📋 准备工作
|
||||
|
||||
- **Godot Engine** >= 4.5.0 (推荐 4.5.1)
|
||||
- **Python** >= 3.7.0 (用于API测试，可选)
|
||||
- **Git** >= 2.0.0
|
||||
**你需要安装：**
|
||||
- [Godot Engine 4.5+](https://godotengine.org/download) - 游戏引擎
|
||||
- [Git](https://git-scm.com/) - 版本控制工具
|
||||
|
||||
### 🛠️ 安装与运行
|
||||
=======
|
||||
### 环境要求
|
||||
- [Godot Engine 4.5+](https://godotengine.org/download)
|
||||
- Python 3.7+ (用于API测试和Web服务器)
|
||||
>>>>>>> whale-town-front/main
|
||||
### 🛠️ 启动项目
|
||||
|
||||
```bash
|
||||
# 1. 克隆项目
|
||||
# 1️⃣ 获取项目
|
||||
git clone <repository-url>
|
||||
cd whale-town
|
||||
|
||||
# 2. 使用Godot编辑器打开项目
|
||||
# 双击 project.godot 文件或在Godot编辑器中导入项目
|
||||
# 2️⃣ 打开项目
|
||||
# 双击 project.godot 文件，或在Godot编辑器中选择"导入项目"
|
||||
|
||||
# 3. 运行项目
|
||||
# 按F5或点击"运行"按钮启动游戏
|
||||
# 3️⃣ 运行游戏
|
||||
# 在Godot编辑器中按 F5 或点击"运行项目"按钮
|
||||
```
|
||||
|
||||
<<<<<<< HEAD
|
||||
🎉 **游戏启动成功！** 进入认证界面开始体验
|
||||
🎉 **成功！** 你应该看到游戏的认证界面
|
||||
|
||||
### 🧪 快速测试
|
||||
### 🎮 体验功能
|
||||
|
||||
1. **注册新用户** - 体验完整的邮箱验证流程
|
||||
2. **登录系统** - 尝试用户名/邮箱登录
|
||||
3. **游戏界面** - 探索主游戏场景
|
||||
|
||||
### 🧪 测试API（可选）
|
||||
|
||||
```bash
|
||||
# API接口测试
|
||||
=======
|
||||
### Web版本部署
|
||||
```bash
|
||||
# Windows用户
|
||||
tools\build_web.bat # 导出Web版本
|
||||
tools\serve_web.bat # 启动本地测试服务器
|
||||
# 安装Python依赖
|
||||
pip install requests
|
||||
|
||||
# Linux/macOS用户
|
||||
./tools/build_web.sh # 导出Web版本
|
||||
./tools/serve_web.sh # 启动本地测试服务器
|
||||
# 快速API测试
|
||||
python tests/api/quick_test.py
|
||||
|
||||
# 完整功能测试
|
||||
python tests/api/api_client_test.py
|
||||
```
|
||||
|
||||
详细部署指南请查看: [Web部署完整指南](docs/web_deployment_guide.md)
|
||||
---
|
||||
|
||||
## 🏗️ 项目架构
|
||||
## 📚 新手开发指南
|
||||
|
||||
### 核心设计理念
|
||||
项目采用 **分层架构** 和 **组件化设计**，遵循 Godot 最佳实践：
|
||||
- **清晰的分层** - 框架层、玩法层、界面层明确分离
|
||||
- **场景内聚** - 脚本紧邻场景文件，符合 Godot 原生开发习惯
|
||||
- **高度解耦** - 通过事件系统和管理器通信
|
||||
- **组件复用** - 可复用组件统一管理
|
||||
- **标准化** - 统一的命名规范和目录结构
|
||||
- **测试驱动** - 完整的测试体系和文档
|
||||
### 🎯 第一步：了解项目
|
||||
|
||||
**⚠️ 重要：开始开发前必读**
|
||||
|
||||
1. **[📖 项目入门总览](docs/01-项目入门/README.md)** - 5分钟了解项目
|
||||
2. **[🏗️ 项目结构说明](docs/01-项目入门/项目结构说明.md)** - 理解架构设计
|
||||
3. **[⚙️ 项目设置指南](docs/01-项目入门/项目设置指南.md)** - 配置开发环境
|
||||
|
||||
### 🎯 第二步：学习规范
|
||||
|
||||
**代码质量保证**
|
||||
|
||||
1. **[📝 命名规范](docs/02-开发规范/命名规范.md)** - 统一命名标准
|
||||
2. **[🏛️ 架构与通信规范](docs/02-开发规范/架构与通信规范.md)** - 组件通信方式
|
||||
3. **[💬 代码注释规范](docs/02-开发规范/代码注释规范.md)** - 注释标准
|
||||
4. **[🔄 Git提交规范](docs/02-开发规范/Git提交规范.md)** - 版本控制规范
|
||||
|
||||
### 🎯 第三步：开始开发
|
||||
|
||||
**技术实现指导**
|
||||
|
||||
1. **[🔧 实现细节规范](docs/03-技术实现/实现细节规范.md)** - 游戏对象实现
|
||||
2. **[🌐 API接口文档](docs/03-技术实现/API接口文档.md)** - 后端接口使用
|
||||
3. **[🧪 测试指南](docs/03-技术实现/测试指南.md)** - 测试方法和工具
|
||||
|
||||
### 🎯 第四步：高级开发
|
||||
|
||||
**进阶技能**
|
||||
|
||||
1. **[🚀 性能优化指南](docs/04-高级开发/性能优化指南.md)** - 性能调优
|
||||
2. **[🎬 场景设计规范](docs/04-高级开发/场景设计规范.md)** - 场景架构
|
||||
3. **[🧩 模块开发指南](docs/04-高级开发/模块开发指南.md)** - 模块化开发
|
||||
|
||||
### 🎯 第五步：项目发布
|
||||
|
||||
**部署和运维**
|
||||
|
||||
1. **[🌐 Web部署指南](docs/05-部署运维/Web部署指南.md)** - 完整部署流程
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ 项目架构一览
|
||||
|
||||
### 📁 目录结构
|
||||
|
||||
### 目录结构
|
||||
```
|
||||
whaleTown/
|
||||
├── _Core/ # [框架层] 游戏的底层框架，单例，全局管理器
|
||||
│ ├── managers/ # 游戏管理器
|
||||
│ │ ├── GameManager.gd # 游戏状态管理
|
||||
│ │ ├── SceneManager.gd # 场景管理
|
||||
│ │ ├── NetworkManager.gd # 网络通信
|
||||
│ │ └── ResponseHandler.gd # API响应处理
|
||||
│ ├── systems/ # 核心系统
|
||||
│ │ └── EventSystem.gd # 事件系统
|
||||
│ └── singletons/ # 其他单例（待扩展）
|
||||
│
|
||||
├── Scenes/ # [玩法层] 具体的游戏场景、实体、地图
|
||||
│ ├── Maps/ # 地图场景
|
||||
│ │ └── main_scene.tscn # 主游戏场景
|
||||
│ ├── Entities/ # 游戏实体
|
||||
│ │ ├── Player/ # 玩家实体
|
||||
│ │ ├── NPC/ # NPC实体
|
||||
│ │ └── Interactables/ # 交互物
|
||||
│ └── Components/ # 可复用组件
|
||||
│
|
||||
├── UI/ # [界面层] 所有UI相关的预制体和逻辑
|
||||
│ ├── HUD/ # 抬头显示（常驻）
|
||||
│ ├── Windows/ # 模态窗口
|
||||
│ │ └── LoginWindow.tscn # 登录窗口
|
||||
│ ├── Dialog/ # 对话系统
|
||||
│ └── Theme/ # 全局样式
|
||||
│ ├── MainTheme.tres # 主主题
|
||||
│ └── Fonts/ # 字体文件
|
||||
│
|
||||
├── Assets/ # [资源层] 美术、音频、字体
|
||||
│ ├── Sprites/ # 精灵图
|
||||
│ │ ├── icon/ # 图标
|
||||
│ │ ├── materials/ # 材质
|
||||
│ │ ├── shaders/ # 着色器
|
||||
│ │ └── sprites/ # 精灵图
|
||||
│ ├── Audio/ # 音频
|
||||
│ └── Fonts/ # 字体
|
||||
│
|
||||
├── Config/ # [配置层] 游戏配置文件
|
||||
│ ├── game_config.json # 游戏配置
|
||||
│ └── zh_CN.json # 中文本地化
|
||||
│
|
||||
├── Utils/ # [工具层] 通用辅助脚本
|
||||
│ └── StringUtils.gd # 字符串工具
|
||||
│
|
||||
├── Tests/ # [测试层] 单元测试脚本
|
||||
│ ├── api/ # API接口测试
|
||||
│ ├── auth/ # 认证UI测试
|
||||
│ ├── unit/ # 单元测试
|
||||
│ ├── integration/ # 集成测试
|
||||
│ └── performance/ # 性能测试
|
||||
│
|
||||
├── docs/ # 项目文档
|
||||
│ ├── auth/ # 认证相关文档
|
||||
│ ├── api-documentation.md # API接口文档
|
||||
│ ├── web_deployment_guide.md # Web部署完整指南
|
||||
│ ├── web_deployment_changelog.md # Web部署更新日志
|
||||
│ ├── project_structure.md # 项目结构说明
|
||||
│ ├── naming_convention.md # 命名规范
|
||||
│ ├── code_comment_guide.md # 代码注释规范
|
||||
│ └── git_commit_guide.md # Git提交规范
|
||||
│
|
||||
├── tools/ # 开发工具和脚本
|
||||
│ ├── build_web.bat # Windows Web导出脚本
|
||||
│ ├── build_web.sh # Linux/macOS Web导出脚本
|
||||
│ ├── serve_web.bat # Windows 本地服务器
|
||||
│ └── serve_web.sh # Linux/macOS 本地服务器
|
||||
│
|
||||
├── REFACTORING.md # 项目结构重构文档
|
||||
└── MIGRATION_COMPLETE.md # 迁移完成标记
|
||||
WhaleTown/ # 🐋 项目根目录
|
||||
├── 📚 docs/ # 📖 完整文档系统（18个文档）
|
||||
│ ├── 01-项目入门/ # 👋 新人必读
|
||||
│ ├── 02-开发规范/ # 📋 编码标准
|
||||
│ ├── 03-技术实现/ # 🔧 开发指导
|
||||
│ ├── 04-高级开发/ # 🚀 进阶技巧
|
||||
│ ├── 05-部署运维/ # 🌐 发布部署
|
||||
│ └── 06-功能模块/ # 🎮 功能文档
|
||||
├── 🎬 scenes/ # 🎭 游戏场景
|
||||
│ ├── Maps/ # 🗺️ 地图场景
|
||||
│ └── Components/ # 🧩 组件预制体
|
||||
├── 🔧 _Core/ # ⚙️ 核心系统
|
||||
│ ├── managers/ # 🎯 全局管理器
|
||||
│ ├── systems/ # 🔄 系统组件
|
||||
│ ├── EventNames.gd # 📝 事件名称定义
|
||||
│ └── ProjectPaths.gd # 📂 路径统一管理
|
||||
├── 🎨 UI/ # 🖼️ 用户界面
|
||||
│ └── Windows/ # 🪟 窗口界面
|
||||
├── 🔨 Utils/ # 🔨 工具类
|
||||
├── 🎮 module/ # 🧩 功能模块
|
||||
├── 🎨 assets/ # 🖼️ 游戏资源
|
||||
├── ⚙️ Config/ # 📋 配置文件
|
||||
├── 🧪 tests/ # 🔬 测试文件
|
||||
└── 🌐 web_assets/ # 🌍 Web部署资源
|
||||
```
|
||||
|
||||
### 架构层次说明
|
||||
### 🔧 核心组件
|
||||
|
||||
#### 1. 框架层 (_Core/)
|
||||
- **职责**: 游戏的底层框架，与具体游戏逻辑无关
|
||||
- **内容**: 单例管理器、核心系统
|
||||
- **特点**: 自动加载，全局可访问
|
||||
- **命名**: 使用下划线前缀 `_Core` 表示这是核心框架代码
|
||||
| 组件 | 作用 | 文档链接 |
|
||||
|------|------|----------|
|
||||
| **EventSystem** | 全局事件通信 | [架构规范](docs/02-开发规范/架构与通信规范.md) |
|
||||
| **GameManager** | 游戏状态管理 | [实现细节](docs/03-技术实现/实现细节规范.md) |
|
||||
| **SceneManager** | 场景切换管理 | [场景设计](docs/04-高级开发/场景设计规范.md) |
|
||||
| **NetworkManager** | 网络请求管理 | [网络管理器](docs/03-技术实现/网络管理器设置.md) |
|
||||
| **ProjectPaths** | 路径统一管理 | [项目结构](docs/01-项目入门/项目结构说明.md) |
|
||||
|
||||
#### 2. 玩法层 (Scenes/)
|
||||
- **职责**: 游戏世界，地图和实体
|
||||
- **内容**: 游戏场景、角色、NPC、交互物
|
||||
- **特点**: 场景内聚，脚本紧邻场景文件
|
||||
- **组织**: 按游戏世界的实体类型分类
|
||||
---
|
||||
|
||||
#### 3. 界面层 (UI/)
|
||||
- **职责**: 所有界面，HUD和弹窗
|
||||
- **内容**: 常驻界面、模态窗口、对话系统、主题样式
|
||||
- **特点**: 独立于游戏场景，便于UI开发和维护
|
||||
- **组织**: 按界面类型和用途分类
|
||||
|
||||
#### 4. 资源层 (Assets/)
|
||||
- **职责**: 纯美术资源
|
||||
- **内容**: 精灵图、音频、字体等
|
||||
- **特点**: 与代码分离，便于美术组独立工作
|
||||
- **组织**: 按资源类型分类
|
||||
|
||||
#### 5. 配置层 (Config/)
|
||||
- **职责**: 静态数据，策划可编辑
|
||||
- **内容**: 游戏配置、本地化文件
|
||||
- **特点**: 数据驱动，便于调整游戏参数
|
||||
- **格式**: JSON 文件
|
||||
|
||||
#### 6. 工具层 (Utils/)
|
||||
- **职责**: 通用辅助脚本
|
||||
- **内容**: 工具函数库
|
||||
- **特点**: 可被任何层调用
|
||||
- **原则**: 无依赖，纯函数
|
||||
|
||||
### 核心系统
|
||||
项目包含以下自动加载的核心系统（位于 [_Core/](./_Core/)）：
|
||||
|
||||
- **GameManager** - 全局游戏状态管理
|
||||
- **SceneManager** - 场景切换管理
|
||||
- **EventSystem** - 事件通信系统
|
||||
- **NetworkManager** - 网络通信管理
|
||||
- **ResponseHandler** - API响应处理
|
||||
|
||||
使用示例：
|
||||
```gdscript
|
||||
# 状态管理
|
||||
GameManager.change_state(GameManager.GameState.IN_GAME)
|
||||
|
||||
# 场景切换（已更新路径）
|
||||
SceneManager.change_scene("main") # → res://Scenes/Maps/main_scene.tscn
|
||||
|
||||
# 事件通信
|
||||
EventSystem.emit_event("player_health_changed", 80)
|
||||
EventSystem.connect_event("player_died", _on_player_died)
|
||||
```
|
||||
|
||||
### 设计原则
|
||||
|
||||
#### 1. 清晰的分层
|
||||
- **_Core**: 框架代码，与具体游戏逻辑无关
|
||||
- **Scenes**: 游戏世界，地图和实体
|
||||
- **UI**: 所有界面，HUD和弹窗
|
||||
- **Config**: 静态数据，策划可编辑
|
||||
|
||||
#### 2. 组件化设计
|
||||
可复用组件放在 `Scenes/Components/` 下，使用组合优于继承的设计模式：
|
||||
- InteractableArea.tscn - 让任何物体"可交互"
|
||||
- MovementSync.gd - 网络位置同步
|
||||
- NameTag3D.tscn - 头顶名字条
|
||||
|
||||
#### 3. 场景内聚
|
||||
- 每个 .tscn 配套一个 .gd
|
||||
- 脚本紧邻场景文件存放
|
||||
- 符合 Godot 原生开发习惯
|
||||
|
||||
#### 4. 职责单一
|
||||
```
|
||||
UI/Windows/ - 模态窗口（登录、设置、商店）
|
||||
UI/HUD/ - 常驻界面（聊天框、状态栏）
|
||||
UI/Dialog/ - 对话系统
|
||||
```
|
||||
|
||||
### 团队协作
|
||||
- **美术组**: 主要在 [Assets/](./Assets/) 工作
|
||||
- **策划组**: 主要在 [Config/](./Config/) 工作
|
||||
- **程序组**: 主要在 [_Core/](./_Core/), [Scenes/](./Scenes/), [UI/](./UI/) 工作
|
||||
- **测试组**: 主要在 [Tests/](./Tests/) 工作
|
||||
|
||||
## ✨ 主要功能
|
||||
## 🎮 核心功能
|
||||
|
||||
### 🔐 用户认证系统
|
||||
- **用户注册** - 支持邮箱验证码验证
|
||||
- **用户登录** - 多种登录方式（用户名/邮箱/手机号）
|
||||
- **密码管理** - 密码重置和修改功能
|
||||
- **GitHub OAuth** - 第三方登录集成
|
||||
- **错误处理** - 完整的错误提示和频率限制
|
||||
- **UI界面**: [UI/Windows/LoginWindow.tscn](UI/Windows/LoginWindow.tscn)
|
||||
|
||||
### 🌐 Web版本部署
|
||||
- **自动化导出** - 一键导出Web版本
|
||||
- **本地测试服务器** - 内置HTTP服务器用于测试
|
||||
- **生产环境配置** - 完整的服务器配置指南
|
||||
- **跨平台支持** - Windows、Linux、macOS全平台支持
|
||||
- **性能优化** - 资源压缩和加载优化
|
||||
**完整的用户管理功能**
|
||||
- ✅ 用户注册（用户名+邮箱验证）
|
||||
- ✅ 多方式登录（用户名/邮箱/验证码）
|
||||
- ✅ 密码管理（修改/重置）
|
||||
- ✅ 表单验证（实时验证+友好提示）
|
||||
- ✅ 错误处理（网络异常+业务错误）
|
||||
|
||||
### 🎮 游戏功能
|
||||
- **主场景** - 游戏主界面和菜单系统 ([Scenes/Maps/main_scene.tscn](Scenes/Maps/main_scene.tscn))
|
||||
- **认证场景** - 完整的登录注册界面
|
||||
- **状态管理** - 用户状态和游戏状态管理
|
||||
- **网络通信** - RESTful API集成 ([_Core/managers/NetworkManager.gd](_Core/managers/NetworkManager.gd))
|
||||
**技术特色**
|
||||
- 📱 响应式UI设计
|
||||
- 🔄 实时表单验证
|
||||
- ⏰ 验证码冷却机制
|
||||
- 🎨 流畅动画效果
|
||||
|
||||
### 🧪 测试体系
|
||||
- **API测试** - 完整的接口测试脚本 ([Tests/api/](Tests/api/))
|
||||
- **UI测试** - 认证界面的交互测试 ([Tests/auth/](Tests/auth/))
|
||||
- **错误场景** - 边界条件和异常处理测试
|
||||
### 🎮 游戏核心系统
|
||||
|
||||
## 🔧 开发规范
|
||||
**模块化游戏架构**
|
||||
- 🎭 场景管理系统
|
||||
- 🔄 事件通信系统
|
||||
- 🎯 状态管理系统
|
||||
- 🌐 网络通信系统
|
||||
|
||||
### 命名规范
|
||||
- **场景文件**: `snake_case_scene.tscn` (如: `auth_scene.tscn`)
|
||||
- **脚本文件**: `PascalCase.gd` (如: `AuthScene.gd`)
|
||||
- **节点名称**: `camelCase` (如: `loginButton`)
|
||||
- **变量/函数**: `camelCase` (如: `playerHealth`)
|
||||
- **常量**: `UPPER_CASE` (如: `MAX_HEALTH`)
|
||||
- **资源文件**: `snake_case` (如: `bg_auth_scene.png`)
|
||||
**开发友好特性**
|
||||
- 🧩 高度模块化
|
||||
- 📝 完整文档覆盖
|
||||
- 🧪 测试用例齐全
|
||||
- 🔧 开发工具完善
|
||||
|
||||
### 代码注释规范
|
||||
- **文件头注释**: 说明文件用途、主要功能和依赖关系
|
||||
- **函数注释**: 包含参数说明、返回值和使用示例
|
||||
- **复杂逻辑**: 添加行内注释解释业务逻辑和设计决策
|
||||
- **特殊标记**: 使用 TODO、FIXME、NOTE 等标准标记
|
||||
- **AI辅助**: 支持AI补充注释，提供详细的上下文信息
|
||||
---
|
||||
|
||||
### Git 提交规范
|
||||
使用格式：`<类型>：<描述>`
|
||||
## 🧪 测试系统
|
||||
|
||||
常用类型：`feat` `fix` `docs` `refactor` `scene` `asset` `ui` `test`
|
||||
### 🔬 测试类型
|
||||
|
||||
| 测试类型 | 工具 | 覆盖范围 | 文档 |
|
||||
|----------|------|----------|------|
|
||||
| **API测试** | Python脚本 | 17个接口全覆盖 | [测试指南](docs/03-技术实现/测试指南.md) |
|
||||
| **UI测试** | Godot场景 | 认证流程完整测试 | [认证测试](docs/06-功能模块/auth/认证测试指南.md) |
|
||||
| **单元测试** | GUT框架 | 核心组件测试 | [测试指南](docs/03-技术实现/测试指南.md) |
|
||||
|
||||
### 🚀 快速测试
|
||||
|
||||
```bash
|
||||
git commit -m "feat：实现用户登录功能"
|
||||
git commit -m "fix：修复429错误处理"
|
||||
git commit -m "test：添加API接口测试"
|
||||
git commit -m "docs：更新项目文档"
|
||||
# 🔌 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 场景
|
||||
```
|
||||
|
||||
## 📚 项目文档
|
||||
---
|
||||
|
||||
### 核心文档
|
||||
- 📋 [项目结构详解](docs/project_structure.md) - 完整的架构说明
|
||||
- 📝 [命名规范](docs/naming_convention.md) - 详细的命名规则
|
||||
- 💬 [代码注释规范](docs/code_comment_guide.md) - 注释标准和AI辅助指南
|
||||
- 🔀 [Git提交规范](docs/git_commit_guide.md) - 提交信息标准
|
||||
- 🌐 [Web部署指南](docs/web_deployment_guide.md) - 完整的Web部署文档
|
||||
## 🚀 部署发布
|
||||
|
||||
### API和测试文档
|
||||
- 🔌 [API接口文档](docs/api-documentation.md) - 完整的API说明和测试指南
|
||||
- 🔐 [认证系统文档](docs/auth/) - 用户认证相关文档
|
||||
- 🧪 [API测试指南](tests/api/README.md) - API测试使用方法
|
||||
- 🎮 [认证UI测试](tests/auth/README.md) - UI测试场景说明
|
||||
|
||||
## 🛠️ 开发指南
|
||||
|
||||
### 添加新场景
|
||||
1. 在 [Scenes/](./Scenes/) 对应分类下创建场景文件
|
||||
2. 脚本文件紧邻场景文件存放（场景内聚原则）
|
||||
3. 在 [_Core/managers/SceneManager.gd](_Core/managers/SceneManager.gd) 中注册场景路径
|
||||
4. 使用 `SceneManager.change_scene()` 切换场景
|
||||
|
||||
示例：
|
||||
```gdscript
|
||||
# 在 SceneManager.gd 中注册
|
||||
var scene_paths: Dictionary = {
|
||||
"battle": "res://Scenes/Maps/battle_scene.tscn",
|
||||
"shop": "res://UI/Windows/ShopWindow.tscn",
|
||||
}
|
||||
|
||||
# 使用
|
||||
SceneManager.change_scene("battle")
|
||||
```
|
||||
|
||||
### 创建可复用组件
|
||||
1. 在 [Scenes/Components/](./Scenes/Components/) 创建组件场景
|
||||
2. 实现标准接口，保持组件独立性
|
||||
3. 通过 [EventSystem](_Core/systems/EventSystem.gd) 与其他模块通信
|
||||
4. 组件可以被任何场景实例化复用
|
||||
|
||||
### 添加UI界面
|
||||
1. **模态窗口** → 放入 [UI/Windows/](./UI/Windows/)
|
||||
2. **常驻界面** → 放入 [UI/HUD/](./UI/HUD/)
|
||||
3. **对话系统** → 放入 [UI/Dialog/](./UI/Dialog/)
|
||||
4. UI脚本紧邻场景文件，保持内聚
|
||||
|
||||
### 资源管理
|
||||
- **精灵图** → 放入 [Assets/Sprites/](./Assets/Sprites/) 对应分类
|
||||
- **音频文件** → 放入 [Assets/Audio/](./Assets/Audio/) 对应分类
|
||||
- **字体文件** → 放入 [UI/Theme/Fonts/](./UI/Theme/Fonts/)
|
||||
- **配置文件** → 放入 [Config/](./Config/)
|
||||
- 遵循命名规范，使用英文小写+下划线
|
||||
|
||||
### 路径映射参考
|
||||
|
||||
| 功能类型 | 旧路径 | 新路径 |
|
||||
|---------|--------|--------|
|
||||
| 核心管理器 | `core/managers/` | [_Core/managers/](_Core/managers/) |
|
||||
| 游戏场景 | `scenes/main_scene.tscn` | [Scenes/Maps/main_scene.tscn](Scenes/Maps/main_scene.tscn) |
|
||||
| 登录界面 | `scenes/auth_scene.tscn` | [UI/Windows/LoginWindow.tscn](UI/Windows/LoginWindow.tscn) |
|
||||
| 配置文件 | `data/configs/` | [Config/](Config/) |
|
||||
| 工具类 | `core/utils/` | [Utils/](Utils/) |
|
||||
|
||||
详细的重构说明请查看：[REFACTORING.md](REFACTORING.md)
|
||||
|
||||
### API接口测试
|
||||
项目提供了完整的Python测试脚本来验证API接口：
|
||||
### 🖥️ 桌面版本
|
||||
|
||||
```bash
|
||||
# 快速测试API连通性
|
||||
>>>>>>> whale-town-front/main
|
||||
python tests/api/simple_api_test.py
|
||||
# Windows
|
||||
godot --export "Windows Desktop" build/WhaleTown.exe
|
||||
|
||||
# 完整功能测试
|
||||
python tests/api/api_test.py --verbose
|
||||
# Linux
|
||||
godot --export "Linux/X11" build/WhaleTown.x86_64
|
||||
|
||||
# macOS
|
||||
godot --export "macOS" build/WhaleTown.app
|
||||
```
|
||||
|
||||
**测试内容：**
|
||||
- ✅ 用户认证流程测试
|
||||
- ✅ API接口连通性测试
|
||||
- ✅ 错误处理和边界条件测试
|
||||
- ✅ 网络通信功能测试
|
||||
|
||||
---
|
||||
|
||||
## 🎓 新开发者指南
|
||||
|
||||
<<<<<<< HEAD
|
||||
### 第一步：了解项目规范 📚
|
||||
|
||||
**⚠️ 重要：在开始开发前，请务必阅读以下文档**
|
||||
|
||||
1. **[项目结构详解](./docs/project_structure.md)** 🏗️
|
||||
- 理解模块化架构设计
|
||||
- 掌握目录组织规则
|
||||
- 学习组件通信机制
|
||||
|
||||
2. **[命名规范](./docs/naming_convention.md)** 📝
|
||||
- 场景、脚本、节点命名规则
|
||||
- 资源文件命名标准
|
||||
- 变量和函数命名约定
|
||||
|
||||
3. **[代码注释规范](./docs/code_comment_guide.md)** 💬
|
||||
- 注释标准和最佳实践
|
||||
- AI辅助开发指南
|
||||
- 文档生成规范
|
||||
|
||||
4. **[Git提交规范](./docs/git_commit_guide.md)** 🔄
|
||||
- 提交信息格式标准
|
||||
- 分支管理策略
|
||||
- 代码审查流程
|
||||
|
||||
### 第二步：熟悉项目架构 🏗️
|
||||
|
||||
```
|
||||
whaleTown/
|
||||
├── 🎬 scenes/ # 游戏场景
|
||||
│ ├── auth_scene.tscn # 🔐 用户认证场景
|
||||
│ ├── main_scene.tscn # 🎮 主游戏场景
|
||||
│ └── prefabs/ # 🧩 预制体组件
|
||||
├── 🔧 core/ # 核心系统（自动加载）
|
||||
│ ├── managers/ # 🎯 全局管理器
|
||||
│ ├── systems/ # ⚙️ 系统组件
|
||||
│ └── utils/ # 🛠️ 工具类
|
||||
├── 📝 scripts/ # 业务逻辑脚本
|
||||
│ ├── scenes/ # 🎬 场景脚本
|
||||
│ ├── network/ # 🌐 网络相关
|
||||
│ └── ui/ # 🎨 UI组件脚本
|
||||
├── 🧩 module/ # 可复用模块
|
||||
│ ├── UI/ # 🎨 UI组件模块
|
||||
│ ├── Character/ # 👤 角色模块
|
||||
│ ├── Combat/ # ⚔️ 战斗模块
|
||||
│ ├── Dialogue/ # 💬 对话模块
|
||||
│ └── Inventory/ # 🎒 背包模块
|
||||
├── 🎨 assets/ # 游戏资源
|
||||
│ ├── sprites/ # 🖼️ 精灵图资源
|
||||
│ ├── audio/ # 🔊 音频文件
|
||||
│ ├── ui/ # 🎨 UI界面资源
|
||||
│ └── fonts/ # 🔤 字体资源
|
||||
├── 📊 data/ # 配置数据
|
||||
│ ├── configs/ # ⚙️ 游戏配置
|
||||
│ ├── localization/ # 🌍 本地化文件
|
||||
│ └── characters/ # 👤 角色数据
|
||||
├── 🧪 tests/ # 测试文件
|
||||
│ ├── api/ # 🔌 API接口测试
|
||||
│ ├── auth/ # 🔐 认证UI测试
|
||||
│ └── unit/ # 🧪 单元测试
|
||||
└── 📚 docs/ # 项目文档
|
||||
├── auth/ # 🔐 认证相关文档
|
||||
└── api-documentation.md # 📖 API接口文档
|
||||
```
|
||||
|
||||
**架构特点：**
|
||||
- 🏗️ **模块化设计** - 按功能而非技术组织代码
|
||||
- 🔄 **事件驱动** - 通过EventSystem实现组件间通信
|
||||
- 📦 **清晰分层** - 场景层 → 业务层 → 核心层
|
||||
- 🧪 **测试友好** - 完整的测试覆盖和文档
|
||||
|
||||
### 第三步：体验核心功能 🎮
|
||||
|
||||
1. **用户认证系统** 🔐
|
||||
- 邮箱验证码注册
|
||||
- 多方式登录（用户名/邮箱/手机号）
|
||||
- 密码重置功能
|
||||
|
||||
2. **游戏核心系统** 🎮
|
||||
- 场景管理和切换
|
||||
- 角色状态管理
|
||||
- 实时网络通信
|
||||
|
||||
3. **开发工具** 🛠️
|
||||
- 内置测试场景
|
||||
- API测试脚本
|
||||
- 性能监控工具
|
||||
|
||||
### 第四步：开始贡献 🤝
|
||||
|
||||
1. **Fork项目** 到你的账户
|
||||
2. **创建功能分支**：`git checkout -b feature/your-feature`
|
||||
3. **遵循规范开发**（参考文档）
|
||||
4. **添加测试用例**：确保功能正确性
|
||||
5. **提交代码**：`git commit -m "feat：添加新功能"`
|
||||
6. **创建Pull Request**
|
||||
|
||||
---
|
||||
|
||||
## <20>[️ 技术栈
|
||||
|
||||
### 🎮 游戏引擎
|
||||
- **Godot Engine** `4.5.1` - 开源游戏引擎，支持2D/3D开发
|
||||
- **GDScript** - Godot专用脚本语言，Python风格语法
|
||||
- **Forward Plus** - 现代渲染管线，支持高质量光照
|
||||
|
||||
### 🏗️ 架构设计
|
||||
- **模块化架构** - 按功能组织的可复用组件系统
|
||||
- **事件驱动** - 基于EventSystem的松耦合通信
|
||||
- **单例管理器** - GameManager、SceneManager等全局管理器
|
||||
- **状态机模式** - 游戏状态和角色状态管理
|
||||
|
||||
### 🌐 网络通信
|
||||
- **RESTful API** - 标准HTTP接口通信
|
||||
- **JSON数据格式** - 轻量级数据交换格式
|
||||
- **WebSocket** - 实时双向通信支持
|
||||
- **错误处理** - 完整的网络异常处理机制
|
||||
|
||||
### 🎨 UI系统
|
||||
- **响应式设计** - 支持多分辨率自适应
|
||||
- **主题系统** - 统一的UI风格管理
|
||||
- **动画系统** - 流畅的界面过渡效果
|
||||
- **本地化支持** - 多语言界面切换
|
||||
|
||||
### 🧪 测试框架
|
||||
- **Godot内置测试** - 场景和组件测试
|
||||
- **Python测试脚本** - API接口自动化测试
|
||||
- **性能监控** - 帧率和内存使用监控
|
||||
- **错误追踪** - 完整的日志和错误报告
|
||||
|
||||
### 📱 跨平台支持
|
||||
- **桌面平台** - Windows、Linux、macOS
|
||||
- **移动平台** - Android、iOS（规划中）
|
||||
- **Web平台** - HTML5导出支持（规划中）
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ 核心功能
|
||||
|
||||
### 🔐 用户认证系统 (scenes/auth_scene.tscn)
|
||||
- **多方式登录** - 用户名/邮箱/手机号
|
||||
- **邮箱验证** - 完整的验证码流程和倒计时
|
||||
- **密码安全** - 强度验证和安全提示
|
||||
- **错误处理** - 友好的错误提示和状态管理
|
||||
- **响应式UI** - 自适应布局和动画效果
|
||||
|
||||
### 🎮 游戏核心系统 (core/)
|
||||
- **GameManager** - 全局游戏状态管理（LOADING、AUTH、IN_GAME等）
|
||||
- **SceneManager** - 场景切换和生命周期管理
|
||||
- **EventSystem** - 全局事件通信系统
|
||||
- **StringUtils** - 字符串处理工具集
|
||||
|
||||
### 🧩 模块化组件 (module/)
|
||||
- **UI组件** - 可复用的界面组件和动画
|
||||
- **角色系统** - 角色数据和行为管理
|
||||
- **战斗系统** - 战斗逻辑和技能系统
|
||||
- **对话系统** - 对话树和文本显示
|
||||
- **背包系统** - 物品管理和交互
|
||||
|
||||
### 🌐 网络通信 (scripts/network/)
|
||||
- **API集成** - RESTful接口调用封装
|
||||
- **实时通信** - WebSocket连接管理
|
||||
- **数据同步** - 客户端服务器数据同步
|
||||
- **离线处理** - 网络异常和离线模式
|
||||
|
||||
### 🧪 测试体系 (tests/)
|
||||
- **API测试** - 完整的接口功能测试
|
||||
- **UI测试** - 交互式界面测试场景
|
||||
- **单元测试** - 组件和函数级别测试
|
||||
- **集成测试** - 完整业务流程测试
|
||||
- **性能测试** - 帧率和内存性能监控
|
||||
|
||||
---
|
||||
|
||||
## 📊 开发与测试
|
||||
|
||||
### 🔧 开发命令
|
||||
### 🌐 Web版本
|
||||
|
||||
```bash
|
||||
# 启动Godot编辑器
|
||||
godot --editor
|
||||
# 使用自动化脚本
|
||||
scripts/build_web.bat # Windows
|
||||
scripts/build_web.sh # Linux/macOS
|
||||
|
||||
# 运行项目（无编辑器）
|
||||
godot --main-pack game.pck
|
||||
|
||||
# 导出项目
|
||||
godot --export "Windows Desktop" game.exe
|
||||
|
||||
# 运行测试
|
||||
godot --headless --script tests/run_tests.gd
|
||||
# 本地测试
|
||||
scripts/serve_web.bat # 启动本地服务器
|
||||
```
|
||||
|
||||
### 🧪 测试命令
|
||||
|
||||
```bash
|
||||
# API接口测试
|
||||
python tests/api/simple_api_test.py
|
||||
|
||||
# 完整功能测试
|
||||
python tests/api/api_test.py --verbose
|
||||
|
||||
# 自定义服务器测试
|
||||
python tests/api/simple_api_test.py https://your-server.com
|
||||
|
||||
# UI交互测试
|
||||
# 在Godot编辑器中运行 tests/auth/auth_ui_test.tscn
|
||||
```
|
||||
|
||||
### 📈 测试覆盖率
|
||||
- **API测试**: 17个接口全覆盖 ✅
|
||||
- **UI测试**: 认证流程完整测试 ✅
|
||||
- **错误处理**: 边界条件和异常测试 ✅
|
||||
- **性能测试**: 帧率和内存监控 ✅
|
||||
**详细部署流程**: [Web部署指南](docs/05-部署运维/Web部署指南.md)
|
||||
|
||||
---
|
||||
|
||||
## 🌍 部署配置
|
||||
## 📊 项目统计
|
||||
|
||||
### 开发环境（默认）
|
||||
```bash
|
||||
# 本地开发配置
|
||||
API_BASE_URL=http://localhost:3000
|
||||
DEBUG_MODE=true
|
||||
LOG_LEVEL=debug
|
||||
```
|
||||
### 📚 文档系统
|
||||
|
||||
### 生产环境
|
||||
```bash
|
||||
# 生产环境配置
|
||||
API_BASE_URL=https://your-api-server.com
|
||||
DEBUG_MODE=false
|
||||
LOG_LEVEL=info
|
||||
ENABLE_ANALYTICS=true
|
||||
```
|
||||
| 类别 | 文档数 | 完成度 |
|
||||
|------|--------|--------|
|
||||
| 项目入门 | 3 | 100% |
|
||||
| 开发规范 | 5 | 100% |
|
||||
| 技术实现 | 4 | 100% |
|
||||
| 高级开发 | 3 | 100% |
|
||||
| 部署运维 | 1 | 100% |
|
||||
| 功能模块 | 2 | 100% |
|
||||
| **总计** | **18** | **100%** |
|
||||
|
||||
### 导出设置
|
||||
- **Windows**: 64位可执行文件
|
||||
- **Linux**: AppImage格式
|
||||
- **macOS**: .app应用包
|
||||
- **Android**: APK安装包（规划中）
|
||||
### 🧪 测试覆盖
|
||||
|
||||
- **API接口**: 17个接口 ✅
|
||||
- **认证流程**: 完整测试 ✅
|
||||
- **错误处理**: 边界测试 ✅
|
||||
- **性能监控**: 帧率/内存 ✅
|
||||
|
||||
---
|
||||
|
||||
## 📚 文档中心
|
||||
## 🤝 参与贡献
|
||||
|
||||
### 🎯 新手必读
|
||||
1. **[项目结构详解](./docs/project_structure.md)** - 架构设计和组织规则
|
||||
2. **[命名规范](./docs/naming_convention.md)** - 代码和资源命名标准
|
||||
3. **[代码注释规范](./docs/code_comment_guide.md)** - 注释标准和AI辅助
|
||||
4. **[Git提交规范](./docs/git_commit_guide.md)** - 版本控制最佳实践
|
||||
|
||||
### 📖 功能文档
|
||||
- **[用户认证系统](./docs/auth/)** - 认证流程和界面设计
|
||||
- **[API接口文档](./docs/api-documentation.md)** - 完整的API使用指南
|
||||
- **[测试指南](./tests/api/README.md)** - 测试用例和使用方法
|
||||
|
||||
### 🏗️ 开发指南
|
||||
- **[模块开发指南](./docs/module_development.md)** - 如何创建新模块
|
||||
- **[场景设计规范](./docs/scene_design.md)** - 场景架构和最佳实践
|
||||
- **[性能优化指南](./docs/performance_guide.md)** - 性能调优技巧
|
||||
|
||||
---
|
||||
|
||||
## 🤝 贡献者
|
||||
|
||||
感谢所有为项目做出贡献的开发者！
|
||||
|
||||
### 🏆 核心团队
|
||||
- **[moyin](https://gitea.xinghangee.icu/moyin)** - 核心开发者
|
||||
- **[jianuo](https://gitea.xinghangee.icu/jianuo)** - 核心开发者
|
||||
- **[angjustinl](https://gitea.xinghangee.icu/ANGJustinl)** - 核心开发者
|
||||
|
||||
查看完整贡献者名单：[docs/CONTRIBUTORS.md](./docs/CONTRIBUTORS.md)
|
||||
|
||||
### 🌟 如何贡献
|
||||
|
||||
我们欢迎所有形式的贡献：
|
||||
### 🌟 贡献方式
|
||||
|
||||
1. **🐛 Bug修复** - 发现并修复问题
|
||||
2. **✨ 新功能** - 添加有价值的功能
|
||||
2. **✨ 新功能** - 添加有价值的功能
|
||||
3. **📚 文档改进** - 完善项目文档
|
||||
4. **🧪 测试用例** - 提高代码覆盖率
|
||||
5. **🎨 UI/UX改进** - 提升用户体验
|
||||
6. **⚡ 性能优化** - 优化游戏性能
|
||||
|
||||
**贡献流程：**
|
||||
1. Fork项目 → 2. 创建分支 → 3. 开发功能 → 4. 提交PR
|
||||
### 📋 贡献流程
|
||||
|
||||
```bash
|
||||
# 1️⃣ Fork项目到你的账户
|
||||
|
||||
# 2️⃣ 克隆到本地
|
||||
git clone <your-fork-url>
|
||||
cd whale-town
|
||||
|
||||
# 3️⃣ 创建功能分支
|
||||
git checkout -b feature/your-feature
|
||||
|
||||
# 4️⃣ 开发功能（遵循项目规范）
|
||||
# 参考: docs/02-开发规范/
|
||||
|
||||
# 5️⃣ 添加测试用例
|
||||
# 参考: docs/03-技术实现/测试指南.md
|
||||
|
||||
# 6️⃣ 提交代码
|
||||
git commit -m "feat：添加新功能"
|
||||
# 参考: docs/02-开发规范/Git提交规范.md
|
||||
|
||||
# 7️⃣ 推送分支
|
||||
git push origin feature/your-feature
|
||||
|
||||
# 8️⃣ 创建Pull Request
|
||||
```
|
||||
|
||||
### 📖 开发规范
|
||||
|
||||
**必读文档**：
|
||||
- [命名规范](docs/02-开发规范/命名规范.md) - 代码命名标准
|
||||
- [Git提交规范](docs/02-开发规范/Git提交规范.md) - 提交信息格式
|
||||
- [代码注释规范](docs/02-开发规范/代码注释规范.md) - 注释标准
|
||||
|
||||
### 🙏 贡献者致谢
|
||||
|
||||
感谢所有为 WhaleTown 项目做出贡献的开发者们！详细的贡献者信息和统计请查看：
|
||||
|
||||
**[📖 贡献者详细信息](docs/CONTRIBUTORS.md)**
|
||||
|
||||
---
|
||||
|
||||
## 📞 联系我们
|
||||
## 📞 获取帮助
|
||||
|
||||
### 🔍 问题解决
|
||||
|
||||
| 问题类型 | 解决方案 |
|
||||
|----------|----------|
|
||||
| **🤔 不知道从哪开始** | [项目入门总览](docs/01-项目入门/README.md) |
|
||||
| **🏗️ 不理解项目架构** | [项目结构说明](docs/01-项目入门/项目结构说明.md) |
|
||||
| **🔧 开发环境问题** | [项目设置指南](docs/01-项目入门/项目设置指南.md) |
|
||||
| **📝 不知道怎么命名** | [命名规范](docs/02-开发规范/命名规范.md) |
|
||||
| **🔄 组件通信问题** | [架构与通信规范](docs/02-开发规范/架构与通信规范.md) |
|
||||
| **🌐 API调用问题** | [API接口文档](docs/03-技术实现/API接口文档.md) |
|
||||
| **🧪 测试相关问题** | [测试指南](docs/03-技术实现/测试指南.md) |
|
||||
| **🚀 部署发布问题** | [Web部署指南](docs/05-部署运维/Web部署指南.md) |
|
||||
|
||||
### 📚 文档导航
|
||||
|
||||
- **[📖 完整文档中心](docs/README.md)** - 所有文档的导航页面
|
||||
- **[📋 文档更新日志](docs/CHANGELOG.md)** - 文档版本变更记录
|
||||
|
||||
### 💬 联系方式
|
||||
|
||||
- **项目地址**: [Gitea Repository](https://gitea.xinghangee.icu/datawhale/whale-town)
|
||||
- **问题反馈**: [Issues](https://gitea.xinghangee.icu/datawhale/whale-town/issues)
|
||||
- **功能建议**: [Discussions](https://gitea.xinghangee.icu/datawhale/whale-town/discussions)
|
||||
|
||||
---
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
本项目采用 [MIT License](./LICENSE) 开源协议。
|
||||
@@ -696,24 +352,12 @@ ENABLE_ANALYTICS=true
|
||||
|
||||
<div align="center">
|
||||
|
||||
**🐋 Whale Town - 让像素世界更精彩！**
|
||||
**🐋 WhaleTown - 企业级像素游戏开发框架**
|
||||
|
||||
Made with ❤️ by the Whale Town Team
|
||||
*让游戏开发更简单，让代码质量更优秀*
|
||||
|
||||
[⭐ Star](https://gitea.xinghangee.icu/datawhale/whale-town) | [🍴 Fork](https://gitea.xinghangee.icu/datawhale/whale-town/fork) | [📖 Docs](./docs/) | [🐛 Issues](https://gitea.xinghangee.icu/datawhale/whale-town/issues)
|
||||
[⭐ Star](https://gitea.xinghangee.icu/datawhale/whale-town) | [🍴 Fork](https://gitea.xinghangee.icu/datawhale/whale-town/fork) | [📖 文档](./docs/) | [🐛 反馈](https://gitea.xinghangee.icu/datawhale/whale-town/issues)
|
||||
|
||||
</div>
|
||||
=======
|
||||
- ✅ 基础架构搭建完成
|
||||
- ✅ 项目结构重构完成（2025-12-31）
|
||||
- ✅ 用户认证系统完成
|
||||
- ✅ API接口集成完成
|
||||
- ✅ 测试体系建立完成
|
||||
- ✅ 文档体系完善
|
||||
- 🚧 游戏核心玩法开发中
|
||||
- 🚧 更多功能模块开发中
|
||||
**文档版本**: v1.2.0 | **最后更新**: 2025-12-31
|
||||
|
||||
**最后更新**: 2025-12-31
|
||||
|
||||
**重要更新**: 项目已完成架构重构，采用新的分层结构。详见 [REFACTORING.md](REFACTORING.md)
|
||||
>>>>>>> whale-town-front/main
|
||||
</div>
|
||||
58
_Core/EventNames.gd
Normal file
58
_Core/EventNames.gd
Normal file
@@ -0,0 +1,58 @@
|
||||
# ============================================================================
|
||||
# 事件名称定义 - EventNames.gd
|
||||
#
|
||||
# 定义项目中所有事件的名称常量，确保事件名称的一致性和可维护性
|
||||
#
|
||||
# 使用方式:
|
||||
# EventSystem.emit_event(EventNames.PLAYER_MOVED, data)
|
||||
# EventSystem.connect_event(EventNames.INTERACT_PRESSED, callback)
|
||||
# ============================================================================
|
||||
|
||||
class_name EventNames
|
||||
|
||||
# ============================================================================
|
||||
# 玩家相关事件
|
||||
# ============================================================================
|
||||
const PLAYER_MOVED = "player_moved"
|
||||
const PLAYER_SPAWNED = "player_spawned"
|
||||
const PLAYER_HEALTH_CHANGED = "player_health_changed"
|
||||
const PLAYER_DIED = "player_died"
|
||||
const PLAYER_RESPAWNED = "player_respawned"
|
||||
const PLAYER_ATTACK = "player_attack"
|
||||
|
||||
# ============================================================================
|
||||
# 交互事件
|
||||
# ============================================================================
|
||||
const INTERACT_PRESSED = "interact_pressed"
|
||||
const NPC_TALKED = "npc_talked"
|
||||
const ITEM_COLLECTED = "item_collected"
|
||||
const OBJECT_INTERACTED = "object_interacted"
|
||||
|
||||
# ============================================================================
|
||||
# UI事件
|
||||
# ============================================================================
|
||||
const UI_BUTTON_CLICKED = "ui_button_clicked"
|
||||
const DIALOG_OPENED = "dialog_opened"
|
||||
const DIALOG_CLOSED = "dialog_closed"
|
||||
const MENU_OPENED = "menu_opened"
|
||||
const MENU_CLOSED = "menu_closed"
|
||||
|
||||
# ============================================================================
|
||||
# 游戏状态事件
|
||||
# ============================================================================
|
||||
const GAME_PAUSED = "game_paused"
|
||||
const GAME_RESUMED = "game_resumed"
|
||||
const SCENE_CHANGED = "scene_changed"
|
||||
const SCENE_DATA_TRANSFER = "scene_data_transfer"
|
||||
|
||||
# ============================================================================
|
||||
# 系统事件
|
||||
# ============================================================================
|
||||
const TILEMAP_READY = "tilemap_ready"
|
||||
const COMPONENT_MESSAGE = "component_message"
|
||||
const POSITION_UPDATE = "position_update"
|
||||
|
||||
# ============================================================================
|
||||
# 测试事件
|
||||
# ============================================================================
|
||||
const TEST_EVENT = "test_event"
|
||||
1
_Core/EventNames.gd.uid
Normal file
1
_Core/EventNames.gd.uid
Normal file
@@ -0,0 +1 @@
|
||||
uid://qn0imbklx1m0
|
||||
107
_Core/ProjectPaths.gd
Normal file
107
_Core/ProjectPaths.gd
Normal file
@@ -0,0 +1,107 @@
|
||||
# ============================================================================
|
||||
# 项目路径配置 - ProjectPaths.gd
|
||||
#
|
||||
# 统一管理项目中所有路径常量，确保路径的一致性和可维护性
|
||||
#
|
||||
# 使用方式:
|
||||
# var scene_path = ProjectPaths.SCENES_COMPONENTS + "ui/Button.tscn"
|
||||
# var config_path = ProjectPaths.DATA_CONFIG + "game_config.json"
|
||||
# ============================================================================
|
||||
|
||||
class_name ProjectPaths
|
||||
|
||||
# ============================================================================
|
||||
# 核心系统路径
|
||||
# ============================================================================
|
||||
const CORE_ROOT = "res://_Core/"
|
||||
const CORE_MANAGERS = CORE_ROOT + "managers/"
|
||||
const CORE_SYSTEMS = CORE_ROOT + "systems/"
|
||||
|
||||
# ============================================================================
|
||||
# 场景路径
|
||||
# ============================================================================
|
||||
const SCENES_ROOT = "res://scenes/"
|
||||
const SCENES_MAPS = SCENES_ROOT + "Maps/"
|
||||
const SCENES_COMPONENTS = SCENES_ROOT + "Components/"
|
||||
const SCENES_UI_COMPONENTS = SCENES_COMPONENTS + "ui/"
|
||||
const SCENES_CHARACTER_COMPONENTS = SCENES_COMPONENTS + "characters/"
|
||||
const SCENES_EFFECT_COMPONENTS = SCENES_COMPONENTS + "effects/"
|
||||
const SCENES_ITEM_COMPONENTS = SCENES_COMPONENTS + "items/"
|
||||
|
||||
# ============================================================================
|
||||
# UI路径
|
||||
# ============================================================================
|
||||
const UI_ROOT = "res://UI/"
|
||||
const UI_WINDOWS = UI_ROOT + "Windows/"
|
||||
|
||||
# ============================================================================
|
||||
# 资源路径
|
||||
# ============================================================================
|
||||
const ASSETS_ROOT = "res://assets/"
|
||||
const ASSETS_SPRITES = ASSETS_ROOT + "sprites/"
|
||||
const ASSETS_AUDIO = ASSETS_ROOT + "audio/"
|
||||
const ASSETS_FONTS = ASSETS_ROOT + "fonts/"
|
||||
const ASSETS_MATERIALS = ASSETS_ROOT + "materials/"
|
||||
const ASSETS_SHADERS = ASSETS_ROOT + "shaders/"
|
||||
|
||||
# ============================================================================
|
||||
# 数据路径
|
||||
# ============================================================================
|
||||
const DATA_ROOT = "res://data/"
|
||||
const DATA_CONFIG = "res://Config/"
|
||||
const DATA_SCENES = DATA_ROOT + "scenes/"
|
||||
const DATA_LEVELS = DATA_ROOT + "levels/"
|
||||
const DATA_DIALOGUES = DATA_ROOT + "dialogues/"
|
||||
|
||||
# ============================================================================
|
||||
# Web资源路径
|
||||
# ============================================================================
|
||||
const WEB_ASSETS = "res://web_assets/"
|
||||
|
||||
# ============================================================================
|
||||
# 测试路径
|
||||
# ============================================================================
|
||||
const TESTS_ROOT = "res://tests/"
|
||||
const TESTS_UNIT = TESTS_ROOT + "unit/"
|
||||
const TESTS_INTEGRATION = TESTS_ROOT + "integration/"
|
||||
const TESTS_AUTH = TESTS_ROOT + "auth/"
|
||||
|
||||
# ============================================================================
|
||||
# 工具路径
|
||||
# ============================================================================
|
||||
const UTILS_ROOT = "res://Utils/"
|
||||
|
||||
# ============================================================================
|
||||
# 模块路径
|
||||
# ============================================================================
|
||||
const MODULES_ROOT = "res://module/"
|
||||
|
||||
# ============================================================================
|
||||
# 辅助方法
|
||||
# ============================================================================
|
||||
|
||||
# 获取场景组件路径
|
||||
static func get_component_path(category: String, component_name: String) -> String:
|
||||
match category:
|
||||
"ui":
|
||||
return SCENES_UI_COMPONENTS + component_name + ".tscn"
|
||||
"characters":
|
||||
return SCENES_CHARACTER_COMPONENTS + component_name + ".tscn"
|
||||
"effects":
|
||||
return SCENES_EFFECT_COMPONENTS + component_name + ".tscn"
|
||||
"items":
|
||||
return SCENES_ITEM_COMPONENTS + component_name + ".tscn"
|
||||
_:
|
||||
return SCENES_COMPONENTS + component_name + ".tscn"
|
||||
|
||||
# 获取模块路径
|
||||
static func get_module_path(module_name: String) -> String:
|
||||
return MODULES_ROOT + module_name + "/"
|
||||
|
||||
# 获取模块配置路径
|
||||
static func get_module_config_path(module_name: String) -> String:
|
||||
return get_module_path(module_name) + "data/module_config.json"
|
||||
|
||||
# 获取场景数据路径
|
||||
static func get_scene_data_path(scene_name: String) -> String:
|
||||
return DATA_SCENES + scene_name.to_lower() + ".json"
|
||||
1
_Core/ProjectPaths.gd.uid
Normal file
1
_Core/ProjectPaths.gd.uid
Normal file
@@ -0,0 +1 @@
|
||||
uid://dybcuscku7tyl
|
||||
@@ -1,6 +1,6 @@
|
||||
[gd_resource type="Theme" load_steps=2 format=3 uid="uid://cp7t8tu7rmyad"]
|
||||
|
||||
[ext_resource type="FontFile" uid="uid://ce7ujbeobblyr" path="res://assets/fonts/msyh.ttc" id="1_ftb5w"]
|
||||
[ext_resource type="FontFile" uid="uid://ce7ujbeobblyr" path="res://UI/Theme/Fonts/msyh.ttc" id="1_ftb5w"]
|
||||
|
||||
[resource]
|
||||
resource_local_to_scene = true
|
||||
|
||||
123
cloude.md
Normal file
123
cloude.md
Normal file
@@ -0,0 +1,123 @@
|
||||
# 🎯 WhaleTown 项目开发规范
|
||||
|
||||
## 1. 项目愿景与背景
|
||||
- **项目名称**: "WhaleTown" - 一个2D俯视角像素风RPG游戏
|
||||
- **引擎**: Godot 4.2+ (严格禁止使用Godot 3.x语法)
|
||||
- **架构**: 严格分层架构：`_Core`(框架层)、`Scenes`(游戏层)、`UI`(界面层)
|
||||
- **核心原则**: "信号向上，调用向下"。通过`EventSystem`实现高度解耦
|
||||
|
||||
## 2. 🛠 命令参考与设置
|
||||
- **输入映射 (必需配置)**:
|
||||
- `move_left`, `move_right`, `move_up`, `move_down` (WASD / 方向键)
|
||||
- `interact` (E键 / 空格键)
|
||||
- `pause` (ESC键)
|
||||
- **运行游戏**: `godot --path .`
|
||||
- **运行测试 (GUT)**: `godot --headless -s addons/gut/gut_cmdline.gd -gdir=res://tests/ -ginclude_subdirs`
|
||||
- **初始化结构**: `mkdir -p _Core/managers _Core/systems Scenes/Maps Scenes/Entities Scenes/Components UI/Windows UI/HUD Assets/Sprites tests/unit tests/integration`
|
||||
|
||||
## 3. 📂 文件路径规则 (严格小写)
|
||||
*注意：根目录文件夹必须小写。脚本和场景必须放在一起。*
|
||||
- **核心管理器**: `_Core/managers/[Name].gd`
|
||||
- **核心系统**: `_Core/systems/[Name].gd`
|
||||
- **实体**: `Scenes/Entities/[EntityName]/[EntityName].tscn` (脚本`.gd`放在同一文件夹)
|
||||
- **地图**: `Scenes/Maps/[map_name].tscn`
|
||||
- **组件**: `Scenes/Components/[ComponentName].gd` (可复用逻辑节点)
|
||||
- **UI窗口**: `UI/Windows/[WindowName].tscn`
|
||||
- **测试**: `tests/[unit|integration]/test_[name].gd` (文件夹名为小写`tests`)
|
||||
|
||||
## 4. 📋 编码标准 (必须遵守)
|
||||
- **类型安全**: 始终使用严格静态类型：`var speed: float = 100.0`, `func _ready() -> void`
|
||||
- **命名约定**:
|
||||
- 每个脚本顶部必须有`class_name PascalCase`
|
||||
- 变量/函数：`snake_case`。常量：`SCREAMING_SNAKE_CASE`
|
||||
- 私有成员：使用下划线前缀`_` (例如：`var _health: int`)
|
||||
- **节点访问**: 对UI和内部场景组件使用`%UniqueName`
|
||||
- **信号**: 使用"信号向上，调用向下"原则。父节点调用子节点方法；子节点发出信号
|
||||
- **禁止模式**:
|
||||
- ❌ 禁止使用`yield()` -> 使用`await`
|
||||
- ❌ 禁止在`_process`中使用`get_node()` -> 使用`@onready`缓存
|
||||
- ❌ 禁止线性过滤 -> 所有Sprite2D/TileMap资源必须使用**最近邻**过滤
|
||||
|
||||
## 5. 🏛 架构与通信
|
||||
- **事件系统**: 使用`_Core/systems/EventSystem.gd`进行跨模块消息传递
|
||||
- **事件注册**: 在`_Core/EventNames.gd`中使用`class_name EventNames`
|
||||
```gdscript
|
||||
class_name EventNames
|
||||
const PLAYER_MOVED = "player_moved"
|
||||
const INTERACT_PRESSED = "interact_pressed"
|
||||
const NPC_TALKED = "npc_talked"
|
||||
```
|
||||
- **单例**: 只允许GameManager、SceneManager、EventSystem作为自动加载
|
||||
- **解耦**: 底层实体不得直接引用GameManager。使用事件系统
|
||||
|
||||
## 6. 🏗 实现细节
|
||||
- **玩家**: 使用CharacterBody2D。必须包含Camera2D，设置`position_smoothing_enabled = true`
|
||||
- **NPC/交互物**: 使用名为InteractionArea的Area2D。通过EventSystem触发
|
||||
- **TileMap图层**:
|
||||
- 图层0：地面 (无碰撞)
|
||||
- 图层1：障碍物 (启用物理层)
|
||||
- 图层2：装饰 (启用Y排序)
|
||||
- **相机**: 必须通过`TileMap.get_used_rect()`自动计算边界
|
||||
|
||||
## 7. 🧪 测试要求 (强制性)
|
||||
- **覆盖率**: `_Core/`中的每个管理器/系统都必须有GUT测试
|
||||
- **命名**: 测试文件必须以`test_`开头并继承`GutTest`
|
||||
- **示例**:
|
||||
```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. 🧘 开发哲学
|
||||
- **流畅体验**: 每个交互(UI弹窗、NPC对话)都必须有Tween动画占位符
|
||||
- **零魔法数字**: 所有速度/计时器必须使用`@export`或在`Config/`中定义
|
||||
- **简洁性**: 如果一个函数做两件事，就拆分它
|
||||
- **隐藏逻辑**: 隐藏的逻辑(如ResponseHandler.gd)必须和HUD一样干净
|
||||
|
||||
## 9. 📝 代码模板 (实体模式)
|
||||
```gdscript
|
||||
extends CharacterBody2D
|
||||
class_name Player
|
||||
|
||||
# 1. 导出变量与常量
|
||||
@export var move_speed: float = 200.0
|
||||
|
||||
# 2. 节点引用
|
||||
@onready var sprite: Sprite2D = %Sprite2D
|
||||
|
||||
# 3. 生命周期
|
||||
func _physics_process(delta: float) -> void:
|
||||
_move(delta)
|
||||
|
||||
# 4. 私有方法
|
||||
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()
|
||||
```
|
||||
|
||||
## 10. 🎨 UI设计规范
|
||||
- **响应式布局**: 使用Anchor和Margin实现自适应
|
||||
- **主题统一**: 所有UI组件使用统一主题资源
|
||||
- **动画效果**: 界面切换必须有过渡动画
|
||||
- **无障碍支持**: 支持键盘导航
|
||||
|
||||
## 11. 🔧 性能优化
|
||||
- **对象池**: 频繁创建销毁的对象使用对象池
|
||||
- **视锥剔除**: 只渲染可见区域的对象
|
||||
- **批量处理**: 合并相似的渲染调用
|
||||
- **内存管理**: 及时释放不需要的资源
|
||||
|
||||
## 12. 📚 最佳实践
|
||||
- **模块化**: 功能拆分为独立模块
|
||||
- **可测试**: 设计易于测试的代码结构
|
||||
- **文档化**: 为复杂逻辑添加详细注释
|
||||
- **版本控制**: 遵循Git提交规范
|
||||
|
||||
---
|
||||
|
||||
**记住：代码质量是游戏成功的基础！**
|
||||
85
docs/01-项目入门/README.md
Normal file
85
docs/01-项目入门/README.md
Normal file
@@ -0,0 +1,85 @@
|
||||
# 📖 项目入门
|
||||
|
||||
> **适用人群**: 新加入项目的开发者
|
||||
> **使用时机**: 项目开始前，环境搭建阶段
|
||||
> **质量等级**: 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)。
|
||||
157
docs/01-项目入门/输入映射配置.md
Normal file
157
docs/01-项目入门/输入映射配置.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# 输入映射配置指南
|
||||
|
||||
本文档说明了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中正确配置了手柄按钮映射。
|
||||
|
||||
---
|
||||
|
||||
**注意：输入映射配置是游戏正常运行的基础，请确保所有必需的输入动作都已正确配置！**
|
||||
334
docs/01-项目入门/项目结构说明.md
Normal file
334
docs/01-项目入门/项目结构说明.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# WhaleTown 项目结构说明
|
||||
|
||||
本文档详细说明了 WhaleTown 项目的文件结构设计，采用分层架构模式，确保团队协作高效且代码结构清晰。
|
||||
|
||||
## 🎯 设计理念
|
||||
|
||||
### 核心原则
|
||||
- **分层架构**：框架层、游戏层、界面层明确分离
|
||||
- **团队协作**：策划、美术、开发三类角色各司其职
|
||||
- **高度解耦**：通过事件系统实现组件间通信
|
||||
- **组件复用**：可复用组件统一管理
|
||||
- **标准化**：统一的命名规范和目录结构
|
||||
|
||||
### 团队协作模式
|
||||
- **🎮 开发团队** - 主要工作在 `_Core/`、`scenes/`、`UI/`、`Utils/`
|
||||
- **🎨 美术团队** - 主要工作在 `assets/`
|
||||
- **📋 策划团队** - 主要工作在 `Config/`
|
||||
|
||||
## 🏗️ 项目架构概览
|
||||
|
||||
```
|
||||
WhaleTown/
|
||||
├── 🔧 _Core/ # [框架层] 核心系统和管理器
|
||||
├── 🎬 scenes/ # [游戏层] 游戏场景和组件
|
||||
├── 🎨 UI/ # [界面层] 用户界面
|
||||
├── 🖼️ assets/ # [资源层] 美术资源
|
||||
├── ⚙️ Config/ # [配置层] 游戏配置和数据
|
||||
├── 🛠️ Utils/ # [工具层] 通用工具脚本
|
||||
├── 🧪 tests/ # [测试层] 测试文件
|
||||
├── 🚀 tools/ # [构建层] 构建和部署工具
|
||||
├── 🌐 web_assets/ # [发布层] Web版本资源
|
||||
└── 📚 docs/ # [文档层] 项目文档
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 详细目录结构
|
||||
|
||||
### 1. 🔧 框架层 (_Core/)
|
||||
> **负责团队**: 开发团队
|
||||
> **职责**: 游戏底层框架，全局管理器和核心系统
|
||||
|
||||
```
|
||||
_Core/
|
||||
├── managers/ # 全局管理器
|
||||
│ ├── GameManager.gd # 游戏状态管理
|
||||
│ ├── SceneManager.gd # 场景切换管理
|
||||
│ ├── NetworkManager.gd # 网络通信管理
|
||||
│ └── ResponseHandler.gd # API响应处理
|
||||
└── systems/ # 核心系统
|
||||
└── EventSystem.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_scene.tscn # 主游戏场景
|
||||
│ └── MainScene.gd # 主场景脚本
|
||||
└── Components/ # 可复用组件
|
||||
├── characters/ # 角色组件
|
||||
├── effects/ # 特效组件
|
||||
├── items/ # 物品组件
|
||||
└── ui/ # UI组件
|
||||
```
|
||||
|
||||
**设计原则**:
|
||||
- **场景内聚**: 脚本紧邻场景文件存放
|
||||
- **组件化**: 可复用组件统一管理
|
||||
- **模块化**: 按功能类型分类组织
|
||||
|
||||
### 3. 🎨 界面层 (UI/)
|
||||
> **负责团队**: 开发团队 + 美术团队协作
|
||||
> **职责**: 用户界面和主题管理
|
||||
|
||||
```
|
||||
UI/
|
||||
├── Windows/ # 模态窗口
|
||||
│ ├── LoginWindow.tscn # 登录窗口
|
||||
│ └── AuthScene.gd # 认证场景脚本
|
||||
└── Theme/ # 全局主题
|
||||
├── MainTheme.tres # 主题资源
|
||||
└── Fonts/ # 字体文件
|
||||
└── msyh.ttc # 微软雅黑字体
|
||||
```
|
||||
|
||||
**组织方式**:
|
||||
- **Windows/**: 模态窗口和对话框
|
||||
- **Theme/**: 统一的UI主题和样式
|
||||
- **Fonts/**: 字体资源管理
|
||||
|
||||
### 4. 🖼️ 资源层 (assets/)
|
||||
> **负责团队**: 美术团队
|
||||
> **职责**: 所有美术资源和素材
|
||||
|
||||
```
|
||||
assets/
|
||||
├── sprites/ # 精灵图资源
|
||||
│ ├── characters/ # 角色精灵
|
||||
│ ├── effects/ # 特效精灵
|
||||
│ ├── environment/ # 环境精灵
|
||||
│ └── icon/ # 图标资源
|
||||
├── audio/ # 音频资源
|
||||
│ ├── music/ # 背景音乐
|
||||
│ ├── sounds/ # 音效
|
||||
│ └── voice/ # 语音
|
||||
├── ui/ # UI专用资源
|
||||
│ ├── auth/ # 认证界面资源
|
||||
│ │ ├── bg_auth_scene.png # 认证背景
|
||||
│ │ └── login_frame_smart_transparent.png
|
||||
│ ├── chinese_theme.tres # 中文主题
|
||||
│ └── datawhale_logo.png # 项目Logo
|
||||
├── fonts/ # 字体文件
|
||||
├── materials/ # 材质资源
|
||||
└── shaders/ # 着色器
|
||||
```
|
||||
|
||||
**美术团队工作流程**:
|
||||
1. 按分类将资源放入对应目录
|
||||
2. 遵循命名规范 (snake_case)
|
||||
3. 确保资源格式符合Godot要求
|
||||
4. 配置正确的导入设置 (像素艺术使用最近邻过滤)
|
||||
|
||||
### 5. ⚙️ 配置层 (Config/)
|
||||
> **负责团队**: 策划团队
|
||||
> **职责**: 游戏配置、数据和本地化
|
||||
|
||||
```
|
||||
Config/
|
||||
├── game_config.json # 游戏主配置
|
||||
└── zh_CN.json # 中文本地化
|
||||
```
|
||||
|
||||
**策划团队工作内容**:
|
||||
- **游戏数值配置**: 角色属性、物品数据、关卡参数
|
||||
- **本地化文本**: 多语言文本翻译和管理
|
||||
- **游戏平衡**: 数值平衡和游戏性调整
|
||||
|
||||
**配置文件示例**:
|
||||
```json
|
||||
// game_config.json
|
||||
{
|
||||
"player": {
|
||||
"move_speed": 200.0,
|
||||
"max_health": 100,
|
||||
"jump_height": 400.0
|
||||
},
|
||||
"game": {
|
||||
"target_fps": 60,
|
||||
"auto_save_interval": 300
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 6. 🛠️ 工具层 (Utils/)
|
||||
> **负责团队**: 开发团队
|
||||
> **职责**: 通用工具和辅助脚本
|
||||
|
||||
```
|
||||
Utils/
|
||||
└── StringUtils.gd # 字符串处理工具
|
||||
```
|
||||
|
||||
**特点**:
|
||||
- 纯函数，无依赖
|
||||
- 可被任何层调用
|
||||
- 提供通用功能
|
||||
|
||||
### 7. 🧪 测试层 (tests/)
|
||||
> **负责团队**: 开发团队
|
||||
> **职责**: 质量保证和自动化测试
|
||||
|
||||
```
|
||||
tests/
|
||||
├── api/ # API接口测试
|
||||
├── auth/ # 认证功能测试
|
||||
├── unit/ # 单元测试
|
||||
├── integration/ # 集成测试
|
||||
└── performance/ # 性能测试
|
||||
```
|
||||
|
||||
### 8. 🚀 构建层 (tools/)
|
||||
> **负责团队**: 开发团队/DevOps
|
||||
> **职责**: 构建脚本和部署工具
|
||||
|
||||
```
|
||||
tools/
|
||||
├── build_web.bat # Windows Web构建脚本
|
||||
├── build_web.sh # Linux/macOS Web构建脚本
|
||||
├── serve_web.bat # Windows 本地服务器
|
||||
├── serve_web.sh # Linux/macOS 本地服务器
|
||||
└── README.md # 工具使用说明
|
||||
```
|
||||
|
||||
### 9. 🌐 发布层 (web_assets/)
|
||||
> **负责团队**: 自动生成
|
||||
> **职责**: Web版本发布资源
|
||||
|
||||
```
|
||||
web_assets/
|
||||
├── index.html # Web版本入口
|
||||
├── index.js # Godot Web导出JS
|
||||
├── index.wasm # WebAssembly文件
|
||||
├── index.pck # 游戏资源包
|
||||
└── [其他Web资源] # 图标、配置等
|
||||
```
|
||||
|
||||
### 10. 📚 文档层 (docs/)
|
||||
> **负责团队**: 全体团队
|
||||
> **职责**: 项目文档和开发指南
|
||||
|
||||
```
|
||||
docs/
|
||||
├── 01-项目入门/ # 新人必读
|
||||
├── 02-开发规范/ # 编码标准
|
||||
├── 03-技术实现/ # 开发指导
|
||||
├── 04-高级开发/ # 进阶技巧
|
||||
├── 05-部署运维/ # 发布部署
|
||||
└── 06-功能模块/ # 功能文档
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🤝 团队协作指南
|
||||
|
||||
### 开发团队 🎮
|
||||
**主要工作区域**: `_Core/`, `scenes/`, `UI/`, `Utils/`, `tests/`
|
||||
|
||||
**日常工作流程**:
|
||||
1. 在 `_Core/` 中开发核心系统和管理器
|
||||
2. 在 `scenes/` 中创建游戏场景和组件
|
||||
3. 在 `UI/` 中实现用户界面
|
||||
4. 在 `Utils/` 中编写通用工具
|
||||
5. 在 `tests/` 中编写测试用例
|
||||
|
||||
**协作要点**:
|
||||
- 遵循架构设计原则，使用事件系统通信
|
||||
- 保持代码模块化和可复用性
|
||||
- 及时编写测试和文档
|
||||
|
||||
### 美术团队 🎨
|
||||
**主要工作区域**: `assets/`
|
||||
|
||||
**日常工作流程**:
|
||||
1. 按分类整理美术资源到 `assets/` 对应目录
|
||||
2. 遵循命名规范，使用 snake_case 命名
|
||||
3. 配置正确的Godot导入设置
|
||||
4. 与开发团队协作调整UI资源
|
||||
|
||||
**协作要点**:
|
||||
- 严格按照目录结构组织资源
|
||||
- 确保资源格式和质量符合要求
|
||||
- 及时与开发团队沟通资源需求
|
||||
|
||||
### 策划团队 📋
|
||||
**主要工作区域**: `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)
|
||||
- 及时清理不使用的资源文件
|
||||
|
||||
### 代码组织规范
|
||||
- 脚本文件与场景文件放在同一目录
|
||||
- 使用事件系统实现模块间通信
|
||||
- 保持单一职责原则，避免过度耦合
|
||||
- 及时编写注释和文档
|
||||
|
||||
---
|
||||
|
||||
**记住：良好的项目结构是团队协作成功的基础！**
|
||||
142
docs/01-项目入门/项目设置指南.md
Normal file
142
docs/01-项目入门/项目设置指南.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# 项目设置指南
|
||||
|
||||
本文档指导你完成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` 确认
|
||||
|
||||
## ⚙️ 其他重要设置
|
||||
|
||||
### 主题配置
|
||||
项目使用自定义中文主题：
|
||||
- **路径**: `UI/Theme/MainTheme.tres`
|
||||
- **字体**: 微软雅黑 (`UI/Theme/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. 检查 `UI/Theme/MainTheme.tres` 文件是否存在
|
||||
2. 确认字体文件 `UI/Theme/Fonts/msyh.ttc` 已正确导入
|
||||
3. 在项目设置中重新设置自定义主题
|
||||
|
||||
### 问题4: 网络请求失败
|
||||
**症状**: NetworkManager调用失败
|
||||
|
||||
**解决方案**:
|
||||
1. 检查网络连接
|
||||
2. 确认API地址配置正确
|
||||
3. 查看ResponseHandler是否正常工作
|
||||
|
||||
## 📋 配置检查清单
|
||||
|
||||
完成设置后，请检查以下项目：
|
||||
|
||||
- [ ] 所有AutoLoad单例配置正确
|
||||
- [ ] 主场景可以正常启动
|
||||
- [ ] 控制台没有错误信息
|
||||
- [ ] 自定义主题加载正常
|
||||
- [ ] 中文字体显示正确
|
||||
- [ ] 网络管理器可以正常调用
|
||||
- [ ] 事件系统工作正常
|
||||
- [ ] 场景管理器可以切换场景
|
||||
|
||||
## 🚀 下一步
|
||||
|
||||
配置完成后，建议继续阅读：
|
||||
- [输入映射配置](输入映射配置.md) - 设置游戏控制
|
||||
- [命名规范](../02-开发规范/命名规范.md) - 学习编码规范
|
||||
- [架构与通信规范](../02-开发规范/架构与通信规范.md) - 理解项目架构
|
||||
|
||||
---
|
||||
|
||||
**💡 提示**: 如果遇到问题，可以参考 [测试指南](../03-技术实现/测试指南.md) 进行更详细的功能验证。
|
||||
105
docs/02-开发规范/README.md
Normal file
105
docs/02-开发规范/README.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# 📋 开发规范
|
||||
|
||||
> **适用人群**: 所有开发者
|
||||
> **使用时机**: 编码过程中，代码审查时
|
||||
|
||||
这个目录包含了项目的所有编码标准和开发规范，确保团队代码风格一致，架构设计统一。
|
||||
|
||||
## 📚 规范文档
|
||||
|
||||
### 基础规范 📝
|
||||
**[命名规范.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提交改进方案
|
||||
|
||||
---
|
||||
|
||||
**记住：规范不是束缚，而是团队协作的基础！**
|
||||
406
docs/02-开发规范/开发哲学与最佳实践.md
Normal file
406
docs/02-开发规范/开发哲学与最佳实践.md
Normal file
@@ -0,0 +1,406 @@
|
||||
# 开发哲学与最佳实践
|
||||
|
||||
本文档阐述了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: 这里的逻辑比较复杂，需要详细注释
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**记住：优秀的代码不仅能工作，更要易于理解、维护和扩展。追求代码质量是每个开发者的责任！**
|
||||
280
docs/02-开发规范/架构与通信规范.md
Normal file
280
docs/02-开发规范/架构与通信规范.md
Normal file
@@ -0,0 +1,280 @@
|
||||
# 架构与通信规范
|
||||
|
||||
本文档定义了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)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**记住：良好的架构设计是项目成功的基石！遵循这些通信规范可以确保代码的可维护性和扩展性。**
|
||||
120
docs/03-技术实现/README.md
Normal file
120
docs/03-技术实现/README.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# 🔧 技术实现
|
||||
|
||||
> **适用人群**: 正在开发功能的程序员
|
||||
> **使用时机**: 具体功能开发时
|
||||
|
||||
这个目录包含了具体的技术实现指导，帮助开发者快速实现各种游戏功能和系统集成。
|
||||
|
||||
## 📋 实现指南
|
||||
|
||||
### 核心实现 🎮
|
||||
**[实现细节规范.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变量进行配置
|
||||
- 充分利用事件系统解耦组件
|
||||
|
||||
### 质量保证
|
||||
- 每个功能都要编写对应测试
|
||||
- 定期进行代码审查
|
||||
- 关注性能指标和内存使用
|
||||
- 保持代码简洁和可读性
|
||||
|
||||
---
|
||||
|
||||
**记住：好的实现不仅要功能正确，更要易于维护和扩展！**
|
||||
388
docs/03-技术实现/实现细节规范.md
Normal file
388
docs/03-技术实现/实现细节规范.md
Normal file
@@ -0,0 +1,388 @@
|
||||
# 实现细节规范
|
||||
|
||||
本文档详细说明了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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**记住：遵循这些实现细节规范可以确保游戏对象的一致性和性能！**
|
||||
@@ -13,7 +13,7 @@ NetworkManager 是一个统一的网络请求管理器，提供了简洁的API
|
||||
1. 打开 `Project` → `Project Settings`
|
||||
2. 切换到 `AutoLoad` 标签
|
||||
3. 添加新的AutoLoad：
|
||||
- **Path**: `res://core/managers/NetworkManager.gd`
|
||||
- **Path**: `res://_Core/managers/NetworkManager.gd`
|
||||
- **Name**: `NetworkManager`
|
||||
- **Singleton**: ✅ 勾选
|
||||
|
||||
@@ -24,7 +24,7 @@ NetworkManager 是一个统一的网络请求管理器，提供了简洁的API
|
||||
```ini
|
||||
[autoload]
|
||||
|
||||
NetworkManager="*res://core/managers/NetworkManager.gd"
|
||||
NetworkManager="*res://_Core/managers/NetworkManager.gd"
|
||||
```
|
||||
|
||||
### 3. 验证设置
|
||||
@@ -22,29 +22,29 @@
|
||||
### 标准目录结构
|
||||
```
|
||||
scenes/
|
||||
├── main_scene.tscn # 主场景
|
||||
├── auth_scene.tscn # 认证场景
|
||||
├── game_scene.tscn # 游戏场景
|
||||
├── settings_scene.tscn # 设置场景
|
||||
└── prefabs/ # 预制体组件
|
||||
├── ui/ # UI组件
|
||||
│ ├── button.tscn
|
||||
│ ├── dialog.tscn
|
||||
│ └── menu.tscn
|
||||
├── characters/ # 角色组件
|
||||
│ ├── player.tscn
|
||||
│ └── npc.tscn
|
||||
├── effects/ # 特效组件
|
||||
│ ├── particle_effect.tscn
|
||||
│ └── animation_effect.tscn
|
||||
└── items/ # 物品组件
|
||||
├── collectible.tscn
|
||||
└── interactive.tscn
|
||||
├── Maps/ # 地图场景
|
||||
│ ├── main_scene.tscn # 主场景
|
||||
│ └── game_scene.tscn # 游戏场景
|
||||
├── Components/ # 组件预制体
|
||||
│ ├── ui/ # UI组件
|
||||
│ │ ├── button.tscn
|
||||
│ │ ├── dialog.tscn
|
||||
│ │ └── menu.tscn
|
||||
│ ├── characters/ # 角色组件
|
||||
│ │ ├── player.tscn
|
||||
│ │ └── npc.tscn
|
||||
│ ├── effects/ # 特效组件
|
||||
│ │ ├── particle_effect.tscn
|
||||
│ │ └── animation_effect.tscn
|
||||
│ └── items/ # 物品组件
|
||||
│ ├── collectible.tscn
|
||||
│ └── interactive.tscn
|
||||
└── auth_scene.tscn # 认证场景
|
||||
```
|
||||
|
||||
### 场景命名规范
|
||||
- **主场景**: `scene_name.tscn` (snake_case)
|
||||
- **预制体**: `component_name.tscn` (snake_case)
|
||||
- **主场景**: `SceneName.tscn` (PascalCase)
|
||||
- **组件预制体**: `ComponentName.tscn` (PascalCase)
|
||||
- **脚本文件**: `SceneName.gd` (PascalCase)
|
||||
- **节点名称**: `NodeName` (PascalCase) 或 `nodeName` (camelCase)
|
||||
|
||||
@@ -149,7 +149,7 @@ func initialize_scene():
|
||||
func load_scene_data():
|
||||
"""加载场景数据"""
|
||||
# 从配置文件或网络加载场景数据
|
||||
var data_path = "res://data/scenes/%s.json" % SCENE_NAME.to_lower()
|
||||
var data_path = ProjectPaths.get_scene_data_path(SCENE_NAME)
|
||||
if FileAccess.file_exists(data_path):
|
||||
var file = FileAccess.open(data_path, FileAccess.READ)
|
||||
if file:
|
||||
@@ -87,9 +87,9 @@ func return_object(obj: Node, type: String):
|
||||
func _create_new_object(type: String) -> Node:
|
||||
match type:
|
||||
"Bullet":
|
||||
return preload("res://prefabs/Bullet.tscn").instantiate()
|
||||
return preload(ProjectPaths.get_component_path("effects", "Bullet")).instantiate()
|
||||
"Enemy":
|
||||
return preload("res://prefabs/Enemy.tscn").instantiate()
|
||||
return preload(ProjectPaths.get_component_path("characters", "Enemy")).instantiate()
|
||||
_:
|
||||
return null
|
||||
```
|
||||
@@ -129,7 +129,7 @@ func get_module_info() -> Dictionary:
|
||||
# 私有方法
|
||||
func _load_config() -> bool:
|
||||
"""加载模块配置"""
|
||||
var config_path = "res://module/%s/data/module_config.json" % MODULE_NAME
|
||||
var config_path = ProjectPaths.get_module_config_path(MODULE_NAME)
|
||||
if not FileAccess.file_exists(config_path):
|
||||
print("警告: 模块配置文件不存在: ", config_path)
|
||||
return true # 使用默认配置
|
||||
@@ -270,7 +270,7 @@ func update_data(data_type: String, new_data: Dictionary):
|
||||
|
||||
```gdscript
|
||||
# tests/test_your_module.gd
|
||||
extends "res://addons/gut/test.gd"
|
||||
extends GutTest
|
||||
|
||||
var module: YourModule
|
||||
|
||||
@@ -66,13 +66,13 @@ Dedicated Server: ✗ 禁用
|
||||
Variant: release
|
||||
Vram Texture Compression: ✓ 启用
|
||||
Export Type: Regular
|
||||
Custom HTML Shell: res://assets/web/custom_shell.html
|
||||
Custom HTML Shell: res://web_assets/custom_shell.html
|
||||
Head Include: (留空，已在自定义模板中配置)
|
||||
```
|
||||
|
||||
#### 高级选项
|
||||
```
|
||||
Custom HTML Shell: res://assets/web/custom_shell.html
|
||||
Custom HTML Shell: res://web_assets/custom_shell.html
|
||||
Progressive Web App: ✓ 启用（可选）
|
||||
Icon 144x144: res://icon.svg
|
||||
Icon 180x180: res://icon.svg
|
||||
65
docs/CHANGELOG.md
Normal file
65
docs/CHANGELOG.md
Normal file
@@ -0,0 +1,65 @@
|
||||
# 文档更新日志
|
||||
|
||||
本文档记录了WhaleTown项目文档的重要更新和修改。
|
||||
|
||||
## 版本 1.1.0 (2025-12-31)
|
||||
|
||||
### 🆕 新增内容
|
||||
- **新增**: `_Core/EventNames.gd` - 统一管理所有事件名称常量
|
||||
- **新增**: `_Core/ProjectPaths.gd` - 统一管理项目路径配置
|
||||
- **新增**: 输入映射配置到 `project.godot`
|
||||
- **新增**: 文档更新日志 `docs/CHANGELOG.md`
|
||||
|
||||
### 🔧 修复问题
|
||||
- **修复**: 架构与通信规范中AutoLoad单例数量描述（从3个更新为5个）
|
||||
- **修复**: 网络管理器设置文档中的路径错误（`core/` → `_Core/`）
|
||||
- **修复**: Web部署指南中的资源路径（`assets/web/` → `web_assets/`）
|
||||
- **修复**: 场景设计规范中的目录结构（`prefabs/` → `Components/`）
|
||||
- **修复**: 性能优化指南中的预制体路径
|
||||
- **修复**: 模块开发指南中的测试基类路径（使用 `GutTest` 而非完整路径）
|
||||
|
||||
### 📝 内容优化
|
||||
- **优化**: 场景命名规范，与实际项目结构保持一致
|
||||
- **优化**: 所有文档中的路径引用，使用 `ProjectPaths` 统一管理
|
||||
- **优化**: 代码示例的准确性和可用性
|
||||
|
||||
### 🎯 质量提升
|
||||
- **提升**: 文档与实际代码的匹配度
|
||||
- **提升**: 路径配置的一致性和可维护性
|
||||
- **提升**: 开发者体验和文档可用性
|
||||
|
||||
## 版本 1.0.0 (2025-12-24)
|
||||
|
||||
### 📚 初始文档结构
|
||||
- **01-项目入门**: 项目介绍、结构说明、设置指南
|
||||
- **02-开发规范**: 命名规范、注释规范、Git提交规范、架构规范、开发哲学
|
||||
- **03-技术实现**: 实现细节、API文档、网络管理器、测试指南
|
||||
- **04-高级开发**: 场景设计、模块开发、性能优化
|
||||
- **05-部署运维**: Web部署指南
|
||||
- **06-功能模块**: 认证模块相关文档
|
||||
|
||||
### 🏗️ 核心特性
|
||||
- 完整的开发规范体系
|
||||
- 详细的技术实现指导
|
||||
- 全面的测试和部署流程
|
||||
- 模块化的功能开发指南
|
||||
|
||||
---
|
||||
|
||||
## 维护说明
|
||||
|
||||
### 文档更新原则
|
||||
1. **同步更新**: 代码变更时同步更新相关文档
|
||||
2. **版本记录**: 重要更新需要在此日志中记录
|
||||
3. **向后兼容**: 尽量保持API和配置的向后兼容性
|
||||
4. **质量保证**: 确保文档内容的准确性和可用性
|
||||
|
||||
### 贡献指南
|
||||
- 发现文档问题请及时反馈
|
||||
- 提交文档更新时请更新此日志
|
||||
- 重大变更需要团队讨论确认
|
||||
|
||||
### 相关链接
|
||||
- [项目结构说明](01-项目入门/项目结构说明.md)
|
||||
- [开发规范总览](02-开发规范/README.md)
|
||||
- [技术实现指南](03-技术实现/README.md)
|
||||
122
docs/CONTRIBUTORS.md
Normal file
122
docs/CONTRIBUTORS.md
Normal file
@@ -0,0 +1,122 @@
|
||||
# 🤝 项目贡献者
|
||||
|
||||
感谢所有为WhaleTown项目做出贡献的开发者！
|
||||
|
||||
## 🏆 核心贡献者
|
||||
|
||||
### 主要开发者
|
||||
|
||||
#### 王浩
|
||||
- **贡献数量**: 3+ commits
|
||||
- **主要贡献**:
|
||||
- 🏗️ 项目架构分层结构重构
|
||||
- 📚 AI开发规范文档制定
|
||||
- 📖 项目开发规范文档完善
|
||||
|
||||
#### moyin
|
||||
- **贡献数量**: 35+ commits
|
||||
- **主要贡献**:
|
||||
- 🔧 项目功能开发和实现
|
||||
- 📝 文档内容编写和维护
|
||||
- 🧪 测试用例开发和验证
|
||||
- 🌐 网络系统和部署配置
|
||||
|
||||
## 📊 贡献统计
|
||||
|
||||
### 按贡献类型
|
||||
|
||||
| 贡献类型 | 主要贡献者 | 说明 |
|
||||
|----------|------------|------|
|
||||
| **架构设计** | 王浩, moyin | 分层结构重构，模块化架构 |
|
||||
| **开发规范** | 王浩 | AI开发规范、编码标准 |
|
||||
| **文档建设** | moyin, 王浩 | 18个完整文档，覆盖全开发流程 |
|
||||
| **网络系统** | moyin | NetworkManager、API集成 |
|
||||
| **测试框架** | moyin | API测试、UI测试、性能测试 |
|
||||
| **认证系统** | moyin | 用户认证流程实现 |
|
||||
| **部署系统** | moyin | Web部署、自动化脚本 |
|
||||
|
||||
### 按时间线
|
||||
|
||||
#### 2024年12月
|
||||
- **架构重构**: 王浩 实施分层架构重构
|
||||
- **规范制定**: 王浩 制定AI开发规范
|
||||
- **项目开发**: moyin 完成主要功能开发
|
||||
- **文档建设**: moyin, 王浩 建设文档系统
|
||||
- **测试集成**: moyin 完成API集成和测试
|
||||
|
||||
## 🌟 贡献亮点
|
||||
|
||||
### 🏗️ 架构设计
|
||||
- **分层结构**: 清晰的代码组织和职责分离
|
||||
- **模块化架构**: 高度解耦的组件系统
|
||||
- **事件驱动**: 基于EventSystem的通信机制
|
||||
|
||||
### 📚 文档建设
|
||||
- **企业级文档**: 18个完整文档，100%覆盖
|
||||
- **分类组织**: 按开发阶段精心分类
|
||||
- **实用导向**: 大量可直接使用的代码模板
|
||||
|
||||
### 🎯 开发规范
|
||||
- **AI开发规范**: AI辅助开发的最佳实践
|
||||
- **编码标准**: 统一的命名规范和代码风格
|
||||
- **质量保证**: 完善的代码审查流程
|
||||
|
||||
### 🧪 测试体系
|
||||
- **多层测试**: API、UI、单元、集成测试
|
||||
- **自动化**: Python测试脚本和Godot测试场景
|
||||
- **完整覆盖**: 17个API接口全覆盖
|
||||
|
||||
### 🌐 部署系统
|
||||
- **一键部署**: 自动化Web部署脚本
|
||||
- **跨平台**: 支持Windows、Linux、macOS
|
||||
- **配置完善**: 详细的服务器配置指南
|
||||
|
||||
## 🎯 特别感谢
|
||||
|
||||
### 技术贡献
|
||||
- **王浩**: 负责架构重构和开发规范制定
|
||||
- **moyin**: 负责主要功能开发和文档编写
|
||||
|
||||
### 架构贡献
|
||||
- **分层结构**: 提升了项目的代码组织和可维护性
|
||||
- **模块化设计**: 为项目扩展奠定了良好基础
|
||||
- **开发规范**: 统一了团队的开发标准
|
||||
|
||||
## 🚀 如何成为贡献者
|
||||
|
||||
### 贡献方式
|
||||
1. **🐛 Bug修复** - 发现并修复问题
|
||||
2. **✨ 新功能** - 添加有价值的功能
|
||||
3. **📚 文档改进** - 完善项目文档
|
||||
4. **🧪 测试用例** - 提高代码覆盖率
|
||||
5. **🎨 UI/UX改进** - 提升用户体验
|
||||
6. **⚡ 性能优化** - 优化游戏性能
|
||||
|
||||
### 贡献流程
|
||||
1. Fork项目到你的账户
|
||||
2. 创建功能分支：`git checkout -b feature/your-feature`
|
||||
3. 遵循项目规范开发
|
||||
4. 添加测试用例
|
||||
5. 提交代码：`git commit -m "feat：添加新功能"`
|
||||
6. 创建Pull Request
|
||||
|
||||
### 规范要求
|
||||
- 遵循[命名规范](02-开发规范/命名规范.md)
|
||||
- 遵循[Git提交规范](02-开发规范/Git提交规范.md)
|
||||
- 遵循[代码注释规范](02-开发规范/代码注释规范.md)
|
||||
- 添加相应的测试用例
|
||||
- 更新相关文档
|
||||
|
||||
## 📞 联系方式
|
||||
|
||||
如果你想参与贡献或有任何问题：
|
||||
|
||||
- **项目地址**: [Gitea Repository](https://gitea.xinghangee.icu/datawhale/whale-town)
|
||||
- **问题反馈**: [Issues](https://gitea.xinghangee.icu/datawhale/whale-town/issues)
|
||||
- **功能建议**: [Discussions](https://gitea.xinghangee.icu/datawhale/whale-town/discussions)
|
||||
|
||||
---
|
||||
|
||||
**感谢所有贡献者的辛勤付出！每个人的贡献都让WhaleTown项目变得更好。** 🙏
|
||||
|
||||
*最后更新: 2025-12-31*
|
||||
310
docs/README.md
Normal file
310
docs/README.md
Normal file
@@ -0,0 +1,310 @@
|
||||
# 📚 WhaleTown 项目文档中心
|
||||
|
||||
欢迎来到WhaleTown项目文档中心！这是一个完整的企业级文档系统，按开发阶段精心组织，帮助你快速找到所需的技术指导。
|
||||
|
||||
## 🎯 文档特色
|
||||
|
||||
- **📋 完整覆盖**: 从项目入门到部署运维的全生命周期
|
||||
- **🎨 结构清晰**: 按开发阶段和角色需求分类组织
|
||||
- **💻 实用导向**: 提供大量可直接使用的代码模板和配置示例
|
||||
- **🔄 持续更新**: 与项目代码保持同步，确保文档准确性
|
||||
- **🧪 测试完备**: 包含详细的测试指南和用例
|
||||
|
||||
## 🗂️ 文档结构
|
||||
|
||||
```
|
||||
docs/
|
||||
├── 📖 README.md # 本导航文档
|
||||
├── 📋 CHANGELOG.md # 文档更新日志
|
||||
├── 📁 01-项目入门/ # 新人必读，项目基础
|
||||
├── 📁 02-开发规范/ # 编码标准和规范
|
||||
├── 📁 03-技术实现/ # 具体开发指导
|
||||
├── 📁 04-高级开发/ # 进阶开发技巧
|
||||
├── 📁 05-部署运维/ # 发布和部署
|
||||
└── 📁 06-功能模块/ # 特定功能文档
|
||||
```
|
||||
|
||||
## 📊 文档质量等级
|
||||
|
||||
| 等级 | 说明 | 标识 |
|
||||
|------|------|------|
|
||||
| A级 | 企业级标准，内容完整准确 | ⭐⭐⭐⭐⭐ |
|
||||
| B级 | 内容详实，偶有更新需求 | ⭐⭐⭐⭐ |
|
||||
| C级 | 基础完备，持续完善中 | ⭐⭐⭐ |
|
||||
|
||||
**当前整体质量**: **A级** ✨
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速开始指南
|
||||
|
||||
### 👋 我是新人，从哪里开始？
|
||||
**推荐阅读顺序：**
|
||||
1. [项目入门总览](01-项目入门/README.md) - 快速了解项目
|
||||
2. [项目结构说明](01-项目入门/项目结构说明.md) - 深入了解项目架构
|
||||
3. [项目设置指南](01-项目入门/项目设置指南.md) - 配置开发环境
|
||||
4. [命名规范](02-开发规范/命名规范.md) - 学习编码规范
|
||||
|
||||
### 💻 我要开始编码了
|
||||
**必读文档：**
|
||||
- [架构与通信规范](02-开发规范/架构与通信规范.md) - 组件通信方式 ⭐⭐⭐⭐⭐
|
||||
- [实现细节规范](03-技术实现/实现细节规范.md) - 具体实现要求 ⭐⭐⭐⭐⭐
|
||||
- [开发哲学与最佳实践](02-开发规范/开发哲学与最佳实践.md) - 代码质量标准 ⭐⭐⭐⭐
|
||||
|
||||
### 🔧 我需要集成API
|
||||
**相关文档：**
|
||||
- [API接口文档](03-技术实现/API接口文档.md) - 完整的接口说明 ⭐⭐⭐⭐⭐
|
||||
- [网络管理器设置](03-技术实现/网络管理器设置.md) - 网络配置指南 ⭐⭐⭐⭐
|
||||
- [测试指南](03-技术实现/测试指南.md) - API测试方法 ⭐⭐⭐⭐
|
||||
|
||||
### 🚀 我要发布项目
|
||||
**部署文档：**
|
||||
- [Web部署指南](05-部署运维/Web部署指南.md) - 完整的Web版本发布流程 ⭐⭐⭐⭐
|
||||
|
||||
### 🔍 我需要调试和优化
|
||||
**高级文档：**
|
||||
- [性能优化指南](04-高级开发/性能优化指南.md) - 全面的性能优化策略 ⭐⭐⭐⭐⭐
|
||||
- [场景设计规范](04-高级开发/场景设计规范.md) - 场景架构最佳实践 ⭐⭐⭐⭐
|
||||
|
||||
---
|
||||
|
||||
## 📁 详细目录
|
||||
|
||||
### 01-项目入门 📖
|
||||
> **适用人群**: 新加入项目的开发者
|
||||
> **使用时机**: 项目开始前，环境搭建阶段
|
||||
> **质量等级**: A级 ⭐⭐⭐⭐⭐
|
||||
|
||||
| 文档 | 用途 | 重要程度 | 更新状态 |
|
||||
|------|------|----------|----------|
|
||||
| [README.md](01-项目入门/README.md) | 项目入门总览和快速导航 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [项目结构说明.md](01-项目入门/项目结构说明.md) | 了解项目整体架构和目录组织 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [项目设置指南.md](01-项目入门/项目设置指南.md) | Godot项目配置和AutoLoad设置 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
|
||||
### 02-开发规范 📋
|
||||
> **适用人群**: 所有开发者
|
||||
> **使用时机**: 编码过程中，代码审查时
|
||||
> **质量等级**: A级 ⭐⭐⭐⭐⭐
|
||||
|
||||
| 文档 | 用途 | 重要程度 | 更新状态 |
|
||||
|------|------|----------|----------|
|
||||
| [命名规范.md](02-开发规范/命名规范.md) | 统一的命名标准，包含完整示例 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [代码注释规范.md](02-开发规范/代码注释规范.md) | 注释格式和AI辅助注释指南 | ⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [Git提交规范.md](02-开发规范/Git提交规范.md) | 版本控制规范和最佳实践 | ⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [架构与通信规范.md](02-开发规范/架构与通信规范.md) | 事件系统和组件通信标准 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [开发哲学与最佳实践.md](02-开发规范/开发哲学与最佳实践.md) | 代码质量和开发理念 | ⭐⭐⭐⭐ | ✅ 最新 |
|
||||
|
||||
### 03-技术实现 🔧
|
||||
> **适用人群**: 正在开发功能的程序员
|
||||
> **使用时机**: 具体功能开发时
|
||||
> **质量等级**: A级 ⭐⭐⭐⭐⭐
|
||||
|
||||
| 文档 | 用途 | 重要程度 | 更新状态 |
|
||||
|------|------|----------|----------|
|
||||
| [实现细节规范.md](03-技术实现/实现细节规范.md) | 游戏对象具体实现要求和模板 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [API接口文档.md](03-技术实现/API接口文档.md) | 完整的后端接口说明和测试用例 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [网络管理器设置.md](03-技术实现/网络管理器设置.md) | 网络通信配置和使用指南 | ⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [测试指南.md](03-技术实现/测试指南.md) | 多种测试方法和工具使用 | ⭐⭐⭐⭐ | ✅ 最新 |
|
||||
|
||||
### 04-高级开发 🚀
|
||||
> **适用人群**: 有经验的开发者，架构师
|
||||
> **使用时机**: 复杂功能开发，性能优化时
|
||||
> **质量等级**: A级 ⭐⭐⭐⭐⭐
|
||||
|
||||
| 文档 | 用途 | 重要程度 | 更新状态 |
|
||||
|------|------|----------|----------|
|
||||
| [场景设计规范.md](04-高级开发/场景设计规范.md) | 场景架构和设计标准，包含完整模板 | ⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [模块开发指南.md](04-高级开发/模块开发指南.md) | 创建可复用模块的完整流程 | ⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| [性能优化指南.md](04-高级开发/性能优化指南.md) | 全面的游戏性能优化策略 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
|
||||
### 05-部署运维 🌐
|
||||
> **适用人群**: DevOps工程师，项目负责人
|
||||
> **使用时机**: 项目发布，部署配置时
|
||||
> **质量等级**: A级 ⭐⭐⭐⭐⭐
|
||||
|
||||
| 文档 | 用途 | 重要程度 | 更新状态 |
|
||||
|------|------|----------|----------|
|
||||
| [Web部署指南.md](05-部署运维/Web部署指南.md) | 完整的Web版本导出和部署流程 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
|
||||
### 06-功能模块 🎮
|
||||
> **适用人群**: 开发特定功能的程序员
|
||||
> **使用时机**: 开发对应功能时
|
||||
> **质量等级**: A级 ⭐⭐⭐⭐⭐
|
||||
|
||||
| 目录/文档 | 用途 | 重要程度 | 更新状态 |
|
||||
|-----------|------|----------|----------|
|
||||
| [auth/](06-功能模块/auth/) | 用户认证系统完整文档 | ⭐⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| └── [表单验证规范.md](06-功能模块/auth/表单验证规范.md) | 详细的表单验证规则和UI规范 | ⭐⭐⭐⭐ | ✅ 最新 |
|
||||
| └── [认证测试指南.md](06-功能模块/auth/认证测试指南.md) | 完整的认证功能测试用例 | ⭐⭐⭐⭐ | ✅ 最新 |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 按角色推荐
|
||||
|
||||
### 👨💻 前端开发者
|
||||
**学习路径**: 01-项目入门 → 02-开发规范 → 03-技术实现 → 06-功能模块
|
||||
**核心文档**:
|
||||
- [架构与通信规范](02-开发规范/架构与通信规范.md) - 掌握事件系统 ⭐⭐⭐⭐⭐
|
||||
- [实现细节规范](03-技术实现/实现细节规范.md) - 游戏对象实现 ⭐⭐⭐⭐⭐
|
||||
- [API接口文档](03-技术实现/API接口文档.md) - 后端接口调用 ⭐⭐⭐⭐⭐
|
||||
|
||||
### 🏗️ 架构师/技术负责人
|
||||
**学习路径**: 01-项目入门 → 02-开发规范 → 04-高级开发 → 05-部署运维
|
||||
**核心文档**:
|
||||
- [开发哲学与最佳实践](02-开发规范/开发哲学与最佳实践.md) - 代码质量标准 ⭐⭐⭐⭐⭐
|
||||
- [场景设计规范](04-高级开发/场景设计规范.md) - 架构设计模式 ⭐⭐⭐⭐⭐
|
||||
- [性能优化指南](04-高级开发/性能优化指南.md) - 性能优化策略 ⭐⭐⭐⭐⭐
|
||||
|
||||
### 🧪 测试工程师
|
||||
**学习路径**: 01-项目入门 → 03-技术实现/测试指南 → 06-功能模块
|
||||
**核心文档**:
|
||||
- [测试指南](03-技术实现/测试指南.md) - 测试方法和工具 ⭐⭐⭐⭐⭐
|
||||
- [认证测试指南](06-功能模块/auth/认证测试指南.md) - 功能测试用例 ⭐⭐⭐⭐
|
||||
|
||||
### 🚀 DevOps工程师
|
||||
**学习路径**: 01-项目入门 → 05-部署运维 → 03-技术实现
|
||||
**核心文档**:
|
||||
- [Web部署指南](05-部署运维/Web部署指南.md) - 完整部署流程 ⭐⭐⭐⭐⭐
|
||||
- [项目设置指南](01-项目入门/项目设置指南.md) - 环境配置 ⭐⭐⭐⭐
|
||||
|
||||
### 🎮 游戏设计师
|
||||
**学习路径**: 01-项目入门 → 04-高级开发/场景设计规范 → 06-功能模块
|
||||
**核心文档**:
|
||||
- [场景设计规范](04-高级开发/场景设计规范.md) - 场景设计标准 ⭐⭐⭐⭐⭐
|
||||
|
||||
---
|
||||
|
||||
## 🔍 快速查找
|
||||
|
||||
### 按问题类型查找
|
||||
|
||||
**🤔 "我不知道项目是怎么组织的"**
|
||||
→ [项目结构说明.md](01-项目入门/项目结构说明.md) - 完整的项目架构说明
|
||||
|
||||
**🤔 "我不知道怎么配置开发环境"**
|
||||
→ [项目设置指南.md](01-项目入门/项目设置指南.md) - 详细的环境配置步骤
|
||||
|
||||
**🤔 "我不知道怎么命名变量/函数"**
|
||||
→ [命名规范.md](02-开发规范/命名规范.md) - 统一的命名标准和示例
|
||||
|
||||
**🤔 "我不知道怎么让组件之间通信"**
|
||||
→ [架构与通信规范.md](02-开发规范/架构与通信规范.md) - 事件系统使用指南
|
||||
|
||||
**🤔 "我不知道怎么实现玩家/NPC"**
|
||||
→ [实现细节规范.md](03-技术实现/实现细节规范.md) - 游戏对象实现模板
|
||||
|
||||
**🤔 "我不知道怎么调用API"**
|
||||
→ [API接口文档.md](03-技术实现/API接口文档.md) - 完整的接口说明和示例
|
||||
|
||||
**🤔 "我不知道怎么测试功能"**
|
||||
→ [测试指南.md](03-技术实现/测试指南.md) - 多种测试方法和工具
|
||||
|
||||
**🤔 "我不知道怎么优化性能"**
|
||||
→ [性能优化指南.md](04-高级开发/性能优化指南.md) - 全面的优化策略
|
||||
|
||||
**🤔 "我不知道怎么发布项目"**
|
||||
→ [Web部署指南.md](05-部署运维/Web部署指南.md) - 完整的部署流程
|
||||
|
||||
**🤔 "我不知道怎么开发模块"**
|
||||
→ [模块开发指南.md](04-高级开发/模块开发指南.md) - 模块化开发方法
|
||||
|
||||
### 按开发阶段查找
|
||||
|
||||
| 阶段 | 主要文档 | 说明 |
|
||||
|------|----------|------|
|
||||
| **项目启动** | 01-项目入门 | 环境搭建，项目了解 |
|
||||
| **需求分析** | 02-开发规范 | 规范制定，架构设计 |
|
||||
| **功能开发** | 03-技术实现 | 具体实现，API集成 |
|
||||
| **质量保证** | 03-技术实现/测试指南 | 测试验证，质量控制 |
|
||||
| **性能优化** | 04-高级开发 | 性能调优，架构优化 |
|
||||
| **项目发布** | 05-部署运维 | 部署配置，运维监控 |
|
||||
|
||||
## 🛠️ 核心工具和配置
|
||||
|
||||
### 已集成的核心组件
|
||||
- **EventSystem** - 全局事件通信系统 ([EventNames.gd](_Core/EventNames.gd))
|
||||
- **ProjectPaths** - 统一路径管理 ([ProjectPaths.gd](_Core/ProjectPaths.gd))
|
||||
- **NetworkManager** - 网络请求管理器
|
||||
- **ResponseHandler** - 统一响应处理器
|
||||
- **StringUtils** - 字符串工具类
|
||||
|
||||
### 配置文件
|
||||
- **project.godot** - 项目配置，包含输入映射和AutoLoad设置
|
||||
- **Config/game_config.json** - 游戏配置文件
|
||||
- **web_assets/** - Web部署资源
|
||||
|
||||
## 📈 文档统计
|
||||
|
||||
| 类别 | 文档数量 | 完成度 | 质量等级 |
|
||||
|------|----------|--------|----------|
|
||||
| 项目入门 | 3 | 100% | A级 ⭐⭐⭐⭐⭐ |
|
||||
| 开发规范 | 5 | 100% | A级 ⭐⭐⭐⭐⭐ |
|
||||
| 技术实现 | 4 | 100% | A级 ⭐⭐⭐⭐⭐ |
|
||||
| 高级开发 | 3 | 100% | A级 ⭐⭐⭐⭐⭐ |
|
||||
| 部署运维 | 1 | 100% | A级 ⭐⭐⭐⭐⭐ |
|
||||
| 功能模块 | 2 | 100% | A级 ⭐⭐⭐⭐⭐ |
|
||||
| **总计** | **18** | **100%** | **A级** ⭐⭐⭐⭐⭐ |
|
||||
|
||||
---
|
||||
|
||||
## 📝 文档维护
|
||||
|
||||
### 更新机制
|
||||
- **自动同步**: 代码变更时自动检查相关文档
|
||||
- **版本控制**: 重要更新记录在 [CHANGELOG.md](CHANGELOG.md)
|
||||
- **质量保证**: 定期校验文档与代码的一致性
|
||||
- **持续改进**: 根据用户反馈持续优化文档质量
|
||||
|
||||
### 更新频率
|
||||
| 文档类别 | 更新触发条件 | 更新频率 |
|
||||
|----------|--------------|----------|
|
||||
| **01-项目入门** | 项目架构变更 | 按需更新 |
|
||||
| **02-开发规范** | 团队规范调整 | 季度评审 |
|
||||
| **03-技术实现** | API变更/新功能 | 实时更新 |
|
||||
| **04-高级开发** | 最佳实践演进 | 月度评审 |
|
||||
| **05-部署运维** | 部署流程变更 | 按需更新 |
|
||||
| **06-功能模块** | 功能开发完成 | 实时更新 |
|
||||
|
||||
### 贡献指南
|
||||
如果你发现文档有问题或需要补充：
|
||||
|
||||
1. **报告问题**: 创建Issue描述具体问题
|
||||
2. **提交改进**: 提交PR修改文档内容
|
||||
3. **遵循规范**: 按照[Git提交规范](02-开发规范/Git提交规范.md)提交
|
||||
4. **更新日志**: 重要变更需更新[CHANGELOG.md](CHANGELOG.md)
|
||||
|
||||
### 文档质量标准
|
||||
- **准确性**: 与实际代码保持100%一致
|
||||
- **完整性**: 覆盖功能的完整生命周期
|
||||
- **实用性**: 提供可直接使用的代码示例
|
||||
- **可读性**: 结构清晰，表达简洁明了
|
||||
|
||||
## 🎉 特别感谢
|
||||
|
||||
感谢所有为WhaleTown项目文档贡献的开发者！
|
||||
|
||||
### 文档贡献者
|
||||
- 项目架构设计和文档框架搭建
|
||||
- 开发规范制定和最佳实践总结
|
||||
- 技术实现指南和代码模板编写
|
||||
- 测试用例设计和质量保证
|
||||
|
||||
### 持续改进
|
||||
我们致力于打造最好用的游戏开发文档系统，欢迎提供反馈和建议！
|
||||
|
||||
---
|
||||
|
||||
## 📞 获取帮助
|
||||
|
||||
- **文档问题**: 查看 [CHANGELOG.md](CHANGELOG.md) 了解最新更新
|
||||
- **技术问题**: 参考对应的技术实现文档
|
||||
- **最佳实践**: 查阅开发规范和高级开发指南
|
||||
- **部署问题**: 参考部署运维文档
|
||||
|
||||
**💡 提示**: 建议将本导航页面加入书签，方便随时查阅！
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: v1.1.0
|
||||
**最后更新**: 2025-12-31
|
||||
**文档质量**: A级 ⭐⭐⭐⭐⭐
|
||||
@@ -1,251 +0,0 @@
|
||||
# 最终更新总结
|
||||
|
||||
**完成日期**: 2025-12-25
|
||||
**更新内容**: AuthScene文件修复 + Python API测试工具
|
||||
|
||||
---
|
||||
|
||||
## 🎯 完成的工作
|
||||
|
||||
### 1. ✅ AuthScene.gd 文件修复
|
||||
|
||||
#### 问题解决
|
||||
- **修复Parser Error**: 删除了第1196行的语法错误"母和数字"
|
||||
- **重构代码结构**: 完全重写了AuthScene.gd，代码更清晰、更易维护
|
||||
- **优化验证逻辑**: 使用StringUtils工具类统一处理表单验证
|
||||
|
||||
#### 文件状态
|
||||
- **语法检查**: ✅ No diagnostics found
|
||||
- **代码行数**: 约600行（原来~1400行，精简57%）
|
||||
- **功能完整性**: ✅ 保持所有原有功能
|
||||
- **API兼容性**: ✅ 完全支持API v1.1.1
|
||||
|
||||
### 2. ✅ Python API测试工具
|
||||
|
||||
#### 创建的测试脚本
|
||||
1. **`quick_test.py`** - 快速测试脚本（推荐日常使用）
|
||||
2. **`api_client_test.py`** - 完整测试套件（全面功能验证）
|
||||
3. **`requirements.txt`** - Python依赖配置
|
||||
4. **`run_tests.bat`** - Windows批处理脚本
|
||||
5. **`run_tests.sh`** - Linux/Mac Shell脚本
|
||||
|
||||
#### 测试覆盖范围
|
||||
- ✅ 应用状态检查
|
||||
- ✅ 用户认证流程（登录/注册）
|
||||
- ✅ 邮箱验证流程
|
||||
- ✅ 验证码功能（发送/验证）
|
||||
- ✅ 密码重置流程
|
||||
- ✅ 错误场景测试
|
||||
- ✅ 频率限制测试
|
||||
- ✅ API v1.1.1新特性测试
|
||||
|
||||
### 3. ✅ 文档更新
|
||||
|
||||
#### 新增文档
|
||||
- **`docs/testing_guide.md`** - 完整的API测试指南
|
||||
- **`docs/final_update_summary.md`** - 本总结文档
|
||||
- **`tests/api/README.md`** - 更新了测试说明
|
||||
|
||||
#### 更新文档
|
||||
- **`docs/api_update_log.md`** - API更新日志
|
||||
- **`docs/cleanup_summary.md`** - 代码清理总结
|
||||
|
||||
---
|
||||
|
||||
## 🔧 技术改进
|
||||
|
||||
### AuthScene.gd 优化
|
||||
```gdscript
|
||||
# 优化前的问题
|
||||
- 语法错误导致无法解析
|
||||
- 代码重复，维护困难
|
||||
- 验证逻辑分散
|
||||
|
||||
# 优化后的改进
|
||||
- 无语法错误，结构清晰
|
||||
- 使用StringUtils统一验证
|
||||
- 方法分组，易于维护
|
||||
```
|
||||
|
||||
### API测试工具特性
|
||||
```python
|
||||
# 完整的API客户端
|
||||
class APIClient:
|
||||
- 统一的请求处理
|
||||
- 详细的错误处理
|
||||
- 支持所有API端点
|
||||
- 自动状态码判断
|
||||
|
||||
# 智能测试结果
|
||||
class TestResult:
|
||||
- 成功/失败判断
|
||||
- 执行时间统计
|
||||
- 详细错误信息
|
||||
- 特殊状态码处理
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 测试验证
|
||||
|
||||
### 语法检查结果
|
||||
```bash
|
||||
✅ scripts/scenes/AuthScene.gd - No diagnostics found
|
||||
✅ core/managers/NetworkManager.gd - No diagnostics found
|
||||
✅ core/managers/ResponseHandler.gd - No diagnostics found
|
||||
```
|
||||
|
||||
### Python测试工具验证
|
||||
```bash
|
||||
# 快速测试
|
||||
python tests/api/quick_test.py
|
||||
# 预期结果: 6个基础API测试通过
|
||||
|
||||
# 完整测试
|
||||
python tests/api/api_client_test.py
|
||||
# 预期结果: 完整业务流程测试通过
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 使用指南
|
||||
|
||||
### 开发者日常使用
|
||||
|
||||
#### 1. 快速API测试
|
||||
```bash
|
||||
cd tests/api
|
||||
python quick_test.py
|
||||
```
|
||||
|
||||
#### 2. 完整功能验证
|
||||
```bash
|
||||
cd tests/api
|
||||
python api_client_test.py
|
||||
```
|
||||
|
||||
#### 3. Windows用户
|
||||
```bash
|
||||
cd tests/api
|
||||
run_tests.bat
|
||||
```
|
||||
|
||||
#### 4. Linux/Mac用户
|
||||
```bash
|
||||
cd tests/api
|
||||
./run_tests.sh
|
||||
```
|
||||
|
||||
### Godot开发者使用
|
||||
|
||||
#### 1. 运行AuthScene
|
||||
- 场景文件正常加载
|
||||
- Toast系统正常工作
|
||||
- 网络请求正常处理
|
||||
|
||||
#### 2. API测试脚本
|
||||
```gdscript
|
||||
# 在Godot中运行
|
||||
var api_test = preload("res://scripts/network/ApiTestScript.gd").new()
|
||||
add_child(api_test)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 质量保证
|
||||
|
||||
### 代码质量指标
|
||||
| 指标 | 修复前 | 修复后 | 改进 |
|
||||
|------|--------|--------|------|
|
||||
| 语法错误 | 1个 | 0个 | ✅ 完全修复 |
|
||||
| 代码行数 | ~1400行 | ~600行 | ✅ 精简57% |
|
||||
| 重复代码 | 多处 | 无 | ✅ 完全消除 |
|
||||
| 可维护性 | 中等 | 高 | ✅ 显著提升 |
|
||||
|
||||
### 功能完整性
|
||||
- ✅ 登录功能完整保留
|
||||
- ✅ 注册功能完整保留
|
||||
- ✅ 验证码功能完整保留
|
||||
- ✅ Toast显示功能增强
|
||||
- ✅ 错误处理功能增强
|
||||
|
||||
### API兼容性
|
||||
- ✅ 支持409冲突检测
|
||||
- ✅ 支持206测试模式
|
||||
- ✅ 支持429频率限制
|
||||
- ✅ 支持所有新增错误码
|
||||
- ✅ 向后兼容旧版本
|
||||
|
||||
---
|
||||
|
||||
## 📈 项目收益
|
||||
|
||||
### 开发效率提升
|
||||
1. **无需Godot引擎**: Python测试脚本可独立运行
|
||||
2. **快速验证**: 30秒内完成基础API测试
|
||||
3. **自动化支持**: 可集成到CI/CD流程
|
||||
4. **跨平台支持**: Windows/Linux/Mac都可使用
|
||||
|
||||
### 代码质量提升
|
||||
1. **消除语法错误**: AuthScene.gd现在完全可用
|
||||
2. **减少代码重复**: 使用工具类统一处理
|
||||
3. **提高可维护性**: 清晰的代码结构和注释
|
||||
4. **增强错误处理**: 支持最新API规范
|
||||
|
||||
### 测试覆盖提升
|
||||
1. **完整业务流程**: 覆盖所有用户操作场景
|
||||
2. **错误场景测试**: 验证各种异常情况
|
||||
3. **性能测试**: 包含频率限制测试
|
||||
4. **兼容性测试**: 支持不同环境测试
|
||||
|
||||
---
|
||||
|
||||
## 🚀 后续建议
|
||||
|
||||
### 短期优化
|
||||
1. **集成CI/CD**: 将Python测试脚本集成到自动化流程
|
||||
2. **监控告警**: 设置API测试失败的通知机制
|
||||
3. **性能基准**: 建立API响应时间基准线
|
||||
|
||||
### 长期规划
|
||||
1. **测试扩展**: 添加更多边界条件测试
|
||||
2. **压力测试**: 开发高并发场景测试
|
||||
3. **安全测试**: 添加安全漏洞检测测试
|
||||
|
||||
---
|
||||
|
||||
## 📚 相关资源
|
||||
|
||||
### 文档链接
|
||||
- [API文档](api-documentation.md) - 完整API接口说明
|
||||
- [测试指南](testing_guide.md) - 详细测试使用指南
|
||||
- [API更新日志](api_update_log.md) - 最新变更记录
|
||||
|
||||
### 代码文件
|
||||
- `scripts/scenes/AuthScene.gd` - 修复后的认证场景
|
||||
- `tests/api/quick_test.py` - 快速API测试脚本
|
||||
- `tests/api/api_client_test.py` - 完整API测试套件
|
||||
|
||||
### 工具脚本
|
||||
- `tests/api/run_tests.bat` - Windows测试启动器
|
||||
- `tests/api/run_tests.sh` - Linux/Mac测试启动器
|
||||
|
||||
---
|
||||
|
||||
## 🎉 总结
|
||||
|
||||
通过这次更新，我们成功：
|
||||
|
||||
1. **修复了关键问题** - AuthScene.gd的Parser Error已完全解决
|
||||
2. **提升了代码质量** - 代码更清晰、更易维护、更高效
|
||||
3. **增强了测试能力** - 提供了完整的Python API测试工具
|
||||
4. **改善了开发体验** - 无需Godot引擎即可测试API接口
|
||||
5. **保证了向后兼容** - 所有原有功能都得到保留和增强
|
||||
|
||||
现在开发者可以：
|
||||
- ✅ 正常使用AuthScene.gd进行认证界面开发
|
||||
- ✅ 使用Python脚本快速验证API接口
|
||||
- ✅ 在任何环境下进行API测试
|
||||
- ✅ 享受更好的错误处理和用户体验
|
||||
|
||||
**项目现在处于完全可用状态，支持最新的API v1.1.1规范！** 🚀
|
||||
@@ -1,505 +0,0 @@
|
||||
# Godot 项目结构说明
|
||||
|
||||
本文档详细说明了 whaleTown 项目的文件结构设计，采用"场景+通用工具+其他"的架构模式，确保每个场景清晰独立且高度解耦。
|
||||
|
||||
## 设计理念
|
||||
|
||||
### 核心原则
|
||||
- **场景独立性**：每个场景都是独立的功能模块，可以单独开发和测试
|
||||
- **高度解耦**：场景之间通过事件系统和管理器进行通信，避免直接依赖
|
||||
- **组件复用**：可复用的组件放在通用模块中，提高开发效率
|
||||
- **资源管理**：统一的资源管理和命名规范，便于维护
|
||||
|
||||
## 项目架构概览
|
||||
|
||||
```
|
||||
whaleTown/
|
||||
├── 🎬 scenes/ # 场景层：独立的游戏场景
|
||||
├── 🔧 core/ # 核心层：通用工具和系统
|
||||
├── 🎨 assets/ # 资源层：静态资源文件
|
||||
├── 📊 data/ # 数据层：配置和游戏数据
|
||||
├── 📝 scripts/ # 脚本层：业务逻辑代码
|
||||
├── 🧩 module/ # 模块层：可复用组件
|
||||
├── 🧪 tests/ # 测试层：单元测试和集成测试
|
||||
└── 📚 docs/ # 文档层：项目文档
|
||||
```
|
||||
|
||||
## 1. 场景层 (scenes/)
|
||||
|
||||
场景层包含所有独立的游戏场景，每个场景都是完整的功能模块。
|
||||
|
||||
### 1.1 场景分类
|
||||
|
||||
#### 主要场景 (Main Scenes)
|
||||
```
|
||||
scenes/
|
||||
├── main_scene.tscn # 主场景：游戏入口
|
||||
├── auth_scene.tscn # 认证场景：登录注册
|
||||
├── menu_scene.tscn # 菜单场景：主菜单界面
|
||||
├── game_scene.tscn # 游戏场景：主要游戏玩法
|
||||
├── battle_scene.tscn # 战斗场景：战斗系统
|
||||
├── inventory_scene.tscn # 背包场景：物品管理
|
||||
├── shop_scene.tscn # 商店场景：购买系统
|
||||
└── settings_scene.tscn # 设置场景：游戏设置
|
||||
```
|
||||
|
||||
#### 预制体场景 (Prefabs)
|
||||
```
|
||||
scenes/prefabs/
|
||||
├── ui/
|
||||
│ ├── dialog_prefab.tscn # 对话框预制体
|
||||
│ ├── button_prefab.tscn # 按钮预制体
|
||||
│ ├── health_bar_prefab.tscn # 血条预制体
|
||||
│ └── notification_prefab.tscn # 通知预制体
|
||||
├── characters/
|
||||
│ ├── player_prefab.tscn # 玩家角色预制体
|
||||
│ ├── npc_prefab.tscn # NPC预制体
|
||||
│ └── enemy_prefab.tscn # 敌人预制体
|
||||
├── items/
|
||||
│ ├── weapon_prefab.tscn # 武器预制体
|
||||
│ ├── consumable_prefab.tscn # 消耗品预制体
|
||||
│ └── collectible_prefab.tscn # 收集品预制体
|
||||
└── effects/
|
||||
├── explosion_prefab.tscn # 爆炸特效预制体
|
||||
├── particle_prefab.tscn # 粒子特效预制体
|
||||
└── damage_text_prefab.tscn # 伤害数字预制体
|
||||
```
|
||||
|
||||
### 1.2 场景设计原则
|
||||
|
||||
- **单一职责**：每个场景只负责一个主要功能
|
||||
- **独立运行**：场景可以独立启动和测试
|
||||
- **标准接口**：场景间通过标准化接口通信
|
||||
- **资源隔离**：场景相关资源放在对应子目录
|
||||
## 2. 核心层 (core/)
|
||||
|
||||
核心层提供通用的工具类、管理器和系统组件，为整个项目提供基础服务。
|
||||
|
||||
### 2.1 核心系统结构
|
||||
|
||||
```
|
||||
core/
|
||||
├── managers/ # 管理器系统
|
||||
│ ├── GameManager.gd # 游戏管理器：全局游戏状态
|
||||
│ ├── SceneManager.gd # 场景管理器：场景切换
|
||||
│ ├── AudioManager.gd # 音频管理器：音效音乐
|
||||
│ ├── InputManager.gd # 输入管理器：输入处理
|
||||
│ ├── SaveManager.gd # 存档管理器：数据存储
|
||||
│ ├── UIManager.gd # UI管理器：界面管理
|
||||
│ └── NetworkManager.gd # 网络管理器：网络通信
|
||||
├── systems/ # 系统组件
|
||||
│ ├── EventSystem.gd # 事件系统：全局事件
|
||||
│ ├── StateMachine.gd # 状态机系统
|
||||
│ ├── ObjectPool.gd # 对象池系统
|
||||
│ ├── ResourceLoader.gd # 资源加载系统
|
||||
│ └── LocalizationSystem.gd # 本地化系统
|
||||
├── utils/ # 工具类
|
||||
│ ├── MathUtils.gd # 数学工具
|
||||
│ ├── StringUtils.gd # 字符串工具
|
||||
│ ├── FileUtils.gd # 文件工具
|
||||
│ ├── TimeUtils.gd # 时间工具
|
||||
│ └── DebugUtils.gd # 调试工具
|
||||
├── components/ # 通用组件
|
||||
│ ├── HealthComponent.gd # 生命值组件
|
||||
│ ├── MovementComponent.gd # 移动组件
|
||||
│ ├── AnimationComponent.gd # 动画组件
|
||||
│ └── CollisionComponent.gd # 碰撞组件
|
||||
└── interfaces/ # 接口定义
|
||||
├── IInteractable.gd # 可交互接口
|
||||
├── IDamageable.gd # 可受伤接口
|
||||
├── ICollectable.gd # 可收集接口
|
||||
└── ISaveable.gd # 可存储接口
|
||||
```
|
||||
|
||||
### 2.2 核心系统职责
|
||||
|
||||
#### 管理器 (Managers)
|
||||
- **单例模式**：全局唯一实例
|
||||
- **生命周期管理**：负责系统初始化和清理
|
||||
- **状态维护**：维护全局状态信息
|
||||
- **服务提供**：为其他模块提供服务
|
||||
|
||||
#### 系统组件 (Systems)
|
||||
- **功能封装**：封装特定功能逻辑
|
||||
- **可插拔设计**：可以独立启用或禁用
|
||||
- **事件驱动**：通过事件系统通信
|
||||
- **性能优化**：提供高效的实现方案
|
||||
## 3. 模块层 (module/)
|
||||
|
||||
模块层包含可复用的功能模块，这些模块可以在不同场景中重复使用。
|
||||
|
||||
### 3.1 模块分类
|
||||
|
||||
```
|
||||
module/
|
||||
├── UI/ # UI模块
|
||||
│ ├── components/ # UI组件
|
||||
│ │ ├── Button/ # 按钮组件
|
||||
│ │ │ ├── CustomButton.gd
|
||||
│ │ │ └── custom_button.tscn
|
||||
│ │ ├── Dialog/ # 对话框组件
|
||||
│ │ │ ├── DialogBox.gd
|
||||
│ │ │ └── dialog_box.tscn
|
||||
│ │ ├── ProgressBar/ # 进度条组件
|
||||
│ │ │ ├── CustomProgressBar.gd
|
||||
│ │ │ └── custom_progress_bar.tscn
|
||||
│ │ └── InputField/ # 输入框组件
|
||||
│ │ ├── CustomInputField.gd
|
||||
│ │ └── custom_input_field.tscn
|
||||
│ ├── layouts/ # 布局组件
|
||||
│ │ ├── GridLayout.gd
|
||||
│ │ ├── FlexLayout.gd
|
||||
│ │ └── ResponsiveLayout.gd
|
||||
│ └── animations/ # UI动画
|
||||
│ ├── FadeTransition.gd
|
||||
│ ├── SlideTransition.gd
|
||||
│ └── ScaleTransition.gd
|
||||
├── Character/ # 角色模块
|
||||
│ ├── Player/ # 玩家角色
|
||||
│ │ ├── PlayerController.gd
|
||||
│ │ ├── PlayerStats.gd
|
||||
│ │ └── PlayerAnimator.gd
|
||||
│ ├── NPC/ # NPC角色
|
||||
│ │ ├── NPCController.gd
|
||||
│ │ ├── NPCDialogue.gd
|
||||
│ │ └── NPCBehavior.gd
|
||||
│ └── Enemy/ # 敌人角色
|
||||
│ ├── EnemyAI.gd
|
||||
│ ├── EnemyStats.gd
|
||||
│ └── EnemyBehavior.gd
|
||||
├── Inventory/ # 背包模块
|
||||
│ ├── InventorySystem.gd
|
||||
│ ├── Item.gd
|
||||
│ ├── ItemSlot.gd
|
||||
│ └── ItemDatabase.gd
|
||||
├── Combat/ # 战斗模块
|
||||
│ ├── CombatSystem.gd
|
||||
│ ├── Weapon.gd
|
||||
│ ├── Skill.gd
|
||||
│ └── DamageCalculator.gd
|
||||
└── Dialogue/ # 对话模块
|
||||
├── DialogueSystem.gd
|
||||
├── DialogueNode.gd
|
||||
├── DialogueParser.gd
|
||||
└── DialogueUI.gd
|
||||
```
|
||||
|
||||
### 3.2 模块设计原则
|
||||
|
||||
- **高内聚**：模块内部功能紧密相关
|
||||
- **低耦合**：模块间依赖最小化
|
||||
- **可配置**：通过配置文件自定义行为
|
||||
- **可扩展**：支持功能扩展和定制
|
||||
## 4. 资源层 (assets/)
|
||||
|
||||
资源层统一管理所有静态资源文件，采用分类存储和标准化命名。
|
||||
|
||||
### 4.1 资源目录结构
|
||||
|
||||
```
|
||||
assets/
|
||||
├── sprites/ # 精灵图资源
|
||||
│ ├── characters/ # 角色精灵
|
||||
│ │ ├── player/
|
||||
│ │ │ ├── sprite_player_idle.png
|
||||
│ │ │ ├── sprite_player_walk.png
|
||||
│ │ │ └── sprite_player_attack.png
|
||||
│ │ ├── enemies/
|
||||
│ │ │ ├── sprite_enemy_goblin_idle.png
|
||||
│ │ │ └── sprite_enemy_orc_walk.png
|
||||
│ │ └── npcs/
|
||||
│ │ ├── sprite_npc_merchant.png
|
||||
│ │ └── sprite_npc_guard.png
|
||||
│ ├── ui/ # UI精灵
|
||||
│ │ ├── buttons/
|
||||
│ │ │ ├── ui_button_normal.png
|
||||
│ │ │ ├── ui_button_hover.png
|
||||
│ │ │ └── ui_button_pressed.png
|
||||
│ │ ├── icons/
|
||||
│ │ │ ├── icon_sword.png
|
||||
│ │ │ ├── icon_shield.png
|
||||
│ │ │ └── icon_potion.png
|
||||
│ │ └── panels/
|
||||
│ │ ├── ui_panel_main.png
|
||||
│ │ └── ui_panel_dialog.png
|
||||
│ ├── environment/ # 环境精灵
|
||||
│ │ ├── backgrounds/
|
||||
│ │ │ ├── bg_forest.png
|
||||
│ │ │ └── bg_dungeon.png
|
||||
│ │ ├── tiles/
|
||||
│ │ │ ├── tile_grass_01.png
|
||||
│ │ │ └── tile_stone_01.png
|
||||
│ │ └── objects/
|
||||
│ │ ├── obj_tree.png
|
||||
│ │ └── obj_rock.png
|
||||
│ └── effects/ # 特效精灵
|
||||
│ ├── fx_explosion.png
|
||||
│ ├── fx_magic_circle.png
|
||||
│ └── fx_damage_numbers.png
|
||||
├── audio/ # 音频资源
|
||||
│ ├── music/ # 背景音乐
|
||||
│ │ ├── music_main_menu.ogg
|
||||
│ │ ├── music_battle.ogg
|
||||
│ │ └── music_peaceful.ogg
|
||||
│ ├── sounds/ # 音效
|
||||
│ │ ├── ui/
|
||||
│ │ │ ├── sound_button_click.wav
|
||||
│ │ │ └── sound_menu_open.wav
|
||||
│ │ ├── combat/
|
||||
│ │ │ ├── sound_sword_hit.wav
|
||||
│ │ │ └── sound_explosion.wav
|
||||
│ │ └── ambient/
|
||||
│ │ ├── sound_footsteps.wav
|
||||
│ │ └── sound_wind.wav
|
||||
│ └── voice/ # 语音
|
||||
│ ├── voice_npc_greeting.wav
|
||||
│ └── voice_player_hurt.wav
|
||||
├── fonts/ # 字体资源
|
||||
│ ├── font_main.ttf # 主要字体
|
||||
│ ├── font_title.ttf # 标题字体
|
||||
│ └── font_ui.ttf # UI字体
|
||||
├── materials/ # 材质资源
|
||||
│ ├── material_metal.tres
|
||||
│ ├── material_wood.tres
|
||||
│ └── material_water.tres
|
||||
└── shaders/ # 着色器资源
|
||||
├── shader_water.gdshader
|
||||
├── shader_fire.gdshader
|
||||
└── shader_outline.gdshader
|
||||
```
|
||||
|
||||
### 4.2 资源命名规范
|
||||
|
||||
#### 图片资源命名
|
||||
- **精灵图**：`sprite_[类别]_[名称]_[状态].png`
|
||||
- 示例：`sprite_player_idle.png`、`sprite_enemy_goblin_walk.png`
|
||||
- **UI图片**：`ui_[类型]_[名称]_[状态].png`
|
||||
- 示例：`ui_button_normal.png`、`ui_panel_main.png`
|
||||
- **图标**：`icon_[名称].png`
|
||||
- 示例：`icon_sword.png`、`icon_health.png`
|
||||
- **背景**：`bg_[场景名称].png`
|
||||
- 示例：`bg_forest.png`、`bg_dungeon.png`
|
||||
- **瓦片**：`tile_[材质]_[编号].png`
|
||||
- 示例：`tile_grass_01.png`、`tile_stone_02.png`
|
||||
|
||||
#### 音频资源命名
|
||||
- **音乐**：`music_[场景/情境].ogg`
|
||||
- 示例：`music_battle.ogg`、`music_peaceful.ogg`
|
||||
- **音效**：`sound_[动作/事件].wav`
|
||||
- 示例：`sound_jump.wav`、`sound_explosion.wav`
|
||||
- **语音**：`voice_[角色]_[内容].wav`
|
||||
- 示例：`voice_npc_greeting.wav`、`voice_player_hurt.wav`
|
||||
|
||||
#### 其他资源命名
|
||||
- **字体**：`font_[用途].ttf`
|
||||
- 示例：`font_main.ttf`、`font_title.ttf`
|
||||
- **材质**：`material_[材质名].tres`
|
||||
- 示例：`material_metal.tres`、`material_wood.tres`
|
||||
- **着色器**：`shader_[效果名].gdshader`
|
||||
- 示例：`shader_water.gdshader`、`shader_fire.gdshader`
|
||||
## 5. 脚本层 (scripts/)
|
||||
|
||||
脚本层包含所有业务逻辑代码，按功能模块组织。
|
||||
|
||||
### 5.1 脚本目录结构
|
||||
|
||||
```
|
||||
scripts/
|
||||
├── scenes/ # 场景脚本
|
||||
│ ├── MainScene.gd # 主场景脚本
|
||||
│ ├── AuthScene.gd # 认证场景脚本
|
||||
│ ├── GameScene.gd # 游戏场景脚本
|
||||
│ └── BattleScene.gd # 战斗场景脚本
|
||||
├── ui/ # UI脚本
|
||||
│ ├── MainMenu.gd # 主菜单脚本
|
||||
│ ├── SettingsPanel.gd # 设置面板脚本
|
||||
│ ├── InventoryUI.gd # 背包界面脚本
|
||||
│ └── DialogueUI.gd # 对话界面脚本
|
||||
├── characters/ # 角色脚本
|
||||
│ ├── PlayerController.gd # 玩家控制器
|
||||
│ ├── EnemyAI.gd # 敌人AI
|
||||
│ └── NPCBehavior.gd # NPC行为
|
||||
├── gameplay/ # 游戏玩法脚本
|
||||
│ ├── CombatSystem.gd # 战斗系统
|
||||
│ ├── QuestSystem.gd # 任务系统
|
||||
│ ├── InventorySystem.gd # 背包系统
|
||||
│ └── DialogueSystem.gd # 对话系统
|
||||
├── network/ # 网络脚本
|
||||
│ ├── NetworkClient.gd # 网络客户端
|
||||
│ ├── NetworkServer.gd # 网络服务器
|
||||
│ └── NetworkProtocol.gd # 网络协议
|
||||
└── data/ # 数据脚本
|
||||
├── GameData.gd # 游戏数据
|
||||
├── PlayerData.gd # 玩家数据
|
||||
├── ItemData.gd # 物品数据
|
||||
└── ConfigData.gd # 配置数据
|
||||
```
|
||||
|
||||
## 6. 数据层 (data/)
|
||||
|
||||
数据层存储游戏配置、关卡数据和其他静态数据文件。
|
||||
|
||||
### 6.1 数据目录结构
|
||||
|
||||
```
|
||||
data/
|
||||
├── configs/ # 配置文件
|
||||
│ ├── game_config.json # 游戏配置
|
||||
│ ├── audio_config.json # 音频配置
|
||||
│ ├── input_config.json # 输入配置
|
||||
│ └── graphics_config.json # 图形配置
|
||||
├── levels/ # 关卡数据
|
||||
│ ├── level_01.json # 第一关数据
|
||||
│ ├── level_02.json # 第二关数据
|
||||
│ └── level_boss.json # Boss关数据
|
||||
├── items/ # 物品数据
|
||||
│ ├── weapons.json # 武器数据
|
||||
│ ├── armor.json # 装备数据
|
||||
│ └── consumables.json # 消耗品数据
|
||||
├── characters/ # 角色数据
|
||||
│ ├── player_stats.json # 玩家属性
|
||||
│ ├── enemy_stats.json # 敌人属性
|
||||
│ └── npc_data.json # NPC数据
|
||||
├── dialogues/ # 对话数据
|
||||
│ ├── main_story.json # 主线对话
|
||||
│ ├── side_quests.json # 支线对话
|
||||
│ └── npc_dialogues.json # NPC对话
|
||||
└── localization/ # 本地化数据
|
||||
├── en.json # 英文文本
|
||||
├── zh_CN.json # 简体中文文本
|
||||
└── zh_TW.json # 繁体中文文本
|
||||
```
|
||||
|
||||
## 7. 测试层 (tests/)
|
||||
|
||||
测试层包含单元测试、集成测试和功能测试。
|
||||
|
||||
### 7.1 测试目录结构
|
||||
|
||||
```
|
||||
tests/
|
||||
├── unit/ # 单元测试
|
||||
│ ├── test_player_controller.gd
|
||||
│ ├── test_inventory_system.gd
|
||||
│ └── test_combat_system.gd
|
||||
├── integration/ # 集成测试
|
||||
│ ├── test_scene_transitions.gd
|
||||
│ ├── test_save_load.gd
|
||||
│ └── test_network_sync.gd
|
||||
├── ui/ # UI测试
|
||||
│ ├── test_main_menu.gd
|
||||
│ ├── test_inventory_ui.gd
|
||||
│ └── test_dialogue_ui.gd
|
||||
└── performance/ # 性能测试
|
||||
├── test_memory_usage.gd
|
||||
├── test_frame_rate.gd
|
||||
└── test_loading_times.gd
|
||||
```
|
||||
## 8. 场景间通信机制
|
||||
|
||||
### 8.1 事件系统
|
||||
|
||||
使用全局事件系统实现场景间的松耦合通信：
|
||||
|
||||
```gdscript
|
||||
# 事件定义示例
|
||||
signal player_health_changed(new_health: int)
|
||||
signal scene_transition_requested(scene_name: String)
|
||||
signal item_collected(item_id: String)
|
||||
signal quest_completed(quest_id: String)
|
||||
|
||||
# 事件发送
|
||||
EventSystem.emit_signal("player_health_changed", 80)
|
||||
|
||||
# 事件监听
|
||||
EventSystem.connect("player_health_changed", _on_player_health_changed)
|
||||
```
|
||||
|
||||
### 8.2 管理器模式
|
||||
|
||||
通过单例管理器实现全局状态管理：
|
||||
|
||||
```gdscript
|
||||
# 场景切换
|
||||
SceneManager.change_scene("battle_scene")
|
||||
|
||||
# 音频播放
|
||||
AudioManager.play_sound("sound_button_click")
|
||||
|
||||
# 数据保存
|
||||
SaveManager.save_game_data(player_data)
|
||||
```
|
||||
|
||||
## 9. 开发工作流
|
||||
|
||||
### 9.1 新场景开发流程
|
||||
|
||||
1. **创建场景文件**：在 `scenes/` 目录创建 `.tscn` 文件
|
||||
2. **编写场景脚本**：在 `scripts/scenes/` 创建对应脚本
|
||||
3. **添加UI组件**：使用 `module/UI/` 中的可复用组件
|
||||
4. **配置场景数据**：在 `data/` 目录添加相关配置
|
||||
5. **编写测试用例**：在 `tests/` 目录添加测试
|
||||
6. **更新文档**：更新相关文档说明
|
||||
|
||||
### 9.2 新功能模块开发流程
|
||||
|
||||
1. **设计模块接口**：定义模块的公共接口
|
||||
2. **实现核心逻辑**：在 `module/` 目录实现功能
|
||||
3. **添加管理器支持**：在 `core/managers/` 添加管理器
|
||||
4. **创建测试场景**：创建独立的测试场景
|
||||
5. **集成到主项目**：将模块集成到现有场景
|
||||
6. **性能优化**：进行性能测试和优化
|
||||
|
||||
## 10. 最佳实践
|
||||
|
||||
### 10.1 代码组织
|
||||
|
||||
- **单一职责**：每个类只负责一个功能
|
||||
- **依赖注入**：通过构造函数或属性注入依赖
|
||||
- **接口隔离**：使用接口定义模块间的契约
|
||||
- **配置外置**：将配置信息放在数据文件中
|
||||
|
||||
### 10.2 性能优化
|
||||
|
||||
- **对象池**：复用频繁创建的对象
|
||||
- **延迟加载**：按需加载资源和场景
|
||||
- **批量处理**：合并相似的操作
|
||||
- **内存管理**：及时释放不需要的资源
|
||||
|
||||
### 10.3 调试和测试
|
||||
|
||||
- **单元测试**：为核心逻辑编写单元测试
|
||||
- **集成测试**：测试模块间的交互
|
||||
- **性能监控**：监控内存和CPU使用情况
|
||||
- **日志记录**：记录关键操作和错误信息
|
||||
|
||||
## 11. 扩展指南
|
||||
|
||||
### 11.1 添加新场景
|
||||
|
||||
1. 在 `scenes/` 目录创建场景文件
|
||||
2. 在 `scripts/scenes/` 创建场景脚本
|
||||
3. 在 `SceneManager` 中注册新场景
|
||||
4. 添加场景切换逻辑
|
||||
|
||||
### 11.2 添加新模块
|
||||
|
||||
1. 在 `module/` 目录创建模块文件夹
|
||||
2. 实现模块的核心功能
|
||||
3. 创建模块管理器（如需要）
|
||||
4. 编写模块文档和示例
|
||||
|
||||
### 11.3 添加新资源类型
|
||||
|
||||
1. 在 `assets/` 目录创建对应分类
|
||||
2. 更新命名规范文档
|
||||
3. 在资源加载器中添加支持
|
||||
4. 更新导入设置
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
这个项目结构设计遵循了模块化、可扩展、易维护的原则。通过清晰的分层架构和标准化的命名规范，确保了项目的可读性和可维护性。每个开发者都应该遵循这个结构进行开发，以保持项目的一致性和质量。
|
||||
|
||||
如有任何疑问或建议，请参考相关文档或联系项目维护者。
|
||||
@@ -1,28 +0,0 @@
|
||||
# 项目设置指南
|
||||
|
||||
## AutoLoad 配置
|
||||
|
||||
在 Godot 编辑器中设置 NetworkManager 为全局单例：
|
||||
|
||||
1. 打开 `Project` → `Project Settings`
|
||||
2. 切换到 `AutoLoad` 标签
|
||||
3. 添加新的 AutoLoad：
|
||||
- **Path**: `res://core/managers/NetworkManager.gd`
|
||||
- **Name**: `NetworkManager`
|
||||
- **Singleton**: ✅ 勾选
|
||||
|
||||
## 验证设置
|
||||
|
||||
在任何脚本中可以直接使用：
|
||||
|
||||
```gdscript
|
||||
func _ready():
|
||||
var request_id = NetworkManager.login("username", "password", callback)
|
||||
print("请求ID: ", request_id)
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 确保 NetworkManager.gd 和 ResponseHandler.gd 文件存在
|
||||
- 重启 Godot 编辑器以确保 AutoLoad 生效
|
||||
- 检查控制台是否有错误信息
|
||||
@@ -1,200 +0,0 @@
|
||||
# Web部署更新日志
|
||||
|
||||
## v1.0.0 (2025-12-25)
|
||||
|
||||
### 🎉 初始版本
|
||||
- 创建完整的Web导出解决方案
|
||||
- 支持Windows、Linux、macOS平台
|
||||
- 自动化构建和部署脚本
|
||||
|
||||
### 📁 文件结构
|
||||
```
|
||||
scripts/
|
||||
├── build_web.bat # Windows导出脚本
|
||||
├── build_web.sh # Linux/macOS导出脚本
|
||||
├── serve_web.bat # Windows本地服务器
|
||||
└── serve_web.sh # Linux/macOS本地服务器
|
||||
|
||||
docs/
|
||||
├── web_deployment_guide.md # 完整部署指南
|
||||
└── web_deployment_changelog.md # 更新日志
|
||||
```
|
||||
|
||||
### ✨ 主要特性
|
||||
|
||||
#### 自动化导出
|
||||
- 智能检测Godot安装路径
|
||||
- 验证项目文件完整性
|
||||
- 自动备份旧版本
|
||||
- 生成部署配置文件
|
||||
- 文件大小统计和优化建议
|
||||
|
||||
#### 本地测试服务器
|
||||
- 自动端口检测和冲突处理
|
||||
- 支持局域网访问
|
||||
- 实时文件监控
|
||||
- 自动打开浏览器
|
||||
- 详细的调试信息
|
||||
|
||||
#### 服务器配置
|
||||
- Apache .htaccess自动生成
|
||||
- Nginx配置示例
|
||||
- MIME类型配置
|
||||
- CORS头设置
|
||||
- 文件压缩优化
|
||||
- 缓存策略配置
|
||||
|
||||
#### 部署优化
|
||||
- 资源文件压缩
|
||||
- 渐进式Web应用支持
|
||||
- 性能监控
|
||||
- 错误诊断工具
|
||||
|
||||
### 🔧 技术规格
|
||||
|
||||
#### 支持的平台
|
||||
- **开发环境**: Windows 10+, macOS 10.15+, Ubuntu 18.04+
|
||||
- **目标浏览器**: Chrome 80+, Firefox 75+, Safari 13+, Edge 80+
|
||||
- **Godot版本**: 4.5+
|
||||
|
||||
#### 系统要求
|
||||
- **Godot Engine**: 4.5或更高版本
|
||||
- **Python**: 3.6+（用于本地测试）
|
||||
- **磁盘空间**: 至少100MB可用空间
|
||||
- **内存**: 建议4GB以上
|
||||
|
||||
#### 网络要求
|
||||
- **带宽**: 建议10Mbps以上（用于资源下载）
|
||||
- **端口**: 8000（默认），8080（备用）
|
||||
- **协议**: HTTP/HTTPS
|
||||
|
||||
### 📋 配置选项
|
||||
|
||||
#### 导出设置
|
||||
```
|
||||
导出预设: Web
|
||||
渲染方法: gl_compatibility
|
||||
纹理压缩: 启用VRAM压缩
|
||||
文件格式: WASM + PCK
|
||||
```
|
||||
|
||||
#### 服务器设置
|
||||
```
|
||||
默认端口: 8000
|
||||
备用端口: 8080
|
||||
文档根目录: build/web/
|
||||
索引文件: index.html
|
||||
```
|
||||
|
||||
### 🚀 性能优化
|
||||
|
||||
#### 文件大小优化
|
||||
- WASM文件压缩率: ~30%
|
||||
- 纹理压缩: ETC2/ASTC格式
|
||||
- 音频压缩: OGG Vorbis
|
||||
- 脚本压缩: 移除调试信息
|
||||
|
||||
#### 加载速度优化
|
||||
- 启用Gzip压缩
|
||||
- 设置缓存策略
|
||||
- 使用CDN加速
|
||||
- 实现预加载机制
|
||||
|
||||
### 🛡️ 安全特性
|
||||
|
||||
#### 跨域安全
|
||||
- CORS头配置
|
||||
- CSP策略设置
|
||||
- XSS防护
|
||||
- 点击劫持防护
|
||||
|
||||
#### 文件安全
|
||||
- MIME类型验证
|
||||
- 文件大小限制
|
||||
- 路径遍历防护
|
||||
- 敏感文件隐藏
|
||||
|
||||
### 📊 监控和诊断
|
||||
|
||||
#### 构建监控
|
||||
- 文件完整性检查
|
||||
- 大小统计分析
|
||||
- 构建时间记录
|
||||
- 错误日志收集
|
||||
|
||||
#### 运行时监控
|
||||
- 性能指标收集
|
||||
- 错误报告系统
|
||||
- 用户行为分析
|
||||
- 网络请求监控
|
||||
|
||||
### 🔄 兼容性
|
||||
|
||||
#### 浏览器兼容性
|
||||
| 浏览器 | 最低版本 | 推荐版本 | 支持特性 |
|
||||
|--------|----------|----------|----------|
|
||||
| Chrome | 80 | 最新 | 完整支持 |
|
||||
| Firefox | 75 | 最新 | 完整支持 |
|
||||
| Safari | 13 | 最新 | 基本支持 |
|
||||
| Edge | 80 | 最新 | 完整支持 |
|
||||
|
||||
#### 移动端兼容性
|
||||
- iOS Safari 13+
|
||||
- Android Chrome 80+
|
||||
- 响应式设计支持
|
||||
- 触摸操作优化
|
||||
|
||||
### 📝 已知问题
|
||||
|
||||
#### 当前限制
|
||||
1. **文件系统访问**: Web版本无法直接访问本地文件系统
|
||||
2. **性能差异**: 相比原生版本可能有10-30%的性能损失
|
||||
3. **内存限制**: 受浏览器内存限制影响
|
||||
4. **网络依赖**: 需要稳定的网络连接
|
||||
|
||||
#### 解决方案
|
||||
1. 使用IndexedDB存储本地数据
|
||||
2. 优化资源和代码以提升性能
|
||||
3. 实现内存管理和垃圾回收
|
||||
4. 添加离线缓存支持
|
||||
|
||||
### 🔮 未来计划
|
||||
|
||||
#### v1.1.0 (计划中)
|
||||
- [ ] PWA（渐进式Web应用）完整支持
|
||||
- [ ] 离线模式实现
|
||||
- [ ] 自动更新机制
|
||||
- [ ] 性能分析工具
|
||||
|
||||
#### v1.2.0 (计划中)
|
||||
- [ ] WebRTC多人游戏支持
|
||||
- [ ] WebGL 2.0优化
|
||||
- [ ] 移动端手势优化
|
||||
- [ ] 云存档同步
|
||||
|
||||
#### v2.0.0 (远期计划)
|
||||
- [ ] WebAssembly SIMD支持
|
||||
- [ ] Web Workers多线程
|
||||
- [ ] WebXR虚拟现实支持
|
||||
- [ ] 边缘计算集成
|
||||
|
||||
### 📞 技术支持
|
||||
|
||||
#### 问题报告
|
||||
如遇到问题，请提供以下信息：
|
||||
1. 操作系统和版本
|
||||
2. 浏览器类型和版本
|
||||
3. Godot版本
|
||||
4. 错误日志和截图
|
||||
5. 复现步骤
|
||||
|
||||
#### 联系方式
|
||||
- 项目文档: `docs/web_deployment_guide.md`
|
||||
- 构建日志: `build/web/server.log`
|
||||
- 部署信息: `build/web/deploy_info.json`
|
||||
|
||||
---
|
||||
|
||||
**维护者**: 鲸鱼镇开发团队
|
||||
**最后更新**: 2025-12-25
|
||||
**文档版本**: 1.0.0
|
||||
@@ -39,6 +39,43 @@ window/stretch/aspect="expand"
|
||||
|
||||
theme/custom="uid://cp7t8tu7rmyad"
|
||||
|
||||
[input]
|
||||
|
||||
move_left={
|
||||
"deadzone": 0.5,
|
||||
"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":65,"key_label":0,"unicode":97,"location":0,"echo":false,"script":null)
|
||||
, Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194319,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
|
||||
]
|
||||
}
|
||||
move_right={
|
||||
"deadzone": 0.5,
|
||||
"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":68,"key_label":0,"unicode":100,"location":0,"echo":false,"script":null)
|
||||
, Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194321,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
|
||||
]
|
||||
}
|
||||
move_up={
|
||||
"deadzone": 0.5,
|
||||
"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":87,"key_label":0,"unicode":119,"location":0,"echo":false,"script":null)
|
||||
, Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194320,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
|
||||
]
|
||||
}
|
||||
move_down={
|
||||
"deadzone": 0.5,
|
||||
"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":83,"key_label":0,"unicode":115,"location":0,"echo":false,"script":null)
|
||||
, Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":4194322,"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)
|
||||
]
|
||||
}
|
||||
jump={
|
||||
"deadzone": 0.5,
|
||||
"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":32,"key_label":0,"unicode":32,"location":0,"echo":false,"script":null)
|
||||
]
|
||||
}
|
||||
interact={
|
||||
"deadzone": 0.5,
|
||||
"events": [Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0,"physical_keycode":69,"key_label":0,"unicode":101,"location":0,"echo":false,"script":null)
|
||||
]
|
||||
}
|
||||
|
||||
[internationalization]
|
||||
|
||||
locale/test="zh_CN"
|
||||
|
||||
Reference in New Issue
Block a user