XCEngine/docs/plan/XCUI完整架构设计与执行计划.md

# XCUI完整架构设计与执行计划

## 1. 文档定位

本文档定义 `XCUI` 的完整目标、分层架构、核心数据模型、运行机制、编辑器集成方式、迁移策略与执行计划。

`XCUI` 的定位不是“再做一个游戏内 UI 模块”，而是：

- XCEngine 的统一 UI 平台
- Editor 与 Runtime 共用的一套 UI Core
- 面向 AI Coding Agent 友好的 UI 开发体系
- 未来替代当前 editor 中 ImGui 主路径的正式方案

本文档默认服务于两个目标：

- 给后续实现提供明确蓝图
- 给 AI / 人类开发者提供稳定的架构边界

---

## 2. 背景与问题定义

当前 XCEngine 的 editor 已经形成了较清晰的主链：

- `RHI -> Rendering -> Editor Viewport -> AssetDatabase/Library -> Mono Scripting`

但 UI 层目前仍以 ImGui 即时模式为主，存在以下问题：

- 过程式 UI 代码体量大，面板文件容易膨胀
- 状态、布局、事件、业务逻辑容易缠绕在一起
- AI 不擅长稳定修改大段 imperative native UI 代码
- 现有 UI 逻辑难以沉淀为资源化、组件化、可热重载的体系
- editor UI 和未来 runtime UI 之间没有统一技术底座

### 2.1 当前问题不是“有没有 UI”，而是“UI 的组织方式不适合 AI”

当前 editor 已经有大量真实能力：

- Hierarchy
- Project
- Inspector
- Console
- Scene/Game Viewport
- Play Mode / Scripting / Asset 工作流

因此，XCUI 的目标不是重做 editor 后端能力，而是重做 UI 前端组织方式。

### 2.2 为什么不能直接照抄 Unity UI

不采用 Unity 风格 UI 的主要原因：

- `RectTransform / Anchor / Pivot / Canvas` 模型复杂度高
- 组件化表达不够直接
- inspector/custom editor 体系过重
- 对 AI 来说，状态流和布局意图不够清晰
- editor UI 与 runtime UI 分裂严重

### 2.3 为什么也不直接采用浏览器/WebView路线

本文档明确不采用“真正 HTML/CSS/JS + 浏览器内核”作为主路线，原因如下：

- 这会把问题从 UI 架构转移成浏览器宿主工程
- 会引入大量与引擎无关的复杂性
- 不利于 editor/runtime 共享同一套 native UI Core
- 会让 viewport、输入、宿主生命周期复杂化

XCUI 借鉴前端范式，但不引入浏览器运行时。

---

## 3. XCUI的总体目标

### 3.1 核心目标

XCUI 必须同时满足以下目标：

1. AI 能稳定理解、生成、修改 UI
2. Editor 与 Runtime 共用统一 UI Core
3. UI 可资源化、可热重载、可调试
4. 复杂度显著低于 Unity UI
5. 能逐步替代 editor 当前的 ImGui 主路径
6. 能承载 editor 级别的面板、布局、属性表单、树控件和 viewport 壳层

### 3.2 非目标

XCUI 明确不做以下事情：

- 不做浏览器
- 不做 DOM
- 不做完整 CSS cascade
- 不复刻 Unity UGUI / UI Toolkit
- 不把普通 UI 节点做成 Scene GameObject
- 不在 V1 做完整 world-space UI 体系

### 3.3 成功标准

XCUI 成功的标志不是“能画几个按钮”，而是：

- editor 核心公共边界中不再暴露 ImGui 类型
- Inspector / Project / Console / Hierarchy 至少 4 个核心面板迁移到 XCUI
- Scene/Game 使用 `ViewportSlot` 承载视口纹理和输入边界
- `.xcui/.xctheme/.xcschema` 支持热重载
- runtime HUD/menu 可以基于同一套 UI Core 构建
- editor 最终可不依赖 ImGui 运行主 UI

---

## 4. 总体架构

### 4.1 分层结构

XCUI 采用如下四层架构：

```text
Editor / Runtime Application
        |
        v
XCUI Views / ViewModels / Commands
        |
        v
XCUI Core
(State / Binding / Layout / Style / Input / Render / Widgets)
        |
        v
Backend
(ImGui Adapter -> 过渡期)
(Native RHI Renderer -> 最终目标)
```

### 4.2 在仓库中的推荐目录

```text
engine/
  include/XCEngine/UI/
    Core/
    State/
    Binding/
    Layout/
    Style/
    Input/
    Render/
    Text/
    Widgets/
    Markup/
    Schema/
    Runtime/
    DevTools/
  src/UI/

editor/
  src/XCUIHost/
  src/XCUIViewModels/
  src/XCUIAdapters/
  src/XCUICommands/
  ui/views/
  ui/themes/
  ui/schemas/

project/
  Assets/UI/
  Assets/Themes/
  Assets/Schemas/

tests/
  UI/
```
### 4.2.1 当前执行覆盖规则（2026-04-06）

