Files

2026-05-15 14:47:24 +08:00

22 KiB

Raw Permalink Blame History

Editor Tools 规划方案

版本：1.0 · 2026-05
范围：Assets/_Game/Scripts/Editor/ 下所有编辑器扩展的全面规划
关联架构：Docs/Architecture/ 全集，重点 05/06/07/09/23
目标：为策划、程序提供一套完整、一致、易维护的 Unity 编辑器工具体系

1. 技术选型：IMGUI vs UI Toolkit

1.1 对比矩阵

维度	IMGUI	UI Toolkit
开发速度（简单工具）	✅ 快，代码即布局	🟡 需 UXML + USS + C#
性能（大量列表/刷新）	🔴 每帧重绘全部	✅ 虚拟化列表，增量刷新
分栏/停靠布局	🟡 手动计算 Rect	✅ `TwoPaneSplitView` 内置
运行时数据绑定	🔴 不支持	✅ `INotifyValueChanged`
属性绘制（SerializedObject）	✅ `PropertyField` 直接用	🟡 `BindProperty()` 额外步骤
Play Mode 实时刷新	🟡 依赖 `Repaint()`	✅ 事件驱动
现有代码库一致性	✅ 全部现有工具使用	🟡 新引入
Unity 版本要求	任意	Unity 2022+ ✅（项目已满足）

1.2 决策结论

按工具类型分策略，不做全局迁移：

工具类别	推荐技术	原因
运行时调试监视器（EventBusMonitor、PlayModeOverlay）	IMGUI	每帧刷新，状态简单，IMGUI 够用且响应快
简单属性绘制器（PropertyDrawer、CustomEditor）	IMGUI	`PropertyField` + `EditorGUI` 即可，无需 UXML
验收工具（VerificationHelperWindow）	IMGUI	已有，稳定，无改造价值
一次性脚手架工具（SceneScaffoldTools）	IMGUI MenuItems	无窗口 UI，只是菜单触发
数据浏览 + 编辑窗口（武器/技能/敌人/护符）	UI Toolkit	分栏布局、可搜索列表、大量字段，UI Toolkit 优势明显
Dashboard 总入口	UI Toolkit	模块导航卡片，视觉丰富
Boss 技能序列可视化	IMGUI（现有保留）	甘特图自绘，IMGUI Rect 更直接

2. 工具体系总览

按功能分为五大类：

A. 数据管理窗口     — 浏览 / 创建 / 编辑 ScriptableObject 资产
B. Prefab 配置工具  — 武器 / 技能 / 敌人 HitBox Prefab 结构验证与快速搭建
C. 场景工具         — 场景脚手架、World 物体快速放置
D. 运行时调试工具   — Play Mode 下数据监视 / 状态覆写
E. 验收 / 构建工具  — SO 合法性校验、构建前检查、Physics2D 矩阵

3. 现有工具清单与评估

3.1 保留不变（Stable）

