Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 39 ยท Lights and Shadows

Shadows in Three.js

Enable realistic Three.js shadows: renderer shadow maps, castShadow and receiveShadow, shadow camera bounds, map size, bias to fix acne, and soft shadow types.

Shadows anchor objects to the ground and tell the eye how far apart things are. They are not free in Three.js: you must switch them on in three places (renderer, light, objects), and then tune a handful of settings. Shadows use a technique called shadow mapping: for each shadow-casting light the scene is rendered once from the light's point of view into a depth texture, and when drawing normally the renderer compares each pixel's distance from the light with that texture. If something is closer to the light, the pixel is in shadow.

The three switches

JavaScript
// 1. renderer
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = THREE.PCFSoftShadowMap;

// 2. light
sun.castShadow = true;

// 3. objects
cube.castShadow = true;       // throws shadows
floor.receiveShadow = true;   // catches shadows

Forget any one and no shadow appears. A mesh can do both: a roof receives the shadow of a tree and casts its own onto the floor. Only DirectionalLight, PointLight and SpotLight can cast shadows.

Shadow map types

shadowMap.type Look Cost
BasicShadowMap Hard, pixelated edges Cheapest
PCFShadowMap (default) Slightly filtered edges Cheap
PCFSoftShadowMap Smoother, softer edges Moderate
VSMShadowMap Very soft, blurred; can show light bleeding Higher

The shadow camera

Each light renders its shadow map through a hidden camera, available as light.shadow.camera. For a DirectionalLight it is orthographic: a box that defines the area that gets shadows. Anything outside the box has no shadow, and a too-big box wastes resolution and makes shadows blurry.

JavaScript
sun.shadow.mapSize.set(2048, 2048);      // shadow texture resolution
sun.shadow.camera.near = 1;
sun.shadow.camera.far = 30;
sun.shadow.camera.left = -8;
sun.shadow.camera.right = 8;
sun.shadow.camera.top = 8;
sun.shadow.camera.bottom = -8;
sun.shadow.camera.updateProjectionMatrix();

For spot lights the shadow camera is perspective and follows the cone. Point lights render six directions (like a cube camera), so they cost about six times as much.

Use new THREE.CameraHelper(sun.shadow.camera) to see the box. Fit the box tightly around the part of the scene that matters.

Shadow acne and peter-panning

Because the shadow map has limited precision, a surface can wrongly shadow itself, giving stripes called shadow acne. The fix is a small bias that pushes the comparison slightly:

JavaScript
sun.shadow.bias = -0.0005;       // tiny negative, try -0.0001 to -0.002
sun.shadow.normalBias = 0.02;    // offsets along the surface normal; often works better

Too much bias creates the opposite problem, peter-panning: shadows detach from their objects and appear to float. Raise mapSize and tighten the camera box first, then add the smallest bias that cures the stripes. normalBias is usually the nicer tool for curved shapes.

Soft shadows with radius

light.shadow.radius blurs the shadow edge (it has no effect with BasicShadowMap, and large values cause banding), and light.shadow.blurSamples tunes the blur of VSMShadowMap. Pick VSM when you need a really wide, soft blur.

A shadow playground

Move the sliders to see acne appear and vanish, and watch how the camera helper box limits where shadows exist.

Shadow lab

Set mapSize to 256 for blocky edges, then back to 2048. Shrink the shadow box until the knot's shadow gets cut off at the edge of the helper: shadows only exist inside that box. Push bias strongly negative and watch the contact shadow detach from the sphere (peter-panning).

Spot and point light shadows

Spot lights give focused, stage-like shadows. Point lights cast shadows in all directions, and are costly, so use them sparingly and keep distance small.

Spot light and a moving caster

Performance notes

  • Every shadow-casting light adds a full scene render per update. Limit shadow-casting lights to one or two.
  • Only mark objects that matter with castShadow. Tiny details rarely need to throw shadows.
  • For static scenes set renderer.shadowMap.autoUpdate = false and trigger renderer.shadowMap.needsUpdate = true only when something moves.
  • A cheap fake for soft contact shadows is a blurred dark texture on a plane under the object ("blob shadow"). The best performance of all is baking: render shadows into a texture offline in a tool like Blender and apply them as a light map.

Materials that use transparency, alpha maps or vertex displacement need a matching customDepthMaterial (or alphaTest) to cast the right shadow; otherwise the shadow is cast as if the object were fully opaque and undisplaced.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which settings must be enabled for a mesh to cast a visible shadow on the floor?

    All four switches are needed: renderer, light, caster and receiver.
  2. 2. What is shadow acne?

    A small negative bias or a normalBias fixes it.
  3. 3. Shadows disappear when objects are far from the center of the scene. What is the likely cause?

    Directional shadows only exist inside the orthographic shadow camera volume. Enlarge or move it.
  4. 4. Which light type is the most expensive for shadows?

    A point light's shadow map covers all six directions, like a cube map.

Summary

  • Shadows need renderer.shadowMap.enabled, light.castShadow, mesh.castShadow and mesh.receiveShadow.
  • Fit the shadow camera tightly; raise mapSize for sharper shadows.
  • Cure acne with a small negative bias or normalBias; too much causes peter-panning.
  • Shadows are expensive: limit casters, turn off autoUpdate for static scenes or bake them.

Next: Environment Lighting and HDR