GDScript Types and Static Typing Practice

GDScript has 38+ built-in types. Here are the ones you'll use most in 2D games:

One thing that trips people up: most built-in types are pass-by-value. Vector2, Color, int, float all get copied on assignment or when passed to a function. Modifying a Vector2 inside a function does not change the original.

The exceptions are Object (and all subclasses like Node, Resource), Array, Dictionary, and packed arrays. These are pass-by-reference.

Three syntaxes cover everything:

# Explicit type
var health: int = 100
var player_name: String = "Hero"
var enemies: Array[Node2D] = []

# Type inference with :=
var speed := 50        # Inferred as int
var damage := 10.5     # Inferred as float
var label := "Hello"   # Inferred as String

# Function signatures
func take_damage(amount: float) -> bool:
	return health <= 0

For-loop variables can be typed too:

for name: String in names:
	print(name)

for i: int in range(10):
	print(i)

Constants work with both : and :=. There's no difference for constants since the value is known at compile time: const MAX_SPEED: float = 200.0 and const MAX_SPEED := 200.0 are identical.

Typed arrays landed in Godot 4.0. Add the element type in brackets:

var scores: Array[int] = [10, 20, 30]
var enemies: Array[Node] = [$Goblin, $Skeleton]
var items: Array[Item] = [Item.new()]

Godot checks the type on every write operation at runtime. Try to insert a wrong type and you get a runtime error. This also works with @export, giving you a smarter Inspector widget.

Typed dictionaries arrived in Godot 4.4 (March 2025). Same bracket syntax:

var fruit_costs: Dictionary[String, int] = {"apple": 5, "orange": 10}
var positions: Dictionary[Vector2i, Item] = {Vector2i(0, 0): Item.new()}

One limitation to know: nested typed collections are not supported. Array[Array[int]] won't compile. You can only go one level deep: Array[Array] works, but the inner array is untyped.

GDScript has two type operators: as for casting and is for checking.

Casting with as behaves differently depending on the type category:

# Object types: returns null on failure (safe)
var player := body as PlayerController
if not player:
	return  # Cast failed, body is not a PlayerController

# Built-in types: throws an ERROR on failure (dangerous!)
var num := value as int  # Crashes if value is a String

This asymmetry is a common source of bugs. For Object types, as is a safe "try-cast." For built-in types like int or String, a failed cast crashes your game.

Checking with is is always safe:

if body is PlayerController:
	body.damage()  # Editor knows body is PlayerController here

if value is int:
	print("It's an integer")

A useful pattern for node references:

@onready var timer := $Timer as Timer  # Green line in editor

One gotcha: is type narrowing is not always recognized by the editor. After if event is InputEventMouseMotion:, you might still see UNSAFE_PROPERTY_ACCESS warnings when accessing event.relative. The workaround is to assign to a typed variable inside the block.

Yes. Typed GDScript generates optimized opcodes that bypass the Variant dispatch system. Instead of unwrapping a Variant, checking its type, looking up the operator, performing the operation, and wrapping the result, typed code takes a direct shortcut.

Independent benchmarks (1 billion iterations, M2 Max) show concrete gains:

The biggest wins come from vector math and engine API calls. If your movement code does position += velocity * delta every frame, typing those variables costs nothing and gives you a measurable speedup.

Variant is Godot's universal container type. It occupies 24 bytes on 64-bit platforms and can hold any of the 38+ built-in types. Every untyped variable in GDScript is a Variant.

var x = 5       # x is a Variant holding an int
var y: int = 5  # y is a native int, no Variant wrapper

Variant matters because many engine methods return it. Array.pop_back(), Dictionary.get(), signal parameters, and dynamic function arguments are all Variant. To get type safety back, you need to cast explicitly:

var text: String = arr.pop_back()  # Implicit Variant -> String
var node := arr.pop_back() as Node  # Explicit cast

One important nuance: only Object-typed variables can be null. Built-in value types (int, float, Vector2, etc.) always hold a valid value. There is no "null int" in GDScript.

Enums are named groups of integer constants:

enum State { IDLE, JUMP = 5, SHOOT }
# State.IDLE = 0, State.JUMP = 5, State.SHOOT = 6

Values auto-increment from the previous entry. You can use enums as type hints:

var current_state: State = State.IDLE

But enums are int under the hood. var x: State = 999 compiles without complaint, even if 999 is not a valid state. GDScript does not validate enum ranges at compile time. See exports tuning for exposing enums to the Inspector.