Skip to content

Petrichor.Task#

Petrichor.Task adds async/await on top of Luau coroutines. Timers, network results, and deferred work resume on the main Luau thread during petrichor_tick, the same thread that runs mod tick and hooks.

Background threads can do I/O. Luau only runs from the task scheduler tick, which keeps the VM safe.

Loading#

local Task = require("Petrichor.Task")

import * as Task from "Petrichor.Task"

How it works#

  1. Task.async(fn) returns a starter function.
  2. Call starter() to run the coroutine.
  3. Inside the body, Task.await(thunk) waits until the thunk calls step(...) with resume values.
  4. Built-in thunks: Task.defer(), Task.delay(seconds).

Errors in the async body are logged with the async tag and include a Luau stack trace. They do not crash the game.

API#

Task.async(func) -> starter#

Builds a coroutine from func and returns starter. Call starter() to start it.

Task.async(function()
    Task.await(Task.delay(1.0))
    Log.info("my-mod", "one second later")
end)()

import * as Log from "Petrichor.Log"

Task.async(() => {
    Task.await(Task.delay(1.0))
    Log.info("my-mod", "one second later")
})()

Task.await(thunk) -> ...#

Pauses until thunk(step) calls step(...). Those arguments become the return values of await.

Task.await(Task.defer())  -- resume on the next task tick

Task.await(Task.defer())  // resume on the next task tick

Task.defer() -> thunk#

Resume on the next task batch, same thread, after the current hook or mod code returns.

Task.delay(seconds) -> thunk#

Resume after seconds of game time. Uses the real delta passed to petrichor_tick (Courage supplies DELTA_TIME / 30.0f).

Task.sleep(seconds) -> ...#

Same as Task.await(Task.delay(seconds)).

Task.on_hook does not exist yet. Register hooks in init and resume async work with Task.defer() or your own thunk.

Execution order#

Each frame:

petrichor::async::tick(L, delta)   -- timers, deferred steps, net/hook resumes
mod instance:tick(delta)             -- your mod tick methods

Task work runs before mod tick handlers.

See also#