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

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) 单例
• 全局可访问的核心功能
• 与具体游戏逻辑无关的底层实现
• 提供基础服务和组件框架

使用示例:

# 游戏状态管理
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等）
• 及时清理不使用的资源文件

代码组织规范

• 脚本文件与场景文件放在同一目录
• 使用事件系统实现模块间通信，避免直接引用
• 保持单一职责原则，避免过度耦合
• 针对像素风游戏优化性能（避免浮点数位置、使用整数坐标）
• 及时编写注释和文档

像素风游戏特殊规范

• 像素完美: 确保所有精灵在整数坐标上渲染
• 统一风格: 保持一致的像素密度和艺术风格
• 性能优化: 使用对象池管理频繁创建销毁的对象
• 分辨率适配: 使用像素完美的缩放方式适配不同分辨率

---

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