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

---

## 总结

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

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