Arrays

Arrays are used to store lists of various elements, such as numbers or objects. Most times they are one dimensional but may be multi-dimensional for storing data related to grids or 3D space.

Each element of the array is referenced by an integer index value starting from zero for the first element.

An array is an object with various available helper functions to work with it such as for appending new values, getting the size of the array, sorting the values, and shuffling the values etc.

Since it is an object, it is passed into functions by reference, so changes made to it's elements within a function call are made directly to the array object whose reference was passed to the function.

These code examples will help you to understand how to use GDScript Arrays:

extends Node2D

func _ready():
	# Ways to create an array instance
	var a = Array()
	var b = []
	var c = ["a","b","c"]
	
	# Add some items to array 'a'
	a.append("Item 1")
	a.append("Item 2")
	
	# Pass array by reference to a function
	change(a)
	# Confirm that changes were made
	print(a[0])
	
	# Print the size of array 'b'
	print(b.size())
	
	# Shuffle the values of array 'c'
	c.shuffle() # This function doesn't return a value
	# Check that the element order was changed
	print_elements_of(c)
	
func change(a):
	a[0] = 1

func print_elements_of(array):
	# Here we are using one of the Pool array types
	print(PoolStringArray(array).join(""))

To learn more about the available helper functions (Methods) you can check out the documentation for the Array Class.

There is also a PoolByteArray Class that is intended for large data sets. This stores an array of a single data type without any fear of splitting the data into chunks in memory. But you probably don't need to concern yourself with this for now.

However, there are various Pool Array types that have more advanced features than the basic Array. These allow for joining arrays together, and joining string elements into one single string for example.

Most of the time, we have fixed sized arrays, or we append new elements to the end of the array. However, there are advanced uses for arrays such as buffers where we might push a value on to one end of the array and pop a value off the other end. This would be an implementation of a FILO (First In Last Out buffer). Or implement a stack (FIFO) (First In First Out Buffer).

So there are array methods that allow us to push, pop, insert, and remove array elements. And, all types of Array have methods to convert from one type to another to access the extra features.

Next we will look at GDScript Dictionaries.