InitiativeTracker tracks initiative, rounds, and status conditions. The start of each round, as well as the start of each character's turn, can be announced in the chat. Status icons are automatically managed (counting down the last 9 rounds of the status duration), and status expiration can be announced in the chat as well.

It is recommended that this script be used in conjunction with the CommandShell module, which will improve output formatting and command discovery.

The Initiative Tracker

The initiative tracker is triggered automatically when you sort the entries in the turn tracker. Under the default settings, this will generate a message announcing the start of round 1, followed by a message announcing the start of the turn for the character at the top of the initiative order. These announcements can be disabled using the tracker command described below.

Each time the turn tracker advances, any status effects operating on any initiative count between the previous count and the current count will have their durations decremented. Any status whose new duration is zero or less will be removed; any status whose new duration is 9 or less will have its icon counter updated to reflect the number of rounds remaining. If the initiative count has wrapped around, the round counter will be incremented, and the start of the new round will be announced (if enabled). Finally, the start of the next character's turn will be announced (if enabled).

Tracker Commands

The tracker command provides several subcommands to affect the initiative tracker:

!tracker help

Display a help message listing the various subcommands.

!tracker round [num]

If NUM is provided, set the round counter to NUM. Otherwise, display the current value of the round counter.

!tracker forward

Advance the initiative counter to the next entry (this emulates clicking the "next turn" button in the turn tracker).

!tracker fwd

Synonym for !tracker forward.

!tracker back

Rewind the initiative counter to the previous entry.

!tracker start

Sort all the entries in the turn tracker and begin tracking initiative.

!tracker get [PARAM]

If PARAM is specified, display the value of the specified configuration parameter. Otherwise, display all configuration parameters. Valid values for PARAM are:

highToLow	Whether high initiative counts go before low initiative counts.
announceRounds	Whether to announce the start of each round.
announceTurns	Whether to announce the start of each character's turn.
announceExpiration	Whether to announce the expiration of status effects.

!tracker set <PARAM> [VALUE]

Set the specified configuration parameter to VALUE. If VALUE is omitted, it defaults to true.

!tracker enable <PARAM>

Set the specified configuration parameter to true.

!tracker disable <PARAM>

Set the specified configuration parameter to false.

!tracker toggle <PARAM>

Toggle the specified configuration parameter between true and false.

Status Effects

Status effects can be set for any token in the turn tracker. If a token is removed from the turn tracker, any status effects on it will be removed when its next turn would have come up. Each status effect consists of an icon, a description, and a duration. When the duration expires, the status effect will be removed automatically.

Status effects are managed via the status command, which provides the following subcommands:

!status help

Display a help message listing the various subcommands.

!status add <DUR> <ICON> <DESC>

Add DUR rounds of a status effect with the specified icon and description to the selected token(s). ICON must be one of the status icon names defined by Roll20 or an alias defined in the script in Tracker.STATUS_ALIASES. Use icons subcommand for a list of icons.

!status list

List all status effects on the selected token(s), along with their remaining duration.

!status show

Synonym for !status list.

!status remove [ID]

Remove the specified status effect (or all status effects from the selected token(s) if ID is omitted). Status effect ID can be obtained via the list subcommand. Be aware that the ID may change if any tracked status is removed, so use the list subcommand just before using this subcommand.

!status rem / delete / del

Synonyms for !status remove.

!status icons

List all available status icons (in the order in which they appear in the popup menu), plus all aliases.

Status icon names can be somewhat cryptic. It is recommended that you create your own aliases for frequently-used icons. This can be done by adding entries in Tracker.STATUS_ALIASES, defined near the top of the script. Each new alias should be a key, and the associated value should be an icon name from Tracker.ALL_STATUSES (defined just above Tracker.STATUS_ALIASES).