XCEngine/docs/plan/used/NewEditor对标旧Editor迁移重建计划_2026-04-12.md

NewEditor 对标旧 Editor 迁移重建计划

日期: 2026-04-12

1. 文档定位

这份计划用于正式切换主线：

• 旧 editor/ 继续作为参考实现与行为基线。
• new_editor/ 从“XCEditor 基础层试验宿主”升级为“新编辑器正式重建宿主”。
• 后续工作重点不再是单独补 XCEditor 的孤立控件，而是参考旧 editor/，在 new_editor/ 内逐步重建完整编辑器应用。

但有一个硬约束必须始终遵守：

• 如果在重建 new_editor 的过程中暴露出 XCEditor、宿主层或输入/布局/viewport 基础设施的结构问题，必须先回到底层修根因，再继续往上迁移。
• 不允许在 new_editor 业务层堆临时兼容逻辑来掩盖底层问题。

这份计划替代此前“先单独收口 dock/UI 基础层，再暂停业务”的阶段性计划。当前主线已经进入 new_editor 正式重建阶段。

2. 不可违背的设计原则

2.1 根因优先

• 任何交互、布局、DPI、capture、拖拽、文本测量、渲染清晰度问题，优先在 XCEditor / Host / shared editor infrastructure 修。
• 禁止在某个 panel 内写只为绕过去的局部 hack。

2.2 旧 Editor 是参考基线，不是直接复制目标

• 旧 editor/ 的行为、工作流、信息架构、可用性和视觉结果是当前最可靠的参考。
• 旧 editor/ 里凡是 ImGui 特有的壳代码、临时 helper、历史包袱，不应机械照搬。
• 迁移过程中允许顺手做架构收敛，但必须保持行为兼容，不允许一边“优化”一边偏离旧版交互。

2.3 XCEditor 只承载 Editor UI 基础层，不承载 Editor 业务

