null¶

null is an empty data type that contains no information and can notbe assigned any other value.

bool¶

Short for "boolean", it can only containtrue orfalse.

int¶

Short for "integer", it stores whole numbers (positive and negative).It is stored as a 64-bit value, equivalent to "int64_t" in C++.

float¶

Stores real numbers, including decimals, using floating-point values.It is stored as a 64-bit value, equivalent to "double" in C++.Note: Currently, data structures such as Vector2, Vector3, andPoolRealArray store 32-bit single-precision "float" values.

String¶

A sequence of characters inUnicode format.Strings can contain the following escape sequences:

GDScript also supportsGDScript format strings.

Vector2¶

2D vector type containingx andy fields. Can also beaccessed as an array.

Rect2¶

2D Rectangle type containing two vectors fields:position andsize.Also contains anend field which isposition+size.

Vector3¶

3D vector type containingx,y andz fields. This can alsobe accessed as an array.

Transform2D¶

3×2 matrix used for 2D transforms.

Plane¶

3D Plane type in normalized form that contains anormal vector fieldand ad scalar distance.

Quat¶

Quaternion is a datatype used for representing a 3D rotation. It'suseful for interpolating rotations.

AABB¶

Axis-aligned bounding box (or 3D box) contains 2 vectors fields:positionandsize. Also contains anend field which isposition+size.

Basis¶

3x3 matrix used for 3D rotation and scale. It contains 3 vector fields(x,y andz) and can also be accessed as an array of 3Dvectors.

Transform¶

3D Transform contains a Basis fieldbasis and a Vector3 fieldorigin.

Color¶

Color data type containsr,g,b, anda fields. It canalso be accessed ash,s, andv for hue/saturation/value.

NodePath¶

Compiled path to a node used mainly in the scene system. It can beeasily assigned to, and from, a String.

RID¶

Resource ID (RID). Servers use generic RIDs to reference opaque data.

Object¶

Base class for anything that is not a built-in type.

Array¶

Generic sequence of arbitrary object types, including other arrays or dictionaries (see below).The array can resize dynamically. Arrays are indexed starting from index0.Negative indices count from the end.

vararr=[]arr=[1,2,3]varb=arr[1]# This is 2.varc=arr[arr.size()-1]# This is 3.vard=arr[-1]# Same as the previous line, but shorter.arr[0]="Hi!"# Replacing value 1 with "Hi!".arr.append(4)# Array is now ["Hi!", 2, 3, 4].

GDScript arrays are allocated linearly in memory for speed.Large arrays (more than tens of thousands of elements) may however causememory fragmentation. If this is a concern, special types ofarrays are available. These only accept a single data type. They avoid memoryfragmentation and use less memory, but are atomic and tend to run slower than genericarrays. They are therefore only recommended to use for large data sets:

• PoolByteArray: An array of bytes (integers from 0 to 255).

• PoolIntArray: An array of integers.

• PoolRealArray: An array of floats.

• PoolStringArray: An array of strings.

• PoolVector2Array: An array ofVector2 objects.

• PoolVector3Array: An array ofVector3 objects.

• PoolColorArray: An array ofColor objects.

Dictionary¶

Associative container which contains values referenced by unique keys.

vard={4:5,"A key":"A value",28:[1,2,3]}d["Hi!"]=0d={22:"value","some_key":2,"other_key":[2,3,4],"more_key":"Hello"}

Lua-style table syntax is also supported. Lua-style uses= instead of:and doesn't use quotes to mark string keys (making for slightly less to write).However, keys written in this form can't start with a digit (like any GDScriptidentifier).

vard={test22="value",some_key=2,other_key=[2,3,4],more_key="Hello"}

To add a key to an existing dictionary, access it like an existing key andassign to it:

vard={}# Create an empty Dictionary.d.waiting=14# Add String "waiting" as a key and assign the value 14 to it.d[4]="hello"# Add integer 4 as a key and assign the String "hello" as its value.d["Godot"]=3.01# Add String "Godot" as a key and assign the value 3.01 to it.vartest=4# Prints "hello" by indexing the dictionary with a dynamic key.# This is not the same as `d.test`. The bracket syntax equivalent to# `d.test` is `d["test"]`.print(d[test])

Casting¶

