xuanchi/XCEngine

Fork 0

Files

ssdfasd 8848cfd958 chore: checkpoint current workspace changes

2026-04-11 22:14:02 +08:00

33 KiB

Raw Blame History

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 必须同时满足以下目标：

AI 能稳定理解、生成、修改 UI
Editor 与 Runtime 共用统一 UI Core
UI 可资源化、可热重载、可调试
复杂度显著低于 Unity UI
能逐步替代 editor 当前的 ImGui 主路径
能承载 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 采用如下四层架构：

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 在仓库中的推荐目录

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-09）

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

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

当前过渡期目录（自 2026-04-09 起执行）

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 推荐命令命名

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 视图树。

示例：

<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。当前执行口径补充：.xctheme 的主适用范围是 Core / Runtime / shared。Editor 当前不以 .xctheme 解析作为样式主线。

建议结构：

tokens
widget defaults
class styles
state overrides

7.3 `.xcschema`

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

示例：

<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 状态分为四层：

Domain State
ViewModel State
Local UI State
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 基本形态

示例：

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

底层类型可定义为：

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 样式优先级

建议顺序：

theme 默认
widget 默认样式
class 样式
id 样式
inline style
state override

11.3 Token系统

建议 token 类型：

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

示例：

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 输入分发模型

流程：

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

13.3 焦点模型

建议区分：

KeyboardFocus
PointerHover
PointerCapture
ActiveTextInput
FocusScope
ModalScope

13.4 与当前 editor 的关系

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

FocusScope
CommandScope
ShortcutManager

14. 渲染架构

14.1 渲染流程

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 后端划分

必须有两个后端：

XCUIImGuiBackend
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.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 导入流程

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

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. 测试策略

当前正式验证入口固定为 tests/UI。Core / Runtime / Editor 三层都在该测试树下收口；new_editor 只承担未来产品宿主与装配冒烟，不承担当前基础层验证入口职责。

建议新增测试目录：

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 推荐迁移顺序

Console
Inspector
Project
Hierarchy
Dock shell
SceneView/GameView shell
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 可日常使用
过滤、拖拽、选择稳定

时间：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-09）

近期执行顺序调整如下：

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

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

当前判断：

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

执行硬规则：

Editor 当前阶段只负责 editor shell、panel 生命周期、workspace 装配、menu/shortcut 这类 editor-only 上层能力。
Core / Runtime 仍可继续走资源化路线；Editor 当前默认样式固定在代码层，不再围绕 Editor 主题解析扩展主线。
凡是发现 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）

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

完善 Panel Registry / Descriptor，让面板元数据、展示语义、默认能力声明先稳定。
建立 Workspace Session / Panel State 装配层，明确 panel instance、visible/hidden、active、pinned 等状态归属。
打通 open / close / show / hide / activate 的基础状态流，并让 tab 选择与 active panel 始终一致。
先补 tests/UI/Editor/unit 对上述状态机与装配规则的覆盖，再补一个专注状态流的 integration 场景。
上述基础层稳定后，再继续推进 MenuBar / ShortcutManager / DockHost layout persistence，最后才轮到具体业务面板迁移。

24.4 当前下一阶段主线（2026-04-06）

结合当前实现进度，下一阶段执行顺序补充固定为：

先在 tests/UI/Core 回补共享 popup / menu overlay primitive，包括 open/close、anchor/placement、outside click dismiss、Escape dismiss、submenu path。
再补 popup overlay 与现有 focus / input / capture / shortcut scope 的契约收口，先做 unit，再做一个只验证单场景的 integration exe。
上述 Core 能力稳定后，再在 tests/UI/Editor 中推进 MenuBar / MenuPopup / ContextMenu 对这套 primitive 的复用，不在 Editor 层另写临时实现绕过 Core。
最后继续 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”，而是：

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

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

33 KiB Raw Blame History Unescape Escape

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

1. 文档定位

2. 背景与问题定义

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

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

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

3. XCUI的总体目标

3.1 核心目标

3.2 非目标

3.3 成功标准

4. 总体架构

4.1 分层结构

4.2 在仓库中的推荐目录

4.2.1 当前执行覆盖规则（2026-04-09）

当前过渡期目录（自 2026-04-09 起执行）

4.3 模块划分

5. 核心设计原则

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

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

5.3 单向数据流

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

5.5 Schema 优先于硬编码 Inspector

6. 编程模型

6.1 View / ViewModel / Command

View

ViewModel

Command

6.2 推荐命令命名

6.3 绑定表达式约束

7. 文件格式设计

7.1 .xcui

7.2 .xctheme

7.3 .xcschema

7.4 编译产物

8. 状态系统设计

8.1 状态类型

Domain State

ViewModel State

Local UI State

Persistent UI State

8.2 状态基元

8.3 失效传播

9. ViewModel 设计

9.1 基本形态

9.2 ViewModel约束

10. 布局系统设计

10.1 布局理念

10.2 布局单位

10.3 基础容器

10.4 基础布局属性

10.5 关键规则

11. 样式与主题系统

11.1 样式模型

11.2 样式优先级

11.3 Token系统

11.4 样式表达约束

12. 文本系统设计

12.1 V1 必须支持

12.2 平台策略

12.3 风险提示

13. 输入系统与焦点系统

13.1 输入事件类型

13.2 输入分发模型

13.3 焦点模型

13.4 与当前 editor 的关系

14. 渲染架构

14.1 渲染流程

14.2 DrawList基元

14.3 后端划分

ImGui Backend

RHI Native Backend

14.4 性能要求

15. Widget库设计

15.1 基础件

15.2 布局件

15.3 数据件

15.4 字段件

15.5 Editor专用件

15.6 Runtime专用件

33 KiB

Raw Blame History

7.1 `.xcui`

7.2 `.xctheme`

7.3 `.xcschema`

18.2 `ViewportSlot`职责

18.3 `ViewportSlot`不负责