godot-docs/classes/class_light2d.rst

:github_url: hide

.. Generated automatically by doc/tools/make_rst.py in Godot's source tree.
.. DO NOT EDIT THIS FILE, but the Light2D.xml source instead.
.. The source is found in doc/classes or modules/<name>/doc_classes.

.. _class_Light2D:

Light2D
=======

**Inherits:** :ref:`Node2D<class_Node2D>` **<** :ref:`CanvasItem<class_CanvasItem>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`

**Inherited By:** :ref:`DirectionalLight2D<class_DirectionalLight2D>`, :ref:`PointLight2D<class_PointLight2D>`

Casts light in a 2D environment.

Description
-----------

Casts light in a 2D environment. Light is defined by a (usually grayscale) texture, a color, an energy value, a mode (see constants), and various other parameters (range and shadows-related).

\ **Note:** Light2D can also be used as a mask.

Tutorials
---------

- :doc:`2D lights and shadows <../tutorials/2d/2d_lights_and_shadows>`

Properties
----------

+------------------------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`BlendMode<enum_Light2D_BlendMode>`       | :ref:`blend_mode<class_Light2D_property_blend_mode>`                       | ``0``                 |
+------------------------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`Color<class_Color>`                      | :ref:`color<class_Light2D_property_color>`                                 | ``Color(1, 1, 1, 1)`` |
+------------------------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`bool<class_bool>`                        | :ref:`editor_only<class_Light2D_property_editor_only>`                     | ``false``             |
+------------------------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`bool<class_bool>`                        | :ref:`enabled<class_Light2D_property_enabled>`                             | ``true``              |
+------------------------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`float<class_float>`                      | :ref:`energy<class_Light2D_property_energy>`                               | ``1.0``               |
+------------------------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`int<class_int>`                          | :ref:`range_item_cull_mask<class_Light2D_property_range_item_cull_mask>`   | ``1``                 |
+------------------------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`int<class_int>`                          | :ref:`range_layer_max<class_Light2D_property_range_layer_max>`             | ``0``                 |
+------------------------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`int<class_int>`                          | :ref:`range_layer_min<class_Light2D_property_range_layer_min>`             | ``0``                 |
+------------------------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`int<class_int>`                          | :ref:`range_z_max<class_Light2D_property_range_z_max>`                     | ``1024``              |
+------------------------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`int<class_int>`                          | :ref:`range_z_min<class_Light2D_property_range_z_min>`                     | ``-1024``             |
+------------------------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`Color<class_Color>`                      | :ref:`shadow_color<class_Light2D_property_shadow_color>`                   | ``Color(0, 0, 0, 0)`` |
+------------------------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`bool<class_bool>`                        | :ref:`shadow_enabled<class_Light2D_property_shadow_enabled>`               | ``false``             |
+------------------------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`ShadowFilter<enum_Light2D_ShadowFilter>` | :ref:`shadow_filter<class_Light2D_property_shadow_filter>`                 | ``0``                 |
+------------------------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`float<class_float>`                      | :ref:`shadow_filter_smooth<class_Light2D_property_shadow_filter_smooth>`   | ``0.0``               |
+------------------------------------------------+----------------------------------------------------------------------------+-----------------------+
| :ref:`int<class_int>`                          | :ref:`shadow_item_cull_mask<class_Light2D_property_shadow_item_cull_mask>` | ``1``                 |
+------------------------------------------------+----------------------------------------------------------------------------+-----------------------+

Methods
-------

+---------------------------+-------------------------------------------------------------------------------------------------+
| :ref:`float<class_float>` | :ref:`get_height<class_Light2D_method_get_height>` **(** **)** |const|                          |
+---------------------------+-------------------------------------------------------------------------------------------------+
| void                      | :ref:`set_height<class_Light2D_method_set_height>` **(** :ref:`float<class_float>` height **)** |
+---------------------------+-------------------------------------------------------------------------------------------------+

Enumerations
------------

.. _enum_Light2D_ShadowFilter:

.. _class_Light2D_constant_SHADOW_FILTER_NONE:

.. _class_Light2D_constant_SHADOW_FILTER_PCF5:

.. _class_Light2D_constant_SHADOW_FILTER_PCF13:

