From fca3eb79ddf844cae2f2f0984b00c2805640a033 Mon Sep 17 00:00:00 2001 From: moyin <2443444649@qq.com> Date: Fri, 2 Jan 2026 00:57:53 +0800 Subject: [PATCH] =?UTF-8?q?chore=EF=BC=9A=E6=B8=85=E7=90=86=E4=B8=B4?= =?UTF-8?q?=E6=97=B6=E6=96=87=E6=A1=A3=E6=96=87=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 删除迁移完成标记文件 MIGRATION_COMPLETE.md - 删除重构说明文件 REFACTORING.md - 删除结构对比文件 STRUCTURE_COMPARISON.md - 删除临时文档 cloude.md --- MIGRATION_COMPLETE.md | 235 ---------------------------------------- REFACTORING.md | 222 ------------------------------------- STRUCTURE_COMPARISON.md | 213 ------------------------------------ cloude.md | 123 --------------------- 4 files changed, 793 deletions(-) delete mode 100644 MIGRATION_COMPLETE.md delete mode 100644 REFACTORING.md delete mode 100644 STRUCTURE_COMPARISON.md delete mode 100644 cloude.md diff --git a/MIGRATION_COMPLETE.md b/MIGRATION_COMPLETE.md deleted file mode 100644 index c4b7123..0000000 --- a/MIGRATION_COMPLETE.md +++ /dev/null @@ -1,235 +0,0 @@ -# ✅ 项目结构重构完成报告 - -## 📅 完成时间 -2025-12-31 - -## 🎉 重构成功 - -项目已成功从混乱的文件结构重构为清晰、模块化的架构! - ---- - -## 📊 最终结构总览 - -``` -whale-town-front/ -├── _Core/ ✅ [框架层] 全局单例和系统 -├── Scenes/ ✅ [玩法层] 游戏世界实体 -├── UI/ ✅ [界面层] 所有UI界面 -├── Assets/ ✅ [资源层] 美术资源 -├── Config/ ✅ [配置层] 静态数据 -├── Utils/ ✅ [工具层] 工具类 -├── Tests/ ✅ [测试层] 测试脚本 -└── docs/ 📄 项目文档 -``` - ---- - -## ✅ 已完成的迁移 - -### 1️⃣ 框架层 (_Core/) -- ✅ `GameManager.gd` → `_Core/managers/` -- ✅ `SceneManager.gd` → `_Core/managers/` (已更新路径) -- ✅ `NetworkManager.gd` → `_Core/managers/` -- ✅ `ResponseHandler.gd` → `_Core/managers/` -- ✅ `EventSystem.gd` → `_Core/systems/` - -### 2️⃣ 场景层 (Scenes/) -- ✅ `scenes/main_scene.tscn` → `Scenes/Maps/main_scene.tscn` -- ✅ `scripts/scenes/MainScene.gd` → `Scenes/Maps/MainScene.gd` -- ✅ `scenes/prefabs/` → `Scenes/Components/` - -### 3️⃣ 界面层 (UI/) -- ✅ `scenes/auth_scene.tscn` → `UI/Windows/LoginWindow.tscn` -- ✅ `scripts/scenes/AuthScene.gd` → `UI/Windows/AuthScene.gd` -- ✅ `assets/ui/chinese_theme.tres` → `UI/Theme/MainTheme.tres` -- ✅ `assets/fonts/` → `UI/Theme/Fonts/` - -### 4️⃣ 配置层 (Config/) -- ✅ `data/configs/game_config.json` → `Config/game_config.json` -- ✅ `data/localization/zh_CN.json` → `Config/zh_CN.json` - -### 5️⃣ 工具层 (Utils/) -- ✅ `core/utils/StringUtils.gd` → `Utils/StringUtils.gd` - -### 6️⃣ 资源层 (Assets/) -- ✅ `assets/sprites/` → `Assets/Sprites/` -- ✅ `assets/audio/` → `Assets/Audio/` -- ✅ 其他资源文件保留在 `assets/`(待后续整理) - -### 7️⃣ 构建脚本 -- ✅ `scripts/build_web.sh` → `./build_web.sh` -- ✅ `scripts/serve_web.sh` → `./serve_web.sh` - ---- - -## 🗑️ 已删除的旧目录 - -- ❌ `core/` - 已迁移到 `_Core/` -- ❌ `module/` - 空目录,未使用 -- ❌ `scripts/` - 脚本已内联到场景目录 -- ❌ `scenes/` - 已迁移到 `Scenes/` 和 `UI/` -- ❌ `data/` - 配置已移至 `Config/` - ---- - -## 🔧 已更新的配置 - -### project.godot -```ini -✅ run/main_scene="res://Scenes/Maps/main_scene.tscn" -✅ GameManager="*res://_Core/managers/GameManager.gd" -✅ SceneManager="*res://_Core/managers/SceneManager.gd" -✅ EventSystem="*res://_Core/systems/EventSystem.gd" -✅ NetworkManager="*res://_Core/managers/NetworkManager.gd" -✅ ResponseHandler="*res://_Core/managers/ResponseHandler.gd" -``` - -### SceneManager.gd -```gdscript -✅ "main": "res://Scenes/Maps/main_scene.tscn" -✅ "auth": "res://UI/Windows/LoginWindow.tscn" -``` - -### 测试文件 -```gdscript -✅ tests/auth/enhanced_toast_test.gd - 已更新脚本路径 -✅ tests/auth/auth_ui_test.tscn - 已更新场景路径 -``` - ---- - -## 📚 创建的文档 - -1. **REFACTORING.md** - 详细的重构文档 - - 迁移映射表 - - 设计原则 - - 注意事项 - - 后续建议 - -2. **STRUCTURE_COMPARISON.md** - 结构对比分析 - - 旧结构问题分析 - - 新结构优势说明 - - 对比表格 - - 团队协作改进 - ---- - -## 🎯 关键改进 - -### 清晰的分层 -- **_Core**: 框架代码,全局系统 -- **Scenes**: 游戏世界,地图和实体 -- **UI**: 所有界面,HUD和弹窗 -- **Config**: 静态数据,策划可编辑 -- **Utils**: 通用工具函数库 - -### 组件化设计 -```gdscript -Scenes/Components/ // 可复用组件 -├── characters/ // 角色预制体 -├── effects/ // 特效预制体 -├── items/ // 物品预制体 -└── ui/ // UI预制体 -``` - -### 场景内聚 -- 每个 `.tscn` 配套一个 `.gd` -- 脚本紧邻场景文件 -- 符合 Godot 原生习惯 - -### UI 独立化 -``` -UI/ -├── Windows/ // 模态窗口(登录、设置) -├── HUD/ // 常驻界面(聊天框) -├── Dialog/ // 对话系统 -└── Theme/ // 全局样式 -``` - ---- - -## ⚠️ 后续步骤 - -### 必做事项 -- [ ] 在 Godot 编辑器中打开项目,让编辑器重新索引文件 -- [ ] 测试主场景加载: `Scenes/Maps/main_scene.tscn` -- [ ] 验证登录窗口: `UI/Windows/LoginWindow.tscn` -- [ ] 测试所有自动加载脚本 -- [ ] 运行完整测试套件 - -### 建议优化 -- [ ] 补充 `Scenes/Components/` 下的可复用组件 -- [ ] 完善 `UI/HUD/` 和 `UI/Dialog/` -- [ ] 添加 `Scenes/Entities/Player/` 玩家实体 -- [ ] 将硬编码数值移至 `Config/` - -### 代码审查 -- [ ] 检查是否还有硬编码的旧路径 -- [ ] 验证所有 `.import` 文件正常 -- [ ] 确认网络连接功能正常 -- [ ] 验证 UI 主题显示正确 - ---- - -## 🎓 团队协作指南 - -### 工作目录划分 -``` -🎨 美术组 → Assets/Sprites/, Assets/Audio/ -📋 策划组 → Config/ -💻 前端程序 → UI/, Scenes/Entities/ -⚙️ 后端程序 → _Core/, Utils/ -🧪 测试组 → Tests/ -``` - -### Git 提交建议 -```bash -# 按目录分类提交 -git add _Core/ -git commit -m "refactor: 迁移核心框架代码到 _Core/" - -git add Scenes/ -git commit -m "refactor: 重组场景文件到 Scenes/" - -git add UI/ -git commit -m "refactor: 独立 UI 界面到 UI/" -``` - ---- - -## 📈 预期收益 - -### 可维护性提升 -- 🟢 目录职责清晰,降低认知负担 -- 🟢 新人快速定位文件 -- 🟢 减少代码冲突 - -### 开发效率提升 -- 🟢 组件复用更容易 -- 🟢 团队协作更流畅 -- 🟢 代码审查更高效 - -### 符合最佳实践 -- ✅ Godot 官方推荐结构 -- ✅ 场景内聚原则 -- ✅ 组件化设计思想 -- ✅ 配置与代码分离 - ---- - -## 🎉 总结 - -**重构完成!** 项目现在拥有: -- ✅ 清晰的 6 层架构 -- ✅ 符合 Godot 最佳实践 -- ✅ 易于维护和扩展 -- ✅ 团队协作友好 - -感谢您的耐心!如有问题,请查看详细文档: -- [REFACTORING.md](./REFACTORING.md) - 重构详情 -- [STRUCTURE_COMPARISON.md](./STRUCTURE_COMPARISON.md) - 结构对比 - ---- - -**下一步:在 Godot 编辑器中打开项目并测试!** 🚀 diff --git a/REFACTORING.md b/REFACTORING.md deleted file mode 100644 index ecad018..0000000 --- a/REFACTORING.md +++ /dev/null @@ -1,222 +0,0 @@ -# 项目结构重构文档 - -## 📅 重构时间 -2025-12-31 - -## 🎯 重构目标 -将项目从混乱的文件结构重构为清晰、模块化的架构,采用 Godot 最佳实践。 - -## 📊 重构前后对比 - -### 旧结构问题 -``` -❌ core/ - 概念模糊,混合了框架和业务逻辑 -❌ module/ - 空壳目录,设计未落地 -❌ scripts/ - 与 scenes/ 重复,脚本分散 -❌ scenes/ - 场景、预制体、脚本混在一起 -❌ data/ - 配置和运行时数据不分 -``` - -### 新结构优势 -``` -✅ _Core/ - 框架层:全局单例和系统 -✅ Scenes/ - 玩法层:按游戏世界组织 -✅ UI/ - 界面层:独立的UI管理 -✅ Assets/ - 资源层:纯美术资源 -✅ Config/ - 配置层:静态数据 -✅ Utils/ - 工具层:通用函数库 -``` - -## 🏗️ 新的目录结构 - -``` -res:// -├── _Core/ # [框架层] 游戏的底层框架,单例,全局管理器 -│ ├── managers/ # 游戏管理器 -│ │ ├── GameManager.gd # 游戏状态管理 -│ │ ├── SceneManager.gd # 场景管理(已更新路径) -│ │ ├── NetworkManager.gd # 网络通信 -│ │ └── ResponseHandler.gd # API响应处理 -│ ├── systems/ # 核心系统 -│ │ └── EventSystem.gd # 事件系统 -│ └── singletons/ # 其他单例(待扩展) -│ -├── Scenes/ # [玩法层] 具体的游戏场景、实体、地图 -│ ├── Maps/ # 地图场景 -│ │ └── main_scene.tscn # 主游戏场景 -│ ├── Entities/ # 游戏实体 -│ │ ├── Player/ # 玩家实体 -│ │ ├── NPC/ # NPC实体 -│ │ └── Interactables/ # 交互物 -│ └── Components/ # 可复用组件 -│ -├── UI/ # [界面层] 所有UI相关的预制体和逻辑 -│ ├── HUD/ # 抬头显示(常驻) -│ ├── Windows/ # 模态窗口 -│ │ └── LoginWindow.tscn # 登录窗口(原auth_scene.tscn) -│ ├── Dialog/ # 对话系统 -│ └── Theme/ # 全局样式 -│ ├── MainTheme.tres # 主主题 -│ └── Fonts/ # 字体文件 -│ -├── Assets/ # [资源层] 美术、音频、字体 -│ ├── Sprites/ # 精灵图 -│ ├── Audio/ # 音频 -│ └── Fonts/ # 字体 -│ -├── Config/ # [配置层] 游戏配置文件 -│ ├── game_config.json # 游戏配置 -│ └── zh_CN.json # 中文本地化 -│ -├── Utils/ # [工具层] 通用辅助脚本 -│ └── StringUtils.gd # 字符串工具 -│ -└── Tests/ # [测试层] 单元测试脚本 - ├── api/ # API测试 - ├── auth/ # 认证测试 - ├── integration/ # 集成测试 - ├── performance/ # 性能测试 - └── unit/ # 单元测试 -``` - -## 🔄 迁移映射表 - -| 旧路径 | 新路径 | 说明 | -|--------|--------|------| -| `core/managers/*` | `_Core/managers/` | 框架层管理器 | -| `core/systems/*` | `_Core/systems/` | 框架层系统 | -| `core/utils/*` | `Utils/` | 工具类 | -| `scenes/main_scene.tscn` | `Scenes/Maps/main_scene.tscn` | 主游戏场景 | -| `scenes/auth_scene.tscn` | `UI/Windows/LoginWindow.tscn` | 登录窗口 | -| `data/configs/*.json` | `Config/` | 配置文件 | -| `data/localization/*.json` | `Config/` | 本地化配置 | -| `assets/ui/chinese_theme.tres` | `UI/Theme/MainTheme.tres` | UI主题 | -| `assets/fonts/*` | `UI/Theme/Fonts/` | 字体文件 | - -## ✂️ 已删除的目录 - -- ❌ `core/` - 已迁移到 `_Core/` -- ❌ `module/` - 空目录,未使用 -- ❌ `scripts/` - 脚本应内联到场景目录 -- ❌ `scenes/` - 已迁移到 `Scenes/` 和 `UI/` -- ❌ `data/` - 配置已移至 `Config/` - -## 🔧 已更新的配置文件 - -### project.godot -```ini -# 更新主场景路径 -run/main_scene="res://Scenes/Maps/main_scene.tscn" - -# 更新自动加载路径 -GameManager="*res://_Core/managers/GameManager.gd" -SceneManager="*res://_Core/managers/SceneManager.gd" -EventSystem="*res://_Core/systems/EventSystem.gd" -NetworkManager="*res://_Core/managers/NetworkManager.gd" -ResponseHandler="*res://_Core/managers/ResponseHandler.gd" -``` - -### SceneManager.gd -```gdscript -# 更新场景路径映射 -var scene_paths: Dictionary = { - "main": "res://Scenes/Maps/main_scene.tscn", - "auth": "res://UI/Windows/LoginWindow.tscn", - # ... 其他场景路径 -} -``` - -### 测试文件 -- `tests/auth/enhanced_toast_test.gd` - 已更新脚本路径 -- `tests/auth/auth_ui_test.tscn` - 已更新场景路径 - -## 🎨 设计原则 - -### 1. 清晰的分层 -- **_Core**: 框架代码,与具体游戏逻辑无关 -- **Scenes**: 游戏世界,地图和实体 -- **UI**: 所有界面,HUD和弹窗 -- **Config**: 静态数据,策划可编辑 - -### 2. 组件化设计 -```gdscript -# 可复用组件放在 Scenes/Components/ -Scenes/Components/ -├── InteractableArea.tscn # 让任何物体"可交互" -├── MovementSync.gd # 网络位置同步 -└── NameTag3D.tscn # 头顶名字条 -``` - -### 3. 场景内聚 -- 每个 .tscn 配套一个 .gd -- 脚本紧邻场景文件存放 -- 符合 Godot 原生开发习惯 - -### 4. 职责单一 -``` -UI/Windows/ - 模态窗口(登录、设置、商店) -UI/HUD/ - 常驻界面(聊天框、状态栏) -UI/Dialog/ - 对话系统 -``` - -## 🚀 后续建议 - -### 待完善的功能 -1. **组件化开发** - - 创建 `Scenes/Components/` 下的可复用组件 - - 使用组合优于继承的设计模式 - -2. **UI 独立化** - - 补充 `UI/HUD/` 下的常驻界面 - - 创建 `UI/Dialog/` 对话系统 - -3. **场景管理** - - 补充更多地图场景到 `Scenes/Maps/` - - 添加玩家实体到 `Scenes/Entities/Player/` - -4. **配置驱动** - - 将硬编码的数值移到 `Config/` - - 使用 Resource 文件管理游戏数据 - -### 团队协作 -- **美术组**: 主要在 `Assets/` 工作 -- **策划组**: 主要在 `Config/` 工作 -- **程序组**: 主要在 `_Core/`, `Scenes/`, `UI/` 工作 -- **测试组**: 主要在 `Tests/` 工作 - -## 📝 迁移检查清单 - -- [x] 创建新的目录结构 -- [x] 迁移核心管理器 -- [x] 迁移工具类 -- [x] 迁移场景文件 -- [x] 分离 UI 界面 -- [x] 迁移配置文件 -- [x] 重组资源文件 -- [x] 更新 project.godot -- [x] 更新路径引用 -- [x] 清理旧目录 -- [ ] 在 Godot 编辑器中测试场景加载 -- [ ] 验证所有自动加载脚本正常工作 -- [ ] 测试网络连接功能 -- [ ] 验证 UI 主题显示 - -## ⚠️ 注意事项 - -1. **场景引用更新**: 所有旧场景的引用都已更新,但建议在 Godot 编辑器中重新打开项目,让编辑器重新索引文件 - -2. **.import 文件**: 移动资源文件后,Godot 可能会重新生成 .import 文件,这是正常的 - -3. **版本控制**: 如果使用 Git,旧文件的删除会在下次提交时体现 - -4. **测试覆盖**: 迁移后建议运行完整的测试套件确保功能正常 - -## 🎓 参考资料 - -- [Godot 官方项目组织建议](https://docs.godotengine.org/en/stable/tutorials/best_practices/project_organization.html) -- [GDScript 场景组织](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_basics.html#scenes-and-scripts) -- [ECS 架构模式](https://github.com/SmitUS/Pine-Tree-ECS-For-Godot-4) - ---- - -**重构完成!项目现在拥有清晰的架构,易于维护和扩展。** 🎉 diff --git a/STRUCTURE_COMPARISON.md b/STRUCTURE_COMPARISON.md deleted file mode 100644 index 37001d3..0000000 --- a/STRUCTURE_COMPARISON.md +++ /dev/null @@ -1,213 +0,0 @@ -# 🏗️ 项目结构对比 - -## 旧结构 ❌ -``` -whale-town-front/ -├── core/ # ❌ 概念模糊 -│ ├── managers/ # - 框架代码? -│ ├── systems/ # - 还是业务逻辑? -│ └── utils/ # - 边界不清 -├── module/ # ❌ 空壳目录(无 .gd 文件) -│ ├── Character/ -│ ├── Combat/ -│ ├── Dialogue/ -│ ├── Inventory/ -│ └── UI/ -├── scenes/ # ❌ 混乱的组织 -│ ├── auth_scene.tscn -│ ├── main_scene.tscn -│ ├── Components/ -│ ├── Entities/ -│ ├── Maps/ -│ └── prefabs/ -├── scripts/ # ❌ 与 scenes/ 重复 -│ ├── characters/ -│ ├── scenes/ -│ ├── ui/ -│ └── network/ -├── data/ # ❌ 配置和数据混在一起 -│ ├── configs/ -│ ├── characters/ -│ ├── dialogues/ -│ └── localization/ -├── assets/ # ✅ 相对清晰 -│ ├── audio/ -│ ├── fonts/ -│ ├── icon/ -│ ├── materials/ -│ ├── shaders/ -│ ├── sprites/ -│ └── ui/ -├── tests/ # ✅ 结构良好 -│ ├── api/ -│ ├── auth/ -│ ├── integration/ -│ ├── performance/ -│ └── unit/ -└── docs/ -``` - -**问题总结:** -1. 🔴 脚本分散:`scripts/` 和 `scenes/` 都有脚本,职责不清 -2. 🔴 空壳模块:`module/` 目录存在但无实际代码 -3. 🔴 场景混乱:场景文件、预制体、脚本平级放置 -4. 🔴 分层不明:`core/`, `module/`, `scripts/` 三层交叉 -5. 🔴 数据混杂:`data/` 既包含配置也包含运行时数据 - ---- - -## 新结构 ✅ -``` -whale-town-front/ -├── _Core/ # ✅ 框架层 - 清晰的单例和系统 -│ ├── managers/ # - 全局管理器 -│ ├── systems/ # - 核心系统 -│ └── singletons/ # - 其他单例 -│ -├── Scenes/ # ✅ 玩法层 - 按游戏世界组织 -│ ├── Maps/ # - 地图场景 -│ │ └── main_scene.tscn -│ ├── Entities/ # - 游戏实体 -│ │ ├── Player/ # - 玩家 -│ │ ├── NPC/ # - NPC -│ │ └── Interactables/ # - 交互物 -│ └── Components/ # - 可复用组件 -│ -├── UI/ # ✅ 界面层 - 独立的UI管理 -│ ├── HUD/ # - 抬头显示(常驻) -│ ├── Windows/ # - 模态窗口 -│ │ └── LoginWindow.tscn # (原 auth_scene) -│ ├── Dialog/ # - 对话系统 -│ └── Theme/ # - 全局样式 -│ ├── MainTheme.tres -│ └── Fonts/ -│ -├── Assets/ # ✅ 资源层 - 纯美术资源 -│ ├── Sprites/ # - 精灵图 -│ ├── Audio/ # - 音频 -│ └── Fonts/ # - 字体 -│ -├── Config/ # ✅ 配置层 - 静态数据 -│ ├── game_config.json -│ └── zh_CN.json -│ -├── Utils/ # ✅ 工具层 - 通用函数库 -│ └── StringUtils.gd -│ -├── Tests/ # ✅ 测试层 - 完整的测试覆盖 -│ ├── api/ -│ ├── auth/ -│ ├── integration/ -│ ├── performance/ -│ └── unit/ -│ -└── docs/ # 📄 项目文档 - └── web_deployment_guide.md -``` - -**改进总结:** -1. 🟢 **分层清晰**: 框架、玩法、界面、资源、配置、工具各司其职 -2. 🟢 **场景内聚**: .tscn 和 .gd 成对出现,逻辑紧耦合场景 -3. 🟢 **UI 独立**: 所有界面统一管理,避免和游戏场景混淆 -4. 🟢 **配置分离**: Config 只存放静态数据,策划可直接编辑 -5. 🟢 **组件化**: Scenes/Components/ 提供可复用的逻辑组件 - ---- - -## 📊 核心改进对比表 - -| 维度 | 旧结构 | 新结构 | 改进效果 | -|:---:|:---:|:---:|:---:| -| **目录层级** | 8层 | 6层 | ✅ 更扁平 | -| **脚本管理** | 分散在2处 | 集中在场景内 | ✅ 内聚性高 | -| **UI 组织** | 混在 scenes/ | 独立 UI/ | ✅ 职责清晰 | -| **框架代码** | core/ 概念模糊 | _Core/ 明确 | ✅ 边界清楚 | -| **配置管理** | data/ 混杂 | Config/ 专职 | ✅ 策划友好 | -| **可维护性** | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ✅ 提升67% | -| **学习曲线** | ⭐⭐ | ⭐⭐⭐⭐ | ✅ 新人友好 | - ---- - -## 🎯 Godot 最佳实践对照 - -### ✅ 符合 Godot 规范 -- [x] 场景脚本内聚(.tscn + .gd 相邻) -- [x] 使用 autoload 全局单例 -- [x] 组件化设计(可复用的 Components/) -- [x] 资源独立管理(Assets/) -- [x] 配置与代码分离(Config/) - -### 🔧 待完善项 -- [ ] 补充 Scenes/Components/ 下的可复用组件 -- [ ] 完善事件系统的使用 -- [ ] 添加 SaveSystem 到 _Core/systems/ -- [ ] 实现资源热重载机制 - ---- - -## 📈 团队协作改进 - -### 角色与目录对应 -``` -┌─────────────────┬─────────────────────────────────┐ -│ 角色 │ 主要工作目录 │ -├─────────────────┼─────────────────────────────────┤ -│ 🎨 美术组 │ Assets/Sprites/, Assets/Audio/ │ -│ 📋 策划组 │ Config/ │ -│ 💻 前端程序 │ UI/, Scenes/Entities/ │ -│ ⚙️ 后端程序 │ _Core/, Utils/ │ -│ 🧪 测试组 │ Tests/ │ -└─────────────────┴─────────────────────────────────┘ -``` - -### 协作优势 -1. **减少冲突**: 不同角色在不同目录工作 -2. **职责清晰**: 每个目录有明确的负责人 -3. **易于审查**: PR 可以按目录分类评审 -4. **快速定位**: 新人快速找到相关文件 - ---- - -## 🚀 扩展性对比 - -### 旧结构的扩展问题 -```gdscript -// 添加新功能时需要在多个地方修改 -module/FeatureName/ // ❌ 需要创建 -scenes/feature_scene/ // ❌ 需要创建 -scripts/feature_logic/ // ❌ 需要创建 -data/feature_config/ // ❌ 需要创建 -``` - -### 新结构的扩展方式 -```gdscript -// 添加新功能只需要: -Scenes/Entities/NewFeature/ // ✅ 场景+逻辑一体 -Config/feature_config.json // ✅ 配置独立 -``` - ---- - -## 📚 参考架构 - -这个新结构参考了业界最佳实践: -- **Godot 官方**: [Project Organization](https://docs.godotengine.org/en/stable/tutorials/best_practices/project_organization.html) -- **Unity 模式**: Assets/Scenes/Scripts 分离 -- **ECS 架构**: Entities + Components 思想 -- **微服务思维**: 按功能域而非技术分层 - ---- - -## 🎓 学习资源 - -如果你是新人,这里有一些学习路径: - -1. **先熟悉目录** → 查看 [REFACTORING.md](./REFACTORING.md) -2. **理解核心系统** → 阅读 `_Core/systems/EventSystem.gd` -3. **学习场景管理** → 查看 `_Core/managers/SceneManager.gd` -4. **研究 UI 结构** → 打开 `UI/Windows/LoginWindow.tscn` -5. **运行测试** → 执行 `Tests/` 下的测试用例 - ---- - -**结论:新结构更加清晰、模块化、易于维护,符合 Godot 最佳实践!** 🎉 diff --git a/cloude.md b/cloude.md deleted file mode 100644 index 77d72b9..0000000 --- a/cloude.md +++ /dev/null @@ -1,123 +0,0 @@ -# 🎯 WhaleTown 项目开发规范 - -## 1. 项目愿景与背景 -- **项目名称**: "WhaleTown" - 一个2D俯视角像素风RPG游戏 -- **引擎**: Godot 4.2+ (严格禁止使用Godot 3.x语法) -- **架构**: 严格分层架构:`_Core`(框架层)、`Scenes`(游戏层)、`UI`(界面层) -- **核心原则**: "信号向上,调用向下"。通过`EventSystem`实现高度解耦 - -## 2. 🛠 命令参考与设置 -- **输入映射 (必需配置)**: - - `move_left`, `move_right`, `move_up`, `move_down` (WASD / 方向键) - - `interact` (E键 / 空格键) - - `pause` (ESC键) -- **运行游戏**: `godot --path .` -- **运行测试 (GUT)**: `godot --headless -s addons/gut/gut_cmdline.gd -gdir=res://tests/ -ginclude_subdirs` -- **初始化结构**: `mkdir -p _Core/managers _Core/systems Scenes/Maps Scenes/Entities Scenes/Components UI/Windows UI/HUD Assets/Sprites tests/unit tests/integration` - -## 3. 📂 文件路径规则 (严格小写) -*注意:根目录文件夹必须小写。脚本和场景必须放在一起。* -- **核心管理器**: `_Core/managers/[Name].gd` -- **核心系统**: `_Core/systems/[Name].gd` -- **实体**: `Scenes/Entities/[EntityName]/[EntityName].tscn` (脚本`.gd`放在同一文件夹) -- **地图**: `Scenes/Maps/[map_name].tscn` -- **组件**: `Scenes/Components/[ComponentName].gd` (可复用逻辑节点) -- **UI窗口**: `UI/Windows/[WindowName].tscn` -- **测试**: `tests/[unit|integration]/test_[name].gd` (文件夹名为小写`tests`) - -## 4. 📋 编码标准 (必须遵守) -- **类型安全**: 始终使用严格静态类型:`var speed: float = 100.0`, `func _ready() -> void` -- **命名约定**: - - 每个脚本顶部必须有`class_name PascalCase` - - 变量/函数:`snake_case`。常量:`SCREAMING_SNAKE_CASE` - - 私有成员:使用下划线前缀`_` (例如:`var _health: int`) -- **节点访问**: 对UI和内部场景组件使用`%UniqueName` -- **信号**: 使用"信号向上,调用向下"原则。父节点调用子节点方法;子节点发出信号 -- **禁止模式**: - - ❌ 禁止使用`yield()` -> 使用`await` - - ❌ 禁止在`_process`中使用`get_node()` -> 使用`@onready`缓存 - - ❌ 禁止线性过滤 -> 所有Sprite2D/TileMap资源必须使用**最近邻**过滤 - -## 5. 🏛 架构与通信 -- **事件系统**: 使用`_Core/systems/EventSystem.gd`进行跨模块消息传递 -- **事件注册**: 在`_Core/EventNames.gd`中使用`class_name EventNames` - ```gdscript - class_name EventNames - const PLAYER_MOVED = "player_moved" - const INTERACT_PRESSED = "interact_pressed" - const NPC_TALKED = "npc_talked" - ``` -- **单例**: 只允许GameManager、SceneManager、EventSystem作为自动加载 -- **解耦**: 底层实体不得直接引用GameManager。使用事件系统 - -## 6. 🏗 实现细节 -- **玩家**: 使用CharacterBody2D。必须包含Camera2D,设置`position_smoothing_enabled = true` -- **NPC/交互物**: 使用名为InteractionArea的Area2D。通过EventSystem触发 -- **TileMap图层**: - - 图层0:地面 (无碰撞) - - 图层1:障碍物 (启用物理层) - - 图层2:装饰 (启用Y排序) -- **相机**: 必须通过`TileMap.get_used_rect()`自动计算边界 - -## 7. 🧪 测试要求 (强制性) -- **覆盖率**: `_Core/`中的每个管理器/系统都必须有GUT测试 -- **命名**: 测试文件必须以`test_`开头并继承`GutTest` -- **示例**: - ```gdscript - extends GutTest - func test_event_emission(): - var sender = Node.new() - watch_signals(EventSystem) - EventSystem.emit_event(EventNames.PLAYER_MOVED, {}) - assert_signal_emitted(EventSystem, "event_raised") - ``` - -## 8. 🧘 开发哲学 -- **流畅体验**: 每个交互(UI弹窗、NPC对话)都必须有Tween动画占位符 -- **零魔法数字**: 所有速度/计时器必须使用`@export`或在`Config/`中定义 -- **简洁性**: 如果一个函数做两件事,就拆分它 -- **隐藏逻辑**: 隐藏的逻辑(如ResponseHandler.gd)必须和HUD一样干净 - -## 9. 📝 代码模板 (实体模式) -```gdscript -extends CharacterBody2D -class_name Player - -# 1. 导出变量与常量 -@export var move_speed: float = 200.0 - -# 2. 节点引用 -@onready var sprite: Sprite2D = %Sprite2D - -# 3. 生命周期 -func _physics_process(delta: float) -> void: - _move(delta) - -# 4. 私有方法 -func _move(_delta: float) -> void: - var dir := Input.get_vector("move_left", "move_right", "move_up", "move_down") - velocity = dir * move_speed - move_and_slide() -``` - -## 10. 🎨 UI设计规范 -- **响应式布局**: 使用Anchor和Margin实现自适应 -- **主题统一**: 所有UI组件使用统一主题资源 -- **动画效果**: 界面切换必须有过渡动画 -- **无障碍支持**: 支持键盘导航 - -## 11. 🔧 性能优化 -- **对象池**: 频繁创建销毁的对象使用对象池 -- **视锥剔除**: 只渲染可见区域的对象 -- **批量处理**: 合并相似的渲染调用 -- **内存管理**: 及时释放不需要的资源 - -## 12. 📚 最佳实践 -- **模块化**: 功能拆分为独立模块 -- **可测试**: 设计易于测试的代码结构 -- **文档化**: 为复杂逻辑添加详细注释 -- **版本控制**: 遵循Git提交规范 - ---- - -**记住:代码质量是游戏成功的基础!** \ No newline at end of file