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.

[beders]

Careful when adopting this pattern. This can be an anti-pattern depending on your use case.

Consider grouping signals in a way that makes sense to your game and avoid centralizing signals in a singleton.
Carefully analyze which signals need to be seen by whom: Maybe you are just missing a domain object that is in charge of communication, like EnemyDeath or something of that kind.

If you adopt the above you will end up with a very large object containing large lists of events that are not related.

[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.

[CecileGallioz]

Thx so much!

[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.

[salmonmoose]

I presume you mean this:

func take_damage(amount):
    var old_health = health
    health -= amount
    health_changed.emit(old_health, health)

You would consume this elsewhere with something along the lines of:

func _ready():
    $DamageTaker.health_changed.connect(handle_health_changed)
    
func handle_health_changed(old_health, health):
    #do stuff here

With this, when you emit health_changed from the node "DamageTaker" it is intercepted by handle_health_changed

[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")

[okachobi]

This page should have some discussion about binding custom parameters to an existing signal.

An example scenario where this might be helpful is when you have a number of Control Buttons in a container and you want to connect their "pressed" signal to a single signal handler rather than having a function for each one separately. If you use mybutton.connect( "pressed", _on_pressed ) you cannot determine which button was pressed in _on_pressed().

Instead, you can use mybutton.connect( "pressed", Callable(self, "on_pressed").bind(mybutton) ) to add the button as a parameter to on_pressed.

func _ready() -> void:
    $StartButton.connect( "pressed", Callable( self, "_on_pressed" ).bind( $StartButton ) )
    $ExitButton.connect( "pressed", Callable( self, "_on_pressed" ).bind( $ExitButton ) )

func _on_pressed( which : Button ) -> void:
    print( "Button pressed: " + which.name )

or even...

func _ready() -> void:
    for button in $Container:
        if button is Button:
            button.connect( "pressed", Callable( self, "_on_pressed" ).bind( button ) )

func _on_pressed( which : Button ) -> void:
    print( "Button pressed: " + which.name )

There are more details in the docs for Callable

[revilofr]

Hi thx for your solution guys.

I'm working with C# and I enjoyed reading your way to do it.
On my end, I wanted to get a way to do it in a way that is in the spirit of this tutorial :

here it is

public partial class Button : Godot.Button
{
	private MySprite2D _sprite2D;

	// Called when the node enters the scene tree for the first time.
	public override void _Ready()
	{
		// get Sprite2D which is a same level node
		_sprite2D = GetNode<MySprite2D>("../Sprite2D");

		//Connecting action events
		Pressed+=_sprite2D.OnButtonPressed;
	}
}

I hope it wil help some of you ! Cheers !

[QuizzicalCapers]

Hi, I am completely new to programming and I'm following along with the tutorials. When it comes to connecting the pressed() signal in the "Connect a Signal to a Method" panel I get a "Target method not found". I've gone back through to check if I've made a mistake somewhere but can't see anything. Could anyone point me in the right direction?, Regards

[QuizzicalCapers]

I have just spotted that in the Scene tree there is no script icon next to Sprite2D

[MisterMajickMan]

Why can I do this:

button.pressed.connect(func(): plus_button_pressed("TEST"))

but not:

button.pressed.connect(plus_button_pressed("TEST"))

Shouldn't this still return the same in the end?

Also I am having difficulty finding documentation on lambda functions and how they work, perhaps that might help - so would anyone be able to forward the relevant document page?

[zombyra]

As far as I know its like this:
button.pressed.connect(plus_button_pressed.bind("TEST"))

[faulknermano]

Shouldn't this still return the same in the end?

When you use

plus_button_pressed("TEST")

You are calling the function with a parameter. You aren't referring to a function, but referring to the result of the function call.

So when you make a connect call like you did above:

button.pressed.connect(plus_button_pressed("TEST"))

Are you, in effect, saying: "I want to connect the result of plus_button_pressed("TEST") to button.pressed.

But what you actually want is to connect the very function itself.

If you didn't have args you would just pass in the func:

button.pressed.connect(plus_button_pressed)

(You wouldn't call the func like button.pressed.connect(plus_button_pressed()), but remove the brackets)

Because you want to use a pre-determined argument "TEST", you use bind as @zombyra wrote: plus_button_pressed.bind("TEST") returns a "copy" of the function with "TEST" already assumed to be have been put in. But it doesn't call the function, it simply passes the "argument-injected" func as an object.

It could be made even clearer by splitting the lines

# `bind` returns a function/Callable with "TEST" injected as arg
var custom_test_func = plus_button_pressed.bind("TEST")
button.pressed.connect(custom_test_func)

This "argument-injected" func is the one that gets run when the signal is emitted.