Tutorials

Using timers

Sample name: SampleTimer
Script source code file: sample/timer/main.lua

SampleTimer

The goal of this tutorial is to show you
  • how to create and use timers
New functions in this tutorial

addTimer()
setTimerTime()
removeTimer()

Run the sample SampleTimer.exe. Only three lines of text are rendered. The first shows you a random timer interval, the second is a string that says that you can remove the timer with the space key and finally, there is a line showing a flashing text :"Timer called".

Before we start looking at the code we should get a rough idea about what a timer is, and what functionalities it has.

A timer is a simple object that has a certain set time and the name of the callback function. As soon as the timer is activated, the defined time is counted down to zero. When this happens, the timer calls the callback function. This behavior can be used in various situations, for instance if a trigger shouldn’t react immediately but only after a certain delay.

Open the the main.lua which is located in the directory /sample/timer.

At first, four variables are defined:

timerId = 0;
timerInterval = 0;
renderCount = 0;
timerRemoved = false;

init()


In the init function the first line calls the function setRandomTimerInterval. This function simply generates a random value between 1000 and 5000 for the variable timerInterval.

function setRandomTimerInterval()
  timerInterval = math.random(1000, 5000);
end;

The variable timerInterval is used immediately because a new timer is created with the line:

 timerId = addTimer(timerInterval, "onTimer");

The variable timerId stores the Id of the new timer which is returned by the function addTimer. Here is how this function is described in the documentation:

addTimer

Description
Adds timer callback function
Definition
function addTimer(float time, string timerFunctionCallback, object instance)
Arguments
floattimetime in milliseconds
stringtriggerFunctionCallbacktrigger function callback
objectinstanceinstance object (optional)
Return Values
integertimerIdtimer id
The first argument is the time in milliseconds and the second argument is the function that is called when the time reaches zero. In this case, the variable timerInterval defines how long the timer will wait, until it calls its callback function. After this time, the function onTimer is called.

keyEvent()


If you hit the space key the timer is removed and the boolean timerRemoved is switched to true.

if sym == Input.KEY_space then
  -- Remove timer
  removeTimer(timerId);
  timerRemoved = true;
end;

onTimer()


This function is called as soon as the timer reaches zero.

The first line defines the variable renderCount to be 100. This defines the number of frames the line "timer called" is rendered in the draw function later on.

The second line defines a new timerInterval by calling the setRandomTimerInterval function again.

The third line sets a new timer time with the new timerInterval time. The setTimerTime function needs the id of the timer (timerId) and the new time (timerInterval). After the timer reaches zero again, the onTimer function is called again. You can remove a timer within the callback function by returning false.

-- Timer callback
function onTimer()
  renderCount = 100;
  setRandomTimerInterval();
  setTimerTime(timerId, timerInterval);
  return true;
end;

draw()


First we have an if-else construct that handles the two states, i.e. whether the timer is removed or not. Depending on the state of the boolean timerRemoved, the different renderText functions are executed.

The string "timer called" is only called if the variable renderCount is not zero. Remember that we set the renderCount to 100 in the onTimer function which is the trigger callback of the timer. With each frame the renderCount is decreased by 1.