API Reference
Types are in the CrimsonLoadingScreen runtime module unless noted. BP (pure) = pure Blueprint node; BP = Blueprint-callable with exec pins; C++ only = no Blueprint node.
UCrimsonLoadingScreenManager
UGameInstanceSubsystem + FTickableGameObject. Never creates on dedicated servers. Obtain: Blueprint uses the subsystem getter node (search Crimson Loading Screen Manager); C++ uses static UCrimsonLoadingScreenManager* Get(const UObject* WorldContextObject) (C++ only).
| Member | Access | Description |
|---|---|---|
GetCurrentTip() / GetCurrentTipCategory() | BP (pure) | Tip FText / FGameplayTag picked for this load; empty/invalid without a TipsCollection |
GetCurrentBackground() | BP (pure) | UMaterialInterface* picked for this load; null without a BackgroundCollection |
GetShowcaseRenderTarget() | BP (pure) | The configured render target; null unless `bUseLivePreview` is on AND a host has declared `SetShowcaseLive(true)` |
SetShowcaseLive(bool) | BP | Declared by the showcase host while its capture is actively writing the render target; gates the getter above |
IsShowcaseLive() | BP (pure) | True while a showcase host has declared itself live |
OnShowcaseLiveChanged / On Showcase Live Changed | Delegate (native + BP) | (bool bLive) - fires on every actual change. The built-in showcase goes live several frames after the widget is built (the stage level streams in first), so widgets re-run their content pass on this rather than only at construct time. |
OnShowcaseRosterChanged / On Showcase Roster Changed | Delegate (native + BP) | (const TArray<FCrimsonLoadingCharacterInfo>& Roster) - fires when a new companion is registered or a companion is removed while the screen is up. Never fires while the screen is hidden. |
GetCachedShowcaseRoster() | BP (pure) | const TArray<FCrimsonLoadingCharacterInfo>& - what this load is presenting: the registered primary at index 0, then companions in registration order. Empty when nothing is registered or the showcase is suppressed. A snapshot, safe while the pawns are gone. |
ClearCachedCharacterInfo() | BP | Retracts the registered primary and every companion, so the next loading screen shows its normal presentation. Call on a character switch or when leaving a session. |
UpdateCachedCharacterInfo(CharacterInfo) | BP | Registers the local player's character - the showcase primary, roster index 0, and the only way character data reaches the showcase. Lives on the game instance, so it survives every travel. Invalid descriptions are ignored. Never rebuilds a screen that is already up. |
AddShowcaseCompanion(CompanionId, CharacterInfo) | BP | Registers a second, third, ... character under a key you own. Re-adding an id replaces that look in place; a None id or invalid info is ignored. A new id registered while the screen is up rebuilds the roster and fires OnShowcaseRosterChanged. |
RemoveShowcaseCompanion(CompanionId) | BP | Drops one companion registration. Unknown ids are ignored. |
ClearShowcaseCompanions() | BP | Drops every companion registration, leaving the primary. |
SetNextLoadPresentation(Presentation, bPersistAcrossLoads) | BP | Per-load overrides (suppress showcase, background/widget/tip category); one-shot unless persistent |
ClearLoadPresentation() | BP | Drop any active presentation overrides |
GetLoadPresentation() | BP (pure) | The FCrimsonLoadingPresentation the current/next screen will use |
GetLoadingScreenDisplayStatus() | BP (pure) | True while the widget is on the viewport |
GetDebugReasonForShowingOrHidingLoadingScreen() | BP (pure) | Human-readable current show/hide reason |
OnLoadingScreenVisibilityChanged | C++ only (native multicast) | (bool bIsVisible) - fires on show (before widget creation) and hide |
OnLoadingScreenContentReady | C++ only (native multicast) | (const TArray<FCrimsonLoadingCharacterInfo>& Roster) - fires just before the screen becomes visible, after the cinematic actors are notified |
On Loading Screen Visibility Changed (OnLoadingScreenVisibilityChangedBP) | BP (assignable) | Blueprint mirror of the native visibility delegate |
On Loading Screen Content Ready (OnLoadingScreenContentReadyBP) | BP (assignable) | Blueprint mirror of the native content-ready delegate |
RegisterLoadingProcessor / UnregisterLoadingProcessor | C++ only | Add/remove an external ICrimsonLoadingProcessInterface vote (stored weakly) |
GetShaderPrecompileState() | BlueprintPure | ECrimsonShaderPrecompileState. Reveal shader UI only on Precompiling. |
GetShaderPrecompileProgress() | BlueprintPure | 0..1. Advisory - the bar can stall below 1.0; completion is delegate-driven. |
GetShaderPrecompilePSOsRemaining() | BlueprintPure | Outstanding PSOs. Clamped to a minimum of 1 by the engine while precompiling. |
GetShaderPrecompilePSOsTotal() | BlueprintPure | Batch size. Estimated if the precompile began before the plugin module loaded. |
IsBlockingOnShaderPrecompile() | BlueprintPure | True while the shader gate specifically is holding the screen. |
RequestBlockUntilShaderPrecompileComplete() | BlueprintCallable | Hold until the batch finishes. Only meaningful in BackgroundThenBlockOnPlay; no-op once complete. |
OnShaderPrecompileProgress / ...BP | Delegate | (float Progress, int32 Remaining, int32 Total). Fires when the outstanding count changes. |
OnShaderPrecompileComplete / ...BP | Delegate | Fires once when the batch finishes. |
UCrimsonLoadingScreenSettings
UDeveloperSettings (Config=Game, DefaultConfig): Project Settings -> Crimson -> Crimson Loading Screen, persisted to DefaultGame.ini under [/Script/CrimsonLoadingScreen.CrimsonLoadingScreenSettings]. Not Blueprint-exposed - runtime values surface through the manager getters. C++: GetDefault<UCrimsonLoadingScreenSettings>().
| Property | Section | Type | Default | Notes |
|---|---|---|---|---|
LoadingScreenWidget | Display | FSoftClassPath (UUserWidget) | empty | Falls back to SThrobber + error log when unset/unloadable |
LoadingScreenZOrder | Display | int32 | 10000 | Viewport Z-order of the widget |
HoldLoadingScreenAdditionalSecs | Timing | float (s) | 2.0 | Seeds the hold CVar at startup; console/cmdline CVar set overrides; skipped in editor unless the Debugging toggle is on |
LoadingScreenHeartbeatHangDuration | Timing | float (s) | 0.0 | Non-zero = hang detector fires after this much continuous visibility; 0 = off |
LogLoadingScreenHeartbeatInterval | Timing | float (s) | 5.0 | Seconds between 'still showing because...' log lines; 0 = off |
TipsCollection | Tips | TSoftObjectPtr<UCrimsonLoadingTipsCollection> | null | Null = no tip text |
bPickNewTipEachLoad | Tips | bool | true | false = one tip per session |
TipCategoryFilter | Tips | FGameplayTag | empty | When set, only matching-Category tips are candidates |
BackgroundCollection | Backgrounds | TSoftObjectPtr<UCrimsonLoadingBackgroundCollection> | null | Null = no background |
bPickNewBackgroundEachLoad | Backgrounds | bool | true | false = one background per session |
bUseLivePreview | Cinematic Preview | bool | false | Master switch for the showcase. Keeps world rendering ON during loads so the capture keeps updating; unlocks the fields below. |
ShowcaseRenderTarget | Cinematic Preview | TSoftObjectPtr<UTextureRenderTarget2D> | null | EditCondition: bUseLivePreview. Its size sets the preview's aspect ratio, which the automatic framing fits the characters to. |
ShowcaseStageLevel | Cinematic Preview | TSoftObjectPtr<UWorld> | null | Optional level streamed into the pocket world as the set. Unset = the built-in studio stage in an empty world, which is also the fallback when the level cannot be used. Plain non-World-Partition maps only. |
ShowcaseStageClass | Cinematic Preview | TSoftClassPtr<ACrimsonShowcaseStage> | ACrimsonShowcaseStage | Stage spawned when the stage level does not place one itself. Subclass it to change the built-in lighting, framing or formation defaults. |
MaxShowcaseCharacters | Cinematic Preview | int32 | 8 | Most characters presented at once; the primary is always first. Clamped to a minimum of 1. |
ShowcaseStageLoadTimeoutSecs | Cinematic Preview | float (s) | 10.0 | How long to wait for ShowcaseStageLevel to become visible before falling back to the built-in studio stage. Minimum 0.5. |
bForceTickLoadingScreenEvenInEditor | Debugging | bool | true | Force one Slate tick on show in PIE so the widget appears immediately |
bHoldLoadingScreenAdditionalSecsEvenInEditor | Debugging | bool (Transient) | false | Apply the hold delay in PIE; not saved to config |
bEnableShaderPrecompileGate | Shader Precompilation | bool | true | Master switch for all PSO precompile handling. |
ShaderPrecompileGateMode | Shader Precompilation | ECrimsonShaderPrecompileGateMode | BlockUntilComplete | Whether and when a precompile holds the screen. |
ShaderPrecompileGraceSecs | Shader Precompilation | float | 2.0 | Hold silently this long before revealing shader UI. |
MaxShaderPrecompileBlockSecs | Shader Precompilation | float | 0.0 | Hard cap on the hold; 0 means none. Backstop only. |
bRunShaderPrecompileGateInEditor | Shader Precompilation | bool | false | Editor never opens a bundled cache; use SimulateSecs instead. |
bHoldForRuntimePSOPrecache | Runtime PSO Precache | bool | false | Drain outstanding precache requests before the screen hides. |
RuntimePSOPrecacheMinPriority | Runtime PSO Precache | ECrimsonPSOPrecacheWaitPriority | HighAndAbove | Feeds r.PSOPrecaching.MinPriorityForActivePrecacheRequests. |
RuntimePSOPrecacheThreshold | Runtime PSO Precache | int32 | 0 | Outstanding requests tolerated before hiding. |
MaxRuntimePSOPrecacheWaitSecs | Runtime PSO Precache | float | 10.0 | Cap on the drain. Not optional. |
Hold votes
| Type | Kind | Description |
|---|---|---|
ICrimsonLoadingProcessInterface | UInterface | C++ only to implement (plain virtual ShouldShowLoadingScreen(FString& OutReason)). Auto-polled on GameState, local PlayerControllers, and all their components; other objects register via the manager. Static helper ShouldShowLoadingScreen(UObject*, FString&) tests any object. |
UCrimsonLoadingProcessTask | UObject + the interface | BP: CreateLoadingScreenProcessTask(WorldContextObject, Reason) (static factory - keep the returned reference in a variable!), Unregister(), SetShowLoadingScreenReason(Reason). Held weakly by the manager: dropping every reference lets GC release the hold automatically. |
Tips & backgrounds
| Type | Kind | Description |
|---|---|---|
FCrimsonLoadingTip | Struct (BlueprintType) | Text (FText), Category (FGameplayTag), Weight (float, min 0.01, default 1.0). All read-only in BP. |
UCrimsonLoadingTipsCollection | UDataAsset | Tips array. BP: GetRandomTip(CategoryFilter, OutTip) - weighted random, category-filtered, returns false when nothing matches. |
UCrimsonLoadingBackgroundCollection | UDataAsset | Backgrounds - TArray<TSoftObjectPtr<UMaterialInterface>>, loaded on demand per pick. |
Cinematic preview
| Type | Kind | Description |
|---|---|---|
ICrimsonLoadingCharacterProvider | UInterface (BP-implementable) | GetLoadingCharacterInfo(OutInfo) -> bool - BlueprintNativeEvent. Implement on the object that owns the authoritative appearance data (usually an equipment or appearance component on the pawn) and have the caller register the result. The manager does not search for implementors. |
ICrimsonLoadingCinematicInterface | UInterface (BP-implementable) | OnLoadingScreenStarted(const TArray<FCrimsonLoadingCharacterInfo>& Roster) / OnLoadingScreenEnded() - BlueprintNativeEvents; sent to every actor in the current world on show/hide. A director that writes the render target itself must call SetShowcaseLive(true) from the started event, which makes the built-in showcase stand down. |
FCrimsonLoadingCharacterInfo | Struct (BlueprintType) | MeshComponents, AdditionalActors - both readable and writable in BP. C++-only helpers: IsValid() (a leader with a mesh exists), GetLeaderComponent(). |
FCrimsonLoadingMeshComponent | Struct (BlueprintType) | SlotName, Mesh (null = empty slot), Materials, AnimInstanceClass (leader only), bIsLeader, RelativeTransform. All BP-writable. |
FCrimsonLoadingActorEntry | Struct (BlueprintType) | ActorTypeTag, Mesh (skeletal), StaticMesh (static - the usual case for equipment visuals; a valid entry sets exactly one of the two), Materials, AnimInstanceClass, AttachSocketName (None = free placement), RelativeTransform. All BP-writable. C++-only IsValid() (true when either mesh is set). |
FCrimsonLoadingShowcaseCompanion | Struct (BlueprintType) | One companion registration: CompanionId (your key; None is rejected) and Info. Both BP-writable. You rarely build one by hand - AddShowcaseCompanion takes the two fields. |
UCrimsonShowcaseSubsystem | UGameInstanceSubsystem | The built-in showcase host. Creates the pocket world, streams ShowcaseStageLevel, resolves or spawns the stage, ticks and captures at 30 Hz, and tears it all down on hide. Never creates on a dedicated server. BP (pure): IsShowcaseActive(). Everything else is internal - it is driven by the manager's delegates, not called. |
ACrimsonShowcaseStage | AActor (Blueprintable) | The set. BP: ApplyRoster(Roster), ClearShowcase(), SetRenderTarget(RenderTarget), CaptureFrame(), SetStudioSetupEnabled(bEnabled). Editable defaults: TurntableSpeed (18), CameraDistance (800), CameraHeight (120), LookAtHeight (95), CameraFOV (32), FramingPadding (1.15), FormationLateralStep (75), FormationRowDepth (120), FormationFrontRowInset (30), FormationArcDepthPerStep (8), FormationYawPerStep (3), bStudioSetupEnabled (true). |
ACrimsonShowcaseSlot | AActor (Blueprintable) | A standing mark in a stage level. SlotIndex (0 is the primary) plus a transform and an editor-only facing arrow. Used only when the level holds at least as many slots as characters. |
ACrimsonShowcaseCamera | ACameraActor (Blueprintable) | An authored shot in a stage level. CharacterCount (the exact head count; 0 = any count) and bAutoFit (keep the angle and lens, dolly to fit). The chosen camera hands the capture its field of view and post-process settings. |
Per-load presentation
| Type | Kind | Description |
|---|---|---|
FCrimsonLoadingPresentation | Struct (BlueprintType) | bSuppressShowcase (bool), BackgroundOverride (TSoftObjectPtr<UMaterialInterface>), WidgetOverride (TSoftClassPtr<UUserWidget>), TipCategoryOverride (FGameplayTag). All BP-writable; every field optional - unset keeps project-settings behavior. Applied via SetNextLoadPresentation; a one-shot presentation is cleared when the screen it styled hides. |
Console variables & flags
| Name | Default | Description |
|---|---|---|
CrimsonLoadingScreen.HoldLoadingScreenAdditionalSecs | seeded from the Project Setting (2.0) | Post-load hold in seconds; console/cmdline set overrides the setting |
CrimsonLoadingScreen.LogLoadingScreenReasonEveryFrame | false | Print the show/hide reason every frame - first tool for a stuck screen |
CrimsonLoadingScreen.AlwaysShow | false | Pin the screen up for widget iteration |
CrimsonLoadingScreen.Showcase.DebugCompanions | 0 | Duplicate the registered primary this many times into the roster at show time, so slot placement and framing can be tested with one player. Clamped by MaxShowcaseCharacters. Pair with AlwaysShow 1. |
-NoLoadingScreen (command line) | - | Suppress the loading screen entirely; non-shipping builds only |
CrimsonLoadingScreen.ShaderPrecompile.Disable | 0 | Disable all PSO precompile handling, overriding project settings. |
CrimsonLoadingScreen.ShaderPrecompile.LogProgress | 0 | Log precompile progress whenever the outstanding count changes. |
CrimsonLoadingScreen.ShaderPrecompile.SimulateSecs | 0 | Simulate an N-second precompile so the UI can be authored in PIE. Self-clearing. |
Editor tooling & logging
| Item | Description |
|---|---|
Log category LogCrimsonLoadingScreen | All manager and showcase activity: show/hide reasons, widget load errors, visible-duration summaries, roster registrations, stage-level streaming and its fallbacks, and pocket-world creation and teardown. |
| Cook hook | CrimsonLoadingScreenEditor adds ShowcaseStageLevel's package to the cook through FGameDelegates::GetModifyCookDelegate(), so the setting stays folder-agnostic - a soft path in a settings ini is otherwise invisible to the cooker. It also logs a warning at editor startup when the setting points at a package that is not on disk. |
Shader precompilation types
| Type | Kind | Description |
|---|---|---|
ECrimsonShaderPrecompileState | UENUM | Idle / Warming / Precompiling / Complete. Warming is inside the grace period - show nothing. |
ECrimsonShaderPrecompileGateMode | UENUM | BlockUntilComplete / BackgroundThenBlockOnPlay / NeverBlock. |
ECrimsonPSOPrecacheWaitPriority | UENUM | All / MediumAndAbove / HighAndAbove / HighestOnly. |
FCrimsonShaderPrecompileMonitor | Private class | Module-owned observer of FShaderPipelineCache. Not public API; reach it via the manager. |
Modules
| Module | Type | Notes |
|---|---|---|
CrimsonLoadingScreen | Runtime | Everything above except the editor tooling. Public deps: Core, CoreUObject, Engine, GameplayTags - Engine is public because the showcase actors derive from AActor and ACameraActor in public headers. |
CrimsonLoadingScreenEditor | Editor | The cook hook that adds ShowcaseStageLevel's package to the cook, and the startup warning when that package is missing. Never ships in packaged builds. |