:github_url: hide

.. DO NOT EDIT THIS FILE!!!

.. Generated automatically from Godot engine sources.
.. Generator:
https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py.
.. XML source: https://github.com/godotengine/godot/tree/master/modules/gdscript/
doc_classes/@GDScript.xml.

.. _class_@GDScript:

@GDScript
=========

Built-in GDScript constants, functions, and annotations.

.. rst-class:: classref-introduction-group

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

A list of GDScript-specific utility functions and annotations accessible from any

script.

For the list of the global functions and constants

see :ref:`@GlobalScope<class_@GlobalScope>`.

.. rst-class:: classref-introduction-group

Tutorials
---------

- :doc:`GDScript exports <../tutorials/scripting/gdscript/gdscript_exports>`

.. rst-class:: classref-reftable-group

Methods
-------

.. table::
:widths: auto

+-------------------------------------
+----------------------------------------------------------------------------------
-----------------------------------------------------------------------------------
-----+
| :ref:`Color<class_Color>`
| :ref:`Color8<class_@GDScript_method_Color8>`\ (\ r8\: :ref:`int<class_int>`, g8\:
:ref:`int<class_int>`, b8\: :ref:`int<class_int>`, a8\: :ref:`int<class_int>` =
255\ ) |
+-------------------------------------
+----------------------------------------------------------------------------------
-----------------------------------------------------------------------------------
-----+
| |void|
| :ref:`assert<class_@GDScript_method_assert>`\ (\
condition\: :ref:`bool<class_bool>`, message\: :ref:`String<class_String>` = ""\ )
|
 +-------------------------------------
+----------------------------------------------------------------------------------
-----------------------------------------------------------------------------------
-----+
| :ref:`String<class_String>`
| :ref:`char<class_@GDScript_method_char>`\ (\ char\: :ref:`int<class_int>`\ )
|
+-------------------------------------
+----------------------------------------------------------------------------------
-----------------------------------------------------------------------------------
-----+
| :ref:`Variant<class_Variant>`
| :ref:`convert<class_@GDScript_method_convert>`\ (\
what\: :ref:`Variant<class_Variant>`, type\: :ref:`int<class_int>`\ )
|
+-------------------------------------
+----------------------------------------------------------------------------------
-----------------------------------------------------------------------------------
-----+
| :ref:`Object<class_Object>`
| :ref:`dict_to_inst<class_@GDScript_method_dict_to_inst>`\ (\
dictionary\: :ref:`Dictionary<class_Dictionary>`\ )
|
+-------------------------------------
+----------------------------------------------------------------------------------
-----------------------------------------------------------------------------------
-----+
| :ref:`Array<class_Array>`
| :ref:`get_stack<class_@GDScript_method_get_stack>`\ (\ )
|
+-------------------------------------
+----------------------------------------------------------------------------------
-----------------------------------------------------------------------------------
-----+
| :ref:`Dictionary<class_Dictionary>`
| :ref:`inst_to_dict<class_@GDScript_method_inst_to_dict>`\ (\
instance\: :ref:`Object<class_Object>`\ )
|
+-------------------------------------
+----------------------------------------------------------------------------------
-----------------------------------------------------------------------------------
-----+
| :ref:`bool<class_bool>`
| :ref:`is_instance_of<class_@GDScript_method_is_instance_of>`\ (\
value\: :ref:`Variant<class_Variant>`, type\: :ref:`Variant<class_Variant>`\ )
|
+-------------------------------------
+----------------------------------------------------------------------------------
-----------------------------------------------------------------------------------
-----+
| :ref:`int<class_int>` | :ref:`len<class_@GDScript_method_len>`\
(\ var\: :ref:`Variant<class_Variant>`\ )
|
+-------------------------------------
+----------------------------------------------------------------------------------
-----------------------------------------------------------------------------------
-----+
| :ref:`Resource<class_Resource>`
| :ref:`load<class_@GDScript_method_load>`\ (\
path\: :ref:`String<class_String>`\ )
|
+-------------------------------------
+----------------------------------------------------------------------------------
-----------------------------------------------------------------------------------
-----+
| :ref:`Resource<class_Resource>`
| :ref:`preload<class_@GDScript_method_preload>`\ (\
path\: :ref:`String<class_String>`\ )
|
+-------------------------------------
+----------------------------------------------------------------------------------
-----------------------------------------------------------------------------------
-----+
| |void|
| :ref:`print_debug<class_@GDScript_method_print_debug>`\ (\ ...\ ) |vararg|
|
+-------------------------------------
+----------------------------------------------------------------------------------
-----------------------------------------------------------------------------------
-----+
| |void|
| :ref:`print_stack<class_@GDScript_method_print_stack>`\ (\ )
|
+-------------------------------------
+----------------------------------------------------------------------------------
-----------------------------------------------------------------------------------
-----+
| :ref:`Array<class_Array>`
| :ref:`range<class_@GDScript_method_range>`\ (\ ...\ ) |vararg|
|
+-------------------------------------
+----------------------------------------------------------------------------------
-----------------------------------------------------------------------------------
-----+
| :ref:`bool<class_bool>`
| :ref:`type_exists<class_@GDScript_method_type_exists>`\ (\
type\: :ref:`StringName<class_StringName>`\ )
|
+-------------------------------------
+----------------------------------------------------------------------------------
-----------------------------------------------------------------------------------
-----+

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Constants
---------

.. _class_@GDScript_constant_PI:

.. rst-class:: classref-constant

**PI** = ``3.14159265358979`` :ref:`🔗<class_@GDScript_constant_PI>`

Constant that represents how many times the diameter of a circle fits around its
perimeter. This is equivalent to ``TAU / 2``, or 180 degrees in rotations.

.. _class_@GDScript_constant_TAU:

.. rst-class:: classref-constant

**TAU** = ``6.28318530717959`` :ref:`🔗<class_@GDScript_constant_TAU>`

The circle constant, the circumference of the unit circle in radians. This is
equivalent to ``PI * 2``, or 360 degrees in rotations.

.. _class_@GDScript_constant_INF:

.. rst-class:: classref-constant

**INF** = ``inf`` :ref:`🔗<class_@GDScript_constant_INF>`

Positive floating-point infinity. This is the result of floating-point division

when the divisor is ``0.0``. For negative infinity, use ``-INF``. Dividing by ``-
0.0`` will result in negative infinity if the numerator is positive, so dividing by
``0.0`` is not the same as dividing by ``-0.0`` (despite ``0.0 == -0.0`` returning
``true``).

\ **Warning:** Numeric infinity is only a concept with floating-point numbers, and

has no equivalent for integers. Dividing an integer number by ``0`` will not result
in :ref:`INF<class_@GDScript_constant_INF>` and will result in a run-time error
instead.

.. _class_@GDScript_constant_NAN:

.. rst-class:: classref-constant

**NAN** = ``nan`` :ref:`🔗<class_@GDScript_constant_NAN>`

"Not a Number", an invalid floating-point

