From ee1ff7f44484823add0296ccc9a614d86d22f1b3 Mon Sep 17 00:00:00 2001 From: lms <573220649@qq.com> Date: Tue, 7 Jul 2026 18:36:15 +0800 Subject: [PATCH] =?UTF-8?q?[docs][refactor]:=20=E5=B0=86=E6=97=A7=2001~06?= =?UTF-8?q?=20=E4=B8=AD=E6=96=87=E6=95=99=E7=A8=8B=E5=90=88=E5=B9=B6?= =?UTF-8?q?=E6=95=B4=E7=90=86=E4=B8=BA=20modules/frameworks=20=E6=96=87?= =?UTF-8?q?=E4=BB=B6=E5=A4=B9=E7=BB=93=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 删除 01~05 旧中文教程目录 - 将 03 核心功能教程拆分为各 framework 模块的子文档 - 06 工具脚本移入 modules/frameworks/编辑器工具/UI工具/ - 非框架内容合并进 rules/20-开发规则.md 与 rules/40-工作流清单.md - 更新所有交叉链接与文档关联表 Co-Authored-By: Claude Opus 4.8 (1M context) --- 02_开发规范/开发规范指南.md | 106 ----- 03_核心功能/UI/UI界面拼接设计指南.md | 407 ------------------ 04_开发流程/常见问题指南.md | 46 -- 04_开发流程/开发流程指南.md | 108 ----- 04_开发流程/最佳实践指南.md | 49 --- 05_项目管理/Git提交注意事项.md | 21 - 05_项目管理/Git规定指南.md | 115 ----- 05_项目管理/核心库保护规范.md | 80 ---- AGENTS.md | 31 ++ CLAUDE.md | 33 ++ README.md | 119 +++-- RULES.md | 21 + ai/AI接入入口.md | 65 +++ .../playballoons/features/GM调试.md | 134 ++++++ .../playballoons/features/PVE关卡战斗.md | 94 ++++ .../playballoons/features/PVP.md | 80 ++++ .../playballoons/features/商店.md | 128 ++++++ .../playballoons/features/地图进度.md | 148 +++++++ .../playballoons/features/塔养成.md | 123 ++++++ .../playballoons/features/奖励道具.md | 105 +++++ .../playballoons/features/登录.md | 167 +++++++ .../playballoons/features/背包.md | 174 ++++++++ .../playballoons/业务参考总入口.md | 40 ++ .../playballoons/业务框架映射接口.md | 105 +++++ hooks/Hook共享层.md | 89 ++++ hooks/archive-check.ps1 | 181 ++++++++ hooks/commit-check.ps1 | 111 +++++ hooks/commit-module-mappings.json | 88 ++++ hooks/sync-doc-associations.ps1 | 22 + hooks/sync_doc_associations.py | 218 ++++++++++ modules/frameworks/Hotfix启动.md | 95 ++++ modules/frameworks/UI窗口系统/README.md | 129 ++++++ .../frameworks/UI窗口系统/开发指南.md | 51 ++- modules/frameworks/UI窗口系统/界面拼接.md | 192 +++++++++ modules/frameworks/事件系统/README.md | 122 ++++++ .../frameworks/事件系统/使用指南.md | 45 +- modules/frameworks/内存对象管理/README.md | 110 +++++ .../frameworks/内存对象管理/使用指南.md | 25 +- modules/frameworks/场景系统.md | 98 +++++ modules/frameworks/实体系统/README.md | 138 ++++++ .../frameworks/实体系统/开发指南.md | 121 +++--- .../frameworks/实体系统/注意事项.md | 42 +- modules/frameworks/技能系统/README.md | 134 ++++++ .../frameworks/技能系统/使用指南.md | 34 +- modules/frameworks/数据配置框架.md | 111 +++++ modules/frameworks/相机系统/README.md | 122 ++++++ .../frameworks/相机系统/使用指南.md | 25 +- modules/frameworks/第三方插件.md | 49 +++ modules/frameworks/编辑器工具/README.md | 54 +++ .../编辑器工具}/UI工具/ExternalCommandListener.cs | 0 .../UI工具/ExternalCommandListener.cs.meta | 0 .../编辑器工具}/UI工具/RemoteCommand.cs | 0 .../编辑器工具}/UI工具/RemoteCommand.cs.meta | 0 .../编辑器工具}/UI工具/UIPrefabGenerator.cs | 0 .../编辑器工具}/UI工具/UIPrefabGenerator.cs.meta | 0 .../编辑器工具}/UI工具/UIPrefabToJson.cs | 0 .../编辑器工具}/UI工具/UIPrefabToJson.cs.meta | 0 modules/frameworks/编辑器工具/UI拼接工具.md | 248 +++++++++++ modules/frameworks/网络系统.md | 121 ++++++ modules/frameworks/资源管理/README.md | 136 ++++++ .../frameworks/资源管理/使用指南.md | 30 +- modules/frameworks/通用框架/README.md | 70 +++ .../frameworks/通用框架/框架架构.md | 115 +++-- modules/模块文档模板.md | 84 ++++ modules/模块索引.md | 85 ++++ rules/00-项目概览.md | 119 +++++ rules/10-架构说明.md | 144 +++++++ rules/20-开发规则.md | 269 ++++++++++++ rules/30-模块登记规则.md | 81 ++++ rules/40-工作流清单.md | 206 +++++++++ rules/50-归档规则.md | 79 ++++ rules/60-新特性工作流.md | 138 ++++++ rules/70-项目设置.md | 82 ++++ rules/项目规则入口.md | 252 +++++++++++ specs/Spec模板.md | 75 ++++ specs/Spec索引.md | 57 +++ specs/openspec/OpenSpec归档.md | 100 +++++ 77 files changed, 6263 insertions(+), 1133 deletions(-) delete mode 100644 02_开发规范/开发规范指南.md delete mode 100644 03_核心功能/UI/UI界面拼接设计指南.md delete mode 100644 04_开发流程/常见问题指南.md delete mode 100644 04_开发流程/开发流程指南.md delete mode 100644 04_开发流程/最佳实践指南.md delete mode 100644 05_项目管理/Git提交注意事项.md delete mode 100644 05_项目管理/Git规定指南.md delete mode 100644 05_项目管理/核心库保护规范.md create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 RULES.md create mode 100644 ai/AI接入入口.md create mode 100644 business-reference/playballoons/features/GM调试.md create mode 100644 business-reference/playballoons/features/PVE关卡战斗.md create mode 100644 business-reference/playballoons/features/PVP.md create mode 100644 business-reference/playballoons/features/商店.md create mode 100644 business-reference/playballoons/features/地图进度.md create mode 100644 business-reference/playballoons/features/塔养成.md create mode 100644 business-reference/playballoons/features/奖励道具.md create mode 100644 business-reference/playballoons/features/登录.md create mode 100644 business-reference/playballoons/features/背包.md create mode 100644 business-reference/playballoons/业务参考总入口.md create mode 100644 business-reference/playballoons/业务框架映射接口.md create mode 100644 hooks/Hook共享层.md create mode 100644 hooks/archive-check.ps1 create mode 100644 hooks/commit-check.ps1 create mode 100644 hooks/commit-module-mappings.json create mode 100644 hooks/sync-doc-associations.ps1 create mode 100644 hooks/sync_doc_associations.py create mode 100644 modules/frameworks/Hotfix启动.md create mode 100644 modules/frameworks/UI窗口系统/README.md rename 03_核心功能/UI/UI开发指南.md => modules/frameworks/UI窗口系统/开发指南.md (72%) create mode 100644 modules/frameworks/UI窗口系统/界面拼接.md create mode 100644 modules/frameworks/事件系统/README.md rename 03_核心功能/事件系统使用指南.md => modules/frameworks/事件系统/使用指南.md (64%) create mode 100644 modules/frameworks/内存对象管理/README.md rename 03_核心功能/对象池使用指南.md => modules/frameworks/内存对象管理/使用指南.md (67%) create mode 100644 modules/frameworks/场景系统.md create mode 100644 modules/frameworks/实体系统/README.md rename 03_核心功能/Entity/Entity开发指南.md => modules/frameworks/实体系统/开发指南.md (63%) rename 03_核心功能/Entity/UnityEntities注意事项.md => modules/frameworks/实体系统/注意事项.md (55%) create mode 100644 modules/frameworks/技能系统/README.md rename 03_核心功能/Entity/通用技能系统使用指南.md => modules/frameworks/技能系统/使用指南.md (67%) create mode 100644 modules/frameworks/数据配置框架.md create mode 100644 modules/frameworks/相机系统/README.md rename 03_核心功能/相机系统使用指南.md => modules/frameworks/相机系统/使用指南.md (64%) create mode 100644 modules/frameworks/第三方插件.md create mode 100644 modules/frameworks/编辑器工具/README.md rename {06_工具脚本 => modules/frameworks/编辑器工具}/UI工具/ExternalCommandListener.cs (100%) rename {06_工具脚本 => modules/frameworks/编辑器工具}/UI工具/ExternalCommandListener.cs.meta (100%) rename {06_工具脚本 => modules/frameworks/编辑器工具}/UI工具/RemoteCommand.cs (100%) rename {06_工具脚本 => modules/frameworks/编辑器工具}/UI工具/RemoteCommand.cs.meta (100%) rename {06_工具脚本 => modules/frameworks/编辑器工具}/UI工具/UIPrefabGenerator.cs (100%) rename {06_工具脚本 => modules/frameworks/编辑器工具}/UI工具/UIPrefabGenerator.cs.meta (100%) rename {06_工具脚本 => modules/frameworks/编辑器工具}/UI工具/UIPrefabToJson.cs (100%) rename {06_工具脚本 => modules/frameworks/编辑器工具}/UI工具/UIPrefabToJson.cs.meta (100%) create mode 100644 modules/frameworks/编辑器工具/UI拼接工具.md create mode 100644 modules/frameworks/网络系统.md create mode 100644 modules/frameworks/资源管理/README.md rename 03_核心功能/资源管理使用指南.md => modules/frameworks/资源管理/使用指南.md (56%) create mode 100644 modules/frameworks/通用框架/README.md rename 01_框架架构/StrayFog框架架构分析.md => modules/frameworks/通用框架/框架架构.md (71%) create mode 100644 modules/模块文档模板.md create mode 100644 modules/模块索引.md create mode 100644 rules/00-项目概览.md create mode 100644 rules/10-架构说明.md create mode 100644 rules/20-开发规则.md create mode 100644 rules/30-模块登记规则.md create mode 100644 rules/40-工作流清单.md create mode 100644 rules/50-归档规则.md create mode 100644 rules/60-新特性工作流.md create mode 100644 rules/70-项目设置.md create mode 100644 rules/项目规则入口.md create mode 100644 specs/Spec模板.md create mode 100644 specs/Spec索引.md create mode 100644 specs/openspec/OpenSpec归档.md diff --git a/02_开发规范/开发规范指南.md b/02_开发规范/开发规范指南.md deleted file mode 100644 index ca5067b..0000000 --- a/02_开发规范/开发规范指南.md +++ /dev/null @@ -1,106 +0,0 @@ -# StrayFog 框架开发规范指南 - -## 一、开发前准备 - -### 1.1 核心概念理解 - -#### 1.1.1 框架层级关系 - -``` -┌─────────────────────────────────────────────────────────────┐ -│ 开发层级视图 │ -├─────────────────────────────────────────────────────────────┤ -│ 业务层 (你开发的代码) │ -│ ├── UI界面、业务逻辑、游戏数据 │ -│ │ │ -│ │ ┌───────────────────────────────────────────────────┐ │ -│ │ │ 核心库 (只读，框架团队维护) │ │ -│ │ │ ├── Core: 模拟行为、全局数据 │ │ -│ │ │ ├── HF: 资源管理、事件系统、相机管理 │ │ -│ │ │ └── General: 状态机、工具类 │ │ -│ │ └───────────────────────────────────────────────────┘ │ -│ │ │ -│ └─────────────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ -``` - -#### 1.1.2 核心库访问原则 - -| 原则 | 说明 | -|-----|-----| -| **只读访问** | 核心库代码只可读取，不可修改 | -| **接口优先** | 通过接口访问服务，而非直接实例化实现类 | -| **继承扩展** | 通过继承抽象类实现自定义逻辑 | -| **依赖注入** | 通过管理器获取实例，而非硬编码 | - ---- - -## 二、业务代码结构 - -### 2.1 目录组织规范 - -``` -Assets/Game/GameHFScripte/GameFunction/ -├── Event/ # 消息处理 -│ ├── ServerToClient/ # 服务器到客户端消息 -│ ├── ClientToClient/ # 客户端内部消息 -│ └── Handle/ # 消息处理器 - -├── GameRoot/ # 框架调用入口 -│ ├── HFGameStart.cs # 热更新进入入口 -│ ├── HFFunCatalogue.cs # 框架统一调用入口 -│ ├── HFFunCatalogue_Function.cs # 功能调用方法 -│ └── ... - -├── HFDownLoadSubPackage/ # 分包下载 -│ ├── HFSubPackageManager.cs # 分包管理器 -│ ├── HFGameStartAssetsCheckManager.cs # 资源检查 -│ └── ... - -├── HFExtends/ # Class扩展方法 -│ ├── UI/ # UI扩展 -│ ├── Material/ # 材质扩展 -│ ├── String/ # 字符串扩展 -│ └── ... - -├── Logic/ # 游戏主要业务逻辑（存放各功能Manager） -│ ├── User/ # 用户相关 -│ ├── Login/ # 登录系统 -│ ├── Fight/ # 战斗系统 -│ ├── CardDeck/ # 卡组系统 -│ ├── Bag/ # 背包系统 -│ └── ... - -├── UIWindows/ # UI窗口业务逻辑 -│ ├── Login/ # 登录窗口 -│ ├── Lobby/ # 大厅窗口 -│ ├── Fight/ # 战斗窗口 -│ ├── Shop/ # 商店窗口 -│ └── ... - -├── GameEntity/ # 游戏实体 -│ ├── Entity/ # 实体定义 -│ ├── EntityPool/ # 实体对象池 -│ └── ... - -├── SoundManagerPro/ # 音效管理 -├── SceneManager/ # 场景管理 -├── SDK/ # SDK集成 -└── MonoCompent/ # Mono组件 -``` - -### 2.2 文件命名规范 - -| 文件类型 | 命名规则 | 示例 | -|---------|---------|-----| -| **窗口类** | `XXXWindow.cs` | `LoginWindow.cs` | -| **组件类** | `XXXComponent.cs` | `ItemCellComponent.cs` | -| **管理器类** | `XXXManager.cs` | `UIManager.cs` | -| **数据类** | `XXXData.cs` | `PlayerData.cs` | -| **配置类** | `XXXConfig.cs` | `SkillConfig.cs` | - ---- - -**版本**: v1.0 -**生效日期**: 2026年 -**适用范围**: GiftGameX项目业务开发人员 \ No newline at end of file diff --git a/03_核心功能/UI/UI界面拼接设计指南.md b/03_核心功能/UI/UI界面拼接设计指南.md deleted file mode 100644 index 4382fd4..0000000 --- a/03_核心功能/UI/UI界面拼接设计指南.md +++ /dev/null @@ -1,407 +0,0 @@ -# UI界面拼接设计指南 - -## 一、界面结构设计原则 - -### 1.1 模块化拆分 -将界面按功能划分为独立模块： - -| 模块类型 | 功能定位 | 示例 | -|---------|---------|------| -| **信息展示区** | 显示玩家状态、资源等静态信息 | 顶部信息栏、左侧状态栏 | -| **功能入口区** | 提供功能按钮入口 | 中央功能区、底部快捷栏 | -| **交互面板区** | 可展开/收起的功能面板 | 右侧功能面板、顶部按钮区 | -| **输入输出区** | 用户输入和系统反馈 | 聊天输入框、提示信息 | - -### 1.2 经典布局模式 - -``` -┌─────────────────────────────────────────────────────┐ -│ TopArea (信息展示 + 可收起功能按钮) │ -├──────────┬───────────────────────┬──────────────────┤ -│ Left │ │ Right │ -│ Area │ CenterArea │ Area │ -│ (状态) │ (核心功能入口) │ (功能面板) │ -│ │ │ │ -├──────────┴───────────────────────┴──────────────────┤ -│ BottomArea (快捷功能 + 状态信息 + 输入) │ -└─────────────────────────────────────────────────────┘ -``` - ---- - -## 二、组件拆分方法 - -### 2.1 基础组件识别 - -| 组件类型 | 识别特征 | 处理方式 | -|---------|---------|---------| -| **按钮** | 可点击、有交互反馈 | 使用 `SFUI_Button` | -| **文本** | 静态/动态文字显示 | 使用 `SFUI_TextMeshProUGUI` | -| **图片** | 图标、背景图 | 使用 `SFUI_Image` | -| **进度条** | HP、MP、经验等 | 使用 `SFUI_Slider` | -| **列表** | 可滚动的项目列表 | 使用 `SFUI_ScrollRect` | - -### 2.2 复合组件封装 - -将功能相关的基础组件组合为复合组件，便于复用和维护： - -**设计原则**： -- 将同一功能模块的组件封装在一起（如玩家头像+血条+蓝条） -- 提供统一的数据设置接口 -- 保持组件之间的逻辑独立性 - ---- - -## 三、预制体层级规范 - -### 3.1 标准层级结构 - -``` -WindowName (RectTransform) -├── ModuleName (RectTransform) # 模块容器 -│ ├── ComponentName (SFUI_*) # 功能组件 -│ ├── SubModule (RectTransform) # 子模块 -│ └── CollapsibleArea (RectTransform) # 可收起区域 -└── BtnCollapse (SFUI_Button) # 收起控制按钮 -``` - -### 3.2 命名规范 - -| 类型 | 命名规则 | 示例 | -|-----|---------|------| -| 模块容器 | PascalCase + Area | `TopArea` | -| 功能组件 | PascalCase | `BtnCollapseTop` | -| 可收起区域 | PascalCase + FuncArea | `TopFuncArea` | -| 状态变量 | m_ + PascalCase | `m_IsTopCollapsed` | - ---- - -## 四、收起/展开功能设计 - -### 4.1 功能定义 - -| 按钮 | 控制区域 | 用途 | -|-----|---------|------| -| `BtnCollapseTop` | 顶部功能按钮区 | 收起/展开顶部按钮群 | -| `BtnCollapseRight` | 右侧功能面板区 | 收起/展开右侧功能面板 | - -### 4.2 设计要点 - -**状态管理**：每个可收起区域需要一个布尔状态变量来记录当前收起/展开状态。 - -**交互逻辑**： -1. 点击收起按钮时，切换对应区域的显示/隐藏状态 -2. 同时切换按钮图标（收起时显示展开图标，展开时显示收起图标） - -**布局要求**： -- 收起按钮应放置在对应区域的边缘位置，便于用户找到 -- 收起区域内的所有元素应作为一个整体进行显示/隐藏控制 -- 收起状态应在窗口生命周期内保持记忆 - ---- - -## 五、实际案例：主界面拼接 - -### 5.1 模块化设计思想 - -**核心原则**：将界面按功能边界划分为独立模块，模块内可嵌套子模块。 - -**模块归类方法**： - -1. **一级模块**：按空间位置划分（顶部、左侧、中央、右侧、底部） -2. **二级模块**：按功能类型划分（信息展示区、功能按钮区、输入输出区） -3. **三级模块**：按具体功能划分（玩家头像、资源显示、功能按钮群） - -**层级关系示例**： - -``` -Window -├── TopArea (一级：位置) -│ ├── InfoPanel (二级：信息展示) -│ │ └── TxtWelcome (三级：具体组件) -│ └── FuncButtons (二级：功能按钮) -│ └── BtnUpload (三级：具体按钮) -└── LeftArea (一级：位置) - └── PlayerPortrait (二级：复合组件) - ├── ImgAvatar (三级：头像) - └── BarHP (三级：血条) -``` - -**设计要点**： -- 同一功能域内的元素归为同一模块（如头像、血条、蓝条归为玩家状态模块） -- 独立交互功能作为独立模块（如收起按钮单独作为控制模块） -- 可收起区域作为独立子模块，便于统一控制显示/隐藏 - ---- - -## 六、界面拼接流程 - -### 6.1 设计阶段 -1. **需求分析**：明确界面功能和交互需求 -2. **模块划分**：将界面拆分为独立功能模块 -3. **层级设计**：设计预制体层级结构 - -### 6.2 开发阶段 -1. **组件创建**：创建基础组件和复合组件 -2. **预制体搭建**：按层级结构搭建预制体 -3. **脚本编写**：实现交互逻辑和收起/展开功能 - -### 6.3 测试阶段 -1. **功能测试**：验证所有按钮和交互功能 -2. **收起测试**：测试收起/展开功能正常工作 -3. **适配测试**：验证不同分辨率下的显示效果 - ---- - -## 七、注意事项 - -1. **组件复用**：相同功能的组件尽量复用，减少冗余 -2. **状态管理**：收起状态需要正确保存和恢复 -3. **图标反馈**：收起按钮图标应随状态变化 -4. **性能优化**：可收起区域使用 `SetActive` 而非销毁重建 -5. **命名规范**：统一的命名规则便于维护和查找 - ---- - -## 八、JSON配置驱动的UI生成方式 - -### 8.1 概述 - -**UI相关人员核心工作流程**：读取设计效果图和碎片图片，生成JSON配置文件，再通过工具自动生成Unity预制体。 - -本项目支持JSON配置与Unity预制体的双向转换： -- **正向转换**：JSON配置 → UI预制体（核心流程） -- **反向转换**：UI预制体 → JSON配置（开发者调整完预制体后，反向生成用于版本控制或重新生成） - -实现UI界面的快速构建、迭代和版本控制。 - -### 8.2 核心组件 - -| 组件 | 职责 | 文件路径 | -|-----|------|---------| -| **UIPrefabGenerator** | 解析JSON并生成UI预制体 | `Assets/Editor/Command/UIPrefabGenerator.cs` | -| **UIPrefabToJson** | 从预制体反向导出JSON | `Assets/Editor/Command/UIPrefabToJson.cs` | -| **RemoteCommand** | 提供外部调用接口 | `Assets/Editor/Command/RemoteCommand.cs` | -| **ExternalCommandListener** | 监听外部命令触发文件 | `Assets/Editor/Command/ExternalCommandListener.cs` | - -### 8.3 JSON配置文件结构 - -```json -{ - "name": "BagWindow", - "width": 1024, - "height": 768, - "elements": [ - { - "type": "Image", - "name": "BgPanel", - "anchorMin": [0, 0], - "anchorMax": [1, 1], - "position": [0, 0, 0], - "sizeDelta": [0, 0], - "sprite": "Assets/Game/GameHFResource/CN/UIWindows/BagWindow/Sprites/Bg.png" - }, - { - "type": "Text", - "name": "TitleText", - "anchorMin": [0.5, 0.9], - "anchorMax": [0.5, 0.9], - "position": [0, 0, 0], - "sizeDelta": [200, 40], - "text": "背包", - "font": "Assets/Game/GameHFResource/CN/Fonts/FZY4K-M05S SDF.asset", - "fontSize": 28, - "color": [1, 1, 1, 1] - } - ] -} -``` - -### 8.4 支持的UI元素类型 - -| 类型 | 对应Unity组件 | 关键属性 | -|-----|-------------|---------| -| **Image** | Image | sprite, color, type, preserveAspect | -| **TextMeshProUGUI** | TextMeshProUGUI | text, font, fontSize, color, alignment | -| **Button** | Button | interactable, transition, navigationMode | -| **Slider** | Slider | minValue, maxValue, value, wholeNumbers, direction | -| **Toggle** | Toggle | isOn, toggleTransition, transition | -| **InputField** | InputField | text, placeholder, characterLimit, contentType | -| **ScrollRect** | ScrollRect | horizontal, vertical, movementType | -| **GridLayoutGroup** | GridLayoutGroup | cellSize, spacing, constraint, padding | -| **VerticalLayoutGroup** | VerticalLayoutGroup | spacing, childAlignment, padding | -| **HorizontalLayoutGroup** | HorizontalLayoutGroup | spacing, childAlignment, padding | - -### 8.5 外部命令触发机制 - -#### 8.5.1 触发方式 - -通过创建/修改 `Trigger_Command.txt` 文件触发UI生成： - -``` -GenerateUIPrefab:Assets/Editor/UI/BagWindow.json -``` - -#### 8.5.2 命令格式 - -``` -<命令名>:<参数1>:<参数2>:... -``` - -**支持的命令**： - -| 命令 | 参数 | 说明 | -|-----|------|------| -| **GenerateUIPrefab** | `jsonPath` [, `prefabPath`] | 根据JSON生成UI预制体 | -| **ExportPrefabToJson** | `prefabPath` [, `jsonPath`] | 从预制体反向导出JSON | -| **ReadJson** | [参数列表] | 读取JSON配置（测试用） | - -#### 8.5.3 完整执行流程 - -``` -┌─────────────────────────────────────────────────────────────────────┐ -│ 外部系统写入命令到 Trigger_Command.txt │ -└─────────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────────┐ -│ ExternalCommandListener (FileSystemWatcher) 检测到文件变化 │ -└─────────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────────┐ -│ 解析命令格式：GenerateUIPrefab:Assets/Editor/UI/BagWindow.json │ -└─────────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────────┐ -│ 通过反射调用 RemoteCommand.GenerateUIPrefab(string[] args) │ -└─────────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────────┐ -│ UIPrefabGenerator.GeneratePrefabFromJson(jsonPath, prefabPath) │ -└─────────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────────┐ -│ 生成预制体到指定路径：Assets/Game/GameHFResource/CN/UIWindows/... │ -└─────────────────────────────────────────────────────────────────────┘ -``` - -### 8.6 使用示例 - -#### 方式一：外部命令触发 - -```bash -# 正向：从JSON生成预制体 -echo "GenerateUIPrefab:Assets/Editor/UI/BagWindow.json" > "F:\JMNet\CrystalBattle_Client\Trigger_Command.txt" - -# 反向：从预制体导出JSON -echo "ExportPrefabToJson:Assets/Game/GameHFResource/CN/UIWindows/BagWindow/BagWindow.prefab" > "F:\JMNet\CrystalBattle_Client\Trigger_Command.txt" -``` - -#### 方式二：Unity编辑器菜单 - -**正向生成**： -1. 打开Unity编辑器 -2. 点击菜单 `Tools > External > Test GenerateUIPrefab` -3. 查看Console窗口日志确认执行结果 - -**反向导出**： -1. 打开Unity编辑器 -2. 点击菜单 `Tools > UI > Export Prefab to JSON` -3. 选择要导出的预制体文件 - -#### 方式三：代码调用 - -```csharp -// 正向：从JSON生成预制体 -UIPrefabGenerator.GeneratePrefabFromJson( - "Assets/Editor/UI/BagWindow.json", - "Assets/Game/GameHFResource/CN/UIWindows/BagWindow/BagWindow.prefab" -); - -// 反向：从预制体导出JSON -UIPrefabToJson.ExportPrefabToJson( - "Assets/Game/GameHFResource/CN/UIWindows/BagWindow/BagWindow.prefab", - "Assets/Editor/UI/BagWindow.json" -); -``` - -### 8.8 注意事项 - -1. **路径格式**：JSON中的资源路径使用 `/` 分隔符，且为Unity项目相对路径 -2. **资源引用**：确保JSON中引用的Sprite、Font等资源已存在于项目中 -3. **编码格式**：JSON文件使用UTF-8编码 -4. **坐标系统**：使用Unity RectTransform的anchorMin/anchorMax/position/sizeDelta四元组 -5. **文件锁定**：生成前确保目标预制体文件未被其他进程占用 - -### 8.9 工具脚本部署 - -#### 8.9.1 工具位置 - -工具脚本位于UnityAI文档库的以下路径： - -``` -UnityAI/06_工具脚本/UI工具/ -├── ExternalCommandListener.cs # 外部命令监听器 -├── RemoteCommand.cs # 远程命令接口 -├── UIPrefabGenerator.cs # JSON转预制体生成器 -└── UIPrefabToJson.cs # 预制体转JSON导出器 -``` - -#### 8.9.2 部署步骤 - -**方法一：手动复制** - -1. 复制 `06_工具脚本/UI工具/` 目录下的所有文件 -2. 粘贴到目标项目的 `Assets/Editor/Command/` 目录中 -3. 确保目录结构如下： - ``` - Assets/Editor/Command/ - ├── ExternalCommandListener.cs - ├── RemoteCommand.cs - ├── UIPrefabGenerator.cs - └── UIPrefabToJson.cs - ``` - -**方法二：自动部署脚本** - -创建部署脚本 `DeployUITools.bat`： - -```batch -@echo off -set "SOURCE_DIR=E:\AI\UnityAI\06_工具脚本\UI工具" -set "TARGET_DIR=%cd%\Assets\Editor\Command" - -mkdir "%TARGET_DIR%" 2>nul -xcopy "%SOURCE_DIR%\*.cs" "%TARGET_DIR%\" /y -xcopy "%SOURCE_DIR%\*.cs.meta" "%TARGET_DIR%\" /y - -echo UI工具部署完成 -pause -``` - -#### 8.9.3 部署规则 - -| 检查项 | 要求 | -|-------|------| -| **目标路径** | 必须放置在 `Assets/Editor/Command/` 目录下 | -| **文件完整性** | 必须包含所有4个cs文件及其meta文件 | -| **Unity版本** | 支持Unity 2020及以上版本 | -| **依赖组件** | 需要导入 TextMeshPro 包 | - -#### 8.9.4 验证部署 - -部署完成后，在Unity编辑器中验证： - -1. 打开Unity编辑器 -2. 检查菜单 `Tools > UI` 是否存在 -3. 检查菜单 `Tools > External` 是否存在 -4. 在Console窗口确认无编译错误 - ---- - -**版本**: v1.2 -**适用**: StrayFog框架UI拼接开发人员 \ No newline at end of file diff --git a/04_开发流程/常见问题指南.md b/04_开发流程/常见问题指南.md deleted file mode 100644 index 569f5d4..0000000 --- a/04_开发流程/常见问题指南.md +++ /dev/null @@ -1,46 +0,0 @@ -# StrayFog 框架常见问题指南 - -## 一、常见问题解答 - -### 1.1 如何扩展核心库功能？ - -通过继承抽象类或实现接口来扩展，不要直接修改核心库代码。 - -### 1.2 核心库有Bug怎么办？ - -提交Issue到框架团队，由框架团队修复并发布新版本。 - -### 1.3 如何获取核心库的最新版本？ - -关注内部通知，定期更新核心库引用。 - -### 1.4 如何调试核心库代码？ - -可以设置断点调试，但不允许修改代码。 - ---- - -## 附录 - -### A. 常用核心库API - -| 类别 | 管理器 | 常用方法 | -|-----|-------|---------| -| **对象池** | `HFObjectMemPool` | `GetItem()`, `GiveBack()` | -| **事件** | `IHFEventHandle` | `AddListener()`, `Dispatch()` | -| **资源** | `HFABMgr` | `OnStartLoad()` | -| **相机** | `HFCameraManager` | `AddCamera()`, `GetCamera()` | - -### B. 核心库只读目录 - -``` -Assets/StrayFog/Core/ -Assets/Game/GameHFScripte/CopyToHF/ -Assets/Game/GameGeneralScripte/ -``` - ---- - -**版本**: v1.0 -**生效日期**: 2026年 -**适用范围**: GiftGameX项目业务开发人员 \ No newline at end of file diff --git a/04_开发流程/开发流程指南.md b/04_开发流程/开发流程指南.md deleted file mode 100644 index c24853e..0000000 --- a/04_开发流程/开发流程指南.md +++ /dev/null @@ -1,108 +0,0 @@ -# StrayFog 框架开发流程指南 - -## 一、文档学习阶段 - -### 1.1 必读文档清单 - -| 优先级 | 文档路径 | 目的 | -|-------|---------|-----| -| P0 | `01_框架架构/StrayFog框架架构分析.md` | 理解框架整体架构 | -| P0 | `02_开发规范/开发规范指南.md` | 掌握编码规范和命名约定 | -| P1 | `03_核心功能/事件系统使用指南.md` | 理解事件驱动机制 | -| P1 | `03_核心功能/对象池使用指南.md` | 掌握对象池复用机制 | -| P1 | `03_核心功能/资源管理使用指南.md` | 理解资源加载流程 | - -### 1.2 功能专项文档 - -根据开发任务类型，必须阅读对应的专项指南： - -| 任务类型 | 必读文档 | -|---------|---------| -| UI开发 | `03_核心功能/UI/UI开发指南.md` | -| UI界面设计 | `03_核心功能/UI/UI界面拼接设计指南.md` | -| 相机控制 | `03_核心功能/相机系统使用指南.md` | - -### 1.3 输出要求 - -完成文档学习后，开发人员必须输出： -1. **工作流程说明**：详细描述从需求到交付的完整步骤 -2. **技术选型说明**：明确使用的框架组件和API -3. **风险评估**：识别潜在问题和解决方案 - ---- - -## 二、需求分析 - -### 2.1 需求分析步骤 - -1. **明确需求**：理解业务需求，确定需要实现的功能 -2. **评估复杂度**：判断是否需要核心库支持或扩展 -3. **设计方案**：规划代码结构和调用关系 - ---- - -## 三、代码编写 - -### 3.1 代码编写步骤 - -1. **创建目录**：在`GameBusiness`下创建对应模块目录 -2. **编写代码**：遵循编码规范，使用核心库提供的API -3. **测试验证**：在Unity中测试功能正确性 - ---- - -## 四、代码审查 - -### 4.1 代码审查流程 - -1. **自我检查**：检查是否符合规范，是否有潜在问题 -2. **团队审查**：提交代码进行团队审查 -3. **修复问题**：根据审查意见修改代码 - ---- - -## 五、集成测试 - -### 5.1 测试阶段 - -1. **模块测试**：测试单个模块功能 -2. **集成测试**：测试模块间交互 -3. **回归测试**：确保不影响现有功能 - ---- - -## 六、Git提交规范 - -### 6.1 提交格式要求 - -所有代码提交必须遵循以下格式： - -``` -【操作原因】具体操作内容 -``` - -### 6.2 操作原因分类 - -| 分类 | 说明 | 适用场景 | -|------|------|----------| -| 【初始化】 | 首次创建或上传 | 新项目初始化、首次上传文档 | -| 【更新】 | 修改或完善现有内容 | 更新文档、优化代码 | -| 【新增】 | 添加新文件或功能 | 新增文档、新增代码模块 | -| 【修复】 | 修复错误或问题 | 修复Bug、修正文档错误 | -| 【重构】 | 重构代码或文档结构 | 优化架构、重新组织文档 | -| 【删除】 | 删除文件或功能 | 删除无用文件、移除废弃代码 | -| 【配置】 | 修改配置文件 | 更新配置、调整参数 | - -### 6.3 提交示例 - -```bash -git commit -m "【更新】修复UI窗口打开时的空指针异常" -git commit -m "【新增】添加战斗系统核心模块" -git commit -m "【修复】修正开发流程指南中的错误描述" -``` - ---- - -**版本**: v1.0 -**生效日期**: 2026年 -**适用范围**: GiftGameX项目业务开发人员 \ No newline at end of file diff --git a/04_开发流程/最佳实践指南.md b/04_开发流程/最佳实践指南.md deleted file mode 100644 index a07fff8..0000000 --- a/04_开发流程/最佳实践指南.md +++ /dev/null @@ -1,49 +0,0 @@ -# StrayFog 框架最佳实践指南 - -## 一、性能优化 - -### 1.1 对象池使用 - -- 频繁创建销毁的对象必须使用对象池 -- 合理设置对象池初始容量 -- 定期清理空闲对象避免内存泄漏 - -### 1.2 资源管理 - -- 及时释放不再使用的资源 -- 使用异步加载避免卡顿 -- 合理使用资源缓存 - ---- - -## 二、代码组织 - -### 2.1 单一职责 - -- 每个类只负责一个功能 -- 避免庞大的God类 - -### 2.2 依赖管理 - -- 通过管理器获取依赖，而非硬编码 -- 使用接口解耦依赖关系 - ---- - -## 三、错误处理 - -### 3.1 异常捕获 - -- 在关键路径添加异常处理 -- 记录错误日志便于排查 - -### 3.2 防御性编程 - -- 检查参数合法性 -- 处理空引用情况 - ---- - -**版本**: v1.0 -**生效日期**: 2026年 -**适用范围**: GiftGameX项目业务开发人员 \ No newline at end of file diff --git a/05_项目管理/Git提交注意事项.md b/05_项目管理/Git提交注意事项.md deleted file mode 100644 index f047a21..0000000 --- a/05_项目管理/Git提交注意事项.md +++ /dev/null @@ -1,21 +0,0 @@ -# Git 提交注意事项 - -## 默认提交路径 - -- **默认仓库**：上传 Git 时，默认路径为 `E:\AI\UnityAI` -- **路径规则**：除非用户明确指定项目工程路径，否则所有 Git 操作均针对 `E:\AI\UnityAI` 仓库 -- **项目区分**：若需操作其他项目（如 `F:\JMNet\GiftGameX`），必须在指令中明确指定 - -## Git 操作原则 - -- **路径确认**：执行 Git 操作前，确认当前操作路径是否正确 -- **分支管理**：遵循项目既定的分支策略 -- **提交规范**：使用语义化提交信息，清晰描述更改内容 -- **代码审查**：重要功能提交前建议先创建分支进行测试 - -## 常见操作 - -- 查看状态：`git status` -- 添加更改：`git add .` -- 提交更改：`git commit -m "描述信息"` -- 推送到远程：`git push origin ` \ No newline at end of file diff --git a/05_项目管理/Git规定指南.md b/05_项目管理/Git规定指南.md deleted file mode 100644 index ef10ec2..0000000 --- a/05_项目管理/Git规定指南.md +++ /dev/null @@ -1,115 +0,0 @@ -# UnityAI Git 规定指南 - -## 一、提交日志格式规范 - -### 1.1 格式要求 - -所有 Git 提交日志必须遵循以下格式： - -``` -【操作原因】具体操作内容 -``` - -### 1.2 格式说明 - -| 部分 | 说明 | 示例 | -|------|------|------| -| `【操作原因】` | 用中文方括号包裹，描述本次操作的核心目的 | 【初始化】、【更新】、【修复】 | -| `具体操作内容` | 详细描述本次提交的内容，使用中文 | 上传框架文档、修改配置文件 | - -### 1.3 操作原因分类 - -| 分类 | 说明 | 适用场景 | -|------|------|----------| -| **【初始化】** | 首次创建或上传项目/文档 | 新项目初始化、首次上传文档 | -| **【更新】** | 修改或完善现有内容 | 更新文档内容、优化代码逻辑 | -| **【新增】** | 添加新的文件或功能 | 新增文档、新增代码模块 | -| **【修复】** | 修复错误或问题 | 修复文档错误、修复代码Bug | -| **【重构】** | 重构代码结构或文档结构 | 优化代码架构、重新组织文档 | -| **【删除】** | 删除文件或功能 | 删除无用文件、移除废弃代码 | -| **【迁移】** | 迁移文件或项目 | 文件位置调整、项目迁移 | -| **【配置】** | 修改配置文件 | 更新配置、调整参数 | - ---- - -## 二、提交日志示例 - -### 2.1 文档相关 - -``` -【初始化】上传UnityAI框架文档，包含StrayFog框架架构分析、业务开发指南、核心库保护规范 -【更新】完善StrayFog框架架构分析中Core层的描述 -【新增】添加Git规定指南文档 -【修复】修正业务开发指南中的代码示例错误 -``` - -### 2.2 代码相关 - -``` -【新增】实现AI决策系统核心模块 -【更新】优化对象池性能 -【修复】修复事件系统内存泄漏问题 -【重构】重构技能系统架构 -【删除】移除废弃的测试代码 -``` - -### 2.3 配置相关 - -``` -【配置】更新构建脚本参数 -【配置】调整日志输出级别 -``` - ---- - -## 三、Git 工作流程 - -### 3.1 提交流程 - -``` -修改文件 - │ - ▼ -git add . # 暂存所有修改 - │ - ▼ -git commit -m "【操作原因】具体操作内容" # 提交并撰写规范日志 - │ - ▼ -git push # 推送到远程仓库 -``` - -### 3.2 分支管理 - -| 分支名称 | 用途 | -|----------|------| -| `master` | 主分支，稳定版本 | -| `develop` | 开发分支，日常开发 | -| `feature/*` | 功能分支，开发新功能 | -| `bugfix/*` | Bug修复分支 | - -### 3.3 远程仓库信息 - -- **仓库地址**: `https://jinmt.com/Shiliang/UnityAI.git` -- **用户名**: *请在本地配置，不要提交到仓库* -- **密码**: *请在本地配置，不要提交到仓库* - -**本地配置方法**： -1. 使用 `git config credential.helper store` 配置凭证存储 -2. 首次推送时输入用户名密码，系统会自动保存到本地 - ---- - -## 四、注意事项 - -1. **日志语言**: 统一使用中文描述 -2. **简洁明了**: 日志应简洁清晰，准确反映提交内容 -3. **分类准确**: 选择合适的操作原因分类 -4. **避免空提交**: 禁止无内容的空提交 -5. **定期推送**: 开发完成后及时推送到远程仓库 - ---- - -**版本**: v1.0 -**生效日期**: 2026年5月22日 -**适用范围**: UnityAI项目团队 \ No newline at end of file diff --git a/05_项目管理/核心库保护规范.md b/05_项目管理/核心库保护规范.md deleted file mode 100644 index 439e033..0000000 --- a/05_项目管理/核心库保护规范.md +++ /dev/null @@ -1,80 +0,0 @@ -# StrayFog 框架核心库保护规范 - -## 一、核心库定义 - -### 1.1 核心库范围（只读） - -| 路径 | 说明 | -|------|------| -| `Assets/StrayFog/Core` | 基础框架核心 | -| `Assets/Game/GameHFScripte/CopyToHF` | 游戏核心业务框架 | -| `Assets/Game/GameGeneralScripte` | 通用工具层 | - ---- - -## 二、保护规则 - -### 2.1 访问方式 - -**业务代码必须通过 `HFFunCatalogue` 统一入口访问核心库：** - -```csharp -// ✅ 正确：通过统一入口访问 -HFFunCatalogue.UIManager.OpenWindow(); -HFFunCatalogue.Asset.LoadAsset("path"); -HFFunCatalogue.Scene.LoadScene("MainScene"); - -// ❌ 禁止：直接访问核心库 -HFUIWindowMgr.Instance.OpenWindow(); // 禁止 -HFABMgr.Instance.LoadAsset("path"); // 禁止 -``` - -### 2.2 禁止操作 - -| 禁止行为 | 后果 | -|---------|------| -| 修改核心库源代码 | 破坏框架稳定性 | -| 删除/重命名核心库文件 | 编译错误 | -| 直接实例化核心库内部类 | 违反封装原则 | -| 绕过 `HFFunCatalogue` 直接调用核心库单例 | 难以维护和测试 | - ---- - -## 三、修改流程 - -``` -业务人员发现问题/需求 - │ - ▼ - 提交Issue到框架团队 - │ - ▼ - 框架团队评估需求 - │ - ┌────┴────┐ - │ │ - 合理 不合理 - │ │ - ▼ ▼ - 开发修复 反馈拒绝 - │ - ▼ - 代码审查 → 发布新版本 → 业务团队更新引用 -``` - ---- - -## 四、违规处理 - -| 等级 | 违规行为 | 处理方式 | -|-----|---------|---------| -| **轻微** | 误修改注释、空行 | 警告+恢复 | -| **一般** | 修改非核心逻辑 | 通报批评+代码回滚 | -| **严重** | 修改核心逻辑导致Bug | 绩效扣分+修复责任 | -| **重大** | 删除核心文件导致崩溃 | 追责+修复责任 | - ---- - -**版本**: v1.0 -**生效日期**: 2024年 -**适用范围**: OnlineGame项目 \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..6f61bb0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,31 @@ +# UnityAI - Codex 入口 + +本文件是 Codex 的项目级入口包装。 + +处理本项目任务时，**先读取 `ai/AI接入入口.md`**，再按其中说明读取项目规则、项目知识和共享 hook 文档。 + +--- + +## AI 接入入口 + +- **[ai/AI接入入口.md](ai/AI接入入口.md)** — 所有 AI / IDE 工具的接入总入口。 + +## 说明 + +- 不要把项目规则重复写在你的系统提示里。 +- 所有项目规则维护在 `rules/`。 +- 所有项目模块知识维护在 `modules/`。 +- 共享 hook 规则和检查脚本维护在 `hooks/`。 +- Codex 私有目录只放适配器，不复制项目规则。 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [ai/AI接入入口.md](ai/AI接入入口.md) | AGENTS.md 指向 AI 接入入口，入口变更需同步 | +| [CLAUDE.md](CLAUDE.md) | Claude Code 入口与 AGENTS.md 互为替代入口 | +| [RULES.md](RULES.md) | 通用兼容入口需与 AGENTS.md 保持一致 | \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..7c00941 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,33 @@ +# UnityAI - Claude Code 入口 + +本文件是 Claude Code 的入口包装。 + +处理本项目任务时，**先读取 `ai/AI接入入口.md`**，再按其中说明读取项目规则、项目知识和共享 hook 文档。 + +--- + +## AI 接入入口 + +- **[ai/AI接入入口.md](ai/AI接入入口.md)** — 所有 AI / IDE 工具的接入总入口。 + +## 说明 + +- 不要把项目规则重复写在你的系统提示里。 +- 所有项目规则维护在 `rules/`。 +- 所有项目模块知识维护在 `modules/`。 +- 共享 hook 规则和检查脚本维护在 `hooks/`。 +- 若已配置 OpenSpec，Claude Code 用户可使用命令：`/opsx:propose`、`/opsx:apply`、`/opsx:archive`。 +- 只有用户明确说“提交”“提交代码”“commit”或使用 `/commit` 时，才触发提交流程。 +- 若已配置自定义提交命令 `/commit` 或 git `prepare-commit-msg` hook，按项目实际配置使用。 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [ai/AI接入入口.md](ai/AI接入入口.md) | CLAUDE.md 指向 AI 接入入口，入口变更需同步 | +| [AGENTS.md](AGENTS.md) | Claude Code 入口与 AGENTS.md 互为替代入口 | +| [RULES.md](RULES.md) | 通用兼容入口需与 CLAUDE.md 保持一致 | diff --git a/README.md b/README.md index d1d5241..93f19ae 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,73 @@ -# UnityAI - StrayFog框架文档中心 +# UnityAI - StrayFog 框架文档中心 -## 📋 文档索引 +本仓库是 **StrayFog 框架的知识库**，同时服务两类读者： -### 01_框架架构 -- [StrayFog框架架构分析](01_框架架构/StrayFog框架架构分析.md) +- **人工开发者**：通过 `modules/frameworks/` 下的框架模块文档和 `rules/` 下的规则文档学习使用 StrayFog 框架。 +- **AI 工具**：通过 `ai/`、`rules/`、`modules/`、`hooks/` 下的规则、模块、hook 文档快速理解框架结构和工作方式。 -### 02_开发规范 -- [开发规范指南](02_开发规范/开发规范指南.md) +--- -### 03_核心功能 -- [对象池使用指南](03_核心功能/对象池使用指南.md) -- [事件系统使用指南](03_核心功能/事件系统使用指南.md) -- [资源管理使用指南](03_核心功能/资源管理使用指南.md) -- [相机系统使用指南](03_核心功能/相机系统使用指南.md) +## 🚀 快速入口 -#### Entity相关 -- [Entity开发指南](03_核心功能/Entity/Entity开发指南.md) - Entity创建规范、生命周期、System-Model架构、属性系统、对象池 -- [UnityEntities注意事项](03_核心功能/Entity/UnityEntities注意事项.md) - 枚举定义、ESM架构、数据表字段映射、动画系统、AI系统、错误处理、架构模式 -- [通用技能系统使用指南](03_核心功能/Entity/通用技能系统使用指南.md) - 通用技能系统架构、使用方法、配置管理、事件系统 +| 读者 | 入口 | +|------|------| +| AI 工具 | [AGENTS.md](AGENTS.md) / [CLAUDE.md](CLAUDE.md) / [RULES.md](RULES.md) → [ai/AI接入入口.md](ai/AI接入入口.md) | +| 人工开发者 | 继续阅读下方中文文档索引 | -#### UI相关 -- [UI开发指南](03_核心功能/UI/UI开发指南.md) - 窗口开发、组件使用、事件绑定、对象池、开发规范 -- [UI界面拼接设计指南](03_核心功能/UI/UI界面拼接设计指南.md) - 界面模块化设计、布局规划、模块组装 +--- -### 04_开发流程 -- [开发流程指南](04_开发流程/开发流程指南.md) -- [最佳实践指南](04_开发流程/最佳实践指南.md) -- [常见问题指南](04_开发流程/常见问题指南.md) +## 🤖 AI 工具说明 -### 05_项目管理 -- [核心库保护规范](05_项目管理/核心库保护规范.md) -- [Git规定指南](05_项目管理/Git规定指南.md) -- [Git提交注意事项](05_项目管理/Git提交注意事项.md) +处理本仓库任务时，AI 工具应： -### 06_工具脚本 -- [UI工具](06_工具脚本/UI工具/) - UI预制体与JSON双向转换工具 +1. 读取 [ai/AI接入入口.md](ai/AI接入入口.md) +2. 读取 [rules/项目规则入口.md](rules/项目规则入口.md) +3. 按需读取 [modules/模块索引.md](modules/模块索引.md) 中的框架模块 +4. 如需了解外部项目业务参考，读取 [business-reference/playballoons/业务框架映射接口.md](business-reference/playballoons/业务框架映射接口.md) + +--- + +## 📋 中文文档索引 + +### 框架架构 +- [通用框架](modules/frameworks/通用框架/README.md) — General/StrayFog Core 通用能力 +- [框架架构分析](modules/frameworks/通用框架/框架架构.md) — StrayFog 整体架构分析 + +### 核心框架 +- [实体系统](modules/frameworks/实体系统/README.md) + - [Entity 开发指南](modules/frameworks/实体系统/开发指南.md) + - [Unity Entities 注意事项](modules/frameworks/实体系统/注意事项.md) +- [技能系统](modules/frameworks/技能系统/README.md) + - [通用技能系统使用指南](modules/frameworks/技能系统/使用指南.md) +- [UI 窗口系统](modules/frameworks/UI窗口系统/README.md) + - [UI 开发指南](modules/frameworks/UI窗口系统/开发指南.md) + - [UI 界面拼接设计指南](modules/frameworks/UI窗口系统/界面拼接.md) +- [事件系统](modules/frameworks/事件系统/README.md) + - [事件系统使用指南](modules/frameworks/事件系统/使用指南.md) +- [对象池与运行时对象管理](modules/frameworks/内存对象管理/README.md) + - [对象池使用指南](modules/frameworks/内存对象管理/使用指南.md) +- [相机系统](modules/frameworks/相机系统/README.md) + - [相机系统使用指南](modules/frameworks/相机系统/使用指南.md) +- [资源管理](modules/frameworks/资源管理/README.md) + - [资源管理使用指南](modules/frameworks/资源管理/使用指南.md) +- [场景系统](modules/frameworks/场景系统.md) +- [网络系统](modules/frameworks/网络系统.md) +- [数据配置框架](modules/frameworks/数据配置框架.md) +- [Hotfix 启动](modules/frameworks/Hotfix启动.md) +- [第三方插件](modules/frameworks/第三方插件.md) + +### 编辑器工具 +- [编辑器工具](modules/frameworks/编辑器工具/README.md) + - [UI 拼接工具](modules/frameworks/编辑器工具/UI拼接工具.md) + +### 项目规则 +- [项目规则入口](rules/项目规则入口.md) +- [架构说明](rules/10-架构说明.md) +- [开发规则](rules/20-开发规则.md) +- [工作流清单](rules/40-工作流清单.md) + +### 编辑器工具脚本 +- [UI 工具](modules/frameworks/编辑器工具/UI工具/) — UI 预制体与 JSON 双向转换工具 --- @@ -42,12 +75,32 @@ | 场景 | 推荐文档 | |-----|---------| -| 新人开发 | `02_开发规范/开发规范指南.md` | -| 使用对象池 | `03_核心功能/对象池使用指南.md` | -| 使用事件系统 | `03_核心功能/事件系统使用指南.md` | -| 遇到问题 | `04_开发流程/常见问题指南.md` | +| 新人开发 | [开发规则](rules/20-开发规则.md) | +| 使用对象池 | [对象池与运行时对象管理](modules/frameworks/内存对象管理/README.md) | +| 使用事件系统 | [事件系统](modules/frameworks/事件系统/README.md) | +| 遇到问题 | [开发规则/常见问题](rules/20-开发规则.md#常见问题) | +| AI 工具接入 | [ai/AI接入入口.md](ai/AI接入入口.md) | + +--- + +## 📦 业务参考 + +- [business-reference/playballoons/](business-reference/playballoons/) — 来自 PlayBalloons 实际项目的业务参考，与 StrayFog 框架核心分离。 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [ai/AI接入入口.md](ai/AI接入入口.md) | AI 工具入口说明 | +| [rules/项目规则入口.md](rules/项目规则入口.md) | 项目规则总入口 | +| [modules/模块索引.md](modules/模块索引.md) | 框架模块索引 | +| [rules/00-项目概览.md](rules/00-项目概览.md) | 项目概览中的人工开发者使用方式 | --- **版本**: v1.0 -**适用项目**: GiftGameX \ No newline at end of file +**适用项目**: GiftGameX diff --git a/RULES.md b/RULES.md new file mode 100644 index 0000000..af499af --- /dev/null +++ b/RULES.md @@ -0,0 +1,21 @@ +# UnityAI 通用入口 + +本文件是给其他 AI、IDE 或人工快速查看的兼容入口。 + +**请先读取：[ai/AI接入入口.md](ai/AI接入入口.md)** + +--- + +> 本文件仅保留为兼容入口，不重复维护项目规则内容。 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [ai/AI接入入口.md](ai/AI接入入口.md) | RULES.md 是 AI 接入入口的兼容重定向 | +| [AGENTS.md](AGENTS.md) | AI 工具入口之一，需与 RULES.md 保持一致 | +| [CLAUDE.md](CLAUDE.md) | Claude Code 入口，需与 RULES.md 保持一致 | \ No newline at end of file diff --git a/ai/AI接入入口.md b/ai/AI接入入口.md new file mode 100644 index 0000000..018d65f --- /dev/null +++ b/ai/AI接入入口.md @@ -0,0 +1,65 @@ +# AI 工具接入入口 + +本文件是 UnityAI / StrayFog 框架知识库面向 Codex、Claude Code、Cursor、Windsurf、GitHub Copilot 等 AI / IDE 工具的统一接入说明。 + +根目录入口文件只做适配和跳转： + +- `AGENTS.md`：Codex 默认项目入口。 +- `CLAUDE.md`：Claude Code 默认项目入口。 +- `RULES.md`：通用兼容入口，给其他 AI、IDE 或人工快速查看。 + +这些入口文件不要复制项目规则；真实内容统一维护在 ai/rules/modules/hooks/ 下。 + +## 所有 AI 先读 + +处理本项目任务时，按顺序读取： + +1. [项目规则入口](../rules/项目规则入口.md) +2. [项目知识入口](../modules/模块索引.md) +3. [共享 hook 入口](../hooks/Hook共享层.md) + +然后根据任务范围按需读取具体规则、模块、spec、plan 或 hook 文档。 + +## 文档分层 + +| 层级 | 文档 | 用途 | +|---|---|---| +| AI 接入层 | `ai/AI接入入口.md` | 说明不同 AI / IDE 工具如何进入项目 | +| 项目规则层 | `rules/项目规则入口.md` | 工作方式、扫描范围、任务流程、归档规则 | +| 项目知识层 | `modules/模块索引.md` | 项目框架、核心功能、编辑器工具总入口 | +| 业务参考层 | `business-reference/` | 外部实际项目业务参考，与框架核心分离 | +| Hook 共享层 | `hooks/Hook共享层.md` | 共享 hook 原则、检查脚本、触发方式 | +| Spec / Plan 层 | `specs/Spec索引.md`、`plans/` | 大需求、新模块、跨模块计划和归档 | + +## Hook 接入原则 + +- 共享 hook 规则、脚本和文档关联逻辑统一放在 `hooks/`。 +- 各 AI 工具自己的目录只放适配器，不重复维护 hook 逻辑。 +- 若已配置 Codex，适配器 `.codex/hooks/archive-reminder.ps1` 可调用 `hooks/archive-check.ps1`。 +- Claude Code 可以通过 command / hook 配置调用 `hooks/archive-check.ps1`。 +- 只有用户明确说“提交”“提交代码”“commit”时，才触发提交流程。 +- 若项目配置了自定义提交命令 `/commit` 或 git `prepare-commit-msg` hook，按实际配置使用，默认提交信息格式为 `[模块][feat]:内容描述`。 +- 如需在关联文档中自动留下变更提醒，可调用 `hooks/sync-doc-associations.ps1`（只追加、不覆盖，执行后需 review）。 +- 其他 AI / IDE 如果支持任务结束 hook，也应调用 `hooks/archive-check.ps1`。 +- 如果某个工具不支持自动 hook，任务结束时手动运行或按 `hooks/Hook共享层.md` 执行归档检查。 + +## 新接入 AI 工具时 + +1. 确认该工具默认读取什么入口文件。 +2. 如果该工具有默认入口文件，只在入口文件中指向 `ai/AI接入入口.md`。 +3. 如果该工具支持 hook，配置它调用 `hooks/archive-check.ps1`。 +4. 不要把 `rules/`、`modules/`、`hooks/` 的内容复制进工具私有目录。 +5. 如需新增工具专属说明，只写适配方式，不写项目规则副本。 + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [AGENTS.md](../AGENTS.md) | Codex 入口应指向本 AI 接入入口 | +| [CLAUDE.md](../CLAUDE.md) | Claude Code 入口应指向本 AI 接入入口 | +| [RULES.md](../RULES.md) | 通用兼容入口应指向本 AI 接入入口 | +| [rules/项目规则入口.md](../rules/项目规则入口.md) | 项目规则入口由本文档引用 | +| [modules/模块索引.md](../modules/模块索引.md) | 项目知识入口由本文档引用 | +| [hooks/Hook共享层.md](../hooks/Hook共享层.md) | 共享 hook 入口由本文档引用 | diff --git a/business-reference/playballoons/features/GM调试.md b/business-reference/playballoons/features/GM调试.md new file mode 100644 index 0000000..d0417f2 --- /dev/null +++ b/business-reference/playballoons/features/GM调试.md @@ -0,0 +1,134 @@ +# GM/调试功能 + +## 分类 + +- 项目功能 + +## 目的 + +记录 GM 面板、调试请求、测试入口和开发验证流程。 + +## 已知线索 + +- UI 路径：`Assets/Game/GameHFScripte/GameFunction/UIWindows/GMWindow/` +- 背包数据：`GMWindow_BagData.cs` +- 请求配置：`GMWindow_GM.cs` +- 能看到背包、战斗、商店等调试请求线索。 + +## 已确认内容 + +窗口定义： + +```text +GMWindow : AbsHFUIWindow + -> [HFAssetBundlePath(..., "UIWindows/GMWindow/GMWindow.prefab")] + -> [HFUIWindowLayer(UIWindow, Popup)] +``` + +生命周期： + +```text +GMWindow.OnRunAwake() + -> OnRunAwake_BagData() + -> OnRunAwake_GM() + +GMWindow.OnOpen() + -> OnOpen_BagData() + -> OnOpen_GM() + +GMWindow.OnClose() + -> OnClose_BagData() + -> OnClose_GM() +``` + +GM 请求结构： + +```text +GM_Network_MsgId + -> msgId : Network_MsgId + -> tip + -> args : List + +GM_Network_MsgId_Arg + -> tip + -> contentType + -> value +``` + +发送链路： + +```text +点击 btnSendGM + -> OnSendGM() + -> new GMC2S() + -> gmC2S.Msgid = (int)selected.msgId + -> gmC2S.Args.AddRange(...) + -> HFSeverManager.Instance.SendMsg(gmC2S) +``` + +当前 GM 覆盖范围： + +- 背包： + - 请求背包数据：`GetBagItem` + - 添加道具：`PlayerResourceChange` +- 关卡： + - `BattleLevelEnter` + - `BattleLevelExit` + - `BattleLevelWin` + - `BattleLevelFail` +- 用户外围数据： + - 设置关卡完成波数：`SetUserRolePeripheryLevelWaveProgress` + - 领取用户关卡进度奖励：`UserRolePeripheryClaimedProgressReward1Reward` +- 时间： + - `GetServerTimeStamp` +- 宝箱： + - 添加用户宝箱：`AddUserRolePeripheryTreasureChest` + - 删除用户宝箱：`DelUserRolePeripheryTreasureChest` + - 获取/开启/领取/结束冷却相关操作存在注释。 +- 商店： + - `SetDailyFeaturedTotalRefreshCount` 使用硬编码 `(Network_MsgId)7090`。 +- Tower： + - 上阵、下阵、升级、添加 Tower 的 GM 配置块存在，但全部注释。 + +当前接入状态： + +- GMWindow 本身是完整 UI 窗口。 +- GM 请求通过统一 `GMC2S` 包装真实业务 `Network_MsgId` 和参数。 +- 未看到明显的开发环境开关；MainWindow 中 GM 按钮也有编辑器开关注释，当前入口是否开放待确认。 + +## 梳理任务 + +- [ ] 梳理 GMWindow 打开入口。 +- [x] 梳理 GM 请求结构和参数配置。 +- [x] 梳理 GM 对背包、PVE、商店等功能的覆盖范围。 +- [ ] 梳理 GM 功能是否只在开发环境启用。 +- [x] 梳理 GM 请求和网络框架的关系。 + +## 待确认 + +- GMWindow 的正式打开入口待确认。 +- 是否有权限/环境开关待确认。 +- 是否允许线上包保留 GM 面板待确认。 +- GM 操作通过服务器 GM 协议，有修改服务器数据的能力风险，需要上线前明确禁用策略。 + +## 相关框架 + +- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md) +- [网络框架](../../../modules/frameworks/网络系统.md) +- [事件框架](../../../modules/frameworks/事件系统/README.md) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 | +| [modules/frameworks/事件系统/README.md](../../../modules/frameworks/事件系统/README.md) | 事件框架 | +| [modules/frameworks/网络系统.md](../../../modules/frameworks/网络系统.md) | 网络框架 | +| [modules/frameworks/UI窗口系统/README.md](../../../modules/frameworks/UI窗口系统/README.md) | UI 框架 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | +| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 | \ No newline at end of file diff --git a/business-reference/playballoons/features/PVE关卡战斗.md b/business-reference/playballoons/features/PVE关卡战斗.md new file mode 100644 index 0000000..9d77a0b --- /dev/null +++ b/business-reference/playballoons/features/PVE关卡战斗.md @@ -0,0 +1,94 @@ +# PVE/关卡战斗 + +## 分类 + +- 项目功能 + +## 目的 + +记录 PVE 关卡进入、战斗流程、胜负结算、波次和奖励逻辑。 + +## 已知线索 + +- 逻辑路径：`Assets/Game/GameHFScripte/GameFunction/Logic/GameScenes/` +- 地图路径：`Assets/Game/GameHFScripte/GameFunction/Logic/MapManager/` +- 伤害路径：`Assets/Game/GameHFScripte/GameFunction/Logic/DamageManager/` +- 地图资源：`Assets/Game/GameHFResource/CN/Map/` +- 网络消息线索：`BattleLevelEnter`、`BattleLevelExit`、`BattleLevelWin`、`BattleLevelFail` +- 配置线索：`XLSX_SRC/CN/Wave.xlsx` + +## 已确认内容 + +当前 PVE/关卡战斗处于“有核心框架和协议线索，但主流程接入不完整或待确认”的状态。 + +已确认的子系统： + +- `HFWaveManager`：从 `HFFunCatalogue.NDB.ds_WaveD0D9AA20TableData.ReadTableList()` 读取波次配置。 +- `WaveInfo`：根据 `WaveTime`、`WaveID`、`WaveHpInc`、`GateFirst` 生成波次信息。 +- `CreateMonsterInfo`：解析 `start_end_delay_monsterId_count` 格式的发怪配置。 +- `HFMapManager.CreateMap(levelid, finish)`：当前会先 `ClearMap()`，再通过 `HFFunCatalogue.Asset.LoadAsset(1501, ...)` 加载地图 prefab。 +- `HFDamageManager`：存在伤害计算、掉落、死亡事件、HUD 飘字逻辑，但大部分实现当前被注释。 +- 网络协议和事件已生成：`BattleLevelEnter`、`BattleLevelExit`、`BattleLevelWin`、`BattleLevelFail`。 + +`HFWaveManager` 当前有 Editor GUI 调试入口： + +```text +OnRunGUI + -> 按钮“游戏开始” + -> InitCampWaveInfo(Red/Blue) + -> TryCreateMonster +``` + +`OnRunFixedUpdate` 每秒尝试发怪： + +```text +OnRunFixedUpdate + -> TryCreateMonster + -> CampWaveInfo.TryCreateMonster + -> WaveInfo.TryCreateMonster + -> CreateMonsterInfo.TryCreateMonster +``` + +## 梳理任务 + +- [ ] 找到 PVE 入口：从主界面、地图或 GM 进入关卡的调用点。 +- [ ] 梳理关卡状态：进入、战斗中、胜利、失败、退出。 +- [x] 梳理波次配置和怪物/实体生成关系。 +- [x] 梳理伤害计算和实体框架之间的关系。 +- [ ] 梳理结算奖励如何进入背包和奖励展示。 +- [x] 梳理 PVE 相关网络消息和事件。 + +## 待确认 + +- 是否有明确的 PVE manager。 +- 战斗是纯本地模拟、服务器校验，还是服务器主导。 +- `GameScenes`、`MapManager`、`LineManager` 在 PVE 中的边界。 +- `HFMapManager.CreateMap` 的 `levelid` 当前未用于读表，资源 id 固定为 `1501`，是否临时逻辑待确认。 +- `HFWaveManager` 是否只通过 Editor GUI 调试启动，还是存在运行时入口待确认。 +- `HFDamageManager` 大量逻辑被注释，当前战斗伤害是否启用待确认。 + +## 相关框架 + +- [实体框架](../../../modules/frameworks/实体系统/README.md) +- [场景框架](../../../modules/frameworks/场景系统.md) +- [网络框架](../../../modules/frameworks/网络系统.md) +- [事件框架](../../../modules/frameworks/事件系统/README.md) +- [数据/配置框架](../../../modules/frameworks/数据配置框架.md) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 | +| [modules/frameworks/数据配置框架.md](../../../modules/frameworks/数据配置框架.md) | 数据/配置框架 | +| [modules/frameworks/实体系统/README.md](../../../modules/frameworks/实体系统/README.md) | 实体框架 | +| [modules/frameworks/事件系统/README.md](../../../modules/frameworks/事件系统/README.md) | 事件框架 | +| [modules/frameworks/网络系统.md](../../../modules/frameworks/网络系统.md) | 网络框架 | +| [modules/frameworks/场景系统.md](../../../modules/frameworks/场景系统.md) | 场景框架 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | +| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 | \ No newline at end of file diff --git a/business-reference/playballoons/features/PVP.md b/business-reference/playballoons/features/PVP.md new file mode 100644 index 0000000..8ff7065 --- /dev/null +++ b/business-reference/playballoons/features/PVP.md @@ -0,0 +1,80 @@ +# PVP + +## 分类 + +- 项目功能 + +## 目的 + +记录 PVP 是否存在、入口、协议、匹配、战斗和结算流程。 + +## 已知线索 + +- 当前未在初步扫描中发现明确的 PVP 目录或关键词。 + +## 已确认内容 + +已搜索关键词： + +- `PVP` +- `PvP` +- `pvp` +- `Arena` +- `Rank` +- `Duel` +- `竞技` +- `排行` +- `匹配` + +搜索范围： + +- `Assets/Game/GameHFScripte/` +- `Assets/AutoBuildScript/` +- `XLSX_SRC/` +- `Assets/Editor/XLSX_SRC/` + +结果： + +- 未发现明确 PVP / 竞技场 / 排行 / 匹配业务代码。 +- 未发现 PVP 相关 UIWindow。 +- 未发现 PVP 相关配置表。 +- 未发现 PVP 相关 protobuf 消息。 +- 搜到的“匹配”均为正则匹配工具注释，不属于业务功能。 + +当前判断： + +- 当前工程未发现 PVP 实现。 +- 该模块目前只作为规划/占位模块保留。 + +## 梳理任务 + +- [x] 全局搜索 PVP、Arena、Match、Rank、Opponent 等关键词。 +- [x] 检查 protobuf 是否有 PVP/匹配/排行相关消息。 +- [x] 检查配置表是否有 PVP、竞技场或排行配置。 +- [x] 检查 UIWindows 是否有隐藏或未接入的 PVP 窗口。 +- [ ] 确认项目当前是否规划 PVP。 + +## 待确认 + +- 是否产品规划中存在 PVP。 +- 如果短期不做，可以从模块索引移除，或保持为“规划占位”。 + +## 相关框架 + +- [网络框架](../../../modules/frameworks/网络系统.md) +- [PVE/关卡战斗](PVE关卡战斗.md) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 | +| [modules/features/PVE关卡战斗.md](PVE关卡战斗.md) | PVE/关卡战斗 | +| [modules/frameworks/网络系统.md](../../../modules/frameworks/网络系统.md) | 网络框架 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | +| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 | \ No newline at end of file diff --git a/business-reference/playballoons/features/商店.md b/business-reference/playballoons/features/商店.md new file mode 100644 index 0000000..c0e3eeb --- /dev/null +++ b/business-reference/playballoons/features/商店.md @@ -0,0 +1,128 @@ +# 商店 + +## 分类 + +- 项目功能 + +## 目的 + +记录商店商品、购买、货币消耗、体力/资源购买和商店 UI 入口。 + +## 已知线索 + +- GM 线索：`Assets/Game/GameHFScripte/GameFunction/UIWindows/GMWindow/GMWindow_GM.cs` 中有商店模块注释。 +- Tips 线索：`Tips_GetPower` 引用 `ShopGoodsInfo`。 +- 图集线索：`SpriteAtlasAssets/Shop` +- 代码中可见 `ShopWindow`、`ShopGetCurrency` 注释引用。 + +## 已确认内容 + +协议和数据结构已生成： + +- `Network_MsgId.GetShop = 2500` +- `Network_MsgId.ShopBuy = 2501` +- `Network_MsgId.ShopRefresh = 2502` +- `HFEvent_STC_GetShopS2C` +- `HFEvent_STC_ShopBuyS2C` +- `HFEvent_STC_ShopRefreshS2C` + +请求/响应字段： + +```text +GetShopC2S + -> ShopId +GetShopS2C + -> repeated ShopInfo + +ShopBuyC2S + -> GoodsId + -> BuyType +ShopBuyS2C + -> ShopId + -> Goods + -> Item + +ShopRefreshC2S + -> ShopId + -> RefreshType +ShopRefreshS2C + -> Shop +``` + +核心数据结构在： + +- `Assets/Game/GameHFScripte/CopyToHF/Network/Player.cs` +- `Assets/Game/GameHFScripte/CopyToHF/Network/Common.cs` + +```text +ShopInfo + -> ShopId + -> RefreshInfo : Map + -> Goods : Map + +ShopGoodsInfo + -> GoodsId + -> BuyNum : Map + -> Item + +ShopRefreshInfo + -> RefreshType + -> RefreshNum + +GoodsBuyNumInfo + -> BuyType + -> BuyNum +``` + +体力购买相关： + +- `Tips_GetPower` 是当前能看到的体力购买/领取 UI 线索。 +- `Tips_GetPower` 读取 `Constants.PurchaseStamina`。 +- `Tips_GetPower` 监听 `HFEvent_BagItemUpdate` 刷新展示。 +- `Stamina_QueryC2S` / `Stamina_GetC2S` 协议已生成，但当前未看到实际发送点。 + +当前接入状态： + +- `MainWindow` 中 `OpenWindow`、`ShopGetCurrency`、`Tips_GetPower` 入口大多处于注释状态。 +- 未发现 `GetShopC2S`、`ShopBuyC2S`、`ShopRefreshC2S` 在业务代码中的实际发送点。 +- 未发现独立商店 manager。 +- 因此当前判断：商店协议和部分 UI/资源痕迹存在，但客户端业务主流程未完整接入或处于注释/待开发状态。 + +## 梳理任务 + +- [x] 查找是否存在独立商店 manager、window 或配置表。 +- [x] 梳理商品数据结构和 `ShopGoodsInfo` 来源。 +- [ ] 梳理购买流程：打开、选择、校验、扣费、到账。 +- [x] 梳理商店与背包、资源、体力之间的关系。 +- [x] 确认当前商店功能是完整实现、部分接入还是已注释/待开发。 + +## 待确认 + +- 是否存在未纳入当前工程的 `ShopWindow`、`ShopGetCurrency` 或旧分支代码。 +- 是否存在 `Shop.xlsx`、`Goods.xlsx`、`DailyDeals.xlsx` 等相关配置；当前配置列表未登记这些表，但生成代码里有旧表痕迹。 +- 商店是否区分普通商店、体力购买、礼包、广告等类型。 +- 商店 UI 当前看起来未接入，需要后续确认是否是产品阶段未启用。 + +## 相关框架 + +- [背包](背包.md) +- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md) +- [网络框架](../../../modules/frameworks/网络系统.md) +- [数据/配置框架](../../../modules/frameworks/数据配置框架.md) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 | +| [modules/features/背包.md](背包.md) | 背包 | +| [modules/frameworks/数据配置框架.md](../../../modules/frameworks/数据配置框架.md) | 数据/配置框架 | +| [modules/frameworks/网络系统.md](../../../modules/frameworks/网络系统.md) | 网络框架 | +| [modules/frameworks/UI窗口系统/README.md](../../../modules/frameworks/UI窗口系统/README.md) | UI 框架 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | +| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 | \ No newline at end of file diff --git a/business-reference/playballoons/features/地图进度.md b/business-reference/playballoons/features/地图进度.md new file mode 100644 index 0000000..53805d7 --- /dev/null +++ b/business-reference/playballoons/features/地图进度.md @@ -0,0 +1,148 @@ +# 地图/关卡进度 + +## 分类 + +- 项目功能 + +## 目的 + +记录地图、关卡、波次、进度奖励和关卡状态。 + +## 已知线索 + +- 地图逻辑：`Assets/Game/GameHFScripte/GameFunction/Logic/MapManager/` +- 关卡资源：`Assets/Game/GameHFResource/CN/Map/Level.prefab` +- 配置线索：`XLSX_SRC/CN/Wave.xlsx` +- 网络线索：`UserRolePeripheryProgressReward*` + +## 已确认内容 + +地图加载： + +```text +HFMapManager.CreateMap(levelid, finish) + -> ClearMap() + -> HFFunCatalogue.Asset.LoadAsset(1501) + -> GetOrAddComponent() + -> OnSetFinishLoad() +``` + +当前 `CreateMap` 传入了 `levelid`，但实际读取关卡配置的代码被注释： + +```text +// MapInfo = HFFunCatalogue.NDB.ds_Level83D033B2TableData.ReadTableByPK(levelid); +``` + +地图配置数据： + +- `stMapInfo` 使用 `MemoryPack`，包含障碍物/实体位置列表 `ObstaclesPos`。 +- `stMapEntityInfo` 包含 `Postion`、`EntityId`、`CellIndexs`。 +- `HF_MapEditor` 可以保存/读取地图配置文件到 `Assets/Game/GameHFResource/CN/MapInfoData/.txt`，但实体加载/放置代码大多处于注释状态。 +- `HFM_MapSetting` 记录地图出生点、终点、Hero 引用。 +- `HF_WaveInfo` 记录波次中的起止时间、怪物 id、数量和 Boss 卡显示等。 + +关卡/波次协议： + +- `GetLevelInfo = 3004` +- `GetLevelWaveReward = 3005` +- `BattleLevelEnter = 3000` +- `BattleLevelExit = 3001` +- `BattleLevelWin = 3002` +- `BattleLevelFail = 3003` + +字段线索： + +```text +GetLevelInfoS2C + -> Levels + +GetLevelWaveRewardC2S + -> Id + -> Wave +GetLevelWaveRewardS2C + -> Level + -> Item + +BattleLevelEnterC2S + -> Id +BattleLevelWinC2S + -> Id + -> ChestType + -> KillMons + -> MaxWave +BattleLevelFailC2S + -> Id + -> MaxWave + -> KillMons +``` + +外围进度奖励协议： + +- `GetUserRolePeripheryProgressReward1Data = 5000` +- `UserRolePeripheryClaimedProgressReward1Reward = 5001` +- `SetUserRolePeripheryLevelWaveProgress = 5901`，当前主要在 GM 调试入口看到。 + +字段线索： + +```text +UserRolePeripheryDataProgressReward1 + -> LevelId + -> MaxWave + -> State + -> ClaimedWave + +GetUserRolePeripheryProgressReward1DataS2C + -> ProgressReward1 : repeated UserRolePeripheryDataProgressReward1 + +UserRolePeripheryClaimedProgressReward1RewardC2S + -> LevelId +UserRolePeripheryClaimedProgressReward1RewardS2C + -> Rewards : Map +``` + +当前接入状态： + +- PVE 战斗内波次由 `HFWaveManager` 读取 `Wave.xlsx`，属于战斗流程。 +- 地图/关卡进度协议已生成，但业务 UI 和普通发送链路未确认。 +- `GMWindow_GM.cs` 中有外围进度设置和领取奖励调试入口。 +- 地图编辑器、关卡配置、地图实体摆放等代码保留较多注释，当前更像半接入/调试状态。 + +## 梳理任务 + +- [x] 梳理地图/关卡数据结构。 +- [ ] 梳理关卡解锁、当前关卡、已通关状态。 +- [x] 梳理波次和关卡配置的关系。 +- [x] 梳理进度奖励领取条件和网络消息。 +- [ ] 梳理地图进度如何驱动主界面或 PVE 入口。 + +## 待确认 + +- 地图是否有章节/大关/小关层级；`ChapterWindow` 有注释入口，但当前未确认实装。 +- `Level` 相关配置表是否为旧表残留或当前未登记源表。 +- 关卡进度是否全部由服务器维护。 +- `GetLevelWaveReward` 与外围进度奖励 `ProgressReward1` 的产品边界。 +- 地图进度如何驱动主界面或 PVE 入口。 + +## 相关框架 + +- [PVE/关卡战斗](PVE关卡战斗.md) +- [数据/配置框架](../../../modules/frameworks/数据配置框架.md) +- [网络框架](../../../modules/frameworks/网络系统.md) +- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 | +| [modules/features/PVE关卡战斗.md](PVE关卡战斗.md) | PVE/关卡战斗 | +| [modules/frameworks/数据配置框架.md](../../../modules/frameworks/数据配置框架.md) | 数据/配置框架 | +| [modules/frameworks/网络系统.md](../../../modules/frameworks/网络系统.md) | 网络框架 | +| [modules/frameworks/UI窗口系统/README.md](../../../modules/frameworks/UI窗口系统/README.md) | UI 框架 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | +| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 | \ No newline at end of file diff --git a/business-reference/playballoons/features/塔养成.md b/business-reference/playballoons/features/塔养成.md new file mode 100644 index 0000000..0948e3b --- /dev/null +++ b/business-reference/playballoons/features/塔养成.md @@ -0,0 +1,123 @@ +# 塔/角色养成 + +## 分类 + +- 项目功能 + +## 目的 + +记录塔、角色或卡片的升级、升星、技能升级、展示和养成配置。 + +## 已知线索 + +- 逻辑路径：`Assets/Game/GameHFScripte/GameFunction/Logic/TowerLevelUpManager/` +- 逻辑路径：`Assets/Game/GameHFScripte/GameFunction/Logic/TowerSkillUpManager/` +- UI 路径：`Assets/Game/GameHFScripte/GameFunction/UIWindows/AvatarItem/` +- 配置线索：`XLSX_SRC/CN/EntityConfig.xlsx` +- 配置线索：`XLSX_SRC/CN/SkillGroup.xlsx`、`SkillReleaser.xlsx`、`SkillTrigger.xlsx`、`SkillUp.xlsx` + +## 已确认内容 + +启动初始化： + +```text +HFGameStart.InitManager() + -> HFTowerStarUpManager.Instance + -> HFTowerSkillUpManager.Instance +``` + +协议已生成： + +- `GetPlayerTower = 4000` +- `TowerLevelFormation = 4001` +- `TowerLevelUpLv = 4002` +- route： + - `game.player.getTower` + - `game.player.formationTower` + - `game.player.levelUpTower` + +请求/响应字段： + +```text +GetPlayerTowerC2S + -> 无主要字段 +GetPlayerTowerS2C + -> Formation : repeated long + +TowerLevelFormationC2S + -> Formation : repeated long +TowerLevelFormationS2C + -> Formation : repeated long + +TowerLevelUpLvC2S + -> Id +TowerLevelUpLvS2C + -> Id + -> Formation : repeated long +``` + +STC 事件： + +- `HFEvent_STC_GetPlayerTowerS2C` +- `HFEvent_STC_TowerLevelFormationS2C` +- `HFEvent_STC_TowerLevelUpLvS2C` + +配置和实体侧线索： + +- `Constants` 中有塔相关字段：`BossTowerCardNum`、`BossTowerGetNum`、`TowerRange`、`TowerRectangle`、`NewTowerInitLevel`、`TowerPutEffect*`、`LucySpinSameTower` 等。 +- 实体侧会读取 `EntityConfig`、`Resource`、`SkillGroup`、`SkillReleaser`、`SkillTrigger` 等表来驱动塔实体、模型、AI、技能。 +- 历史/生成代码里存在 `Tower`、`Towerlevel`、`StarUpgrade`、`CardWeight` 等表的读取痕迹，但当前 `ZYXlsxProjectSettings` 登记的 CN 表没有显式列出这些源表，需要确认是否是旧生成残留或表源未纳入当前列表。 + +当前接入状态： + +- `HFTowerStarUpManager` 主体逻辑几乎全部注释，包括选择塔、显示升级 HUD、读取 `StarUpgrade`、修改实体属性等。 +- `HFTowerSkillUpManager` 主体逻辑也处于注释状态，包括监听 `HFEvent_TowerSkillState` 并修改实体技能能力。 +- `AvatarItem` 的资源路径 attribute 被注释，当前更像 MainWindow 内嵌组件；`SetAvatarFrame` 尚未实装。 +- `CardItem` 有卡片 UI 基础绑定，但 `SetData` 为空。 +- 未发现 `GetPlayerTowerC2S`、`TowerLevelFormationC2S`、`TowerLevelUpLvC2S` 在业务代码中的实际发送点。 + +当前判断： + +- “塔/角色养成”协议、配置痕迹、实体战斗联动线索都存在。 +- 客户端养成主流程当前未完整实装，或被注释保留。 +- 运行中的塔更偏战斗实体/技能系统；大厅养成、编队、升级 UI 还需要进一步确认产品接入状态。 + +## 梳理任务 + +- [x] 确认“塔”“角色”“卡片”在代码和配置中的对应概念。 +- [x] 梳理塔升级和技能升级的入口。 +- [ ] 梳理升级消耗和背包资源关系。 +- [x] 梳理 Avatar/Card UI 展示数据来源。 +- [x] 梳理养成数据是否同步服务器。 + +## 待确认 + +- `TowerLevelUpManager` / `TowerSkillUpManager` 当前初始化但主体逻辑被注释，需确认是否计划恢复。 +- 升级、升星、技能升级是否属于同一产品功能域，需要结合 UI/策划表确认。 +- 升级消耗、卡片碎片、背包资源之间的真实关系待确认。 +- 养成结果如何同步并影响 PVE 实体属性，需要确认服务端返回和客户端应用链路。 +- `Tower`、`Towerlevel`、`StarUpgrade`、`CardWeight` 等表是否是旧表残留或当前缺失源表。 + +## 相关框架 + +- [实体框架](../../../modules/frameworks/实体系统/README.md) +- [背包](背包.md) +- [数据/配置框架](../../../modules/frameworks/数据配置框架.md) +- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 | +| [modules/features/背包.md](背包.md) | 背包 | +| [modules/frameworks/数据配置框架.md](../../../modules/frameworks/数据配置框架.md) | 数据/配置框架 | +| [modules/frameworks/实体系统/README.md](../../../modules/frameworks/实体系统/README.md) | 实体框架 | +| [modules/frameworks/UI窗口系统/README.md](../../../modules/frameworks/UI窗口系统/README.md) | UI 框架 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | +| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 | \ No newline at end of file diff --git a/business-reference/playballoons/features/奖励道具.md b/business-reference/playballoons/features/奖励道具.md new file mode 100644 index 0000000..ca82c57 --- /dev/null +++ b/business-reference/playballoons/features/奖励道具.md @@ -0,0 +1,105 @@ +# 奖励/道具展示 + +## 分类 + +- 项目功能 + +## 目的 + +记录通用奖励、道具展示、资源展示、弹窗提示和奖励到账表现。 + +## 已知线索 + +- 奖励提示：`Assets/Game/GameHFScripte/GameFunction/UIWindows/Tips/Tips_CommonReward.cs` +- 资源组件：`Assets/Game/GameHFScripte/GameFunction/UIWindows/Components/ResourceItem.cs` +- 道具 UI：`Assets/Game/GameHFScripte/GameFunction/UIWindows/Item/` +- 配置线索：`XLSX_SRC/CN/Gift.xlsx`、`Resource.xlsx` + +## 已确认内容 + +通用入口： + +```text +HFFunCatalogue.Tips.ShowCommonRewardTips(reward, cardReward) + -> HFFunCatalogue.UIManager.OpenWindow() + -> Tips_CommonReward.SetData(reward, cardReward) +``` + +定义位置： + +- `Assets/Game/GameHFScripte/GameFunction/Logic/UI/HFFunCatalogue_UI_TipsManager.cs` +- `Assets/Game/GameHFScripte/GameFunction/UIWindows/Tips/Tips_CommonReward.cs` + +奖励数据结构： + +- `Tips_CommonReward.SetData` 接收 `RepeatedField`。 +- `BagItem` 来自网络 protobuf。 +- 当前代码中把奖励分成 `cards` 和 `items` 的逻辑存在，但核心分类代码被注释： + - 原计划通过 `Item` 配置表判断 `enItemType.Tower`。 + - 当前 `ZYXlsxProjectSettings` 未登记 `Item.xlsx`，但旧代码里有 `ds_Item860D2A9ETableData` 痕迹。 + +展示组件： + +- `Tips_CommonReward` + - 标题固定设置为 `REWARDS`。 + - `ResourceItem` 当前固定调用 `SetData(1)` 展示顶部资源。 + - 普通道具用 `ItemIcon` 池展示。 + - 卡片奖励区域逻辑存在，但资源设置代码被注释。 +- `ResourceItem` + - 监听 `HFEvent_InitBag`。 + - 通过 `HFFunCatalogue.Bag.GetGameResourceCount(resourceId)` 展示资源数量。 + - 资源变化动画和主动刷新事件逻辑存在注释。 +- `Tips_UnlockTower` + - 用于解锁塔/卡片提示。 + - 当前读 `Tower` / `Item` 配置和设置图标的代码被注释。 + +配置线索： + +- `Gift.xlsx` 已登记到 ZYXlsx，生成 `Gift14537B33Sheet1`。 +- `Resource.xlsx` 已登记到 ZYXlsx，生成 `Resource840C5F09TableData`。 +- `Constants.xlsx` 中有奖励相关字段：`LuckyLootRewardTimes`、`LoginUsersItem`、`QuickOfflineReward`、`FreeOfflineReward` 等。 + +当前接入状态： + +- 通用奖励弹窗入口存在。 +- 奖励 UI 框架存在，但道具/卡片配置读取大量注释。 +- 入包逻辑不在奖励弹窗里，当前主要由背包/服务器推送 `PlayerResourceChangeS2C` 更新。 + +## 梳理任务 + +- [x] 梳理奖励数据结构和展示入口。 +- [x] 梳理奖励中道具、卡片、资源的分类。 +- [x] 梳理奖励展示和背包更新的先后关系。 +- [x] 梳理通用 Tips 的打开方式和资源加载方式。 +- [ ] 梳理奖励来源：PVE、任务、商店、GM 或其他系统。 + +## 待确认 + +- 奖励展示当前看起来只负责表现，不负责入包；仍需结合具体领取协议确认。 +- `Gift.xlsx` 和实际奖励结构的对应关系待确认。 +- `Item.xlsx` / `Tower.xlsx` 是否是旧表残留或当前缺失源表。 +- 飞图事件 `HFEvent_FlyIcon` 存在，但实际调用链待继续确认。 + +## 相关框架 + +- [背包](背包.md) +- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md) +- [资源框架](../../../modules/frameworks/资源管理/README.md) +- [数据/配置框架](../../../modules/frameworks/数据配置框架.md) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 | +| [modules/features/背包.md](背包.md) | 背包 | +| [modules/frameworks/数据配置框架.md](../../../modules/frameworks/数据配置框架.md) | 数据/配置框架 | +| [modules/frameworks/资源管理/README.md](../../../modules/frameworks/资源管理/README.md) | 资源框架 | +| [modules/frameworks/UI窗口系统/README.md](../../../modules/frameworks/UI窗口系统/README.md) | UI 框架 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | +| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 | \ No newline at end of file diff --git a/business-reference/playballoons/features/登录.md b/business-reference/playballoons/features/登录.md new file mode 100644 index 0000000..1615016 --- /dev/null +++ b/business-reference/playballoons/features/登录.md @@ -0,0 +1,167 @@ +# 登录 + +## 分类 + +- 项目功能 + +## 目的 + +记录登录流程、登录窗口、网络交互和进入游戏后的衔接关系。 + +## 关键文件 + +| 用途 | 路径 | 说明 | +|---|---|---| +| 登录管理器 | `Assets/Game/GameHFScripte/GameFunction/Logic/Login/HFLoginManager.cs` | 单例，负责连接服务器、发送登录协议、处理登录后事件链 | +| 登录窗口 | `Assets/Game/GameHFScripte/GameFunction/UIWindows/Login/LoginWindow.cs` | 继承 `AbsHFUIWindow`，绑定输入框和登录按钮 | +| 登录 Prefab | `Assets/Game/GameHFResource/UIWindows/Login/LoginWindow.prefab` | 窗口资源，由 `HFAssetBundlePath` 指定 | +| 启动入口 | `Assets/Game/GameHFScripte/GameFunction/GameRoot/HFGameStart.cs`（待确认） | 初始化 manager 并打开 `LoginWindow` | + +## 数据流 + +```text +[启动] +HFGameStart.InitManager + -> OpenWindow + +[用户点击] +LoginWindow.OnBtnLogin + -> 校验用户名非空 + -> PlayerPrefs 保存用户名/密码 + -> HFLoginManager.Instance.Login(InputName.text) + +[连接服务器] +HFLoginManager.Login(account) + -> UNITY_EDITOR 下读取 EditorPrefs["IPData"] 覆盖 IP + -> HFSeverManager.ReConnect(OnReConnect) + -> HFSeverManager.Connect(MainConnect, WebSocket, m_IP, m_Port, m_Token, callback) + -> 连接成功后 OnSendLogin + +[登录协议] +OnSendLogin + -> LoginAuthC2S + ServerId = 10001 + Token = m_Token + Pid = "2126001" + UserName = m_Account + Password = m_Account + +[服务端响应链] +LoginAuthS2C (ErrorCode == 0) + -> PlayerSelectC2S + -> PlayerSelectS2C + 有角色：PlayerEnterC2S + 无角色：PlayerCreateC2S -> PlayerEnterC2S + -> PlayerEnterS2C + -> PlayerFlushC2S(All = true) + -> RequestLoginData 触发后续背包、资源等初始化 +``` + +## 关键协议 + +- `LoginAuthC2S` / `LoginAuthS2C` +- `PlayerSelectC2S` / `PlayerSelectS2C` +- `PlayerCreateC2S` / `PlayerCreateS2C` +- `PlayerEnterC2S` / `PlayerEnterS2C` +- `PlayerFlushC2S` / `PlayerFlushS2C` +- `ChangeNicknameC2S` / `ChangeNicknameS2C` + +## 已确认流程 + +当前登录入口： + +```text +HFGameStart.InitManager + -> OpenWindow + -> LoginWindow.OnBtnLogin + -> HFLoginManager.Login(InputName.text) +``` + +`HFLoginManager.Login` 流程： + +```text +Login(account) + -> 读取 EditorPrefs["IPData"] 覆盖 IP（仅 UNITY_EDITOR） + -> ConnectServer + -> HFSeverManager.ReConnect(OnReConnect) + -> HFSeverManager.Connect(MainConnect, WebSocket, m_IP, m_Port, m_Token) + -> OnSendLogin + -> LoginAuthC2S.Dispatch +``` + +服务端事件链： + +```text +LoginAuthS2C + -> PlayerSelectC2S + -> PlayerSelectS2C + -> 有角色：PlayerEnterC2S + -> 无角色：PlayerCreateC2S -> PlayerEnterC2S + -> PlayerEnterS2C + -> PlayerFlushC2S(All = true) +``` + +`LoginWindow` 会把用户名和密码写入 `PlayerPrefs`，但实际登录请求当前使用用户名作为 account，密码未参与 `LoginAuthC2S`。 + +## 梳理任务 + +- [x] 找到登录功能的入口方法和首个调用点。 +- [x] 梳理登录请求、响应和错误处理。 +- [x] 梳理登录成功后初始化了哪些 manager。 +- [x] 梳理登录窗口 prefab 和脚本绑定关系。 +- [ ] 确认登录完成后进入主界面或 PVE 的流程。 + +## 待确认 + +- 登录是否区分游客、账号、平台登录。 +- 登录数据是否会初始化背包、关卡、角色/塔数据。 +- 是否存在断线重连或重新登录流程。 +- `PlayerFlushS2C` 收到后由谁打开主界面，目前未确认。 +- 密码输入框当前只保存到 `PlayerPrefs`，是否应参与登录待确认。 + +## 相关框架 + +- [网络框架](../../../modules/frameworks/网络系统.md) +- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md) +- [Hotfix 启动/目录](../../../modules/frameworks/Hotfix启动.md) + +--- + +## 文档关联 + +> **注意**：当本模块发生变更时，应同步检查以下关联文档，避免信息不一致。 + +### 关联模块 + +| 模块 | 文档 | 关联原因 | +|---|---|---| +| 背包 | [背包](背包.md) | 登录成功后 `RequestLoginData` 触发背包初始化 | +| 奖励/道具展示 | [奖励/道具展示](奖励道具.md) | 登录流程涉及资源、道具配置 | +| GM/调试功能 | [GM/调试功能](GM调试.md) | `HFLoginManager` 在 Editor 下读取 `EditorPrefs["IPData"]` 覆盖 IP | +| PVE/关卡战斗 | [PVE/关卡战斗](PVE关卡战斗.md) | 登录后进入主界面或 PVE 的流程衔接 | +| 地图/关卡进度 | [地图/关卡进度](地图进度.md) | 登录后角色数据与关卡进度同步 | + +### 关联框架文档 + +| 框架 | 文档 | 关联原因 | +|---|---|---| +| 网络框架 | [网络框架](../../../modules/frameworks/网络系统.md) | 登录协议（`LoginAuthC2S/S2C`、`PlayerEnterS2C` 等） | +| UI 框架 | [UI 框架](../../../modules/frameworks/UI窗口系统/README.md) | `LoginWindow` 继承 `AbsHFUIWindow` | +| Hotfix 启动/目录 | [Hotfix 启动/目录](../../../modules/frameworks/Hotfix启动.md) | `HFGameStart.InitManager` 为入口 | +| 事件框架 | [事件框架](../../../modules/frameworks/事件系统/README.md) | `RequestLoginData` 触发后续初始化事件链 | +| 场景框架 | [场景框架](../../../modules/frameworks/场景系统.md) | 登录后进入主界面涉及场景切换 | + +### 关联规则 + +| 规则 | 文档 | 关联原因 | +|---|---|---| +| 模块登记规则 | [30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 登录模块登记与状态 | +| 归档规则 | [50-归档规则.md](../../../rules/50-归档规则.md) | 变更后需同步归档相关文档 | +| 架构说明 | [10-架构说明.md](../../../rules/10-架构说明.md) | 登录为游戏入口，涉及整体架构 | +| 开发规则 | [20-开发规则.md](../../../rules/20-开发规则.md) | 网络协议、UI 窗口开发规范 | + +### 关联 Spec / OpenSpec + +| Spec | 文档 | 关联原因 | +|---|---|---| +| 规则工作流 Spec | [2026-06-11-rules-workflow-v1.md](../../../specs/Spec索引.md) | 项目文档和规则系统建立 | \ No newline at end of file diff --git a/business-reference/playballoons/features/背包.md b/business-reference/playballoons/features/背包.md new file mode 100644 index 0000000..4900adb --- /dev/null +++ b/business-reference/playballoons/features/背包.md @@ -0,0 +1,174 @@ +# 背包 + +## 分类 + +- 项目功能 + +## 目的 + +记录道具、资源数量、背包数据同步、资源展示和奖励入包逻辑。 + +## 关键文件 + +| 用途 | 路径 | 说明 | +|---|---|---| +| 背包管理器 | `Assets/Game/GameHFScripte/GameFunction/Logic/Bag/BagInfo/HFBagManager.cs` | 单例 `AbsHFSingleRunTime`，管理背包页签、道具/资源数量 | +| 背包数据结构 | `Assets/Game/GameHFScripte/GameFunction/Logic/Bag/BagInfo/StItem.cs` | 单个道具数据 | +| 背包数据结构 | `Assets/Game/GameHFScripte/GameFunction/Logic/Bag/BagInfo/stItemInfo.cs` | 道具信息 | +| 道具类型枚举 | `Assets/Game/GameHFScripte/GameFunction/Logic/Constant/enItemType.cs` | 货币、材料、防御塔、经验、道具等 | +| 背包窗口 | `Assets/Game/GameHFScripte/GameFunction/UIWindows/ItemWindow/ItemWindow.cs` | 单个道具/资源展示单元 | +| GM 调试 | `Assets/Game/GameHFScripte/GameFunction/UIWindows/GMWindow/GMWindow_BagData.cs` | GM 修改背包数据入口 | +| 资源配置 | `XLSX_SRC/CN/Resource.xlsx` | 资源/道具基础配置 | + +## 数据流 + +### 登录初始化 + +```text +HFLoginManager.RequestLoginData + -> PlayerFlushC2S(All = true) + -> 服务端推送 GetBagItemS2C（待确认具体时序） + -> HFBagManager.OnPushBagItem + -> AddItem(item) + -> HFEvent_InitBag.Dispatch +``` + +### 增量更新 + +```text +PlayerResourceChangeS2C + -> ItemChange.Add / Del / Update + -> HFBagManager.OnUpdateBagItem + -> AddItem / DelItem + -> HFEvent_BagItemUpdate.Dispatch +``` + +## 关键 API + +| 方法 | 用途 | +|---|---| +| `Init(int maxpage)` | 初始化背包页签 | +| `AddItem(Item item)` | 添加/更新道具 | +| `DelItem(...)` | 删除道具 | +| `GetGameResourceCount(int resId)` | 按 resid 快速获取资源数量 | +| `GetItemCount(int resid)` | 遍历具体 item 累加数量 | +| `BagPageIndex` | 当前背包页签 | + +## 内部存储 + +- `m_BagPage`：按页签保存 `RB_Tree`。 +- `m_DicPageUUid`：按 `resid` 记录 uuid 到 page 的映射。 +- `m_DicItemCount`：按 `resid` 快速记录数量（当前为覆盖值，不是累加值）。 + +## 关键事件 + +- `enHFSTCEvent.GetBagItem`：首次推送背包数据。 +- `enHFSTCEvent.PlayerResourceChange`：资源/道具增量变化。 +- `HFEvent_InitBag`：背包初始化完成。 +- `HFEvent_BagItemUpdate`：背包数据更新。 + +## 已确认内容 + +背包 manager： + +- 主类：`HFBagManager` +- 基类：`AbsHFSingleRunTime` +- 初始化：`HFGameStart.InitManager` 访问 `HFBagManager.Instance` 时创建。 + +监听的服务端事件： + +- `GetBagItemS2C` -> `OnPushBagItem` +- `PlayerResourceChangeS2C` -> `OnUpdateBagItem` + +首次背包数据： + +```text +HFLoginManager.RequestLoginData + -> PlayerFlushC2S(All = true) + -> 服务端推送 GetBagItemS2C（待确认具体时序） + -> HFBagManager.OnPushBagItem + -> AddItem + -> HFEvent_InitBag.Dispatch +``` + +增删改更新： + +```text +PlayerResourceChangeS2C + -> ItemChange.Add / Del / Update + -> AddItem / DelItem + -> HFEvent_BagItemUpdate.Dispatch +``` + +内部存储： + +- `m_BagPage`：按页签保存 `RB_Tree`。 +- `m_DicPageUUid`：按 `resid` 记录 uuid 到 page 的映射。 +- `m_DicItemCount`：按 `resid` 快速记录数量。 +- `GetGameResourceCount(resId)`：常用于资源数量展示。 +- `GetItemCount(resid)`：遍历具体 item 累加数量。 + +## 梳理任务 + +- [x] 找到 `HFBagManager` 或背包 manager 的入口和生命周期。 +- [x] 梳理背包数据来源：登录初始化、网络消息、GM 请求或本地配置。 +- [x] 梳理道具和资源的查询 API。 +- [x] 梳理背包更新事件如何驱动 UI 刷新。 +- [ ] 梳理奖励入包和奖励展示的关系。 + +## 待确认 + +- 背包是否区分道具、资源、卡片。 +- 背包数据是否全部来自服务器。 +- 是否有消耗、添加、合并、排序等本地逻辑。 +- `PlayerFlushS2C` 和 `GetBagItemS2C` 的服务端推送时序需确认。 +- `m_DicItemCount[resid] = count` 当前是覆盖值，不是累加值，是否符合资源类型语义待确认。 + +## 相关框架 + +- [事件框架](../../../modules/frameworks/事件系统/README.md) +- [网络框架](../../../modules/frameworks/网络系统.md) +- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md) +- [数据/配置框架](../../../modules/frameworks/数据配置框架.md) + +--- + +## 文档关联 + +> **注意**：当本模块发生变更时，应同步检查以下关联文档，避免信息不一致。 + +### 关联模块 + +| 模块 | 文档 | 关联原因 | +|---|---|---| +| 登录 | [登录](登录.md) | `HFLoginManager.RequestLoginData` 触发背包首次初始化 | +| 商店 | [商店](商店.md) | 商店购买/出售涉及背包道具增减 | +| 奖励/道具展示 | [奖励/道具展示](奖励道具.md) | 奖励入包展示、道具配置（`Resource.xlsx`、`Gift.xlsx`） | +| 塔/角色养成 | [塔/角色养成](塔养成.md) | 养成消耗涉及背包资源扣除 | +| 地图/关卡进度 | [地图/关卡进度](地图进度.md) | 关卡奖励可能涉及背包道具更新 | +| GM/调试功能 | [GM/调试功能](GM调试.md) | `GMWindow_BagData` 为 GM 修改背包数据入口 | + +### 关联框架文档 + +| 框架 | 文档 | 关联原因 | +|---|---|---| +| 事件框架 | [事件框架](../../../modules/frameworks/事件系统/README.md) | `HFEvent_InitBag`、`HFEvent_BagItemUpdate` 事件驱动 | +| 网络框架 | [网络框架](../../../modules/frameworks/网络系统.md) | `GetBagItemS2C`、`PlayerResourceChangeS2C` 协议 | +| UI 框架 | [UI 框架](../../../modules/frameworks/UI窗口系统/README.md) | `ItemWindow` 为背包 UI 展示单元 | +| 数据/配置框架 | [数据/配置框架](../../../modules/frameworks/数据配置框架.md) | `Resource.xlsx` 资源配置源 | +| 内存/对象管理 | [内存/对象管理](../../../modules/frameworks/内存对象管理/README.md) | `RB_Tree` 存储结构、对象池 | + +### 关联规则 + +| 规则 | 文档 | 关联原因 | +|---|---|---| +| 模块登记规则 | [30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 背包模块登记与状态 | +| 归档规则 | [50-归档规则.md](../../../rules/50-归档规则.md) | 变更后需同步归档相关文档 | +| 架构说明 | [10-架构说明.md](../../../rules/10-架构说明.md) | 背包为全局数据模块，涉及架构分层 | +| 开发规则 | [20-开发规则.md](../../../rules/20-开发规则.md) | 数据管理、事件使用规范 | + +### 关联 Spec / OpenSpec + +| Spec | 文档 | 关联原因 | +|---|---|---| +| 规则工作流 Spec | [2026-06-11-rules-workflow-v1.md](../../../specs/Spec索引.md) | 项目文档和规则系统建立 | \ No newline at end of file diff --git a/business-reference/playballoons/业务参考总入口.md b/business-reference/playballoons/业务参考总入口.md new file mode 100644 index 0000000..8f77668 --- /dev/null +++ b/business-reference/playballoons/业务参考总入口.md @@ -0,0 +1,40 @@ +# PlayBalloons 业务参考 + +> 本目录存放来自 **PlayBalloons / CrystalBattle** 实际项目的业务功能文档。 +> +> 这些内容**不是 StrayFog 框架的一部分**，仅作为“使用 StrayFog 框架如何实现具体业务”的参考示例。 +> +> AI 和人工开发者应先学习 StrayFog 框架核心文档，再按需查阅本目录。 + +--- + +## 入口文档 + +- [业务功能 → StrayFog 框架能力映射](业务框架映射接口.md) +- [features/](features/)：原始业务功能文档 + +--- + +## 来源说明 + +这些文档原本位于 `modules/features/`（旧结构），是从 PlayBalloons 项目迁移而来。迁移时已移除与 StrayFog 框架核心无关的占位和未实现模块（如 PVP）。 + +--- + +## 使用建议 + +1. **不要直接套用**其中的具体类名、协议号、配置表字段到其他项目。 +2. **重点关注通用模式**：单例管理器、事件驱动数据流、GM 协议包装、通用弹窗接口等。 +3. **对照框架文档阅读**：看到业务实现时，回溯到 `modules/frameworks/` 下对应框架模块文档，理解底层机制。 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [业务框架映射接口.md](业务框架映射接口.md) | 业务参考总入口指向框架能力映射 | +| [modules/模块索引.md](../../modules/模块索引.md) | 模块索引可链接业务参考区 | +| [rules/10-架构说明.md](../../rules/10-架构说明.md) | 架构说明定义业务功能与框架层的依赖方向 | diff --git a/business-reference/playballoons/业务框架映射接口.md b/business-reference/playballoons/业务框架映射接口.md new file mode 100644 index 0000000..033303f --- /dev/null +++ b/business-reference/playballoons/业务框架映射接口.md @@ -0,0 +1,105 @@ +# 业务功能 → StrayFog 框架能力映射 + +> 本文档是 PlayBalloons 业务参考的“接口文档”。> +> 它不描述业务实现细节，而是说明每个业务功能用到了 StrayFog 框架的哪些能力，以及应该参考哪些框架文档。 + +--- + +## 来源说明 + +以下业务功能来自 PlayBalloons 实际项目，仅作参考，不是 StrayFog 框架本身。 + +原始业务文档位于 [features/](features/) 目录。 + +--- + +## 业务功能映射表 + +| 业务功能 | 涉及 StrayFog 框架能力 | 参考文档 | 状态 | +|---|---|---|---| +| 登录 | 单例管理器、网络协议、UI 窗口、事件链 | 网络框架、UI 框架、Hotfix 启动 | 可提炼示例 | +| 背包 | 单例、RB_Tree 存储、事件驱动、增量同步 | 事件框架、网络框架、数据/配置框架 | 可提炼示例 | +| 商店 | 网络协议、Map 数据结构、UI 窗口 | 网络框架、UI 框架、数据/配置框架 | 部分接入 | +| PVE 战斗 | 场景、实体、波次管理、伤害管理器 | 实体框架、场景框架、网络框架 | 半接入 | +| 塔养成 | 单例、编队数据、实体属性联动 | 实体框架、数据/配置框架 | 未完整实装 | +| GM 调试 | GM 协议包装、参数配置、模块化窗口生命周期 | 网络框架、UI 框架 | 可提炼示例 | +| 奖励展示 | 通用 Tips、事件监听、资源组件 | UI 框架、事件框架、资源框架 | 可提炼示例 | +| 地图进度 | 地图加载、波次配置、进度奖励 | 场景框架、数据/配置框架 | 半接入 | +| PVP | — | — | 未发现实现 | + +--- + +## 可复用模式索引 + +从业务文档中提炼出的通用模式，可作为使用 StrayFog 框架实现类似系统的参考： + +### 1. 单例管理器 + 初始化模式 + +```text +HFGameStart.InitManager() + -> 各业务 Manager.Instance 初始化 + -> Manager 监听 STC 事件 +``` + +对应框架能力： +- [Hotfix 启动](../../modules/frameworks/Hotfix启动.md) +- [对象池](../../modules/frameworks/内存对象管理/README.md) + +### 2. 事件驱动数据流 + +```text +服务器消息 S2C + -> 反射创建 STC 事件 + -> 业务 Manager 监听并更新数据 + -> 派发 CTC 事件通知 UI +``` + +对应框架能力： +- [事件系统](../../modules/frameworks/事件系统/README.md) +- [网络系统](../../modules/frameworks/网络系统.md) + +### 3. GM 命令统一包装 + +```text +GM 窗口 + -> 选择 msgId 和参数 + -> 包装成 GMC2S + -> 发送真实业务 Network_MsgId +``` + +对应框架能力： +- [网络系统](../../modules/frameworks/网络系统.md) +- [UI 窗口系统](../../modules/frameworks/UI窗口系统/README.md) + +### 4. 通用弹窗 / Tips 展示 + +```text +业务逻辑调用 HFFunCatalogue.Tips.ShowCommonRewardTips(rewardItems) + -> 打开通用奖励窗口 + -> 窗口内资源组件监听背包事件刷新 +``` + +对应框架能力： +- [UI 窗口系统](../../modules/frameworks/UI窗口系统/README.md) +- [事件系统](../../modules/frameworks/事件系统/README.md) +- [资源管理](../../modules/frameworks/资源管理/README.md) + +--- + +## 使用说明 + +1. AI 阅读时应先读框架文档，再读业务参考。 +2. 业务参考中的具体类名、协议号不可直接套用到其他项目。 +3. 如需新增业务参考，放入 `business-reference//features/`，并在本文件补充映射。 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [业务参考总入口.md](业务参考总入口.md) | 业务参考总入口指向本映射文档 | +| [features/*.md](features/) | 每个业务功能文档都应在映射表中有对应行 | +| [modules/模块索引.md](../../modules/模块索引.md) | 模块索引可链接到业务参考区 | diff --git a/hooks/Hook共享层.md b/hooks/Hook共享层.md new file mode 100644 index 0000000..2d9a9b7 --- /dev/null +++ b/hooks/Hook共享层.md @@ -0,0 +1,89 @@ +# Hook 共享层 + +> 本目录存放 UnityAI / StrayFog 框架知识库共享的 hook 脚本和规则。 +> +> 各 AI 工具自己的私有目录只放适配器，不重复维护 hook 逻辑。 + +--- + +## 脚本清单 + +| 脚本 | 用途 | +|---|---| +| [archive-check.ps1](archive-check.ps1) | 读取 git diff 中变更的 `.md` 文件，解析 `## 文档关联` 表，输出需要同步检查的关联文档 | +| [sync-doc-associations.ps1](sync-doc-associations.ps1) | Python 脚本的 PowerShell 包装器 | +| [sync_doc_associations.py](sync_doc_associations.py) | 在关联文档中追加变更提醒（只追加、不覆盖，执行后需 review） | +| [commit-check.ps1](commit-check.ps1) | 提交前检查：推断变更文件所属模块，校验提交信息格式 | +| [commit-module-mappings.json](commit-module-mappings.json) | `commit-check.ps1` 使用的目录-模块映射配置 | + +--- + +## 归档检查 + +所有任务结束后都应执行归档检查，判断是否需要同步更新长期文档。 + +```powershell +# PowerShell +.\docs\hooks\archive-check.ps1 +``` + +该脚本只输出建议，不会自动修改任何文档。最终是否更新关联文档，需要用户确认。 + +--- + +## 文档关联同步 + +如需在关联文档中自动留下变更提醒，可运行： + +```powershell +.\docs\hooks\sync-doc-associations.ps1 +``` + +该脚本只追加、不覆盖，执行后必须 review。 + +--- + +## 提交检查 + +提交前可运行： + +```powershell +.\docs\hooks\commit-check.ps1 -Message "[entity][docs]: 补充实体池说明" +``` + +检查项包括： + +- 提交信息是否符合 `[模块][类型]: 描述` 格式 +- 变更文件是否能映射到已知模块 +- 模块映射配置来自 [commit-module-mappings.json](commit-module-mappings.json) + +--- + +## 触发方式 + +| 触发方式 | 命令/路径 | 说明 | +|---|---|---| +| Codex Stop hook | `.codex/hooks/archive-reminder.ps1` | 若已配置，每次任务结束自动调用 `hooks/archive-check.ps1` | +| Claude Code 手动 | 直接运行脚本 | 任务结束时手动调用 `hooks/archive-check.ps1` | +| 手动脚本 | `hooks/archive-check.ps1` | 直接运行 PowerShell 脚本 | + +--- + +## 新增 Hook 时 + +1. 把脚本放入 `hooks/`。 +2. 在本文件中登记。 +3. 在 [ai/AI接入入口.md](../ai/AI接入入口.md) 中说明触发方式。 +4. 如果涉及提交信息格式，同步更新 [rules/40-工作流清单.md](../rules/40-工作流清单.md)。 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [ai/AI接入入口.md](../ai/AI接入入口.md) | AI 接入入口引用 hook 共享层 | +| [rules/项目规则入口.md](../rules/项目规则入口.md) | 规则入口索引归档触发机制 | +| [rules/40-工作流清单.md](../rules/40-工作流清单.md) | 提交前检查与工作流清单互相引用 | diff --git a/hooks/archive-check.ps1 b/hooks/archive-check.ps1 new file mode 100644 index 0000000..667d150 --- /dev/null +++ b/hooks/archive-check.ps1 @@ -0,0 +1,181 @@ +# hooks/archive-check.ps1 +# Check changed .md files and suggest related docs to update. +# This script only outputs suggestions; it does NOT modify any files. +# +# Mechanism: +# For every changed .md file, parse its "## 文档关联" section and extract +# Markdown links. Those links are the documents that may need syncing. + +$ErrorActionPreference = "SilentlyContinue" + +$scriptPath = $MyInvocation.MyCommand.Path +if (-not [System.IO.Path]::IsPathRooted($scriptPath)) { + $scriptPath = Join-Path (Get-Location) $scriptPath +} +$scriptPath = [System.IO.Path]::GetFullPath($scriptPath) +$scriptDir = Split-Path -Parent $scriptPath +$projectRoot = [System.IO.Path]::GetFullPath((Join-Path $scriptDir "..")) + +Set-Location $projectRoot + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + +function Resolve-RelativePath { + param( + [string]$BaseFile, + [string]$LinkPath + ) + + # Skip anchors, query strings, and external URLs + if ($LinkPath -match '^[a-zA-Z][a-zA-Z0-9+.-]*://') { return $null } + if ([string]::IsNullOrWhiteSpace($LinkPath)) { return $null } + + # Drop fragment + $pathOnly = ($LinkPath -split '#')[0] + if ([string]::IsNullOrWhiteSpace($pathOnly)) { return $null } + + $baseDir = Split-Path -Parent $BaseFile + $combined = Join-Path $baseDir $pathOnly + try { + $resolved = [System.IO.Path]::GetFullPath($combined) + } catch { + return $null + } + + # Convert to relative path from project root, normalizing separators + $fullProjectRoot = [System.IO.Path]::GetFullPath($projectRoot) + if ($resolved.StartsWith($fullProjectRoot, [System.StringComparison]::OrdinalIgnoreCase)) { + $relative = $resolved.Substring($fullProjectRoot.Length).TrimStart('\', '/') + return $relative -replace '\\', '/' + } + return $pathOnly -replace '\\', '/' +} + +function Get-DocumentAssociations { + param( + [string]$MdFile + ) + + $fullPath = Join-Path $projectRoot $MdFile + if (-not (Test-Path $fullPath)) { return @() } + + $lines = [System.IO.File]::ReadAllLines($fullPath, [System.Text.Encoding]::UTF8) + $associations = @() + $inSection = $false + $inCodeBlock = $false + + foreach ($line in $lines) { + # Toggle fenced code block state (``` or ~~~) + if ($line -match '^\s*```' -or $line -match '^\s*~~~') { + $inCodeBlock = -not $inCodeBlock + continue + } + if ($inCodeBlock) { continue } + + # Match exactly '## 文档关联' (not '## 文档关联机制' etc.). + if ($line -match "^##\s+文档关联\s*$") { + $inSection = $true + continue + } + if ($inSection -and $line -match '^##\s+') { + break + } + if ($inSection) { + # Extract markdown links: [text](path) + $regex = '\[(?[^\]]*)\]\((?[^\)]+)\)' + $matches = [regex]::Matches($line, $regex) + foreach ($match in $matches) { + $linkPath = $match.Groups['path'].Value.Trim() + $resolved = Resolve-RelativePath -BaseFile $MdFile -LinkPath $linkPath + if ($resolved) { + $associations += $resolved + } + } + } + } + + return $associations | Select-Object -Unique +} + +function Test-WildcardMatch { + param( + [string]$Pattern, + [string]$Path + ) + $regex = "^" + ($Pattern -replace "\.", "\." -replace "\*", ".*" -replace "\?", ".") + "$" + return $Path -match $regex +} + +# --------------------------------------------------------------------------- +# Collect changed .md files (tracked modifications + untracked new files) +# --------------------------------------------------------------------------- + +$changedFiles = @(cmd /c "git diff --name-only 2>nul") | Where-Object { $_ } +if ($changedFiles.Count -eq 0) { + $changedFiles = @(cmd /c "git diff --name-only --cached 2>nul") | Where-Object { $_ } +} + +# Also include untracked .md files so new documents are checked too +$untrackedFiles = @(cmd /c "git ls-files --others --exclude-standard 2>nul") | Where-Object { $_ } +$allChangedFiles = @($changedFiles) + @($untrackedFiles) | Where-Object { $_ } | Select-Object -Unique + +if (-not $allChangedFiles) { + Write-Output "[archive-check] No documentation changes detected (git diff is empty and no untracked .md files)." + exit 0 +} + +$changedMdFiles = $allChangedFiles | Where-Object { $_ -like "*.md" } | Select-Object -Unique + +if ($changedMdFiles.Count -eq 0) { + Write-Output "[archive-check] No .md documentation changes detected." + exit 0 +} + +# --------------------------------------------------------------------------- +# Build suggestions from each changed file's "## 文档关联" section +# --------------------------------------------------------------------------- + +$suggestions = @{} + +foreach ($changed in $changedMdFiles) { + $relatedDocs = Get-DocumentAssociations -MdFile $changed + foreach ($related in $relatedDocs) { + # Normalize related path + $relatedNormalized = $related -replace '\\', '/' + if (-not $suggestions.ContainsKey($relatedNormalized)) { + $suggestions[$relatedNormalized] = @() + } + if ($suggestions[$relatedNormalized] -notcontains $changed) { + $suggestions[$relatedNormalized] += $changed + } + } +} + +# --------------------------------------------------------------------------- +# Output results +# --------------------------------------------------------------------------- + +Write-Output "[archive-check] Changed documentation files:" +foreach ($changed in $changedMdFiles | Sort-Object) { + Write-Output " - $changed" +} + +if ($suggestions.Count -eq 0) { + Write-Output "" + Write-Output "[archive-check] No associations found in changed files' `"## 文档关联`" sections." + exit 0 +} + +Write-Output "" +Write-Output "[archive-check] Related docs that may need updating:" +foreach ($related in $suggestions.Keys | Sort-Object) { + $sources = $suggestions[$related] | Sort-Object + $sourceList = $sources -join ", " + Write-Output " - $related (mentioned by: $sourceList)" +} + +Write-Output "" +Write-Output "[archive-check] Please confirm whether to sync-update the above docs." +exit 0 diff --git a/hooks/commit-check.ps1 b/hooks/commit-check.ps1 new file mode 100644 index 0000000..50627e4 --- /dev/null +++ b/hooks/commit-check.ps1 @@ -0,0 +1,111 @@ +<# +.SYNOPSIS + 提交前共享检查：推断变更文件所属模块，校验提交信息格式。 + +.DESCRIPTION + 读取 git diff 中变更的文件，根据 hooks/commit-module-mappings.json + 推断模块，然后校验提交信息是否符合 [模块][类型]: 描述 格式。 + +.PARAMETER Message + 待校验的提交信息。 + +.EXAMPLE + .\docs\hooks\commit-check.ps1 -Message "[entity][docs]: 补充实体池说明" +#> + +param( + [Parameter(Mandatory = $true)] + [string]$Message +) + +$ErrorActionPreference = 'Stop' + +$mappingFile = Join-Path $PSScriptRoot 'commit-module-mappings.json' +if (-not (Test-Path $mappingFile)) { + Write-Error "Module mapping file not found: $mappingFile" + exit 1 +} + +$mapping = Get-Content $mappingFile -Raw | ConvertFrom-Json + +function Get-ChangedFiles { + $staged = (cmd /c "git diff --cached --name-only 2>nul") -split "`r?`n" | Where-Object { $_ } + if (-not $staged) { $staged = @() } + + $unstaged = (cmd /c "git diff --name-only 2>nul") -split "`r?`n" | Where-Object { $_ } + if (-not $unstaged) { $unstaged = @() } + + $all = @($staged) + @($unstaged) | Select-Object -Unique | Where-Object { $_ } + return $all +} + +function Get-ModuleForFile($file) { + foreach ($entry in $mapping.mappings) { + if ($file -match $entry.pattern) { + return $entry.module + } + } + return $null +} + +function Get-ModulesFromChangedFiles($files) { + $modules = @() + foreach ($file in $files) { + $module = Get-ModuleForFile $file + if ($module) { + $modules += $module + } + } + return $modules | Select-Object -Unique +} + +function Test-CommitMessage($message, $modules) { + if ($message -notmatch '^\[([^\]]+)\]\[([^\]]+)\]:\s*(.+)$') { + return @{ IsValid = $false; Reason = '提交信息格式应为：[模块][类型]: 描述' } + } + + $msgModule = $Matches[1] + $msgType = $Matches[2] + $msgDesc = $Matches[3] + + if (-not $msgDesc) { + return @{ IsValid = $false; Reason = '提交信息缺少描述内容' } + } + + if ($mapping.validTypes -notcontains $msgType) { + return @{ IsValid = $false; Reason = "无效的类型 '$msgType'。有效类型：$($mapping.validTypes -join ', ')" } + } + + if ($modules -and $modules -notcontains $msgModule) { + Write-Warning "提交信息中的模块 [$msgModule] 与变更文件推断的模块 [$($modules -join ', ')] 不一致，请确认是否 intentional。" + } + + return @{ IsValid = $true; Reason = '' } +} + +$files = Get-ChangedFiles +if (-not $files) { + Write-Host "未检测到变更文件。" -ForegroundColor Yellow + exit 0 +} + +$modules = Get-ModulesFromChangedFiles $files + +Write-Host "变更文件：" +$files | ForEach-Object { Write-Host " - $_" } + +if ($modules) { + Write-Host "推断模块：$($modules -join ', ')" +} +else { + Write-Warning "未能从变更文件推断出模块，请检查提交信息是否手动指定了正确模块。" +} + +$result = Test-CommitMessage $Message $modules +if (-not $result.IsValid) { + Write-Error $result.Reason + exit 1 +} + +Write-Host "提交信息格式正确。" -ForegroundColor Green +exit 0 diff --git a/hooks/commit-module-mappings.json b/hooks/commit-module-mappings.json new file mode 100644 index 0000000..660473a --- /dev/null +++ b/hooks/commit-module-mappings.json @@ -0,0 +1,88 @@ +{ + "mappings": [ + { + "pattern": "rules/.*", + "module": "rules" + }, + { + "pattern": "modules/frameworks/实体系统.*", + "module": "entity" + }, + { + "pattern": "modules/frameworks/UI窗口系统.*", + "module": "ui" + }, + { + "pattern": "modules/frameworks/事件系统.*", + "module": "event" + }, + { + "pattern": "modules/frameworks/资源管理.*|modules/frameworks/通用框架.*", + "module": "resource" + }, + { + "pattern": "modules/frameworks/内存对象管理.*", + "module": "pool" + }, + { + "pattern": "modules/frameworks/相机系统.*", + "module": "camera" + }, + { + "pattern": "modules/frameworks/场景系统.*", + "module": "scene" + }, + { + "pattern": "modules/frameworks/网络系统.*", + "module": "network" + }, + { + "pattern": "modules/frameworks/数据配置框架.*", + "module": "config" + }, + { + "pattern": "modules/frameworks/技能系统.*", + "module": "skill" + }, + { + "pattern": "modules/frameworks/Hotfix启动.*", + "module": "hotfix" + }, + { + "pattern": "modules/frameworks/编辑器工具.*|modules/frameworks/第三方插件.*", + "module": "editor" + }, + { + "pattern": "hooks/.*", + "module": "hooks" + }, + { + "pattern": "ai/.*|AGENTS\\.md|CLAUDE\\.md|RULES\\.md", + "module": "ai" + }, + { + "pattern": "specs/.*|plans/.*", + "module": "spec" + }, + { + "pattern": "modules/frameworks/编辑器工具/UI工具/.*", + "module": "tools" + }, + { + "pattern": "business-reference/.*", + "module": "business-reference" + }, + { + "pattern": "README\\.md", + "module": "docs" + } + ], + "validTypes": [ + "feat", + "fix", + "docs", + "refactor", + "test", + "chore" + ] +} diff --git a/hooks/sync-doc-associations.ps1 b/hooks/sync-doc-associations.ps1 new file mode 100644 index 0000000..e2565a2 --- /dev/null +++ b/hooks/sync-doc-associations.ps1 @@ -0,0 +1,22 @@ +# hooks/sync-doc-associations.ps1 +# Wrapper for sync_doc_associations.py +# This script appends change reminders to associated .md files. +# It only appends to standard sections; it never overwrites existing content. + +$ErrorActionPreference = "Stop" + +$scriptPath = $MyInvocation.MyCommand.Path +if (-not [System.IO.Path]::IsPathRooted($scriptPath)) { + $scriptPath = Join-Path (Get-Location) $scriptPath +} +$scriptPath = [System.IO.Path]::GetFullPath($scriptPath) +$scriptDir = Split-Path -Parent $scriptPath +$pythonScript = Join-Path $scriptDir "sync_doc_associations.py" + +if (-not (Test-Path $pythonScript)) { + Write-Error "Python script not found: $pythonScript" + exit 1 +} + +python "$pythonScript" +exit $LASTEXITCODE diff --git a/hooks/sync_doc_associations.py b/hooks/sync_doc_associations.py new file mode 100644 index 0000000..c0b0b53 --- /dev/null +++ b/hooks/sync_doc_associations.py @@ -0,0 +1,218 @@ +#!/usr/bin/env python3 +# hooks/sync_doc_associations.py +# +# 当 md 文件变更时，自动在关联文档的标准位置追加变更提醒： +# - 有 ## 变更记录 表格的模块文档：追加一行变更记录 +# - 有 ## 下一步 清单的 progress/tasks 文档：追加一个待检查项 +# - 其他文档：追加 ## 最近关联变更 章节 +# +# 本脚本只追加、不覆盖正文；执行后请通过 git diff 人工确认。 + +import os +import re +import subprocess +import sys +from datetime import datetime +from pathlib import Path + +PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent + +EXCLUDED_PREFIXES = ( + '.claude/', '.codex/', '.git/', + 'Library/', 'Temp/', 'Logs/', 'UserSettings/', + 'obj/', 'bin/', 'HybridCLRData/', + 'Assets/ThirdPlugins/', + 'Assets/.WX-WASM-SDK-V2/', + 'Packages/', +) + + +def run_git(args): + result = subprocess.run( + ["git"] + args, + cwd=PROJECT_ROOT, + capture_output=True, + text=True, + encoding="utf-8", + ) + return result.stdout.strip(), result.returncode + + +def get_changed_md_files(): + """获取 tracked 改动 + untracked 新 md 文件。""" + changed, code = run_git(["diff", "--name-only"]) + if code != 0 or not changed: + changed = "" + + untracked, code = run_git(["ls-files", "--others", "--exclude-standard"]) + if code == 0 and untracked: + changed = (changed + "\n" + untracked).strip() + + if not changed: + return [] + + files = [line.strip() for line in changed.splitlines() if line.strip().endswith(".md")] + files = [f for f in files if not f.startswith(EXCLUDED_PREFIXES)] + return sorted(set(files)) + + +def resolve_link(source_file: Path, link: str): + """解析相对链接为项目相对路径。""" + if re.match(r"^[a-zA-Z][a-zA-Z0-9+.-]*://", link): + return None + if link.startswith("#"): + return None + link = link.split("#")[0] + if not link: + return None + target = (source_file.parent / link).resolve() + try: + target.relative_to(PROJECT_ROOT) + except ValueError: + return None + rel = target.relative_to(PROJECT_ROOT) + return str(rel).replace("\\", "/") + + +def extract_associations(md_path: Path): + """读取 md 的 ## 文档关联 章节，返回关联文件相对路径列表。""" + content = md_path.read_text(encoding="utf-8") + in_section = False + targets = [] + for line in content.splitlines(): + if re.match(r"^##\s+文档关联\s*$", line): + in_section = True + continue + if in_section and re.match(r"^##\s+", line): + break + if in_section: + for _, link in re.findall(r"\[([^\]]*)\]\(([^\)]+)\)", line): + resolved = resolve_link(md_path, link) + if resolved: + targets.append(resolved) + return targets + + +def find_section_range(lines, title_re): + """返回 [start, end) 行号，end 为下一个 ## 标题或文件末尾。""" + start = None + for i, line in enumerate(lines): + if re.match(title_re, line): + start = i + continue + if start is not None and re.match(r"^##\s+", line): + return start, i + if start is not None: + return start, len(lines) + return None, None + + +def append_changelog(target_path: Path, source_rel: str, date_str: str) -> bool: + """在 ## 变更记录 表格追加一行；成功返回 True。""" + content = target_path.read_text(encoding="utf-8") + lines = content.splitlines() + start, end = find_section_range(lines, r"^##\s+变更记录\s*$") + if start is None: + return False + + # 找到表格最后一行（跳过标题和分隔线） + insert_pos = end + for i in range(start + 1, end): + if lines[i].strip().startswith("|") and not re.match(r"^\|[-:\s|]+\|$", lines[i].strip()): + insert_pos = i + 1 + + new_line = f"| {date_str} | [{source_rel}](../../{source_rel}) 发生变更 | 待补充影响范围 | 待确认 |" + lines.insert(insert_pos, new_line) + target_path.write_text("\n".join(lines) + ("\n" if content.endswith("\n") else ""), encoding="utf-8") + return True + + +def append_next_step(target_path: Path, source_rel: str) -> bool: + """在 ## 下一步 清单追加一个待检查项；成功返回 True。""" + content = target_path.read_text(encoding="utf-8") + lines = content.splitlines() + start, end = find_section_range(lines, r"^##\s+下一步\s*$") + if start is None: + return False + + new_line = f"- [ ] 检查 [{source_rel}](../../{source_rel}) 的变更是否影响本文档" + # 避免重复 + for line in lines[start:end]: + if source_rel in line and "变更是否影响本文档" in line: + return True # 已存在，视为成功但不写入 + + lines.insert(end, new_line) + target_path.write_text("\n".join(lines) + ("\n" if content.endswith("\n") else ""), encoding="utf-8") + return True + + +def append_recent_changes_section(target_path: Path, source_rel: str, date_str: str) -> bool: + """在没有 变更记录/下一步 的文档末尾追加 ## 最近关联变更。""" + content = target_path.read_text(encoding="utf-8") + # 生成从 target 到 source 的相对链接 + try: + link = os.path.relpath(PROJECT_ROOT / source_rel, target_path.parent).replace("\\", "/") + except ValueError: + link = source_rel + + if "## 最近关联变更" in content: + lines = content.splitlines() + start, end = find_section_range(lines, r"^##\s+最近关联变更\s*$") + if start is not None: + new_line = f"- {date_str}：关联文档 [{source_rel}]({link}) 发生变更，需同步检查。" + lines.insert(end, new_line) + target_path.write_text("\n".join(lines) + ("\n" if content.endswith("\n") else ""), encoding="utf-8") + return True + + section = ( + "\n---\n\n" + "## 最近关联变更\n\n" + f"- {date_str}：关联文档 [{source_rel}]({link}) 发生变更，需同步检查。\n" + ) + target_path.write_text(content.rstrip() + section, encoding="utf-8") + return True + + +def sync_associations(): + changed_files = get_changed_md_files() + if not changed_files: + print("[sync-doc-assoc] No .md changes detected.") + return 0 + + date_str = datetime.now().strftime("%Y-%m-%d") + modified = [] + + for source_rel in changed_files: + source_path = PROJECT_ROOT / source_rel + if not source_path.exists(): + continue + targets = extract_associations(source_path) + for target_rel in targets: + target_path = PROJECT_ROOT / target_rel + if not target_path.is_file(): + # Skip directories, globs, or missing targets + continue + if target_rel == source_rel: + continue + + done = ( + append_changelog(target_path, source_rel, date_str) + or append_next_step(target_path, source_rel) + or append_recent_changes_section(target_path, source_rel, date_str) + ) + if done: + modified.append((source_rel, target_rel)) + + if not modified: + print("[sync-doc-assoc] No associated docs need updating.") + return 0 + + print("[sync-doc-assoc] Updated associated docs:") + for source, target in modified: + print(f" - {source} -> {target}") + print("\n[sync-doc-assoc] Please review the changes with git diff before committing.") + return 0 + + +if __name__ == "__main__": + sys.exit(sync_associations()) diff --git a/modules/frameworks/Hotfix启动.md b/modules/frameworks/Hotfix启动.md new file mode 100644 index 0000000..bda1239 --- /dev/null +++ b/modules/frameworks/Hotfix启动.md @@ -0,0 +1,95 @@ +# Hotfix 启动 + +## 分类 + +- 核心框架 + +## 目的 + +记录 hotfix 侧根入口和功能目录聚合，梳理游戏启动链路。 + +--- + +## 核心路径 + +- `Assets/Game/GameHFScripte/GameFunction/GameRoot/` +- 关键文件：`HFGameStart.cs`、`HFFunCatalogue_GameManager.cs` +- 程序集：`GameHF` + +--- + +## 启动调用链 + +```text +HFGameStart.Init(GameSetting) + -> HFFunCatalogue.SetGameSetting + -> HFFunCatalogue.ChangeLanguage(enHFLanguageClassify.EN) + -> HFGameStartAssetsCheckManager.CheckFirstDownLoadWindowAsset + -> HFGameStart.LoadDB + -> Hotfix_ZYXlsx_GoogleProtobuf_Helper.LoadAllXlsx + -> HFFunCatalogue.Scene.LoadScene(enHFSceneName.Game) + -> HFGameStart.InitManager + -> HFFunCatalogue.UIManager.OpenWindow<登录窗口> +``` + +--- + +## InitManager 初始化单例 + +`HFGameStart.InitManager()` 负责初始化各业务/框架管理器，例如： + +- `HFSeverManager` +- `HFMapManager` +- `HFDamageManager` +- `HFPopupTextManager` +- 各业务管理器（如背包、登录等，按项目实际） + +--- + +## HFFunCatalogue 聚合入口 + +`HFFunCatalogue` 提供统一访问入口： + +- `UIManager` — UI 窗口 +- `Asset` — 资源加载 +- `Scene` — 场景加载 +- `Sprite` — 图集/精灵 +- `EntityPool` — 实体池 +- `LinePool` / `SoundPool` — 其他对象池 +- `Event` — 事件系统 +- `GameConstant` — 游戏常量 +- `NDB` — 配置表读取 +- `Bag` / `Tips` — 业务相关入口（按项目实际） + +--- + +## 使用规则 + +- 业务代码通过 `HFFunCatalogue` 访问核心库，禁止直接实例化核心库内部类。 +- `HFGameStart` 是 hotfix 侧启动入口，不要绕过它直接初始化管理器。 +- 启动顺序修改需谨慎，确保配置表、资源、场景按正确顺序加载。 + +--- + +## 相关模块 + +- [UI 窗口系统](UI窗口系统/README.md) +- [资源管理](资源管理/README.md) +- [场景系统](场景系统.md) +- [数据/配置框架](数据配置框架.md) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../模块索引.md) | 模块索引是项目知识总入口 | +| [modules/frameworks/UI窗口系统/README.md](UI窗口系统/README.md) | 启动后打开登录窗口依赖 UI 框架 | +| [modules/frameworks/资源管理/README.md](资源管理/README.md) | 启动流程涉及资源检查 | +| [modules/frameworks/场景系统.md](场景系统.md) | 启动流程涉及场景加载 | +| [modules/frameworks/数据配置框架.md](数据配置框架.md) | 启动流程涉及配置表加载 | +| [rules/10-架构说明.md](../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/modules/frameworks/UI窗口系统/README.md b/modules/frameworks/UI窗口系统/README.md new file mode 100644 index 0000000..cf23798 --- /dev/null +++ b/modules/frameworks/UI窗口系统/README.md @@ -0,0 +1,129 @@ +# UI 框架 + +## 分类 + +- 项目框架 + +## 目的 + +记录 UIWindow 管理、窗口基类、UIMono 桥接、窗口资源加载和 UI 生命周期。 + +## 已知线索 + +- 管理路径：`Assets/Game/GameHFScripte/CopyToHF/UIWindowMgr/` +- 窗口实现：`Assets/Game/GameHFScripte/GameFunction/UIWindows/` +- Mono 桥接：`Assets/Game/GameMono/Scripts/UIMono/` +- 资源路径：`Assets/Game/GameHFResource/CN/UIWindows/` + +## 已确认链路 + +UI manager 初始化： + +```text +HFUIWindowMgr.OnAfterCreateInstance() + -> OnInitializeCanvasAndCamera() + -> 为 enHFUICanvasLayer 创建 Canvas + -> 为 ScreenSpaceCamera Canvas 创建 UI Camera + -> 创建 CacheSiblingIndex Canvas + -> 创建或接管 EventSystem / StandaloneInputModule +``` + +打开窗口： + +```text +HFFunCatalogue.UIManager.OpenWindow() + -> HFUIWindowMgr.OnOpenWindow() + -> 创建 HFDefaultTask / HFUIWindow_RespondTask + -> 读取窗口类型上的 HFAssetBundlePathAttribute 和 HFUIWindowLayerAttribute + -> OnSettingWindowSiblingIndex() + -> 从缓存队列复用窗口实例，或 Activator.CreateInstance 创建窗口逻辑实例 + -> OnPreloadWindowInMemory() + -> HFABMgr.Instance.LoadInMemory(windowPrefabPath) + -> win.BindGameObject(prefab) + -> OnAttachWindow(win) + -> win.SyncWindowState() + -> AbsHFUIWindow.OnOpen() +``` + +关闭窗口： + +```text +CloseWindow() / AbsHFUIWindow.CloseWindow() + -> HFUIWindowMgr.OnCloseWindow() + -> siblingIndexLayer.ToggleWindowActive(false) + -> 放入 mCacheWindowInstanceMaping + -> 处理 backtrack 自动恢复窗口 + -> win.SyncWindowState() + -> AbsHFUIWindow.OnClose() +``` + +窗口资源绑定： + +- 窗口类通过 `[HFAssetBundlePath(...)]` 标记 prefab 路径。 +- 窗口类通过 `[HFUIWindowLayer(...)]` 标记 Canvas/Layer 和是否允许多开。 +- `AbsHFUIWindowSetting.SetWindowType` 会读取上述 attribute，生成 `winId`、`winTypeId` 和资源路径。 + +## 使用规则 + +- 新窗口必须继承 `AbsHFUIWindow`。 +- 新窗口必须配置 `HFAssetBundlePath` 和 `HFUIWindowLayer`。 +- 打开窗口统一走 `HFFunCatalogue.UIManager.OpenWindow()`。 +- 关闭窗口统一走 `CloseWindow()` 或 `HFFunCatalogue.UIManager.CloseWindow()`。 +- 在 `OnOpen` 中注册的事件必须在 `OnClose` 中移除。 +- 不直接 `Instantiate` / `Destroy` UI 窗口 prefab。 +- 不绕过 `HFUIWindowMgr` 手动修改窗口 active、父节点或 siblingIndex。 +- 普通业务窗口默认使用 `Dynamic`，提示类优先使用 `Tooltip`，强交互弹窗优先使用 `Popup`，`Highest` 仅用于明确的顶层兜底。 +- UI prefab 放在 `Assets/Game/GameHFResource/<语言>/UIWindows/<模块>/`，代码中的 `HFAssetBundlePath` 使用相对 `UIWindows/...` 的路径。 +- 优先使用项目已有 UIMono / ZYUGUI 绑定流程，不手写大量 `transform.Find`。 +- 列表、循环列表、网格优先使用已有 ZYUGUI / SuperScrollView 组件和编辑器转换工具。 +- 异步加载或动画结束后再调用完成回调时，必须保证失败/取消路径不会卡住窗口状态。 + +## 新增 UI 窗口清单 + +1. 确认窗口所属功能模块。 +2. 创建窗口类，继承 `AbsHFUIWindow`。 +3. 添加 `HFAssetBundlePath` 和 `HFUIWindowLayer`。 +4. 创建或更新 prefab。 +5. 使用 UIMono / ZYUGUI 生成或绑定 UI 引用。 +6. 用 `HFFunCatalogue.UIManager.OpenWindow()` 接入入口。 +7. 在 `OnOpen` / `OnClose` 对称处理事件、计时器、临时数据。 +8. 验证打开、关闭、重复打开、切场景或语言变化时的表现。 +9. 如果新增模块或改变 UI 架构，更新相关模块文档。 + +## 梳理任务 + +- [x] 梳理窗口基类和打开/关闭 API。 +- [x] 梳理窗口 prefab 路径绑定方式。 +- [ ] 梳理 UIMono 自动绑定和 partial 生成关系。 +- [x] 梳理窗口生命周期：Open/Close/状态同步。 +- [x] 梳理 UI 事件订阅和释放规范。 +- [x] 梳理功能 UI 和框架 UI 的边界。 + +## 待确认 + +- 常规入口已确认是 `HFFunCatalogue.UIManager` / `HFUIWindowMgr`，是否存在绕过路径待继续扫描。 +- UI 资源会经过 `HFAssetBundlePathAttribute` 和语言路径规则，哪些 UI 真正有 CN/EN 差异待确认。 +- UIMono 是否由编辑器工具生成。 +- `OnOpen`/`OnClose` 外是否还有业务窗口统一订阅/释放规范待确认。 + +## 相关模块 + +- [资源框架](../资源管理/README.md) +- [事件框架](../事件系统/README.md) +- [ZYUGUI Tools](../../模块索引.md#编辑器工具) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../../模块索引.md) | ZYUGUI Tools | +| [modules/frameworks/事件系统/README.md](../事件系统/README.md) | 事件框架 | +| [modules/frameworks/资源管理/README.md](../资源管理/README.md) | 资源框架 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | 开发规则与框架/生成规则互相引用 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | +| TODO：补充依赖或使用本框架的模块文档 | 如依赖本框架的功能模块 | \ No newline at end of file diff --git a/03_核心功能/UI/UI开发指南.md b/modules/frameworks/UI窗口系统/开发指南.md similarity index 72% rename from 03_核心功能/UI/UI开发指南.md rename to modules/frameworks/UI窗口系统/开发指南.md index 60c63cb..372da26 100644 --- a/03_核心功能/UI/UI开发指南.md +++ b/modules/frameworks/UI窗口系统/开发指南.md @@ -1,4 +1,4 @@ -# StrayFog 框架 UI开发指南 +# StrayFog 框架 UI 开发指南 ## 一、窗口开发 @@ -32,9 +32,9 @@ public class MyWindow : AbsHFUIWindow | 方法 | 调用时机 | 推荐操作 | |-----|---------|---------| -| `OnRunAwake` | 创建时一次 | 绑定UI事件、初始化滚动列表 `BindEvent` | -| `OnOpen` | 每次打开 | 注册TC事件、调用 `ShowView()` 刷新数据 | -| `OnClose` | 每次关闭 | 取消TC事件 | +| `OnRunAwake` | 创建时一次 | 绑定 UI 事件、初始化滚动列表 `BindEvent` | +| `OnOpen` | 每次打开 | 注册 TC 事件、调用 `ShowView()` 刷新数据 | +| `OnClose` | 每次关闭 | 取消 TC 事件 | **关键原则**： - **绑定类操作**（如 `BindEvent`）放在 `OnRunAwake`，只需执行一次 @@ -54,8 +54,8 @@ HFFunCatalogue.UIManager.CloseWindow(); | 事件类型 | 绑定位置 | 是否需要 `-=` | |---------|---------|--------------| -| UI按钮/拖拽 | `OnRunAwake` | 不需要 | -| 全局TC事件 | `OnOpen`/`OnClose` | 需要 | +| UI 按钮/拖拽 | `OnRunAwake` | 不需要 | +| 全局 TC 事件 | `OnOpen`/`OnClose` | 需要 | --- @@ -176,16 +176,16 @@ public class CardItem : AbsListItem | 类型 | 路径 | 说明 | |-----|------|------| | **窗口脚本** | `Assets/Game/GameHFScripte/GameFunction/UIWindows/{WindowName}/` | 窗口逻辑脚本存放目录 | -| **窗口预制体** | `Assets/Game/GameHFResource/CN/UIWindows/{WindowName}/` | UI窗口预制体存放目录 | -| **图标图集** | `Assets/Game/GameHFResource/CN/SpriteAtlas/{AtlasName}/` | SpriteAtlas图集资源 | +| **窗口预制体** | `Assets/Game/GameHFResource/CN/UIWindows/{WindowName}/` | UI 窗口预制体存放目录 | +| **图标图集** | `Assets/Game/GameHFResource/CN/SpriteAtlas/{AtlasName}/` | SpriteAtlas 图集资源 | | **字体资源** | `Assets/Game/GameHFResource/CN/Fonts/` | 字体文件存放目录 | #### 6.1.2 工具脚本路径 | 工具名称 | 路径 | 职责 | |---------|------|------| -| **UIPrefabGenerator** | `Assets/Editor/Command/UIPrefabGenerator.cs` | JSON转UI预制体 | -| **UIPrefabToJson** | `Assets/Editor/Command/UIPrefabToJson.cs` | 预制体转JSON | +| **UIPrefabGenerator** | `Assets/Editor/Command/UIPrefabGenerator.cs` | JSON 转 UI 预制体 | +| **UIPrefabToJson** | `Assets/Editor/Command/UIPrefabToJson.cs` | 预制体转 JSON | | **RemoteCommand** | `Assets/Editor/Command/RemoteCommand.cs` | 外部命令接口 | | **ExternalCommandListener** | `Assets/Editor/Command/ExternalCommandListener.cs` | 外部命令监听器 | @@ -193,20 +193,39 @@ public class CardItem : AbsListItem | 文档名称 | 路径 | |---------|------| -| UI开发指南 | `UnityAI/03_核心功能/UI/UI开发指南.md` | -| UI界面拼接设计指南 | `UnityAI/03_核心功能/UI/UI界面拼接设计指南.md` | +| UI 开发指南 | [UI窗口系统/开发指南.md](开发指南.md) | +| UI 界面拼接设计指南 | [UI窗口系统/界面拼接.md](界面拼接.md) | #### 6.1.4 命令触发路径 - **触发文件**: `{ProjectRoot}/Trigger_Command.txt` -- **JSON配置**: `Assets/Editor/UI/{WindowName}.json` +- **JSON 配置**: `Assets/Editor/UI/{WindowName}.json` ### 6.2 性能优化 -- 使用对象池复用UI元素 -- 将图标打包到SpriteAtlas +- 使用对象池复用 UI 元素 +- 将图标打包到 SpriteAtlas - 滚动列表用 `SFUI_ScrollRect.BindEvent` --- **版本**: v1.1 -**适用**: StrayFog框架UI开发人员 \ No newline at end of file +**适用**: StrayFog 框架 UI 开发人员 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [UI 窗口系统入口](README.md) | 本文件是 UI 窗口系统模块的子文档 | +| [UI 界面拼接设计指南](界面拼接.md) | 界面拼接是 UI 开发的补充设计指南 | +| [UI 拼接工具](../编辑器工具/UI拼接工具.md) | JSON 驱动 UI 生成工具说明 | +| [事件系统](../事件系统/README.md) | UI 事件订阅和释放规范 | +| [对象池与运行时对象管理](../内存对象管理/README.md) | UI 元素复用相关 | +| [资源管理](../资源管理/README.md) | UI 资源加载依赖资源管理 | +| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | UI 命名与编码规范互相引用 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/modules/frameworks/UI窗口系统/界面拼接.md b/modules/frameworks/UI窗口系统/界面拼接.md new file mode 100644 index 0000000..6d11642 --- /dev/null +++ b/modules/frameworks/UI窗口系统/界面拼接.md @@ -0,0 +1,192 @@ +# UI 界面拼接设计指南 + +## 一、界面结构设计原则 + +### 1.1 模块化拆分 + +将界面按功能划分为独立模块： + +| 模块类型 | 功能定位 | 示例 | +|---------|---------|------| +| **信息展示区** | 显示玩家状态、资源等静态信息 | 顶部信息栏、左侧状态栏 | +| **功能入口区** | 提供功能按钮入口 | 中央功能区、底部快捷栏 | +| **交互面板区** | 可展开/收起的功能面板 | 右侧功能面板、顶部按钮区 | +| **输入输出区** | 用户输入和系统反馈 | 聊天输入框、提示信息 | + +### 1.2 经典布局模式 + +``` +┌─────────────────────────────────────────────────────┐ +│ TopArea (信息展示 + 可收起功能按钮) │ +├──────────┬───────────────────────┬──────────────────┤ +│ Left │ │ Right │ +│ Area │ CenterArea │ Area │ +│ (状态) │ (核心功能入口) │ (功能面板) │ +│ │ │ │ +├──────────┴───────────────────────┴──────────────────┤ +│ BottomArea (快捷功能 + 状态信息 + 输入) │ +└─────────────────────────────────────────────────────┘ +``` + +--- + +## 二、组件拆分方法 + +### 2.1 基础组件识别 + +| 组件类型 | 识别特征 | 处理方式 | +|---------|---------|---------| +| **按钮** | 可点击、有交互反馈 | 使用 `SFUI_Button` | +| **文本** | 静态/动态文字显示 | 使用 `SFUI_TextMeshProUGUI` | +| **图片** | 图标、背景图 | 使用 `SFUI_Image` | +| **进度条** | HP、MP、经验等 | 使用 `SFUI_Slider` | +| **列表** | 可滚动的项目列表 | 使用 `SFUI_ScrollRect` | + +### 2.2 复合组件封装 + +将功能相关的基础组件组合为复合组件，便于复用和维护： + +**设计原则**： +- 将同一功能模块的组件封装在一起（如玩家头像+血条+蓝条） +- 提供统一的数据设置接口 +- 保持组件之间的逻辑独立性 + +--- + +## 三、预制体层级规范 + +### 3.1 标准层级结构 + +``` +WindowName (RectTransform) +├── ModuleName (RectTransform) # 模块容器 +│ ├── ComponentName (SFUI_*) # 功能组件 +│ ├── SubModule (RectTransform) # 子模块 +│ └── CollapsibleArea (RectTransform) # 可收起区域 +└── BtnCollapse (SFUI_Button) # 收起控制按钮 +``` + +### 3.2 命名规范 + +| 类型 | 命名规则 | 示例 | +|-----|---------|------| +| 模块容器 | PascalCase + Area | `TopArea` | +| 功能组件 | PascalCase | `BtnCollapseTop` | +| 可收起区域 | PascalCase + FuncArea | `TopFuncArea` | +| 状态变量 | m_ + PascalCase | `m_IsTopCollapsed` | + +--- + +## 四、收起/展开功能设计 + +### 4.1 功能定义 + +| 按钮 | 控制区域 | 用途 | +|-----|---------|------| +| `BtnCollapseTop` | 顶部功能按钮区 | 收起/展开顶部按钮群 | +| `BtnCollapseRight` | 右侧功能面板区 | 收起/展开右侧功能面板 | + +### 4.2 设计要点 + +**状态管理**：每个可收起区域需要一个布尔状态变量来记录当前收起/展开状态。 + +**交互逻辑**： +1. 点击收起按钮时，切换对应区域的显示/隐藏状态 +2. 同时切换按钮图标（收起时显示展开图标，展开时显示收起图标） + +**布局要求**： +- 收起按钮应放置在对应区域的边缘位置，便于用户找到 +- 收起区域内的所有元素应作为一个整体进行显示/隐藏控制 +- 收起状态应在窗口生命周期内保持记忆 + +--- + +## 五、实际案例：主界面拼接 + +### 5.1 模块化设计思想 + +**核心原则**：将界面按功能边界划分为独立模块，模块内可嵌套子模块。 + +**模块归类方法**： + +1. **一级模块**：按空间位置划分（顶部、左侧、中央、右侧、底部） +2. **二级模块**：按功能类型划分（信息展示区、功能按钮区、输入输出区） +3. **三级模块**：按具体功能划分（玩家头像、资源显示、功能按钮群） + +**层级关系示例**： + +``` +Window +├── TopArea (一级：位置) +│ ├── InfoPanel (二级：信息展示) +│ │ └── TxtWelcome (三级：具体组件) +│ └── FuncButtons (二级：功能按钮) +│ └── BtnUpload (三级：具体按钮) +└── LeftArea (一级：位置) + └── PlayerPortrait (二级：复合组件) + ├── ImgAvatar (三级：头像) + └── BarHP (三级：血条) +``` + +**设计要点**： +- 同一功能域内的元素归为同一模块（如头像、血条、蓝条归为玩家状态模块） +- 独立交互功能作为独立模块（如收起按钮单独作为控制模块） +- 可收起区域作为独立子模块，便于统一控制显示/隐藏 + +--- + +## 六、界面拼接流程 + +### 6.1 设计阶段 +1. **需求分析**：明确界面功能和交互需求 +2. **模块划分**：将界面拆分为独立功能模块 +3. **层级设计**：设计预制体层级结构 + +### 6.2 开发阶段 +1. **组件创建**：创建基础组件和复合组件 +2. **预制体搭建**：按层级结构搭建预制体 +3. **脚本编写**：实现交互逻辑和收起/展开功能 + +### 6.3 测试阶段 +1. **功能测试**：验证所有按钮和交互功能 +2. **收起测试**：测试收起/展开功能正常工作 +3. **适配测试**：验证不同分辨率下的显示效果 + +--- + +## 七、注意事项 + +1. **组件复用**：相同功能的组件尽量复用，减少冗余 +2. **状态管理**：收起状态需要正确保存和恢复 +3. **图标反馈**：收起按钮图标应随状态变化 +4. **性能优化**：可收起区域使用 `SetActive` 而非销毁重建 +5. **命名规范**：统一的命名规则便于维护和查找 + +--- + +## 八、JSON 配置驱动的 UI 生成方式 + +本项目支持通过 JSON 配置快速生成 UI 预制体，详细工具说明、命令格式和部署步骤见 [UI 拼接工具](../编辑器工具/UI拼接工具.md)。 + +UI 相关人员核心工作流程：读取设计效果图和碎片图片，生成 JSON 配置文件，再通过工具自动生成 Unity 预制体。 + +--- + +**版本**: v1.2 +**适用**: StrayFog 框架 UI 拼接开发人员 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [UI 窗口系统入口](README.md) | 本文件是 UI 窗口系统模块的子文档 | +| [UI 开发指南](开发指南.md) | 窗口开发与界面拼接互相补充 | +| [UI 拼接工具](../编辑器工具/UI拼接工具.md) | JSON 驱动 UI 生成工具说明 | +| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | UI 命名与资源规则互相引用 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/modules/frameworks/事件系统/README.md b/modules/frameworks/事件系统/README.md new file mode 100644 index 0000000..93e4a78 --- /dev/null +++ b/modules/frameworks/事件系统/README.md @@ -0,0 +1,122 @@ +# 事件系统 + +## 分类 + +- 核心框架 + +## 目的 + +提供客户端内部事件（CTC）和服务器消息事件（STC）的统一派发、监听和释放机制。 + +--- + +## 核心路径 + +- 框架层：`Assets/Game/GameHFScripte/CopyToHF/Event/` +- 功能层：`Assets/Game/GameHFScripte/GameFunction/Event/` +- STC 事件参数：`Assets/Game/GameHFScripte/GameFunction/Event/STCEventArg/` + +--- + +## 核心类 + +| 类 | 职责 | +|---|---| +| `HFEventManager` | 事件管理器单例，继承 `AbsHFSingleRunTime` | +| `TCEvent` | CTC 事件句柄 | +| `STCEvent` | STC 事件句柄 | +| `CTCHandle` | CTC 事件处理器定义位置 | +| `AbsHFEventArg` | 事件参数基类 | + +--- + +## 事件派发链路 + +### CTC 事件 + +```text +AbsHFEventArg.Dispatch() + -> HFEventManager.Instance.TCEvent.Dispatch(arg) +``` + +CTC 事件来源： + +- 功能代码手动创建事件参数对象。 +- 设置字段后调用 `.Dispatch()`。 +- 示例：业务管理器派发初始化事件、背包更新事件。 + +### STC 事件 + +```text +AbsHFEventArg.Dispatch() + -> HFEventManager.Instance.STCEvent.Dispatch(arg) +``` + +STC 事件来源： + +```text +WSSession 收到 protobuf S2C + -> 反射创建 HFEvent_STC_{MessageTypeName} + -> 写入 Request / ErrorCode + -> Dispatch 到 STCEvent +``` + +--- + +## 监听与派发机制 + +```text +AddListener(eventId, callback) + -> 按 eventId 分组 + -> 按事件参数类型 hash 分组 + +Dispatch(arg) + -> 根据 arg.eventId 找事件组 + -> 根据 arg.GetType() 找具体类型监听 + -> Invoke callbacks + -> arg.Recycle() +``` + +--- + +## 使用规则 + +- UI 窗口在 `OnOpen` 中注册的事件，必须在 `OnClose` 中移除。 +- 管理器监听 STC 事件通常在初始化时添加，在 `Recycle` 或销毁时移除。 +- 不要直接监听与当前模块无关的事件。 +- 事件参数对象由框架自动回收，业务代码不要重复释放。 + +--- + +## 错误响应 + +当服务器返回错误响应时： + +```text +messagePage.IsError = true + -> 解析 ErrorResponse + -> 派发 HFEvent_ErrorCode + -> 同时仍创建对应 HFEvent_STC_* 并写入 ErrorCode +``` + +--- + +## 相关模块 + +- [网络系统](../网络系统.md) +- [UI 窗口系统](../UI窗口系统/README.md) +- [实体系统](../实体系统/README.md) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 | +| [modules/frameworks/网络系统.md](../网络系统.md) | S2C 消息是 STC 事件来源 | +| [modules/frameworks/UI窗口系统/README.md](../UI窗口系统/README.md) | UI 窗口订阅和释放事件 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/03_核心功能/事件系统使用指南.md b/modules/frameworks/事件系统/使用指南.md similarity index 64% rename from 03_核心功能/事件系统使用指南.md rename to modules/frameworks/事件系统/使用指南.md index 9c24b8e..d320baa 100644 --- a/03_核心功能/事件系统使用指南.md +++ b/modules/frameworks/事件系统/使用指南.md @@ -1,4 +1,4 @@ -# StrayFog 框架事件系统使用指南 +# 事件系统使用指南 ## 一、事件系统概述 @@ -13,7 +13,7 @@ ### 2.1 定义事件枚举和参数 ```csharp -// 事件ID枚举 +// 事件 ID 枚举 public enum GameEventId { PlayerLevelUp, @@ -44,9 +44,9 @@ public class PlayerLevelUpEventArgs : GameEventArgs --- -## 三、UI窗口事件监听 +## 三、UI 窗口事件监听 -### 3.1 在窗口中注册CTCEvent +### 3.1 在窗口中注册 CTCEvent ```csharp [HFAssetBundlePath(enHFLanguageRootFolder.ASSETS_GAME_GAMEHFRESOURCE, "UIWindows/CardDeck/CardDeckWindow.prefab")] @@ -70,18 +70,18 @@ public class CardDeckWindow : AbsHFUIWindow void OnCardUpdate(HFEventArgBase arg) { HFEvent_CTC_CardUpdate cardArg = arg as HFEvent_CTC_CardUpdate; - // 更新卡组UI显示 + // 更新卡组 UI 显示 } } ``` -> **注意**：UI窗口中**不监听服务器事件（STCEvent）**，服务器事件应在Logic层的Manager中监听。 +> **注意**：UI 窗口中**不监听服务器事件（STCEvent）**，服务器事件应在 Logic 层的 Manager 中监听。 --- -## 四、Manager事件监听 +## 四、Manager 事件监听 -### 4.1 使用AbsHFSingleMonoBehaviour（需要Update） +### 4.1 使用 AbsHFSingleMonoBehaviour（需要 Update） ```csharp public class PlayerManager : AbsHFSingleMonoBehaviour @@ -107,7 +107,7 @@ public class PlayerManager : AbsHFSingleMonoBehaviour { HFEvent_STC_PlayerInfo info = arg as HFEvent_STC_PlayerInfo; // 处理服务器返回的玩家信息 - // 触发客户端事件通知UI更新 + // 触发客户端事件通知 UI 更新 HFEvent_CTC_PlayerLevelUp evt = HFFunCatalogue.New(); evt.playerId = info.playerId; evt.newLevel = info.level; @@ -116,7 +116,7 @@ public class PlayerManager : AbsHFSingleMonoBehaviour } ``` -### 4.2 使用AbsHFSingleRunTime（纯逻辑） +### 4.2 使用 AbsHFSingleRunTime（纯逻辑） ```csharp public class ConfigManager : AbsHFSingleRunTime @@ -137,15 +137,32 @@ public class ConfigManager : AbsHFSingleRunTime --- -## 五、Manager类型对比 +## 五、Manager 类型对比 | 类型 | 说明 | 适用场景 | |-----|------|---------| -| `AbsHFSingleMonoBehaviour` | 生成GameObject，可注册MonoBehaviour事件 | 需要Update/FixedUpdate等生命周期 | -| `AbsHFSingleRunTime` | 纯内存单例，无GameObject | 不需要生命周期事件 | +| `AbsHFSingleMonoBehaviour` | 生成 GameObject，可注册 MonoBehaviour 事件 | 需要 Update/FixedUpdate 等生命周期 | +| `AbsHFSingleRunTime` | 纯内存单例，无 GameObject | 不需要生命周期事件 | --- **版本**: v1.0 **生效日期**: 2026年 -**适用范围**: GiftGameX项目业务开发人员 \ No newline at end of file +**适用范围**: GiftGameX 项目业务开发人员 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [事件系统入口](README.md) | 本文件是事件系统模块的子文档 | +| [网络系统](../网络系统.md) | STC 事件来源与网络系统相关 | +| [UI 窗口系统](../UI窗口系统/README.md) | UI 窗口订阅和释放事件 | +| [实体系统](../实体系统/README.md) | Manager 常与实体系统协作 | +| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | 事件订阅/释放与开发规则互相引用 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/modules/frameworks/内存对象管理/README.md b/modules/frameworks/内存对象管理/README.md new file mode 100644 index 0000000..143fdda --- /dev/null +++ b/modules/frameworks/内存对象管理/README.md @@ -0,0 +1,110 @@ +# 对象池与运行时对象管理 + +## 分类 + +- 核心框架 + +## 目的 + +提供类实例池、行为对象池、脚本对象池、实体池和 RT 展示对象的统一复用机制，减少 GC 和实例化开销。 + +--- + +## 核心路径 + +- 内存管理：`Assets/Game/GameHFScripte/CopyToHF/MemoryManager/` +- 运行时对象：`Assets/Game/GameHFScripte/GameFunction/RTObjectManager/` +- 调用池：`Assets/Game/GameHFScripte/GameFunction/Logic/CallPoolManager/` +- 实体池：`Assets/Game/GameHFScripte/GameFunction/GameEntity/EntityPool/` + +--- + +## 池类型 + +### HFClassEntityManager + +类实例池，按类型 hash 维护 `Stack`。 + +```text +GetClassEntity() + -> 优先从 Stack 弹出复用 + -> 否则 Activator.CreateInstance() +``` + +### HFSimulateBehaviourPool + +行为对象池，用于继承 `AbsHFSimulateBehaviour` 的对象。 + +- 维护未使用队列和使用中列表。 +- `GiveBack()` 隐藏 GameObject 并调用 `Recycle()`。 + +### HFScriptMemPool + +脚本对象池，用于 `IHFRecycle` 的普通对象或 MonoBehaviour。 + +- 若类型继承 MonoBehaviour，自动创建 GameObject 挂载组件。 +- 若类型为普通类，直接 `Activator.CreateInstance`。 + +### 实体池 + +`HFEntityPool` + 各类 `AbsHFEntityPool` 实现，见 [实体系统](../实体系统/README.md)。 + +--- + +## 运行时展示对象（RT） + +RT 对象用于在独立相机上展示模型、特效等： + +- `RTObject`：运行时展示对象基类 +- `RTGameObjectRes`：从资源 id 创建展示对象 +- `RTEntity`：实体展示对象 +- `RTCameraItem`：RT 相机项 +- `RTUIEffectCameraItem`：UI 特效相机项 + +创建流程： + +```text +RTGameObjectRes + -> 从资源 id 创建 GameObject + -> 资源加载走 HFABMgr.Instance.LoadAsset +``` + +--- + +## 回收接口 + +| 接口 | 职责 | +|---|---| +| `IHFRecycle` | 基础回收接口，声明 `Recycle()` | +| `IHFRecycleEventHandler` | 回收事件处理 | +| `OnAfterRecycleHandler` | 回收到类实例池 | + +--- + +## 使用规则 + +- 频繁创建/销毁的对象优先使用对象池。 +- 归还对象时确保来源正确，避免泄漏。 +- 对象池内对象在归还后应重置状态。 +- RT 对象注意及时释放相机 seat 和资源引用。 + +--- + +## 相关模块 + +- [实体系统](../实体系统/README.md) +- [资源管理](../资源管理/README.md) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 | +| [modules/frameworks/实体系统/README.md](../实体系统/README.md) | 实体池是对象池的一种特化 | +| [modules/frameworks/资源管理/README.md](../资源管理/README.md) | RT 对象资源加载依赖资源管理 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/03_核心功能/对象池使用指南.md b/modules/frameworks/内存对象管理/使用指南.md similarity index 67% rename from 03_核心功能/对象池使用指南.md rename to modules/frameworks/内存对象管理/使用指南.md index 022d080..e546b2d 100644 --- a/03_核心功能/对象池使用指南.md +++ b/modules/frameworks/内存对象管理/使用指南.md @@ -1,6 +1,6 @@ -# StrayFog 框架对象池使用指南 +# 对象池使用指南 -## 一、GameObject对象池 +## 一、GameObject 对象池 ### 1.1 基本用法 @@ -82,11 +82,11 @@ public class EventArgPool : MonoBehaviour ### 3.1 对象池设计特点 | 特性 | 说明 | -|-----|-----| +|-----|------| | **双池结构** | 空闲池 + 使用池，高效管理对象状态 | | **内存泄漏检测** | 归还时校验来源，及时发现问题 | | **泛型支持** | `HFScriptMemPool` 提供类型安全 | -| **Mono支持** | 自动创建GameObject，无缝集成Unity | +| **Mono 支持** | 自动创建 GameObject，无缝集成 Unity | ### 3.2 性能优化建议 @@ -98,4 +98,19 @@ public class EventArgPool : MonoBehaviour **版本**: v1.0 **生效日期**: 2026年 -**适用范围**: GiftGameX项目业务开发人员 \ No newline at end of file +**适用范围**: GiftGameX 项目业务开发人员 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [对象池与运行时对象管理入口](README.md) | 本文件是内存对象管理模块的子文档 | +| [实体系统](../实体系统/README.md) | 实体池是对象池的一种特化 | +| [资源管理](../资源管理/README.md) | RT 对象资源加载依赖资源管理 | +| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/modules/frameworks/场景系统.md b/modules/frameworks/场景系统.md new file mode 100644 index 0000000..3fa6a42 --- /dev/null +++ b/modules/frameworks/场景系统.md @@ -0,0 +1,98 @@ +# 场景系统 + +## 分类 + +- 核心框架 + +## 目的 + +管理 Unity 场景的加载、资源配置读取和场景生命周期回调。 + +--- + +## 核心路径 + +- 场景管理器：`Assets/Game/GameHFScripte/GameFunction/SceneManager/` +- Unity 场景：`Assets/Game/GameMono/Scenes/` + +--- + +## 核心类 + +| 类 | 职责 | +|---|---| +| `HFSceneMgr` | 场景管理器单例，继承 `AbsHFSingleMonoBehaviour` | +| `enHFSceneName` | 场景枚举，例如 `Game = 80001` | + +--- + +## 加载流程 + +```text +LoadScene(enHFSceneName scene, Action complete) + -> 转为资源/关卡 id + -> LoadScene(int levelId, Action complete) + -> HFFunCatalogue.NDB.ds_Resource840C5F09TableData.ReadTableByPK(levelId) + -> 读取资源配置 +``` + +### Editor 模式 + +```text +从配置 Path 取文件名 + -> SceneManager.LoadScene(scName) +``` + +### 非 Editor 模式 + +```text +HFFunCatalogue.Asset.LoadAsset(levelId, ...) + -> 用结果中的 res.sceneName 调用 SceneManager.LoadScene +``` + +`OnLoadScene()` 同步调用 `SceneManager.LoadScene()` 后立即执行完成回调。 + +--- + +## 生命周期 + +`ZYCore` 中存在 `IZYH_ZYCore_Scene` 和 `AbsZYH_ZYCore_Scene` 接口： + +- 进入加载场景 +- 加载完成 +- 进入/退出场景前后 +- 切场景释放 + +`ZYUGUI` 窗口管理器提供： + +- `isAutoCloseWhenToggleScene`：切场景时自动关闭 +- `isAutoDestoryWhenToggleScene`：切场景时自动销毁 + +--- + +## 使用规则 + +- 场景切换统一走 `HFFunCatalogue.Scene.LoadScene()`。 +- 不要在场景里堆放运行时动态加载的资源。 +- 切场景时注意 UI 窗口的自动关闭/销毁配置。 + +--- + +## 相关模块 + +- [资源管理](资源管理/README.md) +- [UI 窗口系统](UI窗口系统/README.md) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../模块索引.md) | 模块索引是项目知识总入口 | +| [modules/frameworks/资源管理/README.md](资源管理/README.md) | 场景资源加载依赖资源管理 | +| [modules/frameworks/UI窗口系统/README.md](UI窗口系统/README.md) | 切场景影响 UI 窗口生命周期 | +| [rules/10-架构说明.md](../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/modules/frameworks/实体系统/README.md b/modules/frameworks/实体系统/README.md new file mode 100644 index 0000000..7d68f5b --- /dev/null +++ b/modules/frameworks/实体系统/README.md @@ -0,0 +1,138 @@ +# 实体系统 + +## 分类 + +- 核心框架 + +## 目的 + +管理游戏实体的创建、生命周期、System-Model 架构、实体池和子系统协作。 + +--- + +## 核心路径 + +- 实体框架：`Assets/Game/GameHFScripte/GameFunction/GameEntity/` +- 实体数据：`Assets/Game/GameHFScripte/GameFunction/Logic/EntityData/` +- 子目录：`Core/`、`Entity/`、`EntityPool/`、`RVO/`、`StateMachineBehaviour/` + +--- + +## 核心类 + +| 类 | 职责 | +|---|---| +| `HFAbsEntity` | 实体基类，继承 `AbsHFSimulateBehaviour` | +| `HFEntity_Basic` | 基础实体标签 | +| `HFEntity_Enemy` | 敌人类型标签 | +| `HFEntity_Human` | 人类/玩家类型标签 | +| `HFEntityPool` | 实体池入口 | +| `HFBasicPool` / `HFEnemyPool` / `HFHumanityPool` | 按 `enEntityLayer` 分类的实体池实现 | +| `AbsHFEntityPool` | 实体池抽象基类 | +| `stEntityInfo` | 实体数据结构 | + +--- + +## System-Model 架构 + +`HFAbsEntity` 内部维护两个集合： + +```text +m_Models : IModel[] // 数据层 +m_Systems : ISystem[] // 表现层/逻辑层 +``` + +按 `enSystemType` 关联 `IModel` 和 `ISystem`。 + +添加系统： + +```csharp +AddSystem() + -> HFClassEntityManager.Instance.GetClassEntity() // 创建或复用系统对象 + -> 生成对应 IModel + -> model.Init(this, system.Init) // 建立实体、模型、系统关系 +``` + +更新顺序： + +```text +OnSystemUpdate() // 表现层更新 +OnModelUpdate() // 数据层更新 +``` + +--- + +## 实体池机制 + +`HFEntityPool` 按 `enEntityLayer` 注册不同的 `AbsHFEntityPool` 实现。 + +创建实体： + +```text +AbsHFEntityPool.OnCreateEnity() + -> 创建 GameObject 根节点 + -> 维护 onlyid -> entity 索引 + -> 维护 EntityId -> onlyid 索引 +``` + +查询实体： + +```text +HFEntityPool.SelectByOnlyid(onlyid) + -> 通过 onlyid -> enEntityLayer 找到对应池 + -> 从具体池取实体 +``` + +回收实体： + +```text +DelEntityByOnlyid(onlyid) + -> 从池索引移除 + -> 调用 entity.Recycle() +``` + +--- + +## 子系统 + +实体相关的子系统通常位于： + +- `Models/AI`、`Systems/AI` — AI +- `Models/Animation`、`Systems/Animation` — 动画 +- `Models/Feature`、`Systems/Feature` — 特性/属性 +- `Models/Move`、`Systems/Move` — 移动 +- `Models/Skill`、`Systems/Skill` — 技能 +- `HFSkillTrigger_*` — 技能触发器 +- `HFSkill_*_Releaser` — 技能释放器 +- `GameEntity/RVO/RVOManager.cs` — RVO 避障 + +--- + +## 使用规则 + +- 新实体类型应继承 `HFAbsEntity`。 +- 实体对象统一通过 `HFEntityPool` 创建和回收。 +- 系统通过 `AddSystem()` 添加，避免直接 new。 +- 子系统数据更新放在 `OnModelUpdate()`，表现更新放在 `OnSystemUpdate()`。 + +--- + +## 相关模块 + +- [技能系统](../技能系统/README.md) +- [对象池](../内存对象管理/README.md) +- [数据/配置框架](../数据配置框架.md) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 | +| [modules/frameworks/技能系统/README.md](../技能系统/README.md) | 技能系统是实体系统的子系统 | +| [modules/frameworks/内存对象管理/README.md](../内存对象管理/README.md) | 实体池与对象池机制相关 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/03_核心功能/Entity/Entity开发指南.md b/modules/frameworks/实体系统/开发指南.md similarity index 63% rename from 03_核心功能/Entity/Entity开发指南.md rename to modules/frameworks/实体系统/开发指南.md index def6392..f053042 100644 --- a/03_核心功能/Entity/Entity开发指南.md +++ b/modules/frameworks/实体系统/开发指南.md @@ -1,12 +1,12 @@ -# StrayFog 框架 Entity开发指南 +# Entity 开发指南 -## 一、Entity概述 +## 一、Entity 概述 -Entity是游戏世界中所有游戏对象的抽象基类，包括玩家、敌人、塔楼、城堡等。Entity系统提供统一的对象管理、生命周期控制和**System-Model架构**。 +Entity 是游戏世界中所有游戏对象的抽象基类，包括玩家、敌人、塔楼、城堡等。Entity 系统提供统一的对象管理、生命周期控制和 **System-Model 架构**。 -### 1.1 Entity分类 +### 1.1 Entity 分类 -Entity分类根据具体业务需求定义，以下为示例分类（项目实际分类以业务为准）： +Entity 分类根据具体业务需求定义，以下为示例分类（项目实际分类以业务为准）： | 类别 | 说明 | 示例 | |-----|------|------| @@ -15,22 +15,22 @@ Entity分类根据具体业务需求定义，以下为示例分类（项目实 | **Castle** | 城堡/基地实体 | 玩家基地 | | **Obstacle** | 障碍物实体 | 墙壁、陷阱 | -> **说明**：实际项目中需根据业务需求定义Entity类型，继承`HFAbsEntity`基类并实现对应逻辑。 +> **说明**：实际项目中需根据业务需求定义 Entity 类型，继承 `HFAbsEntity` 基类并实现对应逻辑。 ### 1.2 核心数据结构 ```csharp -// Entity唯一标识 +// Entity 唯一标识 public long onlyid { get; } // 运行时唯一ID public int EntityId { get; } // 资源配置ID -public enEntityLayer entityType { get; } // Entity类型 +public enEntityLayer entityType { get; } // Entity 类型 public enEntityCamp entityCamp { get; } // 阵营 public bool isDeath { get; } // 是否死亡 ``` --- -## 二、Entity创建规范 +## 二、Entity 创建规范 ### 2.1 继承结构 @@ -53,11 +53,11 @@ public abstract partial class HFAbsEntity : AbsHFSimulateBehaviour public virtual void OnDeath() { ... } // 子类重写处理表现死亡逻辑 // 逻辑死亡（数据层） - protected void Logic_Death() { ... } // 设置isDeath=true，数据层死亡 + protected void Logic_Death() { ... } // 设置 isDeath=true，数据层死亡 protected virtual void OnLogicDeath() { ... } // 子类重写处理逻辑死亡逻辑 } -// 具体Entity示例 - Human类型 +// 具体 Entity 示例 - Human 类型 public class HFEntity_Human : HFAbsEntity { protected override void OnRunAwake() @@ -85,36 +85,36 @@ public class HFEntity_Human : HFAbsEntity | 类型 | 命名规则 | 示例 | |-----|---------|------| -| Entity类 | `HFEntity_{TypeName}` | `HFEntity_Human`、`HFEntity_Tower` | +| Entity 类 | `HFEntity_{TypeName}` | `HFEntity_Human`、`HFEntity_Tower` | | 系统类 | `HF{SystemName}System[_TypeName]` | `HFAnimationSystem_Human` | | 模型类 | `HF{ModelName}Model[_TypeName]` | `HFAnimationModel_Human` | | 数据结构 | `st{DataName}` | `stAbilityData`、`stDamageInfo` | --- -## 三、Entity生命周期 +## 三、Entity 生命周期 ### 3.1 生命周期方法 | 方法 | 调用时机 | 职责 | 层级 | |-----|---------|------|-----| -| `OnRunAwake()` | 对象创建时 | 添加System组件 | 表现层 | -| `Init()` | 初始化时调用 | 重置死亡状态、调用OnInit | - | -| `OnInit()` | Init内部调用 | 子类重写，初始化配置数据 | 数据层 | -| `Logic_Death()` | HP归零时调用 | 设置`isDeath=true`，调用OnLogicDeath | 数据层 | -| `OnLogicDeath()` | Logic_Death内部调用 | 子类重写处理逻辑死亡逻辑 | 数据层 | -| `Death()` | 逻辑死亡后调用 | 触发死亡事件、调用OnDeath | 表现层 | -| `OnDeath()` | Death内部调用 | 子类重写，处理表现死亡逻辑（动画、特效等） | 表现层 | +| `OnRunAwake()` | 对象创建时 | 添加 System 组件 | 表现层 | +| `Init()` | 初始化时调用 | 重置死亡状态、调用 OnInit | - | +| `OnInit()` | Init 内部调用 | 子类重写，初始化配置数据 | 数据层 | +| `Logic_Death()` | HP 归零时调用 | 设置 `isDeath=true`，调用 OnLogicDeath | 数据层 | +| `OnLogicDeath()` | Logic_Death 内部调用 | 子类重写处理逻辑死亡逻辑 | 数据层 | +| `Death()` | 逻辑死亡后调用 | 触发死亡事件、调用 OnDeath | 表现层 | +| `OnDeath()` | Death 内部调用 | 子类重写，处理表现死亡逻辑（动画、特效等） | 表现层 | | `OnRecycle()` | 对象回收时 | 清理资源、释放引用 | - | > **重要区分**： -> - **逻辑死亡**：`Logic_Death()` 由伤害计算触发，设置`isDeath=true`，仅影响数据层 +> - **逻辑死亡**：`Logic_Death()` 由伤害计算触发，设置 `isDeath=true`，仅影响数据层 > - **表现死亡**：`Death()` 在逻辑死亡后调用，触发死亡事件和表现效果（动画、音效等） ### 3.2 创建流程 ```csharp -// 1. 对象池创建Entity +// 1. 对象池创建 Entity HFEntityPool.Instance.CreateEntity(onlyid, entityId, () => HFClassEntityManager.Instance.GetClassEntity(), (entity) => { @@ -127,14 +127,14 @@ HFEntityPool.Instance.CreateEntity(onlyid, entityId, --- -## 四、System-Model架构 +## 四、System-Model 架构 ### 4.1 架构设计 -Entity采用**System-Model分离架构**： +Entity 采用 **System-Model 分离架构**： -- **System层**：处理表现逻辑（Update、状态转换） -- **Model层**：处理数据逻辑（数据存储、计算） +- **System 层**：处理表现逻辑（Update、状态转换） +- **Model 层**：处理数据逻辑（数据存储、计算） ### 4.2 添加系统 @@ -156,21 +156,21 @@ public class HFEntity_Human : HFAbsEntity ### 4.3 常用系统 -| 系统 | 职责 | 适用Entity | +| 系统 | 职责 | 适用 Entity | |-----|------|-----------| -| `HFFeatureSystem` | 属性管理 | 所有Entity | +| `HFFeatureSystem` | 属性管理 | 所有 Entity | | `HFAnimationSystem` | 动画控制 | Human、Tower | | `HFMoveSystem` | 移动控制 | Human | -| `HFAISystem` | AI行为 | Enemy、Tower | +| `HFAISystem` | AI 行为 | Enemy、Tower | | `HFSkillSystem` | 技能系统 | Human、Tower | -### 4.4 获取Model +### 4.4 获取 Model ```csharp -// 通过System类型获取Model +// 通过 System 类型获取 Model HFAnimationModel_Human animModel = GetModel(); -// 通过System对象获取Model +// 通过 System 对象获取 Model HFSkillSystem skillSystem = ...; HFSkillModel skillModel = GetModel(skillSystem); ``` @@ -184,7 +184,7 @@ HFSkillModel skillModel = GetModel(skillSystem); | 属性类型 | 说明 | 示例 | |---------|------|------| | **基础属性** | 配置表读取，基础值 | HP、SPD、MoveSpeed | -| **战斗属性** | 实际战斗中使用，受Buff影响 | Fight_SPD、Fight_ATK | +| **战斗属性** | 实际战斗中使用，受 Buff 影响 | Fight_SPD、Fight_ATK | ### 5.2 属性数据结构 @@ -228,20 +228,20 @@ public void ChangeData(stAbilityData data) } else { - // 临时属性变更（存入Buff字典） + // 临时属性变更（存入 Buff 字典） OnAddEntityAbilityData(data); } // 刷新战斗属性 OnRefushEntityAbility(data.ChangeTarget); - // 通知所有Model属性变更 + // 通知所有 Model 属性变更 ChangeAbility(data.ChangeTarget); } ``` --- -## 六、Entity对象池 +## 六、Entity 对象池 ### 6.1 对象池职责 @@ -250,16 +250,16 @@ public abstract partial class AbsHFEntityPool : IHFObject { public abstract enEntityLayer entityType { get; } - // 根据onlyid获取Entity + // 根据 onlyid 获取 Entity public virtual HFAbsEntity SelectByOnlyid(long onlyid) { ... } - // 根据资源ID获取所有Entity + // 根据资源 ID 获取所有 Entity public List SelectByResId(int resid) { ... } - // 删除Entity + // 删除 Entity public virtual bool DelEntityByOnlyid(long onlyid) { ... } - // 获取所有Entity + // 获取所有 Entity public List GetAllEntities() { ... } } ``` @@ -267,7 +267,7 @@ public abstract partial class AbsHFEntityPool : IHFObject ### 6.2 使用示例 ```csharp -// 创建Entity +// 创建 Entity HFEntityPool.Instance.CreateEntity( onlyid: 1001, entityId: 10001, @@ -277,11 +277,11 @@ HFEntityPool.Instance.CreateEntity( entity.Init(); }); -// 获取Entity +// 获取 Entity HFAbsEntity entity = HFEntityPool.Instance.SelectByOnlyid(1001); HFEntity_Human human = entity as HFEntity_Human; -// 删除Entity +// 删除 Entity HFEntityPool.Instance.DelEntityByOnlyid(1001); ``` @@ -293,8 +293,8 @@ HFEntityPool.Instance.DelEntityByOnlyid(1001); | 类型 | 路径 | |-----|------| -| Entity基类 | `Assets/Game/GameHFScripte/GameFunction/GameEntity/Core/BaseEntity/AbsEntity/` | -| 具体Entity | `Assets/Game/GameHFScripte/GameFunction/GameEntity/Entity/EntityTag/` | +| Entity 基类 | `Assets/Game/GameHFScripte/GameFunction/GameEntity/Core/BaseEntity/AbsEntity/` | +| 具体 Entity | `Assets/Game/GameHFScripte/GameFunction/GameEntity/Entity/EntityTag/` | | 系统类 | `Assets/Game/GameHFScripte/GameFunction/GameEntity/Entity/System/` | | 模型类 | `Assets/Game/GameHFScripte/GameFunction/GameEntity/Entity/Model/` | | 对象池 | `Assets/Game/GameHFScripte/GameFunction/GameEntity/Core/BaseEntity/EntityPool/` | @@ -302,21 +302,38 @@ HFEntityPool.Instance.DelEntityByOnlyid(1001); ### 7.2 编码规范 1. **必须继承** `HFAbsEntity` 基类 -2. **必须在** `OnRunAwake()` 中添加所需System +2. **必须在** `OnRunAwake()` 中添加所需 System 3. **必须重写** `OnInit()` 初始化配置数据 4. **必须重写** `OnDeath()` 处理死亡逻辑 -5. **禁止**在Entity中直接访问Manager，通过`HFFunCatalogue`访问 -6. **禁止**在Entity中持有场景引用 +5. **禁止** 在 Entity 中直接访问 Manager，通过 `HFFunCatalogue` 访问 +6. **禁止** 在 Entity 中持有场景引用 ### 7.3 性能优化 -- 使用对象池复用Entity实例 +- 使用对象池复用 Entity 实例 - 使用 `AddSystem()` 延迟初始化系统 -- 属性变更通过 `ChangeAbility()` 通知所有Model -- 死亡Entity通过 `OnDeathFinish()` 回调回收 +- 属性变更通过 `ChangeAbility()` 通知所有 Model +- 死亡 Entity 通过 `OnDeathFinish()` 回调回收 --- **版本**: v1.1 **生效日期**: 2026年 -**适用范围**: StrayFog框架开发人员 \ No newline at end of file +**适用范围**: StrayFog 框架开发人员 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [实体系统入口](README.md) | 本文件是实体系统模块的子文档 | +| [通用技能系统使用指南](../技能系统/使用指南.md) | 技能系统是 Entity 常用子系统 | +| [对象池与运行时对象管理](../内存对象管理/README.md) | Entity 池机制相关 | +| [事件系统](../事件系统/README.md) | Entity 间通信常依赖事件系统 | +| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | 编码规范与开发规则互相引用 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/03_核心功能/Entity/UnityEntities注意事项.md b/modules/frameworks/实体系统/注意事项.md similarity index 55% rename from 03_核心功能/Entity/UnityEntities注意事项.md rename to modules/frameworks/实体系统/注意事项.md index dcce386..347e8c4 100644 --- a/03_核心功能/Entity/UnityEntities注意事项.md +++ b/modules/frameworks/实体系统/注意事项.md @@ -4,19 +4,19 @@ ### enHFCTCEvent 枚举 - **新增项**：`Custom = 281` - 用于自定义事件 -- **用途**：在HFEvent_OnDamage等自定义事件中使用 +- **用途**：在 `HFEvent_OnDamage` 等自定义事件中使用 - **注意**：添加新事件时，确保数值不与其他事件冲突 ### enEntityLayer 枚举 - **现有项**：`None=0`, `Role`, `Monster`, `Max` -- **注意**：没有`Enemy`项，敌人应归类为`Monster` +- **注意**：没有 `Enemy` 项，敌人应归类为 `Monster` ## 2. 实体-系统-模型 (ESM) 架构相关 ### HFAbsEntity 访问方式 -- **Transform访问**：使用 `entity.gameObject.transform.position` 而不是 `entity.transform.position` +- **Transform 访问**：使用 `entity.gameObject.transform.position` 而不是 `entity.transform.position` - **属性访问**：使用公共属性如 `entity.NormalATK` 而不是私有字段 `entity.m_NormalATK` -- **系统获取**：HFAbsEntity 没有 `GetSystem()` 方法，只有 `GetModel()` 方法 +- **系统获取**：`HFAbsEntity` 没有 `GetSystem()` 方法，只有 `GetModel()` 方法 - **模型获取**：通过 `entity.GetModel()` 获取模型实例 ### 系统间通信 @@ -25,23 +25,23 @@ ## 3. 数据表字段映射 -### Role表字段 +### Role 表字段 - `Lifefold` -> 生命值 - `Attackfold` -> 攻击力 - `Defensefold` -> 防御力 - `AttackRange` -> 攻击范围 - `CriticalRate` -> 暴击率 - `CriticalDamage` -> 暴击伤害 -- **注意**：Role表中没有速度字段 (SPD) +- **注意**：Role 表中没有速度字段 (SPD) ## 4. 动画系统相关 ### FSM (有限状态机) 系统 - **HFFMSModel** 现在包含 `CurrentSkeletonAnimation` 属性 -- **访问方式**：通过 `FSM.CurrentSkeletonAnimation` 访问SkeletonAnimation +- **访问方式**：通过 `FSM.CurrentSkeletonAnimation` 访问 SkeletonAnimation - **动画速度设置**：使用 `skeletonAnimation.timeScale = speed` -## 5. AI系统相关 +## 5. AI 系统相关 ### HFAIModel_Enemy - **伤害处理**：通过事件系统 (`HFEvent_OnDamage`) 而不是直接获取系统 @@ -52,12 +52,12 @@ ### 常见错误类型 - **CS0117**: 枚举中不包含指定定义 - 检查枚举项是否存在 - **CS1061**: 类型不包含指定定义 - 检查属性/方法名是否正确 -- **CS0122**: 成员因保护级别不可访问 - 使用公共API而不是私有字段 +- **CS0122**: 成员因保护级别不可访问 - 使用公共 API 而不是私有字段 ### 修复策略 - 优先使用公共属性而不是私有字段 - 通过事件系统进行组件间通信 -- 正确访问GameObject的Transform组件 +- 正确访问 GameObject 的 Transform 组件 - 使用正确的枚举值 ## 7. 架构模式 @@ -65,9 +65,25 @@ ### 系统-模型 (System-Model) 模式 - **AbsHFMoveSystem** 需要指定泛型参数 - **AbsHFAIModel** 不能直接获取系统，应通过事件或模型进行通信 -- **AbsHFAnimationModel** 需要配合AbsHFFMSModel使用 +- **AbsHFAnimationModel** 需要配合 `AbsHFFMSModel` 使用 ### 事件驱动架构 - 自定义事件需继承 `AbsHFEventArg` -- 事件ID使用 `enHFCTCEvent.Custom` 或其他预定义事件 -- 事件分发使用 `Dispatch()` 方法 \ No newline at end of file +- 事件 ID 使用 `enHFCTCEvent.Custom` 或其他预定义事件 +- 事件分发使用 `Dispatch()` 方法 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [实体系统入口](README.md) | 本文件是实体系统模块的子文档 | +| [Entity 开发指南](开发指南.md) | 与开发指南中的 System-Model、属性系统互补 | +| [事件系统](../事件系统/README.md) | 自定义事件派发相关 | +| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | 公共 API 访问方式与开发规则互相引用 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/modules/frameworks/技能系统/README.md b/modules/frameworks/技能系统/README.md new file mode 100644 index 0000000..6e9b0dd --- /dev/null +++ b/modules/frameworks/技能系统/README.md @@ -0,0 +1,134 @@ +# 技能系统 + +## 分类 + +- 核心框架 + +## 目的 + +为角色、怪物等实体提供统一的技能管理、冷却控制、释放接口和事件通知。 + +--- + +## 核心组成 + +| 类/结构 | 职责 | +|---------|------| +| `HFGenericSkillSystem` | 通用技能系统，继承 `AbsHFSkillSystem` | +| `HFGenericSkillModel` | 通用技能模型，继承 `HFAbsModel` | +| `HFEvent_OnSkillUsed` | 技能使用事件 | +| `stSkillConfig` | 技能配置结构 | + +--- + +## 技能管理 + +```csharp +// 添加技能 +skillSystem.AddSkill(skillId); + +// 移除技能 +skillSystem.RemoveSkill(skillId); + +// 检查技能是否就绪 +bool isReady = skillSystem.IsSkillReady(skillId); + +// 获取技能冷却时间 +float cooldown = skillSystem.GetSkillCooldown(skillId); + +// 是否有技能在冷却 +bool hasCooldown = skillSystem.HasSkillInCooldown(); + +// 清除所有冷却 +skillSystem.ClearAllCooldowns(); +``` + +--- + +## 技能使用 + +```csharp +// 对目标使用技能 +skillSystem.UseSkill(skillId, targetEntity); + +// 对位置使用技能 +skillSystem.UseSkillAtPosition(skillId, worldPosition); +``` + +触发事件： + +```csharp +public class HFEvent_OnSkillUsed : AbsHFEventArg +{ + public HFAbsEntity Caster { get; set; } + public int SkillId { get; set; } + public HFAbsEntity Target { get; set; } + public Vector3 Position { get; set; } +} +``` + +--- + +## 自动配置加载 + +系统会根据实体配置自动加载技能： + +```csharp +var config = HFFunCatalogue.NDB.ds_EntityConfig_Sheet_TableData_1FC4334A.ReadTable(ownerEntity.EntityId); +if (config != null && config.SkillID > 0) +{ + AddSkill(config.SkillID); +} +``` + +--- + +## 实体中的添加方式 + +在角色或敌人实体中统一添加： + +```csharp +AddSystem(); +``` + +--- + +## 子系统边界 + +从实体系统角度看，技能相关子目录通常包括： + +- `Models/Skill` — 技能数据模型 +- `Systems/Skill` — 技能系统逻辑 +- `HFSkillTrigger_*` — 技能触发器 +- `HFSkill_*_Releaser` — 技能释放器 + +--- + +## 使用规则 + +- 角色和怪物使用同一套技能系统接口。 +- 技能 ID 在项目中应保持唯一。 +- 技能效果逻辑应在事件处理器中实现，避免直接写在释放器里。 +- 合理设置冷却时间以平衡游戏体验。 + +--- + +## 相关模块 + +- [实体系统](../实体系统/README.md) +- [事件系统](../事件系统/README.md) +- [数据/配置框架](../数据配置框架.md) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 | +| [modules/frameworks/实体系统/README.md](../实体系统/README.md) | 技能系统是实体系统的子系统 | +| [modules/frameworks/事件系统/README.md](../事件系统/README.md) | 技能使用事件依赖事件系统 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/03_核心功能/Entity/通用技能系统使用指南.md b/modules/frameworks/技能系统/使用指南.md similarity index 67% rename from 03_核心功能/Entity/通用技能系统使用指南.md rename to modules/frameworks/技能系统/使用指南.md index bf80962..6a2f153 100644 --- a/03_核心功能/Entity/通用技能系统使用指南.md +++ b/modules/frameworks/技能系统/使用指南.md @@ -2,13 +2,13 @@ ## 概述 -通用技能系统（HFGenericSkillSystem）是一个适用于角色和怪物的统一技能管理系统，提供了一套标准化的技能操作接口。 +通用技能系统（`HFGenericSkillSystem`）是一个适用于角色和怪物的统一技能管理系统，提供了一套标准化的技能操作接口。 ## 架构设计 ### 系统组成 -- **HFGenericSkillSystem** - 通用技能系统（继承自 AbsHFSkillSystem） -- **HFGenericSkillModel** - 通用技能模型（继承自 HFAbsModel） +- **HFGenericSkillSystem** - 通用技能系统（继承自 `AbsHFSkillSystem`） +- **HFGenericSkillModel** - 通用技能模型（继承自 `HFAbsModel`） - **HFEvent_OnSkillUsed** - 技能使用事件 ### 核心功能 @@ -78,7 +78,7 @@ public struct stSkillConfig ### 技能加载 系统会根据实体配置自动加载对应的技能： ```csharp -// 从EntityConfig表加载技能 +// 从 EntityConfig 表加载技能 var config = HFFunCatalogue.NDB.ds_EntityConfig_Sheet_TableData_1FC4334A.ReadTable(ownerEntity.EntityId); if (config != null && config.SkillID > 0) { @@ -102,12 +102,12 @@ public class HFEvent_OnSkillUsed : AbsHFEventArg ## 扩展接口 -### Buff管理 +### Buff 管理 ```csharp -// 添加Buff +// 添加 Buff skillSystem.AddBuff(buffTemplate); -// 移除Buff +// 移除 Buff skillSystem.RemoveBuff(buffId); ``` @@ -123,5 +123,21 @@ skillSystem.RemoveBuff(buffId); 1. 技能释放器的具体实现需要根据游戏需求进行定制 2. 技能效果逻辑应在事件处理器中实现 -3. 确保技能ID在项目中唯一 -4. 合理设置技能冷却时间以平衡游戏体验 \ No newline at end of file +3. 确保技能 ID 在项目中唯一 +4. 合理设置技能冷却时间以平衡游戏体验 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [技能系统入口](README.md) | 本文件是技能系统模块的子文档 | +| [实体系统](../实体系统/README.md) | 技能系统是实体系统的子系统 | +| [事件系统](../事件系统/README.md) | 技能使用事件依赖事件系统 | +| [数据/配置框架](../数据配置框架.md) | 技能配置加载依赖配置框架 | +| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/modules/frameworks/数据配置框架.md b/modules/frameworks/数据配置框架.md new file mode 100644 index 0000000..f1b8420 --- /dev/null +++ b/modules/frameworks/数据配置框架.md @@ -0,0 +1,111 @@ +# 数据 / 配置框架 + +## 分类 + +- 核心框架 + +## 目的 + +管理 XLSX 配置表源、解析、生成运行时数据和读取 API。 + +--- + +## 核心路径 + +- 配置源：`XLSX_SRC/CN/`、`XLSX_SRC/EN/` +- 生成设置：`ProjectSettings/ZYF/ZYXlsx/ZYXlsxProjectSettings.asset` +- Resolve Asset：`Assets/Editor/XLSX_SRC/Resolve/ZYXlsx/` +- 输出数据：`Assets/AutoBuildAsset/{Editor,Hotfix}/AutoFrame/Google.Protobuf/XLSX_SRC/<语言>/` +- 输出代码：`Assets/AutoBuildScript/{Editor,General,Hotfix}/AutoFrame/Google.Protobuf/XLSX_Script/` + +--- + +## 常见配置表 + +| 表名 | 用途 | +|---|---| +| `Constants.xlsx` | 常量配置 | +| `EntityConfig.xlsx` | 实体配置 | +| `Gift.xlsx` | 礼包/奖励配置 | +| `Resource.xlsx` | 资源/道具配置 | +| `SkillGroup.xlsx` | 技能组配置 | +| `SkillReleaser.xlsx` | 技能释放器配置 | +| `SkillTrigger.xlsx` | 技能触发器配置 | +| `SkillUp.xlsx` | 技能升级配置 | +| `Sounds.xlsx` | 音效配置 | +| `Wave.xlsx` | 波次配置（业务示例） | + +--- + +## 运行时加载调用链 + +```text +HFGameStart.LoadDB() + -> Hotfix_ZYXlsx_GoogleProtobuf_Helper.instance.LoadAllXlsx(OnLoadDbFinish) + -> 遍历 enZYXlsxSheet + -> GetExistsDataLang / GetSheetMemoryPackBufferFilePath + -> HFFunCatalogue.Asset.LoadDBHelper(path.GetHashCode(), path, callback) + -> 缓存 sheet bytes 到 mDicLangSheetBytes +``` + +--- + +## 运行时读取 API + +```csharp +// 按主键读取单条 +HFFunCatalogue.NDB.ds_xxx.ReadTableByPK(pk); + +// 读取全表 +HFFunCatalogue.NDB.ds_xxx.ReadTableList(); + +// 读取行列式数据 +HFFunCatalogue.NDB.ds_xxx.ReadTableDeterminant(); +``` + +--- + +## 使用规则 + +- 改表后必须重新生成。 +- 配置读取必须在 `LoadAllXlsx` 完成后。 +- 主键/全表/常量分别用对应 API。 +- 禁止高频全表读取。 +- id 优先来自表/协议/常量，禁止魔法数字。 +- 高频配置在 manager 初始化或窗口打开时缓存。 +- 多语言字段需补齐。 + +--- + +## 变更清单 + +1. 修改源表。 +2. 确认 settings / resolve 配置。 +3. 重新生成。 +4. 检查输出。 +5. 编译验证。 +6. 运行时验证。 +7. 更新文档。 + +--- + +## 相关模块 + +- [实体系统](实体系统/README.md) +- [技能系统](技能系统/README.md) +- [资源管理](资源管理/README.md) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../模块索引.md) | 模块索引是项目知识总入口 | +| [modules/frameworks/实体系统/README.md](实体系统/README.md) | 实体配置来自配置表 | +| [modules/frameworks/技能系统/README.md](技能系统/README.md) | 技能配置来自配置表 | +| [modules/frameworks/资源管理/README.md](资源管理/README.md) | 配置资源加载依赖资源管理 | +| [rules/10-架构说明.md](../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/modules/frameworks/相机系统/README.md b/modules/frameworks/相机系统/README.md new file mode 100644 index 0000000..25a803b --- /dev/null +++ b/modules/frameworks/相机系统/README.md @@ -0,0 +1,122 @@ +# 相机系统 + +## 分类 + +- 核心框架 + +## 目的 + +管理多相机注册、相机堆栈排序、渲染顺序控制，为 UI、场景、特效等提供分层渲染能力。 + +--- + +## 核心类 + +| 类 | 职责 | +|---|---| +| `HFCameraManager` | 相机管理器单例，维护相机列表和主相机引用 | +| `HFMainCamera` | 主相机，管理 CameraStack | +| `AbsHFCameraItem` | 相机项抽象基类，子类实现具体相机逻辑 | + +--- + +## 创建自定义相机 + +继承 `AbsHFCameraItem`，实现 `CameraItem` 和 `Weight` 属性： + +```csharp +public class UIOverlayCamera : AbsHFCameraItem +{ + [SerializeField] private Camera uiCamera; + [SerializeField] private int weight = 10; + + public override Camera CameraItem => uiCamera; + public override int Weight => weight; + + protected override void OnInitialize() + { + base.OnInitialize(); + uiCamera.clearFlags = CameraClearFlags.Depth; + uiCamera.depth = 100; + } +} +``` + +--- + +## 相机堆栈架构 + +```text +HFMainCamera (主相机) + │ + ├── CameraStack (相机堆栈) + │ ├── CameraItem1 (Weight=10) + │ ├── CameraItem2 (Weight=20) + │ └── CameraItem3 (Weight=5) + │ + └── 按 Weight 排序 → 渲染顺序控制 +``` + +--- + +## 管理相机 + +```csharp +public class CameraController : MonoBehaviour +{ + void Start() + { + HFCameraManager cameraMgr = HFCameraManager.Instance; + + UIOverlayCamera uiCamera = GetComponent(); + cameraMgr.AddCamera(uiCamera); + + Camera mainCam = cameraMgr.mainCamera.MainCamera; + } + + void OnDestroy() + { + UIOverlayCamera uiCamera = GetComponent(); + HFCameraManager.Instance.RemoveCamera(uiCamera); + } +} +``` + +--- + +## 常用 API + +| 方法 | 说明 | +|-----|------| +| `AddCamera(AbsHFCameraItem)` | 添加相机到堆栈 | +| `RemoveCamera(AbsHFCameraItem)` | 从堆栈移除相机 | +| `GetCamera(string cameraName)` | 获取指定名称相机 | + +--- + +## 使用规则 + +- 相机项必须继承 `AbsHFCameraItem`。 +- `Weight` 决定堆栈内渲染顺序，值越大越靠后渲染。 +- 添加和移除相机需成对出现，避免残留。 +- UI 相机通常使用 `CameraClearFlags.Depth` 和较高 depth。 + +--- + +## 相关模块 + +- [UI 窗口系统](../UI窗口系统/README.md) +- [资源管理](../资源管理/README.md) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 | +| [modules/frameworks/UI窗口系统/README.md](../UI窗口系统/README.md) | UI 窗口系统常与相机系统协作 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/03_核心功能/相机系统使用指南.md b/modules/frameworks/相机系统/使用指南.md similarity index 64% rename from 03_核心功能/相机系统使用指南.md rename to modules/frameworks/相机系统/使用指南.md index 57a1b7f..d5cd120 100644 --- a/03_核心功能/相机系统使用指南.md +++ b/modules/frameworks/相机系统/使用指南.md @@ -1,8 +1,8 @@ -# StrayFog 框架相机系统使用指南 +# 相机系统使用指南 ## 一、创建自定义相机 -### 1.1 继承AbsHFCameraItem +### 1.1 继承 AbsHFCameraItem ```csharp public class UIOverlayCamera : AbsHFCameraItem @@ -64,12 +64,12 @@ HFMainCamera (主相机) │ ├── CameraItem2 (Weight=20) │ └── CameraItem3 (Weight=5) │ - └── 按Weight排序 → 渲染顺序控制 + └── 按 Weight 排序 → 渲染顺序控制 ``` --- -## 三、相机管理API +## 三、相机管理 API ### 3.1 常用方法 @@ -83,4 +83,19 @@ HFMainCamera (主相机) **版本**: v1.0 **生效日期**: 2026年 -**适用范围**: GiftGameX项目业务开发人员 \ No newline at end of file +**适用范围**: GiftGameX 项目业务开发人员 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [相机系统入口](README.md) | 本文件是相机系统模块的子文档 | +| [UI 窗口系统](../UI窗口系统/README.md) | UI 窗口系统常与相机系统协作 | +| [资源管理](../资源管理/README.md) | 相机资源加载依赖资源管理 | +| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/modules/frameworks/第三方插件.md b/modules/frameworks/第三方插件.md new file mode 100644 index 0000000..737ffd6 --- /dev/null +++ b/modules/frameworks/第三方插件.md @@ -0,0 +1,49 @@ +# 第三方插件 + +## 分类 + +- 项目框架 + +## 目的 + +记录第三方插件和 embedded packages 的用途、边界和修改规则。 + +## 已知线索 + +- 插件目录：`Assets/ThirdPlugins/` +- Package 目录：`Packages/` +- 已识别插件包括 HybridCLR、Spine、DOTween、SuperScrollView、Astar、UnityWebSocket、SoundManagerPro、SRDebugger 等。 + +## 梳理任务 + +- [ ] 梳理主要插件列表和用途。 +- [ ] 标记哪些插件是运行时依赖，哪些是编辑器依赖。 +- [ ] 梳理插件是否有项目本地修改。 +- [ ] 梳理升级插件的风险和验证步骤。 +- [ ] 记录禁止直接修改 vendor 的规则例外。 + +## 待确认 + +- 哪些插件来自 Asset Store，哪些来自 package。 +- 是否有插件被项目深度改造。 +- 哪些插件参与 hotfix 或 WebGL 构建。 + +## 相关模块 + +- [通用框架](通用框架/README.md) +- [编辑器工具索引](../模块索引.md#编辑器工具) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../模块索引.md) | 编辑器工具索引 | +| [modules/frameworks/通用框架/README.md](通用框架/README.md) | 通用框架 | +| [rules/10-架构说明.md](../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/20-开发规则.md](../../rules/20-开发规则.md) | 开发规则与框架/生成规则互相引用 | +| [rules/30-模块登记规则.md](../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | +| TODO：补充依赖或使用本框架的模块文档 | 如依赖本框架的功能模块 | \ No newline at end of file diff --git a/modules/frameworks/编辑器工具/README.md b/modules/frameworks/编辑器工具/README.md new file mode 100644 index 0000000..b5a133b --- /dev/null +++ b/modules/frameworks/编辑器工具/README.md @@ -0,0 +1,54 @@ +# 编辑器工具 + +## 分类 + +- 编辑器工具 + +## 目的 + +汇总 Unity Editor 内使用的 StrayFog 相关编辑器扩展和项目编辑器资源。 + +--- + +## SF Editor + +- **路径**：`Assets/StrayFog/Editor/` +- **程序集**：`SFEditor` +- **职责**： + - StrayFog 编辑器扩展 + - 打包、UGUI、SpriteAtlas、表格路径选择等编辑器工具 + +--- + +## Project Editor Assets + +- **路径**：`Assets/Editor/` +- **职责**： + - 项目编辑器资源与脚本 + - 引导菜单、编辑器插件 + +--- + +## 使用规则 + +- 编辑器工具可以读取/生成核心运行时代码，但运行时代码不要反向依赖 Editor 程序集。 +- 新增 Editor 工具时，优先在 `Assets/StrayFog/Editor/` 或 `Assets/Editor/` 下按功能分类存放。 + +--- + +## 相关模块 + +- [通用框架](../通用框架/README.md) +- [资源管理](../资源管理/README.md) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 编辑器工具层的架构说明 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/06_工具脚本/UI工具/ExternalCommandListener.cs b/modules/frameworks/编辑器工具/UI工具/ExternalCommandListener.cs similarity index 100% rename from 06_工具脚本/UI工具/ExternalCommandListener.cs rename to modules/frameworks/编辑器工具/UI工具/ExternalCommandListener.cs diff --git a/06_工具脚本/UI工具/ExternalCommandListener.cs.meta b/modules/frameworks/编辑器工具/UI工具/ExternalCommandListener.cs.meta similarity index 100% rename from 06_工具脚本/UI工具/ExternalCommandListener.cs.meta rename to modules/frameworks/编辑器工具/UI工具/ExternalCommandListener.cs.meta diff --git a/06_工具脚本/UI工具/RemoteCommand.cs b/modules/frameworks/编辑器工具/UI工具/RemoteCommand.cs similarity index 100% rename from 06_工具脚本/UI工具/RemoteCommand.cs rename to modules/frameworks/编辑器工具/UI工具/RemoteCommand.cs diff --git a/06_工具脚本/UI工具/RemoteCommand.cs.meta b/modules/frameworks/编辑器工具/UI工具/RemoteCommand.cs.meta similarity index 100% rename from 06_工具脚本/UI工具/RemoteCommand.cs.meta rename to modules/frameworks/编辑器工具/UI工具/RemoteCommand.cs.meta diff --git a/06_工具脚本/UI工具/UIPrefabGenerator.cs b/modules/frameworks/编辑器工具/UI工具/UIPrefabGenerator.cs similarity index 100% rename from 06_工具脚本/UI工具/UIPrefabGenerator.cs rename to modules/frameworks/编辑器工具/UI工具/UIPrefabGenerator.cs diff --git a/06_工具脚本/UI工具/UIPrefabGenerator.cs.meta b/modules/frameworks/编辑器工具/UI工具/UIPrefabGenerator.cs.meta similarity index 100% rename from 06_工具脚本/UI工具/UIPrefabGenerator.cs.meta rename to modules/frameworks/编辑器工具/UI工具/UIPrefabGenerator.cs.meta diff --git a/06_工具脚本/UI工具/UIPrefabToJson.cs b/modules/frameworks/编辑器工具/UI工具/UIPrefabToJson.cs similarity index 100% rename from 06_工具脚本/UI工具/UIPrefabToJson.cs rename to modules/frameworks/编辑器工具/UI工具/UIPrefabToJson.cs diff --git a/06_工具脚本/UI工具/UIPrefabToJson.cs.meta b/modules/frameworks/编辑器工具/UI工具/UIPrefabToJson.cs.meta similarity index 100% rename from 06_工具脚本/UI工具/UIPrefabToJson.cs.meta rename to modules/frameworks/编辑器工具/UI工具/UIPrefabToJson.cs.meta diff --git a/modules/frameworks/编辑器工具/UI拼接工具.md b/modules/frameworks/编辑器工具/UI拼接工具.md new file mode 100644 index 0000000..be40356 --- /dev/null +++ b/modules/frameworks/编辑器工具/UI拼接工具.md @@ -0,0 +1,248 @@ +# UI 拼接工具 + +## 概述 + +UI 拼接工具提供 JSON 配置与 Unity 预制体的双向转换，帮助 UI 相关人员通过 JSON 配置文件快速生成 UI 预制体，同时支持从现有预制体反向导出 JSON 用于版本控制或重新生成。 + +## 核心组件 + +| 组件 | 职责 | 文件路径 | +|-----|------|---------| +| **UIPrefabGenerator** | 解析 JSON 并生成 UI 预制体 | `Assets/Editor/Command/UIPrefabGenerator.cs` | +| **UIPrefabToJson** | 从预制体反向导出 JSON | `Assets/Editor/Command/UIPrefabToJson.cs` | +| **RemoteCommand** | 提供外部调用接口 | `Assets/Editor/Command/RemoteCommand.cs` | +| **ExternalCommandListener** | 监听外部命令触发文件 | `Assets/Editor/Command/ExternalCommandListener.cs` | + +工具脚本在文档库中的位置（已并入编辑器工具模块）： + +``` +modules/frameworks/编辑器工具/UI工具/ +├── ExternalCommandListener.cs # 外部命令监听器 +├── RemoteCommand.cs # 远程命令接口 +├── UIPrefabGenerator.cs # JSON 转预制体生成器 +└── UIPrefabToJson.cs # 预制体转 JSON 导出器 +``` + +## JSON 配置文件结构 + +```json +{ + "name": "BagWindow", + "width": 1024, + "height": 768, + "elements": [ + { + "type": "Image", + "name": "BgPanel", + "anchorMin": [0, 0], + "anchorMax": [1, 1], + "position": [0, 0, 0], + "sizeDelta": [0, 0], + "sprite": "Assets/Game/GameHFResource/CN/UIWindows/BagWindow/Sprites/Bg.png" + }, + { + "type": "Text", + "name": "TitleText", + "anchorMin": [0.5, 0.9], + "anchorMax": [0.5, 0.9], + "position": [0, 0, 0], + "sizeDelta": [200, 40], + "text": "背包", + "font": "Assets/Game/GameHFResource/CN/Fonts/FZY4K-M05S SDF.asset", + "fontSize": 28, + "color": [1, 1, 1, 1] + } + ] +} +``` + +## 支持的 UI 元素类型 + +| 类型 | 对应 Unity 组件 | 关键属性 | +|-----|-------------|---------| +| **Image** | Image | sprite, color, type, preserveAspect | +| **TextMeshProUGUI** | TextMeshProUGUI | text, font, fontSize, color, alignment | +| **Button** | Button | interactable, transition, navigationMode | +| **Slider** | Slider | minValue, maxValue, value, wholeNumbers, direction | +| **Toggle** | Toggle | isOn, toggleTransition, transition | +| **InputField** | InputField | text, placeholder, characterLimit, contentType | +| **ScrollRect** | ScrollRect | horizontal, vertical, movementType | +| **GridLayoutGroup** | GridLayoutGroup | cellSize, spacing, constraint, padding | +| **VerticalLayoutGroup** | VerticalLayoutGroup | spacing, childAlignment, padding | +| **HorizontalLayoutGroup** | HorizontalLayoutGroup | spacing, childAlignment, padding | + +## 外部命令触发机制 + +### 触发方式 + +通过创建/修改 `Trigger_Command.txt` 文件触发 UI 生成： + +``` +GenerateUIPrefab:Assets/Editor/UI/BagWindow.json +``` + +### 命令格式 + +``` +<命令名>:<参数1>:<参数2>:... +``` + +**支持的命令**： + +| 命令 | 参数 | 说明 | +|-----|------|------| +| **GenerateUIPrefab** | `jsonPath` [, `prefabPath`] | 根据 JSON 生成 UI 预制体 | +| **ExportPrefabToJson** | `prefabPath` [, `jsonPath`] | 从预制体反向导出 JSON | +| **ReadJson** | [参数列表] | 读取 JSON 配置（测试用） | + +### 完整执行流程 + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ 外部系统写入命令到 Trigger_Command.txt │ +└─────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ ExternalCommandListener (FileSystemWatcher) 检测到文件变化 │ +└─────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ 解析命令格式：GenerateUIPrefab:Assets/Editor/UI/BagWindow.json │ +└─────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ 通过反射调用 RemoteCommand.GenerateUIPrefab(string[] args) │ +└─────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ UIPrefabGenerator.GeneratePrefabFromJson(jsonPath, prefabPath) │ +└─────────────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ 生成预制体到指定路径：Assets/Game/GameHFResource/CN/UIWindows/... │ +└─────────────────────────────────────────────────────────────────────┘ +``` + +## 使用示例 + +### 方式一：外部命令触发 + +```bash +# 正向：从 JSON 生成预制体 +echo "GenerateUIPrefab:Assets/Editor/UI/BagWindow.json" > "F:\JMNet\CrystalBattle_Client\Trigger_Command.txt" + +# 反向：从预制体导出 JSON +echo "ExportPrefabToJson:Assets/Game/GameHFResource/CN/UIWindows/BagWindow/BagWindow.prefab" > "F:\JMNet\CrystalBattle_Client\Trigger_Command.txt" +``` + +### 方式二：Unity 编辑器菜单 + +**正向生成**： +1. 打开 Unity 编辑器 +2. 点击菜单 `Tools > External > Test GenerateUIPrefab` +3. 查看 Console 窗口日志确认执行结果 + +**反向导出**： +1. 打开 Unity 编辑器 +2. 点击菜单 `Tools > UI > Export Prefab to JSON` +3. 选择要导出的预制体文件 + +### 方式三：代码调用 + +```csharp +// 正向：从 JSON 生成预制体 +UIPrefabGenerator.GeneratePrefabFromJson( + "Assets/Editor/UI/BagWindow.json", + "Assets/Game/GameHFResource/CN/UIWindows/BagWindow/BagWindow.prefab" +); + +// 反向：从预制体导出 JSON +UIPrefabToJson.ExportPrefabToJson( + "Assets/Game/GameHFResource/CN/UIWindows/BagWindow/BagWindow.prefab", + "Assets/Editor/UI/BagWindow.json" +); +``` + +## 注意事项 + +1. **路径格式**：JSON 中的资源路径使用 `/` 分隔符，且为 Unity 项目相对路径 +2. **资源引用**：确保 JSON 中引用的 Sprite、Font 等资源已存在于项目中 +3. **编码格式**：JSON 文件使用 UTF-8 编码 +4. **坐标系统**：使用 Unity RectTransform 的 anchorMin/anchorMax/position/sizeDelta 四元组 +5. **文件锁定**：生成前确保目标预制体文件未被其他进程占用 + +## 部署步骤 + +### 方法一：手动复制 + +1. 复制 `modules/frameworks/编辑器工具/UI工具/` 目录下的所有文件 +2. 粘贴到目标项目的 `Assets/Editor/Command/` 目录中 +3. 确保目录结构如下： + ``` + Assets/Editor/Command/ + ├── ExternalCommandListener.cs + ├── RemoteCommand.cs + ├── UIPrefabGenerator.cs + └── UIPrefabToJson.cs + ``` + +### 方法二：自动部署脚本 + +创建部署脚本 `DeployUITools.bat`： + +```batch +@echo off +set "SOURCE_DIR=E:\AI\UnityAI\modules\frameworks\编辑器工具\UI工具" +set "TARGET_DIR=%cd%\Assets\Editor\Command" + +mkdir "%TARGET_DIR%" 2>nul +xcopy "%SOURCE_DIR%\*.cs" "%TARGET_DIR%\" /y +xcopy "%SOURCE_DIR%\*.cs.meta" "%TARGET_DIR%\" /y + +echo UI 工具部署完成 +pause +``` + +### 部署检查项 + +| 检查项 | 要求 | +|-------|------| +| **目标路径** | 必须放置在 `Assets/Editor/Command/` 目录下 | +| **文件完整性** | 必须包含所有 4 个 cs 文件及其 meta 文件 | +| **Unity 版本** | 支持 Unity 2020 及以上版本 | +| **依赖组件** | 需要导入 TextMeshPro 包 | + +### 验证部署 + +部署完成后，在 Unity 编辑器中验证： + +1. 打开 Unity 编辑器 +2. 检查菜单 `Tools > UI` 是否存在 +3. 检查菜单 `Tools > External` 是否存在 +4. 在 Console 窗口确认无编译错误 + +--- + +**版本**: v1.2 +**适用**: StrayFog 框架 UI 拼接开发人员 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [编辑器工具入口](README.md) | 本文件是编辑器工具模块的子文档 | +| [UI 窗口系统](../UI窗口系统/README.md) | UI 拼接工具服务于 UI 窗口系统 | +| [UI 界面拼接设计指南](../UI窗口系统/界面拼接.md) | 设计指南说明 JSON 驱动的界面拼接原则 | +| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义编辑器工具层与运行时层边界 | +| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | 编辑器工具开发规则互相引用 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/modules/frameworks/网络系统.md b/modules/frameworks/网络系统.md new file mode 100644 index 0000000..01e5f5a --- /dev/null +++ b/modules/frameworks/网络系统.md @@ -0,0 +1,121 @@ +# 网络系统 + +## 分类 + +- 核心框架 + +## 目的 + +提供 WebSocket 连接、protobuf 消息收发、消息 ID / route 映射和错误响应处理。 + +--- + +## 核心路径 + +- protobuf 源：`GoogleProtobufNetwork/` +- 生成输出：`Assets/Game/GameHFScripte/CopyToHF/Network/` +- WebSocket：`Assets/Game/GameHFScripte/GameFunction/WebSocket/` + +--- + +## 核心类 + +| 类 | 职责 | +|---|---| +| `HFSeverManager` | 网络管理器单例 | +| `WSSession` | WebSocket 会话 | +| `HFM_Socket_WS` | WebSocket 底层连接 | +| `HFWebSocket_Manager_AutoMsgMap` | 自动生成消息映射 | +| `HFNetWorkMsgIdMap` | 网络消息 ID 映射 | +| `MessagePage` | 数据包编解码 | + +--- + +## C2S 发送链路 + +```text +IMessage.Dispatch() + -> HFSeverManager.Instance.SendMsg(message) + -> HFSeverManager.OnAuto_OnGetProtocNo(message) + -> HFSeverManager.OnAuto_OnGetRoute(Network_MsgId) + -> m_Session.SendMessage(protoNo, route, PacketType.Data, Request, message) +``` + +`IMessage.Dispatch()` 定义在 `Assets/Game/GameHFScripte/GameFunction/WebSocket/Extends/HFServer_Extend.cs`。 + +--- + +## WebSocket 连接流程 + +```text +登录管理器.ConnectServer + -> HFSeverManager.Connect(MainConnect, WebSocket, ip, port, token) + -> WSSession.Connect + -> HFM_Socket_WS.Connect + -> Handshake -> HandshakeAck -> 连接成功回调 +``` + +--- + +## S2C 收包和派发 + +```text +WSSession.ReceiveMessages(PacketType.Data) + -> MessagePage.Decode(packet.Body) + -> Response.MessageId / Push.Route -> Network_MsgId + -> HFSeverManager.OnAuto_OnMergeFrom(msgid, body) + -> protobuf Parser.ParseFrom + -> 反射创建 HFEvent_STC_{MessageTypeName} + -> 写入 Request / ErrorCode + -> AbsHFEventArg.Dispatch() + -> HFEventManager.Instance.STCEvent.Dispatch(arg) +``` + +--- + +## 自动生成映射 + +- `HFWebSocket_Manager_AutoMsgMap.cs`：提供 `OnAuto_OnGetProtocNo`、`OnAuto_OnGetRoute`、`OnAuto_OnMergeFrom`、`msrDicRouteToMsg`、S2C/C2S 类型字典。 +- `HFNetWorkMsgIdMap.cs`：为 protobuf partial class 标记 `[HFNetworkMsg(...)]`。 + +--- + +## 使用规则 + +- 新增协议先改 `.proto`、`msg.proto`、`route.txt`。 +- 不手动修改生成输出。 +- 不硬编码 route 或数字 msgId。 +- UI 监听 S2C 必须在 `OnClose` 移除。 +- 错误响应会触发 `HFEvent_ErrorCode`。 + +--- + +## 协议变更清单 + +1. 修改 `.proto` 和 `msg.proto`。 +2. 登记 msgId / route。 +3. 重新生成 C# 代码。 +4. 检查 `HFNetWorkMsgIdMap.cs` / `HFWebSocket_Manager_AutoMsgMap.cs`。 +5. 更新业务入口和监听。 +6. 验证。 + +--- + +## 相关模块 + +- [事件系统](事件系统/README.md) +- [数据/配置框架](数据配置框架.md) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../模块索引.md) | 模块索引是项目知识总入口 | +| [modules/frameworks/事件系统/README.md](事件系统/README.md) | S2C 消息派发为 STC 事件 | +| [modules/frameworks/数据配置框架.md](数据配置框架.md) | 配置表与网络消息可能联动 | +| [rules/10-架构说明.md](../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/modules/frameworks/资源管理/README.md b/modules/frameworks/资源管理/README.md new file mode 100644 index 0000000..ef0d7be --- /dev/null +++ b/modules/frameworks/资源管理/README.md @@ -0,0 +1,136 @@ +# 资源管理 + +## 分类 + +- 核心框架 + +## 目的 + +管理 AssetBundle、语言资源、图集、prefab、DllBytes 等资源的加载、缓存和释放。 + +--- + +## 核心路径 + +- AssetBundle：`Assets/Game/GameHFScripte/CopyToHF/AssetBundle/` +- 图集：`Assets/Game/GameHFScripte/CopyToHF/SpriteAtlas/` +- 资源目录：`Assets/Game/GameHFResource/CN/`、`EN/`、`DllBytes/` + +--- + +## 核心类 + +| 类 | 职责 | +|---|---| +| `HFABMgr` | AssetBundle 资源管理器单例 | +| `HFAssetLoader` | 具体资源加载器 | +| `HFAssetRequest` | 资源加载请求 | +| `HFAssetBundlePathAttribute` | 资源路径属性，标记资源根目录、相对路径、语言包规则等 | +| `HFGlobal_SpriteAtlas` | 图集全局管理 | + +--- + +## 资源路径规则 + +`HFAssetBundlePathAttribute` 记录： + +- 资源根目录 +- 相对路径 +- 是否忽略语言包 +- 是否场景 +- 线程优先级 + +`ChangeLanguage` 生成： + +- `editorPath` +- `assetBundlePath` +- `assetBundleKey` +- `assetName` + +`HFABMgr.OnCheckAssetBundlePathAttributeLanguage` 在当前语言无资源时回退默认语言。 + +--- + +## 加载流程 + +```text +HFABMgr.LoadInMemory(pathAttr) + -> OnReadAssetBundleManifest() + -> OnCheckAssetBundlePathAttributeLanguage() + -> new HFAssetRequest(...) + -> OnStartLoad() + -> 获取或创建 HFAssetLoader + -> HFAssetLoader.LoadAsset() +``` + +--- + +## 加载模式 + +### Editor 模式 + +```text +enHFAbLoadModel.Editor + -> SFAssetUtility_Unity.LoadFromFile(editorPath) + -> 直接读取编辑器资源 +``` + +### 非 Editor 模式 + +```text +读取 AssetBundleManifest + -> 解析依赖 + -> AssetBundle.LoadFromMemoryAsync 读取主资源 +``` + +### CDN / 边玩边下 + +```text +缺失资源进入 WaitDownload + -> HFAssetsDownLoadManager 下载 + -> HFABMgr.SaveFile 保存到本地 + -> 加载完成 +``` + +--- + +## 图集加载 + +```text +SpriteAtlasManager.atlasRequested + -> HFGlobal_SpriteAtlas.Instance.GetSpriteAtlasPath(spriteAtlasName) + -> HFABMgr.OnLoadInMemory(spriteAtlasAttribute) + -> callback(SpriteAtlas) +``` + +--- + +## 使用规则 + +- 资源路径统一通过 `HFAssetBundlePathAttribute` 配置。 +- 加载资源统一走 `HFFunCatalogue.Asset.LoadAsset()` 或 `HFABMgr.LoadInMemory()`。 +- 语言资源按 `GameHFResource//` 分目录存放。 +- 图集按业务或 UI 模块划分。 + +--- + +## 相关模块 + +- [UI 窗口系统](../UI窗口系统/README.md) +- [实体系统](../实体系统/README.md) +- [场景系统](../场景系统.md) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 | +| [modules/frameworks/UI窗口系统/README.md](../UI窗口系统/README.md) | UI 资源加载依赖资源管理 | +| [modules/frameworks/实体系统/README.md](../实体系统/README.md) | 实体资源加载依赖资源管理 | +| [modules/frameworks/场景系统.md](../场景系统.md) | 场景资源加载依赖资源管理 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/03_核心功能/资源管理使用指南.md b/modules/frameworks/资源管理/使用指南.md similarity index 56% rename from 03_核心功能/资源管理使用指南.md rename to modules/frameworks/资源管理/使用指南.md index 21ad7ad..b2212d5 100644 --- a/03_核心功能/资源管理使用指南.md +++ b/modules/frameworks/资源管理/使用指南.md @@ -1,6 +1,6 @@ -# StrayFog 框架资源管理使用指南 +# 资源管理使用指南 -## 一、AssetBundle资源加载 +## 一、AssetBundle 资源加载 ### 1.1 加载资源示例 @@ -9,8 +9,8 @@ public class ResourceLoader : MonoBehaviour { public void LoadPlayerModel(int resId, Action onLoaded) { - // 通过HFFunCatalogue统一入口加载资源 - // resId: 从Res配置表中读取的资源ID + // 通过 HFFunCatalogue 统一入口加载资源 + // resId: 从 Res 配置表中读取的资源 ID HFFunCatalogue.Asset.LoadAsset(resId, (res, obj) => { if (obj != null) @@ -30,7 +30,7 @@ public class ResourceLoader : MonoBehaviour ### 1.2 实体资源加载示例 ```csharp -// 在Entity中加载资源 +// 在 Entity 中加载资源 HFFunCatalogue.Asset.LoadAsset(data.EntityRes.Id, (res, obj) => { if (!entity.isDeath) { @@ -42,7 +42,7 @@ HFFunCatalogue.Asset.LoadAsset(data.EntityRes.Id, (res, obj) => { --- -## 二、资源管理API +## 二、资源管理 API ### 2.1 常用方法 @@ -83,4 +83,20 @@ loader.LoadAsset() → 异步加载 **版本**: v1.0 **生效日期**: 2026年 -**适用范围**: GiftGameX项目业务开发人员 \ No newline at end of file +**适用范围**: GiftGameX 项目业务开发人员 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [资源管理入口](README.md) | 本文件是资源管理模块的子文档 | +| [UI 窗口系统](../UI窗口系统/README.md) | UI 资源加载依赖资源管理 | +| [实体系统](../实体系统/README.md) | 实体资源加载依赖资源管理 | +| [场景系统](../场景系统.md) | 场景资源加载依赖资源管理 | +| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/modules/frameworks/通用框架/README.md b/modules/frameworks/通用框架/README.md new file mode 100644 index 0000000..ee76f6c --- /dev/null +++ b/modules/frameworks/通用框架/README.md @@ -0,0 +1,70 @@ +# 通用框架 + +## 分类 + +- 项目框架 + +## 目的 + +记录 general/shared 代码、生成框架、StrayFog 核心和跨模块通用能力。 + +## 已知线索 + +- General：`Assets/Game/GameGeneralScripte/` +- 生成 General：`Assets/AutoBuildScript/General/` +- StrayFog Core：`Assets/StrayFog/Core/` +- 程序集：`GameGeneral`、`ZY.General.ZYCore`、`StrayFogCore` + +## 当前结构 + +- `GameGeneralScripte/`：项目通用运行时代码，包含 `CopyToGeneral`、状态机扩展、`GameGeneral.asmdef`、`SEHFCommon.dll`。 +- `AutoBuildScript/General/`：生成框架的 General 层，包含 `ZYCore`、`ZYXlsx`、`ZYUGUI` 的通用模板和属性。 +- `StrayFog/Core/`：底层核心程序集和模拟行为桥接，包含 `SFCore.dll`、`SFGlobalData`、`SFAssetUtility_Unity`、`SimulateBehaviour`。 +- `GameGeneralScripte/CopyToGeneral/AssetBundle/HFAssetBundleHelper.cs`：资源路径、StreamingAssets、PersistentData、CDNAssets、微信小游戏文件读写适配。 +- `GameGeneralScripte/CopyToGeneral/DllHelper/HFDllHelper.cs`：Hotfix DLL、PDB、HybridCLR AOT DLL bytes 路径和读取。 +- `GameGeneralScripte/CopyToGeneral/Enum/HFEnumForAssetBundle.cs`：AssetBundle 加载/更新模式枚举。 +- `GameGeneralScripte/StateMachineBehaviour/`：Animator 状态机扩展和只读属性 Drawer。 + +## 边界判断 + +- `GameGeneralScripte` 更像项目运行时可依赖的通用层。 +- `AutoBuildScript/General` 更像代码生成框架的通用模板层。 +- `StrayFog/Core` 提供更底层的工具、全局路径和模拟行为桥接能力。 +- 资源框架、配置框架、Hotfix 启动都会依赖这里的通用能力；反向依赖 hotfix 业务逻辑应避免。 + +## 梳理任务 + +- [x] 梳理 `GameGeneralScripte` 和 `AutoBuildScript/General` 的边界。 +- [x] 梳理 StrayFog Core 提供的基础能力。 +- [x] 梳理通用 attributes、enum、dll helper、asset bundle helper。 +- [x] 梳理哪些功能/框架允许依赖 general/shared。 +- [x] 梳理生成代码和手写代码的边界。 + +## 待确认 + +- `StrayFog` 是项目自研框架还是外部框架。 +- `CopyToGeneral` 的复制/生成来源需要继续追 `AutoBuildScript` 配置。 +- General 层建议保持底层通用，不依赖 hotfix 业务层。 + +## 相关模块 + +- [Hotfix 启动/目录](../Hotfix启动.md) +- [资源框架](../资源管理/README.md) +- [数据/配置框架](../数据配置框架.md) + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 | +| [modules/frameworks/数据配置框架.md](../数据配置框架.md) | 数据/配置框架 | +| [modules/frameworks/Hotfix启动.md](../Hotfix启动.md) | Hotfix 启动/目录 | +| [modules/frameworks/资源管理/README.md](../资源管理/README.md) | 资源框架 | +| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 | +| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | 开发规则与框架/生成规则互相引用 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | +| TODO：补充依赖或使用本框架的模块文档 | 如依赖本框架的功能模块 | \ No newline at end of file diff --git a/01_框架架构/StrayFog框架架构分析.md b/modules/frameworks/通用框架/框架架构.md similarity index 71% rename from 01_框架架构/StrayFog框架架构分析.md rename to modules/frameworks/通用框架/框架架构.md index 713c8f4..8ce9da4 100644 --- a/01_框架架构/StrayFog框架架构分析.md +++ b/modules/frameworks/通用框架/框架架构.md @@ -1,14 +1,16 @@ # StrayFog 框架架构分析 +> 本文档从实现视角分析 StrayFog 框架的整体架构。高层架构规则与程序集边界见 [rules/10-架构说明.md](../../../rules/10-架构说明.md)。 + ## 一、框架整体架构 ### 1.1 模块划分 | 模块层级 | 路径 | 职责描述 | |---------|------|---------| -| **Core层** | `Assets/StrayFog/Core` | 核心基础框架，模拟行为系统、全局数据管理 | -| **HF层** | `Assets/Game/GameHFScripte/CopyToHF` | 游戏核心业务框架，资源管理、事件系统、相机管理等 | -| **General层** | `Assets/Game/GameGeneralScripte` | 通用工具层，状态机、辅助工具等 | +| **Core 层** | `Assets/StrayFog/Core` | 核心基础框架，模拟行为系统、全局数据管理 | +| **HF 层** | `Assets/Game/GameHFScripte/CopyToHF` | 游戏核心业务框架，资源管理、事件系统、相机管理等 | +| **General 层** | `Assets/Game/GameGeneralScripte` | 通用工具层，状态机、辅助工具等 | ### 1.2 架构图 @@ -31,7 +33,7 @@ --- -## 二、Core层架构 +## 二、Core 层架构 ### 2.1 SimulateBehaviour 模拟行为系统 @@ -40,11 +42,11 @@ ```csharp public interface ISimulateBehaviour { - long simulateGlobalId { get; } // 模拟行为全局ID - int bindGameObjectInstanceId { get; } // 绑定对象实例ID - void BindGameObject(GameObject _go); // 绑定GameObject - void UnBindGameObject(); // 解绑GameObject - // ... 完整的MonoBehaviour生命周期方法 + long simulateGlobalId { get; } // 模拟行为全局 ID + int bindGameObjectInstanceId { get; } // 绑定对象实例 ID + void BindGameObject(GameObject _go); // 绑定 GameObject + void UnBindGameObject(); // 解绑 GameObject + // ... 完整的 MonoBehaviour 生命周期方法 } ``` @@ -52,8 +54,8 @@ public interface ISimulateBehaviour | 设计目标 | 实现方式 | |---------|---------| -| **解耦MonoBehaviour** | 将逻辑从MonoBehaviour中剥离，便于测试和复用 | -| **生命周期控制** | 完整模拟Unity生命周期，支持自定义调度 | +| **解耦 MonoBehaviour** | 将逻辑从 MonoBehaviour 中剥离，便于测试和复用 | +| **生命周期控制** | 完整模拟 Unity 生命周期，支持自定义调度 | | **对象池优化** | 配合对象池实现高效对象复用 | #### 2.1.3 目录结构 @@ -63,14 +65,14 @@ SimulateBehaviour/ ├── ISimulateBehaviour.cs # 核心接口定义 ├── Bind/ # 绑定实现 │ ├── IBindSimulateBehaviour.cs -│ ├── AbsBindSimulateBehaviour_Mono.cs # Mono绑定基类 -│ ├── AbsBindSimulateBehaviour_UI.cs # UI绑定基类 +│ ├── AbsBindSimulateBehaviour_Mono.cs # Mono 绑定基类 +│ ├── AbsBindSimulateBehaviour_UI.cs # UI 绑定基类 │ └── BindSimulateBehaviour_Collect.cs # 收集器 ├── MonoBehaviour/ # 各生命周期模拟实现 │ ├── SimulateMonoBehaviour_Awake__xxx.cs │ ├── SimulateMonoBehaviour_Update__xxx.cs -│ └── ... (40+生命周期方法) -└── UIBehaviour/ # UI生命周期模拟 +│ └── ... (40+ 生命周期方法) +└── UIBehaviour/ # UI 生命周期模拟 ├── SimulateUIBehaviour_Awake__xxx.cs └── ... ``` @@ -82,16 +84,16 @@ SimulateBehaviour/ ```csharp public sealed class SFGlobalData { - public static string assetBundleRoot; // AB包根路径 + public static string assetBundleRoot; // AB 包根路径 public static string streamingAssetsRoot; // 流式资源根路径 - public static string cdnassetBundleRoot; // CDN资源路径 + public static string cdnassetBundleRoot; // CDN 资源路径 public static RuntimePlatform Platform(); // 当前平台判断 } ``` --- -## 三、HF层架构 +## 三、HF 层架构 ### 3.1 接口体系 @@ -116,13 +118,13 @@ IHFObject (基础对象接口) | `IHFObject` | 基础对象标识 | 无 | | `IHFRecycle` | 对象回收机制 | `Recycle()` | | `IHFGlobal` | 全局唯一标识 | `globalId` | -| `IHFClone` | 对象克隆能力 | 系列Clone方法 | +| `IHFClone` | 对象克隆能力 | 系列 Clone 方法 | | `IHFLanguage` | 多语言支持 | 语言切换 | | `IHFScene` | 场景管理 | 场景加载/卸载 | ### 3.2 对象池系统 -#### 3.2.1 HFObjectMemPool - GameObject对象池 +#### 3.2.1 HFObjectMemPool - GameObject 对象池 ```csharp public class HFObjectMemPool @@ -143,7 +145,7 @@ public class HFScriptMemPool : IHFRecycle { private Queue m_UnoccupiedPool; private List m_UsingPool; - // 支持MonoBehaviour和普通类的自动创建 + // 支持 MonoBehaviour 和普通类的自动创建 } ``` @@ -154,7 +156,7 @@ public class HFScriptMemPool : IHFRecycle | **双池结构** | 空闲池 + 使用池 | 高效管理对象状态 | | **内存泄漏检测** | 归还时校验来源 | 及时发现问题 | | **泛型支持** | `HFScriptMemPool` | 类型安全 | -| **Mono支持** | 自动创建GameObject | 无缝集成Unity | +| **Mono 支持** | 自动创建 GameObject | 无缝集成 Unity | ### 3.3 事件系统 @@ -177,7 +179,7 @@ public abstract class AbsHFEventHandle : IHFEventHandle where K : struct, Enum where T : IHFEventArg { - // 多级索引: EventId -> TypeHashCode -> Action列表 + // 多级索引: EventId -> TypeHashCode -> Action 列表 HFMultiKeyDictionary> mICacheEventActionMaping; } ``` @@ -189,10 +191,10 @@ public abstract class AbsHFEventHandle : IHFEventHandle Dispatch(arg) │ ▼ -获取 EventId 对应的 Action字典 +获取 EventId 对应的 Action 字典 │ ▼ -获取 参数类型HashCode 对应的 CacheEventAction +获取 参数类型 HashCode 对应的 CacheEventAction │ ▼ 遍历执行所有 Action @@ -235,7 +237,7 @@ loader.LoadAsset() → 异步加载 #### 3.4.3 依赖管理 -通过Manifest文件解析资源依赖关系： +通过 Manifest 文件解析资源依赖关系： ```csharp HFAssetBundlePathAttribute OnGetDependencyAbpAttr(string _depManifestName) @@ -271,12 +273,12 @@ HFMainCamera (主相机) │ ├── CameraItem2 (Weight=20) │ └── CameraItem3 (Weight=5) │ - └── 按Weight排序 → 渲染顺序控制 + └── 按 Weight 排序 → 渲染顺序控制 ``` --- -## 四、General层架构 +## 四、General 层架构 ### 4.1 状态机系统 @@ -296,16 +298,16 @@ IGFStateMachineBehaviour (接口) #### 4.1.2 状态机特性 | 特性 | 说明 | -|-----|-----| +|-----|------| | **层级化设计** | 支持状态、层、机三个层级的行为绑定 | | **参数化驱动** | 通过参数控制状态切换 | -| **Inspector扩展** | 自定义编辑器支持 | +| **Inspector 扩展** | 自定义编辑器支持 | ### 4.2 工具类 #### 4.2.1 扩展方法集合 -**HFUGUIExtendEngine.cs** - UGUI扩展方法（40+方法） +**HFUGUIExtendEngine.cs** - UGUI 扩展方法（40+ 方法） | 功能分类 | 方法示例 | |---------|---------| @@ -318,9 +320,9 @@ IGFStateMachineBehaviour (接口) | 工具类 | 职责 | |-------|-----| -| `HFAssetBundleHelper` | AB包辅助工具 | -| `HFDllHelper` | DLL加载辅助 | -| `HFEnumForAssetBundle` | AB包相关枚举 | +| `HFAssetBundleHelper` | AB 包辅助工具 | +| `HFDllHelper` | DLL 加载辅助 | +| `HFEnumForAssetBundle` | AB 包相关枚举 | | `MinGameModel` | 微信小游戏适配 | --- @@ -332,46 +334,65 @@ IGFStateMachineBehaviour (接口) | 模式 | 应用场景 | 实现类 | |-----|---------|-------| | **单例模式** | 全局管理器 | `AbsHFSingleMonoBehaviour`, `AbsHFSingleRunTime` | -| **工厂模式** | 对象创建 | 对象池的GetItem | +| **工厂模式** | 对象创建 | 对象池的 GetItem | | **观察者模式** | 事件系统 | `IHFEventHandle` | | **策略模式** | 多平台适配 | `SFGlobalData.Platform()` | -| **模板方法** | 生命周期 | `SimulateBehaviour`系列 | +| **模板方法** | 生命周期 | `SimulateBehaviour` 系列 | ### 5.2 架构优势 | 优势 | 体现 | -|-----|-----| -| **解耦性** | 逻辑与MonoBehaviour分离 | +|-----|------| +| **解耦性** | 逻辑与 MonoBehaviour 分离 | | **可测试性** | 纯逻辑类易于单元测试 | -| **性能优化** | 对象池减少GC | +| **性能优化** | 对象池减少 GC | | **扩展性** | 接口驱动，易于扩展 | | **可维护性** | 清晰的模块划分 | ### 5.3 潜在改进点 | 改进方向 | 说明 | -|---------|-----| -| **异步加载优化** | 可引入协程池或Job System | +|---------|------| +| **异步加载优化** | 可引入协程池或 Job System | | **资源依赖可视化** | 可增加依赖关系图工具 | | **性能监控** | 可增加加载时间、内存占用统计 | -| **热更新支持** | 可考虑集成Lua或ILRuntime | +| **热更新支持** | 可考虑集成 Lua 或 ILRuntime | --- ## 六、总结 -StrayFog框架是一个结构清晰、设计完善的Unity游戏框架，核心特点包括： +StrayFog 框架是一个结构清晰、设计完善的 Unity 游戏框架，核心特点包括： -1. **模拟行为系统** - 实现了完整的MonoBehaviour生命周期解耦 +1. **模拟行为系统** - 实现了完整的 MonoBehaviour 生命周期解耦 2. **对象池机制** - 高效的内存管理策略 3. **事件驱动架构** - 灵活的事件分发系统 -4. **资源管理体系** - 完善的AssetBundle加载和依赖管理 +4. **资源管理体系** - 完善的 AssetBundle 加载和依赖管理 5. **模块化设计** - 清晰的分层和职责划分 -该框架适合中大型Unity项目使用，具备良好的扩展性和维护性。 +该框架适合中大型 Unity 项目使用，具备良好的扩展性和维护性。 --- **版本**: v1.0 **分析日期**: 2024年 -**适用项目**: OnlineGame \ No newline at end of file +**适用项目**: OnlineGame + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [通用框架入口](README.md) | 本文件是通用框架模块的子文档 | +| [架构说明](../../../rules/10-架构说明.md) | 高层架构规则与程序集边界 | +| [实体系统](../实体系统/README.md) | 实体系统架构在本文件中分析 | +| [对象池与运行时对象管理](../内存对象管理/README.md) | 对象池架构在本文件中分析 | +| [事件系统](../事件系统/README.md) | 事件系统架构在本文件中分析 | +| [资源管理](../资源管理/README.md) | 资源管理架构在本文件中分析 | +| [相机系统](../相机系统/README.md) | 相机系统架构在本文件中分析 | +| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 | +| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | 开发规则与框架架构互相引用 | +| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 | diff --git a/modules/模块文档模板.md b/modules/模块文档模板.md new file mode 100644 index 0000000..3856be7 --- /dev/null +++ b/modules/模块文档模板.md @@ -0,0 +1,84 @@ +# 模块名称 + +## 分类 + +- 项目功能 / 项目框架 / 编辑器工具 + +## 目的 + +TODO：一句话说明这个模块是做什么的，从玩家/产品/技术视角写。 + +## 主要路径 + +| 类型 | 路径 | 说明 | +|---|---|---| +| 逻辑代码 | `Assets/...` | TODO | +| UI 代码 | `Assets/...` | TODO | +| 资源 | `Assets/...` | TODO | +| 配置 | `XLSX_SRC/...` 或 `GoogleProtobufNetwork/...` | TODO | + +## 入口 + +- 运行入口：TODO +- 编辑器入口：TODO +- 资源入口：TODO + +## 数据流 + +```text +TODO：用箭头图描述关键流程 +``` + +## 关键类 / API + +| 类/方法 | 用途 | +|---|---| +| `ClassName` | TODO | + +## 依赖 + +- 依赖的框架模块：TODO +- 依赖的其他功能模块：TODO +- 依赖的第三方插件：TODO + +## 当前状态 + +- TODO + +## 变更记录 + +| 日期 | 变更内容 | 关联 spec/change | 影响范围 | +|---|---|---|---| +| YYYY-MM-DD | 简要描述 | `[]`（对应 `specs/openspec//业务参考总入口.md`） | 相关模块/文件 | + +## 文档关联 + +本模块发生变更时，以下文档必须同步更新： + +- [模块索引](模块索引.md) — 如果新增/删除模块，或模块分类/状态改变 +- [模块登记规则](../rules/30-模块登记规则.md) — 如果新增模块、分类口径或依赖关系变化 +- [架构说明](../rules/10-架构说明.md) — 如果涉及架构变化 +- TODO：链接相关功能/框架模块文档（如依赖方或被依赖方） +- TODO：链接相关 spec 目录（如 `../../specs/openspec//业务参考总入口.md`） + +> 注意：本模板位于 `modules/` 根目录。如果复制到 `modules/features/` 或 `modules/frameworks/` 下，请把 `../rules/` 和 `模块索引.md` 调整为 `../../rules/` 和 `../模块索引.md`。 + +## 下一步 + +- [ ] TODO + +## 相关文档 + +- [模块索引](模块索引.md) +- [模块登记规则](../rules/30-模块登记规则.md) +- [架构说明](../rules/10-架构说明.md) +- TODO：链接相关功能/框架模块文档 + +## 是否需要拆分文档 + +轻量模块可以只保留这个 README。 + +当模块出现独立计划、持续进度或多项待办时，再增加： + +- `progress.md` +- `tasks.md` \ No newline at end of file diff --git a/modules/模块索引.md b/modules/模块索引.md new file mode 100644 index 0000000..59ec5c5 --- /dev/null +++ b/modules/模块索引.md @@ -0,0 +1,85 @@ +# 模块索引 + +这里是 UnityAI / StrayFog 框架知识库的项目知识总入口。 + +模块清单、模块状态和模块入口以本文件为准；`rules/` 只维护规则和约束，不重复维护模块事实表。 + +--- + +## 重要口径 + +- **核心框架**：支撑游戏运行的内部系统，例如实体系统、UI 窗口系统、事件系统、资源管理、对象池、场景管理。 +- **编辑器工具**：Unity Editor 内使用的生成器、Inspector、菜单、配置工具。 +- **业务参考**：外部实际项目的业务实现示例，仅作参考，不作为框架规范。见 [business-reference](../business-reference/playballoons/业务参考总入口.md)。 + +轻量模块先在本文件登记；复杂模块再拆独立目录。 + +--- + +## 状态口径 + +见 [模块登记规则](../rules/30-模块登记规则.md#状态定义)。 + +不要使用“已开始”，优先使用“已识别 / 初步梳理 / 待验证 / 已完成 / 未发现实现”。 + +--- + +## 核心框架 + +| 框架模块 | 主要路径 | 当前判断 | 状态 | +|---|---|---|---| +| [模拟行为系统](frameworks/通用框架/README.md) | `Assets/StrayFog/Core/SimulateBehaviour/` | 解耦 MonoBehaviour，模拟完整生命周期 | 已完成 | +| [对象池](frameworks/内存对象管理/README.md) | `Assets/Game/GameHFScripte/CopyToHF/MemoryManager/` | GameObject 对象池、脚本对象池、类实例池 | 已完成 | +| [事件系统](frameworks/事件系统/README.md) | `Assets/Game/GameHFScripte/CopyToHF/Event/` | CTC/STC 事件参数和事件派发 | 已完成 | +| [资源管理](frameworks/资源管理/README.md) | `Assets/Game/GameHFScripte/CopyToHF/AssetBundle/` | AssetBundle、语言资源、图集、加载规则 | 已完成 | +| [相机系统](frameworks/相机系统/README.md) | `Assets/Game/GameHFScripte/CopyToHF/` | 多相机管理、相机堆栈、渲染顺序 | 初步梳理 | +| [实体系统](frameworks/实体系统/README.md) | `Assets/Game/GameHFScripte/GameFunction/GameEntity/` | 实体基类、模型/系统、实体池 | 已完成 | +| [UI 窗口系统](frameworks/UI窗口系统/README.md) | `Assets/Game/GameHFScripte/CopyToHF/UIWindowMgr/` | UI 窗口管理、窗口基类、生命周期 | 已完成 | +| [技能系统](frameworks/技能系统/README.md) | `Assets/Game/GameHFScripte/GameFunction/GameEntity/` | 技能触发器、释放器、配置联动 | 初步梳理 | +| [场景系统](frameworks/场景系统.md) | `Assets/Game/GameHFScripte/GameFunction/SceneManager/` | 场景加载、资源配置、生命周期 | 初步梳理 | +| [网络系统](frameworks/网络系统.md) | `Assets/Game/GameHFScripte/CopyToHF/Network/` | WebSocket、protobuf、消息映射 | 初步梳理 | +| [配置生成](frameworks/数据配置框架.md) | `XLSX_SRC/`、`Assets/AutoBuildScript/` | 表格配置源、解析、生成代码 | 初步梳理 | +| [Hotfix 启动](frameworks/Hotfix启动.md) | `Assets/Game/GameHFScripte/GameFunction/GameRoot/` | hotfix 侧根入口和功能目录聚合 | 初步梳理 | + +--- + +## 编辑器工具 + +| 工具模块 | 主要路径 | 当前判断 | 状态 | +|---|---|---|---| +| [SF Editor](frameworks/编辑器工具/README.md#sf-editor) | `Assets/StrayFog/Editor/` | StrayFog 编辑器扩展 | 待验证 | +| [项目 Editor Assets](frameworks/编辑器工具/README.md#project-editor-assets) | `Assets/Editor/` | 项目编辑器资源与脚本 | 待验证 | + +--- + +## 文档拆分规则 + +- 核心框架按技术职责命名，可以对应 `GameEntity`、`UIWindowMgr`、`Network`、`AssetBundle`、`Event` 这类内部系统。 +- 轻量模块只在本文件登记。 +- 复杂模块再拆 `modules//`。 +- `模块索引.md` 写稳定说明。 +- `progress.md` 写阶段状态。 +- `tasks.md` 写下一步待办。 +- 跨模块计划放到 [plans](../plans/)。 + +--- + +## 相关文档 + +- [项目规则入口](../rules/项目规则入口.md)：AI 工作方式、扫描范围、归档规则和规则索引。 +- [模块登记规则](../rules/30-模块登记规则.md)：分类口径、状态定义和新增模块登记规则。 +- [架构说明](../rules/10-架构说明.md)：总体分层、程序集边界和依赖方向。 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [rules/30-模块登记规则.md](../rules/30-模块登记规则.md) | 模块索引是模块登记规则的唯一事实来源 | +| [rules/10-架构说明.md](../rules/10-架构说明.md) | 模块分类、分层与架构说明互相影响 | +| [rules/项目规则入口.md](../rules/项目规则入口.md) | 模块索引是项目规则入口引用的项目知识总入口 | +| [ai/AI接入入口.md](../ai/AI接入入口.md) | AI 接入入口引用模块索引作为必读文档 | +| [modules/frameworks/*](frameworks/) | 框架模块文档新增/拆分时需同步索引 | diff --git a/rules/00-项目概览.md b/rules/00-项目概览.md new file mode 100644 index 0000000..c9af4df --- /dev/null +++ b/rules/00-项目概览.md @@ -0,0 +1,119 @@ +# 项目概览 + +> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。 + +## 摘要 + +`UnityAI` 是 **StrayFog 框架文档中心**，用于沉淀 StrayFog 框架的架构设计、核心功能使用规范、开发流程和项目管理规则。 + +本仓库本身不包含游戏业务代码，而是一个**面向 AI 工具与人工开发者的知识库**。AI 工具通过 ai/rules/modules/ 下的规则与模块文档快速理解框架；人工开发者可以通过 `modules/frameworks/` 下的框架模块文档和 `rules/` 下的规则文档学习使用。 + +- **项目名**：UnityAI +- **副标题**：StrayFog 框架文档中心 +- **目标读者**：AI 工具、业务开发人员、框架维护人员 +- **文档语言**：中文 +- **适用项目**：GiftGameX、OnlineGame 等使用 StrayFog 框架的项目 + +--- + +## 重要目录 + +| 目录 | 用途 | +|------|------| +| `modules/frameworks/` | 核心框架模块文档：实体、UI、事件、资源、对象池等。 | +| `rules/` | 项目长期规则：工作方式、扫描范围、任务流程、归档规则。 | +| `modules/` | 项目知识总入口：框架模块、核心功能、编辑器工具。 | +| `hooks/` | 共享 hook：归档检查、提交检查、文档关联同步。 | +| `specs/` | 大需求 / 新模块的 OpenSpec 归档。 | +| `modules/frameworks/编辑器工具/UI工具/` | UI 预制体 JSON 转换工具脚本。 | +| `business-reference/` | 外部实际项目业务参考，与框架核心分离。 | + +--- + +## 核心子系统 + +StrayFog 框架主要包含以下子系统： + +| 子系统 | 主要职责 | 对应文档 | +|--------|---------|---------| +| **模拟行为系统** | 解耦 MonoBehaviour，模拟完整生命周期 | [SimulateBehaviour](../modules/frameworks/通用框架/README.md) | +| **对象池系统** | GameObject 对象池、脚本对象池、类实例池 | [对象池](../modules/frameworks/内存对象管理/README.md) | +| **事件系统** | CTC/STC 事件派发、监听与释放 | [事件系统](../modules/frameworks/事件系统/README.md) | +| **资源管理系统** | AssetBundle 加载、依赖管理、语言包、图集 | [资源管理](../modules/frameworks/资源管理/README.md) | +| **相机管理系统** | 多相机管理、相机堆栈、渲染顺序 | [相机系统](../modules/frameworks/相机系统/README.md) | +| **实体系统** | 实体创建、System-Model 架构、实体池 | [实体系统](../modules/frameworks/实体系统/README.md) | +| **UI 窗口系统** | UI 窗口管理、层级、生命周期、事件释放 | [UI 窗口系统](../modules/frameworks/UI窗口系统/README.md) | +| **技能系统** | 技能触发器、释放器、配置联动 | [技能系统](../modules/frameworks/技能系统/README.md) | +| **场景系统** | 场景加载、资源配置、生命周期 | [场景系统](../modules/frameworks/场景系统.md) | +| **网络系统** | WebSocket、protobuf、消息映射（如项目使用） | [网络系统](../modules/frameworks/网络系统.md) | +| **配置生成系统** | XLSX / protobuf 配置生成（如项目使用） | [配置生成](../modules/frameworks/数据配置框架.md) | + +--- + +## 文档分层 + +```text +AI 接入层 + AGENTS.md / CLAUDE.md / RULES.md / ai/AI接入入口.md + | + v +项目规则层 + rules/项目规则入口.md + 00~70 规则文件 + | + v +项目知识层 + modules/模块索引.md + | + ├── 框架模块（frameworks/） + ├── 编辑器工具（editor-tools/） + └── 使用示例（examples/） + | + v +业务参考层 + business-reference/playballoons/ + | + v +Hook / Spec / Plan + hooks/ / specs/ / plans/ +``` + +--- + +## 使用方式 + +### AI 工具 + +1. 读取 `ai/AI接入入口.md` +2. 读取 `rules/项目规则入口.md` +3. 按任务范围读取 `modules/` 下具体模块文档 +4. 如需了解外部项目业务参考，读取 `business-reference/playballoons/业务框架映射接口.md` + +### 人工开发者 + +1. 新成员从 [开发规则](20-开发规则.md) 开始。 +2. 了解架构看 [架构说明](10-架构说明.md) 和 [通用框架/框架架构](../modules/frameworks/通用框架/框架架构.md)。 +3. 使用具体系统看 `modules/frameworks/` 下对应框架模块。 +4. 遇到问题看 [开发规则/常见问题](20-开发规则.md#常见问题)。 + +--- + +## 关键约束 + +- `ai/rules/modules/` 是 StrayFog 框架知识的唯一事实来源；旧中文教程内容已迁移合并至此。 +- 修改 `modules/` 中模块文档后，必须同步更新 `modules/模块索引.md` 和相关规则文件。 +- `business-reference/` 中的内容来自外部实际项目，仅作参考，不作为 StrayFog 框架规范。 +- 不要把项目规则复制进系统提示或 AI 工具私有目录。 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [rules/项目规则入口.md](项目规则入口.md) | 项目概览是项目规则入口引用的核心信息 | +| [rules/10-架构说明.md](10-架构说明.md) | 重要顶层目录与总体分层、程序集边界相关 | +| [rules/20-开发规则.md](20-开发规则.md) | 生成内容约束与开发规则互相引用 | +| [rules/70-项目设置.md](70-项目设置.md) | 扫描范围、跳过目录与项目概况中的目录说明相关 | +| [modules/模块索引.md](../modules/模块索引.md) | 模块索引是项目知识总入口 | diff --git a/rules/10-架构说明.md b/rules/10-架构说明.md new file mode 100644 index 0000000..63aa071 --- /dev/null +++ b/rules/10-架构说明.md @@ -0,0 +1,144 @@ +# 架构说明 + +> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。 + +项目文档按三类组织：**核心运行时**、**编辑器工具**、**业务参考**。详细模块索引见 [模块索引](../modules/模块索引.md)。 + +--- + +## 分类口径 + +- **核心运行时**：支撑游戏运行的内部系统，例如实体、UI、网络、资源、事件、场景、对象池。 +- **编辑器工具**：Unity Editor 内使用的生成器、Inspector、菜单、配置工具。 +- **业务参考**：外部实际项目的业务实现示例，仅作参考，不作为框架规范。 + +--- + +## 总体分层 + +```text +┌─────────────────────────────────────────────────────────────┐ +│ StrayFog Framework │ +├─────────────────────────────────────────────────────────────┤ +│ ┌──────────────────┐ ┌──────────────────┐ ┌───────────┐ │ +│ │ GameGeneral │ │ GameHF │ │ Core │ │ +│ │ 通用工具层 │ │ 业务核心层 │ │ 基础框架 │ │ +│ └────────┬─────────┘ └────────┬─────────┘ └─────┬─────┘ │ +├───────────┼─────────────────────┼──────────────────┼─────────┤ +│ │ │ │ │ +│ ▼ ▼ ▼ │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ Unity Engine │ │ +│ └─────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 各层职责 + +| 层级 | 路径 | 职责描述 | +|------|------|---------| +| **Core 层** | `Assets/StrayFog/Core` | 核心基础框架，模拟行为系统、全局数据管理 | +| **HF 层** | `Assets/Game/GameHFScripte/CopyToHF` | 游戏核心业务框架，资源管理、事件系统、相机管理、UI 管理等 | +| **General 层** | `Assets/Game/GameGeneralScripte` | 通用工具层，状态机、辅助工具、扩展方法等 | + +--- + +## 核心运行时层 + +核心运行时按技术职责命名，可以对应内部目录。 + +- **Hotfix 启动/目录**：`GameFunction/GameRoot/` +- **实体系统**：`GameFunction/GameEntity/`、`Logic/EntityData/` +- **UI 系统**：`CopyToHF/UIWindowMgr/`、`GameFunction/UIWindows/`、`GameMono/Scripts/UIMono/` +- **场景系统**：`GameFunction/SceneManager/`、`GameMono/Scenes/` +- **网络系统**：`CopyToHF/Network/`、`GameFunction/WebSocket/`、`GoogleProtobufNetwork/`（如项目使用） +- **资源系统**：`CopyToHF/AssetBundle/`、`CopyToHF/SpriteAtlas/`、`GameHFResource/` +- **事件系统**：`CopyToHF/Event/`、`GameFunction/Event/` +- **对象池**：`CopyToHF/MemoryManager/`、`GameFunction/GameEntity/EntityPool/` +- **通用框架**：`GameGeneralScripte/`、`StrayFog/Core/` + +--- + +## 编辑器工具层 + +- `Assets/StrayFog/Editor/`：StrayFog 编辑器扩展。 +- `Assets/Editor/`：项目编辑器资源与脚本。 +- `Assets/AutoBuildScript/Editor/`：编辑器生成工具（如项目使用）。 + +--- + +## 程序集边界 + +已识别 asmdef： + +| 程序集 | 主要路径 | 分类 | +|---|---|---| +| `StrayFogCore` | `Assets/StrayFog/Core/` | 核心运行时 | +| `SFEditor` | `Assets/StrayFog/Editor/` | 编辑器工具 | +| `GameHF` | `Assets/Game/GameHFScripte/` | 核心运行时 / hotfix 承载 | +| `GameGeneral` | `Assets/Game/GameGeneralScripte/` | 核心运行时 / general | +| `SFMono` | `Assets/Game/GameMono/` | 核心运行时 / Mono 桥接 | + +--- + +## 依赖方向 + +```text +业务功能（PVE、PVP、背包、商店等，放在外部业务参考层） + | + v +核心运行时（GameRoot、GameEntity、UIWindowMgr、SceneManager、Network、AssetBundle、Event 等） + | + v +通用框架 / 第三方插件（StrayFog Core、Spine、DOTween 等） + | + v +Unity Engine / .NET Runtime + +编辑器工具 -----------------> 读取/生成 核心运行时代码 +``` + +### 依赖规则 + +| 上层 | 可以依赖 | 禁止依赖 | +|---|---|---| +| 业务功能 | 核心运行时、通用框架 | 编辑器工具、第三方插件源码 | +| 核心运行时 | 通用框架、第三方插件 | 具体业务功能、编辑器工具 | +| 编辑器工具 | 核心运行时源码、生成模板 | 被运行时代码反向引用 | + +### 说明 + +- 运行时代码不要依赖 Editor 程序集。 +- 第三方插件不应反向依赖具体玩法模块。 +- 业务功能代码按业务命名，代码目录可以仍然按框架/实现组织。 + +--- + +## 文档与代码分层对应 + +| 文档层 | 对应代码层 | 示例 | +|--------|-----------|------| +| `modules/frameworks/` | 核心运行时 | 实体系统、UI 系统、事件系统等 | +| `modules/frameworks/通用框架/框架架构.md` | 核心运行时 + 规范 | StrayFog 整体架构分析 | +| `rules/` | 规范与流程 | 开发规则、工作流清单、架构说明 | + +--- + +## 待确认 + +- 各项目实际使用的 StrayFog 版本与目录可能略有差异，文档中路径以当前仓库描述的 `Assets/StrayFog/` 和 `Assets/Game/` 结构为准。 +- 网络系统、配置生成系统是否为所有使用 StrayFog 的项目标配，需按具体项目确认。 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/frameworks/通用框架/框架架构.md](../modules/frameworks/通用框架/框架架构.md) | 实现视角的框架架构分析 | +| [modules/模块索引.md](../modules/模块索引.md) | 模块索引是架构说明的落地入口，分类口径需一致 | +| [rules/30-模块登记规则.md](30-模块登记规则.md) | 模块登记口径、状态定义与架构分层互相影响 | +| [rules/20-开发规则.md](20-开发规则.md) | 程序集边界、依赖方向与开发规则互相引用 | +| [rules/项目规则入口.md](项目规则入口.md) | 架构说明是项目规则入口索引的关键规则 | diff --git a/rules/20-开发规则.md b/rules/20-开发规则.md new file mode 100644 index 0000000..46c9cbc --- /dev/null +++ b/rules/20-开发规则.md @@ -0,0 +1,269 @@ +# 开发规则 + +> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。 + +## 基本原则 + +- 优先遵循项目已有模式。 +- 修改范围保持在当前功能或模块内。 +- 不手动修改生成代码，除非生成器不可用且已记录原因。 +- 不直接修改 `Assets/ThirdPlugins/` 或 embedded package，除非必须且记录原因。 +- 正常分析项目时忽略 Unity/IDE 本地状态目录。 +- 运行时代码不引用 Editor 程序集。 +- **一处定义，多处引用**：如果一个事实出现在多个文档中，修改时必须同步所有地方。 + +--- + +## C# 规则 + +### 命名 + +- 类名、结构体、枚举、属性、方法使用 PascalCase。 +- 私有字段使用 `m_` + PascalCase，例如 `m_UserName`、`m_BagPage`。 +- 方法参数使用 `_` + camelCase，例如 `_username`、`_maxpage`。 +- 局部变量使用 camelCase。 +- 常量：同一文件内保持一致，优先使用全大写 + 下划线（如 `C_FRAME_ROOT_PATH`）或 PascalCase。 +- 抽象类优先加 `Abs` 前缀，例如 `AbsHFSingleMonoBehaviour`、`AbsHFAssetRequest`。 +- 单例管理器优先继承 `AbsHFSingleMonoBehaviour` 或 `AbsHFSingleRunTime`。 +- Hotfix 类名可优先加 `HF` 前缀，例如 `HFLoginManager`、`HFBagManager`。 +- 业务类型枚举可按用途加前缀，例如 `enItemType`、`enCurrencySubItemType`。 +- 事件枚举可按用途加前缀，例如 `enHFSTCEvent`、`enHFCTCEvent`。 + +### 代码组织 + +- 一个 `.cs` 文件原则上只放一个主要类型；小枚举可多个共存。 +- 类型可见性排序按项目已有风格；如无风格，按 public → protected → internal → private。 +- 公共 API 添加中文 XML 文档注释或行内注释，说明用途、参数、返回值。 +- 只在解释非显然意图时添加注释，不写无意义注释。 + +### 日志与异常 + +- 异常只用于异常情况，不用于正常流程控制。 +- 错误日志包含方法名和关键上下文，不包含敏感信息。 +- 写日志时保持附近文件风格；优先使用项目统一的日志封装（如有）。 + +### 其他 + +- 优先遵循附近文件风格。同一文件/同一目录下风格应保持一致。 +- 保持 public API 小而明确。 +- 避免超长方法和深层嵌套。 + +--- + +## 核心库访问规则 + +### 核心库范围 + +以下目录属于核心库，业务代码应只读访问，修改需走框架团队 Issue 流程： + +| 路径 | 说明 | +|------|------| +| `Assets/StrayFog/Core` | 基础框架核心 | +| `Assets/Game/GameHFScripte/CopyToHF` | 游戏核心业务框架 | +| `Assets/Game/GameGeneralScripte` | 通用工具层 | + +### 访问方式 + +业务代码必须通过 `HFFunCatalogue` 统一入口访问核心库： + +```csharp +// ✅ 正确：通过统一入口访问 +HFFunCatalogue.UIManager.OpenWindow(); +HFFunCatalogue.Asset.LoadAsset("path"); +HFFunCatalogue.Scene.LoadScene("MainScene"); + +// ❌ 禁止：直接访问核心库 +HFUIWindowMgr.Instance.OpenWindow(); // 禁止 +HFABMgr.Instance.LoadAsset("path"); // 禁止 +``` + +### 禁止操作 + +| 禁止行为 | 后果 | +|---------|------| +| 修改核心库源代码 | 破坏框架稳定性 | +| 删除/重命名核心库文件 | 编译错误 | +| 直接实例化核心库内部类 | 违反封装原则 | +| 绕过 `HFFunCatalogue` 直接调用核心库单例 | 难以维护和测试 | + +### 修改流程 + +1. 业务人员发现问题/需求 → 提交 Issue 到框架团队 +2. 框架团队评估需求 +3. 合理：开发修复 → 代码审查 → 发布新版本 → 业务团队更新引用 +4. 不合理：反馈拒绝 + +--- + +## 业务代码结构 + +### 目录组织 + +业务代码主要位于 `Assets/Game/GameHFScripte/GameFunction/`，按职责分目录： + +``` +Assets/Game/GameHFScripte/GameFunction/ +├── Event/ # 消息处理 +│ ├── ServerToClient/ # 服务器到客户端消息 +│ ├── ClientToClient/ # 客户端内部消息 +│ └── Handle/ # 消息处理器 +├── GameRoot/ # 框架调用入口 +├── Logic/ # 游戏主要业务逻辑（存放各功能 Manager） +├── UIWindows/ # UI 窗口业务逻辑 +├── GameEntity/ # 游戏实体 +├── SoundManagerPro/ # 音效管理 +├── SceneManager/ # 场景管理 +└── SDK/ # SDK 集成 +``` + +### 文件命名 + +| 文件类型 | 命名规则 | 示例 | +|---------|---------|-----| +| 窗口类 | `XXXWindow.cs` | `LoginWindow.cs` | +| 组件类 | `XXXComponent.cs` | `ItemCellComponent.cs` | +| 管理器类 | `XXXManager.cs` | `UIManager.cs` | +| 数据类 | `XXXData.cs` | `PlayerData.cs` | +| 配置类 | `XXXConfig.cs` | `SkillConfig.cs` | + +--- + +## 最佳实践 + +### 性能优化 + +- 频繁创建销毁的对象必须使用对象池。 +- 合理设置对象池初始容量。 +- 及时释放不再使用的资源。 +- 使用异步加载避免卡顿。 +- 合理使用资源缓存。 +- 将图标打包到 SpriteAtlas。 +- 滚动列表优先使用 `SFUI_ScrollRect.BindEvent`。 + +### 代码组织 + +- 每个类只负责一个功能，避免庞大的 God 类。 +- 通过管理器获取依赖，而非硬编码。 +- 使用接口解耦依赖关系。 +- 保持 public API 小而明确。 +- 避免超长方法和深层嵌套。 + +### 错误处理 + +- 异常只用于异常情况，不用于正常流程控制。 +- 在关键路径添加异常处理。 +- 记录错误日志便于排查，但不包含敏感信息。 +- 检查参数合法性，处理空引用情况。 + +--- + +## 常见问题 + +### 如何扩展核心库功能？ + +通过继承抽象类或实现接口来扩展，不要直接修改核心库代码。 + +### 核心库有 Bug 怎么办？ + +提交 Issue 到框架团队，由框架团队修复并发布新版本。 + +### 如何调试核心库代码？ + +可以设置断点调试，但不允许修改代码。 + +### 常用核心库 API + +| 类别 | 管理器 | 常用方法 | +|-----|-------|---------| +| 对象池 | `HFObjectMemPool` | `GetItem()`, `GiveBack()` | +| 事件 | `IHFEventHandle` | `AddListener()`, `Dispatch()` | +| 资源 | `HFABMgr` | `OnStartLoad()` | +| 相机 | `HFCameraManager` | `AddCamera()`, `GetCamera()` | + +--- + +## Unity 资源规则 + +### Prefab + +- Prefab 修改保持聚焦，避免无意义的大范围 reserialize。 +- UI Prefab 命名与窗口/面板对应，例如 `Login.prefab`、`ItemWindow.prefab`。 +- 通用 UI 组件/Item 使用 `Item` 后缀，例如 `AvatarItem.prefab`、`ResourceItem.prefab`。 +- 记录无法从代码复现的手动 Unity Editor 操作。 + +### Scene + +- 场景按用途命名，例如 `LoginScene`、`BattleScene`。 +- 不要直接在场景里堆放运行时动态加载的资源。 + +### Sprite Atlas + +- 按业务或 UI 模块划分图集，例如 `SpriteAtlasAssets/Shop`、`SpriteAtlasAssets/Login`。 +- 图集内图片按功能子目录组织，避免单张图集过大。 + +### Material / Shader + +- 优先使用项目已有 Shader，不随意引入新 Shader。 +- Material 实例在运行时通过代码创建，避免直接修改共享 Material。 + +### Audio + +- 音效、背景音乐分目录存放。 +- 短音效优先使用 AudioClip + AudioSource 池，长音乐注意卸载。 + +### 本地化资源 + +- 资源按语言分目录，例如 `GameHFResource/CN/`、`GameHFResource/EN/`。 +- 多语言共用资源放在不带语言后缀的公共目录。 + +--- + +## 配置和数据规则 + +- 优先修改源表、proto 或 schema，而不是生成输出。 +- 数据/schema 修改后，按项目流程重新生成。 +- 缺失的生成步骤记录到 [工作流清单](40-工作流清单.md) 或对应模块文档。 +- 详细规则见 [数据/配置框架](../modules/frameworks/数据配置框架.md)。 + +--- + +## 网络和 Protobuf 规则 + +- `.proto` 是消息结构源头。 +- schema 修改后重新生成 C# 输出。 +- route/message-id 映射变化要和 schema 变化一起记录。 +- 详细规则见 [网络框架](../modules/frameworks/网络系统.md)。 + +--- + +## UI 框架规则 + +UI 窗口、Prefab、层级、生命周期、事件释放和 UIMono 绑定规则见 [UI 框架](../modules/frameworks/UI窗口系统/README.md)。 + +--- + +## 文档编写规则 + +- 每个 `.md` 文件末尾必须包含 **文档关联** 表。 +- 模块文档变更必须同步更新 [模块索引](../modules/模块索引.md)。 +- 不要在多个文档中重复维护同一份事实表。 +- 使用相对路径链接，确保在 GitHub / IDE / AI 工具中均可点击。 +- 代码示例必须可编译（或明确标注为伪代码）。 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [rules/项目规则入口.md](项目规则入口.md) | 开发规则是项目规则入口索引的关键规则 | +| [rules/10-架构说明.md](10-架构说明.md) | 程序集边界、依赖方向与 C# / Unity 规则互相引用 | +| [modules/模块索引.md](../modules/模块索引.md) | 模块索引中的框架模块文档是开发规则的具体落地 | +| [UI 框架](../modules/frameworks/UI窗口系统/README.md) | UI 命名、Prefab、层级等规则的具体说明 | +| [网络框架](../modules/frameworks/网络系统.md) | 网络、Protobuf 规则的具体说明 | +| [数据/配置框架](../modules/frameworks/数据配置框架.md) | 配置表、生成输出规则的具体说明 | +| [实体系统](../modules/frameworks/实体系统/README.md) | Entity 编码规范与核心库访问规则落地 | +| [通用框架](../modules/frameworks/通用框架/README.md) | 核心库范围与通用层规则落地 | +| [对象池与运行时对象管理](../modules/frameworks/内存对象管理/README.md) | 对象池最佳实践落地 | diff --git a/rules/30-模块登记规则.md b/rules/30-模块登记规则.md new file mode 100644 index 0000000..b9f62df --- /dev/null +++ b/rules/30-模块登记规则.md @@ -0,0 +1,81 @@ +# 模块登记规则 + +> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。 + +这里定义模块登记口径、状态含义和拆分规则。项目模块总入口统一维护在 [模块索引](../modules/模块索引.md)，本文件不重复维护模块清单。 + +--- + +## 口径 + +- **核心框架**：支撑游戏运行的内部系统，例如实体系统、UI 窗口系统、事件系统、资源管理、对象池、场景管理、网络、配置生成。 +- **编辑器工具**：Unity Editor 内使用的生成器、Inspector、菜单、配置工具。 +- **业务参考**：外部实际项目的业务实现示例，仅作参考，不作为框架规范。 + +--- + +## 唯一事实来源 + +模块清单、模块状态和模块入口统一维护在： + +```text +modules/模块索引.md +``` + +其他规则文档只链接到模块索引或具体模块文档，不再复制模块表。 + +--- + +## 状态定义 + +- **未识别**：还没有稳定线索。 +- **已识别**：已发现目录、类、资源或协议线索，但未完成梳理。 +- **初步梳理**：已写入核心路径、职责、数据流或使用规则，仍可能有待确认项。 +- **待验证**：文档已有结论，但需要通过 Unity、运行时、生成器或日志验证。 +- **已完成**：文档和验证都闭环，后续只需随代码演进维护。 +- **未发现实现**：按关键词和目录扫描后暂未发现实现，可作为规划占位。 + +避免使用“已开始”作为状态；它不能说明到底是只建了文件，还是已经完成了一轮梳理。 + +--- + +## 登记规则 + +- 新增核心框架模块时，登记到 [模块索引](../modules/模块索引.md) 的“核心框架”。 +- 新增编辑器工具时，登记到 [模块索引](../modules/模块索引.md) 的“编辑器工具”。 +- 新增业务参考时，登记到 `business-reference/` 下对应项目目录，不进入主模块索引。 +- 框架内部规则优先写进对应框架模块文档，例如 UI 写入 [UI 框架](../modules/frameworks/UI窗口系统/README.md)。 +- 模块开始有独立设计、进度、任务时，再拆 `modules//`。 +- 新增或拆分模块后，同步检查 [架构说明](10-架构说明.md) 和相关模块文档。 + +--- + +## 文档关系 + +- `modules/模块索引.md`：项目模块总入口和事实表。 +- `modules/frameworks/*`：核心框架职责和框架使用规则。复杂模块拆分为文件夹，入口为 `README.md`。 +- `modules//业务参考总入口.md`：复杂模块稳定说明。 +- `modules//progress.md`：复杂模块阶段进度。 +- `modules//tasks.md`：复杂模块待办事项。 +- `rules/`：跨模块的通用规则、工作流、扫描范围和归档规则。 +- `business-reference/`：外部项目业务参考，不进入主索引。 + +--- + +## 相关文档 + +- [模块索引](../modules/模块索引.md)：按分类整理的模块详细索引。 +- [架构说明](10-架构说明.md)：总体分层、程序集边界和依赖方向。 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [modules/模块索引.md](../modules/模块索引.md) | 模块索引是模块登记规则的唯一事实来源 | +| [rules/10-架构说明.md](10-架构说明.md) | 分类口径、依赖方向与架构说明互相影响 | +| [rules/项目规则入口.md](项目规则入口.md) | 模块登记规则是项目规则入口索引的关键规则 | +| [modules/frameworks/*.md](../modules/frameworks/) | 框架模块的状态、拆分规则需与登记规则一致 | diff --git a/rules/40-工作流清单.md b/rules/40-工作流清单.md new file mode 100644 index 0000000..c86fe1a --- /dev/null +++ b/rules/40-工作流清单.md @@ -0,0 +1,206 @@ +# 工作流清单 + +> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。 + +--- + +## 任务分类 + +| 类型 | 特征 | 处理方式 | +|---|---|---| +| **简单修复** | 查询、解释、小范围修改、影响面低、用户已给出明确方式 | 直接处理，完成后验证并归档检查 | +| **旧模块修复** | 已有框架模块的 bug 修复、逻辑补全、局部优化 | 读取模块文档，分析影响范围后修复，验证并归档 | +| **Spec 任务** | 新增框架模块、调整架构/目录/依赖、批量修改迁移 | 走 OpenSpec 流程 | + +--- + +## 简单修复流程 + +1. 确认任务范围。 +2. 读取相关模块文档。 +3. 直接修改。 +4. 验证（如可运行测试、检查链接、预览 Markdown）。 +5. 执行归档检查。 +6. 简短说明结果。 + +--- + +## 旧模块修复流程 + +1. 定位已有模块文档和相关内容。 +2. 简短分析影响范围和风险。 +3. 直接修复。 +4. 验证。 +5. 按 [50-归档规则.md](50-归档规则.md) 同步相关模块文档。 + +--- + +## Spec 任务流程 + +大需求 / 新模块统一走 OpenSpec： + +1. 分析目标、影响范围、风险和依赖。 +2. 给出 2-3 个方案。 +3. 用户确认后创建 OpenSpec change。 +4. 生成 `proposal.md`、`design.md`、`tasks.md`。 +5. 实现。 +6. 验证。 +7. 归档并同步文档。 + +详见 [60-新特性工作流.md](60-新特性工作流.md)。 + +--- + +## 开发流程 + +### 1. 文档学习 + +根据任务类型阅读对应模块文档： + +| 任务类型 | 必读文档 | +|---------|---------| +| UI 开发 | [UI 窗口系统](../modules/frameworks/UI窗口系统/README.md) | +| UI 界面设计 | [UI 界面拼接设计指南](../modules/frameworks/UI窗口系统/界面拼接.md) | +| 相机控制 | [相机系统](../modules/frameworks/相机系统/README.md) | +| 实体开发 | [实体系统](../modules/frameworks/实体系统/README.md) | +| 事件使用 | [事件系统](../modules/frameworks/事件系统/README.md) | +| 资源加载 | [资源管理](../modules/frameworks/资源管理/README.md) | + +### 2. 需求分析 + +1. 明确需求：理解业务需求，确定需要实现的功能。 +2. 评估复杂度：判断是否需要核心库支持或扩展。 +3. 设计方案：规划代码结构和调用关系。 + +### 3. 代码编写 + +1. 在 `GameFunction/` 下按职责创建模块目录。 +2. 遵循编码规范，使用核心库提供的 API。 +3. 在 Unity 中测试功能正确性。 + +### 4. 代码审查 + +1. 自我检查：检查是否符合规范，是否有潜在问题。 +2. 团队审查：提交代码进行团队审查。 +3. 修复问题：根据审查意见修改代码。 + +### 5. 集成测试 + +1. 模块测试：测试单个模块功能。 +2. 集成测试：测试模块间交互。 +3. 回归测试：确保不影响现有功能。 + +--- + +## 文档变更联动检查 + +修改任何文档前，确认它是否被其他文档引用： + +- 模块文档变更 → 同步检查模块索引、模块登记规则、架构说明。 +- 架构/目录变更 → 同步检查模块索引、相关模块 README、架构说明。 +- 规则文件变更 → 同步检查 `rules/项目规则入口.md`、`ai/AI接入入口.md`、`AGENTS.md`、`CLAUDE.md`、`RULES.md`。 +- spec/change 完成 → 同步更新相关模块 progress.md，并建立 `specs/openspec/` 归档。 + +--- + +## 提交前检查 + +### 提交信息格式 + +推荐格式： + +```text +[模块][类型]: 简短描述 + +- 详细说明 1 +- 详细说明 2 +``` + +类型：`feat`、`fix`、`docs`、`refactor`、`test`、`chore`。 + +模块名示例：`framework`、`entity`、`ui`、`event`、`resource`、`docs`、`rules`、`hooks`。 + +示例： + +```text +[entity][docs]: 补充实体池索引机制说明 + +- 添加 onlyid -> entity 映射说明 +- 补充 HFBasicPool/HFEnemyPool/HFHumanityPool 边界 +``` + +> **历史格式说明**：早期文档使用 `【操作原因】具体操作内容`（如 `【修复】xxx`）。该格式已弃用，新提交统一使用 `[module][type]: description`。 + +### 分支管理 + +| 分支名称 | 用途 | +|----------|------| +| `master` | 主分支，稳定版本 | +| `develop` | 开发分支，日常开发 | +| `feature/*` | 功能分支，开发新功能 | +| `bugfix/*` | Bug 修复分支 | + +### Git 操作原则 + +- 执行 Git 操作前确认当前操作路径是否正确。 +- 遵循项目既定的分支策略。 +- 使用语义化提交信息，清晰描述更改内容。 +- 重要功能提交前建议先创建分支进行测试。 +- 开发完成后及时推送到远程仓库。 + +### 提交前检查项 + +- [ ] 文档链接可点击且指向正确。 +- [ ] 文档关联表已更新。 +- [ ] 模块索引已同步（如新增/拆分了模块）。 +- [ ] 无拼写或明显格式错误。 +- [ ] 未引入外部项目专属内容。 +- [ ] 业务参考内容只出现在 `business-reference/` 下。 + +--- + +## 新增内容流程 + +### 新增框架模块 + +1. 在 [模块索引](../modules/模块索引.md) 中登记。 +2. 创建 `modules/frameworks/.md`；复杂模块可拆分为 `modules/frameworks//README.md` 加子文档。 +3. 在 [架构说明](10-架构说明.md) 中补充依赖方向。 +4. 更新相关模块的文档关联表。 + +### 新增编辑器工具 + +1. 在 [模块索引](../modules/模块索引.md) 中登记。 +2. 创建 `modules/editor-tools/.md` 或补充汇总文档。 +3. 说明使用入口、生成输出、依赖项。 + +### 新增业务参考 + +1. 放入 `business-reference//`。 +2. 不进入 `modules/模块索引.md` 主索引。 +3. 在 `business-reference//业务框架映射接口.md` 中补充映射关系。 + +--- + +## 生成/构建流程 + +若项目使用 StrayFog 框架配套的生成工具： + +- 优先修改源表、proto 或 schema，而不是生成输出。 +- 生成后检查输出目录，确认变更符合预期。 +- 缺失的生成步骤记录到对应模块文档。 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [rules/项目规则入口.md](项目规则入口.md) | 工作流清单是项目规则入口索引的关键规则 | +| [rules/50-归档规则.md](50-归档规则.md) | 归档规则与工作流清单互相引用 | +| [rules/60-新特性工作流.md](60-新特性工作流.md) | 新特性工作流是工作流清单的延伸 | +| [rules/20-开发规则.md](20-开发规则.md) | 提交格式与开发规则互相引用 | +| [modules/模块索引.md](../modules/模块索引.md) | 新增模块登记需同步模块索引 | +| [hooks/commit-check.ps1](../hooks/commit-check.ps1) | 提交检查脚本需与本文件格式一致 | diff --git a/rules/50-归档规则.md b/rules/50-归档规则.md new file mode 100644 index 0000000..1c42939 --- /dev/null +++ b/rules/50-归档规则.md @@ -0,0 +1,79 @@ +# 归档规则 + +> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。 + +“归档”是指任务完成后，通过归档 hook / 归档检查判断是否需要把本次任务产生的长期信息同步回项目文档。 + +归档 hook / 归档检查每个任务都要执行；归档不是写流水账，也不是每次都改所有文档。只更新和本次任务相关的文档。 + +## 什么时候必须更新文档 + +- 新增模块、拆分模块、调整模块职责。 +- 修改架构、目录结构、依赖方向。 +- 新增或改变生成流程。 +- 完成一个 spec、计划、功能阶段或里程碑。 +- 修改提交、构建、验证、发布规则。 +- 用户明确要求记录进度。 +- 旧模块修复改变了模块状态、关键流程、后续任务或长期约定。 + +## 简单修复如何归档 + +简单修复也必须执行归档 hook / 归档检查。 + +如果只是查询、解释、无长期影响的小修，可以不改文档，但最终回复中应说明没有长期文档需要更新。 + +如果简单修复改变了长期规则、模块状态或后续任务，需要补充对应文档。 + +## 归档内容 + +按需更新，并保持文档之间的关联关系一致： + +| 文档 | 更新时机 | 必须同步更新的关联文档 | +|---|---|---| +| `specs/` 或 `specs/openspec//` | 每个 Spec 任务完成后 | 相关模块 README/progress/tasks、架构说明、模块索引 | +| `modules//业务参考总入口.md` | 模块职责/入口/结构变化时 | 模块索引、模块登记规则、架构说明、相关功能/框架模块文档 | +| `modules//progress.md` | 阶段状态变化时 | 同一模块的 README、tasks、相关 spec | +| `modules//tasks.md` | 下一步任务变化时 | 同一模块的 progress、plans（如涉及跨模块计划） | +| `rules/10-架构说明.md` | 架构/目录/依赖方向变化时 | 模块索引、相关模块 README | +| `rules/30-模块登记规则.md` | 新增/拆分/调整模块时 | 架构说明、模块索引、相关模块 README | +| `rules/项目规则入口.md` | 项目规则入口内容变化时 | `ai/AI接入入口.md`、相关规则文件、`AGENTS.md`/`CLAUDE.md`/`RULES.md` | +| `RULES.md` | 仅当重定向目标变化时 | 无需单独维护内容，保持指向 `rules/项目规则入口.md` | + +### 关联更新原则 + +- **一处定义，多处引用**：如果一个事实出现在多个文档中，修改时必须同步所有地方。 +- **新增模块必须登记**：新增或拆分模块后，必须更新 `modules/模块索引.md`；如分类、状态定义或登记口径变化，再更新 `rules/30-模块登记规则.md`。 +- **已有模块变更必须留痕**：修改某个模块的入口、数据流或关键类时，同步更新该模块的 progress.md，并在相关 spec/change 中记录。 +- **避免孤儿文档**：不要创建没有从索引/注册表链接过去的模块或 spec 文档。 + +## 归档格式 + +建议每次记录： + +- 日期。 +- 本次目标。 +- 影响范围。 +- 已完成。 +- 未完成/TODO。 +- 验证情况。 +- 相关代码或文档链接。 + +## 归档前检查 + +- 不把临时讨论写成长久事实。 +- 不把所有模块细节写进总入口。 +- 不重复记录已经能从代码直接看出的内容。 +- 不记录密钥、账号、机器私有路径。 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [rules/项目规则入口.md](项目规则入口.md) | 归档规则是项目规则入口索引的关键规则 | +| [rules/40-工作流清单.md](40-工作流清单.md) | 任务分类、提交前检查与归档触发互相引用 | +| [rules/60-新特性工作流.md](60-新特性工作流.md) | OpenSpec 归档流程与本文件归档规则互相引用 | +| [specs/openspec/OpenSpec归档.md](../specs/openspec/OpenSpec归档.md) | OpenSpec 归档说明与本文件归档规则互相引用 | \ No newline at end of file diff --git a/rules/60-新特性工作流.md b/rules/60-新特性工作流.md new file mode 100644 index 0000000..4406b44 --- /dev/null +++ b/rules/60-新特性工作流.md @@ -0,0 +1,138 @@ +# 大需求 / 新模块工作流 + +> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。 + +--- + +## 总体流程 + +```text +判断任务类型 + | + ├── 简单修复 ────────────────→ 直接处理 → 归档检查 + | + ├── 旧模块修复 ──────────────→ 分析后修复 → 归档检查 + | + └── Spec 任务 ───────────────→ OpenSpec 流程 + | + v + 新模块 / 已有模块大改 + | + v + 实现 → 验证 → archive → 同步文档 +``` + +--- + +## 三种任务类型判定 + +| 类型 | 判定标准 | +|---|---| +| **简单修复** | 查询、解释、小范围修改、用户已给出明确实现方式 | +| **旧模块修复** | 已有框架模块的局部修复，不新增模块、不调整架构 | +| **Spec 任务** | 新增框架模块、调整架构/目录/依赖、批量迁移、用户未明确方案 | + +--- + +## 创建 OpenSpec Change + +当任务被判定为 Spec 任务时： + +1. 分析目标、影响范围、风险和依赖。 +2. 给出 2-3 个方案，让用户选择。 +3. 用户确认后创建 OpenSpec change： + - Claude Code：`/opsx:propose "需求描述"` + - CLI 通用：`openspec new change "change-name"` +4. 生成 `proposal.md`、`design.md`、`tasks.md`。 + +--- + +## 新模块操作清单 + +适用于在 StrayFog 框架知识库中新增一个框架模块，例如： + +- 新增“相机系统”模块文档 +- 新增“配置生成”模块文档 +- 新增“网络系统”模块文档 + +操作步骤： + +1. 在 [模块索引](../modules/模块索引.md) 中登记模块。 +2. 创建模块文档 `modules/frameworks/.md`（简单模块）或 `modules/frameworks//业务参考总入口.md`（复杂模块）。 +3. 如为复杂模块，创建 `progress.md` 和 `tasks.md`。 +4. 在 [架构说明](../rules/10-架构说明.md) 中补充该模块的分层位置和依赖方向。 +5. 更新相关模块的文档关联表。 +6. 如新增模块影响开发规则，更新 [开发规则](../rules/20-开发规则.md)。 +7. 按 design/tasks 完成内容编写。 +8. 验证文档链接、格式、关联表完整性。 +9. 归档 OpenSpec change。 +10. 同步更新模块索引、架构说明、相关模块文档。 + +--- + +## 已有模块大改操作清单 + +适用于对已有框架模块进行较大调整，例如： + +- 重构实体系统文档结构 +- 调整 UI 窗口系统的生命周期描述 +- 合并/拆分对象池相关文档 + +操作步骤： + +1. 读取现有模块文档和模块索引。 +2. 在 OpenSpec `design.md` 中说明变更原因、影响范围、新结构。 +3. 更新模块 `模块索引.md`。 +4. 更新模块 `progress.md`，记录本次变更。 +5. 更新模块 `tasks.md`，记录后续待办。 +6. 同步更新 [模块索引](../modules/模块索引.md)。 +7. 如影响架构或依赖方向，更新 [架构说明](../rules/10-架构说明.md)。 +8. 验证文档关联表一致性。 +9. 归档 OpenSpec change。 + +--- + +## 实现与验证 + +- 按 `tasks.md` 逐项完成。 +- 每完成一项，在 `tasks.md` 中标记。 +- 验证方式包括： + - Markdown 链接检查 + - 文档关联表完整性检查 + - 人工阅读关键章节 + - 运行 `hooks/archive-check.ps1` 检查关联文档 + +--- + +## 归档与联动更新 + +归档 OpenSpec change 后，必须同步更新： + +- `specs/openspec//` +- 相关模块 `模块索引.md`、`progress.md`、`tasks.md` +- `rules/10-架构说明.md`（如涉及架构变化） +- `modules/模块索引.md`（如新增模块） +- `rules/30-模块登记规则.md`（如改变模块分类、状态定义或登记规则） + +--- + +## 禁止事项 + +- 不要在没有 OpenSpec 的情况下进行大模块新增或架构调整。 +- 不要把临时讨论写进长期文档。 +- 不要创建没有从模块索引链接过去的孤儿文档。 +- 不要把外部项目专属内容混入框架核心文档。 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [rules/项目规则入口.md](项目规则入口.md) | 新特性工作流是项目规则入口索引的关键规则 | +| [rules/40-工作流清单.md](40-工作流清单.md) | 工作流清单与新特性工作流互相引用 | +| [rules/50-归档规则.md](50-归档规则.md) | 归档规则与新特性工作流互相引用 | +| [specs/openspec/OpenSpec归档.md](../specs/openspec/OpenSpec归档.md) | OpenSpec 归档说明与新特性工作流互相引用 | +| [modules/模块索引.md](../modules/模块索引.md) | 新增/拆分模块需同步模块索引 | diff --git a/rules/70-项目设置.md b/rules/70-项目设置.md new file mode 100644 index 0000000..ce54de9 --- /dev/null +++ b/rules/70-项目设置.md @@ -0,0 +1,82 @@ +# AI 工具扫描范围 + +> 本文件定义 AI 工具在正常分析项目时应跳过的目录和文件，以节省 token 并避免误读本地缓存/生成噪音。 +> +> Codex 和 Claude Code 均遵循此规则。 +> +> 返回主规则索引：[rules/项目规则入口.md](项目规则入口.md) + +--- + +## 通用跳过模式 + +| 模式 | 原因 | +|------|------| +| `.git/` | Git 版本控制元数据 | +| `.vs/` | Visual Studio 本地缓存 | +| `obj/` | .NET 编译中间输出目录 | +| `bin/` | .NET 编译输出目录 | +| `node_modules/` | Node.js 依赖目录 | +| `*.log` | 运行时日志 | +| `*.tmp` / `*.temp` | 临时文件 | +| `Thumbs.db` / `.DS_Store` | 系统缩略图/缓存 | + +## Unity 项目跳过模式 + +由于 StrayFog 是 Unity 框架，若知识库关联 Unity 工程，AI 分析时还应跳过： + +| 模式 | 原因 | +|------|------| +| `Library/` | Unity 本地缓存（资源导入、编译缓存、包缓存等），非项目源码 | +| `Temp/` | Unity 运行时临时文件 | +| `Logs/` | Unity 运行时日志 | +| `UserSettings/` | Unity 用户本地偏好设置 | +| `*.csproj` | 由 Unity 自动生成的项目文件 | +| `*.sln` | 由 Unity 自动生成的解决方案文件 | +| `Library/PackageCache/` | Unity Package Manager 缓存的第三方包源码 | +| `HybridCLRData/` | HybridCLR 构建生成输出（DLL、桥接文件等） | + +## AI 工具本地状态 + +| 模式 | 原因 | +|------|------| +| `.codex/` | Codex 本地 hooks 状态 | +| `.claude/` | Claude Code 本地命令/技能状态（除 `config` 外） | + +## 文档仓库跳过模式 + +本仓库本身以 Markdown 文档为主，以下文件通常无需 AI 全文读取： + +| 模式 | 原因 | +|------|------| +| 图片、音频、视频等二进制资源 | 非文本内容 | +| `.claude/` 中的本地 skill/hook 状态 | 工具私有状态 | +| `__pycache__/` | Python 缓存 | + +## 例外情况 + +当任务明确要求分析**构建问题**或**生成流程问题**时，可以按需读取以下目录中的特定文件： + +- `HybridCLRData/` — 检查 HybridCLR 构建输出、DLL 生成结果或 AOT 桥接错误 +- `Library/PackageCache/` — 检查特定包的版本或源码（仅限调试包相关问题时） +- `*.csproj` / `*.sln` — 检查项目引用或编译配置问题 + +> 例外读取后，应在分析结论中说明读取了哪些缓存/生成文件以及原因。 + +## 相关规则 + +- [rules/项目规则入口.md](项目规则入口.md) — 项目规则总索引 +- [00-项目概览.md](00-项目概览.md) — 项目概览与重要目录说明 +- [20-开发规则.md](20-开发规则.md) — 开发规则（含生成文件约束） + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [rules/项目规则入口.md](项目规则入口.md) | 项目设置是项目规则入口索引的关键规则 | +| [rules/00-项目概览.md](00-项目概览.md) | 扫描范围中的目录说明与项目概览互相引用 | +| [rules/20-开发规则.md](20-开发规则.md) | 生成文件约束、例外读取与扫描范围互相引用 | diff --git a/rules/项目规则入口.md b/rules/项目规则入口.md new file mode 100644 index 0000000..5f939ac --- /dev/null +++ b/rules/项目规则入口.md @@ -0,0 +1,252 @@ +# UnityAI - 项目规则入口 + +> 本文件是 UnityAI / StrayFog 框架知识库的 **项目规则入口**。 +> +> 所有 AI / IDE 工具先通过 [ai/AI接入入口.md](../ai/AI接入入口.md) 接入项目，再按任务范围读取本文件和下方链接的具体文档。 +> +> 不要把项目规则重复写在你的系统提示里；直接引用本文件和 `rules/` 下的规则文件。 + +--- + +## AI 快速启动 + +1. 确认已读取 [AI 工具接入入口](../ai/AI接入入口.md)。 +2. **读取本文件**（`rules/项目规则入口.md`）。 +3. 根据任务范围，从下方的 **规则索引**、**项目知识入口**、**Spec 索引** 中选择相关文档读取。 +4. **简单修复**：直接开始处理，完成后简短说明结果。 +5. **旧模块修复**：定位已有模块文档和相关内容，简短分析后直接修复。 +6. **大需求 / 新模块**：新增框架模块、架构调整、文档重组等，先给出 2-3 个方案，用户确认后走 **OpenSpec 流程**。 +7. **所有任务结束都执行归档 hook / 归档检查**，按影响范围决定是否更新长期文档。 + +--- + +## 项目概况 + +- **项目名**：UnityAI +- **副标题**：StrayFog 框架文档中心 +- **目标读者**：使用 StrayFog 框架的 AI 工具、业务开发人员、框架维护人员 +- **核心内容**：StrayFog 框架架构说明、核心功能使用指南、开发规范、开发流程、项目管理规范 +- **仓库结构**： + - `ai/` / `rules/` / `modules/` / `hooks/`：AI 规则与项目知识库（AI 优先读取） + - `modules/frameworks/`：核心框架模块文档（按模块拆分为文件夹） + - `business-reference/`：外部实际项目业务参考（与框架核心分离） +- **技术栈**：Unity、C#、StrayFog 框架 +- **文档语言**：中文 + +--- + +## 语言与工作方式 + +- **默认使用中文回答用户**。 +- **代码、类名、方法名、路径、命令、API 名称保持英文原文**。 +- 简单修复直接处理，简短说明结果。 +- 旧模块修复先定位已有模块文档和相关内容，简短分析风险后直接修复。 +- 大需求 / 新模块先分析目标、影响范围、风险和依赖，给出 2-3 个方案，用户确认后走 OpenSpec。 +- 如果用户明确说“直接实现”“按你判断来”，采用保守方案继续执行。 +- 所有任务结束都执行归档 hook / 归档检查；不把无长期价值的流水账写入文档。 + +--- + +## 规则索引 + +`rules/` 下的文件是项目长期规则，按以下顺序按需读取： + +| 文件 | 用途 | +|---|---| +| [00-项目概览.md](00-项目概览.md) | 项目用途、文档结构、核心子系统 | +| [10-架构说明.md](10-架构说明.md) | 框架结构、目录职责、依赖方向、程序集边界 | +| [20-开发规则.md](20-开发规则.md) | C# 规范、Unity 资源规则、文档编写规则 | +| [30-模块登记规则.md](30-模块登记规则.md) | 模块登记口径、状态定义、文档拆分规则 | +| [40-工作流清单.md](40-工作流清单.md) | 任务分类、修复流程、Spec 流程、提交前检查 | +| [50-归档规则.md](50-归档规则.md) | 归档时机、归档内容、关联更新原则 | +| [60-新特性工作流.md](60-新特性工作流.md) | 大需求 / 新模块如何通过 OpenSpec 流程推进 | +| [70-项目设置.md](70-项目设置.md) | AI 工具扫描范围、跳过目录、例外情况 | + +--- + +## 项目知识入口 + +项目框架、核心功能、编辑器工具的总入口统一维护在 [modules/模块索引.md](../modules/模块索引.md)。 + +规则文件不重复维护模块清单；新增、拆分、改名模块时，以 `modules/模块索引.md` 为唯一事实来源，并按 [30-模块登记规则.md](30-模块登记规则.md) 的口径登记。 + +常用框架规则入口： + +- [实体系统](../modules/frameworks/实体系统/README.md)：实体基类、System-Model 架构、实体池、生命周期。 +- [UI 窗口系统](../modules/frameworks/UI窗口系统/README.md)：UIWindow、Prefab、层级、生命周期和事件释放。 +- [事件系统](../modules/frameworks/事件系统/README.md)：CTC/STC 事件、派发链路、监听规范。 +- [资源管理](../modules/frameworks/资源管理/README.md)：AssetBundle、语言资源、图集、加载规则。 +- [对象池](../modules/frameworks/内存对象管理/README.md)：类实例池、行为对象池、实体池、RT 展示对象。 + +--- + +## Spec / Plan 索引 + +| 类型 | 文档 | +|---|---| +| Spec 索引 | [specs/Spec索引.md](../specs/Spec索引.md) | +| OpenSpec 归档 | [specs/openspec/OpenSpec归档.md](../specs/openspec/OpenSpec归档.md) | +| 计划进度 | [plans/](../plans/) | + +--- + +## 任务流转 + +### 简单修复 + +- 查询、解释、定位问题。 +- 小范围、明确、影响面低的修改。 +- 用户已给出明确实现方式。 + +处理：直接开始修复或回答，完成后验证，并执行归档 hook / 归档检查。 + +### 旧模块修复 + +- 项目中已有模块的 bug 修复、逻辑补全、局部优化。 +- 影响范围主要集中在一个已有功能或框架模块。 +- 不新增大模块，不调整总体架构。 + +处理：读取相关模块文档和代码/内容，简短分析影响范围后直接修复；完成后验证，并按 [50-归档规则.md](50-归档规则.md) 执行归档 hook / 归档检查。 + +### Spec 任务 + +- 新增大功能或新模块。 +- 调整架构、目录职责、依赖方向。 +- 调整文档结构、生成流程。 +- 涉及多个系统的批量修改、删除、迁移。 +- 用户没有明确方案，需要先权衡。 + +处理：按 [40-工作流清单.md](40-工作流清单.md) 和 [60-新特性工作流.md](60-新特性工作流.md) 走 OpenSpec。 + +--- + +## OpenSpec 工作流（大需求 / 新模块） + +1. 分析目标、影响范围、风险和依赖。 +2. 给出 2-3 个方案，让用户选择。 +3. 用户确认后创建 OpenSpec change： + - Claude Code：`/opsx:propose "需求描述"` + - CLI 通用：`openspec new change "change-name"` +4. 生成 `proposal.md`、`design.md`、`tasks.md`。 +5. 判断是 **新模块** 还是 **已有模块的大改**： + - 新模块：创建模块文档、登记模块、补充架构。 + - 已有模块的大改：更新模块 progress.md、tasks.md，记录变更。 +6. 按 design/tasks 实现代码、资源或配置变更。 +7. 验证。 +8. 归档 OpenSpec change： + - Claude Code：`/opsx:archive` + - CLI 通用：`openspec archive "change-name"` +9. 按 [50-归档规则.md](50-归档规则.md) 同步到项目文档： + - `specs/openspec//` + - 相关模块 `模块索引.md`、`progress.md`、`tasks.md` + - `10-架构说明.md`（如涉及架构变化） + - `modules/模块索引.md`（如新增模块） + - `30-模块登记规则.md`（如改变模块分类、状态定义或登记规则） + +--- + +## 扫描范围 + +正常分析项目时，**默认跳过**以下目录和文件以节省 token： + +- `Library/` +- `Temp/` +- `Logs/` +- `UserSettings/` +- `.vs/` +- `*.csproj` +- `*.sln` +- `.codex/`（本地 hooks 状态） +- `.claude/`（本地 commands/skills 状态） +- `Library/PackageCache/` +- `obj/` +- `bin/` +- 图片、音频、模型等二进制资源 + +详见 [70-项目设置.md](70-项目设置.md)。 + +--- + +## 关键约束 + +- **一处定义，多处引用**：如果一个事实出现在多个文档中，修改时必须同步所有地方。 +- 优先修改源头文档，不要手动同步复制多份内容。 +- 运行时代码不引用 Editor 程序集。 +- UI 变更遵循 [UI 框架](../modules/frameworks/UI窗口系统/README.md)。 +- 事件变更遵循 [事件框架](../modules/frameworks/事件系统/README.md)。 +- 资源变更遵循 [资源管理](../modules/frameworks/资源管理/README.md)。 + +--- + +## 归档规则摘要 + +所有任务完成后都执行归档 hook / 归档检查。归档不是写流水账，只更新和本次任务相关的长期文档。 + +简单修复如果没有改变长期规则、模块状态、架构或后续任务，可以只在最终回复中说明无需文档更新；旧模块修复和 Spec 任务按影响范围同步相关模块文档。 + +核心原则：**一处定义，多处引用**。 + +详见 [50-归档规则.md](50-归档规则.md)。 + +--- + +## 文档变更联动原则 + +修改任何文档前，先确认它是否被其他文档引用： + +- 模块文档变更 → 同步检查模块索引、模块登记规则、架构说明。 +- 架构/目录变更 → 同步检查模块索引、相关模块 README、架构说明。 +- 规则文件变更 → 同步检查本文件、`ai/AI接入入口.md`、`AGENTS.md`、`CLAUDE.md`、`RULES.md`。 +- spec/change 完成 → 同步更新相关模块 progress.md，并建立 `specs/openspec/` 归档。 + +## 归档触发 + +文档关联和归档触发逻辑统一放在 `hooks/`： + +| 触发方式 | 命令/路径 | 说明 | +|---|---|---| +| Codex Stop hook | `.codex/hooks/archive-reminder.ps1` | 每次任务结束自动调用 `hooks/archive-check.ps1` 输出建议 | +| Claude Code 手动 | `/opsx:archive-check` | 手动触发归档检查 | +| OpenSpec 自动 | `/opsx:archive` | Spec 流程归档完成后自动调用 `hooks/archive-check.ps1` | +| 手动脚本 | `hooks/archive-check.ps1` | 直接运行 PowerShell 脚本 | + +**重要**：以上触发只输出建议，不会自动修改任何文档。最终是否更新关联文档，需要用户确认。 + +详见 [hooks/Hook共享层.md](../hooks/Hook共享层.md)。 + +--- + +## 接入新 AI 工具时 + +如果你是新接入的 AI 工具，只需要： + +1. 读取 [ai/AI接入入口.md](../ai/AI接入入口.md)。 +2. 再读取本文件（`rules/项目规则入口.md`）。 +3. 按任务范围读取本文件索引中的具体规则/模块/spec 文档。 +4. 遵循本文件的工作方式、扫描范围、关键约束和归档规则。 + +不同 AI / IDE 的默认入口、hook 适配方式统一维护在 `ai/AI接入入口.md`。项目根目录的 `AGENTS.md`、`CLAUDE.md`、`RULES.md` 都是指向 `ai/AI接入入口.md` 的薄入口。 + +--- + +## 文档关联 + +> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。 + +| 文档 | 关联原因 | +|---|---| +| [ai/AI接入入口.md](../ai/AI接入入口.md) | AI 接入入口引用本项目规则入口 | +| [AGENTS.md](../AGENTS.md) | Codex 入口通过 ai/AI接入入口.md 引用本文件 | +| [CLAUDE.md](../CLAUDE.md) | Claude Code 入口通过 ai/AI接入入口.md 引用本文件 | +| [RULES.md](../RULES.md) | 兼容重定向入口通过 ai/AI接入入口.md 引用本文件 | +| [rules/00-项目概览.md](00-项目概览.md) | 项目概况在本文档中被引用 | +| [rules/10-架构说明.md](10-架构说明.md) | 架构说明在本文档中被引用 | +| [rules/20-开发规则.md](20-开发规则.md) | 开发规则在本文档中被引用 | +| [rules/30-模块登记规则.md](30-模块登记规则.md) | 模块登记规则在本文档中被引用 | +| [rules/40-工作流清单.md](40-工作流清单.md) | 工作流清单在本文档中被引用 | +| [rules/50-归档规则.md](50-归档规则.md) | 归档规则在本文档中被引用 | +| [rules/60-新特性工作流.md](60-新特性工作流.md) | 大需求/新模块工作流在本文档中被引用 | +| [rules/70-项目设置.md](70-项目设置.md) | 扫描范围规则在本文档中被引用 | +| [modules/模块索引.md](../modules/模块索引.md) | 模块索引是本文档引用的项目知识入口 | +| [specs/Spec索引.md](../specs/Spec索引.md) | Spec 索引在本文档中被引用 | +| [hooks/Hook共享层.md](../hooks/Hook共享层.md) | 归档触发机制在本文档中被引用 | diff --git a/specs/Spec模板.md b/specs/Spec模板.md new file mode 100644 index 0000000..c056712 --- /dev/null +++ b/specs/Spec模板.md @@ -0,0 +1,75 @@ +# Spec 标题 + +## 文档关联 + +- **相关规则**： + - [归档规则](../rules/50-归档规则.md) + - [大需求 / 新模块工作流](../rules/60-新特性工作流.md) +- **相关模块**： + - `[<功能模块>]`（示例路径：`../modules/features/.md`） + - `[<框架模块>]`（示例路径：`../modules/frameworks/.md`） + +> 当本 spec 发生变更时，必须检查并同步更新相关模块文档和规则。 + +## 背景 + +TODO：为什么做这件事？当前有什么问题？ + +## 目标 + +- TODO + +## 非目标 + +- TODO + +## 影响范围 + +- 代码： +- 资源： +- 数据/配置： +- 文档： +- 关联模块： + - `[<功能模块>]`（示例路径：`../modules/features/.md`） + - `[<框架模块>]`（示例路径：`../modules/frameworks/.md`） + +## 方案 + +### 方案 A + +- 优点： +- 缺点： + +### 方案 B + +- 优点： +- 缺点： + +## 选定方案 + +TODO + +## 任务 + +- [ ] TODO + +## 验证 + +- [ ] TODO + +## 变更记录 + +| 日期 | 变更内容 | 变更人 | +|---|---|---| +| YYYY-MM-DD | 初始版本 | - | + +## 归档 + +完成后必须同步更新（详见 [归档规则](../rules/50-归档规则.md)、[大需求 / 新模块工作流](../rules/60-新特性工作流.md)）： + +- [ ] `specs/openspec//` +- [ ] 相关模块 `模块索引.md` +- [ ] 相关模块 `progress.md` +- [ ] 相关模块 `tasks.md` +- [ ] `rules/10-架构说明.md`（如涉及架构变化） +- [ ] `rules/30-模块登记规则.md`（如新增模块） \ No newline at end of file diff --git a/specs/Spec索引.md b/specs/Spec索引.md new file mode 100644 index 0000000..2deb845 --- /dev/null +++ b/specs/Spec索引.md @@ -0,0 +1,57 @@ +# Spec 索引 + +大需求、新模块、架构调整、生成流程调整等 Spec 任务在这里沉淀方案和结果。 + +## 使用规则 + +- 简单修复和旧模块修复不需要创建 spec，按规则直接处理并执行归档检查。 +- 大需求 / 新模块使用 OpenSpec 流程： + - Claude Code 命令 `/opsx:propose "需求描述"` 创建 change。 + - 生成 `proposal.md`、`design.md`、`tasks.md`。 + - `/opsx:apply` 执行实现。 + - `/opsx:archive` 归档到 `openspec/changes/archive/`。 +- OpenSpec 归档后，再按 [归档规则](../rules/50-归档规则.md) 同步到项目既有模块文档： + - `specs/openspec//` + - `modules//业务参考总入口.md`、`progress.md`、`tasks.md` + - `rules/10-架构说明.md`、`rules/30-模块登记规则.md` +- 如果不用 OpenSpec，也可复制 [Spec模板.md](Spec模板.md) 创建普通 spec。 + +## OpenSpec 归档 + +大需求 / 新模块经 OpenSpec 流程后，长期归档优先放在： + +```text +specs/openspec/ +``` + +详见 [specs/openspec/OpenSpec归档.md](openspec/OpenSpec归档.md)。 + +## 命名建议 + +普通 spec 文件： + +```text +YYYY-MM-DD-feature-name.md +``` + +OpenSpec change： + +```text +kebab-case-change-name +``` + +## 文档关联 + +- [工作流清单](../rules/40-工作流清单.md)：任务分类、修复流程、Spec 流程、提交前检查、生成/构建流程。 +- [大需求 / 新模块工作流](../rules/60-新特性工作流.md)：新增/已有功能判断、模块登记、联动更新检查。 +- [归档规则](../rules/50-归档规则.md)：归档时机、内容、格式和关联更新原则。 +- [模块索引](../modules/模块索引.md)：项目功能、框架、编辑器工具模块总览。 + +## 同步要求 + +OpenSpec change 完成后，必须将结论同步到项目模块文档： + +- `specs/openspec//` — OpenSpec 归档目录 +- `modules//业务参考总入口.md`、`progress.md`、`tasks.md` — 相关模块文档 +- `rules/10-架构说明.md`（如涉及架构变化） +- `rules/30-模块登记规则.md`（如新增模块） \ No newline at end of file diff --git a/specs/openspec/OpenSpec归档.md b/specs/openspec/OpenSpec归档.md new file mode 100644 index 0000000..e67105d --- /dev/null +++ b/specs/openspec/OpenSpec归档.md @@ -0,0 +1,100 @@ +# OpenSpec 归档目录 + +本目录用于存放大需求、新模块、架构调整、生成流程调整等 Spec 任务经 OpenSpec 流程沉淀后的长期文档。 + +## 目录结构 + +```text +specs/openspec/ +├── 模块索引.md # 本文件 +├── / # 单个 Spec 任务的归档 +│ ├── proposal.md # 需求背景与目标 +│ ├── design.md # 设计方案 +│ └── tasks.md # 实现任务与验证 +└── ... +``` + +## OpenSpec 工作目录 + +OpenSpec CLI 的活跃工作目录位于项目根目录： + +```text +openspec/ +├── changes/ # 进行中的 change +├── changes/archive/ # OpenSpec 自身归档的 change +└── specs/ # OpenSpec 管理的 spec +``` + +## 工作流 + +### 简单修复 / 旧模块修复 + +- 直接修改代码/资源。 +- 简短说明结果。 +- 执行归档检查；没有长期信息变化时，不归档到本目录。 + +### 大需求 / 新模块 + +1. 使用 Claude Code 命令 `/opsx:propose "需求描述"` 创建 change。 +2. 按 OpenSpec 流程生成 `proposal.md`、`design.md`、`tasks.md`。 +3. 使用 `/opsx:apply` 执行实现。 +4. 实现完成后使用 `/opsx:archive` 归档。 +5. **同时**把结论同步到本目录和项目既有模块文档： + - `specs/openspec//` + - `modules//业务参考总入口.md` + - `modules//progress.md` + - `modules//tasks.md` + - `rules/10-架构说明.md`（如涉及架构变化） + - `modules/模块索引.md`（如新增模块） + - `rules/30-模块登记规则.md`（如改变模块分类、状态定义或登记规则） + +## 文档关联 + +- [工作流清单](../../rules/40-工作流清单.md)：任务分类、修复流程、Spec 流程、提交前检查、生成/构建流程。 +- [大需求 / 新模块工作流](../../rules/60-新特性工作流.md)：新增/已有功能判断、模块登记、联动更新检查。 +- [归档规则](../../rules/50-归档规则.md)：归档时机、内容、格式和关联更新原则。 +- [模块索引](../../modules/模块索引.md)：项目功能、框架、编辑器工具模块总览。 + +## 同步要求 + +OpenSpec change 完成后，必须将结论同步到项目模块文档： + +- `specs/openspec//` — OpenSpec 归档目录 +- `modules//业务参考总入口.md`、`progress.md`、`tasks.md` — 相关模块文档 +- `rules/10-架构说明.md`（如涉及架构变化） +- `modules/模块索引.md`（如新增模块） +- `rules/30-模块登记规则.md`（如改变模块分类、状态定义或登记规则） + +## 与项目既有规则的关系 + +- 项目既有规则入口：`RULES.md`、`AGENTS.md`、`rules/` +- OpenSpec 负责大需求 / 新模块的 spec-driven 流程。 +- 项目既有文档负责长期模块知识、架构说明和任务跟踪。 +- 大需求 / 新模块完成后，OpenSpec 归档和项目归档都需要做。 + +## 命令速查 + +```bash +# 查看进行中的 changes +openspec list + +# 查看 specs +openspec list --specs + +# 创建新 change +openspec new change "change-name" + +# 查看 change 状态 +openspec status --change "change-name" + +# 归档 change +openspec archive "change-name" +``` + +Claude Code 命令： + +- `/opsx:propose "需求描述"` — 创建并生成 change 文档 +- `/opsx:apply` — 按 design/tasks 实现 +- `/opsx:archive` — 归档完成 +- `/opsx:explore` — 探索性分析 +- `/opsx:sync` — 同步 specs \ No newline at end of file