timer
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.
Functions
timer.cancel(handle: number): booleantimer.delay(delay: number, repeating: boolean, callback: (self: unknown, handle: unknown, time_elapsed: unknown) => void): numbertimer.get_info(handle: number): { time_remaining: number; delay: number; repeating: boolean } | undefinedtimer.trigger(handle: number): boolean
timer.cancel(handle: number): boolean
You may cancel a timer from inside a timer callback. Cancelling a timer that is already executed or cancelled is safe.
function cancel_ticking(self: { handle: number }) {
self.handle = timer.delay(1, true, () => print("print every second"));
// ...
const cancelled = timer.cancel(self.handle);
if (!cancelled) {
print("the timer is already cancelled");
}
}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")
endParameters
handle:number— the timer handle returned by timer.delay()
Returns
cancelled:boolean—trueif the timer was active and cancelled,falseif the timer was already cancelled or complete
timer.delay(delay: number, repeating: boolean, callback: (self: unknown, handle: unknown, time_elapsed: unknown) => void): number
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.
A simple one-shot timer
timer.delay(1, false, () => print("print in one second"));timer.delay(1, false, function() print("print in one second") end)Repetitive timer which canceled after 10 calls
function call_every_second(self: unknown, handle: unknown, time_elapsed: unknown) {
const state = self as { counter: number };
state.counter = state.counter + 1;
print("Call #", state.counter);
if (state.counter === 10) {
timer.cancel(handle as number); // cancel timer after 10 calls
}
}
function start_counting(self: { counter: number }) {
self.counter = 0;
timer.delay(1, true, call_every_second);
}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)Parameters
delay:number— time interval in secondsrepeating:boolean— true = repeat timer until cancel, false = one-shot timercallback:(self: unknown, handle: unknown, time_elapsed: unknown) => void— timer callback functionselfscript_instance The current script instancehandletimer_handle The handle of the timertime_elapsednumber The elapsed time - on first trigger it is time since timer.delay call, otherwise time since last trigger
Returns
handle:number— identifier for the create timer, returns timer.INVALID_TIMER_HANDLE if the timer can not be created
timer.get_info(handle: number): { time_remaining: number; delay: number; repeating: boolean } | undefined
Get information about timer.
function report_ticking(self: { handle: number }) {
self.handle = timer.delay(1, true, () => print("print every second"));
// ...
const result = timer.get_info(self.handle);
if (!result) {
print("the timer is already cancelled or complete");
} else {
pprint(result); // delay, time_remaining, repeating
}
}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
endParameters
handle:number— the timer handle returned by timer.delay()
Returns
data:{ time_remaining: number; delay: number; repeating: boolean } | undefined— timer information, ornilif the timer is cancelled or complete
timer.trigger(handle: number): boolean
Manual triggering a callback for a timer.
function trigger_ticking(self: { handle: number }) {
self.handle = timer.delay(1, true, () => print("print every second or manually by timer.trigger"));
// ...
const triggered = timer.trigger(self.handle);
if (!triggered) {
print("the timer is already cancelled or complete");
}
}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")
endParameters
handle:number— the timer handle returned by timer.delay()
Returns
triggered:boolean—trueif the timer was active and triggered,falseif the timer was already cancelled or complete
Constants
timer.INVALID_TIMER_HANDLE: number & { readonly __brand: "timer.INVALID_TIMER_HANDLE" }
Indicates an invalid timer handle