Timer objects are used to perform tasks after a delay or on a repeating schedule. When a timer is created, it is given a function to call, and a delay and an optional interval in seconds in game real time. The next fire time of the timer is set to the current time + the delay. When the game clock reaches (or passes) the next fire time, the function is called. If the timer has a positive interval, the interval is added to the next fire time. Otherwise, the timer stops.
Note: in order for a timer to work consistently, you must keep a reference to it as long as it is in use. The easiest way is to make it a property of your script:
new Timer(this : Object, function : Function, delay : Number [, interval : Number]) : Timer
Creates a new timer which will call
delay seconds, and optionally repeatedly every
interval seconds. If
delay is zero or more, the timer will be started automatically. If
interval is 0 or less, the timer will not repeat. If
interval is greater than 0 but less than 0.25, it will be rounded up to 0.25.
delay is negative and
interval is positive, the timer will initially be stopped. After it is started, it will fire at multiples of
interval after its creation time. For instance, if a timer is created stopped with a five-second interval, and started after seven seconds, it will fire after three seconds (which is ten seconds after it was created).
this parameter becomes invalid (usually because it’s attached to a ship that’s destroyed, or left behind when the player executes a hyperspace jump), the timer will be stopped and removed automatically. You should use entityDestroyed in ship scripts to clean up timers.
interval : Number (read/write)
The rate at which the timer repeats. For a one-shot timer, this will be -1. If set to 0 or a negative number, it will be treated as -1. If set to a number between 0 and 0.25, it will be rounded up to 0.25.
isRunning : Boolean (read-only)
true if the timer is running,
false if it is stopped.
nextTime : Number (read/write when stopped)
The next time the timer will fire, if it is running at that time. This can be modified if the timer is stopped. Note that this is an absolute time, not a delay. You can get the current absolute time using
function start() : Boolean
Starts the timer, if it is not currently running. This will fail if it is a one-shot timer (i.e., its
interval is -1) and its
nextTime is in the past. Returns
true if successful or the timer was already running,
false on failure (i.e., the same as
start() is called).
Stops the timer, if it is currently running.
Important: Always stop a timer before deleting its JS reference, or a copy of the object will stay around in a timer queue and will keep firing. Without explicit stopping, the timer will only stop with an error when the script it belongs to no longer exists.
- The normal, widely-used standard for creating the callback function (Phkb, 2017)
- Unrooted Timers and Garbage Collection (Nite Owl, 2023)