Area 51

This page is for the development of documentation for Lua API functions that are currently being worked on. Ideally the entries here can be created in the same format as will be eventually used in Lua Functions and its sub-sites.

Please use the Area_51/Template to add new entries in the sections below.

Links to other functions or parts in other sections (i.e. the main Wiki area) need to include the section details before the '#' character in the link identifier on the left side of the '|' divider between the identifier and the display text. e.g.

[[Manual:Mapper_Functions#getCustomLines|getCustomLines()]]

rather than:

[[#getCustomLines|getCustomLines()]]

which would refer to a link within the current (in this case Area 51) section. Note that this ought to be removed once the article is moved to the main wiki area!

The following headings reflect those present in the main Wiki area of the Lua API functions. It is suggested that new entries are added so as to maintain a sorted alphabetical order under the appropriate heading.

Basic Essential Functions

These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.

Database Functions

A collection of functions for helping deal with the database.

Date/Time Functions

A collection of functions for handling date & time.

File System Functions

A collection of functions for interacting with the file system.

Mapper Functions

A collection of functions that manipulate the mapper and its related features.

createMapLabel, merged #7598

labelID = createMapLabel(areaID, text, posX, posY, posZ, fgRed, fgGreen, fgBlue, bgRed, bgGreen, bgBlue[, zoom, fontSize, showOnTop, noScaling, fontName, foregroundTransparency, backgroundTransparency, temporary, outlineRed, outlineGreen, outlineBlue])

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() will place the label near that room.

See also: getMapLabel(), getMapLabels(), deleteMapLabel, createMapImageLabel()

Expand

Historical Version Note

Note: Some changes were done prior to 4.13 (which exactly? function existed before!) - see corresponding PR and update here!

Parameters

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

• outlineRed, outlineGreen, outlineBlue

(optional) the outline colour of the displayed text

Example

-- the first 50 is some area id, the next three 0,0,0 are coordinates - middle of the area
-- 255,0,0 would be the foreground in RGB, 23,0,0 would be the background RGB
-- zoom is only relevant when when you're using a label of a static size, so we use 0
-- and we use a font size of 20 for our label, which is a small medium compared to the map
local labelid = createMapLabel( 50, "my map label", 0,0,0, 255,0,0, 23,0,0, 0,20)

-- to create a multi line text label add '\n' between lines
-- 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)

-- create a temporary, multiline label with purple text and a white outline lua createMapLabel(1, "This is a really long text\nwith multiple lines.", 0, 0, 0, 125, 0, 125, 0, 0, 0, 50, 48, true, false, "Noto Sans", 255, 0, true, 255, 255, 255)

mapSymbolFontInfo, PR #4038 closed

mapSymbolFontInfo()

See also: setupMapSymbolFont()

Note: pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038

returns

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

moveMapLabel, PR #6014 open

moveMapLabel(areaID/Name, labeID/Text, coordX/deltaX, coordY/deltaY[, coordZ/deltaZ][, absoluteNotRelativeMove])

Re-positions a map label within an area in the 2D mapper, in a similar manner as the moveRoom() function does for rooms and their custom exit lines. When moving a label to given coordinates this is the position that the top-left corner of the label will be positioned at; since the space allocated to a particular room on the map is ± 0.5 around the integer value of its x and y coordinates this means for a label which has a size of 1.0 x 1,0 (w x h) to position it centrally in the space for a single room at the coordinates (x, y, z) it should be positioned at (x - 0.5, y + 0.5, z).

See also: getMapLabels(), getMapLabel().

Available in Mudlet ?.??+

Note: pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6014

Parameters

• areaID/Name:

Area ID as number or AreaName as string containing the map label.

• labelID/Text:

Label ID as number (which will be 0 or greater) or the LabelText on a text label. All labels will have a unique ID number but there may be more than one text labels with a non-empty text string; only the first matching one will be moved by this function and image labels also have no text and will match the empty string. with mo or AreaName as string containing the map label.

• coordX/deltaX:

A floating point number for the absolute coordinate to use or the relative amount to move the label in "room coordinates" along the X-axis.

• coordY/deltaY:

A floating point number for the absolute coordinate to use or the relative amount to move the label in "room coordinates" along the Y-axis.

• coordZ/deltaZ:

(Optional) A floating point number for the absolute coordinate to use or the relative amount to move the label in "room coordinates" along the Z-axis, if omitted the label is not moved in the z-axis at all.

• absoluteNotRelativeMove:

(Optional) a boolean value (defaults to false if omitted) as to whether to move the label to the absolute coordinates (true) or to move it the relative amount from its current location (false).

Returns

true on success or nil and an error message on failure, if successful it will also refresh the map display to show the result.

Example

-- move the first label in the area with the ID number of 2, three spaces to the east and four spaces to the north
moveMapLabel(0, 2, 3.0, 4.0)

-- move the first label in the area with the ID number of 2, one space to the west, note the final boolean argument is unneeded
moveMapLabel(0, 2, -1.0, 0.0, false)

-- move the second label in the area with the ID number of 2, three and a half spaces to the west, and two south **of the center of the current level it is on in the map**:
moveRoom(1, 2, -3.5, -2.0, true)

-- move the second label in the area with the ID number of 2, up three levels
moveRoom(1, 2, 0.0, 0.0, 3.0)

-- move the second label in the "Test 1" area one space to the west, note the last two arguments are unneeded
moveRoom("Test 1", 1, -1.0, 0.0, 0.0, false)

-- move the (top-left corner of the first) label with the text "Home" in the area with ID number 5 to the **center of the whole map**, note the last two arguments are required in this case:
moveRoom(5, "Home", 0.0, 0.0, 0.0, true)

-- all of the above will return the 'true'  boolean value assuming there are the indicated labels and areas

moveRoom, PR #6010 open

moveRoom(roomID, coordX/deltaX, coordY/deltaY[, coordZ/deltaZ][, absoluteNotRelativeMove])

Re-positions a room within an area, in the same manner as the "move to" context menu item for one or more rooms in the 2D mapper. Like that method this will also shift the entirety of any custom exit lines defined for the room concerned. This contrasts with the behavior of the setRoomCoordinates() which only moves the starting point of such custom exit lines so that they still emerge from the room to which they belong but otherwise remain pointing to the original place.

See also: setRoomCoordinates()

Available in Mudlet ?.??+

Note: pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6010

Parameters

• roomID:

Room ID number to move.

• coordX/deltaX:

The absolute coordinate or the relative amount as a number to move the room in "room coordinates" along the X-axis.

• coordY/deltaY:

The absolute coordinate or the relative amount as a number to move the room in "room coordinates" along the Y-axis.

• coordZ/deltaZ:

(Optional) the absolute coordinate or the relative amount as a number to move the room in "room coordinates" along the Z-axis, if omitted the room is not moved in the z-axis at all.

• absoluteNotRelativeMove:

(Optional) a boolean value (defaults to false if omitted) as to whether to move the room to the absolute coordinates (true) or the relative amount from its current location (false).

Returns

true on success or nil and an error message on failure, if successful it will also refresh the map display to show the result.

Example

-- move the first room one space to the east and two spaces to the north
moveRoom(1, 1, 2)

-- move the first room one space to the west, note the final boolean argument is unneeded
moveRoom(1, -1, 0, false)

-- move the first room three spaces to the west, and two south **of the center of the current level it is on in the map**:
moveRoom(1, -3, -2, true)

-- move the second room up three levels
moveRoom(2, 0, 0, 3)

-- move the second room one space to the west, note the last two arguments are unneeded
moveRoom(2, -1, 0, 0, false)

-- move the second room to the **center of the whole map**, note the last two arguments are required in this case:
moveRoom(2, 0, 0, 0, true)

-- all of the above will return the 'true'  boolean value assuming there are rooms with 1 and 2 as ID numbers

setupMapSymbolFont, PR #4038 closed

setupMapSymbolFont(fontName[, onlyUseThisFont[, scalingFactor]])

configures the font used for symbols in the (2D) map.

See also: mapSymbolFontInfo()

Note: pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038

Parameters

• fontName one of:

• - a string that is the family name of the font to use;
• - the empty string "" to reset to the default {which is "Bitstream Vera Sans Mono"};
• - a Lua nil as a placeholder to not change this parameter but still allow a following one to be modified.

• onlyUseThisFont (optional) one of:

• - a Lua boolean true to require Mudlet to use graphemes (character) only from the selected font. Should a requested grapheme not be included in the selected font then the font replacement character (�) might be used instead; note that under some circumstances it is possible that the OS (or Mudlet) provided color Emoji Font may still be used but that cannot be guaranteed across all OS platforms that Mudlet might be run on;
• - a Lua boolean false to allow Mudlet to get a different glyph for a particular grapheme from the most suitable other font found in the system should there not be a glyph for it in the requested font. This is the default unless previously changed by this function or by the corresponding checkbox in the Profile Preferences dialogue for the profile concerned;
• - a Lua nil as a placeholder to not change this parameter but still allow the following one to be modified.

• scalingFactor (optional): a floating point value in the range 0.5 to 2.0 (default 1.0) that can be used to tweak the rectangular space that each different room symbol is scaled to fit inside; this might be useful should the range of characters used to make the room symbols be consistently under- or over-sized.

Returns

• true on success
• 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 initialised, by activating a map window).

Miscellaneous Functions

Miscellaneous functions.

createVideoPlayer, PR #6439 on-hold

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

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

loadVideoFile, PR #7721 closed

loadVideoFile(settings table) or loadVideoFile(name, [url])

Loads video files from the Internet or the local file system to the "media" folder of the profile for later use with playVideoFile() and stopVideos(). Although files could be loaded or streamed directly at playing time from playVideoFile(), loadVideoFile() provides the advantage of loading files in advance.

Note: Video files consume drive space on your device. Consider using the streaming feature of playVideoFile() for large files.

Required	Key	Value	Purpose
Yes	name	<file name>	Name of the media file. May contain directory information (i.e. weather/maelstrom.mp4). May be part of the profile (i.e. getMudletHomeDir().. "/congratulations.mp4") May be on the local device (i.e. "C:/Users/YourNameHere/Movies/nevergoingtogiveyouup.mp4")
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: getPausedMusic(), getPausedSounds(), getPausedVideos(), getPlayingMusic(), getPlayingSounds(), getPausedVideos(), loadMusicFile(), loadSoundFile(), pauseMusic(), pauseSounds(), pauseVideos(), playMusicFile(), playSoundFile(), playVideoFile(), purgeMediaCache(), receiveMSP(), stopMusic(), stopSounds(), stopVideos(), Mud Client Media Protocol

Available in Mudlet4.??+

Example

---- Table Parameter Syntax ----

-- Download from the Internet
loadVideoFile({
    name = "TextInMotion-VideoSample-1080p.mp4"
    , url = "https://d2qguwbxlx1sbt.cloudfront.net/"
})

-- OR download from the profile
loadVideoFile({name = getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4"})

-- OR download from the local file system
loadVideoFile({name = "C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4"})

playVideoFile, PR #7721 closed

playVideoFile(settings table)

Plays video files from the Internet or the local file system for later use with stopVideos(). Video files may be downloaded to the device and played, or streamed from the Internet when the value of the stream parameter is true.

Required	Key	Value	Default	Purpose
Yes	name	<file name>		Name of the media file. May contain directory information (i.e. weather/maelstrom.mp4). May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp4") May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp4") 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	start	<msec>	0	Begin play at the specified position in milliseconds.
No	finish	<msec>	0	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.
Yes	key	<key>		Identifies the label or window the video will appear on the user interface. 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 video files when true. Restarts matching new video files when false.
No	close	true or false	false	Closes the label or window when playback is complete.
Maybe	url	<url>		Resource location where the media file may be downloaded. Only required if the file is to be downloaded remotely or for streaming from the Internet.
Maybe	stream	true or false	false	Streams files from the Internet when true. Download files when false (default). Used in combination with the `url` key.

See also: getPausedMusic(), getPausedSounds(), getPausedVideos(), getPlayingMusic(), getPlayingSounds(), getPausedVideos(), loadMusicFile(), loadSoundFile(), loadVideoFile(), pauseMusic(), pauseSounds(), pauseVideos(), playMusicFile(), playSoundFile(), purgeMediaCache(), receiveMSP(), stopMusic(), stopSounds(), stopVideos(), Mud Client Media Protocol

Available in Mudlet4.??+

Example

---- Table Parameter Syntax ----

-- Stream a video file from the Internet and play it.
playVideoFile({
    name = "TextInMotion-VideoSample-1080p.mp4"
    , key = "textinmotion" -- label or window to target playback
    , url = "https://d2qguwbxlx1sbt.cloudfront.net/"
    , stream = true
})

-- Play a video file from the Internet, storing it in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media) so you don't need to download it over and over.  You could add ", stream = false" below, but that is the default and is not needed.

playVideoFile({
    name = "TextInMotion-VideoSample-1080p.mp4"
    , key = "textinmotion" -- label or window to target playback
    , url = "https://d2qguwbxlx1sbt.cloudfront.net/"
})

-- Play a video file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)
playVideoFile({
    name = "TextInMotion-VideoSample-1080p.mp4"
    , key = "textinmotion" -- label or window to target playback
})

-- OR copy once from the game's profile, and play a video file stored in the profile's media directory
---- [volume] of 75 (1 to 100)
playVideoFile({
    name = getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4"
    , key = "textinmotion" -- label or window to target playback
    , volume = 75
})

-- OR copy once from the local file system, and play a video file stored in the profile's media directory
---- [volume] of 75 (1 to 100)
playVideoFile({
    name = "C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4"
    , key = "textinmotion" -- label or window to target playback
    , volume = 75
})

-- OR download once from the Internet, and play a video 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 10 seconds
---- [fadeout] and decrease the volume from default volume to one, 15 seconds from the end of the video
---- [start] 5 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)
---- [key] reference of "textinmotion" for targeting label or window playback
---- [tag] reference of "ambience" to stop any video later with the same tag
---- [continue] playing this video if another request for the same video comes in (false restarts it) 
---- [url] resource location where the file may be accessed on the Internet
---- [stream] download once from the Internet if the video does not exist in the profile's media directory when false (true streams from the Internet and will not download to the device) 
playVideoFile({
    name = "TextInMotion-VideoSample-1080p.mp4"
    , volume = nil -- nil lines are optional, no need to use
    , start = 10000
    , finish = 20000
    , loops = nil -- nil lines are optional, no need to use
    , key = "textinmotion" -- label or window where this will play
    , tag = "ambience"
    , continue = true
    , close = true -- close the label or window when playback completes
    , url = "https://d2qguwbxlx1sbt.cloudfront.net/"
    , stream = false
})