以下规则在当前阶段覆盖本节中所有与目录落点有关的模糊表述：

- `editor/` 当前视为 ImGui 版本冻结区；在 XCUI editor shell 成熟前，不直接在该目录中推进替换开发。
- `tests/UI` 是当前 `Editor` 基础层的唯一实验场；所有基础能力验证、交互试验、状态流检查都必须优先放在 `tests/UI/Editor/unit` 与 `tests/UI/Editor/integration`。
- `new_editor/` 当前不作为试验场；它承载 `Editor` 基础层库与临时宿主骨架，禁止往其中追加业务面板、临时验证逻辑或与 `tests/UI` 重复的实验入口。
- `new_editor/` 当前目录结构按库式 `Editor UI` 形态维护：公共头放在 `include/XCEditor/Core|Widgets`，实现放在 `src/Core|Widgets`，宿主代码放在 `app/Application.*|Host/*`，不再把库层与宿主层揉成一套业务目录。
- `engine/UI` 当前继续只放 `Core / Runtime / shared` 部分，不再继续沉积 editor-only 代码。
- 等 `Editor` 基础层在 `tests/UI/Editor` 中稳定收口后，再规划从 `new_editor/` 迁入正式 `editor/` 的接入阶段，而不是继续在旧 `editor/` 与 `new_editor/` 之间双线推进。

#### 当前过渡期目录（自 2026-04-06 起执行）
```text
engine/
  include/XCEngine/UI/
  src/UI/
  # 只承载 Core / Runtime / shared UI 基础层

new_editor/
  include/XCEditor/
  src/
  app/
  ui/
  # Editor 基础层库 + 临时宿主骨架；不承载测试验证入口与业务面板

editor/
  # 当前 ImGui 版本冻结，不作为本阶段 XCUI 主实现目录

tests/
  UI/
  # XCUI 验证体系入口，不承载正式 editor 实现
```

### 4.3 模块划分

| 模块 | 职责 |
|---|---|
| `UI/Core` | UI 树、节点生命周期、失效传播、实例管理 |
| `UI/State` | 响应式状态、派生状态、store |
| `UI/Binding` | 数据绑定、命令绑定、viewmodel 适配 |
| `UI/Layout` | 测量、布局、容器规则 |
| `UI/Style` | 样式、主题 token、状态样式 |
| `UI/Input` | 指针、键盘、焦点、拖拽、快捷键 |
| `UI/Render` | draw list、渲染命令、后端抽象 |
| `UI/Text` | 字体、文本测量、IME、换行 |
| `UI/Widgets` | 基础控件和复合控件 |
| `UI/Markup` | `.xcui` 解析、编译、热重载 |
| `UI/Schema` | inspector/form schema |
| `UI/Runtime` | runtime screen/player/系统接入 |
| `UI/DevTools` | UI 树、layout、style、binding 调试工具 |

---

## 5. 核心设计原则

### 5.1 Retained-mode，而不是即时模式

XCUI 的正式形态是 retained-mode：

- UI 树长期存在
- 状态变化驱动局部更新
- 布局与绘制是独立阶段
- 不以“每帧手写过程式调用”作为主路径

### 5.2 声明式优先，代码式保底

XCUI 应同时支持：

- `Markup-first`
- `Code-first`

但主路径必须是 `Markup-first`，原因如下：

- 树状 UI 更适合 AI 生成和修改
- 结构、样式、行为边界更清晰
- 更适合热重载和资源化

### 5.3 单向数据流

强制采用：

- `State -> View`
- `UI Event -> Command -> Domain -> State Update -> View Refresh`

禁止：

- Widget 直接到处改业务对象
- UI 节点绕过命令系统随意操作 `SceneManager`
- 控件内部偷偷维护大量业务状态

### 5.4 Viewport 是宿主，不是普通控件

`Scene/Game Viewport` 必须视为特殊宿主节点：

- 它承载纹理
- 它定义输入边界
- 它连接 viewport 服务
- 它不负责普通 UI 布局逻辑之外的 gizmo/picking/世界 overlay

### 5.5 Schema 优先于硬编码 Inspector

对于 Inspector、Material、ImportSettings、Script 字段：

- 默认走 schema + auto form
- 只有少量复杂控件才走 custom section

目标是让“新增/修改一个属性面板”更多是改 schema 和 view，而不是继续写大块 imperative C++。

---

## 6. 编程模型

### 6.1 View / ViewModel / Command

#### View

职责：

