Main Page: API:Script Index

• Customizable Roll Listener^(Forum)

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.

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.

Example

!crl \\create,name=Listener1,text=TESTCRL \\SUCCESS

Changelog

• Version 1.1 2020 - Fixed crit/fumble matching
• Version 1.0 2016 - Release