class

CArcUIScreenStack

Runtime owner of the live game-UI overlays. Scans a World for ArcUIComponents, hosts code-driven Push/Pop screens next to them, instantiates each visible one from its .ui asset, composites them (ZOrder-sorted) into a single overlay the host mounts into its Arc root, re-resolves data bindings every Tick, routes widget events to the host's event sink and drives directional (gamepad/keyboard) focus navigation.

Module
ArcUI
Header
#include "ArcUI/CArcUIScreenStack.h"
Namespace
Mowo

Type aliases

AliasDescription
using FWorldQuadSink = std::function<void(const FArcUIWorldQuad&)>The true-3D path: for every visible worldSpace ArcUIWorldWidgetComponent, (re-)renders its tree into an offscreen texture at a distance-driven LOD resolution — only when the widget is dirty or its LOD bucket moved, so an idle nameplate never re-renders — computes its billboard/oriented world quad, and hands each quad to sink for the host to submit to the scene renderer. Widgets with worldSpace = false are skipped here (drive them through SyncWorldWidgets instead). No-ops without a world-widget renderer.
using FBackHandler = std::function<bool()>

Constructors

SignatureNameDescription
CArcUIScreenStack()CArcUIScreenStack
~CArcUIScreenStack()~CArcUIScreenStack
CArcUIScreenStack(const CArcUIScreenStack&) = deleteCArcUIScreenStack

Public functions

