PSO Autopilot Manual

🖥️ Supported Platforms

The plugin descriptor declares its runtime module for Win64, Mac, Linux, Android, and IOS, with the editor module limited to desktop (Win64 / Mac / Linux). The new per-platform performance overrides let you tune the warmup independently for each target. Win64 is the primary desktop target used for the bundled demo and the included validation tooling, and the plugin ships as source so each engine compiles it with its own per-platform toolchain.

🧯 CrashGUID Is Not a Crash by Itself

Unreal can print a Session CrashGUID near startup even on clean exits. A real crash log usually has Fatal error, Unhandled Exception, LowLevelFatalError, an assert/ensure that terminates, CrashReportClient activity, or a call stack near the end. Clean exits usually end with RequestExit(0), LogExit: Exiting, and Log file closed.

🗂️ About the /Game/ path prefix

Throughout the wizard you will see paths like /Game/PSOAutopilot/PSOAutopilot_Loading. /Game/ is Unreal's name for your project's Content/ folder; it is not a literal folder named "Game". In the Content Browser sidebar, click the Content node (under All) to navigate there. The PSOAutopilot subfolder is created the moment you click one of the wizard's Create fix buttons; on a fresh install the path is just a default the wizard intends to create.

🧪 Editor Play Uses Unreal's Default Path by Default

With Editor Iteration Mode set to Use Unreal Editor Compilation, pressing Play in the editor immediately completes the PSO Autopilot flow and lets Unreal compile shaders normally for that PIE session. Packaged builds, Standalone Game, and -game validation still use the production warmup path.

🧭 Recommended Production Flow

The best current integration is a dedicated loading level that prepares and loads Level To Open After Warmup before travel. This is the same flow used by the bundled /Game/Demo/Demo_BootFlow sample.

For the standard Simple Setup flow, the wizard now writes both GameDefaultMap and EditorStartupMap to the selected loading level. If Allow Custom Startup Level is off, a different startup map is a blocking validator error.

🎯 What Content to Prepare Should Contain

Content to Prepare should point at runtime content that represents what players can see or load near startup: maps, menu/UI widgets, actor Blueprints, static meshes, skeletal meshes, VFX, environment folders, UI materials, and the material folders used by those assets.

Material folders alone are usually not enough because a PSO is the combination of material, mesh type, vertex factory, render state, render pass, platform, and RHI. If the validator says your setup is material-heavy, add the maps, meshes, Blueprints, widgets, and VFX that use those materials.

🧬 Where the Overlay Happens

The override is applied while the runtime warmup snapshot is captured (the same place Simple-mode tuning is resolved), so it composes cleanly with presets and Simple Setup. It only touches the six performance fields above — content targeting, dependency expansion, and texture pre-heating are unchanged. A disabled or non-matching override is a no-op, so it is safe to leave platform entries configured for builds you are not currently making.

📦 Note on Distribution

The commandlet and CI script are development and validation tooling. They run against the editor/commandlet target; nothing here is required at runtime or shipped into a packaged game.

Editor Preview Bypass

When Editor Iteration Mode is set to Use Unreal Editor Compilation and the world is PIE, Editor, Editor Preview, or Game Preview, StartWarmup() completes immediately before calling FShaderPipelineCache::ResumeBatching(). This keeps normal editor Play sessions on Unreal's built-in shader compilation behavior while preserving the full PSO Autopilot path for packaged/runtime validation.

Batch Loop Details

Scanning — waits for the Asset Registry to be ready, then builds the warmup list from scan directories, explicit roots, runtime-queued roots, classes, and optional dependency expansion.

Fingerprinting — hashes the final discovered asset set plus key settings so cache-skip decisions reflect the real startup workload.

Preloading Packages — asynchronously loads any queued gameplay packages before the loading screen is allowed to finish.

Loading Batch — Uses FStreamableManager::RequestAsyncLoad to stream assets without blocking the game thread. A 60-second watchdog timer protects against stuck loads.

Processing Batch — Time-sliced PSO precaching via PrecachePSOs(). Covers Local, Nanite, ParticleSprite, BeamTrail, and MeshParticle vertex factories.

