Index · Object → Node → Node3D → VisualInstance3D → Light3D

Light3D

Provides a base class for different kinds of light nodes.

Inherited by (4): AreaLight3DDirectionalLight3DOmniLight3DSpotLight3D
Class Description

Light3D is the abstract base class for light nodes. As it can't be instantiated, it shouldn't be used directly. Other types of light nodes inherit from it. Light3D contains the common variables and parameters used for lighting.

Properties

var distance_fade_begin: float = 40.0

The distance from the camera at which the light begins to fade away (in 3D units).

Note: Only effective for OmniLight3D and SpotLight3D.

var distance_fade_enabled: bool = false

If true, the light will smoothly fade away when far from the active Camera3D starting at distance_fade_begin. This acts as a form of level of detail (LOD). The light will fade out over distance_fade_begin + distance_fade_length, after which it will be culled and not sent to the shader at all. Use this to reduce the number of active lights in a scene and thus improve performance.

Note: Only effective for OmniLight3D and SpotLight3D.

var distance_fade_length: float = 10.0

Distance over which the light and its shadow fades. The light's energy and shadow's opacity is progressively reduced over this distance and is completely invisible at the end.

Note: Only effective for OmniLight3D and SpotLight3D.

var distance_fade_shadow: float = 50.0

The distance from the camera at which the light's shadow cuts off (in 3D units). Set this to a value lower than distance_fade_begin + distance_fade_length to further improve performance, as shadow rendering is often more expensive than light rendering itself.

Note: Only effective for OmniLight3D and SpotLight3D, and only when shadow_enabled is true.

var editor_only: bool = false

If true, the light only appears in the editor and will not be visible at runtime. If true, the light will never be baked in LightmapGI regardless of its light_bake_mode.

var light_angular_distance: float = 0.0

The light's angular size in degrees. Increasing this will make shadows softer at greater distances (also called percentage-closer soft shadows, or PCSS). Only available for DirectionalLight3Ds. For reference, the Sun from the Earth is approximately 0.5. Increasing this value above 0.0 for lights with shadows enabled will have a noticeable performance cost due to PCSS.

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

Note: PCSS for directional lights is only supported in the Forward+ rendering method, not Mobile or Compatibility.

var light_bake_mode: Light3D.BakeMode = 2

The light's bake mode. This will affect the global illumination techniques that have an effect on the light's rendering.

Note: Meshes' global illumination mode will also affect the global illumination rendering. See GeometryInstance3D.gi_mode.

var light_color: Color = Color(1, 1, 1, 1)

The light's color in nonlinear sRGB encoding. An overbright color can be used to achieve a result equivalent to increasing the light's light_energy.

var light_cull_mask: int = 4294967295

The light will affect objects in the selected layers.

Note: The light cull mask is ignored by VoxelGI, SDFGI, LightmapGI, and volumetric fog. These will always render lights in a way that ignores the cull mask. See also VisualInstance3D.layers.

var light_energy: float = 1.0

The light's strength multiplier (this is not a physical unit). For OmniLight3D and SpotLight3D, changing this value will only change the light color's intensity, not the light's radius.

var light_indirect_energy: float = 1.0

Secondary multiplier used with indirect light (light bounces). Used with VoxelGI and SDFGI (see Environment.sdfgi_enabled).

Note: This property is ignored if light_energy is equal to 0.0, as the light won't be present at all in the GI shader.

var light_intensity_lumens: float

Used by positional lights (OmniLight3D and SpotLight3D) when ProjectSettings.rendering/lights_and_shadows/use_physical_light_units is true. Sets the intensity of the light source measured in Lumens. Lumens are a measure of luminous flux, which is the total amount of visible light emitted by a light source per unit of time.

For SpotLight3Ds, we assume that the area outside the visible cone is surrounded by a perfect light absorbing material. Accordingly, the apparent brightness of the cone area does not change as the cone increases and decreases in size.

A typical household lightbulb can range from around 600 lumens to 1,200 lumens, a candle is about 13 lumens, while a streetlight can be approximately 60,000 lumens.

var light_intensity_lux: float

Used by DirectionalLight3Ds when ProjectSettings.rendering/lights_and_shadows/use_physical_light_units is true. Sets the intensity of the light source measured in Lux. Lux is a measure of luminous flux per unit area, it is equal to one lumen per square meter. Lux is the measure of how much light hits a surface at a given time.

