Class: Scene
A scene is graphical representation of an environment. It manages the scene hierarchy, all graphical objects, lights, and scene-wide properties.
Extends
Properties
ambientBake
ambientBake: boolean = false
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
ambientBakeOcclusionBrightness: number = 0
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
ambientBakeOcclusionContrast: number = 0
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
ambientLight: Color
The color of the scene's ambient light, specified in sRGB color space. Defaults to black (0, 0, 0).
ambientLuminance
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
exposure: number = 1
The exposure value tweaks the overall brightness of the scene. Ignored if physicalUnits is true. Defaults to 1.
lightmapFilterEnabled
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
lightmapHDR: boolean = false
Enables HDR lightmaps. This can result in smoother lightmaps especially when many samples are used. Defaults to false.
lightmapMaxResolution
lightmapMaxResolution: number = 2048
The maximum lightmap resolution. Defaults to 2048.
lightmapMode
lightmapMode: number = BAKE_COLORDIR
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.
lightmapSizeMultiplier
lightmapSizeMultiplier: number = 1
The lightmap resolution multiplier. Defaults to 1.
physicalUnits
physicalUnits: boolean = false
Use physically based units for cameras and lights. When used, the exposure value is ignored.
root
root: Entity = null
The root entity of the scene, which is usually the only child to the Application root entity.
ambientBakeNumSamples
Get Signature
get ambientBakeNumSamples(): number
Gets the number of samples used to bake the ambient light into the lightmap.
Returns
number
Set Signature
set ambientBakeNumSamples(value: number): void
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.
Parameters
value
number
Returns
void
ambientBakeSpherePart
Get Signature
get ambientBakeSpherePart(): number
Gets the part of the sphere which represents the source of ambient light.
Returns
number
Set Signature
set ambientBakeSpherePart(value: number): void
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.
Parameters
value
number
Returns
void
clusteredLightingEnabled
Get Signature
get clusteredLightingEnabled(): boolean
Gets whether clustered lighting is enabled.
Returns
boolean
Set Signature
set clusteredLightingEnabled(value: boolean): void
Sets whether clustered lighting is enabled. Set to false before the first frame is rendered to use non-clustered lighting. Defaults to true.
Parameters
value
boolean
Returns
void
envAtlas
Get Signature
get envAtlas(): null | Texture
Gets the environment lighting atlas.
Returns
null | Texture
Set Signature
set envAtlas(value: null | Texture): void
Sets the environment lighting atlas.
Parameters
value
null | Texture
Returns
void
fog
Get Signature
get fog(): FogParams
Gets the FogParams that define fog parameters.
Returns
layers
Get Signature
get layers(): LayerComposition
Gets the LayerComposition that defines rendering order of this scene.
Returns
Set Signature
set layers(layers: LayerComposition): void
Sets the LayerComposition that defines rendering order of this scene.
Parameters
layers
Returns
void
lighting
Get Signature
get lighting(): LightingParams
Gets the LightingParams that define lighting parameters.
Returns
lightmapFilterRange
Get Signature
get lightmapFilterRange(): number
Gets the range parameter of the bilateral filter.
Returns
number
Set Signature
set lightmapFilterRange(value: number): void
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.
Parameters
value
number
Returns
void
lightmapFilterSmoothness
Get Signature
get lightmapFilterSmoothness(): number
Gets the spatial parameter of the bilateral filter.
Returns
number
Set Signature
set lightmapFilterSmoothness(value: number): void
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.
Parameters
value
number
Returns
void
lightmapPixelFormat
Get Signature
get lightmapPixelFormat(): number
Gets the lightmap pixel format.
Returns
number
prefilteredCubemaps
Get Signature
get prefilteredCubemaps(): Texture[]
Gets the 6 prefiltered cubemaps acting as the source of image-based lighting.
Returns
Set Signature
set prefilteredCubemaps(value: Texture[]): void
Sets the 6 prefiltered cubemaps acting as the source of image-based lighting.
Parameters
value
Returns
void
sky
Get Signature
get sky(): Sky
Gets the Sky that defines sky properties.
Returns
skybox
Get Signature
get skybox(): null | Texture
Gets the base cubemap texture used as the scene's skybox when skyboxMip is 0.
Returns
null | Texture
Set Signature
set skybox(value: null | Texture): void
Sets the base cubemap texture used as the scene's skybox when skyboxMip is 0. Defaults to null.
Parameters
value
null | Texture
Returns
void
skyboxHighlightMultiplier
Get Signature
get skyboxHighlightMultiplier(): number
Gets the highlight multiplied for the skybox.
Returns
number
Set Signature
set skyboxHighlightMultiplier(value: number): void
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.
Parameters
value
number
Returns
void
skyboxIntensity
Get Signature
get skyboxIntensity(): number
Gets the multiplier for skybox intensity.
Returns
number
Set Signature
set skyboxIntensity(value: number): void
Sets the multiplier for skybox intensity. Defaults to 1. Unused if physical units are used.
Parameters
value
number
Returns
void
skyboxLuminance
Get Signature
get skyboxLuminance(): number
Gets the luminance (in lm/m^2) of the skybox.
Returns
number
Set Signature
set skyboxLuminance(value: number): void
Sets the luminance (in lm/m^2) of the skybox. Defaults to 0. Only used if physical units are used.
Parameters
value
number
Returns
void
skyboxMip
Get Signature
get skyboxMip(): number
Gets the mip level of the skybox to be displayed.
Returns
number
Set Signature
set skyboxMip(value: number): void
Sets the mip level of the skybox to be displayed. Only valid for prefiltered cubemap skyboxes. Defaults to 0 (base level).
Parameters
value
number
Returns
void
skyboxRotation
Get Signature
get skyboxRotation(): Quat
Gets the rotation of the skybox to be displayed.
Returns
Set Signature
set skyboxRotation(value: Quat): void
Sets the rotation of the skybox to be displayed. Defaults to Quat.IDENTITY.
Parameters
value
Returns
void
Methods
fire()
fire(
name: string,
arg1?: any,
arg2?: any,
arg3?: any,
arg4?: any,
arg5?: any,
arg6?: any,
arg7?: any,
arg8?: any): EventHandler
Fire an event, all additional arguments are passed on to the event listener.
Parameters
name
string
Name of event to fire.
arg1?
any
First argument that is passed to the event handler.
arg2?
any
Second argument that is passed to the event handler.
arg3?
any
Third argument that is passed to the event handler.
arg4?
any
Fourth argument that is passed to the event handler.
arg5?
any
Fifth argument that is passed to the event handler.
arg6?
any
Sixth argument that is passed to the event handler.
arg7?
any
Seventh argument that is passed to the event handler.
arg8?
any
Eighth argument that is passed to the event handler.
Returns
Self for chaining.
Example
obj.fire('test', 'This is the message')
Inherited from
hasEvent()
hasEvent(name: string): boolean
Test if there are any handlers bound to an event name.
Parameters
name
string
The name of the event to test.
Returns
boolean
True if the object has handlers bound to the specified event name.
Example
obj.on('test', () => {}) // bind an event to 'test'
obj.hasEvent('test') // returns true
obj.hasEvent('hello') // returns false
Inherited from
off()
off(
name?: string,
callback?: HandleEventCallback,
scope?: any): EventHandler
Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.
Parameters
name?
string
Name of the event to unbind.
callback?
HandleEventCallback
Function to be unbound.
scope?
any
Scope that was used as the this when the event is fired.
Returns
Self for chaining.
Example
const handler = () => {}
obj.on('test', handler)
obj.off() // Removes all events
obj.off('test') // Removes all events called 'test'
obj.off('test', handler) // Removes all handler functions, called 'test'
obj.off('test', handler, this) // Removes all handler functions, called 'test' with scope this
Inherited from
on()
on(
name: string,
callback: HandleEventCallback,
scope?: any): EventHandle
Attach an event handler to an event.
Parameters
name
string
Name of the event to bind the callback to.
callback
HandleEventCallback
Function that is called when event is fired. Note the callback is limited to 8 arguments.
scope?
any = ...
Object to use as 'this' when the event is fired, defaults to current this.
Returns
Can be used for removing event in the future.
Examples
obj.on('test', (a, b) => {
console.log(a + b)
})
obj.fire('test', 1, 2) // prints 3 to the console
const evt = obj.on('test', (a, b) => {
console.log(a + b)
})
// some time later
evt.off()
Inherited from
once()
once(
name: string,
callback: HandleEventCallback,
scope?: any): EventHandle
Attach an event handler to an event. This handler will be removed after being fired once.
Parameters
name
string
Name of the event to bind the callback to.
callback
HandleEventCallback
Function that is called when event is fired. Note the callback is limited to 8 arguments.
scope?
any = ...
Object to use as 'this' when the event is fired, defaults to current this.
Returns
- can be used for removing event in the future.
Example
obj.once('test', (a, b) => {
console.log(a + b)
})
obj.fire('test', 1, 2) // prints 3 to the console
obj.fire('test', 1, 2) // not going to get handled
Inherited from
setSkybox()
setSkybox(cubemaps?: Texture[]): void
Sets the cubemap for the scene skybox.
Parameters
cubemaps?
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).
Returns
void
Events
EVENT_POSTCULL
static EVENT_POSTCULL: string = 'postcull';
Fired after visibility culling is performed for the camera.
Example
app.scene.on('postcull', (camera) => {
console.log(
`Visibility culling was performed for camera ${'${camera.entity.name}'}`
)
})
EVENT_POSTRENDER
static EVENT_POSTRENDER: string = 'postrender';
Fired when the camera renders the scene. The handler is passed the CameraComponent that rendered the scene.
Example
app.scene.on('postrender', (camera) => {
console.log(`Camera ${'${camera.entity.name}'} rendered the scene`)
})
EVENT_POSTRENDER_LAYER
static EVENT_POSTRENDER_LAYER: string = 'postrender:layer';
Fired when the camera renders a layer. The handler is passed the CameraComponent, the Layer 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.
Example
app.scene.on('postrender:layer', (camera, layer, transparent) => {
console.log(
`Camera ${'${camera.entity.name}'} rendered the layer ${'${layer.name}'} (transparent: ${'${transparent}'})`
)
})
EVENT_PRECULL
static EVENT_PRECULL: string = 'precull';
Fired before visibility culling is performed for the camera.
Example
app.scene.on('precull', (camera) => {
console.log(
`Visibility culling will be performed for camera ${'${camera.entity.name}'}`
)
})
EVENT_PRERENDER
static EVENT_PRERENDER: string = 'prerender';
Fired before the camera renders the scene. The handler is passed the CameraComponent that will render the scene.
Example
app.scene.on('prerender', (camera) => {
console.log(`Camera ${'${camera.entity.name}'} will render the scene`)
})
EVENT_PRERENDER_LAYER
static EVENT_PRERENDER_LAYER: string = 'prerender:layer';
Fired before the camera renders a layer. The handler is passed the CameraComponent, the Layer 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.
Example
app.scene.on('prerender:layer', (camera, layer, transparent) => {
console.log(
`Camera ${'${camera.entity.name}'} will render the layer ${'${layer.name}'} (transparent: ${'${transparent}'})`
)
})
EVENT_SETLAYERS
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.
Example
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
static EVENT_SETSKYBOX: string = 'set:skybox';
Fired when the skybox is set. The handler is passed the Texture that is the previously used skybox cubemap texture. The new skybox cubemap texture is in the Scene#skybox property.
Example
app.scene.on('set:skybox', (oldSkybox) => {
console.log(
`Skybox changed from ${'${oldSkybox.name}'} to ${'${app.scene.skybox.name}'}`
)
})