stopVideos, PR #7721 closed

stopVideos(settings table)

Stop all videos (no filter), or videos that meet a combination of filters (name, key, and tag) intended to be paired with playVideoFile().

Required	Key	Value	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.

See also: getPausedMusic(), getPausedSounds(), getPausedVideos(), getPlayingMusic(), getPlayingSounds(), getPausedVideos(), loadMusicFile(), loadSoundFile(), loadVideoFile(), pauseMusic(), pauseSounds(), pauseVideos(), playMusicFile(), playSoundFile(), playVideoFile(), purgeMediaCache(), receiveMSP(), stopMusic(), stopSounds(), Mud Client Media Protocol

Available in Mudlet4.??+

Example

---- Table Parameter Syntax ----

-- Stop all playing video files for this profile associated with the API
stopVideos()

-- Stop playing the text mp4 by name
stopVideos({name = "TextInMotion-VideoSample-1080p.mp4"})

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

getPausedMusic, PR #7721 closed

getPausedMusic(settings table)

List all paused music (no filter), or paused 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: getPausedSounds(), getPausedVideos(), getPlayingMusic(), getPlayingSounds(), getPausedVideos(), loadMusicFile(), loadSoundFile(), loadVideoFile(), pauseMusic(), pauseSounds(), pauseVideos(), playMusicFile(), playSoundFile(), playVideoFile(), purgeMediaCache(), receiveMSP(), stopMusic(), stopSounds(), stopVideos(), Mud Client Media Protocol

