whale-town-front/docs/project_structure.md

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 事件系统

使用全局事件系统实现场景间的松耦合通信：

# 事件定义示例
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 管理器模式

通过单例管理器实现全局状态管理：

# 场景切换
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. 更新导入设置

---

总结

这个项目结构设计遵循了模块化、可扩展、易维护的原则。通过清晰的分层架构和标准化的命名规范，确保了项目的可读性和可维护性。每个开发者都应该遵循这个结构进行开发，以保持项目的一致性和质量。

如有任何疑问或建议，请参考相关文档或联系项目维护者。