# DynamicSkyEffect

Class · extends [`CameraFrameEffect`](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md) · category: Graphics

Source: https://github.com/playcanvas/engine/blob/64089771243fe28a9b9d2b4de538b99b07c75097/src/extras/effects/dynamic-sky/dynamic-sky-effect.js#L241

The dynamic sky effect: renders the sky of the camera - a day sky of an analytic atmosphere, lit by
the sun, a night sky of stars and the moon, and optionally clouds drifting with the wind - in
place of the sky of the scene. The time of day is set by the position of the sun, see
[DynamicSkyEffect#azimuth](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#azimuth) and [DynamicSkyEffect#elevation](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#elevation), and the effect can
keep a directional light in sync with it, see [DynamicSkyEffect#light](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#light).

The sky has no clouds by default, see [DynamicSkyEffect#cloudType](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#cloudtype). They are a single flat
layer of noise ([CLOUDTYPE_FLAT](https://api.playcanvas.com/engine/variables/CLOUDTYPE_FLAT.md)), or volumetric clouds ray marched through a layer of 3D
noise ([CLOUDTYPE_VOLUMETRIC](https://api.playcanvas.com/engine/variables/CLOUDTYPE_VOLUMETRIC.md)). The volumetric clouds are the expensive part of the sky,
and render to a texture of their own, at a reduced resolution by default, see
[DynamicSkyEffect#cloudResolution](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#cloudresolution). Their noise is generated on the CPU when the clouds are
first used.

The effect also generates the lighting of the scene from its sky: the environment atlas lighting
the materials, assigned to [Scene#envAtlas](https://api.playcanvas.com/engine/classes/Scene.md#envatlas), see [DynamicSkyEffect#lighting](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#lighting). The
cameras without the effect, such as the cameras rendering planar reflections, render the sky of
the scene from that environment atlas - a still image of this sky.

The effect can also haze the scene with the sky, see [DynamicSkyEffect#haze](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#haze): with their
distance, the lit materials fade into the color of the sky behind them, in place of the fog of
the camera.

In XR, the sky and the flat clouds render for each view, like the rest of the scene. The
volumetric clouds render to their texture for the view of the camera alone, so they streak where
the view of an eye extends past it - use [CLOUDTYPE_FLAT](https://api.playcanvas.com/engine/variables/CLOUDTYPE_FLAT.md) clouds in XR.

The shaders of the scene's own materials can evaluate the sky too, for example to fade distant
ground into the color of the sky behind it. The effect sets the uniforms of its sky on the
graphics device every frame, and its shader chunk `dynamicSkyAtmospherePS`, in GLSL and WGSL,
evaluates the sky from them. Include the chunk in a shader, and `dynamicSkyBase(dir, ambient)`
returns the radiance of the sky in a direction, without the sun disc, the stars and the moon, and
sets `ambient` to the light of the sky around it. The direction is in the space of the sky - a
world space direction turned by the rotation of the sky of the scene, `dynSkyRotation`, which the
effect sets with the other uniforms, and with X flipped:

```glsl
#include "dynamicSkyAtmospherePS"
uniform mat3 dynSkyRotation;

vec3 skyColor(vec3 worldDir) {
    vec3 dir = worldDir * dynSkyRotation;
    dir.x = -dir.x;
    vec3 ambient;
    return dynamicSkyBase(dir, ambient);
}
```

The chunk `dynamicSkyHazePS` applies the haze of the sky, see [DynamicSkyEffect#haze](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#haze), in
the shaders that the haze does not reach on its own - `dynamicSkyHaze(color, cameraPos, worldPos)`
returns a linear color seen through it:

```glsl
#include "dynamicSkyHazePS"

vec3 hazed = dynamicSkyHaze(color, view_position, vPositionW);
```

With more than one dynamic sky, a material renders with the sky that was updated last. On the
CPU, [DynamicSkyEffect#getSkyColor](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#getskycolor) evaluates the same sky in a direction.

The sky does not work together with the volumetric fog of the camera frame,
[CameraFrame#volumetricFog](https://api.playcanvas.com/engine/classes/CameraFrame.md#volumetricfog): the clouds cast no shadows into the fog, and the fog is not lit
by the light of the sky.

The effect is not part of a camera frame by default - construct it and add it to the camera
frame of a camera:

```javascript
const sky = new DynamicSkyEffect(app.graphicsDevice);
sky.light = sunEntity.light;
sky.cloudType = CLOUDTYPE_VOLUMETRIC;
cameraFrame.addEffect(sky);
cameraFrame.update();
```

Like all effects, its settings apply on the next [CameraFrame#update](https://api.playcanvas.com/engine/classes/CameraFrame.md#update), which a day and
night cycle moving the sun calls every frame. The clouds drift with the time of the application.

## Constructors

### constructor

```ts
new DynamicSkyEffect(device: GraphicsDevice)
```

**Parameters**

- `device` ([`GraphicsDevice`](https://api.playcanvas.com/engine/classes/GraphicsDevice.md)): The graphics device.

## Properties

### atlasSize

```ts
atlasSize: number = 512
```

The size of the environment atlas the lighting is generated to. Higher values give sharper
reflections on glossy surfaces, and a sharper sky of the scene for the cameras without the
effect, such as the cameras rendering planar reflections. Defaults to 512.

### azimuth

```ts
azimuth: number = 0
```

The azimuth of the sun, in degrees - its compass direction. Defaults to 0.

### cloudBrightness

```ts
cloudBrightness: number = 0.6
```

The brightness of the sunlight falling on the clouds. Defaults to 0.6.

### cloudCoverage

```ts
cloudCoverage: number = 0.45
```

The fraction of the sky covered by clouds, 0-1 range, from a clear sky to overcast. Defaults
to 0.45.

### cloudHeight

```ts
cloudHeight: number = 2000
```

The altitude of the cloud layer, in meters. Defaults to 2000.

### cloudNightBrightness

```ts
cloudNightBrightness: number = 0.05
```

The brightness of the moonlight on the clouds at night. The moonlight of the
[DynamicSkyEffect#light](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#light) is usually much brighter than the moon, to keep the night scene
readable - lit by it, the clouds would glow against the dark night sky. Defaults to 0.05.

### cloudOpacity

```ts
cloudOpacity: number = 1
```

The opacity of the clouds, 0-1 range. Defaults to 1.

### cloudQuality

```ts
cloudQuality: number = 0.5
```

The quality of the volumetric clouds, 0-1 range - the number of their steps through the
cloud layer, from 24 to 64, and toward the light, from 1 to 4, and the fineness of the steps
through a cloud. The cost grows about linearly, doubling from 0.5 to 1. Lower values give
less defined edges of the clouds and a flatter shading. Defaults to 0.5.

### cloudResolution

```ts
cloudResolution: number = 0.5
```

The resolution the volumetric clouds render at, relative to the resolution of the scene,
0.25-1 range. The clouds are soft, so a reduced resolution saves most of their cost with
little loss of detail. The sky blurs them over 3x3 of their texels as it reads them, smoothing
the grain of their steps, so lower values also soften the clouds. Defaults to 0.5.

### cloudSize

```ts
cloudSize: number = 8000
```

The distance in meters over which the cloud pattern repeats. Larger values give larger
clouds. Defaults to 8000.

### cloudSoftness

```ts
cloudSoftness: number = 0.7
```

The softness of the clouds, 0.01-1 range. Lower values give dense clouds with crisp edges
and deep shadows, higher values thin them into translucent, wispy clouds with softer shading.
Defaults to 0.7.

### cloudSunDimming

```ts
cloudSunDimming: number = 0.6
```

The fraction of the sunlight the clouds block at the full coverage, dimming the
[DynamicSkyEffect#light](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#light). Defaults to 0.6.

### cloudThickness

```ts
cloudThickness: number = 2500
```

The thickness of the layer of the volumetric clouds, in meters, above their
[DynamicSkyEffect#cloudHeight](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#cloudheight). Defaults to 2500.

### cloudType

```ts
cloudType: string = CLOUDTYPE_NONE
```

The type of the clouds of the sky, [CLOUDTYPE_NONE](https://api.playcanvas.com/engine/variables/CLOUDTYPE_NONE.md), [CLOUDTYPE_FLAT](https://api.playcanvas.com/engine/variables/CLOUDTYPE_FLAT.md) or
[CLOUDTYPE_VOLUMETRIC](https://api.playcanvas.com/engine/variables/CLOUDTYPE_VOLUMETRIC.md). Defaults to [CLOUDTYPE_NONE](https://api.playcanvas.com/engine/variables/CLOUDTYPE_NONE.md).

### elevation

```ts
elevation: number = 25
```

The elevation of the sun above the horizon, in degrees. Negative values place the sun below
the horizon, which gives the night sky. Defaults to 25.

### haze

```ts
haze: boolean = false
```

Whether the sky hazes the scene the camera renders - the aerial perspective. With their
distance, surfaces fade into the color of the sky behind them: warm toward a low sun, blue
away from it, and the gradient of the night sky after the sunset. The haze is densest at
[DynamicSkyEffect#hazeBaseHeight](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#hazebaseheight) and thins out with the height above it, see
[DynamicSkyEffect#hazeHeight](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#hazeheight), so the valleys stay hazy while the view from high up is
clear.

The haze takes the place of the fog of the camera, [Scene#fog](https://api.playcanvas.com/engine/classes/Scene.md#fog) or
[CameraComponent#fog](https://api.playcanvas.com/engine/classes/CameraComponent.md#fog): while the haze is enabled, the effect gives its camera a fog of
its own, and gives the camera its fog back once the haze is disabled. The lit materials the
camera renders, such as [StandardMaterial](https://api.playcanvas.com/engine/classes/StandardMaterial.md), fade into the sky, while the other shaders,
such as those of the particles and the gaussian splats, render without fog - custom shaders
can apply the haze with the chunk `dynamicSkyHazePS`, see the description of the class. A
material opts out of the haze, rendering without fog, with [StandardMaterial#useFog](https://api.playcanvas.com/engine/classes/StandardMaterial.md#usefog),
or by setting the define `DYNAMIC_SKY_NO_HAZE`:

```javascript
material.setDefine('DYNAMIC_SKY_NO_HAZE', true);
material.update();
```

A material replacing the chunk `fogPS` with its own is not hazed, and finds the define `FOG`
of its shaders set to `DYNAMICSKYHAZE` on the camera. Enabling or disabling the haze compiles
the shaders of the lit materials the camera renders again. Defaults to false.

### hazeBaseHeight

```ts
hazeBaseHeight: number = 0
```

The height the haze is densest at, in world units - usually the lowest ground of the scene,
such as the level of the sea. Below it, the haze grows denser still. Defaults to 0.

### hazeDensity

```ts
hazeDensity: number = 0.0005
```

The density of the haze at its [DynamicSkyEffect#hazeBaseHeight](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#hazebaseheight), per world unit - the
fraction of the light it scatters over a unit of distance. A level view at that height is
hidden by 95% of the haze at about 3 / density. Defaults to 0.0005.

### hazeHeight

```ts
hazeHeight: number = 1000
```

The height over which the density of the haze falls to about a third, in world units. Lower
values keep the haze closer to the ground. Defaults to 1000.

### light

```ts
light: LightComponent | null = null
```

The directional light kept in sync with the sun - its direction, color and intensity. By day
it shines from the sun, at [DynamicSkyEffect#sunIntensity](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#sunintensity), dimmed by the clouds, and
at night it fades to the moonlight, see [DynamicSkyEffect#moonIntensity](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#moonintensity). Defaults to
null.

### lighting

```ts
lighting: boolean = true
```

Whether the effect generates the lighting of the scene from its sky - the environment atlas
lighting the materials, assigned to [Scene#envAtlas](https://api.playcanvas.com/engine/classes/Scene.md#envatlas). Only one effect should do so, the
one of the main camera. The lighting is generated when the effect is first used, and again
when the sun moves by [DynamicSkyEffect#lightingThreshold](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#lightingthreshold), when a setting of the sky
changes by more than a percent, when the clouds drift by [DynamicSkyEffect#lightingCloudThreshold](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#lightingcloudthreshold), and when
[DynamicSkyEffect#bakeLighting](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#bakelighting) is called. The clouds are a still image in the
lighting, and the sun disc is left out of it, as the [DynamicSkyEffect#light](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#light) carries
the light of the sun. Defaults to true.

### lightingCloudThreshold

```ts
lightingCloudThreshold: number = 0
```

The distance the clouds drift by, as a fraction of the [DynamicSkyEffect#cloudSize](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#cloudsize),
before the lighting is generated again, so the clouds in it follow the clouds of the sky. A
value of 0 disables it, and the drift of the clouds does not generate the lighting again.
Defaults to 0.

### lightingInterpolation

```ts
lightingInterpolation: boolean = false
```

Whether the lighting blends from its previous update to its latest one, instead of changing
at once. While the sky changes gradually, such as with an animated time of day, each update
blends in over the time since the previous one, up to a second, so the lighting follows the
sky smoothly, about one update behind it. Without it, the lighting steps at each update,
which shows as flicker in the reflections of a quickly changing sky on glossy surfaces, such
as water. Sudden changes, such as a jump of the time of day, and
[DynamicSkyEffect#bakeLighting](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#bakelighting), still apply at once. It costs two more environment
atlases of memory, and a small pass each frame while the lighting blends, so enable it only
when the sky changes continuously. Defaults to false.

### lightingResolution

```ts
lightingResolution: number = 256
```

The resolution of the sky the lighting is generated from, the size of the faces of a
cubemap, in texels. The sky is filtered down from it to the environment atlas, so it should
be well above the resolution of the atlas: at lower values, the detail of the clouds
aliases, and their reflections flicker on each update of the lighting as the clouds drift.
Defaults to 256.

### lightingThreshold

```ts
lightingThreshold: number = 0.5
```

The angle the sun moves by, in degrees, before the lighting is generated again - keeping the
cost of a day and night cycle down. Defaults to 0.5.

### luminance

```ts
luminance: number = 1
```

The brightness of the sky, relative to the light of the sun. At 1, the sky lights the scene
with about a tenth of the light of the sun, as a clear sky does, at any elevation of the
sun: the blue sky and the ground lit by the sun are then of a similar brightness, so a single
exposure suits both. Lower values give a deeper sky, higher values a brighter one, and a
brighter ambient light of the scene. Defaults to 1.

### mieCoefficient

```ts
mieCoefficient: number = 0.005
```

The amount of the Mie (aerosol) scattering, 0-0.1 range, setting the brightness of the glow
around the sun. Defaults to 0.005.

### mieDirectionalG

```ts
mieDirectionalG: number = 0.8
```

The directional anisotropy of the Mie scattering, 0-1 range, setting how tightly the glow
hugs the sun. Defaults to 0.8.

### moonColor

```ts
moonColor: Color
```

The color of the moonlight, and of the moon disc. Defaults to a pale blue.

### moonDirection

```ts
moonDirection: Vec3
```

The direction toward the moon, in the world space, turned by the
[DynamicSkyEffect#rotation](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#rotation) of the sky. It does not need to be normalized. Defaults to
a direction high in the sky.

### moonGlow

```ts
moonGlow: number = 3
```

The brightness of the moon disc in the night sky. Defaults to 3.

### moonIntensity

```ts
moonIntensity: number = 1
```

The intensity of the [DynamicSkyEffect#light](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#light) at night - the moonlight, a dim cool light
from the direction of the moon. Defaults to 1.

### moonSize

```ts
moonSize: number = 0.6
```

The angular radius of the moon disc, in degrees. Defaults to 0.6.

### nightBrightness

```ts
nightBrightness: number = 0.052
```

The brightness of the night sky. Defaults to 0.052.

### nightColor

```ts
nightColor: Color
```

The color of the night sky. Defaults to a deep blue.

### rayleigh

```ts
rayleigh: number = 1.5
```

The amount of the Rayleigh scattering, 0-4 range, setting the blueness of the sky. Defaults
to 1.5.

### rotation

```ts
rotation: number = 0
```

The rotation of the whole sky around the vertical axis, in degrees. It is added to the
azimuth of the sun, so the sky, the sun and the moon turn together, along with the light and
the shadows it casts. Defaults to 0.

### starBrightness

```ts
starBrightness: number = 0.05
```

The brightness of the stars. A value of 0 disables them. Defaults to 0.05.

### starDensity

```ts
starDensity: number = 0.8
```

The density of the stars, 0-1 range - the fraction of the cells of the sky holding a star.
Defaults to 0.8.

### starSize

```ts
starSize: number = 0.5
```

The scale of the size of the stars. Defaults to 0.5.

### sunIntensity

```ts
sunIntensity: number = 2
```

The intensity of the light of the sun: of the [DynamicSkyEffect#light](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#light) with the sun
above the horizon, and of the sunlit clouds. The sky scales with it too, see
[DynamicSkyEffect#luminance](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#luminance), so it sets the brightness of the whole day, to match the
exposure of the camera. Defaults to 2, a sunny day at an exposure of 1.

### turbidity

```ts
turbidity: number = 2
```

The haziness of the atmosphere, 1-20 range. Higher values give a milkier sky and a larger
glow around the sun. Defaults to 2.

### twilightGlow

```ts
twilightGlow: number = 0.52
```

The strength of the warm glow at the horizon while the sun is just below it. Defaults to
0.52.

### windDirection

```ts
windDirection: number = 45
```

The direction the clouds drift toward, in degrees around the vertical axis. Defaults to 45.

### windSpeed

```ts
windSpeed: number = 10
```

The speed the clouds drift with, in meters per second. Defaults to 10.

## Methods

### bakeLighting

```ts
bakeLighting(): void
```

Requests the lighting of the scene to be generated from the sky again, before the next frame
renders. Use it when the lighting should follow a change it does not regenerate for on its
own, such as the drift of the clouds with [DynamicSkyEffect#lightingCloudThreshold](https://api.playcanvas.com/engine/classes/DynamicSkyEffect.md#lightingcloudthreshold)
disabled.

### destroy

```ts
destroy(): void
```

Destroys the effect, removing it from its camera frame if it is still registered and
releasing everything it owns, the passes it created included. Subclasses which create
resources in their constructor release them in an override, calling `super.destroy()`. The
removal takes effect for the frames rendered after the next [CameraFrame#update](https://api.playcanvas.com/engine/classes/CameraFrame.md#update), which
is due before the next frame renders.

### frameUpdate

```ts
frameUpdate(frame: CameraFrameEffectContext): void
```

**Parameters**

- `frame` ([`CameraFrameEffectContext`](https://api.playcanvas.com/engine/interfaces/CameraFrameEffectContext.md)): The values of this frame.

### getSkyColor

```ts
getSkyColor(direction: Vec3, color?: Color): Color
```

Gets the color of the sky in a direction - its linear radiance, without the sun disc, the
stars and the moon, as `dynamicSkyBase` of the shader chunk `dynamicSkyAtmospherePS`
evaluates it. Use it for lighting worked out on the CPU, such as the light the sky gives to
particles. It evaluates the sky as of the last [CameraFrame#update](https://api.playcanvas.com/engine/classes/CameraFrame.md#update).

**Parameters**

- `direction` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): The direction, in the world space. It does not need to be
  normalized.
- `color` ([`Color`](https://api.playcanvas.com/engine/classes/Color.md), optional): The color to receive the result. A new one is created if not given.

**Returns** [`Color`](https://api.playcanvas.com/engine/classes/Color.md): The color of the sky.

**Example**

```ts
// the light of the sky from straight above
const zenith = sky.getSkyColor(Vec3.UP);
```

### update

```ts
update(): void
```

Applies the effect's parameters. Called by [CameraFrame#update](https://api.playcanvas.com/engine/classes/CameraFrame.md#update) while the effect is
active: set the uniform values with [CameraFrameEffect#setUniform](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md#setuniform) here, and the
defines which depend on the parameters.
Everything it sets is what the frames rendered until the next update use.

## Inherited from [CameraFrameEffect](https://api.playcanvas.com/engine/classes/CameraFrameEffect.md)

- `cameraFrame: CameraFrame | null = null`
- `device: GraphicsDevice`
- `enabled: boolean = true`
- `get active(): boolean`
- `get cameraExposureScale(): number`
- `get chunkName(): string`
- `get debugViews(): string[]`
- `get defineName(): string`
- `get entryPoint(): string`
- `get glsl(): string | null`
- `get id(): string`
- `get requires(): string[]`
- `get slot(): string | null`
- `get wgsl(): string | null`
- `getChunk(shaderLanguage: string): string | null`
- `resolveScene(scene: CameraFrameEffectScene): void`
- `setDefine(name: string, value: any): void`
- `setUniform(name: string, value: number | number[] | ArrayBufferView<ArrayBufferLike> | Texture): void`
