Lua utility module Timer

Basic timer that performs countdown.

When it expires, you can set a specific LevelFuncs function to be activated.
Timers are updated automatically at every frame before OnLoop event.
To use Timer inside scripts you need to call the module:

local Timer = require("Engine.Timer")

Example usage:

local Timer = require("Engine.Timer")

-- This will be called when the timer runs out
LevelFuncs.FinishTimer = function(victoryMessage)
    -- Open a door, display a message, make an explosion or whatever you wish
    local pos = TEN.Vec2(TEN.Util.PercentToScreen(50, 10))
    local str = TEN.Strings.DisplayString(victoryMessage, pos)
    TEN.Strings.ShowString(str, 1)
end

-- This function triggers the timer
LevelFuncs.TriggerTimer = function(obj)
    Timer.Create("my_timer",
        5.0,
        false,
        {minutes = false, seconds = true, deciseconds = true},
        LevelFuncs.FinishTimer,
        "Well done!")
    Timer.Get("my_timer"):Start()
end

Timer format:

You have the option of displaying the remaining time or the total time of the timer.
You can display hours, minutes, seconds and deciseconds (deciseconds are 1/10th of a second).
To set which unit to display, you can use a table or a boolean value.
Timer format details:

-- hours:mins:secs.decisecs
local myTimeFormat = {hours = true, minutes = true, seconds = true, deciseconds = true}

-- mins:secs
local myTimeFormat1 = {minutes = true, seconds = true, deciseconds = false}

-- also mins:secs
local myTimeFormat2 = {minutes = true, seconds = true}

-- secs.decisecs
local myTimeFormat3 = {seconds = true, deciseconds = true}

-- secs; to display only seconds you can pass a table or true
local myTimeFormat4 = {seconds = true}
local myTimeFormat5 = true

-- no remaining time display
local myTimeFormat6 = false

Use this sparingly; in the classics, timed challenges did not have visible countdowns.
For shorter timers, the gameplay benefit from showing the remaining time might not be necessary, and could interfere with the atmosphere of the level.
At any given time, multiple timers can show their countdown.

Functions

Create(name, totalTime, [loop], [timerFormat], [func], [...]) Create (but do not start) a new timer.
Delete(name) Delete a timer.
Get(name) Get a timer by its name.
IfExists(name) Check if a timer exists.

Class Timer

Timer:Start([reset]) Begin or unpause a timer.
Timer:Stop() Stop the timer.
Timer:SetPaused(p) Pause or unpause the timer.
Timer:GetRemainingTime() Get the remaining time of a timer in game frames.
Timer:GetRemainingTimeInSeconds() Get the remaining time of a timer in seconds.
Timer:GetRemainingTimeFormatted(timerFormat) Get the formatted remaining time of a timer.
Timer:SetRemainingTime(remainingTime) Set the remaining time of a timer.
Timer:IfRemainingTimeIs(operator, seconds) Compares the remaining time with a value (in seconds).
Timer:GetTotalTime() Get the total time of a timer in game frames.
Timer:GetTotalTimeInSeconds() Get the total time of a timer in seconds.
Timer:GetTotalTimeFormatted(timerFormat) Get the formatted total time of a timer.
Timer:SetTotalTime(totalTime) Set the total time for a timer.
Timer:IfTotalTimeIs(operator, seconds) Compares the total time with a value (in seconds).
Timer:SetLooping(looping) Set whether or not the timer loops.
Timer:SetFunction([func], [...]) Assign a new function and its arguments to the timer.
Timer:SetPosition([x], [y]) Set the on-screen position in percent of the displayed timer when active.
Timer:GetPosition() Get the on-screen position in percent of the displayed timer when active.
Timer:SetScale([scale]) Set the scale of the displayed timer when it is active.
Timer:GetScale() Get the scale of the displayed timer when it is active.
Timer:SetPausedColor([color]) Set the paused color of the displayed timer when it is active.
Timer:SetUnpausedColor([color]) Set the color of the displayed timer when it is active.
Timer:SetTextOption([optionsTable]) Set text options for a timer.
Timer:IsPaused() Get whether or not the timer is paused
Timer:IsActive() Get whether or not the timer is active
Timer:IsTicking() Checks if the timer has ticked (every 0.1 seconds).


Functions

