【Godot 4】GlobalEventBus (イベントバス) コンポーネントの作り方

Godot のシグナルはとても強力ですが、そのまま使うとだんだん「線だらけのスパゲッティ配線」になりがちですよね。
たとえば、

UI から Player に「ボタン押されたよ！」を直接シグナル接続する
Player から GameManager に「ダメージ受けた！」を直接シグナル接続する
敵やアイテムも同様に、あちこちと直接接続する

…とやっていくと、シーンツリーのどこかが変わるたびに接続先を修正したり、get_node("../..") のような壊れやすいパス参照が増えていきます。
さらに、UI と Player のような「本来はお互いを知らなくていい」ノード同士が、がっつり依存し合ってしまうのも気持ちよくないですね。

そこで今回は、「継承より合成」の思想に沿って、どのノードからでも同じ窓口でイベントをやり取りできるコンポーネント、
GlobalEventBus を用意して、シングルトン経由でイベントを中継してしまいましょう。

目次 [ close ]

【Godot 4】依存関係スッキリ！シグナルを一元管理する「GlobalEventBus」コンポーネント

【Godot 4】依存関係スッキリ！シグナルを一元管理する「GlobalEventBus」コンポーネント

このコンポーネントの役割はシンプルです。

ゲーム全体で共有される「イベントバス」としてシングルトン化
UI, Player, 敵, GameManager など、お互いを知らないノード同士のシグナルを中継
「イベント名＋汎用パラメータ」で、ゆるく結合したイベント駆動構成を実現

Godot の AutoLoad（シングルトン） に登録しておくことで、どこからでも GlobalEventBus にアクセスできるようにします。

フルコード：GlobalEventBus.gd


extends Node
class_name GlobalEventBus
## ゲーム全体で使うイベントバス。
## AutoLoad(シングルトン)として登録して使います。
##
## 役割:
## - 「イベント名」と「任意のデータ」を投げる
## - そのイベント名にサブスクライブしているノードへシグナルを中継する
##
## 利点:
## - UI / Player / 敵 / GameManager などが直接お互いを参照しなくてよい
## - シーン構成を変えても、イベントの接続をほぼ触らなくてよい
## - コンポーネント指向で「イベント購読ロジック」を分離しやすい

# ---------------------------------------------------------
# シグナル定義
# ---------------------------------------------------------

## 任意のイベント名とデータを流すための汎用シグナル。
## listener 側は event_name を見て処理を分岐します。
signal event_emitted(event_name: StringName, payload: Variant)

## デバッグ用: イベントの送受信をログに出すかどうか。
@export var enable_debug_log: bool = false

## デバッグ用: ログをフィルタするイベント名。
## 空配列なら全イベントをログ出力します。
@export var debug_log_filter: Array[StringName] = []


# ---------------------------------------------------------
# 内部状態
# ---------------------------------------------------------

## イベント名ごとに、接続されているコールバックの配列を保持します。
## {
##   "player_damaged": [Callable, Callable, ...],
##   "coin_collected": [Callable, ...],
## }
var _listeners: Dictionary = {}


# ---------------------------------------------------------
# 公開 API
# ---------------------------------------------------------

## イベントの購読（サブスクライブ）
## @param event_name  受け取りたいイベント名（"player_damaged" など）
## @param listener    呼び出されるコールバック（func(payload): ...）
func subscribe(event_name: StringName, listener: Callable) -> void:
	if not _listeners.has(event_name):
		_listeners[event_name] = []
	var arr: Array = _listeners[event_name]

	# 二重登録を防止
	if arr.has(listener):
		if enable_debug_log:
			_debug_print("listener already subscribed for '%s'" % event_name)
		return

	arr.append(listener)

	if enable_debug_log:
		_debug_print("subscribe '%s' (%d listeners)" % [event_name, arr.size()])


## イベント購読の解除（アンsubscribe）
func unsubscribe(event_name: StringName, listener: Callable) -> void:
	if not _listeners.has(event_name):
		return
	var arr: Array = _listeners[event_name]
	if not arr.has(listener):
		return

	arr.erase(listener)

	if enable_debug_log:
		_debug_print("unsubscribe '%s' (%d listeners)" % [event_name, arr.size()])

	# 空になったらキーごと消してもよい
	if arr.is_empty():
		_listeners.erase(event_name)


