threejs-lights

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to use this skill

何时使用此技能

ALWAYS use this skill when the user mentions:

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

IMPORTANT: lights vs loaders vs node-tsl

Topic	Skill
Light classes and shadows	threejs-lights
Loading IES/HDR files	threejs-loaders
LightNode / TSL lighting	threejs-node-tsl

Trigger phrases include:

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

当用户提及以下内容时，务必使用此技能：

启用
```
castShadow
```
/
```
receiveShadow
```
、阴影贴图尺寸、偏移（bias）、法线偏移（normal bias）、阴影投射器的相机视锥体
物理灯光：强度、距离/衰减、聚光灯的角度/半影、面光源设置
用于辐照度式探针的
```
LightProbe
```
；带 IES 数据的
```
IESSpotLight
```

重要提示：灯光 vs 加载器 vs node-tsl

主题	对应技能
灯光类与阴影	threejs-lights
加载 IES/HDR 文件	threejs-loaders
LightNode / TSL 灯光	threejs-node-tsl

触发短语包括：

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

How to use this skill

如何使用此技能

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

See examples/workflow-directional-shadow.md.

基础配方：环境光/半球光补光 + 平行光模拟太阳光 + 局部点光源/聚光灯。
阴影：在渲染器上启用阴影，标记投射/接收对象，权衡贴图尺寸与性能，调整偏移以消除阴影痤疮（acne）与彼得潘效应（peter-panning）。
面光源（RectArea）：使用该灯光类型前，需按照文档页面初始化附加库。
探针：放置探针；适用时通过附加生成器生成数据；关联材质环境反射（threejs-materials、threejs-textures）。
IES：通过加载器技能加载配置文件，按照文档挂载到
```
IESSpotLight
```
。
性能优化：限制投射阴影的灯光数量；使用图层（threejs-objects）排除不需要的对象。

参见 examples/workflow-directional-shadow.md。

Doc map (official)

文档地图（官方）

Docs section	Representative links
Lights	https://threejs.org/docs/Light.html
Directional	https://threejs.org/docs/DirectionalLight.html
Spot	https://threejs.org/docs/SpotLight.html
Rect area	https://threejs.org/docs/RectAreaLight.html

文档板块	代表性链接
灯光	https://threejs.org/docs/Light.html
平行光	https://threejs.org/docs/DirectionalLight.html
聚光灯	https://threejs.org/docs/SpotLight.html
面光源	https://threejs.org/docs/RectAreaLight.html

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.

适用范围： 核心灯光、阴影贴图、探针，以及列出的面光源和探针生成相关附加组件。
不适用范围： CSM 深度理论（若用户提及可参见附加组件 Csm 文档）；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).

阴影贴图分辨率必须与场景比例匹配——大场景中的小阴影会显得块状感严重。
点光源阴影需要渲染六个面，性能开销大——请谨慎使用。
未引入必需库的
```
RectAreaLight
```
会导致渲染发黑或着色错误——请确认初始化是否正确。
物理单位（强度与曝光）与 threejs-renderers 色调映射不匹配会导致场景过曝或过暗。
阴影 bias / normalBias 的权衡：阴影痤疮与彼得潘效应——可借助视锥体辅助工具调试（threejs-helpers）。

Documentation and version

文档与版本

Light and shadow classes live under Lights in three.js docs.

RectAreaLight

and probe addons depend on extra init from Addons → Lights; IES profiles require threejs-loaders for file fetch before the light API is usable.

灯光与阴影类位于 three.js 文档的灯光板块下。

RectAreaLight

和探针附加组件需要从 Addons → Lights 中额外初始化；IES 配置文件需要通过 threejs-loaders 加载文件后，才能使用对应的灯光 API。

Agent response checklist

Agent 响应检查清单

When answering under this skill, prefer responses that:

Link the concrete light type (
```
DirectionalLight
```
,
```
SpotLight
```
, …) and shadow pages when shadows are on.
Separate IES loading to threejs-loaders and LightNode topics to threejs-node-tsl.
Give practical shadow map size / bias guidance with threejs-helpers for frustum visualization.
Mention
```
renderer.shadowMap.enabled
```
alongside light
```
castShadow
```
(see threejs-renderers).
Note performance cost of multiple shadow-casting lights.

在此技能下回答问题时，优先遵循以下要求：

当涉及阴影时，附上具体灯光类型（
```
DirectionalLight
```
、
```
SpotLight
```
等）和阴影相关文档页面的链接。
将 IES 加载 相关问题划分到 threejs-loaders，将 LightNode 相关主题划分到 threejs-node-tsl。
提供实用的阴影贴图尺寸/偏移调整指南，并推荐使用 threejs-helpers 进行视锥体可视化。
提及灯光
```
castShadow
```
的同时，也要提到
```
renderer.shadowMap.enabled
```
（参见 threejs-renderers）。
提示多个投射阴影的灯光带来的性能开销。

References

参考资料

Keywords

关键词

English: lights, shadows, directional, spotlight, rectarea, lightprobe, three.js

中文： 灯光、阴影、平行光、聚光灯、面光源、LightProbe、three.js

英文： lights, shadows, directional, spotlight, rectarea, lightprobe, three.js

中文： 灯光、阴影、平行光、聚光灯、面光源、LightProbe、three.js

能力边界

✅ 适用场景

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

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

⚠️ 需要注意

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

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

❌ 不适用场景

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

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

常见陷阱 (Gotchas)

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

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

使用流程

Step 1: 环境准备

确保开发环境已安装必要的依赖和工具。

Step 2: 配置初始化

根据项目需求进行基础配置。

Step 3: 核心功能使用

按照示例代码实现核心功能。

Step 4: 测试验证

运行测试确保功能正常。

Step 5: 部署上线

完成开发后进行部署和监控。