Values assigned to typed variables must have a compatible type. If it's needed tocoerce a value to be of a certain type, in particular for object types, you canuse the casting operatoras.

Casting between object types results in the same object if the value is of thesame type or a subtype of the cast type.

varmy_node2D:Node2Dmy_node2D=$SpriteasNode2D# Works since Sprite is a subtype of Node2D.

If the value is not a subtype, the casting operation will result in anull value.

varmy_node2D:Node2Dmy_node2D=$ButtonasNode2D# Results in 'null' since a Button is not a subtype of Node2D.

For built-in types, they will be forcibly converted if possible, otherwise theengine will raise an error.

varmy_int:intmy_int="123"asint# The string can be converted to int.my_int=Vector2()asint# A Vector2 can't be converted to int, this will cause an error.

Casting is also useful to have better type-safe variables when interacting withthe scene tree:

# Will infer the variable to be of type Sprite.varmy_sprite:=$CharacterasSprite# Will fail if $AnimPlayer is not an AnimationPlayer, even if it has the method 'play()'.($AnimPlayerasAnimationPlayer).play("walk")

Enums¶

Enums are basically a shorthand for constants, and are pretty useful if youwant to assign consecutive integers to some constant.

If you pass a name to the enum, it will put all the keys inside a constantdictionary of that name.

enum{TILE_BRICK,TILE_FLOOR,TILE_SPIKE,TILE_TELEPORT}# Is the same as:constTILE_BRICK=0constTILE_FLOOR=1constTILE_SPIKE=2constTILE_TELEPORT=3enumState{STATE_IDLE,STATE_JUMP=5,STATE_SHOOT}# Is the same as:constState={STATE_IDLE=0,STATE_JUMP=5,STATE_SHOOT=6}# Access values with State.STATE_IDLE, etc.

Referencing functions¶

Contrary to Python, functions arenot first-class objects in GDScript. Thismeans they cannot be stored in variables, passed as an argument to anotherfunction or be returned from other functions. This is for performance reasons.

To reference a function by name at run-time, (e.g. to store it in a variable, orpass it to another function as an argument) one must use thecall orfuncref helpers:

# Call a function by name in one step.my_node.call("my_function",args)# Store a function reference.varmy_func=funcref(my_node,"my_function")# Call stored function reference.my_func.call_func(args)

Static functions¶

A function can be declared static. When a function is static, it has noaccess to the instance member variables orself. This is mainlyuseful to make libraries of helper functions:

staticfuncsum2(a,b):returna+b

if/else/elif¶

Simple conditions are created by using theif/else/elif syntax.Parenthesis around conditions are allowed, but not required. Given thenature of the tab-based indentation,elif can be used instead ofelse/if to maintain a level of indentation.

if[expression]:statement(s)elif[expression]:statement(s)else:statement(s)

Short statements can be written on the same line as the condition:

if1+1==2:return2+2else:varx=3+3returnx

Sometimes, you might want to assign a different initial value based on aboolean expression. In this case, ternary-if expressions come in handy:

varx=[value]if[expression]else[value]y+=3ify<10else-1

Ternary-if expressions can be nested to handle more than 2 cases. When nestingternary-if expressions, it is recommended to wrap the complete expression overmultiple lines to preserve readability:

varcount=0varfruit=("apple"ifcount==2else"pear"ifcount==1else"banana"ifcount==0else"orange")print(fruit)# banana# Alternative syntax with backslashes instead of parentheses (for multi-line expressions).# Less lines required, but harder to refactor.varfruit_alt= \"apple"ifcount==2 \else"pear"ifcount==1 \else"banana"ifcount==0 \else"orange"print(fruit_alt)# banana

while¶

Simple loops are created by usingwhile syntax. Loops can be brokenusingbreak or continued usingcontinue:

while[expression]:statement(s)

for¶

To iterate through a range, such as an array or table, afor loop isused. When iterating over an array, the current array element is stored inthe loop variable. When iterating over a dictionary, thekey is storedin the loop variable.

