PSO Prewarming
The pipeline-state (PSO) precompilation technology is shared by XFSDK Core and XFSDK Light.
Core uses the x_ CVar prefix; Light uses xl_. For the shared loading-screen controls, the remaining CVar name is identical.
The first time a player runs your game, the GPU driver has to compile a pipeline state (PSO) for every combination of material, mesh type and render pass it meets. Each one can take milliseconds, which shows up as stutter the first time something appears on screen.
The documented XFSDK Light implementation compiles them up front, behind a progress screen, on a dedicated map:
- It finds every cooked static mesh, skeletal mesh and Niagara system in the Asset Registry.
- It loads them in small batches and requests their PSOs exactly the way a component in a level would: every material slot, every render pass, as a regular and as an instanced mesh (foliage, ISM/HISM).
- It waits until the driver has compiled the batch, frees it, and moves on.
- When everything is done, it saves a marker in
GameUserSettings.iniand opens your startup map.
It runs again only when it needs to: on the first start, after a GPU or driver change (drivers keep their pipeline cache per driver version) and after a plugin update that changes the precompilation.
Unreal 5.8 already loads a material's shaders together with the material (r.ShaderCodeLibrary.PreloadShaderMaps).
What stalls the first run is compiling the pipeline states, which is what this step does. Earlier XFSDK versions
preloaded shaders instead, which no longer helps on 5.8.
Setup in XFSDK Light
Configure first-start PSO precompilation for XFSDK Light.
Settings (XFSDK Light)
| Setting | Default | Description |
|---|---|---|
| Loading Widget Class | WBP_ShaderPrecompilation | The progress widget. Must derive from XFSDKShaderPrecompilationWidget. |
| Assets Per Batch | 8 | Assets loaded and precached together (1–64). |
| Precache Instanced Meshes | true | Also precache every static mesh as an instanced mesh. Turn off if you don't use foliage or ISMs. |
| Include Engine Content | false | Also precache cooked /Engine content. |
Progress widget
Create a Widget Blueprint with XFSDKShaderPrecompilationWidget as its parent class (or edit
WBP_ShaderPrecompilation). Two ways to show progress:
By name, no Blueprint logic. A ProgressBar named PrecompilationProgress and a TextBlock named
PrecompilationProgressText are filled automatically. The text shows:
Compiling shaders for first start 120/840
35 pipelines compiling - SM_Fern_02
With your own widgets. Bind to these getters on self, or implement the event:
| Function | Returns |
|---|---|
| Get Progress | 0–1. Moves smoothly within each batch. |
| Get Completed Assets / Get Total Assets | e.g. 120 / 840 |
| Get Pipelines Compiling | PSOs still compiling, engine-wide |
| Get Current Asset Name | The mesh or Niagara system being precached |
| Get Status Text | The default two-line text |
| Event On Precompilation Progress | Called on every update with all of the above |
The output log category is LogXFSDKShaderPrecompilation.
References
- Epic Games. PSO Precaching for Unreal Engine. dev.epicgames.com/documentation/en-us/unreal-engine/pso-precaching-for-unreal-engine