In zMUD versions 6.65 and later, pressing Ctrl-T brings up the Simple Trigger Wizard.  This wizard can be customized via *.WIZ files.  This document describes the features of this system and provides examples of how to customize this file.

Overview

The Simple Trigger Wizard allows you to construct a zMUD script from the answers to various questions that the user answers.  Each section of the *.WIZ (referred to as the WIZFile from here on) contains the details on the questions that the user is asked and how those answers are converted into a zMUD script.

zMUD will first load the contents of the ZMUD.WIZ file in the main zMUD directory.  This is the master file distributed with zMUD and may change with each zMUD update, so it should not be modified.  Next, any other *.WIZ file in the zMUD directory is loaded.  Finally, any *.WIZ file in the MUD-specific subdirectory is loaded.

The *.WIZ files are in Windows INI file format, which is used to provide compatibility with 3rd party tools and to provide easy modification.  Any text editor, such as NotePad, can open and edit the *.WIZ files.

Each section of the WIZFile has the following structure:

[Title of this wizard rule]
Author=optional name of author of this wizard
Version=optional version number of this wizard
Date=optional date this wizard was created
Start=optional expression to determine the starting question number for the wizard
Param1=First question to ask the user
Type1=type of answer allowed (string, number, etc)
Default1=default value for answer
Validate1=optional validation expression
Convert1=optional conversion expression
NextN=optional expression to specify the next question number to ask.  0 goes to next question, -1 goes to finish
CommandN=override the default command with this new command when the current answer is accepted
Param2=...
Type2=...
...
Command=script command

Any number of questions can be asked.  The user steps through the questions using the Next and Prev buttons.  When the last question is reached, the Finish button becomes enabled.  The user is shown the full script command that has been constructed and is able to edit the results before clicking the Finish button to execute the command.

The parameter entered by the user is stored in the $1..$99 variables and can be referenced in any of the other strings in the WIZFile.  The $1..$99 are similar to the normal %1..%99 variables in zMUD in that they are expanded before any other parsing is done.  The $ is used instead of % to allow you to use the normal %1..%99 references in any script created by the wizard.

Special characters such as the # command character can be overridden by the player.  In order to create a wizard that works no matter what special characters are being used, you can use the sequences \# \% \@ \; \~ etc to reference zMUD special characters.  These meta values are replaced with the actual special characters used by the player when executed.

You can leave out the use of \ to override special characters.  If you do not use the \ expansion, then zMUD will temporarily use the standard set of special characters when executing your functions or commands.  While this is fine for hidden functions such as the parameter validation and conversion, it is important to use the \ meta characters in your command output so that the player will see the trigger created by the wizard using the special characters they are used to.

Header Information

Several optional header fields can be included in your wizard.  The Author, Version, and Date fields are used to publish your author name, the version of your wizard, and the date is was created.  The values of these fields are displayed to the user at the bottom of the dialog when they are running your wizard.

When you first select the wizard rule, the wizard normally starts with question number one (Param1).  You can change this using the Start string in the WIZFile.  The optional Start string should point to an expression that returns a number.  This number will determine the first question number to ask the user.

Parameter Question

The ParamN field in the WIZFile specifies the question string to be displayed to the user in the wizard.  This string is both expanded for zMUD variables (and function execution) as well as expanded for other parameters using the $1..$99 syntax.

Parameter Types

There are several different parameter types that determine the type of answer you want the user to give to your question:

string

A single-line string result.

memo

A multi-line string result.  Line breaks are implemented as #13#10 (or \r\n) characters imbedded in the text result.

number

A numeric value.

stringlist

The user is presented with a grid and can enter any number of words into the list.  The result is returned as a zMUD string list with the | character between each entry

picklist:valuelist

A Windows Combobox (pulldown box) is filled with the strings given in the ValueList string list.  The string selected by the user is returned as the value.  The ValueList is expanded for meta characters and for zMUD variables and functions.

pickindex:valuelist

A Combobox is filled with the strings given in the ValueList string list as above.  However, unlike the picklist, the numeric index of the selected string is returned as the value instead of the string itself.

radio:valuelist

Presents the ValueList to the user as a set of radio buttons.  The numeric index of the radio button selected (starting with zero) is returned.

check:valuelist

Presents the ValueList to the user as a set of checkboxes.  The numeric value of the checkboxes is returned, with each checkbox representing a bit position.  Thus, the first checkbox has a value of 1, the second one a value of 2, the third one a value of 4, the 4th one a value of 8 and so on.  The values are added together.  So, if the first and third checkboxes are selected, a value of 1+4=5 is returned.  There is a limit of 31 items in the ValueList.

checklist:valuelist

