Skip to main content
rule CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/lighting-shadows-advanced.md
Open on GitHub

What 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.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

All IDE rules for Game dev and 3D: Unity, Unreal, Godot, Blender →

From the same set86

The whole set →
core-web-vitals core-web-vitals is a Claude Code rule for loading Three.js models and textures without letting heavy 3D delay first paint or degrade LCP, FID and CLS. CX Codex +1 ★ 4,719repo stars postprocessing-optimization postprocessing-optimization is a rule for Three.js and React Three Fiber that helps optimize post-processing by combining shader passes and tuning render settings. CX Codex +1 ★ 4,719repo stars timeline-builder timeline-builder is a Claude Code skill that turns JSON event data into interactive HTML timelines with vertical, horizontal, or dual-side layouts. It covers project milestones, release histories, and resumes. CX Codex +1 ★ 4,719repo stars loading-suspense loading-suspense — a rule that keeps async React Three Fiber components inside Suspense, so a model still downloading doesn't leave the canvas blank. CX Codex +1 ★ 4,719repo stars migration-checklist migration-checklist teaches the agent how to migrate code when Three.js updates. Lists breaking changes from r125 onwards and current import paths. CX Codex +1 ★ 4,719repo stars audio-spatial The audio-spatial rule for Claude Code provides Three.js 3D audio patterns for source positioning, distance falloff, and response to user interaction. CX Codex +1 ★ 4,719repo stars debug-devtools The debug-devtools rule guides an agent through adding diagnostics for Three.js performance, scene parameters, and WebGL context loss. Use it when tracking down a rendering bottleneck or inspecting a scene. CX Codex +1 ★ 4,719repo stars tsl-post-processing A reference rule for TSL post-processing in Three.js: chain effects onto postProcessing.outputNode instead of stacking EffectComposer passes. CX Codex +1 ★ 4,719repo stars

Project sponsors

Companies that keep this analytics open