Observer Pattern

The Observer pattern lets one object, the subject, tell many other objects, the observers, that something happened. The subject does not know what the observers do with the news; it only announces it.

Written by hand, the subject keeps an array of observers and calls the same method on each one:

# health.gd
class_name Health
extends RefCounted

var observers: Array = []
var hp := 100

func add_observer(observer) -> void:
	observers.append(observer)

func take_damage(amount: int) -> void:
	hp -= amount
	for observer in observers:
		observer.on_hp_changed(hp)

Godot has this pattern built in. A signal is the subject's announcement, and every connect() adds an observer, so the array and the loop are no longer needed:

# health.gd
class_name Health
extends RefCounted

signal hp_changed(new_hp: int)

var hp := 100

func take_damage(amount: int) -> void:
	hp -= amount
	hp_changed.emit(hp)

An observer is any object with a method whose parameters match the signal:

# health_bar.gd
class_name HealthBar
extends RefCounted

func on_hp_changed(new_hp: int) -> void:
	print("Bar: ", new_hp, "/100")

# damage_log.gd
class_name DamageLog
extends RefCounted

func on_hp_changed(new_hp: int) -> void:
	if new_hp < 50:
		print("Log: low health!")

# main.gd
var health := Health.new()
var bar := HealthBar.new()
var damage_log := DamageLog.new()
health.hp_changed.connect(bar.on_hp_changed)
health.hp_changed.connect(damage_log.on_hp_changed)
health.take_damage(70)

Bar: 30/100
Log: low health!

Health has no idea a bar or a log exists. A sound effect or an achievement can listen too, without a single change to health.gd.

Three rules keep observers working:

• Connecting the same method twice is an error. When it could happen, check first with hp_changed.is_connected(bar.on_hp_changed). disconnect() removes an observer, and disconnecting one that is not connected is an error too.
• A connection does not keep the observer alive. Keep the observer in a variable or an array: an object created inside the connect() call is freed at once and never hears the signal.
• Connect methods of the observers. A lambda that uses the subject and is connected to the subject's own signal keeps the subject alive forever, which Godot reports as a leak when the game closes.