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
setTimeris lost: theonTimeoutthat was waiting does not fire after the sleep. CallsetTimeragain to restart it. The compiler warns (W-SLEEP-WITH-TIMER) when a script uses both. - Events from
scheduleeventstill 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
sleepandsetTimer. AsetTimeron the object while it sleeps, or asleepin another of its functions, drops the sleeping function: it never resumes. Do not mixsleepwithsetTimeror with other sleeping events of the same object. - Other objects, the server, and the client are never blocked.
// time: 1function onCreated() { echo("before"); sleep(0.5); echo("after"); // expect: before // expect: after}Run this example in the playground
waitfor
Section titled “waitfor”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
async and await (extension)
Section titled “async and await (extension)”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: 1async 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
awaitstops only the current function, likewaitfor. It is not likesleep.await(expression, seconds)sets a time limit. A request that runs out of time fails with the messageawait timed out.awaiton something that is not a task or request gives the value at once.awaitworks onrequestsql,requestcurl, a sentTCURLRequest,findpathasync,triggerserver, andtriggerclient. For a request object the result is the finished request, with any failure in itserrorfield. For a trigger the result is the value the other side returned.- A failed
awaitraises an error thattrycan catch. Withouttry, it reportsR-AWAITand gives empty. - Removing the object that owns a stopped function cancels the function. Its
finallyblocks do not run.
setTimer
Section titled “setTimer”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: 1function 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
Section titled “scheduleevent”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: 1function 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.
trigger
Section titled “trigger”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.
Frame and tick events
Section titled “Frame and tick events”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.