Using MXP

The Mud eXtension Protocol (MXP) is used to add special effects to the text sent from the MUD. Comparing a MUD with MXP output to a normal MUD is much like comparing a web page to a text page. On a web page you can have colors, different fonts, bold, italic, graphics etc. MXP adds similar commands to the MUD output, and even looks very similar to the HTML or XML language that is used for web pages.

However, MXP is not just something the MUD server can implement. You can use MXP commands in your own scripts to enhance the text displayed in your MUD window.

For MUD coders and implementors interested in the details on the MXP specification, go to the www.zuggsoft.com web site and you will find the latest version of the spec in the Support Library. Here, we are just going to document the most common features of MXP that a zMUD user might use within triggers or scripts.

Using MXP commands

MXP commands are grouped into two categories: Open and Secure. Open commands can appear on any line on the screen without restriction. To use Open MXP commands on the zMUD command line, make sure the "Expand MXP tags in command line" option is turned on in your MXP Preferences page.

Secure MXP commands can only be executed on lines from the MUD (or from your script) that are "tagged" as secure. The MXP spec instructs the MUD coders how to tag lines as "secure" when being sent from the MUD. To output text to your screen from a script in secure mode, use the #MXP command described below, or place your MXP commands in a #SUBSTITUTE command within a trigger. Examples of this are given below.

Open MXP Commands

Here is a list of Open MXP commands that you can use without restriction:

, <bold> or : use a bold font
, <italic> or : use an italic font
 or <underline>: underline the text
<s> or <strikeout>: draw a line through the text
<color foreground background>: change the text colors
: change the font being used

Each of these commands is a toggle. The command changes the way in which text is displayed. To turn off the command, use </command> where "command" is the name of the command that you started. So, for example, to display the word "test" in bold font, you would use:
This is a test
Note that all Open MXP commands are automatically terminated at the end of a line, even if you don't turn off the command yourself.

To use MXP from the command line is a bit tricky because the < character used in MXP is already used in zMUD to indicate forced variable expansion. So, to prevent zMUD from parsing the < and to let the < character be sent to the MXP processor, put a ~ in front of the < character. So, on the command line you can enter:
#ECHO This is a ~test~
and the word "test" will be displayed in a bold font.

To change color, use the <color> command. The first parameter is the foreground color, and the second parameter, which is optional, is the background color. So, the command:
#ECHO This is a ~<color red>test~</color>
will display the word "test" in red. And the command:
#ECHO This is a ~<color white blue>test~</color>
will display "test" in white characters on a blue background.
Instead of using the name of a color, you can also specify the RGB (red,green,blue) values for the color using the syntax #RRGGBB where RR GG and BB are hexadecimal values indicating a color level from zero (00) to 255 (FF). This is the advantage of MXP over standard ANSI colors. Standard ANSI only allows 8 colors (16 if the Bold command is used for highlighting colors). But the MXP color command can use any color value that your video card can display.

To change the font, use the command. In addition to selecting the font name and size, you can optionally change the color at the same time instead of using a separate <color> command. The only current restriction with the command is that if you try to change the font size to something larger than the current MUD font, it won't display properly. This will be improved in a future version of zMUD.
So, the command:
#ECHO This is a ~test~
will display the word "test" using the Greek Symbol font.

Secure MXP Commands

Secure MXP commands allow more that just visual effects. Secure MXP commands can perform almost any operation in zMUD, including creating triggers, aliases, etc. Since you can already do much of this from a script already, you probably won't use MXP for this. However, since the MUD Server can send secure MXP commands, these features allow the MUD server to create and run it's own scripts on your system. MXP contains a lot of security, and not every zMUD command can be executed by an MXP script. Only "safe" commands can be executed remotely by the MUD server using MXP. For example, the MUD server cannot use the #FILE or #READ/#WRITE commands to access your hard disk. MUD Servers cannot access plugins or use COM scripting. Basically, any command that would give the MUD access to your computer system is not allowed within MXP. Even if the MUD server creates an alias, that alias is tagged as an MXP alias and is still restricted in the commands it can execute.

The MXP specification contains a full list of Secure MXP commands, including commands that allow you to define your own MXP commands. However, here we will focus just on the commands that are useful to a zMUD user in their scripts.

<a>: Define a web URL for a hyperlink
<send>: Define a hyperlink that executes a zMUD command, or creates a menu

