GDScript Static Typing: Types, := and Return Types

GDScript lets you choose: leave a variable dynamic, or give it a type. A type is written after a colon:

extends Node

var speed: float = 200.0
var lives := 3          # type inferred: int
var nickname = "Ana"    # dynamic: no type

func _ready():
	print(speed, " ", lives, " ", nickname)
	nickname = 42       # fine, it is dynamic
	print(nickname)

200.0 3 Ana
42

speed and lives are typed. Writing lives = "three" anywhere in this script is an error the editor shows while you type, and the script refuses to run.

Typed Parameters and Return Types

Functions take types too. Put the parameter's type after its name and the return type after ->:

extends Node

func damage_after_armor(damage: int, armor: float) -> int:
	return int(damage * (1.0 - armor))

func log_hit(amount: int) -> void:
	print("Hit for ", amount)

func _ready():
	var dealt := damage_after_armor(50, 0.2)
	log_hit(dealt)

Hit for 40

-> void means the function returns nothing. With a return type, Godot checks every return in the function and every place you use the result.

What Types Catch

Typing turns run-time surprises into errors you see at once. Each of these stops the script before it starts:

var hp: int = "ten"
# Parse Error: Cannot assign a value of type String to variable "hp" with specified type int.

func half(x: int) -> int:
	return "half"
# Parse Error: Cannot return a value of type "String" as "int".

A typed variable can still receive a wrong value from a dynamic one. Godot catches that when the line runs:

extends Node

func _ready():
	# This stops with an error on purpose.
	var from_save = "seven"  # dynamic, so Godot cannot check it early
	var level: int = 1
	level = from_save
	print(level)

SCRIPT ERROR: Trying to assign value of type 'String' to a variable of type 'int'.
          at: _ready (res://main.gd:7)
          GDScript backtrace (most recent call first):
              [0] _ready (res://main.gd:7)

Numbers convert between int and float without an error. A float stored in an int variable drops its decimals, and the editor shows a NARROWING_CONVERSION warning:

extends Node

func _ready():
	var whole: int = 3.9
	var real: float = 2
	print(whole, " ", real)

3 2.0

Checking and Casting Types

is tests a value's type. as casts a value to a type, and gives null when it is not that type:

extends Node

func describe(value) -> String:
	if value is int:
		return "an int"
	if value is String:
		return "a string"
	if value is Node:
		return "a node"
	return type_string(typeof(value))

func _ready():
	print(describe(5))
	print(describe("hi"))
	print(describe(self))
	print(describe(2.5))
	var some_node: Node = self
	var as_label := some_node as Label
	print(as_label)

an int
a string
a node
float
<null>

In a game you use as on a node you found by name or got from a signal:

func _on_body_entered(body: Node2D) -> void:
	var player := body as Player
	if player:
		player.take_damage(10)

Types You Can Use

• Built-in types: int, float, bool, String, StringName, Vector2, Vector3, Color, Array, Dictionary, Callable and the rest. See data types.
• Engine classes: Node, Node2D, Sprite2D, CharacterBody2D, Resource and every other class in the docs.
• Your own classes, by their class_name.
• Typed collections: Array[int] (typed arrays) and Dictionary[String, int] (dictionaries).
• Your enums: var state: State.

When to Type

Type almost everything. Typed code:

• shows mistakes in the editor before you press Play;
• gives better autocompletion, because the editor knows what a variable holds;
• runs faster, since Godot can skip type checks on each operation.

Leave a variable dynamic when it holds different types, such as a value read from a JSON file before you check it. To make Godot insist on types, open Project Settings, turn on Advanced Settings, and under Debug > GDScript set Untyped Declaration to Warn or Error.