Coroutines
Package: godot.coroutines. Requires isGodotCoroutinesEnabled in build.gradle.kts.
Availability
Use Node.launch and the suspend and reified APIs below from Kotlin. See the guide for a short signal-wait example.
There is no direct Java equivalent to Kotlin suspend calls. Use signal connections for callback-based code.
There is no direct Scala equivalent to Kotlin suspend calls. Use signal connections for callback-based code.
Node scopes
Node.nodeScope() returns the node's shared NodeScope. Node.launch(context = EmptyCoroutineContext, start = CoroutineStart.DEFAULT) returns a Job; Node.async accepts the same options and returns Deferred<T>.
Node.launch starts a coroutine owned by that node. It is valid only once the node has entered the scene tree. The node gets one NodeScope; Godot-JVM cancels it when the node exits the tree, which also cancels all of its child coroutines and pending waits.
1 2 3 4 5 | |
Node.async is the equivalent when the caller needs a result as a Deferred<T>.
1 2 | |
Both blocks have NodeScope as their receiver. Standard coroutine builders remain available inside them: launch, async, coroutineScope, supervisorScope, and so on. Their child coroutines inherit the same node lifetime unless a different scope is deliberately supplied.
godotCoroutine
For work that does not belong to a node, use godotCoroutine(). It is an ordinary CoroutineScope whose default dispatcher is Godot's main thread. Keep its reference and cancel it yourself when its owner is done.
1 2 3 4 5 | |
godotCoroutine(context = EmptyCoroutineContext) returns a new CoroutineScope with a SupervisorJob and GodotDispatchers.MainThread, plus the supplied context. It does not launch a block by itself.
Waiting for frames
There are two deliberately distinct sets of frame waits:
1 2 3 4 5 6 7 8 | |
Use the SceneTree-wide waits for global systems. Use the node-owned waits for a gameplay node: if the node is paused, disabled, or leaves the tree, its wait does not continue as if it were still active.
Signals and flows
For one signal emission, use await(). Signal0.await() returns Unit; Signal1<P0>.await() returns P0; higher arities return SignalArgumentsN with p0, p1, and subsequent fields, supporting destructuring. Cancelling the signal promise cancels the suspended continuation, and cancelling the coroutine releases the wait, so a later emission does nothing:
1 | |
For a stream of repeated emissions, turn the signal into a Kotlin Flow with asFlow(). A flow does nothing until it is collected; collection owns the signal connection, and cancelling the collection disconnects it.
1 2 3 4 5 6 7 8 | |
first, filter, map, debounce, take, and the rest of the Kotlin Flow operators make signal streams useful when the requirement is more than one callback. For a single event, await() is normally clearer.
Threads
GodotDispatchers.MainThread runs immediately on the main thread, otherwise through a deferred callable. GodotDispatchers.MainThreadDeferred always goes through the deferred callable, even from the main thread. GodotDispatchers.ThreadPool uses Godot's worker thread pool. threadSafe and offload are suspend functions that return their block's result.
MainThread is the default of Node.launch, Node.async, and godotCoroutine(). It is immediate so that coroutine latency stays below the frame rate: a body launched from the main thread runs inline until its first real suspension. A suspend function does not have to suspend. awaitLoad on a cached resource, Signal.await() on a signal that fires during connect, or withContext whose block finishes before the caller checks its result all return without suspending. A coroutine that never suspends therefore completes inside the call that launched it, and any signal it emits fires before that call returns.
This matters when another script awaits those signals. The GDScript below hangs if start_work() completes without suspending, because work_finished was emitted before the await existed:
1 2 | |
Either suspend at least once before emitting, for example with awaitNextProcess(), or launch the coroutine with GodotDispatchers.MainThreadDeferred, which starts the body at the next message queue flush and defers every resumption the same way:
1 2 3 4 5 6 7 | |
Node.launch and godotCoroutine() begin on Godot's main thread. A signal or frame wait also resumes there, so regular scene-tree work can remain direct and readable.
Use offload for pure CPU work only. Do not read or modify nodes, resources, or the scene tree from its block. threadSafe switches back to the main-thread dispatcher before touching Godot objects.
1 2 3 4 5 | |
Complete example: a one-wave encounter
This Area3D waits for the player, stops the stage music, plays battle music, creates a randomly chosen enemy at random points within its box, waits for every enemy to leave the tree, gives fifteen coins, restores the stage music, and removes itself. Assign the exported scenes, audio players, and collision shape in the Inspector. StageMusic is a sibling of the encounter.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 | |
The encounter's two coroutines are both owned by the Encounter node. If the encounter leaves the tree at any point, its signal collectors, frame wait, enemy waits, and remaining sequence are all cancelled automatically. The enemies and coins are added to the encounter's parent, so the reward can remain after the encounter node removes itself.
Resource loading
ResourceLoader.awaitLoad(path, typeHint = "", cacheMode = REUSE) returns Resource?. An uncached load runs on the worker thread pool; a resource already in the cache is returned immediately, without suspending. awaitLoadAs<R> supplies a typed result; a load failure returns null.