Der20 Plugins Help

!PLUGIN dump
This commmand is supported by multiple der20 plugins. Use the name of the plugin instead of the word 'PLUGIN' when using this command.
This command prints the current configuration state as JSON, followed by the some debugging information as JSON. Please include this output when filing bugs.
!PLUGIN export [PATH]
This commmand is supported by multiple der20 plugins. Use the name of the plugin instead of the word 'PLUGIN' when using this command.
This command prints the configuration commands that make up the current configuration.
Without any additional arguments, the entire configuration is printed.
To limit the scope of the output, you can specify a path that would have been a valid configuration path. For example, the configuration commands under !league define module example would be exported via !league export define module example.
The output of this command can then be shared with other DMs or pasted into a handout for those plugins that support handout configuration.
!PLUGIN help
This commmand is supported by multiple der20 plugins. Use the name of the plugin instead of the word 'PLUGIN' when using this command.
This command prints the names of all supported commands for the plugin.
!PLUGIN option command [ID]
This commmand is supported by multiple der20 plugins. Use the name of the plugin instead of the word 'PLUGIN' when using this command.
This setting adds a command word that can be used instead of the name of the plugin. Please note that plugins must all have distinct names, so don't choose the name of another plugin. To remove a name from the recognized list, use option delete command.
Command words must consist entirely of a-z, 0-9, and the underscore character.
!PLUGIN option debug [TRUE/FALSE]
This commmand is supported by multiple der20 plugins. Use the name of the plugin instead of the word 'PLUGIN' when using this command.
If set to true, this setting enables very verbose debug logging to the Roll20 API console. This setting can be changed without restarting the script API sandbox, so you can set it to true to test some command that is failing and then switch it back to false.
!PLUGIN option delete command [ID]
This commmand is supported by multiple der20 plugins. Use the name of the plugin instead of the word 'PLUGIN' when using this command.
This delete command removes a string from the set of additional command words configured.
!PLUGIN option echo [TRUE/FALSE]
This commmand is supported by multiple der20 plugins. Use the name of the plugin instead of the word 'PLUGIN' when using this command.
If set to false, commands executed no longer display in chat. By default, plugins echo back the command that was executed in response to input or dialog interaction. Failed commands are shown in red.

!PLUGIN option handouts archived [TRUE/FALSE]
This commmand is supported by multiple der20 plugins. Use the name of the plugin instead of the word 'PLUGIN' when using this command.
If set to false, this setting prevents configuration being read from GM Notes of archived handouts. By default, GM Notes from both archived and journal handouts are read.
Tip: If formatted handouts are not read correctly, try to reset their style to 'Normal' in the Roll20 handout editor.
!PLUGIN option handouts journal [TRUE/FALSE]
This commmand is supported by multiple der20 plugins. Use the name of the plugin instead of the word 'PLUGIN' when using this command.
If set to false, this setting prevents configuration being read from GM Notes of handouts in the journal. By default, GM Notes from both archived and journal handouts are read.
Tip: If formatted handouts are not read correctly, try to reset their style to 'Normal' in the Roll20 handout editor.
!PLUGIN option verbose [TRUE/FALSE]
This commmand is supported by multiple der20 plugins. Use the name of the plugin instead of the word 'PLUGIN' when using this command.
If set to true, the plugin will send additional response messages to the user, confirming the results of the command. These may be extensive in some cases, as shown below:

!PLUGIN reset
This commmand is supported by multiple der20 plugins. Use the name of the plugin instead of the word 'PLUGIN' when using this command.
This command discards all stored state and configuration and restarts the plugin. If the plugin supports handout configuration, configuration stored in handouts is then read.
For safety, the command must be entered as !PLUGIN reset all configuration including spaces.
!anonymous

This plugin is used to hide the name and icon of an NPC or monster until it is time to spring them on your players. For best results, create macro bar entries for all commands, so you can multi select tokens and hit one button.

Usage: select all tokens you want to anonymize, then execute !anonymous set

The icon will be taken from a character called 'Anonymous' or another character in your journal that you can configure via 

!anonymous character My Other Character

