Document GetTimerPos in Globalfunctions_General

[ericoporto]

https://github.com/adventuregamestudio/ags-manual/wiki/Globalfunctions_General#settimer

int  GetTimerPos(int timerID)

This function returns the remaining ticks for the timer timerID. It will return 0 when the timer is not running and 1 when it's expiring.

There are 20 available timers, with timerIDs from 1 to 20. This function will error if the timerID is invalid, either lower than 1 or bigger than 20.

problem: can't figure a good example for this, perhaps a bomb with a counter in a label?

/// Returns the specified timer's time value; returns 0 if timer is not running, and 1 if it's expiring.
import int  GetTimerPos(int timerID);

• Forum request for this

What I'm suggesting here is a GetTimer() function, which simply returns the number of cycles left on a timer. My reason for this is twofold. Firstly, sometimes you'll want to be able to do something in the middle of a timer, without setting up another timer. Secondly, it would provide a way to see whether or not a timer is running, without incurring the IsTimerExpired()'s OFF state.

• Added in commit adventuregamestudio/ags@0ff1596

Needs a See also to SetTimer.

[ericoporto]

Documented below but the example isn't actually working, maybe a bug in the engine. I will leave it open until more information is available.

https://github.com/adventuregamestudio/ags-manual/wiki/_compare/acbcd18831b23ccee965ae00580ec25e57a71a2f...7186d4cfcdfdc2384cd9e81451a893c6d387b76a

[ericoporto]

Fixed docs https://github.com/adventuregamestudio/ags-manual/wiki/_compare/7186d4cfcdfdc2384cd9e81451a893c6d387b76a...4cfe75c98c819f23e704883fb6cdff54fd372dc8

From comment in forums

https://www.adventuregamestudio.co.uk/forums/editor-development/feature-request-gettimer-function/msg636667761/#msg636667761

@eri0o this is the problem with the current Timer implementation. It stays at 1 UNTIL user calls IsTimerExpired.
Add IsTimerExpired check somewhere in the script, and that should fix this infinite timer.

[ericoporto]

add note on stop timer using SetTimer(id, 0)

https://github.com/adventuregamestudio/ags-manual/wiki/_compare/4cfe75c98c819f23e704883fb6cdff54fd372dc8...d42e32812d331700e4ebac5382274b05cbb7d197