Clouds

Controls cloud geometry, lighting, wind, cirrus, haze, and distance fading.

Controls are split into six sub-objects: shape, lighting, wind, cirrus, haze, and fade.

Properties

enabled

Type: boolean
Default: true
Units: -

Enables or disables the complete cloud system. See Turning Clouds Off.

Not a uniform; assign it directly.

Cirrus

A thin high deck, sampled from a texture as a flat layer above the volumetric clouds. Set the texture with sky.setCirrusTexture(tex | null).

cirrus.scale.value

Type: uniform<float>
Default: 30000
Units: meters

Sets how many meters of world the cirrus texture spans before it repeats. Larger values stretch the streaks out.

---

cirrus.strength.value

Type: uniform<float>
Default: 0.0
Units: -

Sets how opaque the cirrus deck reads. 0 hides it.

Fade

Controls how clouds lose contrast and blend into the sky with distance. hazeDensityScale affects near and mid-distance clouds. horizonMeltStart and horizonMeltEnd define the final transition into the horizon.

fade.hazeDensityScale.value

Type: uniform<float>
Default: 1.0
Units: -

Scales how much atmosphere sits between the camera and the clouds, which is what makes distant clouds lose contrast. 1 matches the real atmosphere, higher values thicken the haze, and 0 removes it.

---

fade.horizonMeltEnd.value

Type: uniform<float>
Default: 40000
Units: meters

Sets the distance at which clouds have fully blended into the sky. applyParams keeps this value at or above horizonMeltStart. Raising it also extends the raymarch and increases cost.

---

fade.horizonMeltStart.value

Type: uniform<float>
Default: 25000
Units: meters

Sets the distance at which clouds begin blending into the sky. If this exceeds horizonMeltEnd, applyParams raises the end value to match. Raise both values to move the transition farther away.

---

fade.maxMarchDist

Type: derived node
Default: 42000
Units: meters

Maximum view-ray distance. This read-only value is always horizonMeltEnd + 2000. Raise horizonMeltEnd to extend it.

Haze

A high haze layer that shares the cirrus altitude and motion. Cloud coverage controls its density, so it thickens above dense cumulus regions. It combines with cirrus and can become opaque enough to hide the sun.

haze.density.value

Type: uniform<float>
Default: 0.0
Units: -

Sets how opaque the haze reads for a given amount of cloud coverage. 0 hides it; high values saturate to fully opaque.

---

haze.scale.value

Type: uniform<float>
Default: 40000
Units: meters

Sets how many meters of world the haze layer spans before it repeats. Independent of shape.weatherScale, even though both read the same coverage.

Lighting

How light moves through the clouds.

lighting.ambientIntensity.value

Type: uniform<float>
Default: 0.6
Units: -

Scales skylight in shadowed parts of a cloud. Higher values brighten shadows; lower values increase contrast between lit and unlit regions.

---

lighting.baseShadowHeight.value

Type: uniform<float>
Default: 0.6
Units: shell height fraction

Sets how far up the cloud the base darkening reaches before light returns to full. Larger values spread the shading over more of the cloud, so it reads softer.

---

lighting.baseShadowStrength.value

Type: uniform<float>
Default: 0.0
Units: -

Darkens cloud bottoms. 0 leaves them lit; 1 shades them all the way down to the floor of the shell.

---

lighting.groundBounceAlbedo.value

Type: uniform<Color>
Default: Color(0.18, 0.17, 0.15)
Units: linear RGB

Sets the ground color used for light reflected onto cloud undersides. Use green for vegetation, tan for soil or sand, bright values for snow, and near-black for water.

Separate from atmosphere.groundAlbedo, which does the same job for the sky dome.

---

lighting.moonGain.value

Type: uniform<float>
Default: 1.0
Units: -

Scales the moonlight falling on cloud edges at night. Does nothing without a TimeOfDay.

---

lighting.powderStrength.value

Type: uniform<float>
Default: 1.0
Units: -

Darkens thin outer edges on sunlit clouds to improve depth and definition. Lower it if the edges appear muddy.

---

lighting.scatteringAlbedo.value

Type: uniform<float>
Default: 0.9
Units: -