文件	类型	菜单路径	状态
`Verification/VerificationHelperWindow.cs`	IMGUI Window	`BaseGames/Verification/Open Verification Helper`	✅ 保留
`Verification/Physics2DLayerReport.cs`	IMGUI MenuItem	`BaseGames/Verification/Check	Fix Physics2D Layer Matrix`
`Verification/ExtraScaffoldExtensions.cs`	IMGUI MenuItems	`BaseGames/Verification/Scaffold/…`	✅ 保留
`Verification/PlayModeDebugOverlay.cs`	IMGUI Overlay	Play Mode UI	✅ 保留
`EventBusMonitorWindow.cs`	IMGUI Window	`BaseGames/Tools/Event Bus Monitor`	✅ 保留
`EventChainEditorWindow.cs`	IMGUI Window	`BaseGames/Tools/Event Chain Viewer`	✅ 保留
`BossSkillSequenceWindow.cs`	IMGUI Window	`BaseGames/Tools/Boss Skill Sequence Viewer`	✅ 保留
`AddressReferenceGraphWindow.cs`	IMGUI Window	`BaseGames/Tools/Asset Reference Graph`	✅ 保留
`AddressableBatchTool.cs`	IMGUI MenuItem	—	✅ 保留
`AddressKeyValidator.cs`	Build Preprocessor	—	✅ 保留
`NavSurfaceBakeShortcut.cs`	MenuItem	—	✅ 保留
`ScriptExecutionOrderTools.cs`	MenuItem	—	✅ 保留
`SceneScaffoldTools.cs`	IMGUI MenuItem	`BaseGames/Scene/…`	✅ 保留（已更新 WeaponSocket）
`Validation/SOValidationRunner.cs`	Build Preprocessor + MenuItem	`Tools/Validate All ScriptableObjects`	✅ 保留
`Equipment/CharmEffectDrawer.cs`	IMGUI CustomEditor	Inspector	✅ 保留
`Combat/HurtBoxEditor.cs`	IMGUI CustomEditor	Inspector	✅ 保留
`Map/MapRoomDataEditor.cs`	IMGUI CustomEditor	Inspector	✅ 保留
`World/DestructibleTileEditor.cs`	IMGUI CustomEditor	Inspector	✅ 保留
`Achievements/AchievementSOEditor.cs`	IMGUI CustomEditor	Inspector	✅ 保留

3.2 待改造（Migrate）

文件	问题	建议
`CreateTestAssets.cs`	硬编码文件路径和资产名，缺乏可配置性	保留 MenuItem 逻辑，抽取配置到 SO
`CreateEventChannelAssets.cs`	功能可并入新 Dashboard	长期合并
`EventChannelEditor.cs` / `EventConfigEditor.cs`	独立 Inspector 扩展，无窗口化需求	保留但评估是否并入 Dashboard

4. 新增工具详细规划

W-01 · BaseGames Dashboard（总入口）

文件：Editor/Dashboard/EditorDashboardWindow.cs
技术：UI Toolkit
菜单：BaseGames/Open Dashboard (Ctrl+Shift+D)
优先级：P2（其他窗口完成后汇总入口）

功能：

模块导航卡片（Combat / Player / Enemy / Equipment / World / Tools）
每个卡片点击打开对应数据管理窗口
快速链接：Scene Scaffold、Validation Runner、Verification Helper
状态摘要：当前场景资产统计、未完成 SO 验证警告数

W-02 · Weapon Editor（武器编辑器）

文件：Editor/Combat/WeaponEditorWindow.cs
技术：UI Toolkit（TwoPaneSplitView）
菜单：BaseGames/Data/Weapon Editor
优先级：P1（武器 HitBox 动态化后，数据创建频率增高）

布局：

┌────────────────┬──────────────────────────────────────────┐
│ [搜索框]       │  [WeaponType 标签] Weapon_SkyBlade       │
│ ──────────     │  ──────────────────────────────────────── │
│ ■ SkyBlade     │  基础信息     weaponId / displayName …   │
│ ■ EarthHammer  │  ──────────                              │
│ ■ LifeScythe   │  连击动画     attack1Clip … downAttackClip│
│ + [新建]       │  ──────────                              │
│                │  伤害来源     attack1Source … ×6         │
│                │  ──────────                              │
│                │  HitBox Prefab [对象字段]  [定位 Prefab]  │
│                │  ──────────                              │
│                │  战斗参数     soulPowerGain / weaponType  │
│                │  武器特效     VFXConfig 折叠面板          │
└────────────────┴──────────────────────────────────────────┘

特有功能：

HitBox Prefab 验证：检查引用 Prefab 是否包含 WeaponHitBoxInstance 组件，否则显示警告
伤害来源快速新建：每个 DamageSourceSO 字段旁放 [Create] 按钮，自动命名 DSrc_{weaponId}_{segment} 并存入 Assets/_Game/Data/Combat/DamageSources/
连击链预览：显示 attack1→attack2→attack3 的 Clip 名称 + BaseDamage 数值序列

W-03 · Skill Editor（技能编辑器）

