Godot Signal Architecture

NEVER Do in Signal Architecture

• NEVER use the legacy string-based Object.connect() — Typos result in silent failures. Always use signal.connect(_callback) for compile-time validation.
• NEVER use signals to dictate behavior top-down — Signals are past-tense events (e.g., "died"). Use direct method calls for commands (e.g., "kill").
• NEVER connect a signal twice to the same Callable — This throws an ERR_INVALID_PARAMETER at runtime unless using the Object.CONNECT_REFERENCE_COUNTED flag to stack connections.
• NEVER use a Global Signal Bus for local data — Pollutes global state and makes debugging harder. Use local connections for scene-specific logic.
• NEVER assume callbacks must accept all signal arguments — Use unbind() to drop unwanted parameters and keep your API clean.
• NEVER create circular signal dependencies — A signals B, B signals back to A? Use a mediator (parent or AutoLoad) to break the loop.
• NEVER skip signal typing — signal moved without types lacks editor support. Always use signal moved(dir: Vector2).
• NEVER forget to disconnect dynamic signals — Ghost connections cause "call on null instance" errors. Disconnect in _exit_tree() or when retargeting (disconnect_ghost_signals.gd).
• NEVER emit signals with immediate side effects on the emitter — If died.emit() calls queue_free(), listeners might fail to respond. Emit first.
• NEVER use signals for high-frequency data streams — Sending 1000+ signals/second (like per-particle updates) is inefficient. Use shared arrays or direct buffers.

Signal Up / Call Down

• Children → parents: past-tense signals (health_changed, died).
• Parents → children: direct calls / properties (apply_damage, play_anim).
• Siblings: parent mediator or carefully scoped Autoload bus — never sibling hard refs.

Use signals for: UI presses, death → game over, loot → inventory, cross-scene bus events. Use direct calls for: parent commanding child, local property access.

Decision Tree: Where to Connect

Available Scripts

• signal_up_call_down_pattern.gd — MANDATORY before hierarchy wiring.
• global_signal_bus_router.gd / global_event_bus.gd — MANDATORY before Autoload buses.
• disconnect_ghost_signals.gd — MANDATORY when switching tracked emitters.
• await_signal_sequencing.gd / complex_signal_sequencer.gd — MANDATORY for multi-step awaits.
• safe_dynamic_connections.gd — is_connected guards.
• one_shot_deferred_connections.gd — one-shot / deferred flags.
• callable_bind_context.gd / unbind_unwanted_args.gd — bind/unbind.
• track_signal_emitter_source.gd — CONNECT_APPEND_SOURCE_OBJECT.
• signal_debugger.gd / signal_spy.gd — debug / test spies.

Lambda Capture Cleanup (complete)

Godot auto-disconnects most connections when a node frees. Exception: lambdas that capture locals — you must disconnect manually.

var my_lambda: Callable

func _ready() -> void:
    var x := 10
    my_lambda = func(): print(x)
    player.died.connect(my_lambda)

func _exit_tree() -> void:
    if player and player.died.is_connected(my_lambda):
        player.died.disconnect(my_lambda)

Prefer named methods or disconnect_ghost_signals.gd when retargeting.

CONNECT_REFERENCE_COUNTED — Correct Semantics

CONNECT_REFERENCE_COUNTED means multiple identical connects share one connection with a refcount (connect N times / disconnect N times). It is not "auto-cleanup when the emitter frees" and does not fix capturing-lambda leaks.

• Auto-cleanup on free: normal connections to Object methods (non-capturing) are cleared when either side is freed.
• Capturing lambdas: always manual disconnect (see above).
• One-shot auto-remove after fire: CONNECT_ONE_SHOT.

Deep recipes (on demand)

LLM-ignorance rule: if a general agent would not know it before reading, it lives here or in scripts/ — never delete, only move.

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.