- 描述结构
- 描述布局
- 描述样式
- 建立绑定
- 发出命令意图

不负责：

- 直接修改业务对象
- 直接处理 domain 规则

#### ViewModel

职责：

- 订阅 editor/runtime 的 domain state
- 整理成 UI 可绑定状态
- 组织派生状态
- 绑定命令和事件

#### Command

职责：

- 把 UI 意图翻译成稳定的业务命令
- editor 命令落到现有 `Commands::*`
- runtime 命令落到游戏 UI action handler

### 6.2 推荐命令命名

```text
Editor.Entity.Create
Editor.Entity.Delete
Editor.Entity.Rename
Editor.Project.Open
Editor.Project.Refresh
Editor.Scripting.Rebuild
Editor.Layout.Reset
Runtime.Menu.Open
Runtime.Menu.Close
Runtime.HUD.Toggle
```

### 6.3 绑定表达式约束

XCUI 不引入完整脚本表达式引擎。

Markup 中支持的表达式范围只建议包括：

- `bind`
- `if`
- `not`
- `equals`
- `foreach`
- `command`

这能保证：

- AI 易于生成
- 编译器易于诊断
- runtime 复杂度可控

---

## 7. 文件格式设计

### 7.1 `.xcui`

用于描述 UI 视图树。

示例：

```xml
<View id="InspectorPanel" vm="InspectorPanelVM">
  <Column class="panel inspector">
    <Toolbar>
      <Text class="panel-title" text="Inspector" />
      <Spacer />
      <Button text="Add Component" command="Editor.Component.Add" />
    </Toolbar>

    <Scroll>
      <If when="{bind selection.hasEntity}">
        <AutoForm source="{bind selection.entity}" schema="schemas/entity_inspector.xcschema" />
      </If>

      <If when="{bind selection.hasMaterial}">
        <Use view="views/material_inspector.xcui" />
      </If>

      <If when="{not selection.hasAny}">
        <EmptyState title="No Selection" />
      </If>
    </Scroll>
  </Column>
</View>
```

### 7.2 `.xctheme`

用于定义 theme token 和 widget style。

建议结构：

- tokens
- widget defaults
- class styles
- state overrides

### 7.3 `.xcschema`

用于定义属性表单、自动 inspector 渲染规则。

示例：

```xml
<Schema type="TransformComponent">
  <Field path="position" widget="Vector3Field" label="Position" step="0.1" />
  <Field path="rotation" widget="EulerField" label="Rotation" step="1.0" />
  <Field path="scale" widget="Vector3Field" label="Scale" reset="1,1,1" />
</Schema>
```

### 7.4 编译产物

导入后建议生成 artifact：

- 视图蓝图二进制
- style table
- schema table
- 依赖信息
- source mapping

这样可以统一进入 `AssetDatabase/Library` 工作流。

---

## 8. 状态系统设计

### 8.1 状态类型

XCUI 状态分为四层：

1. `Domain State`
2. `ViewModel State`
3. `Local UI State`
4. `Persistent UI State`

#### Domain State

由 editor/runtime 业务层维护，例如：

- 当前选中实体
- 当前项目目录
- Play Mode 状态
- Console 日志集合

#### ViewModel State

由 VM 派生，例如：

- `selection.hasEntity`
- `selection.hasMaterial`
- `console.filteredEntries`

#### Local UI State

局部交互态，例如：

- splitter 比例
- 树节点展开态
- 输入框草稿值
- hover/pressed/active

#### Persistent UI State

持久化状态，例如：

- dock 布局
- tab 顺序
- 列宽
- 面板可见性
- 最近搜索关键词

### 8.2 状态基元

建议核心状态基元：

- `UISignal<T>`
- `UIComputed<T>`
- `UIListModel<T>`
- `UIStore`

目标：

- 局部变化只传播到依赖它的 subtree
- 不引入全局巨型 store 的维护负担
- 保持 VM 的表达简单明确

### 8.3 失效传播

建议失效类型：

- `StructureDirty`
- `StyleDirty`
- `LayoutDirty`
- `PaintDirty`
- `DataDirty`

传播原则：

- 数据变化优先局部传播
- 布局变化只回溯到需要重排的祖先
- 样式变化只重建受影响节点的 resolved style
- 绘制变化只重建对应 draw list 片段

---

## 9. ViewModel 设计

### 9.1 基本形态

示例：

```cpp
class InspectorPanelVM : public UIViewModel {
public:
    UISignal<bool> hasSelection;
    UISignal<std::string> title;
    UISignal<EntityInspectorModel> entity;
    UISignal<MaterialInspectorModel> material;

    UICommandRef addComponentCommand;
    UICommandRef rebuildScriptsCommand;

    void Attach(IEditorContext& context) override;
    void Detach() override;
};
```