Streaming Textures — Calls SetForceMipLevelsToBeResident() on standard textures and UpdateResource() on Virtual Textures. A 30-second timeout prevents indefinite waits.

Unloading Batch — Releases all FStreamableHandle references and clears temporary component arrays.

Waiting For GC — If enabled, requests a full-purge Garbage Collection to reclaim memory before the next batch.

Delay Minimum Duration — optional demo hold state that keeps the loading UI visible for a minimum total runtime.

Compiling Pipeline Cache — optional final wait that holds the loading screen while the engine's FShaderPipelineCache drains its remaining PSO backlog. Only entered when the backlog exceeds Min PSO Queue To Wait, and bounded by Max Wait Seconds. The progress bar advances across the 0.95 → 1.00 band from the real compiled-vs-discovered PSO ratio.

🛎️ Confirm-Button Flow Pattern 1.2.1

To show a "Press Start" or "Click to Continue" prompt after warmup completes instead of auto-opening Level To Open After Warmup:

1. On the Boot Loader actor, uncheck Auto Open Level. (Leave Remove Loading Widget When Ready at its default; it is ignored while Auto Open Level is off.)
2. In the loading widget, hide the confirm button by default and reveal it on the loader's On Startup Preparation Finished event.
3. On the button's click handler, call Open Level (by Name) with your target map. Optionally call the loader's Dismiss Loading Widget function before the transition if you want the widget gone before the new level streams in.

Before 1.2.1 the widget was always removed at warmup-complete regardless of Auto Open Level, which broke this pattern in packaged builds (and silently broke it on the second run when smart-cache-skip completed warmup in the same frame the widget was created). 1.2.1 keeps the widget alive whenever Auto Open Level is off so Blueprint owns the rest of the flow cleanly.

🛣️ Boot-Flow Handoff

The bundled demo carries a travel option from the boot map to the gameplay map so the destination demo manager can intentionally skip a duplicate warmup pass. If you build your own boot-to-gameplay flow, follow the same rule: do not call StartWarmup() again on the destination map if the boot flow already completed the work.

One-Node Destination Guard

The one-node flow now checks that Level To Open After Warmup exists before cleanup and travel. If the destination is missing from the cooked build, the loading widget remains visible, receives a terminal error, and the log points to Packaging maps/cook settings.

On Progress Updated

Fires continuously during startup preparation.

Overall Progress (Float): A normalized 0.0 to 1.0 value representing the total completion percentage. Bind this directly to a UMG ProgressBar.

Progress bands. The single 0.0–1.0 value is mapped into three sequential sub-bands so the bar stays meaningful end-to-end:

• 0.00 → 0.85 — asset warmup (load + PSO precache batches).
• 0.85 → 0.95 — Level To Open package preload (formerly a hardcoded 100%).
• 0.95 → 1.00 — engine pipeline cache draining (the FlushingPipelineCache state). Only runs when there is real backlog. After -clearPSODriverCache, a driver update, or a fresh GPU install, this slice keeps the loading screen visible while Unreal compiles the remaining PSOs — instead of handing off to OpenLevel while pipelines are still compiling.

Current Status Message (String): Friendly live status text for the loading screen. Messages include: Finding startup assets..., Checking previous warmup..., Loading assets in safe batches..., Preparing shaders..., Preparing textures..., Preloading gameplay map... / destination package preload, and Ready.

Technical Status Message (String): Optional telemetry text available through Get Technical Status Message. Use it in a collapsible debug or telemetry panel when you want details like cache fingerprinting, batch counts, PSO task counts, package names, texture streaming counts, or the engine pipeline cache flush progress (e.g., Compiling engine pipeline cache: N of M PSOs remaining, X.Xs elapsed.).

ETA helpers. Two BlueprintPure getters let you surface a remaining-seconds estimate alongside the progress bar:

• Get Estimated Remaining Seconds — returns a float. Negative values mean "no estimate yet" (very early in the run, idle, or right after a Smart Skip) so the ETA label can hide cleanly.
• Has Estimated Remaining Seconds — convenience boolean for the visibility binding.

