# MetaCore UI 编辑与运行时 UI 工作流设计

生成时间：2026-03-28  
状态：草案  
范围：M4 UI、持久化与打包循环

## 目的

这份文档用于明确 MetaCore 第一阶段 UI 系统应该做到什么程度，以及 UI 编辑、UI 资源、运行时 UI 三者之间的关系。

目标不是一步到位做出 Unity UGUI 或 UI Toolkit 的完整等价物，而是先建立一套足够支撑工业数字孪生项目的基础 UI 工作流。

它要解决的问题包括：

- 第一阶段 UI 系统到底是“调试叠层”还是正式项目 UI
- UI 应该如何被编辑
- UI 资源如何保存
- UI 如何进入运行时
- UI 如何与场景对象和 RuntimeData 建立关系

## 结论先说

MetaCore 第一阶段的 UI 系统应明确定位为：

**可用于搭建工业三维应用静态界面和基础交互界面的正式项目 UI 工作流**

它不是：

- 只给编辑器自己用的 ImGui 面板
- 只给调试用的运行时 overlay
- 一套完整的大而全前端框架

第一阶段只要先把下面这条链做顺就够了：

```text
创建 UI 资源
  -> 在编辑器中组织面板层级
    -> 配置文本/图片/按钮/布局
      -> 挂到项目或场景
        -> Player 运行时正确显示
          -> 可做基础状态展示与简单交互
```

## 为什么 UI 是第一阶段基础能力

工业数字孪生项目的交付不只是 3D 场景。

真正交付时几乎一定会需要：

- 顶部标题栏
- 左右信息面板
- 状态文本
- 设备详情卡片
- 告警提示
- 操作按钮
- 图标和图片

如果没有稳定 UI 工作流，项目最后一定会退化成：

- 场景里有模型
- 但没有正式业务界面

这就不算可交付引擎。

## 当前代码基础判断

当前仓库里已经有：

- 基于 ImGui 的编辑器 UI
- Inspector / Hierarchy / Console 等编辑器面板

但这不等于已经有项目 UI 系统。

当前真正缺的是：

- 正式的 UI 资源模型
- 运行时 UI 组件体系
- UI 编辑工作流
- UI 与项目/场景的关系
- UI 在 Player 中的加载与显示

因此第一阶段必须把“编辑器面板框架”和“项目运行时 UI 系统”明确分开。

## 第一阶段 UI 系统定位

第一阶段建议明确分成两套概念：

### 1. 编辑器 UI

这部分继续使用当前编辑器自己的 UI 技术栈，用于：

- Hierarchy
- Project
- Inspector
- Console
- Runtime 面板

这不是项目交付用 UI。

### 2. 项目运行时 UI

这是用户用 MetaCore 制作数字孪生项目时真正需要的 UI 系统，用于：

- 顶部/侧边面板
- 状态栏
- 文本信息
- 图片和图标
- 按钮
- 基础交互界面

后续讨论“UI 编辑功能”时，默认指的是这一套。

## 第一阶段设计目标

第一阶段 UI 工作流要满足：

- 用户能创建正式 UI 资源
- 用户能编辑 UI 层级
- 用户能配置基础 UI 元素
- 用户能把 UI 作为项目内容保存
- Player 能加载并显示 UI
- UI 能承载数字孪生最基本的信息展示和操作入口

## 第一阶段范围

### 必须支持

- UI 文档或 UI 资产
- UI 根节点
- 面板
- 文本
- 图片
- 按钮
- 基础布局
- 运行时加载与显示

### 推荐支持

- 可见性开关
- 锚点与对齐
- 简单层级重组
- 基础样式属性

### 可以后置

- 复杂动画
- 自适应布局高级特性
- 富文本
- 数据表格系统
- UI 状态机
- 可视化脚本逻辑

## 推荐 UI 资源模型

第一阶段建议正式引入：

- `UiDocument`
- `UiNode`
- `UiStyle`

### UiDocument

负责保存：

- UI 名称
- 根节点列表
- 默认分辨率或参考尺寸
- 画布配置

### UiNode

第一阶段建议统一节点模型，节点通过 `Type` 区分：

- `Panel`
- `Text`
- `Image`
- `Button`

每个节点至少应有：

- `Id`
- `Name`
- `Type`
- `ParentId`
- `Children`
- `RectTransform`
- `Style`
- `Visible`

### RectTransform

第一阶段建议至少包含：

- `AnchorMin`
- `AnchorMax`
- `Pivot`
- `Position`
- `Size`

不要一开始就过度简化成只有绝对位置。

因为工业界面里：

- 顶栏
- 左面板
- 右面板
- 底栏

都强依赖基本锚点布局。

### Style

第一阶段建议做最小样式集合，例如：

- 背景颜色
- 文本颜色
- 字体大小
- 图片资源引用
- 边距
- 对齐方式

