time

Updated October 20, 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(), as the seconds task.wait counts are, so a script driving motion from this runs at the rate the rest of the world runs at, whoever set that rate. A delta a script computes for itself from time.realtime() is on the wall clock instead, and is multiplied by time.timeScale() to match.

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. Every frame the renderer drew counts, so a reading taken across a window answers whether it kept producing frames. Anything read off what the renderer produced (a capture, a camera observation, a readback, a per-frame cost) belongs to this count. task.waitDrawnFrames(n) waits n frames of it drawn with every pipeline the scene asked for in place, so a frame that drew a placeholder while a material's pipeline was still building counts here and is waited past there; task.waitDrawnFrames(n, { settled = false }) waits n frames of this count itself.

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. This is the clock task.waitRealtime counts on, so a wall-clock wait and a wall-clock measurement of it agree.

Returns number — Seconds since the engine started, right now

See also: time/time · task/waitRealtime

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. It reads the WALL clock: time.timeScale() does not reach it and engine.paused does not stop it, so across a paused span this advances by the whole span while update(dt) receives nothing. The clock gameplay and animation run on is the dt a lifecycle callback receives, and task.wait counts in that same scaled clock; this reading answers WHEN something happened. 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. getTime() is the same reading under the prelude's own name. The engine keeps stepping between tool calls, so this advances across the real seconds between two of them; the core/engine guide's "How fast time passes" has the whole model.

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, the delta update(dt) receives, and the seconds task.wait and task.delay count, never the fixed step size itself, so physics stays smooth at low scales. So a task.wait(1) is four wall-clock seconds at 0.25 and never comes due at 0; task.waitRealtime(1) is one wall-clock second at every scale. engine.timeScale = value changes it, and it is one number for the whole process: every agent driving this engine shares it, engine.timeScaleOwner names who it answers to and engine.holdTimeScale takes it for a named owner so a write from anywhere else is refused while the hold stands. time.realtime() ignores it, so a delta computed from that clock is multiplied by this to run at the rate the world is running at.

Returns number — The current time scale