Distinguish cooked shaders from pipeline creation
A Pipeline State Object describes the graphics state needed for rendering; the terminology varies between APIs such as D3D12, Vulkan and Metal. A cache supplies descriptions the application can prepare ahead of their use. A game may need more than one state for a material, because the rendering situation includes more than the shader alone. [2]
Unreal's shader documentation explains that cooking stores compiled material shaders with their packages and global shaders separately. That process is different from preparing every pipeline state the graphics driver will need when the game runs. Rebuilding the project's development shader cache is therefore not, by itself, proof that first-time players will avoid runtime pipeline hitches. [3]
Start with a build that resembles delivery
Package the actual platform, graphics API and content configuration. Use a diagnostic build to investigate, then confirm the final intended distribution configuration. Epic distinguishes Development and Shipping configurations because their debugging facilities and runtime behavior are not identical. An editor session is useful during development but cannot replace this packaged-build check. [7]
Write down the engine version, build revision, hardware, driver and quality settings for every run. Keep those inputs stable while comparing a fix. Select a route containing ordinary gameplay and first-use situations: entering a new area, equipping an item, triggering an effect and changing a relevant graphics option. A route that never exercises the affected state cannot clear the issue.
Capture a cold run and a repeat run
Developer machines can already have a warm driver cache. Epic documents -clearPSODriverCache for supported test runs so cached work does not hide first-use behavior. Keep that diagnostic use separate from normal player startup; confirm applicability to the selected platform and engine. [1]
Capture a frame trace and inspect the spike rather than only the average. Timing Insights lets you select a frame or time interval, inspect CPU/GPU tracks and correlate logs with the selected interval. Compare where the time was spent: loading a package, running game logic, waiting for work or creating rendering state. A cold-run hitch disappearing on the second run is evidence to investigate, not a diagnosis on its own. [4]
Enable the trace channels needed for the question. Epic's Insights reference documents CPU, Frame, Log and LoadTime channels; asset-load tracing requires CPU tracing. Collecting a useful trace is preferable to collecting every possible event without a question. Name the capture by build and scenario so another developer can reproduce and examine it. [5]
Check effective precaching and its evidence
Verify r.PSOPrecaching in the effective target configuration and check RHI support. Epic's automatic system collects and compiles PSOs asynchronously. Validation plus stat PSOPrecache helps distinguish states that were missed from states that were requested but finished too late. Those outcomes point to different work: coverage versus readiness. [1]
Connect each finding to a specific event in the reproduction route. Keep the material, rendering pass and affected scenario with the issue. If the trace attributes a different spike to loading or gameplay, track that separately. Declaring every stall a shader problem can send the team toward cache work while leaving the player's most noticeable interruption untouched.
| Evidence | Question to ask | Useful next check |
|---|---|---|
| PSO missed | Was the required state covered? | Inspect the affected material and rendering path |
| PSO too late | Was preparation requested early enough? | Compare request timing with first use |
| Loading dominates the frame | What content became resident here? | Inspect the load trace and transition |
| Gameplay dominates the frame | What work was triggered together? | Inspect the responsible CPU events |
Make preparation visible to the player
A loading screen can wait for currently outstanding precache work; Epic documents FShaderPipelineCache::NumPrecompilesRemaining() for that check. Completion concerns the requests known at that moment, so it does not replace gameplay coverage testing. Decide how initial preparation and later content transitions will be presented. [1]
Compare startup time, responsiveness and visual readiness together. Moving a noticeable hitch into a deliberate transition can be a useful outcome, but a longer loading screen is still a production tradeoff to measure. Test low-end target hardware and available memory rather than designing the experience around the development workstation. Keep progress feedback understandable and preserve a route back to the menu if your application's loading workflow needs it.
Use a bundled cache when the evidence requires it
The manual bundled-cache workflow records states encountered while playing and includes that information in a later build. Its value depends on the states your collection route exercises. If you use it, cover the shipped content and relevant rendering configurations, then verify the result in the package rather than assuming a recorded file is complete. [2]
For Android, Epic describes bundled caching as the legacy manual method and recommends automatic precaching from UE 5.3 onward where viable. That is a starting recommendation, not a guarantee of coverage for every project. Use the selected engine's documented workflow and verify the target device; do not mix files and recipes from unrelated platforms or branches. [6]
Give production a clear acceptance result
Agree which first-use events must be smooth, what initial preparation is acceptable and which hardware configurations are in scope. The evidence should include a fresh-run capture, a repeat-run comparison, the effective settings and the unresolved issue list. Average FPS can accompany those observations, but it cannot replace them.
Repeat the selected routes after changes to rendering features, materials or the engine. Keep PSO coverage work attached to normal build validation so it survives the next content update. The delivery goal is a predictable player experience with attributable frame spikes, not a console-variable checklist that no one has tested in the shipped application.
Official sources
Technical statements link to official documentation. Planning and acceptance recommendations are ByOwls editorial guidance.
Technical sources reviewed .
- PSO Precaching — Epic Games
- Optimizing Rendering with PSO Caches — Epic Games
- Shader Development — Epic Games
- Timing Insights — Epic Games
- Unreal Insights Reference — Epic Games
- Creating Bundled PSO Caches for Android — Epic Games
- Packaging Your Project — Epic Games