getting_started/step_by_step/signals

[giscus[bot]]

getting_started/step_by_step/signals

In this lesson, we will look at signals. They are messages that nodes emit when something specific happens to them, like a button being pressed. Other nodes can connect to that signal and call a fu...

https://docs.godotengine.org/en/latest/getting_started/step_by_step/signals.html

[samuelfine]

Signals are one of my favorite parts of Godot, but wiring Signals for “one-to-many” or “many-to-many” events can be time-consuming and difficult to maintain. For example, when an enemy dies there may be many other nodes that need to react: a game manager keeping score, a player with experience points, an enemy spawner, and so on. There may also be many types of nodes that could affect the score or experience points, and maintaining all these connections can become complex.

One way to easily manage these kinds of Signals is through creating a Signal Bus, based on the Event Bus architecture pattern. It’s a single script that contains Signals for events that will need to be dispatched to many other nodes, allowing scripts to emit events without knowing (or caring) which other nodes are connected to the event, and vice-versa.

Creating a Signal Bus is quick and simple. Add a new script and register it as an Autoload with “Global Variable” checked. Then, create any Signals you need there:

SignalBus.gd

extends Node

# You can define any params to passthrough here if needed
signal enemy_died(param, another_param)

Now, in any script that would emit that event, do so to the Signal Bus directly:

Enemy.gd

func _whatever_function():
    SignalBus.enemy_died.emit(something, something_else)

Finally, all other scripts that needs to be aware of the event can connect to the Signal Bus’s Signal:

GameManager.gd, Player.gd, EnemySpawner.gd, …

func _ready():
    SignalBus.enemy_died.connect(_on_enemy_died)

func _on_enemy_died(param, another_param):
    # Your code here…

[MaryGz]

Hello, what parent node was used for the section "Custom signals"? I tried a Node2D but I think that's not correct. I tried searching for a CustomSignal node but nothing is coming up. Sorry if it's really obvious. Thanks in advance!

[jessodum]

Is this just for custom signals? How might built-in signals travel through the SignalBus?

[dGameBoy101b]

Is this just for custom signals? How might built-in signals travel through the SignalBus?

You just need to setup a signal relay script that connects to the builtin signal and relays any emissions to the signal bus.

As an example, for the press() signal on the BaseButton node you might do something like the following:

SignalBus.gd

signal button_pressed() #add signal to signal bus

ButtonPressRelay.gd

extends Node

@export var button: BaseButton #the button to relay signals from

func _on_pressed():
    SingalBus.button_pressed.emit() #relay the signal to the signal bus

func _ready():
    button.pressed.connect(_on_pressed) #connect to the button's signals

[dGameBoy101b]

Is this just for custom signals? How might built-in signals travel through the SignalBus?

And for completeness sake, here's an example with parameters, relaying body_entered(body: Node) from RigidBody3D.

SignalBus.gd

signal player_collision(body: Node) #signal doesn't need same name as builtin signal, only same parameters

RigidBody3DBodyEnteredRelay.gd

extends Node

@export var rigid_body_3d: RigidBody3D

func _on_body_entered(body: Node):
    SignalBus.player_collision.emit(body)

func _ready():
    rigid_body_3d.body_entered.connect(_on_body_entered)

This pattern also works with any 3rd party scripts you might be using too.

[freezerain]

I have spells and buffs, and I didn't want to write separate signals for each element. Here is how one can create event-based procedural connection between abstract classes.

# class holder of active buffs
class_name MagicState extends Resource

func _init():
    _generate_signals()

func _generate_signals(): 
    for id in spell_id_list: # I am using ENUMs
        # second argument is an array dict of new signals arguments - {name, type}
        add_user_signal("%s_changed" % id, [{"name":"buff_type", "type":TYPE_INT}])

func buff_activated(target_spell_id, buff_type):
    emit_signal("%s_changed" % target_spell_id, buff_type)

Then in the base class all spells, items, resource are inheriting from:

class_name MagicObject extends Resource

var id

func _init(a_id):
    id = a_id
    _signal_connect()

func _signal_connect():
    Main.magic_state.connect("%s_changed" % id, _on_magic_state_changed)

# this to override in child
func _on_magic_state_changed(type):
    pass

My objects receive signals by their ID or their Tags[], so casting a spell that will improve the power of all FIRE tags will indirectly notify every magic object with that tag and nothing more.

[ryanprice]

Hey guys, something that threw me for awhile as a complete Godot noob, documentation update request.

