whale-town-front/docs/01-项目入门/项目结构说明.md

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) 单例
• 全局可访问
• 与具体游戏逻辑无关
• 提供基础服务

使用示例:

# 游戏状态管理
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                  # 中文本地化

策划团队工作内容:

• 游戏数值配置: 角色属性、物品数据、关卡参数
• 本地化文本: 多语言文本翻译和管理
• 游戏平衡: 数值平衡和游戏性调整

配置文件示例:

// 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)
• 及时清理不使用的资源文件

代码组织规范

• 脚本文件与场景文件放在同一目录
• 使用事件系统实现模块间通信
• 保持单一职责原则，避免过度耦合
• 及时编写注释和文档

---

记住：良好的项目结构是团队协作成功的基础！