History

Example of GDScript

Some people can learn better by taking a look at the syntax, sohere's an example of how GDScript looks.

# Everything after "#" is a comment.# A file is a class!# (optional) icon to show in the editor dialogs:@icon("res://path/to/optional/icon.svg")# (optional) class definition:class_nameMyClass# Inheritance:extendsBaseClass# Member variables.vara=5vars="Hello"vararr=[1,2,3]vardict={"key":"value",2:3}varother_dict={key="value",other_key=2}vartyped_var:intvarinferred_type:="String"# Constants.constANSWER=42constTHE_NAME="Charly"# Enums.enum{UNIT_NEUTRAL,UNIT_ENEMY,UNIT_ALLY}enumNamed{THING_1,THING_2,ANOTHER_THING=-1}# Built-in vector types.varv2=Vector2(1,2)varv3=Vector3(1,2,3)# Functions.funcsome_function(param1,param2,param3):constlocal_const=5ifparam1<local_const:print(param1)elifparam2>5:print(param2)else:print("Fail!")foriinrange(20):print(i)whileparam2!=0:param2-=1matchparam3:3:print("param3 is 3!")_:print("param3 is not 3!")varlocal_var=param1+3returnlocal_var# Functions override functions with the same name on the base/super class.# If you still want to call them, use "super":funcsomething(p1,p2):super(p1,p2)# It's also possible to call another function in the super class:funcother_something(p1,p2):super.something(p1,p2)# Inner classclassSomething:vara=10# Constructorfunc_init():print("Constructed!")varlv=Something.new()print(lv.a)

If you have previous experience with statically typed languages such asC, C++, or C# but never used a dynamically typed one before, it is advised youread this tutorial:GDScript: An introduction to dynamic languages.

Identifiers

Any string that restricts itself to alphabetic characters (a toz andA toZ), digits (0 to9) and_ qualifies as an identifier.Additionally, identifiers must not begin with a digit. Identifiers arecase-sensitive (foo is different fromFOO).

Identifiers may also contain most Unicode characters part ofUAX#31. This allows you to useidentifier names written in languages other than English. Unicode charactersthat are considered "confusable" for ASCII characters and emoji are not allowedin identifiers.

Keywords

The following is the list of keywords supported by the language. Sincekeywords are reserved words (tokens), they can't be used as identifiers.Operators (likein,not,and oror) and names of built-in typesas listed in the following sections are also reserved.

Keywords are defined in theGDScript tokenizerin case you want to take a look under the hood.

Operators

The following is the list of supported operators and their precedence. All binary operators areleft-associative,including the** operator. This means that2**2**3 is equal to(2**2)**3. Use parentheses to explicitly specify precedence you need, forexample2**(2**3). The ternaryif/else operator is right-associative.

Literals

There are also two constructs that look like literals, but actually are not:

Integers and floats can have their numbers separated with_ to make them more readable.The following ways to write numbers are all valid:

12_345_678# Equal to 12345678.3.141_592_7# Equal to 3.1415927.0x8080_0000_ffff# Equal to 0x80800000ffff.0b11_00_11_00# Equal to 0b11001100.

Regular string literals can contain the following escape sequences:

There are two ways to represent an escaped Unicode character above0xFFFF:

• as aUTF-16 surrogate pair\uXXXX\uXXXX.

• as a single UTF-32 codepoint\UXXXXXX.

Also, using\ followed by a newline inside a string will allow you to continue it in the next line,without inserting a newline character in the string itself.

