Difference between revisions of "Manual:Event Engine"

From Mudlet
Jump to navigation Jump to search
(→‎sysDataSendRequest: added denyCurrentSend() in else way)
(→‎Event System: fixed syntax highlighting)
Line 16: Line 16:
 
You can also register your event with the ''[[Manual:Miscellaneous_Functions#registerAnonymousEventHandler|registerAnonymousEventHandler(event name, function name)]]'' function inside your scripts:
 
You can also register your event with the ''[[Manual:Miscellaneous_Functions#registerAnonymousEventHandler|registerAnonymousEventHandler(event name, function name)]]'' function inside your scripts:
  
<lua>
+
<syntaxhighlight lang="lua">
 
-- example taken from the God Wars 2 (http://godwars2.org) Mudlet UI - forces the window to keep to a certain size
 
-- example taken from the God Wars 2 (http://godwars2.org) Mudlet UI - forces the window to keep to a certain size
 
function keepStaticSize()
 
function keepStaticSize()
Line 23: Line 23:
  
 
registerAnonymousEventHandler("sysWindowResizeEvent", "keepStaticSize")
 
registerAnonymousEventHandler("sysWindowResizeEvent", "keepStaticSize")
</lua>
+
</syntaxhighlight>
  
 
{{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).
Line 30: Line 30:
 
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:
  
<lua>raiseEvent(name, [arguments...])</lua>
+
<syntaxhighlight lang="lua">raiseEvent(name, [arguments...])</syntaxhighlight>
  
 
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.
 
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.
Line 37: Line 37:
 
Add a script to each profile you need the event.
 
Add a script to each profile you need the event.
  
<lua>
+
<syntaxhighlight lang="lua">
  
 
-- This is the function that will be called when the event is raised.
 
-- This is the function that will be called when the event is raised.
Line 45: Line 45:
 
--            It is 'nil' if raiseEvent() was used.
 
--            It is 'nil' if raiseEvent() was used.
 
function onMyEvent(event, arg, profile)
 
function onMyEvent(event, arg, profile)
echo("Event: " .. event .. "\n")
+
  echo("Event: " .. event .. "\n")
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
  
 
-- Register the event handler.
 
-- Register the event handler.
 
registerAnonymousEventHandler("my_event", "onMyEvent")
 
registerAnonymousEventHandler("my_event", "onMyEvent")
</lua>
+
</syntaxhighlight>
  
 
To raise the event you can call:
 
To raise the event you can call:
<lua>
+
<syntaxhighlight lang="lua">
 
-- Trigger only in the current profile:
 
-- Trigger only in the current profile:
 
raiseEvent("my_event", "Hello world!")
 
raiseEvent("my_event", "Hello world!")
Line 62: Line 62:
 
-- Trigger the event in all profiles:
 
-- Trigger the event in all profiles:
 
raiseGlobalEvent("my_event", "Hello World!")
 
raiseGlobalEvent("my_event", "Hello World!")
</lua>
+
</syntaxhighlight>
  
 
{{note}} Global events needs Mudlet 3.1.0.
 
{{note}} Global events needs Mudlet 3.1.0.
Line 83: Line 83:
 
This sample code will echo whenever a resize happened with the new dimensions:
 
This sample code will echo whenever a resize happened with the new dimensions:
  
<lua>
+
<syntaxhighlight lang="lua">
 
function resizeEvent( event, x, y )
 
function resizeEvent( event, x, y )
 
   echo("RESIZE EVENT: event="..event.." x="..x.." y="..y.."\n")
 
   echo("RESIZE EVENT: event="..event.." x="..x.." y="..y.."\n")
 
end
 
end
</lua>
+
</syntaxhighlight>
  
 
===sysWindowMousePressEvent===
 
===sysWindowMousePressEvent===
Line 94: Line 94:
 
Example
 
Example
  
<lua>
+
<syntaxhighlight lang="lua">
 
function onClickHandler( event, button, x, y )
 
function onClickHandler( event, button, x, y )
 
   echo("CLICK event:"..event.." button="..button.." x="..x.." y="..y.."\n")
 
   echo("CLICK event:"..event.." button="..button.." x="..x.." y="..y.."\n")
 
end
 
end
</lua>
+
</syntaxhighlight>
  
 
===sysWindowMouseReleaseEvent===
 
===sysWindowMouseReleaseEvent===
Line 118: Line 118:
 
Example - put it into a new script and save it to run:
 
Example - put it into a new script and save it to run:
  
<lua>
+
<syntaxhighlight lang="lua">
 
-- create a function to parse the downloaded webpage and display a result
 
-- create a function to parse the downloaded webpage and display a result
 
function downloaded_file(_, filename)
 
function downloaded_file(_, filename)
Line 140: Line 140:
 
-- download a list of fake users for a demo
 
-- download a list of fake users for a demo
 
downloadFile(getMudletHomeDir().."/achaea-who-count.html", "https://www.achaea.com/game/who")
 
downloadFile(getMudletHomeDir().."/achaea-who-count.html", "https://www.achaea.com/game/who")
</lua>
+
</syntaxhighlight>
  
 
You should see a result like this:
 
You should see a result like this:
Line 154: Line 154:
 
Raised when you see or receive an IRC message. The speakers name, channel and their message will follow as arguments.
 
Raised when you see or receive an IRC message. The speakers name, channel and their message will follow as arguments.
  
<lua>
+
<syntaxhighlight lang="lua">
 
function onIrcMessage(_, person, channel, message)
 
function onIrcMessage(_, person, channel, message)
 
   echo(string.format('(%s) %s says, "%s"\n', channel, person, message))
 
   echo(string.format('(%s) %s says, "%s"\n', channel, person, message))
 
end
 
end
</lua>
+
</syntaxhighlight>
  
 
<sub>Added to Mudlet in an unreleased 2.0rc8</sub>
 
<sub>Added to Mudlet in an unreleased 2.0rc8</sub>
Line 167: Line 167:
 
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: 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.
  
<lua>
+
<syntaxhighlight lang="lua">
 
function onNetworkOutput(_, command)
 
function onNetworkOutput(_, command)
 
   if math.random(2) == 1 then
 
   if math.random(2) == 1 then
Line 176: Line 176:
 
   end
 
   end
 
end
 
end
</lua>
+
</syntaxhighlight>
  
 
===sysConnectionEvent===
 
===sysConnectionEvent===
Line 201: Line 201:
 
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.
  
<lua>
+
<syntaxhighlight lang="lua">
 
function onProtocolEnabled(_, protocol)
 
function onProtocolEnabled(_, protocol)
 
   if protocol == "GMCP" then
 
   if protocol == "GMCP" then
Line 207: Line 207:
 
   end
 
   end
 
end
 
end
</lua>
+
</syntaxhighlight>
  
 
===sysInstall===
 
===sysInstall===

Revision as of 05:24, 29 June 2017

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 an 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 profiles:
raiseGlobalEvent("my_event", "Hello World!")

Note Note: Global events needs Mudlet 3.1.0.

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.

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. 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

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 and the x,y coordinates of the click are reported. Example

function onClickHandler( event, button, x, y )
  echo("CLICK event:"..event.." button="..button.." x="..x.." y="..y.."\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.

sysLoadEvent

Raised when Mudlet is loading the profile. 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.

sysExitEvent

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

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.

sysIrcMessage

Raised when you see or receive an IRC message. The speakers name, channel and their message will follow as arguments.

function onIrcMessage(_, person, channel, message)
  echo(string.format('(%s) %s says, "%s"\n', channel, person, message))
end

Added to Mudlet in an unreleased 2.0rc8

sysDataSendRequest

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 denyCurrentSend().

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.

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

sysConnectionEvent

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

sysDisconnectionEvent

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

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+

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: Present since Mudlet 3.0.0 Epsilon preview.

sysMapDownloadEvent

Raised whenever an MMP map (currently only supported by IRE games) is downloaded and loaded in.

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, GMCP, 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

sysInstall

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.

Note Note: Available in Mudlet 3.1+

sysUninstall

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.

Note Note: Available in Mudlet 3.1+

sysInstallPackage

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 Note: Available in Mudlet 3.1+

sysInstallModule

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.

Note Note: Available in Mudlet 3.1+

sysSyncInstallModule

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.

Note Note: Available in Mudlet 3.1+

sysLuaInstallModule

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.

Note Note: Available in Mudlet 3.1+

sysUninstallPackage

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.

Note Note: Available in Mudlet 3.1+

sysInstallModule

Raised right before a module is being 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 in Mudlet 3.1+

sysSyncInstallModule

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.

Note Note: Available in Mudlet 3.1+

sysLuaInstallModule

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 Note: Available in Mudlet 3.1+

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 in Mudlet 3.1+