threejs-lighting
Helps set up and optimize lighting and shadows in Three.js scenes.
Install
mkdir -p .claude/skills/threejs-lighting && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/3056" && unzip -o skill.zip -d .claude/skills/threejs-lighting && rm skill.zipInstalls to .claude/skills/threejs-lighting
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Three.js lighting - light types, shadows, environment lighting. Use when adding lights, configuring shadows, setting up IBL, or optimizing lighting performance.Key capabilities
- →Configure ambient and directional lighting
- →Implement shadow mapping with bias and softness
- →Set up environment-based lighting using HDR maps
- →Visualize light positions with helper objects
- →Optimize scene performance by limiting light counts
How it works
It provides code patterns for instantiating various Three.js light classes and configuring their properties like intensity, position, and shadow map settings.
Inputs & outputs
When to use threejs-lighting
- →Add ambient or directional lights
- →Configure shadow maps
- →Optimize scene lighting performance
About this skill
Three.js Lighting
Targets three.js r186. Examples use WebGLRenderer; the WebGPU and TSL section uses WebGPURenderer.
Quick Start
import * as THREE from "three";
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setPixelRatio(window.devicePixelRatio);
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(50, window.innerWidth / window.innerHeight, 0.1, 100);
camera.position.set(4, 3, 8);
// A single directional light: intensity is a plain multiplier, no distance falloff
const dirLight = new THREE.DirectionalLight(0xffffff, 3);
dirLight.position.set(5, 10, 5);
scene.add(dirLight);
const floor = new THREE.Mesh(
new THREE.PlaneGeometry(20, 20),
new THREE.MeshStandardMaterial({ color: 0x808080 })
);
floor.rotation.x = -Math.PI / 2;
scene.add(floor);
const mesh = new THREE.Mesh(
new THREE.BoxGeometry(1, 1, 1),
new THREE.MeshStandardMaterial({ color: 0x3a76c4 })
);
scene.add(mesh);
// Shadows need three switches: renderer, light, and the meshes that cast and receive
renderer.shadowMap.enabled = true;
dirLight.castShadow = true;
mesh.castShadow = true;
floor.receiveShadow = true;
function animate() {
renderer.render(scene, camera);
}
renderer.setAnimationLoop(animate);
Light Types and Units
| Light | Shadows | Intensity | Notes |
|---|---|---|---|
| AmbientLight | no | multiplier | Flat fill from every direction |
| HemisphereLight | no | multiplier | Sky color from above, ground color from below |
| DirectionalLight | yes | multiplier | Parallel rays (sun); shines at its target |
| SunLight (addon) | yes, cascaded | multiplier | Shadow frustum fitted to the view automatically |
| PointLight | yes, six faces | candela | Inverse-square falloff (decay 2) |
| SpotLight | yes | candela | Cone; inverse-square falloff (decay 2) |
| RectAreaLight | no | nits | Only MeshStandardMaterial and MeshPhysicalMaterial |
| LightProbe | no | multiplier | Spherical-harmonics ambient, usually baked |
PointLight and SpotLight intensity is candela with inverse-square falloff (decay 2 by default): a 1-candela light 5 units away contributes 1/25, so useful values depend on distance and typically run to the hundreds (the official docs' examples use 80 to 1000). light.power sets the same thing in lumens. light.distance is a smooth cutoff range (0 means no limit). Directional, ambient and hemisphere intensities are plain multipliers with no unit. RectAreaLight intensity is nits (candela per square metre).
Ambient and Hemisphere
// AmbientLight(color, intensity) — a flat multiplier on every lit material
const ambient = new THREE.AmbientLight(0x404040, 0.5);
scene.add(ambient);
// HemisphereLight(skyColor, groundColor, intensity)
const hemi = new THREE.HemisphereLight(0x87ceeb, 0x8b6f47, 0.6);
scene.add(hemi);
DirectionalLight
// DirectionalLight(color, intensity): parallel rays from position towards target; the distance only matters to the shadow camera
const dirLight = new THREE.DirectionalLight(0xffffff, 3);
dirLight.position.set(5, 10, 5);
// Shines from its position towards target; add the target to the scene when you move it
dirLight.target.position.set(0, 0, 0);
scene.add(dirLight.target);
scene.add(dirLight);
SunLight: automatic cascaded shadows
SunLight (three/addons/lights/SunLight.js) is a parallel light with two cascaded shadow maps, suited to large scenes. It has no target: it shines from its position towards the origin, straight down by default. With WebGLRenderer it works out of the box; under WebGPURenderer register it first (see WebGPU and TSL).
import { SunLight } from "three/addons/lights/SunLight.js";
const sun = new SunLight(0xfff2e3, 3);
sun.position.set(100, 160, 60);
sun.castShadow = true;
scene.add(sun);
The cascades are fitted automatically to slices of the camera's view frustum, up to sun.shadow.camera.far or the view camera's far plane, whichever is smaller. shadow.camera.left/right/top/bottom are ignored; the default mapSize is 1024 × 1024 per cascade. There is no shadow frustum to hand-tighten.
PointLight and SpotLight
// PointLight(color, intensity in candela, distance, decay)
const bulb = new THREE.PointLight(0xffdcb0, 100, 20, 2);
bulb.position.set(0, 4, 0);
scene.add(bulb);
// SpotLight(color, intensity in candela, distance, angle, penumbra, decay)
const deskLamp = new THREE.SpotLight(0xffffff, 250, 30, Math.PI / 6, 0.4, 2);
deskLamp.position.set(2, 5, 0);
deskLamp.target.position.set(0, 0, 0);
scene.add(deskLamp.target);
scene.add(deskLamp);
// Prefer lumens: power writes the candela intensity for you
bulb.power = 800;
angle is the cone half-angle in radians with an upper bound of Math.PI / 2; penumbra (0 to 1) softens the cone edge.
RectAreaLight
A rectangular emitter for soft window- or strip-style lighting. It lights only MeshStandardMaterial and MeshPhysicalMaterial, and it cannot cast shadows.
import { RectAreaLightHelper } from "three/addons/helpers/RectAreaLightHelper.js";
import { RectAreaLightUniformsLib } from "three/addons/lights/RectAreaLightUniformsLib.js";
// WebGLRenderer: add the LTC lookup textures to the renderer's uniforms, once
RectAreaLightUniformsLib.init();
// RectAreaLight(color, intensity in nits, width, height)
const windowLight = new THREE.RectAreaLight(0xffffff, 5, 4, 10);
windowLight.position.set(-5, 5, 0);
windowLight.lookAt(0, 0, 0); // emits from its front face
scene.add(windowLight);
// The helper must be added as a child of the light
const helper = new RectAreaLightHelper(windowLight);
windowLight.add(helper);
Under WebGPURenderer, register the LTC textures with RectAreaLightTexturesLib instead (see WebGPU and TSL).
Shadows
// 1. Renderer: shadow maps are off by default; PCFShadowMap is the soft filtered default,
// VSMShadowMap blurs the map itself, BasicShadowMap is hard-edged
renderer.shadowMap.enabled = true;
renderer.shadowMap.type = THREE.PCFShadowMap;
// 2. Light
const dirLight = new THREE.DirectionalLight(0xffffff, 3);
dirLight.position.set(5, 10, 5);
dirLight.castShadow = true;
scene.add(dirLight);
// 3. Objects
mesh.castShadow = true;
mesh.receiveShadow = true;
shadow.radius above 1 widens the PCF filter and the VSM blur; it has no effect with BasicShadowMap. VSM also exposes shadow.blurSamples (default 8), and PointLight shadows do not support VSM at all — WebGLRenderer warns and skips the light's shadow. PCFSoftShadowMap is deprecated: it warns and falls back to PCFShadowMap, which is already soft. With VSMShadowMap, every mesh that receives shadows also casts them.
Tuning a directional shadow
const dirLight = new THREE.DirectionalLight(0xffffff, 3);
dirLight.position.set(5, 10, 5); // every caster must lie between near and far from here
dirLight.castShadow = true;
// The shadow camera sits at the light's position and looks at its target: near and far
// are distances from the light; left/right/top/bottom frame the area around the target
const shadowCam = dirLight.shadow.camera;
shadowCam.left = -10;
shadowCam.right = 10;
shadowCam.top = 10;
shadowCam.bottom = -10;
shadowCam.near = 0.5;
shadowCam.far = 50;
shadowCam.updateProjectionMatrix(); // needed whenever these change after the first render
dirLight.shadow.mapSize.set(2048, 2048); // powers of two
// Acne: normalBias offsets the lookup along the surface normal (light grazing a surface);
// bias offsets the depth compared against the map — start tiny, negative fights acne
dirLight.shadow.normalBias = 0.02;
dirLight.shadow.bias = -0.0001;
// Lighten shadows without adding fill lights: 0 removes, 1 is full darkness
dirLight.shadow.intensity = 0.7;
Point and spot shadow cameras are derived
The renderer rebuilds these cameras on every shadow pass: a spot light's shadow fov is 2 × angle × shadow.focus (in degrees) and its far comes from light.distance; a point light's far also comes from light.distance. The fov is always overwritten, and a manual far survives only while distance is 0. Control the cone with angle and shadow.focus, the range with distance.
const deskLamp = new THREE.SpotLight(0xffffff, 250, 30);
deskLamp.castShadow = true;
deskLamp.shadow.mapSize.set(1024, 1024);
deskLamp.shadow.focus = 0.9; // shadow fov as a fraction of the light's cone
deskLamp.shadow.bias = -0.0001;
Visualize a directional or spot light's shadow camera with new THREE.CameraHelper(light.shadow.camera) added to the scene, and call the helper's update() after changing the camera.
Contact shadows (fake, cheap)
A shadow map per light is overkill for a grounded look; a radial-gradient blob costs one textured quad.
// A soft blob under the object: no shadow map, works under both renderers
const size = 128;
const canvas = document.createElement("canvas");
canvas.width = canvas.height = size;
const ctx = canvas.getContext("2d");
const gradient = ctx.createRadialGradient(size / 2, size / 2, 0, size / 2, size / 2, size / 2);
gradient.addColorStop(0, "rgba(0,0,0,0.6)");
gradient.addColorStop(1, "rgba(0,0,0,0)");
ctx.fillStyle = gradient;
ctx.fillRect(0, 0, size, size);
const shadowTexture = new THREE.CanvasTexture(canvas);
shadowTexture.colorSpace = THREE.SRGBColorSpace; // a canvas used as a color map is sRGB
const blob = new THREE.Mesh(
new THREE.PlaneGeometry(2, 2),
new THREE.MeshBasicMaterial({ map: shadowTexture, transparent: true, depthWrite: false })
);
blob.rotation.x = -Math.PI / 2;
blob.position.y = 0.001; // just above the floor to avoid z-fighting
scene.add(blob);
For a blob that follows the object's silhouette, render depth from below into a render target and blur it — the official webgl_shadow_contact example does this with HorizontalBlurShader an
Content truncated.
When not to use it
- →Scenes requiring only unlit materials
- →Environments where performance constraints forbid dynamic shadows
Prerequisites
Limitations
- →RectAreaLight does not support native shadows
- →High light counts increase shader complexity
How it compares
It offers a structured reference for specific light types and shadow optimization techniques rather than generic documentation.
Compared to similar skills
threejs-lighting side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| threejs-lighting (this skill) | 1 | 10mo | No flags | Intermediate |
| threejs-skills | 61 | 7mo | No flags | Intermediate |
| 3d-graphics | 33 | 9mo | No flags | Advanced |
| threejs-shaders | 4 | 10mo | No flags | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by CloudAI-X
View all by CloudAI-X →You might also like
threejs-skills
sickn33
Three.js skills for creating 3D elements and interactive experiences
3d-graphics
samhvw8
3D web graphics with Three.js (WebGL/WebGPU). Capabilities: scenes, cameras, geometries, materials, lights, animations, model loading (GLTF/FBX), PBR materials, shadows, post-processing (bloom, SSAO, SSR), custom shaders, instancing, LOD, physics, VR/XR. Actions: create, build, animate, render 3D scenes/models. Keywords: Three.js, WebGL, WebGPU, 3D graphics, scene, camera, geometry, material, light, animation, GLTF, FBX, OrbitControls, PBR, shadow mapping, post-processing, bloom, SSAO, shader, instancing, LOD, WebXR, VR, AR, product configurator, data visualization, architectural walkthrough, interactive 3D, canvas. Use when: creating 3D visualizations, building WebGL/WebGPU apps, loading 3D models, adding animations, implementing VR/XR, creating interactive graphics, building product configurators.
threejs-shaders
CloudAI-X
Three.js shaders - GLSL, ShaderMaterial, uniforms, custom effects. Use when creating custom visual effects, modifying vertices, writing fragment shaders, or extending built-in materials.
gsap
martinholovsky
GSAP animations for JARVIS HUD transitions and effects
threejs-animation
CloudAI-X
Three.js animation - keyframe animation, skeletal animation, morph targets, animation mixing. Use when animating objects, playing GLTF animations, creating procedural motion, or blending animations.
threejs-interaction
CloudAI-X
Three.js interaction - raycasting, controls, mouse/touch input, object selection. Use when handling user input, implementing click detection, adding camera controls, or creating interactive 3D experiences.