time

Updated 4 September 2026

The time namespace — 6 functions.

time/deltaTime

time.deltaTime() -> number

Seconds the frame being run covers — the same value a component's update(dt) receives, reachable from code that was not handed one. Scaled by time.timeScale().

Returns number — Seconds this frame covers

time/drawnFrameCount

time.drawnFrameCount() -> number

Frames the RENDERER has drawn. The engine runs a frame whether or not anything wants a picture of it, and a headless renderer declines the ones nothing is consuming, so this is lower than time.frameCount() and the difference is what was declined. Anything read off what the renderer produced — a capture, a camera observation, a readback, a per-frame cost — belongs to this count, and task.waitDrawnFrames(n) waits n of them.

Returns number — Frames the renderer has drawn

time/frameCount

time.frameCount() -> number

Frames the engine has run: 0 when the process starts, one higher for each frame the loop begins, and the same value for the whole of that frame. This is the engine's ONE frame number — task.waitFrames(n) is deadlined on it, so local a = time.frameCount() task.waitFrames(n) leaves time.frameCount() - a == n exactly, however long those frames took. A frame runs whether or not anything wants a picture of it, which is why time.drawnFrameCount() is a separate and smaller count.

Returns number — Frames the engine has run

time/realtime

time.realtime() -> number

Seconds since the engine started, read at the moment of the call. Advances within a frame, so two reads either side of some work report how long that work took. Unaffected by time.timeScale(). One epoch on every platform. For deciding WHEN something happens in gameplay use time.time(), which every script in the frame agrees on.

Returns number — Seconds since the engine started, right now

time/time

time.time() -> number

Seconds since the engine started, stamped once at the top of this frame. Every script in a frame reads the same value, so the frame's logic is consistent with itself — this is the clock to drive gameplay and animation from. Because it holds still for the whole frame it cannot measure a duration INSIDE one: two reads with no yield between them return the same number, and time.realtime() is the live clock for that.

Returns number — Seconds since the engine started, as of this frame

See also: time/realtime · time/deltaTime

time/timeScale

time.timeScale() -> number

How fast time is running: 1 is real time, 0.5 half speed, 0 frozen, 2 double. It scales how fast the fixed-timestep accumulator fills and the delta update(dt) receives — never the fixed step size itself, so physics stays smooth at low scales. timescale.set(value) changes it. time.realtime() ignores it.

Returns number — The current time scale