`<Environment/>`

Environment 配置场景天空盒、环境照明及其他全局效果。

它支持：

设置背景纹理。
提供基于图像的照明与真实环境反射。
控制天空穹顶旋转、缩放和位置。
管理曝光、亮度等全局参数。

用法

在 Application 内添加 Environment，并传入已加载 HDR 或环境图集。

提示

同场景只需一个 Environment，同 Application 下多个会警告。

加载 HDR 作为天空盒，可从 HDRI Haven 获取图像。

const EnvironmentExample = () => {
  const { asset: skybox } = useTexture('/env.hdr')

  return (
      <Environment skybox={skybox} />
      {/* The rest of your scene... */}
  )
}

它影响全场景，曝光等配置见属性。

也可创建带地面投影的穹顶，调整尺寸、位置和旋转。

演示
代码

environment-example.jsx
// ↑ imports hidden

export const EnvironmentExample = () => {
    const { exposure, environment } = useControls(vars)
    
    // Load the assets
    const { asset: lambo } = useModel('/assets/lambo.glb');
    const { asset: skybox } = useTexture(environment);
    
    if (!lambo || !skybox) return null;

    return (<>
        {/* Environment with controllable settings */}
        <Environment 
            type="dome"
            skybox={skybox}
            exposure={exposure}
            scale={[15, 15, 15]} 
            center={[0.0, 0.09, 0.0]} 
            rotation={[0, 290, 0]}
            showSkybox={true}
        />

        {/* Render the model */}
        <Entity name='lambo'>
            <Render asset={lambo} />
        </Entity>
    </>);
}

属性

