|
| 1 | +--- |
| 2 | +title: Environment |
| 3 | +description: Documentation for the Environment component |
| 4 | +openGraph: |
| 5 | + title: playcanvas/react docs - Environment |
| 6 | + description: Documentation for @playcanvas/react |
| 7 | + images: |
| 8 | + - url: https://playcanvas-react.vercel.app/pc_react-og.png |
| 9 | + width: 1200 |
| 10 | + height: 630 |
| 11 | +--- |
| 12 | + |
| 13 | +# Environment |
| 14 | + |
| 15 | +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. |
| 16 | + |
| 17 | +## Overview |
| 18 | + |
| 19 | +The Environment component combines several PlayCanvas scene and sky properties into a single, easy-to-use component: |
| 20 | + |
| 21 | +- **Skybox**: Sets the background texture for the scene |
| 22 | +- **Environment Atlas**: Provides Image-Based Lighting (IBL) for realistic environmental reflections |
| 23 | +- **Sky Settings**: Controls sky dome properties, rotation, scale, and positioning |
| 24 | +- **Scene Settings**: Manages exposure, luminance, and other global lighting parameters |
| 25 | + |
| 26 | +## Usage |
| 27 | + |
| 28 | +The Environment component should be placed within an `<Application>` component. Only one Environment component should be used per application instance. |
| 29 | + |
| 30 | +### Basic Usage |
| 31 | + |
| 32 | +```jsx copy filename="environment-basic.jsx" |
| 33 | +import { Environment } from '@playcanvas/react/components' |
| 34 | +import { useAsset } from '@playcanvas/react/hooks' |
| 35 | + |
| 36 | +const EnvironmentExample = () => { |
| 37 | + const skyboxAsset = useAsset('/skybox.jpg') |
| 38 | + const envAtlasAsset = useAsset('/env_atlas.png') |
| 39 | + |
| 40 | + return ( |
| 41 | + <Application> |
| 42 | + <Environment |
| 43 | + skybox={skyboxAsset} |
| 44 | + envAtlas={envAtlasAsset} |
| 45 | + exposure={1.2} |
| 46 | + /> |
| 47 | + {/* Your scene entities here */} |
| 48 | + </Application> |
| 49 | + ) |
| 50 | +} |
| 51 | +``` |
| 52 | + |
| 53 | +### Advanced Configuration |
| 54 | + |
| 55 | +```jsx copy filename="environment-advanced.jsx" |
| 56 | +import { Environment } from '@playcanvas/react/components' |
| 57 | +import { useAsset } from '@playcanvas/react/hooks' |
| 58 | + |
| 59 | +const AdvancedEnvironmentExample = () => { |
| 60 | + const skyboxAsset = useAsset('/skybox.jpg') |
| 61 | + const envAtlasAsset = useAsset('/env_atlas.png') |
| 62 | + |
| 63 | + return ( |
| 64 | + <Application> |
| 65 | + <Environment |
| 66 | + envAtlas={envAtlasAsset} |
| 67 | + skybox={skyboxAsset} |
| 68 | + |
| 69 | + // Environment lighting |
| 70 | + exposure={1.1} |
| 71 | + |
| 72 | + // Sky dome settings |
| 73 | + scale={[200, 200, 200]} |
| 74 | + position={[0, 50, 0]} |
| 75 | + center={[0, 0.05, 0]} |
| 76 | + rotation={[0, 45, 0]} |
| 77 | + type="dome" |
| 78 | + depthWrite={true} |
| 79 | + /> |
| 80 | + </Application> |
| 81 | + ) |
| 82 | +} |
| 83 | +``` |
| 84 | + |
| 85 | +## Important Notes |
| 86 | + |
| 87 | +- **Single Instance**: Only one `<Environment/>` component should be used per application instance. Multiple instances will cause warnings and only the first will be used. |
| 88 | +- **Asset Requirements**: The `skybox` and `envAtlas` props expect PlayCanvas Asset instances, typically loaded using the `useAsset` hook. |
| 89 | +- **Automatic Cleanup**: The component automatically restores default values when unmounted. |
| 90 | + |
| 91 | +## Props |
| 92 | + |
| 93 | +The following props are based on PlayCanvas version **<PcVersion />**. This documentation is automatically generated from the TypeScript types of the installed PlayCanvas package. |
| 94 | + |
| 95 | +<TSDoc |
| 96 | + code={`import type { Environment } from '@playcanvas/react/components' |
| 97 | +type $ = React.ComponentProps<typeof Environment> |
| 98 | +export default $`} |
| 99 | +/> |
0 commit comments