文件：Editor/Skills/SkillEditorWindow.cs
技术：UI Toolkit
菜单：BaseGames/Data/Skill Editor
优先级：P1

布局：与 W-02 类似的双栏结构

左栏：

按 SkillEffectType 分组（MeleeAoE / Projectile / BarrierAura / …）
搜索框（按 skillId / displayNameKey 过滤）

右栏：

Identity / Resource / Animation / Effect / Projectile / Explosion / Feedback 分区折叠面板
SkillHitBoxPrefab 字段：若非空，显示 Prefab 结构预览（SkillHitBoxInstance 子节点个数 + HitBox 列表）

特有功能：

冷却 / 消耗平衡表：底部浮动 Panel，以表格展示所有技能的 baseCost / cooldown 对比，辅助策划平衡调整
HitBox Prefab 快速创建向导：填写 skillId → 自动生成 SKL_{skillId}_HitBox.prefab 骨架（含 SkillHitBoxInstance + 子节点 HitBox GO）

W-04 · Form & Weapon Assignment（形态-武器-技能关联）

文件：Editor/Player/FormEditorWindow.cs
技术：UI Toolkit
菜单：BaseGames/Data/Form Editor
优先级：P2

布局：三列

[FormSO 列表] → [当前形态详情] → [技能/武器预览面板]

功能：

显示所有 FormSO，点击进入详情
详情显示：defaultWeapon（链接到 W-02）、soulSkill / spirit1 / spirit2（链接到 W-03）
矩阵视图：所有形态 × 三个技能槽的全局总览（快速发现空槽）

W-05 · Enemy Data Manager（敌人数据管理器）

文件：Editor/Enemies/EnemyDataWindow.cs
技术：UI Toolkit
菜单：BaseGames/Data/Enemy Data Manager
优先级：P1（敌人设计是高频迭代内容）

布局：双栏，左侧 ListView（支持搜索 + 按 EnemyType 过滤）

右栏分页：

Stats：EnemyStatsSO 全字段（MaxHP / Attack / Defense / Speed / …）
Loot：LootTableSO 条目列表（itemId / weight / minCount / maxCount）可增删
Boss：若为 Boss，显示关联 BossSkillSO 列表（链接 BossSkillSequenceWindow）
Prefab：关联 Prefab 路径 + 结构验证（HurtBox Layer、EnemyBase、HitBox 等）

特有功能：

数值对比面板：勾选多个敌人，弹出雷达图（HP / ATK / DEF / SPD）对比
快速克隆：从选中 EnemyStatsSO 克隆变体（命名 EnemyStats_{name}_Elite）

W-06 · Charm Catalog Manager（护符目录管理器）

文件：Editor/Equipment/CharmCatalogWindow.cs
技术：UI Toolkit
菜单：BaseGames/Data/Charm Catalog
优先级：P2

布局：双栏

左栏：护符列表，按 notchCost / Effect 类型过滤
右栏：护符详情

notchCost / icon / displayNameKey
Effects 列表（沿用现有 CharmEffectDrawer 逻辑，移植为 UI Toolkit BindableElement）
效果描述预览（调用 GetEffectDescription()）

特有功能：

Notch 平衡面板：饼图展示当前所有护符 notchCost 分布
效果类型矩阵：护符 × 效果类型的覆盖矩阵，发现重复/空缺

W-07 · Prefab Structure Validator（Prefab 结构验证器）

文件：Editor/Prefabs/PrefabValidatorWindow.cs
技术：IMGUI（简单列表，无复杂布局需求）
菜单：BaseGames/Tools/Prefab Structure Validator
优先级：P2

功能：扫描以下 Prefab 命名规范并验证结构完整性：

Prefab 类型	命名规范	必须包含组件
武器 HitBox	`WPN_{weaponId}_HitBox`	`WeaponHitBoxInstance` + ≥1 `HitBox`
技能 HitBox	`SKL_{skillId}_HitBox`	`SkillHitBoxInstance` + ≥1 `HitBox`
玩家	`PLY_Player`	`PlayerController` `WeaponManager._weaponSocket` 非空
敌人	`ENM_*`	`EnemyBase` `HurtBox`（Layer=EnemyHurtBox）
投射物	`PRJ_*`	`Projectile` `Collider2D`（IsTrigger）