Available in Mudlet4.??+

Example

---- Table Parameter Syntax ----

-- List all paused music files for this profile associated with the API
getPausedMusic()

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

-- List all paused music matching the unique key of "rugby"
getPausedMusic({
    name = nil  -- nil lines are optional, no need to use
    , key = "rugby" -- key
    , tag = nil  -- nil lines are optional, no need to use
})

getPausedSounds, PR #7721 closed

getPausedSounds(settings table)

List all paused sounds (no filter), or paused 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.

See also: getPausedMusic(), getPausedVideos(), getPlayingMusic(), getPlayingSounds(), getPausedVideos(), loadMusicFile(), loadSoundFile(), loadVideoFile(), pauseMusic(), pauseSounds(), pauseVideos(), playMusicFile(), playSoundFile(), playVideoFile(), purgeMediaCache(), receiveMSP(), stopMusic(), stopSounds(), stopVideos(), Mud Client Media Protocol

Available in Mudlet4.??+

Example

---- Table Parameter Syntax ----

-- List all paused sounds for this profile associated with the API
getPausedSounds()

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

-- List the paused sound matching the unique key of "rugby"
getPausedSounds({
    name = nil  -- nil lines are optional, no need to use
    , key = "rugby" -- key
    , tag = nil  -- nil lines are optional, no need to use
})

