0

Description

"This event singleton script handles global game events, used to signal events between nodes by a event StringName.\r\n\r\nThis event-based logic has several benefits:\r\n* Reference decoupling: No necessity to get the reference to the target node, one subscribes to the event and the other emits;\r\n* Automatic unsubscription: As it internally uses the Node's signal connections, it doesn't need to manually handle target dereferencing, as the engine handles this internally;\r\n* Last value replay: With the optional **emit_last_val** argument on **subscribe** method, if the event were already emitted, it emits the newest value to the subscriber method;\r\n* Multiplayer code: This can be used for multiplayer events, useful for custom sync logic, match join, etc.\r\n\r\nThe main use case is event handling, for example:\r\n\r\n```\r\n# coin.gd\r\nvar value: int\r\n\r\nfunc pickup() -> void:\r\n\tEvent.emit(&\"coin_pickup\", self)\r\n\r\n# player.gd\r\nvar total_coins: int\r\n\r\nfunc _ready() -> void:\r\n\tEvent.subscribe(&\"coin_pickup\", on_coin_picked_up)\r\n\r\nfunc on_coin_picked_up(coin) -> void:\r\n\ttotal_coins += coin.value\r\n```\r\n\r\nBut another great usage is executing a setup when another node is ready:\r\n\r\n```\r\n# sfx_manager.gd\r\n\r\nfunc _ready() -> void:\r\n\tEvent.emit(&\"sfx_manager_ready\", self)\r\n\r\nfunc play_sfx(sfx_name: String) -> void:\r\n\tpass\r\n\r\n# coin.gd\r\n\r\nvar sfx_manager\r\n\r\nfunc _ready() -> void:\r\n\t# [true] sends the newest emitted value, if any\r\n\tEvent.subscribe(&\"sfx_manager_ready\", on_sfx_manager_ready, true)\r\n\r\nfunc on_sfx_manager_ready(manager) -> void:\r\n\tsfx_manager = manager\r\n\r\nfunc pickup() -> void:\r\n\tsfx_manager.play_sfx(\"coin_pickup\")\r\n\r\n```\r\n\r\nPassing `true` to the third argument `subscribe` makes it replay the last value to the subscriber method. With this, you don't need to worry if the manager is ready before the coin, or the inverse.\r\n\r\nFor multiplayer, one of the main struggles for me is using RPC with runtime instantiated nodes. For example a Player node which is instantiated in the server, but yet not instantiated for several frames on clients. Calling RPC methods throws errors that the node doesn't exist in the peers.\r\n\r\nWith the event singleton, you can emit using RPC for these cases, for example:\r\n\r\n```\r\n# player.gd\r\n\r\nvar player_id: int\r\n\r\nfunc _ready() -> void:\r\n\tEvent.subscribe(\"player_%d_position_sync\" % player_id, on_player_position_sync)\r\n\r\nfunc _process(delta: float) -> void:\r\n\tEvent.emit.rpc(\"player_%d_position_sync\" % player_id, position)\r\n\r\nfunc on_player_position_sync(new_pos: Vector2) -> void:\r\n\tposition = new_pos\r\n``` \r\n\r\nSo you don't need to worry about validating if the node is already instantiated on the pairs. \r\n> [!NOTE]\r\n> When using `emit.rpc`, the function is only called on the remote peers, to also emit on the local client, you must call `emit` without rpc:\r\n> ```\r\n> func _process(delta: float) -> void:\r\n> \tEvent.emit.rpc(\"player_%d_position_sync\" % player_id, position)\r\n> \tEvent.emit(\"player_%d_position_sync\" % player_id, position)\r\n> ```"

Main code

extends Node

var event_signal_ids: Dictionary[StringName, StringName]
var event_last_call: Dictionary[StringName, Array]
var event_signal_current_id: int = 1

func create_signal_id() -> StringName:
	var id: int = event_signal_current_id
	event_signal_current_id += 1
	return StringName("__event_%d" % id)

func get_or_create_signal_id(event_id: StringName) -> StringName:
	if not event_signal_ids.has(event_id):
		var signal_id: StringName = create_signal_id()
		add_user_signal(signal_id)
		event_signal_ids[event_id] = signal_id
		return signal_id
	return event_signal_ids[event_id]

func subscribe(event_id: StringName, cb: Callable, emit_last_val: bool = false) -> void:
	connect(get_or_create_signal_id(event_id), cb)
	if emit_last_val and event_last_call.has(event_id):
		var last_args: Array = event_last_call[event_id]
		cb.callv(last_args)

func unsubscribe(event_id: StringName, cb: Callable) -> void:
	var sig_id: StringName = get_or_create_signal_id(event_id)
	disconnect(sig_id, cb)
	if get_signal_connection_list(sig_id).is_empty():
		remove_user_signal(sig_id)
		event_signal_ids.erase(event_id)
		event_last_call.erase(event_id)

@rpc("any_peer", "call_remote", "reliable")
func emit(event_id: StringName, ...args: Array) -> void:
	emit_signal.bindv(args).call(get_or_create_signal_id(event_id))
	event_last_call[event_id] = args

Comments