coroutines in godot engine
september 17, 2020
#programming
Coroutines are functions that, instead of running to completion, can yield until certain criteria are met. Godot Engine supports coroutines through yield ( Object object=null, String signal=""), resume, and the GDScriptFunctionState object.
why use a coroutine?
Coroutines allow for scripted game scenarios that respond dynamically to the player and the changing game world. They let you bounce between functions, step-by-step, and respond to interruptions. This means functions can be automatically called at the completion of other functions, animations, player actions, in-game events, or timers. Add in interruptions and conditionals, and you have a tool for building a responsive game world.
stoplight example
As a basic example of coroutines in Godot Engine, I made a stoplight. Follow along with my code on GitLab.
In my example, the light changes every few seconds, going from green, yellow, then finally red. The light changes immediately if the Walk Button is pressed. This project demonstrates methods that can wait, resume, and be affected through player action.
how does it work?
node hierarchy
I have a TextureRect background, an AnimatedSprite stoplight, a Sprite walk button with a TextureButton, and a label for displaying a timer. Since this is a simple example, most of the code is attached to the root. It's better to have code closer to where it's being used and to watch your separation of concerns in real projects, though.
animation
The light is changed by setting its animation to one of these options. Each is one-frame - just the stoplight with the one or none of the lights colored in.
the code
This project has two scripts: Main.gd, which is attached to the root node, and Label.gd, which is attached to the Label.
Main.gd - code available on GitLab
Label.gd - code available on GitLab
how the code works
At _ready()
, wait()
is assigned to the GDScriptFunctionState result
and is called for the first color, green. _ready()
yields until the given function wait()
is completed.
The wait method yields for the given amount of seconds then sets the stoplight to the given color.
At wait()
's completion, _ready()
calls wait()
for yellow, then red. Each is called one at a time, waiting for the color to complete before moving on.
interrupting the stoplight
The Wait Button interrupts the wait times between colors. Before _ready()
yields, it connects the 'pressed'
signal on the Wait Button.
If the Wait Button is clicked during wait()
's yield, the GDScriptFunctionState result
resumes immediately, ignoring wait()
's yield timer. This time, result
has a string arg 'interrupted on green'
, so it will print the result, change the stoplight's color, then print 'done: green'
. The wait
method is complete, so _ready()
resumes and calls wait()
for the next color.
applications
The outcomes in this example be swapped out for anything. I use coroutines in blessfrey's skills to manage the flow of phases from activation, different phases of effects, cooldown, and interactions with any counters. I also use it in the basic weapon attack so the character continuously swings at the rate of his attack speed until he cancels, uses a skill, or moves. It could also be used for something like cars that stop and honk when the player walks in front of them and drive off once the path is clear.
Coroutines enable lots of practical ways to improve the flow and interactivity of your game, so just keep experimenting.