How to: Use Timers in JASS

Tutorial By tooltiperror

([ljass]type timer extends handle[/ljass])
A timer is a 32-bit pointer. It is similar to a stopwatch, in JASS you can start a timer and execute a function you chose when the time has elapsed. You might think you can just use [ljass]TriggerSleepAction[/ljass] or [ljass]PolledWait[/ljass] rather than use a timer, but they are inaccurate on single player, and become even worse on Using timers can seem daunting for beginning JASSers even though they are quite simple. This tutorial will explain how to use JASS2 timers and then timer systems in increasing difficulty.

The simplest timer example has three important parts to it.

The Declaration — The creation of the timer.
Life of a Timer — Entering the duration for the timer to run and starting it.
The Decline — Destroying the timer and nulling it.

Here's a commented snippet of code explaining the use of a timer.

It's pretty self explanatory. A problem with timers is that you need to pause them before you destroy them. If you don't, you can get some strange bugs like timers being fired and recurring after you destroy them.

You might notice in the first example we pass the argument [ljass]false[/ljass] to the [LJASS]TimerStart[/LJASS] function. The name of that argument is [ljass]periodic[/ljass]. In our example, it is false, so the timer is not periodic. If we passed [ljass]true[/ljass] instead, the function would run every five seconds.

Another important point to make use of the event response [ljass]GetExpiredTimer[/ljass]. It returns the timer that expired to run the current function. Returns null if the function was not run by a timer (not sure why you would run into that circumstance anyways). Here's an example.

Examples are examples, what if we want something more practical, like an MUI spell that kills the target after 5 seconds? The problem is that we don't want it to fail if someone pauses the game or lags. Perfectly possible with timers. The solution is to store the target in a [ljass]hashtable[/ljass], by the Handle ID of the timer. When we get the expired timer in the handler function, it will have the same Handle ID so we can get the same unit.

At this point, you should know enough of how to use timers in your spells, libraries, or whatever you need precise time instead. If you want to use vJASS and timers combined, keep reading.

TIMERUTILS (Note: The rest of this tutorial now uses vJASS)
Probably the most widely used timer system in WC3 modding, TimerUtils was written by Vexorian first using [ljass]gamecache[/ljass] and now utilizing [ljass]hashtable[/ljass]s. It replaces [ljass]CreateTimer[/ljass] with [ljass]NewTimer[/ljass] and [ljass]DestroyTimer[/ljass] with [ljass]ReleaseTimer[/ljass]. A simple example should suffice. This is the same as Example #1 but it uses TimerUtils functions.

TimerUtils uses a different system than normal timers for increased efficiency. However, the best part of TimerUtils is two more functions it provides, [ljass]SetTimerData[/ljass] and [ljass]GetTimerData[/ljass]. Here's yet another timer example with those functions.

You can also use structs, however. You see, structs are really just integers. So you can pass any struct to [ljass]SetTimerData[/ljass], like this.

You can now store all your spell information in the struct and use TimerUtils, so making timed effects is easy.

Key Timers 2
A bit after the time Vexorian wrote TimerUtils, Jesus4Lyf entered the timer industry with his own attempt at a timer system. His used some complicated method to handle timers all differently. The result was Key Timers. Cohadar hounded him some more and he came up with an even more efficient system, Key Timers 2. Abbreviated as KT2 or KT, it handled low and high period timers differently. At its time it may have been better than TimerUtils, but now it's only useful for people with weird interface fetishes and for compatibility (read: new content should use TimerUtils) so this is only one example for those of you who want to use the interface.

Some time after modules came out, Jesus4Lyf thought it'd be cool to make an object oriented timer system or something, I don't really know why, but he felt like making some cool interface I guess. He pretty much succeeded and made the super kinky Timer32 (T32). It's the most efficient timer system to date and very useful for writing your code inside of a struct. The idea is that if you have a method called periodic in your struct and you call [ljass].startPeriodic[/ljass] it will be run every 0.03125 seconds. However, the period can be changed so you use the public variable [ljass]T32_PERIOD[/ljass] instead. You also get [LJASS]T32_FPS[/ljass] (1/T32_PERIOD) to use to calculate when a whole second has gone by. It's easier to understand with an example.

At this point you should know how to use timers, with either vanilla JASS or also with vJASS. Here are some additional links for you to read from:
Rising_Dusk's Timer Tutorial — Click Me!
Viikuna's Timer Tutorial — Click Me!
Weep's GTS — Click Me!


Click here to comment on this tutorial.
Blizzard Entertainment, Inc.
Silkroad Online Forums
Team Griffonrawl Trains Muay Thai and MMA fighters in Ohio.
Apex Steel Pipe - Buys and sells Steel Pipe.