With typed GDScript, Godot can detect even more errors as you write
code! It gives you and your teammates more information as you’re
working, as the arguments’ types show up when you call a method.

Imagine you’re programming an inventory system. You code an Item
node, then an Inventory. To add items to the inventory, the people
who work with your code should always pass an Item to the
Inventory.add method. With types, you can enforce this:

# In 'Item.gd'.class_nameItem# In 'Inventory.gd'.class_nameInventoryfuncadd(reference:Item,amount:int=1):varitem=find_item(reference)ifnotitem:item=_instance_item_from_db(reference)item.amount+=amount

Another significant advantage of typed GDScript is the new warning
system. From version 3.1, Godot gives you warnings about your code as
you write it: the engine identifies sections of your code that may lead
to issues at runtime, but lets you decide whether or not you want to
leave the code as it is. More on that in a moment.

Static types also give you better code completion options. Below, you
can see the difference between a dynamic and a static typed completion
options for a class called PlayerController.

You’ve probably stored a node in a variable before, and typed a dot to
be left with no autocomplete suggestions:

This is due to dynamic code. Godot cannot know what node or value type
you’re passing to the function. If you write the type explicitly
however, you will get all public methods and variables from the node:

In the future, typed GDScript will also increase code performance:
Just-In-Time compilation and other compiler improvements are already
on the roadmap!

Overall, typed programming gives you a more structured experience. It
helps prevent errors and improves the self-documenting aspect of your
scripts. This is especially helpful when you’re working in a team or on
a long-term project: studies have shown that developers spend most of
their time reading other people’s code, or scripts they wrote in the
past and forgot about. The clearer and the more structured the code, the
faster it is to understand, the faster you can move forward.

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

Imagine an Enemy in your game, that extendsArea2D. You want it to
collide with the Player, a KinematicBody2D with a script called
PlayerController attached to it. You use the on_body_entered
signal to detect the collision. With typed code, the body you detect is
going to be a generic PhysicsBody2D, and not your
PlayerController on the _on_body_entered callback.

You can check if this PhysicsBody2D is your Player with the as
casting keyword, and using the colon : again to force the variable
to use this type. This forces the variable to stick to the
PlayerController type:

As we’re dealing with a custom type, if the body doesn’t extend
PlayerController, the playervariable will be set to null.
We can use this to check if the body is the player or not. We will also
get full autocompletion on the player variable thanks to that cast.

Note

If you try to cast with a built-in type and it fails, Godot will throw an error.

You can also use casting to ensure safe lines. Safe lines are a new
tool in Godot 3.1 to tell you when ambiguous lines of code are
type-safe. As you can mix and match typed and dynamic code, at times,
Godot doesn’t have enough information to know if an 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
supports duck-typing,
so even if your timer is of type Timer, it is also a Node and an
Object, two classes it extends. With dynamic GDScript, you also
don’t care 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), ($PlayerasKinematicBody2D), etc.
Godot will ensure the type works and if so, the line number will turn
green at the left of the script editor.

Unsafe line (line 7) vs Safe Lines (line 6 and 8)

Note

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

# Inventory.gd# 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

Typed GDScript and dynamic GDScript can coexist in the same project. But
I recommended to stick to either style for consistency in your codebase,
and for your peers. It’s easier for everyone to work together if you
follow the same guidelines, and faster to read and understand other
people’s code.

Typed code takes a little more writing, but you get the benefits we
discussed above. Here’s an example of the same, empty script, in a
dynamic style:

The bullet variable could hold any CollisionObject2D here, but
we make sure it is our Bullet, a node we created for our project. If
it’s anything else, like an Area2D, or any node that doesn’t extend
Bullet, the bullet variable will be null.

Typed GDScript is a powerful tool. Available as of version 3.1 of Godot, it
helps you write more structured code, avoid common errors, and
create scalable systems. In the future, static types will also bring you
a nice performance boost thanks to upcoming compiler optimizations.