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 r186, verified
against r186 (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
- 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.
- 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.
- Mind light intensity. Since r155, lighting is physically based; modern
intensities are higher than old tutorials (a key
DirectionalLight ≈ 1–3).
- 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.
- Use an environment map for grounded reflections. Assign an equirectangular or
PMREM-processed texture to
scene.environment; PBR materials pick it up
automatically.
- 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 THREE.MeshStandardMaterial({
color: 0xcc4444,
roughness: 0.5, // 0 = mirror, 1 = fully matte
metalness: 0.0, // 0 = dielectric (plastic/wood), 1 = metal
});
const mesh = new THREE.Mesh(new THREE.SphereGeometry(1, 32, 16), material);
scene.add(mesh);
// Soft sky/ground fill + a directional key light.
scene.add(new THREE.HemisphereLight(0xbbddff, 0x443322, 1.0)); // sky, ground, intensity
const key = new THREE.DirectionalLight(0xffffff, 2.5);
key.position.set(5, 10, 7);
scene.add(key);
2. Unlit material (no light needed)
// MeshBasicMaterial ignores lights — for flat color, UI, or sprites/labels.
const flat = new THREE.MeshBasicMaterial({ color: 0x44aa88 });
// A textured color map should be tagged sRGB so colors aren't washed out:
const tex = new THREE.TextureLoader().load('assets/logo.png');
tex.colorSpace = THREE.SRGBColorSpace;
const logo = new THREE.MeshBasicMaterial({ map: tex, transparent: true });
3. Shadows (the three required switches + camera fit)
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = THREE.PCFShadowMap; // soft by default since r182
const sun = new THREE.DirectionalLight(0xffffff, 3);
sun.position.set(8, 12, 6);
sun.castShadow = true;
sun.shadow.mapSize.set(2048, 2048); // default 512; raise for crisp
// DirectionalLight uses an OrthographicCamera — fit it tightly to the scene:
const cam = sun.shadow.camera;
cam.near = 1; cam.far = 40;
cam.left = -15; cam.right = 15; cam.top = 15; cam.bottom = -15;
scene.add(sun);
mesh.castShadow = true;
ground.receiveShadow = true; // a plane to catch the shadow
4. PBR textures on a material
const loader = new THREE.TextureLoader();
const colorMap = loader.load('assets/brick_color.jpg');
colorMap.colorSpace = THREE.SRGBColorSpace; // color maps are sRGB
const normalMap = loader.load('assets/brick_normal.jpg'); // data maps stay linear
const roughMap = loader.load('assets/brick_rough.jpg');
const brick = new THREE.MeshStandardMaterial({
map: colorMap,
normalMap,
roughnessMap: roughMap,
metalness: 0,
});
5. Image-based lighting from an HDR environment
import { HDRLoader } from 'three/addons/loaders/HDRLoader.js'; // RGBELoader before r180
new HDRLoader().load('assets/studio.hdr', (hdr) => {
hdr.mapping = THREE.EquirectangularReflectionMapping;
scene.environment = hdr; // lights + reflects all PBR materials
scene.background = hdr; // optional: show it as the backdrop
});
// Optional tone curve (default is NoToneMapping). AgXToneMapping and
// NeutralToneMapping are the other common choices.
renderer.toneMapping = THREE.ACESFilmicToneMapping;
renderer.toneMappingExposure = 1.0;
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). GLTFLoader already tags glTF
textures correctly, so this applies to textures you load yourself.
- Looks right on its own but dark/flat once post-processing is added → tone
mapping and the sRGB output conversion only run when rendering straight to the
canvas; end the
EffectComposer chain with OutputPass.
- Environment lighting too strong or too weak → scale it with
scene.environmentIntensity (r163+); material.envMapIntensity only affects a
material's own envMap.
- 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, the
PMREMGenerator/RoomEnvironment route to IBL without an HDR file, and tone
mapping with post-processing, 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).
1---2name: threejs-materials-lighting3description: >4 Light and shade a three.js scene: choose materials (MeshStandardMaterial PBR vs5 unlit MeshBasicMaterial), add ambient/hemisphere/directional/point/spot lights,6 turn on shadow maps, and use an environment map (IBL) for realistic reflections.7 Use when a three.js model looks black, flat, or wrong — when the user mentions8 three.js materials, MeshStandardMaterial, lights, shadows, envMap, or PBR. For9 renderer/loop setup use threejs-scene-setup; for loading models use10 threejs-gltf-loading.11metadata:12 source: https://skillmd.com/skills/junmystery/threejs-materials-lighting13---1415# three.js Materials & Lighting1617Make three.js surfaces look right: pick the correct material, light the scene,18enable shadows, and add image-based lighting. Patterns target **r186**, verified19against **r186** (lighting is physically based by default since r155).2021## When to use2223- Use when a mesh renders black or flat, when choosing a material, adding lights,24 enabling shadows, or setting up environment-map reflections (IBL).25- Use when code constructs `MeshStandardMaterial`, `DirectionalLight`, etc., or sets26 `renderer.shadowMap.enabled` or `scene.environment`.2728**When *not* to use:** the renderer/camera/loop → `threejs-scene-setup`. Loading29models (whose PBR materials this complements) → `threejs-gltf-loading`. Custom30GLSL/`ShaderMaterial` is its own topic; for the portable concept see31`shader-programming`.3233## Core workflow34351. **Pick a material by need.** `MeshStandardMaterial` (PBR: `roughness`,36 `metalness`, reacts to lights/IBL) for realism; `MeshPhysicalMaterial` for37 clearcoat/transmission; `MeshBasicMaterial` (unlit, ignores lights) for UI/flat;38 `MeshNormalMaterial`/`MeshDepthMaterial` for debugging.392. **Add light, or nothing shows.** Lit materials need a light source and/or40 `scene.environment`. Combine a soft fill (`AmbientLight`/`HemisphereLight`) with a41 key `DirectionalLight`.423. **Mind light intensity.** Since r155, lighting is physically based; modern43 intensities are higher than old tutorials (a key `DirectionalLight` ≈ 1–3).444. **Enable shadows in three places.** `renderer.shadowMap.enabled = true`, the45 light's `castShadow = true`, and each mesh's `castShadow`/`receiveShadow`. Then46 fit the light's shadow camera to the scene.475. **Use an environment map for grounded reflections.** Assign an equirectangular or48 PMREM-processed texture to `scene.environment`; PBR materials pick it up49 automatically.506. **Verify under real lighting** — confirm the surface responds to the key light51 (highlights move), shadows land where expected, and reflections look plausible.5253## Patterns5455### 1. PBR material under a 3-light rig5657```js58import * as THREE from 'three';5960const material = new THREE.MeshStandardMaterial({61 color: 0xcc4444,62 roughness: 0.5, // 0 = mirror, 1 = fully matte63 metalness: 0.0, // 0 = dielectric (plastic/wood), 1 = metal64});65const mesh = new THREE.Mesh(new THREE.SphereGeometry(1, 32, 16), material);66scene.add(mesh);6768// Soft sky/ground fill + a directional key light.69scene.add(new THREE.HemisphereLight(0xbbddff, 0x443322, 1.0)); // sky, ground, intensity70const key = new THREE.DirectionalLight(0xffffff, 2.5);71key.position.set(5, 10, 7);72scene.add(key);73```7475### 2. Unlit material (no light needed)7677```js78// MeshBasicMaterial ignores lights — for flat color, UI, or sprites/labels.79const flat = new THREE.MeshBasicMaterial({ color: 0x44aa88 });80// A textured color map should be tagged sRGB so colors aren't washed out:81const tex = new THREE.TextureLoader().load('assets/logo.png');82tex.colorSpace = THREE.SRGBColorSpace;83const logo = new THREE.MeshBasicMaterial({ map: tex, transparent: true });84```8586### 3. Shadows (the three required switches + camera fit)8788```js89renderer.shadowMap.enabled = true;90renderer.shadowMap.type = THREE.PCFShadowMap; // soft by default since r1829192const sun = new THREE.DirectionalLight(0xffffff, 3);93sun.position.set(8, 12, 6);94sun.castShadow = true;95sun.shadow.mapSize.set(2048, 2048); // default 512; raise for crisp96// DirectionalLight uses an OrthographicCamera — fit it tightly to the scene:97const cam = sun.shadow.camera;98cam.near = 1; cam.far = 40;99cam.left = -15; cam.right = 15; cam.top = 15; cam.bottom = -15;100scene.add(sun);101102mesh.castShadow = true;103ground.receiveShadow = true; // a plane to catch the shadow104```105106### 4. PBR textures on a material107108```js109const loader = new THREE.TextureLoader();110const colorMap = loader.load('assets/brick_color.jpg');111colorMap.colorSpace = THREE.SRGBColorSpace; // color maps are sRGB112const normalMap = loader.load('assets/brick_normal.jpg'); // data maps stay linear113const roughMap = loader.load('assets/brick_rough.jpg');114115const brick = new THREE.MeshStandardMaterial({116 map: colorMap,117 normalMap,118 roughnessMap: roughMap,119 metalness: 0,120});121```122123### 5. Image-based lighting from an HDR environment124125```js126import { HDRLoader } from 'three/addons/loaders/HDRLoader.js'; // RGBELoader before r180127128new HDRLoader().load('assets/studio.hdr', (hdr) => {129 hdr.mapping = THREE.EquirectangularReflectionMapping;130 scene.environment = hdr; // lights + reflects all PBR materials131 scene.background = hdr; // optional: show it as the backdrop132});133// Optional tone curve (default is NoToneMapping). AgXToneMapping and134// NeutralToneMapping are the other common choices.135renderer.toneMapping = THREE.ACESFilmicToneMapping;136renderer.toneMappingExposure = 1.0;137```138139## Pitfalls140141- **Mesh is pure black** → a lit material with no light and no `scene.environment`.142 Add a light or an environment map; to confirm geometry, temporarily swap to143 `MeshBasicMaterial`/`MeshNormalMaterial`.144- **Scene too dark even with lights** → old tutorial intensities. r155+ is physically145 based; raise intensities (key light ≈ 2–3) or add an environment map.146- **Shadows don't appear** → you missed one of the three switches147 (`renderer.shadowMap.enabled`, `light.castShadow`, mesh `castShadow`/148 `receiveShadow`).149- **Shadows are cut off or blocky** → the `DirectionalLight`'s orthographic150 `shadow.camera` frustum is too big/small or doesn't cover the scene; tighten151 `left/right/top/bottom/near/far` and raise `shadow.mapSize`. Visualise it with152 `new THREE.CameraHelper(light.shadow.camera)`.153- **Shadow acne / peter-panning** → adjust `light.shadow.bias` (small negative) and154 `light.shadow.normalBias`.155- **Colors look washed out / too bright** → color (albedo) textures need156 `texture.colorSpace = THREE.SRGBColorSpace`; normal/roughness/metalness maps must157 stay linear (leave them as `NoColorSpace`). `GLTFLoader` already tags glTF158 textures correctly, so this applies to textures you load yourself.159- **Looks right on its own but dark/flat once post-processing is added** → tone160 mapping and the sRGB output conversion only run when rendering straight to the161 canvas; end the `EffectComposer` chain with `OutputPass`.162- **Environment lighting too strong or too weak** → scale it with163 `scene.environmentIntensity` (r163+); `material.envMapIntensity` only affects a164 material's own `envMap`.165- **PointLight shadows tank performance** → a point light renders the scene 6 times166 (cube map). Prefer one shadow-casting `DirectionalLight`; use cheaper fakes167 elsewhere.168169## References170171- For the material cheat-sheet (which `Mesh*Material` for which look), light types172 and their parameters/units, transparency vs `alphaTest` ordering, the173 `PMREMGenerator`/`RoomEnvironment` route to IBL without an HDR file, and tone174 mapping with post-processing, read `references/materials-lights-table.md`.175176## Related skills177178- `threejs-scene-setup` — renderer, camera, and loop (set `shadowMap`, tone mapping).179- `threejs-gltf-loading` — models arrive with PBR materials this skill tunes.180- `shader-programming` — custom shader effects (engine-agnostic concept).