SkyEnvironment
A continuously updated equirectangular panorama of the sky and clouds. Use it for reflections on water, mirrors, and glossy materials.
For Water Pro, use sky.createSkyProvider({ envMap: true }), which manages the environment map automatically. See Water Pro Integration.
Construction
const env = sky.createEnvironmentMap({ width: 512, height: 256 });Create a SkyEnvironment with sky.createEnvironmentMap(). It shares the parent SkySystem atmosphere, sun, and cloud state, so reflections follow runtime changes.
Properties
bakeAtmosphere
Type: boolean
Default: true
Units: -
Includes the atmospheric sky and the sun and moon discs in the environment map. Disable it when isolating other layers.
bakeClouds
Type: boolean
Default: true
Units: -
Includes volumetric clouds and the cirrus/haze deck. Cirrus requires a mask supplied through setCirrusTexture. This property can disable clouds at runtime only when the environment map was created with includeClouds: true.
bakeNightSky
Type: boolean
Default: true
Units: -
Draws the night-sky stars into the bake. Only has an effect when the parent SkySystem was created with a nightSky; the stars fade in across twilight, matching the on-screen sky.
bakeQuality
Type: object
Default: -
Units: -
Cloud rendering settings for the environment map. These are separate from the on-screen cloud settings. Configure them with cloudMarchSteps and cloudMipBase when creating the environment map.
bakeVersion
Type: number
Default: 1 after the constructor's initial bake, or 0 with initialBake: false
Units: -
Increments after each rendered environment frame. Moving cirrus/haze can produce frames between scheduled volumetric-cloud bakes.
enabled
Type: boolean
Default: true
Units: -
Enables scheduled baking. When false, update() leaves the existing texture unchanged. bakeAll() ignores this property.
height
Type: number
Default: -
Units: pixels
The texture's current height. Change it with setResolution.
origin
Type: Readonly<THREE.Vector3>
Default: -
Units: meters
The point the bake is currently captured from. Read-only — move it with setOrigin.
skipFrames
Type: number
Default: 4
Units: frames
How many update() calls pass between expensive volumetric-cloud raymarches. Clamped to 0–8. Animated cirrus/haze remains current between those raymarches.
texture
Type: THREE.Texture
Default: -
Units: -
The baked panorama texture. setResolution replaces this object, so rebuild samplers that reference the previous texture.
width
Type: number
Default: -
Units: pixels
The texture's current width. Change it with setResolution.
Methods
bakeAll()
Immediately bakes the environment map, ignoring skipFrames and enabled. Use it after a preset change or a large change in sun position.
Takes no parameters.
Returns: void
clearTexture()
Clears the env map to opaque black. Use it after disabling per-frame baking so consumers stop sampling the last bake.
Takes no parameters.
Returns: void
dispose()
Releases the render target and the internal sky, night-sky, and cloud materials.
Takes no parameters.
Returns: void
setCirrusTexture(texture)
Sets or clears the cirrus-deck mask used by the environment map's thin-cloud pass.
| Param | Type | Required | Description |
|---|---|---|---|
texture | THREE.Texture | null | required | The mask. Pass null to clear it. |
Returns: void — no-op on an env map built with includeClouds: false.
setOrigin(v)
Moves the point the next bake is captured from.
| Param | Type | Required | Description |
|---|---|---|---|
v | THREE.Vector3 | required | World-space capture point. Copied, not retained — mutating your vector afterward has no effect. |
Returns: void
setResolution(width, height?)
Resizes the env map. texture is replaced — rebuild any TSL sampler reading the old one before the next render.
| Param | Type | Required | Description |
|---|---|---|---|
width | number | required | New bake width in pixels. |
height | number | optional — default width / 2 | New bake height in pixels. Leave it out for the standard 2:1 equirect. |
Returns: void — clears the texture to black; the next bake refills it.
env.setResolution(512);update()
Updates the environment map. Volumetric clouds follow the skipFrames cadence; animated cirrus/haze is recomposited whenever its wind offset or capture origin moves. Does nothing while enabled is false.
Takes no parameters.
Returns: void
Sampling
The texture uses an equirectangular projection: longitude maps to U and latitude maps to V. The U seam uses THREE.RepeatWrapping. Assign it to scene.environment, sample it with pmremTexture, or sample the raw texture:
import { pmremTexture } from "three/tsl";
const skyReflection = pmremTexture(envMap.texture, reflectDir, roughness);import { equirectUVFromDir } from "threejs-sky-pro";
import { texture } from "three/tsl";
const skyReflection = texture(envMap.texture, equirectUVFromDir(reflectDir));equirectUVFromDir matches three.js's TSL equirectUV() convention: +X at u = 0.5, +Z at u = 0.75, zenith at v = 1, nadir at v = 0. dir need not be unit length.
Example
const env = sky.createEnvironmentMap({ width: 512 });
function animate() {
sky.update(dt);
env.update();
postProcessing.render();
}