# Editor Tools 规划方案

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

---

## 目录

1. [技术选型：IMGUI vs UI Toolkit](#1-技术选型imgui-vs-ui-toolkit)
2. [工具体系总览](#2-工具体系总览)
3. [现有工具清单与评估](#3-现有工具清单与评估)
4. [新增工具详细规划](#4-新增工具详细规划)
5. [目录结构规范](#5-目录结构规范)
6. [菜单结构规范](#6-菜单结构规范)
7. [优先级与实施顺序](#7-优先级与实施顺序)
8. [共用基础设施](#8-共用基础设施)

---

## 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 动态化改造配套）

**流程**：
1. 输入 `weaponId`（如 `SkyBlade`）
2. 勾选需要的攻击方向（Ground / Up / Down / Air）
3. 为每个方向选择 Collider 类型（Box / Capsule / Polygon）和初始尺寸
4. 点击「创建」→ 在 `Assets/Prefabs/Weapons/` 下生成：
   ```
   WPN_SkyBlade_HitBox.prefab
   └── [HitBox_Ground]   BoxCollider2D(IsTrigger) + HitBox.cs  Layer=PlayerHitBox
   └── [HitBox_Up]       …
   └── [HitBox_Down]     …
   └── [HitBox_Air]      …
       WeaponHitBoxInstance.cs（挂在根节点，SerializeField 自动赋值）
   ```
5. 自动 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` 中的私有静态方法提取为独立公共类：

```csharp
// 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`：
```css
/* 标准分区标题 */
.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 创建辅助

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

```csharp
// 返回创建的资产路径；已存在时返回 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 工具后，同步更新本文档的「现有工具清单」表格。*