Difference between revisions of "Manual:Miscellaneous Functions"

From Mudlet
Jump to navigation Jump to search
(add stopSounds)
 
(34 intermediate revisions by 8 users not shown)
Line 127: Line 127:
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
local deleted = deletedNamedEventHandler("Demonnic", "Vitals")
+
local deleted = deleteNamedEventHandler("Demonnic", "Vitals")
 
if deleted then
 
if deleted then
 
   cecho("Vitals deleted forever!!")
 
   cecho("Vitals deleted forever!!")
Line 244: Line 244:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==getModulePath==
+
==getCharacterName==
;path = getModulePath(module name)
+
;getCharacterName()
 +
 
 +
:Returns the name entered into the "Character name" field on the Connection Preferences form. Can be used to find out the name that might need to be handled specially in scripts or anything that needs to be personalized to the player. If there is nothing set in that entry will return an empty string.
  
:Returns the location of a module on the disk. If the given name does not correspond to an installed module, it'll return <code>nil</code>
+
:See also: [[#getProfileName|getProfileName()]]
:See also: [[Manual:Lua_Functions#installModule|installModule()]]
 
  
{{MudletVersion|3.0}}
+
{{MudletVersion|4.16}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
getModulePath("mudlet-mapper")
+
-- cast glamor on yourself
</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.
 
:Modules with priority <code>-1</code> will be loaded before scripts (Mudlet 4.11+).
 
 
 
:See also: [[Manual:Lua_Functions#setModulePriority|setModulePriority()]]
 
  
;Example
+
send("cast 'glamor' " .. getCharacterName())
<syntaxhighlight lang="lua">
 
getModulePriority("mudlet-mapper")
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==getModules==
+
==getConfig ==
;getModules()
+
;getConfig([option])
  
:Returns installed modules as table.
+
: Returns configuration options similar to those that can be set with setConfig. One could use this to decide if a script should notify the user of suggested changes.
 +
See also: [[Manual:Miscellaneous_Functions#setConfig|setConfig()]]
  
:See also: [[#getPackages|getPackages]]
+
{{MudletVersion|4.17}}
  
{{MudletVersion|4.12}}
+
;Parameters
 +
*''option:''
 +
:Particular option to retrieve - see list below for available ones. This may be a string or an array of strings.
  
;Example
+
{| class="wikitable sortable"
<syntaxhighlight lang="lua">
+
|+General options
--Check if the module myTabChat is installed and if it isn't install it and enable sync on it
+
|-
if not table.contains(getModules(),"myTabChat") then
+
!Option!!Description!!Available in Mudlet
  installModule(getMudletHomeDir().."/modules/myTabChat.xml")
+
|-
  enableModuleSync("myTabChat")
+
|enableGMCP||Enable GMCP||4.17
end
+
|-
 +
|enableMSDP||Enable MSDP||4.17
 +
|-
 +
|enableMSSP||Enable MSSP||4.17
 +
|-
 +
|enableMSP|| Enable MSP||4.17
 +
|}
  
</syntaxhighlight>
+
{| class="wikitable sortable"
 +
|+Input line
 +
|-
 +
!Option!!Description!!Available in Mudlet
 +
|-
 +
|inputLineStrictUnixEndings||Workaround option to use strict UNIX line endings for sending commands||4.17
 +
|-
 +
|}
  
==getModuleInfo==
+
{| class="wikitable sortable"
;getModuleInfo(moduleName, [info])
+
|+Main display
 +
|-
 +
!Option!!Description!!Available in Mudlet
 +
|-
 +
|fixUnnecessaryLinebreaks||Remove extra linebreaks from output (mostly for IRE servers) || 4.17
 +
|-
 +
|}
  
:Returns table with meta information for a package
+
{| class="wikitable sortable"
 +
|+Mapper options
 +
|-
 +
!Option!!Description!!Available in Mudlet
 +
|-
 +
|mapRoomSize||Size of rooms on map||4.17
 +
|-
 +
|mapExitSize||Size of exits on map||4.17
 +
|-
 +
|mapRoundRooms||Draw rooms round or square||4.17
 +
|-
 +
|showRoomIdsOnMap||Show room IDs on all rooms||4.17
 +
|-
 +
|show3dMapView||Show map as 3D||4.17
 +
|-
 +
|mapperPanelVisible||Map controls at the bottom||4.17
 +
|-
 +
|mapShowRoomBorders|| Draw a thin border for every room||4.17
 +
|}
  
;Parameters
+
{| class="wikitable sortable"
* ''moduleName:''
+
|+Special options
:Name of the package
+
|-
* ''info:''
+
!Option!!Description!!Available in Mudlet
:(optional) specific info wanted to get, if not given all available meta-info is returned
+
|-
 +
|specialForceCompressionOff|| Workaround option to disable MCCP compression, in case the game server is not working correctly||4.17
 +
|-
 +
|specialForceGAOff||Workaround option to disable Telnet Go-Ahead, in case the game server is not working correctly||4.17
 +
|-
 +
|specialForceCharsetNegotiationOff||Workaround option to disable automatically setting the correct encoding, in case the game server is not working correctly||4.17
 +
|-
 +
|specialForceMxpNegotiationOff|| Workaround option to disable MXP, in case the game server is not working correctly ||4.17
 +
|-
 +
|caretShortcut||For visually-impaired players - get the key to switch between input line and main window (can be "none", "tab", "ctrltab", "f6")|| 4.17
 +
|-
 +
|blankLinesBehaviour||For visually impaired players options for dealing with blank lines (can be "show", "hide", "replacewithspace")||4.17
 +
|}
  
:See also: [[#getPackageInfo|getPackageInfo]], [[#setModuleInfo|getModuleInfo]]
+
;Returns
 +
*It returns a table of options or the value of a single option requested. They are only the configuration options, for example "enableGMCP" means that the "Enable GMCP" box is checked and does not mean that it has been negotiated with the server.
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
getModuleInfo("myModule","author")
+
getConfig()
 +
 
 +
-- Suggest enabling GMCP if it is unchecked
 +
if not getConfig("enableGMCP") then
 +
  echo("\nMy script works best with GMCP enabled. You may ")
 +
  cechoLink("<red>click here", function() setConfig("enableGMCP",true) echo("GMCP enabled\n") end, "Enable GMCP", true)
 +
  echo(" to enable it.\n")
 +
end
 
</syntaxhighlight>
 
</syntaxhighlight>
  
{{MudletVersion|4.12}}
+
==getModulePath==
 +
;path = getModulePath(module name)
  
==getModuleSync==
+
:Returns the location of a module on the disk. If the given name does not correspond to an installed module, it'll return <code>nil</code>
;getModuleSync(name)
+
:See also: [[Manual:Lua_Functions#installModule|installModule()]]
: returns false if module sync is not active, true if it is active and nil if module is not found.
 
  
;Parameter
+
{{MudletVersion|3.0}}
* ''name'': name of the module
 
  
:See also: [[Manual:Lua_Functions#enableModuleSync|enableModuleSync()]], [[Manual:Lua_Functions#disableModuleSync|disableModuleSync()]]
+
;Example
{{MudletVersion|4.8}}
+
<syntaxhighlight lang="lua">
 +
getModulePath("mudlet-mapper")
 +
</syntaxhighlight>
 +
 
 +
==getModulePriority==
 +
;priority = getModulePriority(module name)
  
==getMudletHomeDir==
+
: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.
;getMudletHomeDir()
+
:Modules with priority <code>-1</code> will be loaded before scripts (Mudlet 4.11+).
: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.
 
  
{{note}} intentionally uses forward slashes <code>/</code> as separators on Windows since [[Manual:UI_Functions#setLabelStyleSheet|stylesheets]] require them.
+
:See also: [[Manual:Lua_Functions#setModulePriority|setModulePriority()]]
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
-- save a table
+
getModulePriority("mudlet-mapper")
table.save(getMudletHomeDir().."/myinfo.dat", myinfo)
+
</syntaxhighlight>
  
-- or access package data. The forward slash works even on Windows fine
+
==getModules==
local path = getMudletHomeDir().."/mypackagename"
+
;getModules()
</syntaxhighlight>
 
  
==getMudletInfo==
+
:Returns installed modules as table.
;getMudletInfo()
 
:Prints debugging information about the Mudlet that you're running - this can come in handy for diagnostics.
 
  
Don't use this command in your scripts to find out if certain features are supported in Mudlet - there are better functions available for this.
+
:See also: [[#getPackages|getPackages]]
  
{{MudletVersion|4.8}}
+
{{MudletVersion|4.12}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
getMudletInfo()
+
--Check if the module myTabChat is installed and if it isn't install it and enable sync on it
 +
if not table.contains(getModules(),"myTabChat") then
 +
  installModule(getMudletHomeDir().."/modules/myTabChat.xml")
 +
  enableModuleSync("myTabChat")
 +
end
 +
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==getMudletVersion==
+
==getModuleInfo==
;getMudletVersion(style)
+
;getModuleInfo(moduleName, [info])
: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 existence of the function itself. Otherwise, checking for the version can come in handy if you'd like to test for a broken function or so on.
 
  
See also: [[#mudletOlderThan|mudletOlderThan()]]
+
:Returns table with meta information for a package
  
{{MudletVersion|3.0}}
+
;Parameters
 +
* ''moduleName:''
 +
:Name of the package
 +
* ''info:''
 +
:(optional) specific info wanted to get, if not given all available meta-info is returned
  
;Parameters
+
:See also: [[#getPackageInfo|getPackageInfo]], [[#setModuleInfo|setModuleInfo]]
* ''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
+
;Example
* ''"string"'':
+
<syntaxhighlight lang="lua">
:Returns the full Mudlet version as text.
+
getModuleInfo("myModule","author")
* ''"table"'':
+
</syntaxhighlight>
:Returns the full Mudlet version as four values (multi-return)
+
 
* ''"major"'':
+
{{MudletVersion|4.12}}
: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
+
==getModuleSync==
<syntaxhighlight lang="lua">
+
;getModuleSync(name)
-- see the full Mudlet version as text:
+
: returns false if module sync is not active, true if it is active and nil if module is not found.
getMudletVersion("string")
 
-- returns for example "3.0.0-alpha"
 
  
-- check that the major Mudlet version is at least 3:
+
;Parameter
if getMudletVersion("major") >= 3 then echo("You're running on Mudlet 3+!") end
+
* ''name'': name of the module
-- but mudletOlderThan() is much better for this:
 
if mudletOlderThan(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:
+
:See also: [[Manual:Lua_Functions#enableModuleSync|enableModuleSync()]], [[Manual:Lua_Functions#disableModuleSync|disableModuleSync()]]
if setAppStyleSheet then
+
{{MudletVersion|4.8}}
  -- example credit to http://qt-project.org/doc/qt-4.8/stylesheet-examples.html#customizing-qscrollbar
+
 
  setAppStyleSheet[[
+
==getMudletHomeDir==
  QScrollBar:vertical {
+
;getMudletHomeDir()
      border: 2px solid grey;
+
: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.
      background: #32CC99;
+
 
      width: 15px;
+
{{note}} intentionally uses forward slashes <code>/</code> as separators on Windows since [[Manual:UI_Functions#setLabelStyleSheet|stylesheets]] require them.
      margin: 22px 0 22px 0;
+
 
  }
+
;Example
  QScrollBar::handle:vertical {
+
<syntaxhighlight lang="lua">
      background: white;
+
-- save a table
      min-height: 20px;
+
table.save(getMudletHomeDir().."/myinfo.dat", myinfo)
  }
+
 
  QScrollBar::add-line:vertical {
+
-- or access package data. The forward slash works even on Windows fine
      border: 2px solid grey;
+
local path = getMudletHomeDir().."/mypackagename"
      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>
 
</syntaxhighlight>
  
==getNewIDManager==
+
==getMudletInfo==
; getNewIDManager()
+
;getMudletInfo()
 +
:Prints debugging information about the Mudlet that you're running - this can come in handy for diagnostics.
  
:Returns an IDManager object, for manager your own set of named events and timers isolated from the rest of the profile.
+
Don't use this command in your scripts to find out if certain features are supported in Mudlet - there are better functions available for this.
  
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]]
+
{{MudletVersion|4.8}}
 
 
{{MudletVersion|4.14}}
 
 
 
{{note}} Full IDManager usage can be found at [[Manual:IDManager|IDManager]]
 
 
 
;Returns
 
* an IDManager for managing your own named events and timers
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
demonnic = demonnic or {}
+
getMudletInfo()
demonnic.IDManager = getNewIDManager()
 
local idm = demonnic.IDManager
 
-- assumes you have defined demonnic.vitalsUpdate and demonnic.balanceChecker as functions
 
idm:registerEvent("DemonVitals", "gmcp.Char.Vitals", demonnic.vitalsUpdate)
 
idm:registerTimer("Balance Check", 1, demonnic.balanceChecker)
 
idm:stopEvent("DemonVitals")
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==getNamedEventHandlers==
+
==getMudletVersion==
; handlers = getNamedEventHandlers(userName)
+
;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 existence of the function itself. Otherwise, checking for the version can come in handy if you'd like to test for a broken function or so on.
  
:Returns a list of all userName's named event handlers' names as a table.
+
See also: [[#mudletOlderThan|mudletOlderThan()]]
  
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]]
+
{{MudletVersion|3.0}}
 
 
{{MudletVersion|4.14}}
 
  
 
;Parameters
 
;Parameters
* ''userName:''
+
* ''style:''
: The user name the event handler was registered under.
+
:(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.
  
;Returns  
+
;Values you can choose
* a table of handler names. { "DemonVitals", "DemonInv" } for example. {} if none are registered
+
* ''"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
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
  local handlers = getNamedEventHandlers()
+
-- see the full Mudlet version as text:
  display(handlers)
+
getMudletVersion("string")
  -- {}
+
-- returns for example "3.0.0-alpha"
  registerNamedEventHandler("Test1", "testEvent", "testFunction")
 
  registerNamedEventHandler("Test2", "someOtherEvent", myHandlerFunction)
 
  handlers = getNamedEventHandlers()
 
  display(handlers)
 
  -- { "Test1", "Test2" }
 
</syntaxhighlight>
 
  
==getOS==
+
-- check that the major Mudlet version is at least 3:
;getOS()
+
if getMudletVersion("major") >= 3 then echo("You're running on Mudlet 3+!") end
 +
-- but mudletOlderThan() is much better for this:
 +
if mudletOlderThan(3) then echo("You're running on Mudlet 3+!") end
  
:Returns the name of the Operating System (OS). Useful for applying particular scripts only under particular operating systems, such as applying a stylesheet only when the OS is Windows.  
+
-- if you'd like to see if a function is available however, test for it explicitly instead:
:Returned text will be one of these: "cygwin", "windows", "mac", "linux", "hurd", "freebsd", "kfreebsd", "openbsd", "netbsd", "bsd4", "unix" or "unknown" otherwise.
+
if setAppStyleSheet then
:Additionally returns the version of the OS, and if using Linux, the distribution in use (as of Mudlet 4.12+).
+
  -- example credit to http://qt-project.org/doc/qt-4.8/stylesheet-examples.html#customizing-qscrollbar
 
+
  setAppStyleSheet[[
;Example
+
  QScrollBar:vertical {
<syntaxhighlight lang="lua">
+
      border: 2px solid grey;
display(getOS())
+
      background: #32CC99;
 
+
      width: 15px;
if getOS() == "windows" then
+
      margin: 22px 0 22px 0;
   echo("\nWindows OS detected.\n")
+
  }
else
+
  QScrollBar::handle:vertical {
   echo("\nDetected Operating system is NOT windows.\n")
+
      background: white;
end
+
      min-height: 20px;
 
+
  }
if mudlet.supports.osVersion then
+
   QScrollBar::add-line:vertical {
   local os, osversion = getOS()
+
      border: 2px solid grey;
   print(f"Running {os} {osversion}")
+
      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
 
end
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==getPackages==
+
==getNewIDManager==
;getPackages()
+
; getNewIDManager()
 +
 
 +
:Returns an IDManager object, for manager your own set of named events and timers isolated from the rest of the profile.
 +
 
 +
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]]
  
:Returns installed packages as table.
+
{{MudletVersion|4.14}}
  
:See also: [[#getModules|getModules]]
+
{{note}} Full IDManager usage can be found at [[Manual:IDManager|IDManager]]
  
{{MudletVersion|4.12}}
+
;Returns
 +
* an IDManager for managing your own named events and timers
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
--Check if the generic_mapper package is installed and if so uninstall it
+
demonnic = demonnic or {}
if table.contains(getPackages(),"generic_mapper") then
+
demonnic.IDManager = getNewIDManager()
  uninstallPackage("generic_mapper")
+
local idm = demonnic.IDManager
end
+
-- assumes you have defined demonnic.vitalsUpdate and demonnic.balanceChecker as functions
 
+
idm:registerEvent("DemonVitals", "gmcp.Char.Vitals", demonnic.vitalsUpdate)
 +
idm:registerTimer("Balance Check", 1, demonnic.balanceChecker)
 +
idm:stopEvent("DemonVitals")
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==getPackageInfo==
+
==getNamedEventHandlers==
;getPackageInfo(packageName, [info])
+
; handlers = getNamedEventHandlers(userName)
  
:Returns table with meta information for a package
+
:Returns a list of all userName's named event handlers' names as a table.
 +
 
 +
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]]
 +
 
 +
{{MudletVersion|4.14}}
  
 
;Parameters
 
;Parameters
* ''packageName:''
+
* ''userName:''
:Name of the package
+
: The user name the event handler was registered under.
* ''info:''
 
:(optional) specific info wanted to get, if not given all available meta-info is returned
 
  
:See also: [[#getModuleInfo|getModuleInfo]], [[#setPackageInfo|getPackageInfo]]
+
;Returns
 +
* a table of handler names. { "DemonVitals", "DemonInv" } for example. {} if none are registered
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
getPackageInfo("myPackage", "version")
+
  local handlers = getNamedEventHandlers()
 +
  display(handlers)
 +
  -- {}
 +
  registerNamedEventHandler("Test1", "testEvent", "testFunction")
 +
  registerNamedEventHandler("Test2", "someOtherEvent", myHandlerFunction)
 +
  handlers = getNamedEventHandlers()
 +
  display(handlers)
 +
  -- { "Test1", "Test2" }
 
</syntaxhighlight>
 
</syntaxhighlight>
  
{{MudletVersion|4.12}}
+
==getOS==
 +
;getOS()
  
==getProfileName==
+
:Returns the name of the Operating System (OS). Useful for applying particular scripts only under particular operating systems, such as applying a stylesheet only when the OS is Windows.
;getProfileName()
+
:Returned text will be one of these: "windows", "mac", "linux", as well as "cygwin", "hurd", "freebsd", "kfreebsd", "openbsd", "netbsd", "bsd4", "unix" or "unknown" otherwise.
 +
:Additionally returns the version of the OS, and if using Linux, the distribution in use (as of Mudlet 4.12+).
  
: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.
+
;Example
 +
<syntaxhighlight lang="lua">
 +
display(getOS())
  
{{MudletVersion|3.1}}
+
if getOS() == "windows" then
 +
  echo("\nWindows OS detected.\n")
 +
else
 +
  echo("\nDetected Operating system is NOT windows.\n")
 +
end
  
;Example
+
if mudlet.supports.osVersion then
<syntaxhighlight lang="lua">
+
  local os, osversion = getOS()
-- if connected to the Achaea profile, will print Achaea to the main console
+
  print(f"Running {os} {osversion}")
echo(getProfileName())
+
end
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==getCommandSeparator==
+
==getPackages==
;getCommandSeparator()
+
;getPackages()
 +
 
 +
:Returns installed packages as table.
  
:Returns the command separator in use by the profile.
+
:See also: [[#getModules|getModules]]
  
{{MudletVersion|3.18}}
+
{{MudletVersion|4.12}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
-- if your command separator is ;;, the following would send("do thing 1;;do thing 2").
+
--Check if the generic_mapper package is installed and if so uninstall it
-- This way you can determine what it is set to and use that and share this script with
+
if table.contains(getPackages(),"generic_mapper") then
-- someone who has changed their command separator.
+
  uninstallPackage("generic_mapper")
-- Note: This is not really the preferred way to send this, using sendAll("do thing 1", "do thing 2") is,
+
end
--      but this illustates the use case.
+
 
local s = getCommandSeparator()
 
expandAlias("do thing 1" .. s .. "do thing 2")
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==getServerEncoding==
+
==getPackageInfo==
;getServerEncoding()
+
;getPackageInfo(packageName, [info])
:Returns the current server [https://www.w3.org/International/questions/qa-what-is-encoding data encoding] in use.
+
 
 +
:Returns table with meta information for a package
 +
 
 +
;Parameters
 +
* ''packageName:''
 +
:Name of the package
 +
* ''info:''
 +
:(optional) specific information to retrieve which can be one of; <code>author</code>, <code>created</code>, <code>description</code>, <code>icon</code>, <code>mpackage</code> (package name), <code>title</code> or <code>version</code>. If not given all available meta-info is returned.
  
:See also: [[#setServerEncoding|setServerEncoding()]], [[#getServerEncodingsList|getServerEncodingsList()]]
+
:See also: [[#getModuleInfo|getModuleInfo]], [[#setPackageInfo|setPackageInfo]]
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
getServerEncoding()
+
getPackageInfo("myPackage", "version")
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==getServerEncodingsList==
+
{{MudletVersion|4.12}}
;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()]]
+
==getPlayingMusic==
 +
;getPlayingMusic(settings table)
 +
:List all playing music (no filter), or playing music that meets a combination of filters (name, key, and tag) intended to be paired with [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]].
  
;Example
+
{| class="wikitable"
<syntaxhighlight lang="lua">
+
! Required
-- check if UTF-8 is available:
+
! Key
if table.contains(getServerEncodingsList(), "UTF-8") then
+
! Value
  print("UTF-8 is available!")
+
!Default
end
+
! style="text-align:left;"| Purpose
</syntaxhighlight>
+
|-
 
+
| style="text-align:center;"| No
==getWindowsCodepage==
+
| name
;getWindowsCodepage()
+
| <file name>
:Returns the current [https://docs.microsoft.com/en-us/windows/desktop/Intl/code-page-identifiers codepage] of your Windows system.
+
|
 
+
| style="text-align:left;"|
{{MudletVersion|3.22}}
+
* Name of the media file.
{{Note}} This function only works on Windows - It is only needed internally in Mudlet to enable Lua to work with non-ASCII usernames (e.g. Iksiński, Jäger) for the purposes of IO. Linux and macOS work fine with with these out of the box.
+
|-
 
+
| style="text-align:center;" |No
;Example
+
| key
<syntaxhighlight lang="lua">
+
|<key>
print(getWindowsCodepage())
+
|
</syntaxhighlight>
+
| style="text-align:left;" |
 +
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".
 +
|-
 +
| style="text-align:center;"| No
 +
| tag
 +
| <tag>
 +
|
 +
| style="text-align:left;"|
 +
* Helps categorize media.
 +
|-
 +
|}
  
==hfeedTriggers==
+
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]],  [[Manual:Miscellaneous_Functions#getPlayingSounds|getPlayingSounds()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]
;hfeedTriggers(str)
 
:Like feedTriggers, but you can add color information using #RRGGBB in hex, similar to hecho.
 
  
;Parameters
+
{{MudletVersion|4.18}}
* ''str'': The string to feed to the trigger engine. Include color information in the same manner as hecho.
 
:See also: [[Manual:Lua_Functions#dfeedTriggers|dfeedTriggers]]
 
:See also: [[Manual:Lua_Functions#hecho|hecho]]
 
  
{{MudletVersion|4.11}}
+
;Example
  
;Example
 
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
hfeedTriggers("#008000,800000green on red#r reset\n")
+
---- Table Parameter Syntax ----
</syntaxhighlight>
 
  
==installModule==
+
-- List all playing music files for this profile associated with the API
;installModule(location)
+
getPlayingMusic()
:Installs a Mudlet XML, zip, or mpackage as a module.
 
  
;Parameters
+
-- List all playing music matching the rugby mp3 name
* ''location:''
+
getPlayingMusic({name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"})
:Exact location of the file install.
 
  
:See also: [[#uninstallModule | uninstallModule()]], [[Manual:Event_Engine#sysLuaInstallModule | Event: sysLuaInstallModule]], [[#setModulePriority | setModulePriority()]]
+
-- List all playing music matching the unique key of "rugby"
 +
getPlayingMusic({
 +
    name = nil  -- nil lines are optional, no need to use
 +
    , key = "rugby" -- key
 +
    , tag = nil  -- nil lines are optional, no need to use
 +
})
 +
</syntaxhighlight>
 +
<syntaxhighlight lang="lua">
 +
---- Ordered Parameter Syntax of getPlayingMusic([name][,key][,tag]) ----
  
;Example
+
-- List all playing music files for this profile associated with the API
<syntaxhighlight lang="lua">
+
getPlayingMusic()
installModule([[C:\Documents and Settings\bub\Desktop\myalias.xml]])
 
</syntaxhighlight>
 
  
==installPackage==
+
-- List all playing music matching the rugby mp3 name
;installPackage(location or url)
+
getPlayingMusic("167124__patricia-mcmillen__rugby-club-in-spain.mp3")
:Installs a Mudlet XML or package. Since Mudlet 4.11+ returns <code>true</code> if it worked, or <code>false</code>.
 
  
;Parameters
+
-- List all playing music matching the unique key of "rugby"
* ''location:''
+
getPlayingMusic(
:Exact location of the xml or package to install.
+
    nil -- name
Since Mudlet 4.11+ it is possible to pass download link to a package (must start with <code>http</code> or <code>https</code> and end with <code>.xml</code>, <code>.zip</code>, <code>.mpackage</code> or <code>.trigger</code>)
+
    , "rugby" -- key
 +
    , nil -- tag
 +
)
 +
</syntaxhighlight>
  
:See also: [[#uninstallPackage | uninstallPackage()]]
+
==getPlayingSounds==
 +
;getPlayingSounds(settings table)
 +
:List all playing sounds (no filter), or playing sounds that meets a combination of filters (name, key, tag, and priority) intended to be paired with [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]].
  
;Example
+
{| class="wikitable"
<syntaxhighlight lang="lua">
+
! Required
installPackage([[C:\Documents and Settings\bub\Desktop\myalias.xml]])
+
! Key
</syntaxhighlight>
+
! Value
 
+
!Default
<syntaxhighlight lang="lua">
+
! style="text-align:left;"| Purpose
installPackage([[https://github.com/Mudlet/Mudlet/blob/development/src/run-lua-code-v4.xml]])
+
|-
</syntaxhighlight>
+
| style="text-align:center;"| No
 
+
| name
==killAnonymousEventHandler==
+
| <file name>
;killAnonymousEventHandler(handler id)
+
|
:Disables and removes the given event handler.
+
| style="text-align:left;"|
 
+
* Name of the media file.
;Parameters
+
|-
* ''handler id''
+
| style="text-align:center;" |No
:ID of the event handler to remove as returned by the [[ #registerAnonymousEventHandler | registerAnonymousEventHandler ]] function.
+
| key
 +
|<key>
 +
|
 +
| style="text-align:left;" |
 +
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".
 +
|-
 +
| style="text-align:center;"| No
 +
| tag
 +
| <tag>
 +
|
 +
| style="text-align:left;"|
 +
* Helps categorize media.
 +
|-
 +
| style="text-align:center;"| No
 +
| priority
 +
| <priority>
 +
|
 +
| style="text-align:left;"|
 +
* Matches media files with equal or lower priority.
 +
|-
 +
|}
 +
 
 +
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]],  [[Manual:Miscellaneous_Functions#getPlayingMusic|getPlayingMusic()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]
  
:See also: [[ #registerAnonymousEventHandler | registerAnonymousEventHandler ]]
+
{{MudletVersion|4.18}}
  
{{MudletVersion|3.5}}
 
 
;Example
 
;Example
 +
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
-- registers an event handler that prints the first 5 GMCP events and then terminates itself
+
---- Table Parameter Syntax ----
 +
 
 +
-- List all playing sounds for this profile associated with the API
 +
getPlayingSounds()
 +
 
 +
-- List all playing sounds matching the rugby mp3 name
 +
getPlayingSounds({name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"})
  
local counter = 0
+
-- List the playing sound matching the unique key of "rugby"
local handlerId = registerAnonymousEventHandler("gmcp", function(_, origEvent)
+
getPlayingSounds({
  print(origEvent)
+
    name = nil  -- nil lines are optional, no need to use
  counter = counter + 1
+
    , key = "rugby" -- key
  if counter == 5 then
+
     , tag = nil  -- nil lines are optional, no need to use
     killAnonymousEventHandler(handlerId)
+
})
  end
 
end)
 
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
<syntaxhighlight lang="lua">
 +
---- Ordered Parameter Syntax of getPlayingSounds([name][,key][,tag][,priority]) ----
 +
 +
-- List all playing sounds for this profile associated with the API
 +
getPlayingSounds()
  
==loadMusicFile==
+
-- List all playing sounds matching the rugby mp3 name
;loadMusicFile(settings table)
+
getPlayingSounds("167124__patricia-mcmillen__rugby-club-in-spain.mp3")
:Loads music files from the Internet or the local file system to the "media" folder of the profile for later use with [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]] and [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]]. Although files could be loaded directly at playing time from [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], loadMusicFile() provides the advantage of loading files in advance.
+
 
 +
-- List the playing sound matching the unique key of "rugby"
 +
getPlayingSounds(
 +
    nil -- name
 +
    , "rugby" -- key
 +
    , nil -- tag
 +
    , nil -- priority
 +
)
 +
</syntaxhighlight>
  
{| class="wikitable"
+
==getProfileName==
! Required
+
;getProfileName()
! Key
 
! Value
 
! style="text-align:left;"| Purpose
 
|- style="color: green;"
 
| style="text-align:center;"| Yes
 
| name
 
| <file name>
 
| style="text-align:left;"|
 
* Name of the media file.
 
* May contain directory information (i.e. weather/lightning.wav).
 
* May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")
 
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")
 
|- style="color: blue;"
 
| style="text-align:center;"| Maybe
 
| url
 
| <url>
 
| style="text-align:left;"|
 
* Resource location where the media file may be downloaded.
 
* Only required if file to load is not part of the profile or on the local file system.
 
|-
 
|}
 
  
See also: [[Manual:Miscellaneous_Functions#playMusicFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]
+
: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.
  
{{MudletVersion|4.15}}
+
{{MudletVersion|3.1}}
  
 
;Example
 
;Example
 
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
---- Table Parameter Syntax ----
+
-- if connected to the Achaea profile, will print Achaea to the main console
 +
echo(getProfileName())
 +
</syntaxhighlight>
  
-- Download from the Internet
+
==getCommandSeparator==
loadMusicFile({
+
;getCommandSeparator()
    name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"
 
    , url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"
 
})
 
  
-- OR download from the profile
+
:Returns the command separator in use by the profile.
loadMusicFile({name = getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3"})
+
 
 +
{{MudletVersion|3.18}}
  
-- OR download from the local file system
+
;Example
loadMusicFile({name = "C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3"})
+
<syntaxhighlight lang="lua">
 +
-- if your command separator is ;;, the following would send("do thing 1;;do thing 2").
 +
-- This way you can determine what it is set to and use that and share this script with
 +
-- someone who has changed their command separator.
 +
-- Note: This is not really the preferred way to send this, using sendAll("do thing 1", "do thing 2") is,
 +
--      but this illustates the use case.
 +
local s = getCommandSeparator()
 +
expandAlias("do thing 1" .. s .. "do thing 2")
 
</syntaxhighlight>
 
</syntaxhighlight>
<syntaxhighlight lang="lua">
 
---- Ordered Parameter Syntax of loadMediaFile(name[, url]) ----
 
  
-- Download from the Internet
+
==getServerEncoding==
loadMusicFile(
+
;getServerEncoding()
    "167124__patricia-mcmillen__rugby-club-in-spain.mp3"
+
:Returns the current server [https://www.w3.org/International/questions/qa-what-is-encoding data encoding] in use.
    , "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"
 
)
 
  
-- OR download from the profile
+
:See also: [[#setServerEncoding|setServerEncoding()]], [[#getServerEncodingsList|getServerEncodingsList()]]
loadMusicFile(getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3")
 
  
-- OR download from the local file system
+
;Example
loadMusicFile("C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3")
+
<syntaxhighlight lang="lua">
 +
getServerEncoding()
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==loadSoundFile==
+
==getServerEncodingsList==
;loadSoundFile(settings table)
+
;getServerEncodingsList()
:Loads sound files from the Internet or the local file system to the "media" folder of the profile for later use with [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]] and [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]]. Although files could be loaded directly at playing time from [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], loadSoundFile() provides the advantage of loading files in advance. 
+
: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>
  
{| class="wikitable"
+
==getWindowsCodepage==
! Required
+
;getWindowsCodepage()
! Key
+
:Returns the current [https://docs.microsoft.com/en-us/windows/desktop/Intl/code-page-identifiers codepage] of your Windows system.
! Value
 
! style="text-align:left;"| Purpose
 
|- style="color: green;"
 
| style="text-align:center;"| Yes
 
| name
 
| <file name>
 
| style="text-align:left;"|
 
* Name of the media file.
 
* May contain directory information (i.e. weather/lightning.wav).
 
* May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")
 
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")
 
|- style="color: blue;"
 
| style="text-align:center;"| Maybe
 
| url
 
| <url>
 
| style="text-align:left;"|
 
* Resource location where the media file may be downloaded.
 
* Only required if file to load is not part of the profile or on the local file system.
 
|-
 
|}
 
  
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]
+
{{MudletVersion|3.22}}
 
+
{{Note}} This function only works on Windows - It is only needed internally in Mudlet to enable Lua to work with non-ASCII usernames (e.g. Iksiński, Jäger) for the purposes of IO. Linux and macOS work fine with with these out of the box.
{{MudletVersion|4.15}}
 
  
 
;Example
 
;Example
 +
<syntaxhighlight lang="lua">
 +
print(getWindowsCodepage())
 +
</syntaxhighlight>
  
<syntaxhighlight lang="lua">
+
==hfeedTriggers==
---- Table Parameter Syntax ----
+
;hfeedTriggers(str)
 +
:Like feedTriggers, but you can add color information using #RRGGBB in hex, similar to hecho.
  
-- Download from the Internet
+
;Parameters
loadSoundFile({
+
* ''str'': The string to feed to the trigger engine. Include color information in the same manner as hecho.
    name = "cow.wav"
+
:See also: [[Manual:Lua_Functions#dfeedTriggers|dfeedTriggers]]
    , url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"
+
:See also: [[Manual:Lua_Functions#hecho|hecho]]
})
 
  
-- OR download from the profile
+
{{MudletVersion|4.11}}
loadSoundFile({name = getMudletHomeDir().. "/cow.wav"})
 
  
-- OR download from the local file system
+
;Example
loadSoundFile({name = "C:/Users/Tamarindo/Documents/cow.wav"})
+
<syntaxhighlight lang="lua">
 +
hfeedTriggers("#008000,800000green on red#r reset\n")
 
</syntaxhighlight>
 
</syntaxhighlight>
<syntaxhighlight lang="lua">
 
---- Ordered Parameter Syntax of loadSoundFile(name[,url]) ----
 
  
-- Download from the Internet
 
loadSoundFile("cow.wav", "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/")
 
  
-- OR download from the profile
 
loadSoundFile(getMudletHomeDir().. "/cow.wav")
 
  
-- OR download from the local file system
+
==holdingModifiers==
loadSoundFile("C:/Users/Tamarindo/Documents/cow.wav")
+
;holdingModifiers(number)
</syntaxhighlight>
+
:Returns true or false depending on whether a particular modifier key is being held at the time this function is run. Can be paired with a number of actions, including clicking on a label.
 +
 
 +
;Parameters
 +
* ''number'': A number corresponding to a specific modifier key.
  
==mudletOlderThan==
+
;Modifiers
;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.
 
  
See also: [[#getMudletVersion|getMudletVersion()]]
+
Modifier values can be found by accessing the global `mudlet.keymodifier` table, which, as of 4.18, provides for the following:
  
;Parameters
+
<syntaxhighlight lang="lua">
* ''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.
+
  Alt = 134217728,
* ''minor:''
+
  Control = 67108864,
:(optional) minor version to check.
+
  GroupSwitch = 1073741824,
* ''patch:''
+
  Keypad = 536870912,
:(optional) patch version to check.
+
  Meta = 268435456,
 +
  None = 0,
 +
  Shift = 33554432
 +
}
 +
</syntaxhighlight>
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
-- stop doing the script of Mudlet is older than 3.2
+
local MyLabel = MyLabel or Geyser.Label:new({
if mudletOlderThan(3,2) then return end
+
  name = "MyLabel",
 +
  x = 0,y = 0,
 +
  height = 200, width = 100,
 +
  message = "This is my label"
 +
})
  
-- or older than 2.1.3
+
function clickity(...)
if mudletOlderThan(2, 1, 3) then return end
+
  display(...)
 +
 
 +
  for k, v in spairs(mudlet.keymodifier) do
 +
    print(f[[Holding down {k} : {holdingModifiers(v)}]])
 +
  end
 +
end
  
-- however, if you'd like to check that a certain function is available, like getMousePosition(), do this instead:
+
setLabelClickCallback("MyLabel", "clickity")
if not getMousePosition then return end
 
  
-- if you'd like to check that coroutines are supported, do this instead:
+
-- Result:
if not mudlet.supportscoroutines then return end
+
--
 +
-- Holding down Alt : true
 +
-- Holding down Control : false
 +
-- Holding down GroupSwitch : false
 +
-- Holding down Keypad : false
 +
-- Holding down Meta : false
 +
-- Holding down None : false
 +
-- Holding down Shift : false
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==openWebPage==
+
;Notes
;openWebPage(URL)
+
 
:Opens the browser to the given webpage.
+
You may only test for one modifier key being held. If more than one modifier key is held down, then all results will be false.
 +
 
 +
==installModule==
 +
;installModule(location)
 +
:Installs a Mudlet XML, zip, or mpackage as a module.
  
 
;Parameters
 
;Parameters
* ''URL:''
+
* ''location:''
:Exact URL to open.
+
:Exact location of the file install.
 +
 
 +
:See also: [[#uninstallModule | uninstallModule()]], [[Manual:Event_Engine#sysLuaInstallModule | Event: sysLuaInstallModule]], [[#setModulePriority | setModulePriority()]]
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
openWebPage("http://google.com")
+
installModule([[C:\Documents and Settings\bub\Desktop\myalias.xml]])
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Note: This function can be used to open a local file or file folder as well by using "file:///" and the file path instead of "http://".
+
==installPackage==
 +
;installPackage(location or url)
 +
:Installs a Mudlet XML or package. Since Mudlet 4.11+ returns <code>true</code> if it worked, or <code>false</code>.
 +
 
 +
;Parameters
 +
* ''location:''
 +
:Exact location of the xml or package to install.
 +
Since Mudlet 4.11+ it is possible to pass download link to a package (must start with <code>http</code> or <code>https</code> and end with <code>.xml</code>, <code>.zip</code>, <code>.mpackage</code> or <code>.trigger</code>)
 +
 
 +
:See also: [[#uninstallPackage | uninstallPackage()]]
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
openWebPage("file:///"..getMudletHomeDir().."file.txt")
+
installPackage([[C:\Documents and Settings\bub\Desktop\myalias.xml]])
 +
</syntaxhighlight>
 +
 
 +
<syntaxhighlight lang="lua">
 +
installPackage([[https://github.com/Mudlet/Mudlet/blob/development/src/run-lua-code-v4.xml]])
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==playMusicFile==
+
==killAnonymousEventHandler==
;playMusicFile(settings table)
+
;killAnonymousEventHandler(handler id)
:Plays music files from the Internet or the local file system to the "media" folder of the profile for later use with [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]].
+
:Disables and removes the given event handler.
  
{| class="wikitable"
+
;Parameters
! Required
+
* ''handler id''
! Key
+
:ID of the event handler to remove as returned by the [[ #registerAnonymousEventHandler | registerAnonymousEventHandler ]] function.
 +
 
 +
:See also: [[ #registerAnonymousEventHandler | registerAnonymousEventHandler ]]
 +
 
 +
{{MudletVersion|3.5}}
 +
;Example
 +
<syntaxhighlight lang="lua">
 +
-- registers an event handler that prints the first 5 GMCP events and then terminates itself
 +
 
 +
local counter = 0
 +
local handlerId = registerAnonymousEventHandler("gmcp", function(_, origEvent)
 +
  print(origEvent)
 +
  counter = counter + 1
 +
  if counter == 5 then
 +
    killAnonymousEventHandler(handlerId)
 +
  end
 +
end)
 +
</syntaxhighlight>
 +
 
 +
==loadMusicFile==
 +
;loadMusicFile(settings table) or loadMusicFile(name, [url])
 +
:Loads music files from the Internet or the local file system to the "media" folder of the profile for later use with [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]] and [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]]. Although files could be loaded directly at playing time from [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], loadMusicFile() provides the advantage of loading files in advance.
 +
 
 +
{| class="wikitable"
 +
! Required
 +
! Key
 
! Value
 
! Value
! Default
 
 
! style="text-align:left;"| Purpose
 
! style="text-align:left;"| Purpose
 
|- style="color: green;"
 
|- style="color: green;"
Line 873: Line 1,022:
 
| name
 
| name
 
| <file name>
 
| <file name>
| &nbsp;
 
 
| style="text-align:left;"|
 
| style="text-align:left;"|
 
* Name of the media file.
 
* Name of the media file.
Line 879: Line 1,027:
 
* May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")
 
* May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")
 
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")
 
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")
* Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.
+
|- style="color: blue;"
|-
+
| style="text-align:center;"| Maybe
| style="text-align:center;"| No
+
| url
| volume
+
| <url>
| 1 to 100
 
| 50
 
 
| style="text-align:left;"|
 
| style="text-align:left;"|
* Relative to the volume set on the player's client.
+
* Resource location where the media file may be downloaded.
 +
* Only required if file to load is not part of the profile or on the local file system.
 
|-
 
|-
| style="text-align:center;"| No
+
|}
| fadein
+
 
|<msec>
+
See also: [[Manual:Miscellaneous_Functions#playMusicFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]
|
+
 
|
+
{{MudletVersion|4.15}}
*Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.
+
 
*Start position: Start of media.
+
;Example
*End position:  Start of media plus the number of milliseconds (msec) specified.
+
 
*1000 milliseconds = 1 second.
+
<syntaxhighlight lang="lua">
|-
+
---- Table Parameter Syntax ----
| style="text-align:center;" |No
+
 
| fadeout
+
-- Download from the Internet
|<msec>
+
loadMusicFile({
|
+
    name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"
|
+
    , url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"
*Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.
+
})
*Start position:  End of the media minus the number of milliseconds (msec) specified.
+
 
*End position: End of the media.
+
-- OR download from the profile
*1000 milliseconds = 1 second.
+
loadMusicFile({name = getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3"})
|-
+
 
| style="text-align:center;"| No
+
-- OR download from the local file system
| start
+
loadMusicFile({name = "C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3"})
| <msec>
+
</syntaxhighlight>
| 0
+
<syntaxhighlight lang="lua">
 +
---- Ordered Parameter Syntax of loadMusicFile(name[, url]) ----
 +
 
 +
-- Download from the Internet
 +
loadMusicFile(
 +
    "167124__patricia-mcmillen__rugby-club-in-spain.mp3"
 +
    , "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"
 +
)
 +
 
 +
-- OR download from the profile
 +
loadMusicFile(getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3")
 +
 
 +
-- OR download from the local file system
 +
loadMusicFile("C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3")
 +
</syntaxhighlight>
 +
 
 +
==loadSoundFile==
 +
;loadSoundFile(settings table) or loadSoundFile(name, [url])
 +
:Loads sound files from the Internet or the local file system to the "media" folder of the profile for later use with [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]] and [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]]. Although files could be loaded directly at playing time from [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], loadSoundFile() provides the advantage of loading files in advance.
 +
 
 +
{| class="wikitable"
 +
! Required
 +
! Key
 +
! Value
 +
! style="text-align:left;"| Purpose
 +
|- style="color: green;"
 +
| style="text-align:center;"| Yes
 +
| name
 +
| <file name>
 
| style="text-align:left;"|
 
| style="text-align:left;"|
* Begin play at the specified position in milliseconds.
+
* Name of the media file.
|-
+
* May contain directory information (i.e. weather/lightning.wav).
| style="text-align:center;" |No
+
* May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")
| loops
+
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")
| -1, or >= 1
+
|- style="color: blue;"
|1
+
| style="text-align:center;"| Maybe
| style="text-align:left;" |
+
| url
*Number of iterations that the media plays.
+
| <url>
* A value of -1 allows the media to loop indefinitely.
 
|-
 
| style="text-align:center;" |No
 
| key
 
|<key>
 
|&nbsp;
 
| style="text-align:left;" |
 
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".
 
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.
 
|-
 
| style="text-align:center;"| No
 
| tag
 
| <tag>
 
| &nbsp;
 
 
| style="text-align:left;"|
 
| style="text-align:left;"|
* Helps categorize media.
+
* Resource location where the media file may be downloaded.
 +
* Only required if file to load is not part of the profile or on the local file system.
 
|-
 
|-
| style="text-align:center;" |No
+
|}
| continue
 
| true or false
 
| true
 
| style="text-align:left;" |
 
*Continues playing matching new music files when true.
 
*Restarts matching new music files when false.
 
|- style="color: blue;"
 
| style="text-align:center;"| Maybe
 
| url
 
| <url>
 
| &nbsp;
 
| style="text-align:left;"|
 
* Resource location where the media file may be downloaded.
 
* Only required if the file is to be downloaded remotely.
 
|-
 
|}
 
  
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]
+
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]
  
 
{{MudletVersion|4.15}}
 
{{MudletVersion|4.15}}
Line 965: Line 1,111:
 
---- Table Parameter Syntax ----
 
---- Table Parameter Syntax ----
  
-- Play a music file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)
+
-- Download from the Internet
playMusicFile({
+
loadSoundFile({
     name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"
+
     name = "cow.wav"
 +
    , url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"
 
})
 
})
  
-- OR copy once from the game's profile, and play a music file stored in the profile's media directory
+
-- OR download from the profile
---- [volume] of 75 (1 to 100)
+
loadSoundFile({name = getMudletHomeDir().. "/cow.wav"})
playMusicFile({
+
 
    name = getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3"
+
-- OR download from the local file system
    , volume = 75
+
loadSoundFile({name = "C:/Users/Tamarindo/Documents/cow.wav"})
})
+
</syntaxhighlight>
 +
<syntaxhighlight lang="lua">
 +
---- Ordered Parameter Syntax of loadSoundFile(name[,url]) ----
 +
 
 +
-- Download from the Internet
 +
loadSoundFile("cow.wav", "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/")
 +
 
 +
-- OR download from the profile
 +
loadSoundFile(getMudletHomeDir().. "/cow.wav")
  
-- OR copy once from the local file system, and play a music file stored in the profile's media directory
+
-- OR download from the local file system
---- [volume] of 75 (1 to 100)
+
loadSoundFile("C:/Users/Tamarindo/Documents/cow.wav")
playMusicFile({
+
</syntaxhighlight>
    name = "C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3"
 
    , volume = 75
 
})
 
  
-- OR download once from the Internet, and play music stored in the profile's media directory
+
==mudletOlderThan==
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 20 seconds
+
;mudletOlderThan(major, [minor], [patch])
---- [fadeout] and decrease the volume from default volume to one, 53 seconds from the end of the music
+
: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.
---- [start] 10 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)
 
---- [key] reference of "rugby" for stopping this unique music later
 
---- [tag] reference of "ambience" to stop and music later with the same tag
 
---- [continue] playing this music if another request for the same music comes in (false restarts it)
 
---- [url] to download once from the Internet if the music does not exist in the profile's media directory
 
playMusicFile({
 
    name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"
 
    , volume = nil -- nil lines are optional, no need to use
 
    , fadein = 20000
 
    , fadein = 53000
 
    , start = 10000
 
    , loops = nil -- nil lines are optional, no need to use
 
    , key = "rugby"
 
    , tag = "ambience"
 
    , continue = true
 
    , url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"
 
})
 
</syntaxhighlight>
 
<syntaxhighlight lang="lua">
 
---- Ordered Parameter Syntax of playMusicFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,continue][,url]) ----
 
  
-- Play a music file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)
+
See also: [[#getMudletVersion|getMudletVersion()]]
playMusicFile(
 
    "167124__patricia-mcmillen__rugby-club-in-spain.mp3"  -- name
 
)
 
  
-- OR copy once from the game's profile, and play a music file stored in the profile's media directory
+
;Parameters
---- [volume] of 75 (1 to 100)
+
* ''major:''
playMusicFile(
+
: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.
    getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name
+
* ''minor:''
    , 75 -- volume
+
:(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, 1, 3) then return end
  
-- OR copy once from the local file system, and play a music file stored in the profile's media directory
+
-- however, if you'd like to check that a certain function is available, like getMousePosition(), do this instead:
---- [volume] of 75 (1 to 100)
+
if not getMousePosition then return end
playMusicFile(
 
    "C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name
 
    , 75 -- volume
 
)
 
  
-- OR download once from the Internet, and play music stored in the profile's media directory
+
-- if you'd like to check that coroutines are supported, do this instead:
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 20 seconds
+
if not mudlet.supports.coroutines then return end
---- [fadeout] and decrease the volume from default volume to one, 53 seconds from the end of the music
 
---- [start] 10 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)
 
---- [key] reference of "rugby" for stopping this unique music later
 
---- [tag] reference of "ambience" to stop and music later with the same tag
 
---- [continue] playing this music if another request for the same music comes in (false restarts it)
 
---- [url] to download once from the Internet if the music does not exist in the profile's media directory
 
playMusicFile(
 
    "167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name
 
    , nil -- volume
 
    , 20000 -- fadein
 
    , 53000 -- fadeout
 
    , 10000 -- start
 
    , nil -- loops
 
    , "rugby" -- key
 
    , "ambience" -- tag
 
    , true -- continue
 
    , "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/" -- url
 
)
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==playSoundFile, PR #5799 merged ==
+
==openWebPage==
;playSoundFile(settings table)
+
;openWebPage(URL)
:Plays sound files from the Internet or the local file system to the "media" folder of the profile for later use with [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]].
+
:Opens the browser to the given webpage.
 +
 
 +
;Parameters
 +
* ''URL:''
 +
:Exact URL to open.
  
{| class="wikitable"
+
;Example
! Required
+
<syntaxhighlight lang="lua">
! Key
+
openWebPage("http://google.com")
! Value
+
</syntaxhighlight>
! Default
+
 
! style="text-align:left;"| Purpose
+
Note: This function can be used to open a local file or file folder as well by using "file:///" and the file path instead of "http://".
 +
 
 +
;Example
 +
<syntaxhighlight lang="lua">
 +
openWebPage("file:///"..getMudletHomeDir().."file.txt")
 +
</syntaxhighlight>
 +
 
 +
==playMusicFile==
 +
;playMusicFile(settings table)
 +
:Plays music files from the Internet or the local file system to the "media" folder of the profile for later use with [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]].
 +
 
 +
{| class="wikitable"
 +
! Required
 +
! Key
 +
! Value
 +
! Default
 +
! style="text-align:left;"| Purpose
 
|- style="color: green;"
 
|- style="color: green;"
 
| style="text-align:center;"| Yes
 
| style="text-align:center;"| Yes
Line 1,104: Line 1,240:
 
| style="text-align:left;"|
 
| style="text-align:left;"|
 
*  Begin play at the specified position in milliseconds.
 
*  Begin play at the specified position in milliseconds.
 +
|-
 +
| style="text-align:center;"| No
 +
| finish
 +
| <msec>
 +
|
 +
| style="text-align:left;"|
 +
*  End play at the specified position in milliseconds.
 
|-
 
|-
 
| style="text-align:center;" |No
 
| style="text-align:center;" |No
Line 1,129: Line 1,272:
 
|-
 
|-
 
| style="text-align:center;" |No
 
| style="text-align:center;" |No
| priority
+
| continue
| 1 to 100
+
| true or false
|&nbsp;
+
| true
 
| style="text-align:left;" |
 
| style="text-align:left;" |
*Halts the play of current or future played media files with a lower priority while this media plays.
+
*Continues playing matching new music files when true.
 +
*Restarts matching new music files when false.
 
|- style="color: blue;"
 
|- style="color: blue;"
 
| style="text-align:center;"| Maybe
 
| style="text-align:center;"| Maybe
Line 1,145: Line 1,289:
 
|}
 
|}
  
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]
+
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#getPlayingMusic|getPlayingMusic()]], [[Manual:Miscellaneous_Functions#getPlayingSounds|getPlayingSounds()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]
 +
 
 +
{{Note}} on Windows and certain files are not playing? Try installing the 3rd party [https://codecguide.com/download_k-lite_codec_pack_standard.htm K-lite codec pack].
  
 
{{MudletVersion|4.15}}
 
{{MudletVersion|4.15}}
Line 1,154: Line 1,300:
 
---- Table Parameter Syntax ----
 
---- Table Parameter Syntax ----
  
-- Play a sound file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)
+
-- Play a music file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)
playSoundFile({
+
playMusicFile({
     name = "cow.wav"
+
     name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"
 
})
 
})
  
-- OR copy once from the game's profile, and play a sound file stored in the profile's media directory
+
-- OR copy once from the game's profile, and play a music file stored in the profile's media directory
 
---- [volume] of 75 (1 to 100)
 
---- [volume] of 75 (1 to 100)
playSoundFile({
+
playMusicFile({
     name = getMudletHomeDir().. "/cow.wav"
+
     name = getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3"
 
     , volume = 75
 
     , volume = 75
 
})
 
})
  
-- OR copy once from the local file system, and play a sound file stored in the profile's media directory
+
-- OR copy once from the local file system, and play a music file stored in the profile's media directory
 
---- [volume] of 75 (1 to 100)
 
---- [volume] of 75 (1 to 100)
playSoundFile({
+
playMusicFile({
     name = "C:/Users/Tamarindo/Documents/cow.wav"
+
     name = "C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3"
 
     , volume = 75
 
     , volume = 75
 
})
 
})
  
-- OR download once from the Internet, and play a sound stored in the profile's media directory
+
-- OR download once from the Internet, and play music stored in the profile's media directory
---- [volume] of 75
+
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 20 seconds
---- [loops] of 2 (-1 for indefinite repeats, 1+ for finite repeats)
+
---- [fadeout] and decrease the volume from default volume to one, 53 seconds from the end of the music
---- [key] reference of "cow" for stopping this unique sound later
+
---- [start] 10 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)
---- [tag] reference of "animals" to stop a group of sounds later with the same tag
+
---- [finish] 110 seconds from the track start (fadeout scales its volume decrease over a shorter duration, too)
---- [priority] of 25 (1 to 100, 50 default, a sound with a higher priority would stop this one)
+
---- [key] reference of "rugby" for stopping this unique music later
---- [url] to download once from the Internet if the sound does not exist in the profile's media directory
+
---- [tag] reference of "ambience" to stop and music later with the same tag
playSoundFile({
+
---- [continue] playing this music if another request for the same music comes in (false restarts it)  
     name = "cow.wav"
+
---- [url] to download once from the Internet if the music does not exist in the profile's media directory
     , volume = 75
+
playMusicFile({
    , fadein = nil -- nil lines are optional, no need to use
+
     name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"
     , fadeout = nil -- nil lines are optional, no need to use
+
     , volume = nil -- nil lines are optional, no need to use
     , start = nil -- nil lines are optional, no need to use
+
    , fadein = 20000
    , loops = 2
+
     , fadeout = 53000
     , key = "cow"
+
    , start = 10000
     , tag = "animals"
+
    , finish = 110000
     , priority = 25
+
     , loops = nil -- nil lines are optional, no need to use
 +
     , key = "rugby"
 +
     , tag = "ambience"
 +
     , continue = true
 
     , url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"
 
     , url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"
 
})
 
})
 
</syntaxhighlight>
 
</syntaxhighlight>
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
---- Ordered Parameter Syntax of playSoundFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,priority][,url]) ----
+
---- Ordered Parameter Syntax of playMusicFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,continue][,url][,finish]) ----
  
-- Play a sound file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)
+
-- Play a music file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)
playSoundFile(
+
playMusicFile(
     "cow.wav" -- name
+
     "167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name
 
)
 
)
  
-- OR copy once from the game's profile, and play a sound file stored in the profile's media directory
+
-- OR copy once from the game's profile, and play a music file stored in the profile's media directory
 
---- [volume] of 75 (1 to 100)
 
---- [volume] of 75 (1 to 100)
playSoundFile(
+
playMusicFile(
     getMudletHomeDir().. "/cow.wav" -- name
+
     getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name
 
     , 75 -- volume
 
     , 75 -- volume
 
)
 
)
  
-- OR copy once from the local file system, and play a sound file stored in the profile's media directory
+
-- OR copy once from the local file system, and play a music file stored in the profile's media directory
 
---- [volume] of 75 (1 to 100)
 
---- [volume] of 75 (1 to 100)
playSoundFile(
+
playMusicFile(
     "C:/Users/Tamarindo/Documents/cow.wav" -- name
+
     "C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name
 
     , 75 -- volume
 
     , 75 -- volume
 
)
 
)
  
-- OR download once from the Internet, and play a sound stored in the profile's media directory
+
-- OR download once from the Internet, and play music stored in the profile's media directory
---- [volume] of 75
+
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 20 seconds
---- [loops] of 2 (-1 for indefinite repeats, 1+ for finite repeats)
+
---- [fadeout] and decrease the volume from default volume to one, 53 seconds from the end of the music
---- [key] reference of "cow" for stopping this unique sound later
+
---- [start] 10 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)
---- [tag] reference of "animals" to stop a group of sounds later with the same tag
+
---- [finish] 110 seconds from the track start (fadeout scales its volume decrease over a shorter duration, too)
---- [priority] of 25 (1 to 100, 50 default, a sound with a higher priority would stop this one)
+
---- [key] reference of "rugby" for stopping this unique music later
---- [url] to download once from the Internet if the sound does not exist in the profile's media directory
+
---- [tag] reference of "ambience" to stop and music later with the same tag
playSoundFile(
+
---- [continue] playing this music if another request for the same music comes in (false restarts it)  
     "cow.wav" -- name
+
---- [url] to download once from the Internet if the music does not exist in the profile's media directory
     , 75 -- volume
+
playMusicFile(
     , nil -- fadein
+
     "167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name
     , nil -- fadeout
+
     , nil -- volume
     , nil -- start
+
     , 20000 -- fadein
     , 2 -- loops
+
     , 53000 -- fadeout
     , "cow" -- key  
+
     , 10000 -- start
     , "animals" -- tag
+
     , nil -- loops
     , 25 -- priority
+
     , "rugby" -- key  
 +
     , "ambience" -- tag
 +
     , true -- continue
 
     , "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/" -- url
 
     , "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/" -- url
 +
    , 110000 -- finish
 
)
 
)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==purgeMediaCache==
+
==playSoundFile==
;purgeMediaCache()
+
;playSoundFile(settings table)
: Purge all media file stored in the media cache within a given Mudlet profile (media used with MCMP and MSP protocols). As game developers update the media files on their games, this enables the media folder inside the profile to be cleared so that the media files could be refreshed to the latest update(s).
+
:Plays sound files from the Internet or the local file system to the "media" folder of the profile for later use with [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]].
  
;Guidance:
+
{| class="wikitable"
 
+
! Required
* Instruct a player to type ''lua purgeMediaCache()'' on the command line, or
+
! Key
* Distribute a trigger, button or other scriptable feature for the given profile to call ''purgeMediaCache()''
+
! Value
 
+
! Default
: See also: [[Manual:Supported_Protocols#MSP|Supported Protocols MSP]], [[Manual:Scripting#MUD_Client_Media_Protocol|Scripting MCMP]]
+
! style="text-align:left;"| Purpose
 
+
|- style="color: green;"
==receiveMSP==
+
| style="text-align:center;"| Yes
;receiveMSP(command)
+
| name
: Receives a well-formed Mud Sound Protocol (MSP) message to be processed by the Mudlet client. Reference the [[Manual:Supported_Protocols#MSP|Supported Protocols MSP]] manual for more information on about what can be sent and example triggers.
+
| <file name>
 
+
| &nbsp;
: See also: [[Manual:Supported_Protocols#MSP|Supported Protocols MSP]]
+
| style="text-align:left;"|
 
+
* Name of the media file.
;Example
+
* May contain directory information (i.e. weather/lightning.wav).
<syntaxhighlight lang="lua">
+
* May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")
--Play a cow.wav media file stored in the media folder of the current profile. The sound would play twice at a normal volume.
+
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")
receiveMSP("!!SOUND(cow.wav L=2 V=50)")
+
* Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.
 
+
|-
--Stop any SOUND media files playing stored in the media folder of the current profile.
+
| style="text-align:center;"| No
receiveMSP("!!SOUND(Off)")
+
| volume
 
+
| 1 to 100
--Play a city.mp3 media file stored in the media folder of the current profile. The music would play once at a low volume.
+
| 50
--The music would continue playing if it was triggered earlier by another room, perhaps in the same area.
+
| style="text-align:left;"|
receiveMSP([[!!MUSIC(city.mp3 L=1 V=25 C=1)]])
+
* Relative to the volume set on the player's client.
 
+
|-
--Stop any MUSIC media files playing stored in the media folder of the current profile.
+
| style="text-align:center;"| No
receiveMSP("!!MUSIC(Off)")
+
| fadein
</syntaxhighlight>
+
|<msec>
 
+
|
==registerAnonymousEventHandler==
+
|
;registerAnonymousEventHandler(event name, functionReference, [one shot])
+
*Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.
: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 refered to either by name as a string containing a global function name, or with the lua function object itself.
+
*Start position:  Start of media.
 
+
*End position: Start of media plus the number of milliseconds (msec) specified.
: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.
+
*1000 milliseconds = 1 second.
 
+
|-
:The function returns an ID that can be used in [[Manual:Lua_Functions#killAnonymousEventHandler|killAnonymousEventHandler()]] to unregister the handler again.
+
| style="text-align:center;" |No
 
+
| fadeout
:If you use an asterisk ''("*")'' as the event name, your code will capture all events. Useful for debugging, or integration with external programs.
+
|<msec>
 
+
|
{{note}} The ability to refer lua functions directly, the <code>one shot</code> parameter and the returned ID are features of Mudlet 3.5 and above.
+
|
 
+
*Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.
{{note}} The ''"*"'' all-events capture was added in Mudlet 4.10.
+
*Start position:  End of the media minus the number of milliseconds (msec) specified.
 
+
*End position:  End of the media.
;See also
+
*1000 milliseconds = 1 second.
:[[Manual:Lua_Functions#killAnonymousEventHandler|killAnonymousEventHandler()]], [[Manual:Lua_Functions#raiseEvent|raiseEvent()]], [[Manual:Event_Engine#Mudlet-raised_events|list of Mudlet-raised events]]
+
|-
 
+
| style="text-align:center;"| No
;Example
+
| start
<syntaxhighlight lang="lua">
+
| <msec>
-- example taken from the God Wars 2 (http://godwars2.org) Mudlet UI - forces the window to keep to a certain size
+
| 0
function keepStaticSize()
+
| style="text-align:left;"|
  setMainWindowSize(1280,720)
+
*  Begin play at the specified position in milliseconds.
end -- keepStaticSize
+
|-
 
+
| style="text-align:center;"| No
if keepStaticSizeEventHandlerID then killAnonymousEventHandler(keepStaticSizeEventHandlerID) end -- clean up any already registered handlers for this function
+
| finish
keepStatisSizeEventHandlerID = registerAnonymousEventHandler("sysWindowResizeEvent", "keepStaticSize") -- register the event handler and save the ID for later killing
+
| <msec>
</syntaxhighlight>
+
|
 
+
| style="text-align:left;"|
<syntaxhighlight lang="lua">
+
*  Finish play at the specified position in milliseconds.
-- 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
+
| style="text-align:center;" |No
-- table via an own namespace.
+
| loops
local inventory = {}
+
| -1, or >= 1
 
+
|1
local function inventoryAdd()
+
| style="text-align:left;" |
  if gmcp.Char.Items.Add.location == "inv" then
+
*Number of iterations that the media plays.
    inventory[#inventory + 1] = table.deepcopy(gmcp.Char.Items.Add.item)
+
* A value of -1 allows the media to loop indefinitely.
  end
+
|-
end
+
| style="text-align:center;" |No
if inventoryAddHandlerID then killAnonymousEventHandler(inventoryAddHandlerID) end -- clean up any already registered handlers for this function
+
| key
inventoryAddHandlerID = registerAnonymousEventHandler("gmcp.Char.Items.Add", inventoryAdd) -- register the event handler and save the ID for later killing
+
|<key>
 
+
|&nbsp;
local function inventoryList()
+
| style="text-align:left;" |
  if gmcp.Char.Items.List.location == "inv" then
+
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".
    inventory = table.deepcopy(gmcp.Char.Items.List.items)
+
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.
  end
+
|-
end
+
| style="text-align:center;"| No
if inventoryListHandlerID then killAnonymousEventHandler(inventoryListHandlerID) end -- clean up any already registered handlers for this function
+
| tag
inventoryListHandlerID = registerAnonymousEventHandler("gmcp.Char.Items.List", inventoryList) -- register the event handler and save the ID for later killing
+
| <tag>
 +
| &nbsp;
 +
| style="text-align:left;"|
 +
* Helps categorize media.
 +
|-
 +
| style="text-align:center;" |No
 +
| priority
 +
| 1 to 100
 +
|&nbsp;
 +
| style="text-align:left;" |
 +
*Halts the play of current or future played media files with a lower priority while this media plays.
 +
|- style="color: blue;"
 +
| style="text-align:center;"| Maybe
 +
| url
 +
| <url>
 +
| &nbsp;
 +
| style="text-align:left;"|
 +
* Resource location where the media file may be downloaded.
 +
* Only required if the file is to be downloaded remotely.
 +
|-
 +
|}
 +
 
 +
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#getPlayingMusic|getPlayingMusic()]], [[Manual:Miscellaneous_Functions#getPlayingSounds|getPlayingSounds()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]
 +
 
 +
{{Note}} on Windows and certain files are not playing? Try installing the 3rd party [https://codecguide.com/download_k-lite_codec_pack_standard.htm K-lite codec pack].
 +
 
 +
{{MudletVersion|4.15}}
 +
 
 +
;Example
  
local function inventoryUpdate()
+
<syntaxhighlight lang="lua">
  if gmcp.Char.Items.Remove.location == "inv" then
+
---- Table Parameter Syntax ----
    local found
+
 
    local updatedItem = gmcp.Char.Items.Update.item
+
-- Play a sound file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)
    for index, item in ipairs(inventory) do
+
playSoundFile({
      if item.id == updatedItem.id then
+
     name = "cow.wav"
        found = index
+
})
        break
 
      end
 
    end
 
    if found then
 
      inventory[found] = table.deepcopy(updatedItem)
 
     end
 
  end
 
end
 
if inventoryUpdateHandlerID then killAnonymousEventHandler(inventoryUpdateHandlerID) end -- clean up any already registered handlers for this function
 
inventoryUpdateHandlerID = registerAnonymousEventHandler("gmcp.Char.Items.Update", inventoryUpdate)
 
  
local function inventoryRemove()
+
-- OR copy once from the game's profile, and play a sound file stored in the profile's media directory
  if gmcp.Char.Items.Remove.location == "inv" then
+
---- [volume] of 75 (1 to 100)
    local found
+
playSoundFile({
    local removedItem = gmcp.Char.Items.Remove.item
+
     name = getMudletHomeDir().. "/cow.wav"
    for index, item in ipairs(inventory) do
+
    , volume = 75
      if item.id == removedItem.id then
+
})
        found = index
 
        break
 
      end
 
    end
 
    if found then
 
      table.remove(inventory, found)
 
     end
 
  end
 
end
 
if inventoryRemoveHandlerID then killAnonymousEventHandler(inventoryRemoveHandlerID) end -- clean up any already registered handlers for this function
 
inventoryRemoveHandlerID = registerAnonymousEventHandler("gmcp.Char.Items.Remove", inventoryRemove)
 
</syntaxhighlight>
 
  
<syntaxhighlight lang="lua">
+
-- OR copy once from the local file system, and play a sound file stored in the profile's media directory
-- downloads a package from the internet and kills itself after it is installed.
+
---- [volume] of 75 (1 to 100)
local saveto = getMudletHomeDir().."/dark-theme-mudlet.zip"
+
playSoundFile({
local url = "http://www.mudlet.org/wp-content/files/dark-theme-mudlet.zip"
+
    name = "C:/Users/Tamarindo/Documents/cow.wav"
 +
    , volume = 75
 +
})
  
if myPackageInstallHandler then killAnonymousEventHandler(myPackageInstallHandler) end
+
-- OR download once from the Internet, and play a sound stored in the profile's media directory
myPackageInstallHandler = registerAnonymousEventHandler(
+
---- [volume] of 75
  "sysDownloadDone",
+
---- [loops] of 2 (-1 for indefinite repeats, 1+ for finite repeats)
  function(_, filename)
+
---- [key] reference of "cow" for stopping this unique sound later
    if filename ~= saveto then
+
---- [tag] reference of "animals" to stop a group of sounds later with the same tag
      return true -- keep the event handler since this was not our file
+
---- [priority] of 25 (1 to 100, 50 default, a sound with a higher priority would stop this one)
     end
+
---- [url] to download once from the Internet if the sound does not exist in the profile's media directory
     installPackage(saveto)
+
playSoundFile({
     os.remove(b)
+
     name = "cow.wav"
  end,
+
     , volume = 75
  true
+
     , fadein = nil -- nil lines are optional, no need to use
)
+
    , fadeout = nil -- nil lines are optional, no need to use
 
+
    , start = nil -- nil lines are optional, no need to use
downloadFile(saveto, url)
+
    , finish = nil -- nil lines are optional, no need to use
cecho("<white>Downloading <green>"..url.."<white> to <green>"..saveto.."\n")
+
    , loops = 2
 +
    , key = "cow"
 +
    , tag = "animals"
 +
    , priority = 25
 +
    , url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"
 +
})
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
<syntaxhighlight lang="lua">
 +
---- Ordered Parameter Syntax of playSoundFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,priority][,url][,finish]) ----
  
==registerNamedEventHandler==
+
-- Play a sound file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)
; success = registerNamedEventHandler(userName, handlerName, eventName, functionReference, [oneShot])
+
playSoundFile(
 +
    "cow.wav" -- name
 +
)
  
:Registers a named event handler with name handlerName. Named event handlers are protected from duplication and can be stopped and resumed, unlike anonymous event handlers. A separate list is kept per userName
+
-- OR copy once from the game's profile, and play a sound file stored in the profile's media directory
 +
---- [volume] of 75 (1 to 100)
 +
playSoundFile(
 +
    getMudletHomeDir().. "/cow.wav" -- name
 +
    , 75 -- volume
 +
)
  
;See also: [[Manual:Lua_Functions#registerAnonymousEventHandler|registerAnonymousEventHandler()]], [[Manual:Lua_Functions#stopNamedEventHandler|stopNamedEventHandler()]], [[Manual:Lua_Functions#resumeNamedEventHandler|resumeNamedEventHandler()]], [[Manual:Lua_Functions#deleteNamedEventHandler|deleteNamedEventHandler()]], [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]]
+
-- OR copy once from the local file system, and play a sound file stored in the profile's media directory
 +
---- [volume] of 75 (1 to 100)
 +
playSoundFile(
 +
    "C:/Users/Tamarindo/Documents/cow.wav" -- name
 +
    , 75 -- volume
 +
)
  
{{MudletVersion|4.14}}
+
-- OR download once from the Internet, and play a sound stored in the profile's media directory
 
+
---- [volume] of 75
;Parameters
+
---- [loops] of 2 (-1 for indefinite repeats, 1+ for finite repeats)
* ''userName:''
+
---- [key] reference of "cow" for stopping this unique sound later
: The user name the event handler was registered under.
+
---- [tag] reference of "animals" to stop a group of sounds later with the same tag
* ''handlerName:''
+
---- [priority] of 25 (1 to 100, 50 default, a sound with a higher priority would stop this one)
: The name of the handler. Used to reference the handler in other functions and prevent duplicates. Recommended you use descriptive names, "hp" is likely to collide with something else, "DemonVitals" less so.
+
---- [url] to download once from the Internet if the sound does not exist in the profile's media directory
* ''eventName:''
+
playSoundFile(
: The name of the event the handler responds to. [[Manual:Event_Engine#Mudlet-raised_events|See here]] for a list of Mudlet-raised events.
+
    "cow.wav" -- name
* ''functionReference:''
+
    , 75 -- volume
: The function reference to run when the event comes in. Can be the name of a function, "handlerFuncion", or the lua function itself.
+
    , nil -- fadein
* ''oneShot:''
+
    , nil -- fadeout
: (optional) if true, the event handler will only fire once when the event is raised. If you need to extend a one shot event handler for "one more check" you can have the handler return true, and it will keep firing until the function does not return true.
+
    , nil -- start
 +
    , 2 -- loops
 +
    , "cow" -- key
 +
    , "animals" -- tag
 +
    , 25 -- priority
 +
    , "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/" -- url
 +
    , nil -- finish
 +
)
 +
</syntaxhighlight>
 +
 
 +
==purgeMediaCache==
 +
;purgeMediaCache()
 +
: Purge all media file stored in the media cache within a given Mudlet profile (media used with MCMP and MSP protocols). As game developers update the media files on their games, this enables the media folder inside the profile to be cleared so that the media files could be refreshed to the latest update(s).
  
;Returns
+
;Guidance:
* true if successful, otherwise errors.
 
  
;Example
+
* Instruct a player to type ''lua purgeMediaCache()'' on the command line, or
<syntaxhighlight lang="lua">
+
* Distribute a trigger, button or other scriptable feature for the given profile to call ''purgeMediaCache()''
-- register a named event handler. Will call demonVitalsHandler(eventName, ...) when gmcp.Char.Vitals is raised.
+
 
local ok = registerNamedEventHandler("Demonnic", "DemonVitals", "gmcp.Char.Vitals", "demonVitalsHandler")
+
: See also: [[Manual:Supported_Protocols#MSP|Supported Protocols MSP]], [[Manual:Scripting#MUD_Client_Media_Protocol|Scripting MCMP]]
if ok then
 
  cecho("Vitals handler switched to demonVitalsHandler")
 
end
 
  
-- something changes later, and we want to handle vitals with another function, demonBlackoutHandler()
+
==receiveMSP==
-- note we do not use "" around demonBlackoutHandler but instead pass the function itself. Both work.
+
;receiveMSP(command)
-- using the same handlerName ("DemonVitals") means it will automatically unregister the old handler
+
: Receives a well-formed Mud Sound Protocol (MSP) message to be processed by the Mudlet client.  Reference the [[Manual:Supported_Protocols#MSP|Supported Protocols MSP]] manual for more information on about what can be sent and example triggers.
-- and reregister it using the new information.
 
local ok = registerNamedEventHandler("Demonnic", "DemonVitals", "gmcp.Char.Vitals", demonBlackoutHandler)
 
if ok then
 
  cecho("Vitals handler switched to demonBlackoutHandler")
 
end
 
  
-- Now you want to check your inventory, but you only want to do it once, so you pass the optional oneShot as true
+
: See also: [[Manual:Supported_Protocols#MSP|Supported Protocols MSP]]
local function handleInv()
 
  local list = gmcp.Char.Items.List
 
  if list.location ~= "inventory" then
 
    return true -- if list.location is, say "room" then we need to keep responding until it's "inventory"
 
  end
 
  display(list.items) -- you would probably store values and update displays or something, but here I'll just show the data as it comes in
 
end
 
  
-- you can ignore the response from registerNamedEventHandler if you want, it's always going to be true
+
;Example
-- unless there is an error, in which case it throws the error and halts execution anyway. The return is
+
<syntaxhighlight lang="lua">
-- in part for feedback when using the lua alias or other REPL window.
+
--Play a cow.wav media file stored in the media folder of the current profile. The sound would play twice at a normal volume.
registerNamedEventHandler("Demonnic", "DemonInvCheck", "gmcp.Char.Items.List", handleInv, true)
+
receiveMSP("!!SOUND(cow.wav L=2 V=50)")
</syntaxhighlight>
 
  
==reloadModule==
+
--Stop any SOUND media files playing stored in the media folder of the current profile.
;reloadModule(module name)
+
receiveMSP("!!SOUND(Off)")
:Reload a module (by uninstalling and reinstalling).
 
  
:See also: [[#installModule|installModule()]], [[#uninstallModule|uninstallModule()]]
+
--Play a city.mp3 media file stored in the media folder of the current profile. The music would play once at a low volume.
 +
--The music would continue playing if it was triggered earlier by another room, perhaps in the same area.
 +
receiveMSP([[!!MUSIC(city.mp3 L=1 V=25 C=1)]])
  
;Example
+
--Stop any MUSIC media files playing stored in the media folder of the current profile.
<syntaxhighlight lang="lua">
+
receiveMSP("!!MUSIC(Off)")
reloadModule("3k-mapper")
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 +
==registerAnonymousEventHandler==
 +
;registerAnonymousEventHandler(event name, functionReference, [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 refered to either by name as a string containing a global function name, or with the lua function object itself.
  
==removeFileWatch==
+
: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.
;removeFileWatch(path)
 
:Remove file watch on directory or file. Every change in that file will no longer raise [[Manual:Event_Engine#sysPathChanged|sysPathChanged]] event.
 
  
:See also: [[#addFileWatch|addFileWatch()]]
+
:The function returns an ID that can be used in [[Manual:Lua_Functions#killAnonymousEventHandler|killAnonymousEventHandler()]] to unregister the handler again.
  
{{MudletVersion|4.12}}
+
:If you use an asterisk ''("*")'' as the event name, your code will capture all events. Useful for debugging, or integration with external programs.
  
;Example
+
{{note}} The ability to refer lua functions directly, the <code>one shot</code> parameter and the returned ID are features of Mudlet 3.5 and above.
<syntaxhighlight lang="lua">
 
herbs = {}
 
local herbsPath = getMudletHomeDir() .. "/herbs.lua"
 
function herbsChangedHandler(_, path)
 
  if path == herbsPath then
 
    table.load(herbsPath, herbs)
 
    removeFileWatch(herbsPath)
 
  end
 
end
 
  
addFileWatch(herbsPath)
+
{{note}} The ''"*"'' all-events capture was added in Mudlet 4.10.
registerAnonymousEventHandler("sysPathChanged", "herbsChangedHandler")
 
</syntaxhighlight>
 
  
==resetProfile==
+
;See also
;resetProfile()
+
:[[Manual:Lua_Functions#killAnonymousEventHandler|killAnonymousEventHandler()]], [[Manual:Lua_Functions#raiseEvent|raiseEvent()]], [[Manual:Event_Engine#Mudlet-raised_events|list of Mudlet-raised events]]
 
 
: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.
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
resetProfile()
+
-- 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
 +
 
 +
if keepStaticSizeEventHandlerID then killAnonymousEventHandler(keepStaticSizeEventHandlerID) end -- clean up any already registered handlers for this function
 +
keepStatisSizeEventHandlerID = registerAnonymousEventHandler("sysWindowResizeEvent", "keepStaticSize") -- register the event handler and save the ID for later killing
 
</syntaxhighlight>
 
</syntaxhighlight>
  
The function used to require input from the game to work, but as of Mudlet 3.20 that is no longer the case.
 
 
 
{{note}} Don't put resetProfile() in the a script-item in the script editor as the script will be reloaded by resetProfile() as well better use
 
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
lua resetProfile()
+
-- simple inventory tracker for GMCP enabled games. This version does not leak any of the methods
</syntaxhighlight>
+
-- or tables into the global namespace. If you want to access it, you should export the inventory
in your commandline or make an Alias containing resetProfile().
+
-- table via an own namespace.
 +
local inventory = {}
  
==resumeNamedEventHandler==
+
local function inventoryAdd()
; success = resumeNamedEventHandler(userName, handlerName)
+
  if gmcp.Char.Items.Add.location == "inv" then
 +
    inventory[#inventory + 1] = table.deepcopy(gmcp.Char.Items.Add.item)
 +
  end
 +
end
 +
if inventoryAddHandlerID then killAnonymousEventHandler(inventoryAddHandlerID) end -- clean up any already registered handlers for this function
 +
inventoryAddHandlerID = registerAnonymousEventHandler("gmcp.Char.Items.Add", inventoryAdd) -- register the event handler and save the ID for later killing
  
:Resumes a named event handler with name handlerName and causes it to start firing once more
+
local function inventoryList()
 +
  if gmcp.Char.Items.List.location == "inv" then
 +
    inventory = table.deepcopy(gmcp.Char.Items.List.items)
 +
  end
 +
end
 +
if inventoryListHandlerID then killAnonymousEventHandler(inventoryListHandlerID) end -- clean up any already registered handlers for this function
 +
inventoryListHandlerID = registerAnonymousEventHandler("gmcp.Char.Items.List", inventoryList) -- register the event handler and save the ID for later killing
  
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#stopNamedEventHandler|stopNamedEventHandler()]]
+
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
 +
if inventoryUpdateHandlerID then killAnonymousEventHandler(inventoryUpdateHandlerID) end -- clean up any already registered handlers for this function
 +
inventoryUpdateHandlerID = registerAnonymousEventHandler("gmcp.Char.Items.Update", inventoryUpdate)
  
{{MudletVersion|4.14}}
+
local function inventoryRemove()
 
+
  if gmcp.Char.Items.Remove.location == "inv" then
;Parameters
+
    local found
* ''userName:''
+
    local removedItem = gmcp.Char.Items.Remove.item
: The user name the event handler was registered under.
+
    for index, item in ipairs(inventory) do
* ''handlerName:''
+
      if item.id == removedItem.id then
: The name of the handler to resume. Same as used when you called [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]]
+
        found = index
 
+
        break
;Returns
+
      end
* true if successful, false if it didn't exist.
+
    end
 
+
    if found then
;Example
+
      table.remove(inventory, found)
<syntaxhighlight lang="lua">
+
    end
local resumed = resumeNamedEventHandler("Demonnic", "DemonVitals")
+
   end
if resumed then
 
  cecho("DemonVitals resumed!")
 
else
 
   cecho("DemonVitals doesn't exist, cannot resume it")
 
 
end
 
end
 +
if inventoryRemoveHandlerID then killAnonymousEventHandler(inventoryRemoveHandlerID) end -- clean up any already registered handlers for this function
 +
inventoryRemoveHandlerID = registerAnonymousEventHandler("gmcp.Char.Items.Remove", inventoryRemove)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==saveProfile==
+
<syntaxhighlight lang="lua">
;saveProfile(location)
+
-- 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"
  
:Saves the current Mudlet profile to disk, which is equivalent to pressing the "Save Profile" button.
+
if myPackageInstallHandler then killAnonymousEventHandler(myPackageInstallHandler) end
 
+
myPackageInstallHandler = registerAnonymousEventHandler(
;Parameters
+
  "sysDownloadDone",
* ''location:''
+
  function(_, filename)
:(optional) folder to save the profile to. If not given, the profile will go into the [[Mudlet_File_Locations|default location]].
+
    if filename ~= saveto then
 +
      return true -- keep the event handler since this was not our file
 +
    end
 +
    installPackage(saveto)
 +
    os.remove(b)
 +
  end,
 +
  true
 +
)
  
;Example
+
downloadFile(saveto, url)
<syntaxhighlight lang="lua">
+
cecho("<white>Downloading <green>"..url.."<white> to <green>"..saveto.."\n")
saveProfile()
+
</syntaxhighlight>
  
-- save to the desktop on Windows:
+
==registerNamedEventHandler==
saveProfile([[C:\Users\yourusername\Desktop]])
+
; success = registerNamedEventHandler(userName, handlerName, eventName, functionReference, [oneShot])
</syntaxhighlight>
 
  
==sendSocket==
+
:Registers a named event handler with name handlerName. Named event handlers are protected from duplication and can be stopped and resumed, unlike anonymous event handlers. A separate list is kept per userName
;sendSocket(data)
 
  
:Sends given binary data as-is to the game. 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.
+
;See also: [[Manual:Lua_Functions#registerAnonymousEventHandler|registerAnonymousEventHandler()]], [[Manual:Lua_Functions#stopNamedEventHandler|stopNamedEventHandler()]], [[Manual:Lua_Functions#resumeNamedEventHandler|resumeNamedEventHandler()]], [[Manual:Lua_Functions#deleteNamedEventHandler|deleteNamedEventHandler()]], [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]]
  
;Example
+
{{MudletVersion|4.14}}
<syntaxhighlight lang="lua">
 
TN_IAC = 255
 
TN_WILL = 251
 
TN_DO = 253
 
TN_SB = 250
 
TN_SE = 240
 
TN_MSDP = 69
 
  
MSDP_VAL = 1
+
;Parameters
MSDP_VAR = 2
+
* ''userName:''
 +
: The user name the event handler was registered under.
 +
* ''handlerName:''
 +
: The name of the handler. Used to reference the handler in other functions and prevent duplicates. Recommended you use descriptive names, "hp" is likely to collide with something else, "DemonVitals" less so.
 +
* ''eventName:''
 +
: The name of the event the handler responds to. [[Manual:Event_Engine#Mudlet-raised_events|See here]] for a list of Mudlet-raised events.
 +
* ''functionReference:''
 +
: The function reference to run when the event comes in. Can be the name of a function, "handlerFuncion", or the lua function itself.
 +
* ''oneShot:''
 +
: (optional) if true, the event handler will only fire once when the event is raised. If you need to extend a one shot event handler for "one more check" you can have the handler return true, and it will keep firing until the function does not return true.
  
sendSocket( string.char( TN_IAC, TN_DO, TN_MSDP ) ) -- sends IAC DO MSDP
+
;Returns
 +
* true if successful, otherwise errors.
  
--sends: IAC  SB MSDP MSDP_VAR "LIST" MSDP_VAL "COMMANDS" IAC SE
+
;Example
local msg = string.char( TN_IAC, TN_SB, TN_MSDP, MSDP_VAR ) .. " LIST " ..string.char( MSDP_VAL ) .. " COMMANDS " .. string.char( TN_IAC, TN_SE )
+
<syntaxhighlight lang="lua">
sendSocket( msg )
+
-- register a named event handler. Will call demonVitalsHandler(eventName, ...) when gmcp.Char.Vitals is raised.
</syntaxhighlight>
+
local ok = registerNamedEventHandler("Demonnic", "DemonVitals", "gmcp.Char.Vitals", "demonVitalsHandler")
 +
if ok then
 +
  cecho("Vitals handler switched to demonVitalsHandler")
 +
end
  
{{Note}} Remember that should it be necessary to send the byte value of 255 as a ''data'' byte and not as the Telnet '''IAC''' value it is required to repeat it for Telnet to ignore it and not treat it as the latter.
+
-- something changes later, and we want to handle vitals with another function, demonBlackoutHandler()
 +
-- note we do not use "" around demonBlackoutHandler but instead pass the function itself. Both work.
 +
-- using the same handlerName ("DemonVitals") means it will automatically unregister the old handler
 +
-- and reregister it using the new information.
 +
local ok = registerNamedEventHandler("Demonnic", "DemonVitals", "gmcp.Char.Vitals", demonBlackoutHandler)
 +
if ok then
 +
  cecho("Vitals handler switched to demonBlackoutHandler")
 +
end
  
==setMergeTables==
+
-- Now you want to check your inventory, but you only want to do it once, so you pass the optional oneShot as true
;setMergeTables(module)
+
local function handleInv()
:Makes Mudlet merge the table of the given GMCP or MSDP module instead of overwriting the data. This is useful if the game sends only partial updates which need combining for the full data. By default "Char.Status" is the only merged module.
+
  local list = gmcp.Char.Items.List
 +
  if list.location ~= "inventory" then
 +
    return true -- if list.location is, say "room" then we need to keep responding until it's "inventory"
 +
  end
 +
  display(list.items) -- you would probably store values and update displays or something, but here I'll just show the data as it comes in
 +
end
  
;Parameters
+
-- you can ignore the response from registerNamedEventHandler if you want, it's always going to be true
* ''module:''
+
-- unless there is an error, in which case it throws the error and halts execution anyway. The return is
:Name(s) of the GMCP or MSDP module(s) that should be merged as a string - this will add it to the existing list.
+
-- in part for feedback when using the lua alias or other REPL window.
 +
registerNamedEventHandler("Demonnic", "DemonInvCheck", "gmcp.Char.Items.List", handleInv, true)
 +
</syntaxhighlight>
 +
 
 +
==reloadModule==
 +
;reloadModule(module name)
 +
:Reload a module (by uninstalling and reinstalling).
 +
 
 +
:See also: [[#installModule|installModule()]], [[#uninstallModule|uninstallModule()]]
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
setMergeTables("Char.Skills", "Char.Vitals")
+
reloadModule("3k-mapper")
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==setModuleInfo==
 
;setModuleInfo(moduleName, info, value)
 
  
:Sets a specific meta info value for a module
+
==removeFileWatch==
 +
;removeFileWatch(path)
 +
:Remove file watch on directory or file. Every change in that file will no longer raise [[Manual:Event_Engine#sysPathChanged|sysPathChanged]] event.
  
;Parameters
+
:See also: [[#addFileWatch|addFileWatch()]]
* ''moduleName:''
 
:Name of the module
 
* ''info:''
 
: specific info to set (for example "version")
 
* ''value:''
 
: specific value to set (for example "1.0")
 
  
:See also: [[#getModuleInfo|getModuleInfo]], [[#setPackageInfo|getPackageInfo]]
+
{{MudletVersion|4.12}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
setModuleInfo("myModule", "version", "1.0")
+
herbs = {}
</syntaxhighlight>
+
local herbsPath = getMudletHomeDir() .. "/herbs.lua"
 +
function herbsChangedHandler(_, path)
 +
  if path == herbsPath then
 +
    table.load(herbsPath, herbs)
 +
    removeFileWatch(herbsPath)
 +
  end
 +
end
  
{{MudletVersion|4.12}}
+
addFileWatch(herbsPath)
 +
registerAnonymousEventHandler("sysPathChanged", "herbsChangedHandler")
 +
</syntaxhighlight>
  
==setModulePriority==
+
==resetProfile==
;setModulePriority(moduleName, priority)
+
;resetProfile()
  
:Sets the module priority on a given module as a number - the module priority determines the order modules are loaded in, which can be helpful if you have ones dependent on each other. This can also be set from the module manager window.
+
: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.
: Modules with priority <code>-1</code> will be loaded before scripts (Mudlet 4.11+).
 
 
 
: See also: [[#getModulePriority|getModulePriority()]]
 
  
 +
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
setModulePriority("mudlet-mapper", 1)
+
resetProfile()
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==setPackageInfo==
+
The function used to require input from the game to work, but as of Mudlet 3.20 that is no longer the case.
;setPackageInfo(packageName, info, value)
 
  
:Sets a specific meta info value for a package
 
  
;Parameters
+
{{note}} Don't put resetProfile() in the a script-item in the script editor as the script will be reloaded by resetProfile() as well better use
* ''packageName:''
+
<syntaxhighlight lang="lua">
:Name of the module
+
lua resetProfile()
* ''info:''
+
</syntaxhighlight>
: specific info to set (for example "version")
+
in your commandline or make an Alias containing resetProfile().
* ''value:''
 
: specific value to set (for example "1.0")
 
  
:See also: [[#getPackageInfo|getPackageInfo]], [[#setModuleInfo|setModuleInfo]]
+
==resumeNamedEventHandler==
 +
; success = resumeNamedEventHandler(userName, handlerName)
  
;Example
+
:Resumes a named event handler with name handlerName and causes it to start firing once more.
<syntaxhighlight lang="lua">
 
setPackageInfo("myPackage", "title", "This is my test package")
 
</syntaxhighlight>
 
  
{{MudletVersion|4.12}}
+
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#stopNamedEventHandler|stopNamedEventHandler()]]
  
==setServerEncoding==
+
{{MudletVersion|4.14}}
;setServerEncoding(encoding)
 
:Makes Mudlet use the specified [https://www.w3.org/International/questions/qa-what-is-encoding encoding] for communicating with the game.
 
  
 
;Parameters
 
;Parameters
* ''encoding:''
+
* ''userName:''
:Encoding to use.
+
: The user name the event handler was registered under.
 +
* ''handlerName:''
 +
: The name of the handler to resume. Same as used when you called [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]]
  
:See also: [[#getServerEncodingsList|getServerEncodingsList()]], [[#getServerEncoding|getServerEncoding()]]
+
;Returns
 +
* true if successful, false if it didn't exist.
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<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.
+
local resumed = resumeNamedEventHandler("Demonnic", "DemonVitals")
if table.contains(getServerEncodingsList(), "UTF-8") then
+
if resumed then
   setServerEncoding("UTF-8")
+
  cecho("DemonVitals resumed!")
 +
else
 +
   cecho("DemonVitals doesn't exist, cannot resume it")
 
end
 
end
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==showNotification==
+
==saveProfile==
;showNotification(title, [content], [expiryTimeInSeconds])
+
;saveProfile(location)
  
:Shows a native (system) notification.
+
:Saves the current Mudlet profile to disk, which is equivalent to pressing the "Save Profile" button.
 
 
{{MudletVersion|4.11}}
 
 
 
{{Note}} This might not work on all systems, this depends on the system.
 
  
 
;Parameters
 
;Parameters
* ''title'' - plain text notification title
+
* ''location:''
* ''content'' - optional argument, plain text notification content, if omitted title argument will be used as content as well
+
:(optional) folder to save the profile to. If not given, the profile will go into the [[Mudlet_File_Locations|default location]].
* ''expiryTimeInSeconds'' - optional argument, sets expiration time in seconds for notification, very often ignored by OS
 
  
 +
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
showNotification("Notification title", "Notification content", 5)
+
saveProfile()
 +
 
 +
-- save to the desktop on Windows:
 +
saveProfile([[C:\Users\yourusername\Desktop]])
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==spawn==
+
==sendSocket==
;spawn(readFunction, processToSpawn[, ...arguments])
+
;sendSocket(data)
  
: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()''.
+
:Sends given binary data as-is to the game. 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.
  
:This allows you to setup RPC communication with another process.
+
;Example
 
 
;Examples
 
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
-- simple example on a program that quits right away, but prints whatever it gets using the 'display' function
+
TN_IAC = 255
local f = spawn(display, "ls")
+
TN_WILL = 251
display(f.isRunning())
+
TN_DO = 253
f.close()
+
TN_SB = 250
</syntaxhighlight>
+
TN_SE = 240
<syntaxhighlight lang="lua">
+
TN_MSDP = 69
local f = spawn(display, "ls", "-la")
 
display(f.isRunning())
 
f.close()
 
</syntaxhighlight>
 
  
==startLogging==
+
MSDP_VAL = 1
;startLogging(state)
+
MSDP_VAR = 2
  
: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.
+
sendSocket( string.char( TN_IAC, TN_DO, TN_MSDP ) ) -- sends IAC DO MSDP
  
;Parameters
+
--sends: IAC  SB MSDP MSDP_VAR "LIST" MSDP_VAL "COMMANDS" IAC SE
* ''state:''
+
local msg = string.char( TN_IAC, TN_SB, TN_MSDP, MSDP_VAR ) .. " LIST " ..string.char( MSDP_VAL ) .. " COMMANDS " .. string.char( TN_IAC, TN_SE )
:Required: logging state. Passed as a boolean
+
sendSocket( msg )
 +
</syntaxhighlight>
  
;Returns (4 values)
+
{{Note}} Remember that should it be necessary to send the byte value of 255 as a ''data'' byte and not as the Telnet '''IAC''' value it is required to repeat it for Telnet to ignore it and not treat it as the latter.
* ''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).
 
* ''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''.
 
* ''fileName (string)''
 
:The log will be/is being written to the path/file name returned.
 
* ''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
 
  
;Example
+
==setConfig==
<syntaxhighlight lang="lua">
+
; setConfig(option, value)
-- start logging
 
local success, message, filename, code = startLogging(true)
 
if code == 1 or code == -1 then print(f"Started logging to {filename}") end
 
  
-- stop logging
+
:Sets a Mudlet option to a certain value. This comes in handy for scripts that want to customise Mudlet settings to their preferences - for example, setting up mapper room and exit size to one that works for a certain map, or enabling MSDP for a certain game. For transparency reasons, the Debug window (when open) will show which options were modified by scripts.
startLogging(false)
+
:To set many options at once, pass in a table of options. More options will be added over time / per request.
</syntaxhighlight>
 
  
==stopAllNamedEventHandlers==
+
;See also: [[Manual:Lua_Functions#enableMapInfo|enableMapInfo()]], [[Manual:Lua_Functions#disableMapInfo|disableMapInfo()]]
; stopAllNamedEventHandlers(userName)
 
  
:Stops all named event handlers and prevents them from firing any more. Information is retained and handlers can be resumed.
+
{{MudletVersion|4.16}}
  
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#stopNamedEventHandler|stopNamedEventHandler()]], [[Manual:Lua_Functions#resumeNamedEventHandler|resumeNamedEventHandler()]]
+
;Parameters
 +
* ''option:''
 +
: Particular option to change - see list below for available ones.
 +
* ''value:''
 +
: Value to set - can be a boolean, number, or text depending on the option.
  
{{MudletVersion|4.14}}
+
{| class="wikitable sortable"
 +
|+ General options
 +
|-
 +
! Option !! Default !! Description !! Available in Mudlet
 +
|-
 +
| enableGMCP || true || Enable GMCP (Reconnect after changing) || 4.16
 +
|-
 +
| enableMSDP || false || Enable MSDP (Reconnect after changing) || 4.16
 +
|-
 +
| enableMSSP || true || Enable MSSP (Reconnect after changing) || 4.16
 +
|-
 +
| enableMSP || true || Enable MSP (Reconnect after changing) || 4.16
 +
|-
 +
| compactInputLine || false || Hide search, timestamp, other buttons and labels bottom-right of input line || 4.17
 +
|}
  
;Parameter
+
{| class="wikitable sortable"
* ''userName:''
+
|+ Input line
: The user name the event handler was registered under.
+
|-
 +
! Option !! Default !! Description !! Available in Mudlet
 +
|-
 +
| inputLineStrictUnixEndings || false || Workaround option to use strict UNIX line endings for sending commands || 4.16
 +
|-
 +
|}
  
;Example
+
{| class="wikitable sortable"
<syntaxhighlight lang="lua">
+
|+ Main display
stopAllNamedEventHandlers() -- emergency stop situation, most likely.
+
|-
</syntaxhighlight>
+
! Option !! Default !! Description !! Available in Mudlet
 +
|-
 +
| fixUnnecessaryLinebreaks || false || Remove extra linebreaks from output (mostly for IRE servers) || 4.16
 +
|-
 +
|}
  
==stopMusic==
+
{| class="wikitable sortable"
;stopMusic(settings table)
+
|+ Mapper options
:Stop all music (no filter), or music that meets a combination of filters (name, key, and tag) intended to be paired with [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]].
+
|-
 
+
! Option !! Default !! Description !! Available in Mudlet
{| class="wikitable"
+
|-
! Required
+
| mapRoomSize  || 5 || Size of rooms on map (a good value is 5) || 4.16
! Key
+
|-
! Value
+
| mapExitSize  || 10 || Size of exits on map (a good value is 10) || 4.16
! style="text-align:left;"| Purpose
+
|-
 +
| mapRoundRooms || false || Draw rooms round or square || 4.16
 +
|-
 +
| showRoomIdsOnMap || false || Show room IDs on all rooms (if zoom permits) || 4.16
 +
|-
 +
| showMapInfo || - || Map overlay text ('Full', 'Short', or any custom made. Map can show multiple at once) || 4.16
 
|-
 
|-
| style="text-align:center;"| No
+
| hideMapInfo || - || Map overlay text ('Full', 'Short', or any custom made. Hide each info separately to hide all) || 4.16
| name
 
| <file name>
 
| style="text-align:left;"|
 
* Name of the media file.
 
 
|-
 
|-
| style="text-align:center;" |No
+
| show3dMapView || false || Show map as 3D || 4.16
| key
 
|<key>
 
| style="text-align:left;" |
 
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".
 
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.
 
 
|-
 
|-
| style="text-align:center;"| No
+
| mapperPanelVisible || true || Map controls at the bottom || 4.16
| tag
 
| <tag>
 
| style="text-align:left;"|
 
* Helps categorize media.
 
 
|-
 
|-
 +
| mapShowRoomBorders || true || Draw a thin border for every room || 4.16
 
|}
 
|}
  
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]
+
{| class="wikitable sortable"
 +
|+ Special options
 +
|-
 +
! Option !! Default !! Description !! Available in Mudlet
 +
|-
 +
| specialForceCompressionOff || false || Workaround option to disable MCCP compression, in case the game server is not working correctly || 4.16
 +
|-
 +
| specialForceGAOff || false || Workaround option to disable Telnet Go-Ahead, in case the game server is not working correctly || 4.16
 +
|-
 +
| specialForceCharsetNegotiationOff || false || Workaround option to disable automatically setting the correct encoding, in case the game server is not working correctly || 4.16
 +
|-
 +
| specialForceMxpNegotiationOff || false || Workaround option to disable MXP, in case the game server is not working correctly || 4.16
 +
|-
 +
| caretShortcut || "none" || For visually-impaired players - set the key to switch between input line and main window (can be "none", "tab", "ctrltab", "f6") || 4.17
 +
|-
 +
| blankLinesBehaviour || "show" || For visually impaired players options for dealing with blank lines (can be "show", "hide", "replacewithspace") || 4.17
 +
|}
  
{{MudletVersion|4.15}}
+
;Returns
 +
* true if successful, or nil+msg if the option doesn't exist. Setting mapper options requires the mapper being open first.
  
 
;Example
 
;Example
 
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
---- Table Parameter Syntax ----
+
setConfig("mapRoomSize", 5)
 
 
-- Stop all playing music files for this profile associated with the API
 
stopMusic()
 
 
 
-- Stop playing the rugby mp3 by name
 
stopMusic({name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"})
 
  
-- Stop playing the unique sound identified as "rugby"
+
setConfig({mapRoomSize = 6, mapExitSize = 12})
stopMusic({
 
    name = nil  -- nil lines are optional, no need to use
 
    , key = "rugby" -- key
 
    , tag = nil  -- nil lines are optional, no need to use
 
})
 
 
</syntaxhighlight>
 
</syntaxhighlight>
<syntaxhighlight lang="lua">
 
---- Ordered Parameter Syntax of stopMusic([name][,key][,tag]) ----
 
  
-- Stop all playing music files for this profile associated with the API
+
==setMergeTables==
stopMusic()
+
;setMergeTables(module)
 +
:Makes Mudlet merge the table of the given GMCP or MSDP module instead of overwriting the data. This is useful if the game sends only partial updates which need combining for the full data. By default "Char.Status" is the only merged module.
  
-- Stop playing the rugby mp3 by name
+
;Parameters
stopMusic("167124__patricia-mcmillen__rugby-club-in-spain.mp3")
+
* ''module:''
 +
:Name(s) of the GMCP or MSDP module(s) that should be merged as a string - this will add it to the existing list.
  
-- Stop playing the unique sound identified as "rugby"
+
;Example
stopMusic(
+
<syntaxhighlight lang="lua">
    nil -- name
+
setMergeTables("Char.Skills", "Char.Vitals")
    , "rugby" -- key
 
    , nil -- tag
 
)
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==stopNamedEventHandler==
+
==setModuleInfo==
; success = stopNamedEventHandler(userName, handlerName)
+
;setModuleInfo(moduleName, info, value)
  
:Stops a named event handler with name handlerName and prevents it from firing any more. Information is stored so it can be resumed later if desired.
+
:Sets a specific meta info value for a module
  
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#resumeNamedEventHandler|resumeNamedEventHandler()]]
+
;Parameters
 +
* ''moduleName:''
 +
:Name of the module
 +
* ''info:''
 +
: specific info to set (for example "version")
 +
* ''value:''
 +
: specific value to set (for example "1.0")
  
{{MudletVersion|4.14}}
+
:See also: [[#getModuleInfo|getModuleInfo]], [[#setPackageInfo|getPackageInfo]]
 
 
;Parameters
 
* ''userName:''
 
: The user name the event handler was registered under.
 
* ''handlerName:''
 
: The name of the handler to stop. Same as used when you called [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]]
 
 
 
;Returns
 
* true if successful, false if it didn't exist or was already stopped
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
local stopped = stopNamedEventHandler("DemonVitals")
+
setModuleInfo("myModule", "version", "1.0")
if stopped then
 
  cecho("DemonVitals stopped!")
 
else
 
  cecho("DemonVitals doesn't exist or already stopped; either way it won't fire any more.")
 
end
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==stopSounds==
+
{{MudletVersion|4.12}}
;stopSounds(settings table)
+
 
:Stop all sounds (no filter), or sounds that meets a combination of filters (name, key, tag, and priority) intended to be paired with [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]].
+
==setModulePriority==
 +
;setModulePriority(moduleName, priority)
 +
 
 +
:Sets the module priority on a given module as a number - the module priority determines the order modules are loaded in, which can be helpful if you have ones dependent on each other. This can also be set from the module manager window.
 +
: Modules with priority <code>-1</code> will be loaded before scripts (Mudlet 4.11+).
  
{| class="wikitable"
+
: See also: [[#getModulePriority|getModulePriority()]]
! Required
 
! Key
 
! Value
 
! style="text-align:left;"| Purpose
 
|-
 
| style="text-align:center;"| No
 
| name
 
| <file name>
 
| style="text-align:left;"|
 
* Name of the media file.
 
|-
 
| style="text-align:center;" |No
 
| key
 
|<key>
 
| style="text-align:left;" |
 
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".
 
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.
 
|-
 
| style="text-align:center;"| No
 
| tag
 
| <tag>
 
| style="text-align:left;"|
 
* Helps categorize media.
 
|-
 
| style="text-align:center;" |No
 
| priority
 
| 1 to 100
 
| style="text-align:left;" |
 
*Halts the play of current or future played media files with a matching or lower priority.
 
|-
 
|}
 
  
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]
+
<syntaxhighlight lang="lua">
 +
setModulePriority("mudlet-mapper", 1)
 +
</syntaxhighlight>
 +
 
 +
==setPackageInfo==
 +
;setPackageInfo(packageName, info, value)
 +
 
 +
:Sets a specific meta info value for a package
 +
 
 +
;Parameters
 +
* ''packageName:''
 +
:Name of the module
 +
* ''info:''
 +
: specific info to set (for example "version")
 +
* ''value:''
 +
: specific value to set (for example "1.0")
  
{{MudletVersion|4.15}}
+
:See also: [[#getPackageInfo|getPackageInfo]], [[#setModuleInfo|setModuleInfo]]
  
 
;Example
 
;Example
 
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
---- Table Parameter Syntax ----
+
setPackageInfo("myPackage", "title", "This is my test package")
 +
</syntaxhighlight>
  
-- Stop all playing sound files for this profile associated with the API
+
{{MudletVersion|4.12}}
stopSounds()
 
  
-- Stop playing the cow sound
+
==setServerEncoding==
stopSounds({name = "cow.wav"})
+
;setServerEncoding(encoding)
 +
:Makes Mudlet use the specified [https://www.w3.org/International/questions/qa-what-is-encoding encoding] for communicating with the game.
  
-- Stop playing any sounds tagged as "animals" with a priority less than or equal to 50
+
;Parameters
---- This would not stop sounds tagged as "animals" greater than priority 50.  This is an "AND" and not an "OR".
+
* ''encoding:''
stopSounds({
+
: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>
 +
 
 +
==showNotification==
 +
;showNotification(title, [content], [expiryTimeInSeconds])
 +
 
 +
:Shows a native (system) notification.
 +
 
 +
{{MudletVersion|4.11}}
 +
 
 +
{{Note}} This might not work on all systems, this depends on the system.
 +
 
 +
;Parameters
 +
* ''title'' - plain text notification title
 +
* ''content'' - optional argument, plain text notification content, if omitted title argument will be used as content as well
 +
* ''expiryTimeInSeconds'' - optional argument, sets expiration time in seconds for notification, very often ignored by OS
 +
 
 +
<syntaxhighlight lang="lua">
 +
showNotification("Notification title", "Notification content", 5)
 +
</syntaxhighlight>
 +
 
 +
==spawn==
 +
;spawn(readFunction, processToSpawn[, ...arguments])
 +
 
 +
: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()''.
 +
 
 +
:This allows you to setup RPC communication with another process.
 +
 
 +
;Examples
 +
<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>
 +
<syntaxhighlight lang="lua">
 +
local f = spawn(display, "ls", "-la")
 +
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).
 +
* ''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''.
 +
* ''fileName (string)''
 +
:The log will be/is being written to the path/file name returned.
 +
* ''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
 +
 
 +
;Example
 +
<syntaxhighlight lang="lua">
 +
-- start logging
 +
local success, message, filename, code = startLogging(true)
 +
if code == 1 or code == -1 then print(f"Started logging to {filename}") end
 +
 
 +
-- stop logging
 +
startLogging(false)
 +
</syntaxhighlight>
 +
 
 +
==stopAllNamedEventHandlers==
 +
; stopAllNamedEventHandlers(userName)
 +
 
 +
:Stops all named event handlers and prevents them from firing any more. Information is retained and handlers can be resumed.
 +
 
 +
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#stopNamedEventHandler|stopNamedEventHandler()]], [[Manual:Lua_Functions#resumeNamedEventHandler|resumeNamedEventHandler()]]
 +
 
 +
{{MudletVersion|4.14}}
 +
 
 +
;Parameter
 +
* ''userName:''
 +
: The user name the event handler was registered under.
 +
 
 +
;Example
 +
<syntaxhighlight lang="lua">
 +
stopAllNamedEventHandlers() -- emergency stop situation, most likely.
 +
</syntaxhighlight>
 +
 
 +
==stopMusic==
 +
;stopMusic(settings table)
 +
:Stop all music (no filter), or music that meets a combination of filters (name, key, and tag) intended to be paired with [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]].
 +
 
 +
{| class="wikitable"
 +
! Required
 +
! Key
 +
! Value
 +
!Default
 +
! style="text-align:left;"| Purpose
 +
|-
 +
| style="text-align:center;"| No
 +
| name
 +
| <file name>
 +
|
 +
| style="text-align:left;"|
 +
* Name of the media file.
 +
|-
 +
| style="text-align:center;" |No
 +
| key
 +
|<key>
 +
|
 +
| style="text-align:left;" |
 +
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".
 +
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.
 +
|-
 +
| style="text-align:center;"| No
 +
| tag
 +
| <tag>
 +
|
 +
| style="text-align:left;"|
 +
* Helps categorize media.
 +
|-
 +
| style="text-align:center;"| No
 +
| fadeaway
 +
| true or false
 +
|false
 +
| style="text-align:left;" |
 +
* Decrease volume from the current position for a given duration, then stops the track.
 +
* Given duration is the lesser of the remaining track duration or the fadeout specified in playMusicFile().
 +
* If fadeout was not specified in playMusicFile(), then the optional fadeout parameter from stopMusic() or a default of 5000 milliseconds will be applied.
 +
|-
 +
| style="text-align:center;"| No
 +
| fadeout
 +
|
 +
|5000
 +
| style="text-align:left;" |
 +
* Default duration in milliseconds to decrease volume to the end of the track.
 +
* Only used if fadeout was not defined in playMusicFile().
 +
|-
 +
|}
 +
 
 +
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#getPlayingMusic|getPlayingMusic()]], [[Manual:Miscellaneous_Functions#getPlayingSounds|getPlayingSounds()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]
 +
 
 +
{{MudletVersion|4.15}}
 +
 
 +
;Example
 +
 
 +
<syntaxhighlight lang="lua">
 +
---- Table Parameter Syntax ----
 +
 
 +
-- Stop all playing music files for this profile associated with the API
 +
stopMusic()
 +
 
 +
-- Stop playing the rugby mp3 by name
 +
stopMusic({name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"})
 +
 
 +
-- Stop playing the unique sound identified as "rugby"
 +
stopMusic({
 +
    name = nil  -- nil lines are optional, no need to use
 +
    , key = "rugby" -- key
 +
    , tag = nil  -- nil lines are optional, no need to use
 +
})
 +
 
 +
-- Decrease volume for 5 seconds and then stop all playing music files for this profile associated with the API
 +
stopMusic({
 +
    fadeaway = true
 +
})
 +
 
 +
-- Decrease volume for 10 seconds (or apply the duration of fadeout set in playMusicFile()) and then stop all playing music files for this profile associated with the API
 +
stopMusic({
 +
    fadeaway = true
 +
    , fadeout = 10000
 +
})
 +
 
 +
-- Decrease volume for 5 seconds and then stop all the unique "rugby" music for this profile associated with the API
 +
stopMusic({
 +
    key = "rugby"
 +
    , fadeaway = true
 +
})
 +
</syntaxhighlight>
 +
<syntaxhighlight lang="lua">
 +
---- Ordered Parameter Syntax of stopMusic([name][,key][,tag][,fadeaway][,fadeout]) ----
 +
 
 +
-- Stop all playing music files for this profile associated with the API
 +
stopMusic()
 +
 
 +
-- Stop playing the rugby mp3 by name
 +
stopMusic("167124__patricia-mcmillen__rugby-club-in-spain.mp3")
 +
 
 +
-- Stop playing the unique sound identified as "rugby"
 +
stopMusic(
 +
    nil -- name
 +
    , "rugby" -- key
 +
    , nil -- tag
 +
)
 +
 
 +
-- Decrease the volume for 10 seconds then stop playing the unique sound identified as "rugby"
 +
stopMusic(
 +
    nil -- name
 +
    , "rugby" -- key
 +
    , nil -- tag
 +
    , true -- fadeaway
 +
    , 10000 -- fadeout
 +
)
 +
</syntaxhighlight>
 +
 
 +
==stopNamedEventHandler==
 +
; success = stopNamedEventHandler(userName, handlerName)
 +
 
 +
:Stops a named event handler with name handlerName and prevents it from firing any more. Information is stored so it can be resumed later if desired.
 +
 
 +
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#resumeNamedEventHandler|resumeNamedEventHandler()]]
 +
 
 +
{{MudletVersion|4.14}}
 +
 
 +
;Parameters
 +
* ''userName:''
 +
: The user name the event handler was registered under.
 +
* ''handlerName:''
 +
: The name of the handler to stop. Same as used when you called [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]]
 +
 
 +
;Returns
 +
* true if successful, false if it didn't exist or was already stopped
 +
 
 +
;Example
 +
<syntaxhighlight lang="lua">
 +
local stopped = stopNamedEventHandler("DemonVitals")
 +
if stopped then
 +
  cecho("DemonVitals stopped!")
 +
else
 +
  cecho("DemonVitals doesn't exist or already stopped; either way it won't fire any more.")
 +
end
 +
</syntaxhighlight>
 +
 
 +
==stopSounds==
 +
;stopSounds(settings table)
 +
:Stop all sounds (no filter), or sounds that meets a combination of filters (name, key, tag, and priority) intended to be paired with [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]].
 +
 
 +
{| class="wikitable"
 +
! Required
 +
! Key
 +
! Value
 +
! Default
 +
! style="text-align:left;"| Purpose
 +
|-
 +
| style="text-align:center;"| No
 +
| name
 +
| <file name>
 +
|
 +
| style="text-align:left;"|
 +
* Name of the media file.
 +
|-
 +
| style="text-align:center;" |No
 +
| key
 +
|<key>
 +
|
 +
| style="text-align:left;" |
 +
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".
 +
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.
 +
|-
 +
| style="text-align:center;"| No
 +
| tag
 +
| <tag>
 +
|
 +
| style="text-align:left;"|
 +
* Helps categorize media.
 +
|-
 +
| style="text-align:center;" |No
 +
| priority
 +
| 1 to 100
 +
|
 +
| style="text-align:left;" |
 +
*Halts the play of current or future played media files with a matching or lower priority.
 +
|-
 +
| style="text-align:center;"| No
 +
| fadeaway
 +
| true or false
 +
|false
 +
| style="text-align:left;" |
 +
* Decrease volume from the current position for a given duration, then stops the track.
 +
* Given duration is the lesser of the remaining track duration or the fadeout specified in playSoundFile().
 +
* If fadeout was not specified in playSoundFile(), then the optional fadeout parameter from stopSounds() or a default of 5000 milliseconds will be applied.
 +
|-
 +
| style="text-align:center;"| No
 +
| fadeout
 +
|
 +
|5000
 +
| style="text-align:left;" |
 +
* Default duration in milliseconds to decrease volume to the end of the track.
 +
* Only used if fadeout was not defined in playSoundFile().
 +
|-
 +
|}
 +
 
 +
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#getPlayingMusic|getPlayingMusic()]], [[Manual:Miscellaneous_Functions#getPlayingSounds|getPlayingSounds()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]
 +
 
 +
{{MudletVersion|4.15}}
 +
 
 +
;Example
 +
 
 +
<syntaxhighlight lang="lua">
 +
---- Table Parameter Syntax ----
 +
 
 +
-- Stop all playing sound files for this profile associated with the API
 +
stopSounds()
 +
 
 +
-- Stop playing the cow sound
 +
stopSounds({name = "cow.wav"})
 +
 
 +
-- Stop playing any sounds tagged as "animals" with a priority less than or equal to 50
 +
---- This would not stop sounds tagged as "animals" greater than priority 50.  This is an "AND" and not an "OR".
 +
stopSounds({
 
     name = nil -- nil lines are optional, no need to use
 
     name = nil -- nil lines are optional, no need to use
     , key = nil -- nil lines are optional, no need to use
+
     , key = nil -- nil lines are optional, no need to use
     , tag = "animals"
+
     , tag = "animals"
     , priority = 50
+
     , priority = 50
})
+
})
</syntaxhighlight>
+
 
<syntaxhighlight lang="lua">
+
-- Decrease volume for 5 seconds and then stop all playing sound files for this profile associated with the API
---- Ordered Parameter Syntax of stopSounds([name][,key][,tag][,priority]) ----
+
stopSounds({
 
+
    fadeaway = true
-- Stop all playing sound files for this profile associated with the API
+
})
stopSounds()
+
 
 
+
-- Decrease volume for 10 seconds (or apply the duration of fadeout set in playSoundFile()) and then stop all playing music files for this profile associated with the API
-- Stop playing the cow sound
+
stopSounds({
stopSounds("cow.wav")
+
    fadeaway = true
 
+
    , fadeout = 10000
-- Stop playing any sounds tagged as "animals" with a priority less than or equal to 50
+
})
---- This would not stop sounds tagged as "animals" greater than priority 50.  This is an "AND" and not an "OR".
+
 
stopSounds(
+
-- Decrease volume for 3 seconds and then stop all the tagged "animals" music for this profile associated with the API
     nil -- name
+
stopSounds({
     , nil -- key
+
    tag = "animals"
     , "animals" -- tag
+
    , fadeaway = true
     , 50 -- priority
+
    , fadeout = 3000
 +
})
 +
</syntaxhighlight>
 +
<syntaxhighlight lang="lua">
 +
---- Ordered Parameter Syntax of stopSounds([name][,key][,tag][,priority][,fadeaway][,fadeout]) ----
 +
 
 +
-- Stop all playing sound files for this profile associated with the API
 +
stopSounds()
 +
 
 +
-- Stop playing the cow sound
 +
stopSounds("cow.wav")
 +
 
 +
-- Stop playing any sounds tagged as "animals" with a priority less than or equal to 50
 +
---- This would not stop sounds tagged as "animals" greater than priority 50.  This is an "AND" and not an "OR".
 +
stopSounds(
 +
     nil -- name
 +
     , nil -- key
 +
     , "animals" -- tag
 +
     , 50 -- priority
 +
)
 +
 
 +
-- Decrease the volume for 7 seconds and then stop playing sounds
 +
stopSounds(
 +
    nil -- name
 +
    , nil -- key
 +
    , nil -- tag
 +
    , nil -- priority
 +
    , true -- fadeaway
 +
    , 7000 -- fadeout
 
)
 
)
</syntaxhighlight>
 
 
==stopSounds==
 
;stopSounds()
 
 
:Stops all currently playing sounds.
 
 
{{MudletVersion|3.0.}}
 
 
:See also: [[#playSoundFile|playSoundFile()]]
 
 
;Example
 
<syntaxhighlight lang="lua">
 
stopSounds()
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  

Latest revision as of 23:53, 30 October 2024

Miscellaneous Functions

addFileWatch

addFileWatch(path)
Adds file watch on directory or file. Every change in that file (or directory) will raise sysPathChanged event.
See also: removeFileWatch()
Mudlet VersionAvailable in Mudlet4.12+
Example
herbs = {}
local herbsPath = getMudletHomeDir() .. "/herbs.lua"
function herbsChangedHandler(_, path)
  if path == herbsPath then
    table.load(herbsPath, herbs)
    removeFileWatch(herbsPath)
  end
end

addFileWatch(herbsPath)
registerAnonymousEventHandler("sysPathChanged", "herbsChangedHandler")

addSupportedTelnetOption

addSupportedTelnetOption(option)
Adds a telnet option, which when queried by a game 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
<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)

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.
Mudlet VersionAvailable in Mudlet3.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
-- flash indefinitely until Mudlet is open
alert()

-- flash for just 3 seconds
alert(3)

cfeedTriggers

cfeedTriggers(text)
Like feedTriggers, but you can add color information using color names, similar to cecho.
Parameters
  • text: The string to feed to the trigger engine. Include colors by name as black,red,green,yellow,blue,magenta,cyan,white and light_* versions of same. You can also use a number to get the ansi color corresponding to that number.
See also: feedTriggers
Mudlet VersionAvailable in Mudlet4.10+
Example
cfeedTriggers("<green:red>green on red<r> reset <124:100> foreground of ANSI124 and background of ANSI100<r>\n")

closeMudlet

closeMudlet()
Closes Mudlet and all profiles immediately.
See also: saveProfile()

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

Mudlet VersionAvailable in Mudlet3.1+
Example
closeMudlet()

deleteAllNamedEventHandlers

deleteAllNamedEventHandlers(userName)
Deletes all named event handlers for userName and prevents them from firing any more. Information is deleted and cannot be retrieved.
See also
registerNamedEventHandler(), stopNamedEventHandler()
Mudlet VersionAvailable in Mudlet4.14+
Parameters
  • userName:
The user name the event handler was registered under.
Example
deleteAllNamedEventHandlers("Demonnic") -- emergency stop or debugging situation, most likely.

deleteNamedEventHandler

success = deleteNamedEventHandler(userName, handlerName)
Deletes a named event handler with name handlerName and prevents it from firing any more. Information is deleted and cannot be retrieved.
See also
registerNamedEventHandler(), stopNamedEventHandler()
Mudlet VersionAvailable in Mudlet4.14+
Parameters
  • userName:
The user name the event handler was registered under.
  • handlerName:
The name of the handler to stop. Same as used when you called registerNamedEventHandler()
Returns
  • true if successful, false if it didn't exist
Example
local deleted = deleteNamedEventHandler("Demonnic", "Vitals")
if deleted then
  cecho("Vitals deleted forever!!")
else
  cecho("Vitals doesn't exist and so could not be deleted.")
end

denyCurrentSend

denyCurrentSend()
Cancels a send() or user-entered command, but only if used within a sysDataSendRequest event.
Example
-- 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")

dfeedTriggers

dfeedTriggers(str)
Like feedTriggers, but you can add color information using <r,g,b>, similar to decho.
Parameters
  • str: The string to feed to the trigger engine. Include color information inside tags like decho.
See also
cfeedTriggers, decho
Mudlet VersionAvailable in Mudlet4.11+
Example
dfeedTriggers("<0,128,0:128,0,0>green on red<r> reset\n")

disableModuleSync

disableModuleSync(name)
Stops syncing the given module.
Parameter
  • name: name of the module.
See also: enableModuleSync(), getModuleSync()
Mudlet VersionAvailable in Mudlet4.8+

enableModuleSync

enableModuleSync(name)
Enables the sync for the given module name - any changes done to it will be saved to disk and if the module is installed in any other profile(s), it'll be updated in them as well on profile save.
Parameter
  • name: name of the module to enable sync on.
See also: disableModuleSync(), getModuleSync()
Mudlet VersionAvailable in Mudlet4.8+

expandAlias

expandAlias(command, [echoBackToBuffer])
Runs the command as if it was from the command line - so aliases are checked and if none match, it's sent to the game unchanged.
Parameters
  • command
Text of the command you want to send to the game. Will be checked for aliases.
  • echoBackToBuffer
(optional) If false, the command will not be echoed back in your buffer. Defaults to true if omitted.

Note Note: Using expandAlias is not recommended anymore as it is not very robust and may lead to problems down the road. The recommendation is to use lua functions instead. See Manual:Functions_vs_expandAlias for details and examples.

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

Note Note: Since Mudlet 3.17.1 the optional second argument to echo the command on screen will be ineffective whilst the game server has negotiated the telnet ECHO option to provide the echoing of text we send to him.

Example
expandAlias("t rat")

-- don't echo the command
expandAlias("t rat", false)

feedTriggers

feedTriggers(text[, dataIsUtf8Encoded = true])
This function will have Mudlet parse the given text as if it came from the game - one great application is trigger testing. The built-in `echo alias provides this functionality as well.
Parameters
  • text:
string which is sent to the trigger processing system almost as if it came from the game server. This string must be byte encoded in a manner to match the currently selected Server Encoding.
  • dataIsUtf8Encoded (available in Mudlet 4.2+):
Set this to false, if you need pre-Mudlet 4.0 behavior. Most players won't need this.
(Before Mudlet 4.0 the text had to be encoded directly in whatever encoding the setting in the preferences was set to.
(Encoding could involve using the Lua string character escaping mechanism of \ and a base 10 number for character codes from \1 up to \255 at maximum)
Since Mudlet 4.0 it is assumed that the text is UTF-8 encoded. It will then be automatically converted to the currently selected game server encoding.
Preventing the automatic conversion can be useful to Mudlet developers testing things, or possibly to those who are creating handlers for Telnet protocols within the Lua subsystem, who need to avoid the transcoding of individual protocol bytes, when they might otherwise be seen as extended ASCII characters.)
Returns (available in Mudlet 4.2+)
  • true on success, nil and an error message if the text contains characters that cannot be conveyed by the current Game Server encoding.

Note Note: It is important to ensure that in Mudlet 4.0.0 and beyond the text data only contains characters that can be encoded in the current Game Server encoding, from 4.2.0 the content is checked that it can successfully be converted from the UTF-8 that the Mudlet Lua subsystem uses internally into that particular encoding and if it cannot the function call will fail and not pass any of the data, this will be significant if the text component contains any characters that are not plain ASCII.

Example
-- 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 games. 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")

getCharacterName

getCharacterName()
Returns the name entered into the "Character name" field on the Connection Preferences form. Can be used to find out the name that might need to be handled specially in scripts or anything that needs to be personalized to the player. If there is nothing set in that entry will return an empty string.
See also: getProfileName()
Mudlet VersionAvailable in Mudlet4.16+
Example
-- cast glamor on yourself

send("cast 'glamor' " .. getCharacterName())

getConfig

getConfig([option])
Returns configuration options similar to those that can be set with setConfig. One could use this to decide if a script should notify the user of suggested changes.

See also: setConfig()

Mudlet VersionAvailable in Mudlet4.17+
Parameters
  • option:
Particular option to retrieve - see list below for available ones. This may be a string or an array of strings.
General options
Option Description Available in Mudlet
enableGMCP Enable GMCP 4.17
enableMSDP Enable MSDP 4.17
enableMSSP Enable MSSP 4.17
enableMSP Enable MSP 4.17
Input line
Option Description Available in Mudlet
inputLineStrictUnixEndings Workaround option to use strict UNIX line endings for sending commands 4.17
Main display
Option Description Available in Mudlet
fixUnnecessaryLinebreaks Remove extra linebreaks from output (mostly for IRE servers) 4.17
Mapper options
Option Description Available in Mudlet
mapRoomSize Size of rooms on map 4.17
mapExitSize Size of exits on map 4.17
mapRoundRooms Draw rooms round or square 4.17
showRoomIdsOnMap Show room IDs on all rooms 4.17
show3dMapView Show map as 3D 4.17
mapperPanelVisible Map controls at the bottom 4.17
mapShowRoomBorders Draw a thin border for every room 4.17
Special options
Option Description Available in Mudlet
specialForceCompressionOff Workaround option to disable MCCP compression, in case the game server is not working correctly 4.17
specialForceGAOff Workaround option to disable Telnet Go-Ahead, in case the game server is not working correctly 4.17
specialForceCharsetNegotiationOff Workaround option to disable automatically setting the correct encoding, in case the game server is not working correctly 4.17
specialForceMxpNegotiationOff Workaround option to disable MXP, in case the game server is not working correctly 4.17
caretShortcut For visually-impaired players - get the key to switch between input line and main window (can be "none", "tab", "ctrltab", "f6") 4.17
blankLinesBehaviour For visually impaired players options for dealing with blank lines (can be "show", "hide", "replacewithspace") 4.17
Returns
  • It returns a table of options or the value of a single option requested. They are only the configuration options, for example "enableGMCP" means that the "Enable GMCP" box is checked and does not mean that it has been negotiated with the server.
Example
getConfig()

-- Suggest enabling GMCP if it is unchecked
if not getConfig("enableGMCP") then
  echo("\nMy script works best with GMCP enabled. You may ")
  cechoLink("<red>click here", function() setConfig("enableGMCP",true) echo("GMCP enabled\n") end, "Enable GMCP", true)
  echo(" to enable it.\n")
end

getModulePath

path = getModulePath(module name)
Returns the location of a module on the disk. If the given name does not correspond to an installed module, it'll return nil
See also: installModule()
Mudlet VersionAvailable in Mudlet3.0+
Example
getModulePath("mudlet-mapper")

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.
Modules with priority -1 will be loaded before scripts (Mudlet 4.11+).
See also: setModulePriority()
Example
getModulePriority("mudlet-mapper")

getModules

getModules()
Returns installed modules as table.
See also: getPackages
Mudlet VersionAvailable in Mudlet4.12+
Example
--Check if the module myTabChat is installed and if it isn't install it and enable sync on it
if not table.contains(getModules(),"myTabChat") then
  installModule(getMudletHomeDir().."/modules/myTabChat.xml")
  enableModuleSync("myTabChat")
end

getModuleInfo

getModuleInfo(moduleName, [info])
Returns table with meta information for a package
Parameters
  • moduleName:
Name of the package
  • info:
(optional) specific info wanted to get, if not given all available meta-info is returned
See also: getPackageInfo, setModuleInfo
Example
getModuleInfo("myModule","author")
Mudlet VersionAvailable in Mudlet4.12+

getModuleSync

getModuleSync(name)
returns false if module sync is not active, true if it is active and nil if module is not found.
Parameter
  • name: name of the module
See also: enableModuleSync(), disableModuleSync()
Mudlet VersionAvailable in Mudlet4.8+

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.

Note Note: intentionally uses forward slashes / as separators on Windows since stylesheets require them.

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

getMudletInfo

getMudletInfo()
Prints debugging information about the Mudlet that you're running - this can come in handy for diagnostics.

Don't use this command in your scripts to find out if certain features are supported in Mudlet - there are better functions available for this.

Mudlet VersionAvailable in Mudlet4.8+
Example
getMudletInfo()

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 existence of the function itself. Otherwise, checking for the version can come in handy if you'd like to test for a broken function or so on.

See also: mudletOlderThan()

Mudlet VersionAvailable in Mudlet3.0+
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
-- 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
-- but mudletOlderThan() is much better for this:
if mudletOlderThan(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

getNewIDManager

getNewIDManager()
Returns an IDManager object, for manager your own set of named events and timers isolated from the rest of the profile.
See also
registerNamedEventHandler(), registerNamedTimer()
Mudlet VersionAvailable in Mudlet4.14+

Note Note: Full IDManager usage can be found at IDManager

Returns
  • an IDManager for managing your own named events and timers
Example
demonnic = demonnic or {}
demonnic.IDManager = getNewIDManager()
local idm = demonnic.IDManager
-- assumes you have defined demonnic.vitalsUpdate and demonnic.balanceChecker as functions
idm:registerEvent("DemonVitals", "gmcp.Char.Vitals", demonnic.vitalsUpdate)
idm:registerTimer("Balance Check", 1, demonnic.balanceChecker)
idm:stopEvent("DemonVitals")

getNamedEventHandlers

handlers = getNamedEventHandlers(userName)
Returns a list of all userName's named event handlers' names as a table.
See also
registerNamedEventHandler()
Mudlet VersionAvailable in Mudlet4.14+
Parameters
  • userName:
The user name the event handler was registered under.
Returns
  • a table of handler names. { "DemonVitals", "DemonInv" } for example. {} if none are registered
Example
  local handlers = getNamedEventHandlers()
  display(handlers)
  -- {}
  registerNamedEventHandler("Test1", "testEvent", "testFunction")
  registerNamedEventHandler("Test2", "someOtherEvent", myHandlerFunction)
  handlers = getNamedEventHandlers()
  display(handlers)
  -- { "Test1", "Test2" }

getOS

getOS()
Returns the name of the Operating System (OS). Useful for applying particular scripts only under particular operating systems, such as applying a stylesheet only when the OS is Windows.
Returned text will be one of these: "windows", "mac", "linux", as well as "cygwin", "hurd", "freebsd", "kfreebsd", "openbsd", "netbsd", "bsd4", "unix" or "unknown" otherwise.
Additionally returns the version of the OS, and if using Linux, the distribution in use (as of Mudlet 4.12+).
Example
display(getOS())

if getOS() == "windows" then
  echo("\nWindows OS detected.\n")
else
  echo("\nDetected Operating system is NOT windows.\n")
end

if mudlet.supports.osVersion then
  local os, osversion = getOS()
  print(f"Running {os} {osversion}")
end

getPackages

getPackages()
Returns installed packages as table.
See also: getModules
Mudlet VersionAvailable in Mudlet4.12+
Example
--Check if the generic_mapper package is installed and if so uninstall it
if table.contains(getPackages(),"generic_mapper") then
  uninstallPackage("generic_mapper")
end

getPackageInfo

getPackageInfo(packageName, [info])
Returns table with meta information for a package
Parameters
  • packageName:
Name of the package
  • info:
(optional) specific information to retrieve which can be one of; author, created, description, icon, mpackage (package name), title or version. If not given all available meta-info is returned.
See also: getModuleInfo, setPackageInfo
Example
getPackageInfo("myPackage", "version")
Mudlet VersionAvailable in Mudlet4.12+

getPlayingMusic

getPlayingMusic(settings table)
List all playing music (no filter), or playing music that meets a combination of filters (name, key, and tag) intended to be paired with playMusicFile().
Required Key Value Default Purpose
No name <file name>
  • Name of the media file.
No key <key>
  • Uniquely identifies media files with a "key" that is bound to their "name" or "url".
No tag <tag>
  • Helps categorize media.

See also: loadMusicFile(), loadSoundFile(), playMusicFile(), playSoundFile(), getPlayingSounds(), stopSounds(), purgeMediaCache(), Mud Client Media Protocol

Mudlet VersionAvailable in Mudlet4.18+
Example
---- Table Parameter Syntax ----

-- List all playing music files for this profile associated with the API
getPlayingMusic()

-- List all playing music matching the rugby mp3 name
getPlayingMusic({name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"})

-- List all playing music matching the unique key of "rugby"
getPlayingMusic({
    name = nil  -- nil lines are optional, no need to use
    , key = "rugby" -- key
    , tag = nil  -- nil lines are optional, no need to use
})
---- Ordered Parameter Syntax of getPlayingMusic([name][,key][,tag]) ----

-- List all playing music files for this profile associated with the API
getPlayingMusic()

-- List all playing music matching the rugby mp3 name
getPlayingMusic("167124__patricia-mcmillen__rugby-club-in-spain.mp3")

-- List all playing music matching the unique key of "rugby"
getPlayingMusic(
    nil -- name
    , "rugby" -- key
    , nil -- tag
)

getPlayingSounds

getPlayingSounds(settings table)
List all playing sounds (no filter), or playing sounds that meets a combination of filters (name, key, tag, and priority) intended to be paired with playSoundFile().
Required Key Value Default Purpose
No name <file name>
  • Name of the media file.
No key <key>
  • Uniquely identifies media files with a "key" that is bound to their "name" or "url".
No tag <tag>
  • Helps categorize media.
No priority <priority>
  • Matches media files with equal or lower priority.

See also: loadMusicFile(), loadSoundFile(), playMusicFile(), playSoundFile(), getPlayingMusic(), stopSounds(), purgeMediaCache(), Mud Client Media Protocol

Mudlet VersionAvailable in Mudlet4.18+
Example
---- Table Parameter Syntax ----

-- List all playing sounds for this profile associated with the API
getPlayingSounds()

-- List all playing sounds matching the rugby mp3 name
getPlayingSounds({name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"})

-- List the playing sound matching the unique key of "rugby"
getPlayingSounds({
    name = nil  -- nil lines are optional, no need to use
    , key = "rugby" -- key
    , tag = nil  -- nil lines are optional, no need to use
})
---- Ordered Parameter Syntax of getPlayingSounds([name][,key][,tag][,priority]) ----

-- List all playing sounds for this profile associated with the API
getPlayingSounds()

-- List all playing sounds matching the rugby mp3 name
getPlayingSounds("167124__patricia-mcmillen__rugby-club-in-spain.mp3")

-- List the playing sound matching the unique key of "rugby"
getPlayingSounds(
    nil -- name
    , "rugby" -- key
    , nil -- tag
    , nil -- priority
)

getProfileName

getProfileName()
Returns the name of the profile. Useful when combined with raiseGlobalEvent() to know which profile a global event came from.
Mudlet VersionAvailable in Mudlet3.1+
Example
-- if connected to the Achaea profile, will print Achaea to the main console
echo(getProfileName())

getCommandSeparator

getCommandSeparator()
Returns the command separator in use by the profile.
Mudlet VersionAvailable in Mudlet3.18+
Example
-- if your command separator is ;;, the following would send("do thing 1;;do thing 2"). 
-- This way you can determine what it is set to and use that and share this script with 
-- someone who has changed their command separator.
-- Note: This is not really the preferred way to send this, using sendAll("do thing 1", "do thing 2") is,
--       but this illustates the use case.
local s = getCommandSeparator()
expandAlias("do thing 1" .. s .. "do thing 2")

getServerEncoding

getServerEncoding()
Returns the current server data encoding in use.
See also: setServerEncoding(), getServerEncodingsList()
Example
getServerEncoding()

getServerEncodingsList

getServerEncodingsList()
Returns an indexed list of the server 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 encodings in Mudlet for the list of which encodings are available in which Mudlet version.
See also: setServerEncoding(), getServerEncoding()
Example
-- check if UTF-8 is available:
if table.contains(getServerEncodingsList(), "UTF-8") then
  print("UTF-8 is available!")
end

getWindowsCodepage

getWindowsCodepage()
Returns the current codepage of your Windows system.
Mudlet VersionAvailable in Mudlet3.22+

Note Note: This function only works on Windows - It is only needed internally in Mudlet to enable Lua to work with non-ASCII usernames (e.g. Iksiński, Jäger) for the purposes of IO. Linux and macOS work fine with with these out of the box.

Example
print(getWindowsCodepage())

hfeedTriggers

hfeedTriggers(str)
Like feedTriggers, but you can add color information using #RRGGBB in hex, similar to hecho.
Parameters
  • str: The string to feed to the trigger engine. Include color information in the same manner as hecho.
See also: dfeedTriggers
See also: hecho
Mudlet VersionAvailable in Mudlet4.11+
Example
hfeedTriggers("#008000,800000green on red#r reset\n")


holdingModifiers

holdingModifiers(number)
Returns true or false depending on whether a particular modifier key is being held at the time this function is run. Can be paired with a number of actions, including clicking on a label.
Parameters
  • number: A number corresponding to a specific modifier key.
Modifiers

Modifier values can be found by accessing the global `mudlet.keymodifier` table, which, as of 4.18, provides for the following:

{
  Alt = 134217728,
  Control = 67108864,
  GroupSwitch = 1073741824,
  Keypad = 536870912,
  Meta = 268435456,
  None = 0,
  Shift = 33554432
}
Example
local MyLabel = MyLabel or Geyser.Label:new({
  name = "MyLabel",
  x = 0,y = 0,
  height = 200, width = 100,
  message = "This is my label"
})

function clickity(...)
  display(...)
  
  for k, v in spairs(mudlet.keymodifier) do
    print(f[[Holding down {k} : {holdingModifiers(v)}]])
  end
end

setLabelClickCallback("MyLabel", "clickity")

-- Result:
--
-- Holding down Alt : true
-- Holding down Control : false
-- Holding down GroupSwitch : false
-- Holding down Keypad : false
-- Holding down Meta : false
-- Holding down None : false
-- Holding down Shift : false
Notes

You may only test for one modifier key being held. If more than one modifier key is held down, then all results will be false.

installModule

installModule(location)
Installs a Mudlet XML, zip, or mpackage as a module.
Parameters
  • location:
Exact location of the file install.
See also: uninstallModule(), Event: sysLuaInstallModule, setModulePriority()
Example
installModule([[C:\Documents and Settings\bub\Desktop\myalias.xml]])

installPackage

installPackage(location or url)
Installs a Mudlet XML or package. Since Mudlet 4.11+ returns true if it worked, or false.
Parameters
  • location:
Exact location of the xml or package to install.

Since Mudlet 4.11+ it is possible to pass download link to a package (must start with http or https and end with .xml, .zip, .mpackage or .trigger)

See also: uninstallPackage()
Example
installPackage([[C:\Documents and Settings\bub\Desktop\myalias.xml]])
installPackage([[https://github.com/Mudlet/Mudlet/blob/development/src/run-lua-code-v4.xml]])

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 function.
See also: registerAnonymousEventHandler
Mudlet VersionAvailable in Mudlet3.5+
Example
-- registers an event handler that prints the first 5 GMCP events and then terminates itself

local counter = 0
local handlerId = registerAnonymousEventHandler("gmcp", function(_, origEvent)
  print(origEvent)
  counter = counter + 1
  if counter == 5 then
    killAnonymousEventHandler(handlerId)
  end
end)

loadMusicFile

loadMusicFile(settings table) or loadMusicFile(name, [url])
Loads music files from the Internet or the local file system to the "media" folder of the profile for later use with playMusicFile() and stopMusic(). Although files could be loaded directly at playing time from playMusicFile(), loadMusicFile() provides the advantage of loading files in advance.
Required Key Value Purpose
Yes name <file name>
  • Name of the media file.
  • May contain directory information (i.e. weather/lightning.wav).
  • May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")
  • May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")
Maybe url <url>
  • Resource location where the media file may be downloaded.
  • Only required if file to load is not part of the profile or on the local file system.

See also: loadSoundFile(), playMusicFile(), playSoundFile(), stopMusic(), stopSounds(), purgeMediaCache(), Mud Client Media Protocol

Mudlet VersionAvailable in Mudlet4.15+
Example
---- Table Parameter Syntax ----

-- Download from the Internet
loadMusicFile({
    name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"
    , url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"
})

-- OR download from the profile
loadMusicFile({name = getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3"})

-- OR download from the local file system
loadMusicFile({name = "C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3"})
---- Ordered Parameter Syntax of loadMusicFile(name[, url]) ----

-- Download from the Internet
loadMusicFile(
    "167124__patricia-mcmillen__rugby-club-in-spain.mp3"
    , "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"
)

-- OR download from the profile
loadMusicFile(getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3")

-- OR download from the local file system
loadMusicFile("C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3")

loadSoundFile

loadSoundFile(settings table) or loadSoundFile(name, [url])
Loads sound files from the Internet or the local file system to the "media" folder of the profile for later use with playSoundFile() and stopSounds(). Although files could be loaded directly at playing time from playSoundFile(), loadSoundFile() provides the advantage of loading files in advance.
Required Key Value Purpose
Yes name <file name>
  • Name of the media file.
  • May contain directory information (i.e. weather/lightning.wav).
  • May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")
  • May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")
Maybe url <url>
  • Resource location where the media file may be downloaded.
  • Only required if file to load is not part of the profile or on the local file system.

See also: loadMusicFile(), playMusicFile(), playSoundFile(), stopMusic(), stopSounds(), purgeMediaCache(), Mud Client Media Protocol

Mudlet VersionAvailable in Mudlet4.15+
Example
---- Table Parameter Syntax ----

-- Download from the Internet
loadSoundFile({
    name = "cow.wav"
    , url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"
})

-- OR download from the profile
loadSoundFile({name = getMudletHomeDir().. "/cow.wav"})

-- OR download from the local file system
loadSoundFile({name = "C:/Users/Tamarindo/Documents/cow.wav"})
---- Ordered Parameter Syntax of loadSoundFile(name[,url]) ----

-- Download from the Internet
loadSoundFile("cow.wav", "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/")

-- OR download from the profile
loadSoundFile(getMudletHomeDir().. "/cow.wav")

-- OR download from the local file system
loadSoundFile("C:/Users/Tamarindo/Documents/cow.wav")

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 if mudletfunction then - it'll be much more readable and reliable.

See also: getMudletVersion()

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
-- 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, 1, 3) 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.supports.coroutines then return end

openWebPage

openWebPage(URL)
Opens the browser to the given webpage.
Parameters
  • URL:
Exact URL to open.
Example
openWebPage("http://google.com")

Note: This function can be used to open a local file or file folder as well by using "file:///" and the file path instead of "http://".

Example
openWebPage("file:///"..getMudletHomeDir().."file.txt")

playMusicFile

playMusicFile(settings table)
Plays music files from the Internet or the local file system to the "media" folder of the profile for later use with stopMusic().
Required Key Value Default Purpose
Yes name <file name>  
  • Name of the media file.
  • May contain directory information (i.e. weather/lightning.wav).
  • May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")
  • May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")
  • Wildcards * and ? may be used within the name to randomize media files selection.
No volume 1 to 100 50
  • Relative to the volume set on the player's client.
No fadein <msec>
  • Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.
  • Start position: Start of media.
  • End position: Start of media plus the number of milliseconds (msec) specified.
  • 1000 milliseconds = 1 second.
No fadeout <msec>
  • Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.
  • Start position: End of the media minus the number of milliseconds (msec) specified.
  • End position: End of the media.
  • 1000 milliseconds = 1 second.
No start <msec> 0
  • Begin play at the specified position in milliseconds.
No finish <msec>
  • End play at the specified position in milliseconds.
No loops -1, or >= 1 1
  • Number of iterations that the media plays.
  • A value of -1 allows the media to loop indefinitely.
No key <key>  
  • Uniquely identifies media files with a "key" that is bound to their "name" or "url".
  • Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.
No tag <tag>  
  • Helps categorize media.
No continue true or false true
  • Continues playing matching new music files when true.
  • Restarts matching new music files when false.
Maybe url <url>  
  • Resource location where the media file may be downloaded.
  • Only required if the file is to be downloaded remotely.

See also: loadMusicFile(), loadSoundFile(), playSoundFile(), getPlayingMusic(), getPlayingSounds(), stopMusic(), stopSounds(), purgeMediaCache(), Mud Client Media Protocol

Note Note: on Windows and certain files are not playing? Try installing the 3rd party K-lite codec pack.

Mudlet VersionAvailable in Mudlet4.15+
Example
---- Table Parameter Syntax ----

-- Play a music file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)
playMusicFile({
    name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"
})

-- OR copy once from the game's profile, and play a music file stored in the profile's media directory
---- [volume] of 75 (1 to 100)
playMusicFile({
    name = getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3"
    , volume = 75
})

-- OR copy once from the local file system, and play a music file stored in the profile's media directory
---- [volume] of 75 (1 to 100)
playMusicFile({
    name = "C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3"
    , volume = 75
})

-- OR download once from the Internet, and play music stored in the profile's media directory
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 20 seconds
---- [fadeout] and decrease the volume from default volume to one, 53 seconds from the end of the music
---- [start] 10 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)
---- [finish] 110 seconds from the track start (fadeout scales its volume decrease over a shorter duration, too)
---- [key] reference of "rugby" for stopping this unique music later
---- [tag] reference of "ambience" to stop and music later with the same tag
---- [continue] playing this music if another request for the same music comes in (false restarts it) 
---- [url] to download once from the Internet if the music does not exist in the profile's media directory
playMusicFile({
    name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"
    , volume = nil -- nil lines are optional, no need to use
    , fadein = 20000
    , fadeout = 53000
    , start = 10000
    , finish = 110000
    , loops = nil -- nil lines are optional, no need to use
    , key = "rugby"
    , tag = "ambience"
    , continue = true
    , url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"
})
---- Ordered Parameter Syntax of playMusicFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,continue][,url][,finish]) ----

-- Play a music file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)
playMusicFile(
    "167124__patricia-mcmillen__rugby-club-in-spain.mp3"  -- name
)

-- OR copy once from the game's profile, and play a music file stored in the profile's media directory
---- [volume] of 75 (1 to 100)
playMusicFile(
    getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name
    , 75 -- volume
)

-- OR copy once from the local file system, and play a music file stored in the profile's media directory
---- [volume] of 75 (1 to 100)
playMusicFile(
    "C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name
    , 75 -- volume
)

-- OR download once from the Internet, and play music stored in the profile's media directory
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 20 seconds
---- [fadeout] and decrease the volume from default volume to one, 53 seconds from the end of the music
---- [start] 10 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)
---- [finish] 110 seconds from the track start (fadeout scales its volume decrease over a shorter duration, too)
---- [key] reference of "rugby" for stopping this unique music later
---- [tag] reference of "ambience" to stop and music later with the same tag
---- [continue] playing this music if another request for the same music comes in (false restarts it) 
---- [url] to download once from the Internet if the music does not exist in the profile's media directory
playMusicFile(
    "167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name
    , nil -- volume
    , 20000 -- fadein
    , 53000 -- fadeout
    , 10000 -- start
    , nil -- loops
    , "rugby" -- key 
    , "ambience" -- tag
    , true -- continue
    , "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/" -- url
    , 110000 -- finish
)

playSoundFile

playSoundFile(settings table)
Plays sound files from the Internet or the local file system to the "media" folder of the profile for later use with stopSounds().
Required Key Value Default Purpose
Yes name <file name>  
  • Name of the media file.
  • May contain directory information (i.e. weather/lightning.wav).
  • May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")
  • May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")
  • Wildcards * and ? may be used within the name to randomize media files selection.
No volume 1 to 100 50
  • Relative to the volume set on the player's client.
No fadein <msec>
  • Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.
  • Start position: Start of media.
  • End position: Start of media plus the number of milliseconds (msec) specified.
  • 1000 milliseconds = 1 second.
No fadeout <msec>
  • Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.
  • Start position: End of the media minus the number of milliseconds (msec) specified.
  • End position: End of the media.
  • 1000 milliseconds = 1 second.
No start <msec> 0
  • Begin play at the specified position in milliseconds.
No finish <msec>
  • Finish play at the specified position in milliseconds.
No loops -1, or >= 1 1
  • Number of iterations that the media plays.
  • A value of -1 allows the media to loop indefinitely.
No key <key>  
  • Uniquely identifies media files with a "key" that is bound to their "name" or "url".
  • Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.
No tag <tag>  
  • Helps categorize media.
No priority 1 to 100  
  • Halts the play of current or future played media files with a lower priority while this media plays.
Maybe url <url>  
  • Resource location where the media file may be downloaded.
  • Only required if the file is to be downloaded remotely.

See also: loadMusicFile(), loadSoundFile(), playMusicFile(), getPlayingMusic(), getPlayingSounds(), stopMusic(), stopSounds(), purgeMediaCache(), Mud Client Media Protocol

Note Note: on Windows and certain files are not playing? Try installing the 3rd party K-lite codec pack.

Mudlet VersionAvailable in Mudlet4.15+
Example
---- Table Parameter Syntax ----

-- Play a sound file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)
playSoundFile({
    name = "cow.wav"
})

-- OR copy once from the game's profile, and play a sound file stored in the profile's media directory
---- [volume] of 75 (1 to 100)
playSoundFile({
    name = getMudletHomeDir().. "/cow.wav"
    , volume = 75
})

-- OR copy once from the local file system, and play a sound file stored in the profile's media directory
---- [volume] of 75 (1 to 100)
playSoundFile({
    name = "C:/Users/Tamarindo/Documents/cow.wav"
    , volume = 75
})

-- OR download once from the Internet, and play a sound stored in the profile's media directory
---- [volume] of 75
---- [loops] of 2 (-1 for indefinite repeats, 1+ for finite repeats)
---- [key] reference of "cow" for stopping this unique sound later
---- [tag] reference of "animals" to stop a group of sounds later with the same tag
---- [priority] of 25 (1 to 100, 50 default, a sound with a higher priority would stop this one)
---- [url] to download once from the Internet if the sound does not exist in the profile's media directory
playSoundFile({
    name = "cow.wav"
    , volume = 75
    , fadein = nil -- nil lines are optional, no need to use
    , fadeout = nil -- nil lines are optional, no need to use
    , start = nil -- nil lines are optional, no need to use
    , finish = nil -- nil lines are optional, no need to use
    , loops = 2
    , key = "cow"
    , tag = "animals"
    , priority = 25
    , url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"
})
---- Ordered Parameter Syntax of playSoundFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,priority][,url][,finish]) ----

-- Play a sound file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)
playSoundFile(
    "cow.wav" -- name
)

-- OR copy once from the game's profile, and play a sound file stored in the profile's media directory
---- [volume] of 75 (1 to 100)
playSoundFile(
    getMudletHomeDir().. "/cow.wav" -- name
    , 75 -- volume
)

-- OR copy once from the local file system, and play a sound file stored in the profile's media directory
---- [volume] of 75 (1 to 100)
playSoundFile(
    "C:/Users/Tamarindo/Documents/cow.wav" -- name
    , 75 -- volume
)

-- OR download once from the Internet, and play a sound stored in the profile's media directory
---- [volume] of 75
---- [loops] of 2 (-1 for indefinite repeats, 1+ for finite repeats)
---- [key] reference of "cow" for stopping this unique sound later
---- [tag] reference of "animals" to stop a group of sounds later with the same tag
---- [priority] of 25 (1 to 100, 50 default, a sound with a higher priority would stop this one)
---- [url] to download once from the Internet if the sound does not exist in the profile's media directory
playSoundFile(
    "cow.wav" -- name
    , 75 -- volume
    , nil -- fadein
    , nil -- fadeout
    , nil -- start
    , 2 -- loops
    , "cow" -- key 
    , "animals" -- tag
    , 25 -- priority
    , "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/" -- url
    , nil -- finish
)

purgeMediaCache

purgeMediaCache()
Purge all media file stored in the media cache within a given Mudlet profile (media used with MCMP and MSP protocols). As game developers update the media files on their games, this enables the media folder inside the profile to be cleared so that the media files could be refreshed to the latest update(s).
Guidance
  • Instruct a player to type lua purgeMediaCache() on the command line, or
  • Distribute a trigger, button or other scriptable feature for the given profile to call purgeMediaCache()
See also: Supported Protocols MSP, Scripting MCMP

receiveMSP

receiveMSP(command)
Receives a well-formed Mud Sound Protocol (MSP) message to be processed by the Mudlet client. Reference the Supported Protocols MSP manual for more information on about what can be sent and example triggers.
See also: Supported Protocols MSP
Example
--Play a cow.wav media file stored in the media folder of the current profile. The sound would play twice at a normal volume.
receiveMSP("!!SOUND(cow.wav L=2 V=50)")

--Stop any SOUND media files playing stored in the media folder of the current profile.
receiveMSP("!!SOUND(Off)")

--Play a city.mp3 media file stored in the media folder of the current profile. The music would play once at a low volume.
--The music would continue playing if it was triggered earlier by another room, perhaps in the same area.
receiveMSP([[!!MUSIC(city.mp3 L=1 V=25 C=1)]])

--Stop any MUSIC media files playing stored in the media folder of the current profile.
receiveMSP("!!MUSIC(Off)")

registerAnonymousEventHandler

registerAnonymousEventHandler(event name, functionReference, [one shot])
Registers a function to an event handler, not requiring you to set one up via script. See here for a list of Mudlet-raised events. The function may be refered to either by name as a string containing a global function name, or with the lua function object itself.
The optional one shot 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 true from the function to keep it registered.
The function returns an ID that can be used in killAnonymousEventHandler() to unregister the handler again.
If you use an asterisk ("*") as the event name, your code will capture all events. Useful for debugging, or integration with external programs.

Note Note: The ability to refer lua functions directly, the one shot parameter and the returned ID are features of Mudlet 3.5 and above.

Note Note: The "*" all-events capture was added in Mudlet 4.10.

See also
killAnonymousEventHandler(), raiseEvent(), list of Mudlet-raised events
Example
-- 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

if keepStaticSizeEventHandlerID then killAnonymousEventHandler(keepStaticSizeEventHandlerID) end -- clean up any already registered handlers for this function
keepStatisSizeEventHandlerID = registerAnonymousEventHandler("sysWindowResizeEvent", "keepStaticSize") -- register the event handler and save the ID for later killing
-- 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
if inventoryAddHandlerID then killAnonymousEventHandler(inventoryAddHandlerID) end -- clean up any already registered handlers for this function
inventoryAddHandlerID = registerAnonymousEventHandler("gmcp.Char.Items.Add", inventoryAdd) -- register the event handler and save the ID for later killing

local function inventoryList()
  if gmcp.Char.Items.List.location == "inv" then
    inventory = table.deepcopy(gmcp.Char.Items.List.items)
  end
end
if inventoryListHandlerID then killAnonymousEventHandler(inventoryListHandlerID) end -- clean up any already registered handlers for this function
inventoryListHandlerID = registerAnonymousEventHandler("gmcp.Char.Items.List", inventoryList) -- register the event handler and save the ID for later killing

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
if inventoryUpdateHandlerID then killAnonymousEventHandler(inventoryUpdateHandlerID) end -- clean up any already registered handlers for this function
inventoryUpdateHandlerID = 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
if inventoryRemoveHandlerID then killAnonymousEventHandler(inventoryRemoveHandlerID) end -- clean up any already registered handlers for this function
inventoryRemoveHandlerID = registerAnonymousEventHandler("gmcp.Char.Items.Remove", inventoryRemove)
-- 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"

if myPackageInstallHandler then killAnonymousEventHandler(myPackageInstallHandler) end
myPackageInstallHandler = 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")

registerNamedEventHandler

success = registerNamedEventHandler(userName, handlerName, eventName, functionReference, [oneShot])
Registers a named event handler with name handlerName. Named event handlers are protected from duplication and can be stopped and resumed, unlike anonymous event handlers. A separate list is kept per userName
See also
registerAnonymousEventHandler(), stopNamedEventHandler(), resumeNamedEventHandler(), deleteNamedEventHandler(), registerNamedTimer()
Mudlet VersionAvailable in Mudlet4.14+
Parameters
  • userName:
The user name the event handler was registered under.
  • handlerName:
The name of the handler. Used to reference the handler in other functions and prevent duplicates. Recommended you use descriptive names, "hp" is likely to collide with something else, "DemonVitals" less so.
  • eventName:
The name of the event the handler responds to. See here for a list of Mudlet-raised events.
  • functionReference:
The function reference to run when the event comes in. Can be the name of a function, "handlerFuncion", or the lua function itself.
  • oneShot:
(optional) if true, the event handler will only fire once when the event is raised. If you need to extend a one shot event handler for "one more check" you can have the handler return true, and it will keep firing until the function does not return true.
Returns
  • true if successful, otherwise errors.
Example
-- register a named event handler. Will call demonVitalsHandler(eventName, ...) when gmcp.Char.Vitals is raised.
local ok = registerNamedEventHandler("Demonnic", "DemonVitals", "gmcp.Char.Vitals", "demonVitalsHandler")
if ok then
  cecho("Vitals handler switched to demonVitalsHandler")
end

-- something changes later, and we want to handle vitals with another function, demonBlackoutHandler()
-- note we do not use "" around demonBlackoutHandler but instead pass the function itself. Both work.
-- using the same handlerName ("DemonVitals") means it will automatically unregister the old handler
-- and reregister it using the new information.
local ok = registerNamedEventHandler("Demonnic", "DemonVitals", "gmcp.Char.Vitals", demonBlackoutHandler)
if ok then
  cecho("Vitals handler switched to demonBlackoutHandler")
end

-- Now you want to check your inventory, but you only want to do it once, so you pass the optional oneShot as true
local function handleInv()
  local list = gmcp.Char.Items.List
  if list.location ~= "inventory" then
    return true -- if list.location is, say "room" then we need to keep responding until it's "inventory"
  end
  display(list.items) -- you would probably store values and update displays or something, but here I'll just show the data as it comes in
end

-- you can ignore the response from registerNamedEventHandler if you want, it's always going to be true
-- unless there is an error, in which case it throws the error and halts execution anyway. The return is
-- in part for feedback when using the lua alias or other REPL window.
registerNamedEventHandler("Demonnic", "DemonInvCheck", "gmcp.Char.Items.List", handleInv, true)

reloadModule

reloadModule(module name)
Reload a module (by uninstalling and reinstalling).
See also: installModule(), uninstallModule()
Example
reloadModule("3k-mapper")


removeFileWatch

removeFileWatch(path)
Remove file watch on directory or file. Every change in that file will no longer raise sysPathChanged event.
See also: addFileWatch()
Mudlet VersionAvailable in Mudlet4.12+
Example
herbs = {}
local herbsPath = getMudletHomeDir() .. "/herbs.lua"
function herbsChangedHandler(_, path)
  if path == herbsPath then
    table.load(herbsPath, herbs)
    removeFileWatch(herbsPath)
  end
end

addFileWatch(herbsPath)
registerAnonymousEventHandler("sysPathChanged", "herbsChangedHandler")

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.
Example
resetProfile()

The function used to require input from the game to work, but as of Mudlet 3.20 that is no longer the case.


Note Note: Don't put resetProfile() in the a script-item in the script editor as the script will be reloaded by resetProfile() as well better use

lua resetProfile()

in your commandline or make an Alias containing resetProfile().

resumeNamedEventHandler

success = resumeNamedEventHandler(userName, handlerName)
Resumes a named event handler with name handlerName and causes it to start firing once more.
See also
registerNamedEventHandler(), stopNamedEventHandler()
Mudlet VersionAvailable in Mudlet4.14+
Parameters
  • userName:
The user name the event handler was registered under.
  • handlerName:
The name of the handler to resume. Same as used when you called registerNamedEventHandler()
Returns
  • true if successful, false if it didn't exist.
Example
local resumed = resumeNamedEventHandler("Demonnic", "DemonVitals")
if resumed then
  cecho("DemonVitals resumed!")
else
  cecho("DemonVitals doesn't exist, cannot resume it")
end

saveProfile

saveProfile(location)
Saves the current Mudlet profile to disk, which is equivalent to pressing the "Save Profile" button.
Parameters
  • location:
(optional) folder to save the profile to. If not given, the profile will go into the default location.
Example
saveProfile()

-- save to the desktop on Windows:
saveProfile([[C:\Users\yourusername\Desktop]])

sendSocket

sendSocket(data)
Sends given binary data as-is to the game. You can use this to implement support for a new telnet protocol, simultronics login or etcetera.
Example
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 )

Note Note: Remember that should it be necessary to send the byte value of 255 as a data byte and not as the Telnet IAC value it is required to repeat it for Telnet to ignore it and not treat it as the latter.

setConfig

setConfig(option, value)
Sets a Mudlet option to a certain value. This comes in handy for scripts that want to customise Mudlet settings to their preferences - for example, setting up mapper room and exit size to one that works for a certain map, or enabling MSDP for a certain game. For transparency reasons, the Debug window (when open) will show which options were modified by scripts.
To set many options at once, pass in a table of options. More options will be added over time / per request.
See also
enableMapInfo(), disableMapInfo()
Mudlet VersionAvailable in Mudlet4.16+
Parameters
  • option:
Particular option to change - see list below for available ones.
  • value:
Value to set - can be a boolean, number, or text depending on the option.
General options
Option Default Description Available in Mudlet
enableGMCP true Enable GMCP (Reconnect after changing) 4.16
enableMSDP false Enable MSDP (Reconnect after changing) 4.16
enableMSSP true Enable MSSP (Reconnect after changing) 4.16
enableMSP true Enable MSP (Reconnect after changing) 4.16
compactInputLine false Hide search, timestamp, other buttons and labels bottom-right of input line 4.17
Input line
Option Default Description Available in Mudlet
inputLineStrictUnixEndings false Workaround option to use strict UNIX line endings for sending commands 4.16
Main display
Option Default Description Available in Mudlet
fixUnnecessaryLinebreaks false Remove extra linebreaks from output (mostly for IRE servers) 4.16
Mapper options
Option Default Description Available in Mudlet
mapRoomSize 5 Size of rooms on map (a good value is 5) 4.16
mapExitSize 10 Size of exits on map (a good value is 10) 4.16
mapRoundRooms false Draw rooms round or square 4.16
showRoomIdsOnMap false Show room IDs on all rooms (if zoom permits) 4.16
showMapInfo - Map overlay text ('Full', 'Short', or any custom made. Map can show multiple at once) 4.16
hideMapInfo - Map overlay text ('Full', 'Short', or any custom made. Hide each info separately to hide all) 4.16
show3dMapView false Show map as 3D 4.16
mapperPanelVisible true Map controls at the bottom 4.16
mapShowRoomBorders true Draw a thin border for every room 4.16
Special options
Option Default Description Available in Mudlet
specialForceCompressionOff false Workaround option to disable MCCP compression, in case the game server is not working correctly 4.16
specialForceGAOff false Workaround option to disable Telnet Go-Ahead, in case the game server is not working correctly 4.16
specialForceCharsetNegotiationOff false Workaround option to disable automatically setting the correct encoding, in case the game server is not working correctly 4.16
specialForceMxpNegotiationOff false Workaround option to disable MXP, in case the game server is not working correctly 4.16
caretShortcut "none" For visually-impaired players - set the key to switch between input line and main window (can be "none", "tab", "ctrltab", "f6") 4.17
blankLinesBehaviour "show" For visually impaired players options for dealing with blank lines (can be "show", "hide", "replacewithspace") 4.17
Returns
  • true if successful, or nil+msg if the option doesn't exist. Setting mapper options requires the mapper being open first.
Example
setConfig("mapRoomSize", 5)

setConfig({mapRoomSize = 6, mapExitSize = 12})

setMergeTables

setMergeTables(module)
Makes Mudlet merge the table of the given GMCP or MSDP module instead of overwriting the data. This is useful if the game sends only partial updates which need combining for the full data. By default "Char.Status" is the only merged module.
Parameters
  • module:
Name(s) of the GMCP or MSDP module(s) that should be merged as a string - this will add it to the existing list.
Example
setMergeTables("Char.Skills", "Char.Vitals")

setModuleInfo

setModuleInfo(moduleName, info, value)
Sets a specific meta info value for a module
Parameters
  • moduleName:
Name of the module
  • info:
specific info to set (for example "version")
  • value:
specific value to set (for example "1.0")
See also: getModuleInfo, getPackageInfo
Example
setModuleInfo("myModule", "version", "1.0")
Mudlet VersionAvailable in Mudlet4.12+

setModulePriority

setModulePriority(moduleName, priority)
Sets the module priority on a given module as a number - the module priority determines the order modules are loaded in, which can be helpful if you have ones dependent on each other. This can also be set from the module manager window.
Modules with priority -1 will be loaded before scripts (Mudlet 4.11+).
See also: getModulePriority()
setModulePriority("mudlet-mapper", 1)

setPackageInfo

setPackageInfo(packageName, info, value)
Sets a specific meta info value for a package
Parameters
  • packageName:
Name of the module
  • info:
specific info to set (for example "version")
  • value:
specific value to set (for example "1.0")
See also: getPackageInfo, setModuleInfo
Example
setPackageInfo("myPackage", "title", "This is my test package")
Mudlet VersionAvailable in Mudlet4.12+

setServerEncoding

setServerEncoding(encoding)
Makes Mudlet use the specified encoding for communicating with the game.
Parameters
  • encoding:
Encoding to use.
See also: getServerEncodingsList(), getServerEncoding()
Example
-- 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

showNotification

showNotification(title, [content], [expiryTimeInSeconds])
Shows a native (system) notification.
Mudlet VersionAvailable in Mudlet4.11+

Note Note: This might not work on all systems, this depends on the system.

Parameters
  • title - plain text notification title
  • content - optional argument, plain text notification content, if omitted title argument will be used as content as well
  • expiryTimeInSeconds - optional argument, sets expiration time in seconds for notification, very often ignored by OS
showNotification("Notification title", "Notification content", 5)

spawn

spawn(readFunction, processToSpawn[, ...arguments])
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().
This allows you to setup RPC communication with another process.
Examples
-- 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()
local f = spawn(display, "ls", "-la")
display(f.isRunning())
f.close()

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).
  • 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.
  • fileName (string)
The log will be/is being written to the path/file name returned.
  • 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
Example
-- start logging
local success, message, filename, code = startLogging(true)
if code == 1 or code == -1 then print(f"Started logging to {filename}") end

-- stop logging
startLogging(false)

stopAllNamedEventHandlers

stopAllNamedEventHandlers(userName)
Stops all named event handlers and prevents them from firing any more. Information is retained and handlers can be resumed.
See also
registerNamedEventHandler(), stopNamedEventHandler(), resumeNamedEventHandler()
Mudlet VersionAvailable in Mudlet4.14+
Parameter
  • userName:
The user name the event handler was registered under.
Example
stopAllNamedEventHandlers() -- emergency stop situation, most likely.

stopMusic

stopMusic(settings table)
Stop all music (no filter), or music that meets a combination of filters (name, key, and tag) intended to be paired with playMusicFile().
Required Key Value Default Purpose
No name <file name>
  • Name of the media file.
No key <key>
  • Uniquely identifies media files with a "key" that is bound to their "name" or "url".
  • Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.
No tag <tag>
  • Helps categorize media.
No fadeaway true or false false
  • Decrease volume from the current position for a given duration, then stops the track.
  • Given duration is the lesser of the remaining track duration or the fadeout specified in playMusicFile().
  • If fadeout was not specified in playMusicFile(), then the optional fadeout parameter from stopMusic() or a default of 5000 milliseconds will be applied.
No fadeout 5000
  • Default duration in milliseconds to decrease volume to the end of the track.
  • Only used if fadeout was not defined in playMusicFile().

See also: loadMusicFile(), loadSoundFile(), playMusicFile(), playSoundFile(), getPlayingMusic(), getPlayingSounds(), stopSounds(), purgeMediaCache(), Mud Client Media Protocol

Mudlet VersionAvailable in Mudlet4.15+
Example
---- Table Parameter Syntax ----

-- Stop all playing music files for this profile associated with the API
stopMusic()

-- Stop playing the rugby mp3 by name
stopMusic({name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"})

-- Stop playing the unique sound identified as "rugby"
stopMusic({
    name = nil  -- nil lines are optional, no need to use
    , key = "rugby" -- key
    , tag = nil  -- nil lines are optional, no need to use
})

-- Decrease volume for 5 seconds and then stop all playing music files for this profile associated with the API
stopMusic({
    fadeaway = true
})

-- Decrease volume for 10 seconds (or apply the duration of fadeout set in playMusicFile()) and then stop all playing music files for this profile associated with the API
stopMusic({
    fadeaway = true
    , fadeout = 10000
})

-- Decrease volume for 5 seconds and then stop all the unique "rugby" music for this profile associated with the API
stopMusic({
    key = "rugby"
    , fadeaway = true
})
---- Ordered Parameter Syntax of stopMusic([name][,key][,tag][,fadeaway][,fadeout]) ----

-- Stop all playing music files for this profile associated with the API
stopMusic()

-- Stop playing the rugby mp3 by name
stopMusic("167124__patricia-mcmillen__rugby-club-in-spain.mp3")

-- Stop playing the unique sound identified as "rugby"
stopMusic(
    nil -- name
    , "rugby" -- key
    , nil -- tag
)

-- Decrease the volume for 10 seconds then stop playing the unique sound identified as "rugby"
stopMusic(
    nil -- name
    , "rugby" -- key
    , nil -- tag
    , true -- fadeaway
    , 10000 -- fadeout
)

stopNamedEventHandler

success = stopNamedEventHandler(userName, handlerName)
Stops a named event handler with name handlerName and prevents it from firing any more. Information is stored so it can be resumed later if desired.
See also
registerNamedEventHandler(), resumeNamedEventHandler()
Mudlet VersionAvailable in Mudlet4.14+
Parameters
  • userName:
The user name the event handler was registered under.
  • handlerName:
The name of the handler to stop. Same as used when you called registerNamedEventHandler()
Returns
  • true if successful, false if it didn't exist or was already stopped
Example
local stopped = stopNamedEventHandler("DemonVitals")
if stopped then
  cecho("DemonVitals stopped!")
else
  cecho("DemonVitals doesn't exist or already stopped; either way it won't fire any more.")
end

stopSounds

stopSounds(settings table)
Stop all sounds (no filter), or sounds that meets a combination of filters (name, key, tag, and priority) intended to be paired with playSoundFile().
Required Key Value Default Purpose
No name <file name>
  • Name of the media file.
No key <key>
  • Uniquely identifies media files with a "key" that is bound to their "name" or "url".
  • Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.
No tag <tag>
  • Helps categorize media.
No priority 1 to 100
  • Halts the play of current or future played media files with a matching or lower priority.
No fadeaway true or false false
  • Decrease volume from the current position for a given duration, then stops the track.
  • Given duration is the lesser of the remaining track duration or the fadeout specified in playSoundFile().
  • If fadeout was not specified in playSoundFile(), then the optional fadeout parameter from stopSounds() or a default of 5000 milliseconds will be applied.
No fadeout 5000
  • Default duration in milliseconds to decrease volume to the end of the track.
  • Only used if fadeout was not defined in playSoundFile().

See also: loadMusicFile(), loadSoundFile(), playMusicFile(), playSoundFile(), getPlayingMusic(), getPlayingSounds(), stopMusic(), purgeMediaCache(), Mud Client Media Protocol

Mudlet VersionAvailable in Mudlet4.15+
Example
---- Table Parameter Syntax ----

-- Stop all playing sound files for this profile associated with the API
stopSounds()

-- Stop playing the cow sound
stopSounds({name = "cow.wav"})

-- Stop playing any sounds tagged as "animals" with a priority less than or equal to 50
---- This would not stop sounds tagged as "animals" greater than priority 50.  This is an "AND" and not an "OR".
stopSounds({
    name = nil -- nil lines are optional, no need to use
    , key = nil -- nil lines are optional, no need to use
    , tag = "animals"
    , priority = 50
})

-- Decrease volume for 5 seconds and then stop all playing sound files for this profile associated with the API
stopSounds({
    fadeaway = true
})

-- Decrease volume for 10 seconds (or apply the duration of fadeout set in playSoundFile()) and then stop all playing music files for this profile associated with the API
stopSounds({
    fadeaway = true
    , fadeout = 10000
})

-- Decrease volume for 3 seconds and then stop all the tagged "animals" music for this profile associated with the API
stopSounds({
    tag = "animals"
    , fadeaway = true
    , fadeout = 3000
})
---- Ordered Parameter Syntax of stopSounds([name][,key][,tag][,priority][,fadeaway][,fadeout]) ----

-- Stop all playing sound files for this profile associated with the API
stopSounds()

-- Stop playing the cow sound
stopSounds("cow.wav")

-- Stop playing any sounds tagged as "animals" with a priority less than or equal to 50
---- This would not stop sounds tagged as "animals" greater than priority 50.  This is an "AND" and not an "OR".
stopSounds(
    nil -- name
    , nil -- key
    , "animals" -- tag
    , 50 -- priority
)

-- Decrease the volume for 7 seconds and then stop playing sounds
stopSounds(
    nil -- name
    , nil -- key
    , nil -- tag
    , nil -- priority
    , true -- fadeaway
    , 7000 -- fadeout
)

timeframe

timeframe(vname, true_time, nil_time, ...)
A utility function that helps you change and track variable states without using a lot of tempTimers.
Mudlet VersionAvailable in Mudlet3.6+
Parameters
  • vname:
A string or function to use as the variable placeholder.
  • true_time:
Time before setting the variable to true. Can be a number or a table in the format: {time, value}
  • nil_time:
(optional) Number of seconds until vname is set back to nil. Leaving it undefined will leave it at whatever it was set to last. Can be a number of a table in the format: {time, value}
  • ...:
(optional) Further list of times and values to set the variable to, in the following format: {time, value}
Example
-- sets the global 'limiter' variable to true immediately (see the 0) and back to nil in one second (that's the 1).
timeframe("limiter", 0, 1)

-- An angry variable 'giant' immediately set to "fee", followed every second after by "fi", "fo", and "fum" before being reset to nil at four seconds.
timeframe("giant", {0, "fee"}, 4, {1, "fi"}, {2, "fo"}, {3, "fum"})

-- sets the local 'width' variable to true immediately and back to nil in one second.
local width
timeframe(function(value) width = value end, 0, 1)

translateTable

translateTable(directions, [languagecode])
Given a table of directions (such as speedWalkDir), translates directions to another language for you. Right now, it can only translate it into the language of Mudlet's user interface - but let us know if you need more.
Mudlet VersionAvailable in Mudlet3.22+
Parameters
  • directions:
An indexed table of directions (eg. {"sw", "w", "nw", "s"}).
  • languagecode:
(optional) Language code (eg ru_RU or it_IT) - by default, mudlet.translations.interfacelanguage is used.
Example
-- get the path from room 2 to room 5 and translate directions
if getPath(2, 5) then
speedWalkDir = translateTable(speedWalkDir)
print("Translated directions:")
display(speedWalkDir)

uninstallModule

uninstallModule(name)
Uninstalls a Mudlet module with the given name.
See also: installModule(), Event: sysLuaUninstallModule
Example
uninstallModule("myalias")

uninstallPackage

uninstallPackage(name)
Uninstalls a Mudlet package with the given name.
See also: installPackage()
Example
uninstallPackage("myalias")

unzipAsync

unzipAsync(path, location)
Unzips the zip file at path, extracting the contents to the location provided. Returns true if it is able to start unzipping, or nil+message if it cannot.

Raises the sysUnzipDone event with the zip file location and location unzipped to as arguments if unzipping is successful, and sysUnzipError with the same arguments if it is not.

Do not use the unzip() function as it is synchronous and will impact Mudlet's performance (ie, freeze Mudlet while unzipping).

Mudlet VersionAvailable in Mudlet4.6+
Example
function handleUnzipEvents(event, ...)
  local args = {...}
  local zipName = args[1]
  local unzipLocation = args[2]
  if event == "sysUnzipDone" then
    cecho(string.format("<green>Unzip successful! Unzipped %s to %s\n", zipName, unzipLocation))
  elseif event == "sysUnzipError" then
    cecho(string.format("<firebrick>Unzip failed! Tried to unzip %s to %s\n", zipName, unzipLocation))
  end
end
if unzipSuccessHandler then killAnonymousEventHandler(unzipSuccessHandler) end
if unzipFailureHandler then killAnonymousEventHandler(unzipFailureHandler) end
unzipSuccessHandler = registerAnonymousEventHandler("sysUnzipDone", "handleUnzipEvents")
unzipFailureHandler = registerAnonymousEventHandler("sysUnzipError", "handleUnzipEvents")
--use the path to your zip file for this, not mine
local zipFileLocation = "/home/demonnic/Downloads/Junkyard_Orc.zip" 
--directory to unzip to, it does not need to exist but you do need to be able to create it
local unzipLocation = "/home/demonnic/Downloads/Junkyard_Orcs" 
unzipAsync(zipFileLocation, unzipLocation) -- this will work
unzipAsync(zipFileLocation .. "s", unzipLocation) --demonstrate error, will happen first because unzipping takes time

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
-- on IRE MUD games, 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)


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