|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 functions. The example code below is in Lua.
In the case of routines like OnPluginCommand (about to send a command to the MUD), 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 (attempting to send a line of text to the MUD) and OnPluginLineReceived (received a line of text from the MUD).
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 text lines, or more than one line. If compression (MCCP) is active, the packet is the data after decompression.
Be warned that when compression is turned on, one packet may contain both uncompressed and compressed data (with the "turn on compression" sequence between them). Changing data in that packet may cause decompression to fail, if you alter the compressed part of the packet.
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.
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 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.
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):
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.
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:
This is called when you have packet debugging turned on. If a plugin is found with this function in it, then it is called and the packet debug is not displayed in a notepad window. Only the first plugin found is called.
Example, in Lua:
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:
This is intended to allow plugin writers to make a miniwindow that has text that scrolls with the output window. It is called at the start of drawing (refreshing) the output window (eg. when a new line arrives from the MUD, or after a Note).
The arguments to OnPluginDrawOutputWindow are:
FirstLine: The first line number which is going to be drawn (starting at 1). You can use GetLineInfo to get details about that line.
ScrollOffset: The pixel position which it will start drawing at (based on the scroll bar thumb position). You can use that to tweak which pixel to start drawing at vertically.
NotUsed: An empty string (required because of the way plugin callbacks are implemented).
Example of echoing the line number in the output buffer, plus the text of the line is:
Do not call WindowCreate inside this callback or strange things may happen as it is in the middle of drawing to the output device context. Reserve creating the window for OnPluginInstall and OnPluginWorldOutputResized.
Do not call Repaint inside this callback or the client will go into an infinite loop (it is already repainting the window, so trying to repaint it while repainting it will cause a loop). Also do not do things like print to the output window (eg. using Note) as that will cause the output window to be redrawn, and then the callback will be called again, and so on.
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.
If you select the Display > Stop Sound Playing menu item, then OnPluginPlaySound will be called with an empty file name.
This is called when the output window is resized.
This is called when the mouse is moved inside the output window.
The x and y arguments (long integers) give the location of the mouse, relative to the top-left corner of the current world's output window.
The third argument is the miniwindow ID of any miniwindow the mouse may happen to be over, or "" if it is not over a miniwindow.
This is called 25 times a second.
This is called 25 times a second (every 40 milliseconds), even if timers are disabled.
It is intended as a simple way of doing things that need to be done smoothly and more rapidly than timers allow (timer granularity is set to a minimum of 1/10 of a second). For example, when using the sound functions such as PlaySound, you could smoothly fade music up or down using this callback.
Also you might use it to implement scrolling text (eg. a miniwindow that says "Critical Hit!") which smoothly scrolls up the screen and disappears. The callback is called 25 times a second as 25 fps (frames per second) is about the minimum for smooth animation, so animated effects (like scrolling text) should look reasonably smooth if implemented using this.
Warning! This is implemented using a Windows timer event (WM_TIMER). This is a low-priority event, which means it may not be called if other things are happening. In other words, the timer may fire less frequently than 25 times a second, depending on what else is happening.
This is called if the server sends IAC WILL x, or IAC DO x to the client. In that case the callback lets you decide whether or not to handle the protocol (eg. ATCP or ZMP). The following protocols are handled internally and may not cause a call to this function (in some cases for DO and in some cases for WILL):
1 (ECHO) - output echo on/off
3 (SGA) - Suppress Go Ahead
24 (TERMTYPE) - send terminal type
25 (EOR) - End Of Record
31 (NAWS) - Negotiate About Window Size
70 (MSSP) - MUD Server Status Protocol
85 (MCCP v1) - MUD Client Compression Protocol version 1
86 (MCCP v2) - MUD Client Compression Protocol version 2
91 (MXP) - MUD eXtension Protocol
102 (Aardwolf options) - used by Aardwolf MUD and some MUSHclient plugins
If you return true then MUSHclient will send a positive response to the server and then call OnPluginTelnetRequest a second time with another code, as follows:
If it initially called the plugin with "WILL" it will call back with "SENT_DO".
If it initially called the plugin with "DO" it will call back with "SENT_WILL".
This is because the positive response to WILL is DO, and the positive response to DO is WILL. This second call to OnPluginTelnetRequest lets you do extra processing after agreeing to the negotiation with the server, such as logging on to it.
The OnPluginTelnetRequest function should return true to indicate it handled the message, or false if it did not. Once OnPluginTelnetRequest returns true in one plugin, no further plugins are checked. This is to stop multiple plugins logging in, as presumably a single login is all that is required.
This is called if the server sends IAC SB x <data> IAC SE to the client. In that case the callback lets you handle the protocol yourself. The following types are not sent as they are handled internally.
24 (terminal type)
85 (MCCP v1)
86 (MCCP v2)
In the case of type 102, then OnPluginTelnetOption is called as well (without the option number, as that is fixed at 102).
Note - despite the above example, it is not recommended that you do Notes (or anything similar) when receiving telnet subnegotiation packets. Doing a Note may switch the current line from "MUD output" to "Note line" in ways that are not expected, particularly if you are hoping to trigger on the next line that arrives.
This is called if the server sends IAC SB 102 <data> IAC SE to the client. In that case the callback lets you handle the protocol yourself. This is similar to OnPluginTelnetSubnegotiation but is included separately for backwards compatibility. Note that OnPluginTelnetSubnegotiation is also called (afterwards), so new scripts can just use OnPluginTelnetSubnegotiation.
This is called if the server sends IAC GA (0xFF 0xF9) or IAC EOR (0xFF 0xEF) to the client. This is intended for situations like where the ATCP protocol sends a whole lot of telnet negotiation sequences, and then IAC GA when waiting for player input. In this case the IAC GA could be a signal to a plugin to start responding.
Chat System Callbacks
See Also ...
Lua base functions
(Help topic: general=plugin_callbacks)
Enter a search string to find matching documentation.
Information and images on this site are licensed under the Creative Commons Attribution 3.0 Australia License unless stated otherwise.
Gammon Software support
Forum RSS feed ( https://gammon.com.au/rss/forum.xml )