名称	类型与说明	默认值
`device?`	`GraphicsDevice`	`-`
`scene?`	`Scene`	`-`
`centerArray?`	`Float32Array<ArrayBuffer>`	`-`
`projectedSkydomeCenterId?`	`ScopeId`	`-`
`type?`	`string` 设置或获取天空类型：SKYTYPE_INFINITE、SKYTYPE_BOX 或 SKYTYPE_DOME，默认 SKYTYPE_INFINITE。	`-`
`depthWrite?`	`boolean` 设置或获取天空是否写入深度，默认 false。非 SKYTYPE_INFINITE 的天空穹顶可在场景通道或深度预通道写入场景深度纹理，以供景深等后续效果使用。使用深度预通道时，Sky 图层必须排在作为预通道最后图层的 Depth 图层之前。	`-`
`fisheye?`	`number` 设置或获取天空鱼眼投影强度，范围 [0, 1]：0 为标准直线透视投影；大于 0 时桶形畸变逐渐增强，视野更广。仅支持 SKYTYPE_INFINITE，对穹顶、盒状天空和正交相机无效，默认 0。	`-`
`scale?`	`[number, number, number]` 天空的缩放。	`-`
`position?`	`[number, number, number]` 天空的位置。	`-`
`center?`	`[number, number, number]` 天空的中心。	`-`
`rotation?`	`[number, number, number]` 天空的旋转。	`-`
`showSkybox?`	`boolean` 是否显示天空盒。	`-`
`ambientBake?`	`boolean` 启用后将环境光烘焙到光照贴图。已设置天空盒时使用天空盒，否则使用 ambientLight。默认 false。	`-`
`ambientBakeOcclusionBrightness?`	`number` ambientBake 为 true 时，控制环境光遮蔽亮度，常用范围 -1 到 1。默认 0，表示不改变亮度。	`-`
`ambientBakeOcclusionContrast?`	`number` ambientBake 为 true 时，控制环境光遮蔽对比度，常用范围 -1 到 1。默认 0，表示不改变对比度。	`-`
`ambientLight?`	`Color` 场景环境光的 sRGB 颜色，默认为黑色 (0, 0, 0)。	`-`
`ambientLuminance?`	`number` 场景环境光照度，单位 lux（lm/m²），仅在 physicalUnits 为 true 时使用，默认 0。	`-`
`exposure?`	`number` 控制场景整体亮度的曝光值，physicalUnits 为 true 时忽略，默认 1。	`-`
`lightmapSizeMultiplier?`	`number` 光照贴图分辨率倍率，默认 1。	`-`
`lightmapMaxResolution?`	`number` 光照贴图最大分辨率，默认 2048。	`-`
`lightmapMode?`	`number` 光照贴图烘焙模式：BAKE_COLOR 为单张颜色贴图；BAKE_COLORDIR 为颜色贴图加主光方向，用于凹凸或镜面反射。仅 bakeDir=true 的光源参与主光方向生成。默认 BAKE_COLORDIR。	`-`
`lightmapFilterEnabled?`	`boolean` 为运行时烘焙的颜色光照贴图启用双边滤波，保留边缘的同时去除噪声和色带，默认 false。滤波在贴图图像空间进行，不跨越 UV 接缝，可能使接缝更明显；应平衡滤波强度与烘焙采样数以减少伪影。	`-`
`lightmapHDR?`	`boolean` 启用 HDR 光照贴图，采样数较多时尤其能使贴图更平滑，默认 false。	`-`
`root?`	`Entity` 场景根实体，通常是 Application 根实体的唯一子级。	`-`
`physicalUnits?`	`boolean` 相机与光源使用物理单位，启用后忽略 exposure。	`-`
`updateShaders?`	`boolean`	`-`
`immediate?`	`Immediate`	`-`
`ambientBakeNumSamples?`	`number` 设置或获取将环境光烘焙到光照贴图的采样数，仅在 ambientBake 为 true 时有效。默认 1，最大 255。	`-`
`ambientBakeSpherePart?`	`number` 设置或获取用作环境光源的球面比例，仅在 ambientBake 为 true 时有效。范围 0..1，表示从球顶向下取球面；0.5 为上半球，1 为完整球。默认 0.4，即较小的上半球，以减少烘焙采样需求。	`-`
`clusteredLightingEnabled?`	`boolean` 设置或获取是否启用聚类光照，默认 true。要使用非聚类光照，应在渲染第一帧前设为 false。	`-`
`layers?`	`LayerComposition` 设置或获取定义场景渲染顺序的 LayerComposition。	`-`
`lightmapFilterRange?`	`number` 设置或获取双边滤波的范围参数，仅在 lightmapFilterEnabled 启用时使用。值越大模糊范围越广，必须为正数，默认 10。	`-`
`lightmapFilterSmoothness?`	`number` 设置或获取双边滤波的空间参数，仅在 lightmapFilterEnabled 启用时使用。值越大，会混合差异更大的颜色，必须为正数，默认 0.2。	`-`
`prefilteredCubemaps?`	`Texture[]` 设置或获取作为基于图像光照来源的六张预过滤立方体贴图。	`-`
`skyboxIntensity?`	`number` 设置或获取天空盒强度倍率，默认 1。使用物理单位时忽略。	`-`
`skyboxLuminance?`	`number` 设置或获取天空盒亮度，单位 lm/m²，默认 0，仅在使用物理单位时生效。	`-`
`skyboxMip?`	`number` 设置或获取显示的天空盒 mip 层级，仅对预过滤立方体天空盒有效。默认 0，即基础层级。	`-`
`skyboxHighlightMultiplier?`	`number` 设置或获取天空盒高光倍率。HDR 天空盒最多表示亮度 64，超出部分被截断，太阳等极亮光源因此可能无法产生足够的 HDR 泛光。该倍率在截断后调整亮度，以增强强光源的泛光效果，默认 1。	`-`
`skyboxRotation?`	`Readonly<Quat>` 设置或获取天空盒旋转，默认 Quat.IDENTITY。更新天空盒状态时使用 setter。	`-`
`skybox?`	`Asset<string> \| null` 天空盒资源，用于设置环境天空盒。	`-`
`envAtlas?`	`Asset<string> \| null` 环境光照，用于设置环境照明。	`-`

用法​

属性​

用法

属性