Engine API Reference - v1.77.0
    Preparing search index...

    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 pc.LightComponent to an entity
    const entity = new pc.Entity();
    entity.addComponent('light', {
        type: "omni",
        color: new pc.Color(1, 0, 0),
        range: 10
    });

    // Get the pc.LightComponent on an entity
    const lightComponent = entity.light;

    // Update a property on a light component
    entity.light.range = 20;

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    entity system

    Accessors

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

    Methods

    fire hasEvent off on once

    Constructors

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

      • SHADOW_PCF3: Render depth (color-packed on WebGL 1.0), can be used for PCF 3x3 sampling.
      • SHADOW_VSM8: Render packed variance shadow map. All shadow receivers must also cast shadows for this mode to work correctly.
      • SHADOW_VSM16: Render 16-bit exponential variance shadow map. Requires OES_texture_half_float extension. Falls back to SHADOW_VSM8, if not supported.
      • SHADOW_VSM32: Render 32-bit exponential variance shadow map. Requires OES_texture_float extension. Falls back to SHADOW_VSM16, if not supported.
      • SHADOW_PCF5: Render depth buffer only, can be used for hardware-accelerated PCF 5x5 sampling. Requires WebGL2. Falls back to SHADOW_PCF3 on WebGL 1.0.
      • SHADOW_PCSS: Render depth as color, and use the software sampled PCSS method for shadows.

      Parameters

      • arg: 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', function () { }); // 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 = function () {
      };
      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', function (a, b) {
          console.log(a + b);
      });
      obj.fire('test', 1, 2); // prints 3 to the console

      const evt = obj.on('test', function (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', function (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

    Constructors
    Properties
    Accessors
    Methods