Roll20 Wiki

{{revdate}}{{main/api}}

==Overview==
{{script overview
|name=Customizable-Roll-Listener
|author=[[Scott C.]]
|version=1.1
|lastmodified=2020-07-20
|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 [[Character#Ability|ability]], it can be a triggered output of a listener; with the notable exception that [[Roll Query|roll queries]], and attribute & ability calls using the {{c|selected}} and {{c|target}} keywords will not work.

<code>!crl</code> will launch the help menu.

* {{fpl|4259054/ Customizable Roll Listener}}
__TOC__ {{apiboxRec}}
==General==
Please note that the separation of individual arguments differs from the standard <code>--</code> that you see in Aaron's scripts (and many others), instead using <code>\\</code>. This is to ensure, as much as I can, that the script doesn't improperly separate multi argument API commands.

{{orange|'''Warning:''' If you attempt to send an API command to a script that utilizes the <code>playerid</code> 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 [[Character#Attributes_.26_Abilities_Tab|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:

<pre>!crl \\action,name=name of the listener, [specific properties of the listener] \\command 1 \\command 2 \\etc.</pre>

* Action keywords are preceded by a space followed by a double backslash {{c|\\}}. 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.
{{ex}}

<pre>!crl \\create,name=Trap,text=springthetrap \\**a trap suddenly closes, dealing 3d6+2 piercing damage.**</pre>


===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 {{c|/}}. 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.

<pre>\\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...]</pre>

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.

<pre>\\delete,name=Listener Name</pre>

Deletes the indicated roll listener.
*'''name''' - Same as in create/edit.

<pre>\\config,[menu=Menu Name]</pre>

Opens the indicated config menu.
*'''menu''' - Opens the specified config menu. If not passed, opens the general config menu.

==Examples==

<pre>!crl \\create,name=Listener1,text=TESTCRL \\SUCCESS</pre>


===Play Sound on Roll===
Source: [https://www.reddit.com/r/Roll20/comments/qs01lk/need_help_linking_attacks_to_sound_effects/hkddgix/ Play gun sound when rolling an attack]

{{notebox|Using [https://app.roll20.net/forum/permalink/10593263/ 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 <code><nowiki>!crl \\create,name=GunSound,text=gunsound \\!splay gun</nowiki></code> }}

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 <code>gunsound</code> to the attack's description(or name).<br>
'''2.''' create {{Jukebox}} sound named <code>gun</code><br>
'''3.''' do command <code>!roll20AM --config,import</code> (imports all jukebox tracks to Roll20AM )<br>
'''4.''' do command <code>!crl \\create,name=GunSound,text=gunsound \\!roll20AM --audio,play,nomenu,single|gun</code><br>

'''Creating multiple sounds & triggers for each'''

If you add more tracks to the jukebox or change track names, you need to do <code>!roll20AM --config,import</code> 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. 

<pre>!crl \\create,name=AlienSound,text=aliensound \\!roll20AM --audio,play,nomenu,single|alienslash</pre>

'''Update Listener'''

To edit an existing listener, change <code>create</code> to <code>edit</code> in the api command, and make the changes you want:

<pre>!crl \\edit,name=GunSound,text=shotgunsound \\!roll20AM --audio,play,nomenu,single|shotgun</pre>

====Simple Sound version====
Using [https://app.roll20.net/forum/permalink/10593263/ Simple Sound] instead of Roll20AM makes for a more simple process:

'''1.''' add <code>gunsound</code> to the attack's description(or name).<br>
'''2.''' create {{Jukebox}} sound named <code>gun</code><br>
'''3.''' do command <code>!crl \\create,name=GunSound,text=gunsound \\!splay gun</code><br>

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

<pre>!crl \\create,name=AlienSound,text=aliensound \\!splay alienslash</pre>
'''Update Listener'''

To edit an existing listener, change <code>create</code> to <code>edit</code> in the api command, and make the changes you want:

<pre>!crl \\edit,name=GunSound,text=shotgunsound \\!splay shotgun</pre>

===Saving Throw Trigger===

[[File:CRL-Save.png|right|Customizable Roll Listener Saving Throw Example.]]

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 <code>[AbilityName] saving throw</code>.

<pre>!crl \\create,name=Dexterity Save,template=spell atk dmg atkdmg npcatk npcdmg, text=Dexterity saving throw
 \\%{Macros|Dexterity-Save}</pre>

<code>Dexterity-Save</code> is an [[Ability]](Macro) on a [[Macro Character Sheet]] called "Macros":

A simple version of this macro could be:
<pre>/w gm &{template:npcaction} {{rname=Dexterity Save}} {{description=[Dexterity Save](~selected|dexterity_save)}}</pre>
{{clear}}

==Changelog==
* '''Version 1.1''' 2020 - Fixed crit/fumble matching
* '''Version 1.0''' 2016 - Release

[[Category:Audio]]