Await

In GDScript, the await keyword pauses a function until a signal is emitted or a function call ends. Using this keyword inside a function makes that function asynchronous, allowing other code to run while waiting for the awaited signal or function to finish.

Here's an example of waiting for one second before printing a message:

func show_time() -> void:
	print("Waiting for 1 second...")
	await get_tree().create_timer(1.0).timeout
	print("1 second has passed!")

When reaching the await keyword, the function literally pauses and waits for the following signal to be emitted or the following function call to return. It only pauses the function that contains the keyword; the rest of the game keeps running.

The point of this keyword is to keep your code linear even if it needs to wait for a long algorithm to run, an animation to finish, or for a file to download, for example.

Here's a video tutorial on the await keyword in Godot 4:

Execution order

When writing asynchronous code, the order can be surprising. In the example below, "Hello" and "Goodbye" both show up before "1 second has passed" does:

func _ready() -> void:
  print("Hello")
  show_time()
  print("Goodbye")

The output of this would be:

Hello
Waiting for 1 second...
Goodbye
1 second has passed!

However, the following code block would show the outputs in the expected order:

func _ready() -> void:
  print("Hello")
  await show_time()
  print("Goodbye")

Because of the await keyword before show_time(), the execution of _ready() is also paused until show_time() returns. We get this result:

Hello
Waiting for 1 second...
1 second has passed!
Goodbye

Why use await with function calls

While await is mostly used with signals, it can be useful with function calls as well. Here's an example of waiting for a function to finish. This shows how to download a file from the internet and wait for the download to complete:

var http_request := HTTPRequest.new()

func _ready() -> void:
	add_child(http_request)
	var content := await download_file("https://example.com/file.txt")
	print(content)


func download_file(url: String) -> String:
	var error := http_request.request(url)
	if error != OK:
		return ""

	# Notice that we are awaiting the signal here, which makes this
	# function asynchronous.
	var result = await http_request.request_completed
	var response_code: int = result[1]

	if response_code != 200:
		printerr("Failed to download file from '" + url + "'. Response code: " + str(response_code))
		return ""

	var body: PackedByteArray = result[3]
	return body.get_string_from_utf8()

Downloading a file from the internet takes time. Your computer has to connect to the server, request the file, and wait for the server to send the file back. Depending on the file size, the distance to the server, and the server's load, this can take a few milliseconds to several seconds.

So, we use the await keyword to pause the function until the download is complete. This way, the function remains asynchronous and the game can continue running while the download is in progress.

Be careful that the signal emits

When using the await keyword, if the associated signal never emits, the function will never resume execution. It will hang in memory until the object running the function is deleted.

This is generally not a major issue if the object is deleted, as the hanging function will be freed with the object, but it's something to keep in mind. You don't want to have a lot of hanging functions accumulating in memory.

Also, more generally, you don't want to have a function that never resumes execution because your game will not behave as intended.

There's no built-in way to set a timeout for the await keyword, so you need to make sure that the signal you are waiting for will always emit.