Godot Array: GDScript Array Methods with Examples

Q: How do I add an item to an array in Godot?

Use append() (or its alias pushback()) to add at the end: items.append("key"). pushfront() adds at the start and insert(index, value) adds at any position.

Q: How do I remove an item from an array in GDScript?

erase(value) removes the first item equal to the value. removeat(index) removes the item at a position. popback() and pop_front() remove and return the last or first item, and clear() empties the array.

Q: How do I check if an array contains a value in Godot?

Use has() or in: items.has("key") and "key" in items both return true or false. find(value) returns the index, or -1 when the value is missing.

Q: How do I copy an array in Godot?

Call duplicate(). Writing var b = a does not copy: both names point at the same array, so a change through one shows through the other. duplicate(true) also copies nested arrays and dictionaries.

An Array is an ordered list of values. Write it with square brackets:

extends Node

func _ready():
	var inventory = ["sword", "shield", "potion"]
	print(inventory)
	print(inventory[0])        # first item
	print(inventory[-1])       # last item
	print(inventory.size())    # number of items
	inventory[1] = "bow"
	print(inventory)

["sword", "shield", "potion"]
sword
potion
3
["sword", "bow", "potion"]

Indexes start at 0. A negative index counts from the end. An array can hold mixed types, such as [1, "two", Vector2(3, 4)]. To allow only one type, use a typed array: var inventory: Array[String] = [].

Adding Items

extends Node

func _ready():
	var queue = ["bat"]
	queue.append("slime")         # at the end
	queue.push_front("goblin")    # at the start
	queue.insert(1, "spider")     # at index 1
	print(queue)
	queue.append_array(["orc", "troll"])
	print(queue)

["goblin", "spider", "bat", "slime"]
["goblin", "spider", "bat", "slime", "orc", "troll"]

push_back() is the same as append(). append_array() adds every item of another array.

Removing Items

extends Node

func _ready():
	var items = ["dagger", "axe", "sword", "bow", "staff"]
	items.erase("bow")             # removes the first "bow"
	print(items)
	items.remove_at(0)             # removes the item at index 0
	print(items)
	var last = items.pop_back()    # removes and returns the last item
	var first = items.pop_front()  # removes and returns the first item
	print(last, " ", first, " ", items)
	items.clear()
	print(items, " ", items.is_empty())

["dagger", "axe", "sword", "staff"]
["axe", "sword", "staff"]
staff axe ["sword"]
[] true

erase() does nothing when the value is missing. remove_at() with an index past the end prints an error and leaves the array unchanged. pop_back() on an empty array returns null.

Finding Items

extends Node

func _ready():
	var scores = [40, 75, 75, 90]
	print(scores.has(75), " ", 75 in scores)
	print(scores.find(75))        # first index, or -1
	print(scores.find(10))
	print(scores.count(75))
	print(scores.max(), " ", scores.min())
	print(scores.front(), " ", scores.back())

true true
1
-1
2
90 40
40 90

Sorting

sort() sorts in place, from small to large. sort_custom() takes a function that returns true when the first argument should come before the second:

extends Node

func _ready():
	var numbers = [5, 3, 8, 1]
	numbers.sort()
	print(numbers)
	numbers.reverse()
	print(numbers)

	var players = [
		{"name": "Ana", "score": 120},
		{"name": "Bo", "score": 300},
		{"name": "Chidi", "score": 95},
	]
	players.sort_custom(func(a, b): return a.score > b.score)
	for p in players:
		print(p.name, " ", p.score)

[1, 3, 5, 8]
[8, 5, 3, 1]
Bo 300
Ana 120
Chidi 95

a.score works on a dictionary as a shorthand for a["score"] when the key is a valid name.

Slices

slice(begin, end) returns a new array from begin up to, but not including, end:

extends Node

func _ready():
	var days = ["mon", "tue", "wed", "thu", "fri"]
	print(days.slice(1, 3))
	print(days.slice(3))       # to the end
	print(days.slice(-2))      # the last two

["tue", "wed"]
["thu", "fri"]
["thu", "fri"]

map, filter, reduce, any and all

These take a function, usually a lambda, and return a result without changing the array:

extends Node

func _ready():
	var damage = [12, 5, 30, 8]
	print(damage.map(func(d): return d * 2))
	print(damage.filter(func(d): return d >= 10))
	print(damage.reduce(func(total, d): return total + d, 0))
	print(damage.any(func(d): return d > 25))
	print(damage.all(func(d): return d > 0))

[24, 10, 60, 16]
[12, 30]
55
true
true

Arrays Are Shared, Not Copied

Assigning an array to another variable does not copy it. Both names point at the same array:

extends Node

func _ready():
	var original = [1, 2, 3]
	var same = original
	same.append(4)
	print(original)

	var copy = original.duplicate()
	copy.append(5)
	print(original, " ", copy)

[1, 2, 3, 4]
[1, 2, 3, 4] [1, 2, 3, 4, 5]

The same happens when you pass an array to a function: the function can change the caller's array. Use duplicate() for a separate copy, and duplicate(true) to copy nested arrays and dictionaries too.

2D Arrays

An array of arrays works as a grid. Read a cell with grid[y][x]:

extends Node

func _ready():
	var width := 3
	var height := 2
	var grid = []
	for y in height:
		var row = []
		for x in width:
			row.append(0)
		grid.append(row)
	grid[1][2] = 7
	print(grid)
	print(grid[1][2])

[[0, 0, 0], [0, 0, 7]]
7

Build each row as a new array inside the loop, as above. Appending one row array to every slot would make every row the same shared array, so changing one cell would change a whole column.

A Fixed Size Array

resize() sets the size, filling new slots with null, and fill() sets every slot:

extends Node

func _ready():
	var slots = []
	slots.resize(4)
	print(slots)
	slots.fill(0)
	print(slots)

[<null>, <null>, <null>, <null>]
[0, 0, 0, 0]

Quick Reference

Task	Method
Add at the end	`append(x)`, `push_back(x)`
Add at the start or at an index	`push_front(x)`, `insert(i, x)`
Remove by value or index	`erase(x)`, `remove_at(i)`
Remove and return the first or last	`pop_front()`, `pop_back()`
Length, empty	`size()`, `is_empty()`
Contains, position	`has(x)`, `x in a`, `find(x)`
Sort	`sort()`, `sort_custom(f)`, `reverse()`
Part of the array	`slice(begin, end)`
Copy	`duplicate()`, `duplicate(true)`
A random item	`pick_random()`
Transform	`map(f)`, `filter(f)`, `reduce(f, start)`

Frequently Asked Questions

How do I add an item to an array in Godot?

Use append() (or its alias push_back()) to add at the end: items.append("key"). push_front() adds at the start and insert(index, value) adds at any position.

How do I remove an item from an array in GDScript?

erase(value) removes the first item equal to the value. remove_at(index) removes the item at a position. pop_back() and pop_front() remove and return the last or first item, and clear() empties the array.

How do I check if an array contains a value in Godot?

Use has() or in: items.has("key") and "key" in items both return true or false. find(value) returns the index, or -1 when the value is missing.

How do I copy an array in Godot?

Call duplicate(). Writing var b = a does not copy: both names point at the same array, so a change through one shows through the other. duplicate(true) also copies nested arrays and dictionaries.

How do I make a 2D array in GDScript?

Make an array of arrays: append one inner array per row, then read a cell with grid[y][x]. For a fixed size grid of tiles, a TileMapLayer or a flat array indexed with y * width + x are common alternatives.

Related concepts