## イベントを発行（publish / emit）
## @param event_name  発行するイベント名
## @param payload     任意のデータ（Dictionary, int, String, なんでもOK）
func emit_event(event_name: StringName, payload: Variant = null) -> void:
	# まず GlobalEventBus 自身のシグナルを発火 (UIデバッグ用など)
	emit_signal("event_emitted", event_name, payload)

	if enable_debug_log:
		_debug_print_event(event_name, payload)

	if not _listeners.has(event_name):
		return

	# コピーを取ってからループしないと、コールバック内で
	# subscribe/unsubscribe されたときにエラーになる可能性があります。
	var listeners_copy: Array = _listeners[event_name].duplicate()

	for listener in listeners_copy:
		if not listener.is_valid():
			# 無効なコールバックは掃除
			_listeners[event_name].erase(listener)
			continue

		# 例外が出ても他のリスナーには影響しないように try/catch
		# （Godot 4 では "assert" などでも可。ここでは素直に呼び出し）
		listener.call(payload)


## すべてのリスナーを解除（テストやシーン切り替え時用）
func clear_all_listeners() -> void:
	_listeners.clear()
	if enable_debug_log:
		_debug_print("cleared all listeners")


# ---------------------------------------------------------
# デバッグ表示
# ---------------------------------------------------------

func _debug_print(msg: String) -> void:
	print("[GlobalEventBus] ", msg)


func _debug_print_event(event_name: StringName, payload: Variant) -> void:
	if debug_log_filter.size() > 0 and not debug_log_filter.has(event_name):
		return

	var payload_str := ""
	match typeof(payload):
		TYPE_NIL:
			payload_str = "null"
		TYPE_DICTIONARY:
			payload_str = JSON.stringify(payload, "\t")
		_:
			payload_str = str(payload)

	print("[GlobalEventBus] emit: '%s' payload=%s" % [event_name, payload_str])

この GlobalEventBus.gd を AutoLoad に登録して、どこからでも GlobalEventBus.emit_event(...) や GlobalEventBus.subscribe(...) を呼べるようにします。

使い方の手順

手順①：シングルトン（AutoLoad）として登録する

res://scripts/GlobalEventBus.gd など、好きな場所に保存します。
Godot エディタのメニューから
Project > Project Settings… > AutoLoad タブを開きます。
Path に res://scripts/GlobalEventBus.gd を指定し、Name を GlobalEventBus のまま「Add」します。

これで、どのスクリプトからでも GlobalEventBus という名前でアクセスできるようになります。

手順②：UI からイベントを発行する（例：HP 減少ボタン）

たとえば、デバッグ用に「ダメージを与える」ボタンを UI に置いて、Player に直接触らずにイベントだけ飛ばしてみます。

MainUI (Control)
 ├── DamageButton (Button)
 └── ...

DamageButton に以下のようなスクリプトを付けます。


extends Button

func _ready() -> void:
	pressed.connect(_on_pressed)

func _on_pressed() -> void:
	# Player のことは知らない。ただ「player_damaged」イベントを投げるだけ。
	var payload := {
		"amount": 10,
		"source": "debug_button"
	}
	GlobalEventBus.emit_event("player_damaged", payload)

UI 側は 「Player がどこにいるか」「どのシーンにいるか」一切知らない のがポイントです。

手順③：Player がイベントを購読して反応する

Player 側は CharacterBody2D などのノードにコンポーネント的なスクリプトをアタッチして、GlobalEventBus からのイベントを購読します。

Player (CharacterBody2D)
 ├── Sprite2D
 ├── CollisionShape2D
 └── PlayerEventListener (Node)

PlayerEventListener という Node を子として追加して、そこにスクリプトを付けましょう。


extends Node

@export var max_hp: int = 100
var current_hp: int

func _ready() -> void:
	current_hp = max_hp
	# Player がダメージイベントを購読
	GlobalEventBus.subscribe("player_damaged", _on_player_damaged)

func _exit_tree() -> void:
	# シーンから消えるときは購読解除しておくと安全
	GlobalEventBus.unsubscribe("player_damaged", _on_player_damaged)


func _on_player_damaged(payload: Variant) -> void:
	# UI から送られてくる payload を想定
	# 例: { "amount": 10, "source": "debug_button" }
	if typeof(payload) != TYPE_DICTIONARY:
		return

	var amount: int = payload.get("amount", 0)
	current_hp = max(current_hp - amount, 0)

	print("Player took %d damage from %s. HP: %d/%d"
		% [amount, payload.get("source", "unknown"), current_hp, max_hp])

	if current_hp <= 0:
		_die()


