Skip to main content 首页 创作者 afovea game-dev-skills threejs-lighting
threejs-lighting Three.js lighting — 6 light types (Ambient, Directional, Point, Spot, Hemisphere, RectArea), shadow configuration, PCSS/PCFSoft shadow maps, environment map lighting via HDR and PMREMGenerator, 3-point studio setup, LightProbe, and performance rules. Use when setting up scene lighting, configuring shadows, loading HDR environments, or optimising light count for mobile. Adapted from CloudAI-X/threejs-skills (MIT).
跳到安装 Skills Marketplace 发现并探索由社区构建的 Agent Skills
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/afovea/game-dev-skills --skill threejs-lighting命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
下载 Zip 下载中... 同仓库更多 Skills Art Director persona for visual style, pillars, art bible, cross-discipline visual consistency, art critique, and art QA. Use when a task needs visual direction, style enforcement, or cohesion across concept, environment, character, VFX, and lighting.
Audio Director persona for sound design, music direction, mix, audio implementation patterns, and audio pipeline. Use when a task needs reasoning about audio intent, audio-mechanic integration, mix balance, or the audio toolchain.
Post-pipeline cleanup and verification pass for game-development work. Regenerate / re-bake any derived content, rebuild the project, verify the editor / engine opens cleanly, run automated test suites, take a perf snapshot against budgets, and confirm save / network / cert / pipeline surfaces are untouched (or correctly versioned) against the pre-run baseline.
name threejs-lighting description Three.js lighting — 6 light types (Ambient, Directional, Point, Spot, Hemisphere, RectArea), shadow configuration, PCSS/PCFSoft shadow maps, environment map lighting via HDR and PMREMGenerator, 3-point studio setup, LightProbe, and performance rules. Use when setting up scene lighting, configuring shadows, loading HDR environments, or optimising light count for mobile. Adapted from CloudAI-X/threejs-skills (MIT). license MIT compatibility Portable reference skill for agents that support markdown skills or prompt files. Works best alongside project Three.js source files and renderer shadow/light count profiling. disable-model-invocation true metadata {"owner":"game-delivery","version":"2.0.0","language":"en-GB","category":"web-rendering","upstream_references":["https://github.com/CloudAI-X/threejs-skills (MIT — see NOTICE.md)"],"tags":["three-js","lighting","shadows","environment-maps","hdr","pmrem","ambient-light","directional-light","point-light","spot-light","hemisphere-light","rect-area-light"],"intents":["light-selection","shadow-configuration","environment-lighting","studio-setup","light-budget"],"output_types":["code-example","api-reference","lighting-plan"]}
Three.js Lighting
Quick Start
import * as THREE from 'three' ;
const scene = new THREE .Scene ();
const ambient = new THREE .AmbientLight (0xffffff , 0.4 );
scene.add (ambient);
const sun = new THREE .DirectionalLight (0xffffff , 1.0 );
sun.position .set (5 , 10 , 5 );
sun.castShadow = true ;
scene.add (sun);
renderer.shadowMap .enabled = true ;
renderer.shadowMap .type = THREE .PCFSoftShadowMap ;
mesh.castShadow = true ;
mesh.receiveShadow = true ;
Light Types
AmbientLight — Uniform Fill
No position, no shadows. Adds flat, directionless light to every surface equally.
const ambient = new
THREE
AmbientLight
0xffffff
0.4
add
Use as a low-intensity fill to prevent pure-black shadows. Never as the sole light source.
HemisphereLight — Sky/Ground Gradient Simulates outdoor bounce light from sky above and ground below.
const hemi = new THREE .HemisphereLight (
0x87ceeb ,
0x4a4a2a ,
0.6 ,
);
scene.add (hemi);
Good outdoor ambient substitute — more natural than AmbientLight. No shadows.
DirectionalLight — Sun Parallel rays from infinity. Best for outdoor sun/moon. Supports shadows.
const dirLight = new THREE .DirectionalLight (0xfff5e0 , 1.2 );
dirLight.position .set (10 , 20 , 10 );
dirLight.target .position .set (0 , 0 , 0 );
scene.add (dirLight);
scene.add (dirLight.target );
dirLight.castShadow = true ;
dirLight.shadow .mapSize .width = 2048 ;
dirLight.shadow .mapSize .height = 2048 ;
dirLight.shadow .camera .near = 0.5 ;
dirLight.shadow .camera .far = 100 ;
dirLight.shadow .camera .left = -20 ;
dirLight.shadow .camera .right = 20 ;
dirLight.shadow .camera .top = 20 ;
dirLight.shadow .camera .bottom = -20 ;
dirLight.shadow .bias = -0.001 ;
dirLight.shadow .normalBias = 0.02 ;
Visualise the shadow frustum during development:
import { CameraHelper } from 'three' ;
const shadowHelper = new CameraHelper (dirLight.shadow .camera );
scene.add (shadowHelper);
PointLight — Omni Light (Bulb) Radiates in all directions from a single point. Supports shadows (expensive — 6 shadow maps).
const point = new THREE .PointLight (
0xff8844 ,
2.0 ,
15 ,
2 ,
);
point.position .set (0 , 3 , 0 );
scene.add (point);
point.castShadow = true ;
point.shadow .mapSize .width = 512 ;
point.shadow .mapSize .height = 512 ;
point.shadow .camera .near = 0.1 ;
point.shadow .camera .far = 15 ;
SpotLight — Cone of Light Directional cone. Supports shadows with a single shadow map.
const spot = new THREE .SpotLight (
0xffffff ,
2.0 ,
30 ,
Math .PI / 6 ,
0.3 ,
2 ,
);
spot.position .set (0 , 8 , 0 );
spot.target .position .set (0 , 0 , 0 );
scene.add (spot);
scene.add (spot.target );
spot.castShadow = true ;
spot.shadow .mapSize .width = 1024 ;
spot.shadow .mapSize .height = 1024 ;
spot.shadow .camera .near = 1 ;
spot.shadow .camera .far = 30 ;
spot.shadow .focus = 1 ;
RectAreaLight — Area Light (Softbox) Rectangular emitter for studio/interior looks. No real-time shadows — bake or use PointLight fallback.
import { RectAreaLightHelper } from 'three/addons/helpers/RectAreaLightHelper.js' ;
import { RectAreaLightUniformsLib } from 'three/addons/lights/RectAreaLightUniformsLib.js' ;
RectAreaLightUniformsLib .init ();
const rectLight = new THREE .RectAreaLight (
0xffffff ,
5 ,
4 ,
4 ,
);
rectLight.position .set (0 , 5 , 0 );
rectLight.lookAt (0 , 0 , 0 );
scene.add (rectLight);
scene.add (new RectAreaLightHelper (rectLight));
Only works with MeshStandardMaterial and MeshPhysicalMaterial.
Shadow Configuration
Shadow Map Types renderer.shadowMap .enabled = true ;
renderer.shadowMap .type = THREE .PCFSoftShadowMap ;
Tuning Shadow Quality
light.shadow .mapSize .set (2048 , 2048 );
light.shadow .bias = -0.001 ;
light.shadow .normalBias = 0.02 ;
light.shadow .camera .left = -10 ;
light.shadow .camera .right = 10 ;
light.shadow .camera .top = 10 ;
light.shadow .camera .bottom = -10 ;
light.shadow .camera .updateProjectionMatrix ();
Selective Shadows
mesh.castShadow = true ;
mesh.receiveShadow = true ;
groundPlane.castShadow = false ;
groundPlane.receiveShadow = true ;
Environment Map Lighting
Equirectangular HDR (Recommended) import { RGBELoader } from 'three/addons/loaders/RGBELoader.js' ;
import { PMREMGenerator } from 'three' ;
const pmrem = new PMREMGenerator (renderer);
pmrem.compileEquirectangularShader ();
new RGBELoader ().load ('studio.hdr' , hdrTexture =>const envMap = pmrem.fromEquirectangular (hdrTexture).texture ;
scene.environment = envMap;
scene.background = envMap;
hdrTexture.dispose ();
pmrem.dispose ();
});
Cube Texture (Legacy) const cubeLoader = new THREE .CubeTextureLoader ();
const envMap = cubeLoader.load ([
'px.jpg' , 'nx.jpg' ,
'py.jpg' , 'ny.jpg' ,
'pz.jpg' , 'nz.jpg' ,
]);
scene.environment = envMap;
scene.background = envMap;
Apply Per-Material
material.envMap = envMap;
material.envMapIntensity = 1.5 ;
3-Point Studio Setup Classic lighting rig for character/product renders.
function createStudioLighting (scene ) {
const keyLight = new THREE .DirectionalLight (0xfff5e0 , 1.5 );
keyLight.position .set (3 , 4 , 3 );
keyLight.castShadow = true ;
keyLight.shadow .mapSize .set (1024 , 1024 );
scene.add (keyLight);
const fillLight = new THREE .DirectionalLight (0xe0f0ff , 0.4 );
fillLight.position .set (-3 , 2 , 2 );
scene.add (fillLight);
const rimLight = new THREE .DirectionalLight (0xffffff , 0.6 );
rimLight.position .set (0 , 3 , -4 );
scene.add (rimLight);
const ambient = new THREE .AmbientLight (0xffffff , 0.2 );
scene.add (ambient);
}
LightProbe — Baked Ambient from Environment Captures low-frequency ambient light from a cube render at runtime.
import { LightProbeGenerator } from 'three/addons/lights/LightProbeGenerator.js' ;
const cubeRenderTarget = new THREE .WebGLCubeRenderTarget (256 );
const cubeCamera = new THREE .CubeCamera (0.1 , 1000 , cubeRenderTarget);
scene.add (cubeCamera);
cubeCamera.update (renderer, scene);
const lightProbe = LightProbeGenerator .fromCubeRenderTarget (renderer, cubeRenderTarget);
scene.add (lightProbe);
Better quality than AmbientLight for scenes with a skybox — captures actual sky colour.
Light Helpers (Development) import { DirectionalLightHelper } from 'three' ;
import { PointLightHelper } from 'three' ;
import { SpotLightHelper } from 'three' ;
import { HemisphereLightHelper } from 'three' ;
import { RectAreaLightHelper } from 'three/addons/helpers/RectAreaLightHelper.js' ;
scene.add (new DirectionalLightHelper (dirLight, 2 ));
scene.add (new PointLightHelper (pointLight, 0.5 ));
scene.add (new SpotLightHelper (spotLight));
scene.add (new HemisphereLightHelper (hemiLight, 1 ));
spotHelper.update ();
Performance Tips
Limit shadow-casting lights — each adds a render pass. 1–2 maximum on mobileUse HemisphereLight instead of AmbientLight outdoors — more realistic for the same costDisable castShadow on small/distant objects — only the floor and large props need shadowsTight shadow camera frustum — shadow precision is proportional to frustum size; fit it to visible areaShadow map pooling — Three.js reuses shadow map textures; don't create lights dynamicallyUse environment maps for static PBR lighting — scene.environment + no dynamic lights is fastest
console .log ('Lights:' , renderer.info .programs );
const lightCount = scene.children .filter (c =>isLight ).length ;
See Also
threejs-fundamentals — scene setup and renderer configurationthreejs-materials — PBR material properties that interact with lightingthreejs-textures — HDR and environment map texture loadingthree-js-best-practices — shadow map budget and light count limits 