forked from datawhale/whale-town-front
docs: 更新项目结构说明，匹配实际项目结构
主要更新: - 根据实际项目目录结构重写文档 - 明确三类团队协作模式：开发、美术、策划 - 详细说明每个目录的职责和使用方式 - 添加团队协作指南和工作流程 - 提供实际的代码示例和配置示例 新增内容: - 团队协作模式说明 (开发/美术/策划) - 详细的目录结构和文件说明 - 开发工作流和版本发布流程 - 最佳实践和规范要求 确保准确性: - 所有目录结构都基于实际项目检查 - 文件路径和命名完全匹配当前状态 - 团队职责划分清晰明确
This commit is contained in:
@@ -1,505 +1,334 @@
|
|||||||
# Godot 项目结构说明
|
# WhaleTown 项目结构说明
|
||||||
|
|
||||||
本文档详细说明了 whaleTown 项目的文件结构设计，采用"场景+通用工具+其他"的架构模式，确保每个场景清晰独立且高度解耦。
|
本文档详细说明了 WhaleTown 项目的文件结构设计，采用分层架构模式，确保团队协作高效且代码结构清晰。
|
||||||
|
|
||||||
## 设计理念
|
## 🎯 设计理念
|
||||||
|
|
||||||
### 核心原则
|
### 核心原则
|
||||||
- **场景独立性**：每个场景都是独立的功能模块，可以单独开发和测试
|
- **分层架构**：框架层、游戏层、界面层明确分离
|
||||||
- **高度解耦**：场景之间通过事件系统和管理器进行通信，避免直接依赖
|
- **团队协作**：策划、美术、开发三类角色各司其职
|
||||||
- **组件复用**：可复用的组件放在通用模块中，提高开发效率
|
- **高度解耦**：通过事件系统实现组件间通信
|
||||||
- **资源管理**：统一的资源管理和命名规范，便于维护
|
- **组件复用**：可复用组件统一管理
|
||||||
|
- **标准化**：统一的命名规范和目录结构
|
||||||
|
|
||||||
## 项目架构概览
|
### 团队协作模式
|
||||||
|
- **🎮 开发团队** - 主要工作在 `_Core/`、`scenes/`、`UI/`、`Utils/`
|
||||||
|
- **🎨 美术团队** - 主要工作在 `assets/`
|
||||||
|
- **📋 策划团队** - 主要工作在 `Config/`
|
||||||
|
|
||||||
|
## 🏗️ 项目架构概览
|
||||||
|
|
||||||
```
|
```
|
||||||
whaleTown/
|
WhaleTown/
|
||||||
├── 🎬 scenes/ # 场景层：独立的游戏场景
|
├── 🔧 _Core/ # [框架层] 核心系统和管理器
|
||||||
├── 🔧 core/ # 核心层：通用工具和系统
|
├── 🎬 scenes/ # [游戏层] 游戏场景和组件
|
||||||
├── 🎨 assets/ # 资源层：静态资源文件
|
├── 🎨 UI/ # [界面层] 用户界面
|
||||||
├── 📊 data/ # 数据层：配置和游戏数据
|
├── 🖼️ assets/ # [资源层] 美术资源
|
||||||
├── 📝 scripts/ # 脚本层：业务逻辑代码
|
├── ⚙️ Config/ # [配置层] 游戏配置和数据
|
||||||
├── 🧩 module/ # 模块层：可复用组件
|
├── 🛠️ Utils/ # [工具层] 通用工具脚本
|
||||||
├── 🧪 tests/ # 测试层：单元测试和集成测试
|
├── 🧪 tests/ # [测试层] 测试文件
|
||||||
└── 📚 docs/ # 文档层：项目文档
|
├── 🚀 tools/ # [构建层] 构建和部署工具
|
||||||
|
├── 🌐 web_assets/ # [发布层] Web版本资源
|
||||||
|
└── 📚 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. 🔧 框架层 (_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)
|
||||||
|
- 及时清理不使用的资源文件
|
||||||
|
|
||||||
|
### 代码组织规范
|
||||||
|
- 脚本文件与场景文件放在同一目录
|
||||||
|
- 使用事件系统实现模块间通信
|
||||||
|
- 保持单一职责原则，避免过度耦合
|
||||||
|
- 及时编写注释和文档
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**记住：良好的项目结构是团队协作成功的基础！**
|
||||||
Reference in New Issue
Block a user