Technical note: The 'cache defeat' query string at the end of the image URL is set to midnight of the current day, so images are cached for around 24 hours.

The name of the token will be changed to the creature type from the Journal.  The intent is that you can narrate what sort of creature the player characters are seeing (like a 'small, rotten corpse') instead of knowing the exact creature stats just from the picture or name.

Either during the first round of combat or when your players get a turn, you can decide with which creatures they are familiar, and reveal their true identity by selecting multiple tokens and executing !anonymous reveal

Oh god, DM... Why???

!anonymous character [STRING]
This setting specifies the complete case-sensitive name of a Character that must be present in the Roll20 Journal. If found, the default token for this character is used for anonymous tokens. If not set, this features defaults to using the a character named 'Anonymous', which the user must create.
If the [STRING] is not specified, a dialog is presented to select from all the characters in the current game.
!anonymous reveal
This command sets the selected tokens to be revealed, showing their real name and icon.
!anonymous set
This command sets the selected tokens to be anonymous, showing only the creature type instead of a name and showing the icon from the configured anonymous character. If !anonymous character is not configured and no character named 'Anonymous' is present, only the name of the creature will be changed.
!anonymous whisper set [TRUE/FALSE]
!anonymous whisper unset [TRUE/FALSE]
!init5e

This plugin rolls initiative and does some combat tracking. It tries to be a fixed configuration solution for league play, using strict RAW rolling and without the full feature set of combat tracking or general group initiative scripts.

Usage: select all tokens you want to add to initiative, then execute !init5e roll

!init5e actions announce
This command takes the configured actions for a new turn starting. It is automaticaly called on turn changes.
!init5e automatic actions [TRUE/FALSE]
If true, the GM is sent a set of useful links for each creature that starts its turn.
!init5e automatic marker insert [TRUE/FALSE]
If true, an initiative tracker round marker is automatically added when there isn't one with the configured name.
!init5e automatic marker name [STRING]
This setting configures the name of the initiative tracker special round marker.
!init5e automatic ping [TRUE/FALSE]
!init5e automatic sort [TRUE/FALSE]
If true, the initiative tracker will be automatically sorted at the top of each round.
!init5e beam
!init5e clear
This command removes all entries from the initiative tracker.
!init5e roll
This command rolls initiative for all selected 5e OGL tokens according to RAW rules, including grouping all identical creatures under the same initiative.
!init5e sort
This command sorts the initiative tracker.
!league

This API Script contains tools to help run sessions for D&D Adventurers League (DDAL).  Before the session, you can enter all of the objectives and treasure unlock information about the modules (or hardcover chapters) you are running for DDAL.  Rules differences between Season 8 and previous season's modules are considered and customizable if things change.

Configuration is via a command language, which is documented in the page you are currently reading. For most configuration, you can also use interactive dialogs. These dialogs effectively type in commands for you, which change the configuration that is stored in the Roll20 API Script state.

The minimum required configuration is to declare a DM and a module. You can do this by executing !league define dm ID and !league define module ANOTHER_ID. In these commands, replace 'ID' with some short word that identifies your DM entry, such as your first name. Replace 'ANOTHER_ID' with a short word that identifies the module, such as the DDAL module code.

Both of these commands will then run a dialog, where you can fill in the information about these items. Please note that the following screen shots may be out of date, but the same information is presented by the current dialogs, even if the formatting is different.

Alternatively, you can store configuration commands in the GM Notes of handouts, so you can move them from room to room.

When starting a new game session, discard all current session state by running !league session clear.

Then run !league session show to start interactive use. If you have more than one DM or Module (in case of shared rooms), a selection dialog will be presented.

After DM and module selection, it will show the rewards for the current module initialized to their defaults.  Depending on whether you are running a module (or hardcover chapter) and depending on the tier and season, rewards are calculated.  You can override any of the defaults calculated for you.

Then you interactively check off objectives as they are achieved and hit a start and stop timer for the session.  Time entry is either as an absolute time string, or empty string for "now" or a number meaning "this many hours ago."  So if you have been playing for about 3 hours, you can just hit start and type in "3."