ReturnsNameDescription
CArcUIScreenStack&operator=
voidSetPathResolverResolves a serialized asset path ("Content/UI/x.ui") to something LoadFromFile can open.
voidSetFocusSinkWhere directional nav sends the newly focused widget (host wires this to its Arc input processor's SetFocus).
voidSetBindingResolverSupplies the current value for a widget data-binding source.
voidSetEventSinkReceives (widgetName, eventName, action) for every authored widget event that fires.
voidInstallVfsPathResolverConvenience installers so every host mounts identically.
voidInstallBridgeFocusSink
voidInstallWorldBindingResolver
voidEnableHotReloadWatches every loaded .ui file and rebuilds its screens on save.
uint32_tLoadLocalizationLoads <rootDir>/<locale>/*.txt string tables (key=value lines, file stem = namespace) into Arc's CTextLocalizationManager and makes the locale current, so authored text_key props resolve through CText::FromKey.
boolSetProjectThemeTheme every screen without its own theme: resolves colour tokens against.
const FArcUITheme&GetActiveTheme
voidSetSafeZoneInsetsTitle-safe insets as a fraction of each axis, applied by every screen's root canvas (the designer's Safe Area overlay draws the same box).
voidSyncFromWorld
voidSyncWorldWidgetsPlaces every visible ArcUIWorldWidgetComponent's tree at its entity's projected screen position.
voidSyncWorldWidgets3D
voidMarkWorldWidgetDirtyMarks a world widget's offscreen texture stale so the next SyncWorldWidgets3D re-renders it.
voidRecordPendingWorldWidgets
FArcUIWorldHitHitTestWorldWidgetsRay-vs-quad hit test against the interactive world-widget quads resolved by the last SyncWorldWidgets3D, nearest hit first.
boolRouteWorldWidgetClickRay-picks the nearest interactive world widget and dispatches a synthetic left click (button down + up) to the widget under the mapped local point, exactly as if the user had clicked that pixel of the offscreen tree.
voidClear
int32_tPushScreenCode-driven screens (pause menu, main menu, loading).
boolPopScreen
boolPopTopScreen
boolHasModalScreen
int32_tPushedCount
boolPlayAnimationTimeline playback on a mounted screen (world-scanned or pushed), addressed by its asset path.
boolPlayAnimation
boolStopAnimation
voidStopAllAnimations
boolIsAnimationPlaying
boolDispatchActionThe built-in event-action vocabulary: "PlayAnim:Name", "PlayAnimReverse:Name", "StopAnim:Name".
boolDispatchVisualScriptAction
boolSetWidgetText
boolSetWidgetVisible
boolSetWidgetProgress
Arcf::AVideoPlayer*FindVideoPlayerThe VideoPlayer node under a name (empty screen path searches every screen), or null when the name is not a video — MUIStatics' seam.
voidSetVisualScriptBindingText
voidSetVisualScriptBindingNumber
boolInVisualScriptBindingEval
uint32_tVisualScriptEvalsLastTick
voidNotifyAssetChangedMarks a loaded asset stale so the next Tick evicts and rebuilds every screen using it — the entry point the file watcher drives, public so hosts without a watcher (and tests) can force the same reload.
Arcf::TSharedPtr<Arcf::AWidget>GetOverlayWidget
voidTick
boolHandleDirectionalDirectional navigation: spatial pick of the nearest focusable widget in the pressed direction (center-line projection with axis bias, the UE approach).
voidSetRightToLeftThe reading order screens build with when a node says "inherit" — set from the active culture.
boolIsRightToLeft
boolHandleAcceptAccept delivered as a real activate on the focused widget (the widget translates it internally — click delegate, toggle, open); no synthesized mouse events.
boolHandleBackBack/cancel: a host- or screen-defined handler first, then pop of the top code-driven screen.
voidSetBackHandler
voidNotifyInputDeviceHosts report the device each input event came from; switching to the gamepad re-applies the focus visual, switching to the mouse clears it.
EArcUIInputDeviceGetActiveInputDevice
Arcf::TSharedPtr<Arcf::AWidget>FindNamed
int32_tMountedCount

Function details

CArcUIScreenStack

C++
CArcUIScreenStack()

~CArcUIScreenStack

C++
~CArcUIScreenStack()

CArcUIScreenStack

C++
CArcUIScreenStack(const CArcUIScreenStack&) = delete

operator=

C++
CArcUIScreenStack& operator=(const CArcUIScreenStack&) = delete

SetPathResolver

C++
void SetPathResolver(std::function<std::string(const std::string&)> resolver)

Resolves a serialized asset path ("Content/UI/x.ui") to something LoadFromFile can open. Identity when unset.

SetFocusSink

C++
void SetFocusSink(std::function<void(Arcf::TSharedPtr<Arcf::AWidget>)> sink)

Where directional nav sends the newly focused widget (host wires this to its Arc input processor's SetFocus). Optional.

SetBindingResolver

C++
void SetBindingResolver(FArcUIBindingResolver resolver)

Supplies the current value for a widget data-binding source. Applied to bound widgets at instantiation, then re-resolved every Tick with a dirty-check so bound widgets track live gameplay state. Optional — without it authored defaults stand. Set it before the first SyncFromWorld.

SetEventSink

C++
void SetEventSink(FArcUIEventSink sink)

Receives (widgetName, eventName, action) for every authored widget event that fires. Optional; without it events are dropped.

InstallVfsPathResolver

C++
void InstallVfsPathResolver()

Convenience installers so every host mounts identically. The VFS path resolver maps "Content/UI/x.ui" to a native path; the bridge focus sink drives CArcMowoBridge's input processor; the world binding resolver wires FArcUIBindingLibrary reflection paths against the host's live World + entity-name lookup (customHook is the Visual Script seam).

InstallBridgeFocusSink

C++
void InstallBridgeFocusSink()

InstallWorldBindingResolver

C++
void InstallWorldBindingResolver(FArcUIBindingLibrary::FWorldProvider world, FArcUIBindingLibrary::FEntityLookup lookup, FArcUIBindingLibrary::FCustomSourceHook customHook = FArcUIBindingLibrary::FCustomSourceHook())

EnableHotReload

C++
void EnableHotReload(bool enable)

Watches every loaded .ui file and rebuilds its screens on save. Watch callbacks only record intent; the rebuild happens in Tick.

LoadLocalization

C++
static uint32_t LoadLocalization(const std::string& rootDir, const std::string& locale)

Loads <rootDir>/<locale>/*.txt string tables (key=value lines, file stem = namespace) into Arc's CTextLocalizationManager and makes the locale current, so authored text_key props resolve through CText::FromKey. Returns the number of entries registered.

SetProjectTheme

C++
bool SetProjectTheme(const std::string& themePath)

Theme every screen without its own theme: resolves colour tokens against. Loaded through the path resolver and cached; empty clears back to the built-in default theme.

GetActiveTheme

C++
const FArcUITheme& GetActiveTheme() const

SetSafeZoneInsets

C++
void SetSafeZoneInsets(float fractionX, float fractionY)

Title-safe insets as a fraction of each axis, applied by every screen's root canvas (the designer's Safe Area overlay draws the same box).

SyncFromWorld

C++
void SyncFromWorld(World& world)

SyncWorldWidgets

C++
void SyncWorldWidgets(World& world, const FArcUIViewInfo& view)

Places every visible ArcUIWorldWidgetComponent's tree at its entity's projected screen position. Call once per frame after the camera is resolved; an invalid view hides the layer instead of dropping the trees. This is the screen-space fallback — components with worldSpace = false use it exclusively, and everything falls back to it when the offscreen renderer is unavailable.

SyncWorldWidgets3D

C++
void SyncWorldWidgets3D(World& world, const FArcUIViewInfo& view, const FWorldQuadSink& sink)

MarkWorldWidgetDirty

C++
void MarkWorldWidgetDirty(uint64_t owner)

Marks a world widget's offscreen texture stale so the next SyncWorldWidgets3D re-renders it. Bound widgets whose data changed call this automatically; hosts can force a refresh (e.g. a health bar tick).

RecordPendingWorldWidgets

C++
void RecordPendingWorldWidgets()

HitTestWorldWidgets

C++
FArcUIWorldHit HitTestWorldWidgets(const Vec3& rayOrigin, const Vec3& rayDir) const

Ray-vs-quad hit test against the interactive world-widget quads resolved by the last SyncWorldWidgets3D, nearest hit first. On a hit, the local UV is filled in (top-left origin, matching the widget's own coordinates).

RouteWorldWidgetClick

C++
bool RouteWorldWidgetClick(const Vec3& rayOrigin, const Vec3& rayDir)

Ray-picks the nearest interactive world widget and dispatches a synthetic left click (button down + up) to the widget under the mapped local point, exactly as if the user had clicked that pixel of the offscreen tree. Returns true when a widget consumed it.

Clear

C++
void Clear()

PushScreen

C++
int32_t PushScreen(const std::string& assetPath, int32_t zOrder = 1000, bool modal = false)

Code-driven screens (pause menu, main menu, loading). Returns a handle for PopScreen; 0 on load failure. Modal screens contain gamepad focus and report through HasModalScreen so the host can gate game input.

PopScreen

C++
bool PopScreen(int32_t handle)

PopTopScreen

C++
bool PopTopScreen()

HasModalScreen

C++
bool HasModalScreen() const

PushedCount

C++
int32_t PushedCount() const

PlayAnimation

C++
bool PlayAnimation(const std::string& assetPath, const std::string& name)

Timeline playback on a mounted screen (world-scanned or pushed), addressed by its asset path. The two-argument form starts with the authored loop flag; the params form overrides loop/reverse and takes a completion callback (fired once, after the end pose is applied; looping runs never finish). Playing an already-running animation restarts it. Every finished run also reports through the event sink as (assetPath, "anim_finished", animationName).

PlayAnimation

C++
bool PlayAnimation(const std::string& assetPath, const std::string& name, const FArcUIAnimPlayParams& params)

StopAnimation

C++
bool StopAnimation(const std::string& assetPath, const std::string& name)

StopAllAnimations

C++
void StopAllAnimations(const std::string& assetPath)

IsAnimationPlaying

C++
bool IsAnimationPlaying(const std::string& assetPath, const std::string& name) const

DispatchAction

C++
bool DispatchAction(const std::string& assetPath, const std::string& action)

The built-in event-action vocabulary: "PlayAnim:Name", "PlayAnimReverse:Name", "StopAnim:Name". Authored widget events run through this before reaching the host's event sink; hosts and tests can dispatch the same verbs directly. Returns true when the action was one of the built-ins (whether or not the animation existed).

DispatchVisualScriptAction

C++
bool DispatchVisualScriptAction(const std::string& assetPath, const std::string& widgetName, const std::string& action)

SetWidgetText

C++
bool SetWidgetText(const std::string& assetPath, const std::string& widgetName, const std::string& text)

SetWidgetVisible

C++
bool SetWidgetVisible(const std::string& assetPath, const std::string& widgetName, bool visible)

SetWidgetProgress

C++
bool SetWidgetProgress(const std::string& assetPath, const std::string& widgetName, float percent)

FindVideoPlayer

C++
Arcf::AVideoPlayer* FindVideoPlayer(const std::string& assetPath, const std::string& widgetName) const

The VideoPlayer node under a name (empty screen path searches every screen), or null when the name is not a video — MUIStatics' seam.

SetVisualScriptBindingText

C++
void SetVisualScriptBindingText(const std::string& name, const std::string& text)

SetVisualScriptBindingNumber

C++
void SetVisualScriptBindingNumber(const std::string& name, double number)

InVisualScriptBindingEval

C++
bool InVisualScriptBindingEval() const

VisualScriptEvalsLastTick

C++
uint32_t VisualScriptEvalsLastTick() const

NotifyAssetChanged

C++
void NotifyAssetChanged(const std::string& assetPath)

Marks a loaded asset stale so the next Tick evicts and rebuilds every screen using it — the entry point the file watcher drives, public so hosts without a watcher (and tests) can force the same reload.

GetOverlayWidget

C++
Arcf::TSharedPtr<Arcf::AWidget> GetOverlayWidget() const

Tick

C++
void Tick(float deltaSeconds)

HandleDirectional

C++
bool HandleDirectional(int32_t dx, int32_t dy)

Directional navigation: spatial pick of the nearest focusable widget in the pressed direction (center-line projection with axis bias, the UE approach). Falls back to the linear cycle only when the tree has no usable geometry (headless). Focusability comes from the AWidget IsFocusable predicate, not a type whitelist. The focused widget's navigation rules (nav_up / nav_down / nav_left / nav_right on its node or an ancestor) can stop the move, wrap it at the edge, or send it to a named widget instead.

SetRightToLeft

C++
void SetRightToLeft(bool rightToLeft)

The reading order screens build with when a node says "inherit" — set from the active culture. Takes effect on the next (re)build; call before pushing, or push again after switching.

IsRightToLeft

C++
bool IsRightToLeft() const

HandleAccept

C++
bool HandleAccept()

Accept delivered as a real activate on the focused widget (the widget translates it internally — click delegate, toggle, open); no synthesized mouse events.

HandleBack

C++
bool HandleBack()

Back/cancel: a host- or screen-defined handler first, then pop of the top code-driven screen.

SetBackHandler

C++
void SetBackHandler(FBackHandler handler)

NotifyInputDevice

C++
void NotifyInputDevice(EArcUIInputDevice device)

Hosts report the device each input event came from; switching to the gamepad re-applies the focus visual, switching to the mouse clears it.

GetActiveInputDevice

C++
EArcUIInputDevice GetActiveInputDevice() const

FindNamed

C++
Arcf::TSharedPtr<Arcf::AWidget> FindNamed(const std::string& name) const

MountedCount

C++
int32_t MountedCount() const
Generated from ArcUI/CArcUIScreenStack.h via arcui.json · Nov 4, 2026Version 1.0.0