Posted by
| Nick Gammon
Australia (22,973 posts) bio
Forum Administrator |
Message
| There seems to be some confusion about how MUSHclient scripts should be called from triggers, aliases and the like. This is probably partly because they are only really documented by example, in the example script files supplied with the client. For sake of completeness, this post will describe them in more detail.
What is a callback routine anyway?
This term is used to describe what happens when the client "calls back" into the script file. For example, when a trigger fires. Each one has a different format. If you don't supply a callback routine in the correct format (right number of arguments) then you will get an error message.
The examples are in VBscript, but will look very similar in JScript and Perlscript. See the example script files for the exact syntax.
Triggers
Triggers take three arguments:
- Name of the calling trigger (ie. the contents of the "label" field)
- The entire matching line that caused the trigger to fire
- The first 9 wildcards, and wildcard (10) which is "the entire matching text".
The example below will just display the information it receives ...
sub OnTrigger (strName, strLine, aryWildcards)
dim i
world.note "Trigger " & strName & " fired."
world.note "Matching line: " & strLine
for i = 1 to 9
world.note "Wildcard " & i & " = " & aryWildcards (i)
next
world.note "Matching text = " & aryWildcards (10)
end sub
The distinction between "matching text" (wildcard 10) and "matching line" is that, in a regular expression they may be different.
For example:
Match on: the monster .* flees
Regular expression: checked
If you had the line: "you notice that the monster dragon flees immediately".
The trigger would be supplied these:
strLine (matching line): you notice that the monster dragon flees immediately
aryWildcards (10) (matching text): the monster dragon flees
The difference is because a regular expression can match a partial line.
Aliases
Aliases take three arguments (just like triggers):
- Name of the calling alias (ie. the contents of the "label" field)
- The generated text (ie. what will be sent the MUD, if anything) with wildcard replacements done (eg. wildcard 1 put into %1). Also, variables will have been replaced.
- The first 9 wildcards, and wildcard (10) which is "the entire matching text".
The example below will just display the information it receives ...
sub OnAlias (strName, strLine, aryWildcards)
dim i
world.note "Alias " & strName & " fired."
world.note "Line to be sent: " & strLine
for i = 1 to 9
world.note "Wildcard " & i & " = " & aryWildcards (i)
next
world.note "Matching text = " & aryWildcards (10)
end sub
Timers
Timers take one argument - the name of the timer.
sub OnTimer (strName)
world.note "Timer " & strName & " fired."
end sub
World open/close/connect/disconnect/get focus/lose focus
All of these scripts take zero arguments, as they are "unnamed" events.
sub OnWorldOpen
world.note "---------- World Open ------------"
end sub
sub OnWorldClose
world.note "---------- World Close ------------"
end sub
sub OnWorldConnect
world.note "---------- World Connect ------------"
end sub
sub OnWorldDisconnect
world.note "---------- World Disconnect ------------"
end sub
sub OnWorldGetFocus
world.note "---------- World Got Focus ------------"
end sub
sub OnWorldLoseFocus
world.note "---------- World Lost focus ------------"
end sub
MXP startup
This is called when MXP is started.
sub OnMXPStart
world.Note "MXP started."
end sub
MXP shutdown
This is called when MXP is stopped.
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.
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. < )
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'>".
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>".
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).
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
|
- Nick Gammon
www.gammon.com.au, www.mushclient.com | top |
|