config：更新项目配置和文档

- 更新Godot项目配置，添加自动加载脚本 - 完善.gitignore文件，排除不必要的文件 - 更新README文档，添加项目介绍和使用说明 - 更新主场景配置，集成认证系统 - 添加开发规范文档和项目结构说明
2025-12-24 20:39:33 +08:00
parent 5b67771bbc
commit 370cffbdd8
10 changed files with 2112 additions and 91 deletions
--- a/docs/project_structure.md
+++ b/docs/project_structure.md
@@ -0,0 +1,505 @@
+# 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. 更新导入设置
+
+---
+
+## 总结
+
+这个项目结构设计遵循了模块化、可扩展、易维护的原则。通过清晰的分层架构和标准化的命名规范，确保了项目的可读性和可维护性。每个开发者都应该遵循这个结构进行开发，以保持项目的一致性和质量。
+
+如有任何疑问或建议，请参考相关文档或联系项目维护者。