169 lines
6.4 KiB
Markdown
169 lines
6.4 KiB
Markdown
# 76 — BPC_LoadingScreen
|
||
|
||
## Blueprint Spec — UE 5.5–5.7
|
||
|
||
---
|
||
|
||
### Parent Class
|
||
`ActorComponent`
|
||
|
||
### Dependencies
|
||
- [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) — Load state during transitions
|
||
- [`BPC_PerformanceScaler`](../10-adaptive/68_BPC_PerformanceScaler.md) — Quality level for loading assets
|
||
- [`WBP_LoadingScreen`](../06-ui/46_WBP_LoadingScreen.md) — UI widget (Phase 5)
|
||
- [`FL_LevelStreaming`](../01-core/07_FL_LevelStreaming.md) — Level loading utilities (Phase 0)
|
||
- [`DA_LoadingTips`](../12-content/79_DA_LoadingTips.md) — Tip data assets (Phase 12)
|
||
|
||
### Purpose
|
||
Manages loading screen display and behavior during level transitions, save/load operations, and streaming scenarios. Controls visibility, progress feedback, tip rotation, background presentation, and minimum display duration. Supports seamless transitions with fade effects and asynchronous loading state tracking.
|
||
|
||
### Enums
|
||
|
||
**ELoadingScreenType**
|
||
|
||
| Value | Description |
|
||
|-------|-------------|
|
||
| LevelTransition | Full level load |
|
||
| SaveLoad | Save/load operation |
|
||
| Streaming | Sub-level streaming |
|
||
| Boot | Initial game load |
|
||
| Quick | Fast travel |
|
||
|
||
**ELoadingScreenState**
|
||
|
||
| Value | Description |
|
||
|-------|-------------|
|
||
| Inactive | No loading active |
|
||
| FadingIn | Fade to black |
|
||
| Visible | Loading displayed |
|
||
| FadingOut | Fade from black |
|
||
| Complete | Load done, cleanup |
|
||
|
||
### Structs
|
||
|
||
**FLoadingScreenConfig**
|
||
|
||
| Field | Type | Description |
|
||
|-------|------|-------------|
|
||
| Type | ELoadingScreenType | What triggered this |
|
||
| bShowTips | Bool | Rotate loading tips |
|
||
| bShowProgress | Bool | Show progress bar |
|
||
| bUseBackgroundImage | Bool | Static or image |
|
||
| MinDisplayTime | Float | Minimum seconds shown |
|
||
| FadeInDuration | Float | Fade to black time |
|
||
| FadeOutDuration | Float | Fade from black time |
|
||
| BackgroundImages | TArray\<UTexture2D\> | Optional backgrounds |
|
||
| bAllowSkipping | Bool | Skip after load complete |
|
||
|
||
### Variables
|
||
|
||
| Name | Type | Description |
|
||
|------|------|-------------|
|
||
| `CurrentState` | ELoadingScreenState | Current loading state |
|
||
| `CurrentConfig` | FLoadingScreenConfig | Active configuration |
|
||
| `LoadingScreenWidget` | WBP_LoadingScreen | Widget reference |
|
||
| `LoadStartTime` | Float | When load began |
|
||
| `bIsTransitioning` | Bool | Fade in progress |
|
||
| `RemainingTips` | TArray\<FText\> | Unshown tips pool |
|
||
| `BackgroundIndex` | Int32 | Current background |
|
||
| `bLoadingComplete` | Bool | Load finished flag |
|
||
|
||
### Functions
|
||
|
||
| Name | Inputs | Outputs | Description |
|
||
|------|--------|---------|-------------|
|
||
| `ShowLoadingScreen` | Type: ELoadingScreenType, Config: FLoadingScreenConfig | — | Start loading display |
|
||
| `HideLoadingScreen` | — | — | End loading display |
|
||
| `UpdateLoadingProgress` | Progress: Float, StatusText: FText | — | Update progress bar |
|
||
| `SetLoadingMessage` | Message: FText | — | Change message text |
|
||
| `GetNextTip` | — | FText | Get random tip |
|
||
| `GetNextBackground` | — | UTexture2D | Cycle backgrounds |
|
||
| `SetBootConfiguration` | — | — | Configure for initial load |
|
||
| `SetLevelTransitionConfig` | LevelName: FName | — | Configure for level load |
|
||
| `HandleFadeInComplete` | — | — | Fade in finished |
|
||
| `HandleFadeOutComplete` | — | — | Fade out finished |
|
||
| `ForceCompleteLoading` | — | — | Skip remaining time |
|
||
| `ProcessPendingLoading` | — | — | Handle load queue |
|
||
| `LogLoadingComplete` | LoadTime: Float | — | Log load duration |
|
||
|
||
### Blueprint Flow
|
||
|
||
```
|
||
[ShowLoadingScreen]
|
||
└─► If bIsTransitioning: return (queue if needed)
|
||
└─► Set CurrentConfig = Config
|
||
└─► LoadStartTime = Current Time
|
||
└─► FadeIn:
|
||
Create WBP_LoadingScreen
|
||
Add to viewport (topmost Z-order)
|
||
Play fade in animation (FadeInDuration)
|
||
On anim complete:
|
||
CurrentState = Visible
|
||
bIsTransitioning = false
|
||
└─► If Type == Boot:
|
||
Show game logo, company logo (fade sequence)
|
||
└─► Start rotating tips timer (every 8 seconds):
|
||
GetNextTip() -> Update loading message
|
||
└─► If bUseBackgroundImage:
|
||
Set static or rotating backgrounds
|
||
|
||
[UpdateLoadingProgress]
|
||
└─► If Not Visible: return
|
||
└─► Clamp Progress 0–1
|
||
└─► WBP_LoadingScreen.UpdateProgress(Progress, StatusText)
|
||
|
||
[HideLoadingScreen]
|
||
└─► If Complete animation not playing && elapsed < MinDisplayTime:
|
||
Delay until MinDisplayTime reached
|
||
└─► CurrentState = FadingOut
|
||
└─► bIsTransitioning = true
|
||
└─► Play fade out animation (FadeOutDuration)
|
||
└─► On anim complete:
|
||
Remove WBP_LoadingScreen from viewport
|
||
CurrentState = Inactive
|
||
bIsTransitioning = false
|
||
LogLoadingComplete(ElapsedTime)
|
||
Broadcast OnLoadingComplete()
|
||
|
||
[GetNextTip]
|
||
└─► If RemainingTips is empty:
|
||
Refill from DA_LoadingTips
|
||
└─► Remove random tip from RemainingTips
|
||
└─► Return tip text
|
||
|
||
[Level Transition Flow]
|
||
└─► Level requested
|
||
└─► ShowLoadingScreen(LevelTransition)
|
||
└─► Asynchronous level loading:
|
||
Bind to load progress delegate
|
||
UpdateLoadingProgress(Progress, "Loading...")
|
||
└─► Level fully loaded:
|
||
Set bLoadingComplete = true
|
||
HideLoadingScreen()
|
||
```
|
||
|
||
### Event Dispatchers
|
||
|
||
| Name | Payload | Description |
|
||
|------|---------|-------------|
|
||
| `OnLoadingStarted` | Type: ELoadingScreenType | Load began |
|
||
| `OnLoadingComplete` | — | Load finished, fade out |
|
||
|
||
### Communications With
|
||
|
||
| Target | Method | Why |
|
||
|--------|--------|-----|
|
||
| [`WBP_LoadingScreen`](../06-ui/46_WBP_LoadingScreen.md) | Widget reference | Display control |
|
||
| [`FL_LevelStreaming`](../01-core/07_FL_LevelStreaming.md) | Direct call | Level load progress |
|
||
| [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) | Direct call | Save/load operations |
|
||
| [`BPC_PerformanceScaler`](../10-adaptive/68_BPC_PerformanceScaler.md) | Direct call | Quality during load |
|
||
| [`DA_LoadingTips`](../12-content/79_DA_LoadingTips.md) | Data asset | Tip content |
|
||
|
||
### Reuse Notes
|
||
- Config-driven for different loading contexts (boot, level, save)
|
||
- Tip rotation prevents repetition during long loads
|
||
- MinDisplayTime prevents flash-loading on fast systems
|
||
- Background cycling adds visual variety
|
||
- Fade in/out duration configurable per context
|
||
- Asynchronous progress bound to actual load completion
|
||
- Compatible with both synchronous and async level loading |