Difference between revisions of "Script:Group Initiative"
From Roll20 Wiki
Andreas J. (Talk | contribs) m (→Configuring for Specific Sheets) |
Andreas J. (Talk | contribs) m |
||
Line 171: | Line 171: | ||
<br> | <br> | ||
<br> | <br> | ||
+ | [[Category:Featured articles]] |
Revision as of 21:08, 10 September 2021
Version: 0.9.35
Last Modified: 2020-10-01
Code: GroupInitiative
Dependencies: None
Conflicts: None
![]() | This page have only some info on the API, and to see the latest documentation for it, run the !group-init --help command inside a game. |
Main Page: API:Script Index
Overview
GroupInitiative adds a command for rapidly adding large groups of tokens to the t Turn Tracker. As of v0.3, there are quite a few configuration commands (some examples below).
For full documentation of API, run the !group-init --help
command inside a game.
The basic process followed by the script is this:
- Remove any tokens that already have a turn.
- For all selected tokens, find the character they represent.
- For each character, figure out the initiative bonus.
- Initiative bonuses are calculated using Bonus Stat Groups. Each Bonus Stat Group is a collection of Attribute Names and Stat Adjustment operations to apply to them.
- Bonus Stat Groups are evaluated in order. The first one that produces a bonus is used. If a character doesn't have one of the Attribute Names listed in the Bonus Stat Group (or that Attribute Name does not contain a valid number), that group does not produce a bonus.
- The selected Roller is used to generate the rolls for each token, with the bonus for its character applied (or 0 if it doesn't have a character).
- Add each token to the t Turn Tracker.
Contents |
Commands
Rolls
!group-init
- This is the root api command. If you have any tokens selected, it will add them to the initiative order. If you don't have anything selected, it will show the
--help
.
- This is the root api command. If you have any tokens selected, it will add them to the initiative order. If you don't have anything selected, it will show the
!group-init --bonus <bonus>
- This command is just line the bare
!group-init
roll, but will add the supplied bonus to all rolls. The bonus can be from an Inline Roll.
- This command is just line the bare
!group-init --reroll [bonus]
- This command rerolls all of the tokens currently in the turn order as if they were selected when you executed
!group-init
. An optional bonus can be supplied, which can be the result of an inline roll.
- This command rerolls all of the tokens currently in the turn order as if they were selected when you executed
!group-init --ids [...]
- This command uses the configured Roller to determine the initiative order for all tokens whose ids are specified.
!group-init --adjust <adjustment> [minimum]
- Applies an adjustment to all the current Turn Order tokens (Custom entries ignored). The required adjustment value will be applied to the current value of all Turn Order entries. The optional minium value will be used if the value after adjustiment is lower, which can end up raising Turn Order values even if they were already lower.
!group-init --adjust-current <adjustment> [minimum]
- This is identical to
--adjust
, save that it is only applied to the top entry in the Turn Order.
- This is identical to
Other
This is identical to --adjust, save that it is only applied to the top entry in the Turn Order.
!group-init --help
- This shows the help, which includes state information about the currently selected Roller, available Stat Adjustment Options, and the ordered list of Bonus Stat Groups.
!group-init --sort
- Will sort everything in the t Turn Tracker. Good to run after having all intitiatives rolled.
!group-init --toggle-turnorder
- Opens or closes the Turn Order window.
!group-init --clear
- Removes all tokens from the Turn Order. If Auto Open Init is enabled, it will also close the Turn Tracker box.
!group-init --add-group --<adjustment> [--<adjustment>] <attribute name[|<max|current>]> ...
- This command adds another Bonus Stat Group to the end of the list. Examples and further explanation below.
!group-init --del-group <number>
- Removes the Bonus Stat Group identified by number.
!group-init --promote <number>
- Moves the Bonus Stat Group identified by number up one slot.
!group-init-config --set-roller <roller name>
- Sets the Roller to use for figuring initiative.
Rollers
There are currently 4 different Rollers:
- Least-All-Roll -- Roll 1d20+Bonus for every token, then take the lowest number as the initiative for all tokens. (Bryan K.)
- Mean-All-Roll -- Roll 1d20+Bonus for every token, then take the average (rounded down) roll as the initiative for all tokens.
- Individual-Roll -- Roll 1d20+Bonus for each token and set each token's initiative to whatever it rolled. (James the DM, GenKitty, etc)
- Constant-By-Stat -- Set the initiative to whatever the Bonus for that token is. (Michael H.)
Add-Group Detailed Explanation
The --add-group
command creates a new Bonus Stat Group. It takes one or more attribute specifications. An attribute specification is made up of one or more Stat Adjustment Options, followed by an Attribute Name (optionally with |max
on the end).
Stat Adjustment Options
- Bare -- Use this when you want just the attributes value. This will add a Bonus Stat Group with just the attribute dexterity in it.
- Example: !group-init --add-group --Bare dexterity
- Floor -- Use this to compute the floor of the value. This is useful when you have attributes that are decimal values, but you want a whole integer.
- Example: !group-init --add-group --Floor skill bonus
- Ceiling -- The same as Floor, but returns the next highest whole integer. The Bonus Stat Group added by this command would turn the attribute skill bonus from 2.35 to 3:
- Example: !group-init --add-group --Ceiling skill bonus
- Bounded:<low>:<high> -- Use this to restrict the value of an attribute to a particular range. This would specify a Bonus Stat Group where dexterity can only be between -2 and +2:
- 'Example: !group-init --add-group --Bounded:-2:2 dexterity
- Note: To leave a value unrestricted, you can leave the bound for that side empty. This would specify a Bonus Stat Group where dexterity has a maximum value of +4, but can be as low as it wants:
- Example: !group-init --add-group --Bounded::4 dexterity
- Stat-DnD -- Use this to convert an attribute from a Dungeons and Dragons Stat into the Stat's associated bonus. 18 becomes 4, 7 becomes -2, etc. This would specify a Bonus Stat Group which finds the stat bonus for the dexterity stat:
- Example: !group-init --add-group --Stat-DnD dexterity
Advanced Examples
You can chain multiple Stat Adjustment Options together. This would specify a Bonus Stat Group where dexterity is first converted to a Dungeons and Dragons stat bonus, and then is bounded to a maximum of +2:
!group-init --add-group --Bounded::2 --Stat-DnD dexterity
Stat Adjustment Options always operate on the value to the right. In the example above, Bounded would be applied to whatever is returned from Stat-DnD.
You can also chain multiple attribute specifications together. The Bonus is calculated by adding the results of each together. This would create a Bonus Stat Group that is the sum of the dexterity and initiative stats:
!group-init --add-group --Bare dexterity --Bare initiative
A more complicated example. This would specify a Bonus Stat Group which consists of the sum of the Dungeons and Dragons stat bonus computed for the max field of dexterity, the Dungeons and Dragons stat bonus computed from the max field of wisdom limited to a maximum of +2, and the current value of initiative.
!group-init --add-group --Stat-DnD dexterity|max --Bounded::2 --Stat-DnD wisdom|max --Bare initiative
Computing the Bonus
When the Bonus is computed for a character, the Bonus Stat Groups are considered in order. The first Bonus Stat Group to produce a number is used. When a Bonus Stat Group is evaluated, it will produce a number as long as every referenced attribute is present and numeric on the character.
Example: Assume you have the following 3 stat groups:
-
dexterity|current
+initiative|current
+rage|current
-
dexterity|current
+initiative|current
-
dexterity|current
If a character has attributes named both dexterity
and initiative
, but doesn't have one named rage
, the first Bonus Stat Group would not produce a number. In that case, the second Bonus Stat Group would produce a number, which would then be used as the Bonus.
Hopefully that will be enough documentation that people can use this!
Configuring for Specific Sheets
The API have built in Configuration for a number of sheet, that can be selected through the chat menu when you call !group-init --help
.
Preset options exists for the following sheets:
- D&D 5E by Roll20
- D&D 5E (Shaped)
- Stargate RPG by Wyvern Gaming
Here are configuration for other sheets that you can simply copy and run yourself:
D&D 5E by Roll20-character Sheet
!group-init --del-group 1 !group-init --add-group --bare initiative_bonus
D&D 5E (Shaped)- character sheet
!group-init-config --set-dice-count|0 !group-init --del-group 1 !group-init --add-group --bare initiative_formula
Pathfinder Community-character sheet
!group-init --del-group 1 !group-init --add-group --bare init --tie-Breaker init|current (Optional) !group-init-config --set-dice-count|1 !group-init-config --set-max-decimal|2 !group-init-config --set-roller|Individual-Roll !group-init-config --sort-option|Descending !group-init-config --toggle-replace-roll
Star Wars D6 char sheet (This is incomplete)
- only rolls dexterity number of d6s, and adds dexterity-pip & initiative-pip bonus to roll
- doesn't roll wild die
- doesn't account for anything affecting the dex stats
- doesn't get boosted if character has initiative bonus dice
!group-init --del-group 1 !group-init-config --set-die-size|6 !group-init-config --set-dice-count-attribute|dexterity !group-init --add-group --bare dexteritypip --bare initiativepip
Vampire the masquerade 20th anniversary Sheet
!group-init --del-group 1 !group-init --add-group --Bare dexterity --Bare wits !group-init-config --set-dice-size|10
Changelog
v0.9.35 (2020-10-01)
- Stargate added as new preset option.
v2.2 (2015-02-26)
- Fixed bug preventing second tier of attributes from being considered
v0.5 (2015-02-20)
- -
v0.41 (2015-02-01)
- Release
See Also
- API:Script Index (partial) list of other APIs
- Script:GroupCheck
- Script:EncounterHelper - API for organizing Combat encounters, it has options to use GroupInit.