getPausedVideos, PR #7721 closed

getPausedVideos(settings table)

List all paused videos (no filter), or playing videos that meets a combination of filters (name, key, and tag) intended to be paired with playVideoFile().

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: getPausedMusic(), getPausedSounds(), getPlayingMusic(), getPlayingSounds(), getPlayingVideos(), loadMusicFile(), loadSoundFile(), loadVideoFile(), pauseMusic(), pauseSounds(), pauseVideos(), playMusicFile(), playSoundFile(), playVideoFile(), purgeMediaCache(), receiveMSP(), stopMusic(), stopSounds(), stopVideos(), Mud Client Media Protocol

Available in Mudlet4.??+

Example

---- Table Parameter Syntax ----

-- List all paused videos files for this profile associated with the API
getPausedVideos()

-- List all paused videos matching the unique textinmotion key name
getPausedVideos({name = "textinmotion"})

-- List all paused videos matching the textinmotion mp4 name
getPausedVideos({name = "TextInMotion-VideoSample-1080p.mp4"})

-- List all paused videos matching the unique key of "textinmotion"
getPausedVideos({
    name = nil  -- nil lines are optional, no need to use
    , key = "textinmotion" -- key
    , tag = nil  -- nil lines are optional, no need to use
})

getPlayingVideos, PR #7721 closed

