SpotLight - Verge3D User Manual - Soft8Soft
Description: Learn how to use SpotLight in your interactive 3D apps made with Verge3D

Object3D → Light →

# SpotLight

This light gets emitted from a single point in one direction, along a cone that increases in size the further from the light it gets.

This light can cast shadows — see the SpotLightShadow page for details.

## Target and Free Spot Lights

In Verge3D, spot lights can operate in two different modes depending on the value of the .isFreeLight flag. If `isFreeLight=true` SpotLight is the equivalent to what is often called a "Target Spotlight" in 3ds Max. When `isFreeLight=true` the light is equivalent to "Free Spotlight" in 3ds Max or just "Spot Light" in Blender/Maya.

In any case, the light direction is calculated as pointing from the light's position to the target's position. In the first mode, `target` is specified explicitly, while in the second mode, `target` is calculated by the engine from the light object rotation.

## Code Example

`// white spotlight shining from the side, modulated by a texture, casting a shadow const spotLight = new v3d.SpotLight(0xffffff); spotLight.position.set(100, 1000, 100); spotLight.castShadow = true; spotLight.shadow.mapSize.width = 1024; spotLight.shadow.mapSize.height = 1024; spotLight.shadow.camera.near = 500; spotLight.shadow.camera.far = 4000; spotLight.shadow.camera.fov = 30; app.scene.add(spotLight);`

## Constructor

### SpotLight(color : Integer, intensity : Float, distance : Float, angle : Float, penumbra : Float, decay : Float)

- color — (optional) hexadecimal color of the light. Default is `0xffffff` (white).
- intensity — (optional) numeric value of the light's strength/intensity. Default is `1`.
- distance — maximum range of the light. Default is `0` (no limit).
- angle — maximum angle of light dispersion from its direction whose upper bound is Math.PI/2.
- penumbra — percent of the spotlight cone that is attenuated due to penumbra. Takes values between `0` and `1`. Default is `0`.
- decay — the amount the light dims along the distance of the light.

Creates a new SpotLight.

## Properties

See the base Light class for inherited properties.

### # .angle : Float

Maximum extent of the spotlight, in radians, from its direction. Should be no more than `Math.PI/2`. The default is `Math.PI/3`.

### # .castShadow : Boolean

If set to `true` light will cast dynamic shadows. Warning: This is expensive and requires tweaking to get shadows looking right. See the SpotLightShadow for details. The default is `false`.

### # .decay : Float

The amount the light dims along the distance of the light. Default is `2`. In context of physically-correct rendering the default value should not be changed.

### # .distance : Float

When distance is zero, light will attenuate according to inverse-square law to infinite distance. When distance is non-zero, light will attenuate according to inverse-square law until near the distance cutoff, where it will then attenuate quickly and smoothly to `0`. Inherently, cutoffs are not physically correct.

Default is `0.0`.

### # .intensity : Float

The light's intensity. Default is `1`. Intensity is the luminous intensity of the light measured in candela (cd).

Changing the intensity will also change the light's power.

### # .isFreeLight : Boolean

Flag which used to define the lights with no explicit target. For such lights the virtual `target` is calculated from the rotation applied to the light object.

### # .isSpotLight : Boolean

Read-only flag to check if a given object is of type SpotLight.

### # .penumbra : Float

Percent of the spotlight cone that is attenuated due to penumbra. Takes values between zero and 1. The default is `0.0`.

### # .position : Vector3

This is set equal to Object3D.DefaultUp `(0, 1, 0)`, so that the light shines from the top down.

### # .power : Float

The light's power. Power is the luminous power of the light measured in lumens (lm).

Changing the power will also change the light's intensity.

### # .shadow : SpotLightShadow

A SpotLightShadow used to calculate shadows for this light.

### # .target : Object3D

The Spotlight points from its position to target.position. The default position of the target is `(0, 0, 0)`.

For the target's position to be changed to anything other than the default, it must be added to the scene using

`app.scene.add(light.target);`

This is so that the target's matrixWorld gets automatically updated each frame.

If `isFreeLight=false` is also possible to set the target to be another object in the scene (anything with a position property), like so:

`const targetObject = new v3d.Object3D(); app.scene.add(targetObject); light.target = targetObject;`

The spotlight will now track the target object.

## Methods

See the base Light class for inherited methods.

### # .copy(source : SpotLight) → this

Copies value of all the properties from the source to this SpotLight.

### # .dispose()

Frees the GPU-related resources allocated by this instance. Call this method whenever this instance is no longer used in your app.

## Puzzles

The following puzzles work with the spot lights:

- create object — select light, then spot.
- set light param — to set various light parameters.
- get light param — to obtain light parameters.

## Source

For more info on how to obtain the source code of this module see this page.