Register forum user name Search FAQ

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


function OnMXPStart ()
  Note "MXP started."
end -- function




MXP shutdown

This is called when MXP is stopped.

Inside a plugin: OnPluginMXPstop


function OnMXPShutdown ()
  Note "MXP stopped."
end -- function




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 
    ColourNote ("white", "red", level .. "(" .. number .. "): " message)
  end if

-- do not display entities received (eg. < )
  if number == 20001 then 
     return 1
  end -- if

  return 0
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. (This only applies in the main script file, not plugins).



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.

Note: Lua exception

For Lua scripts, the arguments are passed as single string in the format:


  • tagname,arguments ... eg: sound,volume=1 pan=2 name="boing.wav"


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)

  AppendToNotepad ("MXP", "Opening tag: " .. name .. "\n")
  AppendToNotepad ("MXP", "Argument list: "  .. args .. "\n")

  
  if mylist then
    for k, v in pairs (mylist) do
      AppendToNotepad ("MXP", "Arg " .. k .. " = " + v .. "\n")
    end -- for
  end -- if

  -- suppress color tags

  if name == "color" then 
    return 1
  end -- if

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.

Note: Lua exception

For Lua scripts, the arguments are passed as single string in the format:


  • tagname,text ... eg: send,eat newspaper


For example, if you had:

<send>eat newspaper</send>

The value of &text; would be "eat newspaper".


function OnMXPEndTag (name, text)
  AppendToNotepad ("MXP", "Closing tag: " .. name .. "\n")
  AppendToNotepad ("MXP", "Text: " .. text .. "\n")
end -- function




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"

Note: Lua exception

For Lua scripts, the arguments are passed as single string in the format:


  • variable, value ... eg: max_hp,22



function OnMXPvariable (name, contents)
  Note ("Var " .. name .. " set to " .. contents)
end -- function


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


function OnPluginMXPsetEntity (value)
  Note (value)  -- eg. foo=bar
end -- function

See Also ...

Topic

Scripting

(Help topic: general=mxp_callbacks)

Documentation contents page

Search ...

Enter a search string to find matching documentation.

Search for:   

Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.

Home