Quality Levels

import {
  QUALITY_LEVELS,
  type QualityLevel,
  type QualityLevelConfig,
  type NoiseDim3,
} from "threejs-sky-pro";

Types

type QualityLevel = "low" | "medium" | "high" | "ultra";
interface QualityLevelConfig {
  // reconstruction divisor; cloud rendering mode applies another 2× or 4× reduction
  cloudHistoryDiv: 1 | 2 | 4 | 8;
  // accumulated cloud opacity where screen lighting switches to its cheaper approximation ([0, 1])
  cloudFullLightingAlpha: number;
  // cloud shadow-map resolution (square), px
  cloudShadowResolution: number;
  // mip the shadow bake samples the cloud field at (0 = finest)
  cloudShadowMipLevel: number;
  godRaysEnabled: boolean;
  // god-ray view-ray march step count
  godRaySteps: number;
  // bake the reflection env map per frame
  envMapEnabled: boolean;
  // bake clouds into the reflection
  envMapClouds: boolean;
  // equirect width, px
  envMapWidth: number;
  // equirect height, px (typically width / 2)
  envMapHeight: number;
  // env-map cloud raymarch steps
  envMapMarchSteps: number;
  // env-map base-shape noise mip floor
  envMapMipBase: number;
  // 2D weather-map resolution (square), px
  weatherMapResolution: number;
  // base-shape 3D noise resolution ({x,y,z}); non-tier sizes CPU-generate
  baseShapeDims: NoiseDim3;
}

"high" is the default tier.

Bundled Tiers

Field	low	medium	high	ultra
cloudHistoryDiv	4	2	2	2
cloudFullLightingAlpha	0.3	0.3	0.5	0.7
cloudShadowResolution	128	256	512	1024
cloudShadowMipLevel	3	2	2	1
godRaysEnabled	false	true	true	true
godRaySteps	16	16	24	24
envMapEnabled	true	true	true	true
envMapClouds	false	true	true	true
envMapWidth	256	384	512	1024
envMapHeight	128	192	256	512
envMapMarchSteps	24	32	48	64
envMapMipBase	3	2	1	1
weatherMapResolution	256	512	1024	1024
baseShapeDims	16³	32³	64³	64³

cloudHistoryDiv controls temporal-reconstruction resolution. Cloud rendering mode then reduces how many cloud rays render each frame:

Static or Dynamic raymarch divisor = cloudHistoryDiv × 4
Ultra Dynamic raymarch divisor = cloudHistoryDiv × 2

Static and Dynamic refresh every cloud sample over 16 frames. Ultra Dynamic refreshes every sample over 4 frames by rendering four times as many cloud rays per frame.

Screen-Cloud Resolutions

Stage	low	medium	high	ultra
Reconstruction	1/4 × 1/4 screen	1/2 × 1/2 screen	1/2 × 1/2 screen	1/2 × 1/2 screen
Raymarch with Static/Dynamic	1/16 × 1/16 screen	1/8 × 1/8 screen	1/8 × 1/8 screen	1/8 × 1/8 screen
Raymarch with Ultra Dynamic	1/8 × 1/8 screen	1/4 × 1/4 screen	1/4 × 1/4 screen	1/4 × 1/4 screen

The march renders every texel in its target each frame; reprojected history supplies the other positions until their next fresh sample.

Quality tiers configure screen-cloud resolution and lighting, cloud shadows, god rays, environment maps, weather-map resolution, and base-shape noise resolution. The bundled 16³, 32³, and 64³ noise volumes are precomputed; custom dimensions are generated at runtime.

The environment-map fields seed and update the map created by createSkyProvider({ envMap: true }). A standalone map from createEnvironmentMap() uses its own SkyEnvironmentOptions and is not retuned by setQualityLevel().

Switching At Runtime

await sky.setQualityLevel("ultra");

// With overrides
await sky.setQualityLevel("medium", {
  cloudFullLightingAlpha: 0.4,
  cloudShadowResolution: 512,
});

overrides is a Partial<QualityLevelConfig> applied on top of the selected tier.

See Also

• Tuning Performance — picking a tier and what each field costs