Class LightComponent

The LightComponent enables an Entity to light the scene. There are three types of light:

directional: A global light that emits light in the direction of the negative y-axis of the owner entity. Emulates light sources that appear to be infinitely far away such as the sun. The owner entity's position is effectively ignored.
omni: A local light that emits light in all directions from the owner entity's position. Emulates candles, lamps, bulbs, etc.
spot: A local light that emits light similarly to an omni light but is bounded by a cone centered on the owner entity's negative y-axis. Emulates flashlights, spotlights, etc.

You should never need to use the LightComponent constructor directly. To add an LightComponent to an Entity, use Entity#addComponent:

const entity = new pc.Entity();
entity.addComponent('light', {
    type: 'omni',
    color: new pc.Color(1, 0, 0),
    intensity: 2
});

Once the LightComponent is added to the entity, you can access it via the light property:

entity.light.intensity = 3; // Set the intensity of the light

console.log(entity.light.intensity); // Get the intensity of the light

Relevant Engine API examples:

Hierarchy (View Summary)

Component
- LightComponent

Properties

entity

entity: Entity

The Entity that this Component is attached to.

system

system: ComponentSystem

The ComponentSystem used to create this Component.

Accessors

affectDynamic

get affectDynamic(): boolean
Gets whether the light will affect non-lightmapped objects.

Returns boolean
set affectDynamic(arg: boolean): void
Sets whether the light will affect non-lightmapped objects.
Parameters
- arg: boolean
Returns void

affectLightmapped

get affectLightmapped(): boolean
Gets whether the light will affect lightmapped objects.

Returns boolean
set affectLightmapped(arg: boolean): void
Sets whether the light will affect lightmapped objects.
Parameters
- arg: boolean
Returns void

affectSpecularity

get affectSpecularity(): boolean
Gets whether material specularity will be affected by this light.

Returns boolean
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 bake(): boolean
Gets whether the light will be rendered into lightmaps.

Returns boolean
set bake(arg: boolean): void
Sets whether the light will be rendered into lightmaps.
Parameters
- arg: boolean
Returns void

bakeArea

get bakeArea(): number
Gets the penumbra angle in degrees.

Returns number
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 bakeDir(): boolean
Gets whether the light's direction will contribute to directional lightmaps.

Returns boolean
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 bakeNumSamples(): number
Gets the number of samples used to bake this light into the lightmap.

Returns number
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 cascadeBlend(): number
Gets the blend factor for cascaded shadow maps.

Returns number
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 cascadeDistribution(): number
Gets the distribution of subdivision of the camera frustum for individual shadow cascades.

Returns number
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 castShadows(): boolean
Gets whether the light will cast shadows.

Returns boolean
set castShadows(arg: boolean): void
Sets whether the light will cast shadows. Defaults to false.
Parameters
- arg: boolean
Returns void

color

get color(): Color
Gets the color of the light.

Returns Color
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: Color
Returns void

get cookie(): null | Texture
Gets the texture to be used as the cookie for this light.

Returns null | Texture
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 cookieAngle(): number
Gets the angle for spotlight cookie rotation (in degrees).

Returns number
set cookieAngle(arg: number): void
Sets the angle for spotlight cookie rotation (in degrees).
Parameters
- arg: number
Returns void

cookieAsset

get cookieAsset(): null | number
Gets the texture asset to be used as the cookie for this light.

Returns null | number
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 cookieChannel(): string
Gets the color channels of the cookie texture to use.

Returns string
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 cookieFalloff(): boolean
Gets whether normal spotlight falloff is active when a cookie texture is set.

Returns boolean
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 cookieIntensity(): number
Gets the cookie texture intensity.

Returns number
set cookieIntensity(arg: number): void
Sets the cookie texture intensity. Defaults to 1.
Parameters
- arg: number
Returns void

cookieOffset

get cookieOffset(): null | Vec2
Gets the spotlight cookie position offset.

Returns null | Vec2
set cookieOffset(arg: null | Vec2): void
Sets the spotlight cookie position offset.
Parameters
- arg: null | Vec2
Returns void

cookieScale

get cookieScale(): null | Vec2
Gets the spotlight cookie scale.

Returns null | Vec2
set cookieScale(arg: null | Vec2): void
Sets the spotlight cookie scale.
Parameters
- arg: null | Vec2
Returns void

enabled

get enabled(): boolean
Gets the enabled state of the component.

Returns boolean
set enabled(arg: boolean): void
Sets the enabled state of the component.
Parameters
- arg: boolean
Returns void

falloffMode

get falloffMode(): number
Gets the fall off mode for the light.

Returns number
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 innerConeAngle(): number
Gets the angle at which the spotlight cone starts to fade off.

Returns number
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 intensity(): number
Gets the brightness of the light.

Returns number
set intensity(arg: number): void
Sets the brightness of the light. Defaults to 1.
Parameters
- arg: number
Returns void

isStatic

get isStatic(): boolean
Gets whether the light ever moves.

Returns boolean
set isStatic(arg: boolean): void
Sets whether the light ever moves. This is an optimization hint.
Parameters
- arg: boolean
Returns void

