threejs-lights

何时使用此技能

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

• 启用 castShadow / receiveShadow、阴影贴图尺寸、偏差、法线偏差、阴影投射物的相机视锥体
• 物理光源：强度、距离/衰减、聚光灯的角度/半影、矩形面光源设置
• 用于辐照度探针的 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”

如何使用此技能

1. 基础方案： 环境光/半球光补光 + 平行光太阳光 + 局部点光源/聚光灯。
2. 阴影： 在渲染器上启用阴影，标记投射物/接收物，权衡贴图尺寸与性能，并调整偏差以消除阴影痤疮/悬浮。
3. RectArea： 使用此类光源前，按照文档页面的说明初始化附加库。
4. 探针： 放置探针；适用时使用附加生成器生成数据；并关联到材质环境反射（threejs-materials、threejs-textures）。
5. IES： 使用加载器技能加载配置文件，并按照文档将其附加到 IESSpotLight。
6. 性能： 限制投射阴影的光源数量；使用图层（threejs-objects）排除对象。

请参阅 examples/workflow-directional-shadow.md。

文档索引（官方）

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

范围

• 涵盖范围： 核心灯光、阴影贴图、探针、矩形面光源和探针生成所列出的附加组件。
• 不涵盖范围： CSM 深入理论（用户提及时请参阅附加组件 Csm 文档）；DCC 中烘焙的光照贴图。

常见问题和最佳实践

• 阴影贴图分辨率必须与场景规模相匹配——在广阔的世界中，微小的阴影会显得块状。
• 点光源阴影需要六个面，开销很大——请谨慎使用。
• 未加载所需库的 RectAreaLight 会产生黑色或错误的着色效果——请确认已正确初始化。
• 物理单位（强度与曝光）不匹配时，配合 threejs-renderers 色调映射会导致场景过曝或过暗。
• 阴影 bias / normalBias 需要权衡：阴影痤疮 vs 阴影悬浮——请使用辅助视锥体（threejs-helpers）进行调节。

文档和版本

灯光和阴影类位于 three.js 文档的 Lights 下。RectAreaLight 和探针附加组件需要从 Addons → Lights 执行额外初始化；IES 配置文件需要通过 threejs-loaders 获取文件，之后才能使用灯光 API。

Agent 回复检查清单

使用此技能回答时，优先做到：

1. 在启用阴影时，链接具体的灯光类型（DirectionalLight、SpotLight 等）和阴影文档页面。
2. 将 IES 加载归入 threejs-loaders，将 LightNode 主题归入 threejs-node-tsl。
3. 提供实用的阴影贴图尺寸/偏差建议，并使用 threejs-helpers 可视化视锥体。
4. 除灯光的 castShadow 外，也提及 renderer.shadowMap.enabled（参见 threejs-renderers）。
5. 说明多个投射阴影的光源会带来的性能开销。

参考资料

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

关键词

英文： 灯光、阴影、平行光、聚光灯、矩形面光源、光照探针、three.js

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