Scripting callbacks - MXP
When using MXP you can have various events call a script in your script file. This lets you customise your handling of things like errors, variables being set, and so on. To add these script handlers, go to the Configuration screen -> Scripts and click on the "MXP" button. Then fill in the names of the routines you wish to call. The actual names do not matter, as long as they agree with the names used in your script file. Some example scripts are shown below, these also illustrate the correct argument lists for each function. Plugins You can also call these routines inside plugins. In this case they must have fixed names, as there is no way of configuring the names to be used. Each item indicates the appropriate name to be used in a plugin. MXP startup This is called when MXP is started. Inside a plugin: OnPluginMXPstart
    sub OnMXPStart
      world.Note "MXP started."
    end sub
MXP shutdown This is called when MXP is stopped. Inside a plugin: OnPluginMXPstop
    sub OnMXPShutdown
      world.Note "MXP stopped."
    end sub
MXP errors This routine is called whenever an error, warning or information message is generated by MXP. This routine is called regardless of the "MXP debug" level you have set in your configuration screen. This lets you handle MXP errors in your own way. For instance, set the "MXP debug" level to "none" and display selected message to the output window or a notepad window. Note: Lua exception For Lua scripts, the arguments are passed in a different order than described below, namely: Error number Line number Error level Error message For example:
    function OnMXPError (number, line, level, message)
    -- processing here
    end -- function
Inside a plugin: OnPluginMXPerror The first argument is the "level" of the message, namely: "E" - error "W" - warning "I" - information "A" - all other messages You might choose to only display "E" messages. The second argument is the message number. This is a different number for each message, so you could choose to filter in (or out) particular message numbers. See the next posting for a list of message numbers. The third argument is the line number of the current line in the output buffer (actually the count of lines in the output buffer). Effectively this identifies the line which caused the error, although in a sense the line is only a "nearby" line as MXP tags do not necessarily in themselves cause output to be sent to the output window. Also, if the output buffer fills up, and lines at the top are discarded, then the line number will eventually become incorrect. For example, if you have an error in line 1, the output buffer is 5,000 lines long, and you have received 10,000 lines, then clearly line 1 in the output buffer is not the same line 1 that reported the error. If you are trying to debug MXP problems you are advised to set your output buffer size to some large figure (eg. 100,000 lines) so that this problem does not arise quickly. The fourth argument is the message text itself, which is usually pretty self-explanatory, and includes the name of the tag or item in error.
    function OnMXPError (level, number, line, message)
      if level = "E" and number <> 1030 then
        world.NoteColourName "white", "red"
        world.Note level + "(" + cstr (number) + "): " _
                   + message
      end if

    ' do not display entities received (eg. &lt; )
      if number = 20001 then OnMXPError = 1

    end function
If you want to fine-tune which errors are shown in the standard MXP message window, you can return a non-zero value for any messages that are to be suppressed. The example above returns 1 to suppress message 20001 from appearing in the message window. MXP start tag This routine is called when a "start" tag is parsed (successfully). For example, "<send href='go west'>". Inside a plugin: OnPluginMXPopenTag Some tags, marked as EMPTY, do not have end tags, and thus you would need to detect them here, rather than looking for their end tag. The arguments are: 1. Tag name, eg. "send". The name will always be in lower case. 2. Arguments as provided, eg. "href='go west'" 3. Arguments parsed into a list. There will be one entry in the list for each argument. They will be supplied in the format "name=value", eg. "href=go west". If there were quotes around the argument value they will be removed. Thus, to find the name and the value, everything before the first "=" is the argument name, everything after the first "=" is the argument value. Arguments without a name will be named by an ascending number, eg. "1=prompt" means "prompt" is the first un-named argument. You are advised to not use world.note to display the tag name/arguments to the output window, because this is likely to interfere with the MXP routines which are trying to work out, for example, which words to underline. You are best sending any debug information to another window, as in the example below.
    function OnMXPStartTag (name, args, mylist)

      dim i

      world.AppendToNotepad "MXP", _
           "Opening tag: " + name + vbCRLF
      world.AppendToNotepad "MXP", _
           "Argument list: " + args + vbCRLF

      if not IsEmpty (mylist) then
        for i = lbound (mylist) to ubound (mylist)
          world.AppendToNotepad "MXP", _
           "Arg " + cstr (i) + " = " + mylist (i) + vbCRLF
        next
      End If

      ' suppress color tags

      if name = "color" then OnMXPStartTag = 1

    end function
If you want to suppress certain tags, you can return a non-zero value for the corresponding tag name, as in the example above. MXP end tag This routine is called when an "end" tag is parsed (successfully). For example, "</send>". Inside a plugin: OnPluginMXPcloseTag Some tags, marked as EMPTY, do not have end tags. The arguments are: 1. Tag name, eg. "send" 2. Value of "&text;" variable. In other words, everything that appeared between the start tag and the end tag. This is limited to 1000 characters maximum. For example, if you had: <send>eat newspaper</send> The value of &text; would be "eat newspaper".
    sub OnMXPEndTag (name, text)

      world.AppendToNotepad "MXP", _
           "Closing tag: " + name + vbCRLF
      world.AppendToNotepad "MXP", _
           "Text: " + text + vbCRLF
    end sub
MXP set variable This is called when MXP sets a MUSHclient variable (by using the FLAG parameter on an element definition). Inside a plugin: OnPluginMXPsetVariable MXP variables are prefixed by "mxp_" so that they do not clash with variable names that you might already be using in your scripts. The arguments are: 1. Variable name, eg. "mxp_hp" 2. Value of variable, eg. "22"
    sub OnMXPvariable (name, contents)
      world.note "Var " + name + " set to " + contents
    end sub
Setting an MXP entity (plugins only) Inside a plugin you can detect an entity being changed by the MXP code from the MUD (not using the script SetEntity function). Inside a plugin: OnPluginMXPsetEntity The argument is: entityname=newvalue
    sub OnPluginMXPsetEntity (value)
      world.note value  ' eg. foo=bar
    end sub
See Also ... Topic Scripting (Help topic: general=mxp_callbacks) Documentation contents page