enum **ShadowFilter**:

- **SHADOW_FILTER_NONE** = **0** --- No filter applies to the shadow map. See :ref:`shadow_filter<class_Light2D_property_shadow_filter>`.

- **SHADOW_FILTER_PCF5** = **1** --- Percentage closer filtering (5 samples) applies to the shadow map. See :ref:`shadow_filter<class_Light2D_property_shadow_filter>`.

- **SHADOW_FILTER_PCF13** = **2** --- Percentage closer filtering (13 samples) applies to the shadow map. See :ref:`shadow_filter<class_Light2D_property_shadow_filter>`.

----

.. _enum_Light2D_BlendMode:

.. _class_Light2D_constant_BLEND_MODE_ADD:

.. _class_Light2D_constant_BLEND_MODE_SUB:

.. _class_Light2D_constant_BLEND_MODE_MIX:

enum **BlendMode**:

- **BLEND_MODE_ADD** = **0** --- Adds the value of pixels corresponding to the Light2D to the values of pixels under it. This is the common behavior of a light.

- **BLEND_MODE_SUB** = **1** --- Subtracts the value of pixels corresponding to the Light2D to the values of pixels under it, resulting in inversed light effect.

- **BLEND_MODE_MIX** = **2** --- Mix the value of pixels corresponding to the Light2D to the values of pixels under it by linear interpolation.

Property Descriptions
---------------------

.. _class_Light2D_property_blend_mode:

- :ref:`BlendMode<enum_Light2D_BlendMode>` **blend_mode**

+-----------+-----------------------+
| *Default* | ``0``                 |
+-----------+-----------------------+
| *Setter*  | set_blend_mode(value) |
+-----------+-----------------------+
| *Getter*  | get_blend_mode()      |
+-----------+-----------------------+

The Light2D's blend mode. See :ref:`BlendMode<enum_Light2D_BlendMode>` constants for values.

----

.. _class_Light2D_property_color:

- :ref:`Color<class_Color>` **color**

+-----------+-----------------------+
| *Default* | ``Color(1, 1, 1, 1)`` |
+-----------+-----------------------+
| *Setter*  | set_color(value)      |
+-----------+-----------------------+
| *Getter*  | get_color()           |
+-----------+-----------------------+

The Light2D's :ref:`Color<class_Color>`.

----

.. _class_Light2D_property_editor_only:

- :ref:`bool<class_bool>` **editor_only**

+-----------+------------------------+
| *Default* | ``false``              |
+-----------+------------------------+
| *Setter*  | set_editor_only(value) |
+-----------+------------------------+
| *Getter*  | is_editor_only()       |
+-----------+------------------------+

If ``true``, Light2D will only appear when editing the scene.

----

.. _class_Light2D_property_enabled:

- :ref:`bool<class_bool>` **enabled**

+-----------+--------------------+
| *Default* | ``true``           |
+-----------+--------------------+
| *Setter*  | set_enabled(value) |
+-----------+--------------------+
| *Getter*  | is_enabled()       |
+-----------+--------------------+

If ``true``, Light2D will emit light.

----

.. _class_Light2D_property_energy:

- :ref:`float<class_float>` **energy**

+-----------+-------------------+
| *Default* | ``1.0``           |
+-----------+-------------------+
| *Setter*  | set_energy(value) |
+-----------+-------------------+
| *Getter*  | get_energy()      |
+-----------+-------------------+

The Light2D's energy value. The larger the value, the stronger the light.

----

.. _class_Light2D_property_range_item_cull_mask:

- :ref:`int<class_int>` **range_item_cull_mask**

+-----------+---------------------------+
| *Default* | ``1``                     |
+-----------+---------------------------+
| *Setter*  | set_item_cull_mask(value) |
+-----------+---------------------------+
| *Getter*  | get_item_cull_mask()      |
+-----------+---------------------------+

The layer mask. Only objects with a matching mask will be affected by the Light2D.

----

.. _class_Light2D_property_range_layer_max:

- :ref:`int<class_int>` **range_layer_max**

