Timer API documentation

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

Functions

timer.cancel()

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()

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 `self` object The current object `handle` integer The handle of the timer `time_elapsed` number The elapsed time - on first trigger it is time since timer.delay call, otherwise time since last trigger

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 timer

timer.delay(1, false, function() print("print in one second") end)

Repetitive timer which canceled after 10 calls

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()

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:

time_remaining: number Time remaining until the next time a timer.delay() fires.
delay: number Time interval.
repeating: boolean true = repeat timer until cancel, false = one-shot timer.

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()

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

Constants

timer.INVALID_TIMER_HANDLE

Indicates an invalid timer handle