threejs-materials-lighting Checked

// 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 cinematic tone curve:

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`).
- **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).