On a clear sunny day a surface in direct sunlight may be approximately 100,000 lux, a typical room in a home may be approximately 50 lux, while the moonlit ground may be approximately 0.1 lux.

var light_negative: bool = false

If true, the light's effect is reversed, darkening areas and casting bright shadows.

var light_projector: Texture2D

Texture2D projected by light. shadow_enabled must be on for the projector to work. Light projectors make the light appear as if it is shining through a colored but transparent object, almost like light shining through stained-glass.

Note: Unlike BaseMaterial3D whose filter mode can be adjusted on a per-material basis, the filter mode for light projector textures is set globally with ProjectSettings.rendering/textures/light_projectors/filter.

Note: Light projector textures are only supported in the Forward+ and Mobile rendering methods, not Compatibility.

var light_size: float = 0.0

The simulated size of the light in Godot units, affecting shading and shadows. For OmniLight3Ds and SpotLight3Ds, increasing this value simulates a spherical area light, expanding the size of specular highlights. If shadows are enabled, a penumbra is rendered, making shadows appear blurrier. For AreaLight3Ds, only the shadows are affected. Penumbras are simulated with percentage-closer soft shadows, or PCSS, which has a noticeable performance cost for values above 0.0.

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

Note: PCSS for positional lights is only supported in the Forward+ and Mobile rendering methods, not Compatibility.

var light_specular: float = 1.0

The intensity of the specular blob in objects affected by the light. At 0, the light becomes a pure diffuse light. When not baking emission, this can be used to avoid unrealistic reflections when placing lights above an emissive surface.

var light_temperature: float

Sets the color temperature of the light source, measured in Kelvin. This is used to calculate a correlated color temperature which tints the light_color.

The sun on a cloudy day is approximately 6500 Kelvin, on a clear day it is between 5500 to 6000 Kelvin, and on a clear day at sunrise or sunset it ranges to around 1850 Kelvin.

var light_volumetric_fog_energy: float = 1.0

Secondary multiplier multiplied with light_energy then used with the Environment's volumetric fog (if enabled). If set to 0.0, computing volumetric fog will be skipped for this light, which can improve performance for large amounts of lights when volumetric fog is enabled.

Note: To prevent short-lived dynamic light effects from poorly interacting with volumetric fog, lights used in those effects should have light_volumetric_fog_energy set to 0.0 unless Environment.volumetric_fog_temporal_reprojection_enabled is disabled (or unless the reprojection amount is significantly lowered).

var shadow_bias: float = 0.1

Used to adjust shadow appearance. Too small a value results in self-shadowing ("shadow acne"), while too large a value causes shadows to separate from casters ("peter-panning"). Adjust as needed.

var shadow_blur: float = 1.0

Blurs the edges of the shadow. Can be used to hide pixel artifacts in low-resolution shadow maps. A high value can impact performance, make shadows appear grainy and can cause other unwanted artifacts. Try to keep as near default as possible.

var shadow_caster_mask: int = 4294967295

The light will only cast shadows using objects in the selected layers.

var shadow_enabled: bool = false

If true, the light will cast real-time shadows. This has a significant performance cost. Only enable shadow rendering when it makes a noticeable difference in the scene's appearance, and consider using distance_fade_enabled to hide the light when far away from the Camera3D.

var shadow_normal_bias: float = 2.0

Offsets the lookup into the shadow map by the object's normal. This can be used to reduce self-shadowing artifacts without using shadow_bias. In practice, this value should be tweaked along with shadow_bias to reduce artifacts as much as possible.

var shadow_opacity: float = 1.0

The opacity to use when rendering the light's shadow map. Values lower than 1.0 make the light appear through shadows. This can be used to fake global illumination at a low performance cost.

var shadow_reverse_cull_face: bool = false

If true, reverses the backface culling of the mesh. This can be useful when you have a flat mesh that has a light behind it. If you need to cast a shadow on both sides of the mesh, set the mesh to use double-sided shadows with GeometryInstance3D.SHADOW_CASTING_SETTING_DOUBLE_SIDED.