When you set the start time of the module, the script finds all player-owned characters in the game and adds them to the session data.  It selects the highest level character for each player as the probable player character.  You can then interactively correct which characters are included in the session.   APL and player count are calculated from this selection.  In this example, there are two players: 'Ammo' and 'Test U.'    'Ammo' brought three characters to the session, only one of which counts. The tier of the hard cover is set to 3 based on the APL of this group. Because the group is mixed-tier, TCP calculation is broken out by tier according to Season 8 rules.

For a Season 8+ module, you might have several explicit objectives and no rewards per hour:

Finally, you can compile the rewards page in private and check everything before you share it with all the players.

Development on this tool continues.  There is a feature to directly import this reward information into the website https://www.adventurersleaguelog.com.  However, this functionality won't be enabled until the server side code can be implemented under this issue  https://github.com/Ariel-Thomas/adventurers-league-log/issues/157

!league define dm [ID]
This command presents a dialog to interactively configure a Dungeon Master definition. The intent of this feature is to configure the name and DCI of a DM who uses the current game room, even if there are multiple DMs sharing the room. During a session, !league session dm can then be used to select the DM information to use in the rewards.
Instead of using the interactive dialog, individual parameters of the DM definition can be configured directly by simply appending the name of a value to set, as in !league define dm [ID] name [STRING] and !league define dm [ID] dci [STRING]
!league define dm [ID] dci [STRING]
!league define dm [ID] name [STRING]
!league define module [ID]
This command presents a dialog to interactively configure a DDAL module (or hardcover chapter) definition. The intent of this feature is to configure the information for a DDAL module that is run from the current game room, even if there are multiple modules run from the same room. During a session, !league session module can then be used to select the module for the current session. If there is only one module defined, that step is not necessary.
For example, a season 8 module with multiple objectives might look like this:

A hard cover definition would instead have hourly advancement. Note you may want to have a separate 'module' defined for each hard cover chapter(s) that you run separately, instead of the simple example shown here.

