Script:Customizable Roll Listener
From Roll20 Wiki
Page Updated: 2022-06-23 |
Overview
Version: 1.1
Last Modified: 2020-07-20
Code: Customizable-Roll-Listener
Dependencies: None
Conflicts: None
You can define custom roll listeners to send additional chat messages based on the what was just sent (including the results of Inline Rolls). Listeners can trigger anything from an additional simple chat message (e.g. Congratulations! You scored a critical) to multiple API commands.
Essentially, if you can do it in an ability, it can be a triggered output of a listener; with the notable exception that roll queries, and attribute & ability calls using the selected
and target
keywords will not work.
!crl
will launch the help menu.
- Customizable Roll Listener(Forum)
Contents |
Roll20 Mod
Mod Suggestions
- D&D 5E
- Combat
- Character Sheet
- Dynamic Lighting
- Jukebox
- Maps
- Text Chat/Macros
- Tokens
- System Specific
- Mod Guides by Script
Debug
Other
General
Please note that the separation of individual arguments differs from the standard --
that you see in Aaron's scripts (and many others), instead using \\
. This is to ensure, as much as I can, that the script doesn't improperly separate multi argument API commands.
Warning: If you attempt to send an API command to a script that utilizes the playerid of the messaging player, that script may crash the API depending on how it's handling of playerid's was coded. Test all listeners before using them in a live game. |
Basic Command Syntax
The CRL listens for user defined patterns in chat consisting of what Roll Template was sent (if any), what the text was (including inline rolls), and what the results of those rolls were (critical,fumble,success,failure). The script expects only a single inline roll in any provided text. Each roll listener is stored as an ability on the attributes & abilities tab of this character.
All CRL commands use the same basic syntax. The contents of a command will change based on what you are doing, but the basic format will always look like this:
!crl \\action,name=name of the listener, [specific properties of the listener] \\command 1 \\command 2 \\etc.
- Action keywords are preceded by a space followed by a double backslash
\\
. The action keywords are: create,edit, delete, and config. - Action keywords and settings/options are separated by a comma. The option keywords will be described below in their associated action keyword section.
- Commands to be executed by the listener can be chained together by making a second (third, fourth, etc) command group. Each command will be placed on a new line in the created listener ability on the CRL character.
Example:
!crl \\create,name=Trap,text=springthetrap \\**a trap suddenly closes, dealing 3d6+2 piercing damage.**
Action Keywords
Commands are shown with all possible settings. If a setting is optional, it will be enclosed in brackets. If only one of a series of settings will be accepted, they are separated by a slash /
. The order of options does not matter as long as the action keyword begins the first action group and the command(s) to execute are the following groups.
\\create/edit,name=Listener Name,[template=Template Name],[text=What text to match including up to a single inline roll],[roll=critical/fumble/success/fail] [\\Command line 1 \\Command line 2 \\etc...]
Creates/edits a listener. Editing a listener will overwrite the current values of whatever arguments you pass.
- name - What the listener will be called, this will be used for accessing the listener to edit it and for organization in the config screen.
- template - The name of the template(s) this listener can react to. Separate template names with a space.
- text - What text must be present in the chat message for the listener to react. Inline roll locations are designated with "##". Multiple separate texts can be defined for a single listener by separating them with "&&". The listener will only respond if all of these texts are present.
- roll - What special roll result all matched inline rolls have to have. Options are critical,fumble, success, or fail.
- command lines- The individual commands that will be triggered when the conditions of the listener are met. If you have a multiline command to initiate, enter each line as a new command in order (first line would be command 1, second command 2, etc). If your command has characters or formatting that the chat will parse (e.g. inline rolls or attribute calls) you can enter these manually by entering them in the proper roll listener on the attributes and abilities screen of this character.
\\delete,name=Listener Name
Deletes the indicated roll listener.
- name - Same as in create/edit.
\\config,[menu=Menu Name]
Opens the indicated config menu.
- menu - Opens the specified config menu. If not passed, opens the general config menu.
Examples
!crl \\create,name=Listener1,text=TESTCRL \\SUCCESS
Play Sound on Roll
Source: Play gun sound when rolling an attack
Using Simple Sound instead of Roll20AM, would make this more simple; you don't need to perform Step 3 each time a new track is added or edited, and the command in Step 4 would be just !crl \\create,name=GunSound,text=gunsound \\!splay gun |
Combining Customizable Roll Listener with Roll20AM, you can have sounds play when certain words appear in the chat. (This example was for the Alien-sheet, but works for any sheet)
1. add gunsound
to the attack's description(or name).
2. create u Jukebox sound named gun
3. do command !roll20AM --config,import
(imports all jukebox tracks to Roll20AM )
4. do command !crl \\create,name=GunSound,text=gunsound \\!roll20AM --audio,play,nomenu,single|gun
Creating multiple sounds & triggers for each
If you add more tracks to the jukebox or change track names, you need to do !roll20AM --config,import
again so the API knows about the change.
If you want to create a new type of sound, you take the api command from step 3., and create a variation with a different name, listening for a different keyword, and playing a different sound.
!crl \\create,name=AlienSound,text=aliensound \\!roll20AM --audio,play,nomenu,single|alienslash
Update Listener
To edit an existing listener, change create
to edit
in the api command, and make the changes you want:
!crl \\edit,name=GunSound,text=shotgunsound \\!roll20AM --audio,play,nomenu,single|shotgun
Simple Sound version
Using Simple Sound instead of Roll20AM makes for a more simple process:
1. add gunsound
to the attack's description(or name).
2. create u Jukebox sound named gun
3. do command !crl \\create,name=GunSound,text=gunsound \\!splay gun
Creating multiple sounds & triggers for each
Just add more tracks to the jukebox or change track names, Simple Sound will always know the tracks you have available.
If you want to create a new type of sound, you take the api command from step 3., and create a variation with a different name, listening for a different keyword, and playing a different sound.
!crl \\create,name=AlienSound,text=aliensound \\!splay alienslash
Update Listener
To edit an existing listener, change create
to edit
in the api command, and make the changes you want:
!crl \\edit,name=GunSound,text=shotgunsound \\!splay shotgun
Saving Throw Trigger
This Roll Listener is actually a series of six potential roll listeners, each of which looks for specific wording in a number of templates to call up a Saving throw dialog when triggered. It looks for [AbilityName] saving throw
.
!crl \\create,name=Dexterity Save,template=spell atk dmg atkdmg npcatk npcdmg, text=Dexterity saving throw \\%{Macros|Dexterity-Save}
Dexterity-Save
is an Ability(Macro) on a Macro Character Sheet called "Macros":
A simple version of this macro could be:
/w gm &{template:npcaction} {{rname=Dexterity Save}} {{description=[Dexterity Save](~selected|dexterity_save)}}
Changelog
- Version 1.1 2020 - Fixed crit/fumble matching
- Version 1.0 2016 - Release