Defold C

Defold C++

dmGameObject

dmGameSystem

dmGraphics

dmResource

dmScript

Defold Lua

Extension

firebase

Version

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: alpha

TYPES
timer_handle	Timer handle

RECORDS
timer.info	Timer information

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

Types

timer_handle

timer_handle = number

An opaque numeric identifier returned by timer.delay. Pass it to timer.cancel, timer.trigger, or timer.get_info to control the timer. Timers are owned by the script that created them and are removed automatically when the script is deleted. A failed creation returns timer.INVALID_TIMER_HANDLE.

EXAMPLES

local handle = timer.delay(1, true, function()
    print("tick")
end)

timer.cancel(handle)

Records

timer.info

Timer information

FIELDS

`time_remaining`	`number`	Time remaining until the next callback.
`delay`	`number`	Timer interval.
`repeating`	`boolean`	Whether the timer repeats until cancelled.

Functions

timer.cancel()

timer.cancel(handle:timer_handle)→cancelled:boolean

You may cancel a timer from inside a timer callback. Cancelling a timer that is already executed or cancelled is safe.

PARAMETERS

handle timer_handle the timer handle returned by timer.delay()

RETURNS

cancelled boolean true if the timer was active and cancelled, false if the timer was already cancelled or complete

EXAMPLES

self.handle = timer.delay(1, true, function() print("print every second") end)
...
local cancelled = timer.cancel(self.handle)
if not cancelled then
   print("the timer is already cancelled")
end

timer.delay()

timer.delay(delay:number, repeating:boolean, callback:fun(self:script_instance, handle:timer_handle, time_elapsed:number))→handle:timer_handle

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:script_instance, handle:timer_handle, time_elapsed:number)`	timer callback function `self:script_instance` The current script instance `handle:timer_handle` 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 timer_handle 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:timer_handle)→data:timer.info|nil

Get information about timer.

PARAMETERS

handle timer_handle the timer handle returned by timer.delay()

RETURNS

data timer.info
nil timer information, or nil if the timer is cancelled or complete

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:timer_handle)→triggered:boolean

Manual triggering a callback for a timer.

PARAMETERS

handle timer_handle the timer handle returned by timer.delay()

RETURNS

triggered boolean true if the timer was active and triggered, false if the timer was already cancelled or complete

EXAMPLES

self.handle = timer.delay(1, true, function() print("print every second or manually by timer.trigger") end)
...
local triggered = timer.trigger(self.handle)
if not triggered then
   print("the timer is already cancelled or complete")
end

Constants

timer.INVALID_TIMER_HANDLE

Indicates an invalid timer handle

value timer_handle