Instead of using the interactive dialog, individual parameters of the module definition can be configured directly by simply appending the name of a value to set, as in !league define module [ID] name [STRING] and !league define module [ID] season [INTEGER]
Multiple objectives or unlocks can also be added to a module definition using the dialog, or by directly configuing them through providing the ID for both the module and each unlock or objective. For example, the command !league define module ddal01-100 unlock sword name Sword of Awesome would create a module with id 'ddal01-100' and add an unlock with id 'sword' that is called 'Sword of Awesome'. If the module and/or the unlock already existed, then it would simply set the specified property 'name' on the unlock to the given value. This means you do not need to 'create' modules or their unlocks, they are created for you when you set their properties.
!league define module [ID] duration [NUMBER]
!league define module [ID] hardcover [TRUE/FALSE]
!league define module [ID] level maximum [INTEGER]
This setting configures the maximum level for characters in this module. It is defaulted based on the module tier.
!league define module [ID] level minimum [INTEGER]
This setting configures the minimum level for characters in this module. It is defaulted based on the module tier.
!league define module [ID] name [STRING]
!league define module [ID] objective [ID]
This command presents an interactive dialog to configure an objective (Season 8+) in the module.
!league define module [ID] objective [ID] awarded [TRUE/FALSE]
!league define module [ID] objective [ID] dm [TRUE/FALSE]
!league define module [ID] objective [ID] name [STRING]
!league define module [ID] objective [ID] players [TRUE/FALSE]
!league define module [ID] objective [ID] story [STRING]
!league define module [ID] season [Historical|Masters|10]
This setting configures the DDAL season for the module. This is primarily used to default the rewards based on Season 8 rules for modules and hardcovers from different seasons' rules.
!league define module [ID] target apl [INTEGER]
This setting configures the target APL of the module. It is defaulted to the middle of the configured level range.
!league define module [ID] tier [INTEGER]
This setting configures the default tier (1-4, or 0 if not specified) of the module or hardcover. If the module is a hardcover, then the player characters' APL during the game session will determine the default tier. The per-session configuration command !league session module current tier can be used to manually override the tier in either case.
!league define module [ID] unlock [ID]
This command presents an interactive dialog to configure an unlockable item in the module.
!league define module [ID] unlock [ID] awarded [TRUE/FALSE]
If this setting is set to true, then the unlock is awarded by default. The per-session configuration can override this default.
!league define module [ID] unlock [ID] consumable [TRUE/FALSE]
If set to true, this unlock uses the consumables rules. Specifically, the player character that picks up the consumable gets to keep it at the end of the session, while any picked up permanent magic items disappear. Setting this to true causes this unlock to be included in the session report as both an unlock and a note specifying which character picked up the item, if specified via !league session module current unlock [ID] owner.
!league define module [ID] unlock [ID] description [STRING]
!league define module [ID] unlock [ID] dm [TRUE/FALSE]
!league define module [ID] unlock [ID] location [STRING]
This setting configures a description of where in the module the item is found. This is useful for disambiguating multiple items of the same type. If this is configured, then this location string is displayed in the unlocks list, in addition to the the unlock name.
!league define module [ID] unlock [ID] name [STRING]
!league define module [ID] unlock [ID] players [TRUE/FALSE]
!league define module [ID] unlock [ID] rarity [Common|Uncommon|Rare|Very Rare|Legendary|Artifact|Unique]
!league define module [ID] unlock [ID] table [STRING]
!league define module [ID] unlock [ID] tier [INTEGER]
!league define rules advancement downtime multiplier [NUMBER]
!league define rules advancement downtime unit [NUMBER]
!league define rules advancement renown multiplier [NUMBER]
!league define rules advancement renown unit [NUMBER]
!league delete dm
!league delete module
!league populate module [ID] unlock [ID]
This command will try to find another unlock with the same name (not id) as the specified module unlock. The search will prefer unlocks defined in the same module, after which other modules will be searched. The first unlock with the same name, if any, is used to populate all the unconfigured properties of the specified unlock.
The intended use of this command is for creation of many similar unlocks. For example, you can create one unlock named 'Potion of Healing' and fill in the rarity, DMG table, and related information. For any additional potions of the same type, you only need to configure the name and then populate the rest automatically. The UI supports this functionality when graphically configuring an unlock.
From the command line, an example use would be (assuming there is already another 'Potion of Healing' defined):

!league define module foo unlock healing2 name Potion of Healing

!league populate module foo unlock healing2