The estimator is phase-aware: during the engine pipeline cache flush it uses the real PSOs-per-second drain rate from FShaderPipelineCache; during the asset and preload phases it falls back to linear extrapolation from the current progress fraction. Values are cached internally for 0.25 s so a tick-bound widget binding does not jitter.

On Startup Preparation Complete

Fires exactly once when the entire process is finished or skipped because the content was already prepared. Bind this event to close your loading screen and transition to gameplay.

🧩 Optional Named Bindings for Template Widgets

If a widget exists with one of these exact variable names, PSO Autopilot updates it automatically. If it does not exist, nothing breaks; that part of the UI is simply skipped.

Important: keep Is Variable enabled and preserve the exact variable name for any widget you want updated automatically.

🧠 Interface Contract for Fully Custom Widgets

If your widget implements PSOAutopilotLoadingScreenReceiver, the built-in flows call these functions automatically:

• Apply Loading Progress — overall progress and friendly status text.
• Apply Loading Progress Summary — phase-aware summary label under the bar.
• Apply Loading Technical Status — optional telemetry / debug detail.
• Apply Loading Telemetry Visibility — whether the technical panel should be visible.

This is the cleanest path when you already have your own loading-screen widget architecture and do not want to use the named-binding template base.

🧰 Ready-Made Templates

Use Tools > PSO Autopilot > Create/Open Loading Widget Templates or run Scripts/CreateEditableLoadingWidget.py to generate the default, minimal, and telemetry Widget Blueprint templates under /Game/PSOAutopilot. Each template includes a populated Designer tree and an editable Event Graph seeded with the expected parent calls.

Blueprint-Driven Loading Screen

You can also use the subsystem directly from any Blueprint. Get the subsystem reference, bind to OnProgressUpdated and OnWarmupComplete, then call StartWarmup(). This gives you complete control over when and how startup preparation runs.

// Blueprint pseudo-code
GameInstance -> GetSubsystem(PSOAutopilotSubsystem) -> subsystem
subsystem -> BindEvent(OnProgressUpdated) -> UpdateMyProgressBar
subsystem -> BindEvent(OnWarmupComplete) -> OpenLevel("MainMenu")
subsystem -> StartWarmup()

If you prefer the one-node flow or Boot Loader, keep this same widget but implement PSOAutopilotLoadingScreenReceiver so those built-in flows can push progress updates into it automatically.

Cache Storage Location

Fingerprints are stored in Saved/PSOAutopilotCache.ini under the [PSOAutopilot] section as a comma-separated list in the CompletedFingerprints key. Current builds also read legacy cache entries from GameUserSettings.ini once, migrate them into the dedicated cache file, and then continue using PSOAutopilotCache.ini.

Interpreting Packaged Progress

Do not judge packaged behavior from a single captured frame. The progress bar is intentionally phase-banded:

• 0.00 → 0.85 — asset warmup and PSO precache batches.
• 0.85 → 0.95 — Level To Open package preload.
• 0.95 → 1.00 — final engine pipeline-cache flush, only when the remaining backlog is large enough to justify waiting.

If a packaged run shows only 0 or 1 processed items, jumps to 85%, then opens Level To Open almost immediately, that usually means the asset phase found little startup work or was skipped by the cache fingerprint, the level-package preload phase still ran, and the final engine PSO backlog was too small to hold the screen.

Use Get Current Progress Summary Text instead of raw percentages alone. It switches between asset counts, package-preload counts, pipeline-cache PSO counts, and cached-run states so the UI reflects the real phase.

Fallback Widget

If no HUDClass is set on the Demo Manager, it automatically falls back to UPSOAutopilotDemoWidget's C++ fallback UI, which procedurally generates a compact telemetry panel with progress, timing, cold/cached controls, cache status, and a smooth spinner.

🛠️ Regenerating the Sample

Run Unreal with Scripts/CreatePSOAutopilotDemo.py via -ExecutePythonScript if you want to rebuild or normalize the sample levels, demo materials, boot widget, and boot actor defaults.

Q: The progress bar stays at 0% for a long time on boot.