value. :ref:`NAN<class_@GDScript_constant_NAN>` has special properties, including
that ``!=`` always returns ``true``, while other comparison operators always return
``false``. This is true even when comparing with itself (``NAN == NAN`` returns
``false`` and ``NAN != NAN`` returns ``true``). It is returned by some invalid
operations, such as dividing floating-point ``0.0`` by ``0.0``.

\ **Warning:** "Not a Number" is only a concept with floating-point numbers, and

has no equivalent for integers. Dividing an integer ``0`` by ``0`` will not result
in :ref:`NAN<class_@GDScript_constant_NAN>` and will result in a run-time error
instead.

.. rst-class:: classref-section-separator

----

Annotations
-----------

.. _class_@GDScript_annotation_@export:

.. rst-class:: classref-annotation

**@export**\ (\ ) :ref:`🔗<class_@GDScript_annotation_@export>`
Mark the following property as exported (editable in the Inspector dock and saved
to disk). To control the type of the exported property, use the type hint notation.

::

extends Node

enum Direction {LEFT, RIGHT, UP, DOWN}

# Built-in types.
@export var string = ""
@export var int_number = 5
@export var float_number: float = 5

# Enums.
@export var type: Variant.Type
@export var format: Image.Format
@export var direction: Direction

# Resources.
@export var image: Image
@export var custom_resource: CustomResource

# Nodes.
@export var node: Node
@export var custom_node: CustomNode

# Typed arrays.
@export var int_array: Array[int]
@export var direction_array: Array[Direction]
@export var image_array: Array[Image]
@export var node_array: Array[Node]

\ **Note:** Custom resources and nodes should be registered as global classes using
``class_name``, since the Inspector currently only supports global classes.
Otherwise, a less specific type will be exported instead.

\ **Note:** Node export is only supported in :ref:`Node<class_Node>`-derived

classes and has a number of other limitations.

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_category:

.. rst-class:: classref-annotation

**@export_category**\ (\
name\: :ref:`String<class_String>`\ ) :ref:`🔗<class_@GDScript_annotation_@export_ca
tegory>`

Define a new category for the following exported properties. This helps to organize
properties in the Inspector dock.

See
also :ref:`@GlobalScope.PROPERTY_USAGE_CATEGORY<class_@GlobalScope_constant_PROPERT
Y_USAGE_CATEGORY>`.
::

@export_category("Statistics")
@export var hp = 30
@export var speed = 1.25

\ **Note:** Categories in the Inspector dock's list usually divide properties

coming from different classes (Node, Node2D, Sprite, etc.). For better clarity,
it's recommended to
use :ref:`@export_group<class_@GDScript_annotation_@export_group>`
and :ref:`@export_subgroup<class_@GDScript_annotation_@export_subgroup>`, instead.

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_color_no_alpha:

.. rst-class:: classref-annotation

**@export_color_no_alpha**\
(\ ) :ref:`🔗<class_@GDScript_annotation_@export_color_no_alpha>`

Export a :ref:`Color<class_Color>`, :ref:`Array<class_Array>`\ \

[:ref:`Color<class_Color>`\ \], or :ref:`PackedColorArray<class_PackedColorArray>`
property without allowing its transparency (:ref:`Color.a<class_Color_property_a>`)
to be edited.

See
also :ref:`@GlobalScope.PROPERTY_HINT_COLOR_NO_ALPHA<class_@GlobalScope_constant_PR
OPERTY_HINT_COLOR_NO_ALPHA>`.

::

@export_color_no_alpha var dye_color: Color

@export_color_no_alpha var dye_colors: Array[Color]

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_custom:

.. rst-class:: classref-annotation

**@export_custom**\ (\ hint\: :ref:`PropertyHint<enum_@GlobalScope_PropertyHint>`,

hint_string\: :ref:`String<class_String>`, usage\: |bitfield|\
[:ref:`PropertyUsageFlags<enum_@GlobalScope_PropertyUsageFlags>`\] =
6\ ) :ref:`🔗<class_@GDScript_annotation_@export_custom>`

Allows you to set a custom hint, hint string, and usage flags for the exported
property. Note that there's no validation done in GDScript, it will just pass the
parameters to the editor.

::

@export_custom(PROPERTY_HINT_NONE, "suffix:m") var suffix: Vector3

\ **Note:** Regardless of the ``usage`` value,
the :ref:`@GlobalScope.PROPERTY_USAGE_SCRIPT_VARIABLE<class_@GlobalScope_constant_P
ROPERTY_USAGE_SCRIPT_VARIABLE>` flag is always added, as with any explicitly
declared script variable.

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_dir:

.. rst-class:: classref-annotation

**@export_dir**\ (\ ) :ref:`🔗<class_@GDScript_annotation_@export_dir>`

Export a :ref:`String<class_String>`, :ref:`Array<class_Array>`\ \

[:ref:`String<class_String>`\ \],
or :ref:`PackedStringArray<class_PackedStringArray>` property as a path to a
directory. The path will be limited to the project folder and its subfolders.
See :ref:`@export_global_dir<class_@GDScript_annotation_@export_global_dir>` to
allow picking from the entire filesystem.

See
also :ref:`@GlobalScope.PROPERTY_HINT_DIR<class_@GlobalScope_constant_PROPERTY_HINT
_DIR>`.

::

@export_dir var sprite_folder_path: String

@export_dir var sprite_folder_paths: Array[String]

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_enum:

.. rst-class:: classref-annotation

**@export_enum**\ (\ names\: :ref:`String<class_String>`, ...\ ) |

vararg| :ref:`🔗<class_@GDScript_annotation_@export_enum>`

Export
an :ref:`int<class_int>`, :ref:`String<class_String>`, :ref:`Array<class_Array>`\ \
[:ref:`int<class_int>`\ \], :ref:`Array<class_Array>`\ \
[:ref:`String<class_String>`\ \], :ref:`PackedByteArray<class_PackedByteArray>`, :r
ef:`PackedInt32Array<class_PackedInt32Array>`, :ref:`PackedInt64Array<class_PackedI
nt64Array>`, or :ref:`PackedStringArray<class_PackedStringArray>` property as an
enumerated list of options (or an array of options). If the property is
an :ref:`int<class_int>`, then the index of the value is stored, in the same order
the values are provided. You can add explicit values using a colon. If the property
is a :ref:`String<class_String>`, then the value is stored.

See
also :ref:`@GlobalScope.PROPERTY_HINT_ENUM<class_@GlobalScope_constant_PROPERTY_HIN
T_ENUM>`.

::
 @export_enum("Warrior", "Magician", "Thief") var character_class: int
@export_enum("Slow:30", "Average:60", "Very Fast:200") var character_speed: int
@export_enum("Rebecca", "Mary", "Leah") var character_name: String

@export_enum("Sword", "Spear", "Mace") var character_items: Array[int]

@export_enum("double_jump", "climb", "dash") var character_skills:
Array[String]

If you want to set an initial value, you must specify it explicitly:

::

@export_enum("Rebecca", "Mary", "Leah") var character_name: String = "Rebecca"

