ArcUI screens
How a .ui asset describes a game screen, how the screen stack mounts it, and how bindings, events, animations and controller classes bring it to life.
A game screen in Mowo is a .ui asset: an MDF document holding a widget tree, data bindings, event wiring and animations. At run time the screen stack (CArcUIScreenStack) builds the asset into Arc widgets, mounts it over the game view, and keeps it in sync with gameplay every tick.
The lifecycle of a screen
- Load .ui
- Factory builds Arc widgets
- Mount on stack
- Tick: bindings + animations
- Events → actions / graphs
FArcUIAssetreads the MDF file FArcUIAsset.FArcWidgetFactoryturns each node into a live Arc widget and wires its bindings and events FArcWidgetFactory.- The stack composites every mounted screen into one overlay widget, sorted by z-order.
- Each
Tickre-resolves bindings, advances animations, and advances the settings-screen countdown. - Widget events run built-in verbs, controller graphs or the host's handlers.
The .ui format
A screen is a .ui file (older projects used .ui, which still loads and is renamed when the project opens). A file starts with a Package block that carries the asset id and the assets it imports, then the ArcUI document. This is an excerpt of the test project's main menu:
ArcUI "Widget" {
design_width: 1920
design_height: 1080
Animations {
Anim "MenuIn" {
auto_play: true
Track {
target: "MenuPanel"
property: opacity
Key {
t: 0.0
v: 0.0
}
Key {
t: 0.35
v: 1.0
easing: cubic_out
}
}
}
}
Widget "Root" {
class: "CanvasPanel"
anchor: Stretch
Widget "StartButton" {
class: "Button"
variable: true
anchor: Center
position: vec2(0.0, -120.0)
size: vec2(360.0, 52.0)
Props {
label: "Start Match"
text_key: "Menu.start"
}
Events {
On {
event: "clicked"
action: "PlayAnim:StartNudge"
}
On {
event: "clicked"
action: "StartMatch"
}
}
}
}
}Root properties
| Property | Meaning |
|---|---|
schema_version | Written on every save; currently 1 FArcUIAsset |
design_width, design_height | The resolution the numbers in the tree are authored in. The root canvas scales the screen to the viewport. |
theme | Optional .theme for color, font and metric tokens. See Arc styling. |
visual_script_class | Optional Visual Scripting class (.vscript) that acts as the screen's controller. See Controller classes. |
Node properties
Every Widget node has a class and a name. The name is what bindings, animation targets and FindNamed use.
| Property | Meaning |
|---|---|
anchor | TopLeft, TopCenter, TopRight, CenterLeft, Center, CenterRight, BottomLeft, BottomCenter, BottomRight or Stretch FArcUIAsset |
position, size | Offset from the anchor and size, in design units |
anchor_min, anchor_max, alignment | Fractional anchors and pivot, overriding the preset |
offset_high | The far inset on a stretched axis |
size_to_content_x, size_to_content_y | Take the widget's desired size on that axis |
z_order | Paint and hit-test order inside a canvas |
variable | Expose the widget by name to the controller |
slot_margin, slot_fill, slot_h_align, slot_v_align | Slot settings when the parent is a box, overlay or grid |
nav_up, nav_down, nav_left, nav_right and their _targets, clip_to_bounds, flow_direction | Gamepad navigation rules, clipping and reading direction. See Arc widgets and layout. |
design_hidden, design_locked | Designer-only; ignored unless the factory runs in designer mode |
Text properties
Text nodes take these optional properties; a node that sets no font property keeps the style's font:
| Property | Meaning |
|---|---|
text | The source text, also the fallback for text_key |
text_key | Namespace.key in the string tables. See Localization. |
font, font_size, bold, italic | Font family, size in logical pixels and face |
line_height, letter_spacing | Pixels between baselines (0 means the face's own) and tracking |
font_features | OpenType features, such as tnum for tabular figures |
justify | left, center or right; logical, so a right-to-left paragraph's left is the right edge |
wrap, ellipsis | Wrap at the arranged width; elide at the tail, head or middle |
text_direction | auto, ltr or rtl |
shadow_x, shadow_y, shadow_color | A drop shadow under the text |
Child blocks: Props (class-specific key/value pairs), Bindings, Events, and nested Widget nodes. Props is schema-tolerant: unknown keys are kept through a save.
Fields are written only when they differ from their default, so opening and saving an untouched asset gives a byte-identical file. slot_h_align and slot_v_align default to Default, which means "keep the parent's own alignment".
Widget types
The factory knows these class names:
| Kind | Classes |
|---|---|
| Panels | CanvasPanel, ClipBox, HorizontalBox, VerticalBox, GridPanel, UniformGridPanel, WrapPanel, Overlay, ScrollBox, Border, SizeBox, ScaleBox, RetainerBox, WidgetSwitcher |
| Text | Text, RichText, RichTextBlock, EditableTextBox, MultiLineEditableTextBox, Hyperlink |
| Input | Button, CheckBox, ToggleSwitch, ComboBox, Slider, KeyCap, KeyCapture |
| Data | ListView, TreeView |
| Display | Image, ProgressBar, Spinner, Spacer, VideoPlayer, Breadcrumb |
| Composite | UserWidget, SettingsScreen, RebindScreen, LobbyScreen |
A ListView takes an items array and one child node as its row template. Strings in the template can use $item, $index, or $0, $1… for fields of an array item.
A UserWidget embeds another .ui. ClipBox is a canvas panel that always clips. Nesting deeper than MaxUserWidgetDepth (8), or a reference back to an asset that is already being expanded, becomes a placeholder and a build error instead of a crash FArcWidgetFactory.
The screen stack
There are two ways to mount a screen.
World screens. Add an ArcUI component to an entity. It has asset, z_order, visible and auto_focus ArcUIComponent. SyncFromWorld mounts every visible one.
Code screens. Call PushScreen(assetPath, zOrder, modal). It returns a handle for PopScreen, or 0 if the asset failed to load. PopTopScreen() pops the most recent one CArcUIScreenStack. In a game, MGameEngine wraps these as PushUIScreen and PopUIScreen.
#include <ArcUI/CArcUIScreenStack.h>
static int32_t g_mainMenu = 0;
void ShowMainMenu(Mowo::CArcUIScreenStack& stack)
{
g_mainMenu = stack.PushScreen("Content/UI/MainMenu.ui", 1000, true);
}
void HideMainMenu(Mowo::CArcUIScreenStack& stack)
{
if (g_mainMenu != 0) {
stack.PopScreen(g_mainMenu);
g_mainMenu = 0;
}
}In a packaged game, the host owns the stack's event sink. Use MGameEngine::RegisterUIAction(action, handler) to map an action string from a .ui event, such as the sample's StartMatch, to a C++ handler. QuitGame is registered by default and stops the engine.
Modal screens
A modal screen:
- keeps gamepad focus inside itself;
- is drawn over a full-screen scrim that eats clicks and wheel input, so nothing reaches screens or gameplay below;
- switches the input mode to
UIOnlyand gives back the previous mode when it pops.
The input-mode rule is re-checked every tick against the stack's own HasModalScreen(), so it works however the screen was pushed, including from a graph and in Play-In-Editor FArcUIModalInputGate.
Safe zone
SetSafeZoneInsets(x, y) insets every screen's root canvas by a fraction of each axis, clamped to 0–0.25. The default is zero.
Bindings
A Bind entry drives one widget property from a source every tick. The widget is written only when the value changes.
Bindings {
Bind {
property: "text"
source: "visualscript.UiDemoController.GetStatus"
}
}Bindable properties:
| Property | Widgets |
|---|---|
text | Text, RichText, EditableTextBox |
percent | ProgressBar |
value | Slider, ProgressBar |
checked | CheckBox, ToggleSwitch |
visible | any widget |
image | Image (an asset path; empty clears it) |
active_index | WidgetSwitcher |
spinning | Spinner |
media, playing, volume | VideoPlayer |
Sources, in the order the stack tries them:
- Published values
An exact name published with
MUIStatics::SetBindingValueorSetBindingNumber. This is how a controller pushes values to the screen. - Controller functions
visualscript.<Class>.<Function>calls a function on the screen's controller class. See below. - The host resolver
A custom hook first, then numeric literals (
"0.75"), then reflection pathsEntity.Component.Property[.x|.y|.z|.w]. The entity is found by scene name and the component by its reflected name FArcUIBindingLibrary.
Events
An On entry wires a widget event to an action string. Several entries for the same event all run, in order.
| Event | Fired by |
|---|---|
clicked | Button, Hyperlink |
changed | CheckBox, ToggleSwitch, ComboBox, Slider |
committed | EditableTextBox, MultiLineEditableTextBox |
link | RichText links; the payload is the link target |
drop, drop_outside | Widgets with drop_target / drag_source props |
closed, rebind | SettingsScreen (closed also on RebindScreen and LobbyScreen) |
Actions are resolved in this order:
- Built-in animation verbs:
PlayAnim:Name,PlayAnimReverse:Name,StopAnim:Name. VisualScript:<Class>.<Event>[:payload], which runs an event graph on the controller class.- Anything else goes to the host's event sink. In a game, that is the
RegisterUIActiontable.
Animations
An Anim is a named timeline. Each Track animates one property of one named node: opacity, translation_x, translation_y, scale or rotation. Color tracks tint Text and RichText widgets. Keys have a time t, a value, and an easing into that key: linear, or quad, cubic, quart, quint, sine, expo, circ, back, bounce, elastic with _in, _out or _in_out.
auto_play starts a timeline when the screen mounts; loop wraps it. From C++, use PlayAnimation(assetPath, name, params) with FArcUIAnimPlayParams (Loop, Reverse, OnFinished) FArcUIAnimPlayParams. Every finished run also reports anim_finished through the event sink.
Controller classes
A screen can be driven entirely from Visual Scripting. Set visual_script_class at the root to a .vscript class, then:
- Pull values with
visualscript.<Class>.<Function>bindings. The stack keeps one shared instance per class and caches each source's result per tick. Evaluation runs under a 50,000-step budget, so a runaway loop warns and yields nothing. - Push events with
VisualScript:<Class>.<Event>actions. Before the graph runs, the stack sets the variablesWidgetName,EventName,PinPayload,ScreenPathandOwnerEntity. - React to the screen: the controller receives
OnScreenShown,OnScreenHidden, andOnUIEventfor every widget event on the screen. - Reach back with the
MUIStaticsfunctions:SetWidgetText,SetWidgetVisible,SetProgress,PlayWidgetAnim,StopWidgetAnim,PushScreen,PopScreen,SetBindingValue,SetBindingNumberand the video controls MUIStatics.
UI graphs run with no actor behind them. Calls that need a target actor do nothing and log an error; go through MUIStatics or gameplay events instead. Pushing or popping screens during a binding evaluation is refused, so a binding can never rebuild the screen it is drawing.
The test project pairs Content/UI/VisualScriptDemo.ui with Content/UI/UiDemoController.vscript. For graph authoring, see Functions, macros and dispatchers and Calling C++.
Localization and hot reload
A text_key such as Menu.start resolves through the string tables; the part before the first dot is the namespace. See Localization. LoadLocalization(rootDir, locale) loads key=value tables from <rootDir>/<locale>/ CArcUIScreenStack.
EnableHotReload(true) watches loaded .ui files. Saving one rebuilds every screen that uses it on the next tick CArcUIScreenStack.
Related
- ArcUI Designer to author these assets visually.
- API: ArcUI reference, including
CArcUIScreenStack,FArcUIAsset,FArcWidgetFactory,FArcUIBindingLibrary,MUIStatics,ArcUIComponent.
Engine sources
This page describes behavior implemented in these files of the engine repository, checked against commit c1d08db53.
- Engine/Source/Runtime/ArcUI/Public/ArcUI/FArcUIAsset.h
- Engine/Source/Runtime/ArcUI/Public/ArcUI/FArcWidgetFactory.h
- Engine/Source/Runtime/ArcUI/Public/ArcUI/CArcUIScreenStack.h
- Engine/Source/Runtime/ArcUI/Public/ArcUI/FArcUIBindingLibrary.h
- Engine/Source/Runtime/ArcUI/Public/ArcUI/FArcUIAnimPlayer.h
- Engine/Source/Runtime/ArcUI/Public/ArcUI/FArcUIModalInputGate.h
- Engine/Source/Runtime/ArcUI/Public/ArcUI/Statics/MUIStatics.h
- Engine/Source/Runtime/ArcUI/Public/ArcUI/ECS/Components/ArcUIComponent.h
- Engine/Source/Runtime/GameHost/Public/GameHost/MGameEngine.h