A: Unreal Engine's Asset Registry initializes asynchronously in the background when the game boots. PSO Autopilot waits for this background scan to finish before querying assets to ensure none are missed. If your project is very large, this initial wait is normal. You can monitor progress in the log under LogPSOAutopilot: once the Asset Registry is ready, scanning begins immediately.

Q: The scan finds 0 assets even though my directories are set correctly.

A: Check for these common causes:

1. Empty path entry: If DefaultGame.ini contains +DirectoriesToScan=(Path=""), this empty entry causes the Asset Registry filter to fail silently. Remove it.

2. Wrong path format: Paths must use the /Game/ prefix, not filesystem paths. Use /Game/Characters, not Content/Characters.

3. Asset Registry not ready: In -game mode, the background asset scan may not have started yet. Current builds handle this by kicking off an async full search and waiting until the registry is ready.

4. Your real roots are not directory-based: If the startup content is rooted in a map, blueprint, label, or dynamic runtime selection, add it through ExplicitAssetsToWarm or RegisterRuntimeWarmupAsset(...) rather than relying only on DirectoriesToScan.

5. PIE and packaged builds do not see identical content sets: PIE can enumerate uncooked editor content, while packaged builds only see cooked staged runtime content. A setup that looks rich in editor can still discover very little in a packaged build if the runtime roots are narrow or the real startup content is elsewhere.

6. Cook roots are not the same as processed counts: Seeing many folders under Additional Asset Directories to Cook proves those folders were staged for cooking, but the loading-screen counter still advances per discovered warmable asset, not per folder path.

Q: Scanning is very slow in the Editor.

A: In Editor builds, PSO Autopilot queries filesystem modification timestamps for every discovered asset to build the fingerprint. This is necessary to detect material changes but adds I/O overhead. In packaged builds this step is skipped, and scanning is significantly faster. To speed up Editor iteration, narrow your DirectoriesToScan to only the folders you're actively working on.

Q: Pressing Play in the editor no longer runs the warmup. Is the plugin disabled?

A: Not globally. Current builds default Editor Iteration Mode to Use Unreal Editor Compilation, so PIE/editor preview uses Unreal's standard shader compilation path and PSO Autopilot completes immediately. Packaged builds and runtime validation still use the warmup. Switch the mode to Run PSO Autopilot Warmup when you want to test the full flow in PIE.

Q: I see "Compiling PSOs..." in the log, but no shaders are actually building.

A: Ensure your project is configured to generate shader caches. In DefaultEngine.ini, verify that bShareMaterialShaderCode=True is set under [/Script/Engine.RendererSettings]. Also test in a Packaged Build or -game mode—the Editor handles PSOs differently than a deployed executable.

Q: Which vertex factories does PSO Autopilot cover?

A: The plugin submits PSO precache requests for these vertex factory types:

• Local Vertex Factory — Standard static meshes
• Nanite Vertex Factory — Nanite-enabled meshes (UE 5.x)
• Particle Sprite — GPU sprite particles
• Beam/Trail — Beam and trail particle emitters
• Mesh Particle — Mesh-based particle emitters

Skeletal mesh vertex factories are covered when the corresponding materials are scanned. Landscape and other specialized factories rely on the Engine's own PSO collection at draw time.

Q: My loading screen stutters or drops below 60fps during warmup.

A: The MaxProcessingTimeMsPerFrame setting controls how much game-thread time the plugin uses per frame. The default of 5.0ms should leave ~11.6ms for rendering at 60fps. If you're still seeing hitches:

1. Lower MaxProcessingTimeMsPerFrame to 2.0–3.0ms.

2. Reduce BatchSize—smaller batches mean less per-frame work.

3. Check if other systems (level streaming, audio loading) are competing for the game thread.

Q: RAM usage spikes during warmup. How do I reduce peak memory?

A: Three levers control memory usage:

1. Reduce BatchSize — Fewer assets loaded simultaneously means lower peak RAM. Try 25–50 for constrained platforms.

2. Enable GC Between Batches — Ensure bGarbageCollectBetweenBatches is true. The plugin performs a full-purge GC after each batch to aggressively reclaim memory.

