# Class: Timer

### LuxModule: luxinialuacore

Luxinia does automaticly call a function named 'think' in a table called 'luxinia' each frame. The Timer class registers this function and provides a mechanism to add additional function that should be called each frame.

The function is being disabled if it throws an error.

The timer has been changed during 0.93 to use coroutines. This is quite useful: you can yield a function at any point of time during execution if it is called by a timer or timertask. The execution is then continued later. For timers, this is the next period, for TimerTasks, please read the documentation on the TimerTask class. You can create endless loops just as this:

     Timer.set("endless loop",
     	function ()
     		while true do
     			print "tick"
     			coroutine.yield()
     		end
     	end, 50)

The code sample above will create a timertask that is executed about every 50 ms and will always print "tick" out.

Coroutines are useful utilities to create AIs, agents or gameloops. You do not have to change a state of a game function for example:

     Timer.set("game",
     	function ()
     		local gamestarts,gamefinished
     		repeat
     			-- do something about intro menu etc. stuff
     			coroutine.yield()
     		until gamestarts 		repeat
     			-- make some gamelogic stuff, spawing actors, etc
     			-- set gamefinished to true or break loop if game is finished
     			coroutine.yield()
     		until gamefinished
     	end, 1000/30)

The code sample above will be executed every 30 fps. You can also nest the loops in loops, for example for each level. Instead of writing different functions that represent your state of game and that are selected for execution, you can use this method to create a linear way of writing a game.

## Methods:

### Method overview:

- enable
- finally
- frame
- remove
- set
- think

enable (string/function key)
  returns: ()

  enables a disabled timerfunction again

finally (key,function)
  returns: ()

  the finally function is a list of functions that should be executed when all timers are finished. The timer and the finish functions are called in no particular order so this is just a method to do some stuff at the end of the timer calls (the timertasks are finished till then too). A key can only be registered one time, after that it will overwrite the previous function.

  The finally function registrations are only valid for the current frame, so you must reregister it if required.

  This functionality exists to provide help on optimized updating - you may want to collect information on for the real update function of an object that can then update all information alltogether instead of doing the same again and again updating ony tiny changes.

  Registering finally functions in a finally function call works. The new registered function is called once all previously registered functions have been executed. If you keep on registering finally functions, this means that the finally calls will never stop!

frame ()
  returns: (int)
  returns the frame (or the number of thinkcycles)
remove (string/function key)
  returns: ()
  removes a timer function from the Timer list.
set (string description,function fn[, int interval], [int maxcnt])
  returns: (function fn)

  set a function to be called each frame if interval is not passed. If interval is a number (minimum 1), the function will be called in the intervals in milliseconds. The timer automaticly repeates calls if the timer is late. If the maxcnt argument is passed, the timer won't be called more often than maxcnt per frame - if a timer is behind time, this prevents the system too freeze if the timerfunction is taking longer than its given interval.

  fn will be called with the local time of the function as first argument and the number of the repeated calls within this frame as second argument (`fn(int localtime, int repeatedcalls)`). The localtime is increased by the value of interval each time a call is done.

  The description string can be used to remove a timer. The timer is identified by the function value and multiple timers can share the same description string (and can all be removed with one remove call this way).

  Returns the passed function.
think ()
  returns: ()

  Function that is called each frame. If you switch to manual frame processing within lua, you should call this function each frame you do, since other modules are dependent on the timer function (i.e. the Keyboard class).