init

.opencode/skills/threejs/references/05-lights.md

@@ -0,0 +1,183 @@
+# Lights
+
+Illuminate 3D scenes with various light types.
+
+## Ambient Light
+
+Global illumination affecting all objects equally:
+
+```javascript
+const light = new THREE.AmbientLight(0x404040); // soft white
+scene.add(light);
+
+// Often used as base illumination with other lights
+```
+
+## Directional Light
+
+Infinite distance light with parallel rays (sun-like):
+
+```javascript
+const light = new THREE.DirectionalLight(0xffffff, 1);
+light.position.set(10, 10, 5);
+light.target.position.set(0, 0, 0);
+scene.add(light);
+scene.add(light.target); // target must be in scene
+
+// With shadows
+light.castShadow = true;
+light.shadow.mapSize.width = 2048;
+light.shadow.mapSize.height = 2048;
+light.shadow.camera.near = 0.5;
+light.shadow.camera.far = 500;
+light.shadow.camera.left = -10;
+light.shadow.camera.right = 10;
+light.shadow.camera.top = 10;
+light.shadow.camera.bottom = -10;
+
+// Visualize shadow camera
+const helper = new THREE.CameraHelper(light.shadow.camera);
+scene.add(helper);
+```
+
+## Point Light
+
+Omnidirectional light from a point (lightbulb-like):
+
+```javascript
+const light = new THREE.PointLight(0xff0000, 1, 100, 2);
+// params: color, intensity, distance (0 = infinite), decay
+
+light.position.set(0, 10, 0);
+scene.add(light);
+
+// With shadows
+light.castShadow = true;
+light.shadow.mapSize.width = 1024;
+light.shadow.mapSize.height = 1024;
+light.shadow.camera.near = 0.5;
+light.shadow.camera.far = 100;
+```
+
+## Spot Light
+
+Cone-shaped light (spotlight-like):
+
+```javascript
+const light = new THREE.SpotLight(0xffffff, 1);
+light.position.set(0, 10, 0);
+light.target.position.set(0, 0, 0);
+scene.add(light);
+scene.add(light.target);
+
+// Cone parameters
+light.angle = Math.PI / 6; // cone angle
+light.penumbra = 0.1;      // edge softness (0-1)
+light.decay = 2;           // light falloff
+light.distance = 100;      // max range (0 = infinite)
+
+// With shadows
+light.castShadow = true;
+light.shadow.mapSize.width = 1024;
+light.shadow.mapSize.height = 1024;
+```
+
+## Hemisphere Light
+
+Sky/ground two-color lighting:
+
+```javascript
+const light = new THREE.HemisphereLight(
+  0x0000ff, // sky color (blue)
+  0x00ff00, // ground color (green)
+  0.6       // intensity
+);
+scene.add(light);
+
+// Good for outdoor scenes
+```
+
+## RectArea Light (Addon)
+
+Rectangular area light (realistic surface illumination):
+
+```javascript
+import { RectAreaLight } from 'three/addons/lights/RectAreaLight.js';
+
+const light = new RectAreaLight(0xffffff, 5, 10, 10);
+// params: color, intensity, width, height
+
+light.position.set(0, 5, 0);
+light.lookAt(0, 0, 0);
+scene.add(light);
+
+// Requires WebGL 2.0
+```
+
+## Shadow Configuration
+
+Global renderer settings:
+
+```javascript
+renderer.shadowMap.enabled = true;
+renderer.shadowMap.type = THREE.PCFSoftShadowMap; // soft shadows
+
+// Shadow types:
+// THREE.BasicShadowMap - fast, aliased
+// THREE.PCFShadowMap - smoother
+// THREE.PCFSoftShadowMap - softer (default)
+// THREE.VSMShadowMap - variance shadow maps
+
+// Objects must opt-in to shadows
+mesh.castShadow = true;    // object casts shadows
+mesh.receiveShadow = true; // object receives shadows
+```
+
+## Light Helpers
+
+Visualize light positions and directions:
+
+```javascript
+// Directional light
+const helper = new THREE.DirectionalLightHelper(light, 5);
+scene.add(helper);
+
+// Point light
+const helper = new THREE.PointLightHelper(light, 1);
+scene.add(helper);
+
+// Spot light
+const helper = new THREE.SpotLightHelper(light);
+scene.add(helper);
+
+// Hemisphere light
+const helper = new THREE.HemisphereLightHelper(light, 5);
+scene.add(helper);
+
+// RectArea light
+import { RectAreaLightHelper } from 'three/addons/helpers/RectAreaLightHelper.js';
+const helper = new RectAreaLightHelper(light);
+light.add(helper);
+```
+
+## Light Intensity & Units
+
+```javascript
+// Intensity values depend on physically-based rendering:
+// - Lower values (0.1-1) for ambient/hemisphere
+// - Higher values (1-10) for directional/point/spot
+// - Very high (10-100+) for small area lights
+
+// Physical light units (optional)
+renderer.physicallyCorrectLights = true; // deprecated in newer versions
+// Use intensity in candelas (cd) for point/spot lights
+```
+
+## Performance Tips
+
+- Limit number of lights (3-5 for good performance)
+- Use ambient + 1-2 directional lights for outdoor scenes
+- Bake lighting into textures for static scenes
+- Use lightmaps for complex static lighting
+- Shadows are expensive - use selectively
+- Lower shadow map resolution for better performance