threejs-lights

When to use this skill

• Enabling

  castShadow

  /

  receiveShadow

  , shadow map size, bias, normal bias, camera frusta for shadow casters
• Physical lights: intensity, distance/decay, angle/penumbra for spots, rect area setup

• LightProbe

  for irradiance-style probes;

  IESSpotLight

  with IES data

• "DirectionalLight", "SpotLight", "RectAreaLight", "castShadow", "shadow map"
• "阴影", "点光源", "面光源", "LightProbe"

How to use this skill

1. Base recipe: ambient/hemisphere fill + directional sun + local points/spots.
2. Shadows: enable on renderer, mark casters/receivers, tune map size vs performance, adjust bias to remove acne/peter-panning.
3. RectArea: initialize addon libs per docs page before using light type.
4. Probes: place probes; generate data via addon generator when applicable; relate to materials env reflections (threejs-materials, threejs-textures).
5. IES: load profile via loader skill, attach to

   IESSpotLight

   per docs.
6. Performance: limit shadow-casting lights; use layers (threejs-objects) to exclude objects.

Doc map (official)

Scope

• In scope: Core lights, shadow maps, probes, listed addons for rect area and probe generation.
• Out of scope: CSM deep theory (see addon Csm docs if user names it); baked lightmaps in DCC.

Common pitfalls and best practices

• Shadow map resolution must match scene scale—tiny shadows on huge worlds look blocky.
• Point light shadows are six-face expensive—use wisely.

• RectAreaLight

  without required libs yields black or wrong shading—verify init.
• Mismatched physical units (intensity vs exposure) with threejs-renderers tone mapping causes blown or dim scenes.
• Shadow bias / normalBias trade-offs: acne vs peter-paning—tune with helper frusta (threejs-helpers).

Documentation and version

RectAreaLight

Agent response checklist

1. Link the concrete light type (

   DirectionalLight

   ,

   SpotLight

   , …) and shadow pages when shadows are on.
2. Separate IES loading to threejs-loaders and LightNode topics to threejs-node-tsl.
3. Give practical shadow map size / bias guidance with threejs-helpers for frustum visualization.
4. Mention

   renderer.shadowMap.enabled

   alongside light

   castShadow

   (see threejs-renderers).
5. Note performance cost of multiple shadow-casting lights.

References

• https://threejs.org/docs/#Lights
• https://threejs.org/docs/DirectionalLight.html
• https://threejs.org/docs/SpotLight.html
• https://threejs.org/docs/LightShadow.html

Keywords

能力边界

✅ 适用场景

• 当你需要使用此技能对应的技术栈时
• 当项目需要遵循最佳实践时
• 当需要快速上手或深入理解核心概念时

⚠️ 需要注意

• 复杂业务逻辑需要结合具体场景调整
• 性能优化需要根据实际数据量评估

❌ 不适用场景

• 不相关的技术栈或框架
• 需要完全自定义的特殊场景

常见陷阱 (Gotchas)

1. 版本兼容性：注意框架版本与依赖库的兼容性，不同版本 API 可能有差异
2. 配置文件格式：配置文件格式错误是最常见的问题，建议使用编辑器的语法检查
3. 环境变量：确保所有必要的环境变量已正确设置，敏感信息不要硬编码
4. 依赖冲突：多版本共存时注意依赖冲突，使用 lock 文件锁定版本
5. 性能陷阱：大数据量场景下注意性能优化，避免 N+1 查询等常见问题

使用流程

Step 1: 环境准备

Step 2: 配置初始化

Step 3: 核心功能使用

Step 4: 测试验证

Step 5: 部署上线