Scripting callbacks - plugins
The following subroutines/functions will be called in your plugin if they are present. The names are hard-coded, and a check is made to see if such names exist when the plugin is installed. As each one starts with the characters "OnPlugin" you should not get clashes with your own routines, provided you avoid using that particular prefix when naming your own subs (functions).
    OnPluginInstall
    '
    ' Plugin has been installed
    '
    sub OnPluginInstall
    end sub

    OnPluginClose
    '
    ' Plugin is being removed (closed)
    '
    sub OnPluginClose
    end sub

    OnPluginConnect
    '
    ' This world has been connected (to the MUD)
    '
    sub OnPluginConnect
    end sub

    OnPluginDisconnect
    '
    ' This world has been disconnected (from the MUD)
    '
    sub OnPluginDisconnect
    end sub

    OnPluginSaveState
    '
    ' The plugin is about to save its state
    ' If you want to create new variables to be saved (eg. save script variables as MUSHclient variables)
    '  now is the time to do it.
    '
    sub OnPluginSaveState
    end sub

    OnPluginEnable
    '
    ' The plugin is being enabled
    '
    sub OnPluginEnable
    end sub

    OnPluginDisable
    '
    ' The plugin is being disabled
    '
    sub OnPluginDisable
    end sub

    OnPluginCommand

    '
    '  The player has typed the command 'sText'
    '  Return TRUE to process the command, FALSE to discard it
    '
    Function OnPluginCommand (sText)
      OnPluginCommand = vbTrue  ' process it
    End Function

    OnPluginCommandEntered

    '
    ' The player has typed the command 'sText' and pressed <Enter>
    '
    ' You can modify the command in this function, and return the modified string
    '   which is what will be sent to the command processor.
    ' If you return an empty string, that will sent to the command processor.
    ' If you return a tab character on its own (\t or hex 09) then the command will be
    ' discarded, and the command window cleared (unless auto-repeat commands is set).
    '
    ' If you return a carriage-return character on its own (\r or hex 0D) then the command will be
    ' discarded, and retained in the command window.
    '
    ' This differs from OnPluginCommand which processes individual command lines,
    '  after command stacking and other processing has taken place.
    '
    '  The example replaces line breaks by %r.
    '
    '  You might use this to implement your own "rules" for evaluating command stacking,
    '  spell checking, keeping a command history, and so on.
    '

    Function OnPluginCommandEntered (sText)
      OnPluginCommandEntered = world.Replace (sText, vbCrLf, "%r", vbTrue)
    End Function

    OnPluginTabComplete

    '
    ' The player has typed some text into the command window and pressed <Tab>.
    '
    ' The tab completion processing has found a match.
    '
    ' You can modify the match text in this function, and return the modified string
    '   which is what will be replaced into the command window.

    Function OnPluginTabComplete (s)
      MsgBox (s)
    End Function

    OnPluginSend
    '
    '  MUSHclient is proposing to send 'sText' to the MUD
    '  Return TRUE to send the text, FALSE to discard it
    '
    ' If any plugin returns FALSE, then the text is not actually sent.
    '
    ' If you want to know what was actually sent, use OnPluginSent (below).
    '
    '  If you call world.Send from within this function, OnPluginSend is not called again (however OnPluginSent will be).
    '
    Function OnPluginSend (sText)
      OnPluginSend = vbTrue  ' process it
    End Function

    OnPluginSent
    '
    '  MUSHclient is definitely sending 'sText' to the MUD
    '
    ' This is called after every plugin has a chance to reject the text in the
    '   OnPluginSend callback.
    '
    '  An example of use of this would be for an auto-mapper, as this function gets
    '   text that has definitely been sent to the MUD.
    '
    ' If you call world.Send from within this callback, it will return an error.
    '
    '  OnPluginSent is supposed to be recording what is being sent, not sending new things.
    '
    Sub OnPluginSent (sText)
    End Sub

    OnPluginLineReceived
    '
    '  MUSHclient has received the line 'sText'
    '  Return TRUE to process the text, FALSE to discard it
    '
    Function OnPluginLineReceived (sText)
      OnPluginLineReceived = vbTrue  ' display it
    End Function
In the case of routines like OnPluginCommand, each plugin is scanned for every command entered. If any plugin returns FALSE, then that command is not processed. This gives each plugin a chance to respond to various commands, and suppress them if it wants to. Likewise for OnPluginSend and OnPluginLineReceived.
    OnPluginPacketReceived
    '
    '  MUSHclient has received the packet 'sText'
    '
    Function OnPluginPacketReceived (sText)
    End Function
This function is called when each incoming packet (data) arrives from the MUD. A packet does not necessarily start or end on line boundaries, and may consist of partial lines, or more than one line. You can return data from this function (in version 3.59 onwards). If you do, then the returned data will replace the incoming data. In other words, you can change words, omit lines, add new lines, and MUSHclient will proceed as if the altered line had arrived from the MUD.
    OnPluginPartialLine
