gamedev-skills/awesome-gamedev-agent-skills / skills/godot/godot-signals-groups
godot-signals-groups
VerifiedGodot 4.7 signals and node groups: typed signals, connect() with Callables, one-shot and deferred connections, event-bus autoloads and call_group broadcasts. Use when nodes must talk without hard references, a handler fires twice or never, or the log says "already connected". Not for GDScript syntax (`godot-gdscript`) or autoload setup (`godot-nodes-scenes`).
Godot Signals & Groups (4.x)
Decouple nodes with signals and act on many nodes at once with groups, instead of hard-coding references between scenes. Targets Godot 4.7 (see Version notes).
When to use
- A node must announce "something happened" (player died, item picked up, wave cleared) without holding references to its listeners.
- A whole category of nodes needs one call ("pause all enemies", "save every checkpoint").
When not to use: general GDScript syntax → godot-gdscript; scene structure and
autoload registration → godot-nodes-scenes.
Core workflow
-
Decide the direction. A child or sub-scene emits upward; the parent connects. The child stays reusable and ignorant of who listens. Calling down into a child you own is a plain method call, not a signal.
-
Declare typed signals on the emitter and
emit()exactly the declared arguments. -
Connect with a Callable (
sig.connect(_on_sig)). UseCONNECT_ONE_SHOTfor fire-once andbind()to pass extra context. -
Editor connections and groups are plain text in the
.tscn, so you can read and write them without the Node dock:[node name="Goblin" type="CharacterBody2D" parent="Enemies" groups=["enemies"]] [connection signal="pressed" from="UI/StartButton" to="." method="_on_start_pressed"]from/toare paths relative to the scene root, and themethodmust exist on thetonode's script. -
Use groups for broadcast:
add_to_group(), thenget_tree().call_group(...)or iterateget_nodes_in_group(...). -
For cross-scene events, put signals on an autoload (event bus, see the reference).
-
Check before you finish.
-
If you edited
.tscnconnections, run thegodot-nodes-scenesskill'sscripts/check_godot_project.py <project-dir>; it reports[connection]entries whosefrom/tonode does not exist. It does not check method names. -
Prove the wiring at runtime with a headless test (Pattern 4), or smoke-run the scene and grep the log:
godot --headless --path . --fixed-fps 60 --quit-after 300 --scene res://level.tscn > run.log 2>&1 grep -nE "^ *(SCRIPT ERROR|ERROR):" run.log # signal errors print as ERROR: linesWith no Godot binary (
godot,godot4or$GODOT_BIN), ask the user to run it and pasterun.log.
-
Patterns
1. Emit upward, connect from the parent
# coin.gd (reusable pickup; knows nothing about the player or HUD)
extends Area2D
signal collected(value: int)
func _ready() -> void:
body_entered.connect(_on_body_entered)
func _on_body_entered(body: Node2D) -> void:
if body.is_in_group("player"):
collected.emit(10)
queue_free()
# level.gd (the parent wires coins to game state)
func _ready() -> void:
for coin in get_tree().get_nodes_in_group("coins"):
coin.collected.connect(_on_coin_collected)
func _on_coin_collected(value: int) -> void:
GameState.add_score(value)
2. One-shot and bound arguments
func _ready() -> void:
$Door.opened.connect(_on_door_opened, CONNECT_ONE_SHOT) # auto-disconnects
# bind() appends its arguments after the signal's own arguments.
$RedButton.pressed.connect(_on_button.bind("red"))
func _on_button(color: String) -> void:
print("Pressed the %s button" % color)
3. Groups: broadcast to many nodes
func pause_all_enemies() -> void:
get_tree().call_group("enemies", "set_paused", true) # skips nodes without the method
4. Headless test that a signal reaches its handler once
# res://tests/test_signals.gd
extends SceneTree
func _initialize() -> void:
var level: Node = load("res://level.tscn").instantiate()
root.add_child(level) # parent _ready() connects the coins
await process_frame
var coin: Node = get_first_node_in_group("coins")
var failed := 0
if coin == null or coin.collected.get_connections().size() != 1:
failed += 1
push_error("coin.collected should have exactly one connection")
print("Results: %d failed" % failed)
quit(1 if failed > 0 else 0)
Run it with godot --headless --path . --script res://tests/test_signals.gd and read the
exit code. To check the handler's effect, emit the signal in the test and assert on the
state it should change.
Gotchas
- 3.x connect signature is gone.
connect("died", self, "_on_died")→died.connect(_on_died).Object.connect("died", Callable(self, "_on_died"))still works; the method-name string form does not. Preferdied.emit()overemit_signal("died"): a misspelled signal name is then a parse error, not a runtime one. - Connecting the same method twice prints "Signal '...' is already connected to given
callable" and keeps one connection. A new lambda each time is a different Callable, so
it stacks silently and the handler fires once per connect. Keep the lambda in a variable,
or guard with
if not sig.is_connected(cb):. - A lambda outlives the nodes it captures. Godot removes a connection when the emitter or the Callable's owner is freed, but a lambda belongs to the script that created it; one that captures a node freed later keeps firing and errors. Connect listener methods, or disconnect stored lambdas yourself.
- Argument mismatch fails at emit time.
emit()does not validate arguments against thesignaldeclaration; a handler with a different count logs "Error calling from signal ... Method expected N argument(s)". Declare typed params and emit exactly those. - Groups are global to the SceneTree, not per scene. Two levels using the same group name share membership; namespace names if that matters.
call_groupsilently ignores nodes lacking the method, so a typo fails quietly. Prefer a typed signal when the contract matters.[connection]to a method that doesn't exist is not caught by the checker; Godot prints a "Cannot connect" error when the scene is instantiated, so the smoke run catches it.- Handlers that change the tree during physics ("flushing queries" errors) → connect
with
CONNECT_DEFERREDorcall_deferredthe change.
References
- Read
references/signal-patterns.mdwhen you need every connection flag,unbind(), awaiting a signal with a timeout, safe disconnection and lambda lifetime, the full groups API, an autoload event bus, or a signals-vs-direct-calls decision.
Related skills
godot-gdscriptfor signal andawaitsyntax.godot-nodes-scenesfor autoloads used as global event buses, and the checker.godot-gdscript-headless-testingto keep Pattern 4 in CI.game-aifor state machines that drive and consume these events.
Version notes
Last verified: 2026-11-11 against Godot 4.7.2-stable (released 2026-08-18).
- Variadic rest parameters (
..._args), used by the reference's timeout helper, exist since GDScript 4.5. - The "already connected" and "Method expected N argument(s)" messages match 4.7.2's
object.cppandvariant.cpp.
Sources: object.cpp @ 4.7.2-stable, variant.cpp @ 4.7.2-stable, Signal @ 4.7.2-stable, Using signals.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |