What can be a type hint

Here is a complete list of what can be used as a type hint:

1. Variant. Any type. In most cases this is not much different from an untypeddeclaration, but increases readability. As a return type, forces the functionto explicitly return some value.

2. (Only return type)void. Indicates that the function does not return any value.

3. Built-in types.

4. Native classes (Object,Node,Area2D,Camera2D, etc.).

5. Global classes.

6. Inner classes.

7. Global, native and custom named enums. Note that an enum type is just anint,there is no guarantee that the value belongs to the set of enum values.

8. Constants (including local ones) if they contain a preloaded class or enum.

You can use any class, including your custom classes, as types. There are two waysto use them in scripts. The first method is to preload the script you want to useas a type in a constant:

constRifle=preload("res://player/weapons/rifle.gd")varmy_rifle:Rifle

The second method is to use theclass_name keyword when you create.For the example above, yourrifle.gd would look like this:

class_nameRifleextendsNode2D

If you useclass_name, Godot registers theRifle type globally in the editor,and you can use it anywhere, without having to preload it into a constant:

varmy_rifle:Rifle

Specify the return type of a function with the arrow->

To define the return type of a function, write a dash and a right angle bracket->after its declaration, followed by the return type:

func_process(delta:float)->void:pass

The typevoid means the function does not return anything. You can use any type,as with variables:

funchit(damage:float)->bool:health_points-=damagereturnhealth_points<=0

You can also use your own classes as return types:

# Adds an item to the inventory and returns it.funcadd(reference:Item,amount:int)->Item:varitem:Item=find_item(reference)ifnotitem:item=ItemDatabase.get_instance(reference)item.amount+=amountreturnitem

Covariance and contravariance

When inheriting base class methods, you should follow theLiskov substitutionprinciple.

Covariance: When you inherit a method, you can specify a return type that ismore specific (subtype) than the parent method.

Contravariance: When you inherit a method, you can specify a parameter typethat is less specific (supertype) than the parent method.

Example:

class_nameParentfuncget_property(param:Label)->Node:# ...

class_nameChildextendsParent# `Control` is a supertype of `Label`.# `Node2D` is a subtype of `Node`.funcget_property(param:Control)->Node2D:# ...

Specify the element type of anArray

To define the type of anArray, enclose the type name in[].

An array's type applies tofor loop variables, as well as some operators like[],[...]= (assignment), and+. Array methods(such aspush_back) and other operators (such as==)are still untyped. Built-in types, native and custom classes,and enums may be used as element types. Nested array types (likeArray[Array[int]])are not supported.

varscores:Array[int]=[10,20,30]varvehicles:Array[Node]=[$Car,$Plane]varitems:Array[Item]=[Item.new()]vararray_of_arrays:Array[Array]=[[],[]]# var arrays: Array[Array[int]] -- disallowedforscoreinscores:# score has type `int`# The following would be errors:scores+=vehiclesvars:String=scores[0]scores[0]="lots"

Since Godot 4.2, you can also specify a type for the loop variable in afor loop.For instance, you can write:

varnames=["John","Marta","Samantha","Jimmy"]forname:Stringinnames:pass

The array will remain untyped, but thename variable within thefor loopwill always be ofString type.

Specify the element type of aDictionary

To define the type of aDictionary's keys and values, enclose the type name in[]and separate the key and value type with a comma.

A dictionary's value type applies tofor loop variables, as well as some operators like[] and[...]= (assignment). Dictionary methods that return valuesand other operators (such as==) are still untyped. Built-in types, nativeand custom classes, and enums may be used as element types. Nested typed collections(likeDictionary[String,Dictionary[String,int]]) are not supported.

varfruit_costs:Dictionary[String,int]={"apple":5,"orange":10}varvehicles:Dictionary[String,Node]={"car":$Car,"plane":$Plane}varitem_tiles:Dictionary[Vector2i,Item]={Vector2i(0,0):Item.new(),Vector2i(0,1):Item.new()}vardictionary_of_dictionaries:Dictionary[String,Dictionary]={{}}# var dicts: Dictionary[String, Dictionary[String, int]] -- disallowedforcostinfruit_costs:# cost has type `int`# The following would be errors:fruit_costs["pear"]+=vehiclesvars:String=fruit_costs["apple"]fruit_costs["orange"]="lots"

Type casting

Type casting is an important concept in typed languages.Casting is the conversion of a value from one type to another.

Imagine anEnemy in your game, thatextendsArea2D. You want it to collidewith thePlayer, aCharacterBody2D with a script calledPlayerControllerattached to it. You use thebody_entered signal to detect the collision.With typed code, the body you detect is going to be a genericPhysicsBody2D,and not yourPlayerController on the_on_body_entered callback.

You can check if thisPhysicsBody2D is yourPlayer with theas keyword,and using the colon: again to force the variable to use this type.This forces the variable to stick to thePlayerController type:

