Revision as of 14:12, 8 June 2016

This article is a stub. You can help the Roll20 Community Wiki by expanding it.

Overview

This script adds a command for rapidly adding large groups of tokens into the turn order. As of v0.3, there are quite a few configuration commands (see Commands below). 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 turn order.

Commands

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

!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 --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 --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:

1. dexterity|current + initiative|current + rage|current
2. dexterity|current + initiative|current
3. 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! If you have any issues, just let me know!

Changelog

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