getPlayingVideos(settings table)

List all playing videos (no filter), or playing videos that meets a combination of filters (name, key, and tag) intended to be paired with playVideoFile().

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: getPausedMusic(), getPausedSounds(), getPausedVideos(), getPlayingMusic(), getPlayingSounds(), loadMusicFile(), loadSoundFile(), loadVideoFile(), pauseMusic(), pauseSounds(), pauseVideos(), playMusicFile(), playSoundFile(), playVideoFile(), purgeMediaCache(), receiveMSP(), stopMusic(), stopSounds(), stopVideos(), Mud Client Media Protocol

Available in Mudlet4.??+

Example

---- Table Parameter Syntax ----

-- List all playing videos files for this profile associated with the API
getPlayingVideos()

-- List all playing videos matching the unique textinmotion key name
getPlayingVideos({name = "textinmotion"})

-- List all playing videos matching the textinmotion mp4 name
getPlayingVideos({name = "TextInMotion-VideoSample-1080p.mp4"})

-- List all playing videos matching the unique key of "textinmotion"
getPlayingVideos({
    name = nil  -- nil lines are optional, no need to use
    , key = "textinmotion" -- key
    , tag = nil  -- nil lines are optional, no need to use
})

pauseMusic, PR #7721 closed

pauseMusic(settings table)

Pause all music (no filter), or music that meet a combination of filters (name, key, and tag) intended to be paired with playMusicFile().

Required	Key	Value	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". Pauses 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.

See also: getPausedMusic(), getPausedSounds(), getPausedVideos(), getPlayingMusic(), getPlayingSounds(), getPausedVideos(), loadMusicFile(), loadSoundFile(), loadVideoFile(), pauseSounds(), pauseVideos(), playMusicFile(), playSoundFile(), playVideoFile(), purgeMediaCache(), receiveMSP(), stopMusic(), stopSounds(), stopVideos(), Mud Client Media Protocol

Available in Mudlet4.??+

Example

---- Table Parameter Syntax ----

-- Pause all playing music files for this profile associated with the API
pauseMusic()

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

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

pauseSounds, PR #7721 closed

pauseSounds(settings table)

Pause all sounds (no filter), or sounds that meet a combination of filters (name, key, and tag) intended to be paired with playSoundFile().

Required	Key	Value	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". Pauses 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.

See also: getPausedMusic(), getPausedSounds(), getPausedVideos(), getPlayingMusic(), getPlayingSounds(), getPausedVideos(), loadMusicFile(), loadSoundFile(), loadVideoFile(), pauseMusic(), pauseVideos(), playMusicFile(), playSoundFile(), playVideoFile(), purgeMediaCache(), receiveMSP(), stopMusic(), stopSounds(), stopVideos(), Mud Client Media Protocol

Available in Mudlet4.??+

Example

---- Table Parameter Syntax ----

-- Pause all playing sound files for this profile associated with the API
pauseSounds()

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

-- Pause all 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
})

pauseVideos, PR #7721 closed

pauseVideos(settings table)

Pause all videos (no filter), or videos that meet a combination of filters (name, key, and tag) intended to be paired with playVideoFile().

Required	Key	Value	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". Pauses 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.

See also: getPausedMusic(), getPausedSounds(), getPausedVideos(), getPlayingMusic(), getPlayingSounds(), getPausedVideos(), loadMusicFile(), loadSoundFile(), loadVideoFile(), pauseMusic(), pauseSounds(), playMusicFile(), playSoundFile(), playVideoFile(), purgeMediaCache(), receiveMSP(), stopMusic(), stopSounds(), stopVideos(), Mud Client Media Protocol

