V5

How To

Mirror Engine API

Mirror Engine API / LightComponent

Class: LightComponent

The Light Component enables the Entity to light the scene. There are three types of light: directional, omni and spot. Directional lights are global in that they are considered to be infinitely far away and light the entire scene. Omni and spot lights are local in that they have a position and a range. A spot light is a specialization of an omni light where light is emitted in a cone rather than in all directions. Lights also have the ability to cast shadows to add realism to your scenes.

// Add a LightComponent to an entity
const entity = new Entity()
entity.addComponent('light', {
  type: 'omni',
  color: new Color(1, 0, 0),
  range: 10
})

// Get the LightComponent on an entity
const lightComponent = entity.light

// Update a property on a light component
entity.light.range = 20

Extends

Component

Properties

entity

entity: Entity

The Entity that this Component is attached to.

Inherited from

Component.entity

system

system: ComponentSystem

The ComponentSystem used to create this Component.

Inherited from

Component.system

affectDynamic

Get Signature

get affectDynamic(): boolean

Gets whether the light will affect non-lightmapped objects.

Returns

boolean

Set Signature

set affectDynamic(arg: boolean): void

Sets whether the light will affect non-lightmapped objects.

Parameters

arg

boolean

Returns

void

affectLightmapped

Get Signature

get affectLightmapped(): boolean

Gets whether the light will affect lightmapped objects.

Returns

boolean

Set Signature

set affectLightmapped(arg: boolean): void

Sets whether the light will affect lightmapped objects.

Parameters

arg

boolean

Returns

void

affectSpecularity

Get Signature

get affectSpecularity(): boolean

Gets whether material specularity will be affected by this light.

Returns

boolean

Set Signature

set affectSpecularity(arg: boolean): void

Sets whether material specularity will be affected by this light. Ignored for lights other than LIGHTTYPE_DIRECTIONAL. Defaults to true.

Parameters

arg

boolean

Returns

void

bake

Get Signature

get bake(): boolean

Gets whether the light will be rendered into lightmaps.

Returns

boolean

Set Signature

set bake(arg: boolean): void

Sets whether the light will be rendered into lightmaps.

Parameters

arg

boolean

Returns

void

bakeArea

Get Signature

get bakeArea(): number

Gets the penumbra angle in degrees.

Returns

number

Set Signature

set bakeArea(arg: number): void

Sets the penumbra angle in degrees, allowing for a soft shadow boundary. Defaults to 0. Requires bake to be set to true and the light type is LIGHTTYPE_DIRECTIONAL.

Parameters

arg

number

Returns

void

bakeDir

Get Signature

get bakeDir(): boolean

Gets whether the light's direction will contribute to directional lightmaps.

Returns

boolean

Set Signature

set bakeDir(arg: boolean): void

Sets whether the light's direction will contribute to directional lightmaps. The light must be enabled and bake set to true. Be aware, that directional lightmap is an approximation and can only hold single direction per pixel. Intersecting multiple lights with bakeDir=true may lead to incorrect look of specular/bump-mapping in the area of intersection. The error is not always visible though, and highly scene-dependent.

Parameters

arg

boolean

Returns

void

bakeNumSamples

Get Signature

get bakeNumSamples(): number

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

Returns

number

Set Signature

set bakeNumSamples(arg: number): void

Sets the number of samples used to bake this light into the lightmap. Defaults to 1. Maximum value is 255.

Parameters

arg

number

Returns

void

cascadeBlend

Get Signature

get cascadeBlend(): number

Gets the blend factor for cascaded shadow maps.

Returns

number

Set Signature

set cascadeBlend(value: number): void

Sets the blend factor for cascaded shadow maps, defining the fraction of each cascade level used for blending between adjacent cascades. The value should be between 0 and 1, with a default of 0, which disables blending between cascades.

Parameters

value

number

Returns

void

cascadeDistribution

Get Signature

get cascadeDistribution(): number

Gets the distribution of subdivision of the camera frustum for individual shadow cascades.

Returns

number

Set Signature

set cascadeDistribution(arg: number): void

Sets the distribution of subdivision of the camera frustum for individual shadow cascades. Only used if LightComponent#numCascades is larger than 1. Can be a value in range of 0 and 1. Value of 0 represents a linear distribution, value of 1 represents a logarithmic distribution. Defaults to 0.5. Larger value increases the resolution of the shadows in the near distance.

Parameters

arg

number

Returns

void

castShadows

Get Signature

get castShadows(): boolean

Gets whether the light will cast shadows.