Create(name, totalTime, [loop], [timerFormat], [func], [...])
Create (but do not start) a new timer.

Parameters:

  • name string A label to give this timer; used to retrieve the timer later.
    Do not give your timers a name beginning with __TEN, as this is reserved for timers used by other internal libaries.
  • totalTime float Duration of the timer, in seconds.
    Values with only 1 tenth of a second (0.1) are accepted, example: 1.5 - 6.0 - 9.9 - 123.6. No negative values allowed!
  • loop bool If true, the timer will start again immediately after the time has elapsed. Default: false.
  • timerFormat table or bool Sets the remaining time display. See Timer format. Default: false.
  • func LevelFunc The function defined in the LevelFuncs table to call when the time is up Default: nil.
  • ... any a variable number of arguments with which the above function will be called Optional.

Returns:

    Timer The timer in its paused state

Usage:

    -- Example 1 simple timer:
Timer.Create("my_timer", 6.1)

-- Example 2 Timer that executes a function when it expires:
local TimeFormat = {minutes = true, seconds = true, deciseconds = true}
LevelFuncs.FinishTimer = function()
   TEN.Util.PrintLog("Timer expired", TEN.Util.LogLevel.INFO)
end
Timer.Create("my_timer", 6.1, false, TimerFormat, LevelFuncs.FinishTimer)
Delete(name)
Delete a timer.

Parameters:

  • name string The label that was given to the timer when it was created

Usage:

    -- Example:
Timer.Delete("my_timer")
Get(name)
Get a timer by its name.

Parameters:

  • name string The label that was given to the timer when it was created

Returns:

    Timer or nil The timer or nil if timer does not exist

Usage:

    -- Example:
Timer.Get("my_timer")
IfExists(name)
Check if a timer exists.

Parameters:

  • name string The label that was given to the timer when it was created

Returns:

    bool true if the timer exists, false if it does not exist

Usage:

    -- Example:
-- This function checks if a timer named "my_timer" exists and starts it
LevelFuncs.CheckAndStart = function()
   if Timer.IfExists("my_timer") then
      Timer.Get("my_timer"):Start()
   end
end

Class Timer

List of all methods of the Timer object. It's always recommended to check the existence of the timer with the Timer.IfExists() function before using the methods of the Timer object, to avoid errors or unexpected behavior. When calling a method, it's recommended to use the Timer.Get() function, to avoid errors after loading a savegame

Usage:

-- Examples of some methods
Timer.Get("my_timer"):Start()
Timer.Get("my_timer"):Stop()
Timer.Get("my_timer"):SetPaused(true)

-- check if the timer exists before using methods
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):Start()
end
Timer:Start([reset])
Begin or unpause a timer. If showing the remaining time on-screen, its default color will be set to white.

Parameters:

  • reset bool If true, the timer will restart from the beginning (total time) Default: false.

Usage:

    local TimeFormat = {minutes = true, seconds = true, deciseconds = true}
Timer.Create("my_timer", 6.1, false, TimerFormat)

-- Example 1: Start the timer
-- This function starts the timer named my_timer
LevelFuncs.StartTimer = function()
   if Timer.IfExists("my_timer") then
      Timer.Get("my_timer"):Start()
   end
end

-- Example 2: Start the timer and reset it
-- This function resets the timer named my_timer and starts it
LevelFuncs.Reset_StartTimer = function()
   if Timer.IfExists("my_timer") then
      Timer.Get("my_timer"):Start(true)
   end
end
Timer:Stop()
Stop the timer.

Usage:

    -- example
local TimeFormat = {minutes = true, seconds = true, deciseconds = true}
Timer.Create("my_timer", 6.1, false, TimerFormat)

-- This function stops the timer named my_timer
LevelFuncs.StopTimer = function()
   if Timer.IfExists("my_timer") then
      Timer.Get("my_timer"):Stop()
   end
end
Timer:SetPaused(p)
Pause or unpause the timer. If showing the remaining time on-screen, its default color will be set to yellow (paused) or white (unpaused).

Parameters:

  • p bool If true, the timer will be paused; if false, it would be unpaused

Usage:

    local TimeFormat = {minutes = true, seconds = true, deciseconds = true}
Timer.Create("my_timer", 6.1, false, TimerFormat)

-- Example 1 paused timer:
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetPaused(true)
end

