Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Script:InitiativeTracker"

From Roll20 Wiki

Jump to: navigation, search
(major formatting changes)
Line 7: Line 7:
 
'''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.
 
'''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 [[Script:CommandShell|CommandShell]] module, which will improve output formatting and command discovery.
+
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 <code>!tracker</code> command described below.
 
+
=== 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 <code>tracker</code> 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).
 
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 ===
+
It is recommended that this script be used in conjunction with the [[Script:CommandShell|CommandShell]] module, which will improve output formatting and command discovery.
The <code>tracker</code> command provides several subcommands to affect the initiative tracker:
+
 
{{syntaxbox top|InitiativeTracker}}
+
=== Syntax ===
{{API command|tracker}} help
+
{{syntaxbox top|InitiativeTracker|formal=true}}
 +
{{API command|tracker}} {{API parameter|name=tracker action}} {{API parameter|name=tracker parameters|optional=true}}<br>
 +
{{API command|status}} {{API parameter|name=status action}} {{API parameter|name=status parameters|optional=true}}
 +
{{Formal API command|
 +
{{token|S}} {{rarr}} tracker {{token|tracker command|-}}
 +
{{token|S}} {{rarr}} status {{token|status command|-}}
 +
{{token|tracker command}} {{rarr}} help<br>
 +
{{token|tracker command}} {{rarr}} round {{integer|-}}
 +
{{token|tracker command}} {{rarr}} forward<br>
 +
{{token|tracker command}} {{rarr}} fwd<br>
 +
{{token|tracker command}} {{rarr}} back<br>
 +
{{token|tracker command}} {{rarr}} start<br>
 +
{{token|tracker command}} {{rarr}} get {{token|optional config|-}}
 +
{{token|tracker command}} {{rarr}} set {{token|config}} {{boolean|-}}
 +
{{token|tracker command}} {{rarr}} enable {{token|config|-}}
 +
{{token|tracker command}} {{rarr}} disable {{token|config|-}}
 +
{{token|tracker command}} {{rarr}} toggle {{token|config|-}}
 +
{{token|optional config}} {{rarr}} {{epsilon}}
 +
{{token|optional config}} {{rarr}} {{token|config|-}}
 +
{{token|config}} {{rarr}} highToLow<br>
 +
{{token|config}} {{rarr}} announceRounds<br>
 +
{{token|config}} {{rarr}} announceTurns<br>
 +
{{token|config}} {{rarr}} announceExpiration<br>
 +
{{token|status command}} {{rarr}} help<br>
 +
{{token|status command}} {{rarr}} add {{integer}} {{string}} {{string|-}}
 +
{{token|status command}} {{rarr}} list<br>
 +
{{token|status command}} {{rarr}} show<br>
 +
{{token|status command}} {{rarr}} remove {{token|id|-}}
 +
{{token|status command}} {{rarr}} rem {{token|id|-}}
 +
{{token|status command}} {{rarr}} delete {{token|id|-}}
 +
{{token|status command}} {{rarr}} del {{token|id|-}}
 +
{{token|status command}} {{rarr}} icons<br>
 +
{{token|id}} {{rarr}} {{epsilon}}
 +
{{token|id}} {{rarr}} {{string|-}}
 +
}}
 
{{syntaxbox end}}
 
{{syntaxbox end}}
Display a help message listing the various subcommands.
 
{{syntaxbox top|InitiativeTracker}}
 
{{API command|tracker}} round {{API parameter|name=num|optional=true}}
 
{{syntaxbox end}}
 
If NUM is provided, set the round counter to NUM.  Otherwise, display the current value of the round counter.
 
{{syntaxbox top|InitiativeTracker}}
 
{{API command|tracker}} forward
 
{{syntaxbox end}}
 
Advance the initiative counter to the next entry (this emulates clicking the "next turn" button in the turn tracker).
 
{{syntaxbox top|InitiativeTracker}}
 
{{API command|tracker}} fwd
 
{{syntaxbox end}}
 
Synonym for <code>!tracker forward</code>.
 
{{syntaxbox top|InitiativeTracker}}
 
{{API command|tracker}} back
 
{{syntaxbox end}}
 
Rewind the initiative counter to the previous entry.
 
{{syntaxbox top|InitiativeTracker}}
 
{{API command|tracker}} start
 
{{syntaxbox end}}
 
Sort all the entries in the turn tracker and begin tracking initiative.
 
{{syntaxbox top|InitiativeTracker}}
 
{{API command|tracker}} get {{API parameter|name=PARAM|optional=true}}
 
{{syntaxbox end}}
 
If PARAM is specified, display the value of the specified configuration parameter.  Otherwise, display all configuration parameters.  Valid values for PARAM are:
 
