| name | threejs-lighting |
| description | Design and debug Three.js lighting with directional, point, spot, hemisphere, and area lights, shadow maps, image-based lighting, environment maps, light helpers, and performance budgets. Use when lighting a 3D scene, configuring shadows, setting up HDR illumination, matching a visual reference, or fixing dark, flat, or expensive renders. Triggers on: Three.js lighting, directional light, point light, spot light, shadows, shadow map, ambient light, HDR environment, IBL, environment map, light helper.
|
| allowed-tools | Bash Read Write Edit Glob Grep |
| license | MIT |
| metadata | {"tags":"three.js, lighting, shadows, environment-map, ibl, hdr, pbr, webgl","version":"1.0","source":"https://github.com/CloudAI-X/threejs-skills/tree/main/skills/threejs-lighting"} |
Three.js Lighting
Use this skill for light selection, shadow behavior, and image-based illumination. Route
PBR surface settings to threejs-materials, HDR/environment asset setup to
threejs-textures, and screen-space effects to threejs-postprocessing.
When to use this skill
- Light a scene with physically meaningful direct and ambient/environment contribution
- Configure directional, point, or spot shadows without uncontrolled quality cost
- Set up an HDR environment for PBR reflections and diffuse illumination
- Diagnose black, flat, overexposed, acne-prone, or performance-heavy lighting
Instructions
Step 1: Start from material and exposure reality
- Confirm the mesh uses a light-reactive material such as
MeshStandardMaterial; an
unlit MeshBasicMaterial cannot demonstrate lighting changes.
- Establish renderer color/tone settings before compensating with arbitrary light values.
- Decide whether the scene needs direct lights, image-based lighting, or both. A single
ambient light hides shape; use it sparingly as fill, not as an all-purpose fix.
Step 2: Choose the narrowest light model
| Visual requirement | Default |
|---|
| Sun/moon-like directional source | DirectionalLight |
| Local bulb or small emitter | PointLight |
| Cone/projector with falloff | SpotLight |
| Soft sky/ground fill | HemisphereLight |
| Large studio panel | RectAreaLight |
| PBR reflection and ambient response | Environment map / IBL |
const key = new THREE.DirectionalLight(0xffffff, 3);
key.position.set(4, 6, 3);
key.castShadow = true;
scene.add(key);
scene.add(new THREE.HemisphereLight(0xcfe8ff, 0x223344, 1));
Use helpers during setup, then remove or gate them in production views.
Step 3: Make shadows intentional
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = THREE.PCFSoftShadowMap;
mesh.castShadow = true;
mesh.receiveShadow = true;
key.shadow.mapSize.set(1024, 1024);
key.shadow.camera.near = 0.5;
key.shadow.camera.far = 30;
Tighten the shadow camera/frustum around real casters and receivers. Increase map size,
number of shadow-casting lights, or update frequency only after profiling target hardware.
Address acne/peter-panning by checking geometry scale, bias, and normal bias—not by
blindly pushing values until artifacts invert.
Step 4: Add image-based lighting when PBR requires it
Load and preprocess an HDR/equirectangular asset through the appropriate loader/PMREM
path for the installed Three.js version. Set scene.environment for material response;
set scene.background separately when the environment should also be visible.
Step 5: Verify look and budget
- Compare the material response with shadows off/on, direct light only, and IBL only.
- Test shadow edges, moving casters, and objects near the light's shadow bounds.
- Profile on target devices with real scene density before raising quality tiers.
- Verify teardown disposes feature-owned environment/render resources through the
texture-loading owner.
Examples
Small product presentation
Use a key directional/area source, low-intensity fill, and an environment map. Do not
simulate every studio bounce with many shadowed point lights; PBR environment lighting is
usually more stable and cheaper.
Outdoor scene
Use one directional sun, a sky/ground hemisphere contribution, and a bounded shadow
camera that follows the visible play/view area only when required.
Best practices
- Light for material response, not only for a bright screenshot.
- Keep shadow casters/receivers and the shadow frustum as small as the visual need allows.
- Use environment maps for PBR instead of stacking ambient lights.
- Tune tone mapping/exposure at the renderer level before distorting every light.
- Treat every shadow quality increase as a measured performance tradeoff.
References
