Time

A module singleton (global functions only, no handle) for reading frame and fixed-step timing.
Delta values come in scaled (multiplied by TimeScale) and unscaled forms; a separate
group describes the deterministic fixed-step physics loop. All values are read-only queries except
the three Set* setters, which clamp their inputs (see below).

Functions

Time.DeltaTime( ) : number
Scaled seconds elapsed since the previous frame (unscaled × TimeScale), pre-clamped to
MaximumDeltaTime. Inside a fixed step (while IsFixedUpdate() is true) it returns
FixedDeltaTime instead — so the same call is correct whether run from Update or FixedUpdate.

Time.UnscaledDeltaTime( ) : number
Frame delta ignoring TimeScale — raw and unclamped. MaximumDeltaTime does not apply to
it (only DeltaTime is clamped).

Time.SmoothDeltaTime( ) : number
An exponentially-smoothed (EMA) frame delta — steadier than DeltaTime for animation.

Time.Time( ) : number
Scaled seconds since startup (accumulated DeltaTime).

Time.UnscaledTime( ) : number
Unscaled seconds since startup — accumulates the clamped unscaled delta (each frame capped at
MaximumDeltaTime), so after a stall it is not the running sum of UnscaledDeltaTime.

Time.RealtimeSinceStartup( ) : number
Drift-free wall-clock seconds since startup, read from an Instant. Never scaled, smoothed, or
clamped — it keeps advancing even when TimeScale is 0.

Time.FrameCount( ) : integer
Number of frames rendered since startup.

Time.FPS( ) : number
The smoothed frames-per-second display value, recomputed on roughly half-second windows (so it is
stable to read every frame, not a raw 1/DeltaTime).

Time.FixedStepCount( ) : integer
Number of fixed steps the accumulator will run this frame — not a running total. It is 2
at 60 fps with the default 1/120 step, 0 or 1 at 144 fps, 4 at 30 fps, and is capped by
the spiral-of-death guard (≤ 8 with the default settings) after a stall.

Time.CurrentFixedStep( ) : integer
The 0-based index of the fixed step currently executing within this frame’s batch (ranges
0 .. FixedStepCount-1); set by the app frame loop before each Script.FixedUpdate.

Time.IsFixedUpdate( ) : boolean
true while the engine is dispatching fixed-update callbacks (i.e. inside a fixed step).

Properties (get / set)

Setters return void and silently clamp — they never raise a Lua error. Non-finite inputs (NaN,
±inf) are rejected outright, leaving the previous value unchanged (a NaN would otherwise poison the
physics accumulator).

TimeScale

Time.TimeScale( ) : number — the global time-scale multiplier (1.0 = real time, 0.0 = paused).
Time.SetTimeScale( number scale ) : void — scales DeltaTime/Time. Clamped to [0.0, 100.0] (lib.rs:316-327), so negatives become 0; 0 pauses scaled time while
RealtimeSinceStartup keeps running.

MaximumDeltaTime

Time.MaximumDeltaTime( ) : number — the frame-delta clamp ceiling, in seconds.
Time.SetMaximumDeltaTime( number seconds ) : void — caps DeltaTime (and the times derived
from it) to avoid a spiral-of-death after a stall; it does not clamp the raw UnscaledDeltaTime. Clamped to [0.001, 1.0] (lib.rs:361-372).

FixedDeltaTime

Time.FixedDeltaTime( ) : number — the fixed-step timestep, in seconds (default 1/120).
Time.SetFixedDeltaTime( number seconds ) : void — sets the deterministic physics timestep.
Clamped to [1/480, 1/30] (≈ 0.00208–0.03333 s, i.e. 30–480 Hz) (lib.rs:333-344).
Because the fixed-point physics runs lockstep off this cadence, treat it as a startup setting —
changing it mid-session changes the simulation (and its determinism hash).

Example

function Script.Update(self)
    -- Toggle pause without stopping wall-clock time (RealtimeSinceStartup keeps counting).
    if Input.KeyDown("pause") then
        Time.SetTimeScale(Time.TimeScale() > 0.0 and 0.0 or 1.0)
    end
    self.label:SetText(string.format("%.1fs  (%.0f fps)", Time.Time(), Time.FPS()))
end