func _die() -> void:
	print("Player died!")
	# ここで GameOver イベントをさらに飛ばしてもOK
	GlobalEventBus.emit_event("game_over", {"reason": "player_dead"})

この構成なら、Player 本体は「誰がダメージを飛ばしているか」を知る必要がありません。
UI でも、敵でも、トラップでも、GlobalEventBus.emit_event("player_damaged", ...) さえ呼べば共通のロジックが走ります。

手順④：GameManager や UI が別イベントを購読する

今度は、Player が死んだときに game_over イベントを飛ばして、それを GameManager と UI が受け取る例を見てみましょう。

GameManager (Node)
 └── (他の管理用ノードなど)


extends Node

func _ready() -> void:
	GlobalEventBus.subscribe("game_over", _on_game_over)

func _exit_tree() -> void:
	GlobalEventBus.unsubscribe("game_over", _on_game_over)


func _on_game_over(payload: Variant) -> void:
	print("Game Over! reason =", payload.get("reason", "unknown"))
	# シーン遷移やリトライメニュー表示などをここで行う

UI 側でも同じように購読できます。

MainUI (Control)
 ├── GameOverLabel (Label)
 └── ...


extends Control

@onready var game_over_label: Label = %GameOverLabel

func _ready() -> void:
	game_over_label.visible = false
	GlobalEventBus.subscribe("game_over", _on_game_over)

func _exit_tree() -> void:
	GlobalEventBus.unsubscribe("game_over", _on_game_over)


func _on_game_over(payload: Variant) -> void:
	game_over_label.visible = true
	game_over_label.text = "GAME OVER\n(%s)" % payload.get("reason", "???")

これで、

Player は GameManager や UI を知らない
GameManager も Player や UI を知らない
UI も Player や GameManager を知らない

という、かなり疎結合な構成になります。
それぞれが GlobalEventBus という「窓口」だけを知っていればよい、というのがポイントですね。

メリットと応用

1. シーン構造の変更に強い
ノード同士を直接シグナル接続していると、

UI を別シーンに切り出した
Player を別シーンからインスタンスするようにした

といったタイミングで get_node() のパスやシグナル接続を全部見直す羽目になります。
GlobalEventBus 経由にしておけば、「どこにいようが emit_event() と subscribe() さえ呼べればOK」なので、レベルデザインやシーン再構成の自由度がかなり上がります。

2. 再利用しやすいコンポーネントが作れる
今回の PlayerEventListener のように、「イベント購読ロジックだけを持った Node」をコンポーネントとして作っておけば、

敵用の EnemyEventListener
アイテム用の ItemEventListener
UI 用の UIEventListener

などをノードにペタペタ貼るだけで、イベント駆動の挙動をどんどん追加できます。
ノードの継承をいじらずに、合成（Composition）で機能を付け足していけるのが気持ちいいところですね。

3. デバッグやログ出力が一箇所に集約される
イベントの流れを追いたいときは、GlobalEventBus.enable_debug_log = true にしておくだけで、

どのイベントがいつ飛んだか
どんな payload が載っていたか

をまとめてログに出せます。
個別のノードで print デバッグをばらまくより、中央集権的に監視できるのが便利です。

改造案：特定イベント専用のショートカット API を追加する

よく使うイベントは、毎回 emit_event("player_damaged", {...}) と書くのが少しだるいので、
GlobalEventBus に「専用メソッド」を生やしておくのもありです。


# GlobalEventBus.gd の末尾あたりに追加

## Player にダメージを与える専用メソッド
func emit_player_damaged(amount: int, source: String = "unknown") -> void:
	var payload := {
		"amount": amount,
		"source": source,
	}
	emit_event("player_damaged", payload)

こうしておけば、UI や敵などからは


GlobalEventBus.emit_player_damaged(10, "enemy_slime")

と書けるようになり、イベント名の typo を防ぎつつ、コードの意図も明確になります。
プロジェクトが大きくなってきたら、イベントごとにこうしたショートカットを整理していくのもおすすめです。

GlobalEventBus のようなイベントバスを一つ用意しておくだけで、
「深いノード階層＋直接シグナル接続」から、「シンプルなシーン構成＋コンポーネント＋イベント駆動」へきれいに移行できます。
ぜひ、自分のプロジェクト用にカスタマイズしながら使い回してみてください。

【Godot 4】PatrolPath (巡回ルート) コンポーネントの作り方

【Godot 4】InvestigatePos (不審点調査) コンポーネントの作り方