Multithreading

Multithreading

Run expensive work off the main thread without corrupting the scene tree. Prefer WorkerThreadPool for short parallel jobs; reach for Thread/Mutex/Semaphore only when you need a long-lived worker.

Related skills: godot-optimization for profiling before threading, assets-pipeline for asset import, csharp-godot for C# specifics, gdscript-advanced for async/await pitfalls.

1. Threading model & safety rules

The main thread owns the scene tree — interacting with the active scene tree is not thread-safe. Observe these doc-sourced rules:

• Servers (RenderingServer, PhysicsServer) are thread-safe only after enabling it in Project Settings (Rendering > Driver > Thread Model = Separate, Physics > {2D,3D} > Run on Separate Thread). Servers handle thousands of thread-driven instances well.
• NavigationServer2D/3D are thread-safe and thread-friendly (true parallel queries); tune Navigation > Pathfinding > Max Threads.
• AStar2D/3D/Grid2D are NOT thread-safe — one dedicated thread per object only; sharing one object across threads corrupts data.
• GDScript Array/Dictionary: reading/writing existing elements across threads is OK; resizing (add/remove) needs a Mutex.
• No GPU work off the main thread (texture creation, image read/modify) — causes RenderingServer sync stalls.
• Build scene chunks off-tree in a thread, then add them on the main thread via add_child.call_deferred() — only with a single loader thread (multiple threads risk tweaking the same cached resource → crashes).

Golden rule: Mutate the scene tree only on the main thread. From a worker, hand results back with call_deferred / set_deferred.

2. WorkerThreadPool (preferred)

WorkerThreadPool is a global singleton with threads allocated at startup. A regular task (add_task) runs on one worker; a group task (add_group_task) is distributed across workers, calling the Callable repeatedly for each element index — great for iterating many elements. Every task must be waited on (wait_for_task_completion / wait_for_group_task_completion) or its allocated resources leak. Distributing cheap work can hurt performance — only use it for genuinely expensive work.

GDScript

var enemies = [] # Filled with enemies elsewhere.

func process_enemy_ai(enemy_index):
    var processed_enemy = enemies[enemy_index]
    # Expensive per-enemy logic...

func _process(delta):
    var task_id = WorkerThreadPool.add_group_task(process_enemy_ai, enemies.size())
    # ... other main-thread work ...
    WorkerThreadPool.wait_for_group_task_completion(task_id)