As with Open MXP commands, each secure command is a toggle that must be turned off using the </command> syntax. Unlike Open commands, Secure MXP commands are NOT automatically closed at the end of a line. So, be sure and close them yourself or you will get unpleasant results.

Both of these MXP commands create "hyperlinks". Like on a web page, clicking on a hyperlink performs an action. With the <a> command, the action is to tell your web browser to load a particular URL. This is much like the #URL command. With the <send> command, the action performed by clicking on the hyperlink is to execute a command line and send it to the MUD. The <send> command can also be used to create a special right-click menu which can contain multiple commands.

There are two ways to use Secure MXP commands from zMUD scripts. The easiest method is the #MXP command. The #MXP command works just like the #SHOW command, except it allows for Secure MXP commands. Also, the < character is already escaped, so you don't need the ~ in front of it.

For example, to create a standard web hyperlink, you could do:

#MXP This is a <a "http://www.zuggsoft.com/">hyperlink</a>

By default, the text "hyperlink" will be underlined (this can be turned off in the MXP Preferences). If you move the mouse over the underlined "hyperlink" the mouse hint "http://www.zuggsoft.com/" will be displayed. If you click on the hyperlink, your web browser will open the page www.zuggsoft.com. You can change the mouse hint using the second argument to the <a> command:

#MXP This is a <a "http://www.zuggsoft.com" "Zugg Software">hyperlink</a>

In this case, when you move the mouse over the link, the help text "Zugg Software" will be displayed.

The URL can be anything that your browser understands, including mailto: for sending email.

The <send> command also creates a hyperlink, but instead of calling your web browser, it just sends a command back to the MUD. So, for example, the command:

#MXP This is a <send>test</send>

will underline the text "test" by default as a hyperlink. If you move the mouse over the "test" hyperlink, the mouse hint will show "test". If you click on the hyperlink, the command "test" is sent to the MUD. This works just as if "test" was entered on the command line, so if you have an alias called "test", it will be executed.

To change the command sent to the MUD, use the first argument of the <send> command. So, the command:

#MXP This is a <send "hello">test</send>

will create a hyperlink called "test", but now, when you click on it, the command "hello" is sent to the MUD instead.

To change the help text displayed when the mouse is over the link, use the second argument to the <send> command. So:

#MXP This is a <send "hello" "help me">test</send>

will still send the "hello" command when you click on the link, but now the mouse-over help will say "help me"

The most powerful form of the <send> command will create a right-click menu of multiple commands. This is done by using a string list for the commands and for the help text. The first command in the list will still be sent if you just left-click the link. But if you right-click the link, the other commands will be shown, and the other items in the string list for the help argument will be used as the menu captions. So, for example:

#MXP This is a <send "hello|command1|command2" "help me|First command|Second command">test</send>

will create a hyperlink called "test". If you move the mouse over it, the "help me" text will be displayed. If you left-click on the hyperlink, the command "hello" is sent to the MUD. However, if you right-click on the hyperlink, you will get a popup menu with 3 commands listed. The first item will say "help me" and will send "hello" to the MUD when you select it. This is the same as left-clicking on the hyperlink. The second item in the menu will say "First command" and will send "command1" to the MUD when you select it. The third item in the menu will say "Second command" and will send "command2" to the MUD when you select it.

Here is a more practical example that a MUD might use if you are in a store trying to buy an item:

#MXP There is some <send "buy bread|examine bread|steal bread" "buy|examine|steal">bread</send> here.

The text "bread" will be underlined as a hyperlink. If you move the mouse over "bread", the "buy" help text will be displayed. If you click on the hyperlink, the command "buy bread" is sent to the MUD. However, if you right-click the hyperlink you are given the options to "examine" the bread, or "steal" the bread. This allows the MUD to provide a lot of command options hidden within the normal text of the MUD.

Using MXP in the #SUBSTITUTE command

Instead of using the #MXP command to send Secure MXP commands to the screen, you can also create a trigger and then use the #SUBSTITUTE command to add MXP commands to the text. For example,

#TRIGGER {north} {#SUB {~<send>north~</send>}}

will replace the word "north" whenever it is displayed by the MUD and replace it with the text <send>north</send> which creates a hyperlink. If you click on the "north" hyperlink, the command "north" is sent to the MUD.