timer

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"));

// Repetitive timer which canceled after 10 calls
function call_every_second(self, handle, time_elapsed) {
  self.counter = self.counter + 1;
  print("Call #", self.counter);
  if (self.counter === 10) {
    timer.cancel(handle); // cancel timer after 10 calls
  }
}

self.counter = 0;
timer.delay(1, true, call_every_second);

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 number 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: number — identifier for the create timer, returns timer.INVALID_TIMER_HANDLE if the timer can not be created

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

self.handle = timer.delay(1, true, () => print("print every second"));
// ...
const result = timer.cancel(self.handle);
if (!result) {
  print("the timer is already cancelled");
}

Parameters

• handle: number — the timer handle returned by timer.delay()

Returns

• true: boolean — if the timer was active, false if the timer is already cancelled / complete

Manual triggering a callback for a timer.

self.handle = timer.delay(1, true, () => print("print every second or manually by timer.trigger"));
// ...
const result = timer.trigger(self.handle);
if (!result) {
  print("the timer is already cancelled or complete");
}

Parameters

• handle: number — the timer handle returned by timer.delay()

Returns

• true: boolean — if the timer was active, false if the timer is already cancelled / complete

Get information about timer.

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
}

Parameters

• handle: number — the timer handle returned by timer.delay()

Returns

• data: Record<string | number, unknown> | 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.

Indicates an invalid timer handle