Manual:Miscellaneous Functions

Miscellaneous Functions

addSupportedTelnetOption

addSupportedTelnetOption(option)

Adds a telnet option, which when queried by a MUD server, Mudlet will return DO (253) on. Use this to register the telnet option that you will be adding support for with Mudlet - see additional protocols section for more.

Example

<lua> <event handlers that add support for MSDP... see http://www.mudbytes.net/forum/comment/63920/#c63920 for an example>

-- register with Mudlet that it should not decline the request of MSDP support local TN_MSDP = 69 addSupportedTelnetOption(TN_MSDP) </lua>

closeMudlet

closeMudlet()

Closes Mudlet and subsequently all profiles immediately.

See also: saveProfile()

Note: Use with care. This potentially lead to data loss, if "save on close" is not activated and the user didn't save the profile manually as this will NOT ask for confirmation nor will the profile be saved.

Note: Available in Mudlet 3.1+

Example

<lua> closeMudlet() </lua>

expandAlias

expandAlias(command,true/false)

Runs the command as if it was from the command line - so aliases are checked and if none match, it's sent to the the game. If the second argument is false, it will hide the command from being echoed back in your buffer. Defaults to true.

Example

<lua> expandAlias("t rat")

-- don't echo the command expandAlias("t rat", false) </lua>

Note: If you want to be using the matches table after calling expandAlias, you should save it first as local oldmatches = matches before calling expandAlias, since expandAlias will overwrite it after using it again.

feedTriggers

feedTriggers( text )

This function will have Mudlet parse the given text as if it came from the MUD - one great application is trigger testing. The built-in `echo alias provides this functionality as well.

Example

<lua> -- try using this on the command line `echo This is a sample line from the game

-- You can use \n to represent a new line - you also want to use it before and after the text you’re testing, like so: feedTriggers("\nYou sit yourself down.\n")

-- The function also accept ANSI color codes that are used in MUDs. A sample table can be found http://codeworld.wikidot.com/ansicolorcodes feedTriggers("\nThis is \27[1;32mgreen\27[0;37m, \27[1;31mred\27[0;37m, \27[46mcyan background\27[0;37m," .. "\27[32;47mwhite background and green foreground\27[0;37m.\n") </lua>

getModulePath

path = getModulePath(module name)

Returns the location of a module on the disk.

See also: installModule()

Note: Available in Mudlet 3.0+

Example

<lua> getModulePath("mudlet-mapper") </lua>

getModulePriority

priority = getModulePriority(module name)

Returns the priority of a module as an integer. This determines the order modules will be loaded in - default is 0. Useful if you have a module that depends on another module being loaded first, for example.

See also: setModulePriority()

Example

<lua> getModulePriority("mudlet-mapper") </lua>

getMudletHomeDir

getMudletHomeDir()

Returns the current home directory of the current profile. This can be used to store data, save statistical information, or load resource files from packages.

Example

<lua> -- save a table table.save(getMudletHomeDir().."/myinfo.dat", myinfo)

-- or access package data. The forward slash works even on Windows fine local path = getMudletHomeDir().."/mypackagename" </lua>

getMudletLuaDefaultPath

getMudletLuaDefaultPath()

Returns the compiled in default location that this version of Mudlet tries as the last ditch attempt to find the luaGlobal.lua Lua script. luaGlobal.lua is the "loader" for all the Mudlet (and included Geyser but NOT Vyzor GUI management system packages) - failure to find this when a profile is loaded will be associated with a:

[ ERROR ] - LuaGlobal.lua compile error - please report!

message in the main console, instead of the expected:

[ OK ] - Mudlet-lua API & Geyser Layout manager loaded.

Note: This command is initially for *nix (but NOT MacOs) versions that need to support having shared, read-only copies of non-executable files used by an application in a directory that is not directly associated with that executable; for MacOs and Windows version it will not return a useful result either an empty string "" or a single slash "/". It is currently present only in the development branch of code in the GitHub repository and will not be included in the 3.0.0 release or it's previews.

getMudletVersion

getMudletVersion(style)

Returns the current Mudlet version. Note that you shouldn't hardcode against a specific Mudlet version if you'd like to see if a function is present - instead, check for the functions existence itself. Otherwise, checking for the version can come in handy if you'd like to test for a broken function or so on.

