Godot Vector2: Positions, Directions and Vector Math

A Vector2 holds two numbers, x and y. Godot uses it for every position, direction and velocity in 2D:

extends Node

func _ready():
	var position := Vector2(100, 50)
	print(position)
	print(position.x, " ", position.y)
	position.x += 20
	position += Vector2(0, 10)
	print(position)

(100.0, 50.0)
100.0 50.0
(120.0, 60.0)

The values are floats, even when you write whole numbers. In Godot's 2D space, x grows to the right and y grows down the screen.

Built-in Directions

extends Node

func _ready():
	print(Vector2.ZERO, " ", Vector2.ONE)
	print(Vector2.UP, " ", Vector2.DOWN)
	print(Vector2.LEFT, " ", Vector2.RIGHT)

(0.0, 0.0) (1.0, 1.0)
(0.0, -1.0) (0.0, 1.0)
(-1.0, 0.0) (1.0, 0.0)

Because y points down, Vector2.UP is (0, -1). A jump therefore sets velocity.y to a negative number.

Vector Math

Adding vectors moves a point. Multiplying by a number scales a vector:

extends Node

func _ready():
	var a := Vector2(3, 4)
	var b := Vector2(1, 2)
	print(a + b)
	print(a - b)
	print(a * 2)
	print(a / 2)
	print(a * b)   # component by component

(4.0, 6.0)
(2.0, 2.0)
(6.0, 8.0)
(1.5, 2.0)
(3.0, 8.0)

a - b is the vector that goes from b to a. That one fact powers most game math: aiming, chasing and measuring distance.

Length, Distance and Direction

extends Node

func _ready():
	var player := Vector2(0, 0)
	var enemy := Vector2(30, 40)
	print((enemy - player).length())
	print(player.distance_to(enemy))
	print(player.direction_to(enemy))
	print((enemy - player).normalized())

50.0
50.0
(0.6, 0.8)
(0.6, 0.8)

• length() is the size of a vector. distance_to() is the length of the vector between two points.
• normalized() keeps the direction and sets the length to 1. direction_to() is (target - self).normalized() in one call.

Multiply a direction of length 1 by a speed to get a velocity. This is how an enemy chases the player:

extends CharacterBody2D

@export var speed := 120.0
@onready var player: Node2D = %Player

func _physics_process(_delta):
	velocity = global_position.direction_to(player.global_position) * speed
	move_and_slide()

Normalizing Input

Holding right and down at once gives the input vector (1, 1), whose length is about 1.41. Without normalizing, diagonal movement is 41% faster:

extends Node

func _ready():
	var input := Vector2(1, 1)
	print("%.2f" % input.length())
	print("%.2f" % input.normalized().length())

1.41
1.00

Input.get_vector("left", "right", "up", "down") reads four input actions and already returns a vector no longer than 1, so it is the usual way to read movement keys.

Angles and Rotation

Angles in Godot are in radians. angle() gives a vector's angle from the positive x axis, and rotated() turns a vector:

extends Node

func _ready():
	var aim := Vector2(1, 1)
	print("%.1f degrees" % rad_to_deg(aim.angle()))
	print(Vector2.RIGHT.rotated(deg_to_rad(90)).round())
	print(Vector2.from_angle(PI).round())

45.0 degrees
(0.0, 1.0)
(-1.0, 0.0)

Turning RIGHT by 90 degrees points it down here, again because y grows downward. To point a node at a target, use look_at(target_position), or set rotation = direction.angle().

Moving Toward a Target

extends Node

func _ready():
	var here := Vector2(0, 0)
	var target := Vector2(10, 0)
	print(here.move_toward(target, 3))    # at most 3 units closer
	print(here.lerp(target, 0.5))         # halfway
	print(Vector2(30, 40).limit_length(5))

(3.0, 0.0)
(5.0, 0.0)
(3.0, 4.0)

• move_toward(to, delta) moves a fixed amount and never overshoots. Use speed * delta as the amount for frame-rate independent movement.
• lerp(to, weight) goes a fraction of the way.
• limit_length(max) caps a velocity at a top speed.

Comparing Vectors

Vector2 stores 32-bit floats, so math results are rarely exact. Compare with is_equal_approx():

extends Node

func _ready():
	var turned := Vector2.RIGHT.rotated(PI / 2)
	print(turned)
	print(turned == Vector2.DOWN)
	print(turned.is_equal_approx(Vector2.DOWN))

(-0.0, 1.0)
false
true

Vector2i for Grids

Vector2i holds integers. Tile maps and grid games use it for cell coordinates:

extends Node

func _ready():
	var cell := Vector2i(3, 4)
	print(cell + Vector2i.RIGHT)
	print(Vector2i(Vector2(3.7, 4.2)))
	print(Vector2(cell) * 32)    # cell to pixels with 32 px tiles

(4, 4)
(3, 4)
(96.0, 128.0)

For 3D the same methods exist on Vector3, with a z component.