3. Target fewer directories — Only scan folders with materials the player will actually see. Reducing total asset count is the most effective way to lower peak memory.

4. Be selective with package preload — PackagesToPreload and bPreloadLevelPackagesBeforeOpen intentionally move more work into startup, which can also increase temporary memory pressure. Preload only the packages that materially improve first-run smoothness.

Q: The warmup takes too long. How can I speed it up?

A: Warmup speed is a tradeoff with memory and UI smoothness:

1. Increase BatchSize to 150–200 (if RAM allows).

2. Increase MaxProcessingTimeMsPerFrame to 8–10ms (loading animations may be slightly choppier).

3. Disable texture pre-heating if visual pop-in is acceptable: set bPreHeatTextureStreaming and bPreHeatVirtualTextures to false.

4. Narrow your scan targets to only critical directories.

Q: I saw a D3D12RHI uniform buffer crash during a huge warmup. What changed?

A: Current builds throttle active PSO precache requests during time-sliced batch processing. This prevents very large material sets from flooding the renderer with unchecked background PSO work. If you still hit renderer instability, reduce BatchSize, narrow scan folders, and test with a Development packaged build log.

Q: Does a Session CrashGUID mean PSO Autopilot crashed?

A: No. Unreal often prints a Session CrashGUID during startup so crash reporting has an ID ready if the process fails later. That line alone is not crash evidence.

A real crash usually has a fatal marker near the end of the log: Fatal error, Unhandled Exception, LowLevelFatalError, an assert/ensure that terminates, CrashReportClient activity, or a call stack. A clean exit normally ends with RequestExit(0), LogExit: Exiting, and Log file closed.

Q: The log shows "Texture streaming timed out." Is this a problem?

A: The plugin imposes a 30-second timeout on the texture streaming phase per batch. If some textures haven't finished streaming by then, the plugin advances to the next batch rather than waiting indefinitely. This is a safety mechanism. If you see this frequently:

1. Your batch size may be too large for your I/O bandwidth. Reduce BatchSize.

2. Virtual Textures with very large page tables may need more time. The timeout is generous enough for most projects.

3. The textures will still stream in during gameplay—this timeout just means they weren't fully resident before the loading screen dropped.

Q: Textures still pop in blurry after the loading screen finishes.

A: Ensure both bPreHeatTextureStreaming and bPreHeatVirtualTextures are enabled in Project Settings. If the issue persists:

1. The materials causing pop-in may be outside your scanned directories. Add their parent folders to DirectoriesToScan.

2. Texture streaming may have timed out (see above). Check the log for timeout warnings.

3. If using World Partition or level streaming, textures in streamed sub-levels are not covered by PSO Autopilot's pre-heat—they are managed by Unreal's runtime streaming system.

Q: The warmup runs every time I launch, even though nothing changed.

A: The fingerprint may be changing between launches. Common causes:

1. Editor timestamp drift: In Editor/PIE, filesystem timestamps are included in the fingerprint. If your source control or build system touches file modification dates, the hash changes. This does not happen in packaged builds.

2. The dedicated cache file is not being written: Current builds persist fingerprints to Saved/PSOAutopilotCache.ini. If that file cannot be created or updated, the cache is lost. Check that the file and its parent Saved/ directory are writable.

3. bResetFingerprintOnBeginPlay is enabled: The Boot Loader or Demo Manager may be forcing a reset. Check the actor's properties. Re-running the setup wizard clears stale simple-setup demo/debug overrides on existing loader actors.

4. The previous run had warnings: Fingerprints are only stored for clean runs. Asset-load or package-preload failures intentionally force a fresh attempt next time.

Q: I changed some materials but the warmup was skipped. Stale cache?

A: In Editor builds, PSO Autopilot includes filesystem timestamps in the fingerprint, so saving a material should invalidate the cache. If it doesn't:

1. Verify the changed material is inside one of your DirectoriesToScan directories.

2. The material may be a Material Instance whose parent hasn't changed. Re-save the parent material to force a new timestamp.

3. If the changed content is only reachable through a map, blueprint, label, or soft reference, make sure that root is still represented in the discovered warmup set. The fingerprint now keys off the final discovered asset list, not just the raw directory list.

