Difference between revisions of "User:Molideus"

From Mudlet
Jump to navigation Jump to search
Line 1: Line 1:
 
{{TOC right}}
 
{{TOC right}}
−
{{#description2:Mudlet API documentation for functions that manipulate the mapper and its related features.}}
+
{{#description2:Mudlet API documentation for miscellaneous functions.}}
−
= Mapper Functions =
+
= Miscellaneous Functions =
−
These are functions that are to be used with the Mudlet Mapper. The mapper is designed to be generic - it only provides the display and pathway calculations, to be used in Lua scripts that are tailored to the game you're playing. For a collection of pre-made scripts and general mapper talk, visit the [http://forums.mudlet.org/viewforum.php?f=13 mapper section] of the forums.
 
  
−
To register a script as a mapping one with Mudlet (so Mudlet knows the profile has one and won't bother the user when they open the map), please do this in your script:
+
==addFileWatch==
−
<syntaxhighlight lang="lua">
+
;addFileWatch(path)
−
mudlet = mudlet or {}; mudlet.mapper_script = true
+
:Adds file watch on directory or file. Every change in that file (or directory) will raise [[Manual:Event_Engine#sysPathChanged|sysPathChanged]] event.
−
</syntaxhighlight>
 
  
−
==addAreaName==
+
:See also: [[#removeFileWatch|removeFileWatch()]]
−
;areaID = addAreaName(areaName)
 
  
−
:Adds a new area name and returns the new (positive) area ID for the new name. If the name already exists, older versions of Mudlet returned -1 though since 3.0 the code will return ''nil'' and an error message.
+
{{MudletVersion|4.12}}
−
: See also: [[#deleteArea|deleteArea()]], [[#addRoom|addRoom()]]
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
local newId, err = addAreaName("My House")
+
herbs = {}
−
 
+
local herbsPath = getMudletHomeDir() .. "/herbs.lua"
−
if newId == nil or newId < 1 or err then
+
function herbsChangedHandler(_, path)
−
  echo("That area name could not be added - error is: ".. err.."\n")
+
   if path == herbsPath then
−
else
+
    table.load(herbsPath, herbs)
−
  cecho("<green>Created new area with the ID of "..newId..".\n")
+
     removeFileWatch(herbsPath)
−
end
 
−
</syntaxhighlight>
 
−
 
 
−
==addCustomLine==
 
−
;addCustomLine(roomID, id_to, direction, style, color, arrow)
 
−
: See also: [[#getCustomLines|getCustomLines()]], [[#removeCustomLine|removeCustomLine()]]
 
−
 
 
−
:Adds a new/replaces an existing custom exit line to the 2D mapper for the room with the Id given.
 
−
 
 
−
;Parameters
 
−
* ''roomID:''
 
−
: Room ID to attach the custom line to.
 
−
* ''id_to:''
 
−
: EITHER: a room Id number, of a room on same area who's x and y coordinates are used as the other end of a SINGLE segment custom line (it does NOT imply that is what the exit it represent goes to, just the location of the end of the line);
 
−
: OR: a table of sets of THREE (x,y and z) coordinates in that order, x and y can be decimals, z is an integer ('''and must be present and be the same for all points on the line''', though it is irrelevant to what is produced as the line is drawn on the same z-coordinate as the room that the line is attached to!)
 
−
* ''direction:'' a string to associate the line with a valid exit direction, "n", "ne", "e", "se", "s", "sw", "w", "nw", "up", "down", "in" or "out" or a special exit (before Mudlet 3.17 this was case-sensitive and cardinal directions had to be uppercase).
 
−
* ''style:'' a string, one of: "solid line", "dot line", "dash line", "dash dot line" or "dash dot dot line" exactly.
 
−
* ''color:'' a table of three integers between 0 and 255 as the custom line color as the red, green and blue components in that order.
 
−
* ''arrow:'' a boolean which if true will set the custom line to have an arrow on the end of the last segment.
 
−
 
 
−
{{MudletVersion|3.0}}
 
−
 
 
−
;Examples
 
−
<syntaxhighlight lang="lua">
 
−
-- create a line from roomid 1 to roomid 2
 
−
addCustomLine(1, 2, "N", "dot line", {0, 255, 255}, true)
 
−
 
 
−
addCustomLine(1, {{4.5, 5.5, 3}, {4.5, 9.5, 3}, {6.0, 9.5, 3}}, "climb Rope", "dash dot dot line", {128, 128, 0}, false)
 
−
</syntaxhighlight>
 
−
 
 
−
A bigger example that'll create a new area and the room in it:
 
−
 
 
−
<syntaxhighlight lang="lua">
 
−
local areaid = addAreaName("my first area")
 
−
local newroomid = createRoomID()
 
−
addRoom(newroomid)
 
−
setRoomArea(newroomid, "my first area")
 
−
setRoomCoordinates(newroomid, 0, 0, 0)
 
−
 
 
−
local otherroomid = createRoomID()
 
−
addRoom(otherroomid)
 
−
setRoomArea(otherroomid, "my first area")
 
−
setRoomCoordinates(otherroomid, 0, 5, 0)
 
−
 
 
−
addSpecialExit(newroomid, otherroomid, "climb Rope")
 
−
addCustomLine(newroomid, {{4.5, 5.5, 3}, {4.5, 9.5, 3}, {6.0, 9.5, 3}}, "climb Rope", "dash dot dot line", {128, 128, 0}, false)
 
−
 
 
−
centerview(newroomid)
 
−
</syntaxhighlight>
 
−
 
 
−
==addMapEvent==
 
−
;addMapEvent(uniquename, event name, parent, display name, arguments)
 
−
 
 
−
:Adds a new entry to an existing mapper right-click entry. You can add one with addMapMenu. If there is no display name, it will default to the unique name (which otherwise isn't shown and is just used to differentiate this entry from others). ''event name'' is the Mudlet event that will be called when this is clicked on, and ''arguments'' will be passed to the handler function.
 
−
: See also: [[#addMapMenu|addMapMenu()]], [[#removeMapEvent|removeMapEvent()]], [[#getMapEvents|getMapEvents()]]
 
−
 
 
−
;Example
 
−
<syntaxhighlight lang="lua">
 
−
addMapEvent("room a", "onFavorite") -- will make a label "room a" on the map menu's right click that calls onFavorite
 
−
 
 
−
addMapEvent("room b", "onFavorite", "Favorites", "Special Room!", 12345, "arg1", "arg2", "argn")
 
−
</syntaxhighlight>
 
−
The last line will make a label "Special Room!" under the "Favorites" menu that upon clicking will raise an event with all the arguments.
 
−
 
 
−
<syntaxhighlight lang="lua">
 
−
addMapMenu("Room type")
 
−
addMapEvent("markRoomsAsDeathTrap", "onMapMarkSelectedRooms", "Room type", "Mark selected rooms as Death Trap")
 
−
addMapEvent("markRoomsAsOneRoom", "onMapMarkSelectedRooms", "Room type", "Mark selected rooms as single-pass")
 
−
 
 
−
function onMapMarkSelectedRooms(event, markRoomType)
 
−
  local selectedRooms = getMapSelection()["rooms"]
 
−
   for i, val in ipairs(selectedRooms) do
 
−
    if markRoomType == "markRoomsAsDeathTrap" then
 
−
      local r, g, b = unpack(color_table.black)
 
−
      --death trap
 
−
      setRoomEnv(val, 300)
 
−
      --death traps Env
 
−
      setCustomEnvColor(300, r, g, b, 255)
 
−
      setRoomChar(val, "☠️")
 
−
      lockRoom(val, true)
 
−
     elseif markRoomType == "markRoomsAsOneRoom" then
 
−
      local r, g, b = unpack(color_table.LightCoral)
 
−
      --single-pass
 
−
      setRoomEnv(val, 301)
 
−
      --one room Env
 
−
      setCustomEnvColor(301, r, g, b, 255)
 
−
      setRoomChar(val, "🚹")
 
−
    end
 
 
   end
 
   end
−
  updateMap()
 
 
end
 
end
  
−
registerAnonymousEventHandler("onMapMarkSelectedRooms", "onMapMarkSelectedRooms")
+
addFileWatch(herbsPath)
 +
registerAnonymousEventHandler("sysPathChanged", "herbsChangedHandler")
 
</syntaxhighlight>
 
</syntaxhighlight>
−
This create menu and two submenu options: "Mark selected rooms as Death Trap" and "Mark selected rooms as single-pass"
 
  
−
==addMapMenu==
+
==addSupportedTelnetOption==
−
;addMapMenu(uniquename, parent, display name)
+
;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 [[Manual:Supported_Protocols#Adding_support_for_a_telnet_protocol|additional protocols]] section for more.
  
−
:Adds a new submenu to the right-click menu that opens when you right-click on the mapper. You can then add more submenus to it, or add entries with [[#addMapEvent|addMapEvent()]].
+
;Example:
−
: See also: [[#addMapEvent|addMapEvent()]], [[#removeMapEvent|removeMapEvent()]], [[#getMapEvents|getMapEvents()]]
 
  
−
;Example
 
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- This will create a menu named: Favorites.
+
<event handlers that add support for MSDP... see http://www.mudbytes.net/forum/comment/63920/#c63920 for an example>
−
addMapMenu("Favorites")
 
  
−
-- This will create a submenu with the unique id 'Favorites123' under 'Favorites' with the display name of 'More Favorites'.
+
-- register with Mudlet that it should not decline the request of MSDP support
−
addMapMenu("Favorites1234343", "Favorites", "More Favorites")  
+
local TN_MSDP = 69
 +
addSupportedTelnetOption(TN_MSDP)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==addRoom==
+
==alert==
−
;addRoom(roomID)
+
;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.
  
−
:Creates a new room with the given ID, returns true if the room was successfully created.  
+
{{MudletVersion|3.2}}
  
−
{{note}} If you're not using incremental room IDs but room IDs stitched together from other factors or in-game hashes for room IDs - and your room IDs are starting off at 250+million numbers, you need to look into incrementally creating Mudlets room IDs with [[#createRoomID|createRoomID()]] and associating your room IDs with Mudlets via [[#setRoomIDbyHash|setRoomIDbyHash()]] and [[#getRoomIDbyHash|getRoomIDbyHash()]]. The reason being is that Mudlet's A* pathfinding implementation from boost cannot deal with extremely large room IDs because the resulting matrices it creates for pathfinding are enormously huge.
+
;Parameters
−
{{note}} Creating your own mapping script? Check out more [[Manual:Mapper#Making_your_own_mapping_script|information here]].
+
* ''seconds:''
−
 
+
:(optional) number of seconds to have the alert for. If not provided, Mudlet will flash until the user opens Mudlet again.
−
: See also: [[#createRoomID|createRoomID()]]
 
  
 
;Example:
 
;Example:
−
<syntaxhighlight lang="lua">
 
−
local newroomid = createRoomID()
 
−
addRoom(newroomid)
 
−
</syntaxhighlight>
 
−
 
−
==addSpecialExit==
 
−
;addSpecialExit(roomIDFrom, roomIDTo, moveCommand)
 
−
 
−
:Creates a one-way from one room to another, that will use the given command for going through them.
 
−
 
−
: See also: [[#clearSpecialExits|clearSpecialExits()]], [[#removeSpecialExit|removeSpecialExit()]], [[#setExit|setExit()]]
 
  
−
;Example
 
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- add a one-way special exit going from room 1 to room 2 using the 'pull rope' command
+
-- flash indefinitely until Mudlet is open
−
addSpecialExit(1, 2, "pull rope")
+
alert()
−
</syntaxhighlight>
 
  
−
Example in an alias:
+
-- flash for just 3 seconds
−
<syntaxhighlight lang="lua">
+
alert(3)
−
-- sample alias pattern: ^spe (\d+) (.*?)$
 
−
-- currentroom is your current room ID in this example
 
−
addSpecialExit(currentroom,tonumber(matches[2]), matches[3])
 
−
echo("\n SPECIAL EXIT ADDED TO ROOMID:"..matches[2]..", Command:"..matches[3])
 
−
centerview(currentroom)
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==auditAreas==
+
==cfeedTriggers==
−
;auditAreas()
+
;cfeedTriggers(text)
 +
:Like feedTriggers, but you can add color information using color names, similar to cecho.
  
−
: Initiates a consistency check on the whole map: All rooms, areas, and their composition. This is also done automatically whenever you first open your map, so probably seldom necessary to do manually. Will output findings to screen and/or logfile for later review.
+
;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: [[#saveMap|saveMap()]], [[#removeMapEvent|removeMapEvent()]], [[#getMapEvents|getMapEvents()]]
+
:See also: [[#feedTriggers|feedTriggers]]
−
 
 
−
==centerview==
 
−
;centerview (roomID)
 
−
 
 
−
:Centers the map view onto the given room ID. The map must be open to see this take effect. This function can also be used to see the map of an area if you know the number of a room there and the area and room are mapped.
 
−
 
 
−
: See also: [[#getPlayerRoom|getPlayerRoom()]], [[#updateMap|updateMap()]]
 
−
 
 
−
==clearAreaUserData==
 
−
;clearAreaUserData(areaID)
 
−
 
 
−
; Parameter
 
−
* areaID - ID number for area to clear.
 
  
−
:Clears all user data from a given area. Note that this will not touch the room user data.
+
{{MudletVersion|4.10}}
−
: See also: [[#setAreaUserData|setAreaUserData()]], [[#getAllAreaUserData|getAllAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#clearRoomUserData|clearRoomUserData()]]
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
display(clearAreaUserData(34))
+
cfeedTriggers("<green:red>green on red<r> reset <124:100> foreground of ANSI124 and background of ANSI100<r>\n")
−
-- I did have data in that area, so it returns:
 
−
true
 
−
 
 
−
display(clearAreaUserData(34))
 
−
-- There is no data NOW, so it returns:
 
−
false
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
{{MudletVersion|3.0}}
+
==closeMudlet==
 +
;closeMudlet()
  
−
==clearAreaUserDataItem==
+
:Closes Mudlet and all profiles immediately.
−
;clearAreaUserDataItem(areaID, key)
+
:See also: [[Manual:Lua_Functions#saveProfile|saveProfile()]]
  
−
:Removes the specific key and value from the user data from a given area.
+
{{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!
−
: See also: [[#setAreaUserData|setAreaUserData()]], [[#clearAreaUserData|clearAreaUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]]
 
  
−
{{MudletVersion|3.0}}
+
{{MudletVersion|3.1}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
display(getAllAreaUserData(34))
+
closeMudlet()
−
{
 
−
  description = [[<area description here>]],
 
−
  ruler = "Queen Morgase Trakand"
 
−
}
 
−
 
 
−
display(clearAreaUserDataItem(34,"ruler"))
 
−
true
 
−
 
 
−
display(getAllAreaUserData(34))
 
−
{
 
−
  description = [[<area description here>]],
 
−
}
 
−
 
 
−
display(clearAreaUserDataItem(34,"ruler"))
 
−
false
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==clearMapSelection==
+
==compare==
−
;clearMapSelection()
 
  
−
:Clears any selected rooms from the map (i.e. they are highlighted in orange).
 
  
−
:Returns true if rooms are successfully cleared, false if nothing selected or cleared.
+
; sameValue = compare(a, b)
  
−
: See also [[#getMapSelection|getMapSelection()]]
+
:This function takes two items, and compares their values. It will compare numbers, strings, but most importantly it will compare two tables by value, not reference. For instance, ''{} == {}'' is ''false'', but ''compare({}, {})'' is ''true''
  
−
==clearMapUserData==
+
;See also: [[Manual:Lua_Functions#table.complement|table.complement()]], [[Manual:Lua_Functions#table.n_union|table.n_union()]]
−
;clearMapUserData()
 
  
−
:Clears all user data stored for the map itself. Note that this will not touch the area or room user data.
+
{{MudletVersion|4.18}}
  
−
: See also: [[#setMapUserData|setMapUserData()]], [[#clearRoomUserData|clearRoomUserData()]], [[#clearAreaUserData|clearAreaUserData()]]
+
;Parameters
 +
* ''a:''
 +
: The first item to compare
 +
* ''b:''
 +
: The second item to compare
  
−
{{MudletVersion|3.0}}
+
;Returns
 +
* Boolean true if the items have the same value, otherwise boolean false
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
display(clearMapUserData())
+
local tblA = { 255, 0, 0 }
−
-- I did have user data stored for the map, so it returns:
+
local tblB = color_table.red
−
true
+
local same = compare(tblA, tblB)
−
 
+
display(same)
−
display(clearMapUserData())
+
-- this will return true
−
-- There is no data NOW, so it returns:
+
display(tblA == tblB)
−
false
+
-- this will display false, as they are different tables
 +
-- even though they have the same value
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==clearMapUserDataItem==
+
; Additional development notes
−
;clearMapUserDataItem(mapID, key)
+
This is just exposing the existing _comp function, which is currently the best way to compare two tables by value. --[[User:Demonnic|Demonnic]] ([[User talk:Demonnic|talk]]) 18:51, 7 February 2024 (UTC)
  
−
:Removes the specific key and value from the user data from the map user data.
+
==createVideoPlayer==
−
: See also: [[#setMapUserData|setMapUserData()]], [[#clearMapUserData|clearMapUserData()]], [[#clearAreaRoomUserData|clearAreaRoomUserData()]]
 
  
−
;Example
+
;createVideoPlayer([name of userwindow], x, y, width, height)
−
<syntaxhighlight lang="lua">
 
−
display(getAllMapUserData())
 
−
{
 
−
  description = [[<map description here>]],
 
−
  last_modified = "1483228799"
 
−
}
 
  
−
display(clearMapUserDataItem("last_modified"))
+
:Creates a miniconsole window for the video player to render in, the with the given dimensions. One can only create one video player at a time (currently), and it is not currently possible to have a label on or under the video player - otherwise, clicks won't register.
−
true
 
  
−
display(getAllMapUserData())
+
{{note}} A video player may also be created through use of the [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]], the [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]] API command, or adding a Geyser.VideoPlayer object to ones user interface such as the example below.
−
{
 
−
  description = [[<map description here>]],
 
−
}
 
  
−
display(clearMapUserDataItem("last_modified"))
+
{{Note}} The Main Toolbar will show a '''Video''' button to hide/show the video player, which is located in a userwindow generated through createVideoPlayer, embedded in a user interface, or a dock-able widget (that can be floated free to anywhere on the Desktop, it can be resized and does not have to even reside on the same monitor should there be multiple screens in your system). Further clicks on the '''Video''' button will toggle between showing and hiding the map whether it was created using the ''createVideo'' function or as a dock-able widget.
−
false
 
−
</syntaxhighlight>
 
  
−
{{MudletVersion|3.0}}
+
See also: [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous Functions#loadVideoFile|loadVideoFile()]], [[Manual:Miscellaneous Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous Functions#playVideoFile|playVideoFile()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous Functions#stopVideos|stopVideos()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]
  
−
==clearRoomUserData==
+
{{MudletVersion|4.??}}
−
;clearRoomUserData(roomID)
 
−
 
 
−
:Clears all user data from a given room.
 
−
: See also: [[#setRoomUserData|setRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]]
 
−
 
 
−
{{note}} Returns a boolean true if any data was removed from the specified room and false if there was nothing to erase since Mudlet 3.0.
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
display(clearRoomUserData(3441))
+
-- Create a 300x300 video player in the top-left corner of Mudlet
−
-- I did have data in that room, so it returns:
+
createVideoPlayer(0,0,300,300)
−
true
 
  
−
display(clearRoomUserData(3441))
+
-- Alternative examples using Geyser.VideoPlayer
−
-- There is no data NOW, so it returns:
+
GUI.VideoPlayer = GUI.VideoPlayer or Geyser.VideoPlayer:new({name="GUI.VideoPlayer", x = 0, y = 0, width = "25%", height = "25%"})
−
false
+
 +
GUI.VideoPlayer = GUI.VideoPlayer or Geyser.VideoPlayer:new({
 +
  name = "GUI.VideoPlayer",
 +
  x = "70%", y = 0, -- edit here if you want to move it
 +
  width = "30%", height = "50%"
 +
}, GUI.Right)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==clearRoomUserDataItem==
+
==deleteAllNamedEventHandlers==
−
;clearRoomUserDataItem(roomID, key)
+
; deleteAllNamedEventHandlers(userName)
  
−
:Removes the specific key and value from the user data from a given room.
+
:Deletes all named event handlers for userName and prevents them from firing any more. Information is deleted and cannot be retrieved.
−
:Returns a boolean true if data was found against the give key in the user data for the given room and it is removed, will return false if exact key not present in the data. Returns nil if the room for the roomID not found.
 
−
: See also: [[#setRoomUserData|setRoomUserData()]], [[#clearRoomUserData|clearRoomUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]]
 
  
−
;Example
+
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#stopNamedEventHandler|stopNamedEventHandler()]]
−
<syntaxhighlight lang="lua">
 
−
display(getAllRoomUserData(3441))
 
−
{
 
−
  description = [[
 
−
From this ledge you can see out across a large cavern to the southwest. The
 
−
east side of the cavern is full of stalactites and stalagmites and other
 
−
weird rock formations. The west side has a path through it and an exit to the
 
−
south. The sound of falling water pervades the cavern seeming to come from
 
−
every side. There is a small tunnel to your east and a stalactite within arms
 
−
reach to the south. It appears to have grown till it connects with the
 
−
stalagmite below it. Something smells... Yuck you are standing in bat guano!]],
 
−
  doorname_up = "trapdoor"
 
−
}
 
  
−
display(clearRoomUserDataItem(3441,"doorname_up"))
+
{{MudletVersion|4.14}}
−
true
 
  
−
display(getAllRoomUserData(3441))
+
;Parameters
−
{
+
* ''userName:''
−
  description = [[
+
: The user name the event handler was registered under.
−
From this ledge you can see out across a large cavern to the southwest. The
 
−
east side of the cavern is full of stalactites and stalagmites and other
 
−
weird rock formations. The west side has a path through it and an exit to the
 
−
south. The sound of falling water pervades the cavern seeming to come from
 
−
every side. There is a small tunnel to your east and a stalactite within arms
 
−
reach to the south. It appears to have grown till it connects with the
 
−
stalagmite below it. Something smells... Yuck you are standing in bat guano!]],
 
−
}
 
−
 
 
−
display(clearRoomUserDataItem(3441,"doorname_up"))
 
−
false
 
−
</syntaxhighlight>
 
−
 
 
−
{{MudletVersion|3.0}}
 
−
 
 
−
==clearSpecialExits==
 
−
;clearSpecialExits(roomID)
 
−
 
 
−
:Removes all special exits from a room.
 
−
: See also: [[#addSpecialExit|addSpecialExit()]], [[#removeSpecialExit|removeSpecialExit()]]
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
clearSpecialExits(1337)
+
deleteAllNamedEventHandlers("Demonnic") -- emergency stop or debugging situation, most likely.
−
 
 
−
if #getSpecialExits(1337) == 0 then -- clearSpecialExits will never fail on a valid room ID, this is an example
 
−
  echo("All special exits successfully cleared from 1337.\n")
 
−
end
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==closeMapWidget==
+
==deleteNamedEventHandler==
−
;closeMapWidget()
+
; success = deleteNamedEventHandler(userName, handlerName)
−
:closes (hides) the map window (similar to clicking on the map icon)
 
  
−
{{MudletVersion|4.7}}
+
:Deletes a named event handler with name handlerName and prevents it from firing any more. Information is deleted and cannot be retrieved.
−
: See also: [[#openMapWidget|openMapWidget()]], [[#moveMapWidget|moveMapWidget()]], [[#resizeMapWidget|resizeMapWidget()]]
 
  
−
==connectExitStub==
+
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#stopNamedEventHandler|stopNamedEventHandler()]]
−
;connectExitStub(fromID, direction) or connectExitStub(fromID, toID, [direction])
 
  
−
:Connects existing rooms with matching exit stubs. If you only give it a roomID and a direction, it'll work out which room should be linked to it that has an appropriate opposite exit stub and is located in the right direction. You can also just specify from and to room IDs, and it'll smartly use the right direction to link in. Lastly, you can specify all three arguments - fromID, toID and the direction (in that order) if you'd like to be explicit, or use [[#setExit|setExit()]] for the same effect.
+
{{MudletVersion|4.14}}
  
 
;Parameters
 
;Parameters
−
* ''fromID:''
+
* ''userName:''
−
: Room ID to set the exit stub in.
+
: The user name the event handler was registered under.
−
* ''direction:''
+
* ''handlerName:''
−
: You can either specify the direction to link the room in, and/or a specific room ID (see below). Direction can be specified as a number, short direction name ("nw") or long direction name ("northwest").
+
: The name of the handler to stop. Same as used when you called [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]]
−
* ''toID:''
 
−
: The room ID to link this room to. If you don't specify it, the mapper will work out which room should be logically linked.
 
−
 
 
−
: See also: [[#setExitStub|setExitStub()]], [[#getExitStubs|getExitStubs()]]
 
  
 +
;Returns
 +
* true if successful, false if it didn't exist
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- try and connect all stubs that are in a room
+
local deleted = deleteNamedEventHandler("Demonnic", "Vitals")
−
local stubs = getExitStubs(roomID)
+
if deleted then
−
if stubs then
+
   cecho("Vitals deleted forever!!")
−
   for i,v in pairs(stubs) do
+
else
−
    connectExitStub(roomID, v)
+
  cecho("Vitals doesn't exist and so could not be deleted.")
−
  end
 
 
end
 
end
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==createMapLabel==
+
==denyCurrentSend==
−
;labelID = createMapLabel(areaID, text, posX, posY, posZ, fgRed, fgGreen, fgBlue, bgRed, bgGreen, bgBlue[, zoom, fontSize, showOnTop, noScaling, fontName, foregroundTransparency, backgroundTransparency, temporary])
+
;denyCurrentSend()
−
 
 
−
:Creates a text label on the map at given coordinates, with the given background and foreground colors. It can go above or below the rooms, scale with zoom or stay a static size. From Mudlet 4.17.0 an additional parameter (assumed to be false if not given from then) makes the label NOT be saved in the map file which, if the image can be regenerated on future loading from a script can reduce the size of the saved map somewhat. It returns a label ID that you can use later for deleting it.
 
−
 
 
−
:The coordinates 0,0 are in the middle of the map, and are in sync with the room coordinates - so using the x,y values of [[#getRoomCoordinates|getRoomCoordinates()]] will place the label near that room.
 
−
 
 
−
: See also: [[#getMapLabel|getMapLabel()]], [[#getMapLabels|getMapLabels()]], [[#deleteMapLabel|deleteMapLabel]], [[#createMapImageLabel|createMapImageLabel()]]
 
−
 
 
−
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
 
−
<div style="font-weight:bold;line-height:1.6;">Historical Version Note</div>
 
−
<div class="mw-collapsible-content">
 
−
{{note}} Some changes were done prior to 4.13 (which exactly? function existed before!) - see corresponding PR and update here!
 
−
</div></div></div>
 
  
−
;Parameters
+
:Cancels a [[Manual:Lua_Functions#send|send()]] or user-entered command, but only if used within a [[Manual:Event_Engine#sysDataSendRequest|sysDataSendRequest]] event.
−
* ''areaID:''
 
−
: Area ID where to put the label.
 
−
* ''text:''
 
−
: The text to put into the label. To get a multiline text label add a '\n' between the lines.
 
−
* ''posX, posY, posZ:''
 
−
: Position of the label in (floating point numbers) room coordinates.
 
−
* ''fgRed, fgGreen, fgBlue:''
 
−
: Foreground color or text color of the label.
 
−
* ''bgRed, bgGreen, bgBlue:''
 
−
: Background color of the label.
 
−
* ''zoom:''
 
−
: (optional) Zoom factor of the label if noScaling is false. Higher zoom will give higher resolution of the text and smaller size of the label. Default is 30.0.
 
−
* ''fontSize:''
 
−
: (optional, but needed if zoom is provided) Size of the font of the text. Default is 50.
 
−
* ''showOnTop:''
 
−
: (optional) If true the label will be drawn on top of the rooms and if it is false the label will be drawn as a background, defaults to true if not given.
 
−
* ''noScaling:''
 
−
: (optional) If true the label will have the same size when you zoom in and out in the mapper, If it is false the label will scale when you zoom the mapper, defaults to true if not given.
 
−
* ''fontName:''
 
−
: (optional) font name to use.
 
−
* ''foregroundTransparency''
 
−
: (optional) transparency of the text on the label, defaults to 255 (in range of 0 to 255) or fully opaque if not given.
 
−
* ''backgroundTransparency''
 
−
: (optional) transparency of the label background itself, defaults to 50 (in range of 0 to 255) or significantly transparent if not given.
 
−
* ''temporary''
 
−
: (optional, from Mudlet version 4.17.0) if true does not save the image that the label makes in map save files, defaults to false if not given, or for prior versions of Mudlet.
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- the first 50 is some area id, the next three 0,0,0 are coordinates - middle of the area
+
-- cancels all "eat hambuger" commands
−
-- 255,0,0 would be the foreground in RGB, 23,0,0 would be the background RGB
+
function cancelEatHamburger(event, command)
−
-- zoom is only relevant when when you're using a label of a static size, so we use 0
+
  if command == "eat hamburger" then
−
-- and we use a font size of 20 for our label, which is a small medium compared to the map
+
    denyCurrentSend()
−
local labelid = createMapLabel( 50, "my map label", 0,0,0, 255,0,0, 23,0,0, 0,20)
+
    cecho("<red>Denied! Didn't let the command through.\n")
 +
  end
 +
end
  
−
-- to create a multi line text label we add '\n' between lines
+
registerAnonymousEventHandler("sysDataSendRequest", "cancelEatHamburger")
−
-- the position is placed somewhat to the northeast of the center of the map
 
−
-- this label will be scaled as you zoom the map.
 
−
local labelid = createMapLabel( 50, "1. Row One\n2. Row 2", .5,5.5,0, 255,0,0, 23,0,0, 30,50, true, false)
 
−
 
 
−
local x,y,z = getRoomCoordinates(getPlayerRoom())
 
−
createMapLabel(getRoomArea(getPlayerRoom()), "my map label", x,y,z, 255,0,0, 23,0,0, 0,20, false, true, "Ubuntu", 255, 100)
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==createMapImageLabel==
+
==dfeedTriggers==
−
;labelID = createMapImageLabel(areaID, filePath, posx, posy, posz, width, height, zoom, showOnTop[, temporary])
+
;dfeedTriggers(str)
 +
:Like feedTriggers, but you can add color information using <r,g,b>, similar to decho.
  
−
:Creates an image label on the map at the given coordinates, with the given dimensions and zoom. You might find the default room and image size correlation to be too big - try reducing the width and height of the image then, while also zooming in the same amount. From Mudlet 4.17.0 an additional parameter (assumed to be false if not given from then) makes the label NOT be saved in the map file which, if the image can be regenerated on future loading from a external file available when the map file is loaded, can avoid expanding the size of the saved map considerably.
+
;Parameters
 +
* ''str'': The string to feed to the trigger engine. Include color information inside tags like decho.
 +
;See also: [[Manual:Lua_Functions#cfeedTriggers|cfeedTriggers]], [[Manual:Lua_Functions#decho|decho]]
  
−
:The coordinates 0,0 are in the middle of the map, and are in sync with the room coordinates - so using the x,y values of [[#getRoomCoordinates|getRoomCoordinates()]] will place the label near that room.
+
{{MudletVersion|4.11}}
−
: See also: [[#createMapLabel|createMapLabel]], [[#deleteMapLabel|deleteMapLabel]]
 
  
−
;Example:
+
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- 138 is our pretend area ID
+
dfeedTriggers("<0,128,0:128,0,0>green on red<r> reset\n")
−
-- next, inside [[]]'s, is the exact location of our image
 
−
-- 0,0,0 are the x,y,z coordinates - so this will place it in the middle of the map
 
−
-- 482 is the width of the image - we divide it by 100 to scale it down, and then we'll zoom it by 100 - making the image take up about 4 rooms in width then
 
−
-- 555 is the original height of the image
 
−
-- 100 is how much we zoom it by, 1 would be no zoom
 
−
-- false to make it go below our rooms
 
−
-- (from 4.17.0) true to not save the label's image in the map file afterwards
 
−
createMapImageLabel(138, [[/home/vadi/Pictures/You only see what shown.png]], 0,0,0, 482/100, 555/100, 100, false, true)
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==createMapper==
+
==disableModuleSync==
−
;createMapper([name of userwindow], x, y, width, height)
+
;disableModuleSync(name)
−
 
+
: Stops syncing the given module.
−
:Creates a miniconsole window for the mapper to render in, the with the given dimensions. You can only create one mapper at a time, and it is not currently possible to have a label on or under the mapper - otherwise, clicks won't register.
 
  
−
{{note}} ''name of userwindow'' available in Mudlet 4.6.1+
+
;Parameter
 +
* ''name'': name of the module.
  
−
{{Note}} If this command is ''not'' used then clicking on the Main Toolbar's '''Map''' button will create a dock-able widget (that can be floated free to anywhere on the Desktop, it can be resized and does not have to even reside on the same monitor should there be multiple screens in your system). Further clicks on the '''Map''' button will toggle between showing and hiding the map whether it was created using the ''createMapper'' function or as a dock-able widget.
+
:See also: [[Manual:Lua_Functions#enableModuleSync|enableModuleSync()]], [[Manual:Lua_Functions#getModuleSync|getModuleSync()]]
 +
{{MudletVersion|4.8}}
  
−
;Example
+
==enableModuleSync==
−
<syntaxhighlight lang="lua">
+
;enableModuleSync(name)
−
createMapper(0,0,300,300) -- creates a 300x300 mapper in the top-left corner of Mudlet
+
: 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.
−
setBorderLeft(305) -- adds a border so text doesn't underlap the mapper display
 
−
</syntaxhighlight>
 
  
−
<syntaxhighlight lang="lua">
+
;Parameter
−
-- another example:
+
* ''name'': name of the module to enable sync on.
−
local main = Geyser.Container:new({x=0,y=0,width="100%",height="100%",name="mapper container"})
 
−
 
−
local mapper = Geyser.Mapper:new({
 
−
  name = "mapper",
 
−
  x = "70%", y = 0, -- edit here if you want to move it
 
−
  width = "30%", height = "50%"
 
−
}, main)
 
−
</syntaxhighlight>
 
  
−
==createRoomID==
+
:See also: [[Manual:Lua_Functions#disableModuleSync|disableModuleSync()]], [[Manual:Lua_Functions#getModuleSync|getModuleSync()]]
−
;usableId = createRoomID([minimumStartingRoomId])
+
{{MudletVersion|4.8}}
  
−
:Returns the lowest possible room ID you can use for creating a new room. If there are gaps in room IDs your map uses it, this function will go through the gaps first before creating higher IDs.  
+
==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
 
;Parameters
−
* ''minimumStartingRoomId'' (optional, available in Mudlet 3.0+):
+
* ''command''
−
: If provided, specifies a roomID to start searching for an empty one at, instead of 1. Useful if you'd like to ensure certain areas have specific room number ranges, for example. If you you're working with a huge map, provide the last used room ID to this function for an available roomID to be found a lot quicker.
+
: Text of the command you want to send to the game. Will be checked for aliases.
−
 
+
* ''echoBackToBuffer''
−
: See also: [[#addRoom|addRoom()]]
+
: (optional) If ''false'', the command will not be echoed back in your buffer. Defaults to ''true'' if omitted.
−
 
 
−
==deleteArea==
 
−
;deleteArea(areaID or areaName)
 
  
−
:Deletes the given area and all rooms in it. Returns ''true'' on success or ''nil'' + ''error message'' otherwise.
+
{{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.
−
: See also: [[#addAreaName|addAreaName()]]
 
  
−
;Parameters
+
{{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.
−
* ''areaID:''
 
−
: Area ID to delete, or:
 
−
* ''areaName'' (available in Mudlet 3.0+):
 
−
: Area name to delete.
 
  
 +
{{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
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- delete by areaID
+
expandAlias("t rat")
−
deleteArea(23)
+
 
−
-- or since Mudlet 3.0, by area name
+
-- don't echo the command
−
deleteArea("Big city")
+
expandAlias("t rat", false)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==deleteMap==
+
==feedTriggers==
−
;deleteMap()
+
;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.
  
−
Deletes the entire map. This may be useful whilst initially setting up a mapper package for a new Game to clear faulty map data generated up to this point.
+
;Parameters
−
: See also: [[#loadMap|loadMap()]]
+
* ''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''. 
−
{{MudletVersion|4.14.0}}
+
* ''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
+
;Returns (available in Mudlet 4.2+):
−
:''true'' on success or ''nil'' and an error message on failure, if successful it will also refresh the map display to show the result - which will be the "blank" screen with a warning message of the form ''"No rooms in the map - load another one, or start mapping from scratch to begin."''
+
* ''true'' on success, ''nil'' and an error message if the text contains characters that cannot be conveyed by the current Game Server encoding.
  
−
{{note}} Prior to the introduction of this function, the recommended method to achieve the same result was to use [[#loadMap|loadMap()]] with a non-existent file-name, such as ''"_"'' however that would also cause an ''"[ ERROR ]"'' type message to appear on the profile's main console.
+
{{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
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
deleteMap()
+
-- 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")
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==deleteMapLabel==
+
==getCharacterName==
−
;deleteMapLabel(areaID, labelID)
+
;getCharacterName()
−
 
 
−
:Deletes a map label from  a specific area.
 
−
: See also: [[#createMapLabel|createMapLabel()]]
 
  
−
;Example
+
: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.
−
<syntaxhighlight lang="lua">
 
−
deleteMapLabel(50, 1)
 
−
</syntaxhighlight>
 
  
−
==deleteRoom==
+
:See also: [[#getProfileName|getProfileName()]]
−
;deleteRoom(roomID)
 
  
−
:Deletes an individual room, and unlinks all exits leading to and from it.
+
{{MudletVersion|4.16}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
deleteRoom(335)
+
-- cast glamor on yourself
 +
 
 +
send("cast 'glamor' " .. getCharacterName())
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==disableMapInfo==
+
==getConfig ==
−
;disableMapInfo(label)
+
;getConfig([option])
−
 
 
−
Disable the particular map info - same as toggling off checkbox from select box under mapper.
 
−
 
 
−
;Parameters
 
−
* ''label:''
 
−
: Name under which map info to be disabled was registered.
 
−
 
 
−
: See also: [[#registerMapInfo|registerMapInfo()]], [[#enableMapInfo|enableMapInfo()]], [[#killMapInfo|killMapInfo()]]
 
−
 
 
−
{{MudletVersion|4.11}}
 
  
−
==enableMapInfo==
+
: 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.
−
;enableMapInfo(label)
+
See also: [[Manual:Miscellaneous_Functions#setConfig|setConfig()]]
  
−
Enable the particular map info - same as toggling on checkbox from select box under mapper.
+
{{MudletVersion|4.17}}
  
 
;Parameters
 
;Parameters
−
* ''label:''
+
*''option:''
−
: Name under which map info to be enabled was registered.
+
:Particular option to retrieve - see list below for available ones. This may be a string or an array of strings.
  
−
: See also: [[#registerMapInfo|registerMapInfo()]], [[#disableMapInfo|disableMapInfo()]], [[#killMapInfo|killMapInfo()]]
+
{| class="wikitable sortable"
 +
|+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
 +
|}
  
−
{{MudletVersion|4.11}}
+
{| class="wikitable sortable"
 +
|+Input line
 +
|-
 +
!Option!!Description!!Available in Mudlet
 +
|-
 +
|inputLineStrictUnixEndings||Workaround option to use strict UNIX line endings for sending commands||4.17
 +
|-
 +
|}
  
−
==getAllAreaUserData==
+
{| class="wikitable sortable"
−
;dataTable = getAllAreaUserData(areaID)
+
|+Main display
 +
|-
 +
!Option!!Description!!Available in Mudlet
 +
|-
 +
|fixUnnecessaryLinebreaks||Remove extra linebreaks from output (mostly for IRE servers) || 4.17
 +
|-
 +
|}
  
−
:Returns all the user data items stored in the given area ID; will return an empty table if there is no data stored or nil if there is no such area with that ID.
+
{| 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
 +
|}
  
−
: See also: [[#clearAreaUserData|clearAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#searchAreaUserData|searchAreaUserData()]], [[#setAreaUserData|setAreaUserData()]]
+
{| class="wikitable sortable"
 +
|+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
 +
|}
  
−
;Example
+
;Returns
−
<syntaxhighlight lang="lua">
+
*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.
−
display(getAllAreaUserData(34))
 
−
--might result in:--
 
−
{
 
−
  country = "Andor",
 
−
  ruler = "Queen Morgase Trakand"
 
−
}
 
−
</syntaxhighlight>
 
−
 
 
−
{{MudletVersion|3.0}}
 
−
 
 
−
==getAllMapUserData==
 
−
;dataTable = getAllMapUserData()
 
−
 
 
−
:Returns all the user data items stored at the map level; will return an empty table if there is no data stored.
 
−
 
 
−
: See also: [[#getMapUserData|getMapUserData()]]
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
display(getAllMapUserData())
+
getConfig()
−
--might result in:--
 
−
{
 
−
  description = [[This map is about so and so game]],
 
−
  author = "Bob",
 
−
  ["last updated"] = "December 5, 2020"
 
−
}
 
−
</syntaxhighlight>
 
−
 
 
−
{{MudletVersion|3.0}}
 
−
 
 
−
==getAllRoomEntrances==
 
−
;exitsTable = getAllRoomEntrances(roomID)
 
  
−
:Returns an indexed list of normal and special exits leading into this room. In case of two-way exits, this'll report exactly the same rooms as [[#getRoomExits|getRoomExits()]], but this function has the ability to pick up one-way exits coming into the room as well.
+
-- Suggest enabling GMCP if it is unchecked
−
 
+
if not getConfig("enableGMCP") then
−
{{MudletVersion|3.0}}
+
  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)
−
;Example
+
   echo(" to enable it.\n")
−
<syntaxhighlight lang="lua">
 
−
-- print the list of rooms that have exits leading into room 512
 
−
for _, roomid in ipairs(getAllRoomEntrances(512)) do
 
−
   print(roomid)
 
 
end
 
end
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
: See also: [[#getRoomExits|getRoomExits()]]
+
==getModulePath==
−
 
+
;path = getModulePath(module name)
−
==getAllRoomUserData==
 
−
;dataTable = getAllRoomUserData(roomID)
 
−
 
 
−
:Returns all the user data items stored in the given room ID; will return an empty table if there is no data stored or nil if there is no such room with that ID. ''Can be useful if the user was not the one who put the data in the map in the first place!''
 
  
−
;See also: [[#getRoomUserDataKeys|getRoomUserDataKeys()]] - for a related command that only returns the data keys.
+
: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: [[Manual:Lua_Functions#installModule|installModule()]]
  
 
{{MudletVersion|3.0}}
 
{{MudletVersion|3.0}}
Line 674: Line 431:
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
display(getAllRoomUserData(3441))
+
getModulePath("mudlet-mapper")
−
--might result in:--
 
−
{
 
−
  description = [[
 
−
From this ledge you can see out across a large cavern to the southwest. The
 
−
east side of the cavern is full of stalactites and stalagmites and other
 
−
weird rock formations. The west side has a path through it and an exit to the
 
−
south. The sound of falling water pervades the cavern seeming to come from
 
−
every side. There is a small tunnel to your east and a stalactite within arms
 
−
reach to the south. It appears to have grown till it connects with the
 
−
stalagmite below it. Something smells... Yuck you are standing in bat guano!]],
 
−
  doorname_up = "trapdoor"
 
−
}
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==getAreaExits==
+
==getModulePriority==
−
;roomTable = getAreaExits(areaID, showExits)
+
;priority = getModulePriority(module name)
−
 
 
−
: Returns a table (indexed or key-value) of the rooms in the given area that have exits leading out to other areas - that is, border rooms.
 
−
 
 
−
;See also: [[#setExit|setExit()]], [[#getRoomExits|getRoomExits()]]
 
  
−
;Parameters
+
: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.
−
* ''areaID:''
+
:Modules with priority <code>-1</code> will be loaded before scripts (Mudlet 4.11+).
−
: Area ID to list the exits for.
 
−
* ''showExits:''
 
−
: Boolean argument, if true then the exits that lead out to another area will be listed for each room.
 
  
 +
:See also: [[Manual:Lua_Functions#setModulePriority|setModulePriority()]]
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- list all border rooms for area 44:
+
getModulePriority("mudlet-mapper")
−
getAreaExits(44)
+
</syntaxhighlight>
  
−
-- returns:
+
==getModules==
−
--[[
+
;getModules()
−
{
 
−
  7091,
 
−
  10659,
 
−
  11112,
 
−
  11122,
 
−
  11133,
 
−
  11400,
 
−
  12483,
 
−
  24012
 
−
}
 
−
]]
 
  
−
-- list all border rooms for area 44, and the exits within them that go out to other areas:
+
:Returns installed modules as table.
−
getAreaExits(44, true)
 
−
--[[
 
−
{
 
−
  [12483] = {
 
−
    north = 27278
 
−
  },
 
−
  [11122] = {
 
−
    ["enter grate"] = 14551
 
−
  },
 
−
  [11112] = {
 
−
    ["enter grate"] = 14829
 
−
  },
 
−
  [24012] = {
 
−
    north = 22413
 
−
  },
 
−
  [11400] = {
 
−
    south = 10577
 
−
  },
 
−
  [11133] = {
 
−
    ["enter grate"] = 15610
 
−
  },
 
−
  [7091] = {
 
−
    down = 4411
 
−
  },
 
−
  [10659] = {
 
−
    ["enter grate"] = 15510
 
−
  }
 
−
}
 
−
]]
 
−
</syntaxhighlight>
 
  
−
==getAreaRooms==
+
:See also: [[#getPackages|getPackages]]
−
;getAreaRooms(area id)
 
  
−
:Returns an indexed table with all rooms IDs for a given area ID (room IDs are values), or ''nil'' if no such area exists.  
+
{{MudletVersion|4.12}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- using the sample findAreaID() function defined in the getAreaTable() example,
+
--Check if the module myTabChat is installed and if it isn't install it and enable sync on it
−
-- we'll define a function that echo's us a nice list of all rooms in an area with their ID
+
if not table.contains(getModules(),"myTabChat") then
−
function echoRoomList(areaname)
+
   installModule(getMudletHomeDir().."/modules/myTabChat.xml")
−
  local id, msg = findAreaID(areaname)
+
   enableModuleSync("myTabChat")
−
   if id then
+
end
−
    local roomlist, endresult = getAreaRooms(id), {}
 
−
 
 
−
    -- obtain a room list for each of the room IDs we got
 
−
    for _, id in pairs(roomlist) do
 
−
      endresult[id] = getRoomName(id)
 
−
    end
 
−
    
 
−
    -- now display something half-decent looking
 
−
    cecho(string.format(
 
−
      "List of all rooms in %s (%d):\n", msg, table.size(endresult)))
 
  
−
    for roomid, roomname in pairs(endresult) do
 
−
      cecho(string.format(
 
−
        "%6s: %s\n", roomid, roomname))
 
−
    end
 
−
  elseif not id and msg then
 
−
    echo("ID not found; " .. msg)
 
−
  else
 
−
    echo("No areas matched the query.")
 
−
  end
 
−
end
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==getAreaTable==
+
==getModuleInfo==
−
;areaTable = getAreaTable()
+
;getModuleInfo(moduleName, [info])
  
−
:Returns a key(area name)-value(area id) table with all known areas and their IDs.
+
:Returns table with meta information for a package
  
−
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
+
;Parameters
−
<div style="font-weight:bold;line-height:1.6;">Historical Version Note</div>
+
* ''moduleName:''
−
<div class="mw-collapsible-content">
+
:Name of the package
−
{{Note}} Some older versions of Mudlet return an area with an empty name and an ID of 0 included in it, you should ignore that.
+
* ''info:''
−
</div></div></div>
+
:(optional) specific info wanted to get, if not given all available meta-info is returned
  
−
;See also: [[#getAreaTableSwap|getAreaTableSwap()]]
+
:See also: [[#getPackageInfo|getPackageInfo]], [[#setModuleInfo|setModuleInfo]]
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- example function that returns the area ID for a given area
+
getModuleInfo("myModule","author")
−
 
 
−
function findAreaID(areaname)
 
−
  local list = getAreaTable()
 
−
 
 
−
  -- iterate over the list of areas, matching them with substring match.
 
−
  -- if we get match a single area, then return it's ID, otherwise return
 
−
  -- 'false' and a message that there are than one are matches
 
−
  local returnid, fullareaname
 
−
  for area, id in pairs(list) do
 
−
    if area:find(areaname, 1, true) then
 
−
      if returnid then return false, "more than one area matches" end
 
−
      returnid = id; fullareaname = area
 
−
    end
 
−
  end
 
−
 
 
−
  return returnid, fullareaname
 
−
end
 
−
 
 
−
-- sample use:
 
−
local id, msg = findAreaID("blahblah")
 
−
if id then
 
−
  echo("Found a matching ID: " .. id)
 
−
elseif not id and msg then
 
−
  echo("ID not found: " .. msg)
 
−
else
 
−
  echo("No areas matched the query.")
 
−
end
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==getAreaTableSwap==
+
{{MudletVersion|4.12}}
−
;areaTable = getAreaTableSwap()
 
  
−
:Returns a key(area id)-value(area name) table with all known areas and their IDs. Unlike getAreaTable which won't show you all areas with the same name by different IDs, this function will.
+
==getModuleSync==
−
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
+
;getModuleSync(name)
−
<div style="font-weight:bold;line-height:1.6;">Historical Version Note</div>
+
: returns false if module sync is not active, true if it is active and nil if module is not found.
−
<div class="mw-collapsible-content">
 
−
{{Note}} Some older versions of Mudlet return an area with an empty name and an ID of 0 included in it, you should ignore that.
 
−
</div></div></div>
 
  
−
==getAreaUserData==
+
;Parameter
−
;dataValue = getAreaUserData(areaID, key)
+
* ''name'': name of the module
  
−
:Returns a specific data item stored against the given key for the given area ID number.  This is very like the corresponding Room User Data command but intended for per area rather than for per room data (for storage of data relating to the whole map see the corresponding Map User Data commands.)
+
:See also: [[Manual:Lua_Functions#enableModuleSync|enableModuleSync()]], [[Manual:Lua_Functions#disableModuleSync|disableModuleSync()]]
 +
{{MudletVersion|4.8}}
  
−
:Returns the user data value (string) stored at a given room with a given key (string), or a Lua ''nil'' and an error message if the key is not present in the Area User Data for the given Area ID. Use [[#setAreaUserData|setAreaUserData()]] function for storing the user data.
+
==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.
  
−
;See also: [[#clearAreaUserData|clearAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#getAllAreaUserData|getAllAreaUserData()]], [[#searchAreaUserData|searchAreaUserData()]], [[#setAreaUserData|setAreaUserData()]]
+
{{note}} intentionally uses forward slashes <code>/</code> as separators on Windows since [[Manual:UI_Functions#setLabelStyleSheet|stylesheets]] require them.
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
display(getAreaUserData(34, "country"))
+
-- save a table
−
-- might produce --
+
table.save(getMudletHomeDir().."/myinfo.dat", myinfo)
−
"Andor"
 
−
</syntaxhighlight>
 
−
 
 
−
==getCustomEnvColorTable==
 
−
;envcolors = getCustomEnvColorTable()
 
−
 
 
−
:Returns a table with customized environments, where the key is the environment ID and the value is a indexed table of rgb values.
 
−
: See also: [[#setCustomEnvColor|setCustomEnvColor()]]
 
  
−
;Example
+
-- or access package data. The forward slash works even on Windows fine
−
<syntaxhighlight lang="lua">
+
local path = getMudletHomeDir().."/mypackagename"
−
{
 
−
  envid1 = {r, g, b, alpha},
 
−
  envid2 = {r, g, b, alpha}
 
−
}
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==getCustomLines==
+
==getMudletInfo==
−
;lineTable = getCustomLines(roomID)
+
;getMudletInfo()
−
: See also: [[#addCustomLine|addCustomLine()]], [[#removeCustomLine|removeCustomLine()]]
+
:Prints debugging information about the Mudlet that you're running - this can come in handy for diagnostics.
−
 
 
−
:Returns a table including all the details of the custom exit lines, if any, for the room with the id given.
 
  
−
;Parameters
+
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.
−
* ''roomID:''
 
−
: Room ID to return the custom line details of.
 
  
−
{{MudletVersion|3.0.}}
+
{{MudletVersion|4.8}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
display getCustomLines(1)
+
getMudletInfo()
−
{
 
−
  ["climb Rope"] = {
 
−
    attributes = {
 
−
      color = {
 
−
        b = 0,
 
−
        g = 128,
 
−
        r = 128
 
−
      },
 
−
      style = "dash dot dot line",
 
−
      arrow = false
 
−
    },
 
−
    points = {
 
−
      {
 
−
        y = 9.5,
 
−
        x = 4.5
 
−
      },
 
−
      {
 
−
        y = 9.5,
 
−
        x = 6
 
−
      },
 
−
      [0] = {
 
−
        y = 5.5,
 
−
        x = 4.5
 
−
      }
 
−
    }
 
−
  },
 
−
  N = {
 
−
    attributes = {
 
−
      color = {
 
−
        b = 255,
 
−
        g = 255,
 
−
        r = 0
 
−
      },
 
−
      style = "dot line",
 
−
      arrow = true
 
−
    },
 
−
    points = {
 
−
      [0] = {
 
−
        y = 27,
 
−
        x = -3
 
−
      }
 
−
    }
 
−
  }
 
−
}
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==getCustomLines1==
+
==getMudletVersion==
−
;lineTable = getCustomLines1(roomID)
+
;getMudletVersion(style)
−
This is a replacement for ''getCustomLines(...)'' that outputs the tables for the coordinates for the points on the custom line in an order and format that can be fed straight back into an ''addCustomLine(...)'' call; similarly the color parameters are also reported in the correct format to also be reused in the same manner. This function is intended to make it simpler for scripts to manipulate such lines.
+
: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: [[Manual:Mapper_Functions#addCustomLine|addCustomLine()]], [[Manual:Mapper_Functions#removeCustomLine|removeCustomLine()]], [[Manual:Mapper_Functions#getCustomLines|getCustomLines()]]
 
−
{{MudletVersion| 4.16}}
 
  
−
;Parameters
+
See also: [[#mudletOlderThan|mudletOlderThan()]]
−
* ''roomID:''
 
−
:Room ID to return the custom line details of.
 
  
−
;Returns
+
{{MudletVersion|3.0}}
−
:a table including all the details of the custom exit lines, if any, for the room with the id given.
 
−
 
 
−
;Example
 
−
<syntaxhighlight lang="lua">
 
−
display getCustomLines1(1)
 
−
{
 
−
  ["climb Rope"] = {
 
−
    attributes = {
 
−
      color = { 128, 128, 0 },
 
−
      style = "dash dot dot line",
 
−
      arrow = false
 
−
    },
 
−
    points = { { 4.5, 5.5, 3 }, { 4.5, 9.5, 3 }, { 6, 9.5, 3 } }
 
−
  },
 
−
  N = {
 
−
    attributes = {
 
−
      color = { 0, 255, 255 },
 
−
      style = "dot line",
 
−
      arrow = true
 
−
    },
 
−
    points = { { -3, 27, 3 } }
 
−
  }
 
−
}
 
−
</syntaxhighlight>
 
−
 
 
−
==getDoors==
 
−
;doors = getDoors(roomID)
 
−
 
 
−
:Returns a key-value table with the cardinal direction as the key and the door value as a number. If there are no doors in a room, it returns an empty table.
 
  
 
;Parameters
 
;Parameters
−
* ''roomID:''
+
* ''style:''
−
: Room ID to check for doors in.
+
:(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.
  
−
: See also: [[#setDoor|setDoor()]]
+
;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
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- an example that displays possible doors in room 2334
+
-- see the full Mudlet version as text:
−
local doors = getDoors(2334)
+
getMudletVersion("string")
 +
-- returns for example "3.0.0-alpha"
  
−
if not next(doors) then cecho("\nThere aren't any doors in room 2334.") return end
+
-- 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  
  
−
local door_status = {"open", "closed", "locked"}
+
-- if you'd like to see if a function is available however, test for it explicitly instead:
−
 
+
if setAppStyleSheet then
−
for direction, door in pairs(doors) do
+
   -- example credit to http://qt-project.org/doc/qt-4.8/stylesheet-examples.html#customizing-qscrollbar
−
   cecho("\nThere's a door leading in "..direction.." that is "..door_status[door]..".")
+
  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
 
end
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==getExitStubs==
+
==getNewIDManager==
−
;stubs = getExitStubs(roomid)
+
; getNewIDManager()
  
−
:Returns an indexed table (starting at 0) of the direction #'s that have an exit stub marked in them. You can use this information to connect earlier-made exit stubs between rooms when mapping.  Returns nil plus error message of called on a non-existent room.
+
:Returns an IDManager object, for manager your own set of named events and timers isolated from the rest of the profile.
  
−
: See also: [[#setExitStub|setExitStub()]], [[#connectExitStub|connectExitStub()]], [[#getExitStubs1|getExitStubs1()]]
+
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]]
  
−
;Example
+
{{MudletVersion|4.14}}
−
<syntaxhighlight lang="lua">
 
−
-- show the exit stubs in room 6 as numbers
 
−
local stubs = getExitStubs(6)
 
−
for i = 0, #stubs do print(stubs[i]) end
 
−
</syntaxhighlight>
 
−
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
 
−
<div style="font-weight:bold;line-height:1.6;">Historical Version Note</div>
 
−
<div class="mw-collapsible-content">
 
−
{{note}} Previously would throw a lua error on non-existent room - now returns nil plus error message (as does other run-time errors) - previously would return just a nil on NO exit stubs but now returns a notification error message as well, to aide disambiguation of the nil value.
 
−
</div></div></div>
 
  
−
==getExitStubs1==
+
{{note}} Full IDManager usage can be found at [[Manual:IDManager|IDManager]]
−
;stubs = getExitStubs1(roomid)
 
  
−
:Returns an indexed table (starting at 1) of the direction #'s that have an exit stub marked in them. You can use this information to connect earlier-made exit stubs between rooms when mapping. As this function starts indexing from 1 as it is default in Lua, you can use ipairs() to iterate over the results.
+
;Returns
−
 
+
* an IDManager for managing your own named events and timers
−
; See also: [[#getExitStubs|getExitStubs()]]
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- show the exit stubs in room 6 as numbers
+
demonnic = demonnic or {}
−
for k,v in ipairs(getExitStubs1(6)) do print(k,v) end
+
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>
  
−
==getExitWeights==
+
==getNamedEventHandlers==
−
;weights = getExitWeights(roomid)
+
; handlers = getNamedEventHandlers(userName)
  
−
:Returns a key-value table of the exit weights that a room has, with the direction or special exit as a key and the value as the exit weight. If a weight for a direction wasn't yet set, it won't be listed.
+
:Returns a list of all userName's named event handlers' names as a table.
  
−
;Parameters
+
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]]
−
* ''roomid:''
 
−
: Room ID to view the exit weights in.
 
  
−
: See also: [[#setExitWeight|setExitWeight()]]
+
{{MudletVersion|4.14}}
−
 
 
−
==getGridMode==
 
−
;TrueOrFalse = getGridMode(areaID)
 
−
 
 
−
:Use this to see, if a specific area has grid/wilderness view mode set. This way, you can also calculate from a script, how many grid areas a map has got in total.
 
−
 
 
−
{{MudletVersion|3.11}}
 
  
 
;Parameters
 
;Parameters
−
* ''areaID:''
+
* ''userName:''
−
: Area ID (number) to view the grid mode of.
+
: The user name the event handler was registered under.
  
−
: See also: [[#setGridMode|setGridMode()]]
+
;Returns
 +
* a table of handler names. { "DemonVitals", "DemonInv" } for example. {} if none are registered
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
getGridMode(55)
+
  local handlers = getNamedEventHandlers()
−
-- will return: false
+
  display(handlers)
−
setGridMode(55, true) -- set area with ID 55 to be in grid mode
+
  -- {}
−
getGridMode(55)
+
  registerNamedEventHandler("Test1", "testEvent", "testFunction")
−
-- will return: true
+
  registerNamedEventHandler("Test2", "someOtherEvent", myHandlerFunction)
 +
  handlers = getNamedEventHandlers()
 +
  display(handlers)
 +
  -- { "Test1", "Test2" }
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==getMapEvents==
+
==getOS==
−
; mapevents = getMapEvents()
+
;getOS()
  
−
: Returns a list of map events currently registered. Each event is a dictionary with the keys ''uniquename'', ''parent'', ''event name'', ''display name'', and ''arguments'', which correspond to the arguments of ''addMapEvent()''.
+
: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.
−
: See also: [[#addMapMenu|addMapMenu()]], [[#removeMapEvent|removeMapEvent()]], [[#addMapEvent|addMapEvent()]]
+
: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
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
addMapEvent("room a", "onFavorite") -- will make a label "room a" on the map menu's right click that calls onFavorite
+
display(getOS())
  
−
addMapEvent("room b", "onFavorite", "Favorites", "Special Room!", 12345, "arg1", "arg2", "argn")
+
if getOS() == "windows" then
 +
  echo("\nWindows OS detected.\n")
 +
else
 +
  echo("\nDetected Operating system is NOT windows.\n")
 +
end
  
−
local mapEvents = getMapEvents()
+
if mudlet.supports.osVersion then
−
for _, event in ipairs(mapEvents) do
+
  local os, osversion = getOS()
−
   echo(string.format("MapEvent '%s' is bound to event '%s' with these args: '%s'", event["uniquename"], event["event name"], table.concat(event["arguments"], ",")))
+
   print(f"Running {os} {osversion}")
 
end
 
end
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
{{MudletVersion|3.3}}
+
==getPackages==
−
 
+
;getPackages()
−
==getMapLabel==
 
−
;labelinfo = getMapLabel(areaID, labelID or labelText)
 
  
−
:Returns a key-value table describing that particular label in an area. Keys it contains are the ''X'', ''Y'', ''Z'' coordinates, ''Height'' and ''Width'', ''BgColor'', ''FgColor'', ''Pixmap'', and the ''Text'' it contains. If the label is an image label, then ''Text'' will be set to the ''no text'' string.
+
:Returns installed packages as table.
  
−
:''BgColor'' and ''FgColor'' are tables with ''r'',''g'',''b'' keys, each holding ''0-255'' color component value.
+
:See also: [[#getModules|getModules]]
  
−
:''Pixmap'' is base64 encoded image of label.
+
{{MudletVersion|4.12}}
−
 
 
−
{{note}} ''BgColor'', ''FgColor'', ''Pixmap'' are available in Mudlet 4.11+
 
−
 
 
−
;Parameters
 
−
* ''areaID:'' areaID from which to retrieve label
 
−
* ''labelID:'' labelID (''getMapLabels'' return table key) or labelText (exact match)
 
−
 
 
−
See also: [[#createMapLabel|createMapLabel()]], [[#getMapLabels|getMapLabels()]]
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
lua getMapLabels(52)
+
--Check if the generic_mapper package is installed and if so uninstall it
−
{
+
if table.contains(getPackages(),"generic_mapper") then
−
  "no text",
+
   uninstallPackage("generic_mapper")
−
   [0] = "test"
+
end
−
}
 
  
−
lua getMapLabel(52, 0)
+
</syntaxhighlight>
−
{
 
−
  Y = -2,
 
−
  X = -8,
 
−
  Z = 11,
 
−
  Height = 3.9669418334961,
 
−
  Text = "test",
 
−
  Width = 8.6776866912842,
 
−
  BgColor = {
 
−
    b = 0,
 
−
    g = 0,
 
−
    r = 0
 
−
  },
 
−
  FgColor = {
 
−
    b = 50,
 
−
    g = 255,
 
−
    r = 255
 
−
  },
 
−
  Pixmap = "iVBORw0KG(...)lFTkSuQmCC" -- base64 encoded png image (shortened for brevity)
 
−
}
 
  
−
lua getMapLabel(52, "no text")
+
==getPackageInfo==
−
{
+
;getPackageInfo(packageName, [info])
−
  Y = 8,
 
−
  X = -15,
 
−
  Z = 11,
 
−
  Height = 7.2520666122437,
 
−
  Text = "no text"
 
−
  Width = 11.21900844574,
 
−
  BgColor = {
 
−
    b = 0,
 
−
    g = 0,
 
−
    r = 0
 
−
  },
 
−
  FgColor = {
 
−
    b = 50,
 
−
    g = 255,
 
−
    r = 255
 
−
  },
 
−
  Pixmap = "iVBORw0KG(...)lFTkSuQmCC" -- base64 encoded png image (shortened for brevity)
 
−
}
 
−
</syntaxhighlight>
 
  
−
==getMapLabels==
+
:Returns table with meta information for a package
−
;arealabels = getMapLabels(areaID)
 
  
−
:Returns an indexed table (that starts indexing from 0) of all of the labels in the area, plus their label text. You can use the label id to [[#deleteMapLabel|deleteMapLabel()]] it.
+
;Parameters
−
:If there are no labels in the area at all, it will return an empty table.
+
* ''packageName:''
 +
:Name of the package
 +
* ''info:''
 +
:(optional) specific info wanted to get, if not given all available meta-info is returned
  
−
: See also: [[#createMapLabel|createMapLabel()]], [[#getMapLabel|getMapLabel()]], [[#deleteMapLabel|deleteMapLabel()]]
+
:See also: [[#getModuleInfo|getModuleInfo]], [[#setPackageInfo|setPackageInfo]]
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
display(getMapLabels(43))
+
getPackageInfo("myPackage", "version")
−
table {
 
−
  0: ''
 
−
  1: 'Waterways'
 
−
}
 
−
 
 
−
deleteMapLabel(43, 0)
 
−
display(getMapLabels(43))
 
−
table {
 
−
  1: 'Waterways'
 
−
}
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==getMapMenus==
+
{{MudletVersion|4.12}}
−
;getMapMenus()
 
  
−
:Returns a table with the available map menus as key-value in the format of <code>map menu - parent item</code>. If an item is positioned at the menu's top-level, the value will say <code>top-level</code>.
+
==getPlayingMusic==
−
:If you haven't opened a map yet, getMapMenus() will return nil+error message. If you don't have any map labels yet, an empty table <code>{}</code> is returned.
+
;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()]].
  
−
: See also: [[#addMapMenu|addMapMenu()]], [[#addMapEvent|addMapEvent()]]
+
{| 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".
 +
|-
 +
| style="text-align:center;"| No
 +
| tag
 +
| <tag>
 +
|
 +
| style="text-align:left;"|
 +
* Helps categorize media.
 +
|-
 +
|}
  
−
;Example
+
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]]
−
<syntaxhighlight lang="lua">
 
−
-- given the following menu structure:
 
−
top-level
 
−
  menu1
 
−
    menu1.1
 
−
      action1.1.1
 
−
    menu1.2
 
−
      action1.2.1
 
−
  menu2
 
  
−
getMapMenus() -- will return:
+
{{MudletVersion|4.18}}
−
{
 
−
  menu2 = "top-level",
 
−
  menu1.2 = "menu1",
 
−
  menu1.1 = "menu1",
 
−
  menu1 = "top-level"
 
−
}
 
−
</syntaxhighlight>
 
  
−
==getMapSelection==
+
;Example
−
; getMapSelection()
 
  
−
:Returns a table containing details of the current mouse selection in the 2D mapper.
+
<syntaxhighlight lang="lua">
 +
---- Table Parameter Syntax ----
  
−
:Reports on one or more rooms being selected (i.e. they are highlighted in orange).
+
-- List all playing music files for this profile associated with the API
 +
getPlayingMusic()
  
−
:The contents of the table will vary depending on what is currently selected. If the selection is of map rooms then there will be keys of ''center'' and ''rooms'': the former will indicates the center room (the one with the yellow cross-hairs) if there is more than one room selected or the only room if there is only one selected (there will not be cross-hairs in that case); the latter will contain a list of the one or more rooms.
+
-- List all playing music matching the rugby mp3 name
 +
getPlayingMusic({name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"})
  
−
; Example - several rooms selected
+
-- List all playing music matching the unique key of "rugby"
−
<syntaxhighlight lang="lua">
+
getPlayingMusic({
−
display(getMapSelection())
+
    name = nil  -- nil lines are optional, no need to use
−
{
+
     , key = "rugby" -- key
−
  center = 5013,
+
     , tag = nil  -- nil lines are optional, no need to use
−
  rooms = {
+
})
−
     5011,
 
−
     5012,
 
−
    5013,
 
−
    5014,
 
−
    5018,
 
−
    5019,
 
−
    5020
 
−
  }
 
−
}
 
 
</syntaxhighlight>
 
</syntaxhighlight>
−
; Example - one room selected
 
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
display(getMapSelection())
+
---- Ordered Parameter Syntax of getPlayingMusic([name][,key][,tag]) ----
−
{
 
−
  center = 5013,
 
−
  rooms = {
 
−
    5013
 
−
  }
 
−
}
 
−
</syntaxhighlight>
 
−
; Example - no or something other than a room selected
 
−
<syntaxhighlight lang="lua">
 
−
display(getMapSelection())
 
−
{
 
−
}
 
−
</syntaxhighlight>
 
  
−
{{MudletVersion|3.17}}
+
-- List all playing music files for this profile associated with the API
 +
getPlayingMusic()
  
−
==getMapUserData==
+
-- List all playing music matching the rugby mp3 name
−
;getMapUserData( key )
+
getPlayingMusic("167124__patricia-mcmillen__rugby-club-in-spain.mp3")
  
−
;Parameters
+
-- List all playing music matching the unique key of "rugby"
−
* ''key:''
+
getPlayingMusic(
−
: string used as a key to select the data stored in the map as a whole.
+
    nil -- name
−
 
+
    , "rugby" -- key
−
:Returns the user data item (string); will return a nil+error message if there is no data with such a key in the map data.
+
    , nil -- tag
 +
)
 +
</syntaxhighlight>
  
−
: See also: [[#getAllMapUserData|getAllMapUserData()]], [[#setMapUserData|setMapUserData()]]
+
==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
−
display(getMapUserData("last updated"))
+
! Key
−
--might result in:--
+
! Value
−
"December 5, 2020"
+
!Default
−
</syntaxhighlight>
+
! 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".
 +
|-
 +
| 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.
 +
|-
 +
|}
  
−
{{MudletVersion|3.0}}
+
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]]
  
−
==getMapZoom==
+
{{MudletVersion|4.18}}
−
;getMapZoom([areaID])
 
  
−
:Gets the current 2D map zoom level. Added in '''Mudlet ''4.17.0''''' also with the option to get the zoom for an area to be specified even if it is not the one currently being viewed. This change is combined with Mudlet remembering the zoom level last used for each area and with the revision of the ''setMapZoom()'' function to also take an areaID to work on instead of the current area being viewed in the map.
+
;Example
  
−
:See also: [[Manual:Mapper_Functions#setMapZoom|setMapZoom()]].
+
<syntaxhighlight lang="lua">
 +
---- Table Parameter Syntax ----
  
−
{{MudletVersion| 4.17.0}}
+
-- List all playing sounds for this profile associated with the API
 +
getPlayingSounds()
  
−
;Parameters
+
-- List all playing sounds matching the rugby mp3 name
−
* ''areaID:''
+
getPlayingSounds({name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"})
−
: Area ID number to get the 2D zoom for (''optional'', the function works on the area currently being viewed if this is omitted).
 
  
−
;Returns
+
-- List the playing sound matching the unique key of "rugby"
−
* A floating point number on success
+
getPlayingSounds({
−
* ''nil'' and an error message on failure.
+
    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 getPlayingSounds([name][,key][,tag][,priority]) ----
  
−
;Example
+
-- List all playing sounds for this profile associated with the API
−
<syntaxhighlight lang="lua">
+
getPlayingSounds()
−
echo("\nCurrent zoom level: " .. getMapZoom() .. "\n")
 
−
-- Could be anything from 3 upwards:
 
  
−
Current zoom level: 42.4242
+
-- List all playing sounds matching the rugby mp3 name
 +
getPlayingSounds("167124__patricia-mcmillen__rugby-club-in-spain.mp3")
  
−
setMapZoom(2.5 + getMapZoom(1), 1) -- zoom out the area with ID 1 by 2.5
+
-- List the playing sound matching the unique key of "rugby"
−
true
+
getPlayingSounds(
 +
    nil -- name
 +
    , "rugby" -- key
 +
    , nil -- tag
 +
    , nil -- priority
 +
)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
{{note}} The precise meaning of a particular zoom value may have an underlying meaning however that has not been determined other than that the minimum value is ''3.0'' and the initial value - and what prior Mudlet versions started each session with - is ''20.0''.
+
==getProfileName==
−
 
+
;getProfileName()
−
==getPath==
 
−
;getPath(roomID from, roomID to)
 
−
 
 
−
:Returns a boolean true/false if a path between two room IDs is possible. If it is, the global ''speedWalkDir'' table is set to all of the directions that have to be taken to get there, and the global ''speedWalkPath'' table is set to all of the roomIDs you'll encounter on the way, and as of 3.0, ''speedWalkWeight'' will return all of the room weights. Additionally returns the total cost (all weights added up) of the path after the boolean argument in 3.0.
 
  
 +
: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.
  
−
: See also: [[Manual:Lua_Functions#translateTable|translateTable()]]
+
{{MudletVersion|3.1}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- check if we can go to room 155 from room 34 - if yes, go to it
+
-- if connected to the Achaea profile, will print Achaea to the main console
−
if getPath(34,155) then
+
echo(getProfileName())
−
  gotoRoom(155)
 
−
else
 
−
  echo("\nCan't go there!")
 
−
end
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==getPlayerRoom==
+
==getCommandSeparator==
−
;getPlayerRoom()
+
;getCommandSeparator()
  
−
:Returns the current player location as set by [[#centerview|centerview()]].
+
:Returns the command separator in use by the profile.
  
−
: See also: [[#centerview|centerview]]
+
{{MudletVersion|3.18}}
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
display("We're currently in " .. getRoomName(getPlayerRoom()))
+
-- 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>
  
−
{{MudletVersion|3.14}}
+
==getServerEncoding==
−
 
+
;getServerEncoding()
−
==getRoomArea==
+
:Returns the current server [https://www.w3.org/International/questions/qa-what-is-encoding data encoding] in use.
−
;getRoomArea(roomID)
 
−
 
 
−
:Returns the area ID of a given room ID. To get the area name, you can check the area ID against the data given by [[#getAreaTable | getAreaTable()]] function, or use the [[#getRoomAreaName |getRoomAreaName()]] function.
 
  
−
{{note}} If the room ID does not exist, this function will raise an error.
+
:See also: [[#setServerEncoding|setServerEncoding()]], [[#getServerEncodingsList|getServerEncodingsList()]]
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
display("Area ID of room #100 is: "..getRoomArea(100))
+
getServerEncoding()
−
 
 
−
display("Area name for room #100 is: "..getRoomAreaName(getRoomArea(100)))
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==getRoomAreaName==
+
==getServerEncodingsList==
−
;getRoomAreaName(areaID or areaName)
+
;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.
−
:Returns the area name for a given area id; or the area id for a given area name.
 
  
−
{{note}} Despite the name, this function will not return the area name for a given ''room'' id (or room name) directly. However, renaming or revising it would break existing scripts.
+
:See also: [[#setServerEncoding|setServerEncoding()]], [[#getServerEncoding|getServerEncoding()]]
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
echo(string.format("room id #455 is in %s.", getRoomAreaName(getRoomArea(455))))
+
-- check if UTF-8 is available:
 +
if table.contains(getServerEncodingsList(), "UTF-8") then
 +
  print("UTF-8 is available!")
 +
end
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 +
==getWindowsCodepage==
 +
;getWindowsCodepage()
 +
:Returns the current [https://docs.microsoft.com/en-us/windows/desktop/Intl/code-page-identifiers codepage] of your Windows system.
  
−
==getRoomChar==
+
{{MudletVersion|3.22}}
−
;getRoomChar(roomID)
+
{{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.
  
−
:Returns the single ASCII character that forms the ''symbol'' for the given room id.
+
;Example
−
 
+
<syntaxhighlight lang="lua">
−
: '''Since Mudlet version 3.8 :''' this facility has been extended:
+
print(getWindowsCodepage())
−
: Returns the string (UTF-8) that forms the ''symbol'' for the given room id; this may have been set with either [[#setRoomChar|setRoomChar()]] or with the ''symbol'' (was ''letter'' in prior versions) context menu item for rooms in the 2D Map.
+
</syntaxhighlight>
−
 
 
−
==getRoomCharColor==
 
−
;r,g,b = getRoomCharColor(roomID)
 
−
 
 
−
:Returns the color of the Room Character as a set of r,g,b color coordinates.
 
  
−
;See also: [[Manual:Lua_Functions#setRoomCharColor|setRoomCharColor()]], [[Manual:Lua_Functions#getRoomChar|getRoomChar()]]
+
==hfeedTriggers==
 +
;hfeedTriggers(str)
 +
:Like feedTriggers, but you can add color information using #RRGGBB in hex, similar to hecho.
  
 
;Parameters
 
;Parameters
−
* ''roomID:''
+
* ''str'': The string to feed to the trigger engine. Include color information in the same manner as hecho.
−
: The room ID to get the room character color from
+
:See also: [[Manual:Lua_Functions#dfeedTriggers|dfeedTriggers]]
 +
:See also: [[Manual:Lua_Functions#hecho|hecho]]
  
−
;Returns
+
{{MudletVersion|4.11}}
−
* The color as 3 separate numbers, red, green, and blue from 0-255
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- gets the color of the room character set on room 12345. If no room character is set the default 'color' is 0,0,0
+
hfeedTriggers("#008000,800000green on red#r reset\n")
−
local r,g,b = getRoomCharColor(12345)
 
−
decho(f"Room Character for room 12345 is <{r},{g},{b}>this color.<r> It is made up of <{r},0,0>{r} red<r>, <0,{g},0>{g} green<r>, <0,0,{b}> {b} blue<r>.\")
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==getRoomCoordinates==
+
==installModule==
−
;x,y,z = getRoomCoordinates(roomID)
+
;installModule(location)
 +
:Installs a Mudlet XML, zip, or mpackage as a module.
  
−
:Returns the room coordinates of the given room ID.
+
;Parameters
 +
* ''location:''
 +
:Exact location of the file install.
  
−
;See also: [[Manual:Lua_Functions#setRoomCoordinates|setRoomCoordinates()]]
+
:See also: [[#uninstallModule | uninstallModule()]], [[Manual:Event_Engine#sysLuaInstallModule | Event: sysLuaInstallModule]], [[#setModulePriority | setModulePriority()]]
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
local x,y,z = getRoomCoordinates(roomID)
+
installModule([[C:\Documents and Settings\bub\Desktop\myalias.xml]])
−
echo("Room Coordinates for "..roomID..":")
 
−
echo("\n    X:"..x)
 
−
echo("\n    Y:"..y)
 
−
echo("\n    Z:"..z)
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
<syntaxhighlight lang="lua">
+
==installPackage==
−
-- A quick function that will find all rooms on the same z-position in an area; this is useful if, say, you want to know what all the same rooms on the same "level" of an area is.
+
;installPackage(location or url)
−
function sortByZ(areaID, zval)
+
:Installs a Mudlet XML or package. Since Mudlet 4.11+ returns <code>true</code> if it worked, or <code>false</code>.
−
  local area = getAreaRooms(areaID)
 
−
  local t = {}
 
−
  for _, id in ipairs(area) do
 
−
    local _, _, z = getRoomCoordinates(id)
 
−
    if z == zval then
 
−
      table.insert(t, id)
 
−
    end
 
−
  end
 
−
  return t
 
−
end
 
−
</syntaxhighlight>
 
  
−
==getRoomEnv==
+
;Parameters
−
;envID = getRoomEnv(roomID)
+
* ''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>)
  
−
:Returns the environment ID of a room. The mapper does not store environment names, so you'd need to keep track of which ID is what name yourself.
+
:See also: [[#uninstallPackage | uninstallPackage()]]
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
function checkID(id)
+
installPackage([[C:\Documents and Settings\bub\Desktop\myalias.xml]])
−
  echo(string.format("The env ID of room #%d is %d.\n", id, getRoomEnv(id)))
 
−
end
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
== getRoomExits ==
 
−
;getRoomExits (roomID)
 
−
:Returns the currently known non-special exits for a room in an key-index form: ''exit = exitroomid''.
 
−
 
−
: See also: [[#getSpecialExits|getSpecialExits()]]
 
−
 
−
;Example
 
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
table {
+
installPackage([[https://github.com/Mudlet/Mudlet/blob/development/src/run-lua-code-v4.xml]])
−
  'northwest': 80
 
−
  'east': 78
 
−
}
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
Here's a practical example that queries the rooms around you and searched for one of the water environments (the number would depend on how it was mapped):
+
==killAnonymousEventHandler==
 +
;killAnonymousEventHandler(handler id)
 +
:Disables and removes the given event handler.
  
−
<syntaxhighlight lang="lua">
+
;Parameters
−
local exits = getRoomExits(mycurrentroomid)
+
* ''handler id''
−
for direction,num in pairs(exits) do
+
:ID of the event handler to remove as returned by the [[ #registerAnonymousEventHandler | registerAnonymousEventHandler ]] function.
−
  local env_num = getRoomEnv(num)
 
−
  if env_num == 22 or env_num == 20 or env_num == 30 then
 
−
    print("There's water to the "..direction.."!")
 
−
  end
 
−
end</syntaxhighlight>
 
  
−
==getRoomHashByID==
+
:See also: [[ #registerAnonymousEventHandler | registerAnonymousEventHandler ]]
−
;getRoomHashByID(roomID)
 
−
 
 
−
:Returns a room hash that is associated with a given room ID in the mapper. This is primarily for games that make use of hashes instead of room IDs. It may be used to share map data while not sharing map itself. ''nil'' is returned if no room is not found.
 
−
 
 
−
: See also: [[#getRoomIDbyHash|getRoomIDbyHash()]]
 
−
{{MudletVersion|3.13.0}}
 
  
 +
{{MudletVersion|3.5}}
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
    for id,name in pairs(getRooms()) do
+
-- registers an event handler that prints the first 5 GMCP events and then terminates itself
−
        local h = getRoomUserData(id, "herbs")
+
 
−
        if h ~= "" then
+
local counter = 0
−
            echo(string.format([[["%s"] = "%s",]], getRoomHashByID(id), h))
+
local handlerId = registerAnonymousEventHandler("gmcp", function(_, origEvent)
−
            echo("\n")
+
  print(origEvent)
−
        end
+
  counter = counter + 1
−
    end
+
  if counter == 5 then
 +
    killAnonymousEventHandler(handlerId)
 +
  end
 +
end)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==getRoomIDbyHash==
+
==loadMusicFile==
−
;roomID = getRoomIDbyHash(hash)
+
;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
 +
! 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.
 +
|-
 +
|}
  
−
:Returns a room ID that is associated with a given hash in the mapper. This is primarily for games that make use of hashes instead of room IDs (like [http://avalon.mud.de/index.php?enter=1 Avalon.de]). ''-1'' is returned if no room ID matches the hash.
+
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]]
  
−
: See also: [[#getRoomHashByID|getRoomHashByID()]]
+
{{MudletVersion|4.15}}
  
 
;Example
 
;Example
 +
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- example taken from http://forums.mudlet.org/viewtopic.php?f=13&t=2177
+
---- Table Parameter Syntax ----
−
local id = getRoomIDbyHash("5dfe55b0c8d769e865fd85ba63127fbc")
 
−
if id == -1 then
 
−
  id = createRoomID()
 
−
  setRoomIDbyHash(id, "5dfe55b0c8d769e865fd85ba63127fbc")
 
−
  addRoom(id)
 
−
  setRoomCoordinates(id, 0, 0, -1)
 
−
end
 
−
</syntaxhighlight>
 
  
−
==getRoomName==
+
-- Download from the Internet
−
;getRoomName(roomID)
+
loadMusicFile({
 +
    name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"
 +
    , url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"
 +
})
  
−
:Returns the room name for a given room id.
+
-- OR download from the profile
 +
loadMusicFile({name = getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3"})
  
−
;Example
+
-- OR download from the local file system
 +
loadMusicFile({name = "C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3"})
 +
</syntaxhighlight>
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
echo(string.format("The name of the room id #455 is %s.", getRoomName(455))
+
---- Ordered Parameter Syntax of loadMusicFile(name[, url]) ----
−
</syntaxhighlight>
 
  
−
==getRooms==
+
-- Download from the Internet
−
;rooms = getRooms()
+
loadMusicFile(
 +
    "167124__patricia-mcmillen__rugby-club-in-spain.mp3"
 +
    , "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"
 +
)
  
−
:Returns the list of '''all''' rooms in the map in the whole map in roomid - room name format.
+
-- OR download from the profile
 +
loadMusicFile(getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3")
  
−
;Example
+
-- OR download from the local file system
−
<syntaxhighlight lang="lua">
+
loadMusicFile("C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3")
−
-- simple, raw viewer for rooms in the world
+
</syntaxhighlight>
−
display(getRooms())
 
  
−
-- iterate over all rooms in code
+
==loadSoundFile==
−
for id,name in pairs(getRooms()) do
+
;loadSoundFile(settings table) or loadSoundFile(name, [url])
−
  print(id, name)
+
: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. 
−
end
 
−
</syntaxhighlight>
 
  
−
==getRoomsByPosition==
+
{| class="wikitable"
−
;roomTable = getRoomsByPosition(areaID, x,y,z)
+
! Required
 +
! 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.
 +
|-
 +
|}
  
−
:Returns an indexed table of all rooms at the given coordinates in the given area, or an empty one if there are none. This function can be useful for checking if a room exists at certain coordinates, or whenever you have rooms overlapping.
+
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]]
  
−
{{note}} The returned table starts indexing from '''0''' and not the usual lua index of '''1''', which means that using '''#''' to count the size of the returned table will produce erroneous results - use [[Manual:Table_Functions#table.size|table.size()]] instead.
+
{{MudletVersion|4.15}}
  
 
;Example
 
;Example
 +
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- sample alias to determine a room nearby, given a relative direction from the current room
+
---- Table Parameter Syntax ----
−
 
 
−
local otherroom
 
−
if matches[2] == "" then
 
−
  local w = matches[3]
 
−
  local ox, oy, oz, x,y,z = getRoomCoordinates(mmp.currentroom)
 
−
  local has = table.contains
 
−
  if has({"west", "left", "w", "l"}, w) then
 
−
    x = (x or ox) - 1; y = (y or oy); z = (z or oz)
 
−
  elseif has({"east", "right", "e", "r"}, w) then
 
−
    x = (x or ox) + 1; y = (y or oy); z = (z or oz)
 
−
  elseif has({"north", "top", "n", "t"}, w) then
 
−
    x = (x or ox); y = (y or oy) + 1; z = (z or oz)
 
−
  elseif has({"south", "bottom", "s", "b"}, w) then
 
−
    x = (x or ox); y = (y or oy) - 1; z = (z or oz)
 
−
  elseif has({"northwest", "topleft", "nw", "tl"}, w) then
 
−
    x = (x or ox) - 1; y = (y or oy) + 1; z = (z or oz)
 
−
  elseif has({"northeast", "topright", "ne", "tr"}, w) then
 
−
    x = (x or ox) + 1; y = (y or oy) + 1; z = (z or oz)
 
−
  elseif has({"southeast", "bottomright", "se", "br"}, w) then
 
−
    x = (x or ox) + 1; y = (y or oy) - 1; z = (z or oz)
 
−
  elseif has({"southwest", "bottomleft", "sw", "bl"}, w) then
 
−
    x = (x or ox) - 1; y = (y or oy) - 1; z = (z or oz)
 
−
  elseif has({"up", "u"}, w) then
 
−
    x = (x or ox); y = (y or oy); z = (z or oz) + 1
 
−
  elseif has({"down", "d"}, w) then
 
−
    x = (x or ox); y = (y or oy); z = (z or oz) - 1
 
−
  end
 
  
−
  local carea = getRoomArea(mmp.currentroom)
+
-- Download from the Internet
−
  if not carea then mmp.echo("Don't know what area are we in.") return end
+
loadSoundFile({
 +
    name = "cow.wav"
 +
    , url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"
 +
})
  
−
  otherroom = select(2, next(getRoomsByPosition(carea,x,y,z)))
+
-- OR download from the profile
 +
loadSoundFile({name = getMudletHomeDir().. "/cow.wav"})
  
−
  if not otherroom then
+
-- OR download from the local file system
−
    mmp.echo("There isn't a room to the "..w.." that I see - try with an exact room id.") return
+
loadSoundFile({name = "C:/Users/Tamarindo/Documents/cow.wav"})
−
  else
 
−
    mmp.echo("The room "..w.." of us has an ID of "..otherroom)
 
−
  end
 
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
<syntaxhighlight lang="lua">
 +
---- Ordered Parameter Syntax of loadSoundFile(name[,url]) ----
  
−
==getRoomUserData==
+
-- Download from the Internet
−
;getRoomUserData(roomID, key)
+
loadSoundFile("cow.wav", "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/")
  
−
:Returns the user data value (string) stored at a given room with a given key (string), or "" if none is stored. Use [[#setRoomUserData|setRoomUserData()]] function for setting the user data.
+
-- OR download from the profile
 +
loadSoundFile(getMudletHomeDir().. "/cow.wav")
  
−
;Example
+
-- OR download from the local file system
−
<syntaxhighlight lang="lua">
+
loadSoundFile("C:/Users/Tamarindo/Documents/cow.wav")
−
display(getRoomUserData(341, "visitcount"))
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
:;getRoomUserData(roomID, key, enableFullErrorReporting)
+
==mudletOlderThan==
 +
;mudletOlderThan(major, [minor], [patch])
 +
:Returns true if Mudlet is older than the given version to check. This is useful if you'd like to use a feature that you can't check for easily, such as coroutines support. However, if you'd like to check if a certain function exists, do not use this and use <code>if mudletfunction then</code> - it'll be much more readable and reliable.
  
−
::Returns the user data value (string) stored at a given room with a given key (string), or, if the boolean value ''enableFullErrorReporting'' is true, ''nil'' and an error message if the key is not present or the room does not exist; if ''enableFullErrorReporting'' is false an empty string is returned but then it is not possible to tell if that particular value is actually stored or not against the given key.
+
See also: [[#getMudletVersion|getMudletVersion()]]
  
−
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserDataKeys|getRoomUserDataKeys()]], [[#searchRoomUserData|searchRoomUserData()]], [[#setRoomUserData|setRoomUserData()]]
+
;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
 
;Example
−
<!-- I would like this block to be indented to match the Example header but the mark-up system seems to be broken and only includes the first line
+
<syntaxhighlight lang="lua">
−
if the start of the code line begins: ":<lua>..."-->
+
-- stop doing the script of Mudlet is older than 3.2
−
<syntaxhighlight lang="lua">local vNum = 341
+
if mudletOlderThan(3,2) then return end
−
result, errMsg = getRoomUserData(vNum, "visitcount", true)
 
−
if result ~= nil then
 
−
    display(result)
 
−
else
 
−
    echo("\nNo visitcount data for room: "..vNum.."; reason: "..errMsg.."\n")
 
−
end</syntaxhighlight>
 
−
 
 
−
==getRoomUserDataKeys==
 
−
;getRoomUserDataKeys(roomID)
 
  
−
:Returns all the keys for user data items stored in the given room ID; will return an empty table if there is no data stored or nil if there is no such room with that ID. ''Can be useful if the user was not the one who put the data in the map in the first place!''
+
-- or older than 2.1.3
 +
if mudletOlderThan(2, 1, 3) then return end
  
−
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserData|getRoomUserData()]], [[#searchRoomUserData|searchRoomUserData()]], [[#setRoomUserData|setRoomUserData()]]
+
-- however, if you'd like to check that a certain function is available, like getMousePosition(), do this instead:
 +
if not getMousePosition then return end
  
−
;Example
+
-- if you'd like to check that coroutines are supported, do this instead:
−
<syntaxhighlight lang="lua">
+
if not mudlet.supportscoroutines then return end
−
display(getRoomUserDataKeys(3441))
 
−
--might result in:--
 
−
{
 
−
  "description",
 
−
  "doorname_up",
 
−
}
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
{{MudletVersion|3.0}}
+
==openWebPage==
 +
;openWebPage(URL)
 +
:Opens the browser to the given webpage.
  
−
==getRoomWeight==
+
;Parameters
−
;getRoomWeight(roomID)
+
* ''URL:''
−
 
+
:Exact URL to open.
−
:Returns the weight of a room. By default, all new rooms have a weight of 1.
 
−
: See also: [[#setRoomWeight|setRoomWeight()]]
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
display("Original weight of room 541: "..getRoomWeight(541))
+
openWebPage("http://google.com")
−
setRoomWeight(541, 3)
 
−
display("New weight of room 541: "..getRoomWeight(541))
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==getSpecialExits==
+
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://".
−
;exits = getSpecialExits(roomID[, listAllExits])
 
−
 
 
−
;Parameters
 
−
* ''roomID:''
 
−
: Room ID to return the special exits of.
 
−
* ''listAllExits:''
 
−
: In the case where there is more than one special exit to the same room ID list all of them.
 
−
 
 
−
: Returns a roomid table of sub-tables containing name/command and exit lock status, of the special exits in the room. If there are no special exits in the room, the table returned will be empty
 
−
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
 
−
<div style="font-weight:bold;line-height:1.6;">Historical Version Note</div>
 
−
<div class="mw-collapsible-content">
 
−
: (Since ''TBA'') In the case where there is more than one special exit to the same room ID list all of them.
 
−
:Before ''TBA'' (likely to be Mudlet version '''4.11.0'''), if more than one special exit goes to the ''same'' exit room id then one of those exits is returned at random. Since ''TBA'' this will be the best (i.e. lowest-weight) exit that is '''not''' locked; should none be unlocked then the lowest locked one will be listed. In case of a tie, one of the tying exits will be picked at random.
 
−
</div></div></div>
 
−
: See also: [[#getRoomExits|getRoomExits()]]
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- There are three special exits from 1337 to the room 42:
+
openWebPage("file:///"..getMudletHomeDir().."file.txt")
−
-- "climb down ladder" which is locked and has an exit weight of 10
 
−
-- "step out window" which is unlocked and has an exit weight of 20
 
−
-- "jump out window" which is unlocked and has an exit weight of 990
 
−
getSpecialExits(1337)
 
−
 
 
−
-- In 4.10.1 and before this could results in:
 
−
table {
 
−
  42 = {"jump out window" = "0"},
 
−
  666 = {"dive into pit" = "1"}
 
−
}
 
−
-- OR
 
−
table {
 
−
  42 = {"climb down ladder" = "1"},
 
−
  666 = {"dive into pit" = "1"}
 
−
}
 
−
-- OR
 
−
table {
 
−
  42 = {"step out window" = "0"},
 
−
  666 = {"dive into pit" = "1"}
 
−
}
 
−
 
 
−
-- From TBA this will return:
 
−
table {
 
−
  42 = {"step out window" = "0"},
 
−
  666 = {"dive into pit" = "1"}
 
−
}
 
−
 
 
−
-- From TBA, with the second argument as true, this gives:
 
−
getSpecialExits(1337, true)
 
−
table {
 
−
  42 = {"step out window" = "0",
 
−
        "climb down ladder" = "1",
 
−
        "jump out window" = "0"},
 
−
  666 = {"dive into pit" = "1"}
 
−
}
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==getSpecialExitsSwap==
+
==playMusicFile==
−
;getSpecialExitsSwap(roomID)
+
;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()]].
  
−
:Very similar to [[#getSpecialExits|getSpecialExits()]] function, but returns the rooms in the command - roomid style.
+
{| class="wikitable"
 +
! Required
 +
! Key
 +
! Value
 +
! Default
 +
! style="text-align:left;"| Purpose
 +
|- style="color: green;"
 +
| style="text-align:center;"| Yes
 +
| name
 +
| <file name>
 +
| &nbsp;
 +
| 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")
 +
* Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.
 +
|-
 +
| style="text-align:center;"| No
 +
| volume
 +
| 1 to 100
 +
| 50
 +
| style="text-align:left;"|
 +
* Relative to the volume set on the player's client.
 +
|-
 +
| style="text-align:center;"| 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.
 +
|-
 +
| style="text-align:center;" |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.
 +
|-
 +
| style="text-align:center;"| No
 +
| start
 +
| <msec>
 +
| 0
 +
| style="text-align:left;"|
 +
*  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
 +
| loops
 +
| -1, or >= 1
 +
|1
 +
| style="text-align:left;" |
 +
*Number of iterations that the media plays.
 +
* 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;"|
 +
* Helps categorize media.
 +
|-
 +
| 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.
 +
|-
 +
|}
  
−
==gotoRoom==
+
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]]
−
;gotoRoom (roomID)
 
−
:Speedwalks you to the given room from your current room if it is able and knows the way. You must turn the map on for this to work, else it will return "(mapper): Don't know how to get there from here :(".
 
  
−
In case this isn't working, and you are coding your own mapping script, [[Manual:Mapper#Making_your_own_mapping_script|see here]] how to implement additional functionality necessary.
+
{{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].
  
−
==hasExitLock==
+
{{MudletVersion|4.15}}
−
;status = hasExitLock(roomID, direction)
 
  
−
:Returns ''true'' or ''false'' depending on whenever a given exit leading out from a room is locked. Direction can be specified as a number, short direction name ("nw") or long direction name ("northwest").
+
;Example
  
−
; Example
 
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- check if the east exit of room 1201 is locked
+
---- Table Parameter Syntax ----
−
display(hasExitLock(1201, 4))
 
−
display(hasExitLock(1201, "e"))
 
−
display(hasExitLock(1201, "east"))
 
−
</syntaxhighlight>
 
  
−
: See also: [[#lockExit|lockExit()]]
+
-- 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"
 +
})
  
−
==hasSpecialExitLock==
+
-- OR copy once from the game's profile, and play a music file stored in the profile's media directory
−
;hasSpecialExitLock(from roomID, to roomID, moveCommand)
+
---- [volume] of 75 (1 to 100)
 +
playMusicFile({
 +
    name = getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3"
 +
    , volume = 75
 +
})
  
−
:Returns ''true'' or ''false'' depending on whenever a given exit leading out from a room is locked. ''moveCommand'' is the action to take to get through the gate.
+
-- 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)
−
See also: [[#lockSpecialExit|lockSpecialExit()]]
+
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/"
 +
})
 +
</syntaxhighlight>
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- lock a special exit from 17463 to 7814 that uses the 'enter feather' command
+
---- Ordered Parameter Syntax of playMusicFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,continue][,url][,finish]) ----
−
lockSpecialExit(17463, 7814, 'enter feather', true)
 
−
 
 
−
-- see if it is locked: it will say 'true', it is
 
−
display(hasSpecialExitLock(17463, 7814, 'enter feather'))
 
−
</syntaxhighlight>
 
−
 
 
−
==highlightRoom==
 
−
;highlightRoom( roomID, color1Red, color1Green, color1Blue, color2Red, color2Green, color2Blue, highlightRadius, color1Alpha, color2Alpha)
 
  
−
:Highlights a room with the given color, which will override its environment color. If you use two different colors, then there'll be a shading from the center going outwards that changes into the other color.  
+
-- 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
 +
)
  
−
;Parameters
+
-- OR copy once from the game's profile, and play a music file stored in the profile's media directory
−
* ''roomID''
+
---- [volume] of 75 (1 to 100)
−
: ID of the room to be colored.
+
playMusicFile(
−
* ''color1Red, color1Green, color1Blue''
+
    getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name
−
: RGB values of the first color.
+
    , 75 -- volume
−
* ''color2Red, color2Green, color2Blue''
+
)
−
: RGB values of the second color.
 
−
* ''highlightRadius''
 
−
: The radius for the highlight circle - if you don't want rooms beside each other to overlap, use ''1'' as the radius.  
 
−
* ''color1Alpha'' and ''color2Alpha''
 
−
: Transparency values from 0 (completely transparent) to 255 (not transparent at all).
 
  
−
: See also: [[#unHighlightRoom|unHighlightRoom()]]
+
-- 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
 +
)
  
−
<syntaxhighlight lang="lua">
+
-- OR download once from the Internet, and play music stored in the profile's media directory
−
-- color room #351 red to blue
+
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 20 seconds
−
local r,g,b = unpack(color_table.red)
+
---- [fadeout] and decrease the volume from default volume to one, 53 seconds from the end of the music
−
local br,bg,bb = unpack(color_table.blue)
+
---- [start] 10 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)
−
highlightRoom(351, r,g,b,br,bg,bb, 1, 255, 255)
+
---- [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
 +
)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==killMapInfo==
+
==playSoundFile==
−
;killMapInfo(label)
+
;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 [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]].
  
−
Delete a map info contributor entirely - it will be not available anymore.
+
{| class="wikitable"
 +
! Required
 +
! Key
 +
! Value
 +
! Default
 +
! style="text-align:left;"| Purpose
 +
|- style="color: green;"
 +
| style="text-align:center;"| Yes
 +
| name
 +
| <file name>
 +
| &nbsp;
 +
| 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")
 +
* Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.
 +
|-
 +
| style="text-align:center;"| No
 +
| volume
 +
| 1 to 100
 +
| 50
 +
| style="text-align:left;"|
 +
* Relative to the volume set on the player's client.
 +
|-
 +
| style="text-align:center;"| 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.
 +
|-
 +
| style="text-align:center;" |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.
 +
|-
 +
| style="text-align:center;"| No
 +
| start
 +
| <msec>
 +
| 0
 +
| style="text-align:left;"|
 +
*  Begin play at the specified position in milliseconds.
 +
|-
 +
| style="text-align:center;"| No
 +
| finish
 +
| <msec>
 +
|
 +
| style="text-align:left;"|
 +
*  Finish play at the specified position in milliseconds.
 +
|-
 +
| style="text-align:center;" |No
 +
| loops
 +
| -1, or >= 1
 +
|1
 +
| style="text-align:left;" |
 +
*Number of iterations that the media plays.
 +
* 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;"|
 +
* 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.
 +
|-
 +
|}
  
−
;Parameters
+
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]]
−
* ''label:''
 
−
: Name under which map info to be removed was registered.
 
  
−
: See also: [[#registerMapInfo|registerMapInfo()]], [[#enableMapInfo|enableMapInfo()]], [[#disableMapInfo|disableMapInfo()]]
+
{{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.11}}
+
{{MudletVersion|4.15}}
  
−
==loadJsonMap==
+
;Example
−
; loadJsonMap(pathFileName)
 
  
−
; Parameters:
+
<syntaxhighlight lang="lua">
 +
---- Table Parameter Syntax ----
  
−
* ''pathFileName'' a string that is an absolute path and file name to read the data from.
+
-- Play a sound file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)
 +
playSoundFile({
 +
    name = "cow.wav"
 +
})
  
−
Load the Mudlet map in text (JSON) format. It does take longer than loading usual map file (''.dat'' in binary) so it will show a progress dialog.
+
-- 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
 +
})
  
−
: See also: [[#saveJsonMap|saveJsonMap()]]
+
-- 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
 +
})
  
−
Returns:
+
-- OR download once from the Internet, and play a sound stored in the profile's media directory
−
* ''true'' on success
+
---- [volume] of 75
−
* ''nil'' and an error message on failure.
+
---- [loops] of 2 (-1 for indefinite repeats, 1+ for finite repeats)
−
 
+
---- [key] reference of "cow" for stopping this unique sound later
−
;Example
+
---- [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/"
 +
})
 +
</syntaxhighlight>
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
loadJsonMap(getMudletHomeDir() .. "/map.json")
+
---- Ordered Parameter Syntax of playSoundFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,priority][,url][,finish]) ----
−
 
 
−
true
 
−
</syntaxhighlight>
 
  
−
{{MudletVersion|4.11.0}}
+
-- Play a sound file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)
 +
playSoundFile(
 +
    "cow.wav" -- name
 +
)
  
−
==loadMap==
+
-- OR copy once from the game's profile, and play a sound file stored in the profile's media directory
−
;loadMap(file location)
+
---- [volume] of 75 (1 to 100)
 +
playSoundFile(
 +
    getMudletHomeDir().. "/cow.wav" -- name
 +
    , 75 -- volume
 +
)
  
−
:Loads the map file from a given location. The map file must be in Mudlet's format - saved with [[#saveMap|saveMap()]] or, as of the Mudlet 3.0 may be a MMP XML map conforming to the structure used by I.R.E. for their downloadable maps for their MUD games.  
+
-- 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
 +
)
  
−
:Returns a boolean for whenever the loading succeeded. Note that the mapper must be open, or this will fail.
+
-- OR download once from the Internet, and play a sound stored in the profile's media directory
−
 
+
---- [volume] of 75
−
:Using no arguments will load the last saved map.
+
---- [loops] of 2 (-1 for indefinite repeats, 1+ for finite repeats)
−
 
+
---- [key] reference of "cow" for stopping this unique sound later
−
<syntaxhighlight lang="lua">
+
---- [tag] reference of "animals" to stop a group of sounds later with the same tag
−
  loadMap("/home/user/Desktop/Mudlet Map.dat")
+
---- [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
 +
)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
{{Note}} A file name ending with <code>.xml</code> will indicate the XML format.
+
==purgeMediaCache==
−
 
+
;purgeMediaCache()
−
==lockExit==
+
: 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).
−
;lockExit(roomID, direction, lockIfTrue)
 
  
−
:Locks a given exit from a room. The destination may remain accessible through other paths, unlike [[#lockRoom|lockRoom]]. Direction can be specified as a number, short direction name ("nw") or long direction name ("northwest").
+
;Guidance:
  
−
: See also: [[#hasExitLock|hasExitLock()]]
+
* 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()''
  
−
;Example
+
: See also: [[Manual:Supported_Protocols#MSP|Supported Protocols MSP]], [[Manual:Scripting#MUD_Client_Media_Protocol|Scripting MCMP]]
−
<syntaxhighlight lang="lua">
 
−
-- lock the east exit of room 1201 so we never path through it
 
−
lockExit(1201, 4, true)
 
−
</syntaxhighlight>
 
  
−
==lockRoom==
+
==receiveMSP==
−
;lockRoom (roomID, lockIfTrue)
+
;receiveMSP(command)
 +
: 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.
  
−
:Locks a given room id from future speed walks (thus the mapper will never path through that room).
+
: See also: [[Manual:Supported_Protocols#MSP|Supported Protocols MSP]]
−
: See also: [[#roomLocked | roomLocked()]]
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
lockRoom(1, true) -- locks a room if from being walked through when speedwalking.
+
--Play a cow.wav media file stored in the media folder of the current profile. The sound would play twice at a normal volume.
−
lockRoom(1, false) -- unlocks the room, adding it back to possible rooms that can be walked through.
+
receiveMSP("!!SOUND(cow.wav L=2 V=50)")
−
</syntaxhighlight>
 
  
−
==lockSpecialExit==
+
--Stop any SOUND media files playing stored in the media folder of the current profile.
−
;lockSpecialExit (from roomID, to roomID, special exit command, lockIfTrue)
+
receiveMSP("!!SOUND(Off)")
  
−
:Locks a given special exit, leading from one specific room to another that uses a certain command from future speed walks (thus the mapper will never path through that special exit).
+
--Play a city.mp3 media file stored in the media folder of the current profile. The music would play once at a low volume.
−
: See also: [[#hasSpecialExitLock | hasSpecialExitLock()]], [[#lockExit | lockExit()]], [[#lockRoom | lockRoom()]]
+
--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)")
−
lockSpecialExit(1,2,'enter gate', true) -- locks the special exit that does 'enter gate' to get from room 1 to room 2
 
−
lockSpecialExit(1,2,'enter gate', false) -- unlocks the said exit
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==mapSymbolFontInfo==
+
==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.
  
−
;mapSymbolFontInfo()
+
: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.
−
: See also: [[#setupMapSymbolFont|setupMapSymbolFont()]]
 
  
−
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038
+
:The function returns an ID that can be used in [[Manual:Lua_Functions#killAnonymousEventHandler|killAnonymousEventHandler()]] to unregister the handler again.
  
−
;returns
+
:If you use an asterisk ''("*")'' as the event name, your code will capture all events. Useful for debugging, or integration with external programs.
−
* either a table of information about the configuration of the font used for symbols in the (2D) map, the elements are:
 
−
:* ''fontName'' - a string of the family name of the font specified
 
−
:* ''onlyUseThisFont'' - a boolean indicating whether glyphs from just the ''fontName'' font are to be used or if there is not a ''glyph'' for the required ''grapheme'' (''character'') then a ''glyph'' from the most suitable different font will be substituted instead. Should this be ''true'' and the specified font does not have the required glyph then the replacement character (typically something like ''�'') could be used instead. Note that this may not affect the use of Color Emoji glyphs that are automatically used in some OSes but that behavior does vary across the range of operating systems that Mudlet can be run on.
 
−
:* ''scalingFactor'' - a floating point number between 0.50 and 2.00 which modifies the size of the symbols somewhat though the extremes are likely to be unsatisfactory because some of the particular symbols may be too small (and be less visible at smaller zoom levels) or too large (and be clipped by the edges of the room rectangle or circle).
 
−
* or ''nil'' and an error message on failure.
 
  
−
::As the symbol font details are stored in the (binary) map file rather than the profile then this function will not work until a map is loaded (or initialized, by activating a map window).
+
{{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.
  
−
==moveMapWidget==
+
{{note}} The ''"*"'' all-events capture was added in Mudlet 4.10.
−
;moveMapWidget(Xpos, Ypos)
 
−
:moves the map window to the given position.
 
−
: See also: [[#openMapWidget|openMapWidget()]], [[#closeMapWidget|closeMapWidget()]], [[#resizeMapWidget|resizeMapWidget()]]
 
  
−
;Parameters
+
;See also
−
* ''Xpos:''
+
:[[Manual:Lua_Functions#killAnonymousEventHandler|killAnonymousEventHandler()]], [[Manual:Lua_Functions#raiseEvent|raiseEvent()]], [[Manual:Event_Engine#Mudlet-raised_events|list of Mudlet-raised events]]
−
: X position of the map window. Measured in pixels, with 0 being the very left. Passed as an integer number.
 
−
* ''Ypos:''
 
−
: Y position of the map window. Measured in pixels, with 0 being the very top. Passed as an integer number.
 
  
−
{{MudletVersion|4.7}}
+
;Example
 +
<syntaxhighlight lang="lua">
 +
-- example taken from the God Wars 2 (http://godwars2.org) Mudlet UI - forces the window to keep to a certain size
 +
function keepStaticSize()
 +
  setMainWindowSize(1280,720)
 +
end -- keepStaticSize
  
−
==openMapWidget==
+
if keepStaticSizeEventHandlerID then killAnonymousEventHandler(keepStaticSizeEventHandlerID) end -- clean up any already registered handlers for this function
−
;openMapWidget([dockingArea | Xpos, Ypos, width, height])
+
keepStatisSizeEventHandlerID = registerAnonymousEventHandler("sysWindowResizeEvent", "keepStaticSize") -- register the event handler and save the ID for later killing
−
means either of these are fine:
+
</syntaxhighlight>
−
;openMapWidget()
 
−
;openMapWidget(dockingArea)
 
−
;openMapWidget(Xpos, Ypos, width, height)
 
  
−
:opens a map window with given options.
+
<syntaxhighlight lang="lua">
 +
-- simple inventory tracker for GMCP enabled games. This version does not leak any of the methods
 +
-- or tables into the global namespace. If you want to access it, you should export the inventory
 +
-- table via an own namespace.
 +
local inventory = {}
  
−
: See also: [[#closeMapWidget|closeMapWidget()]], [[#moveMapWidget|moveMapWidget()]], [[#resizeMapWidget|resizeMapWidget()]]
+
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
  
−
{{MudletVersion|4.7}}
+
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
  
−
;Parameters
+
local function inventoryUpdate()
−
{{note}} If no parameter is given the map window will be opened with the saved layout or at the right docking position (similar to clicking the icon)
+
  if gmcp.Char.Items.Remove.location == "inv" then
−
* ''dockingArea:''
+
    local found
−
: If only one parameter is given this parameter will be a string that contains one of the possible docking areas the map window will be created in (f" floating "t" top "b" bottom "r" right and "l" left)
+
    local updatedItem = gmcp.Char.Items.Update.item
−
{{note}} If 4 parameters are given the map window will be created in floating state
+
    for index, item in ipairs(inventory) do
−
* ''Xpos:''
+
      if item.id == updatedItem.id then
−
: X position of the map window. Measured in pixels, with 0 being the very left. Passed as an integer number.
+
        found = index
−
* ''Ypos:''
+
        break
−
: Y position of the map window. Measured in pixels, with 0 being the very left. Passed as an integer number.
+
      end
−
* ''width:''
+
    end
−
: The width map window, in pixels. Passed as an integer number.
+
    if found then
−
* ''height:''
+
      inventory[found] = table.deepcopy(updatedItem)
−
: The height map window, in pixels. Passed as an integer number.
+
    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)
  
−
==pauseSpeedwalk==
+
local function inventoryRemove()
−
;pauseSpeedwalk()
+
  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)
 +
</syntaxhighlight>
  
−
:Pauses a speedwalk started using [[#speedwalk|speedwalk()]]
+
<syntaxhighlight lang="lua">
 +
-- downloads a package from the internet and kills itself after it is installed.
 +
local saveto = getMudletHomeDir().."/dark-theme-mudlet.zip"
 +
local url = "http://www.mudlet.org/wp-content/files/dark-theme-mudlet.zip"
  
−
: See also: [[#speedwalk|speedwalk()]], [[#stopSpeedwalk|stopSpeedwalk()]], [[#resumeSpeedwalk|resumeSpeedwalk()]]
+
if myPackageInstallHandler then killAnonymousEventHandler(myPackageInstallHandler) end
−
 
+
myPackageInstallHandler = registerAnonymousEventHandler(
−
{{MudletVersion|4.13}}
+
  "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
 +
)
  
−
<syntaxhighlight lang="lua">
+
downloadFile(saveto, url)
−
local ok, err = pauseSpeedwalk()
+
cecho("<white>Downloading <green>"..url.."<white> to <green>"..saveto.."\n")
−
if not ok then
 
−
  debugc(f"Error: unable to pause speedwalk because {err}\n")
 
−
  return
 
−
end
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==registerMapInfo==
+
==registerNamedEventHandler==
−
;registerMapInfo(label, function)
+
; success = registerNamedEventHandler(userName, handlerName, eventName, functionReference, [oneShot])
−
 
 
−
Adds an extra 'map info' to the mapper widget which can be used to display custom information.
 
  
−
: See also: [[#killMapInfo|killMapInfo()]], [[#enableMapInfo|enableMapInfo()]], [[#disableMapInfo|disableMapInfo()]]
+
: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
  
−
{{MudletVersion|4.11}}
+
;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()]]
  
−
{{note}}
+
{{MudletVersion|4.14}}
−
You can register multiple map infos - just give them unique names and toggle whichever ones you need.
 
  
 
;Parameters
 
;Parameters
−
* ''label:''
+
* ''userName:''
−
: Name under which map info will be registered and visible in select box under mapper. You can use it later to kill map info, enable it, disable it or overwrite using [[#registerMapInfo|registerMapInfo()]] again.
+
: The user name the event handler was registered under.
−
* ''function:''
+
* ''handlerName:''
−
: Callback function that will be responsible for returning information how to draw map info fragment.
+
: 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.
  
−
Callback function is called with following arguments:
+
;Returns
−
* ''roomId'' - current roomId or currently selected room (when multiple selection is made this is center room)
+
* true if successful, otherwise errors.
−
* ''selectionSize'' -  how many rooms are selected
 
−
* ''areaId'' - roomId's areaId
 
−
* ''displayedAreaId'' - areaId that is currently displayed
 
−
 
 
−
Callback needs to return following:
 
−
* ''text'' - text that will be displayed (when empty, nothing will be displayed, if you want to "reserve" line or lines use not empty value " " or add line breaks "\n")
 
−
* ''isBold'' (optional) -  true/false - determines whether text will be bold
 
−
* ''isItalic'' (optional) - true/false - determines whether text will be italic
 
−
* ''color r'' (optional) - color of text red component (0-255)
 
−
* ''color g'' (optional) - color of text green component (0-255)
 
−
* ''color b'' (optional) - color of text blue component (0-255)
 
−
 
 
−
{{note}}
 
−
Map info is registered in disabled state, you need to enable it through script or by selecting checkbox under mapper.
 
  
 +
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
registerMapInfo("My very own handler!", function(roomId, selectionSize, areaId, displayedArea)  
+
-- register a named event handler. Will call demonVitalsHandler(eventName, ...) when gmcp.Char.Vitals is raised.
−
  return string.format("RoomId: %d\nNumbers of room selected: %d\nAreaId: %d\nDisplaying area: %d", roomId, selectionSize, areaId, displayedArea),
+
local ok = registerNamedEventHandler("Demonnic", "DemonVitals", "gmcp.Char.Vitals", "demonVitalsHandler")
−
   true, true, 0, 255, 0
+
if ok then
−
end)
+
   cecho("Vitals handler switched to demonVitalsHandler")
−
enableMapInfo("My very own handler!")
+
end
−
</syntaxhighlight>
 
  
−
Example will display something like that:
+
-- 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.
−
[[File:Map-info-example.png]]
+
-- 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
  
−
Using function arguments is completely optional and you can determine whether and how to display map info completely externally.
+
-- Now you want to check your inventory, but you only want to do it once, so you pass the optional oneShot as true
−
<syntaxhighlight lang="lua">
+
local function handleInv()
−
registerMapInfo("Alert", function()  
+
  local list = gmcp.Char.Items.List
−
   if character.hp < 20 then
+
   if list.location ~= "inventory" then
−
     return "Look out! Your HP is getting low", true, false, unpack(color_table.red) -- will display red, bolded warning whne character.hp is below 20
+
     return true -- if list.location is, say "room" then we need to keep responding until it's "inventory"
−
  else
 
−
    return "" -- will not return anything
 
 
   end
 
   end
−
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
−
enableMapInfo("Alert")
+
end
−
</syntaxhighlight>
 
−
 
 
−
==resumeSpeedwalk==
 
−
;resumeSpeedwalk()
 
−
 
 
−
:Continues a speedwalk paused using [[#pauseSpeedwalk|pauseSpeedwalk()]]
 
−
: See also: [[#speedwalk|speedwalk()]], [[#pauseSpeedwalk|pauseSpeedwalk()]], [[#stopSpeedwalk|stopSpeedwalk()]]
 
−
 
 
−
{{MudletVersion|4.13}}
 
  
−
<syntaxhighlight lang="lua">
+
-- you can ignore the response from registerNamedEventHandler if you want, it's always going to be true
−
local ok, err = resumeSpeedwalk()
+
-- unless there is an error, in which case it throws the error and halts execution anyway. The return is
−
if not ok then
+
-- in part for feedback when using the lua alias or other REPL window.
−
  cecho(f"\n<red>Error:<reset> Problem resuming speedwalk: {err}\n")
+
registerNamedEventHandler("Demonnic", "DemonInvCheck", "gmcp.Char.Items.List", handleInv, true)
−
  return
 
−
end
 
−
cecho("\n<green>Successfully resumed speedwalk!\n")
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==removeCustomLine==
+
==reloadModule==
−
;removeCustomLine(roomID, direction)  
+
;reloadModule(module name)
 +
:Reload a module (by uninstalling and reinstalling).
  
−
:Removes the custom exit line that's associated with a specific exit of a room.
+
:See also: [[#installModule|installModule()]], [[#uninstallModule|uninstallModule()]]
−
:See also: [[#addCustomLine|addCustomLine()]], [[#getCustomLines|getCustomLines()]]
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- remove custom exit line that starts in room 315 going north
+
reloadModule("3k-mapper")
−
removeCustomLine(315, "n")
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==removeMapEvent==
 
−
;removeMapEvent(event name)
 
−
 
−
:Removes the given menu entry from a mappers right-click menu. You can add custom ones with [[#addMapEvent | addMapEvent()]].
 
−
: See also: [[#addMapEvent | addMapEvent()]], [[#getMapEvents | getMapEvents()]], [[#removeMapMenu | removeMapMenu()]]
 
  
−
;Example
+
==removeFileWatch==
−
<syntaxhighlight lang="lua">
+
;removeFileWatch(path)
−
addMapEvent("room a", "onFavorite") -- add one to the general menu
+
:Remove file watch on directory or file. Every change in that file will no longer raise [[Manual:Event_Engine#sysPathChanged|sysPathChanged]] event.
−
removeMapEvent("room a") -- removes the said menu
 
−
</syntaxhighlight>
 
  
−
==removeMapMenu==
+
:See also: [[#addFileWatch|addFileWatch()]]
−
;removeMapMenu(menu name)
 
  
−
:Removes the given submenu from a mappers right-click menu. You can add custom ones with [[#addMapMenu | addMapMenu()]].
+
{{MudletVersion|4.12}}
−
: See also: [[#addMapMenu | addMapMenu()]], [[#getMapMenus | getMapMenus()]], [[#removeMapEvent | removeMapEvent()]]
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
addMapMenu("Test") -- add submenu to the general menu
+
herbs = {}
−
removeMapMenu("Test") -- removes that same menu again
+
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")
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==removeSpecialExit==
+
==resetProfile==
−
;removeSpecialExit(roomID, command)  
+
;resetProfile()
  
−
:Removes the special exit which is accessed by ''command'' from the room with the given ''roomID''.
+
: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.
−
:See also: [[#addSpecialExit|addSpecialExit()]], [[#clearSpecialExits|clearSpecialExits()]]
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
addSpecialExit(1, 2, "pull rope") -- add a special exit from room 1 to room 2
+
resetProfile()
−
removeSpecialExit(1, "pull rope") -- removes the exit again
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==resetRoomArea==
+
The function used to require input from the game to work, but as of Mudlet 3.20 that is no longer the case.
−
;resetRoomArea (roomID)
 
  
−
: Unassigns the room from its given area. While not assigned, its area ID will be -1.  Note that since Mudlet 3.0 the "default area" which has the id of -1 may be selectable in the area selection widget on the mapper - although there is also an option to conceal this in the settings.
 
  
−
: See also: [[#setRoomArea | setRoomArea()]], [[#getRoomArea | getRoomArea()]]
+
{{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
−
 
 
−
;Example
 
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
resetRoomArea(3143)
+
lua resetProfile()
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
in your commandline or make an Alias containing resetProfile().
  
−
==resizeMapWidget==
+
==resumeNamedEventHandler==
−
;resizeMapWidget(width, height)
+
; success = resumeNamedEventHandler(userName, handlerName)
−
:resizes a map window with given width, height.
 
−
: See also: [[#openMapWidget|openMapWidget()]], [[#closeMapWidget|closeMapWidget()]], [[#moveMapWidget|moveMapWidget()]]
 
  
−
{{MudletVersion|4.7}}
+
:Resumes a named event handler with name handlerName and causes it to start firing once more.
  
−
;Parameters
+
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#stopNamedEventHandler|stopNamedEventHandler()]]
−
* ''width:''
 
−
: The width of the map window, in pixels. Passed as an integer number.
 
−
* ''height:''
 
−
: The height of the map window, in pixels. Passed as an integer number.
 
  
−
==roomExists==
+
{{MudletVersion|4.14}}
−
;roomExists(roomID)
 
  
−
:Returns a boolean true/false depending if the room with that ID exists (is created) or not.
+
;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 [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]]
  
−
==roomLocked==
+
;Returns
−
;locked = roomLocked(roomID)
+
* true if successful, false if it didn't exist.
−
 
 
−
:Returns true or false whenever a given room is locked.
 
−
: See also: [[#lockRoom|lockRoom()]]
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
echo(string.format("Is room #4545 locked? %s.", roomLocked(4545) and "Yep" or "Nope"))
+
local resumed = resumeNamedEventHandler("Demonnic", "DemonVitals")
 +
if resumed then
 +
  cecho("DemonVitals resumed!")
 +
else
 +
  cecho("DemonVitals doesn't exist, cannot resume it")
 +
end
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==saveJsonMap==
+
==saveProfile==
−
; saveJsonMap([pathFileName])
+
;saveProfile(location)
−
Saves all the data that is normally held in the Mudlet map (''.dat'' as a binary format) in text (JSON) format. It does take longer to do this, so a progress dialog will be shown indicating the status.
 
  
−
: See also: [[#loadJsonMap|loadJsonMap()]]
+
:Saves the current Mudlet profile to disk, which is equivalent to pressing the "Save Profile" button.
−
{{MudletVersion|4.11.0}}
 
  
−
; Parameters:
+
;Parameters
−
* ''pathFileName'' (optional in Mudlet 4.12+): a string that is an absolute path and file name to save the data into.
+
* ''location:''
−
 
+
:(optional) folder to save the profile to. If not given, the profile will go into the [[Mudlet_File_Locations|default location]].
−
; Returns:
 
−
* ''true'' on success
 
−
* ''nil'' and an error message on failure.
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
saveJsonMap(getMudletHomeDir() .. "/map.json")
+
saveProfile()
  
−
true
+
-- save to the desktop on Windows:
 +
saveProfile([[C:\Users\yourusername\Desktop]])
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==saveMap==
+
==sendSocket==
−
;saveMap([location], [version])
+
;sendSocket(data)
−
 
 
−
:Saves the map to a given location, and returns true on success. The location folder needs to be already created for save to work. You can also save the map in the Mapper settings tab.
 
  
−
;Parameters
+
: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.
−
* ''location''
 
−
: (optional) save the map to the given location if provided, or the default one otherwise.
 
−
* ''version''
 
−
: (optional) map version as a number to use when saving (Mudlet 3.17+)
 
−
 
 
−
: See also: [[#loadMap|loadMap()]]
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
local savedok = saveMap(getMudletHomeDir().."/my fancy map.dat")
+
TN_IAC = 255
−
if not savedok then
+
TN_WILL = 251
−
  echo("Couldn't save :(\n")
+
TN_DO = 253
−
else
+
TN_SB = 250
−
  echo("Saved fine!\n")
+
TN_SE = 240
−
end
+
TN_MSDP = 69
  
−
-- save with a particular map version
+
MSDP_VAL = 1
−
saveMap(20)
+
MSDP_VAR = 2
−
</syntaxhighlight>
 
  
−
==searchAreaUserData==
+
sendSocket( string.char( TN_IAC, TN_DO, TN_MSDP ) ) -- sends IAC DO MSDP
−
;searchAreaUserData(area number | area name[, case-sensitive [, exact-match]])
 
−
:Searches Areas' User Data in a manner exactly the same as [[#searchRoomUserData|searchRoomUserData()]] does in all Rooms' User Data, refer to that command for the specific details except to replace references to rooms and room ID numbers there with areas and areas ID numbers.
 
  
−
==searchRoom==
+
--sends: IAC  SB MSDP MSDP_VAR "LIST" MSDP_VAL "COMMANDS" IAC SE
−
;searchRoom (room number | room name[, case-sensitive [, exact-match]])
+
local msg = string.char( TN_IAC, TN_SB, TN_MSDP, MSDP_VAR ) .. " LIST " ..string.char( MSDP_VAL ) .. " COMMANDS " .. string.char( TN_IAC, TN_SE )
−
:Searches for rooms that match (by case-insensitive, substring match) the given room name. It returns a key-value table in form of ''roomid = roomname'', the optional second and third boolean parameters have been available since Mudlet 3.0;
+
sendSocket( msg )
 +
</syntaxhighlight>
  
−
::If no rooms are found, then an empty table is returned.
+
{{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.
  
−
:If you pass it a '''number''' instead of a '''string''' as just one argument, it'll act like [[#getRoomName|getRoomName()]] and return the room name.
+
==setConfig==
 +
; setConfig(option, value)
  
−
;Examples
+
: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.
−
<syntaxhighlight lang="lua">
+
:To set many options at once, pass in a table of options. More options will be added over time / per request.
−
-- show the behavior when given a room number:
 
−
display(searchRoom(3088))
 
−
"The North Road South of Taren Ferry"
 
  
−
-- show the behavior when given a string:
+
;See also: [[Manual:Lua_Functions#enableMapInfo|enableMapInfo()]], [[Manual:Lua_Functions#disableMapInfo|disableMapInfo()]]
−
-- shows all rooms containing the text in any case:
 
−
display(searchRoom("North road"))
 
−
{
 
−
  [3114] = "Bend in North road",
 
−
  [3115] = "North road",
 
−
  [3116] = "North Road",
 
−
  [3117] = "North road",
 
−
  [3146] = "Bend in the North Road",
 
−
  [3088] = "The North Road South of Taren Ferry",
 
−
  [6229] = "Grassy Field By North Road"
 
−
}
 
−
-- or:
 
−
--  display(searchRoom("North road",false))
 
−
--  display(searchRoom("North road",false,false))
 
−
-- would both also produce those results.
 
  
−
-- shows all rooms containing the text in ONLY the letter-case provided:
+
{{MudletVersion|4.16}}
−
display(searchRoom("North road",true,false))
 
−
{
 
−
  [3114] = "Bend in North road",
 
−
  [3115] = "North road",
 
−
  [3117] = "North road",
 
−
}
 
  
−
-- shows all rooms containing ONLY that text in either letter-case:
+
;Parameters
−
lua searchRoom("North road",false,true)
+
* ''option:''
−
{
+
: Particular option to change - see list below for available ones.
−
  [3115] = "North road",
+
* ''value:''
−
  [3116] = "North Road",
+
: Value to set - can be a boolean, number, or text depending on the option.
−
  [3117] = "North road"
 
−
}
 
  
−
-- shows all rooms containing only and exactly the given text:
+
{| class="wikitable sortable"
−
lua searchRoom("North road",true,true)
+
|+ General options
−
{
+
|-
−
  [3115] = "North road",
+
! Option !! Default !! Description !! Available in Mudlet
−
  [3117] = "North road"
+
|-
−
}
+
| enableGMCP || true || Enable GMCP (Reconnect after changing) || 4.16
−
</syntaxhighlight>
+
|-
−
{{note}} Technically, with both options (case-sensitive and exact-match) set to true, one could just return a list of numbers as we know precisely what the string will be, but it was kept the same for maximum flexibility in user scripts.
+
| 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
 +
|}
  
−
==searchRoomUserData==
+
{| class="wikitable sortable"
−
;searchRoomUserData([key, [value]])
+
|+ Input line
−
:A command with three variants that search though all the rooms in sequence (so '''not as fast as a user built/maintained ''index'' system''') and find/reports on the room user data stored:
+
|-
 +
! Option !! Default !! Description !! Available in Mudlet
 +
|-
 +
| inputLineStrictUnixEndings || false || Workaround option to use strict UNIX line endings for sending commands || 4.16
 +
|-
 +
|}
  
−
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserData|getRoomUserData()]], [[#getRoomUserDataKeys|getRoomUserDataKeys()]], [[#setRoomUserData|setRoomUserData()]]
+
{| class="wikitable sortable"
 +
|+ Main display
 +
|-
 +
! Option !! Default !! Description !! Available in Mudlet
 +
|-
 +
| fixUnnecessaryLinebreaks || false || Remove extra linebreaks from output (mostly for IRE servers) || 4.16
 +
|-
 +
|}
  
−
;searchRoomUserData(key, value)
+
{| class="wikitable sortable"
 +
|+ 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
 +
|}
  
−
:Reports a (sorted) list of all room ids with user data with the given "value" for the given (case sensitive) "key".  
+
{| 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
 +
|}
  
−
;searchRoomUserData(key)
+
;Returns
 +
* true if successful, or nil+msg if the option doesn't exist. Setting mapper options requires the mapper being open first.
  
−
:Reports a (sorted) list of the unique values from all rooms with user data with the given (case sensitive) "key".
+
;Example
−
 
 
−
;searchRoomUserData()
 
−
 
 
−
:Reports a (sorted) list of the unique keys from all rooms with user data with any (case sensitive) "key", available since Mudlet 3.0. It is possible (though not recommended) to have a room user data item with an empty string "" as a key, this is handled correctly.
 
−
 
 
−
{{MudletVersion|3.0}}
 
−
 
 
−
;Examples
 
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- if I had stored the details of "named doors" as part of the room user data --
+
setConfig("mapRoomSize", 5)
−
display(searchRoomUserData("doorname_up"))
 
  
−
--[[ could result in a list:
+
setConfig({mapRoomSize = 6, mapExitSize = 12})
−
{
+
</syntaxhighlight>
−
  "Eastgate",
 
−
  "Northgate",
 
−
  "boulderdoor",
 
−
  "chamberdoor",
 
−
  "dirt",
 
−
  "floorboards",
 
−
  "floortrap",
 
−
  "grate",
 
−
  "irongrate",
 
−
  "rockwall",
 
−
  "tomb",
 
−
  "trap",
 
−
  "trapdoor"
 
−
}]]
 
  
−
-- then taking one of these keys --
+
==setMergeTables==
−
display(searchRoomUserData("doorname_up","trapdoor"))
+
;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.
  
−
--[[ might result in a list:
+
;Parameters
−
{
+
* ''module:''
−
  3441,
+
:Name(s) of the GMCP or MSDP module(s) that should be merged as a string - this will add it to the existing list.
−
  6113,
 
−
  6115,
 
−
  8890
 
−
}
 
−
]]</syntaxhighlight>
 
−
 
 
−
==setAreaName==
 
−
;setAreaName(areaID or areaName, newName)
 
−
 
 
−
:Names, or renames an existing area to the new name. The area must be created first with [[#addAreaName|addAreaName()]] and it must be unique.
 
−
 
 
−
{{note}} parameter areaName is available since Mudlet 3.0.
 
−
 
 
−
:See also: [[#deleteArea|deleteArea()]], [[#addAreaName|addAreaName()]]
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
setAreaName(2, "My city")
+
setMergeTables("Char.Skills", "Char.Vitals")
−
 
 
−
-- available since Mudlet 3.0
 
−
setAreaName("My old city name", "My new city name")
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==setAreaUserData==
+
==setModuleInfo==
−
;setAreaUserData(areaID, key (as a string), value (as a string))
+
;setModuleInfo(moduleName, info, value)
  
−
:Stores information about an area under a given key. Similar to Lua's key-value tables, except only strings may be used here. One advantage of using userdata is that it's stored within the map file itself - so sharing the map with someone else will pass on the user data. Returns a lua ''true'' value on success. You can have as many keys as you'd like, however a blank key will not be accepted and will produce a lua ''nil'' and an error message instead.
+
:Sets a specific meta info value for a module
  
−
:Returns true if successfully set.
+
;Parameters
−
: See also: [[#clearAreaUserData|clearAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#getAllAreaUserData|getAllAreaUserData()]], [[#getAreaUserData|getAreaUserData()]], [[#searchAreaUserData|searchAreaUserData()]]
+
* ''moduleName:''
 +
:Name of the module
 +
* ''info:''
 +
: specific info to set (for example "version")
 +
* ''value:''
 +
: specific value to set (for example "1.0")
  
−
{{MudletVersion|3.0}}
+
:See also: [[#getModuleInfo|getModuleInfo]], [[#setPackageInfo|getPackageInfo]]
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- can use it to store extra area details...
+
setModuleInfo("myModule", "version", "1.0")
−
setAreaUserData(34, "country", "Andor.")
 
−
 
 
−
-- or a sound file to play in the background (with a script that checks a room's area when entered)...
 
−
setAreaUserData(34, "backgroundSound", "/home/user/mudlet-data/soundFiles/birdsong.mp4")
 
−
 
 
−
-- can even store tables in it, using the built-in yajl.to_string function
 
−
setAreaUserData(101, "some table", yajl.to_string({ruler = "Queen Morgase Trakand", clan = "Lion Warden"}))
 
−
display("The ruler's name is: "..yajl.to_value(getRoomUserData(101, "some table")).ruler)
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==setCustomEnvColor==
+
{{MudletVersion|4.12}}
−
;setCustomEnvColor(environmentID, r,g,b,a)
 
  
−
:Creates, or overrides an already created custom color definition for a given environment ID. Note that this will not work on the default environment colors - those are adjustable by the user in the preferences. You can however create your own environment and use a custom color definition for it.
+
==setModulePriority==
−
: See also: [[#getCustomEnvColorTable|getCustomEnvColorTable()]], [[#setRoomEnv|setRoomEnv()]]
+
;setModulePriority(moduleName, priority)
  
−
{{note}} Numbers 1-16 and 257-272 are reserved by Mudlet. 257-272 are the default colors the user can adjust in mapper settings, so feel free to use them if you'd like - but don't overwrite them with this function.
+
: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+).
  
−
[[File:Screenshot 20240305 115555.png|thumb|center|Default colour table for Mudlet mapper.]]
+
: See also: [[#getModulePriority|getModulePriority()]]
  
−
;Example
 
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
setRoomEnv(571, 200) -- change the room's environment ID to something arbitrary, like 200
+
setModulePriority("mudlet-mapper", 1)
−
local r,g,b = unpack(color_table.blue)
 
−
setCustomEnvColor(200, r,g,b, 255) -- set the color of environmentID 200 to blue
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==setDoor==
+
==setPackageInfo==
−
;setDoor(roomID, exitCommand, doorStatus)
+
;setPackageInfo(packageName, info, value)
−
 
 
−
:Creates or deletes a door in a room. Doors are purely visual - they don't affect default pathfinding (use a custom script to overcome this). You can use the information to adjust your speedwalking path based on the door information in a room, though.
 
−
 
 
−
:Doors CAN be set on stub exits ''- so that map makers can note if there is an obvious door to somewhere even if they do not (yet) know where it goes, perhaps because they do not yet have the key to open it!''
 
−
 
 
−
:Returns ''true'' if the change could be made, ''false'' if the input was valid but ineffective (door status was not changed), and ''nil'' with a message string on invalid input (value type errors).
 
  
−
: See also: [[#getDoors|getDoors()]]
+
:Sets a specific meta info value for a package
  
 
;Parameters
 
;Parameters
−
* ''roomID:''
+
* ''packageName:''
−
: Room ID to to create the door in.
+
:Name of the module
−
* ''exitCommand:''
+
* ''info:''
−
: The cardinal direction for the door is in - it can be one of the following: '''n''', '''e''', '''s''', '''w''', '''ne''', '''se''', '''sw''', '''ne'''. ''{Plans are afoot to add support for doors on the other normal exits: '''up''', '''down''', '''in''' and '''out''', and also on special exits - though more work will be needed for them to be shown in the mapper.}''  It is important to ONLY use these direction codes as others e.g. "UP" will be accepted - because a special exit could have ANY name/lua script - but it will not be associated with the particular normal exit - recent map auditing code about to go into the code base will REMOVE door and other room exit items for which the appropriate exit (or stub) itself is not present, so in this case, in the absence of a special exit called "UP" that example door will not persist and not show on the normal "up" exit when that is possible later on.
+
: specific info to set (for example "version")
−
 
+
* ''value:''
−
* ''doorStatus:''
+
: specific value to set (for example "1.0")
−
: The door status as a number - '''0''' means no (or remove) door, '''1''' means open door (will draw a green square on exit), '''2''' means closed door (yellow square) and '''3''' means locked door (red square).
 
  
 +
:See also: [[#getPackageInfo|getPackageInfo]], [[#setModuleInfo|setModuleInfo]]
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- make a door on the east exit of room 4234 that is currently open
+
setPackageInfo("myPackage", "title", "This is my test package")
−
setDoor(4234, 'e', 1)
 
−
 
 
−
-- remove a door from room 923 that points north
 
−
setDoor(923, 'n', 0)
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==setExit==
+
{{MudletVersion|4.12}}
−
;setExit(from roomID, to roomID, direction)
 
  
−
:Creates a one-way exit from one room to another using a standard direction - which can be either one of ''n, ne, nw, e, w, s, se, sw, u, d, in, out'', the long version of a direction, or a number which represents a direction. If there was an exit stub in that direction already, then it will be automatically deleted for you.
+
==setServerEncoding==
 +
;setServerEncoding(encoding)
 +
:Makes Mudlet use the specified [https://www.w3.org/International/questions/qa-what-is-encoding encoding] for communicating with the game.
  
−
:Returns ''false'' if the exit creation didn't work.
+
;Parameters
 +
* ''encoding:''
 +
:Encoding to use.
  
−
: See also: [[#addSpecialExit|addSpecialExit()]]
+
:See also: [[#getServerEncodingsList|getServerEncodingsList()]], [[#getServerEncoding|getServerEncoding()]]
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- alias pattern: ^exit (\d+) (\d+) (\w+)$
+
-- use UTF-8 if Mudlet knows it. Unfortunately there's no way to check if the game's server knows it too.
−
-- so exit 1 2 5 will make an exit from room 1 to room 2 via north
+
if table.contains(getServerEncodingsList(), "UTF-8") then
−
 
+
   setServerEncoding("UTF-8")
−
if setExit(tonumber(matches[2]), tonumber(matches[3]), matches[4]) then
 
−
  echo("\nExit set to room:"..matches[3].." from "..matches[2]..", direction:"..string.upper(matches[3]))
 
−
else
 
−
   echo("Failed to set the exit.\n")
 
 
end
 
end
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
This function can also delete exits from a room if you use it like so:
+
==showNotification==
 +
;showNotification(title, [content], [expiryTimeInSeconds])
 +
 
 +
:Shows a native (system) notification.
 +
 
 +
{{MudletVersion|4.11}}
  
−
<syntaxhighlight lang="lua">setExit(from roomID, -1, direction)</syntaxhighlight>
+
{{Note}} This might not work on all systems, this depends on the system.
  
−
- which will delete an outgoing exit in the specified direction from a room.
+
;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
  
−
==setExitStub==
+
<syntaxhighlight lang="lua">
−
;setExitStub(roomID, direction, set/unset)
+
showNotification("Notification title", "Notification content", 5)
 +
</syntaxhighlight>
  
−
Creates or removes an exit stub from a room in a given directions. You can use exit stubs later on to connect rooms that you're sure of are together. Exit stubs are also shown visually on the map, so the mapper can easily tell which rooms need finishing.
+
==spawn==
 +
;spawn(readFunction, processToSpawn[, ...arguments])
  
−
;Parameters
+
: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()''.
−
* ''roomID:''
 
−
: The room to place an exit stub in, as a number.
 
−
* ''direction:''
 
−
: The direction the exit stub should lead in - as a short direction name ("nw"), long direction name ("northwest") or a number.
 
−
* ''set/unset:''
 
−
: A boolean to create or delete the exit stub.
 
  
−
: See also: [[#getExitStubs|getExitStubs()]], [[#connectExitStub|connectExitStub()]]
+
:This allows you to setup RPC communication with another process.
  
−
;Example
+
;Examples
−
Create an exit stub to the south from room 8:
 
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
setExitStub(8, "s", true)
+
-- 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>
−
 
−
How to delete all exit stubs in a room:
 
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
for i,v in pairs(getExitStubs(roomID)) do
+
local f = spawn(display, "ls", "-la")
−
  setExitStub(roomID, v,false)
+
display(f.isRunning())
−
end
+
f.close()
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==setExitWeight==
+
==startLogging==
−
;setExitWeight(roomID, exitCommand, weight)
+
;startLogging(state)
  
−
:Gives an exit a weight, which makes it less likely to be chosen for pathfinding. All exits have a weight of 0 by default, which you can increase. Exit weights are set one-way on an exit - if you'd like the weight to be applied both ways, set it from the reverse room and direction as well.
+
: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
 
;Parameters
−
* ''roomID:''
+
* ''state:''
−
: Room ID to to set the weight in.
+
:Required: logging state. Passed as a boolean
−
* ''exitCommand:''
 
−
: The direction for the exit is in - it can be one of the following: '''n''', '''ne''', '''e''', '''se''', '''s''', '''sw''', '''w''', '''nw''', '''up''', '''down''', '''in''', '''out''', or, if it's a special exit, the special exit command - note that the strings for normal exits are case-sensitive and must currently be exactly as given here.
 
−
* ''weight:''
 
−
: Exit weight - by default, all exits have a weight of 0 meaning that the weight of the ''destination room'' is use when the route finding code is considering whether to use that exit; setting a value for an exit can increase or decrease the chance of that exit/destination room being used for a route by the route-finding code.  For example, if the destination room has very high weight compared to it's neighbors but the exit has a low value then that exit and thus the room is more likely to be used than if the exit was not weighted.
 
  
−
: See also: [[#getExitWeights|getExitWeights()]]
+
;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
  
−
==setGridMode==
+
;Example
−
;setGridMode(areaID, true/false)
+
<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
  
−
:Enables grid/wilderness view mode for an area - this will cause the rooms to lose their visible exit connections, like you'd see on compressed ASCII maps, both in 2D and 3D view mode; for the 2D map the custom exit lines will also not be shown if this mode is enabled.
+
-- stop logging
−
:Returns true if the area exists, otherwise false.
+
startLogging(false)
−
:[[File:Mapper-regular-mode.png|none|thumb|640x640px|regular mode]][[File:Mapper-grid-mode.png|none|thumb|631x631px|grid mode]]
+
</syntaxhighlight>
  
−
: See also: [[#getGridMode|getGridMode()]]
+
==stopAllNamedEventHandlers==
 +
; stopAllNamedEventHandlers(userName)
  
−
;Example
+
:Stops all named event handlers and prevents them from firing any more. Information is retained and handlers can be resumed.
−
<syntaxhighlight lang="lua">
 
−
setGridMode(55, true) -- set area with ID 55 to be in grid mode
 
−
</syntaxhighlight>
 
  
−
==setMapUserData==
+
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#stopNamedEventHandler|stopNamedEventHandler()]], [[Manual:Lua_Functions#resumeNamedEventHandler|resumeNamedEventHandler()]]
−
;setMapUserData(key (as a string), value (as a string))
 
  
−
:Stores information about the map under a given key. Similar to Lua's key-value tables, except only strings may be used here. One advantage of using userdata is that it's stored within the map file itself - so sharing the map with someone else will pass on the user data. You can have as many keys as you'd like.  
+
{{MudletVersion|4.14}}
  
−
:Returns true if successfully set.
+
;Parameter
−
: See also: [[#clearMapUserData|clearMapUserData()]], [[#clearMapUserDataItem|clearMapUserDataItem()]], [[#getAllMapUserData|getAllMapUserData()]], [[#getMapUserData|getMapUserData()]]
+
* ''userName:''
 +
: The user name the event handler was registered under.
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- store general meta information about the map...
+
stopAllNamedEventHandlers() -- emergency stop situation, most likely.
−
setMapUserData("game_name", "Achaea Mudlet map")
 
−
 
 
−
-- or who the author was
 
−
setMapUserData("author", "Bob")
 
−
 
 
−
-- can even store tables in it, using the built-in yajl.to_string function
 
−
setMapUserData("some table", yajl.to_string({game = "mud.com", port = 23}))
 
−
display("Available game info in the map: ")
 
−
display(yajl.to_value(getMapUserData("some table")))
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==setMapZoom==
+
==stopMusic==
−
;setMapZoom(zoom[, areaID])
+
;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()]].
  
−
:Zooms the 2D (only) map to a given zoom level. Larger numbers zooms the map further out. Revised in '''Mudlet ''4.17.0''''' to allow the zoom for an area to be specified even if it is not the one currently being viewed. This change is combined with Mudlet permanently remembering (it is saved within the map file) the zoom level last used for each area and with the addition of the ''getMapZoom()'' function.
+
{| 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:Mapper_Functions#getMapZoom|getMapZoom()]].
+
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]]
  
−
;Parameters
+
{{MudletVersion|4.15}}
−
* ''zoom:''
 
−
: floating point number that is at least 3.0 to set the zoom to.
 
  
−
* ''areaID:''
+
;Example
−
:(Optional and only since '''Mudlet ''4.17.0''''') Area ID number to adjust the 2D zoom for (''optional'', the function works on the area currently being viewed if this is omitted).
 
−
 
 
−
;Returns (only since '''Mudlet ''4.17.0''''')
 
−
* ''true'' on success
 
−
* ''nil'' and an error message on failure.
 
  
−
;Example
 
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
setMapZoom(10.0) -- zoom to a somewhat acceptable level, a bit big but easily visible connections
+
---- Table Parameter Syntax ----
−
true
 
  
−
setMapZoom(2.5 + getMapZoom(1), 1) -- zoom out the area with ID 1 by 2.5
+
-- Stop all playing music files for this profile associated with the API
−
true
+
stopMusic()
−
</syntaxhighlight>
 
  
−
{{note}} The precise meaning of a particular zoom value may have an underlying meaning however that has not been determined other than that the minimum value is 3.0 and the initial value - and what prior Mudlet versions started each session with - is 20.0.
+
-- Stop playing the rugby mp3 by name
 +
stopMusic({name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"})
  
−
==setRoomArea==
+
-- Stop playing the unique sound identified as "rugby"
−
;setRoomArea(roomID, newAreaID or newAreaName)
+
stopMusic({
 +
    name = nil  -- nil lines are optional, no need to use
 +
    , key = "rugby" -- key
 +
    , tag = nil  -- nil lines are optional, no need to use
 +
})
  
−
:Assigns the given room to a new or different area. If the area is displayed in the mapper this will have the room be visually moved into the area as well.
+
-- Decrease volume for 5 seconds and then stop all playing music files for this profile associated with the API
 +
stopMusic({
 +
    fadeaway = true
 +
})
  
−
: See also: [[#resetRoomArea|resetRoomArea()]]
+
-- 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
 +
})
  
−
==setRoomChar==
+
-- Decrease volume for 5 seconds and then stop all the unique "rugby" music for this profile associated with the API
−
;setRoomChar(roomID, character)
+
stopMusic({
 +
    key = "rugby"
 +
    , fadeaway = true
 +
})
 +
</syntaxhighlight>
 +
<syntaxhighlight lang="lua">
 +
---- Ordered Parameter Syntax of stopMusic([name][,key][,tag][,fadeaway][,fadeout]) ----
  
−
:Originally designed for an area in grid mode, takes a single ASCII character and draws it on the rectangular background of the room in the 2D map.
+
-- Stop all playing music files for this profile associated with the API
 +
stopMusic()
  
−
;Game-related symbols for your map
+
-- Stop playing the rugby mp3 by name
−
* [https://github.com/toddfast/game-icons-net-font toddfast's font] - 3000+ scalable vector RPG icons from [https://game-icons.net game-icons.net], as well as a script to download the latest icons and generate a new font.
+
stopMusic("167124__patricia-mcmillen__rugby-club-in-spain.mp3")
  
−
;Example
+
-- Stop playing the unique sound identified as "rugby"
−
<syntaxhighlight lang="lua">
+
stopMusic(
−
setRoomChar(431, "#")
+
    nil -- name
 +
    , "rugby" -- key
 +
    , nil -- tag
 +
)
  
−
setRoomChar(123, "$")
+
-- Decrease the volume for 10 seconds then stop playing the unique sound identified as "rugby"
−
 
+
stopMusic(
−
-- emoji's work fine too, and if you'd like it coloured, set the font to Nojo Emoji in settings
+
    nil -- name
−
setRoomChar(666, "👿")
+
    , "rugby" -- key
−
 
+
    , nil -- tag
−
-- clear a symbol with a space
+
    , true -- fadeaway
−
setRoomChar(123, " ")
+
    , 10000 -- fadeout
 +
)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
+
==stopNamedEventHandler==
−
<div style="font-weight:bold;line-height:1.6;">Historical version information</div>
+
; success = stopNamedEventHandler(userName, handlerName)
−
<div class="mw-collapsible-content">
 
−
:Since Mudlet version 3.8 this feature has been extended:
 
−
:* This function will now take a short string of any printable characters as a room ''symbol'', and they will be shrunk to fit them all in horizontally but if they become too small that ''symbol'' may not be shown if the zoom is such that the room symbol is too small to be legible.
 
−
:* As "_" is now a valid character an existing symbol may be erased with either a space " " or an empty string "" although neither may be effective in some previous versions of Mudlet.
 
−
:* Should the rooms be set to be drawn as circles this is now accommodated and the symbol will be resized to fit the reduce drawing area this will cause.
 
−
:* The range of characters that are available are now dependent on the '''fonts''' present in the system and a setting on the "Mapper" tab in the preferences that control whether a specific font is to be used for all symbols (which is best if a font is included as part of a game server package, but has the issue that it may not be displayable if the user does not have that font or chooses a different one) or any font in the user's system may be used (which is the default, but may not display the ''glyph'' {the particular representation of a ''grapheme'' in a particular font} that the original map creator expected).  Should it not be possible to display the wanted symbol in the map because one or more of the required glyphs are not available in either the specified or any font depending on the setting then the ''replacement character'' (Unicode ''code-point'' U+FFFD '�') will be shown instead.  To allow such missing symbols to be handled the "Mapper" tab on the preferences dialogue has an option to display:
 
−
::* an indicator to show whether the symbol can be made just from the selected font (green tick), from the fonts available in the system (yellow warning triangle) or not at all (red cross)
 
−
::* all the symbols used on the map and how they will be displayed both only using the selected font and all fonts
 
−
::* the sequence of code-points used to create the symbol which will be useful when used in conjunction with character selection utilities such as ''charmap.exe'' on Windows and ''gucharmap'' on unix-like system
 
−
::* a count of the rooms using the particular symbol
 
−
::* a list, limited in entries of the first rooms using that symbol
 
−
:* The font that is chosen to be used as the primary (or only) one for the room symbols is stored in the Mudlet map data so that setting will be included if a binary map is shared to other Mudlet users or profiles on the same system.
 
−
</div></div></div>
 
  
 +
: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: [[#getRoomChar|getRoomChar()]]
+
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#resumeNamedEventHandler|resumeNamedEventHandler()]]
  
−
==setRoomCharColor==
+
{{MudletVersion|4.14}}
−
;setRoomCharColor(roomId, r, g, b)
 
  
 
;Parameters
 
;Parameters
−
* ''roomID:''
+
* ''userName:''
−
: Room ID to to set char color to.
+
: The user name the event handler was registered under.
−
* ''r:''
+
* ''handlerName:''
−
: Red component of room char color (0-255)
+
: The name of the handler to stop. Same as used when you called [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]]
−
* ''g:''
 
−
: Green component of room char color (0-255)
 
−
* ''b:''
 
−
: Blue component of room char color (0-255)
 
  
−
Sets color for room symbol.
+
;Returns
 +
* true if successful, false if it didn't exist or was already stopped
  
 +
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
setRoomCharColor(2402, 255, 0, 0)
+
local stopped = stopNamedEventHandler("DemonVitals")
−
setRoomCharColor(2403, 0, 255, 0)
+
if stopped then
−
setRoomCharColor(2404, 0, 0, 255)
+
  cecho("DemonVitals stopped!")
 +
else
 +
  cecho("DemonVitals doesn't exist or already stopped; either way it won't fire any more.")
 +
end
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
{{MudletVersion|4.11}}
+
==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()]].
  
−
: See also: [[#unsetRoomCharColor|unsetRoomCharColor()]]
+
{| 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().
 +
|-
 +
|}
  
−
==setRoomCoordinates==
+
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]]
−
;setRoomCoordinates(roomID, x, y, z)
 
  
−
:Sets the given room ID to be at the following coordinates visually on the map, where ''z'' is the up/down level. These coordinates are define the location of the room within a particular area (so not globally on the overall map).
+
{{MudletVersion|4.15}}
  
−
{{note}} 0,0,0 is the center of the map.
+
;Example
  
−
;Examples
 
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- alias pattern: ^set rc (-?\d+) (-?\d+) (-?\d+)$
+
---- Table Parameter Syntax ----
−
-- this sets the current room to the supplied coordinates
 
−
setRoomCoordinates(roomID,x,y,z)
 
−
centerview(roomID)
 
−
</syntaxhighlight>
 
−
 
 
−
:You can make them relative asa well:
 
  
−
<syntaxhighlight lang="lua">
+
-- Stop all playing sound files for this profile associated with the API
−
-- alias pattern: ^src (\w+)$
+
stopSounds()
  
−
local x,y,z = getRoomCoordinates(previousRoomID)
+
-- Stop playing the cow sound
−
local dir = matches[2]
+
stopSounds({name = "cow.wav"})
  
−
if dir == "n" then
+
-- Stop playing any sounds tagged as "animals" with a priority less than or equal to 50
−
  y = y+1
+
---- This would not stop sounds tagged as "animals" greater than priority 50.  This is an "AND" and not an "OR".
−
elseif dir == "ne" then
+
stopSounds({
−
  y = y+1
+
    name = nil -- nil lines are optional, no need to use
−
  x = x+1
+
    , key = nil -- nil lines are optional, no need to use
−
elseif dir == "e" then
+
    , tag = "animals"
−
  x = x+1
+
    , priority = 50
−
elseif dir == "se" then
+
})
−
  y = y-1
 
−
  x = x+1
 
−
elseif dir == "s" then
 
−
  y = y-1
 
−
elseif dir == "sw" then
 
−
  y = y-1
 
−
  x = x-1
 
−
elseif dir == "w" then
 
−
  x = x-1
 
−
elseif dir == "nw" then
 
−
  y = y+1
 
−
  x = x-1
 
−
elseif dir == "u" or dir == "up" then
 
−
  z = z+1
 
−
elseif dir == "down" then
 
−
  z = z-1
 
−
end
 
−
setRoomCoordinates(roomID,x,y,z)
 
−
centerview(roomID)
 
−
</syntaxhighlight>
 
  
−
==setRoomEnv==
+
-- Decrease volume for 5 seconds and then stop all playing sound files for this profile associated with the API
−
;setRoomEnv(roomID, newEnvID)
+
stopSounds({
 +
    fadeaway = true
 +
})
  
−
:Sets the given room to a new environment ID. You don't have to use any functions to create it - can just set it right away.
+
-- 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
−
: See also: [[#setCustomEnvColor|setCustomEnvColor()]]
+
stopSounds({
 +
    fadeaway = true
 +
    , fadeout = 10000
 +
})
  
−
;Example
+
-- 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
 +
})
 +
</syntaxhighlight>
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
setRoomEnv(551, 34) -- set room with the ID of 551 to the environment ID 34
+
---- Ordered Parameter Syntax of stopSounds([name][,key][,tag][,priority][,fadeaway][,fadeout]) ----
−
</syntaxhighlight>
 
−
 
 
−
==setRoomIDbyHash==
 
−
;setRoomIDbyHash(roomID, hash)
 
−
 
 
−
:Sets the hash to be associated with the given roomID. See also [[#getRoomIDbyHash|getRoomIDbyHash()]].
 
  
−
:If the room was associated with a different hash, or vice versa, that association will be superseded.
+
-- Stop all playing sound files for this profile associated with the API
 +
stopSounds()
  
−
==setRoomName==
+
-- Stop playing the cow sound
−
;setRoomName(roomID, newName)
+
stopSounds("cow.wav")
  
−
:Renames an existing room to a new name.
+
-- 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
 +
)
  
−
;Example
+
-- Decrease the volume for 7 seconds and then stop playing sounds
−
<syntaxhighlight lang="lua">
+
stopSounds(
−
setRoomName(534, "That evil room I shouldn't visit again.")
+
    nil -- name
−
lockRoom(534, true) -- and lock it just to be safe
+
    , nil -- key
 +
    , nil -- tag
 +
    , nil -- priority
 +
    , true -- fadeaway
 +
    , 7000 -- fadeout
 +
)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==setRoomUserData==
+
==timeframe==
−
;setRoomUserData(roomID, key (as a string), value (as a string))
+
;timeframe(vname, true_time, nil_time, ...)
  
−
:Stores information about a room under a given key. Similar to Lua's key-value tables, except only strings may be used here. One advantage of using userdata is that it's stored within the map file itself - so sharing the map with someone else will pass on the user data. You can have as many keys as you'd like.  
+
:A utility function that helps you change and track variable states without using a lot of tempTimers.
  
−
:Returns true if successfully set.
+
{{MudletVersion|3.6}}
−
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserData|getRoomUserData()]], [[#searchRoomUserData|searchRoomUserData()]]
 
  
 +
;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: <code>{time, value}</code>
 +
* ''nil_time:''
 +
:(optional) Number of seconds until <code>vname</code> 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: <code>{time, value}</code>
 +
* ''...:''
 +
:(optional) Further list of times and values to set the variable to, in the following format: <code>{time, value}</code>
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- can use it to store room descriptions...
+
-- sets the global 'limiter' variable to true immediately (see the 0) and back to nil in one second (that's the 1).
−
setRoomUserData(341, "description", "This is a plain-looking room.")
+
timeframe("limiter", 0, 1)
−
 
 
−
-- or whenever it's outdoors or not...
 
−
setRoomUserData(341, "outdoors", "true")
 
  
−
-- how how many times we visited that room
+
-- 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.
−
local visited = getRoomUserData(341, "visitcount")
+
timeframe("giant", {0, "fee"}, 4, {1, "fi"}, {2, "fo"}, {3, "fum"})
−
visited = (tonumber(visited) or 0) + 1
 
−
setRoomUserData(341, "visitcount", tostring(visited))
 
  
−
-- can even store tables in it, using the built-in yajl.to_string function
+
-- sets the local 'width' variable to true immediately and back to nil in one second.
−
setRoomUserData(341, "some table", yajl.to_string({name = "bub", age = 23}))
+
local width
−
display("The denizens name is: "..yajl.to_value(getRoomUserData(341, "some table")).name)
+
timeframe(function(value) width = value end, 0, 1)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==setRoomWeight==
+
==translateTable==
−
;setRoomWeight(roomID, weight)
+
;translateTable(directions, [languagecode])
  
−
:Sets a weight to the given roomID. By default, all rooms have a weight of 1 - the higher the weight is, the more likely the room is to be avoided for pathfinding. For example, if travelling across water rooms takes more time than land ones - then you'd want to assign a weight to all water rooms, so they'd be avoided if there are possible land pathways.
+
:Given a table of directions (such as <code>speedWalkDir</code>), translates directions to another language for you. Right now, it can only translate it into the language of Mudlet's user interface - but [https://github.com/Mudlet/Mudlet/issues/new let us know if you need more].
  
−
{{note}} The minimum allowed room weight is 1.
+
{{MudletVersion|3.22}}
−
 
 
−
:To completely avoid a room, make use of [[#lockRoom|lockRoom()]].
 
−
 
 
−
: See also: [[#getRoomWeight|getRoomWeight()]]
 
  
 +
;Parameters
 +
* ''directions:''
 +
:An indexed table of directions (eg. <code>{"sw", "w", "nw", "s"}</code>).
 +
* ''languagecode:''
 +
:(optional) Language code (eg <code>ru_RU</code> or <code>it_IT</code>) - by default, <code>mudlet.translations.interfacelanguage</code> is used.
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
setRoomWeight(1532, 3) -- avoid using this room if possible, but don't completely ignore it
+
-- 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)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 +
==uninstallModule==
 +
;uninstallModule(name)
  
−
==speedwalk==
+
:Uninstalls a Mudlet module with the given name.
−
;speedwalk(dirString, backwards, delay, show)
 
  
−
:A speedwalking function will work on cardinal+ordinal directions (n, ne, e, etc.) as well as u (for up), d (for down), in and out. It can be called to execute all directions directly after each other, without delay, or with a custom delay, depending on how fast your game allows you to walk. It can also be called with a switch to make the function reverse the whole path and lead you backwards.
+
:See also: [[#installModule | installModule()]], [[Manual:Event_Engine#sysLuaUninstallModule | Event: sysLuaUninstallModule]]
  
−
:Call the function by doing: <code>speedwalk("YourDirectionsString", true/false, delaytime, true/false)</code>
+
;Example
−
 
+
<syntaxhighlight lang="lua">
−
:The delaytime parameter will set a delay between each move (set it to 0.5 if you want the script to move every half second, for instance). It is optional: If you don't indicate it, the script will send all direction commands right after each other. (If you want to indicate a delay, you -have- to explicitly indicate true or false for the reverse flag.)
+
uninstallModule("myalias")
 +
</syntaxhighlight>
  
−
:The show parameter will determine if the commands sent by this function are shown or hidden. It is optional: If you don't give a value, the script will show all commands sent. (If you want to use this option, you -have- to explicitly indicate true or false for the reverse flag, as well as either some number for the delay or nil if you do not want a delay.)
+
==uninstallPackage==
 +
;uninstallPackage(name)
  
−
:The "YourDirectionsString" contains your list of directions and steps (e.g.: "2n, 3w, u, 5ne"). Numbers indicate the number of steps you want it to walk in the direction specified after it. The directions must be separated by anything other than a letter that can appear in a direction itself. (I.e. you can separate with a comma, spaces, the letter x, etc. and any such combinations, but you cannot separate by the letter "e", or write two directions right next to each other with nothing in-between, such as "wn". If you write a number before every direction, you don't need any further separator. E.g. it's perfectly acceptable to write "3w1ne2e".) The function is not case-sensitive.
+
:Uninstalls a Mudlet package with the given name.
  
−
:If your game only has cardinal directions (n,e,s,w and possibly u,d) and you wish to be able to write directions right next to each other like "enu2s3wdu", you'll have to change the pattern slightly. Likewise, if your game has any other directions than n, ne, e, se, s, sw, w, nw, u, d, in, out, the function must be adapted to that.
+
:See also: [[#installPackage | installPackage()]]
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
speedwalk("16d1se1u")
+
uninstallPackage("myalias")
−
-- Will walk 16 times down, once southeast, once up. All in immediate succession.
 
−
 
 
−
speedwalk("2ne,3e,2n,e")
 
−
-- Will walk twice northeast, thrice east, twice north, once east. All in immediate succession.
 
−
 
 
−
speedwalk("IN N 3W 2U W", false, 0.5)
 
−
-- Will walk in, north, thrice west, twice up, west, with half a second delay between every move.
 
−
 
 
−
speedwalk("5sw - 3s - 2n - w", true)
 
−
-- Will walk backwards: east, twice south, thrice north, five times northeast. All in immediate succession.
 
−
 
 
−
speedwalk("3w, 2ne, w, u", true, 1.25)
 
−
-- Will walk backwards: down, east, twice southwest, thrice east, with 1.25 seconds delay between every move.
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
{{note}} The probably most logical usage of this would be to put it in an alias. For example, have the pattern ''^/(.+)$'' execute: <code>speedwalk(matches[2], false, 0.7)</code>
+
==unzipAsync==
−
And have ''^//(.+)$'' execute: <code>speedwalk(matches[2], true, 0.7)</code>
+
;unzipAsync(path, location)
−
Or make aliases like: ''^banktohome$'' to execute <syntaxhighlight lang="lua" inline>speedwalk("2ne,e,ne,e,3u,in", true, 0.5)</syntaxhighlight>
 
  
−
{{note}} The show parameter for this function is available in Mudlet 3.12+
+
: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 <code>sysUnzipDone</code> event with the zip file location and location unzipped to as arguments if unzipping is successful, and <code>sysUnzipError</code> with the same arguments if it is not.
  
−
==stopSpeedwalk==
+
Do not use the <code>unzip()</code> function as it is synchronous and will impact Mudlet's performance (ie, freeze Mudlet while unzipping).
−
;stopSpeedwalk()
 
  
−
:Stops a speedwalk started using [[#speedwalk|speedwalk()]]
+
{{MudletVersion|4.6}}
−
: See also: [[#pauseSpeedwalk|pauseSpeedwalk()]], [[#resumeSpeedwalk|resumeSpeedwalk()]], [[#speedwalk|speedwalk()]]
 
−
 
 
−
{{MudletVersion|4.13}}
 
  
 +
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
local ok, err = stopSpeedwalk()
+
function handleUnzipEvents(event, ...)
−
if not ok then
+
  local args = {...}
−
  cecho(f"\n<red>Error:<reset> {err}")
+
  local zipName = args[1]
−
   return
+
  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
 
end
−
cecho(f"\n<green>Success:<reset> speedwalk stopped")
+
if unzipSuccessHandler then killAnonymousEventHandler(unzipSuccessHandler) end
−
</syntaxhighlight>
+
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</syntaxhighlight>
  
−
==unHighlightRoom==
+
==yajl.to_string==
−
;unHighlightRoom(roomID)
+
;yajl.to_string(data)
  
−
:Unhighlights a room if it was previously highlighted and restores the rooms original environment color.
+
: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.
−
: See also: [[#highlightRoom|highlightRoom()]]
 
  
 
;Example
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
unHighlightRoom(4534)
+
-- on IRE MUD games, you can send a GMCP request to request the skills in a particular skillset. Here's an example:
−
</syntaxhighlight>
+
sendGMCP("Char.Skills.Get "..yajl.to_string{group = "combat"})
−
 
 
−
==unsetRoomCharColor==
 
−
;unsetRoomCharColor(roomId)
 
−
 
 
−
;Parameters
 
−
* ''roomID:''
 
−
: Room ID to to unset char color to.
 
−
 
 
−
Removes char color setting from room, back to automatic determination based on room background lightness.
 
  
−
<syntaxhighlight lang="lua">
+
-- you can also use it to convert a Lua table into a string, so you can, for example, store it as room's userdata
−
unsetRoomCharColor(2031)
+
local toserialize = yajl.to_string(continents)
 +
setRoomUserData(1, "areaContinents", toserialize)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
{{MudletVersion|4.11}}
 
−
 
−
==updateMap==
 
−
;updateMap()
 
  
−
:Updates the mapper display (redraws it). Use this function if you've edited the map via script and would like the changes to show.
+
==yajl.to_value==
 +
;yajl.to_value(data)
  
−
: See also: [[#centerview|centerview()]]
+
: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
 
;Example
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
-- delete a some room
+
-- given the serialization example above with yajl.to_string, you can deserialize room userdata back into a table
−
deleteRoom(500)
+
local tmp = getRoomUserData(1, "areaContinents")
−
-- now make the map show that it's gone
+
if tmp == "" then return end
−
updateMap()
+
 
 +
local continents = yajl.to_value(tmp)
 +
display(continents)
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
[[Category:Mudlet Manual]]
 
[[Category:Mudlet Manual]]
 
[[Category:Mudlet API]]
 
[[Category:Mudlet API]]

Revision as of 07:05, 21 July 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()

compare

sameValue = compare(a, b)
This function takes two items, and compares their values. It will compare numbers, strings, but most importantly it will compare two tables by value, not reference. For instance, {} == {} is false, but compare({}, {}) is true
See also
table.complement(), table.n_union()
Mudlet VersionAvailable in Mudlet4.18+
Parameters
  • a:
The first item to compare
  • b:
The second item to compare
Returns
  • Boolean true if the items have the same value, otherwise boolean false
Example
local tblA = { 255, 0, 0 }
local tblB = color_table.red
local same = compare(tblA, tblB)
display(same)
-- this will return true
display(tblA == tblB)
-- this will display false, as they are different tables
-- even though they have the same value
Additional development notes

This is just exposing the existing _comp function, which is currently the best way to compare two tables by value. --Demonnic (talk) 18:51, 7 February 2024 (UTC)

createVideoPlayer

createVideoPlayer([name of userwindow], x, y, width, height)
Creates a miniconsole window for the video player to render in, the with the given dimensions. One can only create one video player at a time (currently), and it is not currently possible to have a label on or under the video player - otherwise, clicks won't register.

Note Note: A video player may also be created through use of the Mud Client Media Protocol, the playVideoFile() API command, or adding a Geyser.VideoPlayer object to ones user interface such as the example below.

Note Note: The Main Toolbar will show a Video button to hide/show the video player, which is located in a userwindow generated through createVideoPlayer, embedded in a user interface, or a dock-able widget (that can be floated free to anywhere on the Desktop, it can be resized and does not have to even reside on the same monitor should there be multiple screens in your system). Further clicks on the Video button will toggle between showing and hiding the map whether it was created using the createVideo function or as a dock-able widget.

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

Mudlet VersionAvailable in Mudlet4.??+
Example
-- Create a 300x300 video player in the top-left corner of Mudlet
createVideoPlayer(0,0,300,300)

-- Alternative examples using Geyser.VideoPlayer
GUI.VideoPlayer = GUI.VideoPlayer or Geyser.VideoPlayer:new({name="GUI.VideoPlayer", x = 0, y = 0, width = "25%", height = "25%"})
 
GUI.VideoPlayer = GUI.VideoPlayer or Geyser.VideoPlayer:new({
  name = "GUI.VideoPlayer",
  x = "70%", y = 0, -- edit here if you want to move it
  width = "30%", height = "50%"
}, GUI.Right)

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 info wanted to get, 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")

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.supportscoroutines 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)
Retrieved from "https://wiki.mudlet.org/index.php?title=User:Molideus&oldid=21860"