Timer

Timers provide an easy way to execute functions after a specific time delay (timeout) or at recurring intervals.

info

Under the hood, the Timer API is entirely based on the Thread API. Therefore, timers share the exact same characteristics: they do not block the game's main process, they run sequentially, meaning you don't have to worry about thread safety, and a callback that runs for too long is subject to the same limits as a thread.

A timer ID is the ID of the thread behind it. Stop a timer with Timer.Kill all the same: Thread.Kill ends the thread but leaves the timer registered, so Timer.GetRemaining and friends keep reporting a timer that no longer runs.

Quick Reference

Name	Type	Description
SetInterval	Shared	Sets a recurring timer.
SetTimeout	Shared	Executes a function once after a specified delay.
Kill	Shared	Stops and removes a timer immediately.
IsAlive	Shared	Checks if a specific timer is currently registered and active.
GetRemaining	Shared	Returns the milliseconds remaining until the next execution.
GetRepeatsLeft	Shared	Returns the number of remaining executions for finite timers.
GetState	Shared	Returns the current state of the timer as a string.

---

Shared Functions

SetInterval

Sets a recurring timer. The returned ID is the ID of the underlying thread and is what every other Timer function expects.

int timerId = Timer.SetInterval(int intervalMs, function func, int count, any ...)

info

count is the number of executions. Pass 0 (or nothing) for a timer that repeats forever. Any further arguments are passed through to func on every execution.

warning

The first execution happens after intervalMs, not immediately.

danger

intervalMs is a minimum, not a schedule. Timers are built on Thread.Pause, so every round is rounded up to the next script tick and the overshoot adds up: a SetInterval(1000, ...) has run fewer than 3600 times after an hour, and how many fewer depends on the machine. Never use a timer to keep a clock; compare against System.GetTime inside the callback if the exact time matters.

Example:

Lua

-- Every 5 seconds, forever.
Timer.SetInterval(5000, function()
    Chat.AddMessage("5 seconds are over.")
end)

-- Three times, with arguments.
Timer.SetInterval(1000, function(name, n)
    Chat.AddMessage(name .. ": " .. n)
end, 3, "tick", 42)

JavaScript

// Every 5 seconds, forever.
Timer.SetInterval(5000, () => {
    Chat.AddMessage("5 seconds are over.");
});

// Three times, with arguments.
Timer.SetInterval(1000, (name, n) => {
    Chat.AddMessage(name + ": " + n);
}, 3, "tick", 42);

Squirrel (deprecated)

// Every 5 seconds, forever.
Timer.SetInterval(5000, function() {
    Chat.AddMessage("5 seconds are over.");
});

// Three times, with arguments.
Timer.SetInterval(1000, function(name, n) {
    Chat.AddMessage(name + ": " + n);
}, 3, "tick", 42);

---

SetTimeout

Executes a function once after a specified delay. Shorthand for SetInterval(delayMs, func, 1, ...).

int timerId = Timer.SetTimeout(int delayMs, function func, any ...)

Example:

Lua

Timer.SetTimeout(3000, function(message)
    Chat.AddMessage(message)
end, "Three seconds later.")

JavaScript

Timer.SetTimeout(3000, (message) => {
    Chat.AddMessage(message);
}, "Three seconds later.");

Squirrel (deprecated)

Timer.SetTimeout(3000, function(message) {
    Chat.AddMessage(message);
}, "Three seconds later.");

---

Kill

Stops and removes a timer immediately. Safe to call on a timer that has already finished, and safe to call from inside the timer's own callback.

Timer.Kill(int timerId)

---

IsAlive

Checks if a specific timer is currently registered and active.

bool alive = Timer.IsAlive(int timerId)

---

GetRemaining

Returns the milliseconds remaining until the next execution, measured on the System.GetTime clock. Returns 0 for a timer that no longer exists.

int time = Timer.GetRemaining(int timerId)

---

GetRepeatsLeft

Returns the number of remaining executions for finite timers. Returns 0 for a timer that no longer exists, and also for an infinite timer, which has no limit to count down.

int repeats = Timer.GetRepeatsLeft(int timerId)

---

GetState

Returns the current state of the timer as a string ("running" or "dead").

string state = Timer.GetState(int timerId)