Returns

boolean

Set Signature

set castShadows(arg: boolean): void

Sets whether the light will cast shadows. Defaults to false.

Parameters

arg

boolean

Returns

void

color

Get Signature

get color(): Color

Gets the color of the light.

Returns

Set Signature

set color(arg: Color): void

Sets the color of the light. The alpha component of the color is ignored. Defaults to white ([1, 1, 1]).

Parameters

arg

Returns

void

Get Signature

get cookie(): null | Texture

Gets the texture to be used as the cookie for this light.

Returns

null | Texture

Set Signature

set cookie(arg: null | Texture): void

Sets the texture to be used as the cookie for this light. Only spot and omni lights can have cookies. Defaults to null.

Parameters

arg

null | Texture

Returns

void

cookieAngle

Get Signature

get cookieAngle(): number

Gets the angle for spotlight cookie rotation (in degrees).

Returns

number

Set Signature

set cookieAngle(arg: number): void

Sets the angle for spotlight cookie rotation (in degrees).

Parameters

arg

number

Returns

void

cookieAsset

Get Signature

get cookieAsset(): null | number

Gets the texture asset to be used as the cookie for this light.

Returns

null | number

Set Signature

set cookieAsset(arg: null | number): void

Sets the texture asset to be used as the cookie for this light. Only spot and omni lights can have cookies. Defaults to null.

Parameters

arg

null | number

Returns

void

cookieChannel

Get Signature

get cookieChannel(): string

Gets the color channels of the cookie texture to use.

Returns

string

Set Signature

set cookieChannel(arg: string): void

Sets the color channels of the cookie texture to use. Can be "r", "g", "b", "a", "rgb".

Parameters

arg

string

Returns

void

cookieFalloff

Get Signature

get cookieFalloff(): boolean

Gets whether normal spotlight falloff is active when a cookie texture is set.

Returns

boolean

Set Signature

set cookieFalloff(arg: boolean): void

Sets whether normal spotlight falloff is active when a cookie texture is set. When set to false, a spotlight will work like a pure texture projector (only fading with distance). Default is false.

Parameters

arg

boolean

Returns

void

cookieIntensity

Get Signature

get cookieIntensity(): number

Gets the cookie texture intensity.

Returns

number

Set Signature

set cookieIntensity(arg: number): void

Sets the cookie texture intensity. Defaults to 1.

Parameters

arg

number

Returns

void

cookieOffset

Get Signature

get cookieOffset(): null | Vec2

Gets the spotlight cookie position offset.

Returns

null | Vec2

Set Signature

set cookieOffset(arg: null | Vec2): void

Sets the spotlight cookie position offset.

Parameters

arg

null | Vec2

Returns

void

cookieScale

Get Signature

get cookieScale(): null | Vec2

Gets the spotlight cookie scale.

Returns

null | Vec2

Set Signature

set cookieScale(arg: null | Vec2): void

Sets the spotlight cookie scale.

Parameters

arg

null | Vec2

Returns

void

enabled

Get Signature

get enabled(): boolean

Gets the enabled state of the component.

Returns

boolean

Set Signature

set enabled(arg: boolean): void

Sets the enabled state of the component.

Parameters

arg

boolean

Returns

void

Overrides

Component.enabled

falloffMode

Get Signature

get falloffMode(): number

Gets the fall off mode for the light.

Returns

number

Set Signature

set falloffMode(arg: number): void

Sets the fall off mode for the light. This controls the rate at which a light attenuates from its position. Can be:

LIGHTFALLOFF_LINEAR: Linear.
LIGHTFALLOFF_INVERSESQUARED: Inverse squared.

Affects omni and spot lights only. Defaults to LIGHTFALLOFF_LINEAR.

Parameters

arg

number

Returns

void

innerConeAngle

Get Signature

get innerConeAngle(): number

Gets the angle at which the spotlight cone starts to fade off.

Returns

number

Set Signature

set innerConeAngle(arg: number): void

Sets the angle at which the spotlight cone starts to fade off. The angle is specified in degrees. Affects spot lights only. Defaults to 40.

Parameters

arg

number

Returns

void

intensity

Get Signature

get intensity(): number

Gets the brightness of the light.

Returns

number

Set Signature

set intensity(arg: number): void

Sets the brightness of the light. Defaults to 1.

Parameters

arg

number

Returns

void

isStatic

Get Signature

get isStatic(): boolean

Gets whether the light ever moves.

Returns

boolean

Set Signature

set isStatic(arg: boolean): void

