Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Les API sûres pour plusieurs fils d'exécution

Tâches Parallèles

Les threads sont utilisés pour équilibrer la puissance de traitement entre les processeurs et les cœurs. Godot prend en charge le multithreading, mais pas dans l'ensemble du moteur.

Vous trouverez ci-dessous une liste de façons dont le multithreading peut être utilisé dans différents domaines de Godot.

Portée globale

La plupart des singletons de Global Scope sont tous thread-safe par défaut. L'accès aux serveurs à partir de threads est pris en charge. Cependant pour les serveurs de rendu, le fonctionnement thread-safe doit être activé dans les paramètres du projet  d'abord.

Cela rend les singletons idéaux pour du code qui crée des dizaines de milliers d'instances dans des serveurs et les contrôle à partir de threads. Bien sûr, cela nécessite un peu plus de code, car celui-ci est utilisé directement et non dans l'arborescence de la scène.

Scene tree (Arbre de scène)

Interacting with the active scene tree is not thread-safe. Make sure to use mutexes when sending data between threads. If you want to call functions or set properties from a thread, you may use call_deferred or set_deferred:

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

// Unsafe:
node.AddChild(childNode);
// Safe:
node.CallDeferred(Node.MethodName.AddChild, childNode);

Cependant, il est possible de créer des morceaux de scènes (nœuds dans l'arborescence) en dehors de l'arbre actif. De cette façon, des parties d'une scène peuvent être construites ou instanciées dans un fil, puis ajoutées dans le fil principal :

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

PackedScene enemyScene = GD.Load<PackedScene>("res://EnemyScene.scn");
Node enemy = enemyScene.Instantiate<Node>();
enemy.AddChild(weapon);
world.CallDeferred(Node.MethodName.AddChild, enemy);

Still, this is only really useful if you have 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) being tweaked by the multiple threads, resulting in unexpected behaviors or crashes.

N'utilisez plusieurs fils pour générer des données de scène que si vous savez vraiment ce que vous faites et que vous êtes sûr qu'une ressource n'est pas utilisée ou définie dans plusieurs. Au contraire, il sera plus sûr d'utiliser directement l'API des serveurs (qui est entièrement sécurisée) et en ne touchant pas la scènes ou les ressources.

Rendu

Instancing nodes that render anything in 2D or 3D (such as Sprite2D or MeshInstance3D) is not thread-safe by default. To run the rendering driver on a separate thread, set the Rendering > Driver > Thread Model project setting to Separate.

Note that the Separate thread model has several known bugs, so it may not be usable in all scenarios.

Avertissement

You should avoid calling functions involving direct interaction with the GPU on other threads, such as creating new textures or modifying and retrieving image data. These operations can lead to performance stalls because they require synchronization with the RenderingServer, as data needs to be transmitted to or updated on the GPU.

Physique

Physics simulation is not thread-safe by default. To run the physics servers on separate threads (making them thread-safe), enable the following project settings:

PhysicsServer2D: Physics > 2D > Run on Separate Thread.
PhysicsServer3D: Physics > 3D > Run on Separate Thread.

Navigation

NavigationServer2D and NavigationServer3D are both thread-safe and thread-friendly.

The navigation-related query functions can be called by threads and run in true parallel.

By default, a conservative number of threads is supported running in true parallel on navigation maps before additional threads have to wait for map data access at a semaphore. To increase the number of threads that can run simultaneously on map data, set Navigation > Pathfinding > Max Threads.

The navigation server-related resources like NavigationSourceGeometryData, NavigationMesh, and NavigationPolygon are all thread-safe but not necessarily thread-friendly. They use internal read-write locks for thread-safety so editing the same resource (e.g. a single big navmesh) on multiple threads at the same time can cause thread congestion.

The navigation-related helper classes like AStar2D, AStar3D, and AStarGrid2D are not thread-safe. They can be used with threads to some limited capacity, but using two or more threads on the same AStar object causes corruption. For example, using a dedicated background thread per AStar object to populate points or do queries works, but two threads using the same AStar object would corrupt each other's data.

GDScript arrays and 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.

Ressources

Modifying a unique resource from multiple threads is not supported. However, handling references on multiple threads is supported. Hence loading resources on a thread is as well - scenes, textures, meshes, etc - can be loaded and manipulated on a thread and then added to the active scene on the main thread. The limitation here is as described above: one must be careful not to load the same resource from multiple threads at once. Therefore, it's easiest to use one thread for loading and modifying resources, and then the main thread for adding them.