DreamGUI
核心概念

控件模型

UDreamWidget 是什么 —— 一个携带矩形、锚点和轴心的 UObject,挂着视觉、布局、槽和行为,排列成一棵树 —— 外加渲染变换、不透明度与可见性,以及它与 UMG 在尺寸上的差异。

DreamGUI 中的控件是一个 UDreamWidget:一个带矩形、轴心和锚点的 UObject,排列成一棵树,由 画布 绘制,后者会把整棵树尽可能合批成最少的绘制调用。这是 Unity 的 uGUI 形态,而非 Slate 的形态。它不是 Actor,也不是 Actor 组件;其背后没有 SWidget,因此 UMG 的任何控件、样式或绑定都不适用。

控件本身不绘制任何东西,也不排列任何东西。它绘制什么、如何排列子级、父级把它放在哪里、它运行什么逻辑,都由它携带的子对象决定 —— 用 ConstructWidget 的注释里的话说,"panel" 在这里是一个子对象,而不是一个单独的类。

控件由什么组成

部分属性 / 入口决定什么
矩形AnchorData(FDreamUIAnchorData)相对父级的位置和大小
视觉Visual(UDreamVisual),每个控件至多一个绘制什么
布局容器LayoutContainer(UDreamLayoutContainer)如何排列子级
自身布局LayoutSelf(UDreamLayoutSelf)自身的尺寸规则:宽高比、间隔器
面板槽PanelSlot(UDreamPanelSlot)父级的面板如何放置它
行为组件数组:AddComponent、GetComponent、GetComponents逻辑:按钮、画布、导航作用域……
子级GetChildren、AddChild、SetParent树

在 .dui 中,各部分很容易区分:节点类型是视觉(Text、Image)或布局容器(VerticalBox),+ Class { } 挂载行为或容器,@slot 行则是父级面板对该节点的处理方式。

Widget Root {
    // All four anchors on the parent's corners, no inset: fills the parent at any resolution
    AnchorData.AnchorMin = (0, 0)
    AnchorData.AnchorMax = (1, 1)
    AnchorData.SizeDelta = (0, 0)

    Widget Card {
        // Anchored to one point, the parent's centre: SizeDelta is its size, AnchoredPosition the pivot's offset from the anchor (y up)
        AnchorData.AnchorMin = (0.5, 0.5)
        AnchorData.AnchorMax = (0.5, 0.5)
        AnchorData.SizeDelta = (420, 220)
        AnchorData.AnchoredPosition = (0, 40)

        // A visual: a backdrop that fills the card
        Image Backdrop {
            Brush.TintColor = #1B1E26FF
            AnchorData.AnchorMin = (0, 0)
            AnchorData.AnchorMax = (1, 1)
            AnchorData.SizeDelta = (0, 0)
        }

        // A behaviour: a plain widget carrying the button behaviour
        Widget Confirm {
            AnchorData.SizeDelta = (160, 44)
            + UIButton { TransitionType = None }
            Text Label { Text = "OK" }
        }
    }
}

矩形:锚点、轴心和尺寸

FDreamUIAnchorData 有五个字段,默认值是一个锚定在父级中心的 100 × 100 方块:

字段默认值含义
AnchorMin / AnchorMax(0.5, 0.5)父级矩形中的两个归一化点。在某个轴上相等时,控件钉在该轴上的一个点;不等时则沿该轴拉伸
SizeDelta(100, 100)钉在某个轴上时为尺寸;在拉伸轴上则为超出锚点跨度的尺寸 —— 0 正好贴合,负值表示内缩
AnchoredPosition(0, 0)轴心相对锚点的偏移
Pivot(0.5, 0.5)控件自身矩形中的归一化点,(0, 0) 为左下,(1, 1) 为右上

坐标 y 轴向上:Pivot、RenderTransformPivot 和 PerspectiveOrigin 都把原点放在左下角,与 UMG 的左上角原点不同 —— 这是有意为之,因为插件内部的一致比与其他引擎的一致更重要。

