UGantryStreamingSubsystem

#include "GantryStreamingSubsystem.h"

Engine subsystem that tells your game when to show a loading screen and what to put on it.

It exists for the whole run of the game, before any world and across every map change, so a loading screen can rely on it even between maps. Gantry decides when a screen is wanted. How long it stays, how it fades and what it looks like are up to your game.

When to show a loading screen

Should Show Loading Screen is true while any of these holds:

• a user-facing load scope is open, such as an experience loading its content;
• the game is travelling to a map, recorded as a Gantry.Load.Scope.Map scope;
• something holds the screen with Hold Loading Screen, or an object registered with Add Loading Hold (see IGantryLoadingHold) asks for it.

On Loading Screen Changed fires each time the answer changes. At the start of map travel it fires before the map loads, early enough to start the engine's movie player.

Driving a loading screen in Blueprint

• Get the subsystem (search for Gantry Streaming Subsystem under Engine Subsystems) and bind On Loading Screen Changed, for example in your game instance.
• When it fires true, add your loading widget. When it fires false, fade it out and remove it.
• While the widget is up, read Get Primary Scope each frame. Show its Debug Name, Loaded Count and Requested Count, for example "Loading the arena (37/120)", and drive a bar with Get Overall Progress.
• Get Loading Screen Reasons gives one line per reason the screen is up, for a status line.
• To list every load, call Start Load Recording when the widget appears, Get Load Recording to refresh the list, and Stop Load Recording when the widget goes away.

In C++

Reach the subsystem with UGantryStreamingSubsystem::Get(), which can return null before the engine starts and after it shuts down. Everything above has the same name without spaces, such as ShouldShowLoadingScreen and OnLoadingScreenChanged. All events fire on the game thread.

Using your own subclass

Subclass this and name the subclass in DefaultGame.ini, or under Project Settings > Plugins > Gantry Gauge:

[/Script/GantryGauge.GantryGaugeSettings]
StreamingSubsystemClass=/Script/MyGame.MyGameStreamingSubsystem

Only the selected class is created. The change takes effect on the next launch.

Asks an object every frame whether to keep the loading screen up, until removed or destroyed.

Logs this frame's active and recently finished scopes.

Backs Gantry.DumpLoading.

Returns why a loading screen should show, one line per reason: each hold's reason, then the map being travelled to or the load the game waits on.

Reads a recording as a loading screen lists it: each scope followed by the scopes nested under it, siblings in the order they opened, each with its depth and assets.

Returns aggregate 0 to 1 progress across user-facing scopes, as of this frame's snapshot.

Returns the scope a loading bar should be naming right now.

Returns this machine's frame timings, smoothed, and how many load scopes are open, for a game's own performance overlay.

Copies the individual assets of one scope, for a loading screen that names the asset it is on.

Costs time per asset, so do not call it for every scope every frame.

Works for an open scope, or a closed one still among the snapshot's Recent Scopes, as it stood when it closed. Entries exist only for assets recorded while UGantryGaugeSettings::bTrackIndividualAssets was on, including ones already in memory when asked for. Each entry's Loaded flag is as of the last per-asset refresh, or of the close.

Returns everything loading right now, as captured on this frame's tick.

Captured once per frame whether or not anyone asks, so any number of widgets can read it at no extra cost. Empty until the subsystem has ticked once.

Keeps the loading screen up until released, for a reason with no object behind it, such as "Waiting for the server".

Returns true while any user-facing scope is in flight, as of this frame's snapshot.

Returns true while the game is travelling to a map, from the request until the new world is up.

Releases a hold from Hold Loading Screen.

Unknown handles do nothing.

Stops asking an object added with Add Loading Hold.

Returns true when a loading screen should show: a user-facing load is open, a map is being travelled to, or something holds the screen.

Starts recording loads, so a loading screen can list every load since it appeared.

The recording keeps every scope open now and every scope opened until Stop Load Recording, each with its assets. The snapshot's history is capped; a recording is not. Call this when the loading screen appears.

Stops a recording and drops what it kept.

Call it when the loading screen goes away; every recording started should be stopped. Unknown recordings are ignored.

virtual bool UGantryStreamingSubsystem::ShouldCreateSubsystem(UObject *Outer) const override

Declines unless this class is the one UGantryGaugeSettings::StreamingSubsystemClass selects, or the Gantry default when that setting is empty, so exactly one instance exists.

virtual void UGantryStreamingSubsystem::Initialize(FSubsystemCollectionBase &Collection) override

Subscribes to the ledger's events and starts a core ticker that runs with or without a world.

virtual void UGantryStreamingSubsystem::Deinitialize() override

Removes the ticker and unsubscribes from the ledger.

static UGantryStreamingSubsystem * UGantryStreamingSubsystem::Get()

Returns the engine's streaming subsystem, or null before engine init and after shutdown.