`<Light/>`

The <Light/> component allows an Entity to emit light. Any <Render/> component will be lit by the light. When attached to an <Entity/>, the light can be positioned and oriented using the entity's transform. Lights can be directional, omni or spot.

Usage

Simply attach a <Light/> to an <Entity/> and it will emit light from the entity's position and rotation.

<Entity>
  <Light type="directional" intensity={10} />
</Entity>

Demo
Code

// ↑ imports hidden
export const LightExample = () => {
    const lightingProps = useControls(vars);

    return (
        <>
            {/* Light entity */}
            <Entity name="light" 
                position={lightingProps.type === 'directional' ? [0, 5, 0] : [0, 2, 0]}
                rotation={lightingProps.type === 'directional' ? [45, 0, 0] : [0, 0, 0]}
            >
                <Light {...lightingProps} />
            </Entity>

            {/* Box to show lighting */}
            <Entity position={[0, 0, 0]}>
                <Render type="box" />
            </Entity>

            {/* Sphere to show lighting */}
            <Entity position={[2, 0, 0]}>
                <Render type="sphere" />
            </Entity>

            {/* Cylinder to show lighting */}
            <Entity position={[-2, 0, 0]}>
                <Render type="cylinder" />
            </Entity>
        </>
    );
};

Learn more about Lights in the PlayCanvas documentation.

Properties