Sets whether the light ever moves. This is an optimization hint.

Parameters

arg

boolean

Returns

void

layers

Get Signature

get layers(): number[]

Gets the array of layer IDs (Layer#id) to which this light should belong.

Returns

number[]

Set Signature

set layers(arg: number[]): void

Sets the array of layer IDs (Layer#id) to which this light should belong. Don't push/pop/splice or modify this array. If you want to change it, set a new one instead.

Parameters

arg

number[]

Returns

void

luminance

Get Signature

get luminance(): number

Gets the physically-based luminance.

Returns

number

Set Signature

set luminance(arg: number): void

Sets the physically-based luminance. Only used if scene.physicalUnits is true. Defaults to 0.

Parameters

arg

number

Returns

void

mask

Get Signature

get mask(): number

Gets the mask to determine which MeshInstances are lit by this light.

Returns

number

Set Signature

set mask(arg: number): void

Sets the mask to determine which MeshInstances are lit by this light. Defaults to 1.

Parameters

arg

number

Returns

void

normalOffsetBias

Get Signature

get normalOffsetBias(): number

Gets the normal offset depth bias.

Returns

number

Set Signature

set normalOffsetBias(arg: number): void

Sets the normal offset depth bias. Valid range is 0 to 1. Defaults to 0.

Parameters

arg

number

Returns

void

numCascades

Get Signature

get numCascades(): number

Gets the number of shadow cascades.

Returns

number

Set Signature

set numCascades(arg: number): void

Sets the number of shadow cascades. Can be 1, 2, 3 or 4. Defaults to 1, representing no cascades.

Parameters

arg

number

Returns

void

outerConeAngle

Get Signature

get outerConeAngle(): number

Gets the angle at which the spotlight cone has faded to nothing.

Returns

number

Set Signature

set outerConeAngle(arg: number): void

Sets the angle at which the spotlight cone has faded to nothing. The angle is specified in degrees. Affects spot lights only. Defaults to 45.

Parameters

arg

number

Returns

void

penumbraFalloff

Get Signature

get penumbraFalloff(): number

Gets the falloff rate for shadow penumbra for contact hardening shadows.

Returns

number

Set Signature

set penumbraFalloff(value: number): void

Sets the falloff rate for shadow penumbra for contact hardening shadows. This is a value larger than or equal to 1. This parameter determines how quickly the shadow softens with distance. Higher values result in a faster softening of the shadow, while lower values produce a more gradual transition. Defaults to 1.

Parameters

value

number

Returns

void

penumbraSize

Get Signature

get penumbraSize(): number

Gets the size of penumbra for contact hardening shadows.

Returns

number

Set Signature

set penumbraSize(value: number): void

Sets the size of penumbra for contact hardening shadows. For area lights, acts as a multiplier with the dimensions of the area light. For punctual and directional lights it's the area size of the light. Defaults to 1.

Parameters

value

number

Returns

void

range

Get Signature

get range(): number

Gets the range of the light.

Returns

number

Set Signature

set range(arg: number): void

Sets the range of the light. Affects omni and spot lights only. Defaults to 10.

Parameters

arg

number

Returns

void

shadowBias

Get Signature

get shadowBias(): number

Get the depth bias for tuning the appearance of the shadow mapping generated by this light.

Returns

number

Set Signature

set shadowBias(arg: number): void

Set the depth bias for tuning the appearance of the shadow mapping generated by this light. Valid range is 0 to 1. Defaults to 0.05.

Parameters

arg

number

Returns

void

shadowBlockerSamples

Get Signature

get shadowBlockerSamples(): number

Gets the number of blocker samples used for contact hardening shadows.

Returns

number

Set Signature

set shadowBlockerSamples(value: number): void

Sets the number of blocker samples used for soft shadows when the shadow type is SHADOW_PCSS_32F. These samples are used to estimate the distance between the shadow caster and the shadow receiver, which is then used for the estimation of contact hardening in the shadow. This value must be a positive whole number starting at 0. Higher values improve shadow quality by considering more occlusion points, but can decrease performance. When set to 0, contact hardening is disabled and the shadow has constant softness. Defaults to 16. Note that this values can be lower than shadowSamples to optimize performance, often without large impact on quality.

Parameters

value

number

Returns

void

shadowDistance

Get Signature

get shadowDistance(): number

Gets the distance from the viewpoint beyond which shadows are no longer rendered.

Returns

number

Set Signature

set shadowDistance(arg: number): void

Sets the distance from the viewpoint beyond which shadows are no longer rendered. Affects directional lights only. Defaults to 40.

Parameters

arg

number

Returns

void

shadowIntensity

Get Signature

get shadowIntensity(): number

Gets the intensity of the shadow darkening.

Returns

number

Set Signature

set shadowIntensity(arg: number): void

Sets the intensity of the shadow darkening. 0 having no effect and 1 meaning shadows are entirely black. Defaults to 1.

Parameters

arg

number

Returns

void

shadowResolution

Get Signature

get shadowResolution(): number

Gets the size of the texture used for the shadow map.

Returns

number

Set Signature

set shadowResolution(arg: number): void

Sets the size of the texture used for the shadow map. Valid sizes are 64, 128, 256, 512, 1024, 2048. Defaults to 1024.

Parameters

arg

number

Returns

void

shadowSamples

Get Signature

get shadowSamples(): number

Gets the number of shadow samples used for soft shadows.

Returns

number

Set Signature

set shadowSamples(value: number): void

Sets the number of shadow samples used for soft shadows when the shadow type is SHADOW_PCSS_32F. This value must be a positive whole number starting at 1. Higher values result in smoother shadows but can significantly decrease performance. Defaults to 16.

Parameters

value

number

Returns

void

shadowType

Get Signature

get shadowType(): number

Gets the type of shadows being rendered by this light.

Returns

number

Set Signature

set shadowType(arg: number): void

Sets the type of shadows being rendered by this light. Can be:

Parameters

arg

number

Returns

void

shadowUpdateMode

Get Signature

get shadowUpdateMode(): number

Gets the shadow update model.

Returns

number

Set Signature

set shadowUpdateMode(arg: number): void

Sets the shadow update model. This tells the renderer how often shadows must be updated for this light. Can be:

SHADOWUPDATE_NONE: Don't render shadows.
SHADOWUPDATE_THISFRAME: Render shadows only once (then automatically switches to SHADOWUPDATE_NONE.
SHADOWUPDATE_REALTIME: Render shadows every frame (default).

Parameters

arg

number

Returns

void

shadowUpdateOverrides

Get Signature

get shadowUpdateOverrides(): null | number[]

Gets an array of SHADOWUPDATE_ settings per shadow cascade.

Returns

null | number[]

Set Signature

set shadowUpdateOverrides(values: null | number[]): void

Sets an array of SHADOWUPDATE_ settings per shadow cascade. Set to undefined if not used.

Parameters

values

null | number[]

Returns

void

shape

Get Signature

get shape(): number

Gets the light source shape.

Returns

number

Set Signature

set shape(arg: number): void

Sets the light source shape. Can be:

LIGHTSHAPE_PUNCTUAL: Infinitesimally small point.
LIGHTSHAPE_RECT: Rectangle shape.
LIGHTSHAPE_DISK: Disk shape.
LIGHTSHAPE_SPHERE: Sphere shape.

Defaults to LIGHTSHAPE_PUNCTUAL.

Parameters

arg

number

Returns

void

type

Get Signature

get type(): string

Gets the type of the light.

Returns

string

Set Signature

set type(arg: string): void

Sets the type of the light. Can be:

"directional": A light that is infinitely far away and lights the entire scene from one direction.
"omni": An omni-directional light that illuminates in all directions from the light source.
"spot": An omni-directional light but is bounded by a cone.

Defaults to "directional".

Parameters

arg

string

Returns

void

vsmBias

Get Signature

get vsmBias(): number

Gets the VSM bias value.

Returns

number

Set Signature

set vsmBias(arg: number): void

Sets the VSM bias value.

Parameters

arg

number

Returns

void

vsmBlurMode

Get Signature

get vsmBlurMode(): number

Gets the blurring mode for variance shadow maps.

Returns

number

Set Signature

set vsmBlurMode(arg: number): void

Sets the blurring mode for variance shadow maps. Can be:

BLUR_BOX: Box filter.
BLUR_GAUSSIAN: Gaussian filter. May look smoother than box, but requires more samples.

Parameters

arg

number

Returns

void

vsmBlurSize

Get Signature

get vsmBlurSize(): number

Gets the number of samples used for blurring a variance shadow map.

Returns

number

Set Signature

set vsmBlurSize(arg: number): void

Sets the number of samples used for blurring a variance shadow map. Only uneven numbers work, even are incremented. Minimum value is 1, maximum is 25. Defaults to 11.

Parameters

arg

number

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

Component.fire

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

Component.hasEvent

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

Component.off

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

Component.on

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

Component.once