Skip to main content
Version: Next (dev)

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. Android builds also offer a Mobile preset and start on it (see Mobile preset).

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.

In the editor, the Quality Settings panel builds such a preset for you: change single settings on top of a tier, then use Save as preset... to write them into this file.

What presets control​

Presets control 74 settings, listed in the table below. They cover sampling budgets and resolutions, and a few feature controls: the specular GI technique, ray-traced specular shadows, the direct lighting mode, ReSTIR DI, depth of field, motion blur and contact shadows. The diffuse GI technique, diagnostic modes, queue and thread scheduling, light intensity, exposure, artistic colours and content bounds remain project or developer controls and are not touched. The editor's Quality Settings panel can also override a handful of these project-owned settings for your own session.

Feature controls​

  • Rendering.GI.Specular.Technique: 0 = screen space (SSR plus reflection probes, no rays), 1 = screen space with ray-traced misses, 2 = ray traced, 3 = path traced (only with the path-traced diffuse technique). It replaces Rendering.GI.Specular.Mode; values saved under the old name in presets and player overrides are translated when they load.
  • Rendering.DirectLighting.Mode: 0 = classic shadow-mapped lighting, 1 = probe cached, 2 = ReSTIR DI, 3 = guided. Low, Medium and High use classic lighting and Max uses ReSTIR DI where it is supported. No built-in tier picks guided lighting; projects can opt in.
  • Rendering.DepthOfField.Quality, Rendering.MotionBlur.Quality: 0 = Low to 3 = Max. Rendering.MotionBlur.Allowed is on in every tier; only the Mobile preset clears it. Whether a scene uses blur at all is still decided by its cameras and post process volumes. See Depth of Field and Motion Blur.
  • Rendering.ContactShadows.LocalLights and Rendering.ContactShadows.Quality: the number of local lights that get a contact shadow besides the sun (0, 2, 4, and 8 on Max) and the trace quality (0 = hard, 1 = softened and temporally accumulated, 2 = longer rays). See Contact Shadows.

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

Values per tier​

Low reduces sampling and allocations, Medium tracks balanced budgets, and High spends more on samples and resolution. Max uses High's value for every setting except the ones whose Max column differs: ReSTIR DI, guided lighting at full resolution, depth of field, motion blur and contact shadows. Several radiance cascades, path tracing and shadow technique settings currently hold the same value in every tier until those tiers are tuned.

The GI resolution settings (Rendering.GI.Specular.Resolution, Rendering.GI.RTGI.Resolution) take 0 = full, 1 = half, 2 = quarter resolution. They replace the older *.HalfRes booleans, which are translated when old presets and player overrides load.

These are starting budgets, not guaranteed performance targets for every scene and GPU.

