O que é um sinal?

As coisas acontecem com os objetos enquanto um jogo está em execução: uma moeda é coletada, uma porta se abre, o hp do herói cai para 0. Outras partes do programa reagem a esses eventos: a pontuação aumenta, um som toca, a tela de fim de jogo aparece.

Um sinal é uma mensagem que um objeto envia quando algo acontece com ele. O objeto emite o sinal, e todas as funções conectadas a esse sinal são executadas:

# coin.gd
class_name Coin
extends RefCounted

signal collected

func collect() -> void:
	print("Coin picked up")
	collected.emit()

signal collected declara o sinal e collected.emit() o envia. A moeda não sabe quem está ouvindo. O código que se importa com as moedas conecta uma de suas próprias funções ao sinal:

# main.gd
func _ready():
	var coin := Coin.new()
	coin.collected.connect(_on_coin_collected)
	coin.collect()
	print("Done")

func _on_coin_collected() -> void:
	print("Score +1")

A saída é Coin picked up, Score +1, Done. A emissão executa as funções conectadas imediatamente, antes da linha após emit(). Um sinal sem funções conectadas não faz nada quando é emitido.

Sem um sinal, collect() teria que chamar o código da pontuação por conta própria, então cada moeda precisaria de uma referência ao placar. Com um sinal, a moeda apenas anuncia o evento, e qualquer número de ouvintes, ou nenhum, pode reagir a ele.

Os próprios nós do Godot funcionam da mesma forma: um Button emite pressed quando é clicado, e um Timer emite timeout quando o tempo se esgota.