var shadow_transmittance_bias: float = 0.05
Inherited from VisualInstance3D (3)
var layers: int = 1
Inherited from Node3D (17)
var position: Vector3 = Vector3(0, 0, 0)
var rotation: Vector3 = Vector3(0, 0, 0)
var rotation_order: EulerOrder = 2
var scale: Vector3 = Vector3(1, 1, 1)
var top_level: bool = false
var transform: Transform3D = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)
var visibility_parent: NodePath = NodePath("")
var visible: bool = true
Inherited from Node (14)
var owner: Node

Methods

func get_correlated_color() -> Color

Returns the Color of an idealized blackbody at the given light_temperature. This value is calculated internally based on the light_temperature. This Color is multiplied by light_color before being sent to the RenderingServer.

func get_param(param: Light3D.Param) -> float

Returns the value of the specified Param parameter.

func set_param(param: Light3D.Param, value: float) -> void

Sets the value of the specified Param parameter.

Inherited from VisualInstance3D (7)
func _get_aabb() -> AABB
func get_aabb() -> AABB
func get_base() -> RID
func get_instance() -> RID
func get_layer_mask_value(layer_number: int) -> bool
func set_base(base: RID) -> void
func set_layer_mask_value(layer_number: int, value: bool) -> void
Inherited from Node3D (37)
func add_gizmo(gizmo: Node3DGizmo) -> void
func clear_gizmos() -> void
func force_update_transform() -> void
func get_gizmos() -> Node3DGizmo[]
func global_rotate(axis: Vector3, angle: float) -> void
func global_scale(scale: Vector3) -> void
func global_translate(offset: Vector3) -> void
func hide() -> void
func look_at(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) -> void
func look_at_from_position(position: Vector3, target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) -> void
func orthonormalize() -> void
func rotate(axis: Vector3, angle: float) -> void
func rotate_object_local(axis: Vector3, angle: float) -> void
func rotate_x(angle: float) -> void
func rotate_y(angle: float) -> void
func rotate_z(angle: float) -> void
func scale_object_local(scale: Vector3) -> void
func set_disable_scale(disable: bool) -> void
func set_identity() -> void
func set_notify_local_transform(enable: bool) -> void
func set_notify_transform(enable: bool) -> void
func set_subgizmo_selection(gizmo: Node3DGizmo, id: int, transform: Transform3D) -> void
func show() -> void
func to_global(local_point: Vector3) -> Vector3
func to_local(global_point: Vector3) -> Vector3
func translate(offset: Vector3) -> void
func translate_object_local(offset: Vector3) -> void
func update_gizmos() -> void
Inherited from Node (106)
func _enter_tree() -> void
func _exit_tree() -> void
func _input(event: InputEvent) -> void
func _physics_process(delta: float) -> void
func _process(delta: float) -> void
func _ready() -> void
func _shortcut_input(event: InputEvent) -> void
func _unhandled_input(event: InputEvent) -> void
func _unhandled_key_input(event: InputEvent) -> void
func add_child(node: Node, force_readable_name: bool = false, internal: Node.InternalMode = 0) -> void
func add_sibling(sibling: Node, force_readable_name: bool = false) -> void
func add_to_group(group: StringName, persistent: bool = false) -> void
func atr(message: String, context: StringName = "") -> String
func atr_n(message: String, plural_message: StringName, n: int, context: StringName = "") -> String
func can_process() -> bool
func duplicate(flags: int = 15) -> Node
func find_child(pattern: String, recursive: bool = true, owned: bool = true) -> Node
func find_children(pattern: String, type: String = "", recursive: bool = true, owned: bool = true) -> Node[]
func find_parent(pattern: String) -> Node
func get_child(idx: int, include_internal: bool = false) -> Node
func get_child_count(include_internal: bool = false) -> int
func get_children(include_internal: bool = false) -> Node[]
func get_groups() -> StringName[]
func get_index(include_internal: bool = false) -> int
func get_node(path: NodePath) -> Node
func get_orphan_node_ids() -> int[]
func get_parent() -> Node
func get_path() -> NodePath
func get_path_to(node: Node, use_unique_path: bool = false) -> NodePath
func get_window() -> Window
func has_node(path: NodePath) -> bool
func is_ancestor_of(node: Node) -> bool
func is_greater_than(node: Node) -> bool
func is_in_group(group: StringName) -> bool
func move_child(child_node: Node, to_index: int) -> void
func notify_deferred_thread_group(what: int) -> void
func notify_thread_safe(what: int) -> void
func print_orphan_nodes() -> void
func print_tree() -> void
func print_tree_pretty() -> void
func propagate_call(method: StringName, args: Array = [], parent_first: bool = false) -> void
func propagate_notification(what: int) -> void
func queue_free() -> void
func remove_child(node: Node) -> void
func remove_from_group(group: StringName) -> void
func reparent(new_parent: Node, keep_global_transform: bool = true) -> void
func replace_by(node: Node, keep_groups: bool = false) -> void
func request_ready() -> void
func rpc(method: StringName) -> Error
func rpc_config(method: StringName, config: Variant) -> void
func rpc_id(peer_id: int, method: StringName) -> Error
func set_deferred_thread_group(property: StringName, value: Variant) -> void
func set_display_folded(fold: bool) -> void
func set_editable_instance(node: Node, is_editable: bool) -> void
func set_multiplayer_authority(id: int, recursive: bool = true) -> void
func set_physics_process(enable: bool) -> void
func set_physics_process_internal(enable: bool) -> void
func set_process(enable: bool) -> void
func set_process_input(enable: bool) -> void
func set_process_internal(enable: bool) -> void
func set_process_shortcut_input(enable: bool) -> void
func set_process_unhandled_input(enable: bool) -> void
func set_scene_instance_load_placeholder(load_placeholder: bool) -> void
func set_thread_safe(property: StringName, value: Variant) -> void
Inherited from Object (62)
func _get(property: StringName) -> Variant
func _get_property_list() -> Dictionary[]
func _init() -> void
func _iter_get(iter: Variant) -> Variant
func _iter_init(iter: Array) -> bool
func _iter_next(iter: Array) -> bool
func _notification(what: int) -> void
func _set(property: StringName, value: Variant) -> bool
func _to_string() -> String
func _validate_property(property: Dictionary) -> void
func add_user_signal(signal: String, arguments: Array = []) -> void
func call(method: StringName) -> Variant
func callv(method: StringName, arg_array: Array) -> Variant
func cancel_free() -> void
func connect(signal: StringName, callable: Callable, flags: int = 0) -> Error
func disconnect(signal: StringName, callable: Callable) -> void
func emit_signal(signal: StringName) -> Error
func free() -> void
func get(property: StringName) -> Variant
func get_class() -> String
func get_incoming_connections() -> Dictionary[]
func get_indexed(property_path: NodePath) -> Variant
func get_meta(name: StringName, default: Variant = null) -> Variant
func get_meta_list() -> StringName[]
func get_method_list() -> Dictionary[]
func get_property_list() -> Dictionary[]
func get_signal_connection_list(signal: StringName) -> Dictionary[]
func get_signal_list() -> Dictionary[]
func has_meta(name: StringName) -> bool
func has_method(method: StringName) -> bool
func has_signal(signal: StringName) -> bool
func is_class(class: StringName) -> bool
func is_connected(signal: StringName, callable: Callable) -> bool
func notification(what: int, reversed: bool = false) -> void
func remove_meta(name: StringName) -> void
func remove_user_signal(signal: StringName) -> void
func set(property: StringName, value: Variant) -> void
func set_block_signals(enable: bool) -> void
func set_deferred(property: StringName, value: Variant) -> void
func set_indexed(property_path: NodePath, value: Variant) -> void
func set_message_translation(enable: bool) -> void
func set_meta(name: StringName, value: Variant) -> void
func set_script(script: Variant) -> void
func set_translation_domain(domain: StringName) -> void
func to_string() -> String
func tr(message: StringName, context: StringName = &"") -> String
func tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") -> String

