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.

Last updated Oct 26, 2026Edit this pageVersion 1.0.0

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

  1. Load .ui
  2. Factory builds Arc widgets
  3. Mount on stack
  4. Tick: bindings + animations
  5. Events → actions / graphs
What the screen stack does with an asset, frame after frame.
  1. FArcUIAsset reads the MDF file FArcUIAsset.
  2. FArcWidgetFactory turns each node into a live Arc widget and wires its bindings and events FArcWidgetFactory.
  3. The stack composites every mounted screen into one overlay widget, sorted by z-order.
  4. Each Tick re-resolves bindings, advances animations, and advances the settings-screen countdown.
  5. 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:

Content/UI/MainMenu.ui (excerpt)
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

PropertyMeaning
schema_versionWritten on every save; currently 1 FArcUIAsset
design_width, design_heightThe resolution the numbers in the tree are authored in. The root canvas scales the screen to the viewport.
themeOptional .theme for color, font and metric tokens. See Arc styling.
visual_script_classOptional 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.

PropertyMeaning
anchorTopLeft, TopCenter, TopRight, CenterLeft, Center, CenterRight, BottomLeft, BottomCenter, BottomRight or Stretch FArcUIAsset
position, sizeOffset from the anchor and size, in design units
anchor_min, anchor_max, alignmentFractional anchors and pivot, overriding the preset
offset_highThe far inset on a stretched axis
size_to_content_x, size_to_content_yTake the widget's desired size on that axis
z_orderPaint and hit-test order inside a canvas
variableExpose the widget by name to the controller
slot_margin, slot_fill, slot_h_align, slot_v_alignSlot 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_directionGamepad navigation rules, clipping and reading direction. See Arc widgets and layout.
design_hidden, design_lockedDesigner-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:

PropertyMeaning
textThe source text, also the fallback for text_key
text_keyNamespace.key in the string tables. See Localization.
font, font_size, bold, italicFont family, size in logical pixels and face
line_height, letter_spacingPixels between baselines (0 means the face's own) and tracking
font_featuresOpenType features, such as tnum for tabular figures
justifyleft, center or right; logical, so a right-to-left paragraph's left is the right edge
wrap, ellipsisWrap at the arranged width; elide at the tail, head or middle
text_directionauto, ltr or rtl
shadow_x, shadow_y, shadow_colorA 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.

Note

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:

KindClasses
PanelsCanvasPanel, ClipBox, HorizontalBox, VerticalBox, GridPanel, UniformGridPanel, WrapPanel, Overlay, ScrollBox, Border, SizeBox, ScaleBox, RetainerBox, WidgetSwitcher
TextText, RichText, RichTextBlock, EditableTextBox, MultiLineEditableTextBox, Hyperlink
InputButton, CheckBox, ToggleSwitch, ComboBox, Slider, KeyCap, KeyCapture
DataListView, TreeView
DisplayImage, ProgressBar, Spinner, Spacer, VideoPlayer, Breadcrumb
CompositeUserWidget, 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.

MainMenuFlow.cpp
#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.

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 UIOnly and 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.

Content/UI/VisualScriptDemo.ui (excerpt)
Bindings {
    Bind {
        property: "text"
        source: "visualscript.UiDemoController.GetStatus"
    }
}

Bindable properties:

PropertyWidgets
textText, RichText, EditableTextBox
percentProgressBar
valueSlider, ProgressBar
checkedCheckBox, ToggleSwitch
visibleany widget
imageImage (an asset path; empty clears it)
active_indexWidgetSwitcher
spinningSpinner
media, playing, volumeVideoPlayer

Sources, in the order the stack tries them:

  1. Published values

    An exact name published with MUIStatics::SetBindingValue or SetBindingNumber. This is how a controller pushes values to the screen.

  2. Controller functions

    visualscript.<Class>.<Function> calls a function on the screen's controller class. See below.

  3. The host resolver

    A custom hook first, then numeric literals ("0.75"), then reflection paths Entity.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.

EventFired by
clickedButton, Hyperlink
changedCheckBox, ToggleSwitch, ComboBox, Slider
committedEditableTextBox, MultiLineEditableTextBox
linkRichText links; the payload is the link target
drop, drop_outsideWidgets with drop_target / drag_source props
closed, rebindSettingsScreen (closed also on RebindScreen and LobbyScreen)

Actions are resolved in this order:

  1. Built-in animation verbs: PlayAnim:Name, PlayAnimReverse:Name, StopAnim:Name.
  2. VisualScript:<Class>.<Event>[:payload], which runs an event graph on the controller class.
  3. Anything else goes to the host's event sink. In a game, that is the RegisterUIAction table.

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 variables WidgetName, EventName, PinPayload, ScreenPath and OwnerEntity.
  • React to the screen: the controller receives OnScreenShown, OnScreenHidden, and OnUIEvent for every widget event on the screen.
  • Reach back with the MUIStatics functions: SetWidgetText, SetWidgetVisible, SetProgress, PlayWidgetAnim, StopWidgetAnim, PushScreen, PopScreen, SetBindingValue, SetBindingNumber and the video controls MUIStatics.
Warning

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.

  • 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

Page feedback

Was this page helpful?