<Light/>

Light 让实体发光，照亮 Render。通过实体变换控制位置和方向，支持平行光、全向光和聚光灯。

用法

将 Light 挂到 Entity，即按实体姿态发光。

<Entity>
  <Light type="directional" intensity={10} />
</Entity>

演示

调整灯光属性 - 查看代码

代码

// ↑ imports hidden
export const LightExample = () => {
    const lightingProps = useControls(vars);

    return (
        <>
            {/* Light entity */}
            <Entity name="light" 
                position={lightingProps.type === 'directional' ? [0, 5, 0] : [0, 2, 0]}
                rotation={lightingProps.type === 'directional' ? [45, 0, 0] : [0, 0, 0]}
            >
                <Light {...lightingProps} />
            </Entity>

            {/* Box to show lighting */}
            <Entity position={[0, 0, 0]}>
                <Render type="box" />
            </Entity>

            {/* Sphere to show lighting */}
            <Entity position={[2, 0, 0]}>
                <Render type="sphere" />
            </Entity>

            {/* Cylinder to show lighting */}
            <Entity position={[-2, 0, 0]}>
                <Render type="cylinder" />
            </Entity>
        </>
    );
};

详见 LightComponent。

属性

名称	类型与说明	默认值
type	"directional" | "omni" | "spot" 光源类型。	"directional"
color?	string 设置或获取光源的 sRGB 颜色，忽略 Alpha，默认白色 [1, 1, 1]。更新颜色时使用 setter。	-
intensity?	number 设置或获取光源亮度，默认 1。	-
luminance?	number 设置或获取基于物理单位的亮度，仅在 scene.physicalUnits 为 true 时使用，默认 0。	-
shape?	number 设置或获取光源形状：LIGHTSHAPE_PUNCTUAL 为无限小点；LIGHTSHAPE_RECT 为矩形；LIGHTSHAPE_DISK 为圆盘；LIGHTSHAPE_SPHERE 为球体。默认 LIGHTSHAPE_PUNCTUAL。	-
affectSpecularity?	boolean 设置或获取此光源是否影响材质镜面反射。仅在 type 为 "directional" 时有效；其他类型会保留该值，之后改为平行光时应用。默认 true。	-
castShadows?	boolean 设置或获取是否投射阴影，默认 false。平行光只渲染视点到 LightComponent#shadowDistance 以内的阴影，默认距离 40。应按相机实际可见范围设置，否则超出距离后阴影消失。	-
shadowDistance?	number 设置或获取停止渲染阴影的视点距离，仅影响平行光，默认 40。	-
shadowIntensity?	number 设置或获取阴影变暗强度。0 无效果，1 为全黑，默认 1。	-
volumetricScattering?	number 设置或获取光源对体积雾的贡献倍率，以独立调整散射强度，0 表示无贡献。仅用于点光源与聚光灯，且 CameraFrame 体积雾启用局部光源时有效，默认 1。	-
shadowResolution?	number 设置或获取阴影贴图尺寸，可用 64、128、256、512、1024、2048，默认 1024。	-
shadowBias?	number 设置或获取阴影贴图深度偏移，用于调整此光源的阴影表现。范围 0 到 1，默认 0.05。	-
numCascades?	number 设置或获取阴影级联数量，可为 1、2、3、4。默认 1，表示不使用级联。	-
cascadeBlend?	number 设置或获取级联阴影混合系数，范围 0 到 1，表示每级用于相邻级联混合的比例。默认 0，禁用级联混合和阴影距离处淡出。也会在阴影距离末尾按此比例渐变到完全受光，单级联同样有效，例如 0.1 表示最后 10% 距离内淡出。	-
bakeNumSamples?	number 设置或获取将此光源烘焙到光照贴图的采样数，默认 1，最大 255。	-
bakeArea?	number 设置或获取烘焙平行光软阴影边界所用区域的角尺寸，单位度，范围 0 到 180。要求 bake=true 且 type="directional"，默认 0。	-
cascadeDistribution?	number 设置或获取各阴影级联的视锥划分分布，仅在 numCascades 大于 1 时使用。范围 0 到 1，0 为线性，1 为对数，默认 0.5。较大值提高近处阴影分辨率。	-
normalOffsetBias?	number 设置或获取法线偏移深度偏差，范围 0 到 1，默认 0。	-
range?	number 设置或获取光源范围，仅影响点光源和聚光灯，默认 10。	-
innerConeAngle?	number 设置或获取聚光灯开始衰减的半角，单位度，从光源方向轴量到锥体边缘。完整内光束角为此值两倍，仅用于聚光灯。默认 40，即完整内角 80 度。	-
outerConeAngle?	number 设置或获取聚光灯完全衰减到零的半角，单位度，从方向轴量到锥体边缘。完整外光束角为此值两倍，仅用于聚光灯。默认 45，即完整外角 90 度。	-
falloffMode?	number 设置或获取光源衰减模式，控制随距离衰减的速度。LIGHTFALLOFF_LINEAR 为线性，LIGHTFALLOFF_INVERSESQUARED 为平方反比。仅用于点光源和聚光灯，默认 LIGHTFALLOFF_LINEAR。	-
shadowType?	number 设置或获取阴影类型，可选 SHADOW_PCF1_32F、SHADOW_PCF3_32F、SHADOW_PCF5_32F、SHADOW_PCF1_16F、SHADOW_PCF3_16F、SHADOW_PCF5_16F、SHADOW_VSM_16F、SHADOW_VSM_32F、SHADOW_PCSS_32F。默认 SHADOW_PCF3_32F。	-
vsmBlurSize?	number 设置或获取方差阴影贴图模糊采样数，仅支持 1 到 25 的奇数，偶数向上取到下一奇数。默认 11。	-
vsmBlurMode?	number 设置或获取方差阴影贴图模糊模式。BLUR_BOX 为盒式滤波，BLUR_GAUSSIAN 为高斯滤波，通常更平滑但需要更多采样。默认 BLUR_GAUSSIAN。	-
vsmBias?	number 设置或获取抑制方差阴影贴图自阴影条纹的偏移，范围 0 到 1，默认 0.0025。	-
cookieAsset?	number | null 设置或获取光源投影纹理的资源 ID，未设置时为 null。仅聚光灯与点光源支持，前者需要二维纹理，后者需要立方体贴图。默认 null。	-
cookie?	Texture | null 设置或获取光源投影纹理。仅聚光灯与点光源支持，前者需要二维纹理，后者需要立方体贴图。默认 null。	-
cookieIntensity?	number 设置或获取投影纹理强度，默认 1。	-
cookieFalloff?	boolean 设置或获取使用投影纹理时是否保留常规聚光灯角度衰减。false 时像纯纹理投影仪，仅随距离衰减。默认 true。	-
cookieChannel?	string 设置或获取投影纹理使用的颜色通道，可为 "r"、"g"、"b"、"a" 或 "rgb"，默认 "rgb"。	-
cookieAngle?	number 设置或获取聚光灯投影纹理旋转角度，单位度，默认 0。	-
cookieScale?	Vec2 | null 设置或获取聚光灯投影纹理缩放，null 表示不缩放，默认 null。	-
cookieOffset?	Vec2 | null 设置或获取聚光灯投影纹理位置偏移，默认 null。	-
shadowUpdateMode?	number 设置或获取阴影更新模式。SHADOWUPDATE_NONE 不渲染；SHADOWUPDATE_THISFRAME 只渲染一次后自动改为 NONE；SHADOWUPDATE_REALTIME 每帧渲染。默认 SHADOWUPDATE_REALTIME。	-
mask?	number 设置或获取决定此光源照亮哪些 MeshInstance 的位掩码，由 MASK_AFFECT_DYNAMIC、MASK_AFFECT_LIGHTMAPPED 和 MASK_BAKE 组合，仅使用低 8 位。affectDynamic、affectLightmapped、bake 辅助属性写入同一掩码，但各自保存状态，不会从 mask 重新计算；直接修改 mask 不会更新它们，后续写入辅助属性也可能覆盖 mask 设置。默认 MASK_AFFECT_DYNAMIC。	-
affectDynamic?	boolean 设置或获取是否影响未使用光照贴图的对象，切换 mask 的 MASK_AFFECT_DYNAMIC 位，默认 true。	-
affectLightmapped?	boolean 设置或获取是否影响已使用光照贴图的对象，切换 MASK_AFFECT_LIGHTMAPPED 位。在 mask 中与 bake 互斥，启用一个会清除另一个位。默认 false。	-
bake?	boolean 设置或获取是否将此光源烘焙进光照贴图，切换 MASK_BAKE 位。在 mask 中与 affectLightmapped 互斥，启用一个会清除另一个位。默认 false。	-
bakeDir?	boolean 设置或获取光源方向是否参与方向光照贴图。要求光源启用且 bake=true。方向贴图每像素只保存一个近似方向，多个 bakeDir=true 光源相交时可能使交叠区镜面反射或凹凸映射异常，是否明显取决于场景。默认 true。	-
isStatic?	boolean 设置或获取光源是否始终不移动，用于优化提示，默认 false。	-
layers?	readonly number[] 设置或获取光源所属图层 ID 数组（Layer#id），默认 [LAYERID_WORLD]。不要直接 push、pop、splice 或修改数组，应赋入新数组。	-
shadowUpdateOverrides?	number[] | null 设置或获取各阴影级联的 SHADOWUPDATE_ 配置数组，不使用时设为 null，默认 null。	-
shadowSamples?	number 设置或获取 SHADOW_PCSS_32F 软阴影的阴影采样数，必须是从 1 开始的正整数。越高越平滑，但可能显著降低性能，默认 16。	-
shadowBlockerSamples?	number 设置或获取 SHADOW_PCSS_32F 接触硬化阴影的遮挡物采样数，用于估计投射者与接收者距离。必须为非负整数，值越高质量越好但性能越低。0 禁用接触硬化，使柔度恒定。默认 16，可低于 shadowSamples 以优化性能，通常不会明显影响质量。	-
penumbraSize?	number 设置或获取接触硬化阴影半影尺寸。面光源中作为尺寸倍率，点状光源和平行光中表示光源区域大小。默认 1。	-
penumbraFalloff?	number 设置或获取接触硬化阴影半影衰减率，必须大于等于 1。控制阴影随距离变软的速度，值越大变软越快，较小值过渡更缓。默认 1。	-
system?	ComponentSystem 创建此组件的 ComponentSystem。	-
entity?	Entity 此组件挂载的 Entity。	-
enabled?	boolean 设置或获取组件的启用状态。	-