Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

@GDScript

Built-in GDScript constants, functions, and annotations.

Description

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

For the list of the global functions and constants see @GlobalScope.

Tutorials

Methods

Color

Color8 ( int r8, int g8, int b8, int a8=255 )

void

assert ( bool condition, String message="" )

String

char ( int char )

Variant

convert ( Variant what, int type )

Object

dict_to_inst ( Dictionary dictionary )

Array

get_stack ( )

Dictionary

inst_to_dict ( Object instance )

bool

is_instance_of ( Variant value, Variant type )

int

len ( Variant var )

Resource

load ( String path )

Resource

preload ( String path )

void

print_debug ( ... ) vararg

void

print_stack ( )

Array

range ( ... ) vararg

bool

type_exists ( StringName type )


Constants

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.

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.

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 INF and will result in a run-time error instead.

NAN = nan

"Not a Number", an invalid floating-point value. 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 NAN and will result in a run-time error instead.


Annotations

@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 must be registered as global classes using class_name.

Note: Node export is only supported in Node-derived classes and has a number of other limitations.


@export_category ( String name )

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

See also @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 @export_group and @export_subgroup, instead.


@export_color_no_alpha ( )

Export a Color property without allowing its transparency (Color.a) to be edited.

See also @GlobalScope.PROPERTY_HINT_COLOR_NO_ALPHA.

@export_color_no_alpha var dye_color: Color

@export_dir ( )

Export a String property as a path to a directory. The path will be limited to the project folder and its subfolders. See @export_global_dir to allow picking from the entire filesystem.

See also @GlobalScope.PROPERTY_HINT_DIR.

@export_dir var sprite_folder_path: String

@export_enum ( String names, ... ) vararg

Export an int or String property as an enumerated list of options. If the property is an 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 String, then the value is stored.

See also @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 @export instead:

enum CharacterName {REBECCA, MARY, LEAH}
@export var character_name: CharacterName

@export_exp_easing ( 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 @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

@export_file ( String filter="", ... ) vararg

Export a String property as a path to a file. The path will be limited to the project folder and its subfolders. See @export_global_file to allow picking from the entire filesystem.

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

See also @GlobalScope.PROPERTY_HINT_FILE.

@export_file var sound_effect_path: String
@export_file("*.txt") var notes_path: String

@export_flags ( 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 @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 @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

@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 ProjectSettings.layer_names/2d_navigation/layer_1.

See also @GlobalScope.PROPERTY_HINT_LAYERS_2D_NAVIGATION.

@export_flags_2d_navigation var navigation_layers: int

@export_flags_2d_physics ( )

Export an integer property as a bit flag field for 2D p