godot-signal-architecture

name	godot-signal-architecture
description	Expert blueprint for signal-driven architecture using "Signal Up, Call Down" pattern for loose coupling. Covers typed signals, signal chains, one-shot connections, and AutoLoad event buses. Use when implementing event systems OR decoupling nodes. Keywords signal, emit, connect, CONNECT_ONE_SHOT, CONNECT_REFERENCE_COUNTED, event bus, AutoLoad, decoupling.

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).