# 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. 更新导入设置 --- ## 总结 这个项目结构设计遵循了模块化、可扩展、易维护的原则。通过清晰的分层架构和标准化的命名规范，确保了项目的可读性和可维护性。每个开发者都应该遵循这个结构进行开发，以保持项目的一致性和质量。 如有任何疑问或建议，请参考相关文档或联系项目维护者。