Skip to content

Loading screens

Gantry tracks loading as named, counted steps called load scopes: "Environment, 12 of 40", "Activating game features, 2 of 3". Every load Gantry does is tracked this way, and so is every load your game makes through Gantry's asset manager or its Blueprint nodes. A loading screen can then show real progress, name what it is waiting for, and know exactly when to appear and when to go.

Gantry draws no loading screen. Your game builds one in UMG (the example project's is WBP_YR_LoadingScreen) and asks Gantry what to show.

When to show it

The Gantry Streaming Subsystem (an engine subsystem, so it works before any world exists and across map travel) answers in one place:

  • Should Show Loading Screen is true while a load the player waits on is in progress, while the game travels to a map, or while something holds the screen up.
  • On Loading Screen Changed fires when that answer changes, including the moment map travel starts, early enough to start the engine's movie player.
  • Get Loading Screen Reasons lists why, one line each, which is useful while building the screen.

Something can keep the screen up for reasons of its own: a player state still arriving, a pawn still setting up, a fade still running.

  • Hold Loading Screen and Release Loading Screen Hold: for a hold with a reason and no object behind it.
  • Add Loading Hold: registers an object that implements Gantry Loading Hold. Gantry asks it every frame whether to keep holding, until it says no, is removed, or is gone.

How long the screen stays, how it fades and what it looks like are up to your game.

What to show

  • Get Primary Scope: the scope a loading bar should name right now, with its name and counts.
  • Get Overall Progress: 0 to 1 across every load the player waits on.
  • Get Current Stage Name and Get Stage Progress, on the experience subsystem: which stage of an experience is running, as "step 2 of 5".
  • Start Load Recording and Get Load Recording: every scope opened from a moment on, nested as they were, for a screen that lists what loaded.

Each scope has a tag. Gantry's own loads use Gantry.Load.Scope.* tags (startup, experiences, game features, map travel); your own loads use any tag you like. Whether the player waits on a scope is its own setting, not its tag.

Loading through Gantry

A load counts only if it goes through Gantry. In Blueprint:

  • Load Assets Tracked and Load Primary Assets Tracked load assets in the background inside a named scope. On Completed fires with the objects, in the order asked for; On Cancelled fires instead if the load is cancelled. Exactly one of the two fires. The objects stay loaded only while something references them, so store them in a variable to keep them.

In C++, UGantryAssetManager::RequestAsyncLoadTracked and PreloadPrimaryAssetsTracked do the same, and FGantryLoadScopeGuard opens and closes a scope around synchronous work.

All of this needs Gantry's asset manager as the project's asset manager (Getting Started has the one line). Without it the Blueprint nodes still load, untracked, and log a warning.

THE LOADING SCREEN IS ONLY AS HONEST AS THE LOADS IT CAN SEE. A Load Synchronous call or a hard asset reference loads outside Gantry, and the screen can report "done" while the game is still loading. Route loads through the tracked nodes or the asset manager. Warn On Blocking Loads (Project Settings > Plugins > Gantry Gauge) logs synchronous loads that slip through.

The Load Gauge panel

In the editor, the Load Gauge panel shows every scope live while you play: what is loading, how far along it is, and which scope a hitch belongs to. Open it from Tools > Gantry, the Gantry button on the level editor toolbar, or Tools > Debug. When a play session ends, Gantry checks for scopes that never finished, which almost always means a load that never reported completion. Editor Preferences > Plugins > Gantry Gauge sets what it does.