If you want to use named GDScript enums, then

use :ref:`@export<class_@GDScript_annotation_@export>` instead:

::

enum CharacterName {REBECCA, MARY, LEAH}

@export var character_name: CharacterName

enum CharacterItem {SWORD, SPEAR, MACE}

@export var character_items: Array[CharacterItem]

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_exp_easing:

.. rst-class:: classref-annotation

**@export_exp_easing**\ (\ hints\: :ref:`String<class_String>` = "", ...\ ) |

vararg| :ref:`🔗<class_@GDScript_annotation_@export_exp_easing>`

Export a floating-point property with an easing editor widget. Additional hints can
be provided to adjust the behavior of the widget. ``"attenuation"`` flips the
curve, which makes it more intuitive for editing attenuation properties.
``"positive_only"`` limits values to only be greater than or equal to zero.

See
also :ref:`@GlobalScope.PROPERTY_HINT_EXP_EASING<class_@GlobalScope_constant_PROPER
TY_HINT_EXP_EASING>`.

::

@export_exp_easing var transition_speed

@export_exp_easing("attenuation") var fading_attenuation
@export_exp_easing("positive_only") var effect_power
@export_exp_easing var speeds: Array[float]

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_file:

.. rst-class:: classref-annotation
**@export_file**\ (\ filter\: :ref:`String<class_String>` = "", ...\ ) |
vararg| :ref:`🔗<class_@GDScript_annotation_@export_file>`

Export a :ref:`String<class_String>`, :ref:`Array<class_Array>`\ \

[:ref:`String<class_String>`\ \],
or :ref:`PackedStringArray<class_PackedStringArray>` property as a path to a file.
The path will be limited to the project folder and its subfolders.
See :ref:`@export_global_file<class_@GDScript_annotation_@export_global_file>` to
allow picking from the entire filesystem.

If ``filter`` is provided, only matching files will be available for picking.

See
also :ref:`@GlobalScope.PROPERTY_HINT_FILE<class_@GlobalScope_constant_PROPERTY_HIN
T_FILE>`.

::

@export_file var sound_effect_path: String

@export_file("*.txt") var notes_path: String
@export_file var level_paths: Array[String]

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_flags:

.. rst-class:: classref-annotation

**@export_flags**\ (\ names\: :ref:`String<class_String>`, ...\ ) |

vararg| :ref:`🔗<class_@GDScript_annotation_@export_flags>`

Export an integer property as a bit flag field. This allows to store several
"checked" or ``true`` values with one property, and comfortably select them from
the Inspector dock.

See
also :ref:`@GlobalScope.PROPERTY_HINT_FLAGS<class_@GlobalScope_constant_PROPERTY_HI
NT_FLAGS>`.

::

@export_flags("Fire", "Water", "Earth", "Wind") var spell_elements = 0

You can add explicit values using a colon:

::

@export_flags("Self:4", "Allies:8", "Foes:16") var spell_targets = 0

You can also combine several flags:

::

@export_flags("Self:4", "Allies:8", "Self and Allies:12", "Foes:16")

var spell_targets = 0
\ **Note:** A flag value must be at least ``1`` and at most ``2 ** 32 - 1``.

\ **Note:** Unlike :ref:`@export_enum<class_@GDScript_annotation_@export_enum>`,

the previous explicit value is not taken into account. In the following example, A
is 16, B is 2, C is 4.

::

@export_flags("A:16", "B", "C") var x

You can also use the annotation on :ref:`Array<class_Array>`\ \

[:ref:`int<class_int>`\ \], :ref:`PackedByteArray<class_PackedByteArray>`, :ref:`Pa
ckedInt32Array<class_PackedInt32Array>`,
and :ref:`PackedInt64Array<class_PackedInt64Array>`\

::

@export_flags("Fire", "Water", "Earth", "Wind") var phase_elements: Array[int]

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_flags_2d_navigation:

.. rst-class:: classref-annotation

**@export_flags_2d_navigation**\
(\ ) :ref:`🔗<class_@GDScript_annotation_@export_flags_2d_navigation>`

Export an integer property as a bit flag field for 2D navigation layers. The widget
in the Inspector dock will use the layer names defined
in
:ref:`ProjectSettings.layer_names/2d_navigation/layer_1<class_ProjectSettings_prope
rty_layer_names/2d_navigation/layer_1>`.

See
also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_2D_NAVIGATION<class_@GlobalScope_const
ant_PROPERTY_HINT_LAYERS_2D_NAVIGATION>`.

::

@export_flags_2d_navigation var navigation_layers: int

@export_flags_2d_navigation var navigation_layers_array: Array[int]

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_flags_2d_physics:

.. rst-class:: classref-annotation

**@export_flags_2d_physics**\
(\ ) :ref:`🔗<class_@GDScript_annotation_@export_flags_2d_physics>`

Export an integer property as a bit flag field for 2D physics layers. The widget in
the Inspector dock will use the layer names defined
in
:ref:`ProjectSettings.layer_names/2d_physics/layer_1<class_ProjectSettings_property
_layer_names/2d_physics/layer_1>`.

See
also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_2D_PHYSICS<class_@GlobalScope_constant
_PROPERTY_HINT_LAYERS_2D_PHYSICS>`.

::

@export_flags_2d_physics var physics_layers: int

@export_flags_2d_physics var physics_layers_array: Array[int]

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_flags_2d_render:

.. rst-class:: classref-annotation

**@export_flags_2d_render**\
(\ ) :ref:`🔗<class_@GDScript_annotation_@export_flags_2d_render>`

Export an integer property as a bit flag field for 2D render layers. The widget in
the Inspector dock will use the layer names defined
in
:ref:`ProjectSettings.layer_names/2d_render/layer_1<class_ProjectSettings_property_
layer_names/2d_render/layer_1>`.

See
also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_2D_RENDER<class_@GlobalScope_constant_
PROPERTY_HINT_LAYERS_2D_RENDER>`.

::

@export_flags_2d_render var render_layers: int

@export_flags_2d_render var render_layers_array: Array[int]

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_flags_3d_navigation:

.. rst-class:: classref-annotation

**@export_flags_3d_navigation**\
(\ ) :ref:`🔗<class_@GDScript_annotation_@export_flags_3d_navigation>`

Export an integer property as a bit flag field for 3D navigation layers. The widget
in the Inspector dock will use the layer names defined
in
:ref:`ProjectSettings.layer_names/3d_navigation/layer_1<class_ProjectSettings_prope
rty_layer_names/3d_navigation/layer_1>`.

See
also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_3D_NAVIGATION<class_@GlobalScope_const
ant_PROPERTY_HINT_LAYERS_3D_NAVIGATION>`.
::

@export_flags_3d_navigation var navigation_layers: int

@export_flags_3d_navigation var navigation_layers_array: Array[int]

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_flags_3d_physics:

.. rst-class:: classref-annotation

**@export_flags_3d_physics**\
(\ ) :ref:`🔗<class_@GDScript_annotation_@export_flags_3d_physics>`

