Godot Signals in GDScript: signal, connect() and emit()

A signal is a message a node sends when something happens: a button was pressed, the player died, a coin was collected. Other code connects to the signal and runs when it fires. The sender does not need to know who is listening:

extends Node

signal health_changed(old_value: int, new_value: int)
signal died

var health := 10

func take_damage(amount: int) -> void:
	var old := health
	health = max(health - amount, 0)
	health_changed.emit(old, health)
	if health == 0:
		died.emit()

func _on_health_changed(old_value: int, new_value: int) -> void:
	print("Health: ", old_value, " -> ", new_value)

func _on_died() -> void:
	print("Game over")

func _ready():
	health_changed.connect(_on_health_changed)
	died.connect(_on_died)
	take_damage(4)
	take_damage(9)

Health: 10 -> 6
Health: 6 -> 0
Game over

Three steps:

1. Declare the signal with signal, listing its arguments.
2. Connect a function to it with signal_name.connect(function).
3. Emit it with signal_name.emit(arguments). Every connected function runs, in the order they were connected.

Why Signals Matter

Signals keep nodes independent. A Player emits died, and the HUD, the music and the level each connect to it. None of them needs a reference to the others, and the Player scene works on its own. The Godot rule of thumb is "call down, signal up": a parent calls methods on its children, and a child sends signals to whoever is above it.

Built-in Signals

Every node type comes with signals. A few you will use early:

Connect them in code the same way:

func _ready():
	$StartButton.pressed.connect(_on_start_pressed)
	$Hitbox.body_entered.connect(_on_hitbox_body_entered)

func _on_hitbox_body_entered(body: Node2D) -> void:
	if body.is_in_group("player"):
		body.take_damage(1)

Or connect them in the editor: select the node, open the Node dock, double click the signal and pick the script. Godot writes an empty handler such as _on_start_button_pressed() for you.

Connecting a Lambda

For a short reaction, connect a lambda instead of writing a method:

extends Node

signal coin_collected(value: int)

func _ready():
	var total := [0]
	coin_collected.connect(func(value): total[0] += value)
	coin_collected.connect(func(value): print("+", value, " coins"))
	coin_collected.emit(5)
	coin_collected.emit(1)
	print("Total: ", total[0])

+5 coins
+1 coins
Total: 6

One-Shot Connections, Disconnecting and Checks

extends Node

signal level_started

func _on_level_started() -> void:
	print("level started")

func _ready():
	level_started.connect(func(): print("first time only"), CONNECT_ONE_SHOT)
	level_started.connect(_on_level_started)
	level_started.emit()
	level_started.emit()

	print(level_started.is_connected(_on_level_started))
	level_started.disconnect(_on_level_started)
	level_started.emit()          # nothing is connected now
	print(level_started.get_connections().size())

first time only
level started
level started
true
0

CONNECT_ONE_SHOT disconnects after the first emit. Connecting the same function twice is an error, so connect once, usually in _ready():

ERROR: Signal 'level_started' is already connected to given callable 'Node(main.gd)::_on_level_started' in that object.

Passing Extra Data with bind()

A signal's arguments are fixed by the emitter. To add your own, bind() them to the handler. This tells several buttons apart with one function:

func _ready():
	$Shop/BuySword.pressed.connect(_on_buy_pressed.bind("sword"))
	$Shop/BuyShield.pressed.connect(_on_buy_pressed.bind("shield"))

func _on_buy_pressed(item: String) -> void:
	print("Buying ", item)

Waiting for a Signal

await pauses a function until a signal fires, which reads like a script of events:

func open_chest() -> void:
	$AnimationPlayer.play("open")
	await $AnimationPlayer.animation_finished
	spawn_loot()

See await for coroutines and timers.

Godot 3 vs Godot 4