timer#

timer provides functions for reading the current simulation time and scheduling functions to run at a later model time. It is commonly used to build delayed or periodic logic in mission scripts without relying on trigger repetition.

Functions#

timer.getTime()#

Returns the current model time, in seconds, since the mission started.

Returns:

Current model time, in seconds.

Return type:

number

Example:

local now = timer.getTime()
env.info('Current model time: ' .. tostring(now))
timer.getAbsTime()#

Returns the current mission time as an absolute time of day, in seconds since midnight.

Returns:

Absolute time of day, in seconds since midnight.

Return type:

number

Example:

local absTime = timer.getAbsTime()
timer.getTime0()#

Returns the model time at which the mission started, useful for computing absolute time from getTime().

Returns:

Model time at mission start.

Return type:

number

Example:

local missionStart = timer.getTime0()
timer.scheduleFunction(functionToCall, functionArgument, modelTime)#

Schedules functionToCall to be called with functionArgument at the given modelTime. If the scheduled function returns a number, it will be rescheduled to run again at that model time.

Parameters:

  • functionToCall (function) – Function to invoke.

  • functionArgument – Argument passed to the function when invoked.

  • modelTime (number) – Model time at which to invoke the function.

Returns:

A function ID, usable with removeFunction() and setFunctionTime().

Return type:

number

Example:

-- Repeats every 10 seconds by returning the next model time.
local function heartbeat(arg, currentTime)
    env.info('Heartbeat at ' .. tostring(currentTime))
    return currentTime + 10
end

local functionId = timer.scheduleFunction(heartbeat, nil, timer.getTime() + 10)
timer.removeFunction(functionId)#

Cancels a previously scheduled function.

Parameters:

functionId (number) – ID returned by scheduleFunction().

Example:

timer.removeFunction(functionId)
timer.setFunctionTime(functionId, modelTime)#

Reschedules a previously scheduled function to run at a new model time.

Parameters:

  • functionId (number) – ID returned by scheduleFunction().

  • modelTime (number) – New model time at which to invoke the function.

Example:

timer.setFunctionTime(functionId, timer.getTime() + 30)

Footnotes#

  • Scheduled functions run on the simulation thread; long-running logic inside a scheduled function can affect simulation performance.

  • Model time pauses when the simulation is paused, so scheduled functions will not fire while paused.