Migrating from v1.0 to v2.0

Use this guide to update a Sky Pro v1 integration to v2.0.

If you use Water Pro, upgrade it to v3.2.0 or newer first.

Sky Pro v2 requires Three.js r185 or newer.

Setup

SkySystem.create now requires scene and adds the sky objects automatically. The skyMesh, cirrusMesh, nightSkyMesh, and cloudMesh properties were removed. dispose() removes the sky objects from the scene.

// v1
const sky = await SkySystem.create({ renderer, camera });
scene.add(sky.skyMesh);
scene.add(sky.cirrusMesh);
if (sky.nightSkyMesh) scene.add(sky.nightSkyMesh);

// v2
const sky = await SkySystem.create({ renderer, camera, scene });

Clouds now draw in the scene and are depth-tested, so they correctly hide behind your geometry. If you composited cloudMesh in your post graph, delete that stage.

Compositing

sky.applyTo(sceneColor, scenePass) replaces applyGodRays. It reads scene depth and applies fog and god rays. The reconstructWorldPosition and screenRayDir helpers were removed.

// v1
const scenePass = pass(scene, camera);
let output = scenePass.getTextureNode("output");

const depth = scenePass.getTextureNode("depth").sample(screenUV).r;
const { viewDir, dist } = reconstructWorldPosition(
  screenUV,
  depth,
  sky.pipeline.sky.inverseViewProjection,
  sky.pipeline.sky.cameraPositionUniform,
);
output = sky.applyGodRays(output, viewDir, dist);

// v2
const scenePass = pass(scene, camera);
let output = scenePass.getTextureNode("output");

output = sky.applyTo(output, scenePass);

See Post-Processing for where to place it relative to exposure and bloom.

Renames

Component classes no longer use the State suffix. SkyEquirectBaker is now SkyEnvironment, and SkyProviderAdapter is now SkyProvider. Component properties such as sky.atmosphere and sky.clouds are unchanged; update imports and type annotations:

v1	v2
AtmosphereState	Atmosphere
SunState	Sun
CloudState	Clouds
TimeOfDayState	TimeOfDay
GodRaysState	GodRays
SkyEquirectBaker	SkyEnvironment
SkyEquirectBakerOptions	SkyEnvironmentOptions
SkyProviderAdapter	SkyProvider
CloudParams	CloudsParams
sky.asSkyProvider()	sky.createSkyProvider()
sky.createEnvMap()	sky.createEnvironmentMap()

SkyEnvironment, SkyProvider, and NightSkyPanorama are now created through SkySystem. Their names remain available as TypeScript types, but direct construction and instanceof are unsupported:

// v1
const provider = new SkyProviderAdapter(sky);
if (env instanceof SkyEquirectBaker) {
  /* ... */
}

// v2
const provider: SkyProvider = sky.createSkyProvider();
const env: SkyEnvironment = sky.createEnvironmentMap();

The clouds option on createEnvironmentMap is now includeClouds:

// v1
sky.createEnvMap({ clouds: false });

// v2
sky.createEnvironmentMap({ includeClouds: false });

Moved Controls

Sky-level shortcut methods moved to their corresponding components:

// v1
sky.setTimeOfDay(0.75);
sky.setSunFromAngles(35, 120);
sky.pipeline.godRays.enabled = false;
sky.cloudQuality.hazeDensityScale.value = 1.5;
sky.cloudQuality.horizonMeltStart.value = 25_000;
sky.cloudQuality.horizonMeltEnd.value = 40_000;

// v2
sky.timeOfDay.time.value = 0.75; // not wrapped into [0, 1)
sky.sun.setFromAngles(35, 120);
sky.godRays.enabled = false;
sky.clouds.fade.hazeDensityScale.value = 1.5;
sky.clouds.fade.horizonMeltStart.value = 25_000;
sky.clouds.fade.horizonMeltEnd.value = 40_000;

The remaining sky.cloudQuality settings were replaced by quality tiers:

// v1
sky.cloudQuality.maxSteps.value = 96;
sky.cloudQuality.baseStepSize.value = 200;

// v2
await sky.setQualityLevel("medium");

New in v2: sky.clouds.enabled = false turns clouds off, including their ground shadows and reflections.

Presets

The sun block now requires elevation and azimuth in degrees instead of a direction vector:

// v1
sky.sun.applyParams({ direction: new THREE.Vector3(0, 0.5, -1) });

// v2
sky.sun.applyParams({ elevation: 35, azimuth: 120 });
// or aim with a vector directly:
sky.sun.direction.value.set(0, 0.5, -1).normalize();

The atmosphere block now requires fogFarFadeStart and fogFarFadeEnd. Set both beyond the scene bounds to disable the visible far fade:

atmosphere: {
  // ...existing fields
  fogFarFadeStart: 80_000,
  fogFarFadeEnd: 100_000,
},

Parameter types now require every field, while applyParams accepts a Partial. Existing partial calls remain valid; update explicit type annotations:

// v1
const tweak: AtmosphereParams = { turbidity: 3 };

// v2
const tweak: Partial<AtmosphereParams> = { turbidity: 3 };

Environment Maps

setResolution now replaces texture with a new one instead of resizing it in place — rebuild any TSL sampler that captured the old reference:

env.setResolution(1024);
skyTexture = texture(env.texture);

Environment maps now bake every fifth frame by default. Pass skipFrames: 0 to bake every frame:

sky.createEnvironmentMap({ skipFrames: 0 });

debugMode, setDebugMode, and SkyEquirectDebugMode were removed. Use bakeAtmosphere and bakeClouds to isolate the atmosphere and cloud layers.

Removed Internals

Internal rendering and noise APIs are no longer exported. Use SkySystem and its components instead:

• Materials and render passes (SkyMaterial, CloudMaterial, SkyPass, CloudPass, GodRaysPass, CloudShadowPass, SkyRenderPipeline, and related classes). The sky.pipeline property remains available for cloud-shadow settings.
• The cloud-noise generation and loading API (cloudNoise, resolveBaseShapeTexture, setBaseNoiseTextures, setWeatherMapResolution, regenerateWeatherMap, the loadCloudNoiseTextures / generateCloudNoiseTextures family, and the noise/weather/shadow texture properties). Cloud noise follows the quality tier; shape the clouds through sky.clouds.
• The TSL helpers other than equirectUVFromDir. For cloud shadows on your own materials, cloudShadowFactor and CloudShadowProjection are replaced by sky.cloudShadow(worldPos).

See Also

• Changelog
• Basic Example
• Tuning Performance