forked from datawhale/whale-town-front
393 lines
16 KiB
Markdown
393 lines
16 KiB
Markdown
# 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/
|
||
├── MainScene.tscn # 🎯 主入口场景 - 所有图像显示的入口文件
|
||
├── MainScene.gd # 主场景控制器脚本
|
||
├── 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等）
|
||
- 及时清理不使用的资源文件
|
||
|
||
### 代码组织规范
|
||
- 脚本文件与场景文件放在同一目录
|
||
- 使用事件系统实现模块间通信，避免直接引用
|
||
- 保持单一职责原则，避免过度耦合
|
||
- 针对像素风游戏优化性能（避免浮点数位置、使用整数坐标）
|
||
- 及时编写注释和文档
|
||
|
||
### 像素风游戏特殊规范
|
||
- **像素完美**: 确保所有精灵在整数坐标上渲染
|
||
- **统一风格**: 保持一致的像素密度和艺术风格
|
||
- **性能优化**: 使用对象池管理频繁创建销毁的对象
|
||
- **分辨率适配**: 使用像素完美的缩放方式适配不同分辨率
|
||
|
||
---
|
||
|
||
**记住：良好的项目结构是团队协作成功的基础！** |