Note you have to create the first item of each type yourself. This tool cannot include the rarity and table information for common items, because that is licensed content.
!league rewards preview
This command displays the calculated session report to the GM for review. The resulting dialog includes a button to share it with the players.
!league rewards send
This command displays the calculated session report to all players. It is usually preferable to execute !league rewards preview instead, which allows you to review the report and includes a button to run this command to share it with the players.
!league scaling
This command can be placed in the gmnotes of a token to add/remove that token to the game based on party strength.
!league session clear
This command discards all per-session configuration. It is intended to be used when starting a new game session.
!league session dm [ID/current]
The magic string 'current' refers to the current session DM data. During a session, exactly one DM definition will be loaded into that slot.
Using this command or any of its sub-commands with any ID other than 'current' will change the DM information for the current session to the specified DM, loaded from the DM definitions.
!league session dm [ID/current] dci [STRING]
This setting is a per-session override for !league define dm ....
!league session dm [ID/current] name [STRING]
This setting is a per-session override for !league define dm ....
!league session module [ID/current]
The magic string 'current' refers to the current session module data. During a session, exactly one module definition will be loaded into that slot and then modified as the game progresses. All necessary interaction should be done through the !league session show dialog, so you should never have to manually use these commands. However, if you want to automate doing some of these operations, you can learn the required paths by watching the commands executed by the dialog, provided !league option echo true is set, which it is by default.
Using this command or any of its sub-commands with any ID other than 'current' will load the specified module from the module definitions and replace the current session module data with it.
Any settings created by this command or any of its sub-commands are discarded when the session is reset via !league session clear or when a different module is selected via !league session module.
!league session module [ID/current] duration [NUMBER]
This setting is a per-session override for !league define module ....
!league session module [ID/current] hardcover [TRUE/FALSE]
This setting is a per-session override for !league define module ....
!league session module [ID/current] level maximum [INTEGER]
This setting is a per-session override for !league define module ....
!league session module [ID/current] level minimum [INTEGER]
This setting is a per-session override for !league define module ....
!league session module [ID/current] name [STRING]
This setting is a per-session override for !league define module ....
!league session module [ID/current] objective [ID]
!league session module [ID/current] objective [ID] awarded [TRUE/FALSE]
This setting should be set to true when the player characters achieve the objective.
The rewards for this objective are then included in the totals.
!league session module [ID/current] objective [ID] dm [TRUE/FALSE]
This setting is a per-session override for !league define module ....
!league session module [ID/current] objective [ID] name [STRING]
This setting is a per-session override for !league define module ....
!league session module [ID/current] objective [ID] players [TRUE/FALSE]
This setting is a per-session override for !league define module ....
!league session module [ID/current] objective [ID] story [STRING]
!league session module [ID/current] season [INTEGER]
This is a per-session override for !league define module [ID] season.
!league session module [ID/current] session [STRING]
This setting specifies the session number for an adventure that spans multiple sessions. This is the session number that will appear in players' adventure logs.
!league session module [ID/current] start [DATE/HOURS/BLANK]
This setting specifies the start time when the module session was begun, for calculation of hourly rewards and to put the date and time in the log sheet.
The date and time can be specified in three different ways:
  1. As a simple number, with or without a decimal point.
  2. In this case, the start time is set to the specified number of hours before now. For example, if you have been playing for 3 1/2 hours, input !league session module start 3.5

  3. As a full date/time string in a variety of formats.
  4. Most standard date/time formats are recognized.

  5. As nothing at all.
  6. Ending the command after start sets the start time to now.

When the start time is set via this command, the list of players currently in the session is not updated. Please use !league session party scan to update the list of players in the session.
!league session module [ID/current] stop [DATE/HOURS/BLANK]
This setting specifies the stop time when the module session was completed, for calculation of hourly rewards.
The date and time can be specified in three different ways:
  1. As a simple number, with or without a decimal point.
  2. In this case, the stop time is set to the specified number of hours before now. For example, if you stopped playing 1/2 hour ago, input !league session module stop 0.5

  3. As a full date/time string in a variety of formats.
  4. Most standard date/time formats are recognized.

  5. As nothing at all.
  6. Ending the command after stop sets the stop time to now.

