Engine API Reference - v2.7.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 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)

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

    • 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

    • 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

    • 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

    • 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

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

    • 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

    • 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

    • 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

    • 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

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