Name	Type	Default
`type`	`"directional" \| "omni" \| "spot"` The type of the light.	`"directional"`
`color?`	`string` Sets the color of the light. The alpha component of the color is ignored. Defaults to white (`[1, 1, 1]`). Gets the color of the light.	`-`
`intensity?`	`number` Sets the brightness of the light. Defaults to 1. Gets the brightness of the light.	`-`
`luminance?`	`number` Sets the physically-based luminance. Only used if `scene.physicalUnits` is true. Defaults to 0. Gets the physically-based luminance.	`-`
`shape?`	`number` 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. Gets the light source shape.	`-`
`affectSpecularity?`	`boolean` Sets whether material specularity will be affected by this light. Ignored for lights other than LIGHTTYPE_DIRECTIONAL. Defaults to true. Gets whether material specularity will be affected by this light.	`-`
`castShadows?`	`boolean` Sets whether the light will cast shadows. Defaults to false. Gets whether the light will cast shadows.	`-`
`shadowDistance?`	`number` Sets the distance from the viewpoint beyond which shadows are no longer rendered. Affects directional lights only. Defaults to 40. Gets the distance from the viewpoint beyond which shadows are no longer rendered.	`-`
`shadowIntensity?`	`number` Sets the intensity of the shadow darkening. 0 having no effect and 1 meaning shadows are entirely black. Defaults to 1. Gets the intensity of the shadow darkening.	`-`
`shadowResolution?`	`number` Sets the size of the texture used for the shadow map. Valid sizes are 64, 128, 256, 512, 1024, 2048. Defaults to 1024. Gets the size of the texture used for the shadow map.	`-`
`shadowBias?`	`number` 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. Get the depth bias for tuning the appearance of the shadow mapping generated by this light.	`-`
`numCascades?`	`number` Sets the number of shadow cascades. Can be 1, 2, 3 or 4. Defaults to 1, representing no cascades. Gets the number of shadow cascades.	`-`
`cascadeBlend?`	`number` 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. Gets the blend factor for cascaded shadow maps.	`-`
`bakeNumSamples?`	`number` Sets the number of samples used to bake this light into the lightmap. Defaults to 1. Maximum value is 255. Gets the number of samples used to bake this light into the lightmap.	`-`
`bakeArea?`	`number` 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. Gets the penumbra angle in degrees.	`-`
`cascadeDistribution?`	`number` 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. Gets the distribution of subdivision of the camera frustum for individual shadow cascades.	`-`
`normalOffsetBias?`	`number` Sets the normal offset depth bias. Valid range is 0 to 1. Defaults to 0. Gets the normal offset depth bias.	`-`
`range?`	`number` Sets the range of the light. Affects omni and spot lights only. Defaults to 10. Gets the range of the light.	`-`
`innerConeAngle?`	`number` 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. Gets the angle at which the spotlight cone starts to fade off.	`-`
`outerConeAngle?`	`number` 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. Gets the angle at which the spotlight cone has faded to nothing.	`-`
`falloffMode?`	`number` 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. Gets the fall off mode for the light.	`-`
`shadowType?`	`number` Sets the type of shadows being rendered by this light. Can be: - SHADOW_PCF1_32F - SHADOW_PCF3_32F - SHADOW_PCF5_32F - SHADOW_PCF1_16F - SHADOW_PCF3_16F - SHADOW_PCF5_16F - SHADOW_VSM_16F - SHADOW_VSM_32F - SHADOW_PCSS_32F Gets the type of shadows being rendered by this light.	`-`
`vsmBlurSize?`	`number` 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. Gets the number of samples used for blurring a variance shadow map.	`-`
`vsmBlurMode?`	`number` 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. Gets the blurring mode for variance shadow maps.	`-`
`vsmBias?`	`number` Sets the VSM bias value. Gets the VSM bias value.	`-`
`cookieAsset?`	`number \| null` Sets the texture asset to be used as the cookie for this light. Only spot and omni lights can have cookies. Defaults to null. Gets the texture asset to be used as the cookie for this light.	`-`
`cookie?`	`Texture \| null` Sets the texture to be used as the cookie for this light. Only spot and omni lights can have cookies. Defaults to null. Gets the texture to be used as the cookie for this light.	`-`
`cookieIntensity?`	`number` Sets the cookie texture intensity. Defaults to 1. Gets the cookie texture intensity.	`-`
`cookieFalloff?`	`boolean` 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. Gets whether normal spotlight falloff is active when a cookie texture is set.	`-`
`cookieChannel?`	`string` Sets the color channels of the cookie texture to use. Can be "r", "g", "b", "a", "rgb". Gets the color channels of the cookie texture to use.	`-`
`cookieAngle?`	`number` Sets the angle for spotlight cookie rotation (in degrees). Gets the angle for spotlight cookie rotation (in degrees).	`-`
`cookieScale?`	`Vec2 \| null` Sets the spotlight cookie scale. Gets the spotlight cookie scale.	`-`
`cookieOffset?`	`Vec2 \| null` Sets the spotlight cookie position offset. Gets the spotlight cookie position offset.	`-`
`shadowUpdateMode?`	`number` 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). Gets the shadow update model.	`-`
`mask?`	`number` Sets the mask to determine which MeshInstances are lit by this light. Defaults to 1. Gets the mask to determine which MeshInstances are lit by this light.	`-`
`affectDynamic?`	`boolean` Sets whether the light will affect non-lightmapped objects. Gets whether the light will affect non-lightmapped objects.	`-`
`affectLightmapped?`	`boolean` Sets whether the light will affect lightmapped objects. Gets whether the light will affect lightmapped objects.	`-`
`bake?`	`boolean` Sets whether the light will be rendered into lightmaps. Gets whether the light will be rendered into lightmaps.	`-`
`bakeDir?`	`boolean` 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. Gets whether the light's direction will contribute to directional lightmaps.	`-`
`isStatic?`	`boolean` Sets whether the light ever moves. This is an optimization hint. Gets whether the light ever moves.	`-`
`layers?`	`number[]` 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. Gets the array of layer IDs (Layer#id ) to which this light should belong.	`-`
`shadowUpdateOverrides?`	`number[] \| null` Sets an array of SHADOWUPDATE_ settings per shadow cascade. Set to undefined if not used. Gets an array of SHADOWUPDATE_ settings per shadow cascade.	`-`
`shadowSamples?`	`number` 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. Gets the number of shadow samples used for soft shadows.	`-`
`shadowBlockerSamples?`	`number` 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. Gets the number of blocker samples used for contact hardening shadows.	`-`
`penumbraSize?`	`number` 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. Gets the size of penumbra for contact hardening shadows.	`-`
`penumbraFalloff?`	`number` 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. Gets the falloff rate for shadow penumbra for contact hardening shadows.	`-`
`system?`	`ComponentSystem` The ComponentSystem used to create this Component.	`-`
`entity?`	`Entity` The Entity that this Component is attached to.	`-`
`enabled?`	`boolean` Sets the enabled state of the component. Gets the enabled state of the component.	`-`

Usage​

Properties​

Usage

Properties