LoadingScreenWidget

LoadingScreenWidget

#Overview

name: LoadingScreenWidget

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of LoadingScreenWidget is to specify and manage the user interface widget displayed during loading screens in Unreal Engine 5 games. It is primarily used for the game’s loading screen system, allowing developers to customize the visual appearance of loading screens.

This setting variable is primarily relied upon by the CommonLoadingScreen plugin, which is part of the loading screen subsystem in Unreal Engine 5. It is also used in the LyraGame module, specifically in the user-facing experience definition.

The value of this variable is typically set in the UCommonLoadingScreenSettings class, which is a developer settings class backed by console variables (CVars). It can be configured through the project settings in the Unreal Engine editor.

LoadingScreenWidget interacts with other variables such as LoadingScreenZOrder, which determines the z-order of the loading screen widget in the viewport stack. It also works in conjunction with other loading screen-related functions and variables within the ULoadingScreenManager class.

Developers must be aware that:

  1. The LoadingScreenWidget should be a valid UUserWidget subclass.
  2. If the specified widget fails to load, the system will fall back to a default SThrobber widget.
  3. The widget is added to the viewport at a high Z-order to ensure it appears on top of most other UI elements.

Best practices when using this variable include:

  1. Ensure the specified widget class is lightweight and optimized for quick loading.
  2. Design the loading screen widget to be flexible and responsive to different screen sizes and orientations.
  3. Consider using placeholder or fallback widgets in case the main loading screen widget fails to load.
  4. Regularly test the loading screen in various scenarios to ensure it functions correctly and doesn’t introduce performance issues.
  5. Use the LoadingScreenZOrder property to fine-tune the widget’s visibility if needed.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/DefaultGame.ini:67, section: [/Script/CommonLoadingScreen.CommonLoadingScreenSettings]

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Projects/Lyra/Plugins/CommonLoadingScreen/Source/CommonLoadingScreen/Private/CommonLoadingScreenSettings.h:24

Scope (from outer to inner):

file
class        class UCommonLoadingScreenSettings : public UDeveloperSettingsBackedByCVars

Source code excerpt:

	// The widget to load for the loading screen.
	UPROPERTY(config, EditAnywhere, Category=Display, meta=(MetaClass="/Script/UMG.UserWidget"))
	FSoftClassPath LoadingScreenWidget;

	// The z-order of the loading screen widget in the viewport stack
	UPROPERTY(config, EditAnywhere, Category=Display)
	int32 LoadingScreenZOrder = 10000;

	// How long to hold the loading screen up after other loading finishes (in seconds) to

#Loc: <Workspace>/Projects/Lyra/Plugins/CommonLoadingScreen/Source/CommonLoadingScreen/Private/LoadingScreenManager.cpp:493

Scope (from outer to inner):

file
function     void ULoadingScreenManager::ShowLoadingScreen

Source code excerpt:


		// Create the loading screen widget
		TSubclassOf<UUserWidget> LoadingScreenWidgetClass = Settings->LoadingScreenWidget.TryLoadClass<UUserWidget>();
		if (UUserWidget* UserWidget = UUserWidget::CreateWidgetInstance(*LocalGameInstance, LoadingScreenWidgetClass, NAME_None))
		{
			LoadingScreenWidget = UserWidget->TakeWidget();
		}
		else
		{
			UE_LOG(LogLoadingScreen, Error, TEXT("Failed to load the loading screen widget %s, falling back to placeholder."), *Settings->LoadingScreenWidget.ToString());
			LoadingScreenWidget = SNew(SThrobber);
		}

		// Add to the viewport at a high ZOrder to make sure it is on top of most things
		UGameViewportClient* GameViewportClient = LocalGameInstance->GetGameViewportClient();
		GameViewportClient->AddViewportWidgetContent(LoadingScreenWidget.ToSharedRef(), Settings->LoadingScreenZOrder);

		ChangePerformanceSettings(/*bEnableLoadingScreen=*/ true);

		if (!GIsEditor || Settings->ForceTickLoadingScreenEvenInEditor)
		{
			// Tick Slate to make sure the loading screen is displayed immediately

#Loc: <Workspace>/Projects/Lyra/Plugins/CommonLoadingScreen/Source/CommonLoadingScreen/Private/LoadingScreenManager.cpp:559

Scope (from outer to inner):

file
function     void ULoadingScreenManager::RemoveWidgetFromViewport

Source code excerpt:

{
	UGameInstance* LocalGameInstance = GetGameInstance();
	if (LoadingScreenWidget.IsValid())
	{
		if (UGameViewportClient* GameViewportClient = LocalGameInstance->GetGameViewportClient())
		{
			GameViewportClient->RemoveViewportWidgetContent(LoadingScreenWidget.ToSharedRef());
		}
		LoadingScreenWidget.Reset();
	}
}

void ULoadingScreenManager::StartBlockingInput()
{
	if (!InputPreProcessor.IsValid())

#Loc: <Workspace>/Projects/Lyra/Plugins/CommonLoadingScreen/Source/CommonLoadingScreen/Public/LoadingScreenManager.h:99

Scope (from outer to inner):

file
class        class ULoadingScreenManager : public UGameInstanceSubsystem, public FTickableGameObject

Source code excerpt:


	/** A reference to the loading screen widget we are displaying (if any) */
	TSharedPtr<SWidget> LoadingScreenWidget;

	/** Input processor to eat all input while the loading screen is shown */
	TSharedPtr<IInputProcessor> InputPreProcessor;

	/** External loading processors, components maybe actors that delay the loading. */
	TArray<TWeakInterfacePtr<ILoadingProcessInterface>> ExternalLoadingProcessors;

#Loc: <Workspace>/Projects/Lyra/Source/LyraGame/GameModes/LyraUserFacingExperienceDefinition.h:50

Scope (from outer to inner):

file
class        class ULyraUserFacingExperienceDefinition : public UPrimaryDataAsset

Source code excerpt:

	/** The loading screen widget to show when loading into (or back out of) a given experience */
	UPROPERTY(BlueprintReadWrite, EditAnywhere, Category=LoadingScreen)
	TSoftClassPtr<UUserWidget> LoadingScreenWidget;

	/** If true, this is a default experience that should be used for quick play and given priority in the UI */
	UPROPERTY(BlueprintReadWrite, EditAnywhere, Category=Experience)
	bool bIsDefaultExperience = false;

	/** If true, this will show up in the experiences list in the front-end */