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
| Alias | Description |
|---|---|
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
| Signature | Name | Description |
|---|---|---|
CArcUIScreenStack() | CArcUIScreenStack | |
~CArcUIScreenStack() | ~CArcUIScreenStack | |
CArcUIScreenStack(const CArcUIScreenStack&) = delete | CArcUIScreenStack |
Public functions
| Returns | Name | Description |
|---|---|---|
CArcUIScreenStack& | operator= | |
void | SetPathResolver | Resolves a serialized asset path ("Content/UI/x.ui") to something LoadFromFile can open. |
void | SetFocusSink | Where directional nav sends the newly focused widget (host wires this to its Arc input processor's SetFocus). |
void | SetBindingResolver | Supplies the current value for a widget data-binding source. |
void | SetEventSink | Receives (widgetName, eventName, action) for every authored widget event that fires. |
void | InstallVfsPathResolver | Convenience installers so every host mounts identically. |
void | InstallBridgeFocusSink | |
void | InstallWorldBindingResolver | |
void | EnableHotReload | Watches every loaded .ui file and rebuilds its screens on save. |
uint32_t | LoadLocalization | 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. |
bool | SetProjectTheme | Theme every screen without its own theme: resolves colour tokens against. |
const FArcUITheme& | GetActiveTheme | |
void | SetSafeZoneInsets | 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). |
void | SyncFromWorld | |
void | SyncWorldWidgets | Places every visible ArcUIWorldWidgetComponent's tree at its entity's projected screen position. |
void | SyncWorldWidgets3D | |
void | MarkWorldWidgetDirty | Marks a world widget's offscreen texture stale so the next SyncWorldWidgets3D re-renders it. |
void | RecordPendingWorldWidgets | |
FArcUIWorldHit | HitTestWorldWidgets | Ray-vs-quad hit test against the interactive world-widget quads resolved by the last SyncWorldWidgets3D, nearest hit first. |
bool | RouteWorldWidgetClick | 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. |
void | Clear | |
int32_t | PushScreen | Code-driven screens (pause menu, main menu, loading). |
bool | PopScreen | |
bool | PopTopScreen | |
bool | HasModalScreen | |
int32_t | PushedCount | |
bool | PlayAnimation | Timeline playback on a mounted screen (world-scanned or pushed), addressed by its asset path. |
bool | PlayAnimation | |
bool | StopAnimation | |
void | StopAllAnimations | |
bool | IsAnimationPlaying | |
bool | DispatchAction | The built-in event-action vocabulary: "PlayAnim:Name", "PlayAnimReverse:Name", "StopAnim:Name". |
bool | DispatchVisualScriptAction | |
bool | SetWidgetText | |
bool | SetWidgetVisible | |
bool | SetWidgetProgress | |
Arcf::AVideoPlayer* | FindVideoPlayer | The VideoPlayer node under a name (empty screen path searches every screen), or null when the name is not a video — MUIStatics' seam. |
void | SetVisualScriptBindingText | |
void | SetVisualScriptBindingNumber | |
bool | InVisualScriptBindingEval | |
uint32_t | VisualScriptEvalsLastTick | |
void | NotifyAssetChanged | 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. |
Arcf::TSharedPtr<Arcf::AWidget> | GetOverlayWidget | |
void | Tick | |
bool | HandleDirectional | Directional navigation: spatial pick of the nearest focusable widget in the pressed direction (center-line projection with axis bias, the UE approach). |
void | SetRightToLeft | The reading order screens build with when a node says "inherit" — set from the active culture. |
bool | IsRightToLeft | |
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. |
bool | HandleBack | Back/cancel: a host- or screen-defined handler first, then pop of the top code-driven screen. |
void | SetBackHandler | |
void | NotifyInputDevice | Hosts report the device each input event came from; switching to the gamepad re-applies the focus visual, switching to the mouse clears it. |
EArcUIInputDevice | GetActiveInputDevice | |
Arcf::TSharedPtr<Arcf::AWidget> | FindNamed | |
int32_t | MountedCount |
Function details
CArcUIScreenStack
CArcUIScreenStack()~CArcUIScreenStack
~CArcUIScreenStack()CArcUIScreenStack
CArcUIScreenStack(const CArcUIScreenStack&) = deleteoperator=
CArcUIScreenStack& operator=(const CArcUIScreenStack&) = deleteSetPathResolver
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
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
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
void SetEventSink(FArcUIEventSink sink)Receives (widgetName, eventName, action) for every authored widget event that fires. Optional; without it events are dropped.
InstallVfsPathResolver
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
void InstallBridgeFocusSink()InstallWorldBindingResolver
void InstallWorldBindingResolver(FArcUIBindingLibrary::FWorldProvider world, FArcUIBindingLibrary::FEntityLookup lookup, FArcUIBindingLibrary::FCustomSourceHook customHook = FArcUIBindingLibrary::FCustomSourceHook())EnableHotReload
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
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
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
const FArcUITheme& GetActiveTheme() constSetSafeZoneInsets
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
void SyncFromWorld(World& world)SyncWorldWidgets
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
void SyncWorldWidgets3D(World& world, const FArcUIViewInfo& view, const FWorldQuadSink& sink)MarkWorldWidgetDirty
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
void RecordPendingWorldWidgets()HitTestWorldWidgets
FArcUIWorldHit HitTestWorldWidgets(const Vec3& rayOrigin, const Vec3& rayDir) constRay-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
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
void Clear()PushScreen
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
bool PopScreen(int32_t handle)PopTopScreen
bool PopTopScreen()HasModalScreen
bool HasModalScreen() constPushedCount
int32_t PushedCount() constPlayAnimation
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
bool PlayAnimation(const std::string& assetPath, const std::string& name, const FArcUIAnimPlayParams& params)StopAnimation
bool StopAnimation(const std::string& assetPath, const std::string& name)StopAllAnimations
void StopAllAnimations(const std::string& assetPath)IsAnimationPlaying
bool IsAnimationPlaying(const std::string& assetPath, const std::string& name) constDispatchAction
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
bool DispatchVisualScriptAction(const std::string& assetPath, const std::string& widgetName, const std::string& action)SetWidgetText
bool SetWidgetText(const std::string& assetPath, const std::string& widgetName, const std::string& text)SetWidgetVisible
bool SetWidgetVisible(const std::string& assetPath, const std::string& widgetName, bool visible)SetWidgetProgress
bool SetWidgetProgress(const std::string& assetPath, const std::string& widgetName, float percent)FindVideoPlayer
Arcf::AVideoPlayer* FindVideoPlayer(const std::string& assetPath, const std::string& widgetName) constThe VideoPlayer node under a name (empty screen path searches every screen), or null when the name is not a video — MUIStatics' seam.
SetVisualScriptBindingText
void SetVisualScriptBindingText(const std::string& name, const std::string& text)SetVisualScriptBindingNumber
void SetVisualScriptBindingNumber(const std::string& name, double number)InVisualScriptBindingEval
bool InVisualScriptBindingEval() constVisualScriptEvalsLastTick
uint32_t VisualScriptEvalsLastTick() constNotifyAssetChanged
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
Arcf::TSharedPtr<Arcf::AWidget> GetOverlayWidget() constTick
void Tick(float deltaSeconds)HandleDirectional
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
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
bool IsRightToLeft() constHandleAccept
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
bool HandleBack()Back/cancel: a host- or screen-defined handler first, then pop of the top code-driven screen.
SetBackHandler
void SetBackHandler(FBackHandler handler)NotifyInputDevice
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
EArcUIInputDevice GetActiveInputDevice() constFindNamed
Arcf::TSharedPtr<Arcf::AWidget> FindNamed(const std::string& name) constMountedCount
int32_t MountedCount() const