A string enclosed in quotes of one type (for example") can contain quotes of another type(for example') without escaping. Triple-quoted strings allow you to avoid escaping up totwo consecutive quotes of the same type (unless they are adjacent to the string edges).

Raw string literals always encode the string as it appears in the source code.This is especially useful for regular expressions. A raw string literal doesn't process escape sequences,however it does recognize\\ and\" (\') and replaces them with themselves.Thus, a string can have a quote that matches the opening one, but only if it's preceded by a backslash.

print("\tchar=\"\\t\"")# Prints `    char="\t"`.print(r"\tchar=\"\\t\"")# Prints `\tchar=\"\\t\"`.

GDScript also supportsformat strings.

Annotations

Annotations are special tokens in GDScript that act as modifiers to a script orits code and may affect how the script is treated by the Godot engine oreditor.

Every annotation starts with the@ character and is specified by a name. Adetailed description and example for each annotation can be found inside theGDScript class reference.

For instance, you can use it to export a value to the editor:

@export_range(1,100,1,"or_greater")varranged_var:int=50

For more information about exporting properties, read theGDScript exportsarticle.

Any constant expression compatible with the required argument type can be passed as an annotation argument value:

constMAX_SPEED=120.0@export_range(0.0,0.5*MAX_SPEED)varinitial_speed:float=0.25*MAX_SPEED

Annotations can be specified one per line or all in the same line. They affectthe next statement that isn't an annotation. Annotations can have arguments sentbetween parentheses and separated by commas.

Both of these are the same:

@annotation_a@annotation_bvarvariable@annotation_a@annotation_bvarvariable

varmy_labelfunc_ready():my_label=get_node("MyLabel")

@onreadyvarmy_label=get_node("MyLabel")

@exportvara="init_value_a"@onready@exportvarb="init_value_b"func_init():prints(a,b)# init_value_a <null>func_notification(what):ifwhat==NOTIFICATION_SCENE_INSTANTIATED:prints(a,b)# exported_value_a exported_value_bfunc_ready():prints(a,b)# exported_value_a init_value_b

Comments

Anything from a# to the end of the line is ignored and isconsidered a comment.

# This is a comment.

# In the example below, "TODO" will appear in yellow by default.# The `:` symbol after the keyword is not required, but it's often used.# TODO: Add more items for the player to choose from.

Use two hash symbols (##) instead of one (#) to add adocumentationcomment, which will appear in the script documentation and in the inspectordescription of an exported variable. Documentation comments must be placeddirectlyabove a documentable item (such as a member variable), or at the topof a file. Dedicated formatting options are also available. SeeGDScript documentation comments for details.

## This comment will appear in the script documentation.varvalue## This comment will appear in the inspector tooltip, and in the documentation.@exportvarexported_value

Code regions

Code regions are special types of comments that the script editor understands asfoldable regions. This means that after writing code region comments, you cancollapse and expand the region by clicking the arrow that appears at the left ofthe comment. This arrow appears within a purple square to be distinguishablefrom standard code folding.

The syntax is as follows:

# Important: There must be *no* space between the `#` and `region` or `endregion`.# Region without a description:#region...#endregion# Region with a description:#region Some description that is displayed even when collapsed...#endregion

Here's a concrete usage example of code regions:

# This comment is outside the code region. It will be visible when collapsed.#region Terrain generation# This comment is inside the code region. It won't be visible when collapsed.funcgenerate_lakes():passfuncgenerate_hills():pass#endregion#region Terrain populationfuncplace_vegetation():passfuncplace_roads():pass#endregion

This can be useful to organize large chunks of code into easier to understandsections. However, remember that external editors generally don't support thisfeature, so make sure your code is easy to follow even when not relying onfolding code regions.

Line continuation

A line of code in GDScript can be continued on the next line by using a backslash(\). Add one at the end of a line and the code on the next line will act likeit's where the backslash is. Here is an example:

vara=1+ \2

A line can be continued multiple times like this:

vara=1+ \4+ \10+ \4

Built-in types

Built-in types are stack-allocated. They are passed as values. This means a copyis created on each assignment or when passing them as arguments to functions.The exceptions areObject,Array,Dictionary, and packed arrays(such asPackedByteArray), which are passed by reference so they are shared.All arrays,Dictionary, and some objects (Node,Resource)have aduplicate() method that allows you to make a copy.

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].

vara:Array[int]varb:Array[Node]varc:Array[MyClass]vard:Array[MyEnum]vare:Array[Variant]

vara:Array[Node2D]=[Node2D.new()]# (OK) You can add the value to the array because `Node2D` extends `Node`.varb:Array[Node]=[a[0]]# (Error) You cannot assign an `Array[Node2D]` to an `Array[Node]` variable.b=a# (OK) But you can use the `assign()` method instead. Unlike the `=` operator,# the `assign()` method copies the contents of the array, not the reference.b.assign(a)

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"}

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

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])

Variables

Variables can exist as class members or local to functions. They arecreated with thevar keyword and may, optionally, be assigned avalue upon initialization.

vara# Data type is 'null' by default.varb=5varc=3.8vard=b+c# Variables are always initialized in direct order (see below).

Variables can optionally have a type specification. When a type is specified,the variable will be forced to have always that same type, and trying to assignan incompatible value will raise an error.

Types are specified in the variable declaration using a: (colon) symbolafter the variable name, followed by the type.

