Difference between revisions of "Manual:Event Engine"

From Mudlet
Jump to navigation Jump to search
(document sysGetHttpDone / sysGetHttpError)
 
(52 intermediate revisions by 9 users not shown)
Line 27: Line 27:
 
{{note}} Mudlet also uses the event system in-game protocols (like ATCP, GMCP and others).
 
{{note}} Mudlet also uses the event system in-game protocols (like ATCP, GMCP and others).
  
== Raising an event==  
+
== Raising a custom event==  
 
To raise an event, you'd use the [[Manual:Lua_Functions#raiseEvent|raiseEvent()]] function:
 
To raise an event, you'd use the [[Manual:Lua_Functions#raiseEvent|raiseEvent()]] function:
  
Line 48: Line 48:
 
   echo("Arg  : " .. arg .. "\n")
 
   echo("Arg  : " .. arg .. "\n")
 
   -- If the event is not raised with raiseGlobalEvent() profile will be 'nil'
 
   -- If the event is not raised with raiseGlobalEvent() profile will be 'nil'
   echo("Profile: " .. (profile or "Local" .. "\n")
+
   echo("Profile: " .. (profile or "Local") .. "\n")
 
end
 
end
  
Line 62: Line 62:
 
-- Trigger the event in all OTHER profiles:
 
-- Trigger the event in all OTHER profiles:
 
raiseGlobalEvent("my_event", "Hello World!")
 
raiseGlobalEvent("my_event", "Hello World!")
 +
</syntaxhighlight>
 +
 +
To review, count and extract from an unknown number of arguments received by an event:
 +
 +
<syntaxhighlight lang="lua">
 +
function eventArgs(...)
 +
  local args = {...}
 +
  local amount = select("#", ...)
 +
  local first = select(1, ...)
 +
  echo("Number of arguments: " .. amount)
 +
  echo("\nTable of all arguments: ")
 +
  display(args)
 +
  echo("First argument: " .. first)
 +
  echo("\n\n")
 +
end
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 98: Line 113:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
{{note}}Available since Mudlet 3.19
+
{{note}} Available since Mudlet 3.19
 +
 
 +
===sysConnectionEvent===
  
===sysWindowResizeEvent===
+
Raised when the profile becomes connected to a MUD - available in 2.0-test5+.
 +
 
 +
===sysDataSendRequest===
 +
 
 +
Raised right before a command from the send(), sendAll() functions or the command line is sent to the game - useful for keeping track of what your last command was, manipulating input or even denying the command to be sent if necessary with [[Manual:Miscellaneous_Functions#denyCurrentSend|denyCurrentSend()]].
  
Raised when the main window is resized, with the new height and width coordinates passed to the event. A common usecase for this event is to move/resize your UI elements according to the new dimensions.
+
sysDataSendRequest will send the event name and the command sent (in string form) to the functions registered to it. IE: commandSent in the example below will be "eat hambuger" if the user entered only that into command line and pressed enter, send("eat hamburger"), sendAll("eat humburger", "eat fish") or sendAll("eat fish", "eat humburger")
Example
 
  
This sample code will echo whenever a resize happened with the new dimensions:
+
Note: if you'll be making use of denyCurrentSend(), you ''really should'' notify the user that you denied their command - unexperienced ones might conclude that your script or Mudlet is buggy if they don't see visual feedback. Do not mis-use this and use it as [http://en.wikipedia.org/wiki/Keylogger keylogger] either.
  
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
function resizeEvent( event, x, y )
+
-- cancels all "eat hambuger" commands
   echo("RESIZE EVENT: event="..event.." x="..x.." y="..y.."\n")
+
function cancelEatHamburger(eventName, commandSent)
 +
   if commandSent == "eat hamburger" then
 +
    denyCurrentSend() --cancels the command sent.
 +
    cecho("<red>Denied! You can't do "..commandSent.." right now.\n")
 +
  end --if commandSent == eat hamburger
 
end
 
end
 +
 +
registerAnonymousEventHandler("sysDataSendRequest", "cancelEatHamburger")
 
</syntaxhighlight>
 
</syntaxhighlight>
  
===sysWindowMousePressEvent===
+
If you wanted to control input you could set a bool after a trigger.
 
+
This is useful if you want alias like control, do not know what text will be entered, but do know a trigger that WILL occur just before the user enters the command.
Raised when a mouse button is pressed down anywhere on the main window (note that a click is composed of a mouse press and mouse release). The button number and the x,y coordinates of the click are reported.
 
Example
 
  
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
function onClickHandler( event, button, x, y )
+
function controlInput(_, command)  
   echo("CLICK event:"..event.." button="..button.." x="..x.." y="..y.."\n")
+
   if changeCMDInput then
 +
    changeCMDInput = false --set this if check to false to it doesn't occur every input
 +
    --Also set the bool check BEFORE any send() functions within a sysDataSendRequest function
 +
    sendAll(command .. "some target", command .. "some other target", true) --Duplicate and unknown command
 +
    denyCurrentSend() --Deny the original command, not the commands sent with sendAll.
 +
  end
 
end
 
end
 +
registerAnonymousEventHandler("sysDataSendRequest", "controlInput")
 
</syntaxhighlight>
 
</syntaxhighlight>
  
===sysWindowMouseReleaseEvent===
+
Take note that functions registered under sysDataSendRequest WILL trigger with ALL commands that are sent.
 +
 
 +
===sysDeleteHttpDone===
 +
 
 +
Raised whenever a [[Manual:Networking_Functions#deleteHTTP|deleteHTTP()]] request completes successfully. Arguments with the event are the URL that the request was sent to and the response body (if it's less than 10k characters).
 +
 
 +
See also [[#sysDeleteHttpError|sysDeleteHttpError]].
  
Raised when a mouse button is released after being pressed down anywhere on the main window (note that a click is composed of a mouse press and mouse release). See sysWindowMousePressEvent for example use.
+
===sysDeleteHttpError===
  
===sysLoadEvent===
+
Raised whenever a [[Manual:Networking_Functions#deleteHTTP|deleteHTTP()]] request fails. Arguments are the error message and the URL that the request was sent to.
  
Raised after Mudlet is done loading the profile, after all of the scripts, packages, and modules are installed. Note that when it does so, it also compiles and runs all scripts - which could be a good idea to initialize everything at, but beware - scripts are also run when saved. Hence, hooking only on the sysLoadEvent would prevent multiple re-loads as you’re editing the script.
+
See also [[#sysDeleteHttpDone|sysDeleteHttpDone]].
  
===sysExitEvent===
+
===sysDisconnectionEvent===
  
Raised when Mudlet is shutting down the profile - a good event to hook onto for saving all of your data.
+
Raised when the profile becomes disconnected, either manually or by the game - available in 2.0-test5+.
  
 
===sysDownloadDone===
 
===sysDownloadDone===
Line 168: Line 204:
 
You should see a result like this:
 
You should see a result like this:
  
[[File:DownloadFile_demo.png]]
+
[[File:DownloadFile_demo.png|frameless|800px]]
  
 
===sysDownloadError===
 
===sysDownloadError===
  
 
Raised when downloading a file failed - the second argument contains the error message. Starting with Mudlet 2.0-test5+, it specifies the original URL that was going to be downloaded.
 
Raised when downloading a file failed - the second argument contains the error message. Starting with Mudlet 2.0-test5+, it specifies the original URL that was going to be downloaded.
 +
 +
;Example
 +
<syntaxhighlight lang="lua">
 +
--if a download fails notify the player.
 +
function downloadErrorEventHandler(event, errorFound)
 +
    cecho("fuction downloadErrorEventHandler, "..errorFound)
 +
    debugc("fuction downloadErrorEventHandler, "..errorFound) --display to error screen in editor
 +
end --function downloadErrorEventHandler
 +
registerAnonymousEventHandler("sysDownloadError", "downloadErrorEventHandler")
 +
</syntaxhighlight>
 +
 +
===sysDropEvent===
 +
 +
Raised when a file is dropped on the Mudlet main window or a userwindow.
 +
The arguments passed areː filepath, suffix, xpos, ypos, and consolename - "main" for the main window and otherwise of the userwindow/miniconsole name.
 +
 +
{{note}} Available since Mudlet 4.8+
 +
 +
<syntaxhighlight lang="lua">
 +
function onDragAndDrop(_, filepath, suffix, xpos, ypos, consolename)
 +
  print(string.format("Dropped new file into %s: %s (suffix: %s)", consolename, filepath, suffix))
 +
end
 +
registerAnonymousEventHandler("sysDropEvent", "onDragAndDrop")
 +
</syntaxhighlight>
 +
 +
===sysExitEvent===
 +
 +
Raised when Mudlet is shutting down the profile - a good event to hook onto for saving all of your data.
 +
 +
<!-- Gamepad events do not actually seem to work --
 +
 +
===sysGamepadAxisMove===
 +
 +
Raised an axis on a gamepad is moved.
 +
 +
Event handlers receive the device ID, axis number, and the new value as a number.
 +
 +
{{note}}Available since Mudlet 3.3
 +
 +
===sysGamepadButtonPress===
 +
 +
Raised a button on a gamepad is pressed down.
 +
 +
Event handlers receive the device ID, button number, and the new value as a number.
 +
 +
===sysGamepadButtonRelease===
 +
 +
Raised a button on a gamepad is released.
 +
 +
Event handlers receive the device ID, button number, and the new value as a number.
 +
 +
{{note}}Available since Mudlet 3.3
 +
 +
===sysGamepadConnected===
 +
 +
Raised a [https://en.wikipedia.org/wiki/Gamepad gamepad] is connected. On Windows, this uses the XInput backend.
 +
 +
Event handlers receive device ID as an argument.
 +
 +
{{note}}Available since Mudlet 3.3
 +
 +
Example:
 +
 +
<syntaxhighlight lang="lua">
 +
function noticeConnection(deviceID)
 +
  local output = string.format("New gamepad connected: %s\n", deviceID)
 +
  echo(output)
 +
end
 +
 +
function noticeDisconnection(deviceID)
 +
  local output = string.format("Gamepad disconnected: %s\n", deviceID)
 +
  echo(output)
 +
end
 +
 +
function noticeButtonPress(deviceID, buttonNumber, valueNumber)
 +
  local output = string.format("Button pressed: gamepad %s, button %s, value %s\n", deviceID, buttonNumber, valueNumber)
 +
  echo(output)
 +
end
 +
 +
function noticeButtonRelease(deviceID, buttonNumber, valueNumber)
 +
  local output = string.format("Button released: gamepad %s, button %s, value %s\n", deviceID, buttonNumber, valueNumber)
 +
  echo(output)
 +
end
 +
 +
function noticeAxis(deviceID, axisNumber, valueNumber)
 +
  local output = string.format("Axis moved: gamepad %s, axis %s, value %s\n", deviceID, axisNumber, valueNumber)
 +
  echo(output)
 +
end
 +
 +
registerAnonymousEventHandler("sysGamepadConnected", "noticeConnection")
 +
registerAnonymousEventHandler("sysGamepadDisconnected", "noticeDisconnection")
 +
registerAnonymousEventHandler("sysGamepadButtonPress", "noticeButtonPress")
 +
registerAnonymousEventHandler("sysGamepadButtonRelease", "noticeButtonRelease")
 +
registerAnonymousEventHandler("sysGamepadAxisMove", "noticeAxis")
 +
</syntaxhighlight>
 +
 +
===sysGamepadDisconnected===
 +
 +
Raised a [https://en.wikipedia.org/wiki/Gamepad gamepad] is disconnected
 +
 +
Event handlers receive device ID as an argument.
 +
 +
{{note}}Available since Mudlet 3.3
 +
 +
-- Gamepad events do not actually seem to work -->
 +
 +
===sysGetHttpDone===
 +
 +
Raised whenever a [[Manual:Networking_Functions#putHTTP|putHTTP()]] request completes successfully. Arguments with the event are the URL that the request was sent to and the response body (if it's less than 10k characters).
 +
 +
This event is also raised when a post/put/delete request redirects to a ''GET''.
 +
 +
See also [[#sysGetHttpError|sysGetHttpError]].
 +
 +
{{note}}Available since Mudlet 4.10
 +
 +
===sysGetHttpError===
 +
 +
Raised whenever a [[Manual:Networking_Functions#getHTTP|getHTTP()]] request fails. Arguments are the error message and the URL that the request was sent to.
 +
 +
See also [[#sysGetHttpDone|sysGetHttpDone]].
 +
 +
{{note}}Available since Mudlet 4.10
 +
 +
===sysInstall===
 +
 +
Raised right after a module or package is installed by any means. This can be used to display post-installation information or setup things.
 +
 +
Event handlers receive the name of the installed package or module as additional argument.
 +
 +
{{note}}Installed modules will raise this event handler each time the synced profile is opened. [[sysInstallModule]] and [[sysInstallPackage]] are not raised by opening profiles.
 +
Available since Mudlet 3.1
 +
 +
<syntaxhighlight lang="lua">
 +
function myScriptInstalled(_, name)
 +
  -- stop if what got installed isn't my thing
 +
  if name ~= "my script name here" then return end
 +
 +
  print("Hey, thanks for installing my thing!")
 +
end
 +
registerAnonymousEventHandler("sysInstallPackage", "myScriptInstalled")
 +
</syntaxhighlight>
 +
 +
===sysInstallModule===
 +
 +
Raised right after a module is installed through the module dialog. This can be used to display post-installation information or setup things.
 +
 +
See also [[sysLuaInstallModule]] for when a module is installed via Lua.
 +
 +
Event handlers receive the name of the installed module as well as the file name as additional arguments.
 +
 +
{{note}}Available since Mudlet 3.1
 +
 +
===sysInstallPackage===
 +
 +
Raised right after a package is installed by any means. This can be used to display post-installation information or setup things.
 +
 +
Event handlers receive the name of the installed package as well as the file name as additional arguments.
 +
 +
{{note}}Available since Mudlet 3.1
  
 
===sysIrcMessage===
 
===sysIrcMessage===
Line 180: Line 376:
 
Starting with Mudlet 3.3, this event changes slightly to provide more information from IRC network messages.  Data such as status codes, command responses, or error messages sent by the IRC Server may be formatted as plain text by the client and posted to lua via this event.  
 
Starting with Mudlet 3.3, this event changes slightly to provide more information from IRC network messages.  Data such as status codes, command responses, or error messages sent by the IRC Server may be formatted as plain text by the client and posted to lua via this event.  
  
* '''''sender''''' argument may be the nick name of an IRC user or the name of the IRC server host, as retrievable by  [[Manual:Networking_Functions#getIrcConnectedHost|getIrcConnectedHost()]]   
+
* sender: may be the nick name of an IRC user or the name of the IRC server host, as retrievable by  [[Manual:Networking_Functions#getIrcConnectedHost|getIrcConnectedHost()]]   
* '''''channel''''' argument may not always contain a channel name, but will be the name of the target/recipient of a message or action. In some networks the name may be that of a service (like ''"Auth"'' for example.)   
+
* channel: may not always contain a channel name, but will be the name of the target/recipient of a message or action. In some networks the name may be that of a service (like ''"Auth"'' for example)   
  
 
;Example
 
;Example
Line 188: Line 384:
 
   echo(string.format('(%s) %s says, "%s"\n', target, sender, message))
 
   echo(string.format('(%s) %s says, "%s"\n', target, sender, message))
 
end
 
end
 +
 +
registerAnonymousEventHandler("sysIrcMessage", onIrcMessage)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
{{note}}Available since Mudlet 2.1
+
{{note}} Available in Mudlet 2.1+
  
===sysDataSendRequest===
+
To send a message, see [[Manual:Networking_Functions#sendIrc|sendIrc()]].
Raised right before a command from the send() function or the command line is sent to the game - useful for keeping track of what your last command was, or even denying the command to be sent if necessary with [[Manual:Miscellaneous_Functions#denyCurrentSend|denyCurrentSend()]].
+
 
 +
===sysLabelDeleted===
 +
 
 +
Raised after a label is deleted, with the former label's name as an argument.
 +
 
 +
 
 +
===sysLoadEvent===
 +
 
 +
Raised after Mudlet is done loading the profile, after all of the scripts, packages, and modules are installed. Note that when it does so, it also compiles and runs all scripts - which could be a good idea to initialize everything at once, but beware - scripts are also run when saved. Hence, hooking only on the sysLoadEvent would prevent multiple re-loads as you’re editing the script.
 +
 
 +
===sysLuaInstallModule===
 +
 
 +
Raised right after a module is installed through the Lua installModule() command. This can be used to display post-installation information or setup things.
 +
 
 +
Event handlers receive the name of the installed module as well as the file name as additional arguments.
  
Note: if you'll be making use of denyCurrentSend(), you ''really should'' notify the user that you denied their command - unexperienced ones might conclude that your script or Mudlet is buggy if they don't see visual feedback. Do not mis-use this and use it as [http://en.wikipedia.org/wiki/Keylogger keylogger] either.
+
{{note}}Available since Mudlet 3.1
  
<syntaxhighlight lang="lua">
+
===sysLuaUninstallModule===
function onNetworkOutput(_, command)
 
  if math.random(2) == 1 then
 
    echo("Hello! Sending "..command.." to the game.\n")
 
  else
 
    echo("Not your day! Denying "..command..".\n")
 
    denyCurrentSend()
 
  end
 
end
 
</syntaxhighlight>
 
  
===sysConnectionEvent===
+
Raised right before a module is removed through the lua uninstallModule command. This can be used to display post-removal information or for cleanup.
Raised when the profile becomes connected to a MUD - available in 2.0-test5+.
 
  
===sysDisconnectionEvent===
+
Event handlers receive the name of the removed module as additional argument.
Raised when the profile becomes disconnected, either manually or by the game - available in 2.0-test5+.
 
  
===sysTelnetEvent===
+
{{note}}Available since Mudlet 3.1
Raised whenever an unsupported telnet option is encountered, allowing you to handle it yourself. The arguments that get passed with the event are type, telnet option, and the message. Available in 2.1+
 
  
 
===sysManualLocationSetEvent===
 
===sysManualLocationSetEvent===
 +
 
Raised whenever the "set location" command (on the 2D mapper context menu) is used to reposition the current "player room".  It provides the room ID of the new room ID that the player has been moved to.
 
Raised whenever the "set location" command (on the 2D mapper context menu) is used to reposition the current "player room".  It provides the room ID of the new room ID that the player has been moved to.
  
{{note}}
+
{{note}}Available since Mudlet 3.0
Available in Mudlet 3.0
 
  
 
===sysMapDownloadEvent===
 
===sysMapDownloadEvent===
Raised whenever an MMP map (currently only supported by IRE games) is downloaded and loaded in.
+
 
 +
Raised whenever an [[Standards:MMP|MMP map]] is downloaded and loaded in.
 +
 
 +
===sysPostHttpDone===
 +
 
 +
Raised whenever a [[Manual:Networking_Functions#postHTTP|postHTTP()]] request completes successfully. Arguments with the event are the URL that the request was sent to and the response body (if it's less than 10k characters).
 +
 
 +
See also [[#sysPostHttpError|sysPostHttpError]].
 +
 
 +
===sysPostHttpError===
 +
 
 +
Raised whenever a [[Manual:Networking_Functions#postHTTP|postHTTP()]] request fails. Arguments are the error message and the URL that the request was sent to.
 +
 
 +
See also [[#sysPostHttpDone|sysPostHttpDone]].
  
 
===sysProtocolDisabled===
 
===sysProtocolDisabled===
 +
 
Raised whenever a communications protocol is disabled, with the protocol name passed as an argument. Current values Mudlet will use for this are: GMCP, MDSP, ATCP, MXP, and channel102.
 
Raised whenever a communications protocol is disabled, with the protocol name passed as an argument. Current values Mudlet will use for this are: GMCP, MDSP, ATCP, MXP, and channel102.
  
 
===sysProtocolEnabled===
 
===sysProtocolEnabled===
 +
 
Raised whenever a communications protocol is enabled, with the protocol name passed as an argument. Current values Mudlet will use for this are: GMCP, MDSP, ATCP, MXP, and channel102.
 
Raised whenever a communications protocol is enabled, with the protocol name passed as an argument. Current values Mudlet will use for this are: GMCP, MDSP, ATCP, MXP, and channel102.
  
Line 240: Line 455:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
===sysInstall===
+
===sysPutHttpDone===
Raised right after a module or package is being installed by any means. This can be used to display post-installation information or setup things.
 
  
Event handlers receive the name of the installed package or module as additional argument.
+
Raised whenever a [[Manual:Networking_Functions#putHTTP|putHTTP()]] request completes successfully. Arguments with the event are the URL that the request was sent to and the response body (if it's less than 10k characters).
  
{{note}}
+
See also [[#sysPutHttpError|sysPutHttpError]].
Available in Mudlet 3.1+
 
  
<syntaxhighlight lang="lua">
+
===sysPutHttpError===
function myScriptInstalled(_, name)
 
  -- stop if what got installed isn't my thing
 
  if name ~= "my script name here" then return end
 
  
  print("Hey, thanks for installing my thing!")
+
Raised whenever a [[Manual:Networking_Functions#putHTTP|putHTTP()]] request fails. Arguments are the error message and the URL that the request was sent to.
end
 
registerAnonymousEventHandler("sysInstallPackage", "myScriptInstalled")
 
</syntaxhighlight>
 
  
===sysUninstall===
+
See also [[#sysPutHttpDone|sysPutHttpDone]].
Raised right before a module or package is being uninstalled by any means. This can be used to display post-removal information or for cleanup.
 
  
Event handlers receive the name of the removed package or module as additional argument.
+
===sysSoundFinished===
  
{{note}}
+
Raised when a sound finished playing. This can be used in a music player for example to start the next song.
Available in Mudlet 3.1+
 
  
===sysInstallPackage===
+
Event handlers receive the sound file name and the file path as additional arguments.
Raised right after a package is being installed by any means. This can be used to display post-installation information or setup things.
 
  
Event handlers receive the name of the installed package as well as the file name as additional arguments.
+
{{note}}Available since Mudlet 3.1
  
{{note}}
+
===sysSyncInstallModule===
Available in Mudlet 3.1+
 
  
===sysInstallModule===
+
Raised right after a module is installed through the "sync" mechanism. This can be used to display post-installation information or setup things.
Raised right after a module is being installed through the module dialog. This can be used to display post-installation information or setup things.
 
  
 
Event handlers receive the name of the installed module as well as the file name as additional arguments.
 
Event handlers receive the name of the installed module as well as the file name as additional arguments.
  
{{note}}
+
{{note}}Available since Mudlet 3.1
Available in Mudlet 3.1+
+
 
 +
===sysSyncUninstallModule===
  
===sysSyncInstallModule===
+
Raised right before a module is removed through the "sync" mechanism. This can be used to display post-removal information or for cleanup.
Raised right after a module is being installed through the "sync" mechanism. This can be used to display post-installation information or setup things.
 
  
Event handlers receive the name of the installed module as well as the file name as additional arguments.
+
Event handlers receive the name of the removed module as additional argument.
  
{{note}}
+
{{note}}Available since Mudlet 3.1
Available in Mudlet 3.1+
 
  
===sysLuaInstallModule===
+
===sysTelnetEvent===
Raised right after a module is being installed through the lua installModule command. This can be used to display post-installation information or setup things.
 
  
Event handlers receive the name of the installed module as well as the file name as additional arguments.
+
Raised whenever an unsupported telnet option is encountered, allowing you to handle it yourself. The arguments that get passed with the event are type, telnet option, and the message. Available in 2.1+
  
{{note}}
+
===sysUninstall===
Available in Mudlet 3.1+
 
  
===sysUninstallPackage===
+
Raised right before a module or package is uninstalled by any means. This can be used to display post-removal information or for cleanup.
Raised right before a package is being removed by any means. This can be used to display post-removal information or for cleanup.
 
  
Event handlers receive the name of the removed package as additional argument.
+
Event handlers receive the name of the removed package or module as additional argument.
  
{{note}}
+
{{note}}Available since Mudlet 3.1
Available in Mudlet 3.1+
 
  
 
===sysUninstallModule===
 
===sysUninstallModule===
Raised right before a module is being removed through the module dialog. This can be used to display post-removal information or for cleanup.
+
 
 +
Raised right before a module is removed through the module dialog. This can be used to display post-removal information or for cleanup.
  
 
Event handlers receive the name of the removed module as additional argument.
 
Event handlers receive the name of the removed module as additional argument.
  
{{note}}
+
{{note}}Available since Mudlet 3.1
Available in Mudlet 3.1+
+
 
 +
===sysUninstallPackage===
 +
 
 +
Raised right before a package is removed by any means. This can be used to display post-removal information or for cleanup.
 +
 
 +
Event handlers receive the name of the removed package as additional argument.
  
===sysSyncUninstallModule===
+
{{note}}Available since Mudlet 3.1
Raised right before a module is being removed through the "sync" mechanism. This can be used to display post-removal information or for cleanup.
 
  
Event handlers receive the name of the removed module as additional argument.
+
===sysUnzipDone===
  
{{note}}
+
Raised when a zip file is successfully unzipped using unzipAsync()
Available in Mudlet 3.1+
 
  
===sysLuaUninstallModule===
+
Event handlers receive the zip file name and the unzip path as additional arguments.
Raised right before a module is being removed through the lua uninstallModule command. This can be used to display post-removal information or for cleanup.
 
  
Event handlers receive the name of the removed module as additional argument.
+
{{note}}Available since Mudlet 4.6
  
{{note}}
+
===sysUnzipError===
Available in Mudlet 3.1+
 
  
===sysSoundFinished===
+
Raised when a zip file fails to unzip using unzipAsync()
Raised when a sound finished playing. This can be used in a music player for example to start the next song.
 
  
Event handlers receive the sound file name and the file path as additional arguments.
+
Event handlers receive the zip file name and the unzip path as additional arguments.
  
{{note}}
+
{{note}}Available since Mudlet 4.6
Available in Mudlet 3.1+
 
  
<!-- does not actually seem to work
+
===sysUserWindowResizeEvent===
  
===sysGamepadConnected===
+
Raised when a userwindow is resized, with the new height and width coordinates and the windowname passed to the event. A common usecase for this event is to move/resize your UI elements according to the new dimensions.
Raised a [https://en.wikipedia.org/wiki/Gamepad gamepad] is connected. On Windows, this uses the XInput backend.
 
  
Event handlers receive device ID as an argument.
+
See alsoː [[#sysWindowResizeEvent|sysWindowResizeEvent]]
  
{{note}} Available in Mudlet 3.3+
+
Example
  
Example:
+
This sample code will echo whenever a resize happened with the new dimensions:
  
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
function noticeConnection(deviceID)
+
function resizeEvent( event, x, y, windowname )
   local output = string.format("New gamepad connected: %s\n", deviceID)
+
   echo("RESIZE EVENT: event="..event.." x="..x.." y="..y.." windowname="..windowname.."\n")
  echo(output)
 
 
end
 
end
 +
</syntaxhighlight>
  
function noticeDisconnection(deviceID)
+
===sysWindowMousePressEvent===
  local output = string.format("Gamepad disconnected: %s\n", deviceID)
+
 
  echo(output)
+
Raised when a mouse button is pressed down anywhere on the main window (note that a click is composed of a mouse press and mouse release). The button number, the x,y coordinates of the click and the windowname are reported.
end
+
 
 +
{{note}}Windowname reported in Mudlet 4.9+
  
function noticeButtonPress(deviceID, buttonNumber, valueNumber)
+
See alsoː [[#sysWindowMouseReleaseEvent|sysWindowMouseReleaseEvent]]
  local output = string.format("Button pressed: gamepad %s, button %s, value %s\n", deviceID, buttonNumber, valueNumber)
 
  echo(output)
 
end
 
  
function noticeButtonRelease(deviceID, buttonNumber, valueNumber)
+
Example
  local output = string.format("Button released: gamepad %s, button %s, value %s\n", deviceID, buttonNumber, valueNumber)
 
  echo(output)
 
end
 
  
function noticeAxis(deviceID, axisNumber, valueNumber)
+
<syntaxhighlight lang="lua">
   local output = string.format("Axis moved: gamepad %s, axis %s, value %s\n", deviceID, axisNumber, valueNumber)
+
function onClickHandler( event, button, x, y, windowname )
  echo(output)
+
   echo("CLICK event:"..event.." button="..button.." x="..x.." y="..y.." windowname="..windowname.."\n")
 
end
 
end
 
registerAnonymousEventHandler("sysGamepadConnected", "noticeConnection")
 
registerAnonymousEventHandler("sysGamepadDisconnected", "noticeDisconnection")
 
registerAnonymousEventHandler("sysGamepadButtonPress", "noticeButtonPress")
 
registerAnonymousEventHandler("sysGamepadButtonRelease", "noticeButtonRelease")
 
registerAnonymousEventHandler("sysGamepadAxisMove", "noticeAxis")
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
===sysGamepadDisconnected===
+
===sysWindowMouseReleaseEvent===
Raised a [https://en.wikipedia.org/wiki/Gamepad gamepad] is disconnected
 
  
Event handlers receive device ID as an argument.
+
Raised when a mouse button is released after being pressed down anywhere on the main window (note that a click is composed of a mouse press and mouse release).
 +
 +
See [[#sysWindowMousePressEvent|sysWindowMousePressEvent]] for example use.
  
{{note}} Available in Mudlet 3.3+
+
===sysWindowResizeEvent===
  
===sysGamepadButtonPress===
+
Raised when the main window is resized, with the new height and width coordinates passed to the event. A common usecase for this event is to move/resize your UI elements according to the new dimensions.
Raised a button on a gamepad is pressed down.
 
  
Event handlers receive the device ID, button number, and the new value as a number.
+
See alsoː [[#sysUserWindowResizeEvent|sysUserWindowResizeEvent]]
  
===sysGamepadButtonRelease===
+
Example
Raised a button on a gamepad is released.
 
  
Event handlers receive the device ID, button number, and the new value as a number.
+
This sample code will echo whenever a resize happened with the new dimensions:
  
{{note}} Available in Mudlet 3.3+
+
<syntaxhighlight lang="lua">
 
+
function resizeEvent( event, x, y )
===sysGamepadAxisMove===
+
  echo("RESIZE EVENT: event="..event.." x="..x.." y="..y.."\n")
Raised an axis on a gamepad is moved.
+
end
 
+
</syntaxhighlight>
Event handlers receive the device ID, axis number, and the new value as a number.
 
  
{{note}} Available in Mudlet 3.3+
 
  
-->
 
 
[[Category:Mudlet Manual]]
 
[[Category:Mudlet Manual]]

Latest revision as of 12:25, 2 August 2020

Event System

Events in Mudlet allow a paradigm of system-building that is easy to maintain (because if you’d like to restructure something, you’d have to do less work), enables interoperability (making a collection of scripts that work with each other is easier) and enables an event-based way of programming.

The essentials of it are as such: you use Scripts to define which events should a function to listen to, and when the event is raised, the said function(s) will be called. Events can also have function parameters with them, which’ll be passed onto the receiving functions.

Registering an event handler via UI

Registering an event handler means that you’ll be telling Mudlet what function should it call for you when an event is raised, so it’s a two step process - you need to tell it both what function you’d like to be called, and on what event should it be called.

To tell it what function should be called, create a new script, and give the script the name of the function you’d like to be called. This is the only time where an items name matters in Mudlet. You can define the function right inside the script as well, if you’d like.

Next, we tell it what event or events should this function be called on - you can add multiple ones. To do that, enter the events name in the Add User Defined Event Handler: field, press enter, and it’ll go into the list - and that is all.

Registering an event from a script

You can also register your event with the registerAnonymousEventHandler(event name, function name) function inside your scripts:

-- example taken from the God Wars 2 (http://godwars2.org) Mudlet UI - forces the window to keep to a certain size
function keepStaticSize()
  setMainWindowSize(1280,720)
end -- keepStaticSize

registerAnonymousEventHandler("sysWindowResizeEvent", "keepStaticSize")

Note Note: Mudlet also uses the event system in-game protocols (like ATCP, GMCP and others).

Raising a custom event

To raise an event, you'd use the raiseEvent() function:

raiseEvent(name, [arguments...])

It takes an event name as the first argument, and then any amount of arguments after it which will be passed onto the receiving functions.

Example of registering and raising an event

Add a script to each profile you need the event.

-- This is the function that will be called when the event is raised.
-- "event" is set to the event name.
-- "arg" is the argument(s) provided with raiseEvent/rasieGlobalEvent.
-- "profile" - Is the profile name from where the raiseGlobalEvent where triggered from
--             It is 'nil' if raiseEvent() was used.
function onMyEvent(event, arg, profile)
  echo("Event: " .. event .. "\n")
  echo("Arg  : " .. arg .. "\n")
  -- If the event is not raised with raiseGlobalEvent() profile will be 'nil'
  echo("Profile: " .. (profile or "Local") .. "\n")
end

-- Register the event handler.
registerAnonymousEventHandler("my_event", "onMyEvent")

To raise the event you can call:

-- Trigger only in the current profile:
raiseEvent("my_event", "Hello world!")

-- Trigger the event in all OTHER profiles:
raiseGlobalEvent("my_event", "Hello World!")

To review, count and extract from an unknown number of arguments received by an event:

function eventArgs(...)
  local args = {...}
  local amount = select("#", ...)
  local first = select(1, ...)
  echo("Number of arguments: " .. amount)
  echo("\nTable of all arguments: ")
  display(args)
  echo("First argument: " .. first)
  echo("\n\n")
end

Mudlet-raised events

Mudlet itself also creates events for your scripts to hook on. The following events are generated currently:

channel102Message

Raised when a telnet sub-option 102 message is received (which comprises of two numbers passed in the event). This is of particular use with the Aardwolf MUD who originated this protocol. See this forum topic for more about the Mudlet Aardwolf GUI that makes use of this.

mapOpenEvent

Raised when the mapper is opened - either the floating dock or the in-Mudlet widget.

sysAppStyleSheetChange

Raised when setAppStyleSheet is called and a new stylesheet applied to Mudlet.

-- This will respond to a future (as yet unpublished) addition to the Mudlet code that will allow some
-- of a default application style sheet to be supplied with Mudlet to compensate for some text colors
-- that do not show up equally well in both light and dark desktop themes. That, perhaps, might finally
-- allow different colored texts to be uses again for the trigger item types!
function appStyleSheetChangeEvent( event, tag, source )
  if source == "system" then
    colorTable = colorTable or {}
    if tag == "mudlet-dark-theme" then
      colorTable.blue = {64, 64, 255}
      colorTable.green = {0, 255, 0}
    elseif tag == "mudlet-light-theme" then
      colorTable.blue = {0, 0, 255}
      colorTable.green = {64, 255, 64}
    end
  end
end

Note Note: Available since Mudlet 3.19

sysConnectionEvent

Raised when the profile becomes connected to a MUD - available in 2.0-test5+.

sysDataSendRequest

Raised right before a command from the send(), sendAll() functions or the command line is sent to the game - useful for keeping track of what your last command was, manipulating input or even denying the command to be sent if necessary with denyCurrentSend().

sysDataSendRequest will send the event name and the command sent (in string form) to the functions registered to it. IE: commandSent in the example below will be "eat hambuger" if the user entered only that into command line and pressed enter, send("eat hamburger"), sendAll("eat humburger", "eat fish") or sendAll("eat fish", "eat humburger")

Note: if you'll be making use of denyCurrentSend(), you really should notify the user that you denied their command - unexperienced ones might conclude that your script or Mudlet is buggy if they don't see visual feedback. Do not mis-use this and use it as keylogger either.

-- cancels all "eat hambuger" commands
function cancelEatHamburger(eventName, commandSent)
  if commandSent == "eat hamburger" then
    denyCurrentSend() --cancels the command sent.
    cecho("<red>Denied! You can't do "..commandSent.." right now.\n")
  end --if commandSent == eat hamburger
end

registerAnonymousEventHandler("sysDataSendRequest", "cancelEatHamburger")

If you wanted to control input you could set a bool after a trigger. This is useful if you want alias like control, do not know what text will be entered, but do know a trigger that WILL occur just before the user enters the command.

function controlInput(_, command) 
  if changeCMDInput then
    changeCMDInput = false --set this if check to false to it doesn't occur every input
    --Also set the bool check BEFORE any send() functions within a sysDataSendRequest function
    sendAll(command .. "some target", command .. "some other target", true) --Duplicate and unknown command
    denyCurrentSend() --Deny the original command, not the commands sent with sendAll.
  end
end
registerAnonymousEventHandler("sysDataSendRequest", "controlInput")

Take note that functions registered under sysDataSendRequest WILL trigger with ALL commands that are sent.

sysDeleteHttpDone

Raised whenever a deleteHTTP() request completes successfully. Arguments with the event are the URL that the request was sent to and the response body (if it's less than 10k characters).

See also sysDeleteHttpError.

sysDeleteHttpError

Raised whenever a deleteHTTP() request fails. Arguments are the error message and the URL that the request was sent to.

See also sysDeleteHttpDone.

sysDisconnectionEvent

Raised when the profile becomes disconnected, either manually or by the game - available in 2.0-test5+.

sysDownloadDone

Raised when Mudlet is finished downloading a file successfully - the location of the downloaded file is passed as a second argument.

Example - put it into a new script and save it to run:

-- create a function to parse the downloaded webpage and display a result
function downloaded_file(_, filename)
  -- is the file that downloaded ours?
  if not filename:find("achaea-who-count.html", 1, true) then return end

  -- read the contents of the webpage in
  local f, s, webpage = io.open(filename)
  if f then webpage = f:read("*a"); io.close(f) end
  -- delete the file on disk, don't clutter
  os.remove(filename)

  -- parse our downloaded file for the player count
  local pc = webpage:match([[Total: (%d+) players online]])
  display("Achaea has "..tostring(pc).." players on right now.")
end

-- register our function to run on the event that something was downloaded
registerAnonymousEventHandler("sysDownloadDone", "downloaded_file")

-- download a list of fake users for a demo
downloadFile(getMudletHomeDir().."/achaea-who-count.html", "https://www.achaea.com/game/who")

You should see a result like this:

DownloadFile demo.png

sysDownloadError

Raised when downloading a file failed - the second argument contains the error message. Starting with Mudlet 2.0-test5+, it specifies the original URL that was going to be downloaded.

Example
--if a download fails notify the player.
function downloadErrorEventHandler(event, errorFound)
    cecho("fuction downloadErrorEventHandler, "..errorFound)
    debugc("fuction downloadErrorEventHandler, "..errorFound) --display to error screen in editor
end --function downloadErrorEventHandler
registerAnonymousEventHandler("sysDownloadError", "downloadErrorEventHandler")

sysDropEvent

Raised when a file is dropped on the Mudlet main window or a userwindow. The arguments passed areː filepath, suffix, xpos, ypos, and consolename - "main" for the main window and otherwise of the userwindow/miniconsole name.

Note Note: Available since Mudlet 4.8+

function onDragAndDrop(_, filepath, suffix, xpos, ypos, consolename)
  print(string.format("Dropped new file into %s: %s (suffix: %s)", consolename, filepath, suffix))
end
registerAnonymousEventHandler("sysDropEvent", "onDragAndDrop")

sysExitEvent

Raised when Mudlet is shutting down the profile - a good event to hook onto for saving all of your data.


sysGetHttpDone

Raised whenever a putHTTP() request completes successfully. Arguments with the event are the URL that the request was sent to and the response body (if it's less than 10k characters).

This event is also raised when a post/put/delete request redirects to a GET.

See also sysGetHttpError.

Note Note: Available since Mudlet 4.10

sysGetHttpError

Raised whenever a getHTTP() request fails. Arguments are the error message and the URL that the request was sent to.

See also sysGetHttpDone.

Note Note: Available since Mudlet 4.10

sysInstall

Raised right after a module or package is installed by any means. This can be used to display post-installation information or setup things.

Event handlers receive the name of the installed package or module as additional argument.

Note Note: Installed modules will raise this event handler each time the synced profile is opened. sysInstallModule and sysInstallPackage are not raised by opening profiles. Available since Mudlet 3.1

function myScriptInstalled(_, name)
  -- stop if what got installed isn't my thing
  if name ~= "my script name here" then return end

  print("Hey, thanks for installing my thing!")
end
registerAnonymousEventHandler("sysInstallPackage", "myScriptInstalled")

sysInstallModule

Raised right after a module is installed through the module dialog. This can be used to display post-installation information or setup things.

See also sysLuaInstallModule for when a module is installed via Lua.

Event handlers receive the name of the installed module as well as the file name as additional arguments.

Note Note: Available since Mudlet 3.1

sysInstallPackage

Raised right after a package is installed by any means. This can be used to display post-installation information or setup things.

Event handlers receive the name of the installed package as well as the file name as additional arguments.

Note Note: Available since Mudlet 3.1

sysIrcMessage

Raised when the IRC client receives an IRC message. The sender's name, channel name, and their message are passed as arguments to this event.

Starting with Mudlet 3.3, this event changes slightly to provide more information from IRC network messages. Data such as status codes, command responses, or error messages sent by the IRC Server may be formatted as plain text by the client and posted to lua via this event.

  • sender: may be the nick name of an IRC user or the name of the IRC server host, as retrievable by getIrcConnectedHost()
  • channel: may not always contain a channel name, but will be the name of the target/recipient of a message or action. In some networks the name may be that of a service (like "Auth" for example)
Example
function onIrcMessage(_, sender, target, message)
  echo(string.format('(%s) %s says, "%s"\n', target, sender, message))
end

registerAnonymousEventHandler("sysIrcMessage", onIrcMessage)

Note Note: Available in Mudlet 2.1+

To send a message, see sendIrc().

sysLabelDeleted

Raised after a label is deleted, with the former label's name as an argument.


sysLoadEvent

Raised after Mudlet is done loading the profile, after all of the scripts, packages, and modules are installed. Note that when it does so, it also compiles and runs all scripts - which could be a good idea to initialize everything at once, but beware - scripts are also run when saved. Hence, hooking only on the sysLoadEvent would prevent multiple re-loads as you’re editing the script.

sysLuaInstallModule

Raised right after a module is installed through the Lua installModule() command. This can be used to display post-installation information or setup things.

Event handlers receive the name of the installed module as well as the file name as additional arguments.

Note Note: Available since Mudlet 3.1

sysLuaUninstallModule

Raised right before a module is removed through the lua uninstallModule command. This can be used to display post-removal information or for cleanup.

Event handlers receive the name of the removed module as additional argument.

Note Note: Available since Mudlet 3.1

sysManualLocationSetEvent

Raised whenever the "set location" command (on the 2D mapper context menu) is used to reposition the current "player room". It provides the room ID of the new room ID that the player has been moved to.

Note Note: Available since Mudlet 3.0

sysMapDownloadEvent

Raised whenever an MMP map is downloaded and loaded in.

sysPostHttpDone

Raised whenever a postHTTP() request completes successfully. Arguments with the event are the URL that the request was sent to and the response body (if it's less than 10k characters).

See also sysPostHttpError.

sysPostHttpError

Raised whenever a postHTTP() request fails. Arguments are the error message and the URL that the request was sent to.

See also sysPostHttpDone.

sysProtocolDisabled

Raised whenever a communications protocol is disabled, with the protocol name passed as an argument. Current values Mudlet will use for this are: GMCP, MDSP, ATCP, MXP, and channel102.

sysProtocolEnabled

Raised whenever a communications protocol is enabled, with the protocol name passed as an argument. Current values Mudlet will use for this are: GMCP, MDSP, ATCP, MXP, and channel102.

function onProtocolEnabled(_, protocol)
  if protocol == "GMCP" then
    print("GMCP enabled! Now we can use GMCP data.")
  end
end

sysPutHttpDone

Raised whenever a putHTTP() request completes successfully. Arguments with the event are the URL that the request was sent to and the response body (if it's less than 10k characters).

See also sysPutHttpError.

sysPutHttpError

Raised whenever a putHTTP() request fails. Arguments are the error message and the URL that the request was sent to.

See also sysPutHttpDone.

sysSoundFinished

Raised when a sound finished playing. This can be used in a music player for example to start the next song.

Event handlers receive the sound file name and the file path as additional arguments.

Note Note: Available since Mudlet 3.1

sysSyncInstallModule

Raised right after a module is installed through the "sync" mechanism. This can be used to display post-installation information or setup things.

Event handlers receive the name of the installed module as well as the file name as additional arguments.

Note Note: Available since Mudlet 3.1

sysSyncUninstallModule

Raised right before a module is removed through the "sync" mechanism. This can be used to display post-removal information or for cleanup.

Event handlers receive the name of the removed module as additional argument.

Note Note: Available since Mudlet 3.1

sysTelnetEvent

Raised whenever an unsupported telnet option is encountered, allowing you to handle it yourself. The arguments that get passed with the event are type, telnet option, and the message. Available in 2.1+

sysUninstall

Raised right before a module or package is uninstalled by any means. This can be used to display post-removal information or for cleanup.

Event handlers receive the name of the removed package or module as additional argument.

Note Note: Available since Mudlet 3.1

sysUninstallModule

Raised right before a module is removed through the module dialog. This can be used to display post-removal information or for cleanup.

Event handlers receive the name of the removed module as additional argument.

Note Note: Available since Mudlet 3.1

sysUninstallPackage

Raised right before a package is removed by any means. This can be used to display post-removal information or for cleanup.

Event handlers receive the name of the removed package as additional argument.

Note Note: Available since Mudlet 3.1

sysUnzipDone

Raised when a zip file is successfully unzipped using unzipAsync()

Event handlers receive the zip file name and the unzip path as additional arguments.

Note Note: Available since Mudlet 4.6

sysUnzipError

Raised when a zip file fails to unzip using unzipAsync()

Event handlers receive the zip file name and the unzip path as additional arguments.

Note Note: Available since Mudlet 4.6

sysUserWindowResizeEvent

Raised when a userwindow is resized, with the new height and width coordinates and the windowname passed to the event. A common usecase for this event is to move/resize your UI elements according to the new dimensions.

See alsoː sysWindowResizeEvent

Example

This sample code will echo whenever a resize happened with the new dimensions:

function resizeEvent( event, x, y, windowname )
  echo("RESIZE EVENT: event="..event.." x="..x.." y="..y.." windowname="..windowname.."\n")
end

sysWindowMousePressEvent

Raised when a mouse button is pressed down anywhere on the main window (note that a click is composed of a mouse press and mouse release). The button number, the x,y coordinates of the click and the windowname are reported.

Note Note: Windowname reported in Mudlet 4.9+

See alsoː sysWindowMouseReleaseEvent

Example

function onClickHandler( event, button, x, y, windowname )
  echo("CLICK event:"..event.." button="..button.." x="..x.." y="..y.." windowname="..windowname.."\n")
end

sysWindowMouseReleaseEvent

Raised when a mouse button is released after being pressed down anywhere on the main window (note that a click is composed of a mouse press and mouse release).

See sysWindowMousePressEvent for example use.

sysWindowResizeEvent

Raised when the main window is resized, with the new height and width coordinates passed to the event. A common usecase for this event is to move/resize your UI elements according to the new dimensions.

See alsoː sysUserWindowResizeEvent

Example

This sample code will echo whenever a resize happened with the new dimensions:

function resizeEvent( event, x, y )
  echo("RESIZE EVENT: event="..event.." x="..x.." y="..y.."\n")
end