How to Check Whether Unreal Engine PSO Pre-Caching Works

To check whether Unreal Engine PSO pre-caching works, test a packaged game with validation enabled, inspect its PSO statistics, and capture gameplay in Unreal Insights. The useful evidence is whether required pipelines are ready when the game needs them—and whether their creation still interrupts a frame.

A setting showing r.PSOPrecaching=1 only confirms configuration. Likewise, a smooth second playthrough cannot establish that the first-time experience works correctly: previously cached data may be helping.

This guide focuses on developers and technical testers with access to an Unreal Engine project. It explains how to prepare a diagnostic build, reproduce a first-run scenario, interpret the results, and investigate remaining stutters. If you only have a retail game, your access to these tools depends on what its developer exposes.

What should successful PSO pre-caching achieve?

A Pipeline State Object, or PSO, describes shaders and rendering state needed for a graphics operation. Preparing pipelines before their first use helps prevent the game from waiting for compilation during rendering.

Epic distinguishes automatic pre-caching from bundled PSO caches collected through testing. GPU drivers also retain compiled data between sessions, which can make later runs behave differently.

For verification, separate three questions:

• Configuration: Is the intended system enabled in the executable being tested?
• Coverage and timing: Does it prepare the pipelines required by your test route before they are needed?
• Player experience: Does gameplay meet your frame-time target without unacceptable visual delays?

Treat these as separate checks. A configuration screenshot cannot answer the other two.

1. Prepare a packaged Development build

Start with a packaged Development build for the target platform. Epic documents Development builds as suitable for testing with console access; ordinary Shipping builds disable console commands and diagnostic tools intended for development.

Avoid using a Play in Editor session as your only verification. Developer Tom Looman’s implementation guide specifically identifies stat PSOPrecache as unavailable in builds compiled with WITH_EDITOR, recommending a packaged executable for these statistics.

Before testing, record:

• Engine version and project build.
• CPU, GPU, and graphics driver.
• Active rendering API, such as DirectX 12.
• Graphics preset and relevant rendering options.
• Starting save, map, and gameplay route.
• Whether bundled and previously generated user PSO caches are present.

Use the same conditions when comparing runs. Otherwise, you may attribute a difference to pre-caching when the content or rendering configuration changed.

2. Enable validation before launching

For a diagnostic build, add or update these entries in the project’s Config/DefaultEngine.ini:

[/Script/Engine.RendererSettings]
r.PSOPrecaching=1
r.PSOPrecache.Validation=2
r.PSOPrecache.Validation.TrackMinimalPSOs=1

Epic documents this configuration section for rendering console variables. Update existing entries instead of leaving conflicting copies across configuration files.

This setup enables automatic pre-caching, detailed validation, and additional diagnostic tracking. Package the project with the settings applied, then start a fresh process. Looman’s guide uses these variables for packaged-build investigation.

In the game console, enter the variable names individually to inspect their effective values:

r.PSOPrecaching
r.PSOPrecache.Validation

For this configuration, expect 1 and 2, respectively.

Pre-caching also requires support from the active rendering hardware interface, or RHI. An enabled variable alone does not establish that the required rendering path supports it.

If a command is unrecognized, first check the executable type and engine version. Changing unrelated graphics settings will not resolve a missing diagnostic command.

3. Run a controlled test with an empty driver cache

A repeat run can reuse compiled pipelines from an earlier session. That makes it useful for testing returning players, but insufficient for assessing the first-run experience. Epic recommends clearing the driver cache during first-use testing.

For a Windows project packaged with DirectX 12 support, an example launch command is:

MyGame.exe -d3d12 -clearPSODriverCache -trace=cpu,frame,gpu,bookmark,log -tracefile=PSO-Cold.utrace

Replace MyGame.exe with your executable. Use a writable location for the trace file.

The -clearPSODriverCache argument clears the PSO driver cache. Unreal’s trace arguments select recording channels and an output file.

Record from startup so you can inspect both loading and gameplay.

Control the other caches, too

Clearing the driver cache does not establish that every other cache starts empty. Unreal can load a bundled cache and merge previously saved user PSO data with it.

For a first-install test, use a controlled QA profile without accumulated user PSO data while retaining the bundled cache you intend to distribute.

For a returning-player test, preserve the relevant caches.

For an investigation specifically isolating automatic pre-caching, document how bundled and user caches are handled. Otherwise, a successful run establishes that the combined configuration works, without identifying which mechanism supplied the benefit.

This deliberate testing procedure differs from routine player troubleshooting. Our explanation of why clearing DirectX Shader Cache can increase stutter covers the player-facing consequences.

4. Read stat PSOPrecache correctly

With validation active, enter:

stat PSOPrecache

Interpret the counters as follows:

Start with Full PSOs, which represent complete runtime state. Shader-only statistics omit other state; Minimal PSOs also exclude render-target information. Consequently, shader-only success cannot establish complete pipeline coverage.

Capture statistics at the beginning and end of each test segment. Keep the segment boundaries consistent: menu activity and gameplay should not become an unexplained combined total.

Do not use the largest number as the success metric

