Reference for the guide's inspected source revision. Start from the complete C# examples for working context.
Start a request#
| Method | Use |
|---|---|
LoadScene(string/int, layout, behaviour) | Start a mapped destination load with optional layout/behavior overrides. |
CreateSceneRequest(string/int, layout, behaviour) | Create an unstarted request, configure it, then pass it to Show. |
Show(LoadingRequest) | Start configured scene/custom work. Reject/Queue controls busy behavior. |
RunTimer(seconds, layout, behaviour) | Timed presentation without a scene operation; another overload uses authored duration. |
TransitionOnly(layout, behaviour) | No-scene Scene Out/In presentation. |
Configure before Show. Effective settings freeze at execution start. Keep queued transient configuration alive until then. Use a temporary behavior copy for per-call changes instead of changing shared saved assets.
Active-request controls#
| Method | Use |
|---|---|
Continue(handle = null) | Satisfy an applicable player gate, subject to policy. |
SkipVideo(handle = null) | Skip when allowed; cannot bypass work/readiness. |
Cancel(handle = null) | Request cancellation; native in-flight work must settle. |
ReportProgress(value, handle = null) | Visual 0–1 Manual progress. Reject NaN/infinity; clamp finite values. |
SetStatus(text, handle = null) | Override stage copy; null restores it. |
SignalReady(checkpointId) | Signal an armed checkpoint on Active. |
SignalReady(requestId, checkpointId) | Request-scoped signaling for delayed callbacks. |
RetryCheckpoint / ReturnToMenu / DismissFailure | Supported checkpoint recovery, configured safe menu or failure dismissal. |
Omitted handles target Active. A true result means the instruction was accepted; configured gates decide its effect. Manual progress does not complete real work. Native Single activation cannot be undone by Cancel.
Status and results#
| Property | Meaning |
|---|---|
Active / IsLoading / State | Active handle, busy flag and nullable lifecycle state. |
Progress / ProgressPercent | Nullable 0–1 fraction / 0–100 value; null means idle or unknown. |
DestinationScene / CurrentLayout | Canonical destination and selected source design. |
Stage / Status / Error | Lifecycle description, status override and active error. |
IsReady | Required readiness finished; optional presentation may remain. |
IsPostLoading / GameplayHeld / CanSkipVideo | Ready screen state, destination hold and Skip availability. |
Registry | Automatically loaded scene registry or a session override. |
Keep the handle for Scene/Layout/Context/State/Progress/Error after completion. Active becomes null when idle. Blank/ambiguous scene arguments and invalid indices can throw before start. Execution failures are recorded on the handle. Cancellation also uses Failed notifications, so inspect State.
Lifecycle milestones#
| Phase | Events |
|---|---|
| Start and measured work | OnRequest, OnEnter, OnLoadStarted, OnProgress, OnLoadReady |
| Destination | OnActivating, OnActivated, OnReadinessStarted, OnGameReady |
| Optional flow | OnVideoPlayback, OnPostLoading, OnPostLoadingContinue |
| Finish | OnExit, OnComplete, OnFailed |
OnActivated only emits for an operation that activates a destination. Final full progress follows required readiness. OnGameReady means required readiness finished; OnComplete means the entire presentation and gameplay hold exited.
Input and renderer hooks#
| Hook | Use |
|---|---|
DevicePressed / DeviceHeld | Func<LoadingInputKind, bool> callbacks. Separate a fresh press from held state. |
ContinuePressed / ContinueHeld | Legacy Func<bool> callbacks; take precedence when assigned. Clear owned callbacks to use filtered hooks. |
AcquireGameplayBlock | Return an IDisposable scope that restores only its own held gameplay state. |
ConfigureEventSystem | Configure the overlay's EventSystem. |
PresentationFactory | Supply an ILoadingPresentation custom renderer. |
ILoadingFlowPresentation | Optional video hiding/playback and post/gameplay transitions. |
IPostLoadingCountdownPresentation | Optional countdown rendering. |
ILoadingIndicator | Custom prefab graphic receiving progress, stage, ready, elapsed time and Reduced Motion. |
The indicator contract is UpdateIndicator(float? progress, string stage, bool ready, float elapsed, bool reducedMotion). Null progress means unknown work. Custom prefab scripts do not execute in the Designer canvas. Set hooks before starting requests and clear only hooks your component owns.
Session audio#
LoadingScreenBuilder.MasterVolume = 0.8f;
LoadingScreenBuilder.MusicVolume = 0.5f;
LoadingScreenBuilder.AmbienceVolume = 0.7f;
LoadingScreenBuilder.SfxVolume = 0.6f;
LoadingScreenBuilder.Muted = true;Session levels clamp to 0–1 and multiply authored playback. They do not rewrite the saved design, unrelated mixer settings or AudioListener settings.