wikis / Three.js / wiki / concepts / lighting.md view as markdown report a mistake

Definition

Light is the abstract base class for all three.js light types. Every light exposes a color and intensity, and lighting only influences materials that are designed to react to it — see materials before diagnosing a scene that looks dark or flat.

How It Works

Lights are ordinary members of the scene graph and contribute to a frame whenever the renderer renders the scene from a given camera:

const light = new THREE.DirectionalLight(0xffffff, 2);
light.position.set(3, 4, 2);
scene.add(light);

Because lighting only affects lighting-aware materials, adding a light to a scene that uses only unlit materials (e.g. MeshBasicMaterial) will produce no visible change — the material has to be swapped to a lighting-aware family for the light to matter.

Shadows. Renderer-level shadow maps are disabled by default (WebGLRenderer.shadowMap.enabled = false). When shadow maps are enabled for a scene, shadowMap.autoUpdate can be turned off once the lighting has settled into a static arrangement, avoiding the recurring cost of recomputing shadow maps every frame for scenes that don't need dynamic shadow updates. Evaluate this cost alongside renderer resolution and material complexity, since shadow-map rendering is itself an extra render pass per shadow-casting light.

Key Parameters

• .color — the light's Color.
• .intensity — the light's strength (default 1).
• Renderer-side: WebGLRenderer.shadowMap.enabled (default false), .autoUpdate (default true, can be disabled for static lighting), .needsUpdate (force a one-off shadow recompute), and .type (BasicShadowMap, PCFShadowMap — the default, or VSMShadowMap).

When To Use

Add lights whenever a scene uses lighting-aware materials and needs to look three-dimensional rather than flat-shaded. Enable shadow maps only when a scene's depth cues genuinely benefit from cast shadows, since shadows add render cost; disable shadowMap.autoUpdate for lighting setups that don't change after the initial frames to reclaim that cost. Revisit lighting alongside animation when a scene has dynamic lighting changes (day/night cycles, flickering lights, etc.).

Risks & Pitfalls

• A scene that "looks dark" despite having lights is frequently a material problem, not a lighting problem — check whether the mesh is using an unlit material like MeshBasicMaterial.
• Leaving shadowMap.autoUpdate at its default true for scenes with genuinely static lighting spends render time recomputing shadows that never change.
• Lights allocate GPU-related resources and, like other three.js objects, are not cleaned up automatically by garbage collection — call dispose() when a light is permanently removed, particularly important in long-lived applications that load and unload scenes or models (see loading 3d models).

Related Concepts

Explore materials for which surfaces respond to light, renderer for shadow-map and general output configuration, scene graph for how lights fit into the object hierarchy, and animation for dynamic lighting changes over time. See also loading 3d models for asset-unload flows that should also dispose of lights.

Sources

• raw/web_community-light-three-js-docs.md — Light abstract base class: constructor, color, intensity, dispose().
• raw/web_community-webglrenderer-three-js-docs.md — WebGLRenderer.shadowMap options: enabled, autoUpdate, needsUpdate, type.
• raw/web_community-cleanup.md — general GPU-resource disposal discipline applicable to lights alongside geometries, textures, and materials.