Stage Zero v3 Subsystem Documentation

Quick Start (Fast Setup)

TL;DR: Enable Stage Zero, set maps in Project Settings, call Start Warmup (or Trigger Stage Zero Warm Up from the Blueprint library), and let the subsystem handle the built-in widget and map transition.

1) Enable & configure

Edit → Plugins → Stage Zero (enabled by default in samples).
Edit → Project Settings → Stage Zero:
- Set Maps To Warm or enable Warm Up All Maps.
- Assign Built In Loading Widget Class (defaults to WB_Loading).
- Optional: Spinner icon, background slides, tips, boot timings.

2) Boot/Intro level flow

In your BootLevel GameMode → Event BeginPlay:
Create a loading widget with Register Stage Zero Loading Widget (or let auto-spawn handle it).
Get Game Instance → Get Stage Zero Subsystem.
Optional: Set Primary Level to your Main Menu or First Map.
Call Start Warmup (or Trigger Stage Zero Warm Up helper).
Bind to On Warmup Progress / On Warmup Finished to update the widget.
On completion, the subsystem auto-opens Primary Level if configured, or you can manually call Transition To Primary Level.

3) Minimal singleplayer example

BootLevel Level Blueprint:
Create Widget → Register Stage Zero Loading Widget (Add to Viewport, bHideAfterComplete=false).
Get Stage Zero Subsystem → Set Primary Level (MainMenu) → Start Warmup.
Bind On Warmup Progress to update a progress text; on On Warmup Finished call Transition To Primary Level (Use Configured Delay=true).

Concepts & Architecture

Stage Zero Subsystem

Runs as a UGameInstanceSubsystem. Builds the warmup plan, executes manifest-driven jobs, polls shader/texture streaming progress, manages the boot widget, and broadcasts progress delegates.

Respects runtime overrides (maps, primary level, auto-widget, auto-transition).
Project Settings control warmup max items, render-materials option, load-maps option, and pipeline cache warmup.
Safe mode CVars avoid heavy Nanite/Lumen/ray tracing during warmup.

Manifest

Data asset built in editor from the Asset Registry (no world loads). Stores materials, textures, Niagara systems per map and per World Partition group.

Paths live at /Game/StageZero/StageZeroWarmupManifest.
Rebuild via the Stage Zero toolbar tab or console: StageZero.BuildMatTexManifest.

Warm Up All Maps vs selections

Start Warmup uses configured map list (or bWarmUpAllMaps) and can auto-transition to a primary level. Warm Up All Maps warms everything from the manifest without opening a level. Warm Up Map targets a single map.

World Partition support

Manifest records WP cells plus anchor- and spline-based groups.

Anchors: place AStageZeroWPAnchor actors; manifest groups assets in their radius (grouped by GroupName or actor name).
Splines: place AStageZeroWPSplineWarmup; manifest samples points along the spline radius.
Runtime nodes warm specific cells/anchors/routes without streaming worlds.

Progress system

Tracks manifest jobs + shader compilation + texture streaming.

Delegates fire on every batch; progress clamps totals so UI stays honest.
Get Warmup Status returns totals, per-map counts, and labels for widgets.

Blueprint API Reference (Core)

All nodes live under Stage Zero categories. Most nodes expose an optional bShowDebug pin (advanced) to log on-screen.

Start Warmup — builds plan, spawns widget if enabled, warms configured maps, auto-opens Primary Level if set.
Cancel Warmup — stops work, tears down widget, broadcasts finished with bWasCancelled=true.
Warm Up All Maps — warms every manifest entry (no level transition).
Warm Up Map / Warm Up Map By Path — warms a single map’s manifest entry.
Get Warmup Progress / Get Warmup Status — returns 0..1 or a struct with totals and current map label.
Is Warmup Running / Completed — state queries.
Get Task Counts, Get Total Maps, Get Completed Maps, Get Current Map Name.
Set Primary Level — sets destination map; also enables auto-transition unless you disable it.
Set Warmup Maps / Add Warmup Map / Clear Warmup Maps — runtime overrides for map list.
Set Warm Up All Maps — runtime toggle for discover-all mode.
Set Warm Up Level Instances / Packed Level Actors — include or skip nested/packed content.
Set Auto Transition To Primary — enable/disable automatic OpenLevel after warmup.
Transition To Primary Level — manual travel after warmup completes; optional delay.
Set Minimum Display Seconds / Set Delay After Complete — UI timing controls.
Set Warmup Cache Enabled / Is Warmup Cache Enabled — skip assets already warmed this session.
Events: OnWarmupStarted, OnWarmupProgress (Progress, CurrentMap, Completed, Total, MapCompleted, MapTotal), OnWarmupFinished (bCancelled), OnWarmupMapStarted, OnWarmupMapFinished.

