Reference

API reference

Everything exported from src/index.js and build/index.js. The types are in build/*.d.ts.

import {
  SkySystem, SkyPostPass, QUALITY_LEVELS, PRESETS, getPresetParams, DEFAULT_PARAMS,
  CLOUD_FORMS, CLOUD_SHADOW_GLSL, patchMaterialWithCloudShadow,
  phaseName, dayPhase, formatClock, lunarAgeNow, SYNODIC,
} from 'naturegl-sky';

#SkySystem

#SkySystem.create(options): Promise<SkySystem>static async

Builds the system, adds the backdrop mesh to options.scene, runs the first LUT, shadow, env and PMREM bakes, and pre-compiles the backdrop. new SkySystem(options) also works; in that case call update(0) before the first render.

Option	Type	Default
`renderer`	`THREE.WebGLRenderer`	—	Required
`scene`	`THREE.Scene`	—	Required; the backdrop mesh is added here
`camera`	`THREE.PerspectiveCamera`	—	Required; the main camera clouds are reconstructed for
`quality`	`'low'`, `'medium'`, `'high'`, `'ultra'`	`'high'`	See Quality levels
`qualityOverrides`	`Partial<QualitySettings>`	`{}`	Merged over the tier
`cloudRenderingMode`	`'static'`, `'dynamic'`	`'dynamic'`	`static` freezes evolution and re-bakes only on change
`preset`	`string` or `Partial<SkyParams>`	`'marine'`	Initial sky
`metersPerUnit`	`number`	`1`	World units → metres
`lightScale`	`number`	`0.5`	Sky radiance → three.js light units (noon sun ≈ 4)
`autoExposure`	`boolean`	`true`	Writes `renderer.toneMappingExposure` every update
`maxExposure`	`number`	`Infinity`	1.1 Ceiling for the auto exposure
`nightExposure`	`number`	—	1.1 Ceiling at full night, blended through dusk
`setSceneEnvironment`	`boolean`	`false`	Keep `scene.environment` on `environment`
`shadowExtent`	`number`	`8000`	Cloud shadow map half-width in metres

The renderer should use a tone mapping, since the sky writes linear HDR.

#Frame

#sky.update(dt, opts?): voidmethod

Call once per frame after moving the camera and before rendering. It advances the clock and the eased weather, and updates the sun, moon, ambient, fog and exposure. Then it does the offscreen work: sky-view LUT, cloud shadow map, env slices and PMREM when due, and the cloud march with its temporal resolve. dt is in seconds, clamped to 0.1. opts.forceBakes re-bakes everything now.

#sky.resize(width?, height?): voidmethod

Re-reads the renderer's drawing-buffer size and reallocates the cloud buffers and the post pass. Call it after renderer.setSize. The renderer size is authoritative, and update() also detects size changes on its own.

#sky.setCamera(camera): voidmethod

Switches the main camera. The temporal history is reset.

#sky.dispose(): voidmethod

Removes the backdrop, frees every render target and material, clears scene.environment if the sky set it, and disposes a post pass created by createPostPass.

#Parameters and presets

#sky.loadPreset(preset): voidmethod

Snaps to a preset name or params object. Missing fields take the defaults. There's no easing, the temporal history is reset, and everything re-bakes.

#sky.applyPreset(preset): voidmethod

Transitions to a preset: the targets change and numeric params ease over about 1–2 s.

#sky.setParams(partial, { immediate? }): voidmethod

Merges into the targets. Numeric params ease unless immediate is set.

#sky.getParams(): SkyParamsmethod

Returns a complete, JSON-safe copy of the targets, with numbers rounded to 3 decimals and no view. You can use it as a preset.

#sky.setTime(hours, { immediate? }): voidmethod

Sets the clock (0–24). It eases the short way round unless immediate is set.

#sky.setSunAngles(elevationDeg, azimuthDeg, { immediate? }): voidmethod

Picks the afternoon time at which the sun has this elevation, and sets northOffset so the sun sits at this world azimuth. sky.sun.setFromAngles(...) does the same.

Property
`params: SkyParams`	The targets
`current: SkyParams`	The eased values actually rendered
`presetName: string \| null`	Last loaded preset (`null` once edited)
`clock: { running, speed }`	When running, `timeOfDay` advances `speed` hours per second (default 24/144)

#Quality and modes

#sky.setQualityLevel(level, overrides?): voidmethod

Switches tier at runtime. Targets are reallocated, history is reset and env/PMREM re-bake. If the PMREM or env texture object changes, scene.environment, scene.background and material envMaps that pointed at the old one are updated, and environmentchange fires. Read back quality (the level name) and qualitySettings (the effective settings).

#sky.setCloudRenderingMode(mode): voidmethod

'static' or 'dynamic'. See Static and dynamic rendering.

Property
`taa: boolean`	Temporal reconstruction on/off (default on). Off gives a plain bilinear upscale of the noisy march; use it for debugging only

#Outputs

Property	Type
`sun.direction`	`Vector3`	Unit vector toward the sun (world)
`sun.color`, `sun.intensity`	`Color`, `number`	Direct sunlight at the camera (0 below the horizon)
`sun.elevation`, `sun.azimuth`	`number`	Degrees; azimuth 0 = −Z, 90 = +X
`sun.visibility`	`number`	0–1 cloud shadow at the camera (async GPU probe, ~4 Hz)
`moon.direction / color / intensity`		The same for the moon
`moon.phase`, `moon.illumination`, `moon.phaseName`	`number`, `number`, `string`	Synodic fraction, lit fraction, e.g. `'WAX GIB'`
`keyLight.direction / color / intensity`		Sun by day, moon once the sun is 6° down
`ambient.skyColor / groundColor / intensity`		For a `HemisphereLight`
`ambient.color`	`Color`	Up-facing irradiance, magnitude included
`envMap`	`Texture`	Equirect HDR sky + clouds (no sun disc)
`environment`	`Texture \| null`	PMREM of `envMap` (listen to `environmentchange`)
`cloudShadow.texture`	`Texture`	Top-down transmittance toward the key light (r)
`cloudShadow.matrix`	`Matrix4`	World position → shadow uv (includes the light shear)
`cloudShadow.strength`	`number`	0–1 scale for patched materials
`cloudShadow.uniforms`	`object`	`skyCloudShadowMap / Matrix / Strength` uniforms to share
`fogColor`, `fogSigma`	`Color`, `number`	Linear horizon colour; sea-level extinction (1/m)
`exposure`	`number`	Display exposure after the ceilings
`meteredExposure`	`number`	1.1 Raw metered exposure
`displayExposure`	`number`	1.1 Exposure in `toneMappingExposure` units
`night`	`number`	1.1 0 by day … 1 at full night
`maxExposure`, `nightExposure`	`number`, `number \| null`	1.1 The ceilings, mutable
`lightning`	`number`	Current flash, 0 – 1.5
`timeOfDay`, `dayPhase`	`number`, `string`	Current eased hour and its name
`cloudLayer`	`{ base, top }`	Deck altitude in metres
`uniforms`	`Record<string, IUniform>`	Shared sky uniform block (advanced)
`backdrop.mesh`	`Mesh`	The sky mesh in your scene
`clouds.texture / depthTexture`	`Texture`	Resolved screen-space cloud buffer

#Composition helpers

#sky.bindLights(directional, hemisphere?, opts?): voidmethod

Drives the lights from the sky on every update. opts: distance (default 100), cloudDimming (multiply by sun.visibility), intensityScale (default 1). See Lighting.

#sky.patchMaterial(material): Materialmethod

Adds cloud shadowing to a built-in lit material (Standard, Physical, Lambert, Phong, Toon). It supports instancing and batching, chains onBeforeCompile, and is idempotent.

#sky.createPostPass(options?): SkyPostPassmethod

See SkyPostPass.

#Events

SkySystem is a THREE.EventDispatcher.

Event	Payload	When
`change`	—	A preset was loaded or params were set
`quality`	`{ level }`	The tier changed
`environmentchange`	—	`environment` or `envMap` is a new texture object

#Debug switches

Property
`debugRotationOnlyTAA`	Reproject history as if the camera only rotated (the cloudpro method), for comparisons
`debugLegacy`	Render the cloud and sky details the way cloudpro.html did, for before/after comparisons

#SkyPostPass

const post = sky.createPostPass({ fog: true, godRays: true, bloom: true, cloudsOverGeometry: true, grade: 1 });

#post.render(scene, camera, target?): voidmethod

Renders the scene into the HDR target with depth, runs bloom and shafts, composites fog, god rays, clouds over geometry and the grade, and tone-maps into target (the screen by default).

#post.composite(colorTexture, depthTexture, camera, target?): voidmethodsince 1.1

Runs the same chain on an HDR render you already have. The colour must be linear and not tone-mapped; the depth is the matching DepthTexture. See Composite.

#post.setSize(w, h): voidmethod

Drawing-buffer size. render calls it automatically.

Member
`options`	`{ fog, godRays, bloom, cloudsOverGeometry, grade, msaa }`, mutable at runtime
`dispose()`	Frees the targets

#Other exports

Export
`PRESETS`	`Record<string, Partial<SkyParams> & { label }>`
`getPresetParams(name)`	Complete, deep-cloned params
`DEFAULT_PARAMS`	The defaults every preset fills from
`CLOUD_FORMS`	The six forms, in shader order
`QUALITY_LEVELS`	See Quality levels
`patchMaterialWithCloudShadow(material, uniforms)`	The function behind `sky.patchMaterial`
`CLOUD_SHADOW_GLSL`	`skyCloudShadow(worldPos)` for your own shaders
`phaseName(age)`, `dayPhase(hour, elevRad)`, `formatClock(hours)`, `lunarAgeNow()`, `SYNODIC`	Astronomy helpers

#Units and conventions

Space: world units × metersPerUnit = metres. Y is up and sea level is y = 0. Azimuth 0 = −Z, 90° = +X.
Light: internal sky radiance uses a sun illuminance of 10. lightScale converts to three.js units for the backdrop, env map, lights, ambient and fog. A white Lambertian surface under the noon sun reads about 4 / π before exposure.
Exposure: with autoExposure, the sky sets renderer.toneMappingExposure = exposure / lightScale. Without it, set your own; the sky reads it back.
Clock: a real sun track for latitude and declination. The moon rides the same track lunarAge days behind and is lit by the real sun direction. The stars turn about the celestial pole.