Roll20 Wiki

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

@@ 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.
-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).
-=== 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}}
-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 version|1.0|2015-01-07|* Release}}

Roll20 Wiki

Navigation

Personal tools

Toolbox

Difference between revisions of "Script:InitiativeTracker"

From Roll20 Wiki

Revision as of 21:15, 13 January 2015

Syntax

Installation

Changelog