Revision as of 09:46, 18 February 2022

Page Updated:   2022-02-18

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

• (Script Update) GroupInitiative - Now with Dice Modifiers for the initial roll!^(Forum)

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.
  Group Initiative showcase starts at 3:15

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.

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

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

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

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:

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!

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 curated list of other APIs
• Script:GroupCheck
• Script:EncounterHelper - API for organizing Combat encounters, it has options to use GroupInit.