Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 36 ยท Nodes and Signals

Godot Signals: Declare, Emit and Connect Events

Learn Godot 4 signals: built-in signals, connecting in the editor and in code, declaring custom signals with parameters, emit, disconnect, one-shot connections, await and the observer pattern.

Signals are Godot's way of saying "something happened" without knowing who cares. A button emits pressed; a timer emits timeout; your player might emit died. Other nodes connect to those signals and react. The sender and the listeners stay independent, so you can change one without breaking the other. This is the observer pattern, built in to the engine, and it is the key to clean Godot projects.

Godot code is read-only here. The Python stand-in implements a small signal system with connect, emit and disconnect so you can run and extend it.

Why signals?

Imagine a player that must update the health bar, play a sound, shake the camera and tell the game when it dies. Without signals the player's script needs paths to all four things, and moving any node breaks the player. With signals the player only does health_changed.emit(hp). The health bar, audio and camera each connect themselves.

flowchart LR
    P["Player emits health_changed"] --> H["HealthBar updates"]
    P --> S["Sound plays"]
    P --> C["Camera shakes"]

One emitter, many independent listeners.

Built-in signals

Almost every node type has signals: Button.pressed, Timer.timeout, Area2D.body_entered(body), AnimationPlayer.animation_finished(anim_name), Node.ready, Node.tree_exited, LineEdit.text_submitted(text). In the editor, open a node, click the Node tab (next to the Inspector) and you see them all, with their parameters.

Connecting in the editor

  1. Select the node that emits (for example a Button).
  2. Open Node > Signals, double-click pressed().
  3. Choose the receiver node and a method name; the editor generates the function in its script, such as _on_button_pressed().

The connection is saved in the scene file. It is quick for simple cases and visible to designers. The downside is that connections are hidden from the script, so for reusable or dynamically created nodes, connect in code.

Connecting in code

GDSCRIPT
extends Node

@onready var button: Button = $Button
@onready var timer: Timer = $Timer

func _ready() -> void:
    button.pressed.connect(_on_button_pressed)
    timer.timeout.connect(_on_timer_timeout)

func _on_button_pressed() -> void:
    print("clicked")

func _on_timer_timeout() -> void:
    print("tick")

In Godot 4 a signal is an object, so you write signal_name.connect(callable). You pass the method without parentheses: _on_button_pressed, not _on_button_pressed().

Signals with parameters pass them to the receiver:

GDSCRIPT
$Area2D.body_entered.connect(_on_body_entered)

func _on_body_entered(body: Node2D) -> void:
    if body is Player:
        queue_free()

Lambdas, bind and flags

GDSCRIPT
button.pressed.connect(func(): print("lambda"))
button.pressed.connect(_on_choice.bind("easy"))       # extra argument appended
timer.timeout.connect(_on_once, CONNECT_ONE_SHOT)     # disconnect after the first call

CONNECT_ONE_SHOT auto-disconnects after firing; CONNECT_DEFERRED calls the receiver at the end of the frame (safer when freeing nodes).

Custom signals

Declare a signal at the top of a script, with typed parameters, and emit it:

GDSCRIPT
# player.gd
class_name Player
extends CharacterBody2D

signal died
signal health_changed(new_health: int, max_health: int)

var max_health := 100
var health := 100:
    set(value):
        health = clampi(value, 0, max_health)
        health_changed.emit(health, max_health)
        if health == 0:
            died.emit()

A listener:

GDSCRIPT
# hud.gd
extends Control

@export var player: Player
@onready var bar: ProgressBar = $HealthBar

func _ready() -> void:
    player.health_changed.connect(_on_health_changed)
    player.died.connect(func(): $GameOver.show())

func _on_health_changed(new_health: int, max_health: int) -> void:
    bar.max_value = max_health
    bar.value = new_health

Notice who knows whom: the HUD knows the player (through an export), but the player knows nothing about the HUD. Name signals in the past tense (died, item_collected, door_opened) as they report events, and name receiver methods _on_<Source>_<signal>.

Disconnecting and checking

GDSCRIPT
player.died.disconnect(_on_player_died)
if player.died.is_connected(_on_player_died):
    pass
print(player.died.get_connections())

Connections to a freed node are removed automatically. Connecting the same method twice is an error, so guard with is_connected when a connect might run more than once.

await a signal

Because signals are events, you can wait for one inline:

GDSCRIPT
func show_intro() -> void:
    $Anim.play("fade_in")
    await $Anim.animation_finished     # code below waits here
    print("intro done")

func ask() -> void:
    var result = await dialog.choice_made    # value of the signal's first argument

This turns callback chains into straight-line code. If the emitter is freed before the signal fires, the function never resumes, so it will not leak but will not continue either.

Stand-in: a signal system in Python

This is not Godot. It implements the same observer idea: connect callables, emit with arguments, one-shot connections, disconnect.

Python Stand-in (Python): signals with connect and emit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The sound plays once (one-shot), the HUD runs for every change and GAME OVER appears when health reaches 0.

Common mistakes

  • Writing button.pressed.connect(_on_pressed()) with parentheses. That calls the function and connects its result.
  • Connecting a signal twice, which raises an error. Use is_connected.
  • Emitting a signal with the wrong number of arguments.
  • Using signals when a plain function call is simpler: "call down, signal up" is the rule (Node Communication and Groups).
  • Freeing a node inside its own signal handler without queue_free().
  • Old Godot 3 code: connect("pressed", self, "_on_pressed") no longer works.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which line correctly connects a button's pressed signal in Godot 4?

    In Godot 4, use signal.connect(callable) and pass the method without parentheses.
  2. 2. How do you declare a custom signal with a parameter?

    signal name(param: Type) declares it; trigger it with name.emit(value).
  3. 3. What does CONNECT_ONE_SHOT do?

    A one-shot connection removes itself after it has been called once.
  4. 4. What does await some_node.some_signal do?

    await suspends only the calling function; the game keeps running.

Summary

  • Signals decouple "something happened" from "who reacts". Emitters do not know the listeners.
  • Connect in the editor (Node > Signals) or in code with signal.connect(callable).
  • Declare with signal name(params), trigger with name.emit(...), name them in the past tense.
  • Use bind, lambdas and CONNECT_ONE_SHOT for flexibility; await to wait for one inline.
  • Check with is_connected and remove with disconnect.

Next: Input and the Input Map