[Home] [Downloads] [Search] [Help/forum]


Register forum user name Search FAQ

Gammon Forum

[Folder]  Entire forum
-> [Folder]  MUSHclient
. -> [Folder]  Tips and tricks
. . -> [Subject]  Callback routines

Callback routines

It is now over 60 days since the last post. This thread is closed.     [Refresh] Refresh page


Posted by Nick Gammon   Australia  (22,973 posts)  [Biography] bio   Forum Administrator
Date Mon 15 Apr 2002 02:12 AM (UTC)

Amended on Mon 15 Apr 2002 02:13 AM (UTC) by Nick Gammon

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:

  1. Name of the calling trigger (ie. the contents of the "label" field)
  2. The entire matching line that caused the trigger to fire
  3. 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):

  1. Name of the calling alias (ie. the contents of the "label" field)
  2. 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.
  3. 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. &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'>".

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
[Go to top] top

The dates and times for posts above are shown in Universal Co-ordinated Time (UTC).

To show them in your local time you can join the forum, and then set the 'time correction' field in your profile to the number of hours difference between your location and UTC time.


6,414 views.

It is now over 60 days since the last post. This thread is closed.     [Refresh] Refresh page

Go to topic:           Search the forum


[Go to top] top

Quick links: MUSHclient. MUSHclient help. Forum shortcuts. Posting templates. Lua modules. Lua documentation.

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

[Home]


Written by Nick Gammon - 5K   profile for Nick Gammon on Stack Exchange, a network of free, community-driven Q&A sites   Marriage equality

Comments to: Gammon Software support
[RH click to get RSS URL] Forum RSS feed ( https://gammon.com.au/rss/forum.xml )

[Best viewed with any browser - 2K]    [Hosted at HostDash]