varmy_vector2:Vector2varmy_node:Node=Sprite2D.new()

If the variable is initialized within the declaration, the type can be inferred, soit's possible to omit the type name:

varmy_vector2:=Vector2()# 'my_vector2' is of type 'Vector2'.varmy_node:=Sprite2D.new()# 'my_node' is of type 'Sprite2D'.

Type inference is only possible if the assigned value has a defined type, otherwiseit will raise an error.

Valid types are:

• Built-in types (Array, Vector2, int, String, etc.).

• Engine classes (Node, Resource, RefCounted, etc.).

• Constant names if they contain a script resource (MyScript if you declaredconstMyScript=preload("res://my_script.gd")).

• Other classes in the same script, respecting scope (InnerClass.NestedClass if you declaredclassNestedClass inside theclassInnerClass in the same scope).

• Script classes declared with theclass_name keyword.

• Autoloads registered as singletons.

vara:int=proxy("a",1)varb:int=proxy("b",2)var_data:Dictionary={}funcproxy(key:String,value:int):_data[key]=valueprint(_data)returnvaluefunc_init()->void:print(_data)

{"a":1}{"a":1,"b":2}{}

staticvara

# person.gdclass_namePersonstaticvarmax_id=0varidvarnamefunc_init(p_name):max_id+=1id=max_idname=p_name

# test.gdextendsNodefunc_ready():varperson1=Person.new("John Doe")varperson2=Person.new("Jane Doe")print(person1.id)# 1print(person2.id)# 2print(Person.max_id)# 2print(person1.max_id)# 2print(person2.max_id)# 2

staticvarbalance:int=0staticvardebt:int:get:return-balanceset(value):balance=-value

classA:staticvarx=1classBextendsA:passfunc_ready():prints(A.x,B.x)# 1 1A.x=2prints(A.x,B.x)# 2 2B.x=3prints(A.x,B.x)# 3 3

@static_unloadclass_nameMyNodeextendsNode

varmy_node2D:Node2Dmy_node2D=$Sprite2DasNode2D# Works since Sprite2D is a subtype of Node2D.

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

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.

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

Constants

Constants are values you cannot change when the game is running.Their value must be known at compile-time. Using theconst keyword allows you to give a constant value a name. Trying to assign avalue to a constant after it's declared will give you an error.

We recommend using constants whenever a value is not meant to change.

constA=5constB=Vector2(20,20)constC=10+20# Constant expression.constD=Vector2(20,30).x# Constant expression: 20.constE=[1,2,3,4][0]# Constant expression: 1.constF=sin(20)# 'sin()' can be used in constant expressions.constG=x+20# Invalid; this is not a constant expression!constH=A+20# Constant expression: 25 (`A` is a constant).

Although the type of constants is inferred from the assigned value, it's alsopossible to add explicit type specification:

constA:int=5constB:Vector2=Vector2()

Assigning a value of an incompatible type will raise an error.

You can also create constants inside a function, which is useful to name localmagic values.

enum{TILE_BRICK,TILE_FLOOR,TILE_SPIKE,TILE_TELEPORT}# Is the same as:constTILE_BRICK=0constTILE_FLOOR=1constTILE_SPIKE=2constTILE_TELEPORT=3