运行时每个字段都有对应的 setter:SetAnchorMin、SetAnchorMax、SetAnchoredPosition、SetSizeDelta、 SetPivot,以及面向结果的 SetWidth、SetHeight 和 SetAnchorOffset(拉伸控件的四条边距离)。每个也有对应的补间 —— AnchoredPositionTo、SizeDeltaTo、WidthTo、HeightTo —— 返回一个 UDreamTweener (见动画)。

RelativeLocation 也可以设置,但它的 setter 会重新计算锚点并请求父级重新布局;而 .dui 只写 AnchorData,因此同一位置永远不会被写两次。

盒子优先:与 UMG 在尺寸上的差异

这一差异是结构性的而非外观性的,在决定采用哪一种之前值得了解:

UMG / SlateDreamGUI
控件SWidget,保留模式的 Slate组件式树中的一个 UObject
尺寸内容决定:控件的尺寸就是其期望尺寸盒子优先:你编写一个矩形,内容在其中排列
文本盒子随文本增长文本在盒子中对齐,可能溢出盒子
定位相对槽位锚点 + 轴心,与分辨率无关
复用Widget Blueprint 子类化Widget Blueprint 子类化,外加用于内容的命名槽位
世界中WidgetComponent,一个渲染的四边形一种一等的渲染模式

文本那一行最让人意外。UMG 的 TextBlock 不会溢出,因为它的盒子由文本推导而来。而这里盒子是编写的,因此文本可以溢出盒子,也就有了 UMG 不需要的控件 —— Margin、 LineHeightPercentage、WrapTextAt 和 Best Fit;见文本。

盒子优先并不意味着没有内容尺寸。一旦控件位于面板中,面板会询问它想要多大(GetDesiredSize),并把排列后的矩形写回它的 AnchorData。视觉以负数回答该问题时表示弃权,此时使用编写的矩形;0 是一个真实的回答。完整规则见布局。

视觉:控件绘制什么

视觉(UDreamVisual)是其控件的子对象,每个控件至多一个。没有视觉的控件就是一个矩形 —— Widget 中的 .dui —— 这正是纯容器的形态。每个视觉都有 Color(sRGB,可在 Sequencer 中打关键帧)、bRaycastTarget 和 RaycastType(Rect、Mesh、VisiblePixel、Custom)。

除非另行说明,否则视觉上会开启 bRaycastTarget,但有一个例外:UDreamText 默认不是射线检测目标,因为 UMG 的 TextBlock 不可命中测试。文本大多只是覆盖在其他内容之上的标签,而如果标签本身是目标,它就会抢走其下方控件的悬停和点击。如果文本本身就是需要按下的对象,请写 bRaycastTarget = true。在默认值更改之前保存的文本会保留保存时所用的 true。bRaycastTarget 属于视觉,因此普通的 Widget 节点没有它(在那里写它是错误:DUI5002、指明一个具有它的节点类型,或 DUI4001);要让控件退出命中测试,请在其上写 Raycastable = Disabled,其子级会通过 Inherit 遵循这一点。

