Manual:Event Engine

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:

<lua> -- 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") </lua>

Note: Mudlet also uses the event system for the ATCP and GMCP events.

Raising an event

To raise an event, you’d use the raiseEvent function:

<lua>raiseEvent(name, [arguments...])</lua>

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.

Mini-tutorial

As an example, our prompt trigger could raise an onPrompt event if you want to attach 2 functions to it. In your prompt trigger, all you’d need to do is raiseEvent("onPrompt"). Now we go about creating functions that attach to the event - lets say the first one is check_health_stuff() and the other is check_salve_stuff(). We would like these to be executed when the event is raised. So create a script and give it a name of check_health_stuff. In the Add user defined event handler, type onPrompt, and press enter to add it to the list. In the script box, create:

<lua> function check_health_stuff()

 echo("I work!\n")

end </lua>

When the onPrompt event comes along, that script catches it, and runs check_health_stuff() for you.

Link title

Mudlet-raised events

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

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:

<lua> function resizeEvent( event, x, y )

 echo("RESIZE EVENT: event="..event.." x="..x.." y="..y.."\n")

end </lua>

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

<lua> function onClickHandler( event, button, x, y )

 echo("CLICK event:"..event.." button="..button.." x="..x.." y="..y.."\n")

end </lua>

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. For a practical example, see the downloadFile() function.

sysDownloadError

Raised when downloading a file failed - the second argument contains the error message. Does not specify which file download has failed yet, however.

sysIrcMessage

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

<lua> function onIrcMessage(_, person, channel, message)

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

end </lua>

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

<lua> 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")
 end

end </lua>

GMCP

GMCP is a protocol for MUD servers to communicate information with MUD clients in a separate channel from the one which carries all of the text that makes up the game itself. Mudlet can be configured to use GMCP by clicking on the Settings button (or Options->Preferences in the menu, or <alt>p). The option is on the General tab. Once GMCP is enabled, you will need to reconnect to the MUD so that Mudlet can inform the server it is ready to receive GMCP information. Mudlet will automatically enable some GMCP modules for you once GMCP has been enabled. To get an idea of what information is available, you can use <lua> display(gmcp) </lua>

When working with GMCP on IRE games, their GMCP reference is a useful tool.

Using GMCP

Receiving GMCP Data

To use the GMCP messages you'll need to create a new script and give it a name. Now register an event handler for the module you want to use. Now you'll need to create a function with exactly the same name as the script file. This function will be called each time you get the GMCP message. The information itself will be saved in the corresponding field of the gmcp table.

Here's a screenshot of the setup you need:

Sending GMCP Data

Certain modules will only send data when a request is made by your client. In Mudlet, you can make such a request using the command sendGMCP("command"). Read your MUD's relevant documentation, such as the IRE document on GMCP, for information about specific modules.

See Also: Manual:Lua_Functions#sendGMCP

Managing GMCP Modules

While some GMCP modules are enabled by Mudlet by default when you connect with a GMCP enabled MUD, others may not be 'standard' modules and are instead specific to the MUD itself. In order to provide a way to manage GMCP modules without scripts causing modules in use by other scripts to be disabled, the gmod lua module has been included with Mudlet (rc2.0+).

Registering User

While this step is no longer strictly required, you can register your 'user' with gmod using <lua> gmod.registerUser("MyUser") </lua> Where MyUser is your plugin/addon/whatever name. However, your user will be automatically registered if you enable or disable any modules using it. Which leads us to...

Enabling Modules

Enabling a GMCP module is as easy as: <lua> gmod.enableModule("MyUser", "Module.Name") </lua>

If MyUser has not been registered previously, then they will be automatically registered when you call this function. An example of a module which would need to be enabled this way is the IRE.Rift module provided by IRE MUDs. <lua> gmod.enableModule("MyUser", "IRE.Rift") </lua>

Disabling Modules

Disabling a GMCP module is just as easy as enabling it: <lua> gmod.disableModule("MyUser", "Module.Name") </lua> The main difference being that the module will be turned on as soon as you enable it if it is not already enabled. If you disable it, it will not be disabled with the server until every user of that module has disabled it. This prevents script A from disabling modules that script B may still be using.