### 9.2 ViewModel约束

ViewModel 只暴露：

- `Signal`
- `Computed`
- `ListModel`
- `CommandRef`
- DTO / ViewData

不要直接把这些暴露给 view：

- `GameObject*`
- `AssetItemPtr`
- `RHITexture*`
- `Scene*`

View 层应该看到的是“UI 友好的数据形态”，而不是业务层裸对象。

---

## 10. 布局系统设计

### 10.1 布局理念

XCUI 布局系统只做你需要的 80%：

- 易于理解
- 易于实现
- 易于 AI 生成
- 足够支撑 editor 和 runtime 主流场景

不追求浏览器级 layout feature completeness。

### 10.2 布局单位

建议支持：

- `px`
- `%`
- `auto`
- `fill`
- `fr`
- `content`

底层类型可定义为：

```cpp
enum class UISizeKind : uint8_t {
    Auto,
    Px,
    Percent,
    Fill,
    Fraction,
    Content
};
```

### 10.3 基础容器

V1 基础容器：

- `Row`
- `Column`
- `Grid`
- `Overlay`
- `Scroll`
- `Split`
- `Tabs`
- `DockHost`

### 10.4 基础布局属性

- `width`
- `height`
- `minWidth`
- `minHeight`
- `maxWidth`
- `maxHeight`
- `margin`
- `padding`
- `gap`
- `align`
- `justify`
- `clip`
- `aspectRatio`

### 10.5 关键规则

- 普通 UI 一律优先流式布局
- 绝对定位只允许在 `Overlay`
- SceneView 的世界空间 overlay 不走普通 UI 布局系统
- `DockHost` 属于 editor-only 高级布局容器

---

## 11. 样式与主题系统

### 11.1 样式模型

XCUI 采用：

- token
- widget type style
- class style
- id style
- state override

不采用完整 CSS cascade。

### 11.2 样式优先级

建议顺序：

1. theme 默认
2. widget 默认样式
3. class 样式
4. id 样式
5. inline style
6. state override

### 11.3 Token系统

建议 token 类型：

- color
- spacing
- radius
- border
- shadow
- font
- icon size
- duration
- z-layer

示例：

```text
color.bg.panel
color.bg.hover
color.text.primary
color.text.muted
color.border.soft
spacing.1
spacing.2
radius.sm
radius.md
font.ui
font.mono
```

### 11.4 样式表达约束

支持：

- widget type
- class
- id
- state

不支持：

- descendant selector
- sibling selector
- 复杂层层 cascade
- 通配复杂选择器

这是为了把复杂度压下来，保证 AI 和人类都容易维护。

---

## 12. 文本系统设计

文本系统必须从 V1 开始纳入正式设计。

### 12.1 V1 必须支持

- UTF-8
- 中文
- 字体 fallback
- 文本测量
- 自动换行
- 裁剪
- 单行输入
- 多行输入
- 选择/复制/粘贴
- IME

### 12.2 平台策略

Windows-first 阶段建议直接依赖平台文本输入能力处理 IME 与文本输入。

后续抽象为：

- `IUITextBackend`
- `UITextLayout`
- `UIFontAtlas`

### 12.3 风险提示

文本和输入法是 editor-grade UI 的硬门槛。
不能把它当成“后面再说”的附属模块。

---

## 13. 输入系统与焦点系统

### 13.1 输入事件类型

建议标准事件：

- `PointerMove`
- `PointerDown`
- `PointerUp`
- `PointerWheel`
- `Click`
- `DoubleClick`
- `DragStart`
- `DragMove`
- `DragDrop`
- `KeyDown`
- `KeyUp`
- `TextInput`
- `Shortcut`
- `FocusChanged`

### 13.2 输入分发模型

流程：

1. 命中测试得到 target
2. target 接收事件
3. 事件向上 bubble
4. drag 期间支持 capture
5. shortcut 基于 focus scope / command scope 分发

### 13.3 焦点模型

建议区分：

- `KeyboardFocus`
- `PointerHover`
- `PointerCapture`
- `ActiveTextInput`
- `FocusScope`
- `ModalScope`

### 13.4 与当前 editor 的关系

当前 `EditorActionRoute` 可在过渡期保留。
中期应逐步把动作路由并入：

- `FocusScope`
- `CommandScope`
- `ShortcutManager`

---

## 14. 渲染架构

### 14.1 渲染流程

```text
View Tree
 -> Layout Tree
 -> Paint Tree
 -> UIDrawList
 -> Render Backend
```

### 14.2 DrawList基元

V1 只做这些 primitive：

- filled rect
- rounded rect
- border
- line
- text
- image
- nine-slice image
- clip push/pop
- transform push/pop
- layer push/pop

### 14.3 后端划分

必须有两个后端：

