PSO Autopilot Manual

Batch Loop Details

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.

On Progress Updated

Fires continuously during the warmup phase.

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): Live telemetry of the internal state. Messages cycle through: Scanning for Assets..., Loading Batch of 100..., Compiling PSOs... (42 remaining), Pre-heating VRAM..., Clearing Memory....

On Warmup Complete

Fires exactly once when the entire process is finished (or if it is instantly skipped via USP 3). 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 the warmup 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. You can clear this key 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 full telemetry panel with progress bar, status text, timer, batch metrics, cache comparison, and a 60fps spinner.

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. PSO Autopilot handles this with a synchronous scan fallback, but verify you're on v1.2 or later.

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

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

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. PSO Autopilot fingerprints the scanned assets, not their dependency chains. Re-save the parent material to force a new timestamp.

3. 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 short name (e.g., MainMenu), not the full path.

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.

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

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: 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: Does PSO Autopilot work on consoles (PlayStation, Xbox, Switch)?

A: PSO Autopilot is a pure C++ plugin with no platform-specific code. It uses only standard Unreal Engine APIs (FStreamableManager, PrecachePSOs, FShaderPipelineCache). It will compile and run on any platform that UE5 supports. However, you should tune BatchSize aggressively downward on consoles (25–50) to stay within their tighter memory budgets.

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.