1.08 - Timers

Timers allow you to call a function in the future with a specified delay.

Here is a first example of use:

-- Play sound "secret" in one second.
local function play_secret_sound()
  sol.audio.play_sound("secret")
end

sol.timer.start(1000, play_secret_sound)

Shorter version to do the same thing:

-- Equivalent code using an anonymous function.
sol.timer.start(1000, function()
  sol.audio.play_sound("secret")
end)

You can repeat a timer by returning true from your function:

-- Call a function every second.
sol.timer.start(1000, function()
  sol.audio.play_sound("danger")
  return true  -- To call the timer again (with the same delay).
end)

To make a timer that repeats itself 10 times, just return false after 10 calls:

-- Call a function ten times, with one second between each call.
local num_calls = 0
sol.timer.start(1000, function()
  sol.audio.play_sound("danger")
  num_calls = num_calls + 1
  return num_calls < 10
end)

It is possible to restrict the lifetime of a timer to a context, like the game, the map or an enemy:

-- Enemy that shoots a fireball every 5 seconds until it is killed.
sol.timer.start(your_enemy, 5000, function()
  sol.audio.play_sound("attack_fireball")
  map:create_enemy(...)  -- Code that creates the fireball.
  return true  -- Repeat the timer.
end)

Setting the context to an enemy ensures that when the enemy is killed, the timer is canceled. Otherwise, the callback function would still be called: in this example, you would hear the "attack_fireball" sound and the fireball would be created even if the enemy is killed in the meantime.

Functions of sol.timer

sol.timer.start([context], delay, callback)

Sets a function to be called after a delay.

If the delay is set to zero, the function is called immediately.

Remarks
When they are created, map timers, map entity timers and item timers are initially suspended if a dialog is active. After that, they get automatically suspended and unsuspended when the map is suspended or unsuspended. This default behavior is suited for most use cases, but if you want to change it, you can use timer:set_suspended() and timer:set_suspended_with_map().

sol.timer.stop_all(context)

Cancels all timers that are currently running in a context.

This function is equivalent to calling timer:stop() on each timer of the context. It may allow you to avoid to store explicitly all your timers.

Remarks
Canceling timers by hand may be tedious and error-prone. In lots of cases, you can simply pass a context parameter to sol.timer.start() in order to restrict the lifetime of your timer to some other object.

Methods of the type timer

timer:stop()

Cancels this timer.

If the timer was already finished or canceled, nothing happens.

Remarks
Canceling timers by hand may be tedious and error-prone. In lots of cases, you can simply pass a context parameter to sol.timer.start() in order to restrict the lifetime of your timer to some other object.

timer:is_with_sound()

Returns whether a clock sound is played repeatedly during this timer.

timer:set_with_sound(with_sound)

Sets whether a clock sound is played repeatedly during this timer.

timer:is_suspended()

Returns whether this timer is currently suspended.

timer:set_suspended([suspended])

Returns whether this timer is currently suspended.

timer:is_suspended_with_map()

Returns whether this timer gets automatically suspended when the map is suspended.

timer:set_suspended_with_map([suspended_with_map])

Sets whether this timer should automatically be suspended when the map gets suspended.

The map is suspended by the engine in a few cases, like when the game is paused, when there is a dialog or when the camera is being moved by a script. When this happens, all map entities stop moving and most sprites stop their animation. With this setting, you can choose whether your timer gets suspended too.

By default, map timers, and item timers are suspended with the map. Entity timers are more complex: an entity (and its timers) also get suspended when the entity gets disabled. You should not use this function on entity timers.

Remarks
Even when this setting is set to true, you can override its behavior by calling timer:set_suspended().

timer:get_remaining_time()

Returns the remaining time of this timer.

timer:set_remaining_time(remaining_time)

Changes the remaining time of this timer.

This function has no effect if the timer is already finished.

Remarks
When a timer is repeated (that is, if its callback returns true), the timer gets rescheduled with its initial delay again, no matter if you called this function in the meantime.