TRIGGER
Syntax: #TR id {pattern} {commands} classname options
This is one of the most powerful features of CMUD. It allows you to define a command to be executed whenever the matching text is received from the MUD.
If the id is present, then the trigger is created with the given short name. Otherwise the name for the trigger is the same as the pattern. IDs are useful for giving short names to complicated trigger patterns, or for creating multiple triggers with the same pattern.
The pattern is the text to be matched. This pattern should always be enclosed in braces {}. The pattern indicates the text received from the MUD which causes this trigger to execute (or fire). This pattern can contain special pattern matching symbols and wildcards.
The commands are executed when the pattern is received from the MUD.
The classname is optional, and is the name of the class folder that this action is part of. Triggers can be enabled and disabled when part of a class. If the classname is not given, the current default class is used.
The options are optional, and are used to set various trigger properties. Options is a string list of values. Allowed values are: - nocr
- Do NOT test this trigger at the end of each line received from the MUD. If this option is not given, then the trigger will be tested when a newline is received from the MUD.
- prompt
- Test this trigger at the end of each buffer of text received from the MUD (even if there is no newline. Used for trigger on MUD prompts). Normally when you specify this option, you should also specify the nocr option or else your trigger might fire twice.
- case
- Causes the pattern to be case-sensitive
- verbatim
- match the text of the pattern verbatim and not parse any special characters or wildcards in the pattern
- notrig
- Prevents other triggers from firing while this trigger is executing
- color
- Indicate that the pattern contains ANSI color control sequences
- disable
- Disable the trigger on startup
- stop
- Prevents processing any trigger after this one in the priority order
- pri=value
- Sets the priority of the trigger. You can also use the longer "priority=value" syntax.
- regex
- Marks the trigger as using regular expression patterns. Using the #REGEX command will automatically set this option for you.
- line=color
- Set the color of the line that this trigger fires on
For setting advanced trigger options, you normally go to the Package Editor dialog. In this screen, you can determine whether the action is triggered at the end of each line received from the MUD, or if it is just triggered at the end of receiving a block of data from the MUD. Responding to MUD prompts such as Username and Password require a trigger that activates after a block of text is received since these prompts are not normally followed by a newline.
See the Pattern Matching section for more detailed information on patterns.
More information on trigger options and trigger types is available here.
More information on multistate triggers (triggers with sequentially-checked patterns) is available here.
A simple trigger action
#TRIG {chats} {#COLOR red}
whenever a line containing the word 'chat' is received, the color of the line is changed to red.
Triggers for automatic logins
#TRIG {^Username:} {#CH}
#TRIG {^Password:} {#PW}
In the Preferences dialog, turn off the 'Trigger on Newline' option and turn on the 'Trigger on Prompt' so that these macros don't wait for a newline character. Note that the ^ character at the beginning of each pattern forces them to match the beginning of a line.
Parameters in triggers
#TRIG {^You get (%d) coins} {split %1} autosplit
Whenever you see a line like You get nnn coins the number of coins is stored in the %1 parameter. The command then uses this value to split the coins among the party members. A class name of autosplit is used so that you can enable and disable the trigger using the #T+ and #T- commands.
ADVANCED: Extracting data from a line
#TRIG {^~[&hp/&{maxhp}hp &mana/&{maxmana}ma~]} {#IF (@hp < @maxhp/10) {cast 'heal'}} "" "prompt"
The &varname syntax in the pattern tells the trigger to store the matching text in the named variable. It is a shortcut for (*) and then assigning the %nn parameter to the @varname variable. In this case, we are matching a MUD prompt. Since MUD prompts do not end in a newline, we add the "prompt" option to the end of the trigger definition. Since the MUD prompt in this example looks like:
[100/150hp 50/70ma]
We have to use a couple of tricks in the pattern definition (which is why this is an ADVANCED example). First, we want to match the [ character at the beginning of the prompt. But, the [ character is a special pattern matching character, so to match the verbatim character from the MUD instead of using [ as a pattern matching character, we put the ~ character in front of it. The ~ character tells CMUD to ignore any special property of the next character and just treat it as a normal character. You will need to use ~ to match any special characters from the MUD like [, @, (, etc. To match a ~ character itself, you would use ~~, of course.
The next trick is to make sure that the &maxhp and &maxmana variable only contain the numeric values, and not the text "hp" or "ma". Remember that &varname is equivalent to (*), so it will normally match both text and numbers. So, we put the literal text "hp" and "ma" in our pattern. But if the pattern had &maxhphp then how would CMUD know that "maxhp" was the variable name and "hp" was the literal text? We have to enclose the name of the variable in braces {} to distinguish it from the literal text. So, we have &{maxhp}hp which tells the trigger to store the numeric value in the @maxhp variable, and then match the literal "hp" text from the MUD.
Take a look at the #SETPROMPT command for an easier way to capture information from this simple MUD prompt. |
#nnn