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

DOC_scripting Scripting

(Help topic: general=plugin_callbacks)

DOC_contents Documentation contents page