Environment

The Environment component is used to configure the environment lighting and skybox for a scene. It provides a comprehensive way to set up atmospheric lighting, skyboxes, and environmental effects that affect the entire scene.

Overview

The Environment component combines several PlayCanvas scene and sky properties into a single, easy-to-use component:

Skybox: Sets the background texture for the scene
Environment Atlas: Provides Image-Based Lighting (IBL) for realistic environmental reflections
Sky Settings: Controls sky dome properties, rotation, scale, and positioning
Scene Settings: Manages exposure, luminance, and other global lighting parameters

Usage

The Environment component should be placed within an <Application> component. Only one Environment component should be used per application instance.

Basic Usage

environment-basic.jsx


import { Environment } from '@playcanvas/react/components'
import { useAsset } from '@playcanvas/react/hooks'
 
const EnvironmentExample = () => {
  const skyboxAsset = useAsset('/skybox.jpg')
  const envAtlasAsset = useAsset('/env_atlas.png')
 
  return (
    <Application>
      <Environment 
        skybox={skyboxAsset}
        envAtlas={envAtlasAsset}
        exposure={1.2}
      />
      {/* Your scene entities here */}
    </Application>
  )
}

Advanced Configuration

environment-advanced.jsx


import { Environment } from '@playcanvas/react/components'
import { useAsset } from '@playcanvas/react/hooks'
 
const AdvancedEnvironmentExample = () => {
  const skyboxAsset = useAsset('/skybox.jpg')
  const envAtlasAsset = useAsset('/env_atlas.png')
 
  return (
    <Application>
      <Environment 
        envAtlas={envAtlasAsset}
        skybox={skyboxAsset}
        
        // Environment lighting
        exposure={1.1}
        
        // Sky dome settings
        scale={[200, 200, 200]}
        position={[0, 50, 0]}
        center={[0, 0.05, 0]}
        rotation={[0, 45, 0]}
        type="dome"
        depthWrite={true}
      />
    </Application>
  )
}

Important Notes

Single Instance: Only one <Environment/> component should be used per application instance. Multiple instances will cause warnings and only the first will be used.
Asset Requirements: The skybox and envAtlas props expect PlayCanvas Asset instances, typically loaded using the useAsset hook.
Automatic Cleanup: The component automatically restores default values when unmounted.

Props

The following props are based on PlayCanvas version 2.11.8. This documentation is automatically generated from the TypeScript types of the installed PlayCanvas package.

