LearnAI ToolsCareerPractice BuildsPlayContact
Lesson 1021 min read

Built-in Types: Vectors, Arrays & Dictionaries

Master GDScript's Vector2/Vector3 math, resizable Arrays, and key-value Dictionaries — the data types every gameplay script relies on.

Introduction

Beyond the basic types from lesson 4, GDScript ships several types built specifically for games — most notably Vector2 and Vector3 for positions and directions — alongside the general-purpose Array and Dictionary you'll use constantly for gameplay data.

What You Will Learn
  • What Vector2 and Vector3 represent, and common operations on them.
  • How to build, index, and modify Arrays.
  • How to build and use Dictionaries as key-value stores.

Vector2 and Vector3

Use case: Vector2 (for 2D projects) and Vector3 (for 3D) bundle x/y(/z) coordinates into one value, used everywhere positions, directions, sizes, and velocities show up in Godot.

var position := Vector2(100, 50)
var velocity := Vector2(0, -300)


print(position)   # (100, 50)
print(velocity.y) # -300
Output

Click Run to see what this code prints.

Common Vector Operations

Vectors support ordinary math operators directly, plus a set of built-in methods for common game math like distance and normalization.

var a := Vector2(3, 4)
var b := Vector2(1, 1)


print(a + b)                  # (4, 5)
print(a.length())             # 5.0  -- the vector's magnitude
print(a.distance_to(b))       # distance between the two points
print(a.normalized())         # a unit-length vector pointing the same direction
Output

Click Run to see what this code prints.

Why length() Matters

a.length() (also known as a vector's magnitude) is exactly how the CharacterBody2D example back in lesson 6's Introduction lesson could measure speed — Vector2/Vector3 methods like this appear constantly throughout real Godot gameplay code.

Arrays

GDScript Arrays are ordered, resizable lists, indexed starting at 0 (unlike Lua's tables, which start at 1) — the familiar zero-based indexing most languages use.

var inventory := ["Sword", "Shield", "Potion"]


print(inventory[0])       # Sword
inventory.append("Bow")
print(inventory.size())   # 4
inventory.remove_at(1)    # removes "Shield"
print(inventory)          # ["Sword", "Potion", "Bow"]
Output

Click Run to see what this code prints.

Dictionaries

A Dictionary stores key-value pairs, similar to a JavaScript object or a Python dict, useful for anything from a character's stat block to a save file's data.

var player_stats := {
    "health": 100,
    "mana": 50,
    "level": 1,
}


print(player_stats["health"])
player_stats["level"] = 2
print(player_stats)
Output

Click Run to see what this code prints.

Common Mistakes

Avoid These Mistakes
  • Confusing GDScript's 0-based Array indexing with Lua's 1-based table indexing if you've taken both courses on this platform.
  • Manually computing a vector's length with sqrt(x*x + y*y) instead of the built-in .length() method.
  • Accessing a Dictionary key that doesn't exist without checking has() first, which can raise an error depending on how it's accessed.

Best Practices

  • Use Vector2/Vector3's built-in methods (length(), normalized(), distance_to()) instead of hand-rolling the underlying math.
  • Use has("key") to check whether a Dictionary key exists before reading it, when you're not certain it's always present.
  • Type Arrays and Dictionaries where practical (Array[String], for example) to get editor autocomplete and stricter error-checking.

Frequently Asked Questions

Not by default — a plain Array can mix types freely, though you can optionally restrict it with typed array syntax like Array[int] for stricter checking.

Godot 4 introduced Vector4 for specific advanced use cases, though Vector2 and Vector3 cover the overwhelming majority of everyday 2D and 3D gameplay code.

A Dictionary is a flexible, general-purpose key-value structure defined entirely at runtime; a Resource gives you a fixed, typed, editor-friendly structure defined in code — reach for a Resource once a data shape stabilizes.

Key Takeaways

  • Vector2 and Vector3 bundle coordinates together and support both operators and built-in methods like length() and normalized().
  • Arrays are ordered, resizable, and zero-indexed.
  • Dictionaries store flexible key-value pairs, similar to a JS object or Python dict.
  • These types show up constantly in real Godot gameplay code, from movement to inventories to save data.

Summary

Vectors, Arrays, and Dictionaries are the data workhorses of nearly every Godot script. Next, you'll cover exported variables and the Inspector — how designers can tune your scripts without touching code.

Next Lesson →

Exporting Variables & the Inspector