Skip to main content

Interface: LightSettings

Defines a light source in the 3D scene.

The LightSettings interface configures how light illuminates products in the 3D scene. Lighting is crucial for creating mood, highlighting product features, and ensuring materials render correctly. Different light types and parameters create different visual effects, from dramatic spotlights to soft ambient illumination.

Strategic lighting can emphasize product details, create appropriate shadows, and enhance the perceived quality and dimensionality of 3D models.

Example​

// Creating a warm key light from the upper right
const keyLight = {
  name: "MainLight",
  type: LightType.DIRECTIONAL,
  intensity: 0.8,
  position: [5, 8, 3],
  direction: [-0.5, -0.8, -0.3],
  color: [1, 0.98, 0.92],  // Slightly warm white
  shadowEnabled: true
};

// Adding a blue fill light for contrast
const fillLight = {
  name: "FillLight",
  type: LightType.POINT,
  intensity: 0.4,
  position: [-3, 1, -2],
  color: [0.8, 0.9, 1],  // Slightly cool blue
  shadowEnabled: false
};

Properties​

angle?​

optional angle?: number

Cone angle of the spot light in Radians. Used by Spot Light

autoCalcShadowZBounds?​

optional autoCalcShadowZBounds?: boolean

Automatically compute the shadowMinZ and shadowMaxZ for the projection matrix to best fit (including all the casters) on each frame. autoUpdateExtends must be set to true for this to work Used by Directional Light

autoUpdateExtends?​

optional autoUpdateExtends?: boolean

Automatically compute the projection matrix to best fit (including all the casters) on each frame. Used by Directional Light

color?​

optional color?: Color3

Color of the light's diffuse illumination.

This is the main color that the light casts on surfaces, affecting the overall tone and mood of the lighting.

direction​

direction: number[]

Type of direction depends on light type:

  1. Hemispheric - The light reflection direction, not the incoming direction.
  2. Point - In case of direction provided, the shadow will not use a cube texture but simulate a spot shadow as a fallback
  3. Spot and Directional - In 2d mode (needCube being false), gets the direction used to cast the shadow. Also use as the light direction on spot and directional lights. Used by all light types

exponent?​

optional exponent?: number

The light decay speed with the distance from the emission spot. Used by Spot Light

falloffType​

falloffType: FalloffType

How the light's intensity diminishes with distance.

Controls the mathematical model used to calculate how light fades as it travels away from its source.

groundColor?​

optional groundColor?: Color3

For hemispheric lights, the color shining from below.

In hemispheric lighting, this color illuminates surfaces from the opposite direction of the main light direction.

innerAngle?​

optional innerAngle?: number

Only used in gltf falloff mode, this defines the angle where the directional falloff will start before cutting at angle which could be seen as outer angle. Used by Spot Light

intensity​

intensity: number

Brightness level of the light.

Controls how strongly the light illuminates the scene. Higher values create brighter illumination from this light source.

intensityMode​

intensityMode: IntensityMode

Physical unit used for measuring this light's intensity.

Determines how the intensity value is interpreted in physical terms, such as lumens, candela, or lux.

isEnabled?​

optional isEnabled?: boolean

When false, this light is turned off.

Provides a way to temporarily disable a light without removing it from the scene configuration.

name?​

optional name?: string

Identifying name for this light.

Used to reference this specific light in code and settings.

position​

position: number[]

Sets the position the shadow will be casted from. Also use as the light position for both point and spot lights. Used by following light types: Point, Spot, Directional

radius?​

optional radius?: number

Light radius used by PBR Materials to simulate soft area lights. Used by all lights

shadowEnabled?​

optional shadowEnabled?: boolean

When true, this light casts shadows.

Shadows enhance realism by showing how objects block light, but they also increase rendering complexity and performance requirements.

shadowMaxZ?​

optional shadowMaxZ?: number

Sets the shadow projection clipping maximum z value. Used by following light types: Directional, Point, Spot

shadowMinZ?​

optional shadowMinZ?: number

Sets the shadow projection clipping minimum z value. Used by following light types: Directional, Point, Spot

specularColor?​

optional specularColor?: Color3

Color of specular highlights created by this light.

Controls the color of the bright reflections that appear on glossy surfaces illuminated by this light.

target​

target: number[]

Point in space the light is aimed at [x, y, z].

An alternative way to specify light direction, by indicating a specific point the light should point toward.

type?​

optional type?: LightType

Type of light source (spot, point, directional, hemispheric).

Different light types create different illumination patterns and effects, simulating various real-world lighting scenarios.