## 第一阶段推荐节点类型

### Panel

用于：

- 容器
- 背景区域
- 信息卡片
- 布局分组

### Text

用于：

- 标题
- 状态文本
- 标签
- 数值显示

### Image

用于：

- 图标
- Logo
- 状态图片

### Button

用于：

- 基础交互入口
- 切换页面
- 打开/关闭面板
- 简单控制命令

第一阶段 Button 不需要做成复杂事件系统，但至少要有：

- 点击事件入口
- 可与后续逻辑系统连接的绑定点

## UI 编辑工作流建议

第一阶段推荐的 UI 编辑工作流不要太复杂，但必须正式存在。

### 建议的最小编辑器形态

- 左侧：UI 层级树
- 中间：UI 预览区域
- 右侧：当前节点 Inspector

这和 Scene 编辑工作流保持一致，学习成本最低。

### 第一阶段必须支持的编辑动作

- 创建 Panel/Text/Image/Button
- 删除节点
- 重命名节点
- 拖拽重排父子级
- 修改 RectTransform
- 修改基础样式
- 选择资源

### 推荐支持

- 复制节点
- 多选节点
- 对齐辅助线

## UI 与项目/场景的关系

第一阶段建议明确：

- UI 作为项目资源存在
- Scene 可以引用一个或多个 UI 文档
- Player 启动后加载 Scene 时，再加载对应 UI

### 不建议的做法

不要把 UI 直接塞进 Scene 文档本体里做成内嵌大对象。

更合理的做法是：

- Scene 引用 `UiDocumentAssetGuid`

这样好处是：

- UI 可以复用
- UI 可单独编辑
- UI 可单独保存和版本化

## UI 与 RuntimeData 的关系

这是数字孪生方向非常关键的一点。

第一阶段建议明确分层：

### UI 资源层

定义界面长什么样。

### UI 运行时层

负责显示节点、接收输入、刷新显示内容。

### 数据绑定层

后续可让 RuntimeData 驱动：

- Text 内容
- Visible
- Image 状态
- 颜色

但第一阶段不要反过来让 RuntimeData 定义 UI 数据结构。

也就是说：

- 先把 UI 工作流做稳
- 再把 RuntimeData 挂进 UI

## 第一阶段运行时能力

Player 至少应能：

- 加载一个或多个 UiDocument
- 构建 UI 节点树
- 正确显示 Panel/Text/Image/Button
- 处理最基础点击输入
- 与场景渲染共存

### 第一阶段不要求

- 完整输入系统生态
- 页面导航框架
- 表单系统
- 动画系统

## Inspector 建议

### 对 UI 节点的 Inspector

第一阶段至少应支持：

- 名称
- 类型
- Visible
- RectTransform
- Style 基础字段

### 对 Text 节点

至少支持：

- 文本内容
- 字体大小
- 颜色
- 对齐

### 对 Image 节点

至少支持：

- 图片资源
- Tint
- PreserveAspect

### 对 Button 节点

至少支持：

- 文本标题或子节点文本
- 可点击状态
- 基础点击动作入口

## 推荐实现顺序

建议按下面顺序推进：

1. 定义 `UiDocument / UiNode / UiStyle`
2. 定义最小 `RectTransform`
3. 打通 UI 资源保存与加载
4. 建立 UI 层级树与 Inspector
5. 建立运行时基础显示
6. 支持 Scene 引用 UI 文档
7. 再补基础交互和数据驱动入口

## 第一阶段 Definition of Done

下面这些成立时，才能认为第一阶段 UI 工作流真正可用：

- 用户能创建 UI 文档
- 用户能创建 Panel/Text/Image/Button
- 用户能编辑 UI 层级与基本属性
- UI 文档可保存并重新打开
- Scene 或项目能引用 UI 资源
- Player 运行时能显示 UI
- UI 能承载数字孪生最基本的状态展示和操作入口

## 与整体引擎路线的关系

这份文档对应的是第一阶段主线中的：

- 项目与内容工作流
- 场景与对象工作流
- UI 工作流

它的位置应当在：

- 模型导入
- 场景编辑
- 材质与光照

之后，且明显先于：

- 更复杂的 RuntimeData 扩展
- VR 训练 UI 工作流
- 浏览器嵌入产品化

## 最终建议

第一阶段最合理的 UI 路线不是：

- 继续把项目 UI 混在编辑器 ImGui 里
- 也不是一口气做成完整前端框架

而是：

**先建立一套正式的项目运行时 UI 资源、编辑和显示闭环，让数字孪生项目至少具备“场景 + 界面 + 基础交互”三件套。**

只有这样，MetaCore 第一阶段才像一个可用于开发工业三维应用的真正引擎，而不是只有 3D 场景能力的半成品。