Timer Class Reference

Trigger one-time or recurring scheduled events.

Member Functions
	clear()
	Removes all pending events from the timer queue.
	scheduleOnce(event, delay)
	Schedules an event to run one time, after delay ms. [details]
	scheduleRepeating(event, delay)
	Schedules an event to be run every delay ms. [details]
	scheduleRepeatWhileTrue(event, delay)
	Schedules an event to run one every delay ms until event returns true. The event will be repeated only if the call to 'event' returns true. [details]

Detailed Description

Trigger one-time or recurring scheduled events.

Timer is a utility class that makes it easier to manage timing periodic or delayed events. The timer code is based on a very nice library written by Haywood Slap.

A timer object that can be used to schedule arbitrary events to be executed at some time in the future. All times are given in milliseconds.

There are four basic timer functions:

-- Execute the event once in 'delay' ms
Timer:scheduleOnce(event, delay)
 
-- Execute the event repeatedly, every 'delay' ms
Timer:scheduleRepeating(event, delay)  
 
-- Execute the event every 'delay' ms while event returns true
Timer:scheduleRepeatWhileTrue(event, delay)  
 
-- Remove all pending events from the timer's queue
Timer:clear()

Timer Events

The 'event' used can either be the name a function, a table that contains a function named 'run', or a bit of arbitrary Lua code. These events are distinct from the Bitfighter-generated events documented elsewhere.

Any Lua function can be called by a Timer.

Examples:

function onLevelStart()
   -- Runs the code contained in the string after five seconds. 
   -- Note that the string here is in quotes.
   Timer:scheduleOnce("logprint(\"Once!\")", 5 * 1000)   
 
   -- Runs the "always" function every 30 seconds
   Timer:scheduleRepeating(always, 30 * 1000)            
 
   -- Runs "run" method of maybe every two seconds
   -- until method returns false
   Timer:scheduleRepeatWhileTrue(maybe, 2 * 1000)        
end                                                  
 
-- Standard function
function always()
   logprint("Timer called always")
end
 
-- Table: run method will be called
maybe = {
   count = 3
   run = function(self)
      logprint("Count down " .. self.count)
      self.count = self.count - 1
      return self.count > 0
   end
}

When using a table as an "event" the first parameter to the run function should always be a parameter named "self". The "self" parameter can be used to access the other fields in the table, that is, the "self" parameter will refer to the table that contains the run function. If you do not need to refer to any of the other fields in the table then you do not need to include the self parameter.

Member Function Documentation

clear()

returns nothing

Removes all pending events from the timer queue.

scheduleOnce(event, delay)

Arg types: event: function, delay: int  |  returns nothing

Schedules an event to run one time, after delay ms.

Parameters

event	- The event to be run.
delay	- The delay (in ms) when the the event should be run.

scheduleRepeating(event, delay)

Arg types: event: function, delay: int  |  returns nothing

Schedules an event to be run every delay ms.

Parameters

event	- The event to be run.
delay	- The time (in ms) which event repeats.

scheduleRepeatWhileTrue(event, delay)

Arg types: event: function, delay: int  |  returns nothing

Schedules an event to run one every delay ms until event returns true.
The event will be repeated only if the call to 'event' returns true.

Parameters

event	- The event to be run.
delay	- The time (in ms) which event repeats.