Godot Math Functions: clamp, lerp, wrap, snapped and More

GDScript ships the math functions games need as global functions. These are the ones you reach for most:

extends Node

func _ready():
	print(clampi(150, 0, 100))        # keep inside a range
	print(lerpf(0.0, 10.0, 0.25))     # a quarter of the way
	print(wrapi(7, 0, 5))             # wrap around: 7 becomes 2
	print(move_toward(5.0, 10.0, 2.0))  # step toward, never past
	print(snappedf(3.14159, 0.01))    # round to a step

100
2.5
2
7.0
3.14

Most have three forms: a general one (clamp), one for ints (clampi) and one for floats (clampf). The typed ones let the editor check your code, so prefer them when you know the type.

clamp: Keep a Value in a Range

extends Node

var hp := 100

func heal(amount: int) -> void:
	hp = clampi(hp + amount, 0, 100)

func _ready():
	heal(30)
	print(hp)
	heal(-250)
	print(hp)
	print(Vector2(150, -20).clamp(Vector2.ZERO, Vector2(100, 100)))

100
0
(100.0, 0.0)

Clamping in one place, such as a setter, keeps health, ammo and volume from ever leaving their range.

lerp, inverse_lerp and remap

lerp(a, b, t) goes from a (at t = 0) to b (at t = 1). inverse_lerp() does the opposite and remap() converts a value from one range to another:

extends Node

func _ready():
	print(lerpf(100.0, 200.0, 0.5))
	print(inverse_lerp(0.0, 200.0, 50.0))      # how far 50 is from 0 to 200
	print(remap(5.0, 0.0, 10.0, 0.0, 100.0))   # 5 out of 10 becomes 50 out of 100

150.0
0.25
50.0

remap() turns a distance into a volume, a speed into an animation rate, or health into a bar width.

Smooth Movement with lerp

Calling lerp() every frame toward a target gives a smooth slow-down, often used for cameras:

func _process(delta):
	# moves 10% of the remaining way per frame at 60 fps, slowing down near the target
	position = position.lerp(target.position, 1.0 - exp(-6.0 * delta))

The 1.0 - exp(-speed * delta) weight makes the smoothing the same at any frame rate. A fixed weight like 0.1 would move faster on a 144 Hz screen than on a 60 Hz one.

move_toward: Constant Speed

move_toward(from, to, delta) changes a value by at most delta and stops exactly at the target:

extends Node

func _ready():
	var speed := 0.0
	for frame in 4:
		speed = move_toward(speed, 10.0, 3.0)
		print(speed)

3.0
6.0
9.0
10.0

This is the standard way to accelerate a character to a top speed: velocity.x = move_toward(velocity.x, max_speed, acceleration * delta).

wrap: Loop Around a Range

extends Node

func _ready():
	var options := ["Play", "Options", "Quit"]
	var cursor := 0
	cursor = wrapi(cursor - 1, 0, options.size())   # up from the first item
	print(options[cursor])
	cursor = wrapi(cursor + 1, 0, options.size())   # down from the last item
	print(options[cursor])
	print(wrapf(370.0, 0.0, 360.0))                 # an angle in degrees
	print(-1 % 5, " ", posmod(-1, 5))

Quit
Play
10.0
-1 4

The max of wrapi() is not included. For negative numbers, % keeps the sign (-1 % 5 is -1), while posmod() always returns a value from 0 up.

Rounding

extends Node

func _ready():
	print(round(2.5), " ", round(-2.5))
	print(floor(2.7), " ", ceil(2.1))
	print(int(-2.7), " ", floori(-2.7))
	print(snapped(17, 5), " ", snappedf(0.66666, 0.1))

3.0 -3.0
2.0 3.0
-2 -3
15 0.7

• round(), floor() and ceil() return floats. roundi(), floori() and ceili() return ints.
• int() drops the decimals, which rounds toward zero: int(-2.7) is -2, but floori(-2.7) is -3.
• snapped() rounds to the nearest multiple, which suits grid snapping.

Angles Are in Radians

Godot's trigonometry and rotation use radians. Convert with deg_to_rad() and rad_to_deg():

extends Node

func _ready():
	print(deg_to_rad(180.0))
	print(rad_to_deg(PI / 2))
	print(sin(PI / 2), " ", cos(0.0))
	print("%.1f" % rad_to_deg(angle_difference(deg_to_rad(350.0), deg_to_rad(10.0))))

3.14159265358979
90.0
1.0 1.0
20.0

angle_difference() gives the shortest turn between two angles, so turning from 350 to 10 degrees is 20 degrees, not 340. Nodes also have rotation_degrees when you prefer degrees.

More Helpers