Page Updated:   2022-02-18

Overview

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 and ability calls using the selected and target keywords will not work.

!crl will launch the help menu.

• Customizable Roll Listener^(Forum)

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.Basic Syntax 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 separted 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

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

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