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.

(gif: demonstration)


how does it work?


node hierarchy


(image: node hierarchy - Root is a node named Main. It's children are TextureRect BG, AnimatedSprite Stoplight, Sprite WalkButton, and a Label. Stoplight's child is a Sprite. WalkButton's child is a TextureButton.)


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


(image: the AnimatedSprite Stoplight has 4 animations - default (which is no light), green, red, and yellow.)

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
(image: Main script.)

Label.gd - code available on GitLab
(image: Label script.)


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.