1. `XCUIImGuiBackend`
2. `XCUIRHIRenderBackend`

#### ImGui Backend

定位：

- 过渡期后端
- 让 XCUI 先接入当前 editor

职责：

- 把 XCUI draw list 翻译为 ImGui draw list
- 把 ImGui 输入桥接为 XCUI 输入事件

#### RHI Native Backend

定位：

- 最终正式后端
- Editor/Runtime 共享

职责：

- 走 XCEngine 自己的 RHI/Rendering 链路
- 支持 D3D12/OpenGL/Vulkan

### 14.4 性能要求

必须尽早纳入：

- 文本布局缓存
- 图片 atlas
- style resolve cache
- virtualization
- clip batch 合并
- dirty subtree 重绘

---

## 15. Widget库设计

### 15.1 基础件

- `Text`
- `Icon`
- `Image`
- `Spacer`
- `Divider`
- `Button`
- `IconButton`
- `Toggle`
- `Checkbox`
- `Radio`
- `Input`
- `TextArea`
- `NumberInput`
- `Slider`
- `Dropdown`
- `ProgressBar`
- `TagChip`

### 15.2 布局件

- `Row`
- `Column`
- `Grid`
- `Overlay`
- `Scroll`
- `Split`
- `Tabs`
- `Panel`
- `Toolbar`
- `StatusBar`

### 15.3 数据件

- `ListView`
- `TreeView`
- `TableView`
- `VirtualList`
- `LogView`
- `Breadcrumb`
- `SearchBox`

### 15.4 字段件

- `BoolField`
- `IntField`
- `FloatField`
- `Vector2Field`
- `Vector3Field`
- `Vector4Field`
- `ColorField`
- `EnumField`
- `AssetField`
- `ObjectField`

### 15.5 Editor专用件

- `PropertyGrid`
- `AutoForm`
- `DockHost`
- `TabStack`
- `AssetGrid`
- `HierarchyTree`
- `ConsoleView`
- `ViewportSlot`

### 15.6 Runtime专用件

- `HUDLayer`
- `MenuStack`
- `Toast`
- `Dialogue`
- `ActionBar`

---

## 16. Schema驱动Inspector体系

### 16.1 设计原则

Inspector 不再以一个巨大 panel 文件承担所有逻辑。
应改为：

- `Reflection`
- `Schema`
- `AutoForm`
- `CustomSection`

### 16.2 Schema可表达内容

- label
- category
- widget type
- visible
- enabled
- tooltip
- range
- precision
- asset filter
- enum source
- reset value
- group
- custom renderer key

### 16.3 执行策略

- 默认能 auto form 的都 auto form
- Script 字段优先 schema 驱动
- Material/ImportSettings 优先 schema 驱动
- 复杂场景才使用 custom section

### 16.4 与当前项目的衔接

当前以下能力可直接成为 schema 后端基础：

- `ScriptComponentEditor` 的字段模型读取与写回
- Material inspector 的 render state / texture / shader 数据模型

---

## 17. Docking与Editor Shell

### 17.1 设计目标

XCUI 需要 editor-grade 布局能力，但不应复刻完整 IDE docking 复杂度。

### 17.2 节点类型

- `SplitNode`
- `TabStackNode`
- `PanelLeaf`

### 17.3 V1支持

- 左右/上下 split
- tab 切换
- tab 重排
- 面板隐藏/显示
- layout 持久化

### 17.4 V1不支持

- 全量浮动窗口系统
- 复杂多显示器浮窗
- 过重的 docking 动画和规则

### 17.5 Layout持久化

建议 layout 资源单独持久化为 `.xclayout`。

---

## 18. Viewport集成设计

### 18.1 设计原则

Scene/Game Viewport 必须作为特殊宿主节点存在，而不是普通 widget。

### 18.2 `ViewportSlot`职责

- 请求 viewport 纹理
- 确定可交互区域
- 接收输入边界
- 把纹理显示在 UI 布局中
- 与 ViewModel 协作渲染壳层工具栏和状态信息

### 18.3 `ViewportSlot`不负责

- gizmo 算法
- object picking 内核
- world overlay 生成
- scene outline pass

这些仍应保留在现有 viewport 子系统中。

### 18.4 公共接口改造

当前与 ImGui 耦合的 viewport 接口后续必须抽象为平台无关类型。

建议新增：

- `UITextureHandle`
- `UIPoint`
- `UISize`
- `UIRect`
- `ViewportFrame`

必须避免在 XCUI 和 editor 公共边界里继续出现：

- `ImTextureID`
- `ImVec2`

---

## 19. Runtime UI设计

### 19.1 基本模型

Runtime UI 建议采用：

- `UIScreenAsset`
- `UIScreenPlayer`
- `UISystem`

