Scene Integration

SkySystem.create adds and orders the atmosphere, stars, cirrus, and clouds. Use named render layers for custom backdrops and transparent objects instead of assigning arbitrary renderOrder values.

import { RenderLayer, placeInLayer } from "threejs-sky-pro";

placeInLayer(myHudSprite, RenderLayer.foreground);

Render Order

Layers are listed from back to front:

background          sky dome — nothing draws behind it
backgroundOverlay   stars, cirrus — blended backdrop
worldSurface        water — a depth-writing surface under the sky
atmosphereOverlay   clouds — depth-tested, drawn over the water
sceneTransparent    your glass, particles, decals
foreground          your HUD, gizmos — always on top

Opaque scene objects require no explicit layer. Use placeInLayer for backdrops, overlays, and objects that need a defined position in the transparent draw order.

Add Custom Content

A transparent object — glass, a particle system, a decal — goes in sceneTransparent. It blends over the clouds and everything behind them:

glass.material.transparent = true;
placeInLayer(glass, RenderLayer.sceneTransparent);

A HUD or gizmo that must stay on top of everything goes in foreground:

placeInLayer(compass, RenderLayer.foreground);

Your own backdrop — a distant mountain ring, a custom skybox behind the atmosphere — goes in background. Keep its material opaque:

mountains.material.transparent = false;
placeInLayer(mountains, RenderLayer.background);

A blended backdrop — an aurora, a haze band that should sit behind your scene but in front of the dome — goes in backgroundOverlay with a transparent material.

Order Objects Within a Layer

Pass an offset to order objects within a layer. Higher values draw later:

placeInLayer(marker, RenderLayer.foreground, 0);
placeInLayer(label, RenderLayer.foreground, 1); // over the marker

Keep the offset under 10 so the mesh stays inside its layer's band.

Opaque and Transparent Objects

Each layer belongs to the opaque or transparent draw list, selected by material.transparent. background and worldSurface are opaque; the other layers are transparent. placeInLayer warns when the material does not match the layer. Correct material.transparent when this warning appears.

With Water Pro

Water Pro uses worldSurface, while Sky Pro clouds use atmosphereOverlay. Both systems assign these layers automatically. See Water Pro Integration for setup.

See Also

• Render Layers — the API reference
• Water Pro Integration
• Post-Processing