Loading Screens

The loading-screen system is shared by XFSDK Core and XFSDK Light.

Integration scope

Core uses the x_ CVar prefix; Light uses xl_. For the shared loading-screen controls, the remaining CVar name is identical.

Two modules cover the whole boot and level loading flow.

Startup loading screen. A plain black screen shown while the engine itself starts, before any game code or assets exist, so players see a clean frame instead of a frozen window. It needs no setup.

Loading screen manager. A Game Instance subsystem that shows your loading screen widget during level loads and keeps it up until the level is really ready.

Console variable naming

XFSDK Core	XFSDK Light
x_common_loading_screen_always_show	xl_common_loading_screen_always_show

All three loading-screen CVars listed under Settings follow the same prefix rule. The table below uses Core names; Light developers substitute xl_.

Setup in XFSDK Light

Configure the loading-screen widget for XFSDK Light.

When the loading screen shows

The manager checks these every frame, in order. The first one that applies keeps the screen up:

1. Forced on by x_common_loading_screen_always_show.
2. (Hidden) Another full-screen flow has suppressed it, such as shader precompilation.
3. No world yet, or the game state doesn't exist yet.
4. A map is loading.
5. Travel or a server connection is in progress.
6. The world has not begun play.
7. Seamless travel is in progress.
8. The game state, a player controller, one of their components, or a registered task asks for it.
9. No local player controller yet.
10. PSOs are still compiling for the new level.
11. Hold for Hold Loading Screen Additional Secs (2 s) so textures can stream in. The world renders during this hold, behind the screen.

While it is up, the manager blocks input, stops rendering the world, compiles cached PSOs faster, and gives level streaming high priority. It runs a garbage collection when it hides.

Status text

The loading screen shows what it is waiting for in the bottom-left corner, for example:

• Loading Showcase
• Starting world...
• Compiling shaders (124 remaining)
• Streaming textures...
• Or the reason a registered task gives.

It is drawn over any widget, so it needs no setup. Turn off Show Loading Status Text to place it yourself: in your widget, bind a TextBlock's Text to Get Game Instance › Get XFSDKLoadingScreenManager › Get Loading Status Text.

The screen does not redraw while Unreal loads the map itself, so the text stays on "Loading ..." until the load finishes.

Settings (shared, Core prefix)

Setting	Default	Description
Loading Screen Widget	—	Widget to show. A throbber is shown if it fails to load.
Loading Screen ZOrder	10000	Z-order in the viewport.
Show Loading Status Text	true	Draw the status line over the widget.
Hold Loading Screen Additional Secs	2.0	Extra time after loading finishes, for texture streaming.
Loading Screen Heartbeat Hang Duration	0	If above 0, reports a hang when the screen stays up this long.
Log Loading Screen Heartbeat Interval	5.0	How often to log why the screen is still up. 0 = off.
Hold … Even In Editor	false	Apply the hold in PIE too.
Force Tick Loading Screen Even In Editor	true	Show the widget on the first frame in PIE.

Console variable	Default	Description
x_common_loading_screen_hold_loading_screen_additional_secs	2.0	Runtime version of the hold setting.
x_common_loading_screen_log_loading_screen_reason_every_frame	0	Log the show/hide reason every frame. Very verbose.
x_common_loading_screen_always_show	0	Keep the loading screen visible. Handy for designing the widget.

In non-shipping builds, the -NoLoadingScreen command-line argument turns it off.

Blueprint API

XFSDKLoadingScreenManager (Get Game Instance › Get XFSDKLoadingScreenManager)

Function	Description
Get Loading Status Text	Player-facing status, e.g. "Compiling shaders (12 remaining)". Empty when about to close.
Get Debug Reason For Showing Or Hiding Loading Screen	The technical reason, updated every frame.
Set Loading Screen Suppressed (bool, Reason)	Keeps the loading screen hidden while another full-screen flow owns the screen.
Is Loading Screen Suppressed	Whether it is suppressed.

XFSDKLoadingProcessTask keeps the loading screen up from Blueprint:

Function	Description
Create Loading Screen Process Task (Reason)	Creates and registers a task. The screen stays up while it exists. The reason shows as the status text.
Set Show Loading Screen Reason	Changes the reason.
Unregister	Lets the screen close. Call it when your work is done.

In C++, implement IXFSDKLoadingProcessInterface::ShouldShowLoadingScreen(FString& OutReason) on your game state, player controller or their components, or register any object with RegisterLoadingProcessor. Bind OnLoadingScreenVisibilityChangedDelegate() to react when the screen opens or closes (music, analytics).

Planned

The loading screen module will be restructured in a future version. Setting and function names on this page may change.

References

• Epic Games. Lyra Sample Game: Common Loading Screen plugin. The loading screen manager is based on it.