GDScript Typed Arrays: Array[int], Array[Node] and assign()

A typed array holds one type of value. Write the type in square brackets after Array:

extends Node

var scores: Array[int] = [120, 95]
var names: Array[String] = ["Ana", "Bo"]

func _ready():
	scores.append(300)
	print(scores, " ", names)
	print(scores.is_typed())

[120, 95, 300] ["Ana", "Bo"]
true

Every array method works the same on a typed array. The difference is that the editor knows each item's type, so scores[0]. autocompletes int methods, and a loop over names gives typed String values.

Wrong Values Are Refused

Adding a value of the wrong type fails at run time with an error, and the array stays unchanged:

extends Node

func _ready():
	# This prints an error on purpose.
	var hp: Array[int] = [10]
	var from_file = "twenty"
	hp.append(from_file)
	print(hp)

ERROR: Attempted to push_back a variable of type 'String' into a TypedArray of type 'int'.
   at: _internal_validate (./core/variant/container_type_validate.h:73)
   GDScript backtrace (most recent call first):
       [0] _ready (res://main.gd:7)
ERROR: Condition "!_p->typed.validate(value, "push_back")" is true.
   at: push_back (core/variant/array.cpp:285)
   GDScript backtrace (most recent call first):
       [0] _ready (res://main.gd:7)
[10]

An int stored in an Array[float] is converted, so var speeds: Array[float] = [1, 2.5] holds [1.0, 2.5].

Arrays of Nodes and Your Own Classes

Any class works as the item type: engine nodes, resources, and your own class_name scripts:

extends Node

class Enemy:
	var name: String
	var hp: int
	func _init(enemy_name: String, enemy_hp: int):
		name = enemy_name
		hp = enemy_hp

func _ready():
	var wave: Array[Enemy] = [Enemy.new("slime", 5), Enemy.new("bat", 3)]
	wave.append(Enemy.new("golem", 40))
	for enemy in wave:
		print(enemy.name, " has ", enemy.hp, " hp")

slime has 5 hp
bat has 3 hp
golem has 40 hp

In a game you will often collect child nodes this way: var coins: Array[Node] = get_tree().get_nodes_in_group("coins").

Typed Parameters and Return Values

extends Node

func total(values: Array[int]) -> int:
	var sum := 0
	for v in values:
		sum += v
	return sum

func _ready():
	var hits: Array[int] = [12, 7, 30]
	print(total(hits))

49

The "Trying to assign an array of type Array" Error

filter(), slice() and duplicate() on a typed array return a typed array. map() does not: it always returns a plain Array, because the function may return any type. Storing its result in a typed variable fails:

var hp: Array[int] = [10, 20]
var doubled: Array[int] = hp.map(func(x): return x * 2)
# SCRIPT ERROR: Trying to assign an array of type "Array" to a variable of type "Array[int]".

Create the typed array, then fill it with assign(), which converts each item:

extends Node

func _ready():
	var hp: Array[int] = [10, 20, 30]
	var doubled: Array[int] = []
	doubled.assign(hp.map(func(x): return x * 2))
	print(doubled, " ", doubled.is_typed())
	print(hp.duplicate().is_typed())

[20, 40, 60] true
true

assign() copies any untyped array into a typed one, converting each item. A value that cannot be converted is an error, and the typed array is left empty.

Exporting a Typed Array

An exported typed array shows a list editor in the Inspector, with the right field for each item:

@export var spawn_points: Array[Vector2] = []
@export var waves: Array[PackedScene] = []
@export var loot_table: Array[Resource] = []

Limits

• Nesting is one level deep: Array[Array] is allowed, Array[Array[int]] is not.
• For large lists of plain numbers or vectors, a packed array uses less memory.
• For keys and values, use a typed dictionary: Dictionary[String, int]. See dictionaries.