Migrating from v2.1 to v2.2

Sky Pro v2.2 replaces cloudAmortization with cloudRenderingMode. The new option describes the result you want—still clouds, normal cloud movement, or faster response during rapid camera movement—and is selected when you create the sky.

To upgrade:

1. Choose a cloud rendering mode and pass it to SkySystem.create().
2. Remove the old cloud amortization properties and methods.
3. Remove cloudAmortization from custom quality settings.
4. If you define custom weather profiles, remove their precipitation field.

1. Choose a Cloud Rendering Mode

For most animated skies, use the default "dynamic" mode. Choose "ultra-dynamic" if the camera moves quickly, or "static" if the clouds should not move.

What you want	v2.2 mode	Closest v2.1 setting
Still clouds and the lowest background rendering cost	"static"	No direct equivalent
Animated clouds for general use	"dynamic"	cloudAmortization: 4
Animated clouds that respond better to fast camera movement	"ultra-dynamic"	cloudAmortization: 2

cloudAmortization: 1 has no direct replacement. Use "ultra-dynamic" for the fastest response available in v2.2.

The response time in this table refers to how long the renderer takes to replace the entire cloud image with new information. "dynamic" and "static" complete that work over 16 frames, or about 0.27 seconds at 60 FPS. "ultra-dynamic" completes it over 4 frames, or about 0.07 seconds at 60 FPS, but performs four times as much cloud rendering work per frame at the same quality level.

Replace the old setting when creating the sky:

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

// v2.2
const sky = await SkySystem.create({
  renderer,
  camera,
  scene,
  cloudRenderingMode: "ultra-dynamic",
});

Keep the v2.1 Quality-Tier Behavior

In v2.1, the default depended on the quality tier:

• Low and Medium refreshed the cloud image over 16 frames. The v2.2 default, "dynamic", keeps the same response time.
• High and Ultra refreshed it over 4 frames. Select "ultra-dynamic" to keep that response time after upgrading.

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

If you leave a High or Ultra sky on the new "dynamic" default, its clouds use less rendering work but take longer to catch up during fast movement.

What Static Mode Changes

"static" stops wind-driven cloud movement and gradual changes in cloud shape. Moving the camera and changing the sun, atmosphere, cloud appearance, cirrus, or haze still updates the sky. Wind heading and skew still control the direction and lean of the stationary cloud pattern.

2. Remove the Old Cloud Amortization API

The following v2.1 APIs no longer exist:

• SkySystemConfig.cloudAmortization
• sky.cloudAmortization
• sky.setCloudAmortization()
• CloudAmortization

The cloud rendering mode cannot be changed on an existing SkySystem. If your app needs to switch modes while it is running, dispose the current sky and create a new one:

sky.dispose();

sky = await SkySystem.create({
  renderer,
  camera,
  scene,
  cloudRenderingMode: "ultra-dynamic",
});

3. Update Custom Quality Settings

Remove cloudAmortization from custom QualityLevelConfig objects and from overrides passed to setQualityLevel():

// v2.1
await sky.setQualityLevel("medium", {
  cloudAmortization: 2,
  cloudShadowResolution: 512,
});

// v2.2
await sky.setQualityLevel("medium", {
  cloudShadowResolution: 512,
});

Changing the quality level no longer changes the cloud rendering mode. Choose the mode once in SkySystem.create().

4. Update Custom Weather Profiles

If you create your own WeatherMapProfile, remove its precipitation field:

// v2.1
const profile: WeatherMapProfile = {
  mainMass: { frequency: 5, octaves: 6, seed: 0, amplitude: 3 },
  detail: { frequency: 7, octaves: 6, seed: 1, strength: 0.5 },
  coverage: 0.55,
  precipitation: { frequency: 3, octaves: 2, seed: 5 },
};

// v2.2
const profile: WeatherMapProfile = {
  mainMass: { frequency: 5, octaves: 6, seed: 0, amplitude: 3 },
  detail: { frequency: 7, octaves: 6, seed: 1, strength: 0.5 },
  coverage: 0.55,
};

No replacement field is needed.

See Also

• SkySystem
• Tuning Performance
• Changelog