Note: Available since Mudlet 3.0.0-alpha.

Parameters

• style:

Optional - allows you to choose what you'd like returned. By default, if you don't specify it, a key-value table with all the values will be returned.

Values you can choose

• "string":

Returns the full Mudlet version as text.

• "table":

Returns the full Mudlet version as four values (multi-return)

• "major":

Returns the major version number (the first one).

• "minor":

Returns the minor version number (the second one).

• "revision":

Returns the revision version number (the third one).

• "build":

Returns the build of Mudlet (the ending suffix, if any).

Example

<lua> -- see the full Mudlet version as text: getMudletVersion("string")

-- check that the major Mudlet version is at least 3: if getMudletVersion("major") >= 3 then echo("You're running on Mudlet 3+!") end

-- if you'd like to see if a function is available however, test for it explicitly instead: if setAppStyleSheet then

 -- example credit to http://qt-project.org/doc/qt-4.8/stylesheet-examples.html#customizing-qscrollbar
 setAppStyleSheet[[
 QScrollBar:vertical {
     border: 2px solid grey;
     background: #32CC99;
     width: 15px;
     margin: 22px 0 22px 0;
 }
 QScrollBar::handle:vertical {
     background: white;
     min-height: 20px;
 }
 QScrollBar::add-line:vertical {
     border: 2px solid grey;
     background: #32CC99;
     height: 20px;
     subcontrol-position: bottom;
     subcontrol-origin: margin;
 }
 QScrollBar::sub-line:vertical {
     border: 2px solid grey;
     background: #32CC99;
     height: 20px;
     subcontrol-position: top;
     subcontrol-origin: margin;
 }
 QScrollBar::up-arrow:vertical, QScrollBar::down-arrow:vertical {
     border: 2px solid grey;
     width: 3px;
     height: 3px;
     background: white;
 }
 QScrollBar::add-page:vertical, QScrollBar::sub-page:vertical {
     background: none;
 }
 ]]

end </lua>

getProfileName

name = getProfileName()

Returns the name of the profile

Note: Available in Mudlet 3.1+

Example

<lua> -- if connected to the Achaea profile, will print Achaea to the main console echo(getProfileName()) </lua>

installModule

installModule(location)

Installs a Mudlet XML or zip as a module.

Parameters

• location:

Exact location of the file install.

See also: uninstallModule()

Example

<lua> installModule(C:\Documents and Settings\bub\Desktop\myalias.xml) </lua>

installPackage

installPackage(location)

Installs a Mudlet XML or package.

Parameters

• location:

Exact location of the xml or package to install.

See also: uninstallPackage()

Example

<lua> installPackage(C:\Documents and Settings\bub\Desktop\myalias.xml) </lua>

openWebPage

openWebPage(URL)

Opens the browser to the given webpage.

Parameters

• URL:

Exact URL to open.

Example

<lua> openWebPage("http://google.com") </lua>

playSoundFile

playSoundFile(fileName)

This function plays a sound file. On 2.0, it can play most sound formats and up to 4 sounds simulaneously and an there's no limit on simultaneous sounds since 3.0.

Parameters

• fileName:

Exact path of the sound file.

See also: stopSounds()

Example

<lua> -- play a sound in Windows playSoundFile(C:\My folder\boing.wav)

-- play a sound in Linux playSoundFile(/home/myname/Desktop/boingboing.wav)

-- play a sound from a package playSoundFile(getMudletHomeDir().. /mypackage/boingboing.wav) </lua>

registerAnonymousEventHandler

registerAnonymousEventHandler(event name, function name)

Registers a function to an event handler, not requiring you to set one up via script.

At the moment, it's not possible to use handlers inside namespaces, or unregister them.

Example

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

reloadModule

reloadModule(module name)

Reload a module (by uninstalling and reinstalling).

See also: installModule(), uninstallModule()

Example

<lua> reloadModule("3k-mapper") </lua>

resetProfile

resetProfile()

Reloads your entire Mudlet profile - as if you've just opened it. All UI elements will be cleared, so this useful when you're coding your UI. To use this function, call it and then receive input from the game - that will trigger Mudlet to do the reset.

