threejs-impl-lighting

Quick Reference

Light Types at a Glance

Critical Warnings

NEVER use AmbientLight as the sole light source -- it produces flat, dimensionless rendering. ALWAYS combine it with at least one directional or point light.

NEVER forget to add light.target to the scene when repositioning a DirectionalLight or SpotLight target -- the direction vector will NOT update without it.

NEVER use RectAreaLight without calling RectAreaLightUniformsLib.init() first (WebGLRenderer) or RectAreaLightTexturesLib (WebGPURenderer) -- the light will render incorrectly or not at all.

NEVER use more than 1-2 shadow-casting PointLight instances -- each requires 6 shadow map render passes. Use SpotLight with shadows as a cheaper alternative.

ALWAYS call pmremGenerator.dispose() after generating environment maps -- PMREMGenerator allocates significant GPU memory.

ALWAYS set renderer.toneMapping when using physically correct intensity values -- without tone mapping, high lux/candela values produce blown-out white scenes.

Light Class Hierarchy

All lights inherit from Light, which extends Object3D:

Object3D
  └── Light (abstract: .color, .intensity, .dispose())
        ├── AmbientLight        — uniform fill
        ├── HemisphereLight     — sky/ground gradient
        ├── DirectionalLight    — parallel rays (sun)
        ├── PointLight          — omnidirectional (bulb)
        ├── SpotLight           — cone (flashlight)
        ├── RectAreaLight       — planar (window/panel)
        └── LightProbe          — spherical harmonics (IBL)

The Light base class provides:

• .color (Color) -- light color, default 0xffffff
• .intensity (number) -- strength multiplier, default 1
• .isLight (boolean, readonly) -- ALWAYS true
• .dispose() -- releases GPU resources

Physically Correct Lighting (r160+)

As of r160+, ALL lighting uses physically based units by default. The legacy renderer.useLegacyLights property was removed.

The .power property on PointLight, SpotLight, and RectAreaLight gives luminous power in lumens:

• PointLight: power = intensity * 4 * Math.PI
• SpotLight: power = intensity * Math.PI

ALWAYS pair physically correct intensities with tone mapping:

import * as THREE from 'three';

renderer.toneMapping = THREE.ACESFilmicToneMapping;
renderer.toneMappingExposure = 1.0;

The 7 Light Types

AmbientLight

Uniform fill light. NO direction, NO shadows. Use for base illumination only.

const ambient = new THREE.AmbientLight(0x404040, 0.5);
scene.add(ambient);

HemisphereLight

Sky-to-ground gradient. NO shadows. Simulates outdoor ambient with sky and ground bounce.

const hemi = new THREE.HemisphereLight(0xffffbb, 0x080820, 1.0);
scene.add(hemi);

Properties: .groundColor (Color) -- lower hemisphere color.

DirectionalLight

Parallel rays simulating distant light (sun). Direction = light.position to light.target.position.

const sun = new THREE.DirectionalLight(0xffffff, 3);
sun.position.set(5, 10, 7.5);
scene.add(sun);
scene.add(sun.target); // REQUIRED for target repositioning

Properties: .target (Object3D), .shadow (DirectionalLightShadow).

PointLight

Omnidirectional light from a single point. Shadows cost 6 render passes.

const bulb = new THREE.PointLight(0xffaa44, 800, 20, 2);
bulb.position.set(0, 3, 0);
scene.add(bulb);

Properties: .distance (number, 0=infinite), .decay (number, 2=physically correct), .power (lumens).

SpotLight

Cone-shaped light. ALWAYS set penumbra >= 0.1 for realistic soft edges.

const spot = new THREE.SpotLight(0xffffff, 1000);
spot.position.set(0, 10, 0);
spot.angle = Math.PI / 6;
spot.penumbra = 0.3;
spot.decay = 2;
scene.add(spot);
scene.add(spot.target); // REQUIRED for target repositioning

Properties: .angle (max Math.PI/2), .penumbra (0-1), .distance, .decay, .power, .map (cookie texture, REQUIRES castShadow = true), .target, .shadow.

RectAreaLight

Planar emitter for windows, panels, strip lights. Works ONLY with MeshStandardMaterial and MeshPhysicalMaterial. CANNOT cast shadows.

import { RectAreaLightUniformsLib } from 'three/addons/lights/RectAreaLightUniformsLib.js';

RectAreaLightUniformsLib.init(); // MUST call before creating any RectAreaLight

const panel = new THREE.RectAreaLight(0xffffff, 5, 4, 10);
panel.position.set(5, 5, 0);
panel.lookAt(0, 0, 0); // Orient using lookAt, NOT rotation
scene.add(panel);

Properties: .width, .height, .power (lumens).

LightProbe

Spherical harmonics-based ambient lighting. Useful for AR and baked environment lighting.

import { LightProbeGenerator } from 'three/addons/lights/LightProbeGenerator.js';

const probe = LightProbeGenerator.fromCubeTexture(cubeTexture);
scene.add(probe);

Environment Maps (IBL)

Image-Based Lighting (IBL) provides the most realistic ambient illumination for PBR materials. The standard workflow uses RGBELoader + PMREMGenerator.

Standard HDR Environment Workflow

import * as THREE from 'three';
import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';

const pmremGenerator = new THREE.PMREMGenerator(renderer);
const rgbeLoader = new RGBELoader();

rgbeLoader.load('environment.hdr', (hdrTexture) => {
  const envMap = pmremGenerator.fromEquirectangular(hdrTexture);

  scene.environment = envMap.texture;  // ALL PBR materials auto-use this
  scene.background = envMap.texture;   // Optional: visible HDR background

  hdrTexture.dispose();                // Free source texture
  pmremGenerator.dispose();            // ALWAYS dispose after use
});

scene.environment vs scene.background

When scene.environment is set, ALL MeshStandardMaterial and MeshPhysicalMaterial instances AUTOMATICALLY use it for reflections and ambient lighting -- no per-material configuration needed.

PMREMGenerator Methods

EXR Alternative

import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';

new EXRLoader().load('environment.exr', (exrTexture) => {
  const envMap = pmremGenerator.fromEquirectangular(exrTexture);
  scene.environment = envMap.texture;
  exrTexture.dispose();
  pmremGenerator.dispose();
});

Light Helpers

ALWAYS call helper.update() after changing light properties if the helper does not auto-update.

const helper = new THREE.DirectionalLightHelper(dirLight, 5);
scene.add(helper);
// After changing dirLight properties:
helper.update();

Performance Budget

ALWAYS prefer baked lighting for static environments over real-time lights.

ALWAYS use environment maps (IBL) as the primary ambient source instead of multiple fill lights.

Reference Links

• references/methods.md -- Complete API signatures for all light types and PMREMGenerator
• references/examples.md -- Lighting recipes: outdoor, indoor, studio, product
• references/anti-patterns.md -- Common lighting mistakes and fixes

Official Sources

• https://threejs.org/docs/#api/en/lights/AmbientLight
• https://threejs.org/docs/#api/en/lights/DirectionalLight
• https://threejs.org/docs/#api/en/lights/PointLight
• https://threejs.org/docs/#api/en/lights/SpotLight
• https://threejs.org/docs/#api/en/lights/RectAreaLight
• https://threejs.org/docs/#api/en/lights/HemisphereLight
• https://threejs.org/docs/#api/en/lights/LightProbe
• https://threejs.org/docs/#api/en/extras/PMREMGenerator