Similar to check in that a series of checkboxes is shown.  However, instead of returning a numeric value, a string list of the items selected is returned.  This check list can have any number of items in ValueList.

list:valuelist

Similar to picklist, but the list of items is presented in a scrollable list instead of a pulldown combobox.

listindex:valuelist

Similar to pickindex, but the list of items is presented in a scrollable list instead of a pulldown combobox.

color

A full color selection dialog is presented to the user.  Color values appropriate for the #COLOR or #CW commands are returned.  Specifically, the user can either select an ANSI color attribute, returned as a numeric value, or can select web colors from a pulldown list, or can select any RGB color returned as an #RRGGBB string.  If both a foreground and background color are selected, they are returned separated by a comma.

message:text of message

No input is collected from the user.  The "text of message" is displayed in the wizard and the user just clicks the Next button.  The message text is expanded with any meta characters and zMUD variables or functions.

Default Values

The DefaultN string in the WIZFile can be used to specify the default value for the answer.  This string is expanded for the $1..$99 previous answers as well as the \ meta characters.  It is also expanded as a normal zMUD string for any variables or function calls.  This default value is recomputed every time you display this question until the user specifically changes it.  So, even after pressing Next and Prev it will be recomputed, allowing you to change some other answer that the default value depends upon.

Input Validation

When the user clicks the Next button to accept the current answer, this answer can be optionally validated with the ValidateN string in the WIZFile section.  The value of the ValidateN key is a zMUD expression that should return true (or non-zero) if the answer is acceptable, or return False (or zero) if the answer is not allowed.

For example, if you wanted the user to enter a number from 1 to 10 inclusive, you could do the following:

Param1=Enter a number from 1 to 10
Type1=number
Validate1=($1 >= 1) and ($1 <= 10)

Note that the answer entered by the user is referenced using the normal %nnn syntax.  %1 refers to the answer of the Param1 question, %2 refers to the answer of the Param2 question, and so forth.  Previous answers are always available so you can use previous answers in your validation test.

Input Conversion

After the answer from the user is validated, it can also be optionally converted.  To convert the answer to a different form, use the ConvertN string in the WIZFile section and specify a zMUD function string.  For example, to replace all occurrences of the CR/LF in a Memo result with the | character, you could do the following:

Param1=Enter some text
Type1=memo
Convert1=%replace("$1",%char(13)%char(10),"|")

This example uses the zMUD %replace function to replace all occurrences of character 13 and character 10 with the | character.  Any zMUD function can be used here, including COM calls and other advanced features.  You can also write conversion functions in VBScript using the normal %mss function in zMUD.  Remember that the %1..%nn parameters will be replaced directly as string values before the conversion function is parsed.

Controlling Flow of Questions

Normally when the user clicks the Next button, the next question will be asked.  To change this and jump to a different question, you can use the StepN string in the WIZFile.  This is a function that should evaluate to a numeric value.  If the value is zero, the next step is taken as normal.  If a -1 value is returned, the wizard will jump to the end, present the command to the user and allow the user to click the Finish button.  Otherwise, if another number is returned, that question number is asked next.

Command Generation

When all of the questions have been answered, the %1..%nn variables contain the answers given by the user.  The value of the Command string in the WIZFile section is now parsed with the %1..%nn parameters replaced by the text given by the user.  The resulting command string is presented to the user in a syntax-checker window with the PrettyPrint and Multiline options set.  The user can edit this script, and the script will be executed when the user clicks the Finish button.

At any step you can override the Command string using the CommandN string in the WIZfile.  When an answer is accepted, the optional CommandN argument will replace the current command.  If CommandN starts with a + character, it is appended to the current command along with the current command separator character (;)

Just before the final command is presented to the user, it is expanded for any <> syntax to perform any immediate evaluation.  This allows you to construct the command in a variable and then expand the variable to present the full command to the user.

During the entire wizard, zMUD sets the default class to a temporary class folder.  This temporary class is deleted just before the final command from the wizard is executed.  The final command is executed in the user's current default class.

Example

The ZMUDWIZARD.INI file comes with several examples.  Here is one of the examples for creating a trigger to color various words sent by the MUD:

[Change the color of certain words sent by the MUD]
Author=Zugg
Version=1.0
Param1=Enter the list of words you want to color.
Type1=stringlist
Param2=Select the color to display these words.
Type2=color
Command=\#TRIGGER {{$1}} {\#CW "$2"}

Notice the use of \# to convert this to whatever special character the player is using for the command character.

Conclusion

The power of zMUD scripting can be used to create quick complex rules for the Simple Trigger Wizard.  This provides a good way to help new users learn how zMUD scripting works since they are able to see the result before it is executed.