4. As a workaround, enable bResetFingerprintOnBeginPlay on your Boot Loader during development to always force the warmup.

Q: How do I manually clear the fingerprint cache?

A: Two methods:

1. At runtime: Call ResetCachedWarmupFingerprint() on the PSOAutopilotSubsystem before starting the warmup.

2. Manually: Open Saved/PSOAutopilotCache.ini and delete the [PSOAutopilot] section, or remove the file entirely.

Q: I have multiple Boot Loaders with different scan directories. Will they conflict?

A: No. PSO Autopilot stores up to 8 unique fingerprints using LRU eviction. Each Boot Loader generates its own fingerprint based on its scan configuration, and they are independently cached. The 9th unique fingerprint will evict the oldest entry.

Q: The Boot Loader warns "LevelToOpenOnComplete was not found."

A: The level name you entered does not match any package available to the current runtime. The Boot Loader validates the level before attempting the transition to prevent crashes and silent failed travel. Check that:

1. The level name matches exactly (case-sensitive on some platforms).

2. The level is included in your packaged build's list of maps (Project Settings > Packaging > List of maps to include).

3. You're using the long package name (for example /Game/MainMenu/MainMenu), not a filesystem path.

Current builds check FPackageName::DoesPackageExist(...) before removing the loading widget or calling OpenLevel. If the destination is missing, the widget stays visible and the log points to Maps to Cook or Additional Asset Directories to Cook.

Q: Why does the gameplay map not start a second warmup after the boot map finishes?

A: That is the intended sample behavior. The boot-flow path hands off a travel option to the gameplay map, and the bundled demo manager checks that flag and skips duplicate warmup work. This prevents the startup cost from being paid twice.

Q: The loading widget doesn't appear.

A: Check the following:

1. Ensure a valid Player Controller exists. The Boot Loader requires a local player controller to create widgets.

2. If using a custom LoadingScreenClass, verify it's a valid Widget Blueprint that compiles without errors. The setup wizard's editable default should live at /Game/PSOAutopilot/WBP_PSOAutopilotLoadingScreen, with optional _Minimal and _Telemetry siblings.

3. Check the output log for LogPSOAutopilot messages—the Boot Loader logs whether widget creation succeeded or failed.

Q: The folder only contains the loading map, but Play shows a C++ loading widget. Why?

A: Older setup data could point directly at the native UPSOAutopilotLoadingScreenWidget fallback instead of a project-owned UMG asset. Run the setup wizard and use the loading-widget fix or Create/Update Startup Flow. Current builds create and assign editable Widget Blueprint templates at /Game/PSOAutopilot/WBP_PSOAutopilotLoadingScreen plus _Minimal and _Telemetry.

Q: I want a completely custom branded loading widget. How do I still get auto-updates?

A: Use any UserWidget that implements PSOAutopilotLoadingScreenReceiver. The Boot Loader and Start PSO Autopilot Loading Flow now call that interface automatically. If you prefer, you can skip the interface and bind to OnProgressUpdated / OnWarmupComplete manually.

Q: My Project Settings get permanently changed after using the Boot Loader.

A: This should not happen. The Boot Loader captures a snapshot of your settings before applying overrides and restores them when warmup completes or when the actor is destroyed. If settings appear stuck:

1. Check if the game crashed before RestoreSettingsOverrides() ran. In that case, the CDO may have been modified but the INI file was not overwritten.

2. Restart the Editor to reload settings from DefaultGame.ini.

3. Verify that bApplySettingsOverride is actually enabled—if it's false, no snapshot is taken and nothing is restored.

Q: The log shows "Batch load timed out." What happened?

A: A 60-second watchdog timer protects against stuck async loads. If an FStreamableManager::RequestAsyncLoad call doesn't complete within 60 seconds, the plugin cancels the load, marks the batch as failed, and advances to the next batch. Causes include:

1. Corrupted or excessively large assets that take too long to load.

2. Disk I/O contention (e.g., antivirus scanning, another application thrashing the disk).

3. The assets have external dependencies that trigger cascading loads. This is rare but can happen with deeply nested Blueprint references.

