Zugg Software :: Introduction to Triggers

Introduction to Triggers

Triggers can be tricky, but are also the most powerful feature of CMUD. Triggers (sometimes called "actions" in other MUD clients) allow you to execute a command whenever a particular string of text is received from the MUD. While this sounds simple, it has powerful implications.

To define a trigger, you use the #TRIGGER (or #ACTION) command. The syntax is: #TRIGGER {pattern} {command}. Whenever the pattern text is received from the MUD, the command is executed. You can also define and edit triggers using the View/Triggers menu command to display the Trigger editor in the Package Editor.

Let's start with a simple example. When you are working in a group, it is important to see anything that someone in the group has to say. When someone in the group talks, the MUD usually says something like Zugg tells the group 'heal me'. To ensure you don't miss this important information, let's change the color of the line to red using the #COLOR red command. Thus, you would type:

#TRIGGER {tells the group} {#COLOR red}.

That was easy, and triggers like this can really enhance your MUD playing. Here's another useful example:

#TRIGGER {You are thirsty} {dr}.

With an alias like #ALIAS dr {drink @container} this trigger will keep your stomach happy and full by automatically drinking whenever you are thirsty from whatever container you have.

You can create triggers on the command line, or you can create and edit triggers in the Package Editor Triggers screen.

Extracting text from the MUD

Patterns can contain more complicated expressions and wildcard characters, and parts of the matched pattern can be stored in special arguments for use in the command string. Arguments were introduced when Aliases were discussed. The way you store part of the pattern into an argument is by surrounding the part of the pattern with parenthesis. One of the wild-card strings for a pattern is %w which matches any word. So, for example:

#TRIGGER {(%w) tells you} {tell %1 I am busy}

will match any string from the MUD that has a word followed by the string tells you. The word before "tells you" is saved to the %1 argument. Thus, when you receive the string Zugg tells you 'Hi', you will automatically send the command tell Zugg I am busy to the MUD.

Here's another really useful one:

#TRIGGER {You get (%d) coins} {split %1}

Since %d matches any set of numeric digits, whenever you pick up some gold coins, you will automatically split them with your group!

As with Aliases, you can used Named Arguments with triggers. Simple place the name of the argument (beginning with the $ character) after the parenthesis, and followed by a colon. For example:

#TRIGGER {You get ($gold:%d) coins} {split $gold}

Many times you just want to extract the text from the MUD and put it into a variable. For example, you might want to capture the information from your MUD status line about your hit points and mana:

#TRIGGER {Hp: (%d) Mana: (%d)} {#VAR HpVar %1;#VAR ManaVar %2}

When the MUD displays

Hp: 100 Mana: 50

the trigger will store 100 into the @HpVar variable and 50 into the @ManaVar variable.

However, there is an even easier way to do this using the &VarName syntax in the trigger patter:

#TRIGGER {Hp: &HpVar Mana: &ManaVar}

No action is needed...the captured values are automatically stored into the specified variables if the pattern matches.

By default, the &VarName syntax uses a wildcard pattern of * to match the text. To change the wildcard that is used, specify it just after the & character. Or, if you want to use the square brackets [] to define your own wildcard range, put it after the & character. For example, to only capture the digits 0,1,2 into a variable, you would do:

#TRIGGER {Hp: &[012]HpVar}

so it would only capture your hitpoints if it only contained the digits 0,1,2. Not very useful, but it illustrates the syntax.

If you need to capture something where there are alphabetic characters just after the value you want, you need to enclose the variable name in {} characters. For example, if the MUD displays:

You have 100gp

You might want to create a trigger to capture this number into the @Gold variable. But, if you do:

#TRIGGER {You have &Goldgp}

IT WON'T WORK! Because it will be using a variable name of "Goldgp" instead of just "Gold". To get around this, use the {}:

#TRIGGER {You have &{Gold}gp}

and now it will set the @Gold variable properly.

Trigger Classes

You probably wouldn't want the above trigger to be active all of the time. Splitting coins when you are not in a group is not recommended. To assign the trigger to a class folder, provide the class name as the optional third parameter to the #TRIGGER command. For example:

#TRIGGER {You get (%d) coins} {split %1} autosplit

Then you can turn the trigger on with #T+ autosplit, or turn it off with #T- autosplit. Assign these two commands to macro keys or buttons and you have full control over when you split and when you don't.

Instead of placing the trigger into a class folder, you can give the trigger itself a unique name (called an ID name). By assigning an ID name to a trigger, you can refer to it by name instead of by pattern. For example:

#TRIGGER autosplit {You get (%d) coins} {split %1}

Just as with the previous example, you can enable and disable this trigger using #T+ autosplit or #T- autosplit. The difference is that you have not created a class folder...you've just assigned a new name to the trigger.

Regular Expressions

Instead of using the normal CMUD trigger syntax, you can use Perl Regular Expressions instead. See the #REGEX command for details on regular expressions.