输出：Console 日志 + 窗口内可点击跳转的错误列表

W-08 · Interactable Scene Helper（场景交互物配置助手）

文件：Editor/World/InteractableSceneHelper.cs
技术：IMGUI（Scene View 工具栏扩展 + 小窗口）
菜单：BaseGames/Scene/Interactable Helper
优先级：P3

功能：

在 Scene View 工具栏添加快速放置按钮：SavePoint / RoomTransition / HazardZone / Collectible / DestructibleTile / MovingPlatform / AbilityUnlock
放置时自动设置 Layer、添加必要子节点、绑定默认事件频道
复用 SceneScaffoldTools 中的 GetOrAddComponent / SetLayer 私有方法（提取为 EditorScaffoldUtils 公共静态类）

W-09 · DamageSource Inspector 增强

文件：Editor/Combat/DamageSourceInspector.cs
技术：IMGUI CustomEditor
优先级：P2

功能：

在 DamageSourceSO Inspector 底部添加伤害预览区：
- 显示 FinalDamage ≈ BaseDamage × DamageMultiplier（含示例防御减免）
- DamageFlags / DamageTags 用枚举 Toggle 组显示，替代默认位掩码数字
BreakLevel 字段以颜色编码标签显示（None=灰 / Light=绿 / Medium=蓝 / Heavy=橙 / Breaker=红）

W-10 · WeaponHitBox Prefab 快速创建向导

文件：Editor/Combat/WeaponHitBoxWizard.cs
技术：IMGUI ScriptableWizard
菜单：BaseGames/Create/Weapon HitBox Prefab
优先级：P1（与 WeaponSO 动态化改造配套）

流程：

输入 weaponId（如 SkyBlade）
勾选需要的攻击方向（Ground / Up / Down / Air）
为每个方向选择 Collider 类型（Box / Capsule / Polygon）和初始尺寸

点击「创建」→ 在 Assets/Prefabs/Weapons/ 下生成：

WPN_SkyBlade_HitBox.prefab
└── [HitBox_Ground]   BoxCollider2D(IsTrigger) + HitBox.cs  Layer=PlayerHitBox
└── [HitBox_Up]       …
└── [HitBox_Down]     …
└── [HitBox_Air]      …
    WeaponHitBoxInstance.cs（挂在根节点，SerializeField 自动赋值）

自动 Ping 创建的 Prefab 并选中

W-11 · SkillHitBox Prefab 快速创建向导

文件：Editor/Skills/SkillHitBoxWizard.cs
技术：IMGUI ScriptableWizard
菜单：BaseGames/Create/Skill HitBox Prefab
优先级：P1

与 W-10 类似，生成：

SKL_{skillId}_HitBox.prefab
└── [HitBox_0]  PolygonCollider2D(IsTrigger) + HitBox.cs  Layer=PlayerHitBox
    SkillHitBoxInstance.cs（根节点，_hitBoxes 自动赋值）

5. 目录结构规范

