Engine API Reference - v2.19.1
    Preparing search index...

    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 a 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 Entity#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)

    Index

    Properties

    entity system

    Accessors

    affectDynamic affectLightmapped affectSpecularity bake bakeArea bakeDir bakeNumSamples cascadeBlend cascadeDistribution castShadows color cookie cookieAngle cookieAsset cookieChannel cookieFalloff cookieIntensity cookieOffset cookieScale enabled falloffMode innerConeAngle intensity isStatic layers luminance mask normalOffsetBias numCascades outerConeAngle penumbraFalloff penumbraSize range shadowBias shadowBlockerSamples shadowDistance shadowIntensity shadowResolution shadowSamples shadowType shadowUpdateMode shadowUpdateOverrides shape type vsmBias vsmBlurMode vsmBlurSize

    Methods

    fire hasEvent off on once

    Properties

    entity: Entity

    The Entity that this Component is attached to.

    system: ComponentSystem

    The ComponentSystem used to create this Component.

    Accessors

    • get affectLightmapped(): boolean

      Gets whether the light will affect lightmapped objects.

      Returns boolean

    • set affectLightmapped(value: boolean): void

      Sets whether the light will affect lightmapped objects. Toggles the MASK_AFFECT_LIGHTMAPPED bit on mask. Mutually exclusive with bake on the mask: enabling one clears the other's mask bit. Defaults to false.

      Parameters

      • value: boolean

      Returns void

    • get affectSpecularity(): boolean

      Gets whether material specularity will be affected by this light.

      Returns boolean

    • set affectSpecularity(value: boolean): void

      Sets whether material specularity will be affected by this light. Only takes effect when type is "directional"; for other types the value is preserved on the component and applied if type later becomes "directional". Defaults to true.

      Parameters

      • value: boolean

      Returns void

    • get bakeArea(): number

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

      Returns number

    • set bakeArea(value: number): void

      Sets the angular size in degrees of the area used when baking soft shadow boundaries for the directional light into the lightmap. Range is 0 to 180. Requires bake to be set to true and type to be "directional". Defaults to 0.

      Parameters

      • value: number

      Returns void

    • get bakeDir(): boolean

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

      Returns boolean

    • set bakeDir(value: 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 the directional lightmap is an approximation and can only hold a single direction per pixel. Intersecting multiple lights with bakeDir set to true may lead to incorrect-looking specular/bump mapping in the area of intersection. The error is not always visible though, and is highly scene-dependent. Defaults to true.

      Parameters

      • value: boolean

      Returns void

    • 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. Defaults to 0, which disables blending between cascades.

      Parameters

      • value: number

      Returns void

    • get cascadeDistribution(): number

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

      Returns number

    • set cascadeDistribution(value: number): void

      Sets the distribution of subdivision of the camera frustum for individual shadow cascades. Only used if 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

      • value: number

      Returns void

    • get cookieAsset(): number | null

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

      Returns number | null

    • set cookieAsset(value: number | null): void

      Sets the id of the texture asset to be used as the cookie for this light. Only spot and omni lights can have cookies. Spot lights expect a 2D texture; omni lights expect a cubemap. Defaults to null.

      Parameters

      • value: number | null

      Returns void

    • get cookieFalloff(): boolean

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

      Returns boolean

    • set cookieFalloff(value: 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). Defaults to true.

      Parameters

      • value: boolean

      Returns void

    • get innerConeAngle(): 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.

      Returns number

    • set innerConeAngle(value: number): void

      Sets 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. The full inner beam angle is twice this value. Affects spot lights only. Defaults to 40 (i.e. an 80-degree full inner beam).

      Parameters

      • value: number

      Returns void

    • get mask(): number

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

      Returns number

    • set mask(value: number): void

      Sets the bitmask that determines which MeshInstances are lit by this light. The value is composed from MASK_AFFECT_DYNAMIC, MASK_AFFECT_LIGHTMAPPED and MASK_BAKE. The affectDynamic, affectLightmapped and bake helpers write to the same underlying mask but maintain their own state and are not recomputed from mask, so writing mask directly will not update those helpers (and a subsequent write to a helper may overwrite bits set via mask). Defaults to MASK_AFFECT_DYNAMIC.

      Parameters

      • value: number

      Returns void

    • get outerConeAngle(): 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.

      Returns number

    • set outerConeAngle(value: number): void

      Sets 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. The full outer beam angle is twice this value. Affects spot lights only. Defaults to 45 (i.e. a 90-degree full outer beam).

      Parameters

      • value: number

      Returns void

    • 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

    • 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

    • get shadowBias(): number

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

      Returns number

    • set shadowBias(value: 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

      • value: number

      Returns void

    • 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 should be a non-negative whole number. 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 value can be lower than shadowSamples to optimize performance, often without large impact on quality.

      Parameters

      • value: number

      Returns void

    • get shadowDistance(): number

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

      Returns number

    • set shadowDistance(value: number): void

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

      Parameters

      • value: number

      Returns void

    • 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 should 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

    • get shadowUpdateOverrides(): number[] | null

      Gets an array of SHADOWUPDATE_ settings per shadow cascade.

      Returns number[] | null

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

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

      Parameters

      • values: number[] | null

      Returns void

    • get type(): string

      Gets the type of the light.

      Returns string

    • set type(value: string): void

      Sets the type of the light. Can be:

      • "directional": A global light that emits light in the direction of the negative y-axis of the owner entity.
      • "omni": A local light that emits light in all directions from the owner entity's position.
      • "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.

      Defaults to "directional".

      Parameters

      • value: string

      Returns void

    • get vsmBlurSize(): number

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

      Returns number

    • set vsmBlurSize(value: number): void

      Sets the number of samples used for blurring a variance shadow map. Only odd values are supported; even values are rounded up to the next odd value. Values should be between 1 and 25. Defaults to 11.

      Parameters

      • value: number

      Returns void

    Methods

    • 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.

      obj.fire('test', 'This is the message');

    • 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.

      obj.on('test', () => {}); // bind an event to 'test'
      obj.hasEvent('test'); // returns true
      obj.hasEvent('hello'); // returns false

    • 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.

      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

    • 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.

      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();

    • 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.

      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

    Settings

    Member Visibility

    On This Page

    Properties
    Accessors
    Methods