{| class="wikitable"
 
|-
 
! Value
 
! Description
 
|-
 
|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.
 
|}
 
{{syntaxbox top|InitiativeTracker}}
 
{{API command|tracker}} set {{API parameter|name=PARAM}} {{API parameter|name=VALUE|optional=true}}
 
{{syntaxbox end}}
 
Set the specified configuration parameter to VALUE.  If VALUE is omitted, it defaults to true.
 
{{syntaxbox top|InitiativeTracker}}
 
{{API command|tracker}} enable {{API parameter|name=PARAM}}
 
{{syntaxbox end}}
 
Set the specified configuration parameter to true.
 
{{syntaxbox top|InitiativeTracker}}
 
{{API command|tracker}} disable {{API parameter|name=PARAM}}
 
{{syntaxbox end}}
 
Set the specified configuration parameter to false.
 
{{syntaxbox top|InitiativeTracker}}
 
{{API command|tracker}} toggle {{API parameter|name=PARAM}}
 
{{syntaxbox end}}
 
Toggle the specified configuration parameter between true and false.
 
  
=== Status Effects ===
+
{{param description top}}
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.
+
{{param description|name=tracker&nbsp;action|value=The <code>!tracker</code> command can perform several actions:
 
+
* '''help''': display a help message detailing the various commands
Status effects are managed via the <code>status</code> command, which provides the following subcommands:
+
* '''round''': set or display the round counter
 
+
* '''forward''' (or '''fwd'''): Advance the turn order
{{syntaxbox top|InitiativeTracker}}
+
* '''back''': rewind the turn order
{{API command|status}} help
+
* '''start''': sort the turn order and begin tracking initiative
{{syntaxbox end}}
+
* '''get''': get the value(s) of one or all configuration parameters
Display a help message listing the various subcommands.
+
* '''set''': set the value of a configuration parameters
{{syntaxbox top|InitiativeTracker}}
+
* '''enable''': enable a configuration parameter
{{API command|status}} add {{API parameter|name=DUR}} {{API parameter|name=ICON}} {{API parameter|name=DESC}}
+
* '''disable''': disable a configuration parameter
{{syntaxbox end}}
+
* '''toggle''': toggle a configuration parameter on or off}}
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 <code>Tracker.STATUS_ALIASES</code>. Use <code>icons</code> subcommand for a list of icons.
+
{{param description|name=tracker&nbsp;parameters|value=Some actions accept additional parameters:
{{syntaxbox top|InitiativeTracker}}
+
* '''round''': If a number is provided, the round counter will be set to that value. Otherwise, the current round counter value will be displayed.
{{API command|status}} list
+
* '''get''': If the name of a configuration parameter is provided, the value of that configuration parameter will be displayed. Otherwise, the value of ''al'' configuration parameters will be displayed. The configuration parameters are:
{{syntaxbox end}}
+
** ''highToLow'': Whether high initiative counts go before low initiative counts.
List all status effects on the selected token(s), along with their remaining duration.
+
** ''announceRounds'': Whether to announce the start of each round.
{{syntaxbox top|InitiativeTracker}}
+
** ''announceTurns'': Whether to announce the start of each character's turn.
{{API command|status}} show
+
** ''announceExpiration'': Whether to announce the expiration of status effects.
{{syntaxbox end}}
+
* '''set''': A configuration parameter is required. If a value is also given, the parameter will be set to that value. Otherwise, the parameter will be set to <code>true</code>.
Synonym for <code>!status list</code>.
+
* '''enable''': Sets the given configuration parameter to <code>true</code>.
{{syntaxbox top|InitiativeTracker}}
+
* '''disable''': Sets the given configuration parameter to <code>false</code>.
{{API command|status}} remove {{API parameter|name=ID|optional=true}}
+
* '''toggle''': Toggles the value of the given configuration parameter. (If the value is currently <code>true</code>, it will be set to <code>false</code>, and vice versa.)}}
{{syntaxbox end}}
+
{{param description|name=status&nbsp;action|value=The <code>!status</code> command can perform several actions:
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 <code>list</code> subcommand.  Be aware that the ID may change if any tracked status is removed, so use the <code>list</code> subcommand just before using this subcommand.
+
* '''help''': display a help message detailing the various commands
{{syntaxbox top|InitiativeTracker}}
+
* '''add''': add a turns of a status effect to the selected token(s)
{{API command|status}} rem / delete / del
+
* '''list''' (or '''show'''): list the status effects remaining on the selected token(s), along with the status' remaining durations
{{syntaxbox end}}
+
* '''remove''' (or '''rem''', '''delete''', or '''del'''): remove one or all status effects from the selected token(s)
Synonyms for <code>!status remove</code>.
+
* '''icons''': display the names of all status icons and their aliases}}
{{syntaxbox top|InitiativeTracker}}
+
{{param description|name=status&nbsp;parameters|value=Some actions accept additional parameters:
{{API command|status}} icons
+
* '''add''': Requires an integer duration, the name (or alias) of a status icon, and a description of the status.
{{syntaxbox end}}
+
* '''remove''': If a status id is provided, the status will be removed. Otherwise, all statuses will be removed. Use <code>!status list</code> to discover the appropriate values for ''id''.}}
List all available status icons (in the order in which they appear in the popup menu), plus all aliases.
+
{{param description bottom}}
  
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 <code>Tracker.STATUS_ALIASES</code>, defined near the top of the script.  Each new alias should be a key, and the associated value should be an icon name from <code>Tracker.ALL_STATUSES</code> (defined just above <code>Tracker.STATUS_ALIASES</code>).
+
=== Installation ===
 +
