GDScript Packed Arrays: PackedVector2Array and More

A packed array is a list of one built-in type, stored tightly in memory. Godot uses them wherever it handles many values at once, such as the points of a polygon:

extends Node

func _ready():
	var points := PackedVector2Array([Vector2(0, 0), Vector2(100, 0), Vector2(50, 80)])
	points.append(Vector2(0, 80))
	print(points)
	print(points.size(), " points, the second is ", points[1])

[(0.0, 0.0), (100.0, 0.0), (50.0, 80.0), (0.0, 80.0)]
4 points, the second is (100.0, 0.0)

You index, append, loop and check size() the same way as with an Array.

The Packed Array Types

Where You Meet Them

Many engine properties and methods use packed arrays:

• String.split() returns a PackedStringArray.
• Line2D.points, Polygon2D.polygon and CollisionPolygon2D.polygon are PackedVector2Arrays.
• A navigation path from NavigationServer2D.map_get_path() is a PackedVector2Array.
• File and network data is a PackedByteArray, for example FileAccess.get_file_as_bytes().

extends Node

func _ready():
	var tags := "fire,ice,poison".split(",")
	print(tags, " ", tags.has("ice"))
	print(" + ".join(tags))

	var bytes := "Hi".to_utf8_buffer()
	print(bytes, " ", bytes.get_string_from_utf8())

["fire", "ice", "poison"] true
fire + ice + poison
[72, 105] Hi

Packed Array, Array or Typed Array?

A good rule: use a typed array for game objects and small lists, and a packed array for many plain values or when an engine API asks for one. Convert between them with the constructors:

extends Node

func _ready():
	var packed := PackedInt32Array([3, 1, 2])
	var plain := Array(packed)
	print(plain.map(func(x): return x * 10))
	var back := PackedInt32Array(plain)
	back.sort()
	print(back)

[30, 10, 20]
[1, 2, 3]

Packed Arrays Are Shared

In Godot 4, a packed array is passed by reference, like an Array. Two variables can point at the same one:

extends Node

func add_bonus(values: PackedInt32Array) -> void:
	values.append(99)

func _ready():
	var a := PackedInt32Array([1, 2])
	var b := a
	b.append(3)
	add_bonus(a)
	print(a)
	var copy := a.duplicate()
	copy.append(4)
	print(a, " ", copy)

[1, 2, 3, 99]
[1, 2, 3, 99] [1, 2, 3, 99, 4]

The Overflow Trap

Each item has a fixed size, so a value too big for it wraps around without an error:

extends Node

func _ready():
	print(PackedByteArray([300, 5]))
	var ints := PackedInt32Array()
	ints.append(3000000000)
	print(ints)

[44, 5]
[-1294967296]

Use PackedInt64Array for big whole numbers and PackedFloat64Array when 32-bit floats lose too much precision.