moyin
6f545b04e9
主要更新: - 根据实际项目目录结构重写文档 - 明确三类团队协作模式：开发、美术、策划 - 详细说明每个目录的职责和使用方式 - 添加团队协作指南和工作流程 - 提供实际的代码示例和配置示例 新增内容: - 团队协作模式说明 (开发/美术/策划) - 详细的目录结构和文件说明 - 开发工作流和版本发布流程 - 最佳实践和规范要求 确保准确性: - 所有目录结构都基于实际项目检查 - 文件路径和命名完全匹配当前状态 - 团队职责划分清晰明确
334 lines
10 KiB
Markdown
334 lines
10 KiB
Markdown
# 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)
|
|
- 及时清理不使用的资源文件
|
|
|
|
### 代码组织规范
|
|
- 脚本文件与场景文件放在同一目录
|
|
- 使用事件系统实现模块间通信
|
|
- 保持单一职责原则，避免过度耦合
|
|
- 及时编写注释和文档
|
|
|
|
---
|
|
|
|
**记住：良好的项目结构是团队协作成功的基础！** |