Roll20 uses cookies to improve your experience on our site. Cookies enable you to enjoy certain features, social sharing functionality, and tailor message and display ads to your interests on our site and others. They also help us understand how our site is being used. By continuing to use our site, you consent to our use of cookies. Update your cookie preferences .
×
Advertisement Create a free account

[Script] Customizable Roll Listener

1479419603

Edited 1516818213
Scott C.
Forum Champion
Sheet Author
API Scripter
Compendium Curator
This script started out as a feature of Roll20AM, but I found it was easier to get the functionality as a standalone script. The script does what it says; 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. 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. Now available from  my fork of the repository and hopefully coming to one-click on the next merge day. 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. 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] Deletes the indicated roll listener. • menu - Opens the specified config menu. If not passed, opens the general config menu. And because I'm a horrible person I almost forgot to thank the people who helped make this script what it is: Aaron and Stephen S. For code review and helping me implement some of the more complicated parts. and DulfiJavadMalik at plainicon.com for all of the button icons for the chat menus.
1483586207
Garrett K.
Marketplace Creator
Could I get some example lines? I can't seem to get this script to function. For example, what you might type to create a listener named Listener1, who responds SUCCESS when it hears TESTCRL ?
1483589261

Edited 1483589336
Scott C.
Forum Champion
Sheet Author
API Scripter
Compendium Curator
Sure thing: !crl \\create,name=Listener1,text=TESTCRL \\SUCCESS Items surrounded by brackets in the instructions in the OP are optional arguments, the brackets aren't part of the syntax.
1483597074
Garrett K.
Marketplace Creator
Perfect! That's what I needed! Trying to piggyback this with Trackerjacker to automatically clear conditions when they expire... Wish me luck ;) haha
1483621883
Scott C.
Forum Champion
Sheet Author
API Scripter
Compendium Curator
Good luck