Generics

Generic types (often abbreviated to "Generics") is a feature of some programming languages that allows types to use parameters.

In GDScript, this applies only to arrays, and dictionaries which can use the Array[type] or Dictionary[key_type, value_type] syntax to describe what kind of items they are allowed to contain.

• Array[String] is an array of StringStrings; like ["a", "b", "c"].
• Array[int] is an array of intints; like [1, 2, 3].
• Array[Vector2] is an array of Vector2Vector2s; like [Vector2(1, 2), Vector2(3, 4)].
• Dictionary[String, int] is a dictionary with StringString keys and intint values; like {"a": 1, "b": 2}.
• Dictionary[Vector2i, Node] is a dictionary with Vector2iVector2i keys and NodeNode values; like {Vector2i(1, 2): $Player, Vector2i(5, 8): $Enemy}.

And so on. We call any array that restricts the type of its items a "typed array" and any dictionary that restricts the type of its keys and values a "typed dictionary".

Why do I need it?

For example, if you have an array of StringStrings like so:

var letters_list: Array[String] = ["a", "b", "c"]

Then trying to add something that isn't a StringString would result in an error:

var letters_list: Array[String] = ["a", "b", "c", 15]
# Error: Cannot include a value of type "int" as "String"

The following also gives an error, but unfortunately only at runtime instead of inside the editor:

letters_list.append(15)
# Error: Attempted to push_back a variable of type 'int' into a TypedArray of type 'String'.

It also gives us strong type guarantees when retrieving an item. In this example, you do not need to type the letter variable:

var letters_list: Array[String] = ["a", "b", "c"]
var letter := letters_list[2]

Godot can infer that the type is a StringString, thanks to the Array[String] type hint (otherwise, you would have to write var letter: String = letters_list[2]).

For dictionaries, the same applies. If you have a dictionary of StringString keys and intint values:

var players_scores: Dictionary[String, int] = {
	"player 1": 7,
	"player 2": 12
}

It's particularly useful when retrieving items, or looping over a dictionary; consider the example below, where a dictionary is used to store the location of players and enemies on a grid in a turn-based game:

var entities_positions: Dictionary[Vector2i, Node] = {
	Vector2i(1, 2): $Player,
	Vector2i(5, 8): $Enemy
}

for position in entities_positions.keys():
	var entity := entities_positions[position]
	print("Entity at position ", position, " is ", entity.name)

Here, Godot can infer that position is a Vector2iVector2i and entity is a NodeNode, which allows us to access their properties and methods without needing to type them explicitly.

Limitations

The type inference isn't perfect. For example:

var letters_list: Array[String] = ["a"]
var letter := letters_list[20]

In this example, letter is null (there aren't 20 items in the array) but Godot assumes it to be a StringString. Always be aware that Godot cannot know if an array index is valid; it doesn't check boundaries.

It is also not possible to use Array[Array[type]] or Dictionary[Array[type]] to create a typed array of typed arrays. You can use Array[Array], Dictionary[Array], Dictionary[Dictionary] and so on, but the internal elements can't be typed; there can be only one level of typing.

Finally, as I said earlier, the only generic types are ArrayArray and DictionaryDictionary. No other GDScript type is generic.

Still, even though the type inference is limited and the generic aspect too, typing arrays and dictionaries provides more documentation and helpful hints, so we recommend always using it when possible.

Your own classes

You can also use your own classes. For example, if you had an Item class that contained a StringString and an intint:

class_name Item

var name := ""
var strength := 10

Then you can do this:

var inventory: Array[Item] = [
	Item.new(),
	Item.new(),
	Item.new()
]

Or:

var inventory: Dictionary[String, Item] = {
	"sword": Item.new(),
	"shield": Item.new()
}

Other languages have more generic types?

Yes, most languages that have generics can apply them across many different situations.

For example, TypeScript allows you to have your own custom generics. Here is a dictionary (called "record" in TypeScript) that accepts only strings as keys, but a custom generic type T as values:

interface Record {
	[key: string]: T;
}

const players_scores: Record = {
	"player 1": 7,
	"player 2": 12
}

const players_names: Record = {
	"player 1": "Alice",
	"player 2": "Bob"
}

Here, the term T is replaced by number in the players_scores variable and by string in the players_names variable.

GDScript's limitation is because it doesn't actually have generics like other languages do; the GDScript developers only implemented a specific way to type arrays and dictionaries because it was a feature that was highly requested.