-- Example 2 unpaused timer:
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetPaused(false)
end
Timer:GetRemainingTime()
Get the remaining time of a timer in game frames.

Returns:

    Time The remaining time in game frames of timer.

Usage:

    -- Example:
local TimeFormat = {minutes = true, seconds = true, deciseconds = true}
Timer.Create("my_timer", 6.1, false, TimerFormat)

local timer = TEN.Time()
if Timer.IfExists("my_timer") then
   time = Timer.Get("my_timer"):GetRemainingTime()
end
Timer:GetRemainingTimeInSeconds()
Get the remaining time of a timer in seconds.

Returns:

    float The remaining time in seconds of timer.
    Seconds have an accuracy of 0.1 tenths. Example: 1.5 - 6.0 - 9.9 - 123.6

Usage:

    -- Example:
local timer = 0
if Timer.IfExists("my_timer") then
   time = Timer.Get("my_timer"):GetRemainingTimeInSeconds()
end
Timer:GetRemainingTimeFormatted(timerFormat)
Get the formatted remaining time of a timer.

Parameters:

Returns:

    string The formatted remaining time.

Usage:

    -- Example:
local TimerFormat = {seconds = true, deciseconds = true}
if Timer.IfExists("my_timer") then
   local pos = TEN.Vec2(TEN.Util.PercentToScreen(50, 10))
   local timer = Timer.Get("my_timer"):GetRemainingTimeFormatted(TimerFormat)
   local str = TEN.Strings.DisplayString("Timer: " .. timer, pos)
   TEN.Strings.ShowString(str, 1)
end
Timer:SetRemainingTime(remainingTime)
Set the remaining time of a timer.

Parameters:

  • remainingTime float The new time remaining for the timer in seconds.
    Values with only 1 tenth of a second (0.1) are accepted, example: 1.5 - 6.0 - 9.9 - 123.6. No negative values allowed!

Usage:

    -- Example:
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetRemainingTime(3.5)
end
Timer:IfRemainingTimeIs(operator, seconds)
Compares the remaining time with a value (in seconds).

It's recommended to use the IfRemainingTimeIs() method to have error-free comparisons

Parameters:

  • operator int The type of comparison.
    0 : If the remaining time is equal to the value
    1 : If the remaining time is different from the value
    2 : If the remaining time is less the value
    3 : If the remaining time is less or equal to the value
    4 : If the remaining time is greater the value
    5 : If the remaining time is greater or equal to the value
  • seconds float The value in seconds to compare.
    Values with only 1 tenth of a second (0.1) are accepted, example: 1.5 - 6.0 - 9.9 - 123.6. No negative values allowed!
    Please note: to have continuous control, the remaining time must be controlled within the OnLoop event and only when the Timer is active Timer.IsActive.

Returns:

    bool true if comparison is true, false if comparison is false or timer does not exist

Usage:

    -- Example: Alternative method to create a sequence of events by checking if the remaining time has specific value.
Timer.Create("my_timer", 8.0)
LevelFuncs.OnLoop = function() -- this function is present in the .lua file of the level
   if Timer.IfExists("my_timer") and Timer.Get("my_timer"):IsActive() then
      if Timer.Get("my_timer"):IfRemainingTimeIs(0, 7.0) then
         -- do something
      end
      if Timer.Get("my_timer"):IfRemainingTimeIs(0, 6.1) then
         -- do something
      end
      if Timer.Get("my_timer"):IfRemainingTimeIs(0, 3.4) then
         -- do something
      end
      if Timer.Get("my_timer"):IfRemainingTimeIs(0, 1.1) then
         -- do something
      end
      if Timer.Get("my_timer"):IfRemainingTimeIs(0, 0.4) then
         -- do something
      end
   end
end
Timer:GetTotalTime()
Get the total time of a timer in game frames. This is the amount of time the timer will start with, as well as when starting a new loop.

Returns:

    Time The timer's total time in game frames.

Usage:

    -- Example:
local total = TEN.Time()
if Timer.IfExists("my_timer") then
   total = Timer.Get("my_timer"):GetTotalTime()
end
Timer:GetTotalTimeInSeconds()
Get the total time of a timer in seconds. This is the amount of time the timer will start with, as well as when starting a new loop

Returns:

    float The timer's total time in seconds.
    Seconds have an accuracy of 0.1 tenths. Example: 1.5 - 6.0 - 9.9 - 123.6

