Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

SpotLight3D

Inherits: Light3D < VisualInstance3D < Node3D < Node < Object

A spotlight, such as a reflector spotlight or a lantern.

Description

A Spotlight is a type of Light3D node that emits lights in a specific direction, in the shape of a cone. The light is attenuated through the distance. This attenuation can be configured by changing the energy, radius and attenuation parameters of Light3D.

Note: When using the Mobile rendering method, only 8 spot lights can be displayed on each mesh resource. Attempting to display more than 8 spot lights on a single mesh resource will result in spot lights flickering in and out as the camera moves. When using the Compatibility rendering method, only 8 spot lights can be displayed on each mesh resource by default, but this can be increased by adjusting ProjectSettings.rendering/limits/opengl/max_lights_per_object.

Note: When using the Mobile or Compatibility rendering methods, spot lights will only correctly affect meshes whose visibility AABB intersects with the light's AABB. If using a shader to deform the mesh in a way that makes it go outside its AABB, GeometryInstance3D.extra_cull_margin must be increased on the mesh. Otherwise, the light may not be visible on the mesh.

Tutorials

Properties

float

shadow_bias

0.03 (overrides Light3D)

float

shadow_normal_bias

1.0 (overrides Light3D)

float

spot_angle

45.0

float

spot_angle_attenuation

1.0

float

spot_attenuation

1.0

float

spot_range

5.0

Property Descriptions

float spot_angle = 45.0

  • void set_param ( float value )

  • float get_param ( )

The spotlight's angle in degrees.

Note: spot_angle is not affected by Node3D.scale (the light's scale or its parent's scale).

float spot_angle_attenuation = 1.0

  • void set_param ( float value )

  • float get_param ( )

The spotlight's angular attenuation curve. See also spot_attenuation.

float spot_attenuation = 1.0

  • void set_param ( float value )

  • float get_param ( )

The spotlight's light energy (drop-off) attenuation curve. A number of presets are available in the Inspector by right-clicking the curve. Zero and negative values are allowed but can produce unusual effects. See also spot_angle_attenuation.

Note: Very high spot_attenuation values (typically above 10) can impact performance negatively if the light is made to use a larger spot_range to compensate. This is because culling opportunities will become less common and shading costs will be increased (as the light will cover more pixels on screen while resulting in the same amount of brightness). To improve performance, use the lowest spot_attenuation value possible for the visuals you're trying to achieve.

float spot_range = 5.0

  • void set_param ( float value )

  • float get_param ( )

The maximal range that can be reached by the spotlight. Note that the effectively lit area may appear to be smaller depending on the spot_attenuation in use. No matter the spot_attenuation in use, the light will never reach anything outside this range.

Note: spot_range is not affected by Node3D.scale (the light's scale or its parent's scale).