Typed Signals in Godot 4 – Decouple Nodes Cleanly

Problem: Tight Coupling Between Nodes

In many Godot projects, a parent node needs to notify a child that a state change has happened – for example, a Player node signalling that it died. Without a clean communication channel, developers often resort to direct method calls or global singletons, both of which make the code harder to test and maintain.

Thesis: Typed Signals Bring Compile‑time Safety

Godot 4 introduces typed signals via the .gdsignal keyword. Unlike the dynamic add_user_signal() used in Godot 3.x, typed signals are declared in the script body, appear in the Inspector, and are validated at load time. This reduces silent failures and improves editor assistance.

Section 1 – From Dynamic to Typed Signals

• 3.x: add_user_signal("custom") – registers a string‑based signal at runtime; errors surface only when the signal is emitted.
• 4.0+: signal custom(arg1: int) – declares a signal with a known signature; the editor shows the argument list and the engine throws an error if a mismatch occurs.
• Inspector integration: typed signals appear as a separate tab, making it easy to connect them visually.
• Serialization: typed signals are stored in the scene file, so connections survive scene edits.

Section 2 – Practical Pattern: Declare, Emit, Connect

1. **Declare** the signal in the parent script:

# Player.gd
extends Node2D

signal died(score: int)

2. **Emit** it at the appropriate moment:

func _on_health_depleted():
    emit_signal("died", current_score)

3. **Connect** from a child or any other node. In the editor, use the Signals dock; in code, use connect() with the typed method name:

# HUD.gd
func _ready():
    var player = get_node("/root/Player")
    player.connect("died", self, "_on_player_died")

func _on_player_died(score: int) -> void:
    print("Player died with score: %d" % score)

Because the signal is typed, the compiler checks that _on_player_died accepts an int, and the editor will warn if you rename the signal without updating the connection.

Section 3 – Concrete Example: Health System

Imagine a simple health component that emits health_changed whenever the health value changes. The signal is typed to carry the new health value and a boolean indicating if the entity died.

# Health.gd
extends Node

signal health_changed(new_value: int, died: bool)

var health: int = 100

func take_damage(amount: int) -> void:
    health = max(health - amount, 0)
    emit_signal("health_changed", health, health == 0)

In a UI node that displays health, you connect once in _ready() and update the label when the signal fires.

Trade‑offs and Limitations

• Version Compatibility: Projects ported from 3.x to 4.0 must replace add_user_signal() calls with typed declarations. Failing to do so will break connections and hide errors until runtime.
• Threading: Signals must be emitted on the main thread after _ready(). Emitting during _physics_process() or from a background thread can cause race conditions or editor crashes.
• Editor Renaming: Renaming a signal in the Inspector does not automatically update your code. Use the “Rename Signal” option in the inspector to keep code in sync.
• Runtime Checks: In 4.0, emitting an undeclared signal raises an immediate error, which is good for catching bugs early but may require defensive programming in older projects.

Actionable Closing

To adopt typed signals in your Godot 4 project:

1. Declare all custom signals at the top of your scripts using signal.
2. Use the Signals dock or connect() in _ready() to wire handlers.
3. Run the project and verify that the Remote Debugger shows the signal emission line.
4. If upgrading from 3.x, replace add_user_signal() calls and re‑connect any existing connections.
5. Test in both editor and exported builds to ensure no race conditions occur.

Typed signals give you a safer, inspector‑friendly way to decouple nodes, making your codebase easier to read, test, and maintain.