Lua:createTimer

function createTimer(owner OPTIONAL, enabled OPTIONAL) : Timer

function createTimer(interval, callback, ... OPTIONAL) : Timer

Creates a Timer object that fires repeatedly or once at specified intervals.

• Returns: A Timer UserData object
• Modes: Two distinct calling modes with different behaviors

Two Calling Modes

Mode 1: Persistent Timer - Creates a recurring timer that continues until destroyed or disabled

createTimer(owner, enabled)

Mode 2: One-Shot Timer - Creates a timer that fires once and auto-destroys

createTimer(interval, callback, ...)

Function Parameters

Mode 1: Persistent Timer

Parameter	Type	Description
owner	Component or nil	Optional. Parent component that owns this timer. When the owner is destroyed, the timer is destroyed too. Pass nil or omit for standalone timer. Default: nil
enabled	boolean	Optional. Whether the timer starts active immediately. Default: true

Mode 2: One-Shot Timer

Parameter	Type	Description
interval	integer	Timer delay in milliseconds before callback fires once
callback	function	Function to execute when the timer fires. Receives any additional varargs as parameters
...	varargs	Optional. Additional arguments to pass to the callback function

Usage Examples

Persistent Timer Examples

Basic recurring timer (runs every second):

local timer = createTimer()
timer.Interval = 1000  -- 1 second
timer.OnTimer = function()
  print("Tick: " .. os.date("%H:%M:%S"))
end

Timer with owner (destroyed when form closes):

local form = createForm()
local timer = createTimer(form)
timer.Interval = 500
timer.OnTimer = function()
  form.Caption = "Time: " .. os.date("%H:%M:%S")
end

Timer owned by main form (auto-cleanup when CE closes):

local timer = createTimer(getMainForm())
timer.Interval = 1000
timer.OnTimer = function()
  print("Running until CE closes")
end

Create disabled timer and enable later:

local timer = createTimer(nil, false)
timer.Interval = 2000
timer.OnTimer = function()
  print("2 seconds passed")
end
-- Enable when needed
timer.Enabled = true

Manual cleanup when done:

local timer = createTimer()
timer.Interval = 100
local count = 0
timer.OnTimer = function()
  count = count + 1
  print("Count: " .. count)
  if count >= 10 then
    timer.Enabled = false
    timer.destroy()
    print("Timer stopped and destroyed")
  end
end

Toggle timer on/off:

local timer = createTimer()
timer.Interval = 1000
timer.Enabled = false
timer.OnTimer = function()
  print("Active!")
end

-- Start
timer.Enabled = true
-- Stop
timer.Enabled = false

One-Shot Timer Examples

Simple delay (auto-destroys after firing):

createTimer(2000, function()
  print("Executed after 2 seconds")
end)

One-shot timer with parameters:

local name = "Player"
local health = 100

createTimer(1500, function(playerName, hp)
  print(playerName .. " health: " .. hp)
end, name, health)

Delayed execution in sequence:

print("Starting...")
createTimer(1000, function()
  print("Step 1: After 1 second")
end)
createTimer(2000, function()
  print("Step 2: After 2 seconds")
end)
createTimer(3000, function()
  print("Step 3: After 3 seconds")
end)

One-shot timer with closure:

local function showMessage(msg)
  createTimer(1000, function()
    print("Delayed message: " .. msg)
  end)
end

showMessage("Hello World")

Delayed form update:

local form = createForm()
form.Caption = "Loading..."

createTimer(2000, function()
  form.Caption = "Ready!"
end)

Advanced Timer Patterns

Countdown timer:

local countdown = 10
local timer = createTimer()
timer.Interval = 1000
timer.OnTimer = function()
  print("Countdown: " .. countdown)
  countdown = countdown - 1
  if countdown < 0 then
    timer.Enabled = false
    timer.destroy()
    print("Countdown complete!")
  end
end

Periodic memory check:

local timer = createTimer()
timer.Interval = 500
timer.OnTimer = function()
  local addr = getAddress("player.health")
  if addr then
    local health = readInteger(addr)
    if health < 50 then
      print("Warning: Low health!")
    end
  end
end

Auto-refresh display:

local form = createForm()
local label = createLabel(form)
label.Caption = ""

local timer = createTimer(form)
timer.Interval = 100
timer.OnTimer = function()
  local addr = getAddress("game.score")
  if addr then
    label.Caption = "Score: " .. readInteger(addr)
  end
end

Rate-limited action:

local canExecute = true
local timer = createTimer(nil, false)
timer.Interval = 1000
timer.OnTimer = function()
  canExecute = true
  timer.Enabled = false
end

function performAction()
  if canExecute then
    print("Action executed!")
    canExecute = false
    timer.Enabled = true
  else
    print("Please wait...")
  end
end

Persistent vs One-Shot Comparison

Feature	Persistent Timer	One-Shot Timer
Creation	createTimer() or createTimer(owner, enabled)	createTimer(interval, callback, ...)
Behavior	Fires repeatedly until disabled	Fires once and auto-destroys
Cleanup	Must call destroy() manually	Destroys itself automatically
Control	Can enable/disable with .Enabled	Cannot control after creation
Callback Setup	Set .OnTimer property after creation	Callback passed during creation
Typical Use	Monitoring, periodic updates, UI refresh	Delays, deferred execution, timeouts

Notes

• Interval is in milliseconds (1000 = 1 second)
• Timers inherit from Component class
• One-shot timers automatically free themselves - do not call destroy()
• Persistent timers must be destroyed manually or by owner
• Use getMainForm() as owner to auto-destroy timer when CE closes
• Timer callbacks execute in the main CE thread
• Setting Enabled = false pauses the timer without destroying it
• Timer accuracy depends on system load (~15ms resolution on Windows)

Common Mistakes

Don't store one-shot timer reference:

-- WRONG: One-shot timer will self-destruct
local t = createTimer(1000, function() print("Hi") end)
-- t becomes invalid after firing

-- RIGHT: Just create and forget
createTimer(1000, function() print("Hi") end)

Don't forget to destroy persistent timers:

-- WRONG: Memory leak if timer never destroyed
function startMonitoring()
  local t = createTimer()
  t.Interval = 1000
  t.OnTimer = function() print("Check") end
end

-- RIGHT: Store reference and destroy when done
local monitorTimer = nil
function startMonitoring()
  monitorTimer = createTimer()
  monitorTimer.Interval = 1000
  monitorTimer.OnTimer = function() print("Check") end
end
function stopMonitoring()
  if monitorTimer then
    monitorTimer.destroy()
    monitorTimer = nil
  end
end

See also

• Lua
• Script engine

Related Functions

• sleep - Blocking delay alternative
• createThread - Non-blocking threading

Related Classes

• Timer - Timer class documentation
• Component - Base class for Timer