Changelog

All notable changes to Three.js Sky Pro are documented here.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

2.2.0

This release replaces cloud amortization with explicit rendering modes and reduces the rendering cost of clouds and related effects.

For help migrating from v2.1 → v2.2 see the migration guide.

Breaking Changes

• SkySystem.create({ cloudRenderingMode }) replaces cloud amortization.
• SkySystemConfig.cloudAmortization, sky.cloudAmortization, CloudAmortization, and setCloudAmortization() are removed. Select cloudRenderingMode when creating SkySystem instead.
• QualityLevelConfig.cloudAmortization is removed. Delete it from custom quality configs; quality tiers no longer change the cloud rendering mode.
• WeatherMapProfile.precipitation was unused and has been removed. Delete the unused field from custom weather profiles.

New Features

• Reduced volumetric-cloud rendering cost across all cloud rendering modes.
• Static rendering mode now skips unchanged cloud-shadow and reflection updates, reducing background GPU work for fixed skies.
• Improved performance of god rays and bloom.
• Reduced weather-map generation work and texture memory use, along with cloud-shadow texture bandwidth.

2.1.1

Bug Fixes

• Fixed cloud occlusion and scene-distance effects for renderers without a logarithmic depth buffer.

2.1.0

Breaking Changes

• RenderLayer.worldSurface is now an opaque layer. Set transparent = false on the water surface you place there, or placeInLayer warns.
• QualityLevelConfig now requires cloudAmortization (1 | 2 | 4) and cloudFullLightingAlpha ([0, 1]); add both fields to complete custom quality configs.

New Features

• Environment maps can defer their first bake with initialBake: false, avoiding an unnecessary render before startup settings are applied.
• Cloud sampling can switch between 1×1, 2×2, and 4×4 with setCloudAmortization(); Low and Medium default to 4×4, while High and Ultra use 2×2.
• Cloud lighting detail now scales with the selected quality tier, reducing cost on Low and Medium while retaining more detail on High and Ultra.
• The source package now includes an interactive Flight example with aircraft controls, a HUD, and sound (see README.md for instructions)
• The Fluffy, Hazy, and Moonlit Night presets have updated cloud shapes, fog, and night lighting.

Bug Fixes

• Fixed distant cloud bottoms showing through when the camera is inside or above the cloud layer.
• Fixed clouds shimmering and fog distances drifting when the camera is far from the world origin or uses a close near plane.
• Reduced jagged edges, flickering thin clouds, smearing, and terrain overlap during fast camera movement.
• Fixed terrain and water z-fighting across the examples' wide camera range.
• Fixed cirrus and storm-haze flicker in cloud reflections on WebGL2.

2.0.0

This is a structural update to support integration with Three.js Water Pro.

The API has been dramatically simplified and the docs have been rewritten and reformatted from the ground up for clarity.

For help with migrating from v1 to v2, see the migration guide.

Note: Sky Pro v2 requires updating to Three.js r185 which contains necessary bug fixes.

Breaking Changes

• SkySystem.create now takes your scene and manages the sky meshes for you — skyMesh, cirrusMesh, nightSkyMesh, and cloudMesh are gone.
• sky.applyTo(sceneColor, scenePass) replaces applyGodRays and the manual depth reconstruction it required; reconstructWorldPosition and screenRayDir are gone.
• The component classes dropped their State suffix:
  • AtmosphereState → Atmosphere
  • SunState → Sun
  • CloudState → Clouds
  • TimeOfDayState → TimeOfDay
  • GodRaysState → GodRays
• Renamed:
  • SkyEquirectBaker → SkyEnvironment
  • SkyProviderAdapter → SkyProvider
  • sky.asSkyProvider() → sky.createSkyProvider()
  • sky.createEnvMap() → sky.createEnvironmentMap(), and its clouds option → includeClouds
  • CloudParams → CloudsParams
• SkyEnvironment, SkyProvider, and NightSkyPanorama can no longer be constructed directly — SkySystem creates them for you (createEnvironmentMap(), createSkyProvider(), and the nightSky option).
• Sky-level shortcuts moved onto the component they control:
  • sky.setTimeOfDay(t) → sky.timeOfDay.time.value = t
  • sky.setSunFromAngles(el, az) → sky.sun.setFromAngles(el, az)
  • the god-ray toggle → sky.godRays.enabled
• sky.cloudQuality is gone — the raymarch budgets follow the quality tier, and the distance-fade controls moved to sky.clouds.fade.
• The internals are no longer exported — the materials, render passes, the cloud-noise generation, and the TSL helpers other than equirectUVFromDir. Everything is reached through SkySystem: cloud noise follows the quality tier, and cloud shadows are applied with sky.cloudShadow().
• Presets:
  • the sun block takes required elevation / azimuth degrees instead of a direction vector
  • the atmosphere block requires fogFarFadeStart / fogFarFadeEnd
  • every params type marks its fields required; applyParams takes a Partial of it
• SkyEnvironment:
  • the diagnostic debug views are gone
  • setResolution replaces texture instead of resizing it in place
  • env maps bake every fifth frame by default (skipFrames: 0 restores per-frame)
• Water Pro integration requires Water Pro v3.2.0 or newer.

New Features

• Clouds now respect scene depth — hidden behind your geometry, with transparent objects drawing over them.
• placeInLayer(mesh, RenderLayer.foreground) places your own meshes in the draw stack by role instead of hand-picked renderOrder numbers. See Scene Integration.
• sky.clouds.enabled = false switches clouds off entirely, including their ground shadows and reflection cost.
• Stars now appear in water and mirror reflections, fading in across twilight like the on-screen sky (envMap.bakeNightSky = false turns it off).
• sky.sun.azimuthDeg and sky.sun.elevationDeg read back the sun's current angles in the same degrees setFromAngles takes.
• sky.toParams() reads the current sky back as a SkyParams — the inverse of applyPreset — so a look tuned at runtime can be saved as a preset. Each component reads back the same way via its own toParams().
• Built-in distance fog: scene geometry fades into the true sky color behind it. Tune with atmosphere.fogDensity; fogFarFadeStart / fogFarFadeEnd fade a finite world's edge fully into the sky.
• Retuned the bundled presets for the new distance fog.

Bug Fixes

• Camera motion applied after sky.update() — such as OrbitControls with damping enabled — no longer makes the clouds jitter; the sky now reads the camera at render time, so update order doesn't matter.
• Cirrus clouds now cover the stars behind them at night, instead of the stars showing through the deck at full brightness.
• Cloud edges no longer swim or checkerboard against the sky while the camera moves.
• Clouds no longer draw on top of terrain and other scene geometry.
• God-ray shafts are no longer drawn through clouds that should block them.
• Sky and cloud backdrops no longer pick up fog from the surrounding scene.

1.0.1

• Updated for compatibility with three.js r185.
• Fixed issue with banding along cloud edges under low-light conditions (sunset / stormy presets)
• Updated presets

1.0.0

• Initial release.