                  MXP Documentation
------------------------------------------------------

MXP is a protocol based off of HTML and XML that was developed by Zugg for Zmud.  
As of the writing of this Doc file, it is only available on Zmud and Mushclient.
If you want to see some other doc files over it, you can view them from the
Zmud site or the Mushclient site.  The links are below

    http://www.zuggsoft.com/zmud/mxp.htm
    http://www.mushclient.com/mxp.htm
    
Both of these are protocol documentation for both of their clients.  If something
new is added, I will try to update this documentation.  This is also written with
the purposes of explaining how it is used in Fear instead of the protocol itself.

First off, what exactly is MXP, what can it do, do I want it, and how do I turn it
off if I do not want it.  As mentioned before, MXP is a markup language that allows
you to do a little more than use straight text.  It allows you to use a full 16 bit
color range (same as a webpage allows, so no more 16 colors) and it allows you to
put in point and click links.  This allows you to click on something to say move or
right click on something to get options.  This is very useful with newbies if they
have not learned the command syntax yet (or simply do not want to learn it, laugh).
The most powerful parts of the code if you ask me is the ability to use inline images.
This is currently available for Zmud as of this writing, but it should be available
for Mushclient sometime down the road.  This allows you to use images in your mud
if you wish.  Along with this feature, you can create frames out of your mud to
allow for multiple output frames for things such as maps, stats, pictures, and channels.

Well, the question of do I want it depends on what you are looking for.  If you do
not like these features, well then you probably want to shut this feature off.  All you
need to do to do this is go into mud.h and find the #define for USE_MXP 1 and change it
to USE_MXP 0 to turn off the feature mud wide.  In future releases, I might put in a player
toggle for this at creation, but as of 1.1.1, it is mud wide or nothing.  Now, for how
to implement or add things.
----------------------------------------

1.  Color usage.

Again, this is a very powerful feature if you ask me.  The ability to use only 16 colors
can be annoying in some instances.  This opens up a good avenue for adding in new colors
if you wish.  An off pink color was added to this release to give you an example of
what you can do.  If you use &e you will change the color of a string to this offpink
color.  You can then use &E to end the color change and go back to the color that you
were using originally.  If a non mxp client sees this, nothing will change for that
user, they will continue to see the standard color.  You can find this additional code
in comm.c in make_color_sequence.  It is as follows

  else if (*col == 'e')
  {
     write_to_buffer(d, MXPTAG("color #FFB6C1"), 0);
     ln = 0;
  }
  else if (*col == 'E')
  {
     write_to_buffer(d, MXPTAG("/color"), 0);
     ln = 0;
  }
  
As you see, e changes the color and E ends the color.  If you wish to add a new color, just
place it below the e and make sure not to use one already selected (like r R or p P).  This
in itself has limitations and eventually a new parsing command will be created.  I will
probably write one for 2.1 eventually, but for the time being, this is your best bet for
allowing players to set their own colors.  Inside the code, you can do this very easily.

ch_printf(ch, "I am going to change "MXPC("FFB6C1")"the color just like that &E");

You do not need to provide the </color> because &E is already set up to do that, a very
useful and quick change :-).  Now you can add color to anything, mxp is detected as soon
as someone logins, so you can even set it up during login (if you haven't noticed, the
level of the player in score is using this feature already).  

2.  Adding in 1 click commands.

This is very simple because of an element I set up called Command.  All you need to do
is this.

sprintf(buf1, "&G&W[" MXPFTAG("Command 'learn \"%s\"' desc='Click here to see what %s Teaches'", "TRAINER", "/Command") "] %s", 
      victim->name, victim->name, char_color_str(AT_PERSON, ch));
      
Above is an example in 2.1 that I use.  When you look in a room you see this

[TRAINER]

If you click on the Trainer text it will give you a list of what the trainer can
teach to you.  If you look carefully at the mess above, you see "&G&W[" this is the
start of the string, it ends with a " because you cannot send a MXP tag in a string.  Once
that is finished, you can send the MXPFTAG macro.  The first part of the Macro

"Command 'learn \"%s\"' desc='Click here to see what %s Teaches'"

