MetaCore/docs/designs/metacore-ui-workflow-design.md

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
• 一套完整的大而全前端框架

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

创建 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 场景能力的半成品。