Develop

Chapter 5: Environment and Lighting

Updated: Sep 4, 2026

IWSDK treats the visible background, image-based lighting (IBL), and authored lights as separate parts of a scene. You can configure each part on its own.

Import the environment components used by the code examples:

import {
  DomeGradient,
  DomeTexture,
  IBLGradient,
  IBLTexture,
} from '@iwsdk/core';

Configure a background

Add DomeGradient or DomeTexture to the level root. DomeGradient creates a color gradient:

const levelRoot = world.activeLevel.value;
if (levelRoot == null) {
  throw new Error('The active level is not ready');
}

levelRoot.addComponent(DomeGradient, {
  sky: [0.53, 0.81, 0.92, 1],
  equator: [0.91, 0.76, 0.65, 1],
  ground: [0.32, 0.32, 0.32, 1],
  intensity: 1,
});

DomeTexture uses an HDR texture from the asset catalog:

levelRoot.addComponent(DomeTexture, {
  src: 'studio-hdr',
  intensity: 0.8,
  blurriness: 0.1,
});

A background changes what the viewer sees behind scene objects. It does not light those objects.

Configure image-based lighting

Add IBLGradient or IBLTexture to the level root. These components light compatible materials and provide reflections.

levelRoot.addComponent(IBLGradient, {
  sky: [1, 0.9, 0.7, 1],
  equator: [0.7, 0.7, 0.9, 1],
  ground: [0.2, 0.2, 0.2, 1],
  intensity: 1,
});

To use an HDR asset instead, register it with AssetType.HDRTexture and reference its ID:

levelRoot.addComponent(IBLTexture, {
  src: 'studio-hdr',
  intensity: 0.9,
  rotation: [0, Math.PI / 4, 0],
});

MeshStandardMaterial and other physically based materials respond to IBL. Their metalness and roughness values control the reflection.

Add authored lights

IWSDK registers six light components:

AmbientLightComponent: Uniform light with no direction.

HemisphereLightComponent: Sky and ground light aligned to world up.

DirectionalLightComponent: Parallel light along the entity’s local negative Z axis.

PointLightComponent: Light from one position in all directions.

SpotLightComponent: Cone-shaped light along local negative Z.

RectAreaLightComponent: Rectangular area light along local negative Z.

You can author a light in native scene JSON:

{
  "id": "key-light",
  "name": "Key Light",
  "content": {
    "type": "group"
  },
  "transform": {
    "rotationDeg": [-35, 25, 0]
  },
  "components": {
    "com.iwsdk.components.DirectionalLight": {
      "color": [1, 0.95, 0.88, 1],
      "intensity": 3,
      "castShadow": true
    }
  }
}

Directional, point, and spot lights support shadow settings. Rectangular area lights do not cast shadows.

Configure the scene root

The default immersive starter scene places background and IBL components on the scene root:

{
  "version": "iwsdk.scene.v1",
  "units": "meters",
  "components": {
    "com.iwsdk.components.DomeGradient": {
      "sky": [0.24, 0.62, 0.83, 1],
      "equator": [0.66, 0.71, 0.79, 1],
      "ground": [0.81, 0.78, 0.75, 1],
      "intensity": 1
    },
    "com.iwsdk.components.IBLGradient": {
      "sky": [0.69, 0.75, 0.78, 1],
      "equator": [0.66, 0.71, 0.79, 1],
      "ground": [0.81, 0.78, 0.75, 1],
      "intensity": 1
    }
  },
  "resources": {},
  "nodes": []
}

If the scene has no dome component, it has no authored background. If it has no IBL component, IWSDK does not add image-based lighting. IWSDK does not add fallback lighting.