Status icon names can be somewhat cryptic.  You can create your own aliases for frequently-used icons by adding entries in <code>Tracker.STATUS_ALIASES</code>, defined near the top of the script.  Each new alias should be a key, and the associated value should be an icon name from <code>Tracker.ALL_STATUSES</code> (defined just above <code>Tracker.STATUS_ALIASES</code>). This is optional, but it may assist in the usage of <code>!status add</code>.
  
 
=== Changelog ===
 
=== Changelog ===
 
{{changelog version|1.0|2015-01-07|* Release}}
 
{{changelog version|1.0|2015-01-07|* Release}}

Revision as of 21:15, 13 January 2015

API ScriptAuthor: manveti
Version: 1.0
Last Modified: 2015-01-07
Code: InitiativeTracker
Dependencies: None
Conflicts: None

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.

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).

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

Syntax

!tracker <tracker action> [tracker parameters]
!status <status action> [status parameters]
Formally:

S

→ tracker tracker command


S

→ status status command


tracker command

→ help

tracker command

→ round integer

tracker command

→ forward

tracker command

→ fwd

tracker command

→ back

tracker command

→ start

tracker command

→ get optional config


tracker command

→ set config
boolean

tracker command

→ enable config


tracker command

→ disable config


tracker command

→ toggle config


optional config

→ ε

optional config

config


config

→ highToLow

config

→ announceRounds

config

→ announceTurns

config

→ announceExpiration

status command

→ help

status command

→ add integer string string

status command

→ list

status command

→ show

status command

→ remove id


status command

→ rem id


status command

→ delete id


status command

→ del id


status command

→ icons

id

→ ε

id

string
Parameter Values
tracker action The !tracker command can perform several actions:
  • help: display a help message detailing the various commands
  • round: set or display the round counter
  • forward (or fwd): Advance the turn order
  • back: rewind the turn order
  • start: sort the turn order and begin tracking initiative
  • get: get the value(s) of one or all configuration parameters
  • set: set the value of a configuration parameters
  • enable: enable a configuration parameter
  • disable: disable a configuration parameter
  • toggle: toggle a configuration parameter on or off
tracker parameters Some actions accept additional parameters:
  • round: If a number is provided, the round counter will be set to that value. Otherwise, the current round counter value will be displayed.
  • get: If the name of a configuration parameter is provided, the value of that configuration parameter will be displayed. Otherwise, the value of al configuration parameters will be displayed. The configuration parameters 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.
  • set: A configuration parameter is required. If a value is also given, the parameter will be set to that value. Otherwise, the parameter will be set to true.
  • enable: Sets the given configuration parameter to true.
  • disable: Sets the given configuration parameter to false.
  • toggle: Toggles the value of the given configuration parameter. (If the value is currently true, it will be set to false, and vice versa.)
status action The !status command can perform several actions:
  • help: display a help message detailing the various commands
  • add: add a turns of a status effect to the selected token(s)
  • list (or show): list the status effects remaining on the selected token(s), along with the status' remaining durations
  • remove (or rem, delete, or del): remove one or all status effects from the selected token(s)
  • icons: display the names of all status icons and their aliases
status parameters Some actions accept additional parameters:
  • add: Requires an integer duration, the name (or alias) of a status icon, and a description of the status.
  • remove: If a status id is provided, the status will be removed. Otherwise, all statuses will be removed. Use !status list to discover the appropriate values for id.

Installation

Status icon names can be somewhat cryptic. You can create your own aliases for frequently-used icons 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). This is optional, but it may assist in the usage of !status add.

Changelog

v1.0 (2015-01-07)

  • Release