Difference between revisions of "Script:InitiativeTracker"
From Roll20 Wiki
(Created page with "{{script overview |name=InitiativeTracker |author={{user profile|503018|manveti}} |version=1.0 |lastmodified=2015-01-07}} '''InitiativeTracker''' tracks initiative, rounds, a...") |
|||
| Line 19: | Line 19: | ||
{{API command|tracker}} help | {{API command|tracker}} help | ||
{{syntaxbox end}} | {{syntaxbox end}} | ||
| − | + | Display a help message listing the various subcommands. | |
{{syntaxbox top|InitiativeTracker}} | {{syntaxbox top|InitiativeTracker}} | ||
{{API command|tracker}} round {{API parameter|name=num|optional=true}} | {{API command|tracker}} round {{API parameter|name=num|optional=true}} | ||
{{syntaxbox end}} | {{syntaxbox end}} | ||
| − | + | If NUM is provided, set the round counter to NUM. Otherwise, display the current value of the round counter. | |
{{syntaxbox top|InitiativeTracker}} | {{syntaxbox top|InitiativeTracker}} | ||
{{API command|tracker}} forward | {{API command|tracker}} forward | ||
{{syntaxbox end}} | {{syntaxbox end}} | ||
| − | + | Advance the initiative counter to the next entry (this emulates clicking the "next turn" button in the turn tracker). | |
{{syntaxbox top|InitiativeTracker}} | {{syntaxbox top|InitiativeTracker}} | ||
{{API command|tracker}} fwd | {{API command|tracker}} fwd | ||
{{syntaxbox end}} | {{syntaxbox end}} | ||
| − | + | Synonym for <code>!tracker forward</code>. | |
{{syntaxbox top|InitiativeTracker}} | {{syntaxbox top|InitiativeTracker}} | ||
{{API command|tracker}} back | {{API command|tracker}} back | ||
{{syntaxbox end}} | {{syntaxbox end}} | ||
| − | + | Rewind the initiative counter to the previous entry. | |
{{syntaxbox top|InitiativeTracker}} | {{syntaxbox top|InitiativeTracker}} | ||
{{API command|tracker}} start | {{API command|tracker}} start | ||
{{syntaxbox end}} | {{syntaxbox end}} | ||
| − | + | Sort all the entries in the turn tracker and begin tracking initiative. | |
{{syntaxbox top|InitiativeTracker}} | {{syntaxbox top|InitiativeTracker}} | ||
{{API command|tracker}} get {{API parameter|name=PARAM|optional=true}} | {{API command|tracker}} get {{API parameter|name=PARAM|optional=true}} | ||
{{syntaxbox end}} | {{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 | |highToLow | ||
|Whether high initiative counts go before low initiative counts. | |Whether high initiative counts go before low initiative counts. | ||
| − | |- | + | |- |
|announceRounds | |announceRounds | ||
|Whether to announce the start of each round. | |Whether to announce the start of each round. | ||
| − | |- | + | |- |
|announceTurns | |announceTurns | ||
|Whether to announce the start of each character's turn. | |Whether to announce the start of each character's turn. | ||
| − | |- | + | |- |
|announceExpiration | |announceExpiration | ||
|Whether to announce the expiration of status effects. | |Whether to announce the expiration of status effects. | ||
| Line 61: | Line 64: | ||
{{API command|tracker}} set {{API parameter|name=PARAM}} {{API parameter|name=VALUE|optional=true}} | {{API command|tracker}} set {{API parameter|name=PARAM}} {{API parameter|name=VALUE|optional=true}} | ||
{{syntaxbox end}} | {{syntaxbox end}} | ||
| − | + | Set the specified configuration parameter to VALUE. If VALUE is omitted, it defaults to true. | |
{{syntaxbox top|InitiativeTracker}} | {{syntaxbox top|InitiativeTracker}} | ||
{{API command|tracker}} enable {{API parameter|name=PARAM}} | {{API command|tracker}} enable {{API parameter|name=PARAM}} | ||
{{syntaxbox end}} | {{syntaxbox end}} | ||
| − | + | Set the specified configuration parameter to true. | |
{{syntaxbox top|InitiativeTracker}} | {{syntaxbox top|InitiativeTracker}} | ||
{{API command|tracker}} disable {{API parameter|name=PARAM}} | {{API command|tracker}} disable {{API parameter|name=PARAM}} | ||
{{syntaxbox end}} | {{syntaxbox end}} | ||
| − | + | Set the specified configuration parameter to false. | |
{{syntaxbox top|InitiativeTracker}} | {{syntaxbox top|InitiativeTracker}} | ||
{{API command|tracker}} toggle {{API parameter|name=PARAM}} | {{API command|tracker}} toggle {{API parameter|name=PARAM}} | ||
{{syntaxbox end}} | {{syntaxbox end}} | ||
| − | + | Toggle the specified configuration parameter between true and false. | |
=== Status Effects === | === Status Effects === | ||
| Line 83: | Line 86: | ||
{{API command|status}} help | {{API command|status}} help | ||
{{syntaxbox end}} | {{syntaxbox end}} | ||
| − | + | Display a help message listing the various subcommands. | |
{{syntaxbox top|InitiativeTracker}} | {{syntaxbox top|InitiativeTracker}} | ||
{{API command|status}} add {{API parameter|name=DUR}} {{API parameter|name=ICON}} {{API parameter|name=DESC}} | {{API command|status}} add {{API parameter|name=DUR}} {{API parameter|name=ICON}} {{API parameter|name=DESC}} | ||
{{syntaxbox end}} | {{syntaxbox end}} | ||
| − | + | 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. | |
{{syntaxbox top|InitiativeTracker}} | {{syntaxbox top|InitiativeTracker}} | ||
{{API command|status}} list | {{API command|status}} list | ||
{{syntaxbox end}} | {{syntaxbox end}} | ||
| − | + | List all status effects on the selected token(s), along with their remaining duration. | |
{{syntaxbox top|InitiativeTracker}} | {{syntaxbox top|InitiativeTracker}} | ||
{{API command|status}} show | {{API command|status}} show | ||
{{syntaxbox end}} | {{syntaxbox end}} | ||
| − | + | Synonym for <code>!status list</code>. | |
{{syntaxbox top|InitiativeTracker}} | {{syntaxbox top|InitiativeTracker}} | ||
{{API command|status}} remove {{API parameter|name=ID|optional=true}} | {{API command|status}} remove {{API parameter|name=ID|optional=true}} | ||
{{syntaxbox end}} | {{syntaxbox end}} | ||
| − | + | 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. | |
{{syntaxbox top|InitiativeTracker}} | {{syntaxbox top|InitiativeTracker}} | ||
{{API command|status}} rem / delete / del | {{API command|status}} rem / delete / del | ||
{{syntaxbox end}} | {{syntaxbox end}} | ||
| − | + | Synonyms for <code>!status remove</code>. | |
{{syntaxbox top|InitiativeTracker}} | {{syntaxbox top|InitiativeTracker}} | ||
{{API command|status}} icons | {{API command|status}} icons | ||
{{syntaxbox end}} | {{syntaxbox end}} | ||
| − | + | 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 <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>). | 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>). | ||
| + | |||
| + | === Changelog === | ||
| + | {{changelog version|1.0|2015-01-07|* Release}} | ||
Revision as of 17:44, 13 January 2015
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.
It is recommended that this script be used in conjunction with the CommandShell module, which will improve output formatting and command discovery.
Contents |
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:
| 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. |
!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).
Changelog
v1.0 (2015-01-07)
- Release
