moyin
1ff677b3b2
新的目录结构: 01-项目入门/ # 新人必读，项目基础 02-开发规范/ # 编码标准和规范 03-技术实现/ # 具体开发指导 04-高级开发/ # 进阶开发技巧 05-部署运维/ # 发布和部署 06-功能模块/ # 特定功能文档 新增导航文档: - docs/README.md - 完整的文档导航和使用指南 - 各目录下的README.md - 分类说明和使用指导 优化效果: - 开发者可以按阶段快速定位需要的文档 - 新人有清晰的学习路径 - 不同角色有针对性的文档推荐 - 提供了问题导向的快速查找功能
505 lines
19 KiB
Markdown
505 lines
19 KiB
Markdown
# 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. 更新导入设置
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
这个项目结构设计遵循了模块化、可扩展、易维护的原则。通过清晰的分层架构和标准化的命名规范，确保了项目的可读性和可维护性。每个开发者都应该遵循这个结构进行开发，以保持项目的一致性和质量。
|
||
|
||
如有任何疑问或建议，请参考相关文档或联系项目维护者。 |