Thread-safe APIs

Threads

Threads are used to balance processing power across CPUs and cores. Godot supports multithreading, but not in the whole engine. Below is a list of ways multithreading can be used in different areas of Godot.

Global scope

Global Scope singletons are all thread-safe. Accessing servers from threads is supported (for VisualServer and Physics servers, ensure threaded or thread-safe operation is enabled in the project settings!). This makes them ideal for code that creates dozens of thousands of instances in servers and controls them from threads. Of course, it requires a bit more code, as this is used directly and not within the scene tree.

Scene tree

NOT thread-safe. Make sure to use mutexes when sending data between threads. If you want to call functions from a thread, the call_deferred function may be used:

# Unsafe:node.add_child(child_node)# Safe:node.call_deferred("add_child", child_node)

However, creating scene chunks (nodes in tree arrangement) outside the active tree is fine. This way, parts of a scene can be built or instantiated in a thread, then added in the main thread:

var enemy_scene = load("res://enemy_scene.scn")var enemy = enemy_scene.instance()enemy.add_child(weapon) # Set a weapon.world.call_deferred("add_child", enemy)

one thread loading data. Attempting to load or create scene chunks from multiple threads may work, but you risk resources (which are only loaded once in Godot) tweaked by the multiple threads, resulting in unexpected behaviors or crashes. really know what you are doing and you are sure that a single resource is not being used or set in multiple ones. Otherwise, you are safer just using the servers API (which is fully thread-safe) directly and not touching scene or resources.

Rendering

not thread-safe by default. To make rendering thread-safe, set the Rendering > Threads > Thread Model project setting to Multi-Threaded. Note that the Multi-Threaded thread model has several known bugs, so it may not be usable in all scenarios.

GDScript arrays, dictionaries

In GDScript, reading and writing elements from multiple threads is OK, but anything that changes the container size (resizing, adding or removing elements) requires locking a mutex.

Resources

one thread for loading and modifying resources, and then the main thread for adding them.