threejs-lights

When to use this skill

ALWAYS use this skill when the user mentions:

• Enabling castShadow / receiveShadow, shadow map size, bias, normal bias, camera frusta for shadow casters
• Physical lights: intensity, distance/decay, angle/penumbra for spots, rect area setup
• LightProbe for irradiance-style probes; IESSpotLight with IES data

IMPORTANT: lights vs loaders vs node-tsl

Topic	Skill
Light classes and shadows	threejs-lights
Loading IES/HDR files	threejs-loaders
LightNode / TSL lighting	threejs-node-tsl

Trigger phrases include:

• "DirectionalLight", "SpotLight", "RectAreaLight", "castShadow", "shadow map"
• "Shadow", "PointLight", "AreaLight", "LightProbe"

How to use this skill

1. Base recipe: ambient/hemisphere fill + directional sun + local points/spots.
2. Shadows: enable on renderer, mark casters/receivers, tune map size vs performance, adjust bias to remove acne/peter-panning.
3. RectArea: initialize addon libs per docs page before using light type.
4. Probes: place probes; generate data via addon generator when applicable; relate to materials env reflections (threejs-materials, threejs-textures).
5. IES: load profile via loader skill, attach to IESSpotLight per docs.
6. Performance: limit shadow-casting lights; use layers (threejs-objects) to exclude objects.

See examples/workflow-directional-shadow.md.

Doc map (official)

Docs section	Representative links
Lights	https://threejs.org/docs/Light.html
Directional	https://threejs.org/docs/DirectionalLight.html
Spot	https://threejs.org/docs/SpotLight.html
Rect area	https://threejs.org/docs/RectAreaLight.html

Scope

• In scope: Core lights, shadow maps, probes, listed addons for rect area and probe generation.
• Out of scope: CSM deep theory (see addon Csm docs if user names it); baked lightmaps in DCC.

Common pitfalls and best practices

• Shadow map resolution must match scene scale—tiny shadows on huge worlds look blocky.
• Point light shadows are six-face expensive—use wisely.
• RectAreaLight without required libs yields black or wrong shading—verify init.
• Mismatched physical units (intensity vs exposure) with threejs-renderers tone mapping causes blown or dim scenes.
• Shadow bias / normalBias trade-offs: acne vs peter-paning—tune with helper frusta (threejs-helpers).

Documentation and version

Light and shadow classes live under Lights in three.js docs. RectAreaLight and probe addons depend on extra init from Addons → Lights; IES profiles require threejs-loaders for file fetch before the light API is usable.

Agent response checklist

When answering under this skill, prefer responses that:

1. Link the concrete light type (DirectionalLight, SpotLight, …) and shadow pages when shadows are on.
2. Separate IES loading to threejs-loaders and LightNode topics to threejs-node-tsl.
3. Give practical shadow map size / bias guidance with threejs-helpers for frustum visualization.
4. Mention renderer.shadowMap.enabled alongside light castShadow (see threejs-renderers).
5. Note performance cost of multiple shadow-casting lights.

References

• https://threejs.org/docs/#Lights
• https://threejs.org/docs/DirectionalLight.html
• https://threejs.org/docs/SpotLight.html
• https://threejs.org/docs/LightShadow.html

Keywords

English: lights, shadows, directional, spotlight, rectarea, lightprobe, three.js

Chinese: Lights, shadows, DirectionalLight, SpotLight, AreaLight, LightProbe, three.js