Available in Mudlet4.??+

Example

---- Table Parameter Syntax ----

-- Pause all playing video files for this profile associated with the API
pauseVideos()

-- Pause playing the text mp4 by name
pauseVideos({name = "TextInMotion-VideoSample-1080p.mp4"})

-- Pause playing the unique video identified as "text"
pauseVideos({
    name = nil  -- nil lines are optional, no need to use
    , key = "text" -- key
    , tag = nil  -- nil lines are optional, no need to use
})

getCustomLoginTextId, PR #3952 open

getCustomLoginTextId()

Returns the Id number of the custom login text setting from the profile's preferences. Returns 0 if the option is disabled or a number greater than that for the item in the table; note it is possible if using an old saved profile in the future that the number might be higher than expected. As a design policy decision it is not permitted for a script to change the setting, this function is intended to allow a script or package to check that the setting is what it expects.

Introduced along with four other functions to enable game server log-in to be scripted with the simultaneous movement of that functionality from the Mudlet application core code to a predefined doLogin() function, a replacement for which is shown below.

See also: getCharacterName(), sendCharacterName(), sendCustomLoginText(), sendPassword().

Note: Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952

Only one custom login text has been defined initially:

Predefined custom login texts

Id	Custom text	Introduced in Mudlet version
1	"connect {character name} {password}"	TBD

The addition of further texts would be subject to negotiation with the Mudlet Makers.

Example

-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:
function doLogin()
  if getCustomLoginTextId() ~= 1 then
    -- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is
    echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")
  else
    tempTime(2.0, [[sendCustomLoginText()]], 1)
  end
end

sendCharacterName, PR #3952 open

sendCharacterName()

Sends the name entered into the "Character name" field on the Connection Preferences form directly to the game server. Returns true unless there is nothing set in that entry in which case a nil and an error message will be returned instead.

Introduced along with four other functions to enable game server log-in to be scripted with the simultaneous movement of that functionality from the Mudlet application core code to a predefined doLogin() function that may be replaced for more sophisticated requirements.

See also: getCharacterName(), sendCharacterPassword(), sendCustomLoginText(), getCustomLoginTextId().

Note: Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952

sendCharacterPassword, PR #3952 open

sendCharacterPassword()

Sends the password entered into the "Password" field on the Connection Preferences form directly to the game server. Returns true unless there is nothing set in that entry or it is too long after (or before) a connection was successfully made in which case a nil and an error message will be returned instead.

Introduced along with four other functions to enable game server log-in to be scripted with the simultaneous movement of that functionality from the Mudlet application core code to a predefined doLogin() function, reproduced below, that may be replaced for more sophisticated requirements.

See also: getCharacterName(), sendCustomLoginText(), getCustomLoginTextId(), sendCharacterName().

Note: Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952

Example

-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:
function doLogin()
  if getCharacterName() ~= "" then
    tempTime(2.0, [[sendCharacterName()]], 1)
    tempTime(3.0, [[sendCharacterPassword()]], 1)
  end
end

sendCustomLoginText, PR #3952 open

sendCustomLoginText()

Sends the custom login text (which does NOT depend on the user's choice of GUI language) selected in the preferences for this profile. The {password} (and {character name} if present) fields will be replaced with the values entered into the "Password" and "Character name" fields on the Connection Preferences form and then sent directly to the game server. Returns true unless there is nothing set in either of those entries (though only if required for the character name) or it is too long after (or before) a connection was successfully made or if the custom login feature is disabled, in which case a nil and an error message will be returned instead.

Introduced along with four other functions to enable game server log-in to be scripted with the simultaneous movement of that functionality from the Mudlet application core code to a predefined doLogin() function, a replacement for which is shown below.

See also: getCharacterName(), sendCharacterName(), sendPassword(), getCustomLoginTextId().

Note: Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952

Only one custom login text has been defined initially:

Predefined custom login texts

Id	Custom text	Introduced in Mudlet version
1	"connect {character name} {password}"	TBD

The addition of further texts would be subject to negotiation with the Mudlet Makers.

Example

-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:
function doLogin()
  if getCustomLoginTextId() ~= 1 then
    -- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is
    echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")
  else
    tempTime(2.0, [[sendCustomLoginText()]], 1)
  end
end

setConfig PR #7654

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

Available 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
showUpperLowerLevels	true	Show rooms of +1/-1 level of current level	4.20
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})