.dui 标签类模块绘制
TextUDreamTextDreamGUI文本;见文本
ImageUDreamImageDreamGUI一个图像 brush;Tiled 在每个完整行中重复整幅图像,并裁剪最后不完整的一行
RectBlockUDreamRectBlockDreamGUI程序化块:圆角、主体、边框、内外阴影,主体和边框可选渐变
Sprite / TextureUDreamSprite / UDreamTextureDreamGUI一个图集精灵 / 整张纹理
EmptyUDreamVisualEmptyDreamGUI不绘制任何东西,但接收射线检测
Ring / Polygon / PolygonLineUDreamRing / UDreamPolygon / UDreamPolygonLineDreamGUIExtensions一个环、一个多边形、一个多边形描边
ShapeUDreamShapeDreamGUIExtensions通过任意点的填充轮廓——三角形、斜条、箭头:Points = [(0, 0), (1, 0.4), (0.2, 1)] 以矩形的 0..1 坐标表示(左下为 0, 0;以像素表示则用 PointUnit = Pixels),可为凸或凹,绕向任意;PointsTo 将其变形为点数相同的另一个轮廓。Polygon 只绘制正 N 边形
Line2DRaw / Line2DChildrenUDream2DLineRaw / UDream2DLineChildrenAsPointsDreamGUIExtensions2D 线:经过给定点 / 经过子级
StaticMeshUDreamStaticMeshDreamGUIExtensions一个静态网格,自成一个绘制调用
BackgroundBlur / BackgroundPixelate / PixelSortUDreamBackgroundBlur / UDreamBackgroundPixelate / UDreamPixelSortDreamGUIExtensions屏幕效果;见渲染
CanvasRenderTargetPreviewerUDreamCanvasRenderTargetPreviewerDreamGUIExtensions渲染目标画布所绘制的内容
UMGWidgetUDreamUMGWidgetDreamGUIExtensions将一个 UMG 控件渲染到渲染目标,然后作为 DreamGUI 自身的几何绘制出来;见 UMG 互操作
PostProcessRenderElementUDreamPostProcessRenderElementDreamGUIExtensions抓取后处理视觉的结果图像并在此处作为一块几何显示
PostProcessRenderElementTextUDreamPostProcessRenderElement_TextDreamGUIExtensions同上,但以文本视觉作为宿主

视觉分三类(EDreamVisualType):BatchMesh 由画布合批,几乎所有的视觉都是这一类;DirectMesh 自己写网格段,每一个都是一个 draw call,用于顶点量大、变化频繁的内容(静态网格);以及 PostProcess,一种读写屏幕的效果。插件也可以添加自己的视觉,用 DECLARE_DREAM_GUI_VISUAL 为它注册一个 .dui 标签。

角度并不共用同一套约定。 在写数字之前,请先确认某个属性使用的是哪一套:

位置零度是正方向旋转
Ring (StartAngle, EndAngle)三点钟方向逆时针
Native.RingMenu(StartAngle、SweepAngle)、Native.ProgressBar(RadialStartAngle)、路径上的文本(StartAngle)十二点钟方向顺时针
矩形块的 RadialFillRotation三点钟方向顺时针
RenderRotation.Roll正立顺时针

因此,用 Ring 绘制的进度环以 StartAngle = 90 从十二点钟方向开始,并顺时针运行到 EndAngle = 90 - 360 * progress。

程序化形状——环、多边形、多边形描边——没有"想要多大"的答案:它们的顶点是从给定的矩形推出来的。它们在测量里弃权,跟着写出来的矩形走。

行为:挂在控件上的逻辑

行为是 UDreamUIBehaviour 的子类,按顺序挂在控件的组件数组里。它们有一套 Unity 式的生命周期——Awake、OnEnable、Start、Tick、OnDisable、OnDestroy——再加上 OnDimensionsChanged、OnAttachmentChanged、OnInteractableChanged 这些回调;Blueprint 子类里同名的事件会在同样的时机触发。bStartWithTickEnabled 和 bTickEvenWhenPaused 控制它的 tick。

Awake 的顺序是层级高的先跑——挂在根控件上的脚本最先执行。

六个时机之外还有七个变更回调:OnTransformChanged、OnDimensionsChanged、OnChildDimensionsChanged、OnAttachmentChanged、OnSiblingIndexChanged、OnInteractableChanged、OnRaycastableChanged。OnDimensionsChanged 会逐项告诉你改了哪个(PivotChanged / WidthChanged / HeightChanged);OnChildDimensionsChanged 是独立的一个——父级要跟着孩子长大时用它,而不是用自己那个。有些回调想先于 Awake 跑,它们先被缓存起来(CallbacksBeforeAwake),等 Awake 时才执行。

Blueprint 侧是 13 个 Receive* 事件(6 个时机 + 7 个回调),全部是 BlueprintImplementableEvent,而且在蓝图里显示出来的名字不带 Receive——ReceiveAwake 就叫 Awake。

声明「我不用」

