SkySystem
The main entry point for creating and controlling the sky. A SkySystem manages the atmosphere, clouds, sun, day/night cycle, and rendering resources.
Construction
const sky = await SkySystem.create({
// required
renderer,
camera,
scene,
// optional
quality: "high",
cloudRenderingMode: "static",
});Options
renderer required
Type: THREE.WebGPURenderer
Units: -
The renderer the sky draws with. Runs on either the WebGPU or WebGL2 backend.
camera required
Type: THREE.PerspectiveCamera
Units: -
The camera the sky projects from.
scene required
Type: THREE.Scene
Units: -
The scene the sky adds its backdrops to. dispose() removes them again.
quality optional
Type: QualityLevel
Default: "high"
Units: -
Selects the initial quality tier. See Quality Levels and Tuning Performance.
cloudRenderingMode optional
Type: "static" | "dynamic" | "ultra-dynamic"
Default: "dynamic"
Units: -
Controls cloud motion, rendering cost, and responsiveness:
"static"stops cloud motion. It spreads a complete refresh over 16 frames and avoids rerendering unchanged cloud shadows and reflections."dynamic"animates the clouds and spreads a complete refresh over 16 frames. Use it for general-purpose scenes and the lowest animated-cloud cost."ultra-dynamic"animates the clouds and completes a refresh in 4 frames. Use it for fast camera movement; it renders four times as many cloud rays per frame as"dynamic"at the same quality level.
At 60 FPS, 16 frames is about 0.27 seconds and 4 frames is about 0.07 seconds.
The mode is fixed for the lifetime of the SkySystem. Dispose and recreate the sky to select another mode.
godRays optional
Type: boolean
Default: from tier
Units: -
Turns god rays on or off, overriding whatever the quality tier chose. See GodRays.
nightSky optional
Type: NightSkyPanoramaOptions
Default: undefined
Units: -
Adds a star panorama and a textured moon disc. Supply texture as a URL or preloaded THREE.Texture; the library does not include a starmap.
moonTexture replaces the bundled lunar texture, radius sets the panorama radius (default 90_000), and intensity sets star brightness (default 0.3). Without this option, stars are disabled and the moon renders as a flat tinted disc. See Stars for texture requirements and starmap sources.
timeOfDay optional
Type: TimeOfDayParams
Default: undefined
Units: -
Sets the starting time, latitude, and moon state. Omit it and the clock starts at noon. See TimeOfDay.
Properties
Use these components to control the sky at runtime.
atmosphere
Type: Atmosphere
Units: -
Turbidity, exposure, and scattering controls.
clouds
Type: Clouds
Units: -
Cloud shape, lighting, wind, and cirrus.
godRays
Type: GodRays
Units: -
God-ray appearance and enable state.
nightSky
Type: NightSkyPanorama | null
Units: -
Star panorama, or null when nightSky was omitted. intensity.value scales star brightness. setTexture(texture, ownsNewTexture?) replaces the panorama at runtime; pass ownsNewTexture: true to let Sky Pro dispose the texture. See Panorama Format.
qualityLevel
Type: QualityLevel
Units: -
The currently active tier name. Read-only — set it via setQualityLevel().
cloudRenderingMode
Type: "static" | "dynamic" | "ultra-dynamic"
Units: -
The construction-time cloud motion and refresh mode. Read-only; see the cloudRenderingMode construction option.
sun
Type: Sun
Units: -
Sun direction, intensity, color, and disc size.
timeOfDay
Type: TimeOfDay
Units: -
Day/night clock; drives sun and moon position.
Methods
applyPreset(preset)
Applies a visual preset without changing the quality tier or march budgets.
| Param | Type | Required | Description |
|---|---|---|---|
preset | SkyParams | required | Preset object. Use a bundled one from PRESETS or author your own. |
Returns: Promise<void> — await it.
import { PRESETS } from "threejs-sky-pro";
await sky.applyPreset(PRESETS.stunningSunset);See Presets.
applyTo(sceneColor, scenePass)
Applies aerial-perspective fog and god rays to a rendered scene. Add the returned node after scene rendering and before exposure, bloom, and tone mapping. Clouds render directly in the scene and are not part of this post-processing step.
| Param | Type | Required | Description |
|---|---|---|---|
sceneColor | Node<vec4> | required | Input color. It may be the scene output or the result of an earlier post-processing stage. |
scenePass | PassNode | required | Your pass(scene, camera). Supplies the depth both stages composite against. |
Returns: Node<vec4> — the composited color node.
const scenePass = pass(scene, camera);
const output = sky.applyTo(scenePass.getTextureNode("output"), scenePass);See Post-Processing.
createSkyProvider(options?)
Returns a SkyProvider for Three.js Water Pro. Creating another cloud-enabled provider disposes the previous system-owned environment map.
| Param | Type | Required | Description |
|---|---|---|---|
options | { envMap?: boolean | SkyEnvironmentOptions } | optional — default {} | Omit for a clouds-free sky bake. { envMap: true } bakes an env map so reflections pick up clouds, seeded from the active tier. Pass a SkyEnvironmentOptions object instead of true to override tier settings field-by-field. |
Returns: SkyProvider
const provider = sky.createSkyProvider({ envMap: true });cloudShadow(worldPos)
Returns cloud shadowing at a world position. Multiply it into direct sunlight, not ambient lighting.
| Param | Type | Required | Description |
|---|---|---|---|
worldPos | Node<vec3> | required | World-space position, e.g. positionWorld. |
Returns: Node<float> — 0..1, where 1 is full sun and 0 is fully shadowed. Positions outside the shadow-map footprint return 1.
import { positionWorld } from "three/tsl";
const litColor = albedo.mul(sunColor).mul(sky.cloudShadow(positionWorld));See Shadows for DirectionalLight setup and configuration.
createEnvironmentMap(options?)
Builds a SkyEnvironment whose .texture is a 2D equirectangular env map sharing this system's atmosphere, sun, cloud state, and noise textures.
| Param | Type | Required | Description |
|---|---|---|---|
options | SkyEnvironmentOptions | optional — default {} | Bake resolution, cloud budget, origin, and cadence. |
Returns: SkyEnvironment
const env = sky.createEnvironmentMap({ width: 512 });See Environment Maps.
dispose()
Releases all GPU resources and removes the backdrops from the scene.
Takes no parameters.
Returns: void
resize(width, height)
Resizes the internal render targets and drops stale history. Call it from your window resize handler, and after renderer.setPixelRatio() too.
| Param | Type | Required | Description |
|---|---|---|---|
width | number | required | CSS (logical) pixels — same units as renderer.setSize(). The renderer's pixel ratio is applied internally. |
height | number | required | CSS (logical) pixels. |
Returns: void
setCirrusTexture(texture)
Sets or clears the cirrus-deck mask. scale and strength are live uniforms on clouds.cirrus.
This updates the on-screen deck and the current provider-owned environment map. Create the provider first if it also needs the mask. For a standalone environment map, call its setCirrusTexture() method separately.
| Param | Type | Required | Description |
|---|---|---|---|
texture | THREE.Texture | null | required | The mask. Pass null to clear it. |
Returns: void
setQualityLevel(level, overrides?)
Switches the runtime quality tier. The cloud rendering mode and its 4- or 16-frame refresh time do not change.
| Param | Type | Required | Description |
|---|---|---|---|
level | QualityLevel | required | Tier name — see Quality Levels. |
overrides | Partial<QualityLevelConfig> | optional — default {} | Merged over the tier, field-by-field. |
Returns: Promise<void> — safe to ignore.
await sky.setQualityLevel("medium", {
cloudHistoryDiv: 4,
});toParams()
Returns the current visual state as SkyParams, the inverse of applyPreset. The result contains copies of colors and the weather profile, so later changes do not modify it.
The quality tier, cloud rendering mode, march budgets, and env-map bake config are not included. Read runtime quality state from qualityLevel and cloudRenderingMode.
Returns: SkyParams
// Save a look tuned at runtime, then restore it later.
const saved = sky.toParams();
await sky.applyPreset(PRESETS.thunderstorm);
await sky.applyPreset(saved);
// Or persist it.
localStorage.setItem("my-sky", JSON.stringify(saved));See Presets.
update(dt)
Updates clouds, the day/night cycle, and per-frame uniforms. Call it once before each render.
| Param | Type | Required | Description |
|---|---|---|---|
dt | number | required | Seconds since the last frame, e.g. clock.getDelta(). |
Returns: void
Example
import * as THREE from "three/webgpu";
import { pass, vec4 } from "three/tsl";
import { SkySystem } from "threejs-sky-pro";
const sky = await SkySystem.create({ renderer, camera, scene });
sky.timeOfDay.autoAdvanceSecondsPerDay = 0;
sky.sun.setFromAngles(35, 120);
const scenePass = pass(scene, camera);
let output = scenePass.getTextureNode("output");
output = sky.applyTo(output, scenePass);
output = vec4(output.rgb.mul(sky.atmosphere.exposure), output.a);
renderer.toneMapping = THREE.ACESFilmicToneMapping;
const postProcessing = new THREE.RenderPipeline(renderer, output);
function animate() {
sky.update(clock.getDelta());
postProcessing.render();
}