I do not know of any examples of using call_deferred right off. Unfortunately, I also was not really able to find any examples of how to use call_deferred online through some quick searches.
This is not Godot related, but this article about deferred functions in Go kinda covers some of what deferred function calls are any what they are primarily used for. Unfortunately, deferred function calls in Godot are slightly different than what the article explains, at least as far as I can tell.
I'll do my best to give a brief explanation below. I'm sure there are better explanations out there, and unfortunately I don't have code examples, but hopefully it helps give an idea of how call_deferred works and why you might want to use it.
Essentially, call_deferred waits before executing the function.
This differs from normal function calls, as when you call a function it will immediately executes. For example:
print ("Hello")
print ("World")
# ==== result ====
# Hello
# World
However, if we change the code to use call_deferred, then the function within call_deferred will execute after the function finishes. For example:
call_deferred("print", "Hello")
print ("World")
# ==== result ====
# World
# Hello
As you can see, despite the line calling call_deferred being before the print("World") line, the output is printed in the opposite order. This is because the call_deferred code is put on a queue to be called after the rest of the code is done executing.
(I think call_deferred functions are called after all of the code is finished executing, but I'm not totally sure)
The biggest reason to defer function calls is because something else needs to be done before the deferred function is called so everything works as expected. For example, the following code will cause an issue in Godot:
extends Node2D
func _ready():
var new_label = Label.new()
get_parent().add_child(new_label)
The reason this does not work is because Godot is initializing the scene and adding a node to the parent of an already initialized node in _ready messes things up.
(This is probably due because of the initialization order Godot creates and/or to avoid circular dependencies)
However, we can still add nodes to the parent of a node in _ready if we use call_deferred, as then the function will be called after the scene is fully initialized and ready to go:
extends Node2D
func _ready():
var new_label = Label.new()
get_parent().call_deferred("add_child", new_label)
Other examples involving not locked/unlocked node reference issues,as explained in this Reddit post. There are other uses, but right now I cannot think of any right off.
The main takeaway is that when you want code to be executed after everything, you should use call_deferred. For the most part, calling the function directly should work without any issues so long as the function you are calling is not dependent on other resources or have constraints that are order/execution dependent.
Personally I have not needed to use call_deferred too many times in my own projects, but when you need it is good to know it is there. I've mainly used it to add/remove nodes on nodes I'm referencing in multiple different places in the code.
I'm sure I got some details wrong and/or explained things poorly, so please take the above with a grain of salt. I only have limited experience with call_deferred and have only used it a handful of times :sweat_smile:
Hopefully the explanation helps. If I find a good reference on call_deferred with Godot, I'll post it here!
