Tuning Performance

Sky Pro provides four quality tiers that configure the main rendering costs together.

const sky = await SkySystem.create({
  renderer,
  camera,
  scene,
  quality: "high"
});

// Switch at runtime
await sky.setQualityLevel("low");

"high" is the default.

Cloud Rendering Modes

Cloud rendering mode sets cloud motion, rendering cost, and how quickly fresh samples replace the previous frames:

Mode	Cloud motion	Complete refresh	Use case
"static"	Stopped	16 frames (~0.27 s at 60 FPS)	Fixed skies and the lowest background cost
"dynamic"	Wind drift and evolution	16 frames (~0.27 s at 60 FPS)	General use and the lowest animated-cloud cost
"ultra-dynamic"	Wind drift and evolution	4 frames (~0.07 s at 60 FPS)	Fast camera movement

const sky = await SkySystem.create({
  renderer,
  camera,
  scene,
  quality: "high",
  cloudRenderingMode: "static",
});

Static mode also removes wind drift and noise evolution from the cloud shaders, and unchanged cloud-shadow and environment-map bakes are skipped. Recreate the SkySystem to change modes.

Choose a Tier

• low — mobile, VR, weak integrated GPUs. Soft, upscaled clouds; no god rays; sky-only reflections.
• medium — laptops and integrated GPUs.
• high — desktop default.
• ultra — high-end desktop GPUs and high-quality captures.

If high exceeds the frame budget, try medium before overriding individual settings.

What Each Tier Sets

Field	low	medium	high	ultra	Perf impact
cloudHistoryDiv	4	2	2	2	Large
cloudFullLightingAlpha	0.3	0.3	0.5	0.7	Medium
cloudShadowResolution	128	256	512	1024	Small
cloudShadowMipLevel	3	2	2	1	Small
godRaysEnabled	off	on	on	on	Medium
godRaySteps	16	16	24	24	Small
envMapClouds	off	on	on	on	Medium
envMapWidth × Height	256×128	384×192	512×256	1024×512	Medium
envMapMarchSteps	24	32	48	64	Medium
envMapMipBase	3	2	1	1	Small
weatherMapResolution	256	512	1024	1024	None
baseShapeDims	16³	32³	64³	64³	None

Performance impact is relative and assumes visible clouds. Screen-cloud resolution has the largest effect, followed by god rays and environment-map rendering.

cloudFullLightingAlpha sets how much cloud opacity receives full lighting detail before the faster approximation takes over. Higher values preserve detail deeper into opaque clouds and increase cost.

Cloud Resolution and Refresh Time

Clouds are expensive to render because each ray requires many samples through the atmosphere. Sky Pro reduces that cost in two stages:

1. It raymarches the clouds into a smaller image.
2. It combines the new samples with reprojected samples from previous frames to reconstruct a larger cloud image.

cloudHistoryDiv controls the size of that reconstructed image. A value of 2 makes it 1/2 of the screen width and 1/2 of the screen height. A value of 4 makes it 1/4 of the width and height.

Refresh Time

Cloud rendering mode spreads a complete set of fresh cloud samples across multiple frames:

• Static and Dynamic: Render 1/16 of the fresh samples each frame. Every sample has been refreshed after 16 frames.
• Ultra Dynamic: Renders 1/4 of the fresh samples each frame. Every sample has been refreshed after 4 frames.

The reconstructed cloud image is still produced every frame. Positions without a new sample use validated history from earlier frames.

The 16-frame modes render one quarter as many cloud rays as Ultra Dynamic at the same quality level. The tradeoff is slower response: fast camera movement and nearby or rapidly changing clouds depend on older history for longer.

The two settings combine as follows:

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

Resolution by Quality Tier and Mode

Quality	Reconstruction	Static/Dynamic raymarch	Ultra Dynamic raymarch
low	1/4 × 1/4 screen	1/16 × 1/16 screen	1/8 × 1/8 screen
medium	1/2 × 1/2 screen	1/8 × 1/8 screen	1/4 × 1/4 screen
high, ultra	1/2 × 1/2 screen	1/8 × 1/8 screen	1/4 × 1/4 screen

At the same quality tier, Ultra Dynamic traces four times as many cloud rays as Static or Dynamic in exchange for refreshing every reconstructed position four times sooner. Switching quality tiers does not change the cloud rendering mode.

Other Performance Controls

Cloud shadows (cloudShadowResolution, cloudShadowMipLevel) control ground-shadow detail. Lower resolution and higher mip levels reduce cost and produce softer shadows.

God rays (godRaysEnabled, godRaySteps) add no rendering cost when disabled. When enabled, cost scales with godRaySteps. The low tier disables them.

Reflection environment maps affect water and reflective materials. Disable envMapClouds to remove the reflection cloud raymarch. envMapWidth, envMapHeight, envMapMarchSteps, and envMapMipBase control the remaining cost. These tier fields apply to the map managed by createSkyProvider({ envMap: true }); standalone maps use their own options. See Reflections.

Noise resolution (weatherMapResolution, baseShapeDims) affects texture memory and load time rather than steady per-frame cost. The bundled 16³, 32³, and 64³ volumes are precomputed; custom dimensions are generated at runtime.

Override a Setting

Pass a partial config to override individual fields on top of a tier:

// medium, but with sharper cloud shadows
await sky.setQualityLevel("medium", { cloudShadowResolution: 512 });

setQualityLevel returns a promise — await it before relying on the new tier being live.

See Also

• QUALITY_LEVELS — the tier table as exported config
• Reflections — env-map settings in detail