Usage:

    -- Example:
local total = 0
if Timer.IfExists("my_timer") then
   total = Timer.Get("my_timer"):GetTotalTimeInSeconds()
end
Timer:GetTotalTimeFormatted(timerFormat)
Get the formatted total time of a timer. This is the amount of time the timer will start with, as well as when starting a new loop

Parameters:

Returns:

    string The formatted total time.

Usage:

    -- Example:
local TimerFormat = {minutes = false, seconds = true, deciseconds = true}
if Timer.IfExists("my_timer") then
   local pos = TEN.Vec2(TEN.Util.PercentToScreen(50, 10))
   local totalTime = Timer.Get("my_timer"):GetTotalTimeFormatted(TimerFormat)
   local str = TEN.Strings.DisplayString("Total time is: " .. totalTime, pos)
end
Timer:SetTotalTime(totalTime)
Set the total time for a timer.

Parameters:

  • totalTime float Timer's new total time in seconds.
    Values with only 1 tenth of a second (0.1) are accepted, example: 1.5 - 6.0 - 9.9 - 123.6. No negative values allowed!

Usage:

    -- Example:
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetTotalTime(3.5)
end
Timer:IfTotalTimeIs(operator, seconds)
Compares the total time with a value (in seconds).

It's recommended to use the IfTotalTimeIs() method to have error-free comparisons

Parameters:

  • operator int The type of comparison.
    0 : If the total time is equal to the value
    1 : If the total time is different from the value
    2 : If the total time is less the value
    3 : If the total time is less or equal to the value
    4 : If the total time is greater the value
    5 : If the total time is greater or equal to the value
  • seconds float the value in seconds to compare.
    Values with only 1 tenth of a second (0.1) are accepted, example: 1.5 - 6.0 - 9.9 - 123.6. No negative values allowed!

Returns:

    bool true if comparison is true, false if comparison is false or timer does not exist

Usage:

    -- Example: this function checks if totalTime is equal to 5.1 seconds
if Timer.IfExists("my_timer") and Timer.Get("my_timer"):IfTotalTimeIs(0, 5.1) then
   local currentToltalTime = Timer.Get("my_timer"):GetTotalTime()
   Timer.Get("my_timer"):SetTotalTime(currentToltalTime + 1.0)
end
Timer:SetLooping(looping)
Set whether or not the timer loops.

Parameters:

  • looping bool Whether or not the timer loops

Usage:

    -- Example:
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetLooping(true)
end
Timer:SetFunction([func], [...])
Assign a new function and its arguments to the timer. It will be called when the time is up.

Parameters:

  • func LevelFunc The function defined in the LevelFuncs table to call when the time is up Default: nil.
  • ... any A variable number of arguments with which the above function will be called Optional.

Usage:

    -- Example1: Assign a new function to the timer
-- This function kills Lara
LevelFuncs.KillLara = function()
   TEN.Util.PrintLog("Kill Lara", TEN.Util.LogLevel.INFO)
   Lara:SetHP(0)
end
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetFunction(LevelFuncs.KillLara)
end

-- Example2: Assign a new function to the timer with arguments
-- This function kills Lara and displays a message
LevelFuncs.KillLara = function(victoryMessage)
   TEN.Util.PrintLog("Kill Lara", TEN.Util.LogLevel.INFO)
   Lara:SetHP(0)
   local pos = TEN.Vec2(TEN.Util.PercentToScreen(50, 10))
   local str = TEN.Strings.DisplayString(victoryMessage, pos)
   TEN.Strings.ShowString(str, 1)
end
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetFunction(LevelFuncs.KillLara, "Well done!")
end

-- Example3: Do not assign a function
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetFunction()
end
Timer:SetPosition([x], [y])
Set the on-screen position in percent of the displayed timer when active.

The coordinate (0,0) is in the upper left-hand corner.

Parameters:

  • x float The x-coordinate in percent Default: 50.
  • y float The y-coordinate in percent Default: 90.

Usage:

    -- Example:
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetPosition(10.0,10.0)
end

-- Example 2: Set defaults values
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetPosition()
end
Timer:GetPosition()
Get the on-screen position in percent of the displayed timer when active.

Returns:

    Vec2 The position of the timer in percent

