threejs-materials-lighting

three.js Materials & Lighting

Make three.js surfaces look right: pick the correct material, light the scene, enable shadows, and add image-based lighting. Patterns target r184, verified against r184 (lighting is physically based by default since r155).

When to use

• Use when a mesh renders black or flat, when choosing a material, adding lights, enabling shadows, or setting up environment-map reflections (IBL).
• Use when code constructs MeshStandardMaterial, DirectionalLight, etc., or sets renderer.shadowMap.enabled or scene.environment.

When not to use: the renderer/camera/loop → threejs-scene-setup. Loading models (whose PBR materials this complements) → threejs-gltf-loading. Custom GLSL/ShaderMaterial is its own topic; for the portable concept see shader-programming.

Core workflow

1. Pick a material by need. MeshStandardMaterial (PBR: roughness, metalness, reacts to lights/IBL) for realism; MeshPhysicalMaterial for clearcoat/transmission; MeshBasicMaterial (unlit, ignores lights) for UI/flat; MeshNormalMaterial/MeshDepthMaterial for debugging.
2. Add light, or nothing shows. Lit materials need a light source and/or scene.environment. Combine a soft fill (AmbientLight/HemisphereLight) with a key DirectionalLight.
3. Mind light intensity. Since r155, lighting is physically based; modern intensities are higher than old tutorials (a key DirectionalLight ≈ 1–3).
4. Enable shadows in three places. renderer.shadowMap.enabled = true, the light's castShadow = true, and each mesh's castShadow/receiveShadow. Then fit the light's shadow camera to the scene.
5. Use an environment map for grounded reflections. Assign an equirectangular or PMREM-processed texture to scene.environment; PBR materials pick it up automatically.
6. Verify under real lighting — confirm the surface responds to the key light (highlights move), shadows land where expected, and reflections look plausible.

Patterns

1. PBR material under a 3-light rig

import * as THREE from 'three';
 
const material = new

2. Unlit material (no light needed)

3. Shadows (the three required switches + camera fit)

4. PBR textures on a material

5. Image-based lighting from an HDR environment

Pitfalls

• Mesh is pure black → a lit material with no light and no scene.environment. Add a light or an environment map; to confirm geometry, temporarily swap to MeshBasicMaterial/MeshNormalMaterial.
• Scene too dark even with lights → old tutorial intensities. r155+ is physically based; raise intensities (key light ≈ 2–3) or add an environment map.
• Shadows don't appear → you missed one of the three switches (renderer.shadowMap.enabled, light.castShadow, mesh castShadow/ receiveShadow).
• Shadows are cut off or blocky → the DirectionalLight's orthographic shadow.camera frustum is too big/small or doesn't cover the scene; tighten left/right/top/bottom/near/far and raise shadow.mapSize. Visualise it with new THREE.CameraHelper(light.shadow.camera).
• Shadow acne / peter-panning → adjust light.shadow.bias (small negative) and light.shadow.normalBias.
• Colors look washed out / too bright → color (albedo) textures need texture.colorSpace = THREE.SRGBColorSpace; normal/roughness/metalness maps must stay linear (leave them as NoColorSpace).
• PointLight shadows tank performance → a point light renders the scene 6 times (cube map). Prefer one shadow-casting DirectionalLight; use cheaper fakes elsewhere.

References

• For the material cheat-sheet (which Mesh*Material for which look), light types and their parameters/units, transparency vs alphaTest ordering, and the PMREMGenerator/RoomEnvironment route to IBL without an HDR file, read references/materials-lights-table.md.

Related skills

• threejs-scene-setup — renderer, camera, and loop (set shadowMap, tone mapping).
• threejs-gltf-loading — models arrive with PBR materials this skill tunes.
• shader-programming — custom shader effects (engine-agnostic concept).