• new_editor/include/XCEditor/** + new_editor/src/** 负责 editor-only 的 UI primitive、shell、dock、field、tree/list、menu、viewport slot、workspace 等基础能力。
• new_editor 的正式编辑器业务必须放在应用层，不得继续把业务逻辑塞回 XCEditor 库层。

2.4 Editor 样式固定写死在代码里

• Runtime UI 保留资源化/主题化能力，服务游戏开发者。
• Editor UI 当前不走资源驱动主线，样式、palette、metrics、chrome 由代码固定维护。
• 不再给 Editor UI 扩一套厚重的主题资源解释系统。

2.5 测试体系与产品宿主分离

• tests/UI/Core|Runtime|Editor 继续作为 UI 模块验证入口。
• new_editor/ 是产品宿主，不是测试场景堆放区。
• 某项能力先在对应层的 tests/UI 里做 unit/integration 回归，再接入 new_editor。

3. 当前基线判断

3.1 已经完成并可复用的部分

当前 new_editor 已经具备一套可继续向上承接的 Editor UI 基础层：

• XCEditor 库层已经有：
  • Fields
  • Tree/List/Scroll/TabStrip
  • MenuBar/MenuPopup/StatusBar
  • DockHost/Workspace/PanelHost
  • ViewportSlot/ViewportShell
  • shortcut、command registry、workspace persistence
• Host 层已经有：
  • Win32 宿主
  • Direct2D/DirectWrite 文本与图像绘制
  • DPI 感知
  • 自动截图
  • 自有 exe 截图输出
• new_editor 当前已经验证过：
  • Unity 风格的基础 chrome
  • tab 拖拽重排与停靠
  • project 左树与右侧浏览器的基础外壳
  • hierarchy / project 图标与文本对齐
  • 多项 tests/UI/Editor unit / integration 回归

结论：

• XCEditor 不再是“完全不能承接产品”的状态。
• 当前真正缺的不是几个零散 widget，而是 new_editor 应用层本身还没有长成旧 editor/ 那样完整的编辑器架构。

3.2 当前仍然缺失的关键能力

距离“可以真正替代旧 editor/ 开始长期迭代”的状态，当前还缺：

1. new_editor 自己的应用层骨架还不完整。
2. 缺少类似旧 editor/src/Core + Managers + Actions + Commands + Panels + Viewport + ComponentEditors + Scripting 的正式分层。
3. Hierarchy 仍是 demo/static 数据，不是场景真实数据。
4. Project 虽然外壳已成型，但还不是旧 editor 的完整资产工作流。
5. Inspector 及 ComponentEditorRegistry 体系尚未接回。
6. Console 与日志桥接尚未接回。
7. Scene/Game viewport 还没有接回旧 editor 的真实渲染/交互主链。
8. project / scene / undo / selection / action route / runtime mode 这些编辑器全局状态在 new_editor 里还没有正式 owner。
9. 脚本、运行模式、保存/打开、项目切换、Library/Asset 流程都还未接回。

4. 旧 Editor 与 NewEditor 的真实差距

4.1 旧 Editor 的实际分层

旧 editor/ 当前已经形成的主干是：

Application -> EditorLayer -> EditorWorkspace -> Panels/Viewport -> Actions -> Commands -> Managers/Core

横向还包含：

• UI
• ComponentEditors
• Layout
• Scripting
• Platform

这意味着旧 editor 已经不是“只有一堆 panel”，而是一套完整的编辑器应用结构。

4.2 NewEditor 当前的真实分层

new_editor/ 当前更接近：

Application + Host + XCEditorLib + 少量 Product 面板

其中：

• include/XCEditor/** + src/** 是 Editor UI 库层。
• Host/** 是平台与绘制宿主。
• app/** 目前还只是轻量应用壳与少量试制 panel。

缺口在于：

• 旧 editor 的“应用层中间层”几乎还没完整迁过来。
• 当前 new_editor 的 panel 仍然偏 prototype，不是正式产品模块。

4.3 模块映射与结论

旧 editor 模块	当前状态	new_editor 目标落点
editor/src/UI/**	大部分语义已被 XCEditor 吸收	继续沉淀在 include/XCEditor/** + src/**
editor/src/Layout/**	旧版依赖 ImGui docking	由 XCEditor/Shell/** 的 workspace/dock host 接替
editor/src/Application.*	旧版完整	new_editor 应保留为宿主壳，避免塞业务
editor/src/Core/**	旧版完整	new_editor 需要建立对应 app-level Core
editor/src/Managers/**	旧版完整	new_editor 需要建立对应 app-level Managers
editor/src/Actions/**	旧版完整	new_editor 需要正式迁入
editor/src/Commands/**	旧版完整	new_editor 需要正式迁入
editor/src/panels/**	旧版完整	new_editor 需要按新 shell 重写，但行为对齐旧版
editor/src/ComponentEditors/**	旧版完整	new_editor 需要迁入并适配 XCEditor property grid/field
editor/src/Viewport/**	旧版完整	new_editor 需要重新桥接到 XCEditor viewport slot/shell
editor/src/Scripting/**	旧版完整	new_editor 后期需要接回

结论：

• XCEditor 已经覆盖了大量旧 editor/src/UI/** 与 Layout 的职责。
• 但 new_editor 还没有真正补上旧 editor 的应用层与工作流层。
• 因此接下来的重点不是“继续造更多基础控件”，而是“用旧 editor 的结构和行为为参照，把新 editor 的应用层补齐”。

5. 迁移总策略

迁移策略固定为两条线并行推进：

5.1 主线：重建 NewEditor 应用层

• 以旧 editor/ 为参考，在 new_editor 下逐步建立正式的：
  • Core
  • Managers
  • Actions
  • Commands
  • Panels
  • Viewport
  • ComponentEditors
  • Scripting

5.2 副线：按需回补 XCEditor / Host

• 当主线重建暴露底层能力缺口时，再回补：
  • XCEditor
  • Host
  • tests/UI/Editor

副线只为解决主线遇到的真实阻塞，不再无边界扩 editor-only widget。

6. 目标架构

6.1 XCEditor 的职责边界

保留在库层的内容：

• fixed-code editor theme / metrics / palette
• menu / popup / dock / workspace / tab strip
• tree / list / scroll / inline rename / property grid / fields
• viewport slot / viewport shell
• editor UI input model、session、interaction state machine

不放进库层的内容：

• project 资产语义
• scene/entity/component 语义
• console/log bridge
• project/scene open/save 工作流
• inspector 组件注册表
• editor 菜单业务动作

6.2 new_editor 应用层目标结构

应用层建议逐步收敛到与旧 editor/src 接近的形态：

new_editor/
  Host/
  include/XCEditor/
  src/
    Core/
    Managers/
    Actions/
    Commands/
    Panels/
    Viewport/
    ComponentEditors/
    Scripting/
    Shell/
    Icons/
    Application/

说明：

• include/XCEditor/** + src/** 中的库层文件继续保留并演进。
• new_editor 的产品应用代码不应长期散落在轻量 app/* 原型目录里。
• 迁移早期可以暂时复用现有 app/*，但必须尽快收敛到正式应用层目录，避免“基础层代码”和“产品层代码”混杂。

7. 分阶段执行计划

Phase 0：文档与目录主线切换

目标

把主线明确切到 new_editor 正式重建，清理过期计划入口。

任务

• 归档旧的阶段性 dock 收口计划。
• 保留 Editor架构说明.md 作为旧 editor 参考文档，不归档。
• 新建本迁移计划，作为当前唯一 editor 重建主线。
• 在计划中正式写死：
  • old editor = reference
  • new_editor = product host
  • XCEditor = editor ui library
  • tests/UI = module verification entry

完成标准

• 后续不再以旧 dock 收口计划作为主线驱动文档。

Phase 1：收敛 NewEditor 应用层骨架

目标

先把 new_editor 从“壳 + 若干 product panel”收敛成“真正的编辑器应用结构”。

任务

• 建立 new_editor 自己的应用层目录与命名边界。
• 提炼 Application 的纯宿主职责：
  • window / DPI / renderer / input pump / screenshot / main loop
• 建立 EditorWorkspace 式的应用装配层：
  • panel registry
  • workspace compose
  • panel attach/detach/update/render
• 建立 EditorContext / IEditorContext 式的全局状态容器。
• 定义新 editor 的状态所有权：
  • selection owner
  • scene owner
  • project owner
  • undo owner
  • active action route owner
  • runtime mode owner

根因要求

• 不允许继续让 Application 直接知道越来越多 project/hierarchy 细节。
• 任何产品语义都必须逐步从 Application 下沉到 context / managers / panels。

完成标准

• new_editor 具备清晰的 app-level Core/Workspace/Panels 骨架。
• 现有 ProductHierarchyPanel / ProductProjectPanel 不再是孤立 demo 对象，而是正式 panel 接口的一部分。

Phase 2：迁入全局动作路由与命令层

目标

把旧 editor 的 “menu / shortcut / context menu / toolbar -> action/router -> command” 主链迁进来。

任务

• 对照旧 editor/src/Actions/** 梳理新 editor 的动作集：
  • File
  • Edit
  • Assets
  • Run
  • Scripts
  • View
  • Help
• 建立新的 action route 机制：
  • global actions
  • focused panel actions
  • active route dispatch
• 将真正修改数据的行为放入 Commands/**。
• 让菜单、快捷键、右键菜单、toolbar 共享同一套动作定义。

根因要求

• 不允许 menu、shortcut、context menu 各自复制一套业务逻辑。
• 不允许 panel 直接偷偷修改 scene/project 状态绕开 command。

完成标准

• 所有 editor 主动作都有稳定 owner。
• UI 入口与业务执行不再混杂。

Phase 3：接回 Hierarchy 正式数据模型

目标

把 Hierarchy 从 demo tree 改成真实 scene-backed 面板。

任务

• 用真实场景层级替换当前静态 m_treeItems。
• 建立 hierarchy 展平与增量同步路径。
• 接回 selection 同步。
• 接回 rename。
• 接回 create/delete/duplicate。
• 接回拖拽 reparent：
  • drop on entity => 成为子节点
  • drop on empty area => 回到 root
• 接回 context menu。
• 接回旧 editor 的层级树图标/展开/焦点/多选策略。

优先参考文件

• editor/src/panels/HierarchyPanel.*
• editor/src/Actions/HierarchyActionRouter.h
• editor/src/Commands/EntityCommands.h
• editor/src/Managers/SceneManager.*

根因要求

• 先建立可变 hierarchy source model，再做拖拽。
• 如拖拽/capture 冲突，需要在 shared hosted-content capture 机制上统一修复，不允许再写 panel 特判。

完成标准

• Hierarchy 具备旧 editor 的核心编辑语义，而不是展示假数据。

Phase 4：接回 Project 正式资产工作流

目标

把已经有外壳的 Project 面板接回真实 project/Assets 工作流。

任务

• 用正式 ProjectManager/Asset data source 替换当前轻量扫描逻辑。
• 保持已完成的外观与交互风格。
• 接回：
  • folder tree
  • breadcrumb navigation
  • asset grid selection
  • open / double click
  • rename
  • create folder
  • delete
  • drag move
  • context menu
  • refresh / watcher
• 对齐旧 editor 的 .meta / Library / 资源管理语义。

优先参考文件

• editor/src/panels/ProjectPanel.*
• editor/src/Actions/ProjectActionRouter.h
• editor/src/Commands/ProjectCommands.h
• editor/src/Managers/ProjectManager.*

根因要求

• Project 右侧 grid 的事件必须继续保持语义化输出，不要退回 raw hit test 乱写业务。
• 资产操作必须收敛到 command / manager，不能把文件系统操作塞在 UI 绘制逻辑里。

完成标准

• Project 成为真正可用的资产浏览与操作入口。

Phase 5：接回 Inspector 与 ComponentEditorRegistry

目标

把 XCEditor 已有的 field/property grid 真正用于 Inspector，而不是停留在基础控件演示。

任务

• 建立新的 ComponentEditors/** 注册表。
• 接回 InspectorPanel。
• 首批接回：
  • Transform
  • Camera
  • Light
  • MeshFilter
  • MeshRenderer
  • Script
• 接回 object/asset reference field。
• 处理 interactive undo 边界。
• 对齐旧 editor 的 Add Component 入口与规则。

优先参考文件

• editor/src/panels/InspectorPanel.*
• editor/src/ComponentEditors/**
• editor/src/Commands/ComponentCommands.h

根因要求

• 通用字段行为沉淀在 XCEditor/Fields/**。
• 组件语义停留在 app-level ComponentEditors/**。
• 不允许把具体组件判断重新塞回 shared field 层。

完成标准

• Inspector 可以对真实选中对象执行稳定编辑。

Phase 6：接回 Console 与编辑器日志桥接

目标

补齐旧 editor 的 console 工作流。

任务

• 迁入 console data model、过滤状态与 sink。
• 接回日志分级、清空、过滤、点击定位等基础行为。
• 与菜单/快捷键/上下文操作对齐。

优先参考文件

• editor/src/panels/ConsolePanel.*
• editor/src/UI/ConsoleFilterState.h
• editor/src/Core/EditorConsoleSink.*
• editor/src/Actions/ConsoleActionRouter.h

完成标准

• Console 不再是空 panel，能承担真实调试反馈。

Phase 7：接回 Scene / Game Viewport 正式主链

目标

这是替代旧 editor 的真正硬门槛。

任务

• 将旧 editor 的 viewport host/render path 重新桥接到 XCEditorViewportSlot / XCEditorViewportShell。
• 接回：
  • scene viewport 离屏渲染
  • game viewport 渲染
  • viewport resize
  • navigation
  • gizmo
  • overlay
  • selection / picking
  • edit / play mode 切换
• 处理 viewport 与 shell 输入焦点、capture、cursor 的统一。

优先参考文件

• editor/src/panels/SceneViewPanel.*
• editor/src/panels/GameViewPanel.*
• editor/src/Viewport/**
• editor/src/Application.*
• editor/src/Platform/D3D12WindowRenderer*

根因要求

• viewport 相关问题优先在 app viewport layer / host bridge 修。
• 不允许在 panel 里私拼第二套渲染路径。

完成标准

• Scene/Game 具备旧 editor 的基础可用性。

Phase 8：接回项目生命周期、运行模式与脚本工作流

目标

把编辑器从“几个面板能显示”推进到“有完整项目工作流”。

任务

• project 打开 / 切换 / 保存状态
• scene 打开 / 保存 / Save As
• runtime mode / play session controller
• 脚本程序集重建与状态显示
• Library/bootstrap/import 状态展示
• window title 与 dirty state

优先参考文件

• editor/src/Core/PlaySessionController.*
• editor/src/Core/EditorWindowTitle.h
• editor/src/Scripting/**
• editor/src/Application.*

完成标准

• new_editor 能跑通真实项目编辑主流程，而不是只展示 UI 壳。

Phase 9：视觉一致性、回归与旧 Editor 退场条件

目标

在核心工作流都接回后，统一做收口。

任务

• 对关键界面做逐项比对：
  • menu bar
  • dock/tab
  • hierarchy
  • project
  • inspector
  • console
  • scene/game
• 修正与旧 editor 的视觉与交互偏差。
• 清理 new_editor 中所有 demo 数据、临时状态、过渡适配层。
• 给每一块关键能力补齐：
  • tests/UI/Editor
  • product-level smoke validation

最终收口标准

满足以下条件后，才算真正达到“可替代旧 editor”的程度：

1. new_editor 已接回旧 editor 的核心面板与主工作流。
2. Scene/Game viewport 可稳定工作。
3. Hierarchy/Project/Inspector/Console 都是正式数据源，不再有 demo 假数据。
4. menu / shortcut / context / toolbar 已共用动作层。
5. undo / selection / runtime mode / active route 有清晰 owner。
6. 没有为了赶进度堆出来的 panel-local hack。

8. 并行拆分建议

可以并行，但必须分主从关系：

主依赖顺序

1. Phase 1 应用层骨架
2. Phase 2 动作与命令层
3. Phase 3/4/5/6 面板业务回接
4. Phase 7 viewport 主链
5. Phase 8/9 生命周期与总收口

可并行子线

1. Core/Managers/Context 收敛
2. Actions/Commands 迁移
3. Hierarchy + SceneManager 接回
4. Project + ProjectManager 接回
5. Inspector + ComponentEditors 接回
6. Console + tests/UI/Editor 回归补齐

说明：

• Viewport 尽量单独作为高风险主线，不和别的大改混在一起。
• 一旦并行子线发现 XCEditor 基础问题，优先暂停子线、回底层修复。

9. 立即执行顺序

当前建议的第一批执行顺序是：

1. 先收敛 new_editor 应用层骨架与目录边界。
2. 立刻建立新的 EditorContext / Managers / Workspace。
3. 然后先接 Hierarchy 和 Project 的真实数据源，因为这两块当前已有可见 UI 外壳。
4. 再接 Inspector 与 Console。
5. 最后接 Scene/Game viewport 与运行模式主链。

原因：

• Hierarchy / Project 已经有可见壳层，最适合先把产品语义接回来。
• Viewport 风险最高，应在应用层骨架稳定后单独推进。

10. 当前需要归档的旧计划

本轮建议归档到 docs/plan/used/ 的文档：

• XCEditor_Dock统一与Tab拖拽停靠收口计划_2026-04-10.md

保留在 docs/plan/ 的参考文档：

• Editor架构说明.md

原因：

• 前者属于阶段性基础层收口计划，主线已被当前迁移重建计划替代。
• 后者不是过期计划，而是旧 editor 的分层参考资料，后续迁移时仍需频繁对照。