---
name: event-bus
description: Use when setting up decoupled node communication — a global EventBus autoload with typed signals. Not for adding signals to an existing bus
title: event-bus
canonical_url: https://skilld.dev/gh/jame581/godotprompter/event-bus
last_updated: 2026-11-13T22:06:02.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/anti-patterns.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/event-bus/references/anti-patterns.md), [references/testing.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/event-bus/references/testing.md), [references/typed-signals.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/event-bus/references/typed-signals.md).
>
> If the user asked to install this Skill, run `npx skilld install jame581/godotprompter/event-bus`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/event-bus`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jame581/godotprompter/event-bus) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/event-bus`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/event-bus --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/event-bus --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Event Bus in Godot 4.3+

A global signal hub that lets unrelated nodes communicate without holding references to each other. All examples target Godot 4.3+ with no deprecated APIs.

> **Related skills:** **component-system** for direct signal communication between components, **csharp-signals** for C#-specific signal patterns, **dependency-injection** for alternative decoupling approaches, **ability-system** for an EventBus usage example with ability events.

---

## 1. What is an Event Bus

An EventBus is a singleton autoload that acts as a central registry for signals. Instead of nodes connecting directly to each other, every node connects to (or emits on) the shared EventBus. This removes the need for one node to hold a reference to another.

```
Without EventBus             With EventBus
──────────────               ──────────────────────────
NodeA ──signal──► NodeB      NodeA ──emit──► EventBus ──signal──► NodeB
                                                       ──signal──► NodeC
                                                       ──signal──► NodeD
```

**Flow diagram**

```
┌─────────┐   emit(player_died)   ┌───────────┐   player_died   ┌──────────┐
│  NodeA  │ ────────────────────► │ EventBus  │ ───────────────► │  NodeB   │
│(Player) │                       │(Autoload) │                  │   (UI)   │
└─────────┘                       └───────────┘ ───────────────► └──────────┘
                                                  player_died    ┌──────────┐
                                                                 │  NodeC   │
                                                                 │(AudioMgr)│
                                                                 └──────────┘
```

NodeA emits the signal. NodeB and NodeC each connected to EventBus independently. Neither knows the other exists.

---

## 2. When to Use vs Direct Signals

| Scenario | Recommended approach |
|--------------------------------------------|-------------------------------|
| Parent notifying its own child | Direct signal or method call |
| Child notifying its parent | Direct signal (bubble up) |
| Two nodes with the same parent | Direct signal via parent |
| Completely unrelated nodes in the tree | Event bus |
| UI reacting to gameplay state changes | Event bus |
| Audio manager reacting to game events | Event bus |
| Data manager / save system reacting | Event bus |
| Tight, performance-sensitive inner loop | Direct method call |

**Rule of thumb:** if you would otherwise need `get_node("../../SomeDistantNode")` or a hard-coded NodePath, the event bus is a better fit.

---

## 3. Basic EventBus

Create `res://autoloads/event_bus.gd` (or `EventBus.cs`), then register it in **Project → Project Settings → Globals → Autoload** with the name `EventBus`.

### GDScript (`autoloads/event_bus.gd`)

```gdscript
extends Node

## Emitted when the player character has died.
signal player_died

## Emitted whenever the score changes.
signal score_changed(new_score: int)

## Emitted when a level finishes successfully.
signal level_completed(level_id: int)

## Emitted when the player picks up a collectible.
signal item_collected(item_name: String)

## Emitted when the player's health changes.
signal health_changed(current: int, maximum: int)
```

### C# (`Autoloads/EventBus.cs`)

```csharp
using Godot;

/// <summary>
/// Global signal hub. Register as an autoload named "EventBus".
/// </summary>
public partial class EventBus : Node
{
    /// <summary>Emitted when the player character has died.</summary>
    [Signal] public delegate void PlayerDiedEventHandler();

    /// <summary>Emitted whenever the score changes.</summary>
    [Signal] public delegate void ScoreChangedEventHandler(int newScore);

    /// <summary>Emitted when a level finishes successfully.</summary>
    [Signal] public delegate void LevelCompletedEventHandler(int levelId);

    /// <summary>Emitted when the player picks up a collectible.</summary>
    [Signal] public delegate void ItemCollectedEventHandler(string itemName);

    /// <summary>Emitted when the player's health changes.</summary>
    [Signal] public delegate void HealthChangedEventHandler(int current, int maximum);
}
```

---

## 4. Connecting to Events

Consumers connect in `_ready()`. In C#, always disconnect in `_ExitTree()`: the bus outlives its consumers and its signals are custom, a case Godot does not disconnect when the consumer is freed, so the next emit would throw `ObjectDisposedException`.

### GDScript

```gdscript
extends CanvasLayer

# A connection to this node's method is removed automatically when the
# node is freed, but explicit disconnection is still good practice
# for long-lived nodes that reconnect frequently.

func _ready() -> void:
    EventBus.player_died.connect(_on_player_died)
    EventBus.score_changed.connect(_on_score_changed)
    EventBus.health_changed.connect(_on_health_changed)


func _exit_tree() -> void:
    EventBus.player_died.disconnect(_on_player_died)
    EventBus.score_changed.disconnect(_on_score_changed)
    EventBus.health_changed.disconnect(_on_health_changed)


func _on_player_died() -> void:
    $DeathScreen.show()


func _on_score_changed(new_score: int) -> void:
    $ScoreLabel.text = "Score: %d" % new_score


func _on_health_changed(current: int, maximum: int) -> void:
    $HealthBar.value = float(current) / float(maximum) * 100.0
```

### C#

