TRIGGER

Syntax: #TR [id] pattern command [classname] [options]

This is one of the most powerful features of zMUD. 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 command is the command to be executed when the pattern is received from the MUD. Since this command usually consists of more than one word, you must enclose it in braces {}.

The classname is optional, and is the name of the trigger action class 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 create triggers from the Export and Import commands. Options is a string list of values. Allowed values are: "nocr" to NOT test this trigger at the end of each line received from the MUD, "prompt" to 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), "case" to make the pattern as case-sensitive, "verbatim" to match the text of the pattern verbatim and not parse any special characters or wildcards in the pattern, "notrig" to prevent other triggers from firing while this trigger is executing, "color" to indicate that the pattern contains ANSI color control sequences, "disable" to disable the trigger on startup, "line=color" to set the color of the line that this trigger fires on.

For setting advanced trigger options, you normally go to the Settings dialog. In this dialog, 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.

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 [number] 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 zMUD 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 zMUD 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.