diff --git a/Docs/Standards/AddressablesLabelSpec.md b/Docs/Standards/AddressablesLabelSpec.md index 3298f9d..283a333 100644 --- a/Docs/Standards/AddressablesLabelSpec.md +++ b/Docs/Standards/AddressablesLabelSpec.md @@ -1,9 +1,9 @@ # Addressables Label（标签）命名与使用规范 -> **版本**：1.0 +> **版本**：1.1 > **创建日期**：2026-05 > **适用范围**：`Assets/_Game/` 目录下所有注册到 Addressables 的资产 -> **关联文档**：`Standards/AssetFolderSpec.md §8`、`Scripts/Core/Assets/AddressKeys.cs` +> **关联文档**：`Standards/AssetFolderSpec.md §8`、`Scripts/Core/Assets/AddressKeys.cs`、`Scripts/Editor/Addressables/AddressableRules.cs` --- @@ -15,6 +15,7 @@ 4. [AddressKeys.cs 常量对照](#4-addresskeyscs-常量对照) 5. [使用规范与禁止行为](#5-使用规范与禁止行为) 6. [新增 Label 决策流程](#6-新增-label-决策流程) +7. [工具链与自动化](#7-工具链与自动化) --- @@ -255,8 +256,62 @@ await Addressables.DownloadDependenciesAsync("Preload", false); │ 新增 Label 的执行步骤： 1. 在 AddressKeys.Labels 类中添加 public const string {Name} = "{Name}"; - 2. 在 Addressables Groups 窗口 → Label 列表中创建同名标签 - 3. 在本文档 §2 Label 清单中追加说明行 - 4. 在本文档 §3 对应资产类型的表格中标注 - 5. 运行 AddressKeyValidator 验证无遗漏 + 2. 在 AddressableRules.cs 的 PrefixLabelMap / ExactLabelMap 中添加对应映射规则 + 3. 在 Addressables Groups 窗口 → Label 列表中创建同名标签 + 4. 在本文档 §2 Label 清单中追加说明行 + 5. 在本文档 §3 对应资产类型的表格中标注 + 6. 运行 Rule Sync（菜单 BaseGames → Addressables → Rule Sync）Scan 验证无遗漏 + 7. 运行 AddressKeyValidator（菜单 BaseGames → Verification → Validate Address Keys）确认 ``` + +--- + +## 7. 工具链与自动化 + +### 7.1 规则权威来源 + +所有分组与标签的映射规则**集中定义**于： + +``` +Assets/_Game/Scripts/Editor/Addressables/AddressableRules.cs +``` + +- `PrefixGroupMap` — 地址前缀 → Group 名称 +- `PrefixLabelMap` — 地址前缀 → Label 列表（更具体的前缀排在前面） +- `ExactLabelMap` — 精确地址 → Label 列表（覆盖前缀规则的特殊情况） + +**修改规则时只改 `AddressableRules.cs` 一处**，两个工具（`AddressableBatchTool` 和 `AddressableRuleSyncWindow`）均从此处读取，保证一致性。 + +### 7.2 日常标签维护工作流 + +``` +新建/更新资产后： + 1. 打开 Rule Sync 窗口（菜单 BaseGames → Addressables → Rule Sync） + 2. 点击 [Scan All] — 扫描所有 Addressable 条目与期望规则的差异 + 3. 查看报告： + - Group Mismatch — 资产在错误的分组 + - Label Missing — 缺少应有标签 + - Label Extra — 存在不应有的标签 + 4. 点击 [Fix All] 或逐条点击 [Fix] 自动修复 + 5. 可选：点击 [Export CSV] 导出差异报告存档 + 6. 运行 Validate Address Keys 做最终验证 +``` + +### 7.3 批量注册工作流（新增大量资产） + +``` + 1. 将资产按命名前缀放置到正确目录（见 AssetFolderSpec.md §2–§4） + 2. 打开 Addressable Batch Tool（菜单 BaseGames → Tools → Addressable Batch Tool） + 3. 切换到 "② 文件夹批量" 标签，选择目标文件夹，点击 [Register Folder] + 4. 切换到 "① 同步 AddressKeys" 标签，点击 [Scan]，为新注册的资产补充 AddressKeys.cs 常量 + 5. 返回 Rule Sync 窗口执行 Scan → Fix All 统一校正 Group / Label + 6. 运行 Validate Address Keys 验证 +``` + +### 7.4 工具一览 + +| 工具 | 菜单路径 | 核心功能 | +|------|---------|---------| +| **Rule Sync** | `BaseGames → Addressables → Rule Sync` | 扫描 + 修复分组/标签不合规条目；导出 CSV | +| **Addressable Batch Tool** | `BaseGames → Tools → Addressable Batch Tool` | 三标签：AddressKeys 同步 / 文件夹批量注册 / Selection 注册 | +| **Validate Address Keys** | `BaseGames → Verification → Validate Address Keys` | 验证 AddressKeys.cs 所有常量均已在 Addressables 注册，构建前自动触发 | diff --git a/Docs/Standards/AssetFolderSpec.md b/Docs/Standards/AssetFolderSpec.md index 5ed3d5b..318efec 100644 --- a/Docs/Standards/AssetFolderSpec.md +++ b/Docs/Standards/AssetFolderSpec.md @@ -22,6 +22,7 @@ 10. [Import Settings 规范](#9-import-settings-规范) 11. [资源新增工作流](#10-资源新增工作流) 12. [禁止行为清单](#11-禁止行为清单) +13. [编辑器工具参考](#12-编辑器工具参考) --- @@ -642,6 +643,8 @@ var (prefab, _) = await AssetLoader.LoadAsync(AddressKeys.PrefabPlay ### 10.1 新增敌人 +> **推荐工具**：`BaseGames → Data → Enemy Data Manager`（`EnemyDataWindow`）——在左栏点击 [New] 可自动创建 `ENM_*_Stats.asset`，在右栏 Loot Tab 配置掉落表。 + ``` 1. _Game/Art/Characters/Enemies/ 下创建 {EnemyID}/ 目录，内含 Sprites/ Animations/ Materials/ Atlases/ 2. 导入 Sprite Sheet 到 Sprites/，配置 Import Settings（PPU=32, Filter=Point, Multiple） @@ -649,25 +652,88 @@ var (prefab, _) = await AssetLoader.LoadAsync(AddressKeys.PrefabPlay 4. 在 Animations/ 下创建动画片段（.anim）和 Animator Controller 5. 在 Materials/ 下创建材质（引用 _Game/Shaders/ 中的角色 Shader，关联主纹理和 Emission 贴图） 6. 在 Atlases/ 下创建 Atlas_Enemy_{ID}.spriteatlas，包含该敌人所有 Sprite -7. 在 _Game/Data/Enemies/{EnemyID}/ 下创建 ENM_*_Stats.asset 等 SO +7. 在 Enemy Data Manager（菜单 BaseGames → Data → Enemy Data Manager）创建 ENM_{ID}_Stats.asset 8. 在 _Game/Prefabs/Enemies/{EnemyID}/ 下创建 ENM_{Name}.prefab 9. 在 AddressKeys.cs 中添加 PrefabEnemy{Name} 常量 -10. 使用 AddressableBatchTool 注册到 Enemies_{Region} 组，添加 Enemy 标签 -11. 运行 AddressKeyValidator 验证 +10. 使用 Rule Sync（菜单 BaseGames → Addressables → Rule Sync）Scan → Fix All，自动分组并打 Enemy 标签 +11. 运行 AddressKeyValidator（菜单 BaseGames → Verification → Validate Address Keys）验证 ``` -### 10.2 新增 VFX +### 10.2 新增武器（Weapon） + +> **推荐工具**：`BaseGames → Data → Weapon Editor`（`WeaponEditorWindow`）创建 `WPN_*_Data.asset`；`BaseGames → Create → Weapon HitBox Prefab`（`WeaponHitBoxWizard`）创建 4 方向 HitBox Prefab。 + +``` +1. 在 _Game/Art/Characters/Player/{FormID}/Sprites/ 下放置武器帧动画 Sprite Sheet，配置 Import Settings +2. 在 Weapon Editor（菜单 BaseGames → Data → Weapon Editor）左栏 [New] 创建 WPN_{Name}_Data.asset + - 路径：_Game/Data/Combat/Weapons/WPN_{Name}_Data.asset + - 命名：WPN_{Name}（示例：WPN_SkyBlade、WPN_EarthClaw） +3. 使用 Weapon HitBox Wizard（菜单 BaseGames → Create → Weapon HitBox Prefab）生成 + _Game/Prefabs/Weapons/WPN_{Name}_HitBox.prefab（自动创建 4 方向 Ground/Up/Down/Air） +4. 在 _Game/Prefabs/Player/ 下创建或更新武器顶级 Prefab WPN_{Name}.prefab +5. 在 AddressKeys.cs 中添加 PrefabWeapon{Name} 常量 +6. 使用 Rule Sync 自动分组（Player 组）并打 Weapon + Preload 标签 +7. 运行 AddressKeyValidator 验证 +``` + +### 10.3 新增技能（Skill） + +> **推荐工具**：`BaseGames → Data → Skill Editor`（`SkillEditorWindow`）创建 `SKL_*_Data.asset`；`BaseGames → Create → Skill HitBox Prefab`（`SkillHitBoxWizard`）创建多段 HitBox Prefab。 + +``` +1. 在 _Game/Art/Characters/Player/{FormID}/Animations/ 下创建技能动画片段（.anim） +2. 在 Skill Editor（菜单 BaseGames → Data → Skill Editor）左栏 [New] 创建 SKL_{SkillID}_Data.asset + - 路径：_Game/Data/Player/Skills/SKL_{SkillID}_Data.asset + - 命名：SKL_{SkillID}（示例：SKL_DashSlash、SKL_SpiritWave） +3. 使用 Skill HitBox Wizard（菜单 BaseGames → Create → Skill HitBox Prefab）生成 + _Game/Prefabs/Skills/SKL_{SkillID}_HitBox.prefab（支持多段伤害配置） +4. 在 AddressKeys.cs 中添加对应常量（如需独立 Addressable 加载） +5. 运行 AddressKeyValidator 验证（如已注册 Addressable） +``` + +### 10.4 新增护身符（Charm） + +> **推荐工具**：直接在 Project 窗口 Create → 对应 CharmSO，然后通过 CharmSOEditor（Custom Inspector）配置效果类型与参数。 + +``` +1. 在 _Game/Data/Progression/Charms/ 下创建 CHM_{Name}.asset（CharmSO） + - 命名：CHM_{Name}（示例：CHM_SoulReaper、CHM_IronSkin） +2. 在 Inspector 中通过 CharmSOEditor 下拉选择效果类型并配置参数 +3. 在 AddressKeys.cs 中添加 DataCharm{Name} 常量 +4. 使用 Rule Sync 自动分组（Config 组）并打 Charms 标签 +5. 运行 AddressKeyValidator 验证 +``` + +### 10.5 新增玩家形态（Player Form） + +> **推荐工具**：`BaseGames → Tools → Character Wizard`（`CharacterWizardWindow`）统一入口——创建 FormSO、绑定武器引用、跳转到 Form Editor；`BaseGames → Data → Form Editor`（`FormEditorWindow`）进行三魂列阵可视化编辑。 + +``` +1. 在 Character Wizard（菜单 BaseGames → Tools → Character Wizard）切换到 Player 标签 + - 填写 FormID，点击 [Create Form Assets]，自动在正确路径创建 FormSO 和相关 SO +2. 在 _Game/Art/Characters/Player/{FormID}/ 下创建 Sprites/ Animations/ Materials/ Atlases/ 目录 +3. 导入 Sprite Sheet，配置 Import Settings（PPU=32, Filter=Point, Multiple） +4. 在 Form Editor（菜单 BaseGames → Data → Form Editor）三栏网格中选择形态格位，绑定武器和技能列表 +5. 在 _Game/Prefabs/Player/ 下创建 PLY_{FormID}.prefab +6. 在 AddressKeys.cs 中添加 PrefabPlayer{FormID} 常量（如为独立 Addressable） +7. 使用 Rule Sync 自动分组（Player 组）并打 Preload 标签 +8. 运行 AddressKeyValidator 验证 +``` + +### 10.6 新增 VFX + +> **提示**：VFX Prefab 必须纳入 `GlobalObjectPool`，在 Pool 配置中指定初始预热数量。 ``` 1. 在 _Game/Art/Effects/Sprites/ 下导入特效 Sprite Sheet，配置 Import Settings（PPU=32, Filter=Point） 2. 在 _Game/Art/Effects/Materials/ 下创建特效材质 3. 在 _Game/Prefabs/Effects/ 下创建 VFX_{Name}.prefab 4. 在 AddressKeys.cs 中添加 PrefabVFX{Name} 常量 -5. 使用 AddressableBatchTool 注册到 VFX_Common 组，添加 Poolable 标签 -6. 在 AssetReleaseTracker 配套的 Pool 中注册（纳入对象池） +5. 使用 Rule Sync 自动分组（VFX_Common 组）并打 Poolable + Preload 标签 +6. 在 GlobalObjectPool._warmupConfigs 中添加初始池数量配置 ``` -### 10.3 新增 UI 界面 +### 10.7 新增 UI 界面 ``` 1. 在 _Game/UI Toolkit/Layouts/ 下创建 {PanelName}.uxml @@ -675,15 +741,15 @@ var (prefab, _) = await AssetLoader.LoadAsync(AddressKeys.PrefabPlay 3. 在 _Game/Prefabs/UI/ 下创建 UI_{PanelName}.prefab 4. 在 _Game/Data/UI/Panels/ 下创建 UI_PanelConfig_{PanelName}.asset（如需配置 SO） 5. 在 AddressKeys.cs 中添加 PrefabUI{PanelName} 常量 -6. 使用 AddressableBatchTool 注册到 UI 组 +6. 使用 Rule Sync 自动分组（UI 组）；常驻全局面板额外打 Preload 标签 ``` -### 10.4 新增关卡场景 +### 10.8 新增关卡场景 ``` 1. 在 _Game/Scenes/ 下创建 Room_{Region}_{Index:D2}.unity 2. 在 AddressKeys.cs 中添加地址常量（复用 SceneRoomPrefix + 动态拼接或新增独立常量） -3. 将场景注册到 Room_{Region} 组 +3. 将场景注册到 Room_{Region} 组（Rule Sync 可自动识别 Room_ 前缀并动态计算组名） 4. 在 _Game/Data/World/Map/ 下创建 MAP_RoomData_{Region}_{Index:D2}.asset ``` @@ -705,3 +771,52 @@ var (prefab, _) = await AssetLoader.LoadAsync(AddressKeys.PrefabPlay | 第三方插件目录内创建自定义资产 | 插件升级时被覆盖 | 自定义内容放在 `_Game/` 下对应模块目录 | | 将 `_Game/` 内的资产移到 `Assets/` 根目录 | 破坏第一方/第三方隔离原则 | 所有自有资产必须在 `_Game/` 内 | | 将 `AddressableAssetsData/` 移入 `_Game/` | Unity 硬编码此路径，移动后 Addressables 完全失效 | 永远保留在 `Assets/` 根目录 | +| 绕过编辑器工具手动创建 SO / Prefab | 路径或命名不符合规范，导致 Addressables 工具误报 | 使用 §12 中的对应编辑器窗口创建 | + +--- + +## 12. 编辑器工具参考 + +所有**资产创建**均应通过以下编辑器工具进行，以保证路径、命名、Addressables 注册完全符合本规范。 + +### 12.1 资产创建工具 + +| 工具名称 | 菜单路径 | 负责资产类型 | 说明 | +|---------|---------|------------|------| +| **Character Wizard** | `BaseGames → Tools → Character Wizard` | 角色 SO（玩家形态 / Minion / Boss 通用入口） | 统一入口，自动在正确路径创建所有配套 SO，内含快捷跳转按钮 | +| **Form Editor** | `BaseGames → Data → Form Editor` | 玩家三魂形态（FormSO） | 三栏可视化网格，自动绑定武器/技能引用，支持 TianHun / DiHun / MingHun | +| **Enemy Data Manager** | `BaseGames → Data → Enemy Data Manager` | 敌人配置 SO（`ENM_*_Stats.asset`）+ 掉落表 | 双面板列表编辑，左栏搜索 + [New]，右栏 Stats/Loot 标签 | +| **Weapon Editor** | `BaseGames → Data → Weapon Editor` | 武器配置 SO（`WPN_*_Data.asset`） | 双面板列表，右栏全属性 + HitBox Prefab 验证 + 快捷操作 | +| **Weapon HitBox Wizard** | `BaseGames → Create → Weapon HitBox Prefab` | 武器 HitBox Prefab（4 方向 Ground/Up/Down/Air） | 自动生成 `WPN_{ID}_HitBox.prefab`，支持各方向碰撞体形状配置 | +| **Skill Editor** | `BaseGames → Data → Skill Editor` | 技能配置 SO（`SKL_*_Data.asset`） | 按 SkillEffectType 分组筛选，右栏含 HitBox 验证 + 资源费预览 | +| **Skill HitBox Wizard** | `BaseGames → Create → Skill HitBox Prefab` | 技能 HitBox Prefab（多段伤害支持） | 自动生成 `SKL_{ID}_HitBox.prefab`，可配置 1–4 段 hitBoxCount | +| **Boss Skill Sequence** | `BaseGames → Tools → Boss Skill Sequence Viewer` | Boss 技能阶段（BossSkillSO / SkillSequenceSO） | Gantt 时间轴可视化，Windup / Active / Recovery 三段颜色标记 | + +### 12.2 场景搭建工具 + +| 工具名称 | 菜单路径 | 说明 | +|---------|---------|------| +| **Boot Flow Wizard** | `BaseGames → Tools → Boot Flow Wizard` | 4 步启动流程一键配置（事件频道 → Persistent 场景 → MainMenu → 验证） | +| **Scene Scaffold** | `BaseGames → Tools → Scaffold Persistent Scene` | 一键创建 Persistent 场景的 Services/Input/Camera/UI 层次结构 | +| **Scene Object Placer** | `BaseGames → Scene → Place → {类型}` | 场景中快速放置角色/陷阱/检查点/摄像机等，自动绑定组件和事件频道 | +| **Persistent Auto-Loader** | `BaseGames → Tools → Edit Mode: Auto-Open Persistent Scene` | 编辑模式下打开任意场景时自动附加 Persistent（仅编辑模式） | + +### 12.3 Addressables 管理工具 + +| 工具名称 | 菜单路径 | 说明 | +|---------|---------|------| +| **Rule Sync** | `BaseGames → Addressables → Rule Sync` | 批量扫描/修复分组和标签（基于 `AddressableRules.cs` 规则，支持导出 CSV） | +| **Addressable Batch Tool** | `BaseGames → Tools → Addressable Batch Tool` | 三标签操作：① 同步 AddressKeys → ② 文件夹批量注册 → ③ Selection 注册 | +| **Validate Address Keys** | `BaseGames → Verification → Validate Address Keys` | 验证 `AddressKeys.cs` 所有常量在 Addressables 中均已注册，构建前自动触发 | + +### 12.4 数据/调试工具 + +| 工具名称 | 菜单路径 | 说明 | +|---------|---------|------| +| **SO Manager** | `BaseGames → Tools → SO Manager` | 全项目 ScriptableObject 浏览器，支持类型/路径搜索 + Ping | +| **Event Bus Monitor** | `BaseGames → Tools → Event Bus Monitor` | 运行时事件派发监控（类型/侦听器数/触发次数实时显示） | +| **Create Event Channel Assets** | `BaseGames → Tools → Create Event Channel Assets` | 一键生成全局事件频道 SO（幂等，跳过已存在资产） | +| **GM Debug Tool** | `BaseGames → Tools → GM Debug Tool` | 运行时快速注入资源/切换形态/解锁技能（仅 PlayMode） | +| **Validate All ScriptableObjects** | `BaseGames → Tools → Validate All ScriptableObjects` | 扫描所有 `IValidatable` SO 并报告错误（构建前自动触发） | + +> **原则**：新增资产类型时，必须同步在对应编辑器工具中增加创建入口；严禁绕过工具手动在 Project 窗口 "Create" 并手动填写路径/命名，否则将导致 Addressables Rule Sync 工具误报分组或标签不一致。