Foundry Hourglass

Configurable animated graphical timers & round trackers for foundry VTT that can be shown by the GM to all players.

Hourglass Options

To create a new hourglass, a Game Master may select the hourglass icon under the Token Controls.

This will open the options window for you to configure your hourglass.

• Timer Type - The type of animated graphic to show to players. Options currently include "Hourglass" & "Flipdown Clock".
• Title - The display name of the timer that will appear at the top left.
• Style - The visual style of the timer graphic to be displayed.
• Size - The display size of the timer window: Tiny, Small, Medium & Large.
• Duration Type - Whether the timer should be an automatic (timed) or manual "on click" countdown.
• Duration (Seconds/Minutes) - The time taken for the hourglass to complete.
• Sand Colour - The hex value for the colour of the sand in the hourglass. Can be typed manually or selected using the colour picker.
• Display time as text? - Indicates whether you wish to display the remaining time as a text overlay on the hourglass.
• End message - Text to be displayed as an overlay on the hourglass after the duration has passed.
• End sound - Sound to be played to all players after the duration has passed (more details below).
• Close after duration? - Indicates whether you wish the timer window to automatically close (for all users) after the duration has passed.

Usage

The start hourglass button, once pressed, will cause a new hourglass window to appear on the screen of all players currently in the game session using the chosen options:

Once the duration has elapsed, the remaining time will dissapear and be replaced by the end message (if one has been entered):

An end sound will also be played to all players (if one has been selected).

Players can move the hourglass around the screen while it is counting down. They do also have the option of closing it, though they should only do this once the duration has elapsed.

Once an hourglass has been created, the module will retain the "last used" settings for the duration of the session. This means that you can create subsequent hourglasses using the same settings without having to re-enter them.

Multiple hourglasses can be opened by a GM at one time, should you wish to track multiple events simultaneously.

Manual "on click" control

Timers can be set to "manual" control by setting the Duration type to "Manual (user click)" in the hourglass options.

The manual timers feature a forward and backward button that, when clicked, will decrease and increase the remaining increments respectively. This could potentially be used by GMs to include manually controlled/incremented events or round tracking within their games. Both forward and back buttons are only visible to users with the GM role.

Styles

As well as changing the sand colour, each timer has a range of different visual styles to choose from.

Each style has all of the same functionality and customisation options as the default.

A heartfelt thankyou to artist Zael for creating some fantastic alternative timer styles with a range of themes.

Presets

Game Masters have the ability to save Hourglass Options as Presets. This will allow frequently used configurations to be quickly recalled and displayed.

• Select Preset - Presents a dropdown list of all previously saved Hourglasses. A GM can select a preset from this list to populate all options fields with data saved for that preset.
• Save New - Will persist all currently entered options as a new Preset with a name matching the Title field.
• Update Selected - Will update an existing selected Preset with currently entered options. If the title field has been changed, the name of the preset will also be updated. If no Preset is selected from the dropdown, this button will be disabled.
• Delete Selected - Will delete an existing selected preset. If no Preset is selected from the dropdown, this button will be disabled.

End Sound

Games masters can choose to play a sound at the end of the timer duration by selecting it from the "End Sound" dropdown in the options window.

Once selected, the sound can be previewed (in the GM's client only) by pressing the "Play" button on the right of the dropdown.

There are a range of pre-loaded sounds to choose from. The GM may alternatively choose to add their own sound from a file by selecting "Select from audio file...". Once selected, the GM can use the file picker to select a previously uploaded audio file or upload a new one.

When an End Sound is selected, this sound will play in all clients where the timer window appears once the timer duration has elapsed.

Timer Controls

Once a timer has been created, the countdown & animation can be paused or restarted by use of the "Timer Controls" in the top right of the timer window. The "Timer Control" buttons are only visible for users with GM role.

Pausing

Pressing the "pause" button will have the effect of pausing the countdown for all players.

This will cause the animation to stop playing and for the words "(Paused)" to appear in the text area of the window. In the case where "Display time as text" has been selected, the "(Paused)" indicator will be appended to the remaining time.

To resume the countdown, the GM can simply press the "Resume" button (which has replaced the "Pause" button) in the top right of the window.

Restarting

Pressing the "restart" button will have the effect of restarting the countdown and animation for all players.

The timer can be restarted at any time, including after the duration is expired & when paused.

If a player has closed their timer window, the restart will also have the added effect of redisplaying it for them.

Closing the Timer

Closing a timer window as a user with GM role will also close that timer for all other players.

Pressing the "close" button as a non-GM user will still only close the window for yourself.

Macro Support

From version 1.9 the ability to show and start Hourglass timer windows from macros has been introduced.

To access the new hourglass API, enter the following line as a Script:

game.modules.get('hourglass').api

The following methods are available:

• showTimer(duration: number) - Displays and starts a default hourglass with the entered duration.
• showTimerPreset(presetTitle: string, duration: number = null) - Displays and starts a previously saved preset timer with the matching title property. The duration for the preset timer can be overridden by entering a duration (in seconds) into the second optional parameter. For countdown timers, this property is set as the "duration seconds". For manual timers, this property is set as the "increments".
• closeAllTimers() - Closes all open timers for all players.

As the Hourglass module is limited to use by GM and Assistant GM users, non-GM players will not have access to call these API methods.

Example Usage:

Popout!

The Popout! module is disabled for Hourglass Timer windows due to compatibility issues.