This will be called when one of these events occurs: A line fills up (eg. you hit 80 characters if that is your screen width) A newline is received A partial packet is received, and no more input is currently available The plugin is passed the current line - not just the new text - (which may or may not be "full" if the third condition is met) - which it can then test or pass into a VB regular expression for more complex testing. This is intended to catch those situations where you need an immediate update (eg. a prompt line, entering a username/password when the newline is not present) on data received from the MUD. Note that triggers will still be evaluated in the usual way, at the usual time. The plugin callback just gives you the chance to get at it sooner.
    sub OnPluginPartialLine (sText)
      AppendToNotepad "test", sText & vbCrLf
    end sub
    OnPluginBroadcast
When a script calls BroadcastPlugin then all installed plugins are checked for a function OnPluginBroadcast. If present, it is called with 4 arguments: The message number (the first argument to BroadcastPlugin). The ID of the calling plugin, or an empty string if BroadcastPlugin was called from the main script file. The name of the calling plugin, or an empty string if BroadcastPlugin was called from the main script file. The Text argument (the second argument to BroadcastPlugin) An example of a plugin handler might be (in Lua):
    function OnPluginBroadcast (msg, id, name, text)
      Note ("msg = " .. msg)
      Note ("id = " .. id)
      Note ("name = " .. name)
      Note ("text = " .. text)
    end
The calling plugin ID and name are supplied so that plugin writers can verify which plugin originated a particular message. This cannot be spoofed as it is supplied automatically by MUSHclient.
    OnPluginTrace
This is called when you have tracing turned on. If a plugin is found with this function in it, then it is called and the trace line is not displayed on the world output window. Only the first plugin found is called. Example, in Lua:
    function OnPluginTrace (line)
      AppendToNotepad ("Trace", line .. "\r\n")
    end
    OnPluginScreendraw
This is intended for people with screen readers, who want the contents of the main window read out, however don't want gagged text to be read. The current way MUSHclient works is to draw text as it arrives, and then "undraw it" if it is gagged. This approach doesn't really work with screen readers, as they can't "unread" something. The arguments to OnPluginScreendraw are: Type: type of line, where 0 = output line, 1 = note, 2 = command Log: are we planning to log it? Line: the text of the line itself An example plugin function, which simply copies the text to a notepad window, is as follows:
    function OnPluginScreendraw (type, log, line)
      AppendToNotepad ("mylog", type, " ", log, " ", line, "\r\n")
    end -- function
    OnPluginPlaySound
This is called when MUSHclient intends to play a sound (eg. new activity sound, trigger sound, world.Sound script function). If it finds a plugin with the OnPluginPlaySound function defined, then that is called, and the internal sound-player is not used. The only argument is the sound file name that is to be played.
    function OnPluginPlaySound (sound)
      Note ("Playing sound ", sound)
    end -- function
If you select the Display > Stop Sound Playing menu item, then OnPluginPlaySound will be called with an empty file name. Chat System Callbacks
    OnPluginChatAccept

    '  MUSHclient has received a connection from IP,name
    '  Return TRUE to accept it, FALSE to reject it
    '
    Function OnPluginChatAccept (sText)

    dim theList
    dim username, ip

      theList = split (sText, ",")
      ip = theList (0)
      username = theList (1)

    End Function

    OnPluginChatMessage

    '  MUSHclient has received chat message: id, type, text
    '  Return TRUE to use the default processing, FALSE to ignore it
    '
    '  See the Chat.xml plugin for the exact message numbers that might be received.

    Function OnPluginChatMessage (id, message, sText)
      OnPluginChatMessage = vbTrue  ' process it
    End Function

    OnPluginChatMessageOut

    '  MUSHclient is about to send chat message: id, type, text
    '  Return TRUE to use the default processing, FALSE to ignore it
    '
    '  See the Chat.xml plugin for the exact message numbers that might be sent.

    Function OnPluginChatMessageOut (id, message, sText)
      OnPluginChatMessage = vbTrue  ' process it
    End Function

    OnPluginChatDisplay

    '
    '  MUSHclient is about to display message: type, text
    '  Return TRUE to use the default display, FALSE to not display
    '
    '  See the Chat.xml plugin for the exact message types that might be received.
    '

    Function OnPluginChatDisplay (message, sText)
      OnPluginChatDisplay = vbTrue  ' display it
    End Function

    OnPluginChatNewUser

    '
    ' A new plugin user has been accepted on: id, name
    '
    '
    ' This script callback has been provided so you can take action if
    ' you want (such as allowing file transfers).
    '

    sub OnPluginChatNewUser (id, name)
    end sub

    OnPluginChatUserDisconnect

    ' This chat user has disconnected for one reason or another.
    '
    ' This callback lets you take action (eg. notify others) however
    ' you cannot send messages to this connection or change any options
    ' once they have disconnected. The chat id is supplied so you can
    ' match the id to the one that connected.
    '
    ' For each call to OnPluginChatNewUser there should eventually be a
    ' corresponding call to OnPluginChatUserDisconnect.
    '
    sub OnPluginChatUserDisconnect (id, name)
    end sub
See Also ... Topic Scripting (Help topic: general=plugin_callbacks) Documentation contents page