timer

Timers use a per-script clock starting at 0 on load. The clock advances by elapsed real time between rendered frames and stops while no frame is rendered.

timer.delayCopy Anchor Link

timer.delay(seconds, fn)

Schedules one call to fn() after seconds.

Returns: numeric timer ID.

Errors: seconds is negative or non-finite, or fn is not a function.

timer.everyCopy Anchor Link

timer.every(seconds, fn)

Schedules repeated calls to fn(), first after seconds. An interval of 0 runs once per frame. Validation is the same as for timer.delay.

Returns: numeric timer ID.

timer.cancelCopy Anchor Link

timer.cancel(id)

Removes a pending timer. It is safe to cancel a timer from its own function.

Returns: true if removed, false if the timer no longer exists. A one-shot timer is already removed when it fires.

timer.realtimeCopy Anchor Link

timer.realtime()

Returns: seconds elapsed on the script's timer clock.

Scheduling rulesCopy Anchor Link

Due timers run at the start of the frame, earliest first. A late repeating timer runs once, without replaying missed intervals. For example, after a two-second pause, a 0.1-second timer runs once and schedules its next call 0.1 seconds later. Intervals are therefore frame-aligned and may drift; use timer.realtime() to measure elapsed time.

A timer created by another timer cannot run until the next frame. A failing timer is removed and reported as a disabled callback. All timers are removed when the script unloads.

local count = 0
local id

id = timer.every(1, function()
    count = count + 1
    print('tick ' .. count)
    if count == 5 then
        timer.cancel(id)
    end
end)