docs: improve AssetFolderSpec and AddressablesLabelSpec standards
- AssetFolderSpec.md: - Add §12 Editor Tools Reference with all creation/scene/Addressables tools - Expand §10 workflows: add Weapon, Skill, Charm, Player Form, VFX (with editor tool refs) - Update §10.1 Enemy workflow to reference EnemyDataWindow - Update §11 forbidden list to include bypassing editor creation tools - Add §13 TOC entry - AddressablesLabelSpec.md: - Bump version to 1.1 - Reference AddressableRules.cs in header - Add §7 Tooling & Automation (Rule Sync workflow, batch workflow, tool table) - Update §6 new-label steps to include AddressableRules.cs update step Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
@@ -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<GameObject>(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<GameObject>(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<GameObject>(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<GameObject>(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 工具误报分组或标签不一致。
|
||||
|
||||
Reference in New Issue
Block a user