Timers are useful mapping/scripting items when you want a script to be triggered after a set period of time (e.g. a player has dallied too long in a particular area and you want to eject them).
However, I have found little documentation on timers, and they seem notoriously difficult to program. I have had to glean stuff through trial and error, so I thought I would pass on what I have found. If others know more, please contribute!
If you look at the special tab of a timer's attributes in mapmaker, you will see the following:
(In spoiler tags as my description takes up a fair amount of space)
connection - if set, a trigger on this connection number will start the timer
connection flag 1 - I don't know what this does, and have never used it
restarts when triggered - if this box is checked, the timer start a new countdown every time it fires (most scripts I have seen have this checked, such at for the maps with periodic thunder).
timer interval - (default 10) this is the time in seconds which elapse before triggering once started through a connection. For scripting, this is timer.max_hitpoints
time left - (default -1) when started, this is set to the timer interval and counts down in seconds until it reaches zero, when it triggers. -1 means the timer is inactive. For scripting, this is timer.hitpoints.
These are the things I discovered, and which don't appear to be documented:
1. The timer will trigger the script twice, once when it starts, and once when it fires. When it starts, event.other contains a value. When it fires, event.other is nil. So your script should ignore a timer trigger unless event.other is nil.
2. A timer can be started by a connection to a switch (toggled by script), but not by a lever - this does not work! The difference is that a switch is of type Handle and a lever is of tyoe Handle Trigger.
3. You would think you could start a timer from a script by not using a connection, and just setting timer.hitpoints to timer.max_hitpoints. Think again: the timer doesn't start.
4. However, if you want to stop the timer midway without a final trigger (for example, if your dallying player has left the restricted area voluntarily), you can
set timer.hitpoints back to -1 and that works!
You obviously need to get the switch and timer objects by using beacons (or beacon if they are on the same map square). The easiest way is to have separate beacons on separate squares as you can then use beacon.environment - if on the same square you would have to iterate through map_objects to find both items.
The overall behaviour of timers is so weird, that I am sure I must have missed something. If anyone knows more - please add to this thread!