lighting-shadows-advanced — Claude Code rule for Three.js lighting
The lighting-shadows-advanced rule covers lighting and shadow settings in Three.js with rendering cost in mind. Use it when tuning a scene with several lights or shadow maps.
MIT ★ 4,719 updated 2026-10-24
.claude/rules/lighting-shadows-advanced.mdWhat lighting-shadows-advanced does
The rule covers practical Three.js choices: keeping active lights to a small number, sizing shadow maps, and fitting the shadow camera to scene bounds. It also describes cascaded shadow maps for large scenes and light baking or disabled automatic shadow updates for static ones.
Other options include environment maps, LightProbe, and contact shadows made from a translucent plane. PointLight shadows need six shadow-map renders per light, so the rule recommends considering DirectionalLight or SpotLight instead. Add .claude/rules/lighting-shadows-advanced.md to your Claude Code project.
What it helps with
- reduce the number of active lights
- size shadow maps for the target platform
- fit a shadow camera to scene bounds
- choose a lighting approach for a static scene
- replace costly PointLight shadows
Example prompts for the agent
- Review the lighting in this Three.js scene and suggest ways to reduce shadow rendering cost.
- Set up the DirectionalLight shadow camera to fit the scene.
- Suggest an alternative to PointLight shadows for this static scene.
How to install lighting-shadows-advanced
Manually: put the files in place
.claude/rules/lighting-shadows-advanced.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/lighting-shadows-advanced.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/lighting-shadows-advanced.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/lighting-shadows-advanced.mdManually: put the files in place
.clinerules/lighting-shadows-advanced.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about lighting-shadows-advanced
How do I install lighting-shadows-advanced in Claude Code?
Add .claude/rules/lighting-shadows-advanced.md to your project.
What does lighting-shadows-advanced do?
It gives Three.js guidance for configuring lights and shadows, including shadow maps, CSM, and baked lighting.
Why does the rule caution against PointLight shadows?
Each PointLight needs six shadow-map renders. For shadows, the rule suggests considering DirectionalLight or SpotLight.
Source text
lighting-shadows-advanced.md · MIT
# Lighting & Shadows Advanced
> Source: [100 Three.js Tips - Utsubo](https://www.utsubo.com/blog/threejs-best-practices-100-tips)
Lighting is computationally expensive. Optimize carefully.
## Limit Active Lights
**Target: 3 or fewer active lights**
Each additional light increases shader complexity. Beyond 3 lights, consider baking.
## PointLight Shadow Cost
PointLights require 6 shadow map renders (cube faces):
```
Draw calls = objects × 6 × point_lights
```
A scene with 100 objects and 2 PointLights = 1,200 shadow draw calls.
**Prefer DirectionalLight or SpotLight for shadows.**
## Shadow Map Sizing
| Platform | Recommended Size |
|----------|------------------|
| Mobile | 512-1024 |
| Desktop | 1024-2048 |
| Quality-critical | 4096 |
```javascript
directionalLight.shadow.mapSize.width = 2048;
directionalLight.shadow.mapSize.height = 2048;
```
## Tight Shadow Camera Frustum
```javascript
const light = new THREE.DirectionalLight(0xffffff, 1);
// Fit tightly to scene bounds
light.shadow.camera.left = -10;
light.shadow.camera.right = 10;
light.shadow.camera.top = 10;
light.shadow.camera.bottom = -10;
light.shadow.camera.near = 0.1;
light.shadow.camera.far = 50;
// Use helper to visualize
const helper = new THREE.CameraHelper(light.shadow.camera);
scene.add(helper);
```
## Disable Shadow Auto-Update for Static Scenes
```javascript
renderer.shadowMap.autoUpdate = false;
// Manually trigger when needed (e.g., after moving light)
renderer.shadowMap.needsUpdate = true;
```
## Cascaded Shadow Maps (CSM) for Large Scenes
```javascript
import { CSM } from 'three/addons/csm/CSM.js';
const csm = new CSM({
maxFar: camera.far,
cascades: 4, // Desktop: 4, Mobile: 2
shadowMapSize: 2048,
lightDirection: new THREE.Vector3(-1, -1, -1).normalize(),
camera: camera,
parent: scene
});
// Update in render loop
function animate() {
csm.update();
renderer.render(scene, camera);
}
```
## Bake Lightmaps for Static Scenes
Options:
1. **Blender** - Bake lighting in Blender, export to glTF
2. **@react-three/lightmap** - Runtime baking in R3F
```jsx
// React Three Fiber
import { Lightmap } from '@react-three/lightmap';
<Lightmap>
<Scene />
</Lightmap>
```
## Environment Maps for Ambient Light
```javascript
import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';
const pmremGenerator = new THREE.PMREMGenerator(renderer);
new RGBELoader().load('environment.hdr', (texture) => {
const envMap = pmremGenerator.fromEquirectangular(texture).texture;
scene.environment = envMap;
texture.dispose();
pmremGenerator.dispose();
});
```
## Fake Shadows for Simple Cases
Semi-transparent planes with radial gradients provide budget-friendly contact shadows:
```javascript
const shadowTexture = createRadialGradientTexture();
const shadowMaterial = new THREE.MeshBasicMaterial({
map: shadowTexture,
transparent: true,
opacity: 0.5,
depthWrite: false
});
const shadowPlane = new THREE.Mesh(
new THREE.PlaneGeometry(2, 2),
shadowMaterial
);
shadowPlane.rotation.x = -Math.PI / 2;
shadowPlane.position.y = 0.01; // Slightly above ground
```
## Light Probes
For static scenes with complex lighting:
```javascript
import { LightProbeGenerator } from 'three/addons/lights/LightProbeGenerator.js';
const lightProbe = new THREE.LightProbe();
// Generate from cube camera
const cubeRenderTarget = new THREE.WebGLCubeRenderTarget(256);
const cubeCamera = new THREE.CubeCamera(0.1, 1000, cubeRenderTarget);
cubeCamera.update(renderer, scene);
lightProbe.copy(LightProbeGenerator.fromCubeRenderTarget(renderer, cubeRenderTarget));
scene.add(lightProbe);
```
## Checklist
- [ ] Limit to 3 or fewer active lights
- [ ] Avoid PointLight shadows when possible
- [ ] Size shadow maps for target platform
- [ ] Fit shadow camera frustum tightly
- [ ] Disable shadow autoUpdate for static scenes
- [ ] Use CSM for large outdoor scenes
- [ ] Bake lighting for static geometry
- [ ] Use environment maps for ambient lighting
- [ ] Consider fake shadows for simple cases
© zebbern · MIT · zebbern/claude-code-guide