Timer

[mattekure]

This extension adds a timer capability into FG. While the extension may be useful for some purely for its timer function, it is also intended for other extension authors which can tie into the timer system. The inspiration for this came from the Combat Timer extension, but its implementation is entirely different, so it doesnt have the same limitations of that method, though it does have its own set of limitations as detailed below.

Forge: https://forge.fantasygrounds.com/shop/items/665/view

Details
Description: This extension uses the recently added Interface.openURL() function to create an internal counter. It uses the worldtimeapi.org functionality to retrieve the time and increment the timer. Due to the asynchronous nature of that function call, it is possible to recursively call it without much impact to FG performance. The counter has a resolution of 1 second. When the timer is started, it continuously counts up. There is a button in the sidebar to open the timer window. The timer will continue running even if the window is closed. You can also start/stop the timer using the slash command /timer [start|stop]

Caveats: The counter running is heavily dependant on the hosts network stability. While it does not add much CPU usage to FG, in my testing it did use about 500kbps of network bandwidth constantly. The timer may unexpectedly stop if there is network instability or issues with the worldtimeapi.org site. In my testing, I have had it running successfully for over 3 hours. I have also had it stop in a few as 5 minutes, so YMMV. There is nothing sent to/from FG clients connected, so all of the network traffic occurs on the host side.

Extension Authors
One of my goals in creating this extension is to make it useful for other extension authors to have a way to hook into a timer. For that reason, I am leaving it installed to the extensions directory so anyone can take a look at how I made it. I have also included an API to hook into the timers. At any time, there should only ever be 1 timer running. For other extensions, they should use the register/unregister api functions below to hook into the running timer.

If anyone has any suggestions for improving it, I'd love to hear it.

API Functions
TimerManager.startTimer() - Begins the timer.
Parameters: none
Return Value: none

TimerManager.stopTimer() - Stops the timer
Parameters: None
Return Value: None

TimerManager.registerTimerAction(fn, delay) - Register a callback function to occur when the timer updates its value. (I typically register this in a windows onInit())
Parameters:
fn - The function to call
delay - An integer number of seconds between calls. Min 1. A value of 1 will call the registered callback function once per second. a value of 2 will occur every 2 seconds, etc.
Return Value: none

TimerManager.unregisterTimerAction(fn, delay) - Unregister a previously registered function. If you have functions registered by a window, I highly recommend to unregister all actions when the window is closed to avoid having old or unlinked entries in the callback list. Examples in the timerwindow in the extension. the parameters must match exactly for it to unregister properly.
Parameters:
fn - the function previously registered.
delay - the delay value previously registered.

TimerManager.outputTime(nTime) - Output the current timer value in HRS:MIN:SEC to the chat.

[mattekure]

reserved for future details

[YAKO SOMEDAKY]

What's the idea behind the Timer extension, is it enabling and disabling effects? Is it to control day and night effect on a map, is it to make the lighting resources fade automatically? I ask and quote this and even mention a Foundry module that seems possible in the FGU which is a kind of Timer where the Master sets the time, sets the speed of this Timer and then doesn't worry if the player forgot or not to deactivate the armor arcana of your character, if the character's Torch is still illuminating and even if it's day or night after a long journey from one realm to another realm and yes I think that's amazing and I believe the FGU can have that.

[mattekure]

What's the idea behind the Timer extension, is it enabling and disabling effects? Is it to control day and night effect on a map, is it to make the lighting resources fade automatically? I ask and quote this and even mention a Foundry module that seems possible in the FGU which is a kind of Timer where the Master sets the time, sets the speed of this Timer and then doesn't worry if the player forgot or not to deactivate the armor arcana of your character, if the character's Torch is still illuminating and even if it's day or night after a long journey from one realm to another realm and yes I think that's amazing and I believe the FGU can have that.

Without getting into the technical details of why and how, the extension adds a new functionality that did not exist in FG before, the ability to set a running timer and have events fire on some set schedule. I deliberately made it so that other extensions could hook into the timer capabilities so that they can do all kinds of fancy stuff, that go way beyond the scope of this extension.

[YAKO SOMEDAKY]

So in theory can I use it with the Clock Adjuster?

[mattekure]

So in theory can I use it with the Clock Adjuster?

If the author adds the hooks, yes.

[DustyLensCap42]

I'm looking to track time on turns, and I've developed another extension to interact with your added hooks. It simply restarts the time at as the combat tracker moves through the characters (PC & NPC). Is there a reason why it reaches out to a website rather than using the lua function os.date? Feels like it might be more efficient for my purposes in that it wouldn't use the 500kbps, but I'm new to lua and I've never created an extension before. I am but a mere coding hobbyist. It'll take me a bit to try and change it out to test it, so I thought I'd ask. Because I know date functions in some coding applications can be dangerous to system resources if they're calling a time function constantly.

Thank you so much for putting out this extension mattekure!

[mattekure]

I'm looking to track time on turns, and I've developed another extension to interact with your added hooks. It simply restarts the time at as the combat tracker moves through the characters (PC & NPC). Is there a reason why it reaches out to a website rather than using the lua function os.date? Feels like it might be more efficient for my purposes in that it wouldn't use the 500kbps, but I'm new to lua and I've never created an extension before. I am but a mere coding hobbyist. It'll take me a bit to try and change it out to test it, so I thought I'd ask. Because I know date functions in some coding applications can be dangerous to system resources if they're calling a time function constantly.

Thank you so much for putting out this extension mattekure!

Certainly. The reason for the website usage is touched upon briefly in the description. Basically it would be very simple to use a function like os.clock or os.date to get the time, but this creates a problem. Typically using a function like this would require some form of loop to check the time, see how much has passed, then check again. Lua doenst have any available functions for waiting or delaying anything, so you cant just say "wait for 1 second". So you end up looping. The major problem with looping like this is that your function isnt returning, so the rest of the FG code on that thread is not being run. This basically causes the rest of FG to come to a grinding halt.

FG does however offer 2 asynchronous functions, meaning that using them allows them to run, but the rest of FG continues to run on its own thread. The two functions are sending an Out of Band (OOB) message and sending a request for a URL. Both of these functions rely on waiting for something else to respond, so FG allows them to fire and continue the processing thread while it waits for a response. When the response arrives, it gets processed in its own separate thread. This allows the clock to run without impacting the rest of FG. So basically it works like this.

Start timer
Timer requests the time from the website and immediately returns allowing FG to run.
When the website returns with the time, it records it, then immediately calls the web function again. starting a loop that we use to track the time.

without the web calls, FG would lock up or you wouldnt be able to keep the timer running.

[DustyLensCap42]

Okay cool, thanks so much for taking the time to give a good explanation! I'm going to play with sending it to a third-party timekeeper with a delay function like the website but is a local file, maybe HTML, pulling data from the os clock. Thanks again.