Warm Up World Partition Cells (MapPath) — warms all manifest-tracked cell assets for the map.
Warm Up World Partition Anchors (MapPath, AnchorNames) — warms anchor groups; when names empty, warms all anchors.
Warm Up World Partition Spline Routes (MapPath, RouteNames) — warms spline groups; empty list warms all.
AStageZeroWPAnchor actor (editor-only properties): Radius, GroupName, Priority, and a preview sphere.
AStageZeroWPSplineWarmup actor: editable spline with SampleDistance, SampleRadius, optional GroupName.
These nodes use manifest data—no runtime streaming/teleporting required.

Is Widget Auto Spawn Enabled — check auto-spawn flag.
Set Auto Spawn Widget — turn built-in widget spawning on/off.
Set Allow Create Player If Missing — allow creating a local player in standalone to own the widget.
Get Boot View Config / Set Boot View Config — read/override widget slides, tips, spinner, intervals, and spinner-only duration.
Register Loading Widget / Unregister Loading Widget — attach your widget (any UserWidget or subclass of UStageZeroLoadingWidget) so the subsystem drives it; optional bHideAfterComplete.
Set Background Slides Override — swap slideshow textures at runtime; respects bLoopSlides.
Register Stage Zero Loading Widget (Blueprint Library) — CreateWidget helper with AddToViewport + registration + optional hide.
StageZeroLoadingWidget events: OnShaderProgress, OnCompletionMessage, OnTransitionMessage, OnBuildInfo, OnSpinnerVisibilityChanged, OnProgressVisibilityChanged, OnBackgroundChanged, OnTipChanged. Public widget members for spinner image, background, tip text, progress bar/text, and hide-after-warmup flag.
StageZeroLoadingWidget functions: InitializeBootScreen, SetSpinnerVisibility, SetProgressVisibility, SetTip.

Set/Get Warm Up All Maps, Set/Get Warm Up Level Instances, Set/Get Warm Up Packed Level Actors — write/read project settings.
Set/Get Loading Icon Texture, Set/Get Background Slides, Set/Get Boot Tips, Set Background Slide Interval, Set Boot Tip Interval, Set Spinner Only Phase Duration, Set Show Spinner During Progress, Set Loop Background Slides.
Clear/Add/Set/Get Maps To Warm Up — modify the project map list.
These save to config immediately; use runtime overrides on the subsystem for per-session changes.

Trigger Stage Zero Warm Up — Blueprint helper that finds the subsystem, copies any legacy loader actor settings, forces widget spawn, and calls StartWarmup.
Get Stage Zero Subsystem — fetch for a world context.
Get Stage Zero Warmup Status — one-call status struct (progress, map label, counts).
Get Stage Zero Warmup Maps, Get Stage Zero Primary Level, Get Stage Zero Map Counts.
Normalize Warmup Progress — convert counts to 0..100.
Set Stage Zero Boot Config, Set Stage Zero Auto Transition, Set Stage Zero Auto Widget, Set Stage Zero Allow Create Player, Set Stage Zero Minimum Display Seconds, Set Stage Zero Delay After Complete.
Transition Stage Zero Primary Level — manual travel helper after warmup.
Get Stage Zero Warmup Jobs (Subsystem) — returns FStageZeroWarmupJobInfo array (AssetName, AssetPath, AssetType, bInManifest, bWarmupRequested, bWarmupFinished). Requires config flag bEnableWarmupDebugFeed.
Is Stage Zero Warmup Debug Enabled — check debug feed flag.

Scenario-based guides

Startup / Boot Map