Assets/_Game/Scripts/Editor/
│
├── BaseGames.Editor.asmdef
│
├── Dashboard/
│   └── EditorDashboardWindow.cs          [新增 W-01] UI Toolkit
│
├── Combat/
│   ├── HurtBoxEditor.cs                  [现有]
│   ├── DamageSourceInspector.cs          [新增 W-09] IMGUI CustomEditor
│   ├── WeaponEditorWindow.cs             [新增 W-02] UI Toolkit
│   └── WeaponHitBoxWizard.cs             [新增 W-10] IMGUI Wizard
│
├── Skills/
│   ├── SkillEditorWindow.cs              [新增 W-03] UI Toolkit
│   └── SkillHitBoxWizard.cs              [新增 W-11] IMGUI Wizard
│
├── Player/
│   └── FormEditorWindow.cs               [新增 W-04] UI Toolkit
│
├── Enemies/
│   └── EnemyDataWindow.cs                [新增 W-05] UI Toolkit
│
├── Equipment/
│   ├── CharmEffectDrawer.cs              [现有]
│   └── CharmCatalogWindow.cs             [新增 W-06] UI Toolkit
│
├── Prefabs/
│   └── PrefabValidatorWindow.cs          [新增 W-07] IMGUI
│
├── World/
│   ├── DestructibleTileEditor.cs         [现有]
│   └── InteractableSceneHelper.cs        [新增 W-08] IMGUI
│
├── Map/
│   └── MapRoomDataEditor.cs              [现有]
│
├── Achievements/
│   └── AchievementSOEditor.cs            [现有]
│
├── Validation/
│   └── SOValidationRunner.cs             [现有]
│
├── Verification/
│   ├── VerificationHelperWindow.cs       [现有]
│   ├── ExtraScaffoldExtensions.cs        [现有]
│   ├── Physics2DLayerReport.cs           [现有]
│   └── PlayModeDebugOverlay.cs           [现有]
│
├── Shared/
│   │   ← 跨窗口复用的基础设施
│   ├── EditorScaffoldUtils.cs            [新增] SceneScaffoldTools 公共工具提取
│   └── EditorWindowBase.cs              [新增] 统一 OnEnable/OnGUI 基类（UI Toolkit 窗口）
│
└── UIToolkit/
    ├── Editor.uss                        [新增] 统一样式表
    └── Layouts/
        ├── TwoPaneWindow.uxml            [新增] 标准双栏布局模板
        └── AssetListItem.uxml            [新增] 资产列表行模板

6. 菜单结构规范

BaseGames/
├── Open Dashboard     (Ctrl+Shift+D)          W-01
│
├── Data/
│   ├── Weapon Editor                          W-02
│   ├── Skill Editor                           W-03
│   ├── Form Editor                            W-04
│   ├── Enemy Data Manager                     W-05
│   └── Charm Catalog                          W-06
│
├── Create/
│   ├── Weapon HitBox Prefab                   W-10
│   └── Skill HitBox Prefab                    W-11
│
├── Scene/
│   ├── Scaffold Persistent Scene              (现有)
│   ├── Scaffold Test Room                     (现有)
│   └── Interactable Helper                    W-08
│
├── Tools/
│   ├── Event Bus Monitor  (Ctrl+Shift+E)      (现有)
│   ├── Event Chain Viewer                     (现有)
│   ├── Boss Skill Sequence Viewer             (现有)
│   ├── Asset Reference Graph                  (现有)
│   ├── Prefab Structure Validator             W-07
│   └── Create Test Assets                     (现有)
│
└── Verification/
    ├── Open Verification Helper (Ctrl+Shift+V)(现有)
    ├── Check Physics2D Layer Matrix            (现有)
    ├── Fix Physics2D Layer Matrix              (现有)
    └── Scaffold/…                              (现有)

7. 优先级与实施顺序

P1 — 配套当前架构改动，立即需要

ID	名称	关联改动	工作量估计
W-10	WeaponHitBox Prefab 向导	WeaponSO.hitBoxPrefab 动态化	S（0.5d）
W-11	SkillHitBox Prefab 向导	SkillHitBoxPrefab 已有字段	S（0.5d）
W-02	Weapon Editor 窗口	WeaponSO 字段增多	M（2d）
W-03	Skill Editor 窗口	FormSkillSO 字段多	M（2d）
W-05	Enemy Data Manager	高频策划迭代	M（2d）
W-09	DamageSource Inspector 增强	DamageSourceSO 易配错	S（0.5d）

P2 — 生产力提升，下一迭代

ID	名称	工作量估计
W-07	Prefab 结构验证器	S（1d）
W-04	Form Editor	S（1d）
W-06	Charm Catalog 管理器	M（1.5d）

P3 — 长期完善

