Der20 Plugins Help
Copyright 2018 Ammo Goettsch
!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.
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.
!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.
!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.
!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.
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.
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]
!league
session dm [ID/current] name
[STRING]
!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.
!league
session module [ID/current] duration
[NUMBER]
!league
session module [ID/current] hardcover
[TRUE/FALSE]
!league
session module [ID/current] level maximum
[INTEGER]
!league
session module [ID/current] level minimum
[INTEGER]
!league
session module [ID/current] name
[STRING]
!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]
!league
session module [ID/current] objective [ID] name
[STRING]
!league
session module [ID/current] objective [ID] players
[TRUE/FALSE]
!league
session module [ID/current] objective [ID] story
[STRING]
!league
session module [ID/current] season
[INTEGER]
!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:
- As a simple number, with or without a decimal point.
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
- As a full date/time string in a variety of formats.
Most standard date/time formats are recognized.
- As nothing at all.
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:
- As a simple number, with or without a decimal point.
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
- As a full date/time string in a variety of formats.
Most standard date/time formats are recognized.
- As nothing at all.
Ending the command after stop sets the stop time to now.
!league
session module [ID/current] target apl
[INTEGER]
!league
session module [ID/current] tier
[INTEGER]
!league
session module [ID/current] unlock
[ID]
!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]
!league
session module [ID/current] unlock [ID] description
[STRING]
!league
session module [ID/current] unlock [ID] dm
[TRUE/FALSE]
!league
session module [ID/current] unlock [ID] location
[STRING]
!league
session module [ID/current] unlock [ID] name
[STRING]
!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]
!league
session module [ID/current] unlock [ID] rarity
[Common|Uncommon|Rare|Very Rare|Legendary|Artifact|Unique]
!league
session module [ID/current] unlock [ID] table
[STRING]
!league
session module [ID/current] unlock [ID] tier
[INTEGER]
!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]
!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.