Export an integer property as a bit flag field for 3D physics layers. The widget in
the Inspector dock will use the layer names defined
in
:ref:`ProjectSettings.layer_names/3d_physics/layer_1<class_ProjectSettings_property
_layer_names/3d_physics/layer_1>`.

See
also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_3D_PHYSICS<class_@GlobalScope_constant
_PROPERTY_HINT_LAYERS_3D_PHYSICS>`.

::

@export_flags_3d_physics var physics_layers: int

@export_flags_3d_physics var physics_layers_array: Array[int]

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_flags_3d_render:

.. rst-class:: classref-annotation

**@export_flags_3d_render**\
(\ ) :ref:`🔗<class_@GDScript_annotation_@export_flags_3d_render>`

Export an integer property as a bit flag field for 3D render layers. The widget in
the Inspector dock will use the layer names defined
in
:ref:`ProjectSettings.layer_names/3d_render/layer_1<class_ProjectSettings_property_
layer_names/3d_render/layer_1>`.

See
also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_3D_RENDER<class_@GlobalScope_constant_
PROPERTY_HINT_LAYERS_3D_RENDER>`.

::

@export_flags_3d_render var render_layers: int

@export_flags_3d_render var render_layers_array: Array[int]

.. rst-class:: classref-item-separator
----

.. _class_@GDScript_annotation_@export_flags_avoidance:

.. rst-class:: classref-annotation

**@export_flags_avoidance**\
(\ ) :ref:`🔗<class_@GDScript_annotation_@export_flags_avoidance>`

Export an integer property as a bit flag field for navigation avoidance layers. The
widget in the Inspector dock will use the layer names defined
in
:ref:`ProjectSettings.layer_names/avoidance/layer_1<class_ProjectSettings_property_
layer_names/avoidance/layer_1>`.