Signals

Inherited from Node3D (1)
Inherited from Node (11)
signal child_entered_tree(node: Node)
signal child_exiting_tree(node: Node)
signal ready()
signal renamed()
signal replacing_by(node: Node)
signal tree_entered()
signal tree_exited()
signal tree_exiting()
Inherited from Object (2)

Enums & Constants

enum Param
PARAM_ENERGY = 0

Constant for accessing light_energy.

PARAM_INDIRECT_ENERGY = 1

Constant for accessing light_indirect_energy.

PARAM_VOLUMETRIC_FOG_ENERGY = 2

Constant for accessing light_volumetric_fog_energy.

PARAM_SPECULAR = 3

Constant for accessing light_specular.

PARAM_RANGE = 4

Constant for accessing OmniLight3D.omni_range or SpotLight3D.spot_range.

PARAM_SIZE = 5

Constant for accessing light_size.

PARAM_ATTENUATION = 6

Constant for accessing OmniLight3D.omni_attenuation or SpotLight3D.spot_attenuation.

PARAM_SPOT_ANGLE = 7

Constant for accessing SpotLight3D.spot_angle.

PARAM_SPOT_ATTENUATION = 8

Constant for accessing SpotLight3D.spot_angle_attenuation.

PARAM_SHADOW_MAX_DISTANCE = 9

