Skip to content

Coroutines and timers

Every event runs as a small program of its own, called a coroutine. A coroutine can stop in the middle and let other events run, then continue later. The engine runs one coroutine at a time and never interrupts it, except where it stops by itself.

sleep(seconds) stops the whole object for that time.

  • The object’s pending setTimer is lost: the onTimeout that was waiting does not fire after the sleep. Call setTimer again to restart it. The compiler warns (W-SLEEP-WITH-TIMER) when a script uses both.
  • Events from scheduleevent still run during the sleep.
  • Triggers also run during the sleep. Engine events for the object wait and run when the sleep ends, in the order they arrived (OQ-VM-1).
  • An object has one timer for sleep and setTimer. A setTimer on the object while it sleeps, or a sleep in another of its functions, drops the sleeping function: it never resumes. Do not mix sleep with setTimer or with other sleeping events of the same object.
  • Other objects, the server, and the client are never blocked.
// time: 1
function onCreated() {
echo("before");
sleep(0.5);
echo("after");
// expect: before
// expect: after
}

Run this example in the playground

waitfor(object, "eventName", timeout) stops only the function that calls it. The object keeps handling its other events and its timer.

It resumes when the event is raised on that object, or when the timeout ends. It gives 1 when the event arrived and 0 on a timeout (OQ-VM-2). The waiting function takes the event, so the object’s own handler for it does not run. A timeout of 0 or less gives 0 at once (OQ-VM-3). The name may be written with or without on, and ignores case.

function onCreated() {
this.trigger("Ready", "go");
temp.got = waitfor(this, "onReady", 1);
echo("waited " @ temp.got);
// expect: waited 1
}
function onReady(what) {
echo("ready " @ what);
}

Run this example in the playground

A function marked async can use await. Calling it starts it at once, runs it until it first stops, and gives a task object. await task waits for the result.

// time: 1
async function slowDouble(x) {
sleep(0.2);
return x * 2;
}
async function onCreated() {
temp.value = await slowDouble(21);
echo(temp.value);
// expect: 42
}

Run this example in the playground

  • await stops only the current function, like waitfor. It is not like sleep.
  • await(expression, seconds) sets a time limit. A request that runs out of time fails with the message await timed out.
  • await on something that is not a task or request gives the value at once.
  • await works on requestsql, requestcurl, a sent TCURLRequest, findpathasync, triggerserver, and triggerclient. For a request object the result is the finished request, with any failure in its error field. For a trigger the result is the value the other side returned.
  • A failed await raises an error that try can catch. Without try, it reports R-AWAIT and gives empty.
  • Removing the object that owns a stopped function cancels the function. Its finally blocks do not run.

An object has one timer. setTimer(seconds) makes one onTimeout() at that time and replaces any timer that was waiting. setTimer(0) cancels it. The loop goes on only while onTimeout calls setTimer again. Timers stop when the object is destroyed.

// time: 1
function onCreated() {
this.count = 0;
setTimer(0.25);
}
function onTimeout() {
this.count++;
echo("tick " @ this.count);
if (this.count < 3) {
setTimer(0.25);
}
// expect: tick 1
// expect: tick 2
// expect: tick 3
}

Run this example in the playground

Use the slowest timer that works: one second for status updates, and 0.05 seconds only for animation and movement. Prefer events such as onPlayerEnters over checking in a timer loop.

scheduleevent(delay, "Name", args...) runs onName(args...) once, after the delay. An object can have any number of them. this.cancelevents("Name") removes the waiting ones with that name.

// time: 1
function onCreated() {
scheduleevent(0.5, "Later", "x");
}
function onLater(what) {
echo("later " @ what);
// expect: later x
}

Run this example in the playground

Timers and scheduled events that fall due run in order of their time, and equal times run in the order they were set. One set during a step runs in the next step at the earliest. The shortest delay is one tick on the server (0.02 seconds at the default rate) and one frame on the client (about 0.0167 seconds). The engine does not copy the timing slack of older servers.

obj.trigger("Event", args...) queues the call onEvent(args...) and returns at once. Code after the call runs first. The queue is run in order when the current event ends or stops. More than 10,000 events in one pass are postponed, and R-TRIGGER-FLOOD is reported.

Set this.keepalive = true to receive:

  • onUpdate(), on the client only, once for each drawn frame.
  • onFixedUpdate(), on both sides, at a fixed rate (50 times per second by default). On the client it can run up to 5 times in one frame to catch up.

An event is not started again while the last one is still stopped. A sleep in either event blocks the object, and the compiler warns about it (W-SLEEP-IN-FRAME-EVENT).

Engine version 0.1.0. Built 2026-11-18.