After the step "Save your newly created scene as node_2d.tscn", maybe mention that you need to change your main scene to the node_2d.tscn, or when you run build/debug it will default back to the sprite_2d scene and the button won't display.

Very obvious for user with any experience.. but going line by line.. I rebuilt this 3x before I realized this update was required.

[aretw0]

If you run with F6 (run current scene) that doesn't matter.

[krzysztofn1993]

Hi total newbie here,
I am programming in C#. I instantieted first scene in second scene, added button for toggling motion, attached script to Sprite2D. In first scene I placed my sprit in the middle of viewport (not at position 0,0). Now when I run it, it looks like it rotates my whole first scene, not just the sprite. I resolved this problem by placing my sprite at position 0,0 in first scene, but is there a other way so the calculation of position is relative to a place where sprite is located in executed scene?

[ajelston16]

My guess is that your button is a child of your sprite2D instead of your Node2D.

[SleepyDreepyEepy]

Leaving this here to potentially clear up an issue I had that other newbies may run into.

sprite_2d.gd:6 @ _ready(): Node not found: "Timer" (relative to "/root/Sprite2D").

After fully building the code for this section I found that I was getting error messages(above) saying that the Timer node could not be found. This was only happening with the 'Run Project(F5)' button, when using 'Run Current Scene(F6)' the code ran as intended.
It took a hot spell to figure out that this was because the main scene(which is the part of the code run by the 'Run Project' option) was still set to the 'sprite_2d.tscn' scene from work on the previous pages. That scene had all the same code as this section without the nodes added on this page.
So if things aren't adding up with your node connections, remember to check what you've set as your main scene (it's highlighted, took me a bit too long to remember that).

[faulknermano]

Since this is an introductory topic, I would like to add something about using Godot's built-in signals that pass their own parameter, which doesn't seem to be covered here.

Built-in signals such CollisionObject2D.mouse_shape_entered pass their own parameter (shape_idx: int).

If you wanted to pass your own, in addition to the built-in one, you write the callback function with the signature accepting the bulit-in parameter first, and then your own user-defined parameters.

For example, in a CollisionObject2D script, I have a "add listener" function:

func add_mouse_entered_listener(call_func):
    mouse_shape_entered.connect(call_func.bind(self))

... where call_func is a callback in another script. I have passed self, which is the CollisionObject2D into a signal which will prepend its parameter with mine.

So in my callback function called set_cursor_light, I make sure that my first parameter(s) are going to accept the builtin parameters first (i.e. shape_index):

func set_cursor_light(shape_index, collider: CollisionObject2D):
    if collider.is_mouse_over:
        enable_cursor_glow(shape_index)
    else:
        disable_cursor_light(shape_index)

[Quest79]

The last part doesn't give a practical example of how this is used, making is clear as mud for the intended audience.

[MaryGz]

Hello, what parent node was used for the section "Custom signals"? I tried a Node2D but I think that's not correct. I tried searching for a CustomSignal node but nothing is coming up. Sorry if it's really obvious. Thanks in advance!

[dallium01]

Custom Signals appears to be a Node2D, since the script starts with "extend Node2D", but that's not the point. The object is called just called Custom Signals for instructional purposes. The purpose of the section is to demonstrate that we can define and design our own signals when we need them, not to instruct us to literally make another Node2D called Custom Signals.tscn, nor to literally attach Custom Signals.gs to said Node2D. It's simply an example to show us what those definitions should look like in our own projects, and how those signals will populate in the node tab in the inspector.

[MaryGz]

To connect a signal named "generate_resource" emited by Main to a function called "obtain_resource" in a child node is it:
var main = get_node("Main")
main.generate_resource.connect(obtain_resource)

I think it´s wrong because I get:
Invalid access to property or key 'generate_resource' on a base object of type 'null instance'.

[MaryGz]

Ok, I see that I need the correct path: var main = get_node("/root/Main")

However, is it good practice to have Main emit signals? I feel that the tutorial implied that children emit signals to parents

[faulknermano]

@MaryGz I don't think it's a question of good practice, but rather what you need them to do.

What you are referring to about "Main emitting signals", is whether a single object emits a signal for many listeners, or whether many signal-emitters are informing a single listening object. As you can see, those are two different things and none of them work better or another; it's a matter of what you need.

I have a setup where a "Main" object is emits signals to indicate that a variable has changed. Certain objects (NPCs) in the scene have "subscribed" to Main's signal because they are interested in knowing when that happens. In order to achieve this setup, each NPC, when initialised, grabs the Main instance and subscribes their callback func to Main's signal.

In Main.gd:

# Main.gd
signal dict_changed(dict)
var my_dict = {}

func _unhandled_input(event):
    # Create an Input action "generic_left_right_mouse" in order to trigger this block
    if event.is_action_pressed("generic_left_right_mouse"):
        my_dict = {"key": 1}
        emit_signal("dict_changed", dict)

In NPC.gd:

# NPC.gd
var Main = get_node("/root/Main")
func _ready():
    Main.connect("dict_changed", __npc_callback)
func __npc_callback(dict):
   print("Detected Main dict changed to %s" % dict )

In same scene, I have a setup that reverses the communications, where the NPCs are requesting Main to call its own function (Main.on_npc_destroyed) when something happens to them, for example, if they get destroyed.

The Main.gd script

# Main.gd
func on_npc_destroyed(npc_object):
    print("Detected NPC %s was destroyed" % npc_object.get_name())

The NPC.gd script:

# NPC.gd
signal npc_destroyed
var Main = get_node("/root/Main")
func _ready():
    connect("npc_destroyed", Main.on_npc_destroyed)
func __on_destroyed():
    emit_signal("npc_destroyed", self)

Also note although we are referring to them as "children" or "parents", Signals can connect objects to those outside their hierarchy. I would rather think of them as "receivers/listeners" and "emitters".

[DaFlarf]

I recently ran into some troubles with signals, so I thought it would be helpful to share my solution.

As the docs tell you, you can connect signals from the editor to methods by right clicking the signal and pressing connect.

However, connecting through code isn't as easy as the guide lets on. To do so, you will need to use lambda functions like shown here: https://www.youtube.com/watch?v=Qlq8pBB2htg

Here is an example:

get_node("MainMenu/UIRoot/ExitButton").pressed.connect(
func _on_main_menu_exit_pressed():
print("it worked finally")
get_tree().quit())

[thomzd]

Hi,
I did not understand why for a Button I could link the signal to the Sprite2D through the "Node" tab whereas for the Timer I had to write code in my script. When I tried to link the Timer timeout() to my Sprite2D through the Node tab it didn't work.

In other terms, why does this code not work :

func _on_timer_timeout():
	visible = not visible

[faulknermano]

whereas for the Timer I had to write code in my script.

Godot will allow you to connect via Node tab:

• Click "Connect"
• Search for and select the node that has the script that contains your function
• Select your function

I think the docs are not presenting the topic in a clear and orderly way. :-D

[thomzd]

whereas for the Timer I had to write code in my script.

Godot will allow you to connect via Node tab:

• Click "Connect"
• Search for and select the node that has the script that contains your function
• Select your function

I think the docs are not presenting the topic in a clear and orderly way. :-D

Thanks for your answer. I just did as you said and it worked. I thought I already did it the same way before but maybe I was missing something... Cheers :)

