PICO-8 Wiki
coresume( cor, [...] )
Starts a coroutine, or resumes a suspended coroutine.
The coroutine, as created by cocreate().

The arguments to pass to the coroutine's function or the coroutine's subsequent yields.

A coroutine is a special kind of function that can yield control back to the caller without completely exiting. The caller can then resume the coroutine as many times as needed until the function exits.

The coresume() function starts or resumes a coroutine created by cocreate(). Control returns to the coroutine function until the function yields or exits.

coresume() returns true if the given coroutine was active (suspended) when coresume() was called, or false if it was given a dead coroutine (and no code was executed by resuming). If a resumed coroutine function exits (rather than yields), the coroutine goes from suspended to dead, and a subsequent call to coresume() with the same coroutine will return false. It is more typical to use the costatus() function to test the status of a coroutine, but the return value from coresume() may be used instead.

In the event that coresume() returns false, it may also return a second value containing a string describing an exception that caused the routine to die unexpectedly, e.g. "attempt to index a nil value". A full stack trace can also be obtained by passing the dead coroutine to trace(). In fact, the code below is a very simple way to stop() with full stack trace when a coroutine dies unexpectedly:

local active, exception = coresume(co)
if exception then
  stop(trace(co, exception))

PICO-8's coresume() does not return a value from the coroutine function, nor can yield() accept a value. If the function exits by returning a value, this value is ignored. (Lua and other languages support yielding and returning values from coroutines, but PICO-8 does not.)

coresume() may pass extra arguments to the coroutine. These arguments will be mapped to the coroutine's function arguments on the first call, and will be used as return values for yield() on subsequent calls.


function foo(a, b, c)
  a, _, c = yield()

local thread = cocreate(foo)
coresume(thread, 1, 2, 3) --> prints: 1 2 3
coresume(thread, 4, 5, 6) --> prints: 4 5 6

See cocreate() for a general example.

See also[]