The warmup will continue with remaining batches. Failed batches are counted and reported in the completion log.

Q: The warmup completes but reports some failed batches. Should I worry?

A: A small number of failed batches (1–2 out of many) is usually harmless—those specific materials may have compilation issues unrelated to PSO Autopilot. The shaders for those materials will be compiled on-demand at draw time (with a potential micro-stutter). If many batches fail, investigate the assets in those batches for corruption or unsupported material features.

Q: Unreal keeps cooking almost everything after I restart the editor. What should I check?

A: Check Project Settings > Packaging > Additional Asset Directories to Cook and your config for +DirectoriesToAlwaysCook=(Path="/Game"). That root entry tells Unreal to always cook the whole project. Current setup-wizard fixes avoid adding it and can remove it; use specific folders such as /Game/Demo, /Game/DemoMaterials, or your real startup content folders instead.

Q: Can I call StartWarmup() from C++ instead of using the Boot Loader?

A: Yes. Get the subsystem from your GameInstance and call StartWarmup() directly:

UGameInstance* GI = UGameplayStatics::GetGameInstance(this);
UPSOAutopilotSubsystem* PSO = GI->GetSubsystem<UPSOAutopilotSubsystem>();
PSO->OnWarmupComplete.AddDynamic(this, &AMyActor::OnWarmupDone);
PSO->StartWarmup();

Q: What platforms does the current packaged release support?

A: The current packaged marketplace build is validated and configured for Win64. The underlying code is portable Unreal C++, but only Win64 is exposed in the released plugin descriptor and packaging profiles for this version.

Q: Is the plugin safe to use in Shipping builds?

A: Yes. The core subsystem (UPSOAutopilotSubsystem) and Boot Loader (APSOAutopilotBootLoader) work in all build configurations including Shipping. The Demo Manager (APSOAutopilotDemoManager) is automatically disabled in Shipping builds via a compile-time guard.

Q: Can I run the warmup in a background thread instead of the game thread?

A: No. PSO precaching (PrecachePSOs) must happen on the game thread because it interacts with the rendering subsystem and material proxies. This is an Unreal Engine requirement, not a PSO Autopilot limitation. The time-slicing architecture ensures the game thread is only occupied for a configurable number of milliseconds per frame, keeping your UI responsive.

Q: How do I enable detailed logging?

A: All PSO Autopilot messages use the LogPSOAutopilot log category. To see them:

1. In-Editor: Open the Output Log and filter by LogPSOAutopilot.

2. In -game mode: Add -log to your launch arguments to open the log window.

3. In packaged builds: Add -log or check the saved log file in Saved/Logs/.

The plugin logs state transitions, batch progress, asset counts, fingerprint values, timing data, and any warnings or errors.

Q: Is "Compiling shader autogen file: AutogenShaderHeaders.ush" PSO Autopilot starting during packaging?

A: No. Lines such as Using Local Shader Compiler with 17 workers, Compiling shader autogen file: .../Intermediate/ShaderAutogen/.../AutogenShaderHeaders.ush, and Autogen file is unchanged, skipping write are normal Unreal shader-cook setup. PSO Autopilot starts at runtime when the packaged game reaches the loader, the one-node loading flow, or your custom call to start warmup.

Use LogPSOAutopilot: Starting PSO Autopilot Warmup... as the marker for the plugin's runtime phase.

Q: The log shows "IsWarmupRunning() is true, ignoring StartWarmup call."

A: You called StartWarmup() while a warmup is already in progress. The plugin guards against re-entrant calls. Wait for OnWarmupComplete to fire before starting another warmup, or check IsWarmupRunning() before calling.

Q: The warmup seems stuck in "Processing Batch" for a very long time.

A: This state is time-sliced, so it only runs for MaxProcessingTimeMsPerFrame per tick. If you have thousands of materials with complex shader permutations, this phase can take minutes. Check the log for the PSO remaining count—if it's decreasing, the plugin is working normally. If it's truly stuck at a fixed number, there may be a shader compilation issue with a specific material. Try reducing your scan scope to isolate the problematic asset.