# Scene

Class · extends [`EventHandler`](https://api.playcanvas.com/engine/classes/EventHandler.md) · category: Graphics

Source: https://github.com/playcanvas/engine/blob/970d89f6d3bc6667f4e1f88153abd6e7e82ed52c/src/scene/scene.js#L56

A scene is a graphical representation of an environment. It manages the scene hierarchy, all
graphical objects, lights, and scene-wide properties.

Each application has one at [AppBase#scene](https://api.playcanvas.com/engine/classes/AppBase.md#scene). The scene owns the rendering setup that is
not tied to a single entity: the [layers](https://api.playcanvas.com/engine/classes/Scene.md#layers) composition that decides render order; the
lighting environment through [ambientLight](https://api.playcanvas.com/engine/classes/Scene.md#ambientlight), [skybox](https://api.playcanvas.com/engine/classes/Scene.md#skybox), [envAtlas](https://api.playcanvas.com/engine/classes/Scene.md#envatlas) and the
[sky](https://api.playcanvas.com/engine/classes/Scene.md#sky) and [lighting](https://api.playcanvas.com/engine/classes/Scene.md#lighting) parameter objects; [exposure](https://api.playcanvas.com/engine/classes/Scene.md#exposure), or [physicalUnits](https://api.playcanvas.com/engine/classes/Scene.md#physicalunits)
in its place, for overall brightness; the lightmapping settings; and the fog described below.

The scene fires `prerender` and `postrender` for each camera that renders it, and `precull`
and `postcull` around visibility culling. Per-frame work that needs to know the camera belongs
in those handlers.

Fog is scene-wide: [fog](https://api.playcanvas.com/engine/classes/Scene.md#fog) is a read-only [FogParams](https://api.playcanvas.com/engine/classes/FogParams.md) whose `type`, `color`, `start`
and `end` you set, and [CameraComponent#fog](https://api.playcanvas.com/engine/classes/CameraComponent.md#fog) can override it for a single camera.

**Example**

```ts
// Light the scene from a prefiltered environment and brighten it slightly
app.scene.envAtlas = envAtlasAsset.resource;
app.scene.skybox = skyboxAsset.resource;
app.scene.exposure = 1.2;
```

**Example**

```ts
// Run code for each camera just before it renders the scene
app.scene.on('prerender', (camera) => {
    // camera is the CameraComponent about to render
});
```

## Properties

### ambientBake

```ts
ambientBake: boolean = false
```

If enabled, the ambient lighting will be baked into lightmaps. This will be either the
[skybox](https://api.playcanvas.com/engine/classes/Scene.md#skybox) if set up, otherwise [ambientLight](https://api.playcanvas.com/engine/classes/Scene.md#ambientlight). Defaults to false.

### ambientBakeOcclusionBrightness

```ts
ambientBakeOcclusionBrightness: number = 0
```

If [ambientBake](https://api.playcanvas.com/engine/classes/Scene.md#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

```ts
ambientBakeOcclusionContrast: number = 0
```

If [ambientBake](https://api.playcanvas.com/engine/classes/Scene.md#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

```ts
ambientLight: Color
```

The color of the scene's ambient light, specified in sRGB color space. Defaults to black
(0, 0, 0).

### ambientLuminance

```ts
ambientLuminance: number = 0
```

The luminosity of the scene's ambient light in lux (lm/m^2). Used if physicalUnits is true. Defaults to 0.

### exposure

```ts
exposure: number = 1
```

The exposure value tweaks the overall brightness of the scene. Ignored if physicalUnits is true. Defaults to 1.

### lightmapFilterEnabled

```ts
lightmapFilterEnabled: boolean = false
```

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

```ts
lightmapHDR: boolean = false
```

Enables HDR lightmaps. This can result in smoother lightmaps especially when many samples
are used. Defaults to false.

### lightmapMaxResolution

```ts
lightmapMaxResolution: number = 2048
```

The maximum lightmap resolution. Defaults to 2048.

### lightmapMode

```ts
lightmapMode: number = BAKE_COLORDIR
```

The lightmap baking mode. Can be:

- [BAKE_COLOR](https://api.playcanvas.com/engine/variables/BAKE_COLOR.md): single color lightmap
- [BAKE_COLORDIR](https://api.playcanvas.com/engine/variables/BAKE_COLORDIR.md): 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](https://api.playcanvas.com/engine/variables/BAKE_COLORDIR.md).

### lightmapSizeMultiplier

```ts
lightmapSizeMultiplier: number = 1
```

The lightmap resolution multiplier. Defaults to 1.

### physicalUnits

```ts
physicalUnits: boolean = false
```

Use physically based units for cameras and lights. When used, the exposure value is ignored.

### root

```ts
root: Entity = null
```

The root entity of the scene, which is usually the only child to the [Application](https://api.playcanvas.com/engine/classes/Application.md)
root entity.

## Accessors

### ambientBakeNumSamples

```ts
get ambientBakeNumSamples(): number
set ambientBakeNumSamples(value: number)
```

Gets the number of samples used to bake the ambient light into the lightmap.

### ambientBakeSpherePart

```ts
get ambientBakeSpherePart(): number
set ambientBakeSpherePart(value: number)
```

Gets the part of the sphere which represents the source of ambient light.

### clusteredLightingEnabled

```ts
get clusteredLightingEnabled(): boolean
set clusteredLightingEnabled(value: boolean)
```

Gets whether clustered lighting is enabled.

### envAtlas

```ts
get envAtlas(): Texture | null
set envAtlas(value: Texture | null)
```

Gets the environment lighting atlas.

### fog

```ts
get fog(): FogParams
```

Gets the [FogParams](https://api.playcanvas.com/engine/classes/FogParams.md) that define fog parameters.

### gsplat

```ts
get gsplat(): GSplatParams
```

Gets the GSplat parameters.

### layers

```ts
get layers(): LayerComposition
set layers(layers: LayerComposition)
```

Gets the [LayerComposition](https://api.playcanvas.com/engine/classes/LayerComposition.md) that defines rendering order of this scene.

### lighting

```ts
get lighting(): LightingParams
```

Gets the [LightingParams](https://api.playcanvas.com/engine/classes/LightingParams.md) that define lighting parameters.

### lightmapFilterRange

```ts
get lightmapFilterRange(): number
set lightmapFilterRange(value: number)
```

Gets the range parameter of the bilateral filter.

### lightmapFilterSmoothness

```ts
get lightmapFilterSmoothness(): number
set lightmapFilterSmoothness(value: number)
```

Gets the spatial parameter of the bilateral filter.

### lightmapPixelFormat

```ts
get lightmapPixelFormat(): number
```

Gets the lightmap pixel format.

### prefilteredCubemaps

```ts
get prefilteredCubemaps(): Texture[]
set prefilteredCubemaps(value: Texture[])
```

Gets the 6 prefiltered cubemaps acting as the source of image-based lighting.

### sky

```ts
get sky(): Sky
```

Gets the [Sky](https://api.playcanvas.com/engine/classes/Sky.md) that defines sky properties.

### skybox

```ts
get skybox(): Texture | null
set skybox(value: Texture | null)
```

Gets the base cubemap texture used as the scene's skybox when skyboxMip is 0.

### skyboxHighlightMultiplier

```ts
get skyboxHighlightMultiplier(): number
set skyboxHighlightMultiplier(value: number)
```

Gets the highlight multiplied for the skybox.

### skyboxIntensity

```ts
get skyboxIntensity(): number
set skyboxIntensity(value: number)
```

Gets the multiplier for skybox intensity.

### skyboxLuminance

```ts
get skyboxLuminance(): number
set skyboxLuminance(value: number)
```

Gets the luminance (in lm/m^2) of the skybox.

### skyboxMip

```ts
get skyboxMip(): number
set skyboxMip(value: number)
```

Gets the mip level of the skybox to be displayed.

### skyboxRotation

```ts
get skyboxRotation(): Readonly<Quat>
set skyboxRotation(value: Readonly<Quat>)
```

Gets the rotation of the skybox to be displayed. Use the setter to update skybox state.

## Methods

### setSkybox

```ts
setSkybox(cubemaps?: Texture[]): void
```

Sets the cubemap for the scene skybox.

**Parameters**

- `cubemaps` ([`Texture`](https://api.playcanvas.com/engine/classes/Texture.md)`[]`, optional): An array of cubemaps corresponding to the skybox at
  different mip levels. If undefined, scene will remove skybox. Cubemap array should be of
  size 7, with the first element (index 0) corresponding to the base cubemap (mip level 0)
  with original resolution. Each remaining element (index 1-6) corresponds to a fixed
  prefiltered resolution (128x128, 64x64, 32x32, 16x16, 8x8, 4x4).

## Events

### EVENT_POSTCULL

```ts
static EVENT_POSTCULL: string = 'postcull'
```

Fired after mesh instance visibility culling is performed for a camera; mesh instance
visibility (such as [MeshInstance#visibleThisFrame](https://api.playcanvas.com/engine/classes/MeshInstance.md#visiblethisframe)) is up to date when this fires. The
handler is passed the [CameraComponent](https://api.playcanvas.com/engine/classes/CameraComponent.md) that was culled, or null when the culling is
internal (for example when culling shadow casters for a light's shadow map).

**Example**

```ts
app.scene.on('postcull', (camera) => {
   if (camera) {
       console.log(`Visibility culling was performed for camera ${camera.entity.name}`);
   }
});
```

### EVENT_POSTRENDER

```ts
static EVENT_POSTRENDER: string = 'postrender'
```

Fired when the camera renders the scene. The handler is passed the [CameraComponent](https://api.playcanvas.com/engine/classes/CameraComponent.md)
that rendered the scene.

**Example**

```ts
app.scene.on('postrender', (camera) => {
   console.log(`Camera ${camera.entity.name} rendered the scene`);
});
```

### EVENT_POSTRENDER_LAYER

```ts
static EVENT_POSTRENDER_LAYER: string = 'postrender:layer'
```

Fired when the camera renders a layer. The handler is passed the [CameraComponent](https://api.playcanvas.com/engine/classes/CameraComponent.md),
the [Layer](https://api.playcanvas.com/engine/classes/Layer.md) that will be rendered, and a boolean parameter set to true if the layer is
transparent. This is called during rendering to a render target or a default framebuffer, and
additional rendering can be performed here, for example using [QuadRender#render](https://api.playcanvas.com/engine/classes/QuadRender.md#render).

**Example**

```ts
app.scene.on('postrender:layer', (camera, layer, transparent) => {
   console.log(`Camera ${camera.entity.name} rendered the layer ${layer.name} (transparent: ${transparent})`);
});
```

### EVENT_PRECULL

```ts
static EVENT_PRECULL: string = 'precull'
```

Fired before mesh instance visibility culling is performed for a camera, just before the
camera's culling frustum is refreshed (so a handler may still adjust the camera). The handler
is passed the [CameraComponent](https://api.playcanvas.com/engine/classes/CameraComponent.md) being culled, or null when the culling is internal (for
example when culling shadow casters for a light's shadow map). Note that light visibility
culling happens earlier in the frame and is not bracketed by this event.

**Example**

```ts
app.scene.on('precull', (camera) => {
   if (camera) {
       console.log(`Visibility culling will be performed for camera ${camera.entity.name}`);
   }
});
```

### EVENT_PRERENDER

```ts
static EVENT_PRERENDER: string = 'prerender'
```

Fired before the camera renders the scene. The handler is passed the [CameraComponent](https://api.playcanvas.com/engine/classes/CameraComponent.md)
that will render the scene.

**Example**

```ts
app.scene.on('prerender', (camera) => {
   console.log(`Camera ${camera.entity.name} will render the scene`);
});
```

### EVENT_PRERENDER_LAYER

```ts
static EVENT_PRERENDER_LAYER: string = 'prerender:layer'
```

Fired before the camera renders a layer. The handler is passed the [CameraComponent](https://api.playcanvas.com/engine/classes/CameraComponent.md),
the [Layer](https://api.playcanvas.com/engine/classes/Layer.md) that will be rendered, and a boolean parameter set to true if the layer is
transparent. This is called during rendering to a render target or a default framebuffer, and
additional rendering can be performed here, for example using [QuadRender#render](https://api.playcanvas.com/engine/classes/QuadRender.md#render).

**Example**

```ts
app.scene.on('prerender:layer', (camera, layer, transparent) => {
   console.log(`Camera ${camera.entity.name} will render the layer ${layer.name} (transparent: ${transparent})`);
});
```

### EVENT_SETLAYERS

```ts
static EVENT_SETLAYERS: string = 'set:layers'
```

Fired when the layer composition is set. Use this event to add callbacks or advanced
properties to your layers. The handler is passed the old and the new
[LayerComposition](https://api.playcanvas.com/engine/classes/LayerComposition.md).

**Example**

```ts
app.scene.on('set:layers', (oldComp, newComp) => {
    const list = newComp.layerList;
    for (let i = 0; i < list.length; i++) {
        const layer = list[i];
        switch (layer.name) {
            case 'MyLayer':
                layer.onEnable = myOnEnableFunction;
                layer.onDisable = myOnDisableFunction;
                break;
            case 'MyOtherLayer':
                layer.clearColorBuffer = true;
                break;
        }
    }
});
```

### EVENT_SETSKYBOX

```ts
static EVENT_SETSKYBOX: string = 'set:skybox'
```

Fired when the skybox is set. The handler is passed the [Texture](https://api.playcanvas.com/engine/classes/Texture.md) that is the
previously used skybox cubemap texture. The new skybox cubemap texture is in the
[skybox](https://api.playcanvas.com/engine/classes/Scene.md#skybox) property.

**Example**

```ts
app.scene.on('set:skybox', (oldSkybox) => {
    console.log(`Skybox changed from ${oldSkybox.name} to ${app.scene.skybox.name}`);
});
```

## Inherited from [EventHandler](https://api.playcanvas.com/engine/classes/EventHandler.md)

- `fire(name: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any, arg6?: any, arg7?: any, arg8?: any): EventHandler`
- `hasEvent(name: string): boolean`
- `off(name?: string, callback?: HandleEventCallback, scope?: any): EventHandler`
- `on(name: string, callback: HandleEventCallback, scope?: any): EventHandle`
- `once(name: string, callback: HandleEventCallback, scope?: any): EventHandle`