Sets how much light survives each scattering event inside a cloud. 1 preserves all light; lower values produce darker, grayer clouds.

Shape

The geometry and silhouette of the cloud shell.

shape.altitude.value

Type: uniform<float>
Default: 1400
Units: meters

Sets the height of the cloud bases above the ground.

---

shape.baseScale.value

Type: uniform<float>
Default: 8000
Units: meters

Sets how many meters of world the cloud-shape noise spans before it repeats. Larger values make individual clouds bigger.

---

shape.baseStrength.value

Type: uniform<float>
Default: 1.0
Units: -

Scales the cloud-shape noise as a whole. 1 leaves it untouched; raising it swells the tops without moving the bases.

---

shape.baseWeatherHeightEnd.value

Type: uniform<float>
Default: 0.1
Units: shell height fraction

Sets the height above which baseWeatherStrength stops carving. Above this, cloud grows normally.

---

shape.baseWeatherHeightStart.value

Type: uniform<float>
Default: 0.05
Units: shell height fraction

Sets the height where baseWeatherStrength carves hardest. Nearer 0 bites at the very bottom of the shell.

---

shape.baseWeatherStrength.value

Type: uniform<float>
Default: 0.0
Units: -

Erodes the bottoms of thin clouds while preserving thicker regions. This prevents patchy clouds from forming a flat layer at the base. 0 disables the effect.

---

shape.coverage.value

Type: uniform<float>
Default: 1.0
Units: -

Sets cloud coverage. 0 clears the field; 1 uses the full coverage map. Typical range: 0–1.

Animate this value to clear or build cloud coverage over time. A value of 0 empties the field but does not disable rendering. See Turning Clouds Off to remove the rendering cost.

---

shape.density.value

Type: uniform<float>
Default: 0.048
Units: 1/m

Sets how much light a meter of cloud blocks. Higher values read as thicker, more opaque cloud.

---

shape.edgeSoftness.value

Type: uniform<float>
Default: 0.05
Units: shell height fraction

Sets how gradually cloud density appears at the base of the shell. Larger values produce a softer lower edge.

---

shape.edgeSoftnessFalloff.value

Type: uniform<float>
Default: 1.0
Units: 1/km

Tightens edgeSoftness as height climbs, so bases stay soft while tops stay crisp. 1 holds the same softness at every height.

---

shape.erosionScaleBaseMultiplier.value

Type: uniform<float>
Default: 0.5
Units: -

Sets erosion-detail size relative to baseScale. Lower values produce finer detail. Typical range: 0–1.

---

shape.erosionShape.value

Type: uniform<float>
Default: 0.0
Units: -

Controls erosion shape. 0 produces rounded, billowing edges; 1 produces torn, wispy edges. Typical range: 0–1.

---

shape.erosionStrengthBase.value

Type: uniform<float>
Default: 1.0
Units: -

Sets erosion strength at the bottom of the cloud. Typical range: 0–5.

---

shape.erosionStrengthPeak.value

Type: uniform<float>
Default: 1.0
Units: -

Sets erosion strength at the top of the cloud. Use it with erosionStrengthBase to control the top and bottom independently. Typical range: 0–5.

---

shape.horizonCoverageAmount.value

Type: uniform<float>
Default: 0.0
Units: -

Adds coverage with distance, creating a denser cloud bank near the horizon without changing overhead coverage. 0 disables the effect. Values may exceed 1.

---

shape.horizonCoverageRamp.value

Type: uniform<float>
Default: 20000
Units: meters

Sets the distance over which the horizon bank builds from normal coverage to the full horizonCoverageAmount boost.

---

shape.horizonCoverageStart.value

Type: uniform<float>
Default: 10000
Units: meters

Sets how far from the camera the horizon bank starts building.

---

shape.thickness.value

Type: uniform<float>
Default: 2800
Units: meters

Sets how tall the cloud shell is, measured up from altitude.

---

shape.weatherScale.value

Type: uniform<float>
Default: 40000
Units: meters

Sets how many meters of world the coverage map spans before it repeats. Larger values push the repeat past the horizon, where it stops reading as tiling.

