DreamGUI
快速上手

项目里的布局

运行时模块的分层与各自装什么、C++ 要在 Build.cs 里加哪个模块、.dui 文件放在哪里、插件目录里每个文件夹是什么,以及日志类别。

模块分层

运行时按层拆成几个模块。一个模块只依赖它下面各层的模块,从不依赖同层的兄弟;反方向的 include 会让 Tools/Tests/static_checks.py 失败(规则 layering)。 UI 的六个运行时模块都在 PostConfigInit 加载,所以它们的类型和 .dui 标签在任何东西编译之前就已就位。

L4   DreamGUISamples
L3   DreamGUIControls      DreamGUIExtensions
L2   DreamGUIInput
L1   DreamGUI (core)
L0   DreamGUIRenderer      DreamTween
     ------------------------------------------------------------
     DreamGUIEditor, DreamGUIK2Nodes (uncooked only), DreamGUITests (editor only)
模块层装什么
DreamGUIRendererL0,核心之下绘制 DreamUI 的 view extension 和绘制渲染目标画布的 render command、它们的着色器、顶点与索引格式、画布用来回答材质参数的材质代理、后处理代理以及各效果共用的屏幕读写、DreamUI.Stats 背后的阶段计时。它对控件一无所知:它要的东西由核心注册给它
DreamGUIL1,核心控件、visual、画布合批、布局、文本与 .dui、动画、事件契约、为渲染器保存画布分段的 render root,以及 PNG 截图
DreamGUIInputL2,核心之上输入系统:事件系统及其预设 Actor、射线检测器与输入模块、动作路由、导航、拖放、提示框与模态、控件库所基于的 selectable 基类,以及游戏视口客户端
DreamGUIControlsL3,输入之上控件库:Dream* 控件(按钮、开关、滑条、列表、对话框、标签页……)、构成它们的 UI* 行为、动作栏、样式表,以及与 UMG 的互操作
DreamGUIExtensionsL3,输入之上2D 线、多边形和环,静态网格 visual,retainer box 与渲染目标辅助,歌词,具体的网格修改器,以及背景模糊、像素化和像素排序效果
DreamGUISamplesL4,控件之上展示场景和控件画廊
DreamTweenL0,独立补间动画;加载阶段是 Default
DreamGUIEditor、DreamGUIK2Nodes只在未烹饪环境设计器和资产工具;蓝图节点。凡是运行未烹饪内容的进程都会加载它们,从编辑器启动的游戏(-game、Standalone Game)也算 —— 编辑器构建加载时会丢掉蓝图保存的字节码、从蓝图重建,而控件蓝图类和它的编译器就在这里。编辑器之外只启动编译器
DreamGUITests编辑器自动化测试套件

C++ 要加哪个模块

用到哪个拆出去的模块里的类型,就把那个模块加进你的 Build.cs。大致的对应是:

你在用模块
绘制、效果的渲染代理DreamGUIRenderer
控件、visual、画布、UDreamUIBPLibraryDreamGUI
事件系统、射线检测器、导航、视口客户端、DreamUITextInputRouterDreamGUIInput
Dream* 控件和 UI* 行为DreamGUIControls
线、环、效果、渲染目标辅助DreamGUIExtensions
// MyGame.Build.cs
PublicDependencyModuleNames.AddRange(new string[] { "DreamGUI", "DreamGUIInput", "DreamGUIControls" });

资产不需要做任何事:每个挪了模块的类型都仍然能用旧名字加载(见迁移)。

.dui 文件放在哪

放在一个 DUI/ 目录下:项目自己的(<Project>/DUI/),或者某个已启用插件的(<Plugin>/DUI/)。不放在 Content/ 下 —— .dui 是源码,不是资产:放进 Content/ 意味着烹饪器要去走它,内容浏览器里多出一个打不开的文件,而一个发布控件类的插件得把源码混进烹饪内容里才能被找到。

指向另一个文件的路径 —— 蓝图的 Source File,或者 use 后面那个 —— 有三种写法:

写法含义
Panels/Settings.dui相对某个 DUI/ 根:先找项目的,再按顺序找每个插件的,取第一个存在这个文件的
Plugin.MyPlugin:Panels/Settings.dui那个插件的 DUI/ 目录
D:/Work/Proj/DUI/Panels/Settings.dui绝对路径,按原样使用

裸的相对路径意思是"哪个根有它就是哪个",方便,但两个根里有同一个相对路径时就有歧义 —— 这正是插件限定写法存在的原因。在设计器里选文件时,选到的绝对路径会被转回可移植的写法:项目根下的存成相对路径,插件根下的存成 Plugin.X:…,都不在的才原样存成绝对路径(拒收会让选择框悄悄丢掉你的选择)。

use "Settings/SettingsLibrary.dui"
use "Plugin.MyPlugin:Panels/Row.dui" as Row
use /Game/UI/WBP_Slider as Slider

VerticalBox Root {
    Spacing = 12
    Row Audio { Label = "Audio" }
    Slider Volume
}

编辑器还会往项目的 DUI/ 里写两个文件:.dui-symbols.json(启动时和执行 DreamUI.ExportSymbols 时重写,是 VS Code 扩展做补全用的符号表),以及 DreamUI.code-workspace (Tools ▸ Open DreamUI Workspace (VSCode) 按当前的源码根重写并打开)。