“Thousands precached” is an activity report. Your acceptance question is whether the particular encounter, effect, or transition under investigation renders smoothly.

Likewise, avoid presenting one overall success percentage as proof that every significant problem is solved. A rare hitch during the first attack or a major cutscene can matter more to the player than many uneventful frames.

Keep the counters alongside the recorded route and trace.

5. Investigate frame spikes in Unreal Insights

Open the .utrace recording in Unreal Insights. On Windows, Epic’s quick-start guide identifies the application at:

Engine\Binaries\Win64\UnrealInsights.exe

The Session Browser can open a saved trace for analysis in Timing Insights.

With PSO validation enabled, look for these timers:

PSOPrecache: Missed
PSOPrecache: Too Late

Epic documents them for investigating compilation-related interruptions. Detailed miss logs can also identify the material, vertex factory, and mesh pass involved.

Use this workflow:

1. Select the gameplay interval containing the visible hitch.
2. Find the relevant timer in the Timers panel.
3. Use its plotting options to compare its activity with game-frame timing.
4. Zoom into the affected frame and inspect the surrounding work.
5. Save the matching log information with the reproduction steps.

Timing Insights supports plotting timer instances and per-frame statistics, and exporting selected events for comparison.

A nearby background compilation task is a lead to investigate. Check whether it contributes to the delayed frame before assigning causation.

Compare against your actual frame budget

The frame budget is approximately:

• 60 FPS: 16.67 milliseconds.
• 120 FPS: 8.33 milliseconds.

These figures come from dividing 1,000 milliseconds by the target frame rate. Judge the whole affected frame against your target, rather than relying on a reassuring average FPS value.

If the trace points elsewhere, investigate that work. Epic identifies loading, spawning, and streaming among other potential sources of gameplay interruptions.

Our guide to shader compilation stutter versus traversal stutter explains why symptoms alone can be misleading.

6. Check when the loading screen ends

Inspect the relationship between loading completion and the first playable frame.

Unreal exposes this function for checking pending pipeline precompilation:

FShaderPipelineCache::NumPrecompilesRemaining()

Epic’s bundled-cache documentation describes using it when deciding whether to retain a loading screen. The API reference also notes that the count can increase as additional caches are processed.

The practical implication is that zero is an observation at a particular time. It cannot certify content your test has not encountered.

Record the count when gameplay becomes available, then test later transitions separately. Include a subsequent level, a newly equipped item, and a first-use effect where those are relevant to the game.

Do not judge the loading screen in isolation. Also record:

• How long the player waits.
• Whether controls become available before the intended preparation finishes.
• Whether objects and materials appear correctly afterward.
• Whether a later encounter introduces a new interruption.

Epic describes mechanisms that can delay rendering or use a fallback material while preparation completes. Visual inspection therefore belongs alongside frame-time analysis.

7. Use a repeatable acceptance test

A useful test plan covers more than one familiar corridor.

Repeat the important cases on representative hardware. Record actual results rather than filling a report with expected improvements.

For each run, retain the configuration, route, validation output, trace, and visual observations. A useful result should be reproducible by someone who did not perform the original test.

If you need an enabled-versus-disabled comparison, keep the cache conditions and other settings equivalent. Label it as a diagnostic experiment, then separately verify the final shipping configuration.

What to do when the results are poor

Use the evidence to choose the next investigation:

• Misses around a repeatable event: Investigate the affected rendering path and the state requested at that event.
• Late work around gameplay entry: Examine when content becomes available and when the game allows it to be used.
• Missing diagnostics: Verify the build, configuration, and trace capture before drawing a performance conclusion.
• Frame spikes without supporting PSO evidence: Follow the expensive work shown in the trace.

Check known issues for your engine branch before assuming the project configuration is responsible. For example, Epic’s UE-314647 report documents specific missing or incorrect pre-caching cases affecting UE 5.6. That is evidence for investigating matching symptoms, not proof that every project has the same defect.

Where appropriate, Epic also documents combining automatic pre-caching with a manually collected bundled cache. Verify that such a cache opens and schedules compilation; merely finding a cache file in the package is insufficient.

FAQ

Can I check PSO pre-caching in a retail Unreal Engine game?

Only to the extent that the developer exposes diagnostics. Standard Shipping configurations restrict development console commands and profiling tools. External frame-time measurements can reveal interruptions, but cannot establish the engine’s internal pre-caching state.

Does smoother gameplay on the second run prove pre-caching works?

No. Treat it as a reason to compare cache conditions. You still need a controlled first-run recording to assess the experience of a new player.

Does zero outstanding compilation mean the whole game is covered?

No. It describes pending work at that point. Test later levels, effects, and supported configurations before extending your conclusion to them.

Should every reported PSO problem produce visible stutter?

Do not assume that it does. Match the diagnostic event to measured frame behavior, and report the observed impact rather than inferring its severity from a counter.

Define success with a reproducible result

A defensible result identifies which build, hardware, settings, cache conditions, and gameplay route passed. It includes supporting validation and timing data, with any remaining interruptions explained.

Once that result is repeatable, add the route to regression testing. Expand coverage when new content or rendering options arrive, and verify that the next build preserves the result.