脚本与代码入口
用于创建、显示和将 UI 放入世界的蓝图与 C++ 入口(UDreamUIBPLibrary)、K2 节点模块、从命令行编译每个 .dui 类,以及创建 Dream Widget Blueprint、将其指向 .dui 并编译它的编辑器 Python。
Blueprint 与 C++ 入口
运行时入口集中在 UDreamUIBPLibrary(模块 DreamGUI、 DreamUIBPLibrary.h),命名刻意对照 UMG:
| 想做的事 | UMG | DreamGUI |
|---|---|---|
| 实例化一个控件类但先不放到任何地方 | Create Widget 节点 / CreateWidget | Create Dream Widget 节点 / CreateDreamWidgetOfClass |
| 创建它并放到视口上 | CreateWidget + AddToViewport | Create Dream Widget + AddToViewport,或 AddWidgetOfClassToViewport |
| 将它从视口移除 | RemoveFromParent | RemoveFromViewport |
| 构造一个裸控件 | WidgetTree::ConstructWidget<T>() | ConstructWidget |
| 立即布局(本帧就需要尺寸) | ForceLayoutPrepass | ForceLayoutPrepass |
| 标记为下一次布局 | InvalidateLayoutAndVolatility | InvalidateLayout |
| 放入世界 | WidgetComponent | AttachWidgetToSceneComponent,或放置一个 ADreamWorldWidgetActor |
值得了解的细节:
- Create Dream Widget 节点。 UMG 的 Create Widget 节点:选中一个类会为每个 Expose on Spawn 属性提供一个引脚,并提供一个 Owning Player 引脚。这些引脚在控件初始化之前赋值,因此 Pre Construct、On Initialized 以及每个绑定的首次取值都能看到它们。它编译为
BeginDeferredCreateDreamWidget、各项赋值,然后是FinishDeferredCreateDreamWidget;C++ 中对应的两半是BeginCreateDreamWidget/FinishCreateDreamWidget(Core/DreamUserWidget.h)。因此CreateDreamWidgetOfClass是 BlueprintInternalUseOnly,正如 UMG 将Create标记的那样:它不在 Blueprint 菜单中,已调用它的图表仍能编译,并且 它已从 Python 中消失——需要实例的编辑器脚本可使用add_widget_of_class_to_viewport,或使用从 C++ 暴露的自己的函数。 - 返回引脚跟随类。 Create Dream Widget、
AddWidgetOfClassToViewport和CreateDreamWidgetOfClass的返回值取类的形状,因此 Blueprint 子类自己的变量和函数无需 Cast 即可访问,与 UMG 的 Create Widget 节点一样。 - 屏幕根按需创建。 当有东西首次放到视口上时,共享的屏幕空间根(
GetOrCreateScreenSpaceUIRoot)、射线检测器和事件系统会被创建;无需任何配置。AddWidgetOfClassToScreen是带 before-alive 回调和排序顺序的变体;IsInViewport用于查询。 - 停放状态。 由
ConstructWidget、CreateDreamWidgetOfClass或 Create Dream Widget 创建的控件存在但不在屏幕上:它不绘制任何内容,行为也不会运行,直到你将其交给AddChild或放到视口上。同时 UI 管理器持有它,因此在你配置它时不会在你眼皮底下被回收。IsWidgetParked用于查询,控制台命令dreamgui.ListPendingWidgets会列出每个停放的控件。 - 放入世界。
AttachWidgetToSceneComponent(Root, Component)是 AddToViewport 的世界空间对应物:根必须带有 DreamCanvas(画布决定渲染模式并拥有网格)且没有父级;它会被附加到场景组件,由此获得世界变换。否则返回 false 且不做任何更改。更常见的是放置一个ADreamWorldWidgetActor,或向自己的 actor 添加UDreamWorldWidgetComponent并SetWidgetClass——参见世界空间。
C++:.dui 屏幕的原生基类
.dui 的节点 id 会成为生成的类的成员,而 C++ 基类在编译时无法命名它们,因此它按变量名查找它们。处理函数路由名称(OnClicked -> HandleApply)是 UFUNCTION():
// MySettingsScreen.h -- add "DreamGUI" and "DreamGUIControls" to Build.cs
#pragma once
#include "Core/DreamTextUserWidget.h"
#include "MySettingsScreen.generated.h"
UCLASS(Abstract)
class UMySettingsScreen : public UDreamTextUserWidget
{
GENERATED_BODY()
protected:
virtual void NativeOnInitialized() override;
/** `OnClicked -> HandleApply` in the .dui lands here. */
UFUNCTION()
void HandleApply();
};// MySettingsScreen.cpp
#include "MySettingsScreen.h"
#include "Core/DreamWidgetTree.h"
#include "Controls/DreamDropdown.h"
void UMySettingsScreen::NativeOnInitialized()
{
Super::NativeOnInitialized();
// The .dui declares the node; the compiler made it a member of the generated class.
if (UDreamDropdown* Quality = Cast<UDreamDropdown>(GetWidgetTree()->FindWidgetByVariableName(TEXT("Quality"))))
{
Quality->SetOptions({ FText::FromString(TEXT("Low")), FText::FromString(TEXT("High")) });
}
}
void UMySettingsScreen::HandleApply()
{
}显示它:
#include "DreamUIBPLibrary.h"
// SettingsClass: a TSubclassOf<UDreamUserWidget> naming the Blueprint made from the .dui
UDreamWidget* Page = UDreamUIBPLibrary::AddWidgetOfClassToViewport(this, SettingsClass);
// ...
UDreamUIBPLibrary::RemoveFromViewport(this, Page);动画与输入模式
UDreamUserWidget::PlayAnimation 是编译器生成的动画变量所接入的入口:将变量拖入并放到 Animation 上。它旁边是 PlayAnimationByName、PlayAnimationForward / PlayAnimationReverse(“点击滑出,再次点击滑回”这一惯用法)、PlayAnimationTimeRange,以及 QueuePlayAnimation,后者在动画自身回调内部也是安全的。它们返回一个 FDreamUIAnimationHandle;UDreamUIAnimationLibrary 提供用于处理句柄的 Blueprint 函数。
输入模式是 UDreamUIInputModeLibrary:SetInputModeUIOnly、 SetInputModeGameAndUI 和 SetInputModeGameOnly,与 UMG 的 SetInputMode_* 是同样三种状态,只是焦点给予 DreamGUI 控件。
K2 节点模块
DreamGUIK2Nodes(仅由运行未烘焙内容的进程加载)添加三个 Blueprint 节点:
| 节点 | 作用 |
|---|---|
| Play Animation with Finished event | PlayAnimation 的异步形式,带一个 Finished 执行引脚 |
| Play Animation Time Range with Finished event | PlayAnimationTimeRange 的异步形式 |
| Get Component for DreamGUIComponentReference | FDreamUIComponentReference 所指定的组件,其输出被转换到所引用的组件类型 |
从命令行编译
如果构建脚本或 CI 需要在没有编辑器窗口、没有 Python 的情况下编译并保存每个 .dui 类,则运行 DreamUICompileWidgets commandlet:
UnrealEditor-Cmd.exe <project>.uproject -run=DreamUICompileWidgets -All [-Path=/Game/UI]
UnrealEditor-Cmd.exe <project>.uproject -run=DreamUICompileWidgets -Manifest=Tools/widgets.json [-Only=WBP_A,WBP_B]-All 会重新编译已存在的基于文本的控件蓝图;清单还会创建缺失的那些,每个都带有父类及其指定的 .dui。每条编译器消息都会写入日志,只要有失败,退出码就为非零。清单的格式及其他内容见 工作流。
要检查、编译或布局单个文件而无需编写清单,.skill/dui.ps1 会向引擎询问 DreamMCP 端点 会回答什么:check <file> / check -All(不写入任何内容)、compile <file>(class 行指定的蓝图,先处理组件)、layout <file> -Width -Height -Sizes(每个节点的矩形和布局问题)。它使用正在服务该项目的编辑器,或为此次调用启动无头宿主,并在源文件没有错误时以 0 退出,有错误时以 1 退出,无法运行时以 2 退出。
pwsh -NoProfile -File Plugins/DreamGUI/.skill/dui.ps1 check -All
pwsh -NoProfile -File Plugins/DreamGUI/.skill/dui.ps1 layout DUI/Menu.dui -Sizes "1280x720, 2560x1440"编辑器 Python:从 .dui 生成 Widget Blueprint
批量创建资产——一系列组件、一组屏幕——不必一次点击一下 Set Source File...。那个按钮所做的是设置类默认值 SourceFile 并编译,Python 也能做到。共四步:
使用 DreamGUI 的工厂创建
unreal.DreamWidgetBlueprintFactory 创建一个 UDreamWidgetBlueprint,由 DreamGUI 自己的编译器编译,而引擎的 Blueprint 工厂做不到。跳过其选择器后,父类是普通的 UDreamUserWidget。
重新设置父类为 DreamTextUserWidget
一个类只有在派生自 UDreamTextUserWidget(或你自己的其子类)时才能指定 .dui。使用 BlueprintEditorLibrary.reparent_blueprint 重新设置父类。
设置 SourceFile
在生成类的默认对象上设置 SourceFile。相对路径以 DUI/ 源目录为根。
编译并保存
compile_blueprint 读取文件并构建树;然后保存包。
# make_settings_assets.py -- run inside the editor; see below for how.
import unreal
PACKAGE_PATH = "/Game/UI"
NAME = "WBP_Settings"
SOURCE = "UI/Settings.dui" # relative to the project's DUI/ directory
def make_widget():
unreal.AssetRegistryHelpers.get_asset_registry().wait_for_completion()
asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
blueprint = unreal.load_asset(PACKAGE_PATH + "/" + NAME)
if blueprint is None:
# DreamGUI's factory makes a UDreamWidgetBlueprint; its parent is the plain user widget until reparented below.
blueprint = asset_tools.create_asset(NAME, PACKAGE_PATH, unreal.DreamWidgetBlueprint,
unreal.DreamWidgetBlueprintFactory())
if blueprint is None:
raise RuntimeError("cannot create " + PACKAGE_PATH + "/" + NAME)
if not hasattr(unreal, "BlueprintEditorLibrary"):
# Python wraps the modules loaded so far; in a commandlet nothing may have loaded this one yet.
unreal.load_module("BlueprintEditorLibrary")
library = unreal.BlueprintEditorLibrary
defaults = unreal.get_default_object(library.generated_class(blueprint))
if not isinstance(defaults, unreal.DreamTextUserWidget):
# A class is text-authored when it derives from UDreamTextUserWidget.
library.reparent_blueprint(blueprint, unreal.DreamTextUserWidget.static_class())
defaults = unreal.get_default_object(library.generated_class(blueprint))
# What the designer's "Set Source File..." sets: the class default the compile reads the hierarchy from.
defaults.set_editor_property("SourceFile", unreal.FilePath(file_path=SOURCE))
if not library.compile_blueprint(blueprint):
raise RuntimeError(NAME + " did not compile from " + SOURCE + "; see the log")
if not unreal.EditorLoadingAndSavingUtils.save_packages([blueprint.get_outermost()], False):
raise RuntimeError("saving " + NAME + " failed")
unreal.log("made " + blueprint.get_path_name() + " <- " + SOURCE)
make_widget()该脚本可以安全地重复运行:现有资产会被保留,重新指向其源文件并重新编译,因此更改过的 .dui 会被读取。它仅使用核心编辑器向 Python 暴露的内容(资产注册表、AssetTools、 EditorLoadingAndSavingUtils、BlueprintEditorLibrary),不使用默认关闭的 Editor Scripting Utilities 插件。属性按 C++ 的命名方式命名("SourceFile"),Python 也能解析。
要使用你自己的原生基类(例如上面的 UMySettingsScreen),改为重新设置父类到 unreal.load_class(None, "/Script/MyGame.MySettingsScreen"),并测试它是否为某个子类。
创建多个时顺序很重要:编译一个屏幕会加载其 .dui 通过 use … as 放置的组件的类,因此应先编译组件,之后再编译使用它们的屏幕。
运行它
无头运行,作为 commandlet:
UnrealEditor-Cmd.exe <project>.uproject -EnablePlugins=PythonScriptPlugin -run=pythonscript -script=<path>\make_settings_assets.py -unattended -nullrhi或在编辑器内,于启动时:
UnrealEditor.exe <project>.uproject -ExecutePythonScript=<path>\make_settings_assets.py一个还会导入文件的脚本(通过 AssetImportTask 导入字体或纹理)必须在编辑器中运行:导入需要 Slate,而 -run=pythonscript commandlet 没有。仅创建 Blueprint、设置属性、编译并保存的脚本作为 commandlet 运行没有问题。
一旦某个类指定了其源文件,在编辑器中保存该 .dui 就会重建该类,而编辑器的 Rebuild DUI 会一次性重新编译每个以文本为基础的类。