[baz-atak]

The Timer example wasn't because you had to connect a timer via code, it's supposed to illustrate how to connect something via code.
The example would probably make more sense if the the thing to connect (in this case the Timer) was created via code rather than added in the scene dock and just looked up in the code via get_node. By adding it via the scene dock you can connect it in the editor via the node tab.
If you were to instantiate something in code then you'd need to connect it via code. The example should probably do that rather than the bit about adding the Timer via the scene dock. I'd suggest removing that stage and changing the code to something like this:

extends Sprite2D

var speed = 400
var angular_speed = PI

func _ready():
	var timer = Timer.new()
	timer.autostart = true
	timer.timeout.connect(_on_timer_timeout)
	add_child(timer)


func _process(delta):
	rotation += angular_speed * delta
	var velocity = Vector2.UP.rotated(rotation) * speed
	position += velocity * delta


func _on_timer_timeout():
	print("timeout")
	visible = not visible

[zombyra]

Thanks, And you can create a timer to call a function at the end with this method!:

get_tree().create_timer(2.0).timeout.connect(throw_dices_phys)

[DarrylHardin]

Anyone who has got this far probably already knows, but I couldn't get the code in the tutorial to work as it said timer was null, even copying their code and pasting it right in gave me the same. @baz-atak's code works perfect.

[avilkinnick]

If someone don't understand why godot don't autocomplete timer.timeout.connect(_on_timer_timeout), it's because line var timer = get_node("Timer") can only deduce type of "Timer" at runtime. To have autocompletion you can use static typing and write var timer: Timer = get_node("Timer")