ANSUIPlayerSubsystem
Overview
The UANSUIPlayerSubsystem is a Game Instance Subsystem designed to manage UI navigation and widget handling in your game. Its primary responsibilities include:
Spawning and Removing Widgets:
Easily add and remove UI widgets from the player's viewport while handling game pause states and input locking.UI Navigation:
Manage widget stack navigation with features like returning to a previous widget.Key Bindings and Icon Management:
Query UI action mappings based on keys, retrieve icons for specific UI actions or keys, and manage input settings.Focus Management:
Broadcast changes in the currently focused widget via theOnFocusChangeddelegate.
Setup and Initialization
Because UANSUIPlayerSubsystem derives from UGameInstanceSubsystem, it is automatically created and managed by Unreal Engine when your game instance starts. To use it:
Access the Subsystem:
Retrieve the subsystem from the game instance using theGetSubsystem<>()function.// Example: Retrieving the UI Player Subsystem in C++ UANSUIPlayerSubsystem* UIPlayerSubsystem = GetGameInstance()->GetSubsystem<UANSUIPlayerSubsystem>(); if (!UIPlayerSubsystem) { UE_LOG(LogTemp, Error, TEXT("Failed to get UANSUIPlayerSubsystem")); return; }Blueprint Access:
The functions exposed as BlueprintCallable allow you to call them directly from your Blueprints, making it simple for UI designers to add or remove widgets without writing any code.
Key Functions and Their Usage
1. Spawning a Widget
Function:
SpawnInGameWidgetDescription:
Adds a widget to the local viewport. Optionally, it can pause the game and lock UI input while the widget is active.Parameters:
widgetClass: The widget class to spawn.bPauseGame(defaulttrue): If true, the game will be paused.bLockGameInput(defaulttrue): If true, game input will be locked (useful when a modal UI is active).
Usage Example (C++):
UUserWidget* MyWidget = UIPlayerSubsystem->SpawnInGameWidget(MyWidgetClass, true, true); if (MyWidget) { UE_LOG(LogTemp, Log, TEXT("Widget spawned successfully")); }Usage Example (Blueprint):
Call theSpawnInGameWidgetnode, pass in the widget class, and set the pause and input lock options as needed.
2. Removing a Widget
Function:
RemoveInGameWidgetDescription:
Removes a widget from the local viewport and can optionally unlock UI input and remove any game pause state.Parameters:
widget: The widget instance to remove.bUnlockUIInput(defaulttrue): If true, re-enables UI/game input.bRemovePause(defaulttrue): If true, resumes the game if it was paused.
Usage Example:
UIPlayerSubsystem->RemoveInGameWidget(MyWidget, true, true);
3. Navigating Widget Stack
Function:
GoToPreviousWidgetDescription:
Navigates back to the previous widget in the widget stack.Usage Example:
UIPlayerSubsystem->GoToPreviousWidget();
4. Querying Key Bindings and Actions
Function:
TryGetActionsFromKeyDescription:
Retrieves an array of UI action tags associated with a specified key.Usage Example:
TArray<FUIActionTag> ActionTags; if (UIPlayerSubsystem->TryGetActionsFromKey(FKey("Enter"), ActionTags)) { // Process the returned action tags... }Function:
TryGetKeysForActionDescription:
Retrieves the keys mapped to a specific UI action.Usage Example:
TArray<FKey> Keys; if (UIPlayerSubsystem->TryGetKeysForAction(MyUIActionTag, Keys)) { // Use the keys as needed... }
5. Icon Retrieval Functions
These functions allow you to retrieve icons for specific UI actions or keys based on the current platform or a provided platform string.
GetIconByTag: Returns an icon based on a gameplay tag.
GetIconForUIAction: Returns an icon for a specified UI action.
GetCurrentPlatformIconForKey: Returns the icon for a given key on the current platform.
GetIconForKey: Returns the icon for a given key for a specified platform.
Usage Example:
UTexture2D* ActionIcon = UIPlayerSubsystem->GetIconForUIAction(MyUIActionTag, ECommonInputType::MouseAndKeyboard); if (ActionIcon) { // Display the icon in your UI... }
6. Focus Change Notification
Delegate:
FOnFocusedWidgetChangedDescription:
This dynamic multicast delegate broadcasts whenever the focused widget changes. You can bind your own functions to this delegate to handle focus changes.Usage Example (Blueprint):
In Blueprints, bind an event toOnFocusChangedto update UI elements or trigger other logic when focus changes.
Private Utility Functions
The subsystem includes private helper functions (e.g., GetInputSettings, GetUISettings) to retrieve internal configuration objects. These are not exposed to Blueprints but are used internally by the public functions.
Example Usage Scenario
Imagine you want to display a pause menu when the player presses a specific key and then remove it when the player unpauses:
Displaying the Pause Menu:
// Get the UI Player Subsystem UANSUIPlayerSubsystem* UIPlayerSubsystem = GetGameInstance()->GetSubsystem<UANSUIPlayerSubsystem>(); // Spawn the pause menu widget (assuming PauseMenuClass is a TSubclassOf<UUserWidget> set up in your game) UUserWidget* PauseMenu = UIPlayerSubsystem->SpawnInGameWidget(PauseMenuClass, true, true); if (PauseMenu) { UE_LOG(LogTemp, Log, TEXT("Pause menu displayed")); }Hiding the Pause Menu:
// Remove the pause menu widget and resume the game UIPlayerSubsystem->RemoveInGameWidget(PauseMenu, true, true); UE_LOG(LogTemp, Log, TEXT("Pause menu removed and game resumed"));Navigating Back in the Widget Stack:
// Navigate back to the previous widget (if any) UIPlayerSubsystem->GoToPreviousWidget();
Conclusion
The UANSUIPlayerSubsystem provides a centralized way to manage UI widgets, input, and navigation in your game. By leveraging its functions, you can streamline your UI flow, easily pause/resume gameplay during UI interactions, and manage key-to-action mappings and icons for various platforms.
For further customization, review the developer settings accessed through GetUISettings() (not exposed publicly) to tailor the UI behavior to your project's needs.
Use this documentation as a guide to integrate the subsystem into your game logic and enhance your UI navigation experience.