Name	Type	Default
`skyMesh`	`SkyMesh \| null` The sky mesh of the scene.
`device`	`GraphicsDevice`
`scene`	`Scene`
`centerArray`	`Float32Array<ArrayBuffer>`
`projectedSkydomeCenterId`	`ScopeId`
`type`	`string` The type of the sky. One of the SKYMESH_* constants. Defaults to SKYTYPE_INFINITE. Can be: SKYTYPE_INFINITE SKYTYPE_BOX SKYTYPE_DOME
`depthWrite`	`boolean` Whether depth writing is enabled for the sky. Defaults to false. Writing a depth value for the skydome is supported when its type is not SKYTYPE_INFINITE. When enabled, the depth is written during a prepass render pass and can be utilized by subsequent passes to apply depth-based effects, such as Depth of Field. Note: For the skydome to be rendered during the prepass, the Sky Layer must be ordered before the Depth layer, which is the final layer used in the prepass. Returns whether depth writing is enabled for the sky.
`scale`	`[number, number, number]` The scale of the sky.
`position`	`[number, number, number]` The position of the sky.
`center`	`[number, number, number]` The center of the sky.
`rotation`	`[number, number, number]` The rotation of the sky.
`showSkybox`	`boolean` Whether to show the skybox.
`ambientBake`	`boolean` If enabled, the ambient lighting will be baked into lightmaps. This will be either the Scene#skybox if set up, otherwise Scene#ambientLight . Defaults to false.
`ambientBakeOcclusionBrightness`	`number` If Scene#ambientBake is true, this specifies the brightness of ambient occlusion. Typical range is -1 to 1. Defaults to 0, representing no change to brightness.
`ambientBakeOcclusionContrast`	`number` If Scene#ambientBake is true, this specifies the contrast of ambient occlusion. Typical range is -1 to 1. Defaults to 0, representing no change to contrast.
`ambientLight`	`Color` The color of the scene’s ambient light, specified in sRGB color space. Defaults to black (0, 0, 0).
`ambientLuminance`	`number` The luminosity of the scene’s ambient light in lux (lm/m^2). Used if physicalUnits is true. Defaults to 0.
`exposure`	`number` The exposure value tweaks the overall brightness of the scene. Ignored if physicalUnits is true. Defaults to 1.
`lightmapSizeMultiplier`	`number` The lightmap resolution multiplier. Defaults to 1.
`lightmapMaxResolution`	`number` The maximum lightmap resolution. Defaults to 2048.
`lightmapMode`	`number` The lightmap baking mode. Can be: BAKE_COLOR: single color lightmap BAKE_COLORDIR: single color lightmap + dominant light direction (used for bump or specular). Only lights with bakeDir=true will be used for generating the dominant light direction. Defaults to BAKE_COLORDIR.
`lightmapFilterEnabled`	`boolean` Enables bilateral filter on runtime baked color lightmaps, which removes the noise and banding while preserving the edges. Defaults to false. Note that the filtering takes place in the image space of the lightmap, and it does not filter across lightmap UV space seams, often making the seams more visible. It’s important to balance the strength of the filter with number of samples used for lightmap baking to limit the visible artifacts.
`lightmapHDR`	`boolean` Enables HDR lightmaps. This can result in smoother lightmaps especially when many samples are used. Defaults to false.
`root`	`Entity` The root entity of the scene, which is usually the only child to the Application root entity.
`physicalUnits`	`boolean` Use physically based units for cameras and lights. When used, the exposure value is ignored.
`forcePassThroughSpecular`	`boolean` Internal flag to indicate that the specular (and sheen) maps of standard materials should be assumed to be in a linear space, instead of sRGB. This is used by the editor using engine v2 internally to render in a style of engine v1, where spec those textures were specified as linear, while engine 2 assumes they are in sRGB space. This should be removed when the editor no longer supports engine v1 projects.
`updateShaders`	`boolean`
`immediate`	`Immediate`
`ambientBakeNumSamples`	`number` Sets the number of samples used to bake the ambient light into the lightmap. Note that Scene#ambientBake must be true for this to have an effect. Defaults to 1. Maximum value is 255. Gets the number of samples used to bake the ambient light into the lightmap.
`ambientBakeSpherePart`	`number` Sets the part of the sphere which represents the source of ambient light. Note that Scene#ambientBake must be true for this to have an effect. The valid range is 0..1, representing a part of the sphere from top to the bottom. A value of 0.5 represents the upper hemisphere. A value of 1 represents a full sphere. Defaults to 0.4, which is a smaller upper hemisphere as this requires fewer samples to bake. Gets the part of the sphere which represents the source of ambient light.
`clusteredLightingEnabled`	`boolean` Sets whether clustered lighting is enabled. Set to false before the first frame is rendered to use non-clustered lighting. Defaults to true. Gets whether clustered lighting is enabled.
`layers`	`LayerComposition` Sets the LayerComposition that defines rendering order of this scene. Gets the LayerComposition that defines rendering order of this scene.
`lightmapFilterRange`	`number` Sets the range parameter of the bilateral filter. It’s used when Scene#lightmapFilterEnabled is enabled. Larger value applies more widespread blur. This needs to be a positive non-zero value. Defaults to 10. Gets the range parameter of the bilateral filter.
`lightmapFilterSmoothness`	`number` Sets the spatial parameter of the bilateral filter. It’s used when Scene#lightmapFilterEnabled is enabled. Larger value blurs less similar colors. This needs to be a positive non-zero value. Defaults to 0.2. Gets the spatial parameter of the bilateral filter.
`prefilteredCubemaps`	`Texture[]` Sets the 6 prefiltered cubemaps acting as the source of image-based lighting. Gets the 6 prefiltered cubemaps acting as the source of image-based lighting.
`skyboxIntensity`	`number` Sets the multiplier for skybox intensity. Defaults to 1. Unused if physical units are used. Gets the multiplier for skybox intensity.
`skyboxLuminance`	`number` Sets the luminance (in lm/m^2) of the skybox. Defaults to 0. Only used if physical units are used. Gets the luminance (in lm/m^2) of the skybox.
`skyboxMip`	`number` Sets the mip level of the skybox to be displayed. Only valid for prefiltered cubemap skyboxes. Defaults to 0 (base level). Gets the mip level of the skybox to be displayed.
`skyboxHighlightMultiplier`	`number` Sets the highlight multiplier for the skybox. The HDR skybox can represent brightness levels up to a maximum of 64, with any values beyond this being clipped. This limitation prevents the accurate representation of extremely bright sources, such as the Sun, which can affect HDR bloom rendering by not producing enough bloom. The multiplier adjusts the brightness after clipping, enhancing the bloom effect for bright sources. Defaults to 1. Gets the highlight multiplied for the skybox.
`skyboxRotation`	`Quat` Sets the rotation of the skybox to be displayed. Defaults to Quat.IDENTITY. Gets the rotation of the skybox to be displayed.
`skybox`	`Asset \| null` The skybox asset. Used to set the skybox of the environment.
`envAtlas`	`Asset \| null` The environment lighting. Used to set the lighting of the environment.