enumState{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.func_ready():# Access values with Name.KEY, prints '5'print(State.STATE_JUMP)# Use dictionary methods:# prints '["STATE_IDLE", "STATE_JUMP", "STATE_SHOOT"]'print(State.keys())# prints '{ "STATE_IDLE": 0, "STATE_JUMP": 5, "STATE_SHOOT": 6 }'print(State)# prints '[0, 5, 6]'print(State.values())

Functions

Functions always belong to aclass. The scope priority forvariable look-up is: local → class member → global. Theself variable isalways available and is provided as an option for accessing class members(seeself), but is not always required (and shouldnot be sent as thefunction's first argument, unlike Python).

funcmy_function(a,b):print(a)print(b)returna+b# Return is optional; without it 'null' is returned.

A function canreturn at any point. The default return value isnull.

If a function contains only one line of code, it can be written on one line:

funcsquare(a):returna*afunchello_world():print("Hello World")funcempty_function():pass

Functions can also have type specification for the arguments and for the returnvalue. Types for arguments can be added in a similar way to variables:

funcmy_function(a:int,b:String):pass

If a function argument has a default value, it's possible to infer the type:

funcmy_function(int_arg:=42,String_arg:="string"):pass

The return type of the function can be specified after the arguments list usingthe arrow token (->):

funcmy_int_function()->int:return0

Functions that have a return typemust return a proper value. Setting thetype asvoid means the function doesn't return anything. Void functions canreturn early with thereturn keyword, but they can't return any value.

funcvoid_function()->void:return# Can't return a value.

funcmap(arr:Array,function:Callable)->Array:varresult=[]foriteminarr:result.push_back(function.call(item))returnresultfuncadd1(value:int)->int:returnvalue+1;func_ready()->void:varmy_array=[1,2,3]varplus_one=map(my_array,add1)print(plus_one)# Prints `[2, 3, 4]`.

varlambda=func(x):print(x)

lambda.call(42)# Prints `42`.

varlambda=funcmy_lambda(x):print(x)

varlambda:=func(x:int)->void:print(x)

varlambda=func(x):returnx**2print(lambda.call(2))# Prints `4`.

varx=42varlambda=func():print(x)# Prints `42`.lambda.call()

varx=42varlambda=func():print(x)lambda.call()# Prints `42`.x="Hello"lambda.call()# Prints `42`.

varx=42varlambda=func():print(x)# Prints `42`.x="Hello"# Produces the `CONFUSABLE_CAPTURE_REASSIGNMENT` warning.print(x)# Prints `Hello`.lambda.call()print(x)# Prints `42`.

vara=[]varlambda=func():a.append(1)print(a)# Prints `[1]`.a=[2]# Produces the `CONFUSABLE_CAPTURE_REASSIGNMENT` warning.print(a)# Prints `[2]`.lambda.call()print(a)# Prints `[1]`.

staticfuncsum2(a,b):returna+b

Statements and control flow

Statements are standard and can be assignments, function calls, controlflow structures, etc (see below).; as a statement separator isentirely optional.

2+2# Binary operation.-5# Unary operation."okay"ifx>4else"not okay"# Ternary operation.x# Identifier representing variable or constant.x.a# Attribute access.x[4]# Subscript access.x>2orx<5# Comparisons and logic operators.x==y+2# Equality test.do_something()# Function call.[1,2,3]# Array definition.{A=1,B=2}# Dictionary definition.preload("res://icon.png")# Preload builtin function.self# Reference to current instance.

extendsNodefunc_ready():# Compile time error, as `my_var` is not defined in the current class or its ancestors.print(my_var)# Checked at runtime, thus may work for dynamic properties or descendant classes.print(self.my_var)# Compile time error, as `my_func()` is not defined in the current class or its ancestors.my_func()# Checked at runtime, thus may work for descendant classes.self.my_func()

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

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

varx=(value)if(expression)else(value)y+=3ify<10else-1

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

# Check if a letter is in a string.vartext="abc"if'b'intext:print("The string contains b")# Check if a variable is contained within a node.if"varName"inget_parent():print("varName is defined in parent!")

while(expression):statement(s)

forxin[5,7,11]:statement# Loop iterates 3 times with 'x' as 5, then 7 and finally 11.varnames=["John","Marta","Samantha","Jimmy"]forname:Stringinnames:# Typed loop variable.print(name)# Prints name's content.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.foriinrange(8,2,-2):statement# Similar to [8, 6, 4] 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)).

foriinarray.size():array[i]="Hello World"

forstringinstring_array:string="Hello World"# This has no effectfornodeinnode_array:node.add_to_group("Cool_Group")# This has an effect

match<testvalue>:<pattern(s)>:<block><pattern(s)>when<patternguard>:<block><...>

matchpoint:[0,0]:print("Origin")[_,0]:print("Point on X-axis")[0,_]:print("Point on Y-axis")[varx,vary]wheny==x:print("Point on line y = x")[varx,vary]wheny==-x:print("Point on line y = -x")[varx,vary]:print("Point (%s,%s)"%[x,y])

Classes

By default, all script files are unnamed classes. In this case, you can onlyreference them using the file's path, using either a relative or an absolutepath. For example, if you name a script filecharacter.gd:

# Inherit from 'character.gd'.extends"res://path/to/character.gd"# Load character.gd and create a new node instance from it.varCharacter=load("res://path/to/character.gd")varcharacter_node=Character.new()

Registering named classes

You can give your class a name to register it as a new type in Godot'seditor. For that, you use theclass_name keyword. You can optionally usethe@icon annotation with a path to an image, to use it as an icon. Yourclass will then appear with its new icon in the editor:

# item.gd@icon("res://interface/icons/item.png")class_nameItemextendsNode

Tip

SVG images that are used as custom node icons should have theEditor > Scale With Editor Scale andEditor > Convert Icons With Editor Themeimport options enabled. This allowsicons to follow the editor's scale and theming settings if the icons are designed withthe same color palette as Godot's own icons.

Here's a class file example:

# Saved as a file named 'character.gd'.class_nameCharactervarhealth=5funcprint_health():print(health)funcprint_this_script_three_times():print(get_script())print(ResourceLoader.load("res://character.gd"))print(Character)

If you want to useextends too, you can keep both on the same line:

class_nameMyNodeextendsNode

Named classes are globally registered, which means they become available to usein other scripts without the need toload orpreload them:

varplayerfunc_ready():player=Character.new()

Note

Godot initializes non-static variables every time you create an instance,and this includes arrays and dictionaries. This is in the spirit of thread safety,since scripts can be initialized in separate threads without the user knowing.

Warning

The Godot editor will hide these custom classes with names that begin with the prefix"Editor" in the 'Create New Node' or 'Create New Scene' dialog windows. The classesare available for instantiation at runtime via their class names, but areautomatically hidden by the editor windows along with the built-in editor nodes usedby the Godot editor.

# 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

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

super(args)

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

funcoverriding():return0# This overrides the method in the base class.funcdont_override():returnsuper.overriding()# This calls the method as defined in the base class.

func_init(arg):super("some_default",arg)# Call the custom base constructor.

# 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):super(e)# Do something with 'e'.message=m

staticvarmy_static_var=1staticfunc_static_init():my_static_var=2

# 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()

# 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()

Exports

Properties (setters and getters)

Sometimes, you want a class' member variable to do more than just hold data and actually performsome validation or computation whenever its value changes. It may also be desired toencapsulate its access in some way.

For this, GDScript provides a special syntax to define properties using theset andgetkeywords after a variable declaration. Then you can define a code block that will be executedwhen the variable is accessed or assigned.

Example:

varmilliseconds:int=0varseconds:int:get:returnmilliseconds/1000set(value):milliseconds=value*1000

varmy_prop:get=get_my_prop,set=set_my_prop

varmy_prop:get=get_my_prop,set=set_my_prop

signalchanged(new_value)varwarns_when_changed="some value":get:returnwarns_when_changedset(value):changed.emit(value)warns_when_changed=value

varmy_prop:set=set_my_propfuncset_my_prop(value):my_prop=value# No infinite recursion.

varmy_prop:set(value):set_my_prop(value)funcset_my_prop(value):my_prop=value# Infinite recursion, since `set_my_prop()` is not the setter.

Tool mode

By default, scripts don't run inside the editor and only the exportedproperties can be changed. In some cases, it is desired that they do runinside the editor (as long as they don't execute game code or manuallyavoid doing so). For this, the@tool annotation exists and must beplaced at the top of the file:

@toolextendsButtonfunc_ready():print("Hello")

SeeRunning code in the editor for more information.

Memory management

Godot implements reference counting to free certain instances that are no longerused, instead of a garbage collector, or requiring purely manual management.Any instance of theRefCounted class (or any class that inheritsit, such asResource) will be freed automatically when no longerin use. For an instance of any class that is not aRefCounted(such asNode or the baseObject type), it willremain in memory until it is deleted withfree() (orqueue_free()for Nodes).

To avoid reference cycles that can't be freed, aWeakReffunction is provided for creating weak references, which allow accessto the object without preventing aRefCounted from freeing.Here is an example:

extendsNodevarmy_file_reffunc_ready():varf=FileAccess.open("user://example_file.json",FileAccess.READ)my_file_ref=weakref(f)# the FileAccess class inherits RefCounted, so it will be freed when not in use# the WeakRef will not prevent f from being freed when other_node is finishedother_node.use_file(f)func_this_is_called_later():varmy_file=my_file_ref.get_ref()ifmy_file:my_file.close()

Alternatively, when not using references, theis_instance_valid(instance) can be used to check if an object has beenfreed.

Signals

Signals are a tool to emit messages from an object that other objects can reactto. To create custom signals for a class, use thesignal keyword.

extendsNode# A signal named health_depleted.signalhealth_depleted

You can connect these signals to methods the same way you connect built-insignals of nodes likeButton orRigidBody3D.

In the example below, we connect thehealth_depleted signal from aCharacter node to aGame node. When theCharacter node emits thesignal, the game node's_on_character_health_depleted is called:

# game.gdfunc_ready():varcharacter_node=get_node('Character')character_node.health_depleted.connect(_on_character_health_depleted)func_on_character_health_depleted():get_tree().reload_current_scene()

You can emit as many arguments as you want along with a signal.

Here is an example where this is useful. Let's say we want a life bar on screento react to health changes with an animation, but we want to keep the userinterface separate from the player in our scene tree.

In ourcharacter.gd script, we define ahealth_changed signal and emitit withSignal.emit(), and fromaGame node higher up our scene tree, we connect it to theLifebar usingtheSignal.connect() method:

# character.gd...signalhealth_changedfunctake_damage(amount):varold_health=healthhealth-=amount# We emit the health_changed signal every time the# character takes damage.health_changed.emit(old_health,health)...

# lifebar.gd# Here, we define a function to use as a callback when the# character's health_changed signal is emitted....func_on_Character_health_changed(old_value,new_value):ifold_value>new_value:progress_bar.modulate=Color.REDelse:progress_bar.modulate=Color.GREEN# Imagine that `animate` is a user-defined function that animates the# bar filling up or emptying itself.progress_bar.animate(old_value,new_value)...

In theGame node, we get both theCharacter andLifebar nodes, thenconnect the character, that emits the signal, to the receiver, theLifebarnode in this case.

# game.gdfunc_ready():varcharacter_node=get_node('Character')varlifebar_node=get_node('UserInterface/Lifebar')character_node.health_changed.connect(lifebar_node._on_Character_health_changed)

This allows theLifebar to react to health changes without coupling it totheCharacter node.

You can write optional argument names in parentheses after the signal'sdefinition:

# Defining a signal that forwards two arguments.signalhealth_changed(old_value,new_value)

These arguments show up in the editor's node dock, and Godot can use them togenerate callback functions for you. However, you can still emit any number ofarguments when you emit signals; it's up to you to emit the correct values.

You can also create copies of GDScript Callable objects which accept additionalarguments usingCallable.bind(). Thisallows you to add extra information to the connection if the emitted signalitself doesn't give you access to all the data that you need.

When the signal is emitted, the callback method receives the bound values, inaddition to those provided by the signal.

Building on the example above, let's say we want to display a log of the damagetaken by each character on the screen, likePlayer1took22damage.. Thehealth_changed signal doesn't give us the name of the character that tookdamage. So when we connect the signal to the in-game console, we can add thecharacter's name using the bind method:

# game.gdfunc_ready():varcharacter_node=get_node('Character')varbattle_log_node=get_node('UserInterface/BattleLog')character_node.health_changed.connect(battle_log_node._on_Character_health_changed.bind(character_node.name))

OurBattleLog node receives each bound element as an extra argument:

# battle_log.gdfunc_on_Character_health_changed(old_value,new_value,character_name):ifnotnew_value<=old_value:returnvardamage=old_value-new_valuelabel.text+=character_name+" took "+str(damage)+" damage."

funcwait_confirmation():print("Prompting user")await$Button.button_up# Waits for the button_up signal from Button node.print("User confirmed")returntrue

funcrequest_confirmation():print("Will ask the user")varconfirmed=awaitwait_confirmation()ifconfirmed:print("User confirmed")else:print("User cancelled")

funcwrong():varconfirmed=wait_confirmation()# Will give an error.

funcokay():wait_confirmation()print("This will be printed immediately, before the user press the button.")

funcno_wait():varx=awaitget_five()print("This doesn't make this function a coroutine.")funcget_five():return5

funcget_signal():return$Button.button_upfuncwait_button():awaitget_signal()print("Button was pressed")

Assert keyword

Theassert keyword can be used to check conditions in debug builds. Theseassertions are ignored in non-debug builds. This means that the expressionpassed as argument won't be evaluated in a project exported in release mode.Due to this, assertions mustnot contain expressions that haveside effects. Otherwise, the behavior of the script would varydepending on whether the project is run in a debug build.

# Check that 'i' is 0. If 'i' is not 0, an assertion error will occur.assert(i==0)

When running a project from the editor, the project will be paused if anassertion error occurs.

You can optionally pass a custom error message to be shown if the assertionfails:

assert(enemy_power<256,"Enemy is too powerful!")