bStartWithTickEnabled / bTickEvenWhenPaused 是运行时开关;另有两个是在构造函数里声明的:

声明之后
DeclareTickUnused(InClass)恰好是这个类的行为(以及由它派生的 Blueprint)不进 UI 管理器的 tick 列表,而不是每帧被白叫一次
DeclareTransformChangedUnused(InClass)不听控件的移动通知——连带效应是「没人听它移动的控件」也不会被通知移动

两条限制要记住:它只覆盖「恰好是 InClass」这一个类(C++ 子类可以重写 Tick,而没有任何东西能替它声明——子类照旧 tick,直到它自己的构造函数也声明一次);它不改变「可不可以 tick」,那是 SetCanExecuteTick 管的,而且 Blueprint 写了 Tick 事件照旧算数。

两条子对象基类链

挂在控件上的子对象有两条,重量不同。上面说的是重的那条;轻的是 UDreamWidgetSubObjectBehaviour(BlueprintType、Abstract、DefaultToInstanced、EditInlineNew,没有 ClassGroup、没有 Blueprintable),只提供 OnRegister / OnUnregister、BeginPlay / EndPlay、IsRegistered、GetWidget 和 GetPathDisplayName——面板槽走这条。会每帧跑、或者要听控件变化的,走重的;纯粹是「挂在控件上的数据与逻辑」,走轻的。

插件里大部分东西都是行为:画布本身(UDreamCanvas)、Dream* 控件由之搭成的 UI* 一族(UIButton 及其兄弟姐妹)、导航作用域、命名槽(UDreamNamedSlot)、拖放的源和目标、网格修改器(阴影、描边、渐变色、文字动画)。代码里用 AddComponent、GetComponent、GetComponents、GetComponentByInterface、RemoveComponent 和 MoveComponentToIndex;在 .dui 里写 + UIButton { … }。

渲染变换:只动画法,不动布局

渲染变换移动的是控件画在哪,布局一无所知。布局照常测量和排布它,兄弟不会挪,任何东西都不会写回 AnchorData。这就是它和 RelativeLocation 的全部区别——后者的 setter 会反算锚点、请父级重新布局,所以在面板里给它做动画永远不行:动画和布局只会轮流改它。

属性类型说明
RenderTranslationFVector本地空间。X 是深度,朝远离观察者的方向,所以负 X 把控件拉向屏幕
RenderRotationFRotator绕 RenderTransformPivot 旋转,单位为度;SetRenderTransformAngle 只写入面内通道。正的 Roll 会让控件在屏幕上顺时针旋转,与 UMG 的角度一致
RenderScaleFVector绕 RenderTransformPivot 缩放
RenderTransformPivotFVector2D控件自己矩形里的归一化点,(0, 0) 左下;和属于布局的 AnchorData.Pivot 互不相干
RenderShearFVector2D斜切,单位度,作用于控件和整棵子树

它是三维的,这是有意为之:被它镜像的那套变换本来就是 FVector / FQuat / FVector,世界空间的画布也存在,一张卡片绕竖轴翻过来是很平常的需求。代价是批处理那条老规矩:在画布平面里滚转、缩放、平移仍然合批;一旦有了深度、偏航或俯仰,这个控件就离开 2D 批处理路径,翻一张卡片多花一个 draw call——和你直接写那个旋转一样。

RenderShear 有两点不同:布局看不到它,命中测试也不跟随它——斜切的控件按没斜切的矩形接收点击(只有在透视作用域里,射线才走矩阵路径)。它也不能打关键帧,另外三个通道可以。ClearRenderTransform 一次性把它们全部放回原样;HasRenderTransform 回答"现在画法是否和布局不同"。

渲染变换不停变化的控件会被它的画布做成渲染层,在 GPU 上移动,见渲染。在面板里给控件做动画请用 RenderOffsetTo、RenderScaleTo、RenderAngleTo 和 RenderTranslationTo,见动画。

每个控件自己的透视

