You are viewing documentation for v1.1. Switch to current version →

🚦 UI States

Short Description

UI States define the high-level configuration of the user interface, including layout, theming, and input mapping.

Long Description

A UI State (represented by UGorgeousUIState_DA) acts as a "preset" for the entire interface. When the UGorgeousUIFoundationSubsystem switches states, it automatically manages the transition: pushing/popping Enhanced Input contexts, applying new themes, and triggering animations on active widgets. This allows for seamless transitions between different gameplay modes, such as moving from "Exploration" (minimal HUD) to "Combat" (full HUD and restricted menus).

🚀 Features

  • Tag-Driven Identification: Each state is uniquely identified by an FGameplayTag (e.g., UI.State.Menu).
  • Input Context Management: Automatically push or pop UInputMappingContext based on the active state.
  • Dynamic Theming: Swap the active UGorgeousUITheme_DA as part of the state transition.
  • Overlay Integration: Configure which overlays (popups, sidebars) are allowed or automatically spawned in each state.
  • Transition Support: Define global animation names that widgets should react to when the state changes.

📚 Usage Examples

Create a new Gorgeous UI State Data Asset. Set the State Tag to UI.State.Gameplay and add your gameplay-specific Input Mapping Contexts.

// In your GameMode or Level Script
SwitchUIState(MyGameplayStateDataAsset);

SwitchUIState

Triggers a global UI state transition. All registered widgets are notified to play their outro animations. Once finished, the new state's input contexts and theme are applied.

Parameter Name Type Description
NewState UGorgeousUIState_DA* The state configuration to activate.
bImmediate bool If true, skips transition animations and applies the state immediately.

🔄 Transition Flow

sequenceDiagram
    participant App as Gameplay Logic
    participant Sub as UI Subsystem
    participant Widget as UGorgeousCommonWidget
    
    App->>Sub: SwitchUIState(NewState)
    Sub->>Widget: OnUIStateChanged(NewState)
    Widget->>Widget: Play Outro Animation
    Widget-->>Sub: NotifyWidgetTransitionComplete()
    Sub->>Sub: Apply Input Contexts
    Sub->>Sub: Apply Theme
    Sub->>Widget: Play Intro Animation

Best Practices

  • Granular States: Create specific states for distinct UI modes (e.g., UI.State.Inventory, UI.State.Dialogue) rather than one giant "Gameplay" state.
  • Animation Naming: Use consistent animation names (e.g., "Intro", "Outro") across all your widgets to make global transitions reliable.
  • Input Priority: Use the priority field in InputMappingContexts to ensure UI-specific inputs (like "Close Menu") always take precedence over gameplay inputs.

Troubleshooting

  • Input Contexts Leaking: If inputs from a previous state are still active, ensure the state transition actually finished and the UGorgeousUIFoundationSubsystem had a chance to pop the old contexts.
  • State Swap Blocked: If the UI hangs during a transition, check if a widget is failing to call NotifyWidgetTransitionComplete. You can use the UI.Debug.Transition console command to see which widgets are still transitioning.

🔗 Related Documents