---
title: "time"
description: "The time namespace — the engine's Luau API reference for time."
section: "API Reference"
slug: "api-time"
canonical: "https://origozero.ai/docs/api-time"
updated: "2026-09-04T19:42:51.302770347+00:00"
tags: ["api", "reference"]
---

# time

The `time` namespace — 6 functions.

## time/deltaTime {#time-deltatime}

```lua
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

See also: [`time/timeScale`](api-time)

## time/drawnFrameCount {#time-drawnframecount}

```lua
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

See also: [`time/frameCount`](api-time) · [`task/waitDrawnFrames`](api-task)

## time/frameCount {#time-framecount}

```lua
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

See also: [`time/drawnFrameCount`](api-time) · [`task/waitFrames`](api-task)

## time/realtime {#time-realtime}

```lua
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

See also: [`time/time`](api-time)

## time/time {#time-time}

```lua
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`](api-time) · [`time/deltaTime`](api-time)

## time/timeScale {#time-timescale}

```lua
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

See also: [`time/deltaTime`](api-time)