Three.js Shadows: Setup and Fixing Common Problems

This trips up almost everyone at least once, so it's worth stating precisely:

1. renderer.shadowMap.enabled = true. Without this, no shadow map is ever rendered, full stop, no matter what else is configured.
2. light.castShadow = true. Only DirectionalLight, PointLight and SpotLight support shadows; AmbientLight and HemisphereLight never cast them.
3. Per-mesh: mesh.castShadow = true on anything that should cast a shadow, mesh.receiveShadow = true on anything that should show shadows cast onto it (commonly a ground plane, which usually wants receiveShadow but not castShadow).

Set renderer.shadowMap.type to THREE.PCFSoftShadowMap for softer edges than the default: a cheap visual upgrade.

A DirectionalLight's shadow is rendered from an orthographic camera whose frustum you must size to fit your scene: light.shadow.camera.{left,right,top,bottom,near,far}. The default frustum is small (roughly a 10-unit box), so in a larger scene, objects and their shadows simply fall outside it and don't render, which looks exactly like "shadows aren't working" but is actually clipping.

Size the frustum to comfortably cover your scene's extent, but not much larger. An oversized frustum spreads the same shadow-map resolution over a bigger area, making shadows blurrier and more prone to acne (see below). For SpotLight and PointLight, the shadow camera is perspective and tied to the light's own angle/range, so there's less manual tuning needed.

Two artifacts show up constantly:

• Shadow acne: a moiré/striped self-shadowing pattern on lit surfaces, caused by shadow-map precision limits. Fix by increasing light.shadow.bias (a small negative offset, e.g. -0.001) or light.shadow.normalBias, which is usually the more predictable of the two to tune.
• Peter-panning: the shadow appears detached from the object, floating slightly away from its base. Usually caused by overcorrecting bias to fix acne. It's a genuine tradeoff: nudge bias values incrementally rather than jumping to a large offset.
• Blocky/low-res shadow edges: increase light.shadow.mapSize.width/height (default is often 512; try 1024 or 2048), and tighten the shadow camera frustum to the actual scene bounds rather than leaving it oversized.