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.
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.
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.
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.
There are several different parameter types that determine the type of answer you want the user to give to your question:
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.
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.
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.
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.
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.
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.
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.