FGantryLoadLedger
The C++ record of every tracked load: which load scopes are open, what they asked for and how far they have got.
Blueprint and most gameplay code never use this directly. They start tracked loads through UGantryAssetManager or the Load Assets Tracked nodes, and read the results from UGantryStreamingSubsystem. Use the ledger from C++ to record work of your own: open a scope, attach streamable handles or count manual work, and close it. FGantryLoadScopeGuard does the closing for you in synchronous code.
There is one ledger per process. Reach it through FGantryGaugeModule::GetLedger, and check for null.
Only tracked loads are seen
The ledger knows only about loads that go through it. A LoadSynchronous call or a hard UPROPERTY reference loads without a scope, so a loading screen reports "done" while the game is still loading. Route requests through UGantryAssetManager. If FGantryLoadSnapshot::EngineAsyncPackageCount is high while no scope is open, something is loading outside the ledger.
Threading
- OpenScope, AttachHandle, AddManualWork, CompleteManualWork and CloseScope may be called from any thread.
- OnScopeOpened and OnScopeClosed fire on the thread that opened or closed the scope.
- Poll runs on the game thread, and OnScopeProgress fires only from Poll.
- Every read returns a copy, which you can keep and read at leisure.
UGantryStreamingSubsystem republishes all three events on the game thread, which is what Blueprint binds to.
Members
OnScopeOpened
FGantryOnScopeEvent Signature of the ledger's scope events; the argument is a copy of the scope's state.
Broadcast when a scope opens, on the thread that called OpenScope.
OnScopeProgress
FGantryOnScopeEvent Broadcast from Poll, on the game thread, for each open scope whose counts changed.
OnScopeClosed
FGantryOnScopeEvent Broadcast when a scope closes, with its final state and counts, on the closing thread.
FGantryLoadLedger
Creates an empty ledger.
FGantryGaugeModule creates the only one a process needs.
~FGantryLoadLedger
Drops every record and the history without closing open scopes or broadcasting.
FGantryLoadLedger
Not copyable: the module owns the one ledger; reach it through FGantryGaugeModule::GetLedger.
operator=
FGantryLoadLedger & Not copy-assignable, for the same reason the ledger is not copyable.
OpenScope
FGantryHandle Opens a scope and returns its handle.
Any thread; broadcasts OnScopeOpened on the calling thread before returning.
DebugName:What a human should see, e.g. "Experience: Arena".
ReasonTag:What kind of work it is, e.g. GantryGaugeTags::Load_Scope_Experience.
ParentHandle:Optional parent, for nesting a stage inside an operation.
bUserFacing:Whether a loading bar should count this scope.
Returns: Handle to the new scope, valid until the scope closes; an invalid handle when UGantryGaugeSettings::bEnableLoadLedger is off.
AttachHandle
void Associates a streamable handle with a scope so its counts feed the scope's progress.
A scope may own several.
The handle's requested asset list is read once, here, so attach after the request is issued. The ledger holds the handle until the scope closes. A null handle is ignored; a stale scope handle logs a warning and is otherwise ignored.
AddManualWork
void Records assets that are being loaded without a streamable handle, e.g.
game feature plugins or level streaming, so they still appear in the bar. Counts of zero or less are ignored.
CompleteManualWork
void Reports completion of manually tracked work added with AddManualWork.
The completed total is clamped to the manual work requested; counts of zero or less are ignored.
CloseScope
void Closes a scope with the given final state, moves it to history and releases its streamable handles.
Safe to call twice; the second call is ignored. Broadcasts OnScopeClosed on the calling thread.
Poll
void Refreshes counts for every open scope and broadcasts OnScopeProgress for each that changed.
Cheap; call once per frame on the game thread. Per-asset detail is refreshed on the slower cadence from the settings. Does nothing while UGantryGaugeSettings::bEnableLoadLedger is off.
CaptureSnapshot
FGantryLoadSnapshot Copies a consistent view of every scope.
Safe to hold and read at leisure.
GetScopeInfo
bool Copies the current info for an open scope.
Returns false if the handle is stale.
GetScopeAssets
bool Copies the individual assets of an open scope, or of a closed one still in the recent history as it stood when it closed.
This read costs time per asset, so avoid it every frame.
Returns false and empties OutAssets if the scope is neither open nor in the history. When UGantryGaugeSettings::bTrackIndividualAssets was off as assets were attached, returns true with no entries for them.
RecordResidentAssets
void Records assets a scope asked for that were already in memory, so nothing had to load: they count as requested and loaded, and appear in its per-asset detail.
With UGantryGaugeSettings::bTrackIndividualAssets off, only the counts are recorded.
GetActiveScopeCount
int32 Returns the number of scopes currently open.
ClearHistory
void Clears finished-scope history.
Active scopes are untouched.
StartRecording
FGantryHandle Starts keeping every scope open now and every scope opened from now on, with its assets, until StopRecording.
This is what a loading screen lists; unlike the history, it has no cap.
Returns: The recording's handle; invalid while the ledger is disabled.
ReadRecording
bool Reads a recording in tree order: each scope followed by the scopes nested under it, siblings in the order they opened.
Returns: False, with OutScopes emptied, for an unknown or stopped recording.
StopRecording
void Stops a recording and drops what it kept.
Unknown handles are ignored.
SortAsTree
static void Puts scopes given in opening order into tree order and sets each one's Depth.
A scope whose parent is not among them is a root. Used by ReadRecording; public for tests and for callers ordering scopes of their own.