Is the Command tag and it performs the following learn "Riona" if Riona is the
name of the trainer.  Then it sends a hint if you hover over the link of Click here
to see what Riona teachs.

The next part

"TRAINER" 

Is the text that is sent to the character.  This is the TRAINER in [TRAINER]

The last part

"/Command")

Ends the command Tag

Lastly, 

"] %s", 

Ends the ] in [TRAINER] and then sets the color to AT_PERSON.  

3.  Adding in Right click menus

This is a much more complex activity because you have to add a new Element.  An element
is a tag you create to avoid typing in a massively huge element.  Below is an example
of the Drop element.  You can modify this or add your own new elements in turn_on_mxp
in comm.c

       write_to_buffer( d, MXPTAG 
       ("!ELEMENT Drop \"<send href='"
            "drop &#39;&name;&#39;|"
            "examine &#39;&name;&#39;|"
            "look in &#39;&name;&#39;|"
           "wear &#39;&name;&#39;|"
           "eat &#39;&name;&#39;|"
            "drink &#39;&name;&#39;"
        "' "
        "hint='RH mouse click to use this object|"
            "Drop &name;|"
            "Examine &name;|"
            "Look inside &name;|"
            "Wear &name;|"
            "Eat &name;|"
            "Drink &name;"
        "'>\" ATT='name'"), 
       0);
       
This is fairly straight forward

!ELEMENT Drop \" - Defines the Element, it is called drop.  \" is simply a " and starts the elment
<send href='" - A send tag, for clicking on things :-)

            "drop &#39;&name;&#39;|"
            "examine &#39;&name;&#39;|"
            "look in &#39;&name;&#39;|"
           "wear &#39;&name;&#39;|"
           "eat &#39;&name;&#39;|"
            "drink &#39;&name;&#39;"
This is the what is sent to the mud when you click on it.  First line is drop &#39; (that is
simply a " symbol) and then &name.  This is an argument that is provided by the Drop element.
It is declared at the bottom (ATT='name')  Then the &#39; again then a |.  The | means another
option follows below that one.

"' " - Ends the send href tag (send href = ' ').  

"hint='RH mouse click to use this object|"
            "Drop &name;|"
            "Examine &name;|"
            "Look inside &name;|"
            "Wear &name;|"
            "Eat &name;|"
            "Drink &name;"
This is the hint text that is sent to the player when they hover over the link for 2 seconds.
It pretty much follows the same rules as above.

"'>\" ATT='name'") - First is a ' that ends the hint = ' ' and then a \" that ends the ELEMENT
define.  The last thing is the ATT='name'.  This is the arguments that are passed when you
call the elment.  Below is an example of a call to this Element

ch_printf(ch, MXPFTAG("Drop '%s", "%s", "/Drop"), obj->name, obj->name);

As you can see the elment Drop is used and the name of the object is passed to the
element.  The second part is the text that shows up, then the end of the tag.

4.  Adding a picture (ZMUD only)

Pictures can be fun, you can use them for custom artwork or simply to allow players to post
pictures up of themselves.  I do not have any custom support in for pictures in this version,
it might be added later.  It is not to hard to add a URL location for players to add in
pictures to add to their finger and bio.  Anyway, here is the syntax for including pictures
loaded from the client and on the Fly

The following loads an image already in the client.  You need to save the picture to directory
where Zmud is installed (mine is c:\zmud).  Once it is there, the picture will show up
correctly.  It is important to add the align tag because without it, the picture will actual
overrun some text and create problems.

ch_printf(ch, "%s", MXPTAG("Image tree2.bmp align=bottom"));

The following is used to load images on the fly.  It will load an image from a website and
store it in the profile for the Zmud connection (ex:  c:\zmud\Rafermand\images).  Once it
is loaded, the picture will be there so you do not need to redownload it.  As of this writing,
if you mistype the URL and it loads nothing, there will be a 0k file in your profile that you
need to delete to make the picture show up once you get the URL correct.

ch_printf(ch, "%s", MXPTAG("Image fname=\"title1.jpg\" url=\"http://www.rafermand.net/\" align=bottom")






    
   
