# WhaleTown 项目结构说明 本文档详细说明了 WhaleTown 项目的文件结构设计，采用分层架构模式，确保团队协作高效且代码结构清晰。 ## 🎯 设计理念 ### 核心原则 - **分层架构**：框架层、游戏层、界面层明确分离 - **团队协作**：策划、美术、开发三类角色各司其职 - **高度解耦**：通过事件系统实现组件间通信 - **组件复用**：可复用组件统一管理 - **标准化**：统一的命名规范和目录结构 ### 团队协作模式 - **🎮 开发团队** - 主要工作在 `_Core/`、`scenes/`、`UI/`、`Utils/` - **🎨 美术团队** - 主要工作在 `assets/` - **📋 策划团队** - 主要工作在 `Config/` ## 🏗️ 项目架构概览 ``` WhaleTown/ ├── 🔧 _Core/ # [框架层] 核心系统和管理器 ├── 🎬 scenes/ # [游戏层] 游戏场景和组件 ├── 🎨 UI/ # [界面层] 用户界面 ├── 🖼️ assets/ # [资源层] 美术资源 ├── ⚙️ Config/ # [配置层] 游戏配置和数据 ├── 🛠️ Utils/ # [工具层] 通用工具脚本 ├── 🧪 tests/ # [测试层] 测试文件 ├── 🚀 tools/ # [构建层] 构建和部署工具 ├── 🌐 web_assets/ # [发布层] Web版本资源 └── 📚 docs/ # [文档层] 项目文档 ``` --- ## 📁 详细目录结构 ### 1. 🔧 框架层 (_Core/) > **负责团队**: 开发团队 > **职责**: 游戏底层框架，全局管理器和核心系统 ``` _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) - 及时清理不使用的资源文件 ### 代码组织规范 - 脚本文件与场景文件放在同一目录 - 使用事件系统实现模块间通信 - 保持单一职责原则，避免过度耦合 - 及时编写注释和文档 --- **记住：良好的项目结构是团队协作成功的基础！**