Troubleshooting

The common problems, what causes them, and the fix for each.

The sky is blown out to white

The sky writes linear HDR. Set renderer.toneMapping = THREE.ACESFilmicToneMapping (or AgX or Neutral). With autoExposure on, don't also set toneMappingExposure yourself, because the sky overwrites it on every update.

Clouds smear or ghost when the camera moves

Call sky.update(dt) after you move the camera (after controls.update()) and before rendering. The reconstruction reprojects with this frame's matrices. If you teleport the camera, set sky.clouds.reset = true or call sky.setCamera(camera) to drop the history.

No clouds, or clouds cut off at the horizon

The camera's far plane must reach the deck: clouds sit 1–2 km up and fade out by about 60 km. Use far: 20000 or more. If your world isn't in metres, set metersPerUnit.

Nights look like a dim day

That's the metered exposure doing its job. Cap it with maxExposure: 2.4, nightExposure: 5 (1.1). See Keep nights dark.

The ground is lit twice

You probably have both scene.environment = sky.environment and a hemisphere light bound with bindLights. With PBR materials, drop the hemisphere light.

Reflections went black after changing quality

The env and PMREM textures are new objects after a tier change. Listen to environmentchange and re-assign scene.environment, or create the sky with setSceneEnvironment: true. If you plugged the sky into NatureGL Water, re-call water.setSky(sky) on the sky's quality event.

Clouds disappear behind my buildings when I fly above the deck

A plain render always draws geometry over the sky. Use the post pass. It composites clouds in front of geometry from the recorded cloud depth.

The post pass looks wrong with a logarithmic depth buffer

The pass reconstructs position from depth. It supports normal and reversed depth, not logarithmicDepthBuffer.

The cumulonimbus is in the wrong place

That form is anchored in world space around (0, −9.5 km), 10 km north of the origin. Rotate the whole sky with northOffset, or move your scene.

#Known limitations

The cloud layer is a flat slab with no planet curvature. Marching stops at about 60 km, and distant decks fade into the haze.
It supports perspective cameras only. One main camera gets the screen-space cloud buffer; XR and array cameras fall back to the env map.
The cloud shadow map covers ±8 km around the camera (shadowExtent).
envMap has no mip chain, so use environment for rough materials. The PMREM sample reduction touches a private PMREMGenerator field, on a best-effort basis.
Everything is WebGL2 GLSL; there is no WebGPU/TSL path.