UGantryLoadingLibrary
Blueprint nodes for tracked loads: read a load scope's progress, and open load scopes of your own so a loading screen can show work that is not an asset load.
Reading progress
Get Scope Progress, Is Scope Finished, Get Snapshot Progress, Is Snapshot Busy and Get Snapshot Primary Scope measure the values UGantryStreamingSubsystem hands out. For most loading screens the subsystem's own Get Overall Progress and Get Primary Scope are enough.
Showing your own work
Wrap work in a scope so the loading screen names it and counts it:
- Call Begin Load Scope with a display name, such as "Spawning the teams". Keep the handle.
- Call Add Load Scope Work with the number of steps, then Complete Load Scope Work as each step finishes. Or pass the handle to Load Assets Tracked nodes through their Parent Scope pin.
- Call End Load Scope when the work is over, also when it fails.
A user-facing scope left open keeps the loading screen up. Always end every scope you begin.
- Inherits
UBlueprintFunctionLibrary
Functions
AddLoadScopeWork
Adds units of work to a scope's total, for work that is not an asset load (spawning, level streaming, a server handshake).
| Pin | Type | Direction | Description |
|---|---|---|---|
Scope | FGantryHandle | in | The scope. |
Count = 1 | int32 | in | Units to add; zero or less is ignored. |
BeginLoadScope
Opens a load scope for work of your own, so a loading screen shows it with a name and real progress.
Close it with End Load Scope, always, including when the work fails.
Count work with Add Load Scope Work and Complete Load Scope Work, or nest Load Assets Tracked nodes inside it through their Parent Scope pin.
| Pin | Type | Direction | Description |
|---|---|---|---|
DisplayName | FString | in | What a loading bar should call this, e.g. "Preparing the arena". |
ReasonTag | FGameplayTag | in | What kind of work it is. Empty means Gantry.Load.Scope.Content. |
bUserFacing = true | bool | in | Whether a loading bar counts it. Off for background work. |
ParentScope = () | FGantryHandle | in | Optional scope to nest inside, such as a stage's Load Scope. |
| Return Value | FGantryHandle | out | The scope; invalid when the load ledger is disabled in project settings, which every other scope node accepts and ignores. |
CompleteLoadScopeWork
Marks units of work added with Add Load Scope Work as done, advancing the scope's progress.
| Pin | Type | Direction | Description |
|---|---|---|---|
Scope | FGantryHandle | in | The scope. |
Count = 1 | int32 | in | Units completed; zero or less is ignored. |
EndLoadScope
Closes a scope opened with Begin Load Scope.
Closing twice is harmless.
| Pin | Type | Direction | Description |
|---|---|---|---|
Scope | FGantryHandle | in | The scope. |
FinalState = Completed | EGantryLoadState | in | How it ended: Completed, Failed or Cancelled. |
GetLoadScopeInfo
Reads an open scope's current state.
| Pin | Type | Direction | Description |
|---|---|---|---|
Scope | FGantryHandle | in | The scope. |
OutInfo | FGantryLoadScopeInfo | out | Its name, counts and state, when open. |
| Return Value | bool | out | False when the scope is closed or the handle is invalid. |
GetScopeProgress
Returns the fraction of one scope's requested assets that have loaded, from 0 to 1.
| Pin | Type | Direction | Description |
|---|---|---|---|
Scope | FGantryLoadScopeInfo | in | Scope to measure, typically taken from a snapshot. |
| Return Value | float | out | Progress from 0 to 1. A scope that requested nothing reads 0 while open and 1 once closed. |
GetSnapshotPrimaryScope
Returns the scope a loading bar should be naming.
| Pin | Type | Direction | Description |
|---|---|---|---|
Snapshot | FGantryLoadSnapshot | in | Snapshot to search. |
| Return Value | FGantryLoadScopeInfo | out | The open user-facing scope with the most assets outstanding, or a default info with an invalid handle when none is open. |
GetSnapshotProgress
Returns aggregate 0 to 1 progress across every user-facing open scope in a snapshot.
| Pin | Type | Direction | Description |
|---|---|---|---|
Snapshot | FGantryLoadSnapshot | in | Snapshot to measure, e.g. from the streaming subsystem. |
| Return Value | float | out | Loaded over requested assets summed across user-facing scopes. When nothing has been requested yet: 0 while a user-facing scope is open, 1 when idle. |
GetTrackedAssetDisplayName
Returns a short display name for a tracked asset, without the package path.
| Pin | Type | Direction | Description |
|---|---|---|---|
Asset | FGantryTrackedAsset | in | Asset entry from a scope's per-asset detail. |
| Return Value | FString | out | The asset name, or the full path if the path has no asset name. |
IsHandleValid
Returns true when a handle has been set, for example by Begin Load Scope.
It does not say whether the scope is still open: a closed scope's handle still reads as valid.
| Pin | Type | Direction | Description |
|---|---|---|---|
Handle | FGantryHandle | in | Handle to test. |
| Return Value | bool | out | True when the handle was set; false for an empty handle. |
IsScopeFinished
Returns true once a scope has closed, whatever the outcome.
| Pin | Type | Direction | Description |
|---|---|---|---|
Scope | FGantryLoadScopeInfo | in | Scope to test. |
| Return Value | bool | out | True when the scope's state is Completed, Failed or Cancelled. |
IsSnapshotBusy
Returns true while the player is waiting on something in a snapshot.
| Pin | Type | Direction | Description |
|---|---|---|---|
Snapshot | FGantryLoadSnapshot | in | Snapshot to test. |
| Return Value | bool | out | True when any user-facing scope in the snapshot is still open. |