saveProfile

saveProfile()

Saves the current Mudlet profile to disc, which is equivalent to pressing the "Save Profile" button.

sendSocket

sendSocket(data)

Sends given binary data as-is to the MUD. You can use this to implement support for a new telnet protocol, simultronics login or etcetera.

Example

<lua> TN_IAC = 255 TN_WILL = 251 TN_DO = 253 TN_SB = 250 TN_SE = 240 TN_MSDP = 69

MSDP_VAL = 1 MSDP_VAR = 2

sendSocket( string.char( TN_IAC, TN_DO, TN_MSDP ) ) -- sends IAC DO MSDP

--sends: IAC SB MSDP MSDP_VAR "LIST" MSDP_VAL "COMMANDS" IAC SE local msg = string.char( TN_IAC, TN_SB, TN_MSDP, MSDP_VAR ) .. " LIST " ..string.char( MSDP_VAL ) .. " COMMANDS " .. string.char( TN_IAC, TN_SE ) sendSocket( msg ) </lua>

spawn

spawn(read function, process to spawn)

Spawns a process and opens a communicatable link with it - read function is the function you'd like to use for reading output from the process, and t is a table containing functions specific to this connection - send(data), true/false = isRunning(), and close().

Example

<lua> -- simple example on a program that quits right away, but prints whatever it gets using the 'display' function local f = spawn(display, "ls") display(f.isRunning()) f.close() </lua>

startLogging

startLogging(state)

Control logging of the main console text as text or HTML (as specified by the "Save log files in HTML format instead of plain text" setting on the "General" tab of the "Profile preferences" or "Settings" dialog). Despite being called startLogging it can also stop the process and correctly close the file being created. The file will have an extension of type ".txt" or ".html" as appropriate and the name will be in the form of a date/time "yyyy-MM-dd#hh-mm-ss" using the time/date of when logging started. Note that this control parallels the corresponding icon in the "bottom buttons" for the profile and that button can also start and stop the same logging process and will reflect the state as well.

Parameters

• state:

Required: logging state. Passed as a boolean

Returns (4 values)

• successful (bool)

true if the logging state actually changed; if, for instance, logging was already active and true was supplied then no change in logging state actually occurred and nil will be returned (and logging will continue).

• fileName (string)

The log will be/is being written to the path/file name returned.

• message (string)

A displayable message given one of four messages depending on the current and previous logging states, this will include the file name except for the case when logging was not taking place and the supplied argument was also false.

• code (number)

A value indicating the response to the system to this instruction:

 *  0 = logging has just stopped
 *  1 = logging has just started
 * -1 = logging was already in progress so no change in logging state
 * -2 = logging was already not in progress so no change in logging state

stopSounds

stopSounds()

Stops all currently playing sounds.

Note: Available in Mudlet 3.0.

See also: playSoundFile()

Example

<lua> stopSounds() </lua>

uninstallModule

uninstallModule(name)

Uninstalls a Mudlet module with the given name.

See also: installModule()

Example

<lua> uninstallModule("myalias") </lua>

uninstallPackage

uninstallPackage(name)

Uninstalls a Mudlet package with the given name.

See also: installPackage()

Example

<lua> uninstallPackage("myalias") </lua>

yajl.to_string

yajl.to_string(data)

Encodes a Lua table into JSON data and returns it as a string. This function is very efficient - if you need to encode into JSON, use this.

Example

<lua> -- on IRE MUDs, you can send a GMCP request to request the skills in a particular skillset. Here's an example: sendGMCP("Char.Skills.Get "..yajl.to_string{group = "combat"})

-- you can also use it to convert a Lua table into a string, so you can, for example, store it as room's userdata local toserialize = yajl.to_string(continents) setRoomUserData(1, "areaContinents", toserialize) </lua>

yajl.to_value

yajl.to_value(data)

Decodes JSON data (as a string) into a Lua table. This function is very efficient - if you need to dencode into JSON, use this.

Example

<lua> -- given the serialization example above with yajl.to_string, you can deserialize room userdata back into a table local tmp = getRoomUserData(1, "areaContinents") if tmp == "" then return end

local continents = yajl.to_value(tmp) display(continents) </lua>