### 19.2 第一阶段范围

V1 runtime UI 只做：

- main menu
- pause menu
- HUD
- dialogue
- settings

默认只支持 screen-space UI。

### 19.3 后续扩展

V2 可考虑：

- world-space UI
- render-to-texture UI
- 3D anchor

但必须放到 core 稳定之后。

---

## 20. 资源与导入管线

### 20.1 新资源类型

建议注册：

- `.xcui`
- `.xctheme`
- `.xcschema`
- `.xclayout`

### 20.2 导入流程

1. 解析源文件
2. 做 schema / style / binding 验证
3. 编译为 blueprint artifact
4. 写入依赖清单
5. 支持热重载

### 20.3 诊断输出

编译器必须输出：

- 文件
- 行号
- 列号
- 错误码
- 简洁可读的错误信息

这是 AI 和人类能否高效修 UI 资源的关键。

---

## 21. DevTools设计

XCUI 必须内建 DevTools，而不是后补。

V1 必须具备：

- UI tree inspector
- layout bounds overlay
- style/token inspector
- focus chain viewer
- binding inspector
- command log
- event log
- invalidation overlay
- hot reload panel

没有 DevTools，XCUI 后期调试成本会迅速失控。

---

## 22. 测试策略

建议新增测试目录：

```text
tests/UI/Core/
tests/UI/Runtime/
tests/UI/Editor/
```

测试类型包括：

- 单元测试：signals/layout/style/schema
- 集成测试：VM + command routing
- 截图回归：控件和面板基线图
- 性能测试：大列表、树、文本布局
- 热重载测试：`.xcui/.xctheme/.xcschema`
- editor 回归：旧命令语义保持一致

---

## 23. 与当前工程的迁移策略

### 23.1 当前关键耦合点

后续迁移时，以下区域是重点：

- `Application` 中的 ImGui 初始化和 frame 驱动
- `ImGuiBackendBridge`
- `IViewportHostService` 中的 ImGui 类型
- `ViewportPanelContent` 中的 ImGui 交互表面和贴图逻辑
- `GameView` 输入桥中的 ImGui 键鼠采样
- `Layer::onImGuiRender()` / `LayerStack::onImGuiRender()`

### 23.2 迁移原则

- 不一次性推翻 editor
- 先把 ImGui 从“架构中心”降为“过渡后端”
- 先迁最能体现价值的业务面板
- 先迁 shell 和表单，不先动 scene gizmo 核心算法

### 23.3 推荐迁移顺序

1. `Console`
2. `Inspector`
3. `Project`
4. `Hierarchy`
5. `Dock shell`
6. `SceneView/GameView shell`
7. `Runtime HUD/Menu`

---

## 24. 详细执行计划

### Phase 0：边界清理

时间：2 周

目标：

- 把 ImGui 从 editor 公共接口中压回 adapter 层

任务：

- 定义 `UIPoint/UISize/UIRect/UITextureHandle`
- 改造 viewport 公共接口去掉 ImGui 类型
- 重构 GameView 输入桥接口
- 规划移除 `onImGuiRender` 的 engine-core 设计残留

退出标准：

- editor 业务边界不再暴露 ImGui 类型
- ImGui 主要停留在宿主和 adapter 层

### Phase 1：XCUI Core MVP

时间：3 周

目标：

- 建立可运行的 XCUI Core

任务：

- `UIRoot/UINode/UIView/UIViewInstance`
- `UISignal/UIComputed/UIStore`
- 失效系统
- `Row/Column/Overlay/Scroll/Split`
- `UITheme/UIStyleSet`
- `UIDrawList`
- 命中测试与焦点管理

退出标准：

- 独立 demo 可运行
- 按钮、输入框、滚动、splitter 可交互
- layout 单元测试通过

### Phase 2：ImGui过渡后端

时间：2 周

目标：

- 让 XCUI 在现有 editor 内先跑起来

任务：

- `XCUIImGuiRenderer`
- `XCUIImGuiInputAdapter`
- `XCUIHost`
- 最小调试 overlay

退出标准：

- 当前 editor 内可显示 XCUI demo panel
- 不影响现有 viewport 主链

### Phase 3：Markup与资源导入

时间：3 周

目标：

- 让 UI 进入资源化和热重载阶段

任务：

- `.xcui` 解析器
- `.xctheme` 解析器
- `.xcschema` 解析器
- blueprint artifact 编译
- dependency tracking
- hot reload

退出标准：

- 修改资源文件后 editor 热更新
- 编译错误能精确定位到行列

### Phase 4：Schema / PropertyGrid / Inspector

时间：4 周

目标：

- 正式打通 editor inspector 体系

任务：

- schema runtime
- `PropertyGrid`
- `AutoForm`
- Transform schema
- Material schema
- Script 字段 schema 适配
- `InspectorVM`

