Character Scripts

Now for what games use coroutines for most: scripts for characters. Each character gets a coroutine that describes what it does, from start to end, one turn after another. The game runs in turns (on our farm, a turn is one day): every turn, it resumes each character's coroutine once, and each character does one step and yields.

Hugo the trader has a route with three stops. Bella the cow has the same routine every two days, so her script is a loop that never ends:

-- Who does what on Sunflower Farm
local function hugo()
    print("Hugo is at the market.")
    coroutine.yield()
    print("Hugo visits Sunflower Farm.")
    coroutine.yield()
    print("Hugo travels to the city.")
end

local function bella()
    while true do
        print("Bella grazes in the meadow.")
        coroutine.yield()
        print("Bella rests in the barn.")
        coroutine.yield()
    end
end

local characters = {coroutine.create(hugo), coroutine.create(bella)}

for day = 1, 4 do
    print("Day " .. day)
    for _, character in ipairs(characters) do
        if coroutine.status(character) ~= "dead" then
            coroutine.resume(character)
        end
    end
end

This prints:

Day 1
Hugo is at the market.
Bella grazes in the meadow.
Day 2
Hugo visits Sunflower Farm.
Bella rests in the barn.
Day 3
Hugo travels to the city.
Bella grazes in the meadow.
Day 4
Bella rests in the barn.

The coroutines are in a list, so the game loop doesn't care how many characters there are: it gives each of them a turn, in the order of the list. The characters take turns; they never run at the same time. Each one runs until its yield, and only then does the next one get its turn. On day 4, Hugo's script has already ended (dead), so the loop skips him.

Why coroutines? Without them, Hugo would need a variable that remembers his step, and every day an if step == 1 then … elseif step == 2 then …, and every character would need such variables of its own. A coroutine remembers where it stopped, and its local variables too, so each script reads from top to bottom like a story: first this, then wait, then that. Bella's script shows it: a loop with two steps, nothing more.