Timers.zh is intended for users of any level of experience, but it would be best for users who understand how constants work, and how to implement functions in other code.

This library file includes one array, with an index size of '10', and assigns dummy constants to each of these ten elements. You will need to modify this to suit the needs of your game.

Otherwise, the main functions run inside any type of loop (e.g. the main while(true) loop of your global active script), and the functions to set, or re-set the timer, or to check the timer values, can be called from anywhere. This code includes an example global active script.

Set-up of this library is not technically complicated, but can be time-consuming, depending on how many timers you need, and how you want to remember them, and their values, when using functions in instructions.

The included ZIP archive contains a basic list of commands in a text file, with details on usage.

Detailed information on using Timers.zh follows, that assumes you are a novice at ZScript.

A Note About Arrays

This library uses a single array to hold all of its timer values, and the default array has ten (integer) elements. Thus, if you need more than ten timers, you will need to expand the side of the array.

It looks like this:

int Timers[10]={0,0,0,0,0,0,0,0,0,0};

Simply change the value '10' to the value that you need (max 214747), and add additional zeros to the set, separated by commas; save for the last value, that should not have a comma. (See above.)

Next, you will need to define your constants, so that they'll be useful.

Constants Set-Up

The header includes dummy constants for the included array, TV_MYTIMER_1 , to TV_MYTIMER_10 , that you should change to something you will easily remember, that doesn't conflict with other defined constants, or variables. For this reason, it's best to use a prefix--in this case, TI_, for TImer, and later TD for Timer Duration--followed by the name of the timer. TD_DUCK, or TD_EXPLOSION, would be good examples of easy to remember constants.

The number on the right side of these constants matches it to the array, so that you can easily modify the timer values, later.

If you have expanded the size of your array beyond 10 elements, you will want to add more constants for your additional timers here. The first element of an array is '0', and for that reason, TV_MYTIMER_1 = 0 : A reference to TV_MYTIMER_1 is passed as the value '0, when reading from, or writing to the array.

You may assign multiple constants to one index value, either for the purpose of naming conventions (e,g. TV_RED, TV_RUBY), or for other reasons; however you will want to avoid this unless you intend to use either term to reference the same timer.

The next set of constants, is a series of Duration Values, with the prefix 'TD_' (Timer Duration). These are not assigned to the array indices, but rather, they are a count (in frames) for pre-set durations. You may want to establish your own naming here too, but I've provided a list of pre-defined time durations, including fractional-seconds, seconds, and minutes.

You may use these as-is, and utilise multiplications thereof, or combinations thereof, to define durations; else specify a duration directly in an instruction,

Note If you need very long timers, you may need to use tiered timers to expand beyond the ZC MAX_INT limitations.

You will see that the number to the right of these is the length, in frames, for that constant, so if you have any durations that you expect to need commonly, this is the place to add them.

Note: You can manually enter values for timer durations as numbers, when coding instructions.

Using the Libraries

Once you have established your values, you can begin using the functions. The code includes a sample global active script, that runs one timer.

Timer Initialisation
The idea is that for each timer that you have running, you run this pair of functions:

setTimer(TI_MY_TIMER,TD_TIME);
reduceTimer(TI_MY_TIMER);

The first instruction, initiates the timer that you specify as TI_MY_TIMER, with a staring count of TD_TIME.

The second, when running in any loop, that has a Waitframe() instruction at its end, will decrement the same timer by '1' each frame. It is also overloaded to accept a custom value that you may specify:

reduceTimer(TI_MY_TIMER,3);

This would reduce a timer by a value of '3' per frame.

The setTimer() function will not reset the value of the timer when run in a loop, until[/i] that timer reaches '0'; and when that happens, it will automatically reset to the value specified as TD_TIME.

Using Timers

To use these timers, you call upon either the boolean functions checkTimer() and zeroTimer(). The first, checkTimer is less sensitive, and will return 'true' when the timer is at 1, or less; whereas the second, zeroTimer() is strict, and returns 'true' when the timer is exactly zero.

You may call these as any boolean condition:[/i]

if ( checkTimer(TI_MY_TIMER_1 ) {
    //Do something
}

Whatever instructions you placed where 'Do something' is noted, would execute when the timer TI_MY_TIMER_1 dropped below a value of '1'.

As an alternative, you may use the function returnTimer() to read the exact value of the timer, and use that as a condition. This can be useful in some circumstances, and you may use this with conditional statements (if, else, else if) similarly to the boolean conditions, or write custom-defined booleans to meet your needs.

Usage Syntax:

checkTimer(TI_TIMER);
zeroTimer(TI_TIMER);
returnTimer(TI_TIMER);

The remaining function allows arbitrary manipulation of timer values.

Example:

changeTimer(TI_MY_TIMER,151);

This would set the timer 'TI_MY_TIMER' to a value of '151', without regard to whatever value it holds at present.

Advanced Use

The above, is the most basic usage of this library, and Timers.zh includes methods of multiple, en-masse timer creation, and manipulation. Please read the enclosed documentation for more information.

This version (v1.5) released on 24th September, 2014, requires no other libraries, or headers.