退出标准：

- Inspector 能替代常见字段编辑
- Material inspector 可用
- Script 字段编辑链路稳定

### Phase 5：Project / Console / Hierarchy

时间：4 周

目标：

- 迁移 editor 三大主工作流面板

任务：

- `VirtualList`
- `TreeView`
- `AssetGrid`
- `LogView`
- `SearchBox`
- `ProjectVM`
- `ConsoleVM`
- `HierarchyVM`

退出标准：

- Project/Console/Hierarchy 可日常使用
- 过滤、拖拽、选择稳定

### Phase 6：DockHost / Menu / Shortcut / Panel Shell

时间：4 周

目标：

- 让 XCUI 承担 editor shell

任务：

- `DockHost`
- `TabStack`
- layout persistence
- `MenuBar`
- `ContextMenu`
- `ShortcutManager`
- `PanelFrame`
- `StatusBar`

退出标准：

- editor shell 不再依赖 ImGui docking
- layout 可保存/恢复

### Phase 7：ViewportSlot 与 Scene/Game Shell

时间：3 周

目标：

- 迁移 Scene/Game 面板外壳

任务：

- `ViewportSlot`
- `SceneViewVM`
- `GameViewVM`
- XCUI 输入桥接
- 工具栏、状态条、壳层布局迁移

退出标准：

- Scene/Game 面板 UI 外壳由 XCUI 驱动
- viewport 内核仍复用原有系统

### Phase 8：RHI原生后端

时间：6 周

目标：

- 让 XCUI 成为真正 native UI renderer

任务：

- `XCUIRHIRenderBackend`
- 字体 atlas / 文本渲染
- 图像、clip、popup、tooltip
- 统一输入与焦点
- editor 主循环直接渲染 XCUI draw list

退出标准：

- editor 主 UI 可不依赖 ImGui
- XCUI 成为正式渲染路径

### Phase 9：Runtime UI

时间：4 周

目标：

- 让 XCUI 成为游戏运行时 UI 方案

任务：

- `UIScreenAsset`
- `UIScreenPlayer`
- runtime 输入桥接
- HUD/menu 示例
- 可选 C# wrapper

退出标准：

- runtime HUD/menu 正式运行
- editor/runtime 共用同一套 UI Core

---


## 24.1 当前执行优先级修正（2026-04-06）

近期执行顺序调整如下：

1. 冻结当前基于 ImGui 的 `editor/` 目录，不把它作为本阶段 XCUI 替换开发的主工作区。
2. 当前阶段所有 `Editor` 基础层实验、交互验证、状态流验证，一律放在 `tests/UI/Editor` 中完成。
3. `new_editor/` 不作为试验场；当前只允许维护 `Editor` 基础层库与宿主骨架，不往里面追加业务面板或验证逻辑。
4. 在具体 editor 面板之前，优先完成 editor shell 基础能力：
   - Splitter / pane resize
   - Tab strip
   - Workspace compose
   - Hierarchy / Inspector / Console 所需的 editor-only 基础件
5. `Runtime UI` 仍然是 XCUI 的长期目标，但在 editor shell 替换路径稳定之前，不作为当前主线。

### 24.2 Core当前阶段判断与Editor推进边界（2026-04-06）

当前判断：

- `Core` 第一阶段已经基本收口，可以继续推进 `Editor` 基础层。
- 但这不等于 `Core` 已经最终封板；后续推进 `Editor` 时，仍然可能暴露新的共享能力缺口。

执行硬规则：

- `Editor` 当前阶段只负责 editor shell、panel 生命周期、workspace 装配、menu/shortcut 这类 editor-only 上层能力。
- 凡是发现 `layout / input / style / text / render contract / shared widget` 等共享能力缺口，必须优先回补到 `Core` 或 shared UI 层。
- 禁止在 `Editor` 层硬写临时替代实现去绕过 `Core` 缺口；否则后面迁移到正式 editor 时会再次返工。
- `tests/UI/Editor` 是当前 `Editor` 基础层的唯一实验与验证入口；需要人工操作检查的内容，也必须做成这里的集成测试场景。
- `new_editor/` 当前不作为试验场，但作为 `Editor` 基础层库与临时宿主骨架存在；允许承载迁移必需的基础层代码，不允许堆业务面板或测试验证逻辑。
- `tests/UI/Editor` 当前只验证 `Editor` 基础壳层与状态流，不提前承担具体业务面板复刻。

### 24.3 Editor基础层当前推进顺序（2026-04-06）

在不提前进入业务面板的前提下，当前主线顺序固定为：