forxin[5,7,11]:statement# Loop iterates 3 times with 'x' as 5, then 7 and finally 11.vardict={"a":0,"b":1,"c":2}foriindict:print(dict[i])# Prints 0, then 1, then 2.foriinrange(3):statement# Similar to [0, 1, 2] but does not allocate an array.foriinrange(1,3):statement# Similar to [1, 2] but does not allocate an array.foriinrange(2,8,2):statement# Similar to [2, 4, 6] but does not allocate an array.forcin"Hello":print(c)# Iterate through all characters in a String, print every letter on new line.foriin3:statement# Similar to range(3)foriin2.2:statement# Similar to range(ceil(2.2))

match¶

Amatch statement is used to branch execution of a program.It's the equivalent of theswitch statement found in many other languages, but offers some additional features.

Basic syntax:

match[expression]:[pattern](s):[block][pattern](s):[block][pattern](s):[block]

Crash-course for people who are familiar with switch statements:

1. Replaceswitch withmatch.

2. Removecase.

3. Remove anybreaks. If you don't want tobreak by default, you can usecontinue for a fallthrough.

4. Changedefault to a single underscore.

Control flow:

The patterns are matched from top to bottom.If a pattern matches, the first corresponding block will be executed. After that, the execution continues below thematch statement.You can usecontinue to stop execution in the current block and check for an additional match in the patterns below it.

There are 6 pattern types:

• Constant pattern

  Constant primitives, like numbers and strings:

  matchx:1:print("We are number one!")2:print("Two are better than one!")"test":print("Oh snap! It's a string!")

• Variable pattern

  Matches the contents of a variable/enum:

  matchtypeof(x):TYPE_REAL:print("float")TYPE_STRING:print("text")TYPE_ARRAY:print("array")

• Wildcard pattern

  This pattern matches everything. It's written as a single underscore.

  It can be used as the equivalent of thedefault in aswitch statement in other languages:

  matchx:1:print("It's one!")2:print("It's one times two!")_:print("It's not 1 or 2. I don't care to be honest.")

• Binding pattern

  A binding pattern introduces a new variable. Like the wildcard pattern, it matches everything - and also gives that value a name.It's especially useful in array and dictionary patterns:

  matchx:1:print("It's one!")2:print("It's one times two!")varnew_var:print("It's not 1 or 2, it's ",new_var)

• Array pattern

  Matches an array. Every single element of the array pattern is a pattern itself, so you can nest them.

  The length of the array is tested first, it has to be the same size as the pattern, otherwise the pattern doesn't match.

  Open-ended array: An array can be bigger than the pattern by making the last subpattern...

  Every subpattern has to be comma-separated.

  matchx:[]:print("Empty array")[1,3,"test",null]:print("Very specific array")[varstart,_,"test"]:print("First element is ",start,", and the last is\"test\"")[42,..]:print("Open ended array")

• Dictionary pattern

  Works in the same way as the array pattern. Every key has to be a constant pattern.

  The size of the dictionary is tested first, it has to be the same size as the pattern, otherwise the pattern doesn't match.

  Open-ended dictionary: A dictionary can be bigger than the pattern by making the last subpattern...

  Every subpattern has to be comma separated.

  If you don't specify a value, then only the existence of the key is checked.

  A value pattern is separated from the key pattern with a:.

  matchx:{}:print("Empty dict"){"name":"Dennis"}:print("The name is Dennis"){"name":"Dennis","age":varage}:print("Dennis is ",age," years old."){"name","age"}:print("Has a name and an age, but it's not Dennis :("){"key":"godotisawesome",..}:print("I only checked for one entry and ignored the rest")

• Multiple patterns

  You can also specify multiple patterns separated by a comma. These patterns aren't allowed to have any bindings in them.

  matchx:1,2,3:print("It's 1 - 3")"Sword","Splash potion","Fist":print("Yep, you've taken damage")

Inheritance¶

A class (stored as a file) can inherit from:

• A global class.

• Another class file.

• An inner class inside another class file.

Multiple inheritance is not allowed.

Inheritance uses theextends keyword:

# Inherit/extend a globally available class.extendsSomeClass# Inherit/extend a named class file.extends"somefile.gd"# Inherit/extend an inner class in another file.extends"somefile.gd".SomeInnerClass

To check if a given instance inherits from a given class,theis keyword can be used:

# Cache the enemy class.constEnemy=preload("enemy.gd")# [...]# Use 'is' to check inheritance.ifentityisEnemy:entity.apply_damage()

To call a function in aparent class (i.e. oneextend-ed in your currentclass), prepend. to the function name:

