godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2025-12-31 17:49:03 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
4.0
godot-docs/classes/class_@gdscript.rst
Godot Organization c39e8f8635 classref: Sync with current 4.0 branch (cfedb0a)
2023-07-24 10:19:37 +00:00

1090 lines
45 KiB
ReStructuredText
Raw Permalink Blame History

:github_url: hide
.. DO NOT EDIT THIS FILE!!!
.. Generated automatically from Godot engine sources.
.. Generator: https://github.com/godotengine/godot/tree/4.0/doc/tools/make_rst.py.
.. XML source: https://github.com/godotengine/godot/tree/4.0/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>` **(** :ref:`int<class_int>` r8, :ref:`int<class_int>` g8, :ref:`int<class_int>` b8, :ref:`int<class_int>` a8=255 **)** |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`assert<class_@GDScript_method_assert>` **(** :ref:`bool<class_bool>` condition, :ref:`String<class_String>` message="" **)** |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`String<class_String>` | :ref:`char<class_@GDScript_method_char>` **(** :ref:`int<class_int>` char **)** |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Variant<class_Variant>` | :ref:`convert<class_@GDScript_method_convert>` **(** :ref:`Variant<class_Variant>` what, :ref:`int<class_int>` type **)** |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Object<class_Object>` | :ref:`dict_to_inst<class_@GDScript_method_dict_to_inst>` **(** :ref:`Dictionary<class_Dictionary>` 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>` **(** :ref:`Object<class_Object>` instance **)** |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>` | :ref:`is_instance_of<class_@GDScript_method_is_instance_of>` **(** :ref:`Variant<class_Variant>` value, :ref:`Variant<class_Variant>` type **)** |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`int<class_int>` | :ref:`len<class_@GDScript_method_len>` **(** :ref:`Variant<class_Variant>` var **)** |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Resource<class_Resource>` | :ref:`load<class_@GDScript_method_load>` **(** :ref:`String<class_String>` path **)** |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Resource<class_Resource>` | :ref:`preload<class_@GDScript_method_preload>` **(** :ref:`String<class_String>` path **)** |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 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>` **(** :ref:`StringName<class_StringName>` type **)** |
+-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
.. rst-class:: classref-section-separator
----
.. rst-class:: classref-descriptions-group
Constants
---------
.. _class_@GDScript_constant_PI:
.. rst-class:: classref-constant
**PI** = ``3.14159265358979``
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``
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``
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``
"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** **(** **)**
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.
::
@export var string = ""
@export var int_number = 5
@export var float_number: float = 5
@export var image: Image
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_annotation_@export_category:
.. rst-class:: classref-annotation
**@export_category** **(** :ref:`String<class_String>` name **)**
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_PROPERTY_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** **(** **)**
Export a :ref:`Color<class_Color>` 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_PROPERTY_HINT_COLOR_NO_ALPHA>`.
::
@export_color_no_alpha var dye_color: Color
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_annotation_@export_dir:
.. rst-class:: classref-annotation
**@export_dir** **(** **)**
Export a :ref:`String<class_String>` 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
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_annotation_@export_enum:
.. rst-class:: classref-annotation
**@export_enum** **(** :ref:`String<class_String>` names, ... **)** |vararg|
Export an :ref:`int<class_int>` or :ref:`String<class_String>` property as an enumerated list 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_HINT_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
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
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_annotation_@export_exp_easing:
.. rst-class:: classref-annotation
**@export_exp_easing** **(** :ref:`String<class_String>` hints="", ... **)** |vararg|
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_PROPERTY_HINT_EXP_EASING>`.
::
@export_exp_easing var transition_speed
@export_exp_easing("attenuation") var fading_attenuation
@export_exp_easing("positive_only") var effect_power
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_annotation_@export_file:
.. rst-class:: classref-annotation
**@export_file** **(** :ref:`String<class_String>` filter="", ... **)** |vararg|
Export a :ref:`String<class_String>` 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_HINT_FILE>`.
::
@export_file var sound_effect_path: String
@export_file("*.txt") var notes_path: String
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_annotation_@export_flags:
.. rst-class:: classref-annotation
**@export_flags** **(** :ref:`String<class_String>` names, ... **)** |vararg|
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_HINT_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
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_annotation_@export_flags_2d_navigation:
.. rst-class:: classref-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_property_layer_names/2d_navigation/layer_1>`.
See also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_2D_NAVIGATION<class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_2D_NAVIGATION>`.
::
@export_flags_2d_navigation var navigation_layers: int
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_annotation_@export_flags_2d_physics:
.. rst-class:: classref-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
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_annotation_@export_flags_2d_render:
.. rst-class:: classref-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
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_annotation_@export_flags_3d_navigation:
.. rst-class:: classref-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_property_layer_names/3d_navigation/layer_1>`.
See also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_3D_NAVIGATION<class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_3D_NAVIGATION>`.
::
@export_flags_3d_navigation var navigation_layers: int
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_annotation_@export_flags_3d_physics:
.. rst-class:: classref-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
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_annotation_@export_flags_3d_render:
.. rst-class:: classref-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
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_annotation_@export_global_dir:
.. rst-class:: classref-annotation
**@export_global_dir** **(** **)**
Export a :ref:`String<class_String>` 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_PROPERTY_HINT_GLOBAL_DIR>`.
::
@export_global_dir var sprite_folder_path: String
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_annotation_@export_global_file:
.. rst-class:: classref-annotation
**@export_global_file** **(** :ref:`String<class_String>` filter="", ... **)** |vararg|
Export a :ref:`String<class_String>` 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_PROPERTY_HINT_GLOBAL_FILE>`.
::
@export_global_file var sound_effect_path: String
@export_global_file("*.txt") var notes_path: String
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_annotation_@export_group:
.. rst-class:: classref-annotation
**@export_group** **(** :ref:`String<class_String>` name, :ref:`String<class_String>` prefix="" **)**
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_USAGE_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** **(** **)**
Export a :ref:`String<class_String>` 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_PROPERTY_HINT_MULTILINE_TEXT>`.
::
@export_multiline var character_biography
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_annotation_@export_node_path:
.. rst-class:: classref-annotation
**@export_node_path** **(** :ref:`String<class_String>` type="", ... **)** |vararg|
Export a :ref:`NodePath<class_NodePath>` property with a filter for allowed node types.
See also :ref:`@GlobalScope.PROPERTY_HINT_NODE_PATH_VALID_TYPES<class_@GlobalScope_constant_PROPERTY_HINT_NODE_PATH_VALID_TYPES>`.
::
@export_node_path("Button", "TouchScreenButton") var some_button
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_annotation_@export_placeholder:
.. rst-class:: classref-annotation
**@export_placeholder** **(** :ref:`String<class_String>` placeholder **)**
Export a :ref:`String<class_String>` 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
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_annotation_@export_range:
.. rst-class:: classref-annotation
**@export_range** **(** :ref:`float<class_float>` min, :ref:`float<class_float>` max, :ref:`float<class_float>` step=1.0, :ref:`String<class_String>` extra_hints="", ... **)** |vararg|
Export an :ref:`int<class_int>` or :ref:`float<class_float>` 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 ``EditorSettings.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"`` you can specify that the actual value is in radians, but should be displayed in degrees in the Inspector dock. ``"degrees"`` allows to add a degree sign as a unit suffix. 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_HINT_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, 100, 1, "or_greater") var power_percent
@export_range(0, 100, 1, "or_greater", "or_less") var health_delta
@export_range(-3.14, 3.14, 0.001, "radians") 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_subgroup:
.. rst-class:: classref-annotation
**@export_subgroup** **(** :ref:`String<class_String>` name, :ref:`String<class_String>` prefix="" **)**
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_PROPERTY_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** **(** :ref:`String<class_String>` icon_path **)**
Add a custom icon to the current script. The script must be registered as a global class using the ``class_name`` keyword for this to have a visible effect. 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 ``@icon`` annotation must be placed before the class definition and inheritance.
\ **Note:** Unlike other annotations, the argument of the ``@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** **(** **)**
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_method__init>`), and instead are computed and stored right before :ref:`Node._ready<class_Node_method__ready>`.
::
@onready var character_name: Label = $Label
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_annotation_@rpc:
.. rst-class:: classref-annotation
**@rpc** **(** :ref:`String<class_String>` mode="authority", :ref:`String<class_String>` sync="call_remote", :ref:`String<class_String>` transfer_mode="unreliable", :ref:`int<class_int>` transfer_channel=0, ... **)** |vararg|
Mark the following method for remote procedure calls. See :doc:`High-level multiplayer <../tutorials/networking/high_level_multiplayer>`.
The order of ``mode``, ``sync`` and ``transfer_mode`` does not matter and all arguments can be omitted, but ``transfer_channel`` always has to be the last argument. The accepted values for ``mode`` are ``"any_peer"`` or ``"authority"``, for ``sync`` are ``"call_remote"`` or ``"call_local"`` and for ``transfer_mode`` are ``"unreliable"``, ``"unreliable_ordered"`` or ``"reliable"``.
::
@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_@tool:
.. rst-class:: classref-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 ``@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** **(** :ref:`String<class_String>` warning, ... **)** |vararg|
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** **(** :ref:`int<class_int>` r8, :ref:`int<class_int>` g8, :ref:`int<class_int>` b8, :ref:`int<class_int>` a8=255 **)**
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** **(** :ref:`bool<class_bool>` condition, :ref:`String<class_String>` message="" **)**
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.
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_method_char:
.. rst-class:: classref-method
:ref:`String<class_String>` **char** **(** :ref:`int<class_int>` 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** **(** :ref:`Variant<class_Variant>` what, :ref:`int<class_int>` type **)**
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** **(** :ref:`Dictionary<class_Dictionary>` dictionary **)**
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** **(** **)**
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:
::
[{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** **(** :ref:`Object<class_Object>` instance **)**
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:
::
[@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** **(** :ref:`Variant<class_Variant>` value, :ref:`Variant<class_Variant>` type **)**
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) and is more performant. 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_valid>`), 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_exists<class_@GDScript_method_type_exists>`, :ref:`Array.is_same_typed<class_Array_method_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** **(** :ref:`Variant<class_Variant>` var **)**
Returns the length of the given Variant ``var``. The length can be the character count of a :ref:`String<class_String>`, 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** **(** :ref:`String<class_String>` path **)**
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>`.
\ **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:** The path must be absolute. A relative path will always return ``null``.
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_ProjectSettings_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_ProjectSettings_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** **(** :ref:`String<class_String>` path **)**
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()
.. rst-class:: classref-item-separator
----
.. _class_@GDScript_method_print_debug:
.. rst-class:: classref-method
void **print_debug** **(** ... **)** |vararg|
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:
::
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** **(** **)**
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:
::
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|
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(), 0, -1):
print(array[i - 1])
Output:
::
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:
::
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** **(** :ref:`StringName<class_StringName>` type **)**
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.)`
Reference in New Issue View Git Blame Copy Permalink