func_on_body_entered(body:PhysicsBody2D)->void:varplayer:=bodyasPlayerControllerifnotplayer:returnplayer.damage()

As we're dealing with a custom type, if thebody doesn't extendPlayerController, theplayer variable will be set tonull.We can use this to check if the body is the player or not. We will alsoget full autocompletion on the player variable thanks to that cast.

ifnot(bodyisPlayerController):push_error("Bug: body is not PlayerController.")varplayer:PlayerController=bodyifnotplayer:returnplayer.damage()

ifbodyisnotPlayerController:push_error("Bug: body is not PlayerController")

assert(bodyisPlayerController,"Bug: body is not PlayerController.")varplayer:PlayerController=bodyifnotplayer:returnplayer.damage()

Safe lines

You can also use casting to ensure safe lines. Safe lines are a tool to tell youwhen ambiguous lines of code are type-safe. As you can mix and match typedand dynamic code, at times, Godot doesn't have enough information to know ifan instruction will trigger an error or not at runtime.

This happens when you get a child node. Let's take a timer for example:with dynamic code, you can get the node with$Timer. GDScript supportsduck-typing,so even if your timer is of typeTimer, it is also aNode andanObject, two classes it extends. With dynamic GDScript, you also don'tcare about the node's type as long as it has the methods you need to call.

You can use casting to tell Godot the type you expect when you get a node:($TimerasTimer),($PlayerasCharacterBody2D), etc.Godot will ensure the type works and if so, the line number will turngreen at the left of the script editor.

Note

Safe lines do not always mean better or more reliable code. See the note aboveabout theas keyword. For example:

@onreadyvarnode_1:=$Node1asType1# Safe line.@onreadyvarnode_2:Type2=$Node2# Unsafe line.

Even thoughnode_2 declaration is marked as an unsafe line, it is morereliable thannode_1 declaration. Because if you change the node typein the scene and accidentally forget to change it in the script, the errorwill be detected immediately when the scene is loaded. Unlikenode_1,which will be silently cast tonull and the error will be detected later.

Note

You can turn off safe lines or change their color in the editor settings.

Global scope methods

The following global scope methods are not statically typed, but they havetyped counterparts available. These methods return statically typed values:

When using static typing, use the typed global scope methods whenever possible.This ensures you have safe lines and benefit from typed instructions forbetter performance.

UNSAFE_PROPERTY_ACCESS andUNSAFE_METHOD_ACCESS warnings

In this example, we aim to set a property and call a method on an objectthat has a script attached withclass_nameMyScript and thatextendsNode2D. If we have a reference to the object as aNode2D (for instance,as it was passed to us by the physics system), we can first check if theproperty and method exist and then set and call them if they do:

if"some_property"innode_2d:node_2d.some_property=20# Produces UNSAFE_PROPERTY_ACCESS warning.ifnode_2d.has_method("some_function"):node_2d.some_function()# Produces UNSAFE_METHOD_ACCESS warning.

However, this code will produceUNSAFE_PROPERTY_ACCESS andUNSAFE_METHOD_ACCESS warnings as the property and method are not presentin the referenced type - in this case aNode2D. To make these operationssafe, you can first check if the object is of typeMyScript using theis keyword and then declare a variable with the typeMyScript onwhich you can set its properties and call its methods:

ifnode_2disMyScript:varmy_script:MyScript=node_2dmy_script.some_property=20my_script.some_function()

Alternatively, you can declare a variable and use theas operator to tryto cast the object. You'll then want to check whether the cast was successfulby confirming that the variable was assigned:

varmy_script:=node_2dasMyScriptifmy_script!=null:my_script.some_property=20my_script.some_function()

UNSAFE_CAST warning

In this example, we would like the label connected to an object entering ourcollision area to show the area's name. Once the object enters the collisionarea, the physics system sends a signal with aNode2D object, and the moststraightforward (but not statically typed) solution to do what we want couldbe achieved like this:

func_on_body_entered(body:Node2D)->void:body.label.text=name# Produces UNSAFE_PROPERTY_ACCESS warning.

This piece of code produces anUNSAFE_PROPERTY_ACCESS warning becauselabel is not defined inNode2D. To solve this, we could first check if thelabel property exist and cast it to typeLabel before settings its textproperty like so:

func_on_body_entered(body:Node2D)->void:if"label"inbody:(body.labelasLabel).text=name# Produces UNSAFE_CAST warning.

However, this produces anUNSAFE_CAST warning becausebody.label is of aVariant type. To safely get the property in the type you want, you can use theObject.get() method which returns the object as aVariant value or returnsnull if the property doesn't exist. You can then determine whether theproperty contains an object of the right type using theis keyword, andfinally declare a statically typed variable with the object:

func_on_body_entered(body:Node2D)->void:varlabel_variant:Variant=body.get("label")iflabel_variantisLabel:varlabel:Label=label_variantlabel.text=name