From 6f545b04e920483e8e6aab5c774eb4f7f2bb8b28 Mon Sep 17 00:00:00 2001 From: moyin <2443444649@qq.com> Date: Wed, 31 Dec 2025 18:08:31 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E7=BB=93=E6=9E=84=E8=AF=B4=E6=98=8E=EF=BC=8C=E5=8C=B9=E9=85=8D?= =?UTF-8?q?=E5=AE=9E=E9=99=85=E9=A1=B9=E7=9B=AE=E7=BB=93=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 主要更新: - 根据实际项目目录结构重写文档 - 明确三类团队协作模式：开发、美术、策划 - 详细说明每个目录的职责和使用方式 - 添加团队协作指南和工作流程 - 提供实际的代码示例和配置示例 新增内容: - 团队协作模式说明 (开发/美术/策划) - 详细的目录结构和文件说明 - 开发工作流和版本发布流程 - 最佳实践和规范要求 确保准确性: - 所有目录结构都基于实际项目检查 - 文件路径和命名完全匹配当前状态 - 团队职责划分清晰明确 --- docs/01-项目入门/项目结构说明.md | 813 ++++++++------------- 1 file changed, 321 insertions(+), 492 deletions(-) diff --git a/docs/01-项目入门/项目结构说明.md b/docs/01-项目入门/项目结构说明.md index 461ee0b..f1d7f9e 100644 --- a/docs/01-项目入门/项目结构说明.md +++ b/docs/01-项目入门/项目结构说明.md @@ -1,505 +1,334 @@ -# Godot 项目结构说明 +# WhaleTown 项目结构说明 -本文档详细说明了 whaleTown 项目的文件结构设计，采用"场景+通用工具+其他"的架构模式，确保每个场景清晰独立且高度解耦。 +本文档详细说明了 WhaleTown 项目的文件结构设计，采用分层架构模式，确保团队协作高效且代码结构清晰。 -## 设计理念 +## 🎯 设计理念 ### 核心原则 -- **场景独立性**：每个场景都是独立的功能模块，可以单独开发和测试 -- **高度解耦**：场景之间通过事件系统和管理器进行通信，避免直接依赖 -- **组件复用**：可复用的组件放在通用模块中，提高开发效率 -- **资源管理**：统一的资源管理和命名规范，便于维护 +- **分层架构**：框架层、游戏层、界面层明确分离 +- **团队协作**：策划、美术、开发三类角色各司其职 +- **高度解耦**：通过事件系统实现组件间通信 +- **组件复用**：可复用组件统一管理 +- **标准化**：统一的命名规范和目录结构 -## 项目架构概览 +### 团队协作模式 +- **🎮 开发团队** - 主要工作在 `_Core/`、`scenes/`、`UI/`、`Utils/` +- **🎨 美术团队** - 主要工作在 `assets/` +- **📋 策划团队** - 主要工作在 `Config/` + +## 🏗️ 项目架构概览 ``` -whaleTown/ -├── 🎬 scenes/ # 场景层：独立的游戏场景 -├── 🔧 core/ # 核心层：通用工具和系统 -├── 🎨 assets/ # 资源层：静态资源文件 -├── 📊 data/ # 数据层：配置和游戏数据 -├── 📝 scripts/ # 脚本层：业务逻辑代码 -├── 🧩 module/ # 模块层：可复用组件 -├── 🧪 tests/ # 测试层：单元测试和集成测试 -└── 📚 docs/ # 文档层：项目文档 +WhaleTown/ +├── 🔧 _Core/ # [框架层] 核心系统和管理器 +├── 🎬 scenes/ # [游戏层] 游戏场景和组件 +├── 🎨 UI/ # [界面层] 用户界面 +├── 🖼️ assets/ # [资源层] 美术资源 +├── ⚙️ Config/ # [配置层] 游戏配置和数据 +├── 🛠️ Utils/ # [工具层] 通用工具脚本 +├── 🧪 tests/ # [测试层] 测试文件 +├── 🚀 tools/ # [构建层] 构建和部署工具 +├── 🌐 web_assets/ # [发布层] Web版本资源 +└── 📚 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. 更新导入设置 - --- -## 总结 +## 📁 详细目录结构 -这个项目结构设计遵循了模块化、可扩展、易维护的原则。通过清晰的分层架构和标准化的命名规范，确保了项目的可读性和可维护性。每个开发者都应该遵循这个结构进行开发，以保持项目的一致性和质量。 +### 1. 🔧 框架层 (_Core/) +> **负责团队**: 开发团队 +> **职责**: 游戏底层框架，全局管理器和核心系统 -如有任何疑问或建议，请参考相关文档或联系项目维护者。 \ No newline at end of file +``` +_Core/ +├── managers/ # 全局管理器 +│ ├── GameManager.gd # 游戏状态管理 +│ ├── SceneManager.gd # 场景切换管理 +│ ├── NetworkManager.gd # 网络通信管理 +│ └── ResponseHandler.gd # API响应处理 +└── systems/ # 核心系统 + └── EventSystem.gd # 全局事件系统 +``` + +**特点**: +- 自动加载 (AutoLoad) 单例 +- 全局可访问 +- 与具体游戏逻辑无关 +- 提供基础服务 + +**使用示例**: +```gdscript +# 游戏状态管理 +GameManager.change_state(GameManager.GameState.IN_GAME) + +# 场景切换 +SceneManager.change_scene("main") + +# 事件通信 +EventSystem.emit_event("player_moved", {"position": Vector2(100, 200)}) +``` + +### 2. 🎬 游戏层 (scenes/) +> **负责团队**: 开发团队 +> **职责**: 游戏场景、实体和可复用组件 + +``` +scenes/ +├── Maps/ # 游戏地图场景 +│ ├── main_scene.tscn # 主游戏场景 +│ └── MainScene.gd # 主场景脚本 +└── Components/ # 可复用组件 + ├── characters/ # 角色组件 + ├── effects/ # 特效组件 + ├── items/ # 物品组件 + └── ui/ # UI组件 +``` + +**设计原则**: +- **场景内聚**: 脚本紧邻场景文件存放 +- **组件化**: 可复用组件统一管理 +- **模块化**: 按功能类型分类组织 + +### 3. 🎨 界面层 (UI/) +> **负责团队**: 开发团队 + 美术团队协作 +> **职责**: 用户界面和主题管理 + +``` +UI/ +├── Windows/ # 模态窗口 +│ ├── LoginWindow.tscn # 登录窗口 +│ └── AuthScene.gd # 认证场景脚本 +└── Theme/ # 全局主题 + ├── MainTheme.tres # 主题资源 + └── Fonts/ # 字体文件 + └── msyh.ttc # 微软雅黑字体 +``` + +**组织方式**: +- **Windows/**: 模态窗口和对话框 +- **Theme/**: 统一的UI主题和样式 +- **Fonts/**: 字体资源管理 + +### 4. 🖼️ 资源层 (assets/) +> **负责团队**: 美术团队 +> **职责**: 所有美术资源和素材 + +``` +assets/ +├── sprites/ # 精灵图资源 +│ ├── characters/ # 角色精灵 +│ ├── effects/ # 特效精灵 +│ ├── environment/ # 环境精灵 +│ └── icon/ # 图标资源 +├── audio/ # 音频资源 +│ ├── music/ # 背景音乐 +│ ├── sounds/ # 音效 +│ └── voice/ # 语音 +├── ui/ # UI专用资源 +│ ├── auth/ # 认证界面资源 +│ │ ├── bg_auth_scene.png # 认证背景 +│ │ └── login_frame_smart_transparent.png +│ ├── chinese_theme.tres # 中文主题 +│ └── datawhale_logo.png # 项目Logo +├── fonts/ # 字体文件 +├── materials/ # 材质资源 +└── shaders/ # 着色器 +``` + +**美术团队工作流程**: +1. 按分类将资源放入对应目录 +2. 遵循命名规范 (snake_case) +3. 确保资源格式符合Godot要求 +4. 配置正确的导入设置 (像素艺术使用最近邻过滤) + +### 5. ⚙️ 配置层 (Config/) +> **负责团队**: 策划团队 +> **职责**: 游戏配置、数据和本地化 + +``` +Config/ +├── game_config.json # 游戏主配置 +└── zh_CN.json # 中文本地化 +``` + +**策划团队工作内容**: +- **游戏数值配置**: 角色属性、物品数据、关卡参数 +- **本地化文本**: 多语言文本翻译和管理 +- **游戏平衡**: 数值平衡和游戏性调整 + +**配置文件示例**: +```json +// game_config.json +{ + "player": { + "move_speed": 200.0, + "max_health": 100, + "jump_height": 400.0 + }, + "game": { + "target_fps": 60, + "auto_save_interval": 300 + } +} +``` + +### 6. 🛠️ 工具层 (Utils/) +> **负责团队**: 开发团队 +> **职责**: 通用工具和辅助脚本 + +``` +Utils/ +└── StringUtils.gd # 字符串处理工具 +``` + +**特点**: +- 纯函数，无依赖 +- 可被任何层调用 +- 提供通用功能 + +### 7. 🧪 测试层 (tests/) +> **负责团队**: 开发团队 +> **职责**: 质量保证和自动化测试 + +``` +tests/ +├── api/ # API接口测试 +├── auth/ # 认证功能测试 +├── unit/ # 单元测试 +├── integration/ # 集成测试 +└── performance/ # 性能测试 +``` + +### 8. 🚀 构建层 (tools/) +> **负责团队**: 开发团队/DevOps +> **职责**: 构建脚本和部署工具 + +``` +tools/ +├── build_web.bat # Windows Web构建脚本 +├── build_web.sh # Linux/macOS Web构建脚本 +├── serve_web.bat # Windows 本地服务器 +├── serve_web.sh # Linux/macOS 本地服务器 +└── README.md # 工具使用说明 +``` + +### 9. 🌐 发布层 (web_assets/) +> **负责团队**: 自动生成 +> **职责**: Web版本发布资源 + +``` +web_assets/ +├── index.html # Web版本入口 +├── index.js # Godot Web导出JS +├── index.wasm # WebAssembly文件 +├── index.pck # 游戏资源包 +└── [其他Web资源] # 图标、配置等 +``` + +### 10. 📚 文档层 (docs/) +> **负责团队**: 全体团队 +> **职责**: 项目文档和开发指南 + +``` +docs/ +├── 01-项目入门/ # 新人必读 +├── 02-开发规范/ # 编码标准 +├── 03-技术实现/ # 开发指导 +├── 04-高级开发/ # 进阶技巧 +├── 05-部署运维/ # 发布部署 +└── 06-功能模块/ # 功能文档 +``` + +--- + +## 🤝 团队协作指南 + +### 开发团队 🎮 +**主要工作区域**: `_Core/`, `scenes/`, `UI/`, `Utils/`, `tests/` + +**日常工作流程**: +1. 在 `_Core/` 中开发核心系统和管理器 +2. 在 `scenes/` 中创建游戏场景和组件 +3. 在 `UI/` 中实现用户界面 +4. 在 `Utils/` 中编写通用工具 +5. 在 `tests/` 中编写测试用例 + +**协作要点**: +- 遵循架构设计原则，使用事件系统通信 +- 保持代码模块化和可复用性 +- 及时编写测试和文档 + +### 美术团队 🎨 +**主要工作区域**: `assets/` + +**日常工作流程**: +1. 按分类整理美术资源到 `assets/` 对应目录 +2. 遵循命名规范，使用 snake_case 命名 +3. 配置正确的Godot导入设置 +4. 与开发团队协作调整UI资源 + +**协作要点**: +- 严格按照目录结构组织资源 +- 确保资源格式和质量符合要求 +- 及时与开发团队沟通资源需求 + +### 策划团队 📋 +**主要工作区域**: `Config/` + +**日常工作流程**: +1. 在 `Config/` 中维护游戏配置文件 +2. 管理游戏数值和平衡性调整 +3. 负责本地化文本的翻译和维护 +4. 与开发团队协作实现游戏功能 + +**协作要点**: +- 使用JSON格式编写配置文件 +- 保持配置文件的结构清晰 +- 及时更新本地化文本 + +--- + +## 🔄 开发工作流 + +### 新功能开发流程 +1. **需求分析** - 明确功能需求和设计方案 +2. **架构设计** - 确定涉及的模块和接口 +3. **资源准备** - 美术团队准备相关资源 +4. **配置设置** - 策划团队配置相关数据 +5. **代码实现** - 开发团队实现功能逻辑 +6. **测试验证** - 编写测试用例验证功能 +7. **文档更新** - 更新相关文档说明 + +### 版本发布流程 +1. **功能完成** - 所有计划功能开发完成 +2. **测试通过** - 所有测试用例通过 +3. **资源整理** - 美术资源整理完成 +4. **配置确认** - 策划配置确认无误 +5. **构建发布** - 使用 `tools/` 中的脚本构建 +6. **部署上线** - 部署到目标环境 + +--- + +## 📋 最佳实践 + +### 目录命名规范 +- **文件夹**: 使用 PascalCase (如: `Config/`, `Utils/`) +- **文件**: 使用 snake_case (如: `main_scene.tscn`, `game_config.json`) +- **脚本类**: 使用 PascalCase (如: `GameManager.gd`) + +### 资源管理规范 +- 所有资源必须放在 `assets/` 对应分类目录下 +- 使用描述性的文件名，避免使用数字编号 +- 像素艺术资源必须关闭过滤 (Filter: Off) +- 及时清理不使用的资源文件 + +### 代码组织规范 +- 脚本文件与场景文件放在同一目录 +- 使用事件系统实现模块间通信 +- 保持单一职责原则，避免过度耦合 +- 及时编写注释和文档 + +--- + +**记住：良好的项目结构是团队协作成功的基础！** \ No newline at end of file