View source for Manual:Miscellaneous Functions

{{TOC right}}
= 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 [[Manual:Supported_Protocols#Adding_support_for_a_telnet_protocol|additional protocols]] section for more.

;Example:

<syntaxhighlight lang="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)
</syntaxhighlight>

==alert==
; alert(''seconds'')
: alerts the user to something happening - makes Mudlet flash in the Windows window bar, bounce in the macOS dock, or flash on Linux.

{{note}} Available in Mudlet 3.2+

;Parameters
* ''seconds:''
: (optional) number of seconds to have the alert for. If not provided, Mudlet will flash until the user opens Mudlet again.

;Example:

<syntaxhighlight lang="lua">
-- flash indefinitely until Mudlet is open
alert()

-- flash for just 3 seconds
alert(3)
</syntaxhighlight>

==closeMudlet==
;closeMudlet()

:Closes Mudlet and all profiles immediately.
: See also: [[Manual:Lua_Functions#saveProfile|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. Also it does not consider if there are ''other'' profiles open if multi-playing: they '''all''' will be closed!

{{note}} Available in Mudlet 3.1+

;Example
<syntaxhighlight lang="lua">
closeMudlet()
</syntaxhighlight>

==denyCurrentSend==
;denyCurrentSend()

:Cancels a [[Manual:Lua_Functions#send|send()]] or user-entered command, but only if used within a [[Manual:Event_Engine#sysDataSendRequest|sysDataSendRequest]] event.

;Example
<syntaxhighlight lang="lua">
-- cancels all "eat hambuger" commands
function cancelEatHamburger(event, command)
  if command == "eat hamburger" then
    denyCurrentSend()
    cecho("<red>Denied! Didn't let the command through.\n")
  end
end

registerAnonymousEventHandler("sysDataSendRequest", "cancelEatHamburger")
</syntaxhighlight>

==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
<syntaxhighlight lang="lua">
expandAlias("t rat")

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

{{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:
<syntaxhighlight lang="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")
</syntaxhighlight>

==getModulePath==
;path = getModulePath(module name)

:Returns the location of a module on the disk.
: See also: [[Manual:Lua_Functions#installModule|installModule()]]

{{note}} Available in Mudlet 3.0+

;Example
<syntaxhighlight lang="lua">
getModulePath("mudlet-mapper")
</syntaxhighlight>

==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: [[Manual:Lua_Functions#setModulePriority|setModulePriority()]]

;Example
<syntaxhighlight lang="lua">
getModulePriority("mudlet-mapper")
</syntaxhighlight>

==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
<syntaxhighlight lang="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"
</syntaxhighlight>

==getMudletLuaDefaultPaths==
; getMudletLuaDefaultPaths()
: 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:
<code>
[ ERROR ] - LuaGlobal.lua compile error - please report!
</code>

message in the main console, instead of the expected:

<code>
[  OK  ]  - Mudlet-lua API & Geyser Layout manager loaded.
</code>

{{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. This command was renamed from getMudletLuaDefaultPath().

==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: major version, minor version, revision number and the optional build name.

;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
<syntaxhighlight lang="lua">
-- see the full Mudlet version as text:
getMudletVersion("string")
-- returns for example "3.0.0-alpha"

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

==getProfileName==
;name = getProfileName()

:Returns the name of the profile. Useful when combined with [[Manual:Mudlet_Object_Functions#raiseGlobalEvent|raiseGlobalEvent()]] to know which profile a global event came from.

{{note}} Available in Mudlet 3.1+

;Example
<syntaxhighlight lang="lua">
-- if connected to the Achaea profile, will print Achaea to the main console
echo(getProfileName())
</syntaxhighlight>

==getServerEncoding==
;getServerEncoding()
: Returns the current server [https://www.w3.org/International/questions/qa-what-is-encoding data encoding] in use.

: See also: [[#setServerEncoding|setServerEncoding()]], [[#getServerEncodingsList|getServerEncodingsList()]]

;Example
<syntaxhighlight lang="lua">
getServerEncoding()
</syntaxhighlight>

==getServerEncodingsList==
;getServerEncodingsList()
: Returns an indexed list of the server [https://www.w3.org/International/questions/qa-what-is-encoding data encodings] that Mudlet knows. This is not the list of encodings the servers knows - there's unfortunately no agreed standard for checking that. See [[Manual:Unicode#Changing_encoding|encodings in Mudlet]] for the list of which encodings are available in which Mudlet version.

: See also: [[#setServerEncoding|setServerEncoding()]], [[#getServerEncoding|getServerEncoding()]]

;Example
<syntaxhighlight lang="lua">
-- check if UTF-8 is available:
if table.contains(getServerEncodingsList(), "UTF-8") then
  print("UTF-8 is available!")
end
</syntaxhighlight>

==installModule==
;installModule(location)
: Installs a Mudlet XML or zip as a module.

;Parameters
* ''location:''
: Exact location of the file install.

: See also: [[#uninstallModule | uninstallModule()]]

;Example
<syntaxhighlight lang="lua">
installModule([[C:\Documents and Settings\bub\Desktop\myalias.xml]])
</syntaxhighlight>

==installPackage==
;installPackage(location)
: Installs a Mudlet XML or package.

;Parameters
* ''location:''
: Exact location of the xml or package to install.

: See also: [[#uninstallPackage | uninstallPackage()]]

;Example
<syntaxhighlight lang="lua">
installPackage([[C:\Documents and Settings\bub\Desktop\myalias.xml]])
</syntaxhighlight>

==killAnonymousEventHandler==
;killAnonymousEventHandler(handler id)
: Disables and removes the given event handler.

;Parameters
* ''handler id''
: ID of the event handler to remove as returned by the [[ #registerAnonymousEventHandler | registerAnonymousEventHandler ]] function.

: See also: [[ #registerAnonymousEventHandler | registerAnonymousEventHandler ]]

;Example
<syntaxhighlight lang="lua">
local counter = 0
local handlerId = registerAnonymousEventHandler("gmcp", function(_, origEvent)
  print(origEvent)
  counter = counter + 1
  if counter == 5 then
    killAnonymousEventHandler(handlerId)
  end
end)
</syntaxhighlight>

==loadWindowLayout==
;loadWindowLayout
: Resets the layout of userwindows (floating miniconsoles) to the last saved state.

: See also: [[#saveWindowLayout|saveWindowLayout()]]

{{note}} Available in Mudlet 3.2+

;Example
<syntaxhighlight lang="lua">
loadWindowLayout()
</syntaxhighlight>

==mudletOlderThan==
;mudletOlderThan(major, ''minor'', ''patch'')
: Returns true if Mudlet is older than the given version to check. This is useful if you'd like to use a feature that you can't check for easily, such as coroutines support. However, if you'd like to check if a certain function exists, do not use this and use <code>if mudletfunction then</code> - it'll be much more readable and reliable.

;Parameters
* ''major:''
: Mudlet major version to check. Given a Mudlet version 3.0.1, 3 is the major version, second 0 is the minor version, and third 1 is the patch version.
* ''minor:''
: (optional) minor version to check.
* ''patch:''
: (optional) patch version to check.

;Example
<syntaxhighlight lang="lua">
-- stop doing the script of Mudlet is older than 3.2
if mudletOlderThan(3,2) then return end

-- or older than 2.1.3
if mudletOlderThan(2,3,1) then return end

-- however, if you'd like to check that a certain function is available, like getMousePosition(), do this instead:
if not getMousePosition then return end

-- if you'd like to check that coroutines are supported, do this instead:
if not mudlet.supportscoroutines then return end
</syntaxhighlight>

==openWebPage==
;openWebPage(URL)
: Opens the browser to the given webpage.

;Parameters
* ''URL:''
: Exact URL to open.

;Example
<syntaxhighlight lang="lua">
openWebPage("http://google.com")
</syntaxhighlight>

==playSoundFile==
;playSoundFile(fileName, volume)
: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.
* ''volume:''
:Set the volume (in percent) of the sound. If no volume is given, 100 (maximum) is used.
:Optional, available since 3.0

See also: [[#stopSounds|stopSounds()]]

;Example
<syntaxhighlight lang="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]])

-- play a sound in Linux at half volume
playSoundFile([[/home/myname/Desktop/boingboing.wav]], 50)
</syntaxhighlight>

==registerAnonymousEventHandler==
;id = registerAnonymousEventHandler(event name, function[, one shot])
: Registers a function to an event handler, not requiring you to set one up via script. [[Manual:Event_Engine#Mudlet-raised_events|See here]] for a list of Mudlet-raised events. The function may be either a string containing a global function name or a lua function object.

: The optional <code>one shot</code> parameter allows you to automatically kill an event handler after it is done by giving a true value. If the event you waited for did not occur yet, return <code>true</code> from the function to keep it registered.

: The function returns an ID that can be used in [[Manual:Lua_Functions#killAnonymousEventHandler|killAnonymousEventHandler()]] to unregister the handler again.

{{note}} The ability to register lua functions, the <code>one shot</code> parameter and the returned ID are features of Mudlet 3.5 and above.

;See also
: [[Manual:Lua_Functions#killAnonymousEventHandler|killAnonymousEventHandler()]]

;Example
<syntaxhighlight lang="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")
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- simple inventory tracker for GMCP enabled games. This version does not leak any of the methods
-- or tables into the global namespace. If you want to access it, you should export the inventory
-- table via an own namespace.
local inventory = {}

local function inventoryAdd()
  if gmcp.Char.Items.Add.location == "inv" then
    inventory[#inventory + 1] = table.deepcopy(gmcp.Char.Items.Add.item)
  end
end
registerAnonymousEventHandler("gmcp.Char.Items.Add", inventoryAdd)

local function inventoryList()
  if gmcp.Char.Items.List.location == "inv" then
    inventory = table.deepcopy(gmcp.Char.Items.List.items)
  end
end
registerAnonymousEventHandler("gmcp.Char.Items.List", inventoryList)

local function inventoryUpdate()
  if gmcp.Char.Items.Remove.location == "inv" then
    local found
    local updatedItem = gmcp.Char.Items.Update.item
    for index, item in ipairs(inventory) do
      if item.id == updatedItem.id then
        found = index
        break
      end
    end
    if found then
      inventory[found] = table.deepcopy(updatedItem)
    end
  end
end
registerAnonymousEventHandler("gmcp.Char.Items.Update", inventoryUpdate)

local function inventoryRemove()
  if gmcp.Char.Items.Remove.location == "inv" then
    local found
    local removedItem = gmcp.Char.Items.Remove.item
    for index, item in ipairs(inventory) do
      if item.id == removedItem.id then
        found = index
        break
      end
    end
    if found then
      table.remove(inventory, found)
    end
  end
end
registerAnonymousEventHandler("gmcp.Char.Items.Remove", inventoryRemove)
</syntaxhighlight>

<syntaxhighlight lang="lua">
-- downloads a package from the internet and kills itself after it is installed.
local saveto = getMudletHomeDir().."/dark-theme-mudlet.zip"
local url = "http://www.mudlet.org/wp-content/files/dark-theme-mudlet.zip"

registerAnonymousEventHandler(
  "sysDownloadDone",
  function(_, filename)
    if filename ~= saveto then
      return true -- keep the event handler since this was not our file
    end
    installPackage(saveto)
    os.remove(b)
  end,
  true
)

downloadFile(saveto, url)
cecho("<white>Downloading <green>"..url.."<white> to <green>"..saveto.."\n")
</syntaxhighlight>

==reloadModule==
;reloadModule(module name)
: Reload a module (by uninstalling and reinstalling).

: See also: [[#installModule|installModule()]], [[#uninstallModule|uninstallModule()]]

;Example
<syntaxhighlight lang="lua">
reloadModule("3k-mapper")
</syntaxhighlight>

==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 disk, which is equivalent to pressing the "Save Profile" button.

;Example
<syntaxhighlight lang="lua">
saveProfile()
</syntaxhighlight>

==saveWindowLayout==
;saveWindowLayout
: Saves the layout of userwindows (floating miniconsoles), in case you'd like to load them again later.

: See also: [[#loadWindowLayout|loadWindowLayout()]]

{{note}} Available in Mudlet 3.2+

;Example
<syntaxhighlight lang="lua">
saveWindowLayout()
</syntaxhighlight>

==sendSocket==
;sendSocket(data)

:Sends given binary data as-is to the MUD. You can use this to implement support for a [[Manual:Supported_Protocols#Adding_support_for_a_telnet_protocol|new telnet protocol]], [http://forums.mudlet.org/viewtopic.php?f=5&t=2272 simultronics] [http://forums.mudlet.org/viewtopic.php?f=5&t=2213#p9810 login] or etcetera.

;Example
<syntaxhighlight lang="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 )
</syntaxhighlight>

==setServerEncoding==
;setServerEncoding(encoding)
: Makes Mudlet use the specified [https://www.w3.org/International/questions/qa-what-is-encoding encoding] for communicating with the game.

;Parameters
* ''encoding:''
: Encoding to use.

: See also: [[#getServerEncodingsList|getServerEncodingsList()]], [[#getServerEncoding|getServerEncoding()]]

;Example
<syntaxhighlight lang="lua">
-- use UTF-8 if Mudlet knows it. Unfortunately there's no way to check if the game's server knows it too.
if table.contains(getServerEncodingsList(), "UTF-8") then
  setServerEncoding("UTF-8")
end
</syntaxhighlight>

==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
<syntaxhighlight lang="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()
</syntaxhighlight>

==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|playSoundFile()]]

;Example
<syntaxhighlight lang="lua">
stopSounds()
</syntaxhighlight>

==uninstallModule==
;uninstallModule(name)

: Uninstalls a Mudlet module with the given name.

: See also: [[#installModule | installModule()]]

;Example
<syntaxhighlight lang="lua">
uninstallModule("myalias")
</syntaxhighlight>

==uninstallPackage==
;uninstallPackage(name)

: Uninstalls a Mudlet package with the given name.

: See also: [[#installPackage | installPackage()]]

;Example
<syntaxhighlight lang="lua">
uninstallPackage("myalias")
</syntaxhighlight>

==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
<syntaxhighlight lang="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)
</syntaxhighlight>


==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
<syntaxhighlight lang="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)
</syntaxhighlight>

[[Category:Mudlet Manual]]
[[Category:Mudlet API]]