```csharp
using Godot;

public partial class HudLayer : CanvasLayer
{
    private EventBus _eventBus;

    public override void _Ready()
    {
        _eventBus = GetNode<EventBus>("/root/EventBus");

        // Connect using strongly-typed delegate handlers
        _eventBus.PlayerDied      += OnPlayerDied;
        _eventBus.ScoreChanged    += OnScoreChanged;
        _eventBus.HealthChanged   += OnHealthChanged;
    }

    // IMPORTANT: Always disconnect in _ExitTree() in C#.
    // A += on a custom [Signal] is not cleaned up when this node is freed.
    // Failing to disconnect leaves the EventBus holding a delegate to the
    // freed node: a leak, and ObjectDisposedException on the next emit.
    public override void _ExitTree()
    {
        _eventBus.PlayerDied    -= OnPlayerDied;
        _eventBus.ScoreChanged  -= OnScoreChanged;
        _eventBus.HealthChanged -= OnHealthChanged;
    }

    private void OnPlayerDied()
    {
        GetNode<Control>("DeathScreen").Show();
    }

    private void OnScoreChanged(int newScore)
    {
        GetNode<Label>("ScoreLabel").Text = $"Score: {newScore}";
    }

    private void OnHealthChanged(int current, int maximum)
    {
        GetNode<ProgressBar>("HealthBar").Value = (double)current / maximum * 100.0;
    }
}
```

---

## 5. Emitting Events

Producers call `EventBus.<signal_name>.emit(...)` (GDScript) or `EmitSignal(SignalName.*)` (C#). The producer does not know which nodes are listening.

### GDScript

```gdscript
extends CharacterBody2D

@export var max_health: int = 100
var current_health: int = max_health
var score: int = 0


func take_damage(amount: int) -> void:
    current_health = clampi(current_health - amount, 0, max_health)
    EventBus.health_changed.emit(current_health, max_health)

    if current_health == 0:
        EventBus.player_died.emit()


func add_score(points: int) -> void:
    score += points
    EventBus.score_changed.emit(score)


func collect_item(item_name: String) -> void:
    EventBus.item_collected.emit(item_name)


func complete_level(level_id: int) -> void:
    EventBus.level_completed.emit(level_id)
```

### C#

```csharp
using Godot;

public partial class Player : CharacterBody2D
{
    [Export] public int MaxHealth { get; set; } = 100;

    private int _currentHealth;
    private int _score;
    private EventBus _eventBus;

    public override void _Ready()
    {
        _currentHealth = MaxHealth;
        _eventBus = GetNode<EventBus>("/root/EventBus");
    }

    public void TakeDamage(int amount)
    {
        _currentHealth = Mathf.Clamp(_currentHealth - amount, 0, MaxHealth);
        _eventBus.EmitSignal(EventBus.SignalName.HealthChanged, _currentHealth, MaxHealth);

        if (_currentHealth == 0)
            _eventBus.EmitSignal(EventBus.SignalName.PlayerDied);
    }

    public void AddScore(int points)
    {
        _score += points;
        _eventBus.EmitSignal(EventBus.SignalName.ScoreChanged, _score);
    }

    public void CollectItem(string itemName)
    {
        _eventBus.EmitSignal(EventBus.SignalName.ItemCollected, itemName);
    }

    public void CompleteLevel(int levelId)
    {
        _eventBus.EmitSignal(EventBus.SignalName.LevelCompleted, levelId);
    }
}
```

---

## 6. Typed Signal Parameters

Type every signal parameter. An untyped bus degrades into "what shape is this payload?" archaeology at every call site, and typos in parameter counts only surface at runtime. For anything richer than two or three primitives, pass a small `Resource` or a `class_name`'d data object rather than growing the parameter list.

Typed signal declarations, payload-object patterns, and the C# `[Signal]` delegate equivalents: [references/typed-signals.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/event-bus/references/typed-signals.md)

---

## 7. Anti-patterns

Four recurring failures: routing **everything** through the bus when a parent could just reach its own child (over-decoupling); handlers whose side effects emit further signals, so tracing one event means reading every handler; **circular chains**, where a listener re-emits the signal it just received and loops forever; and connecting without disconnecting in C#, which leaks the handler for the bus's lifetime.

Each anti-pattern with the failing code, why it hurts, and the fix, in GDScript and C#: [references/anti-patterns.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/event-bus/references/anti-patterns.md)

---

## 8. Testing

Use [GUT](https://github.com/bitwes/Gut) to verify both producer-side emission (`watch_signals(event_bus)` then `assert_signal_emitted_with_parameters(...)`) and consumer-side reactions (emit on the bus, then assert on the consumer's state). Always test against the real autoload EventBus retrieved via `get_tree().root.get_node("EventBus")`, not a fresh instance.

See [references/testing.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/event-bus/references/testing.md) for full producer-side and consumer-side test files plus a GUT-helper reference table.

---

## 9. Checklist

- [ ] `EventBus` autoload is registered in **Project → Project Settings → Globals → Autoload**
- [ ] All signals use typed parameters (`signal foo(bar: int)`) — no untyped signals
- [ ] Every consumer connects in `_ready()` and disconnects in `_exit_tree()` (mandatory in C#)
- [ ] Producers emit through `EventBus`, not by calling consumer methods directly
- [ ] No node holds a direct reference to another unrelated node just to emit or receive signals
- [ ] Complex payloads use a `Resource` subclass, not a raw `Dictionary`
- [ ] No handler re-emits the same signal it just received (prevents infinite loops)
- [ ] No event bus signal used where a direct parent-child call or signal is simpler
- [ ] GUT tests cover both emission (producer) and reception (consumer) for critical signals
- [ ] C# handlers verified to disconnect in `_ExitTree()` before merging
