GDScript Functions: func, Parameters, Defaults, return

A function is a named block of code you can run again and again. Define it with func and call it by name:

extends Node

func greet(player_name):
	print("Welcome, ", player_name)

func _ready():
	greet("Ana")
	greet("Bo")

Welcome, Ana
Welcome, Bo

A script's functions are its methods: they belong to the node, and they can read every member variable of the script. The order does not matter, so greet may be defined after _ready.

Parameters, Types and return

Add types to the parameters and the return value with ->. return sends a value back and ends the function:

extends Node

func damage(base: int, multiplier: float) -> int:
	return int(base * multiplier)

func is_critical(roll: int) -> bool:
	return roll >= 18

func _ready():
	print(damage(12, 1.5))
	print(is_critical(19))
	var total := damage(10, 2.0) + damage(4, 0.5)
	print(total)

18
true
22

A function without return, or declared -> void, returns null. See static typing for what typed functions catch.

Default Values

A parameter with = value is optional:

extends Node

func spawn(enemy: String, count: int = 1, boss: bool = false) -> String:
	var text := "%d x %s" % [count, enemy]
	if boss:
		text += " (boss)"
	return text

func _ready():
	print(spawn("slime"))
	print(spawn("bat", 5))
	print(spawn("dragon", 1, true))

1 x slime
5 x bat
1 x dragon (boss)

Arguments are matched by position, and GDScript has no named arguments. To set boss you must also pass count. When a function grows many options, take a dictionary of settings instead.

Returning Several Values

Return an array or a dictionary:

extends Node

func min_max(values: Array) -> Array:
	return [values.min(), values.max()]

func stats_of(values: Array) -> Dictionary:
	var total := 0
	for v in values:
		total += v
	return {"total": total, "average": float(total) / values.size()}

func _ready():
	var range_of := min_max([4, 9, 1, 7])
	print("low ", range_of[0], ", high ", range_of[1])
	var stats := stats_of([4, 9, 1, 7])
	print(stats.total, " ", stats.average)

low 1, high 9
21 5.25

Recursion

A function may call itself. Give it a case that stops:

extends Node

func factorial(n: int) -> int:
	if n <= 1:
		return 1
	return n * factorial(n - 1)

func _ready():
	print(factorial(5))

120

Calls can only nest so deep: by default GDScript fails at about 1,000 nested calls. Walk large trees with a loop and an array instead of recursion.

Variadic Functions

Since Godot 4.5, a last parameter written ...name collects any number of extra arguments into an array:

extends Node

func total(...numbers: Array) -> int:
	var sum := 0
	for n in numbers:
		sum += n
	return sum

func _ready():
	print(total(1, 2, 3))
	print(total())

6
0

Functions Are Values

A function's name without parentheses is a Callable, a value you can store, pass and call later. This is how signals and sort_custom() take functions:

extends Node

func shout(text: String) -> String:
	return text.to_upper() + "!"

func apply(f: Callable, value: String) -> String:
	return f.call(value)

func _ready():
	var action := shout
	print(action.call("run"))
	print(apply(shout, "jump"))

RUN!
JUMP!

The lambdas and Callables page goes further: inline functions, bind() and captured variables.

Functions Godot Calls for You

Functions that start with _ and match an engine name are virtual: you define them, Godot calls them.

Your own private helpers often start with _ too, by convention. That is only a naming habit: GDScript has no private keyword.