Timers allow you to set a delay and a callback to be called when the timer completes.
The timers created with this API are updated with the collection timer where they
are created. If you pause or speed up the collection (using set_time_step
) it will
also affect the new timer.
Version: stable
FUNCTIONS | |
---|---|
timer.cancel() | cancel a timer |
timer.delay() | create a timer |
timer.get_info() | get information about timer |
timer.trigger() | trigger a callback |
CONSTANTS | |
---|---|
timer.INVALID_TIMER_HANDLE | Indicates an invalid timer handle |
timer.cancel(handle)
You may cancel a timer from inside a timer callback. Cancelling a timer that is already executed or cancelled is safe.
PARAMETERS
handle |
integer |
the timer handle returned by timer.delay() |
RETURNS
true |
boolean | if the timer was active, false if the timer is already cancelled / complete |
EXAMPLES
self.handle = timer.delay(1, true, function() print("print every second") end)
...
local result = timer.cancel(self.handle)
if not result then
print("the timer is already cancelled")
end
timer.delay(delay,repeating,callback)
Adds a timer and returns a unique handle. You may create more timers from inside a timer callback. Using a delay of 0 will result in a timer that triggers at the next frame just before script update functions. If you want a timer that triggers on each frame, set delay to 0.0f and repeat to true. Timers created within a script will automatically die when the script is deleted.
PARAMETERS
delay |
number |
time interval in seconds |
repeating |
boolean |
true = repeat timer until cancel, false = one-shot timer |
callback |
function(self, handle, time_elapsed) |
timer callback function
|
RETURNS
handle |
integer | identifier for the create timer, returns timer.INVALID_TIMER_HANDLE if the timer can not be created |
EXAMPLES
A simple one-shot timertimer.delay(1, false, function() print("print in one second") end)
local function call_every_second(self, handle, time_elapsed)
self.counter = self.counter + 1
print("Call #", self.counter)
if self.counter == 10 then
timer.cancel(handle) -- cancel timer after 10 calls
end
end
self.counter = 0
timer.delay(1, true, call_every_second)
timer.get_info(handle)
Get information about timer.
PARAMETERS
handle |
integer |
the timer handle returned by timer.delay() |
RETURNS
data |
table, nil | table or nil if timer is cancelled/completed. table with data in the following fields:
|
EXAMPLES
self.handle = timer.delay(1, true, function() print("print every second") end)
...
local result = timer.get_info(self.handle)
if not result then
print("the timer is already cancelled or complete")
else
pprint(result) -- delay, time_remaining, repeating
end
timer.trigger(handle)
Manual triggering a callback for a timer.
PARAMETERS
handle |
integer |
the timer handle returned by timer.delay() |
RETURNS
true |
boolean | if the timer was active, false if the timer is already cancelled / complete |
EXAMPLES
self.handle = timer.delay(1, true, function() print("print every second or manually by timer.trigger") end)
...
local result = timer.trigger(self.handle)
if not result then
print("the timer is already cancelled or complete")
end
Indicates an invalid timer handle