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