.base_func(args)

This is especially useful because functions in extending classes replacefunctions with the same name in their parent classes. If you still want tocall them, you can prefix them with. (like thesuper keywordin other languages):

funcsome_func(x):.some_func(x)# Calls the same function on the parent class.

Class constructor¶

The class constructor, called on class instantiation, is named_init. Asmentioned earlier, the constructors of parent classes are called automaticallywhen inheriting a class. So, there is usually no need to call._init()explicitly.

Unlike the call of a regular function, like in the above example with.some_func, if the constructor from the inherited class takes arguments,they are passed like this:

func_init(args).(parent_args):pass

This is better explained through examples. Consider this scenario:

# State.gd (inherited class)varentity=nullvarmessage=nullfunc_init(e=null):entity=efuncenter(m):message=m# Idle.gd (inheriting class)extends"State.gd"func_init(e=null,m=null).(e):# Do something with 'e'.message=m

There are a few things to keep in mind here:

1. If the inherited class (State.gd) defines a_init constructor that takesarguments (e in this case), then the inheriting class (Idle.gd)mustdefine_init as well and pass appropriate parameters to_init fromState.gd.

2. Idle.gd can have a different number of arguments than the parent classState.gd.

3. In the example above,e passed to theState.gd constructor is the samee passedin toIdle.gd.

4. IfIdle.gd's_init constructor takes 0 arguments, it still needs to pass some valueto theState.gd parent class, even if it does nothing. This brings us to the fact that youcan pass literals in the base constructor as well, not just variables, e.g.:

   # Idle.gdfunc_init().(5):pass

Inner classes¶

A class file can contain inner classes. Inner classes are defined using theclass keyword. They are instanced using theClassName.new()function.

# Inside a class file.# An inner class in this class file.classSomeInnerClass:vara=5funcprint_value_of_a():print(a)# This is the constructor of the class file's main class.func_init():varc=SomeInnerClass.new()c.print_value_of_a()

Classes as resources¶

Classes stored as files are treated asresources. Theymust be loaded from disk to access them in other classes. This is done usingeither theload orpreload functions (see below). Instancing of a loadedclass resource is done by calling thenew function on the class object:

# Load the class resource when calling load().varMyClass=load("myclass.gd")# Preload the class only once at compile time.constMyClass=preload("myclass.gd")func_init():vara=MyClass.new()a.some_function()

Coroutines & signals¶

The real strength of usingyield is when combined with signals.yield can accept two arguments, an object and a signal. When thesignal is received, execution will recommence. Here are some examples:

# Resume execution the next frame.yield(get_tree(),"idle_frame")# Resume execution when animation is done playing.yield(get_node("AnimationPlayer"),"animation_finished")# Wait 5 seconds, then resume execution.yield(get_tree().create_timer(5.0),"timeout")

Coroutines themselves use thecompleted signal when they transitioninto an invalid state, for example:

funcmy_func():yield(button_func(),"completed")print("All buttons were pressed, hurray!")funcbutton_func():yield($Button0,"pressed")yield($Button1,"pressed")

my_func will only continue execution once both buttons have been pressed.

You can also get the signal's argument once it's emitted by an object:

# Wait for when any node is added to the scene tree.varnode=yield(get_tree(),"node_added")

If there is more than one argument,yield returns an array containingthe arguments:

signaldone(input,processed)funcprocess_input(input):print("Processing initialized")yield(get_tree(),"idle_frame")print("Waiting")yield(get_tree(),"idle_frame")emit_signal("done",input,"Processed "+input)func_ready():process_input("Test")# Prints: Processing initializedvardata=yield(self,"done")# Prints: waitingprint(data[1])# Prints: Processed Test

If you're unsure whether a function may yield or not, or whether it may yieldmultiple times, you can yield to thecompleted signal conditionally:

funcgenerate():varresult=rand_range(-1.0,1.0)ifresult<0.0:yield(get_tree(),"idle_frame")returnresultfuncmake():varresult=generate()ifresultisGDScriptFunctionState:# Still working.result=yield(result,"completed")returnresult

This ensures that the function returns whatever it was supposed to returnregardless of whether coroutines were used internally. Note that usingwhile would be redundant here as thecompleted signal is only emittedwhen the function didn't yield anymore.