See
also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_AVOIDANCE<class_@GlobalScope_constant_
PROPERTY_HINT_LAYERS_AVOIDANCE>`.

::

@export_flags_avoidance var avoidance_layers: int

@export_flags_avoidance var avoidance_layers_array: Array[int]

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_global_dir:

.. rst-class:: classref-annotation

**@export_global_dir**\
(\ ) :ref:`🔗<class_@GDScript_annotation_@export_global_dir>`

Export a :ref:`String<class_String>`, :ref:`Array<class_Array>`\ \

[:ref:`String<class_String>`\ \],
or :ref:`PackedStringArray<class_PackedStringArray>` property as an absolute path
to a directory. The path can be picked from the entire filesystem.
See :ref:`@export_dir<class_@GDScript_annotation_@export_dir>` to limit it to the
project folder and its subfolders.

See
also :ref:`@GlobalScope.PROPERTY_HINT_GLOBAL_DIR<class_@GlobalScope_constant_PROPER
TY_HINT_GLOBAL_DIR>`.

::

@export_global_dir var sprite_folder_path: String

@export_global_dir var sprite_folder_paths: Array[String]

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_global_file:

.. rst-class:: classref-annotation
**@export_global_file**\ (\ filter\: :ref:`String<class_String>` = "", ...\ ) |
vararg| :ref:`🔗<class_@GDScript_annotation_@export_global_file>`

Export a :ref:`String<class_String>`, :ref:`Array<class_Array>`\ \

[:ref:`String<class_String>`\ \],
or :ref:`PackedStringArray<class_PackedStringArray>` property as an absolute path
to a file. The path can be picked from the entire filesystem.
See :ref:`@export_file<class_@GDScript_annotation_@export_file>` to limit it to the
project folder and its subfolders.

If ``filter`` is provided, only matching files will be available for picking.

See
also :ref:`@GlobalScope.PROPERTY_HINT_GLOBAL_FILE<class_@GlobalScope_constant_PROPE
RTY_HINT_GLOBAL_FILE>`.

::

@export_global_file var sound_effect_path: String

@export_global_file("*.txt") var notes_path: String
@export_global_file var multiple_paths: Array[String]

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_group:

.. rst-class:: classref-annotation

**@export_group**\ (\ name\: :ref:`String<class_String>`,

prefix\: :ref:`String<class_String>` =
""\ ) :ref:`🔗<class_@GDScript_annotation_@export_group>`

Define a new group for the following exported properties. This helps to organize
properties in the Inspector dock. Groups can be added with an optional ``prefix``,
which would make group to only consider properties that have this prefix. The
grouping will break on the first property that doesn't have a prefix. The prefix is
also removed from the property's name in the Inspector dock.

If no ``prefix`` is provided, then every following property will be added to the

group. The group ends when then next group or category is defined. You can also
force end a group by using this annotation with empty strings for parameters,
``@export_group("", "")``.

Groups cannot be nested,

use :ref:`@export_subgroup<class_@GDScript_annotation_@export_subgroup>` to add
subgroups within groups.

See
also :ref:`@GlobalScope.PROPERTY_USAGE_GROUP<class_@GlobalScope_constant_PROPERTY_U
SAGE_GROUP>`.

::

@export_group("Racer Properties")
@export var nickname = "Nick"
@export var age = 26
 @export_group("Car Properties", "car_")
@export var car_label = "Speedy"
@export var car_number = 3

@export_group("", "")
@export var ungrouped_number = 3

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_multiline:

.. rst-class:: classref-annotation

**@export_multiline**\ (\ ) :ref:`🔗<class_@GDScript_annotation_@export_multiline>`

Export a :ref:`String<class_String>`, :ref:`Array<class_Array>`\ \

[:ref:`String<class_String>`\ \], :ref:`PackedStringArray<class_PackedStringArray>`
, :ref:`Dictionary<class_Dictionary>` or :ref:`Array<class_Array>`\ \
[:ref:`Dictionary<class_Dictionary>`\ \] property with a
large :ref:`TextEdit<class_TextEdit>` widget instead of
a :ref:`LineEdit<class_LineEdit>`. This adds support for multiline content and
makes it easier to edit large amount of text stored in the property.

See
also :ref:`@GlobalScope.PROPERTY_HINT_MULTILINE_TEXT<class_@GlobalScope_constant_PR
OPERTY_HINT_MULTILINE_TEXT>`.

::

@export_multiline var character_biography

@export_multiline var npc_dialogs: Array[String]

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_node_path:

.. rst-class:: classref-annotation

**@export_node_path**\ (\ type\: :ref:`String<class_String>` = "", ...\ ) |

vararg| :ref:`🔗<class_@GDScript_annotation_@export_node_path>`

Export a :ref:`NodePath<class_NodePath>` or :ref:`Array<class_Array>`\ \

[:ref:`NodePath<class_NodePath>`\ \] property with a filter for allowed node types.

See
also :ref:`@GlobalScope.PROPERTY_HINT_NODE_PATH_VALID_TYPES<class_@GlobalScope_cons
tant_PROPERTY_HINT_NODE_PATH_VALID_TYPES>`.

::

@export_node_path("Button", "TouchScreenButton") var some_button

@export_node_path("Button", "TouchScreenButton") var many_buttons:
Array[NodePath]

\ **Note:** The type must be a native class or a globally registered script (using
the ``class_name`` keyword) that inherits :ref:`Node<class_Node>`.

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_placeholder:

.. rst-class:: classref-annotation

**@export_placeholder**\ (\
placeholder\: :ref:`String<class_String>`\ ) :ref:`🔗<class_@GDScript_annotation_@ex
port_placeholder>`

Export a :ref:`String<class_String>`, :ref:`Array<class_Array>`\ \

[:ref:`String<class_String>`\ \],
or :ref:`PackedStringArray<class_PackedStringArray>` property with a placeholder
text displayed in the editor widget when no value is present.

See
also :ref:`@GlobalScope.PROPERTY_HINT_PLACEHOLDER_TEXT<class_@GlobalScope_constant_
PROPERTY_HINT_PLACEHOLDER_TEXT>`.

::

@export_placeholder("Name in lowercase") var character_id: String

@export_placeholder("Name in lowercase") var friend_ids: Array[String]

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_range:

.. rst-class:: classref-annotation

**@export_range**\ (\ min\: :ref:`float<class_float>`,

max\: :ref:`float<class_float>`, step\: :ref:`float<class_float>` = 1.0,
extra_hints\: :ref:`String<class_String>` = "", ...\ ) |
vararg| :ref:`🔗<class_@GDScript_annotation_@export_range>`

Export
an :ref:`int<class_int>`, :ref:`float<class_float>`, :ref:`Array<class_Array>`\ \
[:ref:`int<class_int>`\ \], :ref:`Array<class_Array>`\ \[:ref:`float<class_float>`\
\], :ref:`PackedByteArray<class_PackedByteArray>`, :ref:`PackedInt32Array<class_Pac
kedInt32Array>`, :ref:`PackedInt64Array<class_PackedInt64Array>`, :ref:`PackedFloat
32Array<class_PackedFloat32Array>`,
or :ref:`PackedFloat64Array<class_PackedFloat64Array>` property as a range value.
The range must be defined by ``min`` and ``max``, as well as an optional ``step``
and a variety of extra hints. The ``step`` defaults to ``1`` for integer
properties. For floating-point numbers this value depends on
your
:ref:`EditorSettings.interface/inspector/default_float_step<class_EditorSettings_pr
operty_interface/inspector/default_float_step>` setting.

If hints ``"or_greater"`` and ``"or_less"`` are provided, the editor widget will
not cap the value at range boundaries. The ``"exp"`` hint will make the edited
values on range to change exponentially. The ``"hide_slider"`` hint will hide the
slider element of the editor widget.
Hints also allow to indicate the units for the edited value. Using
``"radians_as_degrees"`` you can specify that the actual value is in radians, but
should be displayed in degrees in the Inspector dock (the range values are also in
degrees). ``"degrees"`` allows to add a degree sign as a unit suffix (the value is
unchanged). Finally, a custom suffix can be provided using ``"suffix:unit"``, where
"unit" can be any string.

See
also :ref:`@GlobalScope.PROPERTY_HINT_RANGE<class_@GlobalScope_constant_PROPERTY_HI
NT_RANGE>`.

::

@export_range(0, 20) var number

@export_range(-10, 20) var number
@export_range(-10, 20, 0.2) var number: float
@export_range(0, 20) var numbers: Array[float]

@export_range(0, 100, 1, "or_greater") var power_percent

@export_range(0, 100, 1, "or_greater", "or_less") var health_delta

@export_range(-180, 180, 0.001, "radians_as_degrees") var angle_radians

@export_range(0, 360, 1, "degrees") var angle_degrees
@export_range(-8, 8, 2, "suffix:px") var target_offset

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_storage:

.. rst-class:: classref-annotation

**@export_storage**\ (\ ) :ref:`🔗<class_@GDScript_annotation_@export_storage>`

Export a property
with :ref:`@GlobalScope.PROPERTY_USAGE_STORAGE<class_@GlobalScope_constant_PROPERTY
_USAGE_STORAGE>` flag. The property is not displayed in the editor, but it is
serialized and stored in the scene or resource file. This can be useful
for :ref:`@tool<class_@GDScript_annotation_@tool>` scripts. Also the property value
is copied when :ref:`Resource.duplicate<class_Resource_method_duplicate>`
or :ref:`Node.duplicate<class_Node_method_duplicate>` is called, unlike non-
exported variables.

::

var a # Not stored in the file, not displayed in the editor.

@export_storage var b # Stored in the file, not displayed in the editor.
@export var c: int # Stored in the file, displayed in the editor.

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@export_subgroup:

.. rst-class:: classref-annotation
**@export_subgroup**\ (\ name\: :ref:`String<class_String>`,
prefix\: :ref:`String<class_String>` =
""\ ) :ref:`🔗<class_@GDScript_annotation_@export_subgroup>`

Define a new subgroup for the following exported properties. This helps to organize
properties in the Inspector dock. Subgroups work exactly like groups, except they
need a parent group to exist.
See :ref:`@export_group<class_@GDScript_annotation_@export_group>`.

See
also :ref:`@GlobalScope.PROPERTY_USAGE_SUBGROUP<class_@GlobalScope_constant_PROPERT
Y_USAGE_SUBGROUP>`.

::

@export_group("Racer Properties")
@export var nickname = "Nick"
@export var age = 26

@export_subgroup("Car Properties", "car_")

@export var car_label = "Speedy"
@export var car_number = 3

\ **Note:** Subgroups cannot be nested, they only provide one extra level of depth.
Just like the next group ends the previous group, so do the subsequent subgroups.

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@icon:

.. rst-class:: classref-annotation

**@icon**\ (\
icon_path\: :ref:`String<class_String>`\ ) :ref:`🔗<class_@GDScript_annotation_@icon
>`

Add a custom icon to the current script. The icon specified at ``icon_path`` is
displayed in the Scene dock for every node of that class, as well as in various
editor dialogs.

::

@icon("res://path/to/class/icon.svg")

\ **Note:** Only the script can have a custom icon. Inner classes are not
supported.

\ **Note:** As annotations describe their subject,

the :ref:`@icon<class_@GDScript_annotation_@icon>` annotation must be placed before
the class definition and inheritance.

\ **Note:** Unlike other annotations, the argument of

the :ref:`@icon<class_@GDScript_annotation_@icon>` annotation must be a string
literal (constant expressions are not supported).

.. rst-class:: classref-item-separator
----

.. _class_@GDScript_annotation_@onready:

.. rst-class:: classref-annotation

**@onready**\ (\ ) :ref:`🔗<class_@GDScript_annotation_@onready>`

Mark the following property as assigned when the :ref:`Node<class_Node>` is ready.

Values for these properties are not assigned immediately when the node is
initialized (:ref:`Object._init<class_Object_private_method__init>`), and instead
are computed and stored right
before :ref:`Node._ready<class_Node_private_method__ready>`.

::

@onready var character_name: Label = $Label

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@rpc:

.. rst-class:: classref-annotation

**@rpc**\ (\ mode\: :ref:`String<class_String>` = "authority",

sync\: :ref:`String<class_String>` = "call_remote",
transfer_mode\: :ref:`String<class_String>` = "unreliable",
transfer_channel\: :ref:`int<class_int>` =
0\ ) :ref:`🔗<class_@GDScript_annotation_@rpc>`

Mark the following method for remote procedure calls. See :doc:`High-level
multiplayer <../tutorials/networking/high_level_multiplayer>`.

If ``mode`` is set as ``"any_peer"``, allows any peer to call this RPC function.
Otherwise, only the authority peer is allowed to call it and ``mode`` should be
kept as ``"authority"``. When configuring functions as RPCs
with :ref:`Node.rpc_config<class_Node_method_rpc_config>`, each of these modes
respectively corresponds to
the :ref:`MultiplayerAPI.RPC_MODE_AUTHORITY<class_MultiplayerAPI_constant_RPC_MODE_
AUTHORITY>`
and :ref:`MultiplayerAPI.RPC_MODE_ANY_PEER<class_MultiplayerAPI_constant_RPC_MODE_A
NY_PEER>` RPC modes. See :ref:`RPCMode<enum_MultiplayerAPI_RPCMode>`. If a peer
that is not the authority tries to call a function that is only allowed for the
authority, the function will not be executed. If the error can be detected locally
(when the RPC configuration is consistent between the local and the remote peer),
an error message will be displayed on the sender peer. Otherwise, the remote peer
will detect the error and print an error there.

If ``sync`` is set as ``"call_remote"``, the function will only be executed on the

remote peer, but not locally. To run this function locally too, set ``sync`` to
``"call_local"``. When configuring functions as RPCs
with :ref:`Node.rpc_config<class_Node_method_rpc_config>`, this is equivalent to
setting ``call_local`` to ``true``.

The ``transfer_mode`` accepted values are ``"unreliable"``,

``"unreliable_ordered"``, or ``"reliable"``. It sets the transfer mode of the
underlying :ref:`MultiplayerPeer<class_MultiplayerPeer>`.
See :ref:`MultiplayerPeer.transfer_mode<class_MultiplayerPeer_property_transfer_mod
e>`.

The ``transfer_channel`` defines the channel of the

underlying :ref:`MultiplayerPeer<class_MultiplayerPeer>`.
See :ref:`MultiplayerPeer.transfer_channel<class_MultiplayerPeer_property_transfer_
channel>`.

The order of ``mode``, ``sync`` and ``transfer_mode`` does not matter, but values
related to the same argument must not be used more than once. ``transfer_channel``
always has to be the 4th argument (you must specify 3 preceding arguments).

::

@rpc
func fn(): pass

@rpc("any_peer", "unreliable_ordered")
func fn_update_pos(): pass

@rpc("authority", "call_remote", "unreliable", 0) # Equivalent to @rpc

func fn_default(): pass

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@static_unload:

.. rst-class:: classref-annotation

**@static_unload**\ (\ ) :ref:`🔗<class_@GDScript_annotation_@static_unload>`

Make a script with static variables to not persist after all references are lost.
If the script is loaded again the static variables will revert to their default
values.

\ **Note:** As annotations describe their subject,

the :ref:`@static_unload<class_@GDScript_annotation_@static_unload>` annotation
must be placed before the class definition and inheritance.

\ **Warning:** Currently, due to a bug, scripts are never freed, even

if :ref:`@static_unload<class_@GDScript_annotation_@static_unload>` annotation is
used.

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@tool:

.. rst-class:: classref-annotation

**@tool**\ (\ ) :ref:`🔗<class_@GDScript_annotation_@tool>`

Mark the current script as a tool script, allowing it to be loaded and executed by
the editor. See :doc:`Running code in the editor
<../tutorials/plugins/running_code_in_the_editor>`.
::

@tool
extends Node

\ **Note:** As annotations describe their subject,

the :ref:`@tool<class_@GDScript_annotation_@tool>` annotation must be placed before
the class definition and inheritance.

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_annotation_@warning_ignore:

.. rst-class:: classref-annotation

**@warning_ignore**\ (\ warning\: :ref:`String<class_String>`, ...\ ) |

vararg| :ref:`🔗<class_@GDScript_annotation_@warning_ignore>`

Mark the following statement to ignore the specified ``warning``.

See :doc:`GDScript warning system
<../tutorials/scripting/gdscript/warning_system>`.

::

func test():
print("hello")
return
@warning_ignore("unreachable_code")
print("unreachable")

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

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

.. _class_@GDScript_method_Color8:

.. rst-class:: classref-method

:ref:`Color<class_Color>` **Color8**\ (\ r8\: :ref:`int<class_int>`,

g8\: :ref:`int<class_int>`, b8\: :ref:`int<class_int>`, a8\: :ref:`int<class_int>`
= 255\ ) :ref:`🔗<class_@GDScript_method_Color8>`

Returns a :ref:`Color<class_Color>` constructed from red (``r8``), green (``g8``),

blue (``b8``), and optionally alpha (``a8``) integer channels, each divided by
``255.0`` for their final value. Using :ref:`Color8<class_@GDScript_method_Color8>`
instead of the standard :ref:`Color<class_Color>` constructor is useful when you
need to match exact color values in an :ref:`Image<class_Image>`.

::

var red = Color8(255, 0, 0) # Same as Color(1, 0, 0).

var dark_blue = Color8(0, 0, 51) # Same as Color(0, 0, 0.2).
 var my_color = Color8(306, 255, 0, 102) # Same as Color(1.2, 1, 0, 0.4).

\ **Note:** Due to the lower precision

of :ref:`Color8<class_@GDScript_method_Color8>` compared to the
standard :ref:`Color<class_Color>` constructor, a color created
with :ref:`Color8<class_@GDScript_method_Color8>` will generally not be equal to
the same color created with the standard :ref:`Color<class_Color>` constructor. Use
:ref:`Color.is_equal_approx<class_Color_method_is_equal_approx>` for comparisons to
avoid issues with floating-point precision error.

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_method_assert:

.. rst-class:: classref-method

|void| **assert**\ (\ condition\: :ref:`bool<class_bool>`,

message\: :ref:`String<class_String>` =
""\ ) :ref:`🔗<class_@GDScript_method_assert>`

Asserts that the ``condition`` is ``true``. If the ``condition`` is ``false``, an

error is generated. When running from the editor, the running project will also be
paused until you resume it. This can be used as a stronger form
of :ref:`@GlobalScope.push_error<class_@GlobalScope_method_push_error>` for
reporting errors to project developers or add-on users.

An optional ``message`` can be shown in addition to the generic "Assertion failed"

message. You can use this to provide additional details about why the assertion
failed.

\ **Warning:** For performance reasons, the code

inside :ref:`assert<class_@GDScript_method_assert>` is only executed in debug
builds or when running the project from the editor. Don't include code that has
side effects in an :ref:`assert<class_@GDScript_method_assert>` call. Otherwise,
the project will behave differently when exported in release mode.

::

# Imagine we always want speed to be between 0 and 20.

var speed = -10
assert(speed < 20) # True, the program will continue.
assert(speed >= 0) # False, the program will stop.
assert(speed >= 0 and speed < 20) # You can also combine the two conditional
statements in one check.
assert(speed < 20, "the speed limit is 20") # Show a message.

\ **Note:** :ref:`assert<class_@GDScript_method_assert>` is a keyword, not a

function. So you cannot access it as a :ref:`Callable<class_Callable>` or use it
inside expressions.

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_method_char:

.. rst-class:: classref-method
:ref:`String<class_String>` **char**\ (\
char\: :ref:`int<class_int>`\ ) :ref:`🔗<class_@GDScript_method_char>`

Returns a single character (as a :ref:`String<class_String>`) of the given Unicode

code point (which is compatible with ASCII code).

::

a = char(65) # a is "A"
a = char(65 + 32) # a is "a"
a = char(8364) # a is "€"

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_method_convert:

.. rst-class:: classref-method

:ref:`Variant<class_Variant>` **convert**\ (\ what\: :ref:`Variant<class_Variant>`,

type\: :ref:`int<class_int>`\ ) :ref:`🔗<class_@GDScript_method_convert>`

**Deprecated:**
Use :ref:`@GlobalScope.type_convert<class_@GlobalScope_method_type_convert>`
instead.

Converts ``what`` to ``type`` in the best way possible. The ``type`` uses
the :ref:`Variant.Type<enum_@GlobalScope_Variant.Type>` values.

::

var a = [4, 2.5, 1.2]

print(a is Array) # Prints true

var b = convert(a, TYPE_PACKED_BYTE_ARRAY)

print(b) # Prints [4, 2, 1]
print(b is Array) # Prints false

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_method_dict_to_inst:

.. rst-class:: classref-method

:ref:`Object<class_Object>` **dict_to_inst**\ (\
dictionary\: :ref:`Dictionary<class_Dictionary>`\ ) :ref:`🔗<class_@GDScript_method_
dict_to_inst>`

Converts a ``dictionary`` (created

with :ref:`inst_to_dict<class_@GDScript_method_inst_to_dict>`) back to an Object
instance. Can be useful for deserializing.

.. rst-class:: classref-item-separator

----
.. _class_@GDScript_method_get_stack:

.. rst-class:: classref-method

:ref:`Array<class_Array>` **get_stack**\
(\ ) :ref:`🔗<class_@GDScript_method_get_stack>`

Returns an array of dictionaries representing the current call stack. See

also :ref:`print_stack<class_@GDScript_method_print_stack>`.

::

func _ready():
foo()

func foo():
bar()

func bar():
print(get_stack())

Starting from ``_ready()``, ``bar()`` would print:

.. code:: text

[{function:bar, line:12, source:res://script.gd}, {function:foo, line:9,

source:res://script.gd}, {function:_ready, line:6, source:res://script.gd}]

\ **Note:** This function only works if the running instance is connected to a

debugging server (i.e. an editor
instance). :ref:`get_stack<class_@GDScript_method_get_stack>` will not work in
projects exported in release mode, or in projects exported in debug mode if not
connected to a debugging server.

\ **Note:** Calling this function from a :ref:`Thread<class_Thread>` is not

supported. Doing so will return an empty array.

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_method_inst_to_dict:

.. rst-class:: classref-method

:ref:`Dictionary<class_Dictionary>` **inst_to_dict**\ (\
instance\: :ref:`Object<class_Object>`\ ) :ref:`🔗<class_@GDScript_method_inst_to_di
ct>`

Returns the passed ``instance`` converted to a Dictionary. Can be useful for

serializing.

\ **Note:** Cannot be used to serialize objects with built-in scripts attached or

objects allocated within built-in scripts.

::

var foo = "bar"

 func _ready():
var d = inst_to_dict(self)
print(d.keys())
print(d.values())

Prints out:

.. code:: text

[@subpath, @path, foo]

[, res://test.gd, bar]

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_method_is_instance_of:

.. rst-class:: classref-method

:ref:`bool<class_bool>` **is_instance_of**\ (\
value\: :ref:`Variant<class_Variant>`,
type\: :ref:`Variant<class_Variant>`\ ) :ref:`🔗<class_@GDScript_method_is_instance_
of>`

Returns ``true`` if ``value`` is an instance of ``type``. The ``type`` value must

be one of the following:

- A constant from the :ref:`Variant.Type<enum_@GlobalScope_Variant.Type>`

enumeration, for
example :ref:`@GlobalScope.TYPE_INT<class_@GlobalScope_constant_TYPE_INT>`.

- An :ref:`Object<class_Object>`-derived class which exists

in :ref:`ClassDB<class_ClassDB>`, for example :ref:`Node<class_Node>`.

- A :ref:`Script<class_Script>` (you can use any class, including inner one).

Unlike the right operand of the ``is`` operator, ``type`` can be a non-constant
value. The ``is`` operator supports more features (such as typed arrays). Use the
operator instead of this method if you do not need dynamic type checking.

Examples:

::

print(is_instance_of(a, TYPE_INT))
print(is_instance_of(a, Node))
print(is_instance_of(a, MyClass))
print(is_instance_of(a, MyClass.InnerClass))

\ **Note:** If ``value`` and/or ``type`` are freed objects

(see :ref:`@GlobalScope.is_instance_valid<class_@GlobalScope_method_is_instance_val
id>`), or ``type`` is not one of the above options, this method will raise a
runtime error.

See
also :ref:`@GlobalScope.typeof<class_@GlobalScope_method_typeof>`, :ref:`type_exist
s<class_@GDScript_method_type_exists>`, :ref:`Array.is_same_typed<class_Array_metho
d_is_same_typed>` (and other :ref:`Array<class_Array>` methods).
.. rst-class:: classref-item-separator

----

.. _class_@GDScript_method_len:

.. rst-class:: classref-method

:ref:`int<class_int>` **len**\ (\
var\: :ref:`Variant<class_Variant>`\ ) :ref:`🔗<class_@GDScript_method_len>`

Returns the length of the given Variant ``var``. The length can be the character
count of a :ref:`String<class_String>` or :ref:`StringName<class_StringName>`, the
element count of any array type, or the size of
a :ref:`Dictionary<class_Dictionary>`. For every other Variant type, a run-time
error is generated and execution is stopped.

::

a = [1, 2, 3, 4]
len(a) # Returns 4

b = "Hello!"
len(b) # Returns 6

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_method_load:

.. rst-class:: classref-method

:ref:`Resource<class_Resource>` **load**\ (\
path\: :ref:`String<class_String>`\ ) :ref:`🔗<class_@GDScript_method_load>`

Returns a :ref:`Resource<class_Resource>` from the filesystem located at the

absolute ``path``. Unless it's already referenced elsewhere (such as in another
script or in the scene), the resource is loaded from disk on function call, which
might cause a slight delay, especially when loading large scenes. To avoid
unnecessary delays when loading something multiple times, either store the resource
in a variable or use :ref:`preload<class_@GDScript_method_preload>`. This method is
equivalent of using :ref:`ResourceLoader.load<class_ResourceLoader_method_load>`
with :ref:`ResourceLoader.CACHE_MODE_REUSE<class_ResourceLoader_constant_CACHE_MODE
_REUSE>`.

\ **Note:** Resource paths can be obtained by right-clicking on a resource in the

FileSystem dock and choosing "Copy Path", or by dragging the file from the
FileSystem dock into the current script.

::

# Load a scene called "main" located in the root of the project directory and
cache it in a variable.
var main = load("res://main.tscn") # main will contain a PackedScene resource.

\ **Important:** Relative paths are *not* relative to the script calling this
method, instead it is prefixed with ``"res://"``. Loading from relative paths might
not work as expected.

This function is a simplified version

of :ref:`ResourceLoader.load<class_ResourceLoader_method_load>`, which can be used
for more advanced scenarios.

\ **Note:** Files have to be imported into the engine first to load them using this
function. If you want to load :ref:`Image<class_Image>`\ s at run-time, you may use
:ref:`Image.load<class_Image_method_load>`. If you want to import audio files, you
can use the snippet described
in :ref:`AudioStreamMP3.data<class_AudioStreamMP3_property_data>`.

\ **Note:** If
:ref:`ProjectSettings.editor/export/convert_text_resources_to_binary<class_ProjectS
ettings_property_editor/export/convert_text_resources_to_binary>` is
``true``, :ref:`load<class_@GDScript_method_load>` will not be able to read
converted files in an exported project. If you rely on run-time loading of files
present within the PCK, set
:ref:`ProjectSettings.editor/export/convert_text_resources_to_binary<class_ProjectS
ettings_property_editor/export/convert_text_resources_to_binary>` to ``false``.

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_method_preload:

.. rst-class:: classref-method

:ref:`Resource<class_Resource>` **preload**\ (\ path\: :ref:`String<class_String>`\

) :ref:`🔗<class_@GDScript_method_preload>`

Returns a :ref:`Resource<class_Resource>` from the filesystem located at ``path``.

During run-time, the resource is loaded when the script is being parsed. This
function effectively acts as a reference to that resource. Note that this function
requires ``path`` to be a constant :ref:`String<class_String>`. If you want to load
a resource from a dynamic/variable path,
use :ref:`load<class_@GDScript_method_load>`.

\ **Note:** Resource paths can be obtained by right-clicking on a resource in the

Assets Panel and choosing "Copy Path", or by dragging the file from the FileSystem
dock into the current script.

::

# Create instance of a scene.

var diamond = preload("res://diamond.tscn").instantiate()

\ **Note:** :ref:`preload<class_@GDScript_method_preload>` is a keyword, not a

function. So you cannot access it as a :ref:`Callable<class_Callable>`.

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_method_print_debug:

.. rst-class:: classref-method
|void| **print_debug**\ (\ ...\ ) |
vararg| :ref:`🔗<class_@GDScript_method_print_debug>`

Like :ref:`@GlobalScope.print<class_@GlobalScope_method_print>`, but includes the

current stack frame when running with the debugger turned on.

The output in the console may look like the following:

.. code:: text

Test print
At: res://test.gd:15:_process()

\ **Note:** Calling this function from a :ref:`Thread<class_Thread>` is not

supported. Doing so will instead print the thread ID.

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_method_print_stack:

.. rst-class:: classref-method

|void| **print_stack**\ (\ ) :ref:`🔗<class_@GDScript_method_print_stack>`

Prints a stack trace at the current code location. See

also :ref:`get_stack<class_@GDScript_method_get_stack>`.

The output in the console may look like the following:

.. code:: text

Frame 0 - res://test.gd:16 in function '_process'

\ **Note:** This function only works if the running instance is connected to a

debugging server (i.e. an editor
instance). :ref:`print_stack<class_@GDScript_method_print_stack>` will not work in
projects exported in release mode, or in projects exported in debug mode if not
connected to a debugging server.

\ **Note:** Calling this function from a :ref:`Thread<class_Thread>` is not

supported. Doing so will instead print the thread ID.

.. rst-class:: classref-item-separator

----

.. _class_@GDScript_method_range:

.. rst-class:: classref-method

:ref:`Array<class_Array>` **range**\ (\ ...\ ) |

vararg| :ref:`🔗<class_@GDScript_method_range>`

Returns an array with the given range. :ref:`range<class_@GDScript_method_range>`

can be called in three ways:

\ ``range(n: int)``: Starts from 0, increases by steps of 1, and stops *before*

``n``. The argument ``n`` is **exclusive**.

\ ``range(b: int, n: int)``: Starts from ``b``, increases by steps of 1, and stops
*before* ``n``. The arguments ``b`` and ``n`` are **inclusive** and **exclusive**,
respectively.

\ ``range(b: int, n: int, s: int)``: Starts from ``b``, increases/decreases by

steps of ``s``, and stops *before* ``n``. The arguments ``b`` and ``n`` are
**inclusive** and **exclusive**, respectively. The argument ``s`` **can** be
negative, but not ``0``. If ``s`` is ``0``, an error message is printed.

\ :ref:`range<class_@GDScript_method_range>` converts all arguments

to :ref:`int<class_int>` before processing.

\ **Note:** Returns an empty array if no value meets the value constraint (e.g.
``range(2, 5, -1)`` or ``range(5, 5, 1)``).

Examples:

::

print(range(4)) # Prints [0, 1, 2, 3]

print(range(2, 5)) # Prints [2, 3, 4]
print(range(0, 6, 2)) # Prints [0, 2, 4]
print(range(4, 1, -1)) # Prints [4, 3, 2]

To iterate over an :ref:`Array<class_Array>` backwards, use:

::

var array = [3, 6, 9]

for i in range(array.size() - 1, -1, -1):
print(array[i])

Output:

.. code:: text

9
6
3

To iterate over :ref:`float<class_float>`, convert them in the loop.

::

for i in range (3, 0, -1):

print(i / 10.0)

Output:

.. code:: text

0.3
0.2
0.1

.. rst-class:: classref-item-separator
----

.. _class_@GDScript_method_type_exists:

.. rst-class:: classref-method

:ref:`bool<class_bool>` **type_exists**\ (\
type\: :ref:`StringName<class_StringName>`\ ) :ref:`🔗<class_@GDScript_method_type_e
xists>`

Returns ``true`` if the given :ref:`Object<class_Object>`-derived class exists

in :ref:`ClassDB<class_ClassDB>`. Note that :ref:`Variant<class_Variant>` data
types are not registered in :ref:`ClassDB<class_ClassDB>`.

::

type_exists("Sprite2D") # Returns true

type_exists("NonExistentClass") # Returns false

.. |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.)`
.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a
bitmask of the following flags.)`
.. |void| replace:: :abbr:`void (No return value.)`