Quality Presets
A quality preset is a named bundle of renderer CVar values. The engine ships Low, Medium (the default), High and Max in Data/Base/RuntimeConfigs/QualityPresets.ddl, with an equivalent compiled fallback for cases where the file is unavailable. The editor, the settings menu and the C# client all read the preset list from the service, and always include Max.
Author project presets
Add <project>/RuntimeConfigs/QualityPresets.ddl to override or extend the shipped tiers:
VarDict
{
string %Default { "high" }
VarArray %Presets
{
VarDict
{
string %Id { "high" }
string %Label { "High (project)" }
VarDict %Values
{
int32 %'Rendering.GI.RTGI.RaysPerProbe' { 12 }
bool %'Rendering.GI.Diffuse.HalfRes' { true }
}
}
VarDict
{
string %Id { "cinematic" }
string %Label { "Cinematic" }
string %Base { "high" }
VarDict %Values
{
int32 %'Rendering.GI.RTGI.RaysPerProbe' { 24 }
int32 %'Rendering.GI.Specular.RT.Reuse.Taps' { 16 }
}
}
}
}
An entry whose Id matches an engine tier merges its individual values over the engine definition. A new identifier inherits from low, medium, high or max, and an omitted Base means medium.
Duplicate identifiers or keys, unknown CVars, invalid types or out-of-range values, and non-power-of-two allocation sizes are rejected. An invalid project definition leaves the engine fallback usable and logs a warning, so a typo cannot leave the game without presets.
Identifiers are stable, and labels are display text only. If a selected identifier is removed from the file, the player's selection falls back to the current default on the next load.
Individual player overrides are stored in Quality.Overrides and yield an effective preset of custom. Selecting a preset clears them.
What presets control
Presets control 45 settings: 40 quality budgets and five feature controls. Diffuse GI algorithm selection, diagnostic modes, queue and thread scheduling, light intensity, exposure, artistic colors and content bounds remain project or developer controls and are not touched.
Feature controls
| Feature control | Low | Medium | High | Max |
|---|---|---|---|---|
Rendering.GI.Specular.Enabled | false (cubemaps) | true | true | true |
Rendering.GI.Specular.Mode | 2 (inactive) | 2 (RT) | 2 (RT) | 2 (RT) |
Rendering.GI.Specular.RT.Shadows | false | false | true | true |
Rendering.DirectLighting.Mode | 0 (classic) | 0 (classic) | 0 (classic) | 2 (ReSTIR DI) |
Rendering.ReSTIRDI.Enable | false | false | false | true |
Low disables specular GI and retains reflection-probe and cubemap lighting, avoiding both voxel and ray-traced specular tracing. Screen-space reflections are future work. Medium and above re-enable specular GI.
Low, Medium and High use classic direct lighting with shadow maps: they use neither probe-cached direct lighting nor ReSTIR DI. Max uses ReSTIR DI where it is supported. Projects can still opt into probe-cached lighting with Rendering.DirectLighting.Mode 1. Its shadow-map suppression requires every opaque and deferred lighting consumer to be connected to the probe visibility output, otherwise classic shadow maps remain available. Switching back to classic also ignores any suppression mask left behind by the previous mode.
Hardware ray tracing still requires the project's Rendering.RT.Enable, a supporting device and the relevant pipeline passes. Presets do not recreate the graphics device, and the renderer keeps its existing non-RT fallback when those prerequisites are absent.
Feature controls are accepted in project Values and in player Quality.Overrides exactly like sampling budgets. Mode values are integers (specular 1 to 4, direct lighting 0 to 2) and toggles require booleans. A custom preset with Base = "max" can, for example, set Rendering.GI.Specular.RT.Shadows to false while keeping ReSTIR DI. Specular mode 4 remains conditional on the renderer's path-traced diffuse mode. Descriptors expose each control's Max value alongside Low, Medium and High.
Quality budgets
Low reduces sampling and allocations, Medium tracks balanced budgets, and High spends more on samples and resolution. Max uses High's 40 budgets and enables ReSTIR DI. High and Max keep the VXGI voxel grid at 64, because doubling each dimension multiplies its memory cost by eight.
These are starting budgets, not guaranteed performance targets for every scene and GPU.
| CVar | Low | Medium | High | Validation |
|---|---|---|---|---|
Rendering.Shadows.Quality | 0 | 1 | 2 | 0..2 |
Rendering.VolumetricFog.PixelsPerFroxel | 16 | 8 | 4 | 2..64 |
Rendering.VolumetricFog.FroxelGridSizeZ | 32 | 64 | 96 | 16..128 |
Rendering.VolumetricClouds.Quality | 0 | 1 | 2 | 0..3 |
Rendering.VolumetricClouds.ShadowResolution | 256 | 512 | 1024 | 128..2048 |
Rendering.ScreenSpaceShadows.MaxSteps | 8 | 16 | 24 | 4..64 |
Rendering.Culling.GPU.Meshlets.LODErrorScreenPercent | 0.3 | 0.15 | 0.075 | 0.01..2 |
Rendering.Shadows.AtlasSize | 2048 | 4096 | 8192 | 512..8192, power of two |
Rendering.Shadows.MaxShadowMapSize | 512 | 1024 | 2048 | 64..2048, power of two |
Rendering.Shadows.VSMResolutionBias | 2 | 1.5 | 1 | 0.5..4 |
Rendering.Culling.GPU.Meshlets.ShadowLODErrorPixels | 4 | 2 | 1 | 0.25..16 |
Rendering.GI.Diffuse.HalfRes | true | true | false | boolean |
Rendering.GI.Specular.HalfRes | true | true | false | boolean |
Rendering.GI.VXGI.VoxelResolution | 32 | 64 | 64 | 16..128, power of two |
Rendering.GI.VXGI.RayStepSize | 2 | 1 | 0.75 | 0.25..4 |
Rendering.GI.RTGI.HalfRes | true | true | false | boolean |
Rendering.GI.RTGI.ProbeSpacing | 16 | 8 | 8 | 2..64, power of two |
Rendering.GI.RTGI.RaysPerProbe | 4 | 8 | 16 | 1..64 |
Rendering.GI.RTGI.SpatialPasses | 2 | 3 | 4 | 1..5 |
Rendering.GI.RTGI.MaxEvaluatedLights | 64 | 256 | 1024 | 1..1024 |
Rendering.GI.RTGI.MaxShadowedLights | 2 | 4 | 8 | 1..8 |
Rendering.GI.RT.NRD.AtrousIterations | 3 | 5 | 6 | 2..8 |
Rendering.GI.Specular.RT.MaxEvaluatedLights | 64 | 256 | 1024 | 1..1024 |
Rendering.GI.Specular.RT.MaxShadowedLights | 2 | 4 | 8 | 1..8 |
Rendering.GI.Specular.RT.Denoise.SpatialPasses | 2 | 3 | 4 | 1..5 |
Rendering.GI.Specular.RT.Reuse.Taps | 4 | 8 | 12 | 1..16 |
Rendering.AO.RTAORaysPerPixel | 1 | 1 | 2 | 1..8 |
Rendering.AO.RTAOSpatialPasses | 1 | 2 | 3 | 1..4 |
Rendering.ReSTIRDI.GridCandidates | 4 | 8 | 12 | 1..32 |
Rendering.ReSTIRDI.FroxelCandidates | 2 | 4 | 8 | 1..16 |
Rendering.ReSTIRDI.EmissiveCandidates | 1 | 2 | 4 | 1..16 |
Rendering.ReSTIRDI.SpatialTaps | 3 | 5 | 8 | 1..16 |
Rendering.ReSTIRDI.SpatialTaps2 | 1 | 3 | 5 | 0..16 |
Rendering.ReSTIRDI.AreaSamples | 1 | 2 | 4 | 0..8 |
Rendering.ReSTIRDI.NRD.AtrousIterations | 3 | 5 | 6 | 1..8 |
Rendering.VDBVolumes.RayMarchSteps | 32 | 64 | 96 | 8..256 |
Rendering.VDBVolumes.RayMarchShadowSteps | 2 | 4 | 6 | 1..16 |
Rendering.VDBVolumes.SelfShadowTaps | 3 | 5 | 7 | 0..16 |
Rendering.VDBVolumes.ShadowResolution | 64 | 128 | 256 | 32..512, power of two |
Rendering.VDBVolumes.ShadowStepScale | 4 | 2 | 1.5 | 1..8 |
Switching tiers at runtime
The default quality presets apply without restarting the game.
Rendering.Shadows.AtlasSize and Rendering.Shadows.MaxShadowMapSize retain their delayed values until the renderer reaches a drained frame boundary, then rebuild automatically. Work already extracted against the old atlas is discarded and fresh extraction is requested, so a preset change can briefly skip a rendered frame. Every other entry uses the renderer's normal runtime update and reallocation paths.
Discarding extracted work during a shadow-atlas resize also invalidates virtual-shadow page bookkeeping and buffered uploads. Pages queued for discarded draws are requested and rendered again, and unusable virtual-shadow views stay dirty rather than being marked complete. GPU dumps explicitly capture the persistent virtual atlas even on frames with no dirty-page draws, so resident-but-empty pages can be inspected.
Pipeline deserialization, platform shadow defaults and post-process volumes respect settings-owned CVars, so scene settings cannot silently replace the player's quality modes or budgets.
GetQualityDescriptors() reports each control's type, range, power-of-two restriction, current and pending values, command-line locks and restart requirement. Delayed synchronization on its own does not mean a restart is required for these shadow controls.
Validation status
The development RendererTest and GameEngineTest builds passed. The GameSettings and GameSettingsRuntime tests passed on DX12 and Vulkan after Max and the four feature controls were added, covering the probe shadow fallback regression, missing visibility connections, stale suppression after mode changes, compiled and file preset equality, Max inheritance, boolean override validation and live tier selection. The runtime test creates eight shadow-casting point lights and cycles all four presets, checking atlas sizes, reflection modes, reflection shadows, direct-lighting mode and ReSTIR enable without requesting a restart. The Vulkan run used early update kickoff.
Ray tracing was unavailable in that test configuration, so real RT and ReSTIR rendering still needs a test on a supporting project and device. Scene-specific FPS, visual comparison and spotlight appearance remain manual checks. Revalidate custom presets against your cooked shaders, renderer paths and performance budget.