: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`. .. 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` | :ref:`Color8` **(** :ref:`int` r8, :ref:`int` g8, :ref:`int` b8, :ref:`int` a8=255 **)** | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`assert` **(** :ref:`bool` condition, :ref:`String` message="" **)** | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`char` **(** :ref:`int` char **)** | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`convert` **(** :ref:`Variant` what, :ref:`int` type **)** | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Object` | :ref:`dict_to_inst` **(** :ref:`Dictionary` dictionary **)** | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Array` | :ref:`get_stack` **(** **)** | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Dictionary` | :ref:`inst_to_dict` **(** :ref:`Object` instance **)** | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_instance_of` **(** :ref:`Variant` value, :ref:`Variant` type **)** | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`len` **(** :ref:`Variant` var **)** | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Resource` | :ref:`load` **(** :ref:`String` path **)** | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Resource` | :ref:`preload` **(** :ref:`String` path **)** | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`print_debug` **(** ... **)** |vararg| | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`print_stack` **(** **)** | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Array` | :ref:`range` **(** ... **)** |vararg| | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`type_exists` **(** :ref:`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` 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` 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` 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` 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`. :: @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` and :ref:`@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` property without allowing its transparency (:ref:`Color.a`) to be edited. See also :ref:`@GlobalScope.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` property as a path to a directory. The path will be limited to the project folder and its subfolders. See :ref:`@export_global_dir` to allow picking from the entire filesystem. See also :ref:`@GlobalScope.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` names, ... **)** |vararg| Export an :ref:`int` or :ref:`String` property as an enumerated list of options. If the property is an :ref:`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`, then the value is stored. See also :ref:`@GlobalScope.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` 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` 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`. :: @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` filter="", ... **)** |vararg| Export a :ref:`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` 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`. :: @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` 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`. :: @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`, 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`. See also :ref:`@GlobalScope.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`. See also :ref:`@GlobalScope.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`. See also :ref:`@GlobalScope.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`. See also :ref:`@GlobalScope.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`. See also :ref:`@GlobalScope.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`. See also :ref:`@GlobalScope.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` property as an absolute path to a directory. The path can be picked from the entire filesystem. See :ref:`@export_dir` to limit it to the project folder and its subfolders. See also :ref:`@GlobalScope.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` filter="", ... **)** |vararg| Export a :ref:`String` property as an absolute path to a file. The path can be picked from the entire filesystem. See :ref:`@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`. :: @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` name, :ref:`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` to add subgroups within groups. See also :ref:`@GlobalScope.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` property with a large :ref:`TextEdit` widget instead of a :ref:`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`. :: @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` type="", ... **)** |vararg| Export a :ref:`NodePath` property with a filter for allowed node types. See also :ref:`@GlobalScope.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` placeholder **)** Export a :ref:`String` property with a placeholder text displayed in the editor widget when no value is present. See also :ref:`@GlobalScope.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` min, :ref:`float` max, :ref:`float` step=1.0, :ref:`String` extra_hints="", ... **)** |vararg| Export an :ref:`int` or :ref:`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`. :: @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` name, :ref:`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`. See also :ref:`@GlobalScope.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` 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` is ready. Values for these properties are not assigned immediately when the node is initialized (:ref:`Object._init`), and instead are computed and stored right before :ref:`Node._ready`. :: @onready var character_name: Label = $Label .. rst-class:: classref-item-separator ---- .. _class_@GDScript_annotation_@rpc: .. rst-class:: classref-annotation **@rpc** **(** :ref:`String` mode="authority", :ref:`String` sync="call_remote", :ref:`String` transfer_mode="unreliable", :ref:`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` 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` **Color8** **(** :ref:`int` r8, :ref:`int` g8, :ref:`int` b8, :ref:`int` a8=255 **)** Returns a :ref:`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` instead of the standard :ref:`Color` constructor is useful when you need to match exact color values in an :ref:`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` compared to the standard :ref:`Color` constructor, a color created with :ref:`Color8` will generally not be equal to the same color created with the standard :ref:`Color` constructor. Use :ref:`Color.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` condition, :ref:`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` 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` 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` 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` **char** **(** :ref:`int` char **)** Returns a single character (as a :ref:`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` **convert** **(** :ref:`Variant` what, :ref:`int` type **)** Converts ``what`` to ``type`` in the best way possible. The ``type`` uses the :ref:`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` **dict_to_inst** **(** :ref:`Dictionary` dictionary **)** Converts a ``dictionary`` (created with :ref:`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` **get_stack** **(** **)** Returns an array of dictionaries representing the current call stack. See also :ref:`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` 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` 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` **inst_to_dict** **(** :ref:`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` **is_instance_of** **(** :ref:`Variant` value, :ref:`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` enumeration, for example :ref:`@GlobalScope.TYPE_INT`. - An :ref:`Object`-derived class which exists in :ref:`ClassDB`, for example :ref:`Node`. - A :ref:`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`), or ``type`` is not one of the above options, this method will raise a runtime error. See also :ref:`@GlobalScope.typeof`, :ref:`type_exists`, :ref:`Array.is_same_typed` (and other :ref:`Array` methods). .. rst-class:: classref-item-separator ---- .. _class_@GDScript_method_len: .. rst-class:: classref-method :ref:`int` **len** **(** :ref:`Variant` var **)** Returns the length of the given Variant ``var``. The length can be the character count of a :ref:`String`, the element count of any array type or the size of a :ref:`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` **load** **(** :ref:`String` path **)** Returns a :ref:`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`. \ **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`, 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`\ s at run-time, you may use :ref:`Image.load`. If you want to import audio files, you can use the snippet described in :ref:`AudioStreamMP3.data`. \ **Note:** If :ref:`ProjectSettings.editor/export/convert_text_resources_to_binary` is ``true``, :ref:`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` to ``false``. .. rst-class:: classref-item-separator ---- .. _class_@GDScript_method_preload: .. rst-class:: classref-method :ref:`Resource` **preload** **(** :ref:`String` path **)** Returns a :ref:`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`. If you want to load a resource from a dynamic/variable path, use :ref:`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`, 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` 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`. 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` 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` 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` **range** **(** ... **)** |vararg| Returns an array with the given range. :ref:`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` converts all arguments to :ref:`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` 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`, 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` **type_exists** **(** :ref:`StringName` type **)** Returns ``true`` if the given :ref:`Object`-derived class exists in :ref:`ClassDB`. Note that :ref:`Variant` data types are not registered in :ref:`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.)`