PSO Autopilot Manual

🖥️ Supported Platform in This Release

The packaged marketplace build documented here is currently validated and configured for Win64. The source architecture is portable, but only Win64 is exposed in the released descriptor and packaging profiles for this version.

🧪 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 your destination game level before travel. This is the same flow used by the bundled /Game/Demo/Demo_BootFlow sample.

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.

🛣️ 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.

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.

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..., 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, or texture streaming counts.

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.

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()

Cache Storage Location

Fingerprints are stored in GameUserSettings.ini under the [PSOAutopilot] section as a comma-separated list in the CompletedFingerprints key. The plugin also reads the legacy single-fingerprint key for backward compatibility. You can clear this section to force a full re-warmup on the next launch.

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.

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: 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. GameUserSettings.ini not saved: The fingerprint is written to GameUserSettings.ini. If the game crashes before this file is flushed, the cache is lost. Check that the file is 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 GameUserSettings.ini (in your project's Saved/Config/ folder) and delete the [PSOAutopilot] section.

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 doesn't match any package on disk. The Boot Loader validates the level before attempting the transition to prevent crashes. 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.

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 default editable widget should live at /Game/PSOAutopilot/WBP_PSOAutopilotLoadingScreen.

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 the editable /Game/PSOAutopilot/WBP_PSOAutopilotLoadingScreen Widget Blueprint.

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: 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.