# WhaleTown 项目结构说明 本文档详细说明了 WhaleTown 项目的文件结构设计，采用分层架构模式，确保团队协作高效且代码结构清晰。 ## 🎯 设计理念 ### 核心原则 - **分层架构**：框架层、游戏层、界面层明确分离 - **团队协作**：策划、美术、开发三类角色各司其职 - **高度解耦**：通过事件系统实现组件间通信 - **组件复用**：可复用组件统一管理 - **标准化**：统一的命名规范和目录结构 ### 团队协作模式 - **🎮 开发团队** - 主要工作在 `_Core/`、`scenes/`、`UI/`、`Utils/` - **🎨 美术团队** - 主要工作在 `assets/` - **📋 策划团队** - 主要工作在 `Config/` ## 🏗️ 项目架构概览 ``` WhaleTown/ ├── 🔧 _Core/ # [核心层] 功能实现与组件实现，项目最基本的底层实现 ├── 🎬 scenes/ # [场景层] 场景与视觉呈现，包含地图、人物等视觉部分 ├── 🎨 assets/ # [资源层] 静态资源存储，包括图片、音乐、视频、贴图等 ├── ⚙️ Config/ # [配置层] 配置文件管理，用于配置各类环境 ├── 🧪 tests/ # [测试层] 测试文件系统，放置所有组件的测试代码 ├── 🌐 web_assets/ # [发布层] Web导出资源，专门用于Web平台导出 └── 📚 docs/ # [文档层] 项目文档 ``` --- ## 📁 详细目录结构 ### 1. 🔧 核心层 (_Core/) > **负责团队**: 开发团队 > **职责**: 功能实现与组件实现，项目最基本的底层实现 ``` _Core/ ├── managers/ # 全局管理器 │ ├── GameManager.gd # 游戏状态管理 │ ├── SceneManager.gd # 场景切换管理 │ ├── NetworkManager.gd # 网络通信管理 │ └── ResponseHandler.gd # API响应处理 ├── systems/ # 核心系统 │ └── EventSystem.gd # 全局事件系统 ├── components/ # 基础组件实现 │ ├── BaseCharacter.gd # 基础角色组件 │ ├── BaseItem.gd # 基础物品组件 │ └── BaseUI.gd # 基础UI组件 ├── utils/ # 🔨 核心工具类 │ ├── StringUtils.gd # 字符串处理工具 │ ├── MathUtils.gd # 数学计算工具 │ └── PixelUtils.gd # 像素风游戏专用工具 ├── EventNames.gd # 事件名称定义 └── ProjectPaths.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_world.tscn # 主世界地图 │ ├── dungeon_01.tscn # 地牢场景 │ └── town_center.tscn # 城镇中心 ├── characters/ # 人物场景 │ ├── player/ # 玩家角色 │ │ ├── Player.tscn # 玩家场景 │ │ └── Player.gd # 玩家脚本 │ ├── npcs/ # NPC角色 │ └── enemies/ # 敌人角色 ├── ui/ # UI界面场景 │ ├── menus/ # 菜单界面 │ ├── hud/ # 游戏HUD │ └── dialogs/ # 对话框 ├── effects/ # 特效场景 │ ├── particles/ # 粒子效果 │ └── animations/ # 动画效果 └── prefabs/ # 预制体组件 ├── items/ # 物品预制体 └── interactive/ # 交互对象预制体 ``` **设计原则**: - **场景内聚**: 脚本紧邻场景文件存放 - **分类明确**: 按功能类型（地图、人物、UI、特效）分类 - **模块化**: 可复用的预制体统一管理 - **视觉导向**: 主要负责游戏的视觉呈现和UI实现 ### 3. 🎨 资源层 (assets/) > **负责团队**: 美术团队 > **职责**: 所有静态资源的存储，包括图片、音乐、视频、贴图等素材 ``` assets/ ├── sprites/ # 精灵图片资源 │ ├── characters/ # 角色精灵（玩家、NPC、敌人） │ ├── environment/ # 环境精灵（地形、建筑、装饰） │ ├── items/ # 物品精灵（道具、装备、收集品） │ ├── effects/ # 特效精灵（爆炸、魔法、粒子） │ └── ui/ # UI精灵（按钮、图标、边框） ├── audio/ # 音频资源 │ ├── music/ # 背景音乐（BGM） │ ├── sounds/ # 音效（SFX） │ └── voice/ # 语音（对话、旁白） ├── fonts/ # 字体文件 │ ├── pixel_fonts/ # 像素风字体 │ └── ui_fonts/ # UI专用字体 ├── materials/ # 材质资源 │ ├── pixel_materials/ # 像素风材质 │ └── shader_materials/ # 着色器材质 ├── shaders/ # 着色器文件 │ ├── pixel_shaders/ # 像素风着色器 │ └── effect_shaders/ # 特效着色器 ├── ui/ # UI专用资源 │ ├── themes/ # UI主题 │ ├── icons/ # 图标资源 │ └── backgrounds/ # 背景图片 └── icon/ # 应用图标 ├── icon.svg # 矢量图标 └── icon.png # 位图图标 ``` **像素风游戏资源特点**: - **像素完美**: 所有精灵使用像素完美设置（Filter: Off, Mipmaps: Off） - **统一风格**: 保持一致的像素密度和调色板 - **分辨率标准**: 建议使用16x16、32x32等标准像素尺寸 - **动画帧**: 角色动画使用精灵表（Sprite Sheet）组织 ### 4. ⚙️ 配置层 (Config/) > **负责团队**: 策划团队 > **职责**: 配置文件管理，主要用来配置各类环境 ``` Config/ ├── game_config.json # 游戏主配置 ├── zh_CN.json # 中文本地化 ├── environment/ # 环境配置 │ ├── development.json # 开发环境配置 │ ├── testing.json # 测试环境配置 │ └── production.json # 生产环境配置 ├── gameplay/ # 游戏玩法配置 │ ├── character_stats.json # 角色属性配置 │ ├── item_database.json # 物品数据库 │ └── level_config.json # 关卡配置 └── localization/ # 本地化配置 ├── en_US.json # 英文本地化 ├── zh_CN.json # 中文本地化 └── ja_JP.json # 日文本地化 ``` **配置文件特点**: - **环境分离**: 开发、测试、生产环境配置分离 - **数据驱动**: 游戏数值通过配置文件控制 - **本地化支持**: 多语言文本管理 - **热更新**: 支持运行时配置更新 ### 5. 🧪 测试层 (tests/) > **负责团队**: 开发团队 > **职责**: 测试文件系统，放置所有对应组件的测试代码，方便快速进行功能性与性能测试 ``` tests/ ├── unit/ # 单元测试 │ ├── core/ # 核心组件测试 │ ├── characters/ # 角色组件测试 │ └── systems/ # 系统功能测试 ├── integration/ # 集成测试 │ ├── scene_transitions/ # 场景切换测试 │ ├── save_load/ # 存档系统测试 │ └── network/ # 网络功能测试 ├── performance/ # 性能测试 │ ├── framerate/ # 帧率测试 │ ├── memory/ # 内存使用测试 │ └── loading_times/ # 加载时间测试 ├── api/ # API接口测试 │ ├── auth_tests.py # 认证接口测试 │ └── game_api_tests.py # 游戏API测试 └── ui/ # UI功能测试 ├── menu_tests/ # 菜单测试 └── dialog_tests/ # 对话框测试 ``` **测试类型说明**: - **单元测试**: 测试单个组件的功能正确性 - **集成测试**: 测试组件间的交互和协作 - **性能测试**: 监控游戏性能指标，确保流畅运行 - **API测试**: 验证网络接口的正确性和稳定性 - **UI测试**: 测试用户界面的交互和响应 ### 6. 🌐 Web导出层 (web_assets/) > **负责团队**: 自动生成 > **职责**: Web导出资源，专门用于Web平台导出的相关资源和配置文件 ``` web_assets/ ├── html/ # HTML模板文件 │ ├── index.html # Web版本入口页面 │ └── loading.html # 加载页面模板 ├── css/ # 样式文件 │ ├── game.css # 游戏样式 │ └── loading.css # 加载样式 ├── js/ # JavaScript脚本 │ ├── game_loader.js # 游戏加载器 │ └── utils.js # 工具函数 ├── icons/ # Web应用图标 │ ├── favicon.ico # 网站图标 │ └── app_icons/ # PWA应用图标 └── config/ # Web配置文件 ├── manifest.json # PWA清单文件 └── service-worker.js # 服务工作者 ``` **Web导出特点**: - **PWA支持**: 支持渐进式Web应用功能 - **响应式设计**: 适配不同屏幕尺寸 - **加载优化**: 优化资源加载和缓存策略 - **跨平台兼容**: 确保在各种浏览器中正常运行 ### 7. 📚 文档层 (docs/) > **负责团队**: 全体团队 > **职责**: 项目文档和开发指南 ``` docs/ ├── 01-项目入门/ # 新人必读文档 ├── 02-开发规范/ # 编码标准文档 ├── 03-技术实现/ # 开发指导文档 ├── 04-高级开发/ # 进阶技巧文档 ├── 05-部署运维/ # 发布部署文档 ├── 06-功能模块/ # 功能文档 └── AI_docs/ # 🤖 AI专用文档 ├── README.md # AI文档总览 ├── architecture_guide.md # 架构执行指南 ├── coding_standards.md # 代码风格规范 ├── templates/ # 代码模板库 │ ├── components.md # 组件模板集合 │ ├── managers.md # 管理器模板集合 │ └── ui_templates.md # UI模板集合 ├── workflows/ # 工作流程指南 │ ├── feature_development.md # 功能开发流程 │ ├── bug_fixing.md # Bug修复流程 │ └── testing_workflow.md # 测试执行流程 └── quick_reference/ # 快速参考手册 ├── code_snippets.md # 常用代码片段 ├── api_reference.md # API快速参考 └── troubleshooting.md # 故障排除指南 ``` **AI_docs特点**: - **结构化执行**: 每个文档都包含可直接执行的步骤和代码模板 - **标准化规范**: 为AI编程助手提供统一的开发标准和最佳实践 - **模板驱动**: 提供完整的代码模板，确保代码一致性和质量 - **工作流导向**: 包含详细的开发工作流程，提升AI协作效率 ``` docs/ ├── 01-项目入门/ # 新人必读 ├── 02-开发规范/ # 编码标准 ├── 03-技术实现/ # 开发指导 ├── 04-高级开发/ # 进阶技巧 ├── 05-部署运维/ # 发布部署 └── 06-功能模块/ # 功能文档 ``` --- ## 🤝 团队协作指南 ### 开发团队 🎮 **主要工作区域**: `_Core/`, `scenes/`, `tests/` **日常工作流程**: 1. 在 `_Core/` 中开发核心系统、管理器、基础组件和工具类 2. 在 `scenes/` 中创建游戏场景、角色、UI界面和特效 3. 在 `tests/` 中编写各类测试用例确保代码质量 **协作要点**: - 遵循架构设计原则，使用事件系统进行模块通信 - 保持代码模块化和可复用性 - 将通用工具类放在 `_Core/utils/` 中统一管理 - 针对像素风游戏特点优化性能 - 及时编写测试和文档 ### 美术团队 🎨 **主要工作区域**: `assets/` **日常工作流程**: 1. 按分类整理美术资源到 `assets/` 对应目录 2. 确保像素艺术风格的一致性和像素完美 3. 配置正确的Godot导入设置（关闭过滤、禁用Mipmaps） 4. 与开发团队协作调整UI和游戏资源 **像素风游戏特殊要求**: - 严格遵循像素完美原则 - 保持统一的像素密度和调色板 - 使用标准像素尺寸（16x16、32x32等） - 精灵动画使用精灵表组织 ### 策划团队 📋 **主要工作区域**: `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, Mipmaps: Off) - 保持统一的像素密度和调色板 - 使用标准像素尺寸（16x16、32x32、64x64等） - 及时清理不使用的资源文件 ### 代码组织规范 - 脚本文件与场景文件放在同一目录 - 使用事件系统实现模块间通信，避免直接引用 - 保持单一职责原则，避免过度耦合 - 针对像素风游戏优化性能（避免浮点数位置、使用整数坐标） - 及时编写注释和文档 ### 像素风游戏特殊规范 - **像素完美**: 确保所有精灵在整数坐标上渲染 - **统一风格**: 保持一致的像素密度和艺术风格 - **性能优化**: 使用对象池管理频繁创建销毁的对象 - **分辨率适配**: 使用像素完美的缩放方式适配不同分辨率 --- **记住：良好的项目结构是团队协作成功的基础！**