一个用了 DreamGUI 的项目大概是这样:

MyProject/
  Config/
    DefaultDreamGUI.ini
    DefaultEngine.ini
  Content/
    UI/
      WBP_HelloDreamGUI.uasset
  DUI/
    HelloDreamGUI.dui
    .dui-symbols.json
    DreamUI.code-workspace
  Plugins/
    DreamGUI/

项目的 Config/DefaultDreamGUI.ini 存的是 Project Settings ▸ Plugins ▸ Dream GUI 的值(见安装)。

插件目录里有什么

DreamGUI/
  Config/
    Game.ini
    FilterPlugin.ini
  Content/
  DShader/
  Docs/
  Resources/
  Shaders/
  Source/
  ThirdParty/
  Tools/
  DreamGUI.uplugin
  CHANGELOG.md
  LICENSE
  README.md

Config

从 1.0.0 起插件不再带 CoreRedirects,按旧名字保存的资产怎么重存一次,见升级。

  • Game.ini —— 把 /DreamGUI 加进 DirectoriesToAlwaysCook。插件自己伸手去拿的资产(默认材质、字体、精灵预设……)是赋给原生 CDO 的软指针,不产生资产依赖;没有这一行,按显式包列表烹饪时它们一个也不会进包,整个 UI 画成空白。文件必须叫 Game.ini 才会被并入 Game 分支。
  • FilterPlugin.ini —— BuildPlugin 默认只打包 /Source、/Content、/Resources、/Shaders 和 /Binaries/ThirdParty;这里列出其余必须随插件走的文件:上面的 Game.ini、README、CHANGELOG、Docs/ 下的文档和参考,以及 msdfgen 的源码与许可证。

Content

默认字体(DefaultFont_DistanceField 及其 _Bold、_Italic、_BoldItalic 和 _CJK 四个字面,还有 DefaultFont_Bitmap)、Materials/ 下的材质与材质函数、精灵与纹理预设、Blueprints/ 下的事件系统 Actor、 Controls/ 下的控件蓝图(BP_Button、BP_Toggle、BP_Dropdown……)、EnhancedInput/ 下的输入动作和映射上下文(IA_*、IMC_DreamUIInputContext),以及 Samples/HelloDreamGUI.dui。

DShader

Content/Materials 的源码(.dsm / .dsf)。.uasset 是构建产物,和源码一起提交,所以 DreamGUI 不依赖 DreamShader:没装 DreamShader 时,那些材质就是普通的 UMaterial 和 UMaterialFunction。只有想从文本重建它们时才需要 DreamShader。

Docs

DuiLanguage.md(整个 .dui 语言)、Migration.md、FontsAndPackaging.md,以及 Reference/ —— 逐类的属性与函数参考,从反射打印出来、不是手写的,所以不会落后于头文件:

UnrealEditor-Cmd.exe <project>.uproject -run=DreamGUIReferenceDocs

本站的API 参考就是这些页面。

Resources

插件图标、编辑器图标,以及 UMGParity/:每个 UMG 类一张表(共 58 张),每个成员都标注为:在此处名称和含义相同、在此处以其他名称或位于其他类型上,或是被有意省略并说明原因。自动化测试套件将这些表与 UMG 自身的反射进行双向核对。参见它与 UMG 有何不同 和 UMG 对等。

Shaders、Source、ThirdParty

Shaders/Private 存放渲染器的 .usf / .ush;Source/ 存放上述十个模块;ThirdParty/ 存放 msdfgen 子模块和提交的单文件副本(参见 安装)。

Tools

文件夹说明
Tools/Tests测试运行器 Invoke-DreamGUITests.ps1、其预设、静态检查、结果摘要(参见 测试)
Tools/TestHost一个仅用于构建插件并运行其测试的最小宿主项目,以及打包文本冒烟测试
Tools/Bench性能工作所依据的两个基准:一屏 5000 个按钮和一个关卡中 2688 个世界空间面板(参见 基准测试)
Tools/Fontsmake_default_fonts.py,用于构建默认字体
Tools/TextParityDreamGUI、Slate 和 Chrome 在同一文本语料上的对比
Tools/ModuleSplit将运行时模块从核心中拆分出来的脚本
Tools/UpdateMsdfgen.ps1从子模块重新生成单文件 msdfgen 副本
Tools/Get-DreamGUIEnvironment.ps1打印缺陷报告所需的插件、引擎和系统信息,而无需启动引擎

日志类别

类别使用方
DreamGUI核心及其之上的运行时模块(Input、Controls、Extensions、Samples);编辑器的一部分也使用它
LogDreamGUIRendererDreamGUIRenderer。它位于核心之下,无法使用核心的类别,因此拥有自己的类别
DreamTweenDreamTween
DreamGUIEditor设计器和资产工具
DreamGUIK2Nodes蓝图节点
LogDreamGUIReferenceDocs打印参考的 commandlet

统计组是 stat DreamGUI(声明在渲染器中,因此渲染器及其之上的每个模块都计入同一组)和 stat DreamTween。

本页目录