!league session module [ID/current] target apl [INTEGER]
This setting is a per-session override for !league define module ....
!league session module [ID/current] tier [INTEGER]
This setting is a per-session override for !league define module ....
!league session module [ID/current] unlock [ID]
Settings under this command are per-session overrides for !league define module ....
!league session module [ID/current] unlock [ID] awarded [TRUE/FALSE]
This setting should be set to true when the unlockable item is discovered by the player characters.
!league session module [ID/current] unlock [ID] consumable [TRUE/FALSE]
This setting is a per-session override for !league define module ....
!league session module [ID/current] unlock [ID] description [STRING]
This setting is a per-session override for !league define module ....
!league session module [ID/current] unlock [ID] dm [TRUE/FALSE]
This setting is a per-session override for !league define module ....
!league session module [ID/current] unlock [ID] location [STRING]
This setting is a per-session override for !league define module ....
!league session module [ID/current] unlock [ID] name [STRING]
This setting is a per-session override for !league define module ....
!league session module [ID/current] unlock [ID] owner [STRING]
This setting should be set to the name of a player character that picked up the unlocked item in the adventure. If the item is marked as a consumable, then it will be kept by that player at the end of the adventure (if not consumed.)
The interactive dialogs provide a player picker to configure this setting, provided the player characters have been scanned, which is usually done by starting the session.
!league session module [ID/current] unlock [ID] players [TRUE/FALSE]
This setting is a per-session override for !league define module ....
!league session module [ID/current] unlock [ID] rarity [Common|Uncommon|Rare|Very Rare|Legendary|Artifact|Unique]
This setting is a per-session override for !league define module ....
!league session module [ID/current] unlock [ID] table [STRING]
This setting is a per-session override for !league define module ....
!league session module [ID/current] unlock [ID] tier [INTEGER]
This setting is a per-session override for !league define module ....
!league session party apl [NUMBER]
This setting can be used to override the automatically calculated Average Party Level (APL) if it was not correctly calculated. This can happen if not all player characters are specified in the session data.
!league session party pc [USER_ID character CHARACTER_ID selected TRUE/FALSE/BLANK]
This setting is used by the interactive UI to select which currently present player owned characters are part of the adventure. The parameters required to use this setting are not generally available to users, so this command cannot readily be used manually.
!league session party scan
This command records the player characters that are present in the session. This list is presented in !league session show to select which player characters are included for APL calculation and awards. If not all players were actually present when this command was last called, you can call it again to redo the scan for players.
!league session party strength [STRING]
This setting can be used to override the automatically calculated party strength. The standard values (Very Weak, Weak, Average, Strong, and Very Strong) are set automatically based on the number and APL of player characters in the session and the target APL of the current module.
Additional unofficial values can be used at DM discretion (e.g. Epic, Hard Core, Nightmare, TPK) but future module scaling features may not know which of these are higher than each other, so they should be used sparingly.
!league session show
This command presents the primary dialog to use during a game session. Most game sessions will start with !league session clear and then use !league session show multiple times to update the session. Any interaction with this dialog will print out the direct command that could have been used to the same effect as clicking on the dialog, provided that !league option echo true is set, which it is by default.
If this command is executed without selecting a current DM and module, it will first present additional dialogs to select those items from the definitions. If there is only one DM or module defined, it will automatically select it.
!league session start [-> module current start]
This command calls !league session module current start and also records the player characters that are present in the session. If not all players were actually present when this command was last called, you can call it again to redo the scan for players.
Alternatively, you can use !league session party scan to just re-scan the player characters in the session without changing the start time.
!league session stop [-> module current stop]
This command just calls !league session module current stop
!setup character [CHARACTER_ID hp|ac|pp VALUE]
!setup positions clear
This command discards all the stored positions for tokens in the current game. There is no way to undo this action.
!setup positions restore
This command restores all selected tokens to their positions and layers, if those were previously stored via !setup positions save.
!setup positions save
This command saves the positions and layer placement of all selected tokens to the persistent state in the current game. Existing saved positions are not deleted, so this command can be used repeatedly to save various groups of tokens.
!setup session restore
This command restores a game to a default state, in preparation for a new gaming session in a previously used game. All tokens are restored to their saved positions and layers as if by !setup positions restore, any NPC tokens are reset as if by !setup tokens reset
!setup token [-> tokens]
!setup tokens darkvision
!setup tokens dead
!setup tokens dump
!setup tokens hp [rolled|maximized]
!setup tokens light [[BRIGHT_DISTANCE [dim DIM_EXTRA_DISTANCE]]]
!setup tokens reset
This command resets any selected NPC/Monster tokens to remove previously rolled hp and stealth values, as well as any current condition markers applied to the tokens. It also removes the bars from the tokens to indicate they are no longer set up.
Tokens that do not represent NPC/Monsters are ignored, so that this command can be safely run for all tokens on the page.
!setup tokens stat
This command sets up all selected tokens for sane defaults. Any selected NPC/Monster tokens have their max health and stealth checks (out of 30) individually rolled and assigned to bars of their token. The intention of this command is to vary these numbers each time a game is run.
Selected player character tokens are set up to display their current hp from their character sheet.
Tokens that do not represent characters or monsters are ignored, so that this command can be safely run for all tokens on the page.
For both Player and NPC/Monster tokens, The passive perception score is mapped to the second bar, with the full bar representing a score of 30, just like stealth for NPC/Monster tokens.
NPC/Monster tokens can be reset to an unconfigured state via !setup tokens reset, while Player character tokens remain configured even if !setup tokens reset is run on them.