Mudlet Object Functions

A collection of functions that manipulate Mudlet's scripting objects - triggers, aliases, and so forth.

deleteAllNamedTriggers PR#7767

deleteAllNamedTriggers(userName)

Deletes all named triggers and prevents them from matching. Information is deleted and cannot be retrieved.

See also

registerNamedTrigger(), stopNamedTrigger()

Available in Mudlet4.20+

Parameters

• userName:

The user name the trigger was registered under.

Example

deleteAllNamedTriggers("Zooka") -- emergency stop or debugging situation, most likely.

deleteNamedTrigger PR#7767

success = deleteNamedTrigger(userName, triggerName)

Deletes a named trigger with name triggerName and prevents it from matching any more. Information is deleted and cannot be retrieved.

See also

registerNamedTrigger(), stopNamedTrigger()

Available in Mudlet4.20+

Parameters

• userName:

The user name the trigger was registered under.

• triggerName:

The name of the trigger to stop. Same used as when you called registerNamedTrigger()

Returns

• true if successful, false if it didn't exist

Example

local deleted = deleteNamedTrigger("Zooka", "automatic drinking trigger")
if deleted then
  cecho("Drinking trigger deleted forever!")
else
  cecho("Drinking trigger doesn't exist and so could not be deleted.")
end

getNamedTriggers PR#7767

triggers = getNamedTriggers(userName)

Returns a list of all the named triggers names as a table.

See also

registerNamedTrigger()

Available in Mudlet4.20+

Parameters

• userName:

The user name the triggers were registered under.

Returns

• a table of trigger names. { "automatic drinking trigger", "autoheal trigger" } for example. {} if none are registered

Example

  local triggers = getNamedTriggers("Zooka")
  display(triggers)
  -- {}
  registerNamedTriggers("Zooka", "Test1", "test string", "testFunction")
  triggers = getNamedTriggers("Zooka")
  display(triggers)
  -- { "Test1" }

registerNamedTrigger PR#7767

success = registerNamedTrigger(userName, triggerName, substring, functionReference, [expireAfter])

Registers a named substring trigger with name triggerName. Named triggers are protected from duplication and can be stopped and resumed, unlike normal tempTriggers. A separate list is kept for each userName, to enforce name spacing and avoid collisions

See also

tempTrigger(), stopNamedTrigger(), resumeNamedTrigger(), deleteNamedTrigger()

Available in Mudlet4.20+

Parameters

• userName:

The user name the trigger was registered under.

• triggerName:

The name of the trigger. Used to reference the trigger in other functions and prevent duplicates. Recommended to use descriptive names, "hp" is likely to collide with something else, "automatic drinking trigger" less so.

• substring:

The substring text to match.

• functionReference:

The function reference to run when the trigger matches. Can be the name of a function, "handlerFunction", or the lua function itself.

• expireAfter:

(optional) Delete trigger after a specified number of matches

Returns

• true if successful, otherwise errors.

Example

-- establish a named trigger called "automatic drinking trigger" which sends 'drink canteen' when thirsty
registerNamedTrigger("Zooka", "automatic drinking trigger", "You are thirsty.", function() send("drink canteen") end)

resumeNamedTrigger PR#7767

success = resumeNamedTrigger(userName, triggerName)

Resumes a named trigger with name triggerName and allows it to match again.

See also

registerNamedTrigger(), stopNamedTrigger()

Available in Mudlet4.20+

Parameter

• userName:

The user name the trigger was registered under.s

• triggerName:

The name of the trigger to resume. Same as used when you called registerNamedTrigger()

Returns

• true if successful, false if it didn't exist.

Example

local resumed = resumeNamedTrigger("Zooka", "automatic drinking trigger")
if resumed then
  echo("Starting to automatically drink again.")
else
  echo("Drink trigger doesn't exist so cannot resume it.")
end

stopAllNamedTrigger PR#7767

stopAllNamedTrigger(userName)

Stops all named triggers for userName and prevents them from firing any more. Information is retained and triggers can be resumed.

See also

registerNamedTrigger(), stopNamedTrigger(), resumeNamedTrigger()

Available in Mudlet4.20+

Example

stopAllNamedTriggers("Zooka") -- emergency stop situation, most likely.

stopNamedTrigger PR#7767

success = stopNamedTrigger(userName, triggerName)

Stops a named trigger with name triggerName and prevents it from firing any more. Information is stored so it can be resumed later if desired.

See also

registerNamedTrigger(), resumeNamedTrigger()

