
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
cookie
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:
- SHADOW_PCF1_32F
- SHADOW_PCF3_32F
- SHADOW_PCF5_32F
- SHADOW_PCF1_16F
- SHADOW_PCF3_16F
- SHADOW_PCF5_16F
- SHADOW_VSM_16F
- SHADOW_VSM_32F
- SHADOW_PCSS_32F
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