# LightComponent

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

Source: https://github.com/playcanvas/engine/blob/970d89f6d3bc6667f4e1f88153abd6e7e82ed52c/src/framework/components/light/component.js#L136

The LightComponent enables an [Entity](https://api.playcanvas.com/engine/classes/Entity.md) 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.

Directional and spot lights are therefore aimed with the owner entity's rotation, and shine along
its negative y-axis - so an unrotated light shines straight down. Note that
[GraphNode#lookAt](https://api.playcanvas.com/engine/classes/GraphNode.md#lookat) orients an entity's negative z-axis, which aims a camera but not a
light:

```javascript
// an unrotated light shines straight down
light.setEulerAngles(0, 0, 0);

// tilted 45 degrees, it shines down and towards negative z
light.setEulerAngles(45, 0, 0);

// to aim it at a target, lookAt orients the negative z-axis and the extra rotation brings the
// negative y-axis onto it
light.lookAt(target.getPosition());
light.rotateLocal(90, 0, 0);

// to aim it along a world space direction, rotate the negative y-axis onto that direction.
// Unlike lookAt, this is well defined even when the direction is straight up or down
const dir = new Vec3(-0.5, -1, -0.3).normalize();
light.setRotation(new Quat().setFromDirections(Vec3.DOWN, dir));

// the direction a light currently shines in is the negative of its world space up vector
const currentDir = light.up.clone().mulScalar(-1);
```

You should never need to use the LightComponent constructor directly. To add a LightComponent
to an [Entity](https://api.playcanvas.com/engine/classes/Entity.md), use [Entity#addComponent](https://api.playcanvas.com/engine/classes/Entity.md#addcomponent):

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

Once the LightComponent is added to the entity, you can access it via the [Entity#light](https://api.playcanvas.com/engine/classes/Entity.md#light)
property:

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

- [Area Lights](https://playcanvas.github.io/#/graphics/area-lights)
- [Clustered Area Lights](https://playcanvas.github.io/#/graphics/clustered-area-lights)
- [Clustered Lighting](https://playcanvas.github.io/#/graphics/clustered-lighting)
- [Clustered Omni Shadows](https://playcanvas.github.io/#/graphics/clustered-omni-shadows)
- [Clustered Spot Shadows](https://playcanvas.github.io/#/graphics/clustered-spot-shadows)
- [Lights](https://playcanvas.github.io/#/graphics/lights)

## Accessors

### affectDynamic

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

Gets whether the light will affect non-lightmapped objects.

### affectLightmapped

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

Gets whether the light will affect lightmapped objects.

### affectSpecularity

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

Gets whether material specularity will be affected by this light.

### bake

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

Gets whether the light will be rendered into lightmaps.

### bakeArea

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

Gets the angular size in degrees of the area used when baking soft shadow boundaries for
the directional light into the lightmap.

### bakeDir

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

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

### bakeNumSamples

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

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

### cascadeBlend

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

Gets the blend factor for cascaded shadow maps.

### cascadeDistribution

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

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

### castShadows

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

Gets whether the light will cast shadows.

### color

```ts
get color(): Readonly<Color>
set color(value: Readonly<Color>)
```

Gets the color of the light. Use the setter to update the color.

### cookie

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

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

### cookieAngle

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

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

### cookieAsset

```ts
get cookieAsset(): number | null
set cookieAsset(value: number | null)
```

Gets the id of the texture asset used as the cookie for this light, or null if none is set.

### cookieChannel

```ts
get cookieChannel(): string
set cookieChannel(value: string)
```

Gets the color channels of the cookie texture to use.

### cookieFalloff

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

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

### cookieIntensity

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

Gets the cookie texture intensity.

### cookieOffset

```ts
get cookieOffset(): Vec2 | null
set cookieOffset(value: Vec2 | null)
```

Gets the spotlight cookie position offset.

### cookieScale

```ts
get cookieScale(): Vec2 | null
set cookieScale(value: Vec2 | null)
```

Gets the spotlight cookie scale.

### falloffMode

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

Gets the fall off mode for the light.

### innerConeAngle

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

Gets the half-angle (measured in degrees from the light's direction axis to the cone edge)
at which the spotlight cone starts to fade off.

### intensity

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

Gets the brightness of the light.

### isStatic

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

Gets whether the light ever moves.

### layers

```ts
get layers(): readonly number[]
set layers(value: readonly number[])
```

Gets the array of layer IDs ([Layer#id](https://api.playcanvas.com/engine/classes/Layer.md#id)) to which this light should belong.

### luminance

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

Gets the physically-based luminance.

### mask

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

Gets the mask to determine which [MeshInstance](https://api.playcanvas.com/engine/classes/MeshInstance.md)s are lit by this light.

### normalOffsetBias

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

Gets the normal offset depth bias.

### numCascades

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

Gets the number of shadow cascades.

### outerConeAngle

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

Gets the half-angle (measured in degrees from the light's direction axis to the cone edge)
at which the spotlight cone has faded to nothing.

### penumbraFalloff

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

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

### penumbraSize

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

Gets the size of penumbra for contact hardening shadows.

### range

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

Gets the range of the light.

### shadowBias

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

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

### shadowBlockerSamples

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

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

### shadowDistance

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

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

### shadowIntensity

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

Gets the intensity of the shadow darkening.

### shadowResolution

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

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

### shadowSamples

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

Gets the number of shadow samples used for soft shadows.

### shadowType

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

Gets the type of shadows being rendered by this light.

### shadowUpdateMode

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

Gets the shadow update mode.

### shadowUpdateOverrides

```ts
get shadowUpdateOverrides(): number[] | null
set shadowUpdateOverrides(values: number[] | null)
```

Gets an array of SHADOWUPDATE_ settings per shadow cascade.

### shape

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

Gets the light source shape.

### type

```ts
get type(): string
set type(value: string)
```

Gets the type of the light.

### volumetricScattering

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

Gets the multiplier of the light's contribution to the volumetric fog.

### vsmBias

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

Gets the VSM bias value.

### vsmBlurMode

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

Gets the blurring mode for variance shadow maps.

### vsmBlurSize

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

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

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

- `entity: Entity`
- `system: ComponentSystem`
- `get enabled(): boolean` · `set enabled(value: boolean)`
- `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`