Available in Mudlet4.20+

Parameters

• userName:

The user name the event handler was registered under.

• triggerName:

The name of the trigger to stop. Same as used when you called registerNamedTrigger()

Returns

• true if successful, false if it didn't exist or was already stopped

Example

local stopped = stopNamedTrigger("Zooka", "automatic drinking trigger")
if stopped then
  echo("No longer drinking automatically.")
else
  echo("Drinking trigger doesn't exist or already stopped; either way it won't fire any more.")
end

Networking Functions

A collection of functions for managing networking.

String Functions

These functions are used to manipulate strings.

Table Functions

These functions are used to manipulate tables. Through them you can add to tables, remove values, check if a value is present in the table, check the size of a table, and more.

Text to Speech Functions

These functions are used to create sound from written words. Check out our Text-To-Speech Manual for more detail on how this all works together.

UI Functions

These functions are used to construct custom user GUIs. They deal mainly with miniconsole/label/gauge creation and manipulation as well as displaying or formatting information on the screen.

insertPopup, revised in PR #6925

insertPopup([windowName], text, {commands}, {hints}[{, tool-tips}][, useCurrentFormatElseDefault])

Creates text with a left-clickable link, and a right-click menu for more options at the end of the current line, like echo. The added text, upon being left-clicked, will do the first command in the list. Upon being right-clicked, it'll display a menu with all possible commands. The menu will be populated with hints, one for each line; if a tool-tips table is not provided the same hints will also be listed one-per-line as a tool-tip but if a matching number of tool-tips are provided they will be concatenated to provide a tool-tip when the text is hovered over by the pointer - these tool-tips can be rich-text to produce information formatted with additional content in the same manner as labels.

Parameters

• windowName:

(optional) name of the window as a string to echo to. Use either main or omit for the main window, or the miniconsole's or user-window's name otherwise.

• text:

the text string to display.

• {commands}:

a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. {[[send("hello")]], function() echo("hi!") end}.

• {hints}:

a table of strings which will be shown on the right-click menu (and popup if no {tool-tips} table is provided). If a particular position in both the commands and hints table are both the empty string "" but there is something in the tool-tips table, no entry for that position will be made in the context menu but the tool-tip can still display something which can include images or text.

• {tool-tips}:

(optional) a table of possibly rich-text strings which will be shown on the popup if provided.

• useCurrentFormatElseDefault:

(optional) a boolean value for using either the current formatting options (color, underline, italic and other effects) if true or the link default (blue underline) if false, if omitted the default format is used.

Note: Mudlet will distinguish between the optional tool-tips and the flag to switch between the standard link and the current text format by examining the type of the argument, as such this pair of arguments can be in either order.

Example

-- Create some text as a clickable with a popup menu, a left click will ''send "sleep"'':
insertPopup("activities to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"})

-- alternatively, put commands as text (in [[ and ]] to use quotation marks inside)
insertPopup("activities to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"})

-- one can also provide helpful information

-- todo: an example with rich-text in the tool-tips(s)

Discord Functions

All functions to customize the information Mudlet displays in Discord's rich presence interface. For an overview on how all of these functions tie in together, see our Discord scripting overview.

Mud Client Media Protocol

All GMCP functions to send sound and music events. For an overview on how all of these functions tie in together, see our MUD Client Media Protocol scripting overview.

Events

New or revised events that Mudlet can raise to inform a profile about changes. See Mudlet-raised events for the existing ones.

sysLoadEvent, PR #7726

Raised after Mudlet is done loading the profile, after all of the scripts, packages, and modules are installed. Note that when it does so, it also compiles and runs all scripts - which could be a good idea to initialize everything at once, but beware - scripts are also run when saved. Hence, hooking only on the sysLoadEvent would prevent multiple re-loads as you’re editing the script.

In 4.20.0 an extra boolean argument was provided which indicates whether the event is from loading a new profile (true) or after a call of the resetProfile() function (false).

Note: pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/7726

sysMapWindowMousePressEvent, PR #6962

Raised when the mouse is left-clicked on the mapper window.

Available in Mudlet ?.??+

Note: pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6962

sysSettingChanged, PR #7476

This event is raised when a Preferences or Mudlet setting has changed. The first argument contains the setting that was changed, further arguments detail the change.

Currently implemented sysSettingChanged events are;

• "main window font" - raised when the main window/console font has changed via API or Preferences window. Returns two additional arguments, the font family and the font size. e.g. {"main window font", "Times New Roman", 12 }

Available in Mudlet ?.??+

Note: pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/7476