CVarLowMediumHighMaxRange
Rendering.GI.Specular.Enabledtruetruetruetrueboolean
Rendering.GI.Specular.Technique01110..3
Rendering.GI.Specular.RT.Shadowsfalsefalsetruetrueboolean
Rendering.DirectLighting.Mode00020..3
Rendering.ReSTIRDI.Enablefalsefalsefalsetrueboolean
Rendering.ReSTIRDI.HalfResfalsefalsefalsetrueboolean
Rendering.GuidedLighting.SamplesPerCell24441..16
Rendering.GuidedLighting.HalfRestruetruetruefalseboolean
Rendering.GuidedLighting.NRD.AtrousIterations34552..8
Rendering.Shadows.Quality01220..2
Rendering.Shadows.MaxCascades44441..4
Rendering.Shadows.LocalLightstruetruetruetrueboolean
Rendering.VolumetricFog.PixelsPerFroxel168442..64
Rendering.VolumetricFog.FroxelGridSizeZ3264969616..128
Rendering.VolumetricClouds.Quality01220..3
Rendering.VolumetricClouds.ShadowResolution25651210241024128..2048
Rendering.DepthOfField.Quality01230..3
Rendering.MotionBlur.Quality01230..3
Rendering.MotionBlur.Allowedtruetruetruetrueboolean
Rendering.ContactShadows.LocalLights02480..8
Rendering.ContactShadows.Quality00120..2
Rendering.Culling.GPU.Meshlets.LODErrorScreenPercent0.30.150.0750.0750.01..2
Rendering.Shadows.AtlasSize2048409681928192512..8192, power of two
Rendering.Shadows.MaxShadowMapSize51210242048204864..2048, power of two
Rendering.Shadows.VSMResolutionBias21.5110.5..4
Rendering.Culling.GPU.Meshlets.ShadowLODErrorPixels42110.25..16
Rendering.GI.Specular.Resolution22100..2
Rendering.GI.RTGI.Resolution22100..2
Rendering.GI.RTGI.ProbeSpacing168882..64, power of two
Rendering.GI.RTGI.RaysPerProbe4816161..64
Rendering.GI.RTGI.SpatialPasses23441..5
Rendering.GI.RTGI.MaxEvaluatedLights64256102410241..1024
Rendering.GI.RTGI.MaxShadowedLights11241..8
Rendering.GI.RT.NRD.AtrousIterations35662..8
Rendering.GI.Specular.RT.MaxEvaluatedLights64256102410241..1024
Rendering.GI.Specular.RT.MaxShadowedLights11241..8
Rendering.GI.Specular.RT.Denoise.SpatialPasses23441..5
Rendering.GI.Specular.RT.Reuse.Taps4812121..16
Rendering.AO.RTAORaysPerPixel11221..8
Rendering.AO.RTAOSpatialPasses12331..4
Rendering.ReSTIRDI.GridCandidates481281..32
Rendering.ReSTIRDI.FroxelCandidates24841..16
Rendering.ReSTIRDI.EmissiveCandidates12421..16
Rendering.ReSTIRDI.SpatialTaps35851..16
Rendering.ReSTIRDI.SpatialTaps213530..16
Rendering.ReSTIRDI.AreaSamples12420..8
Rendering.ReSTIRDI.NRD.AtrousIterations35641..8
Rendering.VDBVolumes.RayMarchSteps326496968..256
Rendering.VDBVolumes.RayMarchShadowSteps24661..16
Rendering.VDBVolumes.SelfShadowTaps35770..16
Rendering.VDBVolumes.ShadowResolution6412825625632..512, power of two
Rendering.VDBVolumes.ShadowStepScale421.51.51..8
Rendering.VDBVolumes.Detailfalsetruetruetrueboolean
Rendering.VDBVolumes.ScatterOctaves12331..3
Rendering.GI.RadianceCascades.Cascades55551..6
Rendering.GI.RadianceCascades.Directions44442..8
Rendering.GI.RadianceCascades.ProbeSpacing88882..32
Rendering.GI.RadianceCascades.SoftwareProbeSpacing161616162..32
Rendering.GI.RadianceCascades.MultiBouncetruetruetruetrueboolean
Rendering.PathTracing.ResolutionScale11110.25..1
Rendering.PathTracing.ResolutionScale.Direct11110.25..1
Rendering.GI.RTGI.VRRTfalsefalsefalsefalseboolean
Rendering.GI.RTGI.RadianceCachefalsefalsefalsefalseboolean
Rendering.GI.Specular.SSR.MaxSteps323232328..128
Rendering.GI.Specular.Software.MaxRoughness0.60.60.60.60..1
Rendering.ProbeDirectLighting.RayBudget323232321..256
Rendering.ProbeDirectLighting.MaxLightsPerProbe161616161..64
Rendering.GuidedLighting.AreaSamples44441..16
Rendering.Shadows.UseVirtualShadowMapstruetruetruetrueboolean
Rendering.Shadows.VSMClipmapLevels77771..8
Rendering.CharacterShadow.Resolution2048204820482048512..4096, power of two
Rendering.ContactShadows.Enabletruetruetruetrueboolean
Rendering.AntiAliasing00000..2
Rendering.Textures.Streaming.MipBias0000-1..3

Mobile preset​

Android builds add a Mobile preset (mobile) and use it as the default. It is the Low budgets with settings for tile-based phone GPUs: one sun shadow cascade, unshadowed local lights, medium shadow filtering (the variant that Android shaders are compiled for), cascaded instead of virtual shadow maps, the cheapest depth of field and contact shadows, and no motion blur.

A project preset file can choose another Android default with Default.Android:

VarDict
{
string %Default { "high" }
string %'Default.Android' { "mobile" }
}

Project presets can use Base = "mobile" on Android. Desktop builds do not offer the Mobile preset, nor project presets based on it.

The Mobile preset only sets quality values. The mobile render path itself (the mobile forward pipeline and shading tier) comes from the Android platform profile, see Mobile render pipeline and Shipping.

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 and platform shadow defaults respect settings-owned CVars, so they cannot silently replace the player's quality modes or budgets.

Post process volumes are the exception: a volume can override a preset-owned CVar, such as the GI specular technique or a budget, as a scene layer above the player's settings. While the volume applies, its value wins. When it stops overriding the CVar, the player's value (from the preset or their own override) is restored. A volume does not change the selected preset, and does not make it read as custom.

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.

See Also​