ID	名称	工作量估计
W-08	场景交互物助手	M（2d）
W-01	Dashboard 总入口	M（2d）

8. 共用基础设施

8.1 EditorScaffoldUtils（从 SceneScaffoldTools 提取）

将 SceneScaffoldTools.cs 中的私有静态方法提取为独立公共类：

// Editor/Shared/EditorScaffoldUtils.cs
namespace BaseGames.Editor
{
    public static class EditorScaffoldUtils
    {
        public static Transform    GetOrCreateChild(Transform parent, string name);
        public static T            GetOrAddComponent<T>(GameObject go) where T : Component;
        public static void         SetLayer(GameObject go, string layerName, List<string> report);
        public static void         AssignReference(Object target, string field, Object value, List<string> report = null);
        public static void         AssignAsset<T>(Object target, string field, List<string> report,
                                                   bool required, string assetNameHint) where T : Object;
        public static void         MarkDirtyAndLog(string scaffoldName, Object root, List<string> report);
    }
}

SceneScaffoldTools 和 ExtraScaffoldExtensions 改为调用此工具类，消除重复代码（当前 ExtraScaffoldExtensions 注释"镜像 SceneScaffoldTools 中的 private 静态方法"即为此痛点）。

8.2 UI Toolkit 统一样式

Editor/UIToolkit/Editor.uss：

/* 标准分区标题 */
.section-header { font-size: 11px; -unity-font-style: bold; margin-top: 8px; }

/* 警告行 */
.row-warning { background-color: rgba(220, 150, 0, 0.15); }
.row-error   { background-color: rgba(220, 50,  50, 0.15); }

/* 列表项高亮 */
.list-item:hover { background-color: rgba(255,255,255,0.05); }

8.3 SO 创建辅助

所有数据窗口的「新建」按钮使用统一签名：

// 返回创建的资产路径；已存在时返回 null（不覆盖）
public static T CreateSOAsset<T>(string folder, string assetName) where T : ScriptableObject
{
    string dir  = $"Assets/_Game/Data/{folder}";
    string path = $"{dir}/{assetName}.asset";
    if (AssetDatabase.LoadAssetAtPath<T>(path) != null) return null;
    Directory.CreateDirectory(Path.Combine(Application.dataPath, $"../{dir}"));
    var asset = ScriptableObject.CreateInstance<T>();
    AssetDatabase.CreateAsset(asset, path);
    AssetDatabase.SaveAssets();
    EditorGUIUtility.PingObject(asset);
    return asset;
}

文档维护：每次新增或修改 Editor 工具后，同步更新本文档的「现有工具清单」表格。

22 KiB Raw Permalink Blame History Unescape Escape

Editor Tools 规划方案

目录

1. 技术选型：IMGUI vs UI Toolkit

1.1 对比矩阵

1.2 决策结论

2. 工具体系总览

3. 现有工具清单与评估

3.1 保留不变（Stable）

3.2 待改造（Migrate）

4. 新增工具详细规划

W-01 · BaseGames Dashboard（总入口）

W-02 · Weapon Editor（武器编辑器）

W-03 · Skill Editor（技能编辑器）

W-04 · Form & Weapon Assignment（形态-武器-技能关联）

W-05 · Enemy Data Manager（敌人数据管理器）

W-06 · Charm Catalog Manager（护符目录管理器）

W-07 · Prefab Structure Validator（Prefab 结构验证器）

W-08 · Interactable Scene Helper（场景交互物配置助手）

W-09 · DamageSource Inspector 增强

W-10 · WeaponHitBox Prefab 快速创建向导

W-11 · SkillHitBox Prefab 快速创建向导

5. 目录结构规范

6. 菜单结构规范

7. 优先级与实施顺序

P1 — 配套当前架构改动，立即需要

P2 — 生产力提升，下一迭代

P3 — 长期完善

8. 共用基础设施

8.1 EditorScaffoldUtils（从 SceneScaffoldTools 提取）

8.2 UI Toolkit 统一样式

8.3 SO 创建辅助

22 KiB

Raw Permalink Blame History