Wind

Controls cloud movement and shape evolution. SkySystem.update(dt) advances both each frame and updates the read-only direction, offset, and evolutionOffset uniforms.

Movement and evolution are independent. Set only evolutionSpeed to change cloud shapes in place, or set only speed to move clouds without changing their shape.

In Static cloud rendering mode, speed and evolutionSpeed are paused. heading and skew still control the fixed cloud field's lean.

wind.evolutionSpeed

Type: number
Default: 0
Units: m/s

Sets how quickly cloud shapes evolve. Higher values produce faster changes; 0 preserves the current shape.

Not a uniform; assign it directly.

---

wind.heading

Type: number
Default: 0
Units: degrees

Sets the direction clouds travel toward. 0 is +Z, 90 is +X.

Not a uniform; assign it directly.

---

wind.skew.value

Type: uniform<float>
Default: 0
Units: meters

Offsets cloud tops downwind from their bases to simulate vertical wind shear.

---

wind.speed

Type: number
Default: 0
Units: m/s

Sets how fast clouds drift across the sky. 0 holds them still.

Not a uniform; assign it directly.

Methods

applyParams(params)

Writes any subset of PartialCloudsParams in one call. Omit a group to leave it untouched.

Returns: void

sky.clouds.applyParams({
  shape:    { coverage: 0.7, density: 0.08 },
  lighting: { ambientIntensity: 0.3 },
  wind:     { heading: 90, speed: 12, evolutionSpeed: 3 },
  cirrus:   { strength: 0.4 },
  haze:     { density: 2.5 },
});

toParams()

Returns a new CloudsParams containing all six groups. Pass it to applyParams to restore the state, or store it in a preset's cloud block. Each group also provides its own toParams() method.

Returns: CloudsParams

const saved = sky.clouds.toParams();
sky.clouds.applyParams({ shape: { coverage: 1 } });
sky.clouds.applyParams(saved); // back to where it was

Types

CloudsParams

The six groups, every one required — what toParams() returns and the shape of a preset's cloud block. Each group's keys are the property names on that group, minus the .value.

enabled is not a field on any of these types. It is the one cloud setting applyParams never writes and toParams never reads; assign it directly.

interface CloudsParams {
  // shell geometry and silhouette — see Shape
  shape: CloudShapeParams;
  // scattering, powder, ambient, moon gain — see Lighting
  lighting: CloudLightingParams;
  // drift heading, speed, evolution, skew — see Wind
  wind: CloudWindParams;
  // high thin deck — see Cirrus
  cirrus: CloudCirrusParams;
  // storm haze deck — see Haze
  haze: CloudHazeParams;
  // aerial perspective and horizon melt — see Fade
  fade: CloudFadeParams;
}

PartialCloudsParams

What applyParams accepts: every group optional, and every field within a group optional. { shape: { coverage: 0.7 } } writes coverage and leaves the rest of shape alone.

type PartialCloudsParams = {
  [K in keyof CloudsParams]?: Partial<CloudsParams[K]>;
};

Each group's own applyParams takes the flat Partial of that group — clouds.shape.applyParams(params: Partial<CloudShapeParams>).

Every type here is importable by name:

import type {
  CloudsParams,
  PartialCloudsParams,
  CloudShapeParams,
} from 'threejs-sky-pro';

Turning Clouds Off

enabled controls the raymarch, cloud shadows, and clouds in environment maps:

sky.clouds.enabled = false;

Disabling clouds removes them from view and stops their rendering work. Use it for a clear sky or when clouds cannot be visible, such as indoors or underwater. Water Pro disables them automatically while the camera is submerged.

Re-enabling clouds takes 16 frames to rebuild a complete set of fresh samples in Static or Dynamic mode, and 4 frames in Ultra Dynamic mode. During that interval, the clouds fade in instead of appearing immediately.

applyParams and presets never touch enabled.

Setting shape.coverage to 0 clears the cloud field but keeps the rendering passes active. Use coverage for animated weather changes and enabled when the cloud system should stop rendering.

See Also

• Tuning Performance — the quality tiers, and what cloud cost scales with
• Shadows — the ground shadows clouds cast