Usage:

    -- Example: Move the position of the Timer dynamically
if Timer.IfExists("my_timer") then
   local pos = Timer.Get("my_timer"):GetPosition()
   Timer.Get("my_timer"):SetPosition(pos.x + 10, pos.y + 10)
end
Timer:SetScale([scale])
Set the scale of the displayed timer when it is active.

Parameters:

  • scale float The new scale value Default: 1.0.

Usage:

    -- Example:
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetScale(1.5)
end

-- Example 2: Set default value
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetScale()
end
Timer:GetScale()
Get the scale of the displayed timer when it is active.

Returns:

    float The scale of the timer

Usage:

    -- Example:
if Timer.IfExists("my_timer") then
   local scale = Timer.Get("my_timer"):GetScale()
   Timer.Get("my_timer"):SetScale(scale + 0.5)
end
Timer:SetPausedColor([color])
Set the paused color of the displayed timer when it is active.

Parameters:

  • color Color Timer's new paused color. Default: TEN.Color(255, 255, 0, 255).

Usage:

    -- Example:
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetPausedColor(TEN.Color(0, 255, 0, 255))
end

-- Example 2: Set default value
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetPausedColor()
end
Timer:SetUnpausedColor([color])
Set the color of the displayed timer when it is active.

Parameters:

  • color Color Timer's new color. Default: TEN.Color(255, 255, 255, 255).

Usage:

    -- Example:
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetUnpausedColor(TEN.Color(0, 255, 255, 255))
end

-- Example 2: Set default value
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetUnpausedColor()
end
Timer:SetTextOption([optionsTable])
Set text options for a timer.

Parameters:

  • optionsTable table Table containing timer's new text options. See Strings.DisplayStringOption
    Default: {TEN.Strings.DisplayStringOption.CENTER, TEN.Strings.DisplayStringOption.SHADOW}.

Usage:

    -- Example 1
-- right alignment
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetTextOption({TEN.Strings.DisplayStringOption.RIGHT})
end

-- Example 2: Set default value + BLINK effect
newOptins = {TEN.Strings.DisplayStringOption.CENTER,
            TEN.Strings.DisplayStringOption.SHADOW,
            TEN.Strings.DisplayStringOption.BLINK}
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetTextOption(newOptins)
end

-- Example 3: Set text option to left alignment
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetTextOption({TEN.Strings.DisplayStringOption.LEFT})
end

-- Example 4: Set default value
if Timer.IfExists("my_timer") then
   Timer.Get("my_timer"):SetTextOption()
end
Timer:IsPaused()
Get whether or not the timer is paused

Returns:

    bool true if the timer is paused, false if it is not paused or timer does not exist

Usage:

    -- Example:
if Timer.IfExists("my_timer") and Timer.Get("my_timer"):IsPaused() then
   TEN.View.SetPostProcessMode(TEN.View.PostProcessMode.MONOCHROME)
end
Timer:IsActive()
Get whether or not the timer is active

Returns:

    bool true if the timer is active, false if it is not active or timer does not exist

Usage:

    -- Example:
if Timer.IfExists("my_timer") and Timer.Get("my_timer"):IsActive() then
   TEN.View.SetPostProcessMode(TEN.View.PostProcessMode.EXCLUSION)
end
Timer:IsTicking()
Checks if the timer has ticked (every 0.1 seconds).

Returns true every 0.1 seconds when the timer is active and not paused.
TEN's engine runs on a 0.03-second internal tick, while this timer ticks every 0.1 seconds.
Use IsTicking() to ensure consistency and avoid unexpected behavior — for example, inside the OnLoop event.

Returns:

    boolean true if the timer ticked during this frame, false otherwise.

Usage:

    -- Example: Displays the time remaining when the timer is active
LevelFuncs.OnLoop = function() -- this function is present in the .lua file of the level
   if Timer.IfExists("my_timer") and Timer.Get("my_timer"):IsActive() and Timer.Get("my_timer"):IsTicking() then
      local TimerFormat = {seconds = true, deciseconds = true}
      local remainingTime = Timer.Get("my_timer"):GetRemainingTimeFormatted(TimerFormat)
      TEN.Util.PrintLog("Remaining time: " .. remainingTime, TEN.Util.LogLevel.INFO)
   end
end
generated by TEN-LDoc (a fork of LDoc 1.4.6)