1. 完善 `Panel Registry / Descriptor`，让面板元数据、展示语义、默认能力声明先稳定。
2. 建立 `Workspace Session / Panel State` 装配层，明确 panel instance、visible/hidden、active、pinned 等状态归属。
3. 打通 `open / close / show / hide / activate` 的基础状态流，并让 tab 选择与 active panel 始终一致。
4. 先补 `tests/UI/Editor/unit` 对上述状态机与装配规则的覆盖，再补一个专注状态流的 `integration` 场景。
5. 上述基础层稳定后，再继续推进 `MenuBar / ShortcutManager / DockHost layout persistence`，最后才轮到具体业务面板迁移。
### 24.4 当前下一阶段主线（2026-04-06）
结合当前实现进度，下一阶段执行顺序补充固定为：

1. 先在 `tests/UI/Core` 回补共享 `popup / menu overlay primitive`，包括 `open/close`、anchor/placement、outside click dismiss、`Escape` dismiss、submenu path。
2. 再补 `popup overlay` 与现有 `focus / input / capture / shortcut scope` 的契约收口，先做 `unit`，再做一个只验证单场景的 `integration` exe。
3. 上述 Core 能力稳定后，再在 `tests/UI/Editor` 中推进 `MenuBar / MenuPopup / ContextMenu` 对这套 primitive 的复用，不在 `Editor` 层另写临时实现绕过 Core。
4. 最后继续 `TabStrip / DockHost shell / workspace compose` 的真实渲染、命中与状态联动，直到 `Editor shell` 基础层具备替换当前 ImGui shell 的必要能力。
## 25. 人力与节奏建议

若按 1 名主导工程师 + AI 辅助估算：

- `MVP`：10 到 14 周
- `editor 大部分面板迁移`：18 到 24 周
- `editor 基本脱离 ImGui`：24 到 32 周
- `runtime UI 接入`：额外 6 到 10 周

如果中途扩 scope 到以下内容，周期会明显拉长：

- world-space UI
- 复杂浮动窗口
- 动画系统
- 富文本编辑器
- 多平台文本后端一次性铺开

---

## 26. 主要风险与约束

### 26.1 主要风险

- 试图复刻 HTML/CSS，导致 scope 爆炸
- 过早做复杂 docking
- 低估文本输入和 IME
- Inspector 又重新退化成大块硬编码 C++
- 在 Core 未稳定时就推进 world-space UI
- 太早把 C# UI 脚本化纳入主路径

### 26.2 约束原则

- 不做完整 CSS
- V1 不做 world-space UI
- Docking 先做 split + tabs
- 表单优先 schema 化
- 先迁 shell，后动 viewport 内核
- C# 绑定放到后期

---

## 27. 里程碑定义

### Milestone A：XCUI Core 跑通

条件：

- Core MVP 完成
- ImGui 过渡后端可运行 demo
- `.xcui` 能加载静态界面

### Milestone B：Inspector体系迁移成功

条件：

- PropertyGrid + AutoForm 可用
- Transform/Material/Script 字段链路打通

### Milestone C：Editor主面板迁移完成

条件：

- Console/Inspector/Project/Hierarchy 迁移到 XCUI

### Milestone D：Editor Shell 脱离 ImGui Docking

条件：

- DockHost + Menu + Shortcut + PanelFrame 稳定

### Milestone E：Editor 主 UI 脱离 ImGui

条件：

- XCUI 原生后端可承担 editor 主界面

### Milestone F：Runtime UI 正式接入

条件：

- runtime HUD/menu 使用 XCUI
- editor/runtime 共用 UI Core

---

## 28. 最终拍板建议

如果按本文档执行，最终建议如下：

- 把 `XCUI` 定义为“引擎级统一 UI 平台”
- 先做 `Core + ImGui Adapter`
- 先迁 `Console / Inspector / Project`
- 中期完成 `DockHost + ViewportSlot`
- 后期完成 `RHI Native Backend`
- 最后把 runtime UI 全面接入

XCUI 的最终目标不是“拥有一套新 UI API”，而是让 XCEngine 的 UI 体系从现在的过程式宿主代码，演进成：

- 可组合
- 可资源化
- 可调试
- 可热重载
- 可由 AI 稳定维护
- 可同时服务 editor/runtime 的正式平台层

---

## 29. 当前结论

基于 XCEngine 当前的 editor、viewport、asset、scripting 结构，XCUI 是一条可行且值得投入的路线。

最合理的执行方式不是“一次性替掉 ImGui”，而是：

1. 先把 ImGui 降级为过渡后端
2. 用 XCUI 承担新的 panel/view/form 体系
3. 再逐步收回 editor shell
4. 最后完成原生 RHI UI 后端

这条路线既能保护现有主链不被打断，也能逐步把 UI 层从“AI 不友好的 native imperative 代码”演进为“AI 友好的声明式原生 UI 平台”。