bPerspective 让一个控件为它的后代建立透视,形状和 CSS 的 perspective 一样:有深度的孩子朝站在这个控件平面前方的眼睛缩短。PerspectiveFieldOfView(默认 60 度)决定眼睛离多远,PerspectiveOrigin 是消失点(CSS 的 perspective-origin)。嵌套的透视是嵌套,不是覆盖。关着时不花任何代价,子树里没有深度时也不花——平的控件原样返回。它需要一个使用透视投影的屏幕空间画布,否则不起作用,详见画布。

可见、透明、可交互

几个开关各管一件事,不要混用:

开关管什么
Visibility(EDreamWidgetVisibility)与 UMG 一一对应:Visible、Hidden(占位但不画)、Collapsed(不占位)、HitTestInvisible、SelfHitTestInvisible
ShownVisibility 的是 / 否形式:true 是 Visible,false 是 Collapsed。自己不存任何东西;它正是 Shown <- HasSave() 在 .dui 里绑定的东西
bWidgetActive行为生命周期的开关:不激活就不可见、不占布局、不可交互、不可命中,它的行为收到 OnDisable
bIsEnabled / SetIsEnabledUMG 的启用开关:整棵子树不再接收输入,控件显示禁用外观;GetIsEnabledInHierarchy 是层级合并后的答案
Interactable、Raycastable三态(Inherit、Enabled、Disabled)的可交互 / 可被射线命中
RenderOpacity透明度,沿树向下相乘;GetFinalRenderOpacity 是乘完的值
SetContentTint给后代的视觉染色(不含自己),像 UMG 的 content colour

Shown 永远不会改掉隐藏或不可命中:一个 Hidden 的控件被设成 shown 以后还是 Hidden。剪裁是 Clipping(Inherit、ClipToBounds、ClipToBoundsWithoutIntersecting、Disabled),另有 ClippingCornerRadius、 ClippingMargin 和遮罩 ClipMask;bClipToBelow 让控件只在下方图层画出的地方显示(见裁剪遮罩与剪贴到下方图层)。视觉元素的 BlendMode 和容器上的 UDreamLayerGroup 决定画出的内容如何合成(见混合模式与图层组);调整图层、渐进模糊、玻璃与风格化效果作用于背后的画面(见作用于背后画面的效果)。UDreamLayerStyle 给控件加图像编辑器式的图层样式,UDreamShapeBlendGroup 把容器子项里的 RectBlock 融成一个形状(见图层样式、形状融合与光)。网格修改器可以弯曲它画出的内容(网格变形、果冻与路径文字), UDreamMaskTransition 透过移动的遮罩显示控件(遮罩转场)。OnVisibilityChanged、OnFocusReceived 和 OnFocusLost 是控件上可绑定的三个事件。

在代码里建控件

UDreamUIBPLibrary::ConstructWidget(WorldContext, DisplayName, VisualClass) 是 UMG 的 WidgetTree::ConstructWidget<T>() 的对应物:控件存在但不在屏幕上。它不画任何东西,行为也不会运行,直到你把它交给 AddChild 或 AddToViewport;在此之前 DreamUI 的管理器持有它,所以你在配置它时它不会被回收。纯容器就把 VisualClass 留空,然后给它一个布局容器,就成面板了。

调用结果
AddChild(Child, SiblingIndex)挂上去,返回孩子的 UDreamPanelSlot(所有面板只有这一种槽类,不必转型)
RemoveChild / RemoveFromParent摘下来但留着:仍注册、子树完整,回到还没加进去的状态;对象池用的就是它
DestroyChild / DestroyWidget拆掉整棵子树;之后 IsValid 返回假
FindChildByDisplayName按显示名找孩子,支持路径,如 "Content/ListItem/NameLabel"

一个 Widget Blueprint 的实例在蓝图里用 Create Dream Widget 节点建,C++ 里用 UDreamUIBPLibrary::CreateDreamWidgetOfClass 或 AddWidgetOfClassToViewport 建;见 Widget Blueprint。每个属性和函数都列在 UDreamWidget 参考里,末尾有与 UMG UWidget 的逐项对照。

本页目录