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

APIs thread-safe (seguras para threads)

Partes_Paralelizáveis

Partes_Paralelizáveis são usadas para equilibrar o poder de processamento entre CPUs e núcleos. Godot suporta multithreading(paralelismo), mas não em todo o Motor.

Abaixo está uma lista de maneiras como o paralelismo(multithreading) pode ser utilizado em diferentes áreas do Godot.

Escopo global

A maioria dos singletons de Global Scope é thread-safe por padrão. O acesso a servidores a partir de threads é suportado. No entanto, para os servidores de renderização e de física, a operação thread-safe deve ser habilitada primeiro nas configurações do projeto.

Isso torna os singletons ideais para códigos que criam dezenas de milhares de instâncias em servidores e os controlam a partir de threads. Claro que isso exige um pouco mais de código, já que é usado diretamente e não dentro da árvore de cena (scene tree).

Árvore de cena

Interagir com a árvore de cena ativa não é thread-safe. Certifique-se de usar mutexes ao enviar dados entre threads. Se você quiser chamar funções ou definir propriedades a partir de uma thread, pode usar call_deferred ou set_deferred:

GDScriptC#

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

No entanto, criar partes da cena (nós em uma disposição em árvore) fora da árvore ativa é aceitável. Dessa forma, partes de uma cena podem ser construídas ou instanciadas em uma parte_paralelizavel(thread), e depois adicionadas na parte principal_paralelizavel principal(main thread):

GDScriptC#

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)

Ainda assim, isso só é útil de verdade se você tiver uma thread carregando dados. Tentar carregar ou criar blocos de cena a partir de múltiplas threads pode funcionar, mas você corre o risco de ver recursos (que são carregados apenas uma vez no Godot) sendo modificados pelas múltiplas threads, resultando em comportamentos inesperados ou travamentos.

Utilize mais de uma thread para gerar dados da cena apenas se você realmente souber o que está fazendo e tiver certeza de que um mesmo recurso não está sendo utilizado ou definido em múltiplas threads. Caso contrário, é mais seguro utilizar diretamente a API do servidor (que é totalmente segura para uso em múltiplas threads) e não manipular a cena ou os recursos.

Renderização

Instantiating 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 que o modelo de thread Separate possui vários bugs conhecidos, por isso pode não ser utilizável em todos os cenários.

Aviso

Você deve evitar chamar funções que envolvam interação direta com a GPU em outras threads, como criar novas texturas ou modificar e recuperar dados de imagem. Essas operações podem levar a quedas de desempenho porque exigem sincronização com o RenderingServer, já que os dados precisam ser transmitidos para a GPU ou atualizados nela.

Física

A simulação de física não é segura para threads por padrão. Para rodar os servidores de física em threads separadas (tornando-os thread-safe), ative as seguintes configurações de projeto:

• PhysicsServer2D: Physics > 2D > Run on Separate Thread.

• PhysicsServer3D: Physics > 3D > Run on Separate Thread.

Navegação

NavigationServer2D e NavigationServer3D são ambos thread-safe e amigáveis a threads.

As funções de consulta relacionadas à navegação podem ser chamadas por threads e executadas em paralelo real.

Por padrão, um número conservador de threads é suportado rodando em paralelo real nos mapas de navegação antes que threads adicionais tenham que esperar pelo acesso aos dados do mapa em um semáforo. Para aumentar o número de threads que podem rodar simultaneamente nos dados do mapa, defina Navigation > Pathfinding > Max Threads.

Os recursos relacionados ao servidor de navegação, como NavigationSourceGeometryData, NavigationMesh e NavigationPolygon, são todos seguros para threads, mas não necessariamente amigáveis para threads. Eles usam travas internas de leitura e escrita para segurança de threads, de modo que editar o mesmo recurso (ex.: uma única malha de navegação grande) em múltiplas threads ao mesmo tempo pode causar congestionamento de threads.

As classes auxiliares relacionadas à navegação, como AStar2D, AStar3D e AStarGrid2D, não são seguras para threads. Elas podem ser usadas com threads com alguma capacidade limitada, mas usar duas ou mais threads no mesmo objeto AStar causa corrupção de dados. Por exemplo, usar uma thread de segundo plano dedicada por objeto AStar para preencher pontos ou fazer consultas funciona, mas duas threads usando o mesmo objeto AStar corromperiam os dados uma da outra.

Arrays e dicionários do GDScript

No GDScript, ler e escrever elementos a partir de múltiplas threads é seguro, mas qualquer coisa que altere o tamanho do contêiner (redimensionar, adicionar ou remover elementos) exige o bloqueio de um mutex.

Recursos

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.