Roll20 Wiki

Revision as of 02:24, 10 April 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 4: / Line 4: @@
 |version=1.0
 |lastmodified=2015-01-07}}
-{{stub}}
-Initiative and status tracker.  Round counter, optional round and turn announcements, management of limited-duration status effects (with countdown of last 9 rounds in status icon)
+'''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.
-<br clear="all">
+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).
+It is recommended that this script be used in conjunction with the [[Script:CommandShell|CommandShell]] module, which will improve output formatting and command discovery.
+=== Syntax ===
+{{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}}
+{{param description top}}
+{{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
+* '''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}}
+{{param description|name=tracker&nbsp;parameters|value=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 <code>true</code>.
+* '''enable''': Sets the given configuration parameter to <code>true</code>.
+* '''disable''': Sets the given configuration parameter to <code>false</code>.
+* '''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.)}}
+{{param description|name=status&nbsp;action|value=The <code>!status</code> 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}}
+{{param description|name=status&nbsp;parameters|value=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 <code>!status list</code> to discover the appropriate values for ''id''.}}
+{{param description bottom}}
+=== 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:Initiative Tracker"

From Roll20 Wiki

Revision as of 02:24, 10 April 2015

Syntax

Installation

Changelog