🧱 Base Widgets & Layout

Short Description

The Gorgeous UI Foundation provides specialized base classes for widgets, HUDs, and viewports to ensure consistent behavior across all interface elements.

Long Description

At the heart of the UI are the UGorgeousCommonWidget and AGorgeousHUD. These classes extend standard Unreal classes (UCommonUserWidget and AHUD) with built-in support for theme application, state-driven animations, and input consumption. By using the UGorgeousPrimaryGameLayout, developers can organize their UI into logical layers (e.g., Game, Menu, Overlay, Debug), allowing for complex z-order management and modal interaction rules.

🚀 Features

Theme Hooks: Built-in OnThemeApplied event for updating visuals when the global theme changes.
State Animations: Automatically map UI states to widget animations (e.g., playing a "FadeIn" animation when switching to the "Inventory" state).
Binding Tags: Declarative Signal Bridge integration—just set a tag on the widget to start receiving data payloads.
Layered Viewport: Manage UI layers (Game, Menu, Modal) using UGorgeousPrimaryGameLayout.
Input Consumption: Register widgets with the AGorgeousHUD to receive priority-based input events.

📚 Usage Examples

// Pushing a menu to the Menu layer
AGorgeousHUD* HUD = Cast<AGorgeousHUD>(GetWorld()->GetFirstPlayerController()->GetHUD());
HUD->PushWidgetToLayer(Layer_Menu, MyMenuClass);

Inherit from Gorgeous Common Widget. Set the Binding Tag to Data.Player.Health. Override On Theme Applied to update your progress bar's color from the theme.

`PlayAnimationByName`

Plays a widget animation by its FName. Useful for triggering animations from external logic or state changes.

Parameter Name	Type	Description
AnimName	`FName`	The name of the animation asset in the widget.

`UpdateActionIcon`

Updates the widget's icon based on its ActionTag, the current theme, and the active platform (Xbox, PS, etc.).

`RegisterInputConsumer`

Registers a widget or object to receive tag-based input from the HUD.

Parameter Name	Type	Description
Consumer	`UObject*`	The object implementing `IGorgeousInputConsumer_I`.
Context	`FGameplayTag`	The priority context for this consumer.

`PushWidgetToLayer`

Spawns and adds a widget to a specific layer in the primary game layout.

Parameter Name	Type	Description
LayerTag	`FGameplayTag`	The target layer (e.g., `UI.Layer.Menu`).
WidgetClass	`TSubclassOf<UCommonActivatableWidget>`	The widget class to spawn.

🏗️ Layering Hierarchy

graph TD
    View[Viewport]
    Primary[Primary Game Layout]
    Layer1[Game Layer: HUD]
    Layer2[Menu Layer: Inventory]
    Layer3[Overlay Layer: Toasts]
    Layer4[Debug Layer: Stats]
    
    View --> Primary
    Primary --> Layer1
    Primary --> Layer2
    Primary --> Layer3
    Primary --> Layer4

Best Practices

Layer Separation: Keep gameplay HUD elements on the "Game" layer and full-screen menus on the "Menu" layer to ensure proper input focus and rendering order.
Modular Widgets: Break your UI into small, reusable UGorgeousCommonWidget instances that each handle a single task (e.g., a "Health Bar" widget, an "Inventory Slot" widget).
Implementation via Macros: Use the UE_UI_WIDGET_INTERFACE_BOILERPLATE() macro in your C++ widget classes to quickly implement the required foundation interfaces.

Troubleshooting

Widget Not Animating: Ensure the animation name in the StateAnimations map matches the actual name of the animation in your widget Blueprint.
Input Blocked: If a widget on a lower layer is not receiving input, check if a widget on a higher layer (e.g., Menu) is capturing the input and not forwarding it.
HUD Null: Remember that AGorgeousHUD is only available on the client that owns the local player.

Technical Deep-Dive � Architecture and registration flow.
UI Processors � How property mapping and logic decoupling works.
Common UI Overview � System pillars and quick start.