Library Modules

These modules are not loaded by default. Use require() to load them.

class Timer
class ctor Timer(
    timeout: integer,
    singleshot: boolean,
    callback: function,
    ...: any
): Timer

Timer class for delayed and periodic execution. Must be loaded with require("timer").

Loading this module hooks Timer.update() into dash.update(), so all active timers are automatically processed each frame without needing to call Timer.update() separately.

Timers can be single-shot (fire once and stop) or repeating (fire repeatedly at the given interval).

Extra arguments passed to the constructor or set_callback are forwarded to the callback function when it fires.

local Timer = require("timer")

-- Single-shot timer: prints after 2 seconds
local t1 = Timer(2000, true, function(msg)
    print("Fired:", msg)
end, "hello")
t1:start()

-- Repeating timer: fires every 500ms
local t2 = Timer(500, false, function()
    print("tick", dash.uptime())
end)
t2:start()

while true do
    dash.update()  -- Timer.update() is called automatically
end

Create a new Timer.

Parameters:

  • timeout (integer) – timeout in milliseconds

  • singleshot (boolean) – true for single-shot, false for repeating

  • callback (function) – function called on timeout

  • ... (any) – optional arguments forwarded to the callback

set_callback(self, callback: function, ...: any)

Set the callback function. Replaces any previously set callback. Extra arguments are forwarded to the callback when the timer fires.

Parameters:

  • callback (function) – function called on timeout

  • ... (any) – optional arguments forwarded to the callback

set_timeout(self, timeout: integer)

Set the timeout interval. If the timer is running, the new timeout takes effect on the next cycle. Pass nil to stop a running timer.

Parameters:

timeout (integer) – timeout in milliseconds

set_singleshot(self, singleshot: boolean)

Set whether the timer is single-shot.

Parameters:

singleshot (boolean) – true to fire once and stop, false to repeat

start(self, timeout?: integer)

Start the timer. If a timeout is given, it overrides the previously set value. If no timeout was ever set, the timer will not start.

Parameters:

timeout? (integer) – timeout in milliseconds (default: previously set value)

stop(self)

Stop the timer. The timer can be restarted later with start().

staticmethod update()

Process all active timers. Called automatically by dash.update() when the timer module is loaded. Fires callbacks for all timers that have reached their timeout, and restarts repeating timers for the next cycle.