layers

get layers(): number[]
Gets the array of layer IDs (Layer#id) to which this light should belong.

Returns number[]
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 luminance(): number
Gets the physically-based luminance.

Returns number
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 mask(): number
Gets the mask to determine which MeshInstances are lit by this light.

Returns number
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 normalOffsetBias(): number
Gets the normal offset depth bias.

Returns number
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 numCascades(): number
Gets the number of shadow cascades.

Returns number
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 outerConeAngle(): number
Gets the angle at which the spotlight cone has faded to nothing.

Returns number
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 penumbraFalloff(): number
Gets the falloff rate for shadow penumbra for contact hardening shadows.

Returns number
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 penumbraSize(): number
Gets the size of penumbra for contact hardening shadows.

Returns number
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 range(): number
Gets the range of the light.

Returns number
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 shadowBias(): number
Get the depth bias for tuning the appearance of the shadow mapping generated by this light.

Returns number
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 shadowBlockerSamples(): number
Gets the number of blocker samples used for contact hardening shadows.

Returns number
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 shadowDistance(): number
Gets the distance from the viewpoint beyond which shadows are no longer rendered.

Returns number
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 shadowIntensity(): number
Gets the intensity of the shadow darkening.

Returns number
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 shadowResolution(): number
Gets the size of the texture used for the shadow map.

Returns number
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 shadowSamples(): number
Gets the number of shadow samples used for soft shadows.

Returns number
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 shadowType(): number
Gets the type of shadows being rendered by this light.

Returns number
set shadowType(arg: number): void
Sets the type of shadows being rendered by this light. Can be:
Parameters
- arg: number
Returns void

shadowUpdateMode

get shadowUpdateMode(): number
Gets the shadow update model.

Returns number
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 shadowUpdateOverrides(): null | number[]
Gets an array of SHADOWUPDATE_ settings per shadow cascade.

Returns null | number[]
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 shape(): number
Gets the light source shape.

Returns number
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 pc.LIGHTSHAPE_PUNCTUAL.
Parameters
- arg: number
Returns void

type

get type(): string
Gets the type of the light.

Returns string
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 vsmBias(): number
Gets the VSM bias value.

Returns number
set vsmBias(arg: number): void
Sets the VSM bias value.
Parameters
- arg: number
Returns void

vsmBlurMode

get vsmBlurMode(): number
Gets the blurring mode for variance shadow maps.

Returns number
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 vsmBlurSize(): number
Gets the number of samples used for blurring a variance shadow map.

Returns number
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.
- Optionalarg1: any
  First argument that is passed to the event handler.
- Optionalarg2: any
  Second argument that is passed to the event handler.
- Optionalarg3: any
  Third argument that is passed to the event handler.
- Optionalarg4: any
  Fourth argument that is passed to the event handler.
- Optionalarg5: any
  Fifth argument that is passed to the event handler.
- Optionalarg6: any
  Sixth argument that is passed to the event handler.
- Optionalarg7: any
  Seventh argument that is passed to the event handler.
- Optionalarg8: any
  Eighth argument that is passed to the event handler.
Returns EventHandler
Self for chaining.
Example
```
obj.fire('test', 'This is the message');
```

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
```

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
- Optionalname: string
  Name of the event to unbind.
- Optionalcallback: HandleEventCallback
  Function to be unbound.
- Optionalscope: any
  Scope that was used as the this when the event is fired.
Returns EventHandler
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
```

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.
- Optionalscope: any = ...
  Object to use as 'this' when the event is fired, defaults to current this.
Returns EventHandle
Can be used for removing event in the future.
Example
```
obj.on('test', (a, b) => {
    console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console
```
Example
```
const evt = obj.on('test', (a, b) => {
    console.log(a + b);
});
// some time later
evt.off();
```

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.
- Optionalscope: any = ...
  Object to use as 'this' when the event is fired, defaults to current this.
Returns EventHandle
- 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
```

Class LightComponent

Hierarchy (View Summary)

Index

Properties

Accessors

Methods

Properties

entity

system

Accessors

affectDynamic

Returns boolean

Parameters

Returns void

affectLightmapped

Returns boolean

Parameters

Returns void

affectSpecularity

Returns boolean

Parameters

Returns void

bake

Returns boolean

Parameters

Returns void

bakeArea

Returns number

Parameters

Returns void

bakeDir

Returns boolean

Parameters

Returns void

bakeNumSamples

Returns number

Parameters

Returns void

cascadeBlend

Returns number

Parameters

Returns void

cascadeDistribution

Returns number

Parameters

Returns void

castShadows

Returns boolean

Parameters

Returns void

color

Returns Color

Parameters

Returns void

cookie

Returns null | Texture

Parameters

Returns void

cookieAngle

Returns number

Parameters

Returns void

cookieAsset

Returns null | number

Parameters

Returns void

cookieChannel

Returns string

Parameters

Returns void

cookieFalloff

Returns boolean

Parameters

Returns void

cookieIntensity

Returns number

Parameters

Returns void

cookieOffset

Returns null | Vec2