Goal: Pre-warm assets before showing Main Menu.

Boot level GameMode → BeginPlay:
Create Widget → Register Stage Zero Loading Widget (ZOrder=0).
Get Stage Zero Subsystem → Set Primary Level to MainMenu.
Optional: Set Warm Up All Maps if you want everything warmed.
Start Warmup.
On On Warmup Progress update UI; on On Warmup Finished call Transition To Primary Level (UseConfiguredDelay=true).

Lobby / Multiplayer

Goal: Warm content while in a lobby and only travel when players are ready.

Lobby level blueprint:
Get Stage Zero Subsystem → Set Auto Transition To Primary (false).
Call Start Warmup (or Trigger Stage Zero Warm Up).
Bind progress to lobby UI. Keep widget visible even after completion if desired.
When host presses Start: Transition To Primary Level (bUseConfiguredDelay=true) to open the game map.
Clients: run the same flow in lobby; warmup work is local (no replication), so each machine prepares assets independently.

World Partition maps

Goal: Warm only the areas players hit first.

In the editor, place StageZeroWPAnchor near spawn/points of interest; set Radius and optional GroupName.
Or place StageZeroWPSplineWarmup along expected travel paths; set SampleDistance/SampleRadius and optional GroupName.
Generate the manifest. Anchors/splines capture intersecting cell assets.
Runtime: call Warm Up World Partition Anchors or Warm Up World Partition Spline Routes with specific names (or empty array to warm all groups).
No streaming is triggered; Stage Zero loads assets directly from manifest paths.

Custom loading screen

Goal: Use your own widget instead of WB_Loading.

Create a UMG widget subclassing StageZeroLoadingWidget (recommended) or UserWidget.
Bind optional members (Spinner, BackgroundImage, TipText, ProgressBar/Text). Implement OnShaderProgress and OnBackgroundChanged for visuals.
In BeginPlay, call Register Stage Zero Loading Widget with your class, bAddToViewport=true, bHideAfterComplete as desired.
Or set Built In Loading Widget Class in Project Settings to your class and leave auto-spawn enabled.
Use Set Background Slides Override or Set Stage Zero Boot Config to swap art and tips at runtime.

Debugging & Advanced Tips

Warmup debug feed: Enable bEnableWarmupDebugFeed (Project Settings → Stage Zero). Call Get Stage Zero Warmup Jobs each tick to build a debug UI showing bInManifest / bWarmupRequested / bWarmupFinished per asset.
Manifest rebuild: Use the Level Editor toolbar button Stage Zero → Generate Manifest or console StageZero.BuildMatTexManifest. Safe Mode buttons toggle StageZero.SafeMode (avoids heavy rendering during warmup).
Warmup cache skip: Toggle Set Warmup Cache Enabled to avoid reprocessing assets warmed earlier in the session.
Stuck at 0%: Ensure the manifest exists; rebuild it. Check that maps are assigned and the widget is registered before calling StartWarmup.
World Partition: Make sure runtime grid data is built before generating the manifest; otherwise WP cells may be empty.
Safe mode: Enabled by default via StageZero.SafeMode=1 to avoid forcing Nanite/Lumen/ray tracing during warmup. Set to 0 only if you need aggressive PSO priming and your content is stable.

FAQ

Does Stage Zero load maps?

For manifest-driven runs, Stage Zero loads assets directly and does not stream maps. When bLoadMapsDuringWarmup is enabled (or CVar StageZero.Warmup.LoadMaps=1), it may stream a map briefly for deeper asset discovery.

How do I integrate with an existing loading screen?

Register your widget via Register Stage Zero Loading Widget. Bind to On Warmup Progress and On Warmup Finished. Disable auto widget spawn if you always create your own.

Why do I still see hitches in packaged builds?

Rebuild the manifest, enable warmup cache skip, and ensure bRenderMaterialsDuringWarmup is on only if your project can render safely. For PSOs, keep pipeline cache warming enabled if you rely on it.

How do I use this with World Partition?

Place anchors/splines, rebuild the manifest, then call the WP warmup nodes with your map path and optional group names. No streaming occurs during those calls.

Subsystem-driven warmup for zero-stutter launches.