Constant for accessing DirectionalLight3D.directional_shadow_max_distance.

PARAM_SHADOW_SPLIT_1_OFFSET = 10

Constant for accessing DirectionalLight3D.directional_shadow_split_1.

PARAM_SHADOW_SPLIT_2_OFFSET = 11

Constant for accessing DirectionalLight3D.directional_shadow_split_2.

PARAM_SHADOW_SPLIT_3_OFFSET = 12

Constant for accessing DirectionalLight3D.directional_shadow_split_3.

PARAM_SHADOW_FADE_START = 13

Constant for accessing DirectionalLight3D.directional_shadow_fade_start.

PARAM_SHADOW_NORMAL_BIAS = 14

Constant for accessing shadow_normal_bias.

PARAM_SHADOW_BIAS = 15

Constant for accessing shadow_bias.

PARAM_SHADOW_PANCAKE_SIZE = 16

Constant for accessing DirectionalLight3D.directional_shadow_pancake_size.

PARAM_SHADOW_OPACITY = 17

Constant for accessing shadow_opacity.

PARAM_SHADOW_BLUR = 18

Constant for accessing shadow_blur.

PARAM_TRANSMITTANCE_BIAS = 19

Constant for accessing shadow_transmittance_bias.

PARAM_INTENSITY = 20

Constant for accessing light_intensity_lumens and light_intensity_lux. Only used when ProjectSettings.rendering/lights_and_shadows/use_physical_light_units is true.

PARAM_MAX = 21

Represents the size of the Param enum.

enum BakeMode
BAKE_DISABLED = 0

Light is ignored when baking. This is the fastest mode, but the light will not be taken into account when baking global illumination. This mode should generally be used for dynamic lights that change quickly, as the effect of global illumination is less noticeable on those lights.

Note: Hiding a light does not affect baking LightmapGI. Hiding a light will still affect baking VoxelGI and SDFGI (see Environment.sdfgi_enabled).

BAKE_STATIC = 1

Light is taken into account in static baking (VoxelGI, LightmapGI, SDFGI (Environment.sdfgi_enabled)). The light can be moved around or modified, but its global illumination will not update in real-time.

Note: The light is not baked in LightmapGI if editor_only is true.

Note: When using LightmapGI, both the direct and indirect light are baked. Since direct light is baked, the light doesn't display a specular lobe on static lightmapped meshes. Shadows on static lightmapped meshes will also look less detailed, but the light still casts shadows that can be displayed on dynamic objects. Since real-time light computations are skipped on static lightmapped meshes, this bake mode improves runtime performance compared to BAKE_DYNAMIC and BAKE_DISABLED.

BAKE_DYNAMIC = 2

Light is taken into account in dynamic baking (VoxelGI and SDFGI (Environment.sdfgi_enabled)). The light can be moved around or modified with global illumination updating in real-time. The light's global illumination appearance will be slightly different compared to BAKE_STATIC. This has a greater performance cost compared to BAKE_STATIC. When using SDFGI, the update speed of dynamic lights is affected by ProjectSettings.rendering/global_illumination/sdfgi/frames_to_update_lights.

Note: When using LightmapGI, the light's indirect light is baked, but direct light and shadows remain real-time. This mode allows performing subtle changes to a light's color, energy, and position while still looking fairly correct. For example, you can use this to create flickering static torches that have their indirect light baked.