+-----------+----------------------------+
| *Default* | ``0``                      |
+-----------+----------------------------+
| *Setter*  | set_layer_range_max(value) |
+-----------+----------------------------+
| *Getter*  | get_layer_range_max()      |
+-----------+----------------------------+

Maximum layer value of objects that are affected by the Light2D.

----

.. _class_Light2D_property_range_layer_min:

- :ref:`int<class_int>` **range_layer_min**

+-----------+----------------------------+
| *Default* | ``0``                      |
+-----------+----------------------------+
| *Setter*  | set_layer_range_min(value) |
+-----------+----------------------------+
| *Getter*  | get_layer_range_min()      |
+-----------+----------------------------+

Minimum layer value of objects that are affected by the Light2D.

----

.. _class_Light2D_property_range_z_max:

- :ref:`int<class_int>` **range_z_max**

+-----------+------------------------+
| *Default* | ``1024``               |
+-----------+------------------------+
| *Setter*  | set_z_range_max(value) |
+-----------+------------------------+
| *Getter*  | get_z_range_max()      |
+-----------+------------------------+

Maximum ``z`` value of objects that are affected by the Light2D.

----

.. _class_Light2D_property_range_z_min:

- :ref:`int<class_int>` **range_z_min**

+-----------+------------------------+
| *Default* | ``-1024``              |
+-----------+------------------------+
| *Setter*  | set_z_range_min(value) |
+-----------+------------------------+
| *Getter*  | get_z_range_min()      |
+-----------+------------------------+

Minimum ``z`` value of objects that are affected by the Light2D.

----

.. _class_Light2D_property_shadow_color:

- :ref:`Color<class_Color>` **shadow_color**

+-----------+-------------------------+
| *Default* | ``Color(0, 0, 0, 0)``   |
+-----------+-------------------------+
| *Setter*  | set_shadow_color(value) |
+-----------+-------------------------+
| *Getter*  | get_shadow_color()      |
+-----------+-------------------------+

:ref:`Color<class_Color>` of shadows cast by the Light2D.

----

.. _class_Light2D_property_shadow_enabled:

- :ref:`bool<class_bool>` **shadow_enabled**

+-----------+---------------------------+
| *Default* | ``false``                 |
+-----------+---------------------------+
| *Setter*  | set_shadow_enabled(value) |
+-----------+---------------------------+
| *Getter*  | is_shadow_enabled()       |
+-----------+---------------------------+

If ``true``, the Light2D will cast shadows.

----

.. _class_Light2D_property_shadow_filter:

- :ref:`ShadowFilter<enum_Light2D_ShadowFilter>` **shadow_filter**

+-----------+--------------------------+
| *Default* | ``0``                    |
+-----------+--------------------------+
| *Setter*  | set_shadow_filter(value) |
+-----------+--------------------------+
| *Getter*  | get_shadow_filter()      |
+-----------+--------------------------+

Shadow filter type. See :ref:`ShadowFilter<enum_Light2D_ShadowFilter>` for possible values.

----

.. _class_Light2D_property_shadow_filter_smooth:

- :ref:`float<class_float>` **shadow_filter_smooth**

+-----------+--------------------------+
| *Default* | ``0.0``                  |
+-----------+--------------------------+
| *Setter*  | set_shadow_smooth(value) |
+-----------+--------------------------+
| *Getter*  | get_shadow_smooth()      |
+-----------+--------------------------+

Smoothing value for shadows.

----

.. _class_Light2D_property_shadow_item_cull_mask:

- :ref:`int<class_int>` **shadow_item_cull_mask**

+-----------+----------------------------------+
| *Default* | ``1``                            |
+-----------+----------------------------------+
| *Setter*  | set_item_shadow_cull_mask(value) |
+-----------+----------------------------------+
| *Getter*  | get_item_shadow_cull_mask()      |
+-----------+----------------------------------+

The shadow mask. Used with :ref:`LightOccluder2D<class_LightOccluder2D>` to cast shadows. Only occluders with a matching light mask will cast shadows.

Method Descriptions
-------------------

.. _class_Light2D_method_get_height:

- :ref:`float<class_float>` **get_height** **(** **)** |const|

----

.. _class_Light2D_method_set_height:

- void **set_height** **(** :ref:`float<class_float>` height **)**

.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`