https://wiki.mudlet.org/api.php?action=feedcontributions&user=Demonnic&feedformat=atomMudlet - User contributions [en]2024-03-29T10:50:52ZUser contributionsMediaWiki 1.35.0https://wiki.mudlet.org/index.php?title=Area_51&diff=20910Area 512024-02-07T18:51:42Z<p>Demonnic: /* Miscellaneous Functions */</p>
<hr />
<div>{{TOC right}}<br />
<br />
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 [[Manual:Lua_Functions|Lua Functions]] and its sub-sites. <br />
<br />
Please use the [[Area_51/Template]] to add new entries in the sections below.<br />
<br />
Links to other functions or parts in other sections (i.e. the main Wiki area) need to include the section details before the <nowiki>'#'</nowiki> character in the link identifier on the left side of the <nowiki>'|'</nowiki> divider between the identifier and the display text. e.g.<br />
:: <nowiki>[[Manual:Mapper_Functions#getCustomLines|getCustomLines()]]</nowiki><br />
rather than:<br />
:: <nowiki>[[#getCustomLines|getCustomLines()]]</nowiki><br />
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!<br />
<br />
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.<br />
<br />
<br />
=Basic Essential Functions=<br />
:These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.<br />
<br />
=Database Functions=<br />
:A collection of functions for helping deal with the database.<br />
<br />
=Date/Time Functions=<br />
: A collection of functions for handling date & time.<br />
<br />
=File System Functions=<br />
: A collection of functions for interacting with the file system.<br />
<br />
=Mapper Functions=<br />
: A collection of functions that manipulate the mapper and its related features.<br />
<br />
==mapSymbolFontInfo, PR #4038 closed==<br />
;mapSymbolFontInfo()<br />
: See also: [[#setupMapSymbolFont|setupMapSymbolFont()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;returns<br />
* either a table of information about the configuration of the font used for symbols in the (2D) map, the elements are:<br />
:* ''fontName'' - a string of the family name of the font specified<br />
:* ''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.<br />
:* ''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).<br />
* or ''nil'' and an error message on failure.<br />
<br />
::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).<br />
<br />
==moveMapLabel, PR #6014 open==<br />
;moveMapLabel(areaID/Name, labeID/Text, coordX/deltaX, coordY/deltaY[, coordZ/deltaZ][, absoluteNotRelativeMove])<br />
Re-positions a map label within an area in the 2D mapper, in a similar manner as the [[#moveRoom|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).<br />
<br />
:See also: [[Manual:Mapper_Functions#getMapLabels|getMapLabels()]], [[Manual:Mapper_Functions#getMapLabel|getMapLabel()]].<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6014<br />
<br />
;Parameters<br />
* ''areaID/Name:''<br />
: Area ID as number or AreaName as string containing the map label.<br />
<br />
* ''labelID/Text:''<br />
: 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.<br />
<br />
* ''coordX/deltaX:''<br />
: 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.<br />
<br />
* ''coordY/deltaY:''<br />
: 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.<br />
<br />
* ''coordZ/deltaZ:''<br />
: (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.<br />
<br />
* ''absoluteNotRelativeMove:''<br />
: (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'').<br />
<br />
;Returns<br />
: ''true'' on success or ''nil'' and an error message on failure, if successful it will also refresh the map display to show the result.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- move the first label in the area with the ID number of 2, three spaces to the east and four spaces to the north<br />
moveMapLabel(0, 2, 3.0, 4.0)<br />
<br />
-- 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<br />
moveMapLabel(0, 2, -1.0, 0.0, false)<br />
<br />
-- 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**:<br />
moveRoom(1, 2, -3.5, -2.0, true)<br />
<br />
-- move the second label in the area with the ID number of 2, up three levels<br />
moveRoom(1, 2, 0.0, 0.0, 3.0)<br />
<br />
-- move the second label in the "Test 1" area one space to the west, note the last two arguments are unneeded<br />
moveRoom("Test 1", 1, -1.0, 0.0, 0.0, false)<br />
<br />
-- 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:<br />
moveRoom(5, "Home", 0.0, 0.0, 0.0, true)<br />
<br />
-- all of the above will return the 'true' boolean value assuming there are the indicated labels and areas<br />
</syntaxhighlight><br />
<br />
==moveRoom, PR #6010 open==<br />
;moveRoom(roomID, coordX/deltaX, coordY/deltaY[, coordZ/deltaZ][, absoluteNotRelativeMove])<br />
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 [[Manual:Mapper_Functions#setRoomCoordinates|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.<br />
<br />
:See also: [[Manual:Mapper_Functions#setRoomCoordinates|setRoomCoordinates()]]<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6010<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID number to move.<br />
<br />
* ''coordX/deltaX:''<br />
: The absolute coordinate or the relative amount as a number to move the room in "room coordinates" along the X-axis.<br />
<br />
* ''coordY/deltaY:''<br />
: The absolute coordinate or the relative amount as a number to move the room in "room coordinates" along the Y-axis.<br />
<br />
* ''coordZ/deltaZ:''<br />
: (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.<br />
<br />
* ''absoluteNotRelativeMove:''<br />
: (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'').<br />
<br />
;Returns<br />
: ''true'' on success or ''nil'' and an error message on failure, if successful it will also refresh the map display to show the result.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- move the first room one space to the east and two spaces to the north<br />
moveRoom(1, 1, 2)<br />
<br />
-- move the first room one space to the west, note the final boolean argument is unneeded<br />
moveRoom(1, -1, 0, false)<br />
<br />
-- 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**:<br />
moveRoom(1, -3, -2, true)<br />
<br />
-- move the second room up three levels<br />
moveRoom(2, 0, 0, 3)<br />
<br />
-- move the second room one space to the west, note the last two arguments are unneeded<br />
moveRoom(2, -1, 0, 0, false)<br />
<br />
-- move the second room to the **center of the whole map**, note the last two arguments are required in this case:<br />
moveRoom(2, 0, 0, 0, true)<br />
<br />
-- all of the above will return the 'true' boolean value assuming there are rooms with 1 and 2 as ID numbers<br />
</syntaxhighlight><br />
<br />
==setupMapSymbolFont, PR #4038 closed==<br />
;setupMapSymbolFont(fontName[, onlyUseThisFont[, scalingFactor]])<br />
:configures the font used for symbols in the (2D) map.<br />
: See also: [[#mapSymbolFontInfo|mapSymbolFontInfo()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;Parameters<br />
* ''fontName'' one of:<br />
:* - a string that is the family name of the font to use;<br />
:* - the empty string ''""'' to reset to the default {which is '''"Bitstream Vera Sans Mono"'''};<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow a following one to be modified.<br />
* ''onlyUseThisFont'' (optional) one of:<br />
:* - 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;<br />
:* - 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;<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow the following one to be modified.<br />
* ''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.<br />
<br />
;Returns<br />
* ''true'' on success<br />
* ''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).<br />
<br />
=Miscellaneous Functions=<br />
: Miscellaneous functions.<br />
<br />
==compare, PR#7122 open==<br />
<br />
; sameValue = compare(a, b)<br />
<br />
: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`<br />
<br />
;See also: [[Manual:Lua_Functions#table.complement|table.complement()]], [[Manual:Lua_Functions#table.n_union|table.n_union()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''a:''<br />
: The first item to compare<br />
* ''b:''<br />
: The second item to compare<br />
<br />
;Returns <br />
* Boolean true if the items have the same value, otherwise boolean false<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local tblA = { 255, 0, 0 }<br />
local tblB = color_table.red<br />
local same = compare(tblA, tblB)<br />
display(same)<br />
-- this will return true<br />
display(tblA == tblB)<br />
-- this will display false, as they are different tables<br />
-- even though they have the same value<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
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)<br />
<br />
==playMusicFile, PR #7026==<br />
;playMusicFile(settings table)<br />
: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()]].<br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! Default<br />
! style="text-align:left;"| Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;"| Yes<br />
| name<br />
| <file name><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
* May contain directory information (i.e. weather/lightning.wav).<br />
* May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")<br />
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")<br />
* Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.<br />
|-<br />
| style="text-align:center;"| No<br />
| volume<br />
| 1 to 100<br />
| 50<br />
| style="text-align:left;"|<br />
* Relative to the volume set on the player's client.<br />
|-<br />
| style="text-align:center;"| No<br />
| fadein<br />
|<msec><br />
|<br />
|<br />
*Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.<br />
*Start position: Start of media.<br />
*End position: Start of media plus the number of milliseconds (msec) specified.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
| fadeout<br />
|<msec><br />
|<br />
|<br />
*Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.<br />
*Start position: End of the media minus the number of milliseconds (msec) specified.<br />
*End position: End of the media.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;"| No<br />
| start<br />
| <msec><br />
| 0<br />
| style="text-align:left;"|<br />
* Begin play at the specified position in milliseconds.<br />
|-<br />
| style="text-align:center;"| No<br />
| finish<br />
| <msec><br />
| <br />
| style="text-align:left;"|<br />
* End play at the specified position in milliseconds.<br />
|-<br />
| style="text-align:center;" |No<br />
| loops<br />
| -1, or >= 1<br />
|1<br />
| style="text-align:left;" |<br />
*Number of iterations that the media plays.<br />
* A value of -1 allows the media to loop indefinitely.<br />
|-<br />
| style="text-align:center;" |No<br />
| key <br />
|<key><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;"| No<br />
| tag<br />
| <tag><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Helps categorize media.<br />
|-<br />
| style="text-align:center;" |No<br />
| continue <br />
| true or false<br />
| true<br />
| style="text-align:left;" |<br />
*Continues playing matching new music files when true.<br />
*Restarts matching new music files when false.<br />
|- style="color: blue;"<br />
| style="text-align:center;"| Maybe<br />
| url<br />
| <url><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Resource location where the media file may be downloaded.<br />
* Only required if the file is to be downloaded remotely.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{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].<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Play a music file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playMusicFile({<br />
name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
})<br />
<br />
-- OR copy once from the game's profile, and play a music file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playMusicFile({<br />
name = getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
, volume = 75<br />
})<br />
<br />
-- OR copy once from the local file system, and play a music file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playMusicFile({<br />
name = "C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
, volume = 75<br />
})<br />
<br />
-- OR download once from the Internet, and play music stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 20 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 53 seconds from the end of the music<br />
---- [start] 10 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [finish] 110 seconds from the track start (fadeout scales its volume decrease over a shorter duration, too)<br />
---- [key] reference of "rugby" for stopping this unique music later<br />
---- [tag] reference of "ambience" to stop and music later with the same tag<br />
---- [continue] playing this music if another request for the same music comes in (false restarts it) <br />
---- [url] to download once from the Internet if the music does not exist in the profile's media directory<br />
playMusicFile({<br />
name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
, volume = nil -- nil lines are optional, no need to use<br />
, fadein = 20000<br />
, fadeout = 53000<br />
, start = 10000<br />
, finish = 110000<br />
, loops = nil -- nil lines are optional, no need to use<br />
, key = "rugby"<br />
, tag = "ambience"<br />
, continue = true<br />
, url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of playMusicFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,continue][,url][,finish]) ----<br />
<br />
-- Play a music file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playMusicFile(<br />
"167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name<br />
)<br />
<br />
-- OR copy once from the game's profile, and play a music file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playMusicFile(<br />
getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR copy once from the local file system, and play a music file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playMusicFile(<br />
"C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR download once from the Internet, and play music stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 20 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 53 seconds from the end of the music<br />
---- [start] 10 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [finish] 110 seconds from the track start (fadeout scales its volume decrease over a shorter duration, too)<br />
---- [key] reference of "rugby" for stopping this unique music later<br />
---- [tag] reference of "ambience" to stop and music later with the same tag<br />
---- [continue] playing this music if another request for the same music comes in (false restarts it) <br />
---- [url] to download once from the Internet if the music does not exist in the profile's media directory<br />
playMusicFile(<br />
"167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name<br />
, nil -- volume<br />
, 20000 -- fadein<br />
, 53000 -- fadeout<br />
, 10000 -- start<br />
, nil -- loops<br />
, "rugby" -- key <br />
, "ambience" -- tag<br />
, true -- continue<br />
, "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/" -- url<br />
, 110000 -- finish<br />
)<br />
</syntaxhighlight><br />
<br />
==playSoundFile, PR #7026==<br />
;playSoundFile(settings table)<br />
: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()]].<br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! Default<br />
! style="text-align:left;"| Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;"| Yes<br />
| name<br />
| <file name><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
* May contain directory information (i.e. weather/lightning.wav).<br />
* May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")<br />
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")<br />
* Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.<br />
|-<br />
| style="text-align:center;"| No<br />
| volume<br />
| 1 to 100<br />
| 50<br />
| style="text-align:left;"|<br />
* Relative to the volume set on the player's client.<br />
|-<br />
| style="text-align:center;"| No<br />
| fadein<br />
|<msec><br />
|<br />
|<br />
*Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.<br />
*Start position: Start of media.<br />
*End position: Start of media plus the number of milliseconds (msec) specified.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
| fadeout<br />
|<msec><br />
|<br />
|<br />
*Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.<br />
*Start position: End of the media minus the number of milliseconds (msec) specified.<br />
*End position: End of the media.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;"| No<br />
| start<br />
| <msec><br />
| 0<br />
| style="text-align:left;"|<br />
* Begin play at the specified position in milliseconds.<br />
|-<br />
| style="text-align:center;"| No<br />
| finish<br />
| <msec><br />
| <br />
| style="text-align:left;"|<br />
* Finish play at the specified position in milliseconds.<br />
|-<br />
| style="text-align:center;" |No<br />
| loops<br />
| -1, or >= 1<br />
|1<br />
| style="text-align:left;" |<br />
*Number of iterations that the media plays.<br />
* A value of -1 allows the media to loop indefinitely.<br />
|-<br />
| style="text-align:center;" |No<br />
| key <br />
|<key><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;"| No<br />
| tag<br />
| <tag><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Helps categorize media.<br />
|-<br />
| style="text-align:center;" |No<br />
| priority<br />
| 1 to 100<br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Halts the play of current or future played media files with a lower priority while this media plays.<br />
|- style="color: blue;"<br />
| style="text-align:center;"| Maybe<br />
| url<br />
| <url><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Resource location where the media file may be downloaded.<br />
* Only required if the file is to be downloaded remotely.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{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].<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Play a sound file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playSoundFile({<br />
name = "cow.wav"<br />
})<br />
<br />
-- OR copy once from the game's profile, and play a sound file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playSoundFile({<br />
name = getMudletHomeDir().. "/cow.wav"<br />
, volume = 75<br />
})<br />
<br />
-- OR copy once from the local file system, and play a sound file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playSoundFile({<br />
name = "C:/Users/Tamarindo/Documents/cow.wav"<br />
, volume = 75<br />
})<br />
<br />
-- OR download once from the Internet, and play a sound stored in the profile's media directory<br />
---- [volume] of 75<br />
---- [loops] of 2 (-1 for indefinite repeats, 1+ for finite repeats)<br />
---- [key] reference of "cow" for stopping this unique sound later<br />
---- [tag] reference of "animals" to stop a group of sounds later with the same tag<br />
---- [priority] of 25 (1 to 100, 50 default, a sound with a higher priority would stop this one)<br />
---- [url] to download once from the Internet if the sound does not exist in the profile's media directory<br />
playSoundFile({<br />
name = "cow.wav"<br />
, volume = 75<br />
, fadein = nil -- nil lines are optional, no need to use<br />
, fadeout = nil -- nil lines are optional, no need to use<br />
, start = nil -- nil lines are optional, no need to use<br />
, finish = nil -- nil lines are optional, no need to use<br />
, loops = 2<br />
, key = "cow"<br />
, tag = "animals"<br />
, priority = 25<br />
, url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of playSoundFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,priority][,url][,finish]) ----<br />
<br />
-- Play a sound file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playSoundFile(<br />
"cow.wav" -- name<br />
)<br />
<br />
-- OR copy once from the game's profile, and play a sound file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playSoundFile(<br />
getMudletHomeDir().. "/cow.wav" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR copy once from the local file system, and play a sound file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playSoundFile(<br />
"C:/Users/Tamarindo/Documents/cow.wav" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR download once from the Internet, and play a sound stored in the profile's media directory<br />
---- [volume] of 75<br />
---- [loops] of 2 (-1 for indefinite repeats, 1+ for finite repeats)<br />
---- [key] reference of "cow" for stopping this unique sound later<br />
---- [tag] reference of "animals" to stop a group of sounds later with the same tag<br />
---- [priority] of 25 (1 to 100, 50 default, a sound with a higher priority would stop this one)<br />
---- [url] to download once from the Internet if the sound does not exist in the profile's media directory<br />
playSoundFile(<br />
"cow.wav" -- name<br />
, 75 -- volume<br />
, nil -- fadein<br />
, nil -- fadeout<br />
, nil -- start<br />
, 2 -- loops<br />
, "cow" -- key <br />
, "animals" -- tag<br />
, 25 -- priority<br />
, "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/" -- url<br />
, nil -- finish<br />
)<br />
</syntaxhighlight><br />
<br />
==stopMusic, PR #7026==<br />
;stopMusic(settings table)<br />
: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()]].<br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
!Default<br />
! style="text-align:left;"| Purpose<br />
|-<br />
| style="text-align:center;"| No<br />
| name<br />
| <file name><br />
|<br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
|-<br />
| style="text-align:center;" |No<br />
| key <br />
|<key><br />
|<br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;"| No<br />
| tag<br />
| <tag><br />
|<br />
| style="text-align:left;"|<br />
* Helps categorize media.<br />
|-<br />
| style="text-align:center;"| No<br />
| fadeaway<br />
| true or false<br />
|false<br />
| style="text-align:left;" |<br />
* Decrease volume from the current position for a given duration, then stops the track.<br />
* Given duration is the lesser of the remaining track duration or the fadeout specified in playMusicFile().<br />
* If fadeout was not specified in playMusicFile(), then the optional fadeout parameter from stopMusic() or a default of 5000 milliseconds will be applied.<br />
|-<br />
| style="text-align:center;"| No<br />
| fadeout<br />
| <br />
|5000<br />
| style="text-align:left;" |<br />
* Default duration in milliseconds to decrease volume to the end of the track.<br />
* Only used if fadeout was not defined in playMusicFile().<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stop all playing music files for this profile associated with the API<br />
stopMusic()<br />
<br />
-- Stop playing the rugby mp3 by name<br />
stopMusic({name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"})<br />
<br />
-- Stop playing the unique sound identified as "rugby"<br />
stopMusic({<br />
name = nil -- nil lines are optional, no need to use<br />
, key = "rugby" -- key<br />
, tag = nil -- nil lines are optional, no need to use<br />
})<br />
<br />
-- Decrease volume for 5 seconds and then stop all playing music files for this profile associated with the API<br />
stopMusic({<br />
fadeaway = true<br />
})<br />
<br />
-- 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<br />
stopMusic({<br />
fadeaway = true<br />
, fadeout = 10000<br />
})<br />
<br />
-- Decrease volume for 5 seconds and then stop all the unique "rugby" music for this profile associated with the API<br />
stopMusic({<br />
key = "rugby"<br />
, fadeaway = true<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of stopMusic([name][,key][,tag][,fadeaway][,fadeout]) ----<br />
<br />
-- Stop all playing music files for this profile associated with the API<br />
stopMusic()<br />
<br />
-- Stop playing the rugby mp3 by name<br />
stopMusic("167124__patricia-mcmillen__rugby-club-in-spain.mp3")<br />
<br />
-- Stop playing the unique sound identified as "rugby"<br />
stopMusic(<br />
nil -- name<br />
, "rugby" -- key<br />
, nil -- tag<br />
)<br />
<br />
-- Decrease the volume for 10 seconds then stop playing the unique sound identified as "rugby"<br />
stopMusic(<br />
nil -- name<br />
, "rugby" -- key<br />
, nil -- tag<br />
, true -- fadeaway<br />
, 10000 -- fadeout<br />
)<br />
</syntaxhighlight><br />
<br />
==stopSounds, PR #7026==<br />
;stopSounds(settings table)<br />
: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()]].<br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! Default<br />
! style="text-align:left;"| Purpose<br />
|-<br />
| style="text-align:center;"| No<br />
| name<br />
| <file name><br />
| <br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
|-<br />
| style="text-align:center;" |No<br />
| key <br />
|<key><br />
| <br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;"| No<br />
| tag<br />
| <tag><br />
| <br />
| style="text-align:left;"|<br />
* Helps categorize media.<br />
|-<br />
| style="text-align:center;" |No<br />
| priority<br />
| 1 to 100<br />
| <br />
| style="text-align:left;" |<br />
*Halts the play of current or future played media files with a matching or lower priority.<br />
|-<br />
| style="text-align:center;"| No<br />
| fadeaway<br />
| true or false<br />
|false<br />
| style="text-align:left;" |<br />
* Decrease volume from the current position for a given duration, then stops the track.<br />
* Given duration is the lesser of the remaining track duration or the fadeout specified in playSoundFile().<br />
* If fadeout was not specified in playSoundFile(), then the optional fadeout parameter from stopSounds() or a default of 5000 milliseconds will be applied.<br />
|-<br />
| style="text-align:center;"| No<br />
| fadeout<br />
| <br />
|5000<br />
| style="text-align:left;" |<br />
* Default duration in milliseconds to decrease volume to the end of the track.<br />
* Only used if fadeout was not defined in playSoundFile().<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stop all playing sound files for this profile associated with the API<br />
stopSounds()<br />
<br />
-- Stop playing the cow sound<br />
stopSounds({name = "cow.wav"})<br />
<br />
-- Stop playing any sounds tagged as "animals" with a priority less than or equal to 50<br />
---- This would not stop sounds tagged as "animals" greater than priority 50. This is an "AND" and not an "OR".<br />
stopSounds({<br />
name = nil -- nil lines are optional, no need to use<br />
, key = nil -- nil lines are optional, no need to use<br />
, tag = "animals"<br />
, priority = 50<br />
})<br />
<br />
-- Decrease volume for 5 seconds and then stop all playing sound files for this profile associated with the API<br />
stopSounds({<br />
fadeaway = true<br />
})<br />
<br />
-- 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<br />
stopSounds({<br />
fadeaway = true<br />
, fadeout = 10000<br />
})<br />
<br />
-- Decrease volume for 3 seconds and then stop all the tagged "animals" music for this profile associated with the API<br />
stopSounds({<br />
tag = "animals"<br />
, fadeaway = true<br />
, fadeout = 3000<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of stopSounds([name][,key][,tag][,priority][,fadeaway][,fadeout]) ----<br />
<br />
-- Stop all playing sound files for this profile associated with the API<br />
stopSounds()<br />
<br />
-- Stop playing the cow sound<br />
stopSounds("cow.wav")<br />
<br />
-- Stop playing any sounds tagged as "animals" with a priority less than or equal to 50<br />
---- This would not stop sounds tagged as "animals" greater than priority 50. This is an "AND" and not an "OR".<br />
stopSounds(<br />
nil -- name<br />
, nil -- key<br />
, "animals" -- tag<br />
, 50 -- priority<br />
)<br />
<br />
-- Decrease the volume for 7 seconds and then stop playing sounds<br />
stopSounds(<br />
nil -- name<br />
, nil -- key<br />
, nil -- tag<br />
, nil -- priority<br />
, true -- fadeaway<br />
, 7000 -- fadeout<br />
)<br />
</syntaxhighlight><br />
<br />
==createVideoPlayer, PR #6439==<br />
;createVideoPlayer([name of userwindow], x, y, width, height)<br />
<br />
: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.<br />
<br />
{{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.<br />
<br />
{{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.<br />
<br />
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]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a 300x300 video player in the top-left corner of Mudlet<br />
createVideoPlayer(0,0,300,300)<br />
<br />
-- Alternative examples using Geyser.VideoPlayer<br />
GUI.VideoPlayer = GUI.VideoPlayer or Geyser.VideoPlayer:new({name="GUI.VideoPlayer", x = 0, y = 0, width = "25%", height = "25%"})<br />
<br />
GUI.VideoPlayer = GUI.VideoPlayer or Geyser.VideoPlayer:new({<br />
name = "GUI.VideoPlayer",<br />
x = "70%", y = 0, -- edit here if you want to move it<br />
width = "30%", height = "50%"<br />
}, GUI.Right)<br />
</syntaxhighlight><br />
<br />
==loadVideoFile, PR #6439==<br />
;loadVideoFile(settings table) or loadVideoFile(name, [url])<br />
:Loads video files from the Internet or the local file system to the "media" folder of the profile for later use with [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]] and [[Manual:Miscellaneous_Functions#stopVideos|stopVideos()]]. Although files could be loaded or streamed directly at playing time from [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]], loadVideoFile() provides the advantage of loading files in advance.<br />
<br />
{{note}} Video files consume drive space on your device. Consider using the streaming feature of [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]] for large files.<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
! style="text-align:left;" |Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;" |Yes<br />
|name<br />
|<file name><br />
| style="text-align:left;" |<br />
*Name of the media file.<br />
*May contain directory information (i.e. weather/maelstrom.mp4).<br />
*May be part of the profile (i.e. getMudletHomeDir().. "/congratulations.mp4")<br />
*May be on the local device (i.e. "C:/Users/YourNameHere/Movies/nevergoingtogiveyouup.mp4")<br />
|- style="color: blue;"<br />
| style="text-align:center;" |Maybe<br />
|url<br />
|<url><br />
| style="text-align:left;" |<br />
*Resource location where the media file may be downloaded.<br />
*Only required if file to load is not part of the profile or on the local file system.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#playSoundFile|loadSoundFile()]], [[Manual:Miscellaneous Functions#loadMusicFile|loadMusicFile()]], [[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#createVideoPlayer|createVideoPlayer()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Download from the Internet<br />
loadVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
})<br />
<br />
-- OR download from the profile<br />
loadVideoFile({name = getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4"})<br />
<br />
-- OR download from the local file system<br />
loadVideoFile({name = "C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4"})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of loadVideoFile(name[, url]) ----<br />
<br />
-- Download from the Internet<br />
loadVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4"<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
)<br />
<br />
-- OR download from the profile<br />
loadVideoFile(getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4")<br />
<br />
-- OR download from the local file system<br />
loadVideoFile("C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4")<br />
</syntaxhighlight><br />
<br />
==playVideoFile, PR #6439==<br />
;playVideoFile(settings table)<br />
:Plays video files from the Internet or the local file system for later use with [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]]. Video files may be downloaded to the device and played, or streamed from the Internet when the value of the <code>stream</code> parameter is <code>true</code>.<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
!Default<br />
! style="text-align:left;" |Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;" |Yes<br />
|name<br />
|<file name><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Name of the media file.<br />
*May contain directory information (i.e. weather/maelstrom.mp4).<br />
*May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp4")<br />
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp4")<br />
*Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.<br />
|-<br />
| style="text-align:center;" |No<br />
| volume<br />
|1 to 100<br />
|50<br />
| style="text-align:left;" |<br />
*Relative to the volume set on the player's client.<br />
|-<br />
| style="text-align:center;" |No<br />
|fadein<br />
|<msec><br />
|<br />
|<br />
*Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.<br />
*Start position: Start of media.<br />
*End position: Start of media plus the number of milliseconds (msec) specified.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
|fadeout<br />
|<msec><br />
|<br />
|<br />
*Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.<br />
*Start position: End of the media minus the number of milliseconds (msec) specified.<br />
*End position: End of the media.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
|start<br />
|<msec><br />
| 0<br />
| style="text-align:left;" |<br />
*Begin play at the specified position in milliseconds.<br />
|-<br />
| style="text-align:center;" |No<br />
|loops<br />
| -1, or >= 1<br />
|1<br />
| style="text-align:left;" |<br />
*Number of iterations that the media plays.<br />
*A value of -1 allows the media to loop indefinitely.<br />
|-<br />
| style="text-align:center;" |No<br />
|key<br />
|<key><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;" |No<br />
|tag<br />
|<tag><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Helps categorize media.<br />
|-<br />
| style="text-align:center;" |No<br />
|continue<br />
|true or false<br />
|true<br />
| style="text-align:left;" |<br />
*Continues playing matching new video files when true.<br />
*Restarts matching new video files when false.<br />
|- style="color: blue;"<br />
| style="text-align:center;" |Maybe<br />
|url<br />
|<url><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Resource location where the media file may be downloaded.<br />
*Only required if the file is to be downloaded remotely or for streaming from the Internet.<br />
|- style="color: blue;"<br />
| style="text-align:center;" |Maybe<br />
|stream<br />
|true or false<br />
|false<br />
| style="text-align:left;" |<br />
*Streams files from the Internet when true.<br />
*Download files when false (default).<br />
*Used in combination with the `url` key.<br />
|-<br />
|}<br />
<br />
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#stopSounds|stopSounds()]], [[Manual:Miscellaneous Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous Functions#stopVideos|stopVideos()]], [[Manual:Miscellaneous Functions#createVideoPlayer|createVideoPlayer()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stream a video file from the Internet and play it.<br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
, stream = true<br />
})<br />
<br />
-- 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.<br />
<br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
})<br />
<br />
-- Play a video file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
})<br />
<br />
-- OR copy once from the game's profile, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile({<br />
name = getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4"<br />
, volume = 75<br />
})<br />
<br />
-- OR copy once from the local file system, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile({<br />
name = "C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4"<br />
, volume = 75<br />
})<br />
<br />
-- OR download once from the Internet, and play a video stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 10 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 15 seconds from the end of the video<br />
---- [start] 5 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [key] reference of "text" for stopping this unique video later<br />
---- [tag] reference of "ambience" to stop any video later with the same tag<br />
---- [continue] playing this video if another request for the same video comes in (false restarts it) <br />
---- [url] resource location where the file may be accessed on the Internet<br />
---- [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) <br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, volume = nil -- nil lines are optional, no need to use<br />
, fadein = 10000<br />
, fadeout = 15000<br />
, start = 5000<br />
, loops = nil -- nil lines are optional, no need to use<br />
, key = "text"<br />
, tag = "ambience"<br />
, continue = true<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
, stream = false<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of playVideoFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,continue][,url][,stream]) ----<br />
<br />
-- Stream a video file from the Internet and play it.<br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4"<br />
, nil -- volume<br />
, nil -- fadein<br />
, nil -- fadeout<br />
, nil -- start<br />
, nil -- loops<br />
, nil -- key<br />
, nil -- tag<br />
, true -- continue<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/" -- url<br />
, false -- stream<br />
)<br />
<br />
-- 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.<br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4"<br />
, nil -- volume<br />
, nil -- fadein<br />
, nil -- fadeout<br />
, nil -- start<br />
, nil -- loops<br />
, nil -- key<br />
, nil -- tag<br />
, true -- continue<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/" -- url<br />
, false -- stream<br />
)<br />
<br />
-- Play a video file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4" -- name<br />
)<br />
<br />
-- OR copy once from the game's profile, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile(<br />
getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR copy once from the local file system, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile(<br />
"C:/Users/Tamarindo/Documents/TextInMotion-VideoSample-1080p.mp4" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR download once from the Internet, and play a video stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 10 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 15 seconds from the end of the video<br />
---- [start] 5 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [key] reference of "text" for stopping this unique video later<br />
---- [tag] reference of "ambience" to stop any video later with the same tag<br />
---- [continue] playing this video if another request for the same video comes in (false restarts it) <br />
---- [url] resource location where the file may be accessed on the Internet<br />
---- [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) <br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4" -- name<br />
, nil -- volume<br />
, 10000 -- fadein<br />
, 15000 -- fadeout<br />
, 5000 -- start<br />
, nil -- loops<br />
, "text" -- key<br />
, "ambience" -- tag<br />
, true -- continue<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/" -- url<br />
, false -- stream<br />
)<br />
</syntaxhighlight><br />
<br />
<br />
==stopVideos, PR #6439==<br />
;stopVideos(settings table)<br />
:Stop all videos (no filter), or videos that meet a combination of filters (name, key, and tag) intended to be paired with [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]].<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
! style="text-align:left;" |Purpose<br />
|-<br />
| style="text-align:center;" |No<br />
| name<br />
| <file name><br />
| style="text-align:left;" |<br />
* Name of the media file.<br />
|-<br />
| style="text-align:center;" |No<br />
|key<br />
|<key><br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;" |No<br />
|tag<br />
|<tag><br />
| style="text-align:left;" |<br />
*Helps categorize media.<br />
|-<br />
|}<br />
<br />
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#createVideoPlayer|createVideoPlayer()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stop all playing video files for this profile associated with the API<br />
stopVideos()<br />
<br />
-- Stop playing the text mp4 by name<br />
stopVideos({name = "TextInMotion-VideoSample-1080p.mp4"})<br />
<br />
-- Stop playing the unique sound identified as "text"<br />
stopVideos({<br />
name = nil -- nil lines are optional, no need to use<br />
, key = "text" -- key<br />
, tag = nil -- nil lines are optional, no need to use<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of stopVideos([name][,key][,tag]) ----<br />
<br />
-- Stop all playing video files for this profile associated with the API<br />
stopVideos()<br />
<br />
-- Stop playing the text mp4 by name<br />
stopVideos("TextInMotion-VideoSample-1080p.mp4")<br />
<br />
-- Stop playing the unique sound identified as "text"<br />
stopVideos(<br />
nil -- name<br />
, "text" -- key<br />
, nil -- tag<br />
)<br />
</syntaxhighlight><br />
<br />
<br />
==getCustomLoginTextId, PR #3952 open==<br />
;getCustomLoginTextId()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#sendPassword|sendPassword()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+Predefined custom login texts<br />
|-<br />
!Id!!Custom text!!Introduced in Mudlet version<br />
|-<br />
|1||"connect {character name} {password}"||TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCharacterName, PR #3952 open==<br />
;sendCharacterName()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
==sendCharacterPassword, PR #3952 open==<br />
;sendCharacterPassword()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]], [[#sendCharacterName|sendCharacterName()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCharacterName() ~= "" then<br />
tempTime(2.0, [[sendCharacterName()]], 1)<br />
tempTime(3.0, [[sendCharacterPassword()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCustomLoginText, PR #3952 open ==<br />
;sendCustomLoginText()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendPassword|sendPassword()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+Predefined custom login texts<br />
|-<br />
!Id!!Custom text!!Introduced in Mudlet version<br />
|-<br />
|1||"connect {character name} {password}"||TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
=Mudlet Object Functions=<br />
:A collection of functions that manipulate Mudlet's scripting objects - triggers, aliases, and so forth.<br />
<br />
==ancestors, new in PR #6726==<br />
;ancestors(IDnumber, type)<br />
:You can use this function to find out about all the ancestors of something.<br />
<br />
:Returns a list as a table with the details of each successively distance ancestor (if any) of the given item; the details are in the form of a sub-table, within each containing specifically:<br />
:* its IDnumber as a number<br />
:* its name as a string<br />
:* whether it is active as a boolean<br />
:* its "node" (type) as a string, one of "item", "group" (folder) or "package" (module)<br />
:Returns ''nil'' and an error message if either parameter is not valid<br />
<br />
;Parameters<br />
* ''IDnumber:''<br />
: The ID number of a single item, (which will be that returned by a ''temp*'' or ''perm*'' function to create such an item to identify the item).<br />
* ''type:''<br />
: The type can be 'alias', 'button', 'trigger', 'timer', 'keybind', or 'script'.<br />
<br />
: See also: [[#isAncestorsActive|isAncestorsActive(...)]], [[#isActive|isActive(...)]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- To do<br />
</syntaxhighlight><br />
<br />
==findItems, new in PR #6742==<br />
;findItems("name", "type"[, exact[, case sensitive]])<br />
: You can use this function to determine the ID number or numbers of items of a particular type with a given name.<br />
<br />
:Returns a list as a table with ids of each Mudlet item that matched or ''nil'' and an error message should an incorrect type string be given.<br />
<br />
;Parameters<br />
* ''name:''<br />
:The name (as a string) of the item, (which will be that returned by a ''temp*'' or ''perm*'' function to create such an item to identify the item).<br />
* ''type:''<br />
:The type (as a string) can be 'alias', 'button', 'trigger', 'timer', 'keybind' , or 'script'.<br />
* ''exact:''<br />
:(Optional) a boolean which if omitted or ''true'' specifies to match the given name against the whole of the names for items or only as a sub-string of them. As a side effect, if this is provided and is ''false'' and an empty string (i.e. ''""'') is given as the first argument then the function will return the ID numbers of ''all'' items (both temporary and permanent) of the given type in existence at the time.<br />
* ''case sensitive:''<br />
:(Optional) a boolean which if omitted or ''true'' specifies to match in a case-sensitive manner the given name against the names for items.<br />
<br />
;Example<br />
Given a profile with just the default packages installed (automatically) - including the '''echo''' one:<br />
[[File:View of standard aliases with focus on echo package.png|border|none|400px|link=]]<br />
<br />
<syntaxhighlight lang="lua"><br />
-- Should find just the package with the name:<br />
lua findItems("echo", "alias")<br />
{ 3 }<br />
<br />
-- Should find both the package and the alias - as the latter contains "echo" with another character<br />
lua findItems("echo", "alias", false)<br />
{ 3, 4 }<br />
<br />
-- Finds the ID numbers of all the aliases:<br />
lua findItems("", "alias", false)<br />
{ 1, 2, 3, 4, 5, 6, 7 }<br />
<br />
-- Will still find the package with the name "echo" as we are not concerned with the casing now:<br />
lua findItems("Echo", "alias", true, false)<br />
{ 3 }<br />
<br />
-- Won't find the package with the name "echo" now as we are concerned with the casing:<br />
lua findItems("Echo", "alias", true, true)<br />
{}<br />
</syntaxhighlight><br />
<br />
==isActive, modified by PR #6726==<br />
;isActive(name/IDnumber, type[, checkAncestors])<br />
:You can use this function to check if something, or somethings, are active. <br />
<br />
:Returns the number of active things - and 0 if none are active. Beware that all numbers are true in Lua, including zero.<br />
<br />
;Parameters<br />
* ''name:''<br />
:The name (as a string) or, from '''Mudlet 4.17.0''', the ID number of a single item, (which will be that returned by a ''temp*'' or ''perm*'' function to create such an item to identify the item).<br />
* ''type:''<br />
:The type can be 'alias', 'button' (from '''Mudlet 4.10'''), 'trigger', 'timer', 'keybind' (from '''Mudlet 3.2'''), or 'script' (from '''Mudlet 3.17''').<br />
* ''checkAncestors:''<br />
:(Optional) If provided AND ''true'' (considered ''false'' if absent to reproduce behavior of previous versions of Mudlet) then this function will only count an item as active if it '''and''' all its parents (ancestors) are active (from '''Mudlet tbd''').<br />
<br />
:See also: [[#exists|exists(...)]], [[#isAncestorsActive|isAncestorsActive(...)]], [[#ancestors|ancestors(...)]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo("I have " .. isActive("my trigger", "trigger") .. " currently active trigger(s) called 'my trigger'!")<br />
<br />
-- Can also be used to check if a specific item is enabled or not.<br />
if isActive("spellname", "trigger") > 0 then<br />
-- the spellname trigger is active<br />
else<br />
-- it is not active<br />
end<br />
</syntaxhighlight><br />
<br />
{{note}} A positive ID number that does not exist will still return a ''0'' value, this is for constancy with the way the function behaves for a name that does not refer to any item either. If necessary the existence of an item should be confirmed with [[#exists|exists(...)]] first.<br />
<br />
==isAncestorsActive, new in PR #6726==<br />
;isAncestorsActive(IDnumber, "type")<br />
:You can use this function to check if '''all''' the ancestors of something are active independent of whether it itself is, (for that use the two argument form of [[#isActive|isActive(...)]]). <br />
<br />
:Returns ''true'' if all (if any) of the ancestors of the item with the specified ID number and type are active, if there are no such parents then it will also returns ''true''; otherwise returns ''false''. In the event that an invalid type string or item number is provided returns ''nil'' and an error message.<br />
<br />
;Parameters<br />
* ''IDnumber:''<br />
:The ID number of a single item, (which will be that returned by a ''temp*'' or ''perm*'' function to create such an item to identify the item).<br />
* ''type:''<br />
:The type can be 'alias', 'button', 'trigger', 'timer', 'keybind' or 'script' to define which item type is to be checked.<br />
<br />
:See also: [[#exists|exists(...)]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- To do<br />
</syntaxhighlight><br />
<br />
=Networking Functions=<br />
:A collection of functions for managing networking.<br />
==sendSocket revised in PR #7066 (Open)==<br />
<br />
;sendSocket(data)<br />
<br />
:Sends given binary data as-is (or with some predefined special tokens converted to byte values) 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] etc.<br />
<br />
; success = sendSocket("data")<br />
<br />
;See also: [[Manual:Lua_Functions#feedTelnet|feedTelnet()]], [[Manual:Lua_Functions#feedTriggers|feedTriggers()]]<br />
<br />
{{note}} Modified in Mudlet '''tbd''' to accept some tokens like "''<NUL>''" to include byte values that are not possible to insert with the standard Lua string escape "''\###''" form where ### is a three digit number between 000 and 255 inclusive or where the value is more easily provided via a mnemonic. For the table of the tokens that are known about, see the one in [[Manual:Lua_Functions#feedTelnet|feedTelnet()]].<br />
<br />
{{note}} The data (as bytes) once the tokens have been converted to their byte values is sent as is to the Game Server; any encoding to, say, a UTF-8 representation or to duplicate ''0xff'' byte values so they are not considered to be Telnet ''<IAC>'' (Interpret As Command) bytes must be done to the data prior to calling this function.<br />
<br />
;Parameters<br />
* ''data:''<br />
: String containing the bytes to send to the Game Server possibly containing some tokens that are to be converted to bytes as well.<br />
<br />
;Returns <br />
* (Only since Mudlet '''tbd''') Boolean ''true'' if the whole data string (after token replacement) was sent to the Server, ''false'' if that failed for any reason (including if the Server has not been connected or is now disconnected). ''nil'' and an error message for any other defect.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Tell the Server that we are now willing and able to process to process Ask the Server to a comment explaining what is going on, if there is multiple functionalities (or optional parameters) the examples should start simple and progress in complexity if needed!<br />
-- the examples should be small, but self-contained so new users can copy & paste immediately without going diving in lots other function examples first.<br />
-- comments up top should introduce / explain what it does<br />
<br />
local something = function(exampleValue)<br />
if something then<br />
-- do something with something (assuming there is a meaningful return value)<br />
end<br />
<br />
-- maybe another example for the optional second case<br />
local somethingElse = function(exampleValue, anotherValue)<br />
<br />
-- lastly, include an example with error handling to give an idea of good practice<br />
local ok, err = function()<br />
if not ok then<br />
debugc(f"Error: unable to do <particular thing> because {err}\n")<br />
return<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
-- This function is still being written up.<br />
<br />
==feedTelnet added in PR #7066 (Open)====<br />
<br />
; feedTelnet(data)<br />
<br />
:Sends given binary data with some predefined special tokens converted to byte values, to the internal telnet engine, as if it had been received from the game. This is primarily to enable testing when new Telnet sub-options/protocols are being developed. The data has to be injected into the system nearer to the point where the Game Server's data starts out than ''feedTriggers()'' and unlike the latter the data is not subject to any encoding so as to match the current profile's setting (which normally happens with ''feedTriggers()''). Furthermore - to prevent this function from putting the telnet engine into a state which could damage the processing of real game data it will refuse to work unless the Profile is completely disconnected from the game server.<br />
<br />
;See also: [[Manual:Lua_Functions#feedTriggers|feedTriggers()]], [[Manual:Lua_Functions#sendSocket|sendSocket()]]<br />
<br />
{{MudletVersion|tbd}}<br />
<br />
{{note}} This is not really intended for end-user's but might be useful in some circumstances.<br />
<br />
;Parameters<br />
* ''data''<br />
: String containing the bytes to send to the internal telnet engine as if it had come from the Game Server, it can containing some tokens listed below that are to be converted to bytes as well.<br />
<br />
;Returns <br />
* Boolean ''true'' if the ''data'' string was sent to the internal telnet engine. ''nil'' and an error message otherwise, specifically the case when there is some traces of a connection or a complete connection to the socket that passes the data to and from the game server. Additionally, if the data is an empty string ''""'' a second return value will be provided as an integer number representing a version for the table of tokens - which will be incremented each time a change is made to that table so that which tokens are valid can be determined. Note that unrecognised tokens should be passed through as is and not get replaced.<br />
<br />
{| class="wikitable sortable"<br />
|+ Token value table<br />
|-<br />
! Token !! Byte !! Version!! Notes<br />
|-<br />
|| <00> || \0x00 || 1 || 0 dec.<br />
|-<br />
|| <O_BINARY> || \0x00 || 1 || Telnet option: Binary<br />
|-<br />
|| <NUL> || \0x00 || 1 || ASCII control character: NULL<br />
|-<br />
|| <01> || \x01 || 1 || 1 dec.<br />
|-<br />
|| <O_ECHO> || \x01 || 1 || Telnet option: Echo<br />
|-<br />
|| <SOH> || \x01 || 1 || ASCII control character: Start of Heading<br />
|-<br />
|| <02> || \x02 || 1 || 2 dec. Telnet option: Reconnect<br />
|-<br />
|| <STX> || \x02 || 1 || ASCII control character: Start of Text<br />
|-<br />
|| <03> || \x03 || 1 || 3 dec.<br />
|-<br />
|| <O_SGA> || \x03 || 1 || Telnet option: Suppress Go Ahead<br />
|-<br />
|| <ETX> || \x03 || 1 || ASCII control character: End of Text<br />
|-<br />
|| <04> || \x04 || 1 || Telnet option: Approx Message Size Negotiation<br />
|-<br />
|| <EOT> || \x04 || 1 || ASCII control character: End of Transmission<br />
|-<br />
|| <05> || \x05 || 1 || <br />
|-<br />
|| <O_STATUS> || \x05 || 1 ||<br />
|-<br />
|| <ENQ> || \x05 || 1 || ASCII control character: Enquiry<br />
|-<br />
|| <06> || \x06 || 1 || Telnet option: Timing Mark<br />
|-<br />
|| <ACK> || \x06 || 1 || ASCII control character: Acknowledge<br />
|-<br />
|| <07> || \x07 || 1 || Telnet option: Remote Controlled Trans and Echo<br />
|-<br />
|| <BELL> || \x07 || 1 || ASCII control character: Bell<br />
|-<br />
|| <08> || \x08 || 1 || Telnet option: Output Line Width<br />
|-<br />
|| <BS> || \x08 || 1 ||<br />
|-<br />
|| <09> || \x09 || 1 || Telnet option: Output Page Size<br />
|-<br />
|| <HTAB> || \x09 || 1 || ASCII control character: Horizontal Tab<br />
|-<br />
|| <0A> || \x0a || 1 || Telnet option: Output Carriage-Return Disposition<br />
|-<br />
|| <LF> || \x0a || 1 || ASCII control character: Line-Feed<br />
|-<br />
|| <0B> || \x0b || 1 || Telnet option: Output Horizontal Tab Stops<br />
|-<br />
|| <VTAB> || \x0b || 1 || ASCII control character: Vertical Tab<br />
|-<br />
|| <0C> || \x0c || 1 || Telnet option: Output Horizontal Tab Disposition<br />
|-<br />
|| <FF> || \x0c || 1 || ASCII control character: Form-Feed<br />
|-<br />
|| <0D> || \x0d || 1 || Telnet option: Output Form-feed Disposition<br />
|-<br />
|| <CR> || \x0d || 1 || ASCII control character: Carriage-Return<br />
|-<br />
|| <0E> || \x0e || 1 || Telnet option: Output Vertical Tab Stops<br />
|-<br />
|| <SO> || \x0e || 1 || ASCII control character: Shift-Out<br />
|-<br />
|| <0F> || \x0f || 1 || Telnet option: Output Vertical Tab Disposition<br />
|-<br />
|| <SI> || \x0f || 1 || ASCII control character: Shift-In<br />
|-<br />
|| <10> || \x10 || 1 || Telnet option: Output Linefeed Disposition<br />
|-<br />
|| <DLE> || \x10 || 1 || ASCII control character: Data Link Escape<br />
|-<br />
|| <11> || \x11 || 1 || Telnet option: Extended ASCII<br />
|-<br />
|| <DC1> || \x11 || 1 || ASCII control character: Device Control 1<br />
|-<br />
|| <12> || \x12 || 1 || Telnet option: Logout<br />
|-<br />
|| <DC2" || \x12 || 1 || ASCII control character: Device Control 2<br />
|-<br />
|| <13> || \x13 || 1 || Telnet option: Byte Macro<br />
|-<br />
|| <DC3> || \x13 || 1 || ASCII control character: Device Control 3<br />
|-<br />
|| <14> || \x14 || 1 || Telnet option: Data Entry Terminal<br />
|-<br />
|| <DC4> || \x14 || 1 || ASCII control character: Device Control 4<br />
|-<br />
|| <15> || \x15 || 1 || Telnet option: SUPDUP<br />
|-<br />
|| <NAK> || \x15 || 1 || ASCII control character: Negative Acknowledge<br />
|-<br />
|| <16> || \x16 || 1 || Telnet option: SUPDUP Output<br />
|-<br />
|| <SYN> || \x16 || 1 || ASCII control character: Synchronous Idle<br />
|-<br />
|| <17> || \x17 || 1 || Telnet option: Send location<br />
|-<br />
|| <ETB> || \x17 || 1 || ASCII control character: End of Transmission Block<br />
|-<br />
|| <18> || \x18 || 1 ||<br />
|-<br />
|| <O_TERM> || \x18 || 1 || Telnet option: Terminal Type<br />
|-<br />
|| <CAN> || \x18 || 1 || ASCII control character: Cancel<br />
|-<br />
|| <19> || \x19 || 1 ||<br />
|-<br />
|| <O_EOR> || \x19 || 1 || Telnet option: End-of-Record<br />
|-<br />
|| <nowiki><EM></nowiki> || \x19 || 1 || ASCII control character: End of Medium<br />
|-<br />
|| <1A> || \x1a || 1 || Telnet option: TACACS User Identification<br />
|-<br />
|| <nowiki><SUB></nowiki> || \x1a || 1 || ASCII control character: Substitute<br />
|-<br />
|| <1B> || \x1b || 1 || Telnet option: Output Marking<br />
|-<br />
|| <ESC> || \x1b || 1 || ASCII control character: Escape<br />
|-<br />
|| <1C> || \x1c || 1 || Telnet option: Terminal Location Number<br />
|-<br />
|| <FS> || \x1c || 1 || ASCII control character: File Separator<br />
|-<br />
|| <1D> || \x1d || 1 || Telnet option: Telnet 3270 Regime<br />
|-<br />
|| <GS> || \x1d || 1 || ASCII control character: Group Separator<br />
|-<br />
|| <1E> || \x1e || 1 || Telnet option: X.3 PAD<br />
|-<br />
|| <RS> || \x1e || 1 || ASCII control character: Record Separator<br />
|-<br />
|| <1F> || \x1f || 1 ||<br />
|-<br />
|| <O_NAWS> || \x1f || 1 || Telnet option: Negotiate About Window Size<br />
|-<br />
|| <US> || \x1f || 1 || ASCII control character: Unit Separator<br />
|-<br />
|| <SP> || \x20 || 1 || 32 dec. ASCII character: Space<br />
|-<br />
|| <O_NENV> || \x27 || 1 || 39 dec. Telnet option: New Environment (also MNES)<br />
|-<br />
|| <O_CHARS> || \x2a || 1 || 42 dec. Telnet option: Character Set<br />
|-<br />
|| <O_KERMIT> || \x2f || 1 || 47 dec. Telnet option: Kermit<br />
|-<br />
|| <O_MSDP> || \x45 || 1 || 69 dec. Telnet option: Mud Server Data Protocol<br />
|-<br />
|| <O_MSSP> || \x46 || 1 || 70 dec. Telnet option: Mud Server Status Protocol<br />
|-<br />
|| <O_MCCP> || \x55 || 1 || 85 dec<br />
|-<br />
|| <O_MCCP2> || \x56 || 1 || 86 dec<br />
|-<br />
|| <O_MSP> || \x5a || 1 || 90 dec. Telnet option: Mud Sound Protocol<br />
|-<br />
|| <O_MXP> || \x5b || 1 || 91 dec. Telnet option: Mud eXtension Protocol<br />
|-<br />
|| <O_ZENITH> || \x5d || 1 || 93 dec. Telnet option: Zenith Mud Protocol<br />
|-<br />
|| <O_AARDWULF> || \x66 || 1 || 102 dec. Telnet option: Aardwuld Data Protocol<br />
|-<br />
|| <nowiki><DEL></nowiki> || \x7f || 1 || 127 dec. ASCII control character: Delete<br />
|-<br />
|| <O_ATCP> || \xc8 || 1 || 200 dec<br />
|-<br />
|| <O_GMCP> || \xc9 || 1 || 201 dec<br />
|-<br />
|| <T_EOR> || \xef || 1 || 239 dec<br />
|-<br />
|| <F0> || \xf0 || 1 ||<br />
|-<br />
|| <T_SE> || \xf0 || 1 ||<br />
|-<br />
|| <F1> || \xf1 || 1 ||<br />
|-<br />
|| <T_NOP> || \xf1 || 1 ||<br />
|-<br />
|| <F2> || \xf2 || 1 ||<br />
|-<br />
|| <T_DM> || \xf2 || 1 ||<br />
|-<br />
|| <F3> || \xf3 || 1 ||<br />
|-<br />
|| <T_BRK> || \xf3 || 1 ||<br />
|-<br />
|| <F4> || \xf4 || 1 ||<br />
|-<br />
|| <T_IP> || \xf4 || 1 ||<br />
|-<br />
|| <F5> || \xf5 || 1 ||<br />
|-<br />
|| <T_ABOP> || \xf5 || 1 ||<br />
|-<br />
|| <F6> || \xf6 || 1 ||<br />
|-<br />
|| <T_AYT> || \xf6 || 1 ||<br />
|-<br />
|| <F7> || \xf7 || 1 ||<br />
|-<br />
|| <T_EC> || \xf7 || 1 ||<br />
|-<br />
|| <F8> || \xf8 || 1 ||<br />
|-<br />
|| <T_EL> || \xf8 || 1 ||<br />
|-<br />
|| <F9> || \xf9 || 1 ||<br />
|-<br />
|| <T_GA> || \xf9 || 1 ||<br />
|-<br />
|| <FA> || \xfa || 1 ||<br />
|-<br />
|| <T_SB> || \xfa || 1 ||<br />
|-<br />
|| <FB> || \xfb || 1 ||<br />
|-<br />
|| <T_WILL> || \xfb || 1 ||<br />
|-<br />
|| <FC> || \xfc || 1 ||<br />
|-<br />
|| <T_WONT> || \xfc || 1 ||<br />
|-<br />
|| <FD> || \xfd || 1 ||<br />
|-<br />
|| <T_DO> || \xfd || 1 ||<br />
|-<br />
|| <FE> || \xfe || 1 ||<br />
|-<br />
|| <T_DONT> || \xfe || 1 ||<br />
|-<br />
|| <FF> || \xff || 1 ||<br />
|-<br />
|| <T_IAC> || \xff'<br />
|}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- a comment explaining what is going on, if there is multiple functionalities (or optional parameters) the examples should start simple and progress in complexity if needed!<br />
-- the examples should be small, but self-contained so new users can copy & paste immediately without going diving in lots other function examples first.<br />
-- comments up top should introduce / explain what it does<br />
<br />
local something = feedTelnet(exampleValue)<br />
if something then<br />
-- do something with something (assuming there is a meaningful return value)<br />
end<br />
<br />
-- maybe another example for the optional second case<br />
local somethingElse = function(exampleValue, anotherValue)<br />
<br />
-- lastly, include an example with error handling to give an idea of good practice<br />
local ok, err = function()<br />
if not ok then<br />
debugc(f"Error: unable to do <particular thing> because {err}\n")<br />
return<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
-- This function is still being written up.<br />
<br />
=String Functions=<br />
:These functions are used to manipulate strings.<br />
<br />
=Table Functions=<br />
: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.<br />
<br />
=Text to Speech Functions=<br />
:These functions are used to create sound from written words. Check out our [[Special:MyLanguage/Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.<br />
<br />
=UI Functions=<br />
: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.<br />
<br />
==cecho2decho PR#6849 merged==<br />
; convertedString = cecho2decho(str)<br />
<br />
:Converts a cecho formatted string to a decho formatted one. <br />
;See also: [[Manual:Lua_Functions#decho2cecho|decho2cecho()]], [[Manual:Lua_Functions#cecho2html|cecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from cecho to decho<br />
;Returns <br />
* a string formatted for decho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to a decho string and use decho to display it<br />
local cechoString = "<red><b>!!ALERT!!:</b><orange> Something has gone wrong!\n"<br />
decho(cecho2decho(cechoString))<br />
</syntaxhighlight><br />
<br />
==cecho2hecho PR#6849 merged==<br />
; convertedString = cecho2hecho(str)<br />
<br />
:Converts a cecho formatted string to an hecho formatted one. <br />
;See also: [[Manual:Lua_Functions#hecho2cecho|hecho2cecho()]], [[Manual:Lua_Functions#cecho2html|cecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from cecho to decho<br />
;Returns <br />
* a string formatted for hecho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to an hecho string and use hecho to display it<br />
local cechoString = "<red><b>!!ALERT!!:</b><orange> Something has gone wrong!\n"<br />
hecho(cecho2hecho(cechoString))<br />
</syntaxhighlight><br />
<br />
==cecho2html PR#6849 merged==<br />
; convertedString = cecho2html(str[, resetFormat])<br />
<br />
:Converts a cecho formatted string to an html formatted one. <br />
;See also: [[Manual:Lua_Functions#decho2cecho|decho2cecho()]], [[Manual:Lua_Functions#decho2html|cecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from cecho to decho<br />
* ''resetFormat''<br />
: optional table of default formatting options. As returned by [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
;Returns <br />
* a string formatted for html<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create the base string<br />
local cechoString = "<red><b>!!ALERT!!:</b><orange> Something has gone wrong!\n"<br />
<br />
-- create a label to display the result onto<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
<br />
-- convert the cecho string to an html one, using the default formatting of testLabel created above<br />
local htmlString = cecho2html(cechoString, testLabel:getFormat())<br />
<br />
-- and finally echo it to the label to see<br />
-- I use rawEcho as that displays the html exactly as given.<br />
testLabel:rawEcho(htmlString)<br />
</syntaxhighlight><br />
<br />
==decho2cecho PR#6849 merged==<br />
; convertedString = decho2cecho(str)<br />
<br />
:Converts a decho formatted string to a cecho formatted one. <br />
;See also: [[Manual:Lua_Functions#cecho2decho|cecho2decho()]], [[Manual:Lua_Functions#decho2html|decho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from decho to cecho<br />
;Returns <br />
* a string formatted for cecho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to a decho string and use cecho to display it<br />
local dechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n"<br />
cecho(decho2cecho(dechoString))<br />
</syntaxhighlight><br />
<br />
==decho2hecho PR#6849 merged==<br />
; convertedString = decho2hecho(str)<br />
<br />
:Converts a decho formatted string to an hecho formatted one. <br />
;See also: [[Manual:Lua_Functions#hecho2decho|hecho2decho()]], [[Manual:Lua_Functions#decho2html|decho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from decho to decho<br />
;Returns <br />
* a string formatted for hecho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to an hecho string and use hecho to display it<br />
local dechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n"<br />
hecho(decho2hecho(dechoString))<br />
</syntaxhighlight><br />
<br />
==decho2html PR#6849 merged==<br />
; convertedString = decho2html(str[, resetFormat])<br />
<br />
:Converts a decho formatted string to an html formatted one. <br />
;See also: [[Manual:Lua_Functions#cecho2decho|cecho2decho()]], [[Manual:Lua_Functions#decho2html|decho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from decho to decho<br />
* ''resetFormat''<br />
: optional table of default formatting options. As returned by [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
;Returns <br />
* a string formatted for html<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create the base string<br />
local dechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n"<br />
<br />
-- create a label to display the result onto<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
<br />
-- convert the decho string to an html one, using the default formatting of testLabel created above<br />
local htmlString = decho2html(dechoString, testLabel:getFormat())<br />
<br />
-- and finally echo it to the label to see<br />
-- I use rawEcho as that displays the html exactly as given.<br />
testLabel:rawEcho(htmlString)<br />
</syntaxhighlight><br />
<br />
==deleteMultiline PR #6779 merged==<br />
<br />
; ok,err = deleteMultiline([triggerDelta])<br />
<br />
:Deletes all lines between when the multiline trigger fires and when the first trigger matched. Put another way, it deletes everything since the pattern in slot 1 matched.<br />
;See also: [[Manual:Lua_Functions#deleteLine|deleteLine()]], [[Manual:Lua_Functions#replaceLine|replaceLine()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
{{note}} This deletes all the lines since the first match of the multiline trigger matched. Do not use this if you do not want to delete ALL of those lines.<br />
<br />
;Parameters<br />
* ''[optional]triggerDelta:''<br />
: The line delta from the multiline trigger it is being called from. It is best to pass this in to ensure all lines are caught. If not given it will try to guess based on the number of patterns how many lines at most it might have to delete.<br />
<br />
;Returns <br />
* true if the function was able to run successfully, nil+error if something went wrong.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- if this trigger has a line delta of 3, you would call<br />
deleteMultiline(3)<br />
<br />
-- same thing, but with error handling<br />
local ok,err = deleteMultiline(3)<br />
if not ok then<br />
cecho("\n<firebrick>I could not delete the lines because: " .. err)<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
==echoPopup, revised in PR #6946==<br />
;echoPopup([windowName,] text, {commands}, {hints}[, useCurrentFormatElseDefault])<br />
: 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 there is one extra hint then the first one will be used as a (maybe containing Qt rich-text markup) tool-tip for the text otherwise the remaining hints will be concatenated, one-per-line, as a tool-tip when the text is hovered over by the pointer.<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (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.<br />
* ''text:''<br />
: the text string to display.<br />
* ''{commands}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight>.<br />
* ''{hints}:''<br />
: a table of strings which will be shown on the right-click menu and as a tool-tip for the ''text''. If the number is the same as that of the ''commands'' table then they all will be used for the right-click menu and listed (one per line) as a plain text tooltip; alternatively if there is one extra in number than the ''commands'' table the first will be used purely for the tool tip and the remainder will be used for the right-click menu. This additional entry may be formatted as Qt style "rich-text" (in the same manner as labels elsewhere in the GUI).<br />
::* If a particular position in the ''commands'' table is an empty string ''""'' but there is something in the ''hints'' table then it will be listed in the right-click menu but as it does not do anything it will be shown ''greyed-out'' i.e. disabled and will not be clickable.<br />
::* If a particular position in '''both''' the ''commands'' and the ''hints'' table are empty strings ''""'' then this item will show as a ''separator'' (usually as a horizontal-line) in the right-click menu and it will not be clickable/do anything. <br />
* ''useCurrentFormatElseDefault:''<br />
: (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.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu, a left click will ''send "sleep"'':<br />
echoPopup("activities to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"})<br />
<br />
-- alternatively, put commands as text (in [[ and ]] to use quotation marks inside)<br />
echoPopup("activities to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"})<br />
<br />
-- one can also provide helpful information<br />
<br />
-- todo: an example with rich-text in the tool-tips(s) - not complete yet!<br />
echoPopup("Fancy popup", {[[echo("Doing command 1 (default one)")]], "", "", [[echo("Doing command 3")]], [[echo("Doing another command (number 4)"]], [[echo("Doing another command (number 5)"]])}, {"<p>This tooltip has HTML type tags in/around it, and it will get word-wrapped automatically to fit into a reasonable rectangle.</p><p><b>Plus</b> it can have those HTML like <i>effects</i> and be easily formatted into more than one paragraph and with <span style=\"color:cyan\">bits</span> in <span style=\"color:lime\">different</span> colors!</p><p>This example also demonstrates how to produce disabled menu (right-click) items, how to insert separators and how it now will handle multiple items with the same hint (prior to PR 6945 such duplicates will all run the command associated with the last one!) If the first command/function is an empty string then clicking on the text will have no effect, but hovering the mouse over the text will still produce the tooltip, this could be useful to display extra information about the text without doing anything by default.</p>", "Command 1 (default)", "", "Command 2 (disabled)", "Command 3", "Another command", "Another command"}, true)<br />
echo(" remaining text.\n")<br />
<br />
</syntaxhighlight><br />
<br />
==hecho2cecho PR#6849 merged==<br />
; convertedString = hecho2cecho(str)<br />
<br />
:Converts a hecho formatted string to a cecho formatted one. <br />
;See also: [[Manual:Lua_Functions#cecho2decho|cecho2decho()]], [[Manual:Lua_Functions#hecho2html|hecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from hecho to cecho<br />
;Returns <br />
* a string formatted for cecho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to a hecho string and use cecho to display it<br />
local hechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n""<br />
cecho(hecho2cecho(hechoString))<br />
</syntaxhighlight><br />
<br />
==hecho2decho PR#6849 merged==<br />
; convertedString = hecho2decho(str)<br />
<br />
:Converts a hecho formatted string to a decho formatted one. <br />
;See also: [[Manual:Lua_Functions#decho2hecho|decho2hecho()]], [[Manual:Lua_Functions#hecho2html|hecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from hecho to decho<br />
;Returns <br />
* a string formatted for decho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to a decho string and use decho to display it<br />
local hechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n""<br />
decho(hecho2decho(hechoString))<br />
</syntaxhighlight><br />
<br />
==hecho2html PR#6849 merged==<br />
; convertedString = hecho2html(str[, resetFormat])<br />
<br />
:Converts a hecho formatted string to an html formatted one. <br />
;See also: [[Manual:Lua_Functions#cecho2hecho|cecho2hecho()]], [[Manual:Lua_Functions#hecho2html|hecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from hecho to hecho<br />
* ''resetFormat''<br />
: optional table of default formatting options. As returned by [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
;Returns <br />
* a string formatted for html<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create the base string<br />
local hechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n""<br />
<br />
-- create a label to display the result onto<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
<br />
-- convert the hecho string to an html one, using the default formatting of testLabel created above<br />
local htmlString = hecho2html(hechoString, testLabel:getFormat())<br />
<br />
-- and finally echo it to the label to see<br />
-- I use rawEcho as that displays the html exactly as given.<br />
testLabel:rawEcho(htmlString)<br />
</syntaxhighlight><br />
<br />
==insertPopup, revised in PR #6925==<br />
;insertPopup([windowName], text, {commands}, {hints}[{, tool-tips}][, useCurrentFormatElseDefault])<br />
: 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.<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (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.<br />
* ''text:''<br />
: the text string to display.<br />
* ''{commands}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight>.<br />
* ''{hints}:''<br />
: 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.<br />
* ''{tool-tips}:''<br />
: (optional) a table of possibly ''rich-text'' strings which will be shown on the popup if provided. <br />
* ''useCurrentFormatElseDefault:''<br />
: (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.<br />
<br />
{{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.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu, a left click will ''send "sleep"'':<br />
insertPopup("activities to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"})<br />
<br />
-- alternatively, put commands as text (in [[ and ]] to use quotation marks inside)<br />
insertPopup("activities to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"})<br />
<br />
-- one can also provide helpful information<br />
<br />
-- todo: an example with rich-text in the tool-tips(s)<br />
<br />
</syntaxhighlight><br />
<br />
=Discord Functions=<br />
: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 [[Special:MyLanguage/Manual:Scripting#Discord_Rich_Presence|Discord scripting overview]].<br />
<br />
=Mud Client Media Protocol=<br />
:All GMCP functions to send sound and music events. For an overview on how all of these functions tie in together, see our [[Special:MyLanguage/Manual:Scripting#MUD_Client_Media_Protocol|MUD Client Media Protocol scripting overview]].<br />
<br />
==Playing Media, PR #7026==<br />
<br />
===Playing Media===<br />
<br />
Send '''Client.Media.Play''' GMCP events to play sound or music files.<br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! Default<br />
! style="text-align:left;"| Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;"| Yes<br />
| "name"<br />
| <file name><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
* May contain directory information (i.e. weather/lightning.wav).<br />
* Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.<br />
|- style="color: blue;"<br />
| style="text-align:center;"| Maybe<br />
| "url"<br />
| <url><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Resource location where the media file may be downloaded.<br />
* Only required if the file is to be downloaded remotely and a url was not set above with Client.Media.Default or Client.Media.Load.<br />
|-<br />
| style="text-align:center;"| No<br />
| "type"<br />
| "sound" or "music"<br />
| "sound"<br />
| style="text-align:left;"|<br />
* Identifies the type of media.<br />
|-<br />
| style="text-align:center;"| No<br />
| "tag"<br />
| <tag><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Helps categorize media.<br />
|-<br />
| style="text-align:center;"| No<br />
| "volume"<br />
| 1 to 100<br />
| 50<br />
| style="text-align:left;"|<br />
* Relative to the volume set on the player's client.<br />
|-<br />
| style="text-align:center;"| No<br />
| "fadein"<br />
|<msec><br />
|<br />
|<br />
*Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.<br />
*Start position: Start of media.<br />
*End position: Start of media plus the number of milliseconds (msec) specified.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
|"fadeout"<br />
|<msec><br />
|<br />
|<br />
*Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.<br />
*Start position: End of the media minus the number of milliseconds (msec) specified.<br />
*End position: End of the media.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;"| No<br />
| "start"<br />
| <msec><br />
| 0<br />
| style="text-align:left;"|<br />
* Begin play at the specified position in milliseconds.<br />
* 1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;"| No<br />
| "finish"<br />
| <msec><br />
| 0<br />
| style="text-align:left;"|<br />
* End play at the specified position in milliseconds.<br />
* 1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
|"loops"<br />
| -1, or >= 1<br />
|1<br />
| style="text-align:left;"|<br />
* Number of iterations that the media plays.<br />
* A value of -1 allows the sound or music to loop indefinitely.<br />
|-<br />
| style="text-align:center;" |No<br />
|"priority"<br />
|1 to 100<br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Halts the play of current or future played media files with a lower priority while this media plays.<br />
|-<br />
| style="text-align:center;" |No<br />
|"continue"<br />
| true or false<br />
|true<br />
| style="text-align:left;" |<br />
*Only valid for media files with a "type" of "music".<br />
*Continues playing matching new music files when true.<br />
*Restarts matching new music files when false.<br />
|-<br />
| style="text-align:center;" |No<br />
|"key"<br />
|<key><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
|}<br />
<br />
==== name====<br />
<br />
For example, to simply play the sound of a cow mooing already stored in the "media" folder:<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "cow.wav"<br />
}<br />
</syntaxhighlight><br />
<br />
Or some lightning stored in a "weather" sub-folder under the "media" folder.<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "weather/lightning.wav"<br />
}<br />
</syntaxhighlight><br />
<br />
The "name" parameter may be used for stopping media with the Client.Media.Stop GMCP event.<br />
<br />
====url====<br />
<br />
If you maintain your sound files on the Internet and don't set a default URL with Client.Media.Default, or preload them with Client.Media.Load, include the "url" parameter:<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "cow.wav",<br />
"url": "https://www.example.com/sounds/"<br />
}<br />
</syntaxhighlight><br />
<br />
====type: sound====<br />
<br />
Media files default to a "type" of "sound" when the "type" parameter is not specified, such as in the example above. It is good practice to specify the "type" parameter to best keep media organized within your implementation:<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "cow.wav",<br />
"type": "sound"<br />
}<br />
</syntaxhighlight><br />
<br />
The "type" parameter may be used for stopping matching media with the Client.Media.Stop GMCP event.<br />
<br />
====tag====<br />
<br />
To play the sound of a sword swooshing and categorized as "combat":<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "sword1.wav",<br />
"type": "sound",<br />
"tag": "combat"<br />
}<br />
</syntaxhighlight><br />
<br />
The "tag" parameter may be used for stopping matching media with the Client.Media.Stop GMCP event.<br />
<br />
====type: music====<br />
<br />
Add background music to your environment through use of the "music" value set upon the "type" parameter:<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "river.wav",<br />
"type": "music",<br />
"tag": "environment"<br />
}<br />
</syntaxhighlight><br />
<br />
The "type" parameter may be used for stopping matching media with the Client.Media.Stop GMCP event.<br />
<br />
====volume: 1 to 100====<br />
<br />
As the character draws nearer to or farther from the environmental feature, consider adjusting the "volume" parameter. Example values, followed by syntax examples:<br />
<br />
*Maximum: 100 (recommended to use rarely)<br />
*High: 75<br />
*Default: 50<br />
* Low: 25<br />
* Minimum: 1 (recommended to use rarely)<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "river.wav",<br />
"type": "music",<br />
"tag": "environment",<br />
"volume": 75<br />
}<br />
</syntaxhighlight><br />
<br />
Although using the integer type is recommended, Mudlet parses "volume" values of type string ("75") into integers (75) as needed.<br />
<br />
====fadein====<br />
<br />
Increase volume from the start of the media [start position, volume one] to the number in milliseconds specified with the "fadein" parameter [position start + milliseconds, volume specified with the "volume" parameter]. Example values, followed by syntax examples:<br />
<br />
*1000 milliseconds (1 second)<br />
*60000 milliseconds (1 minute)<br />
*0 milliseconds (no fade in)<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "monty_python.mp3",<br />
"type": "music",<br />
"volume": 100,<br />
"fadein": 1000<br />
}<br />
</syntaxhighlight><br />
+---------------------------+-----------------------+<br />
| Fade in 1000 milliseconds | Normal |<br />
+---------------------------+-----------------------+<br />
Volume 1|........::::::::::iiiiiiiii%%%%%%%%%%%%%%%%%%%%%%%%|Volume 100<br />
+---------------------------+-----------------------+<br />
Although using the integer type is recommended, Mudlet parses "fadein" values of type string ("1000") into integers (1000) as needed.<br />
<br />
==== fadeout====<br />
<br />
Decrease volume from a position in milliseconds subtracted from the duration of the media [position duration - milliseconds, volume specified with the "volume" parameter] to the end of the media [position duration, volume one]. Example values, followed by syntax examples:<br />
<br />
*1000 milliseconds (1 second)<br />
*60000 milliseconds (1 minute)<br />
*0 milliseconds (no fade out)<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "the_matrix.mp3",<br />
"type": "music",<br />
"volume": 50,<br />
"fadeout": 333<br />
}<br />
</syntaxhighlight><br />
+-----------------------+---------------------------+<br />
| Normal | Fade out 333 milliseconds |<br />
+-----------------------+---------------------------+<br />
Volume 50|%%%%%%%%%%%%%%%%%%%%%%%%iiiiiiiii::::::::::........|Volume 1<br />
+-----------------------+---------------------------+<br />
Although using the integer type is recommended, Mudlet parses "fadeout" values of type string ("333") into integers (333) as needed.<br />
<br />
==== start ====<br />
<br />
Start playing a media track at the number of milliseconds specified. Example values, followed by syntax examples:<br />
<br />
*1000 milliseconds (1 second)<br />
*60000 milliseconds (1 minute)<br />
*0 milliseconds (start from beginning)<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "mudlet_beatboxing.mp3",<br />
"type": "music",<br />
"volume": 75,<br />
"start": 1000<br />
}<br />
</syntaxhighlight><br />
<br />
Although using the integer type is recommended, Mudlet parses "start" values of type string ("100") into integers (100) as needed.<br />
<br />
==== finish ====<br />
<br />
Finish playing a media track at the number of milliseconds specified. Example values, followed by syntax examples:<br />
<br />
*1000 milliseconds (1 second)<br />
*60000 milliseconds (1 minute)<br />
*0 milliseconds (start from beginning)<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "mudlet_beatboxing.mp3",<br />
"type": "music",<br />
"volume": 75,<br />
"finish": 35000<br />
}<br />
</syntaxhighlight><br />
<br />
Although using the integer type is recommended, Mudlet parses "finish" values of type string ("100") into integers (100) as needed.<br />
<br />
==== loops: -1, 1 or more ====<br />
<br />
The "loops" parameter controls how many times the sound repeats and defaults to 1 if not specified. A value of -1 will loop the file indefinitely.<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "clock/hour_bell.wav",<br />
"type": "sound",<br />
"loops": 3<br />
}<br />
<br />
Client.Media.Play {<br />
"name": "underdark.mp3",<br />
"type": "music",<br />
"tag": "environment",<br />
"loops": -1<br />
}<br />
</syntaxhighlight><br />
<br />
Although using the integer type is recommended, Mudlet parses "loops" values of type string ("-1") into integers (-1) as needed.<br />
<br />
==== priority: 1 to 100 ====<br />
<br />
The "priority" parameter sets precedence for Client.Media.Play GMCP events that include a "priority" setting. The values for the "priority" parameter range between 1 and 100. Given that two Client.Media.Play GMCP events have the same priority, the media already playing will continue playing. In Mudlet, media without priority set is not included comparisons based on priority.<br />
<br />
A common place to find priority implemented is with combat. In the following example, imagine a combat scenario where some sounds of sword thrusts were interrupted by a successful blocking maneuver.<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "sword1.wav",<br />
"type": "sound",<br />
"tag": "combat",<br />
"loops": 3,<br />
"priority": 60<br />
}<br />
<br />
Client.Media.Play {<br />
"name": "block1.wav",<br />
"type": "sound",<br />
"tag": "combat",<br />
"priority": 70<br />
}<br />
</syntaxhighlight><br />
<br />
Although using the integer type is recommended, Mudlet parses "priority" values of type string ("25") into integers (25) as needed.<br />
<br />
The "priority" parameter may be used for stopping matching media with the Client.Media.Stop GMCP event.<br />
<br />
====continue: true or false (for music)====<br />
<br />
Typically sent with the "type" of "music" is the parameter "continue", which presents the following values:<br />
<br />
*true: continues music that is already playing if it is requested again through a new Client.Media.Play GMCP event<br />
*false: restarts music that is already playing if it is requested again through a new Client.Media.Play GMCP event<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "city.mp3",<br />
"type": "music",<br />
"tag": "environment",<br />
"continue": true<br />
}<br />
</syntaxhighlight><br />
<br />
If the "continue" parameter is not specified, behavior will default to ''true'' for music.<br />
<br />
Although using the boolean type is recommended, Mudlet parses "continue" values of type string ("true" and "false") into boolean (''true'' and ''false'') as needed, as not all game drivers support a boolean type.<br />
<br />
==== key====<br />
<br />
The "key" parameter enables media categorization, similar to the "tag" parameter, however it adds a feature of uniqueness that halts media currently playing with the same key, replacing it with the media that arrived from a new Client.Media.Play GMCP event. This update will only occur if the "name" or "url" associated with the currently playing media does not match the new media, while the key is identical.<br />
<br />
In the example below, consider that a player moves from a sewer area to a village. The "key" parameter is used to stop the previously playing ''sewer.mp3'' and start playing ''village.mp3'' within the second Client.Media.Play GMCP event. <br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "sewer.mp3",<br />
"type": "music",<br />
"tag": "environment",<br />
"loops": -1,<br />
"continue": true,<br />
"key": "area-music"<br />
}<br />
<br />
Client.Media.Play {<br />
"name": "village.mp3",<br />
"type": "music",<br />
"tag": "environment",<br />
"loops": -1,<br />
"continue": true,<br />
"key": "area-music"<br />
}<br />
</syntaxhighlight><br />
<br />
The "key" parameter may be used for stopping matching media with the Client.Media.Stop GMCP event.<br />
<br />
{{note}} Where music is bound to change, continue or stop as a player enters a new room, consider allowing for a slight pause of 1 heart beat or tick to send the Client.Media.Play or Client.Media.Stop GMCP events. This practice reduces the number of Client.Media.Play GMCP events sent when the player travels through several rooms quickly.<br />
<br />
==== randomization====<br />
<br />
Wildcards ''*'' (asterisk) and ''?'' (question mark) may be used within the name to randomize media file(s) selection.<br />
<br />
Given that media files underdark.wav, underdark.mp3 and underdark_dark_elven_moshpit.mp3 were all present in the media/environment directory under the current game profile, the following Client.Media.Play GMCP event would randomly choose one of those files to play using the ''*'' wildcard.<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "underdark*",<br />
"type": "music",<br />
"tag": "environment",<br />
"loops": -1,<br />
"continue": false<br />
}<br />
</syntaxhighlight><br />
<br />
If media files sword1.wav, sword2.wav and sword3.wav were all present in the media/combat directory under the current game profile, the following Client.Media.Play GMCP event would randomly choose one of those files to play per each loop using the ''?'' wildcard.<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Play {<br />
"name": "combat/sword?.wav",<br />
"type": "sound",<br />
"tag": "combat",<br />
"loops": 3<br />
}<br />
</syntaxhighlight><br />
<br />
==Stopping Media, PR #7026==<br />
<br />
=== Stopping Media ===<br />
<br />
Send '''Client.Media.Stop''' GMCP events to stop sound or music media.<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
! style="text-align:left;" |Purpose<br />
|-<br />
| style="text-align:center;" | No<br />
| "name"<br />
|<file name><br />
| style="text-align:left;" |<br />
*Stops playing media by name matching the value specified.<br />
|-<br />
| style="text-align:center;" | No<br />
|"type"<br />
|"sound" or "music"<br />
| style="text-align:left;" | <br />
*Stops playing media by type matching the value specified.<br />
|-<br />
| style="text-align:center;" |No<br />
| "tag"<br />
|<tag><br />
| style="text-align:left;" |<br />
*Stops playing media by tag matching the value specified.<br />
|-<br />
| style="text-align:center;" |No<br />
|"priority"<br />
|1 to 100<br />
| style="text-align:left;" |<br />
*Stops playing media with priority less than or equal to the value.<br />
|-<br />
| style="text-align:center;" |No<br />
|"key"<br />
|<key><br />
| style="text-align:left;" | <br />
*Stops playing media by key matching the value specified.<br />
|-<br />
| style="text-align:center;"| No<br />
| "fadeaway"<br />
| true or false<br />
| style="text-align:left;" |<br />
* Decrease volume from the current position for a given duration, then stops the track.<br />
* Given duration is the lesser of the remaining track duration or the fadeout specified in Client.Media.Play.<br />
* If fadeout was not specified in Client.Media.Play, then the optional fadeout parameter from Client.Media.Stop or a default of 5000 milliseconds will be applied.<br />
|-<br />
| style="text-align:center;"| No<br />
| "fadeout"<br />
| <br />
| style="text-align:left;" |<br />
* Default duration in milliseconds to decrease volume to the end of the track.<br />
* Only used if fadeout was not defined in Client.Media.Play.<br />
|-<br />
|}<br />
<br />
====all====<br />
<br />
Send the Client.Media.Stop GMCP event with no parameters to stop all playing media within a given game profile.<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Stop {}<br />
</syntaxhighlight><br />
<br />
====parameters====<br />
<br />
Send any combination of the name, type, tag, priority or sound parameters and valid corresponding values to stop playing media that matches ''all'' combinations of the parameters.<br />
<br />
Stop the rain.<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Stop {<br />
"name": "rain.wav"<br />
}<br />
</syntaxhighlight><br />
<br />
Stop all media using the "type" of "sound".<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Stop {<br />
"type": "sound"<br />
}<br />
</syntaxhighlight><br />
<br />
Stop all media categorized with the "tag" of "combat" ''and'' that has a "priority" less than or equal to 50.<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Stop {<br />
"tag": "combat",<br />
"priority": 50<br />
}<br />
</syntaxhighlight><br />
<br />
Stop all media categorized with the "key" of "area-music".<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Stop {<br />
"key": "area-music"<br />
}<br />
</syntaxhighlight><br />
<br />
Decrease volume for 5 seconds (or the fadeout parameter defined in Client.Media.Play) and then stop all playing music files for this profile<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Stop {<br />
"fadeaway": true<br />
}<br />
</syntaxhighlight><br />
<br />
Decrease volume for 10 seconds all media categorized with the "key" of "area-music" and then stop the music<br />
<br />
<syntaxhighlight lang="json"><br />
Client.Media.Stop {<br />
"key": "area-music",<br />
"fadeaway": true,<br />
"fadeout": 10000<br />
}<br />
</syntaxhighlight><br />
<br />
=Supported Protocols=<br />
<br />
Mudlet supports CHARSET, NEW-ENVIRON, MNES, MTTS, GMCP, MSSP, MSP, ATCP, Aardwolfs 102, MSDP, and the MXP Protocol.<br />
<br />
CHARSET, NEW-ENVIRON, MTTS, MXP, MSSP, MSP, GMCP and 102 are enabled by default, MSDP and MNES can be enabled in settings.<br />
<br />
==NEW-ENVIRON, PR #7058==<br />
To enhance the player experience through sharing more client-supported details, the Telnet New-Environ Option may be used to transfer client environment variables from Mudlet to game servers. Sharing supporting information on information such as encoding, terminal emulation, and accessibility options aims to improve initial player setup and increase the retention rate for new gaming community members.<br />
<br />
===NEW-ENVIRON in Mudlet===<br />
Mudlet supports two methods of information exchange via NEW-ENVIRON, the first via [https://datatracker.ietf.org/doc/html/rfc1572 RFC 1572]: '''Telnet New-Environ Option''' (on by default), and the second is [https://tintin.mudhalla.net/protocols/mnes/ MNES]: '''Mud New-Environ Standard''' (off by default), which shares a standardized set of client information across multiple clients. <br />
<br />
====Client Environment Variable Updates====<br />
Mudlet provides a user-friendly interface for managing environmental variables through its Settings menu. For certain environmental variables, manual selections made in the Settings menus can dynamically notify servers that have expressed interest in the client's environmental variables through the negotiation of the NEW-ENVIRON option. For instance, when a Mudlet user updates the data encoding for a server profile by navigating to Settings, General, and choosing a specific data encoding from the drop-down menu, this information becomes available for transmission via both the RFC (default) and MNES (requires user enabling) options. <br />
<br />
==== Available Client Environment Variables [https://datatracker.ietf.org/doc/html/rfc1572 RFC 1572] ====<br />
Two types of variables are used per RFC 152, well-known variables defines with VAR (0) and for less common variables, USERVAR (3). Some information requires a user to OPT-IN to share it with the game. Some client variables updates may be reported ad-hoc with an INFO (2) message. If there is no value for a defined variable, a VAL (1) will be sent without a value following it.<br />
{| class="wikitable"<br />
! Type<br />
! Variable<br />
! Example Values<br />
!Mudlet Default<br />
!OPT-IN<br />
!INFO<br />
! Purpose<br />
!Available<br />
|-<br />
| VAR<br />
| '''SYSTEMTYPE'''<br />
| MACOS, WIN64, WIN32, BSD4, CYGWIN, FREEBSD, HURD, NETBSD, OPENBSD, LINUX, UNIX<br />
|<br />
|Yes<br />
|<br />
| Client runs within the listed operating system.<br />
|Future<br />
|-<br />
| VAR<br />
| '''USER'''<br />
| tamarindo<br />
|<br />
|Yes<br />
|<br />
| Character name defined in logon dialogue.<br />
|Future<br />
|-<br />
| USERVAR<br />
| '''256_COLORS'''<br />
| 1, 0<br />
|1<br />
|<br />
|<br />
| Client supports all 256 color codes. 1 = Yes/True/ACK.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''ANSI'''<br />
| 1, 0<br />
|1<br />
|<br />
|<br />
| Client supports all common ANSI color codes. 1 = Yes/True/ACK.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''CHARSET'''<br />
| UTF-8, ASCII<br />
|<br />
|<br />
|Yes<br />
| Encoding set in the client<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''CLIENT_NAME'''<br />
| MUDLET<br />
|MUDLET<br />
|<br />
|<br />
| Name of the client.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''CLIENT_VERSION'''<br />
| 4/18, 4/17/2-DEV<br />
|<br />
|<br />
|<br />
| Version of the client.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''FONT'''<br />
| Bitstream Vera Sans Mono<br />
|<br />
|Yes<br />
|Yes<br />
| Font used in the client.<br />
|Future<br />
|-<br />
| USERVAR<br />
| '''FONT_SIZE'''<br />
| 14<br />
|<br />
|Yes<br />
|Yes<br />
| Font size used in the client.<br />
|Future<br />
|-<br />
| USERVAR<br />
| '''LANGUAGE'''<br />
| en_US<br />
|<br />
|Yes<br />
|Yes<br />
| Client is using this language code and country variant.<br />
|Future<br />
|-<br />
| USERVAR<br />
| '''MTTS'''<br />
| 2349<br />
|<br />
|<br />
|Yes<br />
| Bitvector defined in the Mud Terminal Type Standard ([https://tintin.mudhalla.net/protocols/mtts/ MTTS]).<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''OSC_COLOR_PALETTE'''<br />
| 1, 0<br />
|<br />
|<br />
|<br />
| Client supports OSC and the OSC color palette. 1 = Yes/True/ACK.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''SCREEN_READER'''<br />
| 1, 0<br />
|0<br />
|Yes<br />
|Yes<br />
| Client is using a screen reader. 1 = Yes/True/ACK.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''TERMINAL_TYPE'''<br />
| ANSI-TRUECOLOR, ANSI-256COLOR, ANSI, XTERM, VT100, DUMB<br />
|ANSI-TRUECOLOR<br />
|<br />
|<br />
| Terminal type of the client<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''TLS'''<br />
| 1, 0<br />
|<br />
|<br />
|<br />
| Client supports Transport Layer Security for data encryption. 1 = Yes/True/ACK.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''TRUECOLOR'''<br />
| 1, 0<br />
|<br />
|<br />
|<br />
| Client supports truecolor codes using semicolon notation. 1 = Yes/True/ACK.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''UTF-8'''<br />
| 1, 0<br />
|<br />
|<br />
|Yes<br />
| Client is using UTF-8 character encoding. 1 = Yes/True/ACK.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''VT100'''<br />
| 1, 0<br />
|0<br />
|<br />
|<br />
| Client supports all common VT100 codes. 1 = Yes/True/ACK. This is not applicable for Mudlet and while defined, is not used.<br />
|4.18<br />
|-<br />
| USERVAR<br />
| '''WORD_WRAP'''<br />
| 100<br />
|<br />
|<br />
|Yes<br />
| Client wraps text at this value<br />
|4.18<br />
|-<br />
|}<br />
<br />
====Negotiating NEW-ENVIRON====<br />
Negotiating the NEW-ENVIRON Telnet option empowers game servers to request one, multiple, or all client environment variables configured within Mudlet. The process unfolds with the game server sending a Telopt DO NEW-ENVIRON (39), prompting Mudlet to respond with a WILL NEW-ENVIRON (39). Subsequently, the game server can send SB NEW-ENVIRON (39) SEND to receive all available environment variables. Mudlet responds with SB NEW-ENVIRON (39) IS (0) < VAR (0) | USERVAR (3) > "<variable>" [VAL (1)] ["<value>"] [ .. [ VAR (0) | USERVAR (3) ] "<variable>" VAL (1) "<value>"] containing the list of environmental variables.<br />
<br />
Once an environmental variable is transmitted to a server within the ongoing connection, Mudlet replies with SB NEW-ENVIRON (39) INFO (2) < VAR (0) | USERVAR (3) > "<variable>" [VAL (1)] ["<value>"] messages for select variables. Importantly, no reply from the server is required in this context. If there is a need to specify a particular list of requested environmental variables to Mudlet, the format SB NEW-ENVIRON (39) SEND < VAR (0) | USERVAR (3) > "<variable>" [ .. < VAR (0) | USERVAR (3) > "<variable>" ] can be employed.<br />
<br />
Success example #1 (one environmental variable):<br />
{| class="wikitable"<br />
! Server<br />
! Mudlet<br />
|-<br />
| IAC DO NEW-ENVIRON (39) IAC SE<br />
| IAC WILL NEW-ENVIRON (39) IAC SE<br />
|-<br />
| IAC SB NEW-ENVIRON (39) SEND (1) USERVAR (3) ''CHARSET'' IAC SE<br />
| IAC SB NEW-ENVIRON (39) IS (0) USERVAR (3) ''CHARSET'' VAL (1) ''UTF-8'' IAC SE<br />
|-<br />
|}<br />
<br />
Success example #2 (all environmental variables):<br />
{| class="wikitable"<br />
! Server<br />
! Mudlet<br />
|-<br />
| IAC DO NEW-ENVIRON (39) IAC SE<br />
| IAC WILL NEW-ENVIRON (39) IAC SE<br />
|-<br />
| IAC SB NEW-ENVIRON (39) SEND (1) IAC SE<br />
| IAC SB NEW-ENVIRON (39) IS (0) VAR (0) ''SYSTEMTYPE'' VAL (1) ''MACOS'' VAR (0) ''USER'' VAL (1) ''tamarindo'' USERVAR (3) ''256_COLORS'' VAL (1) ''1'' USERVAR (3) ''ANSI'' VAL (1) ''1'' USERVAR (3) ''CHARSET'' VAL (1) ''UTF-8'' USERVAR (3) ''CLIENT_NAME'' VAL (1) ''MUDLET'' USERVAR (3) ''CLIENT_VERSION'' VAL (1) ''4/17/2-DEV'' USERVAR (3) ''FONT'' VAL (1) ''Bitstream Vera Sans Mono'' USERVAR (3) ''FONT_SIZE'' VAL (1) ''14'' USERVAR (3) ''LANGUAGE'' VAL (1) ''en_US'' USERVAR (3) USERVAR (3) ''MTTS'' VAL (1) ''2349'' USERVAR (3) ''OSC_COLOR_PALETTE'' VAL (1) ''1'' USERVAR (3) ''SCREEN_READER'' VAL (1) USERVAR (3) ''TERMINAL_TYPE'' VAL (1) ''ANSI-TRUECOLOR'' USERVAR (3) ''TLS'' VAL (1) ''1'' USERVAR (3) ''TRUECOLOR'' VAL (1) ''1'' USERVAR (3) ''UTF-8'' VAL (1) ''1'' USERVAR (3) ''VT100'' VAL (1) ''0'' USERVAR (3) ''WORD_WRAP'' VAL (1) ''100'' IAC SE<br />
|-<br />
|<br />
|''[ As updates occur in the client the following are possible... ]''<br />
|-<br />
|<br />
|IAC SB NEW-ENVIRON (39) INFO (2) USERVAR (3) ''CHARSET'' VAL (1) ''UTF-8'' IAC SE<br />
IAC SB NEW-ENVIRON (39) INFO (2) USERVAR (3) ''FONT'' VAL (1) ''Bitstream Vera Sans Mono'' IAC SE<br />
<br />
IAC SB NEW-ENVIRON (39) INFO (2) USERVAR (3) ''FONT_SIZE'' VAL (1) ''14'' IAC SE<br />
<br />
IAC SB NEW-ENVIRON (39) INFO (2) USERVAR (3) ''LANGUAGE'' VAL (1) ''en_US'' IAC SE<br />
<br />
IAC SB NEW-ENVIRON (39) INFO (2) USERVAR (3) ''MTTS'' VAL (1) ''2349'' IAC SE<br />
<br />
IAC SB NEW-ENVIRON (39) INFO (2) USERVAR (3) ''SCREEN_READER'' VAL (1) IAC SE<br />
<br />
IAC SB NEW-ENVIRON (39) INFO (2) USERVAR (3) ''UTF-8'' VAL (1) ''1'' IAC SE<br />
<br />
IAC SB NEW-ENVIRON (39) INFO (2) USERVAR (3) ''WORD_WRAP'' VAL (1) ''100'' IAC SE<br />
|-<br />
|}<br />
<br />
If a Mudlet user does not want to negotiate environmental variables, they may choose the Settings, Special Options menu item in Mudlet and enable "Force NEW_ENVIRON negotiation off". The following is an example of an attempted negotiation where "Force NEW-ENVIRON negotiation off" is enabled.<br />
{| class="wikitable"<br />
! Server<br />
! Mudlet<br />
|-<br />
| IAC DO NEW-ENVIRON (39) IAC SE<br />
| IAC WONT NEW-ENVIRON (39) IAC SE<br />
|-<br />
|}<br />
<br />
NEW-ENVIRON negotiation is available in Mudlet 4.18+.<br />
<br />
== MNES, PR #7058 ==<br />
The Mud New-Environment Standard is an alternative way to share client-supported details between Mudlet to game servers.<br />
<br />
==== Activating MNES ====<br />
If your game supports MNES, instruct users to toggle on the `Enable MNES` menu option on the General tab in Mudlet.<br />
<br />
[[File:Screenshot_2024-01-01_at_1.41.06_PM.png|alt=Enable MNES is found on the Game protocols section of the General tab of Settings|614x614px]]&nbsp;<br />
<br />
==== Mud New-Environ Standard Client Environment Variables [https://tintin.mudhalla.net/protocols/mnes/ MNES] ====<br />
MNES leverages VAR (0) to transfer up to five client environment variables. Some client variables updates may be reported ad-hoc with an INFO message. If there is no value for a defined variable, a VAL (1) will be sent without a value following it.<br />
{| class="wikitable"<br />
! Type<br />
! Variable<br />
! Example Values<br />
!Mudlet Default<br />
!INFO<br />
! Purpose<br />
|-<br />
| VAR<br />
| '''CHARSET'''<br />
| UTF-8, ASCII<br />
|<br />
|Yes<br />
| Encoding set in the client<br />
|-<br />
| VAR<br />
| '''CLIENT_NAME'''<br />
| MUDLET<br />
|MUDLET<br />
|<br />
| Name of the client.<br />
|-<br />
| VAR<br />
| '''CLIENT_VERSION'''<br />
| 4/18, 4/17/2-DEV<br />
|<br />
|<br />
| Version of the client.<br />
|-<br />
| VAR<br />
| '''MTTS'''<br />
| 2349<br />
|<br />
|Yes<br />
| Bitvector defined in the Mud Terminal Type Standard ([https://tintin.mudhalla.net/protocols/mtts/ MTTS]).<br />
|-<br />
| VAR<br />
| '''TERMINAL_TYPE'''<br />
| ANSI-TRUECOLOR, ANSI-256COLOR, ANSI, XTERM, VT100, DUMB<br />
|ANSI-TRUECOLOR<br />
|<br />
| Terminal type of the client<br />
|-<br />
|}<br />
<br />
==== Negotiating MNES ====<br />
The primary differences between MNES and the out-of-the-box RFC 152 NEW-ENVIRON implementation is that MNES sends no more than 5 client environment variables ("IPADDRESS" will not be implemented in Mudlet), it uses a VAR (0) for the SEND (1), IS (0), and INFO (2) messages, and returns a multiple client variable response in multiple IS (0) messages.<br />
{| class="wikitable"<br />
! Server<br />
! Mudlet<br />
|-<br />
| IAC DO NEW-ENVIRON (39) IAC SE<br />
| IAC WILL NEW-ENVIRON (39) IAC SE<br />
|-<br />
| IAC SB NEW-ENVIRON (39) SEND IAC SE<br />
| IAC SB NEW-ENVIRON (39) IS (0) VAR (0) ''CHARSET'' VAL (1) ''UTF-8'' IAC SE<br />
IAC SB NEW-ENVIRON (39) IS (0) VAR (0) ''CLIENT_NAME'' VAL (1) ''MUDLET'' IAC SE<br />
<br />
IAC SB NEW-ENVIRON (39) IS (0) VAR (0) ''CLIENT_VERSION'' VAL (1) ''4/17/2-DEV'' IAC SE<br />
<br />
IAC SB NEW-ENVIRON (39) IS (0) VAR (0) ''MTTS'' VAL (1) ''2349'' IAC SE<br />
<br />
IAC SB NEW-ENVIRON (39) IS (0) VAR (0) ''TERMINAL_TYPE'' VAL (1) ''ANSI-TRUECOLOR'' IAC SE<br />
|-<br />
|<br />
|''[ As updates occur in the client the following are possible... ]''<br />
|-<br />
|<br />
|IAC SB NEW-ENVIRON (39) INFO (2) VAR (0) ''CHARSET'' VAL (1) ''ASCII'' IAC SE<br />
IAC SB NEW-ENVIRON (39) INFO (2) VAR (0) ''MTTS'' VAL (1) ''2345'' IAC SE<br />
|-<br />
|}<br />
<br />
MNES negotiation is available in Mudlet 4.18+.<br />
<br />
==MTTS, PR #7036==<br />
MUD servers frequently seek information about the capabilities of a MUD Client. Despite the availability of various methods, achieving consistency and reliability in this endeavor has proven challenging. The Mud Terminal Type Standard ([https://tintin.mudhalla.net/protocols/mtts/ MTTS]) aims to alleviate these issues by introducing a transparent and straightforward standard for MUD Clients to communicate their terminal capabilities. This standard builds upon and formalizes [https://datatracker.ietf.org/doc/html/rfc1091 RFC 1091], which outlines the Telnet Terminal-Type Option.<br />
<br />
===MTTS in Mudlet===<br />
By incorporating the Mud Terminal-Type Standard (MTTS), Mudlet will communicate with interested servers that it possesses the following capabilities: <br />
<br />
* '''Support for ANSI Color Codes:''' The client supports all common ANSI color codes.<br />
* '''UTF-8 Character Encoding:''' The client utilizes UTF-8 character encoding.<br />
* '''Support for 256 Color Codes:''' Mudlet is equipped to handle all 256 color codes.<br />
* '''OSC Color Palette:''' Mudlet acknowledges support for the OSC color palette.<br />
* '''Screen Reader Support:''' Mudlet offers support for screen readers, with opt-in functionality (not advertised by default).<br />
* '''Truecolor Codes:''' Mudlet supports truecolor codes using semicolon notation.<br />
* '''Mud New Environment Standard (MNES) Support:''' The client adheres to the Mud New Environment Standard for information exchange.<br />
* '''TLS Encryption:''' The client supports Transport Layer Security for data encryption.<br />
<br />
==== Screen Reader Opt-In ====<br />
Users can find on the Accessibility tab under the Settings menu a checkbox identified as "Advertise screen reader use via protocols supporting this notice" which when checked will notify interested game servers. This information may be used to optimize the gaming experience.<br />
<br />
[[File:Screenshot_2024-01-01_at_2.35.07_PM.png|alt=Image displaying the Advertise screen reader checkbox|619x619px]]<br />
<br />
==== Available MTTS Information ====<br />
Through a Telnet TERMINAL-TYPE Option negotiation, Mudlet transfers a bitvector to game servers, (i.e., <code>2349</code>) for processing. A bitvector, also known as a bitmap, is a data structure that represents a fixed-size sequence of binary digits or bits. In a bitvector, each bit corresponds to a specific position or index in the sequence, and its value can be either 0 or 1. The MTTS bitvector represents is a set of flags and boolean values, where each bit can represent the state of a particular boolean condition or flag. For example, if the third bit is set to <code>1</code>, it indicates that the client is using UTF-8 character encoding. A <code>0</code> indicator would indicate that UTF-8 was not supported.<br />
{| class="wikitable"<br />
|+MTTS Bitvector<br />
!Bit<br />
!Property<br />
!Meaning<br />
|-<br />
|1<br />
|ANSI<br />
|Client supports all common ANSI color codes.<br />
|-<br />
|2<br />
|VT100<br />
|Client supports all common VT100 codes.<br />
|-<br />
|4<br />
|UTF-8<br />
|Client is using UTF-8 character encoding.<br />
|-<br />
|8<br />
|256 COLORS<br />
|Client supports all 256 color codes.<br />
|-<br />
|16<br />
|MOUSE TRACKING<br />
|Client supports xterm mouse tracking.<br />
|-<br />
|32<br />
|OSC COLOR PALETTE<br />
|Client supports OSC and the OSC color palette.<br />
|-<br />
|64<br />
|SCREEN READER<br />
|Client is using a screen reader.<br />
|-<br />
|128<br />
|PROXY<br />
|Client is a proxy allowing different users to connect from the same IP address.<br />
|-<br />
|256<br />
|TRUECOLOR<br />
|Client supports truecolor codes using semicolon notation.<br />
|-<br />
|512<br />
|MNES<br />
|Client supports the Mud New Environment Standard for information exchange.<br />
|-<br />
|1024<br />
|MSLP<br />
|Client supports the Mud Server Link Protocol for clickable link handling.<br />
|-<br />
|2048<br />
|TLS<br />
|Client supports Transport Layer Security for data encryption.<br />
|}<br />
<br />
====Negotiating MTTS====<br />
Per the MTTS guidance, game servers should initiate up to 4 TTYPE requests to complete the TTYPE cycling routine within a given connection. If the connection is reset, negotiate TTYPE again. Reference the [https://tintin.mudhalla.net/protocols/mtts/ MTTS website] for more information.<br />
{| class="wikitable"<br />
! Server<br />
! Mudlet<br />
|-<br />
| IAC DO TTYPE (24) IAC SE<br />
| IAC WILL TTYPE (24) IAC SE<br />
|-<br />
| IAC SB TTYPE (24) SEND (1) IAC SE<br />
| IAC SB TTYPE (24) IS (0) ''MUDLET-4/18'' IAC SE<br />
|-<br />
| IAC SB TTYPE (24) SEND (1) IAC SE<br />
| IAC SB TTYPE (24) IS (0) ''ANSI-TRUECOLOR'' IAC SE<br />
|-<br />
|IAC SB TTYPE (24) SEND (1) IAC SE<br />
|IAC SB TTYPE (24) IS (0) ''MTTS 2349'' IAC SE<br />
|-<br />
|IAC SB TTYPE (24) SEND (1) IAC SE<br />
|IAC SB TTYPE (24) IS (0) ''MTTS 2349'' IAC SE<br />
|-<br />
|}<br />
<br />
If a Mudlet user does not want to enable Mud Terminal Type Standard, they may choose the Settings, General menu item in Mudlet and toggle off the "Enable MTTS" checkbox.<br />
<br />
MTTS is available in Mudlet 4.18+.<br />
<br />
=Events=<br />
:New or revised events that Mudlet can raise to inform a profile about changes. See [[Manual:Event_Engine#Mudlet-raised_events|Mudlet-raised events]] for the existing ones.<br />
<br />
===sysMapAreaChanged, PR #6615===<br />
Raised when the area being viewed in the mapper is changed, either by the player-room being set to a new area or the user selecting a different area in the area selection combo-box in the mapper controls area. Returns two additional arguments being the areaID of the area being switched to and then the one for the area that is being left.<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6615<br />
<br />
===sysMapWindowMousePressEvent, PR #6962===<br />
Raised when the mouse is left-clicked on the mapper window.<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6962<br />
<br />
===sysWindowOverflowEvent, PR #6872===<br />
Raised when the content in a mini-console/user window that has been set to be '''non-scrolling''' (see: [[#enableScrolling|enableScrolling(...)]] and [[#disableScrolling|disableScrolling(...)]]) overflows - i.e. fills the visible window and overflows off the bottom. Returns two additional arguments being the window's name as a string and the number of lines that have gone past that which can be shown on the current size of the window.<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6872 and https://github.com/Mudlet/Mudlet/pull/6848 for the Lua API functions (that also need documenting).</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:String_Functions&diff=20878Manual:String Functions2024-01-23T20:25:36Z<p>Demonnic: /* f */</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Mudlet API documentation for functions used to manipulate strings.}}<br />
= String Functions =<br />
A collection of functions used to manipulate strings.<br />
==addWordToDictionary==<br />
;addWordToDictionary(word)<br />
:Adds the given word to the custom profile or shared dictionary (whichever is selected in preferences).<br />
<br />
: Returns true on success (the word was actually ''added'' to the dictionary by this call) and nil+msg on error - including if the word was already there - this is so that if you have other scripts that you wish to run when a word was added you can make their execution conditional on success here.<br />
<br />
:See also: [[#removeWordFromDictionary|removeWordFromDictionary()]]<br />
<br />
;Parameters<br />
* ''word:'' custom word to add to the dictionary.<br />
<br />
{{MudletVersion|3.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addWordToDictionary("Darkwind")<br />
addWordToDictionary("黑暗的风")<br />
addWordToDictionary("норм")<br />
</syntaxhighlight><br />
<br />
;Example - function making use of return value:<br />
<syntaxhighlight lang="lua"><br />
function rememberPlayerName(name)<br />
if addWordToDictionary(name) then<br />
echo("Added '" .. name .. "' to dictionary...\n")<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==cecho2string==<br />
; plainText = cecho2string(formattedText)<br />
<br />
:Strips the text formatting from the string passed in, leaving behind only the text.<br />
<br />
;See also: [[Manual:Lua_Functions#ansi2string|ansi2string()]], [[Manual:Lua_Functions#hecho2string|hecho2string()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formattedText:''<br />
: The string you want to strip the formatting codes from<br />
<br />
;Returns <br />
* The string with the formatting codes stripped out.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local exampleString = "<red>Formatted <b>string</b>"<br />
local plainText = cecho2string(exampleString)<br />
-- "Formatted string"<br />
</syntaxhighlight><br />
<br />
==decho2string==<br />
; plainText = decho2string(formattedText)<br />
<br />
:Strips the text formatting from the string passed in, leaving behind only the text.<br />
<br />
;See also: [[Manual:Lua_Functions#ansi2string|ansi2string()]], [[Manual:Lua_Functions#cecho2string|cecho2string()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formattedText:''<br />
: The string you want to strip the formatting codes from<br />
<br />
;Returns <br />
* The string with the formatting codes stripped out.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local exampleString = "<255,0,0>Formatted <b>string</b>"<br />
local plainText = decho2string(exampleString)<br />
-- "Formatted string"<br />
</syntaxhighlight><br />
<br />
==f==<br />
; formattedString = f(str)<br />
: Allows you to combine variables and functions into text (string interpolation) using <code>{}</code>.<br />
<br />
; Parameters<br />
* ''str:''<br />
: The string to perform interpolation against.<br />
<br />
{{MudletVersion|4.11}}<br />
{{note}} Using f is slower than using concatenation with the '..' operator by a fair bit, due to the way it has to gather scope for supporting local variables. For aliases or single calls this isn't so bad, but if you're looping a large table and building a string then f's slowness will really start to show and bring performance down.<br />
; Example:<br />
<br />
<syntaxhighlight lang=lua><br />
-- old way:<br />
cecho("\nHello, "..matches[2]..", how is it going?")<br />
<br />
-- new way:<br />
cecho(f("\nHello {matches[2]}, how is it going?"))<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang=lua><br />
testResult = "successful"<br />
-- old way:<br />
echo("The test was "..testResult.."\n")<br />
-- with f:<br />
echo(f("The test was {testResult}\n"))<br />
-- echoes "The test was successful\n"<br />
<br />
local testResult = "a failure"<br />
echo(f("The test was {testResult}\n"))<br />
-- echoes "The test was a failure\n" as it sees the local scope over global.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang=lua><br />
-- You can also execute simple expressions<br />
echo(f("2 + 2 = {2 + 2}\n"))<br />
-- echoes "2 + 2 = 4\n"<br />
<br />
-- Or more complicated ones<br />
local function testFunc(item)<br />
return item:title()<br />
end<br />
<br />
echo(f("You should properly capitalize names, such as {testFunc('marilyn')}\n"))<br />
-- echoes "You should properly capitalize names, such as Marilyn\n"<br />
<br />
echo(f("You should properly capitalize names, such as {string.title('robert')}\n")<br />
-- same thing, but uses string.title directly and Robert instead of Marilyn<br />
</syntaxhighlight><br />
<br />
<br />
'''Caution!'''<br />
When using within closures, might not resolve variables correctly if they go out of a scope when closure is called.<br />
<syntaxhighlight lang=lua><br />
function formatter2000()<br />
local upvalue = "2000"<br />
local formatter = function() <br />
echo(f("Let's evaluate: {upvalue}\n"))<br />
end<br />
formatter() -- here evaulation inside f function will work<br />
return formatter<br />
end<br />
<br />
formatter2000()() -- here evaluation inside f function will return nil<br />
-- result<br />
-- Let's evaluate: 2000<br />
-- Let's evaulate: nil<br />
</syntaxhighlight><br />
<br />
You can work around this by doing the following<br />
<syntaxhighlight lang=lua><br />
function formatter2000()<br />
local upvalue = "2000"<br />
local formatter = function()<br />
local upvalue = upvalue -- this keeps upvalue in scope for the function later<br />
echo(f("Let's evaluate: {upvalue}\n"))<br />
end<br />
formatter() -- here evaulation inside f function will work<br />
return formatter<br />
end<br />
<br />
formatter2000()() -- here evaluation inside f function will return 2000 once again<br />
<br />
-- result<br />
-- Let's evaluate: 2000<br />
-- Let's evaulate: 2000<br />
</syntaxhighlight><br />
<br />
==getDictionaryWordList==<br />
;getDictionaryWordList()<br />
:Returns the profile or shared custom dictionary word list (whichever is selected in preferences) - that is, words added via right-click "add word to dictionary" or [[#addWordToDictionary|addWordToDictionary()]].<br />
<br />
: Returns an indexed table of words.<br />
<br />
{{MudletVersion|3.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getDictionaryWordList())<br />
</syntaxhighlight><br />
<br />
==hecho2string==<br />
; plainText = hecho2string(formattedText)<br />
<br />
:Strips the text formatting from the string passed in, leaving behind only the text.<br />
<br />
;See also: [[Manual:Lua_Functions#ansi2string|ansi2string()]], [[Manual:Lua_Functions#decho2string|decho2string()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formattedText:''<br />
: The string you want to strip the formatting codes from<br />
<br />
;Returns <br />
* The string with the formatting codes stripped out.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local exampleString = "#ff0000Formatted #bstring#/b"<br />
local plainText = cecho2string(exampleString)<br />
-- "Formatted string"<br />
</syntaxhighlight><br />
<br />
==removeWordFromDictionary==<br />
;removeWordFromDictionary(word)<br />
:Removed the given word to the custom profile or shared dictionary (whichever is selected in preferences).<br />
<br />
: Returns true on success (if the word was present and removed by this call) and nil+msg on error.<br />
<br />
:See also: [[#addWordToDictionary|addWordToDictionary()]]<br />
<br />
;Parameters<br />
* ''word:'' custom word to remove from the dictionary.<br />
<br />
{{MudletVersion|3.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
removeWordFromDictionary("Darkwind")<br />
removeWordFromDictionary("黑暗的风")<br />
removeWordFromDictionary("норм")<br />
</syntaxhighlight><br />
<br />
==spellCheckWord==<br />
;spellCheckWord(word, [customDictionary])<br />
:Spellchecks the given word against the custom or the system dictionary.<br />
<br />
: Returns true if the word is spelled correctly or false if it's not, and nil+msg on error.<br />
<br />
:See also: [[#addWordToDictionary|addWordToDictionary()]], [[#removeWordFromDictionary|removeWordFromDictionary()]], [[#spellSuggestWord|spellSuggestWord()]]<br />
<br />
;Parameters<br />
* ''word'': word to spellcheck.<br />
* ''customDictionary'' (optional): dictionary to use. If true, the profile or shared dictionary will be used (depending on your settings). If omitted or false, the system dictionary (the language you have selected in settings) will be used.<br />
<br />
{{MudletVersion|3.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- spellcheck against the language dictionary<br />
if spellCheckWord("run") then<br />
echo("'run' is spelled ok!\n")<br />
end<br />
<br />
-- spellcheck against the custom 'add word to dictionary'<br />
if spellCheckWord("Darkwind", true) then<br />
echo("'Darkwind' is spelled OK!\n")<br />
end<br />
</syntaxhighlight><br />
<br />
==spellSuggestWord==<br />
;spellSuggestWord(word, [customDictionary])<br />
:Suggests similar words for the given word.<br />
<br />
: Returns a table of suggestions or nil+msg on error.<br />
<br />
:See also: [[#spellCheckWord|spellCheckWord()]]<br />
<br />
;Parameters<br />
* ''word'': word to give suggestions on.<br />
* ''customDictionary'' (optional): dictionary to use. If true, the profile or shared dictionary will be used (depending on your settings). If omitted or false, the system dictionary (the language you have selected in settings) will be used.<br />
<br />
{{MudletVersion|3.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(spellSuggestWord("Darkwind"))<br />
</syntaxhighlight><br />
<br />
==string.byte, utf8.byte==<br />
;string.byte(string [, i [, j]]) or utf8.byte(string [, i [, j]])<br />
;<nowiki>mystring:byte([, i [, j]])</nowiki><br />
: Returns the internal numerical codes of the characters <code>s[i], s[i+1], ···, s[j]</code>. The default value for <code>i</code> is <code>1</code>; the default value for <code>j</code> is <code>i</code>.<br />
: Note that numerical codes are not necessarily portable across platforms.<br />
: string.byte() works with English text only, use utf8.byte() for the international version.<br />
: See also: [[#string.char.2C_utf8.char|string.char]], [[#string.char.2C_utf8.char|utf8.char]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- the following call will return the ASCII values of "A", "B" and "C"<br />
a, b, c = string.byte("ABC", 1, 3)<br />
echo(a .. " - " .. b .. " - " .. c) -- shows "65 - 66 - 67"<br />
<br />
-- same for the international version but with the Unicode values<br />
a, b, c = utf8.byte("дом", 1, 3)<br />
echo(a .. " - " .. b .. " - " .. c) -- shows "1076 - 1086 - 1084"<br />
</syntaxhighlight><br />
<br />
==string.char, utf8.char==<br />
;string.char(···) or utf8.char(···)<br />
: Receives zero or more integers. Returns a string with length equal to the number of arguments, in which each character has the internal numerical code equal to its corresponding argument.<br />
: Note that numerical codes are not necessarily portable across platforms.<br />
: string.char() works with English text only, use utf8.char() for the international version.<br />
: See also: [[#string.byte.2C_utf8.byte|string.byte]], [[#string.byte.2C_utf8.byte|utf8.byte]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- the following call will return the string "ABC" corresponding to the ASCII values 65, 66, 67<br />
mystring = string.char(65, 66, 67)<br />
<br />
-- same for the infernational version which will return text "дом" for the Unicode values 1076, 1086, 1084<br />
mystring = utf8.char(1076,1086,1084)<br />
print(mystring)<br />
</syntaxhighlight><br />
<br />
==string.cut==<br />
;string.cut(string, maxLen)<br />
: Cuts string to the specified maximum length.<br />
: Returns the modified string.<br />
<br />
;Parameters:<br />
* ''string:''<br />
: The text you wish to cut. Passed as a string.<br />
* ''maxLen:''<br />
: The maximum length you wish the string to be. Passed as an integer number.<br />
<br />
See also: [[#utf8.remove|utf8.remove()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--The following call will return 'abc' and store it in myString<br />
myString = string.cut("abcde", 3)<br />
--You can easily pad string to certain length. Example below will print 'abcde ' e.g. pad/cut string to 10 characters.<br />
local s = "abcde"<br />
s = string.cut(s .. " ", 10) -- append 10 spaces<br />
echo("'" .. s .. "'")<br />
</syntaxhighlight><br />
<br />
==string.dump==<br />
;string.dump()<br />
Converts a function into a binary string. You can use the loadstring() function later to get the function back.<br />
: string.dump() works with both English and non-English text fine.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
testString = string.dump(function() echo("this is a string") end)<br />
--The following should then echo "this is a string"<br />
loadstring(testString)()<br />
</syntaxhighlight><br />
<br />
==string.enclose==<br />
;string.enclose(string)<br />
: Wraps a string with [[ ]]<br />
: Returns the altered string.<br />
<br />
;Parameters:<br />
* ''String:''<br />
:The string to enclose. Passed as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This will echo '[[Oh noes!]]' to the main window<br />
echo("'" .. string.enclose("Oh noes!") .. "'")<br />
</syntaxhighlight><br />
<br />
==string.ends==<br />
;string.ends(String, Suffix)<br />
: Test if string is ending with specified suffix.<br />
: Returns true or false.<br />
: See also: [[#string.starts|string.starts]]<br />
<br />
;Parameters:<br />
* ''String:''<br />
: The string to test. Passed as a string.<br />
* ''Suffix:''<br />
: The suffix to test for. Passed as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This will test if the incoming line ends with "in bed" and if not will add it to the end.<br />
if not string.ends(line, "in bed") then<br />
echo("in bed\n")<br />
end<br />
</syntaxhighlight><br />
<br />
==string.find, utf8.find==<br />
;string.find(text, pattern [, init [, plain]]) or utf8.find<br />
: Looks for the first match of pattern in the string text. If it finds a match, then find returns the indices of text where this occurrence starts and ends; otherwise, it returns nil. A third, optional numerical argument init specifies where to start the search; its default value is 1 and can be negative. A value of true as a fourth, optional argument plain turns off the pattern matching facilities, so the function does a plain "find substring" operation, with no characters in pattern being considered "magic". Note that if plain is given, then init must be given as well.<br />
If the pattern has captures, then in a successful match the captured values are also returned, after the two indices.<br />
: string.find() works with English text only, use utf8.find() for the international version.<br />
;Example<br />
<syntaxhighlight lang=lua><br />
-- check if the word appears in a variable<br />
if string.find(matches[2], "rabbit") then<br />
echo("Found a rabbit!\n")<br />
end<br />
<br />
-- the following example will print: "3, 4"<br />
local start, stop = string.find("This is a test.", "is")<br />
if start then<br />
print(start .. ", " .. stop)<br />
end<br />
-- note that here "is" is being found at the end of the word "This", rather than the expected second word<br />
<br />
-- to make it match the word on its own, prefix %f[%a] and suffix %f[%A]<br />
if string.find("This is a test", "%f[%a]is%f[%A]") then<br />
echo("This 'is' is the actual stand-alone word\n")<br />
end<br />
</syntaxhighlight><br />
* Return value:<br />
: nil or start and stop position of the first matched text, followed by any captured text.<br />
<br />
==string.findPattern==<br />
; string.findPattern(text, pattern)<br />
: Return first matching substring or nil.<br />
<br />
; Parameters<br />
* ''text:''<br />
: The text you are searching the pattern for.<br />
* ''pattern:''<br />
: The pattern you are trying to find in the text.<br />
<br />
; Example:<br />
Following example will print: "I did find: Troll" string.<br />
<syntaxhighlight lang="lua"><br />
local match = string.findPattern("Troll is here!", "Troll")<br />
if match then<br />
echo("I did find: " .. match)<br />
end<br />
</syntaxhighlight><br />
:This example will find substring regardless of case.<br />
<syntaxhighlight lang="lua">local match = string.findPattern("Troll is here!", string.genNocasePattern("troll"))<br />
if match then<br />
echo("I did find: " .. match)<br />
end<br />
</syntaxhighlight><br />
* Return value:<br />
: nil or first matching substring<br />
See also: [[#string.genNocasePattern|string.genNocasePattern()]]<br />
<br />
==string.format==<br />
;string.format(formatstring,...)<br />
: Returns a formatted version of its variable number of arguments following the description given in its first argument (which must be a string). The format string follows the same rules as the printf family of standard C functions. The only differences are that the options/modifiers *, l, L, n, p, and h are not supported and that there is an extra option, q. The q option formats a string in a form suitable to be safely read back by the Lua interpreter: the string is written between double quotes, and all double quotes, newlines, embedded zeros, and backslashes in the string are correctly escaped when written. For instance, the call<br />
<syntaxhighlight lang=lua><br />
string.format('%q', 'a string with "quotes" and \n new line')<br />
</syntaxhighlight><br />
will produce the string:<br />
<syntaxhighlight lang=lua><br />
"a string with \"quotes\" and \<br />
new line"<br />
</syntaxhighlight><br />
The options c, d, E, e, f, g, G, i, o, u, X, and x all expect a number as argument, whereas q and s expect a string.<br />
<br />
This function does not accept string values containing embedded zeros, except as arguments to the q option.<br />
<br />
string.format() works fine with both English and non-English text.<br />
<br />
;Example<br />
<syntaxhighlight lang=lua><br />
some_data = "MudletUser1"<br />
<br />
-- pad data 20 characters wide to the left<br />
display(string.format("%20s", some_data))<br />
-- result: " MudletUser1"<br />
<br />
-- pad same data but instead to the the right<br />
display(string.format("%-20s", some_data))<br />
-- result: "MudletUser1 "<br />
<br />
-- pad but first truncate data to 6 characters<br />
display(string.format("%20s", string.sub(some_data, 1, 6)))<br />
-- result: " Mudlet"<br />
</syntaxhighlight><br />
<br />
==string.genNocasePattern==<br />
; string.genNocasePattern(template)<br />
: Generate case insensitive search pattern from string.<br />
<br />
; Parameters<br />
* template: The original string to be used as the base.<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
echo(string.genNocasePattern("123abc"))<br />
-- result: "123[aA][bB][cC]"<br />
</syntaxhighlight><br />
<br />
==string.gfind==<br />
;string.gfind()<br />
: This is an old version of what is now string.gmatch. Use string.gmatch instead.<br />
;Example<br />
''Need example''<br />
<br />
==string.gmatch, utf8.gmatch==<br />
;string.gmatch(text, pattern) or utf8.gmatch<br />
: Returns an iterator function that, each time it is called, returns the next captures from pattern over string text. If pattern specifies no captures, then the whole match is produced in each call.<br />
As an example, the following loop<br />
<syntaxhighlight lang=lua><br />
s = "hello world from Lua"<br />
for w in string.gmatch(s, "%a+") do<br />
print(w)<br />
end</syntaxhighlight><br />
will iterate over all the words from string s, printing one per line. The next example collects all pairs key=value from the given string into a table:<br />
<syntaxhighlight lang=lua><br />
t = {}<br />
s = "from=world, to=Lua"<br />
for k, v in string.gmatch(s, "(%w+)=(%w+)") do<br />
t[k] = v<br />
end</syntaxhighlight><br />
For this function, a '^' at the start of a pattern does not work as an anchor, as this would prevent the iteration.<br />
: string.gmatch() works with English text only, use utf8.gmatch() for the international version.<br />
;Example<br />
''Need example''<br />
<br />
==string.gsub, utf8.gsub==<br />
;string.gsub(text, pattern, repl [, n]) or utf8.gsub<br />
: Returns a copy of text in which all (or the first n, if given) occurrences of the pattern have been replaced by a replacement string specified by repl, which can be a string, a table, or a function. gsub also returns, as its second value, the total number of matches that occurred.<br />
<br />
:If repl is a string, then its value is used for replacement. The character % works as an escape character: any sequence in repl of the form %n, with n between 1 and 9, stands for the value of the n-th captured substring (see below). The sequence %0 stands for the whole match. The sequence %% stands for a single %.<br />
<br />
:If repl is a table, then the table is queried for every match, using the first capture as the key; if the pattern specifies no captures, then the whole match is used as the key.<br />
<br />
:If repl is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order; if the pattern specifies no captures, then the whole match is passed as a sole argument.<br />
<br />
:If the value returned by the table query or by the function call is a string or a number, then it is used as the replacement string; otherwise, if it is false or nil, then there is no replacement (that is, the original match is kept in the string).<br />
<br />
: string.gsub() works with English text only, use utf8.gsub() for the international version.<br />
;Example<br />
<syntaxhighlight lang=lua><br />
x = string.gsub("hello world", "(%w+)", "%1 %1")<br />
--> x="hello hello world world"<br />
<br />
x = string.gsub("hello world", "%w+", "%0 %0", 1)<br />
--> x="hello hello world"<br />
<br />
x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")<br />
--> x="world hello Lua from"<br />
<br />
x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)<br />
--> x="home = /home/roberto, user = roberto"<br />
<br />
x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)<br />
return loadstring(s)()<br />
end)<br />
--> x="4+5 = 9"<br />
<br />
local t = {name="lua", version="5.1"}<br />
x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)<br />
--> x="lua-5.1.tar.gz"</syntaxhighlight><br />
<br />
==string.len, utf8.len==<br />
;string.len(string) or utf8.len(string)<br />
;<nowiki>mystring:len()</nowiki><br />
:Receives a string and returns its length. The empty string "" has length 0. Embedded zeros are counted, so "a\000bc\000" has length 5.<br />
: string.len() works with English text only, use utf8.len() for the international version.<br />
<br />
;Parameters:<br />
* ''string:''<br />
:The string (text) you want to find the length of.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- prints 5 for the 5 letters in our word<br />
print(string.len("hello"))<br />
<br />
-- international version<br />
print(utf8.len("слово"))<br />
</syntaxhighlight><br />
<br />
==string.lower, utf8.lower==<br />
;string.lower(string) or utf8.lower(string)<br />
;<nowiki>mystring:lower()</nowiki><br />
:Receives a string and returns a copy of this string with all uppercase letters changed to lowercase. All other characters are left unchanged. The definition of what an uppercase letter is depends on the current locale.<br />
: string.lower() works with English text only, use utf8.lower() for the international version.<br />
: See also: [[#string.upper.2C_utf8.upper|string.upper]], [[#string.upper.2C_utf8.upper|utf8.upper]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- prints an all-lowercase version<br />
print(string.lower("No way! This is AWESOME!"))<br />
<br />
-- international version<br />
print(utf8.lower("Класс! Ето ОТЛИЧНО!"))<br />
</syntaxhighlight><br />
<br />
==string.match, utf8.match==<br />
;string.match(text, pattern [, init]) or utf8.match()<br />
: Looks for the first match of pattern in the string text. If it finds one, then match returns the captures from the pattern; otherwise it returns nil. If pattern specifies no captures, then the whole match is returned. A third, optional numerical argument init specifies where to start the search; its default value is 1 and can be negative.<br />
: string.match() works with English text only, use utf8.match() for the international version.<br />
;Example<br />
''Need example''<br />
<br />
== string.patternEscape, utf8.patternEscape==<br />
;escapedString = string.patternEscape(str) or escapedString = utf8.patternEscape(str)<br />
<br />
:Returns a version of str with all Lua pattern characters escaped to ensure string.match/find/etc look for the original str.<br />
<br />
;See also:[[Manual:Lua_Functions#string.trim|string.trim()]], [[Manual:Lua_Functions#string.genNocasePattern|string.genNocasePattern()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
*''str:''<br />
:The string to escape lua pattern characters in.<br />
<br />
;Returns<br />
*The string with all special Lua pattern characters escaped.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- searching for a url inside of a string. <br />
local helpString = [[<br />
This feature can be accessed by going to https://some-url.com/athing.html?param=value and<br />
retrieving the result!<br />
]]<br />
local url = "https://some-url.com/"<br />
display(helpString:find(url))<br />
-- nil<br />
display(helpString:find(string.patternEscape(url)))<br />
-- 42<br />
-- 62<br />
display(url:patternEscape())<br />
-- "https://some%-url%.com/"<br />
</syntaxhighlight><br />
<br />
==string.rep==<br />
;string.rep(String, n)<br />
;<nowiki>mystring:rep(n)</nowiki><br />
: Returns a string that is the concatenation of <code>n</code> copies of the string <code>String</code>.<br />
: string.rep() works with both English and non-English text fine.<br />
<br />
;Example<br />
<syntaxhighlight lang=lua><br />
-- repeat * 10 times<br />
display(string.rep("*", 10))<br />
-- results in:<br />
**********<br />
<br />
-- do the same thing, but this time calling from a variable<br />
s = "*"<br />
display(s:rep(10))<br />
-- results in:<br />
**********<br />
</syntaxhighlight><br />
<br />
==string.reverse, utf8.reverse==<br />
;string.reverse(string) or utf8.reverse(string)<br />
;<nowiki>mystring:reverse()</nowiki><br />
<br />
: Returns a string that is the string <code>string</code> reversed.<br />
: string.reverse() works with English text only, use utf8.reverse() for the international version.<br />
<br />
;Parameters:<br />
* ''string:''<br />
:The string to reverse. Passed as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
mystring = "Hello from Lua"<br />
echo(mystring:reverse()) -- displays 'auL morf olleH'<br />
<br />
-- international version.<br />
mystring = "Привет от Луа!"<br />
echo(utf8.reverse(mystring)) -- displays '!ауЛ то тевирП', which probably looks the same to you<br />
</syntaxhighlight><br />
<br />
==string.split==<br />
;string.split(string, delimiter)<br />
;<nowiki>myString:split(delimiter)</nowiki><br />
: Splits a string into a table by the given delimiter. Can be called against a string (or variable holding a string) using the second form above.<br />
: Returns a table containing the split sections of the string.<br />
<br />
;Parameters:<br />
* ''string:''<br />
: The string to split. Parameter is not needed if using second form of the syntax above. Passed as a string.<br />
* ''delimiter:''<br />
: The delimiter to use when splitting the string. Passed as a string, and allows for [http://www.lua.org/pil/20.2.html Lua pattern types]. Use % to escape here (and %% to escape a stand-alone %).<br />
{{ Note }} as of Mudlet 4.7+, delimiter will default to " " if not provided.<br />
<br />
{{ Note }} as of Mudlet 4.7+, using "" (empty string) for the delimiter will return the string as a table of characters. IE string.split("This","") will return as {"T", "h", "i", "s"}. Prior to 4.7 using empty string as the delimiter would error after hanging temporarily.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This will split the string by ", " delimiter and print the resulting table to the main window.<br />
names = "Alice, Bob, Peter"<br />
name_table = string.split(names, ", ")<br />
display(name_table)<br />
<br />
--The alternate method<br />
names = "Alice, Bob, Peter"<br />
name_table = names:split(", ")<br />
display(name_table)<br />
</syntaxhighlight><br />
<br />
:Either method above will print out:<br />
: table {<br />
:: 1: 'Alice'<br />
:: 2: 'Bob'<br />
:: 3: 'Peter'<br />
: }<br />
<br />
==string.starts==<br />
;string.starts(string, prefix)<br />
: Test if string is starting with specified prefix.<br />
: Returns true or false<br />
: See also: [[#string.ends|string.ends]]<br />
<br />
;Parameters:<br />
* ''string:''<br />
: The string to test. Passed as a string.<br />
* ''prefix:''<br />
: The prefix to test for. Passed as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--The following will see if the line begins with "You" and if so will print a statement at the end of the line<br />
if string.starts(line, "You") then<br />
echo("====oh you====\n")<br />
end<br />
</syntaxhighlight><br />
<br />
==string.sub, utf8.sub==<br />
;string.sub(text, i [, j]) or utf8.sub()<br />
: Returns the substring of text that starts at i and continues until j; i and j can be negative. If j is absent, then it is assumed to be equal to -1 (which is the same as the string length). In particular, the call string.sub(text,1,j) returns a prefix of text with length j, and string.sub(text, -i) returns a suffix of text with length i.<br />
: string.sub() works with English text only, use utf8.sub() for the international version.<br />
;Example<br />
''Need example''<br />
<br />
==string.title==<br />
;string.title(string)<br />
;<nowiki>mystring:title()</nowiki><br />
: Capitalizes the first character in a string.<br />
: Returns the altered string.<br />
<br />
;Parameters:<br />
* ''string:''<br />
: The string to modify. Not needed if you use the second form of the syntax above.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--Variable testname is now Anna.<br />
testname = string.title("anna")<br />
--Example will set test to "Bob".<br />
test = "bob"<br />
test = test:title()<br />
</syntaxhighlight><br />
<br />
==string.trim==<br />
;string.trim(string)<br />
: Trims string, removing all 'extra' white space at the beginning and end of the text.<br />
: Returns the altered string.<br />
<br />
;Parameters:<br />
* ''string:''<br />
: The string to trim. Passed as a string.<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
--This will print 'Troll is here!', without the extra spaces.<br />
local str = string.trim(" Troll is here! ")<br />
echo("'" .. str .. "'")<br />
</syntaxhighlight><br />
<br />
==string.upper, utf8.upper==<br />
;string.upper(string) or utf8.upper(string)<br />
;<nowiki>mystring:upper()</nowiki><br />
: Receives a string and returns a copy of this string with all lowercase letters changed to uppercase. All other characters are left unchanged. The definition of what a lowercase letter is depends on the current locale.<br />
: string.upper() works with English text only, use utf8.upper() for the international version.<br />
<br />
: See also: [[#string.lower.2C_utf8.lower|string.lower]], [[#string.lower.2C_utf8.lower|utf8.lower]]<br />
<br />
;Parameters<br />
* ''string:''<br />
: The string you want to change to uppercase<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- displays 'RUN BOB RUN'<br />
print(string.upper("run bob run"))<br />
<br />
-- displays 'ДАВАЙ ДАВАЙ!'<br />
print(utf8.upper("давай давай!"))<br />
</syntaxhighlight><br />
<br />
==utf8.charpos==<br />
;utf8.charpos(string[[, charpos], offset])<br />
: Converts UTF-8 position to byte offset, returns the character position and code point. If only offset is given, returns byte offset of this UTF-8 char index. If charpos and offset is given, a new charpos will be calculated by adding/subtracting UTF-8 char offset to current charpos. In all cases, it return a new char position, and code point (a number) at this position.<br />
<br />
;Parameters<br />
* ''string:''<br />
: The input string to work on.<br />
* ''charpos:''<br />
: (optional) character position to work on.<br />
* ''offset:''<br />
: (optional) offset (as a number) to work on.<br />
<br />
==utf8.escape==<br />
;utf8.escape(string)<br />
: Escape a string to UTF-8 format string. It support several escape formats:<br />
<br />
%ddd - which ddd is a decimal number at any length:<br />
change Unicode code point to UTF-8 format.<br />
%{ddd} - same as %nnn but has bracket around.<br />
%uddd - same as %ddd, u stands Unicode<br />
%u{ddd} - same as %{ddd}<br />
%xhhh - hexadigit version of %ddd<br />
%x{hhh} same as %xhhh.<br />
%? - '?' stands for any other character: escape this character.<br />
<br />
;Parameters<br />
* ''string:''<br />
: The string you want to escape<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local u = utf8.escape<br />
print(u"%123%u123%{123}%u{123}%xABC%x{ABC}")<br />
print(u"%%123%?%d%%u")<br />
</syntaxhighlight><br />
<br />
==utf8.fold==<br />
;utf8.fold(string)<br />
: Returns the lowercase version of the string for use in case-insensitive comparisons. If string is a number, it's treated as a code point and the converted code point is returned (as a number).<br />
<br />
;Parameters<br />
* ''string:''<br />
: The string to lowercase.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
print(utf8.fold("ПРИВЕТ")) -- 'привет'<br />
print(utf8.fold("Привет")) -- 'привет'<br />
</syntaxhighlight><br />
<br />
==utf8.insert==<br />
;utf8.insert(string[, idx], substring)<br />
: Inserts the substring into the given string. If idx is given, inserts substring before the character at this index, otherwise the substring will append onto the end of string. idx can be negative.<br />
<br />
;Parameters<br />
* ''string:''<br />
: The input string to work on.<br />
* ''idx:''<br />
: (optional) character position to insert the string at.<br />
* ''substring:''<br />
: text to insert into the substring.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- inserts letter я before the 2nd letter and prints 'мясо'<br />
print(utf8.insert("мсо", 2, "я"))<br />
</syntaxhighlight><br />
<br />
==utf8.ncasecmp==<br />
;utf8.ncasecmp(a, b)<br />
: Compares ''a'' and ''b'' without case. Return -1 means a < b, 0 means a == b and 1 means a > b.<br />
<br />
;Parameters<br />
* ''a:''<br />
: String to compare.<br />
* ''b:''<br />
: String to compare against.<br />
<br />
==utf8.next==<br />
;utf8.next(string[, charpos[, offset]])<br />
: Iterates though the UTF-8 string.<br />
<br />
;Parameters<br />
* ''string:''<br />
: The input string to work on.<br />
* ''charpos:''<br />
: (optional) character position to work on.<br />
* ''offset:''<br />
: (optional) offset (as a number) to work on.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- prints location and code point of every letter<br />
for pos, code in utf8.next, "тут есть текст" do<br />
print(pos, code)<br />
end<br />
</syntaxhighlight><br />
<br />
==utf8.remove==<br />
;utf8.remove(string[, start[, stop]])<br />
: Removes characters from the given string. Deletes characters from the given ''start'' to the end of the string. If ''stop'' is given, deletes characters from ''start'' to ''stop'' (including start and stop). ''start'' and ''stop'' can be negative.<br />
<br />
;Parameters<br />
* ''string:''<br />
: The input string to work on.<br />
* ''start:''<br />
: position to start deleting characters from.<br />
* ''stop:''<br />
: (optional) posititon to stop deleting characters at.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- delete everything from the 3rd character including the character itself<br />
print(utf8.remove("мясо", 3)) -- 'мя'<br />
<br />
-- delete the last character, use negative to count backwards<br />
print(utf8.remove("мясо", -1)) -- 'мяс'<br />
<br />
-- delete everything from the 2nd to the 4th character<br />
print(utf8.remove("вкусное", 2,4)) -- 'вное'<br />
</syntaxhighlight><br />
<br />
==utf8.title==<br />
;utf8.title(string)<br />
: Returns the uppercase version of the string for use in case-insensitive comparisons. If string is a number, it's treated as a code point and the converted code point is returned (as a number).<br />
<br />
;Parameters<br />
* ''string:''<br />
: The string to uppercase.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
print(utf8.title("привет")) -- 'ПРИВЕТ'<br />
print(utf8.title("Привет")) -- 'ПРИВЕТ'<br />
</syntaxhighlight><br />
<br />
==utf8.width==<br />
;utf8.width(string[, ambi_is_double[, default_width]])<br />
: Calculate the widths of the given string. If the string is a code point, return the width of this code point.<br />
<br />
;Parameters<br />
* ''string:''<br />
: The input string to work on.<br />
* ''ambi_is_double:''<br />
: (optional) if provided, the ambiguous width character's width is 2, otherwise it's 1.<br />
* ''default_width:''<br />
: (optional) if provided, this will be the width of unprintable character, used display a non-character mark for these characters.<br />
<br />
==utf8.widthindex==<br />
;utf8.widthindex(string, location[, ambi_is_double[, default_width]])<br />
: Returns the character index at the location in the given string as well as the offset and the width. This is a reverse operation of utf8.width().<br />
<br />
;Parameters<br />
* ''string:''<br />
: The input string to work on.<br />
* ''location:''<br />
: location to get the width of.<br />
* ''ambi_is_double:''<br />
: (optional) if provided, the ambiguous width character's width is 2, otherwise it's 1.<br />
* ''default_width:''<br />
: (optional) if provided, this will be the width of unprintable character, used display a non-character mark for these characters.<br />
<br />
[[Category:Mudlet Manual]]<br />
[[Category:Mudlet API]]</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:Introduction&diff=20555Manual:Introduction2023-11-11T20:27:38Z<p>Demonnic: /* Command-line Shortcuts */</p>
<hr />
<div><languages/><br />
{{TOC right}}<br />
{{#description2:Basic introduction to Mudlet, including aliases, variables, scripts, triggers, keybindings, timers, events, etc.}}<br />
<translate><br />
= Automation and game rules = <!--T:1--><br />
<br />
<!--T:2--><br />
It is possible to create an Artificial Intelligence (AI) that does everything you can do in a game. Even more so, an AI can outperform you in every routine operation, depending on the complexity of the task. Because scripting is so powerful, it can give you a competitive advantage that some people consider unfair or even cheating. In some cases it can have much more far reaching consequences on a game, such as inflation, loss of balance in terms of game-mechanics or, ultimately, a complete crash of in-game economy. For these and various other reasons the administrators and owners of some games forbid or limit the use of automation tools.<br />
<br />
<!--T:197--><br />
By including scripting support in Mudlet, we effectively give you the ability to create and utilize AI toolkits. However, '''we do not endorse or promote the usage of automation if it is prohibited in your game!''' Keep in mind that by cheating you can lessen the quality of gameplay for both your fellow players and yourself.<br />
<br />
= Mudlet's Automation Features = <!--T:3--><br />
<br />
<!--T:4--><br />
Mudlet offers a vast array of standard features to automate or otherwise improve your gaming experience. These include, but are not limited to:<br />
<br />
<!--T:5--><br />
; [[#Aliases|Aliases]] <br />
: User-defined text input, which is converted into a different, usually longer input before being sent to the game. <br />
: e.g. typing '''gg''' to have '''get gold from ground;put gold in bag''' be sent to the game'''.<br />
<br />
<!--T:9--><br />
; [[#Variables|Variables]] <br />
: allow the user to store text or numbers for easier use inside scripts.<br />
<br />
<!--T:7--><br />
; [[#Triggers|Triggers]] <br />
: execute user-defined commands upon receiving specific out from the game, <br />
: e.g. gamesends: "You see Elyssa standing here." and Mudlet automatically sends "poke Elyssa" to the game.<br />
<br />
<!--T:6--><br />
; [[#Keybindings|Keybindings]] <br />
: also known as hotkeys, allow executing certain user-defined commands by simultaneously pressing a specific combination of keys <br />
:e.g. pressing '''CTRL+H''' to send "say Hello Miyuki!" to the game or play '''La Marseillaise'''<br />
<br />
<!--T:8--><br />
; [[#Timers|Timers]]<br />
: delay the execution of a command or execute it after a specified period of time.<br />
: e.g. throw gauntlet to Eric-wait 3 seconds-exclaim Let us end this here!<br />
<br />
<!--T:10--><br />
; [[#Events|Events]] <br />
: allow the user to make triggers for specific events like when Mudlet has connected to the game, or even user-defined events to use in complex system making.<br />
<br />
<!--T:11--><br />
To get started on programming in Mudlet, '''[http://www.mudlet.org/media/ watch these screencasts]''' that explain the basics that'll help you get started. <br />
<br />
<!--T:12--><br />
Keep on reading for an introduction to Mudlet's features:<br />
<br />
<br />
<br />
</translate><br />
<span id="aliases"></span><br />
<translate><br />
<br />
= Aliases = <!--T:13--><br />
<br />
<!--T:14--><br />
Aliases are the most basic way of automating the gameplay - you can use aliases to shorten the amount of typing you do. See more detailed info here: [[Manual:Alias Engine|Manual:Alias Engine]]<br />
<br />
<br />
<br />
== Example - Brew’o'Matic 6000 == <!--T:15--><br />
<br />
<!--T:16--><br />
You’re walking around the epic dungeon of the Unholy Firedragon of Westersand, gathering roots in order to brew a potion and thus restore the growth of hair on Farmer Benedict’s bald head. Once you see a root, you need to:<br />
<br />
<!--T:17--><br />
<pre><br />
open the bag of tools<br />
get the sickle of damnation from the bag of tools<br />
cut the root of hair-growth<br />
<wait 5 seconds><br />
clean the sickle of damnation of deadly root acid<br />
put the sickle of damnation in the bag of tools<br />
close the bag of tools<br />
open the magical bag of storing<br />
take the root<br />
put the root into the magical bag of storing<br />
close the magical of storing<br />
</pre><br />
<br />
<!--T:18--><br />
And once you’re done, do the exact same thing nine more times… thrice a day!<br />
<br />
<!--T:19--><br />
Alternatively, you just create an alias that would do this all with a single command - for example, "quest". To make that happen, read on! Here's a sneak peek on what you should have in the end: <br />
<br />
<!--T:20--><br />
[[File:Quest alias.png|center]]<br />
<br />
<br />
<br />
== Making an Alias == <!--T:21--><br />
<br />
<!--T:22--><br />
To get started, go click on the '''Aliases''' button in Mudlet, and then on the '''Add''' one. This will make a blank alias for you, which we’ll now fill in.<br />
<br />
<!--T:23--><br />
The ''Alias name'' field is optional - it’s mainly used for the alias listing that you see on the left as an easy way to distinguish all of the aliases. You can just name our alias "test" for now. The ''Pattern'' field is where you put your regex pattern to describe the command you'll enter to make your new alias spring into action. Let’s say we want our new alias to send the command "say hello" whenever we type "sh". The regex pattern would be '''^sh$'''. Then we put '''say hello''' into the ''Command'' field. After you have saved and activated your new alias "test", whenever you type "sh" Mudlet will not send "sh", but "say hello" instead. We call this replacement process alias expansion.<br />
<br />
<!--T:24--><br />
Mudlet uses Perl regular expression aliases. Regexes are a special way of matching patterns of words. For the beginners it is enough to think of them as a general way to specify the words itself and their placement within the line. For basic aliases it is enough to know that the character ^ symbolizes the beginning of the line and the character $ symbolizes the end of the line. If you want to make an alias "tw" that sends the command "take weapon", you don’t have to care about placement or pattern matching in general. All you need to do is fill '''^tw$''' in the field called "Regex" and type '''take weapon''' in the field called "command". Then you need to save the new alias by clicking on the "Save" icon in the top middle. The symbol for unsaved items disappears and makes way for a little blue checkbox. If this box is checked the alias is active. If the blue box is empty, the alias is deactivated and will not work unless you press the "activate" toggle padlock icon. Now you are ready to go. Type "tw" in the command line and press the enter key. Mudlet will send "take weapon" to the game. Aliases are basically a feature to save you a bit of typing (much like buttons which will be described in detail in a later section of the manual). More advance alias usage will be described later in the manual.<br />
<br />
== Making a Targetting Alias == <!--T:25--><br />
<br />
<!--T:26--><br />
To make an alias that'll remember your target - making it easier to use your skills and saving you the hassle of typing the target in all the time, do the following:<br />
<br />
<!--T:27--><br />
In the '''Pattern''' field, place the following:<br />
<br />
<!--T:28--><br />
^t (.+)$<br />
<br />
<!--T:29--><br />
That will match all commands that you type in the format of '''t <any words>''' - it'll match ''t rat'', ''t tsol'aa'', ''t human'' and etcetera.<br />
<br />
<!--T:30--><br />
Next, make the big box do this:<br />
<br />
<!--T:31--><br />
<syntaxhighlight lang="lua"><br />
target = matches[2]<br />
cecho("<light_slate_blue>My target is now: <red>"..target.."\n")<br />
</syntaxhighlight><br />
<br />
<!--T:32--><br />
[[File:Basic_targetting.png|center]]<br />
<br />
<!--T:33--><br />
You can also make an alias with an optional target:<br />
<br />
<!--T:34--><br />
^dd(?: (.+))?$<br />
<br />
<!--T:35--><br />
Now the target, if it is supplied, is going to be ''matches[2]''. You can test if the target was given with this code:<br />
<br />
<!--T:36--><br />
<syntaxhighlight lang="lua"><br />
send("cast spell at "..(matches[2] or target))<br />
</syntaxhighlight><br />
<br />
<br />
<!--T:37--><br />
That's it - whenever you use this alias, your target will be remembered in the ''target'' variable.<br />
<br />
<!--T:38--><br />
Next, you'd like to make use of this variable - so make another alias that will do the actual attacking for you! Here's an example one:<br />
<br />
<!--T:39--><br />
Pattern:<br />
<br />
<!--T:40--><br />
^atk$<br />
<br />
<!--T:41--><br />
Code:<br />
<br />
<!--T:42--><br />
<syntaxhighlight lang="lua"><br />
send("kick "..target)<br />
</syntaxhighlight><br />
<br />
<!--T:43--><br />
This alias will kick the target when you type in ''atk''. Feel free to adjust the "trigger" word and the command as you need them.<br />
<br />
<!--T:44--><br />
[[File:Basic attack alias.png|center]]<br />
<br />
<br />
<br />
</translate><br />
<span id="variables"></span><br />
<translate><br />
== Variables == <!--T:45--><br />
<br />
<!--T:46--><br />
Variables are containers for data. In Lua, they can store numbers or words. You can use variables to store important information like how much gold do you have, or have them remember things for you.<br />
<br />
<!--T:47--><br />
The syntax for making a variable remember a number is the following - create them in the Script editor in a new script:<br />
<syntaxhighlight lang="lua">variable = 1234</syntaxhighlight><br />
<br />
<!--T:48--><br />
Or to make it remember some text:<br />
<syntaxhighlight lang="lua">my_name = "Bob"</syntaxhighlight><br />
<br />
<!--T:49--><br />
It'll then appear in the Variables view, like so:<br />
<br />
<!--T:50--><br />
[[File:Variables_view.png|border|center|800px|]]<br />
<br />
</translate><br />
{{note|The variables view doesn't autoupdate, but it can be refreshed by clicking the Variables button.}}<br />
<translate><br />
<br />
<!--T:51--><br />
You can also do basic maths easily, for example:<br />
<br />
<!--T:52--><br />
To concatenate strings together, you can use the .. expression:<br />
<syntaxhighlight lang="lua">my_full_name = "Bob" .. " the Builder"</syntaxhighlight><br />
<br />
<!--T:53--><br />
Don't forget to use a space when you're concatenating two variables together:<br />
<syntaxhighlight lang="lua"><br />
firstname = "Apple"<br />
lastname = "Red"<br />
<br />
<!--T:54--><br />
-- bad: will produce "AppleRed"<br />
full_name = firstname .. lastname<br />
<br />
<!--T:55--><br />
-- good: will produce "Apple Red"<br />
full_name = firstname .. " " .. lastname<br />
</syntaxhighlight><br />
<br />
<!--T:56--><br />
You can also edit and delete variables from the variables view. Be careful when changing or deleting existing variables made by third-party scripts - you might break them. If that happens, re-opening the profiles will restore the variables back to working order.<br />
<br />
<!--T:57--><br />
While you can create variables in the Variables view, remember that they won't be saved when Mudlet shuts down - if you'd like them to be more permanent, create scripts with the variables instead.<br />
<br />
= Command-line Shortcuts =<br />
<br />
The command line has some built in keyboard shortcuts.<br />
<br />
{| class="wikitable"<br />
|-<br />
| Tab || Tab completion, see [[Manual:Technical Manual#Command_Line_Auto-Completion.2C_Tab-Completion_and_Command_History|this technical manual section]].<br />
|-<br />
| Up or Down || Command line history, see [[Manual:Technical Manual#Command_Line_Auto-Completion.2C_Tab-Completion_and_Command_History|this technical manual section]].<br />
|-<br />
| Home || Move cursor to beginning of line.<br />
|-<br />
| End || Move cursor to end of line.<br />
|-<br />
| CTRL+A || Select all.<br />
|-<br />
| CTRL+F || Move cursor to search bar.<br />
|-<br />
| SHIFT+Enter || Create an additional input line.<br />
|-<br />
| SHIFT+Left || Highlight one character left of the cursor (or unhighlight if already highlighted).<br />
|-<br />
| SHIFT+Right || Highlight one character right of the cursor (or unhighlight if already highlighted).<br />
|-<br />
| CTRL+Left || Move cursor one word to the left.<br />
|-<br />
| CTRL+Right || Move cursor one word to the right.<br />
|-<br />
| Backspace || Deletes the character to the left of the cursor.<br />
|-<br />
| CTRL+Backspace || Remove one word left of the cursor.<br />
|-<br />
| Delete || Deletes the character to the right of the cursor.<br />
|-<br />
| CTRL+Delete || Remove one word right of the cursor.<br />
|-<br />
| SHIFT+CTRL+Left || Highlight one word left of cursor.<br />
|-<br />
| SHIFT+CTRL+Right || Highlight one word right of cursor.<br />
|-<br />
| CTRL+Insert || Copies the selected text to the clipboard.<br />
|-<br />
| CTRL+K || Deletes to the end of the line.<br />
|-<br />
| CTRL+V || Pastes the clipboard text into line edit.<br />
|-<br />
| SHIFT+Insert || Pastes the clipboard text into line edit.<br />
|-<br />
| CTRL+X || Deletes the selected text and copies it to the clipboard.<br />
|-<br />
| SHIFT+Delete || Deletes the selected text and copies it to the clipboard.<br />
|-<br />
| Ctrl+Z || Undoes the last operation.<br />
|-<br />
| Ctrl+Y || Redoes the last undone operation.<br />
|-<br />
| PgUp || Scroll up one page in the main window buffer<br />
|-<br />
| PgDn || Scroll down one page in the main window buffer<br />
|-<br />
| Ctrl+Enter || Return to the bottom of the main window buffer<br />
|-<br />
|}<br />
<br />
See also: [https://doc.qt.io/qt-6/qlineedit.html#details QT manual]<br />
<br />
= Sending commands to the game = <!--T:58--><br />
<br />
<!--T:59--><br />
To send a command to the game, you can use the send() function. Data inside the quotes is sent to the game.<br />
<br />
<!--T:60--><br />
For example, the following code sends the command to eat bread:<br />
<syntaxhighlight lang="lua">send("eat bread")</syntaxhighlight><br />
<br />
<!--T:61--><br />
If you’d like to include variables in the send command, you need to prefix and suffix them with two dots outside the quotes, like this:<br />
<syntaxhighlight lang="lua">send("My name is " .. full_name .. ". What's yours?")</syntaxhighlight><br />
<br />
<!--T:62--><br />
If your commands ends with a variable, you don't need the two dots after:<br />
<syntaxhighlight lang="lua">send("Hi, my name is " .. character)</syntaxhighlight><br />
<br />
<!--T:63--><br />
Should you want to include double quotes, use a double set of square brackets like this:<br />
<syntaxhighlight lang="lua">send([[say "Hi, I'm new here!"]])</syntaxhighlight><br />
<br />
<!--T:64--><br />
When inserting a variable, you'd use the ]] and [[ appropriately:<br />
<syntaxhighlight lang="lua">send([[poke ]]..victim)</syntaxhighlight><br />
<br />
<!--T:207--><br />
To send many directions, use [[Manual:Mapper_Functions#speedwalk|speedwalk()]]:<br />
<syntaxhighlight lang="lua">speedwalk("n;e;s;w;")</syntaxhighlight><br />
<br />
<!--T:208--><br />
To send many actions, use [[Manual:Networking_Functions#sendAll|sendAll()]]:<br />
<syntaxhighlight lang="lua">sendAll("attack", "cast magic missile")</syntaxhighlight><br />
<br />
= Showing text on screen = <!--T:65--><br />
<br />
<!--T:66--><br />
To echo (show text to yourself) you can use the echo() or the insertText() function. For example, the following code will display "Time to eat dinner!" on your screen:<br />
<br />
<!--T:67--><br />
<syntaxhighlight lang="lua">echo("Time to eat dinner!")</syntaxhighlight><br />
<br />
<!--T:68--><br />
If you’d like to include variables in your echo, you concatenate (put together) the value of your variable to the text:<br />
<syntaxhighlight lang="lua"><br />
my_gold = 5<br />
echo("I have " .. my_gold .. " pieces of gold!\n")<br />
</syntaxhighlight><br />
<br />
<!--T:69--><br />
If you'd like to include a new line in your text, insert ''\n'' for it:<br />
<br />
<!--T:70--><br />
<syntaxhighlight lang="lua"><br />
echo("this echo\nis on\nthree lines!")<br />
<br />
<!--T:71--><br />
-- comes out at:<br />
this echo<br />
is on<br />
three lines!<br />
</syntaxhighlight><br />
<br />
<br />
<br />
= Seeing errors in your code = <!--T:72--><br />
<br />
<!--T:73--><br />
Undoubtedly you'll be making mistakes when you're coding! To err is human, after all. There are two types of mistakes you can make in general: when the words you've typed in make no sense to Lua at all, or they do make sense, but they don't do what you actually thought and intended them to do - or other circumstances are preventing it from working at that point in time.<br />
<br />
<br />
<br />
== Syntax errors aka Ladybugs == <!--T:74--><br />
<br />
<!--T:75--><br />
When you type something in that doesn't make sense to Lua, it's called a syntax mistake (or [http://en.wikipedia.org/wiki/Syntax_error error]). Mudlet will realize this and show you a little ladybug, and '''also tell you on which line the mistake is'''. Here's an example:<br />
<br />
<!--T:76--><br />
[[File:Syntax error.png|1000px|center]]<br />
<br />
<!--T:77--><br />
The ''echo()'' function on line 3 is missing a closing bracket - every bracket in Lua that's not green needs to be closed. Mudlet showed you a ladybug symbol on the alias, to indicate that the alias has a problem. It also showed you that the ( bracket should be closed on line 3. To fix this, you'd add the ''')''', save, and it will be all happy.<br />
<br />
<br />
<br />
== Runtime errors aka Errors View == <!--T:78--><br />
<br />
<!--T:79--><br />
Another type of mistake is when what you typed in makes sense to Lua when you typed it in, but when it's time for code to be actually run, something wrong happens. For example, you asked Lua to '''eecho("hey!")''' - this is valid, you typed it in right, but there is one problem - eecho doesn't exist. So when you run the alias, nothing actually happens. Why?<br />
<br />
<!--T:80--><br />
Mudlet puts all problems that happen when things are run into the Errors view. It is hidden by default, open it by '''pressing the errors button that you see on bottom-left'''. This is where the error is logged at - not your main window, so you aren't spammed when you make a mistake in a piece of code that happens very often.<br />
<br />
<!--T:81--><br />
Opening it up will show this:<br />
<br />
<!--T:82--><br />
[[File:Runtime error.png|1000px|center]]<br />
<br />
<!--T:83--><br />
Let's analyse the message that's shown to us. ''object:<Some random alias>'' means that the Mudlet name you gave to the thing that had a problem is ''Some random alias'' - which is, indeed, our alias. ''function'' will tell you ''Alias'', ''Trigger'', ''Script'' or something else - this helps you locate the problematic item in question.<br />
<br />
<!--T:84--><br />
Next red line is the actual error: it's saying that on line 2 (it's off by one - so actually line 1), ''eecho'' is a '''nil value'''. In Lua, nil means doesn't exist. Hence what it's telling you is that eecho does not actually exist! Change it to ''echo'', run it again, and there will be happiness.<br />
<br />
<!--T:85--><br />
That's it for now - this page in time will be improved with common techniques you can use to diagnose errors quickly, etc... if you know anything about this, feel free to add it here!<br />
<br />
<br />
<br />
</translate><br />
<span id="triggers"></span><br />
<translate><br />
<br />
= Triggers = <!--T:86--><br />
<br />
<!--T:87--><br />
Triggers are an automation feature offered in all game clients. They help you respond quicker a particular situation and generally make things more convenient for you since you need to do less manual work as your triggers will do the hard work for you often times. This helps you concentrate more on the important aspects of the game and lessen stress. <br />
<br />
<!--T:88--><br />
The way a trigger works is simple: You define some text that you want to trigger some action. This is called the trigger pattern. When the trigger "sees" this text in the game output, it’ll run the commands you’ve told it to. <br />
<br />
<!--T:89--><br />
Simple example: Whenever you see a bunny, you want to attack it (meanie!). <br />
<br />
<!--T:90--><br />
# You type "bunny" in the data field titled "1" to add this word to the list of texts this trigger fires on. Make sure the dropdown next to it says "substring". <br />
# Now you type "kill bunny" in the field called "Command". This will be the command that the trigger will send to your game whenever the trigger fires. <br />
# Finally click "Save Item" to save your new trigger and also click "Activate". By doing this, the blue checkbox icon in front of the trigger name (in the trigger tree on the left side) gets checked. The trigger is now activated.<br />
<br />
<!--T:209--><br />
[[File:Trigger intro.png|1000px|center]]<br />
<br />
<!--T:91--><br />
As the trigger is active, each time the word "bunny" will appear in the game output, your trigger will issue the command "kill bunny" automatically. It will repeat this as long as the trigger stays active. When you want to stop hunting bunnies, you can simply select the bunny trigger and then click on the padlock icon to deactivate the trigger. The check mark will vanish and the trigger will stop firing until you re-enable it again via the padlock icon. <br />
<br />
<!--T:92--><br />
You can also put triggers in a group, then lock a group of triggers or an entire trigger branch. If you do that, all triggers in this group or branch will be locked until you remove the lock again. The locking starts from the root of the tree down to the end. As soon as a lock is met the trigger engine will skip the locked branch. Locking and unlocking branches is one of the most common actions you have to take care of when playing. For example, you can turn on your defensive triggers when engaging into a battle and you turn them off afterwards, or you turn on your harvesting triggers only when you are going to harvest.<br />
<br />
<!--T:93--><br />
Beginners should use Mudlet's automated highlight triggers in the beginning to highlight the text that has been triggered on to get the hang of the different trigger and pattern types. Click on the "highlight trigger" option and pick a foreground and a background color that you like to highlight your trigger with. When the trigger matches it automatically highlights its pattern. This is the most used form of triggers in Mudlet as it is a quick way of highlighting words that are important to you at the moment. You don’t have to know anything about scripting, regular expressions etc. to use highlight triggers. Just type in the word you like to be highlighted, select appropriate colors, save the new trigger and activate it.<br />
<br />
<br />
<br />
== Matching one unknown word == <!--T:94--><br />
<br />
<!--T:95--><br />
You can also set up a trigger to gather the weapons, gold or whatever skeletons could carry around with them. Since we do not know what the loot is exactly just yet, we will need to set up a trigger to match the line, identify the loot and take whatever it is that was dropped. <br />
<br />
<!--T:96--><br />
Examples for messages received could be:<br />
<br />
<!--T:97--><br />
The skeleton drops ring.<br />
The skeleton drops gold.<br />
The skeleton drops scimitar.<br />
The skeleton drops wooden key.<br />
<br />
<!--T:98--><br />
"The skeleton drops " (including the last space character) is the generic segment of the line, but the loot itself varies. Thus, we need to tell the client to take whatever the skeleton dropped. We do this by setting up a so-called regular expression:<br />
<br />
<!--T:99--><br />
# In the data field titled "1" write the following '''perl regex''' type pattern: <syntaxhighlight lang="lua">^The skeleton drops (.+)\.$</syntaxhighlight><br />
# Make sure to change the dropdown menu for this line to "perl regex" as well<br />
# In the big script box below write the following lua code: <syntaxhighlight lang="lua">send("take " .. matches[2])</syntaxhighlight><br />
<br />
<!--T:210--><br />
[[File:Trigger intro 2.png|1000px|center]]<br />
<br />
<!--T:100--><br />
The regular expression (.+) matches any characters that the client receives between "The skeleton drops " (NB: notice the blank/space character at the end) and the full-stop symbol that ends the sentence. Know that the variable matches[2] simply transfers the first matched text fitting the search criteria into the output. For this example, it will be the dropped loot we now will take automatically. This text may actually contain more than one word, like in the fourth example shown above. <br />
<br />
<!--T:101--><br />
In case you may wonder, matches[1] contains the entire line in whitch the matched text was found, whereas matches[2] contains only the first capture group. More on this in section two of the manual. The symbols ^ and $ indicate the start and end of a whole line.<br />
<br />
== Matching multiple unknowns == <!--T:102--><br />
<br />
<!--T:103--><br />
Now, we don't want to take only loot from skeletons but from many different sources.<br />
<br />
<!--T:104--><br />
Examples could be:<br />
<br />
<!--T:105--><br />
The skeleton drops ring.<br />
The giant drops gold.<br />
The king drops scimitar.<br />
The box drops wooden key.<br />
<br />
<!--T:106--><br />
So let’s make a trigger that would gather the loot from anybody:<br />
<br />
<!--T:107--><br />
# In data field "1" write: <syntaxhighlight lang="lua">^(.+) drops (.+)\.$</syntaxhighlight><br />
# Select '''perl regex''' type pattern again<br />
# Below write the lua code: <syntaxhighlight lang="lua">send("take " .. matches[3])</syntaxhighlight><br />
<br />
<!--T:211--><br />
[[File:Trigger intro 3.png|1000px|center]]<br />
<br />
<!--T:108--><br />
In this case, any time somebody, or something, "drops" something or someone else, the client will pick it up. Note that we used matches[3] instead of matches[2] this time, in order to pick up the second match. If we used matches[2], we’d end up picking up the skeleton’s corpse.<br />
<br />
== Matching known variants == <!--T:109--><br />
<br />
<!--T:110--><br />
If you’re playing a game in English, you’ll notice that these triggers probably won’t work due to English syntax. Compare:<br />
<br />
<!--T:111--><br />
The skeleton drops ring.<br />
The skeleton drops a ring.<br />
<br />
<!--T:112--><br />
Chances are that you’ll see the later case a little more often. If we used our old regex, the trigger would produce something like this.<br />
<br />
<!--T:113--><br />
TRIGGERED LINE: The skeleton drops a ring.<br />
OUR REACTION: take a ring<br />
<br />
<!--T:114--><br />
However most games can’t handle determiners in user-input, such as articles (i.e. a, an, the) or quantifiers (e.g. five, some, each). In effect, our triggered reaction won't suffice. Instead we would need to react with just "take ring" again.<br />
<br />
<!--T:115--><br />
To correctly handle lines like this, we could either create multiple triggers matching every possible article, which could become very cumbersome. Instead we make one regular expression filtering out all these words and phrases:<br />
<br />
<!--T:116--><br />
# Write a new '''perl regex''' type pattern: <syntaxhighlight lang="lua">(.+) drops (a|an|the|some|a couple of|a few|) (.+)\.$</syntaxhighlight><br />
# With this script: <syntaxhighlight lang="lua">send("take " .. matches[4])</syntaxhighlight><br />
<br />
<!--T:212--><br />
[[File:Trigger intro 4.png|1000px|center]]<br />
<br />
<!--T:117--><br />
Once again, note that this time we are using the third matched group through matches[4] now. <br />
<br />
</translate><br />
==<span class="mw-headline" id="Basic_Regex_Characters">Basic Regex Characters</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span>[[/index.php?title=Manual:Introduction&veaction=edit&section=1|edit]]<span class="mw-editsection-divider"> | </span>[[/index.php?title=Manual:Introduction&action=edit&section=1|edit source]]<span class="mw-editsection-bracket">]</span></span>==<br />
<span></span><br />
You already know <code>(.+)</code> which will match to any and all characters that follow until the end of line or another specific text that you may put in your regex. How about if you only want to match to certain type of characters?<br />
<br />
<br />
<br />
<span></span><br />
===<span class="mw-headline" id="Retrieving_numbers_from_triggers">Retrieving numbers from triggers</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span>[[/index.php?title=Manual:Introduction&veaction=edit&section=2|edit]]<span class="mw-editsection-divider"> | </span>[[/index.php?title=Manual:Introduction&action=edit&section=2|edit source]]<span class="mw-editsection-bracket">]</span></span>===<br />
<span></span><br />
Wildcards from triggers are stored in the matches[] table. The first wildcard goes into matches[2], second into matches[3], and so on, for however many wildcards do you have in your trigger.<br />
<br />
For example, you’d like to say out loud how much gold did you pick up from a slain monster. The message that you get when you pick up the gold is the following:<br />
<br />
<span></span><br />
You pick up 16 gold.<br />
<span></span><br />
A trigger that matches this pattern could be:<br />
<br />
<span></span><br />
#Perl Regex: <div class="mw-highlight mw-highlight-lang-lua mw-content-ltr" dir="ltr"> <span></span><span class="o">^</span><span class="n">You</span> <span class="n">pick</span> <span class="n">up</span> <span class="p">(</span><span class="err">\</span><span class="n">d</span><span class="o">+</span><span class="p">)</span> <span class="n">gold</span><span class="err">\</span><span class="p">.</span><span class="err">$</span> </div><br />
#Script: <div class="mw-highlight mw-highlight-lang-lua mw-content-ltr" dir="ltr"> <span></span><span class="n">echo</span><span class="p">(</span><span class="s2">"I got "</span> <span class="o">..</span> <span class="nb">tonumber</span><span class="p">(</span><span class="n">matches</span><span class="p">[</span><span class="mi">2</span><span class="p">])</span> <span class="o">..</span> <span class="s2">" gold!"</span><span class="p">)</span> </div><br />
<span></span><br />
<br />
In your code, the variable matches[2] will contain the amount of gold you picked up - in this case, 16. Now you say out loud how much gold you did loot. Notice also that (\d+) will only recognize numbers but not letters or a space character.<br />
<br />
<br />
<br />
<span></span><br />
===<span class="mw-headline" id="Retrieving_alphanumeric_characters">Retrieving alphanumeric characters</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span>[[/index.php?title=Manual:Introduction&veaction=edit&section=3|edit]]<span class="mw-editsection-divider"> | </span>[[/index.php?title=Manual:Introduction&action=edit&section=3|edit source]]<span class="mw-editsection-bracket">]</span></span>===<br />
<span></span><br />
Here’s a more advanced example by Heiko, which makes you talk like Yoda:<br />
<br />
<span></span><br />
#Perl Regex: <div class="mw-highlight mw-highlight-lang-lua mw-content-ltr" dir="ltr"> <span></span><span class="o">^</span><span class="n">say</span> <span class="p">(</span><span class="err">\</span><span class="n">w</span><span class="o">+</span><span class="p">)</span> <span class="o">*</span><span class="p">(</span><span class="err">\</span><span class="n">w</span><span class="o">*</span><span class="p">)</span> <span class="p">.</span><span class="o">*</span><span class="err">?</span><span class="p">(.</span><span class="o">*</span><span class="p">)</span> </div><br />
#Script: <div class="mw-highlight mw-highlight-lang-lua mw-content-ltr" dir="ltr"> <span></span><span class="n">send</span><span class="p">(</span> <span class="s2">"say "</span><span class="o">..</span><span class="n">matches</span><span class="p">[</span><span class="mi">4</span><span class="p">]</span><span class="o">..</span><span class="s2">" "</span><span class="o">..</span><span class="n">matches</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="o">..</span><span class="s2">" "</span><span class="o">..</span><span class="n">matches</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span> <span class="p">)</span> </div><br />
<span></span><br />
<br />
The trigger will recognize that you say something, and save in seperate groups the first word, the second word and then the rest of you text. Here the \w wildcards will match any numbers or letters but no non-alphanumeric characters. It then shows you say the rest of the text first, then the first word and finally the second word. Notice this will only affect the text displayed for yourself, but if you want to also adjust the text you are sending to other players, please see the [[Manual:Introduction#Aliases|chapter about aliases]].<br />
<br />
<br />
{{Note}}want to learn more regex? Try [https://regexlearn.com/ https://regexlearn.com] which is a great, easy to follow resource for this.<br />
<br />
<span></span><br />
==<span class="mw-headline" id="Highlighting_Words">Highlighting Words</span><span class="mw-editsection"><span class="mw-editsection-bracket">[</span>[[/index.php?title=Manual:Introduction&veaction=edit&section=4|edit]]<span class="mw-editsection-divider"> | </span>[[/index.php?title=Manual:Introduction&action=edit&section=4|edit source]]<span class="mw-editsection-bracket">]</span></span>==<br />
<span></span><br />
To highlight something in the game output, make a trigger and use the "highlight trigger" option to highlight the matched trigger pattern.<br />
<br />
Optionally, you can also make use of the [[/w/Special:MyLanguage/Manual:Lua Functions#bg|bg()]] and [[/w/Special:MyLanguage/Manual:Lua Functions#fg|fg()]] functions in scripting to highlight.<br />
<br />
<br />
<br />
<span id="keybindings"></span><br />
<translate><br />
<br />
= Keybindings = <!--T:136--><br />
<br />
<!--T:137--><br />
Keybindings (also known as hotkeys or macros), are in many respects very similar to aliases. However, instead of typing in what you want to be done (maybe including additional parameters) and pressing Enter, you simply hit a single key (or combination of keys) to let Mudlet do the work.<br />
<br />
<!--T:138--><br />
Example - You don’t drink tea, you sip it!<br />
You’re participating in an in-game tea sipping contest. The winner is the first person to sip an Earl Grey, should the quiz-master make a vague reference to a series of tubes, or a Ceylon Mint, if he begins talking about the specific theory of relativity. In order to give us a competitive advantage, we will define two keybindings:<br />
<br />
<!--T:139--><br />
HOTKEY: F1<br />
command on button down: sip earl gray<br />
<br />
<!--T:140--><br />
HOTKEY: F2<br />
command on button down: sip ceylon mint<br />
Now you just have to listen, or rather read, carefully and hit either F1 or F2 to claim that prize.<br />
<br />
<!--T:141--><br />
Another practical use for keybindings would be creating a so-called "targeting system", which is especially useful for grinding down armies of pumpkin-men in games without auto-attack. See the Variables chapter for further details.<br />
<br />
<!--T:142--><br />
Example instructions on how to make a keybinding (for a set of settings for binding the keypad):<br />
<br />
<!--T:198--><br />
# Click the '''Keys''' button: [[File:Keys button.jpg]] <br />
# If you wish to group them together, click the '''Add Group''' button<br />
# Then name your group, ''Keypad'' for instance<br />
# With the group selected now click the '''Add Item''' button<br />
# Name it, let's say ''North'', in the '''Name:''' widget<br />
# If you only need a single command, like ''north'' for our example, place it into the '''Command:''' widget, otherwise skip to step 9<br />
# Click the '''Grab New Key''' button<br />
# Click the '''button sequence''' you want to use for your keybinding, ''keypad 8'' for north<br />
# Now if you need additional code to execute when you click your keybinding, or want more complicated code, place it into the giant code box.<br />
# Click the '''Save Item''' button if done or '''New Item''' button if not.<br />
# Click the '''Activate''' button when finished to make sure they work.<br />
<br />
<!--T:199--><br />
Here is a link to the resulting keybinding XML file on the forums: [http://forums.mudlet.org/viewtopic.php?f=6&t=2163]<br />
<br />
<br />
<br />
<br />
</translate><br />
<span id="timers"></span><br />
<translate><br />
<br />
= Timers = <!--T:143--><br />
<br />
<!--T:144--><br />
Timers, as the name suggests, can be used to execute a specific command at a certain time, after a certain time or once every so often. They can be used by clicking in the "timer" editor, or direcly in your script.<br />
<br />
<!--T:200--><br />
To use a simple timer that does something after a period, write like this:<br />
<br />
<!--T:145--><br />
<syntaxhighlight lang="lua"><br />
tempTimer(seconds, [[code]])<br />
</syntaxhighlight><br />
<br />
<!--T:201--><br />
Seconds needs to be a number, the time until the timer starts. Code can be any commands which you want executed then.<br />
<br />
<!--T:202--><br />
{{note}} Seconds can be a decimal, so 0.5 for half a second, or 1 for a full second will both work as expected.<br />
<br />
<!--T:146--><br />
Here's a finished example which you can copy and put in your code directly:<br />
<br />
<!--T:147--><br />
<syntaxhighlight lang="lua"><br />
-- this timer will greet you exactly 2 seconds after it was made<br />
tempTimer(2, [[ echo("hello!\n") ]])<br />
</syntaxhighlight><br />
<br />
<!--T:203--><br />
You can combine both normal and timed commands, for example as code in an alias or keybinding:<br />
<br />
<!--T:204--><br />
<syntaxhighlight lang="lua"><br />
-- this code will let you go north immediately, then go east after 2 seconds <br />
send("n")<br />
tempTimer(2, [[ send("e") ]])<br />
</syntaxhighlight><br />
<br />
<!--T:148--><br />
{{note}} All timers which are made at the same time, will start counting from this common point in time, not relative to each other - so if you want to make one timer go off 1 second after another, '''don't do this''':<br />
<br />
<!--T:149--><br />
<syntaxhighlight lang="lua"><br />
-- incorrect:<br />
tempTimer(1, [[ echo("hello!\n") ]])<br />
tempTimer(1, [[ echo("how are you?\n") ]])<br />
</syntaxhighlight><br />
<br />
<!--T:150--><br />
Both of these timers will go off at once, because both started together, right away! Instead, '''do this''':<br />
<br />
<!--T:151--><br />
<syntaxhighlight lang="lua"><br />
-- correct:<br />
tempTimer(1, [[ echo("hello!\n") ]])<br />
tempTimer(2, [[ echo("how are you?\n") ]])<br />
</syntaxhighlight><br />
<br />
<!--T:205--><br />
{{note}} If you do not want to put all your timed code in <nowiki>[[ brackets ]]</nowiki> there is another way of writing the same example. (This is available since Mudlet 3.5)<br />
<br />
<!--T:206--><br />
<syntaxhighlight lang="lua"><br />
-- this timer will greet you exactly 2 seconds after it was made<br />
tempTimer(2, function() echo("hello!\n") end)<br />
</syntaxhighlight><br />
<br />
<!--T:152--><br />
That's it for the basics of scriptable timers in Mudlet. Want to know more? Here is a '''[[Special:MyLanguage/Manual:Technical Manual#Timer Engine|full description of timers in Mudlet]]'''.<br />
<br />
= Buttons = <!--T:153--><br />
<br />
<!--T:154--><br />
You can use Mudlet to create simple buttons on your screen without much coding at all - you can attach button bars to the top, left or right side of the screen. Each of these locations can contain an infinite number of button bars that are shown when active or hidden when inactive. You can also create drop-down menus or or two-state buttons - ones that you can click on and they stay pressed down.<br />
<br />
<!--T:155--><br />
To get started with buttons, '''make a group''' (buttons have to be in a group to show) and add buttons inside them. Active buttons or groups to make them be visible. Here's an example - by making a new group and a button inside it, and activating both, we got a button to spawn:<br />
<br />
<!--T:156--><br />
[[File:Buttons Start.png|1000px|center|]]<br />
<br />
<!--T:157--><br />
Buttons show '''in the order they appear in''' - so if you'd like one button to be above another, just drag it visually in the editor!<br />
<br />
<br />
<br />
== Menus == <!--T:158--><br />
<br />
<!--T:159--><br />
An important use case for buttons is to have various menus which contain a number of checkbox buttons or sub menus in order to quickly set various scripting configuration or other options in your scripts. To start a menu of buttons, create another group inside your toolbar group and add individual buttons inside it, like so:<br />
<br />
<!--T:160--><br />
[[File:Buttons Menu.png|center|]]<br />
<br />
<!--T:161--><br />
To change the side of Mudlet that the buttons use, change the '''Dock area <side>''' option and save. You can also make buttons align themselves top to bottom or left to right with the '''Orientation <horizontal or vertical>''' option.<br />
<br />
<!--T:162--><br />
[[File:Changing button group position.png|center|]]<br />
<br />
<br />
<br />
== Making buttons do stuff == <!--T:163--><br />
<br />
<!--T:164--><br />
Buttons are half as useful only being there. You can also make them do commands for you for when you press them! To make a button do your command, or alias, or anything - type it into the ''Command on Button Down'' field. Pressing the button will do that command then:<br />
<br />
<!--T:165--><br />
[[File:Button command.png|center|]]<br />
<br />
<!--T:166--><br />
You can also make a button do two things, toggling between each. To do that, '''enable the ''Push Down Button''''' option, and type the command you'd like your button to do when it's released in the ''Command on Button Up'' field. <br />
<br />
<!--T:167--><br />
[[File:Alternating button.png|center|]]<br />
<br />
</translate><br />
{{note}}<br />
<translate> <!--T:168--><br />
If you'd like to include & in the button name, put double && - a single & will act as a mnemonic to underline the shortcut letter.<br />
<br />
<br />
<br />
== Coloring & customizing buttons == <!--T:169--><br />
<br />
<!--T:170--><br />
To change how your buttons look, you put descriptions into the ''CSS Style Sheet'' field, in the format of '''<a word describing something>: <how it should look>;'''. For example, if you'd like to make the button be red, put ''background-color: red;'' into the CSS box:<br />
<br />
<!--T:171--><br />
[[File:Red button.png|center|]]<br />
<br />
<!--T:172--><br />
A full list of names you can use to customize your buttons view is [https://doc.qt.io/qt-5/stylesheet-reference.html available here]. Take note of how that page has the descriptions inside {} brackets - you don't need them, only paste what's inside them in Mudlet.<br />
<br />
<!--T:173--><br />
Applying some skills, we can make our buttons look much more aesthetic:<br />
<br />
<!--T:174--><br />
[[File:Sexy Buttons.png|center|]]<br />
<br />
<!--T:175--><br />
This was the code used, feel free to start your buttons off with it:<br />
<br />
<!--T:176--><br />
<syntaxhighlight lang="lua"><br />
color: white; background-color: orange; font-size: 12px;<br />
padding: 6px;<br />
border-radius: 5px;<br />
</syntaxhighlight><br />
<br />
<br />
Users with OS Windows 10 may find that for Mudlet versions 4.11+, the ''background-color: <colour>;'' is not changing the background as expected. This can be fixed by changing the border of the button. For example ''border: none;''. Although that may destroy the size of button and it has to be set manualy. To achieve somehow similar size to default buttons you can use something like this:<br />
<br />
<syntaxhighlight lang="lua"><br />
background-color: <your_colour>;<br />
border: 1px solid gray;<br />
width: 90px; height: 25px;<br />
margin: 1px;<br />
font-size: 14px;<br />
</syntaxhighlight><br />
<br />
<br />
== Managed layouts == <!--T:177--><br />
<br />
<!--T:178--><br />
To get your buttons to align into rows or columns (that depends on their orientation), add a number to the ''Number of columns or rows'' field. Here's an example with two columns on the left:<br />
<br />
<!--T:179--><br />
[[File:Two row alignment.png|center|]]<br />
<br />
<!--T:180--><br />
Here's another example with three columns on the left:<br />
<br />
<!--T:181--><br />
[[File:Three column alignment.png|center|]]<br />
<br />
</translate><br />
{{note}}<br />
<translate> <!--T:182--><br />
You can change how your buttons are aligned within rows by clicking on the button group - it will cycle through different possible configurations for you.<br />
<br />
<!-- Zooka 20230712 WIP : working on https://github.com/Mudlet/Mudlet/issues/5067 --><br />
== Making Buttons with Labels ==<br />
<br />
Labels can also be used to make buttons. They are far more flexible and you can design [https://www.mudlet.org/media/ almost any UI] you can dream up considering they are simply [[Manual:Geyser#Clickable_images|clickable images]].<br />
<br />
We'll start by making twelve buttons along the top of our screen.<br />
<br />
<nowiki><br />
-- set a 10% margin from the top border to provide space<br />
local width, height = getMainWindowSize()<br />
setBorderTop(height/10)<br />
<br />
-- create some variable space so we don't pollute global variables<br />
MyButtons = {}<br />
<br />
-- create a label for the entire margin, for now<br />
MyButtons.Top = Geyser.Label:new({<br />
name = "MyButtons.Top",<br />
x = 0, y = 0,<br />
width = "100%",<br />
height = "10%",<br />
})<br />
<br />
-- create a horizontal box to organise the buttons equally<br />
MyButtons.TopHBox = Geyser.HBox:new({<br />
name = "MyButtons.TopHBox",<br />
x = 0, y = 0,<br />
width = "100%",<br />
height = "100%",<br />
},MyButtons.Top)<br />
<br />
-- add some buttons to the HBox using a Geyser label<br />
for i=1,12 do<br />
MyButtons["MyButton"..i] = Geyser.Label:new({<br />
name = "MyButtons.Button"..i,<br />
},MyButtons.TopHBox)<br />
MyButtons["MyButton"..i]:echo("<center>My Button "..i)<br />
end<br />
</nowiki><br />
<br />
[[File:Label-button-tutorial-1.png|thumb|center|Basic top button layout, made with labels.]]<br />
<br />
The main function creating the button labels is Geyser.Label. You should now see the results as above. A bit plain, you could add some CSS to spark things up a bit.<br />
<br />
<nowiki><br />
-- add some buttons to the HBox using a Geyser label<br />
for i=1, 12 do<br />
MyButtons["MyButton"..i] = Geyser.Label:new({<br />
name = "MyButtons.Button"..i,<br />
},MyButtons.TopHBox)<br />
MyButtons["MyButton"..i]:echo("<center>My Button "..i)<br />
<br />
-- colour my buttons with CSS<br />
MyButtons["MyButton"..i]:setStyleSheet([[<br />
background-color: rgba(135,206,250,100);<br />
border-style: solid;<br />
border-width: 1px;<br />
border-color: white;<br />
border-radius: 5px;<br />
margin: 5px;<br />
qproperty-wordWrap: true;<br />
]])<br />
end<br />
</nowiki><br />
<br />
Much better. But currently they are just twelve pretty labels that don't perform any function. Let's make them clickable with [https://www.mudlet.org/geyser/files/geyser/GeyserLabel.html#Geyser.Label:setClickCallback setClickCallback]<br />
<br />
[https://www.mudlet.org/geyser/files/geyser/GeyserLabel.html#Geyser.Label:setClickCallback setClickCallback] assigns a function to a Geyser label that will be called when the mouse is clicked on the label. This function has similar methods for double clicking, hovering, etc.. all of which can be found in the [https://www.mudlet.org/geyser/files/geyser/GeyserLabel.html Geyser manual]. Let's keep it straightforward for now with a single click. Consider the following addition;<br />
<br />
<nowiki><br />
-- add some buttons to the HBox using a Geyser label<br />
for i=1,12 do<br />
MyButtons["MyButton"..i] = Geyser.Label:new({<br />
name = "MyButtons.Button"..i,<br />
},MyButtons.TopHBox)<br />
MyButtons["MyButton"..i]:echo("<center>My Button "..i)<br />
<br />
-- colour my buttons with CSS<br />
MyButtons["MyButton"..i]:setStyleSheet([[<br />
background-color: rgba(135,206,250,100);<br />
border-style: solid;<br />
border-width: 1px;<br />
border-color: white;<br />
border-radius: 5px;<br />
margin: 5px;<br />
qproperty-wordWrap: true;<br />
]])<br />
<br />
-- make our buttons clickable<br />
MyButtons["MyButton"..i]:setClickCallback(function() echo("My Button " ..i.." clicked!\n") end)<br />
end<br />
</nowiki><br />
[[File:Label-button-tutorial-2.png|thumb|center|CSS labels acting as clickable buttons.]]<br />
<br />
You should now be able to click the button and see the echo to the main screen.<br />
<br />
=== Adjustable Containers for Labels === <br />
<br />
[[Manual:Geyser#Adjustable.Container|Adjustable Containers]] are a Geyser element that provides a flexible, user configurable, dockable window. Let's move our buttons to one of these containers and see what else we can do.<br />
<br />
<nowiki><br />
-- create some variable space so we don't pollute global variables<br />
MyButtons = {}<br />
<br />
-- create an adjustable container for more flexibility<br />
MyButtons.Top = Adjustable.Container:new({<br />
name = "MyButtons.Top",<br />
x = 0, y = 0,<br />
width = "100%",<br />
height = "10%",<br />
})<br />
<br />
-- create a horizontal box to organise the buttons equally<br />
MyButtons.TopHBox = Geyser.HBox:new({<br />
name = "MyButtons.TopHBox",<br />
x = 0, y = 0,<br />
width = "100%",<br />
height = "100%",<br />
},MyButtons.Top)<br />
<br />
-- add some buttons to the HBox using a Geyser label<br />
for i=1, 12 do<br />
MyButtons["MyButton"..i] = Geyser.Label:new({<br />
name = "MyButtons.Button"..i,<br />
},MyButtons.TopHBox)<br />
MyButtons["MyButton"..i]:echo("<center>My Button "..i)<br />
<br />
-- colour my buttons with CSS<br />
MyButtons["MyButton"..i]:setStyleSheet([[<br />
background-color: rgba(135,206,250,100);<br />
border-style: solid;<br />
border-width: 1px;<br />
border-color: white;<br />
border-radius: 5px;<br />
margin: 5px;<br />
qproperty-wordWrap: true;<br />
]])<br />
<br />
-- make our buttons clickable<br />
MyButtons["MyButton"..i]:setClickCallback(function() echo("My Button " ..i.." clicked!\n") end)<br />
end<br />
</nowiki><br />
<br />
[[File:Label-button-tutorial-3.png|thumb|center|Labels in an adjustable container, docked to the top border.]]<br />
<br />
We removed the setBorderTop code because the adjustable container can be docked to a border by right clicking on the title bar and a margin is automatically created. It is docked to the top border in this example.<br />
<br />
The container can be resized and moved around or perhaps changed to a VBox for slick left and right border docking.<br />
<br />
[[File:Label-button-tutorial-4.png|thumb|center|Resized and undocked adjustable container with clickable labels acting as buttons.]]<br />
<br />
This example can be further expanded to add images to the labels, highlighting when hovering over labels or even multi-state buttons with variables to track the state. Your imagination is the only limit.<br />
<br />
= Built-in aliases = <!--T:183--><br />
<br />
<!--T:184--><br />
The following aliases are available by default in new Mudlet profiles.<br />
<br />
<!--T:185--><br />
{| class="wikitable"<br />
|-<br />
! Alias !! Description !! Examples<br />
|-<br />
| lua || Run Lua code from the input line. || lua print("hello")<br>lua 2+2<br>lua clearWindow()<br />
|-<br />
| `echo || Simulate text from the game to test your triggers.<br>You can use $ for a new line. || `echo You see a rabbit cross the road.<br>`echo line1$line2<br />
|}<br />
<br />
<!--T:186--><br />
If an alias on the list isn't working for you - try copying it from a new profile, since existing profiles will not get new aliases as they're introduced to Mudlet.<br />
<br />
= Misc examples = <!--T:191--><br />
<br />
<!--T:192--><br />
Here are some more miscellaneous examples.<br />
<br />
<!--T:193--><br />
'''Game syntax''': ''get coins from corpse'' and also ''get coins from corpse 3''.<br />
'''Alias Pattern''': '''^gcc(?:\s(\d+))?$''' (can accept simply ''gcc'' and also ''gcc 3'' for example).<br />
<syntaxhighlight lang="lua"><br />
send("get coins from corpse " .. (matches[2] or "") )<br />
</syntaxhighlight><br />
<br />
<!--T:194--><br />
'''Game syntax''': ''unlock northwest with steel key''<br />
'''Alias Pattern''': '''^un (\w+) (.*)$'''<br />
<syntaxhighlight lang="lua"><br />
send("unlock " .. matches[2] .. " with " .. matches[3] )<br />
</syntaxhighlight><br />
<br />
<!--T:195--><br />
See also: [[Special:MyLanguage/Manual:Technical Manual|Mudlet Technical Manual]]<br />
<br />
<!--T:196--><br />
[[Category:Mudlet Manual]]<br />
</translate></div>Demonnichttps://wiki.mudlet.org/index.php?title=Talk:Generic_Mapper_Additions&diff=20544Talk:Generic Mapper Additions2023-09-22T13:22:27Z<p>Demonnic: </p>
<hr />
<div>These should probably be in alphabetical order --[[User:Dt192|Dt192]] ([[User talk:Dt192|talk]]) 20:33, 13 September 2023 (UTC)<br />
<br />
That seems reasonable, I'm certainly not against it if someone wants to take that up --[[User:Demonnic|Demonnic]] ([[User talk:Demonnic|talk]]) 21:17, 13 September 2023 (UTC)<br />
<br />
Done. --[[User:Zooka|Zooka]] ([[User talk:Zooka|talk]]) 02:33, 14 September 2023 (UTC)<br />
:I already did it, but thanks. I'm surprised the moderation extension doesn't show a `Pending changes` message on pages that have pending changes to avoid people's time being wasted. Maybe it's time to find a better solution or to remove moderation if we can't keep on top of it. --[[User:Dt192|Dt192]] ([[User talk:Dt192|talk]]) 07:19, 14 September 2023 (UTC)<br />
:I don't see us getting rid of moderation, given the amount of spam I still have to reject every day. We're open to new/alternative wiki options but we need to be able to transfer what we have without having to start over, there's way too much here to just start again. --[[User:Demonnic|Demonnic]] ([[User talk:Demonnic|talk]]) 13:22, 22 September 2023 (UTC)</div>Demonnichttps://wiki.mudlet.org/index.php?title=Talk:Generic_Mapper_Additions&diff=20531Talk:Generic Mapper Additions2023-09-13T21:18:04Z<p>Demonnic: </p>
<hr />
<div>These should probably be in alphabetical order --[[User:Dt192|Dt192]] ([[User talk:Dt192|talk]]) 20:33, 13 September 2023 (UTC)<br />
<br />
That seems reasonable, I'm certainly not against it if someone wants to take that up --[[User:Demonnic|Demonnic]] ([[User talk:Demonnic|talk]]) 21:17, 13 September 2023 (UTC)</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:Mudlet_Object_Functions&diff=20520Manual:Mudlet Object Functions2023-08-24T21:41:09Z<p>Demonnic: /* isPrompt */</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Mudlet API documentation for functions to manipulate Mudlet's scripting objects - triggers, aliases, and so forth.}}<br />
= Mudlet Object Functions =<br />
Collection of functions to manipulate Mudlet's scripting objects - triggers, aliases, and so forth.<br />
<br />
==addCmdLineSuggestion==<br />
;addCmdLineSuggestion([name], suggestion)<br />
: Add suggestion for tab completion for specified command line.<br />
<br />
: For example, start typing ''he'' and hit ''TAB'' until ''help'' appears in command line.<br />
: Non-word characters are skipped (this is the reason why they can't be added at start of suggestion), therefore it's also possible to type: ''/he'' and hit ''TAB''.<br />
<br />
: See also: [[Manual:Lua_Functions#clearCmdLineSuggestions|clearCmdLineSuggestions()]], [[Manual:Lua_Functions#removeCmdLineSuggestion|removeCmdLineSuggestion()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
;Parameters<br />
* ''name'': optional command line name, if skipped main command line will be used<br />
* ''suggestion'' - suggestion as a single word to add to tab completion (only the following are allowed: ''0-9A-Za-z_'')<br />
<br />
Example:<br />
<syntaxhighlight lang="lua"><br />
addCmdLineSuggestion("help")<br />
<br />
local suggestions = {"Pneumonoultramicroscopicsilicovolcanoconiosis", "supercalifragilisticexpialidocious", "serendipitous"}<br />
for _, suggestion in ipairs(suggestions) do<br />
addCmdLineSuggestion(suggestion)<br />
end<br />
</syntaxhighlight><br />
<br />
==adjustStopWatch==<br />
;adjustStopWatch(watchID/watchName, amount)<br />
: Adjusts the elapsed time on the stopwatch forward or backwards by the amount of time. It will work even on stopwatches that are not running, and thus can be used to preset a newly created stopwatch with a negative amount so that it runs down from a negative time towards zero at the preset time.<br />
<br />
;Parameters<br />
* watchID (number) / watchName (string): The stopwatch ID you get with [[Manual:Lua_Functions#createStopWatch|createStopWatch()]] or the name given to that function or later set with [[Manual:Lua_Functions#setStopWatchName|setStopWatchName()]].<br />
* amount (decimal number): An amount in seconds to adjust the stopwatch by, positive amounts increase the recorded elapsed time.<br />
<br />
;Returns<br />
* true on success if the stopwatch was found and thus adjusted, or nil and an error message if not.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- demo of a persistent stopWatch used to real time a mission<br />
-- called with a positive number of seconds it will start a "missionStopWatch"<br />
-- unless there already is one in which case it will instead report on<br />
-- the deadline. use 'stopStopWatch("missionStopWatch")' when the mission<br />
-- is done and 'deleteStopWatch("missionStopWatch")' when the existing mission<br />
-- is to be disposed of. Until then repeated use of 'mission(interval)' will<br />
-- just give updates...<br />
function mission(time)<br />
local missionTimeTable = missionTimeTable or {}<br />
<br />
if createStopWatch("missionStopWatch") then<br />
adjustStopWatch("missionStopWatch", -tonumber(time))<br />
setStopWatchPersistence("missionStopWatch", true)<br />
missionTimeTable = getStopWatchBrokenDownTime("missionStopWatch")<br />
<br />
echo(string.format("Get cracking, you have %02i:%02i:%02i hg:m:s left.\n", missionTimeTable.hours, missionTimeTable.minutes, missionTimeTable.seconds))<br />
startStopWatch("missionStopWatch")<br />
else<br />
-- it already exists, so instead report what is/was the time on it<br />
--[=[ We know that the stop watch exists - we just need to find the ID<br />
so we can get the running detail which is only available from the getStopWatches()<br />
table and that is indexed by ID]=]<br />
for k,v in pairs(getStopWatches()) do<br />
if v.name == "missionStopWatch" then<br />
missionTimeTable = v<br />
end<br />
end<br />
if missionTimeTable.isRunning then<br />
if missionTimeTable.elapsedTime.negative then<br />
echo(string.format("Better hurry up, the clock is ticking on an existing mission and you only have %02i:%02i:%02i h:m:s left.\n", missionTimeTable.elapsedTime.hours, missionTimeTable.elapsedTime.minutes, missionTimeTable.elapsedTime.seconds))<br />
else<br />
echo(string.format("Bad news, you are past the deadline on an existing mission by %02i:%02i:%02i h:m:s !\n", missionTimeTable.elapsedTime.hours, missionTimeTable.elapsedTime.minutes, missionTimeTable.elapsedTime.seconds))<br />
end<br />
else<br />
if missionTimeTable.elapsedTime.negative then<br />
echo(string.format("Well done! You have already completed a mission %02i:%02i:%02i h:m:s before the deadline ...\n", missionTimeTable.elapsedTime.hours, missionTimeTable.elapsedTime.minutes, missionTimeTable.elapsedTime.seconds))<br />
else<br />
echo(string.format("Uh oh! You failed to meet the deadline on an existing mission by %02i:%02i:%02i h:m:s !\n", missionTimeTable.elapsedTime.hours, missionTimeTable.elapsedTime.minutes, missionTimeTable.elapsedTime.seconds))<br />
end<br />
end<br />
end<br />
end<br />
<br />
<br />
-- in use:<br />
lua mission(60*60)<br />
Get cracking, you have 01:00:00 h:m:s left.<br />
<br />
lua mission(60*60)<br />
Better hurry up, the clock is ticking on an existing mission and you only have 00:59:52 h:m:s left.<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.4}}<br />
<br />
==appendScript==<br />
;appendScript(scriptName, luaCode, [occurrence])<br />
: Appends Lua code to the script "scriptName". If no occurrence given it sets the code of the first found script.<br />
<br />
: See also: [[Manual:Lua_Functions#permScript|permScript()]], [[Manual:Lua_Functions#enableScript|enableScript()]], [[Manual:Lua_Functions#disableScript|disableScript()]], [[Manual:Lua_Functions#getScript|getScript()]], [[Manual:Lua_Functions#setScript|setScript()]]<br />
<br />
;Returns<br />
* a unique id number for that script.<br />
<br />
;Parameters<br />
* ''scriptName'': name of the script<br />
* ''luaCode'': scripts luaCode to append<br />
* ''occurence'': (optional) the occurrence of the script in case you have many with the same name<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- an example of appending the script lua code to the first occurrence of "testscript"<br />
appendScript("testscript", [[echo("This is a test\n")]], 1)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.8}}<br />
<br />
==appendCmdLine==<br />
;appendCmdLine([name], text)<br />
: Appends text to the main input line.<br />
: See also: [[Manual:Lua_Functions#printCmdLine|printCmdLine()]], [[#clearCmdLine|clearCmdLine()]]<br />
<br />
;Parameters<br />
* ''name'': (optional) name of the command line. If not given, the text will be appended to the main commandline.<br />
* ''text'': text to append<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- adds the text "55 backpacks" to whatever is currently in the input line<br />
appendCmdLine("55 backpacks")<br />
<br />
-- makes a link, that when clicked, will add "55 backpacks" to the input line<br />
echoLink("press me", "appendCmdLine'55 backpack'", "Press me!")<br />
</syntaxhighlight><br />
<br />
==clearCmdLine==<br />
;clearCmdLine([name])<br />
: Clears the input line of any text that's been entered.<br />
: See also: [[Manual:Lua_Functions#printCmdLine|printCmdLine()]]<br />
<br />
;Parameters<br />
* ''name'': (optional) name of the command line. If not given, the main commandline's text will be cleared.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- don't be evil with this!<br />
clearCmdLine()<br />
</syntaxhighlight><br />
<br />
==clearCmdLineSuggestions==<br />
;clearCmdLineSuggestions([name])<br />
<br />
: Clears all suggestions for command line.<br />
<br />
: See also: [[Manual:Lua_Functions#addCmdLineSuggestion|addCmdLineSuggestion()]], [[Manual:Lua_Functions#removeCmdLineSuggestion|removeCmdLineSuggestion()]]<br />
<br />
;Parameter<br />
* ''name'': (optional) name of the command line. If not given the main commandline's suggestions will be cleared.<br />
<br />
<syntaxhighlight lang="lua"><br />
clearCmdLineSuggestions()<br />
</syntaxhighlight><br />
<br />
==createStopWatch==<br />
;createStopWatch([name], [start immediately])<br />
;createStopWatch([start immediately])<br />
Before Mudlet 4.4.0:<br />
;createStopWatch()<br />
<br />
: This function creates a stopwatch, a high resolution time measurement tool. Stopwatches can be started, stopped, reset, asked how much time has passed since the stop watch has been started and, following an update for Mudlet 4.4.0: be adjusted, given a name and be made persistent between sessions (so can time real-life things). Prior to 4.4.0 the function took no parameters '''and the stopwatch would start automatically when it was created'''.<br />
<br />
;Parameters:<br />
* ''start immediately'' (bool) used to override the behaviour prior to Mudlet 4.4.0 so that if it is the ''only'' argument then a ''false'' value will cause the stopwatch to be created but be in a ''stopped'' state, however if a name parameter is provided then this behaviour is assumed and then a ''true'' value is required should it be desired for the stopwatch to be started on creation. This difference between the cases with and without a name argument is to allow for older scripts to continue to work with 4.4.0 or later versions of Mudlet without change, yet to allow for more functionality - such as presetting a time when the stopwatch is created but not to start it counting down until some time afterwards - to be performed as well with a named stopwatch.<br />
<br />
* ''name'' (string) a ''unique'' text to use to identify the stopwatch.<br />
<br />
;Returns:<br />
* the ID (number) of a stopwatch; or, from '''4.4.0''': a nil + error message if the name has already been used.<br />
<br />
: See also: [[Manual:Lua_Functions#startStopWatch|startStopWatch()]], [[Manual:Lua_Functions#stopStopWatch|stopStopWatch()]], [[Manual:Lua_Functions#resetStopWatch|resetStopWatch()]], [[Manual:Lua_Functions#getStopWatchTime|getStopWatchTime()]] or, from 4.4.0: [[Manual:Lua_Functions#adjustStopWatch|adjustStopWatch()]], [[Manual:Lua_Functions#deleteStopWatch|deleteStopWatch()]], [[Manual:Lua_Functions#getStopWatches|getStopWatches()]], [[Manual:Lua_Functions#getStopWatchBrokenDownTime|getStopWatchBrokenDownTime()]], [[Manual:Lua_Functions#setStopWatchName|setStopWatchName()]], [[Manual:Lua_Functions#setStopWatchPersistence|setStopWatchPersistence()]]<br />
<br />
;Example<br />
: (Prior to Mudlet 4.4.0) in a global script you can create all stop watches that you need in your system and store the respective stopWatch-IDs in global variables:<br />
<syntaxhighlight lang="lua"><br />
fightStopWatch = fightStopWatch or createStopWatch() -- create, or re-use a stopwatch, and store the watchID in a global variable to access it from anywhere<br />
<br />
-- then you can start the stop watch in some trigger/alias/script with:<br />
startStopWatch(fightStopWatch)<br />
<br />
-- to stop the watch and measure its time in e.g. a trigger script you can write:<br />
fightTime = stopStopWatch(fightStopWatch)<br />
echo("The fight lasted for " .. fightTime .. " seconds.")<br />
resetStopWatch(fightStopWatch)<br />
</syntaxhighlight><br />
<br />
: (From Mudlet 4.4.0) in a global script you can create all stop watches that you need in your system with unique names:<br />
<syntaxhighlight lang="lua"><br />
createStopWatch("fightStopWatch") -- creates the stopwatch or returns nil+msg if it already exists<br />
<br />
-- then you can start the stop watch (if it is not already started) in some trigger/alias/script with:<br />
startStopWatch("fightStopWatch")<br />
<br />
-- to stop the watch and measure its time in e.g. a trigger script you can write:<br />
fightTime = stopStopWatch("fightStopWatch")<br />
echo("The fight lasted for " .. fightTime .. " seconds.")<br />
resetStopWatch("fightStopWatch")<br />
</syntaxhighlight><br />
<br />
:You can also measure the elapsed time without having to stop the stop watch (equivalent to getting a ''lap-time'') with [[#getStopWatchTime|getStopWatchTime()]].<br />
<br />
{{note}} it's best to re-use stopwatch IDs if you can for Mudlet prior to 4.4.0 as they cannot be deleted, so creating more and more would use more memory. From 4.4.0 the revised internal design has been changed such that there are no internal timers created for each stopwatch - instead either a timestamp or a fixed elapsed time record is used depending on whether the stopwatches is running or stopped so that there are no "moving parts" in the later design and less resources are used - and they can be removed if no longer required.<br />
<br />
==deleteAllNamedTimers==<br />
; deleteAllNamedTimers(userName)<br />
<br />
:Deletes all named timers and prevents them from firing any more. Information is deleted and cannot be retrieved.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]], [[Manual:Lua_Functions#stopNamedTimer|stopNamedTimer()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
deleteAllNamedTimers("Demonnic") -- emergency stop or debugging situation, most likely.<br />
</syntaxhighlight><br />
<br />
==deleteNamedTimer==<br />
; success = deleteNamedTimer(userName, handlerName)<br />
<br />
:Deletes a named timer with name handlerName and prevents it from firing any more. Information is deleted and cannot be retrieved.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]], [[Manual:Lua_Functions#stopNamedTimer|stopNamedTimer()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
* ''handlerName:''<br />
: The name of the handler to stop. Same as used when you called [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]]<br />
<br />
;Returns <br />
* true if successful, false if it didn't exist<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local deleted = deleteNamedTimer("Demonnic", "DemonVitals")<br />
if deleted then<br />
cecho("DemonVitals deleted forever!!")<br />
else<br />
cecho("DemonVitals doesn't exist and so could not be deleted.")<br />
end<br />
</syntaxhighlight><br />
<br />
==deleteStopWatch==<br />
;deleteStopWatch(watchID/watchName)<br />
<br />
: This function removes an existing stopwatch, whether it only exists for this session or is set to be otherwise saved between sessions by using [[Manual:Lua_Functions#setStopWatchPersistence|setStopWatchPersistence()]] with a ''true'' argument. <br />
<br />
;Parameters<br />
* ''watchID'' (number) / ''watchName'' (string): The stopwatch ID you get with [[Manual:Lua_Functions#createStopWatch|createStopWatch()]] or the name given to that function or later set with [[Manual:Lua_Functions#setStopWatchName|setStopWatchName()]].<br />
<br />
;Returns:<br />
* ''true'' if the stopwatch was found and thus deleted, or ''nil'' and an error message if not - obviously using it twice with the same argument will fail the second time unless another one with the same name or ID was recreated before the second use. Note that an empty string as a name ''will'' find the lowest ID numbered ''unnamed'' stopwatch and that will then find the next lowest ID number of unnamed ones until there are none left, if used repetitively!<br />
<br />
<syntaxhighlight lang="lua"><br />
lua MyStopWatch = createStopWatch("stopwatch_mine")<br />
true<br />
<br />
lua display(MyStopWatch)<br />
4<br />
<br />
lua deleteStopWatch(MyStopWatch)<br />
true<br />
<br />
lua deleteStopWatch(MyStopWatch)<br />
nil<br />
<br />
"stopwatch with id 4 not found"<br />
<br />
lua deleteStopWatch("stopwatch_mine")<br />
nil<br />
<br />
"stopwatch with name "stopwatch_mine" not found"<br />
</syntaxhighlight><br />
<br />
: See also: [[Manual:Lua_Functions#createStopWatch|createStopWatch()]],<br />
<br />
{{MudletVersion|4.4}}<br />
<br />
{{note}} Stopwatches that are not set to be persistent will be deleted automatically at the end of a session (or if [[Manual:Miscellaneous_Functions#resetProfile|resetProfile()]] is called).<br />
<br />
==removeCmdLineSuggestion==<br />
;removeCmdLineSuggestion([name], suggestion)<br />
: Remove a suggestion for tab completion for specified command line.<br />
<br />
: See also: [[Manual:Lua_Functions#addCmdLineSuggestion|addCmdLineSuggestion()]], [[Manual:Lua_Functions#clearCmdLineSuggestions|clearCmdLineSuggestions()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
;Parameters<br />
* ''name'': optional command line name, if skipped main command line will be used<br />
* ''suggestion'' - text to add to tab completion, non words characters at start and end of word should not be used (all characters except: `0-9A-Za-z_`)<br />
<br />
Example:<br />
<syntaxhighlight lang="lua"><br />
removeCmdLineSuggestion("help")<br />
</syntaxhighlight><br />
<br />
==disableAlias==<br />
;disableAlias(name)<br />
:Disables/deactivates the alias by its name. If several aliases have this name, they'll all be disabled. If you disable an alias group, all the aliases inside the group will be disabled as well.<br />
<br />
: See also: [[#enableAlias|enableAlias()]], [[#disableTrigger|disableTrigger()]], [[#disableTimer|disableTimer()]], [[#disableKey|disableKey()]], [[#disableScript|disableScript()]].<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name of the alias. Passed as a string.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
--Disables the alias called 'my alias'<br />
disableAlias("my alias")<br />
</syntaxhighlight><br />
<br />
==disableKey==<br />
;disableKey(name)<br />
:Disables key a key (macro) or a key group. When you disable a key group, all keys within the group will be implicitly disabled as well.<br />
<br />
: See also: [[#enableKey|enableKey()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name of the key or group to identify what you'd like to disable.<br />
<br />
;Examples<br />
<br />
<syntaxhighlight lang="lua"><br />
-- you could set multiple keys on the F1 key and swap their use as you wish by disabling and enabling them<br />
disableKey("attack macro")<br />
disableKey("jump macro")<br />
enableKey("greet macro")<br />
</syntaxhighlight><br />
<br />
==disableScript==<br />
;disableScript(name)<br />
:Disables a script that was previously enabled. Note that disabling a script only stops it from running in the future - it won't "undo" anything the script has made, such as labels on the screen.<br />
<br />
: See also: [[#permScript|permScript()]], [[#appendScript|appendScript()]], [[#enableScript|enableScript()]], [[#getScript|getScript()]], [[#setScript|setScript()]]<br />
<br />
;Parameters<br />
* ''name'': name of the script.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--Disables the script called 'my script'<br />
disableScript("my script")<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.8}}<br />
<br />
==disableTimer==<br />
;disableTimer(name)<br />
:Disables a timer from running it’s script when it fires - so the timer cycles will still be happening, just no action on them. If you’d like to permanently delete it, use [[Manual:Lua_Functions#killTrigger|killTrigger]] instead.<br />
<br />
: See also: [[#enableTimer|enableTimer()]], [[#disableTrigger|disableTrigger()]], [[#disableAlias|disableAlias()]], [[#disableKey|disableKey()]], [[#disableScript|disableScript()]].<br />
<br />
;Parameters<br />
* ''name:''<br />
: Expects the timer ID that was returned by [[Manual:Lua_Functions#tempTimer|tempTimer]] on creation of the timer or the name of the timer in case of a GUI timer.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--Disables the timer called 'my timer'<br />
disableTimer("my timer")<br />
</syntaxhighlight><br />
<br />
==disableTrigger==<br />
;disableTrigger(name)<br />
:Disables a permanent (one in the trigger editor) or a temporary trigger. When you disable a group, all triggers inside the group are disabled as well<br />
<br />
: See also: [[#enableTrigger|enableTrigger()]], [[#disableAlias|disableAlias()]], [[#disableTimer|disableTimer()]], [[#disableKey|disableKey()]], [[#disableScript|disableScript()]].<br />
<br />
;Parameters<br />
* ''name:''<br />
: Expects the trigger ID that was returned by [[Manual:Lua_Functions#tempTrigger|tempTrigger]] or other temp*Trigger variants, or the name of the trigger in case of a GUI trigger.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Disables the trigger called 'my trigger'<br />
disableTrigger("my trigger")<br />
</syntaxhighlight><br />
<br />
==enableAlias==<br />
;enableAlias(name)<br />
:Enables/activates the alias by it’s name. If several aliases have this name, they’ll all be enabled.<br />
<br />
: See also: [[#disableAlias|disableAlias()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: Expects the alias ID that was returned by [[Manual:Lua_Functions#tempAlias|tempAlias]] on creation of the alias or the name of the alias in case of a GUI alias.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--Enables the alias called 'my alias'<br />
enableAlias("my alias")<br />
</syntaxhighlight><br />
<br />
==enableKey==<br />
;enableKey(name)<br />
:Enables a key (macro) or a group of keys (and thus all keys within it that aren't explicitly deactivated).<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name of the group that identifies the key.<br />
<br />
<syntaxhighlight lang="lua"><br />
-- you could use this to disable one key set for the numpad and activate another<br />
disableKey("fighting keys")<br />
enableKey("walking keys")<br />
</syntaxhighlight><br />
{{note}} From Version '''3.10'' returns ''true'' if one or more keys or groups of keys were found that matched the name given or ''false'' if not; prior to then it returns ''true'' if there were '''any''' keys - whether they matched the name or not!<br />
<br />
==enableScript==<br />
;enableScript(name)<br />
:Enables / activates a script that was previously disabled. <br />
<br />
: See also: [[#permScript|permScript()]], [[#appendScript|appendScript()]], [[#disableScript|disableScript()]], [[#getScript|getScript()]], [[#setScript|setScript()]]<br />
<br />
;Parameters<br />
* ''name'': name of the script.<br />
<syntaxhighlight lang="lua"><br />
-- enable the script called 'my script' that you created in Mudlet's script section<br />
enableScript("my script")<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.8}}<br />
<br />
==enableTimer==<br />
;enableTimer(name)<br />
:Enables or activates a timer that was previously disabled. <br />
<br />
;Parameters<br />
* ''name:''<br />
: Expects the timer ID that was returned by [[Manual:Lua_Functions#tempTimer|tempTimer]] on creation of the timer or the name of the timer in case of a GUI timer.<br />
<syntaxhighlight lang="lua"><br />
-- enable the timer called 'my timer' that you created in Mudlets timers section<br />
enableTimer("my timer")<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- or disable & enable a tempTimer you've made<br />
timerID = tempTimer(10, [[echo("hi!")]])<br />
<br />
-- it won't go off now<br />
disableTimer(timerID)<br />
-- it will continue going off again<br />
enableTimer(timerID)<br />
</syntaxhighlight><br />
<br />
==enableTrigger==<br />
;enableTrigger(name)<br />
:Enables or activates a trigger that was previously disabled. <br />
<br />
;Parameters<br />
* ''name:''<br />
: Expects the trigger ID that was returned by [[Manual:Lua_Functions#tempTrigger|tempTrigger]] or by any other temp*Trigger variants, or the name of the trigger in case of a GUI trigger.<br />
<syntaxhighlight lang="lua"><br />
-- enable the trigger called 'my trigger' that you created in Mudlets triggers section<br />
enableTrigger("my trigger")<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- or disable & enable a tempTrigger you've made<br />
triggerID = tempTrigger("some text that will match in a line", [[echo("hi!")]])<br />
<br />
-- it won't go off now when a line with matching text comes by<br />
disableTrigger(triggerID)<br />
<br />
-- and now it will continue going off again<br />
enableTrigger(triggerID)<br />
</syntaxhighlight><br />
<br />
==exists==<br />
;exists(name/IDnumber, type)<br />
:Returns the number of things with the given name or number of the given type - and 0 if none are present. Beware that all numbers are true in Lua, including zero.<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name (as a string) or, from '''Mudlet 4.17.0''', the ID number of a single item, (which will be that returned by a ''temp*'' or ''perm*'' function to create such an item to identify the item).<br />
* ''type:''<br />
: The type can be 'alias', 'button' (Mudlet 4.10+), 'trigger', 'timer', 'keybind' (Mudlet 3.2+), or 'script' (Mudlet 3.17+).<br />
<br />
:See also: [[#isActive|isActive(...)]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo("I have " .. exists("my trigger", "trigger") .. " triggers called 'my trigger'!")<br />
</syntaxhighlight><br />
<br />
: You can also use this alias to avoid creating duplicate things, for example:<br />
<syntaxhighlight lang="lua"><br />
-- this code doesn't check if an alias already exists and will keep creating new aliases<br />
permAlias("Attack", "General", "^aa$", [[send ("kick rat")]])<br />
<br />
-- while this code will make sure that such an alias doesn't exist first<br />
-- we do == 0 instead of 'not exists' because 0 is considered true in Lua<br />
if exists("Attack", "alias") == 0 then<br />
permAlias("Attack", "General", "^aa$", [[send ("kick rat")]])<br />
end<br />
</syntaxhighlight><br />
<br />
: Especially helpful when working with [[Manual:Lua_Functions#permTimer|permTimer]]:<br />
<syntaxhighlight lang="lua"><br />
if not exists("My animation timer", "timer") then<br />
vdragtimer = permTimer("My animation timer", "", .016, onVDragTimer) -- 60fps timer!<br />
end<br />
<br />
enableTimer("My animation timer")<br />
</syntaxhighlight><br />
<br />
{{Note}} A positive ID number will return either a ''1'' or ''0'' value and not a lua boolean ''true'' or ''false'' as might otherwise be expected, this is for constancy with the way the function behaves for a name.<br />
<br />
==getButtonState==<br />
;getButtonState([ButtonNameOrID])<br />
:This function can be used within checkbox button scripts (2-state buttons) to determine the current state of the checkbox.<br />
<br />
: See also: [[#setButtonState|setButtonState()]].<br />
{{note}} Function can be used in any Mudlet script outside of a button's own script with parameter ButtonNameOrID available from Mudlet version 4.13.0+<br />
<br />
;Parameters<br />
* ''ButtonNameOrID:''<br />
: a numerical ID or string name to identify the checkbox button.<br />
<br />
;Returns <br />
* ''2'' if the button has "checked" state, or ''1'' if the button is not checked. (or a ''nil'' and an error message if ButtonNameOrID did not identify a check-able button)<br />
<br />
;Example <br />
<syntaxhighlight lang="lua"><br />
-- check from within the script of a check-able button:<br />
local checked = getButtonState()<br />
if checked == 1 then<br />
hideExits()<br />
else<br />
showExits()<br />
end<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- check from anywhere in another Lua script of the same profile (available from Mudlet 4.13.0)<br />
local checked, errMsg = getButtonState("Sleep")<br />
if checked then<br />
shouldBeMounted = shouldBeMounted or false<br />
sendAll("wake", "stand")<br />
if shouldBeMounted then<br />
send("mount horse")<br />
end<br />
else<br />
-- Global used to record if we were on a horse before our nap:<br />
shouldBeMounted = mounted or false<br />
if shouldBeMounted then<br />
send("dismount")<br />
end<br />
sendAll("sit", "sleep")<br />
end<br />
</syntaxhighlight><br />
<br />
==getCmdLine==<br />
;getCmdLine([name])<br />
: Returns the current content of the given command line.<br />
: See also: [[Manual:Lua_Functions#printCmdLine|printCmdLine()]]<br />
<br />
{{MudletVersion|3.1}}<br />
<br />
;Parameters<br />
* ''name'': (optional) name of the command line. If not given, it returns the text of the main commandline.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replaces whatever is currently in the input line by "55 backpacks"<br />
printCmdLine("55 backpacks")<br />
<br />
--prints the text "55 backpacks" to the main console<br />
echo(getCmdLine())<br />
</syntaxhighlight><br />
<br />
==getConsoleBufferSize==<br />
;local lineLimit, sizeOfBatchDeletion = getConsoleBufferSize([consoleName])<br />
:Returns, on success, the maximum number of lines a buffer (main window or a miniconsole) can hold and how many will be removed at a time when that limit is exceeded; returns a ''nil'' and an error message on failure.<br />
: See also: [[Manual:Mudlet_Object_Functions#setConsoleBufferSize|setConsoleBufferSize()]]<br />
<br />
;Parameters<br />
* ''consoleName:''<br />
: (optional) The name of the window. If omitted, uses the main console.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- sets the main window's size and how many lines will be deleted<br />
-- when it gets to that size to be as small as possible:<br />
setConsoleBufferSize("main", 1, 1)<br />
true<br />
<br />
-- find out what the numbers are:<br />
local lineLimit, sizeOfBatchDeletion = getConsoleBufferSize()<br />
echo("\nWhen the main console gets to " .. lineLimit .. " lines long, the first " .. sizeOfBatchDeletion .. " lines will be removed.\n")<br />
When the main console gets to 100 lines long, the first 1 lines will be removed.<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.17}}<br />
<br />
==getNamedTimers==<br />
; timers = getNamedTimers(userName)<br />
<br />
:Returns a list of all the named timers' names as a table.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
<br />
;Returns <br />
* a table of handler names. { "DemonVitals", "DemonInv" } for example. {} if none are registered<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local timers = getNamedTimers("Demonnic")<br />
display(timers)<br />
-- {}<br />
registerNamedTimer("Test1", "testEvent", "testFunction")<br />
registerNamedTimer("Test2", "someOtherEvent", myHandlerFunction)<br />
timers = getNamedTimers("Demonnic")<br />
display(timers)<br />
-- { "Test1", "Test2" }<br />
</syntaxhighlight><br />
<br />
== getProfileStats==<br />
;getProfileStats()<br />
<br />
:Returns a table with profile statistics for how many triggers, patterns within them, aliases, keys, timers, and scripts the profile has. Similar to the Statistics button in the script editor, accessible to Lua scripting.<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- show all stats<br />
display(getProfileStats())<br />
<br />
-- check how many active triggers there are<br />
activetriggers = getProfileStats().triggers.active<br />
cecho(f"<PaleGreen>We have <SlateGrey>{activetriggers}<PaleGreen> active triggers!\n")<br />
<br />
-- triggers can have many patterns, so let's check that as well<br />
patterns = getProfileStats().triggers.patterns.active<br />
triggers = getProfileStats().triggers.active<br />
cecho(f"<PaleGreen>We have <SlateGrey>{patterns}<PaleGreen> active patterns within <SlateGrey>{triggers}<PaleGreen> triggers!\n")<br />
</syntaxhighlight><br />
<br />
==getStopWatches==<br />
;table = getStopWatches()<br />
<br />
: Returns a table of the details for each stopwatch in existence, the keys are the watch IDs but since there can be gaps in the ID number allocated for the stopwatches it will be necessary to use the ''pairs(...)'' rather than the ''ipairs(...)'' method to iterate through all of them in ''for'' loops!<br />
: Each stopwatch's details will list the following items: ''name'' (string), ''isRunning'' (boolean), ''isPersistent'' (boolean), ''elapsedTime'' (table). The last of these contains the same data as is returned by the results table from the [[Manual:Lua_Functions#getStopWatchBrokenDownTime|getStopWatchBrokenDownTime()]] function - namely ''days'' (positive integer), ''hours'' (integer, 0 to 23), ''minutes'' (integer, 0 to 59), ''second'' (integer, 0 to 59), ''milliSeconds'' (integer, 0 to 999), ''negative'' (boolean) with an additional ''decimalSeconds'' (number of seconds, with a decimal portion for the milli-seconds and possibly a negative sign, representing the whole elapsed time recorded on the stopwatch) - as would also be returned by the [[Manual:Lua_Functions#getStopWatchTime|getStopWatchTime()]] function.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- on the command line:<br />
lua getStopWatches()<br />
-- could return something like:<br />
{<br />
{<br />
isPersistent = true,<br />
elapsedTime = {<br />
minutes = 15,<br />
seconds = 2,<br />
negative = false,<br />
milliSeconds = 66,<br />
hours = 0,<br />
days = 18,<br />
decimalSeconds = 1556102.066<br />
},<br />
name = "Playing time",<br />
isRunning = true<br />
},<br />
{<br />
isPersistent = true,<br />
elapsedTime = {<br />
minutes = 47,<br />
seconds = 1,<br />
negative = true,<br />
milliSeconds = 657,<br />
hours = 23,<br />
days = 2,<br />
decimalSeconds = -258421.657<br />
},<br />
name = "TMC Vote",<br />
isRunning = true<br />
},<br />
{<br />
isPersistent = false,<br />
elapsedTime = {<br />
minutes = 26,<br />
seconds = 36,<br />
negative = false,<br />
milliSeconds = 899,<br />
hours = 3,<br />
days = 0,<br />
decimalSeconds = 12396.899<br />
},<br />
name = "",<br />
isRunning = false<br />
},<br />
[5] = {<br />
isPersistent = false,<br />
elapsedTime = {<br />
minutes = 0,<br />
seconds = 38,<br />
negative = false,<br />
milliSeconds = 763,<br />
hours = 0,<br />
days = 0,<br />
decimalSeconds = 38.763<br />
},<br />
name = "",<br />
isRunning = true<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.4}}<br />
<br />
==getStopWatchTime==<br />
;time = getStopWatchTime(watchID [or watchName from Mudlet 4.4.0])<br />
: Returns the time as a decimal number of seconds with up to three decimal places to give a milli-seconds (thousandths of a second) resolution.<br />
: Please note that, prior to 4.4.0 it was not possible to retrieve the elapsed time after the stopwatch had been stopped, retrieving the time was not possible as the returned value then was an indeterminate, meaningless time; from the 4.4.0 release, however, the elapsed value can be retrieved at any time, even if the stopwatch has not been started since creation or modified with the [[Manual:Lua_Functions#adjustStopWatch|adjustStopWatch()]] function introduced in that release.<br />
<br />
: See also: [[Manual:Lua_Functions#createStopWatch|createStopWatch()]], [[Manual:Lua_Functions#startStopWatch|startStopWatch()]], [[Manual:Lua_Functions#stopStopWatch|stopStopWatch()]], [[Manual:Lua_Functions#deleteStopWatch|deleteStopWatch()]], [[Manual:Lua_Functions#getStopWatch es|getStopWatches()]], [[Manual:Lua_Functions#getStopWatchBrokenDownTime|getStopWatchBrokenDownTime()]].<br />
<br />
:Returns a number<br />
<br />
;Parameters<br />
* ''watchID''<br />
: The ID number of the watch.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- an example of showing the time left on the stopwatch<br />
teststopwatch = teststopwatch or createStopWatch()<br />
startStopWatch(teststopwatch)<br />
echo("Time on stopwatch: "..getStopWatchTime(teststopwatch))<br />
tempTimer(1, [[echo("Time on stopwatch: "..getStopWatchTime(teststopwatch))]])<br />
tempTimer(2, [[echo("Time on stopwatch: "..getStopWatchTime(teststopwatch))]])<br />
stopStopWatch(teststopwatch)<br />
</syntaxhighlight><br />
<br />
==getStopWatchBrokenDownTime==<br />
; brokenDownTimeTable = getStopWatchBrokenDownTime(watchID or watchName)<br />
: Returns the current stopwatch time, whether the stopwatch is running or is stopped, as a table, broken down into:<br />
* "days" (integer)<br />
* "hours" (integer, 0 to 23)<br />
* "minutes" (integer, 0 to 59)<br />
* "seconds" (integer, 0 to 59)<br />
* "milliSeconds" (integer, 0 to 999)<br />
* "negative" (boolean, true if value is less than zero)<br />
<br />
: See also: [[Manual:Lua_Functions#startStopWatch|startStopWatch()]], [[Manual:Lua_Functions#stopStopWatch|stopStopWatch()]], [[Manual:Lua_Functions#deleteStopWatch|deleteStopWatch()]], [[Manual:Lua_Functions#getStopWatch es|getStopWatches()]], [[Manual:Lua_Functions#getStopWatchTime|getStopWatchTime()]].<br />
<br />
;Parameters<br />
* ''watchID'' / ''watchName''<br />
: The ID number or the name of the watch.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--an example, showing the presetting of a stopwatch.<br />
<br />
--This will fail if the stopwatch with the given name<br />
-- already exists, but then we can use the existing one:<br />
local watchId = createStopWatch("TopMudSiteVoteStopWatch")<br />
if watchId ~= nil then<br />
-- so we have just created the stopwatch, we want it<br />
-- to be saved for future sessions:<br />
setStopWatchPersistence("TopMudSiteVoteStopWatch", true)<br />
-- and set it to count down the 12 hours until we can<br />
-- revote:<br />
adjustStopWatch("TopMudSiteVoteStopWatch", -60*60*12)<br />
-- and start it running<br />
startStopWatch("TopMudSiteVoteStopWatch")<br />
<br />
openWebPage("http://www.topmudsites.com/vote-wotmud.html")<br />
end<br />
<br />
--[[ now I can check when it is time to vote again, even when<br />
I stop the session and restart later by running the following<br />
from a perm timer - perhaps on a 15 minute interval. Note that<br />
when loaded in a new session the Id it gets is unlikely to be<br />
the same as that when it was created - but that is not a<br />
problem as the name is preserved and, if the timer is running<br />
when the profile is saved at the end of the session then the<br />
elapsed time will continue to increase to reflect the real-life<br />
passage of time:]]<br />
<br />
local voteTimeTable = getStopWatchBrokenDownTime("TopMudSiteVoteStopWatch")<br />
<br />
if voteTimeTable["negative"] then<br />
if voteTimeTable["hours"] == 0 and voteTimeTable["minutes"] < 30 then<br />
echo("Voting for WotMUD on Top Mud Site in " .. voteTimeTable["minutes"] .. " minutes...")<br />
end<br />
else<br />
echo("Oooh, it is " .. voteTimeTable["days"] .. " days, " .. voteTimeTable["hours"] .. " hours and " .. voteTimeTable["minutes"] .. " minutes past the time to Vote on Top Mud Site - doing it now!")<br />
openWebPage("http://www.topmudsites.com/vote-wotmud.html")<br />
resetStopWatch("TopMudSiteVoteStopWatch")<br />
adjustStopWatch("TopMudSiteVoteStopWatch", -60*60*12)<br />
end<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.7}}<br />
<br />
==getScript==<br />
; getScript(scriptName, [occurrence])<br />
: Returns the script with the given name. If you have more than one script with the same name, specify the occurrence to pick a different one. Returns -1 if the script doesn't exist.<br />
<br />
: See also: [[Manual:Lua_Functions#permScript|permScript()]], [[Manual:Lua_Functions#enableScript|enableScript()]], [[Manual:Lua_Functions#disableScript|disableScript()]], [[Manual:Lua_Functions#setScript|setScript()]], [[Manual:Lua_Functions#appendScript|appendScript()]]<br />
<br />
;Parameters<br />
* ''scriptName'': name of the script.<br />
* ''occurrence'': (optional) occurence of the script in case you have many with the same name.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- show the "New script" on screen<br />
print(getScript("New script"))<br />
<br />
-- an example of returning the script Lua code from the second occurrence of "testscript"<br />
test_script_code = getScript("testscript", 2)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.8}}<br />
<br />
==invokeFileDialog==<br />
;invokeFileDialog(fileOrFolder, dialogTitle)<br />
:Opens a file chooser dialog, allowing the user to select a file or a folder visually. The function returns the selected path or "" if there was none chosen.<br />
<br />
;Parameters<br />
* ''fileOrFolder:'' ''true'' for file selection, ''false'' for folder selection.<br />
* ''dialogTitle'': what to say in the window title.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
function whereisit()<br />
local path = invokeFileDialog(false, "Where should we save the file? Select a folder and click Open")<br />
<br />
if path == "" then return nil else return path end<br />
end<br />
</syntaxhighlight><br />
<br />
==isActive==<br />
;isActive(name/IDnumber, type)<br />
:You can use this function to check if something, or somethings, are active. <br />
:Returns the number of active things - and 0 if none are active. Beware that all numbers are true in Lua, including zero.<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name (as a string) or, from '''Mudlet 4.17.0''', the ID number of a single item, (which will be that returned by a ''temp*'' function to create such an item to identify the item).<br />
* ''type:''<br />
: The type can be 'alias', 'button' (Mudlet 4.10+), 'trigger', 'timer', 'keybind' (Mudlet 3.2+), or 'script' (Mudlet 3.17+).<br />
<br />
: See also: [[#exists|exists(...)]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo("I have " .. isActive("my trigger", "trigger") .. " currently active trigger(s) called 'my trigger'!")<br />
<br />
-- Can also be used to check if a specific item is enabled or not.<br />
if isActive("spellname", "trigger" > 0 then<br />
-- the spellname trigger is active<br />
else<br />
-- it is not active<br />
end<br />
</syntaxhighlight><br />
<br />
{{note}} A positive ID number that does not exist will still return a ''0'' value, this is for constancy with the way the function behaves for a name that does not refer to any item either. If necessary the existence of an item should be confirmed with [[#exists|exists(...)]] first.<br />
<br />
==isPrompt==<br />
;isPrompt()<br />
:Returns true or false depending on if the line at the cursor position is a prompt. This infallible feature is available for games that supply GA events (to check if yours is one, look to bottom-right of the main window - if it doesn’t say <No GA>, then it supplies them).<br />
<br />
:Example use could be as a Lua function, making closing gates on a prompt real easy.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- make a trigger pattern with 'Lua function', and this will trigger on every prompt!<br />
-- note that this is deprecated as we now have the prompt trigger type which does the same thing<br />
-- the function can still be useful for detecting if you're running code on a prompt for other reasons<br />
-- but you should be using a prompt trigger for this rather than a Lua function trigger.<br />
return isPrompt()<br />
</syntaxhighlight><br />
<br />
==killAlias==<br />
;killAlias(aliasID)<br />
:Deletes a temporary alias with the given ID.<br />
<br />
;Parameters<br />
* ''aliasID:''<br />
: The id returned by [[Manual:Lua_Functions#tempAlias|tempAlias]] to identify the alias.<br />
<br />
<syntaxhighlight lang="lua"><br />
-- deletes the alias with ID 5<br />
killAlias(5)<br />
</syntaxhighlight><br />
<br />
==killKey==<br />
;killKey(name)<br />
:Deletes a keybinding with the given name. If several keybindings have this name, they'll all be deleted.<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name or the id returned by [[Manual:Lua_Functions#tempKey|tempKey]] to identify the key.<br />
<br />
{{MudletVersion|3.2}}<br />
<br />
<syntaxhighlight lang="lua"><br />
-- make a temp key<br />
local keyid = tempKey(mudlet.key.F8, [[echo("hi!")]])<br />
<br />
-- delete the said temp key<br />
killKey(keyid)<br />
</syntaxhighlight><br />
<br />
==killTimer==<br />
;killTimer(id)<br />
:Deletes a [[Manual:Lua_Functions#tempTimer|tempTimer]].<br />
<br />
{{note}} Non-temporary timers that you have set up in the GUI or by using [[#permTimer|permTimer]] cannot be deleted with this function. Use [[Manual:Lua_Functions#disableTimer|disableTimer()]] and [[Manual:Lua_Functions#enableTimer|enableTimer()]] to turn them on or off.<br />
<br />
;Parameters<br />
* ''id:'' the ID returned by [[Manual:Lua_Functions#tempTimer|tempTimer]].<br />
<br />
: Returns true on success and false if the timer id doesn’t exist anymore (timer has already fired) or the timer is not a temp timer.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create the timer and remember the timer ID<br />
timerID = tempTimer(10, [[echo("hello!")]])<br />
<br />
-- delete the timer<br />
killTimer(timerID)<br />
-- reset the reference to it<br />
timerID = nil<br />
</syntaxhighlight><br />
<br />
==killTrigger==<br />
;killTrigger(id)<br />
:Deletes a [[Manual:Lua_Functions#tempTimer|tempTrigger]], or a trigger made with one of the ''temp<type>Trigger()'' functions.<br />
<br />
{{note}} When used in out of trigger contexts, the triggers are disabled and deleted upon the next line received from the game - so if you are testing trigger deletion within an alias, the 'statistics' window will be reporting trigger counts that are disabled and pending removal, and thus are no cause for concern.<br />
<br />
;Parameters<br />
* ''id:''<br />
: The ID returned by [[Manual:Lua_Functions#tempTimer|tempTimer]] to identify the item. ID is a string and not a number.<br />
<br />
:Returns true on success and false if the trigger id doesn’t exist anymore (trigger has already fired) or the trigger is not a temp trigger.<br />
<br />
==permAlias==<br />
;permAlias(name, parent, regex, lua code)<br />
<br />
:Creates a persistent alias that stays after Mudlet is restarted and shows up in the Script Editor.<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name you’d like the alias to have.<br />
* ''parent:'' <br />
: The name of the group, or another alias you want the trigger to go in - however if such a group/alias doesn’t exist, it won’t do anything. Use "" to make it not go into any groups.<br />
* ''regex:''<br />
: The pattern that you’d like the alias to use.<br />
* ''lua code:'' <br />
: The script the alias will do when it matches.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- creates an alias called "new alias" in a group called "my group"<br />
permAlias("new alias", "my group", "^test$", [[echo ("say it works! This alias will show up in the script editor too.")]])<br />
</syntaxhighlight><br />
<br />
{{note}} Mudlet by design allows duplicate names - so calling permAlias with the same name will keep creating new aliases. You can check if an alias already exists with the [[Manual:Lua_Functions#exists|exists]] function.<br />
<br />
==permGroup==<br />
;permGroup(name, itemtype, [parent])<br />
<br />
:Creates a new group of a given type. This group will persist through Mudlet restarts. <br />
;Parameters<br />
* ''name'':<br />
: The name of the new group item you want to create.<br />
* ''itemtype'' :<br />
: The type of the item, can be one of the following:<br />
:: trigger<br />
:: alias <br />
:: timer<br />
:: script (available in Mudlet 4.7+)<br />
:: key (available in Mudlet 4.11+)<br />
* ''parent'' (available in Mudlet 3.1+):<br />
: (optional) Name of existing item which the new item will be created as a child of. If none is given, item will be at the root level (not nested in any other groups)<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--create a new trigger group<br />
permGroup("Combat triggers", "trigger")<br />
<br />
--create a new alias group only if one doesn't exist already<br />
if exists("Defensive aliases", "alias") == 0 then<br />
permGroup("Defensive aliases", "alias")<br />
end<br />
</syntaxhighlight><br />
<br />
==permPromptTrigger==<br />
;permPromptTrigger(name, parent, lua code)<br />
:Creates a persistent trigger for the in-game prompt that stays after Mudlet is restarted and shows up in the Script Editor.<br />
<br />
{{note}} If the trigger is not working, check that the '''N:''' bottom-right has a number. This feature requires telnet Go-Ahead (GA) or End-of-Record (EOR) to be enabled in your game. Available in Mudlet 3.6+<br />
<br />
;Parameters:<br />
* ''name'' is the name you’d like the trigger to have.<br />
* ''parent'' is the name of the group, or another trigger you want the trigger to go in - however if such a group/trigger doesn’t exist, it won’t do anything. Use "" to make it not go into any groups.<br />
* ''lua code'' is the script the trigger will do when it matches.<br />
<br />
;Example: <br />
<syntaxhighlight lang="lua"><br />
permPromptTrigger("echo on prompt", "", [[echo("hey! this thing is working!\n")]])<br />
</syntaxhighlight><br />
<br />
<br />
==permRegexTrigger==<br />
;permRegexTrigger(name, parent, pattern table, lua code)<br />
:Creates a persistent trigger with one or more ''regex'' patterns that stays after Mudlet is restarted and shows up in the Script Editor.<br />
<br />
;Parameters<br />
* ''name'' is the name you’d like the trigger to have.<br />
* ''parent'' is the name of the group, or another trigger you want the trigger to go in - however if such a group/trigger doesn’t exist, it won’t do anything. Use "" to make it not go into any groups.<br />
* ''pattern table'' is a table of patterns that you’d like the trigger to use - it can be one or many.<br />
* ''lua code'' is the script the trigger will do when it matches.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a regex trigger that will match on the prompt to record your status<br />
permRegexTrigger("Prompt", "", {"^(\d+)h, (\d+)m"}, [[health = tonumber(matches[2]); mana = tonumber(matches[3])]])<br />
</syntaxhighlight><br />
{{note}} Mudlet by design allows duplicate names - so calling permRegexTrigger with the same name will keep creating new triggers. You can check if a trigger already exists with the [[Manual:Lua_Functions#exists|exists()]] function.<br />
<br />
==permBeginOfLineStringTrigger==<br />
;permBeginOfLineStringTrigger(name, parent, pattern table, lua code)<br />
:Creates a persistent trigger that stays after Mudlet is restarted and shows up in the Script Editor. The trigger will go off whenever one of the ''regex'' patterns it's provided with matches. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls.<br />
<br />
;Parameters<br />
* ''name'' is the name you’d like the trigger to have.<br />
* ''parent'' is the name of the group, or another trigger you want the trigger to go in - however if such a group/trigger doesn’t exist, it won’t do anything. Use "" to make it not go into any groups.<br />
* ''pattern table'' is a table of patterns that you’d like the trigger to use - it can be one or many.<br />
* ''lua code'' is the script the trigger will do when it matches.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- Create a trigger that will match on anything that starts with "You sit" and do "stand".<br />
-- It will not go into any groups, so it'll be on the top.<br />
permBeginOfLineStringTrigger("Stand up", "", {"You sit"}, [[send ("stand")]])<br />
<br />
-- Another example - lets put our trigger into a "General" folder and give it several patterns.<br />
permBeginOfLineStringTrigger("Stand up", "General", {"You sit", "You fall", "You are knocked over by"}, [[send ("stand")]])<br />
</syntaxhighlight><br />
{{note}} Mudlet by design allows duplicate names - so calling permBeginOfLineStringTrigger with the same name will keep creating new triggers. You can check if a trigger already exists with the [[Manual:Lua_Functions#exists|exists()]] function.<br />
<br />
==permSubstringTrigger==<br />
;permSubstringTrigger( name, parent, pattern table, lua code )<br />
:Creates a persistent trigger with one or more ''substring'' patterns that stays after Mudlet is restarted and shows up in the Script Editor.<br />
;Parameters<br />
* ''name'' is the name you’d like the trigger to have.<br />
* ''parent'' is the name of the group, or another trigger you want the trigger to go in - however if such a group/trigger doesn’t exist, it won’t do anything. Use "" to make it not go into any groups.<br />
* ''pattern table'' is a table of patterns that you’d like the trigger to use - it can be one or many.<br />
* ''lua code'' is the script the trigger will do when it matches.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a trigger to highlight the word "pixie" for us<br />
permSubstringTrigger("Highlight stuff", "General", {"pixie"},<br />
[[selectString(line, 1) bg("yellow") resetFormat()]])<br />
<br />
-- Or another trigger to highlight several different things<br />
permSubstringTrigger("Highlight stuff", "General", {"pixie", "cat", "dog", "rabbit"},<br />
[[selectString(line, 1) fg ("blue") bg("yellow") resetFormat()]])<br />
</syntaxhighlight><br />
{{note}} Mudlet by design allows duplicate names - so calling permSubstringTrigger with the same name will keep creating new triggers. You can check if a trigger already exists with the [[Manual:Lua_Functions#exists|exists()]] function.<br />
<br />
==permScript==<br />
;permScript(name, parent, lua code)<br />
: Creates a new script in the Script Editor that stays after Mudlet is restarted.<br />
<br />
;Parameters<br />
* ''name'': name of the script.<br />
* ''parent'': name of the script group you want the script to go in.<br />
* ''lua code'': is the code with string you are putting in your script.<br />
<br />
;Returns<br />
* a unique id number for that script.<br />
<br />
: See also: [[#enableScript|enableScript()]], [[#exists|exists()]], [[#appendScript|appendScript()]], [[#disableScript|disableScript()]], [[#getScript|getScript()]], [[#setScript|setScript()]]<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
-- create a script in the "first script group" group<br />
permScript("my script", "first script group", [[send ("my script that's in my first script group fired!")]])<br />
-- create a script that's not in any group; just at the top<br />
permScript("my script", "", [[send ("my script that's in my first script group fired!")]])<br />
<br />
-- enable Script - a script element is disabled at creation<br />
enableScript("my script")<br />
</syntaxhighlight><br />
<br />
{{note}} The script is called once but NOT active after creation, it will need to be enabled by [[#enableScript|enableScript()]].<br />
<br />
{{note}} Mudlet by design allows duplicate names - so calling permScript with the same name will keep creating new script elements. You can check if a script already exists with the [[Manual:Lua_Functions#exists|exists()]] function.<br />
<br />
{{note}} If the ''lua code'' parameter is an empty string, then the function will create a script group instead.<br />
<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
==permTimer==<br />
;permTimer(name, parent, seconds, lua code)<br />
: Creates a persistent timer that stays after Mudlet is restarted and shows up in the Script Editor.<br />
<br />
;Parameters<br />
* ''name'' <br />
:name of the timer.<br />
* ''parent'' <br />
:name of the timer group you want the timer to go in.<br />
* ''seconds'' <br />
:a floating point number specifying a delay in seconds after which the timer will do the lua code (stored as the timer's "script") you give it as a string.<br />
* ''lua code'' is the code with string you are doing this to.<br />
<br />
;Returns<br />
* a unique id number for that timer.<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
-- create a timer in the "first timer group" group<br />
permTimer("my timer", "first timer group", 4.5, [[send ("my timer that's in my first timer group fired!")]])<br />
-- create a timer that's not in any group; just at the top<br />
permTimer("my timer", "", 4.5, [[send ("my timer that's in my first timer group fired!")]])<br />
<br />
-- enable timer - they start off disabled until you're ready<br />
enableTimer("my timer")<br />
</syntaxhighlight><br />
<br />
{{note}} The timer is NOT active after creation, it will need to be enabled by a call to [[#enableTimer|enableTimer()]] before it starts.<br />
<br />
{{note}} Mudlet by design allows duplicate names - so calling permTimer with the same name will keep creating new timers. You can check if a timer already exists with the [[Manual:Lua_Functions#exists|exists()]] function.<br />
<br />
==permKey==<br />
;permKey(name, parent, [modifier], key code, lua code)<br />
: Creates a persistent key that stays after Mudlet is restarted and shows up in the Script Editor.<br />
<br />
;Parameters<br />
* ''name'' <br />
:name of the key.<br />
* ''parent'' <br />
:name of the timer group you want the timer to go in or "" for the top level.<br />
* ''modifier'' <br />
:(optional) modifier to use - can be one of ''mudlet.keymodifier.Control'', ''mudlet.keymodifier.Alt'', ''mudlet.keymodifier.Shift'', ''mudlet.keymodifier.Meta'', ''mudlet.keymodifier.Keypad'', or ''mudlet.keymodifier.GroupSwitch'' or the default value of ''mudlet.keymodifier.None'' which is used if the argument is omitted. To use multiple modifiers, add them together: ''(mudlet.keymodifier.Shift + mudlet.keymodifier.Control)''<br />
* ''key code'' <br />
: actual key to use - one of the values available in ''mudlet.key'', e.g. ''mudlet.key.Escape'', ''mudlet.key.Tab'', ''mudlet.key.F1'', ''mudlet.key.A'', and so on. The list is a bit long to list out in full so it is [https://github.com/Mudlet/Mudlet/blob/development/src/mudlet-lua/lua/KeyCodes.lua#L2 available here].<br />
: set to -1 if you want to create a key folder instead.<br />
* ''lua code'<br />
: code you would like the key to run.<br />
<br />
;Returns<br />
* a unique id number for that key.<br />
<br />
{{MudletVersion|3.2+, creating key folders in Mudlet 4.10}}<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
-- create a key at the top level for F8<br />
permKey("my key", "", mudlet.key.F8, [[echo("hey this thing actually works!\n")]])<br />
<br />
-- or Ctrl+F8<br />
permKey("my key", "", mudlet.keymodifier.Control, mudlet.key.F8, [[echo("hey this thing actually works!\n")]])<br />
<br />
-- Ctrl+Shift+W<br />
permKey("jump keybinding", "", mudlet.keymodifier.Control + mudlet.keymodifier.Shift, mudlet.key.W, [[send("jump")]])<br />
</syntaxhighlight><br />
<br />
{{note}} Mudlet by design allows duplicate names - so calling permKey with the same name will keep creating new keys. You can check if a key already exists with the [[Manual:Lua_Functions#exists|exists()]] function. The key will be created even if the lua code does not compile correctly - but this will be apparent as it will be seen in the Editor.<br />
<br />
==printCmdLine==<br />
;printCmdLine([name], text)<br />
<br />
: Replaces the current text in the input line, and sets it to the given text.<br />
: See also: [[Manual:Lua_Functions#clearCmdLine|clearCmdLine()]], [[#appendCmdLine|appendCmdLine()]]<br />
<br />
;Parameters<br />
* ''name'': (optional) name of the command line. If not given, main commandline's text will be set.<br />
* ''text'': text to set<br />
<br />
<syntaxhighlight lang="lua"><br />
printCmdLine("say I'd like to buy ")<br />
</syntaxhighlight><br />
<br />
==raiseEvent==<br />
;raiseEvent(event_name, arg-1, … arg-n)<br />
<br />
: Raises the event event_name. The event system will call the main function (the one that is called exactly like the script name) of all such scripts in this profile that have registered event handlers. If an event is raised, but no event handler scripts have been registered with the event system, the event is ignored and nothing happens. This is convenient as you can raise events in your triggers, timers, scripts etc. without having to care if the actual event handling has been implemented yet - or more specifically how it is implemented. Your triggers raise an event to tell the system that they have detected a certain condition to be true or that a certain event has happened. How - and if - the system is going to respond to this event is up to the system and your trigger scripts don’t have to care about such details. For small systems it will be more convenient to use regular function calls instead of events, however, the more complicated your system will get, the more important events will become because they help reduce complexity very much.<br />
<br />
:The corresponding event handlers that listen to the events raised with raiseEvent() need to use the script name as function name and take the correct number of arguments. <br />
<br />
:See also: [[#raiseGlobalEvent|raiseGlobalEvent]]<br />
<br />
{{note}} possible arguments can be string, number, boolean, table, function, or nil.<br />
<br />
;Example:<br />
<br />
:raiseEvent("fight") a correct event handler function would be: myScript( event_name ). In this example raiseEvent uses minimal arguments, name the event name. There can only be one event handler function per script, but a script can still handle multiple events as the first argument is always the event name - so you can call your own special handlers for individual events. The reason behind this is that you should rather use many individual scripts instead of one huge script that has all your function code etc. Scripts can be organized very well in trees and thus help reduce complexity on large systems.<br />
<br />
Where the number of arguments that your event may receive is not fixed you can use [http://www.lua.org/manual/5.1/manual.html#2.5.9 ''...''] as the last argument in the ''function'' declaration to handle any number of arguments. For example:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- try this function out with "lua myscripthandler(1,2,3,4)"<br />
function myscripthandler(a, b, ...)<br />
print("Arguments a and b are: ", a,b)<br />
-- save the rest of the arguments into a table<br />
local otherarguments = {...}<br />
print("Rest of the arguments are:")<br />
display(otherarguments)<br />
<br />
-- access specific otherarguments:<br />
print("First and second otherarguments are: ", otherarguments[1], otherarguments[2])<br />
end<br />
</syntaxhighlight><br />
<br />
==raiseGlobalEvent==<br />
;raiseGlobalEvent(event_name, arg-1, … arg-n)<br />
<br />
: Like [[Manual:Lua_Functions#raiseEvent|raiseEvent()]] this raises the event "event_name", but this event is sent to all '''other''' opened profiles instead. The profiles receive the event in circular alphabetical order (if profile "C" raised this event and we have profiles "A", "C", and "E", the order is "E" -> "A", but if "E" raised the event the order would be "A" -> "C"); execution control is handed to the receiving profiles so that means that long running events may lock up the profile that raised the event.<br />
<br />
: The sending profile's name is automatically appended as the last argument to the event.<br />
<br />
{{note}} possible arguments can be string, number, boolean, or nil, but not table or function.<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- from profile called "My game" this raises an event "my event" with additional arguments 1, 2, 3, "My game" to all profiles except the original one<br />
raiseGlobalEvent("my event", 1, 2, 3)<br />
<br />
-- want the current profile to receive it as well? Use raiseEvent<br />
raiseEvent("my event", 1, 2, 3)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua><br />
-- example of calling functions in one profile from another:<br />
-- profile B:<br />
control = control or {}<br />
function control.updateStatus()<br />
disableTrigger("test triggers")<br />
print("disabling triggers worked!")<br />
end<br />
<br />
-- this handles calling the right function in the control table<br />
function control.marshaller(_, callfunction)<br />
if control[callfunction] then control[callfunction]()<br />
else<br />
cecho("<red>Asked to call an unknown function: "..callfunction)<br />
end<br />
end<br />
<br />
registerAnonymousEventHandler("sysSendAllProfiles", "control.marshaller")<br />
<br />
-- profile A:<br />
raiseGlobalEvent("sysSendAllProfiles", "updateStatus")<br />
raiseGlobalEvent("sysSendAllProfiles", "invalidfunction")<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.1.0}}<br />
<br />
Tip: you might want to add the [[Manual:Miscellaneous_Functions#getProfileName|profile name]] to your plain [[Manual:Miscellaneous_Functions#raiseEvent|raiseEvent()]] arguments. This'll help you tell which profile your event came from similar to [[#raiseGlobalEvent|raiseGlobalEvent()]].<br />
<br />
==registerNamedTimer==<br />
; success = registerNamedTimer(userName, timerName, time, functionReference, [repeating])<br />
<br />
:Registers a named timer with name timerName. Named timers are protected from duplication and can be stopped and resumed, unlike normal tempTimers. A separate list is kept for each userName, to enforce name spacing and avoid collisions<br />
<br />
;See also: [[Manual:Lua_Functions#tempTimer|tempTimer()]], [[Manual:Lua_Functions#stopNamedTimer|stopNamedTimer()]], [[Manual:Lua_Functions#resumeNamedTimer|resumeNamedTimer()]], [[Manual:Lua_Functions#deleteNamedTimer|deleteNamedTimer()]], [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
* ''timerName:''<br />
: 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.<br />
* ''time:''<br />
: The amount of time in seconds to wait before firing.<br />
* ''functionReference:''<br />
: The function reference to run when the event comes in. Can be the name of a function, "handlerFunction", or the lua function itself.<br />
* ''repeating:''<br />
: (optional) if true, the timer continue to fire until the stop it using [[Manual:Lua_Functions#stopNamedTimer|stopNamedTimer()]]<br />
;Returns <br />
* true if successful, otherwise errors.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- establish a named timer called "Check balance" which runs balanceChecker() after 1 second<br />
-- it is started automatically when registered, and fires only once despite being run twice<br />
-- you wouldn't do this intentionally, but illustrates the duplicate protection<br />
registerNamedTimer("Demonnic", "Check Balance", 1, balanceChecker)<br />
registerNamedTimer("Demonnic", "Check Balance", 1, balanceChecker)<br />
<br />
-- then the next time you want to make/use the same timer, you can shortcut it with<br />
resumeNamedTimer("Demonnic", "Check Balance")<br />
</syntaxhighlight><br />
<br />
==remainingTime==<br />
;remainingTime(timer id number or name)<br />
<br />
: Returns the remaining time in floating point form in seconds (if it is active) for the timer (temporary or permanent) with the id number or the (first) one found with the name.<br />
: If the timer is inactive or has expired or is not found it will return a ''nil'' and an ''error message''. It, theoretically could also return 0 if the timer is overdue, i.e. it has expired but the internal code has not yet been run but that has not been seen in during testing. Permanent ''offset timers'' will only show as active during the period when they are running after their parent has expired and started them.<br />
<br />
{{MudletVersion|3.20}}<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
tid = tempTimer(600, [[echo("\nYour ten minutes are up.\n")]])<br />
echo("\nYou have " .. remainingTime(tid) .. " seconds left, use it wisely... \n")<br />
<br />
-- Will produce something like:<br />
<br />
You have 599.923 seconds left, use it wisely... <br />
<br />
-- Then ten minutes time later:<br />
<br />
Your ten minutes are up.<br />
<br />
</syntaxhighlight><br />
<br />
==resetProfileIcon==<br />
;resetProfileIcon()<br />
: Resets the profile's icon in the connection screen to default.<br />
<br />
See also: [[#setProfileIcon|setProfileIcon()]].<br />
<br />
{{MudletVersion|4.0}}<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
resetProfileIcon()<br />
</syntaxhighlight><br />
<br />
==resetStopWatch==<br />
;resetStopWatch(watchID)<br />
:This function resets the time to 0:0:0.0, but does not stop or start the stop watch. You can stop it with [[Manual:Lua_Functions#stopStopWatch | stopStopWatch]] or start it with [[Manual:Lua_Functions#startStopWatch | startStopWatch]] → [[Manual:Lua_Functions#createStopWatch | createStopWatch]]<br />
<br />
==resumeNamedTimer==<br />
; success = resumeNamedTimer(userName, handlerName)<br />
<br />
:Resumes a named timer with name handlerName and causes it to fire again. One time unless it was registered as repeating.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]], [[Manual:Lua_Functions#stopNamedTimer|stopNamedTimer()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameter<br />
* ''userName:''<br />
: The user name the event handler was registered under.s<br />
* ''handlerName:''<br />
: The name of the handler to resume. Same as used when you called [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]]<br />
<br />
;Returns <br />
* true if successful, false if it didn't exist. If the timer is waiting to fire it will be restarted at 0.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local resumed = resumeNamedTimer("Demonnic", "DemonVitals")<br />
if resumed then<br />
cecho("DemonVitals resumed!")<br />
else<br />
cecho("DemonVitals doesn't exist, so cannot resume it.")<br />
end<br />
</syntaxhighlight><br />
<br />
==setButtonState==<br />
;setButtonState(ButtonNameOrID, checked)<br />
:Sets the state of a check-able ("push-down") type button from any Mudlet item's script - but does not cause the script or one of the commands associated with that button to be run/sent.<br />
: See also: [[#getButtonState|getButtonState()]].<br />
{{MudletVersion|4.13}}<br />
<br />
;Parameters<br />
* ''ButtonNameOrID:''<br />
: The name of the button as a string or a unique ID (positive) integer number {for a name only one matching one will be affected - it will be the same one that the matching [[#getButtonState|getButtonState()]] reports upon}.<br />
* ''checked:''<br />
: boolean value that indicated whether the state required is down (''true'') or up (''false''). <br />
<br />
;Returns:<br />
* A boolean value indicating ''true'' if the visible state was actually changed, i.e. had any effect. This function will return a ''nil'' and a suitable error message if the identifying name or ID was not found or was not a check-able (push-down) button item (i.e. was a non-checkable button or a menu or a toolbar instead).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- inside, for example, an initialization script for a GUI package:<br />
setButtonState("Sleep", false)<br />
setButtonState("Sit", false)<br />
-- these are going to be used as "radio" buttons where setting one<br />
-- of them will unset all the others, they will each need something<br />
-- similar in their own scripts to unset all the others in the set<br />
-- and also something to prevent them from being unset by clicking<br />
-- on themselves:<br />
setButtonState("Wimpy", true)<br />
setButtonState("Defensive", false)<br />
setButtonState("Normal", false)<br />
setButtonState("Brave", false)<br />
if character.type == "Warrior" then<br />
-- Only one type has this mode - and it can only be reset by<br />
-- something dying (though that could be us!)<br />
setButtonState("Beserk!!!", false)<br />
end<br />
</syntaxhighlight><br />
<br />
==setConsoleBufferSize==<br />
;setConsoleBufferSize([consoleName], linesLimit, sizeOfBatchDeletion)<br />
:Sets the maximum number of lines a buffer (main window or a miniconsole) can hold. Default is 10,000.<br />
:Returns nothing on success (up to '''Mudlet 4.16''') or ''true'' (from '''Mudlet 4.17'''); ''nil'' and an error message on failure.<br />
<br />
;Parameters<br />
* ''consoleName:''<br />
: (optional) The name of the window. If omitted, uses the main console.<br />
* ''linesLimit:''<br />
: Sets the amount of lines the buffer should have. <br />
{{note}} Mudlet performs extremely efficiently with even huge numbers, but there is of course a limit to your computer's memory. As of Mudlet 4.7+, this amount will be capped to that limit on macOS and Linux (on Windows, it's capped lower as Mudlet on Windows is 32bit).<br />
* ''sizeOfBatchDeletion:''<br />
: Specifies how many lines should Mudlet delete at once when you go over the limit - it does it in bulk because it's efficient to do so.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- sets the main windows size to 1 million lines maximum - which is more than enough!<br />
setConsoleBufferSize("main", 1000000, 1000)<br />
</syntaxhighlight><br />
<br />
==setProfileIcon==<br />
;setProfileIcon(iconPath)<br />
:Set a custom icon for this profile in the connection screen. <br />
<br />
:Returns true if successful, or nil+error message if not.<br />
<br />
:See also: [[#resetProfileIcon|resetProfileIcon()]].<br />
<br />
{{MudletVersion|4.0}}<br />
<br />
;Parameters<br />
* ''iconPath:''<br />
: Full location of the icon - can be .png or .jpg with ideal dimensions of 120x30.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- set a custom icon that is located in an installed package called "mypackage"<br />
setProfileIcon(getMudletHomeDir().."/mypackage/icon.png")<br />
</syntaxhighlight><br />
<br />
==setScript==<br />
;setScript(scriptName, luaCode, [occurrence])<br />
: Sets the script's Lua code, replacing existing code. If you have many scripts with the same name, use the 'occurrence' parameter to choose between them.<br />
: If you'd like to add code instead of replacing it, have a look at [[Manual:Lua_Functions#appendScript|appendScript()]].<br />
: Returns -1 if the script isn't found - to create a script, use [[Manual:Lua_Functions#permScript|permScript()]].<br />
<br />
: See also: [[Manual:Lua_Functions#permScript|permScript()]], [[Manual:Lua_Functions#enableScript|enableScript()]], [[Manual:Lua_Functions#disableScript|disableScript()]], [[Manual:Lua_Functions#getScript|getScript()]], [[Manual:Lua_Functions#appendScript|appendScript()]]<br />
<br />
;Returns<br />
* a unique id number for that script.<br />
<br />
;Parameters<br />
* ''scriptName'': name of the script to change the code.<br />
* ''luaCode'': new Lua code to set.<br />
* ''occurrence'': The position of the script. Optional, defaults to 1 (first).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- make sure a script named "testscript" exists first, then do:<br />
setScript("testscript", [[echo("This is a test\n")]], 1)<br />
</syntaxhighlight><br />
{{MudletVersion|4.8}}<br />
<br />
==setStopWatchName==<br />
;setStopWatchName(watchID/currentStopWatchName, newStopWatchName)<br />
<br />
;Parameters<br />
* ''watchID'' (number) / ''currentStopWatchName'' (string): The stopwatch ID you get from [[Manual:Lua_Functions#createStopWatch|createStopWatch()]] or the name supplied to that function at that time, or previously applied with this function.<br />
* ''newStopWatchName'' (string): The name to use for this stopwatch from now on.<br />
<br />
;Returns<br />
* ''true'' on success, ''nil'' and an error message if no matching stopwatch is found.<br />
<br />
{{note}} Either ''currentStopWatchName'' or ''newStopWatchName'' may be empty strings: if the first of these is so then the ''lowest'' ID numbered stopwatch without a name is chosen; if the second is so then an existing name is removed from the chosen stopwatch.<br />
<br />
==setStopWatchPersistence==<br />
;setStopWatchPersistence(watchID/watchName, state)<br />
<br />
;Parameters<br />
* ''watchID'' (number) / ''watchName'' (string): The stopwatch ID you get from [[Manual:Lua_Functions#createStopWatch|createStopWatch()]] or the name supplied to that function or applied later with [[Manual:Lua_Functions#setStopWatchName|setStopWatchName()]]<br />
* ''state'' (boolean): if ''true'' the stopWatch will be saved.<br />
<br />
;Returns<br />
* ''true'' on success, ''nil'' and an error message if no matching stopwatch is found.<br />
<br />
:Sets or resets the flag so that the stopwatch is saved between sessions or after a [[Manual:Miscellaneous_Functions#resetProfile|resetProfile()]] call. If set then, if ''stopped'' the elapsed time recorded will be unchanged when the stopwatch is reloaded in the next session; if ''running'' the elapsed time will continue to increment and it will include the time that the profile was not loaded, therefore it can be used to measure events in real-time, outside of the profile!<br />
<br />
{{note}} When a persistent stopwatch is reloaded in a later session (or after a use of ''resetProfile()'') the stopwatch may not be allocated the same ID number as before - therefore it is advisable to assign any persistent stopwatches a name, either when it is created or before the session is ended.<br />
<br />
==setTriggerStayOpen==<br />
;setTriggerStayOpen(name, number of lines)<br />
:Sets for how many more lines a trigger script should fire or a chain should stay open after the trigger has matched - so this allows you to extend or shorten the ''fire length'' of a trigger. The main use of this function is to close a chain when a certain condition has been met.<br />
<br />
;Parameters<br />
* ''name:'' The name of the trigger which has a fire length set (and which opens the chain).<br />
* ''number of lines'': 0 to close the chain, or a positive number to keep the chain open that much longer.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- if you have a trigger that opens a chain (has some fire length) and you'd like it to be closed <br />
-- on the next prompt, you could make a prompt trigger inside the chain with a script of:<br />
setTriggerStayOpen("Parent trigger name", 0)<br />
-- to close it on the prompt!<br />
</syntaxhighlight><br />
<br />
==startStopWatch==<br />
;startStopWatch(watchName or watchID, [resetAndRestart])<br />
<br />
:Stopwatches can be stopped (with [[Manual:Lua_Functions#stopStopWatch|stopStopWatch()]]) and then re-started any number of times. '''To ensure backwards compatibility, if the stopwatch is identified by a ''numeric'' argument then, ''unless a second argument of false is supplied as well'' this function will also reset the stopwatch to zero and restart it - whether it is running or not'''; otherwise only a stopped watch can be started and only a started watch may be stopped. Trying to repeat either will produce a nil and an error message instead; also the recorded time is no longer reset so that they can now be used to record a total of isolated periods of time like a real stopwatch.<br />
<br />
:See also: [[Manual:Lua_Functions#createStopWatch|createStopWatch()]], [[Manual:Lua_Functions#stopStopWatch|stopStopWatch()]]<br />
<br />
;Parameters<br />
* ''watchID''/''watchName'': The stopwatch ID you get with [[Manual:Lua_Functions#createStopWatch|createStopWatch()]], or from '''4.4.0''' the name assigned with that function or [[Manual:Lua_Functions#setStopWatchName|setStopWatchName()]].<br />
* ''resetAndRestart'': Boolean flag needed (as ''false'') to make the function from '''4.4.0''', when supplied with a numeric watch ID, to '''not''' reset the stopwatch and only start a previously stopped stopwatch. This behavior is automatic when a string watch name is used to identify the stopwatch but differs from how the function behaved prior to that version.<br />
<br />
;Returns<br />
* ''true'' on success, ''nil'' and an error message if no matching stopwatch is found or if it cannot be started (because the later style behavior was indicated and it was already running).<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- this is a common pattern for re-using stopwatches prior to 4.4.0 and starting them:<br />
watch = watch or createStopWatch()<br />
startStopWatch(watch)<br />
</syntaxhighlight><br />
<br />
:: After 4.4.0 the above code will work the same as it does not provide a second argument to the ''startStopWatch()'' function - if a ''false'' was used there it would be necessary to call ''stopStopWatch(...)'' and then ''resetStopWatch(...)'' before using ''startStopWatch(...)'' to re-use the stopwatch if the ID form is used, '''this is thus not quite the same behavior but it is more consistent with the model of how a real stopwatch would act.'''<br />
<br />
==stopAllNamedTimers==<br />
; stopAllNamedTimers(userName)<br />
<br />
:Stops all named timers for userName and prevents them from firing any more. Information is retained and timers can be resumed.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]], [[Manual:Lua_Functions#stopNamedTimer|stopNamedTimer()]], [[Manual:Lua_Functions#resumeNamedTimer|resumeNamedTimer()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
stopAllNamedTimers("Demonnic") -- emergency stop situation, most likely.<br />
</syntaxhighlight><br />
<br />
==stopNamedTimer==<br />
; success = stopNamedTimer(userName, handlerName)<br />
<br />
:Stops a named timer with name handlerName and prevents it from firing any more. Information is stored so it can be resumed later if desired.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]], [[Manual:Lua_Functions#resumeNamedTimer|resumeNamedTimer()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
* ''handlerName:''<br />
: The name of the handler to stop. Same as used when you called [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]]<br />
<br />
;Returns <br />
* true if successful, false if it didn't exist or was already stopped<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local stopped = stopNamedTimer("Demonnic", "DemonVitals")<br />
if stopped then<br />
cecho("DemonVitals stopped!")<br />
else<br />
cecho("DemonVitals doesn't exist or already stopped; either way it won't fire any more.")<br />
end<br />
</syntaxhighlight><br />
<br />
==stopStopWatch==<br />
;stopStopWatch(watchID or watchName)<br />
:"Stops" (though see the note below) the stop watch and returns (only the '''first''' time it is called after the stopwatch has been set running with [[Manual:Lua_Functions#startStopWatch|startStopWatch()]]) the elapsed time as a number of seconds, with a decimal portion give a resolution in milliseconds (thousandths of a second). You can also retrieve the current time without stopping the stopwatch with [[Manual:Lua_Functions#getStopWatchTime|getStopWatchTime()]], [[Manual:Lua_Functions#getBrokenDownStopWatchTime|getBrokenDownStopWatchTime()]].<br />
<br />
:See also: [[Manual:Lua_Functions#createStopWatch|createStopWatch()]]<br />
<br />
;Parameters<br />
* ''watchID:'' The stopwatch ID you get with [[Manual:Lua_Functions#createStopWatch|createStopWatch()]] or from Mudlet '''4.4.0''' the name given to that function or later set with [[Manual:Lua_Functions#setStopWatchName|setStopWatchName()]].<br />
<br />
;Returns<br />
* the elapsed time as a floating-point number of seconds - it may be negative if the time was previously adjusted/preset to a negative amount (with [[Manual:Lua_Functions#adjustStopWatch|adjustStopWatch()]]) and that period has not yet elapsed.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- this is a common pattern for re-using stopwatches and starting them:<br />
watch = watch or createStopWatch()<br />
startStopWatch(watch)<br />
<br />
-- do some long-running code here ...<br />
<br />
print("The code took: "..stopStopWatch(watch).."s to run.")<br />
</syntaxhighlight><br />
<br />
==tempAnsiColorTrigger==<br />
;tempAnsiColorTrigger(foregroundColor[, backgroundColor], code[, expireAfter])<br />
:This is an alternative to [[Manual:Lua_Functions#tempColorTrigger|tempColorTrigger()]] which supports the full set of 256 ANSI color codes directly and makes a color trigger that triggers on the specified foreground and background color. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
<br />
;Parameters<br />
* ''foregroundColor:'' The foreground color you'd like to trigger on.<br />
* ''backgroundColor'': The background color you'd like to trigger on.<br />
* ''code to do'': The code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function.<br />
* ''expireAfter'': Delete trigger after a specified number of matches. You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
''BackgroundColor'' and/or ''expireAfter'' may be omitted.<br />
<br />
;Color codes (note that the values greater than or equal to zero are the actual number codes that ANSI and the game server uses for the 8/16/256 color modes)<br />
<br />
::Special codes (may be extended in the future):<br />
:::-2 = default text color (what is used after an ANSI SGR 0 m code that resets the foreground and background colors to those set in the preferences)<br />
:::-1 = ignore (only '''one''' of the foreground or background codes can have this value - otherwise it would not be a ''color'' trigger!)<br />
<br />
::ANSI 8-color set:<br />
:::0 = (dark) black<br />
:::1 = (dark) red<br />
:::2 = (dark) green<br />
:::3 = (dark) yellow<br />
:::4 = (dark) blue<br />
:::5 = (dark) magenta<br />
:::6 = (dark) cyan<br />
:::7 = (dark) white {a.k.a. light gray}<br />
<br />
::Additional colors in 16-color set:<br />
:::8 = light black {a.k.a. dark gray}<br />
:::9 = light red<br />
:::10 = light green<br />
:::11 = light yellow<br />
:::12 = light blue<br />
:::13 = light magenta<br />
:::14 = light cyan<br />
:::15 = light white<br />
<br />
::6 x 6 x 6 RGB (216) colors, shown as a 3x2-digit hex code<br />
:::16 = #000000<br />
:::17 = #000033<br />
:::18 = #000066<br />
:::...<br />
:::229 = #FFFF99<br />
:::230 = #FFFFCC<br />
:::231 = #FFFFFF<br />
<br />
::24 gray-scale, also show as a 3x2-digit hex code<br />
:::232 = #000000<br />
:::233 = #0A0A0A<br />
:::234 = #151515<br />
:::...<br />
:::253 = #E9E9E9<br />
:::254 = #F4F4F4<br />
:::255 = #FFFFFF<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- This script will re-highlight all text in a light cyan foreground color on any background with a red foreground color<br />
-- until another foreground color in the current line is being met. temporary color triggers do not offer match_all<br />
-- or filter options like the GUI color triggers because this is rarely necessary for scripting.<br />
-- A common usage for temporary color triggers is to schedule actions on the basis of forthcoming text colors in a particular context.<br />
tempAnsiColorTrigger(14, -1, [[selectString(matches[1],1) fg("red")]])<br />
-- or:<br />
tempAnsiColorTrigger(14, -1, function()<br />
selectString(matches[1], 1)<br />
fg("red")<br />
end)<br />
<br />
-- match the trigger only 4 times<br />
tempColorTrigger(14, -1, [[selectString(matches[1],1) fg("red")]], 4)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.17}}<br />
<br />
==tempAlias==<br />
;aliasID = tempAlias(regex, code to do)<br />
:Creates a temporary alias - temporary in the sense that it won't be saved when Mudlet restarts (unless you re-create it). The alias will go off as many times as it matches, it is not a one-shot alias. The function returns an ID for subsequent [[Manual:Lua_Functions#enableAlias|enableAlias()]], [[Manual:Lua_Functions#disableAlias|disableAlias()]] and [[Manual:Lua_Functions#killAlias|killAlias()]] calls.<br />
<br />
;Parameters<br />
* ''regex:'' Alias pattern in regex.<br />
* ''code to do:'' The code to do when the alias fires - wrap it in [[ ]].<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
myaliasID = tempAlias("^hi$", [[send ("hi") echo ("we said hi!")]])<br />
<br />
-- you can also delete the alias later with:<br />
killAlias(myaliasID)<br />
<br />
-- tempAlias also accepts functions (and thus closures) - which can be an easier way to embed variables and make the code for an alias look less messy:<br />
<br />
local variable = matches[2]<br />
tempAlias("^hi$", function () send("hello, " .. variable) end)<br />
</syntaxhighlight><br />
<br />
==tempBeginOfLineTrigger==<br />
;tempBeginOfLineTrigger(part of line, code, expireAfter)<br />
:Creates a trigger that will go off whenever the part of line it's provided with matches the line right from the start (doesn't matter what the line ends with). The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls.<br />
<br />
;Parameters<br />
* ''part of line'': start of the line that you'd like to match. This can also be regex.<br />
* ''code to do'': code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function (since Mudlet 3.5.0).<br />
* ''expireAfter'': Delete trigger after a specified number of matches (since Mudlet 3.11). You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
mytriggerID = tempBeginOfLineTrigger("Hello", [[echo("We matched!")]])<br />
<br />
--[[ now this trigger will match on any of these lines:<br />
Hello<br />
Hello!<br />
Hello, Bob!<br />
<br />
but not on:<br />
Oh, Hello<br />
Oh, Hello!<br />
]]<br />
<br />
-- or as a function:<br />
mytriggerID = tempBeginOfLineTrigger("Hello", function() echo("We matched!") end)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- you can make the trigger match only a certain amount of times as well, 5 in this example:<br />
tempBeginOfLineTrigger("This is the start of the line", function() echo("We matched!") end, 5)<br />
<br />
-- if you want a trigger match not to count towards expiration, return true. In this example it'll match 5 times unless the line is "Start of line and this is the end."<br />
tempBeginOfLineTrigger("Start of line", <br />
function()<br />
if line == "Start of line and this is the end." then<br />
return true<br />
else<br />
return false<br />
end<br />
end, 5)<br />
</syntaxhighlight><br />
<br />
==tempButton==<br />
;tempButton(toolbar name, button text, orientation)<br />
:Creates a temporary button. Temporary means, it will disappear when Mudlet is closed.<br />
<br />
;Parameters:<br />
* ''toolbar name'': The name of the toolbar to place the button into.<br />
* ''button text'': The text to display on the button.<br />
* ''orientation'': a number 0 or 1 where 0 means horizontal orientation for the button and 1 means vertical orientation for the button. This becomes important when you want to have more than one button in the same toolbar.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- makes a temporary toolbar with two buttons at the top of the main Mudlet window <br />
lua tempButtonToolbar("topToolbar", 0, 0)<br />
lua tempButton("topToolbar", "leftButton", 0)<br />
lua tempButton("topToolbar", "rightButton", 0)<br />
</syntaxhighlight><br />
<br />
{{note}} ''This function is not that useful as there is no function yet to assign a Lua script or command to such a temporary button - though it may have some use to flag a status indication!''<br />
<br />
==tempButtonToolbar==<br />
;tempButtonToolbar(name, location, orientation)<br />
:Creates a temporary button toolbar. Temporary means, it will disappear when Mudlet is closed.<br />
<br />
;Parameters:<br />
* ''name'': The name of the toolbar.<br />
* ''location'': a number from 0 to 3, where 0 means "at the top of the screen", 1 means "left side", 2 means "right side" and 3 means "in a window of its own" which can be dragged and attached to the main Mudlet window if needed.<br />
* ''orientation'': a number 0 or 1, where 0 means horizontal orientation for the toolbar and 1 means vertical orientation for the toolbar. This becomes important when you want to have more than one toolbar in the same location of the window.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- makes a temporary toolbar with two buttons at the top of the main Mudlet window <br />
lua tempButtonToolbar("topToolbar", 0, 0)<br />
lua tempButton("topToolbar", "leftButton", 0)<br />
lua tempButton("topToolbar", "rightButton", 0)<br />
</syntaxhighlight><br />
<br />
==tempColorTrigger==<br />
;tempColorTrigger(foregroundColor, backgroundColor, code, expireAfter)<br />
:Makes a color trigger that triggers on the specified foreground and background color. Both colors need to be supplied in form of these simplified ANSI 16 color mode codes. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
See also: [[Manual:Mudlet Object Functions#tempAnsiColorTrigger|tempAnsiColorTrigger]]<br />
;Parameters<br />
* ''foregroundColor:'' The foreground color you'd like to trigger on (for ANSI colors, see [[Manual:Mudlet Object Functions#tempAnsiColorTrigger|tempAnsiColorTrigger]]).<br />
* ''backgroundColor'': The background color you'd like to trigger on (same as above).<br />
* ''code to do'': The code to do when the trigger runs - wrap it in <code>[[</code> and <code>]]</code>, or give it a Lua function, ie. <code>function() <nowiki><your code here></nowiki> end</code> (since Mudlet 3.5.0).<br />
* ''expireAfter'': Delete trigger after a specified number of matches (since Mudlet 3.11). You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
;Color codes<br />
<syntaxhighlight lang="lua"><br />
0 = default text color<br />
1 = light black<br />
2 = dark black<br />
3 = light red<br />
4 = dark red<br />
5 = light green<br />
6 = dark green<br />
7 = light yellow<br />
8 = dark yellow<br />
9 = light blue<br />
10 = dark blue<br />
11 = light magenta<br />
12 = dark magenta<br />
13 = light cyan<br />
14 = dark cyan<br />
15 = light white<br />
16 = dark white<br />
</syntaxhighlight><br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- This script will re-highlight all text in blue foreground colors on a black background with a red foreground color<br />
-- on a blue background color until another color in the current line is being met. temporary color triggers do not <br />
-- offer match_all or filter options like the GUI color triggers because this is rarely necessary for scripting. <br />
-- A common usage for temporary color triggers is to schedule actions on the basis of forthcoming text colors in a particular context.<br />
tempColorTrigger(9, 2, [[selectString(matches[1],1) fg("red") bg("blue")]])<br />
-- or:<br />
tempColorTrigger(9, 2, function()<br />
selectString(matches[1], 1)<br />
fg("red")<br />
bg("blue")<br />
end)<br />
<br />
-- match the trigger only 4 times<br />
tempColorTrigger(9, 2, [[selectString(matches[1],1) fg("red") bg("blue")]], 4)<br />
</syntaxhighlight><br />
<br />
==tempComplexRegexTrigger==<br />
;tempComplexRegexTrigger(name, regex, code, multiline, fg color, bg color, filter, match all, highlight fg color, highlight bg color, play sound file, fire length, line delta, expireAfter)<br />
:Allows you to create a temporary trigger in Mudlet, using any of the UI-available options. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
:Returns the trigger name, that you can use [[Manual:Lua_Functions#killTrigger|killTrigger()]] later on with.<br />
<br />
;Parameters<br />
* ''name'' - The name you call this trigger. <br />
* ''regex'' - The regular expression you want to match.<br />
* ''code'' - Code to do when the trigger runs. You need to wrap it in [[ ]], or give a Lua function (since Mudlet 3.5.0).<br />
* ''multiline'' - Set this to 1, if you use multiple regex (see note below), and you need the trigger to fire only if all regex have been matched within the specified line delta. Then all captures will be saved in ''multimatches'' instead of ''matches''. If this option is set to 0, the trigger will fire when any regex has been matched.<br />
* ''fg color'' - The foreground color you'd like to trigger on.<br />
* ''bg color'' - The background color you'd like to trigger on.<br />
* ''filter'' - Do you want only the filtered content (=capture groups) to be passed on to child triggers? Otherwise also the initial line.<br />
* ''match all'' - Set to 1, if you want the trigger to match all possible occurrences of the regex in the line. When set to 0, the trigger will stop after the first successful match.<br />
* ''highlight fg color'' - The foreground color you'd like your match to be highlighted in.<br />
* ''highlight bg color'' - The background color you'd like your match to be highlighted in.<br />
* ''play sound file'' - Set to the name of the sound file you want to play upon firing the trigger.<br />
* ''fire length'' - Number of lines within which all condition must be true to fire the trigger.<br />
* ''line delta'' - Keep firing the script for x more lines, after the trigger or chain has matched.<br />
* ''expireAfter'' - Delete trigger after a specified number of matches (since Mudlet 3.11). You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
{{Note}} Set the options starting at ''multiline'' to 0, if you don't want to use those options. Otherwise enter 1 to activate or the value you want to use.<br />
<br />
{{Note}} If you want to use the color option, you need to provide both fg and bg together.<br />
<br />
;Examples<br />
<br />
<syntaxhighlight lang="lua"><br />
-- This trigger will be activated on any new line received.<br />
triggerNumber = tempComplexRegexTrigger("anyText", "^(.*)$", [[echo("Text received!")]], 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)<br />
<br />
-- This trigger will match two different regex patterns:<br />
tempComplexRegexTrigger("multiTrigger", "first regex pattern", [[]], 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)<br />
tempComplexRegexTrigger("multiTrigger", "second regex pattern", [[echo("Trigger matched!")]], 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)<br />
</syntaxhighlight><br />
<br />
{{Note}} For making a multiline trigger like in the second example, you need to use the same trigger name and options, providing the new pattern to add. Note that only the last script given will be set, any others ignored.<br />
<br />
==tempExactMatchTrigger==<br />
;tempExactMatchTrigger(exact line, code, expireAfter)<br />
:Creates a trigger that will go off whenever the line from the game matches the provided line exactly (ends the same, starts the same, and looks the same). You don't need to use any of the regex symbols here (^ and $). The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
<br />
;Parameters<br />
* ''exact line'': exact line you'd like to match.<br />
* ''code'': code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function (since Mudlet 3.5.0).<br />
* ''expireAfter'': Delete trigger after a specified number of matches (since Mudlet 3.11). You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
mytriggerID = tempExactMatchTrigger("You have recovered balance on all limbs.", [[echo("We matched!")]])<br />
<br />
-- as a function:<br />
mytriggerID = tempExactMatchTrigger("You have recovered balance on all limbs.", function() echo("We matched!") end)<br />
<br />
-- expire after 4 matches:<br />
tempExactMatchTrigger("You have recovered balance on all limbs.", function() echo("Got balance back!\n") end, 4)<br />
<br />
-- you can also avoid expiration by returning true:<br />
tempExactMatchTrigger("You have recovered balance on all limbs.", function() echo("Got balance back!\n") return true end, 4)<br />
</syntaxhighlight><br />
<br />
==tempKey==<br />
;tempKey([modifier], key code, lua code)<br />
:Creates a keybinding. This keybinding isn't temporary in the sense that it'll go off only once (it'll go off as often as you use it), but rather it won't be saved when Mudlet is closed.<br />
<br />
: See also: [[#permKey|permKey()]], [[#killKey|killKey()]]<br />
<br />
* ''modifier'' <br />
:(optional) modifier to use - can be one of ''mudlet.keymodifier.Control'', ''mudlet.keymodifier.Alt'', ''mudlet.keymodifier.Shift'', ''mudlet.keymodifier.Meta'', ''mudlet.keymodifier.Keypad'', or ''mudlet.keymodifier.GroupSwitch'' or the default value of ''mudlet.keymodifier.None'' which is used if the argument is omitted. To use multiple modifiers, add them together: ''(mudlet.keymodifier.Shift + mudlet.keymodifier.Control)''<br />
* ''key code'' <br />
: actual key to use - one of the values available in ''mudlet.key'', e.g. ''mudlet.key.Escape'', ''mudlet.key.Tab'', ''mudlet.key.F1'', ''mudlet.key.A'', and so on. The list is a bit long to list out in full so it is [https://github.com/Mudlet/Mudlet/blob/development/src/mudlet-lua/lua/KeyCodes.lua#L2 available here].<br />
* ''lua code'<br />
: code you'd like the key to run - wrap it in [[ ]].<br />
<br />
;Returns<br />
* a unique id number for that key.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
keyID = tempKey(mudlet.key.F8, [[echo("hi")]])<br />
<br />
anotherKeyID = tempKey(mudlet.keymodifier.Control, mudlet.key.F8, [[echo("hello")]])<br />
<br />
-- bind Ctrl+Shift+W:<br />
tempKey(mudlet.keymodifier.Control + mudlet.keymodifier.Shift, mudlet.key.W, [[send("jump")]])<br />
<br />
-- delete it if you don't like it anymore<br />
killKey(keyID)<br />
<br />
-- tempKey also accepts functions (and thus closures) - which can be an easier way to embed variables and make the code for tempKeys look less messy:<br />
<br />
tempKey(mudlet.key.F8, function() echo("Hi\n") end)<br />
</syntaxhighlight><br />
<br />
==tempLineTrigger==<br />
;tempLineTrigger(from, howMany, code)<br />
:Temporary trigger that will fire on ''n'' consecutive lines following the current line. This is useful to parse output that is known to arrive in a certain line margin or to delete unwanted output from the game - the trigger does not require any patterns to match on. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
<br />
;Parameters:<br />
* ''from'': from which line after this one should the trigger activate - 1 will activate right on the next line.<br />
* ''howMany'': how many lines to run for after the trigger has activated.<br />
* ''code'': code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function (since Mudlet 3.5.0).<br />
<br />
;Example: <br />
<syntaxhighlight lang="lua"><br />
-- Will fire 3 times with the next line from the game<br />
tempLineTrigger(1, 3, function() print(" trigger matched!") end)<br />
<br />
-- Will fire 5 lines after the current line and fire twice on 2 consecutive lines<br />
tempLineTrigger(5, 2, function() print(" trigger matched!") end, 7)<br />
</syntaxhighlight><br />
<br />
==tempPromptTrigger==<br />
;tempPromptTrigger(code, expireAfter)<br />
:Temporary trigger that will match on the games prompt. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
<br />
{{note}} If the trigger is not working, check that the '''N:''' bottom-right has a number. This feature requires telnet Go-Ahead to be enabled in the game. <br />
<br />
{{MudletVersion|3.6}}<br />
<br />
;Parameters:<br />
* ''code'': <br />
: code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function.<br />
* ''expireAfter'': (available in Mudlet 3.11+)<br />
: Delete trigger after a specified number of matches. You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
;Example: <br />
<syntaxhighlight lang="lua"><br />
tempPromptTrigger(function()<br />
echo("hello! this is a prompt!")<br />
end)<br />
<br />
-- match only 2 times:<br />
tempPromptTrigger(function()<br />
echo("hello! this is a prompt!")<br />
end, 2)<br />
<br />
-- match only 2 times, unless the prompt is "55 health."<br />
tempPromptTrigger(function()<br />
if line == "55 health." then return true end<br />
end, 2)<br />
</syntaxhighlight><br />
<br />
==tempRegexTrigger==<br />
;tempRegexTrigger(regex, code, expireAfter)<br />
:Creates a temporary regex trigger that executes the code whenever it matches. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
<br />
;Parameters:<br />
* ''regex:'' regular expression that lines will be matched on.<br />
* ''code'': code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function (since Mudlet 3.5.0).<br />
* ''expireAfter'': Delete trigger after a specified number of matches (since Mudlet 3.11). You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
;Examples:<br />
<syntaxhighlight lang="lua"><br />
-- create a non-duplicate trigger that matches on any line and calls a function<br />
html5log = html5log or {}<br />
if html5log.trig then killTrigger(html5log.trig) end<br />
html5log.trig = tempRegexTrigger("^", [[html5log.recordline()]])<br />
-- or a simpler variant:<br />
html5log.trig = tempRegexTrigger("^", html5log.recordline)<br />
<br />
-- only match 3 times:<br />
tempRegexTrigger("^You prick (.+) twice in rapid succession with", function() echo("Hit "..matches[2].."!\n") end, 3)<br />
<br />
-- since Mudlet 4.11+ you can use named capturing groups<br />
tempRegexTrigger("^You see (?<material>\\w+) axe inside chest\\.", function() echo("\nAxe is " .. matches.material) end)<br />
</syntaxhighlight><br />
<br />
==tempTimer==<br />
;tempTimer(time, code to do[, repeating])<br />
:Creates a temporary one-shot timer and returns the timer ID, which you can use with [[Manual:Lua_Functions#enableTimer|enableTimer()]], [[Manual:Lua_Functions#disableTimer|disableTimer()]] and [[Manual:Lua_Functions#killTimer|killTimer()]] functions. You can use 2.3 seconds or 0.45 etc. After it has fired, the timer will be deactivated and destroyed, so it will only go off once. Here is a [[Manual:Introduction#Timers|more detailed introduction to tempTimer]].<br />
<br />
;Parameters<br />
* ''time:'' The time in seconds for which to set the timer for - you can use decimals here for precision. The timer will go off ''x'' given seconds after you make it.<br />
* ''code to do'': The code to do when the timer is up - wrap it in [[ ]], or provide a Lua function.<br />
* ''repeating'': (optional) if true, keep firing the timer over and over until you kill it (available in Mudlet 4.0+).<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- wait half a second and then run the command<br />
tempTimer(0.5, function() send("kill monster") end)<br />
<br />
-- echo between 1 and 5 seconds after creation<br />
tempTimer(math.random(1, 5), function() echo("hi!") end) <br />
<br />
-- or an another example - two ways to 'embed' variable in a code for later:<br />
local name = matches[2]<br />
tempTimer(2, [[send("hello, ]]..name..[[ !")]])<br />
-- or:<br />
tempTimer(2, function()<br />
send("hello, "..name)<br />
end)<br />
<br />
-- create a looping timer<br />
timerid = tempTimer(1, function() display("hello!") end, true)<br />
<br />
-- later when you'd like to stop it:<br />
killTimer(timerid)<br />
</syntaxhighlight><br />
<br />
{{note}} Double brackets, e.g: [[ ]] can be used to quote strings in Lua. The difference to the usual `" " quote syntax is that `[[ ]] also accepts the character ". Consequently, you don’t have to escape the " character in the above script. The other advantage is that it can be used as a multiline quote, so your script can span several lines.<br />
<br />
{{note}} Lua code that you provide as an argument is compiled from a string value when the timer fires. This means that if you want to pass any parameters by value e.g. you want to make a function call that uses the value of your variable myGold as a parameter you have to do things like this:<br />
<br />
<syntaxhighlight lang="lua"><br />
tempTimer( 3.8, [[echo("at the time of the tempTimer call I had ]] .. myGold .. [[ gold.")]] )<br />
<br />
-- tempTimer also accepts functions (and thus closures) - which can be an easier way to embed variables and make the code for timers look less messy:<br />
<br />
local variable = matches[2]<br />
tempTimer(3, function () send("hello, " .. variable) end)<br />
</syntaxhighlight><br />
<br />
==tempTrigger==<br />
;tempTrigger(substring, code, expireAfter)<br />
:Creates a substring trigger that executes the code whenever it matches. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
<br />
;Parameters:<br />
* ''substring'': The substring to look for - this means a part of the line. If your provided text matches anywhere within the line from the game, the trigger will go off.<br />
* ''code'': The code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function (since Mudlet 3.5)<br />
* ''expireAfter'': Delete trigger after a specified number of matches (since Mudlet 3.11). You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
Example:<br />
<syntaxhighlight lang="lua"><br />
-- this example will highlight the contents of the "target" variable.<br />
-- it will also delete the previous trigger it made when you call it again, so you're only ever highlighting one name<br />
if id then killTrigger(id) end<br />
id = tempTrigger(target, [[selectString("]] .. target .. [[", 1) fg("gold") resetFormat()]])<br />
<br />
-- you can also write the same line as:<br />
id = tempTrigger(target, function() selectString(target, 1) fg("gold") resetFormat() end)<br />
<br />
-- or like so if you have a highlightTarget() function somewhere<br />
id = tempTrigger(target, highlightTarget)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- a simpler trigger to replace "hi" with "bye" whenever you see it<br />
tempTrigger("hi", [[selectString("hi", 1) replace("bye")]])<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- this trigger will go off only 2 times<br />
tempTrigger("hi", function() selectString("hi", 1) replace("bye") end, 2)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- table to store our trigger IDs in<br />
nameIDs = nameIDs or {}<br />
-- delete any existing triggers we've already got<br />
for _, id in ipairs(nameIDs) do killTrigger(id) end<br />
<br />
-- create new ones, avoiding lots of ]] [[ to embed the name<br />
for _, name in ipairs{"Alice", "Ashley", "Aaron"} do<br />
nameIDs[#nameIDs+1] = tempTrigger(name, function() print(" Found "..name.."!") end)<br />
end<br />
</syntaxhighlight><br />
<br />
;Additional Notes:<br />
tempTriggers begin matching on the same line they're created on. <br />
<br />
If your ''code'' deletes and recreates the tempTrigger, or if you ''send'' a matching command again, it's possible to get into an infinite loop.<br />
<br />
Make use of the ''expireAfter'' parameter, [[Manual:Lua_Functions#disableTrigger|disableTrigger()]], or [[Manual:Lua_Functions#killTrigger|killTrigger()]] to prevent a loop from forming.<br />
<br />
[[Category:Mudlet Manual]]<br />
[[Category:Mudlet API]]</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:UI_Functions&diff=20519Manual:UI Functions2023-08-23T03:40:34Z<p>Demonnic: /* setHexBgColor */</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Mudlet API documentation for functions to construct custom GUIs. They deal mainly with miniconsole/label/gauge creation and manipulation as well as displaying or formatting information on the screen.}}<br />
= UI Functions =<br />
All functions that help you construct custom GUIs. They deal mainly with miniconsole/label/gauge creation and manipulation as well as displaying or formatting information on the screen.<br />
<br />
==addCommandLineMenuEvent==<br />
;addCommandLineMenuEvent([window,] label, eventName)<br />
<br />
Adds item to right click menu associated with command line.<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;See also: [[Manual:Lua_Functions#removeCommandLineMenuEvent|removeCommandLineMenuEvent()]]<br />
<br />
;Parameters<br />
* ''window:''<br />
: Window that command line belongs to. Optional, will default to "main" (main window console)<br />
* ''label:''<br />
: Label of item<br />
* ''eventName:''<br />
: Event name that will be fired when clicked.<br />
<br />
;Returns <br />
* Returns ''true'' if the mouse event was added successfully.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addCommandLineMenuEvent("My very own special paste from clipboard", "pasteFromClipboardWithoutLineBreaks" )<br />
registerAnonymousEventHandler("pasteFromClipboardWithoutLineBreaks", function()<br />
local text = string.gsub(getClipboardText(), "[\r|\n]", "")<br />
appendCmdLine(text)<br />
end)<br />
</syntaxhighlight><br />
<br />
==addMouseEvent==<br />
; addMouseEvent(uniqueName, eventName, [displayName, tooltipText])<br />
<br />
:Registers a new context menu option when right-clicked on a console window. Will return ''true'' if the event was added successfully, otherwise ''nil''+''message'' will be returned. If the ''displayName'' isn't set, ''uniqueName'' will be used for the menu label. ''eventName'' should be a Mudlet event that will handle the click data that includes ''event'', ''unique name'', ''window name'', selection upper left ''column'' and ''row'' and selection bottom right ''column'' and ''row'' in that order. This is intended to be used with available cursor functions for any selection or processing needs.<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
;See also: [[Manual:Lua_Functions#getMouseEvents|getMouseEvents()]], [[Manual:Lua_Functions#moveCursor|moveCursor()]]<br />
<br />
;Parameters<br />
* ''uniqueName:''<br />
: A unique identifier for the mouse event.<br />
* ''eventName:''<br />
: Name of the Mudlet event that will handle the data.<br />
* ''displayName:''<br />
: (optional) Label text for the mouse context menu. If not set, the label defaults to ''uniqueName''.<br />
* ''tooltipText:''<br />
: (optional) Tooltip text when mouse is hovered on the option. If not set, no tooltip will be visible.<br />
<br />
;Returns <br />
* Returns ''true'' if the mouse event was added successfully.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- An example showing implementing a hecho-friendly copy option:<br />
<br />
addMouseEvent("hecho copy", "onMouseCopyExample")<br />
<br />
function rgbToHex(r,g,b)<br />
local rgb = (r * 0x10000) + (g * 0x100) + b<br />
return string.format("#%x", rgb)<br />
end<br />
<br />
function onMouseCopyExample(event, menu, window, startCol, startRow, endCol, endRow)<br />
-- Check whether there's an actual selection<br />
if startCol == endCol and startRow == endRow then return end<br />
local parsed = ""<br />
local lastColor = nil<br />
-- Loop through each symbol within the range<br />
for l = startRow, endRow do<br />
local cStart = l == startRow and startCol or 0<br />
moveCursor(window, cStart, l)<br />
local cEnd = l == endRow and endCol or #getCurrentLine() - 1<br />
for c = cStart, cEnd do<br />
selectSection(window, c, 1)<br />
local symbol = getSelection(window) or ""<br />
-- Convert the foreground color to a hex format, suitable for hecho<br />
local color = rgbToHex(getFgColor(window))<br />
-- Don't repeat the color if previous one was the same<br />
if color == lastColor then<br />
parsed = parsed .. symbol<br />
else<br />
lastColor = color<br />
parsed = parsed .. color .. symbol<br />
end<br />
end<br />
if l ~= endRow then parsed = parsed .. "\n" end<br />
end<br />
setClipboardText(parsed)<br />
end<br />
<br />
registerAnonymousEventHandler("onMouseCopyExample", "onMouseCopyExample")<br />
</syntaxhighlight><br />
<br />
==ansi2decho==<br />
;ansi2decho(text, default_colour)<br />
:Converts ANSI colour sequences in <code>text</code> to colour tags that can be processed by the decho() function.<br />
:See also: [[Manual:Lua_Functions#decho|decho()]]<br />
<br />
{{MudletVersion|3.0}}<br />
{{note}} ANSI bold is available since Mudlet 3.7.1+.<br />
<br />
{{note}} underline, italics, overline, and strikethrough supported since Mudlet 4.15+<br />
<br />
;Parameters<br />
*''text:''<br />
:String that contains ANSI colour sequences that should be replaced.<br />
*''default_colour:''<br />
:Optional - ANSI default colour code (used when handling orphan bold tags).<br />
<br />
; Return values<br />
*''string text:''<br />
:The decho-valid converted text.<br />
*''string colour:''<br />
:The ANSI code for the last used colour in the substitution (useful if you want to colour subsequent lines according to this colour).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local replaced = ansi2decho('\27[0;1;36;40mYou say in a baritone voice, "Test."\27[0;37;40m')<br />
-- 'replaced' should now contain <r><0,255,255:0,0,0>You say in a baritone voice, "Test."<r><192,192,192:0,0,0><br />
decho(replaced)<br />
</syntaxhighlight><br />
<br />
Or show a complete colourful squirrel! It's a lotta code to do all the colours, so click the '''Expand''' button on the right to show it:<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<syntaxhighlight lang="lua"><br />
decho(ansi2decho([[<br />
�[38;5;95m▄�[48;5;95;38;5;130m▄▄▄�[38;5;95m█�[49m▀�[0m �[0m<br />
╭───────────────────────╮ �[38;5;95m▄▄�[0m �[38;5;95m▄�[48;5;95;38;5;130m▄▄�[48;5;130m█�[38;5;137m▄�[48;5;137;38;5;95m▄�[49m▀�[0m �[0m<br />
│ │ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄▄▄�[48;5;95;38;5;137m▄▄▄�[49;38;5;95m▄▄�[48;5;95;38;5;130m▄�[48;5;130m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[0m �[0m<br />
│ Encrypt everything! │ �[38;5;95m▄�[48;5;187;38;5;16m▄�[48;5;16;38;5;187m▄�[38;5;16m█�[48;5;137;38;5;137m███�[38;5;187m▄�[38;5;16m▄▄�[38;5;137m██�[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[0m �[0m<br />
│ ├──── �[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;16m▄▄▄�[48;5;137m███�[48;5;16;38;5;16m█�[48;5;187m▄�[48;5;16m█�[48;5;137;38;5;137m█�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
╰───────────────────────╯ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;16m▄�[38;5;16m█�[38;5;137m▄�[48;5;137m██████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;95m▀�[48;5;137m▄�[38;5;137m███████�[38;5;95m▄�[49m▀�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[48;5;95;38;5;187m▄▄▄�[38;5;137m▄�[48;5;137m██�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[38;5;95m▀�[48;5;130m▄�[38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;187m████�[48;5;137;38;5;137m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m██�[38;5;95m▄�[38;5;137m█�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;187;38;5;187m████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95m██�[48;5;137m▄▄�[48;5;187;38;5;187m████�[48;5;137;38;5;95m▄▄�[48;5;95;38;5;137m▄�[48;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;187;38;5;187m███�[48;5;95m▄�[38;5;137m▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[49m▄�[48;5;95;38;5;130m▄�[48;5;130m██████�[48;5;137;38;5;137m███�[38;5;95m▄�[49m▀�[0m�[0m<br />
�[48;5;187;38;5;95m▄�[38;5;187m████�[48;5;137;38;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m█████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;137m▄�[38;5;187m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██████�[48;5;95m▄▄�[48;5;130m▄▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▄▄▄�[48;5;95;38;5;137m▄�[48;5;187m▄�[38;5;187m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m█████�[38;5;95m▄�[38;5;137m███████████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀�[48;5;187m▄▄▄�[48;5;95;38;5;137m▄�[48;5;137m██�[38;5;95m▄�[49m▀�[0m �[38;5;95m▀▀�[48;5;137m▄▄▄▄▄▄�[49m▀▀▀�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀▀�[0m �[0m<br />
]]))<br />
</syntaxhighlight><br />
</div><br />
<br />
[[File:Squirrel-in-Mudlet.png|frameless]]<br />
<br />
==ansi2string==<br />
;ansi2string(text)<br />
: Strips ANSI colour sequences from a string (text)<br />
: See also: [[Manual:Lua_Functions#ansi2decho|ansi2decho()]]<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
;Parameters<br />
* ''text:''<br />
: String that contains ANSI colour sequences that should be removed.<br />
<br />
;Return values<br />
* ''string text:''<br />
: The plain text without ANSI colour sequences.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local replaced = ansi2string('\27[0;1;36;40mYou say in a baritone voice, "Test."\27[0;37;40m')<br />
-- 'replaced' should now contain You say in a baritone voice, "Test."<br />
print(replaced)<br />
</syntaxhighlight><br />
<br />
==appendBuffer==<br />
;appendBuffer(name)<br />
: Pastes the previously copied rich text (including text formats like color etc.) into user window name.<br />
: See also: [[#selectCurrentLine|selectCurrentLine()]], [[#copy|copy()]], [[Manual:Lua_Functions#paste|paste()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name of the user window to paste into. Passed as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--selects and copies an entire line to user window named "Chat"<br />
selectCurrentLine()<br />
copy()<br />
appendBuffer("Chat")<br />
</syntaxhighlight><br />
<br />
==bg==<br />
;bg([window, ]colorName)<br />
: Changes the background color of the text. Useful for highlighting text.<br />
: See Also: [[Manual:Lua_Functions#fg|fg()]], [[Manual:Lua_Functions#setBgColor|setBgColor()]]<br />
<br />
;Parameters<br />
* ''window:''<br />
: The miniconsole to operate on - optional. If you'd like it to work on the main window, don't specify anything, or use ''main'' (since Mudlet 3.0).<br />
* ''colorName:''<br />
: The name of the color to set the background to. [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This would change the background color of the text on the current line to magenta<br />
selectCurrentLine()<br />
bg("magenta")<br />
<br />
-- or echo text with a green background to a miniconsole<br />
bg("my window", "green")<br />
echo("my window", "some green text\n")<br />
</syntaxhighlight><br />
<br />
==calcFontSize==<br />
;calcFontSize(window_or_fontsize, [fontname])<br />
: Returns the average height and width of characters in a particular window, or a font name and size combination. Helpful if you want to size a miniconsole to specific dimensions.<br />
: Returns two numbers, width/height<br />
: See also: [[Manual:Lua_Functions#setMiniConsoleFontSize|setMiniConsoleFontSize()]], [[Manual:Lua_Functions#getMainWindowSize|getMainWindowSize()]]<br />
<br />
;Parameters<br />
* ''window_or_fontsize:''<br />
: The miniconsole or font size you are wanting to calculate pixel sizes for.<br />
* ''fontname:''<br />
: Specific font name (along with the size as the first argument) to calculate for.<br />
<br />
{{note}}<br />
Window as an argument is available in Mudlet 3.10+, and font name in Mudlet 4.1+.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--this snippet will calculate how wide and tall a miniconsole designed to hold 4 lines of text 20 characters wide<br />
--would need to be at 9 point font, and then changes miniconsole Chat to be that size<br />
local width,height = calcFontSize(9)<br />
width = width * 20<br />
height = height * 4<br />
resizeWindow("Chat", width, height)<br />
</syntaxhighlight><br />
<br />
==cecho==<br />
; cecho([window], text)<br />
:Echoes text that can be easily formatted with colour, italics, bold, strikethrough, and underline tags. You can also include unicode art in it - try some examples from [http://1lineart.kulaone.com/#/ 1lineart].<br />
:See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:UI Functions#creplaceLine|creplaceLine()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you cecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
*''window:''<br />
:Optional - the window name to echo to - can either be none or "main" for the main window, or a miniconsole, userwindow, or label name.<br />
*''text:''<br />
:The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
cecho("Hi! This text is <red>red, <blue>blue, <green> and green.")<br />
<br />
cecho("<:green>Green background on normal foreground. Here we add an <ivory>ivory foreground.")<br />
<br />
cecho("<blue:yellow>Blue on yellow text!")<br />
<br />
cecho("\n<red>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, <o>overline</o>, and <b>bold</b>.")<br />
<br />
cecho("\n<green><o><u>Green text with over and underline at the same time.</o></u>")<br />
<br />
-- \n adds a new line<br />
cecho("<red>one line\n<green>another line\n<blue>last line")<br />
<br />
cecho("myinfo", "<green>All of this text is green in the myinfo miniconsole.")<br />
<br />
cecho("<green>(╯°□°)<dark_green>╯︵ ┻━┻")<br />
<br />
cecho("°º¤ø,¸¸,ø¤º°`°º¤ø,¸,ø¤°º¤ø,¸¸,ø¤º°`°º¤ø,¸")<br />
<br />
cecho([[<br />
██╗ ██╗ ██╗███╗ ██╗███████╗ █████╗ ██████╗ ████████╗<br />
███║ ██║ ██║████╗ ██║██╔════╝ ██╔══██╗██╔══██╗╚══██╔══╝<br />
╚██║ ██║ ██║██╔██╗ ██║█████╗ ███████║██████╔╝ ██║<br />
██║ ██║ ██║██║╚██╗██║██╔══╝ ██╔══██║██╔══██╗ ██║<br />
██║ ███████╗██║██║ ╚████║███████╗ ██║ ██║██║ ██║ ██║<br />
╚═╝ ╚══════╝╚═╝╚═╝ ╚═══╝╚══════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝<br />
]])<br />
</syntaxhighlight><br />
<br />
==cechoLink==<br />
;cechoLink([windowName], text, command, hint, true)<br />
: Echos a piece of text as a clickable link, at the end of the current selected line - similar to [[Manual:Lua_Functions#cecho|cecho()]]. This version allows you to use colours within your link text.<br />
<br />
: See also: [[#echoLink|echoLink()]], [[#dechoLink|dechoLink()]], [[#hechoLink|hechoLink()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: optional parameter, allows selection between sending the link to a miniconsole or the main window.<br />
* ''text:''<br />
: text to display in the echo. Same as a normal [[Manual:Lua_Functions#cecho|cecho()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''true:''<br />
: requires argument for the colouring to work.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
cechoLink("<red>press <brown:white>me!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
cechoLink("<red>press <brown:white>me!", [[send("hi")]], "This is a tooltip", true)<br />
</syntaxhighlight><br />
<br />
==cecho2ansi==<br />
;ansiFormattedString = cecho2ansi(text)<br />
<br />
:Converts cecho formatted text to ansi formatted text. Used by cfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also:[[Manual:Lua_Functions#cecho|cecho()]], [[Manual:Lua_Functions#cfeedTriggers|cfeedTriggers()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
{{note}} This function uses the ansi short colors (0-15) for color names which have base 16 ansi equivalents, such as 'red', 'blue', "lightBlue", "cyan", etc rather than the values defined in the color_table. If there is no base ansi equivalent then it will use the rgb values from the color_table for the color.<br />
<br />
;Parameters<br />
*''text:''<br />
:The cecho formatted text for conversion<br />
<br />
;Returns<br />
*String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of cfeedTriggers() for a single line.<br />
-- you would most likely just use cfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(cecho2ansi("\n<red>This is red.<reset> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
<br />
==cechoPopup==<br />
;cechoPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current line, like [[#cecho|cecho()]]. 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.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. ie, <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
cechoPopup("<red>activities<reset> to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"}, true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
cechoPopup("<red>activities<reset> to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"}, true)<br />
</syntaxhighlight><br />
<br />
==cinsertLink==<br />
;cinsertLink([windowName], text, command, hint, true)<br />
: Echos a piece of text as a clickable link, at the end of the current cursor position - similar to [[#cinsertText|cinsertText()]]. This version allows you to use colours within your link text.<br />
<br />
: See also: [[#insertLink|insertLink()]], [[#hinsertLink|hinsertLink()]]<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: optional parameter, allows selection between sending the link to a miniconsole or the main window.<br />
* ''text:''<br />
: text to display in the echo. Same as a normal [[Manual:Lua_Functions#cecho|cecho()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''true:''<br />
: requires argument for the colouring to work.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
cinsertLink("<red>press <brown:white>me!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
cinsertLink("<red>press <brown:white>me!", [[send("hi")]], "This is a tooltip", true)<br />
</syntaxhighlight><br />
<br />
==cinsertPopup==<br />
;cinsertPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current cursor position, like [[#cinsertText|cinsertText()]]. 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.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. ie, <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
cinsertPopup("<red>activities<reset> to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"}, true)<br />
<br />
-- Create some text as a clickable with a popup menu:<br />
cinsertPopup("<red>activities<reset> to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"}, true)</syntaxhighlight><br />
<br />
==cinsertText==<br />
;cinsertText([window], text)<br />
: inserts text at the current cursor position, with the possibility for color tags.<br />
: See Also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:UI Functions#creplaceLine|creplaceLine()]]<br />
<br />
;Parameters<br />
* ''window:''<br />
: Optional - the window name to echo to - can either be none or "main" for the main window, or the miniconsoles name.<br />
* ''text:''<br />
: The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a double colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
cinsertText("Hi! This text is <red>red, <blue>blue, <green> and green.")<br />
<br />
cinsertText("<:green>Green background on normal foreground. Here we add an <ivory>ivory foreground.")<br />
<br />
cinsertText("<blue:yellow>Blue on yellow text!")<br />
<br />
cinsertText("myinfo", "<green>All of this text is green in the myinfo miniconsole.")<br />
</syntaxhighlight><br />
<br />
==clearUserWindow==<br />
;clearUserWindow([name])<br />
: This is (now) identical to [[Manual:Lua_Functions#clearWindow|clearWindow()]].<br />
<br />
==clearWindow==<br />
;clearWindow([windowName])<br />
: Clears the label, mini console, or user window with the name given as argument (removes all text from it). If you don't give it a name, it will clear the main window.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) The name of the label, mini console, or user window to clear. Passed as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This would clear a label, user window, or miniconsole with the name "Chat"<br />
clearWindow("Chat")<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- this can clear your whole main window<br />
clearWindow()<br />
</syntaxhighlight><br />
<br />
==closestColor==<br />
; closestColor(colorOrR[,G,B])<br />
<br />
:Returns the closest color from the color_table to the one provided for use in cecho and associated functions.<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
;Parameters<br />
* ''colorOrR:''<br />
: Either the string representation of a color from decho or hecho (IE "#ff0077" or "<255,0,128>"), a table of color values (IE {255,0,18}), or the Red component of RGB when followed by two next optional parameters<br />
* ''G:''<br />
: (optional) green component of RGB coordinates. Only needed if first parameter sent as the Red component only<br />
* ''B:''<br />
: (optional) blue component of RGB coordinates. Only needed if first parameter sent as the Red component only<br />
<br />
;Returns<br />
* The closest color name from the color_table to the one supplied on success<br />
* nil + error if it cannot parse the parameters into a color.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local colorName = closestColor(255, 0, 0) -- "ansi_light_red"<br />
local colorName = closestColor({127, 255, 127}) -- "ansi_120"<br />
local colorName = closestColor("<127, 127, 127>") -- "ansi_008"<br />
local colorName = closestColor("#a020e6") -- "purple"<br />
local colorName = closestColor("blue") -- "blue" (you wouldn't necessarily do this on purpose, but during automated color conversions this might occur)<br />
</syntaxhighlight><br />
<br />
==copy==<br />
; copy([windowName])<br />
: Copies the current selection to the lua virtual clipboard. This function operates on rich text, i. e. the selected text including all its format codes like colors, fonts etc. in the lua virtual clipboard until it gets overwritten by another copy operation.<br />
: See also: [[#selectString|selectString()]], [[#selectCurrentLine|selectCurrentLine()]], [[#paste|paste()]], [[#appendBuffer|appendBuffer()]], [[#replace|replace()]], [[#createMiniConsole|createMiniConsole()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
; Parameters<br />
* ''windowName'' (optional):<br />
: the window from which to copy text - use the main console if not specified.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This script copies the current line on the main screen to a window (miniconsole or userwindow) called 'chat' and gags the output on the main screen.<br />
selectString(line, 1)<br />
copy()<br />
appendBuffer("chat")<br />
replace("This line has been moved to the chat window!")<br />
</syntaxhighlight><br />
<br />
==copy2decho==<br />
; copy2decho([window], [stringToCopy], [instanceToCopy])<br />
: Copies a string from the current line of window, including color information in decho format.<br />
: See also: [[#decho|decho()]]<br />
{{MudletVersion|4.8}}<br />
<br />
; Parameters<br />
* ''window'' (optional):<br />
: the window to copy the text from. Defaults to "main".<br />
* ''stringToCopy'' (optional): <br />
: the string to copy. Defaults to copying the entire line.<br />
* ''instanceToCopy'' (optional):<br />
: the instance of the string to copy. Defaults to 1.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This copies the current line on the main console and dechos it to a miniconsole named "test"<br />
decho("test", copy2decho())<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- This when put into a trigger would copy matches[2] with color information and decho it to a Geyser miniconsole stored as the variable enemylist<br />
enemylist:decho(copy2decho(matches[2]))<br />
</syntaxhighlight><br />
<br />
==copy2html==<br />
; copy2html([window], [stringToCopy], [instanceToCopy])<br />
: Copies a string from the current line of window, including color information in html format for echoing to a label.<br />
{{MudletVersion|4.8}}<br />
<br />
; Parameters<br />
* ''window'' (optional):<br />
: the window to copy the text from. Defaults to "main"<br />
* ''stringToCopy'' (optional): <br />
: the string to copy. Defaults to copying the entire line<br />
* ''instanceToCopy'' (optional):<br />
: the instance of the string to copy. Defaults to 1<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This copies the current line on the main console and echos it to a label named "TestLabel"<br />
echo("TestLabel", copy2html())<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- This when put into a trigger would copy matches[2] with color information and echo it to a Geyser label stored as the variable enemylist<br />
enemylist:echo(copy2html(matches[2]))<br />
</syntaxhighlight><br />
<br />
==createBuffer==<br />
;createBuffer(name)<br />
: Creates a named buffer for formatted text, much like a miniconsole, but the buffer is not intended to be shown on the screen - use it for formatting text or storing formatted text.<br />
<br />
: See also: [[#selectString|selectString()]], [[#selectCurrentLine|selectCurrentLine()]], [[#copy|copy()]], [[#paste|paste()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name of the buffer to create.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This creates a named buffer called "scratchpad"<br />
createBuffer("scratchpad")<br />
</syntaxhighlight><br />
<br />
==createCommandLine==<br />
;createCommandLine([name of userwindow], name, x, y, width, height)<br />
: Creates a new command line inside the main window of Mudlet. If only a command line inside a miniConsole/UserWindow is needed see [[Manual:UI_Functions#enableCommandLine|enableCommandLine()]].<br />
: You can use [[Manual:Mudlet_Object_Functions#appendCmdLine|appendCmdLine()]] / [[Manual:Mudlet_Object_Functions#getCmdLine|getCmdLine()]] and other command line functions to customize the input.<br />
{{note}} [[Manual:UI_Functions#setCmdLineAction|setCmdLineAction]] allows you to attach an action to your command line input.<br />
<br />
: Returns true or false.<br />
<br />
: See also: [[Manual:UI_Functions#enableCommandLine|enableCommandLine()]], [[Manual:UI_Functions#disableCommandLine|disableCommandLine()]], [[Manual:Mudlet_Object_Functions#clearCmdLine|clearCmdLine()]], [[Manual:Mudlet_Object_Functions#getCmdLine|getCmdLine()]], [[Manual:Mudlet_Object_Functions#printCmdLine|printCmdLine()]], [[Manual:Mudlet_Object_Functions#appendCmdLine|appendCmdLine()]], , [[#selectCmdLineText|selectCmdLineText()]]<br />
<br />
;Parameters<br />
* ''name of userwindow:''<br />
: Name of userwindow the command line is created in. Optional, defaults to the main window if not provided.<br />
* ''name:''<br />
: The name of the command line. Must be unique. Passed as a string.<br />
* ''x'', ''y'', ''width'', ''height''<br />
: Parameters to set the command line size and location - it is also possible to set them by using [[Manual:Lua_Functions#moveWindow|moveWindow()]] and [[Manual:Lua_Functions#resizeWindow|resizeWindow()]], as createCommandLine() will only set them once.<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
==createConsole==<br />
;createConsole([name of userwindow], consoleName, fontSize, charsPerLine, numberOfLines, Xpos, Ypos)<br />
: Makes a new miniconsole which can be sized based upon the width of a 'W' character and the extreme top and bottom positions any character of the font should use. The background will be black, and the text color white.<br />
<br />
;Parameters<br />
* ''name of userwindow:''<br />
: Name of userwindow your new miniconsole is created in. Optional, defaults to the main window if not provided.<br />
* ''consoleName:''<br />
: The name of your new miniconsole. Passed as a string.<br />
* ''fontSize:''<br />
: The font size to use for the miniconsole. Passed as an integer number.<br />
* ''charsPerLine:''<br />
: How many characters wide to make the miniconsole. Passed as an integer number.<br />
* ''numberOfLines:''<br />
: How many lines high to make the miniconsole. Passed as an integer number.<br />
* ''Xpos:''<br />
: X position of miniconsole. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''Ypos:''<br />
: Y position of miniconsole. Measured in pixels, with 0 being the very top. Passed as an integer number.<br />
<br />
{{note}}<br />
userwindow argument only available in 4.6.1+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- this will create a console with the name of "myConsoleWindow", font size 8, 80 characters wide,<br />
-- 20 lines high, at coordinates 300x,400y<br />
createConsole("myConsoleWindow", 8, 80, 20, 200, 400)<br />
</syntaxhighlight><br />
<br />
{{note}}<br />
''(For Mudlet Makers)'' This function is implemented outside the application's core via the '''GUIUtils.lua''' file of the Mudlet supporting Lua code using [[Manual:UI_Functions#createMiniConsole|createMiniConsole()]] and other functions to position and size the mini-console and configure the font.<br />
<br />
==createGauge==<br />
;createGauge([name of userwindow], name, width, height, Xpos, Ypos, gaugeText, r, g, b, orientation)<br />
;createGauge([name of userwindow], name, width, height, Xpos, Ypos, gaugeText, colorName, orientation)<br />
: Creates a gauge that you can use to express completion with. For example, you can use this as your healthbar or xpbar.<br />
: See also: [[Manual:Lua_Functions#moveGauge|moveGauge()]], [[Manual:Lua_Functions#setGauge|setGauge()]], [[Manual:Lua_Functions#setGaugeText|setGaugeText()]], [[#setGaugeStyleSheet|setGaugeStyleSheet()]]<br />
<br />
;Parameters<br />
* ''name of userwindow:''<br />
: Name of userwindow the gauge is created in. Optional, defaults to the main window if not provided.<br />
* ''name:''<br />
: The name of the gauge. Must be unique, you can not have two or more gauges with the same name. Passed as a string.<br />
* ''width:''<br />
: The width of the gauge, in pixels. Passed as an integer number.<br />
* ''height:''<br />
: The height of the gauge, in pixels. Passed as an integer number.<br />
* ''Xpos:''<br />
: X position of gauge. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''Ypos:''<br />
: Y position of gauge. Measured in pixels, with 0 being the very top. Passed as an integer number.<br />
* ''gaugeText:''<br />
: Text to display on the gauge. Passed as a string, unless you do not wish to have any text, in which case you pass nil<br />
* ''r:''<br />
: The red component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''g:''<br />
: The green component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''b:''<br />
: The blue component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''colorName:''<br />
: the name of color for the gauge. Passed as a string.<br />
* ''orientation:''<br />
: the gauge orientation. Can be horizontal (fills from left to right), vertical (fills bottom to top), goofy (fills right to left), or batty (fills top to bottom).<br />
<br />
{{note}}<br />
userwindow argument only available in 4.6.1+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This would make a gauge at that's 300px width, 20px in height, located at Xpos and Ypos and is green.<br />
-- The second example is using the same names you'd use for something like [[fg]]() or [[bg]]().<br />
createGauge("healthBar", 300, 20, 30, 300, nil, 0, 255, 0)<br />
createGauge("healthBar", 300, 20, 30, 300, nil, "green")<br />
<br />
<br />
-- If you wish to have some text on your label, you'll change the nil part and make it look like this:<br />
createGauge("healthBar", 300, 20, 30, 300, "Now with some text", 0, 255, 0)<br />
-- or<br />
createGauge("healthBar", 300, 20, 30, 300, "Now with some text", "green")<br />
</syntaxhighlight><br />
<br />
{{note}}<br />
If you want to put text on the back of the gauge when it's low, use an echo with the <gauge name>_back.<br />
<syntaxhighlight lang="lua"><br />
echo("healthBar_back", "This is a test of putting text on the back of the gauge!")<br />
</syntaxhighlight><br />
<br />
==createLabel==<br />
;createLabel([name of userwindow], name, Xpos, Ypos, width, height, fillBackground, [enableClickthrough])<br />
: Creates a highly manipulable overlay which can take some css and html code for text formatting. Labels are clickable, and as such can be used as a sort of button. Labels are meant for small variable or prompt displays, messages, images, and the like. You should not use them for larger text displays or things which will be updated rapidly and in high volume, as they are much slower than miniconsoles.<br />
: Returns true or false.<br />
: See also: [[Manual:Lua_Functions#hideWindow|hideWindow()]], [[Manual:Lua_Functions#showWindow|showWindow()]], [[Manual:Lua_Functions#resizeWindow|resizeWindow()]], [[Manual:Lua_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:Lua_Functions#setTextFormat|setTextFormat()]], [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#moveWindow|moveWindow()]], [[Manual:Lua_Functions#setBackgroundColor|setBackgroundColor()]], [[Manual:Lua_Functions#getMainWindowSize|getMainWindowSize()]], [[Manual:Lua_Functions#calcFontSize|calcFontSize()]], [[Manual:Lua_Functions#deleteLabel|deleteLabel()]]<br />
<br />
;Parameters<br />
* ''name of userwindow:'' Name of userwindow label is created in. Optional, defaults to the main window if not provided.<br />
* ''name:'' name of the label. Must be unique, you can not have two or more labels with the same name. Passed as a string.<br />
* ''Xpos:'' X position of the label. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''Ypos:'' Y position of the label. Measured in pixels, with 0 being the very top. Passed as an integer number.<br />
* ''width:'' width of the label, in pixels. Passed as an integer number.<br />
* ''height:'' height of the label, in pixels. Passed as an integer number.<br />
* ''fillBackground:'' whether or not to display the background. Passed as integer number (1 or 0) or as boolean (true, false). 1 or true will display the background color, 0 or false will not.<br />
* ''enableClickthrough:'' whether or not enable clickthrough on this label. Passed as integer number (1 or 0) or as boolean (true, false). 1 or true will enable clickthrough, 0 or false will not. Optional, defaults to clickthrough not enabled if not provided.<br />
<br />
{{note}}<br />
userwindow argument only available in 4.6.1+<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
-- a label situated at x=300 y=400 with dimensions 100x200<br />
createLabel("a very basic label",300,400,100,200,1)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- this example creates a transparent overlay message box to show a big warning message "You are under attack!" in the middle<br />
-- of the screen. Because the background color has a transparency level of 150 (0-255, with 0 being completely transparent<br />
-- and 255 opaque) the background text can still be read through.<br />
local width, height = getMainWindowSize()<br />
createLabel("messageBox",(width/2)-300,(height/2)-100,250,150,1)<br />
resizeWindow("messageBox",500,70)<br />
moveWindow("messageBox", (width/2)-300,(height/2)-100 )<br />
setBackgroundColor("messageBox", 255, 204, 0, 200)<br />
echo("messageBox", [[<p style="font-size:35px"><b><center><font color="red">You are under attack!</font></center></b></p>]])<br />
<br />
-- you can also make it react to clicks!<br />
mynamespace = {<br />
messageBoxClicked = function()<br />
echo("hey you've clicked the box!\n")<br />
end<br />
}<br />
<br />
setLabelClickCallback("messageBox", "mynamespace.messageBoxClicked")<br />
<br />
<br />
-- uncomment code below to make it also hide after a short while<br />
-- tempTimer(2.3, [[hideWindow("messageBox")]] ) -- close the warning message box after 2.3 seconds<br />
</syntaxhighlight><br />
<br />
==createMiniConsole==<br />
;createMiniConsole([name of userwindow], name, x, y, width, height)<br />
: Opens a miniconsole window inside the main window of Mudlet. This is the ideal fast colored text display for everything that requires a bit more text, such as status screens, chat windows, etc. Unlike labels, you cannot have transparency in them.<br />
: You can use [[Manual:Lua_Functions#clearWindow|clearWindow()]] / [[Manual:Lua_Functions#moveCursor|moveCursor()]] and other functions for this window for custom printing as well as copy & paste functions for colored text copies from the main window. [[Manual:Lua_Functions#setWindowWrap|setWindowWrap()]] will allow you to set word wrapping, and move the main window to make room for miniconsole windows on your screen (if you want to do this as you can also layer mini console and label windows) see [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#setBorderColor|setBorderColor()]] functions.<br />
<br />
: Returns true or false.<br />
<br />
: See also: [[Manual:Lua_Functions#createLabel|createLabel()]], [[Manual:Lua_Functions#hideWindow|hideWindow()]], [[Manual:Lua_Functions#showWindow|showWindow()]], [[Manual:Lua_Functions#resizeWindow|resizeWindow()]], [[Manual:Lua_Functions#setTextFormat|setTextFormat()]], [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#moveWindow|moveWindow()]], [[Manual:Lua_Functions#setMiniConsoleFontSize|setMiniConsoleFontSize()]], [[Manual:Lua_Functions#handleWindowResizeEvent|handleWindowResizeEvent()]], [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#setWindowWrap|setWindowWrap()]], [[Manual:Lua_Functions#getMainWindowSize|getMainWindowSize()]], [[Manual:Lua_Functions#setMainWindowSize|setMainWindowSize()]], [[Manual:Lua_Functions#calcFontSize|calcFontSize()]]<br />
<br />
;Parameters<br />
* ''name of userwindow:'' (available in Mudlet 4.6.1+)<br />
: (Optional) name of userwindow the miniconsole is created in. Defaults to the main window if not provided.<br />
* ''name:''<br />
: The name of the miniconsole. Must be unique. Passed as a string.<br />
* ''x'', ''y'', ''width'', ''height''<br />
: Parameters to set set the window size and location - in Mudlet version 2.1 and below it's best to set them via [[Manual:Lua_Functions#moveWindow|moveWindow()]] and [[Manual:Lua_Functions#resizeWindow|resizeWindow()]], as createMiniConsole() will only set them once. Starting with Mudlet version 3.0, however, that is fine and calling createMiniConsole() will re-position your miniconsole appropriately.<br />
<br />
==createScrollBox==<br />
;createScrollBox([name of parent window], name, x, y, width, height)<br />
<br />
: creates a graphical elements able to hold other graphical elements such as labels, miniconsoles, command lines etc. in it.<br />
If the added elements don't fit into the ScrollBox scrollbars appear and allow scrolling.<br />
: Returns true or false.<br />
<br />
: See also: [[Manual:Lua_Functions#createLabel|createLabel()]], [[Manual:Lua_Functions#hideWindow|hideWindow()]], [[Manual:Lua_Functions#showWindow|showWindow()]], [[Manual:Lua_Functions#resizeWindow|resizeWindow()]], [[Manual:Lua_Functions#moveWindow|moveWindow()]], [[Manual:Lua_Functions#setWindow|setWindow()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''name of parent window:'' <br />
: (Optional) name of the parent window the scrollBox is created in. Defaults to the main window if not provided.<br />
* ''name:''<br />
: The name of the scrollBox. Must be unique. Passed as a string.<br />
* ''x'', ''y'', ''width'', ''height''<br />
: Parameters to set set the window size and location<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create a ScrollBox with the name sBox<br />
createScrollBox("SBox",0,0,300,200)<br />
<br />
-- create 3 Labels and put them into the ScrollBox<br />
createLabel("SBox","SBoxLabel",0,0,200,200,1)<br />
createLabel("SBox","SBoxLabel2",200,0,200,200,1)<br />
createLabel("SBox","SBoxLabel3",400,0,200,200,1)<br />
<br />
-- put some text on the labels<br />
echo("SBoxLabel","Label")<br />
echo("SBoxLabel2","Label2")<br />
echo("SBoxLabel3","Label3")<br />
<br />
-- change the colours of the labels to make it easier to distinguish them<br />
setBackgroundColor("SBoxLabel",255,0,0)<br />
setBackgroundColor("SBoxLabel2",0,255,0)<br />
setBackgroundColor("SBoxLabel3",0,0,255)<br />
</syntaxhighlight><br />
<br />
==creplace==<br />
;creplace([window, ]text)<br />
: Replaces the output line from the game with a colour-tagged string.<br />
See Also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:Lua_Functions#cinsertText|cinsertText()]]<br />
;Parameters<br />
* ''window:''<br />
*: The window to replace the selection in. Optional, defaults to the main window if not provided.<br />
* ''text:''<br />
*: The text to display, with color names inside angle brackets as with [[Manual:Lua_Functions#cecho|cecho()]]. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectCaptureGroup(1)<br />
creplace("<magenta>[ALERT!]: <reset>"..matches[2])<br />
</syntaxhighlight><br />
<br />
==creplaceLine==<br />
;creplaceLine ([window], text)<br />
: Replaces the output line from the game with a colour-tagged string.<br />
See Also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:Lua_Functions#cinsertText|cinsertText()]]<br />
;Parameters<br />
* ''window'' (optional):<br />
: the window to copy the text from. Defaults to "main". Only supported in Mudlet 4.12+<br />
* ''text:''<br />
*: The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua">creplaceLine("<magenta>[ALERT!]: <reset>"..line)<br />
</syntaxhighlight><br />
<br />
==decho==<br />
;decho ([name of console,] text)<br />
:Color changes can be made using the format <FR,FG,FB:BR,BG,BB,[BA]> where each field is a number from 0 to 255. The background portion can be omitted using <FR,FG,FB> or the foreground portion can be omitted using <:BR,BG,BB,[BA]>. Arguments 2 and 3 set the default fore and background colors for the string using the same format as is used within the string, sans angle brackets, e.g. ''decho("<50,50,0:0,255,0>test")''.<br />
:You can also include <code><nowiki><i>italics</i></nowiki></code>, <code><nowiki><b>bold</b></nowiki></code>, <code><nowiki><s>strikethrough</s></nowiki></code>, <code><nowiki><o>overline</o></nowiki></code>, and <code><nowiki><u>underline</u></nowiki></code> tags.<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you decho it will erase any previous echo sent to the label.<br />
<br />
:See also: [[#cecho|cecho()]], [[#hecho|hecho()]], [[#copy2decho|copy2decho()]]<br />
<br />
;Parameters<br />
*''name of console''<br />
:(Optional) Name of the console to echo to. If no name is given, this will defaults to the main window.<br />
*''text:''<br />
:The text that you’d like to echo with embedded color tags. Tags take the RGB values only, see below for an explanation.<br />
<br />
<br />
{{note}}<br />
Optional background transparancy parameter (BA) available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
decho("<50,50,0:0,255,0>test")<br />
<br />
decho("miniconsolename", "<50,50,0:0,255,0>test")<br />
<br />
decho("\n<255,0,0>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, and <b>bold</b> formatting.")<br />
<br />
decho("<\n<0,128,0><o><u>Green text with both over and underlines.</u></o>")<br />
</syntaxhighlight><br />
<br />
==decho2ansi==<br />
;ansiFormattedString = decho2ansi(text)<br />
<br />
:Converts decho formatted text to ansi formatted text. Used by dfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also:[[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#dfeedTriggers|dfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
; Parameters<br />
*''text:''<br />
:The decho formatted text for conversion<br />
<br />
;Returns<br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of dfeedTriggers() for a single line.<br />
-- you would most likely just use dfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(decho2ansi("\n<128,0,0>This is red.<r> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
==dechoLink==<br />
;dechoLink([windowName], text, command, hint, true)<br />
: Echos a piece of text as a clickable link, at the end of the current selected line - similar to [[Manual:Lua_Functions#decho|decho()]]. This version allows you to use colours within your link text.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) allows selection between sending the link to a miniconsole or the "main" window.<br />
* ''text:''<br />
: text to display in the echo. Same as a normal [[Manual:Lua_Functions#decho|decho()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''true:''<br />
: requires argument for the colouring to work.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
dechoLink("<50,50,0:0,255,0>press me!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
dechoLink("<50,50,0:0,255,0>press me!", [[send("hi")]], "This is a tooltip", true)<br />
</syntaxhighlight><br />
<br />
==dechoPopup==<br />
;dechoPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current line, like [[#decho|decho()]]. 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.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code strings to do or a functions (since Mudlet 4.11). ie, <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
dechoPopup("<255,0,0>activities<r> to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"}, true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
dechoPopup("<255,0,0>activities<r> to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"}, true)<br />
</syntaxhighlight><br />
<br />
==dinsertLink==<br />
;dinsertLink([windowName], text, command, hint, true)<br />
: Echos a piece of text as a clickable link, at the end of the current cursor position - similar to [[#dinsertText|dinsertText()]]. This version allows you to use colours within your link text.<br />
<br />
: See also: [[#insertLink|insertLink()]], [[#hinsertLink|hinsertLink()]]<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: optional parameter, allows selection between sending the link to a miniconsole or the main window.<br />
* ''text:''<br />
: text to display in the echo. Same as a normal [[Manual:Lua_Functions#decho|decho()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''true:''<br />
: requires argument for the colouring to work.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
dinsertLink("<255,0,0>press <165,42,42:255,255,255>me!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
dinsertLink("<255,0,0>press <165,42,42:255,255,255>me!", [[send("hi")]], "This is a tooltip", true)<br />
</syntaxhighlight><br />
<br />
==dinsertPopup==<br />
;dinsertPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current cursor position, like [[#dinsertText|dinsertText()]]. 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.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. ie, <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
dinsertPopup("<255,0,0>activities<r> to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"}, true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
dinsertPopup("<255,0,0>activities<r> to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"}, true)<br />
</syntaxhighlight><br />
<br />
== deleteLabel ==<br />
; deleteLabel(labelName)<br />
<br />
: Deletes and removes a label from the screen. Note that if you'd like to show the label again, it is much more performant to hide/show it instead.<br />
<br />
: Note that you shouldn't use the Geyser label associated with the label you delete afterwards - that doesn't make sense and Geyser right now wouldn't know that it's been deleted, either.<br />
<br />
: See also: [[#hideWindow|hideWindow()]], [[#showWindow|showWindow()]], [[#createLabel|createLabel()]]<br />
<br />
; Parameters<br />
<br />
* ''labelName'': name of the label to delete.<br />
<br />
<syntaxhighlight lang="lua"><br />
createLabel("a very basic label",300,400,100,200,1)<br />
setBackgroundColor("a very basic label", 255, 204, 0, 200)<br />
<br />
-- delete the label after 3 seconds<br />
tempTimer(3, function()<br />
deleteLabel("a very basic label")<br />
end)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.5}}<br />
<br />
==deleteLine==<br />
;deleteLine([windowName])<br />
: Deletes the current line under the user cursor. This is a high speed gagging tool and is very good at this task, but is only meant to be use when a line should be omitted entirely in the output. If you echo() to that line it will not be shown, and lines deleted with deleteLine() are simply no longer rendered. This is purely visual - triggers will still fire on the line as expected.<br />
: See also: [[Manual:Lua_Functions#replace|replace()]], [[Manual:Lua_Functions#wrapLine|wrapLine()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to delete the line in. If no name is given, it just deletes the line it is used on.<br />
<br />
{{note}} for replacing text, [[Manual:Lua_Functions#replace|replace()]] is the proper option; doing the following: <code>selectCurrentLine(); replace(""); cecho("new line!\n")</code> is better.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- deletes the line - just put this command into the big script box. Keep the case the same -<br />
-- it has to be deleteLine(), not Deleteline(), deleteline() or anything else<br />
deleteLine()<br />
<br />
--This example creates a temporary line trigger to test if the next line is a prompt, and if so gags it entirely.<br />
--This can be useful for keeping a pile of prompts from forming if you're gagging chat channels in the main window<br />
--Note: isPrompt() only works on servers which send a GA signal with their prompt.<br />
tempLineTrigger(1, 1, [[if isPrompt() then deleteLine() end]])<br />
<br />
-- example of deleting multiple lines:<br />
deleteLine() -- delete the current line<br />
moveCursor(0,getLineNumber()-1) -- move the cursor back one line<br />
deleteLine() -- delete the previous line now<br />
</syntaxhighlight><br />
<br />
==deselect==<br />
;deselect([window name])<br />
: This is used to clear the current selection (to no longer have anything selected). Should be used after changing the formatting of text, to keep from accidentally changing the text again later with another formatting call.<br />
: See also: [[#selectString|selectString()]], [[#selectCurrentLine|selectCurrentLine()]]<br />
<br />
;Parameters<br />
* ''window name:''<br />
: (optional) The name of the window to stop having anything selected in. If name is not provided the main window will have its selection cleared.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This will change the background on an entire line in the main window to red, and then properly clear the selection to keep further<br />
--changes from effecting this line as well.<br />
selectCurrentLine()<br />
bg("red")<br />
deselect()<br />
</syntaxhighlight><br />
<br />
==disableClickthrough==<br />
; disableClickthrough(label)<br />
: Disables clickthrough for a label - making it act 'normal' again and receive clicks, doubleclicks, onEnter, and onLeave events. This is the default behaviour for labels.<br />
: See also: [[#enableClickthrough|enableClickthrough()]]<br />
<br />
;Parameters<br />
* ''label:''<br />
: Name of the label to restore clickability on.<br />
<br />
{{MudletVersion|3.17}}<br />
<br />
==disableCommandLine==<br />
; disableCommandLine(windowName)<br />
: Disables the command line for the miniConsole named ''windowName''<br />
: See Also: [[Manual:Lua_Functions#enableCommandLine|enableCommandLine()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of the miniConsole to disable the command line in.<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
==disableHorizontalScrollBar==<br />
; disableHorizontalScrollBar([windowName])<br />
: Disables the horizontal scroll bar for the miniConsole/userwindow ''windowName'' or the main window<br />
: See Also: [[Manual:Lua_Functions#enableHorizontalScrollBar|enableHorizontalScrollBar()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of the window to disable the scroll bar in. If "main" or not provided it is the main console.<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
==disableScrollBar==<br />
; disableScrollBar([windowName])<br />
: Disables the scroll bar for the miniConsole/userwindow ''windowName'' or the main window<br />
: See Also: [[Manual:Lua_Functions#enableScrollBar|enableScrollBar()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) The name of the window to disable the scroll bar in. If "main" or not provided it is the main console.<br />
<br />
==dreplace==<br />
;dreplace([window, ]text)<br />
: Replaces the output line from the game with a colour-tagged string.<br />
See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#dinsertText|dinsertText()]]<br />
;Parameters<br />
* ''window:''<br />
*: The window to replace the selection in. Optional, defaults to the main window if not provided.<br />
* ''text:''<br />
*: The text to display, as with [[Manual:Lua_Functions#decho|decho()]]<br />
:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectCaptureGroup(1)<br />
dreplace("<255,0,255>[ALERT!]: <r>"..matches[2])<br />
</syntaxhighlight><br />
<br />
==dreplaceLine==<br />
;dreplaceLine ([window], text)<br />
: Replaces the output line from the game with a colour-tagged string.<br />
{{MudletVersion|4.12}}<br />
See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#dinsertText|dinsertText()]]<br />
;Parameters<br />
* ''window'' (optional):<br />
: the window to copy the text from. Defaults to "main".<br />
* ''text:''<br />
*: The text to display, with RGB color values inside angle brackets <>, ie ''<128,0,0>''. If you'd like to use a background color, put it after a colon : - ''<:128,0,0>''. You can use the ''<r>'' tag to reset to the default color. <br />
:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua">dreplaceLine("<255,0,255>[ALERT!]: <r>"..line)<br />
</syntaxhighlight><br />
<br />
==echoLink==<br />
;echoLink([windowName], text, command, hint, [useCurrentFormatElseDefault])<br />
: Echos a piece of text as a clickable link, at the end of the current selected line - similar to [[Manual:Lua_Functions#echo|echo()]].<br />
<br />
: See also: [[#cechoLink|cechoLink()]], [[#hechoLink|hechoLink()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) either be none or "main" for the main console, or a miniconsole / userwindow name.<br />
* ''text:''<br />
: Text to display in the echo. Same as a normal echo().<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: Text for the tooltip to be displayed when the mouse is over the link.<br />
* ''useCurrentFormatElseDefault:''<br />
: If true, then the link will use the current selection style (colors, underline, etc). If missing or false, it will use the default link style - blue on black underlined text.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
echoLink("press me!", function() send("hi") end, "This is a tooltip")<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
echoLink("press me!", [[send("hi")]], "This is a tooltip")<br />
<br />
-- do the same, but send this link to a miniConsole<br />
echoLink("my miniConsole", "press me!", function() send("hi") end, "This is a tooltip")<br />
</syntaxhighlight><br />
<br />
{{note}} The ''hint'' can contain the same sort of "rich-text" as can be used for "labels" - and if the ''command'' is set to be the empty string ''""'' then this can be a means to show extra information for the text when the mouse is hovered over it but without a command being run should it be clicked upon, e.g.:<br />
<br />
[[File:Screenshot showing example of fancy visual link.png|center|frame|link=|Screenshot showing example of fancy visual link]]<br />
<br />
==echoUserWindow==<br />
;echoUserWindow(windowName, text)<br />
:This function will print text to both mini console windows, dock windows and labels. It is outdated however - [[Manual:Lua_Functions#echo|echo()]] instead.<br />
<br />
==echoPopup==<br />
;echoPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: 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.<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. i.e. <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
echoPopup("activities to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"})<br />
<br />
-- alternatively, put commands as text (in [[ and ]] to use quotation marks inside)<br />
echoPopup("activities to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"})<br />
</syntaxhighlight><br />
<br />
==enableClickthrough==<br />
; enableClickthrough(label)<br />
: Make a label 'invisible' to clicks - so if you have another label underneath, it'll be clicked on instead of this one on top.<br />
: This affects clicks, double-clicks, right-clicks, as well as the onEnter/onLeave events.<br />
: See also: [[#disableClickthrough|disableClickthrough()]]<br />
<br />
;Parameters<br />
* ''label:''<br />
: The name of the label to enable clickthrough on.<br />
<br />
{{MudletVersion|3.17}}<br />
<br />
==enableCommandLine==<br />
; enableCommandLine(windowName)<br />
: Enables the command line for the miniConsole named ''windowName''<br />
: See Also: [[Manual:Lua_Functions#disableCommandLine|disableCommandLine()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of the miniConsole to enable the command line in.<br />
<br />
{{note}} The command line name is the same as the miniConsole name<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
==enableHorizontalScrollBar==<br />
; enableHorizontalScrollBar([windowName])<br />
: Enables the horizontal scroll bar for the miniConsole/userwindow ''windowName'' or the main window<br />
: See Also: [[Manual:Lua_Functions#disableHorizontalScrollBar|disableHorizontalScrollBar()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of the window to enable the scroll bar in. If "main" or not provided it is the main console.<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
==enableScrollBar==<br />
; enableScrollBar([windowName])<br />
: Enables the scroll bar for the miniConsole/userwindow ''windowName'' or the main window<br />
: See Also: [[Manual:Lua_Functions#disableScrollBar|disableScrollBar()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of the window to enable the scroll bar in. If "main" or not provided it is the main console.<br />
<br />
==fg==<br />
; fg([window], colorName)<br />
: If used on a selection, sets the foreground color to ''colorName'' - otherwise, it will set the color of the next text-inserting calls (''echo(), insertText, echoLink()'', and others)<br />
: See Also: [[Manual:Lua_Functions#bg|bg()]], [[Manual:Lua_Functions#setBgColor|setBgColor()]]<br />
<br />
;Parameters<br />
* ''window:''<br />
: (optional) name of the miniconsole to operate on. If you'd like it to work on the main window, don't specify anything or use ''main'' (since Mudlet 3.0).<br />
* ''colorName:''<br />
: The name of the color to set the foreground to - list of possible names: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This would change the color of the text on the current line to green<br />
selectCurrentLine()<br />
fg("green")<br />
resetFormat()<br />
<br />
--This will echo red, green, blue in their respective colors<br />
fg("red")<br />
echo("red ")<br />
fg("green")<br />
echo("green ")<br />
fg("blue")<br />
echo("blue ")<br />
resetFormat()<br />
<br />
-- example of working on a miniconsole<br />
fg("my console", "red")<br />
echo("my console", "red text")<br />
</syntaxhighlight><br />
<br />
==getAvailableFonts==<br />
; getAvailableFonts()<br />
: This returns a "font - true" key-value list of available fonts which you can use to verify that Mudlet has access to a given font.<br />
: To install a new font with your package, include the font file in your zip/mpackage and it'll be automatically installed for you.<br />
<br />
: See also: [[#getFont|getFont()]], [[#setFont|setFont()]]<br />
<br />
{{MudletVersion|3.10}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- check if Ubuntu Mono is a font we can use<br />
if getAvailableFonts()["Ubuntu Mono"] then<br />
-- make the miniconsole use the font at size 16<br />
setFont("my miniconsole", "Ubuntu Mono")<br />
setFontSize("my miniconsole", 16)<br />
end<br />
</syntaxhighlight><br />
<br />
==getBackgroundColor==<br />
;getBackgroundColor([windowName])<br />
: Gets the background for the given label, miniconsole, or userwindow.<br />
: Returns 4 values - red, green, blue, transparency. Colors returned are from 0 to 255 (0 being black), and transparency is from 0 to 255 (0 being completely transparent).<br />
<br />
;Parameters<br />
<br />
* ''windowName:''<br />
: (optional) name of the label/miniconsole/userwindow to getthe background color from, or "main" for the main window.<br />
<br />
: {{MudletVersion|4.15}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local r, g, b, a = getBackgroundColor()<br />
local rW, gW, bW, aW = getBackgroundColor("myWindow")<br />
</syntaxhighlight><br />
<br />
==getBgColor==<br />
; getBgColor(windowName)<br />
: This function returns the rgb values of the background color of the first character of the current selection on mini console (window) windowName. If windowName is omitted Mudlet will use the main screen.<br />
<br />
: See also: [[#setBgColor|setBgColor()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: A window to operate on - either a miniconsole or the main window.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local r,g,b;<br />
selectString("troll",1)<br />
r,g,b = getBgColor()<br />
if r == 255 and g == 0 and b == 0 then<br />
echo("HELP! troll is highlighted in red letters, the monster is aggressive!\n");<br />
end<br />
</syntaxhighlight><br />
<br />
==getBorderBottom==<br />
;getBorderBottom()<br />
: Returns the size of the bottom border of the main window in pixels. <br />
: See also: [[Manual:Lua_Functions#getBorderSizes|getBorderSizes()]], [[Manual:Lua_Functions#setBorderBottom|setBorderBottom()]]<br />
<br />
: {{MudletVersion|4.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderBottom(150)<br />
getBorderBottom()<br />
-- returns: 150<br />
</syntaxhighlight><br />
<br />
==getBorderLeft==<br />
;getBorderLeft()<br />
: Returns the size of the left border of the main window in pixels. <br />
: See also: [[Manual:Lua_Functions#getBorderSizes|getBorderSizes()]], [[Manual:Lua_Functions#setBorderLeft|setBorderLeft()]]<br />
<br />
: {{MudletVersion|4.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderLeft(5)<br />
getBorderLeft()<br />
-- returns: 5<br />
</syntaxhighlight><br />
<br />
==getBorderRight==<br />
;getBorderRight()<br />
: Returns the size of the right border of the main window in pixels. <br />
: See also: [[Manual:Lua_Functions#getBorderSizes|getBorderSizes()]], [[Manual:Lua_Functions#setBorderRight|setBorderRight()]]<br />
<br />
: {{MudletVersion|4.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderRight(50)<br />
getBorderRight()<br />
-- returns: 50<br />
</syntaxhighlight><br />
<br />
==getBorderSizes==<br />
;getBorderSizes()<br />
: Returns the a named table with the sizes of all borders of the main window in pixels. <br />
: See also: [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#getBorderTop|getBorderTop()]], [[Manual:Lua_Functions#getBorderRight|getBorderRight()]],[[Manual:Lua_Functions#getBorderBottom|getBorderBottom()]], [[Manual:Lua_Functions#getBorderLeft|getBorderLeft()]]<br />
<br />
: {{MudletVersion|4.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderSizes(100, 50, 150, 0)<br />
getBorderSizes()<br />
-- returns: { top = 100, right = 50, bottom = 150, left = 0 }<br />
getBorderSizes().right<br />
-- returns: 50<br />
</syntaxhighlight><br />
<br />
==getBorderTop==<br />
;getBorderTop()<br />
: Returns the size of the top border of the main window in pixels. <br />
: See also: [[Manual:Lua_Functions#getBorderSizes|getBorderSizes()]], [[Manual:Lua_Functions#setBorderTop|setBorderTop()]]<br />
<br />
: {{MudletVersion|4.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderTop(100)<br />
getBorderTop()<br />
-- returns: 100<br />
</syntaxhighlight><br />
<br />
==getClipboardText==<br />
;getClipboardText()<br />
: Returns any text that is currently present in the clipboard. <br />
: See also: [[#setClipboardText | setClipboardText()]]<br />
<br />
: {{note}} Note: Available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local clipboardContents = getClipboardText()<br />
echo("Clipboard: " .. clipboardContents)<br />
</syntaxhighlight><br />
<br />
==getColorWildcard==<br />
; getColorWildcard(ansi color number)<br />
: This function, given an ANSI color number ([[Manual:UI_Functions#isAnsiFgColor|list]]), will return all strings on the current line that match it.<br />
<br />
: See also: [[#isAnsiFgColor|isAnsiFgColor()]], [[#isAnsiBgColor|isAnsiBgColor()]]<br />
<br />
;Parameters<br />
* ''ansi color number:''<br />
: A color number ([[Manual:UI_Functions#isAnsiFgColor|list]]) to match.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- we can run this script on a line that has the players name coloured differently to easily capture it from<br />
-- anywhere on the line<br />
local match = getColorWildcard(14) -- this will be a table of every match<br />
<br />
if match then -- if there's a table, then we try and print it on the screen!<br />
echo("\nFound "..table.concat(match, ", ").."!") -- this will combine all captured strings and separate them with a comma so it's easy to read.<br />
else -- if there isn't something in match, then we haven't found anything to print on the screen!<br />
echo("\nDidn't find anyone.") <br />
end<br />
</syntaxhighlight><br />
<br />
==getColumnCount==<br />
;getColumnCount([windowName])<br />
: Gets the maximum number of columns (characters) that a given window can display on a single row, taking into consideration factors such as window width, font size, spacing, etc.<br />
<br />
;Parameters:<br />
* ''windowName'':<br />
: (optional) name of the window whose number of columns we want to calculate. By default it operates on the main window.<br />
<br />
{{MudletVersion|3.7}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
print("Maximum number of columns on the main window "..getColumnCount())<br />
</syntaxhighlight><br />
<br />
==getColumnNumber==<br />
;getColumnNumber([windowName])<br />
: Gets the absolute column number of the current user cursor.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) either be none or "main" for the main console, or a miniconsole / userwindow name.<br />
<br />
{{note}} the argument is available since Mudlet 3.0.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
HelloWorld = Geyser.MiniConsole:new({<br />
name="HelloWorld",<br />
x="70%", y="50%",<br />
width="30%", height="50%",<br />
})<br />
<br />
HelloWorld:echo("hello!\n")<br />
HelloWorld:echo("hello!\n")<br />
HelloWorld:echo("hello!\n")<br />
<br />
moveCursor("HelloWorld", 3, getLastLineNumber("HelloWorld"))<br />
-- should say 3, because we moved the cursor in the HellWorld window to the 3rd position in the line<br />
print("getColumnNumber: "..tostring(getColumnNumber("HelloWorld")))<br />
<br />
moveCursor("HelloWorld", 1, getLastLineNumber("HelloWorld"))<br />
-- should say 3, because we moved the cursor in the HellWorld window to the 1st position in the line<br />
print("getColumnNumber: "..tostring(getColumnNumber("HelloWorld")))<br />
</syntaxhighlight><br />
<br />
==getCurrentLine==<br />
;getCurrentLine([windowName])<br />
: Returns the content of the current line under the user cursor in the buffer. The Lua variable '''line''' holds the content of ''getCurrentLine()'' before any triggers have been run on this line. When triggers change the content of the buffer, the variable line will not be adjusted and thus hold an outdated string. ''line = getCurrentLine()'' will update line to the real content of the current buffer. This is important if you want to copy the current line after it has been changed by some triggers. ''selectString( line,1 )'' will return false and won't select anything because line no longer equals ''getCurrentLine()''. Consequently, ''selectString( getCurrentLine(), 1 )'' is what you need.<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window in which to select text.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
print("Currently selected line: "..getCurrentLine())<br />
</syntaxhighlight><br />
<br />
==getFgColor==<br />
; getFgColor(windowName)<br />
: This function returns the rgb values of the color of the first character of the current selection on mini console (window) windowName. If windowName is omitted Mudlet will use the main screen.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: A window to operate on - either a miniconsole or the main window.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectString("troll",1)<br />
local r,g,b = getFgColor()<br />
if r == 255 and g == 0 and b == 0 then<br />
echo("HELP! troll is written in red letters, the monster is aggressive!\n")<br />
end<br />
</syntaxhighlight><br />
<br />
==getFont==<br />
;getFont([windowName])<br />
: Gets the current font of the given window or console name. Can be used to get font of the main console, dockable userwindows and miniconsoles.<br />
: See also: [[#setFont|setFont()]], [[#setFontSize|setFontSize()]], [[#openUserWindow|openUserWindow()]], [[#getAvailableFonts|getAvailableFonts()]]<br />
<br />
{{MudletVersion|3.4}}<br />
{{note}} Since Mudlet 3.10, returns the actual font that was used in case you didn't have the required font when using [[#setFont|setFont()]].<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The window name to get font size of - can either be none or "main" for the main console, or a miniconsole/userwindow name.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The following will get the "main" console font size.<br />
display("Font in the main window: "..getFont())<br />
<br />
display("Font in the main window: "..getFont("main"))<br />
<br />
-- This will get the font size of a user window named "user window awesome".<br />
display("Font size: " .. getFont("user window awesome"))<br />
</syntaxhighlight><br />
<br />
==getFontSize==<br />
;getFontSize([windowName])<br />
: Gets the current font size of the given window or console name. Can be used to get font size of the Main console as well as dockable UserWindows.<br />
: See also: [[#setFontSize|setFontSize()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The window name to get font size of - can either be none or "main" for the main console, or a UserWindow name.<br />
<br />
{{MudletVersion|3.4}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The following will get the "main" console font size.<br />
local mainWindowFontSize = getFontSize()<br />
if mainWindowFontSize then<br />
display("Font size: " .. mainWindowFontSize)<br />
end<br />
<br />
local mainWindowFontSize = getFontSize("main")<br />
if mainWindowFontSize then<br />
display("Font size: " .. fs2)<br />
end<br />
<br />
-- This will get the font size of a user window named "user window awesome".<br />
local awesomeWindowFontSize = getFontSize("user window awesome")<br />
if awesomeWindowFontSize then<br />
display("Font size: " .. awesomeWindowFontSize)<br />
end<br />
</syntaxhighlight><br />
<br />
==getHTMLformat==<br />
;spanTag = getHTMLformat(formatTable)<br />
<br />
:Takes in a table of formatting options in the same style as [[Manual:Lua_Functions#getTextFormat|getTextFormat()]] and returns a span tag which will format text after it as the table describes.<br />
<br />
;See also:[[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
*''formatTable:''<br />
:Table with formatting options configured. Keys are foreground, background, bold, underline, overline, strikeout, italic, and reverse. All except for foreground and background should be boolean (true/false) values. Foreground and background are either { r, g, b, a } tables, or strings with QSS formatting directives<br />
<br />
;Returns<br />
*A string with the html span tag to format text in accordance with the format table.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Returns a span tag for bold, red text on a green background<br />
local span = getHTMLformat({<br />
foreground = { 255, 0, 0 },<br />
background = "#00FF00",<br />
bold = true<br />
})<br />
<br />
-- span will be '<span style="color: rgb(255, 0, 0);background-color: #00FF00; font-weight: bold; font-style: normal; text-decoration: none;">'<br />
</syntaxhighlight><br />
<br />
==getImageSize==<br />
;getImageSize(imageLocation)<br />
: Returns the width and the height of the given image. If the image can't be found, loaded, or isn't a valid image file - nil+error message will be returned instead.<br />
: See also: [[#createLabel|createLabel()]]<br />
<br />
;Parameters<br />
* ''imageLocation:''<br />
: Path to the image.<br />
<br />
{{MudletVersion|4.5}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local path = getMudletHomeDir().."/my-image.png"<br />
<br />
cecho("Showing dimensions of the picture in: "..path.."\n")<br />
<br />
local width, height = getImageSize(path)<br />
<br />
if not width then<br />
-- in case of an problem, we don't get a height back - but the error message<br />
cecho("error: "..height.."\n")<br />
else<br />
cecho(string.format("They are: %sx%s", width, height))<br />
end<br />
</syntaxhighlight><br />
<br />
==getLabelFormat==<br />
;formatTable = getLabelFormat(labelName)<br />
<br />
: Returns a format table like the one returned by getTextFormat and suitable for getHTMLformat which will format text the same way as simply doing an echo to the label would<br />
<br />
;See also:[[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getHTMLformat|getHTMLformat()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
*''labelName:''<br />
: The name of the label to scan the format of<br />
<br />
;Returns<br />
*A table with all the formatting options to achieve a default text format for label labelName.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- creates a test label, sets a stylesheet, and then returns the default format table for that label.<br />
createLabel("testLabel", 10, 10, 300, 200, 1)<br />
setLabelStyleSheet([[<br />
color: rgb(0,0,180);<br />
border-width: 1px;<br />
border-style: solid;<br />
border-color: gold;<br />
border-radius: 10px;<br />
font-size: 12.0pt;<br />
background: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #98f041, stop: 0.1 #8cf029, stop: 0.49 #66cc00, stop: 0.5 #52a300, stop: 1 #66cc00);<br />
]])<br />
local fmt = getLabelFormat("testLabel"))<br />
<br />
--[[<br />
{<br />
background = "rgba(0, 0, 0, 0)", -- this is transparent<br />
bold = false,<br />
foreground = "rgb(0,0,180)",<br />
italic = false,<br />
overline = false,<br />
reverse = false,<br />
strikeout = false,<br />
underline = false<br />
}<br />
--]]<br />
<br />
</syntaxhighlight><br />
<br />
==getLabelSizeHint==<br />
;width, height = getLabelSizeHint(labelName)<br />
<br />
: Returns the suggested labelsize as width and height<br />
<br />
;See also:[[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getHTMLformat|getHTMLformat()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
*''labelName:''<br />
: The name of the label to get the suggested size from<br />
<br />
;Returns<br />
*suggested width and height (to fit text and/or an image on a label)<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- text resizing example<br />
-- create the label<br />
createLabel("textLabel",400,400,300,300,1)<br />
-- put some text on it<br />
echo("textLabel", "This is my Test.\nAnother Test")<br />
-- resizes the label to fit the text<br />
resizeWindow("textLabel", getLabelSizeHint("textLabel"))<br />
<br />
-- image resizing example<br />
-- create the label<br />
createLabel("imageLabel",400,400,300,300,1)<br />
-- put some image on it<br />
setBackgroundImage("imageLabel", getMudletHomeDir.."/myLabelImage.png")<br />
-- resizes the label to fit the image<br />
resizeWindow("imageLabel", getLabelSizeHint("imageLabel"))<br />
<br />
</syntaxhighlight><br />
<br />
==getLabelStyleSheet==<br />
;getLabelStyleSheet(labelName)<br />
: Returns the stylesheet set on a given label, which is used to customise the labels look and feel.<br />
<br />
;See also:[[Manual:Lua_Functions#setLabelStyleSheet|getTextFormat()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
*''labelName:''<br />
: The name of the label to get the stylesheet from<br />
<br />
;Returns<br />
*stylesheet as a string<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
createLabel("test", 50, 50, 100, 100, 0)<br />
setLabelStyleSheet("test", [[<br />
background-color: white;<br />
border: 10px solid green;<br />
font-size: 12px;<br />
]])<br />
echo("test", "test")<br />
<br />
-- now retrieve it and display:<br />
local stylesheet = getLabelStyleSheet("test")<br />
cecho(f"<green>the label's stylesheet is now: \n<white>{stylesheet}\n")<br />
</syntaxhighlight><br />
<br />
==getLastLineNumber==<br />
;getLastLineNumber(windowName)<br />
:Returns the latest line's number in the main window or the miniconsole. This could be different from [[Manual:UI_Functions#getLineNumber|getLineNumber()]] if the cursor was moved around.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: name of the window to use. Either use ''main'' for the main window, or the name of the miniconsole.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- get the latest line's # in the buffer<br />
local latestline = getLastLineNumber("main")<br />
</syntaxhighlight><br />
<br />
==getLineCount==<br />
;getLineCount([windowName])<br />
:Gets the absolute amount of lines in the current console buffer<br />
<br />
; Parameters<br />
*''windowName''<br />
: Optional name of the window to get the line count of. Defaults to the main window.<br />
<br />
;Example<br />
''Need example''<br />
<br />
==getLines==<br />
;getLines([windowName,] from_line_number, to_line_number)<br />
: Returns a section of the content of the screen text buffer. Returns a Lua table with the content of the lines on a per line basis. The form value is ''result = {relative_linenumber = line}''.<br />
<br />
:Absolute line numbers are used.<br />
<br />
;Parameters<br />
* ''windowName''<br />
: (optional) name of the miniconsole/userwindow to get lines for, or "main" for the main window (Mudlet 3.17+)<br />
* ''from_line_number:''<br />
: First line number<br />
* ''to_line_number:''<br />
: End line number<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- retrieve & echo the last line:<br />
echo(getLines(getLineNumber()-1, getLineNumber())[1])<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- find out which server and port you are connected to (as per Mudlet settings dialog):<br />
local t = getLines(0, getLineNumber())<br />
<br />
local server, port<br />
<br />
for i = 1, #t do<br />
local s, p = t[i]:match("looking up the IP address of server:(.-):(%d+)")<br />
if s then server, port = s, p break end<br />
end<br />
<br />
display(server)<br />
display(port)<br />
</syntaxhighlight><br />
<br />
==getLineNumber==<br />
;getLineNumber([windowName])<br />
: Returns the absolute line number of the current user cursor (the y position). The cursor by default is on the current line the triggers are processing - which you can move around with [[Manual:Lua_Functions#moveCursor|moveCursor()]] and [[Manual:Lua_Functions#moveCursorEnd|moveCursorEnd()]]. This function can come in handy in combination when using with [[Manual:Lua_Functions#moveCursor|moveCursor()]] and [[Manual:Lua_Functions#getLines|getLines()]].<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the miniconsole to operate on. If you'd like it to work on the main window, don't specify anything.<br />
<br />
{{note}}<br />
The argument is available since Mudlet 3.0.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- use getLines() in conjuction with getLineNumber() to check if the previous line has a certain word<br />
if getLines(getLineNumber()-1, getLineNumber())[1]:find("attacks") then echo("previous line had the word 'attacks' in it!\n") end<br />
<br />
-- check how many lines you've got in your miniconsole after echoing some text.<br />
-- Note the use of moveCursorEnd() to update getLineNumber()'s output<br />
HelloWorld = Geyser.MiniConsole:new({<br />
name="HelloWorld",<br />
x="70%", y="50%",<br />
width="30%", height="50%",<br />
})<br />
<br />
print(getLineNumber("HelloWorld"))<br />
<br />
HelloWorld:echo("hello!\n")<br />
HelloWorld:echo("hello!\n")<br />
HelloWorld:echo("hello!\n")<br />
<br />
-- update the cursors position, as it seems to be necessary to do<br />
moveCursorEnd("HelloWorld")<br />
print(getLineNumber("HelloWorld"))<br />
</syntaxhighlight><br />
<br />
==getMainConsoleWidth==<br />
;getMainConsoleWidth()<br />
: Returns a single number; the width of the main console (game output) in pixels. This also accounts for any borders that have been set.<br />
<br />
: See also: [[#getMainWindowSize|getMainWindowSize()]]<br />
<br />
; Parameters<br />
:None<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Save width of the main console to a variable for future use.<br />
consoleWidth = getMainConsoleWidth()<br />
</syntaxhighlight><br />
<br />
==getMouseEvents==<br />
; events = getMouseEvents()<br />
<br />
:Returns a table of registered mouse events, including any of the additional arguments they may have.<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
;See also: [[Manual:Lua_Functions#addMouseEvent|addMouseEvent()]], [[Manual:Lua_Functions#removeMouseEvent|removeMouseEvent()]]<br />
<br />
;Returns <br />
* Returns a table with mouse event ''uniqueName'' as indexes, containing all the creation arguments as the sub-table members.<br />
<br />
==getMousePosition==<br />
;getMousePosition()<br />
: Returns the coordinates of the mouse's position, relative to the Mudlet window itself.<br />
<br />
; Parameters<br />
:None<br />
<br />
{{MudletVersion|3.1}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Retrieve x and y position of the mouse to determine where to create a new label, then use that position to create a new label<br />
local x, y = getMousePosition()<br />
createLabel("clickGeneratedLabel", x, y, 100, 100, 1)<br />
-- if the label already exists, just move it<br />
moveWindow("clickGeneratedLabel", x, y)<br />
-- and make it easier to notice<br />
setBackgroundColor("clickGeneratedLabel", 255, 204, 0, 200)<br />
</syntaxhighlight><br />
<br />
==getProfileTabNumber==<br />
;getProfileTabNumber()<br />
: Returns the current tab number you're in. If you have just one profile loaded, it'll always return 1 - otherwise it'll be the nth tab that is currently open.<br />
<br />
; Parameters<br />
:None<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
print(f"Current playing in tab #{getProfileTabNumber()}.")<br />
</syntaxhighlight><br />
<br />
==getMainWindowSize==<br />
;getMainWindowSize()<br />
: Returns two numbers, the width and height in pixels. This is useful for calculating the window dimensions and placement of custom GUI toolkit items like labels, buttons, mini consoles etc.<br />
: See also: [[#getUserWindowSize|getUserWindowSize()]], [[#setMainWindowSize|setMainWindowSize()]], [[#getMainConsoleWidth|getMainConsoleWidth()]]<br />
<br />
; Parameters<br />
:None<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--this will get the size of your main mudlet window and save them<br />
--into the variables mainHeight and mainWidth<br />
mainWidth, mainHeight = getMainWindowSize()<br />
</syntaxhighlight><br />
<br />
==getRowCount==<br />
;getRowCount([windowName])<br />
: Gets the maximum number of rows that a given window can display at once, taking into consideration factors such as window height, font type, spacing, etc.<br />
<br />
;Parameters:<br />
* ''windowName'':<br />
: (optional) name of the window whose maximum number of rows we want to calculate. By default it operates on the main window.<br />
<br />
{{MudletVersion|3.7}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
print("Maximum of rows on the main window "..getRowCount())<br />
</syntaxhighlight><br />
<br />
==getScroll==<br />
;getScroll([windowName])<br />
:Returns line that the window is currently scrolled to.<br />
:See also: [[Manual:Lua_Functions#scrollTo|scrollTo]], [[Manual:Lua_Functions#scrollUp|scrollUp]], [[Manual:Lua_Functions#scrollDown|scrollDown]]<br />
<br />
; Parameters<br />
*''windowName:''<br />
:(optional) name of the window to ask about. Default is the main window.<br />
<br />
{{MudletVersion|4.17.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- button to jump to next instance of "Timbo"<br />
local current = getScroll()<br />
local data = getLines(current, getLineCount())<br />
for count, line in ipairs(data) do<br />
local match = string.findPattern(line, "Timbo")<br />
if match then<br />
scrollTo(current + count)<br />
break<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==getSelection==<br />
;getSelection([windowName])<br />
: Returns the text currently selected with [[#selectString|selectString()]], [[#selectSection|selectSection()]], or [[#selectCurrentLine|selectCurrentLine()]]. Note that this isn't the text currently selected with the mouse.<br />
: Also returns the start offset and length of the selection as second and third value.<br />
<br />
;Parameters:<br />
* ''windowName'':<br />
: (optional) name of the window to get the selection from. By default it operates on the main window.<br />
<br />
{{MudletVersion|3.16}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectCurrentLine()<br />
print("Current line contains: "..getSelection())<br />
</syntaxhighlight><br />
<br />
;retrieving the selection<br />
<syntaxhighlight lang="lua"><br />
text,offset,len = getSelection()<br />
-- manipulate the selection, e.g. to discover the color of characters other than the first<br />
-- then restore it<br />
selectSection(offset, len)<br />
</syntaxhighlight><br />
<br />
==getTextFormat==<br />
;getTextFormat([windowName])<br />
: Gets the current text format of the currently selected text. May be used with other console windows. The returned values come in a table containing text attribute names and their values. The values given will be booleans for: bold, italics, underline, overline, strikeout, and reverse - followed by color triplet tables for the foreground and background colors.<br />
: See Also: [[Manual:Lua_Functions#setTextFormat|setTextFormat()]]<br />
<br />
;Parameters<br />
* ''windowName''<br />
: (optional) Specify name of selected window. If no name or "main" is given, the format will be gathered from the main console.<br />
<br />
{{MudletVersion|3.20}}<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
-- A suitable test for getTextFormat()<br />
-- (copy it into an alias or a script)<br />
<br />
clearWindow()<br />
<br />
echo("\n")<br />
<br />
local SGR = string.char(27)..'['<br />
feedTriggers("Format attributes: '"..SGR.."1mBold"..SGR.."0m' '"..SGR.."3mItalic"..SGR.."0m' '"..SGR.."4mUnderline"..SGR.."0m' '"..SGR.."5mBlink"..SGR.."0m' '"..SGR.."6mF.Blink"..SGR.."0m' '"..SGR.."7mReverse"..SGR.."0m' '"..SGR.."9mStruckout"..SGR.."0m' '"..SGR.."53mOverline"..SGR.."0m'.\n")<br />
<br />
moveCursor(1,1)<br />
selectSection(1,1)<br />
<br />
local results = getTextFormat()<br />
echo("For first character in test line:\nBold detected: " .. tostring(results["bold"]))<br />
echo("\nItalic detected: " .. tostring(results["italic"]))<br />
echo("\nUnderline detected: " .. tostring(results["underline"]))<br />
echo("\nReverse detected: " .. tostring(results["reverse"]))<br />
echo("\nStrikeout detected: " .. tostring(results["strikeout"]))<br />
echo("\nOverline detected: " .. tostring(results["overline"]))<br />
echo("\nForeground color: (" .. results["foreground"][1] .. ", " .. results["foreground"][2] .. ", " .. results["foreground"][3] .. ")")<br />
echo("\nBackground color: (" .. results["background"][1] .. ", " .. results["background"][2] .. ", " .. results["background"][3] .. ")")<br />
<br />
selectSection(21,1)<br />
echo("\n\nFor individual parts of test text:")<br />
echo("\nBold detected (character 21): " .. tostring(results["bold"]))<br />
<br />
selectSection(28,1)<br />
echo("\nItalic detected (character 28): " .. tostring(results["italic"]))<br />
<br />
selectSection(37,1)<br />
echo("\nUnderline detected (character 37): " .. tostring(results["underline"]))<br />
<br />
selectSection(67,1)<br />
echo("\nReverse detected (character 67): " .. tostring(results["reverse"]))<br />
<br />
selectSection(77,1)<br />
echo("\nStrikeout detected (character 77): " .. tostring(results["strikeout"]))<br />
<br />
selectSection(89,1)<br />
echo("\nOverline detected (character 89): " .. tostring(results["overline"]))<br />
echo("\n")<br />
</syntaxhighlight><br />
<br />
==getUserWindowSize==<br />
;getUserWindowSize(windowName)<br />
: Returns two numbers, the width and height in pixels. This is useful for calculating the given userwindow dimensions and placement of custom GUI toolkit items like labels, buttons, mini consoles etc.<br />
: See also: [[#getMainWindowSize|getMainWindowSize()]]<br />
<br />
; Parameters<br />
* ''windowName''<br />
:the name of the userwindow we will get the dimensions from<br />
<br />
{{MudletVersion|4.6.1}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--this will get the size of your userwindow named "ChatWindow" and save them<br />
--into the variables mainHeight and mainWidth<br />
mainWidth, mainHeight = getUserWindowSize("ChatWindow")<br />
</syntaxhighlight><br />
<br />
<br />
==getWindowWrap==<br />
;getWindowWrap(windowName)<br />
: gets at what position in the line the will start word wrap.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the "main" console or user-created miniconsole which you want to be wrapped differently. If you want to wrap the main window, use windowName "main" or leave empty.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setWindowWrap("main", 10)<br />
display(getWindowWrap("main"))<br />
<br />
-- The following output will result in the main window console:<br />
-- 10<br />
</syntaxhighlight><br />
<br />
;Practical Example<br />
<syntaxhighlight lang="lua"><br />
-- display ======== line with maximum possible width without wrapping<br />
echo(string.rep("=", getWindowWrap("main")))<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.11}}<br />
<br />
==handleWindowResizeEvent==<br />
;handleWindowResizeEvent()<br />
: (''deprecated'') This function is deprecated and should not be used; it's only documented here for historical reference - use the [[Manual:Technical_Manual#sysWindowResizeEvent|sysWindowResizeEvent]] event instead.<br />
<br />
The standard implementation of this function does nothing. However, this function gets called whenever the main window is being manually resized. You can overwrite this function in your own scripts to handle window resize events yourself and e. g. adjust the screen position and size of your mini console windows, labels or other relevant GUI elements in your scripts that depend on the size of the main Window. To override this function you can simply put a function with the same name in one of your scripts thus overwriting the original empty implementation of this.<br />
<br />
; Parameters<br />
:None<br />
<br />
; Example<br />
<syntaxhighlight lang="lua"><br />
function handleWindowResizeEvent()<br />
-- determine the size of your screen<br />
WindowWidth=0;<br />
WindowHeight=0;<br />
WindowWidth, WindowHeight = getMainWindowSize();<br />
<br />
-- move mini console "sys" to the far right side of the screen whenever the screen gets resized<br />
moveWindow("sys",WindowWidth-300,0)<br />
end<br />
</syntaxhighlight><br />
<br />
==hasFocus==<br />
;hasFocus()<br />
: Returns ''true'' or ''false'' depending if Mudlet's main window is currently in focus (ie, the user isn't focused on another window, like a browser). If multiple profiles are loaded, this can also be used to check if a given profile is in focus.<br />
<br />
; Parameters<br />
:None<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
if attacked and not hasFocus() then<br />
runaway()<br />
else<br />
fight()<br />
end<br />
</syntaxhighlight><br />
<br />
==hecho==<br />
;hecho([windowName], text)<br />
:Echoes text that can be easily formatted with colour tags in the hexadecimal format. You can also use italics, bold, strikethrough, and underline tags.<br />
:See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#cecho|cecho()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you hecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
*''windowName:''<br />
:(optional) name of the window to echo to. Can either be omitted or "main" for the main window, else specify the miniconsoles name.<br />
*''text:''<br />
:The text to display, with color changes made within the string using the format |cFRFGFB,BRBGBB or #FRFGFB,BRBGBB where FR is the foreground red value, FG is the foreground green value, FB is the foreground blue value, BR is the background red value, etc., BRBGBB is optional. |r or #r can be used within the string to reset the colors to default. Hexadecimal color codes can be found here: https://www.color-hex.com/<br />
<br />
{{note}}<br />
Transparency for background in hex-format available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
hecho("\n#ffffff White text!")<br />
-- your text in white<br />
hecho("\n#ca0004 Red text! And now reset #rit to the default color")<br />
-- your text in red, then reset to default using #r<br />
hecho("\n#ffffff,ca0004 White text with a red background!")<br />
-- your text in white, against a red background<br />
hecho("\n|c0000ff Blue text, this time using |c instead of #")<br />
-- your text in blue, activated with |c vs #.<br />
hecho("\n#ff0000Red text with #iitalics#/i, |uunderline|/u, #ooverline#/o, #sstrikethrough#/s, and #bbold#/b formatting.")<br />
-- shows the various individual formatting options<br />
hecho("\n#008000#o#uGreen text with both over and underlines.#/o#/u")<br />
</syntaxhighlight><br />
<br />
==hecho2ansi==<br />
;ansiFormattedString = hecho2ansi(text)<br />
<br />
:Converts hecho formatted text to ansi formatted text. Used by hfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also:[[Manual:Lua_Functions#hecho|hecho()]], [[Manual:Lua_Functions#hfeedTriggers|hfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
*''text:''<br />
:The hecho formatted text for conversion<br />
<br />
;Returns<br />
*String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of hfeedTriggers() for a single line.<br />
-- you would most likely just use hfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(hecho2ansi("\n#800000This is red.#r #iitalic#/i, #bbold#/b, #sstrikethrough#/s, #uunderline#/u\n"))<br />
</syntaxhighlight><br />
<br />
==hechoLink==<br />
;hechoLink([windowName], text, command, hint, true)<br />
: Echos a piece of text as a clickable link, at the end of the current selected line - similar to [[Manual:Lua_Functions#hecho|hecho()]]. This version allows you to use colours within your link text.<br />
<br />
: See also: [[#cechoLink|cechoLink()]], [[#dechoLink|dechoLink()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) - allows selection between sending the link to a miniconsole or the ''main'' window.<br />
* ''text:''<br />
: text to display in the echo. Same as a normal [[Manual:Lua_Functions#hecho|hecho()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''true:''<br />
: requires argument for the colouring to work.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
hechoLink("|ca00040black!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- # format also works<br />
hechoLink("#ca00040black!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
hechoLink("#ca00040black!", [[send("hi")]], "This is a tooltip", true)<br />
</syntaxhighlight><br />
<br />
==hechoPopup==<br />
;hechoPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current line, like [[#hecho|hecho()]]. 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.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. ie, <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
hechoPopup("#ff0000activities#r to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"}, true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
hechoPopup("#ff0000activities#r to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"}, true)<br />
</syntaxhighlight><br />
<br />
==hideGauge==<br />
;hideGauge(gaugeName)<br />
: hides the given gauge.<br />
<br />
: See also: [[#showGauge|showGauge()]], [[#createGauge|createGauge()]]<br />
<br />
;Parameters<br />
* ''gaugeName:''<br />
: name of the gauge to show.<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
hideGauge("my gauge")<br />
showGauge("my gauge")<br />
</syntaxhighlight><br />
<br />
==hinsertLink==<br />
;hinsertLink([windowName], text, command, hint, true)<br />
: Echos a piece of text as a clickable link, at the end of the current cursor position - similar to [[#hinsertText|hinsertText()]]. This version allows you to use colours within your link text.<br />
<br />
: See also: [[#insertLink|insertLink()]], [[#dinsertLink|dinsertLink()]]<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: optional parameter, allows selection between sending the link to a miniconsole or the main window.<br />
* ''text:''<br />
: text to display in the echo. Same as a normal [[Manual:Lua_Functions#hecho|hecho()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''true:''<br />
: requires argument for the colouring to work.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
hinsertLink("#ff0000press #a52a2a,ffffffme!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
hinsertLink("#ff0000press #a52a2a,ffffffme!", [[send("hi")]], "This is a tooltip", true)<br />
</syntaxhighlight><br />
<br />
==hinsertPopup==<br />
;hinsertPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current cursor position, like [[#hinsertText|hinsertText()]]. 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.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code strings to do or a functions (since Mudlet 4.11). ie, <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
hinsertPopup("#ff0000activities#r to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"}, true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
hinsertPopup("#ff0000activities#r to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"}, true)<br />
</syntaxhighlight><br />
<br />
==hreplaceLine==<br />
;hreplaceLine ([window], text)<br />
: Replaces the output line from the game with a colour-tagged string.<br />
{{MudletVersion|4.12}}<br />
See Also: [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:Lua_Functions#hinsertText|hinsertText()]]<br />
;Parameters<br />
* ''window'' (optional):<br />
: the window to copy the text from. Defaults to "main".<br />
* ''text:''<br />
*: The text to display, with hex color values , ie ''#ff00ff''. If you'd like to use a background color, put it after a comma , - ''#,ff99ff''. You can use the ''#r'' tag to reset to the default color. <br />
:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua">hreplaceLine("#ff00ff[ALERT!]: #r"..line)<br />
</syntaxhighlight><br />
<br />
==hreplace==<br />
;hreplace([window, ]text)<br />
: Replaces the output line from the game with a colour-tagged string.<br />
See Also: [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:Lua_Functions#hinsertText|hinsertText()]]<br />
;Parameters<br />
* ''window:''<br />
*: The window to replace the selection in. Optional, defaults to the main window if not provided.<br />
* ''text:''<br />
*: The text to display, as with [[Manual:Lua_Functions#hecho|hecho()]]<br />
:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectCaptureGroup(1)<br />
hreplace("#EE00EE[ALERT!]: #r"..matches[2])<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.5}}<br />
<br />
==hideToolBar==<br />
;hideToolBar(name)<br />
: Hides the toolbar with the given name name and makes it disappear. If all toolbars of a tool bar area (top, left, right) are hidden, the entire tool bar area disappears automatically.<br />
<br />
;Parameters<br />
* ''name:''<br />
: name of the button group to hide<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
hideToolBar("my offensive buttons")<br />
</syntaxhighlight><br />
<br />
==hideWindow==<br />
;hideWindow(name)<br />
: This function hides a '''mini console''', a '''user window''' or a '''label''' with the given name. To show it again, use [[Manual:Lua_Functions#showWindow|showWindow()]].<br />
<br />
: See also: [[#createMiniConsole|createMiniConsole()]], [[#createLabel|createLabel()]], [[#deleteLabel|deleteLabel()]]<br />
<br />
;Parameters<br />
* ''name''<br />
: specifies the label or console you want to hide.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
function miniconsoleTest()<br />
local windowWidth, windowHeight = getMainWindowSize()<br />
<br />
-- create the miniconsole<br />
createMiniConsole("sys", windowWidth-650,0,650,300)<br />
setBackgroundColor("sys",255,69,0,255)<br />
setMiniConsoleFontSize("sys", 8)<br />
-- wrap lines in window "sys" at 40 characters per line - somewhere halfway, as an example<br />
setWindowWrap("sys", 40)<br />
<br />
print("created red window top-right")<br />
<br />
tempTimer(1, function()<br />
hideWindow("sys")<br />
print("hid red window top-right")<br />
end)<br />
<br />
tempTimer(3, function()<br />
showWindow("sys")<br />
print("showed red window top-right")<br />
end)<br />
end<br />
<br />
miniconsoleTest()<br />
</syntaxhighlight><br />
<br />
==insertLink==<br />
;insertLink([windowName], text, command, hint, [useCurrentLinkFormat])<br />
: Inserts a piece of text as a clickable link at the current cursor position - similar to [[Manual:Lua_Functions#insertText|insertText()]].<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) the window to insert the link in - use either "main" or omit for the main window.<br />
* ''text:''<br />
: text to display in the window. Same as a normal [[Manual:Lua_Functions#echo|echo()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''useCurrentLinkFormat:''<br />
: (optional) true or false. If true, then the link will use the current selection style (colors, underline, etc). If missing or false, it will use the default link style - blue on black underlined text.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- link with the default blue on white colors<br />
insertLink("hey, click me!", function() echo("you clicked me!\n") end, "Click me popup")<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
insertLink("hey, click me!", [[echo("you clicked me!\n")]], "Click me popup")<br />
<br />
-- use current cursor colors by adding true at the end<br />
fg("red")<br />
insertLink("hey, click me!", function() echo("you clicked me!\n") end, "Click me popup", true)<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
{{note}} The ''hint'' can contain the same sort of "rich-text" as can be used for "labels" - and if the ''command'' is set to be the empty string ''""'' then this can be a means to show extra information for the text when the mouse is hovered over it but without a command being run should it be clicked upon, e.g.:<br />
<br />
[[File:Screenshot showing example of fancy visual link.png|center|frame|link=|Screenshot showing example of fancy visual link]]<br />
<br />
==insertPopup==<br />
;insertPopup([windowName,] text, {commands}, {hints}[, useCurrentLinkFormat])<br />
: Creates text with a left-clickable link, and a right-click menu for more options exactly where the cursor position is, similar to [[Manual:Lua_Functions#insertText|insertText()]]. The inserted 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.<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to - use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text inserted for the popup to be applied to.<br />
* ''{commands}:''<br />
: a table of lua code commands to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight>.<br />
* ''{hints}:''<br />
: a table of strings which will be shown when the pointer hovers over the popup's text and on the right-click menu. ie, <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight>.<br />
* ''useCurrentLinkFormat:''<br />
: (optional) boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
insertPopup("activities to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"})<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
insertPopup("activities to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"})<br />
</syntaxhighlight><br />
<br />
==insertText==<br />
;insertText([windowName], text)<br />
: Inserts text at cursor postion in window - unlike [[Manual:Lua_Functions#echo|echo()]], which inserts the text at the end of the last line in the buffer (typically the one being processed by the triggers). You can use [[Manual:Lua_Functions#moveCursor|moveCursor()]] to move the cursor into position first.<br />
<br />
: insertHTML() also does the same thing as insertText, if you ever come across it.<br />
<br />
: See also: [[Manual:Lua_Functions#cinsertText|cinsertText()]]<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) The window to insert the text to.<br />
* ''text:''<br />
: The text you will insert into the current cursor position.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- move the cursor to the end of the previous line and insert some text<br />
<br />
-- move to the previous line<br />
moveCursor(0, getLineNumber()-1)<br />
-- move the end the of the previous line<br />
moveCursor(#getCurrentLine(), getLineNumber())<br />
<br />
fg("dark_slate_gray")<br />
insertText(' <- that looks nice.')<br />
<br />
deselect()<br />
resetFormat()<br />
moveCursorEnd()<br />
</syntaxhighlight><br />
<br />
==ioprint==<br />
;ioprint(text, some more text, ...)<br />
:Prints text to the to the stdout. This is only available if you [http://www.wikihow.com/Run-a-Program-on-Command-Prompt launched Mudlet from cmd.exe] on Windows, [http://www.wikihow.com/Open-Applications-Using-Terminal-on-Mac from the terminal] on Mac, or from the terminal on a Linux OS (launch the terminal program, type ''mudlet'' and press enter).<br />
<br />
Similar to [[Manual:Lua_Functions#echo|echo()]], but does not require a "\n" at the end for a newline and can print several items given to it. It cannot print whole tables. This function works similarly to the print() you will see in guides for Lua.<br />
<br />
This function is useful in working out potential crashing problems with Mudlet due to your scripts - as you will still see whatever it printed when Mudlet crashes.<br />
<br />
;Parameters<br />
* ''text:''<br />
: The information you want to display.<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
ioprint("hi!")<br />
ioprint(1,2,3)<br />
ioprint(myvariable, someothervariable, yetanothervariable)<br />
</syntaxhighlight><br />
<br />
==isAnsiBgColor==<br />
; isAnsiBgColor(bgColorCode)<br />
: This function tests if the first character of '''the current selection''' in the main console has the background color specified by bgColorCode.<br />
<br />
;Parameters<br />
* ''bgColorCode:''<br />
: A color code to test for, possible codes are:<br />
<br />
<syntaxhighlight lang="lua"><br />
0 = default text color<br />
1 = light black<br />
2 = dark black<br />
3 = light red<br />
4 = dark red<br />
5 = light green<br />
6 = dark green<br />
7 = light yellow<br />
8 = dark yellow<br />
9 = light blue<br />
10 = dark blue<br />
11 = light magenta<br />
12 = dark magenta<br />
13 = light cyan<br />
14 = dark cyan<br />
15 = light white<br />
16 = dark white<br />
</syntaxhighlight><br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectString( matches[1], 1 )<br />
if isAnsiBgColor( 5 ) then<br />
bg( "red" );<br />
resetFormat();<br />
echo( "yes, the background of the text is light green" )<br />
else<br />
echo( "no sorry, some other background color" )<br />
end<br />
</syntaxhighlight><br />
<br />
{{note}}<br />
The variable named matches[1] holds the matched trigger pattern - even in substring, exact match, begin of line substring trigger patterns or even color triggers that do not know about the concept of capture groups. Consequently, you can always test if the text that has fired the trigger has a certain color and react accordingly. This function is faster than using getBgColor() and then handling the color comparison in Lua.<br />
<br />
''Also note that the color code numbers are Mudlet specific, though they do represent the colors in the 16 ANSI color-set for the main console they are not in the same order and they additionally have the default background color in the zeroth position.''<br />
<br />
==isAnsiFgColor==<br />
; isAnsiFgColor(fgColorCode)<br />
: This function tests if the first character of '''the current selection''' in the main console has the foreground color specified by fgColorCode.<br />
<br />
;Parameters<br />
* ''fgColorCode:''<br />
: A color code to test for, possible codes are:<br />
<br />
<syntaxhighlight lang="lua"><br />
0 = default text color<br />
1 = light black<br />
2 = dark black<br />
3 = light red<br />
4 = dark red<br />
5 = light green<br />
6 = dark green<br />
7 = light yellow<br />
8 = dark yellow<br />
9 = light blue<br />
10 = dark blue<br />
11 = light magenta<br />
12 = dark magenta<br />
13 = light cyan<br />
14 = dark cyan<br />
15 = light white<br />
16 = dark white<br />
</syntaxhighlight><br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectString( matches[1], 1 )<br />
if isAnsiFgColor( 5 ) then<br />
bg( "red" );<br />
resetFormat();<br />
echo( "yes, the text is light green" )<br />
else<br />
echo( "no sorry, some other foreground color" )<br />
end<br />
</syntaxhighlight><br />
<br />
{{note}}<br />
The variable named matches[1] holds the matched trigger pattern - even in substring, exact match, begin of line substring trigger patterns or even color triggers that do not know about the concept of capture groups. Consequently, you can always test if the text that has fired the trigger has a certain color and react accordingly. This function is faster than using getFgColor() and then handling the color comparison in Lua.<br />
<br />
''Also note that the color code numbers are Mudlet specific, though they do represent the colors in the 16 ANSI color-set for the main console they are not in the same order and they additionally have the default foreground color in the zeroth position.''<br />
<br />
==loadWindowLayout==<br />
;loadWindowLayout()<br />
:Resets the layout of userwindows (floating miniconsoles) to the last saved state.<br />
<br />
:See also: [[#saveWindowLayout|saveWindowLayout()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
{{MudletVersion|3.2}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
loadWindowLayout()<br />
</syntaxhighlight><br />
<br />
==lowerWindow==<br />
;lowerWindow(labelName)<br />
:Moves the referenced label/console below all other labels/consoles. For the opposite effect, see: [[#raiseWindow | raiseWindow()]].<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: the name of the label/console you wish to move below the rest.<br />
<br />
{{MudletVersion|3.1}}<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
createLabel("blueLabel", 300, 300, 100, 100, 1) --creates a blue label<br />
setBackgroundColor("blueLabel", 50, 50, 250, 255)<br />
<br />
createLabel("redLabel", 350, 350, 100, 100, 1) --creates a red label which is placed on TOP of the blue label, as the last made label will sit at the top of the rest<br />
setBackgroundColor("redLabel", 250, 50, 50, 255)<br />
<br />
lowerWindow("redLabel") --lowers redLabel, causing blueLabel to be back on top<br />
</syntaxhighlight><br />
<br />
==moveCursor==<br />
;moveCursor([windowName], x, y)<br />
: Moves the user cursor of the window windowName, or the main window, to the absolute point (x,y). This function returns false if such a move is impossible e.g. the coordinates don’t exist. To determine the correct coordinates use [[Manual:Lua_Functions#getLineNumber|getLineNumber()]], [[Manual:Lua_Functions#getColumnNumber|getColumnNumber()]] and [[Manual:Lua_Functions#getLastLineNumber|getLastLineNumber()]]. The trigger engine will always place the user cursor at the beginning of the current line before the script is run. If you omit the windowName argument, the main screen will be used.<br />
<br />
: Returns ''true'' or ''false'' depending on if the cursor was moved to a valid position. Check this before doing further cursor operations - because things like deleteLine() might invalidate this.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) The window you are going to move the cursor in.<br />
* ''x:''<br />
: The horizontal axis in the window - that is, the letter position within the line.<br />
* ''y:''<br />
: The vertical axis in the window - that is, the line number.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- move cursor to the start of the previous line and insert -<(<br />
-- the first 0 means we want the cursor right at the start of the line,<br />
-- and getLineNumber()-1 means we want the cursor on the current line# - 1 which<br />
-- equals to the previous line<br />
moveCursor(0, getLineNumber()-1)<br />
insertText("-<(")<br />
<br />
-- now we move the cursor at the end of the previous line. Because the<br />
-- cursor is on the previous line already, we can use #getCurrentLine()<br />
-- to see how long it is. We also just do getLineNumber() because getLineNumber()<br />
-- returns the current line # the cursor is on<br />
moveCursor(#getCurrentLine(), getLineNumber())<br />
insertText(")>-")<br />
<br />
-- finally, reset it to the end where it was after our shenaningans - other scripts<br />
-- could expect the cursor to be at the end<br />
moveCursorEnd()<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- a more complicated example showing how to work with Mudlet functions<br />
<br />
-- set up the small system message window in the top right corner<br />
-- determine the size of your screen<br />
local WindowWidth, WindowHeight = getMainWindowSize()<br />
<br />
-- define a mini console named "sys" and set its background color<br />
createMiniConsole("sys",WindowWidth-650,0,650,300)<br />
setBackgroundColor("sys",85,55,0,255)<br />
<br />
-- you *must* set the font size, otherwise mini windows will not work properly<br />
setMiniConsoleFontSize("sys", 12)<br />
-- wrap lines in window "sys" at 65 characters per line<br />
setWindowWrap("sys", 60)<br />
-- set default font colors and font style for window "sys"<br />
setTextFormat("sys",0,35,255,50,50,50,0,0,0)<br />
-- clear the window<br />
clearUserWindow("sys")<br />
<br />
moveCursorEnd("sys")<br />
setFgColor("sys", 10,10,0)<br />
setBgColor("sys", 0,0,255)<br />
echo("sys", "test1---line1\n<this line is to be deleted>\n<this line is to be deleted also>\n")<br />
echo("sys", "test1---line2\n")<br />
echo("sys", "test1---line3\n")<br />
setTextFormat("sys",158,0,255,255,0,255,0,0,0);<br />
--setFgColor("sys",255,0,0);<br />
echo("sys", "test1---line4\n")<br />
echo("sys", "test1---line5\n")<br />
moveCursor("sys", 1,1)<br />
<br />
-- deleting lines 2+3<br />
deleteLine("sys")<br />
deleteLine("sys")<br />
<br />
-- inserting a line at pos 5,2<br />
moveCursor("sys", 5,2)<br />
setFgColor("sys", 100,100,0)<br />
setBgColor("sys", 255,100,0)<br />
insertText("sys","############## line inserted at pos 5/2 ##############")<br />
<br />
-- inserting a line at pos 0,0<br />
moveCursor("sys", 0,0)<br />
selectCurrentLine("sys")<br />
setFgColor("sys", 255,155,255)<br />
setBold( "sys", true );<br />
setUnderline( "sys", true )<br />
setItalics( "sys", true )<br />
insertText("sys", "------- line inserted at: 0/0 -----\n")<br />
<br />
setBold( "sys", true )<br />
setUnderline( "sys", false )<br />
setItalics( "sys", false )<br />
setFgColor("sys", 255,100,0)<br />
setBgColor("sys", 155,155,0)<br />
echo("sys", "*** This is the end. ***\n")<br />
</syntaxhighlight><br />
<br />
==moveCursorDown==<br />
;moveCursorDown([windowName,] [lines,] [keepHorizontal])<br />
: Moves the cursor in the given window down a specified number of lines.<br />
: See also: [[#moveCursor|moveCursor()]], [[#moveCursorUp|moveCursorUp()]], [[#moveCursorEnd|moveCursorEnd()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the miniconsole/userwindow, or "main" for the main window.<br />
<br />
* ''lines:''<br />
: (optional) number of lines to move cursor down by, or 1 by default.<br />
<br />
* ''keepHorizontal:''<br />
: (optional) true/false to specify if horizontal position should be retained, or reset to the start of the line otherwise.<br />
<br />
{{MudletVersion|3.17}}<br />
<br />
;Example<br />
'' Need example''<br />
<br />
==moveCursorUp==<br />
;moveCursorUp([windowName,] [lines,] [keepHorizontal])<br />
: Moves the cursor in the given window up a specified number of lines.<br />
: See also: [[#moveCursor|moveCursor()]], [[#moveCursorDown|moveCursorDown()]], [[#moveCursorEnd|moveCursorEnd()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the miniconsole/userwindow, or "main" for the main window.<br />
<br />
* ''lines:''<br />
: (optional) number of lines to move cursor up by, or 1 by default.<br />
<br />
* ''keepHorizontal:''<br />
: (optional) true/false to specify if horizontal position should be retained, or reset to the start of the line otherwise.<br />
<br />
{{MudletVersion|3.17}}<br />
<br />
;Example<br />
'' Need example''<br />
<br />
==moveCursorEnd==<br />
;moveCursorEnd([windowName])<br />
: Moves the cursor to the end of the buffer. "main" is the name of the main window, otherwise use the name of your user window.<br />
: See Also: [[Manual:Lua_Functions#moveCursor|moveCursor()]]<br />
<br />
: Returns true or false<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the miniconsole/userwindow, or "main" for the main window.<br />
<br />
;Example<br />
'' Need example''<br />
<br />
==moveGauge==<br />
;moveGauge(gaugeName, newX, newY)<br />
:Moves a gauge created with createGauge to the new x,y coordinates. Remember the coordinates are relative to the top-left corner of the output window.<br />
<br />
;Parameters<br />
* ''gaugeName:''<br />
: The name of your gauge<br />
* ''newX:''<br />
: The horizontal pixel location<br />
* ''newY:''<br />
: The vertical pixel location<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This would move the health bar gauge to the location 1200, 400<br />
moveGauge("healthBar", 1200, 400)<br />
</syntaxhighlight><br />
<br />
==moveWindow==<br />
;moveWindow(name, x, y)<br />
:This function moves window name to the given x/y coordinate. The main screen cannot be moved. Instead you’ll have to set appropriate border values → preferences to move the main screen e.g. to make room for chat or information mini consoles, or other GUI elements. In the future moveWindow() will set the border values automatically if the name parameter is omitted.<br />
<br />
:See Also: [[#createMiniConsole | createMiniConsole()]], [[#createLabel | createLabel()]], [[#handleWindowResizeEvent | handleWindowResizeEvent()]], [[#resizeWindow | resizeWindow()]], [[#setBorderSizes | setBorderSizes()]], [[#openUserWindow | openUserWindow()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name of your window<br />
* ''newX:''<br />
: The horizontal pixel location<br />
* ''newY:''<br />
: The vertical pixel location<br />
<br />
{{note}}<br />
Since Mudlet 3.7 this method can also be used on UserWindow consoles.<br />
<br />
==openUserWindow==<br />
;openUserWindow(windowName, [restoreLayout], [autoDock], [dockingArea])<br />
: Opens a user dockable console window for user output e.g. statistics, chat etc. If a window of such a name already exists, nothing happens. You can move these windows (even to a different screen on a system with a multi-screen display), dock them on any of the four sides of the main application window, make them into notebook tabs or float them.<br />
<br />
: See also: [[#resetUserWindowTitle|resetUserWindowTitle()]], [[#setUserWindowTitle|setUserWindowTitle()]], [[#saveWindowLayout|saveWindowLayout()]], [[#loadWindowLayout|loadWindowLayout()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: name of your window, it must be unique across ALL profiles if more than one is open (for multi-playing).<br />
* ''restoreLayout:'' (available in Mudlet 3.2+)<br />
: (optional) - only relevant, if ''false'' is provided. Then the window won't be restored to its last known position.<br />
* ''autoDock:'' (available in Mudlet 4.7+)<br />
: (optional) - only relevant, if ''false'' is provided. Then the window won't dock automatically at the corners.<br />
* ''dockingArea:'' (available in Mudlet 4.7+)<br />
: (optional) - the area your UserWindow will be docked at. possible docking areas your UserWindow will be created in (f" floating "t" top "b" bottom "r" right and "l" left). Docking area is "right" if not given any value.<br />
<br />
{{note}}<br />
Since Mudlet version 3.2, Mudlet will automatically remember the window's last position.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
openUserWindow("My floating window")<br />
cecho("My floating window", "<red>hello <blue>bob!")<br />
<br />
-- if you don't want Mudlet to remember its last position:<br />
openUserWindow("My floating window", false)<br />
</syntaxhighlight><br />
<br />
==paste==<br />
;paste(windowName)<br />
: Pastes the previously copied text including all format codes like color, font etc. at the current user cursor position. The [[#copy | copy()]] and [[#paste | paste()]] functions can be used to copy formated text from the main window to a user window without losing colors e. g. for chat windows, map windows etc.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of your window<br />
<br />
==pauseMovie==<br />
;pauseMovie(label name)<br />
<br />
: Pauses the gif animation on the label<br />
: Returns true<br />
<br />
: See also: [[Manual:Lua_Functions#setMovie|setMovie()]], [[Manual:Lua Functions#startMovie|startMovie()]], [[Manual:Lua_Functions#setMovieFrame|setMovieFrame()]], [[Manual:Lua_Functions#setMovieSpeed|setMovieSpeed()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''label name:'' <br />
: name of the gif label <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create a label with the name myMovie<br />
createLabel("myMovie",0,0,200,200,0)<br />
<br />
-- puts the gif on the label and animates it<br />
setMovie("myMovie", getMudletHomeDir().."/movie.gif")<br />
--stops the animation<br />
pauseMovie("myMovie")<br />
<br />
</syntaxhighlight><br />
<br />
==prefix==<br />
;prefix(text, [writingFunction], [foregroundColor], [backgroundColor], [windowName])<br />
:Prefixes text at the beginning of the current line when used in a trigger.<br />
<br />
;Parameters<br />
* ''text:''<br />
: the information you want to prefix<br />
* "writingFunction:"<br />
: optional parameter, allows the selection of different functions to be used to write the text, valid options are: echo, cecho, decho, and hecho.<br />
* "foregroundColor:"<br />
: optional parameter, allows a foreground color to be specified if using the echo function using a color name, as with the fg() function<br />
* "backgroundColor:"<br />
: optional parameter, allows a background color to be specified if using the echo function using a color name, as with the bg() function<br />
* "windowName:"<br />
: optional parameter, allows the selection a miniconsole or the main window for the line that will be prefixed<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
-- Prefix the hours, minutes and seconds onto our prompt even though Mudlet has a button for that<br />
prefix(os.date("%H:%M:%S "))<br />
-- Prefix the time in red into a miniconsole named "my_console"<br />
prefix(os.date("<red>%H:%M:%S<reset>", cecho, nil, nil, "my_console"))<br />
</syntaxhighlight><br />
<br />
: See also: [[#suffix | suffix()]]<br />
<br />
==print==<br />
;print(text, some more text, ...)<br />
:Prints text to the main window. Similar to [[Manual:Lua_Functions#echo|echo()]], but does not require a "\n" at the end for a newline and can print several items given to it. It cannot print whole tables - use [[Manual:Lua_Functions#display|display()]] for those. This function works similarly to the print() you will see in guides for Lua.<br />
<br />
;Parameters<br />
* ''text:''<br />
: The information you want to display.<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
print("hi!")<br />
print(1,2,3)<br />
print(myvariable, someothervariable, yetanothervariable)<br />
</syntaxhighlight><br />
<br />
==raiseWindow==<br />
;raiseWindow(labelName)<br />
:Raises the referenced label/console above all over labels/consoles. For the opposite effect, see: [[#lowerWindow | lowerWindow()]].<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: the name of the label/console you wish to bring to the top of the rest.<br />
<br />
{{MudletVersion|3.1}}<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
createLabel("blueLabel", 300, 300, 100, 100, 1) --creates a blue label<br />
setBackgroundColor("blueLabel", 50, 50, 250, 255)<br />
<br />
createLabel("redLabel", 350, 350, 100, 100, 1) --creates a red label which is placed on TOP of the bluewindow, as the last made label will sit at the top of the rest<br />
setBackgroundColor("redLabel", 250, 50, 50, 255)<br />
<br />
raiseWindow("blueLabel") --raises blueLabel back at the top, above redLabel<br />
</syntaxhighlight><br />
<br />
==removeCommandLineMenuEvent==<br />
;removeCommandLineMenuEvent([window,] label)<br />
<br />
:Removes an existing command line menu event.<br />
<br />
;Parameters<br />
* ''window:''<br />
: Window that item is associated with. Optional, defaults to "main" (main window console).<br />
* ''label:''<br />
: Label under which element is registered<br />
<br />
;Returns <br />
* Returns ''True'' If the mouse event was removed successfully.<br />
<br />
==removeMouseEvent==<br />
; removeMouseEvent(uniqueName)<br />
<br />
:Removes an existing mouse event. Returns ''True'' If the event exists and was removed successfully, throws a warning if the event doesn't exist.<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
;See also: [[Manual:Lua_Functions#getMouseEvents|getMouseEvents()]], [[Manual:Lua_Functions#addMouseEvent|addMouseEvent()]]<br />
<br />
;Parameters<br />
* ''uniqueName:''<br />
: A unique identifier that the mouse event was registered under.<br />
<br />
;Returns <br />
* Returns ''True'' If the mouse event was removed successfully.<br />
<br />
==replace==<br />
;replace([windowName], with, [keepcolor])<br />
:Replaces the currently selected text with the new text. To select text, use [[#selectString | selectString()]], [[#selectSection | selectSection()]] or a similar function.<br />
<br />
{{note}}<br />
If you’d like to delete/gag the whole line, use [[#deleteLine | deleteLine()]] instead.<br />
<br />
{{note}}<br />
when used outside of a trigger context (for example, in a timer instead of a trigger), replace() won't trigger the screen to refresh. Instead, use ''replace("")'' and ''insertText("new text")'' as [[#insertText | insertText()]] does.<br />
<br />
See also: [[#creplace|creplace]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of window (a miniconsole)<br />
* ''with:''<br />
: the new text to display.<br />
* ''keepcolor:''<br />
: (optional) argument, setting this to ''true'' will keep the existing colors (since Mudlet 3.0+)<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
-- replace word "troll" with "cute trolly"<br />
selectString("troll",1)<br />
replace("cute trolly")<br />
<br />
-- replace the whole line<br />
selectCurrentLine()<br />
replace("Out with the old, in with the new!")<br />
</syntaxhighlight><br />
<br />
==replaceAll==<br />
;replaceAll(what, with, [keepcolor])<br />
: Replaces all occurrences of ''what'' in the current line with ''with''.<br />
<br />
;Parameters<br />
* ''what:''<br />
: the text to replace<br />
{{note}}<br />
This accepts [https://www.lua.org/pil/20.2.html Lua patterns]<br />
* ''with:''<br />
: the new text to have in place<br />
* ''keepcolor:''<br />
: setting this to true will keep the existing colors.<br />
{{note}} keepcolor is available in Mudlet 4.10+<br />
<br />
;Examples:<br />
<syntaxhighlight lang="lua"><br />
-- replace all occurrences of the word "south" in the line with "north"<br />
replaceAll("south", "north")<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- replace all occurrences of the text that the variable "target" has<br />
replaceAll(target, "The Bad Guy")<br />
</syntaxhighlight><br />
<br />
==replaceLine==<br />
;replaceLine ([window], text)<br />
: Replaces the output line from the game with your own text.<br />
See Also: [[Manual:Lua_Functions#echo|echo()]], [[Manual:Lua_Functions#insertText|insertText()]]<br />
<br />
;Parameters<br />
* ''window'' (optional):<br />
: the window to copy the text from. Defaults to "main".<br />
* ''text:''<br />
*: The text to display<br />
<br />
;Example<br />
<syntaxhighlight lang="lua">replaceLine("[ALERT!]: "..line)<br />
</syntaxhighlight><br />
<br />
==replaceWildcard==<br />
;replaceWildcard(which, replacement, [keepcolor])<br />
: Replaces the given wildcard (as a number) with the given text. Equivalent to doing:<br />
<br />
<syntaxhighlight lang="lua"><br />
selectString(matches[2], 1)<br />
replace("text")<br />
</syntaxhighlight><br />
<br />
;Parameters<br />
* ''which:''<br />
: Wildcard to replace.<br />
* ''replacement:''<br />
: Text to replace the wildcard with.<br />
* ''keepcolor:''<br />
: setting this to true will keep the existing colors<br />
{{note}} keepcolor available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
replaceWildcard(2, "hello") -- on a perl regex trigger of ^You wave (goodbye)\.$, it will make it seem like you waved hello<br />
</syntaxhighlight><br />
<br />
==resetCmdLineAction==<br />
;resetCmdLineAction(commandLineName)<br />
: Resets the action on the command line so the it behaves like the main command line again.<br />
;Parameters<br />
<br />
* ''commandLineName''<br />
: The name of the command line the action will be resetet.<br />
: See also: [[#setCmdLineAction | setCmdLineAction()]]<br />
{{MudletVersion|4.10}}<br />
<br />
==resetBackgroundImage==<br />
;resetBackgroundImage([windowName])<br />
: Resets the console background-image<br />
;Parameters<br />
<br />
* ''windowName''<br />
: (optional) name of the console the image will be reset<br />
: See also: [[#setBackgroundImage | setBackgroundImage()]]<br />
{{MudletVersion|4.10}}<br />
<br />
==resetFormat==<br />
;resetFormat([windowName])<br />
: Resets the colour/bold/italics formatting. Always use this function when done adjusting formatting, so make sure what you've set doesn't 'bleed' onto other triggers/aliases.<br />
<br />
; Parameters<br />
* ''windowName''<br />
: (optional) name of the console to reset formatting. Defaults to "main" if missing.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- select and set the 'Tommy' to red in the line<br />
if selectString("Tommy", 1) ~= -1 then fg("red") end<br />
<br />
-- now reset the formatting, so our echo isn't red<br />
resetFormat()<br />
echo(" Hi Tommy!")<br />
<br />
-- another example: just highlighting some words<br />
for _, word in ipairs{"he", "she", "her", "their"} do<br />
if selectString(word, 1) ~= -1 then<br />
bg("blue")<br />
end<br />
end<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
==resetLabelCursor==<br />
;resetLabelCursor(labelName)<br />
: Resets your mouse cursor to the default one.<br />
<br />
: See also: [[#setLabelCursor|setLabelCursor()]], [[#setLabelCustomCursor|setLabelCustomCursor()]]<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
;Parameters<br />
* ''labelName'': label for which to reset the cursor for.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
resetLabelCursor("myLabel")<br />
-- This will reset the mouse cursor over myLabel to the default one<br />
</syntaxhighlight><br />
<br />
==resetLabelToolTip==<br />
;resetLabelToolTip(labelName)<br />
: Resets the tooltip on the given label.<br />
{{MudletVersion|4.6.1}}<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label the tooltip will be reseted.<br />
: See also: [[#setLabelToolTip | setLabelToolTip()]]<br />
<br />
==resetMapWindowTitle==<br />
;resetMapWindowTitle()<br />
: resets the title of the popped out map window to default.<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
: See also: [[#setMapWindowTitle|setMapWindowTitle()]]<br />
<br />
==resetUserWindowTitle==<br />
;resetUserWindowTitle(windowName)<br />
: resets the title of the UserWindow windowName<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the userwindow for which the title will be resetet<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
: See also: [[#setUserWindowTitle|setUserWindowTitle()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
==resizeWindow==<br />
;resizeWindow(windowName, width, height)<br />
: Resizes a mini console, label, or floating User Windows.<br />
:See also: [[#createMiniConsole | createMiniConsole()]], [[#createLabel | createLabel()]], [[#handleWindowResizeEvent | handleWindowResizeEvent()]], [[#resizeWindow | resizeWindow()]], [[#setBorderSizes | setBorderSizes()]], [[#openUserWindow | openUserWindow()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of your window<br />
* ''width:''<br />
: The new width you want<br />
* ''height:''<br />
: The new height you want<br />
<br />
{{note}}<br />
Since Mudlet 3.7 this method can also be used on User Window consoles if they are floating.<br />
<br />
==saveWindowLayout==<br />
;saveWindowLayout()<br />
:Saves the layout of userwindows (floating miniconsoles), in case you'd like to load them again later.<br />
<br />
:See also: [[#loadWindowLayout|loadWindowLayout()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
{{MudletVersion|3.2}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
saveWindowLayout()<br />
</syntaxhighlight><br />
<br />
==scaleMovie==<br />
;scaleMovie(label name, [autoscale])<br />
:Resizes the gif to fill the full size of its label<br />
<br />
:See also: [[#setMovie|setMovie()]], [[#startMovie|startMovie()]]<br />
<br />
;Parameters<br />
* ''label name:'' <br />
: name of the label the gif will be scaled upon<br />
* ''autoscale:''<br />
: (optional) if false the gif will only be scaled once, resizing the label won't rescale the image<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
==selectCaptureGroup==<br />
;selectCaptureGroup(groupNumber)<br />
: Selects the content of the capture group number in your Perl regular expression (from matches[]). Also works with named capture group. It does not work with multimatches.<br />
<br />
:See also: [[#selectCurrentLine| selectCurrentLine()]]<br />
<br />
;Parameters<br />
* ''groupNumberOrName:''<br />
: number of the capture group you want to select, or the name of the capture group as a string<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--First, set a Perl Reqular expression e.g. "you have (\d+) Euro".<br />
--If you want to color the amount of money you have green you do:<br />
<br />
selectCaptureGroup(1)<br />
setFgColor(0,255,0)<br />
<br />
-- Or perhaps instead if you were to use "you have (?<euro>\d+) Euro"<br />
selectCaptureGroup("euro")<br />
fg("green")<br />
</syntaxhighlight><br />
<br />
==selectCmdLineText==<br />
;selectCmdLineText([commandLine])<br />
: Selects the text in your command line. You can specify which one, if you got many.<br />
<br />
:See also: [[#createCommandLine| createCommandLine()]]<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
;Parameters<br />
* ''commandLine:''<br />
: (optional) name of the command line you want to have selected<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- First, create an extra commandline with the following lua script:<br />
inputContainer = inputContainer or Adjustable.Container:new({<br />
x = 0, y = "-4c",<br />
name = "InputContainer", padding = 2,<br />
width = "100%", height = "4c",<br />
autoLoad = false<br />
})<br />
extraCmdLine = extraCmdLine or Geyser.CommandLine:new({<br />
name = "extraCmdLine",<br />
x = 0, y = 0, width = "100%", height = "100%"<br />
}, inputContainer)<br />
inputContainer:attachToBorder("bottom")<br />
<br />
-- Now you can send the following lua code with your main command line.<br />
-- It will give 2 seconds time to click around, unselect its text, etc. before selecting its text for you:<br />
lua tempTimer(2, function() selectCmdLineText() end)<br />
<br />
-- This will instead select the text in the command line named extraCmdLine:<br />
lua selectCmdLineText('extraCmdLine')<br />
<br />
-- Same as before, but using the Geyser.CommandLine function instead:<br />
lua extraCmdLine:selectText() <br />
</syntaxhighlight><br />
<br />
==selectCurrentLine==<br />
; selectCurrentLine([windowName])<br />
: Selects the content of the current line that the cursor at. By default, the cursor is at the start of the current line that the triggers are processing, but you can move it with the moveCursor() function.<br />
<br />
{{note}}<br />
This selects the whole line, including the linebreak - so it has a subtle difference from the slightly slower ''selectString(line, 1)'' selection method.<br />
: See also: [[Manual:Lua_Functions#selectString|selectString()]], [[#selectCurrentLine| selectCurrentLine()]], [[#getSelection| getSelection()]], [[Manual:Lua_Functions#getCurrentLine|getCurrentLine()]], [[#deselect|deselect()]]<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window in which to select text.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- color the whole line green!<br />
selectCurrentLine()<br />
fg("green")<br />
deselect()<br />
resetFormat()<br />
<br />
-- to select the previous line, you can do this:<br />
moveCursor(0, getLineNumber()-1)<br />
selectCurrentLine()<br />
<br />
-- to select two lines back, this:<br />
moveCursor(0, getLineNumber()-2)<br />
selectCurrentLine()<br />
<br />
</syntaxhighlight><br />
<br />
==selectSection==<br />
;selectSection( [windowName], fromPosition, length )<br />
: Selects the specified parts of the line starting ''from'' the left and extending to the right for however ''how long''. The line starts from 0.<br />
: Returns true if the selection was successful, and false if the line wasn't actually long enough or the selection couldn't be done in general.<br />
<br />
:See also:[[#selectString| selectString()]], [[#selectCurrentLine| selectCurrentLine()]], [[#getSelection| getSelection()]]<br />
<br />
;Parameters<br />
* "windowName:"<br />
: (optional) name of the window in which to select text. By default the main window, if no windowName is given.<br />
: Will not work if "main" is given as the windowName to try to select from the main window.<br />
* ''fromPosition:''<br />
: number to specify at which position in the line to begin selecting<br />
* ''length:''<br />
: number to specify the amount of characters you want to select<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- select and colour the first character in the line red<br />
if selectSection(0,1) then fg("red") end<br />
<br />
-- select and colour the second character green (start selecting from the first character, and select 1 character)<br />
if selectSection(1,1) then fg("green") end<br />
<br />
-- select and colour three character after the first two grey (start selecting from the 2nd character for 3 characters long)<br />
if selectSection(2,3) then fg("grey") end<br />
</syntaxhighlight><br />
<br />
==selectString==<br />
;selectString([windowName], text, number_of_match)<br />
: Selects a substring from the line where the user cursor is currently positioned - allowing you to edit selected text (apply colour, make it be a link, copy to other windows or other things).<br />
<br />
{{note}}<br />
You can move the user cursor with [[#moveCursor | moveCursor()]]. When a new line arrives from the game, the user cursor is positioned at the beginning of the line. However, if one of your trigger scripts moves the cursor around you need to take care of the cursor position yourself and make sure that the cursor is in the correct line if you want to call one of the select functions. To deselect text, see [[#deselect | deselect()]].<br />
<br />
: See also: [[#deselect|deselect()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the window in which to select text. By default the main window, if no windowName or an empty string is given.<br />
* ''text:''<br />
: The text to select. It is matched as a substring match (so the text anywhere within the line will get selected).<br />
* ''number_of_match:''<br />
: The occurrence of text on the line that you'd like to select. For example, if the line was "Bob and Bob", 1 would select the first Bob, and 2 would select the second Bob.<br />
<br />
Returns position in line or -1 on error (text not found in line)<br />
<br />
{{note}}<br />
To prevent working on random text if your selection didn't actually select anything, check the -1 return code before doing changes:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
if selectString("big monster", 1) > -1 then fg("red") end<br />
</syntaxhighlight><br />
<br />
==setAppStyleSheet==<br />
;setAppStyleSheet(stylesheet [, tag])<br />
: Sets a stylesheet for the entire Mudlet application and every open profile. Because it affects other profiles that might not be related to yours, it's better to use [[#setProfileStyleSheet|setProfileStyleSheet()]] instead of this function.<br />
<br />
: Raises the sysAppStyleSheetChange event which comes with two arguments in addition to the event name. The first is the optional tag which was passed into the function, or "" if nothing was given. The second is the profile which made the stylesheet changes.<br />
<br />
: See also: [[#setProfileStyleSheet|setProfileStyleSheet()]]<br />
<br />
;Parameters<br />
<br />
* ''stylesheet:''<br />
: The entire stylesheet you'd like to use.<br />
<br />
* ''tag:'' (available in Mudlet 3.19+)<br />
: (optional) string tag or identifier that will be passed as a second argument in the ''sysAppStyleSheetChange'' event<br />
<br />
;References<br />
: See [http://qt-project.org/doc/qt-5/stylesheet-reference.html Qt Style Sheets Reference] for the list of widgets you can style and CSS properties you can apply on them.<br />
: See also [https://github.com/vadi2/QDarkStyleSheet/blob/master/qdarkstyle/style.qss QDarkStyleSheet], a rather extensive stylesheet that shows you all the different configuration options you could apply, available as an [http://forums.mudlet.org/viewtopic.php?f=6&t=17624 mpackage here].<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- credit to Akaya @ http://forums.mudlet.org/viewtopic.php?f=5&t=4610&start=10#p21770<br />
local background_color = "#26192f"<br />
local border_color = "#b8731b"<br />
<br />
setAppStyleSheet([[<br />
QMainWindow {<br />
background: ]]..background_color..[[;<br />
}<br />
QToolBar {<br />
background: ]]..background_color..[[;<br />
}<br />
QToolButton {<br />
background: ]]..background_color..[[;<br />
border-style: solid;<br />
border-width: 2px;<br />
border-color: ]]..border_color..[[;<br />
border-radius: 5px;<br />
font-family: BigNoodleTitling;<br />
color: white;<br />
margin: 2px;<br />
font-size: 12pt;<br />
}<br />
QToolButton:hover { background-color: grey;}<br />
QToolButton:focus { background-color: grey;}<br />
]])<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
{{note}} Enhanced in Mudlet version 3.19.0 to generate an event that profiles/packages can utilise to redraw any parts of the UI that they themselves had previously styled so their effects can be re-applied to the new application style.<br />
<br />
It is anticipated that the Mudlet application itself will make further use of application styling effects and two strings are provisionally planned for the second parameter in the ''sysAppStyleSheetChange'' event: "''mudlet-theme-dark''" and "''mudlet-theme-light''"; it will also set the third parameter to "''system''".<br />
<br />
==setBackgroundColor==<br />
;setBackgroundColor([windowName], r, g, b, [transparency])<br />
: Sets the background for the given label, miniconsole, or userwindow. Colors are from 0 to 255 (0 being black), and transparency is from 0 to 255 (0 being completely transparent).<br />
<br />
;Parameters<br />
<br />
* ''windowName:''<br />
: (optional) name of the label/miniconsole/userwindow to change the background color on, or "main" for the main window.<br />
* ''r:''<br />
: Amount of red to use, from 0 (none) to 255 (full).<br />
* ''g:''<br />
: Amount of green to use, from 0 (none) to 255 (full).<br />
* ''b:''<br />
: Amount of red to use, from 0 (none) to 255 (full).<br />
* ''transparency:''<br />
: (optional) amount of transparency to use, from 0 (fully transparent) to 255 (fully opaque). Defaults to 255 if omitted.<br />
<br />
{{note}}<br />
Transparency also available for main/miniconsoles in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- make a red label that's somewhat transparent<br />
setBackgroundColor("some label",255,0,0,200)<br />
</syntaxhighlight><br />
<br />
==setBackgroundImage==<br />
;setBackgroundImage(labelName, imageLocation)<br />
;setBackgroundImage([windowname], imageLocation, [mode])<br />
: Loads an image file (png) as a background image for a label or console. This can be used to display clickable buttons in combination with [[Manual:Lua_Functions#setLabelClickCallback|setLabelClickCallback()]] and such.<br />
<br />
{{note}}<br />
You can also load images on labels via [[Manual:Lua_Functions#setLabelStyleSheet|setLabelStyleSheet()]].<br />
<br />
;Parameters (label)<br />
<br />
* ''labelName:''<br />
: The name of the label to change it's background color.<br />
* ''imageLocation:''<br />
: The full path to the image location. It's best to use [[ ]] instead of "" for it - because for Windows paths, backslashes need to be escaped.<br />
<br />
;Parameters (consoles)<br />
<br />
* ''windowName:''<br />
: (optional) name of the miniconsole/userwindow to change the background image on, or "main" for the main window.<br />
* ''imageLocation:''<br />
: The full path to the image location. It's best to use [[ ]] instead of "" for it - because for Windows paths, backslashes need to be escaped.<br />
* ''mode:''<br />
: (optional) allows different modes for drawing the background image. Possible modes areː <br />
<br />
** border - the background image is stretched (1)<br />
** center - the background image is in the center (2), <br />
** tile - the background image is 'tiled' (3)<br />
** style - choose your own background image stylesheet, see example below (4)<br />
<br />
: See also: [[#resetBackgroundImage | resetBackgroundImage()]]<br />
<br />
;Example (label)<br />
<syntaxhighlight lang="lua"><br />
-- give the top border a nice look<br />
setBackgroundImage("top bar", [[/home/vadi/Games/Mudlet/games/top_bar.png]])<br />
</syntaxhighlight><br />
<br />
;Example (main/miniconsole)<br />
<syntaxhighlight lang="lua"><br />
-- give the main window a background image<br />
setBackgroundImage("main", [[:/Mudlet_splashscreen_development.png]], "center")<br />
<br />
-- or use your own for the main window:<br />
setBackgroundImage("main", [[C:\Documents and Settings\bub\Desktop\mypicture.png]], "center")<br />
<br />
-- give my_miniconsole a nice background image and put it in the center<br />
setBackgroundImage("my_miniconsole", [[:/Mudlet_splashscreen_development.png]], "center")<br />
<br />
-- give my_miniconsole a nice background image with own stylesheet option<br />
setBackgroundImage("my_miniconsole", [[background-image: url(:/Mudlet_splashscreen_development.png); background-repeat: no-repeat; background-position: right;]], "style")<br />
</syntaxhighlight><br />
{{note}} setBackgroundImage for main/miniconsoles and userwindows available in Mudlet 4.10+<br />
<br />
==setBgColor==<br />
;setBgColor([windowName], r, g, b, [transparency])<br />
:Sets the current text background color in the main window unless windowName parameter given. If you have selected text prior to this call, the selection will be highlighted otherwise the current text background color will be changed. If you set a foreground or background color, the color will be used until you call resetFormat() on all further print commands.<br />
<br />
:If you'd like to change the background color of a window, see [[#setBackgroundColor|setBackgroundColor()]].<br />
<br />
: ''See also:'' [[#cecho|cecho()]], [[#setBackgroundColor|setBackgroundColor()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) either be none or "main" for the main console, or a miniconsole / userwindow name.<br />
* ''r:''<br />
: The red component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''g:''<br />
: The green component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''b:''<br />
: The blue component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''transparency:''<br />
: Amount of transparency to use, from 0 (fully transparent) to 255 (fully opaque). Optional, if not used color is fully opaque<br />
<br />
<br />
<br />
{{note}}<br />
Transparency parameter available in Mudlet 4.10+<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
--highlights the first occurrence of the string "Tom" in the current line with a red background color.<br />
selectString( "Tom", 1 )<br />
setBgColor( 255,0,0 )<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
--prints "Hello" on red background and "You" on blue.<br />
setBgColor(255,0,0)<br />
echo("Hello")<br />
setBgColor(0,0,255)<br />
echo(" You!")<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
==setBold==<br />
;setBold(windowName, boolean)<br />
: Sets the current text font to bold (true) or non-bold (false) mode. If the windowName parameters omitted, the main screen will be used. If you've got text currently selected in the Mudlet buffer, then the selection will be bolded. Any text you add after with [[Manual:Lua_Functions#echo|echo()]] or [[Manual:Lua_Functions#insertText|insertText()]] will be bolded until you use [[Manual:Lua_Functions#resetFormat|resetFormat()]].<br />
<br />
* ''windowName:''<br />
: Optional parameter set the current text background color in windowname given.<br />
<br />
* ''boolean:''<br />
: A <code>true</code> or <code>false</code> that enables or disables bolding of text<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- enable bold formatting<br />
setBold(true)<br />
-- the following echo will be bolded<br />
echo("hi")<br />
-- turns off bolding, italics, underlines and colouring. It's good practice to clean up after you're done with the formatting, so other your formatting doesn't "bleed" into other echoes.<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
==setBorderBottom==<br />
;setBorderBottom(size)<br />
: Sets the size of the bottom border of the main window in pixels. A border means that the game text won't go on it, so this gives you room to place your graphical elements there.<br />
: See Also: [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#setBorderColor|setBorderColor()]], [[Manual:Lua_Functions#getBorderBottom|getBorderBottom()]]<br />
<br />
;Parameters<br />
* ''size:''<br />
: Height of the border in pixels - with 0 indicating no border.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderBottom(150)<br />
</syntaxhighlight><br />
<br />
==setBorderColor==<br />
;setBorderColor(red, green, blue)<br />
: Sets the color of the main windows border that you can create either with lua commands, or via the main window settings.<br />
: See Also: [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]]<br />
<br />
;Parameters<br />
* ''red:''<br />
: Amount of red color to use, from 0 to 255.<br />
* ''green:''<br />
: Amount of green color to use, from 0 to 255.<br />
* ''blue:''<br />
: Amount of blue color to use, from 0 to 255.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- set the border to be completely blue<br />
setBorderColor(0, 0, 255)<br />
<br />
-- or red, using a name<br />
setBorderColor( unpack(color_table.red) )<br />
</syntaxhighlight><br />
<br />
==setBorderLeft==<br />
;setBorderLeft(size)<br />
: Sets the size of the left border of the main window in pixels. A border means that the game text won't go on it, so this gives you room to place your graphical elements there.<br />
: See Also: [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#setBorderColor|setBorderColor()]], [[Manual:Lua_Functions#getBorderLeft|getBorderLeft()]]<br />
<br />
;Parameters<br />
* ''size:''<br />
: Width of the border in pixels - with 0 indicating no border.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderLeft(5)<br />
</syntaxhighlight><br />
<br />
==setBorderRight==<br />
;setBorderRight(size)<br />
: Sets the size of the right border of the main window in pixels. A border means that the game text won't go on it, so this gives you room to place your graphical elements there.<br />
: See Also: [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#setBorderColor|setBorderColor()]], [[Manual:Lua_Functions#getBorderRight|getBorderRight()]]<br />
<br />
;Parameters<br />
* ''size:''<br />
: Width of the border in pixels - with 0 indicating no border.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderRight(50)<br />
</syntaxhighlight><br />
<br />
==setBorderSizes==<br />
;setBorderSizes(top, right, bottom, left)<br />
: Sets the size of all borders of the main window in pixels. A border means that the game text won't go on it, so this gives you room to place your graphical elements there.<br />
: The exact result of this function depends on how many numbers you give to it as arguments.<br />
: See also: [[Manual:Lua_Functions#getBorderSizes|getBorderSizes()]], [[Manual:Lua_Functions#setBorderTop|setBorderTop()]], [[Manual:Lua_Functions#setBorderRight|setBorderRight()]], [[Manual:Lua_Functions#setBorderBottom|setBorderBottom()]], [[Manual:Lua_Functions#setBorderLeft|setBorderLeft()]], [[Manual:Lua_Functions#setBorderColor|setBorderColor()]]<br />
<br />
: {{MudletVersion|4.0}}<br />
<br />
;Arguments<br />
* '''setBorderSizes(top, right, bottom, left)'''<br />
: ''4 arguments:'' All borders will be set to their new given size.<br />
* '''setBorderSizes(top, width, bottom)''' <br />
: ''3 arguments:'' Top and bottom borders will be set to their new given size, and right and left will gain the same width. <br />
* '''setBorderSizes(height, width)'''<br />
: ''2 arguments:'' Top and bottom borders will gain the same height, and right and left borders gain the same width. <br />
* '''setBorderSizes(size)'''<br />
: ''1 argument:'' All borders will be set to the same size.<br />
* '''setBorderSizes()'''<br />
: ''0 arguments:'' All borders will be hidden or set to size of 0 = no border.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderSizes(100, 50, 150, 0) <br />
-- big border at the top, bigger at the bottom, small at the right, none at the left<br />
<br />
setBorderSizes(100, 50, 150) <br />
-- big border at the top, bigger at the bottom, small at the right and the left<br />
<br />
setBorderSizes(100, 50) <br />
-- big border at the top and the bottom, small at the right and the left<br />
<br />
setBorderSizes(100) <br />
-- big borders at all four sides<br />
<br />
setBorderSizes() <br />
-- no borders at all four sides<br />
</syntaxhighlight><br />
<br />
==setBorderTop==<br />
;setBorderTop(size)<br />
: Sets the size of the top border of the main window in pixels. A border means that the game text won't go on it, so this gives you room to place your graphical elements there.<br />
: See Also: [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#setBorderColor|setBorderColor()]], [[Manual:Lua_Functions#getBorderTop|getBorderTop()]]<br />
<br />
;Parameters<br />
* ''size:''<br />
: Height of the border in pixels - with 0 indicating no border.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderTop(100)<br />
</syntaxhighlight><br />
<br />
==setFgColor==<br />
;setFgColor([windowName], red, green, blue)<br />
:Sets the current text foreground color in the main window unless windowName parameter given.<br />
<br />
* ''windowName:''<br />
: (optional) either be none or "main" for the main console, or a miniconsole / userwindow name.<br />
* ''red:''<br />
: The red component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''green:''<br />
: The green component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''blue:''<br />
: The blue component of the gauge color. Passed as an integer number from 0 to 255<br />
<br />
: See also: [[#setBgColor | setBgColor()]], [[#setHexFgColor | setHexFgColor()]], [[#setHexBgColor | setHexBgColor()]], [[#resetFormat | resetFormat()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--highlights the first occurrence of the string "Tom" in the current line with a red foreground color.<br />
selectString( "Tom", 1 )<br />
setFgColor( 255, 0, 0 )<br />
</syntaxhighlight><br />
<br />
==setButtonStyleSheet==<br />
;setButtonStyleSheet(button, markup)<br />
: Applies Qt style formatting to a button via a special markup language.<br />
<br />
; Parameters<br />
* ''button:''<br />
: The name of the button to be formatted.<br />
* ''markup:''<br />
: The string instructions, as specified by the Qt Style Sheet reference.<br />
: Note: You can instead use QWidget { markup }. QWidget will reference 'button', allowing the use of pseudostates like QWidget:hover and QWidget:selected<br />
<br />
;References<br />
: http://qt-project.org/doc/qt-5/stylesheet-reference.html<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setButtonStyleSheet("my test button", [[<br />
QWidget {<br />
background-color: #999999;<br />
border: 3px #777777;<br />
}<br />
QWidget:hover {<br />
background-color: #bbbbbb;<br />
}<br />
QWidget:checked {<br />
background-color: #77bb77;<br />
border: 3px #559955;<br />
}<br />
QWidget:hover:checked {<br />
background-color: #99dd99;<br />
} ]])</syntaxhighlight><br />
<br />
==setClipboardText==<br />
;setClipboardText(textContent)<br />
: Sets the value of the computer's clipboard to the string data provided.<br />
: See also: [[#getClipboardText | getClipboardText()]]<br />
<br />
; Parameters<br />
* ''textContent:''<br />
: The text to be put into the clipboard.<br />
<br />
: {{note}} Note: Available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setClipboardText("New Clipboard Contents")<br />
echo("Clipboard: " .. getClipboardText()) -- should echo "Clipboard: New Clipboard Contents"<br />
</syntaxhighlight><br />
<br />
==setCmdLineAction==<br />
;setCmdLineAction(commandLineName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called if the user sends text to the command line. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the command line action. Additionally, this function passes the command line input text as the final argument.<br />
{{note}} If no action is set the command line behaves like the main command line and sends commands directly to the game or alias engine.<br />
<br />
The function specified in ''luaFunctionName'' is called like so:<br />
<br />
<syntaxhighlight lang="lua"><br />
luaFuncName(optional number of arguments, text)<br />
</syntaxhighlight><br />
<br />
: See also: [[Manual:UI_Functions#resetCmdLineAction|resetCmdLineAction()]]<br />
<br />
;Parameters<br />
<br />
* ''commandLineName:''<br />
: The name of the command line to attach the action function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string.<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
{{note}} You can also pass a function directly instead of using a string<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
function sendTextToMiniConsole(miniConsoleName, cmdLineText)<br />
echo(miniConsoleName, cmdLineText.."\n")<br />
end<br />
<br />
setCmdLineAction("myCmdLine", "sendTextToMiniConsole", "myMiniConsole")<br />
<br />
</syntaxhighlight><br />
<br />
==setCmdLineStyleSheet==<br />
;setCmdLineStyleSheet([commandLineName], markup)<br />
: Applies Qt style formatting to a command line via a special markup language.<br />
<br />
;Parameters<br />
* ''commandLineName:''<br />
: (optional) Name of the command line (or miniconsole the command line is in). If not given the stylesheet will be applied to the main command line.<br />
* ''markup''<br />
: The string instructions, as specified by the Qt Style Sheet reference.<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
: See also: [[Manual:UI_Functions#enableCommandLine|enableCommandLine()]], [[Manual:UI_Functions#createCommandLine|createCommandLine()]]<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- move the main command line over to the right<br />
setCmdLineStyleSheet("main", [[<br />
QPlainTextEdit {<br />
padding-left: 100px; /* change 100 to your number */<br />
background-color: black; /* change it to your background color */<br />
}<br />
]])<br />
<br />
--only change font-size of your main command line<br />
setCmdLineStyleSheet("main", [[<br />
QPlainTextEdit {<br />
font-sizeː20pt; <br />
}<br />
]])<br />
<br />
--change bg/fg color of your miniconsole command line (name of the miniconsole is 'myMiniconsole'<br />
--the command line in the miniconsole has to be enabled<br />
setCmdLineStyleSheet("myMiniConsole", [[<br />
QPlainTextEdit {<br />
background: rgb(0,100,0);<br />
color: rgb(0,200,255);<br />
font-size: 10pt;<br />
}<br />
]])<br />
</syntaxhighlight><br />
<br />
==setFont==<br />
;setFont(name, font)<br />
: Sets the font on the given window or console name. Can be used to change font of the main console, miniconsoles, and userwindows. Prefer a monospaced font - those work best with text games. See here [https://doc.qt.io/qt-5/qfont.html#setFamily for more].<br />
: See also: [[#getFont|getFont()]], [[#setFontSize|setFontSize()]], [[#getFontSize|getFontSize()]], [[#openUserWindow|openUserWindow()]], [[#getAvailableFonts|getAvailableFonts()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: Optional - the window name to set font size of - can either be none or "main" for the main console, or a miniconsole / userwindow name.<br />
* ''font:''<br />
: The font to use.<br />
<br />
{{MudletVersion|3.9}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The following will set the "main" console window font to Ubuntu Mono, another font included in Mudlet.<br />
setFont("Ubuntu Mono")<br />
setFont("main", "Ubuntu Mono")<br />
<br />
-- This will set the font size of a miniconsole named "combat" to Ubuntu Mono.<br />
setFont("combat", "Ubuntu Mono")<br />
</syntaxhighlight><br />
<br />
==setFontSize==<br />
;setFontSize(name, size)<br />
: Sets a font size on the given window or console name. Can be used to change font size of the Main console as well as dockable UserWindows.<br />
: See Also: [[#getFontSize|getFontSize()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: Optional - the window name to set font size of - can either be none or "main" for the main console, or a UserWindow name.<br />
* ''size:''<br />
: The font size to apply to the window.<br />
<br />
{{MudletVersion|3.4}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The following will set the "main" console window font to 12-point font.<br />
setFontSize(12)<br />
setFontSize("main", 12)<br />
<br />
-- This will set the font size of a user window named "uw1" to 12-point font.<br />
setFontSize("uw1", 12)<br />
</syntaxhighlight><br />
<br />
==setGauge==<br />
;setGauge(gaugeName, currentValue, maxValue, gaugeText)<br />
: Use this function when you want to change the gauges look according to your values. Typical usage would be in a prompt with your current health or whatever value, and throw in some variables instead of the numbers.<br />
<br />
: See also: [[Manual:Lua_Functions#moveGauge|moveGauge()]], [[Manual:Lua_Functions#createGauge|createGauge()]], [[Manual:Lua_Functions#setGaugeText|setGaugeText()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create a gauge<br />
createGauge("healthBar", 300, 20, 30, 300, nil, "green")<br />
<br />
--Change the looks of the gauge named healthBar and make it<br />
--fill to half of its capacity. The height is always remembered.<br />
setGauge("healthBar", 200, 400)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
--If you wish to change the text on your gauge, you’d do the following:<br />
setGauge("healthBar", 200, 400, "some text")<br />
</syntaxhighlight><br />
<br />
==setGaugeStyleSheet==<br />
;setGaugeStyleSheet(gaugeName, css, cssback, csstext)<br />
: Sets the CSS stylesheets on a gauge - one on the front (the part that resizes accoding to the values on the gauge) and one in the back. You can use [https://build-system.fman.io/qt-designer-download Qt Designer] to create stylesheets.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setGaugeStyleSheet("hp_bar", [[background-color: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #f04141, stop: 0.1 #ef2929, stop: 0.49 #cc0000, stop: 0.5 #a40000, stop: 1 #cc0000);<br />
border-top: 1px black solid;<br />
border-left: 1px black solid;<br />
border-bottom: 1px black solid;<br />
border-radius: 7;<br />
padding: 3px;]],<br />
[[background-color: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #bd3333, stop: 0.1 #bd2020, stop: 0.49 #990000, stop: 0.5 #700000, stop: 1 #990000);<br />
border-width: 1px;<br />
border-color: black;<br />
border-style: solid;<br />
border-radius: 7;<br />
padding: 3px;]])<br />
</syntaxhighlight><br />
<br />
==setGaugeText==<br />
;setGaugeText(gaugename, css, ccstext )<br />
: Set the formatting of the text used inside the inserted gaugename.<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
setGaugeText("healthBar", [[<p style="font-weight:bold;color:#C9C9C9;letter-spacing:1pt;word-spacing:2pt;font-size:12px;text-align:center;font-family:arial black, sans-serif;">]]..MY_NUMERIC_VARIABLE_HERE..[[</p>]])</syntaxhighlight><br />
<br />
;Useful resources:<br />
:http://csstxt.com - Generate the text exactly how you like it before pasting it into the css slot.<br />
:https://www.w3schools.com/colors/colors_picker.asp - Can help you choose colors for your text!<br />
<br />
==setHexBgColor==<br />
;setHexBgColor([windowName], hexColorString)<br />
:Sets the current text background color in the main window unless windowName parameter given. This function allows to specify the color as a 6 character hexadecimal string.<br />
<br />
* ''windowName:''<br />
: Optional parameter set the current text background color in windowname given.<br />
* ''hexColorString''<br />
: 6 character long hexadecimal string to set the color to. The first two characters 00-FF represent the red part of the color, the next two the green and the last two characters stand for the blue part of the color<br />
<br />
: See also: [[#setBgColor | setBgColor()]], [[#setHexFgColor | setHexFgColor()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--highlights the first occurrence of the string "Tom" in the current line with a red Background color.<br />
selectString( "Tom", 1 )<br />
setHexBgColor( "FF0000" )<br />
</syntaxhighlight><br />
<br />
==setHexFgColor==<br />
;setHexFgColor([windowName], hexColorString)<br />
:Sets the current text foreground color in the main window unless windowName parameter given. This function allows to specify the color as a 6 character hexadecimal string.<br />
<br />
* ''windowName:''<br />
: Optional parameter set the current text foreground color in windowname given.<br />
* ''hexColorString''<br />
: 6 character long hexadecimal string to set the color to. The first two characters 00-FF represent the red part of the color, the next two the green and the last two characters stand for the blue part of the color<br />
<br />
: See also: [[#setFgColor | setFgColor()]], [[#setHexBgColor | setHexBgColor()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--highlights the first occurrence of the string "Tom" in the current line with a red foreground color.<br />
selectString( "Tom", 1 )<br />
setHexFgColor( "FF0000" )<br />
</syntaxhighlight><br />
<br />
==setItalics==<br />
;setItalics(windowName, bool)<br />
: Sets the current text font to italics/non-italics mode. If the windowName parameters omitted, the main screen will be used.<br />
<br />
==setLabelToolTip==<br />
;setLabelToolTip(labelName, text, [duration])<br />
: Sets a tooltip on the given label.<br />
{{MudletVersion|4.6.1}}<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to set the tooltip to.<br />
* ''text:''<br />
: The text to be shown. Can contain Qt rich text formats.<br />
* ''duration:''<br />
: Duration of the tooltip timeout in seconds. Optional, if not set the default duration will be set.<br />
<br />
: See also: [[Manual:UI_Functions#resetLabelToolTip|resetLabelToolTip()]]<br />
<br />
==setLabelClickCallback==<br />
;setLabelClickCallback(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called if the user clicks on the label/image. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button. Additionally, this function passes an event table as the final argument. This table contains information about the mouse button clicked, other buttons that were pressed at the time, and the mouse cursor's local (relative to the label) and global (relative to the Mudlet window) position. The function specified in ''luaFunctionName'' is called like so:<br />
<br />
<syntaxhighlight lang="lua"><br />
luaFuncName(optional number of arguments, event)<br />
</syntaxhighlight><br />
<br />
where '''event''' has the following structure:<br />
<br />
<syntaxhighlight lang="lua"><br />
event = {<br />
x = 100,<br />
y = 200,<br />
globalX = 300,<br />
globalY = 320,<br />
button = "LeftButton",<br />
buttons = {"RightButton", "MidButton"},<br />
}<br />
</syntaxhighlight><br />
<br />
: See also: [[Manual:UI_Functions#setLabelDoubleClickCallback|setLabelDoubleClickCallback()]], [[Manual:UI_Functions#setLabelReleaseCallback|setLabelReleaseCallback()]], [[Manual:UI_Functions#setLabelMoveCallback|setLabelMoveCallback()]], [[Manual:UI_Functions#setLabelWheelCallback|setLabelWheelCallback()]],[[Manual:UI_Functions#setLabelOnEnter|setLabelOnEnter()]], [[Manual:UI_Functions#setLabelOnLeave|setLabelOnLeave()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: Lua function to call, or the function name, as a string.<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
{{note}} Event argument is available in 3.6+, and in 4.8+ you can pass a function directly instead of a string.<br />
<br />
{{note}}<br />
While '''event.button''' may contain a single string of any listed below, '''event.buttons''' will only ever contain some combination of "LeftButton", "MidButton", and "RightButton"<br />
:The following mouse button strings are defined:<br />
<pre><br />
"LeftButton" "RightButton" "MidButton"<br />
"BackButton" "ForwardButton" "TaskButton"<br />
"ExtraButton4" "ExtraButton5" "ExtraButton6"<br />
"ExtraButton7" "ExtraButton8" "ExtraButton9"<br />
"ExtraButton10" "ExtraButton11" "ExtraButton12"<br />
"ExtraButton13" "ExtraButton14" "ExtraButton15"<br />
"ExtraButton16" "ExtraButton17" "ExtraButton18"<br />
"ExtraButton19" "ExtraButton20" "ExtraButton21"<br />
"ExtraButton22" "ExtraButton23" "ExtraButton24"<br />
</pre><br />
;Example<br />
<syntaxhighlight lang="lua"><br />
createLabel("testLabel", 50, 50, 100, 100, 0)<br />
<br />
function onClickGoNorth(event)<br />
if event.button == "LeftButton" then<br />
send("walk north")<br />
elseif event.button == "RightButton" then<br />
send("swim north")<br />
elseif event.button == "MidButton" then<br />
send("gallop north")<br />
end<br />
end<br />
<br />
setLabelClickCallback("testLabel", "onClickGoNorth")<br />
<br />
-- you can also use them within tables:<br />
mynamespace =<br />
{<br />
onClickGoNorth =<br />
function()<br />
echo("the north button was clicked!")<br />
end,<br />
}<br />
setLabelClickCallback("testLabel", "mynamespace.onClickGoNorth")<br />
<br />
-- or by passing the function directly:<br />
setLabelClickCallback("testLabel", onClickGoNorth)<br />
</syntaxhighlight><br />
<br />
==setLabelDoubleClickCallback==<br />
;setLabelDoubleClickCallback(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called if the user double clicks on the label/image. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button. Additionally, this function passes an event table as the final argument, as in [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]]<br />
<br />
{{MudletVersion|3.6}}<br />
<br />
: See also: [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:UI_Functions#setLabelReleaseCallback|setLabelReleaseCallback()]], [[Manual:UI_Functions#setLabelMoveCallback|setLabelMoveCallback()]], [[Manual:UI_Functions#setLabelWheelCallback|setLabelWheelCallback()]], [[Manual:UI_Functions#setLabelOnEnter|setLabelOnEnter()]], [[Manual:UI_Functions#setLabelOnLeave|setLabelOnLeave()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string.<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
==setLabelMoveCallback==<br />
;setLabelMoveCallback(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called when the mouse moves while inside the specified label/console. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button. Additionally, this function passes an event table as the final argument, as in [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]]<br />
<br />
: See Also: [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:UI_Functions#setLabelDoubleClickCallback|setLabelDoubleClickCallback()]], [[Manual:UI_Functions#setLabelReleaseCallback|setLabelReleaseCallback()]], [[Manual:UI_Functions#setLabelWheelCallback|setLabelWheelCallback()]], [[Manual:UI_Functions#setLabelOnEnter|setLabelOnEnter()]], [[Manual:UI_Functions#setLabelOnLeave|setLabelOnLeave()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string.<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
{{MudletVersion|3.6}}<br />
<br />
==setLabelOnEnter==<br />
;setLabelOnEnter(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called when the mouse enters within the labels borders. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button. Additionally, this function passes an event table as the final argument, similar to [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], but with slightly different information.<br />
: For this callback, the '''event''' argument has the following structure:<br />
<br />
<syntaxhighlight lang="lua"><br />
event = {<br />
x = 100,<br />
y = 200,<br />
globalX = 300,<br />
globalY = 320,<br />
}<br />
</syntaxhighlight><br />
<br />
: See Also: [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:UI_Functions#setLabelDoubleClickCallback|setLabelDoubleClickCallback()]], [[Manual:UI_Functions#setLabelReleaseCallback|setLabelReleaseCallback()]], [[Manual:UI_Functions#setLabelMoveCallback|setLabelMoveCallback()]], [[Manual:UI_Functions#setLabelWheelCallback|setLabelWheelCallback()]], [[Manual:UI_Functions#setLabelOnLeave|setLabelOnLeave()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string - it must be registered as a global function, and not inside any namespaces (tables).<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
function onMouseOver()<br />
echo("The mouse is hovering over the label!\n")<br />
end<br />
<br />
setLabelOnEnter( "compassNorthImage", "onMouseOver" )<br />
</syntaxhighlight><br />
<br />
==setLabelOnLeave==<br />
;setLabelOnLeave(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called when the mouse leaves the labels borders. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button.<br />
<br />
: See Also: [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:UI_Functions#setLabelOnEnter|setLabelOnEnter()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string - it must be registered as a global function, and not inside any namespaces (tables).<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
function onMouseLeft(argument)<br />
echo("The mouse quit hovering over the label the label! We also got this as data on the function: "..argument)<br />
end<br />
<br />
setLabelOnLeave( "compassNorthImage", "onMouseLeft", "argument to pass to function" )<br />
</syntaxhighlight><br />
<br />
==setLabelReleaseCallback==<br />
;setLabelReleaseCallback(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called when a mouse click ends that originated on the specified label/console. This function is called even if you drag the mouse off of the label/console before releasing the click. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button. Additionally, this function passes an event table as the final argument, as in [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]]<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
: See Also: [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:UI_Functions#setLabelDoubleClickCallback|setLabelDoubleClickCallback()]], [[Manual:UI_Functions#setLabelMoveCallback|setLabelMoveCallback()]], [[Manual:UI_Functions#setLabelWheelCallback|setLabelWheelCallback()]], [[Manual:UI_Functions#setLabelOnEnter|setLabelOnEnter()]], [[Manual:UI_Functions#setLabelOnLeave|setLabelOnLeave()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string.<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
{{note}}<br />
The ''event'' argument only available since Mudlet 3.6<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
function onReleaseNorth()<br />
echo("the north button was released!")<br />
end<br />
<br />
setLabelReleaseCallback( "compassNorthImage", "onReleaseNorth" )<br />
<br />
-- you can also use them within tables:<br />
mynamespace = {<br />
onReleaseNorth = function()<br />
echo("the north button was released!")<br />
end<br />
}<br />
<br />
setLabelReleaseCallback( "compassNorthImage", "mynamespace.onReleaseNorth" )<br />
</syntaxhighlight><br />
<br />
==setLabelStyleSheet==<br />
;setLabelStyleSheet(label, markup)<br />
: Applies Qt style formatting to a label via a special markup language.<br />
<br />
; Parameters<br />
* ''label:''<br />
: The name of the label to be formatted (passed when calling createLabel).<br />
* ''markup:''<br />
: The string instructions, as specified by the Qt Style Sheet reference.<br />
: Note that when specifying a file path for styling purposes, forward slashes, / , must be used, even if your OS uses backslashes, \ , normally.<br />
<br />
;References<br />
: http://qt-project.org/doc/qt-5/stylesheet-reference.html<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This creates a label with a white background and a green border, with the text "test"<br />
-- inside.<br />
createLabel("test", 50, 50, 100, 100, 0)<br />
setLabelStyleSheet("test", [[<br />
background-color: white;<br />
border: 10px solid green;<br />
font-size: 12px;<br />
]])<br />
echo("test", "test")<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
-- This creates a label with a single image, that will tile or clip depending on the<br />
-- size of the label. To use this example, please supply your own image.<br />
createLabel("test5", 50, 353, 164, 55, 0)<br />
setLabelStyleSheet("test5", [[<br />
background-image: url("C:/Users/Administrator/.config/mudlet/profiles/Midkemia Online/Vyzor/MkO_logo.png");<br />
]])<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
-- This creates a label with a single image, that can be resized (such as during a<br />
-- sysWindowResizeEvent). To use this example, please supply your own image.<br />
createLabel("test9", 215, 353, 100, 100, 0)<br />
setLabelStyleSheet("test9", [[<br />
border-image: url("C:/Users/Administrator/.config/mudlet/profiles/Midkemia Online/Vyzor/MkO_logo.png");<br />
]])<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
--This creates a label whose background changes when the users mouse hovers over it.<br />
<br />
--putting the styleSheet in a variable allows us to easily change the styleSheet. We also are placing colors in variables that have been preset. <br />
local labelBackgroundColor = "#123456"<br />
local labelHoverColor = "#654321"<br />
local labelFontSize = 12<br />
local labelName = "HoverLabel"<br />
local ourLabelStyle = [[<br />
QLabel{<br />
background-color: ]]..labelBackgroundColor..[[;<br />
font-size: ]]..labelFontSize..[[px;<br />
qproperty-alignment: 'AlignCenter | AlignCenter';<br />
}<br />
QLabel::hover{<br />
background-color: ]]..labelHoverColor..[[;<br />
font-size: ]]..labelFontSize..[[px;<br />
qproperty-alignment: 'AlignCenter | AlignCenter';<br />
}<br />
]]<br />
<br />
--Creating the label using the labelName and ourLabelStyle variables created above.<br />
createLabel(labelName,0,0,400,400,1)<br />
setLabelStyleSheet(labelName, ourLabelStyle)<br />
echo("HoverLabel","This text shows while mouse is or is not over the label.")<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
--Using QLabel::hover mentioned above. Lets "trick" the label into changing it's text.<br />
--Please keep in mind that the setLabelMoveCallback allows for much more control over not just your label but your entire project.<br />
<br />
--putting the styleSheet in a variable allows us to easily change the styleSheet. We also are placing colors in variables that have been preset. <br />
local labelBackgroundColor = "#123456"<br />
local labelHoverColor = "#654321"<br />
local labelFontSize = 12<br />
local labelName = "HoverLabel"<br />
--Notice we are adding a string returned from a function. In this case, the users profile directory.<br />
local ourLabelStyle = [[<br />
QLabel{<br />
border-image: url("]]..getMudletHomeDir()..[[/imagewithtext.png");<br />
}<br />
QLabel::hover{<br />
border-image: url("]]..getMudletHomeDir()..[[/imagewithhovertext.png");<br />
}<br />
]]<br />
<br />
--Creating the label using the labelName and ourLabelStyle variables created above.<br />
createLabel(labelName,0,0,400,400,1)<br />
setLabelStyleSheet(labelName, ourLabelStyle)<br />
--This is just to example that echos draw on top of the label. You would not want to echo onto a label you were drawing text on with images, because echos would draw on top of them.<br />
echo("HoverLabel","This text shows while mouse is or is not over the label.")<br />
</syntaxhighlight><br />
<br />
==setLabelCursor==<br />
;setLabelCursor(labelName, cursorShape)<br />
: Changes how the mouse cursor looks like when over the label. To reset the cursor shape, use [[#resetLabelCursor|resetLabelCursor()]].<br />
<br />
: See also: [[#resetLabelCursor|resetLabelCursor()]], [[#setLabelCustomCursor|setLabelCustomCursor()]]<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: Name of the label which you want the mouse cursor change at.<br />
* ''cursorShape''<br />
: Shape of the mouse cursor. List of possible cursor shapes is [[CursorShapes| available here]].<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setLabelCursor("myLabel", "Cross")<br />
-- This will change the mouse cursor to a cross if it's over the label myLabel<br />
</syntaxhighlight><br />
<br />
==setLabelCustomCursor==<br />
;setLabelCustomCursor(labelName, custom cursor, [hotX, hotY])<br />
: Changes the mouse cursor shape over your label to a custom cursor. To reset the cursor shape, use [[#resetLabelCursor|resetLabelCursor()]].<br />
<br />
: See also: [[#resetLabelCursor|resetLabelCursor()]], [[#setLabelCursor|setLabelCursor()]]<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: Name of the label which you want the mouse cursor change at.<br />
* ''custom cursor''<br />
: Location of your custom cursor file. To be compatible with all systems it is recommended to use png files with size of 32x32.<br />
* ''hotX''<br />
: X-coordinate of the cursors hotspot position. Optional, if not set it is set to -1 which is in the middle of your custom cursor.<br />
* ''hotY''<br />
: Y-coordinate of the cursors hotspot position. Optional, if not set it is set to -1 which is in the middle of your custom cursor.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setLabelCustomCursor("myLabel", getMudletHomeDir().."/custom_cursor.png")<br />
-- This will change the mouse cursor to your custom cursor if it's over the label myLabel<br />
</syntaxhighlight><br />
<br />
==setLabelWheelCallback==<br />
;setLabelWheelCallback(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called when the mouse wheel is scrolled while inside the specified label/console. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button. Additionally, this function passes an event table as the final argument, similar to [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], but with slightly different information.<br />
: For this callback, the ''event'' argument has the following structure:<br />
<br />
<syntaxhighlight lang="lua"><br />
event = {<br />
x = 100,<br />
y = 200,<br />
globalX = 300,<br />
globalY = 320,<br />
buttons = {"RightButton", "MidButton"},<br />
angleDeltaX = 0,<br />
angleDeltaY = 120<br />
}<br />
</syntaxhighlight><br />
<br />
: Keys ''angleDeltaX'' and ''angleDeltaY'' correspond with the horizontal and vertical scroll distance, respectively. For most mice, these values will be multiples of 120.<br />
<br />
: See Also: [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:UI_Functions#setLabelDoubleClickCallback|setLabelDoubleClickCallback()]], [[Manual:UI_Functions#setLabelReleaseCallback|setLabelReleaseCallback()]], [[Manual:UI_Functions#setLabelMoveCallback|setLabelMoveCallback()]], [[Manual:UI_Functions#setLabelOnEnter|setLabelOnEnter()]], [[Manual:UI_Functions#setLabelOnLeave|setLabelOnLeave()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string.<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
{{MudletVersion|3.6}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
function onWheelNorth(event)<br />
if event.angleDeltaY > 0 then<br />
echo("the north button was wheeled forwards over!")<br />
else<br />
echo("the north button was wheeled backwards over!")<br />
end<br />
end<br />
<br />
setLabelWheelCallback( "compassNorthImage", "onWheelNorth" )<br />
<br />
-- you can also use them within tables:<br />
mynamespace = {<br />
onWheelNorth = function()<br />
echo("the north button was wheeled over!")<br />
end<br />
}<br />
<br />
setWheelReleaseCallback( "compassNorthImage", "mynamespace.onWheelNorth" )<br />
</syntaxhighlight><br />
<br />
==setLink==<br />
;setLink([windowName], command, tooltip)<br />
: Turns the [[Manual:Lua_Functions#selectString|selected]] text into a clickable link - upon being clicked, the link will do the command code. Tooltip is a string which will be displayed when the mouse is over the selected text.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of a miniconsole or a userwindow in which to select the text in.<br />
* ''command:''<br />
: command to do when the text is clicked, as text or Lua function.<br />
* ''tooltip:''<br />
: tooltip to show when the mouse is over the text - explaining what would clicking do.<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
-- you can clickify a lot of things to save yourself some time - for example, you can change<br />
-- the line where you receive a message to be clickable to read it!<br />
-- perl regex trigger:<br />
-- ^You just received message #(\w+) from \w+\.$<br />
-- script:<br />
selectString(matches[2], 1)<br />
setUnderline(true) setLink([[send("msg read ]]..matches[2]..[[")]], "Read #"..matches[2])<br />
resetFormat()<br />
<br />
-- example of selecting text in a miniconsole and turning it into a link:<br />
HelloWorld = Geyser.MiniConsole:new({<br />
name="HelloWorld",<br />
x="70%", y="50%",<br />
width="30%", height="50%",<br />
})<br />
HelloWorld:echo("hi")<br />
selectString("HelloWorld", "hi", 1)<br />
setLink("HelloWorld", "echo'you clicked hi!'", "click me!")<br />
</syntaxhighlight><br />
<br />
==setMainWindowSize==<br />
;setMainWindowSize(mainWidth, mainHeight)<br />
: Changes the size of your main Mudlet window to the values given.<br />
: See Also: [[Manual:Lua_Functions#getMainWindowSize|getMainWindowSize()]]<br />
<br />
; Parameters<br />
* ''mainWidth:''<br />
: The new width in pixels.<br />
* ''mainHeight:''<br />
: The new height in pixels.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--this will resize your main Mudlet window<br />
setMainWindowSize(1024, 768)<br />
</syntaxhighlight><br />
<br />
==setMapWindowTitle==<br />
;setMapWindowTitle(text)<br />
: Changes the title shown in the mapper window when it's popped out.<br />
: See also: [[#resetMapWindowTitle|resetMapWindowTitle()]]<br />
<br />
; Parameters<br />
* ''text:''<br />
: New window title to set.<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setMapWindowTitle("my cool game map")<br />
</syntaxhighlight><br />
<br />
==setMiniConsoleFontSize==<br />
;setMiniConsoleFontSize(name, fontSize)<br />
: Sets the font size of the mini console. see also: [[#setFontSize | setFontSize()]], [[#createMiniConsole | createMiniConsole()]], [[#createLabel | createLabel()]]<br />
<br />
==setMovie==<br />
;setMovie(label name, path to gif)<br />
<br />
: Adds a gif to the selected label and animates it. Note that gifs are pretty expensive to play, so don't add too many at once.<br />
: Some websites you can get gifs from are [https://tenor.com/search/stickers-gifs Tenor] and [https://giphy.com/stickers Giphy] (not officially endorsed).<br />
<br />
: Returns true<br />
<br />
: See also: [[Manual:Lua_Functions#startMovie|startMovie()]], [[Manual:Lua_Functions#pauseMovie|pauseMovie()]], [[Manual:Lua_Functions#setMovieFrame|setMovieFrame()]], [[Manual:Lua_Functions#setMovieSpeed|setMovieSpeed()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''label name:'' <br />
: name of the label the gif will be animated on<br />
* ''path:''<br />
: path of the gif file<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- download & show a gif within mudlet<br />
local saveto = getMudletHomeDir().."/kymip.gif"<br />
-- animation credit to https://opengameart.org/content/kymiball-ii-third-prototype-scraps<br />
local url = "https://opengameart.org/sites/default/files/kymip_0.gif"<br />
<br />
if downloadHandler then killAnonymousEventHandler(downloadHandler) end<br />
downloadHandler = registerAnonymousEventHandler("sysDownloadDone",<br />
function(_, filename)<br />
if filename ~= saveto then<br />
return true<br />
end<br />
<br />
local width, height = getImageSize(saveto)<br />
<br />
createLabel("kymip", 300, 300, width, height, 0)<br />
setMovie("kymip", saveto)<br />
setLabelReleaseCallback("kymip", function() deleteLabel("kymip") end)<br />
end, true)<br />
<br />
downloadFile(saveto, url)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
local gifpath = getMudletHomeDir().."/movie.gif"<br />
<br />
local width, height = getImageSize(gifpath)<br />
<br />
-- create a label with the name mygif<br />
createLabel("mygif", 0, 0, width, height,0)<br />
-- put the gif on the label and animate it<br />
setMovie("mygif", gifpath)<br />
</syntaxhighlight><br />
<br />
==setMovieFrame==<br />
;setMovieFrame(label name, frame nr)<br />
<br />
: Jump to a specific frame in the gif.<br />
: Returns true if successful, and false if frame doesn't exist.<br />
<br />
: See also: [[Manual:Lua_Functions#setMovie|setMovie()]], [[Manual:Lua_Functions#startMovie|startMovie()]], [[Manual:Lua_Functions#pauseMovie|pauseMovie()]], [[Manual:Lua_Functions#setMovieSpeed|setMovieSpeed()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''label name:'' <br />
: name of the gif label<br />
* ''frame nr:''<br />
: the gif animations frame nr to jump to<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create a label with the name myMovie<br />
createLabel("myMovie",0,0,200,200,0)<br />
<br />
-- puts the gif on the label and animates it<br />
setMovie("myMovie", getMudletHomeDir().."/movie.gif")<br />
--stops the animation<br />
pauseMovie("myMovie")<br />
-- jumps to frame 12 of the animation<br />
setMovieFrame("myMovie", 12)<br />
--start the animation<br />
startMovie("myMovie")<br />
<br />
</syntaxhighlight><br />
<br />
==setMovieSpeed==<br />
;setMovieSpeed(label name, speed in percent)<br />
<br />
: Set the animation speed, in percent.<br />
: Returns true<br />
<br />
: See also: [[Manual:Lua_Functions#setMovie|setMovie()]], [[Manual:Lua_Functions#startMovie|startMovie()]], [[Manual:Lua_Functions#pauseMovie|pauseMovie()]], [[Manual:Lua_Functions#setMovieFrame|setMovieFrame()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''label name:'' <br />
: name of the gif label<br />
* ''speed in percent:''<br />
: the gif animations speed in percent for example 50 for 50% speed<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create a label with the name myMovie<br />
createLabel("myMovie",0,0,200,200,0)<br />
<br />
-- puts the gif on the label and animates it<br />
setMovie("myMovie", getMudletHomeDir().."/movie.gif")<br />
--accelerates the animation to a speed of 150%<br />
setMovieSpeed("myMovie",150)<br />
<br />
<br />
</syntaxhighlight><br />
<br />
==setOverline==<br />
;setOverline([windowName], boolean)<br />
: Sets the current text font to be overlined (true) or not overlined (false) mode. If the windowName parameters omitted, the main screen will be used. If you've got text currently selected in the Mudlet buffer, then the selection will be overlined. Any text you add after with [[Manual:Lua_Functions#echo|echo()]] or [[Manual:Lua_Functions#insertText|insertText()]] will be overlined until you use [[Manual:Lua_Functions#resetFormat|resetFormat()]].<br />
<br />
* ''windowName:''<br />
: (optional) name of the window to set the text to be overlined or not.<br />
<br />
* ''boolean:''<br />
: A ''true'' or ''false'' that enables or disables overlining of text<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
-- enable overlined text<br />
setOverline(true)<br />
-- the following echo will be have an overline<br />
echo("hi")<br />
-- turns off bolding, italics, underlines, colouring, and strikethrough (and, after this and reverse have been added, them as well). It's good practice to clean up after you're done with the formatting, so other your formatting doesn't "bleed" into other echoes.<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.17}}<br />
<br />
==setPopup==<br />
;setPopup([windowName], {lua code}, {hints})<br />
: Turns the [[Manual:Lua_Functions#selectString|selected()]] text into a left-clickable link, and a right-click menu for more options. The selected 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.<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: the name of the console to operate on. If not using this in a miniConsole, use "main" as the name.<br />
: This argument was ignored before Mudlet 4.11.<br />
* ''{lua code}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. ie, <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight>.<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- In a `Raising your hand in greeting, you say "Hello!"` exact match trigger,<br />
-- the following code will make left-clicking on `Hello` show you an echo, while right-clicking<br />
-- will show some commands you can do.<br />
<br />
selectString("Hello", 1)<br />
setPopup("main", {function() send("bye") end, function() echo("hi!") end}, {"send 'bye' to the MUD", "click to echo 'hi!'"})<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
setPopup("main", {[[send("bye")]], [[echo("hi!")]]}, {"send 'bye' to the MUD", "click to echo 'hi!'"})<br />
<br />
</syntaxhighlight><br />
<br />
==setProfileStyleSheet==<br />
;setProfileStyleSheet(stylesheet)<br />
: Sets a stylesheet for the current Mudlet profile - allowing you to customise content outside of the main window (the profile tabs, the scrollbar, and so on). This function is better than setAppStyleSheet() because it affects only the current profile and not every other one as well.<br />
<br />
: See also: [[#setAppStyleSheet|setAppStyleSheet()]]<br />
<br />
;Parameters<br />
<br />
* ''stylesheet:''<br />
: The entire stylesheet you'd like to use. See [http://qt-project.org/doc/qt-5/stylesheet-reference.html Qt Style Sheets Reference] for the list of widgets you can style and CSS properties you can apply on them.<br />
<br />
: See also [https://github.com/vadi2/QDarkStyleSheet/blob/master/qdarkstyle/style.qss QDarkStyleSheet], a rather extensive stylesheet that shows you all the different configuration options you could apply, available as an [http://forums.mudlet.org/viewtopic.php?f=6&t=17624 mpackage here].<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- credit to Akaya @ http://forums.mudlet.org/viewtopic.php?f=5&t=4610&start=10#p21770<br />
local background_color = "#26192f"<br />
local border_color = "#b8731b"<br />
<br />
setProfileStyleSheet([[<br />
QMainWindow {<br />
background: ]]..background_color..[[;<br />
}<br />
QToolBar {<br />
background: ]]..background_color..[[;<br />
}<br />
QToolButton {<br />
background: ]]..background_color..[[;<br />
border-style: solid;<br />
border-width: 2px;<br />
border-color: ]]..border_color..[[;<br />
border-radius: 5px;<br />
font-family: BigNoodleTitling;<br />
color: white;<br />
margin: 2px;<br />
font-size: 12pt;<br />
}<br />
QToolButton:hover { background-color: grey;}<br />
QToolButton:focus { background-color: grey;}<br />
<br />
QTreeView {<br />
background: ]]..background_color..[[;<br />
color: white;<br />
}<br />
<br />
QMenuBar{ background-color: ]]..background_color..[[;}<br />
<br />
QMenuBar::item{ background-color: ]]..background_color..[[;}<br />
<br />
QDockWidget::title {<br />
background: ]]..border_color..[[;<br />
}<br />
QStatusBar {<br />
background: ]]..border_color..[[;<br />
}<br />
QScrollBar:vertical {<br />
background: ]]..background_color..[[;<br />
width: 15px;<br />
margin: 22px 0 22px 0;<br />
}<br />
QScrollBar::handle:vertical {<br />
background-color: ]]..background_color..[[;<br />
min-height: 20px;<br />
border-width: 2px;<br />
border-style: solid;<br />
border-color: ]]..border_color..[[;<br />
border-radius: 7px;<br />
}<br />
QScrollBar::add-line:vertical {<br />
background-color: ]]..background_color..[[;<br />
border-width: 2px;<br />
border-style: solid;<br />
border-color: ]]..border_color..[[;<br />
border-bottom-left-radius: 7px;<br />
border-bottom-right-radius: 7px;<br />
height: 15px;<br />
subcontrol-position: bottom;<br />
subcontrol-origin: margin;<br />
}<br />
QScrollBar::sub-line:vertical {<br />
background-color: ]]..background_color..[[;<br />
border-width: 2px;<br />
border-style: solid;<br />
border-color: ]]..border_color..[[;<br />
border-top-left-radius: 7px;<br />
border-top-right-radius: 7px;<br />
height: 15px;<br />
subcontrol-position: top;<br />
subcontrol-origin: margin;<br />
}<br />
QScrollBar::up-arrow:vertical, QScrollBar::down-arrow:vertical {<br />
background: white;<br />
width: 4px;<br />
height: 3px;<br />
}<br />
QScrollBar::add-page:vertical, QScrollBar::sub-page:vertical {<br />
background: none;<br />
}<br />
]])<br />
<br />
-- if you'd like to reset it, use:<br />
setProfileStyleSheet("")<br />
<br />
-- to only affect scrollbars within the main window and miniconsoles, prefix them with 'TConsole':<br />
setProfileStyleSheet[[<br />
TConsole QScrollBar:vertical {<br />
border: 2px solid grey;<br />
background: #32CC99;<br />
width: 15px;<br />
margin: 22px 0 22px 0;<br />
}<br />
TConsole QScrollBar::handle:vertical {<br />
background: white;<br />
min-height: 20px;<br />
}<br />
TConsole QScrollBar::add-line:vertical {<br />
border: 2px solid grey;<br />
background: #32CC99;<br />
height: 20px;<br />
subcontrol-position: bottom;<br />
subcontrol-origin: margin;<br />
}<br />
TConsole QScrollBar::sub-line:vertical {<br />
border: 2px solid grey;<br />
background: #32CC99;<br />
height: 20px;<br />
subcontrol-position: top;<br />
subcontrol-origin: margin;<br />
}<br />
TConsole QScrollBar::up-arrow:vertical, QScrollBar::down-arrow:vertical {<br />
border: 2px solid grey;<br />
width: 3px;<br />
height: 3px;<br />
background: white;<br />
}<br />
TConsole QScrollBar::add-page:vertical, QScrollBar::sub-page:vertical {<br />
background: none;<br />
}<br />
]]<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.6}}<br />
<br />
==setReverse==<br />
;setReverse([windowName], boolean)<br />
: Sets the current text to swap foreground and background color settings (true) or not (false) mode. If the windowName parameters omitted, the main screen will be used. If you've got text currently selected in the Mudlet buffer, then the selection will have it's colors swapped. Any text you add after with [[Manual:Lua_Functions#echo|echo()]] or [[Manual:Lua_Functions#insertText|insertText()]] will have their foreground and background colors swapped until you use [[Manual:Lua_Functions#resetFormat|resetFormat()]].<br />
<br />
* ''windowName:''<br />
: (optional) name of the window to set the text colors to be reversed or not.<br />
<br />
* ''boolean:''<br />
: A ''true'' or ''false'' that enables or disables reversing of the fore- and back-ground colors of text<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
-- enable fore/back-ground color reversal of text<br />
setReverse(true)<br />
-- the following echo will have the text colors reversed<br />
echo("hi")<br />
-- turns off bolding, italics, underlines, colouring, and strikethrough (and, after this and overline have been added, them as well). It's good practice to clean up after you're done with the formatting, so other your formatting doesn't "bleed" into other echoes.<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.17}}<br />
<br />
{{note}} Although the visual effect on-screen is the same as that of text being selected if both apply to a piece of text they neutralise each other - however the effect of the reversal ''will'' be carried over in copies made by the "Copy to HTML" and in logs made in HTML format log file mode.<br />
<br />
==setStrikeOut==<br />
;setStrikeOut([windowName], boolean)<br />
: Sets the current text font to be striken out (true) or not striken out (false) mode. If the windowName parameters omitted, the main screen will be used. If you've got text currently selected in the Mudlet buffer, then the selection will be bolded. Any text you add after with [[Manual:Lua_Functions#echo|echo()]] or [[Manual:Lua_Functions#insertText|insertText()]] will be striken out until you use [[Manual:Lua_Functions#resetFormat|resetFormat()]].<br />
<br />
* ''windowName:''<br />
: (optional) name of the window to set the text to be stricken out or not.<br />
<br />
* ''boolean:''<br />
: A ''true'' or ''false'' that enables or disables striking out of text<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
-- enable striken-out text<br />
setStrikeOut(true)<br />
-- the following echo will be have a strikethrough<br />
echo("hi")<br />
-- turns off bolding, italics, underlines, colouring, and strikethrough. It's good practice to clean up after you're done with the formatting, so other your formatting doesn't "bleed" into other echoes.<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
==setTextFormat==<br />
;setTextFormat(windowName, r1, g1, b1, r2, g2, b2, bold, underline, italics, [strikeout], [overline], [reverse])<br />
: Sets current text format of selected window. This is a more convenient means to set all the individual features at once compared to using [[#setFgColor|setFgColor]](windowName, r,g,b), [[#setBold|setBold]](windowName, true), [[#setItalics|setItalics]](windowName, true), [[#setUnderline|setUnderline]](windowName, true), [[#setStrikeOut|setStrikeOut]](windowName, true).<br />
: See Also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]]<br />
<br />
;Parameters<br />
* ''windowName''<br />
: Specify name of selected window. If empty string "" or "main" format will be applied to the main console<br />
* ''r1,g1,b1''<br />
: To color text background, give number values in RBG style<br />
* ''r2,g2,b2''<br />
: To color text foreground, give number values in RBG style<br />
* ''bold''<br />
: To format text bold, set to 1 or true, otherwise 0 or false<br />
* ''underline''<br />
: To underline text, set to 1 or true, otherwise 0 or false<br />
* ''italics''<br />
: To format text italic, set to 1 or true, otherwise 0 or false<br />
* ''strikeout<br />
: (optional) To strike text out, set to 1 or true, otherwise 0 or false or simply no argument<br />
* ''overline<br />
: (optional) To use overline, set to 1 or true, otherwise 0 or false or simply no argument<br />
* ''reverse<br />
: (optional) To swap foreground and background colors, set to 1 or true, otherwise 0 or false or simply no argument<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
--This script would create a mini text console and write with bold, struck-out, yellow foreground color and blue background color "This is a test".<br />
createMiniConsole( "con1", 0,0,300,100);<br />
setTextFormat("con1",0,0,255,255,255,0,true,0,false,1);<br />
echo("con1","This is a test")<br />
</syntaxhighlight><br />
<br />
{{note}} In versions prior to 3.7.0 the error messages ''and this wiki'' were wrong in that they had the foreground color parameters as r1, g1 and b1 and the background ones as r2, g2 and b2.<br />
<br />
==setUnderline==<br />
;setUnderline(windowName, bool)<br />
: Sets the current text font to underline/non-underline mode. If the windowName parameters omitted, the main screen will be used.<br />
<br />
==setUserWindowTitle==<br />
;setUserWindowTitle(windowName, text)<br />
: sets a new title text for the UserWindow windowName<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the userwindow<br />
* ''text''<br />
: new title text<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
: See also: [[#resetUserWindowTitle|resetUserWindowTitle()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
==setUserWindowStyleSheet==<br />
;setUserWindowStyleSheet(windowName, markup)<br />
: Applies Qt style formatting to the border/title area of a userwindow via a special markup language.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the userwindow<br />
* ''markup''<br />
: The string instructions, as specified by the Qt Style Sheet reference.<br />
: Note that when you dock the userwindow the border style is not provided by this<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- changes the title area style of the UserWindow 'myUserWindow'<br />
setUserWindowStyleSheet("myUserWindow", [[QDockWidget::title{ <br />
background-color: rgb(0,255,150);<br />
border: 2px solid red;<br />
border-radius: 8px;<br />
text-align: center; <br />
}]])<br />
</syntaxhighlight><br />
<br />
: See also: [[#openUserWindow|openUserWindow()]]<br />
<br />
==setWindow==<br />
;setWindow(windowName, name, [Xpos, Ypos, show])<br />
: Changes the parent window of an element.<br />
{{MudletVersion|4.8}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the userwindow which you want the element put in. If you want to put the element into the main window, use windowName "main".<br />
* ''name''<br />
: Name of the element which you want to switch the parent from. Elements can be labels, miniconsoles and the embedded mapper. If you want to move the mapper use the name "mapper"<br />
* ''Xpos:''<br />
: X position of the element. Measured in pixels, with 0 being the very left. Passed as an integer number. Optional, if not given it will be 0.<br />
* ''Ypos:''<br />
: Y position of the element. Measured in pixels, with 0 being the very top. Passed as an integer number. Optional, if not given it will be 0.<br />
* ''show:''<br />
: true or false to decide if the element will be shown or not in the new parent window. Optional, if not given it will be true.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setWindow("myuserwindow", "mapper")<br />
-- This will put your embedded mapper in your userwindow "myuserwindow".<br />
</syntaxhighlight><br />
<br />
==setWindowWrap==<br />
;setWindowWrap(windowName, wrapAt)<br />
: sets at what position in the line the will start word wrap.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the "main" console or user-created miniconsole which you want to be wrapped differently. If you want to wrap the main window, use windowName "main".<br />
* ''wrapAt:''<br />
: Number of characters at which the wrap must happen at the latest. This means, it probably will be wrapped earlier than that.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setWindowWrap("main", 10)<br />
display("This is just a test")<br />
<br />
-- The following output will result in the main window console:<br />
"This is<br />
just a<br />
test"<br />
</syntaxhighlight><br />
<br />
==setWindowWrapIndent==<br />
;setWindowWrapIndent(windowName, wrapTo)<br />
: sets how many spaces wrapped text will be indented with (after the first line of course).<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the "main" console or user-created miniconsole which you want to be wrapped differently. If you want to wrap the main window, use windowName "main".<br />
* ''wrapTo:''<br />
: Number of spaces which wrapped lines are prefixed with.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setWindowWrap("main", 10)<br />
setWindowWrapIndent("main", 3)<br />
display("This is just a test")<br />
<br />
-- The following output will result in the main window console:<br />
"This is<br />
just a<br />
test"<br />
</syntaxhighlight><br />
<br />
==showCaptureGroups==<br />
;showCaptureGroups()<br />
:Lua debug function that highlights in random colors all capture groups in your trigger regex on the screen. This is very handy if you make complex regex and want to see what really matches in the text. This function is defined in DebugTools.lua.<br />
<br />
;Example:<br />
:Make a trigger with the regex (\w+) and call this function in a trigger. All words in the text will be highlighted in random colors.<br />
<br />
==showMultimatches==<br />
;showMultimatches()<br />
:Lua helper function to show you what the table multimatches[n][m] contains. This is very useful when debugging multiline triggers - just doing showMultimatches() in your script will make it give the info. This function is defined in DebugTools.lua.<br />
<br />
;Example:<br />
See [[Manual:Advanced_Lua#How_to_use_multimatches.5Bn.5D.5Bm.5D|How to use multimatches[n][m]]] for a more thorough explanation including examples.<br />
<br />
==showWindow==<br />
;showWindow(name)<br />
: Makes a hidden window (label or miniconsole) be shown again.<br />
<br />
: See also: [[#hideWindow | hideWindow()]]<br />
<br />
==startMovie==<br />
;startMovie(label name)<br />
<br />
: Starts the gif animation - if it was previously stopped or paused.<br />
: Returns true<br />
<br />
: See also: [[Manual:Lua_Functions#setMovie|setMovie()]], [[Manual:Lua_Functions#pauseMovie|pauseMovie()]], [[Manual:Lua_Functions#setMovieFrame|setMovieFrame()]], [[Manual:Lua_Functions#setMovieSpeed|setMovieSpeed()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''label name:'' <br />
: name of the gif label <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create a label with the name myMovie<br />
createLabel("myMovie",0,0,200,200,0)<br />
<br />
-- puts the gif on the label and animates it<br />
setMovie("myMovie", getMudletHomeDir().."/movie.gif")<br />
--stops the animation<br />
pauseMovie("myMovie")<br />
--restart the animation<br />
startMovie("myMovie")<br />
<br />
</syntaxhighlight><br />
<br />
==showColors==<br />
;showColors([columns], [filterColor], [sort])<br />
: shows the named colors currently available in Mudlet's color table. These colors are stored in '''color_table''', in table form. The format is ''color_table.colorName = {r, g, b}''.<br />
<br />
: See Also: [[Manual:Lua_Functions#bg|bg()]], [[Manual:Lua_Functions#fg|fg()]], [[Manual:Lua_Functions#cecho|cecho()]]<br />
<br />
;Parameters<br />
* ''columns:''<br />
: (optional) number of columns to print the color table in.<br />
* ''filterColor:''<br />
: (optional) filter text. If given, the colors displayed will be limited to only show colors containing this text.<br />
* ''sort:''<br />
: (optional) sort colors alphabetically.<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- display as four columns:<br />
showColors(4)<br />
<br />
-- show only red colours:<br />
showColors("red")<br />
</syntaxhighlight><br />
The output for this is:<br />
<br />
[[File:ShowColors.png|showColors(4)|thumb|center]]<br />
<br />
==showGauge==<br />
;showGauge(gaugeName)<br />
: shows the given gauge, in case it was hidden previously.<br />
<br />
: See also: [[#hideGauge|hideGauge()]], [[#createGauge|createGauge()]]<br />
<br />
;Parameters<br />
* ''gaugeName:''<br />
: name of the gauge to show.<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
hideGauge("my gauge")<br />
showGauge("my gauge")<br />
</syntaxhighlight><br />
<br />
==showToolBar==<br />
;showToolBar(name)<br />
: Makes a toolbar (a button group) appear on the screen.<br />
<br />
;Parameters<br />
* ''name:''<br />
: name of the button group to display<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
showToolBar("my attack buttons")<br />
</syntaxhighlight><br />
<br />
==suffix==<br />
;suffix(text, [writingFunction], [foregroundColor], [backgroundColor], [windowName])<br />
: Suffixes text at the end of the current line. This is similar to [[Manual:Lua_Functions#echo | echo()]], which also suffixes text at the end of the line, but different - [[Manual:Lua_Functions#echo | echo()]] makes sure to do it on the last line in the buffer, while suffix does it on the line the cursor is currently on.<br />
<br />
;Parameters<br />
* ''text''<br />
: the information you want to prefix<br />
* ''writingFunction''<br />
: optional parameter, allows the selection of different functions to be used to write the text, valid options are: echo, cecho, decho, and hecho.<br />
* ''foregroundColor''<br />
: optional parameter, allows a foreground color to be specified if using the echo function using a color name, as with the fg() function<br />
* ''backgroundColor''<br />
: optional parameter, allows a background color to be specified if using the echo function using a color name, as with the bg() function<br />
* ''windowName''<br />
: optional parameter, allows the selection a miniconsole or the main window for the line that will be prefixed<br />
<br />
: See also: [[#prefix | prefix()]], [[Manual:Lua_Functions#echo | echo()]]<br />
<br />
==setCommandBackgroundColor==<br />
;setCommandBackgroundColor([windowName], r, g, b, [transparency])<br />
:Sets the background color for echo of commands. Colors are from 0 to 255 (0 being black), and transparency is from 0 to 255 (0 being completely transparent).<br />
<br />
;Parameters<br />
<br />
*''windowName:''<br />
: (optional) name of the label/miniconsole/userwindow to change the background color on, or "main" for the main window.<br />
*''r:''<br />
:Amount of red to use, from 0 (none) to 255 (full).<br />
*''g:''<br />
:Amount of green to use, from 0 (none) to 255 (full).<br />
*''b:''<br />
:Amount of red to use, from 0 (none) to 255 (full).<br />
*''transparency:''<br />
:(optional) amount of transparency to use, from 0 (fully transparent) to 255 (fully opaque). Defaults to 255 if omitted.<br />
<br />
{{MudletVersion|4.17.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- make a red command background color in main console.<br />
setCommandBackgroundColor(255,0,0,200)<br />
</syntaxhighlight><br />
<br />
==setCommandForegroundColor==<br />
;setCommandForegroundColor([windowName], r, g, b, [transparency])<br />
:Sets the foreground color for echo of commands. Colors are from 0 to 255 (0 being black), and transparency is from 0 to 255 (0 being completely transparent).<br />
<br />
;Parameters<br />
<br />
*''windowName:''<br />
: (optional) name of the label/miniconsole/userwindow to change the background color on, or "main" for the main window.<br />
*''r:''<br />
:Amount of red to use, from 0 (none) to 255 (full).<br />
*''g:''<br />
:Amount of green to use, from 0 (none) to 255 (full).<br />
*''b:''<br />
:Amount of red to use, from 0 (none) to 255 (full).<br />
*''transparency:''<br />
:(optional) amount of transparency to use, from 0 (fully transparent) to 255 (fully opaque). Defaults to 255 if omitted.<br />
<br />
{{MudletVersion|4.17.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- make a red command foreground color in main console.<br />
setCommandForegroundColor(255,0,0,200)<br />
</syntaxhighlight><br />
<br />
==scrollDown==<br />
;scrollDown([windowName,] [lines])<br />
:Scrolls down in window by a certain number of lines.<br />
:See also: [[Manual:Lua_Functions#getScroll|getScroll]], [[Manual:Lua_Functions#scrollTo|scrollTo]], [[Manual:Lua_Functions#scrollUp|scrollUp]]<br />
<br />
;Parameters<br />
*''windowName:''<br />
:(optional) name of the window in which to scroll. Default is the main window.<br />
*''lines:''<br />
:(optional) how many lines to scroll by. Default is 1.<br />
<br />
{{MudletVersion|4.17.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- scroll down by 7 lines<br />
scrollDown(7)<br />
</syntaxhighlight><br />
<br />
==scrollUp==<br />
;scrollUp([windowName,] [lines])<br />
:Scrolls up in window by a certain number of lines.<br />
:See also: [[Manual:Lua_Functions#getScroll|getScroll]], [[Manual:Lua_Functions#scrollTo|scrollTo]], [[Manual:Lua_Functions#scrollDown|scrollDown]]<br />
<br />
;Parameters<br />
*''windowName:''<br />
:(optional) name of the window in which to scroll. Default is the main window.<br />
*''lines:''<br />
:(optional) how many lines to scroll by. Default is 1.<br />
<br />
{{MudletVersion|4.17.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- scroll up by 7 lines<br />
scrollUp(7)<br />
</syntaxhighlight><br />
<br />
==scrollTo==<br />
;scrollTo([windowName,] [lineNumber])<br />
: Scrolls window to a specific line in the buffer.<br />
; Parameters<br />
*''windowName:''<br />
:(optional) name of the window in which to scroll. Default is the main window.<br />
*''lineNumber:''<br />
:(optional) target line to scroll to, counting from the top of buffer or with negative numbers to count from the end of buffer. Default is the end of the buffer, to stop scrolling.<br />
:See also: [[Manual:Lua_Functions#getScroll|getScroll]], [[Manual:Lua_Functions#scrollUp|scrollUp]], [[Manual:Lua_Functions#scrollDown|scrollDown]]<br />
<br />
{{MudletVersion|4.17.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- scroll to line 42 in buffer<br />
scrollTo(42)<br />
<br />
-- start of session<br />
scrollTo(0)<br />
<br />
-- 20 lines ago<br />
scrollTo(-20)<br />
<br />
-- chat window to line 30<br />
scrollTo("chat", 30)<br />
<br />
-- stop scrolling main window<br />
scrollTo()<br />
<br />
-- stop scrolling chat window<br />
scrollTo("chat")<br />
</syntaxhighlight><br />
<br />
==windowType==<br />
;typeOfWindow = windowType(windowName)<br />
<br />
:Given the name of a window, will return if it's a label, miniconsole, userwindow or a commandline.<br />
<br />
;See also:[[Manual:Lua_Functions#createLabel|createLabel()]], [[Manual:Lua_Functions#openUserWindow|openUserWindow()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
*''windowName:''<br />
:The name used to create the window element. Use "main" for the main console<br />
<br />
<br />
;Returns<br />
*Window type as string ("label", "miniconsole", "userwindow", or "commandline") or nil+error if it does not exist.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a Geyser label and and check its type<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
display(windowType(testLabel.name)) -- displays "label"<br />
<br />
-- the main console returns "miniconsole" because it uses the same formatting functions<br />
display(windowType("main")) -- displays "miniconsole"<br />
<br />
-- check for the existence of a window<br />
local windowName = "this thing does not exist"<br />
local ok, err = windowType(windowName)<br />
if ok then<br />
-- do things with it, as it does exist.<br />
-- the ok variable will hold the type of window it is ("label", "commandline", etc)<br />
else<br />
cecho("<red>ALERT!! window does not exist")<br />
end<br />
</syntaxhighlight><br />
<br />
;Additional development notes<br />
<br />
==wrapLine==<br />
;wrapLine(windowName, lineNumber)<br />
: wraps the line specified by ''lineNumber'' of mini console (window) ''windowName''. This function will interpret \n characters, apply word wrap and display the new lines on the screen. This function may be necessary if you use deleteLine() and thus erase the entire current line in the buffer, but you want to do some further echo() calls after calling deleteLine(). You will then need to re-wrap the last line of the buffer to actually see what you have echoed and get your \n interpreted as newline characters properly. Using this function is no good programming practice and should be avoided. There are better ways of handling situations where you would call deleteLine() and echo afterwards e.g.:<br />
<br />
<syntaxhighlight lang="lua">selectString(line,1)<br />
replace("")</syntaxhighlight><br />
<br />
This will effectively have the same result as a call to deleteLine() but the buffer line will not be entirely removed. Consequently, further calls to echo() etc. sort of functions are possible without using wrapLine() unnecessarily.<br />
<br />
: See Also: [[Manual:Lua_Functions#replace|replace()]], [[Manual:Lua_Functions#deleteLine|deleteLine()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The miniconsole or the main window (use ''main'' for the main window)<br />
* ''lineNumber:''<br />
: The line number which you'd like re-wrapped.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- re-wrap the last line in the main window<br />
wrapLine("main", getLineCount())<br />
</syntaxhighlight><br />
<br />
[[Category:Mudlet Manual]]<br />
[[Category:Mudlet API]]</div>Demonnichttps://wiki.mudlet.org/index.php?title=Area_51&diff=20467Area 512023-06-01T23:30:40Z<p>Demonnic: /* PR 6849 merged*/</p>
<hr />
<div>{{TOC right}}<br />
<br />
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 [[Manual:Lua_Functions|Lua Functions]] and its sub-sites. <br />
<br />
Please use the [[Area_51/Template]] to add new entries in the sections below.<br />
<br />
Links to other functions or parts in other sections (i.e. the main Wiki area) need to include the section details before the <nowiki>'#'</nowiki> character in the link identifier on the left side of the <nowiki>'|'</nowiki> divider between the identifier and the display text. e.g.<br />
:: <nowiki>[[Manual:Mapper_Functions#getCustomLines|getCustomLines()]]</nowiki><br />
rather than:<br />
:: <nowiki>[[#getCustomLines|getCustomLines()]]</nowiki><br />
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!<br />
<br />
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.<br />
<br />
<br />
=Basic Essential Functions=<br />
:These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.<br />
<br />
=Database Functions=<br />
:A collection of functions for helping deal with the database.<br />
<br />
=Date/Time Functions=<br />
: A collection of functions for handling date & time.<br />
<br />
=File System Functions=<br />
: A collection of functions for interacting with the file system.<br />
<br />
=Mapper Functions=<br />
: A collection of functions that manipulate the mapper and its related features.<br />
<br />
==getMapZoom, PR #6615==<br />
;getMapZoom([areaID])<br />
<br />
:Gets the current 2D map zoom level. Added in '''Mudlet ''tba''''' 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.<br />
<br />
<!--will need to insert "Manual:Mapper_Functions" prior to # when moved to that documentation area--><br />
:See also: [[#setMapZoom|setMapZoom()]].<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6615<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID number to get the 2D zoom for (''optional'', the function works on the area currently being viewed if this is omitted).<br />
<br />
;Returns<br />
* A floating point number on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo("\nCurrent zoom level: " .. getMapZoom() .. "\n")<br />
-- Could be anything from 3 upwards:<br />
<br />
Current zoom level: 42.4242<br />
<br />
setMapZoom(2.5 + getMapZoom(1), 1) -- zoom out the area with ID 1 by 2.5<br />
true<br />
</syntaxhighlight><br />
<br />
{{note}} The precise meaning of a particular zoom value may have an underlying meaning however that bit of the code is rather old and no current coder has determined the significance, so far - 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!<br />
<br />
==mapSymbolFontInfo, PR #4038 closed==<br />
;mapSymbolFontInfo()<br />
: See also: [[#setupMapSymbolFont|setupMapSymbolFont()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;returns<br />
* either a table of information about the configuration of the font used for symbols in the (2D) map, the elements are:<br />
:* ''fontName'' - a string of the family name of the font specified<br />
:* ''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.<br />
:* ''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).<br />
* or ''nil'' and an error message on failure.<br />
<br />
::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).<br />
<br />
==moveMapLabel, PR #6014 open==<br />
;moveMapLabel(areaID/Name, labeID/Text, coordX/deltaX, coordY/deltaY[, coordZ/deltaZ][, absoluteNotRelativeMove])<br />
Re-positions a map label within an area in the 2D mapper, in a similar manner as the [[#moveRoom|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).<br />
<br />
:See also: [[Manual:Mapper_Functions#getMapLabels|getMapLabels()]], [[Manual:Mapper_Functions#getMapLabel|getMapLabel()]].<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6014<br />
<br />
;Parameters<br />
* ''areaID/Name:''<br />
: Area ID as number or AreaName as string containing the map label.<br />
<br />
* ''labelID/Text:''<br />
: 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.<br />
<br />
* ''coordX/deltaX:''<br />
: 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.<br />
<br />
* ''coordY/deltaY:''<br />
: 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.<br />
<br />
* ''coordZ/deltaZ:''<br />
: (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.<br />
<br />
* ''absoluteNotRelativeMove:''<br />
: (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'').<br />
<br />
;Returns<br />
: ''true'' on success or ''nil'' and an error message on failure, if successful it will also refresh the map display to show the result.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- move the first label in the area with the ID number of 2, three spaces to the east and four spaces to the north<br />
moveMapLabel(0, 2, 3.0, 4.0)<br />
<br />
-- 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<br />
moveMapLabel(0, 2, -1.0, 0.0, false)<br />
<br />
-- 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**:<br />
moveRoom(1, 2, -3.5, -2.0, true)<br />
<br />
-- move the second label in the area with the ID number of 2, up three levels<br />
moveRoom(1, 2, 0.0, 0.0, 3.0)<br />
<br />
-- move the second label in the "Test 1" area one space to the west, note the last two arguments are unneeded<br />
moveRoom("Test 1", 1, -1.0, 0.0, 0.0, false)<br />
<br />
-- 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:<br />
moveRoom(5, "Home", 0.0, 0.0, 0.0, true)<br />
<br />
-- all of the above will return the 'true' boolean value assuming there are the indicated labels and areas<br />
</syntaxhighlight><br />
<br />
==moveRoom, PR #6010 open==<br />
;moveRoom(roomID, coordX/deltaX, coordY/deltaY[, coordZ/deltaZ][, absoluteNotRelativeMove])<br />
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 [[Manual:Mapper_Functions#setRoomCoordinates|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.<br />
<br />
:See also: [[Manual:Mapper_Functions#setRoomCoordinates|setRoomCoordinates()]]<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6010<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID number to move.<br />
<br />
* ''coordX/deltaX:''<br />
: The absolute coordinate or the relative amount as a number to move the room in "room coordinates" along the X-axis.<br />
<br />
* ''coordY/deltaY:''<br />
: The absolute coordinate or the relative amount as a number to move the room in "room coordinates" along the Y-axis.<br />
<br />
* ''coordZ/deltaZ:''<br />
: (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.<br />
<br />
* ''absoluteNotRelativeMove:''<br />
: (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'').<br />
<br />
;Returns<br />
: ''true'' on success or ''nil'' and an error message on failure, if successful it will also refresh the map display to show the result.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- move the first room one space to the east and two spaces to the north<br />
moveRoom(1, 1, 2)<br />
<br />
-- move the first room one space to the west, note the final boolean argument is unneeded<br />
moveRoom(1, -1, 0, false)<br />
<br />
-- 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**:<br />
moveRoom(1, -3, -2, true)<br />
<br />
-- move the second room up three levels<br />
moveRoom(2, 0, 0, 3)<br />
<br />
-- move the second room one space to the west, note the last two arguments are unneeded<br />
moveRoom(2, -1, 0, 0, false)<br />
<br />
-- move the second room to the **center of the whole map**, note the last two arguments are required in this case:<br />
moveRoom(2, 0, 0, 0, true)<br />
<br />
-- all of the above will return the 'true' boolean value assuming there are rooms with 1 and 2 as ID numbers<br />
</syntaxhighlight><br />
<br />
==setMapZoom (revised), PR #6615==<br />
;setMapZoom(zoom[, areaID])<br />
<br />
:Zooms the 2D (only) map to a given zoom level. Larger numbers zooms the map further out. Revised in '''Mudlet ''tba''''' 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.<br />
<br />
<!--will need to insert "Manual:Mapper_Functions" prior to # when moved to that documentation area--><br />
:See also: [[#getMapZoom|getMapZoom()]].<br />
<br />
{{note}} The additional areaID parameter and the returned values described below are pending, they are not yet available/produced. See https://github.com/Mudlet/Mudlet/pull/6615<br />
<br />
;Parameters<br />
* ''zoom:''<br />
: floating point number that is at least 3.0 to set the zoom to.<br />
<br />
* ''areaID:''<br />
: Area ID number to adjust the 2D zoom for (''optional'', the function works on the area currently being viewed if this is omitted).<br />
<br />
;Returns (only since '''Mudlet ''tba''''')<br />
* ''true'' on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setMapZoom(10.0) -- zoom to a somewhat acceptable level, a bit big but easily visible connections<br />
true<br />
<br />
setMapZoom(2.5 + getMapZoom(1), 1) -- zoom out the area with ID 1 by 2.5<br />
true<br />
</syntaxhighlight><br />
<br />
{{note}} The precise meaning of a particular zoom value may have an underlying meaning however that bit of the code is rather old and no current coder has determined the significance, so far - 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!<br />
<br />
==setupMapSymbolFont, PR #4038 closed==<br />
;setupMapSymbolFont(fontName[, onlyUseThisFont[, scalingFactor]])<br />
:configures the font used for symbols in the (2D) map.<br />
: See also: [[#mapSymbolFontInfo|mapSymbolFontInfo()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;Parameters<br />
* ''fontName'' one of:<br />
:* - a string that is the family name of the font to use;<br />
:* - the empty string ''""'' to reset to the default {which is '''"Bitstream Vera Sans Mono"'''};<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow a following one to be modified.<br />
* ''onlyUseThisFont'' (optional) one of:<br />
:* - 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;<br />
:* - 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;<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow the following one to be modified.<br />
* ''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.<br />
<br />
;Returns<br />
* ''true'' on success<br />
* ''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).<br />
<br />
=Miscellaneous Functions=<br />
: Miscellaneous functions.<br />
<br />
==createVideoPlayer, PR #6439==<br />
;createVideoPlayer([name of userwindow], x, y, width, height)<br />
<br />
: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.<br />
<br />
{{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.<br />
<br />
{{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.<br />
<br />
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]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a 300x300 video player in the top-left corner of Mudlet<br />
createVideoPlayer(0,0,300,300)<br />
<br />
-- Alternative examples using Geyser.VideoPlayer<br />
GUI.VideoPlayer = GUI.VideoPlayer or Geyser.VideoPlayer:new({name="GUI.VideoPlayer", x = 0, y = 0, width = "25%", height = "25%"})<br />
<br />
GUI.VideoPlayer = GUI.VideoPlayer or Geyser.VideoPlayer:new({<br />
name = "GUI.VideoPlayer",<br />
x = "70%", y = 0, -- edit here if you want to move it<br />
width = "30%", height = "50%"<br />
}, GUI.Right)<br />
</syntaxhighlight><br />
<br />
==loadVideoFile, PR #6439==<br />
;loadVideoFile(settings table) or loadVideoFile(name, [url])<br />
:Loads video files from the Internet or the local file system to the "media" folder of the profile for later use with [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]] and [[Manual:Miscellaneous_Functions#stopVideos|stopVideos()]]. Although files could be loaded or streamed directly at playing time from [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]], loadVideoFile() provides the advantage of loading files in advance.<br />
<br />
{{note}} Video files consume drive space on your device. Consider using the streaming feature of [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]] for large files.<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
! style="text-align:left;" |Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;" |Yes<br />
|name<br />
|<file name><br />
| style="text-align:left;" |<br />
*Name of the media file.<br />
*May contain directory information (i.e. weather/maelstrom.mp4).<br />
*May be part of the profile (i.e. getMudletHomeDir().. "/congratulations.mp4")<br />
*May be on the local device (i.e. "C:/Users/YourNameHere/Movies/nevergoingtogiveyouup.mp4")<br />
|- style="color: blue;"<br />
| style="text-align:center;" |Maybe<br />
|url<br />
|<url><br />
| style="text-align:left;" |<br />
*Resource location where the media file may be downloaded.<br />
*Only required if file to load is not part of the profile or on the local file system.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#playSoundFile|loadSoundFile()]], [[Manual:Miscellaneous Functions#loadMusicFile|loadMusicFile()]], [[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#createVideoPlayer|createVideoPlayer()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Download from the Internet<br />
loadVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
})<br />
<br />
-- OR download from the profile<br />
loadVideoFile({name = getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4"})<br />
<br />
-- OR download from the local file system<br />
loadVideoFile({name = "C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4"})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of loadVideoFile(name[, url]) ----<br />
<br />
-- Download from the Internet<br />
loadVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4"<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
)<br />
<br />
-- OR download from the profile<br />
loadVideoFile(getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4")<br />
<br />
-- OR download from the local file system<br />
loadVideoFile("C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4")<br />
</syntaxhighlight><br />
<br />
==playVideoFile, PR #6439==<br />
;playVideoFile(settings table)<br />
:Plays video files from the Internet or the local file system for later use with [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]]. Video files may be downloaded to the device and played, or streamed from the Internet when the value of the <code>stream</code> parameter is <code>true</code>.<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
!Default<br />
! style="text-align:left;" |Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;" |Yes<br />
|name<br />
|<file name><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Name of the media file.<br />
*May contain directory information (i.e. weather/maelstrom.mp4).<br />
*May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp4")<br />
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp4")<br />
*Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.<br />
|-<br />
| style="text-align:center;" |No<br />
| volume<br />
|1 to 100<br />
|50<br />
| style="text-align:left;" |<br />
*Relative to the volume set on the player's client.<br />
|-<br />
| style="text-align:center;" |No<br />
|fadein<br />
|<msec><br />
|<br />
|<br />
*Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.<br />
*Start position: Start of media.<br />
*End position: Start of media plus the number of milliseconds (msec) specified.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
|fadeout<br />
|<msec><br />
|<br />
|<br />
*Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.<br />
*Start position: End of the media minus the number of milliseconds (msec) specified.<br />
*End position: End of the media.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
|start<br />
|<msec><br />
| 0<br />
| style="text-align:left;" |<br />
*Begin play at the specified position in milliseconds.<br />
|-<br />
| style="text-align:center;" |No<br />
|loops<br />
| -1, or >= 1<br />
|1<br />
| style="text-align:left;" |<br />
*Number of iterations that the media plays.<br />
*A value of -1 allows the media to loop indefinitely.<br />
|-<br />
| style="text-align:center;" |No<br />
|key<br />
|<key><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;" |No<br />
|tag<br />
|<tag><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Helps categorize media.<br />
|-<br />
| style="text-align:center;" |No<br />
|continue<br />
|true or false<br />
|true<br />
| style="text-align:left;" |<br />
*Continues playing matching new video files when true.<br />
*Restarts matching new video files when false.<br />
|- style="color: blue;"<br />
| style="text-align:center;" |Maybe<br />
|url<br />
|<url><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Resource location where the media file may be downloaded.<br />
*Only required if the file is to be downloaded remotely or for streaming from the Internet.<br />
|- style="color: blue;"<br />
| style="text-align:center;" |Maybe<br />
|stream<br />
|true or false<br />
|false<br />
| style="text-align:left;" |<br />
*Streams files from the Internet when true.<br />
*Download files when false (default).<br />
*Used in combination with the `url` key.<br />
|-<br />
|}<br />
<br />
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#stopSounds|stopSounds()]], [[Manual:Miscellaneous Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous Functions#stopVideos|stopVideos()]], [[Manual:Miscellaneous Functions#createVideoPlayer|createVideoPlayer()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stream a video file from the Internet and play it.<br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
, stream = true<br />
})<br />
<br />
-- 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.<br />
<br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
})<br />
<br />
-- Play a video file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
})<br />
<br />
-- OR copy once from the game's profile, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile({<br />
name = getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4"<br />
, volume = 75<br />
})<br />
<br />
-- OR copy once from the local file system, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile({<br />
name = "C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4"<br />
, volume = 75<br />
})<br />
<br />
-- OR download once from the Internet, and play a video stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 10 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 15 seconds from the end of the video<br />
---- [start] 5 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [key] reference of "text" for stopping this unique video later<br />
---- [tag] reference of "ambience" to stop any video later with the same tag<br />
---- [continue] playing this video if another request for the same video comes in (false restarts it) <br />
---- [url] resource location where the file may be accessed on the Internet<br />
---- [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) <br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, volume = nil -- nil lines are optional, no need to use<br />
, fadein = 10000<br />
, fadeout = 15000<br />
, start = 5000<br />
, loops = nil -- nil lines are optional, no need to use<br />
, key = "text"<br />
, tag = "ambience"<br />
, continue = true<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
, stream = false<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of playVideoFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,continue][,url][,stream]) ----<br />
<br />
-- Stream a video file from the Internet and play it.<br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4"<br />
, nil -- volume<br />
, nil -- fadein<br />
, nil -- fadeout<br />
, nil -- start<br />
, nil -- loops<br />
, nil -- key<br />
, nil -- tag<br />
, true -- continue<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/" -- url<br />
, false -- stream<br />
)<br />
<br />
-- 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.<br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4"<br />
, nil -- volume<br />
, nil -- fadein<br />
, nil -- fadeout<br />
, nil -- start<br />
, nil -- loops<br />
, nil -- key<br />
, nil -- tag<br />
, true -- continue<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/" -- url<br />
, false -- stream<br />
)<br />
<br />
-- Play a video file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4" -- name<br />
)<br />
<br />
-- OR copy once from the game's profile, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile(<br />
getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR copy once from the local file system, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile(<br />
"C:/Users/Tamarindo/Documents/TextInMotion-VideoSample-1080p.mp4" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR download once from the Internet, and play a video stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 10 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 15 seconds from the end of the video<br />
---- [start] 5 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [key] reference of "text" for stopping this unique video later<br />
---- [tag] reference of "ambience" to stop any video later with the same tag<br />
---- [continue] playing this video if another request for the same video comes in (false restarts it) <br />
---- [url] resource location where the file may be accessed on the Internet<br />
---- [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) <br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4" -- name<br />
, nil -- volume<br />
, 10000 -- fadein<br />
, 15000 -- fadeout<br />
, 5000 -- start<br />
, nil -- loops<br />
, "text" -- key<br />
, "ambience" -- tag<br />
, true -- continue<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/" -- url<br />
, false -- stream<br />
)<br />
</syntaxhighlight><br />
<br />
<br />
==stopVideos, PR #6439==<br />
;stopVideos(settings table)<br />
:Stop all videos (no filter), or videos that meet a combination of filters (name, key, and tag) intended to be paired with [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]].<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
! style="text-align:left;" |Purpose<br />
|-<br />
| style="text-align:center;" |No<br />
| name<br />
| <file name><br />
| style="text-align:left;" |<br />
* Name of the media file.<br />
|-<br />
| style="text-align:center;" |No<br />
|key<br />
|<key><br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;" |No<br />
|tag<br />
|<tag><br />
| style="text-align:left;" |<br />
*Helps categorize media.<br />
|-<br />
|}<br />
<br />
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#createVideoPlayer|createVideoPlayer()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stop all playing video files for this profile associated with the API<br />
stopVideos()<br />
<br />
-- Stop playing the text mp4 by name<br />
stopVideos({name = "TextInMotion-VideoSample-1080p.mp4"})<br />
<br />
-- Stop playing the unique sound identified as "text"<br />
stopVideos({<br />
name = nil -- nil lines are optional, no need to use<br />
, key = "text" -- key<br />
, tag = nil -- nil lines are optional, no need to use<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of stopVideos([name][,key][,tag]) ----<br />
<br />
-- Stop all playing video files for this profile associated with the API<br />
stopVideos()<br />
<br />
-- Stop playing the text mp4 by name<br />
stopVideos("TextInMotion-VideoSample-1080p.mp4")<br />
<br />
-- Stop playing the unique sound identified as "text"<br />
stopVideos(<br />
nil -- name<br />
, "text" -- key<br />
, nil -- tag<br />
)<br />
</syntaxhighlight><br />
<br />
<br />
==getCustomLoginTextId, PR #3952 open==<br />
;getCustomLoginTextId()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#sendPassword|sendPassword()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+Predefined custom login texts<br />
|-<br />
!Id!!Custom text!!Introduced in Mudlet version<br />
|-<br />
|1||"connect {character name} {password}"||TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCharacterName, PR #3952 open==<br />
;sendCharacterName()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
==sendCharacterPassword, PR #3952 open==<br />
;sendCharacterPassword()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]], [[#sendCharacterName|sendCharacterName()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCharacterName() ~= "" then<br />
tempTime(2.0, [[sendCharacterName()]], 1)<br />
tempTime(3.0, [[sendCharacterPassword()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCustomLoginText, PR #3952 open ==<br />
;sendCustomLoginText()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendPassword|sendPassword()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+Predefined custom login texts<br />
|-<br />
!Id!!Custom text!!Introduced in Mudlet version<br />
|-<br />
|1||"connect {character name} {password}"||TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
=Mudlet Object Functions=<br />
:A collection of functions that manipulate Mudlets scripting objects - triggers, aliases, and so forth.<br />
<br />
=Networking Functions=<br />
:A collection of functions for managing networking.<br />
<br />
=String Functions=<br />
:These functions are used to manipulate strings.<br />
<br />
=Table Functions=<br />
: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.<br />
<br />
=Text to Speech Functions=<br />
:These functions are used to create sound from written words. Check out our [[Special:MyLanguage/Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.<br />
<br />
=UI Functions=<br />
: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.<br />
<br />
==cecho2decho PR#6849 merged==<br />
; convertedString = cecho2decho(str)<br />
<br />
:Converts a cecho formatted string to a decho formatted one. <br />
;See also: [[Manual:Lua_Functions#decho2cecho|decho2cecho()]], [[Manual:Lua_Functions#cecho2html|cecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from cecho to decho<br />
;Returns <br />
* a string formatted for decho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to a decho string and use decho to display it<br />
local cechoString = "<red><b>!!ALERT!!:</b><orange> Something has gone wrong!\n"<br />
decho(cecho2decho(cechoString))<br />
</syntaxhighlight><br />
<br />
==cecho2hecho PR#6849 merged==<br />
; convertedString = cecho2hecho(str)<br />
<br />
:Converts a cecho formatted string to an hecho formatted one. <br />
;See also: [[Manual:Lua_Functions#hecho2cecho|hecho2cecho()]], [[Manual:Lua_Functions#cecho2html|cecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from cecho to decho<br />
;Returns <br />
* a string formatted for hecho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to an hecho string and use hecho to display it<br />
local cechoString = "<red><b>!!ALERT!!:</b><orange> Something has gone wrong!\n"<br />
hecho(cecho2hecho(cechoString))<br />
</syntaxhighlight><br />
<br />
==cecho2html PR#6849 merged==<br />
; convertedString = cecho2html(str[, resetFormat])<br />
<br />
:Converts a cecho formatted string to an html formatted one. <br />
;See also: [[Manual:Lua_Functions#decho2cecho|decho2cecho()]], [[Manual:Lua_Functions#decho2html|cecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from cecho to decho<br />
* ''resetFormat''<br />
: optional table of default formatting options. As returned by [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
;Returns <br />
* a string formatted for html<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create the base string<br />
local cechoString = "<red><b>!!ALERT!!:</b><orange> Something has gone wrong!\n"<br />
<br />
-- create a label to display the result onto<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
<br />
-- convert the cecho string to an html one, using the default formatting of testLabel created above<br />
local htmlString = cecho2html(cechoString, testLabel:getFormat())<br />
<br />
-- and finally echo it to the label to see<br />
-- I use rawEcho as that displays the html exactly as given.<br />
testLabel:rawEcho(htmlString)<br />
</syntaxhighlight><br />
<br />
==decho2cecho PR#6849 merged==<br />
; convertedString = decho2cecho(str)<br />
<br />
:Converts a decho formatted string to a cecho formatted one. <br />
;See also: [[Manual:Lua_Functions#cecho2decho|cecho2decho()]], [[Manual:Lua_Functions#decho2html|decho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from decho to cecho<br />
;Returns <br />
* a string formatted for cecho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to a decho string and use cecho to display it<br />
local dechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n"<br />
cecho(decho2cecho(dechoString))<br />
</syntaxhighlight><br />
<br />
==decho2hecho PR#6849 merged==<br />
; convertedString = decho2hecho(str)<br />
<br />
:Converts a decho formatted string to an hecho formatted one. <br />
;See also: [[Manual:Lua_Functions#hecho2decho|hecho2decho()]], [[Manual:Lua_Functions#decho2html|decho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from decho to decho<br />
;Returns <br />
* a string formatted for hecho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to an hecho string and use hecho to display it<br />
local dechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n"<br />
hecho(decho2hecho(dechoString))<br />
</syntaxhighlight><br />
<br />
==decho2html PR#6849 merged==<br />
; convertedString = decho2html(str[, resetFormat])<br />
<br />
:Converts a decho formatted string to an html formatted one. <br />
;See also: [[Manual:Lua_Functions#cecho2decho|cecho2decho()]], [[Manual:Lua_Functions#decho2html|decho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from decho to decho<br />
* ''resetFormat''<br />
: optional table of default formatting options. As returned by [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
;Returns <br />
* a string formatted for html<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create the base string<br />
local dechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n"<br />
<br />
-- create a label to display the result onto<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
<br />
-- convert the decho string to an html one, using the default formatting of testLabel created above<br />
local htmlString = decho2html(dechoString, testLabel:getFormat())<br />
<br />
-- and finally echo it to the label to see<br />
-- I use rawEcho as that displays the html exactly as given.<br />
testLabel:rawEcho(htmlString)<br />
</syntaxhighlight><br />
<br />
==deleteMultiline PR-6779 merged==<br />
<br />
; ok,err = deleteMultiline([triggerDelta])<br />
<br />
:Deletes all lines between when the multiline trigger fires and when the first trigger matched. Put another way, it deletes everything since the pattern in slot 1 matched.<br />
;See also: [[Manual:Lua_Functions#deleteLine|deleteLine()]], [[Manual:Lua_Functions#replaceLine|replaceLine()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
{{note}} This deletes all the lines since the first match of the multiline trigger matched. Do not use this if you donot want to delete ALL of those lines.<br />
<br />
;Parameters<br />
* ''[optional]triggerDelta:''<br />
: The line delta from the multiline trigger it is being called from. It is best to pass this in to ensure all lines are caught. If not given it will try to guess based on the number of patterns how many lines at most it might have to delete.<br />
<br />
;Returns <br />
* true if the function was able to run successfully, nil+error if something went wrong.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- if this trigger has a line delta of 3, you would call<br />
deleteMultiline(3)<br />
<br />
-- same thing, but with error handling<br />
local ok,err = deleteMultiline(3)<br />
if not ok then<br />
cecho("\n<firebrick>I could not delete the lines because: " .. err)<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
==hecho2cecho PR#6849 merged==<br />
; convertedString = hecho2cecho(str)<br />
<br />
:Converts a hecho formatted string to a cecho formatted one. <br />
;See also: [[Manual:Lua_Functions#cecho2decho|cecho2decho()]], [[Manual:Lua_Functions#hecho2html|hecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from hecho to cecho<br />
;Returns <br />
* a string formatted for cecho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to a hecho string and use cecho to display it<br />
local hechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n""<br />
cecho(hecho2cecho(hechoString))<br />
</syntaxhighlight><br />
<br />
==hecho2decho PR#6849 merged==<br />
; convertedString = hecho2decho(str)<br />
<br />
:Converts a hecho formatted string to a decho formatted one. <br />
;See also: [[Manual:Lua_Functions#decho2hecho|decho2hecho()]], [[Manual:Lua_Functions#hecho2html|hecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from hecho to decho<br />
;Returns <br />
* a string formatted for decho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to a decho string and use decho to display it<br />
local hechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n""<br />
decho(hecho2decho(hechoString))<br />
</syntaxhighlight><br />
<br />
==hecho2html PR#6849 merged==<br />
; convertedString = hecho2html(str[, resetFormat])<br />
<br />
:Converts a hecho formatted string to an html formatted one. <br />
;See also: [[Manual:Lua_Functions#cecho2hecho|cecho2hecho()]], [[Manual:Lua_Functions#hecho2html|hecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from hecho to hecho<br />
* ''resetFormat''<br />
: optional table of default formatting options. As returned by [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
;Returns <br />
* a string formatted for html<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create the base string<br />
local hechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n""<br />
<br />
-- create a label to display the result onto<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
<br />
-- convert the hecho string to an html one, using the default formatting of testLabel created above<br />
local htmlString = hecho2html(hechoString, testLabel:getFormat())<br />
<br />
-- and finally echo it to the label to see<br />
-- I use rawEcho as that displays the html exactly as given.<br />
testLabel:rawEcho(htmlString)<br />
</syntaxhighlight><br />
<br />
=Discord Functions=<br />
: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 [[Special:MyLanguage/Manual:Scripting#Discord_Rich_Presence|Discord scripting overview]].<br />
<br />
=Events=<br />
:New or revised events that Mudlet can raise to inform a profile about changes. See [[Manual:Event_Engine#Mudlet-raised_events|Mudlet-raised events]] for the existing ones.<br />
<br />
===sysMapAreaChanged, PR #6615===<br />
Raised when the area being viewed in the mapper is changed, either by the player-room being set to a new area or the user selecting a different area in the area selection combo-box in the mapper controls area. Returns two additional arguments being the areaID of the area being switched to and then the one for the area that is being left.<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6615</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:Mapper_Functions&diff=20461Manual:Mapper Functions2023-06-01T04:07:49Z<p>Demonnic: /* getRoomCharColor missing from docs */</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Mudlet API documentation for functions that manipulate the mapper and its related features.}}<br />
= Mapper Functions =<br />
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.<br />
<br />
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:<br />
<syntaxhighlight lang="lua"><br />
mudlet = mudlet or {}; mudlet.mapper_script = true<br />
</syntaxhighlight><br />
<br />
==addAreaName==<br />
;areaID = addAreaName(areaName)<br />
<br />
: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.<br />
: See also: [[#deleteArea|deleteArea()]], [[#addRoom|addRoom()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local newId, err = addAreaName(string.random(10))<br />
<br />
if newId == nil or newId < 1 or err then<br />
echo("That area name could not be added - error is: ".. err.."\n")<br />
else<br />
cecho("<green>Created new area with the ID of "..newId..".\n")<br />
end<br />
</syntaxhighlight><br />
<br />
==addCustomLine==<br />
;addCustomLine(roomID, id_to, direction, style, color, arrow)<br />
: See also: [[#getCustomLines|getCustomLines()]], [[#removeCustomLine|removeCustomLine()]]<br />
<br />
:Adds a new/replaces an existing custom exit line to the 2D mapper for the room with the Id given.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to attach the custom line to.<br />
* ''id_to:''<br />
: 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);<br />
: 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!)<br />
* ''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).<br />
* ''style:'' a string, one of: "solid line", "dot line", "dash line", "dash dot line" or "dash dot dot line" exactly.<br />
* ''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.<br />
* ''arrow:'' a boolean which if true will set the custom line to have an arrow on the end of the last segment.<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- create a line from roomid 1 to roomid 2<br />
addCustomLine(1, 2, "N", "dot line", {0, 255, 255}, true)<br />
<br />
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)<br />
</syntaxhighlight><br />
<br />
A bigger example that'll create a new area and the room in it:<br />
<br />
<syntaxhighlight lang="lua"><br />
local areaid = addAreaName("my first area")<br />
local newroomid = createRoomID()<br />
addRoom(newroomid)<br />
setRoomArea(newroomid, "my first area")<br />
setRoomCoordinates(newroomid, 0, 0, 0)<br />
<br />
local otherroomid = createRoomID()<br />
addRoom(otherroomid)<br />
setRoomArea(otherroomid, "my first area")<br />
setRoomCoordinates(otherroomid, 0, 5, 0)<br />
<br />
addSpecialExit(newroomid, otherroomid, "climb Rope")<br />
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)<br />
<br />
centerview(newroomid)<br />
</syntaxhighlight><br />
<br />
==addMapEvent==<br />
;addMapEvent(uniquename, event name, parent, display name, arguments)<br />
<br />
: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.<br />
: See also: [[#addMapMenu|addMapMenu()]], [[#removeMapEvent|removeMapEvent()]], [[#getMapEvents|getMapEvents()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addMapEvent("room a", "onFavorite") -- will make a label "room a" on the map menu's right click that calls onFavorite<br />
<br />
addMapEvent("room b", "onFavorite", "Favorites", "Special Room!", 12345, "arg1", "arg2", "argn") <br />
</syntaxhighlight><br />
The last line will make a label "Special Room!" under the "Favorites" menu that upon clicking will raise an event with all the arguments.<br />
<br />
<syntaxhighlight lang="lua"><br />
addMapMenu("Room type")<br />
addMapEvent("markRoomsAsDeathTrap", "onMapMarkSelectedRooms", "Room type", "Mark selected rooms as Death Trap")<br />
addMapEvent("markRoomsAsOneRoom", "onMapMarkSelectedRooms", "Room type", "Mark selected rooms as single-pass")<br />
<br />
function onMapMarkSelectedRooms(event, markRoomType)<br />
local selectedRooms = getMapSelection()["rooms"]<br />
for i, val in ipairs(selectedRooms) do<br />
if markRoomType == "markRoomsAsDeathTrap" then<br />
local r, g, b = unpack(color_table.black)<br />
--death trap<br />
setRoomEnv(val, 300)<br />
--death traps Env<br />
setCustomEnvColor(300, r, g, b, 255)<br />
setRoomChar(val, "☠️")<br />
lockRoom(val, true)<br />
elseif markRoomType == "markRoomsAsOneRoom" then<br />
local r, g, b = unpack(color_table.LightCoral)<br />
--single-pass<br />
setRoomEnv(val, 301)<br />
--one room Env<br />
setCustomEnvColor(301, r, g, b, 255)<br />
setRoomChar(val, "🚹")<br />
end<br />
end<br />
updateMap()<br />
end<br />
<br />
registerAnonymousEventHandler("onMapMarkSelectedRooms", "onMapMarkSelectedRooms")<br />
</syntaxhighlight><br />
This create menu and two submenu options: "Mark selected rooms as Death Trap" and "Mark selected rooms as single-pass"<br />
<br />
==addMapMenu==<br />
;addMapMenu(uniquename, parent, display name)<br />
<br />
: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()]].<br />
: See also: [[#addMapEvent|addMapEvent()]], [[#removeMapEvent|removeMapEvent()]], [[#getMapEvents|getMapEvents()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This will create a menu named: Favorites.<br />
addMapMenu("Favorites")<br />
<br />
-- This will create a submenu with the unique id 'Favorites123' under 'Favorites' with the display name of 'More Favorites'.<br />
addMapMenu("Favorites1234343", "Favorites", "More Favorites") <br />
</syntaxhighlight><br />
<br />
==addRoom==<br />
;addRoom(roomID)<br />
<br />
:Creates a new room with the given ID, returns true if the room was successfully created. <br />
<br />
{{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.<br />
{{note}} Creating your own mapping script? Check out more [[Manual:Mapper#Making_your_own_mapping_script|information here]].<br />
<br />
: See also: [[#createRoomID|createRoomID()]]<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
local newroomid = createRoomID()<br />
addRoom(newroomid)<br />
</syntaxhighlight><br />
<br />
==addSpecialExit==<br />
;addSpecialExit(roomIDFrom, roomIDTo, moveCommand)<br />
<br />
:Creates a one-way from one room to another, that will use the given command for going through them.<br />
<br />
: See also: [[#clearSpecialExits|clearSpecialExits()]], [[#removeSpecialExit|removeSpecialExit()]], [[#setExit|setExit()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- add a one-way special exit going from room 1 to room 2 using the 'pull rope' command<br />
addSpecialExit(1, 2, "pull rope")<br />
</syntaxhighlight><br />
<br />
Example in an alias:<br />
<syntaxhighlight lang="lua"><br />
-- sample alias pattern: ^spe (\d+) (.*?)$<br />
-- currentroom is your current room ID in this example<br />
addSpecialExit(currentroom,tonumber(matches[2]), matches[3])<br />
echo("\n SPECIAL EXIT ADDED TO ROOMID:"..matches[2]..", Command:"..matches[3])<br />
centerview(currentroom)<br />
</syntaxhighlight><br />
<br />
==auditAreas==<br />
;auditAreas()<br />
<br />
: 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.<br />
<br />
: See also: [[#saveMap|saveMap()]], [[#removeMapEvent|removeMapEvent()]], [[#getMapEvents|getMapEvents()]]<br />
<br />
==centerview==<br />
;centerview (roomID)<br />
<br />
: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.<br />
<br />
: See also: [[#getPlayerRoom|getPlayerRoom()]], [[#updateMap|updateMap()]]<br />
<br />
==clearAreaUserData==<br />
;clearAreaUserData(areaID)<br />
<br />
; Parameter<br />
* areaID - ID number for area to clear.<br />
<br />
:Clears all user data from a given area. Note that this will not touch the room user data.<br />
: See also: [[#setAreaUserData|setAreaUserData()]], [[#getAllAreaUserData|getAllAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#clearRoomUserData|clearRoomUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(clearAreaUserData(34))<br />
-- I did have data in that area, so it returns:<br />
true<br />
<br />
display(clearAreaUserData(34))<br />
-- There is no data NOW, so it returns:<br />
false<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==clearAreaUserDataItem==<br />
;clearAreaUserDataItem(areaID, key)<br />
<br />
:Removes the specific key and value from the user data from a given area.<br />
: See also: [[#setAreaUserData|setAreaUserData()]], [[#clearAreaUserData|clearAreaUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]]<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllAreaUserData(34))<br />
{<br />
description = [[<area description here>]],<br />
ruler = "Queen Morgase Trakand"<br />
}<br />
<br />
display(clearAreaUserDataItem(34,"ruler"))<br />
true<br />
<br />
display(getAllAreaUserData(34))<br />
{<br />
description = [[<area description here>]],<br />
}<br />
<br />
display(clearAreaUserDataItem(34,"ruler"))<br />
false<br />
</syntaxhighlight><br />
<br />
==clearMapUserData==<br />
;clearMapUserData()<br />
<br />
:Clears all user data stored for the map itself. Note that this will not touch the area or room user data.<br />
<br />
: See also: [[#setMapUserData|setMapUserData()]], [[#clearRoomUserData|clearRoomUserData()]], [[#clearAreaUserData|clearAreaUserData()]]<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(clearMapUserData())<br />
-- I did have user data stored for the map, so it returns:<br />
true<br />
<br />
display(clearMapUserData())<br />
-- There is no data NOW, so it returns:<br />
false<br />
</syntaxhighlight><br />
<br />
==clearMapUserDataItem==<br />
;clearMapUserDataItem(mapID, key)<br />
<br />
:Removes the specific key and value from the user data from the map user data.<br />
: See also: [[#setMapUserData|setMapUserData()]], [[#clearMapUserData|clearMapUserData()]], [[#clearAreaRoomUserData|clearAreaRoomUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllMapUserData())<br />
{<br />
description = [[<map description here>]],<br />
last_modified = "1483228799"<br />
}<br />
<br />
display(clearMapUserDataItem("last_modified"))<br />
true<br />
<br />
display(getAllMapUserData())<br />
{<br />
description = [[<map description here>]],<br />
}<br />
<br />
display(clearMapUserDataItem("last_modified"))<br />
false<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==clearRoomUserData==<br />
;clearRoomUserData(roomID)<br />
<br />
:Clears all user data from a given room.<br />
: See also: [[#setRoomUserData|setRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]]<br />
<br />
{{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.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(clearRoomUserData(3441))<br />
-- I did have data in that room, so it returns:<br />
true<br />
<br />
display(clearRoomUserData(3441))<br />
-- There is no data NOW, so it returns:<br />
false<br />
</syntaxhighlight><br />
<br />
==clearRoomUserDataItem==<br />
;clearRoomUserDataItem(roomID, key)<br />
<br />
:Removes the specific key and value from the user data from a given room.<br />
: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.<br />
: See also: [[#setRoomUserData|setRoomUserData()]], [[#clearRoomUserData|clearRoomUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllRoomUserData(3441))<br />
{<br />
description = [[<br />
From this ledge you can see out across a large cavern to the southwest. The<br />
east side of the cavern is full of stalactites and stalagmites and other<br />
weird rock formations. The west side has a path through it and an exit to the<br />
south. The sound of falling water pervades the cavern seeming to come from<br />
every side. There is a small tunnel to your east and a stalactite within arms<br />
reach to the south. It appears to have grown till it connects with the<br />
stalagmite below it. Something smells... Yuck you are standing in bat guano!]],<br />
doorname_up = "trapdoor"<br />
}<br />
<br />
display(clearRoomUserDataItem(3441,"doorname_up"))<br />
true<br />
<br />
display(getAllRoomUserData(3441))<br />
{<br />
description = [[<br />
From this ledge you can see out across a large cavern to the southwest. The<br />
east side of the cavern is full of stalactites and stalagmites and other<br />
weird rock formations. The west side has a path through it and an exit to the<br />
south. The sound of falling water pervades the cavern seeming to come from<br />
every side. There is a small tunnel to your east and a stalactite within arms<br />
reach to the south. It appears to have grown till it connects with the<br />
stalagmite below it. Something smells... Yuck you are standing in bat guano!]],<br />
}<br />
<br />
display(clearRoomUserDataItem(3441,"doorname_up"))<br />
false<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==clearSpecialExits==<br />
;clearSpecialExits(roomID) <br />
<br />
:Removes all special exits from a room.<br />
: See also: [[#addSpecialExit|addSpecialExit()]], [[#removeSpecialExit|removeSpecialExit()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
clearSpecialExits(1337)<br />
<br />
if #getSpecialExits(1337) == 0 then -- clearSpecialExits will never fail on a valid room ID, this is an example<br />
echo("All special exits successfully cleared from 1337.\n")<br />
end<br />
</syntaxhighlight><br />
<br />
==closeMapWidget==<br />
;closeMapWidget()<br />
:closes (hides) the map window (similar to clicking on the map icon)<br />
<br />
{{MudletVersion|4.7}}<br />
: See also: [[#openMapWidget|openMapWidget()]], [[#moveMapWidget|moveMapWidget()]], [[#resizeMapWidget|resizeMapWidget()]]<br />
<br />
==connectExitStub==<br />
;connectExitStub(fromID, direction) or connectExitStub(fromID, toID, [direction])<br />
<br />
: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.<br />
<br />
;Parameters<br />
* ''fromID:''<br />
: Room ID to set the exit stub in.<br />
* ''direction:''<br />
: 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").<br />
* ''toID:''<br />
: 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.<br />
<br />
: See also: [[#setExitStub|setExitStub()]], [[#getExitStubs|getExitStubs()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- try and connect all stubs that are in a room<br />
local stubs = getExitStubs(roomID)<br />
if stubs then<br />
for i,v in pairs(stubs) do<br />
connectExitStub(roomID, v)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==createMapLabel==<br />
;labelID = createMapLabel(areaID, text, posX, posY, posZ, fgRed, fgGreen, fgBlue, bgRed, bgGreen, bgBlue[, zoom, fontSize, showOnTop, noScaling, fontName, foregroundTransparency, backgroundTransparency, temporary])<br />
<br />
: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.<br />
<br />
: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.<br />
<br />
: See also: [[#getMapLabel|getMapLabel()]], [[#getMapLabels|getMapLabels()]], [[#deleteMapLabel|deleteMapLabel]], [[#createMapUmageLabel|createMapImageLabel()]]<br />
<br />
{{note}} Some changes were done prior to 4.13 (which exactly? function existed before!) - see corresponding PR and update here!<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID where to put the label.<br />
* ''text:''<br />
: The text to put into the label. To get a multiline text label add a '\n' between the lines.<br />
* ''posX, posY, posZ:''<br />
: Position of the label in (floating point numbers) room coordinates.<br />
* ''fgRed, fgGreen, fgBlue:''<br />
: Foreground color or text color of the label.<br />
* ''bgRed, bgGreen, bgBlue:''<br />
: Background color of the label.<br />
* ''zoom:''<br />
: (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.<br />
* ''fontSize:''<br />
: (optional, but needed if zoom is provided) Size of the font of the text. Default is 50.<br />
* ''showOnTop:''<br />
: (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.<br />
* ''noScaling:''<br />
: (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.<br />
* ''fontName:''<br />
: (optional) font name to use.<br />
* ''foregroundTransparency''<br />
: (optional) transparency of the text on the label, defaults to 255 (in range of 0 to 255) or fully opaque if not given.<br />
* ''backgroundTransparency''<br />
: (optional) transparency of the label background itself, defaults to 50 (in range of 0 to 255) or significantly transparent if not given.<br />
* ''temporary''<br />
: (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.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- the first 50 is some area id, the next three 0,0,0 are coordinates - middle of the area<br />
-- 255,0,0 would be the foreground in RGB, 23,0,0 would be the background RGB<br />
-- zoom is only relevant when when you're using a label of a static size, so we use 0<br />
-- and we use a font size of 20 for our label, which is a small medium compared to the map<br />
local labelid = createMapLabel( 50, "my map label", 0,0,0, 255,0,0, 23,0,0, 0,20)<br />
<br />
-- to create a multi line text label we add '\n' between lines<br />
-- the position is placed somewhat to the northeast of the center of the map<br />
-- this label will be scaled as you zoom the map.<br />
local labelid = createMapLabel( 50, "1. Row One\n2. Row 2", .5,5.5,0, 255,0,0, 23,0,0, 30,50, true, false)<br />
<br />
local x,y,z = getRoomCoordinates(getPlayerRoom())<br />
createMapLabel(getRoomArea(getPlayerRoom()), "my map label", x,y,z, 255,0,0, 23,0,0, 0,20, false, true, "Ubuntu", 255, 100)<br />
</syntaxhighlight><br />
<br />
==createMapImageLabel==<br />
;labelID = createMapImageLabel(areaID, filePath, posx, posy, posz, width, height, zoom, showOnTop[, temporary])<br />
<br />
: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.<br />
<br />
: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.<br />
: See also: [[#createMapLabel|createMapLabel]], [[#deleteMapLabel|deleteMapLabel]]<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
-- 138 is our pretend area ID<br />
-- next, inside [[]]'s, is the exact location of our image<br />
-- 0,0,0 are the x,y,z coordinates - so this will place it in the middle of the map<br />
-- 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<br />
-- 555 is the original height of the image<br />
-- 100 is how much we zoom it by, 1 would be no zoom<br />
-- false to make it go below our rooms<br />
-- (from 4.17.0) true to not save the label's image in the map file afterwards<br />
createMapImageLabel(138, [[/home/vadi/Pictures/You only see what shown.png]], 0,0,0, 482/100, 555/100, 100, false, true)<br />
</syntaxhighlight><br />
<br />
==createMapper==<br />
;createMapper([name of userwindow], x, y, width, height)<br />
<br />
: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.<br />
<br />
{{note}} ''name of userwindow'' available in Mudlet 4.6.1+<br />
<br />
{{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.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
createMapper(0,0,300,300) -- creates a 300x300 mapper in the top-left corner of Mudlet<br />
setBorderLeft(305) -- adds a border so text doesn't underlap the mapper display<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- another example:<br />
local main = Geyser.Container:new({x=0,y=0,width="100%",height="100%",name="mapper container"})<br />
<br />
local mapper = Geyser.Mapper:new({<br />
name = "mapper",<br />
x = "70%", y = 0, -- edit here if you want to move it<br />
width = "30%", height = "50%"<br />
}, main)<br />
</syntaxhighlight><br />
<br />
==createRoomID==<br />
;usableId = createRoomID([minimumStartingRoomId])<br />
<br />
: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. <br />
<br />
;Parameters<br />
* ''minimumStartingRoomId'' (optional, available in Mudlet 3.0+):<br />
: 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.<br />
<br />
: See also: [[#addRoom|addRoom()]]<br />
<br />
==deleteArea==<br />
;deleteArea(areaID or areaName)<br />
<br />
:Deletes the given area and all rooms in it. Returns ''true'' on success or ''nil'' + ''error message'' otherwise.<br />
: See also: [[#addAreaName|addAreaName()]]<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID to delete, or:<br />
* ''areaName'' (available in Mudlet 3.0+):<br />
: Area name to delete.<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- delete by areaID<br />
deleteArea(23)<br />
-- or since Mudlet 3.0, by area name<br />
deleteArea("Big city")<br />
</syntaxhighlight><br />
<br />
==deleteMap==<br />
;deleteMap()<br />
<br />
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.<br />
: See also: [[#loadMap|loadMap()]]<br />
<br />
{{MudletVersion|4.14.0}}<br />
<br />
;Returns<br />
:''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."''<br />
<br />
{{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.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
deleteMap()<br />
</syntaxhighlight><br />
<br />
==deleteMapLabel==<br />
;deleteMapLabel(areaID, labelID)<br />
<br />
:Deletes a map label from a specific area.<br />
: See also: [[#createMapLabel|createMapLabel()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
deleteMapLabel(50, 1)<br />
</syntaxhighlight><br />
<br />
==deleteRoom==<br />
;deleteRoom(roomID)<br />
<br />
:Deletes an individual room, and unlinks all exits leading to and from it.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
deleteRoom(335)<br />
</syntaxhighlight><br />
<br />
==disableMapInfo==<br />
;disableMapInfo(label)<br />
<br />
Disable the particular map info - same as toggling off checkbox from select box under mapper.<br />
<br />
;Parameters<br />
* ''label:''<br />
: Name under which map info to be disabled was registered.<br />
<br />
: See also: [[#registerMapInfo|registerMapInfo()]], [[#enableMapInfo|enableMapInfo()]], [[#killMapInfo|killMapInfo()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
==enableMapInfo==<br />
;enableMapInfo(label)<br />
<br />
Enable the particular map info - same as toggling on checkbox from select box under mapper.<br />
<br />
;Parameters<br />
* ''label:''<br />
: Name under which map info to be enabled was registered.<br />
<br />
: See also: [[#registerMapInfo|registerMapInfo()]], [[#disableMapInfo|disableMapInfo()]], [[#killMapInfo|killMapInfo()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
==getAllAreaUserData==<br />
;dataTable = getAllAreaUserData(areaID)<br />
<br />
: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.<br />
<br />
: See also: [[#clearAreaUserData|clearAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#searchAreaUserData|searchAreaUserData()]], [[#setAreaUserData|setAreaUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllAreaUserData(34))<br />
--might result in:--<br />
{<br />
country = "Andor",<br />
ruler = "Queen Morgase Trakand"<br />
}<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==getAllMapUserData==<br />
;dataTable = getAllMapUserData()<br />
<br />
:Returns all the user data items stored at the map level; will return an empty table if there is no data stored.<br />
<br />
: See also: [[#getMapUserData|getMapUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllMapUserData())<br />
--might result in:--<br />
{<br />
description = [[This map is about so and so game]],<br />
author = "Bob",<br />
["last updated"] = "December 5, 2020"<br />
}<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==getAllRoomEntrances==<br />
;exitsTable = getAllRoomEntrances(roomID)<br />
<br />
: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.<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- print the list of rooms that have exits leading into room 512<br />
for _, roomid in ipairs(getAllRoomEntrances(512)) do <br />
print(roomid)<br />
end<br />
</syntaxhighlight><br />
<br />
: See also: [[#getRoomExits|getRoomExits()]]<br />
<br />
==getAllRoomUserData==<br />
;dataTable = getAllRoomUserData(roomID)<br />
<br />
: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!''<br />
<br />
;See also: [[#getRoomUserDataKeys|getRoomUserDataKeys()]] - for a related command that only returns the data keys.<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAllRoomUserData(3441))<br />
--might result in:--<br />
{<br />
description = [[<br />
From this ledge you can see out across a large cavern to the southwest. The<br />
east side of the cavern is full of stalactites and stalagmites and other<br />
weird rock formations. The west side has a path through it and an exit to the<br />
south. The sound of falling water pervades the cavern seeming to come from<br />
every side. There is a small tunnel to your east and a stalactite within arms<br />
reach to the south. It appears to have grown till it connects with the<br />
stalagmite below it. Something smells... Yuck you are standing in bat guano!]],<br />
doorname_up = "trapdoor"<br />
}<br />
</syntaxhighlight><br />
<br />
==getAreaExits==<br />
;roomTable = getAreaExits(areaID, showExits)<br />
<br />
: 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.<br />
<br />
;See also: [[#setExit|setExit()]], [[#getRoomExits|getRoomExits()]]<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID to list the exits for.<br />
* ''showExits:''<br />
: Boolean argument, if true then the exits that lead out to another area will be listed for each room.<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- list all border rooms for area 44:<br />
getAreaExits(44)<br />
<br />
-- returns:<br />
--[[<br />
{<br />
7091,<br />
10659,<br />
11112,<br />
11122,<br />
11133,<br />
11400,<br />
12483,<br />
24012<br />
}<br />
]]<br />
<br />
-- list all border rooms for area 44, and the exits within them that go out to other areas:<br />
getAreaExits(44, true)<br />
--[[<br />
{<br />
[12483] = {<br />
north = 27278<br />
},<br />
[11122] = {<br />
["enter grate"] = 14551<br />
},<br />
[11112] = {<br />
["enter grate"] = 14829<br />
},<br />
[24012] = {<br />
north = 22413<br />
},<br />
[11400] = {<br />
south = 10577<br />
},<br />
[11133] = {<br />
["enter grate"] = 15610<br />
},<br />
[7091] = {<br />
down = 4411<br />
},<br />
[10659] = {<br />
["enter grate"] = 15510<br />
}<br />
}<br />
]]<br />
</syntaxhighlight><br />
<br />
==getAreaRooms==<br />
;getAreaRooms(area id)<br />
<br />
:Returns an indexed table with all rooms IDs for a given area ID (room IDs are values), or ''nil'' if no such area exists. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- using the sample findAreaID() function defined in the getAreaTable() example, <br />
-- we'll define a function that echo's us a nice list of all rooms in an area with their ID<br />
function echoRoomList(areaname)<br />
local id, msg = findAreaID(areaname)<br />
if id then<br />
local roomlist, endresult = getAreaRooms(id), {}<br />
<br />
-- obtain a room list for each of the room IDs we got<br />
for _, id in pairs(roomlist) do<br />
endresult[id] = getRoomName(id)<br />
end<br />
<br />
-- now display something half-decent looking<br />
cecho(string.format(<br />
"List of all rooms in %s (%d):\n", msg, table.size(endresult)))<br />
<br />
for roomid, roomname in pairs(endresult) do<br />
cecho(string.format(<br />
"%6s: %s\n", roomid, roomname))<br />
end<br />
elseif not id and msg then<br />
echo("ID not found; " .. msg)<br />
else<br />
echo("No areas matched the query.")<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==getAreaTable==<br />
;areaTable = getAreaTable()<br />
<br />
:Returns a key(area name)-value(area id) table with all known areas and their IDs. <br />
{{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.<br />
<br />
;See also: [[#getAreaTableSwap|getAreaTableSwap()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- example function that returns the area ID for a given area<br />
<br />
function findAreaID(areaname)<br />
local list = getAreaTable()<br />
<br />
-- iterate over the list of areas, matching them with substring match. <br />
-- if we get match a single area, then return it's ID, otherwise return<br />
-- 'false' and a message that there are than one are matches<br />
local returnid, fullareaname<br />
for area, id in pairs(list) do<br />
if area:find(areaname, 1, true) then<br />
if returnid then return false, "more than one area matches" end<br />
returnid = id; fullareaname = area<br />
end<br />
end<br />
<br />
return returnid, fullareaname<br />
end<br />
<br />
-- sample use:<br />
local id, msg = findAreaID("blahblah")<br />
if id then<br />
echo("Found a matching ID: " .. id)<br />
elseif not id and msg then<br />
echo("ID not found: " .. msg)<br />
else<br />
echo("No areas matched the query.")<br />
end<br />
</syntaxhighlight><br />
<br />
==getAreaTableSwap==<br />
;areaTable = getAreaTableSwap()<br />
<br />
: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. <br />
{{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.<br />
<br />
==getAreaUserData==<br />
;dataValue = getAreaUserData(areaID, key)<br />
<br />
: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.) <br />
<br />
: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.<br />
<br />
;See also: [[#clearAreaUserData|clearAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#getAllAreaUserData|getAllAreaUserData()]], [[#searchAreaUserData|searchAreaUserData()]], [[#setAreaUserData|setAreaUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getAreaUserData(34, "country"))<br />
-- might produce --<br />
"Andor"<br />
</syntaxhighlight><br />
<br />
==getCustomEnvColorTable==<br />
;envcolors = getCustomEnvColorTable()<br />
<br />
:Returns a table with customized environments, where the key is the environment ID and the value is a indexed table of rgb values.<br />
: See also: [[#setCustomEnvColor|setCustomEnvColor()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
{<br />
envid1 = {r, g, b, alpha},<br />
envid2 = {r, g, b, alpha}<br />
}<br />
</syntaxhighlight><br />
<br />
==getCustomLines==<br />
;lineTable = getCustomLines(roomID)<br />
: See also: [[#addCustomLine|addCustomLine()]], [[#removeCustomLine|removeCustomLine()]]<br />
<br />
:Returns a table including all the details of the custom exit lines, if any, for the room with the id given.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to return the custom line details of.<br />
<br />
{{MudletVersion|3.0.}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display getCustomLines(1)<br />
{<br />
["climb Rope"] = {<br />
attributes = {<br />
color = {<br />
b = 0,<br />
g = 128,<br />
r = 128<br />
},<br />
style = "dash dot dot line",<br />
arrow = false<br />
},<br />
points = {<br />
{<br />
y = 9.5,<br />
x = 4.5<br />
},<br />
{<br />
y = 9.5,<br />
x = 6<br />
},<br />
[0] = {<br />
y = 5.5,<br />
x = 4.5<br />
}<br />
}<br />
},<br />
N = {<br />
attributes = {<br />
color = {<br />
b = 255,<br />
g = 255,<br />
r = 0<br />
},<br />
style = "dot line",<br />
arrow = true<br />
},<br />
points = {<br />
[0] = {<br />
y = 27,<br />
x = -3<br />
}<br />
}<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
==getCustomLines1==<br />
;lineTable = getCustomLines1(roomID)<br />
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.<br />
:See also: [[Manual:Mapper_Functions#addCustomLine|addCustomLine()]], [[Manual:Mapper_Functions#removeCustomLine|removeCustomLine()]], [[Manual:Mapper_Functions#getCustomLines|getCustomLines()]]<br />
{{MudletVersion| 4.16}}<br />
<br />
;Parameters<br />
* ''roomID:''<br />
:Room ID to return the custom line details of.<br />
<br />
;Returns<br />
:a table including all the details of the custom exit lines, if any, for the room with the id given.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display getCustomLines1(1)<br />
{<br />
["climb Rope"] = {<br />
attributes = {<br />
color = { 128, 128, 0 },<br />
style = "dash dot dot line",<br />
arrow = false<br />
},<br />
points = { { 4.5, 5.5, 3 }, { 4.5, 9.5, 3 }, { 6, 9.5, 3 } } <br />
},<br />
N = {<br />
attributes = {<br />
color = { 0, 255, 255 },<br />
style = "dot line",<br />
arrow = true<br />
},<br />
points = { { -3, 27, 3 } }<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
==getDoors==<br />
;doors = getDoors(roomID)<br />
<br />
: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.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to check for doors in.<br />
<br />
: See also: [[#setDoor|setDoor()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- an example that displays possible doors in room 2334<br />
local doors = getDoors(2334)<br />
<br />
if not next(doors) then cecho("\nThere aren't any doors in room 2334.") return end<br />
<br />
local door_status = {"open", "closed", "locked"}<br />
<br />
for direction, door in pairs(doors) do<br />
cecho("\nThere's a door leading in "..direction.." that is "..door_status[door]..".")<br />
end<br />
</syntaxhighlight><br />
<br />
==getExitStubs==<br />
;stubs = getExitStubs(roomid)<br />
<br />
: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.<br />
<br />
: See also: [[#setExitStub|setExitStub()]], [[#connectExitStub|connectExitStub()]], [[#getExitStubs1|getExitStubs1()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- show the exit stubs in room 6 as numbers<br />
local stubs = getExitStubs(6)<br />
for i = 0, #stubs do print(stubs[i]) end<br />
</syntaxhighlight><br />
<br />
{{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.<br />
<br />
==getExitStubs1==<br />
;stubs = getExitStubs1(roomid)<br />
<br />
: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.<br />
<br />
; See also: [[#getExitStubs|getExitStubs()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- show the exit stubs in room 6 as numbers<br />
for k,v in ipairs(getExitStubs1(6)) do print(k,v) end<br />
</syntaxhighlight><br />
<br />
==getExitWeights==<br />
;weights = getExitWeights(roomid)<br />
<br />
: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.<br />
<br />
;Parameters<br />
* ''roomid:''<br />
: Room ID to view the exit weights in.<br />
<br />
: See also: [[#setExitWeight|setExitWeight()]]<br />
<br />
==getGridMode==<br />
;TrueOrFalse = getGridMode(areaID)<br />
<br />
: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.<br />
<br />
{{MudletVersion|3.11}}<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID (number) to view the grid mode of.<br />
<br />
: See also: [[#setGridMode|setGridMode()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
getGridMode(55)<br />
-- will return: false<br />
setGridMode(55, true) -- set area with ID 55 to be in grid mode<br />
getGridMode(55)<br />
-- will return: true<br />
</syntaxhighlight><br />
<br />
==getMapEvents==<br />
; mapevents = getMapEvents()<br />
<br />
: 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()''.<br />
: See also: [[#addMapMenu|addMapMenu()]], [[#removeMapEvent|removeMapEvent()]], [[#addMapEvent|addMapEvent()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addMapEvent("room a", "onFavorite") -- will make a label "room a" on the map menu's right click that calls onFavorite<br />
<br />
addMapEvent("room b", "onFavorite", "Favorites", "Special Room!", 12345, "arg1", "arg2", "argn")<br />
<br />
local mapEvents = getMapEvents()<br />
for _, event in ipairs(mapEvents) do<br />
echo(string.format("MapEvent '%s' is bound to event '%s' with these args: '%s'", event["uniquename"], event["event name"], table.concat(event["arguments"], ",")))<br />
end<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.3}}<br />
<br />
==getMapLabel==<br />
;labelinfo = getMapLabel(areaID, labelID or labelText)<br />
<br />
: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.<br />
<br />
:''BgColor'' and ''FgColor'' are tables with ''r'',''g'',''b'' keys, each holding ''0-255'' color component value.<br />
<br />
:''Pixmap'' is base64 encoded image of label.<br />
<br />
{{note}} ''BgColor'', ''FgColor'', ''Pixmap'' are available in Mudlet 4.11+<br />
<br />
;Parameters <br />
* ''areaID:'' areaID from which to retrieve label<br />
* ''labelID:'' labelID (''getMapLabels'' return table key) or labelText (exact match)<br />
<br />
See also: [[#createMapLabel|createMapLabel()]], [[#getMapLabels|getMapLabels()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lua getMapLabels(52)<br />
{<br />
"no text",<br />
[0] = "test"<br />
}<br />
<br />
lua getMapLabel(52, 0)<br />
{<br />
Y = -2,<br />
X = -8,<br />
Z = 11,<br />
Height = 3.9669418334961,<br />
Text = "test",<br />
Width = 8.6776866912842,<br />
BgColor = {<br />
b = 0,<br />
g = 0,<br />
r = 0<br />
},<br />
FgColor = {<br />
b = 50,<br />
g = 255,<br />
r = 255<br />
},<br />
Pixmap = "iVBORw0KG(...)lFTkSuQmCC" -- base64 encoded png image (shortened for brevity)<br />
}<br />
<br />
lua getMapLabel(52, "no text")<br />
{<br />
Y = 8,<br />
X = -15,<br />
Z = 11,<br />
Height = 7.2520666122437,<br />
Text = "no text"<br />
Width = 11.21900844574,<br />
BgColor = {<br />
b = 0,<br />
g = 0,<br />
r = 0<br />
},<br />
FgColor = {<br />
b = 50,<br />
g = 255,<br />
r = 255<br />
},<br />
Pixmap = "iVBORw0KG(...)lFTkSuQmCC" -- base64 encoded png image (shortened for brevity)<br />
}<br />
</syntaxhighlight><br />
<br />
==getMapLabels==<br />
;arealabels = getMapLabels(areaID)<br />
<br />
: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.<br />
:If there are no labels in the area at all, it will return an empty table.<br />
<br />
: See also: [[#createMapLabel|createMapLabel()]], [[#getMapLabel|getMapLabel()]], [[#deleteMapLabel|deleteMapLabel()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getMapLabels(43))<br />
table {<br />
0: ''<br />
1: 'Waterways'<br />
}<br />
<br />
deleteMapLabel(43, 0)<br />
display(getMapLabels(43))<br />
table {<br />
1: 'Waterways'<br />
}<br />
</syntaxhighlight><br />
<br />
==getMapMenus==<br />
;getMapMenus()<br />
<br />
: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>.<br />
: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.<br />
<br />
: See also: [[#addMapMenu|addMapMenu()]], [[#addMapEvent|addMapEvent()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- given the following menu structure:<br />
top-level<br />
menu1<br />
menu1.1<br />
action1.1.1<br />
menu1.2<br />
action1.2.1<br />
menu2<br />
<br />
getMapMenus() -- will return:<br />
{<br />
menu2 = "top-level",<br />
menu1.2 = "menu1",<br />
menu1.1 = "menu1",<br />
menu1 = "top-level"<br />
}<br />
</syntaxhighlight><br />
<br />
==getMapSelection==<br />
; getMapSelection()<br />
<br />
:Returns a table containing details of the current mouse selection in the 2D mapper.<br />
<br />
:Reports on one or more rooms being selected (i.e. they are highlighted in orange).<br />
<br />
: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.<br />
<br />
; Example - several rooms selected<br />
<syntaxhighlight lang="lua"><br />
display(getMapSelection())<br />
{<br />
center = 5013,<br />
rooms = {<br />
5011,<br />
5012,<br />
5013,<br />
5014,<br />
5018,<br />
5019,<br />
5020<br />
}<br />
}<br />
</syntaxhighlight><br />
; Example - one room selected<br />
<syntaxhighlight lang="lua"><br />
display(getMapSelection())<br />
{<br />
center = 5013,<br />
rooms = {<br />
5013<br />
}<br />
}<br />
</syntaxhighlight><br />
; Example - no or something other than a room selected<br />
<syntaxhighlight lang="lua"><br />
display(getMapSelection())<br />
{<br />
}<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.17}}<br />
<br />
==getMapUserData==<br />
;getMapUserData( key )<br />
<br />
;Parameters<br />
* ''key:''<br />
: string used as a key to select the data stored in the map as a whole.<br />
<br />
: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.<br />
<br />
: See also: [[#getAllMapUserData|getAllMapUserData()]], [[#setMapUserData|setMapUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getMapUserData("last updated"))<br />
--might result in:--<br />
"December 5, 2020"<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==getPath==<br />
;getPath(roomID from, roomID to)<br />
<br />
: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.<br />
<br />
<br />
: See also: [[Manual:Lua_Functions#translateTable|translateTable()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- check if we can go to room 155 from room 34 - if yes, go to it<br />
if getPath(34,155) then<br />
gotoRoom(155)<br />
else<br />
echo("\nCan't go there!")<br />
end<br />
</syntaxhighlight><br />
<br />
==getPlayerRoom==<br />
;getPlayerRoom()<br />
<br />
:Returns the current player location as set by [[#centerview|centerview()]].<br />
<br />
: See also: [[#centerview|centerview]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display("We're currently in " .. getRoomName(getPlayerRoom()))<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.14}}<br />
<br />
==getRoomArea==<br />
;getRoomArea(roomID)<br />
<br />
: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.<br />
<br />
{{note}} If the room ID does not exist, this function will raise an error.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display("Area ID of room #100 is: "..getRoomArea(100))<br />
<br />
display("Area name for room #100 is: "..getRoomAreaName(getRoomArea(100)))<br />
</syntaxhighlight><br />
<br />
==getRoomAreaName==<br />
;getRoomAreaName(areaID or areaName)<br />
<br />
:Returns the area name for a given area id; or the area id for a given area name.<br />
<br />
{{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.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo(string.format("room id #455 is in %s.", getRoomAreaName(getRoomArea(455))))<br />
</syntaxhighlight><br />
<br />
<br />
==getRoomChar==<br />
;getRoomChar(roomID)<br />
<br />
:Returns the single ASCII character that forms the ''symbol'' for the given room id.<br />
<br />
: '''Since Mudlet version 3.8 :''' this facility has been extended:<br />
: 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.<br />
<br />
==getRoomCharColor==<br />
;r,g,b = getRoomCharColor(roomID)<br />
<br />
:Returns the color of the Room Character as a set of r,g,b color coordinates.<br />
<br />
;See also: [[Manual:Lua_Functions#setRoomCharColor|setRoomCharColor()]], [[Manual:Lua_Functions#getRoomChar|getRoomChar()]]<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: The room ID to get the room character color from<br />
<br />
;Returns <br />
* The color as 3 separate numbers, red, green, and blue from 0-255<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- gets the color of the room character set on room 12345. If no room character is set the default 'color' is 0,0,0<br />
local r,g,b = getRoomCharColor(12345)<br />
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>.\")<br />
</syntaxhighlight><br />
<br />
==getRoomCoordinates==<br />
;x,y,z = getRoomCoordinates(roomID)<br />
<br />
:Returns the room coordinates of the given room ID.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local x,y,z = getRoomCoordinates(roomID)<br />
echo("Room Coordinates for "..roomID..":")<br />
echo("\n X:"..x)<br />
echo("\n Y:"..y)<br />
echo("\n Z:"..z)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- 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.<br />
function sortByZ(areaID, zval)<br />
local area = getAreaRooms(areaID)<br />
local t = {}<br />
for _, id in ipairs(area) do<br />
local _, _, z = getRoomCoordinates(id)<br />
if z == zval then<br />
table.insert(t, id)<br />
end<br />
end<br />
return t<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomEnv==<br />
;envID = getRoomEnv(roomID)<br />
<br />
: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.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
funtion checkID(id)<br />
echo(string.format("The env ID of room #%d is %d.\n", id, getRoomEnv(id)))<br />
end<br />
</syntaxhighlight><br />
<br />
== getRoomExits ==<br />
;getRoomExits (roomID)<br />
:Returns the currently known non-special exits for a room in an key-index form: ''exit = exitroomid''.<br />
<br />
: See also: [[#getSpecialExits|getSpecialExits()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
table {<br />
'northwest': 80<br />
'east': 78<br />
}<br />
</syntaxhighlight><br />
<br />
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):<br />
<br />
<syntaxhighlight lang="lua"><br />
local exits = getRoomExits(mycurrentroomid)<br />
for direction,num in pairs(exits) do<br />
local env_num = getRoomEnv(num)<br />
if env_num == 22 or env_num == 20 or env_num == 30 then<br />
print("There's water to the "..direction.."!")<br />
end<br />
end</syntaxhighlight><br />
<br />
==getRoomHashByID==<br />
;getRoomHashByID(roomID)<br />
<br />
: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.<br />
<br />
: See also: [[#getRoomIDbyHash|getRoomIDbyHash()]]<br />
{{MudletVersion|3.13.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
for id,name in pairs(getRooms()) do<br />
local h = getRoomUserData(id, "herbs")<br />
if h ~= "" then<br />
echo(string.format([[["%s"] = "%s",]], getRoomHashByID(id), h))<br />
echo("\n")<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomIDbyHash==<br />
;roomID = getRoomIDbyHash(hash)<br />
<br />
: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.<br />
<br />
: See also: [[#getRoomHashByID|getRoomHashByID()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- example taken from http://forums.mudlet.org/viewtopic.php?f=13&t=2177<br />
local id = getRoomIDbyHash("5dfe55b0c8d769e865fd85ba63127fbc")<br />
if id == -1 then <br />
id = createRoomID()<br />
setRoomIDbyHash(id, "5dfe55b0c8d769e865fd85ba63127fbc")<br />
addRoom(id)<br />
setRoomCoordinates(id, 0, 0, -1)<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomName==<br />
;getRoomName(roomID)<br />
<br />
:Returns the room name for a given room id.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo(string.format("The name of the room id #455 is %s.", getRoomName(455))<br />
</syntaxhighlight><br />
<br />
==getRooms==<br />
;rooms = getRooms()<br />
<br />
:Returns the list of '''all''' rooms in the map in the whole map in roomid - room name format.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- simple, raw viewer for rooms in the world<br />
display(getRooms())<br />
<br />
-- iterate over all rooms in code<br />
for id,name in pairs(getRooms()) do<br />
print(id, name)<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomsByPosition==<br />
;roomTable = getRoomsByPosition(areaID, x,y,z)<br />
<br />
: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.<br />
<br />
{{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.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- sample alias to determine a room nearby, given a relative direction from the current room<br />
<br />
local otherroom<br />
if matches[2] == "" then<br />
local w = matches[3]<br />
local ox, oy, oz, x,y,z = getRoomCoordinates(mmp.currentroom)<br />
local has = table.contains<br />
if has({"west", "left", "w", "l"}, w) then<br />
x = (x or ox) - 1; y = (y or oy); z = (z or oz)<br />
elseif has({"east", "right", "e", "r"}, w) then<br />
x = (x or ox) + 1; y = (y or oy); z = (z or oz)<br />
elseif has({"north", "top", "n", "t"}, w) then<br />
x = (x or ox); y = (y or oy) + 1; z = (z or oz)<br />
elseif has({"south", "bottom", "s", "b"}, w) then<br />
x = (x or ox); y = (y or oy) - 1; z = (z or oz)<br />
elseif has({"northwest", "topleft", "nw", "tl"}, w) then<br />
x = (x or ox) - 1; y = (y or oy) + 1; z = (z or oz)<br />
elseif has({"northeast", "topright", "ne", "tr"}, w) then<br />
x = (x or ox) + 1; y = (y or oy) + 1; z = (z or oz)<br />
elseif has({"southeast", "bottomright", "se", "br"}, w) then<br />
x = (x or ox) + 1; y = (y or oy) - 1; z = (z or oz)<br />
elseif has({"southwest", "bottomleft", "sw", "bl"}, w) then<br />
x = (x or ox) - 1; y = (y or oy) - 1; z = (z or oz)<br />
elseif has({"up", "u"}, w) then<br />
x = (x or ox); y = (y or oy); z = (z or oz) + 1<br />
elseif has({"down", "d"}, w) then<br />
x = (x or ox); y = (y or oy); z = (z or oz) - 1<br />
end<br />
<br />
local carea = getRoomArea(mmp.currentroom)<br />
if not carea then mmp.echo("Don't know what area are we in.") return end<br />
<br />
otherroom = select(2, next(getRoomsByPosition(carea,x,y,z)))<br />
<br />
if not otherroom then<br />
mmp.echo("There isn't a room to the "..w.." that I see - try with an exact room id.") return<br />
else<br />
mmp.echo("The room "..w.." of us has an ID of "..otherroom)<br />
end<br />
</syntaxhighlight><br />
<br />
==getRoomUserData==<br />
;getRoomUserData(roomID, key)<br />
<br />
: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.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getRoomUserData(341, "visitcount"))<br />
</syntaxhighlight><br />
<br />
:;getRoomUserData(roomID, key, enableFullErrorReporting)<br />
<br />
::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.<br />
<br />
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserDataKeys|getRoomUserDataKeys()]], [[#searchRoomUserData|searchRoomUserData()]], [[#setRoomUserData|setRoomUserData()]]<br />
<br />
;Example<br />
<!-- 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<br />
if the start of the code line begins: ":<lua>..."--><br />
<syntaxhighlight lang="lua">local vNum = 341<br />
result, errMsg = getRoomUserData(vNum, "visitcount", true)<br />
if result ~= nil then<br />
display(result)<br />
else<br />
echo("\nNo visitcount data for room: "..vNum.."; reason: "..errMsg.."\n")<br />
end</syntaxhighlight><br />
<br />
==getRoomUserDataKeys==<br />
;getRoomUserDataKeys(roomID)<br />
<br />
: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!''<br />
<br />
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserData|getRoomUserData()]], [[#searchRoomUserData|searchRoomUserData()]], [[#setRoomUserData|setRoomUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getRoomUserDataKeys(3441))<br />
--might result in:--<br />
{<br />
"description",<br />
"doorname_up",<br />
}<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
==getRoomWeight==<br />
;getRoomWeight(roomID)<br />
<br />
:Returns the weight of a room. By default, all new rooms have a weight of 1.<br />
: See also: [[#setRoomWeight|setRoomWeight()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display("Original weight of room 541: "..getRoomWeight(541))<br />
setRoomWeight(541, 3)<br />
display("New weight of room 541: "..getRoomWeight(541))<br />
</syntaxhighlight><br />
<br />
==getSpecialExits==<br />
;exits = getSpecialExits(roomID[, listAllExits])<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to return the special exits of.<br />
* ''listAllExits:''<br />
: (Since ''TBA'') In the case where there is more than one special exit to the same room ID list all of them.<br />
<br />
: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.<br />
: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.<br />
<br />
: See also: [[#getRoomExits|getRoomExits()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- There are three special exits from 1337 to the room 42:<br />
-- "climb down ladder" which is locked and has an exit weight of 10<br />
-- "step out window" which is unlocked and has an exit weight of 20<br />
-- "jump out window" which is unlocked and has an exit weight of 990<br />
getSpecialExits(1337)<br />
<br />
-- In 4.10.1 and before this could results in:<br />
table {<br />
42 = {"jump out window" = "0"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
-- OR<br />
table {<br />
42 = {"climb down ladder" = "1"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
-- OR<br />
table {<br />
42 = {"step out window" = "0"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
<br />
-- From TBA this will return:<br />
table {<br />
42 = {"step out window" = "0"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
<br />
-- From TBA, with the second argument as true, this gives:<br />
getSpecialExits(1337, true)<br />
table {<br />
42 = {"step out window" = "0",<br />
"climb down ladder" = "1",<br />
"jump out window" = "0"},<br />
666 = {"dive into pit" = "1"}<br />
}<br />
</syntaxhighlight><br />
<br />
==getSpecialExitsSwap==<br />
;getSpecialExitsSwap(roomID)<br />
<br />
:Very similar to [[#getSpecialExits|getSpecialExits()]] function, but returns the rooms in the command - roomid style.<br />
<br />
==gotoRoom==<br />
;gotoRoom (roomID)<br />
: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 :(".<br />
<br />
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.<br />
<br />
==hasExitLock==<br />
;status = hasExitLock(roomID, direction)<br />
<br />
: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").<br />
<br />
; Example<br />
<syntaxhighlight lang="lua"><br />
-- check if the east exit of room 1201 is locked<br />
display(hasExitLock(1201, 4))<br />
display(hasExitLock(1201, "e"))<br />
display(hasExitLock(1201, "east"))<br />
</syntaxhighlight><br />
<br />
: See also: [[#lockExit|lockExit()]]<br />
<br />
==hasSpecialExitLock==<br />
;hasSpecialExitLock(from roomID, to roomID, moveCommand)<br />
<br />
: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.<br />
<br />
See also: [[#lockSpecialExit|lockSpecialExit()]]<br />
<br />
<syntaxhighlight lang="lua"><br />
-- lock a special exit from 17463 to 7814 that uses the 'enter feather' command<br />
lockSpecialExit(17463, 7814, 'enter feather', true)<br />
<br />
-- see if it is locked: it will say 'true', it is<br />
display(hasSpecialExitLock(17463, 7814, 'enter feather'))<br />
</syntaxhighlight><br />
<br />
==highlightRoom==<br />
;highlightRoom( roomID, color1Red, color1Green, color1Blue, color2Red, color2Green, color2Blue, highlightRadius, color1Alpha, color2Alpha)<br />
<br />
: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. <br />
<br />
;Parameters<br />
* ''roomID''<br />
: ID of the room to be colored.<br />
* ''color1Red, color1Green, color1Blue''<br />
: RGB values of the first color.<br />
* ''color2Red, color2Green, color2Blue''<br />
: RGB values of the second color.<br />
* ''highlightRadius'' <br />
: The radius for the highlight circle - if you don't want rooms beside each other to overlap, use ''1'' as the radius. <br />
* ''color1Alpha'' and ''color2Alpha'' <br />
: Transparency values from 0 (completely transparent) to 255 (not transparent at all).<br />
<br />
: See also: [[#unHighlightRoom|unHighlightRoom()]]<br />
<br />
<syntaxhighlight lang="lua"><br />
-- color room #351 red to blue<br />
local r,g,b = unpack(color_table.red)<br />
local br,bg,bb = unpack(color_table.blue)<br />
highlightRoom(351, r,g,b,br,bg,bb, 1, 255, 255)<br />
</syntaxhighlight><br />
<br />
==killMapInfo==<br />
;killMapInfo(label)<br />
<br />
Delete a map info contributor entirely - it will be not available anymore.<br />
<br />
;Parameters<br />
* ''label:''<br />
: Name under which map info to be removed was registered.<br />
<br />
: See also: [[#registerMapInfo|registerMapInfo()]], [[#enableMapInfo|enableMapInfo()]], [[#disableMapInfo|disableMapInfo()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
==loadJsonMap==<br />
; loadJsonMap(pathFileName)<br />
<br />
; Parameters:<br />
<br />
* ''pathFileName'' a string that is an absolute path and file name to read the data from.<br />
<br />
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.<br />
<br />
: See also: [[#saveJsonMap|saveJsonMap()]]<br />
<br />
Returns:<br />
* ''true'' on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
loadJsonMap(getMudletHomeDir() .. "/map.json")<br />
<br />
true<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.11.0}}<br />
<br />
==loadMap==<br />
;loadMap(file location)<br />
<br />
: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. <br />
<br />
:Returns a boolean for whenever the loading succeeded. Note that the mapper must be open, or this will fail.<br />
<br />
:Using no arguments will load the last saved map.<br />
<br />
<syntaxhighlight lang="lua"><br />
loadMap("/home/user/Desktop/Mudlet Map.dat")<br />
</syntaxhighlight><br />
<br />
{{Note}} A file name ending with <code>.xml</code> will indicate the XML format.<br />
<br />
==lockExit==<br />
;lockExit(roomID, direction, lockIfTrue)<br />
<br />
: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").<br />
<br />
: See also: [[#hasExitLock|hasExitLock()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- lock the east exit of room 1201 so we never path through it<br />
lockExit(1201, 4, true)<br />
</syntaxhighlight><br />
<br />
==lockRoom==<br />
;lockRoom (roomID, lockIfTrue)<br />
<br />
:Locks a given room id from future speed walks (thus the mapper will never path through that room).<br />
: See also: [[#roomLocked | roomLocked()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lockRoom(1, true) -- locks a room if from being walked through when speedwalking.<br />
lockRoom(1, false) -- unlocks the room, adding it back to possible rooms that can be walked through.<br />
</syntaxhighlight><br />
<br />
==lockSpecialExit==<br />
;lockSpecialExit (from roomID, to roomID, special exit command, lockIfTrue)<br />
<br />
: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).<br />
: See also: [[#hasSpecialExitLock | hasSpecialExitLock()]], [[#lockExit | lockExit()]], [[#lockRoom | lockRoom()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lockSpecialExit(1,2,'enter gate', true) -- locks the special exit that does 'enter gate' to get from room 1 to room 2<br />
lockSpecialExit(1,2,'enter gate', false) -- unlocks the said exit<br />
</syntaxhighlight><br />
<br />
==moveMapWidget==<br />
;moveMapWidget(Xpos, Ypos)<br />
:moves the map window to the given position.<br />
: See also: [[#openMapWidget|openMapWidget()]], [[#closeMapWidget|closeMapWidget()]], [[#resizeMapWidget|resizeMapWidget()]]<br />
<br />
;Parameters<br />
* ''Xpos:''<br />
: X position of the map window. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''Ypos:''<br />
: Y position of the map window. Measured in pixels, with 0 being the very top. Passed as an integer number.<br />
<br />
{{MudletVersion|4.7}}<br />
<br />
==openMapWidget==<br />
;openMapWidget([dockingArea | Xpos, Ypos, width, height])<br />
means either of these are fine:<br />
;openMapWidget()<br />
;openMapWidget(dockingArea)<br />
;openMapWidget(Xpos, Ypos, width, height)<br />
<br />
:opens a map window with given options.<br />
<br />
: See also: [[#closeMapWidget|closeMapWidget()]], [[#moveMapWidget|moveMapWidget()]], [[#resizeMapWidget|resizeMapWidget()]]<br />
<br />
{{MudletVersion|4.7}}<br />
<br />
;Parameters<br />
{{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)<br />
* ''dockingArea:''<br />
: 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)<br />
{{note}} If 4 parameters are given the map window will be created in floating state <br />
* ''Xpos:''<br />
: X position of the map window. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''Ypos:''<br />
: Y position of the map window. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''width:''<br />
: The width map window, in pixels. Passed as an integer number.<br />
* ''height:''<br />
: The height map window, in pixels. Passed as an integer number.<br />
<br />
==pauseSpeedwalk==<br />
;pauseSpeedwalk()<br />
<br />
:Pauses a speedwalk started using [[#speedwalk|speedwalk()]]<br />
<br />
: See also: [[#speedwalk|speedwalk()]], [[#stopSpeedwalk|stopSpeedwalk()]], [[#resumeSpeedwalk|resumeSpeedwalk()]]<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
<syntaxhighlight lang="lua"><br />
local ok, err = pauseSpeedwalk()<br />
if not ok then<br />
debugc(f"Error: unable to pause speedwalk because {err}\n")<br />
return<br />
end<br />
</syntaxhighlight><br />
<br />
==registerMapInfo==<br />
;registerMapInfo(label, function)<br />
<br />
Adds an extra 'map info' to the mapper widget which can be used to display custom information.<br />
<br />
: See also: [[#killMapInfo|killMapInfo()]], [[#enableMapInfo|enableMapInfo()]], [[#disableMapInfo|disableMapInfo()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
{{note}}<br />
You can register multiple map infos - just give them unique names and toggle whichever ones you need.<br />
<br />
;Parameters<br />
* ''label:''<br />
: 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.<br />
* ''function:''<br />
: Callback function that will be responsible for returning information how to draw map info fragment.<br />
<br />
Callback function is called with following arguments:<br />
* ''roomId'' - current roomId or currently selected room (when multiple selection is made this is center room)<br />
* ''selectionSize'' - how many rooms are selected<br />
* ''areaId'' - roomId's areaId<br />
* ''displayedAreaId'' - areaId that is currently displayed<br />
<br />
Callback needs to return following:<br />
* ''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")<br />
* ''isBold'' (optional) - true/false - determines whether text will be bold <br />
* ''isItalic'' (optional) - true/false - determines whether text will be italic<br />
* ''color r'' (optional) - color of text red component (0-255)<br />
* ''color g'' (optional) - color of text green component (0-255)<br />
* ''color b'' (optional) - color of text blue component (0-255)<br />
<br />
{{note}}<br />
Map info is registered in disabled state, you need to enable it through script or by selecting checkbox under mapper.<br />
<br />
<syntaxhighlight lang="lua"><br />
registerMapInfo("My very own handler!", function(roomId, selectionSize, areaId, displayedArea) <br />
return string.format("RoomId: %d\nNumbers of room selected: %d\nAreaId: %d\nDisplaying area: %d", roomId, selectionSize, areaId, displayedArea),<br />
true, true, 0, 255, 0<br />
end)<br />
enableMapInfo("My very own handler!")<br />
</syntaxhighlight><br />
<br />
Example will display something like that:<br />
<br />
[[File:Map-info-example.png]]<br />
<br />
Using function arguments is completely optional and you can determine whether and how to display map info completely externally.<br />
<syntaxhighlight lang="lua"><br />
registerMapInfo("Alert", function() <br />
if character.hp < 20 then<br />
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<br />
else<br />
return "" -- will not return anything<br />
end<br />
end)<br />
enableMapInfo("Alert")<br />
</syntaxhighlight><br />
<br />
==resumeSpeedwalk==<br />
;resumeSpeedwalk()<br />
<br />
:Continues a speedwalk paused using [[#pauseSpeedwalk|pauseSpeedwalk()]]<br />
: See also: [[#speedwalk|speedwalk()]], [[#pauseSpeedwalk|pauseSpeedwalk()]], [[#stopSpeedwalk|stopSpeedwalk()]]<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
<syntaxhighlight lang="lua"><br />
local ok, err = resumeSpeedwalk()<br />
if not ok then<br />
cecho(f"\n<red>Error:<reset> Problem resuming speedwalk: {err}\n")<br />
return<br />
end<br />
cecho("\n<green>Successfully resumed speedwalk!\n")<br />
</syntaxhighlight><br />
<br />
==removeCustomLine==<br />
;removeCustomLine(roomID, direction) <br />
<br />
:Removes the custom exit line that's associated with a specific exit of a room.<br />
:See also: [[#addCustomLine|addCustomLine()]], [[#getCustomLines|getCustomLines()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- remove custom exit line that starts in room 315 going north<br />
removeCustomLine(315, "n")<br />
</syntaxhighlight><br />
<br />
==removeMapEvent==<br />
;removeMapEvent(event name)<br />
<br />
:Removes the given menu entry from a mappers right-click menu. You can add custom ones with [[#addMapEvent | addMapEvent()]].<br />
: See also: [[#addMapEvent | addMapEvent()]], [[#getMapEvents | getMapEvents()]], [[#removeMapMenu | removeMapMenu()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addMapEvent("room a", "onFavorite") -- add one to the general menu<br />
removeMapEvent("room a") -- removes the said menu<br />
</syntaxhighlight><br />
<br />
==removeMapMenu==<br />
;removeMapMenu(menu name)<br />
<br />
:Removes the given submenu from a mappers right-click menu. You can add custom ones with [[#addMapMenu | addMapMenu()]].<br />
: See also: [[#addMapMenu | addMapMenu()]], [[#getMapMenus | getMapMenus()]], [[#removeMapEvent | removeMapEvent()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addMapMenu("Test") -- add submenu to the general menu<br />
removeMapMenu("Test") -- removes that same menu again<br />
</syntaxhighlight><br />
<br />
==removeSpecialExit==<br />
;removeSpecialExit(roomID, command) <br />
<br />
:Removes the special exit which is accessed by ''command'' from the room with the given ''roomID''.<br />
:See also: [[#addSpecialExit|addSpecialExit()]], [[#clearSpecialExits|clearSpecialExits()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addSpecialExit(1, 2, "pull rope") -- add a special exit from room 1 to room 2<br />
removeSpecialExit(1, "pull rope") -- removes the exit again<br />
</syntaxhighlight><br />
<br />
==resetRoomArea==<br />
;resetRoomArea (roomID)<br />
<br />
: 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.<br />
<br />
: See also: [[#setRoomArea | setRoomArea()]], [[#getRoomArea | getRoomArea()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
resetRoomArea(3143)<br />
</syntaxhighlight><br />
<br />
==resizeMapWidget==<br />
;resizeMapWidget(width, height)<br />
:resizes a map window with given width, height.<br />
: See also: [[#openMapWidget|openMapWidget()]], [[#closeMapWidget|closeMapWidget()]], [[#moveMapWidget|moveMapWidget()]]<br />
<br />
{{MudletVersion|4.7}}<br />
<br />
;Parameters<br />
* ''width:''<br />
: The width of the map window, in pixels. Passed as an integer number.<br />
* ''height:''<br />
: The height of the map window, in pixels. Passed as an integer number.<br />
<br />
==roomExists==<br />
;roomExists(roomID)<br />
<br />
:Returns a boolean true/false depending if the room with that ID exists (is created) or not.<br />
<br />
==roomLocked==<br />
;locked = roomLocked(roomID)<br />
<br />
:Returns true or false whenever a given room is locked.<br />
: See also: [[#lockRoom|lockRoom()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo(string.format("Is room #4545 locked? %s.", roomLocked(4545) and "Yep" or "Nope"))<br />
</syntaxhighlight><br />
<br />
==saveJsonMap==<br />
; saveJsonMap([pathFileName])<br />
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. <br />
<br />
: See also: [[#loadJsonMap|loadJsonMap()]]<br />
{{MudletVersion|4.11.0}}<br />
<br />
; Parameters:<br />
* ''pathFileName'' (optional in Mudlet 4.12+): a string that is an absolute path and file name to save the data into.<br />
<br />
; Returns:<br />
* ''true'' on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
saveJsonMap(getMudletHomeDir() .. "/map.json")<br />
<br />
true<br />
</syntaxhighlight><br />
<br />
==saveMap==<br />
;saveMap([location], [version])<br />
<br />
: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.<br />
<br />
;Parameters<br />
* ''location''<br />
: (optional) save the map to the given location if provided, or the default one otherwise.<br />
* ''version''<br />
: (optional) map version as a number to use when saving (Mudlet 3.17+)<br />
<br />
: See also: [[#loadMap|loadMap()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local savedok = saveMap(getMudletHomeDir().."/my fancy map.dat")<br />
if not savedok then<br />
echo("Couldn't save :(\n")<br />
else<br />
echo("Saved fine!\n")<br />
end<br />
<br />
-- save with a particular map version<br />
saveMap(20)<br />
</syntaxhighlight><br />
<br />
==searchAreaUserData==<br />
;searchAreaUserData(area number | area name[, case-sensitive [, exact-match]])<br />
: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.<br />
<br />
==searchRoom== <br />
;searchRoom (room number | room name[, case-sensitive [, exact-match]])<br />
: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;<br />
<br />
::If no rooms are found, then an empty table is returned.<br />
<br />
: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.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- show the behavior when given a room number:<br />
display(searchRoom(3088))<br />
"The North Road South of Taren Ferry"<br />
<br />
-- show the behavior when given a string:<br />
-- shows all rooms containing the text in any case:<br />
display(searchRoom("North road"))<br />
{<br />
[3114] = "Bend in North road",<br />
[3115] = "North road",<br />
[3116] = "North Road",<br />
[3117] = "North road",<br />
[3146] = "Bend in the North Road",<br />
[3088] = "The North Road South of Taren Ferry",<br />
[6229] = "Grassy Field By North Road"<br />
}<br />
-- or:<br />
-- display(searchRoom("North road",false))<br />
-- display(searchRoom("North road",false,false))<br />
-- would both also produce those results.<br />
<br />
-- shows all rooms containing the text in ONLY the letter-case provided:<br />
display(searchRoom("North road",true,false))<br />
{<br />
[3114] = "Bend in North road",<br />
[3115] = "North road",<br />
[3117] = "North road",<br />
}<br />
<br />
-- shows all rooms containing ONLY that text in either letter-case:<br />
lua searchRoom("North road",false,true)<br />
{<br />
[3115] = "North road",<br />
[3116] = "North Road",<br />
[3117] = "North road"<br />
}<br />
<br />
-- shows all rooms containing only and exactly the given text:<br />
lua searchRoom("North road",true,true)<br />
{<br />
[3115] = "North road",<br />
[3117] = "North road"<br />
}<br />
</syntaxhighlight><br />
{{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.<br />
<br />
==searchRoomUserData== <br />
;searchRoomUserData([key, [value]])<br />
: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:<br />
<br />
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserData|getRoomUserData()]], [[#getRoomUserDataKeys|getRoomUserDataKeys()]], [[#setRoomUserData|setRoomUserData()]]<br />
<br />
;searchRoomUserData(key, value)<br />
<br />
:Reports a (sorted) list of all room ids with user data with the given "value" for the given (case sensitive) "key". <br />
<br />
;searchRoomUserData(key)<br />
<br />
:Reports a (sorted) list of the unique values from all rooms with user data with the given (case sensitive) "key". <br />
<br />
;searchRoomUserData()<br />
<br />
: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.<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- if I had stored the details of "named doors" as part of the room user data --<br />
display(searchRoomUserData("doorname_up"))<br />
<br />
--[[ could result in a list:<br />
{<br />
"Eastgate",<br />
"Northgate",<br />
"boulderdoor",<br />
"chamberdoor",<br />
"dirt",<br />
"floorboards",<br />
"floortrap",<br />
"grate",<br />
"irongrate",<br />
"rockwall",<br />
"tomb",<br />
"trap",<br />
"trapdoor"<br />
}]]<br />
<br />
-- then taking one of these keys --<br />
display(searchRoomUserData("doorname_up","trapdoor"))<br />
<br />
--[[ might result in a list:<br />
{<br />
3441,<br />
6113,<br />
6115,<br />
8890<br />
}<br />
]]</syntaxhighlight><br />
<br />
==setAreaName==<br />
;setAreaName(areaID or areaName, newName)<br />
<br />
:Names, or renames an existing area to the new name. The area must be created first with [[#addAreaName|addAreaName()]] and it must be unique.<br />
<br />
{{note}} parameter areaName is available since Mudlet 3.0.<br />
<br />
:See also: [[#deleteArea|deleteArea()]], [[#addAreaName|addAreaName()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setAreaName(2, "My city")<br />
<br />
-- available since Mudlet 3.0<br />
setAreaName("My old city name", "My new city name")<br />
</syntaxhighlight><br />
<br />
==setAreaUserData==<br />
;setAreaUserData(areaID, key (as a string), value (as a string))<br />
<br />
: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.<br />
<br />
:Returns true if successfully set.<br />
: See also: [[#clearAreaUserData|clearAreaUserData()]], [[#clearAreaUserDataItem|clearAreaUserDataItem()]], [[#getAllAreaUserData|getAllAreaUserData()]], [[#getAreaUserData|getAreaUserData()]], [[#searchAreaUserData|searchAreaUserData()]]<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- can use it to store extra area details...<br />
setAreaUserData(34, "country", "Andor.")<br />
<br />
-- or a sound file to play in the background (with a script that checks a room's area when entered)...<br />
setAreaUserData(34, "backgroundSound", "/home/user/mudlet-data/soundFiles/birdsong.mp4")<br />
<br />
-- can even store tables in it, using the built-in yajl.to_string function<br />
setAreaUserData(101, "some table", yajl.to_string({ruler = "Queen Morgase Trakand", clan = "Lion Warden"}))<br />
display("The ruler's name is: "..yajl.to_value(getRoomUserData(101, "some table")).ruler)<br />
</syntaxhighlight><br />
<br />
==setCustomEnvColor==<br />
;setCustomEnvColor(environmentID, r,g,b,a)<br />
<br />
: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.<br />
: See also: [[#getCustomEnvColorTable|getCustomEnvColorTable()]], [[#setRoomEnv|setRoomEnv()]]<br />
<br />
{{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.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomEnv(571, 200) -- change the room's environment ID to something arbitrary, like 200<br />
local r,g,b = unpack(color_table.blue)<br />
setCustomEnvColor(200, r,g,b, 255) -- set the color of environmentID 200 to blue<br />
</syntaxhighlight><br />
<br />
==setDoor==<br />
;setDoor(roomID, exitCommand, doorStatus)<br />
<br />
:Creates or deletes a door in a room. Doors are purely visual - they don't affect pathfinding. You can use the information to adjust your speedwalking path based on the door information in a room, though.<br />
<br />
: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!''<br />
<br />
: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).<br />
<br />
: See also: [[#getDoors|getDoors()]]<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to to create the door in.<br />
* ''exitCommand:''<br />
: 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.<br />
<br />
* ''doorStatus:''<br />
: 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). <br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- make a door on the east exit of room 4234 that is currently open<br />
setDoor(4234, 'e', 1)<br />
<br />
-- remove a door from room 923 that points north<br />
setDoor(923, 'n', 0)<br />
</syntaxhighlight><br />
<br />
==setExit==<br />
;setExit(from roomID, to roomID, direction)<br />
<br />
: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.<br />
<br />
:Returns ''false'' if the exit creation didn't work.<br />
<br />
: See also: [[#addSpecialExit|addSpecialExit()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- alias pattern: ^exit (\d+) (\d+) (\w+)$<br />
-- so exit 1 2 5 will make an exit from room 1 to room 2 via north<br />
<br />
if setExit(tonumber(matches[2]), tonumber(matches[3]), matches[4]) then<br />
echo("\nExit set to room:"..matches[3].." from "..matches[2]..", direction:"..string.upper(matches[3]))<br />
else<br />
echo("Failed to set the exit.\n")<br />
end<br />
</syntaxhighlight><br />
<br />
This function can also delete exits from a room if you use it like so:<br />
<br />
<syntaxhighlight lang="lua">setExit(from roomID, -1, direction)</syntaxhighlight><br />
<br />
- which will delete an outgoing exit in the specified direction from a room.<br />
<br />
==setExitStub==<br />
;setExitStub(roomID, direction, set/unset)<br />
<br />
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.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: The room to place an exit stub in, as a number.<br />
* ''direction:''<br />
: The direction the exit stub should lead in - as a short direction name ("nw"), long direction name ("northwest") or a number.<br />
* ''set/unset:''<br />
: A boolean to create or delete the exit stub.<br />
<br />
: See also: [[#getExitStubs|getExitStubs()]], [[#connectExitStub|connectExitStub()]]<br />
<br />
;Example<br />
Create an exit stub to the south from room 8:<br />
<syntaxhighlight lang="lua"><br />
setExitStub(8, "s", true)<br />
</syntaxhighlight><br />
<br />
How to delete all exit stubs in a room:<br />
<syntaxhighlight lang="lua"><br />
for i,v in pairs(getExitStubs(roomID)) do<br />
setExitStub(roomID, v,false)<br />
end<br />
</syntaxhighlight><br />
<br />
==setExitWeight==<br />
;setExitWeight(roomID, exitCommand, weight)<br />
<br />
: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.<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to to set the weight in.<br />
* ''exitCommand:''<br />
: 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.<br />
* ''weight:''<br />
: 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.<br />
<br />
: See also: [[#getExitWeights|getExitWeights()]]<br />
<br />
==setGridMode==<br />
;setGridMode(areaID, true/false)<br />
<br />
: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. <br />
:Returns true if the area exists, otherwise false.<br />
:[[File:Mapper-regular-mode.png|none|thumb|640x640px|regular mode]][[File:Mapper-grid-mode.png|none|thumb|631x631px|grid mode]]<br />
<br />
: See also: [[#getGridMode|getGridMode()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setGridMode(55, true) -- set area with ID 55 to be in grid mode<br />
</syntaxhighlight><br />
<br />
==setMapUserData==<br />
;setMapUserData(key (as a string), value (as a string))<br />
<br />
: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. <br />
<br />
:Returns true if successfully set.<br />
: See also: [[#clearMapUserData|clearMapUserData()]], [[#clearMapUserDataItem|clearMapUserDataItem()]], [[#getAllMapUserData|getAllMapUserData()]], [[#getMapUserData|getMapUserData()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- store general meta information about the map...<br />
setMapUserData("game_name", "Achaea Mudlet map")<br />
<br />
-- or who the author was<br />
setMapUserData("author", "Bob")<br />
<br />
-- can even store tables in it, using the built-in yajl.to_string function<br />
setMapUserData("some table", yajl.to_string({game = "mud.com", port = 23}))<br />
display("Available game info in the map: ")<br />
display(yajl.to_value(getMapUserData("some table")))<br />
</syntaxhighlight><br />
<br />
==setMapZoom==<br />
;setMapZoom(zoom)<br />
<br />
:Zooms the map in to a given zoom level. '''3.0''' is the closest you can get, and anything higher than that zooms the map out.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setMapZoom(10) -- zoom to a somewhat acceptable level, a bit big but easily visible connections<br />
</syntaxhighlight><br />
<br />
==setRoomArea==<br />
;setRoomArea(roomID, newAreaID or newAreaName)<br />
<br />
: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.<br />
<br />
: See also: [[#resetRoomArea|resetRoomArea()]]<br />
<br />
==setRoomChar==<br />
;setRoomChar(roomID, character)<br />
<br />
: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. In versions prior to Mudlet 3.8, the symbol can be cleared by using "_" as the character. In Mudlet version 3.8 and higher, the symbol may be cleared with either a space <code>" "</code> or an empty string <code>""</code>.<br />
<br />
;Game-related symbols for your map<br />
* [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.<br />
* Pixel Kitchen's [https://www.fontspace.com/donjonikons-font-f30607 Donjonikon Font] - 10x10 fantasy and RPG-related icons.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomChar(431, "#")<br />
<br />
setRoomChar(123, "$")<br />
<br />
-- emoji's work fine too, and if you'd like it coloured, set the font to Nojo Emoji in settings<br />
setRoomChar(666, "👿")<br />
</syntaxhighlight><br />
<br />
:'''Since Mudlet version 3.8 :''' this facility has been extended:<br />
:* 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.<br />
:* 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.<br />
:* 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.<br />
:* 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:<br />
::* 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)<br />
::* all the symbols used on the map and how they will be displayed both only using the selected font and all fonts<br />
::* 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<br />
::* a count of the rooms using the particular symbol<br />
::* a list, limited in entries of the first rooms using that symbol<br />
:* 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.<br />
<br />
: See also: [[#getRoomChar|getRoomChar()]]<br />
<br />
==setRoomCharColor==<br />
;setRoomCharColor(roomId, r, g, b)<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to to set char color to.<br />
* ''r:''<br />
: Red component of room char color (0-255)<br />
* ''g:''<br />
: Green component of room char color (0-255)<br />
* ''b:''<br />
: Blue component of room char color (0-255)<br />
<br />
Sets color for room symbol.<br />
<br />
<syntaxhighlight lang="lua"><br />
setRoomCharColor(2402, 255, 0, 0)<br />
setRoomCharColor(2403, 0, 255, 0)<br />
setRoomCharColor(2404, 0, 0, 255)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.11}}<br />
<br />
: See also: [[#unsetRoomCharColor|unsetRoomCharColor()]]<br />
<br />
==setRoomCoordinates==<br />
;setRoomCoordinates(roomID, x, y, z)<br />
<br />
: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).<br />
<br />
{{note}} 0,0,0 is the center of the map.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- alias pattern: ^set rc (-?\d+) (-?\d+) (-?\d+)$<br />
-- this sets the current room to the supplied coordinates<br />
setRoomCoordinates(roomID,x,y,z)<br />
centerview(roomID)<br />
</syntaxhighlight><br />
<br />
:You can make them relative asa well:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- alias pattern: ^src (\w+)$<br />
<br />
local x,y,z = getRoomCoordinates(previousRoomID)<br />
local dir = matches[2]<br />
<br />
if dir == "n" then<br />
y = y+1<br />
elseif dir == "ne" then<br />
y = y+1<br />
x = x+1<br />
elseif dir == "e" then<br />
x = x+1<br />
elseif dir == "se" then<br />
y = y-1<br />
x = x+1<br />
elseif dir == "s" then<br />
y = y-1<br />
elseif dir == "sw" then<br />
y = y-1<br />
x = x-1<br />
elseif dir == "w" then<br />
x = x-1<br />
elseif dir == "nw" then<br />
y = y+1<br />
x = x-1<br />
elseif dir == "u" or dir == "up" then<br />
z = z+1<br />
elseif dir == "down" then<br />
z = z-1<br />
end<br />
setRoomCoordinates(roomID,x,y,z)<br />
centerview(roomID)<br />
</syntaxhighlight><br />
<br />
==setRoomEnv==<br />
;setRoomEnv(roomID, newEnvID)<br />
<br />
: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.<br />
: See also: [[#setCustomEnvColor|setCustomEnvColor()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomEnv(551, 34) -- set room with the ID of 551 to the environment ID 34<br />
</syntaxhighlight><br />
<br />
==setRoomIDbyHash==<br />
;setRoomIDbyHash(roomID, hash)<br />
<br />
:Sets the hash to be associated with the given roomID. See also [[#getRoomIDbyHash|getRoomIDbyHash()]].<br />
<br />
:If the room was associated with a different hash, or vice versa, that association will be superseded.<br />
<br />
==setRoomName==<br />
;setRoomName(roomID, newName)<br />
<br />
:Renames an existing room to a new name.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomName(534, "That evil room I shouldn't visit again.")<br />
lockRoom(534, true) -- and lock it just to be safe<br />
</syntaxhighlight><br />
<br />
==setRoomUserData==<br />
;setRoomUserData(roomID, key (as a string), value (as a string))<br />
<br />
: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. <br />
<br />
:Returns true if successfully set.<br />
: See also: [[#clearRoomUserData|clearRoomUserData()]], [[#clearRoomUserDataItem|clearRoomUserDataItem()]], [[#getAllRoomUserData|getAllRoomUserData()]], [[#getRoomUserData|getRoomUserData()]], [[#searchRoomUserData|searchRoomUserData()]]<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- can use it to store room descriptions...<br />
setRoomUserData(341, "description", "This is a plain-looking room.")<br />
<br />
-- or whenever it's outdoors or not...<br />
setRoomUserData(341, "outdoors", "true")<br />
<br />
-- how how many times we visited that room<br />
local visited = getRoomUserData(341, "visitcount")<br />
visited = (tonumber(visited) or 0) + 1<br />
setRoomUserData(341, "visitcount", tostring(visited))<br />
<br />
-- can even store tables in it, using the built-in yajl.to_string function<br />
setRoomUserData(341, "some table", yajl.to_string({name = "bub", age = 23}))<br />
display("The denizens name is: "..yajl.to_value(getRoomUserData(341, "some table")).name)<br />
</syntaxhighlight><br />
<br />
==setRoomWeight==<br />
;setRoomWeight(roomID, weight)<br />
<br />
: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.<br />
<br />
{{note}} The minimum allowed room weight is 1. <br />
<br />
:To completely avoid a room, make use of [[#lockRoom|lockRoom()]].<br />
<br />
: See also: [[#getRoomWeight|getRoomWeight()]]<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setRoomWeight(1532, 3) -- avoid using this room if possible, but don't completely ignore it<br />
</syntaxhighlight><br />
<br />
<br />
==speedwalk==<br />
;speedwalk(dirString, backwards, delay, show)<br />
<br />
: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.<br />
<br />
:Call the function by doing: <code>speedwalk("YourDirectionsString", true/false, delaytime, true/false)</code><br />
<br />
: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.)<br />
<br />
: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.)<br />
<br />
: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.<br />
<br />
: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.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
speedwalk("16d1se1u")<br />
-- Will walk 16 times down, once southeast, once up. All in immediate succession.<br />
<br />
speedwalk("2ne,3e,2n,e")<br />
-- Will walk twice northeast, thrice east, twice north, once east. All in immediate succession.<br />
<br />
speedwalk("IN N 3W 2U W", false, 0.5)<br />
-- Will walk in, north, thrice west, twice up, west, with half a second delay between every move.<br />
<br />
speedwalk("5sw - 3s - 2n - w", true)<br />
-- Will walk backwards: east, twice south, thrice, north, five times northeast. All in immediate succession.<br />
<br />
speedwalk("3w, 2ne, w, u", true, 1.25)<br />
-- Will walk backwards: down, east, twice southwest, thrice east, with 1.25 seconds delay between every move.<br />
</syntaxhighlight><br />
<br />
{{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><br />
And have ''^//(.+)$'' execute: <code>speedwalk(matches[2], true, 0.7)</code><br />
Or make aliases like: ''^banktohome$'' to execute <syntaxhighlight lang="lua" inline>speedwalk("2ne,e,ne,e,3u,in", true, 0.5)</syntaxhighlight><br />
<br />
{{note}} The show parameter for this function is available in Mudlet 3.12+<br />
<br />
==stopSpeedwalk==<br />
;stopSpeedwalk()<br />
<br />
:Stops a speedwalk started using [[#speedwalk|speedwalk()]]<br />
: See also: [[#pauseSpeedwalk|pauseSpeedwalk()]], [[#resumeSpeedwalk|resumeSpeedwalk()]], [[#speedwalk|speedwalk()]]<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
<syntaxhighlight lang="lua"><br />
local ok, err = stopSpeedwalk()<br />
if not ok then<br />
cecho(f"\n<red>Error:<reset> {err}")<br />
return<br />
end<br />
cecho(f"\n<green>Success:<reset> speedwalk stopped")<br />
</syntaxhighlight><br />
<br />
==unHighlightRoom==<br />
;unHighlightRoom(roomID)<br />
<br />
:Unhighlights a room if it was previously highlighted and restores the rooms original environment color.<br />
: See also: [[#highlightRoom|highlightRoom()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
unHighlightRoom(4534)<br />
</syntaxhighlight><br />
<br />
==unsetRoomCharColor==<br />
;unsetRoomCharColor(roomId)<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID to to unset char color to.<br />
<br />
Removes char color setting from room, back to automatic determination based on room background lightness.<br />
<br />
<syntaxhighlight lang="lua"><br />
unsetRoomCharColor(2031)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.11}}<br />
<br />
==updateMap==<br />
;updateMap()<br />
<br />
:Updates the mapper display (redraws it). Use this function if you've edited the map via script and would like the changes to show.<br />
<br />
: See also: [[#centerview|centerview()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- delete a some room<br />
deleteRoom(500)<br />
-- now make the map show that it's gone<br />
updateMap()<br />
</syntaxhighlight><br />
<br />
[[Category:Mudlet Manual]]<br />
[[Category:Mudlet API]]</div>Demonnichttps://wiki.mudlet.org/index.php?title=Area_51&diff=20454Area 512023-05-14T13:15:52Z<p>Demonnic: /* UI Functions */</p>
<hr />
<div>{{TOC right}}<br />
<br />
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 [[Manual:Lua_Functions|Lua Functions]] and its sub-sites. <br />
<br />
Please use the [[Area_51/Template]] to add new entries in the sections below.<br />
<br />
Links to other functions or parts in other sections (i.e. the main Wiki area) need to include the section details before the <nowiki>'#'</nowiki> character in the link identifier on the left side of the <nowiki>'|'</nowiki> divider between the identifier and the display text. e.g.<br />
:: <nowiki>[[Manual:Mapper_Functions#getCustomLines|getCustomLines()]]</nowiki><br />
rather than:<br />
:: <nowiki>[[#getCustomLines|getCustomLines()]]</nowiki><br />
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!<br />
<br />
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.<br />
<br />
<br />
=Basic Essential Functions=<br />
:These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.<br />
<br />
=Database Functions=<br />
:A collection of functions for helping deal with the database.<br />
<br />
=Date/Time Functions=<br />
: A collection of functions for handling date & time.<br />
<br />
=File System Functions=<br />
: A collection of functions for interacting with the file system.<br />
<br />
=Mapper Functions=<br />
: A collection of functions that manipulate the mapper and its related features.<br />
<br />
==getMapZoom, PR #6615==<br />
;getMapZoom([areaID])<br />
<br />
:Gets the current 2D map zoom level. Added in '''Mudlet ''tba''''' 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.<br />
<br />
<!--will need to insert "Manual:Mapper_Functions" prior to # when moved to that documentation area--><br />
:See also: [[#setMapZoom|setMapZoom()]].<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6615<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID number to get the 2D zoom for (''optional'', the function works on the area currently being viewed if this is omitted).<br />
<br />
;Returns<br />
* A floating point number on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo("\nCurrent zoom level: " .. getMapZoom() .. "\n")<br />
-- Could be anything from 3 upwards:<br />
<br />
Current zoom level: 42.4242<br />
<br />
setMapZoom(2.5 + getMapZoom(1), 1) -- zoom out the area with ID 1 by 2.5<br />
true<br />
</syntaxhighlight><br />
<br />
{{note}} The precise meaning of a particular zoom value may have an underlying meaning however that bit of the code is rather old and no current coder has determined the significance, so far - 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!<br />
<br />
==mapSymbolFontInfo, PR #4038 closed==<br />
;mapSymbolFontInfo()<br />
: See also: [[#setupMapSymbolFont|setupMapSymbolFont()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;returns<br />
* either a table of information about the configuration of the font used for symbols in the (2D) map, the elements are:<br />
:* ''fontName'' - a string of the family name of the font specified<br />
:* ''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.<br />
:* ''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).<br />
* or ''nil'' and an error message on failure.<br />
<br />
::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).<br />
<br />
==moveMapLabel, PR #6014 open==<br />
;moveMapLabel(areaID/Name, labeID/Text, coordX/deltaX, coordY/deltaY[, coordZ/deltaZ][, absoluteNotRelativeMove])<br />
Re-positions a map label within an area in the 2D mapper, in a similar manner as the [[#moveRoom|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).<br />
<br />
:See also: [[Manual:Mapper_Functions#getMapLabels|getMapLabels()]], [[Manual:Mapper_Functions#getMapLabel|getMapLabel()]].<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6014<br />
<br />
;Parameters<br />
* ''areaID/Name:''<br />
: Area ID as number or AreaName as string containing the map label.<br />
<br />
* ''labelID/Text:''<br />
: 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.<br />
<br />
* ''coordX/deltaX:''<br />
: 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.<br />
<br />
* ''coordY/deltaY:''<br />
: 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.<br />
<br />
* ''coordZ/deltaZ:''<br />
: (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.<br />
<br />
* ''absoluteNotRelativeMove:''<br />
: (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'').<br />
<br />
;Returns<br />
: ''true'' on success or ''nil'' and an error message on failure, if successful it will also refresh the map display to show the result.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- move the first label in the area with the ID number of 2, three spaces to the east and four spaces to the north<br />
moveMapLabel(0, 2, 3.0, 4.0)<br />
<br />
-- 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<br />
moveMapLabel(0, 2, -1.0, 0.0, false)<br />
<br />
-- 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**:<br />
moveRoom(1, 2, -3.5, -2.0, true)<br />
<br />
-- move the second label in the area with the ID number of 2, up three levels<br />
moveRoom(1, 2, 0.0, 0.0, 3.0)<br />
<br />
-- move the second label in the "Test 1" area one space to the west, note the last two arguments are unneeded<br />
moveRoom("Test 1", 1, -1.0, 0.0, 0.0, false)<br />
<br />
-- 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:<br />
moveRoom(5, "Home", 0.0, 0.0, 0.0, true)<br />
<br />
-- all of the above will return the 'true' boolean value assuming there are the indicated labels and areas<br />
</syntaxhighlight><br />
<br />
==moveRoom, PR #6010 open==<br />
;moveRoom(roomID, coordX/deltaX, coordY/deltaY[, coordZ/deltaZ][, absoluteNotRelativeMove])<br />
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 [[Manual:Mapper_Functions#setRoomCoordinates|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.<br />
<br />
:See also: [[Manual:Mapper_Functions#setRoomCoordinates|setRoomCoordinates()]]<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6010<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID number to move.<br />
<br />
* ''coordX/deltaX:''<br />
: The absolute coordinate or the relative amount as a number to move the room in "room coordinates" along the X-axis.<br />
<br />
* ''coordY/deltaY:''<br />
: The absolute coordinate or the relative amount as a number to move the room in "room coordinates" along the Y-axis.<br />
<br />
* ''coordZ/deltaZ:''<br />
: (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.<br />
<br />
* ''absoluteNotRelativeMove:''<br />
: (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'').<br />
<br />
;Returns<br />
: ''true'' on success or ''nil'' and an error message on failure, if successful it will also refresh the map display to show the result.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- move the first room one space to the east and two spaces to the north<br />
moveRoom(1, 1, 2)<br />
<br />
-- move the first room one space to the west, note the final boolean argument is unneeded<br />
moveRoom(1, -1, 0, false)<br />
<br />
-- 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**:<br />
moveRoom(1, -3, -2, true)<br />
<br />
-- move the second room up three levels<br />
moveRoom(2, 0, 0, 3)<br />
<br />
-- move the second room one space to the west, note the last two arguments are unneeded<br />
moveRoom(2, -1, 0, 0, false)<br />
<br />
-- move the second room to the **center of the whole map**, note the last two arguments are required in this case:<br />
moveRoom(2, 0, 0, 0, true)<br />
<br />
-- all of the above will return the 'true' boolean value assuming there are rooms with 1 and 2 as ID numbers<br />
</syntaxhighlight><br />
<br />
==setMapZoom (revised), PR #6615==<br />
;setMapZoom(zoom[, areaID])<br />
<br />
:Zooms the 2D (only) map to a given zoom level. Larger numbers zooms the map further out. Revised in '''Mudlet ''tba''''' 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.<br />
<br />
<!--will need to insert "Manual:Mapper_Functions" prior to # when moved to that documentation area--><br />
:See also: [[#getMapZoom|getMapZoom()]].<br />
<br />
{{note}} The additional areaID parameter and the returned values described below are pending, they are not yet available/produced. See https://github.com/Mudlet/Mudlet/pull/6615<br />
<br />
;Parameters<br />
* ''zoom:''<br />
: floating point number that is at least 3.0 to set the zoom to.<br />
<br />
* ''areaID:''<br />
: Area ID number to adjust the 2D zoom for (''optional'', the function works on the area currently being viewed if this is omitted).<br />
<br />
;Returns (only since '''Mudlet ''tba''''')<br />
* ''true'' on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setMapZoom(10.0) -- zoom to a somewhat acceptable level, a bit big but easily visible connections<br />
true<br />
<br />
setMapZoom(2.5 + getMapZoom(1), 1) -- zoom out the area with ID 1 by 2.5<br />
true<br />
</syntaxhighlight><br />
<br />
{{note}} The precise meaning of a particular zoom value may have an underlying meaning however that bit of the code is rather old and no current coder has determined the significance, so far - 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!<br />
<br />
==setupMapSymbolFont, PR #4038 closed==<br />
;setupMapSymbolFont(fontName[, onlyUseThisFont[, scalingFactor]])<br />
:configures the font used for symbols in the (2D) map.<br />
: See also: [[#mapSymbolFontInfo|mapSymbolFontInfo()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;Parameters<br />
* ''fontName'' one of:<br />
:* - a string that is the family name of the font to use;<br />
:* - the empty string ''""'' to reset to the default {which is '''"Bitstream Vera Sans Mono"'''};<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow a following one to be modified.<br />
* ''onlyUseThisFont'' (optional) one of:<br />
:* - 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;<br />
:* - 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;<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow the following one to be modified.<br />
* ''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.<br />
<br />
;Returns<br />
* ''true'' on success<br />
* ''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).<br />
<br />
=Miscellaneous Functions=<br />
: Miscellaneous functions.<br />
<br />
==createVideoPlayer, PR #6439==<br />
;createVideoPlayer([name of userwindow], x, y, width, height)<br />
<br />
: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.<br />
<br />
{{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.<br />
<br />
{{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.<br />
<br />
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]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a 300x300 video player in the top-left corner of Mudlet<br />
createVideoPlayer(0,0,300,300)<br />
<br />
-- Alternative examples using Geyser.VideoPlayer<br />
GUI.VideoPlayer = GUI.VideoPlayer or Geyser.VideoPlayer:new({name="GUI.VideoPlayer", x = 0, y = 0, width = "25%", height = "25%"})<br />
<br />
GUI.VideoPlayer = GUI.VideoPlayer or Geyser.VideoPlayer:new({<br />
name = "GUI.VideoPlayer",<br />
x = "70%", y = 0, -- edit here if you want to move it<br />
width = "30%", height = "50%"<br />
}, GUI.Right)<br />
</syntaxhighlight><br />
<br />
==loadVideoFile, PR #6439==<br />
;loadVideoFile(settings table) or loadVideoFile(name, [url])<br />
:Loads video files from the Internet or the local file system to the "media" folder of the profile for later use with [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]] and [[Manual:Miscellaneous_Functions#stopVideos|stopVideos()]]. Although files could be loaded or streamed directly at playing time from [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]], loadVideoFile() provides the advantage of loading files in advance.<br />
<br />
{{note}} Video files consume drive space on your device. Consider using the streaming feature of [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]] for large files.<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
! style="text-align:left;" |Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;" |Yes<br />
|name<br />
|<file name><br />
| style="text-align:left;" |<br />
*Name of the media file.<br />
*May contain directory information (i.e. weather/maelstrom.mp4).<br />
*May be part of the profile (i.e. getMudletHomeDir().. "/congratulations.mp4")<br />
*May be on the local device (i.e. "C:/Users/YourNameHere/Movies/nevergoingtogiveyouup.mp4")<br />
|- style="color: blue;"<br />
| style="text-align:center;" |Maybe<br />
|url<br />
|<url><br />
| style="text-align:left;" |<br />
*Resource location where the media file may be downloaded.<br />
*Only required if file to load is not part of the profile or on the local file system.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#playSoundFile|loadSoundFile()]], [[Manual:Miscellaneous Functions#loadMusicFile|loadMusicFile()]], [[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#createVideoPlayer|createVideoPlayer()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Download from the Internet<br />
loadVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
})<br />
<br />
-- OR download from the profile<br />
loadVideoFile({name = getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4"})<br />
<br />
-- OR download from the local file system<br />
loadVideoFile({name = "C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4"})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of loadVideoFile(name[, url]) ----<br />
<br />
-- Download from the Internet<br />
loadVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4"<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
)<br />
<br />
-- OR download from the profile<br />
loadVideoFile(getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4")<br />
<br />
-- OR download from the local file system<br />
loadVideoFile("C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4")<br />
</syntaxhighlight><br />
<br />
==playVideoFile, PR #6439==<br />
;playVideoFile(settings table)<br />
:Plays video files from the Internet or the local file system for later use with [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]]. Video files may be downloaded to the device and played, or streamed from the Internet when the value of the <code>stream</code> parameter is <code>true</code>.<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
!Default<br />
! style="text-align:left;" |Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;" |Yes<br />
|name<br />
|<file name><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Name of the media file.<br />
*May contain directory information (i.e. weather/maelstrom.mp4).<br />
*May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp4")<br />
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp4")<br />
*Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.<br />
|-<br />
| style="text-align:center;" |No<br />
| volume<br />
|1 to 100<br />
|50<br />
| style="text-align:left;" |<br />
*Relative to the volume set on the player's client.<br />
|-<br />
| style="text-align:center;" |No<br />
|fadein<br />
|<msec><br />
|<br />
|<br />
*Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.<br />
*Start position: Start of media.<br />
*End position: Start of media plus the number of milliseconds (msec) specified.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
|fadeout<br />
|<msec><br />
|<br />
|<br />
*Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.<br />
*Start position: End of the media minus the number of milliseconds (msec) specified.<br />
*End position: End of the media.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
|start<br />
|<msec><br />
| 0<br />
| style="text-align:left;" |<br />
*Begin play at the specified position in milliseconds.<br />
|-<br />
| style="text-align:center;" |No<br />
|loops<br />
| -1, or >= 1<br />
|1<br />
| style="text-align:left;" |<br />
*Number of iterations that the media plays.<br />
*A value of -1 allows the media to loop indefinitely.<br />
|-<br />
| style="text-align:center;" |No<br />
|key<br />
|<key><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;" |No<br />
|tag<br />
|<tag><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Helps categorize media.<br />
|-<br />
| style="text-align:center;" |No<br />
|continue<br />
|true or false<br />
|true<br />
| style="text-align:left;" |<br />
*Continues playing matching new video files when true.<br />
*Restarts matching new video files when false.<br />
|- style="color: blue;"<br />
| style="text-align:center;" |Maybe<br />
|url<br />
|<url><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Resource location where the media file may be downloaded.<br />
*Only required if the file is to be downloaded remotely or for streaming from the Internet.<br />
|- style="color: blue;"<br />
| style="text-align:center;" |Maybe<br />
|stream<br />
|true or false<br />
|false<br />
| style="text-align:left;" |<br />
*Streams files from the Internet when true.<br />
*Download files when false (default).<br />
*Used in combination with the `url` key.<br />
|-<br />
|}<br />
<br />
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#stopSounds|stopSounds()]], [[Manual:Miscellaneous Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous Functions#stopVideos|stopVideos()]], [[Manual:Miscellaneous Functions#createVideoPlayer|createVideoPlayer()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stream a video file from the Internet and play it.<br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
, stream = true<br />
})<br />
<br />
-- 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.<br />
<br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
})<br />
<br />
-- Play a video file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
})<br />
<br />
-- OR copy once from the game's profile, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile({<br />
name = getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4"<br />
, volume = 75<br />
})<br />
<br />
-- OR copy once from the local file system, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile({<br />
name = "C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4"<br />
, volume = 75<br />
})<br />
<br />
-- OR download once from the Internet, and play a video stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 10 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 15 seconds from the end of the video<br />
---- [start] 5 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [key] reference of "text" for stopping this unique video later<br />
---- [tag] reference of "ambience" to stop any video later with the same tag<br />
---- [continue] playing this video if another request for the same video comes in (false restarts it) <br />
---- [url] resource location where the file may be accessed on the Internet<br />
---- [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) <br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, volume = nil -- nil lines are optional, no need to use<br />
, fadein = 10000<br />
, fadeout = 15000<br />
, start = 5000<br />
, loops = nil -- nil lines are optional, no need to use<br />
, key = "text"<br />
, tag = "ambience"<br />
, continue = true<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
, stream = false<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of playVideoFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,continue][,url][,stream]) ----<br />
<br />
-- Stream a video file from the Internet and play it.<br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4"<br />
, nil -- volume<br />
, nil -- fadein<br />
, nil -- fadeout<br />
, nil -- start<br />
, nil -- loops<br />
, nil -- key<br />
, nil -- tag<br />
, true -- continue<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/" -- url<br />
, false -- stream<br />
)<br />
<br />
-- 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.<br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4"<br />
, nil -- volume<br />
, nil -- fadein<br />
, nil -- fadeout<br />
, nil -- start<br />
, nil -- loops<br />
, nil -- key<br />
, nil -- tag<br />
, true -- continue<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/" -- url<br />
, false -- stream<br />
)<br />
<br />
-- Play a video file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4" -- name<br />
)<br />
<br />
-- OR copy once from the game's profile, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile(<br />
getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR copy once from the local file system, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile(<br />
"C:/Users/Tamarindo/Documents/TextInMotion-VideoSample-1080p.mp4" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR download once from the Internet, and play a video stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 10 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 15 seconds from the end of the video<br />
---- [start] 5 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [key] reference of "text" for stopping this unique video later<br />
---- [tag] reference of "ambience" to stop any video later with the same tag<br />
---- [continue] playing this video if another request for the same video comes in (false restarts it) <br />
---- [url] resource location where the file may be accessed on the Internet<br />
---- [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) <br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4" -- name<br />
, nil -- volume<br />
, 10000 -- fadein<br />
, 15000 -- fadeout<br />
, 5000 -- start<br />
, nil -- loops<br />
, "text" -- key<br />
, "ambience" -- tag<br />
, true -- continue<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/" -- url<br />
, false -- stream<br />
)<br />
</syntaxhighlight><br />
<br />
<br />
==stopVideos, PR #6439==<br />
;stopVideos(settings table)<br />
:Stop all videos (no filter), or videos that meet a combination of filters (name, key, and tag) intended to be paired with [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]].<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
! style="text-align:left;" |Purpose<br />
|-<br />
| style="text-align:center;" |No<br />
| name<br />
| <file name><br />
| style="text-align:left;" |<br />
* Name of the media file.<br />
|-<br />
| style="text-align:center;" |No<br />
|key<br />
|<key><br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;" |No<br />
|tag<br />
|<tag><br />
| style="text-align:left;" |<br />
*Helps categorize media.<br />
|-<br />
|}<br />
<br />
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#createVideoPlayer|createVideoPlayer()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stop all playing video files for this profile associated with the API<br />
stopVideos()<br />
<br />
-- Stop playing the text mp4 by name<br />
stopVideos({name = "TextInMotion-VideoSample-1080p.mp4"})<br />
<br />
-- Stop playing the unique sound identified as "text"<br />
stopVideos({<br />
name = nil -- nil lines are optional, no need to use<br />
, key = "text" -- key<br />
, tag = nil -- nil lines are optional, no need to use<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of stopVideos([name][,key][,tag]) ----<br />
<br />
-- Stop all playing video files for this profile associated with the API<br />
stopVideos()<br />
<br />
-- Stop playing the text mp4 by name<br />
stopVideos("TextInMotion-VideoSample-1080p.mp4")<br />
<br />
-- Stop playing the unique sound identified as "text"<br />
stopVideos(<br />
nil -- name<br />
, "text" -- key<br />
, nil -- tag<br />
)<br />
</syntaxhighlight><br />
<br />
<br />
==getCustomLoginTextId, PR #3952 open==<br />
;getCustomLoginTextId()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#sendPassword|sendPassword()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+Predefined custom login texts<br />
|-<br />
!Id!!Custom text!!Introduced in Mudlet version<br />
|-<br />
|1||"connect {character name} {password}"||TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCharacterName, PR #3952 open==<br />
;sendCharacterName()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
==sendCharacterPassword, PR #3952 open==<br />
;sendCharacterPassword()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]], [[#sendCharacterName|sendCharacterName()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCharacterName() ~= "" then<br />
tempTime(2.0, [[sendCharacterName()]], 1)<br />
tempTime(3.0, [[sendCharacterPassword()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCustomLoginText, PR #3952 open ==<br />
;sendCustomLoginText()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendPassword|sendPassword()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+Predefined custom login texts<br />
|-<br />
!Id!!Custom text!!Introduced in Mudlet version<br />
|-<br />
|1||"connect {character name} {password}"||TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
=Mudlet Object Functions=<br />
:A collection of functions that manipulate Mudlets scripting objects - triggers, aliases, and so forth.<br />
<br />
=Networking Functions=<br />
:A collection of functions for managing networking.<br />
<br />
=String Functions=<br />
:These functions are used to manipulate strings.<br />
<br />
=Table Functions=<br />
: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.<br />
<br />
=Text to Speech Functions=<br />
:These functions are used to create sound from written words. Check out our [[Special:MyLanguage/Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.<br />
<br />
=UI Functions=<br />
: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.<br />
<br />
==cecho2decho PR#6849 open==<br />
; convertedString = cecho2decho(str)<br />
<br />
:Converts a cecho formatted string to a decho formatted one. <br />
;See also: [[Manual:Lua_Functions#decho2cecho|decho2cecho()]], [[Manual:Lua_Functions#cecho2html|cecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from cecho to decho<br />
;Returns <br />
* a string formatted for decho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to a decho string and use decho to display it<br />
local cechoString = "<red><b>!!ALERT!!:</b><orange> Something has gone wrong!\n"<br />
decho(cecho2decho(cechoString))<br />
</syntaxhighlight><br />
<br />
==cecho2hecho PR#6849 open==<br />
; convertedString = cecho2hecho(str)<br />
<br />
:Converts a cecho formatted string to an hecho formatted one. <br />
;See also: [[Manual:Lua_Functions#hecho2cecho|hecho2cecho()]], [[Manual:Lua_Functions#cecho2html|cecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from cecho to decho<br />
;Returns <br />
* a string formatted for hecho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to an hecho string and use hecho to display it<br />
local cechoString = "<red><b>!!ALERT!!:</b><orange> Something has gone wrong!\n"<br />
hecho(cecho2hecho(cechoString))<br />
</syntaxhighlight><br />
<br />
==cecho2html PR#6849 open==<br />
; convertedString = cecho2html(str[, resetFormat])<br />
<br />
:Converts a cecho formatted string to an html formatted one. <br />
;See also: [[Manual:Lua_Functions#decho2cecho|decho2cecho()]], [[Manual:Lua_Functions#decho2html|cecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from cecho to decho<br />
* ''resetFormat''<br />
: optional table of default formatting options. As returned by [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
;Returns <br />
* a string formatted for html<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create the base string<br />
local cechoString = "<red><b>!!ALERT!!:</b><orange> Something has gone wrong!\n"<br />
<br />
-- create a label to display the result onto<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
<br />
-- convert the cecho string to an html one, using the default formatting of testLabel created above<br />
local htmlString = cecho2html(cechoString, testLabel:getFormat())<br />
<br />
-- and finally echo it to the label to see<br />
-- I use rawEcho as that displays the html exactly as given.<br />
testLabel:rawEcho(htmlString)<br />
</syntaxhighlight><br />
<br />
==decho2cecho PR#6849 open==<br />
; convertedString = decho2cecho(str)<br />
<br />
:Converts a decho formatted string to a cecho formatted one. <br />
;See also: [[Manual:Lua_Functions#cecho2decho|cecho2decho()]], [[Manual:Lua_Functions#decho2html|decho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from decho to cecho<br />
;Returns <br />
* a string formatted for cecho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to a decho string and use cecho to display it<br />
local dechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n"<br />
cecho(decho2cecho(dechoString))<br />
</syntaxhighlight><br />
<br />
==decho2hecho PR#6849 open==<br />
; convertedString = decho2hecho(str)<br />
<br />
:Converts a decho formatted string to an hecho formatted one. <br />
;See also: [[Manual:Lua_Functions#hecho2decho|hecho2decho()]], [[Manual:Lua_Functions#decho2html|decho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from decho to decho<br />
;Returns <br />
* a string formatted for hecho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to an hecho string and use hecho to display it<br />
local dechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n"<br />
hecho(decho2hecho(dechoString))<br />
</syntaxhighlight><br />
<br />
==decho2html PR#6849 open==<br />
; convertedString = decho2html(str[, resetFormat])<br />
<br />
:Converts a decho formatted string to an html formatted one. <br />
;See also: [[Manual:Lua_Functions#cecho2decho|cecho2decho()]], [[Manual:Lua_Functions#decho2html|decho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from decho to decho<br />
* ''resetFormat''<br />
: optional table of default formatting options. As returned by [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
;Returns <br />
* a string formatted for html<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create the base string<br />
local dechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n"<br />
<br />
-- create a label to display the result onto<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
<br />
-- convert the decho string to an html one, using the default formatting of testLabel created above<br />
local htmlString = decho2html(dechoString, testLabel:getFormat())<br />
<br />
-- and finally echo it to the label to see<br />
-- I use rawEcho as that displays the html exactly as given.<br />
testLabel:rawEcho(htmlString)<br />
</syntaxhighlight><br />
<br />
==deleteMultiline PR-6779 merged==<br />
<br />
; ok,err = deleteMultiline([triggerDelta])<br />
<br />
:Deletes all lines between when the multiline trigger fires and when the first trigger matched. Put another way, it deletes everything since the pattern in slot 1 matched.<br />
;See also: [[Manual:Lua_Functions#deleteLine|deleteLine()]], [[Manual:Lua_Functions#replaceLine|replaceLine()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
{{note}} This deletes all the lines since the first match of the multiline trigger matched. Do not use this if you donot want to delete ALL of those lines.<br />
<br />
;Parameters<br />
* ''[optional]triggerDelta:''<br />
: The line delta from the multiline trigger it is being called from. It is best to pass this in to ensure all lines are caught. If not given it will try to guess based on the number of patterns how many lines at most it might have to delete.<br />
<br />
;Returns <br />
* true if the function was able to run successfully, nil+error if something went wrong.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- if this trigger has a line delta of 3, you would call<br />
deleteMultiline(3)<br />
<br />
-- same thing, but with error handling<br />
local ok,err = deleteMultiline(3)<br />
if not ok then<br />
cecho("\n<firebrick>I could not delete the lines because: " .. err)<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
==hecho2cecho PR#6849 open==<br />
; convertedString = hecho2cecho(str)<br />
<br />
:Converts a hecho formatted string to a cecho formatted one. <br />
;See also: [[Manual:Lua_Functions#cecho2decho|cecho2decho()]], [[Manual:Lua_Functions#hecho2html|hecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from hecho to cecho<br />
;Returns <br />
* a string formatted for cecho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to a hecho string and use cecho to display it<br />
local hechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n""<br />
cecho(hecho2cecho(hechoString))<br />
</syntaxhighlight><br />
<br />
==hecho2decho PR#6849 open==<br />
; convertedString = hecho2decho(str)<br />
<br />
:Converts a hecho formatted string to a decho formatted one. <br />
;See also: [[Manual:Lua_Functions#decho2hecho|decho2hecho()]], [[Manual:Lua_Functions#hecho2html|hecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from hecho to decho<br />
;Returns <br />
* a string formatted for decho<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- convert to a decho string and use decho to display it<br />
local hechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n""<br />
decho(hecho2decho(hechoString))<br />
</syntaxhighlight><br />
<br />
==hecho2html PR#6849 open==<br />
; convertedString = hecho2html(str[, resetFormat])<br />
<br />
:Converts a hecho formatted string to an html formatted one. <br />
;See also: [[Manual:Lua_Functions#cecho2hecho|cecho2hecho()]], [[Manual:Lua_Functions#hecho2html|hecho2html()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Parameters<br />
* ''str''<br />
: string you wish to convert from hecho to hecho<br />
* ''resetFormat''<br />
: optional table of default formatting options. As returned by [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
;Returns <br />
* a string formatted for html<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create the base string<br />
local hechoString = "#ff0000#b!!ALERT!!:#/b#ffa500 Something has gone wrong!\n""<br />
<br />
-- create a label to display the result onto<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
<br />
-- convert the hecho string to an html one, using the default formatting of testLabel created above<br />
local htmlString = hecho2html(hechoString, testLabel:getFormat())<br />
<br />
-- and finally echo it to the label to see<br />
-- I use rawEcho as that displays the html exactly as given.<br />
testLabel:rawEcho(htmlString)<br />
</syntaxhighlight><br />
<br />
=Discord Functions=<br />
: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 [[Special:MyLanguage/Manual:Scripting#Discord_Rich_Presence|Discord scripting overview]].<br />
<br />
=Events=<br />
:New or revised events that Mudlet can raise to inform a profile about changes. See [[Manual:Event_Engine#Mudlet-raised_events|Mudlet-raised events]] for the existing ones.<br />
<br />
===sysMapAreaChanged, PR #6615===<br />
Raised when the area being viewed in the mapper is changed, either by the player-room being set to a new area or the user selecting a different area in the area selection combo-box in the mapper controls area. Returns two additional arguments being the areaID of the area being switched to and then the one for the area that is being left.<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6615</div>Demonnichttps://wiki.mudlet.org/index.php?title=IRE_mapping_script&diff=20452IRE mapping script2023-05-12T13:57:01Z<p>Demonnic: /* Download */</p>
<hr />
<div>{{TOC right}}<br />
This is the Lua component to make the Mudlet Mapper work for IRE games and StickMUD. You'll need to import the xml below in order for autowalking to work on Achaea, Aetolia, Lusternia, Imperian, or Starmourn. The script is included in the standard StickMUD GUI. See the '''[[IRE_mapping_script#Download|download section]]''' to get started!<br />
<br />
It has many features such as:<br />
* automatic repathing if you get off course<br />
* locking of whole areas<br />
* auto-swimming<br />
* mapping<br />
* scriptable exits<br />
* using special movement types for even faster speedwalking (like gallop, glide, dash, sprint, runaway, and more)<br />
* configurable teleportation methods<br />
* maintaining map features and finding the shortest route to the nearest one of a given type (like: goto junk, goto repair, goto harbour, ...)<br />
<br />
The script is written by Vadi, maintained by a [https://github.com/IRE-Mudlet-Mapping group of volunteers]. Have feedback, comment or a suggestion? Please [http://forums.mudlet.org/viewtopic.php?f=13&t=1696 comment here] or join the [https://discord.gg/PPUNnc3 Discord]! Maintenance of the crowdmaps is mostly done by the following individuals: Qwindor (Achaea and Starmourn), Cylon (Lusternia) and Tamarindo (StickMUD).<br />
<br />
To contact Qwindor about adjustments that need to be made to the Achaean crowdmap you can contact him in game or on skype at "qwindor.rousseau". Please include room numbers if possible to make it easier and faster for the corrections to be made.<br />
<br />
To contact Cylon regarding the Lusternia crowdmap you can reach him in game as Kaiel or on Discord, @Cylon#2741<br />
<br />
The script is open-source and includes contributions from Kard, Keneanung, Patrick, Qwindor, Wyd and others! Would you like to add something? Get in touch with [http://forums.mudlet.org/memberlist.php?mode=viewprofile&u=54 Vadi] for more.<br />
<br />
Would you like to setup a crowdmap for your game? Check out this [https://github.com/IRE-Mudlet-Mapping/CrowdmapTemplate template repo] to get started.<br />
<br />
Are you a game admin who'd like to add your game to the script? If you have similar GMCP room data, that is [[Adding your mud to the IRE mapping script|certainly possible]].<br />
<br />
= Download = <br />
'''[https://ire-mudlet-mapping.github.io/ire-mapping-script/downloads/mudlet-mapper.xml latest version]''' (right-click and 'Save as'), see the changelog [https://github.com/IRE-Mudlet-Mapping/ire-mapping-script/commits/master here].<br />
<br />
To upgrade your '''mapper script''' (not map): click on ''Package Manager'' or ''Toolbox → Package manager'', select ''Install'', and point it to the new '''mudlet-mapper.xml''' that you downloaded from above. It's best to reconnect or restart Mudlet after you to do, because the script won't know what game you're playing until it sees the welcome screen.<br />
<br />
The mapper script is absolutely free, though if you'll be making adjustments to it, please [https://github.com/IRE-Mudlet-Mapping/ire-mapping-script/pulls contribute them back]!<br />
<br />
= Installing =<br />
* make sure you're using a version of Mudlet that has a mapper (either a Map button or a Toolbox → Show Map option)<br />
* import this script either as a package or a module in Mudlet<br />
* restart Mudlet<br />
* if you're on Achaea, Starmourn, Lusternia or StickMUD do '''mconfig crowdmap on'''<br />
* if you can use wormholes, do '''mconfig lockwormholes off''' - if you can't use wormholes, do '''mconfig lockwormholes on'''. Type '''mconfig''' to see all available options!<br />
* done!<br />
<br />
== Updating ==<br />
The mapper script gained a feature a while ago where it is able to let you know when there's a new version of the script available, and even download it for you. You can update using that - or you can come back to this page, download the latest copy and install that.<br />
<br />
= Updating the map =<br />
== in Achaea, Starmourn, Lusternia or StickMUD ==<br />
Make sure you have '''mconfig crowdmap on'''. To force an update on the map, type '''rl''' and then click on ''(force)'' besides ''Check for all updates''. This will redownload the map for you - make sure you have the map window open, loading the new map won't work otherwise.<br />
<br />
== other IRE games and StickMUD ==<br />
To update your map, make sure that the map is open, and then go to Settings → Special Settings, and click on the '''Download map''' button. Your map will be downloaded straight from the game as it provides it to you.<br />
<br />
If any find any mistakes in the map, BUG them, if you are using the game-provided map.<br />
<br />
= Support =<br />
If you wish to leave any feedback on the script, please comment on the [http://forums.mudlet.org/viewtopic.php?f=13&t=1696 Mudlet forums]!<br />
<br />
== Should the crowdmap say locked/unlocked 0 wormholes using crowdmap? ==<br />
If you're using the crowdmap, it should not. The crowdmap format was accidentally updated to a version that requires a newer Mudlet to load it - please update your Mudlet to continue using it.<br />
<br />
== How to stop using sewer shortcuts? ==<br />
Do '''mconfig locksewers on''' to stop the mapper from using any sewer grates. If you'd only want it to stop sewers from a particular city, do '''arealock sewers''' and lock that specific area beneath the city.<br />
<br />
To allow it to use sewer exits again, do '''mconfig locksewers off'''.<br />
<br />
== How to use wormholes? ==<br />
If your map has wormholes mapped, then doing '''mconfig lockwormholes off''' will enable the mapper to use them. <br />
<br />
Note that wormholes are only available by default in the Achaea crowdmap - the IRE-provided maps lack wormhole data.<br />
<br />
== How to make it use wings in Achaea? ==<br />
This is a new feature of the mapper for Achaea so you need to update this mapper script to make sure it's at least version 12.8.1+ and your map as well (mconfig crowdmap needs to be on - not the map from the Mudlet special settings). To enable Atavian wings, do '''mconfig duanatharan on''', or to enable Eagle wings, do '''mconfig duanathar on'''. That's it!<br />
<br />
When Atavian wings are enabled, the mapper will make use of both duanathar and duanatharan, so you don't need to enable duanathar as well. The mapper is smart and won't use the wings if you're inside, only use wings if that is a quicker path and not use wings if you're off the Prime continent. If you start off walking when you're inside and you get outside, the mapper will use wings as well if they're quicker to your destination than walking.<br />
<br />
=== How can I make it not remove my wings? ===<br />
You can do '''mconfig removewings off'''. This is on by default, to prevent you from being forced to go up to clouds where you'll get ganked - the mapper instead only wears and removes them when you're going to clouds yourself.<br />
<br />
=== How can I say the keyword in another language? ===<br />
You can set it with '''mconfig winglanguage <language or none>''' - for example, '''mconfig winglanguage mhaldorian'''.<br />
<br />
=== Possible problems ===<br />
The wings feature involves a fair bit of different components. If your wings aren't being used as they should be, here are some things to look at:<br />
<br />
* is GMCP on? Check the General tab of Mudlet settings. If you don't even see the option, [http://forums.mudlet.org/viewtopic.php?f=5&t=1874&p=7415#p7415 update your Mudlet]. If it's there but it's not on, enable it, and reconnect.<br />
* are you using the crowdmap? Do ''mconfig crowdmap on'' to enable it - it'll check for map updates then and download the crowdmap. This is also necessary for the next step...<br />
* is the crowdmap working? If it says it (un)locked 0 wormholes when it downloads, then it's not working quite properly. The map crowdmap format was accidentally updated to a newer one, which means you need to update your Mudlet to a newer one.<br />
* is the area you are in marked as being on the Prime continent? Because you can't use wings off Prime, the mapper needs to have a list of all areas it can use wings on. To check this, do ''mc on'' and ''acl''. Check the Prime continent list to see if the area you are in (as ''rl'' will tell you) the list. If it's not on the list - do ''ac prime'' to add it, and then ''mc off'' when you're done - and message Qwindor saying that the certain continent isn't on Prime as it should be, so he can update the map for everybody.<br />
<br />
== How do I tell it I have the celerity power (artefact or mhun racial ability)? ==<br />
The mapper will automatically detect that you can move an extra room before the ''don't be hasty'' message and act accordingly.<br />
<br />
== How do I delete the map to start over? ==<br />
Close Mudlet first, then go to:<br />
<br />
* on Windows - your windows account folder, then the ''.config'' and the ''mudlet'' folder within,<br />
* on Linux - your home folder, then the ''mudlet-data'' within,<br />
* on Mac - your users folder, then the ''mudlet-data'' within,<br />
<br />
Once there, go within the ''profiles'' folder - it'll list your list of profiles. Go within the relevant one, and delete the ''maps'' folder entirely.<br />
<br />
That's it - start Mudlet, and your map state will be blank.<br />
<br />
== What is the difference between a room mark and a map feature? ==<br />
Both can be used with the goto syntax (though slightly different) and both help finding certain rooms again, but where are the differences?<br />
<br />
;Room mark<br />
* Room marks are akin to bookmarks. They help you remember a certain unique room and refer to it with another name.<br />
* Your room marks will be migrated with map updates, meaning you can have your personal set of marks.<br />
* They are set, listed and deleted with the *room mark*, *room marks* and *room unmark* commands respectively.<br />
* To use goto with them, simply use *goto <room mark>*<br />
<br />
;Map feature<br />
* Map features are used to mark similar rooms with a certain function. You usually don't care to which one of them you go, you simply needed the closest one.<br />
* Map features are a feature of the crowdmap and lost with every map update. They should be added and maintained by mappers.<br />
* They are set, listed and deleted with the *room create feature*, *feature list* and *room delete feature* respectively<br />
* To use goto with them, use *goto feature <partial feature name>*<br />
<br />
= Embedding the map =<br />
Here is a script to place the map into a container and have it open each time you open the profile.<br />
<syntaxhighlight lang="lua"><br />
mapper = Geyser.Mapper:new({<br />
name = "mapper",<br />
x = "65%", y = 0, -- edit here if you want to move it<br />
width = "30%", height = "50%"<br />
})<br />
</syntaxhighlight><br />
<br />
= Settings =<br />
To see what options can you set in the mapper script, do '''mconfig'''. To change an option a true/false, do '''mconfig option on/off'''. Some options are specific to IRE games, some are applicable in general.<br />
<br />
<html><br />
<div style="font-family: monospace; background-color:black; white-space:pre-wrap; font-size:medium;"><span style="color: rgb(192,192,192); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal">Available options: <br /></span><span style="color: rgb(0,255,0); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal">Use Sprint?</span><span style="color: rgb(255,255,255); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal"> (sprint) false<br /></span><span style="color: rgb(0,255,0); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal">Use a crowd-sourced map instead of IREs default?</span><span style="color: rgb(255,255,255); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal"> (crowdmap) true<br /></span><span style="color: rgb(0,255,0); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal">Use Atavian Wings in Achaea?</span><span style="color: rgb(255,255,255); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal"> (duanatharan) true<br /></span><span style="color: rgb(0,255,0); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal">Walk caravans?</span><span style="color: rgb(255,255,255); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal"> (caravan) false<br /></span><span style="color: rgb(0,255,0); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal">Lock pathway exits?</span><span style="color: rgb(255,255,255); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal"> (lockpathways) true<br /></span><span style="color: rgb(0,255,0); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal">Walk slowly instead of as quick as possible?</span><span style="color: rgb(255,255,255); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal"> (slowwalk) false<br /></span><span style="color: rgb(0,255,0); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal">Lock all sewers?</span><span style="color: rgb(255,255,255); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal"> (locksewers) false<br /></span><span style="color: rgb(0,255,0); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal">Lock all special exits?</span><span style="color: rgb(255,255,255); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal"> (lockspecials) false<br /></span><span style="color: rgb(0,255,0); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal">Take off shackle?</span><span style="color: rgb(255,255,255); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal"> (shackle) false<br /></span><span style="color: rgb(0,255,0); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal">Use Gallop?</span><span style="color: rgb(255,255,255); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal"> (gallop) false<br /></span><span style="color: rgb(0,255,0); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal">Remove Wings after using them?</span><span style="color: rgb(255,255,255); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal"> (removewings) true<br /></span><span style="color: rgb(0,255,0); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal">Show walking commands?</span><span style="color: rgb(255,255,255); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal"> (showcmds) true<br /></span><span style="color: rgb(0,255,0); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal">Lock all wormholes?</span><span style="color: rgb(255,255,255); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal"> (lockwormholes) true<br /></span><span style="color: rgb(0,255,0); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal">Speak non-default language for wings:</span><span style="color: rgb(255,255,255); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal"> (winglanguage) <br /></span><span style="color: rgb(0,255,0); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal">Use Dash?</span><span style="color: rgb(255,255,255); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal"> (dash) false<br /></span><span style="color: rgb(0,255,0); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal">Use Eagle Wings in Achaea?</span><span style="color: rgb(255,255,255); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal"> (duanathar) false<br /></span><span style="color: rgb(0,255,0); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal">Check for new maps?</span><span style="color: rgb(255,255,255); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal"> (updatemap) true<br /></span><span style="color: rgb(0,255,0); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal">Use Jester Runaway?</span><span style="color: rgb(255,255,255); background: rgb(0,0,0); font-weight: normal; font-style: normal; font-decoration: normal"> (runaway) false<br /></div><br />
</html><br />
<br />
= Aliases =<br />
== common ==<br />
=== goto ===<br />
: goto <id> - goes to a room of that id<br />
: goto <area> - goes to a specific area<br />
: goto <id> sprint/dash/gallop - goes to a place, sprinting, dashing or galloping whenever possible<br />
: goto <area> # - goes to an area - the number specifies which one exactly if more than one matches<br />
: goto feature <feature> - goes to the nearest room with the specified map feature<br />
<br />
=== mpp ===<br />
: mpp [on|off] - toggles or sets mapper to be paused<br />
<br />
<br />
=== mstop ===<br />
: mstop - stops the mapper completely<br />
<br />
<br />
=== rf / room find ===<br />
: rf <name>, room find <name> - searches for a room of a given name<br />
<br />
<br />
=== room marks ===<br />
: room marks - lists all the room marks the map has stored (your personal + default ones)<br />
<br />
<br />
=== room mark ===<br />
: room mark <mark_name> <room> - adds a mark for a given room with the name. Doing 'goto <mark_name>' will take you directly there!<br />
<br />
=== room unmark ===<br />
: room unmark <mark_name> - removes a mark with that name.<br />
<br />
<br />
=== area list ===<br />
: area list - shows the known area list<br />
<br />
<br />
=== room list ===<br />
: room list <area> - shows the list of rooms in an area<br />
<br />
<br />
=== arealock ===<br />
: arealock, arealock <area> - displays a list of areas you can lock/unlock, can also give it an area name to filter by. If an area is locked the mapper will not attempt to walk through or go through any of the rooms in the area;<br />
<br />
<br />
=== rl / room look ===<br />
: ''rl'' or ''room look'' - displays information about the room you're in<br />
: ''rl roomID'' or ''room look roomID'' - displays information on a given room ID (ie, ''rl 34'')<br />
: ''rl room name'' or ''room look room name'' - displays information on a given room, by it's name (ie, ''rl tavern of blah'')<br />
<br />
* Note that this will override the in-game ''rl'' command - but you can use RL to still read the last message.<br />
<br />
<br />
=== showpath ===<br />
: ''showpath roomID'' - shows you a path from where you are to another room (by it's ID)<br />
: ''showpath fromID toID'' - shows you a path from a given room to another given to another room<br />
<br />
=== spe list ===<br />
: ''spe list'' - shows you the list of all known special exists<br />
: ''spe list filter'' - shows you a list of all known special exits, filtered by a command - for example <code>spe list worm warp</code><br />
<br />
== mapping ==<br />
<br />
==== Mapping new areas ====<br />
The mapper relies on the in-game room IDs for it's own, and so it's best that you keep them in sync when creating new rooms as well - if you're in an unmapped room, 'rl' will tell you the rooms in-game ID. So when starting to map a new room in a new area, it'd best to create the new room with it's in-game ID at 0 0 0 coordinates, create the area, and move the room into the area - here are the '''exact steps necessary''':<br />
<br />
mc on (this will start mapping mode on)<br />
<br />
rl <see the room ID> (find out the room ID you are in)<br />
<br />
rlc v<room id> 0 0 0 (create a new room with the ID of the one you're in - notice the lack of space between v and room ID)<br />
<br />
survey <see area name> (find out what is the area name you are in)<br />
<br />
area add <area name> (create this new area)<br />
<br />
room area <area name> (move your newly made room into the newly made area)<br />
<br />
Proceed to walking about and automapping! Take a look at a small [http://www.youtube.com/watch?v=MgD9Nfz16uQ&hd=1 howto video] to get ideas on solving mapping problems as well that you might run into.<br />
<br />
{{note}}<br />
The mapper will not break up areas for you, so you have the choice of selecting how do you define your areas. To start a new area, move the room into an area, and all subsequent rooms will be mapped in that area.<br />
<br />
==== Sharing your map ====<br />
You can use the '''map save custom''' alias to export your map as a .dat file, which you can share it with others. People who'd like to load your map will then do '''map load custom''', select the map file from the file browser, and it will load it!<br />
<br />
=== Some tips on mapping ===<br />
<br />
* it's best to map in the 2D mode, because then you can select them en-masse and move them around, as well as doing other things<br />
* you can move rooms en-masse by selecting them, right-clicking and hitting move (note that in older versions of mudlet, you don't want to select the one you're in and try and move, it would be difficult)<br />
* when the mapper automatically makes a new room it is wise to issue a ''room area <area name>'' command to ensure the room is in the correct area.<br />
* the automatic map view in Mudlet tries to do its best to get the rooms in a sensible order, however the Divine do not always make this easy. Sometimes no matter how much you move the rooms around you simply cannot get the map to look perfect; if this happens:<br />
** you can try to move the rooms around manually (take note of the above tip though)<br />
** if you see yourself in a room but cannot take the apparent exit (e.g. you try to go ''north'' but there is no exit ''north'') you might have two rooms on top of each other; this can be a symptom of this problem<br />
** if you click on a room to walk to that room and you take what seems to be an improbably long path, it is possible some exits are not the direction they appear<br />
** the mapper knows about all the rooms even if Mudlet cannot display them in a way that is easy for us to see, the mapper can still use those rooms to get to or to auto walk through<br />
<br />
Note: ''map save'' is your friend; you don't need to use it after each room you add, but it is suggested you use it after mapping one particular area or a smaller part of a large area; it is better to save more often than have to remap an area because of something totally unexpected.<br />
<br />
Here's a [http://www.youtube.com/watch?v=MgD9Nfz16uQ&hd=1 short mapping video] to get a sense of a possible way to map things.<br />
<br />
=== mc - toggle mapping mode ===<br />
Use: *mc or map create <option>*, where option can be "on" or "off". Turning the mapping mode on enables the mapping aliases, along with several automapping things (that rely on GMCP being enabled):<br />
* room creation - if you enter a room that's not mapped yet, it'll map it<br />
* exit creation - if there is an unmapped exit in the room, the mapper will auto-link it to another room (and create that other room if it doesn't exist yet)<br />
* exit deletion - if the mapper knows about an exit that doesn't really exist, it'll remove it<br />
<br />
<br />
=== rlc - create a room ===<br />
Use: *rlc or room create <option>*, where option will specify the location of the new room. The new room will be auto-linked to the current one, be placed in the same area and take on the same environment type. If the mapper doesn't currently know where you are, you'll have to specify the exact coordinates that you'd like to place the room at (0x,0y,0z is a good place to start at). You can specify the location via several ways:<br />
* relative direction - ie 'rlc n' will create the room north of you, 'rlc se s' will create the room south-east and south of you.<br />
* exact coordinates - ie 'rlc 1 -5 10' will create the room at those exact coordinates. If the mapper doesn't know where you currently are, it'll also assume that you're located in that room now.<br />
* exact coordinates + specific ID - ie 'rlc v34 0 0 0' will create a new room with that exact ID (best to use one from the game, which you can find by doing 'rl') at the center.<br />
* partial coordinates - ie 'rlc 14x 5y' will create the room at 14x and 5y, but the same z-level you're on. You can can include all three of x,y,z coordinates or only one as you wish.<br />
<br />
<br />
=== rc - move a room ===<br />
Use: *rc or room coords [v<id>] <option>*, where option will specify the new location of the room. The room ID is optional, it'll move the current room if you don't provide one. Sample use:<br />
* relative direction - ie 'rc nw' will move the room to be nw of the current location, 'rlc e s' will create the room east and south of the current location, and 'rc v34 w' will move the room ID 34 west<br />
* exact coordinates - ie 'rc 1 -5 10' will move the current room to those exact coordinates. 'rc v12 8 3 -8' will move the room with ID 12 to 8x, 3y and -8z.<br />
* partial coordinates - ie 'rc 14x 5y' will move the room to be at 14x and 5y, but the same z-level you're on. You can can include all three of x,y,z coordinates or only one as you wish<br />
<br />
<br />
=== rld - delete a room ===<br />
Use '''rld or room delete <option>''', where option is the location or ID of the room you'd like to delete. Sample use:<br />
* relative direction - ie 'rld n' will delete the room that's north of you<br />
* exact room ID - ie 'rld 513' will delete the room with ID 513<br />
* current room - ie 'rld' will delete the room you're currently in<br />
<br />
<br />
=== rw - set room weight ===<br />
Use '''rw <optional room ID or direction> <weight>''', where option is the location or ID of the room whose weight you'd like to change. Sample use:<br />
* relative direction - ie 'rw n 4' will set the room weight of the room that's to the north of you to four<br />
* current room - ie 'rw 10' will set the room weight of the room you're standing in to 10<br />
* by room ID - ie 'rw 2343 2' will set the room weight of room 2343 to 2<br />
<br />
<br />
=== rwe - set exit weight ===<br />
Use: '''rwe <optional room ID, otherwise current> <weight> <exit>''', where the weight is a positive number (default for exits is 0). Setting a higher weight will make the exit be less likely to be used. Lastly, the exit can be a cardinal direction of either '''e''','''s''','''w''','''n''','''ne''','''se''','''sw''','''ne''','''up''','''down''','''in''','''out''' or the exact special exit text (including the ''script:'' part). This alias sets a weight one way only, so if you want to set it both ways, use it on the opposite side as well. Use '''rl''' to check exit weights.<br />
* current room - ie 'rwe 1 n' will set the weight of the exit north to 1.<br />
* current room - ie 'rwe 2434 0 e' will reset the exit weight of an east exit that leads out from the 2434 room.<br />
<br />
=== rlk - link rooms ===<br />
Use: *rlk or room link <option>*, where option will specify the room and exit to link with. You can also tack on 'one' at the end to make it be a one-way link. Examples:<br />
* exact room ID and direction - ie 'rlk 351 n' will link the current room to room #351 via a north exit<br />
* relative direction - ie 'rlk n' will link, if there is, a room to the north of this one to the one you're in<br />
* 'rlk n one' will make an exit north one-way (so - from here to there, but not from there to here)<br />
<br />
<br />
=== urlk - unlink rooms ===<br />
Use: *urlk or room unlink <direction>*, where direction will specify the direction of the exit to unlink. This function will unlink exits both ways, or one way if there is no incoming exit. <br />
<br />
Sample use:<br />
* relative direction - ie 'urlk nw' will unlink the exit to the northwest, and from the northwest room to the southeast<br />
<br />
=== rd - make doors ===<br />
Use: *rd <optional room ID, or current if none> <direction> <door status>*. Direction can be one of the following: '''e''','''s''','''w''','''n''','''ne''','''se''','''sw''','''ne'''. Door status can be '''open''' or '''o''', '''closed''' or '''c''', '''locked''' or '''l''', '''clear''' or '''gone'''. To delete a room, use clear or gone. Setting doors is one-way - to set two-way doors, use the alias from the opposite direction.<br />
<br />
Sample use:<br />
* from current room - '''rd n open''' will add a one-way door north.<br />
* from another room - '''rd 23 w closed''' will add a closed door leading west in room 23.<br />
<br />
=== rcc - give room a letter ===<br />
Use: *rcc <character> or rcc <letter> <room ID>*, where the character is one letter/number/symbol. Sample use:<br />
* current room - ie 'rcc $' will put the dollar sign in the current room (good way to indicate a shop)<br />
* another room somewhere on the map - ie 'rcc C 23434' will put the letter C onto room 23434<br />
* using '''clear''' as character will clear the room letter - ie 'rcc clear' will remove any letter from the current room <br />
<br />
<br />
=== spe - link rooms via special commands ===<br />
Use: '''spe <other room> <command>''' or '''exit special <other room> <command>''', where other room will specify the room to link with, and command the command to us to get to that room. Sample use:<br />
* relative direction - ie 'spe n push rock' will go to the room that's north of you by doing 'push rock'<br />
* exact room ID - ie 'spe 125 pull lever' will go to room 125 from the current one by pulling a lever<br />
<br />
You can also specify the script to do code for you, by starting the exit command with ''script:'' - for example:<br />
* run a script: <syntaxhighlight lang="lua">spe 125 script: sendAll("pull lever", "enter gate")</syntaxhighlight><br />
* run a script with a delay: <syntaxhighlight lang="lua">spe 125 script: send("pull lever") mmp.customwalkdelay(10) tempTimer(10, [[enter gate]])</syntaxhighlight><br />
<br />
If you'll be making use of mmp.customwalkdelay - make sure your script doesn't make use of room look or anything of that sort, because it will reset and make the mapper re-path (technical reason for this is because it'll be thinking it moved on already, so when it sees that it "ended up" not where it thought it was not, it'll retry).<br />
<br />
You can also make use of temporary triggers in your special exits as well - if you are, you '''must''' store the trigger IDs in ''mmp.specials'' table - this way if the user decides to cancel walking via ''mstop'', they will be deleted properly. Here is a through example of the Arcadia exit in Achaea, which requires opening the path by saying a word, waiting, and then entering - a path that might already be open and for which saying the word won't have any effect either. The script below is what was used to make it - it is split into multiple lines here for readability, but the command must all be on one line:<br />
<br />
<syntaxhighlight lang="lua"><br />
spe 19775 script: send("say Arcadia") send("enter archway") mmp.customwalkdelay(12) <br />
if mmp.specials.arcadiaarchway then killTrigger(mmp.specials.arcadiaarchway) end <br />
mmp.specials.arcadiaarchway = tempExactMatchTrigger("The arches slowly solidify before your eyes, what was mere light becoming the cool white marble of a tall stone archway.", <br />
[[if mmp.specials.arcadiaarchway then killTrigger(mmp.specials.arcadiaarchway) end<br />
if not mmp.paused then send("enter archway") end<br />
]])<br />
if mmp.specials.arcadiaql then killTrigger(mmp.specials.arcadiaql) end<br />
mmp.specials.arcadiaql = tempExactMatchTrigger("You step through a shimmering marble archway.",<br />
[[if mmp.specials.arcadiaql then killTrigger(mmp.specials.arcadiaql) end<br />
if mmp.specials.arcadiaarchway then killTrigger(mmp.specials.arcadiaarchway) end<br />
]])<br />
</syntaxhighlight><br />
<br />
=== spev - link two remote rooms via special commands ===<br />
Use: '''spev <from room> <to room> <command>'''. This different than '''spe''', which allows you to link only the current room to another room - this command doesn't require you to be in the starting room.<br />
* from room - the starting room for the special exit<br />
* to room - the ending room on the other side of the special exit<br />
* command - the command linking these two rooms together - ie "enter portal". You can also specify a script to run similar to '''spe'''.<br />
<br />
=== spe clear - unlink all special command links ===<br />
Use: *spe clear or exit special clear <option>*, where option is the location or the ID of the room you'd like to clear all special exits in. Sample use:<br />
* relative direction - ie 'spe clear n' will delete all special exits in the room that's north of you<br />
* exact room ID - ie 'spe clear 513' will delete all special exits in room with ID 513<br />
* current room - ie 'spe clear' will delete all special exits in the room you're currently in<br />
<br />
<br />
=== room area - move room to another area ===<br />
Use: *room area <different area>* will move the current room to another area you're in. Sample use:<br />
* area name - ie 'room area glomdoring' will move the room you're currently standing in to Glomdoring. You can also specify another room to move with 'room area v# <area>', ie 'room area 1 my new area'<br />
* area id - ie 'room area 44' will move the room to the area ID 44<br />
<br />
<br />
=== room label - add a label to a room ===<br />
Use: *room label <optional another room ID> <optional foreground color> <optional background color> my message*. Examples of using this:<br />
* room label the room I'm in<br />
* room label 342 this is a label in room 342<br />
* room label green this is a green label where I'm at<br />
* room label green black this is a green to black label where I'm at<br />
* room label 34 green black this is a green to black label at room 34<br />
<br />
<br />
=== area add - create a new area ===<br />
Use: *area add <area name>* will create a new area and automatically give it an ID. Sample use:<br />
* area name - ie 'area add Mrr city' will create a new area called such<br />
<br />
<br />
=== area rename - rename an area ===<br />
Use: *area rename <new area name>* will rename the current area you're in to the new name. Sample use:<br />
* area name - ie 'area rename Bobcat place* will call the area you're in like so from now on<br />
<br />
<br />
=== area delete - delete an area ===<br />
Use: *area delete <area name>* will delete the given area. If the area is really big (thousands of rooms), deleting it at once would take a really long while, and freeze your Mudlet while doing so. To combat the unpleasant experience, the script breaks up area deletion into batches of rooms (100 by default). While this still heavily impacts Mudlets performance, this allows you to see a progress meter of how far it has gotten and gives you an ability to pause it at any time by doing '''cancel area deletion'''.<br />
<br />
Sample use:<br />
* by area name - ie *area delete Bobcat place* will delete that area<br />
<br />
=== cancel area deletion ===<br />
Use: *cancel area deletion* stop area deletion. This will not restore deleted rooms - merely pauses the process, so you can resume it with *area delete* later on. You can type this in while Mudlet is deleting an area - it'll take a short while for letters to show up, but they will eventually.<br />
<br />
Sample use:<br />
* just one command - ie *cancel area deletion*.<br />
<br />
=== area labels - view/delete labels in an area ===<br />
Use: *area labels <area name>* will show the labels in the given area. Click on the small blue minus sign to delete the label.<br />
<br />
<br />
=== aca - add area to continent ===<br />
This alias will assign an area to belong to a continent. If an area belongs to another continent, it'll be moved. Currently, this feature is only used in Achaea for Eagle or Atavian wings (the area needs to be set as being on "Prime" continent).<br />
<br />
Use:<br />
* '''aca <continent>''' - adds the current area to a continent<br />
* '''aca <continent> <area name>''' - adds the given area to a continent<br />
* '''aca <continent> <area ID>''' - adds the area by area ID to a continent<br />
<br />
<br />
=== acl - list continents data ===<br />
Use: '''acl''' or '''area continents''' - lists which areas are in which continents are the mapper knows them. Currently, this feature is only used in Achaea for Eagle or Atavian wings.<br />
<br />
<br />
=== map save - save the map ===<br />
Use: *map save <optional name>* will save all of the map. Sample use:<br />
* default map - ie 'map save' will save the map with the default name as the latest one<br />
* map name - ie 'map save map before experiment' will save the map with that name<br />
* custom - ie 'map save custom' will export the map as a file, so you can share it with others<br />
<br />
You can also save the map as text (JSON) by using <code>map save json</code> or <code>map save all</code> (in both normal and JSON). For example:<br />
<br />
* default map - ie 'map save json' will save the map with the default name as the latest one, 'map save all' will do it in both.<br />
* map name - ie 'map save json map before experiment' will save the map with that name<br />
* custom - ie 'map save json custom' will export the map as a file, so you can share it with others<br />
<br />
=== map load - load the map ===<br />
Use: *map load <optional name>* will reload the map. Sample use:<br />
* default map - ie 'map load' will load the latest saved map (it may be a named one)<br />
* map name - ie 'map load before experiment' will load the map with that name<br />
* custom - ie 'map load custom' will load a map .dat file as you select it<br />
* as json - 'map load before experiment.json' - appending '.json' will make it load as json<br />
<br />
=== map delete all - clear the whole map ===<br />
Use: *map delete all* delete all areas and rooms of the map. Requires confirmation before actually clearing everything.<br />
<br />
<br />
=== delete known stockrooms ===<br />
Use: *delete known stockrooms* will unlink all known shops (marked with $) from their stockrooms, so the $ and the down exit triangle don't overlap each other.<br />
<br />
<br />
=== clear continent data ===<br />
Use: *clear continent data* will delete all of the continent data stored for the map.<br />
<br />
<br />
=== delete suffixed periods ===<br />
Use: *delete suffixed periods* will delete all the periods at the end of room names - which should just be stored as proper titles in the mapper, without the ending dot. It makes dealing with them (for use in locating abilities and etc) easier.<br />
<br />
<br />
=== find single exits ===<br />
Use: *find single exits* will locate all one-way exits for you. These can either be legitimate one-way exits, or they could be unmapped rooms that you want to visit, or they could be half-linked exits that you accidentally made via deleting rooms and mapping. You can click on the lines to go to those rooms.<br />
<br />
<br />
=== show char marks ===<br />
Use: *show char marks* will show you a list of character marks made with [[IRE_mapping_script#rcc_-_give_room_a_letter|rcc]] available on this map.<br />
<br />
=== feature create ===<br />
Use: *feature create <feature> [char <room character>]* will create a new map feature for use on rooms. You can also optionally add a character mark to the feature, which will be set when a map feature is added to a room.<br />
Note: Map feature names are not allowed to contain numbers.<br />
<br />
=== feature list ===<br />
Use: *feature list* lists all map features created via feature create and the associated room characters<br />
<br />
=== feature delete ===<br />
Use: *feature delete <feature>* deletes a map feature and removes it from all rooms.<br />
<br />
=== room create feature ===<br />
Use: *room create feature [v<room id>] <feature>* or *rcf [v<room id>] <feature>* adds a created map feature to the room. If the map feature is associated with a character mark, it will be set on the room and existing marks get overwritten. The room number to add the feature to can be given with the optional argument (note that there is no space between the v and the ID).<br />
<br />
=== room delete feature ===<br />
Use: *room delete feature [v<room id>] <feature>* or *rdf [v<room id>] <feature>* removes a map feature from the room. If the map feature is associated with a character mark and its set on the room, a random character mark from the other map features on the room is chosen to replace it. The room number to delete the feature from can be given with the optional argument (note that there is no space between the v and the ID).<br />
<br />
=== feature migrate ===<br />
Use: *feature migrate* if the command is set up for your game, it will try to migrate certain character marks to map features. Ideally, this should be used only once per game and afterwards map features should be added instead of character marks.<br />
<br />
= API =<br />
== using settings ==<br />
=== checking a setting ===<br />
Check ''mconfig'' settings using ''mmp.setting.<key''> or ''mmp.settings[<key>]''. For example, ''mmp.setting.sprint'' or ''mmp.settings["sprint"]'' will tell you if you have the Sprint option activated or disabled.<br />
<br />
=== retrieving the list of settings ===<br />
''mmp.settings:getAllOptions()'' will return you a key (option) - value (option setting) table of all of the available settings. You can use this to check which options are available.<br />
<br />
=== setting a setting ===<br />
To set a value, use ''mmp.settings:setOption(option, value)''.<br />
<br />
== functions ==<br />
=== mmp.anytolong ===<br />
;mmp.anytolong(exit)<br />
: converts an exit name to its long version.<br />
<br />
;Parameters:<br />
* ''exit:''<br />
: The exit abbreviation that needs to be converted. This must be a lower case string.<br />
<br />
;Return value:<br />
* ''longExit:''<br />
: The long version of the exit name as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This would return "north" from the function<br />
mmp.anytolong("n")<br />
--This would return "south" from the function (to be sure that you use the long version)<br />
mmp.anytolong("south")<br />
</syntaxhighlight><br />
<br />
<br />
=== mmp.anytoshort ===<br />
;mmp.anytoshort(exit)<br />
: converts an exit name to its short version.<br />
<br />
;Parameters:<br />
* ''exit:''<br />
: The exit abbreviation that needs to be converted. This must be a lower case string.<br />
<br />
;Return value:<br />
* ''shortExit:''<br />
: The short version of the exit name as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This would return "n" from the function<br />
mmp.anytoshort("north")<br />
--This would return "s" from the function (to be sure that you use the long version)<br />
mmp.anytoshort("s")<br />
</syntaxhighlight><br />
<br />
<br />
=== mmp.customwalkdelay ===<br />
;mmp.customwalkdelay(time)<br />
: Clears and extends the default walk re-try delay to a custom time, specified in seconds. This is helpful to trigger on, or use in special exit scripts in cases where you need to wait an abnormal amount of time before continuing on your journey. <br />
<br />
If you'd like to cancel the customwalkdelay and move on, call mmp.move(). Note that if a GMCP room event is received (this can be triggered with QL or other commands) the mapper then will attempt to repath, as it would have considered to have moved on and expects to be at the next room (thus don't cause this to happen).<br />
<br />
<br />
;Parameters:<br />
* ''time:''<br />
: Time in seconds to set the delay for.<br />
<br />
;Example<br />
if a special exit somewhere requires you to wait after trying to enter, use a scripted special exit with a delay:<br />
<code><br />
spe # script: send("dance around circle") mmp.customwalkdelay(10)<br />
</code><br />
<br />
you could also use it in a trigger, however the spe method is preferred:<br />
<syntaxhighlight lang="lua"><br />
-- trigger script:<br />
mmp.customwalkdelay(10)<br />
</syntaxhighlight><br />
<br />
<br />
=== mmp.deleteArea ===<br />
;mmp.deleteArea(name,exact)<br />
: Deletes an area from the map, if the given name is distinct. If not it shows a clickable list of deletable matches. <br />
<br />
;Parameters:<br />
* ''name:''<br />
: The name of the area that should be deleted. This is a string parameter.<br />
<br />
* ''exact:''<br />
: Boolean value, that describes if the name is the exact (true) or partial (false) name.<br />
<br />
;Raised events<br />
* ''mmp areas changed''<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This would attempt to delete "Hashan" from the map (Achaea)<br />
mmp.deleteArea("Hashan", false)<br />
--[[<br />
Output:<br />
(mapper): Which one of these specifically would you like to delete?<br />
Hashan, the City of (Sewers)<br />
Hashan, the City of (Seneschal Complex)<br />
Hashan, the City of<br />
]]<br />
<br />
--This would delete "Hashan, the City of" from the map (Achaea)<br />
mmp.deleteArea("Hashan, the City of", true) --if you made the second argument false, it'd give the same output as above<br />
</syntaxhighlight><br />
<br />
<br />
=== mmp.deleteLineP ===<br />
;mmp.deleteLineP()<br />
: Deletes the current line and the following prompt.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--[[<br />
Sample input:<br />
3620h, 3447m, 15755e, 21980w cexb-<br />
Your enhanced senses inform you that Sidai has entered At the southern gates of Hashan nearby.<br />
3620h, 3447m, 15755e, 21980w cexb-<br />
<br />
Trigger:<br />
^Your enhanced senses inform you that (\w+) has entered (.+) nearby\.$<br />
]]<br />
<br />
mmp.deleteLineP()<br />
cecho("WARNING! "..matches[2].."nearby! ("..matches[3]..")")<br />
<br />
--[[<br />
Output:<br />
3620h, 3447m, 15755e, 21980w cexb-<br />
WARNING! Sidai nearby! (At the southern gates of Hashan)<br />
]]<br />
</syntaxhighlight><br />
<br />
<br />
=== mmp.echo ===<br />
;mmp.echo(what)<br />
: Prints the argument with a prefixed "(mapper): ".<br />
<br />
;Parameters:<br />
* ''what:''<br />
: The message that should be printed.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
mmp.echo("We arrived at our destination.")<br />
--[[<br />
Output:<br />
(mapper): We arrived at our destination.<br />
]]<br />
</syntaxhighlight><br />
<br />
<br />
=== mmp.echoAreaList ===<br />
;mmp.echoAreaList()<br />
: Prints a list of all known areas. Each name is clickable to display its room list.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
mmp.echoAreaList()<br />
--[[<br />
Output of Midkemia-Online (no longer extant on IRE - example needs updating...!):<br />
List of all areas we know of (click to view room list):<br />
2 Caldara<br />
3 Human Introduction<br />
4 Krondor<br />
(...)<br />
100 Fifth Circle of Hell<br />
102 Eagles Reaches<br />
108 Ruins of Veilgarden<br />
]]<br />
</syntaxhighlight><br />
<br />
<br />
=== mmp.echonums ===<br />
;mmp.echonums(roomname)<br />
: Prints the first three possible room IDs for the given room name. If no room is found, "?" is echoed. A click of the room ID starts the autowalker to there.<br />
<br />
;Parameters:<br />
* ''roomname:''<br />
: Name of the room of which the IDs should be displayed. This must be a lower case string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
mmp.echonums("The Crossroads")<br />
--[[<br />
Output:<br />
4472, 4895, 6162, ...<br />
]]<br />
<br />
mmp.echonums("foobar")<br />
--[[<br />
Output:<br />
?<br />
]]<br />
</syntaxhighlight><br />
<br />
<br />
=== mmp.locateAndEcho ===<br />
;mmp.locateAndEcho(room, person, area)<br />
: Prints the first three possible room IDs for the given room name, and the area(s) relevant as well if the is not used in the function otherwise it will only print the room numbers for the given area. If no room is found, "?" is echoed. A click of the room ID starts the autowalker to there. This is good to use if you can narrow down the exact in game area with whatever skill you use as shown with the difference between the first and second example.<br />
<br />
Fills the mmp.ndb with relevant information as well.<br />
<br />
;Parameters:<br />
* ''room:''<br />
: Name of the room of which the IDs should be displayed. This must be a lower case string.<br />
<br />
* ''person:''<br />
: Name of the person you are locating for the person for the person location tracker.<br />
<br />
* ''area:''<br />
: Matches the in game area based on the name of the area populated from the room gmcp information.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
mmp.locateAndEcho("Inside the World Tree", "Person")<br />
--[[<br />
Output:<br />
(52454, 53005, 53544, ...)<br />
From your knowledge, that room might be in The collar of Frysta, or The collar of Bjarndyr, or Village of Qerstead, or Radak's Hold, or Loramere, or Central Wilderness, or Lhitsu forest, or Village of Myrinia, or Sarave Foothills, or The collar of Veior, or fathomless expanse of the World Tree, or Ioje compound, or Valley of Kuthalebak, or Kunpai Island, or Pri'alysh Moor.<br />
]]<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
mmp.locateAndEcho("Inside the World Tree", "Person", "the Central Wilderness")<br />
--[[<br />
Output:<br />
(2898)<br />
From your knowledge, that room is in Central Wilderness.<br />
]]<br />
</syntaxhighlight><br />
<br />
=== mmp.locateAndEchoSide ===<br />
;mmp.locateAndEchoSide(room, person)<br />
: Prints the first three possible room IDs for the given room name, and the area(s) relevant as well. If no room is found, "?" is echoed. A click of the room ID starts the autowalker to there. This will display to the side of the line triggered as shown below.<br />
<br />
Fills the mmp.ndb with relevant information as well.<br />
<br />
;Parameters:<br />
* ''room:''<br />
: Name of the room of which the IDs should be displayed. This must be a lower case string.<br />
<br />
* ''person:''<br />
: Name of the person you are locating for the person for the person location tracker.<br />
<br />
;Example<br />
<br />
Triggered line:<br />
: You seek out the mind of Krizal and an image of The Crossroads appears in your mind.<br />
<br />
<syntaxhighlight lang="lua"><br />
mmp.locateAndEcho("The Crossroads", "Krizal")<br />
--[[<br />
Output:<br />
You seek out the mind of Krizal and an image of The Crossroads appears in your mind. (4472) (Hashan)<br />
]]<br />
</syntaxhighlight><br />
<br />
=== mmp.gotoRoom ===<br />
;mmp.gotoRoom(room ID, sprinttype)<br />
: Similar to goto ''<room ID>'', this'll start speedwalking to the given room.<br />
<br />
;Parameters:<br />
* ''room ID:''<br />
: The room ID to head to.<br />
* ''sprinttype:''<br />
: (optional): how to speed up the way there - can be gallop, sprint, dash, runaway, glide.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- go to room #5<br />
mmp.gotoRoom(5)<br />
<br />
-- go to the room Bob was last located in<br />
mmp.gotoRoom(mmp.getnums(mmp.pdb["Bob"])[1])<br />
<br />
-- go to room #5, galloping where possible<br />
mmp.gotoRoom(5, "gallop")<br />
</syntaxhighlight><br />
<br />
=== mmp.echoRoomList ===<br />
;mmp.echoRoomList(area name)<br />
: Prints a list of all known rooms in a given area. Each name is clickable to go to that room.<br />
<br />
;Parameters:<br />
* ''area name:''<br />
: The name of the area in which rooms should be listed.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- list rooms from area "main"<br />
mmp.echoRoomList("main")<br />
</syntaxhighlight><br />
<br />
<br />
=== mmp.findAreaID ===<br />
=== mmp.getAreaBorders ===<br />
<br />
=== mmp.getShortestofMultipleRooms ===<br />
mmp.getShortestofMultipleRooms (rooms)<br />
: Returns the closest room from a table of multiple room ids<br />
;Parameters:<br />
* ''rooms:''<br />
: Table of two or more room ids.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- return the closest of three different rooms<br />
rooms = {1,2,3}<br />
closestRoom = mmp.getShortestofMultipleRooms(rooms)<br />
print(closestRoom)<br />
</syntaxhighlight><br />
<br />
=== mmp.getnums ===<br />
=== mmp.getPath ===<br />
=== mmp.getAreaName ===<br />
mmp.getAreaName(roomid)<br />
: Returns the area name that the room belongs to, or ''"?"'' if it is unknown.<br />
;Parameters:<br />
* ''roomid:''<br />
: Room ID you'd like to know the area of.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- show the area that room 31434 belongs to<br />
print(mmp.getAreaName(31434))<br />
</syntaxhighlight><br />
<br />
=== mmp.pause ===<br />
=== mmp.ranytolong ===<br />
=== mmp.relativeroom ===<br />
=== mmp.renameArea ===<br />
=== mmp.roomArea ===<br />
=== mmp.roomEcho ===<br />
=== mmp.roomexists ===<br />
=== mmp.roomFind ===<br />
;mmp.roomFind(query, lines)<br />
: Displays rooms that match your query. The room number that is output will autowalk to the location when clicked. The area that is output will show the shorted path to the room.<br />
<br />
;Parameters<br />
* ''query'':<br />
: Name or partial name of the room that you are trying to find.<br />
* ''lines'':<br />
: The number of rooms that will be output to your screen. Default is 30. Can also send 'all' to list all room matches.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
mmp.roomFind("forest")<br />
mmp.roomFind("forest", "all")<br />
mmp.roomFind("forest", "40")<br />
</syntaxhighlight ><br />
<br />
=== mmp.roomLook ===<br />
=== mmp.searchRoom ===<br />
=== mmp.searchRoomExact ===<br />
<br />
=== mmp.gotoFeature ===<br />
;mmp.gotoFeature(partialFeatureName, dashtype)<br />
: Finds the sortest path to the nearest feature matching the (partial) map feature name. If given, it will also use a dashtype.<br />
<br />
;Parameters<br />
* ''partialFeatureName'':<br />
: Partial name of a map feature to go to. If the name matches a map feature exactly, it's chosen before any partial matching is attempted.<br />
* ''dashtype'':<br />
: One of the defined movement types which allow skipping a number of rooms in a straight line.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
mmp.gotoFeature("junk")<br />
mmp.gotoFeature("wilder", "gallop")<br />
</syntaxhighlight ><br />
<br />
=== mmp.createMapFeature ===<br />
;mmp.createMapFeature(featureName, roomCharacter)<br />
: Creates a new map feature with the given name and optionally associates a character mark with the map feature. This function will not associate the feature with any rooms, but instead, it whitelists the map feature for future use.<br />
<br />
;Parameters<br />
* ''featureName'':<br />
: Name of the map feature to create.<br />
* ''roomCharacter'':<br />
: Optional parameter to set the character mark to use when adding the map feature to a room.<br />
<br />
;Return value<br />
* ''success'':<br />
: Returns <code>true</code> if the creation was successful, otherwise <code>nil</code>.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
mmp.createMapFeature("savehouse")<br />
mmp.createMapFeature("junk", "J")<br />
mmp.createMapFeature("wilderness", "W")<br />
</syntaxhighlight ><br />
<br />
=== mmp.listMapFeatures ===<br />
;mmp.listMapFeatures()<br />
: Prints the list of map features to the main console.<br />
<br />
;Return value<br />
* ''success'':<br />
: Returns <code>true</code> if the listing was successful, otherwise <code>nil</code>.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
mmp.listMapFeatures()<br />
</syntaxhighlight><br />
<br />
=== mmp.roomCreateMapFeature ===<br />
;mmp.roomCreateMapFeature(featureName, roomId)<br />
: Creates a whitelisted map feature in a room. If the room ID is not given, <code>mmp.currentroom</code> is used. If the map feature is associated with a character mark, the mark will be set on the room, overwriting the existing one.<br />
<br />
;Parameters<br />
* ''featureName'':<br />
: The name of a whitelisted map feature to create in the room.<br />
* ''roomId'':<br />
: Optional parameter to identify the room where the map feature should be created. If it is not given <code>mmp.currentroom</code> is used.<br />
<br />
;Return values<br />
* ''success'':<br />
: Returns <code>true</code> if the creation was successful, otherwise <code>nil</code>.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
mmp.roomCreateMapFeature("junk")<br />
mmp.roomCreateMapFeature("wilderness", 12358)<br />
</syntaxhighlight><br />
<br />
=== mmp.roomDeleteMapFeature ===<br />
;mmp.roomDeleteMapFeature(featureName, roomId)<br />
: Deletes a map feature from a room. If the room ID is not given, <code>mmp.currentroom</code> is used. If the room carries the associated character mark, it will be removed and the character mark of a random remaining map feature will be used.<br />
<br />
;Parameters<br />
* ''featureName'':<br />
: The name of a map feature to delete from the room.<br />
* ''roomId'':<br />
: Optional parameter to identify the room where the map feature should be deleted. If it is not given <code>mmp.currentroom</code> is used.<br />
<br />
;Return values<br />
* ''success'':<br />
: Returns <code>true</code> if the deletion was successful, otherwise <code>nil</code>.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
mmp.roomDeleteMapFeature("junk")<br />
mmp.roomDeleteMapFeature("wilderness", 12358)<br />
</syntaxhighlight><br />
<br />
=== mmp.getRoomMapFeatures ===<br />
;mmp.getRoomMapFeatures(roomId)<br />
: Returns a list of map features in the room. If the room ID is not given, <code>mmp.currentroom</code> is used.<br />
<br />
;Parameters<br />
* ''roomId'':<br />
: Optional parameter to identify the room of which the map features should be returned. If it is not given <code>mmp.currentroom</code> is used.<br />
<br />
;Return values<br />
* ''roomMapFeatures'':<br />
: Returns a list of map features in the given room. If an error occurred, <code>nil</code> is returned.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
mmp.roomCreateMapFeature("junk")<br />
mmp.getRoomMapFeatures() -- returns { "junk" }<br />
<br />
<br />
mmp.roomCreateMapFeature("wilderness", 12358)<br />
mmp.roomCreateMapFeature("harbour", 12358)<br />
mmp.getRoomMapFeatures(12358) -- returns { "wilderness", "harbour" }<br />
</syntaxhighlight><br />
<br />
=== mmp.deleteMapFeature ===<br />
;mmp.deleteMapFeature(featureName)<br />
: Deletes the whitelist entry of a map feature from the map. This also leads to the deletion of the map feature from all rooms.<br />
<br />
;Parameters<br />
* ''featureName'':<br />
: The name of the map feature that should be deleted from the map.<br />
<br />
;Return values<br />
* ''success'':<br />
: returns <code>true</code> if the deletion was successful, otherwise <code>nil</code><br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
mmp.deleteMapFeature("junk")<br />
</syntaxhighlight><br />
<br />
=== mmp.getMapFeatures ===<br />
;mmp.getMapFeatures()<br />
: Returns a table of whitelisted map features for this map and their associated character marks.<br />
<br />
;Return values<br />
* ''mapFeatures'':<br />
: The list of map features that are whitelisted in this map and their associated character marks.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
mmp.createMapFeature("savehouse")<br />
mmp.createMapFeature("junk", "J")<br />
mmp.createMapFeature("wilderness", "W")<br />
<br />
mmp.getMapFeatures()<br />
-- [[<br />
returns {<br />
savehouse = "",<br />
junk = "J",<br />
wilderness = "W"<br />
}<br />
]]<br />
</syntaxhighlight><br />
<br />
== mudlet events ==<br />
* mmapper started walking - raised before starting autowalking<br />
* mmapper failed path - tried to go from A to B, but failed because there is no known path (or we were walking, got moved offcourse, and can't get to the destination anymore)<br />
* mmapper arrived - arrived at our destination successfully<br />
* mmapper stopped - mapper's stop function was called (this will be raised anytime it was, even if we weren't moving)<br />
* mmapper updated pdb - mmp.pdb table was updated with new data<br />
* mmapper updated map - raised when the mapper loads a new map in with loadMap()<br />
* mmapper map reloaded - raised when the map is reloaded<br />
* mmapper went inside - raised when you go inside in Achaea<br />
* mmapper went outside - raised when you go outside in Achaea<br />
* mmapper changed continent - raised when you change continents in Achaea<br />
* mmp logged in - raised when logged in to determine IRE game<br />
* mmp lost def - raised when a defence is lost<br />
* mmp got def - raised when a defence is gained<br />
* mmp areas changed - called when list of areas is edited<br />
* mmp link externals - raised before a path starts getting computed. You can use this event to add in special exits that you'd like the mapper to consider. Added in 14.4.1.<br />
* mmp clear externals - raised after a path is computed. Use this event to remove special exits that you've added with 'mmp link externals'. Added in 14.4.1.<br />
<br />
= Developers =<br />
Code is hosted in Git on GitHub, [https://github.com/IRE-Mudlet-Mapping/ire-mapping-script ire-mapper-script]. If you'd like to help develop, please feel free to submit a pull request!<br />
<br />
Credit to: Sidd (for sharing his own mapping aliases that came before any documentation existed), keneanung (contributing to the coding, adding goto <area> and many other things), Wyd for the options system.<br />
<br />
= What else needs to be done =<br />
General things that need work are triggers for where room detection is necessary - player-locating abilities, shrine defilement warnings, mindsense area reports, etc. The general format is that the room ID should be prefixed to the line the room name is given + be made clickable - so the player can click on it and go. An example is provided for the Lusternian scent ability that implements this. Also needs to recognize the need to swim, right now if you don't have waterwalking - it'll loop trying to walk. Another small problem is that if it gets off the path once, it'll keep saying that it ended up off the path, and not realize when it arrived at the location properly (but it does arrive).<br />
<br />
I've also started a bit on a person db - it stores the last known locations of players. This is something that is useful to everybody, so it's best that we don't have to keep reimplementing ourselves but use a common version. This requires more triggers to feed it's hunger for data as well!<br />
<br />
* track which rooms you've visited, and have an option to highlight unvisited rooms<br />
* show only game-relevant mconfig options<br />
<br />
[[Category:Mudlet Package Listing]]</div>Demonnichttps://wiki.mudlet.org/index.php?title=Area_51&diff=20436Area 512023-05-01T17:09:27Z<p>Demonnic: /* deleteMultiline PR-6779 open */</p>
<hr />
<div>{{TOC right}}<br />
<br />
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 [[Manual:Lua_Functions|Lua Functions]] and its sub-sites. <br />
<br />
Please use the [[Area_51/Template]] to add new entries in the sections below.<br />
<br />
Links to other functions or parts in other sections (i.e. the main Wiki area) need to include the section details before the <nowiki>'#'</nowiki> character in the link identifier on the left side of the <nowiki>'|'</nowiki> divider between the identifier and the display text. e.g.<br />
:: <nowiki>[[Manual:Mapper_Functions#getCustomLines|getCustomLines()]]</nowiki><br />
rather than:<br />
:: <nowiki>[[#getCustomLines|getCustomLines()]]</nowiki><br />
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!<br />
<br />
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.<br />
<br />
<br />
=Basic Essential Functions=<br />
:These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.<br />
<br />
=Database Functions=<br />
:A collection of functions for helping deal with the database.<br />
<br />
=Date/Time Functions=<br />
: A collection of functions for handling date & time.<br />
<br />
=File System Functions=<br />
: A collection of functions for interacting with the file system.<br />
<br />
=Mapper Functions=<br />
: A collection of functions that manipulate the mapper and its related features.<br />
<br />
==getMapZoom, PR #6615==<br />
;getMapZoom([areaID])<br />
<br />
:Gets the current 2D map zoom level. Added in '''Mudlet ''tba''''' 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.<br />
<br />
<!--will need to insert "Manual:Mapper_Functions" prior to # when moved to that documentation area--><br />
:See also: [[#setMapZoom|setMapZoom()]].<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6615<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID number to get the 2D zoom for (''optional'', the function works on the area currently being viewed if this is omitted).<br />
<br />
;Returns<br />
* A floating point number on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo("\nCurrent zoom level: " .. getMapZoom() .. "\n")<br />
-- Could be anything from 3 upwards:<br />
<br />
Current zoom level: 42.4242<br />
<br />
setMapZoom(2.5 + getMapZoom(1), 1) -- zoom out the area with ID 1 by 2.5<br />
true<br />
</syntaxhighlight><br />
<br />
{{note}} The precise meaning of a particular zoom value may have an underlying meaning however that bit of the code is rather old and no current coder has determined the significance, so far - 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!<br />
<br />
==mapSymbolFontInfo, PR #4038 closed==<br />
;mapSymbolFontInfo()<br />
: See also: [[#setupMapSymbolFont|setupMapSymbolFont()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;returns<br />
* either a table of information about the configuration of the font used for symbols in the (2D) map, the elements are:<br />
:* ''fontName'' - a string of the family name of the font specified<br />
:* ''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.<br />
:* ''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).<br />
* or ''nil'' and an error message on failure.<br />
<br />
::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).<br />
<br />
==moveMapLabel, PR #6014 open==<br />
;moveMapLabel(areaID/Name, labeID/Text, coordX/deltaX, coordY/deltaY[, coordZ/deltaZ][, absoluteNotRelativeMove])<br />
Re-positions a map label within an area in the 2D mapper, in a similar manner as the [[#moveRoom|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).<br />
<br />
:See also: [[Manual:Mapper_Functions#getMapLabels|getMapLabels()]], [[Manual:Mapper_Functions#getMapLabel|getMapLabel()]].<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6014<br />
<br />
;Parameters<br />
* ''areaID/Name:''<br />
: Area ID as number or AreaName as string containing the map label.<br />
<br />
* ''labelID/Text:''<br />
: 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.<br />
<br />
* ''coordX/deltaX:''<br />
: 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.<br />
<br />
* ''coordY/deltaY:''<br />
: 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.<br />
<br />
* ''coordZ/deltaZ:''<br />
: (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.<br />
<br />
* ''absoluteNotRelativeMove:''<br />
: (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'').<br />
<br />
;Returns<br />
: ''true'' on success or ''nil'' and an error message on failure, if successful it will also refresh the map display to show the result.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- move the first label in the area with the ID number of 2, three spaces to the east and four spaces to the north<br />
moveMapLabel(0, 2, 3.0, 4.0)<br />
<br />
-- 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<br />
moveMapLabel(0, 2, -1.0, 0.0, false)<br />
<br />
-- 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**:<br />
moveRoom(1, 2, -3.5, -2.0, true)<br />
<br />
-- move the second label in the area with the ID number of 2, up three levels<br />
moveRoom(1, 2, 0.0, 0.0, 3.0)<br />
<br />
-- move the second label in the "Test 1" area one space to the west, note the last two arguments are unneeded<br />
moveRoom("Test 1", 1, -1.0, 0.0, 0.0, false)<br />
<br />
-- 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:<br />
moveRoom(5, "Home", 0.0, 0.0, 0.0, true)<br />
<br />
-- all of the above will return the 'true' boolean value assuming there are the indicated labels and areas<br />
</syntaxhighlight><br />
<br />
==moveRoom, PR #6010 open==<br />
;moveRoom(roomID, coordX/deltaX, coordY/deltaY[, coordZ/deltaZ][, absoluteNotRelativeMove])<br />
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 [[Manual:Mapper_Functions#setRoomCoordinates|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.<br />
<br />
:See also: [[Manual:Mapper_Functions#setRoomCoordinates|setRoomCoordinates()]]<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6010<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID number to move.<br />
<br />
* ''coordX/deltaX:''<br />
: The absolute coordinate or the relative amount as a number to move the room in "room coordinates" along the X-axis.<br />
<br />
* ''coordY/deltaY:''<br />
: The absolute coordinate or the relative amount as a number to move the room in "room coordinates" along the Y-axis.<br />
<br />
* ''coordZ/deltaZ:''<br />
: (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.<br />
<br />
* ''absoluteNotRelativeMove:''<br />
: (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'').<br />
<br />
;Returns<br />
: ''true'' on success or ''nil'' and an error message on failure, if successful it will also refresh the map display to show the result.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- move the first room one space to the east and two spaces to the north<br />
moveRoom(1, 1, 2)<br />
<br />
-- move the first room one space to the west, note the final boolean argument is unneeded<br />
moveRoom(1, -1, 0, false)<br />
<br />
-- 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**:<br />
moveRoom(1, -3, -2, true)<br />
<br />
-- move the second room up three levels<br />
moveRoom(2, 0, 0, 3)<br />
<br />
-- move the second room one space to the west, note the last two arguments are unneeded<br />
moveRoom(2, -1, 0, 0, false)<br />
<br />
-- move the second room to the **center of the whole map**, note the last two arguments are required in this case:<br />
moveRoom(2, 0, 0, 0, true)<br />
<br />
-- all of the above will return the 'true' boolean value assuming there are rooms with 1 and 2 as ID numbers<br />
</syntaxhighlight><br />
<br />
==setMapZoom (revised), PR #6615==<br />
;setMapZoom(zoom[, areaID])<br />
<br />
:Zooms the 2D (only) map to a given zoom level. Larger numbers zooms the map further out. Revised in '''Mudlet ''tba''''' 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.<br />
<br />
<!--will need to insert "Manual:Mapper_Functions" prior to # when moved to that documentation area--><br />
:See also: [[#getMapZoom|getMapZoom()]].<br />
<br />
{{note}} The additional areaID parameter and the returned values described below are pending, they are not yet available/produced. See https://github.com/Mudlet/Mudlet/pull/6615<br />
<br />
;Parameters<br />
* ''zoom:''<br />
: floating point number that is at least 3.0 to set the zoom to.<br />
<br />
* ''areaID:''<br />
: Area ID number to adjust the 2D zoom for (''optional'', the function works on the area currently being viewed if this is omitted).<br />
<br />
;Returns (only since '''Mudlet ''tba''''')<br />
* ''true'' on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setMapZoom(10.0) -- zoom to a somewhat acceptable level, a bit big but easily visible connections<br />
true<br />
<br />
setMapZoom(2.5 + getMapZoom(1), 1) -- zoom out the area with ID 1 by 2.5<br />
true<br />
</syntaxhighlight><br />
<br />
{{note}} The precise meaning of a particular zoom value may have an underlying meaning however that bit of the code is rather old and no current coder has determined the significance, so far - 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!<br />
<br />
==setupMapSymbolFont, PR #4038 closed==<br />
;setupMapSymbolFont(fontName[, onlyUseThisFont[, scalingFactor]])<br />
:configures the font used for symbols in the (2D) map.<br />
: See also: [[#mapSymbolFontInfo|mapSymbolFontInfo()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;Parameters<br />
* ''fontName'' one of:<br />
:* - a string that is the family name of the font to use;<br />
:* - the empty string ''""'' to reset to the default {which is '''"Bitstream Vera Sans Mono"'''};<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow a following one to be modified.<br />
* ''onlyUseThisFont'' (optional) one of:<br />
:* - 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;<br />
:* - 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;<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow the following one to be modified.<br />
* ''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.<br />
<br />
;Returns<br />
* ''true'' on success<br />
* ''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).<br />
<br />
=Miscellaneous Functions=<br />
: Miscellaneous functions.<br />
<br />
==createVideoPlayer, PR #6439==<br />
;createVideoPlayer([name of userwindow], x, y, width, height)<br />
<br />
: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.<br />
<br />
{{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.<br />
<br />
{{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.<br />
<br />
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]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a 300x300 video player in the top-left corner of Mudlet<br />
createVideoPlayer(0,0,300,300)<br />
<br />
-- Alternative examples using Geyser.VideoPlayer<br />
GUI.VideoPlayer = GUI.VideoPlayer or Geyser.VideoPlayer:new({name="GUI.VideoPlayer", x = 0, y = 0, width = "25%", height = "25%"})<br />
<br />
GUI.VideoPlayer = GUI.VideoPlayer or Geyser.VideoPlayer:new({<br />
name = "GUI.VideoPlayer",<br />
x = "70%", y = 0, -- edit here if you want to move it<br />
width = "30%", height = "50%"<br />
}, GUI.Right)<br />
</syntaxhighlight><br />
<br />
==loadVideoFile, PR #6439==<br />
;loadVideoFile(settings table) or loadVideoFile(name, [url])<br />
:Loads video files from the Internet or the local file system to the "media" folder of the profile for later use with [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]] and [[Manual:Miscellaneous_Functions#stopVideos|stopVideos()]]. Although files could be loaded or streamed directly at playing time from [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]], loadVideoFile() provides the advantage of loading files in advance.<br />
<br />
{{note}} Video files consume drive space on your device. Consider using the streaming feature of [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]] for large files.<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
! style="text-align:left;" |Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;" |Yes<br />
|name<br />
|<file name><br />
| style="text-align:left;" |<br />
*Name of the media file.<br />
*May contain directory information (i.e. weather/maelstrom.mp4).<br />
*May be part of the profile (i.e. getMudletHomeDir().. "/congratulations.mp4")<br />
*May be on the local device (i.e. "C:/Users/YourNameHere/Movies/nevergoingtogiveyouup.mp4")<br />
|- style="color: blue;"<br />
| style="text-align:center;" |Maybe<br />
|url<br />
|<url><br />
| style="text-align:left;" |<br />
*Resource location where the media file may be downloaded.<br />
*Only required if file to load is not part of the profile or on the local file system.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#playSoundFile|loadSoundFile()]], [[Manual:Miscellaneous Functions#loadMusicFile|loadMusicFile()]], [[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#createVideoPlayer|createVideoPlayer()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Download from the Internet<br />
loadVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
})<br />
<br />
-- OR download from the profile<br />
loadVideoFile({name = getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4"})<br />
<br />
-- OR download from the local file system<br />
loadVideoFile({name = "C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4"})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of loadVideoFile(name[, url]) ----<br />
<br />
-- Download from the Internet<br />
loadVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4"<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
)<br />
<br />
-- OR download from the profile<br />
loadVideoFile(getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4")<br />
<br />
-- OR download from the local file system<br />
loadVideoFile("C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4")<br />
</syntaxhighlight><br />
<br />
==playVideoFile, PR #6439==<br />
;playVideoFile(settings table)<br />
:Plays video files from the Internet or the local file system for later use with [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]]. Video files may be downloaded to the device and played, or streamed from the Internet when the value of the <code>stream</code> parameter is <code>true</code>.<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
!Default<br />
! style="text-align:left;" |Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;" |Yes<br />
|name<br />
|<file name><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Name of the media file.<br />
*May contain directory information (i.e. weather/maelstrom.mp4).<br />
*May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp4")<br />
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp4")<br />
*Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.<br />
|-<br />
| style="text-align:center;" |No<br />
| volume<br />
|1 to 100<br />
|50<br />
| style="text-align:left;" |<br />
*Relative to the volume set on the player's client.<br />
|-<br />
| style="text-align:center;" |No<br />
|fadein<br />
|<msec><br />
|<br />
|<br />
*Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.<br />
*Start position: Start of media.<br />
*End position: Start of media plus the number of milliseconds (msec) specified.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
|fadeout<br />
|<msec><br />
|<br />
|<br />
*Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.<br />
*Start position: End of the media minus the number of milliseconds (msec) specified.<br />
*End position: End of the media.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
|start<br />
|<msec><br />
| 0<br />
| style="text-align:left;" |<br />
*Begin play at the specified position in milliseconds.<br />
|-<br />
| style="text-align:center;" |No<br />
|loops<br />
| -1, or >= 1<br />
|1<br />
| style="text-align:left;" |<br />
*Number of iterations that the media plays.<br />
*A value of -1 allows the media to loop indefinitely.<br />
|-<br />
| style="text-align:center;" |No<br />
|key<br />
|<key><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;" |No<br />
|tag<br />
|<tag><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Helps categorize media.<br />
|-<br />
| style="text-align:center;" |No<br />
|continue<br />
|true or false<br />
|true<br />
| style="text-align:left;" |<br />
*Continues playing matching new video files when true.<br />
*Restarts matching new video files when false.<br />
|- style="color: blue;"<br />
| style="text-align:center;" |Maybe<br />
|url<br />
|<url><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Resource location where the media file may be downloaded.<br />
*Only required if the file is to be downloaded remotely or for streaming from the Internet.<br />
|- style="color: blue;"<br />
| style="text-align:center;" |Maybe<br />
|stream<br />
|true or false<br />
|false<br />
| style="text-align:left;" |<br />
*Streams files from the Internet when true.<br />
*Download files when false (default).<br />
*Used in combination with the `url` key.<br />
|-<br />
|}<br />
<br />
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#stopSounds|stopSounds()]], [[Manual:Miscellaneous Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous Functions#stopVideos|stopVideos()]], [[Manual:Miscellaneous Functions#createVideoPlayer|createVideoPlayer()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stream a video file from the Internet and play it.<br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
, stream = true<br />
})<br />
<br />
-- 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.<br />
<br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
})<br />
<br />
-- Play a video file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
})<br />
<br />
-- OR copy once from the game's profile, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile({<br />
name = getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4"<br />
, volume = 75<br />
})<br />
<br />
-- OR copy once from the local file system, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile({<br />
name = "C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4"<br />
, volume = 75<br />
})<br />
<br />
-- OR download once from the Internet, and play a video stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 10 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 15 seconds from the end of the video<br />
---- [start] 5 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [key] reference of "text" for stopping this unique video later<br />
---- [tag] reference of "ambience" to stop any video later with the same tag<br />
---- [continue] playing this video if another request for the same video comes in (false restarts it) <br />
---- [url] resource location where the file may be accessed on the Internet<br />
---- [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) <br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, volume = nil -- nil lines are optional, no need to use<br />
, fadein = 10000<br />
, fadeout = 15000<br />
, start = 5000<br />
, loops = nil -- nil lines are optional, no need to use<br />
, key = "text"<br />
, tag = "ambience"<br />
, continue = true<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
, stream = false<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of playVideoFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,continue][,url][,stream]) ----<br />
<br />
-- Stream a video file from the Internet and play it.<br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4"<br />
, nil -- volume<br />
, nil -- fadein<br />
, nil -- fadeout<br />
, nil -- start<br />
, nil -- loops<br />
, nil -- key<br />
, nil -- tag<br />
, true -- continue<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/" -- url<br />
, false -- stream<br />
)<br />
<br />
-- 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.<br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4"<br />
, nil -- volume<br />
, nil -- fadein<br />
, nil -- fadeout<br />
, nil -- start<br />
, nil -- loops<br />
, nil -- key<br />
, nil -- tag<br />
, true -- continue<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/" -- url<br />
, false -- stream<br />
)<br />
<br />
-- Play a video file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4" -- name<br />
)<br />
<br />
-- OR copy once from the game's profile, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile(<br />
getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR copy once from the local file system, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile(<br />
"C:/Users/Tamarindo/Documents/TextInMotion-VideoSample-1080p.mp4" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR download once from the Internet, and play a video stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 10 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 15 seconds from the end of the video<br />
---- [start] 5 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [key] reference of "text" for stopping this unique video later<br />
---- [tag] reference of "ambience" to stop any video later with the same tag<br />
---- [continue] playing this video if another request for the same video comes in (false restarts it) <br />
---- [url] resource location where the file may be accessed on the Internet<br />
---- [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) <br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4" -- name<br />
, nil -- volume<br />
, 10000 -- fadein<br />
, 15000 -- fadeout<br />
, 5000 -- start<br />
, nil -- loops<br />
, "text" -- key<br />
, "ambience" -- tag<br />
, true -- continue<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/" -- url<br />
, false -- stream<br />
)<br />
</syntaxhighlight><br />
<br />
<br />
==stopVideos, PR #6439==<br />
;stopVideos(settings table)<br />
:Stop all videos (no filter), or videos that meet a combination of filters (name, key, and tag) intended to be paired with [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]].<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
! style="text-align:left;" |Purpose<br />
|-<br />
| style="text-align:center;" |No<br />
| name<br />
| <file name><br />
| style="text-align:left;" |<br />
* Name of the media file.<br />
|-<br />
| style="text-align:center;" |No<br />
|key<br />
|<key><br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;" |No<br />
|tag<br />
|<tag><br />
| style="text-align:left;" |<br />
*Helps categorize media.<br />
|-<br />
|}<br />
<br />
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#createVideoPlayer|createVideoPlayer()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stop all playing video files for this profile associated with the API<br />
stopVideos()<br />
<br />
-- Stop playing the text mp4 by name<br />
stopVideos({name = "TextInMotion-VideoSample-1080p.mp4"})<br />
<br />
-- Stop playing the unique sound identified as "text"<br />
stopVideos({<br />
name = nil -- nil lines are optional, no need to use<br />
, key = "text" -- key<br />
, tag = nil -- nil lines are optional, no need to use<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of stopVideos([name][,key][,tag]) ----<br />
<br />
-- Stop all playing video files for this profile associated with the API<br />
stopVideos()<br />
<br />
-- Stop playing the text mp4 by name<br />
stopVideos("TextInMotion-VideoSample-1080p.mp4")<br />
<br />
-- Stop playing the unique sound identified as "text"<br />
stopVideos(<br />
nil -- name<br />
, "text" -- key<br />
, nil -- tag<br />
)<br />
</syntaxhighlight><br />
<br />
<br />
==getCustomLoginTextId, PR #3952 open==<br />
;getCustomLoginTextId()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#sendPassword|sendPassword()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+Predefined custom login texts<br />
|-<br />
!Id!!Custom text!!Introduced in Mudlet version<br />
|-<br />
|1||"connect {character name} {password}"||TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCharacterName, PR #3952 open==<br />
;sendCharacterName()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
==sendCharacterPassword, PR #3952 open==<br />
;sendCharacterPassword()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]], [[#sendCharacterName|sendCharacterName()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCharacterName() ~= "" then<br />
tempTime(2.0, [[sendCharacterName()]], 1)<br />
tempTime(3.0, [[sendCharacterPassword()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCustomLoginText, PR #3952 open ==<br />
;sendCustomLoginText()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendPassword|sendPassword()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+Predefined custom login texts<br />
|-<br />
!Id!!Custom text!!Introduced in Mudlet version<br />
|-<br />
|1||"connect {character name} {password}"||TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
=Mudlet Object Functions=<br />
:A collection of functions that manipulate Mudlets scripting objects - triggers, aliases, and so forth.<br />
<br />
=Networking Functions=<br />
:A collection of functions for managing networking.<br />
<br />
=String Functions=<br />
:These functions are used to manipulate strings.<br />
<br />
=Table Functions=<br />
: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.<br />
<br />
=Text to Speech Functions=<br />
:These functions are used to create sound from written words. Check out our [[Special:MyLanguage/Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.<br />
<br />
=UI Functions=<br />
: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.<br />
<br />
==deleteMultiline PR-6779 merged==<br />
<br />
; ok,err = deleteMultiline([triggerDelta])<br />
<br />
:Deletes all lines between when the multiline trigger fires and when the first trigger matched. Put another way, it deletes everything since the pattern in slot 1 matched.<br />
;See also: [[Manual:Lua_Functions#deleteLine|deleteLine()]], [[Manual:Lua_Functions#replaceLine|replaceLine()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
{{note}} This deletes all the lines since the first match of the multiline trigger matched. Do not use this if you donot want to delete ALL of those lines.<br />
<br />
;Parameters<br />
* ''[optional]triggerDelta:''<br />
: The line delta from the multiline trigger it is being called from. It is best to pass this in to ensure all lines are caught. If not given it will try to guess based on the number of patterns how many lines at most it might have to delete.<br />
<br />
;Returns <br />
* true if the function was able to run successfully, nil+error if something went wrong.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- if this trigger has a line delta of 3, you would call<br />
deleteMultiline(3)<br />
<br />
-- same thing, but with error handling<br />
local ok,err = deleteMultiline(3)<br />
if not ok then<br />
cecho("\n<firebrick>I could not delete the lines because: " .. err)<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
=Discord Functions=<br />
: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 [[Special:MyLanguage/Manual:Scripting#Discord_Rich_Presence|Discord scripting overview]].<br />
<br />
=Events=<br />
:New or revised events that Mudlet can raise to inform a profile about changes. See [[Manual:Event_Engine#Mudlet-raised_events|Mudlet-raised events]] for the existing ones.<br />
<br />
===sysMapAreaChanged, PR #6615===<br />
Raised when the area being viewed in the mapper is changed, either by the player-room being set to a new area or the user selecting a different area in the area selection combo-box in the mapper controls area. Returns two additional arguments being the areaID of the area being switched to and then the one for the area that is being left.<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6615</div>Demonnichttps://wiki.mudlet.org/index.php?title=Area_51&diff=20433Area 512023-04-26T16:01:02Z<p>Demonnic: /* UI Functions */</p>
<hr />
<div>{{TOC right}}<br />
<br />
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 [[Manual:Lua_Functions|Lua Functions]] and its sub-sites. <br />
<br />
Please use the [[Area_51/Template]] to add new entries in the sections below.<br />
<br />
Links to other functions or parts in other sections (i.e. the main Wiki area) need to include the section details before the <nowiki>'#'</nowiki> character in the link identifier on the left side of the <nowiki>'|'</nowiki> divider between the identifier and the display text. e.g.<br />
:: <nowiki>[[Manual:Mapper_Functions#getCustomLines|getCustomLines()]]</nowiki><br />
rather than:<br />
:: <nowiki>[[#getCustomLines|getCustomLines()]]</nowiki><br />
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!<br />
<br />
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.<br />
<br />
<br />
=Basic Essential Functions=<br />
:These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.<br />
<br />
=Database Functions=<br />
:A collection of functions for helping deal with the database.<br />
<br />
=Date/Time Functions=<br />
: A collection of functions for handling date & time.<br />
<br />
=File System Functions=<br />
: A collection of functions for interacting with the file system.<br />
<br />
=Mapper Functions=<br />
: A collection of functions that manipulate the mapper and its related features.<br />
<br />
==getMapZoom, PR #6615==<br />
;getMapZoom([areaID])<br />
<br />
:Gets the current 2D map zoom level. Added in '''Mudlet ''tba''''' 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.<br />
<br />
<!--will need to insert "Manual:Mapper_Functions" prior to # when moved to that documentation area--><br />
:See also: [[#setMapZoom|setMapZoom()]].<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6615<br />
<br />
;Parameters<br />
* ''areaID:''<br />
: Area ID number to get the 2D zoom for (''optional'', the function works on the area currently being viewed if this is omitted).<br />
<br />
;Returns<br />
* A floating point number on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo("\nCurrent zoom level: " .. getMapZoom() .. "\n")<br />
-- Could be anything from 3 upwards:<br />
<br />
Current zoom level: 42.4242<br />
<br />
setMapZoom(2.5 + getMapZoom(1), 1) -- zoom out the area with ID 1 by 2.5<br />
true<br />
</syntaxhighlight><br />
<br />
{{note}} The precise meaning of a particular zoom value may have an underlying meaning however that bit of the code is rather old and no current coder has determined the significance, so far - 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!<br />
<br />
==mapSymbolFontInfo, PR #4038 closed==<br />
;mapSymbolFontInfo()<br />
: See also: [[#setupMapSymbolFont|setupMapSymbolFont()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;returns<br />
* either a table of information about the configuration of the font used for symbols in the (2D) map, the elements are:<br />
:* ''fontName'' - a string of the family name of the font specified<br />
:* ''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.<br />
:* ''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).<br />
* or ''nil'' and an error message on failure.<br />
<br />
::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).<br />
<br />
==moveMapLabel, PR #6014 open==<br />
;moveMapLabel(areaID/Name, labeID/Text, coordX/deltaX, coordY/deltaY[, coordZ/deltaZ][, absoluteNotRelativeMove])<br />
Re-positions a map label within an area in the 2D mapper, in a similar manner as the [[#moveRoom|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).<br />
<br />
:See also: [[Manual:Mapper_Functions#getMapLabels|getMapLabels()]], [[Manual:Mapper_Functions#getMapLabel|getMapLabel()]].<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6014<br />
<br />
;Parameters<br />
* ''areaID/Name:''<br />
: Area ID as number or AreaName as string containing the map label.<br />
<br />
* ''labelID/Text:''<br />
: 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.<br />
<br />
* ''coordX/deltaX:''<br />
: 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.<br />
<br />
* ''coordY/deltaY:''<br />
: 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.<br />
<br />
* ''coordZ/deltaZ:''<br />
: (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.<br />
<br />
* ''absoluteNotRelativeMove:''<br />
: (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'').<br />
<br />
;Returns<br />
: ''true'' on success or ''nil'' and an error message on failure, if successful it will also refresh the map display to show the result.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- move the first label in the area with the ID number of 2, three spaces to the east and four spaces to the north<br />
moveMapLabel(0, 2, 3.0, 4.0)<br />
<br />
-- 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<br />
moveMapLabel(0, 2, -1.0, 0.0, false)<br />
<br />
-- 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**:<br />
moveRoom(1, 2, -3.5, -2.0, true)<br />
<br />
-- move the second label in the area with the ID number of 2, up three levels<br />
moveRoom(1, 2, 0.0, 0.0, 3.0)<br />
<br />
-- move the second label in the "Test 1" area one space to the west, note the last two arguments are unneeded<br />
moveRoom("Test 1", 1, -1.0, 0.0, 0.0, false)<br />
<br />
-- 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:<br />
moveRoom(5, "Home", 0.0, 0.0, 0.0, true)<br />
<br />
-- all of the above will return the 'true' boolean value assuming there are the indicated labels and areas<br />
</syntaxhighlight><br />
<br />
==moveRoom, PR #6010 open==<br />
;moveRoom(roomID, coordX/deltaX, coordY/deltaY[, coordZ/deltaZ][, absoluteNotRelativeMove])<br />
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 [[Manual:Mapper_Functions#setRoomCoordinates|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.<br />
<br />
:See also: [[Manual:Mapper_Functions#setRoomCoordinates|setRoomCoordinates()]]<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6010<br />
<br />
;Parameters<br />
* ''roomID:''<br />
: Room ID number to move.<br />
<br />
* ''coordX/deltaX:''<br />
: The absolute coordinate or the relative amount as a number to move the room in "room coordinates" along the X-axis.<br />
<br />
* ''coordY/deltaY:''<br />
: The absolute coordinate or the relative amount as a number to move the room in "room coordinates" along the Y-axis.<br />
<br />
* ''coordZ/deltaZ:''<br />
: (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.<br />
<br />
* ''absoluteNotRelativeMove:''<br />
: (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'').<br />
<br />
;Returns<br />
: ''true'' on success or ''nil'' and an error message on failure, if successful it will also refresh the map display to show the result.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- move the first room one space to the east and two spaces to the north<br />
moveRoom(1, 1, 2)<br />
<br />
-- move the first room one space to the west, note the final boolean argument is unneeded<br />
moveRoom(1, -1, 0, false)<br />
<br />
-- 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**:<br />
moveRoom(1, -3, -2, true)<br />
<br />
-- move the second room up three levels<br />
moveRoom(2, 0, 0, 3)<br />
<br />
-- move the second room one space to the west, note the last two arguments are unneeded<br />
moveRoom(2, -1, 0, 0, false)<br />
<br />
-- move the second room to the **center of the whole map**, note the last two arguments are required in this case:<br />
moveRoom(2, 0, 0, 0, true)<br />
<br />
-- all of the above will return the 'true' boolean value assuming there are rooms with 1 and 2 as ID numbers<br />
</syntaxhighlight><br />
<br />
==setMapZoom (revised), PR #6615==<br />
;setMapZoom(zoom[, areaID])<br />
<br />
:Zooms the 2D (only) map to a given zoom level. Larger numbers zooms the map further out. Revised in '''Mudlet ''tba''''' 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.<br />
<br />
<!--will need to insert "Manual:Mapper_Functions" prior to # when moved to that documentation area--><br />
:See also: [[#getMapZoom|getMapZoom()]].<br />
<br />
{{note}} The additional areaID parameter and the returned values described below are pending, they are not yet available/produced. See https://github.com/Mudlet/Mudlet/pull/6615<br />
<br />
;Parameters<br />
* ''zoom:''<br />
: floating point number that is at least 3.0 to set the zoom to.<br />
<br />
* ''areaID:''<br />
: Area ID number to adjust the 2D zoom for (''optional'', the function works on the area currently being viewed if this is omitted).<br />
<br />
;Returns (only since '''Mudlet ''tba''''')<br />
* ''true'' on success<br />
* ''nil'' and an error message on failure.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setMapZoom(10.0) -- zoom to a somewhat acceptable level, a bit big but easily visible connections<br />
true<br />
<br />
setMapZoom(2.5 + getMapZoom(1), 1) -- zoom out the area with ID 1 by 2.5<br />
true<br />
</syntaxhighlight><br />
<br />
{{note}} The precise meaning of a particular zoom value may have an underlying meaning however that bit of the code is rather old and no current coder has determined the significance, so far - 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!<br />
<br />
==setupMapSymbolFont, PR #4038 closed==<br />
;setupMapSymbolFont(fontName[, onlyUseThisFont[, scalingFactor]])<br />
:configures the font used for symbols in the (2D) map.<br />
: See also: [[#mapSymbolFontInfo|mapSymbolFontInfo()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;Parameters<br />
* ''fontName'' one of:<br />
:* - a string that is the family name of the font to use;<br />
:* - the empty string ''""'' to reset to the default {which is '''"Bitstream Vera Sans Mono"'''};<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow a following one to be modified.<br />
* ''onlyUseThisFont'' (optional) one of:<br />
:* - 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;<br />
:* - 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;<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow the following one to be modified.<br />
* ''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.<br />
<br />
;Returns<br />
* ''true'' on success<br />
* ''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).<br />
<br />
=Miscellaneous Functions=<br />
: Miscellaneous functions.<br />
<br />
==createVideoPlayer, PR #6439==<br />
;createVideoPlayer([name of userwindow], x, y, width, height)<br />
<br />
: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.<br />
<br />
{{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.<br />
<br />
{{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.<br />
<br />
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]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a 300x300 video player in the top-left corner of Mudlet<br />
createVideoPlayer(0,0,300,300)<br />
<br />
-- Alternative examples using Geyser.VideoPlayer<br />
GUI.VideoPlayer = GUI.VideoPlayer or Geyser.VideoPlayer:new({name="GUI.VideoPlayer", x = 0, y = 0, width = "25%", height = "25%"})<br />
<br />
GUI.VideoPlayer = GUI.VideoPlayer or Geyser.VideoPlayer:new({<br />
name = "GUI.VideoPlayer",<br />
x = "70%", y = 0, -- edit here if you want to move it<br />
width = "30%", height = "50%"<br />
}, GUI.Right)<br />
</syntaxhighlight><br />
<br />
==loadVideoFile, PR #6439==<br />
;loadVideoFile(settings table) or loadVideoFile(name, [url])<br />
:Loads video files from the Internet or the local file system to the "media" folder of the profile for later use with [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]] and [[Manual:Miscellaneous_Functions#stopVideos|stopVideos()]]. Although files could be loaded or streamed directly at playing time from [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]], loadVideoFile() provides the advantage of loading files in advance.<br />
<br />
{{note}} Video files consume drive space on your device. Consider using the streaming feature of [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]] for large files.<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
! style="text-align:left;" |Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;" |Yes<br />
|name<br />
|<file name><br />
| style="text-align:left;" |<br />
*Name of the media file.<br />
*May contain directory information (i.e. weather/maelstrom.mp4).<br />
*May be part of the profile (i.e. getMudletHomeDir().. "/congratulations.mp4")<br />
*May be on the local device (i.e. "C:/Users/YourNameHere/Movies/nevergoingtogiveyouup.mp4")<br />
|- style="color: blue;"<br />
| style="text-align:center;" |Maybe<br />
|url<br />
|<url><br />
| style="text-align:left;" |<br />
*Resource location where the media file may be downloaded.<br />
*Only required if file to load is not part of the profile or on the local file system.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#playSoundFile|loadSoundFile()]], [[Manual:Miscellaneous Functions#loadMusicFile|loadMusicFile()]], [[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#createVideoPlayer|createVideoPlayer()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Download from the Internet<br />
loadVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
})<br />
<br />
-- OR download from the profile<br />
loadVideoFile({name = getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4"})<br />
<br />
-- OR download from the local file system<br />
loadVideoFile({name = "C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4"})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of loadVideoFile(name[, url]) ----<br />
<br />
-- Download from the Internet<br />
loadVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4"<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
)<br />
<br />
-- OR download from the profile<br />
loadVideoFile(getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4")<br />
<br />
-- OR download from the local file system<br />
loadVideoFile("C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4")<br />
</syntaxhighlight><br />
<br />
==playVideoFile, PR #6439==<br />
;playVideoFile(settings table)<br />
:Plays video files from the Internet or the local file system for later use with [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]]. Video files may be downloaded to the device and played, or streamed from the Internet when the value of the <code>stream</code> parameter is <code>true</code>.<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
!Default<br />
! style="text-align:left;" |Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;" |Yes<br />
|name<br />
|<file name><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Name of the media file.<br />
*May contain directory information (i.e. weather/maelstrom.mp4).<br />
*May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp4")<br />
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp4")<br />
*Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.<br />
|-<br />
| style="text-align:center;" |No<br />
| volume<br />
|1 to 100<br />
|50<br />
| style="text-align:left;" |<br />
*Relative to the volume set on the player's client.<br />
|-<br />
| style="text-align:center;" |No<br />
|fadein<br />
|<msec><br />
|<br />
|<br />
*Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.<br />
*Start position: Start of media.<br />
*End position: Start of media plus the number of milliseconds (msec) specified.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
|fadeout<br />
|<msec><br />
|<br />
|<br />
*Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.<br />
*Start position: End of the media minus the number of milliseconds (msec) specified.<br />
*End position: End of the media.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
|start<br />
|<msec><br />
| 0<br />
| style="text-align:left;" |<br />
*Begin play at the specified position in milliseconds.<br />
|-<br />
| style="text-align:center;" |No<br />
|loops<br />
| -1, or >= 1<br />
|1<br />
| style="text-align:left;" |<br />
*Number of iterations that the media plays.<br />
*A value of -1 allows the media to loop indefinitely.<br />
|-<br />
| style="text-align:center;" |No<br />
|key<br />
|<key><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;" |No<br />
|tag<br />
|<tag><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Helps categorize media.<br />
|-<br />
| style="text-align:center;" |No<br />
|continue<br />
|true or false<br />
|true<br />
| style="text-align:left;" |<br />
*Continues playing matching new video files when true.<br />
*Restarts matching new video files when false.<br />
|- style="color: blue;"<br />
| style="text-align:center;" |Maybe<br />
|url<br />
|<url><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Resource location where the media file may be downloaded.<br />
*Only required if the file is to be downloaded remotely or for streaming from the Internet.<br />
|- style="color: blue;"<br />
| style="text-align:center;" |Maybe<br />
|stream<br />
|true or false<br />
|false<br />
| style="text-align:left;" |<br />
*Streams files from the Internet when true.<br />
*Download files when false (default).<br />
*Used in combination with the `url` key.<br />
|-<br />
|}<br />
<br />
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#stopSounds|stopSounds()]], [[Manual:Miscellaneous Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous Functions#stopVideos|stopVideos()]], [[Manual:Miscellaneous Functions#createVideoPlayer|createVideoPlayer()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stream a video file from the Internet and play it.<br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
, stream = true<br />
})<br />
<br />
-- 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.<br />
<br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
})<br />
<br />
-- Play a video file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
})<br />
<br />
-- OR copy once from the game's profile, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile({<br />
name = getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4"<br />
, volume = 75<br />
})<br />
<br />
-- OR copy once from the local file system, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile({<br />
name = "C:/Users/Tamarindo/Movies/TextInMotion-VideoSample-1080p.mp4"<br />
, volume = 75<br />
})<br />
<br />
-- OR download once from the Internet, and play a video stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 10 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 15 seconds from the end of the video<br />
---- [start] 5 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [key] reference of "text" for stopping this unique video later<br />
---- [tag] reference of "ambience" to stop any video later with the same tag<br />
---- [continue] playing this video if another request for the same video comes in (false restarts it) <br />
---- [url] resource location where the file may be accessed on the Internet<br />
---- [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) <br />
playVideoFile({<br />
name = "TextInMotion-VideoSample-1080p.mp4"<br />
, volume = nil -- nil lines are optional, no need to use<br />
, fadein = 10000<br />
, fadeout = 15000<br />
, start = 5000<br />
, loops = nil -- nil lines are optional, no need to use<br />
, key = "text"<br />
, tag = "ambience"<br />
, continue = true<br />
, url = "https://d2qguwbxlx1sbt.cloudfront.net/"<br />
, stream = false<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of playVideoFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,continue][,url][,stream]) ----<br />
<br />
-- Stream a video file from the Internet and play it.<br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4"<br />
, nil -- volume<br />
, nil -- fadein<br />
, nil -- fadeout<br />
, nil -- start<br />
, nil -- loops<br />
, nil -- key<br />
, nil -- tag<br />
, true -- continue<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/" -- url<br />
, false -- stream<br />
)<br />
<br />
-- 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.<br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4"<br />
, nil -- volume<br />
, nil -- fadein<br />
, nil -- fadeout<br />
, nil -- start<br />
, nil -- loops<br />
, nil -- key<br />
, nil -- tag<br />
, true -- continue<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/" -- url<br />
, false -- stream<br />
)<br />
<br />
-- Play a video file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4" -- name<br />
)<br />
<br />
-- OR copy once from the game's profile, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile(<br />
getMudletHomeDir().. "/TextInMotion-VideoSample-1080p.mp4" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR copy once from the local file system, and play a video file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playVideoFile(<br />
"C:/Users/Tamarindo/Documents/TextInMotion-VideoSample-1080p.mp4" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR download once from the Internet, and play a video stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 10 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 15 seconds from the end of the video<br />
---- [start] 5 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [key] reference of "text" for stopping this unique video later<br />
---- [tag] reference of "ambience" to stop any video later with the same tag<br />
---- [continue] playing this video if another request for the same video comes in (false restarts it) <br />
---- [url] resource location where the file may be accessed on the Internet<br />
---- [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) <br />
playVideoFile(<br />
"TextInMotion-VideoSample-1080p.mp4" -- name<br />
, nil -- volume<br />
, 10000 -- fadein<br />
, 15000 -- fadeout<br />
, 5000 -- start<br />
, nil -- loops<br />
, "text" -- key<br />
, "ambience" -- tag<br />
, true -- continue<br />
, "https://d2qguwbxlx1sbt.cloudfront.net/" -- url<br />
, false -- stream<br />
)<br />
</syntaxhighlight><br />
<br />
<br />
==stopVideos, PR #6439==<br />
;stopVideos(settings table)<br />
:Stop all videos (no filter), or videos that meet a combination of filters (name, key, and tag) intended to be paired with [[Manual:Miscellaneous_Functions#playVideoFile|playVideoFile()]].<br />
<br />
{| class="wikitable"<br />
!Required<br />
!Key<br />
!Value<br />
! style="text-align:left;" |Purpose<br />
|-<br />
| style="text-align:center;" |No<br />
| name<br />
| <file name><br />
| style="text-align:left;" |<br />
* Name of the media file.<br />
|-<br />
| style="text-align:center;" |No<br />
|key<br />
|<key><br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;" |No<br />
|tag<br />
|<tag><br />
| style="text-align:left;" |<br />
*Helps categorize media.<br />
|-<br />
|}<br />
<br />
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#createVideoPlayer|createVideoPlayer()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stop all playing video files for this profile associated with the API<br />
stopVideos()<br />
<br />
-- Stop playing the text mp4 by name<br />
stopVideos({name = "TextInMotion-VideoSample-1080p.mp4"})<br />
<br />
-- Stop playing the unique sound identified as "text"<br />
stopVideos({<br />
name = nil -- nil lines are optional, no need to use<br />
, key = "text" -- key<br />
, tag = nil -- nil lines are optional, no need to use<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of stopVideos([name][,key][,tag]) ----<br />
<br />
-- Stop all playing video files for this profile associated with the API<br />
stopVideos()<br />
<br />
-- Stop playing the text mp4 by name<br />
stopVideos("TextInMotion-VideoSample-1080p.mp4")<br />
<br />
-- Stop playing the unique sound identified as "text"<br />
stopVideos(<br />
nil -- name<br />
, "text" -- key<br />
, nil -- tag<br />
)<br />
</syntaxhighlight><br />
<br />
<br />
==getCustomLoginTextId, PR #3952 open==<br />
;getCustomLoginTextId()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#sendPassword|sendPassword()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+Predefined custom login texts<br />
|-<br />
!Id!!Custom text!!Introduced in Mudlet version<br />
|-<br />
|1||"connect {character name} {password}"||TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCharacterName, PR #3952 open==<br />
;sendCharacterName()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
==sendCharacterPassword, PR #3952 open==<br />
;sendCharacterPassword()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]], [[#sendCharacterName|sendCharacterName()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCharacterName() ~= "" then<br />
tempTime(2.0, [[sendCharacterName()]], 1)<br />
tempTime(3.0, [[sendCharacterPassword()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCustomLoginText, PR #3952 open ==<br />
;sendCustomLoginText()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendPassword|sendPassword()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+Predefined custom login texts<br />
|-<br />
!Id!!Custom text!!Introduced in Mudlet version<br />
|-<br />
|1||"connect {character name} {password}"||TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
=Mudlet Object Functions=<br />
:A collection of functions that manipulate Mudlets scripting objects - triggers, aliases, and so forth.<br />
<br />
=Networking Functions=<br />
:A collection of functions for managing networking.<br />
<br />
=String Functions=<br />
:These functions are used to manipulate strings.<br />
<br />
=Table Functions=<br />
: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.<br />
<br />
=Text to Speech Functions=<br />
:These functions are used to create sound from written words. Check out our [[Special:MyLanguage/Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.<br />
<br />
=UI Functions=<br />
: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.<br />
<br />
==deleteMultiline PR-6779 open==<br />
<br />
; ok,err = deleteMultiline([triggerDelta])<br />
<br />
:Deletes all lines between when the multiline trigger fires and when the first trigger matched. Put another way, it deletes everything since the pattern in slot 1 matched.<br />
;See also: [[Manual:Lua_Functions#deleteLine|deleteLine()]], [[Manual:Lua_Functions#replaceLine|replaceLine()]]<br />
<br />
{{MudletVersion|4.18}}<br />
<br />
{{note}} This deletes all the lines since the first match of the multiline trigger matched. Do not use this if you donot want to delete ALL of those lines.<br />
<br />
;Parameters<br />
* ''[optional]triggerDelta:''<br />
: The line delta from the multiline trigger it is being called from. It is best to pass this in to ensure all lines are caught. If not given it will try to guess based on the number of patterns how many lines at most it might have to delete.<br />
<br />
;Returns <br />
* true if the function was able to run successfully, nil+error if something went wrong.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- if this trigger has a line delta of 3, you would call<br />
deleteMultiline(3)<br />
<br />
-- same thing, but with error handling<br />
local ok,err = deleteMultiline(3)<br />
if not ok then<br />
cecho("\n<firebrick>I could not delete the lines because: " .. err)<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
=Discord Functions=<br />
: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 [[Special:MyLanguage/Manual:Scripting#Discord_Rich_Presence|Discord scripting overview]].<br />
<br />
=Events=<br />
:New or revised events that Mudlet can raise to inform a profile about changes. See [[Manual:Event_Engine#Mudlet-raised_events|Mudlet-raised events]] for the existing ones.<br />
<br />
===sysMapAreaChanged, PR #6615===<br />
Raised when the area being viewed in the mapper is changed, either by the player-room being set to a new area or the user selecting a different area in the area selection combo-box in the mapper controls area. Returns two additional arguments being the areaID of the area being switched to and then the one for the area that is being left.<br />
<br />
{{MudletVersion| ?.??}}<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6615</div>Demonnichttps://wiki.mudlet.org/index.php?title=HowTo:OpenInWindowsCmd&diff=20423HowTo:OpenInWindowsCmd2023-04-21T03:06:46Z<p>Demonnic: layout changes</p>
<hr />
<div>== Running Mudlet in the Windows command line ==<br />
Sometimes it can be helpful to run Mudlet in the command line, as it prints out some extra information there when you do so. Unfortunately, it is not immediately obvious how to do this on Windows. Fortunately, it's not that difficult once you know how.<br />
<br />
<br />
Open the command line by hitting windowskey+r, then typing cmd and hitting enter<br />
[[File:Running cmd in Windows.png|thumb|307x307px|alt=|center]]<br />
<br />
<br />
<br />
Then, once it opens the command window, you will want to type the following<syntaxhighlight lang="batch"><br />
cd %LOCALAPPDATA%\Mudlet\app-*<br />
Mudlet<br />
</syntaxhighlight>Which will launch Mudlet in such a way that it prints extra information to the command window as it runs.<br />
[[File:Running with output.png|thumb|Mudlet running with the extra output in the command window|alt=|center]]<br />
<br />
And that's all there is to it!</div>Demonnichttps://wiki.mudlet.org/index.php?title=HowTo:OpenInWindowsCmd&diff=20422HowTo:OpenInWindowsCmd2023-04-21T03:05:48Z<p>Demonnic: New page to describe how to open Mudlet in the command line on Windows</p>
<hr />
<div>== Running Mudlet in the Windows command line ==<br />
Sometimes it can be helpful to run Mudlet in the command line, as it prints out some extra information there when you do so. Unfortunately, it is not immediately obvious how to do this on Windows. Fortunately, it's not that difficult once you know how.<br />
<br />
<br />
Open the command line by hitting windowskey+r, then typing cmd and hitting enter<br />
[[File:Running cmd in Windows.png|left|thumb|307x307px]]<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
Then, once it opens the command window, you will want to type the following<syntaxhighlight lang="batch"><br />
cd %LOCALAPPDATA%\Mudlet\app-*<br />
Mudlet<br />
</syntaxhighlight>Which will launch Mudlet in such a way that it prints extra information to the command window as it runs.<br />
[[File:Running with output.png|left|thumb|Mudlet running with the extra output in the command window]]<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
And that's all there is to it!</div>Demonnichttps://wiki.mudlet.org/index.php?title=File:Running_with_output.png&diff=20421File:Running with output.png2023-04-21T03:04:33Z<p>Demonnic: </p>
<hr />
<div>Shows Mudlet running in Windows Command window, with the extra output that entails</div>Demonnichttps://wiki.mudlet.org/index.php?title=File:Running_cmd_in_Windows.png&diff=20420File:Running cmd in Windows.png2023-04-21T02:59:12Z<p>Demonnic: </p>
<hr />
<div>Shows the screen used for running cmd in Windows</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:Mudlet_Object_Functions&diff=20401Manual:Mudlet Object Functions2023-04-02T15:15:20Z<p>Demonnic: /* isActive */</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Mudlet API documentation for functions to manipulate Mudlet's scripting objects - triggers, aliases, and so forth.}}<br />
= Mudlet Object Functions =<br />
Collection of functions to manipulate Mudlet's scripting objects - triggers, aliases, and so forth.<br />
<br />
==addCmdLineSuggestion==<br />
;addCmdLineSuggestion([name], suggestion)<br />
: Add suggestion for tab completion for specified command line.<br />
<br />
: For example, start typing ''he'' and hit ''TAB'' until ''help'' appears in command line.<br />
: Non-word characters are skipped (this is the reason why they can't be added at start of suggestion), therefore it's also possible to type: ''/he'' and hit ''TAB''.<br />
<br />
: See also: [[Manual:Lua_Functions#clearCmdLineSuggestions|clearCmdLineSuggestions()]], [[Manual:Lua_Functions#removeCmdLineSuggestion|removeCmdLineSuggestion()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
;Parameters<br />
* ''name'': optional command line name, if skipped main command line will be used<br />
* ''suggestion'' - suggestion as a single word to add to tab completion (only the following are allowed: ''0-9A-Za-z_'')<br />
<br />
Example:<br />
<syntaxhighlight lang="lua"><br />
addCmdLineSuggestion("help")<br />
<br />
local suggestions = {"Pneumonoultramicroscopicsilicovolcanoconiosis", "supercalifragilisticexpialidocious", "serendipitous"}<br />
for _, suggestion in ipairs(suggestions) do<br />
addCmdLineSuggestion(suggestion)<br />
end<br />
</syntaxhighlight><br />
<br />
==adjustStopWatch==<br />
;adjustStopWatch(watchID/watchName, amount)<br />
: Adjusts the elapsed time on the stopwatch forward or backwards by the amount of time. It will work even on stopwatches that are not running, and thus can be used to preset a newly created stopwatch with a negative amount so that it runs down from a negative time towards zero at the preset time.<br />
<br />
;Parameters<br />
* watchID (number) / watchName (string): The stopwatch ID you get with [[Manual:Lua_Functions#createStopWatch|createStopWatch()]] or the name given to that function or later set with [[Manual:Lua_Functions#setStopWatchName|setStopWatchName()]].<br />
* amount (decimal number): An amount in seconds to adjust the stopwatch by, positive amounts increase the recorded elapsed time.<br />
<br />
;Returns<br />
* true on success if the stopwatch was found and thus adjusted, or nil and an error message if not.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- demo of a persistent stopWatch used to real time a mission<br />
-- called with a positive number of seconds it will start a "missionStopWatch"<br />
-- unless there already is one in which case it will instead report on<br />
-- the deadline. use 'stopStopWatch("missionStopWatch")' when the mission<br />
-- is done and 'deleteStopWatch("missionStopWatch")' when the existing mission<br />
-- is to be disposed of. Until then repeated use of 'mission(interval)' will<br />
-- just give updates...<br />
function mission(time)<br />
local missionTimeTable = missionTimeTable or {}<br />
<br />
if createStopWatch("missionStopWatch") then<br />
adjustStopWatch("missionStopWatch", -tonumber(time))<br />
setStopWatchPersistence("missionStopWatch", true)<br />
missionTimeTable = getStopWatchBrokenDownTime("missionStopWatch")<br />
<br />
echo(string.format("Get cracking, you have %02i:%02i:%02i hg:m:s left.\n", missionTimeTable.hours, missionTimeTable.minutes, missionTimeTable.seconds))<br />
startStopWatch("missionStopWatch")<br />
else<br />
-- it already exists, so instead report what is/was the time on it<br />
--[=[ We know that the stop watch exists - we just need to find the ID<br />
so we can get the running detail which is only available from the getStopWatches()<br />
table and that is indexed by ID]=]<br />
for k,v in pairs(getStopWatches()) do<br />
if v.name == "missionStopWatch" then<br />
missionTimeTable = v<br />
end<br />
end<br />
if missionTimeTable.isRunning then<br />
if missionTimeTable.elapsedTime.negative then<br />
echo(string.format("Better hurry up, the clock is ticking on an existing mission and you only have %02i:%02i:%02i h:m:s left.\n", missionTimeTable.elapsedTime.hours, missionTimeTable.elapsedTime.minutes, missionTimeTable.elapsedTime.seconds))<br />
else<br />
echo(string.format("Bad news, you are past the deadline on an existing mission by %02i:%02i:%02i h:m:s !\n", missionTimeTable.elapsedTime.hours, missionTimeTable.elapsedTime.minutes, missionTimeTable.elapsedTime.seconds))<br />
end<br />
else<br />
if missionTimeTable.elapsedTime.negative then<br />
echo(string.format("Well done! You have already completed a mission %02i:%02i:%02i h:m:s before the deadline ...\n", missionTimeTable.elapsedTime.hours, missionTimeTable.elapsedTime.minutes, missionTimeTable.elapsedTime.seconds))<br />
else<br />
echo(string.format("Uh oh! You failed to meet the deadline on an existing mission by %02i:%02i:%02i h:m:s !\n", missionTimeTable.elapsedTime.hours, missionTimeTable.elapsedTime.minutes, missionTimeTable.elapsedTime.seconds))<br />
end<br />
end<br />
end<br />
end<br />
<br />
<br />
-- in use:<br />
lua mission(60*60)<br />
Get cracking, you have 01:00:00 h:m:s left.<br />
<br />
lua mission(60*60)<br />
Better hurry up, the clock is ticking on an existing mission and you only have 00:59:52 h:m:s left.<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.4}}<br />
<br />
==appendScript==<br />
;appendScript(scriptName, luaCode, [occurrence])<br />
: Appends Lua code to the script "scriptName". If no occurrence given it sets the code of the first found script.<br />
<br />
: See also: [[Manual:Lua_Functions#permScript|permScript()]], [[Manual:Lua_Functions#enableScript|enableScript()]], [[Manual:Lua_Functions#disableScript|disableScript()]], [[Manual:Lua_Functions#getScript|getScript()]], [[Manual:Lua_Functions#setScript|setScript()]]<br />
<br />
;Returns<br />
* a unique id number for that script.<br />
<br />
;Parameters<br />
* ''scriptName'': name of the script<br />
* ''luaCode'': scripts luaCode to append<br />
* ''occurence'': (optional) the occurrence of the script in case you have many with the same name<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- an example of appending the script lua code to the first occurrence of "testscript"<br />
appendScript("testscript", [[echo("This is a test\n")]], 1)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.8}}<br />
<br />
==appendCmdLine==<br />
;appendCmdLine([name], text)<br />
: Appends text to the main input line.<br />
: See also: [[Manual:Lua_Functions#printCmdLine|printCmdLine()]], [[#clearCmdLine|clearCmdLine()]]<br />
<br />
;Parameters<br />
* ''name'': (optional) name of the command line. If not given, the text will be appended to the main commandline.<br />
* ''text'': text to append<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- adds the text "55 backpacks" to whatever is currently in the input line<br />
appendCmdLine("55 backpacks")<br />
<br />
-- makes a link, that when clicked, will add "55 backpacks" to the input line<br />
echoLink("press me", "appendCmdLine'55 backpack'", "Press me!")<br />
</syntaxhighlight><br />
<br />
==clearCmdLine==<br />
;clearCmdLine([name])<br />
: Clears the input line of any text that's been entered.<br />
: See also: [[Manual:Lua_Functions#printCmdLine|printCmdLine()]]<br />
<br />
;Parameters<br />
* ''name'': (optional) name of the command line. If not given, the main commandline's text will be cleared.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- don't be evil with this!<br />
clearCmdLine()<br />
</syntaxhighlight><br />
<br />
==clearCmdLineSuggestions==<br />
;clearCmdLineSuggestions([name])<br />
<br />
: Clears all suggestions for command line.<br />
<br />
: See also: [[Manual:Lua_Functions#addCmdLineSuggestion|addCmdLineSuggestion()]], [[Manual:Lua_Functions#removeCmdLineSuggestion|removeCmdLineSuggestion()]]<br />
<br />
;Parameter<br />
* ''name'': (optional) name of the command line. If not given the main commandline's suggestions will be cleared.<br />
<br />
<syntaxhighlight lang="lua"><br />
clearCmdLineSuggestions()<br />
</syntaxhighlight><br />
<br />
==createStopWatch==<br />
;createStopWatch([name], [start immediately])<br />
;createStopWatch([start immediately])<br />
Before Mudlet 4.4.0:<br />
;createStopWatch()<br />
<br />
: This function creates a stopwatch, a high resolution time measurement tool. Stopwatches can be started, stopped, reset, asked how much time has passed since the stop watch has been started and, following an update for Mudlet 4.4.0: be adjusted, given a name and be made persistent between sessions (so can time real-life things). Prior to 4.4.0 the function took no parameters '''and the stopwatch would start automatically when it was created'''.<br />
<br />
;Parameters:<br />
* ''start immediately'' (bool) used to override the behaviour prior to Mudlet 4.4.0 so that if it is the ''only'' argument then a ''false'' value will cause the stopwatch to be created but be in a ''stopped'' state, however if a name parameter is provided then this behaviour is assumed and then a ''true'' value is required should it be desired for the stopwatch to be started on creation. This difference between the cases with and without a name argument is to allow for older scripts to continue to work with 4.4.0 or later versions of Mudlet without change, yet to allow for more functionality - such as presetting a time when the stopwatch is created but not to start it counting down until some time afterwards - to be performed as well with a named stopwatch.<br />
<br />
* ''name'' (string) a ''unique'' text to use to identify the stopwatch.<br />
<br />
;Returns:<br />
* the ID (number) of a stopwatch; or, from '''4.4.0''': a nil + error message if the name has already been used.<br />
<br />
: See also: [[Manual:Lua_Functions#startStopWatch|startStopWatch()]], [[Manual:Lua_Functions#stopStopWatch|stopStopWatch()]], [[Manual:Lua_Functions#resetStopWatch|resetStopWatch()]], [[Manual:Lua_Functions#getStopWatchTime|getStopWatchTime()]] or, from 4.4.0: [[Manual:Lua_Functions#adjustStopWatch|adjustStopWatch()]], [[Manual:Lua_Functions#deleteStopWatch|deleteStopWatch()]], [[Manual:Lua_Functions#getStopWatches|getStopWatches()]], [[Manual:Lua_Functions#getStopWatchBrokenDownTime|getStopWatchBrokenDownTime()]], [[Manual:Lua_Functions#setStopWatchName|setStopWatchName()]], [[Manual:Lua_Functions#setStopWatchPersistence|setStopWatchPersistence()]]<br />
<br />
;Example<br />
: (Prior to Mudlet 4.4.0) in a global script you can create all stop watches that you need in your system and store the respective stopWatch-IDs in global variables:<br />
<syntaxhighlight lang="lua"><br />
fightStopWatch = fightStopWatch or createStopWatch() -- create, or re-use a stopwatch, and store the watchID in a global variable to access it from anywhere<br />
<br />
-- then you can start the stop watch in some trigger/alias/script with:<br />
startStopWatch(fightStopWatch)<br />
<br />
-- to stop the watch and measure its time in e.g. a trigger script you can write:<br />
fightTime = stopStopWatch(fightStopWatch)<br />
echo("The fight lasted for " .. fightTime .. " seconds.")<br />
resetStopWatch(fightStopWatch)<br />
</syntaxhighlight><br />
<br />
: (From Mudlet 4.4.0) in a global script you can create all stop watches that you need in your system with unique names:<br />
<syntaxhighlight lang="lua"><br />
createStopWatch("fightStopWatch") -- creates the stopwatch or returns nil+msg if it already exists<br />
<br />
-- then you can start the stop watch (if it is not already started) in some trigger/alias/script with:<br />
startStopWatch("fightStopWatch")<br />
<br />
-- to stop the watch and measure its time in e.g. a trigger script you can write:<br />
fightTime = stopStopWatch("fightStopWatch")<br />
echo("The fight lasted for " .. fightTime .. " seconds.")<br />
resetStopWatch("fightStopWatch")<br />
</syntaxhighlight><br />
<br />
:You can also measure the elapsed time without having to stop the stop watch (equivalent to getting a ''lap-time'') with [[#getStopWatchTime|getStopWatchTime()]].<br />
<br />
{{note}} it's best to re-use stopwatch IDs if you can for Mudlet prior to 4.4.0 as they cannot be deleted, so creating more and more would use more memory. From 4.4.0 the revised internal design has been changed such that there are no internal timers created for each stopwatch - instead either a timestamp or a fixed elapsed time record is used depending on whether the stopwatches is running or stopped so that there are no "moving parts" in the later design and less resources are used - and they can be removed if no longer required.<br />
<br />
==deleteAllNamedTimers==<br />
; deleteAllNamedTimers(userName)<br />
<br />
:Deletes all named timers and prevents them from firing any more. Information is deleted and cannot be retrieved.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]], [[Manual:Lua_Functions#stopNamedTimer|stopNamedTimer()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
deleteAllNamedTimers("Demonnic") -- emergency stop or debugging situation, most likely.<br />
</syntaxhighlight><br />
<br />
==deleteNamedTimer==<br />
; success = deleteNamedTimer(userName, handlerName)<br />
<br />
:Deletes a named timer with name handlerName and prevents it from firing any more. Information is deleted and cannot be retrieved.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]], [[Manual:Lua_Functions#stopNamedTimer|stopNamedTimer()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
* ''handlerName:''<br />
: The name of the handler to stop. Same as used when you called [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]]<br />
<br />
;Returns <br />
* true if successful, false if it didn't exist<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local deleted = deleteNamedTimer("Demonnic", "DemonVitals")<br />
if deleted then<br />
cecho("DemonVitals deleted forever!!")<br />
else<br />
cecho("DemonVitals doesn't exist and so could not be deleted.")<br />
end<br />
</syntaxhighlight><br />
<br />
==deleteStopWatch==<br />
;deleteStopWatch(watchID/watchName)<br />
<br />
: This function removes an existing stopwatch, whether it only exists for this session or is set to be otherwise saved between sessions by using [[Manual:Lua_Functions#setStopWatchPersistence|setStopWatchPersistence()]] with a ''true'' argument. <br />
<br />
;Parameters<br />
* ''watchID'' (number) / ''watchName'' (string): The stopwatch ID you get with [[Manual:Lua_Functions#createStopWatch|createStopWatch()]] or the name given to that function or later set with [[Manual:Lua_Functions#setStopWatchName|setStopWatchName()]].<br />
<br />
;Returns:<br />
* ''true'' if the stopwatch was found and thus deleted, or ''nil'' and an error message if not - obviously using it twice with the same argument will fail the second time unless another one with the same name or ID was recreated before the second use. Note that an empty string as a name ''will'' find the lowest ID numbered ''unnamed'' stopwatch and that will then find the next lowest ID number of unnamed ones until there are none left, if used repetitively!<br />
<br />
<syntaxhighlight lang="lua"><br />
lua MyStopWatch = createStopWatch("stopwatch_mine")<br />
true<br />
<br />
lua display(MyStopWatch)<br />
4<br />
<br />
lua deleteStopWatch(MyStopWatch)<br />
true<br />
<br />
lua deleteStopWatch(MyStopWatch)<br />
nil<br />
<br />
"stopwatch with id 4 not found"<br />
<br />
lua deleteStopWatch("stopwatch_mine")<br />
nil<br />
<br />
"stopwatch with name "stopwatch_mine" not found"<br />
</syntaxhighlight><br />
<br />
: See also: [[Manual:Lua_Functions#createStopWatch|createStopWatch()]],<br />
<br />
{{MudletVersion|4.4}}<br />
<br />
{{note}} Stopwatches that are not set to be persistent will be deleted automatically at the end of a session (or if [[Manual:Miscellaneous_Functions#resetProfile|resetProfile()]] is called).<br />
<br />
==removeCmdLineSuggestion==<br />
;removeCmdLineSuggestion([name], suggestion)<br />
: Remove a suggestion for tab completion for specified command line.<br />
<br />
: See also: [[Manual:Lua_Functions#addCmdLineSuggestion|addCmdLineSuggestion()]], [[Manual:Lua_Functions#clearCmdLineSuggestions|clearCmdLineSuggestions()]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
;Parameters<br />
* ''name'': optional command line name, if skipped main command line will be used<br />
* ''suggestion'' - text to add to tab completion, non words characters at start and end of word should not be used (all characters except: `0-9A-Za-z_`)<br />
<br />
Example:<br />
<syntaxhighlight lang="lua"><br />
removeCmdLineSuggestion("help")<br />
</syntaxhighlight><br />
<br />
==disableAlias==<br />
;disableAlias(name)<br />
:Disables/deactivates the alias by its name. If several aliases have this name, they'll all be disabled. If you disable an alias group, all the aliases inside the group will be disabled as well.<br />
<br />
: See also: [[#enableAlias|enableAlias()]], [[#disableTrigger|disableTrigger()]], [[#disableTimer|disableTimer()]], [[#disableKey|disableKey()]], [[#disableScript|disableScript()]].<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name of the alias. Passed as a string.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
--Disables the alias called 'my alias'<br />
disableAlias("my alias")<br />
</syntaxhighlight><br />
<br />
==disableKey==<br />
;disableKey(name)<br />
:Disables key a key (macro) or a key group. When you disable a key group, all keys within the group will be implicitly disabled as well.<br />
<br />
: See also: [[#enableKey|enableKey()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name of the key or group to identify what you'd like to disable.<br />
<br />
;Examples<br />
<br />
<syntaxhighlight lang="lua"><br />
-- you could set multiple keys on the F1 key and swap their use as you wish by disabling and enabling them<br />
disableKey("attack macro")<br />
disableKey("jump macro")<br />
enableKey("greet macro")<br />
</syntaxhighlight><br />
<br />
==disableScript==<br />
;disableScript(name)<br />
:Disables a script that was previously enabled. Note that disabling a script only stops it from running in the future - it won't "undo" anything the script has made, such as labels on the screen.<br />
<br />
: See also: [[#permScript|permScript()]], [[#appendScript|appendScript()]], [[#enableScript|enableScript()]], [[#getScript|getScript()]], [[#setScript|setScript()]]<br />
<br />
;Parameters<br />
* ''name'': name of the script.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--Disables the script called 'my script'<br />
disableScript("my script")<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.8}}<br />
<br />
==disableTimer==<br />
;disableTimer(name)<br />
:Disables a timer from running it’s script when it fires - so the timer cycles will still be happening, just no action on them. If you’d like to permanently delete it, use [[Manual:Lua_Functions#killTrigger|killTrigger]] instead.<br />
<br />
: See also: [[#enableTimer|enableTimer()]], [[#disableTrigger|disableTrigger()]], [[#disableAlias|disableAlias()]], [[#disableKey|disableKey()]], [[#disableScript|disableScript()]].<br />
<br />
;Parameters<br />
* ''name:''<br />
: Expects the timer ID that was returned by [[Manual:Lua_Functions#tempTimer|tempTimer]] on creation of the timer or the name of the timer in case of a GUI timer.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--Disables the timer called 'my timer'<br />
disableTimer("my timer")<br />
</syntaxhighlight><br />
<br />
==disableTrigger==<br />
;disableTrigger(name)<br />
:Disables a permanent (one in the trigger editor) or a temporary trigger. When you disable a group, all triggers inside the group are disabled as well<br />
<br />
: See also: [[#enableTrigger|enableTrigger()]], [[#disableAlias|disableAlias()]], [[#disableTimer|disableTimer()]], [[#disableKey|disableKey()]], [[#disableScript|disableScript()]].<br />
<br />
;Parameters<br />
* ''name:''<br />
: Expects the trigger ID that was returned by [[Manual:Lua_Functions#tempTrigger|tempTrigger]] or other temp*Trigger variants, or the name of the trigger in case of a GUI trigger.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Disables the trigger called 'my trigger'<br />
disableTrigger("my trigger")<br />
</syntaxhighlight><br />
<br />
==enableAlias==<br />
;enableAlias(name)<br />
:Enables/activates the alias by it’s name. If several aliases have this name, they’ll all be enabled.<br />
<br />
: See also: [[#disableAlias|disableAlias()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: Expects the alias ID that was returned by [[Manual:Lua_Functions#tempAlias|tempAlias]] on creation of the alias or the name of the alias in case of a GUI alias.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--Enables the alias called 'my alias'<br />
enableAlias("my alias")<br />
</syntaxhighlight><br />
<br />
==enableKey==<br />
;enableKey(name)<br />
:Enables a key (macro) or a group of keys (and thus all keys within it that aren't explicitly deactivated).<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name of the group that identifies the key.<br />
<br />
<syntaxhighlight lang="lua"><br />
-- you could use this to disable one key set for the numpad and activate another<br />
disableKey("fighting keys")<br />
enableKey("walking keys")<br />
</syntaxhighlight><br />
{{note}} From Version '''3.10'' returns ''true'' if one or more keys or groups of keys were found that matched the name given or ''false'' if not; prior to then it returns ''true'' if there were '''any''' keys - whether they matched the name or not!<br />
<br />
==enableScript==<br />
;enableScript(name)<br />
:Enables / activates a script that was previously disabled. <br />
<br />
: See also: [[#permScript|permScript()]], [[#appendScript|appendScript()]], [[#disableScript|disableScript()]], [[#getScript|getScript()]], [[#setScript|setScript()]]<br />
<br />
;Parameters<br />
* ''name'': name of the script.<br />
<syntaxhighlight lang="lua"><br />
-- enable the script called 'my script' that you created in Mudlet's script section<br />
enableScript("my script")<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.8}}<br />
<br />
==enableTimer==<br />
;enableTimer(name)<br />
:Enables or activates a timer that was previously disabled. <br />
<br />
;Parameters<br />
* ''name:''<br />
: Expects the timer ID that was returned by [[Manual:Lua_Functions#tempTimer|tempTimer]] on creation of the timer or the name of the timer in case of a GUI timer.<br />
<syntaxhighlight lang="lua"><br />
-- enable the timer called 'my timer' that you created in Mudlets timers section<br />
enableTimer("my timer")<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- or disable & enable a tempTimer you've made<br />
timerID = tempTimer(10, [[echo("hi!")]])<br />
<br />
-- it won't go off now<br />
disableTimer(timerID)<br />
-- it will continue going off again<br />
enableTimer(timerID)<br />
</syntaxhighlight><br />
<br />
==enableTrigger==<br />
;enableTrigger(name)<br />
:Enables or activates a trigger that was previously disabled. <br />
<br />
;Parameters<br />
* ''name:''<br />
: Expects the trigger ID that was returned by [[Manual:Lua_Functions#tempTrigger|tempTrigger]] or by any other temp*Trigger variants, or the name of the trigger in case of a GUI trigger.<br />
<syntaxhighlight lang="lua"><br />
-- enable the trigger called 'my trigger' that you created in Mudlets triggers section<br />
enableTrigger("my trigger")<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- or disable & enable a tempTrigger you've made<br />
triggerID = tempTrigger("some text that will match in a line", [[echo("hi!")]])<br />
<br />
-- it won't go off now when a line with matching text comes by<br />
disableTrigger(triggerID)<br />
<br />
-- and now it will continue going off again<br />
enableTrigger(triggerID)<br />
</syntaxhighlight><br />
<br />
==exists==<br />
;exists(name/IDnumber, type)<br />
:Returns the number of things with the given name or number of the given type - and 0 if none are present. Beware that all numbers are true in Lua, including zero.<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name (as a string) or, from '''Mudlet 4.17.0''', the ID number of a single item, (which will be that returned by a ''temp*'' or ''perm*'' function to create such an item to identify the item).<br />
* ''type:''<br />
: The type can be 'alias', 'button' (Mudlet 4.10+), 'trigger', 'timer', 'keybind' (Mudlet 3.2+), or 'script' (Mudlet 3.17+).<br />
<br />
:See also: [[#isActive|isActive(...)]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo("I have " .. exists("my trigger", "trigger") .. " triggers called 'my trigger'!")<br />
</syntaxhighlight><br />
<br />
: You can also use this alias to avoid creating duplicate things, for example:<br />
<syntaxhighlight lang="lua"><br />
-- this code doesn't check if an alias already exists and will keep creating new aliases<br />
permAlias("Attack", "General", "^aa$", [[send ("kick rat")]])<br />
<br />
-- while this code will make sure that such an alias doesn't exist first<br />
-- we do == 0 instead of 'not exists' because 0 is considered true in Lua<br />
if exists("Attack", "alias") == 0 then<br />
permAlias("Attack", "General", "^aa$", [[send ("kick rat")]])<br />
end<br />
</syntaxhighlight><br />
<br />
: Especially helpful when working with [[Manual:Lua_Functions#permTimer|permTimer]]:<br />
<syntaxhighlight lang="lua"><br />
if not exists("My animation timer", "timer") then<br />
vdragtimer = permTimer("My animation timer", "", .016, onVDragTimer) -- 60fps timer!<br />
end<br />
<br />
enableTimer("My animation timer")<br />
</syntaxhighlight><br />
<br />
{{Note}} A positive ID number will return either a ''1'' or ''0'' value and not a lua boolean ''true'' or ''false'' as might otherwise be expected, this is for constancy with the way the function behaves for a name.<br />
<br />
==getButtonState==<br />
;getButtonState([ButtonNameOrID])<br />
:This function can be used within checkbox button scripts (2-state buttons) to determine the current state of the checkbox.<br />
<br />
: See also: [[#setButtonState|setButtonState()]].<br />
{{note}} Function can be used in any Mudlet script outside of a button's own script with parameter ButtonNameOrID available from Mudlet version 4.13.0+<br />
<br />
;Parameters<br />
* ''ButtonNameOrID:''<br />
: a numerical ID or string name to identify the checkbox button.<br />
<br />
;Returns <br />
* ''2'' if the button has "checked" state, or ''1'' if the button is not checked. (or a ''nil'' and an error message if ButtonNameOrID did not identify a check-able button)<br />
<br />
;Example <br />
<syntaxhighlight lang="lua"><br />
-- check from within the script of a check-able button:<br />
local checked = getButtonState()<br />
if checked == 1 then<br />
hideExits()<br />
else<br />
showExits()<br />
end<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- check from anywhere in another Lua script of the same profile (available from Mudlet 4.13.0)<br />
local checked, errMsg = getButtonState("Sleep")<br />
if checked then<br />
shouldBeMounted = shouldBeMounted or false<br />
sendAll("wake", "stand")<br />
if shouldBeMounted then<br />
send("mount horse")<br />
end<br />
else<br />
-- Global used to record if we were on a horse before our nap:<br />
shouldBeMounted = mounted or false<br />
if shouldBeMounted then<br />
send("dismount")<br />
end<br />
sendAll("sit", "sleep")<br />
end<br />
</syntaxhighlight><br />
<br />
==getCmdLine==<br />
;getCmdLine([name])<br />
: Returns the current content of the given command line.<br />
: See also: [[Manual:Lua_Functions#printCmdLine|printCmdLine()]]<br />
<br />
{{MudletVersion|3.1}}<br />
<br />
;Parameters<br />
* ''name'': (optional) name of the command line. If not given, it returns the text of the main commandline.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replaces whatever is currently in the input line by "55 backpacks"<br />
printCmdLine("55 backpacks")<br />
<br />
--prints the text "55 backpacks" to the main console<br />
echo(getCmdLine())<br />
</syntaxhighlight><br />
<br />
==getConsoleBufferSize==<br />
;local lineLimit, sizeOfBatchDeletion = getConsoleBufferSize([consoleName])<br />
:Returns, on success, the maximum number of lines a buffer (main window or a miniconsole) can hold and how many will be removed at a time when that limit is exceeded; returns a ''nil'' and an error message on failure.<br />
: See also: [[Manual:Mudlet_Object_Functions#setConsoleBufferSize|setConsoleBufferSize()]]<br />
<br />
;Parameters<br />
* ''consoleName:''<br />
: (optional) The name of the window. If omitted, uses the main console.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- sets the main window's size and how many lines will be deleted<br />
-- when it gets to that size to be as small as possible:<br />
setConsoleBufferSize("main", 1, 1)<br />
true<br />
<br />
-- find out what the numbers are:<br />
local lineLimit, sizeOfBatchDeletion = getConsoleBufferSize()<br />
echo("\nWhen the main console gets to " .. lineLimit .. " lines long, the first " .. sizeOfBatchDeletion .. " lines will be removed.\n")<br />
When the main console gets to 100 lines long, the first 1 lines will be removed.<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.17}}<br />
<br />
==getNamedTimers==<br />
; timers = getNamedTimers(userName)<br />
<br />
:Returns a list of all the named timers' names as a table.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
<br />
;Returns <br />
* a table of handler names. { "DemonVitals", "DemonInv" } for example. {} if none are registered<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local timers = getNamedTimers("Demonnic")<br />
display(timers)<br />
-- {}<br />
registerNamedTimer("Test1", "testEvent", "testFunction")<br />
registerNamedTimer("Test2", "someOtherEvent", myHandlerFunction)<br />
timers = getNamedTimers("Demonnic")<br />
display(timers)<br />
-- { "Test1", "Test2" }<br />
</syntaxhighlight><br />
<br />
== getProfileStats==<br />
;getProfileStats()<br />
<br />
:Returns a table with profile statistics for how many triggers, patterns within them, aliases, keys, timers, and scripts the profile has. Similar to the Statistics button in the script editor, accessible to Lua scripting.<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- show all stats<br />
display(getProfileStats())<br />
<br />
-- check how many active triggers there are<br />
activetriggers = getProfileStats().triggers.active<br />
cecho(f"<PaleGreen>We have <SlateGrey>{activetriggers}<PaleGreen> active triggers!\n")<br />
<br />
-- triggers can have many patterns, so let's check that as well<br />
patterns = getProfileStats().triggers.patterns.active<br />
triggers = getProfileStats().triggers.active<br />
cecho(f"<PaleGreen>We have <SlateGrey>{patterns}<PaleGreen> active patterns within <SlateGrey>{triggers}<PaleGreen> triggers!\n")<br />
</syntaxhighlight><br />
<br />
==getStopWatches==<br />
;table = getStopWatches()<br />
<br />
: Returns a table of the details for each stopwatch in existence, the keys are the watch IDs but since there can be gaps in the ID number allocated for the stopwatches it will be necessary to use the ''pairs(...)'' rather than the ''ipairs(...)'' method to iterate through all of them in ''for'' loops!<br />
: Each stopwatch's details will list the following items: ''name'' (string), ''isRunning'' (boolean), ''isPersistent'' (boolean), ''elapsedTime'' (table). The last of these contains the same data as is returned by the results table from the [[Manual:Lua_Functions#getStopWatchBrokenDownTime|getStopWatchBrokenDownTime()]] function - namely ''days'' (positive integer), ''hours'' (integer, 0 to 23), ''minutes'' (integer, 0 to 59), ''second'' (integer, 0 to 59), ''milliSeconds'' (integer, 0 to 999), ''negative'' (boolean) with an additional ''decimalSeconds'' (number of seconds, with a decimal portion for the milli-seconds and possibly a negative sign, representing the whole elapsed time recorded on the stopwatch) - as would also be returned by the [[Manual:Lua_Functions#getStopWatchTime|getStopWatchTime()]] function.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- on the command line:<br />
lua getStopWatches()<br />
-- could return something like:<br />
{<br />
{<br />
isPersistent = true,<br />
elapsedTime = {<br />
minutes = 15,<br />
seconds = 2,<br />
negative = false,<br />
milliSeconds = 66,<br />
hours = 0,<br />
days = 18,<br />
decimalSeconds = 1556102.066<br />
},<br />
name = "Playing time",<br />
isRunning = true<br />
},<br />
{<br />
isPersistent = true,<br />
elapsedTime = {<br />
minutes = 47,<br />
seconds = 1,<br />
negative = true,<br />
milliSeconds = 657,<br />
hours = 23,<br />
days = 2,<br />
decimalSeconds = -258421.657<br />
},<br />
name = "TMC Vote",<br />
isRunning = true<br />
},<br />
{<br />
isPersistent = false,<br />
elapsedTime = {<br />
minutes = 26,<br />
seconds = 36,<br />
negative = false,<br />
milliSeconds = 899,<br />
hours = 3,<br />
days = 0,<br />
decimalSeconds = 12396.899<br />
},<br />
name = "",<br />
isRunning = false<br />
},<br />
[5] = {<br />
isPersistent = false,<br />
elapsedTime = {<br />
minutes = 0,<br />
seconds = 38,<br />
negative = false,<br />
milliSeconds = 763,<br />
hours = 0,<br />
days = 0,<br />
decimalSeconds = 38.763<br />
},<br />
name = "",<br />
isRunning = true<br />
}<br />
}<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.4}}<br />
<br />
==getStopWatchTime==<br />
;time = getStopWatchTime(watchID [or watchName from Mudlet 4.4.0])<br />
: Returns the time as a decimal number of seconds with up to three decimal places to give a milli-seconds (thousandths of a second) resolution.<br />
: Please note that, prior to 4.4.0 it was not possible to retrieve the elapsed time after the stopwatch had been stopped, retrieving the time was not possible as the returned value then was an indeterminate, meaningless time; from the 4.4.0 release, however, the elapsed value can be retrieved at any time, even if the stopwatch has not been started since creation or modified with the [[Manual:Lua_Functions#adjustStopWatch|adjustStopWatch()]] function introduced in that release.<br />
<br />
: See also: [[Manual:Lua_Functions#createStopWatch|createStopWatch()]], [[Manual:Lua_Functions#startStopWatch|startStopWatch()]], [[Manual:Lua_Functions#stopStopWatch|stopStopWatch()]], [[Manual:Lua_Functions#deleteStopWatch|deleteStopWatch()]], [[Manual:Lua_Functions#getStopWatch es|getStopWatches()]], [[Manual:Lua_Functions#getStopWatchBrokenDownTime|getStopWatchBrokenDownTime()]].<br />
<br />
:Returns a number<br />
<br />
;Parameters<br />
* ''watchID''<br />
: The ID number of the watch.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- an example of showing the time left on the stopwatch<br />
teststopwatch = teststopwatch or createStopWatch()<br />
startStopWatch(teststopwatch)<br />
echo("Time on stopwatch: "..getStopWatchTime(teststopwatch))<br />
tempTimer(1, [[echo("Time on stopwatch: "..getStopWatchTime(teststopwatch))]])<br />
tempTimer(2, [[echo("Time on stopwatch: "..getStopWatchTime(teststopwatch))]])<br />
stopStopWatch(teststopwatch)<br />
</syntaxhighlight><br />
<br />
==getStopWatchBrokenDownTime==<br />
; brokenDownTimeTable = getStopWatchBrokenDownTime(watchID or watchName)<br />
: Returns the current stopwatch time, whether the stopwatch is running or is stopped, as a table, broken down into:<br />
* "days" (integer)<br />
* "hours" (integer, 0 to 23)<br />
* "minutes" (integer, 0 to 59)<br />
* "seconds" (integer, 0 to 59)<br />
* "milliSeconds" (integer, 0 to 999)<br />
* "negative" (boolean, true if value is less than zero)<br />
<br />
: See also: [[Manual:Lua_Functions#startStopWatch|startStopWatch()]], [[Manual:Lua_Functions#stopStopWatch|stopStopWatch()]], [[Manual:Lua_Functions#deleteStopWatch|deleteStopWatch()]], [[Manual:Lua_Functions#getStopWatch es|getStopWatches()]], [[Manual:Lua_Functions#getStopWatchTime|getStopWatchTime()]].<br />
<br />
;Parameters<br />
* ''watchID'' / ''watchName''<br />
: The ID number or the name of the watch.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--an example, showing the presetting of a stopwatch.<br />
<br />
--This will fail if the stopwatch with the given name<br />
-- already exists, but then we can use the existing one:<br />
local watchId = createStopWatch("TopMudSiteVoteStopWatch")<br />
if watchId ~= nil then<br />
-- so we have just created the stopwatch, we want it<br />
-- to be saved for future sessions:<br />
setStopWatchPersistence("TopMudSiteVoteStopWatch", true)<br />
-- and set it to count down the 12 hours until we can<br />
-- revote:<br />
adjustStopWatch("TopMudSiteVoteStopWatch", -60*60*12)<br />
-- and start it running<br />
startStopWatch("TopMudSiteVoteStopWatch")<br />
<br />
openWebPage("http://www.topmudsites.com/vote-wotmud.html")<br />
end<br />
<br />
--[[ now I can check when it is time to vote again, even when<br />
I stop the session and restart later by running the following<br />
from a perm timer - perhaps on a 15 minute interval. Note that<br />
when loaded in a new session the Id it gets is unlikely to be<br />
the same as that when it was created - but that is not a<br />
problem as the name is preserved and, if the timer is running<br />
when the profile is saved at the end of the session then the<br />
elapsed time will continue to increase to reflect the real-life<br />
passage of time:]]<br />
<br />
local voteTimeTable = getStopWatchBrokenDownTime("TopMudSiteVoteStopWatch")<br />
<br />
if voteTimeTable["negative"] then<br />
if voteTimeTable["hours"] == 0 and voteTimeTable["minutes"] < 30 then<br />
echo("Voting for WotMUD on Top Mud Site in " .. voteTimeTable["minutes"] .. " minutes...")<br />
end<br />
else<br />
echo("Oooh, it is " .. voteTimeTable["days"] .. " days, " .. voteTimeTable["hours"] .. " hours and " .. voteTimeTable["minutes"] .. " minutes past the time to Vote on Top Mud Site - doing it now!")<br />
openWebPage("http://www.topmudsites.com/vote-wotmud.html")<br />
resetStopWatch("TopMudSiteVoteStopWatch")<br />
adjustStopWatch("TopMudSiteVoteStopWatch", -60*60*12)<br />
end<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.7}}<br />
<br />
==getScript==<br />
; getScript(scriptName, [occurrence])<br />
: Returns the script with the given name. If you have more than one script with the same name, specify the occurrence to pick a different one. Returns -1 if the script doesn't exist.<br />
<br />
: See also: [[Manual:Lua_Functions#permScript|permScript()]], [[Manual:Lua_Functions#enableScript|enableScript()]], [[Manual:Lua_Functions#disableScript|disableScript()]], [[Manual:Lua_Functions#setScript|setScript()]], [[Manual:Lua_Functions#appendScript|appendScript()]]<br />
<br />
;Parameters<br />
* ''scriptName'': name of the script.<br />
* ''occurrence'': (optional) occurence of the script in case you have many with the same name.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- show the "New script" on screen<br />
print(getScript("New script"))<br />
<br />
-- an example of returning the script Lua code from the second occurrence of "testscript"<br />
test_script_code = getScript("testscript", 2)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.8}}<br />
<br />
==invokeFileDialog==<br />
;invokeFileDialog(fileOrFolder, dialogTitle)<br />
:Opens a file chooser dialog, allowing the user to select a file or a folder visually. The function returns the selected path or "" if there was none chosen.<br />
<br />
;Parameters<br />
* ''fileOrFolder:'' ''true'' for file selection, ''false'' for folder selection.<br />
* ''dialogTitle'': what to say in the window title.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
function whereisit()<br />
local path = invokeFileDialog(false, "Where should we save the file? Select a folder and click Open")<br />
<br />
if path == "" then return nil else return path end<br />
end<br />
</syntaxhighlight><br />
<br />
==isActive==<br />
;isActive(name/IDnumber, type)<br />
:You can use this function to check if something, or somethings, are active. <br />
:Returns the number of active things - and 0 if none are active. Beware that all numbers are true in Lua, including zero.<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name (as a string) or, from '''Mudlet 4.17.0''', the ID number of a single item, (which will be that returned by a ''temp*'' function to create such an item to identify the item).<br />
* ''type:''<br />
: The type can be 'alias', 'button' (Mudlet 4.10+), 'trigger', 'timer', 'keybind' (Mudlet 3.2+), or 'script' (Mudlet 3.17+).<br />
<br />
: See also: [[#exists|exists(...)]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
echo("I have " .. isActive("my trigger", "trigger") .. " currently active trigger(s) called 'my trigger'!")<br />
<br />
-- Can also be used to check if a specific item is enabled or not.<br />
if isActive("spellname", "trigger" > 0 then<br />
-- the spellname trigger is active<br />
else<br />
-- it is not active<br />
end<br />
</syntaxhighlight><br />
<br />
{{note}} A positive ID number that does not exist will still return a ''0'' value, this is for constancy with the way the function behaves for a name that does not refer to any item either. If necessary the existence of an item should be confirmed with [[#exists|exists(...)]] first.<br />
<br />
==isPrompt==<br />
;isPrompt()<br />
:Returns true or false depending on if the line at the cursor position is a prompt. This infallible feature is available for games that supply GA events (to check if yours is one, look to bottom-right of the main window - if it doesn’t say <No GA>, then it supplies them).<br />
<br />
:Example use could be as a Lua function, making closing gates on a prompt real easy.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- make a trigger pattern with 'Lua function', and this will trigger on every prompt!<br />
return isPrompt()<br />
</syntaxhighlight><br />
<br />
==killAlias==<br />
;killAlias(aliasID)<br />
:Deletes a temporary alias with the given ID.<br />
<br />
;Parameters<br />
* ''aliasID:''<br />
: The id returned by [[Manual:Lua_Functions#tempAlias|tempAlias]] to identify the alias.<br />
<br />
<syntaxhighlight lang="lua"><br />
-- deletes the alias with ID 5<br />
killAlias(5)<br />
</syntaxhighlight><br />
<br />
==killKey==<br />
;killKey(name)<br />
:Deletes a keybinding with the given name. If several keybindings have this name, they'll all be deleted.<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name or the id returned by [[Manual:Lua_Functions#tempKey|tempKey]] to identify the key.<br />
<br />
{{MudletVersion|3.2}}<br />
<br />
<syntaxhighlight lang="lua"><br />
-- make a temp key<br />
local keyid = tempKey(mudlet.key.F8, [[echo("hi!")]])<br />
<br />
-- delete the said temp key<br />
killKey(keyid)<br />
</syntaxhighlight><br />
<br />
==killTimer==<br />
;killTimer(id)<br />
:Deletes a [[Manual:Lua_Functions#tempTimer|tempTimer]].<br />
<br />
{{note}} Non-temporary timers that you have set up in the GUI or by using [[#permTimer|permTimer]] cannot be deleted with this function. Use [[Manual:Lua_Functions#disableTimer|disableTimer()]] and [[Manual:Lua_Functions#enableTimer|enableTimer()]] to turn them on or off.<br />
<br />
;Parameters<br />
* ''id:'' the ID returned by [[Manual:Lua_Functions#tempTimer|tempTimer]].<br />
<br />
: Returns true on success and false if the timer id doesn’t exist anymore (timer has already fired) or the timer is not a temp timer.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create the timer and remember the timer ID<br />
timerID = tempTimer(10, [[echo("hello!")]])<br />
<br />
-- delete the timer<br />
killTimer(timerID)<br />
-- reset the reference to it<br />
timerID = nil<br />
</syntaxhighlight><br />
<br />
==killTrigger==<br />
;killTrigger(id)<br />
:Deletes a [[Manual:Lua_Functions#tempTimer|tempTrigger]], or a trigger made with one of the ''temp<type>Trigger()'' functions.<br />
<br />
{{note}} When used in out of trigger contexts, the triggers are disabled and deleted upon the next line received from the game - so if you are testing trigger deletion within an alias, the 'statistics' window will be reporting trigger counts that are disabled and pending removal, and thus are no cause for concern.<br />
<br />
;Parameters<br />
* ''id:''<br />
: The ID returned by [[Manual:Lua_Functions#tempTimer|tempTimer]] to identify the item. ID is a string and not a number.<br />
<br />
:Returns true on success and false if the trigger id doesn’t exist anymore (trigger has already fired) or the trigger is not a temp trigger.<br />
<br />
==permAlias==<br />
;permAlias(name, parent, regex, lua code)<br />
<br />
:Creates a persistent alias that stays after Mudlet is restarted and shows up in the Script Editor.<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name you’d like the alias to have.<br />
* ''parent:'' <br />
: The name of the group, or another alias you want the trigger to go in - however if such a group/alias doesn’t exist, it won’t do anything. Use "" to make it not go into any groups.<br />
* ''regex:''<br />
: The pattern that you’d like the alias to use.<br />
* ''lua code:'' <br />
: The script the alias will do when it matches.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- creates an alias called "new alias" in a group called "my group"<br />
permAlias("new alias", "my group", "^test$", [[echo ("say it works! This alias will show up in the script editor too.")]])<br />
</syntaxhighlight><br />
<br />
{{note}} Mudlet by design allows duplicate names - so calling permAlias with the same name will keep creating new aliases. You can check if an alias already exists with the [[Manual:Lua_Functions#exists|exists]] function.<br />
<br />
==permGroup==<br />
;permGroup(name, itemtype, [parent])<br />
<br />
:Creates a new group of a given type. This group will persist through Mudlet restarts. <br />
;Parameters<br />
* ''name'':<br />
: The name of the new group item you want to create.<br />
* ''itemtype'' :<br />
: The type of the item, can be one of the following:<br />
:: trigger<br />
:: alias <br />
:: timer<br />
:: script (available in Mudlet 4.7+)<br />
:: key (available in Mudlet 4.11+)<br />
* ''parent'' (available in Mudlet 3.1+):<br />
: (optional) Name of existing item which the new item will be created as a child of. If none is given, item will be at the root level (not nested in any other groups)<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--create a new trigger group<br />
permGroup("Combat triggers", "trigger")<br />
<br />
--create a new alias group only if one doesn't exist already<br />
if exists("Defensive aliases", "alias") == 0 then<br />
permGroup("Defensive aliases", "alias")<br />
end<br />
</syntaxhighlight><br />
<br />
==permPromptTrigger==<br />
;permPromptTrigger(name, parent, lua code)<br />
:Creates a persistent trigger for the in-game prompt that stays after Mudlet is restarted and shows up in the Script Editor.<br />
<br />
{{note}} If the trigger is not working, check that the '''N:''' bottom-right has a number. This feature requires telnet Go-Ahead (GA) or End-of-Record (EOR) to be enabled in your game. Available in Mudlet 3.6+<br />
<br />
;Parameters:<br />
* ''name'' is the name you’d like the trigger to have.<br />
* ''parent'' is the name of the group, or another trigger you want the trigger to go in - however if such a group/trigger doesn’t exist, it won’t do anything. Use "" to make it not go into any groups.<br />
* ''lua code'' is the script the trigger will do when it matches.<br />
<br />
;Example: <br />
<syntaxhighlight lang="lua"><br />
permPromptTrigger("echo on prompt", "", [[echo("hey! this thing is working!\n")]])<br />
</syntaxhighlight><br />
<br />
<br />
==permRegexTrigger==<br />
;permRegexTrigger(name, parent, pattern table, lua code)<br />
:Creates a persistent trigger with one or more ''regex'' patterns that stays after Mudlet is restarted and shows up in the Script Editor.<br />
<br />
;Parameters<br />
* ''name'' is the name you’d like the trigger to have.<br />
* ''parent'' is the name of the group, or another trigger you want the trigger to go in - however if such a group/trigger doesn’t exist, it won’t do anything. Use "" to make it not go into any groups.<br />
* ''pattern table'' is a table of patterns that you’d like the trigger to use - it can be one or many.<br />
* ''lua code'' is the script the trigger will do when it matches.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a regex trigger that will match on the prompt to record your status<br />
permRegexTrigger("Prompt", "", {"^(\d+)h, (\d+)m"}, [[health = tonumber(matches[2]); mana = tonumber(matches[3])]])<br />
</syntaxhighlight><br />
{{note}} Mudlet by design allows duplicate names - so calling permRegexTrigger with the same name will keep creating new triggers. You can check if a trigger already exists with the [[Manual:Lua_Functions#exists|exists()]] function.<br />
<br />
==permBeginOfLineStringTrigger==<br />
;permBeginOfLineStringTrigger(name, parent, pattern table, lua code)<br />
:Creates a persistent trigger that stays after Mudlet is restarted and shows up in the Script Editor. The trigger will go off whenever one of the ''regex'' patterns it's provided with matches. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls.<br />
<br />
;Parameters<br />
* ''name'' is the name you’d like the trigger to have.<br />
* ''parent'' is the name of the group, or another trigger you want the trigger to go in - however if such a group/trigger doesn’t exist, it won’t do anything. Use "" to make it not go into any groups.<br />
* ''pattern table'' is a table of patterns that you’d like the trigger to use - it can be one or many.<br />
* ''lua code'' is the script the trigger will do when it matches.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- Create a trigger that will match on anything that starts with "You sit" and do "stand".<br />
-- It will not go into any groups, so it'll be on the top.<br />
permBeginOfLineStringTrigger("Stand up", "", {"You sit"}, [[send ("stand")]])<br />
<br />
-- Another example - lets put our trigger into a "General" folder and give it several patterns.<br />
permBeginOfLineStringTrigger("Stand up", "General", {"You sit", "You fall", "You are knocked over by"}, [[send ("stand")]])<br />
</syntaxhighlight><br />
{{note}} Mudlet by design allows duplicate names - so calling permBeginOfLineStringTrigger with the same name will keep creating new triggers. You can check if a trigger already exists with the [[Manual:Lua_Functions#exists|exists()]] function.<br />
<br />
==permSubstringTrigger==<br />
;permSubstringTrigger( name, parent, pattern table, lua code )<br />
:Creates a persistent trigger with one or more ''substring'' patterns that stays after Mudlet is restarted and shows up in the Script Editor.<br />
;Parameters<br />
* ''name'' is the name you’d like the trigger to have.<br />
* ''parent'' is the name of the group, or another trigger you want the trigger to go in - however if such a group/trigger doesn’t exist, it won’t do anything. Use "" to make it not go into any groups.<br />
* ''pattern table'' is a table of patterns that you’d like the trigger to use - it can be one or many.<br />
* ''lua code'' is the script the trigger will do when it matches.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a trigger to highlight the word "pixie" for us<br />
permSubstringTrigger("Highlight stuff", "General", {"pixie"},<br />
[[selectString(line, 1) bg("yellow") resetFormat()]])<br />
<br />
-- Or another trigger to highlight several different things<br />
permSubstringTrigger("Highlight stuff", "General", {"pixie", "cat", "dog", "rabbit"},<br />
[[selectString(line, 1) fg ("blue") bg("yellow") resetFormat()]])<br />
</syntaxhighlight><br />
{{note}} Mudlet by design allows duplicate names - so calling permSubstringTrigger with the same name will keep creating new triggers. You can check if a trigger already exists with the [[Manual:Lua_Functions#exists|exists()]] function.<br />
<br />
==permScript==<br />
;permScript(name, parent, lua code)<br />
: Creates a new script in the Script Editor that stays after Mudlet is restarted.<br />
<br />
;Parameters<br />
* ''name'': name of the script.<br />
* ''parent'': name of the script group you want the script to go in.<br />
* ''lua code'': is the code with string you are putting in your script.<br />
<br />
;Returns<br />
* a unique id number for that script.<br />
<br />
: See also: [[#enableScript|enableScript()]], [[#exists|exists()]], [[#appendScript|appendScript()]], [[#disableScript|disableScript()]], [[#getScript|getScript()]], [[#setScript|setScript()]]<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
-- create a script in the "first script group" group<br />
permScript("my script", "first script group", [[send ("my script that's in my first script group fired!")]])<br />
-- create a script that's not in any group; just at the top<br />
permScript("my script", "", [[send ("my script that's in my first script group fired!")]])<br />
<br />
-- enable Script - a script element is disabled at creation<br />
enableScript("my script")<br />
</syntaxhighlight><br />
<br />
{{note}} The script is called once but NOT active after creation, it will need to be enabled by [[#enableScript|enableScript()]].<br />
<br />
{{note}} Mudlet by design allows duplicate names - so calling permScript with the same name will keep creating new script elements. You can check if a script already exists with the [[Manual:Lua_Functions#exists|exists()]] function.<br />
<br />
{{note}} If the ''lua code'' parameter is an empty string, then the function will create a script group instead.<br />
<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
==permTimer==<br />
;permTimer(name, parent, seconds, lua code)<br />
: Creates a persistent timer that stays after Mudlet is restarted and shows up in the Script Editor.<br />
<br />
;Parameters<br />
* ''name'' <br />
:name of the timer.<br />
* ''parent'' <br />
:name of the timer group you want the timer to go in.<br />
* ''seconds'' <br />
:a floating point number specifying a delay in seconds after which the timer will do the lua code (stored as the timer's "script") you give it as a string.<br />
* ''lua code'' is the code with string you are doing this to.<br />
<br />
;Returns<br />
* a unique id number for that timer.<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
-- create a timer in the "first timer group" group<br />
permTimer("my timer", "first timer group", 4.5, [[send ("my timer that's in my first timer group fired!")]])<br />
-- create a timer that's not in any group; just at the top<br />
permTimer("my timer", "", 4.5, [[send ("my timer that's in my first timer group fired!")]])<br />
<br />
-- enable timer - they start off disabled until you're ready<br />
enableTimer("my timer")<br />
</syntaxhighlight><br />
<br />
{{note}} The timer is NOT active after creation, it will need to be enabled by a call to [[#enableTimer|enableTimer()]] before it starts.<br />
<br />
{{note}} Mudlet by design allows duplicate names - so calling permTimer with the same name will keep creating new timers. You can check if a timer already exists with the [[Manual:Lua_Functions#exists|exists()]] function.<br />
<br />
==permKey==<br />
;permKey(name, parent, [modifier], key code, lua code)<br />
: Creates a persistent key that stays after Mudlet is restarted and shows up in the Script Editor.<br />
<br />
;Parameters<br />
* ''name'' <br />
:name of the key.<br />
* ''parent'' <br />
:name of the timer group you want the timer to go in or "" for the top level.<br />
* ''modifier'' <br />
:(optional) modifier to use - can be one of ''mudlet.keymodifier.Control'', ''mudlet.keymodifier.Alt'', ''mudlet.keymodifier.Shift'', ''mudlet.keymodifier.Meta'', ''mudlet.keymodifier.Keypad'', or ''mudlet.keymodifier.GroupSwitch'' or the default value of ''mudlet.keymodifier.None'' which is used if the argument is omitted. To use multiple modifiers, add them together: ''(mudlet.keymodifier.Shift + mudlet.keymodifier.Control)''<br />
* ''key code'' <br />
: actual key to use - one of the values available in ''mudlet.key'', e.g. ''mudlet.key.Escape'', ''mudlet.key.Tab'', ''mudlet.key.F1'', ''mudlet.key.A'', and so on. The list is a bit long to list out in full so it is [https://github.com/Mudlet/Mudlet/blob/development/src/mudlet-lua/lua/KeyCodes.lua#L2 available here].<br />
: set to -1 if you want to create a key folder instead.<br />
* ''lua code'<br />
: code you would like the key to run.<br />
<br />
;Returns<br />
* a unique id number for that key.<br />
<br />
{{MudletVersion|3.2+, creating key folders in Mudlet 4.10}}<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
-- create a key at the top level for F8<br />
permKey("my key", "", mudlet.key.F8, [[echo("hey this thing actually works!\n")]])<br />
<br />
-- or Ctrl+F8<br />
permKey("my key", "", mudlet.keymodifier.Control, mudlet.key.F8, [[echo("hey this thing actually works!\n")]])<br />
<br />
-- Ctrl+Shift+W<br />
permKey("jump keybinding", "", mudlet.keymodifier.Control + mudlet.keymodifier.Shift, mudlet.key.W, [[send("jump")]])<br />
</syntaxhighlight><br />
<br />
{{note}} Mudlet by design allows duplicate names - so calling permKey with the same name will keep creating new keys. You can check if a key already exists with the [[Manual:Lua_Functions#exists|exists()]] function. The key will be created even if the lua code does not compile correctly - but this will be apparent as it will be seen in the Editor.<br />
<br />
==printCmdLine==<br />
;printCmdLine([name], text)<br />
<br />
: Replaces the current text in the input line, and sets it to the given text.<br />
: See also: [[Manual:Lua_Functions#clearCmdLine|clearCmdLine()]], [[#appendCmdLine|appendCmdLine()]]<br />
<br />
;Parameters<br />
* ''name'': (optional) name of the command line. If not given, main commandline's text will be set.<br />
* ''text'': text to set<br />
<br />
<syntaxhighlight lang="lua"><br />
printCmdLine("say I'd like to buy ")<br />
</syntaxhighlight><br />
<br />
==raiseEvent==<br />
;raiseEvent(event_name, arg-1, … arg-n)<br />
<br />
: Raises the event event_name. The event system will call the main function (the one that is called exactly like the script name) of all such scripts in this profile that have registered event handlers. If an event is raised, but no event handler scripts have been registered with the event system, the event is ignored and nothing happens. This is convenient as you can raise events in your triggers, timers, scripts etc. without having to care if the actual event handling has been implemented yet - or more specifically how it is implemented. Your triggers raise an event to tell the system that they have detected a certain condition to be true or that a certain event has happened. How - and if - the system is going to respond to this event is up to the system and your trigger scripts don’t have to care about such details. For small systems it will be more convenient to use regular function calls instead of events, however, the more complicated your system will get, the more important events will become because they help reduce complexity very much.<br />
<br />
:The corresponding event handlers that listen to the events raised with raiseEvent() need to use the script name as function name and take the correct number of arguments. <br />
<br />
:See also: [[#raiseGlobalEvent|raiseGlobalEvent]]<br />
<br />
{{note}} possible arguments can be string, number, boolean, table, function, or nil.<br />
<br />
;Example:<br />
<br />
:raiseEvent("fight") a correct event handler function would be: myScript( event_name ). In this example raiseEvent uses minimal arguments, name the event name. There can only be one event handler function per script, but a script can still handle multiple events as the first argument is always the event name - so you can call your own special handlers for individual events. The reason behind this is that you should rather use many individual scripts instead of one huge script that has all your function code etc. Scripts can be organized very well in trees and thus help reduce complexity on large systems.<br />
<br />
Where the number of arguments that your event may receive is not fixed you can use [http://www.lua.org/manual/5.1/manual.html#2.5.9 ''...''] as the last argument in the ''function'' declaration to handle any number of arguments. For example:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- try this function out with "lua myscripthandler(1,2,3,4)"<br />
function myscripthandler(a, b, ...)<br />
print("Arguments a and b are: ", a,b)<br />
-- save the rest of the arguments into a table<br />
local otherarguments = {...}<br />
print("Rest of the arguments are:")<br />
display(otherarguments)<br />
<br />
-- access specific otherarguments:<br />
print("First and second otherarguments are: ", otherarguments[1], otherarguments[2])<br />
end<br />
</syntaxhighlight><br />
<br />
==raiseGlobalEvent==<br />
;raiseGlobalEvent(event_name, arg-1, … arg-n)<br />
<br />
: Like [[Manual:Lua_Functions#raiseEvent|raiseEvent()]] this raises the event "event_name", but this event is sent to all '''other''' opened profiles instead. The profiles receive the event in circular alphabetical order (if profile "C" raised this event and we have profiles "A", "C", and "E", the order is "E" -> "A", but if "E" raised the event the order would be "A" -> "C"); execution control is handed to the receiving profiles so that means that long running events may lock up the profile that raised the event.<br />
<br />
: The sending profile's name is automatically appended as the last argument to the event.<br />
<br />
{{note}} possible arguments can be string, number, boolean, or nil, but not table or function.<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- from profile called "My game" this raises an event "my event" with additional arguments 1, 2, 3, "My game" to all profiles except the original one<br />
raiseGlobalEvent("my event", 1, 2, 3)<br />
<br />
-- want the current profile to receive it as well? Use raiseEvent<br />
raiseEvent("my event", 1, 2, 3)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua><br />
-- example of calling functions in one profile from another:<br />
-- profile B:<br />
control = control or {}<br />
function control.updateStatus()<br />
disableTrigger("test triggers")<br />
print("disabling triggers worked!")<br />
end<br />
<br />
-- this handles calling the right function in the control table<br />
function control.marshaller(_, callfunction)<br />
if control[callfunction] then control[callfunction]()<br />
else<br />
cecho("<red>Asked to call an unknown function: "..callfunction)<br />
end<br />
end<br />
<br />
registerAnonymousEventHandler("sysSendAllProfiles", "control.marshaller")<br />
<br />
-- profile A:<br />
raiseGlobalEvent("sysSendAllProfiles", "updateStatus")<br />
raiseGlobalEvent("sysSendAllProfiles", "invalidfunction")<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.1.0}}<br />
<br />
Tip: you might want to add the [[Manual:Miscellaneous_Functions#getProfileName|profile name]] to your plain [[Manual:Miscellaneous_Functions#raiseEvent|raiseEvent()]] arguments. This'll help you tell which profile your event came from similar to [[#raiseGlobalEvent|raiseGlobalEvent()]].<br />
<br />
==registerNamedTimer==<br />
; success = registerNamedTimer(userName, timerName, time, functionReference, [repeating])<br />
<br />
:Registers a named timer with name timerName. Named timers are protected from duplication and can be stopped and resumed, unlike normal tempTimers. A separate list is kept for each userName, to enforce name spacing and avoid collisions<br />
<br />
;See also: [[Manual:Lua_Functions#tempTimer|tempTimer()]], [[Manual:Lua_Functions#stopNamedTimer|stopNamedTimer()]], [[Manual:Lua_Functions#resumeNamedTimer|resumeNamedTimer()]], [[Manual:Lua_Functions#deleteNamedTimer|deleteNamedTimer()]], [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
* ''timerName:''<br />
: 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.<br />
* ''time:''<br />
: The amount of time in seconds to wait before firing.<br />
* ''functionReference:''<br />
: The function reference to run when the event comes in. Can be the name of a function, "handlerFunction", or the lua function itself.<br />
* ''repeating:''<br />
: (optional) if true, the timer continue to fire until the stop it using [[Manual:Lua_Functions#stopNamedTimer|stopNamedTimer()]]<br />
;Returns <br />
* true if successful, otherwise errors.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- establish a named timer called "Check balance" which runs balanceChecker() after 1 second<br />
-- it is started automatically when registered, and fires only once despite being run twice<br />
-- you wouldn't do this intentionally, but illustrates the duplicate protection<br />
registerNamedTimer("Demonnic", "Check Balance", 1, balanceChecker)<br />
registerNamedTimer("Demonnic", "Check Balance", 1, balanceChecker)<br />
<br />
-- then the next time you want to make/use the same timer, you can shortcut it with<br />
resumeNamedTimer("Demonnic", "Check Balance")<br />
</syntaxhighlight><br />
<br />
==remainingTime==<br />
;remainingTime(timer id number or name)<br />
<br />
: Returns the remaining time in floating point form in seconds (if it is active) for the timer (temporary or permanent) with the id number or the (first) one found with the name.<br />
: If the timer is inactive or has expired or is not found it will return a ''nil'' and an ''error message''. It, theoretically could also return 0 if the timer is overdue, i.e. it has expired but the internal code has not yet been run but that has not been seen in during testing. Permanent ''offset timers'' will only show as active during the period when they are running after their parent has expired and started them.<br />
<br />
{{MudletVersion|3.20}}<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
tid = tempTimer(600, [[echo("\nYour ten minutes are up.\n")]])<br />
echo("\nYou have " .. remainingTime(tid) .. " seconds left, use it wisely... \n")<br />
<br />
-- Will produce something like:<br />
<br />
You have 599.923 seconds left, use it wisely... <br />
<br />
-- Then ten minutes time later:<br />
<br />
Your ten minutes are up.<br />
<br />
</syntaxhighlight><br />
<br />
==resetProfileIcon==<br />
;resetProfileIcon()<br />
: Resets the profile's icon in the connection screen to default.<br />
<br />
See also: [[#setProfileIcon|setProfileIcon()]].<br />
<br />
{{MudletVersion|4.0}}<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
resetProfileIcon()<br />
</syntaxhighlight><br />
<br />
==resetStopWatch==<br />
;resetStopWatch(watchID)<br />
:This function resets the time to 0:0:0.0, but does not stop or start the stop watch. You can stop it with [[Manual:Lua_Functions#stopStopWatch | stopStopWatch]] or start it with [[Manual:Lua_Functions#startStopWatch | startStopWatch]] → [[Manual:Lua_Functions#createStopWatch | createStopWatch]]<br />
<br />
==resumeNamedTimer==<br />
; success = resumeNamedTimer(userName, handlerName)<br />
<br />
:Resumes a named timer with name handlerName and causes it to fire again. One time unless it was registered as repeating.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]], [[Manual:Lua_Functions#stopNamedTimer|stopNamedTimer()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameter<br />
* ''userName:''<br />
: The user name the event handler was registered under.s<br />
* ''handlerName:''<br />
: The name of the handler to resume. Same as used when you called [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]]<br />
<br />
;Returns <br />
* true if successful, false if it didn't exist. If the timer is waiting to fire it will be restarted at 0.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local resumed = resumeNamedTimer("Demonnic", "DemonVitals")<br />
if resumed then<br />
cecho("DemonVitals resumed!")<br />
else<br />
cecho("DemonVitals doesn't exist, so cannot resume it.")<br />
end<br />
</syntaxhighlight><br />
<br />
==setButtonState==<br />
;setButtonState(ButtonNameOrID, checked)<br />
:Sets the state of a check-able ("push-down") type button from any Mudlet item's script - but does not cause the script or one of the commands associated with that button to be run/sent.<br />
: See also: [[#getButtonState|getButtonState()]].<br />
{{MudletVersion|4.13}}<br />
<br />
;Parameters<br />
* ''ButtonNameOrID:''<br />
: The name of the button as a string or a unique ID (positive) integer number {for a name only one matching one will be affected - it will be the same one that the matching [[#getButtonState|getButtonState()]] reports upon}.<br />
* ''checked:''<br />
: boolean value that indicated whether the state required is down (''true'') or up (''false''). <br />
<br />
;Returns:<br />
* A boolean value indicating ''true'' if the visible state was actually changed, i.e. had any effect. This function will return a ''nil'' and a suitable error message if the identifying name or ID was not found or was not a check-able (push-down) button item (i.e. was a non-checkable button or a menu or a toolbar instead).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- inside, for example, an initialization script for a GUI package:<br />
setButtonState("Sleep", false)<br />
setButtonState("Sit", false)<br />
-- these are going to be used as "radio" buttons where setting one<br />
-- of them will unset all the others, they will each need something<br />
-- similar in their own scripts to unset all the others in the set<br />
-- and also something to prevent them from being unset by clicking<br />
-- on themselves:<br />
setButtonState("Wimpy", true)<br />
setButtonState("Defensive", false)<br />
setButtonState("Normal", false)<br />
setButtonState("Brave", false)<br />
if character.type == "Warrior" then<br />
-- Only one type has this mode - and it can only be reset by<br />
-- something dying (though that could be us!)<br />
setButtonState("Beserk!!!", false)<br />
end<br />
</syntaxhighlight><br />
<br />
==setConsoleBufferSize==<br />
;setConsoleBufferSize([consoleName], linesLimit, sizeOfBatchDeletion)<br />
:Sets the maximum number of lines a buffer (main window or a miniconsole) can hold. Default is 10,000.<br />
:Returns nothing on success (up to '''Mudlet 4.16''') or ''true'' (from '''Mudlet 4.17'''); ''nil'' and an error message on failure.<br />
<br />
;Parameters<br />
* ''consoleName:''<br />
: (optional) The name of the window. If omitted, uses the main console.<br />
* ''linesLimit:''<br />
: Sets the amount of lines the buffer should have. <br />
{{note}} Mudlet performs extremely efficiently with even huge numbers, but there is of course a limit to your computer's memory. As of Mudlet 4.7+, this amount will be capped to that limit on macOS and Linux (on Windows, it's capped lower as Mudlet on Windows is 32bit).<br />
* ''sizeOfBatchDeletion:''<br />
: Specifies how many lines should Mudlet delete at once when you go over the limit - it does it in bulk because it's efficient to do so.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- sets the main windows size to 1 million lines maximum - which is more than enough!<br />
setConsoleBufferSize("main", 1000000, 1000)<br />
</syntaxhighlight><br />
<br />
==setProfileIcon==<br />
;setProfileIcon(iconPath)<br />
:Set a custom icon for this profile in the connection screen. <br />
<br />
:Returns true if successful, or nil+error message if not.<br />
<br />
:See also: [[#resetProfileIcon|resetProfileIcon()]].<br />
<br />
{{MudletVersion|4.0}}<br />
<br />
;Parameters<br />
* ''iconPath:''<br />
: Full location of the icon - can be .png or .jpg with ideal dimensions of 120x30.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- set a custom icon that is located in an installed package called "mypackage"<br />
setProfileIcon(getMudletHomeDir().."/mypackage/icon.png")<br />
</syntaxhighlight><br />
<br />
==setScript==<br />
;setScript(scriptName, luaCode, [occurrence])<br />
: Sets the script's Lua code, replacing existing code. If you have many scripts with the same name, use the 'occurrence' parameter to choose between them.<br />
: If you'd like to add code instead of replacing it, have a look at [[Manual:Lua_Functions#appendScript|appendScript()]].<br />
: Returns -1 if the script isn't found - to create a script, use [[Manual:Lua_Functions#permScript|permScript()]].<br />
<br />
: See also: [[Manual:Lua_Functions#permScript|permScript()]], [[Manual:Lua_Functions#enableScript|enableScript()]], [[Manual:Lua_Functions#disableScript|disableScript()]], [[Manual:Lua_Functions#getScript|getScript()]], [[Manual:Lua_Functions#appendScript|appendScript()]]<br />
<br />
;Returns<br />
* a unique id number for that script.<br />
<br />
;Parameters<br />
* ''scriptName'': name of the script to change the code.<br />
* ''luaCode'': new Lua code to set.<br />
* ''occurrence'': The position of the script. Optional, defaults to 1 (first).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- an example of setting the script lua code from the first occurrence of "testscript"<br />
setScript("testscript", [[echo("This is a test\n")]], 1)<br />
</syntaxhighlight><br />
{{MudletVersion|4.8}}<br />
<br />
==setStopWatchName==<br />
;setStopWatchName(watchID/currentStopWatchName, newStopWatchName)<br />
<br />
;Parameters<br />
* ''watchID'' (number) / ''currentStopWatchName'' (string): The stopwatch ID you get from [[Manual:Lua_Functions#createStopWatch|createStopWatch()]] or the name supplied to that function at that time, or previously applied with this function.<br />
* ''newStopWatchName'' (string): The name to use for this stopwatch from now on.<br />
<br />
;Returns<br />
* ''true'' on success, ''nil'' and an error message if no matching stopwatch is found.<br />
<br />
{{note}} Either ''currentStopWatchName'' or ''newStopWatchName'' may be empty strings: if the first of these is so then the ''lowest'' ID numbered stopwatch without a name is chosen; if the second is so then an existing name is removed from the chosen stopwatch.<br />
<br />
==setStopWatchPersistence==<br />
;setStopWatchPersistence(watchID/watchName, state)<br />
<br />
;Parameters<br />
* ''watchID'' (number) / ''watchName'' (string): The stopwatch ID you get from [[Manual:Lua_Functions#createStopWatch|createStopWatch()]] or the name supplied to that function or applied later with [[Manual:Lua_Functions#setStopWatchName|setStopWatchName()]]<br />
* ''state'' (boolean): if ''true'' the stopWatch will be saved.<br />
<br />
;Returns<br />
* ''true'' on success, ''nil'' and an error message if no matching stopwatch is found.<br />
<br />
:Sets or resets the flag so that the stopwatch is saved between sessions or after a [[Manual:Miscellaneous_Functions#resetProfile|resetProfile()]] call. If set then, if ''stopped'' the elapsed time recorded will be unchanged when the stopwatch is reloaded in the next session; if ''running'' the elapsed time will continue to increment and it will include the time that the profile was not loaded, therefore it can be used to measure events in real-time, outside of the profile!<br />
<br />
{{note}} When a persistent stopwatch is reloaded in a later session (or after a use of ''resetProfile()'') the stopwatch may not be allocated the same ID number as before - therefore it is advisable to assign any persistent stopwatches a name, either when it is created or before the session is ended.<br />
<br />
==setTriggerStayOpen==<br />
;setTriggerStayOpen(name, number of lines)<br />
:Sets for how many more lines a trigger script should fire or a chain should stay open after the trigger has matched - so this allows you to extend or shorten the ''fire length'' of a trigger. The main use of this function is to close a chain when a certain condition has been met.<br />
<br />
;Parameters<br />
* ''name:'' The name of the trigger which has a fire length set (and which opens the chain).<br />
* ''number of lines'': 0 to close the chain, or a positive number to keep the chain open that much longer.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- if you have a trigger that opens a chain (has some fire length) and you'd like it to be closed <br />
-- on the next prompt, you could make a prompt trigger inside the chain with a script of:<br />
setTriggerStayOpen("Parent trigger name", 0)<br />
-- to close it on the prompt!<br />
</syntaxhighlight><br />
<br />
==startStopWatch==<br />
;startStopWatch(watchName or watchID, [resetAndRestart])<br />
<br />
:Stopwatches can be stopped (with [[Manual:Lua_Functions#stopStopWatch|stopStopWatch()]]) and then re-started any number of times. '''To ensure backwards compatibility, if the stopwatch is identified by a ''numeric'' argument then, ''unless a second argument of false is supplied as well'' this function will also reset the stopwatch to zero and restart it - whether it is running or not'''; otherwise only a stopped watch can be started and only a started watch may be stopped. Trying to repeat either will produce a nil and an error message instead; also the recorded time is no longer reset so that they can now be used to record a total of isolated periods of time like a real stopwatch.<br />
<br />
:See also: [[Manual:Lua_Functions#createStopWatch|createStopWatch()]], [[Manual:Lua_Functions#stopStopWatch|stopStopWatch()]]<br />
<br />
;Parameters<br />
* ''watchID''/''watchName'': The stopwatch ID you get with [[Manual:Lua_Functions#createStopWatch|createStopWatch()]], or from '''4.4.0''' the name assigned with that function or [[Manual:Lua_Functions#setStopWatchName|setStopWatchName()]].<br />
* ''resetAndRestart'': Boolean flag needed (as ''false'') to make the function from '''4.4.0''', when supplied with a numeric watch ID, to '''not''' reset the stopwatch and only start a previously stopped stopwatch. This behavior is automatic when a string watch name is used to identify the stopwatch but differs from how the function behaved prior to that version.<br />
<br />
;Returns<br />
* ''true'' on success, ''nil'' and an error message if no matching stopwatch is found or if it cannot be started (because the later style behavior was indicated and it was already running).<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- this is a common pattern for re-using stopwatches prior to 4.4.0 and starting them:<br />
watch = watch or createStopWatch()<br />
startStopWatch(watch)<br />
</syntaxhighlight><br />
<br />
:: After 4.4.0 the above code will work the same as it does not provide a second argument to the ''startStopWatch()'' function - if a ''false'' was used there it would be necessary to call ''stopStopWatch(...)'' and then ''resetStopWatch(...)'' before using ''startStopWatch(...)'' to re-use the stopwatch if the ID form is used, '''this is thus not quite the same behavior but it is more consistent with the model of how a real stopwatch would act.'''<br />
<br />
==stopAllNamedTimers==<br />
; stopAllNamedTimers(userName)<br />
<br />
:Stops all named timers for userName and prevents them from firing any more. Information is retained and timers can be resumed.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]], [[Manual:Lua_Functions#stopNamedTimer|stopNamedTimer()]], [[Manual:Lua_Functions#resumeNamedTimer|resumeNamedTimer()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
stopAllNamedTimers("Demonnic") -- emergency stop situation, most likely.<br />
</syntaxhighlight><br />
<br />
==stopNamedTimer==<br />
; success = stopNamedTimer(userName, handlerName)<br />
<br />
:Stops a named timer with name handlerName and prevents it from firing any more. Information is stored so it can be resumed later if desired.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]], [[Manual:Lua_Functions#resumeNamedTimer|resumeNamedTimer()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
* ''handlerName:''<br />
: The name of the handler to stop. Same as used when you called [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]]<br />
<br />
;Returns <br />
* true if successful, false if it didn't exist or was already stopped<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local stopped = stopNamedTimer("Demonnic", "DemonVitals")<br />
if stopped then<br />
cecho("DemonVitals stopped!")<br />
else<br />
cecho("DemonVitals doesn't exist or already stopped; either way it won't fire any more.")<br />
end<br />
</syntaxhighlight><br />
<br />
==stopStopWatch==<br />
;stopStopWatch(watchID or watchName)<br />
:"Stops" (though see the note below) the stop watch and returns (only the '''first''' time it is called after the stopwatch has been set running with [[Manual:Lua_Functions#startStopWatch()|startStopWatchTime()]]) the elapsed time as a number of seconds, with a decimal portion give a resolution in milliseconds (thousandths of a second). You can also retrieve the current time without stopping the stopwatch with [[Manual:Lua_Functions#getStopWatchTime|getStopWatchTime()]], [[Manual:Lua_Functions#getBrokenDownStopWatchTime|getBrokenDownStopWatchTime()]].<br />
<br />
:See also: [[Manual:Lua_Functions#createStopWatch|createStopWatch()]]<br />
<br />
;Parameters<br />
* ''watchID:'' The stopwatch ID you get with [[Manual:Lua_Functions#createStopWatch|createStopWatch()]] or from Mudlet '''4.4.0''' the name given to that function or later set with [[Manual:Lua_Functions#setStopWatchName|setStopWatchName()]].<br />
<br />
;Returns<br />
* the elapsed time as a floating-point number of seconds - it may be negative if the time was previously adjusted/preset to a negative amount (with [[Manual:Lua_Functions#adjustStopWatch|adjustStopWatch()]]) and that period has not yet elapsed.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- this is a common pattern for re-using stopwatches and starting them:<br />
watch = watch or createStopWatch()<br />
startStopWatch(watch)<br />
<br />
-- do some long-running code here ...<br />
<br />
print("The code took: "..stopStopWatch(watch).."s to run.")<br />
</syntaxhighlight><br />
<br />
==tempAnsiColorTrigger==<br />
;tempAnsiColorTrigger(foregroundColor[, backgroundColor], code[, expireAfter])<br />
:This is an alternative to [[Manual:Lua_Functions#tempColorTrigger|tempColorTrigger()]] which supports the full set of 256 ANSI color codes directly and makes a color trigger that triggers on the specified foreground and background color. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
<br />
;Parameters<br />
* ''foregroundColor:'' The foreground color you'd like to trigger on.<br />
* ''backgroundColor'': The background color you'd like to trigger on.<br />
* ''code to do'': The code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function.<br />
* ''expireAfter'': Delete trigger after a specified number of matches. You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
''BackgroundColor'' and/or ''expireAfter'' may be omitted.<br />
<br />
;Color codes (note that the values greater than or equal to zero are the actual number codes that ANSI and the game server uses for the 8/16/256 color modes)<br />
<br />
::Special codes (may be extended in the future):<br />
:::-2 = default text color (what is used after an ANSI SGR 0 m code that resets the foreground and background colors to those set in the preferences)<br />
:::-1 = ignore (only '''one''' of the foreground or background codes can have this value - otherwise it would not be a ''color'' trigger!)<br />
<br />
::ANSI 8-color set:<br />
:::0 = (dark) black<br />
:::1 = (dark) red<br />
:::2 = (dark) green<br />
:::3 = (dark) yellow<br />
:::4 = (dark) blue<br />
:::5 = (dark) magenta<br />
:::6 = (dark) cyan<br />
:::7 = (dark) white {a.k.a. light gray}<br />
<br />
::Additional colors in 16-color set:<br />
:::8 = light black {a.k.a. dark gray}<br />
:::9 = light red<br />
:::10 = light green<br />
:::11 = light yellow<br />
:::12 = light blue<br />
:::13 = light magenta<br />
:::14 = light cyan<br />
:::15 = light white<br />
<br />
::6 x 6 x 6 RGB (216) colors, shown as a 3x2-digit hex code<br />
:::16 = #000000<br />
:::17 = #000033<br />
:::18 = #000066<br />
:::...<br />
:::229 = #FFFF99<br />
:::230 = #FFFFCC<br />
:::231 = #FFFFFF<br />
<br />
::24 gray-scale, also show as a 3x2-digit hex code<br />
:::232 = #000000<br />
:::233 = #0A0A0A<br />
:::234 = #151515<br />
:::...<br />
:::253 = #E9E9E9<br />
:::254 = #F4F4F4<br />
:::255 = #FFFFFF<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- This script will re-highlight all text in a light cyan foreground color on any background with a red foreground color<br />
-- until another foreground color in the current line is being met. temporary color triggers do not offer match_all<br />
-- or filter options like the GUI color triggers because this is rarely necessary for scripting.<br />
-- A common usage for temporary color triggers is to schedule actions on the basis of forthcoming text colors in a particular context.<br />
tempAnsiColorTrigger(14, -1, [[selectString(matches[1],1) fg("red")]])<br />
-- or:<br />
tempAnsiColorTrigger(14, -1, function()<br />
selectString(matches[1], 1)<br />
fg("red")<br />
end)<br />
<br />
-- match the trigger only 4 times<br />
tempColorTrigger(14, -1, [[selectString(matches[1],1) fg("red")]], 4)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.17}}<br />
<br />
==tempAlias==<br />
;aliasID = tempAlias(regex, code to do)<br />
:Creates a temporary alias - temporary in the sense that it won't be saved when Mudlet restarts (unless you re-create it). The alias will go off as many times as it matches, it is not a one-shot alias. The function returns an ID for subsequent [[Manual:Lua_Functions#enableAlias|enableAlias()]], [[Manual:Lua_Functions#disableAlias|disableAlias()]] and [[Manual:Lua_Functions#killAlias|killAlias()]] calls.<br />
<br />
;Parameters<br />
* ''regex:'' Alias pattern in regex.<br />
* ''code to do:'' The code to do when the alias fires - wrap it in [[ ]].<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
myaliasID = tempAlias("^hi$", [[send ("hi") echo ("we said hi!")]])<br />
<br />
-- you can also delete the alias later with:<br />
killAlias(myaliasID)<br />
<br />
-- tempAlias also accepts functions (and thus closures) - which can be an easier way to embed variables and make the code for an alias look less messy:<br />
<br />
local variable = matches[2]<br />
tempAlias("^hi$", function () send("hello, " .. variable) end)<br />
</syntaxhighlight><br />
<br />
==tempBeginOfLineTrigger==<br />
;tempBeginOfLineTrigger(part of line, code, expireAfter)<br />
:Creates a trigger that will go off whenever the part of line it's provided with matches the line right from the start (doesn't matter what the line ends with). The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls.<br />
<br />
;Parameters<br />
* ''part of line'': start of the line that you'd like to match. This can also be regex.<br />
* ''code to do'': code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function (since Mudlet 3.5.0).<br />
* ''expireAfter'': Delete trigger after a specified number of matches (since Mudlet 3.11). You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
mytriggerID = tempBeginOfLineTrigger("Hello", [[echo("We matched!")]])<br />
<br />
--[[ now this trigger will match on any of these lines:<br />
Hello<br />
Hello!<br />
Hello, Bob!<br />
<br />
but not on:<br />
Oh, Hello<br />
Oh, Hello!<br />
]]<br />
<br />
-- or as a function:<br />
mytriggerID = tempBeginOfLineTrigger("Hello", function() echo("We matched!") end)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- you can make the trigger match only a certain amount of times as well, 5 in this example:<br />
tempBeginOfLineTrigger("This is the start of the line", function() echo("We matched!") end, 5)<br />
<br />
-- if you want a trigger match not to count towards expiration, return true. In this example it'll match 5 times unless the line is "Start of line and this is the end."<br />
tempBeginOfLineTrigger("Start of line", <br />
function()<br />
if line == "Start of line and this is the end." then<br />
return true<br />
else<br />
return false<br />
end<br />
end, 5)<br />
</syntaxhighlight><br />
<br />
==tempButton==<br />
;tempButton(toolbar name, button text, orientation)<br />
:Creates a temporary button. Temporary means, it will disappear when Mudlet is closed.<br />
<br />
;Parameters:<br />
* ''toolbar name'': The name of the toolbar to place the button into.<br />
* ''button text'': The text to display on the button.<br />
* ''orientation'': a number 0 or 1 where 0 means horizontal orientation for the button and 1 means vertical orientation for the button. This becomes important when you want to have more than one button in the same toolbar.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- makes a temporary toolbar with two buttons at the top of the main Mudlet window <br />
lua tempButtonToolbar("topToolbar", 0, 0)<br />
lua tempButton("topToolbar", "leftButton", 0)<br />
lua tempButton("topToolbar", "rightButton", 0)<br />
</syntaxhighlight><br />
<br />
{{note}} ''This function is not that useful as there is no function yet to assign a Lua script or command to such a temporary button - though it may have some use to flag a status indication!''<br />
<br />
==tempButtonToolbar==<br />
;tempButtonToolbar(name, location, orientation)<br />
:Creates a temporary button toolbar. Temporary means, it will disappear when Mudlet is closed.<br />
<br />
;Parameters:<br />
* ''name'': The name of the toolbar.<br />
* ''location'': a number from 0 to 3, where 0 means "at the top of the screen", 1 means "left side", 2 means "right side" and 3 means "in a window of its own" which can be dragged and attached to the main Mudlet window if needed.<br />
* ''orientation'': a number 0 or 1, where 0 means horizontal orientation for the toolbar and 1 means vertical orientation for the toolbar. This becomes important when you want to have more than one toolbar in the same location of the window.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- makes a temporary toolbar with two buttons at the top of the main Mudlet window <br />
lua tempButtonToolbar("topToolbar", 0, 0)<br />
lua tempButton("topToolbar", "leftButton", 0)<br />
lua tempButton("topToolbar", "rightButton", 0)<br />
</syntaxhighlight><br />
<br />
==tempColorTrigger==<br />
;tempColorTrigger(foregroundColor, backgroundColor, code, expireAfter)<br />
:Makes a color trigger that triggers on the specified foreground and background color. Both colors need to be supplied in form of these simplified ANSI 16 color mode codes. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
See also: [[Manual:Mudlet Object Functions#tempAnsiColorTrigger|tempAnsiColorTrigger]]<br />
;Parameters<br />
* ''foregroundColor:'' The foreground color you'd like to trigger on (for ANSI colors, see [[Manual:Mudlet Object Functions#tempAnsiColorTrigger|tempAnsiColorTrigger]]).<br />
* ''backgroundColor'': The background color you'd like to trigger on (same as above).<br />
* ''code to do'': The code to do when the trigger runs - wrap it in <code>[[</code> and <code>]]</code>, or give it a Lua function, ie. <code>function() <nowiki><your code here></nowiki> end</code> (since Mudlet 3.5.0).<br />
* ''expireAfter'': Delete trigger after a specified number of matches (since Mudlet 3.11). You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
;Color codes<br />
<syntaxhighlight lang="lua"><br />
0 = default text color<br />
1 = light black<br />
2 = dark black<br />
3 = light red<br />
4 = dark red<br />
5 = light green<br />
6 = dark green<br />
7 = light yellow<br />
8 = dark yellow<br />
9 = light blue<br />
10 = dark blue<br />
11 = light magenta<br />
12 = dark magenta<br />
13 = light cyan<br />
14 = dark cyan<br />
15 = light white<br />
16 = dark white<br />
</syntaxhighlight><br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- This script will re-highlight all text in blue foreground colors on a black background with a red foreground color<br />
-- on a blue background color until another color in the current line is being met. temporary color triggers do not <br />
-- offer match_all or filter options like the GUI color triggers because this is rarely necessary for scripting. <br />
-- A common usage for temporary color triggers is to schedule actions on the basis of forthcoming text colors in a particular context.<br />
tempColorTrigger(9, 2, [[selectString(matches[1],1) fg("red") bg("blue")]])<br />
-- or:<br />
tempColorTrigger(9, 2, function()<br />
selectString(matches[1], 1)<br />
fg("red")<br />
bg("blue")<br />
end)<br />
<br />
-- match the trigger only 4 times<br />
tempColorTrigger(9, 2, [[selectString(matches[1],1) fg("red") bg("blue")]], 4)<br />
</syntaxhighlight><br />
<br />
==tempComplexRegexTrigger==<br />
;tempComplexRegexTrigger(name, regex, code, multiline, fg color, bg color, filter, match all, highlight fg color, highlight bg color, play sound file, fire length, line delta, expireAfter)<br />
:Allows you to create a temporary trigger in Mudlet, using any of the UI-available options. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
:Returns the trigger name, that you can use [[Manual:Lua_Functions#killTrigger|killTrigger()]] later on with.<br />
<br />
;Parameters<br />
* ''name'' - The name you call this trigger. <br />
* ''regex'' - The regular expression you want to match.<br />
* ''code'' - Code to do when the trigger runs. You need to wrap it in [[ ]], or give a Lua function (since Mudlet 3.5.0).<br />
* ''multiline'' - Set this to 1, if you use multiple regex (see note below), and you need the trigger to fire only if all regex have been matched within the specified line delta. Then all captures will be saved in ''multimatches'' instead of ''matches''. If this option is set to 0, the trigger will fire when any regex has been matched.<br />
* ''fg color'' - The foreground color you'd like to trigger on.<br />
* ''bg color'' - The background color you'd like to trigger on.<br />
* ''filter'' - Do you want only the filtered content (=capture groups) to be passed on to child triggers? Otherwise also the initial line.<br />
* ''match all'' - Set to 1, if you want the trigger to match all possible occurrences of the regex in the line. When set to 0, the trigger will stop after the first successful match.<br />
* ''highlight fg color'' - The foreground color you'd like your match to be highlighted in.<br />
* ''highlight bg color'' - The background color you'd like your match to be highlighted in.<br />
* ''play sound file'' - Set to the name of the sound file you want to play upon firing the trigger.<br />
* ''fire length'' - Number of lines within which all condition must be true to fire the trigger.<br />
* ''line delta'' - Keep firing the script for x more lines, after the trigger or chain has matched.<br />
* ''expireAfter'' - Delete trigger after a specified number of matches (since Mudlet 3.11). You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
{{Note}} Set the options starting at ''multiline'' to 0, if you don't want to use those options. Otherwise enter 1 to activate or the value you want to use.<br />
<br />
{{Note}} If you want to use the color option, you need to provide both fg and bg together.<br />
<br />
;Examples<br />
<br />
<syntaxhighlight lang="lua"><br />
-- This trigger will be activated on any new line received.<br />
triggerNumber = tempComplexRegexTrigger("anyText", "^(.*)$", [[echo("Text received!")]], 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)<br />
<br />
-- This trigger will match two different regex patterns:<br />
tempComplexRegexTrigger("multiTrigger", "first regex pattern", [[]], 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)<br />
tempComplexRegexTrigger("multiTrigger", "second regex pattern", [[echo("Trigger matched!")]], 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)<br />
</syntaxhighlight><br />
<br />
{{Note}} For making a multiline trigger like in the second example, you need to use the same trigger name and options, providing the new pattern to add. Note that only the last script given will be set, any others ignored.<br />
<br />
==tempExactMatchTrigger==<br />
;tempExactMatchTrigger(exact line, code, expireAfter)<br />
:Creates a trigger that will go off whenever the line from the game matches the provided line exactly (ends the same, starts the same, and looks the same). You don't need to use any of the regex symbols here (^ and $). The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
<br />
;Parameters<br />
* ''exact line'': exact line you'd like to match.<br />
* ''code'': code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function (since Mudlet 3.5.0).<br />
* ''expireAfter'': Delete trigger after a specified number of matches (since Mudlet 3.11). You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
mytriggerID = tempExactMatchTrigger("You have recovered balance on all limbs.", [[echo("We matched!")]])<br />
<br />
-- as a function:<br />
mytriggerID = tempExactMatchTrigger("You have recovered balance on all limbs.", function() echo("We matched!") end)<br />
<br />
-- expire after 4 matches:<br />
tempExactMatchTrigger("You have recovered balance on all limbs.", function() echo("Got balance back!\n") end, 4)<br />
<br />
-- you can also avoid expiration by returning true:<br />
tempExactMatchTrigger("You have recovered balance on all limbs.", function() echo("Got balance back!\n") return true end, 4)<br />
</syntaxhighlight><br />
<br />
==tempKey==<br />
;tempKey([modifier], key code, lua code)<br />
:Creates a keybinding. This keybinding isn't temporary in the sense that it'll go off only once (it'll go off as often as you use it), but rather it won't be saved when Mudlet is closed.<br />
<br />
: See also: [[#permKey|permKey()]], [[#killKey|killKey()]]<br />
<br />
* ''modifier'' <br />
:(optional) modifier to use - can be one of ''mudlet.keymodifier.Control'', ''mudlet.keymodifier.Alt'', ''mudlet.keymodifier.Shift'', ''mudlet.keymodifier.Meta'', ''mudlet.keymodifier.Keypad'', or ''mudlet.keymodifier.GroupSwitch'' or the default value of ''mudlet.keymodifier.None'' which is used if the argument is omitted. To use multiple modifiers, add them together: ''(mudlet.keymodifier.Shift + mudlet.keymodifier.Control)''<br />
* ''key code'' <br />
: actual key to use - one of the values available in ''mudlet.key'', e.g. ''mudlet.key.Escape'', ''mudlet.key.Tab'', ''mudlet.key.F1'', ''mudlet.key.A'', and so on. The list is a bit long to list out in full so it is [https://github.com/Mudlet/Mudlet/blob/development/src/mudlet-lua/lua/KeyCodes.lua#L2 available here].<br />
* ''lua code'<br />
: code you'd like the key to run - wrap it in [[ ]].<br />
<br />
;Returns<br />
* a unique id number for that key.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
keyID = tempKey(mudlet.key.F8, [[echo("hi")]])<br />
<br />
anotherKeyID = tempKey(mudlet.keymodifier.Control, mudlet.key.F8, [[echo("hello")]])<br />
<br />
-- bind Ctrl+Shift+W:<br />
tempKey(mudlet.keymodifier.Control + mudlet.keymodifier.Shift, mudlet.key.W, [[send("jump")]])<br />
<br />
-- delete it if you don't like it anymore<br />
killKey(keyID)<br />
<br />
-- tempKey also accepts functions (and thus closures) - which can be an easier way to embed variables and make the code for tempKeys look less messy:<br />
<br />
tempKey(mudlet.key.F8, function() echo("Hi\n") end)<br />
</syntaxhighlight><br />
<br />
==tempLineTrigger==<br />
;tempLineTrigger(from, howMany, code)<br />
:Temporary trigger that will fire on ''n'' consecutive lines following the current line. This is useful to parse output that is known to arrive in a certain line margin or to delete unwanted output from the game - the trigger does not require any patterns to match on. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
<br />
;Parameters:<br />
* ''from'': from which line after this one should the trigger activate - 1 will activate right on the next line.<br />
* ''howMany'': how many lines to run for after the trigger has activated.<br />
* ''code'': code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function (since Mudlet 3.5.0).<br />
<br />
;Example: <br />
<syntaxhighlight lang="lua"><br />
-- Will fire 3 times with the next line from the game<br />
tempLineTrigger(1, 3, function() print(" trigger matched!") end)<br />
<br />
-- Will fire 5 lines after the current line and fire twice on 2 consecutive lines<br />
tempLineTrigger(5, 2, function() print(" trigger matched!") end, 7)<br />
</syntaxhighlight><br />
<br />
==tempPromptTrigger==<br />
;tempPromptTrigger(code, expireAfter)<br />
:Temporary trigger that will match on the games prompt. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
<br />
{{note}} If the trigger is not working, check that the '''N:''' bottom-right has a number. This feature requires telnet Go-Ahead to be enabled in the game. <br />
<br />
{{MudletVersion|3.6}}<br />
<br />
;Parameters:<br />
* ''code'': <br />
: code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function.<br />
* ''expireAfter'': (available in Mudlet 3.11+)<br />
: Delete trigger after a specified number of matches. You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
;Example: <br />
<syntaxhighlight lang="lua"><br />
tempPromptTrigger(function()<br />
echo("hello! this is a prompt!")<br />
end)<br />
<br />
-- match only 2 times:<br />
tempPromptTrigger(function()<br />
echo("hello! this is a prompt!")<br />
end, 2)<br />
<br />
-- match only 2 times, unless the prompt is "55 health."<br />
tempPromptTrigger(function()<br />
if line == "55 health." then return true end<br />
end, 2)<br />
</syntaxhighlight><br />
<br />
==tempRegexTrigger==<br />
;tempRegexTrigger(regex, code, expireAfter)<br />
:Creates a temporary regex trigger that executes the code whenever it matches. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
<br />
;Parameters:<br />
* ''regex:'' regular expression that lines will be matched on.<br />
* ''code'': code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function (since Mudlet 3.5.0).<br />
* ''expireAfter'': Delete trigger after a specified number of matches (since Mudlet 3.11). You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
;Examples:<br />
<syntaxhighlight lang="lua"><br />
-- create a non-duplicate trigger that matches on any line and calls a function<br />
html5log = html5log or {}<br />
if html5log.trig then killTrigger(html5log.trig) end<br />
html5log.trig = tempRegexTrigger("^", [[html5log.recordline()]])<br />
-- or a simpler variant:<br />
html5log.trig = tempRegexTrigger("^", html5log.recordline)<br />
<br />
-- only match 3 times:<br />
tempRegexTrigger("^You prick (.+) twice in rapid succession with", function() echo("Hit "..matches[2].."!\n") end, 3)<br />
<br />
-- since Mudlet 4.11+ you can use named capturing groups<br />
tempRegexTrigger("^You see (?<material>\\w+) axe inside chest\\.", function() echo("\nAxe is " .. matches.material) end)<br />
</syntaxhighlight><br />
<br />
==tempTimer==<br />
;tempTimer(time, code to do[, repeating])<br />
:Creates a temporary one-shot timer and returns the timer ID, which you can use with [[Manual:Lua_Functions#enableTimer|enableTimer()]], [[Manual:Lua_Functions#disableTimer|disableTimer()]] and [[Manual:Lua_Functions#killTimer|killTimer()]] functions. You can use 2.3 seconds or 0.45 etc. After it has fired, the timer will be deactivated and destroyed, so it will only go off once. Here is a [[Manual:Introduction#Timers|more detailed introduction to tempTimer]].<br />
<br />
;Parameters<br />
* ''time:'' The time in seconds for which to set the timer for - you can use decimals here for precision. The timer will go off ''x'' given seconds after you make it.<br />
* ''code to do'': The code to do when the timer is up - wrap it in [[ ]], or provide a Lua function.<br />
* ''repeating'': (optional) if true, keep firing the timer over and over until you kill it (available in Mudlet 4.0+).<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- wait half a second and then run the command<br />
tempTimer(0.5, function() send("kill monster") end)<br />
<br />
-- echo between 1 and 5 seconds after creation<br />
tempTimer(math.random(1, 5), function() echo("hi!") end) <br />
<br />
-- or an another example - two ways to 'embed' variable in a code for later:<br />
local name = matches[2]<br />
tempTimer(2, [[send("hello, ]]..name..[[ !")]])<br />
-- or:<br />
tempTimer(2, function()<br />
send("hello, "..name)<br />
end)<br />
<br />
-- create a looping timer<br />
timerid = tempTimer(1, function() display("hello!") end, true)<br />
<br />
-- later when you'd like to stop it:<br />
killTimer(timerid)<br />
</syntaxhighlight><br />
<br />
{{note}} Double brackets, e.g: [[ ]] can be used to quote strings in Lua. The difference to the usual `" " quote syntax is that `[[ ]] also accepts the character ". Consequently, you don’t have to escape the " character in the above script. The other advantage is that it can be used as a multiline quote, so your script can span several lines.<br />
<br />
{{note}} Lua code that you provide as an argument is compiled from a string value when the timer fires. This means that if you want to pass any parameters by value e.g. you want to make a function call that uses the value of your variable myGold as a parameter you have to do things like this:<br />
<br />
<syntaxhighlight lang="lua"><br />
tempTimer( 3.8, [[echo("at the time of the tempTimer call I had ]] .. myGold .. [[ gold.")]] )<br />
<br />
-- tempTimer also accepts functions (and thus closures) - which can be an easier way to embed variables and make the code for timers look less messy:<br />
<br />
local variable = matches[2]<br />
tempTimer(3, function () send("hello, " .. variable) end)<br />
</syntaxhighlight><br />
<br />
==tempTrigger==<br />
;tempTrigger(substring, code, expireAfter)<br />
:Creates a substring trigger that executes the code whenever it matches. The function returns the trigger ID for subsequent [[Manual:Lua_Functions#enableTrigger|enableTrigger()]], [[Manual:Lua_Functions#disableTrigger|disableTrigger()]] and [[Manual:Lua_Functions#killTrigger|killTrigger()]] calls. The trigger is temporary in the sense that it won't stay when you close Mudlet, and it will go off multiple times until you disable or destroy it. You can also make it be temporary and self-delete after a number of matches with the ''expireAfter'' parameter.<br />
<br />
;Parameters:<br />
* ''substring'': The substring to look for - this means a part of the line. If your provided text matches anywhere within the line from the game, the trigger will go off.<br />
* ''code'': The code to do when the trigger runs - wrap it in [[ ]], or give it a Lua function (since Mudlet 3.5)<br />
* ''expireAfter'': Delete trigger after a specified number of matches (since Mudlet 3.11). You can make a trigger match not count towards expiration by returning true after it fires.<br />
<br />
Example:<br />
<syntaxhighlight lang="lua"><br />
-- this example will highlight the contents of the "target" variable.<br />
-- it will also delete the previous trigger it made when you call it again, so you're only ever highlighting one name<br />
if id then killTrigger(id) end<br />
id = tempTrigger(target, [[selectString("]] .. target .. [[", 1) fg("gold") resetFormat()]])<br />
<br />
-- you can also write the same line as:<br />
id = tempTrigger(target, function() selectString(target, 1) fg("gold") resetFormat() end)<br />
<br />
-- or like so if you have a highlightTarget() function somewhere<br />
id = tempTrigger(target, highlightTarget)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- a simpler trigger to replace "hi" with "bye" whenever you see it<br />
tempTrigger("hi", [[selectString("hi", 1) replace("bye")]])<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- this trigger will go off only 2 times<br />
tempTrigger("hi", function() selectString("hi", 1) replace("bye") end, 2)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- table to store our trigger IDs in<br />
nameIDs = nameIDs or {}<br />
-- delete any existing triggers we've already got<br />
for _, id in ipairs(nameIDs) do killTrigger(id) end<br />
<br />
-- create new ones, avoiding lots of ]] [[ to embed the name<br />
for _, name in ipairs{"Alice", "Ashley", "Aaron"} do<br />
nameIDs[#nameIDs+1] = tempTrigger(name, function() print(" Found "..name.."!") end)<br />
end<br />
</syntaxhighlight><br />
<br />
;Additional Notes:<br />
tempTriggers begin matching on the same line they're created on. <br />
<br />
If your ''code'' deletes and recreates the tempTrigger, or if you ''send'' a matching command again, it's possible to get into an infinite loop.<br />
<br />
Make use of the ''expireAfter'' parameter, [[Manual:Lua_Functions#disableTrigger|disableTrigger()]], or [[Manual:Lua_Functions#killTrigger|killTrigger()]] to prevent a loop from forming.<br />
<br />
[[Category:Mudlet Manual]]<br />
[[Category:Mudlet API]]</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:Table_Functions&diff=20400Manual:Table Functions2023-04-02T15:04:19Z<p>Demonnic: /* table.contains */</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Mudlet API documentation for functions 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.}}<br />
= Table Functions =<br />
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.<br />
<br />
==spairs==<br />
; spairs(tbl, sortFunction)<br />
: Returns an iterator similar to pairs(tbl) but sorts the keys before iterating through them. <br />
<br />
; Parameters<br />
* ''tbl:''<br />
: The table to iterate over<br />
* ''sortFunction:''<br />
: The function to use for determining what order to iterate the items in the table. Defaults to alphanumeric sorting by key. Similar to [[Manual:Lua_Functions#table.sort|table.sort]]. See example for more info.<br />
<br />
{{MudletVersion|4.10}}<br />
; Example:<br />
<syntaxhighlight lang=lua><br />
local tbl = { Tom = 40, Mary = 50, Joe = 23 }<br />
<br />
-- This iterates, sorting based on the key (which is the name in this case)<br />
for name, thingies in spairs(tbl) do<br />
echo(string.format("%s has %d thingies\n", name, thingies))<br />
end<br />
--[[<br />
Joe has 23 thingies<br />
Mary has 50 thingies<br />
Tom has 40 thingies<br />
--]]<br />
<br />
-- The function used below sorts based on the value. <br />
for name, thingies in spairs(tbl, function(t,a,b) return t[a] < t[b] end) do --iterate from lowest value to highest<br />
echo(string.format("%s has %d thingies\n", name, thingies))<br />
end<br />
--[[<br />
Joe has 23 thingies<br />
Tom has 40 thingies<br />
Mary has 50 thingies<br />
--]]<br />
<br />
-- This function can be used to sort a group of Geyser gauges based on their value (what percentage of the gauge is filled)<br />
local gaugeSort = function(t,a,b)<br />
local avalue = t[a].value or 100 -- treat non-gauges as though they are full gauges. If you know for -sure- the table only has gauges the 'or 100' is not needed.<br />
local bvalue = t[b].value or 100<br />
return avalue < bvalue<br />
end<br />
for _,gauge in spairs(tblOfGauges, gaugeSort) do<br />
-- do what you want with the gauges. First one will be the least full, then the next least full, until the last which will be the most full. <br />
-- If you replace the < with a > it will go from most full to least full instead.<br />
end<br />
</syntaxhighlight><br />
<br />
==table.collect==<br />
; table.collect(tbl, func)<br />
: Returns a table that is every key-value pair from tbl for which func(key,value) returns true<br />
<br />
; Parameters<br />
* ''tbl:''<br />
: The table to collect items from<br />
* ''func:''<br />
: the function to use for testing if an item should be collected or not<br />
<br />
{{MudletVersion|4.8}}<br />
; Example:<br />
<syntaxhighlight lang=lua><br />
local vitals = { hp = 3482, maxhp = 5000, mana = 3785, maxmana = 5000 }<br />
local pullHpKeys = function(key, value)<br />
if string.match(key, "hp") then return true end<br />
end<br />
local hp_values = table.collect(vitals, pullHpKeys)<br />
display(hp_values)<br />
</syntaxhighlight><br />
This prints the following:<br />
{<br />
hp = 3482,<br />
maxhp = 5000<br />
}<br />
; Returns<br />
: A table containing all the key/value pairs from tbl that cause func(key,value) to return true<br />
<br />
==table.complement==<br />
; table.complement (set1, set2)<br />
: Returns a table that is the relative complement of the first table with respect to the second table. Returns a complement of key/value pairs.<br />
<br />
; Parameters<br />
* ''table1:''<br />
* ''table2:''<br />
<br />
; Example:<br />
<syntaxhighlight lang=lua>local t1 = {key = 1,1,2,3}<br />
local t2 = {key = 2,1,1,1}<br />
local comp = table.complement(t1,t2)<br />
display(comp)</syntaxhighlight><br />
This prints the following:<br />
key = 1,<br />
[2] = 2,<br />
[3] = 3<br />
<br />
; Returns<br />
: A table containing all the key/value pairs from table1 that do not match the key/value pairs from table2.<br />
<br />
==table.concat==<br />
;table.concat(table, delimiter, startingindex, endingindex)<br />
: Joins a table into a string. Each item must be something which can be transformed into a string. <br />
: Returns the joined string.<br />
: See also: [[Manual:Lua_Functions#string.split|string.split]]<br />
<br />
; Parameters<br />
* '''table:'''<br />
: The table to concatenate into a string. Passed as a table.<br />
* '''delimiter:'''<br />
: Optional string to use to separate each element in the joined string. Passed as a string.<br />
* '''startingindex:'''<br />
: Optional parameter to specify which index to begin the joining at. Passed as an integer.<br />
* '''endingindex:'''<br />
: Optional parameter to specify the last index to join. Passed as an integer.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
--This shows a basic concat with none of the optional arguments<br />
testTable = {1,2,"hi","blah",}<br />
testString = table.concat(testTable)<br />
--testString would be equal to "12hiblah"<br />
<br />
--This example shows the concat using the optional delimiter<br />
testString = table.concat(testTable, ", ")<br />
--testString would be equal to "1, 2, hi, blah"<br />
<br />
--This example shows the concat using the delimiter and the optional starting index<br />
testString = table.concat(testTable, ", ", 2)<br />
--testString would be equal to "2, hi, blah"<br />
<br />
--And finally, one which uses all of the arguments<br />
testString = table.concat(testTable, ", ", 2, 3)<br />
--testString would be equal to "2, hi"<br />
</syntaxhighlight><br />
<br />
==table.contains==<br />
; table.contains (t, value)<br />
: Determines if a table contains a value as a key or as a value (recursive as of Mudlet 4.8+).<br />
: Returns true or false<br />
: See also: [[Manual:Lua_Functions#table.index_of|table.index_of]]<br />
{{note}} This tests for the 'value' parameter as either a '''key''' or '''value''' in the table. this means table.contains({"Bob"}, 1) will return true.<br />
<br />
; Parameters<br />
* '''t:''' <br />
: The table in which you are checking for the presence of the item as key or value..<br />
* '''value:''' <br />
: The value you are checking for within the table.<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua">local test_table = {"value1", "value2", "value3", "value4", "value5", "value6", "value7"}<br />
if table.contains(test_table, "value1") then <br />
print("Got value 1!")<br />
else<br />
print("Don't have it. Sorry!")<br />
end<br />
<br />
-- if the table has just a few values, you can skip making a local, named table:<br />
if table.contains({"Anna", "Alanna", "Hanna"}, "Anna") then <br />
print("Have 'Anna' in the list!")<br />
else<br />
print("Don't have the name. Sorry!")<br />
end<br />
<br />
-- don't forget, it will return true if the item is a key in the table as well<br />
display(table.contains({"bob"}, 1) -- displays true, as 1 is the key/index for "bob"<br />
-- If you really only want to check values, try table.index_of, which returns the key a value is found at, or nil if it is not found.<br />
</syntaxhighlight><br />
<br />
==table.deepcopy==<br />
; table.deepcopy (table)<br />
: Returns a complete copy of the table.<br />
<br />
; Parameters<br />
* '''table:''' <br />
: The table which you'd like to get a copy of.<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua">local test_table = { "value1", "value2", "value3", "value4" }<br />
<br />
-- by just doing:<br />
local newtable = test_table<br />
-- you're linking newtable to test_table. Any change in test_table will be reflected in newtable.<br />
<br />
-- however, by doing:<br />
local newtable = table.deepcopy(test_table)<br />
-- the two tables are completely separate now.<br />
</syntaxhighlight><br />
<br />
==table.intersection==<br />
; table.intersection (set1, set2)<br />
: Returns a table that is the relative intersection of the first table with respect to the second table. Returns a intersection of key/value pairs.<br />
<br />
; Parameters<br />
* ''table1:''<br />
* ''table2:''<br />
<br />
; Example:<br />
<syntaxhighlight lang=lua>local t1 = {key = 1,1,2,3}<br />
local t2 = {key = 1,1,1,1}<br />
local intersect = table.intersection(t1,t2)<br />
display(intersect)</syntaxhighlight><br />
This prints the following:<br />
key = 1,<br />
1<br />
<br />
; Returns<br />
: A table containing all the key/value pairs from table1 that match the key/value pairs from table2.<br />
<br />
==table.insert==<br />
; table.insert(table, [pos,] value)<br />
: Inserts element '''value''' at position '''pos''' in '''table''', shifting up other elements to open space, if necessary. The default '''value''' for '''pos''' is n+1, where n is the length of the table, so that a call table.insert(t,x) inserts x at the end of table t.<br />
: See also: [[Manual:Lua_Functions#table.remove|table.remove]]<br />
<br />
; Parameters<br />
* '''table:'''<br />
: The table in which you are inserting the value<br />
* '''pos:'''<br />
: Optional argument, determining where the value will be inserted. <br />
* '''value:'''<br />
: The variable that you are inserting into the table. Can be a regular variable, or even a table or function*.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
--it will inserts what inside the variable of matches[2] into at the end of table of 'test_db_name'. <br />
table.insert(test_db_name, matches[2])<br />
--it will inserts other thing at the first position of this table.<br />
table.insert(test_db_name, 1, "jgcampbell300")<br />
<br />
--[=[<br />
<br />
This results:<br />
<br />
test_db_name = {<br />
"jgcampbell300",<br />
"SlySven"<br />
}<br />
]=]<br />
<br />
</syntaxhighlight><br />
<br />
==table.index_of==<br />
; table.index_of(table, value)<br />
Returns the index (location) of an item in an indexed table, or '''nil''' if it's not found.<br />
<br />
; Parameters<br />
* '''table:'''<br />
: The table in which you are inserting the value<br />
* '''value:'''<br />
: The variable that you are searching for in the table.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- will return 1, because 'hi' is the first item in the list<br />
table.index_of({"hi", "bye", "greetings"}, "hi")<br />
<br />
-- will return 3, because 'greetings' is third in the list<br />
table.index_of({"hi", "bye", "greetings"}, "greetings")<br />
<br />
-- you can also use this in combination with table.remove(), which requires the location of the item to delete<br />
local words = {"hi", "bye", "greetings"}<br />
table.remove(words, table.index_of(words, "greetings"))<br />
<br />
-- however that won't work if the word isn't present, table.remove(mytable, nil (from table.index_of)) will give an error<br />
-- so if you're unsure, confirm with table.contains first<br />
local words = {"hi", "bye", "greetings"}<br />
if table.contains(words, "greetings") then<br />
table.remove(words, table.index_of(words, "greetings"))<br />
end<br />
</syntaxhighlight><br />
<br />
==table.is_empty==<br />
; table.is_empty(table)<br />
: Check if a table is devoid of any values.<br />
<br />
; Parameters<br />
* '''table:'''<br />
: The table you are checking for values.<br />
<br />
==table.keys==<br />
; table.keys(table)<br />
: return a table that is the collection of the keys in use by the table passed in<br />
<br />
; Parameters<br />
* '''table:'''<br />
: The table you are collecting keys from.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local testTable = {<br />
name = "thing",<br />
type = "test",<br />
malfunction = "major"<br />
}<br />
local keys = table.keys(testTable)<br />
-- key is now a table { "name", "type", "malfunction" } but the order cannot be guaranteed<br />
-- as pairs() does not iterate in a guaranteed order. If you want the keys in alphabetical<br />
-- run table.sort(keys) and keys == { "malfunction", "name", "type" }<br />
</syntaxhighlight><br />
<br />
==table.load==<br />
; table.load(location, table)<br />
: Load a table from an external file into mudlet.<br />
: See also: [[Manual:Lua_Functions#table.save|table.save]]<br />
<br />
Tip: you can load a table from anywhere on your computer, but it's preferable to have them consolidated somewhere connected to Mudlet, such as the [[Manual:Lua_Functions#getMudletHomeDir|current profile]].<br />
<br />
; Parameters:<br />
* '''location:'''<br />
: Where you are loading the table from. Can be anywhere on your computer.<br />
* '''table:'''<br />
: The table that you are loading into - it must exist already.<br />
<br />
: Example:<br />
<syntaxhighlight lang="lua"><br />
-- This will load the table mytable from the lua file mytable present in your Mudlet Home Directory.<br />
mytable = mytable or {}<br />
if io.exists(getMudletHomeDir().."/mytable.lua") then<br />
table.load(getMudletHomeDir().."/mytable.lua", mytable) -- using / is OK on Windows too.<br />
end<br />
</syntaxhighlight><br />
<br />
==table.matches==<br />
;table.matches(tbl, pattern, [pattern2], [pattern_n], [check_keys])<br />
:Returns a table of key-value pairs from tbl which match one of the supplied patterns when checked via string.match. This function is not recursive - nested tables within tbl will not be checked, only the top-level.<br />
<br />
; Parameters<br />
* ''tbl:''<br />
: the table you want to check over using string.match<br />
* ''pattern:''<br />
: the pattern you want to use to check each key-value pair. You may specify multiple patterns, separated by commas<br />
* ''check_keys:''<br />
: boolean argument, set to true if you want to include a key-value pair if the key or value string.matches. If you do not set this, only the value will be checked<br />
<br />
{{MudletVersion|4.8}}<br />
; Example<br />
<syntaxhighlight lang="lua"><br />
local items = { this = "that", hp = 400, [4] = "toast", something = "else", more = "keypairs" }<br />
local matches = table.matches(items, "%d")<br />
-- here matches will be { hp = 400 }<br />
local matches = table.matches(items, "%d", "that", true)<br />
-- here matches will be { hp = 400, this = "that", [4] = "toast" }<br />
</syntaxhighlight><br />
<br />
==table.maxn==<br />
;table.maxn(table)<br />
:Returns the largest positive numerical index of the given table, or zero if the table has no positive numerical indices. (To do its job this function does a linear traversal of the whole table.)<br />
<br />
==table.n_collect==<br />
; table.n_collect(tbl, func(value))<br />
: returns a table which contains every unique value from tbl for which func(value) returns true. Ignores keys. Table returned is ipairs iterable.<br />
<br />
; Parameters<br />
* ''tbl:''<br />
: the table you want to collect values from<br />
* ''func(value):''<br />
: the function to check each value against<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
; Example<br />
<syntaxhighlight lang="lua"><br />
local items = { <br />
this = "that",<br />
other = "thing",<br />
otter = "potato",<br />
honey = "bee"<br />
}<br />
local beginsWithTH = function(value)<br />
if string.match(value, "^th") then return true end<br />
end<br />
local nmatches = table.n_collect(items, beginsWithTH)<br />
-- nmatches will be { "that", "thing" }<br />
-- the order will not necessarily be preserved<br />
</syntaxhighlight><br />
<br />
==table.n_filter==<br />
; table.n_filter(table, function(element[, index[, table]]))<br />
: Returns a new table with all elements that pass the test implemented by the provided function. If no elements pass the test, an empty table will be returned.<br />
<br />
; Parameters<br />
* ''table:'' the table you wish to filter values out of.<br />
* ''function:'' the function to test each element of the array. Return true to keep the element, false otherwise. It accepts three arguments:<br />
** ''element:'' The current element being processed in the table.<br />
** ''index:'' (optional) The index of the current element being processed in the table.<br />
** ''table:'' (optional) The table '''n_filter''' was called upon.<br />
<br />
; Examples:<br />
Filter out small values:<br />
<syntaxhighlight lang="lua"><br />
local function isBigEnough(value) return value >= 10 end<br />
local filtered = table.n_filter({12, 5, 8, 130, 44}, isBigEnough)<br />
-- filtered: {12, 130, 44}<br />
</syntaxhighlight><br />
Filter out invalid entries:<br />
<syntaxhighlight lang="lua"><br />
local invalidEntries = 0<br />
local entries = {<br />
{ id = 15 }, { id = -1 }, { id = 0 }, { id = 3 },<br />
{ id = 12.2 }, { }, { id = nil }, { id = false },<br />
{ id = 'not a number' }<br />
}<br />
<br />
local function isNumber(t) return t and type(t) == 'number' end<br />
local function filterByID(item)<br />
if isNumber(item.id) and item.id ~= 0 then<br />
return true<br />
end<br />
invalidEntries = invalidEntries + 1<br />
return false<br />
end<br />
<br />
local entriesByID = table.n_filter(entries, filterByID)<br />
-- invalidEntries: 5<br />
-- entriesByID: { { id = 15 }, { id = -1 }, { id = 3 }, { id = 12.2 } }<br />
</syntaxhighlight><br />
Filter out content based on search criteria:<br />
<syntaxhighlight lang="lua"><br />
local fruits = {'apple', 'banana', 'grapes', 'mango', 'orange'}<br />
local function filterItems(t, query)<br />
return table.n_filter(t, function(item)<br />
return item:lower():find(query:lower())<br />
end)<br />
end<br />
filterItems(fruits, 'ap') -- {'apple', 'grapes'}<br />
filterItems(fruits, 'an') -- {'banana', 'mango', 'orange'}<br />
</syntaxhighlight><br />
<br />
==table.n_flatten==<br />
; table.n_flatten(table)<br />
: Returns a new table with the sub-table elements concatenated into it.<br />
<br />
; Parameters<br />
* ''table:'' A table of nested sub-tables you wish to flatten.<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
local t1 = {1, 2, {3, 4}};<br />
local t2 = {1, 2, {3, 4, {5, 6}}};<br />
local t3 = {1, 2, {3, 4, {5, 6, {7, 8, {9, 10}}}}};<br />
table.n_flatten(t1) -- {1, 2, 3, 4}<br />
table.n_flatten(t2) -- {1, 2, 3, 4, 5, 6}<br />
table.n_flatten(t3) -- {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}<br />
</syntaxhighlight><br />
<br />
==table.n_matches==<br />
; table.n_matches(tbl, pattern, [pattern2], [patternN])<br />
: Returns a table of unique values within tbl which one of the supplied patterns matches using string.match<br />
<br />
; Parameters<br />
* ''tbl:''<br />
: The table you want to search for values<br />
* ''pattern:''<br />
: The pattern you want to check each value with, using string.match. You can supply multiple patterns, separated by commas<br />
{{MudletVersion|4.8}}<br />
<br />
; Example<br />
<syntaxhighlight lang="lua"><br />
local items = { this = "that", [4] = "other", hp = 500, mana = 40 }<br />
local matches = table.n_matches(items, "%a")<br />
-- matches will be { "that", "other" }<br />
-- order is not preserved/guaranteed<br />
</syntaxhighlight><br />
<br />
==table.n_union==<br />
; table.n_union (table1, table2)<br />
: Returns a numerically indexed table that is the union of the provided tables (that is - merges two indexed lists together). This is a union of unique values. The order and keys of the input tables are not preserved.<br />
<br />
; Parameters<br />
* ''table1:'' the first table as an indexed list.<br />
* ''table2:'' the second table as an indexed list.<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
display(table.n_union({"bob", "mary"}, {"august", "justinian"}))<br />
<br />
{<br />
"bob",<br />
"mary",<br />
"august",<br />
"justinian"<br />
}<br />
</syntaxhighlight><br />
<br />
==table.n_complement==<br />
; table.n_complement (set1, set2)<br />
: Returns a table that is the relative complement of the first numerically indexed table with respect to the second numerically indexed table. Returns a numerically indexed complement of values.<br />
<br />
; Parameters<br />
* ''table1:''<br />
* ''table2:''<br />
<br />
; Example:<br />
<syntaxhighlight lang=lua>local t1 = {1,2,3,4,5,6}<br />
local t2 = {2,4,6}<br />
local comp = table.n_complement(t1,t2)<br />
display(comp)</syntaxhighlight><br />
This prints the following:<br />
1,<br />
3,<br />
5<br />
<br />
; Returns<br />
: A table containing all the values from table1 that do not match the values from table2.<br />
<br />
==table.n_intersection==<br />
; table.n_intersection (...)<br />
: Returns a numerically indexed table that is the intersection of the provided tables. This is an intersection of unique values. The order and keys of the input tables are not preserved<br />
<br />
; Example:<br />
<syntaxhighlight lang=lua>local t1 = {1,2,3,4,5,6}<br />
local t2 = {2,4,6}<br />
local intersect = table.n_intersection(t1,t2)<br />
display(intersect)</syntaxhighlight><br />
This prints the following:<br />
2,<br />
4,<br />
6<br />
<br />
; Returns<br />
: A table containing the values that are found in every one of the tables.<br />
<br />
==table.pickle==<br />
;table.pickle( t, file, tables, lookup )<br />
: Internal function used by table.save() for serializing data.<br />
<br />
==table.remove==<br />
; table.remove(table, value_position)<br />
: Remove a value from an indexed table, by the values position in the table.<br />
: See also: [[Manual:Lua_Functions#table.insert|table.insert]]<br />
<br />
; Parameters:<br />
* '''table'''<br />
: The indexed table you are removing the value from.<br />
* '''value_position'''<br />
: The indexed number for the value you are removing.<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
testTable = { "hi", "bye", "cry", "why" }<br />
table.remove(testTable, 1) -- will remove hi from the table<br />
-- new testTable after the remove<br />
testTable = { "bye", "cry", "why" }<br />
-- original position of hi was 1, after the remove, position 1 has become bye<br />
-- any values under the removed value are moved up, 5 becomes 4, 4 becomes 3, etc<br />
</syntaxhighlight> <br />
{{note}} To remove a value from a key-value table, it's best to simply change the value to nil.<br />
<syntaxhighlight lang="lua"><br />
testTable = { test = "testing", go = "boom", frown = "glow" }<br />
table.remove(testTable, test) -- this will error<br />
testTable.test = nil -- won't error<br />
testTable["test"] = nil -- won't error<br />
</syntaxhighlight><br />
<br />
==table.save==<br />
; table.save(location, table)<br />
: Save a table into an external file in '''location'''.<br />
: See also: [[Manual:Lua_Functions#table.load|table.load]]<br />
<br />
; Parameters:<br />
* '''location:'''<br />
: Where you want the table file to be saved. Can be anywhere on your computer.<br />
* '''table:'''<br />
: The table that you are saving to the file.<br />
<br />
: Example:<br />
<syntaxhighlight lang="lua"><br />
-- Saves the table mytable to the lua file mytable in your Mudlet Home Directory<br />
table.save(getMudletHomeDir().."/mytable.lua", mytable)<br />
</syntaxhighlight><br />
==table.sort==<br />
;table.sort(Table [, comp])<br />
:Sorts table elements in a given order, in-place, from <code>Table[1]</code> to <code>Table[n]</code>, where <code>n</code> is the length of the table. <br />
<br />
:If <code>comp</code> is given, then it must be a function that receives two table elements, and returns true when the first is less than the second (so that not <code>comp(a[i+1],a[i])</code> will be true after the sort). If <code>comp</code> is not given, then the standard Lua operator <code><</code> is used instead.<br />
<br />
:The sort algorithm is not stable; that is, elements considered equal by the given order may have their relative positions changed by the sort.<br />
<br />
:See https://www.lua.org/pil/19.3.html for more info<br />
<br />
==table.size==<br />
; table.size (t)<br />
: Returns the size of a key-value table (this function has to iterate through all of the table to count all elements).<br />
: Returns a number.<br />
<br />
; Parameters<br />
* ''t:'' <br />
: The table you are checking the size of.<br />
{{note}}<br />
For index based tables you can get the size with the # operator:<br />
This is the standard Lua way of getting the size of index tables i.e. ipairs() type of tables with numerical indices. <br />
To get the size of tables that use user defined keys instead of automatic indices (pairs() type) you need to use the function table.size() referenced above.<br />
<syntaxhighlight lang="lua"><br />
local test_table = { "value1", "value2", "value3", "value4" }<br />
myTableSize = #test_table<br />
-- This would return 4.<br />
local myTable = { 1 = "hello", "key2" = "bye", "key3" = "time to go" }<br />
table.size(myTable)<br />
-- This would return 3.<br />
</syntaxhighlight><br />
<br />
==table.unpickle==<br />
;table.unpickle( t, tables, tcopy, pickled )<br />
: Internal function used by table.load() for deserialization.<br />
<br />
==table.update==<br />
;table.update(table1, table2)<br />
: Returns a table in which key/value pairs from table2 are added to table1, and any keys present in both tables are assigned the value from table2, so that the resulting table is table1 updated with information from table2.<br />
<br />
;Example<br />
<syntaxhighlight lang=lua>display(table.update({a = 1, b = 2, c = 3}, {b = 4, d = 5}))<br />
{<br />
a = 1,<br />
b = 4,<br />
c = 3,<br />
d = 5<br />
}<br />
<br />
-- to just set a table to new values, assign it directly:<br />
mytable = {key1 = "newvalue"}<br />
</syntaxhighlight><br />
<br />
==table.union==<br />
;table.union(...)<br />
: Returns a table that is the union of the provided tables. This is a union of key/value pairs. If two or more tables contain different values associated with the same key, that key in the returned table will contain a subtable containing all relevant values. See table.n_union() for a union of values. Note that the resulting table may not be reliably traversable with ipairs() due to the fact that it preserves keys. If there is a gap in numerical indices, ipairs() will cease traversal.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
tableA = {<br />
[1] = 123,<br />
[2] = 456,<br />
["test"] = "test",<br />
}<br />
---<br />
tableB = {<br />
[1] = 23,<br />
[3] = 7,<br />
["test2"] = function() return true end,<br />
}<br />
---<br />
tableC = {<br />
[5] = "c",<br />
}<br />
---<br />
table.union(tableA, tableB, tableC)<br />
-- will return the following:<br />
{<br />
[1] = {<br />
123,<br />
23,<br />
},<br />
[2] = 456,<br />
[3] = 7,<br />
[5] = "c",<br />
["test"] = "test",<br />
["test2"] = function() return true end,<br />
}<br />
</syntaxhighlight><br />
<br />
[[Category:Mudlet Manual]]<br />
[[Category:Mudlet API]]</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:Table_Functions&diff=20395Manual:Table Functions2023-04-01T21:23:13Z<p>Demonnic: /* table.contains */</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Mudlet API documentation for functions 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.}}<br />
= Table Functions =<br />
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.<br />
<br />
==spairs==<br />
; spairs(tbl, sortFunction)<br />
: Returns an iterator similar to pairs(tbl) but sorts the keys before iterating through them. <br />
<br />
; Parameters<br />
* ''tbl:''<br />
: The table to iterate over<br />
* ''sortFunction:''<br />
: The function to use for determining what order to iterate the items in the table. Defaults to alphanumeric sorting by key. Similar to [[Manual:Lua_Functions#table.sort|table.sort]]. See example for more info.<br />
<br />
{{MudletVersion|4.10}}<br />
; Example:<br />
<syntaxhighlight lang=lua><br />
local tbl = { Tom = 40, Mary = 50, Joe = 23 }<br />
<br />
-- This iterates, sorting based on the key (which is the name in this case)<br />
for name, thingies in spairs(tbl) do<br />
echo(string.format("%s has %d thingies\n", name, thingies))<br />
end<br />
--[[<br />
Joe has 23 thingies<br />
Mary has 50 thingies<br />
Tom has 40 thingies<br />
--]]<br />
<br />
-- The function used below sorts based on the value. <br />
for name, thingies in spairs(tbl, function(t,a,b) return t[a] < t[b] end) do --iterate from lowest value to highest<br />
echo(string.format("%s has %d thingies\n", name, thingies))<br />
end<br />
--[[<br />
Joe has 23 thingies<br />
Tom has 40 thingies<br />
Mary has 50 thingies<br />
--]]<br />
<br />
-- This function can be used to sort a group of Geyser gauges based on their value (what percentage of the gauge is filled)<br />
local gaugeSort = function(t,a,b)<br />
local avalue = t[a].value or 100 -- treat non-gauges as though they are full gauges. If you know for -sure- the table only has gauges the 'or 100' is not needed.<br />
local bvalue = t[b].value or 100<br />
return avalue < bvalue<br />
end<br />
for _,gauge in spairs(tblOfGauges, gaugeSort) do<br />
-- do what you want with the gauges. First one will be the least full, then the next least full, until the last which will be the most full. <br />
-- If you replace the < with a > it will go from most full to least full instead.<br />
end<br />
</syntaxhighlight><br />
<br />
==table.collect==<br />
; table.collect(tbl, func)<br />
: Returns a table that is every key-value pair from tbl for which func(key,value) returns true<br />
<br />
; Parameters<br />
* ''tbl:''<br />
: The table to collect items from<br />
* ''func:''<br />
: the function to use for testing if an item should be collected or not<br />
<br />
{{MudletVersion|4.8}}<br />
; Example:<br />
<syntaxhighlight lang=lua><br />
local vitals = { hp = 3482, maxhp = 5000, mana = 3785, maxmana = 5000 }<br />
local pullHpKeys = function(key, value)<br />
if string.match(key, "hp") then return true end<br />
end<br />
local hp_values = table.collect(vitals, pullHpKeys)<br />
display(hp_values)<br />
</syntaxhighlight><br />
This prints the following:<br />
{<br />
hp = 3482,<br />
maxhp = 5000<br />
}<br />
; Returns<br />
: A table containing all the key/value pairs from tbl that cause func(key,value) to return true<br />
<br />
==table.complement==<br />
; table.complement (set1, set2)<br />
: Returns a table that is the relative complement of the first table with respect to the second table. Returns a complement of key/value pairs.<br />
<br />
; Parameters<br />
* ''table1:''<br />
* ''table2:''<br />
<br />
; Example:<br />
<syntaxhighlight lang=lua>local t1 = {key = 1,1,2,3}<br />
local t2 = {key = 2,1,1,1}<br />
local comp = table.complement(t1,t2)<br />
display(comp)</syntaxhighlight><br />
This prints the following:<br />
key = 1,<br />
[2] = 2,<br />
[3] = 3<br />
<br />
; Returns<br />
: A table containing all the key/value pairs from table1 that do not match the key/value pairs from table2.<br />
<br />
==table.concat==<br />
;table.concat(table, delimiter, startingindex, endingindex)<br />
: Joins a table into a string. Each item must be something which can be transformed into a string. <br />
: Returns the joined string.<br />
: See also: [[Manual:Lua_Functions#string.split|string.split]]<br />
<br />
; Parameters<br />
* '''table:'''<br />
: The table to concatenate into a string. Passed as a table.<br />
* '''delimiter:'''<br />
: Optional string to use to separate each element in the joined string. Passed as a string.<br />
* '''startingindex:'''<br />
: Optional parameter to specify which index to begin the joining at. Passed as an integer.<br />
* '''endingindex:'''<br />
: Optional parameter to specify the last index to join. Passed as an integer.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
--This shows a basic concat with none of the optional arguments<br />
testTable = {1,2,"hi","blah",}<br />
testString = table.concat(testTable)<br />
--testString would be equal to "12hiblah"<br />
<br />
--This example shows the concat using the optional delimiter<br />
testString = table.concat(testTable, ", ")<br />
--testString would be equal to "1, 2, hi, blah"<br />
<br />
--This example shows the concat using the delimiter and the optional starting index<br />
testString = table.concat(testTable, ", ", 2)<br />
--testString would be equal to "2, hi, blah"<br />
<br />
--And finally, one which uses all of the arguments<br />
testString = table.concat(testTable, ", ", 2, 3)<br />
--testString would be equal to "2, hi"<br />
</syntaxhighlight><br />
<br />
==table.contains==<br />
; table.contains (t, value)<br />
: Determines if a table contains a value as a key or as a value (recursive as of Mudlet 4.8+).<br />
: Returns true or false<br />
: See also: [[Manual:Lua_Functions#table.index_of|table.index_of]]<br />
<br />
; Parameters<br />
* '''t:''' <br />
: The table in which you are checking for the presence of the item as key or value..<br />
* '''value:''' <br />
: The value you are checking for within the table.<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua">local test_table = {"value1", "value2", "value3", "value4", "value5", "value6", "value7"}<br />
if table.contains(test_table, "value1") then <br />
print("Got value 1!")<br />
else<br />
print("Don't have it. Sorry!")<br />
end<br />
<br />
-- if the table has just a few values, you can skip making a local, named table:<br />
if table.contains({"Anna", "Alanna", "Hanna"}, "Anna") then <br />
print("Have 'Anna' in the list!")<br />
else<br />
print("Don't have the name. Sorry!")<br />
end<br />
<br />
-- don't forget, it will return true if the item is a key in the table as well<br />
display(table.contains({"bob"}, 1) -- displays true, as 1 is the key/index for "bob"<br />
-- If you really only want to check values, try table.index_of, which returns the key a value is found at, or nil if it is not found.<br />
</syntaxhighlight><br />
<br />
==table.deepcopy==<br />
; table.deepcopy (table)<br />
: Returns a complete copy of the table.<br />
<br />
; Parameters<br />
* '''table:''' <br />
: The table which you'd like to get a copy of.<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua">local test_table = { "value1", "value2", "value3", "value4" }<br />
<br />
-- by just doing:<br />
local newtable = test_table<br />
-- you're linking newtable to test_table. Any change in test_table will be reflected in newtable.<br />
<br />
-- however, by doing:<br />
local newtable = table.deepcopy(test_table)<br />
-- the two tables are completely separate now.<br />
</syntaxhighlight><br />
<br />
==table.intersection==<br />
; table.intersection (set1, set2)<br />
: Returns a table that is the relative intersection of the first table with respect to the second table. Returns a intersection of key/value pairs.<br />
<br />
; Parameters<br />
* ''table1:''<br />
* ''table2:''<br />
<br />
; Example:<br />
<syntaxhighlight lang=lua>local t1 = {key = 1,1,2,3}<br />
local t2 = {key = 1,1,1,1}<br />
local intersect = table.intersection(t1,t2)<br />
display(intersect)</syntaxhighlight><br />
This prints the following:<br />
key = 1,<br />
1<br />
<br />
; Returns<br />
: A table containing all the key/value pairs from table1 that match the key/value pairs from table2.<br />
<br />
==table.insert==<br />
; table.insert(table, [pos,] value)<br />
: Inserts element '''value''' at position '''pos''' in '''table''', shifting up other elements to open space, if necessary. The default '''value''' for '''pos''' is n+1, where n is the length of the table, so that a call table.insert(t,x) inserts x at the end of table t.<br />
: See also: [[Manual:Lua_Functions#table.remove|table.remove]]<br />
<br />
; Parameters<br />
* '''table:'''<br />
: The table in which you are inserting the value<br />
* '''pos:'''<br />
: Optional argument, determining where the value will be inserted. <br />
* '''value:'''<br />
: The variable that you are inserting into the table. Can be a regular variable, or even a table or function*.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
--it will inserts what inside the variable of matches[2] into at the end of table of 'test_db_name'. <br />
table.insert(test_db_name, matches[2])<br />
--it will inserts other thing at the first position of this table.<br />
table.insert(test_db_name, 1, "jgcampbell300")<br />
<br />
--[=[<br />
<br />
This results:<br />
<br />
test_db_name = {<br />
"jgcampbell300",<br />
"SlySven"<br />
}<br />
]=]<br />
<br />
</syntaxhighlight><br />
<br />
==table.index_of==<br />
; table.index_of(table, value)<br />
Returns the index (location) of an item in an indexed table, or '''nil''' if it's not found.<br />
<br />
; Parameters<br />
* '''table:'''<br />
: The table in which you are inserting the value<br />
* '''value:'''<br />
: The variable that you are searching for in the table.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- will return 1, because 'hi' is the first item in the list<br />
table.index_of({"hi", "bye", "greetings"}, "hi")<br />
<br />
-- will return 3, because 'greetings' is third in the list<br />
table.index_of({"hi", "bye", "greetings"}, "greetings")<br />
<br />
-- you can also use this in combination with table.remove(), which requires the location of the item to delete<br />
local words = {"hi", "bye", "greetings"}<br />
table.remove(words, table.index_of(words, "greetings"))<br />
<br />
-- however that won't work if the word isn't present, table.remove(mytable, nil (from table.index_of)) will give an error<br />
-- so if you're unsure, confirm with table.contains first<br />
local words = {"hi", "bye", "greetings"}<br />
if table.contains(words, "greetings") then<br />
table.remove(words, table.index_of(words, "greetings"))<br />
end<br />
</syntaxhighlight><br />
<br />
==table.is_empty==<br />
; table.is_empty(table)<br />
: Check if a table is devoid of any values.<br />
<br />
; Parameters<br />
* '''table:'''<br />
: The table you are checking for values.<br />
<br />
==table.keys==<br />
; table.keys(table)<br />
: return a table that is the collection of the keys in use by the table passed in<br />
<br />
; Parameters<br />
* '''table:'''<br />
: The table you are collecting keys from.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local testTable = {<br />
name = "thing",<br />
type = "test",<br />
malfunction = "major"<br />
}<br />
local keys = table.keys(testTable)<br />
-- key is now a table { "name", "type", "malfunction" } but the order cannot be guaranteed<br />
-- as pairs() does not iterate in a guaranteed order. If you want the keys in alphabetical<br />
-- run table.sort(keys) and keys == { "malfunction", "name", "type" }<br />
</syntaxhighlight><br />
<br />
==table.load==<br />
; table.load(location, table)<br />
: Load a table from an external file into mudlet.<br />
: See also: [[Manual:Lua_Functions#table.save|table.save]]<br />
<br />
Tip: you can load a table from anywhere on your computer, but it's preferable to have them consolidated somewhere connected to Mudlet, such as the [[Manual:Lua_Functions#getMudletHomeDir|current profile]].<br />
<br />
; Parameters:<br />
* '''location:'''<br />
: Where you are loading the table from. Can be anywhere on your computer.<br />
* '''table:'''<br />
: The table that you are loading into - it must exist already.<br />
<br />
: Example:<br />
<syntaxhighlight lang="lua"><br />
-- This will load the table mytable from the lua file mytable present in your Mudlet Home Directory.<br />
mytable = mytable or {}<br />
if io.exists(getMudletHomeDir().."/mytable.lua") then<br />
table.load(getMudletHomeDir().."/mytable.lua", mytable) -- using / is OK on Windows too.<br />
end<br />
</syntaxhighlight><br />
<br />
==table.matches==<br />
;table.matches(tbl, pattern, [pattern2], [pattern_n], [check_keys])<br />
:Returns a table of key-value pairs from tbl which match one of the supplied patterns when checked via string.match. This function is not recursive - nested tables within tbl will not be checked, only the top-level.<br />
<br />
; Parameters<br />
* ''tbl:''<br />
: the table you want to check over using string.match<br />
* ''pattern:''<br />
: the pattern you want to use to check each key-value pair. You may specify multiple patterns, separated by commas<br />
* ''check_keys:''<br />
: boolean argument, set to true if you want to include a key-value pair if the key or value string.matches. If you do not set this, only the value will be checked<br />
<br />
{{MudletVersion|4.8}}<br />
; Example<br />
<syntaxhighlight lang="lua"><br />
local items = { this = "that", hp = 400, [4] = "toast", something = "else", more = "keypairs" }<br />
local matches = table.matches(items, "%d")<br />
-- here matches will be { hp = 400 }<br />
local matches = table.matches(items, "%d", "that", true)<br />
-- here matches will be { hp = 400, this = "that", [4] = "toast" }<br />
</syntaxhighlight><br />
<br />
==table.maxn==<br />
;table.maxn(table)<br />
:Returns the largest positive numerical index of the given table, or zero if the table has no positive numerical indices. (To do its job this function does a linear traversal of the whole table.)<br />
<br />
==table.n_collect==<br />
; table.n_collect(tbl, func(value))<br />
: returns a table which contains every unique value from tbl for which func(value) returns true. Ignores keys. Table returned is ipairs iterable.<br />
<br />
; Parameters<br />
* ''tbl:''<br />
: the table you want to collect values from<br />
* ''func(value):''<br />
: the function to check each value against<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
; Example<br />
<syntaxhighlight lang="lua"><br />
local items = { <br />
this = "that",<br />
other = "thing",<br />
otter = "potato",<br />
honey = "bee"<br />
}<br />
local beginsWithTH = function(value)<br />
if string.match(value, "^th") then return true end<br />
end<br />
local nmatches = table.n_collect(items, beginsWithTH)<br />
-- nmatches will be { "that", "thing" }<br />
-- the order will not necessarily be preserved<br />
</syntaxhighlight><br />
<br />
==table.n_filter==<br />
; table.n_filter(table, function(element[, index[, table]]))<br />
: Returns a new table with all elements that pass the test implemented by the provided function. If no elements pass the test, an empty table will be returned.<br />
<br />
; Parameters<br />
* ''table:'' the table you wish to filter values out of.<br />
* ''function:'' the function to test each element of the array. Return true to keep the element, false otherwise. It accepts three arguments:<br />
** ''element:'' The current element being processed in the table.<br />
** ''index:'' (optional) The index of the current element being processed in the table.<br />
** ''table:'' (optional) The table '''n_filter''' was called upon.<br />
<br />
; Examples:<br />
Filter out small values:<br />
<syntaxhighlight lang="lua"><br />
local function isBigEnough(value) return value >= 10 end<br />
local filtered = table.n_filter({12, 5, 8, 130, 44}, isBigEnough)<br />
-- filtered: {12, 130, 44}<br />
</syntaxhighlight><br />
Filter out invalid entries:<br />
<syntaxhighlight lang="lua"><br />
local invalidEntries = 0<br />
local entries = {<br />
{ id = 15 }, { id = -1 }, { id = 0 }, { id = 3 },<br />
{ id = 12.2 }, { }, { id = nil }, { id = false },<br />
{ id = 'not a number' }<br />
}<br />
<br />
local function isNumber(t) return t and type(t) == 'number' end<br />
local function filterByID(item)<br />
if isNumber(item.id) and item.id ~= 0 then<br />
return true<br />
end<br />
invalidEntries = invalidEntries + 1<br />
return false<br />
end<br />
<br />
local entriesByID = table.n_filter(entries, filterByID)<br />
-- invalidEntries: 5<br />
-- entriesByID: { { id = 15 }, { id = -1 }, { id = 3 }, { id = 12.2 } }<br />
</syntaxhighlight><br />
Filter out content based on search criteria:<br />
<syntaxhighlight lang="lua"><br />
local fruits = {'apple', 'banana', 'grapes', 'mango', 'orange'}<br />
local function filterItems(t, query)<br />
return table.n_filter(t, function(item)<br />
return item:lower():find(query:lower())<br />
end)<br />
end<br />
filterItems(fruits, 'ap') -- {'apple', 'grapes'}<br />
filterItems(fruits, 'an') -- {'banana', 'mango', 'orange'}<br />
</syntaxhighlight><br />
<br />
==table.n_flatten==<br />
; table.n_flatten(table)<br />
: Returns a new table with the sub-table elements concatenated into it.<br />
<br />
; Parameters<br />
* ''table:'' A table of nested sub-tables you wish to flatten.<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
local t1 = {1, 2, {3, 4}};<br />
local t2 = {1, 2, {3, 4, {5, 6}}};<br />
local t3 = {1, 2, {3, 4, {5, 6, {7, 8, {9, 10}}}}};<br />
table.n_flatten(t1) -- {1, 2, 3, 4}<br />
table.n_flatten(t2) -- {1, 2, 3, 4, 5, 6}<br />
table.n_flatten(t3) -- {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}<br />
</syntaxhighlight><br />
<br />
==table.n_matches==<br />
; table.n_matches(tbl, pattern, [pattern2], [patternN])<br />
: Returns a table of unique values within tbl which one of the supplied patterns matches using string.match<br />
<br />
; Parameters<br />
* ''tbl:''<br />
: The table you want to search for values<br />
* ''pattern:''<br />
: The pattern you want to check each value with, using string.match. You can supply multiple patterns, separated by commas<br />
{{MudletVersion|4.8}}<br />
<br />
; Example<br />
<syntaxhighlight lang="lua"><br />
local items = { this = "that", [4] = "other", hp = 500, mana = 40 }<br />
local matches = table.n_matches(items, "%a")<br />
-- matches will be { "that", "other" }<br />
-- order is not preserved/guaranteed<br />
</syntaxhighlight><br />
<br />
==table.n_union==<br />
; table.n_union (table1, table2)<br />
: Returns a numerically indexed table that is the union of the provided tables (that is - merges two indexed lists together). This is a union of unique values. The order and keys of the input tables are not preserved.<br />
<br />
; Parameters<br />
* ''table1:'' the first table as an indexed list.<br />
* ''table2:'' the second table as an indexed list.<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
display(table.n_union({"bob", "mary"}, {"august", "justinian"}))<br />
<br />
{<br />
"bob",<br />
"mary",<br />
"august",<br />
"justinian"<br />
}<br />
</syntaxhighlight><br />
<br />
==table.n_complement==<br />
; table.n_complement (set1, set2)<br />
: Returns a table that is the relative complement of the first numerically indexed table with respect to the second numerically indexed table. Returns a numerically indexed complement of values.<br />
<br />
; Parameters<br />
* ''table1:''<br />
* ''table2:''<br />
<br />
; Example:<br />
<syntaxhighlight lang=lua>local t1 = {1,2,3,4,5,6}<br />
local t2 = {2,4,6}<br />
local comp = table.n_complement(t1,t2)<br />
display(comp)</syntaxhighlight><br />
This prints the following:<br />
1,<br />
3,<br />
5<br />
<br />
; Returns<br />
: A table containing all the values from table1 that do not match the values from table2.<br />
<br />
==table.n_intersection==<br />
; table.n_intersection (...)<br />
: Returns a numerically indexed table that is the intersection of the provided tables. This is an intersection of unique values. The order and keys of the input tables are not preserved<br />
<br />
; Example:<br />
<syntaxhighlight lang=lua>local t1 = {1,2,3,4,5,6}<br />
local t2 = {2,4,6}<br />
local intersect = table.n_intersection(t1,t2)<br />
display(intersect)</syntaxhighlight><br />
This prints the following:<br />
2,<br />
4,<br />
6<br />
<br />
; Returns<br />
: A table containing the values that are found in every one of the tables.<br />
<br />
==table.pickle==<br />
;table.pickle( t, file, tables, lookup )<br />
: Internal function used by table.save() for serializing data.<br />
<br />
==table.remove==<br />
; table.remove(table, value_position)<br />
: Remove a value from an indexed table, by the values position in the table.<br />
: See also: [[Manual:Lua_Functions#table.insert|table.insert]]<br />
<br />
; Parameters:<br />
* '''table'''<br />
: The indexed table you are removing the value from.<br />
* '''value_position'''<br />
: The indexed number for the value you are removing.<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
testTable = { "hi", "bye", "cry", "why" }<br />
table.remove(testTable, 1) -- will remove hi from the table<br />
-- new testTable after the remove<br />
testTable = { "bye", "cry", "why" }<br />
-- original position of hi was 1, after the remove, position 1 has become bye<br />
-- any values under the removed value are moved up, 5 becomes 4, 4 becomes 3, etc<br />
</syntaxhighlight> <br />
{{note}} To remove a value from a key-value table, it's best to simply change the value to nil.<br />
<syntaxhighlight lang="lua"><br />
testTable = { test = "testing", go = "boom", frown = "glow" }<br />
table.remove(testTable, test) -- this will error<br />
testTable.test = nil -- won't error<br />
testTable["test"] = nil -- won't error<br />
</syntaxhighlight><br />
<br />
==table.save==<br />
; table.save(location, table)<br />
: Save a table into an external file in '''location'''.<br />
: See also: [[Manual:Lua_Functions#table.load|table.load]]<br />
<br />
; Parameters:<br />
* '''location:'''<br />
: Where you want the table file to be saved. Can be anywhere on your computer.<br />
* '''table:'''<br />
: The table that you are saving to the file.<br />
<br />
: Example:<br />
<syntaxhighlight lang="lua"><br />
-- Saves the table mytable to the lua file mytable in your Mudlet Home Directory<br />
table.save(getMudletHomeDir().."/mytable.lua", mytable)<br />
</syntaxhighlight><br />
==table.sort==<br />
;table.sort(Table [, comp])<br />
:Sorts table elements in a given order, in-place, from <code>Table[1]</code> to <code>Table[n]</code>, where <code>n</code> is the length of the table. <br />
<br />
:If <code>comp</code> is given, then it must be a function that receives two table elements, and returns true when the first is less than the second (so that not <code>comp(a[i+1],a[i])</code> will be true after the sort). If <code>comp</code> is not given, then the standard Lua operator <code><</code> is used instead.<br />
<br />
:The sort algorithm is not stable; that is, elements considered equal by the given order may have their relative positions changed by the sort.<br />
<br />
:See https://www.lua.org/pil/19.3.html for more info<br />
<br />
==table.size==<br />
; table.size (t)<br />
: Returns the size of a key-value table (this function has to iterate through all of the table to count all elements).<br />
: Returns a number.<br />
<br />
; Parameters<br />
* ''t:'' <br />
: The table you are checking the size of.<br />
{{note}}<br />
For index based tables you can get the size with the # operator:<br />
This is the standard Lua way of getting the size of index tables i.e. ipairs() type of tables with numerical indices. <br />
To get the size of tables that use user defined keys instead of automatic indices (pairs() type) you need to use the function table.size() referenced above.<br />
<syntaxhighlight lang="lua"><br />
local test_table = { "value1", "value2", "value3", "value4" }<br />
myTableSize = #test_table<br />
-- This would return 4.<br />
local myTable = { 1 = "hello", "key2" = "bye", "key3" = "time to go" }<br />
table.size(myTable)<br />
-- This would return 3.<br />
</syntaxhighlight><br />
<br />
==table.unpickle==<br />
;table.unpickle( t, tables, tcopy, pickled )<br />
: Internal function used by table.load() for deserialization.<br />
<br />
==table.update==<br />
;table.update(table1, table2)<br />
: Returns a table in which key/value pairs from table2 are added to table1, and any keys present in both tables are assigned the value from table2, so that the resulting table is table1 updated with information from table2.<br />
<br />
;Example<br />
<syntaxhighlight lang=lua>display(table.update({a = 1, b = 2, c = 3}, {b = 4, d = 5}))<br />
{<br />
a = 1,<br />
b = 4,<br />
c = 3,<br />
d = 5<br />
}<br />
<br />
-- to just set a table to new values, assign it directly:<br />
mytable = {key1 = "newvalue"}<br />
</syntaxhighlight><br />
<br />
==table.union==<br />
;table.union(...)<br />
: Returns a table that is the union of the provided tables. This is a union of key/value pairs. If two or more tables contain different values associated with the same key, that key in the returned table will contain a subtable containing all relevant values. See table.n_union() for a union of values. Note that the resulting table may not be reliably traversable with ipairs() due to the fact that it preserves keys. If there is a gap in numerical indices, ipairs() will cease traversal.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
tableA = {<br />
[1] = 123,<br />
[2] = 456,<br />
["test"] = "test",<br />
}<br />
---<br />
tableB = {<br />
[1] = 23,<br />
[3] = 7,<br />
["test2"] = function() return true end,<br />
}<br />
---<br />
tableC = {<br />
[5] = "c",<br />
}<br />
---<br />
table.union(tableA, tableB, tableC)<br />
-- will return the following:<br />
{<br />
[1] = {<br />
123,<br />
23,<br />
},<br />
[2] = 456,<br />
[3] = 7,<br />
[5] = "c",<br />
["test"] = "test",<br />
["test2"] = function() return true end,<br />
}<br />
</syntaxhighlight><br />
<br />
[[Category:Mudlet Manual]]<br />
[[Category:Mudlet API]]</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:Table_Functions&diff=20394Manual:Table Functions2023-04-01T21:21:43Z<p>Demonnic: /* table.contains */</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Mudlet API documentation for functions 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.}}<br />
= Table Functions =<br />
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.<br />
<br />
==spairs==<br />
; spairs(tbl, sortFunction)<br />
: Returns an iterator similar to pairs(tbl) but sorts the keys before iterating through them. <br />
<br />
; Parameters<br />
* ''tbl:''<br />
: The table to iterate over<br />
* ''sortFunction:''<br />
: The function to use for determining what order to iterate the items in the table. Defaults to alphanumeric sorting by key. Similar to [[Manual:Lua_Functions#table.sort|table.sort]]. See example for more info.<br />
<br />
{{MudletVersion|4.10}}<br />
; Example:<br />
<syntaxhighlight lang=lua><br />
local tbl = { Tom = 40, Mary = 50, Joe = 23 }<br />
<br />
-- This iterates, sorting based on the key (which is the name in this case)<br />
for name, thingies in spairs(tbl) do<br />
echo(string.format("%s has %d thingies\n", name, thingies))<br />
end<br />
--[[<br />
Joe has 23 thingies<br />
Mary has 50 thingies<br />
Tom has 40 thingies<br />
--]]<br />
<br />
-- The function used below sorts based on the value. <br />
for name, thingies in spairs(tbl, function(t,a,b) return t[a] < t[b] end) do --iterate from lowest value to highest<br />
echo(string.format("%s has %d thingies\n", name, thingies))<br />
end<br />
--[[<br />
Joe has 23 thingies<br />
Tom has 40 thingies<br />
Mary has 50 thingies<br />
--]]<br />
<br />
-- This function can be used to sort a group of Geyser gauges based on their value (what percentage of the gauge is filled)<br />
local gaugeSort = function(t,a,b)<br />
local avalue = t[a].value or 100 -- treat non-gauges as though they are full gauges. If you know for -sure- the table only has gauges the 'or 100' is not needed.<br />
local bvalue = t[b].value or 100<br />
return avalue < bvalue<br />
end<br />
for _,gauge in spairs(tblOfGauges, gaugeSort) do<br />
-- do what you want with the gauges. First one will be the least full, then the next least full, until the last which will be the most full. <br />
-- If you replace the < with a > it will go from most full to least full instead.<br />
end<br />
</syntaxhighlight><br />
<br />
==table.collect==<br />
; table.collect(tbl, func)<br />
: Returns a table that is every key-value pair from tbl for which func(key,value) returns true<br />
<br />
; Parameters<br />
* ''tbl:''<br />
: The table to collect items from<br />
* ''func:''<br />
: the function to use for testing if an item should be collected or not<br />
<br />
{{MudletVersion|4.8}}<br />
; Example:<br />
<syntaxhighlight lang=lua><br />
local vitals = { hp = 3482, maxhp = 5000, mana = 3785, maxmana = 5000 }<br />
local pullHpKeys = function(key, value)<br />
if string.match(key, "hp") then return true end<br />
end<br />
local hp_values = table.collect(vitals, pullHpKeys)<br />
display(hp_values)<br />
</syntaxhighlight><br />
This prints the following:<br />
{<br />
hp = 3482,<br />
maxhp = 5000<br />
}<br />
; Returns<br />
: A table containing all the key/value pairs from tbl that cause func(key,value) to return true<br />
<br />
==table.complement==<br />
; table.complement (set1, set2)<br />
: Returns a table that is the relative complement of the first table with respect to the second table. Returns a complement of key/value pairs.<br />
<br />
; Parameters<br />
* ''table1:''<br />
* ''table2:''<br />
<br />
; Example:<br />
<syntaxhighlight lang=lua>local t1 = {key = 1,1,2,3}<br />
local t2 = {key = 2,1,1,1}<br />
local comp = table.complement(t1,t2)<br />
display(comp)</syntaxhighlight><br />
This prints the following:<br />
key = 1,<br />
[2] = 2,<br />
[3] = 3<br />
<br />
; Returns<br />
: A table containing all the key/value pairs from table1 that do not match the key/value pairs from table2.<br />
<br />
==table.concat==<br />
;table.concat(table, delimiter, startingindex, endingindex)<br />
: Joins a table into a string. Each item must be something which can be transformed into a string. <br />
: Returns the joined string.<br />
: See also: [[Manual:Lua_Functions#string.split|string.split]]<br />
<br />
; Parameters<br />
* '''table:'''<br />
: The table to concatenate into a string. Passed as a table.<br />
* '''delimiter:'''<br />
: Optional string to use to separate each element in the joined string. Passed as a string.<br />
* '''startingindex:'''<br />
: Optional parameter to specify which index to begin the joining at. Passed as an integer.<br />
* '''endingindex:'''<br />
: Optional parameter to specify the last index to join. Passed as an integer.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
--This shows a basic concat with none of the optional arguments<br />
testTable = {1,2,"hi","blah",}<br />
testString = table.concat(testTable)<br />
--testString would be equal to "12hiblah"<br />
<br />
--This example shows the concat using the optional delimiter<br />
testString = table.concat(testTable, ", ")<br />
--testString would be equal to "1, 2, hi, blah"<br />
<br />
--This example shows the concat using the delimiter and the optional starting index<br />
testString = table.concat(testTable, ", ", 2)<br />
--testString would be equal to "2, hi, blah"<br />
<br />
--And finally, one which uses all of the arguments<br />
testString = table.concat(testTable, ", ", 2, 3)<br />
--testString would be equal to "2, hi"<br />
</syntaxhighlight><br />
<br />
==table.contains==<br />
; table.contains (t, value)<br />
: Determines if a table contains a value as a key or as a value (recursive as of Mudlet 4.8+).<br />
: Returns true or false<br />
<br />
; Parameters<br />
* '''t:''' <br />
: The table in which you are checking for the presence of the item as key or value..<br />
* '''value:''' <br />
: The value you are checking for within the table.<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua">local test_table = {"value1", "value2", "value3", "value4", "value5", "value6", "value7"}<br />
if table.contains(test_table, "value1") then <br />
print("Got value 1!")<br />
else<br />
print("Don't have it. Sorry!")<br />
end<br />
<br />
-- if the table has just a few values, you can skip making a local, named table:<br />
if table.contains({"Anna", "Alanna", "Hanna"}, "Anna") then <br />
print("Have 'Anna' in the list!")<br />
else<br />
print("Don't have the name. Sorry!")<br />
end<br />
<br />
-- don't forget, it will return true if the item is a key in the table as well<br />
display(table.contains({"bob"}, 1) -- displays true, as 1 is the key/index for "bob"<br />
-- If you really only want to check values, try table.index_of, which returns the key a value is found at, or nil if it is not found.<br />
</syntaxhighlight><br />
<br />
==table.deepcopy==<br />
; table.deepcopy (table)<br />
: Returns a complete copy of the table.<br />
<br />
; Parameters<br />
* '''table:''' <br />
: The table which you'd like to get a copy of.<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua">local test_table = { "value1", "value2", "value3", "value4" }<br />
<br />
-- by just doing:<br />
local newtable = test_table<br />
-- you're linking newtable to test_table. Any change in test_table will be reflected in newtable.<br />
<br />
-- however, by doing:<br />
local newtable = table.deepcopy(test_table)<br />
-- the two tables are completely separate now.<br />
</syntaxhighlight><br />
<br />
==table.intersection==<br />
; table.intersection (set1, set2)<br />
: Returns a table that is the relative intersection of the first table with respect to the second table. Returns a intersection of key/value pairs.<br />
<br />
; Parameters<br />
* ''table1:''<br />
* ''table2:''<br />
<br />
; Example:<br />
<syntaxhighlight lang=lua>local t1 = {key = 1,1,2,3}<br />
local t2 = {key = 1,1,1,1}<br />
local intersect = table.intersection(t1,t2)<br />
display(intersect)</syntaxhighlight><br />
This prints the following:<br />
key = 1,<br />
1<br />
<br />
; Returns<br />
: A table containing all the key/value pairs from table1 that match the key/value pairs from table2.<br />
<br />
==table.insert==<br />
; table.insert(table, [pos,] value)<br />
: Inserts element '''value''' at position '''pos''' in '''table''', shifting up other elements to open space, if necessary. The default '''value''' for '''pos''' is n+1, where n is the length of the table, so that a call table.insert(t,x) inserts x at the end of table t.<br />
: See also: [[Manual:Lua_Functions#table.remove|table.remove]]<br />
<br />
; Parameters<br />
* '''table:'''<br />
: The table in which you are inserting the value<br />
* '''pos:'''<br />
: Optional argument, determining where the value will be inserted. <br />
* '''value:'''<br />
: The variable that you are inserting into the table. Can be a regular variable, or even a table or function*.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
--it will inserts what inside the variable of matches[2] into at the end of table of 'test_db_name'. <br />
table.insert(test_db_name, matches[2])<br />
--it will inserts other thing at the first position of this table.<br />
table.insert(test_db_name, 1, "jgcampbell300")<br />
<br />
--[=[<br />
<br />
This results:<br />
<br />
test_db_name = {<br />
"jgcampbell300",<br />
"SlySven"<br />
}<br />
]=]<br />
<br />
</syntaxhighlight><br />
<br />
==table.index_of==<br />
; table.index_of(table, value)<br />
Returns the index (location) of an item in an indexed table, or '''nil''' if it's not found.<br />
<br />
; Parameters<br />
* '''table:'''<br />
: The table in which you are inserting the value<br />
* '''value:'''<br />
: The variable that you are searching for in the table.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- will return 1, because 'hi' is the first item in the list<br />
table.index_of({"hi", "bye", "greetings"}, "hi")<br />
<br />
-- will return 3, because 'greetings' is third in the list<br />
table.index_of({"hi", "bye", "greetings"}, "greetings")<br />
<br />
-- you can also use this in combination with table.remove(), which requires the location of the item to delete<br />
local words = {"hi", "bye", "greetings"}<br />
table.remove(words, table.index_of(words, "greetings"))<br />
<br />
-- however that won't work if the word isn't present, table.remove(mytable, nil (from table.index_of)) will give an error<br />
-- so if you're unsure, confirm with table.contains first<br />
local words = {"hi", "bye", "greetings"}<br />
if table.contains(words, "greetings") then<br />
table.remove(words, table.index_of(words, "greetings"))<br />
end<br />
</syntaxhighlight><br />
<br />
==table.is_empty==<br />
; table.is_empty(table)<br />
: Check if a table is devoid of any values.<br />
<br />
; Parameters<br />
* '''table:'''<br />
: The table you are checking for values.<br />
<br />
==table.keys==<br />
; table.keys(table)<br />
: return a table that is the collection of the keys in use by the table passed in<br />
<br />
; Parameters<br />
* '''table:'''<br />
: The table you are collecting keys from.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local testTable = {<br />
name = "thing",<br />
type = "test",<br />
malfunction = "major"<br />
}<br />
local keys = table.keys(testTable)<br />
-- key is now a table { "name", "type", "malfunction" } but the order cannot be guaranteed<br />
-- as pairs() does not iterate in a guaranteed order. If you want the keys in alphabetical<br />
-- run table.sort(keys) and keys == { "malfunction", "name", "type" }<br />
</syntaxhighlight><br />
<br />
==table.load==<br />
; table.load(location, table)<br />
: Load a table from an external file into mudlet.<br />
: See also: [[Manual:Lua_Functions#table.save|table.save]]<br />
<br />
Tip: you can load a table from anywhere on your computer, but it's preferable to have them consolidated somewhere connected to Mudlet, such as the [[Manual:Lua_Functions#getMudletHomeDir|current profile]].<br />
<br />
; Parameters:<br />
* '''location:'''<br />
: Where you are loading the table from. Can be anywhere on your computer.<br />
* '''table:'''<br />
: The table that you are loading into - it must exist already.<br />
<br />
: Example:<br />
<syntaxhighlight lang="lua"><br />
-- This will load the table mytable from the lua file mytable present in your Mudlet Home Directory.<br />
mytable = mytable or {}<br />
if io.exists(getMudletHomeDir().."/mytable.lua") then<br />
table.load(getMudletHomeDir().."/mytable.lua", mytable) -- using / is OK on Windows too.<br />
end<br />
</syntaxhighlight><br />
<br />
==table.matches==<br />
;table.matches(tbl, pattern, [pattern2], [pattern_n], [check_keys])<br />
:Returns a table of key-value pairs from tbl which match one of the supplied patterns when checked via string.match. This function is not recursive - nested tables within tbl will not be checked, only the top-level.<br />
<br />
; Parameters<br />
* ''tbl:''<br />
: the table you want to check over using string.match<br />
* ''pattern:''<br />
: the pattern you want to use to check each key-value pair. You may specify multiple patterns, separated by commas<br />
* ''check_keys:''<br />
: boolean argument, set to true if you want to include a key-value pair if the key or value string.matches. If you do not set this, only the value will be checked<br />
<br />
{{MudletVersion|4.8}}<br />
; Example<br />
<syntaxhighlight lang="lua"><br />
local items = { this = "that", hp = 400, [4] = "toast", something = "else", more = "keypairs" }<br />
local matches = table.matches(items, "%d")<br />
-- here matches will be { hp = 400 }<br />
local matches = table.matches(items, "%d", "that", true)<br />
-- here matches will be { hp = 400, this = "that", [4] = "toast" }<br />
</syntaxhighlight><br />
<br />
==table.maxn==<br />
;table.maxn(table)<br />
:Returns the largest positive numerical index of the given table, or zero if the table has no positive numerical indices. (To do its job this function does a linear traversal of the whole table.)<br />
<br />
==table.n_collect==<br />
; table.n_collect(tbl, func(value))<br />
: returns a table which contains every unique value from tbl for which func(value) returns true. Ignores keys. Table returned is ipairs iterable.<br />
<br />
; Parameters<br />
* ''tbl:''<br />
: the table you want to collect values from<br />
* ''func(value):''<br />
: the function to check each value against<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
; Example<br />
<syntaxhighlight lang="lua"><br />
local items = { <br />
this = "that",<br />
other = "thing",<br />
otter = "potato",<br />
honey = "bee"<br />
}<br />
local beginsWithTH = function(value)<br />
if string.match(value, "^th") then return true end<br />
end<br />
local nmatches = table.n_collect(items, beginsWithTH)<br />
-- nmatches will be { "that", "thing" }<br />
-- the order will not necessarily be preserved<br />
</syntaxhighlight><br />
<br />
==table.n_filter==<br />
; table.n_filter(table, function(element[, index[, table]]))<br />
: Returns a new table with all elements that pass the test implemented by the provided function. If no elements pass the test, an empty table will be returned.<br />
<br />
; Parameters<br />
* ''table:'' the table you wish to filter values out of.<br />
* ''function:'' the function to test each element of the array. Return true to keep the element, false otherwise. It accepts three arguments:<br />
** ''element:'' The current element being processed in the table.<br />
** ''index:'' (optional) The index of the current element being processed in the table.<br />
** ''table:'' (optional) The table '''n_filter''' was called upon.<br />
<br />
; Examples:<br />
Filter out small values:<br />
<syntaxhighlight lang="lua"><br />
local function isBigEnough(value) return value >= 10 end<br />
local filtered = table.n_filter({12, 5, 8, 130, 44}, isBigEnough)<br />
-- filtered: {12, 130, 44}<br />
</syntaxhighlight><br />
Filter out invalid entries:<br />
<syntaxhighlight lang="lua"><br />
local invalidEntries = 0<br />
local entries = {<br />
{ id = 15 }, { id = -1 }, { id = 0 }, { id = 3 },<br />
{ id = 12.2 }, { }, { id = nil }, { id = false },<br />
{ id = 'not a number' }<br />
}<br />
<br />
local function isNumber(t) return t and type(t) == 'number' end<br />
local function filterByID(item)<br />
if isNumber(item.id) and item.id ~= 0 then<br />
return true<br />
end<br />
invalidEntries = invalidEntries + 1<br />
return false<br />
end<br />
<br />
local entriesByID = table.n_filter(entries, filterByID)<br />
-- invalidEntries: 5<br />
-- entriesByID: { { id = 15 }, { id = -1 }, { id = 3 }, { id = 12.2 } }<br />
</syntaxhighlight><br />
Filter out content based on search criteria:<br />
<syntaxhighlight lang="lua"><br />
local fruits = {'apple', 'banana', 'grapes', 'mango', 'orange'}<br />
local function filterItems(t, query)<br />
return table.n_filter(t, function(item)<br />
return item:lower():find(query:lower())<br />
end)<br />
end<br />
filterItems(fruits, 'ap') -- {'apple', 'grapes'}<br />
filterItems(fruits, 'an') -- {'banana', 'mango', 'orange'}<br />
</syntaxhighlight><br />
<br />
==table.n_flatten==<br />
; table.n_flatten(table)<br />
: Returns a new table with the sub-table elements concatenated into it.<br />
<br />
; Parameters<br />
* ''table:'' A table of nested sub-tables you wish to flatten.<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
local t1 = {1, 2, {3, 4}};<br />
local t2 = {1, 2, {3, 4, {5, 6}}};<br />
local t3 = {1, 2, {3, 4, {5, 6, {7, 8, {9, 10}}}}};<br />
table.n_flatten(t1) -- {1, 2, 3, 4}<br />
table.n_flatten(t2) -- {1, 2, 3, 4, 5, 6}<br />
table.n_flatten(t3) -- {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}<br />
</syntaxhighlight><br />
<br />
==table.n_matches==<br />
; table.n_matches(tbl, pattern, [pattern2], [patternN])<br />
: Returns a table of unique values within tbl which one of the supplied patterns matches using string.match<br />
<br />
; Parameters<br />
* ''tbl:''<br />
: The table you want to search for values<br />
* ''pattern:''<br />
: The pattern you want to check each value with, using string.match. You can supply multiple patterns, separated by commas<br />
{{MudletVersion|4.8}}<br />
<br />
; Example<br />
<syntaxhighlight lang="lua"><br />
local items = { this = "that", [4] = "other", hp = 500, mana = 40 }<br />
local matches = table.n_matches(items, "%a")<br />
-- matches will be { "that", "other" }<br />
-- order is not preserved/guaranteed<br />
</syntaxhighlight><br />
<br />
==table.n_union==<br />
; table.n_union (table1, table2)<br />
: Returns a numerically indexed table that is the union of the provided tables (that is - merges two indexed lists together). This is a union of unique values. The order and keys of the input tables are not preserved.<br />
<br />
; Parameters<br />
* ''table1:'' the first table as an indexed list.<br />
* ''table2:'' the second table as an indexed list.<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
display(table.n_union({"bob", "mary"}, {"august", "justinian"}))<br />
<br />
{<br />
"bob",<br />
"mary",<br />
"august",<br />
"justinian"<br />
}<br />
</syntaxhighlight><br />
<br />
==table.n_complement==<br />
; table.n_complement (set1, set2)<br />
: Returns a table that is the relative complement of the first numerically indexed table with respect to the second numerically indexed table. Returns a numerically indexed complement of values.<br />
<br />
; Parameters<br />
* ''table1:''<br />
* ''table2:''<br />
<br />
; Example:<br />
<syntaxhighlight lang=lua>local t1 = {1,2,3,4,5,6}<br />
local t2 = {2,4,6}<br />
local comp = table.n_complement(t1,t2)<br />
display(comp)</syntaxhighlight><br />
This prints the following:<br />
1,<br />
3,<br />
5<br />
<br />
; Returns<br />
: A table containing all the values from table1 that do not match the values from table2.<br />
<br />
==table.n_intersection==<br />
; table.n_intersection (...)<br />
: Returns a numerically indexed table that is the intersection of the provided tables. This is an intersection of unique values. The order and keys of the input tables are not preserved<br />
<br />
; Example:<br />
<syntaxhighlight lang=lua>local t1 = {1,2,3,4,5,6}<br />
local t2 = {2,4,6}<br />
local intersect = table.n_intersection(t1,t2)<br />
display(intersect)</syntaxhighlight><br />
This prints the following:<br />
2,<br />
4,<br />
6<br />
<br />
; Returns<br />
: A table containing the values that are found in every one of the tables.<br />
<br />
==table.pickle==<br />
;table.pickle( t, file, tables, lookup )<br />
: Internal function used by table.save() for serializing data.<br />
<br />
==table.remove==<br />
; table.remove(table, value_position)<br />
: Remove a value from an indexed table, by the values position in the table.<br />
: See also: [[Manual:Lua_Functions#table.insert|table.insert]]<br />
<br />
; Parameters:<br />
* '''table'''<br />
: The indexed table you are removing the value from.<br />
* '''value_position'''<br />
: The indexed number for the value you are removing.<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
testTable = { "hi", "bye", "cry", "why" }<br />
table.remove(testTable, 1) -- will remove hi from the table<br />
-- new testTable after the remove<br />
testTable = { "bye", "cry", "why" }<br />
-- original position of hi was 1, after the remove, position 1 has become bye<br />
-- any values under the removed value are moved up, 5 becomes 4, 4 becomes 3, etc<br />
</syntaxhighlight> <br />
{{note}} To remove a value from a key-value table, it's best to simply change the value to nil.<br />
<syntaxhighlight lang="lua"><br />
testTable = { test = "testing", go = "boom", frown = "glow" }<br />
table.remove(testTable, test) -- this will error<br />
testTable.test = nil -- won't error<br />
testTable["test"] = nil -- won't error<br />
</syntaxhighlight><br />
<br />
==table.save==<br />
; table.save(location, table)<br />
: Save a table into an external file in '''location'''.<br />
: See also: [[Manual:Lua_Functions#table.load|table.load]]<br />
<br />
; Parameters:<br />
* '''location:'''<br />
: Where you want the table file to be saved. Can be anywhere on your computer.<br />
* '''table:'''<br />
: The table that you are saving to the file.<br />
<br />
: Example:<br />
<syntaxhighlight lang="lua"><br />
-- Saves the table mytable to the lua file mytable in your Mudlet Home Directory<br />
table.save(getMudletHomeDir().."/mytable.lua", mytable)<br />
</syntaxhighlight><br />
==table.sort==<br />
;table.sort(Table [, comp])<br />
:Sorts table elements in a given order, in-place, from <code>Table[1]</code> to <code>Table[n]</code>, where <code>n</code> is the length of the table. <br />
<br />
:If <code>comp</code> is given, then it must be a function that receives two table elements, and returns true when the first is less than the second (so that not <code>comp(a[i+1],a[i])</code> will be true after the sort). If <code>comp</code> is not given, then the standard Lua operator <code><</code> is used instead.<br />
<br />
:The sort algorithm is not stable; that is, elements considered equal by the given order may have their relative positions changed by the sort.<br />
<br />
:See https://www.lua.org/pil/19.3.html for more info<br />
<br />
==table.size==<br />
; table.size (t)<br />
: Returns the size of a key-value table (this function has to iterate through all of the table to count all elements).<br />
: Returns a number.<br />
<br />
; Parameters<br />
* ''t:'' <br />
: The table you are checking the size of.<br />
{{note}}<br />
For index based tables you can get the size with the # operator:<br />
This is the standard Lua way of getting the size of index tables i.e. ipairs() type of tables with numerical indices. <br />
To get the size of tables that use user defined keys instead of automatic indices (pairs() type) you need to use the function table.size() referenced above.<br />
<syntaxhighlight lang="lua"><br />
local test_table = { "value1", "value2", "value3", "value4" }<br />
myTableSize = #test_table<br />
-- This would return 4.<br />
local myTable = { 1 = "hello", "key2" = "bye", "key3" = "time to go" }<br />
table.size(myTable)<br />
-- This would return 3.<br />
</syntaxhighlight><br />
<br />
==table.unpickle==<br />
;table.unpickle( t, tables, tcopy, pickled )<br />
: Internal function used by table.load() for deserialization.<br />
<br />
==table.update==<br />
;table.update(table1, table2)<br />
: Returns a table in which key/value pairs from table2 are added to table1, and any keys present in both tables are assigned the value from table2, so that the resulting table is table1 updated with information from table2.<br />
<br />
;Example<br />
<syntaxhighlight lang=lua>display(table.update({a = 1, b = 2, c = 3}, {b = 4, d = 5}))<br />
{<br />
a = 1,<br />
b = 4,<br />
c = 3,<br />
d = 5<br />
}<br />
<br />
-- to just set a table to new values, assign it directly:<br />
mytable = {key1 = "newvalue"}<br />
</syntaxhighlight><br />
<br />
==table.union==<br />
;table.union(...)<br />
: Returns a table that is the union of the provided tables. This is a union of key/value pairs. If two or more tables contain different values associated with the same key, that key in the returned table will contain a subtable containing all relevant values. See table.n_union() for a union of values. Note that the resulting table may not be reliably traversable with ipairs() due to the fact that it preserves keys. If there is a gap in numerical indices, ipairs() will cease traversal.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
tableA = {<br />
[1] = 123,<br />
[2] = 456,<br />
["test"] = "test",<br />
}<br />
---<br />
tableB = {<br />
[1] = 23,<br />
[3] = 7,<br />
["test2"] = function() return true end,<br />
}<br />
---<br />
tableC = {<br />
[5] = "c",<br />
}<br />
---<br />
table.union(tableA, tableB, tableC)<br />
-- will return the following:<br />
{<br />
[1] = {<br />
123,<br />
23,<br />
},<br />
[2] = 456,<br />
[3] = 7,<br />
[5] = "c",<br />
["test"] = "test",<br />
["test2"] = function() return true end,<br />
}<br />
</syntaxhighlight><br />
<br />
[[Category:Mudlet Manual]]<br />
[[Category:Mudlet API]]</div>Demonnichttps://wiki.mudlet.org/index.php?title=Comparison_of_MUD_clients&diff=20263Comparison of MUD clients2023-01-07T04:43:56Z<p>Demonnic: /* Protocol support */</p>
<hr />
<div>== Operating systems ==<br />
<br />
The operating systems the [[wikipedia:MUD|MUD]] clients can run on.<br />
<br />
{| class="sortable wikitable"<br />
|-<br />
! Name<br />
! [[wikipedia:Microsoft Windows|Windows]]<br />
! [[wikipedia:Mac OS X|Mac OS X]]<br />
! [[wikipedia:Linux|Linux]]<br />
! [[wikipedia:BSD|BSD]]<br />
! [[wikipedia:Unix|Unix]]<br />
! [[wikipedia:Android (operating system)|Android]]<br />
! [[wikipedia:iOS|iOS]]<br />
|-<br />
! AMudClient<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Atlantis<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! BeipMU<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! BioMUD<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! BlowTorch<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
|-<br />
! CMUD<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! GGMUD<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! GMUD<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Gnome-Mud<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! JamochaMUD<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! KBtin<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! KildClient<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! KMuddy<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Lyntin<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! mcl<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! muby<br />
| {{No}}<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Mudlet<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! MudMagic<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! MUDRammer<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
|-<br />
! MUSHclient<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Portal<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Potato<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Powwow<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Pueblo/UE<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! SimpleMU<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Soiled<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! [[wikipedia:TinTin++|TinTin++]] <br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
|-<br />
! [[wikipedia:TinyFugue|TinyFugue]] <br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Tortilla <br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Trebuchet<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{Yes2|CPI}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Wintin.Net <br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! zMUD<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
|}<br />
<br />
*CPI: [[wikipedia:Cross-platform|Cross-platform]] or [[wikipedia:Interpreter (computing)|Interpreted]] software<br />
<br />
== Protocol support ==<br />
<br />
Information about what protocols the clients support.<br />
<br />
{| class="sortable wikitable"<br />
|-<br />
! Name<br />
! [[wikipedia:ANSI escape code|COLOR]]<br />
! [[wikipedia:VT100|VT100]]<br />
! [[wikipedia:Transport Layer Security|TLS]]<br />
! NAWS<ref>{{cite web|last1=Waitzman|first1=D.|title=Telnet window size option|url=https://tools.ietf.org/html/rfc1073|website=tools.ietf.org|accessdate=8 August 2017|language=en}}</ref><br />
! EOR<ref>{{cite web|last1=Postel|first1=J.|title=Telnet end of record option|url=https://tools.ietf.org/html/rfc885|website=tools.ietf.org|accessdate=8 August 2017|language=en}}</ref><br />
! ECHO<ref>{{cite web|last1=J.|first1=Postel,|last2=J.|first2=Reynolds,|title=Telnet Echo Option|url=https://tools.ietf.org/html/rfc857|website=tools.ietf.org|accessdate=8 August 2017|language=en}}</ref><br />
! MCCP<br />
! MXP<br />
! MSP<br />
! MMCP<br />
! [[wikipedia:xterm|256 colors]]<br />
! [[wikipedia:Unicode|Unicode]]<br />
|-<br />
! AMudClient<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
|-<br />
! Atlantis<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{yes}}<br />
| {{Yes}}<br />
|-<br />
! BeipMU<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
|-<br />
! BioMUD<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
|-<br />
! BlowTorch<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
|-<br />
! CMUD <br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
|-<br />
! GGMUD<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! GMUD<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Gnome-Mud<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
|-<br />
! JamochaMUD<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes2|Partial}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! KBtin<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
|-<br />
! KildClient<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
|-<br />
! KMuddy<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Lyntin<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
|-<br />
! mcl<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
|-<br />
! muby<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
|-<br />
! Mudlet<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
|-<br />
! MudMagic<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! MUSHclient<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
|-<br />
! Portal<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Potato<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
|-<br />
! Powwow<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
|-<br />
! Pueblo/UE<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! SimpleMU<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Soiled<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
|-<br />
! TinTin++<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
|-<br />
! TinyFugue<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
|-<br />
! Tortilla<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
|-<br />
! Trebuchet<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Wintin.Net<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}} <br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
|-<br />
! zMUD<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
|}<br />
* A locally ran [[wikipedia:MCCP|MCCP]] or [[wikipedia:Transport Layer Security|TLS]] [[wikipedia:proxy server|proxy server]] can be used by clients that do not support MCCP or TLS natively.<br />
* Many MUD clients will be able to display [[wikipedia:Unicode|Unicode]] characters but will have [[wikipedia:wordwrapping|wordwrapping]] issues without proper support.<br />
<br />
== Scripting support ==<br />
<br />
{| class="sortable wikitable"<br />
|-<br />
! Name<br />
! [[wikipedia:C Sharp (programming language)|C#]]<br />
! Client-Specific<br />
! [[wikipedia:Lua (programming language)|Lua]]<br />
! [[wikipedia:Perl|Perl]]<br />
! [[wikipedia:Python (programming language)|Python]]<br />
! [[wikipedia:Ruby (programming language)|Ruby]]<br />
! TINTIN<br />
! [[wikipedia:VB.NET|VB.NET]]<br />
! [[wikipedia:Tcl|Tcl]]<br />
! [[wikipedia:PHP|PHP]]<br />
! [[wikipedia:JScript|JScript]]<br />
<br />
|-<br />
! AMudClient<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Atlantis<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
|-<br />
! BeipMU<br />
| {{Yes2|WSH}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes2|WSH}}<br />
| {{Yes2|WSH}}<br />
| {{Yes2|WSH}}<br />
| {{No}}<br />
| {{Yes2|WSH}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes2|WSH}}<br />
|-<br />
! BioMUD<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! BlowTorch<br />
| {{No}}<br />
| {{Yes2|Minimal}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! CMUD<br />
| {{Yes2|WSH}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes2|WSH}}<br />
| {{Yes2|WSH}}<br />
| {{Yes2|WSH}}<br />
| {{Yes}}<br />
| {{Yes2|WSH}}<br />
| {{no}}<br />
| {{no}}<br />
| {{Yes2|WSH}}<br />
|-<br />
! GGMUD<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! GMUD<br />
| {{No}}<br />
| {{Yes2|Minimal}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Gnome-Mud<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! JamochaMUD<br />
| {{No}}<br />
| {{Yes2|Minimal}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! KBtin<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes2|CLI}}<br />
| {{Yes2|CLI}}<br />
| {{Yes2|CLI}}<br />
| {{Yes2|CLI}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes2|CLI}}<br />
| {{Yes2|CLI}}<br />
| {{No}}<br />
|-<br />
! KildClient<br />
| {{No}}<br />
| {{No}}<br />
| {{no}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
|-<br />
! KMuddy<br />
| {{No}}<br />
| {{Yes2|Minimal}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
|-<br />
! Lyntin<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! mcl<br />
| {{no}}<br />
| {{Yes}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
|-<br />
! muby<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
|-<br />
! Mudlet<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! MudMagic<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
|-<br />
! MUSHclient<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes2|Minimal}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
|-<br />
! Portal<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Potato<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Powwow<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Pueblo/UE<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
| {{Yes}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
|-<br />
! SimpleMU<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Soiled<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
| TinTin++<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes2|CLI}}<br />
| {{Yes2|CLI}}<br />
| {{Yes2|CLI}}<br />
| {{Yes2|CLI}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{Yes2|CLI}}<br />
| {{Yes2|CLI}}<br />
| {{No}}<br />
|-<br />
! TinyFugue<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Tortilla<br />
| {{no}}<br />
| {{no}}<br />
| {{Yes}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
| {{Yes}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
|-<br />
! Trebuchet<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{No}}<br />
| {{No}}<br />
|-<br />
! Wintin.Net<br />
| {{Yes}}<br />
| {{No}}<br />
| {{no}}<br />
| {{No}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes}}<br />
| {{Yes}}<br />
| {{no}}<br />
| {{no}}<br />
| {{no}}<br />
|-<br />
! zMUD<br />
| {{Yes2|WSH}}<br />
| {{No}}<br />
| {{No}}<br />
| {{Yes2|WSH}}<br />
| {{Yes2|WSH}}<br />
| {{Yes2|WSH}}<br />
| {{Yes}}<br />
| {{Yes2|WSH}}<br />
| {{no}}<br />
| {{no}}<br />
| {{Yes2|WSH}}<br />
|-<br />
|}<br />
<br />
==Notes==<br />
* WSH: [[wikipedia:Windows Script Host|Windows Script Host]] allows the execution of various scripting languages.<br />
* CLI: [[wikipedia:command-line interface|command-line interface]] using [[wikipedia:redirection (computing)|redirection]], not to be confused with [[wikipedia:system (C standard library)|system (C standard library)]]<br />
* Many clients provide their own scripting language, sometimes in addition to another scripting language.<br />
* Clients providing a modified version of the original TINTIN scripting language are listed as supporting TINTIN.<br />
<br />
==History of this page==<br />
This page uses content from [https://en.wikipedia.org/ Wikipedia]. The original article was at [https://en.wikipedia.org/wiki/Comparison_of_MUD_clients?redirect=no Comparison of MUD clients].<br />
The list of authors can be seen in the [http://en.wikipedia.org/wiki/Comparison_of_MUD_clients?action=history page history]. The text is available under the [https://creativecommons.org/licenses/by-sa/3.0/deed.en Creative Commons Attribution-Share Alike License 3.0 (Unported) (CC-BY-SA)].<br />
<br />
==References==</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:String_Functions&diff=20180Manual:String Functions2022-10-12T19:13:02Z<p>Demonnic: /* f */</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Mudlet API documentation for functions used to manipulate strings.}}<br />
= String Functions =<br />
A collection of functions used to manipulate strings.<br />
==addWordToDictionary==<br />
;addWordToDictionary(word)<br />
:Adds the given word to the custom profile or shared dictionary (whichever is selected in preferences).<br />
<br />
: Returns true on success (the word was actually ''added'' to the dictionary by this call) and nil+msg on error - including if the word was already there - this is so that if you have other scripts that you wish to run when a word was added you can make their execution conditional on success here.<br />
<br />
:See also: [[#removeWordFromDictionary|removeWordFromDictionary()]]<br />
<br />
;Parameters<br />
* ''word:'' custom word to add to the dictionary.<br />
<br />
{{MudletVersion|3.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addWordToDictionary("Darkwind")<br />
addWordToDictionary("黑暗的风")<br />
addWordToDictionary("норм")<br />
</syntaxhighlight><br />
<br />
;Example - function making use of return value:<br />
<syntaxhighlight lang="lua"><br />
function rememberPlayerName(name)<br />
if addWordToDictionary(name) then<br />
echo("Added '" .. name .. "' to dictionary...\n")<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==cecho2string==<br />
; plainText = cecho2string(formattedText)<br />
<br />
:Strips the text formatting from the string passed in, leaving behind only the text.<br />
<br />
;See also: [[Manual:Lua_Functions#ansi2string|ansi2string()]], [[Manual:Lua_Functions#hecho2string|hecho2string()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formattedText:''<br />
: The string you want to strip the formatting codes from<br />
<br />
;Returns <br />
* The string with the formatting codes stripped out.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local exampleString = "<red>Formatted <b>string</b>"<br />
local plainText = cecho2string(exampleString)<br />
-- "Formatted string"<br />
</syntaxhighlight><br />
<br />
==decho2string==<br />
; plainText = decho2string(formattedText)<br />
<br />
:Strips the text formatting from the string passed in, leaving behind only the text.<br />
<br />
;See also: [[Manual:Lua_Functions#ansi2string|ansi2string()]], [[Manual:Lua_Functions#cecho2string|cecho2string()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formattedText:''<br />
: The string you want to strip the formatting codes from<br />
<br />
;Returns <br />
* The string with the formatting codes stripped out.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local exampleString = "<255,0,0>Formatted <b>string</b>"<br />
local plainText = decho2string(exampleString)<br />
-- "Formatted string"<br />
</syntaxhighlight><br />
<br />
==f==<br />
; formattedString = f(str)<br />
: Allows you to combine variables and functions into text (string interpolation) using <code>{}</code>.<br />
<br />
; Parameters<br />
* ''str:''<br />
: The string to perform interpolation against.<br />
<br />
{{MudletVersion|4.11}}<br />
; Example:<br />
<br />
<syntaxhighlight lang=lua><br />
-- old way:<br />
cecho("\nHello, "..matches[2]..", how is it going?")<br />
<br />
-- new way:<br />
cecho(f("\nHello {matches[2]}, how is it going?"))<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang=lua><br />
testResult = "successful"<br />
-- old way:<br />
echo("The test was "..testResult.."\n")<br />
-- with f:<br />
echo(f("The test was {testResult}\n"))<br />
-- echoes "The test was successful\n"<br />
<br />
local testResult = "a failure"<br />
echo(f("The test was {testResult}\n"))<br />
-- echoes "The test was a failure\n" as it sees the local scope over global.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang=lua><br />
-- You can also execute simple expressions<br />
echo(f("2 + 2 = {2 + 2}\n"))<br />
-- echoes "2 + 2 = 4\n"<br />
<br />
-- Or more complicated ones<br />
local function testFunc(item)<br />
return item:title()<br />
end<br />
<br />
echo(f("You should properly capitalize names, such as {testFunc('marilyn')}\n"))<br />
-- echoes "You should properly capitalize names, such as Marilyn\n"<br />
<br />
echo(f("You should properly capitalize names, such as {string.title('robert')}\n")<br />
-- same thing, but uses string.title directly and Robert instead of Marilyn<br />
</syntaxhighlight><br />
<br />
<br />
'''Caution!'''<br />
When using within closures, might not resolve variables correctly if they go out of a scope when closure is called.<br />
<syntaxhighlight lang=lua><br />
function formatter2000()<br />
local upvalue = "2000"<br />
local formatter = function() <br />
echo(f("Let's evaluate: {upvalue}\n"))<br />
end<br />
formatter() -- here evaulation inside f function will work<br />
return formatter<br />
end<br />
<br />
formatter2000()() -- here evaluation inside f function will return nil<br />
-- result<br />
-- Let's evaluate: 2000<br />
-- Let's evaulate: nil<br />
</syntaxhighlight><br />
<br />
You can work around this by doing the following<br />
<syntaxhighlight lang=lua><br />
function formatter2000()<br />
local upvalue = "2000"<br />
local formatter = function()<br />
local upvalue = upvalue -- this keeps upvalue in scope for the function later<br />
echo(f("Let's evaluate: {upvalue}\n"))<br />
end<br />
formatter() -- here evaulation inside f function will work<br />
return formatter<br />
end<br />
<br />
formatter2000()() -- here evaluation inside f function will return 2000 once again<br />
<br />
-- result<br />
-- Let's evaluate: 2000<br />
-- Let's evaulate: 2000<br />
</syntaxhighlight><br />
<br />
==getDictionaryWordList==<br />
;getDictionaryWordList()<br />
:Returns the profile or shared custom dictionary word list (whichever is selected in preferences) - that is, words added via right-click "add word to dictionary" or [[#addWordToDictionary|addWordToDictionary()]].<br />
<br />
: Returns an indexed table of words.<br />
<br />
{{MudletVersion|3.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getDictionaryWordList())<br />
</syntaxhighlight><br />
<br />
==hecho2string==<br />
; plainText = hecho2string(formattedText)<br />
<br />
:Strips the text formatting from the string passed in, leaving behind only the text.<br />
<br />
;See also: [[Manual:Lua_Functions#ansi2string|ansi2string()]], [[Manual:Lua_Functions#decho2string|decho2string()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formattedText:''<br />
: The string you want to strip the formatting codes from<br />
<br />
;Returns <br />
* The string with the formatting codes stripped out.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local exampleString = "#ff0000Formatted #bstring#/b"<br />
local plainText = cecho2string(exampleString)<br />
-- "Formatted string"<br />
</syntaxhighlight><br />
<br />
==removeWordFromDictionary==<br />
;removeWordFromDictionary(word)<br />
:Removed the given word to the custom profile or shared dictionary (whichever is selected in preferences).<br />
<br />
: Returns true on success (if the word was present and removed by this call) and nil+msg on error.<br />
<br />
:See also: [[#addWordToDictionary|addWordToDictionary()]]<br />
<br />
;Parameters<br />
* ''word:'' custom word to remove from the dictionary.<br />
<br />
{{MudletVersion|3.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
removeWordFromDictionary("Darkwind")<br />
removeWordFromDictionary("黑暗的风")<br />
removeWordFromDictionary("норм")<br />
</syntaxhighlight><br />
<br />
==spellCheckWord==<br />
;spellCheckWord(word, [customDictionary])<br />
:Spellchecks the given word against the custom or the system dictionary.<br />
<br />
: Returns true if the word is spelled correctly or false if it's not, and nil+msg on error.<br />
<br />
:See also: [[#addWordToDictionary|addWordToDictionary()]], [[#removeWordFromDictionary|removeWordFromDictionary()]], [[#spellSuggestWord|spellSuggestWord()]]<br />
<br />
;Parameters<br />
* ''word'': word to spellcheck.<br />
* ''customDictionary'' (optional): dictionary to use. If true, the profile or shared dictionary will be used (depending on your settings). If omitted or false, the system dictionary (the language you have selected in settings) will be used.<br />
<br />
{{MudletVersion|3.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- spellcheck against the language dictionary<br />
if spellCheckWord("run") then<br />
echo("'run' is spelled ok!\n")<br />
end<br />
<br />
-- spellcheck against the custom 'add word to dictionary'<br />
if spellCheckWord("Darkwind", true) then<br />
echo("'Darkwind' is spelled OK!\n")<br />
end<br />
</syntaxhighlight><br />
<br />
==spellSuggestWord==<br />
;spellSuggestWord(word, [customDictionary])<br />
:Suggests similar words for the given word.<br />
<br />
: Returns a table of suggestions or nil+msg on error.<br />
<br />
:See also: [[#spellCheckWord|spellCheckWord()]]<br />
<br />
;Parameters<br />
* ''word'': word to give suggestions on.<br />
* ''customDictionary'' (optional): dictionary to use. If true, the profile or shared dictionary will be used (depending on your settings). If omitted or false, the system dictionary (the language you have selected in settings) will be used.<br />
<br />
{{MudletVersion|3.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(spellSuggestWord("Darkwind"))<br />
</syntaxhighlight><br />
<br />
==string.byte, utf8.byte==<br />
;string.byte(string [, i [, j]]) or utf8.byte(string [, i [, j]])<br />
;<nowiki>mystring:byte([, i [, j]])</nowiki><br />
: Returns the internal numerical codes of the characters <code>s[i], s[i+1], ···, s[j]</code>. The default value for <code>i</code> is <code>1</code>; the default value for <code>j</code> is <code>i</code>.<br />
: Note that numerical codes are not necessarily portable across platforms.<br />
: string.byte() works with English text only, use utf8.byte() for the international version.<br />
: See also: [[#string.char.2C_utf8.char|string.char]], [[#string.char.2C_utf8.char|utf8.char]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- the following call will return the ASCII values of "A", "B" and "C"<br />
a, b, c = string.byte("ABC", 1, 3)<br />
echo(a .. " - " .. b .. " - " .. c) -- shows "65 - 66 - 67"<br />
<br />
-- same for the international version but with the Unicode values<br />
a, b, c = utf8.byte("дом", 1, 3)<br />
echo(a .. " - " .. b .. " - " .. c) -- shows "1076 - 1086 - 1084"<br />
</syntaxhighlight><br />
<br />
==string.char, utf8.char==<br />
;string.char(···) or utf8.char(···)<br />
: Receives zero or more integers. Returns a string with length equal to the number of arguments, in which each character has the internal numerical code equal to its corresponding argument.<br />
: Note that numerical codes are not necessarily portable across platforms.<br />
: string.char() works with English text only, use utf8.char() for the international version.<br />
: See also: [[#string.byte.2C_utf8.byte|string.byte]], [[#string.byte.2C_utf8.byte|utf8.byte]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- the following call will return the string "ABC" corresponding to the ASCII values 65, 66, 67<br />
mystring = string.char(65, 66, 67)<br />
<br />
-- same for the infernational version which will return text "дом" for the Unicode values 1076, 1086, 1084<br />
mystring = utf8.char(1076,1086,1084)<br />
print(mystring)<br />
</syntaxhighlight><br />
<br />
==string.cut==<br />
;string.cut(string, maxLen)<br />
: Cuts string to the specified maximum length.<br />
: Returns the modified string.<br />
<br />
;Parameters:<br />
* ''string:''<br />
: The text you wish to cut. Passed as a string.<br />
* ''maxLen:''<br />
: The maximum length you wish the string to be. Passed as an integer number.<br />
<br />
See also: [[#utf8.remove|utf8.remove()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--The following call will return 'abc' and store it in myString<br />
myString = string.cut("abcde", 3)<br />
--You can easily pad string to certain length. Example below will print 'abcde ' e.g. pad/cut string to 10 characters.<br />
local s = "abcde"<br />
s = string.cut(s .. " ", 10) -- append 10 spaces<br />
echo("'" .. s .. "'")<br />
</syntaxhighlight><br />
<br />
==string.dump==<br />
;string.dump()<br />
Converts a function into a binary string. You can use the loadstring() function later to get the function back.<br />
: string.dump() works with both English and non-English text fine.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
string = string.dump(echo("this is a string"))<br />
--The following should then echo "this is a string"<br />
loadstring(string)()<br />
</syntaxhighlight><br />
<br />
==string.enclose==<br />
;string.enclose(string)<br />
: Wraps a string with [[ ]]<br />
: Returns the altered string.<br />
<br />
;Parameters:<br />
* ''String:''<br />
:The string to enclose. Passed as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This will echo '[[Oh noes!]]' to the main window<br />
echo("'" .. string.enclose("Oh noes!") .. "'")<br />
</syntaxhighlight><br />
<br />
==string.ends==<br />
;string.ends(String, Suffix)<br />
: Test if string is ending with specified suffix.<br />
: Returns true or false.<br />
: See also: [[#string.starts|string.starts]]<br />
<br />
;Parameters:<br />
* ''String:''<br />
: The string to test. Passed as a string.<br />
* ''Suffix:''<br />
: The suffix to test for. Passed as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This will test if the incoming line ends with "in bed" and if not will add it to the end.<br />
if not string.ends(line, "in bed") then<br />
echo("in bed\n")<br />
end<br />
</syntaxhighlight><br />
<br />
==string.find, utf8.find==<br />
;string.find(text, pattern [, init [, plain]]) or utf8.find<br />
: Looks for the first match of pattern in the string text. If it finds a match, then find returns the indices of text where this occurrence starts and ends; otherwise, it returns nil. A third, optional numerical argument init specifies where to start the search; its default value is 1 and can be negative. A value of true as a fourth, optional argument plain turns off the pattern matching facilities, so the function does a plain "find substring" operation, with no characters in pattern being considered "magic". Note that if plain is given, then init must be given as well.<br />
If the pattern has captures, then in a successful match the captured values are also returned, after the two indices.<br />
: string.find() works with English text only, use utf8.find() for the international version.<br />
;Example<br />
<syntaxhighlight lang=lua><br />
-- check if the word appears in a variable<br />
if string.find(matches[2], "rabbit") then<br />
echo("Found a rabbit!\n")<br />
end<br />
<br />
-- the following example will print: "3, 4"<br />
local start, stop = string.find("This is a test.", "is")<br />
if start then<br />
print(start .. ", " .. stop)<br />
end<br />
-- note that here "is" is being found at the end of the word "This", rather than the expected second word<br />
<br />
-- to make it match the word on its own, prefix %f[%a] and suffix %f[%A]<br />
if string.find("This is a test", "%f[%a]is%f[%A]") then<br />
echo("This 'is' is the actual stand-alone word\n")<br />
end<br />
</syntaxhighlight><br />
* Return value:<br />
: nil or start and stop position of the first matched text, followed by any captured text.<br />
<br />
==string.findPattern==<br />
; string.findPattern(text, pattern)<br />
: Return first matching substring or nil.<br />
<br />
; Parameters<br />
* ''text:''<br />
: The text you are searching the pattern for.<br />
* ''pattern:''<br />
: The pattern you are trying to find in the text.<br />
<br />
; Example:<br />
Following example will print: "I did find: Troll" string.<br />
<syntaxhighlight lang="lua"><br />
local match = string.findPattern("Troll is here!", "Troll")<br />
if match then<br />
echo("I did find: " .. match)<br />
end<br />
</syntaxhighlight><br />
:This example will find substring regardless of case.<br />
<syntaxhighlight lang="lua">local match = string.findPattern("Troll is here!", string.genNocasePattern("troll"))<br />
if match then<br />
echo("I did find: " .. match)<br />
end<br />
</syntaxhighlight><br />
* Return value:<br />
: nil or first matching substring<br />
See also: [[#string.genNocasePattern|string.genNocasePattern()]]<br />
<br />
==string.format==<br />
;string.format(formatstring,...)<br />
: Returns a formatted version of its variable number of arguments following the description given in its first argument (which must be a string). The format string follows the same rules as the printf family of standard C functions. The only differences are that the options/modifiers *, l, L, n, p, and h are not supported and that there is an extra option, q. The q option formats a string in a form suitable to be safely read back by the Lua interpreter: the string is written between double quotes, and all double quotes, newlines, embedded zeros, and backslashes in the string are correctly escaped when written. For instance, the call<br />
<syntaxhighlight lang=lua><br />
string.format('%q', 'a string with "quotes" and \n new line')<br />
</syntaxhighlight><br />
will produce the string:<br />
<syntaxhighlight lang=lua><br />
"a string with \"quotes\" and \<br />
new line"<br />
</syntaxhighlight><br />
The options c, d, E, e, f, g, G, i, o, u, X, and x all expect a number as argument, whereas q and s expect a string.<br />
<br />
This function does not accept string values containing embedded zeros, except as arguments to the q option.<br />
<br />
string.format() works fine with both English and non-English text.<br />
<br />
;Example<br />
<syntaxhighlight lang=lua><br />
some_data = "MudletUser1"<br />
<br />
-- pad data 20 characters wide to the left<br />
display(string.format("%20s", some_data))<br />
-- result: " MudletUser1"<br />
<br />
-- pad same data but instead to the the right<br />
display(string.format("%-20s", some_data))<br />
-- result: "MudletUser1 "<br />
<br />
-- pad but first truncate data to 6 characters<br />
display(string.format("%20s", string.sub(some_data, 1, 6)))<br />
-- result: " Mudlet"<br />
</syntaxhighlight><br />
<br />
==string.genNocasePattern==<br />
; string.genNocasePattern(template)<br />
: Generate case insensitive search pattern from string.<br />
<br />
; Parameters<br />
* template: The original string to be used as the base.<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
echo(string.genNocasePattern("123abc"))<br />
-- result: "123[aA][bB][cC]"<br />
</syntaxhighlight><br />
<br />
==string.gfind==<br />
;string.gfind()<br />
: This is an old version of what is now string.gmatch. Use string.gmatch instead.<br />
;Example<br />
''Need example''<br />
<br />
==string.gmatch, utf8.gmatch==<br />
;string.gmatch(text, pattern) or utf8.gmatch<br />
: Returns an iterator function that, each time it is called, returns the next captures from pattern over string text. If pattern specifies no captures, then the whole match is produced in each call.<br />
As an example, the following loop<br />
<syntaxhighlight lang=lua><br />
s = "hello world from Lua"<br />
for w in string.gmatch(s, "%a+") do<br />
print(w)<br />
end</syntaxhighlight><br />
will iterate over all the words from string s, printing one per line. The next example collects all pairs key=value from the given string into a table:<br />
<syntaxhighlight lang=lua><br />
t = {}<br />
s = "from=world, to=Lua"<br />
for k, v in string.gmatch(s, "(%w+)=(%w+)") do<br />
t[k] = v<br />
end</syntaxhighlight><br />
For this function, a '^' at the start of a pattern does not work as an anchor, as this would prevent the iteration.<br />
: string.gmatch() works with English text only, use utf8.gmatch() for the international version.<br />
;Example<br />
''Need example''<br />
<br />
==string.gsub, utf8.gsub==<br />
;string.gsub(text, pattern, repl [, n]) or utf8.gsub<br />
: Returns a copy of text in which all (or the first n, if given) occurrences of the pattern have been replaced by a replacement string specified by repl, which can be a string, a table, or a function. gsub also returns, as its second value, the total number of matches that occurred.<br />
<br />
:If repl is a string, then its value is used for replacement. The character % works as an escape character: any sequence in repl of the form %n, with n between 1 and 9, stands for the value of the n-th captured substring (see below). The sequence %0 stands for the whole match. The sequence %% stands for a single %.<br />
<br />
:If repl is a table, then the table is queried for every match, using the first capture as the key; if the pattern specifies no captures, then the whole match is used as the key.<br />
<br />
:If repl is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order; if the pattern specifies no captures, then the whole match is passed as a sole argument.<br />
<br />
:If the value returned by the table query or by the function call is a string or a number, then it is used as the replacement string; otherwise, if it is false or nil, then there is no replacement (that is, the original match is kept in the string).<br />
<br />
: string.gsub() works with English text only, use utf8.gsub() for the international version.<br />
;Example<br />
<syntaxhighlight lang=lua><br />
x = string.gsub("hello world", "(%w+)", "%1 %1")<br />
--> x="hello hello world world"<br />
<br />
x = string.gsub("hello world", "%w+", "%0 %0", 1)<br />
--> x="hello hello world"<br />
<br />
x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")<br />
--> x="world hello Lua from"<br />
<br />
x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)<br />
--> x="home = /home/roberto, user = roberto"<br />
<br />
x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)<br />
return loadstring(s)()<br />
end)<br />
--> x="4+5 = 9"<br />
<br />
local t = {name="lua", version="5.1"}<br />
x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)<br />
--> x="lua-5.1.tar.gz"</syntaxhighlight><br />
<br />
==string.len, utf8.len==<br />
;string.len(string) or utf8.len(string)<br />
;<nowiki>mystring:len()</nowiki><br />
:Receives a string and returns its length. The empty string "" has length 0. Embedded zeros are counted, so "a\000bc\000" has length 5.<br />
: string.len() works with English text only, use utf8.len() for the international version.<br />
<br />
;Parameters:<br />
* ''string:''<br />
:The string (text) you want to find the length of.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- prints 5 for the 5 letters in our word<br />
print(string.len("hello"))<br />
<br />
-- international version<br />
print(utf8.len("слово"))<br />
</syntaxhighlight><br />
<br />
==string.lower, utf8.lower==<br />
;string.lower(string) or utf8.lower(string)<br />
;<nowiki>mystring:lower()</nowiki><br />
:Receives a string and returns a copy of this string with all uppercase letters changed to lowercase. All other characters are left unchanged. The definition of what an uppercase letter is depends on the current locale.<br />
: string.lower() works with English text only, use utf8.lower() for the international version.<br />
: See also: [[#string.upper.2C_utf8.upper|string.upper]], [[#string.upper.2C_utf8.upper|utf8.upper]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- prints an all-lowercase version<br />
print(string.lower("No way! This is AWESOME!"))<br />
<br />
-- international version<br />
print(utf8.lower("Класс! Ето ОТЛИЧНО!"))<br />
</syntaxhighlight><br />
<br />
==string.match, utf8.match==<br />
;string.match(text, pattern [, init]) or utf8.match()<br />
: Looks for the first match of pattern in the string text. If it finds one, then match returns the captures from the pattern; otherwise it returns nil. If pattern specifies no captures, then the whole match is returned. A third, optional numerical argument init specifies where to start the search; its default value is 1 and can be negative.<br />
: string.match() works with English text only, use utf8.match() for the international version.<br />
;Example<br />
''Need example''<br />
<br />
== string.patternEscape, utf8.patternEscape==<br />
;escapedString = string.patternEscape(str) or escapedString = utf8.patternEscape(str)<br />
<br />
:Returns a version of str with all Lua pattern characters escaped to ensure string.match/find/etc look for the original str.<br />
<br />
;See also:[[Manual:Lua_Functions#string.trim|string.trim()]], [[Manual:Lua_Functions#string.genNocasePattern|string.genNocasePattern()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
*''str:''<br />
:The string to escape lua pattern characters in.<br />
<br />
;Returns<br />
*The string with all special Lua pattern characters escaped.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- searching for a url inside of a string. <br />
local helpString = [[<br />
This feature can be accessed by going to https://some-url.com/athing.html?param=value and<br />
retrieving the result!<br />
]]<br />
local url = "https://some-url.com/"<br />
display(helpString:find(url))<br />
-- nil<br />
display(helpString:find(string.patternEscape(url)))<br />
-- 42<br />
-- 62<br />
display(url:patternEscape())<br />
-- "https://some%-url%.com/"<br />
</syntaxhighlight><br />
<br />
==string.rep==<br />
;string.rep(String, n)<br />
;<nowiki>mystring:rep(n)</nowiki><br />
: Returns a string that is the concatenation of <code>n</code> copies of the string <code>String</code>.<br />
: string.rep() works with both English and non-English text fine.<br />
<br />
;Example<br />
<syntaxhighlight lang=lua><br />
-- repeat * 10 times<br />
display(string.rep("*", 10))<br />
-- results in:<br />
**********<br />
<br />
-- do the same thing, but this time calling from a variable<br />
s = "*"<br />
display(s:rep(10))<br />
-- results in:<br />
**********<br />
</syntaxhighlight><br />
<br />
==string.reverse, utf8.reverse==<br />
;string.reverse(string) or utf8.reverse(string)<br />
;<nowiki>mystring:reverse()</nowiki><br />
<br />
: Returns a string that is the string <code>string</code> reversed.<br />
: string.reverse() works with English text only, use utf8.reverse() for the international version.<br />
<br />
;Parameters:<br />
* ''string:''<br />
:The string to reverse. Passed as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
mystring = "Hello from Lua"<br />
echo(mystring:reverse()) -- displays 'auL morf olleH'<br />
<br />
-- international version.<br />
mystring = "Привет от Луа!"<br />
echo(utf8.reverse(mystring)) -- displays '!ауЛ то тевирП', which probably looks the same to you<br />
</syntaxhighlight><br />
<br />
==string.split==<br />
;string.split(string, delimiter)<br />
;<nowiki>myString:split(delimiter)</nowiki><br />
: Splits a string into a table by the given delimiter. Can be called against a string (or variable holding a string) using the second form above.<br />
: Returns a table containing the split sections of the string.<br />
<br />
;Parameters:<br />
* ''string:''<br />
: The string to split. Parameter is not needed if using second form of the syntax above. Passed as a string.<br />
* ''delimiter:''<br />
: The delimiter to use when splitting the string. Passed as a string, and allows for [http://www.lua.org/pil/20.2.html Lua pattern types]. Use % to escape here (and %% to escape a stand-alone %).<br />
{{ Note }} as of Mudlet 4.7+, delimiter will default to " " if not provided.<br />
<br />
{{ Note }} as of Mudlet 4.7+, using "" (empty string) for the delimiter will return the string as a table of characters. IE string.split("This","") will return as {"T", "h", "i", "s"}. Prior to 4.7 using empty string as the delimiter would error after hanging temporarily.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This will split the string by ", " delimiter and print the resulting table to the main window.<br />
names = "Alice, Bob, Peter"<br />
name_table = string.split(names, ", ")<br />
display(name_table)<br />
<br />
--The alternate method<br />
names = "Alice, Bob, Peter"<br />
name_table = names:split(", ")<br />
display(name_table)<br />
</syntaxhighlight><br />
<br />
:Either method above will print out:<br />
: table {<br />
:: 1: 'Alice'<br />
:: 2: 'Bob'<br />
:: 3: 'Peter'<br />
: }<br />
<br />
==string.starts==<br />
;string.starts(string, prefix)<br />
: Test if string is starting with specified prefix.<br />
: Returns true or false<br />
: See also: [[#string.ends|string.ends]]<br />
<br />
;Parameters:<br />
* ''string:''<br />
: The string to test. Passed as a string.<br />
* ''prefix:''<br />
: The prefix to test for. Passed as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--The following will see if the line begins with "You" and if so will print a statement at the end of the line<br />
if string.starts(line, "You") then<br />
echo("====oh you====\n")<br />
end<br />
</syntaxhighlight><br />
<br />
==string.sub, utf8.sub==<br />
;string.sub(text, i [, j]) or utf8.sub()<br />
: Returns the substring of text that starts at i and continues until j; i and j can be negative. If j is absent, then it is assumed to be equal to -1 (which is the same as the string length). In particular, the call string.sub(text,1,j) returns a prefix of text with length j, and string.sub(text, -i) returns a suffix of text with length i.<br />
: string.sub() works with English text only, use utf8.sub() for the international version.<br />
;Example<br />
''Need example''<br />
<br />
==string.title==<br />
;string.title(string)<br />
;<nowiki>mystring:title()</nowiki><br />
: Capitalizes the first character in a string.<br />
: Returns the altered string.<br />
<br />
;Parameters:<br />
* ''string:''<br />
: The string to modify. Not needed if you use the second form of the syntax above.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--Variable testname is now Anna.<br />
testname = string.title("anna")<br />
--Example will set test to "Bob".<br />
test = "bob"<br />
test = test:title()<br />
</syntaxhighlight><br />
<br />
==string.trim==<br />
;string.trim(string)<br />
: Trims string, removing all 'extra' white space at the beginning and end of the text.<br />
: Returns the altered string.<br />
<br />
;Parameters:<br />
* ''string:''<br />
: The string to trim. Passed as a string.<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
--This will print 'Troll is here!', without the extra spaces.<br />
local str = string.trim(" Troll is here! ")<br />
echo("'" .. str .. "'")<br />
</syntaxhighlight><br />
<br />
==string.upper, utf8.upper==<br />
;string.upper(string) or utf8.upper(string)<br />
;<nowiki>mystring:upper()</nowiki><br />
: Receives a string and returns a copy of this string with all lowercase letters changed to uppercase. All other characters are left unchanged. The definition of what a lowercase letter is depends on the current locale.<br />
: string.upper() works with English text only, use utf8.upper() for the international version.<br />
<br />
: See also: [[#string.lower.2C_utf8.lower|string.lower]], [[#string.lower.2C_utf8.lower|utf8.lower]]<br />
<br />
;Parameters<br />
* ''string:''<br />
: The string you want to change to uppercase<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- displays 'RUN BOB RUN'<br />
print(string.upper("run bob run"))<br />
<br />
-- displays 'ДАВАЙ ДАВАЙ!'<br />
print(utf8.upper("давай давай!"))<br />
</syntaxhighlight><br />
<br />
==utf8.charpos==<br />
;utf8.charpos(string[[, charpos], offset])<br />
: Converts UTF-8 position to byte offset, returns the character position and code point. If only offset is given, returns byte offset of this UTF-8 char index. If charpos and offset is given, a new charpos will be calculated by adding/subtracting UTF-8 char offset to current charpos. In all cases, it return a new char position, and code point (a number) at this position.<br />
<br />
;Parameters<br />
* ''string:''<br />
: The input string to work on.<br />
* ''charpos:''<br />
: (optional) character position to work on.<br />
* ''offset:''<br />
: (optional) offset (as a number) to work on.<br />
<br />
==utf8.escape==<br />
;utf8.escape(string)<br />
: Escape a string to UTF-8 format string. It support several escape formats:<br />
<br />
%ddd - which ddd is a decimal number at any length:<br />
change Unicode code point to UTF-8 format.<br />
%{ddd} - same as %nnn but has bracket around.<br />
%uddd - same as %ddd, u stands Unicode<br />
%u{ddd} - same as %{ddd}<br />
%xhhh - hexadigit version of %ddd<br />
%x{hhh} same as %xhhh.<br />
%? - '?' stands for any other character: escape this character.<br />
<br />
;Parameters<br />
* ''string:''<br />
: The string you want to escape<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local u = utf8.escape<br />
print(u"%123%u123%{123}%u{123}%xABC%x{ABC}")<br />
print(u"%%123%?%d%%u")<br />
</syntaxhighlight><br />
<br />
==utf8.fold==<br />
;utf8.fold(string)<br />
: Returns the lowercase version of the string for use in case-insensitive comparisons. If string is a number, it's treated as a code point and the converted code point is returned (as a number).<br />
<br />
;Parameters<br />
* ''string:''<br />
: The string to lowercase.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
print(utf8.fold("ПРИВЕТ")) -- 'привет'<br />
print(utf8.fold("Привет")) -- 'привет'<br />
</syntaxhighlight><br />
<br />
==utf8.insert==<br />
;utf8.insert(string[, idx], substring)<br />
: Inserts the substring into the given string. If idx is given, inserts substring before the character at this index, otherwise the substring will append onto the end of string. idx can be negative.<br />
<br />
;Parameters<br />
* ''string:''<br />
: The input string to work on.<br />
* ''idx:''<br />
: (optional) character position to insert the string at.<br />
* ''substring:''<br />
: text to insert into the substring.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- inserts letter я before the 2nd letter and prints 'мясо'<br />
print(utf8.insert("мсо", 2, "я"))<br />
</syntaxhighlight><br />
<br />
==utf8.ncasecmp==<br />
;utf8.ncasecmp(a, b)<br />
: Compares ''a'' and ''b'' without case. Return -1 means a < b, 0 means a == b and 1 means a > b.<br />
<br />
;Parameters<br />
* ''a:''<br />
: String to compare.<br />
* ''b:''<br />
: String to compare against.<br />
<br />
==utf8.next==<br />
;utf8.next(string[, charpos[, offset]])<br />
: Iterates though the UTF-8 string.<br />
<br />
;Parameters<br />
* ''string:''<br />
: The input string to work on.<br />
* ''charpos:''<br />
: (optional) character position to work on.<br />
* ''offset:''<br />
: (optional) offset (as a number) to work on.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- prints location and code point of every letter<br />
for pos, code in utf8.next, "тут есть текст" do<br />
print(pos, code)<br />
end<br />
</syntaxhighlight><br />
<br />
==utf8.remove==<br />
;utf8.remove(string[, start[, stop]])<br />
: Removes characters from the given string. Deletes characters from the given ''start'' to the end of the string. If ''stop'' is given, deletes characters from ''start'' to ''stop'' (including start and stop). ''start'' and ''stop'' can be negative.<br />
<br />
;Parameters<br />
* ''string:''<br />
: The input string to work on.<br />
* ''start:''<br />
: position to start deleting characters from.<br />
* ''stop:''<br />
: (optional) posititon to stop deleting characters at.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- delete everything from the 3rd character including the character itself<br />
print(utf8.remove("мясо", 3)) -- 'мя'<br />
<br />
-- delete the last character, use negative to count backwards<br />
print(utf8.remove("мясо", -1)) -- 'мяс'<br />
<br />
-- delete everything from the 2nd to the 4th character<br />
print(utf8.remove("вкусное", 2,4)) -- 'вное'<br />
</syntaxhighlight><br />
<br />
==utf8.title==<br />
;utf8.title(string)<br />
: Returns the uppercase version of the string for use in case-insensitive comparisons. If string is a number, it's treated as a code point and the converted code point is returned (as a number).<br />
<br />
;Parameters<br />
* ''string:''<br />
: The string to uppercase.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
print(utf8.title("привет")) -- 'ПРИВЕТ'<br />
print(utf8.title("Привет")) -- 'ПРИВЕТ'<br />
</syntaxhighlight><br />
<br />
==utf8.width==<br />
;utf8.width(string[, ambi_is_double[, default_width]])<br />
: Calculate the widths of the given string. If the string is a code point, return the width of this code point.<br />
<br />
;Parameters<br />
* ''string:''<br />
: The input string to work on.<br />
* ''ambi_is_double:''<br />
: (optional) if provided, the ambiguous width character's width is 2, otherwise it's 1.<br />
* ''default_width:''<br />
: (optional) if provided, this will be the width of unprintable character, used display a non-character mark for these characters.<br />
<br />
==utf8.widthindex==<br />
;utf8.widthindex(string, location[, ambi_is_double[, default_width]])<br />
: Returns the character index at the location in the given string as well as the offset and the width. This is a reverse operation of utf8.width().<br />
<br />
;Parameters<br />
* ''string:''<br />
: The input string to work on.<br />
* ''location:''<br />
: location to get the width of.<br />
* ''ambi_is_double:''<br />
: (optional) if provided, the ambiguous width character's width is 2, otherwise it's 1.<br />
* ''default_width:''<br />
: (optional) if provided, this will be the width of unprintable character, used display a non-character mark for these characters.<br />
<br />
[[Category:Mudlet Manual]]<br />
[[Category:Mudlet API]]</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:Supported_Protocols&diff=20170Manual:Supported Protocols2022-10-01T17:16:13Z<p>Demonnic: /* Upload premade packages for receiving MSP via triggers */</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Manual on supported protocols like CHARSET, GMCP, MSSP, MSP, ATCP, MSDP, MXP, etc.}}<br />
= Supported Protocols =<br />
<br />
Mudlet supports CHARSET, GMCP, MSSP, MSP, ATCP, Aardwolfs 102, MSDP, and the MXP Protocol. <br />
<br />
CHARSET, MXP, MSSP, MSP, GMCP and 102 are enabled by default, MSDP can be enabled in settings.<br />
<br />
[[File:Game protocols toggle.png|center]]<br />
<br />
==GMCP==<br />
Generic Mud Communication Protocol, or GMCP, is a protocol for game servers to communicate information with game clients in a separate channel from the one which carries all of the text that makes up the game itself. Enabling the Debug window will show you GMCP events as they are coming in, and to get an idea of what information is currently stored, hit the Statistics button.<br />
<br />
When working with GMCP on IRE games, this [https://github.com/keneanung/GMCPAdditions GMCP reference] is a useful tool.<br />
<br />
===Using GMCP===<br />
====Receiving GMCP data====<br />
To "trigger" on GMCP messages, you'll need to create [[Manual:Technical_Manual#Event_System|an event handler]] - Mudlet will call it for you whenever relevant GMCP data is received.<br />
<br />
As an example, create a new script and give it a name of the function you'd like to be called when the relevant GMCP message is received. Then, add the GMCP event you'd like the function to fire on under the registered event handlers left. Lastly, define the function - either in this or any other script - and you'll be done. The GMCP data received will be stored in the corresponding field of the ''gmcp'' table, which your function will read from.<br />
<br />
Example:<br />
<br />
:[[File:using_gmcp.png|border|center]]<br />
<br />
The ''test_gmcp()'' function will be called whenever ''Char.Vitals'' is received from the game, and it'll echo the latest data on the screen.<br />
<br />
====Sending GMCP data====<br />
Certain modules will only send data when a request is made by your client. In Mudlet, you can make such a request using the command '''sendGMCP("command")'''. Read your game's relevant documentation, such as the [http://nexus.ironrealms.com/GMCP IRE document on GMCP], for information about specific modules.<br />
<br />
:See Also: [[Manual:Networking Functions#sendGMCP | sendGMCP]]<br />
<br />
===Managing GMCP modules===<br />
While some GMCP modules are enabled by Mudlet by default when you connect with a GMCP enabled game, others may not be 'standard' modules and are instead specific to the game itself. In order to provide a way to manage GMCP modules without scripts causing modules in use by other scripts to be disabled.<br />
<br />
====Registering user====<br />
While this step is no longer strictly required, you can register your 'user' with gmod using<br />
<syntaxhighlight lang="lua"><br />
gmod.registerUser("MyUser")<br />
</syntaxhighlight><br />
Where ''MyUser'' is your plugin/addon/whatever name. However, your user will be automatically registered if you enable or disable any modules using it. Which leads us to...<br />
<br />
====Enabling modules====<br />
Enabling a GMCP module is as easy as:<br />
<syntaxhighlight lang="lua"><br />
gmod.enableModule("MyUser", "Module.Name")<br />
</syntaxhighlight><br />
<br />
If MyUser has not been registered previously, then they will be automatically registered when you call this function. An example of a module which would need to be enabled this way is the IRE.Rift module provided by IRE MUDs. <br />
<syntaxhighlight lang="lua"><br />
-- add this to a login trigger, or anything that will get done just once per login<br />
gmod.enableModule("<character name>", "IRE.Rift")<br />
</syntaxhighlight><br />
<br />
Another example would be the Combat module in Lithmeria, which isn't enabled by default:<br />
<syntaxhighlight lang="lua"><br />
-- add this to a login trigger, or anything that will get done just once per login<br />
gmod.enableModule("<character name>", "Combat")<br />
</syntaxhighlight><br />
<br />
====Disabling modules====<br />
Disabling a GMCP module is just as easy as enabling it:<br />
<syntaxhighlight lang="lua"><br />
gmod.disableModule("MyUser", "Module.Name")<br />
</syntaxhighlight><br />
The main difference being that the module will be turned on as soon as you enable it if it is not already enabled. If you disable it, it will not be disabled with the server until every user of that module has disabled it. This prevents script A from disabling modules that script B may still be using.<br />
<br />
===Thorough GMCP tutorial===<br />
A good GMCP tutorial that walks you through receiving and sending GMCP data is [http://www.mudlet.org/wp-content/uploads/2013/02/GMCPtutorial.pdf available here] - take a read!<br />
<br />
==MSDP==<br />
MSDP (Mud Server Data Protocol) is a protocol for game servers to communicate information with game clients in a separate channel from the one which carries all of the text that makes up the game itself. Mudlet can be configured to use MSDP by clicking on the Settings button (or Options->Preferences in the menu, or <alt>p). The option is on the General tab. <br />
<br />
Once MSDP is enabled, you will need to reconnect to the game so that Mudlet can inform the server it is ready to receive MSDP information. Please note that some servers don't both send MSDP and GMCP at the same time, so even if you enable both in Mudlet, the server will choose to send only one of them.<br />
<br />
Enabling the Debug window will show you MSDP events as they are coming in, and to get an idea of what information is currently stored, hit the Statistics button. Also see [http://tintin.sourceforge.net/msdp/ MSDP reference] for some of the commands and values your server might support.<br />
<br />
===Using MSDP===<br />
====Receiving MSDP data====<br />
To "trigger" on MSDP messages, you'll need to create [[Manual:Technical_Manual#Event_System|an event handler]] - Mudlet will call it for you whenever relevant MSDP data is received.<br />
<br />
As an example, lets create a script that'll track whenever we move - that is, the room number changes. To begin with, we need to ask the game to be sending us updates whenever we move - so do:<br />
<br />
<code><br />
lua sendMSDP("REPORT", "ROOM_VNUM")<br />
</code><br />
<br />
in the command-line first to enable reporting of the room number and name. Then, create a new script and give it a name of the function you'd like to be called when the relevant MSDP message is received. Add the MSDP event you'd like the function to fire on under the registered event handlers - in our case, '''msdp.ROOM_VNUM'''. Lastly, define the function - either in this or any other script - and you'll be done. The MSDP data received will be stored in the corresponding field of the ''msdp'' table, which your function will read from.<br />
<br />
Example:<br />
<br />
:[[File:Using_msdp.png|border|center]]<br />
<br />
The ''test_msdp()'' function will be called whenever ''ROOM_VNUM'' is received from the game, and it'll echo the latest data on the screen.<br />
<br />
====Sending MSDP data====<br />
You can use [[Manual:Networking Functions#sendMSDP | sendMSDP]] to send information via MSDP back to the game. The first parameter to the function is the MSDP variable, and all the subsequent ones are values. See the [http://tintin.sourceforge.net/msdp/ MSDP documentation] for some examples of data that you can send:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- ask the server to report your health changes to you. Result will be stored in msdp.HEALTH in Mudlet<br />
sendMSDP("REPORT", "HEALTH")<br />
<br />
-- client - IAC SB MSDP MSDP_VAR "SEND" MSDP_VAL "AREA NAME" MSDP_VAL "ROOM NAME" IAC SE in the documentation translates to the following in Mudlet:<br />
sendMSDP("SEND", "AREA NAME", "ROOM NAME")<br />
</syntaxhighlight><br />
<br />
:See Also: [[Manual:Networking Functions#sendMSDP | sendMSDP]]<br />
<br />
==Encoding==<br />
More and more game servers are looking beyond ASCII encoding to support extended character sets, like UTF-8 encoding, to meet demand for localization of language and the use of emoji characters.<br />
<br />
===Encoding in Mudlet===<br />
Reference our manual page on [[Manual:Unicode | Unicode]] for more information on Unicode updating, scripting and trigger support in Mudlet.<br />
<br />
====Manual Encoding Updates====<br />
Mudlet supports manual selection of a server data encoding. Mudlet users may update the server data encoding for a profile by choosing Settings, General and selecting a server data encoding from the corresponding drop-down menu. The server data encoding defaults to ASCII. When the setting is changed, the selected encoding saves with the user's profile information.<br />
<br />
====Automated Encoding Updates====<br />
Negotiating the '''CHARSET''' telnet option provides game servers the capability to automatically request a preferred character set with Mudlet per [https://tools.ietf.org/html/rfc2066 RFC 2066]. Game servers may send a telopt WILL CHARSET (42), Mudlet responds with a DO CHARSET (42), then the game server may send SB CHARSET (42) REQUEST (1) <separator_character> <charset>. Mudlet will respond with SB CHARSET (42) ACCEPTED (2) <charset> if it supports that character set. Mudlet will respond with SB CHARSET (42) REJECTED (3) if it refuses the requested character set(s). When Mudlet accepts a requested character set, it automatically updates the server data encoding viewable in the Settings menu. It is possible to send a list of requested character sets to Mudlet by appending additional "<separator_character> <charset>" byte groups to a SB CHARSET (42) REQUEST (1).<br />
<br />
Success example:<br />
{| class="wikitable"<br />
! Server<br />
! Mudlet<br />
|-<br />
| IAC WILL CHARSET (42) <br />
| IAC DO CHARSET (42)<br />
|-<br />
| IAC SB CHARSET (42) REQUEST (1) <space> ''UTF-8'' IAC SE<br />
| IAC SB CHARSET (42) ACCEPTED (2) ''UTF-8'' IAC SE<br />
|-<br />
|}<br />
<br />
The following is an example of an attempted negotiation where the encoding was not available with Mudlet:<br />
{| class="wikitable"<br />
! Server<br />
! Mudlet<br />
|-<br />
| IAC WILL CHARSET (42) <br />
| IAC DO CHARSET (42)<br />
|-<br />
| IAC SB CHARSET (42) REQUEST (1) <space> ''DEEP-6'' IAC SE<br />
| IAC SB CHARSET (42) REJECTED (3) IAC SE<br />
|-<br />
|}<br />
<br />
If a Mudlet user does not want to negotiate character set, they may choose the Settings, Special Options menu item in Mudlet and enable "Force CHARSET negotiation off". The following is an example of an attempted negotiation where "Force CHARSET negotiation off" is enabled.<br />
{| class="wikitable"<br />
! Server<br />
! Mudlet<br />
|-<br />
| IAC WILL CHARSET (42) <br />
| IAC DONT CHARSET (42)<br />
|-<br />
|}<br />
<br />
CHARSET negotiation is available in Mudlet 4.10+.<br />
<br />
==MSSP==<br />
'''Mud Server Status Protocol''', or MSSP, provides a way for game crawlers (i.e. [https://tintin.sourceforge.io/protocols/mssp/mudlist.html MSSP Mud Crawler]) and game listing sites (search for Listings [https://www.reddit.com/r/MUD/ here]) to gather detailed information about a game, including dynamic information like boot time and the current amount of online players. It also makes submitting a new game entry very simple on game listing sites. A player or administrator is only required to fill in the hostname and port and other information is gathered from behind the scenes.<br />
<br />
===MSSP in Mudlet===<br />
The MSSP data presented in Mudlet will enable MSSP standard data fields to be made accessible for scripting. Some useful fields include the game name, number of players, uptime, game hostname, game port, codebase, admin contact, Discord invite URL, year created, link to an icon, ip address, primary language, game location, website and several others may be available. It is up to the game in question to populate the data, so don't expect all fields to be filled in.<br />
<br />
MSSP is available in Mudlet 4.1+.<br />
<br />
===Receiving MSSP Data===<br />
To receive MSSP data in Mudlet, these conditions must be met:<br />
<br />
# The ''Enable MSSP'' box in the Settings window of Mudlet must be checked (default on).<br />
# The game must negotiate MSSP with clients like Mudlet at its login screen. Details [https://tintin.sourceforge.io/protocols/mssp/ here].<br />
<br />
To see whether your game supports MSSP, after connecting, type ''lua mssp''. If the game does not support MSSP, you will see an empty table ''mssp = {}''. If it does you will see information similar to the example below. The data may be accessed in a similar way to the instructions for GMCP listed above. Typically, MSSP data is only sent once per connection.<br />
<br />
<syntaxhighlight lang="lua"><br />
mssp = {<br />
HOSTNAME = "stickmud.com",<br />
VT100 = "1",<br />
UPTIME = "1565657220",<br />
MSDP = "0",<br />
MCP = "0",<br />
GMCP = "1",<br />
PORT = "7680",<br />
["MINIMUM AGE"] = "13",<br />
PUEBLO = "0",<br />
INTERMUD = "-1",<br />
SKILLS = "100",<br />
["HIRING BUILDERS"] = "0",<br />
PLAYERS = "6",<br />
CONTACT = "askstickmud@hotmail.com",<br />
CODEBASE = "LDMud 3.5.0 (3.5.1)",<br />
["HIRING CODERS"] = "0",<br />
["PAY FOR PERKS"] = "0",<br />
LOCATION = "Canada",<br />
GAMESYSTEM = "Custom",<br />
MCCP = "0",<br />
SUBGENRE = "Medieval Fantasy",<br />
ROOMS = "10000",<br />
STATUS = "Live",<br />
FAMILY = "LPMud",<br />
LEVELS = "150",<br />
CREATED = "1991",<br />
["PAY TO PLAY"] = "0",<br />
IP = "24.138.28.11",<br />
MOBILES = "-1",<br />
GAMEPLAY = "Hack and Slash",<br />
CLASSES = "8",<br />
NAME = "StickMUD",<br />
SSL = "0",<br />
ANSI = "1",<br />
ICON = "https://www.stickmud.com/favicon.ico",<br />
RACES = "12",<br />
UTF-8 = "0",<br />
AREAS = "-1",<br />
MXP = "0",<br />
HELPFILES = "-1",<br />
["XTERM 256 COLORS"] = "0",<br />
MSP = "1",<br />
OBJECTS = "9780",<br />
WEBSITE = "https://www.stickmud.com",<br />
GENRE = "Fantasy",<br />
DISCORD = "https://discord.gg/erBBxt",<br />
LANGUAGE = "English"<br />
}<br />
</syntaxhighlight><br />
<br />
==MSP==<br />
<br />
Want to add accessibility and excitement into your game? How about implementing sound and music triggers?<br />
<br />
'''Mud Sound Protocol''', or MSP, provides a way for games to send sound and music triggers to clients. Clients have the option to implement a framework where the corresponding triggers play. MSP triggers are sent in one direction to game clients and not to game servers. Sounds may be downloaded manually or automatically if conditions are met.<br />
<br />
Games could use telnet option negotiation to signal clients support for MSP (''WILL'', ''WONT''), and toggling MSP processing on and off (''DO'', ''DONT''). This is communicated using TELOPT 90, which is reserved (unofficially) for the MSP protocol by our community. Games that do not support telnet option negotiation for MSP should provide a means for their players to toggle this feature on and off.<br />
<br />
The latest specification for MSP is located [https://www.zuggsoft.com/zmud/msp.htm here]. <br />
<br />
===MSP in Mudlet===<br />
<br />
Mudlet processes MSP sound and music triggers in three ways:<br />
<br />
#'''MSP over OOB''' - Mudlet is capable of receiving hidden, out-of-band telnet sound and music triggers from game servers via messaging with TELOPT 90.<br />
#'''MSP for Lua''' - Mudlet triggers may capture and invoke the [[Manual:Lua Functions#receiveMSP | receiveMSP]] function available through the Lua interpreter of Mudlet to process MSP.<br />
#'''MSP over GMCP''' - Mudlet may receive GMCP events from game servers sent with the [[Manual:Scripting#MUD_Client_Media_Protocol | Client.Media]] package.<br />
<br />
Sound or music triggers that contain a media file name will be searched for in the '''media''' folder of the corresponding Mudlet profile that matches the host for the game. If the ''media'' folder and the file are found by Mudlet, it will be played, given the host's operating system supports playing that type of media file. If the file is not found, Mudlet could initiate a download of the media file when provided a URL to find the file. Alternatively, game administrators may instruct players on other ways to transfer media files by 1) creating a ''media'' folder in their game's Mudlet profile and 2) copying files or extracting them from an archive (zip).<br />
<br />
MSP is available in Mudlet 4.4+<br />
<br />
===Receiving MSP Data===<br />
<br />
Processing of MSP is enabled by default on new game profiles. Control whether the processing is on or off through the Settings menu in Mudlet.<br />
<br />
====MSP over OOB====<br />
<br />
Game administrators may send sound and music triggers over the out-of-bounds (hidden) telnet channel encoded with TELOPT 90 after performing telnet negotiation with Mudlet. The advantage to this is that all of the communication is behind the scenes with no additional trigger requirements for the player (see ''MSP over Lua''). Games will send the bytes of out-of-band messages to Mudlet in a format like this: <pre>IAC SB TELOPT_MSP !!SOUND(cow.wav L=2 V=100) IAC SE</pre><br />
<br />
{{note}} Game admins: This option does require a TELOPT 90 WILL message.<br />
<br />
====MSP for Lua====<br />
<br />
Check for MSP support with your game and enable any options that allow sound and music triggers to be sent to your screen.<br />
<br />
You can download the package from [[Media:MSP.zip]] or follow the instructions below.<br />
<br />
Create a sound trigger to invoke the Lua interpreter:<br />
<br />
{| class="wikitable"<br />
!Name<br />
!Text<br />
!Type<br />
!Script<br />
|-<br />
| style="text-align:center;" |Sound Trigger<br />
|^!!SOUND\((\S+?)(?: (.+))?\)$<br />
|perl regex<br />
| style="text-align:left;" |<br />
*deleteLine()<br />
*[[Manual:Lua Functions#receiveMSP | receiveMSP]](matches[1])<br />
|-<br />
|}<br />
<br />
Create a music trigger to invoke the Lua interpreter:<br />
<br />
{| class="wikitable"<br />
!Name<br />
!Text<br />
!Type<br />
!Script<br />
|-<br />
| style="text-align:center;" |Music Trigger<br />
|^!!MUSIC\((\S+?)(?: (.+))?\)$<br />
|perl regex<br />
| style="text-align:left;" |<br />
*deleteLine()<br />
*[[Manual:Lua Functions#receiveMSP | receiveMSP]](matches[1])<br />
|-<br />
|}<br />
<br />
{{note}} Game admins: Best practice is to implement a TELOPT 90 WILL message as a signal to the client that MSP is supported. This is not required. <br />
<br />
If your game does not negotiate MSP, you can download [[Media:MSP-Alternate.zip]] or you can use this script in your trigger instead of receiveMSP for MSP Sound:<br />
<syntaxhighlight lang="lua"><br />
deleteLine()<br />
local mspFile = nil<br />
local mspVolume = 100<br />
local mspLength = 1<br />
local mspPriority = 50<br />
local mspType = nil<br />
local mspURL = nil<br />
-- Strip !!SOUND() from the line<br />
local line = matches[1]:sub(9, -2)<br />
-- Break up the line into tokens<br />
local tokens = line:split(" ")<br />
-- Iterate through the tokens to discover MSP values<br />
for index, value in ipairs(tokens) do<br />
if index == 1 then<br />
mspFile = value<br />
elseif value:find("V=", 1, true) == 1 or value:find("v=", 1, true) == 1 then<br />
mspVolume = tonumber(value:sub(3))<br />
elseif value:find("L=", 1, true) == 1 or value:find("l=", 1, true) == 1 then<br />
mspLength = tonumber(value:sub(3))<br />
elseif value:find("P=", 1, true) == 1 or value:find("p=", 1, true) == 1 then<br />
mspPriority = tonumber(value:sub(3))<br />
elseif value:find("T=", 1, true) == 1 or value:find("t=", 1, true) == 1 then<br />
mspType = value:sub(3)<br />
elseif value:find("U=", 1, true) == 1 or value:find("u=", 1, true) == 1 then<br />
mspURL = value:sub(3)<br />
end<br />
end<br />
if mspFile == "Off" and mspURL == nil then<br />
stopSounds()<br />
else<br />
playSoundFile(<br />
{<br />
name = mspFile,<br />
volume = mspVolume,<br />
loops = mspLength,<br />
priority = mspPriority,<br />
tag = mspType,<br />
url = mspURL,<br />
}<br />
)<br />
end<br />
</syntaxhighlight><br />
<br />
If your game does not negotiate MSP, you can use this script in your trigger instead of receiveMSP for MSP Music:<br />
<syntaxhighlight lang="lua"><br />
deleteLine()<br />
local mspFile = nil<br />
local mspVolume = 100<br />
local mspLength = 1<br />
local mspContinue = true<br />
local mspType = nil<br />
local mspURL = nil<br />
-- Strip !!MUSIC() from the line<br />
local line = matches[1]:sub(9, -2)<br />
-- Break up the line into tokens<br />
local tokens = line:split(" ")<br />
-- Iterate through the tokens to discover MSP values<br />
for index, value in ipairs(tokens) do<br />
if index == 1 then<br />
mspFile = value<br />
elseif value:find("V=", 1, true) == 1 or value:find("v=", 1, true) == 1 then<br />
mspVolume = tonumber(value:sub(3))<br />
elseif value:find("L=", 1, true) == 1 or value:find("l=", 1, true) == 1 then<br />
mspLength = tonumber(value:sub(3))<br />
elseif value:find("C=", 1, true) == 1 or value:find("c=", 1, true) == 1 then<br />
if tonumber(value:sub(3)) == 0 then<br />
mspContinue = false<br />
else<br />
mspContinue = true<br />
end<br />
elseif value:find("T=", 1, true) == 1 or value:find("t=", 1, true) == 1 then<br />
mspType = value:sub(3)<br />
elseif value:find("U=", 1, true) == 1 or value:find("u=", 1, true) == 1 then<br />
mspURL = value:sub(3)<br />
end<br />
end<br />
if mspFile == "Off" and mspURL == nil then<br />
stopMusic()<br />
else<br />
playMusicFile(<br />
{<br />
name = mspFile,<br />
volume = mspVolume,<br />
loops = mspLength,<br />
continue = mspContinue,<br />
tag = mspType,<br />
url = mspURL,<br />
}<br />
)<br />
end<br />
</syntaxhighlight><br />
<br />
====MSP over GMCP ====<br />
<br />
Reference Mudlet's [[Manual:Scripting#MUD_Client_Media_Protocol | documentation]] on the [[Standards:MUD_Client_Media_Protocol | MUD Client Media Protocol]] specification for more information.<br />
<br />
{{note}} Game admins: Do not implement a TELOPT 90 WILL message exchange when exclusively using this option.<br />
<br />
===MSP Troubleshooting===<br />
<br />
*Wildcards ''?'' or ''*'' within the file name do not trigger automatic sound or music downloads. Ensure the sound was downloaded previously prior to using a wildcard.<br />
*Mudlet < 4.11 would not play the MSP sound if it had unknown elements, Mudlet 4.12+ will ignore the unknown elements and do the best it can to play the sound.<br />
<br />
===MSP Specification===<br />
For more insight into the syntax of sound and music triggers, please reference the [https://www.zuggsoft.com/zmud/msp.htm specification].<br />
<br />
== ATCP==<br />
<br />
Mudlet includes support for ATCP. This is primarily available on IRE-based MUDs, but Mudlet's implementation is generic enough such that any it should work on others.<br />
<br />
{{Note}} ATCP has been overtaken by GMCP, prefer to use that instead.<br />
<br />
The latest ATCP data is stored in the atcp table. Whenever new data arrives, the previous is overwritten. An event is also raised for each ATCP message that arrives. To find out the available messages available in the atcp table and the event names, you can use display(atcp).<br />
<br />
Note that while the typical message comes in the format of Module.Submodule, ie Char.Vitals or Room.Exits, in Mudlet the dot is removed - so it becomes CharVitals and RoomExits. <br />
;Example<br />
<syntaxhighlight lang="lua"><br />
room_number = tonumber(atcp.RoomNum)<br />
echo(room_number)<br />
</syntaxhighlight><br />
<br />
===Triggering on ATCP events===<br />
<br />
If you’d like to trigger on ATCP messages, then you need to create scripts to attach handlers to the ATCP messages. The ATCP handler names follow the same format as the atcp table - RoomNum, RoomExits, CharVitals and so on.<br />
<br />
While the concept of handlers for events is to be explained elsewhere in the manual, the quick rundown is this - place the event name you’d like your script to listen to into the Add User Defined Event Handler: field and press the + button to register it. Next, because scripts in Mudlet can have multiple functions, you need to tell Mudlet which function should it call for you when your handler receives a message. You do that by setting the Script name: to the function name in the script you’d like to be called.<br />
<br />
For example, if you’d like to listen to the RoomExits event and have it call the process_exits() function - register RoomExits as the event handler, make the script name be process_exits, and use this in the script:<br />
<br />
<syntaxhighlight lang="lua"><br />
function process_exits(event, args)<br />
echo("Called event: " .. event .. "\nWith args: " .. args)<br />
end<br />
</syntaxhighlight><br />
<br />
Feel free to experiment with this to achieve the desired results. A ATCP demo package is also available on the forums for using event handlers and parsing its messages into Lua datastructures.<br />
<br />
===Mudlet-specific ATCP===<br />
See [[Manual:ATCP_Extensions|ATCP Extensions]] for ATCP extensions that have been added to Mudlet.<br />
<br />
==Aardwolf’s 102 subchannel==<br />
<br />
Similar to ATCP, Aardwolf includes a hidden channel of information that you can access in Mudlet. Mudlet deals with it in the same way as with ATCP, so for full usage instructions see the ATCP section. All data is stored in the channel102 table, such that you can do:<br />
<br />
<syntaxhighlight lang="lua"><br />
display(channel102)<br />
</syntaxhighlight><br />
<br />
... to see all the latest information that has been received. The event to create handlers on is titled '''channel102Message''', and you can use the [[Manual:Lua_Functions#sendTelnetChannel102|sendTelnetChannel102(msg)]] function to send text via the 102 channel back to Aardwolf.<br />
<br />
<syntaxhighlight lang="lua"><br />
-- Function for detecting AFK status on Aardwolf mud.<br />
function amIafk()<br />
for k,v in pairs(channel102) do<br />
if k==100 and v==4 then<br />
return true<br />
end<br />
end<br />
return false<br />
end<br />
</syntaxhighlight><br />
<br />
==MXP==<br />
MXP is based loosely on the HTML and XML standards supported by modern web browsers. It is only "loosely" based upon these standards because games require dynamic, streaming text, rather than the page-oriented view of web browsers. Also, the existing standards are needlessly verbose for use on a game where text efficiency is important.<br />
<br />
In addition, there are additional security concerns to worry about with MXP. While support for HTML tags within a line is desired, players on a game can exploit this power and cause problems. Certain HTML functions need to be restricted so that players cannot abuse them. For example, while it might be desirable to allow players to change the font or color of their chat messages, you would not want to allow them to display a large graphics image, or execute script commands on the client of other users. MXP handles this by grouping the various tags and commands into secure and open categories, and preventing the secure tags from being used by players.<br />
<br />
Mudlet implements a subset of MXP features - the most popular ones that are actually in use. Mudlet supports MXP links (including send to prompt and open in browser in Mudlet 3.17+), pop-up menus, creation of custom elements, and line modes. As a game admin, you can ask what features are supported with the <code><SUPPORT></code> command.<br />
<br />
=== MXP in Mudlet ===<br />
Just like GMCP, MXP data is available in the <code>mxp.</code> namespace and events are raised. To see all MXP events, turn on Debug mode.<br />
<br />
[[File:MXP data.png]]<br />
<br />
<syntaxhighlight lang="lua"><br />
function testmxpsend()<br />
print("Text for the link is: ".. mxp.send.href)<br />
print("Commands to do are: ")<br />
display(mxp.send.actions)<br />
print("\n")<br />
end<br />
<br />
registerAnonymousEventHandler("mxp.send", "testmxpsend")<br />
</syntaxhighlight><br />
<br />
{{Note}} Available in Mudlet 4.8+<br />
<br />
=== Receiving MXP Data ===<br />
[[File:Mudlet MXP example.gif|alt=shows how MXP can be used to BUY an item at a shop, then within the inventory they can select what to do with their items. i.e. Drop, Eat, Wear, Drink...|thumb|MXP example in Mudlet]]<br />
Processing of MXP is enabled by default on new game profiles. Control whether the processing is on or off through the Settings menu in Mudlet.<br />
<br />
==== Simple example of receiving MXP Data (Server owners) ====<br />
<syntaxhighlight lang="html"><br />
<SEND href=\"&text;\"> go north... </SEND>"<br />
</syntaxhighlight>This creates a clickable link that will enable the player to navigate without typing the directions into Mudlet. MXP sends the data immediately when clicked. <br />
<br />
==== Advanced example of receiving MXP Data (Server owners) ====<br />
<syntaxhighlight lang="html"><br />
<send href='examine &#34;&name;&#34;|get &#34;&name;&#34;' hint='Right mouse click to act on this item|Get &desc;|Examine &desc;|Look in &desc;' expire=get>\" ATT='name desc'><br />
</syntaxhighlight>This creates a clickable link that will 'examine' an item. It also enables a right-click function wherein the player can select to either examine or get the item (in this case &name; is the item and &desc; is the item's description ).<br />
<br />
===MXP Specification===<br />
MXP was originally developed and supported by the Zuggsoft team. For more insight into the syntax, reference the [https://www.zuggsoft.com/zmud/mxp.htm specification]. Mudlet has a partial implementation version 1.0 of the MXP spec - to see what is supported, ask Mudlet with the [https://www.zuggsoft.com/zmud/mxp.htm#Version%20Control <SUPPORT>] tag.<br />
<br />
==Secure connection (TLS)==<br />
To connect to a game securely, tick the 'Secure' box in the profile connection settings:<br />
<br />
[[File:Secure-connection.png|center]]<br />
<br />
Note that the game must support a secure (TLS) connection in order for this to work, and this feature is available in Mudlet 3.17+.<br />
<br />
If you are a games admin/developer, check out [https://wiki.mudlet.org/w/Sample_TLS_Configuration this] or [https://blog.oestrich.org/2018/11/nginx-tls-socket this] example on how to setup a secure connection to your game.<br />
<br />
==Adding support for a telnet protocol ==<br />
In addition to supporting ATCP, GMCP, Aardwolf's 102 and MXP, Mudlet has open telnet support - meaning that for any telnet protocol it doesn't support, it has the tools you can use to build the support for. This does not mean Mudlet supports other protocols "out of the box" - you will either have to get code that adds the support, or you could create it yourself.<br />
<br />
The basic tools that you need are [[Manual:Miscellaneous_Functions#addSupportedTelnetOption|addSupportedTelnetOption()]], [[Manual:Miscellaneous_Functions#sendSocket|sendSocket()]] and the [[Manual:Event_Engine#sysTelnetEvent|sysTelnetEvent]].<br />
<br />
Create [[Manual:Event_Engine#Registering_an_event_from_a_script|an event handler]] that goes off on [[Manual:Event_Engine#sysTelnetEvent|sysTelnetEvent]] - which is raised whenever an unsupported telnet option is encountered. Your logic handling will start in this event handler. Once you decide what you'd like to send to the game, use [[Manual:Miscellaneous_Functions#sendSocket|sendSocket()]] to send raw data as-is. Finally, when your logic is done, use [[Manual:Miscellaneous_Functions#addSupportedTelnetOption|addSupportedTelnetOption()]] to register your telnet option with Mudlet, so it will respond with telnet DO on a query from the game server. See [http://www.mudbytes.net/forum/comment/63920/#c63920 this MSDP snippet] for a barebones example.<br />
<br />
===API philosophy===<br />
Adding a support for a new telnet protocol will involve adding the user-facing API. It best for users if it was in the same style as Mudlets handling of other protocols. To see how it's done exactly, check out GMCP, ATCP or Aardwolf 102 examples - but the gist of it is provided below.<br />
<br />
Mudlet has a built-in event system, which is used to broadcast messages in an independent way. With it, people can "trigger" on 102, ATCP or GMCP events with Lua functions that get called whenever an event they're interested in is raised. '''Use the event system to provide your users with a way to react to new protocol data'''.<br />
<br />
Events have names, and optionally, any amount of data with them. For protocol support, Mudlet prefixes the relevant message received name with the protocol name in lowercase. For example, an ATCP Char.Vitals getting updated would raise an event titled "atcp.Char.Vitals". A GMCP Room.Info message would raise a "gmcp.Room.Info" message. <br />
<br />
Additionally, Mudlet also allows catch-all event - in case the user wants to use one event handler for a variety of sub-events (it's not uncommon for games to use ''Main.Sub.Add'', ''Main.Sub.Remove'', ''Main.Sub.List'' to keep track of a list, for example, while conserving data). To accomplish this, it raises events for every relevant namespace - that is, a Main.Sub.Add event will raise ''protocol.Main.Sub'' and ''protocol.Main.Sub.Add events''. While it is entirely possible for one event handler to react to multiple events, this is provided for convenience.<br />
<br />
For storing protocol data, Mudlet uses an aptly named global table - '''gmcp''' for GMCP data, '''atcp''' for ATCP data. Data is stored in the same way it is received and the event is raised for - so a Char.Vitals message's contents will be stored in gmcp.Char.Vitals, a Room.Info's contents in gmcp.Room.Info. If there were was any nested data within the message, it is stored as a table within the proper namespace - ie, a "details" JSON array of a GMCP Room.Info message would be stored in gmcp.Room.Info.details. '''Use a global table with the protocol name in lowerspace for storing permanent data''' that your users will read from.<br />
<br />
That's it! If you'll need any Mudlet-related help, feel free to [http://forums.mudlet.org/viewforum.php?f=9 post on our forums]. Once you're done, [[Mudlet_Packages|package your work]] for distribution which you can optionally post in the [http://forums.mudlet.org/viewforum.php?f=6 finished scripts] section.<br />
<br />
[[Category:Mudlet Manual]]</div>Demonnichttps://wiki.mudlet.org/index.php?title=File:MSP-Alternate.zip&diff=20169File:MSP-Alternate.zip2022-10-01T17:10:03Z<p>Demonnic: Alternate form of MSP package, for when the other one doesn't work.</p>
<hr />
<div>== Summary ==<br />
Alternate form of MSP package, for when the other one doesn't work.</div>Demonnichttps://wiki.mudlet.org/index.php?title=File:MSP.zip&diff=20168File:MSP.zip2022-10-01T17:09:17Z<p>Demonnic: Pair of triggers to parse MSP lines from a MUD which does not negotiate the OOB telopt.</p>
<hr />
<div>== Summary ==<br />
Pair of triggers to parse MSP lines from a MUD which does not negotiate the OOB telopt.</div>Demonnichttps://wiki.mudlet.org/index.php?title=Compiling_Mudlet&diff=20080Compiling Mudlet2022-08-12T03:41:35Z<p>Demonnic: /* Compiling on Raspberry Pi OS */</p>
<hr />
<div>{{TOC right}}<br />
<br />
If you just want to use Mudlet, you can skip these steps, and use one of the already ready (pre-compiled) installers [https://www.mudlet.org/download ready for download].<br />
<br />
Otherwise, hop in for new adventure! <br />
<br />
[[File:Easy Mudlet code understanding.png|frame|none]]<br />
<br />
= Key contributing information =<br />
<br />
Clang format is used to automatically format code submissions using the [https://github.com/Mudlet/Mudlet/blob/development/src/.clang-format src/.clang-format] style. [http://doc.qt.io/qtcreator/creator-beautifier.html See here] how to enable clang-format with Qt Creator - and make sure to specify the 'File' option for the configuration style.<br />
<br />
Branches:<br />
<br />
'''development''' is the development branch where new features can go.<br />
<br />
Workflow:<br />
<br />
Fork and submit a PR with your changes ([https://guides.github.com/activities/forking/ Github tutorial]).<br />
<br />
Here is a list of package versions delivered with different Linux distros. You may want to upgrade these: <br />
https://repology.org/project/mudlet/versions<br />
<br />
= Compiling =<br />
<br />
== Compiling on Ubuntu ==<br />
<br />
These instructions will get you setup compiling on Ubuntu. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
===Ubuntu 21.10===<br />
Following instructions will work on Ubuntu 21.10 as well as all it's flavours and derivatives (such as KDE Neon, for example)<br />
Important thing is to have ''Universe'' repository enabled in your package manager. (on Ubuntu you will have all the repositories that you need already enabled by default.)<br />
<br />
'''1. necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo apt install ubuntu-restricted-extras qtcreator build-essential git zlib1g-dev libhunspell-dev \<br />
libpcre3-dev libzip-dev libboost-dev libboost-all-dev libyajl-dev libpulse-dev libpugixml-dev \<br />
liblua5.1-0-dev lua-filesystem lua-zip lua-sql-sqlite3 luarocks ccache lua-rex-pcre lua5.1 \<br />
libglu1-mesa-dev mesa-common-dev libglib2.0-dev libgstreamer1.0-dev libqt5opengl5-dev \<br />
qtmultimedia5-dev qttools5-dev qt5keychain-dev libsecret-1-dev \<br />
libqt5texttospeech5-dev qtspeech5-flite-plugin qtspeech5-speechd-plugin \<br />
qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-dev<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks''<br />
sudo luarocks install lcf<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''2. obtaining the source code'''<br />
<br />
If you're compiling Mudlet from source for everyday use with few more features that are not present in official AppImage, it is strongly advised that you obtain and compile the source code latest ''stable'' release of Mudlet. At the moment of writing this article, current stable version is 4.10.1, you'll need to adjust version number if new release comes out at later date.<br />
mkdir build && cd build<br />
wget https://www.mudlet.org/wp-content/files/Mudlet-4.10.1.tar.xz<br />
tar xvf Mudlet-4.10.1.tar.xz<br />
cd src<br />
<br />
However, if you're feeling adventurous and wish to play with the latest development code, you can obtain it directly from Mudlet's Git repository:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
mkdir Mudlet/build<br />
cd Mudlet/build<br />
<br />
'''3. compiling the code'''<br />
<br />
There below are two ways to build with qmake, the first is for general use, the second is for developers:<br />
qmake ../src/mudlet.pro<br />
'''*OR*'''<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''Now finish compiling:'''<br />
make -j `nproc`<br />
<br />
4. '''installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
5. '''optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo apt install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.<br />
Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
6. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybidings (Numpad may not work as expected).<br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
7. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
===Ubuntu 20.10===<br />
Following instructions will work on Ubuntu 20.10 as well as all it's flavours and derivatives (such as KDE Neon, for example)<br />
Important thing is to have ''Universe'' repository enabled in your package manager.<br />
<br />
1. '''necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo apt install qtcreator build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev libzip-dev libboost-dev libboost-all-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev lua5.1 libqt5opengl5-dev libglu1-mesa-dev mesa-common-dev libglib2.0-dev libgstreamer1.0-dev qt5keychain-dev libsecret-1-dev libqt5texttospeech5-dev qtspeech5-flite-plugin qtspeech5-speechd-plugin<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks'' <br />
sudo luarocks install lcf<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
2. '''obtaining the source code'''<br />
<br />
If you're compiling Mudlet from source for everyday use with few more features that are not present in official AppImage, it is strongly advised that you obtain and compile the source code latest ''stable'' release of Mudlet. At the moment of writing this article, current stable version is 4.10.1, you'll need to adjust version number if new release comes out at later date.<br />
mkdir build && cd build<br />
wget https://www.mudlet.org/wp-content/files/Mudlet-4.10.1.tar.xz<br />
tar xvf Mudlet-4.10.1.tar.xz<br />
cd src<br />
<br />
However, if you're feeling adventurous and wish to play with the latest development code, you can obtain it directly from Mudlet's Git repository:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
cd Mudlet/src/<br />
<br />
3. '''compiling the code'''<br />
<br />
Following commands will configure the code to install Mudlet on a system level and compile it.<br />
If you wish to install it somewhere else, you may adjust both paths in following command to point to desired destination before compiling it with make. (Rest of this guide will assume you're installing on a system level)<br />
WITH_FONTS=NO WITH_OWN_QTKEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share qmake PREFIX=/usr<br />
make -j `nproc`<br />
<br />
4. '''compiling on Ubuntu for Raspberry Pi'''<br />
<br />
Ubuntu for Raspberry Pi is essentially the same as Ubuntu for regular PC, however, due to sketchy state of OpenGL drivers on RPi 4, you'll likely need to disable Mudlet's 3D Mapper or code will just not compile. Adjusted commands are:<br />
WITH_3DMAPPER=NO WITH_FONTS=NO WITH_OWN_QTKEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share qmake PREFIX=/usr<br />
make<br />
<br />
5. '''installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
6. '''optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo apt install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.<br />
Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
7. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybidings (Numpad may not work as expected). <br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
8. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
===Ubuntu 18.04 setup===<br />
<br />
For Ubuntu 18.04 see the instructions for [[#Compiling_on_Debian_9_.27Stretch.27|Compiling on Debian 9 'Stretch']] (tested working perfectly).<br />
<br />
<br />
'''1. Ubuntu 18.04 setup'''<br />
<br />
If you're on Ubuntu 18.04 (Bionic Beaver), install the following. If you're on a newer Ubuntu, skip this step and go to ''2. Install dependencies''.<br />
<br />
sudo add-apt-repository ppa:beineri/opt-qt-5.12.3-bionic<br />
sudo apt update<br />
sudo apt install qt512-meta-full qt512creator<br />
source /opt/qt512/bin/qt512-env.sh<br />
<br />
'''2. Install dependencies'''<br />
<br />
sudo apt install git build-essential qt5-default qtmultimedia5-dev qttools5-dev \<br />
lua5.1 liblua5.1-0-dev libpcre3-dev libboost-dev zlib1g-dev cmake \<br />
libhunspell-dev lua-rex-pcre lua-sql-sqlite3 lua-filesystem lua-zip libyajl-dev \<br />
libzip-dev libgstreamer0.10-0 libglu1-mesa-dev ccache libpugixml-dev \<br />
mesa-common-dev qtcreator libpulse-dev libglib2.0-dev luarocks libboost-all-dev \<br />
libsecret-1-dev<br />
sudo apt install gstreamer0.10-fluendo-mp3 # may not work on newer Ubuntu<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''3. Get Mudlet source'''<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''4. Create a build directory'''<br />
<br />
cd mudlet<br />
mkdir build<br />
cd build<br />
<br />
'''5. Run the following commands, depending on which build system you want to use '''<br />
<br />
'''EITHER:'''<br />
<br />
cmake ..<br />
<br />
'''OR:'''<br />
<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''THEN:'''<br />
<br />
make -j `nproc`<br />
<br />
'''5. Start the application you have just compiled - enjoy'''<br />
<br />
cd src<br />
./mudlet<br />
<br />
== Compiling on Chrome OS ==<br />
<br />
These instructions will get you setup compiling on Chrome OS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Install dependencies'''<br />
<br />
sudo apt install git build-essential qt5-default qtmultimedia5-dev qttools5-dev \<br />
lua5.1 liblua5.1-0-dev libpcre3-dev libboost-dev zlib1g-dev cmake \<br />
libhunspell-dev lua-rex-pcre lua-sql-sqlite3 lua-filesystem lua-zip libyajl-dev \<br />
libzip-dev libglu1-mesa-dev ccache libpugixml-dev mesa-common-dev qtcreator \<br />
libpulse-dev libglib2.0-dev luarocks libboost-all-dev libsecret-1-dev \<br />
ninja-build libsecret-1-dev<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''3. Get Mudlet source'''<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''4. Create a build directory'''<br />
<br />
cd mudlet<br />
mkdir build && cd build<br />
<br />
'''5. Run the following command '''<br />
<br />
cmake .. -G Ninja<br />
<br />
'''then:'''<br />
<br />
ninja<br />
<br />
'''5. Start the application you have just compiled - enjoy'''<br />
<br />
src/mudlet<br />
{{Note}}Did <code>ninja</code> fail with <code>c++: fatal error: Killed signal terminated program cclplus</code>? Try again with <code>ninja -j 2</code><br />
<br />
== Compiling on macOS ==<br />
<br />
These instructions will get you setup compiling on macOS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums] otherwise.<br />
<br />
<br />
'''1. Install prerequisites'''<br />
<br />
Install [https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12 XCode], command line tools for XCode, and [http://brew.sh HomeBrew].<br />
<br />
Once everything is installed, do:<br />
<br />
brew doctor<br />
brew update<br />
brew install git<br />
<br />
'''2. Get Mudlet source'''<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git <br />
<br />
'''3. Go to the parent of the mudlet "src" folder and create (if necessary) a build subdirectory (this is so that we can build out of source which keeps the source code clean)'''<br />
cd Mudlet && mkdir build<br />
<br />
'''3. Setup your environment'''<br />
./CI/travis.osx.before_install.sh<br />
./CI/travis.osx.install.sh<br />
<br />
luarocks config lua_version 5.1<br />
eval `luarocks path --lua-version=5.1`<br />
For the following, one may have to add <code>''_DIR="/opt/homebrew/"''</code> such as <code>PCRE_DIR="/opt/homebrew/"</code> or <code>ZIP_DIR="/opt/homebrew/"</code> if the installation could not find header files.<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lrexlib-pcre<br />
brew install sqlite<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luasql-sqlite3 SQLITE_DIR=`brew --prefix sqlite` <br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luautf8<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lua-yajl<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luafilesystem<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lua-zip<br />
<br />
brew install p7zip<br />
export BOOST_ROOT="$(pwd)/../Mudlet/3rdparty/boost"<br />
export BOOST_URL="https://sourceforge.net/projects/boost/files/boost/1.72.0/boost_1_72_0.tar.bz2/download"<br />
mkdir -p $BOOST_ROOT<br />
curl --progress-bar --location --output $BOOST_ROOT/download.tar.bz2 $BOOST_URL<br />
7z -o$BOOST_ROOT x $BOOST_ROOT/download.tar.bz2 -y -bd<br />
7z -o$BOOST_ROOT x $BOOST_ROOT/download.tar -y -bd<br />
cd $BOOST_ROOT && cp -r boost_*/* .<br />
rm -rf boost_*/* download.tar.bz2 download.tar<br />
OK to answer yes to delete files if prompted for the <code>rm</code> command above.<br />
<br />
'''4. Run the following commands'''<br />
<br />
cd ../../build<br />
cmake ../../Mudlet -DCMAKE_PREFIX_PATH=`brew --prefix qt5`<br />
make -j `sysctl -n hw.ncpu`<br />
<br />
<br />
'''5. Enjoy'''<br />
<br />
The mudlet.app is now available in <code>src/</code> for launching:<br />
<br />
open src/Mudlet.app<br />
<br />
'''6. Qt Creator setup'''<br />
<br />
No Lua installation is found, despite it existing on your system? Launch Qt Creator by doing <code>open /Applications/Qt Creator.app</code> (location depends on how you installed it).<br />
<br />
Receiving a <code>No rule to make target ... libQt5UiTools_debug.a</code> error? A workaround is to [https://bugreports.qt.io/browse/QTBUG-81251?focusedCommentId=538705&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-538705 symlink a file].<br />
<br />
Mudlet in Qt Creator is not launching due to <code>dyld: Symbol not found: __cg_jpeg_resync_to_restart</code>? See [https://stackoverflow.com/a/44851430/72944 here] for a workaround.<br />
<br />
== Compiling on Debian 'Sid' ==<br />
<br />
'''1. Install required packages from main repo.'''<br />
<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev<br />
<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''2. Grab latest Mudlet source.'''<br />
<br />
mkdir ~/projects && cd ~/projects && git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''3. Build Mudlet.'''<br />
<br />
cd ~/projects/mudlet/src<br />
<br />
qmake<br />
<br />
make<br />
<br />
sudo make install<br />
<br />
== Compiling on Debian 11 'Bullseye' ==<br />
<br />
'''1. Install required packages.'''<br />
<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-dev \<br />
qttools5-dev luarocks ccache libpugixml-dev libqt5texttospeech5-dev qtspeech5-flite-plugin \<br />
qtspeech5-speechd-plugin libqt5opengl5-dev ninja-build cmake libsecret-1-dev<br />
<br />
sudo luarocks install luautf8 <br />
sudo luarocks install lua-yajl<br />
<br />
'''2. Get Mudlet source.'''<br />
<br />
mkdir ~/source && cd ~/source<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git<br />
<br />
Note: the line above will check out `development` branch source code, and this might not always be stable. You can check out the latest release source code using this command:<br />
<br />
git clone --recursive --branch main https://github.com/Mudlet/Mudlet.git<br />
<br />
'''3. Build Mudlet.'''<br />
<br />
mkdir ~/source/Mudlet/build && cd ~/source/Mudlet/build<br />
<br />
qmake ../src/mudlet.pro<br />
<br />
make -j `nproc`<br />
<br />
sudo make install<br />
<br />
After these steps you can run Mudlet by typing:<br />
<br />
mudlet<br />
<br />
== Compiling on Raspberry Pi OS ==<br />
<br />
These instructions will get you compiling and running Mudlet on Raspberry Pi OS (Buster). Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
''' 1.a Install apt dependencies '''<br />
<br />
sudo apt-get update<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-graph-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev cmake<br />
<br />
<br />
[[File:Apt-get-install-y-n.png|center|thumb|installing apt dependencies]]<br />
<br />
''' 1.b Install luarocks dependencies '''<br />
<br />
sudo luarocks install luautf8 <br />
sudo luarocks install lua-yajl YAJL_LIBDIR=`find /usr -name "libyajl.so" -printf '%h\n'` YAJL_INCDIR=/usr/include<br />
<br />
<br />
[[File:After-luarocks-dependencies.png|center|thumb|after luarocks dependencies]]<br />
<br />
''' 2. Get Mudlet source '''<br />
<br />
mkdir ~/source && cd ~/source <br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
<br />
[[File:After-get-mudlet-source.png|center|thumb|After cloning]]<br />
<br />
''' 3. Create a build directory '''<br />
<br />
cd Mudlet && mkdir build && cd build<br />
<br />
''' 4. Run the following commands to build '''<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake ../src/mudlet.pro<br />
<br />
:If you get a response along the lines of:<br />
<br />
qmake: could not find a Qt installation of ''<br />
<br />
:then you likely have ''qtchooser'' present in your system that allows for both Qt4 and Qt5 (or more than one Qt5 version) and it modifiers qmake and some other Qt development programs to take an additional argument to specify which version to use. In that case you should use:<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake -qt=qt5 ../src/mudlet.pro<br />
<br />
[[File:After-qmake.png|center|thumb|After qmake]]<br />
<br />
''' THEN: '''<br />
:For the fastest compile time while still being able to use the system at all (~35min on a RPi4 with 4GB of ram)<br />
make -j $(expr `nproc` - 1)<br />
<br />
''' OR: '''<br />
<br />
:Use this if you have an older Raspberry Pi. Be prepared for it to take a while (over an hour) - ''it is not recommended to try to more than one compilation task at a time on the older systems with the '''-j''' option as they will only have a system memory with enough space for one of some of those tasks'':<br />
make<br />
<br />
[[File:Success.png|center|thumb|Success!]]<br />
<br />
''' 4. Install the application you have just compiled '''<br />
<br />
sudo make install<br />
<br />
[[File:Installed.png|center|thumb|Installed now]]<br />
<br />
''' 5. Enjoy! '''<br />
<br />
# mudlet is in the path, can just run it<br />
mudlet<br />
<br />
== Compiling on ArchLinux ==<br />
<br />
Mudlet is available in the [https://aur.archlinux.org Arch User Repository]. <br />
<br />
To install it use your favourite AUR helper (helper tool will automatically resove dependancies); example using ''yay'' :<br />
yay -S mudlet<br />
<br />
For more info on this process, visit [https://wiki.archlinux.org/index.php/Arch_User_Repository Arch User Repository - ArchWiki].<br />
<br />
''Note: For the most recent development version of Mudlet, replace 'mudlet' with 'mudlet-git' in the above commands and proceed as described.''<br />
<br />
''Built in fonts have been disabled, but are available in packages listed as optional dependancies.''<br />
<br />
''Discord support in Mudlet depends on an extrenal library provided by discord-rpc-api, which is also available in AUR, choose whichever variant suits you best.''<br />
<br />
== Compiling on Gentoo ==<br />
An [https://github.com/toaster/gentoo-overlay overlay containing Mudlet is available] for compiling Mudlet on Gentoo.<br />
<br />
== Compiling on Windows ==<br />
<br />
These instructions will get you setup compiling on Windows. <br />
<br />
Need a hand? Join us on the Mudlet [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Download Mudlet source code'''<br />
<br />
# Install [https://desktop.github.com/ Github Desktop].<br />
# Clone ([https://help.github.com/desktop/guides/contributing-to-projects/cloning-a-repository-from-github-to-github-desktop/#platform-windows instructions]) Mudlet's [https://github.com/mudlet/mudlet repository] to your local drive.<br />
{{note}} You must use a location on <code>C:\</code> without any spaces in folder names! <br />
<br />
'''2. Perform a one-time setup'''<br />
<br />
Right-click on <code>setup-windows-sdk.ps1</code> and select <code>Run with PowerShell</code>. This will automatically download all of the requires tools (including Python 2) and libraries, set them up for you, build Mudlet, and launch it! If this script exits immediately, please [https://docs.microsoft.com/en-us/powershell/scripting/windows-powershell/install/installing-windows-powershell?view=powershell-7.1#upgrading-existing-windows-powershell upgrade your PowerShell version] first.<br />
<br />
{{note}} Depending on your Internet connection and computer speed, this one-time setup will take 30 minutes or more - so grab a cup of tea or coffee.<br />
<br />
[[File:Start-of-installation.gif|frame|none|Sometimes the output will get stuck and not progress - just press Enter to make it continue. This is a well-known [https://serverfault.com/questions/204150/sometimes-powershell-stops-sending-output-until-i-press-enter-why Powershell bug.]]]<br />
<br />
During the installation, you'll see the Qt installer window pop-up - this is normal:<br />
<br />
[[File:Qt-installer.gif|thumb|none]]<br />
<br />
The Qt installer might ask you about your data collection preferences - answer as you wish and the automated install will continue:<br />
<br />
[[File:Qt-installer-data-collection.png|thumb|none]]<br />
<br />
The installer's final step will be compiling all of the source code, which looks like this:<br />
<br />
[[File:Compiling-step.gif|thumb|none]]<br />
<br />
After it's all done, a Mudlet version ending in "-dev" will launch automatically:<br />
<br />
[[File:Mudlet-launching.gif|frame|none]]<br />
<br />
If something didn't work right, you can check out the verbose log that is available at <code>C:\src\verbose_output.log</code>.<br />
<br />
=== Coding on Mudlet ===<br />
<br />
Open <code>C:\<path to repository>\src\mudlet.pro</code> in Qt Creator, which resides here: <code>C:\Qt\Tools\QtCreator\bin\qtcreator.exe</code>. Then enable Debug and Release builds and hit ''Configure Project'':<br />
<br />
[[File:Selection_173.png|frame|none]]<br />
<br />
Press <code>Ctrl+5</code> and update project settings. Check how many logical processors are available in your system with the Task Manager:<br />
<br />
[[File:Task-manager.png|thumb|none|2 processors are available in this example]]<br />
<br />
And set this amount in Qt Creator:<br />
<br />
[[File:Change Qt Creator to use many cores.gif|frame|none]]<br />
<br />
Hit run:<br />
<br />
[[File:Selection 176.png|frame|none]]<br />
<br />
Click on '''Compile Output''' to see progress on compiling:<br />
<br />
[[File:Selection 177.png|frame|none]]<br />
<br />
When it's all ready, the new Mudlet with your changes will launch. '''You're all done'''!<br />
<br />
=== Contributing changes ===<br />
<br />
Once you're all done with your changes, contribute them to Mudlet using a [https://help.github.com/desktop/guides/contributing-to-projects/creating-a-pull-request/#platform-windows pull request]. Thanks for improving open-source!<br />
<br />
=== Uninstalling ===<br />
To get rid of everything, remove the following folders:<br />
<br />
C:\Libraries<br />
C:\LuaRocks<br />
C:\MinGW<br />
C:\Python27<br />
C:\Qt<br />
C:\src<br />
<br />
== Compiling on Github Codespaces ==<br />
<br />
Github Codespaces allow you to code and run Mudlet all from the browser - makes it a lot easier to get started. It also allows you to code Mudlet itself from any computer in the world! As for this time Github Codespaces is in a private beta, so make sure to [https://github.com/features/codespaces/signup apply here]. <br />
<br />
'''1. Create a new codespace'''<br />
<br />
Create a new Codespace by going to https://github.com/Mudlet/Mudlet using Google Chrome or Microsoft Edge (Firefox at the time of the writing doesn't have working copy/paste). There, click the green "Code" button, select the "Codespaces" tab and click "New codespace".<br />
<br />
[[File:New codespace.png|alt=New codespace screenshot|frameless]]<br />
<br />
'''2. Wait for it to load'''<br />
<br />
This will take a while (~5min) so grab a tea:<br />
<br />
[[File:Building Visual Studio Codespace.png|frameless]]<br />
<br />
'''3. Connect to the environment'''<br />
<br />
Go to the <code>Ports</code> section at the bottom and change the Port Privacy of the Open Mudlet port to Public:<br />
<br />
[[File:Port privacy in Github Codespaces.png|900x900px]]<br />
<br />
<br />
Then connect to your online Linux desktop with <code>mudlet</code> as the password by clicking on the web icon. <br />
<br />
[[File:Connect to remote machine.png|frameless]]<br />
<br />
<br />
In case it can't connect, make sure the port privacy is set to <code>Public</code>. If it still can't connect, try 4-5 more times - eventually it'll work.<br />
<br />
<br />
<br />
We chose a retro 90's look here to fit with the whole hacking theme, so if you see this you're good 😉<br />
<br />
[[File:Github_codespaces_desktop.png|alt=|frameless|400x400px]]<br />
<br />
'''4. Build Mudlet'''<br />
<br />
In Codespaces, hit <code>F7</code> and select <code>Let CMake guess...</code><br />
<br />
[[File:CMake configuration.png|none]]<br />
<br />
It will then start building Mudlet automatically. Using the [https://docs.github.com/en/free-pro-team@latest/github/developing-online-with-codespaces/about-billing-for-codespaces Basic instance] (only kind available in beta) the first-time build will take ~25min, so take a break here - you've made excellent progress. All follow-up compiles after this will be quicker, by the way.<br />
<br />
[[File:Building Mudlet in codespaces.png|none]]<br />
<br />
'''5. Run Mudlet'''<br />
<br />
[[File:Launch Mudlet.png|none]]<br />
<br />
Hit the little play button at the bottom of the screen, and Mudlet will now launch in the remote connection tab. Not working? [https://discord.gg/kuYvMQ9 We can help]. Otherwise, enjoy!<br />
<br />
[[File:Mudlet running remotely.png |500px]]<br />
<br />
Note: When the codespace is unused for a while, it will disconnect. It'll never disconnect while you're actively using it. See [https://github.com/microsoft/vscode-dev-containers/issues/588 Github issue] for details.<br />
<br />
== Developing with Docker ==<br />
<br />
Docker is a system designed for more reproducible and isolated builds. A docker setup exists and has been tested using Pop OS! 20.04 (which is derived from Ubuntu 20.04). First, follow the instructions to install both [https://docs.docker.com/get-docker/ docker] and [https://docs.docker.com/compose/install/ docker-compose].<br />
<br />
Clone the development branch<br />
<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
cd Mudlet/docker<br />
<br />
Make a local copy of the .env.template file:<br />
<br />
cp .env.template .env<br />
<br />
If you wish to customize things like the number of cores to use for building mudlet, feel free to change the corresponding values in the .env file.<br />
<br />
To run Qt-Creator and develop Mudlet, simply run `docker-compose up dev`.<br />
To run Mudlet, simply run `docker-compose up mudlet`. Note: At the moment, the mudlet build will not persist settings past container rebuilds.<br />
<br />
== Compiling on Windows 7+ (MSYS2 Alternative)==<br />
<br />
''INCOMPLETE, IN PROGRESS''<br />
<br />
Go to http://www.msys2.org/ to download the 64 bit MSYS2 installer (as of 2020/05/24 32 bit hosts - for '''compiling''' software, but ''not'' for using code built with it have been deprecated, the last installer for that 32-bit systems is held at: http://repo.msys2.org/distrib/i686/msys2-i686-20200517.exe) and follow the installation instructions (Steps 1 to 8 on that page), these instructions assume that "C:\msys64" or "C:\msys32" is used depending on the bitness of the system it is being installed on.<br />
<br />
Install the following packages (using "pacman -S ''packageName''"), the ones with a '''-i686-''' in the middle are the ones for 32-bit (i686) targets and '''-x86_64-''' are the ones for 64-bit targets - it is possible to install both for building Mudlet for target PCs of both bitnesses on a 64-bit host, it is not clear whether the reverse is true with a 32-bit host. These will pull in a number of other required packages as well (the ''--needed'' option prevents the re-installation of packages that have already been installed by MSYS2/Mingw-w64's own setup/installation process) - as some of the packages, e.g. ''base-devel'' are actually ''groups'' you will be requested to select which members of that group are actually required, it is easiest to just go with the default which is to install ALL of the packages in that group!<br />
<br />
: For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-i686-toolchain mingw-w64-i686-qt-creator mingw-w64-i686-qt5-multimedia mingw-w64-i686-libzip mingw-w64-i686-pugixml mingw-w64-i686-lua51 mingw-w64-i686-lua51-lpeg mingw-w64-i686-lua51-lsqlite3 mingw-w64-i686-hunspell mingw-w64-i686-boost mingw-w64-i686-yajl mingw-w64-i686-clang mingw-w64-i686-cmake mingw-w64-i686-SDL unzip<br />
</syntaxhighlight><br />
<br />
: For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-x86_64-toolchain mingw-w64-x86_64-qt-creator mingw-w64-x86_64-qt5-multimedia mingw-w64-x86_64-libzip mingw-w64-x86_64-pugixml mingw-w64-x86_64-lua51 mingw-w64-x86_64-lua51-lpeg mingw-w64-x86_64-lua51-lsqlite3 mingw-w64-x86_64-hunspell mingw-w64-x86_64-boost mingw-w64-x86_64-yajl mingw-w64-x86_64-clang mingw-w64-x86_64-cmake mingw-w64-x86_64-SDL unzip<br />
</syntaxhighlight><br />
<br />
::The ''*-zziplib'' libraries are used by the ''luazip'' luarock {from the Kepler project} but Mudlet will work perfectly well with the alternative ''lua-zip'' {from the brimworks GitHub repository - which also provides the ''lua-yajl'' rock} which does not require this library - although it is possible that it might still be pulled into the system as a dependency of another MSYS2 package.<br />
<br />
:Note that this will install the MSYS2 builds of the Qt Libraries and Creator IDE - ''THE ON/OFF-LINE INSTALLER OF THE QT LIBRARIES AND CREATOR VIA DOWNLOADS FROM QT ARE NOT USEFUL IN THIS SETUP!''<br />
<br />
:{| class="wikitable"<br />
|-<br />
|'''Attention - Luarocks packages problem'''<br />
|-<br />
| Recently the Luarocks project attempted to adopt the MSYS2/Mingw-w64 platform as one it would supported natively and the MSYS2/Mingw-w64 project went and upgraded its luarocks packages to make use of the changes and also on-board other improvements (and the version number increased from ''2.4.4-2'' to ''3.5.0-1'') unfortunately this completely broke them and although the issue has been reported ([https://github.com/msys2/MINGW-packages/issues/9037 MSYS2 Issue 9037]) a fix has not yet materialised. The only way to work around this in the meantime is to download the older package (with '''wget''') and install it manually (with '''pacman -U):<br />
|-<br />
|For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:19:09-- https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97905 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-i686-lua51-luarocks-2.4.4-2- 100%[===========================================================================>] 95.61K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:19:10 (1.43 MB/s) - ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97905/97905]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-i686-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-i686-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|-<br />
|For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:17:32-- https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97935 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-x86_64-lua51-luarocks-2.4.4- 100%[===========================================================================>] 95.64K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:17:32 (1.28 MB/s) - ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97935/97935]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-x86_64-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-x86_64-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|}<br />
<br />
::{| class="wikitable"<br />
|-<br />
|'''Warning for those planning to build ''both'' 32 and 64 bit versions'''<br />
|-<br />
|If one is planning to build ''both'' bitness binaries an additional step is necessary as, by default, the MSYS2/Mingw-w64 ''luarocks'' setup seems to place any ''.lua'' or ''.dll'' modules it builds/installs on a per user (the so-called ''local'' basis) into the same directories with the same names. This is no good for two reasons:<br />
* It is difficult to work out which bitness a particular module is for and whilst 32-bit modules ''might'' work in a 64-bit environment the reverse is definitely not the case<br />
* It confuses the Luarocks package management systems (as effectively there will be two different luarocks systems operated side-by-side)<br />
<br />
This can be worked around by:<br />
* Editing the '''.\etc\luarocks\config-5.1.lua''' for each bitness so that the ''rocks_trees'' table entry for the ''user'' key is changed from this in '''both''' files:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks]] },</syntaxhighlight><br />
to something different for each of them, say, for example, for the the 64-bit one:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks-x64]] },</syntaxhighlight><br />
* Then by specifying the ''rocktree'' name ('''user''') on the command line when '''installing''' or '''building''' a luarock with the ''--tree user'' argument - note that for some inexplicable reason the ''--local'' argument that '''''should''''' do the same thing does not seem to work for these two actions, it is not clear whether this is a MSYS2/Mingw-w64 specific issue or it goes further upstream to Luarocks in general. Thus, in the next step it will be necessary to change from using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --local rockname<br />
</syntaxhighlight><br />
to, for the example given:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --tree user rockname<br />
</syntaxhighlight><br />
where ''user'' is the literal string "user" to match the Lua table key in the rock_trees and not, in this case, a representation of the user-name/account of the person performing the action.<br />
|}<br />
<br />
From the Windows ''Start menu'' start a shell appropriate for the target with the bitness to be built for i.e. '''"MSYS2 Mingw 32-Bit"''' or '''"MSYS2 Mingw 64-Bit"'''. This will likely position the current directory to the root directory of the MSYS2 environment, the text about the prompt line (the one with the "$") will contain three different bits of colored text '''username@computername'''; one of '''MSYS2'''/'''MINGW32'''/'''MINGW''' depending on the type of shell you currently in use and '''/''' representing the root directory (which will actually be the directory MSYS2 was installed to, for example on the author's system this is "C:/msys64"). Change to the home directory in MYSY by entering "cd" on its own with no argument (it will show up as '''~''' and it would work out to be, for '''user''' to be '''c:/msys64/home/user''' or '''c:/msys32/home/user''' (if both bitnessess are to be built it will be necessary to repeat the following step twice, one for each and also observe the steps in the above warning) install the following luarocks:<br />
<br />
:{| class="wikitable sortable"<br />
|-<br />
! rockname<br />
|-<br />
| lrexlib-pcre<br />
|-<br />
| lua-yajl<br />
|-<br />
| luafilesystem<br />
|-<br />
| luasql-sqlite3<br />
|-<br />
| luautf8<br />
|-<br />
| luazip or lua-zip<br />
|}<br />
by using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install [--local] rockname<br />
</syntaxhighlight><br />
The ''--local'' argument is an optional one that causes the luarock and the lua module to be installed on a per-user basis rather than on a system wide one, this may be important if the PC is used by multiple users and more than one of them uses Lua in any form.<br />
<br />
Now create somewhere to work on the Mudlet source, assuming that other software coding with other pieces of software will be done, create a sub-directory in the home directory, and then make one just for Mudlet under that:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ mkdir ./src<br />
<br />
MINGW64 user@computer ~<br />
$ mkdir ./src/mudlet<br />
</syntaxhighlight><br />
<br />
Change to that directory and get the source code:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ cd ./src/mudlet<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git clone git://github.com/Mudlet/Mudlet.git .<br />
</syntaxhighlight><br />
<br />
If you are planning to contribute to the Mudlet code you will want to visit Github and create your own GitHub repository, you can then push commits (changes to the code) to there and raise a Pull Request for a Mudlet Maker to drag the changes over to the above repository. You will want to add your repository and perhaps those of some other contributors so you can track what they are doing and see/try/experiment with their PRs before they get merged. Therefore you will want to add some other repositories into the mix. The names you use to identify those other repositories will show up in any utility that works with the repository you have just created in the above "clone" operation and can be anything you like but it makes sense to have clear names. So to add "myName", and those of the leading active contributors to the Mudlet codebase you will use:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Mine https://github.com/myName/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Vadim https://github.com/vadi2/Mudlet.git <br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add SlySven https://github.com/SlySven/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Kebap https://github.com/Kebap/Mudlet.git<br />
</syntaxhighlight><br />
<br />
Now obtain ''all'' the versions of the code with:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git fetch --all<br />
</syntaxhighlight><br />
<br />
This will produce a lot of lines of output the first time and it might take a little while on a slow connection...<br />
<br />
{Section missing - it turns out that the default GUI git tools that the author of this section would normally use: "gitk" and "git gui" have some problems in the versions currently supplied from the MSYS2 system - and it was necessary to import them from the set that the Git4Win have patched - see https://github.com/git-for-windows/git/wiki/Install-inside-MSYS2-proper }<br />
<br />
Some modifications to the qmake/cmake project files are needed and these are now supported in the main ''development'' branch in the upstream {the Mudlet organisation's own GitHub repository} which requires that there is an environmental variable '''WITH_MAIN_BUILD_SYSTEM''' and it is set to the (case-insensitive) value '''NO''':<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export WITH_MAIN_BUILD_SYSTEM=NO<br />
</syntaxhighlight><br />
<br />
Also the '''MINGW_BASE_DIR''' environmental variable will need to be set to the root directory for the MINGW-W64 installation for the appropriate bitness of the target to be made. For building on a 64-Bit Host {the PC that is ''compiling'' the code} to make a 64-Bit application this will likely be '''C:/msys64/mingw64''' and for a 32-Bit application it will probably be '''C:/msys64/ming32'''.<br />
: E.g. <syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw64 # To build a 64-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
: Or: <syntaxhighlight lang="shell"><br />
MINGW32 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw32 # To build a 32-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
Now checkout a branch {ideally, if working on solving a new issue, or adding a feature or resolving a bug, one should create a new branch that is a copy of the current, upstream ''development'' branch} and then work on it with Qt Creator:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ qtcreator &<br />
</syntaxhighlight><br />
<br />
Load in the '''mudlet.pro''' ''qmake'' project file in the '''src''' subdirectory (e.g. for this example: '''c:/msys64/home/user/src/mudlet/src/mudlet.pro''') and get hacking...<br />
<br />
= Setting up IDEs =<br />
== CLion ==<br />
=== Qt not detected ===<br />
If you'd like to use CLion and it is giving the following error:<br />
<br />
<nowiki><br />
By not providing "FindQt5Core.cmake" in CMAKE_MODULE_PATH this project has<br />
asked CMake to find a package configuration file provided by "Qt5Core", but<br />
CMake did not find one.<br />
<br />
...<br />
</nowiki><br />
<br />
You can fix this by setting <code>-DCMAKE_PREFIX_PATH=<your Qt + version + compiler location></code>. For example: <code>-DCMAKE_PREFIX_PATH=/media/vadi/SSDer/Programs/Qt/5.15.2/gcc_64/</code> [[File:CLion CMake settings - finidng Qt.png|700px|none]]<br />
<br />
=== CLion setup on Windows ===<br />
After running <code>setup-windows-sdk.ps1</code> make sure to set Cmake options to:<br />
-DCMAKE_PREFIX_PATH=C:\Qt\Tools\mingw730_32;C:\Qt\5.14.2\mingw73_32 -DBoost_INCLUDE_DIR=C:\Libraries\boost_1_71_0<br />
''Directories might vary slightly, when different Qt, Boost or MinGW version will be used.''<br />
<br />
[[File:Clion Settings - Cmake.png|frameless|700x700px]]<br />
<br />
<br />
<br />
You will need 32 bit version of MinGW. Set it in the <code>Toolset</code> field to:<br />
C:\Qt\Tools\mingw730_32<br />
<br />
''Directory may be slightly different if MinGW version used will change.''<br />
<br />
[[File:Toolchain.png|frameless|700x700px]]<br />
<br />
=== Clang Tidy ===<br />
Ensure that CLion is set to run the project's [https://www.jetbrains.com/help/clion/clang-tidy-checks-support.html#paticularcheck .clang-tidy checks] with the <code>Prefer .clang-tidy files over IDE settings</code> option:<br />
<br />
[[File:Clang Tidy CLIon.png|700px|none]]<br />
<br />
This helps us catch any issues just a bit earlier.<br />
<br />
=== Clang Format ===<br />
Ensure that [https://www.jetbrains.com/help/clion/clangformat-as-alternative-formatter.html#clion-support CLion is set to use] the <code>.clang-format</code> formatting style:<br />
<br />
[[File:Clang-format CLion.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
== Visual Studio Code ==<br />
<br />
To set the path in Visual Studio Code, open settings, search for <code>cmake environment</code> and set the <code>CMAKE_PREFIX_PATH</code> to your path, such as <code>/media/vadi/SSDer/Programs/Qt/5.14.1/gcc_64/</code>:<br />
<br />
[[File:CMake path in Visual Studio Code.png|none]]<br />
<br />
===Clang Tidy===<br />
clang-tidy catches common programming issues, run it by selecting 'Analysis' from the command palette (Ctrl+Shift+P by default):<br />
<br />
[[File:Clang-tidy in vscode.png|none]]<br />
<br />
It is also possible [https://devblogs.microsoft.com/cppblog/visual-studio-code-c-december-2021-update-clang-tidy/ check status of analysis and cancel if needed].<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in VSCode, set the <code>cmake.configureSettings</code> variable:<br />
<br />
[[File:Cmake.configureSettings option in vscode.png|frameless|890x890px]]<br />
<br />
[[File:Choosing which sanitizers in vscode to use.png|frameless|891x891px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
== Qt Creator==<br />
===Clang Tidy and Clazy===<br />
<br />
Configure Mudlet-specific checks for [https://clang.llvm.org/extra/clang-tidy/ clang-tidy] and [https://github.com/KDE/clazy clazy] tools help catch any issues early on. See [https://doc.qt.io/qtcreator/creator-clang-tools.html Qt Creator's instructions] for setting this up - clang-tidy can use the <code>.clang-tidy</code> file that's available at the root of the repository, and for clazy enable <code>level0</code> and <code>level1</code> checks.<br />
<br />
[[File:Clang tidy configuration.png|frame|none]]<br />
[[File:Clazy configuration.png|frame|none]]<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in Qt creator, head to <code>Projects</code> - <code>Build</code>: <br />
<br />
[[File:Sanitisers in qt creator.png|frameless|890x890px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
==Clang Format==<br />
Ensure that Qt Creator is set to use the <code>.clang-format</code> formatting style in the C++ settings. Turn on <code>Format instead of indenting</code> for <code>Ctrl+I</code> to format code, and ensure <code>Override Clang Format configuration file</code> is disabled:<br />
<br />
[[File:Qt Creator clang format.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
<br />
=Building with multiple versions of Lua=<br />
Mudlet uses Lua 5.1 only, so if you are compiling on a system that also has later versions installed, you might get the following error: <code>‘LUA_GLOBALSINDEX’ was not declared in this scope</code>.<br />
<br />
To fix this, pass the path to Lua headers explicitly. For CMake: <code>-DLUA_INCLUDE_DIR=/usr/include/lua5.1</code> (adjust as needed).</div>Demonnichttps://wiki.mudlet.org/index.php?title=Compiling_Mudlet&diff=20079Compiling Mudlet2022-08-11T22:11:50Z<p>Demonnic: /* Compiling on Raspberry Pi OS */</p>
<hr />
<div>{{TOC right}}<br />
<br />
If you just want to use Mudlet, you can skip these steps, and use one of the already ready (pre-compiled) installers [https://www.mudlet.org/download ready for download].<br />
<br />
Otherwise, hop in for new adventure! <br />
<br />
[[File:Easy Mudlet code understanding.png|frame|none]]<br />
<br />
= Key contributing information =<br />
<br />
Clang format is used to automatically format code submissions using the [https://github.com/Mudlet/Mudlet/blob/development/src/.clang-format src/.clang-format] style. [http://doc.qt.io/qtcreator/creator-beautifier.html See here] how to enable clang-format with Qt Creator - and make sure to specify the 'File' option for the configuration style.<br />
<br />
Branches:<br />
<br />
'''development''' is the development branch where new features can go.<br />
<br />
Workflow:<br />
<br />
Fork and submit a PR with your changes ([https://guides.github.com/activities/forking/ Github tutorial]).<br />
<br />
Here is a list of package versions delivered with different Linux distros. You may want to upgrade these: <br />
https://repology.org/project/mudlet/versions<br />
<br />
= Compiling =<br />
<br />
== Compiling on Ubuntu ==<br />
<br />
These instructions will get you setup compiling on Ubuntu. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
===Ubuntu 21.10===<br />
Following instructions will work on Ubuntu 21.10 as well as all it's flavours and derivatives (such as KDE Neon, for example)<br />
Important thing is to have ''Universe'' repository enabled in your package manager. (on Ubuntu you will have all the repositories that you need already enabled by default.)<br />
<br />
'''1. necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo apt install ubuntu-restricted-extras qtcreator build-essential git zlib1g-dev libhunspell-dev \<br />
libpcre3-dev libzip-dev libboost-dev libboost-all-dev libyajl-dev libpulse-dev libpugixml-dev \<br />
liblua5.1-0-dev lua-filesystem lua-zip lua-sql-sqlite3 luarocks ccache lua-rex-pcre lua5.1 \<br />
libglu1-mesa-dev mesa-common-dev libglib2.0-dev libgstreamer1.0-dev libqt5opengl5-dev \<br />
qtmultimedia5-dev qttools5-dev qt5keychain-dev libsecret-1-dev \<br />
libqt5texttospeech5-dev qtspeech5-flite-plugin qtspeech5-speechd-plugin \<br />
qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-dev<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks''<br />
sudo luarocks install lcf<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''2. obtaining the source code'''<br />
<br />
If you're compiling Mudlet from source for everyday use with few more features that are not present in official AppImage, it is strongly advised that you obtain and compile the source code latest ''stable'' release of Mudlet. At the moment of writing this article, current stable version is 4.10.1, you'll need to adjust version number if new release comes out at later date.<br />
mkdir build && cd build<br />
wget https://www.mudlet.org/wp-content/files/Mudlet-4.10.1.tar.xz<br />
tar xvf Mudlet-4.10.1.tar.xz<br />
cd src<br />
<br />
However, if you're feeling adventurous and wish to play with the latest development code, you can obtain it directly from Mudlet's Git repository:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
mkdir Mudlet/build<br />
cd Mudlet/build<br />
<br />
'''3. compiling the code'''<br />
<br />
There below are two ways to build with qmake, the first is for general use, the second is for developers:<br />
qmake ../src/mudlet.pro<br />
'''*OR*'''<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''Now finish compiling:'''<br />
make -j `nproc`<br />
<br />
4. '''installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
5. '''optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo apt install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.<br />
Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
6. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybidings (Numpad may not work as expected).<br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
7. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
===Ubuntu 20.10===<br />
Following instructions will work on Ubuntu 20.10 as well as all it's flavours and derivatives (such as KDE Neon, for example)<br />
Important thing is to have ''Universe'' repository enabled in your package manager.<br />
<br />
1. '''necessary dependencies'''<br />
<br />
Majority of required dependencies can be obtained from repositories, and can be installed with following command:<br />
<br />
sudo apt install qtcreator build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev libzip-dev libboost-dev libboost-all-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev lua5.1 libqt5opengl5-dev libglu1-mesa-dev mesa-common-dev libglib2.0-dev libgstreamer1.0-dev qt5keychain-dev libsecret-1-dev libqt5texttospeech5-dev qtspeech5-flite-plugin qtspeech5-speechd-plugin<br />
<br />
Few of required Lua modules are not available in official repositories, so they have to be installed using ''luarocks'' <br />
sudo luarocks install lcf<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
2. '''obtaining the source code'''<br />
<br />
If you're compiling Mudlet from source for everyday use with few more features that are not present in official AppImage, it is strongly advised that you obtain and compile the source code latest ''stable'' release of Mudlet. At the moment of writing this article, current stable version is 4.10.1, you'll need to adjust version number if new release comes out at later date.<br />
mkdir build && cd build<br />
wget https://www.mudlet.org/wp-content/files/Mudlet-4.10.1.tar.xz<br />
tar xvf Mudlet-4.10.1.tar.xz<br />
cd src<br />
<br />
However, if you're feeling adventurous and wish to play with the latest development code, you can obtain it directly from Mudlet's Git repository:<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
cd Mudlet/src/<br />
<br />
3. '''compiling the code'''<br />
<br />
Following commands will configure the code to install Mudlet on a system level and compile it.<br />
If you wish to install it somewhere else, you may adjust both paths in following command to point to desired destination before compiling it with make. (Rest of this guide will assume you're installing on a system level)<br />
WITH_FONTS=NO WITH_OWN_QTKEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share qmake PREFIX=/usr<br />
make -j `nproc`<br />
<br />
4. '''compiling on Ubuntu for Raspberry Pi'''<br />
<br />
Ubuntu for Raspberry Pi is essentially the same as Ubuntu for regular PC, however, due to sketchy state of OpenGL drivers on RPi 4, you'll likely need to disable Mudlet's 3D Mapper or code will just not compile. Adjusted commands are:<br />
WITH_3DMAPPER=NO WITH_FONTS=NO WITH_OWN_QTKEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share qmake PREFIX=/usr<br />
make<br />
<br />
5. '''installing compiled code'''<br />
<br />
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.<br />
sudo make install<br />
sudo cp ../mudlet.png /usr/share/pixmaps<br />
sudo cp ../mudlet.desktop /usr/share/applications<br />
<br />
6. '''optional additional software'''<br />
<br />
One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage.<br />
Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself.<br />
However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).<br />
sudo apt install qt5ct<br />
will install a tool for configuration of look and feel of Qt programs inside those desktop environments.<br />
Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.<br />
<br />
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.<br />
<br />
7. '''Mudlet on Wayland'''<br />
<br />
Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybidings (Numpad may not work as expected). <br />
Until that is resolved you may wish to start mudlet with:<br />
QT_QPA_PLATFORM=xcb mudlet<br />
(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)<br />
<br />
8. '''uninstallation'''<br />
<br />
You can reverse the process described in this guide with following command:<br />
<br />
sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png<br />
<br />
===Ubuntu 18.04 setup===<br />
<br />
For Ubuntu 18.04 see the instructions for [[#Compiling_on_Debian_9_.27Stretch.27|Compiling on Debian 9 'Stretch']] (tested working perfectly).<br />
<br />
<br />
'''1. Ubuntu 18.04 setup'''<br />
<br />
If you're on Ubuntu 18.04 (Bionic Beaver), install the following. If you're on a newer Ubuntu, skip this step and go to ''2. Install dependencies''.<br />
<br />
sudo add-apt-repository ppa:beineri/opt-qt-5.12.3-bionic<br />
sudo apt update<br />
sudo apt install qt512-meta-full qt512creator<br />
source /opt/qt512/bin/qt512-env.sh<br />
<br />
'''2. Install dependencies'''<br />
<br />
sudo apt install git build-essential qt5-default qtmultimedia5-dev qttools5-dev \<br />
lua5.1 liblua5.1-0-dev libpcre3-dev libboost-dev zlib1g-dev cmake \<br />
libhunspell-dev lua-rex-pcre lua-sql-sqlite3 lua-filesystem lua-zip libyajl-dev \<br />
libzip-dev libgstreamer0.10-0 libglu1-mesa-dev ccache libpugixml-dev \<br />
mesa-common-dev qtcreator libpulse-dev libglib2.0-dev luarocks libboost-all-dev \<br />
libsecret-1-dev<br />
sudo apt install gstreamer0.10-fluendo-mp3 # may not work on newer Ubuntu<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''3. Get Mudlet source'''<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''4. Create a build directory'''<br />
<br />
cd mudlet<br />
mkdir build<br />
cd build<br />
<br />
'''5. Run the following commands, depending on which build system you want to use '''<br />
<br />
'''EITHER:'''<br />
<br />
cmake ..<br />
<br />
'''OR:'''<br />
<br />
qmake CONFIG+=debug ../src/mudlet.pro<br />
<br />
'''THEN:'''<br />
<br />
make -j `nproc`<br />
<br />
'''5. Start the application you have just compiled - enjoy'''<br />
<br />
cd src<br />
./mudlet<br />
<br />
== Compiling on Chrome OS ==<br />
<br />
These instructions will get you setup compiling on Chrome OS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Install dependencies'''<br />
<br />
sudo apt install git build-essential qt5-default qtmultimedia5-dev qttools5-dev \<br />
lua5.1 liblua5.1-0-dev libpcre3-dev libboost-dev zlib1g-dev cmake \<br />
libhunspell-dev lua-rex-pcre lua-sql-sqlite3 lua-filesystem lua-zip libyajl-dev \<br />
libzip-dev libglu1-mesa-dev ccache libpugixml-dev mesa-common-dev qtcreator \<br />
libpulse-dev libglib2.0-dev luarocks libboost-all-dev libsecret-1-dev \<br />
ninja-build libsecret-1-dev<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''3. Get Mudlet source'''<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''4. Create a build directory'''<br />
<br />
cd mudlet<br />
mkdir build && cd build<br />
<br />
'''5. Run the following command '''<br />
<br />
cmake .. -G Ninja<br />
<br />
'''then:'''<br />
<br />
ninja<br />
<br />
'''5. Start the application you have just compiled - enjoy'''<br />
<br />
src/mudlet<br />
{{Note}}Did <code>ninja</code> fail with <code>c++: fatal error: Killed signal terminated program cclplus</code>? Try again with <code>ninja -j 2</code><br />
<br />
== Compiling on macOS ==<br />
<br />
These instructions will get you setup compiling on macOS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums] otherwise.<br />
<br />
<br />
'''1. Install prerequisites'''<br />
<br />
Install [https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12 XCode], command line tools for XCode, and [http://brew.sh HomeBrew].<br />
<br />
Once everything is installed, do:<br />
<br />
brew doctor<br />
brew update<br />
brew install git<br />
<br />
'''2. Get Mudlet source'''<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git <br />
<br />
'''3. Go to the parent of the mudlet "src" folder and create (if necessary) a build subdirectory (this is so that we can build out of source which keeps the source code clean)'''<br />
cd Mudlet && mkdir build<br />
<br />
'''3. Setup your environment'''<br />
./CI/travis.osx.before_install.sh<br />
./CI/travis.osx.install.sh<br />
<br />
luarocks config lua_version 5.1<br />
eval `luarocks path --lua-version=5.1`<br />
For the following, one may have to add <code>''_DIR="/opt/homebrew/"''</code> such as <code>PCRE_DIR="/opt/homebrew/"</code> or <code>ZIP_DIR="/opt/homebrew/"</code> if the installation could not find header files.<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lrexlib-pcre<br />
brew install sqlite<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luasql-sqlite3 SQLITE_DIR=`brew --prefix sqlite` <br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luautf8<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lua-yajl<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luafilesystem<br />
luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lua-zip<br />
<br />
brew install p7zip<br />
export BOOST_ROOT="$(pwd)/../Mudlet/3rdparty/boost"<br />
export BOOST_URL="https://sourceforge.net/projects/boost/files/boost/1.72.0/boost_1_72_0.tar.bz2/download"<br />
mkdir -p $BOOST_ROOT<br />
curl --progress-bar --location --output $BOOST_ROOT/download.tar.bz2 $BOOST_URL<br />
7z -o$BOOST_ROOT x $BOOST_ROOT/download.tar.bz2 -y -bd<br />
7z -o$BOOST_ROOT x $BOOST_ROOT/download.tar -y -bd<br />
cd $BOOST_ROOT && cp -r boost_*/* .<br />
rm -rf boost_*/* download.tar.bz2 download.tar<br />
OK to answer yes to delete files if prompted for the <code>rm</code> command above.<br />
<br />
'''4. Run the following commands'''<br />
<br />
cd ../../build<br />
cmake ../../Mudlet -DCMAKE_PREFIX_PATH=`brew --prefix qt5`<br />
make -j `sysctl -n hw.ncpu`<br />
<br />
<br />
'''5. Enjoy'''<br />
<br />
The mudlet.app is now available in <code>src/</code> for launching:<br />
<br />
open src/Mudlet.app<br />
<br />
'''6. Qt Creator setup'''<br />
<br />
No Lua installation is found, despite it existing on your system? Launch Qt Creator by doing <code>open /Applications/Qt Creator.app</code> (location depends on how you installed it).<br />
<br />
Receiving a <code>No rule to make target ... libQt5UiTools_debug.a</code> error? A workaround is to [https://bugreports.qt.io/browse/QTBUG-81251?focusedCommentId=538705&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-538705 symlink a file].<br />
<br />
Mudlet in Qt Creator is not launching due to <code>dyld: Symbol not found: __cg_jpeg_resync_to_restart</code>? See [https://stackoverflow.com/a/44851430/72944 here] for a workaround.<br />
<br />
== Compiling on Debian 'Sid' ==<br />
<br />
'''1. Install required packages from main repo.'''<br />
<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev<br />
<br />
sudo luarocks install luautf8<br />
sudo luarocks install lua-yajl<br />
<br />
'''2. Grab latest Mudlet source.'''<br />
<br />
mkdir ~/projects && cd ~/projects && git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet<br />
<br />
'''3. Build Mudlet.'''<br />
<br />
cd ~/projects/mudlet/src<br />
<br />
qmake<br />
<br />
make<br />
<br />
sudo make install<br />
<br />
== Compiling on Debian 11 'Bullseye' ==<br />
<br />
'''1. Install required packages.'''<br />
<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-dev \<br />
qttools5-dev luarocks ccache libpugixml-dev libqt5texttospeech5-dev qtspeech5-flite-plugin \<br />
qtspeech5-speechd-plugin libqt5opengl5-dev ninja-build cmake libsecret-1-dev<br />
<br />
sudo luarocks install luautf8 <br />
sudo luarocks install lua-yajl<br />
<br />
'''2. Get Mudlet source.'''<br />
<br />
mkdir ~/source && cd ~/source<br />
<br />
git clone --recursive https://github.com/Mudlet/Mudlet.git<br />
<br />
Note: the line above will check out `development` branch source code, and this might not always be stable. You can check out the latest release source code using this command:<br />
<br />
git clone --recursive --branch main https://github.com/Mudlet/Mudlet.git<br />
<br />
'''3. Build Mudlet.'''<br />
<br />
mkdir ~/source/Mudlet/build && cd ~/source/Mudlet/build<br />
<br />
qmake ../src/mudlet.pro<br />
<br />
make -j `nproc`<br />
<br />
sudo make install<br />
<br />
After these steps you can run Mudlet by typing:<br />
<br />
mudlet<br />
<br />
== Compiling on Raspberry Pi OS ==<br />
<br />
These instructions will get you compiling and running Mudlet on Raspberry Pi OS (Buster). Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
''' 1.a Install apt dependencies '''<br />
<br />
sudo apt-get update<br />
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \<br />
libzip-dev libboost-graph-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \<br />
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev cmake<br />
<br />
<br />
[[File:Apt-get-install-y-n.png|center|thumb|installing apt dependencies]]<br />
<br />
''' 1.b Install luarocks dependencies '''<br />
<br />
sudo luarocks install luautf8 <br />
sudo luarocks install lua-yajl YAJL_LIBDIR=`find /usr -name "libyajl.so" -printf '%h\n'` YAJL_INCDIR=/usr/include<br />
<br />
<br />
[[File:After-luarocks-dependencies.png|center|thumb|after luarocks dependencies]]<br />
<br />
''' 2. Get Mudlet source '''<br />
<br />
mkdir ~/source && cd ~/source <br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
<br />
[[File:After-get-mudlet-source.png|center|thumb|After cloning]]<br />
<br />
''' 3. Create a build directory '''<br />
<br />
cd Mudlet && mkdir build && cd build<br />
<br />
''' 4. Run the following commands to build '''<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake ../src/mudlet.pro<br />
<br />
:If you get a response along the lines of:<br />
<br />
qmake: could not find a Qt installation of ''<br />
<br />
:then you likely have ''qtchooser'' present in your system that allows for both Qt4 and Qt5 (or more than one Qt5 version) and it modifiers qmake and some other Qt development programs to take an additional argument to specify which version to use. In that case you should use:<br />
<br />
WITH_UPDATER=NO WITH_3DMAPPER=NO qmake -qt=qt5 ../src/mudlet.pro<br />
<br />
[[File:After-qmake.png|center|thumb|After qmake]]<br />
<br />
''' THEN: '''<br />
:For the fastest compile time, 15-20min on a RPi4 with 4GB of ram<br />
make -j `nproc`<br />
<br />
''' OR: '''<br />
<br />
:If you want to use your Pi while it builds or have an older Raspberry Pi, be prepared for it to take a while (over an hour) - ''it is not recommended to try to more than one compilation task at a time on the older systems with the '''-j''' option as they will only have a system memory with enough space for one of some of those tasks'':<br />
make<br />
<br />
[[File:Success.png|center|thumb|Success!]]<br />
<br />
''' 4. Install the application you have just compiled '''<br />
<br />
sudo make install<br />
<br />
[[File:Installed.png|center|thumb|Installed now]]<br />
<br />
''' 5. Enjoy! '''<br />
<br />
# mudlet is in the path, can just run it<br />
mudlet<br />
<br />
== Compiling on ArchLinux ==<br />
<br />
Mudlet is available in the [https://aur.archlinux.org Arch User Repository]. <br />
<br />
To install it use your favourite AUR helper (helper tool will automatically resove dependancies); example using ''yay'' :<br />
yay -S mudlet<br />
<br />
For more info on this process, visit [https://wiki.archlinux.org/index.php/Arch_User_Repository Arch User Repository - ArchWiki].<br />
<br />
''Note: For the most recent development version of Mudlet, replace 'mudlet' with 'mudlet-git' in the above commands and proceed as described.''<br />
<br />
''Built in fonts have been disabled, but are available in packages listed as optional dependancies.''<br />
<br />
''Discord support in Mudlet depends on an extrenal library provided by discord-rpc-api, which is also available in AUR, choose whichever variant suits you best.''<br />
<br />
== Compiling on Gentoo ==<br />
An [https://github.com/toaster/gentoo-overlay overlay containing Mudlet is available] for compiling Mudlet on Gentoo.<br />
<br />
== Compiling on Windows ==<br />
<br />
These instructions will get you setup compiling on Windows. <br />
<br />
Need a hand? Join us on the Mudlet [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums].<br />
<br />
'''1. Download Mudlet source code'''<br />
<br />
# Install [https://desktop.github.com/ Github Desktop].<br />
# Clone ([https://help.github.com/desktop/guides/contributing-to-projects/cloning-a-repository-from-github-to-github-desktop/#platform-windows instructions]) Mudlet's [https://github.com/mudlet/mudlet repository] to your local drive.<br />
{{note}} You must use a location on <code>C:\</code> without any spaces in folder names! <br />
<br />
'''2. Perform a one-time setup'''<br />
<br />
Right-click on <code>setup-windows-sdk.ps1</code> and select <code>Run with PowerShell</code>. This will automatically download all of the requires tools (including Python 2) and libraries, set them up for you, build Mudlet, and launch it! If this script exits immediately, please [https://docs.microsoft.com/en-us/powershell/scripting/windows-powershell/install/installing-windows-powershell?view=powershell-7.1#upgrading-existing-windows-powershell upgrade your PowerShell version] first.<br />
<br />
{{note}} Depending on your Internet connection and computer speed, this one-time setup will take 30 minutes or more - so grab a cup of tea or coffee.<br />
<br />
[[File:Start-of-installation.gif|frame|none|Sometimes the output will get stuck and not progress - just press Enter to make it continue. This is a well-known [https://serverfault.com/questions/204150/sometimes-powershell-stops-sending-output-until-i-press-enter-why Powershell bug.]]]<br />
<br />
During the installation, you'll see the Qt installer window pop-up - this is normal:<br />
<br />
[[File:Qt-installer.gif|thumb|none]]<br />
<br />
The Qt installer might ask you about your data collection preferences - answer as you wish and the automated install will continue:<br />
<br />
[[File:Qt-installer-data-collection.png|thumb|none]]<br />
<br />
The installer's final step will be compiling all of the source code, which looks like this:<br />
<br />
[[File:Compiling-step.gif|thumb|none]]<br />
<br />
After it's all done, a Mudlet version ending in "-dev" will launch automatically:<br />
<br />
[[File:Mudlet-launching.gif|frame|none]]<br />
<br />
If something didn't work right, you can check out the verbose log that is available at <code>C:\src\verbose_output.log</code>.<br />
<br />
=== Coding on Mudlet ===<br />
<br />
Open <code>C:\<path to repository>\src\mudlet.pro</code> in Qt Creator, which resides here: <code>C:\Qt\Tools\QtCreator\bin\qtcreator.exe</code>. Then enable Debug and Release builds and hit ''Configure Project'':<br />
<br />
[[File:Selection_173.png|frame|none]]<br />
<br />
Press <code>Ctrl+5</code> and update project settings. Check how many logical processors are available in your system with the Task Manager:<br />
<br />
[[File:Task-manager.png|thumb|none|2 processors are available in this example]]<br />
<br />
And set this amount in Qt Creator:<br />
<br />
[[File:Change Qt Creator to use many cores.gif|frame|none]]<br />
<br />
Hit run:<br />
<br />
[[File:Selection 176.png|frame|none]]<br />
<br />
Click on '''Compile Output''' to see progress on compiling:<br />
<br />
[[File:Selection 177.png|frame|none]]<br />
<br />
When it's all ready, the new Mudlet with your changes will launch. '''You're all done'''!<br />
<br />
=== Contributing changes ===<br />
<br />
Once you're all done with your changes, contribute them to Mudlet using a [https://help.github.com/desktop/guides/contributing-to-projects/creating-a-pull-request/#platform-windows pull request]. Thanks for improving open-source!<br />
<br />
=== Uninstalling ===<br />
To get rid of everything, remove the following folders:<br />
<br />
C:\Libraries<br />
C:\LuaRocks<br />
C:\MinGW<br />
C:\Python27<br />
C:\Qt<br />
C:\src<br />
<br />
== Compiling on Github Codespaces ==<br />
<br />
Github Codespaces allow you to code and run Mudlet all from the browser - makes it a lot easier to get started. It also allows you to code Mudlet itself from any computer in the world! As for this time Github Codespaces is in a private beta, so make sure to [https://github.com/features/codespaces/signup apply here]. <br />
<br />
'''1. Create a new codespace'''<br />
<br />
Create a new Codespace by going to https://github.com/Mudlet/Mudlet using Google Chrome or Microsoft Edge (Firefox at the time of the writing doesn't have working copy/paste). There, click the green "Code" button, select the "Codespaces" tab and click "New codespace".<br />
<br />
[[File:New codespace.png|alt=New codespace screenshot|frameless]]<br />
<br />
'''2. Wait for it to load'''<br />
<br />
This will take a while (~5min) so grab a tea:<br />
<br />
[[File:Building Visual Studio Codespace.png|frameless]]<br />
<br />
'''3. Connect to the environment'''<br />
<br />
Go to the <code>Ports</code> section at the bottom and change the Port Privacy of the Open Mudlet port to Public:<br />
<br />
[[File:Port privacy in Github Codespaces.png|900x900px]]<br />
<br />
<br />
Then connect to your online Linux desktop with <code>mudlet</code> as the password by clicking on the web icon. <br />
<br />
[[File:Connect to remote machine.png|frameless]]<br />
<br />
<br />
In case it can't connect, make sure the port privacy is set to <code>Public</code>. If it still can't connect, try 4-5 more times - eventually it'll work.<br />
<br />
<br />
<br />
We chose a retro 90's look here to fit with the whole hacking theme, so if you see this you're good 😉<br />
<br />
[[File:Github_codespaces_desktop.png|alt=|frameless|400x400px]]<br />
<br />
'''4. Build Mudlet'''<br />
<br />
In Codespaces, hit <code>F7</code> and select <code>Let CMake guess...</code><br />
<br />
[[File:CMake configuration.png|none]]<br />
<br />
It will then start building Mudlet automatically. Using the [https://docs.github.com/en/free-pro-team@latest/github/developing-online-with-codespaces/about-billing-for-codespaces Basic instance] (only kind available in beta) the first-time build will take ~25min, so take a break here - you've made excellent progress. All follow-up compiles after this will be quicker, by the way.<br />
<br />
[[File:Building Mudlet in codespaces.png|none]]<br />
<br />
'''5. Run Mudlet'''<br />
<br />
[[File:Launch Mudlet.png|none]]<br />
<br />
Hit the little play button at the bottom of the screen, and Mudlet will now launch in the remote connection tab. Not working? [https://discord.gg/kuYvMQ9 We can help]. Otherwise, enjoy!<br />
<br />
[[File:Mudlet running remotely.png |500px]]<br />
<br />
Note: When the codespace is unused for a while, it will disconnect. It'll never disconnect while you're actively using it. See [https://github.com/microsoft/vscode-dev-containers/issues/588 Github issue] for details.<br />
<br />
== Developing with Docker ==<br />
<br />
Docker is a system designed for more reproducible and isolated builds. A docker setup exists and has been tested using Pop OS! 20.04 (which is derived from Ubuntu 20.04). First, follow the instructions to install both [https://docs.docker.com/get-docker/ docker] and [https://docs.docker.com/compose/install/ docker-compose].<br />
<br />
Clone the development branch<br />
<br />
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git<br />
cd Mudlet/docker<br />
<br />
Make a local copy of the .env.template file:<br />
<br />
cp .env.template .env<br />
<br />
If you wish to customize things like the number of cores to use for building mudlet, feel free to change the corresponding values in the .env file.<br />
<br />
To run Qt-Creator and develop Mudlet, simply run `docker-compose up dev`.<br />
To run Mudlet, simply run `docker-compose up mudlet`. Note: At the moment, the mudlet build will not persist settings past container rebuilds.<br />
<br />
== Compiling on Windows 7+ (MSYS2 Alternative)==<br />
<br />
''INCOMPLETE, IN PROGRESS''<br />
<br />
Go to http://www.msys2.org/ to download the 64 bit MSYS2 installer (as of 2020/05/24 32 bit hosts - for '''compiling''' software, but ''not'' for using code built with it have been deprecated, the last installer for that 32-bit systems is held at: http://repo.msys2.org/distrib/i686/msys2-i686-20200517.exe) and follow the installation instructions (Steps 1 to 8 on that page), these instructions assume that "C:\msys64" or "C:\msys32" is used depending on the bitness of the system it is being installed on.<br />
<br />
Install the following packages (using "pacman -S ''packageName''"), the ones with a '''-i686-''' in the middle are the ones for 32-bit (i686) targets and '''-x86_64-''' are the ones for 64-bit targets - it is possible to install both for building Mudlet for target PCs of both bitnesses on a 64-bit host, it is not clear whether the reverse is true with a 32-bit host. These will pull in a number of other required packages as well (the ''--needed'' option prevents the re-installation of packages that have already been installed by MSYS2/Mingw-w64's own setup/installation process) - as some of the packages, e.g. ''base-devel'' are actually ''groups'' you will be requested to select which members of that group are actually required, it is easiest to just go with the default which is to install ALL of the packages in that group!<br />
<br />
: For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-i686-toolchain mingw-w64-i686-qt-creator mingw-w64-i686-qt5-multimedia mingw-w64-i686-libzip mingw-w64-i686-pugixml mingw-w64-i686-lua51 mingw-w64-i686-lua51-lpeg mingw-w64-i686-lua51-lsqlite3 mingw-w64-i686-hunspell mingw-w64-i686-boost mingw-w64-i686-yajl mingw-w64-i686-clang mingw-w64-i686-cmake mingw-w64-i686-SDL unzip<br />
</syntaxhighlight><br />
<br />
: For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-x86_64-toolchain mingw-w64-x86_64-qt-creator mingw-w64-x86_64-qt5-multimedia mingw-w64-x86_64-libzip mingw-w64-x86_64-pugixml mingw-w64-x86_64-lua51 mingw-w64-x86_64-lua51-lpeg mingw-w64-x86_64-lua51-lsqlite3 mingw-w64-x86_64-hunspell mingw-w64-x86_64-boost mingw-w64-x86_64-yajl mingw-w64-x86_64-clang mingw-w64-x86_64-cmake mingw-w64-x86_64-SDL unzip<br />
</syntaxhighlight><br />
<br />
::The ''*-zziplib'' libraries are used by the ''luazip'' luarock {from the Kepler project} but Mudlet will work perfectly well with the alternative ''lua-zip'' {from the brimworks GitHub repository - which also provides the ''lua-yajl'' rock} which does not require this library - although it is possible that it might still be pulled into the system as a dependency of another MSYS2 package.<br />
<br />
:Note that this will install the MSYS2 builds of the Qt Libraries and Creator IDE - ''THE ON/OFF-LINE INSTALLER OF THE QT LIBRARIES AND CREATOR VIA DOWNLOADS FROM QT ARE NOT USEFUL IN THIS SETUP!''<br />
<br />
:{| class="wikitable"<br />
|-<br />
|'''Attention - Luarocks packages problem'''<br />
|-<br />
| Recently the Luarocks project attempted to adopt the MSYS2/Mingw-w64 platform as one it would supported natively and the MSYS2/Mingw-w64 project went and upgraded its luarocks packages to make use of the changes and also on-board other improvements (and the version number increased from ''2.4.4-2'' to ''3.5.0-1'') unfortunately this completely broke them and although the issue has been reported ([https://github.com/msys2/MINGW-packages/issues/9037 MSYS2 Issue 9037]) a fix has not yet materialised. The only way to work around this in the meantime is to download the older package (with '''wget''') and install it manually (with '''pacman -U):<br />
|-<br />
|For 32-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:19:09-- https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97905 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-i686-lua51-luarocks-2.4.4-2- 100%[===========================================================================>] 95.61K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:19:10 (1.43 MB/s) - ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97905/97905]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-i686-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-i686-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|-<br />
|For 64-Bit Mudlet builds:<br />
:<syntaxhighlight lang="shell"><br />
MSYS user@computer ~<br />
$ wget https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
--2021-07-07 22:17:32-- https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68<br />
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.<br />
HTTP request sent, awaiting response... 200 OK<br />
Length: 97935 (96K) [application/octet-stream]<br />
Saving to: ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’<br />
<br />
mingw-w64-x86_64-lua51-luarocks-2.4.4- 100%[===========================================================================>] 95.64K --.-KB/s in 0.07s<br />
<br />
2021-07-07 22:17:32 (1.28 MB/s) - ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97935/97935]<br />
<br />
<br />
MSYS user@computer ~<br />
$ pacman -U mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst<br />
loading packages...<br />
resolving dependencies...<br />
looking for conflicting packages...<br />
<br />
Packages (1) mingw-w64-x86_64-lua51-luarocks-2.4.4-2<br />
<br />
Total Installed Size: 0.46 MiB<br />
<br />
:: Proceed with installation? [Y/n] y<br />
(1/1) checking keys in keyring [#####################################################] 100%<br />
(1/1) checking package integrity [#####################################################] 100%<br />
(1/1) loading package files [#####################################################] 100%<br />
(1/1) checking for file conflicts [#####################################################] 100%<br />
(1/1) checking available disk space [#####################################################] 100%<br />
:: Processing package changes...<br />
(1/1) installing mingw-w64-x86_64-lua51-luarocks [#####################################################] 100%<br />
<br />
MSYS user@computer ~<br />
</syntaxhighlight><br />
|}<br />
<br />
::{| class="wikitable"<br />
|-<br />
|'''Warning for those planning to build ''both'' 32 and 64 bit versions'''<br />
|-<br />
|If one is planning to build ''both'' bitness binaries an additional step is necessary as, by default, the MSYS2/Mingw-w64 ''luarocks'' setup seems to place any ''.lua'' or ''.dll'' modules it builds/installs on a per user (the so-called ''local'' basis) into the same directories with the same names. This is no good for two reasons:<br />
* It is difficult to work out which bitness a particular module is for and whilst 32-bit modules ''might'' work in a 64-bit environment the reverse is definitely not the case<br />
* It confuses the Luarocks package management systems (as effectively there will be two different luarocks systems operated side-by-side)<br />
<br />
This can be worked around by:<br />
* Editing the '''.\etc\luarocks\config-5.1.lua''' for each bitness so that the ''rocks_trees'' table entry for the ''user'' key is changed from this in '''both''' files:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks]] },</syntaxhighlight><br />
to something different for each of them, say, for example, for the the 64-bit one:<br />
:<syntaxhighlight lang="lua"> { name = [[user]], root = home..[[/.luarocks-x64]] },</syntaxhighlight><br />
* Then by specifying the ''rocktree'' name ('''user''') on the command line when '''installing''' or '''building''' a luarock with the ''--tree user'' argument - note that for some inexplicable reason the ''--local'' argument that '''''should''''' do the same thing does not seem to work for these two actions, it is not clear whether this is a MSYS2/Mingw-w64 specific issue or it goes further upstream to Luarocks in general. Thus, in the next step it will be necessary to change from using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --local rockname<br />
</syntaxhighlight><br />
to, for the example given:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install --tree user rockname<br />
</syntaxhighlight><br />
where ''user'' is the literal string "user" to match the Lua table key in the rock_trees and not, in this case, a representation of the user-name/account of the person performing the action.<br />
|}<br />
<br />
From the Windows ''Start menu'' start a shell appropriate for the target with the bitness to be built for i.e. '''"MSYS2 Mingw 32-Bit"''' or '''"MSYS2 Mingw 64-Bit"'''. This will likely position the current directory to the root directory of the MSYS2 environment, the text about the prompt line (the one with the "$") will contain three different bits of colored text '''username@computername'''; one of '''MSYS2'''/'''MINGW32'''/'''MINGW''' depending on the type of shell you currently in use and '''/''' representing the root directory (which will actually be the directory MSYS2 was installed to, for example on the author's system this is "C:/msys64"). Change to the home directory in MYSY by entering "cd" on its own with no argument (it will show up as '''~''' and it would work out to be, for '''user''' to be '''c:/msys64/home/user''' or '''c:/msys32/home/user''' (if both bitnessess are to be built it will be necessary to repeat the following step twice, one for each and also observe the steps in the above warning) install the following luarocks:<br />
<br />
:{| class="wikitable sortable"<br />
|-<br />
! rockname<br />
|-<br />
| lrexlib-pcre<br />
|-<br />
| lua-yajl<br />
|-<br />
| luafilesystem<br />
|-<br />
| luasql-sqlite3<br />
|-<br />
| luautf8<br />
|-<br />
| luazip or lua-zip<br />
|}<br />
by using:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ luarocks install [--local] rockname<br />
</syntaxhighlight><br />
The ''--local'' argument is an optional one that causes the luarock and the lua module to be installed on a per-user basis rather than on a system wide one, this may be important if the PC is used by multiple users and more than one of them uses Lua in any form.<br />
<br />
Now create somewhere to work on the Mudlet source, assuming that other software coding with other pieces of software will be done, create a sub-directory in the home directory, and then make one just for Mudlet under that:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ mkdir ./src<br />
<br />
MINGW64 user@computer ~<br />
$ mkdir ./src/mudlet<br />
</syntaxhighlight><br />
<br />
Change to that directory and get the source code:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~<br />
$ cd ./src/mudlet<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git clone git://github.com/Mudlet/Mudlet.git .<br />
</syntaxhighlight><br />
<br />
If you are planning to contribute to the Mudlet code you will want to visit Github and create your own GitHub repository, you can then push commits (changes to the code) to there and raise a Pull Request for a Mudlet Maker to drag the changes over to the above repository. You will want to add your repository and perhaps those of some other contributors so you can track what they are doing and see/try/experiment with their PRs before they get merged. Therefore you will want to add some other repositories into the mix. The names you use to identify those other repositories will show up in any utility that works with the repository you have just created in the above "clone" operation and can be anything you like but it makes sense to have clear names. So to add "myName", and those of the leading active contributors to the Mudlet codebase you will use:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Mine https://github.com/myName/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Vadim https://github.com/vadi2/Mudlet.git <br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add SlySven https://github.com/SlySven/Mudlet.git<br />
<br />
MINGW64 user@computer ~/src/mudlet<br />
$ git remote add Kebap https://github.com/Kebap/Mudlet.git<br />
</syntaxhighlight><br />
<br />
Now obtain ''all'' the versions of the code with:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ git fetch --all<br />
</syntaxhighlight><br />
<br />
This will produce a lot of lines of output the first time and it might take a little while on a slow connection...<br />
<br />
{Section missing - it turns out that the default GUI git tools that the author of this section would normally use: "gitk" and "git gui" have some problems in the versions currently supplied from the MSYS2 system - and it was necessary to import them from the set that the Git4Win have patched - see https://github.com/git-for-windows/git/wiki/Install-inside-MSYS2-proper }<br />
<br />
Some modifications to the qmake/cmake project files are needed and these are now supported in the main ''development'' branch in the upstream {the Mudlet organisation's own GitHub repository} which requires that there is an environmental variable '''WITH_MAIN_BUILD_SYSTEM''' and it is set to the (case-insensitive) value '''NO''':<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export WITH_MAIN_BUILD_SYSTEM=NO<br />
</syntaxhighlight><br />
<br />
Also the '''MINGW_BASE_DIR''' environmental variable will need to be set to the root directory for the MINGW-W64 installation for the appropriate bitness of the target to be made. For building on a 64-Bit Host {the PC that is ''compiling'' the code} to make a 64-Bit application this will likely be '''C:/msys64/mingw64''' and for a 32-Bit application it will probably be '''C:/msys64/ming32'''.<br />
: E.g. <syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw64 # To build a 64-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
: Or: <syntaxhighlight lang="shell"><br />
MINGW32 user@computer ~/src/mudlet<br />
$ export MINGW_BASE_DIR=C:/msys64/mingw32 # To build a 32-Bit Application with a 64-Bit system<br />
</syntaxhighlight><br />
<br />
Now checkout a branch {ideally, if working on solving a new issue, or adding a feature or resolving a bug, one should create a new branch that is a copy of the current, upstream ''development'' branch} and then work on it with Qt Creator:<br />
:<syntaxhighlight lang="shell"><br />
MINGW64 user@computer ~/src/mudlet<br />
$ qtcreator &<br />
</syntaxhighlight><br />
<br />
Load in the '''mudlet.pro''' ''qmake'' project file in the '''src''' subdirectory (e.g. for this example: '''c:/msys64/home/user/src/mudlet/src/mudlet.pro''') and get hacking...<br />
<br />
= Setting up IDEs =<br />
== CLion ==<br />
=== Qt not detected ===<br />
If you'd like to use CLion and it is giving the following error:<br />
<br />
<nowiki><br />
By not providing "FindQt5Core.cmake" in CMAKE_MODULE_PATH this project has<br />
asked CMake to find a package configuration file provided by "Qt5Core", but<br />
CMake did not find one.<br />
<br />
...<br />
</nowiki><br />
<br />
You can fix this by setting <code>-DCMAKE_PREFIX_PATH=<your Qt + version + compiler location></code>. For example: <code>-DCMAKE_PREFIX_PATH=/media/vadi/SSDer/Programs/Qt/5.15.2/gcc_64/</code> [[File:CLion CMake settings - finidng Qt.png|700px|none]]<br />
<br />
=== CLion setup on Windows ===<br />
After running <code>setup-windows-sdk.ps1</code> make sure to set Cmake options to:<br />
-DCMAKE_PREFIX_PATH=C:\Qt\Tools\mingw730_32;C:\Qt\5.14.2\mingw73_32 -DBoost_INCLUDE_DIR=C:\Libraries\boost_1_71_0<br />
''Directories might vary slightly, when different Qt, Boost or MinGW version will be used.''<br />
<br />
[[File:Clion Settings - Cmake.png|frameless|700x700px]]<br />
<br />
<br />
<br />
You will need 32 bit version of MinGW. Set it in the <code>Toolset</code> field to:<br />
C:\Qt\Tools\mingw730_32<br />
<br />
''Directory may be slightly different if MinGW version used will change.''<br />
<br />
[[File:Toolchain.png|frameless|700x700px]]<br />
<br />
=== Clang Tidy ===<br />
Ensure that CLion is set to run the project's [https://www.jetbrains.com/help/clion/clang-tidy-checks-support.html#paticularcheck .clang-tidy checks] with the <code>Prefer .clang-tidy files over IDE settings</code> option:<br />
<br />
[[File:Clang Tidy CLIon.png|700px|none]]<br />
<br />
This helps us catch any issues just a bit earlier.<br />
<br />
=== Clang Format ===<br />
Ensure that [https://www.jetbrains.com/help/clion/clangformat-as-alternative-formatter.html#clion-support CLion is set to use] the <code>.clang-format</code> formatting style:<br />
<br />
[[File:Clang-format CLion.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
== Visual Studio Code ==<br />
<br />
To set the path in Visual Studio Code, open settings, search for <code>cmake environment</code> and set the <code>CMAKE_PREFIX_PATH</code> to your path, such as <code>/media/vadi/SSDer/Programs/Qt/5.14.1/gcc_64/</code>:<br />
<br />
[[File:CMake path in Visual Studio Code.png|none]]<br />
<br />
===Clang Tidy===<br />
clang-tidy catches common programming issues, run it by selecting 'Analysis' from the command palette (Ctrl+Shift+P by default):<br />
<br />
[[File:Clang-tidy in vscode.png|none]]<br />
<br />
It is also possible [https://devblogs.microsoft.com/cppblog/visual-studio-code-c-december-2021-update-clang-tidy/ check status of analysis and cancel if needed].<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in VSCode, set the <code>cmake.configureSettings</code> variable:<br />
<br />
[[File:Cmake.configureSettings option in vscode.png|frameless|890x890px]]<br />
<br />
[[File:Choosing which sanitizers in vscode to use.png|frameless|891x891px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
== Qt Creator==<br />
===Clang Tidy and Clazy===<br />
<br />
Configure Mudlet-specific checks for [https://clang.llvm.org/extra/clang-tidy/ clang-tidy] and [https://github.com/KDE/clazy clazy] tools help catch any issues early on. See [https://doc.qt.io/qtcreator/creator-clang-tools.html Qt Creator's instructions] for setting this up - clang-tidy can use the <code>.clang-tidy</code> file that's available at the root of the repository, and for clazy enable <code>level0</code> and <code>level1</code> checks.<br />
<br />
[[File:Clang tidy configuration.png|frame|none]]<br />
[[File:Clazy configuration.png|frame|none]]<br />
<br />
===Checking memory leaks & other issues (sanitizers)===<br />
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:<br />
<br />
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks<br />
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more<br />
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html UndefinedBehaviourSanitizer] for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)<br />
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory<br />
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues<br />
<br />
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code><br />
<br />
To use them in Qt creator, head to <code>Projects</code> - <code>Build</code>: <br />
<br />
[[File:Sanitisers in qt creator.png|frameless|890x890px]]<br />
<br />
Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.<br />
<br />
==Clang Format==<br />
Ensure that Qt Creator is set to use the <code>.clang-format</code> formatting style in the C++ settings. Turn on <code>Format instead of indenting</code> for <code>Ctrl+I</code> to format code, and ensure <code>Override Clang Format configuration file</code> is disabled:<br />
<br />
[[File:Qt Creator clang format.png]]<br />
<br />
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.<br />
<br />
<br />
=Building with multiple versions of Lua=<br />
Mudlet uses Lua 5.1 only, so if you are compiling on a system that also has later versions installed, you might get the following error: <code>‘LUA_GLOBALSINDEX’ was not declared in this scope</code>.<br />
<br />
To fix this, pass the path to Lua headers explicitly. For CMake: <code>-DLUA_INCLUDE_DIR=/usr/include/lua5.1</code> (adjust as needed).</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:Best_Practices&diff=20074Manual:Best Practices2022-08-07T17:16:53Z<p>Demonnic: /* Use local variables */</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Collection of Mudlet best practices for building your scripts.}}<br />
<br />
= Best Practices =<br />
<br />
: The hope is that this page will provide a place to collect a list of Mudlet 'best practices' in an effort to help people keep their Mudlet scripts and packages clean, efficient, and running smoothly. Another way to think of it is a collection of tips and tricks for making Mudlet run its best. They largely fall under these categories.<br />
<br />
* [[#Lua|Lua best practices]]<br />
** Since Lua is the scripting language Mudlet makes use of, the majority of the best practices for Lua will apply when writing Mudlet scripts.<br />
** We do not aim to replace the internet as a source of Lua knowledge, but will try to highlight the most beneficial ones<br />
** Potential exceptions will be noted with their entries<br />
* [[#GUI|GUI best practices]]<br />
** keeping your UI looking it best in as many situations as possible<br />
* [[#Mudlet|Mudlet best practices]]<br />
** Optimizations and items specific to Mudlet's triggers, aliases, API, etc<br />
* [[#Generic_Mapper|Generic mapper best practices]]<br />
<br />
== Lua ==<br />
<br />
=== Use local variables ===<br />
<br />
You should really be using local variables wherever you can. <br />
If a variable is only needed for the duration of a function, alias, or trigger, then make it a local every time.<br />
If you will need to access it repeatedly in your script, make it local first.<br />
Always be asking yourself, "Could I be using a local instead?"<br />
<br />
<syntaxhighlight lang="lua"><br />
-- bad<br />
function myEcho(msg)<br />
transformed_msg = "<cyan>(<yellow>Highlighter<cyan>)<reset>" .. msg<br />
cecho(transformed_msg)<br />
end<br />
<br />
-- better<br />
function myEcho(msg)<br />
local transformed_msg = "<cyan>(<yellow>Highlighter<cyan>)<reset>" .. msg<br />
cecho(transformed_msg)<br />
end<br />
</syntaxhighlight><br />
<br />
There are three main reasons for doing so:<br />
<br />
* Making things local keeps them from colliding with variables in use by other package developers. You are probably not the first person to use "tbl" for a temporary table name.<br />
* You can make the code easier to both read and write.<br />
** <code>self.mc[tabName]</code> is a bit much to type and remember, but if you first do <code>local console = self.mc[tabName]</code> then it's obvious you're referring to a console where you use it in future<br />
* It's faster:<br />
** local variables are inherently faster in Lua, as they exist in the virtual machine registers and are a simple index lookup to access, whereas globals reside in a table and are therefore a hash lookup<br />
*** this means you can increase the speed of intensive processes just by making functions and variables local before using them.<br />
*** For instance, if you are going to cycle through a large table and cecho items from within it, adding <code>local cecho = cecho</code> above the loop can improve performance.<br />
<br />
=== Conversely, avoid _G when possible ===<br />
<br />
It's not only good practice to use local variables where possible, but you should avoid referencing the global table, _G. The very thing which makes _G useful (being able to reference elements if you don't know their name before hand) is what makes it dangerous, as it can be easy to overwrite things you shouldn't and leave yourself in a broken state. For instance, all it takes is accidentally writing to _G["send"] and suddenly all of your scripts which send commands to the game are broken.<br />
<br />
=== Avoid overwriting your variables accidentally ===<br />
<br />
Often times you need to initialize your tables at the top of your scripts. But if you click on that script again later and back off it will save and overwrite your current data. You can use 'or' to avoid this as shown below.<br />
<br />
<syntaxhighlight lang="lua"><br />
-- have to make a table before you can add things to it<br />
<br />
-- risks overwriting the entire table if I resave the script<br />
demonnic = {}<br />
<br />
-- if the variable has already been defined, it is just set back to itself. If it has not, then it's set to a new table<br />
demonnic = demonnic or {}<br />
</syntaxhighlight><br />
<br />
=== Ternary statements in Lua (set a variable based on a condition) ===<br />
<br />
Lua does not have a ternary operator as such, but you can construct a statement in such a way it functions as one, allowing for shorter and more readable code. For example:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- you can rewrite this if statement<br />
if something then<br />
myVariable = "x"<br />
else<br />
myVariable = "y"<br />
end<br />
<br />
-- as<br />
myVariable = something and "x" or "y"<br />
</syntaxhighlight><br />
<br />
=== Group your globals together in a table ===<br />
<br />
Sometimes you have to use globals, to pass values easily between items or make functions and values available to others. Lots of package makers may have a reason to track health and want to be able to pass it easily between triggers and functions without having to make it a parameter for every function they write. Obviously they can't all use the 'health' variable though, especially if one is using percentages and the other direct values. So it's best if you keep the variables for your package grouped together within a table. "Demonnic.health" is a lot less likely to collide than just 'health' There is a [https://forums.mudlet.org/viewtopic.php?f=8&t=1211 forum post] with more information.<br />
<br />
=== Declaring functions in tables: myTable:function() vs myTable.function() ===<br />
<br />
Lua does not have as much syntactic sugar as some other languages, but using a : to call a function within a table is one of them. The following declarations are functionally identical<br />
<br />
<syntaxhighlight lang="lua"><br />
function myTable:coolFunction(parameter)<br />
self.thing = parameter<br />
end<br />
<br />
function myTable.coolFunction(self, parameter)<br />
self.thing = parameter<br />
end<br />
<br />
myTable.coolFunction = function(self, parameter)<br />
self.thing = parameter<br />
end<br />
</syntaxhighlight><br />
<br />
And these calls are equivalent<br />
<br />
<syntaxhighlight lang="lua"><br />
myTable:coolFunction("Test")<br />
myTable.coolFunction(myTable, "Test")<br />
</syntaxhighlight><br />
<br />
You can use this to make it easier to keep your code self-contained and grouped together. You can combine it with setmetatable() to allow a sort of Object Oriented like programming pattern. Which leads us to<br />
<br />
=== Create objects and 'classes' using metatables and: ===<br />
<br />
Geyser makes extensive use of this pattern and it allows you to create classes and objects within Lua's procedural environment. The [https://www.lua.org/pil/16.html chapter in Programming in Lua] on Object Oriented Programming does a good job of explaining it.<br />
<br />
== GUI ==<br />
<br />
=== Give your Geyser elements unique names ===<br />
<br />
While Geyser will generate a name for you if you do not provide one, if you do provide one it gives you some measure of protection against accidental duplication, as miniconsoles and labels with the same name are reused. Likewise, you should make sure you use names which are unlikely to be used by anyone else. "healthgauge" or "container" are maybe a little generic. Try "my_package_name_health_gauge" or similar. It's more typing up front, but you shouldn't need to type it again and it will help a lot in ensuring your UI behaves as expected.<br />
<br />
=== Use percentages ===<br />
<br />
A lot of your users will be on different resolution monitors, or may not want to have Mudlet covering their entire screen. If you hardcode your sizes as direct pixel values for your Geyser objects, they will not scale as well when the window is resized due to resolution restrictions or user preference. If you're personally working on a 1080p resolution UI but you want it to scale up or down, rather than using "640px" as the width to cover a third of the screen use "33%" for the width, and it will resize to cover a third of the window no matter the size.<br />
<br />
=== Adjustable Containers put the power back in your user's hands ===<br />
<br />
If you use Adjustable.Container for groupings of your UI it allows your users to resize and move them around if they don't like the way you've arranged things. This means more people using your package in the end.<br />
<br />
== Mudlet ==<br />
<br />
=== Shield your complicated regular expression triggers with a substring trigger ===<br />
<br />
: Regular expressions are very useful, but are one of the slower trigger types to process for Mudlet. Using a substring trigger gate or a multiline trigger with the substring trigger ahead of the regular expression and a line delta of 0 you can reduce the processing time of your triggers overall by quite a bit. There has been [https://forums.mudlet.org/viewtopic.php?f=12&t=1441 benchmarking done]<br />
<br />
=== Avoid <code>expandAlias()</code> where possible ===<br />
<br />
: There's a whole wiki page on this at [[Manual:Functions_vs_expandAlias|Functions_vs_expandAlias]]<br />
<br />
=== feedTriggers is for testing, not production ===<br />
<br />
: the c/d/h/feedTriggers functions are great for testing your triggers without having to make something actually happen in your game. But you should not be using it as a functional part of your system. Much like with expandAlias, you should be calling a function from the trigger and the place you are calling feedTriggers to do the same thing, rather than getting the trigger engine itself involved.<br />
<br />
=== Capture the IDs returned by your temp items and anonymous event handlers ===<br />
<br />
: You can now skip the following by using [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler]] or [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer]] instead. The below still holds true if you want to use the anonymous functions directly and is left for that reason.<br />
: One of the more common issues people come into the help channel with is stacking tempTimers and old anonymous event handlers which have been edited not being cleared out and still firing. The solution for these issues is the same. The functions which create temporary or anonymous items in Mudlet return an ID. You need to save this ID to a variable and use it to remove the existing item before reregistering it. So for examples<br />
<br />
<syntaxhighlight lang="lua"><br />
-- incorrect, can stack timers<br />
tempTimer(0.5, function()<br />
send("And another one")<br />
end)<br />
<br />
-- Ensures the timer only fires once, .5 seconds after the first time it is called<br />
if not myTempTimerID then -- only do something if we haven't already<br />
myTempTimerID = tempTimer(0.5, function()<br />
send("Only one")<br />
myTempTimerID = nil -- unset it so it can fire again<br />
end)<br />
end<br />
<br />
-- Resets the tempTimer each time it is run, so it runs <br />
if myTempTimerID then<br />
killTimer(myTempTimerID) -- can run killTimer on an already fired timer without causing an issue.<br />
end<br />
myTempTimerID = tempTimer(0.5, function()<br />
send("Only one")<br />
end)<br />
</syntaxhighlight><br />
<br />
=== Package and Module best practices ===<br />
<br />
: This is a list of things we have discovered over the years leads to the best user experience with Mudlet packages. They aren't all necessary, but you will find that the more of them you do, the easier the lives of your users and ultimately yourself.<br />
<br />
* built-in auto-updates<br />
** so players stay up to date, which will not be the case with manual updates)<br />
* modular and extendable - use Mudlet modules for this<br />
** so people can disable ones not needed)<br />
<br />
* event based - raise events of your own for others to hook into<br />
** so the order of scripts installed in the players profile doesn't matter<br />
* make sure aliases only call functions<br />
** so people can make their own aliases or keybindings to customize as needed without using expandAlias<br />
* don't pollute the global namespace, keep everything in a table<br />
** so you don't bugs from people overwriting it or vice versa)<br />
** touched on above but bears repeating<br />
* undo any UI changes on uninstall: set borders back, hide the UI, etc<br />
** so people have a good experience even if they didn't like the package<br />
<br />
* if you're specifying any fonts, package them<br />
** while it might be available on your computer, not guaranteed to be available on every computer<br />
* if you're a game admin, install it automatically via GMCP<br />
** less overhead for players to get a good experience<br />
* if you're a game admin, provide GMCP data for your game<br />
** so people don't have to waste time trying to capture data, and can work with it instead<br />
* don't use \ in paths, use / - even for Windows<br />
** it'll work on Windows - and work on macOS and Linux too<br />
<br />
== Generic Mapper ==<br />
* when adding customisation triggers to the generic mapper, add them outside of the <code>generic_mapper</code> folder<br />
** this is so when the mapper updates, you keep your changes</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:Best_Practices&diff=20072Manual:Best Practices2022-08-01T20:44:22Z<p>Demonnic: /* Capture the IDs returned by your temp items and anonymous event handlers */</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Collection of Mudlet best practices for building your scripts.}}<br />
<br />
= Best Practices =<br />
<br />
: The hope is that this page will provide a place to collect a list of Mudlet 'best practices' in an effort to help people keep their Mudlet scripts and packages clean, efficient, and running smoothly. Another way to think of it is a collection of tips and tricks for making Mudlet run its best. They largely fall under these categories.<br />
<br />
* [[#Lua|Lua best practices]]<br />
** Since Lua is the scripting language Mudlet makes use of, the majority of the best practices for Lua will apply when writing Mudlet scripts.<br />
** We do not aim to replace the internet as a source of Lua knowledge, but will try to highlight the most beneficial ones<br />
** Potential exceptions will be noted with their entries<br />
* [[#GUI|GUI best practices]]<br />
** keeping your UI looking it best in as many situations as possible<br />
* [[#Mudlet|Mudlet best practices]]<br />
** Optimizations and items specific to Mudlet's triggers, aliases, API, etc<br />
* [[#Generic_Mapper|Generic mapper best practices]]<br />
<br />
== Lua ==<br />
<br />
=== Use local variables ===<br />
<br />
You should really be using local variables wherever you can. <br />
If a variable is only needed for the duration of a function, alias, or trigger, then make it a local every time.<br />
If you will need to access it repeatedly in your script, make it local first.<br />
Always be asking yourself, "Could I be using a local instead?"<br />
<br />
<syntaxhighlight lang="lua"><br />
-- bad<br />
function myEcho(msg)<br />
transformed_msg = "<cyan>(<yellow>Highlighter<cyan>)<reset>" .. msg<br />
cecho(transformed_msg)<br />
end<br />
<br />
-- better<br />
function myEcho(msg)<br />
local transformed_msg = "<cyan>(<yellow>Highlighter<cyan>)<reset>" .. msg<br />
cecho(transformed_msg)<br />
end<br />
</syntaxhighlight><br />
<br />
There are three main reasons for doing so:<br />
<br />
* Making things local keeps them from colliding with variables in use by other package developers. You are probably not the first person to use "tbl" for a temporary table name.<br />
* You can make the code easier to both read and write.<br />
** <code>self.mc[tabName]</code> is a bit much to type and remember, but if you first do <code>local console = self.mc[tabName]</code> then it's obvious you're referring to a console where you use it in future<br />
* It's faster:<br />
** local variables are inherently faster in Lua, as they exist in the virtual machine registers and are a simple index lookup to access, whereas globals reside in a table and are therefore a hash lookup<br />
*** this means you can increase the speed of intensive processes just by making functions and variables local before using them.<br />
*** For instance, if you are going to cycle through a large table and cecho items from within it, adding <code>local cecho = cecho</code> above the loop can improve performance.<br />
<br />
=== Avoid overwriting your variables accidentally ===<br />
<br />
Often times you need to initialize your tables at the top of your scripts. But if you click on that script again later and back off it will save and overwrite your current data. You can use 'or' to avoid this as shown below.<br />
<br />
<syntaxhighlight lang="lua"><br />
-- have to make a table before you can add things to it<br />
<br />
-- risks overwriting the entire table if I resave the script<br />
demonnic = {}<br />
<br />
-- if the variable has already been defined, it is just set back to itself. If it has not, then it's set to a new table<br />
demonnic = demonnic or {}<br />
</syntaxhighlight><br />
<br />
=== Ternary statements in Lua (set a variable based on a condition) ===<br />
<br />
Lua does not have a ternary operator as such, but you can construct a statement in such a way it functions as one, allowing for shorter and more readable code. For example:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- you can rewrite this if statement<br />
if something then<br />
myVariable = "x"<br />
else<br />
myVariable = "y"<br />
end<br />
<br />
-- as<br />
myVariable = something and "x" or "y"<br />
</syntaxhighlight><br />
<br />
=== Group your globals together in a table ===<br />
<br />
Sometimes you have to use globals, to pass values easily between items or make functions and values available to others. Lots of package makers may have a reason to track health and want to be able to pass it easily between triggers and functions without having to make it a parameter for every function they write. Obviously they can't all use the 'health' variable though, especially if one is using percentages and the other direct values. So it's best if you keep the variables for your package grouped together within a table. "Demonnic.health" is a lot less likely to collide than just 'health' There is a [https://forums.mudlet.org/viewtopic.php?f=8&t=1211 forum post] with more information.<br />
<br />
=== Declaring functions in tables: myTable:function() vs myTable.function() ===<br />
<br />
Lua does not have as much syntactic sugar as some other languages, but using a : to call a function within a table is one of them. The following declarations are functionally identical<br />
<br />
<syntaxhighlight lang="lua"><br />
function myTable:coolFunction(parameter)<br />
self.thing = parameter<br />
end<br />
<br />
function myTable.coolFunction(self, parameter)<br />
self.thing = parameter<br />
end<br />
<br />
myTable.coolFunction = function(self, parameter)<br />
self.thing = parameter<br />
end<br />
</syntaxhighlight><br />
<br />
And these calls are equivalent<br />
<br />
<syntaxhighlight lang="lua"><br />
myTable:coolFunction("Test")<br />
myTable.coolFunction(myTable, "Test")<br />
</syntaxhighlight><br />
<br />
You can use this to make it easier to keep your code self-contained and grouped together. You can combine it with setmetatable() to allow a sort of Object Oriented like programming pattern. Which leads us to<br />
<br />
=== Create objects and 'classes' using metatables and: ===<br />
<br />
Geyser makes extensive use of this pattern and it allows you to create classes and objects within Lua's procedural environment. The [https://www.lua.org/pil/16.html chapter in Programming in Lua] on Object Oriented Programming does a good job of explaining it.<br />
<br />
== GUI ==<br />
<br />
=== Give your Geyser elements unique names ===<br />
<br />
While Geyser will generate a name for you if you do not provide one, if you do provide one it gives you some measure of protection against accidental duplication, as miniconsoles and labels with the same name are reused. Likewise, you should make sure you use names which are unlikely to be used by anyone else. "healthgauge" or "container" are maybe a little generic. Try "my_package_name_health_gauge" or similar. It's more typing up front, but you shouldn't need to type it again and it will help a lot in ensuring your UI behaves as expected.<br />
<br />
=== Use percentages ===<br />
<br />
A lot of your users will be on different resolution monitors, or may not want to have Mudlet covering their entire screen. If you hardcode your sizes as direct pixel values for your Geyser objects, they will not scale as well when the window is resized due to resolution restrictions or user preference. If you're personally working on a 1080p resolution UI but you want it to scale up or down, rather than using "640px" as the width to cover a third of the screen use "33%" for the width, and it will resize to cover a third of the window no matter the size.<br />
<br />
=== Adjustable Containers put the power back in your user's hands ===<br />
<br />
If you use Adjustable.Container for groupings of your UI it allows your users to resize and move them around if they don't like the way you've arranged things. This means more people using your package in the end.<br />
<br />
== Mudlet ==<br />
<br />
=== Shield your complicated regular expression triggers with a substring trigger ===<br />
<br />
: Regular expressions are very useful, but are one of the slower trigger types to process for Mudlet. Using a substring trigger gate or a multiline trigger with the substring trigger ahead of the regular expression and a line delta of 0 you can reduce the processing time of your triggers overall by quite a bit. There has been [https://forums.mudlet.org/viewtopic.php?f=12&t=1441 benchmarking done]<br />
<br />
=== Avoid <code>expandAlias()</code> where possible ===<br />
<br />
: There's a whole wiki page on this at [[Manual:Functions_vs_expandAlias|Functions_vs_expandAlias]]<br />
<br />
=== feedTriggers is for testing, not production ===<br />
<br />
: the c/d/h/feedTriggers functions are great for testing your triggers without having to make something actually happen in your game. But you should not be using it as a functional part of your system. Much like with expandAlias, you should be calling a function from the trigger and the place you are calling feedTriggers to do the same thing, rather than getting the trigger engine itself involved.<br />
<br />
=== Capture the IDs returned by your temp items and anonymous event handlers ===<br />
<br />
: You can now skip the following by using [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler]] or [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer]] instead. The below still holds true if you want to use the anonymous functions directly and is left for that reason.<br />
: One of the more common issues people come into the help channel with is stacking tempTimers and old anonymous event handlers which have been edited not being cleared out and still firing. The solution for these issues is the same. The functions which create temporary or anonymous items in Mudlet return an ID. You need to save this ID to a variable and use it to remove the existing item before reregistering it. So for examples<br />
<br />
<syntaxhighlight lang="lua"><br />
-- incorrect, can stack timers<br />
tempTimer(0.5, function()<br />
send("And another one")<br />
end)<br />
<br />
-- Ensures the timer only fires once, .5 seconds after the first time it is called<br />
if not myTempTimerID then -- only do something if we haven't already<br />
myTempTimerID = tempTimer(0.5, function()<br />
send("Only one")<br />
myTempTimerID = nil -- unset it so it can fire again<br />
end)<br />
end<br />
<br />
-- Resets the tempTimer each time it is run, so it runs <br />
if myTempTimerID then<br />
killTimer(myTempTimerID) -- can run killTimer on an already fired timer without causing an issue.<br />
end<br />
myTempTimerID = tempTimer(0.5, function()<br />
send("Only one")<br />
end)<br />
</syntaxhighlight><br />
<br />
=== Package and Module best practices ===<br />
<br />
: This is a list of things we have discovered over the years leads to the best user experience with Mudlet packages. They aren't all necessary, but you will find that the more of them you do, the easier the lives of your users and ultimately yourself.<br />
<br />
* built-in auto-updates<br />
** so players stay up to date, which will not be the case with manual updates)<br />
* modular and extendable - use Mudlet modules for this<br />
** so people can disable ones not needed)<br />
<br />
* event based - raise events of your own for others to hook into<br />
** so the order of scripts installed in the players profile doesn't matter<br />
* make sure aliases only call functions<br />
** so people can make their own aliases or keybindings to customize as needed without using expandAlias<br />
* don't pollute the global namespace, keep everything in a table<br />
** so you don't bugs from people overwriting it or vice versa)<br />
** touched on above but bears repeating<br />
* undo any UI changes on uninstall: set borders back, hide the UI, etc<br />
** so people have a good experience even if they didn't like the package<br />
<br />
* if you're specifying any fonts, package them<br />
** while it might be available on your computer, not guaranteed to be available on every computer<br />
* if you're a game admin, install it automatically via GMCP<br />
** less overhead for players to get a good experience<br />
* if you're a game admin, provide GMCP data for your game<br />
** so people don't have to waste time trying to capture data, and can work with it instead<br />
* don't use \ in paths, use / - even for Windows<br />
** it'll work on Windows - and work on macOS and Linux too<br />
<br />
== Generic Mapper ==<br />
* when adding customisation triggers to the generic mapper, add them outside of the <code>generic_mapper</code> folder<br />
** this is so when the mapper updates, you keep your changes</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:Supported_Protocols&diff=20013Manual:Supported Protocols2022-07-07T21:49:25Z<p>Demonnic: /* MXP */</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Manual on supported protocols like CHARSET, GMCP, MSSP, MSP, ATCP, MSDP, MXP, etc.}}<br />
= Supported Protocols =<br />
<br />
Mudlet supports CHARSET, GMCP, MSSP, MSP, ATCP, Aardwolfs 102, MSDP, and the MXP Protocol. <br />
<br />
CHARSET, MXP, MSSP, MSP, GMCP and 102 are enabled by default, MSDP can be enabled in settings.<br />
<br />
[[File:Game protocols toggle.png|center]]<br />
<br />
==GMCP==<br />
Generic Mud Communication Protocol, or GMCP, is a protocol for game servers to communicate information with game clients in a separate channel from the one which carries all of the text that makes up the game itself. Enabling the Debug window will show you GMCP events as they are coming in, and to get an idea of what information is currently stored, hit the Statistics button.<br />
<br />
When working with GMCP on IRE games, this [https://github.com/keneanung/GMCPAdditions GMCP reference] is a useful tool.<br />
<br />
===Using GMCP===<br />
====Receiving GMCP data====<br />
To "trigger" on GMCP messages, you'll need to create [[Manual:Technical_Manual#Event_System|an event handler]] - Mudlet will call it for you whenever relevant GMCP data is received.<br />
<br />
As an example, create a new script and give it a name of the function you'd like to be called when the relevant GMCP message is received. Then, add the GMCP event you'd like the function to fire on under the registered event handlers left. Lastly, define the function - either in this or any other script - and you'll be done. The GMCP data received will be stored in the corresponding field of the ''gmcp'' table, which your function will read from.<br />
<br />
Example:<br />
<br />
:[[File:using_gmcp.png|border|center]]<br />
<br />
The ''test_gmcp()'' function will be called whenever ''Char.Vitals'' is received from the game, and it'll echo the latest data on the screen.<br />
<br />
====Sending GMCP data====<br />
Certain modules will only send data when a request is made by your client. In Mudlet, you can make such a request using the command '''sendGMCP("command")'''. Read your game's relevant documentation, such as the [http://nexus.ironrealms.com/GMCP IRE document on GMCP], for information about specific modules.<br />
<br />
:See Also: [[Manual:Networking Functions#sendGMCP | sendGMCP]]<br />
<br />
===Managing GMCP modules===<br />
While some GMCP modules are enabled by Mudlet by default when you connect with a GMCP enabled game, others may not be 'standard' modules and are instead specific to the game itself. In order to provide a way to manage GMCP modules without scripts causing modules in use by other scripts to be disabled.<br />
<br />
====Registering user====<br />
While this step is no longer strictly required, you can register your 'user' with gmod using<br />
<syntaxhighlight lang="lua"><br />
gmod.registerUser("MyUser")<br />
</syntaxhighlight><br />
Where ''MyUser'' is your plugin/addon/whatever name. However, your user will be automatically registered if you enable or disable any modules using it. Which leads us to...<br />
<br />
====Enabling modules====<br />
Enabling a GMCP module is as easy as:<br />
<syntaxhighlight lang="lua"><br />
gmod.enableModule("MyUser", "Module.Name")<br />
</syntaxhighlight><br />
<br />
If MyUser has not been registered previously, then they will be automatically registered when you call this function. An example of a module which would need to be enabled this way is the IRE.Rift module provided by IRE MUDs. <br />
<syntaxhighlight lang="lua"><br />
-- add this to a login trigger, or anything that will get done just once per login<br />
gmod.enableModule("<character name>", "IRE.Rift")<br />
</syntaxhighlight><br />
<br />
Another example would be the Combat module in Lithmeria, which isn't enabled by default:<br />
<syntaxhighlight lang="lua"><br />
-- add this to a login trigger, or anything that will get done just once per login<br />
gmod.enableModule("<character name>", "Combat")<br />
</syntaxhighlight><br />
<br />
====Disabling modules====<br />
Disabling a GMCP module is just as easy as enabling it:<br />
<syntaxhighlight lang="lua"><br />
gmod.disableModule("MyUser", "Module.Name")<br />
</syntaxhighlight><br />
The main difference being that the module will be turned on as soon as you enable it if it is not already enabled. If you disable it, it will not be disabled with the server until every user of that module has disabled it. This prevents script A from disabling modules that script B may still be using.<br />
<br />
===Thorough GMCP tutorial===<br />
A good GMCP tutorial that walks you through receiving and sending GMCP data is [http://www.mudlet.org/wp-content/uploads/2013/02/GMCPtutorial.pdf available here] - take a read!<br />
<br />
==MSDP==<br />
MSDP (Mud Server Data Protocol) is a protocol for game servers to communicate information with game clients in a separate channel from the one which carries all of the text that makes up the game itself. Mudlet can be configured to use MSDP by clicking on the Settings button (or Options->Preferences in the menu, or <alt>p). The option is on the General tab. <br />
<br />
Once MSDP is enabled, you will need to reconnect to the game so that Mudlet can inform the server it is ready to receive MSDP information. Please note that some servers don't both send MSDP and GMCP at the same time, so even if you enable both in Mudlet, the server will choose to send only one of them.<br />
<br />
Enabling the Debug window will show you MSDP events as they are coming in, and to get an idea of what information is currently stored, hit the Statistics button. Also see [http://tintin.sourceforge.net/msdp/ MSDP reference] for some of the commands and values your server might support.<br />
<br />
===Using MSDP===<br />
====Receiving MSDP data====<br />
To "trigger" on MSDP messages, you'll need to create [[Manual:Technical_Manual#Event_System|an event handler]] - Mudlet will call it for you whenever relevant MSDP data is received.<br />
<br />
As an example, lets create a script that'll track whenever we move - that is, the room number changes. To begin with, we need to ask the game to be sending us updates whenever we move - so do:<br />
<br />
<code><br />
lua sendMSDP("REPORT", "ROOM_VNUM")<br />
</code><br />
<br />
in the command-line first to enable reporting of the room number and name. Then, create a new script and give it a name of the function you'd like to be called when the relevant MSDP message is received. Add the MSDP event you'd like the function to fire on under the registered event handlers - in our case, '''msdp.ROOM_VNUM'''. Lastly, define the function - either in this or any other script - and you'll be done. The MSDP data received will be stored in the corresponding field of the ''msdp'' table, which your function will read from.<br />
<br />
Example:<br />
<br />
:[[File:Using_msdp.png|border|center]]<br />
<br />
The ''test_msdp()'' function will be called whenever ''ROOM_VNUM'' is received from the game, and it'll echo the latest data on the screen.<br />
<br />
====Sending MSDP data====<br />
You can use [[Manual:Networking Functions#sendMSDP | sendMSDP]] to send information via MSDP back to the game. The first parameter to the function is the MSDP variable, and all the subsequent ones are values. See the [http://tintin.sourceforge.net/msdp/ MSDP documentation] for some examples of data that you can send:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- ask the server to report your health changes to you. Result will be stored in msdp.HEALTH in Mudlet<br />
sendMSDP("REPORT", "HEALTH")<br />
<br />
-- client - IAC SB MSDP MSDP_VAR "SEND" MSDP_VAL "AREA NAME" MSDP_VAL "ROOM NAME" IAC SE in the documentation translates to the following in Mudlet:<br />
sendMSDP("SEND", "AREA NAME", "ROOM NAME")<br />
</syntaxhighlight><br />
<br />
:See Also: [[Manual:Networking Functions#sendMSDP | sendMSDP]]<br />
<br />
==Encoding==<br />
More and more game servers are looking beyond ASCII encoding to support extended character sets, like UTF-8 encoding, to meet demand for localization of language and the use of emoji characters.<br />
<br />
===Encoding in Mudlet===<br />
Reference our manual page on [[Manual:Unicode | Unicode]] for more information on Unicode updating, scripting and trigger support in Mudlet.<br />
<br />
====Manual Encoding Updates====<br />
Mudlet supports manual selection of a server data encoding. Mudlet users may update the server data encoding for a profile by choosing Settings, General and selecting a server data encoding from the corresponding drop-down menu. The server data encoding defaults to ASCII. When the setting is changed, the selected encoding saves with the user's profile information.<br />
<br />
====Automated Encoding Updates====<br />
Negotiating the '''CHARSET''' telnet option provides game servers the capability to automatically request a preferred character set with Mudlet per [https://tools.ietf.org/html/rfc2066 RFC 2066]. Game servers may send a telopt WILL CHARSET (42), Mudlet responds with a DO CHARSET (42), then the game server may send SB CHARSET (42) REQUEST (1) <separator_character> <charset>. Mudlet will respond with SB CHARSET (42) ACCEPTED (2) <charset> if it supports that character set. Mudlet will respond with SB CHARSET (42) REJECTED (3) if it refuses the requested character set(s). When Mudlet accepts a requested character set, it automatically updates the server data encoding viewable in the Settings menu. It is possible to send a list of requested character sets to Mudlet by appending additional "<separator_character> <charset>" byte groups to a SB CHARSET (42) REQUEST (1).<br />
<br />
Success example:<br />
{| class="wikitable"<br />
! Server<br />
! Mudlet<br />
|-<br />
| IAC WILL CHARSET (42) <br />
| IAC DO CHARSET (42)<br />
|-<br />
| IAC SB CHARSET (42) REQUEST (1) <space> ''UTF-8'' IAC SE<br />
| IAC SB CHARSET (42) ACCEPTED (2) ''UTF-8'' IAC SE<br />
|-<br />
|}<br />
<br />
The following is an example of an attempted negotiation where the encoding was not available with Mudlet:<br />
{| class="wikitable"<br />
! Server<br />
! Mudlet<br />
|-<br />
| IAC WILL CHARSET (42) <br />
| IAC DO CHARSET (42)<br />
|-<br />
| IAC SB CHARSET (42) REQUEST (1) <space> ''DEEP-6'' IAC SE<br />
| IAC SB CHARSET (42) REJECTED (3) IAC SE<br />
|-<br />
|}<br />
<br />
If a Mudlet user does not want to negotiate character set, they may choose the Settings, Special Options menu item in Mudlet and enable "Force CHARSET negotiation off". The following is an example of an attempted negotiation where "Force CHARSET negotiation off" is enabled.<br />
{| class="wikitable"<br />
! Server<br />
! Mudlet<br />
|-<br />
| IAC WILL CHARSET (42) <br />
| IAC DONT CHARSET (42)<br />
|-<br />
|}<br />
<br />
CHARSET negotiation is available in Mudlet 4.10+.<br />
<br />
==MSSP==<br />
'''Mud Server Status Protocol''', or MSSP, provides a way for game crawlers (i.e. [https://tintin.sourceforge.io/protocols/mssp/mudlist.html MSSP Mud Crawler]) and game listing sites (search for Listings [https://www.reddit.com/r/MUD/ here]) to gather detailed information about a game, including dynamic information like boot time and the current amount of online players. It also makes submitting a new game entry very simple on game listing sites. A player or administrator is only required to fill in the hostname and port and other information is gathered from behind the scenes.<br />
<br />
===MSSP in Mudlet===<br />
The MSSP data presented in Mudlet will enable MSSP standard data fields to be made accessible for scripting. Some useful fields include the game name, number of players, uptime, game hostname, game port, codebase, admin contact, Discord invite URL, year created, link to an icon, ip address, primary language, game location, website and several others may be available. It is up to the game in question to populate the data, so don't expect all fields to be filled in.<br />
<br />
MSSP is available in Mudlet 4.1+.<br />
<br />
===Receiving MSSP Data===<br />
To receive MSSP data in Mudlet, these conditions must be met:<br />
<br />
# The ''Enable MSSP'' box in the Settings window of Mudlet must be checked (default on).<br />
# The game must negotiate MSSP with clients like Mudlet at its login screen. Details [https://tintin.sourceforge.io/protocols/mssp/ here].<br />
<br />
To see whether your game supports MSSP, after connecting, type ''lua mssp''. If the game does not support MSSP, you will see an empty table ''mssp = {}''. If it does you will see information similar to the example below. The data may be accessed in a similar way to the instructions for GMCP listed above. Typically, MSSP data is only sent once per connection.<br />
<br />
<syntaxhighlight lang="lua"><br />
mssp = {<br />
HOSTNAME = "stickmud.com",<br />
VT100 = "1",<br />
UPTIME = "1565657220",<br />
MSDP = "0",<br />
MCP = "0",<br />
GMCP = "1",<br />
PORT = "7680",<br />
["MINIMUM AGE"] = "13",<br />
PUEBLO = "0",<br />
INTERMUD = "-1",<br />
SKILLS = "100",<br />
["HIRING BUILDERS"] = "0",<br />
PLAYERS = "6",<br />
CONTACT = "askstickmud@hotmail.com",<br />
CODEBASE = "LDMud 3.5.0 (3.5.1)",<br />
["HIRING CODERS"] = "0",<br />
["PAY FOR PERKS"] = "0",<br />
LOCATION = "Canada",<br />
GAMESYSTEM = "Custom",<br />
MCCP = "0",<br />
SUBGENRE = "Medieval Fantasy",<br />
ROOMS = "10000",<br />
STATUS = "Live",<br />
FAMILY = "LPMud",<br />
LEVELS = "150",<br />
CREATED = "1991",<br />
["PAY TO PLAY"] = "0",<br />
IP = "24.138.28.11",<br />
MOBILES = "-1",<br />
GAMEPLAY = "Hack and Slash",<br />
CLASSES = "8",<br />
NAME = "StickMUD",<br />
SSL = "0",<br />
ANSI = "1",<br />
ICON = "https://www.stickmud.com/favicon.ico",<br />
RACES = "12",<br />
UTF-8 = "0",<br />
AREAS = "-1",<br />
MXP = "0",<br />
HELPFILES = "-1",<br />
["XTERM 256 COLORS"] = "0",<br />
MSP = "1",<br />
OBJECTS = "9780",<br />
WEBSITE = "https://www.stickmud.com",<br />
GENRE = "Fantasy",<br />
DISCORD = "https://discord.gg/erBBxt",<br />
LANGUAGE = "English"<br />
}<br />
</syntaxhighlight><br />
<br />
==MSP==<br />
<br />
Want to add accessibility and excitement into your game? How about implementing sound and music triggers?<br />
<br />
'''Mud Sound Protocol''', or MSP, provides a way for games to send sound and music triggers to clients. Clients have the option to implement a framework where the corresponding triggers play. MSP triggers are sent in one direction to game clients and not to game servers. Sounds may be downloaded manually or automatically if conditions are met.<br />
<br />
Games could use telnet option negotiation to signal clients support for MSP (''WILL'', ''WONT''), and toggling MSP processing on and off (''DO'', ''DONT''). This is communicated using TELOPT 90, which is reserved (unofficially) for the MSP protocol by our community. Games that do not support telnet option negotiation for MSP should provide a means for their players to toggle this feature on and off.<br />
<br />
The latest specification for MSP is located [https://www.zuggsoft.com/zmud/msp.htm here]. <br />
<br />
===MSP in Mudlet===<br />
<br />
Mudlet processes MSP sound and music triggers in three ways:<br />
<br />
#'''MSP over OOB''' - Mudlet is capable of receiving hidden, out-of-band telnet sound and music triggers from game servers via messaging with TELOPT 90.<br />
#'''MSP for Lua''' - Mudlet triggers may capture and invoke the [[Manual:Lua Functions#receiveMSP | receiveMSP]] function available through the Lua interpreter of Mudlet to process MSP.<br />
#'''MSP over GMCP''' - Mudlet may receive GMCP events from game servers sent with the [[Manual:Scripting#MUD_Client_Media_Protocol | Client.Media]] package.<br />
<br />
Sound or music triggers that contain a media file name will be searched for in the '''media''' folder of the corresponding Mudlet profile that matches the host for the game. If the ''media'' folder and the file are found by Mudlet, it will be played, given the host's operating system supports playing that type of media file. If the file is not found, Mudlet could initiate a download of the media file when provided a URL to find the file. Alternatively, game administrators may instruct players on other ways to transfer media files by 1) creating a ''media'' folder in their game's Mudlet profile and 2) copying files or extracting them from an archive (zip).<br />
<br />
MSP is available in Mudlet 4.4+<br />
<br />
===Receiving MSP Data===<br />
<br />
Processing of MSP is enabled by default on new game profiles. Control whether the processing is on or off through the Settings menu in Mudlet.<br />
<br />
====MSP over OOB====<br />
<br />
Game administrators may send sound and music triggers over the out-of-bounds (hidden) telnet channel encoded with TELOPT 90 after performing telnet negotiation with Mudlet. The advantage to this is that all of the communication is behind the scenes with no additional trigger requirements for the player (see ''MSP over Lua''). Games will send the bytes of out-of-band messages to Mudlet in a format like this: <pre>IAC SB TELOPT_MSP !!SOUND(cow.wav L=2 V=100) IAC SE</pre><br />
<br />
{{note}} Game admins: This option does require a TELOPT 90 WILL message.<br />
<br />
====MSP for Lua====<br />
<br />
Check for MSP support with your game and enable any options that allow sound and music triggers to be sent to your screen.<br />
<br />
Create a sound trigger to invoke the Lua interpreter:<br />
<br />
{| class="wikitable"<br />
!Name<br />
!Text<br />
!Type<br />
!Script<br />
|-<br />
| style="text-align:center;" |Sound Trigger<br />
|^!!SOUND\((\S+?)(?: (.+))?\)$<br />
|perl regex<br />
| style="text-align:left;" |<br />
*deleteLine()<br />
*[[Manual:Lua Functions#receiveMSP | receiveMSP]](matches[1])<br />
|-<br />
|}<br />
<br />
Create a music trigger to invoke the Lua interpreter:<br />
<br />
{| class="wikitable"<br />
!Name<br />
!Text<br />
!Type<br />
!Script<br />
|-<br />
| style="text-align:center;" |Music Trigger<br />
|^!!MUSIC\((\S+?)(?: (.+))?\)$<br />
|perl regex<br />
| style="text-align:left;" |<br />
*deleteLine()<br />
*[[Manual:Lua Functions#receiveMSP | receiveMSP]](matches[1])<br />
|-<br />
|}<br />
<br />
{{note}} Game admins: Best practice is to implement a TELOPT 90 WILL message as a signal to the client that MSP is supported. This is not required. <br />
<br />
If your game does not negotiate MSP, you can use this script in your trigger instead of receiveMSP for MSP Sound:<br />
<syntaxhighlight lang="lua"><br />
deleteLine()<br />
local mspFile = nil<br />
local mspVolume = 100<br />
local mspLength = 1<br />
local mspPriority = 50<br />
local mspType = nil<br />
local mspURL = nil<br />
-- Strip !!SOUND() from the line<br />
local line = matches[1]:sub(9, -2)<br />
-- Break up the line into tokens<br />
local tokens = line:split(" ")<br />
-- Iterate through the tokens to discover MSP values<br />
for index, value in ipairs(tokens) do<br />
if index == 1 then<br />
mspFile = value<br />
elseif value:find("V=", 1, true) == 1 or value:find("v=", 1, true) == 1 then<br />
mspVolume = tonumber(value:sub(3))<br />
elseif value:find("L=", 1, true) == 1 or value:find("l=", 1, true) == 1 then<br />
mspLength = tonumber(value:sub(3))<br />
elseif value:find("P=", 1, true) == 1 or value:find("p=", 1, true) == 1 then<br />
mspPriority = tonumber(value:sub(3))<br />
elseif value:find("T=", 1, true) == 1 or value:find("t=", 1, true) == 1 then<br />
mspType = value:sub(3)<br />
elseif value:find("U=", 1, true) == 1 or value:find("u=", 1, true) == 1 then<br />
mspURL = value:sub(3)<br />
end<br />
end<br />
if mspFile == "Off" and mspURL == nil then<br />
stopSounds()<br />
else<br />
playSoundFile(<br />
{<br />
name = mspFile,<br />
volume = mspVolume,<br />
loops = mspLength,<br />
priority = mspPriority,<br />
tag = mspType,<br />
url = mspURL,<br />
}<br />
)<br />
end<br />
</syntaxhighlight><br />
<br />
If your game does not negotiate MSP, you can use this script in your trigger instead of receiveMSP for MSP Music:<br />
<syntaxhighlight lang="lua"><br />
deleteLine()<br />
local mspFile = nil<br />
local mspVolume = 100<br />
local mspLength = 1<br />
local mspContinue = true<br />
local mspType = nil<br />
local mspURL = nil<br />
-- Strip !!MUSIC() from the line<br />
local line = matches[1]:sub(9, -2)<br />
-- Break up the line into tokens<br />
local tokens = line:split(" ")<br />
-- Iterate through the tokens to discover MSP values<br />
for index, value in ipairs(tokens) do<br />
if index == 1 then<br />
mspFile = value<br />
elseif value:find("V=", 1, true) == 1 or value:find("v=", 1, true) == 1 then<br />
mspVolume = tonumber(value:sub(3))<br />
elseif value:find("L=", 1, true) == 1 or value:find("l=", 1, true) == 1 then<br />
mspLength = tonumber(value:sub(3))<br />
elseif value:find("C=", 1, true) == 1 or value:find("c=", 1, true) == 1 then<br />
if tonumber(value:sub(3)) == 0 then<br />
mspContinue = false<br />
else<br />
mspContinue = true<br />
end<br />
elseif value:find("T=", 1, true) == 1 or value:find("t=", 1, true) == 1 then<br />
mspType = value:sub(3)<br />
elseif value:find("U=", 1, true) == 1 or value:find("u=", 1, true) == 1 then<br />
mspURL = value:sub(3)<br />
end<br />
end<br />
if mspFile == "Off" and mspURL == nil then<br />
stopMusic()<br />
else<br />
playMusicFile(<br />
{<br />
name = mspFile,<br />
volume = mspVolume,<br />
loops = mspLength,<br />
continue = mspContinue,<br />
tag = mspType,<br />
url = mspURL,<br />
}<br />
)<br />
end<br />
</syntaxhighlight><br />
====MSP over GMCP ====<br />
<br />
Reference Mudlet's [[Manual:Scripting#MUD_Client_Media_Protocol | documentation]] on the [[Standards:MUD_Client_Media_Protocol | MUD Client Media Protocol]] specification for more information.<br />
<br />
{{note}} Game admins: Do not implement a TELOPT 90 WILL message exchange when exclusively using this option.<br />
<br />
===MSP Troubleshooting===<br />
<br />
*Wildcards ''?'' or ''*'' within the file name do not trigger automatic sound or music downloads. Ensure the sound was downloaded previously prior to using a wildcard.<br />
*Mudlet < 4.11 would not play the MSP sound if it had unknown elements, Mudlet 4.12+ will ignore the unknown elements and do the best it can to play the sound.<br />
<br />
===MSP Specification===<br />
For more insight into the syntax of sound and music triggers, please reference the [https://www.zuggsoft.com/zmud/msp.htm specification].<br />
<br />
== ATCP==<br />
<br />
Mudlet includes support for ATCP. This is primarily available on IRE-based MUDs, but Mudlet's implementation is generic enough such that any it should work on others.<br />
<br />
{{Note}} ATCP has been overtaken by GMCP, prefer to use that instead.<br />
<br />
The latest ATCP data is stored in the atcp table. Whenever new data arrives, the previous is overwritten. An event is also raised for each ATCP message that arrives. To find out the available messages available in the atcp table and the event names, you can use display(atcp).<br />
<br />
Note that while the typical message comes in the format of Module.Submodule, ie Char.Vitals or Room.Exits, in Mudlet the dot is removed - so it becomes CharVitals and RoomExits. <br />
;Example<br />
<syntaxhighlight lang="lua"><br />
room_number = tonumber(atcp.RoomNum)<br />
echo(room_number)<br />
</syntaxhighlight><br />
<br />
===Triggering on ATCP events===<br />
<br />
If you’d like to trigger on ATCP messages, then you need to create scripts to attach handlers to the ATCP messages. The ATCP handler names follow the same format as the atcp table - RoomNum, RoomExits, CharVitals and so on.<br />
<br />
While the concept of handlers for events is to be explained elsewhere in the manual, the quick rundown is this - place the event name you’d like your script to listen to into the Add User Defined Event Handler: field and press the + button to register it. Next, because scripts in Mudlet can have multiple functions, you need to tell Mudlet which function should it call for you when your handler receives a message. You do that by setting the Script name: to the function name in the script you’d like to be called.<br />
<br />
For example, if you’d like to listen to the RoomExits event and have it call the process_exits() function - register RoomExits as the event handler, make the script name be process_exits, and use this in the script:<br />
<br />
<syntaxhighlight lang="lua"><br />
function process_exits(event, args)<br />
echo("Called event: " .. event .. "\nWith args: " .. args)<br />
end<br />
</syntaxhighlight><br />
<br />
Feel free to experiment with this to achieve the desired results. A ATCP demo package is also available on the forums for using event handlers and parsing its messages into Lua datastructures.<br />
<br />
===Mudlet-specific ATCP===<br />
See [[Manual:ATCP_Extensions|ATCP Extensions]] for ATCP extensions that have been added to Mudlet.<br />
<br />
==Aardwolf’s 102 subchannel==<br />
<br />
Similar to ATCP, Aardwolf includes a hidden channel of information that you can access in Mudlet. Mudlet deals with it in the same way as with ATCP, so for full usage instructions see the ATCP section. All data is stored in the channel102 table, such that you can do:<br />
<br />
<syntaxhighlight lang="lua"><br />
display(channel102)<br />
</syntaxhighlight><br />
<br />
... to see all the latest information that has been received. The event to create handlers on is titled '''channel102Message''', and you can use the [[Manual:Lua_Functions#sendTelnetChannel102|sendTelnetChannel102(msg)]] function to send text via the 102 channel back to Aardwolf.<br />
<br />
<syntaxhighlight lang="lua"><br />
-- Function for detecting AFK status on Aardwolf mud.<br />
function amIafk()<br />
for k,v in pairs(channel102) do<br />
if k==100 and v==4 then<br />
return true<br />
end<br />
end<br />
return false<br />
end<br />
</syntaxhighlight><br />
<br />
==MXP==<br />
MXP is based loosely on the HTML and XML standards supported by modern web browsers. It is only "loosely" based upon these standards because games require dynamic, streaming text, rather than the page-oriented view of web browsers. Also, the existing standards are needlessly verbose for use on a game where text efficiency is important.<br />
<br />
In addition, there are additional security concerns to worry about with MXP. While support for HTML tags within a line is desired, players on a game can exploit this power and cause problems. Certain HTML functions need to be restricted so that players cannot abuse them. For example, while it might be desirable to allow players to change the font or color of their chat messages, you would not want to allow them to display a large graphics image, or execute script commands on the client of other users. MXP handles this by grouping the various tags and commands into secure and open categories, and preventing the secure tags from being used by players.<br />
<br />
Mudlet implements a subset of MXP features - the most popular ones that are actually in use. Mudlet supports MXP links (including send to prompt and open in browser in Mudlet 3.17+), pop-up menus, creation of custom elements, and line modes. As a game admin, you can ask what features are supported with the <code><SUPPORT></code> command.<br />
<br />
=== MXP in Mudlet ===<br />
Just like GMCP, MXP data is available in the <code>mxp.</code> namespace and events are raised. To see all MXP events, turn on Debug mode.<br />
<br />
[[File:MXP data.png]]<br />
<br />
<syntaxhighlight lang="lua"><br />
function testmxpsend()<br />
print("Text for the link is: ".. mxp.send.href)<br />
print("Commands to do are: ")<br />
display(mxp.send.actions)<br />
print("\n")<br />
end<br />
<br />
registerAnonymousEventHandler("mxp.send", "testmxpsend")<br />
</syntaxhighlight><br />
<br />
{{Note}} Available in Mudlet 4.8+<br />
<br />
=== Receiving MXP Data ===<br />
Processing of MXP is enabled by default on new game profiles. Control whether the processing is on or off through the Settings menu in Mudlet.<br />
<br />
==== Simple example of receiving MXP Data ====<br />
<syntaxhighlight lang="lua"><br />
<SEND href=\"&text;\"> go north... </SEND>"<br />
</syntaxhighlight><br />
<br />
==== Advanced example of receiving MXP Data ====<br />
<syntaxhighlight lang="lua"><br />
<send href='examine &#34;&name;&#34;|get &#34;&name;&#34;' hint='Right mouse click to act on this item|Get &desc;|Examine &desc;|Look in &desc;' expire=get>\" ATT='name desc'><br />
</syntaxhighlight><br />
<br />
===MXP Specification===<br />
MXP was originally developed and supported by the Zuggsoft team. For more insight into the syntax, please reference the [https://www.zuggsoft.com/zmud/mxp.htm specification]. Mudlet currently supports version 1.0 of the MXP spec.<br />
<br />
==Secure connection (TLS)==<br />
To connect to a game securely, tick the 'Secure' box in the profile connection settings:<br />
<br />
[[File:Secure-connection.png|center]]<br />
<br />
Note that the game must support a secure (TLS) connection in order for this to work, and this feature is available in Mudlet 3.17+.<br />
<br />
If you are a games admin/developer, check out [https://wiki.mudlet.org/w/Sample_TLS_Configuration this] or [https://blog.oestrich.org/2018/11/nginx-tls-socket this] example on how to setup a secure connection to your game.<br />
<br />
==Adding support for a telnet protocol ==<br />
In addition to supporting ATCP, GMCP, Aardwolf's 102 and MXP, Mudlet has open telnet support - meaning that for any telnet protocol it doesn't support, it has the tools you can use to build the support for. This does not mean Mudlet supports other protocols "out of the box" - you will either have to get code that adds the support, or you could create it yourself.<br />
<br />
The basic tools that you need are [[Manual:Miscellaneous_Functions#addSupportedTelnetOption|addSupportedTelnetOption()]], [[Manual:Miscellaneous_Functions#sendSocket|sendSocket()]] and the [[Manual:Event_Engine#sysTelnetEvent|sysTelnetEvent]].<br />
<br />
Create [[Manual:Event_Engine#Registering_an_event_from_a_script|an event handler]] that goes off on [[Manual:Event_Engine#sysTelnetEvent|sysTelnetEvent]] - which is raised whenever an unsupported telnet option is encountered. Your logic handling will start in this event handler. Once you decide what you'd like to send to the game, use [[Manual:Miscellaneous_Functions#sendSocket|sendSocket()]] to send raw data as-is. Finally, when your logic is done, use [[Manual:Miscellaneous_Functions#addSupportedTelnetOption|addSupportedTelnetOption()]] to register your telnet option with Mudlet, so it will respond with telnet DO on a query from the game server. See [http://www.mudbytes.net/forum/comment/63920/#c63920 this MSDP snippet] for a barebones example.<br />
<br />
===API philosophy===<br />
Adding a support for a new telnet protocol will involve adding the user-facing API. It best for users if it was in the same style as Mudlets handling of other protocols. To see how it's done exactly, check out GMCP, ATCP or Aardwolf 102 examples - but the gist of it is provided below.<br />
<br />
Mudlet has a built-in event system, which is used to broadcast messages in an independent way. With it, people can "trigger" on 102, ATCP or GMCP events with Lua functions that get called whenever an event they're interested in is raised. '''Use the event system to provide your users with a way to react to new protocol data'''.<br />
<br />
Events have names, and optionally, any amount of data with them. For protocol support, Mudlet prefixes the relevant message received name with the protocol name in lowercase. For example, an ATCP Char.Vitals getting updated would raise an event titled "atcp.Char.Vitals". A GMCP Room.Info message would raise a "gmcp.Room.Info" message. <br />
<br />
Additionally, Mudlet also allows catch-all event - in case the user wants to use one event handler for a variety of sub-events (it's not uncommon for games to use ''Main.Sub.Add'', ''Main.Sub.Remove'', ''Main.Sub.List'' to keep track of a list, for example, while conserving data). To accomplish this, it raises events for every relevant namespace - that is, a Main.Sub.Add event will raise ''protocol.Main.Sub'' and ''protocol.Main.Sub.Add events''. While it is entirely possible for one event handler to react to multiple events, this is provided for convenience.<br />
<br />
For storing protocol data, Mudlet uses an aptly named global table - '''gmcp''' for GMCP data, '''atcp''' for ATCP data. Data is stored in the same way it is received and the event is raised for - so a Char.Vitals message's contents will be stored in gmcp.Char.Vitals, a Room.Info's contents in gmcp.Room.Info. If there were was any nested data within the message, it is stored as a table within the proper namespace - ie, a "details" JSON array of a GMCP Room.Info message would be stored in gmcp.Room.Info.details. '''Use a global table with the protocol name in lowerspace for storing permanent data''' that your users will read from.<br />
<br />
That's it! If you'll need any Mudlet-related help, feel free to [http://forums.mudlet.org/viewforum.php?f=9 post on our forums]. Once you're done, [[Mudlet_Packages|package your work]] for distribution which you can optionally post in the [http://forums.mudlet.org/viewforum.php?f=6 finished scripts] section.<br />
<br />
[[Category:Mudlet Manual]]</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:Supported_Protocols&diff=19998Manual:Supported Protocols2022-06-26T02:44:29Z<p>Demonnic: /* Receiving MSSP Data */</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Manual on supported protocols like CHARSET, GMCP, MSSP, MSP, ATCP, MSDP, MXP, etc.}}<br />
= Supported Protocols =<br />
<br />
Mudlet supports CHARSET, GMCP, MSSP, MSP, ATCP, Aardwolfs 102, MSDP, and the MXP Protocol. <br />
<br />
CHARSET, MXP, MSSP, MSP, GMCP and 102 are enabled by default, MSDP can be enabled in settings.<br />
<br />
[[File:Game protocols toggle.png|center]]<br />
<br />
==GMCP==<br />
Generic Mud Communication Protocol, or GMCP, is a protocol for game servers to communicate information with game clients in a separate channel from the one which carries all of the text that makes up the game itself. Enabling the Debug window will show you GMCP events as they are coming in, and to get an idea of what information is currently stored, hit the Statistics button.<br />
<br />
When working with GMCP on IRE games, this [https://github.com/keneanung/GMCPAdditions GMCP reference] is a useful tool.<br />
<br />
===Using GMCP===<br />
====Receiving GMCP data====<br />
To "trigger" on GMCP messages, you'll need to create [[Manual:Technical_Manual#Event_System|an event handler]] - Mudlet will call it for you whenever relevant GMCP data is received.<br />
<br />
As an example, create a new script and give it a name of the function you'd like to be called when the relevant GMCP message is received. Then, add the GMCP event you'd like the function to fire on under the registered event handlers left. Lastly, define the function - either in this or any other script - and you'll be done. The GMCP data received will be stored in the corresponding field of the ''gmcp'' table, which your function will read from.<br />
<br />
Example:<br />
<br />
:[[File:using_gmcp.png|border|center]]<br />
<br />
The ''test_gmcp()'' function will be called whenever ''Char.Vitals'' is received from the game, and it'll echo the latest data on the screen.<br />
<br />
====Sending GMCP data====<br />
Certain modules will only send data when a request is made by your client. In Mudlet, you can make such a request using the command '''sendGMCP("command")'''. Read your game's relevant documentation, such as the [http://nexus.ironrealms.com/GMCP IRE document on GMCP], for information about specific modules.<br />
<br />
:See Also: [[Manual:Networking Functions#sendGMCP | sendGMCP]]<br />
<br />
===Managing GMCP modules===<br />
While some GMCP modules are enabled by Mudlet by default when you connect with a GMCP enabled game, others may not be 'standard' modules and are instead specific to the game itself. In order to provide a way to manage GMCP modules without scripts causing modules in use by other scripts to be disabled.<br />
<br />
====Registering user====<br />
While this step is no longer strictly required, you can register your 'user' with gmod using<br />
<syntaxhighlight lang="lua"><br />
gmod.registerUser("MyUser")<br />
</syntaxhighlight><br />
Where ''MyUser'' is your plugin/addon/whatever name. However, your user will be automatically registered if you enable or disable any modules using it. Which leads us to...<br />
<br />
====Enabling modules====<br />
Enabling a GMCP module is as easy as:<br />
<syntaxhighlight lang="lua"><br />
gmod.enableModule("MyUser", "Module.Name")<br />
</syntaxhighlight><br />
<br />
If MyUser has not been registered previously, then they will be automatically registered when you call this function. An example of a module which would need to be enabled this way is the IRE.Rift module provided by IRE MUDs. <br />
<syntaxhighlight lang="lua"><br />
-- add this to a login trigger, or anything that will get done just once per login<br />
gmod.enableModule("<character name>", "IRE.Rift")<br />
</syntaxhighlight><br />
<br />
Another example would be the Combat module in Lithmeria, which isn't enabled by default:<br />
<syntaxhighlight lang="lua"><br />
-- add this to a login trigger, or anything that will get done just once per login<br />
gmod.enableModule("<character name>", "Combat")<br />
</syntaxhighlight><br />
<br />
====Disabling modules====<br />
Disabling a GMCP module is just as easy as enabling it:<br />
<syntaxhighlight lang="lua"><br />
gmod.disableModule("MyUser", "Module.Name")<br />
</syntaxhighlight><br />
The main difference being that the module will be turned on as soon as you enable it if it is not already enabled. If you disable it, it will not be disabled with the server until every user of that module has disabled it. This prevents script A from disabling modules that script B may still be using.<br />
<br />
===Thorough GMCP tutorial===<br />
A good GMCP tutorial that walks you through receiving and sending GMCP data is [http://www.mudlet.org/wp-content/uploads/2013/02/GMCPtutorial.pdf available here] - take a read!<br />
<br />
==MSDP==<br />
MSDP (Mud Server Data Protocol) is a protocol for game servers to communicate information with game clients in a separate channel from the one which carries all of the text that makes up the game itself. Mudlet can be configured to use MSDP by clicking on the Settings button (or Options->Preferences in the menu, or <alt>p). The option is on the General tab. <br />
<br />
Once MSDP is enabled, you will need to reconnect to the game so that Mudlet can inform the server it is ready to receive MSDP information. Please note that some servers don't both send MSDP and GMCP at the same time, so even if you enable both in Mudlet, the server will choose to send only one of them.<br />
<br />
Enabling the Debug window will show you MSDP events as they are coming in, and to get an idea of what information is currently stored, hit the Statistics button. Also see [http://tintin.sourceforge.net/msdp/ MSDP reference] for some of the commands and values your server might support.<br />
<br />
===Using MSDP===<br />
====Receiving MSDP data====<br />
To "trigger" on MSDP messages, you'll need to create [[Manual:Technical_Manual#Event_System|an event handler]] - Mudlet will call it for you whenever relevant MSDP data is received.<br />
<br />
As an example, lets create a script that'll track whenever we move - that is, the room number changes. To begin with, we need to ask the game to be sending us updates whenever we move - so do:<br />
<br />
<code><br />
lua sendMSDP("REPORT", "ROOM_VNUM")<br />
</code><br />
<br />
in the command-line first to enable reporting of the room number and name. Then, create a new script and give it a name of the function you'd like to be called when the relevant MSDP message is received. Add the MSDP event you'd like the function to fire on under the registered event handlers - in our case, '''msdp.ROOM_VNUM'''. Lastly, define the function - either in this or any other script - and you'll be done. The MSDP data received will be stored in the corresponding field of the ''msdp'' table, which your function will read from.<br />
<br />
Example:<br />
<br />
:[[File:Using_msdp.png|border|center]]<br />
<br />
The ''test_msdp()'' function will be called whenever ''ROOM_VNUM'' is received from the game, and it'll echo the latest data on the screen.<br />
<br />
====Sending MSDP data====<br />
You can use [[Manual:Networking Functions#sendMSDP | sendMSDP]] to send information via MSDP back to the game. The first parameter to the function is the MSDP variable, and all the subsequent ones are values. See the [http://tintin.sourceforge.net/msdp/ MSDP documentation] for some examples of data that you can send:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- ask the server to report your health changes to you. Result will be stored in msdp.HEALTH in Mudlet<br />
sendMSDP("REPORT", "HEALTH")<br />
<br />
-- client - IAC SB MSDP MSDP_VAR "SEND" MSDP_VAL "AREA NAME" MSDP_VAL "ROOM NAME" IAC SE in the documentation translates to the following in Mudlet:<br />
sendMSDP("SEND", "AREA NAME", "ROOM NAME")<br />
</syntaxhighlight><br />
<br />
:See Also: [[Manual:Networking Functions#sendMSDP | sendMSDP]]<br />
<br />
==Encoding==<br />
More and more game servers are looking beyond ASCII encoding to support extended character sets, like UTF-8 encoding, to meet demand for localization of language and the use of emoji characters.<br />
<br />
===Encoding in Mudlet===<br />
Reference our manual page on [[Manual:Unicode | Unicode]] for more information on Unicode updating, scripting and trigger support in Mudlet.<br />
<br />
====Manual Encoding Updates====<br />
Mudlet supports manual selection of a server data encoding. Mudlet users may update the server data encoding for a profile by choosing Settings, General and selecting a server data encoding from the corresponding drop-down menu. The server data encoding defaults to ASCII. When the setting is changed, the selected encoding saves with the user's profile information.<br />
<br />
====Automated Encoding Updates====<br />
Negotiating the '''CHARSET''' telnet option provides game servers the capability to automatically request a preferred character set with Mudlet per [https://tools.ietf.org/html/rfc2066 RFC 2066]. Game servers may send a telopt WILL CHARSET (42), Mudlet responds with a DO CHARSET (42), then the game server may send SB CHARSET (42) REQUEST (1) <separator_character> <charset>. Mudlet will respond with SB CHARSET (42) ACCEPTED (2) <charset> if it supports that character set. Mudlet will respond with SB CHARSET (42) REJECTED (3) if it refuses the requested character set(s). When Mudlet accepts a requested character set, it automatically updates the server data encoding viewable in the Settings menu. It is possible to send a list of requested character sets to Mudlet by appending additional "<separator_character> <charset>" byte groups to a SB CHARSET (42) REQUEST (1).<br />
<br />
Success example:<br />
{| class="wikitable"<br />
! Server<br />
! Mudlet<br />
|-<br />
| IAC WILL CHARSET (42) <br />
| IAC DO CHARSET (42)<br />
|-<br />
| IAC SB CHARSET (42) REQUEST (1) <space> ''UTF-8'' IAC SE<br />
| IAC SB CHARSET (42) ACCEPTED (2) ''UTF-8'' IAC SE<br />
|-<br />
|}<br />
<br />
The following is an example of an attempted negotiation where the encoding was not available with Mudlet:<br />
{| class="wikitable"<br />
! Server<br />
! Mudlet<br />
|-<br />
| IAC WILL CHARSET (42) <br />
| IAC DO CHARSET (42)<br />
|-<br />
| IAC SB CHARSET (42) REQUEST (1) <space> ''DEEP-6'' IAC SE<br />
| IAC SB CHARSET (42) REJECTED (3) IAC SE<br />
|-<br />
|}<br />
<br />
If a Mudlet user does not want to negotiate character set, they may choose the Settings, Special Options menu item in Mudlet and enable "Force CHARSET negotiation off". The following is an example of an attempted negotiation where "Force CHARSET negotiation off" is enabled.<br />
{| class="wikitable"<br />
! Server<br />
! Mudlet<br />
|-<br />
| IAC WILL CHARSET (42) <br />
| IAC DONT CHARSET (42)<br />
|-<br />
|}<br />
<br />
CHARSET negotiation is available in Mudlet 4.10+.<br />
<br />
==MSSP==<br />
'''Mud Server Status Protocol''', or MSSP, provides a way for game crawlers (i.e. [https://tintin.sourceforge.io/protocols/mssp/mudlist.html MSSP Mud Crawler]) and game listing sites (search for Listings [https://www.reddit.com/r/MUD/ here]) to gather detailed information about a game, including dynamic information like boot time and the current amount of online players. It also makes submitting a new game entry very simple on game listing sites. A player or administrator is only required to fill in the hostname and port and other information is gathered from behind the scenes.<br />
<br />
===MSSP in Mudlet===<br />
The MSSP data presented in Mudlet will enable MSSP standard data fields to be made accessible for scripting. Some useful fields include the game name, number of players, uptime, game hostname, game port, codebase, admin contact, Discord invite URL, year created, link to an icon, ip address, primary language, game location, website and several others may be available. It is up to the game in question to populate the data, so don't expect all fields to be filled in.<br />
<br />
MSSP is available in Mudlet 4.1+.<br />
<br />
===Receiving MSSP Data===<br />
To receive MSSP data in Mudlet, these conditions must be met:<br />
<br />
# The ''Enable MSSP'' box in the Settings window of Mudlet must be checked (default on).<br />
# The game must negotiate MSSP with clients like Mudlet at its login screen. Details [https://tintin.sourceforge.io/protocols/mssp/ here].<br />
<br />
To see whether your game supports MSSP, after connecting, type ''lua mssp''. If the game does not support MSSP, you will see an empty table ''mssp = {}''. If it does you will see information similar to the example below. The data may be accessed in a similar way to the instructions for GMCP listed above. Typically, MSSP data is only sent once per connection.<br />
<br />
<syntaxhighlight lang="lua"><br />
mssp = {<br />
HOSTNAME = "stickmud.com",<br />
VT100 = "1",<br />
UPTIME = "1565657220",<br />
MSDP = "0",<br />
MCP = "0",<br />
GMCP = "1",<br />
PORT = "7680",<br />
["MINIMUM AGE"] = "13",<br />
PUEBLO = "0",<br />
INTERMUD = "-1",<br />
SKILLS = "100",<br />
["HIRING BUILDERS"] = "0",<br />
PLAYERS = "6",<br />
CONTACT = "askstickmud@hotmail.com",<br />
CODEBASE = "LDMud 3.5.0 (3.5.1)",<br />
["HIRING CODERS"] = "0",<br />
["PAY FOR PERKS"] = "0",<br />
LOCATION = "Canada",<br />
GAMESYSTEM = "Custom",<br />
MCCP = "0",<br />
SUBGENRE = "Medieval Fantasy",<br />
ROOMS = "10000",<br />
STATUS = "Live",<br />
FAMILY = "LPMud",<br />
LEVELS = "150",<br />
CREATED = "1991",<br />
["PAY TO PLAY"] = "0",<br />
IP = "24.138.28.11",<br />
MOBILES = "-1",<br />
GAMEPLAY = "Hack and Slash",<br />
CLASSES = "8",<br />
NAME = "StickMUD",<br />
SSL = "0",<br />
ANSI = "1",<br />
ICON = "https://www.stickmud.com/favicon.ico",<br />
RACES = "12",<br />
UTF-8 = "0",<br />
AREAS = "-1",<br />
MXP = "0",<br />
HELPFILES = "-1",<br />
["XTERM 256 COLORS"] = "0",<br />
MSP = "1",<br />
OBJECTS = "9780",<br />
WEBSITE = "https://www.stickmud.com",<br />
GENRE = "Fantasy",<br />
DISCORD = "https://discord.gg/erBBxt",<br />
LANGUAGE = "English"<br />
}<br />
</syntaxhighlight><br />
<br />
==MSP==<br />
<br />
Want to add accessibility and excitement into your game? How about implementing sound and music triggers?<br />
<br />
'''Mud Sound Protocol''', or MSP, provides a way for games to send sound and music triggers to clients. Clients have the option to implement a framework where the corresponding triggers play. MSP triggers are sent in one direction to game clients and not to game servers. Sounds may be downloaded manually or automatically if conditions are met.<br />
<br />
Games could use telnet option negotiation to signal clients support for MSP (''WILL'', ''WONT''), and toggling MSP processing on and off (''DO'', ''DONT''). This is communicated using TELOPT 90, which is reserved (unofficially) for the MSP protocol by our community. Games that do not support telnet option negotiation for MSP should provide a means for their players to toggle this feature on and off.<br />
<br />
The latest specification for MSP is located [https://www.zuggsoft.com/zmud/msp.htm here]. <br />
<br />
===MSP in Mudlet===<br />
<br />
Mudlet processes MSP sound and music triggers in three ways:<br />
<br />
#'''MSP over OOB''' - Mudlet is capable of receiving hidden, out-of-band telnet sound and music triggers from game servers via messaging with TELOPT 90.<br />
#'''MSP for Lua''' - Mudlet triggers may capture and invoke the [[Manual:Lua Functions#receiveMSP | receiveMSP]] function available through the Lua interpreter of Mudlet to process MSP.<br />
#'''MSP over GMCP''' - Mudlet may receive GMCP events from game servers sent with the [[Manual:Scripting#MUD_Client_Media_Protocol | Client.Media]] package.<br />
<br />
Sound or music triggers that contain a media file name will be searched for in the '''media''' folder of the corresponding Mudlet profile that matches the host for the game. If the ''media'' folder and the file are found by Mudlet, it will be played, given the host's operating system supports playing that type of media file. If the file is not found, Mudlet could initiate a download of the media file when provided a URL to find the file. Alternatively, game administrators may instruct players on other ways to transfer media files by 1) creating a ''media'' folder in their game's Mudlet profile and 2) copying files or extracting them from an archive (zip).<br />
<br />
MSP is available in Mudlet 4.4+<br />
<br />
===Receiving MSP Data===<br />
<br />
Processing of MSP is enabled by default on new game profiles. Control whether the processing is on or off through the Settings menu in Mudlet.<br />
<br />
====MSP over OOB====<br />
<br />
Game administrators may send sound and music triggers over the out-of-bounds (hidden) telnet channel encoded with TELOPT 90 after performing telnet negotiation with Mudlet. The advantage to this is that all of the communication is behind the scenes with no additional trigger requirements for the player (see ''MSP over Lua''). Games will send the bytes of out-of-band messages to Mudlet in a format like this: <pre>IAC SB TELOPT_MSP !!SOUND(cow.wav L=2 V=100) IAC SE</pre><br />
<br />
{{note}} Game admins: This option does require a TELOPT 90 WILL message.<br />
<br />
====MSP for Lua====<br />
<br />
Check for MSP support with your game and enable any options that allow sound and music triggers to be sent to your screen.<br />
<br />
Create a sound trigger to invoke the Lua interpreter:<br />
<br />
{| class="wikitable"<br />
!Name<br />
!Text<br />
!Type<br />
!Script<br />
|-<br />
| style="text-align:center;" |Sound Trigger<br />
|^!!SOUND\((\S+?)(?: (.+))?\)$<br />
|perl regex<br />
| style="text-align:left;" |<br />
*deleteLine()<br />
*[[Manual:Lua Functions#receiveMSP | receiveMSP]](matches[1])<br />
|-<br />
|}<br />
<br />
Create a music trigger to invoke the Lua interpreter:<br />
<br />
{| class="wikitable"<br />
!Name<br />
!Text<br />
!Type<br />
!Script<br />
|-<br />
| style="text-align:center;" |Music Trigger<br />
|^!!MUSIC\((\S+?)(?: (.+))?\)$<br />
|perl regex<br />
| style="text-align:left;" |<br />
*deleteLine()<br />
*[[Manual:Lua Functions#receiveMSP | receiveMSP]](matches[1])<br />
|-<br />
|}<br />
<br />
{{note}} Game admins: Best practice is to implement a TELOPT 90 WILL message as a signal to the client that MSP is supported. This is not required. <br />
<br />
If your game does not negotiate MSP, you can use this script in your trigger instead of receiveMSP for MSP Sound:<br />
<syntaxhighlight lang="lua"><br />
deleteLine()<br />
local mspFile = nil<br />
local mspVolume = 100<br />
local mspLength = 1<br />
local mspPriority = 50<br />
local mspType = nil<br />
local mspURL = nil<br />
-- Strip !!SOUND() from the line<br />
local line = matches[1]:sub(9, -2)<br />
-- Break up the line into tokens<br />
local tokens = line:split(" ")<br />
-- Iterate through the tokens to discover MSP values<br />
for index, value in ipairs(tokens) do<br />
if index == 1 then<br />
mspFile = value<br />
elseif value:find("V=", 1, true) == 1 or value:find("v=", 1, true) == 1 then<br />
mspVolume = tonumber(value:sub(3))<br />
elseif value:find("L=", 1, true) == 1 or value:find("l=", 1, true) == 1 then<br />
mspLength = tonumber(value:sub(3))<br />
elseif value:find("P=", 1, true) == 1 or value:find("p=", 1, true) == 1 then<br />
mspPriority = tonumber(value:sub(3))<br />
elseif value:find("T=", 1, true) == 1 or value:find("t=", 1, true) == 1 then<br />
mspType = value:sub(3)<br />
elseif value:find("U=", 1, true) == 1 or value:find("u=", 1, true) == 1 then<br />
mspURL = value:sub(3)<br />
end<br />
end<br />
if mspFile == "Off" and mspURL == nil then<br />
stopSounds()<br />
else<br />
playSoundFile(<br />
{<br />
name = mspFile,<br />
volume = mspVolume,<br />
loops = mspLength,<br />
priority = mspPriority,<br />
tag = mspType,<br />
url = mspURL,<br />
}<br />
)<br />
end<br />
</syntaxhighlight><br />
<br />
If your game does not negotiate MSP, you can use this script in your trigger instead of receiveMSP for MSP Music:<br />
<syntaxhighlight lang="lua"><br />
deleteLine()<br />
local mspFile = nil<br />
local mspVolume = 100<br />
local mspLength = 1<br />
local mspContinue = true<br />
local mspType = nil<br />
local mspURL = nil<br />
-- Strip !!MUSIC() from the line<br />
local line = matches[1]:sub(9, -2)<br />
-- Break up the line into tokens<br />
local tokens = line:split(" ")<br />
-- Iterate through the tokens to discover MSP values<br />
for index, value in ipairs(tokens) do<br />
if index == 1 then<br />
mspFile = value<br />
elseif value:find("V=", 1, true) == 1 or value:find("v=", 1, true) == 1 then<br />
mspVolume = tonumber(value:sub(3))<br />
elseif value:find("L=", 1, true) == 1 or value:find("l=", 1, true) == 1 then<br />
mspLength = tonumber(value:sub(3))<br />
elseif value:find("C=", 1, true) == 1 or value:find("c=", 1, true) == 1 then<br />
if tonumber(value:sub(3)) == 0 then<br />
mspContinue = false<br />
else<br />
mspContinue = true<br />
end<br />
elseif value:find("T=", 1, true) == 1 or value:find("t=", 1, true) == 1 then<br />
mspType = value:sub(3)<br />
elseif value:find("U=", 1, true) == 1 or value:find("u=", 1, true) == 1 then<br />
mspURL = value:sub(3)<br />
end<br />
end<br />
if mspFile == "Off" and mspURL == nil then<br />
stopMusic()<br />
else<br />
playMusicFile(<br />
{<br />
name = mspFile,<br />
volume = mspVolume,<br />
loops = mspLength,<br />
continue = mspContinue,<br />
tag = mspType,<br />
url = mspURL,<br />
}<br />
)<br />
end<br />
</syntaxhighlight><br />
====MSP over GMCP ====<br />
<br />
Reference Mudlet's [[Manual:Scripting#MUD_Client_Media_Protocol | documentation]] on the [[Standards:MUD_Client_Media_Protocol | MUD Client Media Protocol]] specification for more information.<br />
<br />
{{note}} Game admins: Do not implement a TELOPT 90 WILL message exchange when exclusively using this option.<br />
<br />
===MSP Troubleshooting===<br />
<br />
*Wildcards ''?'' or ''*'' within the file name do not trigger automatic sound or music downloads. Ensure the sound was downloaded previously prior to using a wildcard.<br />
*Mudlet < 4.11 would not play the MSP sound if it had unknown elements, Mudlet 4.12+ will ignore the unknown elements and do the best it can to play the sound.<br />
<br />
===MSP Specification===<br />
For more insight into the syntax of sound and music triggers, please reference the [https://www.zuggsoft.com/zmud/msp.htm specification].<br />
<br />
== ATCP==<br />
<br />
Mudlet includes support for ATCP. This is primarily available on IRE-based MUDs, but Mudlet's implementation is generic enough such that any it should work on others.<br />
<br />
{{Note}} ATCP has been overtaken by GMCP, prefer to use that instead.<br />
<br />
The latest ATCP data is stored in the atcp table. Whenever new data arrives, the previous is overwritten. An event is also raised for each ATCP message that arrives. To find out the available messages available in the atcp table and the event names, you can use display(atcp).<br />
<br />
Note that while the typical message comes in the format of Module.Submodule, ie Char.Vitals or Room.Exits, in Mudlet the dot is removed - so it becomes CharVitals and RoomExits. <br />
;Example<br />
<syntaxhighlight lang="lua"><br />
room_number = tonumber(atcp.RoomNum)<br />
echo(room_number)<br />
</syntaxhighlight><br />
<br />
===Triggering on ATCP events===<br />
<br />
If you’d like to trigger on ATCP messages, then you need to create scripts to attach handlers to the ATCP messages. The ATCP handler names follow the same format as the atcp table - RoomNum, RoomExits, CharVitals and so on.<br />
<br />
While the concept of handlers for events is to be explained elsewhere in the manual, the quick rundown is this - place the event name you’d like your script to listen to into the Add User Defined Event Handler: field and press the + button to register it. Next, because scripts in Mudlet can have multiple functions, you need to tell Mudlet which function should it call for you when your handler receives a message. You do that by setting the Script name: to the function name in the script you’d like to be called.<br />
<br />
For example, if you’d like to listen to the RoomExits event and have it call the process_exits() function - register RoomExits as the event handler, make the script name be process_exits, and use this in the script:<br />
<br />
<syntaxhighlight lang="lua"><br />
function process_exits(event, args)<br />
echo("Called event: " .. event .. "\nWith args: " .. args)<br />
end<br />
</syntaxhighlight><br />
<br />
Feel free to experiment with this to achieve the desired results. A ATCP demo package is also available on the forums for using event handlers and parsing its messages into Lua datastructures.<br />
<br />
===Mudlet-specific ATCP===<br />
See [[Manual:ATCP_Extensions|ATCP Extensions]] for ATCP extensions that have been added to Mudlet.<br />
<br />
==Aardwolf’s 102 subchannel==<br />
<br />
Similar to ATCP, Aardwolf includes a hidden channel of information that you can access in Mudlet. Mudlet deals with it in the same way as with ATCP, so for full usage instructions see the ATCP section. All data is stored in the channel102 table, such that you can do:<br />
<br />
<syntaxhighlight lang="lua"><br />
display(channel102)<br />
</syntaxhighlight><br />
<br />
... to see all the latest information that has been received. The event to create handlers on is titled '''channel102Message''', and you can use the [[Manual:Lua_Functions#sendTelnetChannel102|sendTelnetChannel102(msg)]] function to send text via the 102 channel back to Aardwolf.<br />
<br />
<syntaxhighlight lang="lua"><br />
-- Function for detecting AFK status on Aardwolf mud.<br />
function amIafk()<br />
for k,v in pairs(channel102) do<br />
if k==100 and v==4 then<br />
return true<br />
end<br />
end<br />
return false<br />
end<br />
</syntaxhighlight><br />
<br />
==MXP==<br />
MXP is based loosely on the HTML and XML standards supported by modern web browsers. It is only "loosely" based upon these standards because games require dynamic, streaming text, rather than the page-oriented view of web browsers. Also, the existing standards are needlessly verbose for use on a game where text efficiency is important.<br />
<br />
In addition, there are additional security concerns to worry about with MXP. While support for HTML tags within a line is desired, players on a game can exploit this power and cause problems. Certain HTML functions need to be restricted so that players cannot abuse them. For example, while it might be desirable to allow players to change the font or color of their chat messages, you would not want to allow them to display a large graphics image, or execute script commands on the client of other users. MXP handles this by grouping the various tags and commands into secure and open categories, and preventing the secure tags from being used by players.<br />
<br />
Mudlet implements a subset of MXP features - the most popular ones that are actually in use. Mudlet supports MXP links (including send to prompt and open in browser in Mudlet 3.17+), pop-up menus, creation of custom elements, and line modes. As a game admin, you can ask what features are supported with the <code><SUPPORT></code> command.<br />
<br />
Just like GMCP, MXP data is available in the <code>mxp.</code> namespace and events are raised. To see all MXP events, turn on Debug mode.<br />
<br />
[[File:MXP data.png]]<br />
<br />
<syntaxhighlight lang="lua"><br />
function testmxpsend()<br />
print("Text for the link is: ".. mxp.send.href)<br />
print("Commands to do are: ")<br />
display(mxp.send.actions)<br />
print("\n")<br />
end<br />
<br />
registerAnonymousEventHandler("mxp.send", "testmxpsend")<br />
</syntaxhighlight><br />
<br />
{{Note}} Available in Mudlet 4.8+<br />
<br />
==Secure connection (TLS)==<br />
To connect to a game securely, tick the 'Secure' box in the profile connection settings:<br />
<br />
[[File:Secure-connection.png|center]]<br />
<br />
Note that the game must support a secure (TLS) connection in order for this to work, and this feature is available in Mudlet 3.17+.<br />
<br />
If you are a games admin/developer, check out [https://wiki.mudlet.org/w/Sample_TLS_Configuration this] or [https://blog.oestrich.org/2018/11/nginx-tls-socket this] example on how to setup a secure connection to your game.<br />
<br />
==Adding support for a telnet protocol ==<br />
In addition to supporting ATCP, GMCP, Aardwolf's 102 and MXP, Mudlet has open telnet support - meaning that for any telnet protocol it doesn't support, it has the tools you can use to build the support for. This does not mean Mudlet supports other protocols "out of the box" - you will either have to get code that adds the support, or you could create it yourself.<br />
<br />
The basic tools that you need are [[Manual:Miscellaneous_Functions#addSupportedTelnetOption|addSupportedTelnetOption()]], [[Manual:Miscellaneous_Functions#sendSocket|sendSocket()]] and the [[Manual:Event_Engine#sysTelnetEvent|sysTelnetEvent]].<br />
<br />
Create [[Manual:Event_Engine#Registering_an_event_from_a_script|an event handler]] that goes off on [[Manual:Event_Engine#sysTelnetEvent|sysTelnetEvent]] - which is raised whenever an unsupported telnet option is encountered. Your logic handling will start in this event handler. Once you decide what you'd like to send to the game, use [[Manual:Miscellaneous_Functions#sendSocket|sendSocket()]] to send raw data as-is. Finally, when your logic is done, use [[Manual:Miscellaneous_Functions#addSupportedTelnetOption|addSupportedTelnetOption()]] to register your telnet option with Mudlet, so it will respond with telnet DO on a query from the game server. See [http://www.mudbytes.net/forum/comment/63920/#c63920 this MSDP snippet] for a barebones example.<br />
<br />
===API philosophy===<br />
Adding a support for a new telnet protocol will involve adding the user-facing API. It best for users if it was in the same style as Mudlets handling of other protocols. To see how it's done exactly, check out GMCP, ATCP or Aardwolf 102 examples - but the gist of it is provided below.<br />
<br />
Mudlet has a built-in event system, which is used to broadcast messages in an independent way. With it, people can "trigger" on 102, ATCP or GMCP events with Lua functions that get called whenever an event they're interested in is raised. '''Use the event system to provide your users with a way to react to new protocol data'''.<br />
<br />
Events have names, and optionally, any amount of data with them. For protocol support, Mudlet prefixes the relevant message received name with the protocol name in lowercase. For example, an ATCP Char.Vitals getting updated would raise an event titled "atcp.Char.Vitals". A GMCP Room.Info message would raise a "gmcp.Room.Info" message. <br />
<br />
Additionally, Mudlet also allows catch-all event - in case the user wants to use one event handler for a variety of sub-events (it's not uncommon for games to use ''Main.Sub.Add'', ''Main.Sub.Remove'', ''Main.Sub.List'' to keep track of a list, for example, while conserving data). To accomplish this, it raises events for every relevant namespace - that is, a Main.Sub.Add event will raise ''protocol.Main.Sub'' and ''protocol.Main.Sub.Add events''. While it is entirely possible for one event handler to react to multiple events, this is provided for convenience.<br />
<br />
For storing protocol data, Mudlet uses an aptly named global table - '''gmcp''' for GMCP data, '''atcp''' for ATCP data. Data is stored in the same way it is received and the event is raised for - so a Char.Vitals message's contents will be stored in gmcp.Char.Vitals, a Room.Info's contents in gmcp.Room.Info. If there were was any nested data within the message, it is stored as a table within the proper namespace - ie, a "details" JSON array of a GMCP Room.Info message would be stored in gmcp.Room.Info.details. '''Use a global table with the protocol name in lowerspace for storing permanent data''' that your users will read from.<br />
<br />
That's it! If you'll need any Mudlet-related help, feel free to [http://forums.mudlet.org/viewforum.php?f=9 post on our forums]. Once you're done, [[Mudlet_Packages|package your work]] for distribution which you can optionally post in the [http://forums.mudlet.org/viewforum.php?f=6 finished scripts] section.<br />
<br />
[[Category:Mudlet Manual]]</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:Miscellaneous_Functions&diff=19990Manual:Miscellaneous Functions2022-05-13T21:51:34Z<p>Demonnic: /* setConfig */</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Mudlet API documentation for miscellaneous functions.}}<br />
= Miscellaneous Functions =<br />
<br />
==addFileWatch==<br />
;addFileWatch(path)<br />
:Adds file watch on directory or file. Every change in that file (or directory) will raise [[Manual:Event_Engine#sysPathChanged|sysPathChanged]] event.<br />
<br />
:See also: [[#removeFileWatch|removeFileWatch()]]<br />
<br />
{{MudletVersion|4.12}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
herbs = {}<br />
local herbsPath = getMudletHomeDir() .. "/herbs.lua"<br />
function herbsChangedHandler(_, path)<br />
if path == herbsPath then<br />
table.load(herbsPath, herbs)<br />
removeFileWatch(herbsPath)<br />
end<br />
end<br />
<br />
addFileWatch(herbsPath)<br />
registerAnonymousEventHandler("sysPathChanged", "herbsChangedHandler")<br />
</syntaxhighlight><br />
<br />
==addSupportedTelnetOption==<br />
;addSupportedTelnetOption(option)<br />
: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.<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
<event handlers that add support for MSDP... see http://www.mudbytes.net/forum/comment/63920/#c63920 for an example><br />
<br />
-- register with Mudlet that it should not decline the request of MSDP support<br />
local TN_MSDP = 69<br />
addSupportedTelnetOption(TN_MSDP)<br />
</syntaxhighlight><br />
<br />
==alert==<br />
;alert([seconds])<br />
:alerts the user to something happening - makes Mudlet flash in the Windows window bar, bounce in the macOS dock, or flash on Linux.<br />
<br />
{{MudletVersion|3.2}}<br />
<br />
;Parameters<br />
* ''seconds:''<br />
:(optional) number of seconds to have the alert for. If not provided, Mudlet will flash until the user opens Mudlet again.<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- flash indefinitely until Mudlet is open<br />
alert()<br />
<br />
-- flash for just 3 seconds<br />
alert(3)<br />
</syntaxhighlight><br />
<br />
==cfeedTriggers==<br />
;cfeedTriggers(text)<br />
:Like feedTriggers, but you can add color information using color names, similar to cecho.<br />
<br />
;Parameters<br />
* ''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.<br />
:See also: [[#feedTriggers|feedTriggers]]<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
cfeedTriggers("<green:red>green on red<r> reset <124:100> foreground of ANSI124 and background of ANSI100<r>\n")<br />
</syntaxhighlight><br />
<br />
==closeMudlet==<br />
;closeMudlet()<br />
<br />
:Closes Mudlet and all profiles immediately.<br />
:See also: [[Manual:Lua_Functions#saveProfile|saveProfile()]]<br />
<br />
{{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!<br />
<br />
{{MudletVersion|3.1}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
closeMudlet()<br />
</syntaxhighlight><br />
<br />
==deleteAllNamedEventHandlers==<br />
; deleteAllNamedEventHandlers(userName)<br />
<br />
:Deletes all named event handlers for userName and prevents them from firing any more. Information is deleted and cannot be retrieved.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#stopNamedEventHandler|stopNamedEventHandler()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
deleteAllNamedEventHandlers("Demonnic") -- emergency stop or debugging situation, most likely.<br />
</syntaxhighlight><br />
<br />
==deleteNamedEventHandler==<br />
; success = deleteNamedEventHandler(userName, handlerName)<br />
<br />
:Deletes a named event handler with name handlerName and prevents it from firing any more. Information is deleted and cannot be retrieved.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#stopNamedEventHandler|stopNamedEventHandler()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
* ''handlerName:''<br />
: The name of the handler to stop. Same as used when you called [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]]<br />
<br />
;Returns <br />
* true if successful, false if it didn't exist<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local deleted = deletedNamedEventHandler("Demonnic", "Vitals")<br />
if deleted then<br />
cecho("Vitals deleted forever!!")<br />
else<br />
cecho("Vitals doesn't exist and so could not be deleted.")<br />
end<br />
</syntaxhighlight><br />
<br />
==denyCurrentSend==<br />
;denyCurrentSend()<br />
<br />
:Cancels a [[Manual:Lua_Functions#send|send()]] or user-entered command, but only if used within a [[Manual:Event_Engine#sysDataSendRequest|sysDataSendRequest]] event.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- cancels all "eat hambuger" commands<br />
function cancelEatHamburger(event, command)<br />
if command == "eat hamburger" then<br />
denyCurrentSend()<br />
cecho("<red>Denied! Didn't let the command through.\n")<br />
end<br />
end<br />
<br />
registerAnonymousEventHandler("sysDataSendRequest", "cancelEatHamburger")<br />
</syntaxhighlight><br />
<br />
==dfeedTriggers==<br />
;dfeedTriggers(str)<br />
:Like feedTriggers, but you can add color information using <r,g,b>, similar to decho.<br />
<br />
;Parameters<br />
* ''str'': The string to feed to the trigger engine. Include color information inside tags like decho.<br />
;See also: [[Manual:Lua_Functions#cfeedTriggers|cfeedTriggers]], [[Manual:Lua_Functions#decho|decho]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
dfeedTriggers("<0,128,0:128,0,0>green on red<r> reset\n")<br />
</syntaxhighlight><br />
<br />
==disableModuleSync==<br />
;disableModuleSync(name)<br />
: Stops syncing the given module.<br />
<br />
;Parameter<br />
* ''name'': name of the module.<br />
<br />
:See also: [[Manual:Lua_Functions#enableModuleSync|enableModuleSync()]], [[Manual:Lua_Functions#getModuleSync|getModuleSync()]]<br />
{{MudletVersion|4.8}}<br />
<br />
==enableModuleSync==<br />
;enableModuleSync(name)<br />
: 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.<br />
<br />
;Parameter<br />
* ''name'': name of the module to enable sync on.<br />
<br />
:See also: [[Manual:Lua_Functions#disableModuleSync|disableModuleSync()]], [[Manual:Lua_Functions#getModuleSync|getModuleSync()]]<br />
{{MudletVersion|4.8}}<br />
<br />
==expandAlias==<br />
;expandAlias(command, [echoBackToBuffer])<br />
: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. <br />
<br />
;Parameters<br />
* ''command''<br />
: Text of the command you want to send to the game. Will be checked for aliases.<br />
* ''echoBackToBuffer''<br />
: (optional) If ''false'', the command will not be echoed back in your buffer. Defaults to ''true'' if omitted.<br />
<br />
{{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.<br />
<br />
{{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.<br />
<br />
{{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.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
expandAlias("t rat")<br />
<br />
-- don't echo the command<br />
expandAlias("t rat", false)<br />
</syntaxhighlight><br />
<br />
==feedTriggers==<br />
;feedTriggers(text[, dataIsUtf8Encoded = true])<br />
: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.<br />
<br />
;Parameters<br />
* ''text:''<br />
: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''. <br />
* ''dataIsUtf8Encoded'' (available in Mudlet 4.2+):<br />
:Set this to false, if you need pre-Mudlet 4.0 behavior. Most players won't need this.<br />
:(Before Mudlet 4.0 the text had to be encoded directly in whatever encoding the setting in the preferences was set to. <br />
:(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)<br />
: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.<br />
: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.)<br />
<br />
;Returns (available in Mudlet 4.2+):<br />
* ''true'' on success, ''nil'' and an error message if the text contains characters that cannot be conveyed by the current Game Server encoding.<br />
<br />
{{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.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- try using this on the command line<br />
`echo This is a sample line from the game<br />
<br />
-- 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:<br />
feedTriggers("\nYou sit yourself down.\n")<br />
<br />
-- The function also accept ANSI color codes that are used in games. A sample table can be found http://codeworld.wikidot.com/ansicolorcodes<br />
feedTriggers("\nThis is \27[1;32mgreen\27[0;37m, \27[1;31mred\27[0;37m, \27[46mcyan background\27[0;37m," ..<br />
"\27[32;47mwhite background and green foreground\27[0;37m.\n")<br />
</syntaxhighlight><br />
<br />
==getCharacterName==<br />
;getCharacterName()<br />
<br />
: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.<br />
<br />
:See also: [[#getProfileName|getProfileName()]]<br />
<br />
{{MudletVersion|4.16}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- cast glamor on yourself<br />
<br />
send("cast 'glamor' " .. getCharacterName())<br />
</syntaxhighlight><br />
<br />
==getModulePath==<br />
;path = getModulePath(module name)<br />
<br />
: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><br />
:See also: [[Manual:Lua_Functions#installModule|installModule()]]<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
getModulePath("mudlet-mapper")<br />
</syntaxhighlight><br />
<br />
==getModulePriority==<br />
;priority = getModulePriority(module name)<br />
<br />
: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.<br />
:Modules with priority <code>-1</code> will be loaded before scripts (Mudlet 4.11+).<br />
<br />
:See also: [[Manual:Lua_Functions#setModulePriority|setModulePriority()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
getModulePriority("mudlet-mapper")<br />
</syntaxhighlight><br />
<br />
==getModules==<br />
;getModules()<br />
<br />
:Returns installed modules as table.<br />
<br />
:See also: [[#getPackages|getPackages]]<br />
<br />
{{MudletVersion|4.12}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--Check if the module myTabChat is installed and if it isn't install it and enable sync on it<br />
if not table.contains(getModules(),"myTabChat") then<br />
installModule(getMudletHomeDir().."/modules/myTabChat.xml")<br />
enableModuleSync("myTabChat")<br />
end<br />
<br />
</syntaxhighlight><br />
<br />
==getModuleInfo==<br />
;getModuleInfo(moduleName, [info])<br />
<br />
:Returns table with meta information for a package<br />
<br />
;Parameters<br />
* ''moduleName:''<br />
:Name of the package<br />
* ''info:''<br />
:(optional) specific info wanted to get, if not given all available meta-info is returned<br />
<br />
:See also: [[#getPackageInfo|getPackageInfo]], [[#setModuleInfo|getModuleInfo]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
getModuleInfo("myModule","author")<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.12}}<br />
<br />
==getModuleSync==<br />
;getModuleSync(name)<br />
: returns false if module sync is not active, true if it is active and nil if module is not found.<br />
<br />
;Parameter<br />
* ''name'': name of the module<br />
<br />
:See also: [[Manual:Lua_Functions#enableModuleSync|enableModuleSync()]], [[Manual:Lua_Functions#disableModuleSync|disableModuleSync()]]<br />
{{MudletVersion|4.8}}<br />
<br />
==getMudletHomeDir==<br />
;getMudletHomeDir()<br />
: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.<br />
<br />
{{note}} intentionally uses forward slashes <code>/</code> as separators on Windows since [[Manual:UI_Functions#setLabelStyleSheet|stylesheets]] require them.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- save a table<br />
table.save(getMudletHomeDir().."/myinfo.dat", myinfo)<br />
<br />
-- or access package data. The forward slash works even on Windows fine<br />
local path = getMudletHomeDir().."/mypackagename"<br />
</syntaxhighlight><br />
<br />
==getMudletInfo==<br />
;getMudletInfo()<br />
:Prints debugging information about the Mudlet that you're running - this can come in handy for diagnostics.<br />
<br />
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.<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
getMudletInfo()<br />
</syntaxhighlight><br />
<br />
==getMudletVersion==<br />
;getMudletVersion(style)<br />
: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.<br />
<br />
See also: [[#mudletOlderThan|mudletOlderThan()]]<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
;Parameters<br />
* ''style:''<br />
:(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.<br />
<br />
;Values you can choose<br />
* ''"string"'':<br />
:Returns the full Mudlet version as text.<br />
* ''"table"'':<br />
:Returns the full Mudlet version as four values (multi-return)<br />
* ''"major"'':<br />
:Returns the major version number (the first one).<br />
* ''"minor"'':<br />
:Returns the minor version number (the second one).<br />
* ''"revision"'':<br />
:Returns the revision version number (the third one).<br />
* ''"build"'':<br />
:Returns the build of Mudlet (the ending suffix, if any).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- see the full Mudlet version as text:<br />
getMudletVersion("string")<br />
-- returns for example "3.0.0-alpha"<br />
<br />
-- check that the major Mudlet version is at least 3:<br />
if getMudletVersion("major") >= 3 then echo("You're running on Mudlet 3+!") end<br />
-- but mudletOlderThan() is much better for this:<br />
if mudletOlderThan(3) then echo("You're running on Mudlet 3+!") end <br />
<br />
-- if you'd like to see if a function is available however, test for it explicitly instead:<br />
if setAppStyleSheet then<br />
-- example credit to http://qt-project.org/doc/qt-4.8/stylesheet-examples.html#customizing-qscrollbar<br />
setAppStyleSheet[[<br />
QScrollBar:vertical {<br />
border: 2px solid grey;<br />
background: #32CC99;<br />
width: 15px;<br />
margin: 22px 0 22px 0;<br />
}<br />
QScrollBar::handle:vertical {<br />
background: white;<br />
min-height: 20px;<br />
}<br />
QScrollBar::add-line:vertical {<br />
border: 2px solid grey;<br />
background: #32CC99;<br />
height: 20px;<br />
subcontrol-position: bottom;<br />
subcontrol-origin: margin;<br />
}<br />
QScrollBar::sub-line:vertical {<br />
border: 2px solid grey;<br />
background: #32CC99;<br />
height: 20px;<br />
subcontrol-position: top;<br />
subcontrol-origin: margin;<br />
}<br />
QScrollBar::up-arrow:vertical, QScrollBar::down-arrow:vertical {<br />
border: 2px solid grey;<br />
width: 3px;<br />
height: 3px;<br />
background: white;<br />
}<br />
QScrollBar::add-page:vertical, QScrollBar::sub-page:vertical {<br />
background: none;<br />
}<br />
]]<br />
end<br />
</syntaxhighlight><br />
<br />
==getNewIDManager==<br />
; getNewIDManager()<br />
<br />
:Returns an IDManager object, for manager your own set of named events and timers isolated from the rest of the profile.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#registerNamedTimer|registerNamedTimer()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
{{note}} Full IDManager usage can be found at [[Manual:IDManager|IDManager]]<br />
<br />
;Returns<br />
* an IDManager for managing your own named events and timers<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
demonnic = demonnic or {}<br />
demonnic.IDManager = getNewIDManager()<br />
local idm = demonnic.IDManager<br />
-- assumes you have defined demonnic.vitalsUpdate and demonnic.balanceChecker as functions<br />
idm:registerEvent("DemonVitals", "gmcp.Char.Vitals", demonnic.vitalsUpdate)<br />
idm:registerTimer("Balance Check", 1, demonnic.balanceChecker)<br />
idm:stopEvent("DemonVitals")<br />
</syntaxhighlight><br />
<br />
==getNamedEventHandlers==<br />
; handlers = getNamedEventHandlers(userName)<br />
<br />
:Returns a list of all userName's named event handlers' names as a table.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
<br />
;Returns <br />
* a table of handler names. { "DemonVitals", "DemonInv" } for example. {} if none are registered<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local handlers = getNamedEventHandlers()<br />
display(handlers)<br />
-- {}<br />
registerNamedEventHandler("Test1", "testEvent", "testFunction")<br />
registerNamedEventHandler("Test2", "someOtherEvent", myHandlerFunction)<br />
handlers = getNamedEventHandlers()<br />
display(handlers)<br />
-- { "Test1", "Test2" }<br />
</syntaxhighlight><br />
<br />
==getOS==<br />
;getOS()<br />
<br />
: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. <br />
:Returned text will be one of these: "cygwin", "windows", "mac", "linux", "hurd", "freebsd", "kfreebsd", "openbsd", "netbsd", "bsd4", "unix" or "unknown" otherwise.<br />
:Additionally returns the version of the OS, and if using Linux, the distribution in use (as of Mudlet 4.12+).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getOS())<br />
<br />
if getOS() == "windows" then<br />
echo("\nWindows OS detected.\n")<br />
else<br />
echo("\nDetected Operating system is NOT windows.\n")<br />
end<br />
<br />
if mudlet.supports.osVersion then<br />
local os, osversion = getOS()<br />
print(f"Running {os} {osversion}")<br />
end<br />
</syntaxhighlight><br />
<br />
==getPackages==<br />
;getPackages()<br />
<br />
:Returns installed packages as table.<br />
<br />
:See also: [[#getModules|getModules]]<br />
<br />
{{MudletVersion|4.12}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--Check if the generic_mapper package is installed and if so uninstall it<br />
if table.contains(getPackages(),"generic_mapper") then<br />
uninstallPackage("generic_mapper")<br />
end<br />
<br />
</syntaxhighlight><br />
<br />
==getPackageInfo==<br />
;getPackageInfo(packageName, [info])<br />
<br />
:Returns table with meta information for a package<br />
<br />
;Parameters<br />
* ''packageName:''<br />
:Name of the package<br />
* ''info:''<br />
:(optional) specific info wanted to get, if not given all available meta-info is returned<br />
<br />
:See also: [[#getModuleInfo|getModuleInfo]], [[#setPackageInfo|getPackageInfo]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
getPackageInfo("myPackage", "version")<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.12}}<br />
<br />
==getProfileName==<br />
;getProfileName()<br />
<br />
: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.<br />
<br />
{{MudletVersion|3.1}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- if connected to the Achaea profile, will print Achaea to the main console<br />
echo(getProfileName())<br />
</syntaxhighlight><br />
<br />
==getCommandSeparator==<br />
;getCommandSeparator()<br />
<br />
:Returns the command separator in use by the profile.<br />
<br />
{{MudletVersion|3.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- if your command separator is ;;, the following would send("do thing 1;;do thing 2"). <br />
-- This way you can determine what it is set to and use that and share this script with <br />
-- someone who has changed their command separator.<br />
-- Note: This is not really the preferred way to send this, using sendAll("do thing 1", "do thing 2") is,<br />
-- but this illustates the use case.<br />
local s = getCommandSeparator()<br />
expandAlias("do thing 1" .. s .. "do thing 2")<br />
</syntaxhighlight><br />
<br />
==getServerEncoding==<br />
;getServerEncoding()<br />
:Returns the current server [https://www.w3.org/International/questions/qa-what-is-encoding data encoding] in use.<br />
<br />
:See also: [[#setServerEncoding|setServerEncoding()]], [[#getServerEncodingsList|getServerEncodingsList()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
getServerEncoding()<br />
</syntaxhighlight><br />
<br />
==getServerEncodingsList==<br />
;getServerEncodingsList()<br />
: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.<br />
<br />
:See also: [[#setServerEncoding|setServerEncoding()]], [[#getServerEncoding|getServerEncoding()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- check if UTF-8 is available:<br />
if table.contains(getServerEncodingsList(), "UTF-8") then<br />
print("UTF-8 is available!")<br />
end<br />
</syntaxhighlight><br />
<br />
==getWindowsCodepage==<br />
;getWindowsCodepage()<br />
:Returns the current [https://docs.microsoft.com/en-us/windows/desktop/Intl/code-page-identifiers codepage] of your Windows system.<br />
<br />
{{MudletVersion|3.22}}<br />
{{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.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
print(getWindowsCodepage())<br />
</syntaxhighlight><br />
<br />
==hfeedTriggers==<br />
;hfeedTriggers(str)<br />
:Like feedTriggers, but you can add color information using #RRGGBB in hex, similar to hecho.<br />
<br />
;Parameters<br />
* ''str'': The string to feed to the trigger engine. Include color information in the same manner as hecho.<br />
:See also: [[Manual:Lua_Functions#dfeedTriggers|dfeedTriggers]]<br />
:See also: [[Manual:Lua_Functions#hecho|hecho]]<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
hfeedTriggers("#008000,800000green on red#r reset\n")<br />
</syntaxhighlight><br />
<br />
==installModule==<br />
;installModule(location)<br />
:Installs a Mudlet XML, zip, or mpackage as a module.<br />
<br />
;Parameters<br />
* ''location:''<br />
:Exact location of the file install.<br />
<br />
:See also: [[#uninstallModule | uninstallModule()]], [[Manual:Event_Engine#sysLuaInstallModule | Event: sysLuaInstallModule]], [[#setModulePriority | setModulePriority()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
installModule([[C:\Documents and Settings\bub\Desktop\myalias.xml]])<br />
</syntaxhighlight><br />
<br />
==installPackage==<br />
;installPackage(location or url)<br />
:Installs a Mudlet XML or package. Since Mudlet 4.11+ returns <code>true</code> if it worked, or <code>false</code>.<br />
<br />
;Parameters<br />
* ''location:''<br />
:Exact location of the xml or package to install.<br />
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>)<br />
<br />
:See also: [[#uninstallPackage | uninstallPackage()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
installPackage([[C:\Documents and Settings\bub\Desktop\myalias.xml]])<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
installPackage([[https://github.com/Mudlet/Mudlet/blob/development/src/run-lua-code-v4.xml]])<br />
</syntaxhighlight><br />
<br />
==killAnonymousEventHandler==<br />
;killAnonymousEventHandler(handler id)<br />
:Disables and removes the given event handler.<br />
<br />
;Parameters<br />
* ''handler id''<br />
:ID of the event handler to remove as returned by the [[ #registerAnonymousEventHandler | registerAnonymousEventHandler ]] function.<br />
<br />
:See also: [[ #registerAnonymousEventHandler | registerAnonymousEventHandler ]]<br />
<br />
{{MudletVersion|3.5}}<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- registers an event handler that prints the first 5 GMCP events and then terminates itself<br />
<br />
local counter = 0<br />
local handlerId = registerAnonymousEventHandler("gmcp", function(_, origEvent)<br />
print(origEvent)<br />
counter = counter + 1<br />
if counter == 5 then<br />
killAnonymousEventHandler(handlerId)<br />
end<br />
end)<br />
</syntaxhighlight><br />
<br />
==loadMusicFile==<br />
;loadMusicFile(settings table)<br />
: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. <br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! style="text-align:left;"| Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;"| Yes<br />
| name<br />
| <file name><br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
* May contain directory information (i.e. weather/lightning.wav).<br />
* May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")<br />
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")<br />
|- style="color: blue;"<br />
| style="text-align:center;"| Maybe<br />
| url<br />
| <url><br />
| style="text-align:left;"|<br />
* Resource location where the media file may be downloaded.<br />
* Only required if file to load is not part of the profile or on the local file system.<br />
|-<br />
|}<br />
<br />
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]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Download from the Internet<br />
loadMusicFile({<br />
name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
, url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"<br />
})<br />
<br />
-- OR download from the profile<br />
loadMusicFile({name = getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3"})<br />
<br />
-- OR download from the local file system<br />
loadMusicFile({name = "C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3"})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of loadMediaFile(name[, url]) ----<br />
<br />
-- Download from the Internet<br />
loadMusicFile(<br />
"167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
, "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"<br />
)<br />
<br />
-- OR download from the profile<br />
loadMusicFile(getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3")<br />
<br />
-- OR download from the local file system<br />
loadMusicFile("C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3")<br />
</syntaxhighlight><br />
<br />
==loadSoundFile==<br />
;loadSoundFile(settings table)<br />
: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. <br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! style="text-align:left;"| Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;"| Yes<br />
| name<br />
| <file name><br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
* May contain directory information (i.e. weather/lightning.wav).<br />
* May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")<br />
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")<br />
|- style="color: blue;"<br />
| style="text-align:center;"| Maybe<br />
| url<br />
| <url><br />
| style="text-align:left;"|<br />
* Resource location where the media file may be downloaded.<br />
* Only required if file to load is not part of the profile or on the local file system.<br />
|-<br />
|}<br />
<br />
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]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Download from the Internet<br />
loadSoundFile({<br />
name = "cow.wav"<br />
, url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"<br />
})<br />
<br />
-- OR download from the profile<br />
loadSoundFile({name = getMudletHomeDir().. "/cow.wav"})<br />
<br />
-- OR download from the local file system<br />
loadSoundFile({name = "C:/Users/Tamarindo/Documents/cow.wav"})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of loadSoundFile(name[,url]) ----<br />
<br />
-- Download from the Internet<br />
loadSoundFile("cow.wav", "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/")<br />
<br />
-- OR download from the profile<br />
loadSoundFile(getMudletHomeDir().. "/cow.wav")<br />
<br />
-- OR download from the local file system<br />
loadSoundFile("C:/Users/Tamarindo/Documents/cow.wav")<br />
</syntaxhighlight><br />
<br />
==mudletOlderThan==<br />
;mudletOlderThan(major, [minor], [patch])<br />
: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.<br />
<br />
See also: [[#getMudletVersion|getMudletVersion()]]<br />
<br />
;Parameters<br />
* ''major:''<br />
: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.<br />
* ''minor:''<br />
:(optional) minor version to check.<br />
* ''patch:''<br />
:(optional) patch version to check.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- stop doing the script of Mudlet is older than 3.2<br />
if mudletOlderThan(3,2) then return end<br />
<br />
-- or older than 2.1.3<br />
if mudletOlderThan(2, 1, 3) then return end<br />
<br />
-- however, if you'd like to check that a certain function is available, like getMousePosition(), do this instead:<br />
if not getMousePosition then return end<br />
<br />
-- if you'd like to check that coroutines are supported, do this instead:<br />
if not mudlet.supportscoroutines then return end<br />
</syntaxhighlight><br />
<br />
==openWebPage==<br />
;openWebPage(URL)<br />
:Opens the browser to the given webpage.<br />
<br />
;Parameters<br />
* ''URL:''<br />
:Exact URL to open.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
openWebPage("http://google.com")<br />
</syntaxhighlight><br />
<br />
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://".<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
openWebPage("file:///"..getMudletHomeDir().."file.txt")<br />
</syntaxhighlight><br />
<br />
==playMusicFile==<br />
;playMusicFile(settings table)<br />
: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()]].<br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! Default<br />
! style="text-align:left;"| Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;"| Yes<br />
| name<br />
| <file name><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
* May contain directory information (i.e. weather/lightning.wav).<br />
* May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")<br />
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")<br />
* Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.<br />
|-<br />
| style="text-align:center;"| No<br />
| volume<br />
| 1 to 100<br />
| 50<br />
| style="text-align:left;"|<br />
* Relative to the volume set on the player's client.<br />
|-<br />
| style="text-align:center;"| No<br />
| fadein<br />
|<msec><br />
|<br />
|<br />
*Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.<br />
*Start position: Start of media.<br />
*End position: Start of media plus the number of milliseconds (msec) specified.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
| fadeout<br />
|<msec><br />
|<br />
|<br />
*Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.<br />
*Start position: End of the media minus the number of milliseconds (msec) specified.<br />
*End position: End of the media.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;"| No<br />
| start<br />
| <msec><br />
| 0<br />
| style="text-align:left;"|<br />
* Begin play at the specified position in milliseconds.<br />
|-<br />
| style="text-align:center;" |No<br />
| loops<br />
| -1, or >= 1<br />
|1<br />
| style="text-align:left;" |<br />
*Number of iterations that the media plays.<br />
* A value of -1 allows the media to loop indefinitely.<br />
|-<br />
| style="text-align:center;" |No<br />
| key <br />
|<key><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;"| No<br />
| tag<br />
| <tag><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Helps categorize media.<br />
|-<br />
| style="text-align:center;" |No<br />
| continue <br />
| true or false<br />
| true<br />
| style="text-align:left;" |<br />
*Continues playing matching new music files when true.<br />
*Restarts matching new music files when false.<br />
|- style="color: blue;"<br />
| style="text-align:center;"| Maybe<br />
| url<br />
| <url><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Resource location where the media file may be downloaded.<br />
* Only required if the file is to be downloaded remotely.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Play a music file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playMusicFile({<br />
name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
})<br />
<br />
-- OR copy once from the game's profile, and play a music file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playMusicFile({<br />
name = getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
, volume = 75<br />
})<br />
<br />
-- OR copy once from the local file system, and play a music file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playMusicFile({<br />
name = "C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
, volume = 75<br />
})<br />
<br />
-- OR download once from the Internet, and play music stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 20 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 53 seconds from the end of the music<br />
---- [start] 10 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [key] reference of "rugby" for stopping this unique music later<br />
---- [tag] reference of "ambience" to stop and music later with the same tag<br />
---- [continue] playing this music if another request for the same music comes in (false restarts it) <br />
---- [url] to download once from the Internet if the music does not exist in the profile's media directory<br />
playMusicFile({<br />
name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
, volume = nil -- nil lines are optional, no need to use<br />
, fadein = 20000<br />
, fadein = 53000<br />
, start = 10000<br />
, loops = nil -- nil lines are optional, no need to use<br />
, key = "rugby"<br />
, tag = "ambience"<br />
, continue = true<br />
, url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of playMusicFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,continue][,url]) ----<br />
<br />
-- Play a music file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playMusicFile(<br />
"167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name<br />
)<br />
<br />
-- OR copy once from the game's profile, and play a music file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playMusicFile(<br />
getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR copy once from the local file system, and play a music file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playMusicFile(<br />
"C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR download once from the Internet, and play music stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 20 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 53 seconds from the end of the music<br />
---- [start] 10 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [key] reference of "rugby" for stopping this unique music later<br />
---- [tag] reference of "ambience" to stop and music later with the same tag<br />
---- [continue] playing this music if another request for the same music comes in (false restarts it) <br />
---- [url] to download once from the Internet if the music does not exist in the profile's media directory<br />
playMusicFile(<br />
"167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name<br />
, nil -- volume<br />
, 20000 -- fadein<br />
, 53000 -- fadeout<br />
, 10000 -- start<br />
, nil -- loops<br />
, "rugby" -- key <br />
, "ambience" -- tag<br />
, true -- continue<br />
, "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/" -- url<br />
)<br />
</syntaxhighlight><br />
<br />
==playSoundFile==<br />
;playSoundFile(settings table)<br />
: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()]].<br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! Default<br />
! style="text-align:left;"| Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;"| Yes<br />
| name<br />
| <file name><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
* May contain directory information (i.e. weather/lightning.wav).<br />
* May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")<br />
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")<br />
* Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.<br />
|-<br />
| style="text-align:center;"| No<br />
| volume<br />
| 1 to 100<br />
| 50<br />
| style="text-align:left;"|<br />
* Relative to the volume set on the player's client.<br />
|-<br />
| style="text-align:center;"| No<br />
| fadein<br />
|<msec><br />
|<br />
|<br />
*Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.<br />
*Start position: Start of media.<br />
*End position: Start of media plus the number of milliseconds (msec) specified.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
| fadeout<br />
|<msec><br />
|<br />
|<br />
*Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.<br />
*Start position: End of the media minus the number of milliseconds (msec) specified.<br />
*End position: End of the media.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;"| No<br />
| start<br />
| <msec><br />
| 0<br />
| style="text-align:left;"|<br />
* Begin play at the specified position in milliseconds.<br />
|-<br />
| style="text-align:center;" |No<br />
| loops<br />
| -1, or >= 1<br />
|1<br />
| style="text-align:left;" |<br />
*Number of iterations that the media plays.<br />
* A value of -1 allows the media to loop indefinitely.<br />
|-<br />
| style="text-align:center;" |No<br />
| key <br />
|<key><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;"| No<br />
| tag<br />
| <tag><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Helps categorize media.<br />
|-<br />
| style="text-align:center;" |No<br />
| priority<br />
| 1 to 100<br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Halts the play of current or future played media files with a lower priority while this media plays.<br />
|- style="color: blue;"<br />
| style="text-align:center;"| Maybe<br />
| url<br />
| <url><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Resource location where the media file may be downloaded.<br />
* Only required if the file is to be downloaded remotely.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Play a sound file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playSoundFile({<br />
name = "cow.wav"<br />
})<br />
<br />
-- OR copy once from the game's profile, and play a sound file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playSoundFile({<br />
name = getMudletHomeDir().. "/cow.wav"<br />
, volume = 75<br />
})<br />
<br />
-- OR copy once from the local file system, and play a sound file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playSoundFile({<br />
name = "C:/Users/Tamarindo/Documents/cow.wav"<br />
, volume = 75<br />
})<br />
<br />
-- OR download once from the Internet, and play a sound stored in the profile's media directory<br />
---- [volume] of 75<br />
---- [loops] of 2 (-1 for indefinite repeats, 1+ for finite repeats)<br />
---- [key] reference of "cow" for stopping this unique sound later<br />
---- [tag] reference of "animals" to stop a group of sounds later with the same tag<br />
---- [priority] of 25 (1 to 100, 50 default, a sound with a higher priority would stop this one)<br />
---- [url] to download once from the Internet if the sound does not exist in the profile's media directory<br />
playSoundFile({<br />
name = "cow.wav"<br />
, volume = 75<br />
, fadein = nil -- nil lines are optional, no need to use<br />
, fadeout = nil -- nil lines are optional, no need to use<br />
, start = nil -- nil lines are optional, no need to use<br />
, loops = 2<br />
, key = "cow"<br />
, tag = "animals"<br />
, priority = 25<br />
, url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of playSoundFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,priority][,url]) ----<br />
<br />
-- Play a sound file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playSoundFile(<br />
"cow.wav" -- name<br />
)<br />
<br />
-- OR copy once from the game's profile, and play a sound file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playSoundFile(<br />
getMudletHomeDir().. "/cow.wav" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR copy once from the local file system, and play a sound file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playSoundFile(<br />
"C:/Users/Tamarindo/Documents/cow.wav" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR download once from the Internet, and play a sound stored in the profile's media directory<br />
---- [volume] of 75<br />
---- [loops] of 2 (-1 for indefinite repeats, 1+ for finite repeats)<br />
---- [key] reference of "cow" for stopping this unique sound later<br />
---- [tag] reference of "animals" to stop a group of sounds later with the same tag<br />
---- [priority] of 25 (1 to 100, 50 default, a sound with a higher priority would stop this one)<br />
---- [url] to download once from the Internet if the sound does not exist in the profile's media directory<br />
playSoundFile(<br />
"cow.wav" -- name<br />
, 75 -- volume<br />
, nil -- fadein<br />
, nil -- fadeout<br />
, nil -- start<br />
, 2 -- loops<br />
, "cow" -- key <br />
, "animals" -- tag<br />
, 25 -- priority<br />
, "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/" -- url<br />
)<br />
</syntaxhighlight><br />
<br />
==purgeMediaCache==<br />
;purgeMediaCache()<br />
: 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).<br />
<br />
;Guidance:<br />
<br />
* Instruct a player to type ''lua purgeMediaCache()'' on the command line, or<br />
* Distribute a trigger, button or other scriptable feature for the given profile to call ''purgeMediaCache()''<br />
<br />
: See also: [[Manual:Supported_Protocols#MSP|Supported Protocols MSP]], [[Manual:Scripting#MUD_Client_Media_Protocol|Scripting MCMP]]<br />
<br />
==receiveMSP==<br />
;receiveMSP(command)<br />
: 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.<br />
<br />
: See also: [[Manual:Supported_Protocols#MSP|Supported Protocols MSP]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--Play a cow.wav media file stored in the media folder of the current profile. The sound would play twice at a normal volume.<br />
receiveMSP("!!SOUND(cow.wav L=2 V=50)")<br />
<br />
--Stop any SOUND media files playing stored in the media folder of the current profile.<br />
receiveMSP("!!SOUND(Off)")<br />
<br />
--Play a city.mp3 media file stored in the media folder of the current profile. The music would play once at a low volume.<br />
--The music would continue playing if it was triggered earlier by another room, perhaps in the same area.<br />
receiveMSP([[!!MUSIC(city.mp3 L=1 V=25 C=1)]])<br />
<br />
--Stop any MUSIC media files playing stored in the media folder of the current profile.<br />
receiveMSP("!!MUSIC(Off)")<br />
</syntaxhighlight><br />
<br />
==registerAnonymousEventHandler==<br />
;registerAnonymousEventHandler(event name, functionReference, [one shot])<br />
: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.<br />
<br />
: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.<br />
<br />
:The function returns an ID that can be used in [[Manual:Lua_Functions#killAnonymousEventHandler|killAnonymousEventHandler()]] to unregister the handler again.<br />
<br />
:If you use an asterisk ''("*")'' as the event name, your code will capture all events. Useful for debugging, or integration with external programs.<br />
<br />
{{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.<br />
<br />
{{note}} The ''"*"'' all-events capture was added in Mudlet 4.10.<br />
<br />
;See also<br />
:[[Manual:Lua_Functions#killAnonymousEventHandler|killAnonymousEventHandler()]], [[Manual:Lua_Functions#raiseEvent|raiseEvent()]], [[Manual:Event_Engine#Mudlet-raised_events|list of Mudlet-raised events]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- example taken from the God Wars 2 (http://godwars2.org) Mudlet UI - forces the window to keep to a certain size<br />
function keepStaticSize()<br />
setMainWindowSize(1280,720)<br />
end -- keepStaticSize<br />
<br />
if keepStaticSizeEventHandlerID then killAnonymousEventHandler(keepStaticSizeEventHandlerID) end -- clean up any already registered handlers for this function<br />
keepStatisSizeEventHandlerID = registerAnonymousEventHandler("sysWindowResizeEvent", "keepStaticSize") -- register the event handler and save the ID for later killing<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- simple inventory tracker for GMCP enabled games. This version does not leak any of the methods<br />
-- or tables into the global namespace. If you want to access it, you should export the inventory<br />
-- table via an own namespace.<br />
local inventory = {}<br />
<br />
local function inventoryAdd()<br />
if gmcp.Char.Items.Add.location == "inv" then<br />
inventory[#inventory + 1] = table.deepcopy(gmcp.Char.Items.Add.item)<br />
end<br />
end<br />
if inventoryAddHandlerID then killAnonymousEventHandler(inventoryAddHandlerID) end -- clean up any already registered handlers for this function<br />
inventoryAddHandlerID = registerAnonymousEventHandler("gmcp.Char.Items.Add", inventoryAdd) -- register the event handler and save the ID for later killing<br />
<br />
local function inventoryList()<br />
if gmcp.Char.Items.List.location == "inv" then<br />
inventory = table.deepcopy(gmcp.Char.Items.List.items)<br />
end<br />
end<br />
if inventoryListHandlerID then killAnonymousEventHandler(inventoryListHandlerID) end -- clean up any already registered handlers for this function<br />
inventoryListHandlerID = registerAnonymousEventHandler("gmcp.Char.Items.List", inventoryList) -- register the event handler and save the ID for later killing<br />
<br />
local function inventoryUpdate()<br />
if gmcp.Char.Items.Remove.location == "inv" then<br />
local found<br />
local updatedItem = gmcp.Char.Items.Update.item<br />
for index, item in ipairs(inventory) do<br />
if item.id == updatedItem.id then<br />
found = index<br />
break<br />
end<br />
end<br />
if found then<br />
inventory[found] = table.deepcopy(updatedItem)<br />
end<br />
end<br />
end<br />
if inventoryUpdateHandlerID then killAnonymousEventHandler(inventoryUpdateHandlerID) end -- clean up any already registered handlers for this function<br />
inventoryUpdateHandlerID = registerAnonymousEventHandler("gmcp.Char.Items.Update", inventoryUpdate)<br />
<br />
local function inventoryRemove()<br />
if gmcp.Char.Items.Remove.location == "inv" then<br />
local found<br />
local removedItem = gmcp.Char.Items.Remove.item<br />
for index, item in ipairs(inventory) do<br />
if item.id == removedItem.id then<br />
found = index<br />
break<br />
end<br />
end<br />
if found then<br />
table.remove(inventory, found)<br />
end<br />
end<br />
end<br />
if inventoryRemoveHandlerID then killAnonymousEventHandler(inventoryRemoveHandlerID) end -- clean up any already registered handlers for this function<br />
inventoryRemoveHandlerID = registerAnonymousEventHandler("gmcp.Char.Items.Remove", inventoryRemove)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- downloads a package from the internet and kills itself after it is installed.<br />
local saveto = getMudletHomeDir().."/dark-theme-mudlet.zip"<br />
local url = "http://www.mudlet.org/wp-content/files/dark-theme-mudlet.zip"<br />
<br />
if myPackageInstallHandler then killAnonymousEventHandler(myPackageInstallHandler) end<br />
myPackageInstallHandler = registerAnonymousEventHandler(<br />
"sysDownloadDone",<br />
function(_, filename)<br />
if filename ~= saveto then<br />
return true -- keep the event handler since this was not our file<br />
end<br />
installPackage(saveto)<br />
os.remove(b)<br />
end,<br />
true<br />
)<br />
<br />
downloadFile(saveto, url)<br />
cecho("<white>Downloading <green>"..url.."<white> to <green>"..saveto.."\n")<br />
</syntaxhighlight><br />
<br />
==registerNamedEventHandler==<br />
; success = registerNamedEventHandler(userName, handlerName, eventName, functionReference, [oneShot])<br />
<br />
: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<br />
<br />
;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()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
* ''handlerName:''<br />
: 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.<br />
* ''eventName:''<br />
: The name of the event the handler responds to. [[Manual:Event_Engine#Mudlet-raised_events|See here]] for a list of Mudlet-raised events.<br />
* ''functionReference:''<br />
: The function reference to run when the event comes in. Can be the name of a function, "handlerFuncion", or the lua function itself. <br />
* ''oneShot:''<br />
: (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.<br />
<br />
;Returns <br />
* true if successful, otherwise errors.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- register a named event handler. Will call demonVitalsHandler(eventName, ...) when gmcp.Char.Vitals is raised.<br />
local ok = registerNamedEventHandler("Demonnic", "DemonVitals", "gmcp.Char.Vitals", "demonVitalsHandler")<br />
if ok then<br />
cecho("Vitals handler switched to demonVitalsHandler")<br />
end<br />
<br />
-- something changes later, and we want to handle vitals with another function, demonBlackoutHandler()<br />
-- note we do not use "" around demonBlackoutHandler but instead pass the function itself. Both work.<br />
-- using the same handlerName ("DemonVitals") means it will automatically unregister the old handler<br />
-- and reregister it using the new information.<br />
local ok = registerNamedEventHandler("Demonnic", "DemonVitals", "gmcp.Char.Vitals", demonBlackoutHandler)<br />
if ok then<br />
cecho("Vitals handler switched to demonBlackoutHandler")<br />
end<br />
<br />
-- Now you want to check your inventory, but you only want to do it once, so you pass the optional oneShot as true<br />
local function handleInv()<br />
local list = gmcp.Char.Items.List<br />
if list.location ~= "inventory" then<br />
return true -- if list.location is, say "room" then we need to keep responding until it's "inventory"<br />
end<br />
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<br />
end<br />
<br />
-- you can ignore the response from registerNamedEventHandler if you want, it's always going to be true<br />
-- unless there is an error, in which case it throws the error and halts execution anyway. The return is<br />
-- in part for feedback when using the lua alias or other REPL window.<br />
registerNamedEventHandler("Demonnic", "DemonInvCheck", "gmcp.Char.Items.List", handleInv, true)<br />
</syntaxhighlight><br />
<br />
==reloadModule==<br />
;reloadModule(module name)<br />
:Reload a module (by uninstalling and reinstalling).<br />
<br />
:See also: [[#installModule|installModule()]], [[#uninstallModule|uninstallModule()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
reloadModule("3k-mapper")<br />
</syntaxhighlight><br />
<br />
<br />
==removeFileWatch==<br />
;removeFileWatch(path)<br />
:Remove file watch on directory or file. Every change in that file will no longer raise [[Manual:Event_Engine#sysPathChanged|sysPathChanged]] event.<br />
<br />
:See also: [[#addFileWatch|addFileWatch()]]<br />
<br />
{{MudletVersion|4.12}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
herbs = {}<br />
local herbsPath = getMudletHomeDir() .. "/herbs.lua"<br />
function herbsChangedHandler(_, path)<br />
if path == herbsPath then<br />
table.load(herbsPath, herbs)<br />
removeFileWatch(herbsPath)<br />
end<br />
end<br />
<br />
addFileWatch(herbsPath)<br />
registerAnonymousEventHandler("sysPathChanged", "herbsChangedHandler")<br />
</syntaxhighlight><br />
<br />
==resetProfile==<br />
;resetProfile()<br />
<br />
: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.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
resetProfile()<br />
</syntaxhighlight><br />
<br />
The function used to require input from the game to work, but as of Mudlet 3.20 that is no longer the case.<br />
<br />
<br />
{{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 <br />
<syntaxhighlight lang="lua"><br />
lua resetProfile()<br />
</syntaxhighlight><br />
in your commandline or make an Alias containing resetProfile().<br />
<br />
==resumeNamedEventHandler==<br />
; success = resumeNamedEventHandler(userName, handlerName)<br />
<br />
:Resumes a named event handler with name handlerName and causes it to start firing once more.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#stopNamedEventHandler|stopNamedEventHandler()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
* ''handlerName:''<br />
: The name of the handler to resume. Same as used when you called [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]]<br />
<br />
;Returns <br />
* true if successful, false if it didn't exist.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local resumed = resumeNamedEventHandler("Demonnic", "DemonVitals")<br />
if resumed then<br />
cecho("DemonVitals resumed!")<br />
else<br />
cecho("DemonVitals doesn't exist, cannot resume it")<br />
end<br />
</syntaxhighlight><br />
<br />
==saveProfile==<br />
;saveProfile(location)<br />
<br />
:Saves the current Mudlet profile to disk, which is equivalent to pressing the "Save Profile" button.<br />
<br />
;Parameters<br />
* ''location:''<br />
:(optional) folder to save the profile to. If not given, the profile will go into the [[Mudlet_File_Locations|default location]].<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
saveProfile()<br />
<br />
-- save to the desktop on Windows:<br />
saveProfile([[C:\Users\yourusername\Desktop]])<br />
</syntaxhighlight><br />
<br />
==sendSocket==<br />
;sendSocket(data)<br />
<br />
: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.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
TN_IAC = 255<br />
TN_WILL = 251<br />
TN_DO = 253<br />
TN_SB = 250<br />
TN_SE = 240<br />
TN_MSDP = 69<br />
<br />
MSDP_VAL = 1<br />
MSDP_VAR = 2<br />
<br />
sendSocket( string.char( TN_IAC, TN_DO, TN_MSDP ) ) -- sends IAC DO MSDP<br />
<br />
--sends: IAC SB MSDP MSDP_VAR "LIST" MSDP_VAL "COMMANDS" IAC SE<br />
local msg = string.char( TN_IAC, TN_SB, TN_MSDP, MSDP_VAR ) .. " LIST " ..string.char( MSDP_VAL ) .. " COMMANDS " .. string.char( TN_IAC, TN_SE )<br />
sendSocket( msg )<br />
</syntaxhighlight><br />
<br />
{{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.<br />
<br />
==setConfig==<br />
; setConfig(option, value)<br />
<br />
: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.<br />
:To set many options at once, pass in a table of options. More options will be added over time / per request.<br />
<br />
{{MudletVersion|4.16}}<br />
<br />
;Parameters<br />
* ''option:''<br />
: Particular option to change - see list below for available ones.<br />
* ''value:''<br />
: Value to set - can be a boolean, number, or text depending on the option.<br />
<br />
{| class="wikitable sortable"<br />
|+ General options<br />
|-<br />
! Option !! Description !! Available in Mudlet<br />
|-<br />
| enableGMCP || Enable GMCP (on by default. Reconnect after changing) || 4.16 <br />
|-<br />
| enableMSDP || Enable MSDP (off by default. Reconnect after changing) || 4.16 <br />
|-<br />
| enableMSSP || Enable MSSP (on by default. Reconnect after changing) || 4.16 <br />
|-<br />
| enableMSP || Enable MSP (on by default. Reconnect after changing) || 4.16 <br />
|}<br />
<br />
{| class="wikitable sortable"<br />
|+ Input line<br />
|-<br />
! Option !! Description !! Available in Mudlet<br />
|-<br />
| inputLineStrictUnixEndings || Workaround option to use strict UNIX line endings for sending commands || 4.16 <br />
|-<br />
|}<br />
<br />
{| class="wikitable sortable"<br />
|+ Main display<br />
|-<br />
! Option !! Description !! Available in Mudlet<br />
|-<br />
| fixUnnecessaryLinebreaks || Remove extra linebreaks from output (mostly for IRE servers) || 4.16 <br />
|-<br />
|}<br />
<br />
{| class="wikitable sortable"<br />
|+ Mapper options<br />
|-<br />
! Option !! Description !! Available in Mudlet<br />
|-<br />
| mapRoomSize || Size of rooms on map (a good value is 5) || 4.16<br />
|-<br />
| mapExitSize || Size of exits on map (a good value is 10) || 4.16<br />
|-<br />
| mapRoundRooms || Draw rooms round or square || 4.16<br />
|-<br />
| showRoomIdsOnMap || Show room IDs on all rooms (if zoom permits) || 4.16<br />
|-<br />
| showMapInfo || Map overlay text ('Full' or 'Short', can have both at once) || 4.16<br />
|-<br />
| hideMapInfo || Map overlay text ('Full' or 'Short', hide both to hide info altogether) || 4.16<br />
|-<br />
| show3dMapView || Show map as 3D || 4.16<br />
|-<br />
| mapperPanelVisible || Map controls at the bottom || 4.16<br />
|-<br />
| mapShowRoomBorders || Draw a thin border for every room || 4.16<br />
|}<br />
<br />
{| class="wikitable sortable"<br />
|+ Special options<br />
|-<br />
! Option !! Description !! Available in Mudlet<br />
|-<br />
| specialForceCompressionOff || Workaround option to disable MCCP compression, in case the game server is not working correctly || 4.16 <br />
|-<br />
| specialForceGAOff || Workaround option to disable Telnet Go-Ahead, in case the game server is not working correctly || 4.16 <br />
|-<br />
| specialForceCharsetNegotiationOff || Workaround option to disable automatically setting the correct encoding, in case the game server is not working correctly || 4.16 <br />
|-<br />
| specialForceMxpNegotiationOff || Workaround option to disable MXP, in case the game server is not working correctly || 4.16 <br />
|-<br />
|}<br />
<br />
;Returns <br />
* true if successful, or nil+msg if the option doesn't exist. Setting mapper options requires the mapper being open first.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setConfig("mapRoomSize", 5)<br />
<br />
setConfig({mapRoomSize = 6, mapExitSize = 12})<br />
</syntaxhighlight><br />
<br />
==setMergeTables==<br />
;setMergeTables(module)<br />
: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.<br />
<br />
;Parameters<br />
* ''module:''<br />
:Name(s) of the GMCP or MSDP module(s) that should be merged as a string - this will add it to the existing list.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setMergeTables("Char.Skills", "Char.Vitals")<br />
</syntaxhighlight><br />
<br />
==setModuleInfo==<br />
;setModuleInfo(moduleName, info, value)<br />
<br />
:Sets a specific meta info value for a module<br />
<br />
;Parameters<br />
* ''moduleName:''<br />
:Name of the module<br />
* ''info:''<br />
: specific info to set (for example "version")<br />
* ''value:''<br />
: specific value to set (for example "1.0")<br />
<br />
:See also: [[#getModuleInfo|getModuleInfo]], [[#setPackageInfo|getPackageInfo]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setModuleInfo("myModule", "version", "1.0")<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.12}}<br />
<br />
==setModulePriority==<br />
;setModulePriority(moduleName, priority)<br />
<br />
: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.<br />
: Modules with priority <code>-1</code> will be loaded before scripts (Mudlet 4.11+).<br />
<br />
: See also: [[#getModulePriority|getModulePriority()]]<br />
<br />
<syntaxhighlight lang="lua"><br />
setModulePriority("mudlet-mapper", 1)<br />
</syntaxhighlight><br />
<br />
==setPackageInfo==<br />
;setPackageInfo(packageName, info, value)<br />
<br />
:Sets a specific meta info value for a package<br />
<br />
;Parameters<br />
* ''packageName:''<br />
:Name of the module<br />
* ''info:''<br />
: specific info to set (for example "version")<br />
* ''value:''<br />
: specific value to set (for example "1.0")<br />
<br />
:See also: [[#getPackageInfo|getPackageInfo]], [[#setModuleInfo|setModuleInfo]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setPackageInfo("myPackage", "title", "This is my test package")<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.12}}<br />
<br />
==setServerEncoding==<br />
;setServerEncoding(encoding)<br />
:Makes Mudlet use the specified [https://www.w3.org/International/questions/qa-what-is-encoding encoding] for communicating with the game.<br />
<br />
;Parameters<br />
* ''encoding:''<br />
:Encoding to use.<br />
<br />
:See also: [[#getServerEncodingsList|getServerEncodingsList()]], [[#getServerEncoding|getServerEncoding()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- use UTF-8 if Mudlet knows it. Unfortunately there's no way to check if the game's server knows it too.<br />
if table.contains(getServerEncodingsList(), "UTF-8") then<br />
setServerEncoding("UTF-8")<br />
end<br />
</syntaxhighlight><br />
<br />
==showNotification==<br />
;showNotification(title, [content], [expiryTimeInSeconds])<br />
<br />
:Shows a native (system) notification.<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
{{Note}} This might not work on all systems, this depends on the system.<br />
<br />
;Parameters<br />
* ''title'' - plain text notification title<br />
* ''content'' - optional argument, plain text notification content, if omitted title argument will be used as content as well<br />
* ''expiryTimeInSeconds'' - optional argument, sets expiration time in seconds for notification, very often ignored by OS<br />
<br />
<syntaxhighlight lang="lua"><br />
showNotification("Notification title", "Notification content", 5)<br />
</syntaxhighlight><br />
<br />
==spawn==<br />
;spawn(readFunction, processToSpawn[, ...arguments])<br />
<br />
: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()''.<br />
<br />
:This allows you to setup RPC communication with another process.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- simple example on a program that quits right away, but prints whatever it gets using the 'display' function<br />
local f = spawn(display, "ls")<br />
display(f.isRunning())<br />
f.close()<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
local f = spawn(display, "ls", "-la")<br />
display(f.isRunning())<br />
f.close()<br />
</syntaxhighlight><br />
<br />
==startLogging==<br />
;startLogging(state)<br />
<br />
: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.<br />
<br />
;Parameters<br />
* ''state:''<br />
:Required: logging state. Passed as a boolean<br />
<br />
;Returns (4 values)<br />
* ''successful (bool)''<br />
:''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).<br />
* ''message (string)''<br />
: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''.<br />
* ''fileName (string)''<br />
:The log will be/is being written to the path/file name returned.<br />
* ''code (number)''<br />
:A value indicating the response to the system to this instruction:<br />
* 0 = logging has just stopped<br />
* 1 = logging has just started<br />
* -1 = logging was already in progress so no change in logging state<br />
* -2 = logging was already not in progress so no change in logging state<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- start logging<br />
local success, message, filename, code = startLogging(true)<br />
if code == 1 or code == -1 then print(f"Started logging to {filename}") end<br />
<br />
-- stop logging<br />
startLogging(false)<br />
</syntaxhighlight><br />
<br />
==stopAllNamedEventHandlers==<br />
; stopAllNamedEventHandlers(userName)<br />
<br />
:Stops all named event handlers and prevents them from firing any more. Information is retained and handlers can be resumed.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#stopNamedEventHandler|stopNamedEventHandler()]], [[Manual:Lua_Functions#resumeNamedEventHandler|resumeNamedEventHandler()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameter<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
stopAllNamedEventHandlers() -- emergency stop situation, most likely.<br />
</syntaxhighlight><br />
<br />
==stopMusic==<br />
;stopMusic(settings table)<br />
: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()]].<br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! style="text-align:left;"| Purpose<br />
|-<br />
| style="text-align:center;"| No<br />
| name<br />
| <file name><br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
|-<br />
| style="text-align:center;" |No<br />
| key <br />
|<key><br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;"| No<br />
| tag<br />
| <tag><br />
| style="text-align:left;"|<br />
* Helps categorize media.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stop all playing music files for this profile associated with the API<br />
stopMusic()<br />
<br />
-- Stop playing the rugby mp3 by name<br />
stopMusic({name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"})<br />
<br />
-- Stop playing the unique sound identified as "rugby"<br />
stopMusic({<br />
name = nil -- nil lines are optional, no need to use<br />
, key = "rugby" -- key<br />
, tag = nil -- nil lines are optional, no need to use<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of stopMusic([name][,key][,tag]) ----<br />
<br />
-- Stop all playing music files for this profile associated with the API<br />
stopMusic()<br />
<br />
-- Stop playing the rugby mp3 by name<br />
stopMusic("167124__patricia-mcmillen__rugby-club-in-spain.mp3")<br />
<br />
-- Stop playing the unique sound identified as "rugby"<br />
stopMusic(<br />
nil -- name<br />
, "rugby" -- key<br />
, nil -- tag<br />
)<br />
</syntaxhighlight><br />
<br />
==stopNamedEventHandler==<br />
; success = stopNamedEventHandler(userName, handlerName)<br />
<br />
: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.<br />
<br />
;See also: [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]], [[Manual:Lua_Functions#resumeNamedEventHandler|resumeNamedEventHandler()]]<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;Parameters<br />
* ''userName:''<br />
: The user name the event handler was registered under.<br />
* ''handlerName:''<br />
: The name of the handler to stop. Same as used when you called [[Manual:Lua_Functions#registerNamedEventHandler|registerNamedEventHandler()]]<br />
<br />
;Returns <br />
* true if successful, false if it didn't exist or was already stopped<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local stopped = stopNamedEventHandler("DemonVitals")<br />
if stopped then<br />
cecho("DemonVitals stopped!")<br />
else<br />
cecho("DemonVitals doesn't exist or already stopped; either way it won't fire any more.")<br />
end<br />
</syntaxhighlight><br />
<br />
==stopSounds==<br />
;stopSounds(settings table)<br />
: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()]].<br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! style="text-align:left;"| Purpose<br />
|-<br />
| style="text-align:center;"| No<br />
| name<br />
| <file name><br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
|-<br />
| style="text-align:center;" |No<br />
| key <br />
|<key><br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;"| No<br />
| tag<br />
| <tag><br />
| style="text-align:left;"|<br />
* Helps categorize media.<br />
|-<br />
| style="text-align:center;" |No<br />
| priority<br />
| 1 to 100<br />
| style="text-align:left;" |<br />
*Halts the play of current or future played media files with a matching or lower priority.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stop all playing sound files for this profile associated with the API<br />
stopSounds()<br />
<br />
-- Stop playing the cow sound<br />
stopSounds({name = "cow.wav"})<br />
<br />
-- Stop playing any sounds tagged as "animals" with a priority less than or equal to 50<br />
---- This would not stop sounds tagged as "animals" greater than priority 50. This is an "AND" and not an "OR".<br />
stopSounds({<br />
name = nil -- nil lines are optional, no need to use<br />
, key = nil -- nil lines are optional, no need to use<br />
, tag = "animals"<br />
, priority = 50<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of stopSounds([name][,key][,tag][,priority]) ----<br />
<br />
-- Stop all playing sound files for this profile associated with the API<br />
stopSounds()<br />
<br />
-- Stop playing the cow sound<br />
stopSounds("cow.wav")<br />
<br />
-- Stop playing any sounds tagged as "animals" with a priority less than or equal to 50<br />
---- This would not stop sounds tagged as "animals" greater than priority 50. This is an "AND" and not an "OR".<br />
stopSounds(<br />
nil -- name<br />
, nil -- key<br />
, "animals" -- tag<br />
, 50 -- priority<br />
)<br />
</syntaxhighlight><br />
<br />
==timeframe==<br />
;timeframe(vname, true_time, nil_time, ...)<br />
<br />
:A utility function that helps you change and track variable states without using a lot of tempTimers.<br />
<br />
{{MudletVersion|3.6}}<br />
<br />
;Parameters<br />
* ''vname:''<br />
:A string or function to use as the variable placeholder.<br />
* ''true_time:''<br />
:Time before setting the variable to true. Can be a number or a table in the format: <code>{time, value}</code><br />
* ''nil_time:''<br />
:(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><br />
* ''...:''<br />
:(optional) Further list of times and values to set the variable to, in the following format: <code>{time, value}</code><br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- sets the global 'limiter' variable to true immediately (see the 0) and back to nil in one second (that's the 1).<br />
timeframe("limiter", 0, 1)<br />
<br />
-- 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.<br />
timeframe("giant", {0, "fee"}, 4, {1, "fi"}, {2, "fo"}, {3, "fum"})<br />
<br />
-- sets the local 'width' variable to true immediately and back to nil in one second.<br />
local width<br />
timeframe(function(value) width = value end, 0, 1)<br />
</syntaxhighlight><br />
<br />
==translateTable==<br />
;translateTable(directions, [languagecode])<br />
<br />
: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].<br />
<br />
{{MudletVersion|3.22}}<br />
<br />
;Parameters<br />
* ''directions:''<br />
:An indexed table of directions (eg. <code>{"sw", "w", "nw", "s"}</code>).<br />
* ''languagecode:''<br />
:(optional) Language code (eg <code>ru_RU</code> or <code>it_IT</code>) - by default, <code>mudlet.translations.interfacelanguage</code> is used.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- get the path from room 2 to room 5 and translate directions<br />
if getPath(2, 5) then<br />
speedWalkDir = translateTable(speedWalkDir)<br />
print("Translated directions:")<br />
display(speedWalkDir)<br />
</syntaxhighlight><br />
<br />
==uninstallModule==<br />
;uninstallModule(name)<br />
<br />
:Uninstalls a Mudlet module with the given name.<br />
<br />
:See also: [[#installModule | installModule()]], [[Manual:Event_Engine#sysLuaUninstallModule | Event: sysLuaUninstallModule]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
uninstallModule("myalias")<br />
</syntaxhighlight><br />
<br />
==uninstallPackage==<br />
;uninstallPackage(name)<br />
<br />
:Uninstalls a Mudlet package with the given name.<br />
<br />
:See also: [[#installPackage | installPackage()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
uninstallPackage("myalias")<br />
</syntaxhighlight><br />
<br />
==unzipAsync==<br />
;unzipAsync(path, location)<br />
<br />
: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.<br />
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.<br />
<br />
Do not use the <code>unzip()</code> function as it is synchronous and will impact Mudlet's performance (ie, freeze Mudlet while unzipping).<br />
<br />
{{MudletVersion|4.6}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
function handleUnzipEvents(event, ...)<br />
local args = {...}<br />
local zipName = args[1]<br />
local unzipLocation = args[2]<br />
if event == "sysUnzipDone" then<br />
cecho(string.format("<green>Unzip successful! Unzipped %s to %s\n", zipName, unzipLocation))<br />
elseif event == "sysUnzipError" then<br />
cecho(string.format("<firebrick>Unzip failed! Tried to unzip %s to %s\n", zipName, unzipLocation))<br />
end<br />
end<br />
if unzipSuccessHandler then killAnonymousEventHandler(unzipSuccessHandler) end<br />
if unzipFailureHandler then killAnonymousEventHandler(unzipFailureHandler) end<br />
unzipSuccessHandler = registerAnonymousEventHandler("sysUnzipDone", "handleUnzipEvents")<br />
unzipFailureHandler = registerAnonymousEventHandler("sysUnzipError", "handleUnzipEvents")<br />
--use the path to your zip file for this, not mine<br />
local zipFileLocation = "/home/demonnic/Downloads/Junkyard_Orc.zip" <br />
--directory to unzip to, it does not need to exist but you do need to be able to create it<br />
local unzipLocation = "/home/demonnic/Downloads/Junkyard_Orcs" <br />
unzipAsync(zipFileLocation, unzipLocation) -- this will work<br />
unzipAsync(zipFileLocation .. "s", unzipLocation) --demonstrate error, will happen first because unzipping takes time</syntaxhighlight><br />
<br />
==yajl.to_string==<br />
;yajl.to_string(data)<br />
<br />
: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.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- on IRE MUD games, you can send a GMCP request to request the skills in a particular skillset. Here's an example:<br />
sendGMCP("Char.Skills.Get "..yajl.to_string{group = "combat"})<br />
<br />
-- you can also use it to convert a Lua table into a string, so you can, for example, store it as room's userdata<br />
local toserialize = yajl.to_string(continents)<br />
setRoomUserData(1, "areaContinents", toserialize)<br />
</syntaxhighlight><br />
<br />
<br />
==yajl.to_value==<br />
;yajl.to_value(data)<br />
<br />
:Decodes JSON data (as a string) into a Lua table. This function is very efficient - if you need to dencode into JSON, use this.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- given the serialization example above with yajl.to_string, you can deserialize room userdata back into a table<br />
local tmp = getRoomUserData(1, "areaContinents")<br />
if tmp == "" then return end<br />
<br />
local continents = yajl.to_value(tmp)<br />
display(continents)<br />
</syntaxhighlight><br />
<br />
[[Category:Mudlet Manual]]<br />
[[Category:Mudlet API]]</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:String_Functions&diff=19867Manual:String Functions2022-02-14T03:44:43Z<p>Demonnic: /* string.patternEscape, utf8.patternEscape PR 5806 */</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Mudlet API documentation for functions used to manipulate strings.}}<br />
= String Functions =<br />
A collection of functions used to manipulate strings.<br />
==addWordToDictionary==<br />
;addWordToDictionary(word)<br />
:Adds the given word to the custom profile or shared dictionary (whichever is selected in preferences).<br />
<br />
: Returns true on success (the word was actually ''added'' to the dictionary by this call) and nil+msg on error - including if the word was already there - this is so that if you have other scripts that you wish to run when a word was added you can make their execution conditional on success here.<br />
<br />
:See also: [[#removeWordFromDictionary|removeWordFromDictionary()]]<br />
<br />
;Parameters<br />
* ''word:'' custom word to add to the dictionary.<br />
<br />
{{MudletVersion|3.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addWordToDictionary("Darkwind")<br />
addWordToDictionary("黑暗的风")<br />
addWordToDictionary("норм")<br />
</syntaxhighlight><br />
<br />
;Example - function making use of return value:<br />
<syntaxhighlight lang="lua"><br />
function rememberPlayerName(name)<br />
if addWordToDictionary(n) then<br />
echo("Added '" .. n .. "' to dictionary...\n")<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==cecho2string==<br />
; plainText = cecho2string(formattedText)<br />
<br />
:Strips the text formatting from the string passed in, leaving behind only the text.<br />
<br />
;See also: [[Manual:Lua_Functions#ansi2string|ansi2string()]], [[Manual:Lua_Functions#hecho2string|hecho2string()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formattedText:''<br />
: The string you want to strip the formatting codes from<br />
<br />
;Returns <br />
* The string with the formatting codes stripped out.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local exampleString = "<red>Formatted <b>string</b>"<br />
local plainText = cecho2string(exampleString)<br />
-- "Formatted string"<br />
</syntaxhighlight><br />
<br />
==decho2string==<br />
; plainText = decho2string(formattedText)<br />
<br />
:Strips the text formatting from the string passed in, leaving behind only the text.<br />
<br />
;See also: [[Manual:Lua_Functions#ansi2string|ansi2string()]], [[Manual:Lua_Functions#cecho2string|cecho2string()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formattedText:''<br />
: The string you want to strip the formatting codes from<br />
<br />
;Returns <br />
* The string with the formatting codes stripped out.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local exampleString = "<255,0,0>Formatted <b>string</b>"<br />
local plainText = decho2string(exampleString)<br />
-- "Formatted string"<br />
</syntaxhighlight><br />
<br />
==f==<br />
; formattedString = f(str)<br />
: Allows you to combine variables and functions into text (string interpolation) using <code>{}</code>.<br />
<br />
; Parameters<br />
* ''str:''<br />
: The string to perform interpolation against.<br />
<br />
{{MudletVersion|4.11}}<br />
; Example:<br />
<br />
<syntaxhighlight lang=lua><br />
-- old way:<br />
cecho("\nHello, "..matches[2]..", how is it going?")<br />
<br />
-- new way:<br />
cecho(f("\nHello {matches[2]}, how is it going?")<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang=lua><br />
testResult = "successful"<br />
-- old way:<br />
echo("The test was "..testResult.."\n")<br />
-- with f:<br />
echo(f("The test was {testResult}\n"))<br />
-- echoes "The test was successful\n"<br />
<br />
local testResult = "a failure"<br />
echo(f("The test was {testResult}\n"))<br />
-- echoes "The test was a failure\n" as it sees the local scope over global.<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang=lua><br />
-- You can also execute simple expressions<br />
echo(f("2 + 2 = {2 + 2}\n"))<br />
-- echoes "2 + 2 = 4\n"<br />
<br />
-- Or more complicated ones<br />
local function testFunc(item)<br />
return item:title()<br />
end<br />
<br />
echo(f("You should properly capitalize names, such as {testFunc('marilyn')}\n"))<br />
-- echoes "You should properly capitalize names, such as Marilyn\n"<br />
<br />
echo(f("You should properly capitalize names, such as {string.title('robert')}\n")<br />
-- same thing, but uses string.title directly and Robert instead of Marilyn<br />
</syntaxhighlight><br />
<br />
<br />
'''Caution!'''<br />
When using within closures, might not resolve variables correctly if they go out of a scope when closure is called.<br />
<syntaxhighlight lang=lua><br />
function formatter2000()<br />
local upvalue = "2000"<br />
local formatter = function() <br />
echo(f("Let's evaluate: {upvalue}\n"))<br />
end<br />
formatter() -- here evaulation inside f function will work<br />
return formatter<br />
end<br />
<br />
formatter2000()() -- here evaluation inside f function will return nil<br />
-- result<br />
-- Let's evaluate: 2000<br />
-- Let's evaulate: nil<br />
</syntaxhighlight><br />
<br />
You can work around this by doing the following<br />
<syntaxhighlight lang=lua><br />
function formatter2000()<br />
local upvalue = "2000"<br />
local formatter = function()<br />
local upvalue = upvalue -- this keeps upvalue in scope for the function later<br />
echo(f("Let's evaluate: {upvalue}\n"))<br />
end<br />
formatter() -- here evaulation inside f function will work<br />
return formatter<br />
end<br />
<br />
formatter2000()() -- here evaluation inside f function will return 2000 once again<br />
<br />
-- result<br />
-- Let's evaluate: 2000<br />
-- Let's evaulate: 2000<br />
</syntaxhighlight><br />
<br />
==getDictionaryWordList==<br />
;getDictionaryWordList()<br />
:Returns the profile or shared custom dictionary word list (whichever is selected in preferences) - that is, words added via right-click "add word to dictionary" or [[#addWordToDictionary|addWordToDictionary()]].<br />
<br />
: Returns an indexed table of words.<br />
<br />
{{MudletVersion|3.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(getDictionaryWordList())<br />
</syntaxhighlight><br />
<br />
==hecho2string==<br />
; plainText = hecho2string(formattedText)<br />
<br />
:Strips the text formatting from the string passed in, leaving behind only the text.<br />
<br />
;See also: [[Manual:Lua_Functions#ansi2string|ansi2string()]], [[Manual:Lua_Functions#decho2string|decho2string()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formattedText:''<br />
: The string you want to strip the formatting codes from<br />
<br />
;Returns <br />
* The string with the formatting codes stripped out.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local exampleString = "#ff0000Formatted #bstring#/b"<br />
local plainText = cecho2string(exampleString)<br />
-- "Formatted string"<br />
</syntaxhighlight><br />
<br />
==removeWordFromDictionary==<br />
;removeWordFromDictionary(word)<br />
:Removed the given word to the custom profile or shared dictionary (whichever is selected in preferences).<br />
<br />
: Returns true on success (if the word was present and removed by this call) and nil+msg on error.<br />
<br />
:See also: [[#addWordToDictionary|addWordToDictionary()]]<br />
<br />
;Parameters<br />
* ''word:'' custom word to remove from the dictionary.<br />
<br />
{{MudletVersion|3.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
removeWordFromDictionary("Darkwind")<br />
removeWordFromDictionary("黑暗的风")<br />
removeWordFromDictionary("норм")<br />
</syntaxhighlight><br />
<br />
==spellCheckWord==<br />
;spellCheckWord(word, [customDictionary])<br />
:Spellchecks the given word against the custom or the system dictionary.<br />
<br />
: Returns true if the word is spelled correctly or false if it's not, and nil+msg on error.<br />
<br />
:See also: [[#addWordToDictionary|addWordToDictionary()]], [[#removeWordFromDictionary|removeWordFromDictionary()]], [[#spellSuggestWord|spellSuggestWord()]]<br />
<br />
;Parameters<br />
* ''word'': word to spellcheck.<br />
* ''customDictionary'' (optional): dictionary to use. If true, the profile or shared dictionary will be used (depending on your settings). If omitted or false, the system dictionary (the language you have selected in settings) will be used.<br />
<br />
{{MudletVersion|3.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- spellcheck against the language dictionary<br />
if spellCheckWord("run") then<br />
echo("'run' is spelled ok!\n")<br />
end<br />
<br />
-- spellcheck against the custom 'add word to dictionary'<br />
if spellCheckWord("Darkwind", true) then<br />
echo("'Darkwind' is spelled OK!\n")<br />
end<br />
</syntaxhighlight><br />
<br />
==spellSuggestWord==<br />
;spellSuggestWord(word, [customDictionary])<br />
:Suggests similar words for the given word.<br />
<br />
: Returns a table of suggestions or nil+msg on error.<br />
<br />
:See also: [[#spellCheckWord|spellCheckWord()]]<br />
<br />
;Parameters<br />
* ''word'': word to give suggestions on.<br />
* ''customDictionary'' (optional): dictionary to use. If true, the profile or shared dictionary will be used (depending on your settings). If omitted or false, the system dictionary (the language you have selected in settings) will be used.<br />
<br />
{{MudletVersion|3.18}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
display(spellSuggestWord("Darkwind"))<br />
</syntaxhighlight><br />
<br />
==string.byte, utf8.byte==<br />
;string.byte(string [, i [, j]]) or utf8.byte(string [, i [, j]])<br />
;<nowiki>mystring:byte([, i [, j]])</nowiki><br />
: Returns the internal numerical codes of the characters <code>s[i], s[i+1], ···, s[j]</code>. The default value for <code>i</code> is <code>1</code>; the default value for <code>j</code> is <code>i</code>.<br />
: Note that numerical codes are not necessarily portable across platforms.<br />
: string.byte() works with English text only, use utf8.byte() for the international version.<br />
: See also: [[#string.char.2C_utf8.char|string.char]], [[#string.char.2C_utf8.char|utf8.char]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- the following call will return the ASCII values of "A", "B" and "C"<br />
a, b, c = string.byte("ABC", 1, 3)<br />
echo(a .. " - " .. b .. " - " .. c) -- shows "65 - 66 - 67"<br />
<br />
-- same for the international version but with the Unicode values<br />
a, b, c = utf8.byte("дом", 1, 3)<br />
echo(a .. " - " .. b .. " - " .. c) -- shows "1076 - 1086 - 1084"<br />
</syntaxhighlight><br />
<br />
==string.char, utf8.char==<br />
;string.char(···) or utf8.char(···)<br />
: Receives zero or more integers. Returns a string with length equal to the number of arguments, in which each character has the internal numerical code equal to its corresponding argument.<br />
: Note that numerical codes are not necessarily portable across platforms.<br />
: string.char() works with English text only, use utf8.char() for the international version.<br />
: See also: [[#string.byte.2C_utf8.byte|string.byte]], [[#string.byte.2C_utf8.byte|utf8.byte]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- the following call will return the string "ABC" corresponding to the ASCII values 65, 66, 67<br />
mystring = string.char(65, 66, 67)<br />
<br />
-- same for the infernational version which will return text "дом" for the Unicode values 1076, 1086, 1084<br />
mystring = utf8.char(1076,1086,1084)<br />
print(mystring)<br />
</syntaxhighlight><br />
<br />
==string.cut==<br />
;string.cut(string, maxLen)<br />
: Cuts string to the specified maximum length.<br />
: Returns the modified string.<br />
<br />
;Parameters:<br />
* ''string:''<br />
: The text you wish to cut. Passed as a string.<br />
* ''maxLen:''<br />
: The maximum length you wish the string to be. Passed as an integer number.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--The following call will return 'abc' and store it in myString<br />
myString = string.cut("abcde", 3)<br />
--You can easily pad string to certain length. Example below will print 'abcde ' e.g. pad/cut string to 10 characters.<br />
local s = "abcde"<br />
s = string.cut(s .. " ", 10) -- append 10 spaces<br />
echo("'" .. s .. "'")<br />
</syntaxhighlight><br />
<br />
==string.dump==<br />
;string.dump()<br />
Converts a function into a binary string. You can use the loadstring() function later to get the function back.<br />
: string.dump() works with both English and non-English text fine.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
string = string.dump(echo("this is a string"))<br />
--The following should then echo "this is a string"<br />
loadstring(string)()<br />
</syntaxhighlight><br />
<br />
==string.enclose==<br />
;string.enclose(string)<br />
: Wraps a string with [[ ]]<br />
: Returns the altered string.<br />
<br />
;Parameters:<br />
* ''String:''<br />
:The string to enclose. Passed as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This will echo '[[Oh noes!]]' to the main window<br />
echo("'" .. string.enclose("Oh noes!") .. "'")<br />
</syntaxhighlight><br />
<br />
==string.ends==<br />
;string.ends(String, Suffix)<br />
: Test if string is ending with specified suffix.<br />
: Returns true or false.<br />
: See also: [[#string.starts|string.starts]]<br />
<br />
;Parameters:<br />
* ''String:''<br />
: The string to test. Passed as a string.<br />
* ''Suffix:''<br />
: The suffix to test for. Passed as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This will test if the incoming line ends with "in bed" and if not will add it to the end.<br />
if not string.ends(line, "in bed") then<br />
echo("in bed\n")<br />
end<br />
</syntaxhighlight><br />
<br />
==string.find, utf8.find==<br />
;string.find(text, pattern [, init [, plain]]) or utf8.find<br />
: Looks for the first match of pattern in the string text. If it finds a match, then find returns the indices of text where this occurrence starts and ends; otherwise, it returns nil. A third, optional numerical argument init specifies where to start the search; its default value is 1 and can be negative. A value of true as a fourth, optional argument plain turns off the pattern matching facilities, so the function does a plain "find substring" operation, with no characters in pattern being considered "magic". Note that if plain is given, then init must be given as well.<br />
If the pattern has captures, then in a successful match the captured values are also returned, after the two indices.<br />
: string.find() works with English text only, use utf8.find() for the international version.<br />
;Example<br />
<syntaxhighlight lang=lua><br />
-- check if the word appears in a variable<br />
if string.find(matches[2], "rabbit") then<br />
echo("Found a rabbit!\n")<br />
end<br />
<br />
-- the following example will print: "3, 4"<br />
local start, stop = string.find("This is a test.", "is")<br />
if start then<br />
print(start .. ", " .. stop)<br />
end<br />
-- note that here "is" is being found at the end of the word "This", rather than the expected second word<br />
<br />
-- to make it match the word on its own, prefix %f[%a] and suffix %f[%A]<br />
if string.find("This is a test", "%f[%a]is%f[%A]") then<br />
echo("This 'is' is the actual stand-alone word\n")<br />
end<br />
</syntaxhighlight><br />
* Return value:<br />
: nil or start and stop position of the first matched text, followed by any captured text.<br />
<br />
==string.findPattern==<br />
; string.findPattern(text, pattern)<br />
: Return first matching substring or nil.<br />
<br />
; Parameters<br />
* ''text:''<br />
: The text you are searching the pattern for.<br />
* ''pattern:''<br />
: The pattern you are trying to find in the text.<br />
<br />
; Example:<br />
Following example will print: "I did find: Troll" string.<br />
<syntaxhighlight lang="lua"><br />
local match = string.findPattern("Troll is here!", "Troll")<br />
if match then<br />
echo("I did find: " .. match)<br />
end<br />
</syntaxhighlight><br />
:This example will find substring regardless of case.<br />
<syntaxhighlight lang="lua">local match = string.findPattern("Troll is here!", string.genNocasePattern("troll"))<br />
if match then<br />
echo("I did find: " .. match)<br />
end<br />
</syntaxhighlight><br />
* Return value:<br />
: nil or first matching substring<br />
See also: [[#string.genNocasePattern|string.genNocasePattern()]]<br />
<br />
==string.format==<br />
;string.format(formatstring,...)<br />
: Returns a formatted version of its variable number of arguments following the description given in its first argument (which must be a string). The format string follows the same rules as the printf family of standard C functions. The only differences are that the options/modifiers *, l, L, n, p, and h are not supported and that there is an extra option, q. The q option formats a string in a form suitable to be safely read back by the Lua interpreter: the string is written between double quotes, and all double quotes, newlines, embedded zeros, and backslashes in the string are correctly escaped when written. For instance, the call<br />
<syntaxhighlight lang=lua><br />
string.format('%q', 'a string with "quotes" and \n new line')<br />
</syntaxhighlight><br />
will produce the string:<br />
<syntaxhighlight lang=lua><br />
"a string with \"quotes\" and \<br />
new line"<br />
</syntaxhighlight><br />
The options c, d, E, e, f, g, G, i, o, u, X, and x all expect a number as argument, whereas q and s expect a string.<br />
<br />
This function does not accept string values containing embedded zeros, except as arguments to the q option.<br />
<br />
string.format() works fine with both English and non-English text.<br />
<br />
;Example<br />
<syntaxhighlight lang=lua><br />
some_data = "MudletUser1"<br />
<br />
-- pad data 20 characters wide to the left<br />
display(string.format("%20s", some_data))<br />
-- result: " MudletUser1"<br />
<br />
-- pad same data but instead to the the right<br />
display(string.format("%-20s", some_data))<br />
-- result: "MudletUser1 "<br />
<br />
-- pad but first truncate data to 6 characters<br />
display(string.format("%20s", string.sub(some_data, 1, 6)))<br />
-- result: " Mudlet"<br />
</syntaxhighlight><br />
<br />
==string.genNocasePattern==<br />
; string.genNocasePattern(template)<br />
: Generate case insensitive search pattern from string.<br />
<br />
; Parameters<br />
* template: The original string to be used as the base.<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
echo(string.genNocasePattern("123abc"))<br />
-- result: "123[aA][bB][cC]"<br />
</syntaxhighlight><br />
<br />
==string.gfind==<br />
;string.gfind()<br />
: This is an old version of what is now string.gmatch. Use string.gmatch instead.<br />
;Example<br />
''Need example''<br />
<br />
==string.gmatch, utf8.gmatch==<br />
;string.gmatch(text, pattern) or utf8.gmatch<br />
: Returns an iterator function that, each time it is called, returns the next captures from pattern over string text. If pattern specifies no captures, then the whole match is produced in each call.<br />
As an example, the following loop<br />
<syntaxhighlight lang=lua><br />
s = "hello world from Lua"<br />
for w in string.gmatch(s, "%a+") do<br />
print(w)<br />
end</syntaxhighlight><br />
will iterate over all the words from string s, printing one per line. The next example collects all pairs key=value from the given string into a table:<br />
<syntaxhighlight lang=lua><br />
t = {}<br />
s = "from=world, to=Lua"<br />
for k, v in string.gmatch(s, "(%w+)=(%w+)") do<br />
t[k] = v<br />
end</syntaxhighlight><br />
For this function, a '^' at the start of a pattern does not work as an anchor, as this would prevent the iteration.<br />
: string.gmatch() works with English text only, use utf8.gmatch() for the international version.<br />
;Example<br />
''Need example''<br />
<br />
==string.gsub, utf8.gsub==<br />
;string.gsub(text, pattern, repl [, n]) or utf8.gsub<br />
: Returns a copy of text in which all (or the first n, if given) occurrences of the pattern have been replaced by a replacement string specified by repl, which can be a string, a table, or a function. gsub also returns, as its second value, the total number of matches that occurred.<br />
<br />
:If repl is a string, then its value is used for replacement. The character % works as an escape character: any sequence in repl of the form %n, with n between 1 and 9, stands for the value of the n-th captured substring (see below). The sequence %0 stands for the whole match. The sequence %% stands for a single %.<br />
<br />
:If repl is a table, then the table is queried for every match, using the first capture as the key; if the pattern specifies no captures, then the whole match is used as the key.<br />
<br />
:If repl is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order; if the pattern specifies no captures, then the whole match is passed as a sole argument.<br />
<br />
:If the value returned by the table query or by the function call is a string or a number, then it is used as the replacement string; otherwise, if it is false or nil, then there is no replacement (that is, the original match is kept in the string).<br />
<br />
: string.gsub() works with English text only, use utf8.gsub() for the international version.<br />
;Example<br />
<syntaxhighlight lang=lua><br />
x = string.gsub("hello world", "(%w+)", "%1 %1")<br />
--> x="hello hello world world"<br />
<br />
x = string.gsub("hello world", "%w+", "%0 %0", 1)<br />
--> x="hello hello world"<br />
<br />
x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")<br />
--> x="world hello Lua from"<br />
<br />
x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)<br />
--> x="home = /home/roberto, user = roberto"<br />
<br />
x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)<br />
return loadstring(s)()<br />
end)<br />
--> x="4+5 = 9"<br />
<br />
local t = {name="lua", version="5.1"}<br />
x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)<br />
--> x="lua-5.1.tar.gz"</syntaxhighlight><br />
<br />
==string.len, utf8.len==<br />
;string.len(string) or utf8.len(string)<br />
;<nowiki>mystring:len()</nowiki><br />
:Receives a string and returns its length. The empty string "" has length 0. Embedded zeros are counted, so "a\000bc\000" has length 5.<br />
: string.len() works with English text only, use utf8.len() for the international version.<br />
<br />
;Parameters:<br />
* ''string:''<br />
:The string (text) you want to find the length of.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- prints 5 for the 5 letters in our word<br />
print(string.len("hello"))<br />
<br />
-- international version<br />
print(utf8.len("слово"))<br />
</syntaxhighlight><br />
<br />
==string.lower, utf8.lower==<br />
;string.lower(string) or utf8.lower(string)<br />
;<nowiki>mystring:lower()</nowiki><br />
:Receives a string and returns a copy of this string with all uppercase letters changed to lowercase. All other characters are left unchanged. The definition of what an uppercase letter is depends on the current locale.<br />
: string.lower() works with English text only, use utf8.lower() for the international version.<br />
: See also: [[#string.upper.2C_utf8.upper|string.upper]], [[#string.upper.2C_utf8.upper|utf8.upper]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- prints an all-lowercase version<br />
print(string.lower("No way! This is AWESOME!"))<br />
<br />
-- international version<br />
print(utf8.lower("Класс! Ето ОТЛИЧНО!"))<br />
</syntaxhighlight><br />
<br />
==string.match, utf8.match==<br />
;string.match(text, pattern [, init]) or utf8.match()<br />
: Looks for the first match of pattern in the string text. If it finds one, then match returns the captures from the pattern; otherwise it returns nil. If pattern specifies no captures, then the whole match is returned. A third, optional numerical argument init specifies where to start the search; its default value is 1 and can be negative.<br />
: string.match() works with English text only, use utf8.match() for the international version.<br />
;Example<br />
''Need example''<br />
<br />
== string.patternEscape, utf8.patternEscape==<br />
;escapedString = string.patternEscape(str) or escapedString = utf8.patternEscape(str)<br />
<br />
:Returns a version of str with all Lua pattern characters escaped to ensure string.match/find/etc look for the original str.<br />
<br />
;See also:[[Manual:Lua_Functions#string.trim|string.trim()]], [[Manual:Lua_Functions#string.genNocasePattern|string.genNocasePattern()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
*''str:''<br />
:The string to escape lua pattern characters in.<br />
<br />
;Returns<br />
*The string with all special Lua pattern characters escaped.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- searching for a url inside of a string. <br />
local helpString = [[<br />
This feature can be accessed by going to https://some-url.com/athing.html?param=value and<br />
retrieving the result!<br />
]]<br />
local url = "https://some-url.com/"<br />
display(helpString:find(url))<br />
-- nil<br />
display(helpString:find(string.patternEscape(url)))<br />
-- 42<br />
-- 62<br />
display(url:patternEscape())<br />
-- "https://some%-url%.com/"<br />
</syntaxhighlight><br />
<br />
==string.rep==<br />
;string.rep(String, n)<br />
;<nowiki>mystring:rep(n)</nowiki><br />
: Returns a string that is the concatenation of <code>n</code> copies of the string <code>String</code>.<br />
: string.rep() works with both English and non-English text fine.<br />
<br />
;Example<br />
<syntaxhighlight lang=lua><br />
-- repeat * 10 times<br />
display(string.rep("*", 10))<br />
-- results in:<br />
**********<br />
<br />
-- do the same thing, but this time calling from a variable<br />
s = "*"<br />
display(s:rep(10))<br />
-- results in:<br />
**********<br />
</syntaxhighlight><br />
<br />
==string.reverse, utf8.reverse==<br />
;string.reverse(string) or utf8.reverse(string)<br />
;<nowiki>mystring:reverse()</nowiki><br />
<br />
: Returns a string that is the string <code>string</code> reversed.<br />
: string.reverse() works with English text only, use utf8.reverse() for the international version.<br />
<br />
;Parameters:<br />
* ''string:''<br />
:The string to reverse. Passed as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
mystring = "Hello from Lua"<br />
echo(mystring:reverse()) -- displays 'auL morf olleH'<br />
<br />
-- international version.<br />
mystring = "Привет от Луа!"<br />
echo(utf8.reverse(mystring)) -- displays '!ауЛ то тевирП', which probably looks the same to you<br />
</syntaxhighlight><br />
<br />
==string.split==<br />
;string.split(string, delimiter)<br />
;<nowiki>myString:split(delimiter)</nowiki><br />
: Splits a string into a table by the given delimiter. Can be called against a string (or variable holding a string) using the second form above.<br />
: Returns a table containing the split sections of the string.<br />
<br />
;Parameters:<br />
* ''string:''<br />
: The string to split. Parameter is not needed if using second form of the syntax above. Passed as a string.<br />
* ''delimiter:''<br />
: The delimiter to use when splitting the string. Passed as a string, and allows for [http://www.lua.org/pil/20.2.html Lua pattern types]. Use % to escape here (and %% to escape a stand-alone %).<br />
{{ Note }} as of Mudlet 4.7+, delimiter will default to " " if not provided.<br />
<br />
{{ Note }} as of Mudlet 4.7+, using "" (empty string) for the delimiter will return the string as a table of characters. IE string.split("This","") will return as {"T", "h", "i", "s"}. Prior to 4.7 using empty string as the delimiter would error after hanging temporarily.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This will split the string by ", " delimiter and print the resulting table to the main window.<br />
names = "Alice, Bob, Peter"<br />
name_table = string.split(names, ", ")<br />
display(name_table)<br />
<br />
--The alternate method<br />
names = "Alice, Bob, Peter"<br />
name_table = names:split(", ")<br />
display(name_table)<br />
</syntaxhighlight><br />
<br />
:Either method above will print out:<br />
: table {<br />
:: 1: 'Alice'<br />
:: 2: 'Bob'<br />
:: 3: 'Peter'<br />
: }<br />
<br />
==string.starts==<br />
;string.starts(string, prefix)<br />
: Test if string is starting with specified prefix.<br />
: Returns true or false<br />
: See also: [[#string.ends|string.ends]]<br />
<br />
;Parameters:<br />
* ''string:''<br />
: The string to test. Passed as a string.<br />
* ''prefix:''<br />
: The prefix to test for. Passed as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--The following will see if the line begins with "You" and if so will print a statement at the end of the line<br />
if string.starts(line, "You") then<br />
echo("====oh you====\n")<br />
end<br />
</syntaxhighlight><br />
<br />
==string.sub, utf8.sub==<br />
;string.sub(text, i [, j]) or utf8.sub()<br />
: Returns the substring of text that starts at i and continues until j; i and j can be negative. If j is absent, then it is assumed to be equal to -1 (which is the same as the string length). In particular, the call string.sub(text,1,j) returns a prefix of text with length j, and string.sub(text, -i) returns a suffix of text with length i.<br />
: string.sub() works with English text only, use utf8.sub() for the international version.<br />
;Example<br />
''Need example''<br />
<br />
==string.title==<br />
;string.title(string)<br />
;<nowiki>mystring:title()</nowiki><br />
: Capitalizes the first character in a string.<br />
: Returns the altered string.<br />
<br />
;Parameters:<br />
* ''string:''<br />
: The string to modify. Not needed if you use the second form of the syntax above.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--Variable testname is now Anna.<br />
testname = string.title("anna")<br />
--Example will set test to "Bob".<br />
test = "bob"<br />
test = test:title()<br />
</syntaxhighlight><br />
<br />
==string.trim==<br />
;string.trim(string)<br />
: Trims string, removing all 'extra' white space at the beginning and end of the text.<br />
: Returns the altered string.<br />
<br />
;Parameters:<br />
* ''string:''<br />
: The string to trim. Passed as a string.<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
--This will print 'Troll is here!', without the extra spaces.<br />
local str = string.trim(" Troll is here! ")<br />
echo("'" .. str .. "'")<br />
</syntaxhighlight><br />
<br />
==string.upper, utf8.upper==<br />
;string.upper(string) or utf8.upper(string)<br />
;<nowiki>mystring:upper()</nowiki><br />
: Receives a string and returns a copy of this string with all lowercase letters changed to uppercase. All other characters are left unchanged. The definition of what a lowercase letter is depends on the current locale.<br />
: string.upper() works with English text only, use utf8.upper() for the international version.<br />
<br />
: See also: [[#string.lower.2C_utf8.lower|string.lower]], [[#string.lower.2C_utf8.lower|utf8.lower]]<br />
<br />
;Parameters<br />
* ''string:''<br />
: The string you want to change to uppercase<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- displays 'RUN BOB RUN'<br />
print(string.upper("run bob run"))<br />
<br />
-- displays 'ДАВАЙ ДАВАЙ!'<br />
print(utf8.upper("давай давай!"))<br />
</syntaxhighlight><br />
<br />
==utf8.charpos==<br />
;utf8.charpos(string[[, charpos], offset])<br />
: Converts UTF-8 position to byte offset, returns the character position and code point. If only offset is given, returns byte offset of this UTF-8 char index. If charpos and offset is given, a new charpos will be calculated by adding/subtracting UTF-8 char offset to current charpos. In all cases, it return a new char position, and code point (a number) at this position.<br />
<br />
;Parameters<br />
* ''string:''<br />
: The input string to work on.<br />
* ''charpos:''<br />
: (optional) character position to work on.<br />
* ''offset:''<br />
: (optional) offset (as a number) to work on.<br />
<br />
==utf8.escape==<br />
;utf8.escape(string)<br />
: Escape a string to UTF-8 format string. It support several escape formats:<br />
<br />
%ddd - which ddd is a decimal number at any length:<br />
change Unicode code point to UTF-8 format.<br />
%{ddd} - same as %nnn but has bracket around.<br />
%uddd - same as %ddd, u stands Unicode<br />
%u{ddd} - same as %{ddd}<br />
%xhhh - hexadigit version of %ddd<br />
%x{hhh} same as %xhhh.<br />
%? - '?' stands for any other character: escape this character.<br />
<br />
;Parameters<br />
* ''string:''<br />
: The string you want to escape<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local u = utf8.escape<br />
print(u"%123%u123%{123}%u{123}%xABC%x{ABC}")<br />
print(u"%%123%?%d%%u")<br />
</syntaxhighlight><br />
<br />
==utf8.fold==<br />
;utf8.fold(string)<br />
: Returns the lowercase version of the string for use in case-insensitive comparisons. If string is a number, it's treated as a code point and the converted code point is returned (as a number).<br />
<br />
;Parameters<br />
* ''string:''<br />
: The string to lowercase.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
print(utf8.fold("ПРИВЕТ")) -- 'привет'<br />
print(utf8.fold("Привет")) -- 'привет'<br />
</syntaxhighlight><br />
<br />
==utf8.insert==<br />
;utf8.insert(string[, idx], substring)<br />
: Inserts the substring into the given string. If idx is given, inserts substring before the character at this index, otherwise the substring will append onto the end of string. idx can be negative.<br />
<br />
;Parameters<br />
* ''string:''<br />
: The input string to work on.<br />
* ''idx:''<br />
: (optional) character position to insert the string at.<br />
* ''substring:''<br />
: text to insert into the substring.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- inserts letter я before the 2nd letter and prints 'мясо'<br />
print(utf8.insert("мсо", 2, "я"))<br />
</syntaxhighlight><br />
<br />
==utf8.ncasecmp==<br />
;utf8.ncasecmp(a, b)<br />
: Compares ''a'' and ''b'' without case. Return -1 means a < b, 0 means a == b and 1 means a > b.<br />
<br />
;Parameters<br />
* ''a:''<br />
: String to compare.<br />
* ''b:''<br />
: String to compare against.<br />
<br />
==utf8.next==<br />
;utf8.next(string[, charpos[, offset]])<br />
: Iterates though the UTF-8 string.<br />
<br />
;Parameters<br />
* ''string:''<br />
: The input string to work on.<br />
* ''charpos:''<br />
: (optional) character position to work on.<br />
* ''offset:''<br />
: (optional) offset (as a number) to work on.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- prints location and code point of every letter<br />
for pos, code in utf8.next, "тут есть текст" do<br />
print(pos, code)<br />
end<br />
</syntaxhighlight><br />
<br />
==utf8.remove==<br />
;utf8.remove(string[, start[, stop]])<br />
: Removed characters from the given string. Deletes characters from the given ''start'' to the end of the string. If ''stop'' is given, deletes characters from ''start'' to ''stop'' (including start and stop). ''start'' and ''stop'' can be negative.<br />
<br />
;Parameters<br />
* ''string:''<br />
: The input string to work on.<br />
* ''start:''<br />
: position to start deleting characters from.<br />
* ''stop:''<br />
: (optional) posititon to stop deleting characters at.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- delete everything from the 3rd character including the character itself<br />
print(utf8.remove("мясо", 3)) -- 'мя'<br />
<br />
-- delete the last character, use negative to count backwards<br />
print(utf8.remove("мясо", -1)) -- 'мяс'<br />
<br />
-- delete everything from the 2nd to the 4th character<br />
print(utf8.remove("вкусное", 2,4)) -- 'вное'<br />
</syntaxhighlight><br />
<br />
==utf8.title==<br />
;utf8.title(string)<br />
: Returns the uppercase version of the string for use in case-insensitive comparisons. If string is a number, it's treated as a code point and the converted code point is returned (as a number).<br />
<br />
;Parameters<br />
* ''string:''<br />
: The string to uppercase.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
print(utf8.title("привет")) -- 'ПРИВЕТ'<br />
print(utf8.title("Привет")) -- 'ПРИВЕТ'<br />
</syntaxhighlight><br />
<br />
==utf8.width==<br />
;utf8.width(string[, ambi_is_double[, default_width]])<br />
: Calculate the widths of the given string. If the string is a code point, return the width of this code point.<br />
<br />
;Parameters<br />
* ''string:''<br />
: The input string to work on.<br />
* ''ambi_is_double:''<br />
: (optional) if provided, the ambiguous width character's width is 2, otherwise it's 1.<br />
* ''default_width:''<br />
: (optional) if provided, this will be the width of unprintable character, used display a non-character mark for these characters.<br />
<br />
==utf8.widthindex==<br />
;utf8.widthindex(string, location[, ambi_is_double[, default_width]])<br />
: Returns the character index at the location in the given string as well as the offset and the width. This is a reverse operation of utf8.width().<br />
<br />
;Parameters<br />
* ''string:''<br />
: The input string to work on.<br />
* ''location:''<br />
: location to get the width of.<br />
* ''ambi_is_double:''<br />
: (optional) if provided, the ambiguous width character's width is 2, otherwise it's 1.<br />
* ''default_width:''<br />
: (optional) if provided, this will be the width of unprintable character, used display a non-character mark for these characters.<br />
<br />
[[Category:Mudlet Manual]]<br />
[[Category:Mudlet API]]</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:Geyser&diff=19863Manual:Geyser2022-02-05T01:16:41Z<p>Demonnic: /* Styling labels */</p>
<hr />
<div>{{TOC right}}<br />
<br />
= Introduction =<br />
<br />
The Geyser Layout Manager is an object oriented framework for creating, updating and organizing GUI elements within Mudlet - it allows you to make your UI easier on Mudlet, and makes it easier for the UI to be compatible with different screen sizes.<br />
<br />
=== Motivation ===<br />
<br />
Mudlet makes the creation of label, miniconsoles and gauges a quick and easy thing. Mudlet provides a nice signal when window resize events happen. To help with complex window management, Geyser steps in.<br />
<br />
=== Main Geyser Features ===<br />
<br />
Geyser is based on traditional GUI concepts and should feel similar to using Java's Swing. The biggest difference is in how positions are specified.<br />
<br />
* All window positions are specified relative to their container - nothing new there. However, window positions can also take on percentages and negative pixel and character values. For instance, a window could be constrained to have a height of 50% of its container and a width such that the window's right edge is always 20 characters from its container's right edge. See examples below and the demos/tests that come with Geyser.<br />
* All windows under Geyser control are automatically resized as necessary when the main Mudlet window is resized. Once you create a window and assign it to a container, you never have to worry about positioning it again. Nonetheless, it's very easy to shift the container that a window is in, maintaining its constraints so that it resizes as needed according to the dimensions of the new container.<br />
* Due to the container hierarchy, hiding a container window automatically hides all its contained windows too. The same for show. With clever construction and labels with callbacks, this lets one make complex GUI elements that are minimizable or maximizable or ...<br />
* However, there is always some overhead for automation systems and Geyser is no exception. Fortunately, most of the overhead is during window creation and resize events - not things that happen frequently.<br />
<br />
=== Getting pictures for your stuff ===<br />
You can find good, freely-available assets for your UI here:<br />
* [https://kenney.nl/assets?q=2d kenney.nl]<br />
* [https://opengameart.org/ opengameart.org]<br />
* [https://game-icons.net/ game-icons.net]<br />
<br />
=== Constraints format ===<br />
<br />
Geyser position constraints are a string composed of a number and a format type. For example, "10px" means 10 pixels, either pixels from the origin (e.g. x or y) or a value for the width or height. A negative number indicates distance from a container's right or bottom border depending on whether is a constraint for x/width or y/height, respectively. Percentages for width and height are in terms of the container's dimensions and negative values are converted to the equivalent positive value. A 100% width subwindow with an x-coordinate of 10 will have part of itself displayed outside the confines of its container. There is no hard limit on maximum window size, just as with regular Mudlet windows. If a number, n, is passed as a constraint instead of a string, it is assumed to be equivalent to "npx". Any Lua table that contains entries for x, y, width and height in the proper format can be used for Geyser constructors and setting constraints. Just like in Mudlet, 0,0 coordinates mean the top-left corner.<br />
<br />
The following is a valid example for coordinates of a Geyser object:<br />
<br />
<syntaxhighlight lang="lua"><br />
{x = "20px", y = "-10c", width = "40%", height = 30}<br />
</syntaxhighlight><br />
<br />
=== Math in Geyser ===<br />
You can also use math in your Geyser constraints just to line things up just right! Want to have a label occupy full height but not the first 30 pixels? You can:<br />
<br />
<syntaxhighlight lang="lua"><br />
footer = Geyser.Label:new({<br />
name = "footer",<br />
x = 0, y = 30,<br />
width = "100%-30px",<br />
}, main_window)<br />
</syntaxhighlight><br />
<br />
= Geyser elements =<br />
The purpose of this document is to go through every Geyser element and provide practical examples on how they are used. Read it from top to bottom, preferably doing all of the examples to understand how they work!<br />
<br />
See also: https://www.mudlet.org/geyser/files/index.html for a brief and technical overview of all elements and their functions.<br />
<br />
==[http://www.mudlet.org/geyser/files/geyser/GeyserContainer.html Geyser.Container]==<br />
An invisible, organizing object in Geyser - use it to divide your screen and position elements accordingly. '''[http://www.mudlet.org/geyser/files/geyser/GeyserContainer.html See here]''' for all of the functions that are available to you to use.<br />
<br />
A container is also the base class - which means that everything (labels, miniconsoles and gauges) can use its functions, since everything else is at heart a container.<br />
<br />
=== Creating a container ===<br />
To get started with a container, here's an example that'll create a 200px border on the left side of Mudlet for you, and make a container cover all of it - so you can place other visual elements inside it:<br />
<br />
<syntaxhighlight lang="lua"><br />
setBorderLeft(200)<br />
left_container = Geyser.Container:new({<br />
name = "left_container", -- give it a unique name here<br />
x=0, y=0, -- have it start at the top-left corner of mudlet<br />
width = 200, height="100%", -- with a width of 200, and a height of the full screen, hence 100%<br />
})<br />
</syntaxhighlight><br />
<br />
Right away, you'll see space appear on the left side. It'll be black, as the container is an invisible unit by itself. You can make sure it's there by making it flash by doing this from the input line:<br />
<br />
<syntaxhighlight lang="lua">lua left_container:flash()</syntaxhighlight><br />
<br />
The command will cause your container to flash for a moment for you, revealing itself.<br />
<br />
{{Note}} If you hide a container and create new Geyser elements within it, they'll be shown automatically for you.<br />
<br />
=== Container within a container ===<br />
You can place containers within other containers by specifying which "parent" the new container should have when you create one. Given our [[#Creating a container|previous example]], you can split the left side into two halves like this:<br />
<br />
<syntaxhighlight lang="lua"><br />
left_container_top = Geyser.Container:new({<br />
name = "left_container_top",<br />
x=0, y=0, -- this container occupies the top, so it starts top-left as well<br />
width = "100%", height="50%", -- but only uses up half of the height<br />
}, left_container) -- this is the important bit - it says that left_container_top should be inside left_container<br />
<br />
left_container_bottom = Geyser.Container:new({<br />
name = "left_container_bottom",<br />
x=0, y="50%", -- this container starts halfway down the first one<br />
width = "100%", height="50%", -- and has the same half height of the original container<br />
}, left_container) <br />
</syntaxhighlight><br />
<br />
=== Aligning relative to bottom or right sides ===<br />
The aligning point within Mudlet is the top-left corner, and it's the same for the elements they are aligned - the position you specify is used by the top-left corner of the element.<br />
<br />
Using Geyser, you can align to the opposite side as well, using the coordinates in negatives, while keeping the dimensions of the object in mind. For example, if you want to align a box that's 20px wide on the usual left side, you'd give it a width of 20 and an x value of 0. If you'd like to align it on the right side, then you'd give it an x value of -20. The box will spawn 20px away from the right side and "grow" to the right by 20px.<br />
<br />
<syntaxhighlight lang="lua"><br />
right_container = Geyser.Container:new({<br />
name = "right_container",<br />
x="-20%", y=0, -- makes the container start 20% of the screen away from the right side<br />
width = "20%", height="50%", -- filling it up until the end<br />
}) <br />
</syntaxhighlight><br />
<br />
Do make sure to account for the scrollbar, as Mudlet UI elements can overlap it. You can also move the scrollbar with [[Manual:UI_Functions#setBorderRight|setBorderRight()]].<br />
<br />
==[http://www.mudlet.org/geyser/files/geyser/GeyserLabel.html Geyser.Label]==<br />
Labels allow you to use pictures in your interface, as well as nicely-formatted text - see docs for label [http://www.mudlet.org/geyser/files/geyser/GeyserLabel.html functions].<br />
<br />
=== Basic label ===<br />
<br />
Here's an example to get you started with:<br />
<br />
<syntaxhighlight lang="lua"><br />
testlabel = Geyser.Label:new({<br />
name = "testlabel",<br />
x = "50%", y = 0,<br />
width = "50%", height = "100%",<br />
fgColor = "black",<br />
color = "SeaGreen",<br />
message = [[<center>heey</center>]]<br />
})<br />
</syntaxhighlight><br />
<br />
This labels '''x''' coordinate is specified as 50% - and because it's not attached to any container, this implies that the window will start halfway at the main window. You can tell it's not attached to a container because there's nothing in between the last ''}'' and '')'', the place where the container goes.<br />
<br />
The '''y''' coordinate is 0 - which means that the label will start at the top of the screen. With the width being 50%, the label will occupy 50% of the screen - and since it starts at the halfway point, it means it'll occupy the entire right side. A height of 100% means that it'll stretch from the top to the full bottom.<br />
<br />
Here's what that'll look like:<br />
<br />
[[File:Simple-label.png|center|600px]]<br />
<br />
<br />
Playing around with the starting location and dimensions, we can also place it in the center of the screen with:<br />
<br />
<syntaxhighlight lang="lua"><br />
testlabel = Geyser.Label:new({<br />
name = "testlabel",<br />
x = "25%", y = "25%",<br />
width = "50%", height = "50%",<br />
fgColor = "black",<br />
message = [[<center>heey</center>]]<br />
})<br />
testlabel:setColor(0,255,0,150)<br />
</syntaxhighlight><br />
<br />
[[File:Simple_label_centered.png|center|600px]]<br />
<br />
To change the message on a label, you can use the ''mylabel:echo()'' function, where ''mylabel'' is the name of the label you gave it:<br />
<br />
<syntaxhighlight lang="lua"><br />
mylabel:echo("hello!")<br />
</syntaxhighlight><br />
<br />
To get rid of the label, use the '':hide()'' function:<br />
<br />
<syntaxhighlight lang="lua"><br />
mylabel:hide()<br />
</syntaxhighlight><br />
<br />
=== Coloring text ===<br />
<syntaxhighlight lang="lua"><br />
testlabel = Geyser.Label:new({<br />
name = "testlabel",<br />
x = "50%", y = 0,<br />
width = "50%", height = "100%",<br />
fgColor = "black", -- default text colour<br />
color = "SeaGreen" -- default label background<br />
})<br />
<br />
-- You can also change colour of text on demand with:<br />
testlabel:echo[[<p style="color:blue;">You can change the text color of a whole sentence or paragraph...</p><p>...or you can change the text color of one <span style="color:green;">word</span> or even a single l<span style="color:red;">e</span>tter.</p>]]<br />
</syntaxhighlight><br />
<br />
=== Setting the font size ===<br />
<br />
To set a different font size for your Label, use the ''setFontSize()'' method. For example:<br />
<br />
<syntaxhighlight lang="lua"><br />
testlabel:setFontSize(14)<br />
</syntaxhighlight><br />
<br />
The font size is set in Pt, so anything above 30 will likely be too large to be useful.<br />
<br />
=== Label inside a container ===<br />
<br />
Once you've got your containers and mastered the basic labels, you can drop labels into your nicely-organized containers. Doing so is similar to nesting containers:<br />
<br />
<syntaxhighlight lang="lua"><br />
testlabel = Geyser.Label:new({<br />
name = "testlabel",<br />
x = "25%", y = "25%",<br />
width = "50%", height = "50%",<br />
fgColor = "black",<br />
message = [[<center>heey</center>]]<br />
}, left_container_bottom) -- this is where we tell it what container to go into<br />
testlabel:setColor(0,255,0,150)<br />
</syntaxhighlight><br />
<br />
That label is exactly the same as the one above that goes across the screen, except it's in our bottom-left container - so it looks appropriately different:<br />
<br />
[[File:Label in a container.png|center]]<br />
<br />
=== Image on a label ===<br />
One of the more amazing things labels allow you to do is put pictures anywhere on your Mudlet screen, that blend in very well. To do so, once the label is created, use the [http://www.mudlet.org/geyser/files/geyser/GeyserLabel.html#Geyser.Label:setBackgroundImage setBackgroundImage()] function with the exact path to the image ([[File:Skullface.png]]):<br />
<br />
<syntaxhighlight lang="lua"><br />
picture_label = Geyser.Label:new({<br />
name = "picture_label",<br />
x = 0, y = "-14px",<br />
width = "16px", height = "14px",<br />
})<br />
picture_label:setBackgroundImage([[/home/vadi/Desktop/skullface.png]]) -- update location to actual image location on your computer<br />
</syntaxhighlight><br />
<br />
This'll plop the picture to the bottom-left of your screen. To make the picture show, download the skullface picture above - save it to your desktop, and adjust the location of the image within [[]]'s to what it is on your computer. For example, if you saved this on your Windows 7 desktop, it would be:<br />
<br />
<syntaxhighlight lang="lua"><br />
picture_label:setBackgroundImage([[C:/Users/<your user name>/Desktop/skullface.png]])<br />
</syntaxhighlight><br />
<br />
(yes, that's / and not \ - \ has been known not to work)<br />
<br />
If you saved this on your Mac desktop, it would be:<br />
<br />
<syntaxhighlight lang="lua"><br />
picture_label:setBackgroundImage([[/Users/<your user name>/Desktop/skullface.png]])<br />
</syntaxhighlight><br />
<br />
If you saved this on your Ubuntu desktop, it would be:<br />
<br />
<syntaxhighlight lang="lua"><br />
picture_label:setBackgroundImage([[/home/<your user name>/Desktop/skullface.png]])<br />
</syntaxhighlight><br />
<br />
Using this basic building block, you can work up to making yourself a UI!<br />
<br />
=== Stretching an image on a label ===<br />
If you'd like your image not to keep its original size, but instead use up the available space of the label - you can use the [http://doc.qt.io/qt-5/stylesheet-reference.html#border-image border-image] stylesheet property to do so.<br />
<br />
<syntaxhighlight lang="lua"><br />
label = Geyser.Label:new({<br />
name = "label",<br />
x = "50%", y = "50%",<br />
width = "50%", height = "50%",<br />
})<br />
<br />
-- change the location to your picture<br />
-- on windows, use / to separate folders still, not \<br />
label:setStyleSheet[[<br />
border-image: url(/home/vadi/Desktop/iso-avatar-draft_0.png);<br />
]]<br />
</syntaxhighlight><br />
<br />
{{note}} If you're on a Mudlet earlier than 3.15 and are having difficulty with the image coming up, it may be because of strange differences between Qt's CSS engine which does not affect mudlet's Lua. You may want to try appending :gsub("\\","/") to your string including getMudletHomeDir() (e.g. <code>getMudletHomeDir():gsub("\\","/")</code>). No longer necessary after Mudlet 3.15.<br />
<br />
=== Aligning an image within a label ===<br />
You can use background-image in combination with background-position to align an image within a label (if, say, the image is much smaller than the label).<br />
<br />
<syntaxhighlight lang="lua"><br />
-- this will set and align an image top-right of the label<br />
if stunning then<br />
mylabel:setStyleSheet([[<br />
background-image: url("/home/vadi/Games/Mudlet/Offensive/Artwork/dialog-ok.png");<br />
background-repeat: no-repeat; background-position: top right; background-origin: margin;<br />
]])<br />
else<br />
mylabel:setStyleSheet([[<br />
background-image: url("/home/vadi/Games/Mudlet/Offensive/Artwork/dialog-no.png");<br />
background-repeat: no-repeat; background-position: top right; background-origin: margin;<br />
]])<br />
end<br />
</syntaxhighlight><br />
<br />
=== Showing / hiding a label ===<br />
You can show and hide labels, as you can any container, miniconsole or a gauge in Geyser with [http://www.mudlet.org/geyser/files/geyser/GeyserContainer.html#Geyser.Container:show Geyser.Container:show()] and [http://www.mudlet.org/geyser/files/geyser/GeyserContainer.html#Geyser.Container:hide Geyser.Container:hide()]. Remember that since labels are a type of a container, all container functions work on them.<br />
<br />
Hiding a label will allow you to click through on what is below the label, as well as free up the visual space for something else.<br />
<br />
<syntaxhighlight lang="lua"><br />
testlabel = Geyser.Label:new({<br />
name = "testlabel",<br />
x = "50%", y = 0,<br />
width = "50%", height = "100%",<br />
fgColor = "black",<br />
color = "SeaGreen",<br />
message = [[<center>heey</center>]]<br />
})<br />
<br />
-- hide the label with:<br />
testlabel:hide()<br />
<br />
-- show the label with:<br />
testlabel:show()<br />
</syntaxhighlight><br />
<br />
=== Clickable images ===<br />
Tacking onto the fact that you can plop images anywhere on your Mudlet screen now, you can also make them react to your clicks. You can do so with the [http://www.mudlet.org/geyser/files/geyser/GeyserLabel.html#Geyser.Label:setClickCallback setClickCallback()] function - by giving it a function to call when your label is clicked, you'll make it react.<br />
<br />
<syntaxhighlight lang="lua"><br />
picture_label = Geyser.Label:new({<br />
name = "picture_label",<br />
x = "-215px", y = "0px",<br />
width = "200px", height = "200px",<br />
})<br />
picture_label:setBackgroundImage([[/home/vadi/Desktop/qubodup-opengameart-cc0-200px-missile_icon.png]]) -- update location to actual image location on your computer<br />
picture_label:setClickCallback("on_bomb_press")<br />
<br />
function on_bomb_press()<br />
send("say BOOM!")<br />
end<br />
</syntaxhighlight><br />
<br />
That's it! Pressing on the image will make the ''on_bomb_press()'' function go off, which will do its code of ''send("say BOOM!")''. Download the picture for use [http://opengameart.org/content/missile-rts-icon here].<br />
<br />
[[File:Clickable_image.png|500px|center]]<br />
<br />
=== Styling labels ===<br />
Besides putting text or images on labels, you can also style them using Qt's stylesheets feature. Doing so allows you to create various graphics that make the label look more appealing:<br />
<br />
[[File:Label_styling_examples.png|center]]<br />
<br />
To set a stylesheet on a label, use the [http://www.mudlet.org/geyser/files/geyser/GeyserLabel.html#Geyser.Label:setStyleSheet Geyser.Label:setStyleSheet()] function on your label, describing the stylesheet you'd like to give it. A stylesheet consists of properties you set - for example the background color, borders, padding, and so forth. You describe properties in the following format: ''property name''''':'''''values''''';'''. See here for a [http://doc.qt.io/qt-5/stylesheet-reference.html#list-of-properties list of all supported properties]. For example, to make your labels background be yellow, you'd use the background-color property:<br />
<br />
<syntaxhighlight lang="lua"><br />
mylabel = Geyser.Label:new({<br />
name = "mylabel",<br />
x = "50%", y = "50%",<br />
width = 200, height = 100<br />
})<br />
<br />
mylabel:setStyleSheet([[<br />
background-color: yellow;<br />
]])<br />
</syntaxhighlight><br />
<br />
[[File:Basic_stylesheet.png|center]]<br />
<br />
Which is nice, but not particularly impressive.<br />
<br />
Scrolling down the list of properties, you'll come along a border one. Plopping it into our stylesheet nets the following:<br />
<br />
<syntaxhighlight lang="lua"><br />
mylabel:setStyleSheet([[<br />
background-color: yellow;<br />
border: 5px solid white;<br />
]])<br />
</syntaxhighlight><br />
<br />
[[File:Basic_stylesheet_border.png|center]]<br />
<br />
Which gives a border!<br />
<br />
Fiddling with it some more and applying new properties we find on that page, we get a rounded border on our label:<br />
<br />
<syntaxhighlight lang="lua"><br />
mylabel:setStyleSheet([[<br />
background-color: grey;<br />
border-width: 15px;<br />
border-style: solid;<br />
border-color: green;<br />
border-radius: 10px;<br />
]])<br />
</syntaxhighlight><br />
<br />
[[File:Basic_stylesheet_border_radius.png|center]]<br />
<br />
Which'll conclude our exploration for now. Try out all of the other possible options available there - there's loads, from [http://doc.qt.io/qt-5/stylesheet-reference.html#border-style funky borders], to tiling images and fancy color combinations using gradients.<br />
<br />
You should also check out [[Manual:Geyser#Geyser.StyleSheet|Geyser.StyleSheet]] for a way to manage your stylesheets with adjustable properties and the ability to take defaults from another stylesheet.<br />
<br />
=== Adding a tooltip to a label ===<br />
<br />
Since Mudlet 4.6, you can now add a tooltip to labels and gauges. You can start by making a simple label and echoing some text to it:<br />
<br />
<syntaxhighlight lang="lua"><br />
testLabel = Geyser.Label:new({<br />
name = "testLabel",<br />
x = "50%",<br />
y = "50%",<br />
height = "25%",<br />
width = "25%",<br />
})<br />
testLabel:echo("This is on the label!")<br />
testLabel:setAlignment("center")<br />
-- sets the tooltip text<br />
testLabel:setToolTip("This is the tooltip", "10")<br />
<br />
<br />
-- optionally - you can customise the tooltip, too!<br />
testLabel:setStyleSheet("QToolTip{background: yellow; color: blue; border:none;}")<br />
</syntaxhighlight><br />
<br />
Without tooltip<br />
[[File:TestLabelForTooltips.png|thumb|center]]<br />
<br />
With tooltip<br />
<br />
[[File:LabelTooltip.png|thumb|center]]<br />
<br />
=== Avoid stylesheet inheritance by tooltip ===<br />
<br />
{{note}} If you set a new stylesheet for a label and with that a background image it is possible that through inheritance the tooltip also has this stylesheet image.<br />
<br />
To avoid this specify that the stylesheet is meant for the Label by using QLabel{...} in your Label stylesheet for exampleː<br />
<syntaxhighlight lang="lua"><br />
label = Geyser.Label:new({<br />
name = "label",<br />
x = "50%", y = "50%",<br />
width = "50%", height = "50%",<br />
})<br />
<br />
-- by using QLabel{...} the stylesheet won't be given to the tooltip as well<br />
label:setStyleSheet[[<br />
QLabel{<br />
border-image: url(/home/vadi/Desktop/iso-avatar-draft_0.png);}<br />
]]<br />
</syntaxhighlight><br />
<br />
<br />
=== Aligning text/images inside a label ===<br />
By default, text is [http://qt-project.org/doc/qt-5/qlabel.html#alignment-prop centered vertically and left aligned] in a label. To align it to a specific side, use the stylesheets we learnt about earlier with the qproperty-alignment:<br />
<br />
<syntaxhighlight lang="lua"><br />
mylabel = Geyser.Label:new({<br />
name = "testlabel",<br />
x = "50%", y = 0,<br />
width = "50%", height = "100%",<br />
fgColor = "black",<br />
color = "SeaGreen",<br />
message = [[<center>heey</center>]]<br />
})<br />
<br />
-- specify one property this way:<br />
mylabel:setStyleSheet([[qproperty-alignment: 'AlignTop';]])<br />
<br />
-- or multiple ones separated with a |, for example this will align text to top-left:<br />
mylabel:setStyleSheet([[<br />
qproperty-alignment: 'AlignLeft | AlignTop';<br />
]])<br />
<br />
mylabel:echo("hi!")<br />
</syntaxhighlight><br />
<br />
[[File:Text_aligned.png|center]]<br />
<br />
=== Enabling wordwrap in a label ===<br />
If you need to enable word wrapping in a label (which by default is off), add the following line to the labels stylesheet:<br />
<br />
qproperty-wordWrap: true;<br />
<br />
As an example:<br />
<br />
<syntaxhighlight lang="lua"><br />
mylabel:setStyleSheet([[<br />
qproperty-wordWrap: true;<br />
]])<br />
</syntaxhighlight><br />
<br />
If you'd like to set multiple properties, set them all at once - not via multiple :setStyleSheet() calls:<br />
<br />
<syntaxhighlight lang="lua"><br />
mylabel:setStyleSheet([[<br />
background: red;<br />
]])<br />
</syntaxhighlight><br />
<br />
=== Adding a hover effect to a label ===<br />
The labels support adding stylesheets for specific cases, such as when a mouse is [http://doc.qt.io/qt-5/stylesheet-reference.html#hover-ps hovering] over them. To make this work, you provide CSS for when the label is in its usual state, and for when it is hovered over:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- this example will add a border to the label when it is hovered over<br />
mylabell:setStyleSheet([[<br />
QLabel{ border-radius: 4px; }<br />
QLabel::hover{<br />
background-color: rgba(0,0,0,0%);<br />
border: 4px double green;<br />
border-radius: 4px;<br />
}<br />
]])<br />
</syntaxhighlight><br />
<br />
=== Checkboxes ===<br />
Combining the fact that you can click on a label with an image to do something with the fact that you can change pictures on a label at will, you can make an image that changes itself when you click on it.<br />
<br />
<syntaxhighlight lang="lua"><br />
picture_label = Geyser.Label:new({<br />
name = "picture_label",<br />
x = "50%", y = "50%",<br />
width = "21px", height = "19px"<br />
})<br />
-- a little trick we do to make the background of the label be transparent<br />
picture_label:setStyleSheet([[<br />
background-color: rgba(0,0,0,0%);<br />
]])<br />
<br />
picture_label:setBackgroundImage([[/home/vadi/Desktop/checkbox_ticked.png]])<br />
picture_label:setClickCallback("on_checkbox_press")<br />
<br />
function on_checkbox_press()<br />
if checkbox_ticked then<br />
checkbox_ticked = false<br />
picture_label:setBackgroundImage([[/home/vadi/Desktop/checkbox_unticked.png]])<br />
echo("Checkbox unticked.\n")<br />
else<br />
checkbox_ticked = true<br />
picture_label:setBackgroundImage([[/home/vadi/Desktop/checkbox_ticked.png]])<br />
echo("Checkbox TICKED!\n")<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
The ''on_checkbox_press()'' function this time keeps the track of the checkbox with the ''checkbox_ticked'' variable and sets the image appropriately. You can download the ticked ([[File:Checkbox_ticked.png]]) and unticked images ([[File:Checkbox_unticked.png]]) or the [http://wiki.mudlet.org/images/6/6d/Checkbox.mpackage whole package] altogether.<br />
<br />
[[File:Checkbox_demo.png|500px|center]]<br />
<br />
=== Animated labels with sprites ===<br />
You can animate sprite packs using timers. Assuming you have the sprite pack downloaded, try this example:<br />
<br />
<syntaxhighlight lang="lua"><br />
picture_label = Geyser.Label:new({<br />
name = "picture_label",<br />
x = 10, y = "-24px",<br />
width = "16px", height = "14px",<br />
})<br />
<br />
santa_counter = nil<br />
<br />
function animate_santa()<br />
santa_counter = (santa_counter or 0) + 1<br />
if santa_counter > 8 then santa_counter = 1 end<br />
<br />
picture_label:setBackgroundImage([[/home/vadi/Desktop/santa/santa]]..santa_counter..[[.png]]) -- update location to actual image location on your computer<br />
santa_timer = tempTimer(.16, animate_santa)<br />
end<br />
<br />
animate_santa()<br />
</syntaxhighlight><br />
<br />
The completed package is available [http://wiki.mudlet.org/images/6/6b/Dancing-santa.mpackage here], install it and do '''start/end animation''' to watch.<br />
<br />
=== Inserting extra spaces and newlines ===<br />
Echoing text into Mudlet and Geyser labels is different from miniconsoles and the main window, due to their nature. One of the differences is that extra spaces in a label, by default, get compressed down to one. '''To add extra spaces in a label''', replace extra spaces with '''&amp;nbsp;''' or by wrapping your text with them inside '''<nowiki><pre>my text here</pre></nowiki>'''.<br />
<br />
<syntaxhighlight lang="lua"><br />
-- this won't work, it'll show as one space:<br />
mylabel:echo("You -> point")<br />
<br />
-- but this would, because it replaces all spaces with &nbsp before echoing<br />
mylabel:echo(string.gsub("You -> point", " ", "&nbsp;"))<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- here is another way to go about this - and it additionally makes the font be monospaced:<br />
mylabel:echo("<pre>You -> point</pre>")<br />
</syntaxhighlight><br />
<br />
'''To add a new line in a label''' (aka linebreak), use '''<nowiki><br></nowiki>''' (instead of ''\n'' as you are used to in an echo).<br />
<syntaxhighlight lang="lua"><br />
mylabel:echo("These<br>words<br>are<br>split")<br />
</syntaxhighlight><br />
<br />
=== Transparent labels ===<br />
One of the possible ways of achieving transparency on a label is to add <code>background-color: rgba(0,0,0,0%);</code> to its stylesheet. Here's an example:<br />
<br />
<syntaxhighlight lang="lua"><br />
my_transparent_label:setStyleSheet([[<br />
background-color: rgba(0,0,0,0%);<br />
]])<br />
</syntaxhighlight><br />
<br />
Want to get transparency in a miniconsole? You can [[Manual:Geyser#Change_your_miniconsole_background_image|do that as well]].<br />
<br />
=== Custom mouse cursor ===<br />
You can change the shape of the cursor when it's over your label with:<br />
<syntaxhighlight lang="lua"><br />
mylabel:setCursor("Forbidden") -- will change your mouse cursor to "forbidden" (as in "can't do this") cursor<br />
</syntaxhighlight><br />
Possible cursor shapes are [[CursorShapes| available here]], and you can import this [[Media:Cursor grid.zip|demo package]] to try them all out.<br />
<br />
It is also possible to change the mouse cursor to a custom made cursor by:<br />
<syntaxhighlight lang="lua"><br />
mylabel:setCustomCursor(getMudletHomeDir().."/custom_cursor.png")<br />
</syntaxhighlight><br />
It is recommended that the custom cursor is a png with size of 32x32 to be supported on all systems.<br />
<br />
[[File:Changecursoroverlabel.gif]]<br />
<br />
{{Note}} Available in Mudlet 4.8+<br />
<br />
=== Flyout Labels ===<br />
<br />
Flyout labels allow you to create 'dropdown' or 'flyout' menus - menus that reveal more items once you hover your mouse over them. To create flyout labels:<br />
# add <code>nestable=true</code> (left click to open menu) or <code>nestflyout=true</code> (mouse hover to open menu) to your main label.<br />
# use [http://www.mudlet.org/geyser/files/geyser/GeyserLabel.html#Geyser.Label:addChild :addChild()] on your main label to add flyout labels to it.<br />
## [http://www.mudlet.org/geyser/files/geyser/GeyserLabel.html#Geyser.Label:addChild :addChild()] uses the same arguments as when creating a new label but also takes the '''layoutDir''' option to specify in which direction and axis should the labels align, where 2 letters combine into the option: first letter R for right, L for left, T for top, B for bottom, followed by the orientation: V for vertical or H for horizontal. So options are: <code>layoutDir="RV"</code>, <code>layoutDir="RH"</code>, <code>layoutDir="LV"</code>, <code>layoutDir="LH"</code>, and so on.<br />
# optionally, add <code>flyOut=true</code> to your flyout labels to make the labels dissapear when the mouse isn't hovering over them anymore.<br />
<br />
Note that the main flyout label cannot go into a container and needs to be on its own.<br />
<br />
{{note}} Requires Mudlet 3.0.<br />
<br />
==== Demo ====<br />
Here's an example that follows the steps above:<br />
<br />
<syntaxhighlight lang="lua"><br />
label0 = Geyser.Label:new({name="label0", <br />
x="50%",y="50%",height=50,width=300,nestable=true, <br />
message="<center>Clicky clicky</center>"})<br />
<br />
-- and add 3 labels to it with RV layout - so Right of the label, aligned Vertically<br />
label1 = label0:addChild({name="label1",height=30,width=70, layoutDir="RV", flyOut=true, message="label one"})<br />
label1:setStyleSheet([[background-color: purple; border-width: 2px; border-style: solid; border-color: blue; border-radius: 2px; font-size: 7pt;]])<br />
<br />
label2 = label0:addChild({name="label2",height=30,width=70, layoutDir="RV", flyOut=true, message="label two"}) <br />
label2:setStyleSheet([[background-color: green; border-width: 2px; border-style: solid; border-color: blue; border-radius: 2px; font-size: 7pt;]])<br />
<br />
label3 = label0:addChild({name="label3",height=30,width=70, layoutDir="RV", flyOut=true, message="label three"})<br />
label3:setStyleSheet([[background-color: red; border-width: 2px; border-style: solid; border-color: blue; border-radius: 2px; font-size: 7pt;]])<br />
</syntaxhighlight><br />
<br />
A more thorough example. Try it out to see what you can create with flyout labels:<br />
<syntaxhighlight lang="lua"><br />
-- create a label with a nestable=true property to say that it can nest labels<br />
mainlabel = Geyser.Label:new({name="testa", x=400,y=50,height=50,width=300,nestflyout=true, message="<center>HOVER HERE TO SEE FLY-OUT LABELS!</center>"})<br />
<br />
-- create 15 labels and store them in a table <br />
table_for_flyout_labels = {}<br />
for i=1,15 do<br />
-- options to layoutDir are the direction the window should go (R for right, L for left, T for top, B for bottom), followed by how the nested labels should be oriented (V for vertical or H for horizontal). So "BH" here means it'll go on the bottom of the label, while expanding horizontally<br />
table_for_flyout_labels[i] = mainlabel:addChild({name="test"..tostring(i),height=30,width=70, layoutDir="BH", flyOut=true, message="test"..tostring(i)})<br />
<br />
table_for_flyout_labels[i]:setStyleSheet([[background-color: purple; border-width: 2px; border-style: solid; border-color: blue; border-radius: 2px;]])<br />
end<br />
<br />
-- make the test5 label look a bit special as it has got a surprise<br />
table_for_flyout_labels[5]:echo("Hover here")<br />
<br />
-- add even more nested labels to the 5th label!<br />
even_more_flyout_labels = {}<br />
for i=1,60 do<br />
-- here, the layout will be to the right of it, while expanding vertically<br />
even_more_flyout_labels[i]=table_for_flyout_labels[5]:addChild({name="hover label "..tostring(i),height=30,width=100, layoutDir="RV", flyOut=true, message="label "..tostring(i)})<br />
even_more_flyout_labels[i]:setClickCallback("testFunc", even_more_flyout_labels[i].name)<br />
even_more_flyout_labels[i]:setStyleSheet([[background-color: grey; border-width: 2px; border-style: solid; border-color: green; border-width: 2px; font-size: 7pt;]])<br />
end<br />
<br />
function testFunc(name)<br />
display(name)<br />
end<br />
</syntaxhighlight><br />
<br />
It'll look something like this: <br />
<br />
[[File:Flyout_labels_demo.png|150px]]<br />
<br />
==== Demo of layouts ====<br />
Here's another demo that explains all of the layout styles quite well:<br />
<syntaxhighlight lang="lua"><br />
local directions = {"R", "L", "T", "B"}<br />
local orientations = {"V", "H"}<br />
local mappings = {R = "right", L = "left", T = "top", B = "bottom", V = "vertical", H = "horizontal"}<br />
<br />
local combinations, combination_labels = {}, {}<br />
for _, direction in pairs(directions) do<br />
for _, orientation in pairs(orientations) do<br />
combinations[#combinations+1] = direction..orientation<br />
end<br />
end<br />
<br />
local function get_foreground_text_colour(r,g,b)<br />
local luminosity = (0.2126 * ((r/255)^2.2)) + (0.7152 * ((g/255)^2.2)) + (0.0722 * ((b /255)^2.2))<br />
if luminosity > 0.5 then<br />
return "black"<br />
else<br />
return "white"<br />
end<br />
end<br />
<br />
local function get_random_colour_rgb()<br />
return math.random(1,255), math.random(1,255), math.random(1,255)<br />
end<br />
<br />
-- create a label with a nestable=true property to say that it can nest labels<br />
all_possible_combinations_label = Geyser.Label:new({name="all_possible_combinations_label", x=0,y="-400",height=50,width=500,<br />
nestable = true, message="<center>Click to see a listing of possible combinations</center>"})<br />
<br />
for i = 1, #combinations do<br />
local combination = combinations[i]<br />
combination_labels[i] = all_possible_combinations_label:addChild({name="combo_"..combination,height=30,width=150, nestable = true, flyOut=true, layoutDir="BH", message="<center>Combination "..combination.."</center>"})<br />
<br />
local r,g,b = get_random_colour_rgb()<br />
local text_colour = get_foreground_text_colour(r,g,b)<br />
<br />
local combination_labels_children = {}<br />
for ii = 1, 3 do<br />
combination_labels_children[ii] = combination_labels[i]:addChild({<br />
name="combo_"..combination.."_"..ii, height = 30, width = 150, layoutDir=combination, flyOut = true,<br />
message = string.format("<center><b>%s</b>%s+<b>%s</b>%s layout</center>", <br />
combination:sub(1,1), mappings[combination:sub(1,1)]:sub(2), combination:sub(2,2), mappings[combination:sub(2,2)]:sub(2)),<br />
fgColor = text_colour})<br />
<br />
combination_labels_children[ii]:setStyleSheet(string.format([[background-color:rgb(%d, %d, %d); border-width: 2px; border-style: solid; border-color: green; border-width: 2px; font-size: 7pt;]], r,g,b))<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
It'll look like this:<br />
<br />
[[File:Flyoutlabels-layout-demo.png]]<br />
<br />
=== Geyser.Label right click menu ===<br />
{{note}} available in Mudlet 4.10+<br />
<br />
You can create a right click menu for a label just by using the function (assuming your label name is 'myLabel')<br />
<syntaxhighlight lang="lua"> myLabelːcreateRightClickMenu(MenuItems = myMenuTable, other cons) -- see example below for details </syntaxhighlight><br />
<br />
The menu table comprises of all the items and their names. To create a parent menu just create a nested table of names.<br />
Example of a menuTable<br />
<syntaxhighlight lang="lua"> menuTable = {"First Item", "Second Item (Parent)",{"First ChildItem","Second ChildItem"}, "Third Item"} </syntaxhighlight><br />
As menu would look likeː<br />
<br />
[[File:RCDemo1.gif|250px]]<br />
<br />
==== Style your right click menu ====<br />
Your right click menu has 2 default styles integratedː "light" and "dark" which are defined by the constraint "Style".<br />
To set a default style just give the constraint Style the preferred value, for exampleː<br />
<syntaxhighlight lang="lua"> Style = "dark" </syntaxhighlight><br />
To give different levels of your menu different style just add the number of the level to the constraint, for exampleː<br />
<syntaxhighlight lang="lua"> Style2 = "light" -- Gives the second level of your menu the "light" style</syntaxhighlight><br />
<br />
For adding your own stylesheet use the constraint MenuStyle (use the same method as above to define stylesheets for different levels)<br />
<syntaxhighlight lang="lua"> MenuStyle2 = [[QLabel::hover{ background-color: rgba(0,255,150,100%); color: white;} QLabel::!hover{color: brown; background-color: rgba(100,240,240,100%);} ]] <br />
-- Gives the second level of your menu this stylesheet</syntaxhighlight><br />
<br />
The same methods are used for defining the format, width and height for the menu item.<br />
<syntaxhighlight lang="lua"> <br />
MenuWidth = 70 -- standard menu width if nothing else is given<br />
MenuWidth2 = 80 -- menu width for the second level <br />
MenuFormat1 = "c10" -- menu format for the first level (format works like any other label echo format, in this case c is center and 10 is the font-size)<br />
MenuHeight = 30<br />
</syntaxhighlight><br />
<br />
==== Set onClick action for your menu item ====<br />
To set an action if your menu item is clicked use the function (assuming your label name is 'myLabel' and using the same MenuItems as defined above)<br />
<syntaxhighlight lang="lua"> <br />
myLabelːsetMenuAction("First Item", function() echo("Clicked on the first item\n") end<br />
myLabelːsetMenuAction("Second Item (Parent).First ChildItem", function() echo("Clicked on the first child item\n") end) -- To set an action to a child item find it by using "Parent.Child" as name (only one parent is needed to be given the parents parent is not needed)<br />
</syntaxhighlight><br />
<br />
==== Access an menu item directly ====<br />
The simplest way to access a menu item directly is by just using the function (assuming your label name is 'myLabel' and using the same MenuItems as defined above)<br />
For example to change the menu item textː<br />
<syntaxhighlight lang="lua"> <br />
myLabelːfindMenuElement("First Item"):echo([[my first Item]])<br />
</syntaxhighlight><br />
<br />
==== Right click menu example ====<br />
Better then any further explanation is probably this practical example. <br />
<br />
<syntaxhighlight lang="lua"> <br />
-- create the label the right click menu will be in<br />
myRightClickLabel = myRightClickLabel or Geyser.Label:new({<br />
name = "myRightClickLabel", message = "Please right click!", <br />
format = "cb15", x=10, y=10, width ="30%", height = "15%", <br />
color = "purple"})<br />
<br />
-- right click menu creation with custom styleheet on level2 and default "Dark" style <br />
myRightClickLabel:createRightClickMenu(<br />
{MenuItems = {"Emergency", "Drink",{"ManaPotion","HealthPotion"}, "Disappear", "Cast",{"Blindness", "Blink"}}, <br />
Style = "Dark", <br />
MenuWidth2 = 80, <br />
MenuFormat1 = "c10",<br />
MenuStyle2 = [[QLabel::hover{ background-color: rgba(0,255,150,100%); color: white;} QLabel::!hover{color: brown; background-color: rgba(100,240,240,100%);} ]]}<br />
)<br />
<br />
myRightClickLabel:setMenuAction("Emergency", function() <br />
cecho("<red:pink>[Emergency Mode] Run as fast as possible!\n") <br />
send("emergency") <br />
closeAllLevels(myRightClickLabel) -- this can be used to close the right click menu if clicked on this item<br />
end)<br />
<br />
myRightClickLabel:setMenuAction("Drink.ManaPotion", function()<br />
cecho("<blue>Drinking my mana potion.\n") <br />
send("drink mp") <br />
end )<br />
<br />
myRightClickLabel:setMenuAction("Drink.HealthPotion", function() <br />
cecho("<red>Drinking my health potion.\n") <br />
send("drink hp") <br />
end )<br />
<br />
myRightClickLabel:setMenuAction("Disappear", function() <br />
cecho("<grey>Disappearing.. \n") <br />
send("disappear") <br />
closeAllLevels(myRightClickLabel) <br />
end )<br />
<br />
myRightClickLabel:setMenuAction("Cast.Blindness", function() <br />
cecho("<light_blue>Casting blindness \n") <br />
send("cast blindness enemy") <br />
closeAllLevels(myRightClickLabel) <br />
end )<br />
<br />
myRightClickLabel:setMenuAction("Cast.Blink", function() <br />
cecho("<light_blue>Casting blink \n") <br />
send("cast blink") <br />
end )<br />
</syntaxhighlight><br />
<br />
This looks likeː<br />
<br />
<br />
[[File:Right click example demo.gif]]<br />
<br />
==== Add right click menu to label with already existing left click action ====<br />
If your label has an already existing left click action you'll have to create the right click menu<br />
"before" creating the labels "setClickCallBack" action and then just put into your labels onClick function<br />
(assuming your label name is 'myLabel' and 'event' is the last parameter of your onClick function)<br />
<br />
<syntaxhighlight lang="lua"> <br />
myLabel:onRightClick(event)<br />
</syntaxhighlight><br />
<br />
=== Geyser name ===<br />
Make sure to give your Geyser Labels, miniconsoles, and userwindows a <code>name</code> - while it'll technically work without one, items will be duplicated when you re-save them if they're lacking a name.<br />
<br />
==[http://www.mudlet.org/geyser/files/geyser/GeyserStyleSheet.html Geyser.StyleSheet]==<br />
<br />
Allows you to create a managed stylesheet to make it easier to set and change properties. Also allows you to inherit properties from another stylesheet, making it easier to manage multiple styles at once.<br />
<br />
=== Basic Usage ===<br />
<br />
Here's an example to get you started. This creates a basic stylesheet to set the background color black and the foreground/text color to green, then applies it to a Geyser Label.<br />
<br />
<syntaxhighlight lang="lua"><br />
local stylesheet = Geyser.StyleSheet:new([[<br />
background-color: black;<br />
color: green;<br />
]])<br />
local testLabel = Geyser.Label:new({<br />
name = "testLabel",<br />
x = 100,<br />
y = 100,<br />
height = 100,<br />
width = 300,<br />
stylesheet = stylesheet:getCSS(),<br />
})<br />
<br />
-- Alternate method of creating a stylesheet using a table of properties<br />
local stylesheet = Geyser.StyleSheet:new({<br />
['background-color'] = "black",<br />
['color'] = "green",<br />
})<br />
</syntaxhighlight><br />
<br />
=== Getting the CSS string === <br />
<br />
As shown above, you can use getCSS to get the stylesheet as a string.<br />
<br />
<syntaxhighlight lang="lua"><br />
display(stylesheet:getCSS())<br />
--[[<br />
"background-color: black;\ncolor: green;"<br />
--]]<br />
</syntaxhighlight><br />
<br />
=== Including a target ===<br />
<br />
You can include a 'target' for your stylesheet to be applied to, such as QLabel, QPlainTextEdit, etc.<br />
<br />
<syntaxhighlight lang="lua"><br />
-- QPlainTextEdit is useful for styling command lines in particular, to keep the style from bleeding into any associated miniconsole or userwindow.<br />
local stylesheet = Geyser.StyleSheet:new([[<br />
QPlainTextEdit {<br />
background-color: black;<br />
color: green;<br />
}]])<br />
<br />
-- or as an optional third argument. Passing nil for the parent explicitly <br />
local stylesheet = Geyser.StyleSheet:new([[<br />
background-color: black;<br />
color: green;<br />
]], nil, "QPlainTextEdit")<br />
<br />
-- or using the setTarget function after the fact<br />
local stylesheet = Geyser.StyleSheet:new([[<br />
background-color: black;<br />
color: green;<br />
]])<br />
stylesheet:setTarget("QPlainTextEdit")<br />
</syntaxhighlight><br />
<br />
=== Changing a property ===<br />
<br />
Assuming you started with the example above, if you wanted to change the background color to purple you would do the following:<br />
<br />
<syntaxhighlight lang="lua"><br />
stylesheet:set("background-color", "purple")<br />
testLabel:setStyleSheet(stylesheet:getCSS())<br />
</syntaxhighlight><br />
<br />
Or if you wanted to set the font, you would do:<br />
<syntaxhighlight lang="lua"><br />
stylesheet:set("font", [["Ubuntu Mono"]])<br />
</syntaxhighlight><br />
<br />
Note the way we set the font with the double quotes included in the string, this is because the quotes have to be there in the final stylesheet. You could use single quotes instead of the bracket notation as well:<br />
<br />
<syntaxhighlight lang="lua"><br />
stylesheet:set("font", '"Ubuntu Mono"')<br />
</syntaxhighlight><br />
<br />
=== Getting the value of a property ===<br />
<br />
Again assuming you started with the example code above it's as easy as<br />
<br />
<syntaxhighlight lang="lua"><br />
stylesheet:get("color") -- will return "green"<br />
</syntaxhighlight><br />
<br />
=== Getting a table of properties and their values ===<br />
<br />
<syntaxhighlight lang="lua"><br />
display(stylesheet:getStyleTable())<br />
--[[<br />
{<br />
["background-color"] = "purple",<br />
color = "green",<br />
font = '"Ubuntu Mono"'<br />
}<br />
--]]<br />
</syntaxhighlight><br />
<br />
=== Setting the properties via table ===<br />
<br />
<syntaxhighlight lang="lua"><br />
stylesheet:setStyleTable({<br />
["background-color"] = "purple",<br />
color = "green",<br />
font = '"Ubuntu Mono"',<br />
})<br />
</syntaxhighlight><br />
<br />
=== Resetting the style with a string ===<br />
<br />
Creating a new Geyser.StyleSheet would break any inheritance for stylesheets which had this one as a parent (see below), so if you wish to reset the style via CSS string you should use :setCSS<br />
<br />
<syntaxhighlight lang="lua"><br />
stylesheet:setCSS([[<br />
background-color: black;<br />
color: green;<br />
font: "Ubuntu Mono";<br />
]])<br />
</syntaxhighlight><br />
<br />
=== Inheriting properties ===<br />
<br />
As with most things Geyser, just pass the parent in when you create the new stylesheet<br />
<br />
<syntaxhighlight lang="lua"><br />
local childsheet = Geyser.StyleSheet:new("color: blue;", stylesheet)<br />
display(childsheet:getStyleTable())<br />
--[[<br />
{<br />
["background-color"] = "purple",<br />
color = "blue",<br />
font = '"Ubuntu Mono"'<br />
}<br />
--]]<br />
<br />
display(childsheet:get("background-color")<br />
--"purple"<br />
<br />
-- show only properties set in this stylesheet, without inheritance<br />
display(childsheet:getStyleTable(false))<br />
--[[<br />
{<br />
color = "blue"<br />
}<br />
--]]<br />
<br />
-- can do the same for the CSS string<br />
display(childsheet:getCSS(false))<br />
--[[<br />
"color: blue;"<br />
--]]<br />
</syntaxhighlight><br />
<br />
==[http://www.mudlet.org/geyser/files/geyser/GeyserMiniConsole.html Geyser.MiniConsole]==<br />
This allows you to spawn a Mudlet miniconsole - unlike labels, these aren't as styleable, but they do format text better. They make a good fit for text-based menus, chat and map capture, and other things.<br />
<br />
Spawning one is very similar to other Geyser elements - paste this into a new script:<br />
<syntaxhighlight lang="lua"><br />
HelloWorld = Geyser.MiniConsole:new({<br />
name="HelloWorld",<br />
x="70%", y="50%",<br />
autoWrap = true,<br />
color = "black",<br />
scrollBar = false,<br />
fontSize = 8,<br />
width="30%", height="50%",<br />
})<br />
</syntaxhighlight><br />
<br />
This'll make you one at the bottom-right of the screen. The miniconsole will have a grey background by default, but you can set it to any color you'd like with [http://www.mudlet.org/geyser/files/geyser/GeyserWindow.html#Geyser.Window:setColor miniconsole:setColor()]:<br />
<br />
<syntaxhighlight lang="lua"><br />
HelloWorld:setColor("black") -- give it a nice black background<br />
</syntaxhighlight><br />
<br />
A special dimension property that MiniConsoles have is a character - instead of specifying a miniconsole to be % of a container or a certain number of pixels, you can specify it as a certain number of characters. You do this by using "c" at the end of a number. This way, you can, for example, specify miniconsole to be 10 letters long and 2 lines high:<br />
<br />
<syntaxhighlight lang="lua"><br />
flatbox = Geyser.MiniConsole:new({<br />
name="flatbox",<br />
x="70%", y="50%",<br />
wrapAt = 10,<br />
width="10c", height="2c",<br />
})<br />
flatbox:setColor("red")<br />
flatbox:echo("ABCDEFGHIJ") -- that is 10 letters<br />
</syntaxhighlight><br />
<br />
=== Adding text ===<br />
You can use [[Manual:Technical_Manual#echo|echo()]] the same way with a miniconsole to add text as to the usual window:<br />
<br />
<syntaxhighlight lang="lua"><br />
HelloWorld:echo("hello!")<br />
</syntaxhighlight><br />
<br />
As well as [[Manual:Technical_Manual#cecho|cecho]], [[Manual:Technical_Manual#decho|decho]], or [[Manual:Technical_Manual#hecho|hecho]]:<br />
<br />
<syntaxhighlight lang="lua"><br />
HelloWorld:cecho("<green>hey, <blue>colored <red>text!\n")<br />
</syntaxhighlight><br />
<br />
=== Copying lines with color ===<br />
To copy a line over to the miniconsole, as it is from the game with all colors preserved, you can [[Manual:UI_Functions#selectCurrentLine|select]], [[Manual:UI_Functions#copy|copy]], and [[Manual:UI_Functions#appendBuffer|append]] it. For an example, try making a trigger with this as the ''Lua function'' pattern type:<br />
<br />
<syntaxhighlight lang="lua"><br />
return true<br />
</syntaxhighlight><br />
<br />
That'll make the trigger go off on every line. Then give it the following script (assumed you have made the HelloWorld miniconsole from earlier):<br />
<syntaxhighlight lang="lua"><br />
selectCurrentLine()<br />
copy()<br />
HelloWorld:appendBuffer()<br />
</syntaxhighlight><br />
<br />
... and you'll see all MUD output duplicated exactly as it is to the miniconsole. Amazing! It's very efficient as well, so you can have many miniconsoles, even in spam, not lag you down.<br />
<br />
=== Clearing the miniconsole ===<br />
Clearing the miniconsole just requires using the following script (assumes you have made the HelloWorld miniconsole from earlier):<br />
<br />
<syntaxhighlight lang="lua"><br />
HelloWorld:clear()<br />
</syntaxhighlight><br />
<br />
=== Doing edits in copied lines ===<br />
Sometimes you'll want to edit the line before stuffing it into the miniconsole. For example, if you're making a chat capture, you'd want to condense a really long org name into something that's more space-friendly.<br />
<br />
To do so, you'd use the [[Manual:Technical_Manual#selectString|selectString()]] the text you'd like to modify, [[Manual:Technical_Manual#replace|replace()]] it with a different one:<br />
<br />
<syntaxhighlight lang="lua"><br />
selectString("Your", 1) -- select the word you'd like to replace - in this case, 'Your'<br />
setBgColor(getBgColor()) -- preserve the background color in the replacement<br />
setFgColor(getFgColor()) -- preserve the foreground color in the replacement<br />
replace("Mine") -- replace the selection with the wird 'Mine'<br />
<br />
selectCurrentLine()<br />
copy()<br />
HelloWorld:appendBuffer()<br />
</syntaxhighlight><br />
<br />
=== Gagging from the main window ===<br />
If you'd like to gag the line from the main window so it only shows up in your miniconsole, [[Manual:Technical_Manual#deleteLine|delete]] it after moving it over:<br />
<br />
<syntaxhighlight lang="lua"><br />
selectCurrentLine()<br />
copy()<br />
HelloWorld:appendBuffer()<br />
deleteLine()<br />
</syntaxhighlight><br />
<br />
=== Clickable menus ===<br />
Using the [[Manual:Technical_Manual#echoLink|echoLink]], [[Manual:Technical_Manual#insertLink|insertLink]] and [[Manual:Technical_Manual#setLink|setLink]] functions, you can turn text into one that reacts on a click. Combined with your power of placing text anywhere on the screen with a miniconsole, you can make menus with options. Here is one such example, where selecting an item causes an echo to happen:<br />
<br />
<syntaxhighlight lang="lua"><br />
flatbox = Geyser.MiniConsole:new({<br />
name="flatbox",<br />
x="20%", y="80%",<br />
width="40c", height="4c",<br />
})<br />
flatbox:setColor("red")<br />
clearWindow("flatbox")<br />
<br />
flatbox:cecho("<white:red>Choose one of the following options:\n")<br />
<br />
flatbox:fg("white")<br />
flatbox:bg("red")<br />
<br />
for _, fruit in ipairs{"banana", "apple", "orange"} do<br />
echoLink("flatbox", "* "..fruit:title().."\n", [[echo("You picked ]]..fruit..[[\n")]], "The "..fruit.." option", true)<br />
end<br />
<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
This will produce something like the following:<br />
<br />
[[File:Fruit_menu.png|center]]<br />
<br />
=== Change your miniconsole background image ===<br />
{{note}} available in Mudlet 4.10+<br />
<br />
To set a custom background image for your miniconsole, use [https://www.mudlet.org/geyser/files/geyser/GeyserMiniConsole.html#Geyser.MiniConsole:setBackgroundImage :setBackgroundImage()]:<br />
<syntaxhighlight lang="lua"><br />
miniconsole_withBgImg = Geyser.MiniConsole:new({name = "BackgroundonConsole", x="50%", y="50%", width = "20%", height = "40%"})<br />
miniconsole_withBgImg:setBackgroundImage(":/Mudlet_splashscreen_development.png", "center")<br />
<br />
for i = 1, 6 do<br />
miniconsole_withBgImg:decho("<:0,0,0,130> This is a decho test with semi-transparent background\n")<br />
end<br />
<br />
for i = 1, 6 do<br />
miniconsole_withBgImg:hecho("#,80000000 This is a hecho test with semi-transparent background\n")<br />
end<br />
<br />
for i = 1, 2 do<br />
miniconsole_withBgImg:decho("<:0,0,0> This is a decho test with no transparent background\n")<br />
end<br />
<br />
for i = 1, 2 do<br />
miniconsole_withBgImg:hecho("#,000000 This is a hecho test with no transparent background\n")<br />
end<br />
</syntaxhighlight><br />
<br />
=== Enable and use your miniconsole command line ===<br />
{{note}} available in Mudlet 4.10+<br />
<br />
Every miniconsole has a hidden command line. Enable it with:<br />
<syntaxhighlight lang="lua"><br />
HelloWorldContainer = HelloWorldContainer or Adjustable.Container:new({name="HelloWorldContainer", titleText = "Container with a command line"})<br />
<br />
HelloWorld = Geyser.MiniConsole:new({<br />
name="HelloWorld",<br />
x=0, y=0,<br />
autoWrap = true,<br />
color = "purple",<br />
scrollBar = false,<br />
fontSize = 8,<br />
width="100%", height="100%",<br />
}, HelloWorldContainer)<br />
<br />
HelloWorld:enableCommandLine()<br />
</syntaxhighlight><br />
<br />
=== Set an action to your miniconsole command line ===<br />
If no action is set to your miniconsole command line the commands are send to the game the same way as for the main command line. Aliases still work as usual, and if you have command echo enabled in preferences, it'll show in both miniconsole and the main window.<br />
<br />
It is also possible to set an action to your command line, this enables you to use the command line as custom text input.<br />
<br />
<syntaxhighlight lang="lua"><br />
HelloWorld:enableCommandLine()<br />
local function channelChat(text)<br />
send("chat "..text)<br />
HelloWorld:echo("[chat] " ..text.."\n")<br />
end<br />
<br />
HelloWorld:setCmdAction(channelChat)<br />
</syntaxhighlight><br />
<br />
This will send your miniconsole command line input to the chat channel.<br />
<br />
More complicated/sophisticated actions are possible, setCmdAction works the same way as the Label clickCallback functions - that is, you can pass arguments to it.<br />
<br />
==[http://www.mudlet.org/geyser/files/geyser/GeyserGauge.html Geyser.Gauge]==<br />
<!--<br />
This is a composite window. Gauge duplicates the functionality of the built in Mudlet gauges, but in a clean and easily extended way. Internally, a Geyser Gauge is a container holding two Labels, front and back, which are initially scaled to fill the entire Gauge container. Hence, a gauge, g, can be given callbacks with the g.front:setClickCallback() method.<br />
<br />
The backgroundColor parameter initially sets the colors of the gauge, but of course the front and back components can be accessed individually as labels for high control over their looks. Gauges can be horizontal or vertical and decrease in value left to right, right to left, down up or up down depending on the value of the orientation parameter.<br />
--><br />
<br />
A Gauge allows you to represent numbers on a scale - and most typically, you've seen it be used as your standard hp/mana/whatever bar. A basic bar is made similarly to other Geyser elements. To set the value on the gauge that it should represent, use the [http://www.mudlet.org/geyser/files/geyser/GeyserGauge.html#Geyser.Gauge:setValue setValue()] function:<br />
<br />
<syntaxhighlight lang="lua"><br />
hpbar = Geyser.Gauge:new({<br />
name="hpbar",<br />
x="50%", y="85%",<br />
width="45%", height="5%",<br />
})<br />
hpbar:setValue(math.random(1,100),100)<br />
</syntaxhighlight><br />
<br />
That'll spawn you a pretty basic gauge with a horizontal orientation and a grey colour - and as a test, with a random value.<br />
<br />
[[File:Basic_gauge.png|center]]<br />
<br />
=== Updating a gauge ===<br />
You'd want your gauge to stay in sync with your actual values. To make that happen, you want to call [http://www.mudlet.org/geyser/files/geyser/GeyserGauge.html#Geyser.Gauge:setValue setValue()] whenever the value that the gauge is tracking changes.<br />
<br />
So for example, if you make a health bar - wherever you get your new health at (be it prompt, gmcp, atcp or whatever), update the gauge as well:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- theoretical example<br />
current_health, max_health = tonumber(matches[2]), tonumber(matches[3])<br />
<br />
-- update the bar<br />
hp_bar:setValue(current_health, max_health)<br />
</syntaxhighlight><br />
<br />
You can also write down how much health have you got on the bar with:<br />
<br />
<syntaxhighlight lang="lua"><br />
lua local hp = math.random(1,100) <br />
hpbar:setValue(current_health, max_health, "<b>"..max_health.."hp</b>")<br />
<br />
-- example using GMCP in IRE games:<br />
hpbar:setValue((100/gmcp.Char.Vitals.maxhp)*gmcp.Char.Vitals.hp,100,gmcp.Char.Vitals.hp)<br />
</syntaxhighlight><br />
<br />
[[File:Hpbar_basic.png|center]]<br />
<br />
=== Styling a gauge ===<br />
The Geyser gauge is composed of three labels - one is called ''mygauge.front'', ''mygauge.back'' and ''mygauge.text''. Combining this with Geyser:Label.setStyleSheet, you can improve the visuals of your gauges by using Qt-supported CSS. The syntax for specifying CSS is a bit different - it requires a semicolon after every property, and is done in the format of ''property name''''':'''''values''''';'''. A list of all possible properties you can use is [http://doc.qt.io/qt-5/stylesheet-reference.html#list-of-properties available here] and you can use [https://build-system.fman.io/qt-designer-download Qt Designer] to create them. Practical example:<br />
<br />
<syntaxhighlight lang="lua"><br />
hpbar = Geyser.Gauge:new({<br />
name="hpbar",<br />
x="50%", y="85%",<br />
width="45%", height="20px",<br />
})<br />
hpbar.front:setStyleSheet([[background-color: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #98f041, stop: 0.1 #8cf029, stop: 0.49 #66cc00, stop: 0.5 #52a300, stop: 1 #66cc00);<br />
border-top: 1px black solid;<br />
border-left: 1px black solid;<br />
border-bottom: 1px black solid;<br />
border-radius: 7;<br />
padding: 3px;<br />
]])<br />
hpbar.back:setStyleSheet([[background-color: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #78bd33, stop: 0.1 #6ebd20, stop: 0.49 #4c9900, stop: 0.5 #387000, stop: 1 #4c9900);<br />
border-width: 1px;<br />
border-color: black;<br />
border-style: solid;<br />
border-radius: 7;<br />
padding: 3px;<br />
]])<br />
<br />
hpbar:setValue(math.random(1,100),100)<br />
</syntaxhighlight><br />
<br />
[[File:Fancy_Geyser_gauge.png|center]]<br />
<br />
The same style can be adjusted by colors to red as well:<br />
<br />
<syntaxhighlight lang="lua"><br />
hpbar = Geyser.Gauge:new({<br />
name="hpbar",<br />
x="50%", y="85%",<br />
width="45%", height="20px",<br />
})<br />
hpbar.front:setStyleSheet([[background-color: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #f04141, stop: 0.1 #ef2929, stop: 0.49 #cc0000, stop: 0.5 #a40000, stop: 1 #cc0000);<br />
border-top: 1px black solid;<br />
border-left: 1px black solid;<br />
border-bottom: 1px black solid;<br />
border-radius: 7;<br />
padding: 3px;]])<br />
hpbar.back:setStyleSheet([[background-color: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #bd3333, stop: 0.1 #bd2020, stop: 0.49 #990000, stop: 0.5 #700000, stop: 1 #990000);<br />
border-width: 1px;<br />
border-color: black;<br />
border-style: solid;<br />
border-radius: 7;<br />
padding: 3px;]])<br />
<br />
hpbar:setValue(math.random(1,100),100)<br />
</syntaxhighlight><br />
<br />
[[File:Fancy_Geyser_gauge_red.png|center]]<br />
<br />
=== Updating a gauge ===<br />
The Geyser gauge is composed of three labels - one is called ''mygauge.front'', ''mygauge.back'' and ''mygauge.text''. To make a gauge clickable you can set a ClickCallBack on the top label which is ''mygauge.text'' example: <syntaxhighlight lang="lua">mygauge.text:setClickCallback("functionName", variableToSendToFunctionName)</syntaxhighlight><br><br />
If you would like to have different click events for the top or back of a gauge you can enable clickThrough for the top or ''mygauge.text'' label example<br />
<br />
<syntaxhighlight lang="lua"><br />
mygauge.text:enableClickthrough()<br />
mygauge.front:setClickCallback("functionOne", variableToSendToFunctionOne)<br />
mygauge.back:setClickCallback("functionTwo", variableToSendToFunctionTwo)<br />
</syntaxhighlight><br />
<br />
<br />
=== Tooltips on gauges ===<br />
Tooltips are available since Mudlet 4.6 as explained in above section [[#Adding_a_tooltip_to_a_label]], and as gauges are really only made up of labels as well, you could add a tooltip then by just using <syntaxhighlight lang="lua">mygauge.text:setToolTip("This is the gauge's tooltip", "10")</syntaxhighlight> the same as it's handled for clickback.<br />
<br />
== HBox/VBox ==<br />
<br />
These are special types of containers. Every window in these is horizontally or vertically aligned in the order they were added.<br />
<br />
<sub>Added to Mudlet in 2.0-rc4</sub><br />
<br />
== Geyser.UserWindow ==<br />
Allows you to use Mudlets UserWindows within Geyser, which allows you to use all the functionality of a MiniConsole in its basic form.<br />
The big advantage is the possibility to add other Geyser Elements like Labels, MiniConsole, Gauges, Mappers to the UserWindow.<br />
The UserWindow then can act as container for those elements with all the perks of dynamic resizing or any other Geyser functionality.<br />
<br />
{{note}} available in Mudlet 4.6.1+<br />
<br />
===Basic floating userwindow ===<br />
This will create a movable floating userwindow.<br />
<br />
<syntaxhighlight lang="lua"><br />
testuserwindow = Geyser.UserWindow:new({<br />
name = "TestUserWindow",<br />
titleText ="My Test UserWindow", -- only available since Mudlet 4.8+<br />
x = "20%", y="20%",<br />
width="30%", height ="40%"<br />
})<br />
</syntaxhighlight><br />
<br />
You can change the title of the userwindow by using the parameger titleText and the functions below (as of Mudlet 4.8+)ː<br />
<br />
To set a new title after creation useː<br />
<syntaxhighlight lang="lua"><br />
testuserwindow:setTitle("My new title Text")<br />
</syntaxhighlight><br />
<br />
To revert to the standard title useː<br />
<syntaxhighlight lang="lua"><br />
testuserwindow:resetTitle()<br />
</syntaxhighlight><br />
<br />
To '''save the position''' of the userwindow - say in case you've dragged it onto another monitor and would like it to stay there when you restart Mudlet - use [[Manual:UI_Functions#saveWindowLayout|saveWindowLayout()]]:<br />
<br />
<syntaxhighlight lang="lua"><br />
saveWindowLayout()<br />
</syntaxhighlight><br />
<br />
To restore it afterwards, use [[Manual:UI_Functions#loadWindowLayout|loadWindowLayout()]]:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- create your userwindows first with Geyser.UserWindow:new<br />
-- then restore them to the positions they were at:<br />
loadWindowLayout()<br />
</syntaxhighlight><br />
<br />
=== Docked UserWindow ===<br />
To create the window docked at the right side,<br />
set the variable docked (at creation of the container) to true.<br />
Be aware that with this variable set to true the position and the size at creation of the userwindow will be ignored.<br />
<br />
<syntaxhighlight lang="lua"><br />
testuserwindow = Geyser.UserWindow:new({<br />
name = "DockedTestUserWindow",<br />
docked = true<br />
<br />
})<br />
</syntaxhighlight><br />
<br />
Since Mudlet 4.8+ it is also possible to choose the docking Position of the UserWindow at creation and by function withː<br />
<br />
<syntaxhighlight lang="lua"><br />
testuserwindow = Geyser.UserWindow:new({<br />
name = "DockedTestUserWindow",<br />
docked = true,<br />
dockPosition = "top" -- Possible dockPositions are left "l", right "r", top "t", bottom "b" and floating "f" <br />
})<br />
</syntaxhighlight><br />
<br />
To change it for a already created UserWindow use the function setDockPosition(dockPosition) likeː<br />
<syntaxhighlight lang="lua"><br />
testuserwindow:setDockPosition("left")<br />
</syntaxhighlight><br />
<br />
=== Disable/enable UserWindow autoDock ===<br />
{{note}} available in Mudlet 4.8+<br />
<br />
The auto docking feature can be really annoying at times. To disable it use the functionsː<br />
<syntaxhighlight lang="lua"><br />
testuserwindow:disableAutoDock() -- disables autoDock. Docking still possible with ːsetDockPosition<br />
testuserwindow:enableAutoDock() -- reenables autoDock<br />
</syntaxhighlight><br />
<br />
=== Styling the UserWindow border and title area ===<br />
{{note}} available in Mudlet 4.10+ and Linux only<br />
<br />
Geyser.UserWindows can accept a stylesheet to change the appearance of the border and title area and make<br />
the UserWindow look more appealing. This unfortunately only works in Linux, as in macOS and Windows, it is the OS theme that is used here. <br />
<br />
<syntaxhighlight lang="lua"><br />
myUserWindow = myUserWindow or Geyser.UserWindow:new({<br />
name = "myUserWindow", titleText = "myUserWindow", autoDock = false<br />
})<br />
<br />
myUserWindow:setStyleSheet( <br />
[[QDockWidget{<br />
border: 1px solid green; /* UserWindow border style */<br />
font: bold 15pt "Arial"; /* Font of the titleBar */<br />
color: rgb(0,0,150); /* Font color */<br />
}<br />
<br />
QDockWidget::title{ <br />
background-color: rgb(0,255,150); /* TitleBar color */<br />
border: 2px solid red; /* TitleBar border */<br />
border-radius: 2px; /* TitleBar border radius */<br />
text-align: center; /* alignment of the titleText */<br />
}<br />
]])<br />
</syntaxhighlight><br />
<br />
This looks likeː<br />
<br />
[[File:UserWindowStyleSheet.png]]<br />
<br />
=== UserWindow as Container ===<br />
This is the feature which shows the versatile nature of Geyser.UserWindows.<br />
The UserWindow act as container and is at that possible to dynamically resize the containing Geyser Elments.<br />
Put a label in the UserWindow resize it as rectangle.<br />
<syntaxhighlight lang="lua"><br />
testuserwindow = Geyser.UserWindow:new({<br />
name = "ParentTestUserWindow",<br />
x = "20%", y="20%",<br />
width="30%", height ="40%"<br />
})<br />
<br />
testuserwindow:setColor("dark_green") -- give the userwindow a bit of color <br />
<br />
labelinuserw = Geyser.Label:new({<br />
name = "LabelinUserWindow",<br />
x=20, y=20,<br />
width = -20, height = -20,<br />
color="light_blue", fontSize=20,<br />
},testuserwindow)<br />
<br />
labelinuserw:echo("This is a label in an userwindow", "black", "c")<br />
</syntaxhighlight><br />
[[File:LabelInUserWindow.png]]<br />
<br />
The same way you are able to add your favorite Geyser Application (like tabbed chat, animated timers, gauges) to an UserWindow.<br />
<br />
Note that you don't need to add MiniConsoles to a UserWindow - as UserWindows already have them built-in.<br />
<br />
[[File:Tabbedchatinuserwindow.png]]<br />
<br />
== Geyser.CommandLine ==<br />
{{note}} available in Mudlet 4.10+<br />
<br />
Allows you to create your custom command lines which can resize/move like any other Geyser object.<br />
<br />
If you just need a command line which is integrated in a miniconsole or userwindow, check out [[Manual:Geyser#Enable and use your miniconsole command line|:enableCommandLine()]].<br />
<br />
=== Creating a Geyser.CommandLine ===<br />
An example to get you startedː<br />
<syntaxhighlight lang="lua"><br />
myCommandLine = myCommandLine or Geyser.CommandLine:new({<br />
name = "myCommandLine", <br />
x = "-20%", y = -40, <br />
width = "20%", height = 40,<br />
stylesheet = "border: 1px solid silver;"<br />
})<br />
</syntaxhighlight><br />
This creates a new command line in the right bottom of your screen.<br />
<br />
=== Bind action to your command line input ===<br />
If you use your previously created command line, any command will just be send to the game, after having been checked for aliases.<br />
<br />
To react to any input in a custom manner, we can set an action to the command line and use the input as parameter.<br />
<br />
Example of a command line changing the background color of your main console (assumes you have created "myCommandLine" from earlier): <br />
<syntaxhighlight lang="lua"><br />
myCommandLine:setAction(<br />
function(commandLineInput)<br />
r, g, b = Geyser.Color.parse(commandLineInput) -- gets the r, g, b values of the color you input to the command line<br />
if b then -- checks if the color is valid<br />
setBackgroundColor(r, g, b)<br />
else<br />
echo("\n"..commandLineInput.." is not a valid color. Try again.")<br />
end<br />
end)<br />
</syntaxhighlight><br />
<br />
=== Styling a command line ===<br />
You can style your Geyser command line by using Qt-supported CSS. A list of all possible properties you can use is [http://doc.qt.io/qt-5/stylesheet-reference.html#list-of-properties available here].<br />
<br />
Practical example (assuming "myCommandLine" is created)ː<br />
<syntaxhighlight lang="lua"><br />
myCommandLine:setStyleSheet([[<br />
QPlainTextEdit{ /* QPlainTextEdit is used to prevent the styleSheet bleeding to the right click menu*/<br />
border: 1px solid silver; /* Command line border style */<br />
background-color: rgb(0,255,150); /* Command line background color */<br />
font: bold 12pt "Arial"; /* Font and font-size of your command line */<br />
color: rgb(0,0,150); /* Command line text color */<br />
}<br />
]])<br />
</syntaxhighlight><br />
<br />
=== Create an extra command line in Mudlet ===<br />
If your goal is to just have an extra command/input line - say, for role-playing purposes: copy/paste the example below into a new script in Mudletː<br />
<br />
<syntaxhighlight lang="lua"><br />
inputContainer = inputContainer or Adjustable.Container:new({<br />
x = 0, y = "-4c", <br />
name = "InputContainer", padding = 2, <br />
width = "100%", height = "4c", <br />
autoLoad = false<br />
})<br />
<br />
extraCmdLine = extraCmdLine or Geyser.CommandLine:new({<br />
name = "extraCmdLine", <br />
x = 0, y = 0, width = "100%", height = "100%"<br />
}, inputContainer)<br />
<br />
inputContainer:attachToBorder("bottom")<br />
</syntaxhighlight><br />
<br />
This will look likeː <br />
<br />
[[File:AdditionalCommandLine.png|extra command line]]<br />
<br />
== Adjustable.Container ==<br />
{{note}} available in Mudlet 4.8+<br />
<br />
Adjustable Containers are a new "GeyserClass" which act as containers for Geyser elements, but with more flexible and user configurable features. They are referred to as "adjustable" because they can be minimized, loaded, saved, moved, adjusted in size with the mouse pointer, and attached to borders. <br />
<br />
A brief video of [https://www.youtube.com/watch?v=GT2ScizuM48&feature=youtu.be Introduction to Adjustable Containers] is available.<br />
<br />
=== Creating an Adjustable.Container ===<br />
An Adjustable.Container is created just like any other Geyser Object. For example, we might experiment with creating a new Adjustable.Container by running the following line of lua code:<br />
<syntaxhighlight lang="lua"><br />
testCon = testCon or Adjustable.Container:new({name="testContainer"})<br />
</syntaxhighlight><br />
This will create a new Adjustable.Container with the name ''testContainer''. Specifying the adjustable container's name is important for saving. Defining a variable, such as ''testCon'' in our above example, allows functions to be used with the Adjustable.Container.<br />
<br />
Our newly created Adjustable.Container may be used the same way as any other Geyser.Container might. For example, let's put a Geyser.Label in our new testContainer:<br />
<br />
<syntaxhighlight lang="lua"><br />
testCon = testCon or Adjustable.Container:new({name="testContainer"})<br />
testLabel = Geyser.Label:new({name="myTestLabel", x=0, y=0, height="100%", width="100%", color="green"},testCon)<br />
</syntaxhighlight><br />
<br />
The above code creates a new, green-colored Geyser.Label in the ''testCon'' adjustable.container as shown below:<br />
<br />
[[File:GreenLabelinAdjustableContainer.png]]<br />
<br />
You can also create one for miniconsole:<br />
<br />
<syntaxhighlight lang="lua"><br />
miniconsoleContainer = miniconsoleContainer or Adjustable.Container:new({name="miniconsoleContainer"})<br />
myMiniconsole = Geyser.MiniConsole:new({<br />
name="myMiniconsole",<br />
x=0, y=0,<br />
autoWrap = true,<br />
color = "black",<br />
scrollBar = false,<br />
fontSize = 8,<br />
width="100%", height="100%",<br />
}, miniconsoleContainer)<br />
<br />
myMiniconsole:echo("Hello!\n")<br />
</syntaxhighlight><br />
<br />
That will give you:<br />
<br />
[[File:Adjustable container miniconsole.png]]<br />
<br />
=== Key Functions ===<br />
A listing of key functions for the Adjustable.Container module can be found hereː https://www.mudlet.org/geyser/files/geyser/AdjustableContainer.html<br />
<br />
To make the Adjustable Container show on screen use the following:<syntaxhighlight lang="lua"><br />
testCon:show() --will cause the Adjustable Container to show if not showing<br />
</syntaxhighlight><br />
<br />
===<div id="valid constraints"> Valid Constraints</div>===<br />
Adjustable Container constraints and their default values can be found at [https://www.mudlet.org/geyser/files/geyser/AdjustableContainer.html#Adjustable.Container:new].<br />
<br />
These are in addition to the standard Geyser.Container constraints.<br />
<br />
=== Change Title Text ===<br />
To specify the title text of a new container, use the constraint <code>titleText</code> in the constructor (see [[Manual:Geyser#valid constraints|valid constraints]]).<br />
<br />
To change the title text after a container has already been created, use <code>setTitle</code>. Continuing from the previous example, the title for an existing container named "testCon" might be adjusted in a number of ways: <br />
<br />
<syntaxhighlight lang="lua"><br />
testCon:setTitle("Title") -- changes the container's title to "Title"<br />
</syntaxhighlight><br />
<br />
A container's title text defaults to the color green, but this can also be adjusted by using <code>setTitle</code>: <br />
<br />
<syntaxhighlight lang="lua"><br />
testCon:setTitle("Red Title Test","red") -- changes the container's title text to "Red Title Test" and displays the text in the specified color "red".<br />
</syntaxhighlight><br />
<br />
To restore a container's default title text, <code>setTitle</code> is issued without any specified title or color: <br />
<br />
<syntaxhighlight lang="lua"><br />
testCon:setTitle() -- resets the container's title text<br />
</syntaxhighlight><br />
<br />
=== AutoSave and AutoLoad ===<br />
The following Adjustable.Container settings can be saved and loadedː<br />
<br />
<code>x</code>, <code>y</code>, <code>height</code>, <code>width</code>, <code>minimized</code>, <code>locked</code>, <code>lock Style</code>, <code>padding</code>, and <code>hidden</code>.<br />
<br />
These settings will be automatically saved when the Mudlet profile is closed, and automatically loaded when a previous Adjustable.Container is created within the corresponding profile.<br />
<br />
To prevent automatic saving and/or loading of these settings, the <code>autoLoad</code> and <code>autoSave</code> constraints can be included in the constructor. For example, the following code will prevent the settings of the ''testCon2'' Adjustable.Container from being loaded upon creation:<br />
<br />
<syntaxhighlight lang="lua"><br />
testCon2 = testCon2 or Adjustable.Container:new({name="testCon2", autoLoad=false})<br />
</syntaxhighlight><br />
<br />
To also prevent the ''testCon2'' Adjustable.Container from automatically saving its settings when the Mudlet profile is closed, the <code>autoSave=false</code> constraint would be added at creation as follows:<br />
<br />
<syntaxhighlight lang="lua"><br />
testCont2 = testCont2 or Adjustable.Container:new({name="testCont2", autoLoad=false, autoSave=false})<br />
</syntaxhighlight><br />
<br />
Automatic saving can also be deactivated after an Adjustable.Container has been created, by invoking <code>testCont:disableAutoSave()</code><br />
<br />
Note that even with autoSave and autoLoad disabled, it is still possible to save and load manually through the right-click menu and/or by using <code>testCont:save()</code> or <code>testCont:load()</code> in a script.<br />
<br />
To save/load all your containers manually at the same time, we use <code>Adjustable.Container:saveAll()</code> and/or <code>Adjustable.Container:loadAll()</code><br />
<br />
=== "All" Functions ===<br />
The following functions affect all Adjustable Containers at the same time.<br />
<br />
{{note}} You must create the Adjustable Containers before these functions will have an effect.<br />
<br />
<code>Adjustable.Container.loadAll()</code> loads all the settings from your Adjustable Containers at once.<br />
<br />
<code>Adjustable.Container.saveAll()</code> saves all your Adjustable Containers at once.<br />
<br />
<code>Adjustable.Container.loadAll()</code> loads all the settings from your Adjustable Containers at once.<br />
<br />
<code>Adjustable.Container:showAll()</code> shows all your Adjustable Containers at once.<br />
<br />
<code>Adjustable.Container:doAll(myfunc)</code> creates a function that will affect all your Adjustable Containers. For example:<br />
<syntaxhighlight lang="lua"><br />
Adjustable.Container:doAll(function(self) self:hide() end) -- hides all your adjustable containers<br />
</syntaxhighlight><br />
<br />
=== Custom Save/Load Directories and Slots ===<br />
{{note}} available in Mudlet 4.10+<br />
==== Custom Directory ====<br />
If no option set your Adjustable.Container saves/loads its settings in your profile directory.<br />
<br />
It is possible to change the default save/load directory by using for example a different defaultDir as constraint when creating your Adjustable.Container.<br />
<br />
{{note}} This can be especially useful for authors of packages which want to ship their own save files.<br />
<br />
Exampleː<br />
<syntaxhighlight lang="lua"><br />
testCon2 = testCon2 or Adjustable.Container:new({name="testCon2", defaultDir = "/home/edru/MyAdjustableContainerSettings/"}) -- noteː the directory will be created if it doesn't exist<br />
</syntaxhighlight><br />
<br />
Example for save files in a package (assuming the packagename is "AdjustableContainerTest" and the settings are saved in "myPersonalAdjSettings"<br />
<syntaxhighlight lang="lua"><br />
local packageName = "AdjustableContainerTest"<br />
testCon2 = testCon2 or Adjustable.Container:new({name="testCon2", defaultDir = string.format("%s/%s/myPersonalAdjSettings/", getMudletHomeDir(), packageName)})<br />
</syntaxhighlight><br />
<br />
==== Custom Slot ====<br />
Another useful addition is to choose a save slot depending on the situation or to reset to a default save state.<br />
<br />
To save to a different slot just add it as parameter when saving.<br />
<br />
For exampleː<br />
<syntaxhighlight lang="lua"><br />
testCon2ːsave("combatSlot")<br />
</syntaxhighlight><br />
<br />
To then load from that slot just useː<br />
<syntaxhighlight lang="lua"><br />
testCon2ːload("combatSlot")<br />
</syntaxhighlight><br />
<br />
{{note}} This also allows package/module authors to choose a "default" save setting to reset to.<br />
<br />
Exampleː<br />
<syntaxhighlight lang="lua"><br />
Adjustable.ContainerːsaveAll("default") -- saves the default settings<br />
<br />
-- to reset to default settings then just use<br />
Adjustable.ContainerːloadAll("default") -- loads the default settings<br />
</syntaxhighlight><br />
<br />
This can also be used to change the whole GUI on the fly.<br />
<br />
Exampleː<br />
<syntaxhighlight lang="lua"><br />
-- in combat situation use combat settings<br />
Adjustable.ContainerːloadAll("combat") -- loads special combat settings<br />
-- combat is over <br />
Adjustable.ContainerːloadAll("default") --reverts to the default settings<br />
</syntaxhighlight><br />
<br />
==== Delete Save File ====<br />
To delete the save file just useː<br />
<syntaxhighlight lang="lua"><br />
testCont2:deleteSaveFile()<br />
</syntaxhighlight><br />
<br />
===Right-click menu===<br />
Your Adjustable Container has also integrated a right-click menu with the main key functions for easier usability:<br />
<br />
[[File:AdjustableContainerRightClickMenu.png]]<br />
<br />
The right-click menu automatically shows you the possible positions to attach to (top, right, bottom, or left) when it's near one of them. For example, to attach a window to the right of the screen, drag it over to the right - and then the 'Attach to - right' will appear as an option:<br />
<br />
[[File:Adjustable Container - attach to right.png]]<br />
<br />
It also shows the lockstyle selection, which allows you to choose what happens when you press <code>Lock</code>, with 4 lockstyles available by default:<br />
<br />
* standard: this is the default lockstyle, with a small margin on top to keep the right click menu usable.<br />
* light: only hides the min/restore and close labels. Borders and margin are not affected.<br />
* full: the container gets fully locked without any margin left for the right click menu.<br />
* border: keeps the borders of the container visible while locked.<br />
<br />
From Mudlet 4.10+ on it is also possible to change your right-click menu style to dark mode by<br />
<br />
<syntaxhighlight lang="lua"><br />
myAdjustableContainer:changeMenuStyle("dark") -- possible menu styles are "dark" or "light"<br />
</syntaxhighlight><br />
<br />
=== Create a Custom Menu with Custom Items ===<br />
To create a new menu element in your right click menu called "Custom" and add an item to it use:<br />
<syntaxhighlight lang="lua"><br />
testcontainer:newCustomItem(name, func)<br />
-- for example<br />
testcontainer:newCustomItem("Hello world", function(self) echo("Hello world\n") self:flash() end)<br />
-- this will write "Hello world" to the main console and flashes your container.<br />
</syntaxhighlight><br />
<br />
=== Add new LockStyles ===<br />
For more advanced users it's possible to add a new Lockstyles by:<br />
<syntaxhighlight lang="lua"><br />
testcontainer:newLockStyle(name, func)<br />
-- for example<br />
testcontainer:newLockStyle("NewLockStyle", function(self) self.Inside:move(40, 40) self.Inside:resize(-40,-40) self:setTitle("") end)<br />
</syntaxhighlight><br />
<br />
=== Change Adjustable Container Style ===<br />
Additionally to the standard container constraints Adjustable Containers allow you to change at creation: the internal Label style, the menu style, min/close buttons, the menu text, title text... <br />
<br />
( see [[Manual:Geyser#valid constraints|valid constraints]])<br />
An example of a Adjustable Container with different style.<br />
<syntaxhighlight lang="lua"><br />
testCont =<br />
testCont or<br />
Adjustable.Container:new(<br />
{<br />
name = "TestNewStyleContainer",<br />
adjLabelstyle = "background-color:rgba(220,220,220,100%); border: 5px groove grey;",<br />
buttonstyle=[[<br />
QLabel{ border-radius: 7px; background-color: rgba(140,140,140,100%);}<br />
QLabel::hover{ background-color: rgba(160,160,160,50%);}<br />
]],<br />
buttonFontSize = 10,<br />
buttonsize = 20,<br />
titleText = "My new Style",<br />
titleTxtColor = "black",<br />
padding = 15,<br />
}<br />
)<br />
</syntaxhighlight><br />
This code creates a container which looks like this:<br />
<br />
[[File:NewStyleAdjustableContainer.png|Adjustable Container with different style]]<br />
<br />
<br />
=== Attach your Adjustable Container to a Border ===<br />
The simplest way to attach your container to a border is to move your container near the border you want it to attach and use the <br />
right click menu <code> Attach to:</code><br />
<br />
There is also the function <code> TestCont:attachToBorder("right") -- attach TestCont to the right border </code><br />
<br />
To change the margin between container and border use the constraint <code> attachedMargin </code > or the function <code> TestContːsetBorderMargin(10) -- 10 is the margin in px </code><br />
<br />
{{note}} The border is set in percentages and adjusts with screen-size<br />
<br />
=== Create a moveable Border Frame ===<br />
{{note}} available in Mudlet 4.10+<br />
<br />
Adjustable Container can be connected to a border and therefore act like a frame.<br />
<br />
This only works if your container is attached to a specific border and the border to connect to has also at least one container attached to it.<br />
Use the function <code>connectToBorder</code><br />
<br />
<syntaxhighlight lang="lua"><br />
TestCont:connectToBorder("left") -- possible borders are "top", "bottom", "right", "left"<br />
</syntaxhighlight><br />
<br />
Minimizing automatically disconnects from a border. Another way is to use the function <code>disconnect</code>.<br />
<br />
{{note}}Connected container are still resizable even if locked.<br />
<br />
If you like to do everything with your right click menu there is the function<br />
<br />
<syntaxhighlight lang="lua"><br />
TestContːaddConnectMenu()<br />
</syntaxhighlight><br />
If you want to add the connect menu items to all Adjustable Containers just<br />
<syntaxhighlight lang="lua"><br />
Adjustable.Container:doAll(function(self) self:addConnectMenu() end)<br />
</syntaxhighlight><br />
<br />
There is also a brief video of how to [https://www.youtube.com/watch?v=Ex-q5zAEfpc connect your Adjustable Container] available.<br />
<br />
Exampleː<br />
<syntaxhighlight lang="lua"><br />
GUI = GUI or {}<br />
<br />
GUI.top = Adjustable.Container:new({name = "top", y="0%", height = "10%", autoLoad = false})<br />
GUI.bottom = Adjustable.Container:new({name = "bottom", height = "20%", y = "-20%", autoLoad = false})<br />
GUI.right = Adjustable.Container:new({name = "right", y = "0%", height = "100%", x = "-20%", width = "20%", autoLoad = false})<br />
GUI.left = Adjustable.Container:new({name = "left", x = "0%", y = "0%", height = "100%", width = "20%", autoLoad = false})<br />
<br />
<br />
GUI.top:attachToBorder("top")<br />
GUI.bottom:attachToBorder("bottom")<br />
GUI.left:attachToBorder("left")<br />
GUI.right:attachToBorder("right")<br />
<br />
GUI.top:connectToBorder("left")<br />
GUI.top:connectToBorder("right")<br />
GUI.bottom:connectToBorder("left")<br />
GUI.bottom:connectToBorder("right")<br />
</syntaxhighlight><br />
Here's what the frame will look like:<br />
<br />
[[File:Adjustable_frame.gif]]<br />
<br />
==Change Container==<br />
{{note}} available in Mudlet 4.8+<br />
<br />
With this command it is possible to change an elements or even a containers location to that from another container.<br />
For example:<br />
<syntaxhighlight lang="lua"><br />
mycontainerone:changeContainer(mycontainertwo)<br />
--puts container one into container two which means container two will be the parent of container one<br />
</syntaxhighlight><br />
It is also possible to change to a container which is not located on the main window:<br />
<syntaxhighlight lang="lua"><br />
myEmco:changeContainer(emco_userwindow)<br />
--puts my tabbed chat Emco into my userwindow<br />
--to put it back to the main window change to a container located on the main window<br />
myEmco:changeContainer(mymainwindow_container)<br />
--or if it the element wasn't in a container use the main Geyser Root container called Geyser<br />
myEmco:changeContainer(Geyser)<br />
</syntaxhighlight><br />
<br />
==Create Map Window==<br />
{{note}} available in Mudlet 4.8+<br />
<br />
It‘s possible to create the mapper as a map window (similar to clicking the icon) like this:<br />
<syntaxhighlight lang="lua"><br />
myMapWidget = Geyser.Mapper:new({embedded= false})<br />
</syntaxhighlight><br />
<br />
This will open a map window with your saved layout (if there is one, otherwise it will dock at the right corner)<br />
<br />
To choose the position of the DockWindow at creation use: (this will create a map window docked at the left corner)<br />
<br />
<syntaxhighlight lang="lua"><br />
myMapWidget = Geyser.Mapper:new({embedded= false, dockPosition="left"})<br />
</syntaxhighlight><br />
<br />
Possible dockPositions are "left", "right", "top", "bottom", and "floating".<br><br />
To change the dockPosition after creation use:<br />
<br />
<syntaxhighlight lang="lua"><br />
myMapWidget:setDockPosition("floating")<br />
-- this will change myMapWidget dockPosition to floating <br />
</syntaxhighlight><br />
<br />
= Tutorial =<br />
Note: This tutorial assumes you know how scripts in Mudlet work. If not then you should look at the manual first. Also it only shows how Geyser basically works and explains Geysers special windows. It wont go into detail about the windows that where already in Mudlet.<br />
<br />
=== Hello World ===<br />
Let's start with something simple. A Label.<br />
<br />
<syntaxhighlight lang="lua"><br />
Geyser.Label:new({<br />
name="HelloWorld",<br />
x=50, y=50,<br />
width=200, height=50,<br />
})<br />
</syntaxhighlight><br />
<br />
[[Image:Geyser_HW_1.png]]<br />
<br />
This code creates a blank Label with a size of 200x50 at a position of 50 points horizontal and vertical from its parent window - which is the main window since we didn't specify any.<br />
<br />
You can manipulate the Label through the normal functions but Geyser.Label:new() returns an object which can be used to manipulate the label directly. So you should store it:<br />
<br />
<syntaxhighlight lang="lua"><br />
local HelloWorld = Geyser.Label:new({<br />
name="HelloWorld",<br />
x=50, y=50,<br />
width=200, height=50,<br />
})<br />
</syntaxhighlight><br />
<br />
Then you can, for example print a text on it:<br />
<br />
<syntaxhighlight lang="lua"><br />
HelloWorld:echo("Hello World")<br />
</syntaxhighlight><br />
<br />
[[Image:Geyser_HW_2.png]]<br />
<br />
You can put a format parameter so that the text is, for example, centered.<br />
<syntaxhighlight lang="lua"><br />
HelloWorld:echo("Hello World", nil, "c")<br />
</syntaxhighlight><br />
<br />
[[Image:Geyser_HW_3.png]]<br />
<br />
The second parameter is the color. We set it to nil which means the labels foreground color will be used.<br />
<br />
The color parameter either accepts a string ("red"), a hex value("#FF0000" or "0xFF0000" or "|cFF0000"), or a decimal value "&lt;255,0,0&gt;"<br />
<br />
Example:<br />
<syntaxhighlight lang="lua"><br />
HelloWorld:echo("Hello World", "red", "c")<br />
</syntaxhighlight><br />
<br />
[[Image:Geyser_HW_4.png]]<br />
<br />
{{note}} This will automatically set the foreground color, so any echo, without the color parameter set, after that will use the same color.<br />
<br />
You can also set the foreground color with the setFgColor method:<br />
<br />
<syntaxhighlight lang="lua"><br />
HelloWorld:setFgColor("red")<br />
HelloWorld:echo("Hello World", nil, "c")<br />
</syntaxhighlight><br />
<br />
[[Image:Geyser_HW_4.png]]<br />
<br />
=== Containers ===<br />
<br />
Containers are windows that can contain other windows. Actually, since all other Geyser windows subclass container, every window can do that. But containers do not have any visible content by themselves. <br />
<br />
Let's show that by an example:<br />
<syntaxhighlight lang="lua"><br />
local container = Geyser.Container:new({<br />
name="container",<br />
x=50, y=50,<br />
width=250, height=50,<br />
})<br />
</syntaxhighlight><br />
<br />
This will create a container, but if you look at the screen you will see nothing at the positon.<br />
There is a way to make containers visible though:<br />
<syntaxhighlight lang="lua"><br />
container:flash()<br />
</syntaxhighlight><br />
<br />
This will flash the container for a short period of time.<br />
<br />
[[Image:Geyser_Container_1.png]]<br />
<br />
flash() accepts a number as paremeter which defines the time, in seconds, the flash is shown.<br />
<br />
Now, that the container is created, you can add other windows to it. There are 2 ways:<br />
<br />
Directly when creating the window:<br />
<br />
<syntaxhighlight lang="lua"><br />
local container_label = Geyser.Label:new({<br />
name="container_label",<br />
x=0, y=0,<br />
width="100%", height="100%",<br />
},<br />
container)<br />
container_label:echo("This is a label in a container", nil, "c")<br />
</syntaxhighlight><br />
<br />
Later, after the window was created<br />
<syntaxhighlight lang="lua"><br />
local container_label = Geyser.Label:new({<br />
name="container_label",<br />
x=0, y=0,<br />
width="100%", height="100%",<br />
})<br />
container_label:echo("This is a label in a container", nil, "c")<br />
container:add(container_label)<br />
</syntaxhighlight><br />
<br />
Both will lead to the same outcome.<br />
<br />
[[Image:Geyser_Container_2.png]]<br />
<br />
Note that we gave a width and height of "100%" to the constructor of the label. This means that the label will take 100% of the containers width and height. If values are given in percent they will even resize with its parent:<br />
<br />
<syntaxhighlight lang="lua"><br />
container:resize(325, nil)<br />
</syntaxhighlight><br />
<br />
[[Image:Geyser_Container_3.png]]<br />
<br />
The first parameter is the width, the second the height. If the value is nil the current value is used.<br />
<br />
As said in the "Hello World" tutorial the position is relative to its parent window. That's why we could set both x and y to 0 and it is at the position we wanted - the position of the container.<br />
<br />
When we now move the container the label moves with it:<br />
<syntaxhighlight lang="lua"><br />
container:move(400, nil)<br />
</syntaxhighlight><br />
<br />
[[Image:Geyser_Container_4.png]]<br />
<br />
The first parameter is the x-, the second the y-position. If the value is nil the current value is used.<br />
<br />
=== VBox and HBox ===<br />
<br />
The VBox and HBox classes are special Containers.<br />
They will automatically align its containing windows vertically or horizontally, respectively, in the order they where added to them.<br />
<br />
<syntaxhighlight lang="lua"><br />
<br />
local HBox = Geyser.HBox:new({<br />
name="HBox",<br />
x=0, y=0,<br />
width=400, height=30,<br />
})<br />
<br />
</syntaxhighlight><br />
<br />
Like containers you won't see them by themselves.<br />
<br />
Adding children works like with containers<br />
<syntaxhighlight lang="lua"><br />
<br />
local label1 = Geyser.Label:new({<br />
name="Label1",<br />
},<br />
HBox)<br />
label1:echo("Label 1", "black", "c")<br />
label1:setColor(255, 0, 0)<br />
<br />
</syntaxhighlight><br />
<br />
[[Image:HVBox_1.png]]<br />
<br />
We didn't set any position or size, but the label gets the same size as the HBox.<br />
<br />
If we add another window:<br />
<syntaxhighlight lang="lua"><br />
<br />
local label2 = Geyser.Label:new({<br />
name="Label2",<br />
},<br />
HBox)<br />
label2:echo("Label 2", "black", "c")<br />
label2:setColor(0, 255, 0)<br />
<br />
</syntaxhighlight><br />
<br />
[[Image:HVBox_2.png]]<br />
<br />
the size will be divided equally between them!<br />
<br />
What if you want a child that takes more or less space than the others?<br />
That's possible too:<br />
<syntaxhighlight lang="lua"><br />
<br />
local label3 = Geyser.Label:new({<br />
name="Label3",<br />
h_stretch_factor=2.0,<br />
},<br />
HBox)<br />
label3:echo("Label 3", nil, "c")<br />
label3:setColor(0, 0, 255)<br />
<br />
</syntaxhighlight><br />
<br />
[[Image:HVBox_3.png]]<br />
<br />
As you can see, Label 3 takes the same space as Label 1 and 2 Together. <br />
That's because we supplied a horizontal stretch factor with "h_stretch_factor=2.0"<br />
<br />
This works also with a vertical stretch factor, just replace "h_stretch_factor" with "v_stretch_factor"<br />
<br />
Now you may have windows that should not be stretched at all.<br />
To accomplish this you have to set the horizontal and/or vertical policy:<br />
<br />
<syntaxhighlight lang="lua"><br />
<br />
local label4 = Geyser.Label:new({<br />
name="Label4",<br />
width="13%",<br />
h_policy=Geyser.Fixed,<br />
},<br />
HBox)<br />
label4:echo("Label 4", "black", "c")<br />
label4:setColor(0, 255, 255)<br />
<br />
</syntaxhighlight><br />
<br />
[[Image:HVBox_4.png]]<br />
<br />
Possible values for the policies are Geyser.Fixed and Geyser.Dynamic (which is the default). They can also be applied to VBox and HBox in exactly the same way.<br />
<br />
Note that, like in the example above, the label will retain relative values (like percent) if used.<br />
<br />
The VBox works like the HBox, only that the child windows are aligned vertically.<br />
<br />
= Walkthroughs =<br />
Here are a few walkthroughs that will show you how to combine Geyser elements to create some simple GUI widgets.<br />
<br />
===Create a Clickable Compass===<br />
[[File: compass.png]]<br />
The following will walk you through the process of creating your own clickable compass using the Geyser framework.<br />
====Setup the image files====<br />
The compass requires a handful of images to work properly. You can find them here: https://www.dropbox.com/sh/53l7xrn4ds35wnq/WpWOziVKmH <br><br />
Download each image and place it in your profile folder. You can find your profile folder with getMudletHomeDir()<br><br />
If you're using Mudlet 2.1+ you can enter '''lua getMudletHomeDir()''' from the command line to return the profile folder path on your computer.<br />
<br />
====Create a new script====<br />
Script Name: '''''compass.resize'''''<br><br />
Registered Event Handlers: '''''sysWindowResizeEvent'''''<p><br />
Every snippet of code will be placed within this script.<br />
====Store the screen size====<br />
We'll want to store the screen size in some local variables so they can be easily referenced to later on.<br />
<syntaxhighlight lang="lua">local mw, mh = getMainWindowSize()</syntaxhighlight><br />
<br />
====Create a global table or namespace====<br />
Creating a global table will make each of your variables unique. Our namespace will be called '''''compass''''' and everything we make from here on out will be stored within the compass table. We'll also add a few values to it: dirs and ratio. '''''compass.dirs''''' will store each direction while '''''compass.ratio''''' will store the ratio of our screen size so you can 'square up' your compass.<br />
<syntaxhighlight lang="lua">compass = compass or {<br />
dirs = {"nw","n","ne","w","center","e","sw","s","se"},<br />
ratio = mw / mh<br />
}</syntaxhighlight><br />
<br />
====Create the parent label====<br />
[[File: grey.png|thumbnail]]<br />
The 'parent label' refers to the label on the bottom layer. The entire compass will be created within this label. It's container is '''main''' for it's parent is the main window.<br />
<syntaxhighlight lang="lua">compass.back = Geyser.Label:new({<br />
name = "compass.back",<br />
x = "25%",<br />
y = "25%",<br />
width = "10%",<br />
height = "10%",<br />
},main)</syntaxhighlight><br />
<br />
====Set the parent label stylesheet====<br />
[[File: blue.png|thumbnail]]<br />
This will create the blue sphere that makes up most of the compass. The background color is a radial gradient that goes from a deep blue to a brighter shade. The border radius rounds the edges. When the radius is exactly half of the label width it forms a circle. The arrows of the compass actually protrude from the sphere so we give it a margin to suck it in a bit for this effect.<br />
<syntaxhighlight lang="lua">compass.back:setStyleSheet([[<br />
background-color: QRadialGradient(cx:.3,cy:1,radius:1,stop:0 rgb(0,0,50),stop:.5 rgb(0,0,100),stop:1 rgb(0,0,255));<br />
border-radius: ]]..tostring(compass.back:get_width()/2-14)..[[px;<br />
margin: 10px;<br />
]])</syntaxhighlight><br />
<br />
====Create a 3x3 grid====<br />
The compass is split into 9 sections. One for each cardinal direction plus an extra space that sits in the center. This 3x3 grid is created by 3 VBoxes that sit within a single HBox (or vice versa but I flipped a coin and this is what it gave me).<br><br />
So first off, we create the HBox. It will be the same size as its parent, ''compass.back''.<br />
<syntaxhighlight lang="lua"> compass.box = Geyser.HBox:new({<br />
name = "compass.box",<br />
x = 0,<br />
y = 0,<br />
width = "100%",<br />
height = "100%",<br />
},compass.back)</syntaxhighlight><br />
Next, we create our 3 VBoxes. You don't need to specify position or size because these are placed within ''compass.box'', an HBox.<br />
<syntaxhighlight lang="lua"> compass.row1 = Geyser.VBox:new({<br />
name = "compass.row1",<br />
},compass.box)<br />
compass.row2 = Geyser.VBox:new({<br />
name = "compass.row2",<br />
},compass.box)<br />
compass.row3 = Geyser.VBox:new({<br />
name = "compass.row3",<br />
},compass.box)</syntaxhighlight><br />
Finally, we add our 9 labels. Take note that they are split up into even groups of 3. Each group is placed into a different ''compass.row#''<br />
<syntaxhighlight lang="lua"> compass.nw = Geyser.Label:new({<br />
name = "compass.nw",<br />
},compass.row1)<br />
<br />
compass.w = Geyser.Label:new({<br />
name = "compass.w",<br />
},compass.row1)<br />
<br />
compass.sw = Geyser.Label:new({<br />
name = "compass.sw",<br />
},compass.row1)<br />
<br />
compass.n = Geyser.Label:new({<br />
name = "compass.n",<br />
},compass.row2)<br />
<br />
compass.center = Geyser.Label:new({<br />
name = "compass.center",<br />
},compass.row2)<br />
<br />
compass.s = Geyser.Label:new({<br />
name = "compass.s",<br />
},compass.row2)<br />
<br />
compass.ne = Geyser.Label:new({<br />
name = "compass.ne",<br />
},compass.row3)<br />
<br />
compass.e = Geyser.Label:new({<br />
name = "compass.e",<br />
},compass.row3)<br />
<br />
compass.se = Geyser.Label:new({<br />
name = "compass.se",<br />
},compass.row3)</syntaxhighlight><br />
====Create a callback function====<br />
We'll want our compass to head in the direction of the arrow we're clicking. This is where we specify so. When the arrow is clicked, this function will be ran with the arrow direction as the argument.<br />
<syntaxhighlight lang="lua">function compass.click(name)<br />
send(name)<br />
end</syntaxhighlight><br />
====Create the hover functions====<br />
We want our arrows to turn yellow when we hover over them. We do so by simply resetting the label's stylesheet and changing the border image. Don't forget to include the margin as we still want that.<br />
<syntaxhighlight lang="lua">function compass.onEnter(name)<br />
compass[name]:setStyleSheet([[<br />
border-image: url("]]..getMudletHomeDir()..[[/]]..name..[[hover.png");<br />
margin: 5px;<br />
]])<br />
end<br />
<br />
function compass.onLeave(name)<br />
compass[name]:setStyleSheet([[<br />
border-image: url("]]..getMudletHomeDir()..[[/]]..name..[[.png");<br />
margin: 5px;<br />
]])<br />
end</syntaxhighlight><br />
====Set the stylesheets in the grid====<br />
[[File: Sample.png|thumb]]<br />
Each of the 9 labels need an image of an arrow. Rather than setting each individually, we'll iterate over the ''compass.dirs'' table we made awhile back and add the respective image to each. The names of images are a reflection of the ''compass.dirs'' table. This keeps it consistent and easy to refer to. During the iteration, the callback, setLabelOnEnter and setLabelOnLeave are also set for each label.<br />
<syntaxhighlight lang="lua">for k,v in pairs(compass.dirs) do<br />
compass[v]:setStyleSheet([[<br />
border-image: url("]]..getMudletHomeDir()..[[/]]..v..[[.png");<br />
margin: 5px;<br />
]])<br />
compass[v]:setClickCallback("compass.click",v)<br />
setLabelOnEnter("compass."..v,"compass.onEnter",v)<br />
setLabelOnLeave("compass."..v,"compass.onLeave",v)<br />
end</syntaxhighlight><br />
<br />
====Resize the compass into a square====<br />
[[File: final.png|thumb]]<br />
Most screen size ratios aren't a perfect 1:1. This will cause a 10% x 10% label to be far from square. By setting our height (the smaller of the two numbers) to our width, we can resize our compass to a near perfect square. This function is also the name of our script because we want it to run each time sysWindowResizeEvent is raised.<br />
<syntaxhighlight lang="lua">function compass.resize()<br />
compass.back:resize(compass.back.width, compass.back:get_width())<br />
end<br />
<br />
compass.resize()</syntaxhighlight><br />
<br />
===Create a Tabbed Window===<br />
[[File: tabwindow.png]]<br />
The following will walk you through the process of creating your own tabbed window using the Geyser framework.<br />
<br />
====Create a new script====<br />
Script Name: '''''Tabbed Window'''''<br><br />
Every snippet of code will be placed within this script.<br />
====Create a global table====<br />
Creating a global table will make each of your variables unique. Our namespace will be called '''''menu''''' and everything we make from here on out will be stored within the menu table. We'll also add a few values to it: tabs, color1, color2, width, height and current. <br><br />
''''tabs'''' will be a table that stores all our tab names. If we want our tabs to have different names, we alter this table.<br><br />
''''color1'''' and ''''color2'''' will store the colors of our tabbed window. If we want to change the color of our tabbed window, we alter these values.<br><br />
''''width'''' and ''''height'''' will store the size of our tabbed window. If we want to change the size of the tabbed window, we alter these values.<br><br />
''''current'''' keeps track of which tab is selected. We will set this to the first tab in the table by default. We do this outside the initial table creation so we can easily access menu.tabs<br><br />
<syntaxhighlight lang="lua">menu = menu or {<br />
tabs = {"Tab1","Tab2","Tab3","Tab4"},<br />
color1 = "rgb(0,0,70)",<br />
color2 = "rgb(0,0,50)",<br />
width = "20%",<br />
height = "40%",<br />
}<br />
menu.current = menu.current or menu.tabs[1]</syntaxhighlight><br />
<br />
====Create the main container====<br />
Our tabbed window will need a container. This will be the bottom layer. Containers are invisible so no need to set a stylesheet.<br />
<syntaxhighlight lang="lua">menu.container = Geyser.Container:new({<br />
name = "menu.back",<br />
x = "50%", y = "25%",<br />
width = menu.width,<br />
height = menu.height,<br />
},main)</syntaxhighlight><br />
====Create an HBox====<br />
All of our tabs will be evenly spaced. So we'll create an HBox to sit at the top of our container.<br />
<syntaxhighlight lang="lua">menu.header = Geyser.HBox:new({<br />
name = "menu.header",<br />
x = 0, y = 0,<br />
width = "100%",<br />
height = "10%",<br />
},menu.container)</syntaxhighlight><br />
====Create a label====<br />
This label will serve as a container for each window. It sits right underneath the HBox we just created for the tabs.<br />
<syntaxhighlight lang="lua">menu.footer = Geyser.Label:new({<br />
name = "menu.footer",<br />
x = 0, y = "10%",<br />
width = "100%",<br />
height = "90%",<br />
},menu.container)</syntaxhighlight><br />
We don't want this to be a big grey box at startup, so we'll set the stylesheet to appear like the rest of the windows.<br />
<syntaxhighlight lang="lua"><br />
menu.footer:setStyleSheet([[<br />
background-color: ]]..menu.color1..[[;<br />
border-bottom-left-radius: 10px;<br />
border-bottom-right-radius: 10px;<br />
]])</syntaxhighlight><br />
Each window actually has two labels. One for the light blue background, and another for the dark blue center. This will create that dark blue center.<br />
<syntaxhighlight lang="lua">menu.center = Geyser.Label:new({<br />
name = "menu.center",<br />
x = 0, y = 0,<br />
width = "100%",<br />
height = "100%",<br />
},menu.footer)<br />
menu.center:setStyleSheet([[<br />
background-color: ]]..menu.color2..[[;<br />
border-radius: 10px;<br />
margin: 5px;<br />
]])</syntaxhighlight><br />
====Add your tabs and their windows====<br />
Now we'll want to add our tabs and windows. We do this in a single for loop of the ''''menu.tabs'''' table since it holds all our tab names.<br />
<syntaxhighlight lang="lua">for k,v in pairs(menu.tabs) do<br />
</syntaxhighlight><br />
This will create the tabs. Each tab will be named: menu.<tabname>tab<br />
<syntaxhighlight lang="lua"><br />
menu[v.."tab"] = Geyser.Label:new({<br />
name = "menu."..v.."tab",<br />
},menu.header)<br />
</syntaxhighlight><br />
Here is where we set the tab stylesheet. Each tab has a rounded top, so we set the border-radius of the top-left and top-right to 10px. Each tab has a small space for separation so we give the right and left sides a tiny margin of 1px.<br />
<syntaxhighlight lang="lua"><br />
menu[v.."tab"]:setStyleSheet([[<br />
background-color: ]]..menu.color1..[[;<br />
border-top-left-radius: 10px;<br />
border-top-right-radius: 10px;<br />
margin-right: 1px;<br />
margin-left: 1px;<br />
]])<br />
</syntaxhighlight><br />
This will display the name of each tab on the tab.<br />
<syntaxhighlight lang="lua"><br />
menu[v.."tab"]:echo("<center>"..v)<br />
</syntaxhighlight><br />
We need our tabs to do stuff when clicked, so we'll assign it a callback function, '''''menu.click''''', which we'll create later on. Our tab name is the argument.<br />
<syntaxhighlight lang="lua"><br />
menu[v.."tab"]:setClickCallback("menu.click",v)<br />
</syntaxhighlight><br />
Now we create the windows that appear when each tab is clicked. Each window has two labels, one atop the other. The first, which we'll create here, has rounded edges on its bottom.<br />
<syntaxhighlight lang="lua"><br />
menu[v] = Geyser.Label:new({<br />
name = "menu."..v,<br />
x = 0, y = 0,<br />
width = "100%",<br />
height = "100%",<br />
},menu.footer)<br />
<br />
menu[v]:setStyleSheet([[<br />
background-color: ]]..menu.color1..[[;<br />
border-bottom-left-radius: 10px;<br />
border-bottom-right-radius: 10px;<br />
]])<br />
</syntaxhighlight><br />
The second label serves as the window's center and has rounded edges on all sides. And a margin of 5px from it's parent, the label we just created. When adding stuff to your windows, this is the label you'll want to use. '''''menu.<tabname>center'''''<br />
<syntaxhighlight lang="lua"><br />
menu[v.."center"] = Geyser.Label:new({<br />
name = "menu."..v.."center",<br />
x = 0, y = 0,<br />
width = "100%",<br />
height = "100%",<br />
},menu[v])<br />
</syntaxhighlight><syntaxhighlight lang="lua"><br />
menu[v.."center"]:setStyleSheet([[<br />
background-color: ]]..menu.color2..[[;<br />
border-radius: 10px;<br />
margin: 5px;<br />
]])<br />
</syntaxhighlight><br />
Finally, we hide all the windows and end the for loop.<br />
<syntaxhighlight lang="lua"><br />
menu[v]:hide()<br />
end</syntaxhighlight><br />
====Create a callback function====<br />
The last step is to create our callback function for when a tab is clicked. This will hide that tab that is stored in '''''menu.current''''', set menu.current to the clicked tab, and then show the menu.current tab.<br />
<syntaxhighlight lang="lua">function menu.click(tab)<br />
menu[menu.current]:hide()<br />
menu.current = tab<br />
menu[menu.current]:show()<br />
end</syntaxhighlight><br />
====Adding content to your windows====<br />
Add content to '''menu.<tab name>center'''<br />
So if we wanted to display our gold in a window we could:<syntaxhighlight lang="lua">menu.Tab1center:echo(myGold)</syntaxhighlight><br />
If we wanted to add a map to a window we could:<br />
<syntaxhighlight lang="lua">myMap = Geyser.Mapper:new({<br />
name = "myMap",<br />
x = 0, y = 0,<br />
width = "100%",<br />
height = "100%",<br />
},menu.Tab2center)</syntaxhighlight><br />
<br />
===Create a Window with a resize label===<br />
<br />
Previous tutorial is now done much simpler [[Manual:Geyser#Adjustable.Container|Adjustable containers]], have a look at those instead.<br />
<br />
[[Category:Mudlet Manual]]</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:Geyser&diff=19862Manual:Geyser2022-02-05T01:08:29Z<p>Demonnic: Add Geyser.StyleSheet</p>
<hr />
<div>{{TOC right}}<br />
<br />
= Introduction =<br />
<br />
The Geyser Layout Manager is an object oriented framework for creating, updating and organizing GUI elements within Mudlet - it allows you to make your UI easier on Mudlet, and makes it easier for the UI to be compatible with different screen sizes.<br />
<br />
=== Motivation ===<br />
<br />
Mudlet makes the creation of label, miniconsoles and gauges a quick and easy thing. Mudlet provides a nice signal when window resize events happen. To help with complex window management, Geyser steps in.<br />
<br />
=== Main Geyser Features ===<br />
<br />
Geyser is based on traditional GUI concepts and should feel similar to using Java's Swing. The biggest difference is in how positions are specified.<br />
<br />
* All window positions are specified relative to their container - nothing new there. However, window positions can also take on percentages and negative pixel and character values. For instance, a window could be constrained to have a height of 50% of its container and a width such that the window's right edge is always 20 characters from its container's right edge. See examples below and the demos/tests that come with Geyser.<br />
* All windows under Geyser control are automatically resized as necessary when the main Mudlet window is resized. Once you create a window and assign it to a container, you never have to worry about positioning it again. Nonetheless, it's very easy to shift the container that a window is in, maintaining its constraints so that it resizes as needed according to the dimensions of the new container.<br />
* Due to the container hierarchy, hiding a container window automatically hides all its contained windows too. The same for show. With clever construction and labels with callbacks, this lets one make complex GUI elements that are minimizable or maximizable or ...<br />
* However, there is always some overhead for automation systems and Geyser is no exception. Fortunately, most of the overhead is during window creation and resize events - not things that happen frequently.<br />
<br />
=== Getting pictures for your stuff ===<br />
You can find good, freely-available assets for your UI here:<br />
* [https://kenney.nl/assets?q=2d kenney.nl]<br />
* [https://opengameart.org/ opengameart.org]<br />
* [https://game-icons.net/ game-icons.net]<br />
<br />
=== Constraints format ===<br />
<br />
Geyser position constraints are a string composed of a number and a format type. For example, "10px" means 10 pixels, either pixels from the origin (e.g. x or y) or a value for the width or height. A negative number indicates distance from a container's right or bottom border depending on whether is a constraint for x/width or y/height, respectively. Percentages for width and height are in terms of the container's dimensions and negative values are converted to the equivalent positive value. A 100% width subwindow with an x-coordinate of 10 will have part of itself displayed outside the confines of its container. There is no hard limit on maximum window size, just as with regular Mudlet windows. If a number, n, is passed as a constraint instead of a string, it is assumed to be equivalent to "npx". Any Lua table that contains entries for x, y, width and height in the proper format can be used for Geyser constructors and setting constraints. Just like in Mudlet, 0,0 coordinates mean the top-left corner.<br />
<br />
The following is a valid example for coordinates of a Geyser object:<br />
<br />
<syntaxhighlight lang="lua"><br />
{x = "20px", y = "-10c", width = "40%", height = 30}<br />
</syntaxhighlight><br />
<br />
=== Math in Geyser ===<br />
You can also use math in your Geyser constraints just to line things up just right! Want to have a label occupy full height but not the first 30 pixels? You can:<br />
<br />
<syntaxhighlight lang="lua"><br />
footer = Geyser.Label:new({<br />
name = "footer",<br />
x = 0, y = 30,<br />
width = "100%-30px",<br />
}, main_window)<br />
</syntaxhighlight><br />
<br />
= Geyser elements =<br />
The purpose of this document is to go through every Geyser element and provide practical examples on how they are used. Read it from top to bottom, preferably doing all of the examples to understand how they work!<br />
<br />
See also: https://www.mudlet.org/geyser/files/index.html for a brief and technical overview of all elements and their functions.<br />
<br />
==[http://www.mudlet.org/geyser/files/geyser/GeyserContainer.html Geyser.Container]==<br />
An invisible, organizing object in Geyser - use it to divide your screen and position elements accordingly. '''[http://www.mudlet.org/geyser/files/geyser/GeyserContainer.html See here]''' for all of the functions that are available to you to use.<br />
<br />
A container is also the base class - which means that everything (labels, miniconsoles and gauges) can use its functions, since everything else is at heart a container.<br />
<br />
=== Creating a container ===<br />
To get started with a container, here's an example that'll create a 200px border on the left side of Mudlet for you, and make a container cover all of it - so you can place other visual elements inside it:<br />
<br />
<syntaxhighlight lang="lua"><br />
setBorderLeft(200)<br />
left_container = Geyser.Container:new({<br />
name = "left_container", -- give it a unique name here<br />
x=0, y=0, -- have it start at the top-left corner of mudlet<br />
width = 200, height="100%", -- with a width of 200, and a height of the full screen, hence 100%<br />
})<br />
</syntaxhighlight><br />
<br />
Right away, you'll see space appear on the left side. It'll be black, as the container is an invisible unit by itself. You can make sure it's there by making it flash by doing this from the input line:<br />
<br />
<syntaxhighlight lang="lua">lua left_container:flash()</syntaxhighlight><br />
<br />
The command will cause your container to flash for a moment for you, revealing itself.<br />
<br />
{{Note}} If you hide a container and create new Geyser elements within it, they'll be shown automatically for you.<br />
<br />
=== Container within a container ===<br />
You can place containers within other containers by specifying which "parent" the new container should have when you create one. Given our [[#Creating a container|previous example]], you can split the left side into two halves like this:<br />
<br />
<syntaxhighlight lang="lua"><br />
left_container_top = Geyser.Container:new({<br />
name = "left_container_top",<br />
x=0, y=0, -- this container occupies the top, so it starts top-left as well<br />
width = "100%", height="50%", -- but only uses up half of the height<br />
}, left_container) -- this is the important bit - it says that left_container_top should be inside left_container<br />
<br />
left_container_bottom = Geyser.Container:new({<br />
name = "left_container_bottom",<br />
x=0, y="50%", -- this container starts halfway down the first one<br />
width = "100%", height="50%", -- and has the same half height of the original container<br />
}, left_container) <br />
</syntaxhighlight><br />
<br />
=== Aligning relative to bottom or right sides ===<br />
The aligning point within Mudlet is the top-left corner, and it's the same for the elements they are aligned - the position you specify is used by the top-left corner of the element.<br />
<br />
Using Geyser, you can align to the opposite side as well, using the coordinates in negatives, while keeping the dimensions of the object in mind. For example, if you want to align a box that's 20px wide on the usual left side, you'd give it a width of 20 and an x value of 0. If you'd like to align it on the right side, then you'd give it an x value of -20. The box will spawn 20px away from the right side and "grow" to the right by 20px.<br />
<br />
<syntaxhighlight lang="lua"><br />
right_container = Geyser.Container:new({<br />
name = "right_container",<br />
x="-20%", y=0, -- makes the container start 20% of the screen away from the right side<br />
width = "20%", height="50%", -- filling it up until the end<br />
}) <br />
</syntaxhighlight><br />
<br />
Do make sure to account for the scrollbar, as Mudlet UI elements can overlap it. You can also move the scrollbar with [[Manual:UI_Functions#setBorderRight|setBorderRight()]].<br />
<br />
==[http://www.mudlet.org/geyser/files/geyser/GeyserLabel.html Geyser.Label]==<br />
Labels allow you to use pictures in your interface, as well as nicely-formatted text - see docs for label [http://www.mudlet.org/geyser/files/geyser/GeyserLabel.html functions].<br />
<br />
=== Basic label ===<br />
<br />
Here's an example to get you started with:<br />
<br />
<syntaxhighlight lang="lua"><br />
testlabel = Geyser.Label:new({<br />
name = "testlabel",<br />
x = "50%", y = 0,<br />
width = "50%", height = "100%",<br />
fgColor = "black",<br />
color = "SeaGreen",<br />
message = [[<center>heey</center>]]<br />
})<br />
</syntaxhighlight><br />
<br />
This labels '''x''' coordinate is specified as 50% - and because it's not attached to any container, this implies that the window will start halfway at the main window. You can tell it's not attached to a container because there's nothing in between the last ''}'' and '')'', the place where the container goes.<br />
<br />
The '''y''' coordinate is 0 - which means that the label will start at the top of the screen. With the width being 50%, the label will occupy 50% of the screen - and since it starts at the halfway point, it means it'll occupy the entire right side. A height of 100% means that it'll stretch from the top to the full bottom.<br />
<br />
Here's what that'll look like:<br />
<br />
[[File:Simple-label.png|center|600px]]<br />
<br />
<br />
Playing around with the starting location and dimensions, we can also place it in the center of the screen with:<br />
<br />
<syntaxhighlight lang="lua"><br />
testlabel = Geyser.Label:new({<br />
name = "testlabel",<br />
x = "25%", y = "25%",<br />
width = "50%", height = "50%",<br />
fgColor = "black",<br />
message = [[<center>heey</center>]]<br />
})<br />
testlabel:setColor(0,255,0,150)<br />
</syntaxhighlight><br />
<br />
[[File:Simple_label_centered.png|center|600px]]<br />
<br />
To change the message on a label, you can use the ''mylabel:echo()'' function, where ''mylabel'' is the name of the label you gave it:<br />
<br />
<syntaxhighlight lang="lua"><br />
mylabel:echo("hello!")<br />
</syntaxhighlight><br />
<br />
To get rid of the label, use the '':hide()'' function:<br />
<br />
<syntaxhighlight lang="lua"><br />
mylabel:hide()<br />
</syntaxhighlight><br />
<br />
=== Coloring text ===<br />
<syntaxhighlight lang="lua"><br />
testlabel = Geyser.Label:new({<br />
name = "testlabel",<br />
x = "50%", y = 0,<br />
width = "50%", height = "100%",<br />
fgColor = "black", -- default text colour<br />
color = "SeaGreen" -- default label background<br />
})<br />
<br />
-- You can also change colour of text on demand with:<br />
testlabel:echo[[<p style="color:blue;">You can change the text color of a whole sentence or paragraph...</p><p>...or you can change the text color of one <span style="color:green;">word</span> or even a single l<span style="color:red;">e</span>tter.</p>]]<br />
</syntaxhighlight><br />
<br />
=== Setting the font size ===<br />
<br />
To set a different font size for your Label, use the ''setFontSize()'' method. For example:<br />
<br />
<syntaxhighlight lang="lua"><br />
testlabel:setFontSize(14)<br />
</syntaxhighlight><br />
<br />
The font size is set in Pt, so anything above 30 will likely be too large to be useful.<br />
<br />
=== Label inside a container ===<br />
<br />
Once you've got your containers and mastered the basic labels, you can drop labels into your nicely-organized containers. Doing so is similar to nesting containers:<br />
<br />
<syntaxhighlight lang="lua"><br />
testlabel = Geyser.Label:new({<br />
name = "testlabel",<br />
x = "25%", y = "25%",<br />
width = "50%", height = "50%",<br />
fgColor = "black",<br />
message = [[<center>heey</center>]]<br />
}, left_container_bottom) -- this is where we tell it what container to go into<br />
testlabel:setColor(0,255,0,150)<br />
</syntaxhighlight><br />
<br />
That label is exactly the same as the one above that goes across the screen, except it's in our bottom-left container - so it looks appropriately different:<br />
<br />
[[File:Label in a container.png|center]]<br />
<br />
=== Image on a label ===<br />
One of the more amazing things labels allow you to do is put pictures anywhere on your Mudlet screen, that blend in very well. To do so, once the label is created, use the [http://www.mudlet.org/geyser/files/geyser/GeyserLabel.html#Geyser.Label:setBackgroundImage setBackgroundImage()] function with the exact path to the image ([[File:Skullface.png]]):<br />
<br />
<syntaxhighlight lang="lua"><br />
picture_label = Geyser.Label:new({<br />
name = "picture_label",<br />
x = 0, y = "-14px",<br />
width = "16px", height = "14px",<br />
})<br />
picture_label:setBackgroundImage([[/home/vadi/Desktop/skullface.png]]) -- update location to actual image location on your computer<br />
</syntaxhighlight><br />
<br />
This'll plop the picture to the bottom-left of your screen. To make the picture show, download the skullface picture above - save it to your desktop, and adjust the location of the image within [[]]'s to what it is on your computer. For example, if you saved this on your Windows 7 desktop, it would be:<br />
<br />
<syntaxhighlight lang="lua"><br />
picture_label:setBackgroundImage([[C:/Users/<your user name>/Desktop/skullface.png]])<br />
</syntaxhighlight><br />
<br />
(yes, that's / and not \ - \ has been known not to work)<br />
<br />
If you saved this on your Mac desktop, it would be:<br />
<br />
<syntaxhighlight lang="lua"><br />
picture_label:setBackgroundImage([[/Users/<your user name>/Desktop/skullface.png]])<br />
</syntaxhighlight><br />
<br />
If you saved this on your Ubuntu desktop, it would be:<br />
<br />
<syntaxhighlight lang="lua"><br />
picture_label:setBackgroundImage([[/home/<your user name>/Desktop/skullface.png]])<br />
</syntaxhighlight><br />
<br />
Using this basic building block, you can work up to making yourself a UI!<br />
<br />
=== Stretching an image on a label ===<br />
If you'd like your image not to keep its original size, but instead use up the available space of the label - you can use the [http://doc.qt.io/qt-5/stylesheet-reference.html#border-image border-image] stylesheet property to do so.<br />
<br />
<syntaxhighlight lang="lua"><br />
label = Geyser.Label:new({<br />
name = "label",<br />
x = "50%", y = "50%",<br />
width = "50%", height = "50%",<br />
})<br />
<br />
-- change the location to your picture<br />
-- on windows, use / to separate folders still, not \<br />
label:setStyleSheet[[<br />
border-image: url(/home/vadi/Desktop/iso-avatar-draft_0.png);<br />
]]<br />
</syntaxhighlight><br />
<br />
{{note}} If you're on a Mudlet earlier than 3.15 and are having difficulty with the image coming up, it may be because of strange differences between Qt's CSS engine which does not affect mudlet's Lua. You may want to try appending :gsub("\\","/") to your string including getMudletHomeDir() (e.g. <code>getMudletHomeDir():gsub("\\","/")</code>). No longer necessary after Mudlet 3.15.<br />
<br />
=== Aligning an image within a label ===<br />
You can use background-image in combination with background-position to align an image within a label (if, say, the image is much smaller than the label).<br />
<br />
<syntaxhighlight lang="lua"><br />
-- this will set and align an image top-right of the label<br />
if stunning then<br />
mylabel:setStyleSheet([[<br />
background-image: url("/home/vadi/Games/Mudlet/Offensive/Artwork/dialog-ok.png");<br />
background-repeat: no-repeat; background-position: top right; background-origin: margin;<br />
]])<br />
else<br />
mylabel:setStyleSheet([[<br />
background-image: url("/home/vadi/Games/Mudlet/Offensive/Artwork/dialog-no.png");<br />
background-repeat: no-repeat; background-position: top right; background-origin: margin;<br />
]])<br />
end<br />
</syntaxhighlight><br />
<br />
=== Showing / hiding a label ===<br />
You can show and hide labels, as you can any container, miniconsole or a gauge in Geyser with [http://www.mudlet.org/geyser/files/geyser/GeyserContainer.html#Geyser.Container:show Geyser.Container:show()] and [http://www.mudlet.org/geyser/files/geyser/GeyserContainer.html#Geyser.Container:hide Geyser.Container:hide()]. Remember that since labels are a type of a container, all container functions work on them.<br />
<br />
Hiding a label will allow you to click through on what is below the label, as well as free up the visual space for something else.<br />
<br />
<syntaxhighlight lang="lua"><br />
testlabel = Geyser.Label:new({<br />
name = "testlabel",<br />
x = "50%", y = 0,<br />
width = "50%", height = "100%",<br />
fgColor = "black",<br />
color = "SeaGreen",<br />
message = [[<center>heey</center>]]<br />
})<br />
<br />
-- hide the label with:<br />
testlabel:hide()<br />
<br />
-- show the label with:<br />
testlabel:show()<br />
</syntaxhighlight><br />
<br />
=== Clickable images ===<br />
Tacking onto the fact that you can plop images anywhere on your Mudlet screen now, you can also make them react to your clicks. You can do so with the [http://www.mudlet.org/geyser/files/geyser/GeyserLabel.html#Geyser.Label:setClickCallback setClickCallback()] function - by giving it a function to call when your label is clicked, you'll make it react.<br />
<br />
<syntaxhighlight lang="lua"><br />
picture_label = Geyser.Label:new({<br />
name = "picture_label",<br />
x = "-215px", y = "0px",<br />
width = "200px", height = "200px",<br />
})<br />
picture_label:setBackgroundImage([[/home/vadi/Desktop/qubodup-opengameart-cc0-200px-missile_icon.png]]) -- update location to actual image location on your computer<br />
picture_label:setClickCallback("on_bomb_press")<br />
<br />
function on_bomb_press()<br />
send("say BOOM!")<br />
end<br />
</syntaxhighlight><br />
<br />
That's it! Pressing on the image will make the ''on_bomb_press()'' function go off, which will do its code of ''send("say BOOM!")''. Download the picture for use [http://opengameart.org/content/missile-rts-icon here].<br />
<br />
[[File:Clickable_image.png|500px|center]]<br />
<br />
=== Styling labels ===<br />
Besides putting text or images on labels, you can also style them using Qt's stylesheets feature. Doing so allows you to create various graphics that make the label look more appealing:<br />
<br />
[[File:Label_styling_examples.png|center]]<br />
<br />
To set a stylesheet on a label, use the [http://www.mudlet.org/geyser/files/geyser/GeyserLabel.html#Geyser.Label:setStyleSheet Geyser.Label:setStyleSheet()] function on your label, describing the stylesheet you'd like to give it. A stylesheet consists of properties you set - for example the background color, borders, padding, and so forth. You describe properties in the following format: ''property name''''':'''''values''''';'''. See here for a [http://doc.qt.io/qt-5/stylesheet-reference.html#list-of-properties list of all supported properties]. For example, to make your labels background be yellow, you'd use the background-color property:<br />
<br />
<syntaxhighlight lang="lua"><br />
mylabel = Geyser.Label:new({<br />
name = "mylabel",<br />
x = "50%", y = "50%",<br />
width = 200, height = 100<br />
})<br />
<br />
mylabel:setStyleSheet([[<br />
background-color: yellow;<br />
]])<br />
</syntaxhighlight><br />
<br />
[[File:Basic_stylesheet.png|center]]<br />
<br />
Which is nice, but not particularly impressive.<br />
<br />
Scrolling down the list of properties, you'll come along a border one. Plopping it into our stylesheet nets the following:<br />
<br />
<syntaxhighlight lang="lua"><br />
mylabel:setStyleSheet([[<br />
background-color: yellow;<br />
border: 5px solid white;<br />
]])<br />
</syntaxhighlight><br />
<br />
[[File:Basic_stylesheet_border.png|center]]<br />
<br />
Which gives a border!<br />
<br />
Fiddling with it some more and applying new properties we find on that page, we get a rounded border on our label:<br />
<br />
<syntaxhighlight lang="lua"><br />
mylabel:setStyleSheet([[<br />
background-color: grey;<br />
border-width: 15px;<br />
border-style: solid;<br />
border-color: green;<br />
border-radius: 10px;<br />
]])<br />
</syntaxhighlight><br />
<br />
[[File:Basic_stylesheet_border_radius.png|center]]<br />
<br />
Which'll conclude our exploration for now. Try out all of the other possible options available there - there's loads, from [http://doc.qt.io/qt-5/stylesheet-reference.html#border-style funky borders], to tiling images and fancy color combinations using gradients.<br />
<br />
=== Adding a tooltip to a label ===<br />
<br />
Since Mudlet 4.6, you can now add a tooltip to labels and gauges. You can start by making a simple label and echoing some text to it:<br />
<br />
<syntaxhighlight lang="lua"><br />
testLabel = Geyser.Label:new({<br />
name = "testLabel",<br />
x = "50%",<br />
y = "50%",<br />
height = "25%",<br />
width = "25%",<br />
})<br />
testLabel:echo("This is on the label!")<br />
testLabel:setAlignment("center")<br />
-- sets the tooltip text<br />
testLabel:setToolTip("This is the tooltip", "10")<br />
<br />
<br />
-- optionally - you can customise the tooltip, too!<br />
testLabel:setStyleSheet("QToolTip{background: yellow; color: blue; border:none;}")<br />
</syntaxhighlight><br />
<br />
Without tooltip<br />
[[File:TestLabelForTooltips.png|thumb|center]]<br />
<br />
With tooltip<br />
<br />
[[File:LabelTooltip.png|thumb|center]]<br />
<br />
=== Avoid stylesheet inheritance by tooltip ===<br />
<br />
{{note}} If you set a new stylesheet for a label and with that a background image it is possible that through inheritance the tooltip also has this stylesheet image.<br />
<br />
To avoid this specify that the stylesheet is meant for the Label by using QLabel{...} in your Label stylesheet for exampleː<br />
<syntaxhighlight lang="lua"><br />
label = Geyser.Label:new({<br />
name = "label",<br />
x = "50%", y = "50%",<br />
width = "50%", height = "50%",<br />
})<br />
<br />
-- by using QLabel{...} the stylesheet won't be given to the tooltip as well<br />
label:setStyleSheet[[<br />
QLabel{<br />
border-image: url(/home/vadi/Desktop/iso-avatar-draft_0.png);}<br />
]]<br />
</syntaxhighlight><br />
<br />
<br />
=== Aligning text/images inside a label ===<br />
By default, text is [http://qt-project.org/doc/qt-5/qlabel.html#alignment-prop centered vertically and left aligned] in a label. To align it to a specific side, use the stylesheets we learnt about earlier with the qproperty-alignment:<br />
<br />
<syntaxhighlight lang="lua"><br />
mylabel = Geyser.Label:new({<br />
name = "testlabel",<br />
x = "50%", y = 0,<br />
width = "50%", height = "100%",<br />
fgColor = "black",<br />
color = "SeaGreen",<br />
message = [[<center>heey</center>]]<br />
})<br />
<br />
-- specify one property this way:<br />
mylabel:setStyleSheet([[qproperty-alignment: 'AlignTop';]])<br />
<br />
-- or multiple ones separated with a |, for example this will align text to top-left:<br />
mylabel:setStyleSheet([[<br />
qproperty-alignment: 'AlignLeft | AlignTop';<br />
]])<br />
<br />
mylabel:echo("hi!")<br />
</syntaxhighlight><br />
<br />
[[File:Text_aligned.png|center]]<br />
<br />
=== Enabling wordwrap in a label ===<br />
If you need to enable word wrapping in a label (which by default is off), add the following line to the labels stylesheet:<br />
<br />
qproperty-wordWrap: true;<br />
<br />
As an example:<br />
<br />
<syntaxhighlight lang="lua"><br />
mylabel:setStyleSheet([[<br />
qproperty-wordWrap: true;<br />
]])<br />
</syntaxhighlight><br />
<br />
If you'd like to set multiple properties, set them all at once - not via multiple :setStyleSheet() calls:<br />
<br />
<syntaxhighlight lang="lua"><br />
mylabel:setStyleSheet([[<br />
background: red;<br />
]])<br />
</syntaxhighlight><br />
<br />
=== Adding a hover effect to a label ===<br />
The labels support adding stylesheets for specific cases, such as when a mouse is [http://doc.qt.io/qt-5/stylesheet-reference.html#hover-ps hovering] over them. To make this work, you provide CSS for when the label is in its usual state, and for when it is hovered over:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- this example will add a border to the label when it is hovered over<br />
mylabell:setStyleSheet([[<br />
QLabel{ border-radius: 4px; }<br />
QLabel::hover{<br />
background-color: rgba(0,0,0,0%);<br />
border: 4px double green;<br />
border-radius: 4px;<br />
}<br />
]])<br />
</syntaxhighlight><br />
<br />
=== Checkboxes ===<br />
Combining the fact that you can click on a label with an image to do something with the fact that you can change pictures on a label at will, you can make an image that changes itself when you click on it.<br />
<br />
<syntaxhighlight lang="lua"><br />
picture_label = Geyser.Label:new({<br />
name = "picture_label",<br />
x = "50%", y = "50%",<br />
width = "21px", height = "19px"<br />
})<br />
-- a little trick we do to make the background of the label be transparent<br />
picture_label:setStyleSheet([[<br />
background-color: rgba(0,0,0,0%);<br />
]])<br />
<br />
picture_label:setBackgroundImage([[/home/vadi/Desktop/checkbox_ticked.png]])<br />
picture_label:setClickCallback("on_checkbox_press")<br />
<br />
function on_checkbox_press()<br />
if checkbox_ticked then<br />
checkbox_ticked = false<br />
picture_label:setBackgroundImage([[/home/vadi/Desktop/checkbox_unticked.png]])<br />
echo("Checkbox unticked.\n")<br />
else<br />
checkbox_ticked = true<br />
picture_label:setBackgroundImage([[/home/vadi/Desktop/checkbox_ticked.png]])<br />
echo("Checkbox TICKED!\n")<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
The ''on_checkbox_press()'' function this time keeps the track of the checkbox with the ''checkbox_ticked'' variable and sets the image appropriately. You can download the ticked ([[File:Checkbox_ticked.png]]) and unticked images ([[File:Checkbox_unticked.png]]) or the [http://wiki.mudlet.org/images/6/6d/Checkbox.mpackage whole package] altogether.<br />
<br />
[[File:Checkbox_demo.png|500px|center]]<br />
<br />
=== Animated labels with sprites ===<br />
You can animate sprite packs using timers. Assuming you have the sprite pack downloaded, try this example:<br />
<br />
<syntaxhighlight lang="lua"><br />
picture_label = Geyser.Label:new({<br />
name = "picture_label",<br />
x = 10, y = "-24px",<br />
width = "16px", height = "14px",<br />
})<br />
<br />
santa_counter = nil<br />
<br />
function animate_santa()<br />
santa_counter = (santa_counter or 0) + 1<br />
if santa_counter > 8 then santa_counter = 1 end<br />
<br />
picture_label:setBackgroundImage([[/home/vadi/Desktop/santa/santa]]..santa_counter..[[.png]]) -- update location to actual image location on your computer<br />
santa_timer = tempTimer(.16, animate_santa)<br />
end<br />
<br />
animate_santa()<br />
</syntaxhighlight><br />
<br />
The completed package is available [http://wiki.mudlet.org/images/6/6b/Dancing-santa.mpackage here], install it and do '''start/end animation''' to watch.<br />
<br />
=== Inserting extra spaces and newlines ===<br />
Echoing text into Mudlet and Geyser labels is different from miniconsoles and the main window, due to their nature. One of the differences is that extra spaces in a label, by default, get compressed down to one. '''To add extra spaces in a label''', replace extra spaces with '''&amp;nbsp;''' or by wrapping your text with them inside '''<nowiki><pre>my text here</pre></nowiki>'''.<br />
<br />
<syntaxhighlight lang="lua"><br />
-- this won't work, it'll show as one space:<br />
mylabel:echo("You -> point")<br />
<br />
-- but this would, because it replaces all spaces with &nbsp before echoing<br />
mylabel:echo(string.gsub("You -> point", " ", "&nbsp;"))<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- here is another way to go about this - and it additionally makes the font be monospaced:<br />
mylabel:echo("<pre>You -> point</pre>")<br />
</syntaxhighlight><br />
<br />
'''To add a new line in a label''' (aka linebreak), use '''<nowiki><br></nowiki>''' (instead of ''\n'' as you are used to in an echo).<br />
<syntaxhighlight lang="lua"><br />
mylabel:echo("These<br>words<br>are<br>split")<br />
</syntaxhighlight><br />
<br />
=== Transparent labels ===<br />
One of the possible ways of achieving transparency on a label is to add <code>background-color: rgba(0,0,0,0%);</code> to its stylesheet. Here's an example:<br />
<br />
<syntaxhighlight lang="lua"><br />
my_transparent_label:setStyleSheet([[<br />
background-color: rgba(0,0,0,0%);<br />
]])<br />
</syntaxhighlight><br />
<br />
Want to get transparency in a miniconsole? You can [[Manual:Geyser#Change_your_miniconsole_background_image|do that as well]].<br />
<br />
=== Custom mouse cursor ===<br />
You can change the shape of the cursor when it's over your label with:<br />
<syntaxhighlight lang="lua"><br />
mylabel:setCursor("Forbidden") -- will change your mouse cursor to "forbidden" (as in "can't do this") cursor<br />
</syntaxhighlight><br />
Possible cursor shapes are [[CursorShapes| available here]], and you can import this [[Media:Cursor grid.zip|demo package]] to try them all out.<br />
<br />
It is also possible to change the mouse cursor to a custom made cursor by:<br />
<syntaxhighlight lang="lua"><br />
mylabel:setCustomCursor(getMudletHomeDir().."/custom_cursor.png")<br />
</syntaxhighlight><br />
It is recommended that the custom cursor is a png with size of 32x32 to be supported on all systems.<br />
<br />
[[File:Changecursoroverlabel.gif]]<br />
<br />
{{Note}} Available in Mudlet 4.8+<br />
<br />
=== Flyout Labels ===<br />
<br />
Flyout labels allow you to create 'dropdown' or 'flyout' menus - menus that reveal more items once you hover your mouse over them. To create flyout labels:<br />
# add <code>nestable=true</code> (left click to open menu) or <code>nestflyout=true</code> (mouse hover to open menu) to your main label.<br />
# use [http://www.mudlet.org/geyser/files/geyser/GeyserLabel.html#Geyser.Label:addChild :addChild()] on your main label to add flyout labels to it.<br />
## [http://www.mudlet.org/geyser/files/geyser/GeyserLabel.html#Geyser.Label:addChild :addChild()] uses the same arguments as when creating a new label but also takes the '''layoutDir''' option to specify in which direction and axis should the labels align, where 2 letters combine into the option: first letter R for right, L for left, T for top, B for bottom, followed by the orientation: V for vertical or H for horizontal. So options are: <code>layoutDir="RV"</code>, <code>layoutDir="RH"</code>, <code>layoutDir="LV"</code>, <code>layoutDir="LH"</code>, and so on.<br />
# optionally, add <code>flyOut=true</code> to your flyout labels to make the labels dissapear when the mouse isn't hovering over them anymore.<br />
<br />
Note that the main flyout label cannot go into a container and needs to be on its own.<br />
<br />
{{note}} Requires Mudlet 3.0.<br />
<br />
==== Demo ====<br />
Here's an example that follows the steps above:<br />
<br />
<syntaxhighlight lang="lua"><br />
label0 = Geyser.Label:new({name="label0", <br />
x="50%",y="50%",height=50,width=300,nestable=true, <br />
message="<center>Clicky clicky</center>"})<br />
<br />
-- and add 3 labels to it with RV layout - so Right of the label, aligned Vertically<br />
label1 = label0:addChild({name="label1",height=30,width=70, layoutDir="RV", flyOut=true, message="label one"})<br />
label1:setStyleSheet([[background-color: purple; border-width: 2px; border-style: solid; border-color: blue; border-radius: 2px; font-size: 7pt;]])<br />
<br />
label2 = label0:addChild({name="label2",height=30,width=70, layoutDir="RV", flyOut=true, message="label two"}) <br />
label2:setStyleSheet([[background-color: green; border-width: 2px; border-style: solid; border-color: blue; border-radius: 2px; font-size: 7pt;]])<br />
<br />
label3 = label0:addChild({name="label3",height=30,width=70, layoutDir="RV", flyOut=true, message="label three"})<br />
label3:setStyleSheet([[background-color: red; border-width: 2px; border-style: solid; border-color: blue; border-radius: 2px; font-size: 7pt;]])<br />
</syntaxhighlight><br />
<br />
A more thorough example. Try it out to see what you can create with flyout labels:<br />
<syntaxhighlight lang="lua"><br />
-- create a label with a nestable=true property to say that it can nest labels<br />
mainlabel = Geyser.Label:new({name="testa", x=400,y=50,height=50,width=300,nestflyout=true, message="<center>HOVER HERE TO SEE FLY-OUT LABELS!</center>"})<br />
<br />
-- create 15 labels and store them in a table <br />
table_for_flyout_labels = {}<br />
for i=1,15 do<br />
-- options to layoutDir are the direction the window should go (R for right, L for left, T for top, B for bottom), followed by how the nested labels should be oriented (V for vertical or H for horizontal). So "BH" here means it'll go on the bottom of the label, while expanding horizontally<br />
table_for_flyout_labels[i] = mainlabel:addChild({name="test"..tostring(i),height=30,width=70, layoutDir="BH", flyOut=true, message="test"..tostring(i)})<br />
<br />
table_for_flyout_labels[i]:setStyleSheet([[background-color: purple; border-width: 2px; border-style: solid; border-color: blue; border-radius: 2px;]])<br />
end<br />
<br />
-- make the test5 label look a bit special as it has got a surprise<br />
table_for_flyout_labels[5]:echo("Hover here")<br />
<br />
-- add even more nested labels to the 5th label!<br />
even_more_flyout_labels = {}<br />
for i=1,60 do<br />
-- here, the layout will be to the right of it, while expanding vertically<br />
even_more_flyout_labels[i]=table_for_flyout_labels[5]:addChild({name="hover label "..tostring(i),height=30,width=100, layoutDir="RV", flyOut=true, message="label "..tostring(i)})<br />
even_more_flyout_labels[i]:setClickCallback("testFunc", even_more_flyout_labels[i].name)<br />
even_more_flyout_labels[i]:setStyleSheet([[background-color: grey; border-width: 2px; border-style: solid; border-color: green; border-width: 2px; font-size: 7pt;]])<br />
end<br />
<br />
function testFunc(name)<br />
display(name)<br />
end<br />
</syntaxhighlight><br />
<br />
It'll look something like this: <br />
<br />
[[File:Flyout_labels_demo.png|150px]]<br />
<br />
==== Demo of layouts ====<br />
Here's another demo that explains all of the layout styles quite well:<br />
<syntaxhighlight lang="lua"><br />
local directions = {"R", "L", "T", "B"}<br />
local orientations = {"V", "H"}<br />
local mappings = {R = "right", L = "left", T = "top", B = "bottom", V = "vertical", H = "horizontal"}<br />
<br />
local combinations, combination_labels = {}, {}<br />
for _, direction in pairs(directions) do<br />
for _, orientation in pairs(orientations) do<br />
combinations[#combinations+1] = direction..orientation<br />
end<br />
end<br />
<br />
local function get_foreground_text_colour(r,g,b)<br />
local luminosity = (0.2126 * ((r/255)^2.2)) + (0.7152 * ((g/255)^2.2)) + (0.0722 * ((b /255)^2.2))<br />
if luminosity > 0.5 then<br />
return "black"<br />
else<br />
return "white"<br />
end<br />
end<br />
<br />
local function get_random_colour_rgb()<br />
return math.random(1,255), math.random(1,255), math.random(1,255)<br />
end<br />
<br />
-- create a label with a nestable=true property to say that it can nest labels<br />
all_possible_combinations_label = Geyser.Label:new({name="all_possible_combinations_label", x=0,y="-400",height=50,width=500,<br />
nestable = true, message="<center>Click to see a listing of possible combinations</center>"})<br />
<br />
for i = 1, #combinations do<br />
local combination = combinations[i]<br />
combination_labels[i] = all_possible_combinations_label:addChild({name="combo_"..combination,height=30,width=150, nestable = true, flyOut=true, layoutDir="BH", message="<center>Combination "..combination.."</center>"})<br />
<br />
local r,g,b = get_random_colour_rgb()<br />
local text_colour = get_foreground_text_colour(r,g,b)<br />
<br />
local combination_labels_children = {}<br />
for ii = 1, 3 do<br />
combination_labels_children[ii] = combination_labels[i]:addChild({<br />
name="combo_"..combination.."_"..ii, height = 30, width = 150, layoutDir=combination, flyOut = true,<br />
message = string.format("<center><b>%s</b>%s+<b>%s</b>%s layout</center>", <br />
combination:sub(1,1), mappings[combination:sub(1,1)]:sub(2), combination:sub(2,2), mappings[combination:sub(2,2)]:sub(2)),<br />
fgColor = text_colour})<br />
<br />
combination_labels_children[ii]:setStyleSheet(string.format([[background-color:rgb(%d, %d, %d); border-width: 2px; border-style: solid; border-color: green; border-width: 2px; font-size: 7pt;]], r,g,b))<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
It'll look like this:<br />
<br />
[[File:Flyoutlabels-layout-demo.png]]<br />
<br />
=== Geyser.Label right click menu ===<br />
{{note}} available in Mudlet 4.10+<br />
<br />
You can create a right click menu for a label just by using the function (assuming your label name is 'myLabel')<br />
<syntaxhighlight lang="lua"> myLabelːcreateRightClickMenu(MenuItems = myMenuTable, other cons) -- see example below for details </syntaxhighlight><br />
<br />
The menu table comprises of all the items and their names. To create a parent menu just create a nested table of names.<br />
Example of a menuTable<br />
<syntaxhighlight lang="lua"> menuTable = {"First Item", "Second Item (Parent)",{"First ChildItem","Second ChildItem"}, "Third Item"} </syntaxhighlight><br />
As menu would look likeː<br />
<br />
[[File:RCDemo1.gif|250px]]<br />
<br />
==== Style your right click menu ====<br />
Your right click menu has 2 default styles integratedː "light" and "dark" which are defined by the constraint "Style".<br />
To set a default style just give the constraint Style the preferred value, for exampleː<br />
<syntaxhighlight lang="lua"> Style = "dark" </syntaxhighlight><br />
To give different levels of your menu different style just add the number of the level to the constraint, for exampleː<br />
<syntaxhighlight lang="lua"> Style2 = "light" -- Gives the second level of your menu the "light" style</syntaxhighlight><br />
<br />
For adding your own stylesheet use the constraint MenuStyle (use the same method as above to define stylesheets for different levels)<br />
<syntaxhighlight lang="lua"> MenuStyle2 = [[QLabel::hover{ background-color: rgba(0,255,150,100%); color: white;} QLabel::!hover{color: brown; background-color: rgba(100,240,240,100%);} ]] <br />
-- Gives the second level of your menu this stylesheet</syntaxhighlight><br />
<br />
The same methods are used for defining the format, width and height for the menu item.<br />
<syntaxhighlight lang="lua"> <br />
MenuWidth = 70 -- standard menu width if nothing else is given<br />
MenuWidth2 = 80 -- menu width for the second level <br />
MenuFormat1 = "c10" -- menu format for the first level (format works like any other label echo format, in this case c is center and 10 is the font-size)<br />
MenuHeight = 30<br />
</syntaxhighlight><br />
<br />
==== Set onClick action for your menu item ====<br />
To set an action if your menu item is clicked use the function (assuming your label name is 'myLabel' and using the same MenuItems as defined above)<br />
<syntaxhighlight lang="lua"> <br />
myLabelːsetMenuAction("First Item", function() echo("Clicked on the first item\n") end<br />
myLabelːsetMenuAction("Second Item (Parent).First ChildItem", function() echo("Clicked on the first child item\n") end) -- To set an action to a child item find it by using "Parent.Child" as name (only one parent is needed to be given the parents parent is not needed)<br />
</syntaxhighlight><br />
<br />
==== Access an menu item directly ====<br />
The simplest way to access a menu item directly is by just using the function (assuming your label name is 'myLabel' and using the same MenuItems as defined above)<br />
For example to change the menu item textː<br />
<syntaxhighlight lang="lua"> <br />
myLabelːfindMenuElement("First Item"):echo([[my first Item]])<br />
</syntaxhighlight><br />
<br />
==== Right click menu example ====<br />
Better then any further explanation is probably this practical example. <br />
<br />
<syntaxhighlight lang="lua"> <br />
-- create the label the right click menu will be in<br />
myRightClickLabel = myRightClickLabel or Geyser.Label:new({<br />
name = "myRightClickLabel", message = "Please right click!", <br />
format = "cb15", x=10, y=10, width ="30%", height = "15%", <br />
color = "purple"})<br />
<br />
-- right click menu creation with custom styleheet on level2 and default "Dark" style <br />
myRightClickLabel:createRightClickMenu(<br />
{MenuItems = {"Emergency", "Drink",{"ManaPotion","HealthPotion"}, "Disappear", "Cast",{"Blindness", "Blink"}}, <br />
Style = "Dark", <br />
MenuWidth2 = 80, <br />
MenuFormat1 = "c10",<br />
MenuStyle2 = [[QLabel::hover{ background-color: rgba(0,255,150,100%); color: white;} QLabel::!hover{color: brown; background-color: rgba(100,240,240,100%);} ]]}<br />
)<br />
<br />
myRightClickLabel:setMenuAction("Emergency", function() <br />
cecho("<red:pink>[Emergency Mode] Run as fast as possible!\n") <br />
send("emergency") <br />
closeAllLevels(myRightClickLabel) -- this can be used to close the right click menu if clicked on this item<br />
end)<br />
<br />
myRightClickLabel:setMenuAction("Drink.ManaPotion", function()<br />
cecho("<blue>Drinking my mana potion.\n") <br />
send("drink mp") <br />
end )<br />
<br />
myRightClickLabel:setMenuAction("Drink.HealthPotion", function() <br />
cecho("<red>Drinking my health potion.\n") <br />
send("drink hp") <br />
end )<br />
<br />
myRightClickLabel:setMenuAction("Disappear", function() <br />
cecho("<grey>Disappearing.. \n") <br />
send("disappear") <br />
closeAllLevels(myRightClickLabel) <br />
end )<br />
<br />
myRightClickLabel:setMenuAction("Cast.Blindness", function() <br />
cecho("<light_blue>Casting blindness \n") <br />
send("cast blindness enemy") <br />
closeAllLevels(myRightClickLabel) <br />
end )<br />
<br />
myRightClickLabel:setMenuAction("Cast.Blink", function() <br />
cecho("<light_blue>Casting blink \n") <br />
send("cast blink") <br />
end )<br />
</syntaxhighlight><br />
<br />
This looks likeː<br />
<br />
<br />
[[File:Right click example demo.gif]]<br />
<br />
==== Add right click menu to label with already existing left click action ====<br />
If your label has an already existing left click action you'll have to create the right click menu<br />
"before" creating the labels "setClickCallBack" action and then just put into your labels onClick function<br />
(assuming your label name is 'myLabel' and 'event' is the last parameter of your onClick function)<br />
<br />
<syntaxhighlight lang="lua"> <br />
myLabel:onRightClick(event)<br />
</syntaxhighlight><br />
<br />
=== Geyser name ===<br />
Make sure to give your Geyser Labels, miniconsoles, and userwindows a <code>name</code> - while it'll technically work without one, items will be duplicated when you re-save them if they're lacking a name.<br />
<br />
==[http://www.mudlet.org/geyser/files/geyser/GeyserStyleSheet.html Geyser.StyleSheet]==<br />
<br />
Allows you to create a managed stylesheet to make it easier to set and change properties. Also allows you to inherit properties from another stylesheet, making it easier to manage multiple styles at once.<br />
<br />
=== Basic Usage ===<br />
<br />
Here's an example to get you started. This creates a basic stylesheet to set the background color black and the foreground/text color to green, then applies it to a Geyser Label.<br />
<br />
<syntaxhighlight lang="lua"><br />
local stylesheet = Geyser.StyleSheet:new([[<br />
background-color: black;<br />
color: green;<br />
]])<br />
local testLabel = Geyser.Label:new({<br />
name = "testLabel",<br />
x = 100,<br />
y = 100,<br />
height = 100,<br />
width = 300,<br />
stylesheet = stylesheet:getCSS(),<br />
})<br />
<br />
-- Alternate method of creating a stylesheet using a table of properties<br />
local stylesheet = Geyser.StyleSheet:new({<br />
['background-color'] = "black",<br />
['color'] = "green",<br />
})<br />
</syntaxhighlight><br />
<br />
=== Getting the CSS string === <br />
<br />
As shown above, you can use getCSS to get the stylesheet as a string.<br />
<br />
<syntaxhighlight lang="lua"><br />
display(stylesheet:getCSS())<br />
--[[<br />
"background-color: black;\ncolor: green;"<br />
--]]<br />
</syntaxhighlight><br />
<br />
=== Including a target ===<br />
<br />
You can include a 'target' for your stylesheet to be applied to, such as QLabel, QPlainTextEdit, etc.<br />
<br />
<syntaxhighlight lang="lua"><br />
-- QPlainTextEdit is useful for styling command lines in particular, to keep the style from bleeding into any associated miniconsole or userwindow.<br />
local stylesheet = Geyser.StyleSheet:new([[<br />
QPlainTextEdit {<br />
background-color: black;<br />
color: green;<br />
}]])<br />
<br />
-- or as an optional third argument. Passing nil for the parent explicitly <br />
local stylesheet = Geyser.StyleSheet:new([[<br />
background-color: black;<br />
color: green;<br />
]], nil, "QPlainTextEdit")<br />
<br />
-- or using the setTarget function after the fact<br />
local stylesheet = Geyser.StyleSheet:new([[<br />
background-color: black;<br />
color: green;<br />
]])<br />
stylesheet:setTarget("QPlainTextEdit")<br />
</syntaxhighlight><br />
<br />
=== Changing a property ===<br />
<br />
Assuming you started with the example above, if you wanted to change the background color to purple you would do the following:<br />
<br />
<syntaxhighlight lang="lua"><br />
stylesheet:set("background-color", "purple")<br />
testLabel:setStyleSheet(stylesheet:getCSS())<br />
</syntaxhighlight><br />
<br />
Or if you wanted to set the font, you would do:<br />
<syntaxhighlight lang="lua"><br />
stylesheet:set("font", [["Ubuntu Mono"]])<br />
</syntaxhighlight><br />
<br />
Note the way we set the font with the double quotes included in the string, this is because the quotes have to be there in the final stylesheet. You could use single quotes instead of the bracket notation as well:<br />
<br />
<syntaxhighlight lang="lua"><br />
stylesheet:set("font", '"Ubuntu Mono"')<br />
</syntaxhighlight><br />
<br />
=== Getting the value of a property ===<br />
<br />
Again assuming you started with the example code above it's as easy as<br />
<br />
<syntaxhighlight lang="lua"><br />
stylesheet:get("color") -- will return "green"<br />
</syntaxhighlight><br />
<br />
=== Getting a table of properties and their values ===<br />
<br />
<syntaxhighlight lang="lua"><br />
display(stylesheet:getStyleTable())<br />
--[[<br />
{<br />
["background-color"] = "purple",<br />
color = "green",<br />
font = '"Ubuntu Mono"'<br />
}<br />
--]]<br />
</syntaxhighlight><br />
<br />
=== Setting the properties via table ===<br />
<br />
<syntaxhighlight lang="lua"><br />
stylesheet:setStyleTable({<br />
["background-color"] = "purple",<br />
color = "green",<br />
font = '"Ubuntu Mono"',<br />
})<br />
</syntaxhighlight><br />
<br />
=== Resetting the style with a string ===<br />
<br />
Creating a new Geyser.StyleSheet would break any inheritance for stylesheets which had this one as a parent (see below), so if you wish to reset the style via CSS string you should use :setCSS<br />
<br />
<syntaxhighlight lang="lua"><br />
stylesheet:setCSS([[<br />
background-color: black;<br />
color: green;<br />
font: "Ubuntu Mono";<br />
]])<br />
</syntaxhighlight><br />
<br />
=== Inheriting properties ===<br />
<br />
As with most things Geyser, just pass the parent in when you create the new stylesheet<br />
<br />
<syntaxhighlight lang="lua"><br />
local childsheet = Geyser.StyleSheet:new("color: blue;", stylesheet)<br />
display(childsheet:getStyleTable())<br />
--[[<br />
{<br />
["background-color"] = "purple",<br />
color = "blue",<br />
font = '"Ubuntu Mono"'<br />
}<br />
--]]<br />
<br />
display(childsheet:get("background-color")<br />
--"purple"<br />
<br />
-- show only properties set in this stylesheet, without inheritance<br />
display(childsheet:getStyleTable(false))<br />
--[[<br />
{<br />
color = "blue"<br />
}<br />
--]]<br />
<br />
-- can do the same for the CSS string<br />
display(childsheet:getCSS(false))<br />
--[[<br />
"color: blue;"<br />
--]]<br />
</syntaxhighlight><br />
<br />
==[http://www.mudlet.org/geyser/files/geyser/GeyserMiniConsole.html Geyser.MiniConsole]==<br />
This allows you to spawn a Mudlet miniconsole - unlike labels, these aren't as styleable, but they do format text better. They make a good fit for text-based menus, chat and map capture, and other things.<br />
<br />
Spawning one is very similar to other Geyser elements - paste this into a new script:<br />
<syntaxhighlight lang="lua"><br />
HelloWorld = Geyser.MiniConsole:new({<br />
name="HelloWorld",<br />
x="70%", y="50%",<br />
autoWrap = true,<br />
color = "black",<br />
scrollBar = false,<br />
fontSize = 8,<br />
width="30%", height="50%",<br />
})<br />
</syntaxhighlight><br />
<br />
This'll make you one at the bottom-right of the screen. The miniconsole will have a grey background by default, but you can set it to any color you'd like with [http://www.mudlet.org/geyser/files/geyser/GeyserWindow.html#Geyser.Window:setColor miniconsole:setColor()]:<br />
<br />
<syntaxhighlight lang="lua"><br />
HelloWorld:setColor("black") -- give it a nice black background<br />
</syntaxhighlight><br />
<br />
A special dimension property that MiniConsoles have is a character - instead of specifying a miniconsole to be % of a container or a certain number of pixels, you can specify it as a certain number of characters. You do this by using "c" at the end of a number. This way, you can, for example, specify miniconsole to be 10 letters long and 2 lines high:<br />
<br />
<syntaxhighlight lang="lua"><br />
flatbox = Geyser.MiniConsole:new({<br />
name="flatbox",<br />
x="70%", y="50%",<br />
wrapAt = 10,<br />
width="10c", height="2c",<br />
})<br />
flatbox:setColor("red")<br />
flatbox:echo("ABCDEFGHIJ") -- that is 10 letters<br />
</syntaxhighlight><br />
<br />
=== Adding text ===<br />
You can use [[Manual:Technical_Manual#echo|echo()]] the same way with a miniconsole to add text as to the usual window:<br />
<br />
<syntaxhighlight lang="lua"><br />
HelloWorld:echo("hello!")<br />
</syntaxhighlight><br />
<br />
As well as [[Manual:Technical_Manual#cecho|cecho]], [[Manual:Technical_Manual#decho|decho]], or [[Manual:Technical_Manual#hecho|hecho]]:<br />
<br />
<syntaxhighlight lang="lua"><br />
HelloWorld:cecho("<green>hey, <blue>colored <red>text!\n")<br />
</syntaxhighlight><br />
<br />
=== Copying lines with color ===<br />
To copy a line over to the miniconsole, as it is from the game with all colors preserved, you can [[Manual:UI_Functions#selectCurrentLine|select]], [[Manual:UI_Functions#copy|copy]], and [[Manual:UI_Functions#appendBuffer|append]] it. For an example, try making a trigger with this as the ''Lua function'' pattern type:<br />
<br />
<syntaxhighlight lang="lua"><br />
return true<br />
</syntaxhighlight><br />
<br />
That'll make the trigger go off on every line. Then give it the following script (assumed you have made the HelloWorld miniconsole from earlier):<br />
<syntaxhighlight lang="lua"><br />
selectCurrentLine()<br />
copy()<br />
HelloWorld:appendBuffer()<br />
</syntaxhighlight><br />
<br />
... and you'll see all MUD output duplicated exactly as it is to the miniconsole. Amazing! It's very efficient as well, so you can have many miniconsoles, even in spam, not lag you down.<br />
<br />
=== Clearing the miniconsole ===<br />
Clearing the miniconsole just requires using the following script (assumes you have made the HelloWorld miniconsole from earlier):<br />
<br />
<syntaxhighlight lang="lua"><br />
HelloWorld:clear()<br />
</syntaxhighlight><br />
<br />
=== Doing edits in copied lines ===<br />
Sometimes you'll want to edit the line before stuffing it into the miniconsole. For example, if you're making a chat capture, you'd want to condense a really long org name into something that's more space-friendly.<br />
<br />
To do so, you'd use the [[Manual:Technical_Manual#selectString|selectString()]] the text you'd like to modify, [[Manual:Technical_Manual#replace|replace()]] it with a different one:<br />
<br />
<syntaxhighlight lang="lua"><br />
selectString("Your", 1) -- select the word you'd like to replace - in this case, 'Your'<br />
setBgColor(getBgColor()) -- preserve the background color in the replacement<br />
setFgColor(getFgColor()) -- preserve the foreground color in the replacement<br />
replace("Mine") -- replace the selection with the wird 'Mine'<br />
<br />
selectCurrentLine()<br />
copy()<br />
HelloWorld:appendBuffer()<br />
</syntaxhighlight><br />
<br />
=== Gagging from the main window ===<br />
If you'd like to gag the line from the main window so it only shows up in your miniconsole, [[Manual:Technical_Manual#deleteLine|delete]] it after moving it over:<br />
<br />
<syntaxhighlight lang="lua"><br />
selectCurrentLine()<br />
copy()<br />
HelloWorld:appendBuffer()<br />
deleteLine()<br />
</syntaxhighlight><br />
<br />
=== Clickable menus ===<br />
Using the [[Manual:Technical_Manual#echoLink|echoLink]], [[Manual:Technical_Manual#insertLink|insertLink]] and [[Manual:Technical_Manual#setLink|setLink]] functions, you can turn text into one that reacts on a click. Combined with your power of placing text anywhere on the screen with a miniconsole, you can make menus with options. Here is one such example, where selecting an item causes an echo to happen:<br />
<br />
<syntaxhighlight lang="lua"><br />
flatbox = Geyser.MiniConsole:new({<br />
name="flatbox",<br />
x="20%", y="80%",<br />
width="40c", height="4c",<br />
})<br />
flatbox:setColor("red")<br />
clearWindow("flatbox")<br />
<br />
flatbox:cecho("<white:red>Choose one of the following options:\n")<br />
<br />
flatbox:fg("white")<br />
flatbox:bg("red")<br />
<br />
for _, fruit in ipairs{"banana", "apple", "orange"} do<br />
echoLink("flatbox", "* "..fruit:title().."\n", [[echo("You picked ]]..fruit..[[\n")]], "The "..fruit.." option", true)<br />
end<br />
<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
This will produce something like the following:<br />
<br />
[[File:Fruit_menu.png|center]]<br />
<br />
=== Change your miniconsole background image ===<br />
{{note}} available in Mudlet 4.10+<br />
<br />
To set a custom background image for your miniconsole, use [https://www.mudlet.org/geyser/files/geyser/GeyserMiniConsole.html#Geyser.MiniConsole:setBackgroundImage :setBackgroundImage()]:<br />
<syntaxhighlight lang="lua"><br />
miniconsole_withBgImg = Geyser.MiniConsole:new({name = "BackgroundonConsole", x="50%", y="50%", width = "20%", height = "40%"})<br />
miniconsole_withBgImg:setBackgroundImage(":/Mudlet_splashscreen_development.png", "center")<br />
<br />
for i = 1, 6 do<br />
miniconsole_withBgImg:decho("<:0,0,0,130> This is a decho test with semi-transparent background\n")<br />
end<br />
<br />
for i = 1, 6 do<br />
miniconsole_withBgImg:hecho("#,80000000 This is a hecho test with semi-transparent background\n")<br />
end<br />
<br />
for i = 1, 2 do<br />
miniconsole_withBgImg:decho("<:0,0,0> This is a decho test with no transparent background\n")<br />
end<br />
<br />
for i = 1, 2 do<br />
miniconsole_withBgImg:hecho("#,000000 This is a hecho test with no transparent background\n")<br />
end<br />
</syntaxhighlight><br />
<br />
=== Enable and use your miniconsole command line ===<br />
{{note}} available in Mudlet 4.10+<br />
<br />
Every miniconsole has a hidden command line. Enable it with:<br />
<syntaxhighlight lang="lua"><br />
HelloWorldContainer = HelloWorldContainer or Adjustable.Container:new({name="HelloWorldContainer", titleText = "Container with a command line"})<br />
<br />
HelloWorld = Geyser.MiniConsole:new({<br />
name="HelloWorld",<br />
x=0, y=0,<br />
autoWrap = true,<br />
color = "purple",<br />
scrollBar = false,<br />
fontSize = 8,<br />
width="100%", height="100%",<br />
}, HelloWorldContainer)<br />
<br />
HelloWorld:enableCommandLine()<br />
</syntaxhighlight><br />
<br />
=== Set an action to your miniconsole command line ===<br />
If no action is set to your miniconsole command line the commands are send to the game the same way as for the main command line. Aliases still work as usual, and if you have command echo enabled in preferences, it'll show in both miniconsole and the main window.<br />
<br />
It is also possible to set an action to your command line, this enables you to use the command line as custom text input.<br />
<br />
<syntaxhighlight lang="lua"><br />
HelloWorld:enableCommandLine()<br />
local function channelChat(text)<br />
send("chat "..text)<br />
HelloWorld:echo("[chat] " ..text.."\n")<br />
end<br />
<br />
HelloWorld:setCmdAction(channelChat)<br />
</syntaxhighlight><br />
<br />
This will send your miniconsole command line input to the chat channel.<br />
<br />
More complicated/sophisticated actions are possible, setCmdAction works the same way as the Label clickCallback functions - that is, you can pass arguments to it.<br />
<br />
==[http://www.mudlet.org/geyser/files/geyser/GeyserGauge.html Geyser.Gauge]==<br />
<!--<br />
This is a composite window. Gauge duplicates the functionality of the built in Mudlet gauges, but in a clean and easily extended way. Internally, a Geyser Gauge is a container holding two Labels, front and back, which are initially scaled to fill the entire Gauge container. Hence, a gauge, g, can be given callbacks with the g.front:setClickCallback() method.<br />
<br />
The backgroundColor parameter initially sets the colors of the gauge, but of course the front and back components can be accessed individually as labels for high control over their looks. Gauges can be horizontal or vertical and decrease in value left to right, right to left, down up or up down depending on the value of the orientation parameter.<br />
--><br />
<br />
A Gauge allows you to represent numbers on a scale - and most typically, you've seen it be used as your standard hp/mana/whatever bar. A basic bar is made similarly to other Geyser elements. To set the value on the gauge that it should represent, use the [http://www.mudlet.org/geyser/files/geyser/GeyserGauge.html#Geyser.Gauge:setValue setValue()] function:<br />
<br />
<syntaxhighlight lang="lua"><br />
hpbar = Geyser.Gauge:new({<br />
name="hpbar",<br />
x="50%", y="85%",<br />
width="45%", height="5%",<br />
})<br />
hpbar:setValue(math.random(1,100),100)<br />
</syntaxhighlight><br />
<br />
That'll spawn you a pretty basic gauge with a horizontal orientation and a grey colour - and as a test, with a random value.<br />
<br />
[[File:Basic_gauge.png|center]]<br />
<br />
=== Updating a gauge ===<br />
You'd want your gauge to stay in sync with your actual values. To make that happen, you want to call [http://www.mudlet.org/geyser/files/geyser/GeyserGauge.html#Geyser.Gauge:setValue setValue()] whenever the value that the gauge is tracking changes.<br />
<br />
So for example, if you make a health bar - wherever you get your new health at (be it prompt, gmcp, atcp or whatever), update the gauge as well:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- theoretical example<br />
current_health, max_health = tonumber(matches[2]), tonumber(matches[3])<br />
<br />
-- update the bar<br />
hp_bar:setValue(current_health, max_health)<br />
</syntaxhighlight><br />
<br />
You can also write down how much health have you got on the bar with:<br />
<br />
<syntaxhighlight lang="lua"><br />
lua local hp = math.random(1,100) <br />
hpbar:setValue(current_health, max_health, "<b>"..max_health.."hp</b>")<br />
<br />
-- example using GMCP in IRE games:<br />
hpbar:setValue((100/gmcp.Char.Vitals.maxhp)*gmcp.Char.Vitals.hp,100,gmcp.Char.Vitals.hp)<br />
</syntaxhighlight><br />
<br />
[[File:Hpbar_basic.png|center]]<br />
<br />
=== Styling a gauge ===<br />
The Geyser gauge is composed of three labels - one is called ''mygauge.front'', ''mygauge.back'' and ''mygauge.text''. Combining this with Geyser:Label.setStyleSheet, you can improve the visuals of your gauges by using Qt-supported CSS. The syntax for specifying CSS is a bit different - it requires a semicolon after every property, and is done in the format of ''property name''''':'''''values''''';'''. A list of all possible properties you can use is [http://doc.qt.io/qt-5/stylesheet-reference.html#list-of-properties available here] and you can use [https://build-system.fman.io/qt-designer-download Qt Designer] to create them. Practical example:<br />
<br />
<syntaxhighlight lang="lua"><br />
hpbar = Geyser.Gauge:new({<br />
name="hpbar",<br />
x="50%", y="85%",<br />
width="45%", height="20px",<br />
})<br />
hpbar.front:setStyleSheet([[background-color: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #98f041, stop: 0.1 #8cf029, stop: 0.49 #66cc00, stop: 0.5 #52a300, stop: 1 #66cc00);<br />
border-top: 1px black solid;<br />
border-left: 1px black solid;<br />
border-bottom: 1px black solid;<br />
border-radius: 7;<br />
padding: 3px;<br />
]])<br />
hpbar.back:setStyleSheet([[background-color: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #78bd33, stop: 0.1 #6ebd20, stop: 0.49 #4c9900, stop: 0.5 #387000, stop: 1 #4c9900);<br />
border-width: 1px;<br />
border-color: black;<br />
border-style: solid;<br />
border-radius: 7;<br />
padding: 3px;<br />
]])<br />
<br />
hpbar:setValue(math.random(1,100),100)<br />
</syntaxhighlight><br />
<br />
[[File:Fancy_Geyser_gauge.png|center]]<br />
<br />
The same style can be adjusted by colors to red as well:<br />
<br />
<syntaxhighlight lang="lua"><br />
hpbar = Geyser.Gauge:new({<br />
name="hpbar",<br />
x="50%", y="85%",<br />
width="45%", height="20px",<br />
})<br />
hpbar.front:setStyleSheet([[background-color: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #f04141, stop: 0.1 #ef2929, stop: 0.49 #cc0000, stop: 0.5 #a40000, stop: 1 #cc0000);<br />
border-top: 1px black solid;<br />
border-left: 1px black solid;<br />
border-bottom: 1px black solid;<br />
border-radius: 7;<br />
padding: 3px;]])<br />
hpbar.back:setStyleSheet([[background-color: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #bd3333, stop: 0.1 #bd2020, stop: 0.49 #990000, stop: 0.5 #700000, stop: 1 #990000);<br />
border-width: 1px;<br />
border-color: black;<br />
border-style: solid;<br />
border-radius: 7;<br />
padding: 3px;]])<br />
<br />
hpbar:setValue(math.random(1,100),100)<br />
</syntaxhighlight><br />
<br />
[[File:Fancy_Geyser_gauge_red.png|center]]<br />
<br />
=== Updating a gauge ===<br />
The Geyser gauge is composed of three labels - one is called ''mygauge.front'', ''mygauge.back'' and ''mygauge.text''. To make a gauge clickable you can set a ClickCallBack on the top label which is ''mygauge.text'' example: <syntaxhighlight lang="lua">mygauge.text:setClickCallback("functionName", variableToSendToFunctionName)</syntaxhighlight><br><br />
If you would like to have different click events for the top or back of a gauge you can enable clickThrough for the top or ''mygauge.text'' label example<br />
<br />
<syntaxhighlight lang="lua"><br />
mygauge.text:enableClickthrough()<br />
mygauge.front:setClickCallback("functionOne", variableToSendToFunctionOne)<br />
mygauge.back:setClickCallback("functionTwo", variableToSendToFunctionTwo)<br />
</syntaxhighlight><br />
<br />
<br />
=== Tooltips on gauges ===<br />
Tooltips are available since Mudlet 4.6 as explained in above section [[#Adding_a_tooltip_to_a_label]], and as gauges are really only made up of labels as well, you could add a tooltip then by just using <syntaxhighlight lang="lua">mygauge.text:setToolTip("This is the gauge's tooltip", "10")</syntaxhighlight> the same as it's handled for clickback.<br />
<br />
== HBox/VBox ==<br />
<br />
These are special types of containers. Every window in these is horizontally or vertically aligned in the order they were added.<br />
<br />
<sub>Added to Mudlet in 2.0-rc4</sub><br />
<br />
== Geyser.UserWindow ==<br />
Allows you to use Mudlets UserWindows within Geyser, which allows you to use all the functionality of a MiniConsole in its basic form.<br />
The big advantage is the possibility to add other Geyser Elements like Labels, MiniConsole, Gauges, Mappers to the UserWindow.<br />
The UserWindow then can act as container for those elements with all the perks of dynamic resizing or any other Geyser functionality.<br />
<br />
{{note}} available in Mudlet 4.6.1+<br />
<br />
===Basic floating userwindow ===<br />
This will create a movable floating userwindow.<br />
<br />
<syntaxhighlight lang="lua"><br />
testuserwindow = Geyser.UserWindow:new({<br />
name = "TestUserWindow",<br />
titleText ="My Test UserWindow", -- only available since Mudlet 4.8+<br />
x = "20%", y="20%",<br />
width="30%", height ="40%"<br />
})<br />
</syntaxhighlight><br />
<br />
You can change the title of the userwindow by using the parameger titleText and the functions below (as of Mudlet 4.8+)ː<br />
<br />
To set a new title after creation useː<br />
<syntaxhighlight lang="lua"><br />
testuserwindow:setTitle("My new title Text")<br />
</syntaxhighlight><br />
<br />
To revert to the standard title useː<br />
<syntaxhighlight lang="lua"><br />
testuserwindow:resetTitle()<br />
</syntaxhighlight><br />
<br />
To '''save the position''' of the userwindow - say in case you've dragged it onto another monitor and would like it to stay there when you restart Mudlet - use [[Manual:UI_Functions#saveWindowLayout|saveWindowLayout()]]:<br />
<br />
<syntaxhighlight lang="lua"><br />
saveWindowLayout()<br />
</syntaxhighlight><br />
<br />
To restore it afterwards, use [[Manual:UI_Functions#loadWindowLayout|loadWindowLayout()]]:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- create your userwindows first with Geyser.UserWindow:new<br />
-- then restore them to the positions they were at:<br />
loadWindowLayout()<br />
</syntaxhighlight><br />
<br />
=== Docked UserWindow ===<br />
To create the window docked at the right side,<br />
set the variable docked (at creation of the container) to true.<br />
Be aware that with this variable set to true the position and the size at creation of the userwindow will be ignored.<br />
<br />
<syntaxhighlight lang="lua"><br />
testuserwindow = Geyser.UserWindow:new({<br />
name = "DockedTestUserWindow",<br />
docked = true<br />
<br />
})<br />
</syntaxhighlight><br />
<br />
Since Mudlet 4.8+ it is also possible to choose the docking Position of the UserWindow at creation and by function withː<br />
<br />
<syntaxhighlight lang="lua"><br />
testuserwindow = Geyser.UserWindow:new({<br />
name = "DockedTestUserWindow",<br />
docked = true,<br />
dockPosition = "top" -- Possible dockPositions are left "l", right "r", top "t", bottom "b" and floating "f" <br />
})<br />
</syntaxhighlight><br />
<br />
To change it for a already created UserWindow use the function setDockPosition(dockPosition) likeː<br />
<syntaxhighlight lang="lua"><br />
testuserwindow:setDockPosition("left")<br />
</syntaxhighlight><br />
<br />
=== Disable/enable UserWindow autoDock ===<br />
{{note}} available in Mudlet 4.8+<br />
<br />
The auto docking feature can be really annoying at times. To disable it use the functionsː<br />
<syntaxhighlight lang="lua"><br />
testuserwindow:disableAutoDock() -- disables autoDock. Docking still possible with ːsetDockPosition<br />
testuserwindow:enableAutoDock() -- reenables autoDock<br />
</syntaxhighlight><br />
<br />
=== Styling the UserWindow border and title area ===<br />
{{note}} available in Mudlet 4.10+ and Linux only<br />
<br />
Geyser.UserWindows can accept a stylesheet to change the appearance of the border and title area and make<br />
the UserWindow look more appealing. This unfortunately only works in Linux, as in macOS and Windows, it is the OS theme that is used here. <br />
<br />
<syntaxhighlight lang="lua"><br />
myUserWindow = myUserWindow or Geyser.UserWindow:new({<br />
name = "myUserWindow", titleText = "myUserWindow", autoDock = false<br />
})<br />
<br />
myUserWindow:setStyleSheet( <br />
[[QDockWidget{<br />
border: 1px solid green; /* UserWindow border style */<br />
font: bold 15pt "Arial"; /* Font of the titleBar */<br />
color: rgb(0,0,150); /* Font color */<br />
}<br />
<br />
QDockWidget::title{ <br />
background-color: rgb(0,255,150); /* TitleBar color */<br />
border: 2px solid red; /* TitleBar border */<br />
border-radius: 2px; /* TitleBar border radius */<br />
text-align: center; /* alignment of the titleText */<br />
}<br />
]])<br />
</syntaxhighlight><br />
<br />
This looks likeː<br />
<br />
[[File:UserWindowStyleSheet.png]]<br />
<br />
=== UserWindow as Container ===<br />
This is the feature which shows the versatile nature of Geyser.UserWindows.<br />
The UserWindow act as container and is at that possible to dynamically resize the containing Geyser Elments.<br />
Put a label in the UserWindow resize it as rectangle.<br />
<syntaxhighlight lang="lua"><br />
testuserwindow = Geyser.UserWindow:new({<br />
name = "ParentTestUserWindow",<br />
x = "20%", y="20%",<br />
width="30%", height ="40%"<br />
})<br />
<br />
testuserwindow:setColor("dark_green") -- give the userwindow a bit of color <br />
<br />
labelinuserw = Geyser.Label:new({<br />
name = "LabelinUserWindow",<br />
x=20, y=20,<br />
width = -20, height = -20,<br />
color="light_blue", fontSize=20,<br />
},testuserwindow)<br />
<br />
labelinuserw:echo("This is a label in an userwindow", "black", "c")<br />
</syntaxhighlight><br />
[[File:LabelInUserWindow.png]]<br />
<br />
The same way you are able to add your favorite Geyser Application (like tabbed chat, animated timers, gauges) to an UserWindow.<br />
<br />
Note that you don't need to add MiniConsoles to a UserWindow - as UserWindows already have them built-in.<br />
<br />
[[File:Tabbedchatinuserwindow.png]]<br />
<br />
== Geyser.CommandLine ==<br />
{{note}} available in Mudlet 4.10+<br />
<br />
Allows you to create your custom command lines which can resize/move like any other Geyser object.<br />
<br />
If you just need a command line which is integrated in a miniconsole or userwindow, check out [[Manual:Geyser#Enable and use your miniconsole command line|:enableCommandLine()]].<br />
<br />
=== Creating a Geyser.CommandLine ===<br />
An example to get you startedː<br />
<syntaxhighlight lang="lua"><br />
myCommandLine = myCommandLine or Geyser.CommandLine:new({<br />
name = "myCommandLine", <br />
x = "-20%", y = -40, <br />
width = "20%", height = 40,<br />
stylesheet = "border: 1px solid silver;"<br />
})<br />
</syntaxhighlight><br />
This creates a new command line in the right bottom of your screen.<br />
<br />
=== Bind action to your command line input ===<br />
If you use your previously created command line, any command will just be send to the game, after having been checked for aliases.<br />
<br />
To react to any input in a custom manner, we can set an action to the command line and use the input as parameter.<br />
<br />
Example of a command line changing the background color of your main console (assumes you have created "myCommandLine" from earlier): <br />
<syntaxhighlight lang="lua"><br />
myCommandLine:setAction(<br />
function(commandLineInput)<br />
r, g, b = Geyser.Color.parse(commandLineInput) -- gets the r, g, b values of the color you input to the command line<br />
if b then -- checks if the color is valid<br />
setBackgroundColor(r, g, b)<br />
else<br />
echo("\n"..commandLineInput.." is not a valid color. Try again.")<br />
end<br />
end)<br />
</syntaxhighlight><br />
<br />
=== Styling a command line ===<br />
You can style your Geyser command line by using Qt-supported CSS. A list of all possible properties you can use is [http://doc.qt.io/qt-5/stylesheet-reference.html#list-of-properties available here].<br />
<br />
Practical example (assuming "myCommandLine" is created)ː<br />
<syntaxhighlight lang="lua"><br />
myCommandLine:setStyleSheet([[<br />
QPlainTextEdit{ /* QPlainTextEdit is used to prevent the styleSheet bleeding to the right click menu*/<br />
border: 1px solid silver; /* Command line border style */<br />
background-color: rgb(0,255,150); /* Command line background color */<br />
font: bold 12pt "Arial"; /* Font and font-size of your command line */<br />
color: rgb(0,0,150); /* Command line text color */<br />
}<br />
]])<br />
</syntaxhighlight><br />
<br />
=== Create an extra command line in Mudlet ===<br />
If your goal is to just have an extra command/input line - say, for role-playing purposes: copy/paste the example below into a new script in Mudletː<br />
<br />
<syntaxhighlight lang="lua"><br />
inputContainer = inputContainer or Adjustable.Container:new({<br />
x = 0, y = "-4c", <br />
name = "InputContainer", padding = 2, <br />
width = "100%", height = "4c", <br />
autoLoad = false<br />
})<br />
<br />
extraCmdLine = extraCmdLine or Geyser.CommandLine:new({<br />
name = "extraCmdLine", <br />
x = 0, y = 0, width = "100%", height = "100%"<br />
}, inputContainer)<br />
<br />
inputContainer:attachToBorder("bottom")<br />
</syntaxhighlight><br />
<br />
This will look likeː <br />
<br />
[[File:AdditionalCommandLine.png|extra command line]]<br />
<br />
== Adjustable.Container ==<br />
{{note}} available in Mudlet 4.8+<br />
<br />
Adjustable Containers are a new "GeyserClass" which act as containers for Geyser elements, but with more flexible and user configurable features. They are referred to as "adjustable" because they can be minimized, loaded, saved, moved, adjusted in size with the mouse pointer, and attached to borders. <br />
<br />
A brief video of [https://www.youtube.com/watch?v=GT2ScizuM48&feature=youtu.be Introduction to Adjustable Containers] is available.<br />
<br />
=== Creating an Adjustable.Container ===<br />
An Adjustable.Container is created just like any other Geyser Object. For example, we might experiment with creating a new Adjustable.Container by running the following line of lua code:<br />
<syntaxhighlight lang="lua"><br />
testCon = testCon or Adjustable.Container:new({name="testContainer"})<br />
</syntaxhighlight><br />
This will create a new Adjustable.Container with the name ''testContainer''. Specifying the adjustable container's name is important for saving. Defining a variable, such as ''testCon'' in our above example, allows functions to be used with the Adjustable.Container.<br />
<br />
Our newly created Adjustable.Container may be used the same way as any other Geyser.Container might. For example, let's put a Geyser.Label in our new testContainer:<br />
<br />
<syntaxhighlight lang="lua"><br />
testCon = testCon or Adjustable.Container:new({name="testContainer"})<br />
testLabel = Geyser.Label:new({name="myTestLabel", x=0, y=0, height="100%", width="100%", color="green"},testCon)<br />
</syntaxhighlight><br />
<br />
The above code creates a new, green-colored Geyser.Label in the ''testCon'' adjustable.container as shown below:<br />
<br />
[[File:GreenLabelinAdjustableContainer.png]]<br />
<br />
You can also create one for miniconsole:<br />
<br />
<syntaxhighlight lang="lua"><br />
miniconsoleContainer = miniconsoleContainer or Adjustable.Container:new({name="miniconsoleContainer"})<br />
myMiniconsole = Geyser.MiniConsole:new({<br />
name="myMiniconsole",<br />
x=0, y=0,<br />
autoWrap = true,<br />
color = "black",<br />
scrollBar = false,<br />
fontSize = 8,<br />
width="100%", height="100%",<br />
}, miniconsoleContainer)<br />
<br />
myMiniconsole:echo("Hello!\n")<br />
</syntaxhighlight><br />
<br />
That will give you:<br />
<br />
[[File:Adjustable container miniconsole.png]]<br />
<br />
=== Key Functions ===<br />
A listing of key functions for the Adjustable.Container module can be found hereː https://www.mudlet.org/geyser/files/geyser/AdjustableContainer.html<br />
<br />
To make the Adjustable Container show on screen use the following:<syntaxhighlight lang="lua"><br />
testCon:show() --will cause the Adjustable Container to show if not showing<br />
</syntaxhighlight><br />
<br />
===<div id="valid constraints"> Valid Constraints</div>===<br />
Adjustable Container constraints and their default values can be found at [https://www.mudlet.org/geyser/files/geyser/AdjustableContainer.html#Adjustable.Container:new].<br />
<br />
These are in addition to the standard Geyser.Container constraints.<br />
<br />
=== Change Title Text ===<br />
To specify the title text of a new container, use the constraint <code>titleText</code> in the constructor (see [[Manual:Geyser#valid constraints|valid constraints]]).<br />
<br />
To change the title text after a container has already been created, use <code>setTitle</code>. Continuing from the previous example, the title for an existing container named "testCon" might be adjusted in a number of ways: <br />
<br />
<syntaxhighlight lang="lua"><br />
testCon:setTitle("Title") -- changes the container's title to "Title"<br />
</syntaxhighlight><br />
<br />
A container's title text defaults to the color green, but this can also be adjusted by using <code>setTitle</code>: <br />
<br />
<syntaxhighlight lang="lua"><br />
testCon:setTitle("Red Title Test","red") -- changes the container's title text to "Red Title Test" and displays the text in the specified color "red".<br />
</syntaxhighlight><br />
<br />
To restore a container's default title text, <code>setTitle</code> is issued without any specified title or color: <br />
<br />
<syntaxhighlight lang="lua"><br />
testCon:setTitle() -- resets the container's title text<br />
</syntaxhighlight><br />
<br />
=== AutoSave and AutoLoad ===<br />
The following Adjustable.Container settings can be saved and loadedː<br />
<br />
<code>x</code>, <code>y</code>, <code>height</code>, <code>width</code>, <code>minimized</code>, <code>locked</code>, <code>lock Style</code>, <code>padding</code>, and <code>hidden</code>.<br />
<br />
These settings will be automatically saved when the Mudlet profile is closed, and automatically loaded when a previous Adjustable.Container is created within the corresponding profile.<br />
<br />
To prevent automatic saving and/or loading of these settings, the <code>autoLoad</code> and <code>autoSave</code> constraints can be included in the constructor. For example, the following code will prevent the settings of the ''testCon2'' Adjustable.Container from being loaded upon creation:<br />
<br />
<syntaxhighlight lang="lua"><br />
testCon2 = testCon2 or Adjustable.Container:new({name="testCon2", autoLoad=false})<br />
</syntaxhighlight><br />
<br />
To also prevent the ''testCon2'' Adjustable.Container from automatically saving its settings when the Mudlet profile is closed, the <code>autoSave=false</code> constraint would be added at creation as follows:<br />
<br />
<syntaxhighlight lang="lua"><br />
testCont2 = testCont2 or Adjustable.Container:new({name="testCont2", autoLoad=false, autoSave=false})<br />
</syntaxhighlight><br />
<br />
Automatic saving can also be deactivated after an Adjustable.Container has been created, by invoking <code>testCont:disableAutoSave()</code><br />
<br />
Note that even with autoSave and autoLoad disabled, it is still possible to save and load manually through the right-click menu and/or by using <code>testCont:save()</code> or <code>testCont:load()</code> in a script.<br />
<br />
To save/load all your containers manually at the same time, we use <code>Adjustable.Container:saveAll()</code> and/or <code>Adjustable.Container:loadAll()</code><br />
<br />
=== "All" Functions ===<br />
The following functions affect all Adjustable Containers at the same time.<br />
<br />
{{note}} You must create the Adjustable Containers before these functions will have an effect.<br />
<br />
<code>Adjustable.Container.loadAll()</code> loads all the settings from your Adjustable Containers at once.<br />
<br />
<code>Adjustable.Container.saveAll()</code> saves all your Adjustable Containers at once.<br />
<br />
<code>Adjustable.Container.loadAll()</code> loads all the settings from your Adjustable Containers at once.<br />
<br />
<code>Adjustable.Container:showAll()</code> shows all your Adjustable Containers at once.<br />
<br />
<code>Adjustable.Container:doAll(myfunc)</code> creates a function that will affect all your Adjustable Containers. For example:<br />
<syntaxhighlight lang="lua"><br />
Adjustable.Container:doAll(function(self) self:hide() end) -- hides all your adjustable containers<br />
</syntaxhighlight><br />
<br />
=== Custom Save/Load Directories and Slots ===<br />
{{note}} available in Mudlet 4.10+<br />
==== Custom Directory ====<br />
If no option set your Adjustable.Container saves/loads its settings in your profile directory.<br />
<br />
It is possible to change the default save/load directory by using for example a different defaultDir as constraint when creating your Adjustable.Container.<br />
<br />
{{note}} This can be especially useful for authors of packages which want to ship their own save files.<br />
<br />
Exampleː<br />
<syntaxhighlight lang="lua"><br />
testCon2 = testCon2 or Adjustable.Container:new({name="testCon2", defaultDir = "/home/edru/MyAdjustableContainerSettings/"}) -- noteː the directory will be created if it doesn't exist<br />
</syntaxhighlight><br />
<br />
Example for save files in a package (assuming the packagename is "AdjustableContainerTest" and the settings are saved in "myPersonalAdjSettings"<br />
<syntaxhighlight lang="lua"><br />
local packageName = "AdjustableContainerTest"<br />
testCon2 = testCon2 or Adjustable.Container:new({name="testCon2", defaultDir = string.format("%s/%s/myPersonalAdjSettings/", getMudletHomeDir(), packageName)})<br />
</syntaxhighlight><br />
<br />
==== Custom Slot ====<br />
Another useful addition is to choose a save slot depending on the situation or to reset to a default save state.<br />
<br />
To save to a different slot just add it as parameter when saving.<br />
<br />
For exampleː<br />
<syntaxhighlight lang="lua"><br />
testCon2ːsave("combatSlot")<br />
</syntaxhighlight><br />
<br />
To then load from that slot just useː<br />
<syntaxhighlight lang="lua"><br />
testCon2ːload("combatSlot")<br />
</syntaxhighlight><br />
<br />
{{note}} This also allows package/module authors to choose a "default" save setting to reset to.<br />
<br />
Exampleː<br />
<syntaxhighlight lang="lua"><br />
Adjustable.ContainerːsaveAll("default") -- saves the default settings<br />
<br />
-- to reset to default settings then just use<br />
Adjustable.ContainerːloadAll("default") -- loads the default settings<br />
</syntaxhighlight><br />
<br />
This can also be used to change the whole GUI on the fly.<br />
<br />
Exampleː<br />
<syntaxhighlight lang="lua"><br />
-- in combat situation use combat settings<br />
Adjustable.ContainerːloadAll("combat") -- loads special combat settings<br />
-- combat is over <br />
Adjustable.ContainerːloadAll("default") --reverts to the default settings<br />
</syntaxhighlight><br />
<br />
==== Delete Save File ====<br />
To delete the save file just useː<br />
<syntaxhighlight lang="lua"><br />
testCont2:deleteSaveFile()<br />
</syntaxhighlight><br />
<br />
===Right-click menu===<br />
Your Adjustable Container has also integrated a right-click menu with the main key functions for easier usability:<br />
<br />
[[File:AdjustableContainerRightClickMenu.png]]<br />
<br />
The right-click menu automatically shows you the possible positions to attach to (top, right, bottom, or left) when it's near one of them. For example, to attach a window to the right of the screen, drag it over to the right - and then the 'Attach to - right' will appear as an option:<br />
<br />
[[File:Adjustable Container - attach to right.png]]<br />
<br />
It also shows the lockstyle selection, which allows you to choose what happens when you press <code>Lock</code>, with 4 lockstyles available by default:<br />
<br />
* standard: this is the default lockstyle, with a small margin on top to keep the right click menu usable.<br />
* light: only hides the min/restore and close labels. Borders and margin are not affected.<br />
* full: the container gets fully locked without any margin left for the right click menu.<br />
* border: keeps the borders of the container visible while locked.<br />
<br />
From Mudlet 4.10+ on it is also possible to change your right-click menu style to dark mode by<br />
<br />
<syntaxhighlight lang="lua"><br />
myAdjustableContainer:changeMenuStyle("dark") -- possible menu styles are "dark" or "light"<br />
</syntaxhighlight><br />
<br />
=== Create a Custom Menu with Custom Items ===<br />
To create a new menu element in your right click menu called "Custom" and add an item to it use:<br />
<syntaxhighlight lang="lua"><br />
testcontainer:newCustomItem(name, func)<br />
-- for example<br />
testcontainer:newCustomItem("Hello world", function(self) echo("Hello world\n") self:flash() end)<br />
-- this will write "Hello world" to the main console and flashes your container.<br />
</syntaxhighlight><br />
<br />
=== Add new LockStyles ===<br />
For more advanced users it's possible to add a new Lockstyles by:<br />
<syntaxhighlight lang="lua"><br />
testcontainer:newLockStyle(name, func)<br />
-- for example<br />
testcontainer:newLockStyle("NewLockStyle", function(self) self.Inside:move(40, 40) self.Inside:resize(-40,-40) self:setTitle("") end)<br />
</syntaxhighlight><br />
<br />
=== Change Adjustable Container Style ===<br />
Additionally to the standard container constraints Adjustable Containers allow you to change at creation: the internal Label style, the menu style, min/close buttons, the menu text, title text... <br />
<br />
( see [[Manual:Geyser#valid constraints|valid constraints]])<br />
An example of a Adjustable Container with different style.<br />
<syntaxhighlight lang="lua"><br />
testCont =<br />
testCont or<br />
Adjustable.Container:new(<br />
{<br />
name = "TestNewStyleContainer",<br />
adjLabelstyle = "background-color:rgba(220,220,220,100%); border: 5px groove grey;",<br />
buttonstyle=[[<br />
QLabel{ border-radius: 7px; background-color: rgba(140,140,140,100%);}<br />
QLabel::hover{ background-color: rgba(160,160,160,50%);}<br />
]],<br />
buttonFontSize = 10,<br />
buttonsize = 20,<br />
titleText = "My new Style",<br />
titleTxtColor = "black",<br />
padding = 15,<br />
}<br />
)<br />
</syntaxhighlight><br />
This code creates a container which looks like this:<br />
<br />
[[File:NewStyleAdjustableContainer.png|Adjustable Container with different style]]<br />
<br />
<br />
=== Attach your Adjustable Container to a Border ===<br />
The simplest way to attach your container to a border is to move your container near the border you want it to attach and use the <br />
right click menu <code> Attach to:</code><br />
<br />
There is also the function <code> TestCont:attachToBorder("right") -- attach TestCont to the right border </code><br />
<br />
To change the margin between container and border use the constraint <code> attachedMargin </code > or the function <code> TestContːsetBorderMargin(10) -- 10 is the margin in px </code><br />
<br />
{{note}} The border is set in percentages and adjusts with screen-size<br />
<br />
=== Create a moveable Border Frame ===<br />
{{note}} available in Mudlet 4.10+<br />
<br />
Adjustable Container can be connected to a border and therefore act like a frame.<br />
<br />
This only works if your container is attached to a specific border and the border to connect to has also at least one container attached to it.<br />
Use the function <code>connectToBorder</code><br />
<br />
<syntaxhighlight lang="lua"><br />
TestCont:connectToBorder("left") -- possible borders are "top", "bottom", "right", "left"<br />
</syntaxhighlight><br />
<br />
Minimizing automatically disconnects from a border. Another way is to use the function <code>disconnect</code>.<br />
<br />
{{note}}Connected container are still resizable even if locked.<br />
<br />
If you like to do everything with your right click menu there is the function<br />
<br />
<syntaxhighlight lang="lua"><br />
TestContːaddConnectMenu()<br />
</syntaxhighlight><br />
If you want to add the connect menu items to all Adjustable Containers just<br />
<syntaxhighlight lang="lua"><br />
Adjustable.Container:doAll(function(self) self:addConnectMenu() end)<br />
</syntaxhighlight><br />
<br />
There is also a brief video of how to [https://www.youtube.com/watch?v=Ex-q5zAEfpc connect your Adjustable Container] available.<br />
<br />
Exampleː<br />
<syntaxhighlight lang="lua"><br />
GUI = GUI or {}<br />
<br />
GUI.top = Adjustable.Container:new({name = "top", y="0%", height = "10%", autoLoad = false})<br />
GUI.bottom = Adjustable.Container:new({name = "bottom", height = "20%", y = "-20%", autoLoad = false})<br />
GUI.right = Adjustable.Container:new({name = "right", y = "0%", height = "100%", x = "-20%", width = "20%", autoLoad = false})<br />
GUI.left = Adjustable.Container:new({name = "left", x = "0%", y = "0%", height = "100%", width = "20%", autoLoad = false})<br />
<br />
<br />
GUI.top:attachToBorder("top")<br />
GUI.bottom:attachToBorder("bottom")<br />
GUI.left:attachToBorder("left")<br />
GUI.right:attachToBorder("right")<br />
<br />
GUI.top:connectToBorder("left")<br />
GUI.top:connectToBorder("right")<br />
GUI.bottom:connectToBorder("left")<br />
GUI.bottom:connectToBorder("right")<br />
</syntaxhighlight><br />
Here's what the frame will look like:<br />
<br />
[[File:Adjustable_frame.gif]]<br />
<br />
==Change Container==<br />
{{note}} available in Mudlet 4.8+<br />
<br />
With this command it is possible to change an elements or even a containers location to that from another container.<br />
For example:<br />
<syntaxhighlight lang="lua"><br />
mycontainerone:changeContainer(mycontainertwo)<br />
--puts container one into container two which means container two will be the parent of container one<br />
</syntaxhighlight><br />
It is also possible to change to a container which is not located on the main window:<br />
<syntaxhighlight lang="lua"><br />
myEmco:changeContainer(emco_userwindow)<br />
--puts my tabbed chat Emco into my userwindow<br />
--to put it back to the main window change to a container located on the main window<br />
myEmco:changeContainer(mymainwindow_container)<br />
--or if it the element wasn't in a container use the main Geyser Root container called Geyser<br />
myEmco:changeContainer(Geyser)<br />
</syntaxhighlight><br />
<br />
==Create Map Window==<br />
{{note}} available in Mudlet 4.8+<br />
<br />
It‘s possible to create the mapper as a map window (similar to clicking the icon) like this:<br />
<syntaxhighlight lang="lua"><br />
myMapWidget = Geyser.Mapper:new({embedded= false})<br />
</syntaxhighlight><br />
<br />
This will open a map window with your saved layout (if there is one, otherwise it will dock at the right corner)<br />
<br />
To choose the position of the DockWindow at creation use: (this will create a map window docked at the left corner)<br />
<br />
<syntaxhighlight lang="lua"><br />
myMapWidget = Geyser.Mapper:new({embedded= false, dockPosition="left"})<br />
</syntaxhighlight><br />
<br />
Possible dockPositions are "left", "right", "top", "bottom", and "floating".<br><br />
To change the dockPosition after creation use:<br />
<br />
<syntaxhighlight lang="lua"><br />
myMapWidget:setDockPosition("floating")<br />
-- this will change myMapWidget dockPosition to floating <br />
</syntaxhighlight><br />
<br />
= Tutorial =<br />
Note: This tutorial assumes you know how scripts in Mudlet work. If not then you should look at the manual first. Also it only shows how Geyser basically works and explains Geysers special windows. It wont go into detail about the windows that where already in Mudlet.<br />
<br />
=== Hello World ===<br />
Let's start with something simple. A Label.<br />
<br />
<syntaxhighlight lang="lua"><br />
Geyser.Label:new({<br />
name="HelloWorld",<br />
x=50, y=50,<br />
width=200, height=50,<br />
})<br />
</syntaxhighlight><br />
<br />
[[Image:Geyser_HW_1.png]]<br />
<br />
This code creates a blank Label with a size of 200x50 at a position of 50 points horizontal and vertical from its parent window - which is the main window since we didn't specify any.<br />
<br />
You can manipulate the Label through the normal functions but Geyser.Label:new() returns an object which can be used to manipulate the label directly. So you should store it:<br />
<br />
<syntaxhighlight lang="lua"><br />
local HelloWorld = Geyser.Label:new({<br />
name="HelloWorld",<br />
x=50, y=50,<br />
width=200, height=50,<br />
})<br />
</syntaxhighlight><br />
<br />
Then you can, for example print a text on it:<br />
<br />
<syntaxhighlight lang="lua"><br />
HelloWorld:echo("Hello World")<br />
</syntaxhighlight><br />
<br />
[[Image:Geyser_HW_2.png]]<br />
<br />
You can put a format parameter so that the text is, for example, centered.<br />
<syntaxhighlight lang="lua"><br />
HelloWorld:echo("Hello World", nil, "c")<br />
</syntaxhighlight><br />
<br />
[[Image:Geyser_HW_3.png]]<br />
<br />
The second parameter is the color. We set it to nil which means the labels foreground color will be used.<br />
<br />
The color parameter either accepts a string ("red"), a hex value("#FF0000" or "0xFF0000" or "|cFF0000"), or a decimal value "&lt;255,0,0&gt;"<br />
<br />
Example:<br />
<syntaxhighlight lang="lua"><br />
HelloWorld:echo("Hello World", "red", "c")<br />
</syntaxhighlight><br />
<br />
[[Image:Geyser_HW_4.png]]<br />
<br />
{{note}} This will automatically set the foreground color, so any echo, without the color parameter set, after that will use the same color.<br />
<br />
You can also set the foreground color with the setFgColor method:<br />
<br />
<syntaxhighlight lang="lua"><br />
HelloWorld:setFgColor("red")<br />
HelloWorld:echo("Hello World", nil, "c")<br />
</syntaxhighlight><br />
<br />
[[Image:Geyser_HW_4.png]]<br />
<br />
=== Containers ===<br />
<br />
Containers are windows that can contain other windows. Actually, since all other Geyser windows subclass container, every window can do that. But containers do not have any visible content by themselves. <br />
<br />
Let's show that by an example:<br />
<syntaxhighlight lang="lua"><br />
local container = Geyser.Container:new({<br />
name="container",<br />
x=50, y=50,<br />
width=250, height=50,<br />
})<br />
</syntaxhighlight><br />
<br />
This will create a container, but if you look at the screen you will see nothing at the positon.<br />
There is a way to make containers visible though:<br />
<syntaxhighlight lang="lua"><br />
container:flash()<br />
</syntaxhighlight><br />
<br />
This will flash the container for a short period of time.<br />
<br />
[[Image:Geyser_Container_1.png]]<br />
<br />
flash() accepts a number as paremeter which defines the time, in seconds, the flash is shown.<br />
<br />
Now, that the container is created, you can add other windows to it. There are 2 ways:<br />
<br />
Directly when creating the window:<br />
<br />
<syntaxhighlight lang="lua"><br />
local container_label = Geyser.Label:new({<br />
name="container_label",<br />
x=0, y=0,<br />
width="100%", height="100%",<br />
},<br />
container)<br />
container_label:echo("This is a label in a container", nil, "c")<br />
</syntaxhighlight><br />
<br />
Later, after the window was created<br />
<syntaxhighlight lang="lua"><br />
local container_label = Geyser.Label:new({<br />
name="container_label",<br />
x=0, y=0,<br />
width="100%", height="100%",<br />
})<br />
container_label:echo("This is a label in a container", nil, "c")<br />
container:add(container_label)<br />
</syntaxhighlight><br />
<br />
Both will lead to the same outcome.<br />
<br />
[[Image:Geyser_Container_2.png]]<br />
<br />
Note that we gave a width and height of "100%" to the constructor of the label. This means that the label will take 100% of the containers width and height. If values are given in percent they will even resize with its parent:<br />
<br />
<syntaxhighlight lang="lua"><br />
container:resize(325, nil)<br />
</syntaxhighlight><br />
<br />
[[Image:Geyser_Container_3.png]]<br />
<br />
The first parameter is the width, the second the height. If the value is nil the current value is used.<br />
<br />
As said in the "Hello World" tutorial the position is relative to its parent window. That's why we could set both x and y to 0 and it is at the position we wanted - the position of the container.<br />
<br />
When we now move the container the label moves with it:<br />
<syntaxhighlight lang="lua"><br />
container:move(400, nil)<br />
</syntaxhighlight><br />
<br />
[[Image:Geyser_Container_4.png]]<br />
<br />
The first parameter is the x-, the second the y-position. If the value is nil the current value is used.<br />
<br />
=== VBox and HBox ===<br />
<br />
The VBox and HBox classes are special Containers.<br />
They will automatically align its containing windows vertically or horizontally, respectively, in the order they where added to them.<br />
<br />
<syntaxhighlight lang="lua"><br />
<br />
local HBox = Geyser.HBox:new({<br />
name="HBox",<br />
x=0, y=0,<br />
width=400, height=30,<br />
})<br />
<br />
</syntaxhighlight><br />
<br />
Like containers you won't see them by themselves.<br />
<br />
Adding children works like with containers<br />
<syntaxhighlight lang="lua"><br />
<br />
local label1 = Geyser.Label:new({<br />
name="Label1",<br />
},<br />
HBox)<br />
label1:echo("Label 1", "black", "c")<br />
label1:setColor(255, 0, 0)<br />
<br />
</syntaxhighlight><br />
<br />
[[Image:HVBox_1.png]]<br />
<br />
We didn't set any position or size, but the label gets the same size as the HBox.<br />
<br />
If we add another window:<br />
<syntaxhighlight lang="lua"><br />
<br />
local label2 = Geyser.Label:new({<br />
name="Label2",<br />
},<br />
HBox)<br />
label2:echo("Label 2", "black", "c")<br />
label2:setColor(0, 255, 0)<br />
<br />
</syntaxhighlight><br />
<br />
[[Image:HVBox_2.png]]<br />
<br />
the size will be divided equally between them!<br />
<br />
What if you want a child that takes more or less space than the others?<br />
That's possible too:<br />
<syntaxhighlight lang="lua"><br />
<br />
local label3 = Geyser.Label:new({<br />
name="Label3",<br />
h_stretch_factor=2.0,<br />
},<br />
HBox)<br />
label3:echo("Label 3", nil, "c")<br />
label3:setColor(0, 0, 255)<br />
<br />
</syntaxhighlight><br />
<br />
[[Image:HVBox_3.png]]<br />
<br />
As you can see, Label 3 takes the same space as Label 1 and 2 Together. <br />
That's because we supplied a horizontal stretch factor with "h_stretch_factor=2.0"<br />
<br />
This works also with a vertical stretch factor, just replace "h_stretch_factor" with "v_stretch_factor"<br />
<br />
Now you may have windows that should not be stretched at all.<br />
To accomplish this you have to set the horizontal and/or vertical policy:<br />
<br />
<syntaxhighlight lang="lua"><br />
<br />
local label4 = Geyser.Label:new({<br />
name="Label4",<br />
width="13%",<br />
h_policy=Geyser.Fixed,<br />
},<br />
HBox)<br />
label4:echo("Label 4", "black", "c")<br />
label4:setColor(0, 255, 255)<br />
<br />
</syntaxhighlight><br />
<br />
[[Image:HVBox_4.png]]<br />
<br />
Possible values for the policies are Geyser.Fixed and Geyser.Dynamic (which is the default). They can also be applied to VBox and HBox in exactly the same way.<br />
<br />
Note that, like in the example above, the label will retain relative values (like percent) if used.<br />
<br />
The VBox works like the HBox, only that the child windows are aligned vertically.<br />
<br />
= Walkthroughs =<br />
Here are a few walkthroughs that will show you how to combine Geyser elements to create some simple GUI widgets.<br />
<br />
===Create a Clickable Compass===<br />
[[File: compass.png]]<br />
The following will walk you through the process of creating your own clickable compass using the Geyser framework.<br />
====Setup the image files====<br />
The compass requires a handful of images to work properly. You can find them here: https://www.dropbox.com/sh/53l7xrn4ds35wnq/WpWOziVKmH <br><br />
Download each image and place it in your profile folder. You can find your profile folder with getMudletHomeDir()<br><br />
If you're using Mudlet 2.1+ you can enter '''lua getMudletHomeDir()''' from the command line to return the profile folder path on your computer.<br />
<br />
====Create a new script====<br />
Script Name: '''''compass.resize'''''<br><br />
Registered Event Handlers: '''''sysWindowResizeEvent'''''<p><br />
Every snippet of code will be placed within this script.<br />
====Store the screen size====<br />
We'll want to store the screen size in some local variables so they can be easily referenced to later on.<br />
<syntaxhighlight lang="lua">local mw, mh = getMainWindowSize()</syntaxhighlight><br />
<br />
====Create a global table or namespace====<br />
Creating a global table will make each of your variables unique. Our namespace will be called '''''compass''''' and everything we make from here on out will be stored within the compass table. We'll also add a few values to it: dirs and ratio. '''''compass.dirs''''' will store each direction while '''''compass.ratio''''' will store the ratio of our screen size so you can 'square up' your compass.<br />
<syntaxhighlight lang="lua">compass = compass or {<br />
dirs = {"nw","n","ne","w","center","e","sw","s","se"},<br />
ratio = mw / mh<br />
}</syntaxhighlight><br />
<br />
====Create the parent label====<br />
[[File: grey.png|thumbnail]]<br />
The 'parent label' refers to the label on the bottom layer. The entire compass will be created within this label. It's container is '''main''' for it's parent is the main window.<br />
<syntaxhighlight lang="lua">compass.back = Geyser.Label:new({<br />
name = "compass.back",<br />
x = "25%",<br />
y = "25%",<br />
width = "10%",<br />
height = "10%",<br />
},main)</syntaxhighlight><br />
<br />
====Set the parent label stylesheet====<br />
[[File: blue.png|thumbnail]]<br />
This will create the blue sphere that makes up most of the compass. The background color is a radial gradient that goes from a deep blue to a brighter shade. The border radius rounds the edges. When the radius is exactly half of the label width it forms a circle. The arrows of the compass actually protrude from the sphere so we give it a margin to suck it in a bit for this effect.<br />
<syntaxhighlight lang="lua">compass.back:setStyleSheet([[<br />
background-color: QRadialGradient(cx:.3,cy:1,radius:1,stop:0 rgb(0,0,50),stop:.5 rgb(0,0,100),stop:1 rgb(0,0,255));<br />
border-radius: ]]..tostring(compass.back:get_width()/2-14)..[[px;<br />
margin: 10px;<br />
]])</syntaxhighlight><br />
<br />
====Create a 3x3 grid====<br />
The compass is split into 9 sections. One for each cardinal direction plus an extra space that sits in the center. This 3x3 grid is created by 3 VBoxes that sit within a single HBox (or vice versa but I flipped a coin and this is what it gave me).<br><br />
So first off, we create the HBox. It will be the same size as its parent, ''compass.back''.<br />
<syntaxhighlight lang="lua"> compass.box = Geyser.HBox:new({<br />
name = "compass.box",<br />
x = 0,<br />
y = 0,<br />
width = "100%",<br />
height = "100%",<br />
},compass.back)</syntaxhighlight><br />
Next, we create our 3 VBoxes. You don't need to specify position or size because these are placed within ''compass.box'', an HBox.<br />
<syntaxhighlight lang="lua"> compass.row1 = Geyser.VBox:new({<br />
name = "compass.row1",<br />
},compass.box)<br />
compass.row2 = Geyser.VBox:new({<br />
name = "compass.row2",<br />
},compass.box)<br />
compass.row3 = Geyser.VBox:new({<br />
name = "compass.row3",<br />
},compass.box)</syntaxhighlight><br />
Finally, we add our 9 labels. Take note that they are split up into even groups of 3. Each group is placed into a different ''compass.row#''<br />
<syntaxhighlight lang="lua"> compass.nw = Geyser.Label:new({<br />
name = "compass.nw",<br />
},compass.row1)<br />
<br />
compass.w = Geyser.Label:new({<br />
name = "compass.w",<br />
},compass.row1)<br />
<br />
compass.sw = Geyser.Label:new({<br />
name = "compass.sw",<br />
},compass.row1)<br />
<br />
compass.n = Geyser.Label:new({<br />
name = "compass.n",<br />
},compass.row2)<br />
<br />
compass.center = Geyser.Label:new({<br />
name = "compass.center",<br />
},compass.row2)<br />
<br />
compass.s = Geyser.Label:new({<br />
name = "compass.s",<br />
},compass.row2)<br />
<br />
compass.ne = Geyser.Label:new({<br />
name = "compass.ne",<br />
},compass.row3)<br />
<br />
compass.e = Geyser.Label:new({<br />
name = "compass.e",<br />
},compass.row3)<br />
<br />
compass.se = Geyser.Label:new({<br />
name = "compass.se",<br />
},compass.row3)</syntaxhighlight><br />
====Create a callback function====<br />
We'll want our compass to head in the direction of the arrow we're clicking. This is where we specify so. When the arrow is clicked, this function will be ran with the arrow direction as the argument.<br />
<syntaxhighlight lang="lua">function compass.click(name)<br />
send(name)<br />
end</syntaxhighlight><br />
====Create the hover functions====<br />
We want our arrows to turn yellow when we hover over them. We do so by simply resetting the label's stylesheet and changing the border image. Don't forget to include the margin as we still want that.<br />
<syntaxhighlight lang="lua">function compass.onEnter(name)<br />
compass[name]:setStyleSheet([[<br />
border-image: url("]]..getMudletHomeDir()..[[/]]..name..[[hover.png");<br />
margin: 5px;<br />
]])<br />
end<br />
<br />
function compass.onLeave(name)<br />
compass[name]:setStyleSheet([[<br />
border-image: url("]]..getMudletHomeDir()..[[/]]..name..[[.png");<br />
margin: 5px;<br />
]])<br />
end</syntaxhighlight><br />
====Set the stylesheets in the grid====<br />
[[File: Sample.png|thumb]]<br />
Each of the 9 labels need an image of an arrow. Rather than setting each individually, we'll iterate over the ''compass.dirs'' table we made awhile back and add the respective image to each. The names of images are a reflection of the ''compass.dirs'' table. This keeps it consistent and easy to refer to. During the iteration, the callback, setLabelOnEnter and setLabelOnLeave are also set for each label.<br />
<syntaxhighlight lang="lua">for k,v in pairs(compass.dirs) do<br />
compass[v]:setStyleSheet([[<br />
border-image: url("]]..getMudletHomeDir()..[[/]]..v..[[.png");<br />
margin: 5px;<br />
]])<br />
compass[v]:setClickCallback("compass.click",v)<br />
setLabelOnEnter("compass."..v,"compass.onEnter",v)<br />
setLabelOnLeave("compass."..v,"compass.onLeave",v)<br />
end</syntaxhighlight><br />
<br />
====Resize the compass into a square====<br />
[[File: final.png|thumb]]<br />
Most screen size ratios aren't a perfect 1:1. This will cause a 10% x 10% label to be far from square. By setting our height (the smaller of the two numbers) to our width, we can resize our compass to a near perfect square. This function is also the name of our script because we want it to run each time sysWindowResizeEvent is raised.<br />
<syntaxhighlight lang="lua">function compass.resize()<br />
compass.back:resize(compass.back.width, compass.back:get_width())<br />
end<br />
<br />
compass.resize()</syntaxhighlight><br />
<br />
===Create a Tabbed Window===<br />
[[File: tabwindow.png]]<br />
The following will walk you through the process of creating your own tabbed window using the Geyser framework.<br />
<br />
====Create a new script====<br />
Script Name: '''''Tabbed Window'''''<br><br />
Every snippet of code will be placed within this script.<br />
====Create a global table====<br />
Creating a global table will make each of your variables unique. Our namespace will be called '''''menu''''' and everything we make from here on out will be stored within the menu table. We'll also add a few values to it: tabs, color1, color2, width, height and current. <br><br />
''''tabs'''' will be a table that stores all our tab names. If we want our tabs to have different names, we alter this table.<br><br />
''''color1'''' and ''''color2'''' will store the colors of our tabbed window. If we want to change the color of our tabbed window, we alter these values.<br><br />
''''width'''' and ''''height'''' will store the size of our tabbed window. If we want to change the size of the tabbed window, we alter these values.<br><br />
''''current'''' keeps track of which tab is selected. We will set this to the first tab in the table by default. We do this outside the initial table creation so we can easily access menu.tabs<br><br />
<syntaxhighlight lang="lua">menu = menu or {<br />
tabs = {"Tab1","Tab2","Tab3","Tab4"},<br />
color1 = "rgb(0,0,70)",<br />
color2 = "rgb(0,0,50)",<br />
width = "20%",<br />
height = "40%",<br />
}<br />
menu.current = menu.current or menu.tabs[1]</syntaxhighlight><br />
<br />
====Create the main container====<br />
Our tabbed window will need a container. This will be the bottom layer. Containers are invisible so no need to set a stylesheet.<br />
<syntaxhighlight lang="lua">menu.container = Geyser.Container:new({<br />
name = "menu.back",<br />
x = "50%", y = "25%",<br />
width = menu.width,<br />
height = menu.height,<br />
},main)</syntaxhighlight><br />
====Create an HBox====<br />
All of our tabs will be evenly spaced. So we'll create an HBox to sit at the top of our container.<br />
<syntaxhighlight lang="lua">menu.header = Geyser.HBox:new({<br />
name = "menu.header",<br />
x = 0, y = 0,<br />
width = "100%",<br />
height = "10%",<br />
},menu.container)</syntaxhighlight><br />
====Create a label====<br />
This label will serve as a container for each window. It sits right underneath the HBox we just created for the tabs.<br />
<syntaxhighlight lang="lua">menu.footer = Geyser.Label:new({<br />
name = "menu.footer",<br />
x = 0, y = "10%",<br />
width = "100%",<br />
height = "90%",<br />
},menu.container)</syntaxhighlight><br />
We don't want this to be a big grey box at startup, so we'll set the stylesheet to appear like the rest of the windows.<br />
<syntaxhighlight lang="lua"><br />
menu.footer:setStyleSheet([[<br />
background-color: ]]..menu.color1..[[;<br />
border-bottom-left-radius: 10px;<br />
border-bottom-right-radius: 10px;<br />
]])</syntaxhighlight><br />
Each window actually has two labels. One for the light blue background, and another for the dark blue center. This will create that dark blue center.<br />
<syntaxhighlight lang="lua">menu.center = Geyser.Label:new({<br />
name = "menu.center",<br />
x = 0, y = 0,<br />
width = "100%",<br />
height = "100%",<br />
},menu.footer)<br />
menu.center:setStyleSheet([[<br />
background-color: ]]..menu.color2..[[;<br />
border-radius: 10px;<br />
margin: 5px;<br />
]])</syntaxhighlight><br />
====Add your tabs and their windows====<br />
Now we'll want to add our tabs and windows. We do this in a single for loop of the ''''menu.tabs'''' table since it holds all our tab names.<br />
<syntaxhighlight lang="lua">for k,v in pairs(menu.tabs) do<br />
</syntaxhighlight><br />
This will create the tabs. Each tab will be named: menu.<tabname>tab<br />
<syntaxhighlight lang="lua"><br />
menu[v.."tab"] = Geyser.Label:new({<br />
name = "menu."..v.."tab",<br />
},menu.header)<br />
</syntaxhighlight><br />
Here is where we set the tab stylesheet. Each tab has a rounded top, so we set the border-radius of the top-left and top-right to 10px. Each tab has a small space for separation so we give the right and left sides a tiny margin of 1px.<br />
<syntaxhighlight lang="lua"><br />
menu[v.."tab"]:setStyleSheet([[<br />
background-color: ]]..menu.color1..[[;<br />
border-top-left-radius: 10px;<br />
border-top-right-radius: 10px;<br />
margin-right: 1px;<br />
margin-left: 1px;<br />
]])<br />
</syntaxhighlight><br />
This will display the name of each tab on the tab.<br />
<syntaxhighlight lang="lua"><br />
menu[v.."tab"]:echo("<center>"..v)<br />
</syntaxhighlight><br />
We need our tabs to do stuff when clicked, so we'll assign it a callback function, '''''menu.click''''', which we'll create later on. Our tab name is the argument.<br />
<syntaxhighlight lang="lua"><br />
menu[v.."tab"]:setClickCallback("menu.click",v)<br />
</syntaxhighlight><br />
Now we create the windows that appear when each tab is clicked. Each window has two labels, one atop the other. The first, which we'll create here, has rounded edges on its bottom.<br />
<syntaxhighlight lang="lua"><br />
menu[v] = Geyser.Label:new({<br />
name = "menu."..v,<br />
x = 0, y = 0,<br />
width = "100%",<br />
height = "100%",<br />
},menu.footer)<br />
<br />
menu[v]:setStyleSheet([[<br />
background-color: ]]..menu.color1..[[;<br />
border-bottom-left-radius: 10px;<br />
border-bottom-right-radius: 10px;<br />
]])<br />
</syntaxhighlight><br />
The second label serves as the window's center and has rounded edges on all sides. And a margin of 5px from it's parent, the label we just created. When adding stuff to your windows, this is the label you'll want to use. '''''menu.<tabname>center'''''<br />
<syntaxhighlight lang="lua"><br />
menu[v.."center"] = Geyser.Label:new({<br />
name = "menu."..v.."center",<br />
x = 0, y = 0,<br />
width = "100%",<br />
height = "100%",<br />
},menu[v])<br />
</syntaxhighlight><syntaxhighlight lang="lua"><br />
menu[v.."center"]:setStyleSheet([[<br />
background-color: ]]..menu.color2..[[;<br />
border-radius: 10px;<br />
margin: 5px;<br />
]])<br />
</syntaxhighlight><br />
Finally, we hide all the windows and end the for loop.<br />
<syntaxhighlight lang="lua"><br />
menu[v]:hide()<br />
end</syntaxhighlight><br />
====Create a callback function====<br />
The last step is to create our callback function for when a tab is clicked. This will hide that tab that is stored in '''''menu.current''''', set menu.current to the clicked tab, and then show the menu.current tab.<br />
<syntaxhighlight lang="lua">function menu.click(tab)<br />
menu[menu.current]:hide()<br />
menu.current = tab<br />
menu[menu.current]:show()<br />
end</syntaxhighlight><br />
====Adding content to your windows====<br />
Add content to '''menu.<tab name>center'''<br />
So if we wanted to display our gold in a window we could:<syntaxhighlight lang="lua">menu.Tab1center:echo(myGold)</syntaxhighlight><br />
If we wanted to add a map to a window we could:<br />
<syntaxhighlight lang="lua">myMap = Geyser.Mapper:new({<br />
name = "myMap",<br />
x = 0, y = 0,<br />
width = "100%",<br />
height = "100%",<br />
},menu.Tab2center)</syntaxhighlight><br />
<br />
===Create a Window with a resize label===<br />
<br />
Previous tutorial is now done much simpler [[Manual:Geyser#Adjustable.Container|Adjustable containers]], have a look at those instead.<br />
<br />
[[Category:Mudlet Manual]]</div>Demonnichttps://wiki.mudlet.org/index.php?title=Area_51&diff=19775Area 512022-01-21T03:08:44Z<p>Demonnic: /* String Functions */</p>
<hr />
<div>{{TOC right}}<br />
<br />
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 [[Manual:Lua_Functions|Lua Functions]] and its sub-sites. <br />
<br />
Please use the [[Area_51/Template]] to add new entries in the sections below.<br />
<br />
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.<br />
<br />
<br />
=Basic Essential Functions=<br />
:These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.<br />
<br />
=Database Functions=<br />
:A collection of functions for helping deal with the database.<br />
<br />
=Date/Time Functions=<br />
: A collection of functions for handling date & time.<br />
<br />
=File System Functions=<br />
: A collection of functions for interacting with the file system.<br />
<br />
=Mapper Functions=<br />
: A collection of functions that manipulate the mapper and its related features.<br />
<br />
==mapSymbolFontInfo, PR #4038 closed==<br />
;mapSymbolFontInfo()<br />
: See also: [[#setupMapSymbolFont|setupMapSymbolFont()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;returns<br />
* either a table of information about the configuration of the font used for symbols in the (2D) map, the elements are:<br />
:* ''fontName'' - a string of the family name of the font specified<br />
:* ''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.<br />
:* ''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).<br />
* or ''nil'' and an error message on failure.<br />
<br />
::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).<br />
<br />
<br />
==setupMapSymbolFont, PR #4038 closed==<br />
;setupMapSymbolFont(fontName[, onlyUseThisFont[, scalingFactor]])<br />
:configures the font used for symbols in the (2D) map.<br />
: See also: [[#mapSymbolFontInfo|mapSymbolFontInfo()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;Parameters<br />
* ''fontName'' one of:<br />
:* - a string that is the family name of the font to use;<br />
:* - the empty string ''""'' to reset to the default {which is '''"Bitstream Vera Sans Mono"'''};<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow a following one to be modified.<br />
* ''onlyUseThisFont'' (optional) one of:<br />
:* - 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;<br />
:* - 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;<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow the following one to be modified.<br />
* ''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.<br />
<br />
;Returns<br />
* ''true'' on success<br />
* ''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).<br />
<br />
=Miscellaneous Functions=<br />
: Miscellaneous functions.<br />
<br />
==getCharacterName, PR #3952 open==<br />
;getCharacterName()<br />
<br />
: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.<br />
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.<br />
<br />
:See also: [[#sendCharacterName|sendCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lua send("cast 'glamor' " .. getCharacterName())<br />
<br />
You get a warm feeling passing from your core to the tips of your hands, feet and other body parts.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A tawny long-haired cat saunters over and start to rub itself against your ankles.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A mangy dog trots up to you and proceeds to mark the bottom of your leggings.<br />
</syntaxhighlight><br />
<br />
==getCustomLoginTextId, PR #3952 open==<br />
;getCustomLoginTextId()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#sendPassword|sendPassword()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==loadMusicFile, PR #5799 merged ==<br />
;loadMusicFile(settings table)<br />
: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. <br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! style="text-align:left;"| Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;"| Yes<br />
| name<br />
| <file name><br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
* May contain directory information (i.e. weather/lightning.wav).<br />
* May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")<br />
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")<br />
|- style="color: blue;"<br />
| style="text-align:center;"| Maybe<br />
| url<br />
| <url><br />
| style="text-align:left;"|<br />
* Resource location where the media file may be downloaded.<br />
* Only required if file to load is not part of the profile or on the local file system.<br />
|-<br />
|}<br />
<br />
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]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Download from the Internet<br />
loadMusicFile({<br />
name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
, url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"<br />
})<br />
<br />
-- OR download from the profile<br />
loadMusicFile({name = getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3"})<br />
<br />
-- OR download from the local file system<br />
loadMusicFile({name = "C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3"})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of loadMediaFile(name[, url]) ----<br />
<br />
-- Download from the Internet<br />
loadMusicFile(<br />
"167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
, "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"<br />
)<br />
<br />
-- OR download from the profile<br />
loadMusicFile(getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3")<br />
<br />
-- OR download from the local file system<br />
loadMusicFile("C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3")<br />
</syntaxhighlight><br />
<br />
==loadSoundFile, PR #5799 merged ==<br />
;loadSoundFile(settings table)<br />
: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. <br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! style="text-align:left;"| Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;"| Yes<br />
| name<br />
| <file name><br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
* May contain directory information (i.e. weather/lightning.wav).<br />
* May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")<br />
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")<br />
|- style="color: blue;"<br />
| style="text-align:center;"| Maybe<br />
| url<br />
| <url><br />
| style="text-align:left;"|<br />
* Resource location where the media file may be downloaded.<br />
* Only required if file to load is not part of the profile or on the local file system.<br />
|-<br />
|}<br />
<br />
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]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Download from the Internet<br />
loadSoundFile({<br />
name = "cow.wav"<br />
, url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"<br />
})<br />
<br />
-- OR download from the profile<br />
loadSoundFile({name = getMudletHomeDir().. "/cow.wav"})<br />
<br />
-- OR download from the local file system<br />
loadSoundFile({name = "C:/Users/Tamarindo/Documents/cow.wav"})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of loadSoundFile(name[,url]) ----<br />
<br />
-- Download from the Internet<br />
loadSoundFile("cow.wav", "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/")<br />
<br />
-- OR download from the profile<br />
loadSoundFile(getMudletHomeDir().. "/cow.wav")<br />
<br />
-- OR download from the local file system<br />
loadSoundFile("C:/Users/Tamarindo/Documents/cow.wav")<br />
</syntaxhighlight><br />
<br />
==playMusicFile, PR #5799 merged ==<br />
;playMusicFile(settings table)<br />
: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()]].<br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! Default<br />
! style="text-align:left;"| Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;"| Yes<br />
| name<br />
| <file name><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
* May contain directory information (i.e. weather/lightning.wav).<br />
* May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")<br />
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")<br />
* Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.<br />
|-<br />
| style="text-align:center;"| No<br />
| volume<br />
| 1 to 100<br />
| 50<br />
| style="text-align:left;"|<br />
* Relative to the volume set on the player's client.<br />
|-<br />
| style="text-align:center;"| No<br />
| fadein<br />
|<msec><br />
|<br />
|<br />
*Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.<br />
*Start position: Start of media.<br />
*End position: Start of media plus the number of milliseconds (msec) specified.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
| fadeout<br />
|<msec><br />
|<br />
|<br />
*Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.<br />
*Start position: End of the media minus the number of milliseconds (msec) specified.<br />
*End position: End of the media.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;"| No<br />
| start<br />
| <msec><br />
| 0<br />
| style="text-align:left;"|<br />
* Begin play at the specified position in milliseconds.<br />
|-<br />
| style="text-align:center;" |No<br />
| loops<br />
| -1, or >= 1<br />
|1<br />
| style="text-align:left;" |<br />
*Number of iterations that the media plays.<br />
* A value of -1 allows the media to loop indefinitely.<br />
|-<br />
| style="text-align:center;" |No<br />
| key <br />
|<key><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;"| No<br />
| tag<br />
| <tag><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Helps categorize media.<br />
|-<br />
| style="text-align:center;" |No<br />
| continue <br />
| true or false<br />
| true<br />
| style="text-align:left;" |<br />
*Continues playing matching new music files when true.<br />
*Restarts matching new music files when false.<br />
|- style="color: blue;"<br />
| style="text-align:center;"| Maybe<br />
| url<br />
| <url><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Resource location where the media file may be downloaded.<br />
* Only required if the file is to be downloaded remotely.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Play a music file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playMusicFile({<br />
name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
})<br />
<br />
-- OR copy once from the game's profile, and play a music file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playMusicFile({<br />
name = getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
, volume = 75<br />
})<br />
<br />
-- OR copy once from the local file system, and play a music file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playMusicFile({<br />
name = "C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
, volume = 75<br />
})<br />
<br />
-- OR download once from the Internet, and play music stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 20 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 53 seconds from the end of the music<br />
---- [start] 10 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [key] reference of "rugby" for stopping this unique music later<br />
---- [tag] reference of "ambience" to stop and music later with the same tag<br />
---- [continue] playing this music if another request for the same music comes in (false restarts it) <br />
---- [url] to download once from the Internet if the music does not exist in the profile's media directory<br />
playMusicFile({<br />
name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"<br />
, volume = nil -- nil lines are optional, no need to use<br />
, fadein = 20000<br />
, fadein = 53000<br />
, start = 10000<br />
, loops = nil -- nil lines are optional, no need to use<br />
, key = "rugby"<br />
, tag = "ambience"<br />
, continue = true<br />
, url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of playMusicFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,continue][,url]) ----<br />
<br />
-- Play a music file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playMusicFile(<br />
"167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name<br />
)<br />
<br />
-- OR copy once from the game's profile, and play a music file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playMusicFile(<br />
getMudletHomeDir().. "/167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR copy once from the local file system, and play a music file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playMusicFile(<br />
"C:/Users/Tamarindo/Documents/167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR download once from the Internet, and play music stored in the profile's media directory<br />
---- [fadein] and increase the volume from 1 at the start position to default volume up until the position of 20 seconds<br />
---- [fadeout] and decrease the volume from default volume to one, 53 seconds from the end of the music<br />
---- [start] 10 seconds after position 0 (fadein scales its volume increase over a shorter duration, too)<br />
---- [key] reference of "rugby" for stopping this unique music later<br />
---- [tag] reference of "ambience" to stop and music later with the same tag<br />
---- [continue] playing this music if another request for the same music comes in (false restarts it) <br />
---- [url] to download once from the Internet if the music does not exist in the profile's media directory<br />
playMusicFile(<br />
"167124__patricia-mcmillen__rugby-club-in-spain.mp3" -- name<br />
, nil -- volume<br />
, 20000 -- fadein<br />
, 53000 -- fadeout<br />
, 10000 -- start<br />
, nil -- loops<br />
, "rugby" -- key <br />
, "ambience" -- tag<br />
, true -- continue<br />
, "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/" -- url<br />
)<br />
</syntaxhighlight><br />
<br />
==playSoundFile, PR #5799 merged ==<br />
;playSoundFile(settings table)<br />
: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()]].<br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! Default<br />
! style="text-align:left;"| Purpose<br />
|- style="color: green;"<br />
| style="text-align:center;"| Yes<br />
| name<br />
| <file name><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
* May contain directory information (i.e. weather/lightning.wav).<br />
* May be part of the profile (i.e. getMudletHomeDir().. "/cow.mp3")<br />
* May be on the local device (i.e. "C:/Users/YourNameHere/Documents/nevergoingtogiveyouup.mp3")<br />
* Wildcards ''*'' and ''?'' may be used within the name to randomize media files selection.<br />
|-<br />
| style="text-align:center;"| No<br />
| volume<br />
| 1 to 100<br />
| 50<br />
| style="text-align:left;"|<br />
* Relative to the volume set on the player's client.<br />
|-<br />
| style="text-align:center;"| No<br />
| fadein<br />
|<msec><br />
|<br />
|<br />
*Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key.<br />
*Start position: Start of media.<br />
*End position: Start of media plus the number of milliseconds (msec) specified.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;" |No<br />
| fadeout<br />
|<msec><br />
|<br />
|<br />
*Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one.<br />
*Start position: End of the media minus the number of milliseconds (msec) specified.<br />
*End position: End of the media.<br />
*1000 milliseconds = 1 second.<br />
|-<br />
| style="text-align:center;"| No<br />
| start<br />
| <msec><br />
| 0<br />
| style="text-align:left;"|<br />
* Begin play at the specified position in milliseconds.<br />
|-<br />
| style="text-align:center;" |No<br />
| loops<br />
| -1, or >= 1<br />
|1<br />
| style="text-align:left;" |<br />
*Number of iterations that the media plays.<br />
* A value of -1 allows the media to loop indefinitely.<br />
|-<br />
| style="text-align:center;" |No<br />
| key <br />
|<key><br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;"| No<br />
| tag<br />
| <tag><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Helps categorize media.<br />
|-<br />
| style="text-align:center;" |No<br />
| priority<br />
| 1 to 100<br />
|&nbsp;<br />
| style="text-align:left;" |<br />
*Halts the play of current or future played media files with a lower priority while this media plays.<br />
|- style="color: blue;"<br />
| style="text-align:center;"| Maybe<br />
| url<br />
| <url><br />
| &nbsp;<br />
| style="text-align:left;"|<br />
* Resource location where the media file may be downloaded.<br />
* Only required if the file is to be downloaded remotely.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Play a sound file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playSoundFile({<br />
name = "cow.wav"<br />
})<br />
<br />
-- OR copy once from the game's profile, and play a sound file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playSoundFile({<br />
name = getMudletHomeDir().. "/cow.wav"<br />
, volume = 75<br />
})<br />
<br />
-- OR copy once from the local file system, and play a sound file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playSoundFile({<br />
name = "C:/Users/Tamarindo/Documents/cow.wav"<br />
, volume = 75<br />
})<br />
<br />
-- OR download once from the Internet, and play a sound stored in the profile's media directory<br />
---- [volume] of 75<br />
---- [loops] of 2 (-1 for indefinite repeats, 1+ for finite repeats)<br />
---- [key] reference of "cow" for stopping this unique sound later<br />
---- [tag] reference of "animals" to stop a group of sounds later with the same tag<br />
---- [priority] of 25 (1 to 100, 50 default, a sound with a higher priority would stop this one)<br />
---- [url] to download once from the Internet if the sound does not exist in the profile's media directory<br />
playSoundFile({<br />
name = "cow.wav"<br />
, volume = 75<br />
, fadein = nil -- nil lines are optional, no need to use<br />
, fadeout = nil -- nil lines are optional, no need to use<br />
, start = nil -- nil lines are optional, no need to use<br />
, loops = 2<br />
, key = "cow"<br />
, tag = "animals"<br />
, priority = 25<br />
, url = "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/"<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of playSoundFile(name[,volume][,fadein][,fadeout][,loops][,key][,tag][,priority][,url]) ----<br />
<br />
-- Play a sound file stored in the profile's media directory (i.e. /Users/Tamarindo/mudlet-data/profiles/StickMUD/media)<br />
playSoundFile(<br />
"cow.wav" -- name<br />
)<br />
<br />
-- OR copy once from the game's profile, and play a sound file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playSoundFile(<br />
getMudletHomeDir().. "/cow.wav" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR copy once from the local file system, and play a sound file stored in the profile's media directory<br />
---- [volume] of 75 (1 to 100)<br />
playSoundFile(<br />
"C:/Users/Tamarindo/Documents/cow.wav" -- name<br />
, 75 -- volume<br />
)<br />
<br />
-- OR download once from the Internet, and play a sound stored in the profile's media directory<br />
---- [volume] of 75<br />
---- [loops] of 2 (-1 for indefinite repeats, 1+ for finite repeats)<br />
---- [key] reference of "cow" for stopping this unique sound later<br />
---- [tag] reference of "animals" to stop a group of sounds later with the same tag<br />
---- [priority] of 25 (1 to 100, 50 default, a sound with a higher priority would stop this one)<br />
---- [url] to download once from the Internet if the sound does not exist in the profile's media directory<br />
playSoundFile(<br />
"cow.wav" -- name<br />
, 75 -- volume<br />
, nil -- fadein<br />
, nil -- fadeout<br />
, nil -- start<br />
, 2 -- loops<br />
, "cow" -- key <br />
, "animals" -- tag<br />
, 25 -- priority<br />
, "https://raw.githubusercontent.com/StickMUD/StickMUDSounds/master/sounds/" -- url<br />
)<br />
</syntaxhighlight><br />
<br />
==sendCharacterName, PR #3952 open ==<br />
;sendCharacterName()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
==sendCharacterPassword, PR #3952 open==<br />
;sendCharacterPassword()<br />
<br />
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.<br />
<br />
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.<br />
: See also: [[#getCharacterName|getCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]], [[#sendCharacterName|sendCharacterName()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCharacterName() ~= "" then<br />
tempTime(2.0, [[sendCharacterName()]], 1)<br />
tempTime(3.0, [[sendCharacterPassword()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
== sendCustomLoginText, PR #3952 open ==<br />
;sendCustomLoginText()<br />
<br />
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.<br />
<br />
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.<br />
: See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendPassword|sendPassword()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+Predefined custom login texts<br />
|-<br />
!Id!!Custom text!! Introduced in Mudlet version<br />
|-<br />
|1||"connect {character name} {password}"||TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==stopMusic, PR #5799 merged ==<br />
;stopMusic(settings table)<br />
: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()]].<br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! style="text-align:left;"| Purpose<br />
|-<br />
| style="text-align:center;"| No<br />
| name<br />
| <file name><br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
|-<br />
| style="text-align:center;" |No<br />
| key <br />
|<key><br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;"| No<br />
| tag<br />
| <tag><br />
| style="text-align:left;"|<br />
* Helps categorize media.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#stopSounds|stopSounds()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stop all playing music files for this profile associated with the API<br />
stopMusic()<br />
<br />
-- Stop playing the rugby mp3 by name<br />
stopMusic({name = "167124__patricia-mcmillen__rugby-club-in-spain.mp3"})<br />
<br />
-- Stop playing the unique sound identified as "rugby"<br />
stopMusic({<br />
name = nil -- nil lines are optional, no need to use<br />
, key = "rugby" -- key<br />
, tag = nil -- nil lines are optional, no need to use<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of stopMusic([name][,key][,tag]) ----<br />
<br />
-- Stop all playing music files for this profile associated with the API<br />
stopMusic()<br />
<br />
-- Stop playing the rugby mp3 by name<br />
stopMusic("167124__patricia-mcmillen__rugby-club-in-spain.mp3")<br />
<br />
-- Stop playing the unique sound identified as "rugby"<br />
stopMusic(<br />
nil -- name<br />
, "rugby" -- key<br />
, nil -- tag<br />
)<br />
</syntaxhighlight><br />
<br />
==stopSounds, PR #5799 merged ==<br />
;stopSounds(settings table)<br />
: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()]].<br />
<br />
{| class="wikitable"<br />
! Required<br />
! Key<br />
! Value<br />
! style="text-align:left;"| Purpose<br />
|-<br />
| style="text-align:center;"| No<br />
| name<br />
| <file name><br />
| style="text-align:left;"|<br />
* Name of the media file.<br />
|-<br />
| style="text-align:center;" |No<br />
| key <br />
|<key><br />
| style="text-align:left;" |<br />
*Uniquely identifies media files with a "key" that is bound to their "name" or "url".<br />
*Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.<br />
|-<br />
| style="text-align:center;"| No<br />
| tag<br />
| <tag><br />
| style="text-align:left;"|<br />
* Helps categorize media.<br />
|-<br />
| style="text-align:center;" |No<br />
| priority<br />
| 1 to 100<br />
| style="text-align:left;" |<br />
*Halts the play of current or future played media files with a matching or lower priority.<br />
|-<br />
|}<br />
<br />
See also: [[Manual:Miscellaneous_Functions#loadMusicFile|loadMusicFile()]], [[Manual:Miscellaneous_Functions#loadSoundFile|loadSoundFile()]], [[Manual:Miscellaneous_Functions#playMusicFile|playMusicFile()]], [[Manual:Miscellaneous_Functions#playSoundFile|playSoundFile()]], [[Manual:Miscellaneous_Functions#stopMusic|stopMusic()]], [[Manual:Miscellaneous_Functions#purgeMediaCache|purgeMediaCache()]], [[Manual:Scripting#MUD_Client_Media_Protocol|Mud Client Media Protocol]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
---- Table Parameter Syntax ----<br />
<br />
-- Stop all playing sound files for this profile associated with the API<br />
stopSounds()<br />
<br />
-- Stop playing the cow sound<br />
stopSounds({name = "cow.wav"})<br />
<br />
-- Stop playing any sounds tagged as "animals" with a priority less than or equal to 50<br />
---- This would not stop sounds tagged as "animals" greater than priority 50. This is an "AND" and not an "OR".<br />
stopSounds({<br />
name = nil -- nil lines are optional, no need to use<br />
, key = nil -- nil lines are optional, no need to use<br />
, tag = "animals"<br />
, priority = 50<br />
})<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
---- Ordered Parameter Syntax of stopSounds([name][,key][,tag][,priority]) ----<br />
<br />
-- Stop all playing sound files for this profile associated with the API<br />
stopSounds()<br />
<br />
-- Stop playing the cow sound<br />
stopSounds("cow.wav")<br />
<br />
-- Stop playing any sounds tagged as "animals" with a priority less than or equal to 50<br />
---- This would not stop sounds tagged as "animals" greater than priority 50. This is an "AND" and not an "OR".<br />
stopSounds(<br />
nil -- name<br />
, nil -- key<br />
, "animals" -- tag<br />
, 50 -- priority<br />
)<br />
</syntaxhighlight><br />
<br />
=Mudlet Object Functions=<br />
:A collection of functions that manipulate Mudlets scripting objects - triggers, aliases, and so forth.<br />
<br />
== getProfileStats PR 5706 ==<br />
;getProfileStats()<br />
<br />
:Returns a table with profile statistics for how many triggers, aliases, keys, timers, and scripts the profile has. Similar to the Statistics button in the script editor, accessible to Lua scripting.<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- show all stats<br />
display(getProfileStats())<br />
<br />
-- check how many active triggers there are<br />
activetriggers = getProfileStats().triggers.active<br />
cecho(f"<PaleGreen>We have <SlateGrey>{activetriggers}<PaleGreen> active triggers!\n")<br />
</syntaxhighlight><br />
<br />
=Networking Functions=<br />
:A collection of functions for managing networking.<br />
<br />
=String Functions=<br />
:These functions are used to manipulate strings.<br />
<br />
==cecho2string, PR#5881 merged==<br />
; plainText = cecho2string(formattedText)<br />
<br />
:Strips the text formatting from the string passed in, leaving behind only the text.<br />
<br />
;See also: [[Manual:Lua_Functions#ansi2string|ansi2string()]], [[Manual:Lua_Functions#hecho2string|hecho2string()]]<br />
<br />
{{MudletVersion|4.16}}<br />
<br />
;Parameters<br />
* ''formattedText:''<br />
: The string you want to strip the formatting codes from<br />
<br />
;Returns <br />
* The string with the formatting codes stripped out.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local exampleString = "<red>Formatted <b>string</b>"<br />
local plainText = cecho2string(exampleString)<br />
-- "Formatted string"<br />
</syntaxhighlight><br />
<br />
==decho2string, PR#5881 merged==<br />
; plainText = decho2string(formattedText)<br />
<br />
:Strips the text formatting from the string passed in, leaving behind only the text.<br />
<br />
;See also: [[Manual:Lua_Functions#ansi2string|ansi2string()]], [[Manual:Lua_Functions#cecho2string|cecho2string()]]<br />
<br />
{{MudletVersion|4.16}}<br />
<br />
;Parameters<br />
* ''formattedText:''<br />
: The string you want to strip the formatting codes from<br />
<br />
;Returns <br />
* The string with the formatting codes stripped out.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local exampleString = "<255,0,0>Formatted <b>string</b>"<br />
local plainText = decho2string(exampleString)<br />
-- "Formatted string"<br />
</syntaxhighlight><br />
<br />
==hecho2string, PR#5881 merged==<br />
; plainText = hecho2string(formattedText)<br />
<br />
:Strips the text formatting from the string passed in, leaving behind only the text.<br />
<br />
;See also: [[Manual:Lua_Functions#ansi2string|ansi2string()]], [[Manual:Lua_Functions#decho2string|decho2string()]]<br />
<br />
{{MudletVersion|4.16}}<br />
<br />
;Parameters<br />
* ''formattedText:''<br />
: The string you want to strip the formatting codes from<br />
<br />
;Returns <br />
* The string with the formatting codes stripped out.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local exampleString = "#ff0000Formatted #bstring#/b"<br />
local plainText = cecho2string(exampleString)<br />
-- "Formatted string"<br />
</syntaxhighlight><br />
<br />
== string.patternEscape, utf8.patternEscape PR 5806==<br />
;escapedString = string.patternEscape(str) or escapedString = utf8.patternEscape(str)<br />
<br />
:Returns a version of str with all Lua pattern characters escaped to ensure string.match/find/etc look for the original str.<br />
<br />
;See also:[[Manual:Lua_Functions#string.trim|string.trim()]], [[Manual:Lua_Functions#string.genNocasePattern|string.genNocasePattern()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
*''str:''<br />
:The string to escape lua pattern characters in.<br />
<br />
;Returns<br />
*The string with all special Lua pattern characters escaped.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- searching for a url inside of a string. <br />
local helpString = [[<br />
This feature can be accessed by going to https://some-url.com/athing.html?param=value and<br />
retrieving the result!<br />
]]<br />
local url = "https://some-url.com/"<br />
display(helpString:find(url))<br />
-- nil<br />
display(helpString:find(string.patternEscape(url)))<br />
-- 42<br />
-- 62<br />
display(url:patternEscape())<br />
-- "https://some%-url%.com/"<br />
</syntaxhighlight><br />
<br />
=Table Functions=<br />
: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.<br />
<br />
=Text to Speech Functions =<br />
:These functions are used to create sound from written words. Check out our [[Special:MyLanguage/Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.<br />
<br />
=UI Functions=<br />
: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.<br />
<br />
==ansi2decho PR# 5670 merge, PR5719 merged==<br />
;ansi2decho(text, default_colour)<br />
:Converts ANSI colour sequences in <code>text</code> to colour tags that can be processed by the decho() function.<br />
:See also: [[Manual:Lua_Functions#decho|decho()]]<br />
<br />
{{MudletVersion|3.0}}<br />
{{note}} ANSI bold is available since Mudlet 3.7.1+.<br />
<br />
{{note}} underline, italics, overline, and strikethrough supported since Mudlet 4.15+<br />
<br />
;Parameters<br />
*''text:''<br />
:String that contains ANSI colour sequences that should be replaced.<br />
*''default_colour:''<br />
:Optional - ANSI default colour code (used when handling orphan bold tags).<br />
<br />
; Return values<br />
*''string text:''<br />
:The decho-valid converted text.<br />
*''string colour:''<br />
:The ANSI code for the last used colour in the substitution (useful if you want to colour subsequent lines according to this colour).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local replaced = ansi2decho('\27[0;1;36;40mYou say in a baritone voice, "Test."\27[0;37;40m')<br />
-- 'replaced' should now contain <r><0,255,255:0,0,0>You say in a baritone voice, "Test."<r><192,192,192:0,0,0><br />
decho(replaced)<br />
</syntaxhighlight><br />
<br />
Or show a complete colourful squirrel! It's a lotta code to do all the colours, so click the '''Expand''' button on the right to show it:<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<syntaxhighlight lang="lua"><br />
decho(ansi2decho([[<br />
�[38;5;95m▄�[48;5;95;38;5;130m▄▄▄�[38;5;95m█�[49m▀�[0m �[0m<br />
╭───────────────────────╮ �[38;5;95m▄▄�[0m �[38;5;95m▄�[48;5;95;38;5;130m▄▄�[48;5;130m█�[38;5;137m▄�[48;5;137;38;5;95m▄�[49m▀�[0m �[0m<br />
│ │ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄▄▄�[48;5;95;38;5;137m▄▄▄�[49;38;5;95m▄▄�[48;5;95;38;5;130m▄�[48;5;130m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[0m �[0m<br />
│ Encrypt everything! │ �[38;5;95m▄�[48;5;187;38;5;16m▄�[48;5;16;38;5;187m▄�[38;5;16m█�[48;5;137;38;5;137m███�[38;5;187m▄�[38;5;16m▄▄�[38;5;137m██�[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[0m �[0m<br />
│ ├──── �[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;16m▄▄▄�[48;5;137m███�[48;5;16;38;5;16m█�[48;5;187m▄�[48;5;16m█�[48;5;137;38;5;137m█�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
╰───────────────────────╯ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;16m▄�[38;5;16m█�[38;5;137m▄�[48;5;137m██████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;95m▀�[48;5;137m▄�[38;5;137m███████�[38;5;95m▄�[49m▀�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[48;5;95;38;5;187m▄▄▄�[38;5;137m▄�[48;5;137m██�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[38;5;95m▀�[48;5;130m▄�[38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;187m████�[48;5;137;38;5;137m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m██�[38;5;95m▄�[38;5;137m█�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;187;38;5;187m████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95m██�[48;5;137m▄▄�[48;5;187;38;5;187m████�[48;5;137;38;5;95m▄▄�[48;5;95;38;5;137m▄�[48;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;187;38;5;187m███�[48;5;95m▄�[38;5;137m▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[49m▄�[48;5;95;38;5;130m▄�[48;5;130m██████�[48;5;137;38;5;137m███�[38;5;95m▄�[49m▀�[0m�[0m<br />
�[48;5;187;38;5;95m▄�[38;5;187m████�[48;5;137;38;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m█████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;137m▄�[38;5;187m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██████�[48;5;95m▄▄�[48;5;130m▄▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▄▄▄�[48;5;95;38;5;137m▄�[48;5;187m▄�[38;5;187m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m█████�[38;5;95m▄�[38;5;137m███████████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀�[48;5;187m▄▄▄�[48;5;95;38;5;137m▄�[48;5;137m██�[38;5;95m▄�[49m▀�[0m �[38;5;95m▀▀�[48;5;137m▄▄▄▄▄▄�[49m▀▀▀�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀▀�[0m �[0m<br />
]]))<br />
</syntaxhighlight><br />
</div><br />
<br />
[[File:Squirrel-in-Mudlet.png|frameless]]<br />
<br />
==cecho PR #5669 merged, PR5719 merged, PR5751 merged==<br />
; cecho([window], text)<br />
:Echoes text that can be easily formatted with colour, italics, bold, strikethrough, and underline tags. You can also include unicode art in it - try some examples from [http://1lineart.kulaone.com/#/ 1lineart].<br />
:See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:UI Functions#creplaceLine|creplaceLine()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you cecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
*''window:''<br />
:Optional - the window name to echo to - can either be none or "main" for the main window, or a miniconsole, userwindow, or label name.<br />
*''text:''<br />
:The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
cecho("Hi! This text is <red>red, <blue>blue, <green> and green.")<br />
<br />
cecho("<:green>Green background on normal foreground. Here we add an <ivory>ivory foreground.")<br />
<br />
cecho("<blue:yellow>Blue on yellow text!")<br />
<br />
cecho("\n<red>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, <o>overline</o>, and <b>bold</b>.")<br />
<br />
cecho("\n<green><o><u>Green text with over and underline at the same time.</o></u>")<br />
<br />
-- \n adds a new line<br />
cecho("<red>one line\n<green>another line\n<blue>last line")<br />
<br />
cecho("myinfo", "<green>All of this text is green in the myinfo miniconsole.")<br />
<br />
cecho("<green>(╯°□°)<dark_green>╯︵ ┻━┻")<br />
<br />
cecho("°º¤ø,¸¸,ø¤º°`°º¤ø,¸,ø¤°º¤ø,¸¸,ø¤º°`°º¤ø,¸")<br />
<br />
cecho([[<br />
██╗ ██╗ ██╗███╗ ██╗███████╗ █████╗ ██████╗ ████████╗<br />
███║ ██║ ██║████╗ ██║██╔════╝ ██╔══██╗██╔══██╗╚══██╔══╝<br />
╚██║ ██║ ██║██╔██╗ ██║█████╗ ███████║██████╔╝ ██║<br />
██║ ██║ ██║██║╚██╗██║██╔══╝ ██╔══██║██╔══██╗ ██║<br />
██║ ███████╗██║██║ ╚████║███████╗ ██║ ██║██║ ██║ ██║<br />
╚═╝ ╚══════╝╚═╝╚═╝ ╚═══╝╚══════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝<br />
]])<br />
</syntaxhighlight><br />
<br />
==cecho2ansi PR# 5672 merged==<br />
<br />
;ansiFormattedString = cecho2ansi(text)<br />
<br />
:Converts cecho formatted text to ansi formatted text. Used by cfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also:[[Manual:Lua_Functions#cecho|cecho()]], [[Manual:Lua_Functions#cfeedTriggers|cfeedTriggers()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
{{note}} This function uses the ansi short colors (0-15) for color names which have base 16 ansi equivalents, such as 'red', 'blue', "lightBlue", "cyan", etc rather than the values defined in the color_table. If there is no base ansi equivalent then it will use the rgb values from the color_table for the color.<br />
<br />
;Parameters<br />
*''text:''<br />
:The cecho formatted text for conversion<br />
<br />
;Returns<br />
*String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of cfeedTriggers() for a single line.<br />
-- you would most likely just use cfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(cecho2ansi("\n<red>This is red.<reset> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
;Additional development notes<br />
<br />
==createScrollBox PR #5739==<br />
;createScrollBox([name of parent window], name, x, y, width, height)<br />
<br />
: creates a graphical elements able to hold other graphical elements such as labels, miniconsoles, command lines etc. in it.<br />
If the added elements don't fit into the ScrollBox scrollbars appear and allow scrolling.<br />
: Returns true or false.<br />
<br />
: See also: [[Manual:Lua_Functions#createLabel|createLabel()]], [[Manual:Lua_Functions#hideWindow|hideWindow()]], [[Manual:Lua_Functions#showWindow|showWindow()]], [[Manual:Lua_Functions#resizeWindow|resizeWindow()]], [[Manual:Lua_Functions#moveWindow|moveWindow()]], [[Manual:Lua_Functions#setWindow|setWindow()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''name of parent window:'' <br />
: (Optional) name of the parent window the scrollBox is created in. Defaults to the main window if not provided.<br />
* ''name:''<br />
: The name of the scrollBox. Must be unique. Passed as a string.<br />
* ''x'', ''y'', ''width'', ''height''<br />
: Parameters to set set the window size and location<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create a ScrollBox with the name sBox<br />
createScrollBox("SBox",0,0,300,200)<br />
<br />
-- create 3 Labels and put them into the ScrollBox<br />
createLabel("SBox","SBoxLabel",0,0,200,200,1)<br />
createLabel("SBox","SBoxLabel2",200,0,200,200,1)<br />
createLabel("SBox","SBoxLabel3",400,0,200,200,1)<br />
<br />
-- put some text on the labels<br />
echo("SBoxLabel","Label")<br />
echo("SBoxLabel2","Label2")<br />
echo("SBoxLabel3","Label3")<br />
<br />
-- change the colours of the labels to make it easier to distinguish them<br />
setBackgroundColor("SBoxLabel",255,0,0)<br />
setBackgroundColor("SBoxLabel2",0,255,0)<br />
setBackgroundColor("SBoxLabel3",0,0,255)<br />
</syntaxhighlight><br />
<br />
==decho PR #5669 merged PR5719 merged PR5751 merged ==<br />
;decho ([name of console,] text)<br />
:Color changes can be made using the format <FR,FG,FB:BR,BG,BB,[BA]> where each field is a number from 0 to 255. The background portion can be omitted using <FR,FG,FB> or the foreground portion can be omitted using <:BR,BG,BB,[BA]>. Arguments 2 and 3 set the default fore and background colors for the string using the same format as is used within the string, sans angle brackets, e.g. ''decho("<50,50,0:0,255,0>test")''.<br />
:You can also include <code><nowiki><i>italics</i></nowiki></code>, <code><nowiki><b>bold</b></nowiki></code>, <code><nowiki><s>strikethrough</s></nowiki></code>, <code><nowiki><o>overline</o></nowiki></code>, and <code><nowiki><u>underline</u></nowiki></code> tags.<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you decho it will erase any previous echo sent to the label.<br />
<br />
:See also: [[#cecho|cecho()]], [[#hecho|hecho()]], [[#copy2decho|copy2decho()]]<br />
<br />
;Parameters<br />
*''name of console''<br />
:(Optional) Name of the console to echo to. If no name is given, this will defaults to the main window.<br />
*''text:''<br />
:The text that you’d like to echo with embedded color tags. Tags take the RGB values only, see below for an explanation.<br />
<br />
<br />
{{note}}<br />
Optional background transparancy parameter (BA) available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
decho("<50,50,0:0,255,0>test")<br />
<br />
decho("miniconsolename", "<50,50,0:0,255,0>test")<br />
<br />
decho("\n<255,0,0>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, and <b>bold</b> formatting.")<br />
<br />
decho("<\n<0,128,0><o><u>Green text with both over and underlines.</u></o>")<br />
</syntaxhighlight><br />
<br />
==decho2ansi PR# 5671 merged==<br />
<br />
;ansiFormattedString = decho2ansi(text)<br />
<br />
:Converts decho formatted text to ansi formatted text. Used by dfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also:[[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#dfeedTriggers|dfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
; Parameters<br />
*''text:''<br />
:The decho formatted text for conversion<br />
<br />
;Returns<br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of dfeedTriggers() for a single line.<br />
-- you would most likely just use dfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(decho2ansi("\n<128,0,0>This is red.<r> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
==getHTMLformat PR#5751 merged==<br />
<br />
;spanTag = getHTMLformat(formatTable)<br />
<br />
:Takes in a table of formatting options in the same style as [[Manual:Lua_Functions#getTextFormat|getTextFormat()]] and returns a span tag which will format text after it as the table describes.<br />
<br />
;See also:[[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
*''formatTable:''<br />
:Table with formatting options configured. Keys are foreground, background, bold, underline, overline, strikeout, italic, and reverse. All except for foreground and background should be boolean (true/false) values. Foreground and background are either { r, g, b, a } tables, or strings with QSS formatting directives<br />
<br />
;Returns<br />
*A string with the html span tag to format text in accordance with the format table.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Returns a span tag for bold, red text on a green background<br />
local span = getHTMLformat({<br />
foreground = { 255, 0, 0 },<br />
background = "#00FF00",<br />
bold = true<br />
})<br />
<br />
-- span will be '<span style="color: rgb(255, 0, 0);background-color: #00FF00; font-weight: bold; font-style: normal; text-decoration: none;">'<br />
</syntaxhighlight><br />
<br />
==getLabelFormat PR#5751 merged==<br />
<br />
;formatTable = getLabelFormat(labelName)<br />
<br />
: Returns a format table like the one returned by getTextFormat and suitable for getHTMLspan which will format text the same way as simply doing an echo to the label would<br />
<br />
;See also:[[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getHTMLspan|getHTMLspan()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
*''labelName:''<br />
: The name of the label to scan the format of<br />
<br />
;Returns<br />
*A table with all the formatting options to achieve a default text format for label labelName.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- creates a test label, sets a stylesheet, and then returns the default format table for that label.<br />
createLabel("testLabel", 10, 10, 300, 200, 1)<br />
setLabelStyleSheet([[<br />
color: rgb(0,0,180);<br />
border-width: 1px;<br />
border-style: solid;<br />
border-color: gold;<br />
border-radius: 10px;<br />
font-size: 12.0pt;<br />
background: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #98f041, stop: 0.1 #8cf029, stop: 0.49 #66cc00, stop: 0.5 #52a300, stop: 1 #66cc00);<br />
]])<br />
local fmt = getLabelFormat("testLabel"))<br />
<br />
--[[<br />
{<br />
background = "rgba(0, 0, 0, 0)", -- this is transparent<br />
bold = false,<br />
foreground = "rgb(0,0,180)",<br />
italic = false,<br />
overline = false,<br />
reverse = false,<br />
strikeout = false,<br />
underline = false<br />
}<br />
--]]<br />
<br />
</syntaxhighlight><br />
<br />
<br />
==getLabelSizeHint PR#5815 merged==<br />
<br />
;width, height = getLabelSizeHint(labelName)<br />
<br />
: Returns the suggested labelsize as width and height<br />
<br />
;See also:[[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getHTMLspan|getHTMLspan()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
*''labelName:''<br />
: The name of the label to get the suggested size from<br />
<br />
;Returns<br />
*suggested width and height (to fit text and/or an image on a label)<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- text resizing example<br />
-- create the label<br />
createLabel("textLabel",400,400,300,300,1)<br />
-- put some text on it<br />
echo("textLabel", "This is my Test.\nAnother Test")<br />
-- resizes the label to fit the text<br />
resizeWindow("textLabel", getLabelSizeHint("textLabel"))<br />
<br />
-- image resizing example<br />
-- create the label<br />
createLabel("imageLabel",400,400,300,300,1)<br />
-- put some image on it<br />
setBackgroundImage("imageLabel", getMudletHomeDir.."/myLabelImage.png")<br />
-- resizes the label to fit the image<br />
resizeWindow("imageLabel", getLabelSizeHint("imageLabel"))<br />
<br />
</syntaxhighlight><br />
<br />
==hecho PR #5669 merged, PR5719 merged, PR5751 merged==<br />
;hecho([windowName], text)<br />
:Echoes text that can be easily formatted with colour tags in the hexadecimal format. You can also use italics, bold, strikethrough, and underline tags.<br />
:See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#cecho|cecho()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you hecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
*''windowName:''<br />
:(optional) name of the window to echo to. Can either be omitted or "main" for the main window, else specify the miniconsoles name.<br />
*''text:''<br />
:The text to display, with color changes made within the string using the format |cFRFGFB,BRBGBB or #FRFGFB,BRBGBB where FR is the foreground red value, FG is the foreground green value, FB is the foreground blue value, BR is the background red value, etc., BRBGBB is optional. |r or #r can be used within the string to reset the colors to default. Hexadecimal color codes can be found here: https://www.color-hex.com/<br />
<br />
{{note}}<br />
Transparency for background in hex-format available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
hecho("\n#ffffff White text!")<br />
-- your text in white<br />
hecho("\n#ca0004 Red text! And now reset #rit to the default color")<br />
-- your text in red, then reset to default using #r<br />
hecho("\n#ffffff,ca0004 White text with a red background!")<br />
-- your text in white, against a red background<br />
hecho("\n|c0000ff Blue text, this time using |c instead of #")<br />
-- your text in blue, activated with |c vs #.<br />
hecho("\n#ff0000Red text with #iitalics#/i, |uunderline|/u, #ooverline#/o, #sstrikethrough#/s, and #bbold#/b formatting.")<br />
-- shows the various individual formatting options<br />
hecho("\n#008000#o#uGreen text with both over and underlines.#/o#/u")<br />
</syntaxhighlight><br />
<br />
==hecho2ansi PR# 5671 merged==<br />
<br />
;ansiFormattedString = hecho2ansi(text)<br />
<br />
:Converts hecho formatted text to ansi formatted text. Used by hfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also:[[Manual:Lua_Functions#hecho|hecho()]], [[Manual:Lua_Functions#hfeedTriggers|hfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
*''text:''<br />
:The hecho formatted text for conversion<br />
<br />
;Returns<br />
*String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of hfeedTriggers() for a single line.<br />
-- you would most likely just use hfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(hecho2ansi("\n#800000This is red.#r #iitalic#/i, #bbold#/b, #sstrikethrough#/s, #uunderline#/u\n"))<br />
</syntaxhighlight><br />
<br />
==setMovie PR #5827==<br />
;setMovie(label name, path to gif)<br />
<br />
: adds a gif to the selected label and animates it<br />
: Returns true<br />
<br />
: See also: [[Manual:Lua_Functions#setMovieStart|setMovieStart()]], [[Manual:Lua_Functions#setMoviePaused|setMoviePaused()]], [[Manual:Lua_Functions#setMovieFrame|setMovieFrame()]], [[Manual:Lua_Functions#setMovieSpeed|setMovieSpeed()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''label name:'' <br />
: name of the label the gif will be animated on<br />
* ''path:''<br />
: path of the gif file<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- download & show a gif within mudlet<br />
local saveto = getMudletHomeDir().."/kymip.gif"<br />
-- animation credit to https://opengameart.org/content/kymiball-ii-third-prototype-scraps<br />
local url = "https://opengameart.org/sites/default/files/kymip_0.gif"<br />
<br />
if downloadHandler then killAnonymousEventHandler(downloadHandler) end<br />
downloadHandler = registerAnonymousEventHandler("sysDownloadDone",<br />
function(_, filename)<br />
if filename ~= saveto then<br />
return true<br />
end<br />
<br />
local width, height = getImageSize(saveto)<br />
<br />
createLabel("kymip", 300, 300, width, height, 0)<br />
setMovie("kymip", saveto)<br />
setLabelReleaseCallback("kymip", function() deleteLabel("kymip") end)<br />
end, true)<br />
<br />
downloadFile(saveto, url)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- create a label with the name myMovie<br />
createLabel("myMovie",0,0,200,200,0)<br />
<br />
-- puts the gif on the label and animates it<br />
setMovie("myMovie", getMudletHomeDir().."/movie.gif")<br />
</syntaxhighlight><br />
<br />
==setMovieStart PR #5827==<br />
;setMovieStart(label name)<br />
<br />
: starts the gif animated if stop or paused<br />
: Returns true<br />
<br />
: See also: [[Manual:Lua_Functions#setMovie|setMovie()]], [[Manual:Lua_Functions#setMoviePaused|setMoviePaused()]], [[Manual:Lua_Functions#setMovieFrame|setMovieFrame()]], [[Manual:Lua_Functions#setMovieSpeed|setMovieSpeed()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''label name:'' <br />
: name of the gif label <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create a label with the name myMovie<br />
createLabel("myMovie",0,0,200,200,0)<br />
<br />
-- puts the gif on the label and animates it<br />
setMovie("myMovie", getMudletHomeDir().."/movie.gif")<br />
--stops the animation<br />
setMoviePaused("myMovie")<br />
--restart the animation<br />
setMovieStart("myMovie")<br />
<br />
</syntaxhighlight><br />
<br />
<br />
==setMoviePaused PR #5827==<br />
;setMoviePaused(label name)<br />
<br />
: toggles pause/unpause of the gif animation on the label<br />
: Returns true<br />
<br />
: See also: [[Manual:Lua_Functions#setMovie|setMovie()]], [[Manual:Lua_Functions#setMovieStart|setMovieStart()]], [[Manual:Lua_Functions#setMovieFrame|setMovieFrame()]], [[Manual:Lua_Functions#setMovieSpeed|setMovieSpeed()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''label name:'' <br />
: name of the gif label <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create a label with the name myMovie<br />
createLabel("myMovie",0,0,200,200,0)<br />
<br />
-- puts the gif on the label and animates it<br />
setMovie("myMovie", getMudletHomeDir().."/movie.gif")<br />
--stops the animation<br />
setMoviePaused("myMovie")<br />
<br />
</syntaxhighlight><br />
<br />
==setMovieFrame PR #5827==<br />
;setMovieFrame(label name, frame nr)<br />
<br />
: jumps to the frame (frame nr)<br />
: Returns true if succesful and false if frame doesn't exist<br />
<br />
: See also: [[Manual:Lua_Functions#setMovie|setMovie()]], [[Manual:Lua_Functions#setMovieStart|setMovieStart()]], [[Manual:Lua_Functions#setMoviePaused|setMoviePaused()]], [[Manual:Lua_Functions#setMovieSpeed|setMovieSpeed()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''label name:'' <br />
: name of the gif label<br />
* ''frame nr:''<br />
: the gif animations frame nr to jump to<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create a label with the name myMovie<br />
createLabel("myMovie",0,0,200,200,0)<br />
<br />
-- puts the gif on the label and animates it<br />
setMovie("myMovie", getMudletHomeDir().."/movie.gif")<br />
--stops the animation<br />
setMoviePaused("myMovie")<br />
-- jumps to frame 12 of the animation<br />
setMovieFrame("myMovie", 12)<br />
--start the animation<br />
setMovieStart("myMovie")<br />
<br />
</syntaxhighlight><br />
<br />
<br />
==setMovieSpeed PR #5827==<br />
;setMovieSpeed(label name, speed in percent)<br />
<br />
: sets the animation speed to speed (in percent)<br />
: Returns true<br />
<br />
: See also: [[Manual:Lua_Functions#setMovie|setMovie()]], [[Manual:Lua_Functions#setMovieStart|setMovieStart()]], [[Manual:Lua_Functions#setMoviePaused|setMoviePaused()]], [[Manual:Lua_Functions#setMovieFrame|setMovieFrame()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''label name:'' <br />
: name of the gif label<br />
* ''speed in percent:''<br />
: the gif animations speed in percent for example 50 for 50% speed<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create a label with the name myMovie<br />
createLabel("myMovie",0,0,200,200,0)<br />
<br />
-- puts the gif on the label and animates it<br />
setMovie("myMovie", getMudletHomeDir().."/movie.gif")<br />
--accelerates the animation to a speed of 150%<br />
setMovieSpeed("myMovie",150)<br />
<br />
<br />
</syntaxhighlight><br />
<br />
==windowType PR# 5696 open==<br />
;typeOfWindow = windowType(windowName)<br />
<br />
:Given the name of a window, will return if it's a label, miniconsole, userwindow or a commandline.<br />
<br />
;See also:[[Manual:Lua_Functions#createLabel|createLabel()]], [[Manual:Lua_Functions#openUserWindow|openUserWindow()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
*''windowName:''<br />
:The name used to create the window element. Use "main" for the main console<br />
<br />
<br />
;Returns<br />
*Window type as string ("label", "miniconsole", "userwindow", or "commandline") or nil+error if it does not exist.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a Geyser label and and check its type<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
display(windowType(testLabel.name)) -- displays "label"<br />
<br />
-- the main console returns "miniconsole" because it uses the same formatting functions<br />
display(windowType("main")) -- displays "miniconsole"<br />
<br />
-- check for the existence of a window<br />
local windowName = "this thing does not exist"<br />
local ok, err = windowType(windowName)<br />
if ok then<br />
-- do things with it, as it does exist.<br />
-- the ok variable will hold the type of window it is ("label", "commandline", etc)<br />
else<br />
cecho("<red>ALERT!! window does not exist")<br />
end<br />
</syntaxhighlight><br />
<br />
;Additional development notes<br />
<br />
=Discord Functions=<br />
: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 [[Special:MyLanguage/Manual:Scripting#Discord_Rich_Presence|Discord scripting overview]].</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:UI_Functions&diff=19666Manual:UI Functions2022-01-14T19:04:40Z<p>Demonnic: /* getLineCount */</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Mudlet API documentation for functions to construct custom GUIs. They deal mainly with miniconsole/label/gauge creation and manipulation as well as displaying or formatting information on the screen.}}<br />
= UI Functions =<br />
All functions that help you construct custom GUIs. They deal mainly with miniconsole/label/gauge creation and manipulation as well as displaying or formatting information on the screen.<br />
<br />
==addCommandLineMenuEvent==<br />
;addCommandLineMenuEvent([window,] label, eventName)<br />
<br />
Adds item to right click menu associated with command line.<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;See also: [[Manual:Lua_Functions#removeCommandLineMenuEvent|removeCommandLineMenuEvent()]]<br />
<br />
;Parameters<br />
* ''window:''<br />
: Window that command line belongs to. Optional, will default to "main" (main window console)<br />
* ''label:''<br />
: Label of item<br />
* ''eventName:''<br />
: Event name that will be fired when clicked.<br />
<br />
;Returns <br />
* Returns ''true'' if the mouse event was added successfully.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addCommandLineMenuEvent("My very own special paste from clipboard", "pasteFromClipboardWithoutLineBreaks" )<br />
registerAnonymousEventHandler("pasteFromClipboardWithoutLineBreaks", function()<br />
local text = string.gsub(getClipboardText(), "[\r|\n]", "")<br />
appendCmdLine(text)<br />
end)<br />
</syntaxhighlight><br />
<br />
==addMouseEvent==<br />
; addMouseEvent(uniqueName, eventName, [displayName, tooltipText])<br />
<br />
:Registers a new context menu option when right-clicked on a console window. Will return ''true'' if the event was added successfully, otherwise ''nil''+''message'' will be returned. If the ''displayName'' isn't set, ''uniqueName'' will be used for the menu label. ''eventName'' should be a Mudlet event that will handle the click data that includes ''event'', ''unique name'', ''window name'', selection upper left ''column'' and ''row'' and selection bottom right ''column'' and ''row'' in that order. This is intended to be used with available cursor functions for any selection or processing needs.<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
;See also: [[Manual:Lua_Functions#getMouseEvents|getMouseEvents()]], [[Manual:Lua_Functions#moveCursor|moveCursor()]]<br />
<br />
;Parameters<br />
* ''uniqueName:''<br />
: A unique identifier for the mouse event.<br />
* ''eventName:''<br />
: Name of the Mudlet event that will handle the data.<br />
* ''displayName:''<br />
: (optional) Label text for the mouse context menu. If not set, the label defaults to ''uniqueName''.<br />
* ''tooltipText:''<br />
: (optional) Tooltip text when mouse is hovered on the option. If not set, no tooltip will be visible.<br />
<br />
;Returns <br />
* Returns ''true'' if the mouse event was added successfully.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- An example showing implementing a hecho-friendly copy option:<br />
<br />
addMouseEvent("hecho copy", "onMouseCopyExample")<br />
<br />
function rgbToHex(r,g,b)<br />
local rgb = (r * 0x10000) + (g * 0x100) + b<br />
return string.format("#%x", rgb)<br />
end<br />
<br />
function onMouseCopyExample(event, menu, window, startCol, startRow, endCol, endRow)<br />
-- Check whether there's an actual selection<br />
if startCol == endCol and startRow == endRow then return end<br />
local parsed = ""<br />
local lastColor = nil<br />
-- Loop through each symbol within the range<br />
for l = startRow, endRow do<br />
local cStart = l == startRow and startCol or 0<br />
moveCursor(window, cStart, l)<br />
local cEnd = l == endRow and endCol or #getCurrentLine() - 1<br />
for c = cStart, cEnd do<br />
selectSection(window, c, 1)<br />
local symbol = getSelection(window) or ""<br />
-- Convert the foreground color to a hex format, suitable for hecho<br />
local color = rgbToHex(getFgColor(window))<br />
-- Don't repeat the color if previous one was the same<br />
if color == lastColor then<br />
parsed = parsed .. symbol<br />
else<br />
lastColor = color<br />
parsed = parsed .. color .. symbol<br />
end<br />
end<br />
if l ~= endRow then parsed = parsed .. "\n" end<br />
end<br />
setClipboardText(parsed)<br />
end<br />
<br />
registerAnonymousEventHandler("onMouseCopyExample", "onMouseCopyExample")<br />
</syntaxhighlight><br />
<br />
==ansi2decho==<br />
;ansi2decho(text, default_colour)<br />
: Converts ANSI colour sequences in <code>text</code> to colour tags that can be processed by the decho() function. Italics and underline not currently supported since decho doesn't support them.<br />
: See also: [[Manual:Lua_Functions#decho|decho()]]<br />
<br />
{{MudletVersion|3.0}}<br />
{{note}} ANSI bold is available since Mudlet 3.7.1+.<br />
<br />
;Parameters<br />
* ''text:''<br />
: String that contains ANSI colour sequences that should be replaced.<br />
* ''default_colour:''<br />
: Optional - ANSI default colour code (used when handling orphan bold tags).<br />
<br />
;Return values<br />
* ''string text:''<br />
: The decho-valid converted text.<br />
* ''string colour:''<br />
: The ANSI code for the last used colour in the substitution (useful if you want to colour subsequent lines according to this colour).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local replaced = ansi2decho('\27[0;1;36;40mYou say in a baritone voice, "Test."\27[0;37;40m')<br />
-- 'replaced' should now contain <r><0,255,255:0,0,0>You say in a baritone voice, "Test."<r><192,192,192:0,0,0><br />
decho(replaced)<br />
</syntaxhighlight><br />
<br />
Or show a complete colourful squirrel! It's a lotta code to do all the colours, so click the '''Expand''' button on the right to show it:<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<syntaxhighlight lang="lua"><br />
decho(ansi2decho([[<br />
�[38;5;95m▄�[48;5;95;38;5;130m▄▄▄�[38;5;95m█�[49m▀�[0m �[0m<br />
╭───────────────────────╮ �[38;5;95m▄▄�[0m �[38;5;95m▄�[48;5;95;38;5;130m▄▄�[48;5;130m█�[38;5;137m▄�[48;5;137;38;5;95m▄�[49m▀�[0m �[0m<br />
│ │ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄▄▄�[48;5;95;38;5;137m▄▄▄�[49;38;5;95m▄▄�[48;5;95;38;5;130m▄�[48;5;130m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[0m �[0m<br />
│ Encrypt everything! │ �[38;5;95m▄�[48;5;187;38;5;16m▄�[48;5;16;38;5;187m▄�[38;5;16m█�[48;5;137;38;5;137m███�[38;5;187m▄�[38;5;16m▄▄�[38;5;137m██�[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[0m �[0m<br />
│ ├──── �[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;16m▄▄▄�[48;5;137m███�[48;5;16;38;5;16m█�[48;5;187m▄�[48;5;16m█�[48;5;137;38;5;137m█�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
╰───────────────────────╯ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;16m▄�[38;5;16m█�[38;5;137m▄�[48;5;137m██████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;95m▀�[48;5;137m▄�[38;5;137m███████�[38;5;95m▄�[49m▀�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[48;5;95;38;5;187m▄▄▄�[38;5;137m▄�[48;5;137m██�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[38;5;95m▀�[48;5;130m▄�[38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;187m████�[48;5;137;38;5;137m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m██�[38;5;95m▄�[38;5;137m█�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;187;38;5;187m████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95m██�[48;5;137m▄▄�[48;5;187;38;5;187m████�[48;5;137;38;5;95m▄▄�[48;5;95;38;5;137m▄�[48;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;187;38;5;187m███�[48;5;95m▄�[38;5;137m▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[49m▄�[48;5;95;38;5;130m▄�[48;5;130m██████�[48;5;137;38;5;137m███�[38;5;95m▄�[49m▀�[0m�[0m<br />
�[48;5;187;38;5;95m▄�[38;5;187m████�[48;5;137;38;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m█████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;137m▄�[38;5;187m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██████�[48;5;95m▄▄�[48;5;130m▄▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▄▄▄�[48;5;95;38;5;137m▄�[48;5;187m▄�[38;5;187m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m█████�[38;5;95m▄�[38;5;137m███████████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀�[48;5;187m▄▄▄�[48;5;95;38;5;137m▄�[48;5;137m██�[38;5;95m▄�[49m▀�[0m �[38;5;95m▀▀�[48;5;137m▄▄▄▄▄▄�[49m▀▀▀�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀▀�[0m �[0m<br />
]]))<br />
</syntaxhighlight><br />
</div><br />
<br />
[[File:Squirrel-in-Mudlet.png|frameless]]<br />
<br />
==ansi2string==<br />
;ansi2string(text)<br />
: Strips ANSI colour sequences from a string (text)<br />
: See also: [[Manual:Lua_Functions#ansi2decho|ansi2decho()]]<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
;Parameters<br />
* ''text:''<br />
: String that contains ANSI colour sequences that should be removed.<br />
<br />
;Return values<br />
* ''string text:''<br />
: The plain text without ANSI colour sequences.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local replaced = ansi2string('\27[0;1;36;40mYou say in a baritone voice, "Test."\27[0;37;40m')<br />
-- 'replaced' should now contain You say in a baritone voice, "Test."<br />
print(replaced)<br />
</syntaxhighlight><br />
<br />
==appendBuffer==<br />
;appendBuffer(name)<br />
: Pastes the previously copied rich text (including text formats like color etc.) into user window name.<br />
: See also: [[#selectCurrentLine|selectCurrentLine()]], [[#copy|copy()]], [[Manual:Lua_Functions#paste|paste()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name of the user window to paste into. Passed as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--selects and copies an entire line to user window named "Chat"<br />
selectCurrentLine()<br />
copy()<br />
appendBuffer("Chat")<br />
</syntaxhighlight><br />
<br />
==bg==<br />
;bg([window, ]colorName)<br />
: Changes the background color of the text. Useful for highlighting text.<br />
: See Also: [[Manual:Lua_Functions#fg|fg()]], [[Manual:Lua_Functions#setBgColor|setBgColor()]]<br />
<br />
;Parameters<br />
* ''window:''<br />
: The miniconsole to operate on - optional. If you'd like it to work on the main window, don't specify anything, or use ''main'' (since Mudlet 3.0).<br />
* ''colorName:''<br />
: The name of the color to set the background to. [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This would change the background color of the text on the current line to magenta<br />
selectCurrentLine()<br />
bg("magenta")<br />
<br />
-- or echo text with a green background to a miniconsole<br />
bg("my window", "green")<br />
echo("my window", "some green text\n")<br />
</syntaxhighlight><br />
<br />
==calcFontSize==<br />
;calcFontSize(window_or_fontsize, [fontname])<br />
: Returns the average height and width of characters in a particular window, or a font name and size combination. Helpful if you want to size a miniconsole to specific dimensions.<br />
: Returns two numbers, width/height<br />
: See also: [[Manual:Lua_Functions#setMiniConsoleFontSize|setMiniConsoleFontSize()]], [[Manual:Lua_Functions#getMainWindowSize|getMainWindowSize()]]<br />
<br />
;Parameters<br />
* ''window_or_fontsize:''<br />
: The miniconsole or font size you are wanting to calculate pixel sizes for.<br />
* ''fontname:''<br />
: Specific font name (along with the size as the first argument) to calculate for.<br />
<br />
{{note}}<br />
Window as an argument is available in Mudlet 3.10+, and font name in Mudlet 4.1+.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--this snippet will calculate how wide and tall a miniconsole designed to hold 4 lines of text 20 characters wide<br />
--would need to be at 9 point font, and then changes miniconsole Chat to be that size<br />
local width,height = calcFontSize(9)<br />
width = width * 20<br />
height = height * 4<br />
resizeWindow("Chat", width, height)<br />
</syntaxhighlight><br />
<br />
==cecho==<br />
;cecho([window], text)<br />
: Echoes text that can be easily formatted with colour, italics, bold and underline tags. You can also include unicode art in it - try some examples from [http://1lineart.kulaone.com/#/ 1lineart].<br />
: See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:UI Functions#creplaceLine|creplaceLine()]]<br />
<br />
;Parameters<br />
* ''window:''<br />
: Optional - the window name to echo to - can either be none or "main" for the main window, or the miniconsoles name.<br />
* ''text:''<br />
: The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
cecho("Hi! This text is <red>red, <blue>blue, <green> and green.")<br />
<br />
cecho("<:green>Green background on normal foreground. Here we add an <ivory>ivory foreground.")<br />
<br />
cecho("<blue:yellow>Blue on yellow text!")<br />
<br />
cecho("\n<red>Red text with <i>italics</i>, <u>underline</u> and <b>bold</b>.")<br />
<br />
-- \n adds a new line<br />
cecho("<red>one line\n<green>another line\n<blue>last line")<br />
<br />
cecho("myinfo", "<green>All of this text is green in the myinfo miniconsole.")<br />
<br />
cecho("<green>(╯°□°)<dark_green>╯︵ ┻━┻")<br />
<br />
cecho("°º¤ø,¸¸,ø¤º°`°º¤ø,¸,ø¤°º¤ø,¸¸,ø¤º°`°º¤ø,¸")<br />
<br />
cecho([[<br />
██╗ ██╗ ██╗███╗ ██╗███████╗ █████╗ ██████╗ ████████╗<br />
███║ ██║ ██║████╗ ██║██╔════╝ ██╔══██╗██╔══██╗╚══██╔══╝<br />
╚██║ ██║ ██║██╔██╗ ██║█████╗ ███████║██████╔╝ ██║<br />
██║ ██║ ██║██║╚██╗██║██╔══╝ ██╔══██║██╔══██╗ ██║<br />
██║ ███████╗██║██║ ╚████║███████╗ ██║ ██║██║ ██║ ██║<br />
╚═╝ ╚══════╝╚═╝╚═╝ ╚═══╝╚══════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝<br />
]])<br />
</syntaxhighlight><br />
<br />
==cechoLink==<br />
;cechoLink([windowName], text, command, hint, true)<br />
: Echos a piece of text as a clickable link, at the end of the current selected line - similar to [[Manual:Lua_Functions#cecho|cecho()]]. This version allows you to use colours within your link text.<br />
<br />
: See also: [[#echoLink|echoLink()]], [[#dechoLink|dechoLink()]], [[#hechoLink|hechoLink()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: optional parameter, allows selection between sending the link to a miniconsole or the main window.<br />
* ''text:''<br />
: text to display in the echo. Same as a normal [[Manual:Lua_Functions#cecho|cecho()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''true:''<br />
: requires argument for the colouring to work.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
cechoLink("<red>press <brown:white>me!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
cechoLink("<red>press <brown:white>me!", [[send("hi")]], "This is a tooltip", true)<br />
</syntaxhighlight><br />
<br />
==cechoPopup==<br />
;cechoPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current line, like [[#cecho|cecho()]]. 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.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. ie, <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
cechoPopup("<red>activities<reset> to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"}, true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
cechoPopup("<red>activities<reset> to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"}, true)<br />
</syntaxhighlight><br />
<br />
==cinsertLink==<br />
;cinsertLink([windowName], text, command, hint, true)<br />
: Echos a piece of text as a clickable link, at the end of the current cursor position - similar to [[#cinsertText|cinsertText()]]. This version allows you to use colours within your link text.<br />
<br />
: See also: [[#insertLink|insertLink()]], [[#hinsertLink|hinsertLink()]]<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: optional parameter, allows selection between sending the link to a miniconsole or the main window.<br />
* ''text:''<br />
: text to display in the echo. Same as a normal [[Manual:Lua_Functions#cecho|cecho()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''true:''<br />
: requires argument for the colouring to work.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
cinsertLink("<red>press <brown:white>me!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
cinsertLink("<red>press <brown:white>me!", [[send("hi")]], "This is a tooltip", true)<br />
</syntaxhighlight><br />
<br />
==cinsertPopup==<br />
;cinsertPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current cursor position, like [[#cinsertText|cinsertText()]]. 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.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. ie, <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
cinsertPopup("<red>activities<reset> to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"}, true)<br />
<br />
-- Create some text as a clickable with a popup menu:<br />
cinsertPopup("<red>activities<reset> to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"}, true)</syntaxhighlight><br />
<br />
==cinsertText==<br />
;cinsertText([window], text)<br />
: inserts text at the current cursor position, with the possibility for color tags.<br />
: See Also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:UI Functions#creplaceLine|creplaceLine()]]<br />
<br />
;Parameters<br />
* ''window:''<br />
: Optional - the window name to echo to - can either be none or "main" for the main window, or the miniconsoles name.<br />
* ''text:''<br />
: The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a double colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
cinsertText("Hi! This text is <red>red, <blue>blue, <green> and green.")<br />
<br />
cinsertText("<:green>Green background on normal foreground. Here we add an <ivory>ivory foreground.")<br />
<br />
cinsertText("<blue:yellow>Blue on yellow text!")<br />
<br />
cinsertText("myinfo", "<green>All of this text is green in the myinfo miniconsole.")<br />
</syntaxhighlight><br />
<br />
==clearUserWindow==<br />
;clearUserWindow([name])<br />
: This is (now) identical to [[Manual:Lua_Functions#clearWindow|clearWindow()]].<br />
<br />
==clearWindow==<br />
;clearWindow([windowName])<br />
: Clears the label, mini console, or user window with the name given as argument (removes all text from it). If you don't give it a name, it will clear the main window.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) The name of the label, mini console, or user window to clear. Passed as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This would clear a label, user window, or miniconsole with the name "Chat"<br />
clearWindow("Chat")<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- this can clear your whole main window<br />
clearWindow()<br />
</syntaxhighlight><br />
<br />
==closestColor==<br />
; closestColor(colorOrR[,G,B])<br />
<br />
:Returns the closest color from the color_table to the one provided for use in cecho and associated functions.<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
;Parameters<br />
* ''colorOrR:''<br />
: Either the string representation of a color from decho or hecho (IE "#ff0077" or "<255,0,128>"), a table of color values (IE {255,0,18}), or the Red component of RGB when followed by two next optional parameters<br />
* ''G:''<br />
: (optional) green component of RGB coordinates. Only needed if first parameter sent as the Red component only<br />
* ''B:''<br />
: (optional) blue component of RGB coordinates. Only needed if first parameter sent as the Red component only<br />
<br />
;Returns<br />
* The closest color name from the color_table to the one supplied on success<br />
* nil + error if it cannot parse the parameters into a color.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local colorName = closestColor(255, 0, 0) -- "ansi_light_red"<br />
local colorName = closestColor({127, 255, 127}) -- "ansi_120"<br />
local colorName = closestColor("<127, 127, 127>") -- "ansi_008"<br />
local colorName = closestColor("#a020e6") -- "purple"<br />
local colorName = closestColor("blue") -- "blue" (you wouldn't necessarily do this on purpose, but during automated color conversions this might occur)<br />
</syntaxhighlight><br />
<br />
==copy==<br />
; copy([windowName])<br />
: Copies the current selection to the lua virtual clipboard. This function operates on rich text, i. e. the selected text including all its format codes like colors, fonts etc. in the lua virtual clipboard until it gets overwritten by another copy operation.<br />
: See also: [[#selectString|selectString()]], [[#selectCurrentLine|selectCurrentLine()]], [[#paste|paste()]], [[#appendBuffer|appendBuffer()]], [[#replace|replace()]], [[#createMiniConsole|createMiniConsole()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
; Parameters<br />
* ''windowName'' (optional):<br />
: the window from which to copy text - use the main console if not specified.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This script copies the current line on the main screen to a window (miniconsole or userwindow) called 'chat' and gags the output on the main screen.<br />
selectString(line, 1)<br />
copy()<br />
appendBuffer("chat")<br />
replace("This line has been moved to the chat window!")<br />
</syntaxhighlight><br />
<br />
==copy2decho==<br />
; copy2decho([window], [stringToCopy], [instanceToCopy])<br />
: Copies a string from the current line of window, including color information in decho format.<br />
: See also: [[#decho|decho()]]<br />
{{MudletVersion|4.8}}<br />
<br />
; Parameters<br />
* ''window'' (optional):<br />
: the window to copy the text from. Defaults to "main".<br />
* ''stringToCopy'' (optional): <br />
: the string to copy. Defaults to copying the entire line.<br />
* ''instanceToCopy'' (optional):<br />
: the instance of the string to copy. Defaults to 1.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This copies the current line on the main console and dechos it to a miniconsole named "test"<br />
decho("test", copy2decho())<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- This when put into a trigger would copy matches[2] with color information and decho it to a Geyser miniconsole stored as the variable enemylist<br />
enemylist:decho(copy2decho(matches[2]))<br />
</syntaxhighlight><br />
<br />
==copy2html==<br />
; copy2html([window], [stringToCopy], [instanceToCopy])<br />
: Copies a string from the current line of window, including color information in html format for echoing to a label.<br />
{{MudletVersion|4.8}}<br />
<br />
; Parameters<br />
* ''window'' (optional):<br />
: the window to copy the text from. Defaults to "main"<br />
* ''stringToCopy'' (optional): <br />
: the string to copy. Defaults to copying the entire line<br />
* ''instanceToCopy'' (optional):<br />
: the instance of the string to copy. Defaults to 1<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This copies the current line on the main console and echos it to a label named "TestLabel"<br />
echo("TestLabel", copy2html())<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- This when put into a trigger would copy matches[2] with color information and echo it to a Geyser label stored as the variable enemylist<br />
enemylist:echo(copy2html(matches[2]))<br />
</syntaxhighlight><br />
<br />
==createBuffer==<br />
;createBuffer(name)<br />
: Creates a named buffer for formatted text, much like a miniconsole, but the buffer is not intended to be shown on the screen - use it for formatting text or storing formatted text.<br />
<br />
: See also: [[#selectString|selectString()]], [[#selectCurrentLine|selectCurrentLine()]], [[#copy|copy()]], [[#paste|paste()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name of the buffer to create.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This creates a named buffer called "scratchpad"<br />
createBuffer("scratchpad")<br />
</syntaxhighlight><br />
<br />
==createCommandLine==<br />
;createCommandLine([name of userwindow], name, x, y, width, height)<br />
: Creates a new command line inside the main window of Mudlet. If only a command line inside a miniConsole/UserWindow is needed see [[Manual:UI_Functions#enableCommandLine|enableCommandLine()]].<br />
: You can use [[Manual:Mudlet_Object_Functions#appendCmdLine|appendCmdLine()]] / [[Manual:Mudlet_Object_Functions#getCmdLine|getCmdLine()]] and other command line functions to customize the input.<br />
{{note}} [[Manual:UI_Functions#setCmdLineAction|setCmdLineAction]] allows you to attach an action to your command line input.<br />
<br />
: Returns true or false.<br />
<br />
: See also: [[Manual:UI_Functions#enableCommandLine|enableCommandLine()]], [[Manual:UI_Functions#disableCommandLine|disableCommandLine()]], [[Manual:Mudlet_Object_Functions#clearCmdLine|clearCmdLine()]], [[Manual:Mudlet_Object_Functions#getCmdLine|getCmdLine()]], [[Manual:Mudlet_Object_Functions#printCmdLine|printCmdLine()]], [[Manual:Mudlet_Object_Functions#appendCmdLine|appendCmdLine()]]<br />
<br />
;Parameters<br />
* ''name of userwindow:''<br />
: Name of userwindow the command line is created in. Optional, defaults to the main window if not provided.<br />
* ''name:''<br />
: The name of the command line. Must be unique. Passed as a string.<br />
* ''x'', ''y'', ''width'', ''height''<br />
: Parameters to set the command line size and location - it is also possible to set them by using [[Manual:Lua_Functions#moveWindow|moveWindow()]] and [[Manual:Lua_Functions#resizeWindow|resizeWindow()]], as createCommandLine() will only set them once.<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
==createConsole==<br />
;createConsole([name of userwindow], consoleName, fontSize, charsPerLine, numberOfLines, Xpos, Ypos)<br />
: Makes a new miniconsole which can be sized based upon the width of a 'W' character and the extreme top and bottom positions any character of the font should use. The background will be black, and the text color white.<br />
<br />
;Parameters<br />
* ''name of userwindow:''<br />
: Name of userwindow your new miniconsole is created in. Optional, defaults to the main window if not provided.<br />
* ''consoleName:''<br />
: The name of your new miniconsole. Passed as a string.<br />
* ''fontSize:''<br />
: The font size to use for the miniconsole. Passed as an integer number.<br />
* ''charsPerLine:''<br />
: How many characters wide to make the miniconsole. Passed as an integer number.<br />
* ''numberOfLines:''<br />
: How many lines high to make the miniconsole. Passed as an integer number.<br />
* ''Xpos:''<br />
: X position of miniconsole. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''Ypos:''<br />
: Y position of miniconsole. Measured in pixels, with 0 being the very top. Passed as an integer number.<br />
<br />
{{note}}<br />
userwindow argument only available in 4.6.1+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- this will create a console with the name of "myConsoleWindow", font size 8, 80 characters wide,<br />
-- 20 lines high, at coordinates 300x,400y<br />
createConsole("myConsoleWindow", 8, 80, 20, 200, 400)<br />
</syntaxhighlight><br />
<br />
{{note}}<br />
''(For Mudlet Makers)'' This function is implemented outside the application's core via the '''GUIUtils.lua''' file of the Mudlet supporting Lua code using [[Manual:UI_Functions#createMiniConsole|createMiniConsole()]] and other functions to position and size the mini-console and configure the font.<br />
<br />
==createGauge==<br />
;createGauge([name of userwindow], name, width, height, Xpos, Ypos, gaugeText, r, g, b, orientation)<br />
;createGauge([name of userwindow], name, width, height, Xpos, Ypos, gaugeText, colorName, orientation)<br />
: Creates a gauge that you can use to express completion with. For example, you can use this as your healthbar or xpbar.<br />
: See also: [[Manual:Lua_Functions#moveGauge|moveGauge()]], [[Manual:Lua_Functions#setGauge|setGauge()]], [[Manual:Lua_Functions#setGaugeText|setGaugeText()]], [[#setGaugeStyleSheet|setGaugeStyleSheet()]]<br />
<br />
;Parameters<br />
* ''name of userwindow:''<br />
: Name of userwindow the gauge is created in. Optional, defaults to the main window if not provided.<br />
* ''name:''<br />
: The name of the gauge. Must be unique, you can not have two or more gauges with the same name. Passed as a string.<br />
* ''width:''<br />
: The width of the gauge, in pixels. Passed as an integer number.<br />
* ''height:''<br />
: The height of the gauge, in pixels. Passed as an integer number.<br />
* ''Xpos:''<br />
: X position of gauge. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''Ypos:''<br />
: Y position of gauge. Measured in pixels, with 0 being the very top. Passed as an integer number.<br />
* ''gaugeText:''<br />
: Text to display on the gauge. Passed as a string, unless you do not wish to have any text, in which case you pass nil<br />
* ''r:''<br />
: The red component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''g:''<br />
: The green component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''b:''<br />
: The blue component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''colorName:''<br />
: the name of color for the gauge. Passed as a string.<br />
* ''orientation:''<br />
: the gauge orientation. Can be horizontal (fills from left to right), vertical (fills bottom to top), goofy (fills right to left), or batty (fills top to bottom).<br />
<br />
{{note}}<br />
userwindow argument only available in 4.6.1+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This would make a gauge at that's 300px width, 20px in height, located at Xpos and Ypos and is green.<br />
-- The second example is using the same names you'd use for something like [[fg]]() or [[bg]]().<br />
createGauge("healthBar", 300, 20, 30, 300, nil, 0, 255, 0)<br />
createGauge("healthBar", 300, 20, 30, 300, nil, "green")<br />
<br />
<br />
-- If you wish to have some text on your label, you'll change the nil part and make it look like this:<br />
createGauge("healthBar", 300, 20, 30, 300, "Now with some text", 0, 255, 0)<br />
-- or<br />
createGauge("healthBar", 300, 20, 30, 300, "Now with some text", "green")<br />
</syntaxhighlight><br />
<br />
{{note}}<br />
If you want to put text on the back of the gauge when it's low, use an echo with the <gauge name>_back.<br />
<syntaxhighlight lang="lua"><br />
echo("healthBar_back", "This is a test of putting text on the back of the gauge!")<br />
</syntaxhighlight><br />
<br />
==createLabel==<br />
;createLabel([name of userwindow], name, Xpos, Ypos, width, height, fillBackground, [enableClickthrough])<br />
: Creates a highly manipulable overlay which can take some css and html code for text formatting. Labels are clickable, and as such can be used as a sort of button. Labels are meant for small variable or prompt displays, messages, images, and the like. You should not use them for larger text displays or things which will be updated rapidly and in high volume, as they are much slower than miniconsoles.<br />
: Returns true or false.<br />
: See also: [[Manual:Lua_Functions#hideWindow|hideWindow()]], [[Manual:Lua_Functions#showWindow|showWindow()]], [[Manual:Lua_Functions#resizeWindow|resizeWindow()]], [[Manual:Lua_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:Lua_Functions#setTextFormat|setTextFormat()]], [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#moveWindow|moveWindow()]], [[Manual:Lua_Functions#setBackgroundColor|setBackgroundColor()]], [[Manual:Lua_Functions#getMainWindowSize|getMainWindowSize()]], [[Manual:Lua_Functions#calcFontSize|calcFontSize()]], [[Manual:Lua_Functions#deleteLabel|deleteLabel()]]<br />
<br />
;Parameters<br />
* ''name of userwindow:'' Name of userwindow label is created in. Optional, defaults to the main window if not provided.<br />
* ''name:'' name of the label. Must be unique, you can not have two or more labels with the same name. Passed as a string.<br />
* ''Xpos:'' X position of the label. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''Ypos:'' Y position of the label. Measured in pixels, with 0 being the very top. Passed as an integer number.<br />
* ''width:'' width of the label, in pixels. Passed as an integer number.<br />
* ''height:'' height of the label, in pixels. Passed as an integer number.<br />
* ''fillBackground:'' whether or not to display the background. Passed as integer number (1 or 0) or as boolean (true, false). 1 or true will display the background color, 0 or false will not.<br />
* ''enableClickthrough:'' whether or not enable clickthrough on this label. Passed as integer number (1 or 0) or as boolean (true, false). 1 or true will enable clickthrough, 0 or false will not. Optional, defaults to clickthrough not enabled if not provided.<br />
<br />
{{note}}<br />
userwindow argument only available in 4.6.1+<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
-- a label situated at x=300 y=400 with dimensions 100x200<br />
createLabel("a very basic label",300,400,100,200,1)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- this example creates a transparent overlay message box to show a big warning message "You are under attack!" in the middle<br />
-- of the screen. Because the background color has a transparency level of 150 (0-255, with 0 being completely transparent<br />
-- and 255 opaque) the background text can still be read through.<br />
local width, height = getMainWindowSize()<br />
createLabel("messageBox",(width/2)-300,(height/2)-100,250,150,1)<br />
resizeWindow("messageBox",500,70)<br />
moveWindow("messageBox", (width/2)-300,(height/2)-100 )<br />
setBackgroundColor("messageBox", 255, 204, 0, 200)<br />
echo("messageBox", [[<p style="font-size:35px"><b><center><font color="red">You are under attack!</font></center></b></p>]])<br />
<br />
-- you can also make it react to clicks!<br />
mynamespace = {<br />
messageBoxClicked = function()<br />
echo("hey you've clicked the box!\n")<br />
end<br />
}<br />
<br />
setLabelClickCallback("messageBox", "mynamespace.messageBoxClicked")<br />
<br />
<br />
-- uncomment code below to make it also hide after a short while<br />
-- tempTimer(2.3, [[hideWindow("messageBox")]] ) -- close the warning message box after 2.3 seconds<br />
</syntaxhighlight><br />
<br />
==createMiniConsole==<br />
;createMiniConsole([name of userwindow], name, x, y, width, height)<br />
: Opens a miniconsole window inside the main window of Mudlet. This is the ideal fast colored text display for everything that requires a bit more text, such as status screens, chat windows, etc. Unlike labels, you cannot have transparency in them.<br />
: You can use [[Manual:Lua_Functions#clearWindow|clearWindow()]] / [[Manual:Lua_Functions#moveCursor|moveCursor()]] and other functions for this window for custom printing as well as copy & paste functions for colored text copies from the main window. [[Manual:Lua_Functions#setWindowWrap|setWindowWrap()]] will allow you to set word wrapping, and move the main window to make room for miniconsole windows on your screen (if you want to do this as you can also layer mini console and label windows) see [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#setBorderColor|setBorderColor()]] functions.<br />
<br />
: Returns true or false.<br />
<br />
: See also: [[Manual:Lua_Functions#createLabel|createLabel()]], [[Manual:Lua_Functions#hideWindow|hideWindow()]], [[Manual:Lua_Functions#showWindow|showWindow()]], [[Manual:Lua_Functions#resizeWindow|resizeWindow()]], [[Manual:Lua_Functions#setTextFormat|setTextFormat()]], [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#moveWindow|moveWindow()]], [[Manual:Lua_Functions#setMiniConsoleFontSize|setMiniConsoleFontSize()]], [[Manual:Lua_Functions#handleWindowResizeEvent|handleWindowResizeEvent()]], [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#setWindowWrap|setWindowWrap()]], [[Manual:Lua_Functions#getMainWindowSize|getMainWindowSize()]], [[Manual:Lua_Functions#setMainWindowSize|setMainWindowSize()]], [[Manual:Lua_Functions#calcFontSize|calcFontSize()]]<br />
<br />
;Parameters<br />
* ''name of userwindow:'' (available in Mudlet 4.6.1+)<br />
: (Optional) name of userwindow the miniconsole is created in. Defaults to the main window if not provided.<br />
* ''name:''<br />
: The name of the miniconsole. Must be unique. Passed as a string.<br />
* ''x'', ''y'', ''width'', ''height''<br />
: Parameters to set set the window size and location - in Mudlet version 2.1 and below it's best to set them via [[Manual:Lua_Functions#moveWindow|moveWindow()]] and [[Manual:Lua_Functions#resizeWindow|resizeWindow()]], as createMiniConsole() will only set them once. Starting with Mudlet version 3.0, however, that is fine and calling createMiniConsole() will re-position your miniconsole appropriately.<br />
<br />
;Example<br />
<br />
==creplace==<br />
;creplace([window, ]text)<br />
: Replaces the output line from the game with a colour-tagged string.<br />
See Also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:Lua_Functions#cinsertText|cinsertText()]]<br />
;Parameters<br />
* ''window:''<br />
*: The window to replace the selection in. Optional, defaults to the main window if not provided.<br />
* ''text:''<br />
*: The text to display, with color names inside angle brackets as with [[Manual:Lua_Functions#cecho|cecho()]]. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectCaptureGroup(1)<br />
creplace("<magenta>[ALERT!]: <reset>"..matches[2])<br />
</syntaxhighlight><br />
<br />
==creplaceLine==<br />
;creplaceLine ([window], text)<br />
: Replaces the output line from the game with a colour-tagged string.<br />
See Also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:Lua_Functions#cinsertText|cinsertText()]]<br />
;Parameters<br />
* ''window'' (optional):<br />
: the window to copy the text from. Defaults to "main". Only supported in Mudlet 4.12+<br />
* ''text:''<br />
*: The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua">creplaceLine("<magenta>[ALERT!]: <reset>"..line)<br />
</syntaxhighlight><br />
<br />
==decho==<br />
;decho ([name of console,] text)<br />
: Color changes can be made using the format <FR,FG,FB:BR,BG,BB,[BA]> where each field is a number from 0 to 255. The background portion can be omitted using <FR,FG,FB> or the foreground portion can be omitted using <:BR,BG,BB,[BA]>. Arguments 2 and 3 set the default fore and background colors for the string using the same format as is used within the string, sans angle brackets, e.g. ''decho("<50,50,0:0,255,0>test")''.<br />
:You can also include <code><nowiki><i>italics</i></nowiki></code>, <code><nowiki><b>bold</b></nowiki></code> and <code><nowiki><u>underline</u></nowiki></code> tags.<br />
<br />
: See also: [[#cecho|cecho()]], [[#hecho|hecho()]], [[#copy2decho|copy2decho()]]<br />
<br />
;Parameters<br />
* ''name of console''<br />
: (Optional) Name of the console to echo to. If no name is given, this will defaults to the main window.<br />
* ''text:''<br />
: The text that you’d like to echo with embedded color tags. Tags take the RGB values only, see below for an explanation.<br />
<br />
<br />
{{note}}<br />
Optional background transparancy parameter (BA) available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
decho("<50,50,0:0,255,0>test")<br />
<br />
decho("miniconsolename", "<50,50,0:0,255,0>test")<br />
<br />
decho("\n<255,0,0>Red text with <i>italics</i>, <u>underline</u> and <b>bold</b> formatting.")<br />
</syntaxhighlight><br />
<br />
==dechoLink==<br />
;dechoLink([windowName], text, command, hint, true)<br />
: Echos a piece of text as a clickable link, at the end of the current selected line - similar to [[Manual:Lua_Functions#decho|decho()]]. This version allows you to use colours within your link text.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) allows selection between sending the link to a miniconsole or the "main" window.<br />
* ''text:''<br />
: text to display in the echo. Same as a normal [[Manual:Lua_Functions#decho|decho()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''true:''<br />
: requires argument for the colouring to work.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
dechoLink("<50,50,0:0,255,0>press me!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
dechoLink("<50,50,0:0,255,0>press me!", [[send("hi")]], "This is a tooltip", true)<br />
</syntaxhighlight><br />
<br />
==dechoPopup==<br />
;dechoPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current line, like [[#decho|decho()]]. 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.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code strings to do or a functions (since Mudlet 4.11). ie, <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
dechoPopup("<255,0,0>activities<r> to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"}, true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
dechoPopup("<255,0,0>activities<r> to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"}, true)<br />
</syntaxhighlight><br />
<br />
==dinsertLink==<br />
;dinsertLink([windowName], text, command, hint, true)<br />
: Echos a piece of text as a clickable link, at the end of the current cursor position - similar to [[#dinsertText|dinsertText()]]. This version allows you to use colours within your link text.<br />
<br />
: See also: [[#insertLink|insertLink()]], [[#hinsertLink|hinsertLink()]]<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: optional parameter, allows selection between sending the link to a miniconsole or the main window.<br />
* ''text:''<br />
: text to display in the echo. Same as a normal [[Manual:Lua_Functions#decho|decho()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''true:''<br />
: requires argument for the colouring to work.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
dinsertLink("<255,0,0>press <165,42,42:255,255,255>me!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
dinsertLink("<255,0,0>press <165,42,42:255,255,255>me!", [[send("hi")]], "This is a tooltip", true)<br />
</syntaxhighlight><br />
<br />
==dinsertPopup==<br />
;dinsertPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current cursor position, like [[#dinsertText|dinsertText()]]. 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.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. ie, <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
dinsertPopup("<255,0,0>activities<r> to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"}, true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
dinsertPopup("<255,0,0>activities<r> to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"}, true)<br />
</syntaxhighlight><br />
<br />
== deleteLabel ==<br />
; deleteLabel(labelName)<br />
<br />
: Deletes and removes a label from the screen. Note that if you'd like to show the label again, it is much more performant to hide/show it instead.<br />
<br />
: Note that you shouldn't use the Geyser label associated with the label you delete afterwards - that doesn't make sense and Geyser right now wouldn't know that it's been deleted, either.<br />
<br />
: See also: [[#hideWindow|hideWindow()]], [[#showWindow|showWindow()]], [[#createLabel|createLabel()]]<br />
<br />
; Parameters<br />
<br />
* ''labelName'': name of the label to delete.<br />
<br />
<syntaxhighlight lang="lua"><br />
createLabel("a very basic label",300,400,100,200,1)<br />
setBackgroundColor("a very basic label", 255, 204, 0, 200)<br />
<br />
-- delete the label after 3 seconds<br />
tempTimer(3, function()<br />
deleteLabel("a very basic label")<br />
end)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.5}}<br />
<br />
==deleteLine==<br />
;deleteLine([windowName])<br />
: Deletes the current line under the user cursor. This is a high speed gagging tool and is very good at this task, but is only meant to be use when a line should be omitted entirely in the output. If you echo() to that line it will not be shown, and lines deleted with deleteLine() are simply no longer rendered. This is purely visual - triggers will still fire on the line as expected.<br />
: See also: [[Manual:Lua_Functions#replace|replace()]], [[Manual:Lua_Functions#wrapLine|wrapLine()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to delete the line in. If no name is given, it just deletes the line it is used on.<br />
<br />
{{note}} for replacing text, [[Manual:Lua_Functions#replace|replace()]] is the proper option; doing the following: <code>selectCurrentLine(); replace(""); cecho("new line!\n")</code> is better.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- deletes the line - just put this command into the big script box. Keep the case the same -<br />
-- it has to be deleteLine(), not Deleteline(), deleteline() or anything else<br />
deleteLine()<br />
<br />
--This example creates a temporary line trigger to test if the next line is a prompt, and if so gags it entirely.<br />
--This can be useful for keeping a pile of prompts from forming if you're gagging chat channels in the main window<br />
--Note: isPrompt() only works on servers which send a GA signal with their prompt.<br />
tempLineTrigger(1, 1, [[if isPrompt() then deleteLine() end]])<br />
<br />
-- example of deleting multiple lines:<br />
deleteLine() -- delete the current line<br />
moveCursor(0,getLineNumber()-1) -- move the cursor back one line<br />
deleteLine() -- delete the previous line now<br />
</syntaxhighlight><br />
<br />
==deselect==<br />
;deselect([window name])<br />
: This is used to clear the current selection (to no longer have anything selected). Should be used after changing the formatting of text, to keep from accidentally changing the text again later with another formatting call.<br />
: See also: [[#selectString|selectString()]], [[#selectCurrentLine|selectCurrentLine()]]<br />
<br />
;Parameters<br />
* ''window name:''<br />
: (optional) The name of the window to stop having anything selected in. If name is not provided the main window will have its selection cleared.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This will change the background on an entire line in the main window to red, and then properly clear the selection to keep further<br />
--changes from effecting this line as well.<br />
selectCurrentLine()<br />
bg("red")<br />
deselect()<br />
</syntaxhighlight><br />
<br />
==disableClickthrough==<br />
; disableClickthrough(label)<br />
: Disables clickthrough for a label - making it act 'normal' again and receive clicks, doubleclicks, onEnter, and onLeave events. This is the default behaviour for labels.<br />
: See also: [[#enableClickthrough|enableClickthrough()]]<br />
<br />
;Parameters<br />
* ''label:''<br />
: Name of the label to restore clickability on.<br />
<br />
{{MudletVersion|3.17}}<br />
<br />
==disableCommandLine==<br />
; disableCommandLine(windowName)<br />
: Disables the command line for the miniConsole named ''windowName''<br />
: See Also: [[Manual:Lua_Functions#enableCommandLine|enableCommandLine()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of the miniConsole to disable the command line in.<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
==disableHorizontalScrollBar==<br />
; disableHorizontalScrollBar([windowName])<br />
: Disables the horizontal scroll bar for the miniConsole/userwindow ''windowName'' or the main window<br />
: See Also: [[Manual:Lua_Functions#enableHorizontalScrollBar|enableHorizontalScrollBar()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of the window to disable the scroll bar in. If "main" or not provided it is the main console.<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
==disableScrollBar==<br />
; disableScrollBar([windowName])<br />
: Disables the scroll bar for the miniConsole/userwindow ''windowName'' or the main window<br />
: See Also: [[Manual:Lua_Functions#enableScrollBar|enableScrollBar()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) The name of the window to disable the scroll bar in. If "main" or not provided it is the main console.<br />
<br />
==dreplace==<br />
;dreplace([window, ]text)<br />
: Replaces the output line from the game with a colour-tagged string.<br />
See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#dinsertText|dinsertText()]]<br />
;Parameters<br />
* ''window:''<br />
*: The window to replace the selection in. Optional, defaults to the main window if not provided.<br />
* ''text:''<br />
*: The text to display, as with [[Manual:Lua_Functions#decho|decho()]]<br />
:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectCaptureGroup(1)<br />
dreplace("<255,0,255>[ALERT!]: <r>"..matches[2])<br />
</syntaxhighlight><br />
<br />
==dreplaceLine==<br />
;dreplaceLine ([window], text)<br />
: Replaces the output line from the game with a colour-tagged string.<br />
{{MudletVersion|4.12}}<br />
See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#dinsertText|dinsertText()]]<br />
;Parameters<br />
* ''window'' (optional):<br />
: the window to copy the text from. Defaults to "main".<br />
* ''text:''<br />
*: The text to display, with RGB color values inside angle brackets <>, ie ''<128,0,0>''. If you'd like to use a background color, put it after a colon : - ''<:128,0,0>''. You can use the ''<r>'' tag to reset to the default color. <br />
:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua">dreplaceLine("<255,0,255>[ALERT!]: <r>"..line)<br />
</syntaxhighlight><br />
<br />
==echoLink==<br />
;echoLink([windowName], text, command, hint, [useCurrentFormatElseDefault])<br />
: Echos a piece of text as a clickable link, at the end of the current selected line - similar to [[Manual:Lua_Functions#echo|echo()]].<br />
<br />
: See also: [[#cechoLink|cechoLink()]], [[#hechoLink|hechoLink()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) either be none or "main" for the main console, or a miniconsole / userwindow name.<br />
* ''text:''<br />
: Text to display in the echo. Same as a normal echo().<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: Text for the tooltip to be displayed when the mouse is over the link.<br />
* ''useCurrentFormatElseDefault:''<br />
: If true, then the link will use the current selection style (colors, underline, etc). If missing or false, it will use the default link style - blue on black underlined text.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
echoLink("press me!", function() send("hi") end, "This is a tooltip")<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
echoLink("press me!", [[send("hi")]], "This is a tooltip")<br />
<br />
-- do the same, but send this link to a miniConsole<br />
echoLink("my miniConsole", "press me!", function() send("hi") end, "This is a tooltip")<br />
</syntaxhighlight><br />
<br />
==echoUserWindow==<br />
;echoUserWindow(windowName, text)<br />
:This function will print text to both mini console windows, dock windows and labels. It is outdated however - [[Manual:Lua_Functions#echo|echo()]] instead.<br />
<br />
==echoPopup==<br />
;echoPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: 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.<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. i.e. <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
echoPopup("activities to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"})<br />
<br />
-- alternatively, put commands as text (in [[ and ]] to use quotation marks inside)<br />
echoPopup("activities to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"})<br />
</syntaxhighlight><br />
<br />
==enableClickthrough==<br />
; enableClickthrough(label)<br />
: Make a label 'invisible' to clicks - so if you have another label underneath, it'll be clicked on instead of this one on top.<br />
: This affects clicks, double-clicks, right-clicks, as well as the onEnter/onLeave events.<br />
: See also: [[#disableClickthrough|disableClickthrough()]]<br />
<br />
;Parameters<br />
* ''label:''<br />
: The name of the label to enable clickthrough on.<br />
<br />
{{MudletVersion|3.17}}<br />
<br />
==enableCommandLine==<br />
; enableCommandLine(windowName)<br />
: Enables the command line for the miniConsole named ''windowName''<br />
: See Also: [[Manual:Lua_Functions#disableCommandLine|disableCommandLine()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of the miniConsole to enable the command line in.<br />
<br />
{{note}} The command line name is the same as the miniConsole name<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
==enableHorizontalScrollBar==<br />
; enableHorizontalScrollBar([windowName])<br />
: Enables the horizontal scroll bar for the miniConsole/userwindow ''windowName'' or the main window<br />
: See Also: [[Manual:Lua_Functions#disableHorizontalScrollBar|disableHorizontalScrollBar()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of the window to enable the scroll bar in. If "main" or not provided it is the main console.<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
==enableScrollBar==<br />
; enableScrollBar([windowName])<br />
: Enables the scroll bar for the miniConsole/userwindow ''windowName'' or the main window<br />
: See Also: [[Manual:Lua_Functions#disableScrollBar|disableScrollBar()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of the window to enable the scroll bar in. If "main" or not provided it is the main console.<br />
<br />
==fg==<br />
; fg([window], colorName)<br />
: If used on a selection, sets the foreground color to ''colorName'' - otherwise, it will set the color of the next text-inserting calls (''echo(), insertText, echoLink()'', and others)<br />
: See Also: [[Manual:Lua_Functions#bg|bg()]], [[Manual:Lua_Functions#setBgColor|setBgColor()]]<br />
<br />
;Parameters<br />
* ''window:''<br />
: (optional) name of the miniconsole to operate on. If you'd like it to work on the main window, don't specify anything or use ''main'' (since Mudlet 3.0).<br />
* ''colorName:''<br />
: The name of the color to set the foreground to - list of possible names: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This would change the color of the text on the current line to green<br />
selectCurrentLine()<br />
fg("green")<br />
resetFormat()<br />
<br />
--This will echo red, green, blue in their respective colors<br />
fg("red")<br />
echo("red ")<br />
fg("green")<br />
echo("green ")<br />
fg("blue")<br />
echo("blue ")<br />
resetFormat()<br />
<br />
-- example of working on a miniconsole<br />
fg("my console", "red")<br />
echo("my console", "red text")<br />
</syntaxhighlight><br />
<br />
==getAvailableFonts==<br />
; getAvailableFonts()<br />
: This returns a "font - true" key-value list of available fonts which you can use to verify that Mudlet has access to a given font.<br />
: To install a new font with your package, include the font file in your zip/mpackage and it'll be automatically installed for you.<br />
<br />
: See also: [[#getFont|getFont()]], [[#setFont|setFont()]]<br />
<br />
{{MudletVersion|3.10}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- check if Ubuntu Mono is a font we can use<br />
if getAvailableFonts()["Ubuntu Mono"] then<br />
-- make the miniconsole use the font at size 16<br />
setFont("my miniconsole", "Ubuntu Mono")<br />
setFontSize("my miniconsole", 16)<br />
end<br />
</syntaxhighlight><br />
<br />
==getBgColor==<br />
; getBgColor(windowName)<br />
: This function returns the rgb values of the background color of the first character of the current selection on mini console (window) windowName. If windowName is omitted Mudlet will use the main screen.<br />
<br />
: See also: [[#setBgColor|setBgColor()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: A window to operate on - either a miniconsole or the main window.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local r,g,b;<br />
selectString("troll",1)<br />
r,g,b = getBgColor()<br />
if r == 255 and g == 0 and b == 0 then<br />
echo("HELP! troll is highlighted in red letters, the monster is aggressive!\n");<br />
end<br />
</syntaxhighlight><br />
<br />
==getBorderBottom==<br />
;getBorderBottom()<br />
: Returns the size of the bottom border of the main window in pixels. <br />
: See also: [[Manual:Lua_Functions#getBorderSizes|getBorderSizes()]], [[Manual:Lua_Functions#setBorderBottom|setBorderBottom()]]<br />
<br />
: {{MudletVersion|4.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderBottom(150)<br />
getBorderBottom()<br />
-- returns: 150<br />
</syntaxhighlight><br />
<br />
==getBorderLeft==<br />
;getBorderLeft()<br />
: Returns the size of the left border of the main window in pixels. <br />
: See also: [[Manual:Lua_Functions#getBorderSizes|getBorderSizes()]], [[Manual:Lua_Functions#setBorderLeft|setBorderLeft()]]<br />
<br />
: {{MudletVersion|4.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderLeft(5)<br />
getBorderLeft()<br />
-- returns: 5<br />
</syntaxhighlight><br />
<br />
==getBorderRight==<br />
;getBorderRight()<br />
: Returns the size of the right border of the main window in pixels. <br />
: See also: [[Manual:Lua_Functions#getBorderSizes|getBorderSizes()]], [[Manual:Lua_Functions#setBorderRight|setBorderRight()]]<br />
<br />
: {{MudletVersion|4.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderRight(50)<br />
getBorderRight()<br />
-- returns: 50<br />
</syntaxhighlight><br />
<br />
==getBorderSizes==<br />
;getBorderSizes()<br />
: Returns the a named table with the sizes of all borders of the main window in pixels. <br />
: See also: [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#getBorderTop|getBorderTop()]], [[Manual:Lua_Functions#getBorderRight|getBorderRight()]],[[Manual:Lua_Functions#getBorderBottom|getBorderBottom()]], [[Manual:Lua_Functions#getBorderLeft|getBorderLeft()]]<br />
<br />
: {{MudletVersion|4.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderSizes(100, 50, 150, 0)<br />
getBorderSizes()<br />
-- returns: { top = 100, right = 50, bottom = 150, left = 0 }<br />
getBorderSizes().right<br />
-- returns: 50<br />
</syntaxhighlight><br />
<br />
==getBorderTop==<br />
;getBorderTop()<br />
: Returns the size of the top border of the main window in pixels. <br />
: See also: [[Manual:Lua_Functions#getBorderSizes|getBorderSizes()]], [[Manual:Lua_Functions#setBorderTop|setBorderTop()]]<br />
<br />
: {{MudletVersion|4.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderTop(100)<br />
getBorderTop()<br />
-- returns: 100<br />
</syntaxhighlight><br />
<br />
==getClipboardText==<br />
;getClipboardText()<br />
: Returns any text that is currently present in the clipboard. <br />
: See also: [[#setClipboardText | setClipboardText()]]<br />
<br />
: {{note}} Note: Available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local clipboardContents = getClipboardText()<br />
echo("Clipboard: " .. clipboardContents)<br />
</syntaxhighlight><br />
<br />
==getColorWildcard==<br />
; getColorWildcard(ansi color number)<br />
: This function, given an ANSI color number ([[Manual:UI_Functions#isAnsiFgColor|list]]), will return all strings on the current line that match it.<br />
<br />
: See also: [[#isAnsiFgColor|isAnsiFgColor()]], [[#isAnsiBgColor|isAnsiBgColor()]]<br />
<br />
;Parameters<br />
* ''ansi color number:''<br />
: A color number ([[Manual:UI_Functions#isAnsiFgColor|list]]) to match.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- we can run this script on a line that has the players name coloured differently to easily capture it from<br />
-- anywhere on the line<br />
local match = getColorWildcard(14) -- this will be a table of every match<br />
<br />
if match then -- if there's a table, then we try and print it on the screen!<br />
echo("\nFound "..table.concat(match, ", ").."!") -- this will combine all captured strings and separate them with a comma so it's easy to read.<br />
else -- if there isn't something in match, then we haven't found anything to print on the screen!<br />
echo("\nDidn't find anyone.") <br />
end<br />
</syntaxhighlight><br />
<br />
==getColumnCount==<br />
;getColumnCount([windowName])<br />
: Gets the maximum number of columns (characters) that a given window can display on a single row, taking into consideration factors such as window width, font size, spacing, etc.<br />
<br />
;Parameters:<br />
* ''windowName'':<br />
: (optional) name of the window whose number of columns we want to calculate. By default it operates on the main window.<br />
<br />
{{MudletVersion|3.7}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
print("Maximum number of columns on the main window "..getColumnCount())<br />
</syntaxhighlight><br />
<br />
==getColumnNumber==<br />
;getColumnNumber([windowName])<br />
: Gets the absolute column number of the current user cursor.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) either be none or "main" for the main console, or a miniconsole / userwindow name.<br />
<br />
{{note}} the argument is available since Mudlet 3.0.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
HelloWorld = Geyser.MiniConsole:new({<br />
name="HelloWorld",<br />
x="70%", y="50%",<br />
width="30%", height="50%",<br />
})<br />
<br />
HelloWorld:echo("hello!\n")<br />
HelloWorld:echo("hello!\n")<br />
HelloWorld:echo("hello!\n")<br />
<br />
moveCursor("HelloWorld", 3, getLastLineNumber("HelloWorld"))<br />
-- should say 3, because we moved the cursor in the HellWorld window to the 3rd position in the line<br />
print("getColumnNumber: "..tostring(getColumnNumber("HelloWorld")))<br />
<br />
moveCursor("HelloWorld", 1, getLastLineNumber("HelloWorld"))<br />
-- should say 3, because we moved the cursor in the HellWorld window to the 1st position in the line<br />
print("getColumnNumber: "..tostring(getColumnNumber("HelloWorld")))<br />
</syntaxhighlight><br />
<br />
==getCurrentLine==<br />
;getCurrentLine([windowName])<br />
: Returns the content of the current line under the user cursor in the buffer. The Lua variable '''line''' holds the content of ''getCurrentLine()'' before any triggers have been run on this line. When triggers change the content of the buffer, the variable line will not be adjusted and thus hold an outdated string. ''line = getCurrentLine()'' will update line to the real content of the current buffer. This is important if you want to copy the current line after it has been changed by some triggers. ''selectString( line,1 )'' will return false and won't select anything because line no longer equals ''getCurrentLine()''. Consequently, ''selectString( getCurrentLine(), 1 )'' is what you need.<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window in which to select text.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
print("Currently selected line: "..getCurrentLine())<br />
</syntaxhighlight><br />
<br />
==getFgColor==<br />
; getFgColor(windowName)<br />
: This function returns the rgb values of the color of the first character of the current selection on mini console (window) windowName. If windowName is omitted Mudlet will use the main screen.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: A window to operate on - either a miniconsole or the main window.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectString("troll",1)<br />
local r,g,b = getFgColor()<br />
if r == 255 and g == 0 and b == 0 then<br />
echo("HELP! troll is written in red letters, the monster is aggressive!\n");<br />
end<br />
</syntaxhighlight><br />
<br />
==getFont==<br />
;getFont([windowName])<br />
: Gets the current font of the given window or console name. Can be used to get font of the main console, dockable userwindows and miniconsoles.<br />
: See also: [[#setFont|setFont()]], [[#setFontSize|setFontSize()]], [[#openUserWindow|openUserWindow()]], [[#getAvailableFonts|getAvailableFonts()]]<br />
<br />
{{MudletVersion|3.4}}<br />
{{note}} Since Mudlet 3.10, returns the actual font that was used in case you didn't have the required font when using [[#setFont|setFont()]].<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The window name to get font size of - can either be none or "main" for the main console, or a miniconsole/userwindow name.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The following will get the "main" console font size.<br />
display("Font in the main window: "..getFont())<br />
<br />
display("Font in the main window: "..getFont("main"))<br />
<br />
-- This will get the font size of a user window named "user window awesome".<br />
display("Font size: " .. getFont("user window awesome"))<br />
</syntaxhighlight><br />
<br />
==getFontSize==<br />
;getFontSize([windowName])<br />
: Gets the current font size of the given window or console name. Can be used to get font size of the Main console as well as dockable UserWindows.<br />
: See also: [[#setFontSize|setFontSize()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The window name to get font size of - can either be none or "main" for the main console, or a UserWindow name.<br />
<br />
{{MudletVersion|3.4}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The following will get the "main" console font size.<br />
local mainWindowFontSize = getFontSize()<br />
if mainWindowFontSize then<br />
display("Font size: " .. mainWindowFontSize)<br />
end<br />
<br />
local mainWindowFontSize = getFontSize("main")<br />
if mainWindowFontSize then<br />
display("Font size: " .. fs2)<br />
end<br />
<br />
-- This will get the font size of a user window named "user window awesome".<br />
local awesomeWindowFontSize = getFontSize("user window awesome")<br />
if awesomeWindowFontSize then<br />
display("Font size: " .. awesomeWindowFontSize)<br />
end<br />
</syntaxhighlight><br />
<br />
==getImageSize==<br />
;getImageSize(imageLocation)<br />
: Returns the width and the height of the given image. If the image can't be found, loaded, or isn't a valid image file - nil+error message will be returned instead.<br />
: See also: [[#createLabel|createLabel()]]<br />
<br />
;Parameters<br />
* ''imageLocation:''<br />
: Path to the image.<br />
<br />
{{MudletVersion|4.5}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local path = getMudletHomeDir().."/my-image.png"<br />
<br />
cecho("Showing dimensions of the picture in: "..path.."\n")<br />
<br />
local width, height = getImageSize(path)<br />
<br />
if not width then<br />
-- in case of an problem, we don't get a height back - but the error message<br />
cecho("error: "..height.."\n")<br />
else<br />
cecho(string.format("They are: %sx%s", width, height))<br />
end<br />
</syntaxhighlight><br />
<br />
==getLastLineNumber==<br />
;getLastLineNumber(windowName)<br />
:Returns the latest line's number in the main window or the miniconsole. This could be different from [[Manual:UI_Functions#getLineNumber|getLineNumber()]] if the cursor was moved around.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: name of the window to use. Either use ''main'' for the main window, or the name of the miniconsole.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- get the latest line's # in the buffer<br />
local latestline = getLastLineNumber("main")<br />
</syntaxhighlight><br />
<br />
==getLineCount==<br />
;getLineCount([windowName])<br />
:Gets the absolute amount of lines in the current console buffer<br />
<br />
; Parameters<br />
*''windowName''<br />
: Optional name of the window to get the line count of. Defaults to the main window.<br />
<br />
;Example<br />
''Need example''<br />
<br />
==getLines==<br />
;getLines([windowName,] from_line_number, to_line_number)<br />
: Returns a section of the content of the screen text buffer. Returns a Lua table with the content of the lines on a per line basis. The form value is ''result = {relative_linenumber = line}''.<br />
<br />
:Absolute line numbers are used.<br />
<br />
;Parameters<br />
* ''windowName''<br />
: (optional) name of the miniconsole/userwindow to get lines for, or "main" for the main window (Mudlet 3.17+)<br />
* ''from_line_number:''<br />
: First line number<br />
* ''to_line_number:''<br />
: End line number<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- retrieve & echo the last line:<br />
echo(getLines(getLineNumber()-1, getLineNumber())[1])<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- find out which server and port you are connected to (as per Mudlet settings dialog):<br />
local t = getLines(0, getLineNumber())<br />
<br />
local server, port<br />
<br />
for i = 1, #t do<br />
local s, p = t[i]:match("looking up the IP address of server:(.-):(%d+)")<br />
if s then server, port = s, p break end<br />
end<br />
<br />
display(server)<br />
display(port)<br />
</syntaxhighlight><br />
<br />
==getLineNumber==<br />
;getLineNumber([windowName])<br />
: Returns the absolute line number of the current user cursor (the y position). The cursor by default is on the current line the triggers are processing - which you can move around with [[Manual:Lua_Functions#moveCursor|moveCursor()]] and [[Manual:Lua_Functions#moveCursorEnd|moveCursorEnd()]]. This function can come in handy in combination when using with [[Manual:Lua_Functions#moveCursor|moveCursor()]] and [[Manual:Lua_Functions#getLines|getLines()]].<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the miniconsole to operate on. If you'd like it to work on the main window, don't specify anything.<br />
<br />
{{note}}<br />
The argument is available since Mudlet 3.0.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- use getLines() in conjuction with getLineNumber() to check if the previous line has a certain word<br />
if getLines(getLineNumber()-1, getLineNumber())[1]:find("attacks") then echo("previous line had the word 'attacks' in it!\n") end<br />
<br />
-- check how many lines you've got in your miniconsole after echoing some text.<br />
-- Note the use of moveCursorEnd() to update getLineNumber()'s output<br />
HelloWorld = Geyser.MiniConsole:new({<br />
name="HelloWorld",<br />
x="70%", y="50%",<br />
width="30%", height="50%",<br />
})<br />
<br />
print(getLineNumber("HelloWorld"))<br />
<br />
HelloWorld:echo("hello!\n")<br />
HelloWorld:echo("hello!\n")<br />
HelloWorld:echo("hello!\n")<br />
<br />
-- update the cursors position, as it seems to be necessary to do<br />
moveCursorEnd("HelloWorld")<br />
print(getLineNumber("HelloWorld"))<br />
</syntaxhighlight><br />
<br />
==getMainConsoleWidth==<br />
;getMainConsoleWidth()<br />
: Returns a single number; the width of the main console (game output) in pixels. This also accounts for any borders that have been set.<br />
<br />
: See also: [[#getMainWindowSize|getMainWindowSize()]]<br />
<br />
; Parameters<br />
:None<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Save width of the main console to a variable for future use.<br />
consoleWidth = getMainConsoleWidth()<br />
</syntaxhighlight><br />
<br />
==getMouseEvents==<br />
; events = getMouseEvents()<br />
<br />
:Returns a table of registered mouse events, including any of the additional arguments they may have.<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
;See also: [[Manual:Lua_Functions#addMouseEvent|addMouseEvent()]], [[Manual:Lua_Functions#removeMouseEvent|removeMouseEvent()]]<br />
<br />
;Returns <br />
* Returns a table with mouse event ''uniqueName'' as indexes, containing all the creation arguments as the sub-table members.<br />
<br />
==getMousePosition==<br />
;getMousePosition()<br />
: Returns the coordinates of the mouse's position, relative to the Mudlet window itself.<br />
<br />
; Parameters<br />
:None<br />
<br />
{{MudletVersion|3.1}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Retrieve x and y position of the mouse to determine where to create a new label, then use that position to create a new label<br />
local x, y = getMousePosition()<br />
createLabel("clickGeneratedLabel", x, y, 100, 100, 1)<br />
-- if the label already exists, just move it<br />
moveWindow("clickGeneratedLabel", x, y)<br />
-- and make it easier to notice<br />
setBackgroundColor("clickGeneratedLabel", 255, 204, 0, 200)<br />
</syntaxhighlight><br />
<br />
==getProfileTabNumber==<br />
;getProfileTabNumber()<br />
: Returns the current tab number you're in. If you have just one profile loaded, it'll always return 1 - otherwise it'll be the nth tab that is currently open.<br />
<br />
; Parameters<br />
:None<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
print(f"Current playing in tab #{getProfileTabNumber()}.")<br />
</syntaxhighlight><br />
<br />
==getMainWindowSize==<br />
;getMainWindowSize()<br />
: Returns two numbers, the width and height in pixels. This is useful for calculating the window dimensions and placement of custom GUI toolkit items like labels, buttons, mini consoles etc.<br />
: See also: [[#getUserWindowSize|getUserWindowSize()]], [[#setMainWindowSize|setMainWindowSize()]], [[#getMainConsoleWidth|getMainConsoleWidth()]]<br />
<br />
; Parameters<br />
:None<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--this will get the size of your main mudlet window and save them<br />
--into the variables mainHeight and mainWidth<br />
mainWidth, mainHeight = getMainWindowSize()<br />
</syntaxhighlight><br />
<br />
==getRowCount==<br />
;getRowCount([windowName])<br />
: Gets the maximum number of rows that a given window can display at once, taking into consideration factors such as window height, font type, spacing, etc.<br />
<br />
;Parameters:<br />
* ''windowName'':<br />
: (optional) name of the window whose maximum number of rows we want to calculate. By default it operates on the main window.<br />
<br />
{{MudletVersion|3.7}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
print("Maximum of rows on the main window "..getRowCount())<br />
</syntaxhighlight><br />
<br />
==getSelection==<br />
;getSelection([windowName])<br />
: Returns the text currently selected with [[#selectString|selectString()]], [[#selectSection|selectSection()]], or [[#selectCurrentLine|selectCurrentLine()]]. Note that this isn't the text currently selected with the mouse.<br />
: Also returns the start offset and length of the selection as second and third value.<br />
<br />
;Parameters:<br />
* ''windowName'':<br />
: (optional) name of the window to get the selection from. By default it operates on the main window.<br />
<br />
{{MudletVersion|3.16}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectCurrentLine()<br />
print("Current line contains: "..getSelection())<br />
</syntaxhighlight><br />
<br />
;retrieving the selection<br />
<syntaxhighlight lang="lua"><br />
text,offset,len = getSelection()<br />
-- manipulate the selection, e.g. to discover the color of characters other than the first<br />
-- then restore it<br />
selectSection(offset, len)<br />
</syntaxhighlight><br />
<br />
==getTextFormat==<br />
;getTextFormat([windowName])<br />
: Gets the current text format of the currently selected text. May be used with other console windows. The returned values come in a table containing text attribute names and their values. The values given will be booleans for: bold, italics, underline, overline, strikeout, and reverse - followed by color triplet tables for the foreground and background colors.<br />
: See Also: [[Manual:Lua_Functions#setTextFormat|setTextFormat()]]<br />
<br />
;Parameters<br />
* ''windowName''<br />
: (optional) Specify name of selected window. If no name or "main" is given, the format will be gathered from the main console.<br />
<br />
{{MudletVersion|3.20}}<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
-- A suitable test for getTextFormat()<br />
-- (copy it into an alias or a script)<br />
<br />
clearWindow()<br />
<br />
echo("\n")<br />
<br />
local SGR = string.char(27)..'['<br />
feedTriggers("Format attributes: '"..SGR.."1mBold"..SGR.."0m' '"..SGR.."3mItalic"..SGR.."0m' '"..SGR.."4mUnderline"..SGR.."0m' '"..SGR.."5mBlink"..SGR.."0m' '"..SGR.."6mF.Blink"..SGR.."0m' '"..SGR.."7mReverse"..SGR.."0m' '"..SGR.."9mStruckout"..SGR.."0m' '"..SGR.."53mOverline"..SGR.."0m'.\n")<br />
<br />
moveCursor(1,1)<br />
selectSection(1,1)<br />
<br />
local results = getTextFormat()<br />
echo("For first character in test line:\nBold detected: " .. tostring(results["bold"]))<br />
echo("\nItalic detected: " .. tostring(results["italic"]))<br />
echo("\nUnderline detected: " .. tostring(results["underline"]))<br />
echo("\nReverse detected: " .. tostring(results["reverse"]))<br />
echo("\nStrikeout detected: " .. tostring(results["strikeout"]))<br />
echo("\nOverline detected: " .. tostring(results["overline"]))<br />
echo("\nForeground color: (" .. results["foreground"][1] .. ", " .. results["foreground"][2] .. ", " .. results["foreground"][3] .. ")")<br />
echo("\nBackground color: (" .. results["background"][1] .. ", " .. results["background"][2] .. ", " .. results["background"][3] .. ")")<br />
<br />
selectSection(21,1)<br />
echo("\n\nFor individual parts of test text:")<br />
echo("\nBold detected (character 21): " .. tostring(results["bold"]))<br />
<br />
selectSection(28,1)<br />
echo("\nItalic detected (character 28): " .. tostring(results["italic"]))<br />
<br />
selectSection(37,1)<br />
echo("\nUnderline detected (character 37): " .. tostring(results["underline"]))<br />
<br />
selectSection(67,1)<br />
echo("\nReverse detected (character 67): " .. tostring(results["reverse"]))<br />
<br />
selectSection(77,1)<br />
echo("\nStrikeout detected (character 77): " .. tostring(results["strikeout"]))<br />
<br />
selectSection(89,1)<br />
echo("\nOverline detected (character 89): " .. tostring(results["overline"]))<br />
echo("\n")<br />
</syntaxhighlight><br />
<br />
==getUserWindowSize==<br />
;getUserWindowSize(windowName)<br />
: Returns two numbers, the width and height in pixels. This is useful for calculating the given userwindow dimensions and placement of custom GUI toolkit items like labels, buttons, mini consoles etc.<br />
: See also: [[#getMainWindowSize|getMainWindowSize()]]<br />
<br />
; Parameters<br />
* ''windowName''<br />
:the name of the userwindow we will get the dimensions from<br />
<br />
{{MudletVersion|4.6.1}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--this will get the size of your userwindow named "ChatWindow" and save them<br />
--into the variables mainHeight and mainWidth<br />
mainWidth, mainHeight = getUserWindowSize("ChatWindow")<br />
</syntaxhighlight><br />
<br />
<br />
==getWindowWrap==<br />
;getWindowWrap(windowName)<br />
: gets at what position in the line the will start word wrap.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the "main" console or user-created miniconsole which you want to be wrapped differently. If you want to wrap the main window, use windowName "main" or leave empty.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setWindowWrap("main", 10)<br />
display(getWindowWrap("main"))<br />
<br />
-- The following output will result in the main window console:<br />
-- 10<br />
</syntaxhighlight><br />
<br />
;Practical Example<br />
<syntaxhighlight lang="lua"><br />
-- display ======== line with maximum possible width without wrapping<br />
echo(string.rep("=", getWindowWrap("main")))<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.11}}<br />
<br />
==handleWindowResizeEvent==<br />
;handleWindowResizeEvent()<br />
: (''depreciated'') This function is depreciated and should not be used; it's only documented here for historical reference - use the [[Manual:Technical_Manual#sysWindowResizeEvent|sysWindowResizeEvent]] event instead.<br />
<br />
The standard implementation of this function does nothing. However, this function gets called whenever the main window is being manually resized. You can overwrite this function in your own scripts to handle window resize events yourself and e. g. adjust the screen position and size of your mini console windows, labels or other relevant GUI elements in your scripts that depend on the size of the main Window. To override this function you can simply put a function with the same name in one of your scripts thus overwriting the original empty implementation of this.<br />
<br />
; Parameters<br />
:None<br />
<br />
; Example<br />
<syntaxhighlight lang="lua"><br />
function handleWindowResizeEvent()<br />
-- determine the size of your screen<br />
WindowWidth=0;<br />
WindowHeight=0;<br />
WindowWidth, WindowHeight = getMainWindowSize();<br />
<br />
-- move mini console "sys" to the far right side of the screen whenever the screen gets resized<br />
moveWindow("sys",WindowWidth-300,0)<br />
end<br />
</syntaxhighlight><br />
<br />
==hasFocus==<br />
;hasFocus()<br />
: Returns ''true'' or ''false'' depending if Mudlet's main window is currently in focus (ie, the user isn't focused on another window, like a browser). If multiple profiles are loaded, this can also be used to check if a given profile is in focus.<br />
<br />
; Parameters<br />
:None<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
if attacked and not hasFocus() then<br />
runaway()<br />
else<br />
fight()<br />
end<br />
</syntaxhighlight><br />
<br />
==hecho==<br />
;hecho([windowName], text)<br />
: Echoes text that can be easily formatted with colour tags in the hexadecimal format. You can also use italics, bold and underline tags.<br />
: See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#cecho|cecho()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Can either be omitted or "main" for the main window, else specify the miniconsoles name.<br />
* ''text:''<br />
: The text to display, with color changes made within the string using the format |cFRFGFB,BRBGBB or #FRFGFB,BRBGBB where FR is the foreground red value, FG is the foreground green value, FB is the foreground blue value, BR is the background red value, etc., BRBGBB is optional. |r or #r can be used within the string to reset the colors to default. Hexadecimal color codes can be found here: https://www.color-hex.com/<br />
<br />
{{note}}<br />
Transparency for background in hex-format available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
hecho("\n#ffffff White text!")<br />
-- your text in white<br />
hecho("\n#ca0004 Red text! And now reset #rit to the default color")<br />
-- your text in red, then reset to default using #r<br />
hecho("\n#ffffff,ca0004 White text with a red background!")<br />
-- your text in white, against a red background<br />
hecho("\n|c0000ff Blue text, this time using |c instead of #")<br />
-- your text in blue, activated with |c vs #.<br />
hecho("\n#ff0000Red text with #iitalics#/i, |uunderline|/u and #bbold#/b formatting.")<br />
</syntaxhighlight><br />
<br />
==hechoLink==<br />
;hechoLink([windowName], text, command, hint, true)<br />
: Echos a piece of text as a clickable link, at the end of the current selected line - similar to [[Manual:Lua_Functions#hecho|hecho()]]. This version allows you to use colours within your link text.<br />
<br />
: See also: [[#cechoLink|cechoLink()]], [[#dechoLink|dechoLink()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) - allows selection between sending the link to a miniconsole or the ''main'' window.<br />
* ''text:''<br />
: text to display in the echo. Same as a normal [[Manual:Lua_Functions#hecho|hecho()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''true:''<br />
: requires argument for the colouring to work.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
hechoLink("|ca00040black!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- # format also works<br />
hechoLink("#ca00040black!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
hechoLink("#ca00040black!", [[send("hi")]], "This is a tooltip", true)<br />
</syntaxhighlight><br />
<br />
==hechoPopup==<br />
;hechoPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current line, like [[#hecho|hecho()]]. 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.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. ie, <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
hechoPopup("#ff0000activities#r to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"}, true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
hechoPopup("#ff0000activities#r to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"}, true)<br />
</syntaxhighlight><br />
<br />
==hideGauge==<br />
;hideGauge(gaugeName)<br />
: hides the given gauge.<br />
<br />
: See also: [[#showGauge|showGauge()]], [[#createGauge|createGauge()]]<br />
<br />
;Parameters<br />
* ''gaugeName:''<br />
: name of the gauge to show.<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
hideGauge("my gauge")<br />
showGauge("my gauge")<br />
</syntaxhighlight><br />
<br />
==hinsertLink==<br />
;hinsertLink([windowName], text, command, hint, true)<br />
: Echos a piece of text as a clickable link, at the end of the current cursor position - similar to [[#hinsertText|hinsertText()]]. This version allows you to use colours within your link text.<br />
<br />
: See also: [[#insertLink|insertLink()]], [[#dinsertLink|dinsertLink()]]<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: optional parameter, allows selection between sending the link to a miniconsole or the main window.<br />
* ''text:''<br />
: text to display in the echo. Same as a normal [[Manual:Lua_Functions#hecho|hecho()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''true:''<br />
: requires argument for the colouring to work.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
hinsertLink("#ff0000press #a52a2a,ffffffme!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
hinsertLink("#ff0000press #a52a2a,ffffffme!", [[send("hi")]], "This is a tooltip", true)<br />
</syntaxhighlight><br />
<br />
==hinsertPopup==<br />
;hinsertPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current cursor position, like [[#hinsertText|hinsertText()]]. 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.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code strings to do or a functions (since Mudlet 4.11). ie, <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
hinsertPopup("#ff0000activities#r to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"}, true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
hinsertPopup("#ff0000activities#r to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"}, true)<br />
</syntaxhighlight><br />
<br />
==hreplaceLine==<br />
;hreplaceLine ([window], text)<br />
: Replaces the output line from the game with a colour-tagged string.<br />
{{MudletVersion|4.12}}<br />
See Also: [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:Lua_Functions#hinsertText|hinsertText()]]<br />
;Parameters<br />
* ''window'' (optional):<br />
: the window to copy the text from. Defaults to "main".<br />
* ''text:''<br />
*: The text to display, with hex color values , ie ''#ff00ff''. If you'd like to use a background color, put it after a comma , - ''#,ff99ff''. You can use the ''#r'' tag to reset to the default color. <br />
:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua">hreplaceLine("#ff00ff[ALERT!]: #r"..line)<br />
</syntaxhighlight><br />
<br />
==hreplace==<br />
;hreplace([window, ]text)<br />
: Replaces the output line from the game with a colour-tagged string.<br />
See Also: [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:Lua_Functions#hinsertText|hinsertText()]]<br />
;Parameters<br />
* ''window:''<br />
*: The window to replace the selection in. Optional, defaults to the main window if not provided.<br />
* ''text:''<br />
*: The text to display, as with [[Manual:Lua_Functions#hecho|hecho()]]<br />
:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectCaptureGroup(1)<br />
hreplace("#EE00EE[ALERT!]: #r"..matches[2])<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.5}}<br />
<br />
==hideToolBar==<br />
;hideToolBar(name)<br />
: Hides the toolbar with the given name name and makes it disappear. If all toolbars of a tool bar area (top, left, right) are hidden, the entire tool bar area disappears automatically.<br />
<br />
;Parameters<br />
* ''name:''<br />
: name of the button group to hide<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
hideToolBar("my offensive buttons")<br />
</syntaxhighlight><br />
<br />
==hideWindow==<br />
;hideWindow(name)<br />
: This function hides a '''mini console''', a '''user window''' or a '''label''' with the given name. To show it again, use [[Manual:Lua_Functions#showWindow|showWindow()]].<br />
<br />
: See also: [[#createMiniConsole|createMiniConsole()]], [[#createLabel|createLabel()]], [[#deleteLabel|deleteLabel()]]<br />
<br />
;Parameters<br />
* ''name''<br />
: specifies the label or console you want to hide.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
function miniconsoleTest()<br />
local windowWidth, windowHeight = getMainWindowSize()<br />
<br />
-- create the miniconsole<br />
createMiniConsole("sys", windowWidth-650,0,650,300)<br />
setBackgroundColor("sys",255,69,0,255)<br />
setMiniConsoleFontSize("sys", 8)<br />
-- wrap lines in window "sys" at 40 characters per line - somewhere halfway, as an example<br />
setWindowWrap("sys", 40)<br />
<br />
print("created red window top-right")<br />
<br />
tempTimer(1, function()<br />
hideWindow("sys")<br />
print("hid red window top-right")<br />
end)<br />
<br />
tempTimer(3, function()<br />
showWindow("sys")<br />
print("showed red window top-right")<br />
end)<br />
end<br />
<br />
miniconsoleTest()<br />
</syntaxhighlight><br />
<br />
==insertLink==<br />
;insertLink([windowName], text, command, hint, [useCurrentLinkFormat])<br />
: Inserts a piece of text as a clickable link at the current cursor position - similar to [[Manual:Lua_Functions#insertText|insertText()]].<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) the window to insert the link in - use either "main" or omit for the main window.<br />
* ''text:''<br />
: text to display in the window. Same as a normal [[Manual:Lua_Functions#echo|echo()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''useCurrentLinkFormat:''<br />
: (optional) true or false. If true, then the link will use the current selection style (colors, underline, etc). If missing or false, it will use the default link style - blue on black underlined text.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- link with the default blue on white colors<br />
insertLink("hey, click me!", function() echo("you clicked me!\n") end, "Click me popup")<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
insertLink("hey, click me!", [[echo("you clicked me!\n")]], "Click me popup")<br />
<br />
-- use current cursor colors by adding true at the end<br />
fg("red")<br />
insertLink("hey, click me!", function() echo("you clicked me!\n") end, "Click me popup", true)<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
==insertPopup==<br />
;insertPopup([windowName], text, {commands}, {hints}, [useCurrentLinkFormat])<br />
: Creates text with a left-clickable link, and a right-click menu for more options exactly where the cursor position is, similar to [[Manual:Lua_Functions#insertText|insertText()]]. The inserted 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.<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to - use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''name:''<br />
: the name of the console to operate on. If not using this in a miniConsole, use "main" as the name.<br />
* ''{lua code}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight>.<br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. ie, <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight>.<br />
* ''useCurrentLinkFormat:''<br />
: (optional) boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
insertPopup("activities to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"})<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
insertPopup("activities to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"})<br />
</syntaxhighlight><br />
<br />
==insertText==<br />
;insertText([windowName], text)<br />
: Inserts text at cursor postion in window - unlike [[Manual:Lua_Functions#echo|echo()]], which inserts the text at the end of the last line in the buffer (typically the one being processed by the triggers). You can use [[Manual:Lua_Functions#moveCursor|moveCursor()]] to move the cursor into position first.<br />
<br />
: insertHTML() also does the same thing as insertText, if you ever come across it.<br />
<br />
: See also: [[Manual:Lua_Functions#cinsertText|cinsertText()]]<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) The window to insert the text to.<br />
* ''text:''<br />
: The text you will insert into the current cursor position.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- move the cursor to the end of the previous line and insert some text<br />
<br />
-- move to the previous line<br />
moveCursor(0, getLineNumber()-1)<br />
-- move the end the of the previous line<br />
moveCursor(#getCurrentLine(), getLineNumber())<br />
<br />
fg("dark_slate_gray")<br />
insertText(' <- that looks nice.')<br />
<br />
deselect()<br />
resetFormat()<br />
moveCursorEnd()<br />
</syntaxhighlight><br />
<br />
==ioprint==<br />
;ioprint(text, some more text, ...)<br />
:Prints text to the to the stdout. This is only available if you [http://www.wikihow.com/Run-a-Program-on-Command-Prompt launched Mudlet from cmd.exe] on Windows, [http://www.wikihow.com/Open-Applications-Using-Terminal-on-Mac from the terminal] on Mac, or from the terminal on a Linux OS (launch the terminal program, type ''mudlet'' and press enter).<br />
<br />
Similar to [[Manual:Lua_Functions#echo|echo()]], but does not require a "\n" at the end for a newline and can print several items given to it. It cannot print whole tables. This function works similarly to the print() you will see in guides for Lua.<br />
<br />
This function is useful in working out potential crashing problems with Mudlet due to your scripts - as you will still see whatever it printed when Mudlet crashes.<br />
<br />
;Parameters<br />
* ''text:''<br />
: The information you want to display.<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
ioprint("hi!")<br />
ioprint(1,2,3)<br />
ioprint(myvariable, someothervariable, yetanothervariable)<br />
</syntaxhighlight><br />
<br />
==isAnsiBgColor==<br />
; isAnsiBgColor(bgColorCode)<br />
: This function tests if the first character of '''the current selection''' in the main console has the background color specified by bgColorCode.<br />
<br />
;Parameters<br />
* ''bgColorCode:''<br />
: A color code to test for, possible codes are:<br />
<br />
<syntaxhighlight lang="lua"><br />
0 = default text color<br />
1 = light black<br />
2 = dark black<br />
3 = light red<br />
4 = dark red<br />
5 = light green<br />
6 = dark green<br />
7 = light yellow<br />
8 = dark yellow<br />
9 = light blue<br />
10 = dark blue<br />
11 = light magenta<br />
12 = dark magenta<br />
13 = light cyan<br />
14 = dark cyan<br />
15 = light white<br />
16 = dark white<br />
</syntaxhighlight><br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectString( matches[1], 1 )<br />
if isAnsiBgColor( 5 ) then<br />
bg( "red" );<br />
resetFormat();<br />
echo( "yes, the background of the text is light green" )<br />
else<br />
echo( "no sorry, some other background color" )<br />
end<br />
</syntaxhighlight><br />
<br />
{{note}}<br />
The variable named matches[1] holds the matched trigger pattern - even in substring, exact match, begin of line substring trigger patterns or even color triggers that do not know about the concept of capture groups. Consequently, you can always test if the text that has fired the trigger has a certain color and react accordingly. This function is faster than using getBgColor() and then handling the color comparison in Lua.<br />
<br />
''Also note that the color code numbers are Mudlet specific, though they do represent the colors in the 16 ANSI color-set for the main console they are not in the same order and they additionally have the default background color in the zeroth position.''<br />
<br />
==isAnsiFgColor==<br />
; isAnsiFgColor(fgColorCode)<br />
: This function tests if the first character of '''the current selection''' in the main console has the foreground color specified by fgColorCode.<br />
<br />
;Parameters<br />
* ''fgColorCode:''<br />
: A color code to test for, possible codes are:<br />
<br />
<syntaxhighlight lang="lua"><br />
0 = default text color<br />
1 = light black<br />
2 = dark black<br />
3 = light red<br />
4 = dark red<br />
5 = light green<br />
6 = dark green<br />
7 = light yellow<br />
8 = dark yellow<br />
9 = light blue<br />
10 = dark blue<br />
11 = light magenta<br />
12 = dark magenta<br />
13 = light cyan<br />
14 = dark cyan<br />
15 = light white<br />
16 = dark white<br />
</syntaxhighlight><br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectString( matches[1], 1 )<br />
if isAnsiFgColor( 5 ) then<br />
bg( "red" );<br />
resetFormat();<br />
echo( "yes, the text is light green" )<br />
else<br />
echo( "no sorry, some other foreground color" )<br />
end<br />
</syntaxhighlight><br />
<br />
{{note}}<br />
The variable named matches[1] holds the matched trigger pattern - even in substring, exact match, begin of line substring trigger patterns or even color triggers that do not know about the concept of capture groups. Consequently, you can always test if the text that has fired the trigger has a certain color and react accordingly. This function is faster than using getFgColor() and then handling the color comparison in Lua.<br />
<br />
''Also note that the color code numbers are Mudlet specific, though they do represent the colors in the 16 ANSI color-set for the main console they are not in the same order and they additionally have the default foreground color in the zeroth position.''<br />
<br />
==loadWindowLayout==<br />
;loadWindowLayout()<br />
:Resets the layout of userwindows (floating miniconsoles) to the last saved state.<br />
<br />
:See also: [[#saveWindowLayout|saveWindowLayout()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
{{MudletVersion|3.2}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
loadWindowLayout()<br />
</syntaxhighlight><br />
<br />
==lowerWindow==<br />
;lowerWindow(labelName)<br />
:Moves the referenced label/console below all other labels/consoles. For the opposite effect, see: [[#raiseWindow | raiseWindow()]].<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: the name of the label/console you wish to move below the rest.<br />
<br />
{{MudletVersion|3.1}}<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
createLabel("blueLabel", 300, 300, 100, 100, 1) --creates a blue label<br />
setBackgroundColor("blueLabel", 50, 50, 250, 255)<br />
<br />
createLabel("redLabel", 350, 350, 100, 100, 1) --creates a red label which is placed on TOP of the blue label, as the last made label will sit at the top of the rest<br />
setBackgroundColor("redLabel", 250, 50, 50, 255)<br />
<br />
lowerWindow("redLabel") --lowers redLabel, causing blueLabel to be back on top<br />
</syntaxhighlight><br />
<br />
==moveCursor==<br />
;moveCursor([windowName], x, y)<br />
: Moves the user cursor of the window windowName, or the main window, to the absolute point (x,y). This function returns false if such a move is impossible e.g. the coordinates don’t exist. To determine the correct coordinates use [[Manual:Lua_Functions#getLineNumber|getLineNumber()]], [[Manual:Lua_Functions#getColumnNumber|getColumnNumber()]] and [[Manual:Lua_Functions#getLastLineNumber|getLastLineNumber()]]. The trigger engine will always place the user cursor at the beginning of the current line before the script is run. If you omit the windowName argument, the main screen will be used.<br />
<br />
: Returns ''true'' or ''false'' depending on if the cursor was moved to a valid position. Check this before doing further cursor operations - because things like deleteLine() might invalidate this.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) The window you are going to move the cursor in.<br />
* ''x:''<br />
: The horizontal axis in the window - that is, the letter position within the line.<br />
* ''y:''<br />
: The vertical axis in the window - that is, the line number.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- move cursor to the start of the previous line and insert -<(<br />
-- the first 0 means we want the cursor right at the start of the line,<br />
-- and getLineNumber()-1 means we want the cursor on the current line# - 1 which<br />
-- equals to the previous line<br />
moveCursor(0, getLineNumber()-1)<br />
insertText("-<(")<br />
<br />
-- now we move the cursor at the end of the previous line. Because the<br />
-- cursor is on the previous line already, we can use #getCurrentLine()<br />
-- to see how long it is. We also just do getLineNumber() because getLineNumber()<br />
-- returns the current line # the cursor is on<br />
moveCursor(#getCurrentLine(), getLineNumber())<br />
insertText(")>-")<br />
<br />
-- finally, reset it to the end where it was after our shenaningans - other scripts<br />
-- could expect the cursor to be at the end<br />
moveCursorEnd()<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- a more complicated example showing how to work with Mudlet functions<br />
<br />
-- set up the small system message window in the top right corner<br />
-- determine the size of your screen<br />
local WindowWidth, WindowHeight = getMainWindowSize()<br />
<br />
-- define a mini console named "sys" and set its background color<br />
createMiniConsole("sys",WindowWidth-650,0,650,300)<br />
setBackgroundColor("sys",85,55,0,255)<br />
<br />
-- you *must* set the font size, otherwise mini windows will not work properly<br />
setMiniConsoleFontSize("sys", 12)<br />
-- wrap lines in window "sys" at 65 characters per line<br />
setWindowWrap("sys", 60)<br />
-- set default font colors and font style for window "sys"<br />
setTextFormat("sys",0,35,255,50,50,50,0,0,0)<br />
-- clear the window<br />
clearUserWindow("sys")<br />
<br />
moveCursorEnd("sys")<br />
setFgColor("sys", 10,10,0)<br />
setBgColor("sys", 0,0,255)<br />
echo("sys", "test1---line1\n<this line is to be deleted>\n<this line is to be deleted also>\n")<br />
echo("sys", "test1---line2\n")<br />
echo("sys", "test1---line3\n")<br />
setTextFormat("sys",158,0,255,255,0,255,0,0,0);<br />
--setFgColor("sys",255,0,0);<br />
echo("sys", "test1---line4\n")<br />
echo("sys", "test1---line5\n")<br />
moveCursor("sys", 1,1)<br />
<br />
-- deleting lines 2+3<br />
deleteLine("sys")<br />
deleteLine("sys")<br />
<br />
-- inserting a line at pos 5,2<br />
moveCursor("sys", 5,2)<br />
setFgColor("sys", 100,100,0)<br />
setBgColor("sys", 255,100,0)<br />
insertText("sys","############## line inserted at pos 5/2 ##############")<br />
<br />
-- inserting a line at pos 0,0<br />
moveCursor("sys", 0,0)<br />
selectCurrentLine("sys")<br />
setFgColor("sys", 255,155,255)<br />
setBold( "sys", true );<br />
setUnderline( "sys", true )<br />
setItalics( "sys", true )<br />
insertText("sys", "------- line inserted at: 0/0 -----\n")<br />
<br />
setBold( "sys", true )<br />
setUnderline( "sys", false )<br />
setItalics( "sys", false )<br />
setFgColor("sys", 255,100,0)<br />
setBgColor("sys", 155,155,0)<br />
echo("sys", "*** This is the end. ***\n")<br />
</syntaxhighlight><br />
<br />
==moveCursorDown==<br />
;moveCursorDown([windowName,] [lines,] [keepHorizontal])<br />
: Moves the cursor in the given window down a specified number of lines.<br />
: See also: [[#moveCursor|moveCursor()]], [[#moveCursorUp|moveCursorUp()]], [[#moveCursorEnd|moveCursorEnd()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the miniconsole/userwindow, or "main" for the main window.<br />
<br />
* ''lines:''<br />
: (optional) number of lines to move cursor down by, or 1 by default.<br />
<br />
* ''keepHorizontal:''<br />
: (optional) true/false to specify if horizontal position should be retained, or reset to the start of the line otherwise.<br />
<br />
{{MudletVersion|3.17}}<br />
<br />
;Example<br />
'' Need example''<br />
<br />
==moveCursorUp==<br />
;moveCursorUp([windowName,] [lines,] [keepHorizontal])<br />
: Moves the cursor in the given window up a specified number of lines.<br />
: See also: [[#moveCursor|moveCursor()]], [[#moveCursorDown|moveCursorDown()]], [[#moveCursorEnd|moveCursorEnd()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the miniconsole/userwindow, or "main" for the main window.<br />
<br />
* ''lines:''<br />
: (optional) number of lines to move cursor up by, or 1 by default.<br />
<br />
* ''keepHorizontal:''<br />
: (optional) true/false to specify if horizontal position should be retained, or reset to the start of the line otherwise.<br />
<br />
{{MudletVersion|3.17}}<br />
<br />
;Example<br />
'' Need example''<br />
<br />
==moveCursorEnd==<br />
;moveCursorEnd([windowName])<br />
: Moves the cursor to the end of the buffer. "main" is the name of the main window, otherwise use the name of your user window.<br />
: See Also: [[Manual:Lua_Functions#moveCursor|moveCursor()]]<br />
<br />
: Returns true or false<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the miniconsole/userwindow, or "main" for the main window.<br />
<br />
;Example<br />
'' Need example''<br />
<br />
==moveGauge==<br />
;moveGauge(gaugeName, newX, newY)<br />
:Moves a gauge created with createGauge to the new x,y coordinates. Remember the coordinates are relative to the top-left corner of the output window.<br />
<br />
;Parameters<br />
* ''gaugeName:''<br />
: The name of your gauge<br />
* ''newX:''<br />
: The horizontal pixel location<br />
* ''newY:''<br />
: The vertical pixel location<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This would move the health bar gauge to the location 1200, 400<br />
moveGauge("healthBar", 1200, 400)<br />
</syntaxhighlight><br />
<br />
==moveWindow==<br />
;moveWindow(name, x, y)<br />
:This function moves window name to the given x/y coordinate. The main screen cannot be moved. Instead you’ll have to set appropriate border values → preferences to move the main screen e.g. to make room for chat or information mini consoles, or other GUI elements. In the future moveWindow() will set the border values automatically if the name parameter is omitted.<br />
<br />
:See Also: [[#createMiniConsole | createMiniConsole()]], [[#createLabel | createLabel()]], [[#handleWindowResizeEvent | handleWindowResizeEvent()]], [[#resizeWindow | resizeWindow()]], [[#setBorderSizes | setBorderSizes()]], [[#openUserWindow | openUserWindow()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name of your window<br />
* ''newX:''<br />
: The horizontal pixel location<br />
* ''newY:''<br />
: The vertical pixel location<br />
<br />
{{note}}<br />
Since Mudlet 3.7 this method can also be used on UserWindow consoles.<br />
<br />
==openUserWindow==<br />
;openUserWindow(windowName, [restoreLayout], [autoDock], [dockingArea])<br />
: Opens a user dockable console window for user output e.g. statistics, chat etc. If a window of such a name already exists, nothing happens. You can move these windows (even to a different screen on a system with a multi-screen display), dock them on any of the four sides of the main application window, make them into notebook tabs or float them.<br />
<br />
: See also: [[#resetUserWindowTitle|resetUserWindowTitle()]], [[#setUserWindowTitle|setUserWindowTitle()]], [[#saveWindowLayout|saveWindowLayout()]], [[#loadWindowLayout|loadWindowLayout()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: name of your window, it must be unique across ALL profiles if more than one is open (for multi-playing).<br />
* ''restoreLayout:'' (available in Mudlet 3.2+)<br />
: (optional) - only relevant, if ''false'' is provided. Then the window won't be restored to its last known position.<br />
* ''autoDock:'' (available in Mudlet 4.7+)<br />
: (optional) - only relevant, if ''false'' is provided. Then the window won't dock automatically at the corners.<br />
* ''dockingArea:'' (available in Mudlet 4.7+)<br />
: (optional) - the area your UserWindow will be docked at. possible docking areas your UserWindow will be created in (f" floating "t" top "b" bottom "r" right and "l" left). Docking area is "right" if not given any value.<br />
<br />
{{note}}<br />
Since Mudlet version 3.2, Mudlet will automatically remember the window's last position.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
openUserWindow("My floating window")<br />
cecho("My floating window", "<red>hello <blue>bob!")<br />
<br />
-- if you don't want Mudlet to remember its last position:<br />
openUserWindow("My floating window", false)<br />
</syntaxhighlight><br />
<br />
==paste==<br />
;paste(windowName)<br />
: Pastes the previously copied text including all format codes like color, font etc. at the current user cursor position. The [[#copy | copy()]] and [[#paste | paste()]] functions can be used to copy formated text from the main window to a user window without losing colors e. g. for chat windows, map windows etc.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of your window<br />
<br />
==prefix==<br />
;prefix(text, [writingFunction], [foregroundColor], [backgroundColor], [windowName])<br />
:Prefixes text at the beginning of the current line when used in a trigger.<br />
<br />
;Parameters<br />
* ''text:''<br />
: the information you want to prefix<br />
* "writingFunction:"<br />
: optional parameter, allows the selection of different functions to be used to write the text, valid options are: echo, cecho, decho, and hecho.<br />
* "foregroundColor:"<br />
: optional parameter, allows a foreground color to be specified if using the echo function using a color name, as with the fg() function<br />
* "backgroundColor:"<br />
: optional parameter, allows a background color to be specified if using the echo function using a color name, as with the bg() function<br />
* "windowName:"<br />
: optional parameter, allows the selection a miniconsole or the main window for the line that will be prefixed<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
-- Prefix the hours, minutes and seconds onto our prompt even though Mudlet has a button for that<br />
prefix(os.date("%H:%M:%S "))<br />
-- Prefix the time in red into a miniconsole named "my_console"<br />
prefix(os.date("<red>%H:%M:%S<reset>", cecho, nil, nil, "my_console"))<br />
</syntaxhighlight><br />
<br />
: See also: [[#suffix | suffix()]]<br />
<br />
==print==<br />
;print(text, some more text, ...)<br />
:Prints text to the main window. Similar to [[Manual:Lua_Functions#echo|echo()]], but does not require a "\n" at the end for a newline and can print several items given to it. It cannot print whole tables - use [[Manual:Lua_Functions#display|display()]] for those. This function works similarly to the print() you will see in guides for Lua.<br />
<br />
;Parameters<br />
* ''text:''<br />
: The information you want to display.<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
print("hi!")<br />
print(1,2,3)<br />
print(myvariable, someothervariable, yetanothervariable)<br />
</syntaxhighlight><br />
<br />
==raiseWindow==<br />
;raiseWindow(labelName)<br />
:Raises the referenced label/console above all over labels/consoles. For the opposite effect, see: [[#lowerWindow | lowerWindow()]].<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: the name of the label/console you wish to bring to the top of the rest.<br />
<br />
{{MudletVersion|3.1}}<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
createLabel("blueLabel", 300, 300, 100, 100, 1) --creates a blue label<br />
setBackgroundColor("blueLabel", 50, 50, 250, 255)<br />
<br />
createLabel("redLabel", 350, 350, 100, 100, 1) --creates a red label which is placed on TOP of the bluewindow, as the last made label will sit at the top of the rest<br />
setBackgroundColor("redLabel", 250, 50, 50, 255)<br />
<br />
raiseWindow("blueLabel") --raises blueLabel back at the top, above redLabel<br />
</syntaxhighlight><br />
<br />
==removeCommandLineMenuEvent==<br />
;removeCommandLineMenuEvent([window,] label)<br />
<br />
:Removes an existing command line menu event.<br />
<br />
;Parameters<br />
* ''window:''<br />
: Window that item is associated with. Optional, defaults to "main" (main window console).<br />
* ''label:''<br />
: Label under which element is registered<br />
<br />
;Returns <br />
* Returns ''True'' If the mouse event was removed successfully.<br />
<br />
==removeMouseEvent==<br />
; removeMouseEvent(uniqueName)<br />
<br />
:Removes an existing mouse event. Returns ''True'' If the event exists and was removed successfully, throws a warning if the event doesn't exist.<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
;See also: [[Manual:Lua_Functions#getMouseEvents|getMouseEvents()]], [[Manual:Lua_Functions#addMouseEvent|addMouseEvent()]]<br />
<br />
;Parameters<br />
* ''uniqueName:''<br />
: A unique identifier that the mouse event was registered under.<br />
<br />
;Returns <br />
* Returns ''True'' If the mouse event was removed successfully.<br />
<br />
==replace==<br />
;replace([windowName], with, [keepcolor])<br />
:Replaces the currently selected text with the new text. To select text, use [[#selectString | selectString()]], [[#selectSection | selectSection()]] or a similar function.<br />
<br />
{{note}}<br />
If you’d like to delete/gag the whole line, use [[#deleteLine | deleteLine()]] instead.<br />
<br />
{{note}}<br />
when used outside of a trigger context (for example, in a timer instead of a trigger), replace() won't trigger the screen to refresh. Instead, use ''replace("")'' and ''insertText("new text")'' as [[#insertText | insertText()]] does.<br />
<br />
See also: [[#creplace|creplace]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of window (a miniconsole)<br />
* ''with:''<br />
: the new text to display.<br />
* ''keepcolor:''<br />
: (optional) argument, setting this to ''true'' will keep the existing colors (since Mudlet 3.0+)<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
-- replace word "troll" with "cute trolly"<br />
selectString("troll",1)<br />
replace("cute trolly")<br />
<br />
-- replace the whole line<br />
selectCurrentLine()<br />
replace("Out with the old, in with the new!")<br />
</syntaxhighlight><br />
<br />
==replaceAll==<br />
;replaceAll(what, with, [keepcolor])<br />
: Replaces all occurrences of ''what'' in the current line with ''with''.<br />
<br />
;Parameters<br />
* ''what:''<br />
: the text to replace<br />
{{note}}<br />
This accepts [https://www.lua.org/pil/20.2.html Lua patterns]<br />
* ''with:''<br />
: the new text to have in place<br />
* ''keepcolor:''<br />
: setting this to true will keep the existing colors.<br />
{{note}} keepcolor is available in Mudlet 4.10+<br />
<br />
;Examples:<br />
<syntaxhighlight lang="lua"><br />
-- replace all occurrences of the word "south" in the line with "north"<br />
replaceAll("south", "north")<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- replace all occurrences of the text that the variable "target" has<br />
replaceAll(target, "The Bad Guy")<br />
</syntaxhighlight><br />
<br />
==replaceLine==<br />
;replaceLine ([window], text)<br />
: Replaces the output line from the game with your own text.<br />
See Also: [[Manual:Lua_Functions#echo|echo()]], [[Manual:Lua_Functions#insertText|insertText()]]<br />
<br />
;Parameters<br />
* ''window'' (optional):<br />
: the window to copy the text from. Defaults to "main".<br />
* ''text:''<br />
*: The text to display<br />
<br />
;Example<br />
<syntaxhighlight lang="lua">replaceLine("[ALERT!]: "..line)<br />
</syntaxhighlight><br />
<br />
==replaceWildcard==<br />
;replaceWildcard(which, replacement, [keepcolor])<br />
: Replaces the given wildcard (as a number) with the given text. Equivalent to doing:<br />
<br />
<syntaxhighlight lang="lua"><br />
selectString(matches[2], 1)<br />
replace("text")<br />
</syntaxhighlight><br />
<br />
;Parameters<br />
* ''which:''<br />
: Wildcard to replace.<br />
* ''replacement:''<br />
: Text to replace the wildcard with.<br />
* ''keepcolor:''<br />
: setting this to true will keep the existing colors<br />
{{note}} keepcolor available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
replaceWildcard(2, "hello") -- on a perl regex trigger of ^You wave (goodbye)\.$, it will make it seem like you waved hello<br />
</syntaxhighlight><br />
<br />
==resetCmdLineAction==<br />
;resetCmdLineAction(commandLineName)<br />
: Resets the action on the command line so the it behaves like the main command line again.<br />
;Parameters<br />
<br />
* ''commandLineName''<br />
: The name of the command line the action will be resetet.<br />
: See also: [[#setCmdLineAction | setCmdLineAction()]]<br />
{{MudletVersion|4.10}}<br />
<br />
==resetBackgroundImage==<br />
;resetBackgroundImage([windowName])<br />
: Resets the console background-image<br />
;Parameters<br />
<br />
* ''windowName''<br />
: (optional) name of the console the image will be reset<br />
: See also: [[#setBackgroundImage | setBackgroundImage()]]<br />
{{MudletVersion|4.10}}<br />
<br />
==resetFormat==<br />
;resetFormat()<br />
: Resets the colour/bold/italics formatting. Always use this function when done adjusting formatting, so make sure what you've set doesn't 'bleed' onto other triggers/aliases.<br />
<br />
; Parameters<br />
:None<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- select and set the 'Tommy' to red in the line<br />
if selectString("Tommy", 1) ~= -1 then fg("red") end<br />
<br />
-- now reset the formatting, so our echo isn't red<br />
resetFormat()<br />
echo(" Hi Tommy!")<br />
<br />
-- another example: just highlighting some words<br />
for _, word in ipairs{"he", "she", "her", "their"} do<br />
if selectString(word, 1) ~= -1 then<br />
bg("blue")<br />
end<br />
end<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
==resetLabelCursor==<br />
;resetLabelCursor(labelName)<br />
: Resets your mouse cursor to the default one.<br />
<br />
: See also: [[#setLabelCursor|setLabelCursor()]], [[#setLabelCustomCursor|setLabelCustomCursor()]]<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
;Parameters<br />
* ''labelName'': label for which to reset the cursor for.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
resetLabelCursor("myLabel")<br />
-- This will reset the mouse cursor over myLabel to the default one<br />
</syntaxhighlight><br />
<br />
==resetLabelToolTip==<br />
;resetLabelToolTip(labelName)<br />
: Resets the tooltip on the given label.<br />
{{MudletVersion|4.6.1}}<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label the tooltip will be reseted.<br />
: See also: [[#setLabelToolTip | setLabelToolTip()]]<br />
<br />
==resetMapWindowTitle==<br />
;resetMapWindowTitle()<br />
: resets the title of the popped out map window to default.<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
: See also: [[#setMapWindowTitle|setMapWindowTitle()]]<br />
<br />
==resetUserWindowTitle==<br />
;resetUserWindowTitle(windowName)<br />
: resets the title of the UserWindow windowName<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the userwindow for which the title will be resetet<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
: See also: [[#setUserWindowTitle|setUserWindowTitle()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
==resizeWindow==<br />
;resizeWindow(windowName, width, height)<br />
: Resizes a mini console, label, or floating User Windows.<br />
:See also: [[#createMiniConsole | createMiniConsole()]], [[#createLabel | createLabel()]], [[#handleWindowResizeEvent | handleWindowResizeEvent()]], [[#resizeWindow | resizeWindow()]], [[#setBorderSizes | setBorderSizes()]], [[#openUserWindow | openUserWindow()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of your window<br />
* ''width:''<br />
: The new width you want<br />
* ''height:''<br />
: The new height you want<br />
<br />
{{note}}<br />
Since Mudlet 3.7 this method can also be used on User Window consoles if they are floating.<br />
<br />
==saveWindowLayout==<br />
;saveWindowLayout()<br />
:Saves the layout of userwindows (floating miniconsoles), in case you'd like to load them again later.<br />
<br />
:See also: [[#loadWindowLayout|loadWindowLayout()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
{{MudletVersion|3.2}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
saveWindowLayout()<br />
</syntaxhighlight><br />
<br />
==selectCaptureGroup==<br />
;selectCaptureGroup(groupNumber)<br />
: Selects the content of the capture group number in your Perl regular expression (from matches[]). Also works with named capture group. It does not work with multimatches.<br />
<br />
:See also: [[#selectCurrentLine| selectCurrentLine()]]<br />
<br />
;Parameters<br />
* ''groupNumberOrName:''<br />
: number of the capture group you want to select, or the name of the capture group as a string<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--First, set a Perl Reqular expression e.g. "you have (\d+) Euro".<br />
--If you want to color the amount of money you have green you do:<br />
<br />
selectCaptureGroup(1)<br />
setFgColor(0,255,0)<br />
<br />
-- Or perhaps instead if you were to use "you have (?<euro>\d+) Euro"<br />
selectCaptureGroup("euro")<br />
fg("green")<br />
</syntaxhighlight><br />
<br />
==selectCmdLineText==<br />
;selectCmdLineText([commandLine])<br />
: Selects the text in your command line. You can specify which one, if you got many.<br />
<br />
:See also: [[#createCommandLine| createCommandLine()]]<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
;Parameters<br />
* ''commandLine:''<br />
: (optional) name of the command line you want to have selected<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- First, create an extra commandline with the following lua script:<br />
inputContainer = inputContainer or Adjustable.Container:new({<br />
x = 0, y = "-4c",<br />
name = "InputContainer", padding = 2,<br />
width = "100%", height = "4c",<br />
autoLoad = false<br />
})<br />
extraCmdLine = extraCmdLine or Geyser.CommandLine:new({<br />
name = "extraCmdLine",<br />
x = 0, y = 0, width = "100%", height = "100%"<br />
}, inputContainer)<br />
inputContainer:attachToBorder("bottom")<br />
<br />
-- Now you can send the following lua code with your main command line.<br />
-- It will give 2 seconds time to click around, unselect its text, etc. before selecting its text for you:<br />
lua tempTimer(2, function() selectCmdLineText() end)<br />
<br />
-- This will instead select the text in the command line named extraCmdLine:<br />
lua selectCmdLineText('extraCmdLine')<br />
<br />
-- Same as before, but using the Geyser.CommandLine function instead:<br />
lua extraCmdLine:selectText() <br />
</syntaxhighlight><br />
<br />
==selectCurrentLine==<br />
; selectCurrentLine([windowName])<br />
: Selects the content of the current line that the cursor at. By default, the cursor is at the start of the current line that the triggers are processing, but you can move it with the moveCursor() function.<br />
<br />
{{note}}<br />
This selects the whole line, including the linebreak - so it has a subtle difference from the slightly slower ''selectString(line, 1)'' selection method.<br />
: See also: [[Manual:Lua_Functions#selectString|selectString()]], [[#selectCurrentLine| selectCurrentLine()]], [[#getSelection| getSelection()]], [[Manual:Lua_Functions#getCurrentLine|getCurrentLine()]]<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window in which to select text.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- color the whole line green!<br />
selectCurrentLine()<br />
fg("green")<br />
deselect()<br />
resetFormat()<br />
<br />
-- to select the previous line, you can do this:<br />
moveCursor(0, getLineNumber()-1)<br />
selectCurrentLine()<br />
<br />
-- to select two lines back, this:<br />
moveCursor(0, getLineNumber()-2)<br />
selectCurrentLine()<br />
<br />
</syntaxhighlight><br />
<br />
==selectSection==<br />
;selectSection( [windowName], fromPosition, length )<br />
: Selects the specified parts of the line starting ''from'' the left and extending to the right for however ''how long''. The line starts from 0.<br />
: Returns true if the selection was successful, and false if the line wasn't actually long enough or the selection couldn't be done in general.<br />
<br />
:See also:[[#selectString| selectString()]], [[#selectCurrentLine| selectCurrentLine()]], [[#getSelection| getSelection()]]<br />
<br />
;Parameters<br />
* "windowName:"<br />
: (optional) name of the window in which to select text. By default the main window, if no windowName is given.<br />
: Will not work if "main" is given as the windowName to try to select from the main window.<br />
* ''fromPosition:''<br />
: number to specify at which position in the line to begin selecting<br />
* ''length:''<br />
: number to specify the amount of characters you want to select<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- select and colour the first character in the line red<br />
if selectSection(0,1) then fg("red") end<br />
<br />
-- select and colour the second character green (start selecting from the first character, and select 1 character)<br />
if selectSection(1,1) then fg("green") end<br />
<br />
-- select and colour three character after the first two grey (start selecting from the 2nd character for 3 characters long)<br />
if selectSection(2,3) then fg("grey") end<br />
</syntaxhighlight><br />
<br />
==selectString==<br />
;selectString([windowName], text, number_of_match)<br />
: Selects a substring from the line where the user cursor is currently positioned - allowing you to edit selected text (apply colour, make it be a link, copy to other windows or other things).<br />
<br />
{{note}}<br />
You can move the user cursor with [[#moveCursor | moveCursor()]]. When a new line arrives from the game, the user cursor is positioned at the beginning of the line. However, if one of your trigger scripts moves the cursor around you need to take care of the cursor position yourself and make sure that the cursor is in the correct line if you want to call one of the select functions. To deselect text, see [[#deselect | deselect()]].<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the window in which to select text. By default the main window, if no windowName or an empty string is given.<br />
* ''text:''<br />
: The text to select. It is matched as a substring match (so the text anywhere within the line will get selected).<br />
* ''number_of_match:''<br />
: The occurrence of text on the line that you'd like to select. For example, if the line was "Bob and Bob", 1 would select the first Bob, and 2 would select the second Bob.<br />
<br />
Returns position in line or -1 on error (text not found in line)<br />
<br />
{{note}}<br />
To prevent working on random text if your selection didn't actually select anything, check the -1 return code before doing changes:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
if selectString("big monster", 1) > -1 then fg("red") end<br />
</syntaxhighlight><br />
<br />
==setAppStyleSheet==<br />
;setAppStyleSheet(stylesheet [, tag])<br />
: Sets a stylesheet for the entire Mudlet application and every open profile. Because it affects other profiles that might not be related to yours, it's better to use [[#setProfileStyleSheet|setProfileStyleSheet()]] instead of this function.<br />
<br />
: Raises the sysAppStyleSheetChange event which comes with two arguments in addition to the event name. The first is the optional tag which was passed into the function, or "" if nothing was given. The second is the profile which made the stylesheet changes.<br />
<br />
: See also: [[#setProfileStyleSheet|setProfileStyleSheet()]]<br />
<br />
;Parameters<br />
<br />
* ''stylesheet:''<br />
: The entire stylesheet you'd like to use.<br />
<br />
* ''tag:'' (available in Mudlet 3.19+)<br />
: (optional) string tag or identifier that will be passed as a second argument in the ''sysAppStyleSheetChange'' event<br />
<br />
;References<br />
: See [http://qt-project.org/doc/qt-5/stylesheet-reference.html Qt Style Sheets Reference] for the list of widgets you can style and CSS properties you can apply on them.<br />
: See also [https://github.com/vadi2/QDarkStyleSheet/blob/master/qdarkstyle/style.qss QDarkStyleSheet], a rather extensive stylesheet that shows you all the different configuration options you could apply, available as an [http://forums.mudlet.org/viewtopic.php?f=6&t=17624 mpackage here].<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- credit to Akaya @ http://forums.mudlet.org/viewtopic.php?f=5&t=4610&start=10#p21770<br />
local background_color = "#26192f"<br />
local border_color = "#b8731b"<br />
<br />
setAppStyleSheet([[<br />
QMainWindow {<br />
background: ]]..background_color..[[;<br />
}<br />
QToolBar {<br />
background: ]]..background_color..[[;<br />
}<br />
QToolButton {<br />
background: ]]..background_color..[[;<br />
border-style: solid;<br />
border-width: 2px;<br />
border-color: ]]..border_color..[[;<br />
border-radius: 5px;<br />
font-family: BigNoodleTitling;<br />
color: white;<br />
margin: 2px;<br />
font-size: 12pt;<br />
}<br />
QToolButton:hover { background-color: grey;}<br />
QToolButton:focus { background-color: grey;}<br />
]])<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
{{note}} Enhanced in Mudlet version 3.19.0 to generate an event that profiles/packages can utilise to redraw any parts of the UI that they themselves had previously styled so their effects can be re-applied to the new application style.<br />
<br />
It is anticipated that the Mudlet application itself will make further use of application styling effects and two strings are provisionally planned for the second parameter in the ''sysAppStyleSheetChange'' event: "''mudlet-theme-dark''" and "''mudlet-theme-light''"; it will also set the third parameter to "''system''".<br />
<br />
==setBackgroundColor==<br />
;setBackgroundColor([windowName], r, g, b, [transparency])<br />
: Sets the background for the given label, miniconsole, or userwindow. Colors are from 0 to 255 (0 being black), and transparency is from 0 to 255 (0 being completely transparent).<br />
<br />
;Parameters<br />
<br />
* ''windowName:''<br />
: (optional) name of the label/miniconsole/userwindow to change the background color on, or "main" for the main window.<br />
* ''r:''<br />
: Amount of red to use, from 0 (none) to 255 (full).<br />
* ''g:''<br />
: Amount of green to use, from 0 (none) to 255 (full).<br />
* ''b:''<br />
: Amount of red to use, from 0 (none) to 255 (full).<br />
* ''transparency:''<br />
: (optional) amount of transparency to use, from 0 (fully transparent) to 255 (fully opaque). Defaults to 255 if omitted.<br />
<br />
{{note}}<br />
Transparency also available for main/miniconsoles in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- make a red label that's somewhat transparent<br />
setBackgroundColor("some label",255,0,0,200)<br />
</syntaxhighlight><br />
<br />
==setBackgroundImage==<br />
;setBackgroundImage(labelName, imageLocation)<br />
;setBackgroundImage([windowname], imageLocation, [mode])<br />
: Loads an image file (png) as a background image for a label or console. This can be used to display clickable buttons in combination with [[Manual:Lua_Functions#setLabelClickCallback|setLabelClickCallback()]] and such.<br />
<br />
{{note}}<br />
You can also load images on labels via [[Manual:Lua_Functions#setLabelStyleSheet|setLabelStyleSheet()]].<br />
<br />
;Parameters (label)<br />
<br />
* ''labelName:''<br />
: The name of the label to change it's background color.<br />
* ''imageLocation:''<br />
: The full path to the image location. It's best to use [[ ]] instead of "" for it - because for Windows paths, backslashes need to be escaped.<br />
<br />
;Parameters (consoles)<br />
<br />
* ''windowName:''<br />
: (optional) name of the miniconsole/userwindow to change the background image on, or "main" for the main window.<br />
* ''imageLocation:''<br />
: The full path to the image location. It's best to use [[ ]] instead of "" for it - because for Windows paths, backslashes need to be escaped.<br />
* ''mode:''<br />
: (optional) allows different modes for drawing the background image. Possible modes areː <br />
<br />
** border - the background image is stretched (1)<br />
** center - the background image is in the center (2), <br />
** tile - the background image is 'tiled' (3)<br />
** style - choose your own background image stylesheet, see example below (4)<br />
<br />
: See also: [[#resetBackgroundImage | resetBackgroundImage()]]<br />
<br />
;Example (label)<br />
<syntaxhighlight lang="lua"><br />
-- give the top border a nice look<br />
setBackgroundImage("top bar", [[/home/vadi/Games/Mudlet/games/top_bar.png]])<br />
</syntaxhighlight><br />
<br />
;Example (main/miniconsole)<br />
<syntaxhighlight lang="lua"><br />
-- give the main window a background image<br />
setBackgroundImage("main", [[:/Mudlet_splashscreen_development.png]], "center")<br />
<br />
-- or use your own for the main window:<br />
setBackgroundImage("main", [[C:\Documents and Settings\bub\Desktop\mypicture.png]], "center")<br />
<br />
-- give my_miniconsole a nice background image and put it in the center<br />
setBackgroundImage("my_miniconsole", [[:/Mudlet_splashscreen_development.png]], "center")<br />
<br />
-- give my_miniconsole a nice background image with own stylesheet option<br />
setBackgroundImage("my_miniconsole", [[background-image: url(:/Mudlet_splashscreen_development.png); background-repeat: no-repeat; background-position: right;]], "style")<br />
</syntaxhighlight><br />
{{note}} setBackgroundImage for main/miniconsoles and userwindows available in Mudlet 4.10+<br />
<br />
==setBgColor==<br />
;setBgColor([windowName], r, g, b, [transparency])<br />
:Sets the current text background color in the main window unless windowName parameter given. If you have selected text prior to this call, the selection will be highlighted otherwise the current text background color will be changed. If you set a foreground or background color, the color will be used until you call resetFormat() on all further print commands.<br />
<br />
:If you'd like to change the background color of a window, see [[#setBackgroundColor|setBackgroundColor()]].<br />
<br />
: ''See also:'' [[#cecho|cecho()]], [[#setBackgroundColor|setBackgroundColor()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) either be none or "main" for the main console, or a miniconsole / userwindow name.<br />
* ''r:''<br />
: The red component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''g:''<br />
: The green component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''b:''<br />
: The blue component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''transparency:''<br />
: Amount of transparency to use, from 0 (fully transparent) to 255 (fully opaque). Optional, if not used color is fully opaque<br />
<br />
<br />
<br />
{{note}}<br />
Transparency parameter available in Mudlet 4.10+<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
--highlights the first occurrence of the string "Tom" in the current line with a red background color.<br />
selectString( "Tom", 1 )<br />
setBgColor( 255,0,0 )<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
--prints "Hello" on red background and "You" on blue.<br />
setBgColor(255,0,0)<br />
echo("Hello")<br />
setBgColor(0,0,255)<br />
echo(" You!")<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
==setBold==<br />
;setBold(windowName, boolean)<br />
: Sets the current text font to bold (true) or non-bold (false) mode. If the windowName parameters omitted, the main screen will be used. If you've got text currently selected in the Mudlet buffer, then the selection will be bolded. Any text you add after with [[Manual:Lua_Functions#echo|echo()]] or [[Manual:Lua_Functions#insertText|insertText()]] will be bolded until you use [[Manual:Lua_Functions#resetFormat|resetFormat()]].<br />
<br />
* ''windowName:''<br />
: Optional parameter set the current text background color in windowname given.<br />
<br />
* ''boolean:''<br />
: A <code>true</code> or <code>false</code> that enables or disables bolding of text<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- enable bold formatting<br />
setBold(true)<br />
-- the following echo will be bolded<br />
echo("hi")<br />
-- turns off bolding, italics, underlines and colouring. It's good practice to clean up after you're done with the formatting, so other your formatting doesn't "bleed" into other echoes.<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
==setBorderBottom==<br />
;setBorderBottom(size)<br />
: Sets the size of the bottom border of the main window in pixels. A border means that the game text won't go on it, so this gives you room to place your graphical elements there.<br />
: See Also: [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#setBorderColor|setBorderColor()]], [[Manual:Lua_Functions#getBorderBottom|getBorderBottom()]]<br />
<br />
;Parameters<br />
* ''size:''<br />
: Height of the border in pixels - with 0 indicating no border.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderBottom(150)<br />
</syntaxhighlight><br />
<br />
==setBorderColor==<br />
;setBorderColor(red, green, blue)<br />
: Sets the color of the main windows border that you can create either with lua commands, or via the main window settings.<br />
: See Also: [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]]<br />
<br />
;Parameters<br />
* ''red:''<br />
: Amount of red color to use, from 0 to 255.<br />
* ''green:''<br />
: Amount of green color to use, from 0 to 255.<br />
* ''blue:''<br />
: Amount of blue color to use, from 0 to 255.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- set the border to be completely blue<br />
setBorderColor(0, 0, 255)<br />
<br />
-- or red, using a name<br />
setBorderColor( unpack(color_table.red) )<br />
</syntaxhighlight><br />
<br />
==setBorderLeft==<br />
;setBorderLeft(size)<br />
: Sets the size of the left border of the main window in pixels. A border means that the game text won't go on it, so this gives you room to place your graphical elements there.<br />
: See Also: [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#setBorderColor|setBorderColor()]], [[Manual:Lua_Functions#getBorderLeft|getBorderLeft()]]<br />
<br />
;Parameters<br />
* ''size:''<br />
: Width of the border in pixels - with 0 indicating no border.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderLeft(5)<br />
</syntaxhighlight><br />
<br />
==setBorderRight==<br />
;setBorderRight(size)<br />
: Sets the size of the right border of the main window in pixels. A border means that the game text won't go on it, so this gives you room to place your graphical elements there.<br />
: See Also: [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#setBorderColor|setBorderColor()]], [[Manual:Lua_Functions#getBorderRight|getBorderRight()]]<br />
<br />
;Parameters<br />
* ''size:''<br />
: Width of the border in pixels - with 0 indicating no border.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderRight(50)<br />
</syntaxhighlight><br />
<br />
==setBorderSizes==<br />
;setBorderSizes(top, right, bottom, left)<br />
: Sets the size of all borders of the main window in pixels. A border means that the game text won't go on it, so this gives you room to place your graphical elements there.<br />
: The exact result of this function depends on how many numbers you give to it as arguments.<br />
: See also: [[Manual:Lua_Functions#getBorderSizes|getBorderSizes()]], [[Manual:Lua_Functions#setBorderTop|setBorderTop()]], [[Manual:Lua_Functions#setBorderRight|setBorderRight()]], [[Manual:Lua_Functions#setBorderBottom|setBorderBottom()]], [[Manual:Lua_Functions#setBorderLeft|setBorderLeft()]], [[Manual:Lua_Functions#setBorderColor|setBorderColor()]]<br />
<br />
: {{MudletVersion|4.0}}<br />
<br />
;Arguments<br />
* '''setBorderSizes(top, right, bottom, left)'''<br />
: ''4 arguments:'' All borders will be set to their new given size.<br />
* '''setBorderSizes(top, width, bottom)''' <br />
: ''3 arguments:'' Top and bottom borders will be set to their new given size, and right and left will gain the same width. <br />
* '''setBorderSizes(height, width)'''<br />
: ''2 arguments:'' Top and bottom borders will gain the same height, and right and left borders gain the same width. <br />
* '''setBorderSizes(size)'''<br />
: ''1 argument:'' All borders will be set to the same size.<br />
* '''setBorderSizes()'''<br />
: ''0 arguments:'' All borders will be hidden or set to size of 0 = no border.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderSizes(100, 50, 150, 0) <br />
-- big border at the top, bigger at the bottom, small at the right, none at the left<br />
<br />
setBorderSizes(100, 50, 150) <br />
-- big border at the top, bigger at the bottom, small at the right and the left<br />
<br />
setBorderSizes(100, 50) <br />
-- big border at the top and the bottom, small at the right and the left<br />
<br />
setBorderSizes(100) <br />
-- big borders at all four sides<br />
<br />
setBorderSizes() <br />
-- no borders at all four sides<br />
</syntaxhighlight><br />
<br />
==setBorderTop==<br />
;setBorderTop(size)<br />
: Sets the size of the top border of the main window in pixels. A border means that the game text won't go on it, so this gives you room to place your graphical elements there.<br />
: See Also: [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#setBorderColor|setBorderColor()]], [[Manual:Lua_Functions#getBorderTop|getBorderTop()]]<br />
<br />
;Parameters<br />
* ''size:''<br />
: Height of the border in pixels - with 0 indicating no border.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderTop(100)<br />
</syntaxhighlight><br />
<br />
==setFgColor==<br />
;setFgColor([windowName], red, green, blue)<br />
:Sets the current text foreground color in the main window unless windowName parameter given.<br />
<br />
* ''windowName:''<br />
: (optional) either be none or "main" for the main console, or a miniconsole / userwindow name.<br />
* ''red:''<br />
: The red component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''green:''<br />
: The green component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''blue:''<br />
: The blue component of the gauge color. Passed as an integer number from 0 to 255<br />
<br />
: See also: [[#setBgColor | setBgColor()]], [[#setHexFgColor | setHexFgColor()]], [[#setHexBgColor | setHexBgColor()]], [[#resetFormat | resetFormat()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--highlights the first occurrence of the string "Tom" in the current line with a red foreground color.<br />
selectString( "Tom", 1 )<br />
setFgColor( 255, 0, 0 )<br />
</syntaxhighlight><br />
<br />
==setButtonStyleSheet==<br />
;setButtonStyleSheet(button, markup)<br />
: Applies Qt style formatting to a button via a special markup language.<br />
<br />
; Parameters<br />
* ''button:''<br />
: The name of the button to be formatted.<br />
* ''markup:''<br />
: The string instructions, as specified by the Qt Style Sheet reference.<br />
: Note: You can instead use QWidget { markup }. QWidget will reference 'button', allowing the use of pseudostates like QWidget:hover and QWidget:selected<br />
<br />
;References<br />
: http://qt-project.org/doc/qt-5/stylesheet-reference.html<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setButtonStyleSheet("my test button", [[<br />
QWidget {<br />
background-color: #999999;<br />
border: 3px #777777;<br />
}<br />
QWidget:hover {<br />
background-color: #bbbbbb;<br />
}<br />
QWidget:checked {<br />
background-color: #77bb77;<br />
border: 3px #559955;<br />
}<br />
QWidget:hover:checked {<br />
background-color: #99dd99;<br />
} ]])</syntaxhighlight><br />
<br />
==setClipboardText==<br />
;setClipboardText(textContent)<br />
: Sets the value of the computer's clipboard to the string data provided.<br />
: See also: [[#getClipboardText | getClipboardText()]]<br />
<br />
; Parameters<br />
* ''textContent:''<br />
: The text to be put into the clipboard.<br />
<br />
: {{note}} Note: Available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setClipboardText("New Clipboard Contents")<br />
echo("Clipboard: " .. getClipboardText()) -- should echo "Clipboard: New Clipboard Contents"<br />
</syntaxhighlight><br />
<br />
==setCmdLineAction==<br />
;setCmdLineAction(commandLineName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called if the user sends text to the command line. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the command line action. Additionally, this function passes the command line input text as the final argument.<br />
{{note}} If no action is set the command line behaves like the main command line and sends commands directly to the game or alias engine.<br />
<br />
The function specified in ''luaFunctionName'' is called like so:<br />
<br />
<syntaxhighlight lang="lua"><br />
luaFuncName(optional number of arguments, text)<br />
</syntaxhighlight><br />
<br />
: See also: [[Manual:UI_Functions#resetCmdLineAction|resetCmdLineAction()]]<br />
<br />
;Parameters<br />
<br />
* ''commandLineName:''<br />
: The name of the command line to attach the action function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string.<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
{{note}} You can also pass a function directly instead of using a string<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
function sendTextToMiniConsole(miniConsoleName, cmdLineText)<br />
echo(miniConsoleName, cmdLineText.."\n")<br />
end<br />
<br />
setCmdLineAction("myCmdLine", "sendTextToMiniConsole", "myMiniConsole")<br />
<br />
</syntaxhighlight><br />
<br />
==setCmdLineStyleSheet==<br />
;setCmdLineStyleSheet([commandLineName], markup)<br />
: Applies Qt style formatting to a command line via a special markup language.<br />
<br />
;Parameters<br />
* ''commandLineName:''<br />
: (optional) Name of the command line (or miniconsole the command line is in). If not given the stylesheet will be applied to the main command line.<br />
* ''markup''<br />
: The string instructions, as specified by the Qt Style Sheet reference.<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
: See also: [[Manual:UI_Functions#enableCommandLine|enableCommandLine()]], [[Manual:UI_Functions#createCommandLine|createCommandLine()]]<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- move the main command line over to the right<br />
setCmdLineStyleSheet("main", [[<br />
QPlainTextEdit {<br />
padding-left: 100px; /* change 100 to your number */<br />
background-color: black; /* change it to your background color */<br />
}<br />
]])<br />
<br />
--only change font-size of your main command line<br />
setCmdLineStyleSheet("main", [[<br />
QPlainTextEdit {<br />
font-sizeː20pt; <br />
}<br />
]])<br />
<br />
--change bg/fg color of your miniconsole command line (name of the miniconsole is 'myMiniconsole'<br />
--the command line in the miniconsole has to be enabled<br />
setCmdLineStyleSheet("myMiniConsole", [[<br />
QPlainTextEdit {<br />
background: rgb(0,100,0);<br />
color: rgb(0,200,255);<br />
font-size: 10pt;<br />
}<br />
]])<br />
</syntaxhighlight><br />
<br />
==setFont==<br />
;setFont(name, font)<br />
: Sets the font on the given window or console name. Can be used to change font of the main console, miniconsoles, and userwindows. Prefer a monospaced font - those work best with text games. See here [https://doc.qt.io/qt-5/qfont.html#setFamily for more].<br />
: See also: [[#getFont|getFont()]], [[#setFontSize|setFontSize()]], [[#getFontSize|getFontSize()]], [[#openUserWindow|openUserWindow()]], [[#getAvailableFonts|getAvailableFonts()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: Optional - the window name to set font size of - can either be none or "main" for the main console, or a miniconsole / userwindow name.<br />
* ''font:''<br />
: The font to use.<br />
<br />
{{MudletVersion|3.9}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The following will set the "main" console window font to Ubuntu Mono, another font included in Mudlet.<br />
setFont("Ubuntu Mono")<br />
setFont("main", "Ubuntu Mono")<br />
<br />
-- This will set the font size of a miniconsole named "combat" to Ubuntu Mono.<br />
setFont("combat", "Ubuntu Mono")<br />
</syntaxhighlight><br />
<br />
==setFontSize==<br />
;setFontSize(name, size)<br />
: Sets a font size on the given window or console name. Can be used to change font size of the Main console as well as dockable UserWindows.<br />
: See Also: [[#getFontSize|getFontSize()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: Optional - the window name to set font size of - can either be none or "main" for the main console, or a UserWindow name.<br />
* ''size:''<br />
: The font size to apply to the window.<br />
<br />
{{MudletVersion|3.4}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The following will set the "main" console window font to 12-point font.<br />
setFontSize(12)<br />
setFontSize("main", 12)<br />
<br />
-- This will set the font size of a user window named "uw1" to 12-point font.<br />
setFontSize("uw1", 12)<br />
</syntaxhighlight><br />
<br />
==setGauge==<br />
;setGauge(gaugeName, currentValue, maxValue, gaugeText)<br />
: Use this function when you want to change the gauges look according to your values. Typical usage would be in a prompt with your current health or whatever value, and throw in some variables instead of the numbers.<br />
<br />
: See also: [[Manual:Lua_Functions#moveGauge|moveGauge()]], [[Manual:Lua_Functions#createGauge|createGauge()]], [[Manual:Lua_Functions#setGaugeText|setGaugeText()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create a gauge<br />
createGauge("healthBar", 300, 20, 30, 300, nil, "green")<br />
<br />
--Change the looks of the gauge named healthBar and make it<br />
--fill to half of its capacity. The height is always remembered.<br />
setGauge("healthBar", 200, 400)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
--If you wish to change the text on your gauge, you’d do the following:<br />
setGauge("healthBar", 200, 400, "some text")<br />
</syntaxhighlight><br />
<br />
==setGaugeStyleSheet==<br />
;setGaugeStyleSheet(gaugeName, css, cssback, csstext)<br />
: Sets the CSS stylesheets on a gauge - one on the front (the part that resizes accoding to the values on the gauge) and one in the back. You can use [https://build-system.fman.io/qt-designer-download Qt Designer] to create stylesheets.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setGaugeStyleSheet("hp_bar", [[background-color: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #f04141, stop: 0.1 #ef2929, stop: 0.49 #cc0000, stop: 0.5 #a40000, stop: 1 #cc0000);<br />
border-top: 1px black solid;<br />
border-left: 1px black solid;<br />
border-bottom: 1px black solid;<br />
border-radius: 7;<br />
padding: 3px;]],<br />
[[background-color: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #bd3333, stop: 0.1 #bd2020, stop: 0.49 #990000, stop: 0.5 #700000, stop: 1 #990000);<br />
border-width: 1px;<br />
border-color: black;<br />
border-style: solid;<br />
border-radius: 7;<br />
padding: 3px;]])<br />
</syntaxhighlight><br />
<br />
==setGaugeText==<br />
;setGaugeText(gaugename, css, ccstext )<br />
: Set the formatting of the text used inside the inserted gaugename.<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
setGaugeText("healthBar", [[<p style="font-weight:bold;color:#C9C9C9;letter-spacing:1pt;word-spacing:2pt;font-size:12px;text-align:center;font-family:arial black, sans-serif;">]]..MY_NUMERIC_VARIABLE_HERE..[[</p>]])</syntaxhighlight><br />
<br />
;Useful resources:<br />
:http://csstxt.com - Generate the text exactly how you like it before pasting it into the css slot.<br />
:https://www.w3schools.com/colors/colors_picker.asp - Can help you choose colors for your text!<br />
<br />
==setHexBgColor==<br />
;setHexBgColor([windowName], hexColorString)<br />
:Sets the current text nackground color in the main window unless windowName parameter given. This function allows to specify the color as a 6 character hexadecimal string.<br />
<br />
* ''windowName:''<br />
: Optional parameter set the current text background color in windowname given.<br />
* ''hexColorString''<br />
: 6 character long hexadecimal string to set the color to. The first two characters 00-FF represent the red part of the color, the next two the green and the last two characters stand for the blue part of the color<br />
<br />
: See also: [[#setBgColor | setBgColor()]], [[#setHexFgColor | setHexFgColor()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--highlights the first occurrence of the string "Tom" in the current line with a red Background color.<br />
selectString( "Tom", 1 )<br />
setHexBgColor( "FF0000" )<br />
</syntaxhighlight><br />
<br />
==setHexFgColor==<br />
;setHexFgColor([windowName], hexColorString)<br />
:Sets the current text foreground color in the main window unless windowName parameter given. This function allows to specify the color as a 6 character hexadecimal string.<br />
<br />
* ''windowName:''<br />
: Optional parameter set the current text foreground color in windowname given.<br />
* ''hexColorString''<br />
: 6 character long hexadecimal string to set the color to. The first two characters 00-FF represent the red part of the color, the next two the green and the last two characters stand for the blue part of the color<br />
<br />
: See also: [[#setFgColor | setFgColor()]], [[#setHexBgColor | setHexBgColor()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--highlights the first occurrence of the string "Tom" in the current line with a red foreground color.<br />
selectString( "Tom", 1 )<br />
setHexFgColor( "FF0000" )<br />
</syntaxhighlight><br />
<br />
==setItalics==<br />
;setItalics(windowName, bool)<br />
: Sets the current text font to italics/non-italics mode. If the windowName parameters omitted, the main screen will be used.<br />
<br />
==setLabelToolTip==<br />
;setLabelToolTip(labelName, text, [duration])<br />
: Sets a tooltip on the given label.<br />
{{MudletVersion|4.6.1}}<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to set the tooltip to.<br />
* ''text:''<br />
: The text to be shown. Can contain Qt rich text formats.<br />
* ''duration:''<br />
: Duration of the tooltip timeout in seconds. Optional, if not set the default duration will be set.<br />
<br />
: See also: [[Manual:UI_Functions#resetLabelToolTip|resetLabelToolTip()]]<br />
<br />
==setLabelClickCallback==<br />
;setLabelClickCallback(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called if the user clicks on the label/image. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button. Additionally, this function passes an event table as the final argument. This table contains information about the mouse button clicked, other buttons that were pressed at the time, and the mouse cursor's local (relative to the label) and global (relative to the Mudlet window) position. The function specified in ''luaFunctionName'' is called like so:<br />
<br />
<syntaxhighlight lang="lua"><br />
luaFuncName(optional number of arguments, event)<br />
</syntaxhighlight><br />
<br />
where '''event''' has the following structure:<br />
<br />
<syntaxhighlight lang="lua"><br />
event = {<br />
x = 100,<br />
y = 200,<br />
globalX = 300,<br />
globalY = 320,<br />
button = "LeftButton",<br />
buttons = {"RightButton", "MidButton"},<br />
}<br />
</syntaxhighlight><br />
<br />
: See also: [[Manual:UI_Functions#setLabelDoubleClickCallback|setLabelDoubleClickCallback()]], [[Manual:UI_Functions#setLabelReleaseCallback|setLabelReleaseCallback()]], [[Manual:UI_Functions#setLabelMoveCallback|setLabelMoveCallback()]], [[Manual:UI_Functions#setLabelWheelCallback|setLabelWheelCallback()]],[[Manual:UI_Functions#setLabelOnEnter|setLabelOnEnter()]], [[Manual:UI_Functions#setLabelOnLeave|setLabelOnLeave()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: Lua function to call, or the function name, as a string.<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
{{note}} Event argument is available in 3.6+, and in 4.8+ you can pass a function directly instead of a string.<br />
<br />
{{note}}<br />
While '''event.button''' may contain a single string of any listed below, '''event.buttons''' will only ever contain some combination of "LeftButton", "MidButton", and "RightButton"<br />
:The following mouse button strings are defined:<br />
<pre><br />
"LeftButton" "RightButton" "MidButton"<br />
"BackButton" "ForwardButton" "TaskButton"<br />
"ExtraButton4" "ExtraButton5" "ExtraButton6"<br />
"ExtraButton7" "ExtraButton8" "ExtraButton9"<br />
"ExtraButton10" "ExtraButton11" "ExtraButton12"<br />
"ExtraButton13" "ExtraButton14" "ExtraButton15"<br />
"ExtraButton16" "ExtraButton17" "ExtraButton18"<br />
"ExtraButton19" "ExtraButton20" "ExtraButton21"<br />
"ExtraButton22" "ExtraButton23" "ExtraButton24"<br />
</pre><br />
;Example<br />
<syntaxhighlight lang="lua"><br />
createLabel("testLabel", 50, 50, 100, 100, 0)<br />
<br />
function onClickGoNorth(event)<br />
if event.button == "LeftButton" then<br />
send("walk north")<br />
elseif event.button == "RightButton" then<br />
send("swim north")<br />
elseif event.button == "MidButton" then<br />
send("gallop north")<br />
end<br />
end<br />
<br />
setLabelClickCallback("testLabel", "onClickGoNorth")<br />
<br />
-- you can also use them within tables:<br />
mynamespace =<br />
{<br />
onClickGoNorth =<br />
function()<br />
echo("the north button was clicked!")<br />
end,<br />
}<br />
setLabelClickCallback("testLabel", "mynamespace.onClickGoNorth")<br />
<br />
-- or by passing the function directly:<br />
setLabelClickCallback("testLabel", onClickGoNorth)<br />
</syntaxhighlight><br />
<br />
==setLabelDoubleClickCallback==<br />
;setLabelDoubleClickCallback(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called if the user double clicks on the label/image. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button. Additionally, this function passes an event table as the final argument, as in [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]]<br />
<br />
{{MudletVersion|3.6}}<br />
<br />
: See also: [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:UI_Functions#setLabelReleaseCallback|setLabelReleaseCallback()]], [[Manual:UI_Functions#setLabelMoveCallback|setLabelMoveCallback()]], [[Manual:UI_Functions#setLabelWheelCallback|setLabelWheelCallback()]], [[Manual:UI_Functions#setLabelOnEnter|setLabelOnEnter()]], [[Manual:UI_Functions#setLabelOnLeave|setLabelOnLeave()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string.<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
==setLabelMoveCallback==<br />
;setLabelMoveCallback(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called when the mouse moves while inside the specified label/console. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button. Additionally, this function passes an event table as the final argument, as in [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]]<br />
<br />
: See Also: [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:UI_Functions#setLabelDoubleClickCallback|setLabelDoubleClickCallback()]], [[Manual:UI_Functions#setLabelReleaseCallback|setLabelReleaseCallback()]], [[Manual:UI_Functions#setLabelWheelCallback|setLabelWheelCallback()]], [[Manual:UI_Functions#setLabelOnEnter|setLabelOnEnter()]], [[Manual:UI_Functions#setLabelOnLeave|setLabelOnLeave()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string.<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
{{MudletVersion|3.6}}<br />
<br />
==setLabelOnEnter==<br />
;setLabelOnEnter(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called when the mouse enters within the labels borders. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button. Additionally, this function passes an event table as the final argument, similar to [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], but with slightly different information.<br />
: For this callback, the '''event''' argument has the following structure:<br />
<br />
<syntaxhighlight lang="lua"><br />
event = {<br />
x = 100,<br />
y = 200,<br />
globalX = 300,<br />
globalY = 320,<br />
}<br />
</syntaxhighlight><br />
<br />
: See Also: [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:UI_Functions#setLabelDoubleClickCallback|setLabelDoubleClickCallback()]], [[Manual:UI_Functions#setLabelReleaseCallback|setLabelReleaseCallback()]], [[Manual:UI_Functions#setLabelMoveCallback|setLabelMoveCallback()]], [[Manual:UI_Functions#setLabelWheelCallback|setLabelWheelCallback()]], [[Manual:UI_Functions#setLabelOnLeave|setLabelOnLeave()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string - it must be registered as a global function, and not inside any namespaces (tables).<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
function onMouseOver()<br />
echo("The mouse is hovering over the label!\n")<br />
end<br />
<br />
setLabelOnEnter( "compassNorthImage", "onMouseOver" )<br />
</syntaxhighlight><br />
<br />
==setLabelOnLeave==<br />
;setLabelOnLeave(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called when the mouse leaves the labels borders. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button.<br />
<br />
: See Also: [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:UI_Functions#setLabelOnEnter|setLabelOnEnter()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string - it must be registered as a global function, and not inside any namespaces (tables).<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
function onMouseLeft(argument)<br />
echo("The mouse quit hovering over the label the label! We also got this as data on the function: "..argument)<br />
end<br />
<br />
setLabelOnLeave( "compassNorthImage", "onMouseLeft", "argument to pass to function" )<br />
</syntaxhighlight><br />
<br />
==setLabelReleaseCallback==<br />
;setLabelReleaseCallback(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called when a mouse click ends that originated on the specified label/console. This function is called even if you drag the mouse off of the label/console before releasing the click. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button. Additionally, this function passes an event table as the final argument, as in [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]]<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
: See Also: [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:UI_Functions#setLabelDoubleClickCallback|setLabelDoubleClickCallback()]], [[Manual:UI_Functions#setLabelMoveCallback|setLabelMoveCallback()]], [[Manual:UI_Functions#setLabelWheelCallback|setLabelWheelCallback()]], [[Manual:UI_Functions#setLabelOnEnter|setLabelOnEnter()]], [[Manual:UI_Functions#setLabelOnLeave|setLabelOnLeave()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string.<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
{{note}}<br />
The ''event'' argument only available since Mudlet 3.6<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
function onReleaseNorth()<br />
echo("the north button was released!")<br />
end<br />
<br />
setLabelReleaseCallback( "compassNorthImage", "onReleaseNorth" )<br />
<br />
-- you can also use them within tables:<br />
mynamespace = {<br />
onReleaseNorth = function()<br />
echo("the north button was released!")<br />
end<br />
}<br />
<br />
setLabelReleaseCallback( "compassNorthImage", "mynamespace.onReleaseNorth" )<br />
</syntaxhighlight><br />
<br />
==setLabelStyleSheet==<br />
;setLabelStyleSheet(label, markup)<br />
: Applies Qt style formatting to a label via a special markup language.<br />
<br />
; Parameters<br />
* ''label:''<br />
: The name of the label to be formatted (passed when calling createLabel).<br />
* ''markup:''<br />
: The string instructions, as specified by the Qt Style Sheet reference.<br />
: Note that when specifying a file path for styling purposes, forward slashes, / , must be used, even if your OS uses backslashes, \ , normally.<br />
<br />
;References<br />
: http://qt-project.org/doc/qt-5/stylesheet-reference.html<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This creates a label with a white background and a green border, with the text "test"<br />
-- inside.<br />
createLabel("test", 50, 50, 100, 100, 0)<br />
setLabelStyleSheet("test", [[<br />
background-color: white;<br />
border: 10px solid green;<br />
font-size: 12px;<br />
]])<br />
echo("test", "test")<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
-- This creates a label with a single image, that will tile or clip depending on the<br />
-- size of the label. To use this example, please supply your own image.<br />
createLabel("test5", 50, 353, 164, 55, 0)<br />
setLabelStyleSheet("test5", [[<br />
background-image: url("C:/Users/Administrator/.config/mudlet/profiles/Midkemia Online/Vyzor/MkO_logo.png");<br />
]])<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
-- This creates a label with a single image, that can be resized (such as during a<br />
-- sysWindowResizeEvent). To use this example, please supply your own image.<br />
createLabel("test9", 215, 353, 100, 100, 0)<br />
setLabelStyleSheet("test9", [[<br />
border-image: url("C:/Users/Administrator/.config/mudlet/profiles/Midkemia Online/Vyzor/MkO_logo.png");<br />
]])<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
--This creates a label whose background changes when the users mouse hovers over it.<br />
<br />
--putting the styleSheet in a variable allows us to easily change the styleSheet. We also are placing colors in variables that have been preset. <br />
local labelBackgroundColor = "#123456"<br />
local labelHoverColor = "#654321"<br />
local labelFontSize = 12<br />
local labelName = "HoverLabel"<br />
local ourLabelStyle = [[<br />
QLabel{<br />
background-color: ]]..labelBackgroundColor..[[;<br />
font-size: ]]..labelFontSize..[[px;<br />
qproperty-alignment: 'AlignCenter | AlignCenter';<br />
}<br />
QLabel::hover{<br />
background-color: ]]..labelHoverColor..[[;<br />
font-size: ]]..labelFontSize..[[px;<br />
qproperty-alignment: 'AlignCenter | AlignCenter';<br />
}<br />
]]<br />
<br />
--Creating the label using the labelName and ourLabelStyle variables created above.<br />
createLabel(labelName,0,0,400,400,1)<br />
setLabelStyleSheet(labelName, ourLabelStyle)<br />
echo("HoverLabel","This text shows while mouse is or is not over the label.")<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
--Using QLabel::hover mentioned above. Lets "trick" the label into changing it's text.<br />
--Please keep in mind that the setLabelMoveCallback allows for much more control over not just your label but your entire project.<br />
<br />
--putting the styleSheet in a variable allows us to easily change the styleSheet. We also are placing colors in variables that have been preset. <br />
local labelBackgroundColor = "#123456"<br />
local labelHoverColor = "#654321"<br />
local labelFontSize = 12<br />
local labelName = "HoverLabel"<br />
--Notice we are adding a string returned from a function. In this case, the users profile directory.<br />
local ourLabelStyle = [[<br />
QLabel{<br />
border-image: url("]]..getMudletHomeDir()..[[/imagewithtext.png");<br />
}<br />
QLabel::hover{<br />
border-image: url("]]..getMudletHomeDir()..[[/imagewithhovertext.png");<br />
}<br />
]]<br />
<br />
--Creating the label using the labelName and ourLabelStyle variables created above.<br />
createLabel(labelName,0,0,400,400,1)<br />
setLabelStyleSheet(labelName, ourLabelStyle)<br />
--This is just to example that echos draw on top of the label. You would not want to echo onto a label you were drawing text on with images, because echos would draw on top of them.<br />
echo("HoverLabel","This text shows while mouse is or is not over the label.")<br />
</syntaxhighlight><br />
<br />
==setLabelCursor==<br />
;setLabelCursor(labelName, cursorShape)<br />
: Changes how the mouse cursor looks like when over the label. To reset the cursor shape, use [[#resetLabelCursor|resetLabelCursor()]].<br />
<br />
: See also: [[#resetLabelCursor|resetLabelCursor()]], [[#setLabelCustomCursor|setLabelCustomCursor()]]<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: Name of the label which you want the mouse cursor change at.<br />
* ''cursorShape''<br />
: Shape of the mouse cursor. List of possible cursor shapes is [[CursorShapes| available here]].<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setLabelCursor("myLabel", "Cross")<br />
-- This will change the mouse cursor to a cross if it's over the label myLabel<br />
</syntaxhighlight><br />
<br />
==setLabelCustomCursor==<br />
;setLabelCustomCursor(labelName, custom cursor, [hotX, hotY])<br />
: Changes the mouse cursor shape over your label to a custom cursor. To reset the cursor shape, use [[#resetLabelCursor|resetLabelCursor()]].<br />
<br />
: See also: [[#resetLabelCursor|resetLabelCursor()]], [[#setLabelCursor|setLabelCursor()]]<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: Name of the label which you want the mouse cursor change at.<br />
* ''custom cursor''<br />
: Location of your custom cursor file. To be compatible with all systems it is recommended to use png files with size of 32x32.<br />
* ''hotX''<br />
: X-coordinate of the cursors hotspot position. Optional, if not set it is set to -1 which is in the middle of your custom cursor.<br />
* ''hotY''<br />
: Y-coordinate of the cursors hotspot position. Optional, if not set it is set to -1 which is in the middle of your custom cursor.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setLabelCustomCursor("myLabel", getMudletHomeDir().."/custom_cursor.png")<br />
-- This will change the mouse cursor to your custom cursor if it's over the label myLabel<br />
</syntaxhighlight><br />
<br />
==setLabelWheelCallback==<br />
;setLabelWheelCallback(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called when the mouse wheel is scrolled while inside the specified label/console. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button. Additionally, this function passes an event table as the final argument, similar to [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], but with slightly different information.<br />
: For this callback, the ''event'' argument has the following structure:<br />
<br />
<syntaxhighlight lang="lua"><br />
event = {<br />
x = 100,<br />
y = 200,<br />
globalX = 300,<br />
globalY = 320,<br />
buttons = {"RightButton", "MidButton"},<br />
angleDeltaX = 0,<br />
angleDeltaY = 120<br />
}<br />
</syntaxhighlight><br />
<br />
: Keys ''angleDeltaX'' and ''angleDeltaY'' correspond with the horizontal and vertical scroll distance, respectively. For most mice, these values will be multiples of 120.<br />
<br />
: See Also: [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:UI_Functions#setLabelDoubleClickCallback|setLabelDoubleClickCallback()]], [[Manual:UI_Functions#setLabelReleaseCallback|setLabelReleaseCallback()]], [[Manual:UI_Functions#setLabelMoveCallback|setLabelMoveCallback()]], [[Manual:UI_Functions#setLabelOnEnter|setLabelOnEnter()]], [[Manual:UI_Functions#setLabelOnLeave|setLabelOnLeave()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string.<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
{{MudletVersion|3.6}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
function onWheelNorth(event)<br />
if event.angleDeltaY > 0 then<br />
echo("the north button was wheeled forwards over!")<br />
else<br />
echo("the north button was wheeled backwards over!")<br />
end<br />
end<br />
<br />
setLabelWheelCallback( "compassNorthImage", "onWheelNorth" )<br />
<br />
-- you can also use them within tables:<br />
mynamespace = {<br />
onWheelNorth = function()<br />
echo("the north button was wheeled over!")<br />
end<br />
}<br />
<br />
setWheelReleaseCallback( "compassNorthImage", "mynamespace.onWheelNorth" )<br />
</syntaxhighlight><br />
<br />
==setLink==<br />
;setLink([windowName], command, tooltip)<br />
: Turns the [[Manual:Lua_Functions#selectString|selected]] text into a clickable link - upon being clicked, the link will do the command code. Tooltip is a string which will be displayed when the mouse is over the selected text.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of a miniconsole or a userwindow in which to select the text in.<br />
* ''command:''<br />
: command to do when the text is clicked, as text or Lua function.<br />
* ''tooltip:''<br />
: tooltip to show when the mouse is over the text - explaining what would clicking do.<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
-- you can clickify a lot of things to save yourself some time - for example, you can change<br />
-- the line where you receive a message to be clickable to read it!<br />
-- prel regex trigger:<br />
-- ^You just received message #(\w+) from \w+\.$<br />
-- script:<br />
selectString(matches[2], 1)<br />
setUnderline(true) setLink([[send("msg read ]]..matches[2]..[[")]], "Read #"..matches[2])<br />
resetFormat()<br />
<br />
-- example of selecting text in a miniconsole and turning it into a link:<br />
HelloWorld = Geyser.MiniConsole:new({<br />
name="HelloWorld",<br />
x="70%", y="50%",<br />
width="30%", height="50%",<br />
})<br />
HelloWorld:echo("hi")<br />
selectString("HelloWorld", "hi", 1)<br />
setLink("HelloWorld", "echo'you clicked hi!'", "click me!")<br />
</syntaxhighlight><br />
<br />
==setMainWindowSize==<br />
;setMainWindowSize(mainWidth, mainHeight)<br />
: Changes the size of your main Mudlet window to the values given.<br />
: See Also: [[Manual:Lua_Functions#getMainWindowSize|getMainWindowSize()]]<br />
<br />
; Parameters<br />
* ''mainWidth:''<br />
: The new width in pixels.<br />
* ''mainHeight:''<br />
: The new height in pixels.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--this will resize your main Mudlet window<br />
setMainWindowSize(1024, 768)<br />
</syntaxhighlight><br />
<br />
==setMapWindowTitle==<br />
;setMapWindowTitle(text)<br />
: Changes the title shown in the mapper window when it's popped out.<br />
: See also: [[#resetMapWindowTitle|resetMapWindowTitle()]]<br />
<br />
; Parameters<br />
* ''text:''<br />
: New window title to set.<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setMapWindowTitle("my cool game map")<br />
</syntaxhighlight><br />
<br />
==setMiniConsoleFontSize==<br />
;setMiniConsoleFontSize(name, fontSize)<br />
: Sets the font size of the mini console. see also: [[#setFontSize | setFontSize()]], [[#createMiniConsole | createMiniConsole()]], [[#createLabel | createLabel()]]<br />
<br />
==setOverline==<br />
;setOverline([windowName], boolean)<br />
: Sets the current text font to be overlined (true) or not overlined (false) mode. If the windowName parameters omitted, the main screen will be used. If you've got text currently selected in the Mudlet buffer, then the selection will be overlined. Any text you add after with [[Manual:Lua_Functions#echo|echo()]] or [[Manual:Lua_Functions#insertText|insertText()]] will be overlined until you use [[Manual:Lua_Functions#resetFormat|resetFormat()]].<br />
<br />
* ''windowName:''<br />
: (optional) name of the window to set the text to be overlined or not.<br />
<br />
* ''boolean:''<br />
: A ''true'' or ''false'' that enables or disables overlining of text<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
-- enable overlined text<br />
setOverline(true)<br />
-- the following echo will be have an overline<br />
echo("hi")<br />
-- turns off bolding, italics, underlines, colouring, and strikethrough (and, after this and reverse have been added, them as well). It's good practice to clean up after you're done with the formatting, so other your formatting doesn't "bleed" into other echoes.<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.17}}<br />
<br />
==setPopup==<br />
;setPopup([windowName], {lua code}, {hints})<br />
: Turns the [[Manual:Lua_Functions#selectString|selected()]] text into a left-clickable link, and a right-click menu for more options. The selected 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.<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: the name of the console to operate on. If not using this in a miniConsole, use "main" as the name.<br />
: This argument was ignored before Mudlet 4.11.<br />
* ''{lua code}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. ie, <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight>.<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- In a `Raising your hand in greeting, you say "Hello!"` exact match trigger,<br />
-- the following code will make left-clicking on `Hello` show you an echo, while right-clicking<br />
-- will show some commands you can do.<br />
<br />
selectString("Hello", 1)<br />
setPopup("main", {function() send("bye") end, function() echo("hi!") end}, {"send 'bye' to the MUD", "click to echo 'hi!'"})<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
setPopup("main", {[[send("bye")]], [[echo("hi!")]]}, {"send 'bye' to the MUD", "click to echo 'hi!'"})<br />
<br />
</syntaxhighlight><br />
<br />
==setProfileStyleSheet==<br />
;setProfileStyleSheet(stylesheet)<br />
: Sets a stylesheet for the current Mudlet profile - allowing you to customise content outside of the main window (the profile tabs, the scrollbar, and so on). This function is better than setAppStyleSheet() because it affects only the current profile and not every other one as well.<br />
<br />
: See also: [[#setAppStyleSheet|setAppStyleSheet()]]<br />
<br />
;Parameters<br />
<br />
* ''stylesheet:''<br />
: The entire stylesheet you'd like to use. See [http://qt-project.org/doc/qt-5/stylesheet-reference.html Qt Style Sheets Reference] for the list of widgets you can style and CSS properties you can apply on them.<br />
<br />
: See also [https://github.com/vadi2/QDarkStyleSheet/blob/master/qdarkstyle/style.qss QDarkStyleSheet], a rather extensive stylesheet that shows you all the different configuration options you could apply, available as an [http://forums.mudlet.org/viewtopic.php?f=6&t=17624 mpackage here].<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- credit to Akaya @ http://forums.mudlet.org/viewtopic.php?f=5&t=4610&start=10#p21770<br />
local background_color = "#26192f"<br />
local border_color = "#b8731b"<br />
<br />
setProfileStyleSheet([[<br />
QMainWindow {<br />
background: ]]..background_color..[[;<br />
}<br />
QToolBar {<br />
background: ]]..background_color..[[;<br />
}<br />
QToolButton {<br />
background: ]]..background_color..[[;<br />
border-style: solid;<br />
border-width: 2px;<br />
border-color: ]]..border_color..[[;<br />
border-radius: 5px;<br />
font-family: BigNoodleTitling;<br />
color: white;<br />
margin: 2px;<br />
font-size: 12pt;<br />
}<br />
QToolButton:hover { background-color: grey;}<br />
QToolButton:focus { background-color: grey;}<br />
<br />
QTreeView {<br />
background: ]]..background_color..[[;<br />
color: white;<br />
}<br />
<br />
QMenuBar{ background-color: ]]..background_color..[[;}<br />
<br />
QMenuBar::item{ background-color: ]]..background_color..[[;}<br />
<br />
QDockWidget::title {<br />
background: ]]..border_color..[[;<br />
}<br />
QStatusBar {<br />
background: ]]..border_color..[[;<br />
}<br />
QScrollBar:vertical {<br />
background: ]]..background_color..[[;<br />
width: 15px;<br />
margin: 22px 0 22px 0;<br />
}<br />
QScrollBar::handle:vertical {<br />
background-color: ]]..background_color..[[;<br />
min-height: 20px;<br />
border-width: 2px;<br />
border-style: solid;<br />
border-color: ]]..border_color..[[;<br />
border-radius: 7px;<br />
}<br />
QScrollBar::add-line:vertical {<br />
background-color: ]]..background_color..[[;<br />
border-width: 2px;<br />
border-style: solid;<br />
border-color: ]]..border_color..[[;<br />
border-bottom-left-radius: 7px;<br />
border-bottom-right-radius: 7px;<br />
height: 15px;<br />
subcontrol-position: bottom;<br />
subcontrol-origin: margin;<br />
}<br />
QScrollBar::sub-line:vertical {<br />
background-color: ]]..background_color..[[;<br />
border-width: 2px;<br />
border-style: solid;<br />
border-color: ]]..border_color..[[;<br />
border-top-left-radius: 7px;<br />
border-top-right-radius: 7px;<br />
height: 15px;<br />
subcontrol-position: top;<br />
subcontrol-origin: margin;<br />
}<br />
QScrollBar::up-arrow:vertical, QScrollBar::down-arrow:vertical {<br />
background: white;<br />
width: 4px;<br />
height: 3px;<br />
}<br />
QScrollBar::add-page:vertical, QScrollBar::sub-page:vertical {<br />
background: none;<br />
}<br />
]])<br />
<br />
-- if you'd like to reset it, use:<br />
setProfileStyleSheet("")<br />
<br />
-- to only affect scrollbars within the main window and miniconsoles, prefix them with 'TConsole':<br />
setProfileStyleSheet[[<br />
TConsole QScrollBar:vertical {<br />
border: 2px solid grey;<br />
background: #32CC99;<br />
width: 15px;<br />
margin: 22px 0 22px 0;<br />
}<br />
TConsole QScrollBar::handle:vertical {<br />
background: white;<br />
min-height: 20px;<br />
}<br />
TConsole QScrollBar::add-line:vertical {<br />
border: 2px solid grey;<br />
background: #32CC99;<br />
height: 20px;<br />
subcontrol-position: bottom;<br />
subcontrol-origin: margin;<br />
}<br />
TConsole QScrollBar::sub-line:vertical {<br />
border: 2px solid grey;<br />
background: #32CC99;<br />
height: 20px;<br />
subcontrol-position: top;<br />
subcontrol-origin: margin;<br />
}<br />
TConsole QScrollBar::up-arrow:vertical, QScrollBar::down-arrow:vertical {<br />
border: 2px solid grey;<br />
width: 3px;<br />
height: 3px;<br />
background: white;<br />
}<br />
TConsole QScrollBar::add-page:vertical, QScrollBar::sub-page:vertical {<br />
background: none;<br />
}<br />
]]<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.6}}<br />
<br />
==setReverse==<br />
;setReverse([windowName], boolean)<br />
: Sets the current text to swap foreground and background color settings (true) or not (false) mode. If the windowName parameters omitted, the main screen will be used. If you've got text currently selected in the Mudlet buffer, then the selection will have it's colors swapped. Any text you add after with [[Manual:Lua_Functions#echo|echo()]] or [[Manual:Lua_Functions#insertText|insertText()]] will have their foreground and background colors swapped until you use [[Manual:Lua_Functions#resetFormat|resetFormat()]].<br />
<br />
* ''windowName:''<br />
: (optional) name of the window to set the text colors to be reversed or not.<br />
<br />
* ''boolean:''<br />
: A ''true'' or ''false'' that enables or disables reversing of the fore- and back-ground colors of text<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
-- enable fore/back-ground color reversal of text<br />
setReverse(true)<br />
-- the following echo will have the text colors reversed<br />
echo("hi")<br />
-- turns off bolding, italics, underlines, colouring, and strikethrough (and, after this and overline have been added, them as well). It's good practice to clean up after you're done with the formatting, so other your formatting doesn't "bleed" into other echoes.<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.17}}<br />
<br />
{{note}} Although the visual effect on-screen is the same as that of text being selected if both apply to a piece of text they neutralise each other - however the effect of the reversal ''will'' be carried over in copies made by the "Copy to HTML" and in logs made in HTML format log file mode.<br />
<br />
==setStrikeOut==<br />
;setStrikeOut([windowName], boolean)<br />
: Sets the current text font to be striken out (true) or not striken out (false) mode. If the windowName parameters omitted, the main screen will be used. If you've got text currently selected in the Mudlet buffer, then the selection will be bolded. Any text you add after with [[Manual:Lua_Functions#echo|echo()]] or [[Manual:Lua_Functions#insertText|insertText()]] will be striken out until you use [[Manual:Lua_Functions#resetFormat|resetFormat()]].<br />
<br />
* ''windowName:''<br />
: (optional) name of the window to set the text to be stricken out or not.<br />
<br />
* ''boolean:''<br />
: A ''true'' or ''false'' that enables or disables striking out of text<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
-- enable striken-out text<br />
setStrikeOut(true)<br />
-- the following echo will be have a strikethrough<br />
echo("hi")<br />
-- turns off bolding, italics, underlines, colouring, and strikethrough. It's good practice to clean up after you're done with the formatting, so other your formatting doesn't "bleed" into other echoes.<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
==setTextFormat==<br />
;setTextFormat(windowName, r1, g1, b1, r2, g2, b2, bold, underline, italics, [strikeout], [overline], [reverse])<br />
: Sets current text format of selected window. This is a more convenient means to set all the individual features at once compared to using [[#setFgColor|setFgColor]]( windowName, r,g,b ), [[#setBold|setBold]]( windowName, true ), [[#setItalics|setItalics]]( windowName, true ), [[#setUnderline|setUnderline]]( windowName, true ), [[#setStrikeOut|setStrikeOut]]( windowName, true ).<br />
: See Also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]]<br />
<br />
;Parameters<br />
* ''windowName''<br />
: Specify name of selected window. If empty string "" or "main" format will be applied to the main console<br />
* ''r1,g1,b1''<br />
: To color text background, give number values in RBG style<br />
* ''r2,g2,b2''<br />
: To color text foreground, give number values in RBG style<br />
* ''bold''<br />
: To format text bold, set to 1 or true, otherwise 0 or false<br />
* ''underline''<br />
: To underline text, set to 1 or true, otherwise 0 or false<br />
* ''italics''<br />
: To format text italic, set to 1 or true, otherwise 0 or false<br />
* ''strikeout<br />
: (optional) To strike text out, set to 1 or true, otherwise 0 or false or simply no argument<br />
* ''overline<br />
: (optional) To use overline, set to 1 or true, otherwise 0 or false or simply no argument<br />
* ''reverse<br />
: (optional) To swap foreground and background colors, set to 1 or true, otherwise 0 or false or simply no argument<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
--This script would create a mini text console and write with bold, struck-out, yellow foreground color and blue background color "This is a test".<br />
createMiniConsole( "con1", 0,0,300,100);<br />
setTextFormat("con1",0,0,255,255,255,0,true,0,false,1);<br />
echo("con1","This is a test")<br />
</syntaxhighlight><br />
<br />
{{note}} In versions prior to 3.7.0 the error messages ''and this wiki'' were wrong in that they had the foreground color parameters as r1, g1 and b1 and the background ones as r2, g2 and b2.<br />
<br />
==setUnderline==<br />
;setUnderline(windowName, bool)<br />
: Sets the current text font to underline/non-underline mode. If the windowName parameters omitted, the main screen will be used.<br />
<br />
==setUserWindowTitle==<br />
;setUserWindowTitle(windowName, text)<br />
: sets a new title text for the UserWindow windowName<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the userwindow<br />
* ''text''<br />
: new title text<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
: See also: [[#resetUserWindowTitle|resetUserWindowTitle()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
==setUserWindowStyleSheet==<br />
;setUserWindowStyleSheet(windowName, markup)<br />
: Applies Qt style formatting to the border/title area of a userwindow via a special markup language.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the userwindow<br />
* ''markup''<br />
: The string instructions, as specified by the Qt Style Sheet reference.<br />
: Note that when you dock the userwindow the border style is not provided by this<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- changes the title area style of the UserWindow 'myUserWindow'<br />
setUserWindowStyleSheet("myUserWindow", [[QDockWidget::title{ <br />
background-color: rgb(0,255,150);<br />
border: 2px solid red;<br />
border-radius: 8px;<br />
text-align: center; <br />
}]])<br />
</syntaxhighlight><br />
<br />
: See also: [[#openUserWindow|openUserWindow()]]<br />
<br />
==setWindow==<br />
;setWindow(windowName, name, [Xpos, Ypos, show])<br />
: Changes the parent window of an element.<br />
{{MudletVersion|4.8}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the userwindow which you want the element put in. If you want to put the element into the main window, use windowName "main".<br />
* ''name''<br />
: Name of the element which you want to switch the parent from. Elements can be labels, miniconsoles and the embedded mapper. If you want to move the mapper use the name "mapper"<br />
* ''Xpos:''<br />
: X position of the element. Measured in pixels, with 0 being the very left. Passed as an integer number. Optional, if not given it will be 0.<br />
* ''Ypos:''<br />
: Y position of the element. Measured in pixels, with 0 being the very top. Passed as an integer number. Optional, if not given it will be 0.<br />
* ''show:''<br />
: true or false to decide if the element will be shown or not in the new parent window. Optional, if not given it will be true.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setWindow("myuserwindow", "mapper")<br />
-- This will put your embedded mapper in your userwindow "myuserwindow".<br />
</syntaxhighlight><br />
<br />
==setWindowWrap==<br />
;setWindowWrap(windowName, wrapAt)<br />
: sets at what position in the line the will start word wrap.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the "main" console or user-created miniconsole which you want to be wrapped differently. If you want to wrap the main window, use windowName "main".<br />
* ''wrapAt:''<br />
: Number of characters at which the wrap must happen at the latest. This means, it probably will be wrapped earlier than that.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setWindowWrap("main", 10)<br />
display("This is just a test")<br />
<br />
-- The following output will result in the main window console:<br />
"This is<br />
just a<br />
test"<br />
</syntaxhighlight><br />
<br />
==setWindowWrapIndent==<br />
;setWindowWrapIndent(windowName, wrapTo)<br />
: sets how many spaces wrapped text will be indented with (after the first line of course).<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the "main" console or user-created miniconsole which you want to be wrapped differently. If you want to wrap the main window, use windowName "main".<br />
* ''wrapTo:''<br />
: Number of spaces which wrapped lines are prefixed with.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setWindowWrap("main", 10)<br />
setWindowWrapIndent("main", 3)<br />
display("This is just a test")<br />
<br />
-- The following output will result in the main window console:<br />
"This is<br />
just a<br />
test"<br />
</syntaxhighlight><br />
<br />
==showCaptureGroups==<br />
;showCaptureGroups()<br />
:Lua debug function that highlights in random colors all capture groups in your trigger regex on the screen. This is very handy if you make complex regex and want to see what really matches in the text. This function is defined in DebugTools.lua.<br />
<br />
;Example:<br />
:Make a trigger with the regex (\w+) and call this function in a trigger. All words in the text will be highlighted in random colors.<br />
<br />
==showMultimatches==<br />
;showMultimatches()<br />
:Lua helper function to show you what the table multimatches[n][m] contains. This is very useful when debugging multiline triggers - just doing showMultimatches() in your script will make it give the info. This function is defined in DebugTools.lua.<br />
<br />
;Example:<br />
See [[Manual:Advanced_Lua#How_to_use_multimatches.5Bn.5D.5Bm.5D|How to use multimatches[n][m]]] for a more thorough explanation including examples.<br />
<br />
==showWindow==<br />
;showWindow(name)<br />
: Makes a hidden window (label or miniconsole) be shown again.<br />
<br />
: See also: [[#hideWindow | hideWindow()]]<br />
<br />
==showColors==<br />
;showColors([columns], [filterColor], [sort])<br />
: shows the named colors currently available in Mudlet's color table. These colors are stored in '''color_table''', in table form. The format is ''color_table.colorName = {r, g, b}''.<br />
<br />
: See Also: [[Manual:Lua_Functions#bg|bg()]], [[Manual:Lua_Functions#fg|fg()]], [[Manual:Lua_Functions#cecho|cecho()]]<br />
<br />
;Parameters<br />
* ''columns:''<br />
: (optional) number of columns to print the color table in.<br />
* ''filterColor:''<br />
: (optional) filter text. If given, the colors displayed will be limited to only show colors containing this text.<br />
* ''sort:''<br />
: (optional) sort colors alphabetically.<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- display as four columns:<br />
showColors(4)<br />
<br />
-- show only red colours:<br />
showColors("red")<br />
</syntaxhighlight><br />
The output for this is:<br />
<br />
[[File:ShowColors.png|showColors(4)|thumb|center]]<br />
<br />
==showGauge==<br />
;showGauge(gaugeName)<br />
: shows the given gauge, in case it was hidden previously.<br />
<br />
: See also: [[#hideGauge|hideGauge()]], [[#createGauge|createGauge()]]<br />
<br />
;Parameters<br />
* ''gaugeName:''<br />
: name of the gauge to show.<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
hideGauge("my gauge")<br />
showGauge("my<br />
</syntaxhighlight><br />
<br />
==showToolBar==<br />
;showToolBar(name)<br />
: Makes a toolbar (a button group) appear on the screen.<br />
<br />
;Parameters<br />
* ''name:''<br />
: name of the button group to display<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
showToolBar("my attack buttons")<br />
</syntaxhighlight><br />
<br />
==suffix==<br />
;suffix(text, [writingFunction], [foregroundColor], [backgroundColor], [windowName])<br />
: Suffixes text at the end of the current line. This is similar to [[Manual:Lua_Functions#echo | echo()]], which also suffixes text at the end of the line, but different - [[Manual:Lua_Functions#echo | echo()]] makes sure to do it on the last line in the buffer, while suffix does it on the line the cursor is currently on.<br />
<br />
;Parameters<br />
* ''text''<br />
: the information you want to prefix<br />
* ''writingFunction''<br />
: optional parameter, allows the selection of different functions to be used to write the text, valid options are: echo, cecho, decho, and hecho.<br />
* ''foregroundColor''<br />
: optional parameter, allows a foreground color to be specified if using the echo function using a color name, as with the fg() function<br />
* ''backgroundColor''<br />
: optional parameter, allows a background color to be specified if using the echo function using a color name, as with the bg() function<br />
* ''windowName''<br />
: optional parameter, allows the selection a miniconsole or the main window for the line that will be prefixed<br />
<br />
: See also: [[#prefix | prefix()]], [[Manual:Lua_Functions#echo | echo()]]<br />
<br />
==wrapLine==<br />
;wrapLine(windowName, lineNumber)<br />
: wraps the line specified by ''lineNumber'' of mini console (window) ''windowName''. This function will interpret \n characters, apply word wrap and display the new lines on the screen. This function may be necessary if you use deleteLine() and thus erase the entire current line in the buffer, but you want to do some further echo() calls after calling deleteLine(). You will then need to re-wrap the last line of the buffer to actually see what you have echoed and get your \n interpreted as newline characters properly. Using this function is no good programming practice and should be avoided. There are better ways of handling situations where you would call deleteLine() and echo afterwards e.g.:<br />
<br />
<syntaxhighlight lang="lua">selectString(line,1)<br />
replace("")</syntaxhighlight><br />
<br />
This will effectively have the same result as a call to deleteLine() but the buffer line will not be entirely removed. Consequently, further calls to echo() etc. sort of functions are possible without using wrapLine() unnecessarily.<br />
<br />
: See Also: [[Manual:Lua_Functions#replace|replace()]], [[Manual:Lua_Functions#deleteLine|deleteLine()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The miniconsole or the main window (use ''main'' for the main window)<br />
* ''lineNumber:''<br />
: The line number which you'd like re-wrapped.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- re-wrap the last line in the main window<br />
wrapLine("main", getLineCount())<br />
</syntaxhighlight><br />
<br />
[[Category:Mudlet Manual]]<br />
[[Category:Mudlet API]]</div>Demonnichttps://wiki.mudlet.org/index.php?title=Manual:UI_Functions&diff=18614Manual:UI Functions2022-01-06T03:38:22Z<p>Demonnic: /* selectCaptureGroup */</p>
<hr />
<div>{{TOC right}}<br />
{{#description2:Mudlet API documentation for functions to construct custom GUIs. They deal mainly with miniconsole/label/gauge creation and manipulation as well as displaying or formatting information on the screen.}}<br />
= UI Functions =<br />
All functions that help you construct custom GUIs. They deal mainly with miniconsole/label/gauge creation and manipulation as well as displaying or formatting information on the screen.<br />
<br />
==addCommandLineMenuEvent==<br />
;addCommandLineMenuEvent([window,] label, eventName)<br />
<br />
Adds item to right click menu associated with command line.<br />
<br />
{{MudletVersion|4.14}}<br />
<br />
;See also: [[Manual:Lua_Functions#removeCommandLineMenuEvent|removeCommandLineMenuEvent()]]<br />
<br />
;Parameters<br />
* ''window:''<br />
: Window that command line belongs to. Optional, will default to "main" (main window console)<br />
* ''label:''<br />
: Label of item<br />
* ''eventName:''<br />
: Event name that will be fired when clicked.<br />
<br />
;Returns <br />
* Returns ''true'' if the mouse event was added successfully.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
addCommandLineMenuEvent("My very own special paste from clipboard", "pasteFromCliboardWithoutLineBreaks" )<br />
registerAnynomousEventListener("pasteFromCliboardWithoutLineBreaks", function()<br />
local text = string.gsub(getClipboardText(), "[\r|\n]", "")<br />
appendCmdLine(text)<br />
end<br />
</syntaxhighlight><br />
<br />
==addMouseEvent==<br />
; addMouseEvent(uniqueName, eventName, [displayName, tooltipText])<br />
<br />
:Registers a new context menu option when right-clicked on a console window. Will return ''true'' if the event was added successfully, otherwise ''nil''+''message'' will be returned. If the ''displayName'' isn't set, ''uniqueName'' will be used for the menu label. ''eventName'' should be a Mudlet event that will handle the click data that includes ''event'', ''unique name'', ''window name'', selection upper left ''column'' and ''row'' and selection bottom right ''column'' and ''row'' in that order. This is intended to be used with available cursor functions for any selection or processing needs.<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
;See also: [[Manual:Lua_Functions#getMouseEvents|getMouseEvents()]], [[Manual:Lua_Functions#moveCursor|moveCursor()]]<br />
<br />
;Parameters<br />
* ''uniqueName:''<br />
: A unique identifier for the mouse event.<br />
* ''eventName:''<br />
: Name of the Mudlet event that will handle the data.<br />
* ''displayName:''<br />
: (optional) Label text for the mouse context menu. If not set, the label defaults to ''uniqueName''.<br />
* ''tooltipText:''<br />
: (optional) Tooltip text when mouse is hovered on the option. If not set, no tooltip will be visible.<br />
<br />
;Returns <br />
* Returns ''true'' if the mouse event was added successfully.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- An example showing implementing a hecho-friendly copy option:<br />
<br />
addMouseEvent("hecho copy", "onMouseCopyExample")<br />
<br />
function rgbToHex(r,g,b)<br />
local rgb = (r * 0x10000) + (g * 0x100) + b<br />
return string.format("#%x", rgb)<br />
end<br />
<br />
function onMouseCopyExample(event, menu, window, startCol, startRow, endCol, endRow)<br />
-- Check whether there's an actual selection<br />
if startCol == endCol and startRow == endRow then return end<br />
local parsed = ""<br />
local lastColor = nil<br />
-- Loop through each symbol within the range<br />
for l = startRow, endRow do<br />
local cStart = l == startRow and startCol or 0<br />
moveCursor(window, cStart, l)<br />
local cEnd = l == endRow and endCol or #getCurrentLine() - 1<br />
for c = cStart, cEnd do<br />
selectSection(window, c, 1)<br />
local symbol = getSelection(window) or ""<br />
-- Convert the foreground color to a hex format, suitable for hecho<br />
local color = rgbToHex(getFgColor(window))<br />
-- Don't repeat the color if previous one was the same<br />
if color == lastColor then<br />
parsed = parsed .. symbol<br />
else<br />
lastColor = color<br />
parsed = parsed .. color .. symbol<br />
end<br />
end<br />
if l ~= endRow then parsed = parsed .. "\n" end<br />
end<br />
setClipboardText(parsed)<br />
end<br />
<br />
registerAnonymousEventHandler("onMouseCopyExample", "onMouseCopyExample")<br />
</syntaxhighlight><br />
<br />
==ansi2decho==<br />
;ansi2decho(text, default_colour)<br />
: Converts ANSI colour sequences in <code>text</code> to colour tags that can be processed by the decho() function. Italics and underline not currently supported since decho doesn't support them.<br />
: See also: [[Manual:Lua_Functions#decho|decho()]]<br />
<br />
{{MudletVersion|3.0}}<br />
{{note}} ANSI bold is available since Mudlet 3.7.1+.<br />
<br />
;Parameters<br />
* ''text:''<br />
: String that contains ANSI colour sequences that should be replaced.<br />
* ''default_colour:''<br />
: Optional - ANSI default colour code (used when handling orphan bold tags).<br />
<br />
;Return values<br />
* ''string text:''<br />
: The decho-valid converted text.<br />
* ''string colour:''<br />
: The ANSI code for the last used colour in the substitution (useful if you want to colour subsequent lines according to this colour).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local replaced = ansi2decho('\27[0;1;36;40mYou say in a baritone voice, "Test."\27[0;37;40m')<br />
-- 'replaced' should now contain <r><0,255,255:0,0,0>You say in a baritone voice, "Test."<r><192,192,192:0,0,0><br />
decho(replaced)<br />
</syntaxhighlight><br />
<br />
Or show a complete colourful squirrel! It's a lotta code to do all the colours, so click the '''Expand''' button on the right to show it:<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<syntaxhighlight lang="lua"><br />
decho(ansi2decho([[<br />
�[38;5;95m▄�[48;5;95;38;5;130m▄▄▄�[38;5;95m█�[49m▀�[0m �[0m<br />
╭───────────────────────╮ �[38;5;95m▄▄�[0m �[38;5;95m▄�[48;5;95;38;5;130m▄▄�[48;5;130m█�[38;5;137m▄�[48;5;137;38;5;95m▄�[49m▀�[0m �[0m<br />
│ │ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄▄▄�[48;5;95;38;5;137m▄▄▄�[49;38;5;95m▄▄�[48;5;95;38;5;130m▄�[48;5;130m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[0m �[0m<br />
│ Encrypt everything! │ �[38;5;95m▄�[48;5;187;38;5;16m▄�[48;5;16;38;5;187m▄�[38;5;16m█�[48;5;137;38;5;137m███�[38;5;187m▄�[38;5;16m▄▄�[38;5;137m██�[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[0m �[0m<br />
│ ├──── �[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;16m▄▄▄�[48;5;137m███�[48;5;16;38;5;16m█�[48;5;187m▄�[48;5;16m█�[48;5;137;38;5;137m█�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
╰───────────────────────╯ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;16m▄�[38;5;16m█�[38;5;137m▄�[48;5;137m██████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;95m▀�[48;5;137m▄�[38;5;137m███████�[38;5;95m▄�[49m▀�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[48;5;95;38;5;187m▄▄▄�[38;5;137m▄�[48;5;137m██�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[38;5;95m▀�[48;5;130m▄�[38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;187m████�[48;5;137;38;5;137m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m██�[38;5;95m▄�[38;5;137m█�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;187;38;5;187m████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95m██�[48;5;137m▄▄�[48;5;187;38;5;187m████�[48;5;137;38;5;95m▄▄�[48;5;95;38;5;137m▄�[48;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;187;38;5;187m███�[48;5;95m▄�[38;5;137m▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[49m▄�[48;5;95;38;5;130m▄�[48;5;130m██████�[48;5;137;38;5;137m███�[38;5;95m▄�[49m▀�[0m�[0m<br />
�[48;5;187;38;5;95m▄�[38;5;187m████�[48;5;137;38;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m█████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;137m▄�[38;5;187m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██████�[48;5;95m▄▄�[48;5;130m▄▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▄▄▄�[48;5;95;38;5;137m▄�[48;5;187m▄�[38;5;187m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m█████�[38;5;95m▄�[38;5;137m███████████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀�[48;5;187m▄▄▄�[48;5;95;38;5;137m▄�[48;5;137m██�[38;5;95m▄�[49m▀�[0m �[38;5;95m▀▀�[48;5;137m▄▄▄▄▄▄�[49m▀▀▀�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀▀�[0m �[0m<br />
]]))<br />
</syntaxhighlight><br />
</div><br />
<br />
[[File:Squirrel-in-Mudlet.png|frameless]]<br />
<br />
==ansi2string==<br />
;ansi2string(text)<br />
: Strips ANSI colour sequences from a string (text)<br />
: See also: [[Manual:Lua_Functions#ansi2decho|ansi2decho()]]<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
;Parameters<br />
* ''text:''<br />
: String that contains ANSI colour sequences that should be removed.<br />
<br />
;Return values<br />
* ''string text:''<br />
: The plain text without ANSI colour sequences.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local replaced = ansi2string('\27[0;1;36;40mYou say in a baritone voice, "Test."\27[0;37;40m')<br />
-- 'replaced' should now contain You say in a baritone voice, "Test."<br />
print(replaced)<br />
</syntaxhighlight><br />
<br />
==appendBuffer==<br />
;appendBuffer(name)<br />
: Pastes the previously copied rich text (including text formats like color etc.) into user window name.<br />
: See also: [[#selectCurrentLine|selectCurrentLine()]], [[#copy|copy()]], [[Manual:Lua_Functions#paste|paste()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name of the user window to paste into. Passed as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--selects and copies an entire line to user window named "Chat"<br />
selectCurrentLine()<br />
copy()<br />
appendBuffer("Chat")<br />
</syntaxhighlight><br />
<br />
==bg==<br />
;bg([window, ]colorName)<br />
: Changes the background color of the text. Useful for highlighting text.<br />
: See Also: [[Manual:Lua_Functions#fg|fg()]], [[Manual:Lua_Functions#setBgColor|setBgColor()]]<br />
<br />
;Parameters<br />
* ''window:''<br />
: The miniconsole to operate on - optional. If you'd like it to work on the main window, don't specify anything, or use ''main'' (since Mudlet 3.0).<br />
* ''colorName:''<br />
: The name of the color to set the background to. [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This would change the background color of the text on the current line to magenta<br />
selectCurrentLine()<br />
bg("magenta")<br />
<br />
-- or echo text with a green background to a miniconsole<br />
bg("my window", "green")<br />
echo("my window", "some green text\n")<br />
</syntaxhighlight><br />
<br />
==calcFontSize==<br />
;calcFontSize(window_or_fontsize, [fontname])<br />
: Returns the average height and width of characters in a particular window, or a font name and size combination. Helpful if you want to size a miniconsole to specific dimensions.<br />
: Returns two numbers, width/height<br />
: See also: [[Manual:Lua_Functions#setMiniConsoleFontSize|setMiniConsoleFontSize()]], [[Manual:Lua_Functions#getMainWindowSize|getMainWindowSize()]]<br />
<br />
;Parameters<br />
* ''window_or_fontsize:''<br />
: The miniconsole or font size you are wanting to calculate pixel sizes for.<br />
* ''fontname:''<br />
: Specific font name (along with the size as the first argument) to calculate for.<br />
<br />
{{note}}<br />
Window as an argument is available in Mudlet 3.10+, and font name in Mudlet 4.1+.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--this snippet will calculate how wide and tall a miniconsole designed to hold 4 lines of text 20 characters wide<br />
--would need to be at 9 point font, and then changes miniconsole Chat to be that size<br />
local width,height = calcFontSize(9)<br />
width = width * 20<br />
height = height * 4<br />
resizeWindow("Chat", width, height)<br />
</syntaxhighlight><br />
<br />
==cecho==<br />
;cecho([window], text)<br />
: Echoes text that can be easily formatted with colour, italics, bold and underline tags. You can also include unicode art in it - try some examples from [http://1lineart.kulaone.com/#/ 1lineart].<br />
: See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:UI Functions#creplaceLine|creplaceLine()]]<br />
<br />
;Parameters<br />
* ''window:''<br />
: Optional - the window name to echo to - can either be none or "main" for the main window, or the miniconsoles name.<br />
* ''text:''<br />
: The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
cecho("Hi! This text is <red>red, <blue>blue, <green> and green.")<br />
<br />
cecho("<:green>Green background on normal foreground. Here we add an <ivory>ivory foreground.")<br />
<br />
cecho("<blue:yellow>Blue on yellow text!")<br />
<br />
cecho("\n<red>Red text with <i>italics</i>, <u>underline</u> and <b>bold</b>.")<br />
<br />
-- \n adds a new line<br />
cecho("<red>one line\n<green>another line\n<blue>last line")<br />
<br />
cecho("myinfo", "<green>All of this text is green in the myinfo miniconsole.")<br />
<br />
cecho("<green>(╯°□°)<dark_green>╯︵ ┻━┻")<br />
<br />
cecho("°º¤ø,¸¸,ø¤º°`°º¤ø,¸,ø¤°º¤ø,¸¸,ø¤º°`°º¤ø,¸")<br />
<br />
cecho([[<br />
██╗ ██╗ ██╗███╗ ██╗███████╗ █████╗ ██████╗ ████████╗<br />
███║ ██║ ██║████╗ ██║██╔════╝ ██╔══██╗██╔══██╗╚══██╔══╝<br />
╚██║ ██║ ██║██╔██╗ ██║█████╗ ███████║██████╔╝ ██║<br />
██║ ██║ ██║██║╚██╗██║██╔══╝ ██╔══██║██╔══██╗ ██║<br />
██║ ███████╗██║██║ ╚████║███████╗ ██║ ██║██║ ██║ ██║<br />
╚═╝ ╚══════╝╚═╝╚═╝ ╚═══╝╚══════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝<br />
]])<br />
</syntaxhighlight><br />
<br />
==cechoLink==<br />
;cechoLink([windowName], text, command, hint, true)<br />
: Echos a piece of text as a clickable link, at the end of the current selected line - similar to [[Manual:Lua_Functions#cecho|cecho()]]. This version allows you to use colours within your link text.<br />
<br />
: See also: [[#echoLink|echoLink()]], [[#dechoLink|dechoLink()]], [[#hechoLink|hechoLink()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: optional parameter, allows selection between sending the link to a miniconsole or the main window.<br />
* ''text:''<br />
: text to display in the echo. Same as a normal [[Manual:Lua_Functions#cecho|cecho()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''true:''<br />
: requires argument for the colouring to work.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
cechoLink("<red>press <brown:white>me!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
cechoLink("<red>press <brown:white>me!", [[send("hi")]], "This is a tooltip", true)<br />
</syntaxhighlight><br />
<br />
==cechoPopup==<br />
;cechoPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current line, like [[#cecho|cecho()]]. 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.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. ie, <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
cechoPopup("<red>activities<reset> to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"}, true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
cechoPopup("<red>activities<reset> to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"}, true)<br />
</syntaxhighlight><br />
<br />
==cinsertLink==<br />
;cinsertLink([windowName], text, command, hint, true)<br />
: Echos a piece of text as a clickable link, at the end of the current cursor position - similar to [[#cinsertText|cinsertText()]]. This version allows you to use colours within your link text.<br />
<br />
: See also: [[#insertLink|insertLink()]], [[#hinsertLink|hinsertLink()]]<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: optional parameter, allows selection between sending the link to a miniconsole or the main window.<br />
* ''text:''<br />
: text to display in the echo. Same as a normal [[Manual:Lua_Functions#cecho|cecho()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''true:''<br />
: requires argument for the colouring to work.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
cinsertLink("<red>press <brown:white>me!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
cinsertLink("<red>press <brown:white>me!", [[send("hi")]], "This is a tooltip", true)<br />
</syntaxhighlight><br />
<br />
==cinsertPopup==<br />
;cinsertPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current cursor position, like [[#cinsertText|cinsertText()]]. 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.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. ie, <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
cinsertPopup("<red>activities<reset> to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"}, true)<br />
<br />
-- Create some text as a clickable with a popup menu:<br />
cinsertPopup("<red>activities<reset> to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"}, true)</syntaxhighlight><br />
<br />
==cinsertText==<br />
;cinsertText([window], text)<br />
: inserts text at the current cursor position, with the possibility for color tags.<br />
: See Also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:UI Functions#creplaceLine|creplaceLine()]]<br />
<br />
;Parameters<br />
* ''window:''<br />
: Optional - the window name to echo to - can either be none or "main" for the main window, or the miniconsoles name.<br />
* ''text:''<br />
: The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a double colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
cinsertText("Hi! This text is <red>red, <blue>blue, <green> and green.")<br />
<br />
cinsertText("<:green>Green background on normal foreground. Here we add an <ivory>ivory foreground.")<br />
<br />
cinsertText("<blue:yellow>Blue on yellow text!")<br />
<br />
cinsertText("myinfo", "<green>All of this text is green in the myinfo miniconsole.")<br />
</syntaxhighlight><br />
<br />
==clearUserWindow==<br />
;clearUserWindow([name])<br />
: This is (now) identical to [[Manual:Lua_Functions#clearWindow|clearWindow()]].<br />
<br />
==clearWindow==<br />
;clearWindow([windowName])<br />
: Clears the label, mini console, or user window with the name given as argument (removes all text from it). If you don't give it a name, it will clear the main window.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) The name of the label, mini console, or user window to clear. Passed as a string.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This would clear a label, user window, or miniconsole with the name "Chat"<br />
clearWindow("Chat")<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- this can clear your whole main window<br />
clearWindow()<br />
</syntaxhighlight><br />
<br />
==closestColor==<br />
; closestColor(colorOrR[,G,B])<br />
<br />
:Returns the closest color from the color_table to the one provided for use in cecho and associated functions.<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
;Parameters<br />
* ''colorOrR:''<br />
: Either the string representation of a color from decho or hecho (IE "#ff0077" or "<255,0,128>"), a table of color values (IE {255,0,18}), or the Red component of RGB when followed by two next optional parameters<br />
* ''G:''<br />
: (optional) green component of RGB coordinates. Only needed if first parameter sent as the Red component only<br />
* ''B:''<br />
: (optional) blue component of RGB coordinates. Only needed if first parameter sent as the Red component only<br />
<br />
;Returns<br />
* The closest color name from the color_table to the one supplied on success<br />
* nil + error if it cannot parse the parameters into a color.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local colorName = closestColor(255, 0, 0) -- "ansi_light_red"<br />
local colorName = closestColor({127, 255, 127}) -- "ansi_120"<br />
local colorName = closestColor("<127, 127, 127>") -- "ansi_008"<br />
local colorName = closestColor("#a020e6") -- "purple"<br />
local colorName = closestColor("blue") -- "blue" (you wouldn't necessarily do this on purpose, but during automated color conversions this might occur)<br />
</syntaxhighlight><br />
<br />
==copy==<br />
; copy([windowName])<br />
: Copies the current selection to the lua virtual clipboard. This function operates on rich text, i. e. the selected text including all its format codes like colors, fonts etc. in the lua virtual clipboard until it gets overwritten by another copy operation.<br />
: See also: [[#selectString|selectString()]], [[#selectCurrentLine|selectCurrentLine()]], [[#paste|paste()]], [[#appendBuffer|appendBuffer()]], [[#replace|replace()]], [[#createMiniConsole|createMiniConsole()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
; Parameters<br />
* ''windowName'' (optional):<br />
: the window from which to copy text - use the main console if not specified.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This script copies the current line on the main screen to a window (miniconsole or userwindow) called 'chat' and gags the output on the main screen.<br />
selectString(line, 1)<br />
copy()<br />
appendBuffer("chat")<br />
replace("This line has been moved to the chat window!")<br />
</syntaxhighlight><br />
<br />
==copy2decho==<br />
; copy2decho([window], [stringToCopy], [instanceToCopy])<br />
: Copies a string from the current line of window, including color information in decho format.<br />
: See also: [[#decho|decho()]]<br />
{{MudletVersion|4.8}}<br />
<br />
; Parameters<br />
* ''window'' (optional):<br />
: the window to copy the text from. Defaults to "main".<br />
* ''stringToCopy'' (optional): <br />
: the string to copy. Defaults to copying the entire line.<br />
* ''instanceToCopy'' (optional):<br />
: the instance of the string to copy. Defaults to 1.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This copies the current line on the main console and dechos it to a miniconsole named "test"<br />
decho("test", copy2decho())<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- This when put into a trigger would copy matches[2] with color information and decho it to a Geyser miniconsole stored as the variable enemylist<br />
enemylist:decho(copy2decho(matches[2]))<br />
</syntaxhighlight><br />
<br />
==copy2html==<br />
; copy2html([window], [stringToCopy], [instanceToCopy])<br />
: Copies a string from the current line of window, including color information in html format for echoing to a label.<br />
{{MudletVersion|4.8}}<br />
<br />
; Parameters<br />
* ''window'' (optional):<br />
: the window to copy the text from. Defaults to "main"<br />
* ''stringToCopy'' (optional): <br />
: the string to copy. Defaults to copying the entire line<br />
* ''instanceToCopy'' (optional):<br />
: the instance of the string to copy. Defaults to 1<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This copies the current line on the main console and echos it to a label named "TestLabel"<br />
echo("TestLabel", copy2html())<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- This when put into a trigger would copy matches[2] with color information and echo it to a Geyser label stored as the variable enemylist<br />
enemylist:echo(copy2html(matches[2]))<br />
</syntaxhighlight><br />
<br />
==createBuffer==<br />
;createBuffer(name)<br />
: Creates a named buffer for formatted text, much like a miniconsole, but the buffer is not intended to be shown on the screen - use it for formatting text or storing formatted text.<br />
<br />
: See also: [[#selectString|selectString()]], [[#selectCurrentLine|selectCurrentLine()]], [[#copy|copy()]], [[#paste|paste()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name of the buffer to create.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This creates a named buffer called "scratchpad"<br />
createBuffer("scratchpad")<br />
</syntaxhighlight><br />
<br />
==createCommandLine==<br />
;createCommandLine([name of userwindow], name, x, y, width, height)<br />
: Creates a new command line inside the main window of Mudlet. If only a command line inside a miniConsole/UserWindow is needed see [[Manual:UI_Functions#enableCommandLine|enableCommandLine()]].<br />
: You can use [[Manual:Mudlet_Object_Functions#appendCmdLine|appendCmdLine()]] / [[Manual:Mudlet_Object_Functions#getCmdLine|getCmdLine()]] and other command line functions to customize the input.<br />
{{note}} [[Manual:UI_Functions#setCmdLineAction|setCmdLineAction]] allows you to attach an action to your command line input.<br />
<br />
: Returns true or false.<br />
<br />
: See also: [[Manual:UI_Functions#enableCommandLine|enableCommandLine()]], [[Manual:UI_Functions#disableCommandLine|disableCommandLine()]], [[Manual:Mudlet_Object_Functions#clearCmdLine|clearCmdLine()]], [[Manual:Mudlet_Object_Functions#getCmdLine|getCmdLine()]], [[Manual:Mudlet_Object_Functions#printCmdLine|printCmdLine()]], [[Manual:Mudlet_Object_Functions#appendCmdLine|appendCmdLine()]]<br />
<br />
;Parameters<br />
* ''name of userwindow:''<br />
: Name of userwindow the command line is created in. Optional, defaults to the main window if not provided.<br />
* ''name:''<br />
: The name of the command line. Must be unique. Passed as a string.<br />
* ''x'', ''y'', ''width'', ''height''<br />
: Parameters to set the command line size and location - it is also possible to set them by using [[Manual:Lua_Functions#moveWindow|moveWindow()]] and [[Manual:Lua_Functions#resizeWindow|resizeWindow()]], as createCommandLine() will only set them once.<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
==createConsole==<br />
;createConsole([name of userwindow], consoleName, fontSize, charsPerLine, numberOfLines, Xpos, Ypos)<br />
: Makes a new miniconsole which can be sized based upon the width of a 'W' character and the extreme top and bottom positions any character of the font should use. The background will be black, and the text color white.<br />
<br />
;Parameters<br />
* ''name of userwindow:''<br />
: Name of userwindow your new miniconsole is created in. Optional, defaults to the main window if not provided.<br />
* ''consoleName:''<br />
: The name of your new miniconsole. Passed as a string.<br />
* ''fontSize:''<br />
: The font size to use for the miniconsole. Passed as an integer number.<br />
* ''charsPerLine:''<br />
: How many characters wide to make the miniconsole. Passed as an integer number.<br />
* ''numberOfLines:''<br />
: How many lines high to make the miniconsole. Passed as an integer number.<br />
* ''Xpos:''<br />
: X position of miniconsole. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''Ypos:''<br />
: Y position of miniconsole. Measured in pixels, with 0 being the very top. Passed as an integer number.<br />
<br />
{{note}}<br />
userwindow argument only available in 4.6.1+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- this will create a console with the name of "myConsoleWindow", font size 8, 80 characters wide,<br />
-- 20 lines high, at coordinates 300x,400y<br />
createConsole("myConsoleWindow", 8, 80, 20, 200, 400)<br />
</syntaxhighlight><br />
<br />
{{note}}<br />
''(For Mudlet Makers)'' This function is implemented outside the application's core via the '''GUIUtils.lua''' file of the Mudlet supporting Lua code using [[Manual:UI_Functions#createMiniConsole|createMiniConsole()]] and other functions to position and size the mini-console and configure the font.<br />
<br />
==createGauge==<br />
;createGauge([name of userwindow], name, width, height, Xpos, Ypos, gaugeText, r, g, b, orientation)<br />
;createGauge([name of userwindow], name, width, height, Xpos, Ypos, gaugeText, colorName, orientation)<br />
: Creates a gauge that you can use to express completion with. For example, you can use this as your healthbar or xpbar.<br />
: See also: [[Manual:Lua_Functions#moveGauge|moveGauge()]], [[Manual:Lua_Functions#setGauge|setGauge()]], [[Manual:Lua_Functions#setGaugeText|setGaugeText()]], [[#setGaugeStyleSheet|setGaugeStyleSheet()]]<br />
<br />
;Parameters<br />
* ''name of userwindow:''<br />
: Name of userwindow the gauge is created in. Optional, defaults to the main window if not provided.<br />
* ''name:''<br />
: The name of the gauge. Must be unique, you can not have two or more gauges with the same name. Passed as a string.<br />
* ''width:''<br />
: The width of the gauge, in pixels. Passed as an integer number.<br />
* ''height:''<br />
: The height of the gauge, in pixels. Passed as an integer number.<br />
* ''Xpos:''<br />
: X position of gauge. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''Ypos:''<br />
: Y position of gauge. Measured in pixels, with 0 being the very top. Passed as an integer number.<br />
* ''gaugeText:''<br />
: Text to display on the gauge. Passed as a string, unless you do not wish to have any text, in which case you pass nil<br />
* ''r:''<br />
: The red component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''g:''<br />
: The green component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''b:''<br />
: The blue component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''colorName:''<br />
: the name of color for the gauge. Passed as a string.<br />
* ''orientation:''<br />
: the gauge orientation. Can be horizontal (fills from left to right), vertical (fills bottom to top), goofy (fills right to left), or batty (fills top to bottom).<br />
<br />
{{note}}<br />
userwindow argument only available in 4.6.1+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This would make a gauge at that's 300px width, 20px in height, located at Xpos and Ypos and is green.<br />
-- The second example is using the same names you'd use for something like [[fg]]() or [[bg]]().<br />
createGauge("healthBar", 300, 20, 30, 300, nil, 0, 255, 0)<br />
createGauge("healthBar", 300, 20, 30, 300, nil, "green")<br />
<br />
<br />
-- If you wish to have some text on your label, you'll change the nil part and make it look like this:<br />
createGauge("healthBar", 300, 20, 30, 300, "Now with some text", 0, 255, 0)<br />
-- or<br />
createGauge("healthBar", 300, 20, 30, 300, "Now with some text", "green")<br />
</syntaxhighlight><br />
<br />
{{note}}<br />
If you want to put text on the back of the gauge when it's low, use an echo with the <gauge name>_back.<br />
<syntaxhighlight lang="lua"><br />
echo("healthBar_back", "This is a test of putting text on the back of the gauge!")<br />
</syntaxhighlight><br />
<br />
==createLabel==<br />
;createLabel([name of userwindow], name, Xpos, Ypos, width, height, fillBackground, [enableClickthrough])<br />
: Creates a highly manipulable overlay which can take some css and html code for text formatting. Labels are clickable, and as such can be used as a sort of button. Labels are meant for small variable or prompt displays, messages, images, and the like. You should not use them for larger text displays or things which will be updated rapidly and in high volume, as they are much slower than miniconsoles.<br />
: Returns true or false.<br />
: See also: [[Manual:Lua_Functions#hideWindow|hideWindow()]], [[Manual:Lua_Functions#showWindow|showWindow()]], [[Manual:Lua_Functions#resizeWindow|resizeWindow()]], [[Manual:Lua_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:Lua_Functions#setTextFormat|setTextFormat()]], [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#moveWindow|moveWindow()]], [[Manual:Lua_Functions#setBackgroundColor|setBackgroundColor()]], [[Manual:Lua_Functions#getMainWindowSize|getMainWindowSize()]], [[Manual:Lua_Functions#calcFontSize|calcFontSize()]], [[Manual:Lua_Functions#deleteLabel|deleteLabel()]]<br />
<br />
;Parameters<br />
* ''name of userwindow:'' Name of userwindow label is created in. Optional, defaults to the main window if not provided.<br />
* ''name:'' name of the label. Must be unique, you can not have two or more labels with the same name. Passed as a string.<br />
* ''Xpos:'' X position of the label. Measured in pixels, with 0 being the very left. Passed as an integer number.<br />
* ''Ypos:'' Y position of the label. Measured in pixels, with 0 being the very top. Passed as an integer number.<br />
* ''width:'' width of the label, in pixels. Passed as an integer number.<br />
* ''height:'' height of the label, in pixels. Passed as an integer number.<br />
* ''fillBackground:'' whether or not to display the background. Passed as integer number (1 or 0) or as boolean (true, false). 1 or true will display the background color, 0 or false will not.<br />
* ''enableClickthrough:'' whether or not enable clickthrough on this label. Passed as integer number (1 or 0) or as boolean (true, false). 1 or true will enable clickthrough, 0 or false will not. Optional, defaults to clickthrough not enabled if not provided.<br />
<br />
{{note}}<br />
userwindow argument only available in 4.6.1+<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
-- a label situated at x=300 y=400 with dimensions 100x200<br />
createLabel("a very basic label",300,400,100,200,1)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- this example creates a transparent overlay message box to show a big warning message "You are under attack!" in the middle<br />
-- of the screen. Because the background color has a transparency level of 150 (0-255, with 0 being completely transparent<br />
-- and 255 opaque) the background text can still be read through.<br />
local width, height = getMainWindowSize()<br />
createLabel("messageBox",(width/2)-300,(height/2)-100,250,150,1)<br />
resizeWindow("messageBox",500,70)<br />
moveWindow("messageBox", (width/2)-300,(height/2)-100 )<br />
setBackgroundColor("messageBox", 255, 204, 0, 200)<br />
echo("messageBox", [[<p style="font-size:35px"><b><center><font color="red">You are under attack!</font></center></b></p>]])<br />
<br />
-- you can also make it react to clicks!<br />
mynamespace = {<br />
messageBoxClicked = function()<br />
echo("hey you've clicked the box!\n")<br />
end<br />
}<br />
<br />
setLabelClickCallback("messageBox", "mynamespace.messageBoxClicked")<br />
<br />
<br />
-- uncomment code below to make it also hide after a short while<br />
-- tempTimer(2.3, [[hideWindow("messageBox")]] ) -- close the warning message box after 2.3 seconds<br />
</syntaxhighlight><br />
<br />
==createMiniConsole==<br />
;createMiniConsole([name of userwindow], name, x, y, width, height)<br />
: Opens a miniconsole window inside the main window of Mudlet. This is the ideal fast colored text display for everything that requires a bit more text, such as status screens, chat windows, etc. Unlike labels, you cannot have transparency in them.<br />
: You can use [[Manual:Lua_Functions#clearWindow|clearWindow()]] / [[Manual:Lua_Functions#moveCursor|moveCursor()]] and other functions for this window for custom printing as well as copy & paste functions for colored text copies from the main window. [[Manual:Lua_Functions#setWindowWrap|setWindowWrap()]] will allow you to set word wrapping, and move the main window to make room for miniconsole windows on your screen (if you want to do this as you can also layer mini console and label windows) see [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#setBorderColor|setBorderColor()]] functions.<br />
<br />
: Returns true or false.<br />
<br />
: See also: [[Manual:Lua_Functions#createLabel|createLabel()]], [[Manual:Lua_Functions#hideWindow|hideWindow()]], [[Manual:Lua_Functions#showWindow|showWindow()]], [[Manual:Lua_Functions#resizeWindow|resizeWindow()]], [[Manual:Lua_Functions#setTextFormat|setTextFormat()]], [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#moveWindow|moveWindow()]], [[Manual:Lua_Functions#setMiniConsoleFontSize|setMiniConsoleFontSize()]], [[Manual:Lua_Functions#handleWindowResizeEvent|handleWindowResizeEvent()]], [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#setWindowWrap|setWindowWrap()]], [[Manual:Lua_Functions#getMainWindowSize|getMainWindowSize()]], [[Manual:Lua_Functions#setMainWindowSize|setMainWindowSize()]], [[Manual:Lua_Functions#calcFontSize|calcFontSize()]]<br />
<br />
;Parameters<br />
* ''name of userwindow:'' (available in Mudlet 4.6.1+)<br />
: (Optional) name of userwindow the miniconsole is created in. Defaults to the main window if not provided.<br />
* ''name:''<br />
: The name of the miniconsole. Must be unique. Passed as a string.<br />
* ''x'', ''y'', ''width'', ''height''<br />
: Parameters to set set the window size and location - in Mudlet version 2.1 and below it's best to set them via [[Manual:Lua_Functions#moveWindow|moveWindow()]] and [[Manual:Lua_Functions#resizeWindow|resizeWindow()]], as createMiniConsole() will only set them once. Starting with Mudlet version 3.0, however, that is fine and calling createMiniConsole() will re-position your miniconsole appropriately.<br />
<br />
;Example<br />
<br />
==creplace==<br />
;creplace([window, ]text)<br />
: Replaces the output line from the game with a colour-tagged string.<br />
See Also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:Lua_Functions#cinsertText|cinsertText()]]<br />
;Parameters<br />
* ''window:''<br />
*: The window to replace the selection in. Optional, defaults to the main window if not provided.<br />
* ''text:''<br />
*: The text to display, with color names inside angle brackets as with [[Manual:Lua_Functions#cecho|cecho()]]. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectCaptureGroup(1)<br />
creplace("<magenta>[ALERT!]: <reset>"..matches[2])<br />
</syntaxhighlight><br />
<br />
==creplaceLine==<br />
;creplaceLine ([window], text)<br />
: Replaces the output line from the game with a colour-tagged string.<br />
See Also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:Lua_Functions#cinsertText|cinsertText()]]<br />
;Parameters<br />
* ''window'' (optional):<br />
: the window to copy the text from. Defaults to "main". Only supported in Mudlet 4.12+<br />
* ''text:''<br />
*: The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua">creplaceLine("<magenta>[ALERT!]: <reset>"..line)<br />
</syntaxhighlight><br />
<br />
==decho==<br />
;decho ([name of console,] text)<br />
: Color changes can be made using the format <FR,FG,FB:BR,BG,BB,[BA]> where each field is a number from 0 to 255. The background portion can be omitted using <FR,FG,FB> or the foreground portion can be omitted using <:BR,BG,BB,[BA]>. Arguments 2 and 3 set the default fore and background colors for the string using the same format as is used within the string, sans angle brackets, e.g. ''decho("<50,50,0:0,255,0>test")''.<br />
:You can also include <code><nowiki><i>italics</i></nowiki></code>, <code><nowiki><b>bold</b></nowiki></code> and <code><nowiki><u>underline</u></nowiki></code> tags.<br />
<br />
: See also: [[#cecho|cecho()]], [[#hecho|hecho()]], [[#copy2decho|copy2decho()]]<br />
<br />
;Parameters<br />
* ''name of console''<br />
: (Optional) Name of the console to echo to. If no name is given, this will defaults to the main window.<br />
* ''text:''<br />
: The text that you’d like to echo with embedded color tags. Tags take the RGB values only, see below for an explanation.<br />
<br />
<br />
{{note}}<br />
Optional background transparancy parameter (BA) available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
decho("<50,50,0:0,255,0>test")<br />
<br />
decho("miniconsolename", "<50,50,0:0,255,0>test")<br />
<br />
decho("\n<255,0,0>Red text with <i>italics</i>, <u>underline</u> and <b>bold</b> formatting.")<br />
</syntaxhighlight><br />
<br />
==dechoLink==<br />
;dechoLink([windowName], text, command, hint, true)<br />
: Echos a piece of text as a clickable link, at the end of the current selected line - similar to [[Manual:Lua_Functions#decho|decho()]]. This version allows you to use colours within your link text.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) allows selection between sending the link to a miniconsole or the "main" window.<br />
* ''text:''<br />
: text to display in the echo. Same as a normal [[Manual:Lua_Functions#decho|decho()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''true:''<br />
: requires argument for the colouring to work.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
dechoLink("<50,50,0:0,255,0>press me!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
dechoLink("<50,50,0:0,255,0>press me!", [[send("hi")]], "This is a tooltip", true)<br />
</syntaxhighlight><br />
<br />
==dechoPopup==<br />
;dechoPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current line, like [[#decho|decho()]]. 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.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code strings to do or a functions (since Mudlet 4.11). ie, <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
dechoPopup("<255,0,0>activities<r> to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"}, true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
dechoPopup("<255,0,0>activities<r> to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"}, true)<br />
</syntaxhighlight><br />
<br />
==dinsertLink==<br />
;dinsertLink([windowName], text, command, hint, true)<br />
: Echos a piece of text as a clickable link, at the end of the current cursor position - similar to [[#dinsertText|dinsertText()]]. This version allows you to use colours within your link text.<br />
<br />
: See also: [[#insertLink|insertLink()]], [[#hinsertLink|hinsertLink()]]<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: optional parameter, allows selection between sending the link to a miniconsole or the main window.<br />
* ''text:''<br />
: text to display in the echo. Same as a normal [[Manual:Lua_Functions#decho|decho()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''true:''<br />
: requires argument for the colouring to work.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
dinsertLink("<255,0,0>press <165,42,42:255,255,255>me!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
dinsertLink("<255,0,0>press <165,42,42:255,255,255>me!", [[send("hi")]], "This is a tooltip", true)<br />
</syntaxhighlight><br />
<br />
==dinsertPopup==<br />
;dinsertPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current cursor position, like [[#dinsertText|dinsertText()]]. 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.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. ie, <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
dinsertPopup("<255,0,0>activities<r> to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"}, true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
dinsertPopup("<255,0,0>activities<r> to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"}, true)<br />
</syntaxhighlight><br />
<br />
== deleteLabel ==<br />
; deleteLabel(labelName)<br />
<br />
: Deletes and removes a label from the screen. Note that if you'd like to show the label again, it is much more performant to hide/show it instead.<br />
<br />
: Note that you shouldn't use the Geyser label associated with the label you delete afterwards - that doesn't make sense and Geyser right now wouldn't know that it's been deleted, either.<br />
<br />
: See also: [[#hideWindow|hideWindow()]], [[#showWindow|showWindow()]], [[#createLabel|createLabel()]]<br />
<br />
; Parameters<br />
<br />
* ''labelName'': name of the label to delete.<br />
<br />
<syntaxhighlight lang="lua"><br />
createLabel("a very basic label",300,400,100,200,1)<br />
setBackgroundColor("a very basic label", 255, 204, 0, 200)<br />
<br />
-- delete the label after 3 seconds<br />
tempTimer(3, function()<br />
deleteLabel("a very basic label")<br />
end)<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.5}}<br />
<br />
==deleteLine==<br />
;deleteLine([windowName])<br />
: Deletes the current line under the user cursor. This is a high speed gagging tool and is very good at this task, but is only meant to be use when a line should be omitted entirely in the output. If you echo() to that line it will not be shown, and lines deleted with deleteLine() are simply no longer rendered. This is purely visual - triggers will still fire on the line as expected.<br />
: See also: [[Manual:Lua_Functions#replace|replace()]], [[Manual:Lua_Functions#wrapLine|wrapLine()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to delete the line in. If no name is given, it just deletes the line it is used on.<br />
<br />
{{note}} for replacing text, [[Manual:Lua_Functions#replace|replace()]] is the proper option; doing the following: <code>selectCurrentLine(); replace(""); cecho("new line!\n")</code> is better.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- deletes the line - just put this command into the big script box. Keep the case the same -<br />
-- it has to be deleteLine(), not Deleteline(), deleteline() or anything else<br />
deleteLine()<br />
<br />
--This example creates a temporary line trigger to test if the next line is a prompt, and if so gags it entirely.<br />
--This can be useful for keeping a pile of prompts from forming if you're gagging chat channels in the main window<br />
--Note: isPrompt() only works on servers which send a GA signal with their prompt.<br />
tempLineTrigger(1, 1, [[if isPrompt() then deleteLine() end]])<br />
<br />
-- example of deleting multiple lines:<br />
deleteLine() -- delete the current line<br />
moveCursor(0,getLineNumber()-1) -- move the cursor back one line<br />
deleteLine() -- delete the previous line now<br />
</syntaxhighlight><br />
<br />
==deselect==<br />
;deselect([window name])<br />
: This is used to clear the current selection (to no longer have anything selected). Should be used after changing the formatting of text, to keep from accidentally changing the text again later with another formatting call.<br />
: See also: [[#selectString|selectString()]], [[#selectCurrentLine|selectCurrentLine()]]<br />
<br />
;Parameters<br />
* ''window name:''<br />
: (optional) The name of the window to stop having anything selected in. If name is not provided the main window will have its selection cleared.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This will change the background on an entire line in the main window to red, and then properly clear the selection to keep further<br />
--changes from effecting this line as well.<br />
selectCurrentLine()<br />
bg("red")<br />
deselect()<br />
</syntaxhighlight><br />
<br />
==disableClickthrough==<br />
; disableClickthrough(label)<br />
: Disables clickthrough for a label - making it act 'normal' again and receive clicks, doubleclicks, onEnter, and onLeave events. This is the default behaviour for labels.<br />
: See also: [[#enableClickthrough|enableClickthrough()]]<br />
<br />
;Parameters<br />
* ''label:''<br />
: Name of the label to restore clickability on.<br />
<br />
{{MudletVersion|3.17}}<br />
<br />
==disableCommandLine==<br />
; disableCommandLine(windowName)<br />
: Disables the command line for the miniConsole named ''windowName''<br />
: See Also: [[Manual:Lua_Functions#enableCommandLine|enableCommandLine()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of the miniConsole to disable the command line in.<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
==disableHorizontalScrollBar==<br />
; disableHorizontalScrollBar([windowName])<br />
: Disables the horizontal scroll bar for the miniConsole/userwindow ''windowName'' or the main window<br />
: See Also: [[Manual:Lua_Functions#enableHorizontalScrollBar|enableHorizontalScrollBar()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of the window to disable the scroll bar in. If "main" or not provided it is the main console.<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
==disableScrollBar==<br />
; disableScrollBar([windowName])<br />
: Disables the scroll bar for the miniConsole/userwindow ''windowName'' or the main window<br />
: See Also: [[Manual:Lua_Functions#enableScrollBar|enableScrollBar()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) The name of the window to disable the scroll bar in. If "main" or not provided it is the main console.<br />
<br />
==dreplace==<br />
;dreplace([window, ]text)<br />
: Replaces the output line from the game with a colour-tagged string.<br />
See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#dinsertText|dinsertText()]]<br />
;Parameters<br />
* ''window:''<br />
*: The window to replace the selection in. Optional, defaults to the main window if not provided.<br />
* ''text:''<br />
*: The text to display, as with [[Manual:Lua_Functions#decho|decho()]]<br />
:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectCaptureGroup(1)<br />
dreplace("<255,0,255>[ALERT!]: <r>"..matches[2])<br />
</syntaxhighlight><br />
<br />
==dreplaceLine==<br />
;dreplaceLine ([window], text)<br />
: Replaces the output line from the game with a colour-tagged string.<br />
{{MudletVersion|4.12}}<br />
See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#dinsertText|dinsertText()]]<br />
;Parameters<br />
* ''window'' (optional):<br />
: the window to copy the text from. Defaults to "main".<br />
* ''text:''<br />
*: The text to display, with RGB color values inside angle brackets <>, ie ''<128,0,0>''. If you'd like to use a background color, put it after a colon : - ''<:128,0,0>''. You can use the ''<r>'' tag to reset to the default color. <br />
:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua">dreplaceLine("<255,0,255>[ALERT!]: <r>"..line)<br />
</syntaxhighlight><br />
<br />
==echoLink==<br />
;echoLink([windowName], text, command, hint, [useCurrentFormatElseDefault])<br />
: Echos a piece of text as a clickable link, at the end of the current selected line - similar to [[Manual:Lua_Functions#echo|echo()]].<br />
<br />
: See also: [[#cechoLink|cechoLink()]], [[#hechoLink|hechoLink()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) either be none or "main" for the main console, or a miniconsole / userwindow name.<br />
* ''text:''<br />
: Text to display in the echo. Same as a normal echo().<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: Text for the tooltip to be displayed when the mouse is over the link.<br />
* ''useCurrentFormatElseDefault:''<br />
: If true, then the link will use the current selection style (colors, underline, etc). If missing or false, it will use the default link style - blue on black underlined text.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
echoLink("press me!", function() send("hi") end, "This is a tooltip")<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
echoLink("press me!", [[send("hi")]], "This is a tooltip")<br />
<br />
-- do the same, but send this link to a miniConsole<br />
echoLink("my miniConsole", "press me!", function() send("hi") end, "This is a tooltip")<br />
</syntaxhighlight><br />
<br />
==echoUserWindow==<br />
;echoUserWindow(windowName, text)<br />
:This function will print text to both mini console windows, dock windows and labels. It is outdated however - [[Manual:Lua_Functions#echo|echo()]] instead.<br />
<br />
==echoPopup==<br />
;echoPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: 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.<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. i.e. <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
echoPopup("activities to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"})<br />
<br />
-- alternatively, put commands as text (in [[ and ]] to use quotation marks inside)<br />
echoPopup("activities to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"})<br />
</syntaxhighlight><br />
<br />
==enableClickthrough==<br />
; enableClickthrough(label)<br />
: Make a label 'invisible' to clicks - so if you have another label underneath, it'll be clicked on instead of this one on top.<br />
: This affects clicks, double-clicks, right-clicks, as well as the onEnter/onLeave events.<br />
: See also: [[#disableClickthrough|disableClickthrough()]]<br />
<br />
;Parameters<br />
* ''label:''<br />
: The name of the label to enable clickthrough on.<br />
<br />
{{MudletVersion|3.17}}<br />
<br />
==enableCommandLine==<br />
; enableCommandLine(windowName)<br />
: Enables the command line for the miniConsole named ''windowName''<br />
: See Also: [[Manual:Lua_Functions#disableCommandLine|disableCommandLine()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of the miniConsole to enable the command line in.<br />
<br />
{{note}} The command line name is the same as the miniConsole name<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
==enableHorizontalScrollBar==<br />
; enableHorizontalScrollBar([windowName])<br />
: Enables the horizontal scroll bar for the miniConsole/userwindow ''windowName'' or the main window<br />
: See Also: [[Manual:Lua_Functions#disableHorizontalScrollBar|disableHorizontalScrollBar()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of the window to enable the scroll bar in. If "main" or not provided it is the main console.<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
==enableScrollBar==<br />
; enableScrollBar([windowName])<br />
: Enables the scroll bar for the miniConsole/userwindow ''windowName'' or the main window<br />
: See Also: [[Manual:Lua_Functions#disableScrollBar|disableScrollBar()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of the window to enable the scroll bar in. If "main" or not provided it is the main console.<br />
<br />
==fg==<br />
; fg([window], colorName)<br />
: If used on a selection, sets the foreground color to ''colorName'' - otherwise, it will set the color of the next text-inserting calls (''echo(), insertText, echoLink()'', and others)<br />
: See Also: [[Manual:Lua_Functions#bg|bg()]], [[Manual:Lua_Functions#setBgColor|setBgColor()]]<br />
<br />
;Parameters<br />
* ''window:''<br />
: (optional) name of the miniconsole to operate on. If you'd like it to work on the main window, don't specify anything or use ''main'' (since Mudlet 3.0).<br />
* ''colorName:''<br />
: The name of the color to set the foreground to - list of possible names: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--This would change the color of the text on the current line to green<br />
selectCurrentLine()<br />
fg("green")<br />
resetFormat()<br />
<br />
--This will echo red, green, blue in their respective colors<br />
fg("red")<br />
echo("red ")<br />
fg("green")<br />
echo("green ")<br />
fg("blue")<br />
echo("blue ")<br />
resetFormat()<br />
<br />
-- example of working on a miniconsole<br />
fg("my console", "red")<br />
echo("my console", "red text")<br />
</syntaxhighlight><br />
<br />
==getAvailableFonts==<br />
; getAvailableFonts()<br />
: This returns a "font - true" key-value list of available fonts which you can use to verify that Mudlet has access to a given font.<br />
: To install a new font with your package, include the font file in your zip/mpackage and it'll be automatically installed for you.<br />
<br />
: See also: [[#getFont|getFont()]], [[#setFont|setFont()]]<br />
<br />
{{MudletVersion|3.10}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- check if Ubuntu Mono is a font we can use<br />
if getAvailableFonts()["Ubuntu Mono"] then<br />
-- make the miniconsole use the font at size 16<br />
setFont("my miniconsole", "Ubuntu Mono")<br />
setFontSize("my miniconsole", 16)<br />
end<br />
</syntaxhighlight><br />
<br />
==getBgColor==<br />
; getBgColor(windowName)<br />
: This function returns the rgb values of the background color of the first character of the current selection on mini console (window) windowName. If windowName is omitted Mudlet will use the main screen.<br />
<br />
: See also: [[#setBgColor|setBgColor()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: A window to operate on - either a miniconsole or the main window.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local r,g,b;<br />
selectString("troll",1)<br />
r,g,b = getBgColor()<br />
if r == 255 and g == 0 and b == 0 then<br />
echo("HELP! troll is highlighted in red letters, the monster is aggressive!\n");<br />
end<br />
</syntaxhighlight><br />
<br />
==getBorderBottom==<br />
;getBorderBottom()<br />
: Returns the size of the bottom border of the main window in pixels. <br />
: See also: [[Manual:Lua_Functions#getBorderSizes|getBorderSizes()]], [[Manual:Lua_Functions#setBorderBottom|setBorderBottom()]]<br />
<br />
: {{MudletVersion|4.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderBottom(150)<br />
getBorderBottom()<br />
-- returns: 150<br />
</syntaxhighlight><br />
<br />
==getBorderLeft==<br />
;getBorderLeft()<br />
: Returns the size of the left border of the main window in pixels. <br />
: See also: [[Manual:Lua_Functions#getBorderSizes|getBorderSizes()]], [[Manual:Lua_Functions#setBorderLeft|setBorderLeft()]]<br />
<br />
: {{MudletVersion|4.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderLeft(5)<br />
getBorderLeft()<br />
-- returns: 5<br />
</syntaxhighlight><br />
<br />
==getBorderRight==<br />
;getBorderRight()<br />
: Returns the size of the right border of the main window in pixels. <br />
: See also: [[Manual:Lua_Functions#getBorderSizes|getBorderSizes()]], [[Manual:Lua_Functions#setBorderRight|setBorderRight()]]<br />
<br />
: {{MudletVersion|4.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderRight(50)<br />
getBorderRight()<br />
-- returns: 50<br />
</syntaxhighlight><br />
<br />
==getBorderSizes==<br />
;getBorderSizes()<br />
: Returns the a named table with the sizes of all borders of the main window in pixels. <br />
: See also: [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#getBorderTop|getBorderTop()]], [[Manual:Lua_Functions#getBorderRight|getBorderRight()]],[[Manual:Lua_Functions#getBorderBottom|getBorderBottom()]], [[Manual:Lua_Functions#getBorderLeft|getBorderLeft()]]<br />
<br />
: {{MudletVersion|4.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderSizes(100, 50, 150, 0)<br />
getBorderSizes()<br />
-- returns: { top = 100, right = 50, bottom = 150, left = 0 }<br />
getBorderSizes().right<br />
-- returns: 50<br />
</syntaxhighlight><br />
<br />
==getBorderTop==<br />
;getBorderTop()<br />
: Returns the size of the top border of the main window in pixels. <br />
: See also: [[Manual:Lua_Functions#getBorderSizes|getBorderSizes()]], [[Manual:Lua_Functions#setBorderTop|setBorderTop()]]<br />
<br />
: {{MudletVersion|4.0}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderTop(100)<br />
getBorderTop()<br />
-- returns: 100<br />
</syntaxhighlight><br />
<br />
==getClipboardText==<br />
;getClipboardText()<br />
: Returns any text that is currently present in the clipboard. <br />
: See also: [[#setClipboardText | setClipboardText()]]<br />
<br />
: {{note}} Note: Available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local clipboardContents = getClipboardText()<br />
echo("Clipboard: " .. clipboardContents)<br />
</syntaxhighlight><br />
<br />
==getColorWildcard==<br />
; getColorWildcard(ansi color number)<br />
: This function, given an ANSI color number ([[Manual:UI_Functions#isAnsiFgColor|list]]), will return all strings on the current line that match it.<br />
<br />
: See also: [[#isAnsiFgColor|isAnsiFgColor()]], [[#isAnsiBgColor|isAnsiBgColor()]]<br />
<br />
;Parameters<br />
* ''ansi color number:''<br />
: A color number ([[Manual:UI_Functions#isAnsiFgColor|list]]) to match.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- we can run this script on a line that has the players name coloured differently to easily capture it from<br />
-- anywhere on the line<br />
local match = getColorWildcard(14) -- this will be a table of every match<br />
<br />
if match then -- if there's a table, then we try and print it on the screen!<br />
echo("\nFound "..table.concat(match, ", ").."!") -- this will combine all captured strings and separate them with a comma so it's easy to read.<br />
else -- if there isn't something in match, then we haven't found anything to print on the screen!<br />
echo("\nDidn't find anyone.") <br />
end<br />
</syntaxhighlight><br />
<br />
==getColumnCount==<br />
;getColumnCount([windowName])<br />
: Gets the maximum number of columns (characters) that a given window can display on a single row, taking into consideration factors such as window width, font size, spacing, etc.<br />
<br />
;Parameters:<br />
* ''windowName'':<br />
: (optional) name of the window whose number of columns we want to calculate. By default it operates on the main window.<br />
<br />
{{MudletVersion|3.7}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
print("Maximum number of columns on the main window "..getColumnCount())<br />
</syntaxhighlight><br />
<br />
==getColumnNumber==<br />
;getColumnNumber([windowName])<br />
: Gets the absolute column number of the current user cursor.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) either be none or "main" for the main console, or a miniconsole / userwindow name.<br />
<br />
{{note}} the argument is available since Mudlet 3.0.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
HelloWorld = Geyser.MiniConsole:new({<br />
name="HelloWorld",<br />
x="70%", y="50%",<br />
width="30%", height="50%",<br />
})<br />
<br />
HelloWorld:echo("hello!\n")<br />
HelloWorld:echo("hello!\n")<br />
HelloWorld:echo("hello!\n")<br />
<br />
moveCursor("HelloWorld", 3, getLastLineNumber("HelloWorld"))<br />
-- should say 3, because we moved the cursor in the HellWorld window to the 3rd position in the line<br />
print("getColumnNumber: "..tostring(getColumnNumber("HelloWorld")))<br />
<br />
moveCursor("HelloWorld", 1, getLastLineNumber("HelloWorld"))<br />
-- should say 3, because we moved the cursor in the HellWorld window to the 1st position in the line<br />
print("getColumnNumber: "..tostring(getColumnNumber("HelloWorld")))<br />
</syntaxhighlight><br />
<br />
==getCurrentLine==<br />
;getCurrentLine([windowName])<br />
: Returns the content of the current line under the user cursor in the buffer. The Lua variable '''line''' holds the content of ''getCurrentLine()'' before any triggers have been run on this line. When triggers change the content of the buffer, the variable line will not be adjusted and thus hold an outdated string. ''line = getCurrentLine()'' will update line to the real content of the current buffer. This is important if you want to copy the current line after it has been changed by some triggers. ''selectString( line,1 )'' will return false and won't select anything because line no longer equals ''getCurrentLine()''. Consequently, ''selectString( getCurrentLine(), 1 )'' is what you need.<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window in which to select text.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
print("Currently selected line: "..getCurrentLine())<br />
</syntaxhighlight><br />
<br />
==getFgColor==<br />
; getFgColor(windowName)<br />
: This function returns the rgb values of the color of the first character of the current selection on mini console (window) windowName. If windowName is omitted Mudlet will use the main screen.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: A window to operate on - either a miniconsole or the main window.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectString("troll",1)<br />
local r,g,b = getFgColor()<br />
if r == 255 and g == 0 and b == 0 then<br />
echo("HELP! troll is written in red letters, the monster is aggressive!\n");<br />
end<br />
</syntaxhighlight><br />
<br />
==getFont==<br />
;getFont([windowName])<br />
: Gets the current font of the given window or console name. Can be used to get font of the main console, dockable userwindows and miniconsoles.<br />
: See also: [[#setFont|setFont()]], [[#setFontSize|setFontSize()]], [[#openUserWindow|openUserWindow()]], [[#getAvailableFonts|getAvailableFonts()]]<br />
<br />
{{MudletVersion|3.4}}<br />
{{note}} Since Mudlet 3.10, returns the actual font that was used in case you didn't have the required font when using [[#setFont|setFont()]].<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The window name to get font size of - can either be none or "main" for the main console, or a miniconsole/userwindow name.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The following will get the "main" console font size.<br />
display("Font in the main window: "..getFont())<br />
<br />
display("Font in the main window: "..getFont("main"))<br />
<br />
-- This will get the font size of a user window named "user window awesome".<br />
display("Font size: " .. getFont("user window awesome"))<br />
</syntaxhighlight><br />
<br />
==getFontSize==<br />
;getFontSize([windowName])<br />
: Gets the current font size of the given window or console name. Can be used to get font size of the Main console as well as dockable UserWindows.<br />
: See also: [[#setFontSize|setFontSize()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The window name to get font size of - can either be none or "main" for the main console, or a UserWindow name.<br />
<br />
{{MudletVersion|3.4}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The following will get the "main" console font size.<br />
local mainWindowFontSize = getFontSize()<br />
if mainWindowFontSize then<br />
display("Font size: " .. mainWindowFontSize)<br />
end<br />
<br />
local mainWindowFontSize = getFontSize("main")<br />
if mainWindowFontSize then<br />
display("Font size: " .. fs2)<br />
end<br />
<br />
-- This will get the font size of a user window named "user window awesome".<br />
local awesomeWindowFontSize = getFontSize("user window awesome")<br />
if awesomeWindowFontSize then<br />
display("Font size: " .. awesomeWindowFontSize)<br />
end<br />
</syntaxhighlight><br />
<br />
==getImageSize==<br />
;getImageSize(imageLocation)<br />
: Returns the width and the height of the given image. If the image can't be found, loaded, or isn't a valid image file - nil+error message will be returned instead.<br />
: See also: [[#createLabel|createLabel()]]<br />
<br />
;Parameters<br />
* ''imageLocation:''<br />
: Path to the image.<br />
<br />
{{MudletVersion|4.5}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local path = getMudletHomeDir().."/my-image.png"<br />
<br />
cecho("Showing dimensions of the picture in: "..path.."\n")<br />
<br />
local width, height = getImageSize(path)<br />
<br />
if not width then<br />
-- in case of an problem, we don't get a height back - but the error message<br />
cecho("error: "..height.."\n")<br />
else<br />
cecho(string.format("They are: %sx%s", width, height))<br />
end<br />
</syntaxhighlight><br />
<br />
==getLastLineNumber==<br />
;getLastLineNumber(windowName)<br />
:Returns the latest line's number in the main window or the miniconsole. This could be different from [[Manual:UI_Functions#getLineNumber|getLineNumber()]] if the cursor was moved around.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: name of the window to use. Either use ''main'' for the main window, or the name of the miniconsole.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- get the latest line's # in the buffer<br />
local latestline = getLastLineNumber("main")<br />
</syntaxhighlight><br />
<br />
==getLineCount==<br />
;getLineCount()<br />
:Gets the absolute amount of lines in the current console buffer<br />
<br />
; Parameters<br />
:None<br />
<br />
;Example<br />
''Need example''<br />
<br />
==getLines==<br />
;getLines([windowName,] from_line_number, to_line_number)<br />
: Returns a section of the content of the screen text buffer. Returns a Lua table with the content of the lines on a per line basis. The form value is ''result = {relative_linenumber = line}''.<br />
<br />
:Absolute line numbers are used.<br />
<br />
;Parameters<br />
* ''windowName''<br />
: (optional) name of the miniconsole/userwindow to get lines for, or "main" for the main window (Mudlet 3.17+)<br />
* ''from_line_number:''<br />
: First line number<br />
* ''to_line_number:''<br />
: End line number<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- retrieve & echo the last line:<br />
echo(getLines(getLineNumber()-1, getLineNumber())[1])<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- find out which server and port you are connected to (as per Mudlet settings dialog):<br />
local t = getLines(0, getLineNumber())<br />
<br />
local server, port<br />
<br />
for i = 1, #t do<br />
local s, p = t[i]:match("looking up the IP address of server:(.-):(%d+)")<br />
if s then server, port = s, p break end<br />
end<br />
<br />
display(server)<br />
display(port)<br />
</syntaxhighlight><br />
<br />
==getLineNumber==<br />
;getLineNumber([windowName])<br />
: Returns the absolute line number of the current user cursor (the y position). The cursor by default is on the current line the triggers are processing - which you can move around with [[Manual:Lua_Functions#moveCursor|moveCursor()]] and [[Manual:Lua_Functions#moveCursorEnd|moveCursorEnd()]]. This function can come in handy in combination when using with [[Manual:Lua_Functions#moveCursor|moveCursor()]] and [[Manual:Lua_Functions#getLines|getLines()]].<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the miniconsole to operate on. If you'd like it to work on the main window, don't specify anything.<br />
<br />
{{note}}<br />
The argument is available since Mudlet 3.0.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- use getLines() in conjuction with getLineNumber() to check if the previous line has a certain word<br />
if getLines(getLineNumber()-1, getLineNumber())[1]:find("attacks") then echo("previous line had the word 'attacks' in it!\n") end<br />
<br />
-- check how many lines you've got in your miniconsole after echoing some text.<br />
-- Note the use of moveCursorEnd() to update getLineNumber()'s output<br />
HelloWorld = Geyser.MiniConsole:new({<br />
name="HelloWorld",<br />
x="70%", y="50%",<br />
width="30%", height="50%",<br />
})<br />
<br />
print(getLineNumber("HelloWorld"))<br />
<br />
HelloWorld:echo("hello!\n")<br />
HelloWorld:echo("hello!\n")<br />
HelloWorld:echo("hello!\n")<br />
<br />
-- update the cursors position, as it seems to be necessary to do<br />
moveCursorEnd("HelloWorld")<br />
print(getLineNumber("HelloWorld"))<br />
</syntaxhighlight><br />
<br />
==getMainConsoleWidth==<br />
;getMainConsoleWidth()<br />
: Returns a single number; the width of the main console (game output) in pixels. This also accounts for any borders that have been set.<br />
<br />
: See also: [[#getMainWindowSize|getMainWindowSize()]]<br />
<br />
; Parameters<br />
:None<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Save width of the main console to a variable for future use.<br />
consoleWidth = getMainConsoleWidth()<br />
</syntaxhighlight><br />
<br />
==getMouseEvents==<br />
; events = getMouseEvents()<br />
<br />
:Returns a table of registered mouse events, including any of the additional arguments they may have.<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
;See also: [[Manual:Lua_Functions#addMouseEvent|addMouseEvent()]], [[Manual:Lua_Functions#removeMouseEvent|removeMouseEvent()]]<br />
<br />
;Returns <br />
* Returns a table with mouse event ''uniqueName'' as indexes, containing all the creation arguments as the sub-table members.<br />
<br />
==getMousePosition==<br />
;getMousePosition()<br />
: Returns the coordinates of the mouse's position, relative to the Mudlet window itself.<br />
<br />
; Parameters<br />
:None<br />
<br />
{{MudletVersion|3.1}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Retrieve x and y position of the mouse to determine where to create a new label, then use that position to create a new label<br />
local x, y = getMousePosition()<br />
createLabel("clickGeneratedLabel", x, y, 100, 100, 1)<br />
-- if the label already exists, just move it<br />
moveWindow("clickGeneratedLabel", x, y)<br />
-- and make it easier to notice<br />
setBackgroundColor("clickGeneratedLabel", 255, 204, 0, 200)<br />
</syntaxhighlight><br />
<br />
==getProfileTabNumber==<br />
;getProfileTabNumber()<br />
: Returns the current tab number you're in. If you have just one profile loaded, it'll always return 1 - otherwise it'll be the nth tab that is currently open.<br />
<br />
; Parameters<br />
:None<br />
<br />
{{MudletVersion|4.11}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
print(f"Current playing in tab #{getProfileTabNumber()}.")<br />
</syntaxhighlight><br />
<br />
==getMainWindowSize==<br />
;getMainWindowSize()<br />
: Returns two numbers, the width and height in pixels. This is useful for calculating the window dimensions and placement of custom GUI toolkit items like labels, buttons, mini consoles etc.<br />
: See also: [[#getUserWindowSize|getUserWindowSize()]], [[#setMainWindowSize|setMainWindowSize()]], [[#getMainConsoleWidth|getMainConsoleWidth()]]<br />
<br />
; Parameters<br />
:None<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--this will get the size of your main mudlet window and save them<br />
--into the variables mainHeight and mainWidth<br />
mainWidth, mainHeight = getMainWindowSize()<br />
</syntaxhighlight><br />
<br />
==getRowCount==<br />
;getRowCount([windowName])<br />
: Gets the maximum number of rows that a given window can display at once, taking into consideration factors such as window height, font type, spacing, etc.<br />
<br />
;Parameters:<br />
* ''windowName'':<br />
: (optional) name of the window whose maximum number of rows we want to calculate. By default it operates on the main window.<br />
<br />
{{MudletVersion|3.7}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
print("Maximum of rows on the main window "..getRowCount())<br />
</syntaxhighlight><br />
<br />
==getSelection==<br />
;getSelection([windowName])<br />
: Returns the text currently selected with [[#selectString|selectString()]], [[#selectSection|selectSection()]], or [[#selectCurrentLine|selectCurrentLine()]]. Note that this isn't the text currently selected with the mouse.<br />
: Also returns the start offset and length of the selection as second and third value.<br />
<br />
;Parameters:<br />
* ''windowName'':<br />
: (optional) name of the window to get the selection from. By default it operates on the main window.<br />
<br />
{{MudletVersion|3.16}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectCurrentLine()<br />
print("Current line contains: "..getSelection())<br />
</syntaxhighlight><br />
<br />
;retrieving the selection<br />
<syntaxhighlight lang="lua"><br />
text,offset,len = getSelection()<br />
-- manipulate the selection, e.g. to discover the color of characters other than the first<br />
-- then restore it<br />
selectSection(offset, len)<br />
</syntaxhighlight><br />
<br />
==getTextFormat==<br />
;getTextFormat([windowName])<br />
: Gets the current text format of the currently selected text. May be used with other console windows. The returned values come in a table containing text attribute names and their values. The values given will be booleans for: bold, italics, underline, overline, strikeout, and reverse - followed by color triplet tables for the foreground and background colors.<br />
: See Also: [[Manual:Lua_Functions#setTextFormat|setTextFormat()]]<br />
<br />
;Parameters<br />
* ''windowName''<br />
: (optional) Specify name of selected window. If no name or "main" is given, the format will be gathered from the main console.<br />
<br />
{{MudletVersion|3.20}}<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
-- A suitable test for getTextFormat()<br />
-- (copy it into an alias or a script)<br />
<br />
clearWindow()<br />
<br />
echo("\n")<br />
<br />
local SGR = string.char(27)..'['<br />
feedTriggers("Format attributes: '"..SGR.."1mBold"..SGR.."0m' '"..SGR.."3mItalic"..SGR.."0m' '"..SGR.."4mUnderline"..SGR.."0m' '"..SGR.."5mBlink"..SGR.."0m' '"..SGR.."6mF.Blink"..SGR.."0m' '"..SGR.."7mReverse"..SGR.."0m' '"..SGR.."9mStruckout"..SGR.."0m' '"..SGR.."53mOverline"..SGR.."0m'.\n")<br />
<br />
moveCursor(1,1)<br />
selectSection(1,1)<br />
<br />
local results = getTextFormat()<br />
echo("For first character in test line:\nBold detected: " .. tostring(results["bold"]))<br />
echo("\nItalic detected: " .. tostring(results["italic"]))<br />
echo("\nUnderline detected: " .. tostring(results["underline"]))<br />
echo("\nReverse detected: " .. tostring(results["reverse"]))<br />
echo("\nStrikeout detected: " .. tostring(results["strikeout"]))<br />
echo("\nOverline detected: " .. tostring(results["overline"]))<br />
echo("\nForeground color: (" .. results["foreground"][1] .. ", " .. results["foreground"][2] .. ", " .. results["foreground"][3] .. ")")<br />
echo("\nBackground color: (" .. results["background"][1] .. ", " .. results["background"][2] .. ", " .. results["background"][3] .. ")")<br />
<br />
selectSection(21,1)<br />
echo("\n\nFor individual parts of test text:")<br />
echo("\nBold detected (character 21): " .. tostring(results["bold"]))<br />
<br />
selectSection(28,1)<br />
echo("\nItalic detected (character 28): " .. tostring(results["italic"]))<br />
<br />
selectSection(37,1)<br />
echo("\nUnderline detected (character 37): " .. tostring(results["underline"]))<br />
<br />
selectSection(67,1)<br />
echo("\nReverse detected (character 67): " .. tostring(results["reverse"]))<br />
<br />
selectSection(77,1)<br />
echo("\nStrikeout detected (character 77): " .. tostring(results["strikeout"]))<br />
<br />
selectSection(89,1)<br />
echo("\nOverline detected (character 89): " .. tostring(results["overline"]))<br />
echo("\n")<br />
</syntaxhighlight><br />
<br />
==getUserWindowSize==<br />
;getUserWindowSize(windowName)<br />
: Returns two numbers, the width and height in pixels. This is useful for calculating the given userwindow dimensions and placement of custom GUI toolkit items like labels, buttons, mini consoles etc.<br />
: See also: [[#getMainWindowSize|getMainWindowSize()]]<br />
<br />
; Parameters<br />
* ''windowName''<br />
:the name of the userwindow we will get the dimensions from<br />
<br />
{{MudletVersion|4.6.1}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--this will get the size of your userwindow named "ChatWindow" and save them<br />
--into the variables mainHeight and mainWidth<br />
mainWidth, mainHeight = getUserWindowSize("ChatWindow")<br />
</syntaxhighlight><br />
<br />
<br />
==getWindowWrap==<br />
;getWindowWrap(windowName)<br />
: gets at what position in the line the will start word wrap.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the "main" console or user-created miniconsole which you want to be wrapped differently. If you want to wrap the main window, use windowName "main" or leave empty.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setWindowWrap("main", 10)<br />
display(getWindowWrap("main"))<br />
<br />
-- The following output will result in the main window console:<br />
-- 10<br />
</syntaxhighlight><br />
<br />
;Practical Example<br />
<syntaxhighlight lang="lua"><br />
-- display ======== line with maximum possible width without wrapping<br />
echo(string.rep("=", getWindowWrap("main")))<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.11}}<br />
<br />
==handleWindowResizeEvent==<br />
;handleWindowResizeEvent()<br />
: (''depreciated'') This function is depreciated and should not be used; it's only documented here for historical reference - use the [[Manual:Technical_Manual#sysWindowResizeEvent|sysWindowResizeEvent]] event instead.<br />
<br />
The standard implementation of this function does nothing. However, this function gets called whenever the main window is being manually resized. You can overwrite this function in your own scripts to handle window resize events yourself and e. g. adjust the screen position and size of your mini console windows, labels or other relevant GUI elements in your scripts that depend on the size of the main Window. To override this function you can simply put a function with the same name in one of your scripts thus overwriting the original empty implementation of this.<br />
<br />
; Parameters<br />
:None<br />
<br />
; Example<br />
<syntaxhighlight lang="lua"><br />
function handleWindowResizeEvent()<br />
-- determine the size of your screen<br />
WindowWidth=0;<br />
WindowHeight=0;<br />
WindowWidth, WindowHeight = getMainWindowSize();<br />
<br />
-- move mini console "sys" to the far right side of the screen whenever the screen gets resized<br />
moveWindow("sys",WindowWidth-300,0)<br />
end<br />
</syntaxhighlight><br />
<br />
==hasFocus==<br />
;hasFocus()<br />
: Returns ''true'' or ''false'' depending if Mudlet's main window is currently in focus (ie, the user isn't focused on another window, like a browser). If multiple profiles are loaded, this can also be used to check if a given profile is in focus.<br />
<br />
; Parameters<br />
:None<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
if attacked and not hasFocus() then<br />
runaway()<br />
else<br />
fight()<br />
end<br />
</syntaxhighlight><br />
<br />
==hecho==<br />
;hecho([windowName], text)<br />
: Echoes text that can be easily formatted with colour tags in the hexadecimal format. You can also use italics, bold and underline tags.<br />
: See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#cecho|cecho()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Can either be omitted or "main" for the main window, else specify the miniconsoles name.<br />
* ''text:''<br />
: The text to display, with color changes made within the string using the format |cFRFGFB,BRBGBB or #FRFGFB,BRBGBB where FR is the foreground red value, FG is the foreground green value, FB is the foreground blue value, BR is the background red value, etc., BRBGBB is optional. |r or #r can be used within the string to reset the colors to default. Hexadecimal color codes can be found here: https://www.color-hex.com/<br />
<br />
{{note}}<br />
Transparency for background in hex-format available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
hecho("\n#ffffff White text!")<br />
-- your text in white<br />
hecho("\n#ca0004 Red text! And now reset #rit to the default color")<br />
-- your text in red, then reset to default using #r<br />
hecho("\n#ffffff,ca0004 White text with a red background!")<br />
-- your text in white, against a red background<br />
hecho("\n|c0000ff Blue text, this time using |c instead of #")<br />
-- your text in blue, activated with |c vs #.<br />
hecho("\n#ff0000Red text with #iitalics#/i, |uunderline|/u and #bbold#/b formatting.")<br />
</syntaxhighlight><br />
<br />
==hechoLink==<br />
;hechoLink([windowName], text, command, hint, true)<br />
: Echos a piece of text as a clickable link, at the end of the current selected line - similar to [[Manual:Lua_Functions#hecho|hecho()]]. This version allows you to use colours within your link text.<br />
<br />
: See also: [[#cechoLink|cechoLink()]], [[#dechoLink|dechoLink()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) - allows selection between sending the link to a miniconsole or the ''main'' window.<br />
* ''text:''<br />
: text to display in the echo. Same as a normal [[Manual:Lua_Functions#hecho|hecho()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''true:''<br />
: requires argument for the colouring to work.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
hechoLink("|ca00040black!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- # format also works<br />
hechoLink("#ca00040black!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
hechoLink("#ca00040black!", [[send("hi")]], "This is a tooltip", true)<br />
</syntaxhighlight><br />
<br />
==hechoPopup==<br />
;hechoPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current line, like [[#hecho|hecho()]]. 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.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. ie, <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
hechoPopup("#ff0000activities#r to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"}, true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
hechoPopup("#ff0000activities#r to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"}, true)<br />
</syntaxhighlight><br />
<br />
==hideGauge==<br />
;hideGauge(gaugeName)<br />
: hides the given gauge.<br />
<br />
: See also: [[#showGauge|showGauge()]], [[#createGauge|createGauge()]]<br />
<br />
;Parameters<br />
* ''gaugeName:''<br />
: name of the gauge to show.<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
hideGauge("my gauge")<br />
showGauge("my gauge")<br />
</syntaxhighlight><br />
<br />
==hinsertLink==<br />
;hinsertLink([windowName], text, command, hint, true)<br />
: Echos a piece of text as a clickable link, at the end of the current cursor position - similar to [[#hinsertText|hinsertText()]]. This version allows you to use colours within your link text.<br />
<br />
: See also: [[#insertLink|insertLink()]], [[#dinsertLink|dinsertLink()]]<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: optional parameter, allows selection between sending the link to a miniconsole or the main window.<br />
* ''text:''<br />
: text to display in the echo. Same as a normal [[Manual:Lua_Functions#hecho|hecho()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''true:''<br />
: requires argument for the colouring to work.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- echo a link named 'press me!' that'll send the 'hi' command to the game<br />
hinsertLink("#ff0000press #a52a2a,ffffffme!", function() send("hi") end, "This is a tooltip", true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
hinsertLink("#ff0000press #a52a2a,ffffffme!", [[send("hi")]], "This is a tooltip", true)<br />
</syntaxhighlight><br />
<br />
==hinsertPopup==<br />
;hinsertPopup([windowName], text, {commands}, {hints}, [useCurrentFormatElseDefault])<br />
: Creates text with a left-clickable link, and a right-click menu for more options at the end of the current cursor position, like [[#hinsertText|hinsertText()]]. 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.<br />
<br />
{{MudletVersion|4.1}}<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''text:''<br />
: the text to display<br />
* ''{commands}:''<br />
: a table of lua code strings to do or a functions (since Mudlet 4.11). ie, <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight><br />
* ''useCurrentFormatElseDefault:''<br />
: (optional) a boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
hinsertPopup("#ff0000activities#r to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"}, true)<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
hinsertPopup("#ff0000activities#r to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"}, true)<br />
</syntaxhighlight><br />
<br />
==hreplaceLine==<br />
;hreplaceLine ([window], text)<br />
: Replaces the output line from the game with a colour-tagged string.<br />
{{MudletVersion|4.12}}<br />
See Also: [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:Lua_Functions#hinsertText|hinsertText()]]<br />
;Parameters<br />
* ''window'' (optional):<br />
: the window to copy the text from. Defaults to "main".<br />
* ''text:''<br />
*: The text to display, with hex color values , ie ''#ff00ff''. If you'd like to use a background color, put it after a comma , - ''#,ff99ff''. You can use the ''#r'' tag to reset to the default color. <br />
:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua">hreplaceLine("#ff00ff[ALERT!]: #r"..line)<br />
</syntaxhighlight><br />
<br />
==hreplace==<br />
;hreplace([window, ]text)<br />
: Replaces the output line from the game with a colour-tagged string.<br />
See Also: [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:Lua_Functions#hinsertText|hinsertText()]]<br />
;Parameters<br />
* ''window:''<br />
*: The window to replace the selection in. Optional, defaults to the main window if not provided.<br />
* ''text:''<br />
*: The text to display, as with [[Manual:Lua_Functions#hecho|hecho()]]<br />
:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectCaptureGroup(1)<br />
hreplace("#EE00EE[ALERT!]: #r"..matches[2])<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.5}}<br />
<br />
==hideToolBar==<br />
;hideToolBar(name)<br />
: Hides the toolbar with the given name name and makes it disappear. If all toolbars of a tool bar area (top, left, right) are hidden, the entire tool bar area disappears automatically.<br />
<br />
;Parameters<br />
* ''name:''<br />
: name of the button group to hide<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
hideToolBar("my offensive buttons")<br />
</syntaxhighlight><br />
<br />
==hideWindow==<br />
;hideWindow(name)<br />
: This function hides a '''mini console''', a '''user window''' or a '''label''' with the given name. To show it again, use [[Manual:Lua_Functions#showWindow|showWindow()]].<br />
<br />
: See also: [[#createMiniConsole|createMiniConsole()]], [[#createLabel|createLabel()]], [[#deleteLabel|deleteLabel()]]<br />
<br />
;Parameters<br />
* ''name''<br />
: specifies the label or console you want to hide.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
function miniconsoleTest()<br />
local windowWidth, windowHeight = getMainWindowSize()<br />
<br />
-- create the miniconsole<br />
createMiniConsole("sys", windowWidth-650,0,650,300)<br />
setBackgroundColor("sys",255,69,0,255)<br />
setMiniConsoleFontSize("sys", 8)<br />
-- wrap lines in window "sys" at 40 characters per line - somewhere halfway, as an example<br />
setWindowWrap("sys", 40)<br />
<br />
print("created red window top-right")<br />
<br />
tempTimer(1, function()<br />
hideWindow("sys")<br />
print("hid red window top-right")<br />
end)<br />
<br />
tempTimer(3, function()<br />
showWindow("sys")<br />
print("showed red window top-right")<br />
end)<br />
end<br />
<br />
miniconsoleTest()<br />
</syntaxhighlight><br />
<br />
==insertLink==<br />
;insertLink([windowName], text, command, hint, [useCurrentLinkFormat])<br />
: Inserts a piece of text as a clickable link at the current cursor position - similar to [[Manual:Lua_Functions#insertText|insertText()]].<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) the window to insert the link in - use either "main" or omit for the main window.<br />
* ''text:''<br />
: text to display in the window. Same as a normal [[Manual:Lua_Functions#echo|echo()]].<br />
* ''command:''<br />
: Lua code to do when the link is clicked, as text or a function (since Mudlet 4.11).<br />
* ''hint:''<br />
: text for the tooltip to be displayed when the mouse is over the link.<br />
* ''useCurrentLinkFormat:''<br />
: (optional) true or false. If true, then the link will use the current selection style (colors, underline, etc). If missing or false, it will use the default link style - blue on black underlined text.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- link with the default blue on white colors<br />
insertLink("hey, click me!", function() echo("you clicked me!\n") end, "Click me popup")<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
insertLink("hey, click me!", [[echo("you clicked me!\n")]], "Click me popup")<br />
<br />
-- use current cursor colors by adding true at the end<br />
fg("red")<br />
insertLink("hey, click me!", function() echo("you clicked me!\n") end, "Click me popup", true)<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
==insertPopup==<br />
;insertPopup([windowName], text, {commands}, {hints}, [useCurrentLinkFormat])<br />
: Creates text with a left-clickable link, and a right-click menu for more options exactly where the cursor position is, similar to [[Manual:Lua_Functions#insertText|insertText()]]. The inserted 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.<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to - use either ''main'' or omit for the main window, or the miniconsoles name otherwise.<br />
* ''name:''<br />
: the name of the console to operate on. If not using this in a miniConsole, use "main" as the name.<br />
* ''{lua code}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight>.<br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. ie, <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight>.<br />
* ''useCurrentLinkFormat:''<br />
: (optional) boolean value for using either the current formatting options (colour, underline, italic) or the link default (blue underline).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create some text as a clickable with a popup menu:<br />
insertPopup("activities to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"})<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
insertPopup("activities to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"})<br />
</syntaxhighlight><br />
<br />
==insertText==<br />
;insertText([windowName], text)<br />
: Inserts text at cursor postion in window - unlike [[Manual:Lua_Functions#echo|echo()]], which inserts the text at the end of the last line in the buffer (typically the one being processed by the triggers). You can use [[Manual:Lua_Functions#moveCursor|moveCursor()]] to move the cursor into position first.<br />
<br />
: insertHTML() also does the same thing as insertText, if you ever come across it.<br />
<br />
: See also: [[Manual:Lua_Functions#cinsertText|cinsertText()]]<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) The window to insert the text to.<br />
* ''text:''<br />
: The text you will insert into the current cursor position.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- move the cursor to the end of the previous line and insert some text<br />
<br />
-- move to the previous line<br />
moveCursor(0, getLineNumber()-1)<br />
-- move the end the of the previous line<br />
moveCursor(#getCurrentLine(), getLineNumber())<br />
<br />
fg("dark_slate_gray")<br />
insertText(' <- that looks nice.')<br />
<br />
deselect()<br />
resetFormat()<br />
moveCursorEnd()<br />
</syntaxhighlight><br />
<br />
==ioprint==<br />
;ioprint(text, some more text, ...)<br />
:Prints text to the to the stdout. This is only available if you [http://www.wikihow.com/Run-a-Program-on-Command-Prompt launched Mudlet from cmd.exe] on Windows, [http://www.wikihow.com/Open-Applications-Using-Terminal-on-Mac from the terminal] on Mac, or from the terminal on a Linux OS (launch the terminal program, type ''mudlet'' and press enter).<br />
<br />
Similar to [[Manual:Lua_Functions#echo|echo()]], but does not require a "\n" at the end for a newline and can print several items given to it. It cannot print whole tables. This function works similarly to the print() you will see in guides for Lua.<br />
<br />
This function is useful in working out potential crashing problems with Mudlet due to your scripts - as you will still see whatever it printed when Mudlet crashes.<br />
<br />
;Parameters<br />
* ''text:''<br />
: The information you want to display.<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
ioprint("hi!")<br />
ioprint(1,2,3)<br />
ioprint(myvariable, someothervariable, yetanothervariable)<br />
</syntaxhighlight><br />
<br />
==isAnsiBgColor==<br />
; isAnsiBgColor(bgColorCode)<br />
: This function tests if the first character of '''the current selection''' in the main console has the background color specified by bgColorCode.<br />
<br />
;Parameters<br />
* ''bgColorCode:''<br />
: A color code to test for, possible codes are:<br />
<br />
<syntaxhighlight lang="lua"><br />
0 = default text color<br />
1 = light black<br />
2 = dark black<br />
3 = light red<br />
4 = dark red<br />
5 = light green<br />
6 = dark green<br />
7 = light yellow<br />
8 = dark yellow<br />
9 = light blue<br />
10 = dark blue<br />
11 = light magenta<br />
12 = dark magenta<br />
13 = light cyan<br />
14 = dark cyan<br />
15 = light white<br />
16 = dark white<br />
</syntaxhighlight><br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectString( matches[1], 1 )<br />
if isAnsiBgColor( 5 ) then<br />
bg( "red" );<br />
resetFormat();<br />
echo( "yes, the background of the text is light green" )<br />
else<br />
echo( "no sorry, some other background color" )<br />
end<br />
</syntaxhighlight><br />
<br />
{{note}}<br />
The variable named matches[1] holds the matched trigger pattern - even in substring, exact match, begin of line substring trigger patterns or even color triggers that do not know about the concept of capture groups. Consequently, you can always test if the text that has fired the trigger has a certain color and react accordingly. This function is faster than using getBgColor() and then handling the color comparison in Lua.<br />
<br />
''Also note that the color code numbers are Mudlet specific, though they do represent the colors in the 16 ANSI color-set for the main console they are not in the same order and they additionally have the default background color in the zeroth position.''<br />
<br />
==isAnsiFgColor==<br />
; isAnsiFgColor(fgColorCode)<br />
: This function tests if the first character of '''the current selection''' in the main console has the foreground color specified by fgColorCode.<br />
<br />
;Parameters<br />
* ''fgColorCode:''<br />
: A color code to test for, possible codes are:<br />
<br />
<syntaxhighlight lang="lua"><br />
0 = default text color<br />
1 = light black<br />
2 = dark black<br />
3 = light red<br />
4 = dark red<br />
5 = light green<br />
6 = dark green<br />
7 = light yellow<br />
8 = dark yellow<br />
9 = light blue<br />
10 = dark blue<br />
11 = light magenta<br />
12 = dark magenta<br />
13 = light cyan<br />
14 = dark cyan<br />
15 = light white<br />
16 = dark white<br />
</syntaxhighlight><br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
selectString( matches[1], 1 )<br />
if isAnsiFgColor( 5 ) then<br />
bg( "red" );<br />
resetFormat();<br />
echo( "yes, the text is light green" )<br />
else<br />
echo( "no sorry, some other foreground color" )<br />
end<br />
</syntaxhighlight><br />
<br />
{{note}}<br />
The variable named matches[1] holds the matched trigger pattern - even in substring, exact match, begin of line substring trigger patterns or even color triggers that do not know about the concept of capture groups. Consequently, you can always test if the text that has fired the trigger has a certain color and react accordingly. This function is faster than using getFgColor() and then handling the color comparison in Lua.<br />
<br />
''Also note that the color code numbers are Mudlet specific, though they do represent the colors in the 16 ANSI color-set for the main console they are not in the same order and they additionally have the default foreground color in the zeroth position.''<br />
<br />
==loadWindowLayout==<br />
;loadWindowLayout()<br />
:Resets the layout of userwindows (floating miniconsoles) to the last saved state.<br />
<br />
:See also: [[#saveWindowLayout|saveWindowLayout()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
{{MudletVersion|3.2}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
loadWindowLayout()<br />
</syntaxhighlight><br />
<br />
==lowerWindow==<br />
;lowerWindow(labelName)<br />
:Moves the referenced label/console below all other labels/consoles. For the opposite effect, see: [[#raiseWindow | raiseWindow()]].<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: the name of the label/console you wish to move below the rest.<br />
<br />
{{MudletVersion|3.1}}<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
createLabel("blueLabel", 300, 300, 100, 100, 1) --creates a blue label<br />
setBackgroundColor("blueLabel", 50, 50, 250, 255)<br />
<br />
createLabel("redLabel", 350, 350, 100, 100, 1) --creates a red label which is placed on TOP of the blue label, as the last made label will sit at the top of the rest<br />
setBackgroundColor("redLabel", 250, 50, 50, 255)<br />
<br />
lowerWindow("redLabel") --lowers redLabel, causing blueLabel to be back on top<br />
</syntaxhighlight><br />
<br />
==moveCursor==<br />
;moveCursor([windowName], x, y)<br />
: Moves the user cursor of the window windowName, or the main window, to the absolute point (x,y). This function returns false if such a move is impossible e.g. the coordinates don’t exist. To determine the correct coordinates use [[Manual:Lua_Functions#getLineNumber|getLineNumber()]], [[Manual:Lua_Functions#getColumnNumber|getColumnNumber()]] and [[Manual:Lua_Functions#getLastLineNumber|getLastLineNumber()]]. The trigger engine will always place the user cursor at the beginning of the current line before the script is run. If you omit the windowName argument, the main screen will be used.<br />
<br />
: Returns ''true'' or ''false'' depending on if the cursor was moved to a valid position. Check this before doing further cursor operations - because things like deleteLine() might invalidate this.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) The window you are going to move the cursor in.<br />
* ''x:''<br />
: The horizontal axis in the window - that is, the letter position within the line.<br />
* ''y:''<br />
: The vertical axis in the window - that is, the line number.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- move cursor to the start of the previous line and insert -<(<br />
-- the first 0 means we want the cursor right at the start of the line,<br />
-- and getLineNumber()-1 means we want the cursor on the current line# - 1 which<br />
-- equals to the previous line<br />
moveCursor(0, getLineNumber()-1)<br />
insertText("-<(")<br />
<br />
-- now we move the cursor at the end of the previous line. Because the<br />
-- cursor is on the previous line already, we can use #getCurrentLine()<br />
-- to see how long it is. We also just do getLineNumber() because getLineNumber()<br />
-- returns the current line # the cursor is on<br />
moveCursor(#getCurrentLine(), getLineNumber())<br />
insertText(")>-")<br />
<br />
-- finally, reset it to the end where it was after our shenaningans - other scripts<br />
-- could expect the cursor to be at the end<br />
moveCursorEnd()<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- a more complicated example showing how to work with Mudlet functions<br />
<br />
-- set up the small system message window in the top right corner<br />
-- determine the size of your screen<br />
local WindowWidth, WindowHeight = getMainWindowSize()<br />
<br />
-- define a mini console named "sys" and set its background color<br />
createMiniConsole("sys",WindowWidth-650,0,650,300)<br />
setBackgroundColor("sys",85,55,0,255)<br />
<br />
-- you *must* set the font size, otherwise mini windows will not work properly<br />
setMiniConsoleFontSize("sys", 12)<br />
-- wrap lines in window "sys" at 65 characters per line<br />
setWindowWrap("sys", 60)<br />
-- set default font colors and font style for window "sys"<br />
setTextFormat("sys",0,35,255,50,50,50,0,0,0)<br />
-- clear the window<br />
clearUserWindow("sys")<br />
<br />
moveCursorEnd("sys")<br />
setFgColor("sys", 10,10,0)<br />
setBgColor("sys", 0,0,255)<br />
echo("sys", "test1---line1\n<this line is to be deleted>\n<this line is to be deleted also>\n")<br />
echo("sys", "test1---line2\n")<br />
echo("sys", "test1---line3\n")<br />
setTextFormat("sys",158,0,255,255,0,255,0,0,0);<br />
--setFgColor("sys",255,0,0);<br />
echo("sys", "test1---line4\n")<br />
echo("sys", "test1---line5\n")<br />
moveCursor("sys", 1,1)<br />
<br />
-- deleting lines 2+3<br />
deleteLine("sys")<br />
deleteLine("sys")<br />
<br />
-- inserting a line at pos 5,2<br />
moveCursor("sys", 5,2)<br />
setFgColor("sys", 100,100,0)<br />
setBgColor("sys", 255,100,0)<br />
insertText("sys","############## line inserted at pos 5/2 ##############")<br />
<br />
-- inserting a line at pos 0,0<br />
moveCursor("sys", 0,0)<br />
selectCurrentLine("sys")<br />
setFgColor("sys", 255,155,255)<br />
setBold( "sys", true );<br />
setUnderline( "sys", true )<br />
setItalics( "sys", true )<br />
insertText("sys", "------- line inserted at: 0/0 -----\n")<br />
<br />
setBold( "sys", true )<br />
setUnderline( "sys", false )<br />
setItalics( "sys", false )<br />
setFgColor("sys", 255,100,0)<br />
setBgColor("sys", 155,155,0)<br />
echo("sys", "*** This is the end. ***\n")<br />
</syntaxhighlight><br />
<br />
==moveCursorDown==<br />
;moveCursorDown([windowName,] [lines,] [keepHorizontal])<br />
: Moves the cursor in the given window down a specified number of lines.<br />
: See also: [[#moveCursor|moveCursor()]], [[#moveCursorUp|moveCursorUp()]], [[#moveCursorEnd|moveCursorEnd()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the miniconsole/userwindow, or "main" for the main window.<br />
<br />
* ''lines:''<br />
: (optional) number of lines to move cursor down by, or 1 by default.<br />
<br />
* ''keepHorizontal:''<br />
: (optional) true/false to specify if horizontal position should be retained, or reset to the start of the line otherwise.<br />
<br />
{{MudletVersion|3.17}}<br />
<br />
;Example<br />
'' Need example''<br />
<br />
==moveCursorUp==<br />
;moveCursorUp([windowName,] [lines,] [keepHorizontal])<br />
: Moves the cursor in the given window up a specified number of lines.<br />
: See also: [[#moveCursor|moveCursor()]], [[#moveCursorDown|moveCursorDown()]], [[#moveCursorEnd|moveCursorEnd()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the miniconsole/userwindow, or "main" for the main window.<br />
<br />
* ''lines:''<br />
: (optional) number of lines to move cursor up by, or 1 by default.<br />
<br />
* ''keepHorizontal:''<br />
: (optional) true/false to specify if horizontal position should be retained, or reset to the start of the line otherwise.<br />
<br />
{{MudletVersion|3.17}}<br />
<br />
;Example<br />
'' Need example''<br />
<br />
==moveCursorEnd==<br />
;moveCursorEnd([windowName])<br />
: Moves the cursor to the end of the buffer. "main" is the name of the main window, otherwise use the name of your user window.<br />
: See Also: [[Manual:Lua_Functions#moveCursor|moveCursor()]]<br />
<br />
: Returns true or false<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the miniconsole/userwindow, or "main" for the main window.<br />
<br />
;Example<br />
'' Need example''<br />
<br />
==moveGauge==<br />
;moveGauge(gaugeName, newX, newY)<br />
:Moves a gauge created with createGauge to the new x,y coordinates. Remember the coordinates are relative to the top-left corner of the output window.<br />
<br />
;Parameters<br />
* ''gaugeName:''<br />
: The name of your gauge<br />
* ''newX:''<br />
: The horizontal pixel location<br />
* ''newY:''<br />
: The vertical pixel location<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This would move the health bar gauge to the location 1200, 400<br />
moveGauge("healthBar", 1200, 400)<br />
</syntaxhighlight><br />
<br />
==moveWindow==<br />
;moveWindow(name, x, y)<br />
:This function moves window name to the given x/y coordinate. The main screen cannot be moved. Instead you’ll have to set appropriate border values → preferences to move the main screen e.g. to make room for chat or information mini consoles, or other GUI elements. In the future moveWindow() will set the border values automatically if the name parameter is omitted.<br />
<br />
:See Also: [[#createMiniConsole | createMiniConsole()]], [[#createLabel | createLabel()]], [[#handleWindowResizeEvent | handleWindowResizeEvent()]], [[#resizeWindow | resizeWindow()]], [[#setBorderSizes | setBorderSizes()]], [[#openUserWindow | openUserWindow()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: The name of your window<br />
* ''newX:''<br />
: The horizontal pixel location<br />
* ''newY:''<br />
: The vertical pixel location<br />
<br />
{{note}}<br />
Since Mudlet 3.7 this method can also be used on UserWindow consoles.<br />
<br />
==openUserWindow==<br />
;openUserWindow(windowName, [restoreLayout], [autoDock], [dockingArea])<br />
: Opens a user dockable console window for user output e.g. statistics, chat etc. If a window of such a name already exists, nothing happens. You can move these windows (even to a different screen on a system with a multi-screen display), dock them on any of the four sides of the main application window, make them into notebook tabs or float them.<br />
<br />
: See also: [[#resetUserWindowTitle|resetUserWindowTitle()]], [[#setUserWindowTitle|setUserWindowTitle()]], [[#saveWindowLayout|saveWindowLayout()]], [[#loadWindowLayout|loadWindowLayout()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: name of your window, it must be unique across ALL profiles if more than one is open (for multi-playing).<br />
* ''restoreLayout:'' (available in Mudlet 3.2+)<br />
: (optional) - only relevant, if ''false'' is provided. Then the window won't be restored to its last known position.<br />
* ''autoDock:'' (available in Mudlet 4.7+)<br />
: (optional) - only relevant, if ''false'' is provided. Then the window won't dock automatically at the corners.<br />
* ''dockingArea:'' (available in Mudlet 4.7+)<br />
: (optional) - the area your UserWindow will be docked at. possible docking areas your UserWindow will be created in (f" floating "t" top "b" bottom "r" right and "l" left). Docking area is "right" if not given any value.<br />
<br />
{{note}}<br />
Since Mudlet version 3.2, Mudlet will automatically remember the window's last position.<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
openUserWindow("My floating window")<br />
cecho("My floating window", "<red>hello <blue>bob!")<br />
<br />
-- if you don't want Mudlet to remember its last position:<br />
openUserWindow("My floating window", false)<br />
</syntaxhighlight><br />
<br />
==paste==<br />
;paste(windowName)<br />
: Pastes the previously copied text including all format codes like color, font etc. at the current user cursor position. The [[#copy | copy()]] and [[#paste | paste()]] functions can be used to copy formated text from the main window to a user window without losing colors e. g. for chat windows, map windows etc.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of your window<br />
<br />
==prefix==<br />
;prefix(text, [writingFunction], [foregroundColor], [backgroundColor], [windowName])<br />
:Prefixes text at the beginning of the current line when used in a trigger.<br />
<br />
;Parameters<br />
* ''text:''<br />
: the information you want to prefix<br />
* "writingFunction:"<br />
: optional parameter, allows the selection of different functions to be used to write the text, valid options are: echo, cecho, decho, and hecho.<br />
* "foregroundColor:"<br />
: optional parameter, allows a foreground color to be specified if using the echo function using a color name, as with the fg() function<br />
* "backgroundColor:"<br />
: optional parameter, allows a background color to be specified if using the echo function using a color name, as with the bg() function<br />
* "windowName:"<br />
: optional parameter, allows the selection a miniconsole or the main window for the line that will be prefixed<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
-- Prefix the hours, minutes and seconds onto our prompt even though Mudlet has a button for that<br />
prefix(os.date("%H:%M:%S "))<br />
-- Prefix the time in red into a miniconsole named "my_console"<br />
prefix(os.date("<red>%H:%M:%S<reset>", cecho, nil, nil, "my_console"))<br />
</syntaxhighlight><br />
<br />
: See also: [[#suffix | suffix()]]<br />
<br />
==print==<br />
;print(text, some more text, ...)<br />
:Prints text to the main window. Similar to [[Manual:Lua_Functions#echo|echo()]], but does not require a "\n" at the end for a newline and can print several items given to it. It cannot print whole tables - use [[Manual:Lua_Functions#display|display()]] for those. This function works similarly to the print() you will see in guides for Lua.<br />
<br />
;Parameters<br />
* ''text:''<br />
: The information you want to display.<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
print("hi!")<br />
print(1,2,3)<br />
print(myvariable, someothervariable, yetanothervariable)<br />
</syntaxhighlight><br />
<br />
==raiseWindow==<br />
;raiseWindow(labelName)<br />
:Raises the referenced label/console above all over labels/consoles. For the opposite effect, see: [[#lowerWindow | lowerWindow()]].<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: the name of the label/console you wish to bring to the top of the rest.<br />
<br />
{{MudletVersion|3.1}}<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
createLabel("blueLabel", 300, 300, 100, 100, 1) --creates a blue label<br />
setBackgroundColor("blueLabel", 50, 50, 250, 255)<br />
<br />
createLabel("redLabel", 350, 350, 100, 100, 1) --creates a red label which is placed on TOP of the bluewindow, as the last made label will sit at the top of the rest<br />
setBackgroundColor("redLabel", 250, 50, 50, 255)<br />
<br />
raiseWindow("blueLabel") --raises blueLabel back at the top, above redLabel<br />
</syntaxhighlight><br />
<br />
==removeCommandLineMenuEvent==<br />
;removeCommandLineMenuEvent([window,] label)<br />
<br />
:Removes an existing command line menu event.<br />
<br />
;Parameters<br />
* ''window:''<br />
: Window that item is associated with. Optional, defaults to "main" (main window console).<br />
* ''label:''<br />
: Label under which element is registered<br />
<br />
;Returns <br />
* Returns ''True'' If the mouse event was removed successfully.<br />
<br />
==removeMouseEvent==<br />
; removeMouseEvent(uniqueName)<br />
<br />
:Removes an existing mouse event. Returns ''True'' If the event exists and was removed successfully, throws a warning if the event doesn't exist.<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
;See also: [[Manual:Lua_Functions#getMouseEvents|getMouseEvents()]], [[Manual:Lua_Functions#addMouseEvent|addMouseEvent()]]<br />
<br />
;Parameters<br />
* ''uniqueName:''<br />
: A unique identifier that the mouse event was registered under.<br />
<br />
;Returns <br />
* Returns ''True'' If the mouse event was removed successfully.<br />
<br />
==replace==<br />
;replace([windowName], with, [keepcolor])<br />
:Replaces the currently selected text with the new text. To select text, use [[#selectString | selectString()]], [[#selectSection | selectSection()]] or a similar function.<br />
<br />
{{note}}<br />
If you’d like to delete/gag the whole line, use [[#deleteLine | deleteLine()]] instead.<br />
<br />
{{note}}<br />
when used outside of a trigger context (for example, in a timer instead of a trigger), replace() won't trigger the screen to refresh. Instead, use ''replace("")'' and ''insertText("new text")'' as [[#insertText | insertText()]] does.<br />
<br />
See also: [[#creplace|creplace]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of window (a miniconsole)<br />
* ''with:''<br />
: the new text to display.<br />
* ''keepcolor:''<br />
: (optional) argument, setting this to ''true'' will keep the existing colors (since Mudlet 3.0+)<br />
<br />
; Example:<br />
<syntaxhighlight lang="lua"><br />
-- replace word "troll" with "cute trolly"<br />
selectString("troll",1)<br />
replace("cute trolly")<br />
<br />
-- replace the whole line<br />
selectCurrentLine()<br />
replace("Out with the old, in with the new!")<br />
</syntaxhighlight><br />
<br />
==replaceAll==<br />
;replaceAll(what, with, [keepcolor])<br />
: Replaces all occurrences of ''what'' in the current line with ''with''.<br />
<br />
;Parameters<br />
* ''what:''<br />
: the text to replace<br />
{{note}}<br />
This accepts [https://www.lua.org/pil/20.2.html Lua patterns]<br />
* ''with:''<br />
: the new text to have in place<br />
* ''keepcolor:''<br />
: setting this to true will keep the existing colors.<br />
{{note}} keepcolor is available in Mudlet 4.10+<br />
<br />
;Examples:<br />
<syntaxhighlight lang="lua"><br />
-- replace all occurrences of the word "south" in the line with "north"<br />
replaceAll("south", "north")<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
-- replace all occurrences of the text that the variable "target" has<br />
replaceAll(target, "The Bad Guy")<br />
</syntaxhighlight><br />
<br />
==replaceLine==<br />
;replaceLine ([window], text)<br />
: Replaces the output line from the game with your own text.<br />
See Also: [[Manual:Lua_Functions#echo|echo()]], [[Manual:Lua_Functions#insertText|insertText()]]<br />
<br />
;Parameters<br />
* ''window'' (optional):<br />
: the window to copy the text from. Defaults to "main".<br />
* ''text:''<br />
*: The text to display<br />
<br />
;Example<br />
<syntaxhighlight lang="lua">replaceLine("[ALERT!]: "..line)<br />
</syntaxhighlight><br />
<br />
==replaceWildcard==<br />
;replaceWildcard(which, replacement, [keepcolor])<br />
: Replaces the given wildcard (as a number) with the given text. Equivalent to doing:<br />
<br />
<syntaxhighlight lang="lua"><br />
selectString(matches[2], 1)<br />
replace("text")<br />
</syntaxhighlight><br />
<br />
;Parameters<br />
* ''which:''<br />
: Wildcard to replace.<br />
* ''replacement:''<br />
: Text to replace the wildcard with.<br />
* ''keepcolor:''<br />
: setting this to true will keep the existing colors<br />
{{note}} keepcolor available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
replaceWildcard(2, "hello") -- on a perl regex trigger of ^You wave (goodbye)\.$, it will make it seem like you waved hello<br />
</syntaxhighlight><br />
<br />
==resetCmdLineAction==<br />
;resetCmdLineAction(commandLineName)<br />
: Resets the action on the command line so the it behaves like the main command line again.<br />
;Parameters<br />
<br />
* ''commandLineName''<br />
: The name of the command line the action will be resetet.<br />
: See also: [[#setCmdLineAction | setCmdLineAction()]]<br />
{{MudletVersion|4.10}}<br />
<br />
==resetBackgroundImage==<br />
;resetBackgroundImage([windowName])<br />
: Resets the console background-image<br />
;Parameters<br />
<br />
* ''windowName''<br />
: (optional) name of the console the image will be reset<br />
: See also: [[#setBackgroundImage | setBackgroundImage()]]<br />
{{MudletVersion|4.10}}<br />
<br />
==resetFormat==<br />
;resetFormat()<br />
: Resets the colour/bold/italics formatting. Always use this function when done adjusting formatting, so make sure what you've set doesn't 'bleed' onto other triggers/aliases.<br />
<br />
; Parameters<br />
:None<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- select and set the 'Tommy' to red in the line<br />
if selectString("Tommy", 1) ~= -1 then fg("red") end<br />
<br />
-- now reset the formatting, so our echo isn't red<br />
resetFormat()<br />
echo(" Hi Tommy!")<br />
<br />
-- another example: just highlighting some words<br />
for _, word in ipairs{"he", "she", "her", "their"} do<br />
if selectString(word, 1) ~= -1 then<br />
bg("blue")<br />
end<br />
end<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
==resetLabelCursor==<br />
;resetLabelCursor(labelName)<br />
: Resets your mouse cursor to the default one.<br />
<br />
: See also: [[#setLabelCursor|setLabelCursor()]], [[#setLabelCustomCursor|setLabelCustomCursor()]]<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
;Parameters<br />
* ''labelName'': label for which to reset the cursor for.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
resetLabelCursor("myLabel")<br />
-- This will reset the mouse cursor over myLabel to the default one<br />
</syntaxhighlight><br />
<br />
==resetLabelToolTip==<br />
;resetLabelToolTip(labelName)<br />
: Resets the tooltip on the given label.<br />
{{MudletVersion|4.6.1}}<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label the tooltip will be reseted.<br />
: See also: [[#setLabelToolTip | setLabelToolTip()]]<br />
<br />
==resetMapWindowTitle==<br />
;resetMapWindowTitle()<br />
: resets the title of the popped out map window to default.<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
: See also: [[#setMapWindowTitle|setMapWindowTitle()]]<br />
<br />
==resetUserWindowTitle==<br />
;resetUserWindowTitle(windowName)<br />
: resets the title of the UserWindow windowName<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the userwindow for which the title will be resetet<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
: See also: [[#setUserWindowTitle|setUserWindowTitle()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
==resizeWindow==<br />
;resizeWindow(windowName, width, height)<br />
: Resizes a mini console, label, or floating User Windows.<br />
:See also: [[#createMiniConsole | createMiniConsole()]], [[#createLabel | createLabel()]], [[#handleWindowResizeEvent | handleWindowResizeEvent()]], [[#resizeWindow | resizeWindow()]], [[#setBorderSizes | setBorderSizes()]], [[#openUserWindow | openUserWindow()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name of your window<br />
* ''width:''<br />
: The new width you want<br />
* ''height:''<br />
: The new height you want<br />
<br />
{{note}}<br />
Since Mudlet 3.7 this method can also be used on User Window consoles if they are floating.<br />
<br />
==saveWindowLayout==<br />
;saveWindowLayout()<br />
:Saves the layout of userwindows (floating miniconsoles), in case you'd like to load them again later.<br />
<br />
:See also: [[#loadWindowLayout|loadWindowLayout()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
{{MudletVersion|3.2}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
saveWindowLayout()<br />
</syntaxhighlight><br />
<br />
==selectCaptureGroup==<br />
;selectCaptureGroup(groupNumber)<br />
: Selects the content of the capture group number in your Perl regular expression (from matches[]). Also works with named capture group. It does not work with multimatches.<br />
<br />
:See also: [[#selectCurrentLine| selectCurrentLine()]]<br />
<br />
;Parameters<br />
* ''groupNumberOrName:''<br />
: number of the capture group you want to select, or the name of the capture group as a string<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--First, set a Perl Reqular expression e.g. "you have (\d+) Euro".<br />
--If you want to color the amount of money you have green you do:<br />
<br />
selectCaptureGroup(1)<br />
setFgColor(0,255,0)<br />
<br />
-- Or perhaps instead if you were to use "you have (?<euro>\d+) Euro"<br />
selectCaptureGroup("euro")<br />
fg("green")<br />
</syntaxhighlight><br />
<br />
==selectCmdLineText==<br />
;selectCmdLineText([commandLine])<br />
: Selects the text in your command line. You can specify which one, if you got many.<br />
<br />
:See also: [[#createCommandLine| createCommandLine()]]<br />
<br />
{{MudletVersion|4.13}}<br />
<br />
;Parameters<br />
* ''commandLine:''<br />
: (optional) name of the command line you want to have selected<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- First, create an extra commandline with the following lua script:<br />
inputContainer = inputContainer or Adjustable.Container:new({<br />
x = 0, y = "-4c",<br />
name = "InputContainer", padding = 2,<br />
width = "100%", height = "4c",<br />
autoLoad = false<br />
})<br />
extraCmdLine = extraCmdLine or Geyser.CommandLine:new({<br />
name = "extraCmdLine",<br />
x = 0, y = 0, width = "100%", height = "100%"<br />
}, inputContainer)<br />
inputContainer:attachToBorder("bottom")<br />
<br />
-- Now you can send the following lua code with your main command line.<br />
-- It will give 2 seconds time to click around, unselect its text, etc. before selecting its text for you:<br />
lua tempTimer(2, function() selectCmdLineText() end)<br />
<br />
-- This will instead select the text in the command line named extraCmdLine:<br />
lua selectCmdLineText('extraCmdLine')<br />
<br />
-- Same as before, but using the Geyser.CommandLine function instead:<br />
lua extraCmdLine:selectText() <br />
</syntaxhighlight><br />
<br />
==selectCurrentLine==<br />
; selectCurrentLine([windowName])<br />
: Selects the content of the current line that the cursor at. By default, the cursor is at the start of the current line that the triggers are processing, but you can move it with the moveCursor() function.<br />
<br />
{{note}}<br />
This selects the whole line, including the linebreak - so it has a subtle difference from the slightly slower ''selectString(line, 1)'' selection method.<br />
: See also: [[Manual:Lua_Functions#selectString|selectString()]], [[#selectCurrentLine| selectCurrentLine()]], [[#getSelection| getSelection()]], [[Manual:Lua_Functions#getCurrentLine|getCurrentLine()]]<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: (optional) name of the window in which to select text.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- color the whole line green!<br />
selectCurrentLine()<br />
fg("green")<br />
deselect()<br />
resetFormat()<br />
<br />
-- to select the previous line, you can do this:<br />
moveCursor(0, getLineNumber()-1)<br />
selectCurrentLine()<br />
<br />
-- to select two lines back, this:<br />
moveCursor(0, getLineNumber()-2)<br />
selectCurrentLine()<br />
<br />
</syntaxhighlight><br />
<br />
==selectSection==<br />
;selectSection( [windowName], fromPosition, length )<br />
: Selects the specified parts of the line starting ''from'' the left and extending to the right for however ''how long''. The line starts from 0.<br />
: Returns true if the selection was successful, and false if the line wasn't actually long enough or the selection couldn't be done in general.<br />
<br />
:See also:[[#selectString| selectString()]], [[#selectCurrentLine| selectCurrentLine()]], [[#getSelection| getSelection()]]<br />
<br />
;Parameters<br />
* "windowName:"<br />
: (optional) name of the window in which to select text. By default the main window, if no windowName is given.<br />
: Will not work if "main" is given as the windowName to try to select from the main window.<br />
* ''fromPosition:''<br />
: number to specify at which position in the line to begin selecting<br />
* ''length:''<br />
: number to specify the amount of characters you want to select<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- select and colour the first character in the line red<br />
if selectSection(0,1) then fg("red") end<br />
<br />
-- select and colour the second character green (start selecting from the first character, and select 1 character)<br />
if selectSection(1,1) then fg("green") end<br />
<br />
-- select and colour three character after the first two grey (start selecting from the 2nd character for 3 characters long)<br />
if selectSection(2,3) then fg("grey") end<br />
</syntaxhighlight><br />
<br />
==selectString==<br />
;selectString([windowName], text, number_of_match)<br />
: Selects a substring from the line where the user cursor is currently positioned - allowing you to edit selected text (apply colour, make it be a link, copy to other windows or other things).<br />
<br />
{{note}}<br />
You can move the user cursor with [[#moveCursor | moveCursor()]]. When a new line arrives from the game, the user cursor is positioned at the beginning of the line. However, if one of your trigger scripts moves the cursor around you need to take care of the cursor position yourself and make sure that the cursor is in the correct line if you want to call one of the select functions. To deselect text, see [[#deselect | deselect()]].<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the window in which to select text. By default the main window, if no windowName or an empty string is given.<br />
* ''text:''<br />
: The text to select. It is matched as a substring match (so the text anywhere within the line will get selected).<br />
* ''number_of_match:''<br />
: The occurrence of text on the line that you'd like to select. For example, if the line was "Bob and Bob", 1 would select the first Bob, and 2 would select the second Bob.<br />
<br />
Returns position in line or -1 on error (text not found in line)<br />
<br />
{{note}}<br />
To prevent working on random text if your selection didn't actually select anything, check the -1 return code before doing changes:<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
if selectString("big monster", 1) > -1 then fg("red") end<br />
</syntaxhighlight><br />
<br />
==setAppStyleSheet==<br />
;setAppStyleSheet(stylesheet [, tag])<br />
: Sets a stylesheet for the entire Mudlet application and every open profile. Because it affects other profiles that might not be related to yours, it's better to use [[#setProfileStyleSheet|setProfileStyleSheet()]] instead of this function.<br />
<br />
: Raises the sysAppStyleSheetChange event which comes with two arguments in addition to the event name. The first is the optional tag which was passed into the function, or "" if nothing was given. The second is the profile which made the stylesheet changes.<br />
<br />
: See also: [[#setProfileStyleSheet|setProfileStyleSheet()]]<br />
<br />
;Parameters<br />
<br />
* ''stylesheet:''<br />
: The entire stylesheet you'd like to use.<br />
<br />
* ''tag:'' (available in Mudlet 3.19+)<br />
: (optional) string tag or identifier that will be passed as a second argument in the ''sysAppStyleSheetChange'' event<br />
<br />
;References<br />
: See [http://qt-project.org/doc/qt-5/stylesheet-reference.html Qt Style Sheets Reference] for the list of widgets you can style and CSS properties you can apply on them.<br />
: See also [https://github.com/vadi2/QDarkStyleSheet/blob/master/qdarkstyle/style.qss QDarkStyleSheet], a rather extensive stylesheet that shows you all the different configuration options you could apply, available as an [http://forums.mudlet.org/viewtopic.php?f=6&t=17624 mpackage here].<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- credit to Akaya @ http://forums.mudlet.org/viewtopic.php?f=5&t=4610&start=10#p21770<br />
local background_color = "#26192f"<br />
local border_color = "#b8731b"<br />
<br />
setAppStyleSheet([[<br />
QMainWindow {<br />
background: ]]..background_color..[[;<br />
}<br />
QToolBar {<br />
background: ]]..background_color..[[;<br />
}<br />
QToolButton {<br />
background: ]]..background_color..[[;<br />
border-style: solid;<br />
border-width: 2px;<br />
border-color: ]]..border_color..[[;<br />
border-radius: 5px;<br />
font-family: BigNoodleTitling;<br />
color: white;<br />
margin: 2px;<br />
font-size: 12pt;<br />
}<br />
QToolButton:hover { background-color: grey;}<br />
QToolButton:focus { background-color: grey;}<br />
]])<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.0}}<br />
<br />
{{note}} Enhanced in Mudlet version 3.19.0 to generate an event that profiles/packages can utilise to redraw any parts of the UI that they themselves had previously styled so their effects can be re-applied to the new application style.<br />
<br />
It is anticipated that the Mudlet application itself will make further use of application styling effects and two strings are provisionally planned for the second parameter in the ''sysAppStyleSheetChange'' event: "''mudlet-theme-dark''" and "''mudlet-theme-light''"; it will also set the third parameter to "''system''".<br />
<br />
==setBackgroundColor==<br />
;setBackgroundColor([windowName], r, g, b, [transparency])<br />
: Sets the background for the given label, miniconsole, or userwindow. Colors are from 0 to 255 (0 being black), and transparency is from 0 to 255 (0 being completely transparent).<br />
<br />
;Parameters<br />
<br />
* ''windowName:''<br />
: (optional) name of the label/miniconsole/userwindow to change the background color on, or "main" for the main window.<br />
* ''r:''<br />
: Amount of red to use, from 0 (none) to 255 (full).<br />
* ''g:''<br />
: Amount of green to use, from 0 (none) to 255 (full).<br />
* ''b:''<br />
: Amount of red to use, from 0 (none) to 255 (full).<br />
* ''transparency:''<br />
: (optional) amount of transparency to use, from 0 (fully transparent) to 255 (fully opaque). Defaults to 255 if omitted.<br />
<br />
{{note}}<br />
Transparency also available for main/miniconsoles in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- make a red label that's somewhat transparent<br />
setBackgroundColor("some label",255,0,0,200)<br />
</syntaxhighlight><br />
<br />
==setBackgroundImage==<br />
;setBackgroundImage(labelName, imageLocation)<br />
;setBackgroundImage([windowname], imageLocation, [mode])<br />
: Loads an image file (png) as a background image for a label or console. This can be used to display clickable buttons in combination with [[Manual:Lua_Functions#setLabelClickCallback|setLabelClickCallback()]] and such.<br />
<br />
{{note}}<br />
You can also load images on labels via [[Manual:Lua_Functions#setLabelStyleSheet|setLabelStyleSheet()]].<br />
<br />
;Parameters (label)<br />
<br />
* ''labelName:''<br />
: The name of the label to change it's background color.<br />
* ''imageLocation:''<br />
: The full path to the image location. It's best to use [[ ]] instead of "" for it - because for Windows paths, backslashes need to be escaped.<br />
<br />
;Parameters (consoles)<br />
<br />
* ''windowName:''<br />
: (optional) name of the miniconsole/userwindow to change the background image on, or "main" for the main window.<br />
* ''imageLocation:''<br />
: The full path to the image location. It's best to use [[ ]] instead of "" for it - because for Windows paths, backslashes need to be escaped.<br />
* ''mode:''<br />
: (optional) allows different modes for drawing the background image. Possible modes areː <br />
<br />
** border - the background image is stretched (1)<br />
** center - the background image is in the center (2), <br />
** tile - the background image is 'tiled' (3)<br />
** style - choose your own background image stylesheet, see example below (4)<br />
<br />
: See also: [[#resetBackgroundImage | resetBackgroundImage()]]<br />
<br />
;Example (label)<br />
<syntaxhighlight lang="lua"><br />
-- give the top border a nice look<br />
setBackgroundImage("top bar", [[/home/vadi/Games/Mudlet/games/top_bar.png]])<br />
</syntaxhighlight><br />
<br />
;Example (main/miniconsole)<br />
<syntaxhighlight lang="lua"><br />
-- give the main window a background image<br />
setBackgroundImage("main", [[:/Mudlet_splashscreen_development.png]], "center")<br />
<br />
-- or use your own for the main window:<br />
setBackgroundImage("main", [[C:\Documents and Settings\bub\Desktop\mypicture.png]], "center")<br />
<br />
-- give my_miniconsole a nice background image and put it in the center<br />
setBackgroundImage("my_miniconsole", [[:/Mudlet_splashscreen_development.png]], "center")<br />
<br />
-- give my_miniconsole a nice background image with own stylesheet option<br />
setBackgroundImage("my_miniconsole", [[background-image: url(:/Mudlet_splashscreen_development.png); background-repeat: no-repeat; background-position: right;]], "style")<br />
</syntaxhighlight><br />
{{note}} setBackgroundImage for main/miniconsoles and userwindows available in Mudlet 4.10+<br />
<br />
==setBgColor==<br />
;setBgColor([windowName], r, g, b, [transparency])<br />
:Sets the current text background color in the main window unless windowName parameter given. If you have selected text prior to this call, the selection will be highlighted otherwise the current text background color will be changed. If you set a foreground or background color, the color will be used until you call resetFormat() on all further print commands.<br />
<br />
:If you'd like to change the background color of a window, see [[#setBackgroundColor|setBackgroundColor()]].<br />
<br />
: ''See also:'' [[#cecho|cecho()]], [[#setBackgroundColor|setBackgroundColor()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) either be none or "main" for the main console, or a miniconsole / userwindow name.<br />
* ''r:''<br />
: The red component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''g:''<br />
: The green component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''b:''<br />
: The blue component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''transparency:''<br />
: Amount of transparency to use, from 0 (fully transparent) to 255 (fully opaque). Optional, if not used color is fully opaque<br />
<br />
<br />
<br />
{{note}}<br />
Transparency parameter available in Mudlet 4.10+<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
--highlights the first occurrence of the string "Tom" in the current line with a red background color.<br />
selectString( "Tom", 1 )<br />
setBgColor( 255,0,0 )<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
--prints "Hello" on red background and "You" on blue.<br />
setBgColor(255,0,0)<br />
echo("Hello")<br />
setBgColor(0,0,255)<br />
echo(" You!")<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
==setBold==<br />
;setBold(windowName, boolean)<br />
: Sets the current text font to bold (true) or non-bold (false) mode. If the windowName parameters omitted, the main screen will be used. If you've got text currently selected in the Mudlet buffer, then the selection will be bolded. Any text you add after with [[Manual:Lua_Functions#echo|echo()]] or [[Manual:Lua_Functions#insertText|insertText()]] will be bolded until you use [[Manual:Lua_Functions#resetFormat|resetFormat()]].<br />
<br />
* ''windowName:''<br />
: Optional parameter set the current text background color in windowname given.<br />
<br />
* ''boolean:''<br />
: A <code>true</code> or <code>false</code> that enables or disables bolding of text<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- enable bold formatting<br />
setBold(true)<br />
-- the following echo will be bolded<br />
echo("hi")<br />
-- turns off bolding, italics, underlines and colouring. It's good practice to clean up after you're done with the formatting, so other your formatting doesn't "bleed" into other echoes.<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
==setBorderBottom==<br />
;setBorderBottom(size)<br />
: Sets the size of the bottom border of the main window in pixels. A border means that the game text won't go on it, so this gives you room to place your graphical elements there.<br />
: See Also: [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#setBorderColor|setBorderColor()]], [[Manual:Lua_Functions#getBorderBottom|getBorderBottom()]]<br />
<br />
;Parameters<br />
* ''size:''<br />
: Height of the border in pixels - with 0 indicating no border.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderBottom(150)<br />
</syntaxhighlight><br />
<br />
==setBorderColor==<br />
;setBorderColor(red, green, blue)<br />
: Sets the color of the main windows border that you can create either with lua commands, or via the main window settings.<br />
: See Also: [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]]<br />
<br />
;Parameters<br />
* ''red:''<br />
: Amount of red color to use, from 0 to 255.<br />
* ''green:''<br />
: Amount of green color to use, from 0 to 255.<br />
* ''blue:''<br />
: Amount of blue color to use, from 0 to 255.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- set the border to be completely blue<br />
setBorderColor(0, 0, 255)<br />
<br />
-- or red, using a name<br />
setBorderColor( unpack(color_table.red) )<br />
</syntaxhighlight><br />
<br />
==setBorderLeft==<br />
;setBorderLeft(size)<br />
: Sets the size of the left border of the main window in pixels. A border means that the game text won't go on it, so this gives you room to place your graphical elements there.<br />
: See Also: [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#setBorderColor|setBorderColor()]], [[Manual:Lua_Functions#getBorderLeft|getBorderLeft()]]<br />
<br />
;Parameters<br />
* ''size:''<br />
: Width of the border in pixels - with 0 indicating no border.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderLeft(5)<br />
</syntaxhighlight><br />
<br />
==setBorderRight==<br />
;setBorderRight(size)<br />
: Sets the size of the right border of the main window in pixels. A border means that the game text won't go on it, so this gives you room to place your graphical elements there.<br />
: See Also: [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#setBorderColor|setBorderColor()]], [[Manual:Lua_Functions#getBorderRight|getBorderRight()]]<br />
<br />
;Parameters<br />
* ''size:''<br />
: Width of the border in pixels - with 0 indicating no border.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderRight(50)<br />
</syntaxhighlight><br />
<br />
==setBorderSizes==<br />
;setBorderSizes(top, right, bottom, left)<br />
: Sets the size of all borders of the main window in pixels. A border means that the game text won't go on it, so this gives you room to place your graphical elements there.<br />
: The exact result of this function depends on how many numbers you give to it as arguments.<br />
: See also: [[Manual:Lua_Functions#getBorderSizes|getBorderSizes()]], [[Manual:Lua_Functions#setBorderTop|setBorderTop()]], [[Manual:Lua_Functions#setBorderRight|setBorderRight()]], [[Manual:Lua_Functions#setBorderBottom|setBorderBottom()]], [[Manual:Lua_Functions#setBorderLeft|setBorderLeft()]], [[Manual:Lua_Functions#setBorderColor|setBorderColor()]]<br />
<br />
: {{MudletVersion|4.0}}<br />
<br />
;Arguments<br />
* '''setBorderSizes(top, right, bottom, left)'''<br />
: ''4 arguments:'' All borders will be set to their new given size.<br />
* '''setBorderSizes(top, width, bottom)''' <br />
: ''3 arguments:'' Top and bottom borders will be set to their new given size, and right and left will gain the same width. <br />
* '''setBorderSizes(height, width)'''<br />
: ''2 arguments:'' Top and bottom borders will gain the same height, and right and left borders gain the same width. <br />
* '''setBorderSizes(size)'''<br />
: ''1 argument:'' All borders will be set to the same size.<br />
* '''setBorderSizes()'''<br />
: ''0 arguments:'' All borders will be hidden or set to size of 0 = no border.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderSizes(100, 50, 150, 0) <br />
-- big border at the top, bigger at the bottom, small at the right, none at the left<br />
<br />
setBorderSizes(100, 50, 150) <br />
-- big border at the top, bigger at the bottom, small at the right and the left<br />
<br />
setBorderSizes(100, 50) <br />
-- big border at the top and the bottom, small at the right and the left<br />
<br />
setBorderSizes(100) <br />
-- big borders at all four sides<br />
<br />
setBorderSizes() <br />
-- no borders at all four sides<br />
</syntaxhighlight><br />
<br />
==setBorderTop==<br />
;setBorderTop(size)<br />
: Sets the size of the top border of the main window in pixels. A border means that the game text won't go on it, so this gives you room to place your graphical elements there.<br />
: See Also: [[Manual:Lua_Functions#setBorderSizes|setBorderSizes()]], [[Manual:Lua_Functions#setBorderColor|setBorderColor()]], [[Manual:Lua_Functions#getBorderTop|getBorderTop()]]<br />
<br />
;Parameters<br />
* ''size:''<br />
: Height of the border in pixels - with 0 indicating no border.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setBorderTop(100)<br />
</syntaxhighlight><br />
<br />
==setFgColor==<br />
;setFgColor([windowName], red, green, blue)<br />
:Sets the current text foreground color in the main window unless windowName parameter given.<br />
<br />
* ''windowName:''<br />
: (optional) either be none or "main" for the main console, or a miniconsole / userwindow name.<br />
* ''red:''<br />
: The red component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''green:''<br />
: The green component of the gauge color. Passed as an integer number from 0 to 255<br />
* ''blue:''<br />
: The blue component of the gauge color. Passed as an integer number from 0 to 255<br />
<br />
: See also: [[#setBgColor | setBgColor()]], [[#setHexFgColor | setHexFgColor()]], [[#setHexBgColor | setHexBgColor()]], [[#resetFormat | resetFormat()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--highlights the first occurrence of the string "Tom" in the current line with a red foreground color.<br />
selectString( "Tom", 1 )<br />
setFgColor( 255, 0, 0 )<br />
</syntaxhighlight><br />
<br />
==setButtonStyleSheet==<br />
;setButtonStyleSheet(button, markup)<br />
: Applies Qt style formatting to a button via a special markup language.<br />
<br />
; Parameters<br />
* ''button:''<br />
: The name of the button to be formatted.<br />
* ''markup:''<br />
: The string instructions, as specified by the Qt Style Sheet reference.<br />
: Note: You can instead use QWidget { markup }. QWidget will reference 'button', allowing the use of pseudostates like QWidget:hover and QWidget:selected<br />
<br />
;References<br />
: http://qt-project.org/doc/qt-5/stylesheet-reference.html<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setButtonStyleSheet("my test button", [[<br />
QWidget {<br />
background-color: #999999;<br />
border: 3px #777777;<br />
}<br />
QWidget:hover {<br />
background-color: #bbbbbb;<br />
}<br />
QWidget:checked {<br />
background-color: #77bb77;<br />
border: 3px #559955;<br />
}<br />
QWidget:hover:checked {<br />
background-color: #99dd99;<br />
} ]])</syntaxhighlight><br />
<br />
==setClipboardText==<br />
;setClipboardText(textContent)<br />
: Sets the value of the computer's clipboard to the string data provided.<br />
: See also: [[#getClipboardText | getClipboardText()]]<br />
<br />
; Parameters<br />
* ''textContent:''<br />
: The text to be put into the clipboard.<br />
<br />
: {{note}} Note: Available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setClipboardText("New Clipboard Contents")<br />
echo("Clipboard: " .. getClipboardText()) -- should echo "Clipboard: New Clipboard Contents"<br />
</syntaxhighlight><br />
<br />
==setCmdLineAction==<br />
;setCmdLineAction(commandLineName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called if the user sends text to the command line. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the command line action. Additionally, this function passes the command line input text as the final argument.<br />
{{note}} If no action is set the command line behaves like the main command line and sends commands directly to the game or alias engine.<br />
<br />
The function specified in ''luaFunctionName'' is called like so:<br />
<br />
<syntaxhighlight lang="lua"><br />
luaFuncName(optional number of arguments, text)<br />
</syntaxhighlight><br />
<br />
: See also: [[Manual:UI_Functions#resetCmdLineAction|resetCmdLineAction()]]<br />
<br />
;Parameters<br />
<br />
* ''commandLineName:''<br />
: The name of the command line to attach the action function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string.<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
{{note}} You can also pass a function directly instead of using a string<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
function sendTextToMiniConsole(miniConsoleName, cmdLineText)<br />
echo(miniConsoleName, cmdLineText.."\n")<br />
end<br />
<br />
setCmdLineAction("myCmdLine", "sendTextToMiniConsole", "myMiniConsole")<br />
<br />
</syntaxhighlight><br />
<br />
==setCmdLineStyleSheet==<br />
;setCmdLineStyleSheet([commandLineName], markup)<br />
: Applies Qt style formatting to a command line via a special markup language.<br />
<br />
;Parameters<br />
* ''commandLineName:''<br />
: (optional) Name of the command line (or miniconsole the command line is in). If not given the stylesheet will be applied to the main command line.<br />
* ''markup''<br />
: The string instructions, as specified by the Qt Style Sheet reference.<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
: See also: [[Manual:UI_Functions#enableCommandLine|enableCommandLine()]], [[Manual:UI_Functions#createCommandLine|createCommandLine()]]<br />
<br />
;Examples<br />
<syntaxhighlight lang="lua"><br />
-- move the main command line over to the right<br />
setCmdLineStyleSheet("main", [[<br />
QPlainTextEdit {<br />
padding-left: 100px; /* change 100 to your number */<br />
background-color: black; /* change it to your background color */<br />
}<br />
]])<br />
<br />
--only change font-size of your main command line<br />
setCmdLineStyleSheet("main", [[<br />
QPlainTextEdit {<br />
font-sizeː20pt; <br />
}<br />
]])<br />
<br />
--change bg/fg color of your miniconsole command line (name of the miniconsole is 'myMiniconsole'<br />
--the command line in the miniconsole has to be enabled<br />
setCmdLineStyleSheet("myMiniConsole", [[<br />
QPlainTextEdit {<br />
background: rgb(0,100,0);<br />
color: rgb(0,200,255);<br />
font-size: 10pt;<br />
}<br />
]])<br />
</syntaxhighlight><br />
<br />
==setFont==<br />
;setFont(name, font)<br />
: Sets the font on the given window or console name. Can be used to change font of the main console, miniconsoles, and userwindows. Prefer a monospaced font - those work best with text games. See here [https://doc.qt.io/qt-5/qfont.html#setFamily for more].<br />
: See also: [[#getFont|getFont()]], [[#setFontSize|setFontSize()]], [[#getFontSize|getFontSize()]], [[#openUserWindow|openUserWindow()]], [[#getAvailableFonts|getAvailableFonts()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: Optional - the window name to set font size of - can either be none or "main" for the main console, or a miniconsole / userwindow name.<br />
* ''font:''<br />
: The font to use.<br />
<br />
{{MudletVersion|3.9}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The following will set the "main" console window font to Ubuntu Mono, another font included in Mudlet.<br />
setFont("Ubuntu Mono")<br />
setFont("main", "Ubuntu Mono")<br />
<br />
-- This will set the font size of a miniconsole named "combat" to Ubuntu Mono.<br />
setFont("combat", "Ubuntu Mono")<br />
</syntaxhighlight><br />
<br />
==setFontSize==<br />
;setFontSize(name, size)<br />
: Sets a font size on the given window or console name. Can be used to change font size of the Main console as well as dockable UserWindows.<br />
: See Also: [[#getFontSize|getFontSize()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
;Parameters<br />
* ''name:''<br />
: Optional - the window name to set font size of - can either be none or "main" for the main console, or a UserWindow name.<br />
* ''size:''<br />
: The font size to apply to the window.<br />
<br />
{{MudletVersion|3.4}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The following will set the "main" console window font to 12-point font.<br />
setFontSize(12)<br />
setFontSize("main", 12)<br />
<br />
-- This will set the font size of a user window named "uw1" to 12-point font.<br />
setFontSize("uw1", 12)<br />
</syntaxhighlight><br />
<br />
==setGauge==<br />
;setGauge(gaugeName, currentValue, maxValue, gaugeText)<br />
: Use this function when you want to change the gauges look according to your values. Typical usage would be in a prompt with your current health or whatever value, and throw in some variables instead of the numbers.<br />
<br />
: See also: [[Manual:Lua_Functions#moveGauge|moveGauge()]], [[Manual:Lua_Functions#createGauge|createGauge()]], [[Manual:Lua_Functions#setGaugeText|setGaugeText()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- create a gauge<br />
createGauge("healthBar", 300, 20, 30, 300, nil, "green")<br />
<br />
--Change the looks of the gauge named healthBar and make it<br />
--fill to half of its capacity. The height is always remembered.<br />
setGauge("healthBar", 200, 400)<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="lua"><br />
--If you wish to change the text on your gauge, you’d do the following:<br />
setGauge("healthBar", 200, 400, "some text")<br />
</syntaxhighlight><br />
<br />
==setGaugeStyleSheet==<br />
;setGaugeStyleSheet(gaugeName, css, cssback, csstext)<br />
: Sets the CSS stylesheets on a gauge - one on the front (the part that resizes accoding to the values on the gauge) and one in the back. You can use [https://build-system.fman.io/qt-designer-download Qt Designer] to create stylesheets.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setGaugeStyleSheet("hp_bar", [[background-color: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #f04141, stop: 0.1 #ef2929, stop: 0.49 #cc0000, stop: 0.5 #a40000, stop: 1 #cc0000);<br />
border-top: 1px black solid;<br />
border-left: 1px black solid;<br />
border-bottom: 1px black solid;<br />
border-radius: 7;<br />
padding: 3px;]],<br />
[[background-color: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #bd3333, stop: 0.1 #bd2020, stop: 0.49 #990000, stop: 0.5 #700000, stop: 1 #990000);<br />
border-width: 1px;<br />
border-color: black;<br />
border-style: solid;<br />
border-radius: 7;<br />
padding: 3px;]])<br />
</syntaxhighlight><br />
<br />
==setGaugeText==<br />
;setGaugeText(gaugename, css, ccstext )<br />
: Set the formatting of the text used inside the inserted gaugename.<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
setGaugeText("healthBar", [[<p style="font-weight:bold;color:#C9C9C9;letter-spacing:1pt;word-spacing:2pt;font-size:12px;text-align:center;font-family:arial black, sans-serif;">]]..MY_NUMERIC_VARIABLE_HERE..[[</p>]])</syntaxhighlight><br />
<br />
;Useful resources:<br />
:http://csstxt.com - Generate the text exactly how you like it before pasting it into the css slot.<br />
:https://www.w3schools.com/colors/colors_picker.asp - Can help you choose colors for your text!<br />
<br />
==setHexBgColor==<br />
;setHexBgColor([windowName], hexColorString)<br />
:Sets the current text nackground color in the main window unless windowName parameter given. This function allows to specify the color as a 6 character hexadecimal string.<br />
<br />
* ''windowName:''<br />
: Optional parameter set the current text background color in windowname given.<br />
* ''hexColorString''<br />
: 6 character long hexadecimal string to set the color to. The first two characters 00-FF represent the red part of the color, the next two the green and the last two characters stand for the blue part of the color<br />
<br />
: See also: [[#setBgColor | setBgColor()]], [[#setHexFgColor | setHexFgColor()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--highlights the first occurrence of the string "Tom" in the current line with a red Background color.<br />
selectString( "Tom", 1 )<br />
setHexBgColor( "FF0000" )<br />
</syntaxhighlight><br />
<br />
==setHexFgColor==<br />
;setHexFgColor([windowName], hexColorString)<br />
:Sets the current text foreground color in the main window unless windowName parameter given. This function allows to specify the color as a 6 character hexadecimal string.<br />
<br />
* ''windowName:''<br />
: Optional parameter set the current text foreground color in windowname given.<br />
* ''hexColorString''<br />
: 6 character long hexadecimal string to set the color to. The first two characters 00-FF represent the red part of the color, the next two the green and the last two characters stand for the blue part of the color<br />
<br />
: See also: [[#setFgColor | setFgColor()]], [[#setHexBgColor | setHexBgColor()]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--highlights the first occurrence of the string "Tom" in the current line with a red foreground color.<br />
selectString( "Tom", 1 )<br />
setHexFgColor( "FF0000" )<br />
</syntaxhighlight><br />
<br />
==setItalics==<br />
;setItalics(windowName, bool)<br />
: Sets the current text font to italics/non-italics mode. If the windowName parameters omitted, the main screen will be used.<br />
<br />
==setLabelToolTip==<br />
;setLabelToolTip(labelName, text, [duration])<br />
: Sets a tooltip on the given label.<br />
{{MudletVersion|4.6.1}}<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to set the tooltip to.<br />
* ''text:''<br />
: The text to be shown. Can contain Qt rich text formats.<br />
* ''duration:''<br />
: Duration of the tooltip timeout in seconds. Optional, if not set the default duration will be set.<br />
<br />
: See also: [[Manual:UI_Functions#resetLabelToolTip|resetLabelToolTip()]]<br />
<br />
==setLabelClickCallback==<br />
;setLabelClickCallback(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called if the user clicks on the label/image. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button. Additionally, this function passes an event table as the final argument. This table contains information about the mouse button clicked, other buttons that were pressed at the time, and the mouse cursor's local (relative to the label) and global (relative to the Mudlet window) position. The function specified in ''luaFunctionName'' is called like so:<br />
<br />
<syntaxhighlight lang="lua"><br />
luaFuncName(optional number of arguments, event)<br />
</syntaxhighlight><br />
<br />
where '''event''' has the following structure:<br />
<br />
<syntaxhighlight lang="lua"><br />
event = {<br />
x = 100,<br />
y = 200,<br />
globalX = 300,<br />
globalY = 320,<br />
button = "LeftButton",<br />
buttons = {"RightButton", "MidButton"},<br />
}<br />
</syntaxhighlight><br />
<br />
: See also: [[Manual:UI_Functions#setLabelDoubleClickCallback|setLabelDoubleClickCallback()]], [[Manual:UI_Functions#setLabelReleaseCallback|setLabelReleaseCallback()]], [[Manual:UI_Functions#setLabelMoveCallback|setLabelMoveCallback()]], [[Manual:UI_Functions#setLabelWheelCallback|setLabelWheelCallback()]],[[Manual:UI_Functions#setLabelOnEnter|setLabelOnEnter()]], [[Manual:UI_Functions#setLabelOnLeave|setLabelOnLeave()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: Lua function to call, or the function name, as a string.<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
{{note}} Event argument is available in 3.6+, and in 4.8+ you can pass a function directly instead of a string.<br />
<br />
{{note}}<br />
While '''event.button''' may contain a single string of any listed below, '''event.buttons''' will only ever contain some combination of "LeftButton", "MidButton", and "RightButton"<br />
:The following mouse button strings are defined:<br />
<pre><br />
"LeftButton" "RightButton" "MidButton"<br />
"BackButton" "ForwardButton" "TaskButton"<br />
"ExtraButton4" "ExtraButton5" "ExtraButton6"<br />
"ExtraButton7" "ExtraButton8" "ExtraButton9"<br />
"ExtraButton10" "ExtraButton11" "ExtraButton12"<br />
"ExtraButton13" "ExtraButton14" "ExtraButton15"<br />
"ExtraButton16" "ExtraButton17" "ExtraButton18"<br />
"ExtraButton19" "ExtraButton20" "ExtraButton21"<br />
"ExtraButton22" "ExtraButton23" "ExtraButton24"<br />
</pre><br />
;Example<br />
<syntaxhighlight lang="lua"><br />
createLabel("testLabel", 50, 50, 100, 100, 0)<br />
<br />
function onClickGoNorth(event)<br />
if event.button == "LeftButton" then<br />
send("walk north")<br />
elseif event.button == "RightButton" then<br />
send("swim north")<br />
elseif event.button == "MidButton" then<br />
send("gallop north")<br />
end<br />
end<br />
<br />
setLabelClickCallback("testLabel", "onClickGoNorth")<br />
<br />
-- you can also use them within tables:<br />
mynamespace =<br />
{<br />
onClickGoNorth =<br />
function()<br />
echo("the north button was clicked!")<br />
end,<br />
}<br />
setLabelClickCallback("testLabel", "mynamespace.onClickGoNorth")<br />
<br />
-- or by passing the function directly:<br />
setLabelClickCallback("testLabel", onClickGoNorth)<br />
</syntaxhighlight><br />
<br />
==setLabelDoubleClickCallback==<br />
;setLabelDoubleClickCallback(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called if the user double clicks on the label/image. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button. Additionally, this function passes an event table as the final argument, as in [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]]<br />
<br />
{{MudletVersion|3.6}}<br />
<br />
: See also: [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:UI_Functions#setLabelReleaseCallback|setLabelReleaseCallback()]], [[Manual:UI_Functions#setLabelMoveCallback|setLabelMoveCallback()]], [[Manual:UI_Functions#setLabelWheelCallback|setLabelWheelCallback()]], [[Manual:UI_Functions#setLabelOnEnter|setLabelOnEnter()]], [[Manual:UI_Functions#setLabelOnLeave|setLabelOnLeave()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string.<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
==setLabelMoveCallback==<br />
;setLabelMoveCallback(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called when the mouse moves while inside the specified label/console. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button. Additionally, this function passes an event table as the final argument, as in [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]]<br />
<br />
: See Also: [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:UI_Functions#setLabelDoubleClickCallback|setLabelDoubleClickCallback()]], [[Manual:UI_Functions#setLabelReleaseCallback|setLabelReleaseCallback()]], [[Manual:UI_Functions#setLabelWheelCallback|setLabelWheelCallback()]], [[Manual:UI_Functions#setLabelOnEnter|setLabelOnEnter()]], [[Manual:UI_Functions#setLabelOnLeave|setLabelOnLeave()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string.<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
{{MudletVersion|3.6}}<br />
<br />
==setLabelOnEnter==<br />
;setLabelOnEnter(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called when the mouse enters within the labels borders. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button. Additionally, this function passes an event table as the final argument, similar to [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], but with slightly different information.<br />
: For this callback, the '''event''' argument has the following structure:<br />
<br />
<syntaxhighlight lang="lua"><br />
event = {<br />
x = 100,<br />
y = 200,<br />
globalX = 300,<br />
globalY = 320,<br />
}<br />
</syntaxhighlight><br />
<br />
: See Also: [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:UI_Functions#setLabelDoubleClickCallback|setLabelDoubleClickCallback()]], [[Manual:UI_Functions#setLabelReleaseCallback|setLabelReleaseCallback()]], [[Manual:UI_Functions#setLabelMoveCallback|setLabelMoveCallback()]], [[Manual:UI_Functions#setLabelWheelCallback|setLabelWheelCallback()]], [[Manual:UI_Functions#setLabelOnLeave|setLabelOnLeave()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string - it must be registered as a global function, and not inside any namespaces (tables).<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
function onMouseOver()<br />
echo("The mouse is hovering over the label!\n")<br />
end<br />
<br />
setLabelOnEnter( "compassNorthImage", "onMouseOver" )<br />
</syntaxhighlight><br />
<br />
==setLabelOnLeave==<br />
;setLabelOnLeave(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called when the mouse leaves the labels borders. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button.<br />
<br />
: See Also: [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:UI_Functions#setLabelOnEnter|setLabelOnEnter()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string - it must be registered as a global function, and not inside any namespaces (tables).<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
function onMouseLeft(argument)<br />
echo("The mouse quit hovering over the label the label! We also got this as data on the function: "..argument)<br />
end<br />
<br />
setLabelOnLeave( "compassNorthImage", "onMouseLeft", "argument to pass to function" )<br />
</syntaxhighlight><br />
<br />
==setLabelReleaseCallback==<br />
;setLabelReleaseCallback(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called when a mouse click ends that originated on the specified label/console. This function is called even if you drag the mouse off of the label/console before releasing the click. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button. Additionally, this function passes an event table as the final argument, as in [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]]<br />
<br />
{{MudletVersion|3.0}}<br />
<br />
: See Also: [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:UI_Functions#setLabelDoubleClickCallback|setLabelDoubleClickCallback()]], [[Manual:UI_Functions#setLabelMoveCallback|setLabelMoveCallback()]], [[Manual:UI_Functions#setLabelWheelCallback|setLabelWheelCallback()]], [[Manual:UI_Functions#setLabelOnEnter|setLabelOnEnter()]], [[Manual:UI_Functions#setLabelOnLeave|setLabelOnLeave()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string.<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
{{note}}<br />
The ''event'' argument only available since Mudlet 3.6<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
function onReleaseNorth()<br />
echo("the north button was released!")<br />
end<br />
<br />
setLabelReleaseCallback( "compassNorthImage", "onReleaseNorth" )<br />
<br />
-- you can also use them within tables:<br />
mynamespace = {<br />
onReleaseNorth = function()<br />
echo("the north button was released!")<br />
end<br />
}<br />
<br />
setLabelReleaseCallback( "compassNorthImage", "mynamespace.onReleaseNorth" )<br />
</syntaxhighlight><br />
<br />
==setLabelStyleSheet==<br />
;setLabelStyleSheet(label, markup)<br />
: Applies Qt style formatting to a label via a special markup language.<br />
<br />
; Parameters<br />
* ''label:''<br />
: The name of the label to be formatted (passed when calling createLabel).<br />
* ''markup:''<br />
: The string instructions, as specified by the Qt Style Sheet reference.<br />
: Note that when specifying a file path for styling purposes, forward slashes, / , must be used, even if your OS uses backslashes, \ , normally.<br />
<br />
;References<br />
: http://qt-project.org/doc/qt-5/stylesheet-reference.html<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- This creates a label with a white background and a green border, with the text "test"<br />
-- inside.<br />
createLabel("test", 50, 50, 100, 100, 0)<br />
setLabelStyleSheet("test", [[<br />
background-color: white;<br />
border: 10px solid green;<br />
font-size: 12px;<br />
]])<br />
echo("test", "test")<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
-- This creates a label with a single image, that will tile or clip depending on the<br />
-- size of the label. To use this example, please supply your own image.<br />
createLabel("test5", 50, 353, 164, 55, 0)<br />
setLabelStyleSheet("test5", [[<br />
background-image: url("C:/Users/Administrator/.config/mudlet/profiles/Midkemia Online/Vyzor/MkO_logo.png");<br />
]])<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
-- This creates a label with a single image, that can be resized (such as during a<br />
-- sysWindowResizeEvent). To use this example, please supply your own image.<br />
createLabel("test9", 215, 353, 100, 100, 0)<br />
setLabelStyleSheet("test9", [[<br />
border-image: url("C:/Users/Administrator/.config/mudlet/profiles/Midkemia Online/Vyzor/MkO_logo.png");<br />
]])<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
--This creates a label whose background changes when the users mouse hovers over it.<br />
<br />
--putting the styleSheet in a variable allows us to easily change the styleSheet. We also are placing colors in variables that have been preset. <br />
local labelBackgroundColor = "#123456"<br />
local labelHoverColor = "#654321"<br />
local labelFontSize = 12<br />
local labelName = "HoverLabel"<br />
local ourLabelStyle = [[<br />
QLabel{<br />
background-color: ]]..labelBackgroundColor..[[;<br />
font-size: ]]..labelFontSize..[[px;<br />
qproperty-alignment: 'AlignCenter | AlignCenter';<br />
}<br />
QLabel::hover{<br />
background-color: ]]..labelHoverColor..[[;<br />
font-size: ]]..labelFontSize..[[px;<br />
qproperty-alignment: 'AlignCenter | AlignCenter';<br />
}<br />
]]<br />
<br />
--Creating the label using the labelName and ourLabelStyle variables created above.<br />
createLabel(labelName,0,0,400,400,1)<br />
setLabelStyleSheet(labelName, ourLabelStyle)<br />
echo("HoverLabel","This text shows while mouse is or is not over the label.")<br />
</syntaxhighlight><br />
<syntaxhighlight lang="lua"><br />
--Using QLabel::hover mentioned above. Lets "trick" the label into changing it's text.<br />
--Please keep in mind that the setLabelMoveCallback allows for much more control over not just your label but your entire project.<br />
<br />
--putting the styleSheet in a variable allows us to easily change the styleSheet. We also are placing colors in variables that have been preset. <br />
local labelBackgroundColor = "#123456"<br />
local labelHoverColor = "#654321"<br />
local labelFontSize = 12<br />
local labelName = "HoverLabel"<br />
--Notice we are adding a string returned from a function. In this case, the users profile directory.<br />
local ourLabelStyle = [[<br />
QLabel{<br />
border-image: url("]]..getMudletHomeDir()..[[/imagewithtext.png");<br />
}<br />
QLabel::hover{<br />
border-image: url("]]..getMudletHomeDir()..[[/imagewithhovertext.png");<br />
}<br />
]]<br />
<br />
--Creating the label using the labelName and ourLabelStyle variables created above.<br />
createLabel(labelName,0,0,400,400,1)<br />
setLabelStyleSheet(labelName, ourLabelStyle)<br />
--This is just to example that echos draw on top of the label. You would not want to echo onto a label you were drawing text on with images, because echos would draw on top of them.<br />
echo("HoverLabel","This text shows while mouse is or is not over the label.")<br />
</syntaxhighlight><br />
<br />
==setLabelCursor==<br />
;setLabelCursor(labelName, cursorShape)<br />
: Changes how the mouse cursor looks like when over the label. To reset the cursor shape, use [[#resetLabelCursor|resetLabelCursor()]].<br />
<br />
: See also: [[#resetLabelCursor|resetLabelCursor()]], [[#setLabelCustomCursor|setLabelCustomCursor()]]<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: Name of the label which you want the mouse cursor change at.<br />
* ''cursorShape''<br />
: Shape of the mouse cursor. List of possible cursor shapes is [[CursorShapes| available here]].<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setLabelCursor("myLabel", "Cross")<br />
-- This will change the mouse cursor to a cross if it's over the label myLabel<br />
</syntaxhighlight><br />
<br />
==setLabelCustomCursor==<br />
;setLabelCustomCursor(labelName, custom cursor, [hotX, hotY])<br />
: Changes the mouse cursor shape over your label to a custom cursor. To reset the cursor shape, use [[#resetLabelCursor|resetLabelCursor()]].<br />
<br />
: See also: [[#resetLabelCursor|resetLabelCursor()]], [[#setLabelCursor|setLabelCursor()]]<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: Name of the label which you want the mouse cursor change at.<br />
* ''custom cursor''<br />
: Location of your custom cursor file. To be compatible with all systems it is recommended to use png files with size of 32x32.<br />
* ''hotX''<br />
: X-coordinate of the cursors hotspot position. Optional, if not set it is set to -1 which is in the middle of your custom cursor.<br />
* ''hotY''<br />
: Y-coordinate of the cursors hotspot position. Optional, if not set it is set to -1 which is in the middle of your custom cursor.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setLabelCustomCursor("myLabel", getMudletHomeDir().."/custom_cursor.png")<br />
-- This will change the mouse cursor to your custom cursor if it's over the label myLabel<br />
</syntaxhighlight><br />
<br />
==setLabelWheelCallback==<br />
;setLabelWheelCallback(labelName, luaFunctionName, [any arguments])<br />
: Specifies a Lua function to be called when the mouse wheel is scrolled while inside the specified label/console. This function can pass any number of string or integer number values as additional parameters. These parameters are then used in the callback - thus you can associate data with the label/button. Additionally, this function passes an event table as the final argument, similar to [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], but with slightly different information.<br />
: For this callback, the ''event'' argument has the following structure:<br />
<br />
<syntaxhighlight lang="lua"><br />
event = {<br />
x = 100,<br />
y = 200,<br />
globalX = 300,<br />
globalY = 320,<br />
buttons = {"RightButton", "MidButton"},<br />
angleDeltaX = 0,<br />
angleDeltaY = 120<br />
}<br />
</syntaxhighlight><br />
<br />
: Keys ''angleDeltaX'' and ''angleDeltaY'' correspond with the horizontal and vertical scroll distance, respectively. For most mice, these values will be multiples of 120.<br />
<br />
: See Also: [[Manual:UI_Functions#setLabelClickCallback|setLabelClickCallback()]], [[Manual:UI_Functions#setLabelDoubleClickCallback|setLabelDoubleClickCallback()]], [[Manual:UI_Functions#setLabelReleaseCallback|setLabelReleaseCallback()]], [[Manual:UI_Functions#setLabelMoveCallback|setLabelMoveCallback()]], [[Manual:UI_Functions#setLabelOnEnter|setLabelOnEnter()]], [[Manual:UI_Functions#setLabelOnLeave|setLabelOnLeave()]]<br />
<br />
;Parameters<br />
<br />
* ''labelName:''<br />
: The name of the label to attach a callback function to.<br />
* ''luaFunctionName:''<br />
: The Lua function name to call, as a string.<br />
* ''any arguments:''<br />
: (optional) Any amount of arguments you'd like to pass to the calling function.<br />
<br />
{{MudletVersion|3.6}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
function onWheelNorth(event)<br />
if event.angleDeltaY > 0 then<br />
echo("the north button was wheeled forwards over!")<br />
else<br />
echo("the north button was wheeled backwards over!")<br />
end<br />
end<br />
<br />
setLabelWheelCallback( "compassNorthImage", "onWheelNorth" )<br />
<br />
-- you can also use them within tables:<br />
mynamespace = {<br />
onWheelNorth = function()<br />
echo("the north button was wheeled over!")<br />
end<br />
}<br />
<br />
setWheelReleaseCallback( "compassNorthImage", "mynamespace.onWheelNorth" )<br />
</syntaxhighlight><br />
<br />
==setLink==<br />
;setLink([windowName], command, tooltip)<br />
: Turns the [[Manual:Lua_Functions#selectString|selected]] text into a clickable link - upon being clicked, the link will do the command code. Tooltip is a string which will be displayed when the mouse is over the selected text.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of a miniconsole or a userwindow in which to select the text in.<br />
* ''command:''<br />
: command to do when the text is clicked, as text or Lua function.<br />
* ''tooltip:''<br />
: tooltip to show when the mouse is over the text - explaining what would clicking do.<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
-- you can clickify a lot of things to save yourself some time - for example, you can change<br />
-- the line where you receive a message to be clickable to read it!<br />
-- prel regex trigger:<br />
-- ^You just received message #(\w+) from \w+\.$<br />
-- script:<br />
selectString(matches[2], 1)<br />
setUnderline(true) setLink([[send("msg read ]]..matches[2]..[[")]], "Read #"..matches[2])<br />
resetFormat()<br />
<br />
-- example of selecting text in a miniconsole and turning it into a link:<br />
HelloWorld = Geyser.MiniConsole:new({<br />
name="HelloWorld",<br />
x="70%", y="50%",<br />
width="30%", height="50%",<br />
})<br />
HelloWorld:echo("hi")<br />
selectString("HelloWorld", "hi", 1)<br />
setLink("HelloWorld", "echo'you clicked hi!'", "click me!")<br />
</syntaxhighlight><br />
<br />
==setMainWindowSize==<br />
;setMainWindowSize(mainWidth, mainHeight)<br />
: Changes the size of your main Mudlet window to the values given.<br />
: See Also: [[Manual:Lua_Functions#getMainWindowSize|getMainWindowSize()]]<br />
<br />
; Parameters<br />
* ''mainWidth:''<br />
: The new width in pixels.<br />
* ''mainHeight:''<br />
: The new height in pixels.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
--this will resize your main Mudlet window<br />
setMainWindowSize(1024, 768)<br />
</syntaxhighlight><br />
<br />
==setMapWindowTitle==<br />
;setMapWindowTitle(text)<br />
: Changes the title shown in the mapper window when it's popped out.<br />
: See also: [[#resetMapWindowTitle|resetMapWindowTitle()]]<br />
<br />
; Parameters<br />
* ''text:''<br />
: New window title to set.<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setMapWindowTitle("my cool game map")<br />
</syntaxhighlight><br />
<br />
==setMiniConsoleFontSize==<br />
;setMiniConsoleFontSize(name, fontSize)<br />
: Sets the font size of the mini console. see also: [[#setFontSize | setFontSize()]], [[#createMiniConsole | createMiniConsole()]], [[#createLabel | createLabel()]]<br />
<br />
==setOverline==<br />
;setOverline([windowName], boolean)<br />
: Sets the current text font to be overlined (true) or not overlined (false) mode. If the windowName parameters omitted, the main screen will be used. If you've got text currently selected in the Mudlet buffer, then the selection will be overlined. Any text you add after with [[Manual:Lua_Functions#echo|echo()]] or [[Manual:Lua_Functions#insertText|insertText()]] will be overlined until you use [[Manual:Lua_Functions#resetFormat|resetFormat()]].<br />
<br />
* ''windowName:''<br />
: (optional) name of the window to set the text to be overlined or not.<br />
<br />
* ''boolean:''<br />
: A ''true'' or ''false'' that enables or disables overlining of text<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
-- enable overlined text<br />
setOverline(true)<br />
-- the following echo will be have an overline<br />
echo("hi")<br />
-- turns off bolding, italics, underlines, colouring, and strikethrough (and, after this and reverse have been added, them as well). It's good practice to clean up after you're done with the formatting, so other your formatting doesn't "bleed" into other echoes.<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.17}}<br />
<br />
==setPopup==<br />
;setPopup([windowName], {lua code}, {hints})<br />
: Turns the [[Manual:Lua_Functions#selectString|selected()]] text into a left-clickable link, and a right-click menu for more options. The selected 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.<br />
<br />
; Parameters<br />
* ''windowName:''<br />
: the name of the console to operate on. If not using this in a miniConsole, use "main" as the name.<br />
: This argument was ignored before Mudlet 4.11.<br />
* ''{lua code}:''<br />
: a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e. <syntaxhighlight lang="lua" inline="">{[[send("hello")]], function() echo("hi!") end}</syntaxhighlight><br />
* ''{hints}:''<br />
: a table of strings which will be shown on the popup and right-click menu. ie, <syntaxhighlight lang="lua" inline="">{"send the hi command", "echo hi to yourself"}</syntaxhighlight>.<br />
<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- In a `Raising your hand in greeting, you say "Hello!"` exact match trigger,<br />
-- the following code will make left-clicking on `Hello` show you an echo, while right-clicking<br />
-- will show some commands you can do.<br />
<br />
selectString("Hello", 1)<br />
setPopup("main", {function() send("bye") end, function() echo("hi!") end}, {"send 'bye' to the MUD", "click to echo 'hi!'"})<br />
<br />
-- alternatively, put command as text (in [[ and ]] to use quotation marks inside)<br />
setPopup("main", {[[send("bye")]], [[echo("hi!")]]}, {"send 'bye' to the MUD", "click to echo 'hi!'"})<br />
<br />
</syntaxhighlight><br />
<br />
==setProfileStyleSheet==<br />
;setProfileStyleSheet(stylesheet)<br />
: Sets a stylesheet for the current Mudlet profile - allowing you to customise content outside of the main window (the profile tabs, the scrollbar, and so on). This function is better than setAppStyleSheet() because it affects only the current profile and not every other one as well.<br />
<br />
: See also: [[#setAppStyleSheet|setAppStyleSheet()]]<br />
<br />
;Parameters<br />
<br />
* ''stylesheet:''<br />
: The entire stylesheet you'd like to use. See [http://qt-project.org/doc/qt-5/stylesheet-reference.html Qt Style Sheets Reference] for the list of widgets you can style and CSS properties you can apply on them.<br />
<br />
: See also [https://github.com/vadi2/QDarkStyleSheet/blob/master/qdarkstyle/style.qss QDarkStyleSheet], a rather extensive stylesheet that shows you all the different configuration options you could apply, available as an [http://forums.mudlet.org/viewtopic.php?f=6&t=17624 mpackage here].<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- credit to Akaya @ http://forums.mudlet.org/viewtopic.php?f=5&t=4610&start=10#p21770<br />
local background_color = "#26192f"<br />
local border_color = "#b8731b"<br />
<br />
setProfileStyleSheet([[<br />
QMainWindow {<br />
background: ]]..background_color..[[;<br />
}<br />
QToolBar {<br />
background: ]]..background_color..[[;<br />
}<br />
QToolButton {<br />
background: ]]..background_color..[[;<br />
border-style: solid;<br />
border-width: 2px;<br />
border-color: ]]..border_color..[[;<br />
border-radius: 5px;<br />
font-family: BigNoodleTitling;<br />
color: white;<br />
margin: 2px;<br />
font-size: 12pt;<br />
}<br />
QToolButton:hover { background-color: grey;}<br />
QToolButton:focus { background-color: grey;}<br />
<br />
QTreeView {<br />
background: ]]..background_color..[[;<br />
color: white;<br />
}<br />
<br />
QMenuBar{ background-color: ]]..background_color..[[;}<br />
<br />
QMenuBar::item{ background-color: ]]..background_color..[[;}<br />
<br />
QDockWidget::title {<br />
background: ]]..border_color..[[;<br />
}<br />
QStatusBar {<br />
background: ]]..border_color..[[;<br />
}<br />
QScrollBar:vertical {<br />
background: ]]..background_color..[[;<br />
width: 15px;<br />
margin: 22px 0 22px 0;<br />
}<br />
QScrollBar::handle:vertical {<br />
background-color: ]]..background_color..[[;<br />
min-height: 20px;<br />
border-width: 2px;<br />
border-style: solid;<br />
border-color: ]]..border_color..[[;<br />
border-radius: 7px;<br />
}<br />
QScrollBar::add-line:vertical {<br />
background-color: ]]..background_color..[[;<br />
border-width: 2px;<br />
border-style: solid;<br />
border-color: ]]..border_color..[[;<br />
border-bottom-left-radius: 7px;<br />
border-bottom-right-radius: 7px;<br />
height: 15px;<br />
subcontrol-position: bottom;<br />
subcontrol-origin: margin;<br />
}<br />
QScrollBar::sub-line:vertical {<br />
background-color: ]]..background_color..[[;<br />
border-width: 2px;<br />
border-style: solid;<br />
border-color: ]]..border_color..[[;<br />
border-top-left-radius: 7px;<br />
border-top-right-radius: 7px;<br />
height: 15px;<br />
subcontrol-position: top;<br />
subcontrol-origin: margin;<br />
}<br />
QScrollBar::up-arrow:vertical, QScrollBar::down-arrow:vertical {<br />
background: white;<br />
width: 4px;<br />
height: 3px;<br />
}<br />
QScrollBar::add-page:vertical, QScrollBar::sub-page:vertical {<br />
background: none;<br />
}<br />
]])<br />
<br />
-- if you'd like to reset it, use:<br />
setProfileStyleSheet("")<br />
<br />
-- to only affect scrollbars within the main window and miniconsoles, prefix them with 'TConsole':<br />
setProfileStyleSheet[[<br />
TConsole QScrollBar:vertical {<br />
border: 2px solid grey;<br />
background: #32CC99;<br />
width: 15px;<br />
margin: 22px 0 22px 0;<br />
}<br />
TConsole QScrollBar::handle:vertical {<br />
background: white;<br />
min-height: 20px;<br />
}<br />
TConsole QScrollBar::add-line:vertical {<br />
border: 2px solid grey;<br />
background: #32CC99;<br />
height: 20px;<br />
subcontrol-position: bottom;<br />
subcontrol-origin: margin;<br />
}<br />
TConsole QScrollBar::sub-line:vertical {<br />
border: 2px solid grey;<br />
background: #32CC99;<br />
height: 20px;<br />
subcontrol-position: top;<br />
subcontrol-origin: margin;<br />
}<br />
TConsole QScrollBar::up-arrow:vertical, QScrollBar::down-arrow:vertical {<br />
border: 2px solid grey;<br />
width: 3px;<br />
height: 3px;<br />
background: white;<br />
}<br />
TConsole QScrollBar::add-page:vertical, QScrollBar::sub-page:vertical {<br />
background: none;<br />
}<br />
]]<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|4.6}}<br />
<br />
==setReverse==<br />
;setReverse([windowName], boolean)<br />
: Sets the current text to swap foreground and background color settings (true) or not (false) mode. If the windowName parameters omitted, the main screen will be used. If you've got text currently selected in the Mudlet buffer, then the selection will have it's colors swapped. Any text you add after with [[Manual:Lua_Functions#echo|echo()]] or [[Manual:Lua_Functions#insertText|insertText()]] will have their foreground and background colors swapped until you use [[Manual:Lua_Functions#resetFormat|resetFormat()]].<br />
<br />
* ''windowName:''<br />
: (optional) name of the window to set the text colors to be reversed or not.<br />
<br />
* ''boolean:''<br />
: A ''true'' or ''false'' that enables or disables reversing of the fore- and back-ground colors of text<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
-- enable fore/back-ground color reversal of text<br />
setReverse(true)<br />
-- the following echo will have the text colors reversed<br />
echo("hi")<br />
-- turns off bolding, italics, underlines, colouring, and strikethrough (and, after this and overline have been added, them as well). It's good practice to clean up after you're done with the formatting, so other your formatting doesn't "bleed" into other echoes.<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
{{MudletVersion|3.17}}<br />
<br />
{{note}} Although the visual effect on-screen is the same as that of text being selected if both apply to a piece of text they neutralise each other - however the effect of the reversal ''will'' be carried over in copies made by the "Copy to HTML" and in logs made in HTML format log file mode.<br />
<br />
==setStrikeOut==<br />
;setStrikeOut([windowName], boolean)<br />
: Sets the current text font to be striken out (true) or not striken out (false) mode. If the windowName parameters omitted, the main screen will be used. If you've got text currently selected in the Mudlet buffer, then the selection will be bolded. Any text you add after with [[Manual:Lua_Functions#echo|echo()]] or [[Manual:Lua_Functions#insertText|insertText()]] will be striken out until you use [[Manual:Lua_Functions#resetFormat|resetFormat()]].<br />
<br />
* ''windowName:''<br />
: (optional) name of the window to set the text to be stricken out or not.<br />
<br />
* ''boolean:''<br />
: A ''true'' or ''false'' that enables or disables striking out of text<br />
<br />
;Example<br />
<br />
<syntaxhighlight lang="lua"><br />
-- enable striken-out text<br />
setStrikeOut(true)<br />
-- the following echo will be have a strikethrough<br />
echo("hi")<br />
-- turns off bolding, italics, underlines, colouring, and strikethrough. It's good practice to clean up after you're done with the formatting, so other your formatting doesn't "bleed" into other echoes.<br />
resetFormat()<br />
</syntaxhighlight><br />
<br />
==setTextFormat==<br />
;setTextFormat(windowName, r1, g1, b1, r2, g2, b2, bold, underline, italics, [strikeout], [overline], [reverse])<br />
: Sets current text format of selected window. This is a more convenient means to set all the individual features at once compared to using [[#setFgColor|setFgColor]]( windowName, r,g,b ), [[#setBold|setBold]]( windowName, true ), [[#setItalics|setItalics]]( windowName, true ), [[#setUnderline|setUnderline]]( windowName, true ), [[#setStrikeOut|setStrikeOut]]( windowName, true ).<br />
: See Also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]]<br />
<br />
;Parameters<br />
* ''windowName''<br />
: Specify name of selected window. If empty string "" or "main" format will be applied to the main console<br />
* ''r1,g1,b1''<br />
: To color text background, give number values in RBG style<br />
* ''r2,g2,b2''<br />
: To color text foreground, give number values in RBG style<br />
* ''bold''<br />
: To format text bold, set to 1 or true, otherwise 0 or false<br />
* ''underline''<br />
: To underline text, set to 1 or true, otherwise 0 or false<br />
* ''italics''<br />
: To format text italic, set to 1 or true, otherwise 0 or false<br />
* ''strikeout<br />
: (optional) To strike text out, set to 1 or true, otherwise 0 or false or simply no argument<br />
* ''overline<br />
: (optional) To use overline, set to 1 or true, otherwise 0 or false or simply no argument<br />
* ''reverse<br />
: (optional) To swap foreground and background colors, set to 1 or true, otherwise 0 or false or simply no argument<br />
<br />
;Example:<br />
<syntaxhighlight lang="lua"><br />
--This script would create a mini text console and write with bold, struck-out, yellow foreground color and blue background color "This is a test".<br />
createMiniConsole( "con1", 0,0,300,100);<br />
setTextFormat("con1",0,0,255,255,255,0,true,0,false,1);<br />
echo("con1","This is a test")<br />
</syntaxhighlight><br />
<br />
{{note}} In versions prior to 3.7.0 the error messages ''and this wiki'' were wrong in that they had the foreground color parameters as r1, g1 and b1 and the background ones as r2, g2 and b2.<br />
<br />
==setUnderline==<br />
;setUnderline(windowName, bool)<br />
: Sets the current text font to underline/non-underline mode. If the windowName parameters omitted, the main screen will be used.<br />
<br />
==setUserWindowTitle==<br />
;setUserWindowTitle(windowName, text)<br />
: sets a new title text for the UserWindow windowName<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the userwindow<br />
* ''text''<br />
: new title text<br />
<br />
{{MudletVersion|4.8}}<br />
<br />
: See also: [[#resetUserWindowTitle|resetUserWindowTitle()]], [[#openUserWindow|openUserWindow()]]<br />
<br />
==setUserWindowStyleSheet==<br />
;setUserWindowStyleSheet(windowName, markup)<br />
: Applies Qt style formatting to the border/title area of a userwindow via a special markup language.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the userwindow<br />
* ''markup''<br />
: The string instructions, as specified by the Qt Style Sheet reference.<br />
: Note that when you dock the userwindow the border style is not provided by this<br />
<br />
{{MudletVersion|4.10}}<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- changes the title area style of the UserWindow 'myUserWindow'<br />
setUserWindowStyleSheet("myUserWindow", [[QDockWidget::title{ <br />
background-color: rgb(0,255,150);<br />
border: 2px solid red;<br />
border-radius: 8px;<br />
text-align: center; <br />
}]])<br />
</syntaxhighlight><br />
<br />
: See also: [[#openUserWindow|openUserWindow()]]<br />
<br />
==setWindow==<br />
;setWindow(windowName, name, [Xpos, Ypos, show])<br />
: Changes the parent window of an element.<br />
{{MudletVersion|4.8}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the userwindow which you want the element put in. If you want to put the element into the main window, use windowName "main".<br />
* ''name''<br />
: Name of the element which you want to switch the parent from. Elements can be labels, miniconsoles and the embedded mapper. If you want to move the mapper use the name "mapper"<br />
* ''Xpos:''<br />
: X position of the element. Measured in pixels, with 0 being the very left. Passed as an integer number. Optional, if not given it will be 0.<br />
* ''Ypos:''<br />
: Y position of the element. Measured in pixels, with 0 being the very top. Passed as an integer number. Optional, if not given it will be 0.<br />
* ''show:''<br />
: true or false to decide if the element will be shown or not in the new parent window. Optional, if not given it will be true.<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setWindow("myuserwindow", "mapper")<br />
-- This will put your embedded mapper in your userwindow "myuserwindow".<br />
</syntaxhighlight><br />
<br />
==setWindowWrap==<br />
;setWindowWrap(windowName, wrapAt)<br />
: sets at what position in the line the will start word wrap.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the "main" console or user-created miniconsole which you want to be wrapped differently. If you want to wrap the main window, use windowName "main".<br />
* ''wrapAt:''<br />
: Number of characters at which the wrap must happen at the latest. This means, it probably will be wrapped earlier than that.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setWindowWrap("main", 10)<br />
display("This is just a test")<br />
<br />
-- The following output will result in the main window console:<br />
"This is<br />
just a<br />
test"<br />
</syntaxhighlight><br />
<br />
==setWindowWrapIndent==<br />
;setWindowWrapIndent(windowName, wrapTo)<br />
: sets how many spaces wrapped text will be indented with (after the first line of course).<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: Name of the "main" console or user-created miniconsole which you want to be wrapped differently. If you want to wrap the main window, use windowName "main".<br />
* ''wrapTo:''<br />
: Number of spaces which wrapped lines are prefixed with.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
setWindowWrap("main", 10)<br />
setWindowWrapIndent("main", 3)<br />
display("This is just a test")<br />
<br />
-- The following output will result in the main window console:<br />
"This is<br />
just a<br />
test"<br />
</syntaxhighlight><br />
<br />
==showCaptureGroups==<br />
;showCaptureGroups()<br />
:Lua debug function that highlights in random colors all capture groups in your trigger regex on the screen. This is very handy if you make complex regex and want to see what really matches in the text. This function is defined in DebugTools.lua.<br />
<br />
;Example:<br />
:Make a trigger with the regex (\w+) and call this function in a trigger. All words in the text will be highlighted in random colors.<br />
<br />
==showMultimatches==<br />
;showMultimatches()<br />
:Lua helper function to show you what the table multimatches[n][m] contains. This is very useful when debugging multiline triggers - just doing showMultimatches() in your script will make it give the info. This function is defined in DebugTools.lua.<br />
<br />
;Example:<br />
See [[Manual:Advanced_Lua#How_to_use_multimatches.5Bn.5D.5Bm.5D|How to use multimatches[n][m]]] for a more thorough explanation including examples.<br />
<br />
==showWindow==<br />
;showWindow(name)<br />
: Makes a hidden window (label or miniconsole) be shown again.<br />
<br />
: See also: [[#hideWindow | hideWindow()]]<br />
<br />
==showColors==<br />
;showColors([columns], [filterColor], [sort])<br />
: shows the named colors currently available in Mudlet's color table. These colors are stored in '''color_table''', in table form. The format is ''color_table.colorName = {r, g, b}''.<br />
<br />
: See Also: [[Manual:Lua_Functions#bg|bg()]], [[Manual:Lua_Functions#fg|fg()]], [[Manual:Lua_Functions#cecho|cecho()]]<br />
<br />
;Parameters<br />
* ''columns:''<br />
: (optional) number of columns to print the color table in.<br />
* ''filterColor:''<br />
: (optional) filter text. If given, the colors displayed will be limited to only show colors containing this text.<br />
* ''sort:''<br />
: (optional) sort colors alphabetically.<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
-- display as four columns:<br />
showColors(4)<br />
<br />
-- show only red colours:<br />
showColors("red")<br />
</syntaxhighlight><br />
The output for this is:<br />
<br />
[[File:ShowColors.png|showColors(4)|thumb|center]]<br />
<br />
==showGauge==<br />
;showGauge(gaugeName)<br />
: shows the given gauge, in case it was hidden previously.<br />
<br />
: See also: [[#hideGauge|hideGauge()]], [[#createGauge|createGauge()]]<br />
<br />
;Parameters<br />
* ''gaugeName:''<br />
: name of the gauge to show.<br />
<br />
;Example:<br />
<br />
<syntaxhighlight lang="lua"><br />
hideGauge("my gauge")<br />
showGauge("my<br />
</syntaxhighlight><br />
<br />
==showToolBar==<br />
;showToolBar(name)<br />
: Makes a toolbar (a button group) appear on the screen.<br />
<br />
;Parameters<br />
* ''name:''<br />
: name of the button group to display<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
showToolBar("my attack buttons")<br />
</syntaxhighlight><br />
<br />
==suffix==<br />
;suffix(text, [writingFunction], [foregroundColor], [backgroundColor], [windowName])<br />
: Suffixes text at the end of the current line. This is similar to [[Manual:Lua_Functions#echo | echo()]], which also suffixes text at the end of the line, but different - [[Manual:Lua_Functions#echo | echo()]] makes sure to do it on the last line in the buffer, while suffix does it on the line the cursor is currently on.<br />
<br />
;Parameters<br />
* ''text''<br />
: the information you want to prefix<br />
* ''writingFunction''<br />
: optional parameter, allows the selection of different functions to be used to write the text, valid options are: echo, cecho, decho, and hecho.<br />
* ''foregroundColor''<br />
: optional parameter, allows a foreground color to be specified if using the echo function using a color name, as with the fg() function<br />
* ''backgroundColor''<br />
: optional parameter, allows a background color to be specified if using the echo function using a color name, as with the bg() function<br />
* ''windowName''<br />
: optional parameter, allows the selection a miniconsole or the main window for the line that will be prefixed<br />
<br />
: See also: [[#prefix | prefix()]], [[Manual:Lua_Functions#echo | echo()]]<br />
<br />
==wrapLine==<br />
;wrapLine(windowName, lineNumber)<br />
: wraps the line specified by ''lineNumber'' of mini console (window) ''windowName''. This function will interpret \n characters, apply word wrap and display the new lines on the screen. This function may be necessary if you use deleteLine() and thus erase the entire current line in the buffer, but you want to do some further echo() calls after calling deleteLine(). You will then need to re-wrap the last line of the buffer to actually see what you have echoed and get your \n interpreted as newline characters properly. Using this function is no good programming practice and should be avoided. There are better ways of handling situations where you would call deleteLine() and echo afterwards e.g.:<br />
<br />
<syntaxhighlight lang="lua">selectString(line,1)<br />
replace("")</syntaxhighlight><br />
<br />
This will effectively have the same result as a call to deleteLine() but the buffer line will not be entirely removed. Consequently, further calls to echo() etc. sort of functions are possible without using wrapLine() unnecessarily.<br />
<br />
: See Also: [[Manual:Lua_Functions#replace|replace()]], [[Manual:Lua_Functions#deleteLine|deleteLine()]]<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The miniconsole or the main window (use ''main'' for the main window)<br />
* ''lineNumber:''<br />
: The line number which you'd like re-wrapped.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- re-wrap the last line in the main window<br />
wrapLine("main", getLineCount())<br />
</syntaxhighlight><br />
<br />
[[Category:Mudlet Manual]]<br />
[[Category:Mudlet API]]</div>Demonnichttps://wiki.mudlet.org/index.php?title=Area_51&diff=18602Area 512022-01-02T17:22:07Z<p>Demonnic: /* hecho PR #5669 merged, PR5719 merged, PR5751 open */</p>
<hr />
<div>{{TOC right}}<br />
<br />
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 [[Manual:Lua_Functions|Lua Functions]] and its sub-sites. <br />
<br />
Please use the [[Area_51/Template]] to add new entries in the sections below.<br />
<br />
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.<br />
<br />
<br />
=Basic Essential Functions=<br />
:These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.<br />
<br />
=Database Functions=<br />
:A collection of functions for helping deal with the database.<br />
<br />
=Date/Time Functions=<br />
: A collection of functions for handling date & time.<br />
<br />
=File System Functions=<br />
: A collection of functions for interacting with the file system.<br />
<br />
=Mapper Functions=<br />
: A collection of functions that manipulate the mapper and its related features.<br />
<br />
==mapSymbolFontInfo, PR #4038 closed==<br />
;mapSymbolFontInfo()<br />
: See also: [[#setupMapSymbolFont|setupMapSymbolFont()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;returns<br />
* either a table of information about the configuration of the font used for symbols in the (2D) map, the elements are:<br />
:* ''fontName'' - a string of the family name of the font specified<br />
:* ''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.<br />
:* ''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).<br />
* or ''nil'' and an error message on failure.<br />
<br />
::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).<br />
<br />
<br />
==setupMapSymbolFont, PR #4038 closed==<br />
;setupMapSymbolFont(fontName[, onlyUseThisFont[, scalingFactor]])<br />
:configures the font used for symbols in the (2D) map.<br />
: See also: [[#mapSymbolFontInfo|mapSymbolFontInfo()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;Parameters<br />
* ''fontName'' one of:<br />
:* - a string that is the family name of the font to use;<br />
:* - the empty string ''""'' to reset to the default {which is '''"Bitstream Vera Sans Mono"'''};<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow a following one to be modified.<br />
* ''onlyUseThisFont'' (optional) one of:<br />
:* - 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;<br />
:* - 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;<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow the following one to be modified.<br />
* ''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.<br />
<br />
;Returns<br />
* ''true'' on success<br />
* ''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).<br />
<br />
=Miscellaneous Functions=<br />
: Miscellaneous functions.<br />
<br />
==getCharacterName, PR #3952 open==<br />
;getCharacterName()<br />
<br />
: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.<br />
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.<br />
<br />
:See also: [[#sendCharacterName|sendCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lua send("cast 'glamor' " .. getCharacterName())<br />
<br />
You get a warm feeling passing from your core to the tips of your hands, feet and other body parts.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A tawny long-haired cat saunters over and start to rub itself against your ankles.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A mangy dog trots up to you and proceeds to mark the bottom of your leggings.<br />
</syntaxhighlight><br />
<br />
==getCustomLoginTextId, PR #3952 open==<br />
;getCustomLoginTextId()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#sendPassword|sendPassword()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCharacterName, PR #3952 open==<br />
;sendCharacterName()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
==sendCharacterPassword, PR #3952 open==<br />
;sendCharacterPassword()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]], [[#sendCharacterName|sendCharacterName()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCharacterName() ~= "" then<br />
tempTime(2.0, [[sendCharacterName()]], 1)<br />
tempTime(3.0, [[sendCharacterPassword()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCustomLoginText, PR #3952 open==<br />
;sendCustomLoginText()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendPassword|sendPassword()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
=Mudlet Object Functions=<br />
: A collection of functions that manipulate Mudlets scripting objects - triggers, aliases, and so forth.<br />
<br />
=Networking Functions=<br />
: A collection of functions for managing networking.<br />
<br />
=String Functions=<br />
: These functions are used to manipulate strings.<br />
<br />
==string.patternEscape, utf8.patternEscape PR 5806==<br />
; escapedString = string.patternEscape(str) or escapedString = utf8.patternEscape(str)<br />
<br />
: Returns a version of str with all Lua pattern characters escaped to ensure string.match/find/etc look for the original str.<br />
<br />
;See also: [[Manual:Lua_Functions#string.trim|string.trim()]], [[Manual:Lua_Functions#string.genNocasePattern|string.genNocasePattern()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''str:''<br />
: The string to escape lua pattern characters in.<br />
<br />
;Returns <br />
* The string with all special Lua pattern characters escaped. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- searching for a url inside of a string. <br />
local helpString = [[<br />
This feature can be accessed by going to https://some-url.com/athing.html?param=value and<br />
retrieving the result!<br />
]]<br />
local url = "https://some-url.com/"<br />
display(helpString:find(url))<br />
-- nil<br />
display(helpString:find(string.patternEscape(url)))<br />
-- 42<br />
-- 62<br />
display(url:patternEscape())<br />
-- "https://some%-url%.com/"<br />
</syntaxhighlight><br />
<br />
=Table Functions=<br />
: 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.<br />
<br />
=Text to Speech Functions=<br />
: These functions are used to create sound from written words. Check out our [[Special:MyLanguage/Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.<br />
<br />
=UI Functions=<br />
: 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.<br />
<br />
==ansi2decho PR# 5670 merge, PR5719 merged==<br />
;ansi2decho(text, default_colour)<br />
: Converts ANSI colour sequences in <code>text</code> to colour tags that can be processed by the decho() function.<br />
: See also: [[Manual:Lua_Functions#decho|decho()]]<br />
<br />
{{MudletVersion|3.0}}<br />
{{note}} ANSI bold is available since Mudlet 3.7.1+.<br />
<br />
{{note}} underline, italics, overline, and strikethrough supported since Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: String that contains ANSI colour sequences that should be replaced.<br />
* ''default_colour:''<br />
: Optional - ANSI default colour code (used when handling orphan bold tags).<br />
<br />
;Return values<br />
* ''string text:''<br />
: The decho-valid converted text.<br />
* ''string colour:''<br />
: The ANSI code for the last used colour in the substitution (useful if you want to colour subsequent lines according to this colour).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local replaced = ansi2decho('\27[0;1;36;40mYou say in a baritone voice, "Test."\27[0;37;40m')<br />
-- 'replaced' should now contain <r><0,255,255:0,0,0>You say in a baritone voice, "Test."<r><192,192,192:0,0,0><br />
decho(replaced)<br />
</syntaxhighlight><br />
<br />
Or show a complete colourful squirrel! It's a lotta code to do all the colours, so click the '''Expand''' button on the right to show it:<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<syntaxhighlight lang="lua"><br />
decho(ansi2decho([[<br />
�[38;5;95m▄�[48;5;95;38;5;130m▄▄▄�[38;5;95m█�[49m▀�[0m �[0m<br />
╭───────────────────────╮ �[38;5;95m▄▄�[0m �[38;5;95m▄�[48;5;95;38;5;130m▄▄�[48;5;130m█�[38;5;137m▄�[48;5;137;38;5;95m▄�[49m▀�[0m �[0m<br />
│ │ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄▄▄�[48;5;95;38;5;137m▄▄▄�[49;38;5;95m▄▄�[48;5;95;38;5;130m▄�[48;5;130m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[0m �[0m<br />
│ Encrypt everything! │ �[38;5;95m▄�[48;5;187;38;5;16m▄�[48;5;16;38;5;187m▄�[38;5;16m█�[48;5;137;38;5;137m███�[38;5;187m▄�[38;5;16m▄▄�[38;5;137m██�[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[0m �[0m<br />
│ ├──── �[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;16m▄▄▄�[48;5;137m███�[48;5;16;38;5;16m█�[48;5;187m▄�[48;5;16m█�[48;5;137;38;5;137m█�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
╰───────────────────────╯ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;16m▄�[38;5;16m█�[38;5;137m▄�[48;5;137m██████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;95m▀�[48;5;137m▄�[38;5;137m███████�[38;5;95m▄�[49m▀�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[48;5;95;38;5;187m▄▄▄�[38;5;137m▄�[48;5;137m██�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[38;5;95m▀�[48;5;130m▄�[38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;187m████�[48;5;137;38;5;137m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m██�[38;5;95m▄�[38;5;137m█�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;187;38;5;187m████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95m██�[48;5;137m▄▄�[48;5;187;38;5;187m████�[48;5;137;38;5;95m▄▄�[48;5;95;38;5;137m▄�[48;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;187;38;5;187m███�[48;5;95m▄�[38;5;137m▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[49m▄�[48;5;95;38;5;130m▄�[48;5;130m██████�[48;5;137;38;5;137m███�[38;5;95m▄�[49m▀�[0m�[0m<br />
�[48;5;187;38;5;95m▄�[38;5;187m████�[48;5;137;38;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m█████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;137m▄�[38;5;187m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██████�[48;5;95m▄▄�[48;5;130m▄▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▄▄▄�[48;5;95;38;5;137m▄�[48;5;187m▄�[38;5;187m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m█████�[38;5;95m▄�[38;5;137m███████████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀�[48;5;187m▄▄▄�[48;5;95;38;5;137m▄�[48;5;137m██�[38;5;95m▄�[49m▀�[0m �[38;5;95m▀▀�[48;5;137m▄▄▄▄▄▄�[49m▀▀▀�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀▀�[0m �[0m<br />
]]))<br />
</syntaxhighlight><br />
</div><br />
<br />
[[File:Squirrel-in-Mudlet.png|frameless]]<br />
<br />
==cecho PR #5669 merged, PR5719 merged, PR5751 merged==<br />
;cecho([window], text)<br />
: Echoes text that can be easily formatted with colour, italics, bold, strikethrough, and underline tags. You can also include unicode art in it - try some examples from [http://1lineart.kulaone.com/#/ 1lineart].<br />
: See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:UI Functions#creplaceLine|creplaceLine()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you cecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''window:''<br />
: Optional - the window name to echo to - can either be none or "main" for the main window, or a miniconsole, userwindow, or label name.<br />
* ''text:''<br />
: The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
cecho("Hi! This text is <red>red, <blue>blue, <green> and green.")<br />
<br />
cecho("<:green>Green background on normal foreground. Here we add an <ivory>ivory foreground.")<br />
<br />
cecho("<blue:yellow>Blue on yellow text!")<br />
<br />
cecho("\n<red>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, <o>overline</o>, and <b>bold</b>.")<br />
<br />
cecho("\n<green><o><u>Green text with over and underline at the same time.</o></u>")<br />
<br />
-- \n adds a new line<br />
cecho("<red>one line\n<green>another line\n<blue>last line")<br />
<br />
cecho("myinfo", "<green>All of this text is green in the myinfo miniconsole.")<br />
<br />
cecho("<green>(╯°□°)<dark_green>╯︵ ┻━┻")<br />
<br />
cecho("°º¤ø,¸¸,ø¤º°`°º¤ø,¸,ø¤°º¤ø,¸¸,ø¤º°`°º¤ø,¸")<br />
<br />
cecho([[<br />
██╗ ██╗ ██╗███╗ ██╗███████╗ █████╗ ██████╗ ████████╗<br />
███║ ██║ ██║████╗ ██║██╔════╝ ██╔══██╗██╔══██╗╚══██╔══╝<br />
╚██║ ██║ ██║██╔██╗ ██║█████╗ ███████║██████╔╝ ██║<br />
██║ ██║ ██║██║╚██╗██║██╔══╝ ██╔══██║██╔══██╗ ██║<br />
██║ ███████╗██║██║ ╚████║███████╗ ██║ ██║██║ ██║ ██║<br />
╚═╝ ╚══════╝╚═╝╚═╝ ╚═══╝╚══════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝<br />
]])<br />
</syntaxhighlight><br />
<br />
==cecho2ansi PR# 5672 merged==<br />
<br />
; ansiFormattedString = cecho2ansi(text)<br />
<br />
:Converts cecho formatted text to ansi formatted text. Used by cfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:Lua_Functions#cfeedTriggers|cfeedTriggers()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
{{note}} This function uses the ansi short colors (0-15) for color names which have base 16 ansi equivalents, such as 'red', 'blue', "lightBlue", "cyan", etc rather than the values defined in the color_table. If there is no base ansi equivalent then it will use the rgb values from the color_table for the color.<br />
<br />
;Parameters<br />
* ''text:''<br />
: The cecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of cfeedTriggers() for a single line.<br />
-- you would most likely just use cfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(cecho2ansi("\n<red>This is red.<reset> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
==decho PR #5669 merged PR5719 merged PR5751 merged==<br />
;decho ([name of console,] text)<br />
: Color changes can be made using the format <FR,FG,FB:BR,BG,BB,[BA]> where each field is a number from 0 to 255. The background portion can be omitted using <FR,FG,FB> or the foreground portion can be omitted using <:BR,BG,BB,[BA]>. Arguments 2 and 3 set the default fore and background colors for the string using the same format as is used within the string, sans angle brackets, e.g. ''decho("<50,50,0:0,255,0>test")''.<br />
:You can also include <code><nowiki><i>italics</i></nowiki></code>, <code><nowiki><b>bold</b></nowiki></code>, <code><nowiki><s>strikethrough</s></nowiki></code>, <code><nowiki><o>overline</o></nowiki></code>, and <code><nowiki><u>underline</u></nowiki></code> tags.<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you decho it will erase any previous echo sent to the label.<br />
<br />
: See also: [[#cecho|cecho()]], [[#hecho|hecho()]], [[#copy2decho|copy2decho()]]<br />
<br />
;Parameters<br />
* ''name of console''<br />
: (Optional) Name of the console to echo to. If no name is given, this will defaults to the main window.<br />
* ''text:''<br />
: The text that you’d like to echo with embedded color tags. Tags take the RGB values only, see below for an explanation.<br />
<br />
<br />
{{note}}<br />
Optional background transparancy parameter (BA) available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
decho("<50,50,0:0,255,0>test")<br />
<br />
decho("miniconsolename", "<50,50,0:0,255,0>test")<br />
<br />
decho("\n<255,0,0>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, and <b>bold</b> formatting.")<br />
<br />
decho("<\n<0,128,0><o><u>Green text with both over and underlines.</u></o>")<br />
</syntaxhighlight><br />
<br />
==decho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = decho2ansi(text)<br />
<br />
:Converts decho formatted text to ansi formatted text. Used by dfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#dfeedTriggers|dfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The decho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of dfeedTriggers() for a single line.<br />
-- you would most likely just use dfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(decho2ansi("\n<128,0,0>This is red.<r> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
==getHTMLformat PR#5751 merged==<br />
<br />
; spanTag = getHTMLformat(formatTable)<br />
<br />
:Takes in a table of formatting options in the same style as [[Manual:Lua_Functions#getTextFormat|getTextFormat()]] and returns a span tag which will format text after it as the table describes.<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formatTable:''<br />
: Table with formatting options configured. Keys are foreground, background, bold, underline, overline, strikeout, italic, and reverse. All except for foreground and background should be boolean (true/false) values. Foreground and background are either { r, g, b, a } tables, or strings with QSS formatting directives<br />
<br />
;Returns <br />
* A string with the html span tag to format text in accordance with the format table.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Returns a span tag for bold, red text on a green background<br />
local span = getHTMLformat({<br />
foreground = { 255, 0, 0 },<br />
background = "#00FF00",<br />
bold = true<br />
})<br />
<br />
-- span will be '<span style="color: rgb(255, 0, 0);background-color: #00FF00; font-weight: bold; font-style: normal; text-decoration: none;">'<br />
</syntaxhighlight><br />
<br />
==getLabelFormat PR#5751 merged==<br />
<br />
; formatTable = getLabelFormat(labelName)<br />
<br />
:Returns a format table like the one returned by getTextFormat and suitable for getHTMLspan which will format text the same way as simply doing an echo to the label would<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getHTMLspan|getHTMLspan()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: The name of the label to scan the format of<br />
<br />
;Returns <br />
* A table with all the formatting options to achieve a default text format for label labelName. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- creates a test label, sets a stylesheet, and then returns the default format table for that label.<br />
createLabel("testLabel", 10, 10, 300, 200, 1)<br />
setLabelStyleSheet([[<br />
color: rgb(0,0,180);<br />
border-width: 1px;<br />
border-style: solid;<br />
border-color: gold;<br />
border-radius: 10px;<br />
font-size: 12.0pt;<br />
background: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #98f041, stop: 0.1 #8cf029, stop: 0.49 #66cc00, stop: 0.5 #52a300, stop: 1 #66cc00);<br />
]])<br />
local fmt = getLabelFormat("testLabel"))<br />
<br />
--[[<br />
{<br />
background = "rgba(0, 0, 0, 0)", -- this is transparent<br />
bold = false,<br />
foreground = "rgb(0,0,180)",<br />
italic = false,<br />
overline = false,<br />
reverse = false,<br />
strikeout = false,<br />
underline = false<br />
}<br />
--]]<br />
<br />
</syntaxhighlight><br />
<br />
==hecho PR #5669 merged, PR5719 merged, PR5751 merged==<br />
;hecho([windowName], text)<br />
: Echoes text that can be easily formatted with colour tags in the hexadecimal format. You can also use italics, bold, strikethrough, and underline tags.<br />
: See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#cecho|cecho()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you hecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Can either be omitted or "main" for the main window, else specify the miniconsoles name.<br />
* ''text:''<br />
: The text to display, with color changes made within the string using the format |cFRFGFB,BRBGBB or #FRFGFB,BRBGBB where FR is the foreground red value, FG is the foreground green value, FB is the foreground blue value, BR is the background red value, etc., BRBGBB is optional. |r or #r can be used within the string to reset the colors to default. Hexadecimal color codes can be found here: https://www.color-hex.com/<br />
<br />
{{note}}<br />
Transparency for background in hex-format available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
hecho("\n#ffffff White text!")<br />
-- your text in white<br />
hecho("\n#ca0004 Red text! And now reset #rit to the default color")<br />
-- your text in red, then reset to default using #r<br />
hecho("\n#ffffff,ca0004 White text with a red background!")<br />
-- your text in white, against a red background<br />
hecho("\n|c0000ff Blue text, this time using |c instead of #")<br />
-- your text in blue, activated with |c vs #.<br />
hecho("\n#ff0000Red text with #iitalics#/i, |uunderline|/u, #ooverline#/o, #sstrikethrough#/s, and #bbold#/b formatting.")<br />
-- shows the various individual formatting options<br />
hecho("\n#008000#o#uGreen text with both over and underlines.#/o#/u")<br />
</syntaxhighlight><br />
<br />
==hecho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = hecho2ansi(text)<br />
<br />
:Converts hecho formatted text to ansi formatted text. Used by hfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:Lua_Functions#hfeedTriggers|hfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The hecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of hfeedTriggers() for a single line.<br />
-- you would most likely just use hfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(hecho2ansi("\n#800000This is red.#r #iitalic#/i, #bbold#/b, #sstrikethrough#/s, #uunderline#/u\n"))<br />
</syntaxhighlight><br />
<br />
==windowType PR# 5696 open==<br />
; typeOfWindow = windowType(windowName)<br />
<br />
:Given the name of a window, will return if it's a label, miniconsole, userwindow or a commandline.<br />
<br />
;See also: [[Manual:Lua_Functions#createLabel|createLabel()]], [[Manual:Lua_Functions#openUserWindow|openUserWindow()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name used to create the window element. Use "main" for the main console<br />
<br />
<br />
;Returns <br />
* Window type as string ("label", "miniconsole", "userwindow", or "commandline") or nil+error if it does not exist.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a Geyser label and and check its type<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
display(windowType(testLabel.name)) -- displays "label"<br />
<br />
-- the main console returns "miniconsole" because it uses the same formatting functions<br />
display(windowType("main")) -- displays "miniconsole"<br />
<br />
-- check for the existence of a window<br />
local windowName = "this thing does not exist"<br />
local ok, err = windowType(windowName)<br />
if ok then<br />
-- do things with it, as it does exist.<br />
-- the ok variable will hold the type of window it is ("label", "commandline", etc)<br />
else<br />
cecho("<red>ALERT!! window does not exist")<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
=Discord Functions=<br />
: 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 [[Special:MyLanguage/Manual:Scripting#Discord_Rich_Presence|Discord scripting overview]].</div>Demonnichttps://wiki.mudlet.org/index.php?title=Area_51&diff=18601Area 512022-01-02T17:21:50Z<p>Demonnic: /* getLabelFormat PR#5751 open */</p>
<hr />
<div>{{TOC right}}<br />
<br />
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 [[Manual:Lua_Functions|Lua Functions]] and its sub-sites. <br />
<br />
Please use the [[Area_51/Template]] to add new entries in the sections below.<br />
<br />
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.<br />
<br />
<br />
=Basic Essential Functions=<br />
:These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.<br />
<br />
=Database Functions=<br />
:A collection of functions for helping deal with the database.<br />
<br />
=Date/Time Functions=<br />
: A collection of functions for handling date & time.<br />
<br />
=File System Functions=<br />
: A collection of functions for interacting with the file system.<br />
<br />
=Mapper Functions=<br />
: A collection of functions that manipulate the mapper and its related features.<br />
<br />
==mapSymbolFontInfo, PR #4038 closed==<br />
;mapSymbolFontInfo()<br />
: See also: [[#setupMapSymbolFont|setupMapSymbolFont()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;returns<br />
* either a table of information about the configuration of the font used for symbols in the (2D) map, the elements are:<br />
:* ''fontName'' - a string of the family name of the font specified<br />
:* ''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.<br />
:* ''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).<br />
* or ''nil'' and an error message on failure.<br />
<br />
::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).<br />
<br />
<br />
==setupMapSymbolFont, PR #4038 closed==<br />
;setupMapSymbolFont(fontName[, onlyUseThisFont[, scalingFactor]])<br />
:configures the font used for symbols in the (2D) map.<br />
: See also: [[#mapSymbolFontInfo|mapSymbolFontInfo()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;Parameters<br />
* ''fontName'' one of:<br />
:* - a string that is the family name of the font to use;<br />
:* - the empty string ''""'' to reset to the default {which is '''"Bitstream Vera Sans Mono"'''};<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow a following one to be modified.<br />
* ''onlyUseThisFont'' (optional) one of:<br />
:* - 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;<br />
:* - 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;<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow the following one to be modified.<br />
* ''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.<br />
<br />
;Returns<br />
* ''true'' on success<br />
* ''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).<br />
<br />
=Miscellaneous Functions=<br />
: Miscellaneous functions.<br />
<br />
==getCharacterName, PR #3952 open==<br />
;getCharacterName()<br />
<br />
: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.<br />
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.<br />
<br />
:See also: [[#sendCharacterName|sendCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lua send("cast 'glamor' " .. getCharacterName())<br />
<br />
You get a warm feeling passing from your core to the tips of your hands, feet and other body parts.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A tawny long-haired cat saunters over and start to rub itself against your ankles.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A mangy dog trots up to you and proceeds to mark the bottom of your leggings.<br />
</syntaxhighlight><br />
<br />
==getCustomLoginTextId, PR #3952 open==<br />
;getCustomLoginTextId()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#sendPassword|sendPassword()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCharacterName, PR #3952 open==<br />
;sendCharacterName()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
==sendCharacterPassword, PR #3952 open==<br />
;sendCharacterPassword()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]], [[#sendCharacterName|sendCharacterName()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCharacterName() ~= "" then<br />
tempTime(2.0, [[sendCharacterName()]], 1)<br />
tempTime(3.0, [[sendCharacterPassword()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCustomLoginText, PR #3952 open==<br />
;sendCustomLoginText()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendPassword|sendPassword()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
=Mudlet Object Functions=<br />
: A collection of functions that manipulate Mudlets scripting objects - triggers, aliases, and so forth.<br />
<br />
=Networking Functions=<br />
: A collection of functions for managing networking.<br />
<br />
=String Functions=<br />
: These functions are used to manipulate strings.<br />
<br />
==string.patternEscape, utf8.patternEscape PR 5806==<br />
; escapedString = string.patternEscape(str) or escapedString = utf8.patternEscape(str)<br />
<br />
: Returns a version of str with all Lua pattern characters escaped to ensure string.match/find/etc look for the original str.<br />
<br />
;See also: [[Manual:Lua_Functions#string.trim|string.trim()]], [[Manual:Lua_Functions#string.genNocasePattern|string.genNocasePattern()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''str:''<br />
: The string to escape lua pattern characters in.<br />
<br />
;Returns <br />
* The string with all special Lua pattern characters escaped. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- searching for a url inside of a string. <br />
local helpString = [[<br />
This feature can be accessed by going to https://some-url.com/athing.html?param=value and<br />
retrieving the result!<br />
]]<br />
local url = "https://some-url.com/"<br />
display(helpString:find(url))<br />
-- nil<br />
display(helpString:find(string.patternEscape(url)))<br />
-- 42<br />
-- 62<br />
display(url:patternEscape())<br />
-- "https://some%-url%.com/"<br />
</syntaxhighlight><br />
<br />
=Table Functions=<br />
: 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.<br />
<br />
=Text to Speech Functions=<br />
: These functions are used to create sound from written words. Check out our [[Special:MyLanguage/Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.<br />
<br />
=UI Functions=<br />
: 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.<br />
<br />
==ansi2decho PR# 5670 merge, PR5719 merged==<br />
;ansi2decho(text, default_colour)<br />
: Converts ANSI colour sequences in <code>text</code> to colour tags that can be processed by the decho() function.<br />
: See also: [[Manual:Lua_Functions#decho|decho()]]<br />
<br />
{{MudletVersion|3.0}}<br />
{{note}} ANSI bold is available since Mudlet 3.7.1+.<br />
<br />
{{note}} underline, italics, overline, and strikethrough supported since Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: String that contains ANSI colour sequences that should be replaced.<br />
* ''default_colour:''<br />
: Optional - ANSI default colour code (used when handling orphan bold tags).<br />
<br />
;Return values<br />
* ''string text:''<br />
: The decho-valid converted text.<br />
* ''string colour:''<br />
: The ANSI code for the last used colour in the substitution (useful if you want to colour subsequent lines according to this colour).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local replaced = ansi2decho('\27[0;1;36;40mYou say in a baritone voice, "Test."\27[0;37;40m')<br />
-- 'replaced' should now contain <r><0,255,255:0,0,0>You say in a baritone voice, "Test."<r><192,192,192:0,0,0><br />
decho(replaced)<br />
</syntaxhighlight><br />
<br />
Or show a complete colourful squirrel! It's a lotta code to do all the colours, so click the '''Expand''' button on the right to show it:<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<syntaxhighlight lang="lua"><br />
decho(ansi2decho([[<br />
�[38;5;95m▄�[48;5;95;38;5;130m▄▄▄�[38;5;95m█�[49m▀�[0m �[0m<br />
╭───────────────────────╮ �[38;5;95m▄▄�[0m �[38;5;95m▄�[48;5;95;38;5;130m▄▄�[48;5;130m█�[38;5;137m▄�[48;5;137;38;5;95m▄�[49m▀�[0m �[0m<br />
│ │ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄▄▄�[48;5;95;38;5;137m▄▄▄�[49;38;5;95m▄▄�[48;5;95;38;5;130m▄�[48;5;130m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[0m �[0m<br />
│ Encrypt everything! │ �[38;5;95m▄�[48;5;187;38;5;16m▄�[48;5;16;38;5;187m▄�[38;5;16m█�[48;5;137;38;5;137m███�[38;5;187m▄�[38;5;16m▄▄�[38;5;137m██�[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[0m �[0m<br />
│ ├──── �[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;16m▄▄▄�[48;5;137m███�[48;5;16;38;5;16m█�[48;5;187m▄�[48;5;16m█�[48;5;137;38;5;137m█�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
╰───────────────────────╯ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;16m▄�[38;5;16m█�[38;5;137m▄�[48;5;137m██████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;95m▀�[48;5;137m▄�[38;5;137m███████�[38;5;95m▄�[49m▀�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[48;5;95;38;5;187m▄▄▄�[38;5;137m▄�[48;5;137m██�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[38;5;95m▀�[48;5;130m▄�[38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;187m████�[48;5;137;38;5;137m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m██�[38;5;95m▄�[38;5;137m█�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;187;38;5;187m████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95m██�[48;5;137m▄▄�[48;5;187;38;5;187m████�[48;5;137;38;5;95m▄▄�[48;5;95;38;5;137m▄�[48;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;187;38;5;187m███�[48;5;95m▄�[38;5;137m▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[49m▄�[48;5;95;38;5;130m▄�[48;5;130m██████�[48;5;137;38;5;137m███�[38;5;95m▄�[49m▀�[0m�[0m<br />
�[48;5;187;38;5;95m▄�[38;5;187m████�[48;5;137;38;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m█████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;137m▄�[38;5;187m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██████�[48;5;95m▄▄�[48;5;130m▄▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▄▄▄�[48;5;95;38;5;137m▄�[48;5;187m▄�[38;5;187m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m█████�[38;5;95m▄�[38;5;137m███████████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀�[48;5;187m▄▄▄�[48;5;95;38;5;137m▄�[48;5;137m██�[38;5;95m▄�[49m▀�[0m �[38;5;95m▀▀�[48;5;137m▄▄▄▄▄▄�[49m▀▀▀�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀▀�[0m �[0m<br />
]]))<br />
</syntaxhighlight><br />
</div><br />
<br />
[[File:Squirrel-in-Mudlet.png|frameless]]<br />
<br />
==cecho PR #5669 merged, PR5719 merged, PR5751 merged==<br />
;cecho([window], text)<br />
: Echoes text that can be easily formatted with colour, italics, bold, strikethrough, and underline tags. You can also include unicode art in it - try some examples from [http://1lineart.kulaone.com/#/ 1lineart].<br />
: See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:UI Functions#creplaceLine|creplaceLine()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you cecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''window:''<br />
: Optional - the window name to echo to - can either be none or "main" for the main window, or a miniconsole, userwindow, or label name.<br />
* ''text:''<br />
: The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
cecho("Hi! This text is <red>red, <blue>blue, <green> and green.")<br />
<br />
cecho("<:green>Green background on normal foreground. Here we add an <ivory>ivory foreground.")<br />
<br />
cecho("<blue:yellow>Blue on yellow text!")<br />
<br />
cecho("\n<red>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, <o>overline</o>, and <b>bold</b>.")<br />
<br />
cecho("\n<green><o><u>Green text with over and underline at the same time.</o></u>")<br />
<br />
-- \n adds a new line<br />
cecho("<red>one line\n<green>another line\n<blue>last line")<br />
<br />
cecho("myinfo", "<green>All of this text is green in the myinfo miniconsole.")<br />
<br />
cecho("<green>(╯°□°)<dark_green>╯︵ ┻━┻")<br />
<br />
cecho("°º¤ø,¸¸,ø¤º°`°º¤ø,¸,ø¤°º¤ø,¸¸,ø¤º°`°º¤ø,¸")<br />
<br />
cecho([[<br />
██╗ ██╗ ██╗███╗ ██╗███████╗ █████╗ ██████╗ ████████╗<br />
███║ ██║ ██║████╗ ██║██╔════╝ ██╔══██╗██╔══██╗╚══██╔══╝<br />
╚██║ ██║ ██║██╔██╗ ██║█████╗ ███████║██████╔╝ ██║<br />
██║ ██║ ██║██║╚██╗██║██╔══╝ ██╔══██║██╔══██╗ ██║<br />
██║ ███████╗██║██║ ╚████║███████╗ ██║ ██║██║ ██║ ██║<br />
╚═╝ ╚══════╝╚═╝╚═╝ ╚═══╝╚══════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝<br />
]])<br />
</syntaxhighlight><br />
<br />
==cecho2ansi PR# 5672 merged==<br />
<br />
; ansiFormattedString = cecho2ansi(text)<br />
<br />
:Converts cecho formatted text to ansi formatted text. Used by cfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:Lua_Functions#cfeedTriggers|cfeedTriggers()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
{{note}} This function uses the ansi short colors (0-15) for color names which have base 16 ansi equivalents, such as 'red', 'blue', "lightBlue", "cyan", etc rather than the values defined in the color_table. If there is no base ansi equivalent then it will use the rgb values from the color_table for the color.<br />
<br />
;Parameters<br />
* ''text:''<br />
: The cecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of cfeedTriggers() for a single line.<br />
-- you would most likely just use cfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(cecho2ansi("\n<red>This is red.<reset> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
==decho PR #5669 merged PR5719 merged PR5751 merged==<br />
;decho ([name of console,] text)<br />
: Color changes can be made using the format <FR,FG,FB:BR,BG,BB,[BA]> where each field is a number from 0 to 255. The background portion can be omitted using <FR,FG,FB> or the foreground portion can be omitted using <:BR,BG,BB,[BA]>. Arguments 2 and 3 set the default fore and background colors for the string using the same format as is used within the string, sans angle brackets, e.g. ''decho("<50,50,0:0,255,0>test")''.<br />
:You can also include <code><nowiki><i>italics</i></nowiki></code>, <code><nowiki><b>bold</b></nowiki></code>, <code><nowiki><s>strikethrough</s></nowiki></code>, <code><nowiki><o>overline</o></nowiki></code>, and <code><nowiki><u>underline</u></nowiki></code> tags.<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you decho it will erase any previous echo sent to the label.<br />
<br />
: See also: [[#cecho|cecho()]], [[#hecho|hecho()]], [[#copy2decho|copy2decho()]]<br />
<br />
;Parameters<br />
* ''name of console''<br />
: (Optional) Name of the console to echo to. If no name is given, this will defaults to the main window.<br />
* ''text:''<br />
: The text that you’d like to echo with embedded color tags. Tags take the RGB values only, see below for an explanation.<br />
<br />
<br />
{{note}}<br />
Optional background transparancy parameter (BA) available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
decho("<50,50,0:0,255,0>test")<br />
<br />
decho("miniconsolename", "<50,50,0:0,255,0>test")<br />
<br />
decho("\n<255,0,0>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, and <b>bold</b> formatting.")<br />
<br />
decho("<\n<0,128,0><o><u>Green text with both over and underlines.</u></o>")<br />
</syntaxhighlight><br />
<br />
==decho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = decho2ansi(text)<br />
<br />
:Converts decho formatted text to ansi formatted text. Used by dfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#dfeedTriggers|dfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The decho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of dfeedTriggers() for a single line.<br />
-- you would most likely just use dfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(decho2ansi("\n<128,0,0>This is red.<r> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
==getHTMLformat PR#5751 merged==<br />
<br />
; spanTag = getHTMLformat(formatTable)<br />
<br />
:Takes in a table of formatting options in the same style as [[Manual:Lua_Functions#getTextFormat|getTextFormat()]] and returns a span tag which will format text after it as the table describes.<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formatTable:''<br />
: Table with formatting options configured. Keys are foreground, background, bold, underline, overline, strikeout, italic, and reverse. All except for foreground and background should be boolean (true/false) values. Foreground and background are either { r, g, b, a } tables, or strings with QSS formatting directives<br />
<br />
;Returns <br />
* A string with the html span tag to format text in accordance with the format table.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Returns a span tag for bold, red text on a green background<br />
local span = getHTMLformat({<br />
foreground = { 255, 0, 0 },<br />
background = "#00FF00",<br />
bold = true<br />
})<br />
<br />
-- span will be '<span style="color: rgb(255, 0, 0);background-color: #00FF00; font-weight: bold; font-style: normal; text-decoration: none;">'<br />
</syntaxhighlight><br />
<br />
==getLabelFormat PR#5751 merged==<br />
<br />
; formatTable = getLabelFormat(labelName)<br />
<br />
:Returns a format table like the one returned by getTextFormat and suitable for getHTMLspan which will format text the same way as simply doing an echo to the label would<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getHTMLspan|getHTMLspan()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: The name of the label to scan the format of<br />
<br />
;Returns <br />
* A table with all the formatting options to achieve a default text format for label labelName. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- creates a test label, sets a stylesheet, and then returns the default format table for that label.<br />
createLabel("testLabel", 10, 10, 300, 200, 1)<br />
setLabelStyleSheet([[<br />
color: rgb(0,0,180);<br />
border-width: 1px;<br />
border-style: solid;<br />
border-color: gold;<br />
border-radius: 10px;<br />
font-size: 12.0pt;<br />
background: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #98f041, stop: 0.1 #8cf029, stop: 0.49 #66cc00, stop: 0.5 #52a300, stop: 1 #66cc00);<br />
]])<br />
local fmt = getLabelFormat("testLabel"))<br />
<br />
--[[<br />
{<br />
background = "rgba(0, 0, 0, 0)", -- this is transparent<br />
bold = false,<br />
foreground = "rgb(0,0,180)",<br />
italic = false,<br />
overline = false,<br />
reverse = false,<br />
strikeout = false,<br />
underline = false<br />
}<br />
--]]<br />
<br />
</syntaxhighlight><br />
<br />
==hecho PR #5669 merged, PR5719 merged, PR5751 open==<br />
;hecho([windowName], text)<br />
: Echoes text that can be easily formatted with colour tags in the hexadecimal format. You can also use italics, bold, strikethrough, and underline tags.<br />
: See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#cecho|cecho()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you hecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Can either be omitted or "main" for the main window, else specify the miniconsoles name.<br />
* ''text:''<br />
: The text to display, with color changes made within the string using the format |cFRFGFB,BRBGBB or #FRFGFB,BRBGBB where FR is the foreground red value, FG is the foreground green value, FB is the foreground blue value, BR is the background red value, etc., BRBGBB is optional. |r or #r can be used within the string to reset the colors to default. Hexadecimal color codes can be found here: https://www.color-hex.com/<br />
<br />
{{note}}<br />
Transparency for background in hex-format available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
hecho("\n#ffffff White text!")<br />
-- your text in white<br />
hecho("\n#ca0004 Red text! And now reset #rit to the default color")<br />
-- your text in red, then reset to default using #r<br />
hecho("\n#ffffff,ca0004 White text with a red background!")<br />
-- your text in white, against a red background<br />
hecho("\n|c0000ff Blue text, this time using |c instead of #")<br />
-- your text in blue, activated with |c vs #.<br />
hecho("\n#ff0000Red text with #iitalics#/i, |uunderline|/u, #ooverline#/o, #sstrikethrough#/s, and #bbold#/b formatting.")<br />
-- shows the various individual formatting options<br />
hecho("\n#008000#o#uGreen text with both over and underlines.#/o#/u")<br />
</syntaxhighlight><br />
<br />
==hecho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = hecho2ansi(text)<br />
<br />
:Converts hecho formatted text to ansi formatted text. Used by hfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:Lua_Functions#hfeedTriggers|hfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The hecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of hfeedTriggers() for a single line.<br />
-- you would most likely just use hfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(hecho2ansi("\n#800000This is red.#r #iitalic#/i, #bbold#/b, #sstrikethrough#/s, #uunderline#/u\n"))<br />
</syntaxhighlight><br />
<br />
==windowType PR# 5696 open==<br />
; typeOfWindow = windowType(windowName)<br />
<br />
:Given the name of a window, will return if it's a label, miniconsole, userwindow or a commandline.<br />
<br />
;See also: [[Manual:Lua_Functions#createLabel|createLabel()]], [[Manual:Lua_Functions#openUserWindow|openUserWindow()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name used to create the window element. Use "main" for the main console<br />
<br />
<br />
;Returns <br />
* Window type as string ("label", "miniconsole", "userwindow", or "commandline") or nil+error if it does not exist.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a Geyser label and and check its type<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
display(windowType(testLabel.name)) -- displays "label"<br />
<br />
-- the main console returns "miniconsole" because it uses the same formatting functions<br />
display(windowType("main")) -- displays "miniconsole"<br />
<br />
-- check for the existence of a window<br />
local windowName = "this thing does not exist"<br />
local ok, err = windowType(windowName)<br />
if ok then<br />
-- do things with it, as it does exist.<br />
-- the ok variable will hold the type of window it is ("label", "commandline", etc)<br />
else<br />
cecho("<red>ALERT!! window does not exist")<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
=Discord Functions=<br />
: 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 [[Special:MyLanguage/Manual:Scripting#Discord_Rich_Presence|Discord scripting overview]].</div>Demonnichttps://wiki.mudlet.org/index.php?title=Area_51&diff=18600Area 512022-01-02T17:21:38Z<p>Demonnic: /* getHTMLformat PR#5751 open */</p>
<hr />
<div>{{TOC right}}<br />
<br />
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 [[Manual:Lua_Functions|Lua Functions]] and its sub-sites. <br />
<br />
Please use the [[Area_51/Template]] to add new entries in the sections below.<br />
<br />
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.<br />
<br />
<br />
=Basic Essential Functions=<br />
:These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.<br />
<br />
=Database Functions=<br />
:A collection of functions for helping deal with the database.<br />
<br />
=Date/Time Functions=<br />
: A collection of functions for handling date & time.<br />
<br />
=File System Functions=<br />
: A collection of functions for interacting with the file system.<br />
<br />
=Mapper Functions=<br />
: A collection of functions that manipulate the mapper and its related features.<br />
<br />
==mapSymbolFontInfo, PR #4038 closed==<br />
;mapSymbolFontInfo()<br />
: See also: [[#setupMapSymbolFont|setupMapSymbolFont()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;returns<br />
* either a table of information about the configuration of the font used for symbols in the (2D) map, the elements are:<br />
:* ''fontName'' - a string of the family name of the font specified<br />
:* ''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.<br />
:* ''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).<br />
* or ''nil'' and an error message on failure.<br />
<br />
::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).<br />
<br />
<br />
==setupMapSymbolFont, PR #4038 closed==<br />
;setupMapSymbolFont(fontName[, onlyUseThisFont[, scalingFactor]])<br />
:configures the font used for symbols in the (2D) map.<br />
: See also: [[#mapSymbolFontInfo|mapSymbolFontInfo()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;Parameters<br />
* ''fontName'' one of:<br />
:* - a string that is the family name of the font to use;<br />
:* - the empty string ''""'' to reset to the default {which is '''"Bitstream Vera Sans Mono"'''};<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow a following one to be modified.<br />
* ''onlyUseThisFont'' (optional) one of:<br />
:* - 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;<br />
:* - 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;<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow the following one to be modified.<br />
* ''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.<br />
<br />
;Returns<br />
* ''true'' on success<br />
* ''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).<br />
<br />
=Miscellaneous Functions=<br />
: Miscellaneous functions.<br />
<br />
==getCharacterName, PR #3952 open==<br />
;getCharacterName()<br />
<br />
: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.<br />
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.<br />
<br />
:See also: [[#sendCharacterName|sendCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lua send("cast 'glamor' " .. getCharacterName())<br />
<br />
You get a warm feeling passing from your core to the tips of your hands, feet and other body parts.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A tawny long-haired cat saunters over and start to rub itself against your ankles.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A mangy dog trots up to you and proceeds to mark the bottom of your leggings.<br />
</syntaxhighlight><br />
<br />
==getCustomLoginTextId, PR #3952 open==<br />
;getCustomLoginTextId()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#sendPassword|sendPassword()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCharacterName, PR #3952 open==<br />
;sendCharacterName()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
==sendCharacterPassword, PR #3952 open==<br />
;sendCharacterPassword()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]], [[#sendCharacterName|sendCharacterName()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCharacterName() ~= "" then<br />
tempTime(2.0, [[sendCharacterName()]], 1)<br />
tempTime(3.0, [[sendCharacterPassword()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCustomLoginText, PR #3952 open==<br />
;sendCustomLoginText()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendPassword|sendPassword()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
=Mudlet Object Functions=<br />
: A collection of functions that manipulate Mudlets scripting objects - triggers, aliases, and so forth.<br />
<br />
=Networking Functions=<br />
: A collection of functions for managing networking.<br />
<br />
=String Functions=<br />
: These functions are used to manipulate strings.<br />
<br />
==string.patternEscape, utf8.patternEscape PR 5806==<br />
; escapedString = string.patternEscape(str) or escapedString = utf8.patternEscape(str)<br />
<br />
: Returns a version of str with all Lua pattern characters escaped to ensure string.match/find/etc look for the original str.<br />
<br />
;See also: [[Manual:Lua_Functions#string.trim|string.trim()]], [[Manual:Lua_Functions#string.genNocasePattern|string.genNocasePattern()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''str:''<br />
: The string to escape lua pattern characters in.<br />
<br />
;Returns <br />
* The string with all special Lua pattern characters escaped. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- searching for a url inside of a string. <br />
local helpString = [[<br />
This feature can be accessed by going to https://some-url.com/athing.html?param=value and<br />
retrieving the result!<br />
]]<br />
local url = "https://some-url.com/"<br />
display(helpString:find(url))<br />
-- nil<br />
display(helpString:find(string.patternEscape(url)))<br />
-- 42<br />
-- 62<br />
display(url:patternEscape())<br />
-- "https://some%-url%.com/"<br />
</syntaxhighlight><br />
<br />
=Table Functions=<br />
: 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.<br />
<br />
=Text to Speech Functions=<br />
: These functions are used to create sound from written words. Check out our [[Special:MyLanguage/Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.<br />
<br />
=UI Functions=<br />
: 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.<br />
<br />
==ansi2decho PR# 5670 merge, PR5719 merged==<br />
;ansi2decho(text, default_colour)<br />
: Converts ANSI colour sequences in <code>text</code> to colour tags that can be processed by the decho() function.<br />
: See also: [[Manual:Lua_Functions#decho|decho()]]<br />
<br />
{{MudletVersion|3.0}}<br />
{{note}} ANSI bold is available since Mudlet 3.7.1+.<br />
<br />
{{note}} underline, italics, overline, and strikethrough supported since Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: String that contains ANSI colour sequences that should be replaced.<br />
* ''default_colour:''<br />
: Optional - ANSI default colour code (used when handling orphan bold tags).<br />
<br />
;Return values<br />
* ''string text:''<br />
: The decho-valid converted text.<br />
* ''string colour:''<br />
: The ANSI code for the last used colour in the substitution (useful if you want to colour subsequent lines according to this colour).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local replaced = ansi2decho('\27[0;1;36;40mYou say in a baritone voice, "Test."\27[0;37;40m')<br />
-- 'replaced' should now contain <r><0,255,255:0,0,0>You say in a baritone voice, "Test."<r><192,192,192:0,0,0><br />
decho(replaced)<br />
</syntaxhighlight><br />
<br />
Or show a complete colourful squirrel! It's a lotta code to do all the colours, so click the '''Expand''' button on the right to show it:<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<syntaxhighlight lang="lua"><br />
decho(ansi2decho([[<br />
�[38;5;95m▄�[48;5;95;38;5;130m▄▄▄�[38;5;95m█�[49m▀�[0m �[0m<br />
╭───────────────────────╮ �[38;5;95m▄▄�[0m �[38;5;95m▄�[48;5;95;38;5;130m▄▄�[48;5;130m█�[38;5;137m▄�[48;5;137;38;5;95m▄�[49m▀�[0m �[0m<br />
│ │ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄▄▄�[48;5;95;38;5;137m▄▄▄�[49;38;5;95m▄▄�[48;5;95;38;5;130m▄�[48;5;130m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[0m �[0m<br />
│ Encrypt everything! │ �[38;5;95m▄�[48;5;187;38;5;16m▄�[48;5;16;38;5;187m▄�[38;5;16m█�[48;5;137;38;5;137m███�[38;5;187m▄�[38;5;16m▄▄�[38;5;137m██�[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[0m �[0m<br />
│ ├──── �[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;16m▄▄▄�[48;5;137m███�[48;5;16;38;5;16m█�[48;5;187m▄�[48;5;16m█�[48;5;137;38;5;137m█�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
╰───────────────────────╯ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;16m▄�[38;5;16m█�[38;5;137m▄�[48;5;137m██████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;95m▀�[48;5;137m▄�[38;5;137m███████�[38;5;95m▄�[49m▀�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[48;5;95;38;5;187m▄▄▄�[38;5;137m▄�[48;5;137m██�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[38;5;95m▀�[48;5;130m▄�[38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;187m████�[48;5;137;38;5;137m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m██�[38;5;95m▄�[38;5;137m█�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;187;38;5;187m████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95m██�[48;5;137m▄▄�[48;5;187;38;5;187m████�[48;5;137;38;5;95m▄▄�[48;5;95;38;5;137m▄�[48;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;187;38;5;187m███�[48;5;95m▄�[38;5;137m▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[49m▄�[48;5;95;38;5;130m▄�[48;5;130m██████�[48;5;137;38;5;137m███�[38;5;95m▄�[49m▀�[0m�[0m<br />
�[48;5;187;38;5;95m▄�[38;5;187m████�[48;5;137;38;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m█████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;137m▄�[38;5;187m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██████�[48;5;95m▄▄�[48;5;130m▄▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▄▄▄�[48;5;95;38;5;137m▄�[48;5;187m▄�[38;5;187m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m█████�[38;5;95m▄�[38;5;137m███████████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀�[48;5;187m▄▄▄�[48;5;95;38;5;137m▄�[48;5;137m██�[38;5;95m▄�[49m▀�[0m �[38;5;95m▀▀�[48;5;137m▄▄▄▄▄▄�[49m▀▀▀�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀▀�[0m �[0m<br />
]]))<br />
</syntaxhighlight><br />
</div><br />
<br />
[[File:Squirrel-in-Mudlet.png|frameless]]<br />
<br />
==cecho PR #5669 merged, PR5719 merged, PR5751 merged==<br />
;cecho([window], text)<br />
: Echoes text that can be easily formatted with colour, italics, bold, strikethrough, and underline tags. You can also include unicode art in it - try some examples from [http://1lineart.kulaone.com/#/ 1lineart].<br />
: See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:UI Functions#creplaceLine|creplaceLine()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you cecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''window:''<br />
: Optional - the window name to echo to - can either be none or "main" for the main window, or a miniconsole, userwindow, or label name.<br />
* ''text:''<br />
: The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
cecho("Hi! This text is <red>red, <blue>blue, <green> and green.")<br />
<br />
cecho("<:green>Green background on normal foreground. Here we add an <ivory>ivory foreground.")<br />
<br />
cecho("<blue:yellow>Blue on yellow text!")<br />
<br />
cecho("\n<red>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, <o>overline</o>, and <b>bold</b>.")<br />
<br />
cecho("\n<green><o><u>Green text with over and underline at the same time.</o></u>")<br />
<br />
-- \n adds a new line<br />
cecho("<red>one line\n<green>another line\n<blue>last line")<br />
<br />
cecho("myinfo", "<green>All of this text is green in the myinfo miniconsole.")<br />
<br />
cecho("<green>(╯°□°)<dark_green>╯︵ ┻━┻")<br />
<br />
cecho("°º¤ø,¸¸,ø¤º°`°º¤ø,¸,ø¤°º¤ø,¸¸,ø¤º°`°º¤ø,¸")<br />
<br />
cecho([[<br />
██╗ ██╗ ██╗███╗ ██╗███████╗ █████╗ ██████╗ ████████╗<br />
███║ ██║ ██║████╗ ██║██╔════╝ ██╔══██╗██╔══██╗╚══██╔══╝<br />
╚██║ ██║ ██║██╔██╗ ██║█████╗ ███████║██████╔╝ ██║<br />
██║ ██║ ██║██║╚██╗██║██╔══╝ ██╔══██║██╔══██╗ ██║<br />
██║ ███████╗██║██║ ╚████║███████╗ ██║ ██║██║ ██║ ██║<br />
╚═╝ ╚══════╝╚═╝╚═╝ ╚═══╝╚══════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝<br />
]])<br />
</syntaxhighlight><br />
<br />
==cecho2ansi PR# 5672 merged==<br />
<br />
; ansiFormattedString = cecho2ansi(text)<br />
<br />
:Converts cecho formatted text to ansi formatted text. Used by cfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:Lua_Functions#cfeedTriggers|cfeedTriggers()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
{{note}} This function uses the ansi short colors (0-15) for color names which have base 16 ansi equivalents, such as 'red', 'blue', "lightBlue", "cyan", etc rather than the values defined in the color_table. If there is no base ansi equivalent then it will use the rgb values from the color_table for the color.<br />
<br />
;Parameters<br />
* ''text:''<br />
: The cecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of cfeedTriggers() for a single line.<br />
-- you would most likely just use cfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(cecho2ansi("\n<red>This is red.<reset> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
==decho PR #5669 merged PR5719 merged PR5751 merged==<br />
;decho ([name of console,] text)<br />
: Color changes can be made using the format <FR,FG,FB:BR,BG,BB,[BA]> where each field is a number from 0 to 255. The background portion can be omitted using <FR,FG,FB> or the foreground portion can be omitted using <:BR,BG,BB,[BA]>. Arguments 2 and 3 set the default fore and background colors for the string using the same format as is used within the string, sans angle brackets, e.g. ''decho("<50,50,0:0,255,0>test")''.<br />
:You can also include <code><nowiki><i>italics</i></nowiki></code>, <code><nowiki><b>bold</b></nowiki></code>, <code><nowiki><s>strikethrough</s></nowiki></code>, <code><nowiki><o>overline</o></nowiki></code>, and <code><nowiki><u>underline</u></nowiki></code> tags.<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you decho it will erase any previous echo sent to the label.<br />
<br />
: See also: [[#cecho|cecho()]], [[#hecho|hecho()]], [[#copy2decho|copy2decho()]]<br />
<br />
;Parameters<br />
* ''name of console''<br />
: (Optional) Name of the console to echo to. If no name is given, this will defaults to the main window.<br />
* ''text:''<br />
: The text that you’d like to echo with embedded color tags. Tags take the RGB values only, see below for an explanation.<br />
<br />
<br />
{{note}}<br />
Optional background transparancy parameter (BA) available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
decho("<50,50,0:0,255,0>test")<br />
<br />
decho("miniconsolename", "<50,50,0:0,255,0>test")<br />
<br />
decho("\n<255,0,0>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, and <b>bold</b> formatting.")<br />
<br />
decho("<\n<0,128,0><o><u>Green text with both over and underlines.</u></o>")<br />
</syntaxhighlight><br />
<br />
==decho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = decho2ansi(text)<br />
<br />
:Converts decho formatted text to ansi formatted text. Used by dfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#dfeedTriggers|dfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The decho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of dfeedTriggers() for a single line.<br />
-- you would most likely just use dfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(decho2ansi("\n<128,0,0>This is red.<r> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
==getHTMLformat PR#5751 merged==<br />
<br />
; spanTag = getHTMLformat(formatTable)<br />
<br />
:Takes in a table of formatting options in the same style as [[Manual:Lua_Functions#getTextFormat|getTextFormat()]] and returns a span tag which will format text after it as the table describes.<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formatTable:''<br />
: Table with formatting options configured. Keys are foreground, background, bold, underline, overline, strikeout, italic, and reverse. All except for foreground and background should be boolean (true/false) values. Foreground and background are either { r, g, b, a } tables, or strings with QSS formatting directives<br />
<br />
;Returns <br />
* A string with the html span tag to format text in accordance with the format table.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Returns a span tag for bold, red text on a green background<br />
local span = getHTMLformat({<br />
foreground = { 255, 0, 0 },<br />
background = "#00FF00",<br />
bold = true<br />
})<br />
<br />
-- span will be '<span style="color: rgb(255, 0, 0);background-color: #00FF00; font-weight: bold; font-style: normal; text-decoration: none;">'<br />
</syntaxhighlight><br />
<br />
==getLabelFormat PR#5751 open==<br />
<br />
; formatTable = getLabelFormat(labelName)<br />
<br />
:Returns a format table like the one returned by getTextFormat and suitable for getHTMLspan which will format text the same way as simply doing an echo to the label would<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getHTMLspan|getHTMLspan()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: The name of the label to scan the format of<br />
<br />
;Returns <br />
* A table with all the formatting options to achieve a default text format for label labelName. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- creates a test label, sets a stylesheet, and then returns the default format table for that label.<br />
createLabel("testLabel", 10, 10, 300, 200, 1)<br />
setLabelStyleSheet([[<br />
color: rgb(0,0,180);<br />
border-width: 1px;<br />
border-style: solid;<br />
border-color: gold;<br />
border-radius: 10px;<br />
font-size: 12.0pt;<br />
background: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #98f041, stop: 0.1 #8cf029, stop: 0.49 #66cc00, stop: 0.5 #52a300, stop: 1 #66cc00);<br />
]])<br />
local fmt = getLabelFormat("testLabel"))<br />
<br />
--[[<br />
{<br />
background = "rgba(0, 0, 0, 0)", -- this is transparent<br />
bold = false,<br />
foreground = "rgb(0,0,180)",<br />
italic = false,<br />
overline = false,<br />
reverse = false,<br />
strikeout = false,<br />
underline = false<br />
}<br />
--]]<br />
<br />
</syntaxhighlight><br />
<br />
==hecho PR #5669 merged, PR5719 merged, PR5751 open==<br />
;hecho([windowName], text)<br />
: Echoes text that can be easily formatted with colour tags in the hexadecimal format. You can also use italics, bold, strikethrough, and underline tags.<br />
: See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#cecho|cecho()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you hecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Can either be omitted or "main" for the main window, else specify the miniconsoles name.<br />
* ''text:''<br />
: The text to display, with color changes made within the string using the format |cFRFGFB,BRBGBB or #FRFGFB,BRBGBB where FR is the foreground red value, FG is the foreground green value, FB is the foreground blue value, BR is the background red value, etc., BRBGBB is optional. |r or #r can be used within the string to reset the colors to default. Hexadecimal color codes can be found here: https://www.color-hex.com/<br />
<br />
{{note}}<br />
Transparency for background in hex-format available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
hecho("\n#ffffff White text!")<br />
-- your text in white<br />
hecho("\n#ca0004 Red text! And now reset #rit to the default color")<br />
-- your text in red, then reset to default using #r<br />
hecho("\n#ffffff,ca0004 White text with a red background!")<br />
-- your text in white, against a red background<br />
hecho("\n|c0000ff Blue text, this time using |c instead of #")<br />
-- your text in blue, activated with |c vs #.<br />
hecho("\n#ff0000Red text with #iitalics#/i, |uunderline|/u, #ooverline#/o, #sstrikethrough#/s, and #bbold#/b formatting.")<br />
-- shows the various individual formatting options<br />
hecho("\n#008000#o#uGreen text with both over and underlines.#/o#/u")<br />
</syntaxhighlight><br />
<br />
==hecho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = hecho2ansi(text)<br />
<br />
:Converts hecho formatted text to ansi formatted text. Used by hfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:Lua_Functions#hfeedTriggers|hfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The hecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of hfeedTriggers() for a single line.<br />
-- you would most likely just use hfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(hecho2ansi("\n#800000This is red.#r #iitalic#/i, #bbold#/b, #sstrikethrough#/s, #uunderline#/u\n"))<br />
</syntaxhighlight><br />
<br />
==windowType PR# 5696 open==<br />
; typeOfWindow = windowType(windowName)<br />
<br />
:Given the name of a window, will return if it's a label, miniconsole, userwindow or a commandline.<br />
<br />
;See also: [[Manual:Lua_Functions#createLabel|createLabel()]], [[Manual:Lua_Functions#openUserWindow|openUserWindow()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name used to create the window element. Use "main" for the main console<br />
<br />
<br />
;Returns <br />
* Window type as string ("label", "miniconsole", "userwindow", or "commandline") or nil+error if it does not exist.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a Geyser label and and check its type<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
display(windowType(testLabel.name)) -- displays "label"<br />
<br />
-- the main console returns "miniconsole" because it uses the same formatting functions<br />
display(windowType("main")) -- displays "miniconsole"<br />
<br />
-- check for the existence of a window<br />
local windowName = "this thing does not exist"<br />
local ok, err = windowType(windowName)<br />
if ok then<br />
-- do things with it, as it does exist.<br />
-- the ok variable will hold the type of window it is ("label", "commandline", etc)<br />
else<br />
cecho("<red>ALERT!! window does not exist")<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
=Discord Functions=<br />
: 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 [[Special:MyLanguage/Manual:Scripting#Discord_Rich_Presence|Discord scripting overview]].</div>Demonnichttps://wiki.mudlet.org/index.php?title=Area_51&diff=18599Area 512022-01-02T17:21:24Z<p>Demonnic: /* decho PR #5669 merged PR5719 merged PR5751 open */</p>
<hr />
<div>{{TOC right}}<br />
<br />
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 [[Manual:Lua_Functions|Lua Functions]] and its sub-sites. <br />
<br />
Please use the [[Area_51/Template]] to add new entries in the sections below.<br />
<br />
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.<br />
<br />
<br />
=Basic Essential Functions=<br />
:These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.<br />
<br />
=Database Functions=<br />
:A collection of functions for helping deal with the database.<br />
<br />
=Date/Time Functions=<br />
: A collection of functions for handling date & time.<br />
<br />
=File System Functions=<br />
: A collection of functions for interacting with the file system.<br />
<br />
=Mapper Functions=<br />
: A collection of functions that manipulate the mapper and its related features.<br />
<br />
==mapSymbolFontInfo, PR #4038 closed==<br />
;mapSymbolFontInfo()<br />
: See also: [[#setupMapSymbolFont|setupMapSymbolFont()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;returns<br />
* either a table of information about the configuration of the font used for symbols in the (2D) map, the elements are:<br />
:* ''fontName'' - a string of the family name of the font specified<br />
:* ''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.<br />
:* ''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).<br />
* or ''nil'' and an error message on failure.<br />
<br />
::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).<br />
<br />
<br />
==setupMapSymbolFont, PR #4038 closed==<br />
;setupMapSymbolFont(fontName[, onlyUseThisFont[, scalingFactor]])<br />
:configures the font used for symbols in the (2D) map.<br />
: See also: [[#mapSymbolFontInfo|mapSymbolFontInfo()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;Parameters<br />
* ''fontName'' one of:<br />
:* - a string that is the family name of the font to use;<br />
:* - the empty string ''""'' to reset to the default {which is '''"Bitstream Vera Sans Mono"'''};<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow a following one to be modified.<br />
* ''onlyUseThisFont'' (optional) one of:<br />
:* - 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;<br />
:* - 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;<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow the following one to be modified.<br />
* ''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.<br />
<br />
;Returns<br />
* ''true'' on success<br />
* ''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).<br />
<br />
=Miscellaneous Functions=<br />
: Miscellaneous functions.<br />
<br />
==getCharacterName, PR #3952 open==<br />
;getCharacterName()<br />
<br />
: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.<br />
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.<br />
<br />
:See also: [[#sendCharacterName|sendCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lua send("cast 'glamor' " .. getCharacterName())<br />
<br />
You get a warm feeling passing from your core to the tips of your hands, feet and other body parts.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A tawny long-haired cat saunters over and start to rub itself against your ankles.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A mangy dog trots up to you and proceeds to mark the bottom of your leggings.<br />
</syntaxhighlight><br />
<br />
==getCustomLoginTextId, PR #3952 open==<br />
;getCustomLoginTextId()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#sendPassword|sendPassword()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCharacterName, PR #3952 open==<br />
;sendCharacterName()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
==sendCharacterPassword, PR #3952 open==<br />
;sendCharacterPassword()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]], [[#sendCharacterName|sendCharacterName()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCharacterName() ~= "" then<br />
tempTime(2.0, [[sendCharacterName()]], 1)<br />
tempTime(3.0, [[sendCharacterPassword()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCustomLoginText, PR #3952 open==<br />
;sendCustomLoginText()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendPassword|sendPassword()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
=Mudlet Object Functions=<br />
: A collection of functions that manipulate Mudlets scripting objects - triggers, aliases, and so forth.<br />
<br />
=Networking Functions=<br />
: A collection of functions for managing networking.<br />
<br />
=String Functions=<br />
: These functions are used to manipulate strings.<br />
<br />
==string.patternEscape, utf8.patternEscape PR 5806==<br />
; escapedString = string.patternEscape(str) or escapedString = utf8.patternEscape(str)<br />
<br />
: Returns a version of str with all Lua pattern characters escaped to ensure string.match/find/etc look for the original str.<br />
<br />
;See also: [[Manual:Lua_Functions#string.trim|string.trim()]], [[Manual:Lua_Functions#string.genNocasePattern|string.genNocasePattern()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''str:''<br />
: The string to escape lua pattern characters in.<br />
<br />
;Returns <br />
* The string with all special Lua pattern characters escaped. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- searching for a url inside of a string. <br />
local helpString = [[<br />
This feature can be accessed by going to https://some-url.com/athing.html?param=value and<br />
retrieving the result!<br />
]]<br />
local url = "https://some-url.com/"<br />
display(helpString:find(url))<br />
-- nil<br />
display(helpString:find(string.patternEscape(url)))<br />
-- 42<br />
-- 62<br />
display(url:patternEscape())<br />
-- "https://some%-url%.com/"<br />
</syntaxhighlight><br />
<br />
=Table Functions=<br />
: 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.<br />
<br />
=Text to Speech Functions=<br />
: These functions are used to create sound from written words. Check out our [[Special:MyLanguage/Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.<br />
<br />
=UI Functions=<br />
: 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.<br />
<br />
==ansi2decho PR# 5670 merge, PR5719 merged==<br />
;ansi2decho(text, default_colour)<br />
: Converts ANSI colour sequences in <code>text</code> to colour tags that can be processed by the decho() function.<br />
: See also: [[Manual:Lua_Functions#decho|decho()]]<br />
<br />
{{MudletVersion|3.0}}<br />
{{note}} ANSI bold is available since Mudlet 3.7.1+.<br />
<br />
{{note}} underline, italics, overline, and strikethrough supported since Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: String that contains ANSI colour sequences that should be replaced.<br />
* ''default_colour:''<br />
: Optional - ANSI default colour code (used when handling orphan bold tags).<br />
<br />
;Return values<br />
* ''string text:''<br />
: The decho-valid converted text.<br />
* ''string colour:''<br />
: The ANSI code for the last used colour in the substitution (useful if you want to colour subsequent lines according to this colour).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local replaced = ansi2decho('\27[0;1;36;40mYou say in a baritone voice, "Test."\27[0;37;40m')<br />
-- 'replaced' should now contain <r><0,255,255:0,0,0>You say in a baritone voice, "Test."<r><192,192,192:0,0,0><br />
decho(replaced)<br />
</syntaxhighlight><br />
<br />
Or show a complete colourful squirrel! It's a lotta code to do all the colours, so click the '''Expand''' button on the right to show it:<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<syntaxhighlight lang="lua"><br />
decho(ansi2decho([[<br />
�[38;5;95m▄�[48;5;95;38;5;130m▄▄▄�[38;5;95m█�[49m▀�[0m �[0m<br />
╭───────────────────────╮ �[38;5;95m▄▄�[0m �[38;5;95m▄�[48;5;95;38;5;130m▄▄�[48;5;130m█�[38;5;137m▄�[48;5;137;38;5;95m▄�[49m▀�[0m �[0m<br />
│ │ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄▄▄�[48;5;95;38;5;137m▄▄▄�[49;38;5;95m▄▄�[48;5;95;38;5;130m▄�[48;5;130m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[0m �[0m<br />
│ Encrypt everything! │ �[38;5;95m▄�[48;5;187;38;5;16m▄�[48;5;16;38;5;187m▄�[38;5;16m█�[48;5;137;38;5;137m███�[38;5;187m▄�[38;5;16m▄▄�[38;5;137m██�[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[0m �[0m<br />
│ ├──── �[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;16m▄▄▄�[48;5;137m███�[48;5;16;38;5;16m█�[48;5;187m▄�[48;5;16m█�[48;5;137;38;5;137m█�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
╰───────────────────────╯ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;16m▄�[38;5;16m█�[38;5;137m▄�[48;5;137m██████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;95m▀�[48;5;137m▄�[38;5;137m███████�[38;5;95m▄�[49m▀�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[48;5;95;38;5;187m▄▄▄�[38;5;137m▄�[48;5;137m██�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[38;5;95m▀�[48;5;130m▄�[38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;187m████�[48;5;137;38;5;137m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m██�[38;5;95m▄�[38;5;137m█�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;187;38;5;187m████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95m██�[48;5;137m▄▄�[48;5;187;38;5;187m████�[48;5;137;38;5;95m▄▄�[48;5;95;38;5;137m▄�[48;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;187;38;5;187m███�[48;5;95m▄�[38;5;137m▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[49m▄�[48;5;95;38;5;130m▄�[48;5;130m██████�[48;5;137;38;5;137m███�[38;5;95m▄�[49m▀�[0m�[0m<br />
�[48;5;187;38;5;95m▄�[38;5;187m████�[48;5;137;38;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m█████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;137m▄�[38;5;187m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██████�[48;5;95m▄▄�[48;5;130m▄▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▄▄▄�[48;5;95;38;5;137m▄�[48;5;187m▄�[38;5;187m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m█████�[38;5;95m▄�[38;5;137m███████████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀�[48;5;187m▄▄▄�[48;5;95;38;5;137m▄�[48;5;137m██�[38;5;95m▄�[49m▀�[0m �[38;5;95m▀▀�[48;5;137m▄▄▄▄▄▄�[49m▀▀▀�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀▀�[0m �[0m<br />
]]))<br />
</syntaxhighlight><br />
</div><br />
<br />
[[File:Squirrel-in-Mudlet.png|frameless]]<br />
<br />
==cecho PR #5669 merged, PR5719 merged, PR5751 merged==<br />
;cecho([window], text)<br />
: Echoes text that can be easily formatted with colour, italics, bold, strikethrough, and underline tags. You can also include unicode art in it - try some examples from [http://1lineart.kulaone.com/#/ 1lineart].<br />
: See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:UI Functions#creplaceLine|creplaceLine()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you cecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''window:''<br />
: Optional - the window name to echo to - can either be none or "main" for the main window, or a miniconsole, userwindow, or label name.<br />
* ''text:''<br />
: The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
cecho("Hi! This text is <red>red, <blue>blue, <green> and green.")<br />
<br />
cecho("<:green>Green background on normal foreground. Here we add an <ivory>ivory foreground.")<br />
<br />
cecho("<blue:yellow>Blue on yellow text!")<br />
<br />
cecho("\n<red>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, <o>overline</o>, and <b>bold</b>.")<br />
<br />
cecho("\n<green><o><u>Green text with over and underline at the same time.</o></u>")<br />
<br />
-- \n adds a new line<br />
cecho("<red>one line\n<green>another line\n<blue>last line")<br />
<br />
cecho("myinfo", "<green>All of this text is green in the myinfo miniconsole.")<br />
<br />
cecho("<green>(╯°□°)<dark_green>╯︵ ┻━┻")<br />
<br />
cecho("°º¤ø,¸¸,ø¤º°`°º¤ø,¸,ø¤°º¤ø,¸¸,ø¤º°`°º¤ø,¸")<br />
<br />
cecho([[<br />
██╗ ██╗ ██╗███╗ ██╗███████╗ █████╗ ██████╗ ████████╗<br />
███║ ██║ ██║████╗ ██║██╔════╝ ██╔══██╗██╔══██╗╚══██╔══╝<br />
╚██║ ██║ ██║██╔██╗ ██║█████╗ ███████║██████╔╝ ██║<br />
██║ ██║ ██║██║╚██╗██║██╔══╝ ██╔══██║██╔══██╗ ██║<br />
██║ ███████╗██║██║ ╚████║███████╗ ██║ ██║██║ ██║ ██║<br />
╚═╝ ╚══════╝╚═╝╚═╝ ╚═══╝╚══════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝<br />
]])<br />
</syntaxhighlight><br />
<br />
==cecho2ansi PR# 5672 merged==<br />
<br />
; ansiFormattedString = cecho2ansi(text)<br />
<br />
:Converts cecho formatted text to ansi formatted text. Used by cfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:Lua_Functions#cfeedTriggers|cfeedTriggers()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
{{note}} This function uses the ansi short colors (0-15) for color names which have base 16 ansi equivalents, such as 'red', 'blue', "lightBlue", "cyan", etc rather than the values defined in the color_table. If there is no base ansi equivalent then it will use the rgb values from the color_table for the color.<br />
<br />
;Parameters<br />
* ''text:''<br />
: The cecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of cfeedTriggers() for a single line.<br />
-- you would most likely just use cfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(cecho2ansi("\n<red>This is red.<reset> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
==decho PR #5669 merged PR5719 merged PR5751 merged==<br />
;decho ([name of console,] text)<br />
: Color changes can be made using the format <FR,FG,FB:BR,BG,BB,[BA]> where each field is a number from 0 to 255. The background portion can be omitted using <FR,FG,FB> or the foreground portion can be omitted using <:BR,BG,BB,[BA]>. Arguments 2 and 3 set the default fore and background colors for the string using the same format as is used within the string, sans angle brackets, e.g. ''decho("<50,50,0:0,255,0>test")''.<br />
:You can also include <code><nowiki><i>italics</i></nowiki></code>, <code><nowiki><b>bold</b></nowiki></code>, <code><nowiki><s>strikethrough</s></nowiki></code>, <code><nowiki><o>overline</o></nowiki></code>, and <code><nowiki><u>underline</u></nowiki></code> tags.<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you decho it will erase any previous echo sent to the label.<br />
<br />
: See also: [[#cecho|cecho()]], [[#hecho|hecho()]], [[#copy2decho|copy2decho()]]<br />
<br />
;Parameters<br />
* ''name of console''<br />
: (Optional) Name of the console to echo to. If no name is given, this will defaults to the main window.<br />
* ''text:''<br />
: The text that you’d like to echo with embedded color tags. Tags take the RGB values only, see below for an explanation.<br />
<br />
<br />
{{note}}<br />
Optional background transparancy parameter (BA) available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
decho("<50,50,0:0,255,0>test")<br />
<br />
decho("miniconsolename", "<50,50,0:0,255,0>test")<br />
<br />
decho("\n<255,0,0>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, and <b>bold</b> formatting.")<br />
<br />
decho("<\n<0,128,0><o><u>Green text with both over and underlines.</u></o>")<br />
</syntaxhighlight><br />
<br />
==decho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = decho2ansi(text)<br />
<br />
:Converts decho formatted text to ansi formatted text. Used by dfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#dfeedTriggers|dfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The decho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of dfeedTriggers() for a single line.<br />
-- you would most likely just use dfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(decho2ansi("\n<128,0,0>This is red.<r> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
==getHTMLformat PR#5751 open==<br />
<br />
; spanTag = getHTMLformat(formatTable)<br />
<br />
:Takes in a table of formatting options in the same style as [[Manual:Lua_Functions#getTextFormat|getTextFormat()]] and returns a span tag which will format text after it as the table describes.<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formatTable:''<br />
: Table with formatting options configured. Keys are foreground, background, bold, underline, overline, strikeout, italic, and reverse. All except for foreground and background should be boolean (true/false) values. Foreground and background are either { r, g, b, a } tables, or strings with QSS formatting directives<br />
<br />
;Returns <br />
* A string with the html span tag to format text in accordance with the format table.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Returns a span tag for bold, red text on a green background<br />
local span = getHTMLformat({<br />
foreground = { 255, 0, 0 },<br />
background = "#00FF00",<br />
bold = true<br />
})<br />
<br />
-- span will be '<span style="color: rgb(255, 0, 0);background-color: #00FF00; font-weight: bold; font-style: normal; text-decoration: none;">'<br />
</syntaxhighlight><br />
<br />
==getLabelFormat PR#5751 open==<br />
<br />
; formatTable = getLabelFormat(labelName)<br />
<br />
:Returns a format table like the one returned by getTextFormat and suitable for getHTMLspan which will format text the same way as simply doing an echo to the label would<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getHTMLspan|getHTMLspan()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: The name of the label to scan the format of<br />
<br />
;Returns <br />
* A table with all the formatting options to achieve a default text format for label labelName. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- creates a test label, sets a stylesheet, and then returns the default format table for that label.<br />
createLabel("testLabel", 10, 10, 300, 200, 1)<br />
setLabelStyleSheet([[<br />
color: rgb(0,0,180);<br />
border-width: 1px;<br />
border-style: solid;<br />
border-color: gold;<br />
border-radius: 10px;<br />
font-size: 12.0pt;<br />
background: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #98f041, stop: 0.1 #8cf029, stop: 0.49 #66cc00, stop: 0.5 #52a300, stop: 1 #66cc00);<br />
]])<br />
local fmt = getLabelFormat("testLabel"))<br />
<br />
--[[<br />
{<br />
background = "rgba(0, 0, 0, 0)", -- this is transparent<br />
bold = false,<br />
foreground = "rgb(0,0,180)",<br />
italic = false,<br />
overline = false,<br />
reverse = false,<br />
strikeout = false,<br />
underline = false<br />
}<br />
--]]<br />
<br />
</syntaxhighlight><br />
<br />
==hecho PR #5669 merged, PR5719 merged, PR5751 open==<br />
;hecho([windowName], text)<br />
: Echoes text that can be easily formatted with colour tags in the hexadecimal format. You can also use italics, bold, strikethrough, and underline tags.<br />
: See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#cecho|cecho()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you hecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Can either be omitted or "main" for the main window, else specify the miniconsoles name.<br />
* ''text:''<br />
: The text to display, with color changes made within the string using the format |cFRFGFB,BRBGBB or #FRFGFB,BRBGBB where FR is the foreground red value, FG is the foreground green value, FB is the foreground blue value, BR is the background red value, etc., BRBGBB is optional. |r or #r can be used within the string to reset the colors to default. Hexadecimal color codes can be found here: https://www.color-hex.com/<br />
<br />
{{note}}<br />
Transparency for background in hex-format available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
hecho("\n#ffffff White text!")<br />
-- your text in white<br />
hecho("\n#ca0004 Red text! And now reset #rit to the default color")<br />
-- your text in red, then reset to default using #r<br />
hecho("\n#ffffff,ca0004 White text with a red background!")<br />
-- your text in white, against a red background<br />
hecho("\n|c0000ff Blue text, this time using |c instead of #")<br />
-- your text in blue, activated with |c vs #.<br />
hecho("\n#ff0000Red text with #iitalics#/i, |uunderline|/u, #ooverline#/o, #sstrikethrough#/s, and #bbold#/b formatting.")<br />
-- shows the various individual formatting options<br />
hecho("\n#008000#o#uGreen text with both over and underlines.#/o#/u")<br />
</syntaxhighlight><br />
<br />
==hecho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = hecho2ansi(text)<br />
<br />
:Converts hecho formatted text to ansi formatted text. Used by hfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:Lua_Functions#hfeedTriggers|hfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The hecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of hfeedTriggers() for a single line.<br />
-- you would most likely just use hfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(hecho2ansi("\n#800000This is red.#r #iitalic#/i, #bbold#/b, #sstrikethrough#/s, #uunderline#/u\n"))<br />
</syntaxhighlight><br />
<br />
==windowType PR# 5696 open==<br />
; typeOfWindow = windowType(windowName)<br />
<br />
:Given the name of a window, will return if it's a label, miniconsole, userwindow or a commandline.<br />
<br />
;See also: [[Manual:Lua_Functions#createLabel|createLabel()]], [[Manual:Lua_Functions#openUserWindow|openUserWindow()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name used to create the window element. Use "main" for the main console<br />
<br />
<br />
;Returns <br />
* Window type as string ("label", "miniconsole", "userwindow", or "commandline") or nil+error if it does not exist.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a Geyser label and and check its type<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
display(windowType(testLabel.name)) -- displays "label"<br />
<br />
-- the main console returns "miniconsole" because it uses the same formatting functions<br />
display(windowType("main")) -- displays "miniconsole"<br />
<br />
-- check for the existence of a window<br />
local windowName = "this thing does not exist"<br />
local ok, err = windowType(windowName)<br />
if ok then<br />
-- do things with it, as it does exist.<br />
-- the ok variable will hold the type of window it is ("label", "commandline", etc)<br />
else<br />
cecho("<red>ALERT!! window does not exist")<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
=Discord Functions=<br />
: 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 [[Special:MyLanguage/Manual:Scripting#Discord_Rich_Presence|Discord scripting overview]].</div>Demonnichttps://wiki.mudlet.org/index.php?title=Area_51&diff=18598Area 512022-01-02T17:20:32Z<p>Demonnic: /* cecho PR #5669 merged, PR5719 merged, PR5751 open */</p>
<hr />
<div>{{TOC right}}<br />
<br />
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 [[Manual:Lua_Functions|Lua Functions]] and its sub-sites. <br />
<br />
Please use the [[Area_51/Template]] to add new entries in the sections below.<br />
<br />
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.<br />
<br />
<br />
=Basic Essential Functions=<br />
:These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.<br />
<br />
=Database Functions=<br />
:A collection of functions for helping deal with the database.<br />
<br />
=Date/Time Functions=<br />
: A collection of functions for handling date & time.<br />
<br />
=File System Functions=<br />
: A collection of functions for interacting with the file system.<br />
<br />
=Mapper Functions=<br />
: A collection of functions that manipulate the mapper and its related features.<br />
<br />
==mapSymbolFontInfo, PR #4038 closed==<br />
;mapSymbolFontInfo()<br />
: See also: [[#setupMapSymbolFont|setupMapSymbolFont()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;returns<br />
* either a table of information about the configuration of the font used for symbols in the (2D) map, the elements are:<br />
:* ''fontName'' - a string of the family name of the font specified<br />
:* ''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.<br />
:* ''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).<br />
* or ''nil'' and an error message on failure.<br />
<br />
::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).<br />
<br />
<br />
==setupMapSymbolFont, PR #4038 closed==<br />
;setupMapSymbolFont(fontName[, onlyUseThisFont[, scalingFactor]])<br />
:configures the font used for symbols in the (2D) map.<br />
: See also: [[#mapSymbolFontInfo|mapSymbolFontInfo()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;Parameters<br />
* ''fontName'' one of:<br />
:* - a string that is the family name of the font to use;<br />
:* - the empty string ''""'' to reset to the default {which is '''"Bitstream Vera Sans Mono"'''};<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow a following one to be modified.<br />
* ''onlyUseThisFont'' (optional) one of:<br />
:* - 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;<br />
:* - 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;<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow the following one to be modified.<br />
* ''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.<br />
<br />
;Returns<br />
* ''true'' on success<br />
* ''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).<br />
<br />
=Miscellaneous Functions=<br />
: Miscellaneous functions.<br />
<br />
==getCharacterName, PR #3952 open==<br />
;getCharacterName()<br />
<br />
: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.<br />
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.<br />
<br />
:See also: [[#sendCharacterName|sendCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lua send("cast 'glamor' " .. getCharacterName())<br />
<br />
You get a warm feeling passing from your core to the tips of your hands, feet and other body parts.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A tawny long-haired cat saunters over and start to rub itself against your ankles.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A mangy dog trots up to you and proceeds to mark the bottom of your leggings.<br />
</syntaxhighlight><br />
<br />
==getCustomLoginTextId, PR #3952 open==<br />
;getCustomLoginTextId()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#sendPassword|sendPassword()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCharacterName, PR #3952 open==<br />
;sendCharacterName()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
==sendCharacterPassword, PR #3952 open==<br />
;sendCharacterPassword()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]], [[#sendCharacterName|sendCharacterName()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCharacterName() ~= "" then<br />
tempTime(2.0, [[sendCharacterName()]], 1)<br />
tempTime(3.0, [[sendCharacterPassword()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCustomLoginText, PR #3952 open==<br />
;sendCustomLoginText()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendPassword|sendPassword()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
=Mudlet Object Functions=<br />
: A collection of functions that manipulate Mudlets scripting objects - triggers, aliases, and so forth.<br />
<br />
=Networking Functions=<br />
: A collection of functions for managing networking.<br />
<br />
=String Functions=<br />
: These functions are used to manipulate strings.<br />
<br />
==string.patternEscape, utf8.patternEscape PR 5806==<br />
; escapedString = string.patternEscape(str) or escapedString = utf8.patternEscape(str)<br />
<br />
: Returns a version of str with all Lua pattern characters escaped to ensure string.match/find/etc look for the original str.<br />
<br />
;See also: [[Manual:Lua_Functions#string.trim|string.trim()]], [[Manual:Lua_Functions#string.genNocasePattern|string.genNocasePattern()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''str:''<br />
: The string to escape lua pattern characters in.<br />
<br />
;Returns <br />
* The string with all special Lua pattern characters escaped. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- searching for a url inside of a string. <br />
local helpString = [[<br />
This feature can be accessed by going to https://some-url.com/athing.html?param=value and<br />
retrieving the result!<br />
]]<br />
local url = "https://some-url.com/"<br />
display(helpString:find(url))<br />
-- nil<br />
display(helpString:find(string.patternEscape(url)))<br />
-- 42<br />
-- 62<br />
display(url:patternEscape())<br />
-- "https://some%-url%.com/"<br />
</syntaxhighlight><br />
<br />
=Table Functions=<br />
: 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.<br />
<br />
=Text to Speech Functions=<br />
: These functions are used to create sound from written words. Check out our [[Special:MyLanguage/Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.<br />
<br />
=UI Functions=<br />
: 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.<br />
<br />
==ansi2decho PR# 5670 merge, PR5719 merged==<br />
;ansi2decho(text, default_colour)<br />
: Converts ANSI colour sequences in <code>text</code> to colour tags that can be processed by the decho() function.<br />
: See also: [[Manual:Lua_Functions#decho|decho()]]<br />
<br />
{{MudletVersion|3.0}}<br />
{{note}} ANSI bold is available since Mudlet 3.7.1+.<br />
<br />
{{note}} underline, italics, overline, and strikethrough supported since Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: String that contains ANSI colour sequences that should be replaced.<br />
* ''default_colour:''<br />
: Optional - ANSI default colour code (used when handling orphan bold tags).<br />
<br />
;Return values<br />
* ''string text:''<br />
: The decho-valid converted text.<br />
* ''string colour:''<br />
: The ANSI code for the last used colour in the substitution (useful if you want to colour subsequent lines according to this colour).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local replaced = ansi2decho('\27[0;1;36;40mYou say in a baritone voice, "Test."\27[0;37;40m')<br />
-- 'replaced' should now contain <r><0,255,255:0,0,0>You say in a baritone voice, "Test."<r><192,192,192:0,0,0><br />
decho(replaced)<br />
</syntaxhighlight><br />
<br />
Or show a complete colourful squirrel! It's a lotta code to do all the colours, so click the '''Expand''' button on the right to show it:<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<syntaxhighlight lang="lua"><br />
decho(ansi2decho([[<br />
�[38;5;95m▄�[48;5;95;38;5;130m▄▄▄�[38;5;95m█�[49m▀�[0m �[0m<br />
╭───────────────────────╮ �[38;5;95m▄▄�[0m �[38;5;95m▄�[48;5;95;38;5;130m▄▄�[48;5;130m█�[38;5;137m▄�[48;5;137;38;5;95m▄�[49m▀�[0m �[0m<br />
│ │ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄▄▄�[48;5;95;38;5;137m▄▄▄�[49;38;5;95m▄▄�[48;5;95;38;5;130m▄�[48;5;130m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[0m �[0m<br />
│ Encrypt everything! │ �[38;5;95m▄�[48;5;187;38;5;16m▄�[48;5;16;38;5;187m▄�[38;5;16m█�[48;5;137;38;5;137m███�[38;5;187m▄�[38;5;16m▄▄�[38;5;137m██�[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[0m �[0m<br />
│ ├──── �[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;16m▄▄▄�[48;5;137m███�[48;5;16;38;5;16m█�[48;5;187m▄�[48;5;16m█�[48;5;137;38;5;137m█�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
╰───────────────────────╯ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;16m▄�[38;5;16m█�[38;5;137m▄�[48;5;137m██████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;95m▀�[48;5;137m▄�[38;5;137m███████�[38;5;95m▄�[49m▀�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[48;5;95;38;5;187m▄▄▄�[38;5;137m▄�[48;5;137m██�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[38;5;95m▀�[48;5;130m▄�[38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;187m████�[48;5;137;38;5;137m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m██�[38;5;95m▄�[38;5;137m█�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;187;38;5;187m████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95m██�[48;5;137m▄▄�[48;5;187;38;5;187m████�[48;5;137;38;5;95m▄▄�[48;5;95;38;5;137m▄�[48;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;187;38;5;187m███�[48;5;95m▄�[38;5;137m▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[49m▄�[48;5;95;38;5;130m▄�[48;5;130m██████�[48;5;137;38;5;137m███�[38;5;95m▄�[49m▀�[0m�[0m<br />
�[48;5;187;38;5;95m▄�[38;5;187m████�[48;5;137;38;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m█████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;137m▄�[38;5;187m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██████�[48;5;95m▄▄�[48;5;130m▄▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▄▄▄�[48;5;95;38;5;137m▄�[48;5;187m▄�[38;5;187m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m█████�[38;5;95m▄�[38;5;137m███████████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀�[48;5;187m▄▄▄�[48;5;95;38;5;137m▄�[48;5;137m██�[38;5;95m▄�[49m▀�[0m �[38;5;95m▀▀�[48;5;137m▄▄▄▄▄▄�[49m▀▀▀�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀▀�[0m �[0m<br />
]]))<br />
</syntaxhighlight><br />
</div><br />
<br />
[[File:Squirrel-in-Mudlet.png|frameless]]<br />
<br />
==cecho PR #5669 merged, PR5719 merged, PR5751 merged==<br />
;cecho([window], text)<br />
: Echoes text that can be easily formatted with colour, italics, bold, strikethrough, and underline tags. You can also include unicode art in it - try some examples from [http://1lineart.kulaone.com/#/ 1lineart].<br />
: See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:UI Functions#creplaceLine|creplaceLine()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you cecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''window:''<br />
: Optional - the window name to echo to - can either be none or "main" for the main window, or a miniconsole, userwindow, or label name.<br />
* ''text:''<br />
: The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
cecho("Hi! This text is <red>red, <blue>blue, <green> and green.")<br />
<br />
cecho("<:green>Green background on normal foreground. Here we add an <ivory>ivory foreground.")<br />
<br />
cecho("<blue:yellow>Blue on yellow text!")<br />
<br />
cecho("\n<red>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, <o>overline</o>, and <b>bold</b>.")<br />
<br />
cecho("\n<green><o><u>Green text with over and underline at the same time.</o></u>")<br />
<br />
-- \n adds a new line<br />
cecho("<red>one line\n<green>another line\n<blue>last line")<br />
<br />
cecho("myinfo", "<green>All of this text is green in the myinfo miniconsole.")<br />
<br />
cecho("<green>(╯°□°)<dark_green>╯︵ ┻━┻")<br />
<br />
cecho("°º¤ø,¸¸,ø¤º°`°º¤ø,¸,ø¤°º¤ø,¸¸,ø¤º°`°º¤ø,¸")<br />
<br />
cecho([[<br />
██╗ ██╗ ██╗███╗ ██╗███████╗ █████╗ ██████╗ ████████╗<br />
███║ ██║ ██║████╗ ██║██╔════╝ ██╔══██╗██╔══██╗╚══██╔══╝<br />
╚██║ ██║ ██║██╔██╗ ██║█████╗ ███████║██████╔╝ ██║<br />
██║ ██║ ██║██║╚██╗██║██╔══╝ ██╔══██║██╔══██╗ ██║<br />
██║ ███████╗██║██║ ╚████║███████╗ ██║ ██║██║ ██║ ██║<br />
╚═╝ ╚══════╝╚═╝╚═╝ ╚═══╝╚══════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝<br />
]])<br />
</syntaxhighlight><br />
<br />
==cecho2ansi PR# 5672 merged==<br />
<br />
; ansiFormattedString = cecho2ansi(text)<br />
<br />
:Converts cecho formatted text to ansi formatted text. Used by cfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:Lua_Functions#cfeedTriggers|cfeedTriggers()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
{{note}} This function uses the ansi short colors (0-15) for color names which have base 16 ansi equivalents, such as 'red', 'blue', "lightBlue", "cyan", etc rather than the values defined in the color_table. If there is no base ansi equivalent then it will use the rgb values from the color_table for the color.<br />
<br />
;Parameters<br />
* ''text:''<br />
: The cecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of cfeedTriggers() for a single line.<br />
-- you would most likely just use cfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(cecho2ansi("\n<red>This is red.<reset> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
==decho PR #5669 merged PR5719 merged PR5751 open==<br />
;decho ([name of console,] text)<br />
: Color changes can be made using the format <FR,FG,FB:BR,BG,BB,[BA]> where each field is a number from 0 to 255. The background portion can be omitted using <FR,FG,FB> or the foreground portion can be omitted using <:BR,BG,BB,[BA]>. Arguments 2 and 3 set the default fore and background colors for the string using the same format as is used within the string, sans angle brackets, e.g. ''decho("<50,50,0:0,255,0>test")''.<br />
:You can also include <code><nowiki><i>italics</i></nowiki></code>, <code><nowiki><b>bold</b></nowiki></code>, <code><nowiki><s>strikethrough</s></nowiki></code>, <code><nowiki><o>overline</o></nowiki></code>, and <code><nowiki><u>underline</u></nowiki></code> tags.<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you decho it will erase any previous echo sent to the label.<br />
<br />
: See also: [[#cecho|cecho()]], [[#hecho|hecho()]], [[#copy2decho|copy2decho()]]<br />
<br />
;Parameters<br />
* ''name of console''<br />
: (Optional) Name of the console to echo to. If no name is given, this will defaults to the main window.<br />
* ''text:''<br />
: The text that you’d like to echo with embedded color tags. Tags take the RGB values only, see below for an explanation.<br />
<br />
<br />
{{note}}<br />
Optional background transparancy parameter (BA) available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
decho("<50,50,0:0,255,0>test")<br />
<br />
decho("miniconsolename", "<50,50,0:0,255,0>test")<br />
<br />
decho("\n<255,0,0>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, and <b>bold</b> formatting.")<br />
<br />
decho("<\n<0,128,0><o><u>Green text with both over and underlines.</u></o>")<br />
</syntaxhighlight><br />
<br />
==decho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = decho2ansi(text)<br />
<br />
:Converts decho formatted text to ansi formatted text. Used by dfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#dfeedTriggers|dfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The decho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of dfeedTriggers() for a single line.<br />
-- you would most likely just use dfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(decho2ansi("\n<128,0,0>This is red.<r> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
==getHTMLformat PR#5751 open==<br />
<br />
; spanTag = getHTMLformat(formatTable)<br />
<br />
:Takes in a table of formatting options in the same style as [[Manual:Lua_Functions#getTextFormat|getTextFormat()]] and returns a span tag which will format text after it as the table describes.<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formatTable:''<br />
: Table with formatting options configured. Keys are foreground, background, bold, underline, overline, strikeout, italic, and reverse. All except for foreground and background should be boolean (true/false) values. Foreground and background are either { r, g, b, a } tables, or strings with QSS formatting directives<br />
<br />
;Returns <br />
* A string with the html span tag to format text in accordance with the format table.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Returns a span tag for bold, red text on a green background<br />
local span = getHTMLformat({<br />
foreground = { 255, 0, 0 },<br />
background = "#00FF00",<br />
bold = true<br />
})<br />
<br />
-- span will be '<span style="color: rgb(255, 0, 0);background-color: #00FF00; font-weight: bold; font-style: normal; text-decoration: none;">'<br />
</syntaxhighlight><br />
<br />
==getLabelFormat PR#5751 open==<br />
<br />
; formatTable = getLabelFormat(labelName)<br />
<br />
:Returns a format table like the one returned by getTextFormat and suitable for getHTMLspan which will format text the same way as simply doing an echo to the label would<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getHTMLspan|getHTMLspan()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: The name of the label to scan the format of<br />
<br />
;Returns <br />
* A table with all the formatting options to achieve a default text format for label labelName. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- creates a test label, sets a stylesheet, and then returns the default format table for that label.<br />
createLabel("testLabel", 10, 10, 300, 200, 1)<br />
setLabelStyleSheet([[<br />
color: rgb(0,0,180);<br />
border-width: 1px;<br />
border-style: solid;<br />
border-color: gold;<br />
border-radius: 10px;<br />
font-size: 12.0pt;<br />
background: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #98f041, stop: 0.1 #8cf029, stop: 0.49 #66cc00, stop: 0.5 #52a300, stop: 1 #66cc00);<br />
]])<br />
local fmt = getLabelFormat("testLabel"))<br />
<br />
--[[<br />
{<br />
background = "rgba(0, 0, 0, 0)", -- this is transparent<br />
bold = false,<br />
foreground = "rgb(0,0,180)",<br />
italic = false,<br />
overline = false,<br />
reverse = false,<br />
strikeout = false,<br />
underline = false<br />
}<br />
--]]<br />
<br />
</syntaxhighlight><br />
<br />
==hecho PR #5669 merged, PR5719 merged, PR5751 open==<br />
;hecho([windowName], text)<br />
: Echoes text that can be easily formatted with colour tags in the hexadecimal format. You can also use italics, bold, strikethrough, and underline tags.<br />
: See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#cecho|cecho()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you hecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Can either be omitted or "main" for the main window, else specify the miniconsoles name.<br />
* ''text:''<br />
: The text to display, with color changes made within the string using the format |cFRFGFB,BRBGBB or #FRFGFB,BRBGBB where FR is the foreground red value, FG is the foreground green value, FB is the foreground blue value, BR is the background red value, etc., BRBGBB is optional. |r or #r can be used within the string to reset the colors to default. Hexadecimal color codes can be found here: https://www.color-hex.com/<br />
<br />
{{note}}<br />
Transparency for background in hex-format available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
hecho("\n#ffffff White text!")<br />
-- your text in white<br />
hecho("\n#ca0004 Red text! And now reset #rit to the default color")<br />
-- your text in red, then reset to default using #r<br />
hecho("\n#ffffff,ca0004 White text with a red background!")<br />
-- your text in white, against a red background<br />
hecho("\n|c0000ff Blue text, this time using |c instead of #")<br />
-- your text in blue, activated with |c vs #.<br />
hecho("\n#ff0000Red text with #iitalics#/i, |uunderline|/u, #ooverline#/o, #sstrikethrough#/s, and #bbold#/b formatting.")<br />
-- shows the various individual formatting options<br />
hecho("\n#008000#o#uGreen text with both over and underlines.#/o#/u")<br />
</syntaxhighlight><br />
<br />
==hecho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = hecho2ansi(text)<br />
<br />
:Converts hecho formatted text to ansi formatted text. Used by hfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:Lua_Functions#hfeedTriggers|hfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The hecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of hfeedTriggers() for a single line.<br />
-- you would most likely just use hfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(hecho2ansi("\n#800000This is red.#r #iitalic#/i, #bbold#/b, #sstrikethrough#/s, #uunderline#/u\n"))<br />
</syntaxhighlight><br />
<br />
==windowType PR# 5696 open==<br />
; typeOfWindow = windowType(windowName)<br />
<br />
:Given the name of a window, will return if it's a label, miniconsole, userwindow or a commandline.<br />
<br />
;See also: [[Manual:Lua_Functions#createLabel|createLabel()]], [[Manual:Lua_Functions#openUserWindow|openUserWindow()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name used to create the window element. Use "main" for the main console<br />
<br />
<br />
;Returns <br />
* Window type as string ("label", "miniconsole", "userwindow", or "commandline") or nil+error if it does not exist.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a Geyser label and and check its type<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
display(windowType(testLabel.name)) -- displays "label"<br />
<br />
-- the main console returns "miniconsole" because it uses the same formatting functions<br />
display(windowType("main")) -- displays "miniconsole"<br />
<br />
-- check for the existence of a window<br />
local windowName = "this thing does not exist"<br />
local ok, err = windowType(windowName)<br />
if ok then<br />
-- do things with it, as it does exist.<br />
-- the ok variable will hold the type of window it is ("label", "commandline", etc)<br />
else<br />
cecho("<red>ALERT!! window does not exist")<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
=Discord Functions=<br />
: 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 [[Special:MyLanguage/Manual:Scripting#Discord_Rich_Presence|Discord scripting overview]].</div>Demonnichttps://wiki.mudlet.org/index.php?title=Area_51&diff=18596Area 512022-01-01T20:13:34Z<p>Demonnic: /* string.escape PR 5806 */</p>
<hr />
<div>{{TOC right}}<br />
<br />
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 [[Manual:Lua_Functions|Lua Functions]] and its sub-sites. <br />
<br />
Please use the [[Area_51/Template]] to add new entries in the sections below.<br />
<br />
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.<br />
<br />
<br />
=Basic Essential Functions=<br />
:These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.<br />
<br />
=Database Functions=<br />
:A collection of functions for helping deal with the database.<br />
<br />
=Date/Time Functions=<br />
: A collection of functions for handling date & time.<br />
<br />
=File System Functions=<br />
: A collection of functions for interacting with the file system.<br />
<br />
=Mapper Functions=<br />
: A collection of functions that manipulate the mapper and its related features.<br />
<br />
==mapSymbolFontInfo, PR #4038 closed==<br />
;mapSymbolFontInfo()<br />
: See also: [[#setupMapSymbolFont|setupMapSymbolFont()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;returns<br />
* either a table of information about the configuration of the font used for symbols in the (2D) map, the elements are:<br />
:* ''fontName'' - a string of the family name of the font specified<br />
:* ''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.<br />
:* ''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).<br />
* or ''nil'' and an error message on failure.<br />
<br />
::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).<br />
<br />
<br />
==setupMapSymbolFont, PR #4038 closed==<br />
;setupMapSymbolFont(fontName[, onlyUseThisFont[, scalingFactor]])<br />
:configures the font used for symbols in the (2D) map.<br />
: See also: [[#mapSymbolFontInfo|mapSymbolFontInfo()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;Parameters<br />
* ''fontName'' one of:<br />
:* - a string that is the family name of the font to use;<br />
:* - the empty string ''""'' to reset to the default {which is '''"Bitstream Vera Sans Mono"'''};<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow a following one to be modified.<br />
* ''onlyUseThisFont'' (optional) one of:<br />
:* - 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;<br />
:* - 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;<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow the following one to be modified.<br />
* ''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.<br />
<br />
;Returns<br />
* ''true'' on success<br />
* ''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).<br />
<br />
=Miscellaneous Functions=<br />
: Miscellaneous functions.<br />
<br />
==getCharacterName, PR #3952 open==<br />
;getCharacterName()<br />
<br />
: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.<br />
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.<br />
<br />
:See also: [[#sendCharacterName|sendCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lua send("cast 'glamor' " .. getCharacterName())<br />
<br />
You get a warm feeling passing from your core to the tips of your hands, feet and other body parts.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A tawny long-haired cat saunters over and start to rub itself against your ankles.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A mangy dog trots up to you and proceeds to mark the bottom of your leggings.<br />
</syntaxhighlight><br />
<br />
==getCustomLoginTextId, PR #3952 open==<br />
;getCustomLoginTextId()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#sendPassword|sendPassword()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCharacterName, PR #3952 open==<br />
;sendCharacterName()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
==sendCharacterPassword, PR #3952 open==<br />
;sendCharacterPassword()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]], [[#sendCharacterName|sendCharacterName()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCharacterName() ~= "" then<br />
tempTime(2.0, [[sendCharacterName()]], 1)<br />
tempTime(3.0, [[sendCharacterPassword()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCustomLoginText, PR #3952 open==<br />
;sendCustomLoginText()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendPassword|sendPassword()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
=Mudlet Object Functions=<br />
: A collection of functions that manipulate Mudlets scripting objects - triggers, aliases, and so forth.<br />
<br />
=Networking Functions=<br />
: A collection of functions for managing networking.<br />
<br />
=String Functions=<br />
: These functions are used to manipulate strings.<br />
<br />
==string.patternEscape, utf8.patternEscape PR 5806==<br />
; escapedString = string.patternEscape(str) or escapedString = utf8.patternEscape(str)<br />
<br />
: Returns a version of str with all Lua pattern characters escaped to ensure string.match/find/etc look for the original str.<br />
<br />
;See also: [[Manual:Lua_Functions#string.trim|string.trim()]], [[Manual:Lua_Functions#string.genNocasePattern|string.genNocasePattern()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''str:''<br />
: The string to escape lua pattern characters in.<br />
<br />
;Returns <br />
* The string with all special Lua pattern characters escaped. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- searching for a url inside of a string. <br />
local helpString = [[<br />
This feature can be accessed by going to https://some-url.com/athing.html?param=value and<br />
retrieving the result!<br />
]]<br />
local url = "https://some-url.com/"<br />
display(helpString:find(url))<br />
-- nil<br />
display(helpString:find(string.patternEscape(url)))<br />
-- 42<br />
-- 62<br />
display(url:patternEscape())<br />
-- "https://some%-url%.com/"<br />
</syntaxhighlight><br />
<br />
=Table Functions=<br />
: 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.<br />
<br />
=Text to Speech Functions=<br />
: These functions are used to create sound from written words. Check out our [[Special:MyLanguage/Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.<br />
<br />
=UI Functions=<br />
: 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.<br />
<br />
==ansi2decho PR# 5670 merge, PR5719 merged==<br />
;ansi2decho(text, default_colour)<br />
: Converts ANSI colour sequences in <code>text</code> to colour tags that can be processed by the decho() function.<br />
: See also: [[Manual:Lua_Functions#decho|decho()]]<br />
<br />
{{MudletVersion|3.0}}<br />
{{note}} ANSI bold is available since Mudlet 3.7.1+.<br />
<br />
{{note}} underline, italics, overline, and strikethrough supported since Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: String that contains ANSI colour sequences that should be replaced.<br />
* ''default_colour:''<br />
: Optional - ANSI default colour code (used when handling orphan bold tags).<br />
<br />
;Return values<br />
* ''string text:''<br />
: The decho-valid converted text.<br />
* ''string colour:''<br />
: The ANSI code for the last used colour in the substitution (useful if you want to colour subsequent lines according to this colour).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local replaced = ansi2decho('\27[0;1;36;40mYou say in a baritone voice, "Test."\27[0;37;40m')<br />
-- 'replaced' should now contain <r><0,255,255:0,0,0>You say in a baritone voice, "Test."<r><192,192,192:0,0,0><br />
decho(replaced)<br />
</syntaxhighlight><br />
<br />
Or show a complete colourful squirrel! It's a lotta code to do all the colours, so click the '''Expand''' button on the right to show it:<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<syntaxhighlight lang="lua"><br />
decho(ansi2decho([[<br />
�[38;5;95m▄�[48;5;95;38;5;130m▄▄▄�[38;5;95m█�[49m▀�[0m �[0m<br />
╭───────────────────────╮ �[38;5;95m▄▄�[0m �[38;5;95m▄�[48;5;95;38;5;130m▄▄�[48;5;130m█�[38;5;137m▄�[48;5;137;38;5;95m▄�[49m▀�[0m �[0m<br />
│ │ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄▄▄�[48;5;95;38;5;137m▄▄▄�[49;38;5;95m▄▄�[48;5;95;38;5;130m▄�[48;5;130m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[0m �[0m<br />
│ Encrypt everything! │ �[38;5;95m▄�[48;5;187;38;5;16m▄�[48;5;16;38;5;187m▄�[38;5;16m█�[48;5;137;38;5;137m███�[38;5;187m▄�[38;5;16m▄▄�[38;5;137m██�[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[0m �[0m<br />
│ ├──── �[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;16m▄▄▄�[48;5;137m███�[48;5;16;38;5;16m█�[48;5;187m▄�[48;5;16m█�[48;5;137;38;5;137m█�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
╰───────────────────────╯ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;16m▄�[38;5;16m█�[38;5;137m▄�[48;5;137m██████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;95m▀�[48;5;137m▄�[38;5;137m███████�[38;5;95m▄�[49m▀�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[48;5;95;38;5;187m▄▄▄�[38;5;137m▄�[48;5;137m██�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[38;5;95m▀�[48;5;130m▄�[38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;187m████�[48;5;137;38;5;137m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m██�[38;5;95m▄�[38;5;137m█�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;187;38;5;187m████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95m██�[48;5;137m▄▄�[48;5;187;38;5;187m████�[48;5;137;38;5;95m▄▄�[48;5;95;38;5;137m▄�[48;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;187;38;5;187m███�[48;5;95m▄�[38;5;137m▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[49m▄�[48;5;95;38;5;130m▄�[48;5;130m██████�[48;5;137;38;5;137m███�[38;5;95m▄�[49m▀�[0m�[0m<br />
�[48;5;187;38;5;95m▄�[38;5;187m████�[48;5;137;38;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m█████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;137m▄�[38;5;187m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██████�[48;5;95m▄▄�[48;5;130m▄▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▄▄▄�[48;5;95;38;5;137m▄�[48;5;187m▄�[38;5;187m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m█████�[38;5;95m▄�[38;5;137m███████████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀�[48;5;187m▄▄▄�[48;5;95;38;5;137m▄�[48;5;137m██�[38;5;95m▄�[49m▀�[0m �[38;5;95m▀▀�[48;5;137m▄▄▄▄▄▄�[49m▀▀▀�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀▀�[0m �[0m<br />
]]))<br />
</syntaxhighlight><br />
</div><br />
<br />
[[File:Squirrel-in-Mudlet.png|frameless]]<br />
<br />
==cecho PR #5669 merged, PR5719 merged, PR5751 open==<br />
;cecho([window], text)<br />
: Echoes text that can be easily formatted with colour, italics, bold, strikethrough, and underline tags. You can also include unicode art in it - try some examples from [http://1lineart.kulaone.com/#/ 1lineart].<br />
: See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:UI Functions#creplaceLine|creplaceLine()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you cecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''window:''<br />
: Optional - the window name to echo to - can either be none or "main" for the main window, or a miniconsole, userwindow, or label name.<br />
* ''text:''<br />
: The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
cecho("Hi! This text is <red>red, <blue>blue, <green> and green.")<br />
<br />
cecho("<:green>Green background on normal foreground. Here we add an <ivory>ivory foreground.")<br />
<br />
cecho("<blue:yellow>Blue on yellow text!")<br />
<br />
cecho("\n<red>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, <o>overline</o>, and <b>bold</b>.")<br />
<br />
cecho("\n<green><o><u>Green text with over and underline at the same time.</o></u>")<br />
<br />
-- \n adds a new line<br />
cecho("<red>one line\n<green>another line\n<blue>last line")<br />
<br />
cecho("myinfo", "<green>All of this text is green in the myinfo miniconsole.")<br />
<br />
cecho("<green>(╯°□°)<dark_green>╯︵ ┻━┻")<br />
<br />
cecho("°º¤ø,¸¸,ø¤º°`°º¤ø,¸,ø¤°º¤ø,¸¸,ø¤º°`°º¤ø,¸")<br />
<br />
cecho([[<br />
██╗ ██╗ ██╗███╗ ██╗███████╗ █████╗ ██████╗ ████████╗<br />
███║ ██║ ██║████╗ ██║██╔════╝ ██╔══██╗██╔══██╗╚══██╔══╝<br />
╚██║ ██║ ██║██╔██╗ ██║█████╗ ███████║██████╔╝ ██║<br />
██║ ██║ ██║██║╚██╗██║██╔══╝ ██╔══██║██╔══██╗ ██║<br />
██║ ███████╗██║██║ ╚████║███████╗ ██║ ██║██║ ██║ ██║<br />
╚═╝ ╚══════╝╚═╝╚═╝ ╚═══╝╚══════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝<br />
]])<br />
</syntaxhighlight><br />
<br />
==cecho2ansi PR# 5672 merged==<br />
<br />
; ansiFormattedString = cecho2ansi(text)<br />
<br />
:Converts cecho formatted text to ansi formatted text. Used by cfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:Lua_Functions#cfeedTriggers|cfeedTriggers()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
{{note}} This function uses the ansi short colors (0-15) for color names which have base 16 ansi equivalents, such as 'red', 'blue', "lightBlue", "cyan", etc rather than the values defined in the color_table. If there is no base ansi equivalent then it will use the rgb values from the color_table for the color.<br />
<br />
;Parameters<br />
* ''text:''<br />
: The cecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of cfeedTriggers() for a single line.<br />
-- you would most likely just use cfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(cecho2ansi("\n<red>This is red.<reset> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
==decho PR #5669 merged PR5719 merged PR5751 open==<br />
;decho ([name of console,] text)<br />
: Color changes can be made using the format <FR,FG,FB:BR,BG,BB,[BA]> where each field is a number from 0 to 255. The background portion can be omitted using <FR,FG,FB> or the foreground portion can be omitted using <:BR,BG,BB,[BA]>. Arguments 2 and 3 set the default fore and background colors for the string using the same format as is used within the string, sans angle brackets, e.g. ''decho("<50,50,0:0,255,0>test")''.<br />
:You can also include <code><nowiki><i>italics</i></nowiki></code>, <code><nowiki><b>bold</b></nowiki></code>, <code><nowiki><s>strikethrough</s></nowiki></code>, <code><nowiki><o>overline</o></nowiki></code>, and <code><nowiki><u>underline</u></nowiki></code> tags.<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you decho it will erase any previous echo sent to the label.<br />
<br />
: See also: [[#cecho|cecho()]], [[#hecho|hecho()]], [[#copy2decho|copy2decho()]]<br />
<br />
;Parameters<br />
* ''name of console''<br />
: (Optional) Name of the console to echo to. If no name is given, this will defaults to the main window.<br />
* ''text:''<br />
: The text that you’d like to echo with embedded color tags. Tags take the RGB values only, see below for an explanation.<br />
<br />
<br />
{{note}}<br />
Optional background transparancy parameter (BA) available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
decho("<50,50,0:0,255,0>test")<br />
<br />
decho("miniconsolename", "<50,50,0:0,255,0>test")<br />
<br />
decho("\n<255,0,0>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, and <b>bold</b> formatting.")<br />
<br />
decho("<\n<0,128,0><o><u>Green text with both over and underlines.</u></o>")<br />
</syntaxhighlight><br />
<br />
==decho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = decho2ansi(text)<br />
<br />
:Converts decho formatted text to ansi formatted text. Used by dfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#dfeedTriggers|dfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The decho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of dfeedTriggers() for a single line.<br />
-- you would most likely just use dfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(decho2ansi("\n<128,0,0>This is red.<r> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
==getHTMLformat PR#5751 open==<br />
<br />
; spanTag = getHTMLformat(formatTable)<br />
<br />
:Takes in a table of formatting options in the same style as [[Manual:Lua_Functions#getTextFormat|getTextFormat()]] and returns a span tag which will format text after it as the table describes.<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formatTable:''<br />
: Table with formatting options configured. Keys are foreground, background, bold, underline, overline, strikeout, italic, and reverse. All except for foreground and background should be boolean (true/false) values. Foreground and background are either { r, g, b, a } tables, or strings with QSS formatting directives<br />
<br />
;Returns <br />
* A string with the html span tag to format text in accordance with the format table.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Returns a span tag for bold, red text on a green background<br />
local span = getHTMLformat({<br />
foreground = { 255, 0, 0 },<br />
background = "#00FF00",<br />
bold = true<br />
})<br />
<br />
-- span will be '<span style="color: rgb(255, 0, 0);background-color: #00FF00; font-weight: bold; font-style: normal; text-decoration: none;">'<br />
</syntaxhighlight><br />
<br />
==getLabelFormat PR#5751 open==<br />
<br />
; formatTable = getLabelFormat(labelName)<br />
<br />
:Returns a format table like the one returned by getTextFormat and suitable for getHTMLspan which will format text the same way as simply doing an echo to the label would<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getHTMLspan|getHTMLspan()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: The name of the label to scan the format of<br />
<br />
;Returns <br />
* A table with all the formatting options to achieve a default text format for label labelName. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- creates a test label, sets a stylesheet, and then returns the default format table for that label.<br />
createLabel("testLabel", 10, 10, 300, 200, 1)<br />
setLabelStyleSheet([[<br />
color: rgb(0,0,180);<br />
border-width: 1px;<br />
border-style: solid;<br />
border-color: gold;<br />
border-radius: 10px;<br />
font-size: 12.0pt;<br />
background: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #98f041, stop: 0.1 #8cf029, stop: 0.49 #66cc00, stop: 0.5 #52a300, stop: 1 #66cc00);<br />
]])<br />
local fmt = getLabelFormat("testLabel"))<br />
<br />
--[[<br />
{<br />
background = "rgba(0, 0, 0, 0)", -- this is transparent<br />
bold = false,<br />
foreground = "rgb(0,0,180)",<br />
italic = false,<br />
overline = false,<br />
reverse = false,<br />
strikeout = false,<br />
underline = false<br />
}<br />
--]]<br />
<br />
</syntaxhighlight><br />
<br />
==hecho PR #5669 merged, PR5719 merged, PR5751 open==<br />
;hecho([windowName], text)<br />
: Echoes text that can be easily formatted with colour tags in the hexadecimal format. You can also use italics, bold, strikethrough, and underline tags.<br />
: See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#cecho|cecho()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you hecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Can either be omitted or "main" for the main window, else specify the miniconsoles name.<br />
* ''text:''<br />
: The text to display, with color changes made within the string using the format |cFRFGFB,BRBGBB or #FRFGFB,BRBGBB where FR is the foreground red value, FG is the foreground green value, FB is the foreground blue value, BR is the background red value, etc., BRBGBB is optional. |r or #r can be used within the string to reset the colors to default. Hexadecimal color codes can be found here: https://www.color-hex.com/<br />
<br />
{{note}}<br />
Transparency for background in hex-format available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
hecho("\n#ffffff White text!")<br />
-- your text in white<br />
hecho("\n#ca0004 Red text! And now reset #rit to the default color")<br />
-- your text in red, then reset to default using #r<br />
hecho("\n#ffffff,ca0004 White text with a red background!")<br />
-- your text in white, against a red background<br />
hecho("\n|c0000ff Blue text, this time using |c instead of #")<br />
-- your text in blue, activated with |c vs #.<br />
hecho("\n#ff0000Red text with #iitalics#/i, |uunderline|/u, #ooverline#/o, #sstrikethrough#/s, and #bbold#/b formatting.")<br />
-- shows the various individual formatting options<br />
hecho("\n#008000#o#uGreen text with both over and underlines.#/o#/u")<br />
</syntaxhighlight><br />
<br />
==hecho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = hecho2ansi(text)<br />
<br />
:Converts hecho formatted text to ansi formatted text. Used by hfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:Lua_Functions#hfeedTriggers|hfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The hecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of hfeedTriggers() for a single line.<br />
-- you would most likely just use hfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(hecho2ansi("\n#800000This is red.#r #iitalic#/i, #bbold#/b, #sstrikethrough#/s, #uunderline#/u\n"))<br />
</syntaxhighlight><br />
<br />
==windowType PR# 5696 open==<br />
; typeOfWindow = windowType(windowName)<br />
<br />
:Given the name of a window, will return if it's a label, miniconsole, userwindow or a commandline.<br />
<br />
;See also: [[Manual:Lua_Functions#createLabel|createLabel()]], [[Manual:Lua_Functions#openUserWindow|openUserWindow()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name used to create the window element. Use "main" for the main console<br />
<br />
<br />
;Returns <br />
* Window type as string ("label", "miniconsole", "userwindow", or "commandline") or nil+error if it does not exist.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a Geyser label and and check its type<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
display(windowType(testLabel.name)) -- displays "label"<br />
<br />
-- the main console returns "miniconsole" because it uses the same formatting functions<br />
display(windowType("main")) -- displays "miniconsole"<br />
<br />
-- check for the existence of a window<br />
local windowName = "this thing does not exist"<br />
local ok, err = windowType(windowName)<br />
if ok then<br />
-- do things with it, as it does exist.<br />
-- the ok variable will hold the type of window it is ("label", "commandline", etc)<br />
else<br />
cecho("<red>ALERT!! window does not exist")<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
=Discord Functions=<br />
: 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 [[Special:MyLanguage/Manual:Scripting#Discord_Rich_Presence|Discord scripting overview]].</div>Demonnichttps://wiki.mudlet.org/index.php?title=Area_51&diff=18595Area 512022-01-01T17:00:27Z<p>Demonnic: /* string.escape PR 5806 */</p>
<hr />
<div>{{TOC right}}<br />
<br />
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 [[Manual:Lua_Functions|Lua Functions]] and its sub-sites. <br />
<br />
Please use the [[Area_51/Template]] to add new entries in the sections below.<br />
<br />
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.<br />
<br />
<br />
=Basic Essential Functions=<br />
:These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.<br />
<br />
=Database Functions=<br />
:A collection of functions for helping deal with the database.<br />
<br />
=Date/Time Functions=<br />
: A collection of functions for handling date & time.<br />
<br />
=File System Functions=<br />
: A collection of functions for interacting with the file system.<br />
<br />
=Mapper Functions=<br />
: A collection of functions that manipulate the mapper and its related features.<br />
<br />
==mapSymbolFontInfo, PR #4038 closed==<br />
;mapSymbolFontInfo()<br />
: See also: [[#setupMapSymbolFont|setupMapSymbolFont()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;returns<br />
* either a table of information about the configuration of the font used for symbols in the (2D) map, the elements are:<br />
:* ''fontName'' - a string of the family name of the font specified<br />
:* ''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.<br />
:* ''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).<br />
* or ''nil'' and an error message on failure.<br />
<br />
::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).<br />
<br />
<br />
==setupMapSymbolFont, PR #4038 closed==<br />
;setupMapSymbolFont(fontName[, onlyUseThisFont[, scalingFactor]])<br />
:configures the font used for symbols in the (2D) map.<br />
: See also: [[#mapSymbolFontInfo|mapSymbolFontInfo()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;Parameters<br />
* ''fontName'' one of:<br />
:* - a string that is the family name of the font to use;<br />
:* - the empty string ''""'' to reset to the default {which is '''"Bitstream Vera Sans Mono"'''};<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow a following one to be modified.<br />
* ''onlyUseThisFont'' (optional) one of:<br />
:* - 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;<br />
:* - 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;<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow the following one to be modified.<br />
* ''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.<br />
<br />
;Returns<br />
* ''true'' on success<br />
* ''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).<br />
<br />
=Miscellaneous Functions=<br />
: Miscellaneous functions.<br />
<br />
==getCharacterName, PR #3952 open==<br />
;getCharacterName()<br />
<br />
: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.<br />
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.<br />
<br />
:See also: [[#sendCharacterName|sendCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lua send("cast 'glamor' " .. getCharacterName())<br />
<br />
You get a warm feeling passing from your core to the tips of your hands, feet and other body parts.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A tawny long-haired cat saunters over and start to rub itself against your ankles.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A mangy dog trots up to you and proceeds to mark the bottom of your leggings.<br />
</syntaxhighlight><br />
<br />
==getCustomLoginTextId, PR #3952 open==<br />
;getCustomLoginTextId()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#sendPassword|sendPassword()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCharacterName, PR #3952 open==<br />
;sendCharacterName()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
==sendCharacterPassword, PR #3952 open==<br />
;sendCharacterPassword()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]], [[#sendCharacterName|sendCharacterName()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCharacterName() ~= "" then<br />
tempTime(2.0, [[sendCharacterName()]], 1)<br />
tempTime(3.0, [[sendCharacterPassword()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCustomLoginText, PR #3952 open==<br />
;sendCustomLoginText()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendPassword|sendPassword()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
=Mudlet Object Functions=<br />
: A collection of functions that manipulate Mudlets scripting objects - triggers, aliases, and so forth.<br />
<br />
=Networking Functions=<br />
: A collection of functions for managing networking.<br />
<br />
=String Functions=<br />
: These functions are used to manipulate strings.<br />
<br />
==string.escape PR 5806==<br />
; escapedString = string.escape(str)<br />
<br />
: Returns a version of str with all Lua pattern characters escaped to ensure string.match/find/etc look for the original str.<br />
<br />
;See also: [[Manual:Lua_Functions#string.trim|string.trim()]], [[Manual:Lua_Functions#string.genNocasePattern|string.genNocasePattern()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''str:''<br />
: The string to escape lua pattern characters in.<br />
<br />
;Returns <br />
* The string with all special Lua pattern characters escaped. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- searching for a url inside of a string. <br />
local helpString = [[<br />
This feature can be accessed by going to https://some-url.com/athing.html?param=value and<br />
retrieving the result!<br />
]]<br />
local url = "https://some-url.com/"<br />
display(helpString:find(url))<br />
-- nil<br />
display(helpString:find(url:escape()))<br />
-- 42<br />
-- 62<br />
display(url:escape())<br />
-- "https://some%-url%.com/"<br />
</syntaxhighlight><br />
<br />
=Table Functions=<br />
: 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.<br />
<br />
=Text to Speech Functions=<br />
: These functions are used to create sound from written words. Check out our [[Special:MyLanguage/Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.<br />
<br />
=UI Functions=<br />
: 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.<br />
<br />
==ansi2decho PR# 5670 merge, PR5719 merged==<br />
;ansi2decho(text, default_colour)<br />
: Converts ANSI colour sequences in <code>text</code> to colour tags that can be processed by the decho() function.<br />
: See also: [[Manual:Lua_Functions#decho|decho()]]<br />
<br />
{{MudletVersion|3.0}}<br />
{{note}} ANSI bold is available since Mudlet 3.7.1+.<br />
<br />
{{note}} underline, italics, overline, and strikethrough supported since Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: String that contains ANSI colour sequences that should be replaced.<br />
* ''default_colour:''<br />
: Optional - ANSI default colour code (used when handling orphan bold tags).<br />
<br />
;Return values<br />
* ''string text:''<br />
: The decho-valid converted text.<br />
* ''string colour:''<br />
: The ANSI code for the last used colour in the substitution (useful if you want to colour subsequent lines according to this colour).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local replaced = ansi2decho('\27[0;1;36;40mYou say in a baritone voice, "Test."\27[0;37;40m')<br />
-- 'replaced' should now contain <r><0,255,255:0,0,0>You say in a baritone voice, "Test."<r><192,192,192:0,0,0><br />
decho(replaced)<br />
</syntaxhighlight><br />
<br />
Or show a complete colourful squirrel! It's a lotta code to do all the colours, so click the '''Expand''' button on the right to show it:<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<syntaxhighlight lang="lua"><br />
decho(ansi2decho([[<br />
�[38;5;95m▄�[48;5;95;38;5;130m▄▄▄�[38;5;95m█�[49m▀�[0m �[0m<br />
╭───────────────────────╮ �[38;5;95m▄▄�[0m �[38;5;95m▄�[48;5;95;38;5;130m▄▄�[48;5;130m█�[38;5;137m▄�[48;5;137;38;5;95m▄�[49m▀�[0m �[0m<br />
│ │ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄▄▄�[48;5;95;38;5;137m▄▄▄�[49;38;5;95m▄▄�[48;5;95;38;5;130m▄�[48;5;130m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[0m �[0m<br />
│ Encrypt everything! │ �[38;5;95m▄�[48;5;187;38;5;16m▄�[48;5;16;38;5;187m▄�[38;5;16m█�[48;5;137;38;5;137m███�[38;5;187m▄�[38;5;16m▄▄�[38;5;137m██�[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[0m �[0m<br />
│ ├──── �[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;16m▄▄▄�[48;5;137m███�[48;5;16;38;5;16m█�[48;5;187m▄�[48;5;16m█�[48;5;137;38;5;137m█�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
╰───────────────────────╯ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;16m▄�[38;5;16m█�[38;5;137m▄�[48;5;137m██████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;95m▀�[48;5;137m▄�[38;5;137m███████�[38;5;95m▄�[49m▀�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[48;5;95;38;5;187m▄▄▄�[38;5;137m▄�[48;5;137m██�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[38;5;95m▀�[48;5;130m▄�[38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;187m████�[48;5;137;38;5;137m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m██�[38;5;95m▄�[38;5;137m█�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;187;38;5;187m████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95m██�[48;5;137m▄▄�[48;5;187;38;5;187m████�[48;5;137;38;5;95m▄▄�[48;5;95;38;5;137m▄�[48;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;187;38;5;187m███�[48;5;95m▄�[38;5;137m▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[49m▄�[48;5;95;38;5;130m▄�[48;5;130m██████�[48;5;137;38;5;137m███�[38;5;95m▄�[49m▀�[0m�[0m<br />
�[48;5;187;38;5;95m▄�[38;5;187m████�[48;5;137;38;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m█████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;137m▄�[38;5;187m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██████�[48;5;95m▄▄�[48;5;130m▄▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▄▄▄�[48;5;95;38;5;137m▄�[48;5;187m▄�[38;5;187m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m█████�[38;5;95m▄�[38;5;137m███████████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀�[48;5;187m▄▄▄�[48;5;95;38;5;137m▄�[48;5;137m██�[38;5;95m▄�[49m▀�[0m �[38;5;95m▀▀�[48;5;137m▄▄▄▄▄▄�[49m▀▀▀�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀▀�[0m �[0m<br />
]]))<br />
</syntaxhighlight><br />
</div><br />
<br />
[[File:Squirrel-in-Mudlet.png|frameless]]<br />
<br />
==cecho PR #5669 merged, PR5719 merged, PR5751 open==<br />
;cecho([window], text)<br />
: Echoes text that can be easily formatted with colour, italics, bold, strikethrough, and underline tags. You can also include unicode art in it - try some examples from [http://1lineart.kulaone.com/#/ 1lineart].<br />
: See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:UI Functions#creplaceLine|creplaceLine()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you cecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''window:''<br />
: Optional - the window name to echo to - can either be none or "main" for the main window, or a miniconsole, userwindow, or label name.<br />
* ''text:''<br />
: The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
cecho("Hi! This text is <red>red, <blue>blue, <green> and green.")<br />
<br />
cecho("<:green>Green background on normal foreground. Here we add an <ivory>ivory foreground.")<br />
<br />
cecho("<blue:yellow>Blue on yellow text!")<br />
<br />
cecho("\n<red>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, <o>overline</o>, and <b>bold</b>.")<br />
<br />
cecho("\n<green><o><u>Green text with over and underline at the same time.</o></u>")<br />
<br />
-- \n adds a new line<br />
cecho("<red>one line\n<green>another line\n<blue>last line")<br />
<br />
cecho("myinfo", "<green>All of this text is green in the myinfo miniconsole.")<br />
<br />
cecho("<green>(╯°□°)<dark_green>╯︵ ┻━┻")<br />
<br />
cecho("°º¤ø,¸¸,ø¤º°`°º¤ø,¸,ø¤°º¤ø,¸¸,ø¤º°`°º¤ø,¸")<br />
<br />
cecho([[<br />
██╗ ██╗ ██╗███╗ ██╗███████╗ █████╗ ██████╗ ████████╗<br />
███║ ██║ ██║████╗ ██║██╔════╝ ██╔══██╗██╔══██╗╚══██╔══╝<br />
╚██║ ██║ ██║██╔██╗ ██║█████╗ ███████║██████╔╝ ██║<br />
██║ ██║ ██║██║╚██╗██║██╔══╝ ██╔══██║██╔══██╗ ██║<br />
██║ ███████╗██║██║ ╚████║███████╗ ██║ ██║██║ ██║ ██║<br />
╚═╝ ╚══════╝╚═╝╚═╝ ╚═══╝╚══════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝<br />
]])<br />
</syntaxhighlight><br />
<br />
==cecho2ansi PR# 5672 merged==<br />
<br />
; ansiFormattedString = cecho2ansi(text)<br />
<br />
:Converts cecho formatted text to ansi formatted text. Used by cfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:Lua_Functions#cfeedTriggers|cfeedTriggers()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
{{note}} This function uses the ansi short colors (0-15) for color names which have base 16 ansi equivalents, such as 'red', 'blue', "lightBlue", "cyan", etc rather than the values defined in the color_table. If there is no base ansi equivalent then it will use the rgb values from the color_table for the color.<br />
<br />
;Parameters<br />
* ''text:''<br />
: The cecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of cfeedTriggers() for a single line.<br />
-- you would most likely just use cfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(cecho2ansi("\n<red>This is red.<reset> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
==decho PR #5669 merged PR5719 merged PR5751 open==<br />
;decho ([name of console,] text)<br />
: Color changes can be made using the format <FR,FG,FB:BR,BG,BB,[BA]> where each field is a number from 0 to 255. The background portion can be omitted using <FR,FG,FB> or the foreground portion can be omitted using <:BR,BG,BB,[BA]>. Arguments 2 and 3 set the default fore and background colors for the string using the same format as is used within the string, sans angle brackets, e.g. ''decho("<50,50,0:0,255,0>test")''.<br />
:You can also include <code><nowiki><i>italics</i></nowiki></code>, <code><nowiki><b>bold</b></nowiki></code>, <code><nowiki><s>strikethrough</s></nowiki></code>, <code><nowiki><o>overline</o></nowiki></code>, and <code><nowiki><u>underline</u></nowiki></code> tags.<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you decho it will erase any previous echo sent to the label.<br />
<br />
: See also: [[#cecho|cecho()]], [[#hecho|hecho()]], [[#copy2decho|copy2decho()]]<br />
<br />
;Parameters<br />
* ''name of console''<br />
: (Optional) Name of the console to echo to. If no name is given, this will defaults to the main window.<br />
* ''text:''<br />
: The text that you’d like to echo with embedded color tags. Tags take the RGB values only, see below for an explanation.<br />
<br />
<br />
{{note}}<br />
Optional background transparancy parameter (BA) available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
decho("<50,50,0:0,255,0>test")<br />
<br />
decho("miniconsolename", "<50,50,0:0,255,0>test")<br />
<br />
decho("\n<255,0,0>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, and <b>bold</b> formatting.")<br />
<br />
decho("<\n<0,128,0><o><u>Green text with both over and underlines.</u></o>")<br />
</syntaxhighlight><br />
<br />
==decho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = decho2ansi(text)<br />
<br />
:Converts decho formatted text to ansi formatted text. Used by dfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#dfeedTriggers|dfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The decho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of dfeedTriggers() for a single line.<br />
-- you would most likely just use dfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(decho2ansi("\n<128,0,0>This is red.<r> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
==getHTMLformat PR#5751 open==<br />
<br />
; spanTag = getHTMLformat(formatTable)<br />
<br />
:Takes in a table of formatting options in the same style as [[Manual:Lua_Functions#getTextFormat|getTextFormat()]] and returns a span tag which will format text after it as the table describes.<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formatTable:''<br />
: Table with formatting options configured. Keys are foreground, background, bold, underline, overline, strikeout, italic, and reverse. All except for foreground and background should be boolean (true/false) values. Foreground and background are either { r, g, b, a } tables, or strings with QSS formatting directives<br />
<br />
;Returns <br />
* A string with the html span tag to format text in accordance with the format table.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Returns a span tag for bold, red text on a green background<br />
local span = getHTMLformat({<br />
foreground = { 255, 0, 0 },<br />
background = "#00FF00",<br />
bold = true<br />
})<br />
<br />
-- span will be '<span style="color: rgb(255, 0, 0);background-color: #00FF00; font-weight: bold; font-style: normal; text-decoration: none;">'<br />
</syntaxhighlight><br />
<br />
==getLabelFormat PR#5751 open==<br />
<br />
; formatTable = getLabelFormat(labelName)<br />
<br />
:Returns a format table like the one returned by getTextFormat and suitable for getHTMLspan which will format text the same way as simply doing an echo to the label would<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getHTMLspan|getHTMLspan()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: The name of the label to scan the format of<br />
<br />
;Returns <br />
* A table with all the formatting options to achieve a default text format for label labelName. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- creates a test label, sets a stylesheet, and then returns the default format table for that label.<br />
createLabel("testLabel", 10, 10, 300, 200, 1)<br />
setLabelStyleSheet([[<br />
color: rgb(0,0,180);<br />
border-width: 1px;<br />
border-style: solid;<br />
border-color: gold;<br />
border-radius: 10px;<br />
font-size: 12.0pt;<br />
background: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #98f041, stop: 0.1 #8cf029, stop: 0.49 #66cc00, stop: 0.5 #52a300, stop: 1 #66cc00);<br />
]])<br />
local fmt = getLabelFormat("testLabel"))<br />
<br />
--[[<br />
{<br />
background = "rgba(0, 0, 0, 0)", -- this is transparent<br />
bold = false,<br />
foreground = "rgb(0,0,180)",<br />
italic = false,<br />
overline = false,<br />
reverse = false,<br />
strikeout = false,<br />
underline = false<br />
}<br />
--]]<br />
<br />
</syntaxhighlight><br />
<br />
==hecho PR #5669 merged, PR5719 merged, PR5751 open==<br />
;hecho([windowName], text)<br />
: Echoes text that can be easily formatted with colour tags in the hexadecimal format. You can also use italics, bold, strikethrough, and underline tags.<br />
: See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#cecho|cecho()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you hecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Can either be omitted or "main" for the main window, else specify the miniconsoles name.<br />
* ''text:''<br />
: The text to display, with color changes made within the string using the format |cFRFGFB,BRBGBB or #FRFGFB,BRBGBB where FR is the foreground red value, FG is the foreground green value, FB is the foreground blue value, BR is the background red value, etc., BRBGBB is optional. |r or #r can be used within the string to reset the colors to default. Hexadecimal color codes can be found here: https://www.color-hex.com/<br />
<br />
{{note}}<br />
Transparency for background in hex-format available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
hecho("\n#ffffff White text!")<br />
-- your text in white<br />
hecho("\n#ca0004 Red text! And now reset #rit to the default color")<br />
-- your text in red, then reset to default using #r<br />
hecho("\n#ffffff,ca0004 White text with a red background!")<br />
-- your text in white, against a red background<br />
hecho("\n|c0000ff Blue text, this time using |c instead of #")<br />
-- your text in blue, activated with |c vs #.<br />
hecho("\n#ff0000Red text with #iitalics#/i, |uunderline|/u, #ooverline#/o, #sstrikethrough#/s, and #bbold#/b formatting.")<br />
-- shows the various individual formatting options<br />
hecho("\n#008000#o#uGreen text with both over and underlines.#/o#/u")<br />
</syntaxhighlight><br />
<br />
==hecho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = hecho2ansi(text)<br />
<br />
:Converts hecho formatted text to ansi formatted text. Used by hfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:Lua_Functions#hfeedTriggers|hfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The hecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of hfeedTriggers() for a single line.<br />
-- you would most likely just use hfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(hecho2ansi("\n#800000This is red.#r #iitalic#/i, #bbold#/b, #sstrikethrough#/s, #uunderline#/u\n"))<br />
</syntaxhighlight><br />
<br />
==windowType PR# 5696 open==<br />
; typeOfWindow = windowType(windowName)<br />
<br />
:Given the name of a window, will return if it's a label, miniconsole, userwindow or a commandline.<br />
<br />
;See also: [[Manual:Lua_Functions#createLabel|createLabel()]], [[Manual:Lua_Functions#openUserWindow|openUserWindow()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name used to create the window element. Use "main" for the main console<br />
<br />
<br />
;Returns <br />
* Window type as string ("label", "miniconsole", "userwindow", or "commandline") or nil+error if it does not exist.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a Geyser label and and check its type<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
display(windowType(testLabel.name)) -- displays "label"<br />
<br />
-- the main console returns "miniconsole" because it uses the same formatting functions<br />
display(windowType("main")) -- displays "miniconsole"<br />
<br />
-- check for the existence of a window<br />
local windowName = "this thing does not exist"<br />
local ok, err = windowType(windowName)<br />
if ok then<br />
-- do things with it, as it does exist.<br />
-- the ok variable will hold the type of window it is ("label", "commandline", etc)<br />
else<br />
cecho("<red>ALERT!! window does not exist")<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
=Discord Functions=<br />
: 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 [[Special:MyLanguage/Manual:Scripting#Discord_Rich_Presence|Discord scripting overview]].</div>Demonnichttps://wiki.mudlet.org/index.php?title=Area_51&diff=18594Area 512022-01-01T16:58:16Z<p>Demonnic: /* String Functions */</p>
<hr />
<div>{{TOC right}}<br />
<br />
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 [[Manual:Lua_Functions|Lua Functions]] and its sub-sites. <br />
<br />
Please use the [[Area_51/Template]] to add new entries in the sections below.<br />
<br />
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.<br />
<br />
<br />
=Basic Essential Functions=<br />
:These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.<br />
<br />
=Database Functions=<br />
:A collection of functions for helping deal with the database.<br />
<br />
=Date/Time Functions=<br />
: A collection of functions for handling date & time.<br />
<br />
=File System Functions=<br />
: A collection of functions for interacting with the file system.<br />
<br />
=Mapper Functions=<br />
: A collection of functions that manipulate the mapper and its related features.<br />
<br />
==mapSymbolFontInfo, PR #4038 closed==<br />
;mapSymbolFontInfo()<br />
: See also: [[#setupMapSymbolFont|setupMapSymbolFont()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;returns<br />
* either a table of information about the configuration of the font used for symbols in the (2D) map, the elements are:<br />
:* ''fontName'' - a string of the family name of the font specified<br />
:* ''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.<br />
:* ''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).<br />
* or ''nil'' and an error message on failure.<br />
<br />
::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).<br />
<br />
<br />
==setupMapSymbolFont, PR #4038 closed==<br />
;setupMapSymbolFont(fontName[, onlyUseThisFont[, scalingFactor]])<br />
:configures the font used for symbols in the (2D) map.<br />
: See also: [[#mapSymbolFontInfo|mapSymbolFontInfo()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;Parameters<br />
* ''fontName'' one of:<br />
:* - a string that is the family name of the font to use;<br />
:* - the empty string ''""'' to reset to the default {which is '''"Bitstream Vera Sans Mono"'''};<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow a following one to be modified.<br />
* ''onlyUseThisFont'' (optional) one of:<br />
:* - 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;<br />
:* - 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;<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow the following one to be modified.<br />
* ''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.<br />
<br />
;Returns<br />
* ''true'' on success<br />
* ''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).<br />
<br />
=Miscellaneous Functions=<br />
: Miscellaneous functions.<br />
<br />
==getCharacterName, PR #3952 open==<br />
;getCharacterName()<br />
<br />
: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.<br />
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.<br />
<br />
:See also: [[#sendCharacterName|sendCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lua send("cast 'glamor' " .. getCharacterName())<br />
<br />
You get a warm feeling passing from your core to the tips of your hands, feet and other body parts.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A tawny long-haired cat saunters over and start to rub itself against your ankles.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A mangy dog trots up to you and proceeds to mark the bottom of your leggings.<br />
</syntaxhighlight><br />
<br />
==getCustomLoginTextId, PR #3952 open==<br />
;getCustomLoginTextId()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#sendPassword|sendPassword()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCharacterName, PR #3952 open==<br />
;sendCharacterName()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
==sendCharacterPassword, PR #3952 open==<br />
;sendCharacterPassword()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]], [[#sendCharacterName|sendCharacterName()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCharacterName() ~= "" then<br />
tempTime(2.0, [[sendCharacterName()]], 1)<br />
tempTime(3.0, [[sendCharacterPassword()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCustomLoginText, PR #3952 open==<br />
;sendCustomLoginText()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendPassword|sendPassword()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
=Mudlet Object Functions=<br />
: A collection of functions that manipulate Mudlets scripting objects - triggers, aliases, and so forth.<br />
<br />
=Networking Functions=<br />
: A collection of functions for managing networking.<br />
<br />
=String Functions=<br />
: These functions are used to manipulate strings.<br />
<br />
==string.escape PR 5806==<br />
; escapedString = string.escape(str)<br />
<br />
: Returns a version of str with all Lua pattern characters escaped to ensure string.match/find/etc look for the original str.<br />
<br />
;See also: [[Manual:Lua_Functions#string.trim|string.trim()]], [[Manual:Lua_Functions#string.genNoCasePattern|string.genNoCasePattern()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''str:''<br />
: The string to escape lua pattern characters in.<br />
<br />
;Returns <br />
* The string with all special Lua pattern characters escaped. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- searching for a url inside of a string. <br />
local helpString = [[<br />
This feature can be accessed by going to https://some-url.com/athing.html?param=value and<br />
retrieving the result!<br />
]]<br />
local url = "https://some-url.com/"<br />
display(helpString:find(url))<br />
-- nil<br />
display(helpString:find(url:escape()))<br />
-- 42<br />
-- 62<br />
display(url:escape())<br />
-- "https://some%-url%.com/"<br />
</syntaxhighlight><br />
<br />
=Table Functions=<br />
: 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.<br />
<br />
=Text to Speech Functions=<br />
: These functions are used to create sound from written words. Check out our [[Special:MyLanguage/Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.<br />
<br />
=UI Functions=<br />
: 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.<br />
<br />
==ansi2decho PR# 5670 merge, PR5719 merged==<br />
;ansi2decho(text, default_colour)<br />
: Converts ANSI colour sequences in <code>text</code> to colour tags that can be processed by the decho() function.<br />
: See also: [[Manual:Lua_Functions#decho|decho()]]<br />
<br />
{{MudletVersion|3.0}}<br />
{{note}} ANSI bold is available since Mudlet 3.7.1+.<br />
<br />
{{note}} underline, italics, overline, and strikethrough supported since Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: String that contains ANSI colour sequences that should be replaced.<br />
* ''default_colour:''<br />
: Optional - ANSI default colour code (used when handling orphan bold tags).<br />
<br />
;Return values<br />
* ''string text:''<br />
: The decho-valid converted text.<br />
* ''string colour:''<br />
: The ANSI code for the last used colour in the substitution (useful if you want to colour subsequent lines according to this colour).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local replaced = ansi2decho('\27[0;1;36;40mYou say in a baritone voice, "Test."\27[0;37;40m')<br />
-- 'replaced' should now contain <r><0,255,255:0,0,0>You say in a baritone voice, "Test."<r><192,192,192:0,0,0><br />
decho(replaced)<br />
</syntaxhighlight><br />
<br />
Or show a complete colourful squirrel! It's a lotta code to do all the colours, so click the '''Expand''' button on the right to show it:<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<syntaxhighlight lang="lua"><br />
decho(ansi2decho([[<br />
�[38;5;95m▄�[48;5;95;38;5;130m▄▄▄�[38;5;95m█�[49m▀�[0m �[0m<br />
╭───────────────────────╮ �[38;5;95m▄▄�[0m �[38;5;95m▄�[48;5;95;38;5;130m▄▄�[48;5;130m█�[38;5;137m▄�[48;5;137;38;5;95m▄�[49m▀�[0m �[0m<br />
│ │ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄▄▄�[48;5;95;38;5;137m▄▄▄�[49;38;5;95m▄▄�[48;5;95;38;5;130m▄�[48;5;130m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[0m �[0m<br />
│ Encrypt everything! │ �[38;5;95m▄�[48;5;187;38;5;16m▄�[48;5;16;38;5;187m▄�[38;5;16m█�[48;5;137;38;5;137m███�[38;5;187m▄�[38;5;16m▄▄�[38;5;137m██�[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[0m �[0m<br />
│ ├──── �[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;16m▄▄▄�[48;5;137m███�[48;5;16;38;5;16m█�[48;5;187m▄�[48;5;16m█�[48;5;137;38;5;137m█�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
╰───────────────────────╯ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;16m▄�[38;5;16m█�[38;5;137m▄�[48;5;137m██████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;95m▀�[48;5;137m▄�[38;5;137m███████�[38;5;95m▄�[49m▀�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[48;5;95;38;5;187m▄▄▄�[38;5;137m▄�[48;5;137m██�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[38;5;95m▀�[48;5;130m▄�[38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;187m████�[48;5;137;38;5;137m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m██�[38;5;95m▄�[38;5;137m█�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;187;38;5;187m████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95m██�[48;5;137m▄▄�[48;5;187;38;5;187m████�[48;5;137;38;5;95m▄▄�[48;5;95;38;5;137m▄�[48;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;187;38;5;187m███�[48;5;95m▄�[38;5;137m▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[49m▄�[48;5;95;38;5;130m▄�[48;5;130m██████�[48;5;137;38;5;137m███�[38;5;95m▄�[49m▀�[0m�[0m<br />
�[48;5;187;38;5;95m▄�[38;5;187m████�[48;5;137;38;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m█████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;137m▄�[38;5;187m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██████�[48;5;95m▄▄�[48;5;130m▄▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▄▄▄�[48;5;95;38;5;137m▄�[48;5;187m▄�[38;5;187m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m█████�[38;5;95m▄�[38;5;137m███████████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀�[48;5;187m▄▄▄�[48;5;95;38;5;137m▄�[48;5;137m██�[38;5;95m▄�[49m▀�[0m �[38;5;95m▀▀�[48;5;137m▄▄▄▄▄▄�[49m▀▀▀�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀▀�[0m �[0m<br />
]]))<br />
</syntaxhighlight><br />
</div><br />
<br />
[[File:Squirrel-in-Mudlet.png|frameless]]<br />
<br />
==cecho PR #5669 merged, PR5719 merged, PR5751 open==<br />
;cecho([window], text)<br />
: Echoes text that can be easily formatted with colour, italics, bold, strikethrough, and underline tags. You can also include unicode art in it - try some examples from [http://1lineart.kulaone.com/#/ 1lineart].<br />
: See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:UI Functions#creplaceLine|creplaceLine()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you cecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''window:''<br />
: Optional - the window name to echo to - can either be none or "main" for the main window, or a miniconsole, userwindow, or label name.<br />
* ''text:''<br />
: The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
cecho("Hi! This text is <red>red, <blue>blue, <green> and green.")<br />
<br />
cecho("<:green>Green background on normal foreground. Here we add an <ivory>ivory foreground.")<br />
<br />
cecho("<blue:yellow>Blue on yellow text!")<br />
<br />
cecho("\n<red>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, <o>overline</o>, and <b>bold</b>.")<br />
<br />
cecho("\n<green><o><u>Green text with over and underline at the same time.</o></u>")<br />
<br />
-- \n adds a new line<br />
cecho("<red>one line\n<green>another line\n<blue>last line")<br />
<br />
cecho("myinfo", "<green>All of this text is green in the myinfo miniconsole.")<br />
<br />
cecho("<green>(╯°□°)<dark_green>╯︵ ┻━┻")<br />
<br />
cecho("°º¤ø,¸¸,ø¤º°`°º¤ø,¸,ø¤°º¤ø,¸¸,ø¤º°`°º¤ø,¸")<br />
<br />
cecho([[<br />
██╗ ██╗ ██╗███╗ ██╗███████╗ █████╗ ██████╗ ████████╗<br />
███║ ██║ ██║████╗ ██║██╔════╝ ██╔══██╗██╔══██╗╚══██╔══╝<br />
╚██║ ██║ ██║██╔██╗ ██║█████╗ ███████║██████╔╝ ██║<br />
██║ ██║ ██║██║╚██╗██║██╔══╝ ██╔══██║██╔══██╗ ██║<br />
██║ ███████╗██║██║ ╚████║███████╗ ██║ ██║██║ ██║ ██║<br />
╚═╝ ╚══════╝╚═╝╚═╝ ╚═══╝╚══════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝<br />
]])<br />
</syntaxhighlight><br />
<br />
==cecho2ansi PR# 5672 merged==<br />
<br />
; ansiFormattedString = cecho2ansi(text)<br />
<br />
:Converts cecho formatted text to ansi formatted text. Used by cfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:Lua_Functions#cfeedTriggers|cfeedTriggers()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
{{note}} This function uses the ansi short colors (0-15) for color names which have base 16 ansi equivalents, such as 'red', 'blue', "lightBlue", "cyan", etc rather than the values defined in the color_table. If there is no base ansi equivalent then it will use the rgb values from the color_table for the color.<br />
<br />
;Parameters<br />
* ''text:''<br />
: The cecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of cfeedTriggers() for a single line.<br />
-- you would most likely just use cfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(cecho2ansi("\n<red>This is red.<reset> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
==decho PR #5669 merged PR5719 merged PR5751 open==<br />
;decho ([name of console,] text)<br />
: Color changes can be made using the format <FR,FG,FB:BR,BG,BB,[BA]> where each field is a number from 0 to 255. The background portion can be omitted using <FR,FG,FB> or the foreground portion can be omitted using <:BR,BG,BB,[BA]>. Arguments 2 and 3 set the default fore and background colors for the string using the same format as is used within the string, sans angle brackets, e.g. ''decho("<50,50,0:0,255,0>test")''.<br />
:You can also include <code><nowiki><i>italics</i></nowiki></code>, <code><nowiki><b>bold</b></nowiki></code>, <code><nowiki><s>strikethrough</s></nowiki></code>, <code><nowiki><o>overline</o></nowiki></code>, and <code><nowiki><u>underline</u></nowiki></code> tags.<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you decho it will erase any previous echo sent to the label.<br />
<br />
: See also: [[#cecho|cecho()]], [[#hecho|hecho()]], [[#copy2decho|copy2decho()]]<br />
<br />
;Parameters<br />
* ''name of console''<br />
: (Optional) Name of the console to echo to. If no name is given, this will defaults to the main window.<br />
* ''text:''<br />
: The text that you’d like to echo with embedded color tags. Tags take the RGB values only, see below for an explanation.<br />
<br />
<br />
{{note}}<br />
Optional background transparancy parameter (BA) available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
decho("<50,50,0:0,255,0>test")<br />
<br />
decho("miniconsolename", "<50,50,0:0,255,0>test")<br />
<br />
decho("\n<255,0,0>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, and <b>bold</b> formatting.")<br />
<br />
decho("<\n<0,128,0><o><u>Green text with both over and underlines.</u></o>")<br />
</syntaxhighlight><br />
<br />
==decho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = decho2ansi(text)<br />
<br />
:Converts decho formatted text to ansi formatted text. Used by dfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#dfeedTriggers|dfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The decho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of dfeedTriggers() for a single line.<br />
-- you would most likely just use dfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(decho2ansi("\n<128,0,0>This is red.<r> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
==getHTMLformat PR#5751 open==<br />
<br />
; spanTag = getHTMLformat(formatTable)<br />
<br />
:Takes in a table of formatting options in the same style as [[Manual:Lua_Functions#getTextFormat|getTextFormat()]] and returns a span tag which will format text after it as the table describes.<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formatTable:''<br />
: Table with formatting options configured. Keys are foreground, background, bold, underline, overline, strikeout, italic, and reverse. All except for foreground and background should be boolean (true/false) values. Foreground and background are either { r, g, b, a } tables, or strings with QSS formatting directives<br />
<br />
;Returns <br />
* A string with the html span tag to format text in accordance with the format table.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Returns a span tag for bold, red text on a green background<br />
local span = getHTMLformat({<br />
foreground = { 255, 0, 0 },<br />
background = "#00FF00",<br />
bold = true<br />
})<br />
<br />
-- span will be '<span style="color: rgb(255, 0, 0);background-color: #00FF00; font-weight: bold; font-style: normal; text-decoration: none;">'<br />
</syntaxhighlight><br />
<br />
==getLabelFormat PR#5751 open==<br />
<br />
; formatTable = getLabelFormat(labelName)<br />
<br />
:Returns a format table like the one returned by getTextFormat and suitable for getHTMLspan which will format text the same way as simply doing an echo to the label would<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getHTMLspan|getHTMLspan()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: The name of the label to scan the format of<br />
<br />
;Returns <br />
* A table with all the formatting options to achieve a default text format for label labelName. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- creates a test label, sets a stylesheet, and then returns the default format table for that label.<br />
createLabel("testLabel", 10, 10, 300, 200, 1)<br />
setLabelStyleSheet([[<br />
color: rgb(0,0,180);<br />
border-width: 1px;<br />
border-style: solid;<br />
border-color: gold;<br />
border-radius: 10px;<br />
font-size: 12.0pt;<br />
background: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #98f041, stop: 0.1 #8cf029, stop: 0.49 #66cc00, stop: 0.5 #52a300, stop: 1 #66cc00);<br />
]])<br />
local fmt = getLabelFormat("testLabel"))<br />
<br />
--[[<br />
{<br />
background = "rgba(0, 0, 0, 0)", -- this is transparent<br />
bold = false,<br />
foreground = "rgb(0,0,180)",<br />
italic = false,<br />
overline = false,<br />
reverse = false,<br />
strikeout = false,<br />
underline = false<br />
}<br />
--]]<br />
<br />
</syntaxhighlight><br />
<br />
==hecho PR #5669 merged, PR5719 merged, PR5751 open==<br />
;hecho([windowName], text)<br />
: Echoes text that can be easily formatted with colour tags in the hexadecimal format. You can also use italics, bold, strikethrough, and underline tags.<br />
: See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#cecho|cecho()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you hecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Can either be omitted or "main" for the main window, else specify the miniconsoles name.<br />
* ''text:''<br />
: The text to display, with color changes made within the string using the format |cFRFGFB,BRBGBB or #FRFGFB,BRBGBB where FR is the foreground red value, FG is the foreground green value, FB is the foreground blue value, BR is the background red value, etc., BRBGBB is optional. |r or #r can be used within the string to reset the colors to default. Hexadecimal color codes can be found here: https://www.color-hex.com/<br />
<br />
{{note}}<br />
Transparency for background in hex-format available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
hecho("\n#ffffff White text!")<br />
-- your text in white<br />
hecho("\n#ca0004 Red text! And now reset #rit to the default color")<br />
-- your text in red, then reset to default using #r<br />
hecho("\n#ffffff,ca0004 White text with a red background!")<br />
-- your text in white, against a red background<br />
hecho("\n|c0000ff Blue text, this time using |c instead of #")<br />
-- your text in blue, activated with |c vs #.<br />
hecho("\n#ff0000Red text with #iitalics#/i, |uunderline|/u, #ooverline#/o, #sstrikethrough#/s, and #bbold#/b formatting.")<br />
-- shows the various individual formatting options<br />
hecho("\n#008000#o#uGreen text with both over and underlines.#/o#/u")<br />
</syntaxhighlight><br />
<br />
==hecho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = hecho2ansi(text)<br />
<br />
:Converts hecho formatted text to ansi formatted text. Used by hfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:Lua_Functions#hfeedTriggers|hfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The hecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of hfeedTriggers() for a single line.<br />
-- you would most likely just use hfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(hecho2ansi("\n#800000This is red.#r #iitalic#/i, #bbold#/b, #sstrikethrough#/s, #uunderline#/u\n"))<br />
</syntaxhighlight><br />
<br />
==windowType PR# 5696 open==<br />
; typeOfWindow = windowType(windowName)<br />
<br />
:Given the name of a window, will return if it's a label, miniconsole, userwindow or a commandline.<br />
<br />
;See also: [[Manual:Lua_Functions#createLabel|createLabel()]], [[Manual:Lua_Functions#openUserWindow|openUserWindow()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name used to create the window element. Use "main" for the main console<br />
<br />
<br />
;Returns <br />
* Window type as string ("label", "miniconsole", "userwindow", or "commandline") or nil+error if it does not exist.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a Geyser label and and check its type<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
display(windowType(testLabel.name)) -- displays "label"<br />
<br />
-- the main console returns "miniconsole" because it uses the same formatting functions<br />
display(windowType("main")) -- displays "miniconsole"<br />
<br />
-- check for the existence of a window<br />
local windowName = "this thing does not exist"<br />
local ok, err = windowType(windowName)<br />
if ok then<br />
-- do things with it, as it does exist.<br />
-- the ok variable will hold the type of window it is ("label", "commandline", etc)<br />
else<br />
cecho("<red>ALERT!! window does not exist")<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
=Discord Functions=<br />
: 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 [[Special:MyLanguage/Manual:Scripting#Discord_Rich_Presence|Discord scripting overview]].</div>Demonnichttps://wiki.mudlet.org/index.php?title=Area_51&diff=18544Area 512021-12-24T03:14:40Z<p>Demonnic: /* getHTMLspan PR#5751 open */</p>
<hr />
<div>{{TOC right}}<br />
<br />
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 [[Manual:Lua_Functions|Lua Functions]] and its sub-sites. <br />
<br />
Please use the [[Area_51/Template]] to add new entries in the sections below.<br />
<br />
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.<br />
<br />
<br />
=Basic Essential Functions=<br />
:These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.<br />
<br />
=Database Functions=<br />
:A collection of functions for helping deal with the database.<br />
<br />
=Date/Time Functions=<br />
: A collection of functions for handling date & time.<br />
<br />
=File System Functions=<br />
: A collection of functions for interacting with the file system.<br />
<br />
=Mapper Functions=<br />
: A collection of functions that manipulate the mapper and its related features.<br />
<br />
==mapSymbolFontInfo, PR #4038 closed==<br />
;mapSymbolFontInfo()<br />
: See also: [[#setupMapSymbolFont|setupMapSymbolFont()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;returns<br />
* either a table of information about the configuration of the font used for symbols in the (2D) map, the elements are:<br />
:* ''fontName'' - a string of the family name of the font specified<br />
:* ''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.<br />
:* ''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).<br />
* or ''nil'' and an error message on failure.<br />
<br />
::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).<br />
<br />
<br />
==setupMapSymbolFont, PR #4038 closed==<br />
;setupMapSymbolFont(fontName[, onlyUseThisFont[, scalingFactor]])<br />
:configures the font used for symbols in the (2D) map.<br />
: See also: [[#mapSymbolFontInfo|mapSymbolFontInfo()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;Parameters<br />
* ''fontName'' one of:<br />
:* - a string that is the family name of the font to use;<br />
:* - the empty string ''""'' to reset to the default {which is '''"Bitstream Vera Sans Mono"'''};<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow a following one to be modified.<br />
* ''onlyUseThisFont'' (optional) one of:<br />
:* - 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;<br />
:* - 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;<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow the following one to be modified.<br />
* ''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.<br />
<br />
;Returns<br />
* ''true'' on success<br />
* ''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).<br />
<br />
=Miscellaneous Functions=<br />
: Miscellaneous functions.<br />
<br />
==getCharacterName, PR #3952 open==<br />
;getCharacterName()<br />
<br />
: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.<br />
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.<br />
<br />
:See also: [[#sendCharacterName|sendCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lua send("cast 'glamor' " .. getCharacterName())<br />
<br />
You get a warm feeling passing from your core to the tips of your hands, feet and other body parts.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A tawny long-haired cat saunters over and start to rub itself against your ankles.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A mangy dog trots up to you and proceeds to mark the bottom of your leggings.<br />
</syntaxhighlight><br />
<br />
==getCustomLoginTextId, PR #3952 open==<br />
;getCustomLoginTextId()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#sendPassword|sendPassword()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCharacterName, PR #3952 open==<br />
;sendCharacterName()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
==sendCharacterPassword, PR #3952 open==<br />
;sendCharacterPassword()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]], [[#sendCharacterName|sendCharacterName()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCharacterName() ~= "" then<br />
tempTime(2.0, [[sendCharacterName()]], 1)<br />
tempTime(3.0, [[sendCharacterPassword()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCustomLoginText, PR #3952 open==<br />
;sendCustomLoginText()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendPassword|sendPassword()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
=Mudlet Object Functions=<br />
: A collection of functions that manipulate Mudlets scripting objects - triggers, aliases, and so forth.<br />
<br />
=Networking Functions=<br />
: A collection of functions for managing networking.<br />
<br />
=String Functions=<br />
: These functions are used to manipulate strings.<br />
<br />
=Table Functions=<br />
: 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.<br />
<br />
=Text to Speech Functions=<br />
: These functions are used to create sound from written words. Check out our [[Special:MyLanguage/Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.<br />
<br />
=UI Functions=<br />
: 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.<br />
<br />
==ansi2decho PR# 5670 merge, PR5719 merged==<br />
;ansi2decho(text, default_colour)<br />
: Converts ANSI colour sequences in <code>text</code> to colour tags that can be processed by the decho() function.<br />
: See also: [[Manual:Lua_Functions#decho|decho()]]<br />
<br />
{{MudletVersion|3.0}}<br />
{{note}} ANSI bold is available since Mudlet 3.7.1+.<br />
<br />
{{note}} underline, italics, overline, and strikethrough supported since Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: String that contains ANSI colour sequences that should be replaced.<br />
* ''default_colour:''<br />
: Optional - ANSI default colour code (used when handling orphan bold tags).<br />
<br />
;Return values<br />
* ''string text:''<br />
: The decho-valid converted text.<br />
* ''string colour:''<br />
: The ANSI code for the last used colour in the substitution (useful if you want to colour subsequent lines according to this colour).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local replaced = ansi2decho('\27[0;1;36;40mYou say in a baritone voice, "Test."\27[0;37;40m')<br />
-- 'replaced' should now contain <r><0,255,255:0,0,0>You say in a baritone voice, "Test."<r><192,192,192:0,0,0><br />
decho(replaced)<br />
</syntaxhighlight><br />
<br />
Or show a complete colourful squirrel! It's a lotta code to do all the colours, so click the '''Expand''' button on the right to show it:<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<syntaxhighlight lang="lua"><br />
decho(ansi2decho([[<br />
�[38;5;95m▄�[48;5;95;38;5;130m▄▄▄�[38;5;95m█�[49m▀�[0m �[0m<br />
╭───────────────────────╮ �[38;5;95m▄▄�[0m �[38;5;95m▄�[48;5;95;38;5;130m▄▄�[48;5;130m█�[38;5;137m▄�[48;5;137;38;5;95m▄�[49m▀�[0m �[0m<br />
│ │ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄▄▄�[48;5;95;38;5;137m▄▄▄�[49;38;5;95m▄▄�[48;5;95;38;5;130m▄�[48;5;130m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[0m �[0m<br />
│ Encrypt everything! │ �[38;5;95m▄�[48;5;187;38;5;16m▄�[48;5;16;38;5;187m▄�[38;5;16m█�[48;5;137;38;5;137m███�[38;5;187m▄�[38;5;16m▄▄�[38;5;137m██�[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[0m �[0m<br />
│ ├──── �[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;16m▄▄▄�[48;5;137m███�[48;5;16;38;5;16m█�[48;5;187m▄�[48;5;16m█�[48;5;137;38;5;137m█�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
╰───────────────────────╯ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;16m▄�[38;5;16m█�[38;5;137m▄�[48;5;137m██████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;95m▀�[48;5;137m▄�[38;5;137m███████�[38;5;95m▄�[49m▀�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[48;5;95;38;5;187m▄▄▄�[38;5;137m▄�[48;5;137m██�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[38;5;95m▀�[48;5;130m▄�[38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;187m████�[48;5;137;38;5;137m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m██�[38;5;95m▄�[38;5;137m█�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;187;38;5;187m████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95m██�[48;5;137m▄▄�[48;5;187;38;5;187m████�[48;5;137;38;5;95m▄▄�[48;5;95;38;5;137m▄�[48;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;187;38;5;187m███�[48;5;95m▄�[38;5;137m▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[49m▄�[48;5;95;38;5;130m▄�[48;5;130m██████�[48;5;137;38;5;137m███�[38;5;95m▄�[49m▀�[0m�[0m<br />
�[48;5;187;38;5;95m▄�[38;5;187m████�[48;5;137;38;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m█████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;137m▄�[38;5;187m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██████�[48;5;95m▄▄�[48;5;130m▄▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▄▄▄�[48;5;95;38;5;137m▄�[48;5;187m▄�[38;5;187m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m█████�[38;5;95m▄�[38;5;137m███████████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀�[48;5;187m▄▄▄�[48;5;95;38;5;137m▄�[48;5;137m██�[38;5;95m▄�[49m▀�[0m �[38;5;95m▀▀�[48;5;137m▄▄▄▄▄▄�[49m▀▀▀�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀▀�[0m �[0m<br />
]]))<br />
</syntaxhighlight><br />
</div><br />
<br />
[[File:Squirrel-in-Mudlet.png|frameless]]<br />
<br />
==cecho PR #5669 merged, PR5719 merged, PR5751 open==<br />
;cecho([window], text)<br />
: Echoes text that can be easily formatted with colour, italics, bold, strikethrough, and underline tags. You can also include unicode art in it - try some examples from [http://1lineart.kulaone.com/#/ 1lineart].<br />
: See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:UI Functions#creplaceLine|creplaceLine()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you cecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''window:''<br />
: Optional - the window name to echo to - can either be none or "main" for the main window, or a miniconsole, userwindow, or label name.<br />
* ''text:''<br />
: The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
cecho("Hi! This text is <red>red, <blue>blue, <green> and green.")<br />
<br />
cecho("<:green>Green background on normal foreground. Here we add an <ivory>ivory foreground.")<br />
<br />
cecho("<blue:yellow>Blue on yellow text!")<br />
<br />
cecho("\n<red>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, <o>overline</o>, and <b>bold</b>.")<br />
<br />
cecho("\n<green><o><u>Green text with over and underline at the same time.</o></u>")<br />
<br />
-- \n adds a new line<br />
cecho("<red>one line\n<green>another line\n<blue>last line")<br />
<br />
cecho("myinfo", "<green>All of this text is green in the myinfo miniconsole.")<br />
<br />
cecho("<green>(╯°□°)<dark_green>╯︵ ┻━┻")<br />
<br />
cecho("°º¤ø,¸¸,ø¤º°`°º¤ø,¸,ø¤°º¤ø,¸¸,ø¤º°`°º¤ø,¸")<br />
<br />
cecho([[<br />
██╗ ██╗ ██╗███╗ ██╗███████╗ █████╗ ██████╗ ████████╗<br />
███║ ██║ ██║████╗ ██║██╔════╝ ██╔══██╗██╔══██╗╚══██╔══╝<br />
╚██║ ██║ ██║██╔██╗ ██║█████╗ ███████║██████╔╝ ██║<br />
██║ ██║ ██║██║╚██╗██║██╔══╝ ██╔══██║██╔══██╗ ██║<br />
██║ ███████╗██║██║ ╚████║███████╗ ██║ ██║██║ ██║ ██║<br />
╚═╝ ╚══════╝╚═╝╚═╝ ╚═══╝╚══════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝<br />
]])<br />
</syntaxhighlight><br />
<br />
==cecho2ansi PR# 5672 merged==<br />
<br />
; ansiFormattedString = cecho2ansi(text)<br />
<br />
:Converts cecho formatted text to ansi formatted text. Used by cfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:Lua_Functions#cfeedTriggers|cfeedTriggers()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
{{note}} This function uses the ansi short colors (0-15) for color names which have base 16 ansi equivalents, such as 'red', 'blue', "lightBlue", "cyan", etc rather than the values defined in the color_table. If there is no base ansi equivalent then it will use the rgb values from the color_table for the color.<br />
<br />
;Parameters<br />
* ''text:''<br />
: The cecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of cfeedTriggers() for a single line.<br />
-- you would most likely just use cfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(cecho2ansi("\n<red>This is red.<reset> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
==decho PR #5669 merged PR5719 merged PR5751 open==<br />
;decho ([name of console,] text)<br />
: Color changes can be made using the format <FR,FG,FB:BR,BG,BB,[BA]> where each field is a number from 0 to 255. The background portion can be omitted using <FR,FG,FB> or the foreground portion can be omitted using <:BR,BG,BB,[BA]>. Arguments 2 and 3 set the default fore and background colors for the string using the same format as is used within the string, sans angle brackets, e.g. ''decho("<50,50,0:0,255,0>test")''.<br />
:You can also include <code><nowiki><i>italics</i></nowiki></code>, <code><nowiki><b>bold</b></nowiki></code>, <code><nowiki><s>strikethrough</s></nowiki></code>, <code><nowiki><o>overline</o></nowiki></code>, and <code><nowiki><u>underline</u></nowiki></code> tags.<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you decho it will erase any previous echo sent to the label.<br />
<br />
: See also: [[#cecho|cecho()]], [[#hecho|hecho()]], [[#copy2decho|copy2decho()]]<br />
<br />
;Parameters<br />
* ''name of console''<br />
: (Optional) Name of the console to echo to. If no name is given, this will defaults to the main window.<br />
* ''text:''<br />
: The text that you’d like to echo with embedded color tags. Tags take the RGB values only, see below for an explanation.<br />
<br />
<br />
{{note}}<br />
Optional background transparancy parameter (BA) available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
decho("<50,50,0:0,255,0>test")<br />
<br />
decho("miniconsolename", "<50,50,0:0,255,0>test")<br />
<br />
decho("\n<255,0,0>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, and <b>bold</b> formatting.")<br />
<br />
decho("<\n<0,128,0><o><u>Green text with both over and underlines.</u></o>")<br />
</syntaxhighlight><br />
<br />
==decho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = decho2ansi(text)<br />
<br />
:Converts decho formatted text to ansi formatted text. Used by dfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#dfeedTriggers|dfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The decho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of dfeedTriggers() for a single line.<br />
-- you would most likely just use dfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(decho2ansi("\n<128,0,0>This is red.<r> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
==getHTMLformat PR#5751 open==<br />
<br />
; spanTag = getHTMLformat(formatTable)<br />
<br />
:Takes in a table of formatting options in the same style as [[Manual:Lua_Functions#getTextFormat|getTextFormat()]] and returns a span tag which will format text after it as the table describes.<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formatTable:''<br />
: Table with formatting options configured. Keys are foreground, background, bold, underline, overline, strikeout, italic, and reverse. All except for foreground and background should be boolean (true/false) values. Foreground and background are either { r, g, b, a } tables, or strings with QSS formatting directives<br />
<br />
;Returns <br />
* A string with the html span tag to format text in accordance with the format table.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Returns a span tag for bold, red text on a green background<br />
local span = getHTMLformat({<br />
foreground = { 255, 0, 0 },<br />
background = "#00FF00",<br />
bold = true<br />
})<br />
<br />
-- span will be '<span style="color: rgb(255, 0, 0);background-color: #00FF00; font-weight: bold; font-style: normal; text-decoration: none;">'<br />
</syntaxhighlight><br />
<br />
==getLabelFormat PR#5751 open==<br />
<br />
; formatTable = getLabelFormat(labelName)<br />
<br />
:Returns a format table like the one returned by getTextFormat and suitable for getHTMLspan which will format text the same way as simply doing an echo to the label would<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getHTMLspan|getHTMLspan()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: The name of the label to scan the format of<br />
<br />
;Returns <br />
* A table with all the formatting options to achieve a default text format for label labelName. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- creates a test label, sets a stylesheet, and then returns the default format table for that label.<br />
createLabel("testLabel", 10, 10, 300, 200, 1)<br />
setLabelStyleSheet([[<br />
color: rgb(0,0,180);<br />
border-width: 1px;<br />
border-style: solid;<br />
border-color: gold;<br />
border-radius: 10px;<br />
font-size: 12.0pt;<br />
background: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #98f041, stop: 0.1 #8cf029, stop: 0.49 #66cc00, stop: 0.5 #52a300, stop: 1 #66cc00);<br />
]])<br />
local fmt = getLabelFormat("testLabel"))<br />
<br />
--[[<br />
{<br />
background = "rgba(0, 0, 0, 0)", -- this is transparent<br />
bold = false,<br />
foreground = "rgb(0,0,180)",<br />
italic = false,<br />
overline = false,<br />
reverse = false,<br />
strikeout = false,<br />
underline = false<br />
}<br />
--]]<br />
<br />
</syntaxhighlight><br />
<br />
==hecho PR #5669 merged, PR5719 merged, PR5751 open==<br />
;hecho([windowName], text)<br />
: Echoes text that can be easily formatted with colour tags in the hexadecimal format. You can also use italics, bold, strikethrough, and underline tags.<br />
: See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#cecho|cecho()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you hecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Can either be omitted or "main" for the main window, else specify the miniconsoles name.<br />
* ''text:''<br />
: The text to display, with color changes made within the string using the format |cFRFGFB,BRBGBB or #FRFGFB,BRBGBB where FR is the foreground red value, FG is the foreground green value, FB is the foreground blue value, BR is the background red value, etc., BRBGBB is optional. |r or #r can be used within the string to reset the colors to default. Hexadecimal color codes can be found here: https://www.color-hex.com/<br />
<br />
{{note}}<br />
Transparency for background in hex-format available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
hecho("\n#ffffff White text!")<br />
-- your text in white<br />
hecho("\n#ca0004 Red text! And now reset #rit to the default color")<br />
-- your text in red, then reset to default using #r<br />
hecho("\n#ffffff,ca0004 White text with a red background!")<br />
-- your text in white, against a red background<br />
hecho("\n|c0000ff Blue text, this time using |c instead of #")<br />
-- your text in blue, activated with |c vs #.<br />
hecho("\n#ff0000Red text with #iitalics#/i, |uunderline|/u, #ooverline#/o, #sstrikethrough#/s, and #bbold#/b formatting.")<br />
-- shows the various individual formatting options<br />
hecho("\n#008000#o#uGreen text with both over and underlines.#/o#/u")<br />
</syntaxhighlight><br />
<br />
==hecho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = hecho2ansi(text)<br />
<br />
:Converts hecho formatted text to ansi formatted text. Used by hfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:Lua_Functions#hfeedTriggers|hfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The hecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of hfeedTriggers() for a single line.<br />
-- you would most likely just use hfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(hecho2ansi("\n#800000This is red.#r #iitalic#/i, #bbold#/b, #sstrikethrough#/s, #uunderline#/u\n"))<br />
</syntaxhighlight><br />
<br />
==windowType PR# 5696 open==<br />
; typeOfWindow = windowType(windowName)<br />
<br />
:Given the name of a window, will return if it's a label, miniconsole, userwindow or a commandline.<br />
<br />
;See also: [[Manual:Lua_Functions#createLabel|createLabel()]], [[Manual:Lua_Functions#openUserWindow|openUserWindow()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name used to create the window element. Use "main" for the main console<br />
<br />
<br />
;Returns <br />
* Window type as string ("label", "miniconsole", "userwindow", or "commandline") or nil+error if it does not exist.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a Geyser label and and check its type<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
display(windowType(testLabel.name)) -- displays "label"<br />
<br />
-- the main console returns "miniconsole" because it uses the same formatting functions<br />
display(windowType("main")) -- displays "miniconsole"<br />
<br />
-- check for the existence of a window<br />
local windowName = "this thing does not exist"<br />
local ok, err = windowType(windowName)<br />
if ok then<br />
-- do things with it, as it does exist.<br />
-- the ok variable will hold the type of window it is ("label", "commandline", etc)<br />
else<br />
cecho("<red>ALERT!! window does not exist")<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
=Discord Functions=<br />
: 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 [[Special:MyLanguage/Manual:Scripting#Discord_Rich_Presence|Discord scripting overview]].</div>Demonnichttps://wiki.mudlet.org/index.php?title=Area_51&diff=18521Area 512021-12-19T03:39:55Z<p>Demonnic: /* hecho PR #5669 merged, PR5719 merged, PR5751 open */</p>
<hr />
<div>{{TOC right}}<br />
<br />
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 [[Manual:Lua_Functions|Lua Functions]] and its sub-sites. <br />
<br />
Please use the [[Area_51/Template]] to add new entries in the sections below.<br />
<br />
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.<br />
<br />
<br />
=Basic Essential Functions=<br />
:These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.<br />
<br />
=Database Functions=<br />
:A collection of functions for helping deal with the database.<br />
<br />
=Date/Time Functions=<br />
: A collection of functions for handling date & time.<br />
<br />
=File System Functions=<br />
: A collection of functions for interacting with the file system.<br />
<br />
=Mapper Functions=<br />
: A collection of functions that manipulate the mapper and its related features.<br />
<br />
==mapSymbolFontInfo, PR #4038 closed==<br />
;mapSymbolFontInfo()<br />
: See also: [[#setupMapSymbolFont|setupMapSymbolFont()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;returns<br />
* either a table of information about the configuration of the font used for symbols in the (2D) map, the elements are:<br />
:* ''fontName'' - a string of the family name of the font specified<br />
:* ''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.<br />
:* ''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).<br />
* or ''nil'' and an error message on failure.<br />
<br />
::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).<br />
<br />
<br />
==setupMapSymbolFont, PR #4038 closed==<br />
;setupMapSymbolFont(fontName[, onlyUseThisFont[, scalingFactor]])<br />
:configures the font used for symbols in the (2D) map.<br />
: See also: [[#mapSymbolFontInfo|mapSymbolFontInfo()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;Parameters<br />
* ''fontName'' one of:<br />
:* - a string that is the family name of the font to use;<br />
:* - the empty string ''""'' to reset to the default {which is '''"Bitstream Vera Sans Mono"'''};<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow a following one to be modified.<br />
* ''onlyUseThisFont'' (optional) one of:<br />
:* - 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;<br />
:* - 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;<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow the following one to be modified.<br />
* ''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.<br />
<br />
;Returns<br />
* ''true'' on success<br />
* ''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).<br />
<br />
=Miscellaneous Functions=<br />
: Miscellaneous functions.<br />
<br />
==getCharacterName, PR #3952 open==<br />
;getCharacterName()<br />
<br />
: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.<br />
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.<br />
<br />
:See also: [[#sendCharacterName|sendCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lua send("cast 'glamor' " .. getCharacterName())<br />
<br />
You get a warm feeling passing from your core to the tips of your hands, feet and other body parts.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A tawny long-haired cat saunters over and start to rub itself against your ankles.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A mangy dog trots up to you and proceeds to mark the bottom of your leggings.<br />
</syntaxhighlight><br />
<br />
==getCustomLoginTextId, PR #3952 open==<br />
;getCustomLoginTextId()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#sendPassword|sendPassword()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCharacterName, PR #3952 open==<br />
;sendCharacterName()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
==sendCharacterPassword, PR #3952 open==<br />
;sendCharacterPassword()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]], [[#sendCharacterName|sendCharacterName()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCharacterName() ~= "" then<br />
tempTime(2.0, [[sendCharacterName()]], 1)<br />
tempTime(3.0, [[sendCharacterPassword()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCustomLoginText, PR #3952 open==<br />
;sendCustomLoginText()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendPassword|sendPassword()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
=Mudlet Object Functions=<br />
: A collection of functions that manipulate Mudlets scripting objects - triggers, aliases, and so forth.<br />
<br />
=Networking Functions=<br />
: A collection of functions for managing networking.<br />
<br />
=String Functions=<br />
: These functions are used to manipulate strings.<br />
<br />
=Table Functions=<br />
: 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.<br />
<br />
=Text to Speech Functions=<br />
: These functions are used to create sound from written words. Check out our [[Special:MyLanguage/Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.<br />
<br />
=UI Functions=<br />
: 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.<br />
<br />
==ansi2decho PR# 5670 merge, PR5719 merged==<br />
;ansi2decho(text, default_colour)<br />
: Converts ANSI colour sequences in <code>text</code> to colour tags that can be processed by the decho() function.<br />
: See also: [[Manual:Lua_Functions#decho|decho()]]<br />
<br />
{{MudletVersion|3.0}}<br />
{{note}} ANSI bold is available since Mudlet 3.7.1+.<br />
<br />
{{note}} underline, italics, overline, and strikethrough supported since Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: String that contains ANSI colour sequences that should be replaced.<br />
* ''default_colour:''<br />
: Optional - ANSI default colour code (used when handling orphan bold tags).<br />
<br />
;Return values<br />
* ''string text:''<br />
: The decho-valid converted text.<br />
* ''string colour:''<br />
: The ANSI code for the last used colour in the substitution (useful if you want to colour subsequent lines according to this colour).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local replaced = ansi2decho('\27[0;1;36;40mYou say in a baritone voice, "Test."\27[0;37;40m')<br />
-- 'replaced' should now contain <r><0,255,255:0,0,0>You say in a baritone voice, "Test."<r><192,192,192:0,0,0><br />
decho(replaced)<br />
</syntaxhighlight><br />
<br />
Or show a complete colourful squirrel! It's a lotta code to do all the colours, so click the '''Expand''' button on the right to show it:<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<syntaxhighlight lang="lua"><br />
decho(ansi2decho([[<br />
�[38;5;95m▄�[48;5;95;38;5;130m▄▄▄�[38;5;95m█�[49m▀�[0m �[0m<br />
╭───────────────────────╮ �[38;5;95m▄▄�[0m �[38;5;95m▄�[48;5;95;38;5;130m▄▄�[48;5;130m█�[38;5;137m▄�[48;5;137;38;5;95m▄�[49m▀�[0m �[0m<br />
│ │ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄▄▄�[48;5;95;38;5;137m▄▄▄�[49;38;5;95m▄▄�[48;5;95;38;5;130m▄�[48;5;130m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[0m �[0m<br />
│ Encrypt everything! │ �[38;5;95m▄�[48;5;187;38;5;16m▄�[48;5;16;38;5;187m▄�[38;5;16m█�[48;5;137;38;5;137m███�[38;5;187m▄�[38;5;16m▄▄�[38;5;137m██�[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[0m �[0m<br />
│ ├──── �[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;16m▄▄▄�[48;5;137m███�[48;5;16;38;5;16m█�[48;5;187m▄�[48;5;16m█�[48;5;137;38;5;137m█�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
╰───────────────────────╯ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;16m▄�[38;5;16m█�[38;5;137m▄�[48;5;137m██████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;95m▀�[48;5;137m▄�[38;5;137m███████�[38;5;95m▄�[49m▀�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[48;5;95;38;5;187m▄▄▄�[38;5;137m▄�[48;5;137m██�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[38;5;95m▀�[48;5;130m▄�[38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;187m████�[48;5;137;38;5;137m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m██�[38;5;95m▄�[38;5;137m█�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;187;38;5;187m████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95m██�[48;5;137m▄▄�[48;5;187;38;5;187m████�[48;5;137;38;5;95m▄▄�[48;5;95;38;5;137m▄�[48;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;187;38;5;187m███�[48;5;95m▄�[38;5;137m▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[49m▄�[48;5;95;38;5;130m▄�[48;5;130m██████�[48;5;137;38;5;137m███�[38;5;95m▄�[49m▀�[0m�[0m<br />
�[48;5;187;38;5;95m▄�[38;5;187m████�[48;5;137;38;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m█████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;137m▄�[38;5;187m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██████�[48;5;95m▄▄�[48;5;130m▄▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▄▄▄�[48;5;95;38;5;137m▄�[48;5;187m▄�[38;5;187m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m█████�[38;5;95m▄�[38;5;137m███████████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀�[48;5;187m▄▄▄�[48;5;95;38;5;137m▄�[48;5;137m██�[38;5;95m▄�[49m▀�[0m �[38;5;95m▀▀�[48;5;137m▄▄▄▄▄▄�[49m▀▀▀�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀▀�[0m �[0m<br />
]]))<br />
</syntaxhighlight><br />
</div><br />
<br />
[[File:Squirrel-in-Mudlet.png|frameless]]<br />
<br />
==cecho PR #5669 merged, PR5719 merged, PR5751 open==<br />
;cecho([window], text)<br />
: Echoes text that can be easily formatted with colour, italics, bold, strikethrough, and underline tags. You can also include unicode art in it - try some examples from [http://1lineart.kulaone.com/#/ 1lineart].<br />
: See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:UI Functions#creplaceLine|creplaceLine()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you cecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''window:''<br />
: Optional - the window name to echo to - can either be none or "main" for the main window, or a miniconsole, userwindow, or label name.<br />
* ''text:''<br />
: The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
cecho("Hi! This text is <red>red, <blue>blue, <green> and green.")<br />
<br />
cecho("<:green>Green background on normal foreground. Here we add an <ivory>ivory foreground.")<br />
<br />
cecho("<blue:yellow>Blue on yellow text!")<br />
<br />
cecho("\n<red>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, <o>overline</o>, and <b>bold</b>.")<br />
<br />
cecho("\n<green><o><u>Green text with over and underline at the same time.</o></u>")<br />
<br />
-- \n adds a new line<br />
cecho("<red>one line\n<green>another line\n<blue>last line")<br />
<br />
cecho("myinfo", "<green>All of this text is green in the myinfo miniconsole.")<br />
<br />
cecho("<green>(╯°□°)<dark_green>╯︵ ┻━┻")<br />
<br />
cecho("°º¤ø,¸¸,ø¤º°`°º¤ø,¸,ø¤°º¤ø,¸¸,ø¤º°`°º¤ø,¸")<br />
<br />
cecho([[<br />
██╗ ██╗ ██╗███╗ ██╗███████╗ █████╗ ██████╗ ████████╗<br />
███║ ██║ ██║████╗ ██║██╔════╝ ██╔══██╗██╔══██╗╚══██╔══╝<br />
╚██║ ██║ ██║██╔██╗ ██║█████╗ ███████║██████╔╝ ██║<br />
██║ ██║ ██║██║╚██╗██║██╔══╝ ██╔══██║██╔══██╗ ██║<br />
██║ ███████╗██║██║ ╚████║███████╗ ██║ ██║██║ ██║ ██║<br />
╚═╝ ╚══════╝╚═╝╚═╝ ╚═══╝╚══════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝<br />
]])<br />
</syntaxhighlight><br />
<br />
==cecho2ansi PR# 5672 merged==<br />
<br />
; ansiFormattedString = cecho2ansi(text)<br />
<br />
:Converts cecho formatted text to ansi formatted text. Used by cfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:Lua_Functions#cfeedTriggers|cfeedTriggers()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
{{note}} This function uses the ansi short colors (0-15) for color names which have base 16 ansi equivalents, such as 'red', 'blue', "lightBlue", "cyan", etc rather than the values defined in the color_table. If there is no base ansi equivalent then it will use the rgb values from the color_table for the color.<br />
<br />
;Parameters<br />
* ''text:''<br />
: The cecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of cfeedTriggers() for a single line.<br />
-- you would most likely just use cfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(cecho2ansi("\n<red>This is red.<reset> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
==decho PR #5669 merged PR5719 merged PR5751 open==<br />
;decho ([name of console,] text)<br />
: Color changes can be made using the format <FR,FG,FB:BR,BG,BB,[BA]> where each field is a number from 0 to 255. The background portion can be omitted using <FR,FG,FB> or the foreground portion can be omitted using <:BR,BG,BB,[BA]>. Arguments 2 and 3 set the default fore and background colors for the string using the same format as is used within the string, sans angle brackets, e.g. ''decho("<50,50,0:0,255,0>test")''.<br />
:You can also include <code><nowiki><i>italics</i></nowiki></code>, <code><nowiki><b>bold</b></nowiki></code>, <code><nowiki><s>strikethrough</s></nowiki></code>, <code><nowiki><o>overline</o></nowiki></code>, and <code><nowiki><u>underline</u></nowiki></code> tags.<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you decho it will erase any previous echo sent to the label.<br />
<br />
: See also: [[#cecho|cecho()]], [[#hecho|hecho()]], [[#copy2decho|copy2decho()]]<br />
<br />
;Parameters<br />
* ''name of console''<br />
: (Optional) Name of the console to echo to. If no name is given, this will defaults to the main window.<br />
* ''text:''<br />
: The text that you’d like to echo with embedded color tags. Tags take the RGB values only, see below for an explanation.<br />
<br />
<br />
{{note}}<br />
Optional background transparancy parameter (BA) available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
decho("<50,50,0:0,255,0>test")<br />
<br />
decho("miniconsolename", "<50,50,0:0,255,0>test")<br />
<br />
decho("\n<255,0,0>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, and <b>bold</b> formatting.")<br />
<br />
decho("<\n<0,128,0><o><u>Green text with both over and underlines.</u></o>")<br />
</syntaxhighlight><br />
<br />
==decho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = decho2ansi(text)<br />
<br />
:Converts decho formatted text to ansi formatted text. Used by dfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#dfeedTriggers|dfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The decho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of dfeedTriggers() for a single line.<br />
-- you would most likely just use dfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(decho2ansi("\n<128,0,0>This is red.<r> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
==getHTMLspan PR#5751 open==<br />
<br />
; spanTag = getHTMLspan(formatTable)<br />
<br />
:Takes in a table of formatting options in the same style as [[Manual:Lua_Functions#getTextFormat|getTextFormat()]] and returns a span tag which will format text after it as the table describes.<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formatTable:''<br />
: Table with formatting options configured. Keys are foreground, background, bold, underline, overline, strikeout, italic, and reverse. All except for foreground and background should be boolean (true/false) values. Foreground and background are either { r, g, b, a } tables, or strings with QSS formatting directives<br />
<br />
;Returns <br />
* A string with the html span tag to format text in accordance with the format table.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Returns a span tag for bold, red text on a green background<br />
local span = getHTMLspan({<br />
foreground = { 255, 0, 0 },<br />
background = "#00FF00",<br />
bold = true<br />
})<br />
<br />
-- span will be '<span style="color: rgb(255, 0, 0);background-color: #00FF00; font-weight: bold; font-style: normal; text-decoration: none;">'<br />
</syntaxhighlight><br />
<br />
==getLabelFormat PR#5751 open==<br />
<br />
; formatTable = getLabelFormat(labelName)<br />
<br />
:Returns a format table like the one returned by getTextFormat and suitable for getHTMLspan which will format text the same way as simply doing an echo to the label would<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getHTMLspan|getHTMLspan()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: The name of the label to scan the format of<br />
<br />
;Returns <br />
* A table with all the formatting options to achieve a default text format for label labelName. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- creates a test label, sets a stylesheet, and then returns the default format table for that label.<br />
createLabel("testLabel", 10, 10, 300, 200, 1)<br />
setLabelStyleSheet([[<br />
color: rgb(0,0,180);<br />
border-width: 1px;<br />
border-style: solid;<br />
border-color: gold;<br />
border-radius: 10px;<br />
font-size: 12.0pt;<br />
background: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #98f041, stop: 0.1 #8cf029, stop: 0.49 #66cc00, stop: 0.5 #52a300, stop: 1 #66cc00);<br />
]])<br />
local fmt = getLabelFormat("testLabel"))<br />
<br />
--[[<br />
{<br />
background = "rgba(0, 0, 0, 0)", -- this is transparent<br />
bold = false,<br />
foreground = "rgb(0,0,180)",<br />
italic = false,<br />
overline = false,<br />
reverse = false,<br />
strikeout = false,<br />
underline = false<br />
}<br />
--]]<br />
<br />
</syntaxhighlight><br />
<br />
==hecho PR #5669 merged, PR5719 merged, PR5751 open==<br />
;hecho([windowName], text)<br />
: Echoes text that can be easily formatted with colour tags in the hexadecimal format. You can also use italics, bold, strikethrough, and underline tags.<br />
: See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#cecho|cecho()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you hecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Can either be omitted or "main" for the main window, else specify the miniconsoles name.<br />
* ''text:''<br />
: The text to display, with color changes made within the string using the format |cFRFGFB,BRBGBB or #FRFGFB,BRBGBB where FR is the foreground red value, FG is the foreground green value, FB is the foreground blue value, BR is the background red value, etc., BRBGBB is optional. |r or #r can be used within the string to reset the colors to default. Hexadecimal color codes can be found here: https://www.color-hex.com/<br />
<br />
{{note}}<br />
Transparency for background in hex-format available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
hecho("\n#ffffff White text!")<br />
-- your text in white<br />
hecho("\n#ca0004 Red text! And now reset #rit to the default color")<br />
-- your text in red, then reset to default using #r<br />
hecho("\n#ffffff,ca0004 White text with a red background!")<br />
-- your text in white, against a red background<br />
hecho("\n|c0000ff Blue text, this time using |c instead of #")<br />
-- your text in blue, activated with |c vs #.<br />
hecho("\n#ff0000Red text with #iitalics#/i, |uunderline|/u, #ooverline#/o, #sstrikethrough#/s, and #bbold#/b formatting.")<br />
-- shows the various individual formatting options<br />
hecho("\n#008000#o#uGreen text with both over and underlines.#/o#/u")<br />
</syntaxhighlight><br />
<br />
==hecho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = hecho2ansi(text)<br />
<br />
:Converts hecho formatted text to ansi formatted text. Used by hfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:Lua_Functions#hfeedTriggers|hfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The hecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of hfeedTriggers() for a single line.<br />
-- you would most likely just use hfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(hecho2ansi("\n#800000This is red.#r #iitalic#/i, #bbold#/b, #sstrikethrough#/s, #uunderline#/u\n"))<br />
</syntaxhighlight><br />
<br />
==windowType PR# 5696 open==<br />
; typeOfWindow = windowType(windowName)<br />
<br />
:Given the name of a window, will return if it's a label, miniconsole, userwindow or a commandline.<br />
<br />
;See also: [[Manual:Lua_Functions#createLabel|createLabel()]], [[Manual:Lua_Functions#openUserWindow|openUserWindow()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name used to create the window element. Use "main" for the main console<br />
<br />
<br />
;Returns <br />
* Window type as string ("label", "miniconsole", "userwindow", or "commandline") or nil+error if it does not exist.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a Geyser label and and check its type<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
display(windowType(testLabel.name)) -- displays "label"<br />
<br />
-- the main console returns "miniconsole" because it uses the same formatting functions<br />
display(windowType("main")) -- displays "miniconsole"<br />
<br />
-- check for the existence of a window<br />
local windowName = "this thing does not exist"<br />
local ok, err = windowType(windowName)<br />
if ok then<br />
-- do things with it, as it does exist.<br />
-- the ok variable will hold the type of window it is ("label", "commandline", etc)<br />
else<br />
cecho("<red>ALERT!! window does not exist")<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
=Discord Functions=<br />
: 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 [[Special:MyLanguage/Manual:Scripting#Discord_Rich_Presence|Discord scripting overview]].</div>Demonnichttps://wiki.mudlet.org/index.php?title=Area_51&diff=18520Area 512021-12-19T03:39:38Z<p>Demonnic: /* decho PR #5669 merged PR5719 merged PR5751 open */</p>
<hr />
<div>{{TOC right}}<br />
<br />
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 [[Manual:Lua_Functions|Lua Functions]] and its sub-sites. <br />
<br />
Please use the [[Area_51/Template]] to add new entries in the sections below.<br />
<br />
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.<br />
<br />
<br />
=Basic Essential Functions=<br />
:These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.<br />
<br />
=Database Functions=<br />
:A collection of functions for helping deal with the database.<br />
<br />
=Date/Time Functions=<br />
: A collection of functions for handling date & time.<br />
<br />
=File System Functions=<br />
: A collection of functions for interacting with the file system.<br />
<br />
=Mapper Functions=<br />
: A collection of functions that manipulate the mapper and its related features.<br />
<br />
==mapSymbolFontInfo, PR #4038 closed==<br />
;mapSymbolFontInfo()<br />
: See also: [[#setupMapSymbolFont|setupMapSymbolFont()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;returns<br />
* either a table of information about the configuration of the font used for symbols in the (2D) map, the elements are:<br />
:* ''fontName'' - a string of the family name of the font specified<br />
:* ''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.<br />
:* ''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).<br />
* or ''nil'' and an error message on failure.<br />
<br />
::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).<br />
<br />
<br />
==setupMapSymbolFont, PR #4038 closed==<br />
;setupMapSymbolFont(fontName[, onlyUseThisFont[, scalingFactor]])<br />
:configures the font used for symbols in the (2D) map.<br />
: See also: [[#mapSymbolFontInfo|mapSymbolFontInfo()]]<br />
<br />
{{note}} pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/4038<br />
<br />
;Parameters<br />
* ''fontName'' one of:<br />
:* - a string that is the family name of the font to use;<br />
:* - the empty string ''""'' to reset to the default {which is '''"Bitstream Vera Sans Mono"'''};<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow a following one to be modified.<br />
* ''onlyUseThisFont'' (optional) one of:<br />
:* - 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;<br />
:* - 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;<br />
:* - a Lua ''nil'' as a placeholder to not change this parameter but still allow the following one to be modified.<br />
* ''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.<br />
<br />
;Returns<br />
* ''true'' on success<br />
* ''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).<br />
<br />
=Miscellaneous Functions=<br />
: Miscellaneous functions.<br />
<br />
==getCharacterName, PR #3952 open==<br />
;getCharacterName()<br />
<br />
: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.<br />
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.<br />
<br />
:See also: [[#sendCharacterName|sendCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
lua send("cast 'glamor' " .. getCharacterName())<br />
<br />
You get a warm feeling passing from your core to the tips of your hands, feet and other body parts.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A tawny long-haired cat saunters over and start to rub itself against your ankles.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A light brown faun gambles around you and then nuzzles your hand.<br />
A small twittering bird settles on your shoulder and starts to look adoringly at you.<br />
A mangy dog trots up to you and proceeds to mark the bottom of your leggings.<br />
</syntaxhighlight><br />
<br />
==getCustomLoginTextId, PR #3952 open==<br />
;getCustomLoginTextId()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#sendPassword|sendPassword()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCharacterName, PR #3952 open==<br />
;sendCharacterName()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterPassword|sendCharacterPassword()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
==sendCharacterPassword, PR #3952 open==<br />
;sendCharacterPassword()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCustomLoginText|sendCustomLoginText()]], [[#getCustomLoginTextId|getCustomLoginTextId()]], [[#sendCharacterName|sendCharacterName()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCharacterName() ~= "" then<br />
tempTime(2.0, [[sendCharacterName()]], 1)<br />
tempTime(3.0, [[sendCharacterPassword()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
==sendCustomLoginText, PR #3952 open==<br />
;sendCustomLoginText()<br />
<br />
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.<br />
<br />
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.<br />
:See also: [[#getCharacterName|getCharacterName()]], [[#sendCharacterName|sendCharacterName()]], [[#sendPassword|sendPassword()]], [[#getCustomLoginTextId|getCustomLoginTextId()]].<br />
<br />
{{note}} Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952<br />
<br />
Only one custom login text has been defined initially:<br />
{| class="wikitable"<br />
|+ Predefined custom login texts<br />
|-<br />
! Id !! Custom text !! Introduced in Mudlet version<br />
|-<br />
| 1 || "connect {character name} {password}" || TBD<br />
|}<br />
<br />
The addition of further texts would be subject to negotiation with the Mudlet Makers.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:<br />
function doLogin()<br />
if getCustomLoginTextId() ~= 1 then<br />
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is<br />
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")<br />
else<br />
tempTime(2.0, [[sendCustomLoginText()]], 1)<br />
end<br />
end<br />
</syntaxhighlight><br />
<br />
=Mudlet Object Functions=<br />
: A collection of functions that manipulate Mudlets scripting objects - triggers, aliases, and so forth.<br />
<br />
=Networking Functions=<br />
: A collection of functions for managing networking.<br />
<br />
=String Functions=<br />
: These functions are used to manipulate strings.<br />
<br />
=Table Functions=<br />
: 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.<br />
<br />
=Text to Speech Functions=<br />
: These functions are used to create sound from written words. Check out our [[Special:MyLanguage/Manual:Text-to-Speech|Text-To-Speech Manual]] for more detail on how this all works together.<br />
<br />
=UI Functions=<br />
: 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.<br />
<br />
==ansi2decho PR# 5670 merge, PR5719 merged==<br />
;ansi2decho(text, default_colour)<br />
: Converts ANSI colour sequences in <code>text</code> to colour tags that can be processed by the decho() function.<br />
: See also: [[Manual:Lua_Functions#decho|decho()]]<br />
<br />
{{MudletVersion|3.0}}<br />
{{note}} ANSI bold is available since Mudlet 3.7.1+.<br />
<br />
{{note}} underline, italics, overline, and strikethrough supported since Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: String that contains ANSI colour sequences that should be replaced.<br />
* ''default_colour:''<br />
: Optional - ANSI default colour code (used when handling orphan bold tags).<br />
<br />
;Return values<br />
* ''string text:''<br />
: The decho-valid converted text.<br />
* ''string colour:''<br />
: The ANSI code for the last used colour in the substitution (useful if you want to colour subsequent lines according to this colour).<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
local replaced = ansi2decho('\27[0;1;36;40mYou say in a baritone voice, "Test."\27[0;37;40m')<br />
-- 'replaced' should now contain <r><0,255,255:0,0,0>You say in a baritone voice, "Test."<r><192,192,192:0,0,0><br />
decho(replaced)<br />
</syntaxhighlight><br />
<br />
Or show a complete colourful squirrel! It's a lotta code to do all the colours, so click the '''Expand''' button on the right to show it:<br />
<div class="toccolours mw-collapsible mw-collapsed"><br />
<syntaxhighlight lang="lua"><br />
decho(ansi2decho([[<br />
�[38;5;95m▄�[48;5;95;38;5;130m▄▄▄�[38;5;95m█�[49m▀�[0m �[0m<br />
╭───────────────────────╮ �[38;5;95m▄▄�[0m �[38;5;95m▄�[48;5;95;38;5;130m▄▄�[48;5;130m█�[38;5;137m▄�[48;5;137;38;5;95m▄�[49m▀�[0m �[0m<br />
│ │ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄▄▄�[48;5;95;38;5;137m▄▄▄�[49;38;5;95m▄▄�[48;5;95;38;5;130m▄�[48;5;130m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[0m �[0m<br />
│ Encrypt everything! │ �[38;5;95m▄�[48;5;187;38;5;16m▄�[48;5;16;38;5;187m▄�[38;5;16m█�[48;5;137;38;5;137m███�[38;5;187m▄�[38;5;16m▄▄�[38;5;137m██�[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[0m �[0m<br />
│ ├──── �[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;16m▄▄▄�[48;5;137m███�[48;5;16;38;5;16m█�[48;5;187m▄�[48;5;16m█�[48;5;137;38;5;137m█�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
╰───────────────────────╯ �[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;16m▄�[38;5;16m█�[38;5;137m▄�[48;5;137m██████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;95m▀�[48;5;137m▄�[38;5;137m███████�[38;5;95m▄�[49m▀�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[48;5;95;38;5;187m▄▄▄�[38;5;137m▄�[48;5;137m██�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m█████████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;187m▄�[48;5;187m███�[38;5;137m▄�[48;5;137m█�[48;5;95;38;5;95m█�[48;5;137;38;5;137m███�[48;5;95m▄�[49;38;5;95m▄�[0m �[38;5;95m▀�[48;5;130m▄�[38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;187m████�[48;5;137;38;5;137m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m██�[38;5;95m▄�[38;5;137m█�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;187;38;5;187m████�[48;5;137;38;5;137m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██�[48;5;95m▄�[49;38;5;95m▄�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[38;5;95m▄�[48;5;95m██�[48;5;137m▄▄�[48;5;187;38;5;187m████�[48;5;137;38;5;95m▄▄�[48;5;95;38;5;137m▄�[48;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[48;5;95;38;5;95m█�[48;5;130;38;5;130m██████�[48;5;137;38;5;137m████�[48;5;95;38;5;95m█�[0m�[0m<br />
�[48;5;187;38;5;187m███�[48;5;95m▄�[38;5;137m▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[49m▄�[48;5;95;38;5;130m▄�[48;5;130m██████�[48;5;137;38;5;137m███�[38;5;95m▄�[49m▀�[0m�[0m<br />
�[48;5;187;38;5;95m▄�[38;5;187m████�[48;5;137;38;5;137m█�[38;5;95m▄�[48;5;95;38;5;137m▄�[48;5;137m█████�[48;5;95;38;5;95m█�[48;5;130;38;5;130m███████�[38;5;137m▄�[48;5;137m████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[48;5;95;38;5;95m█�[48;5;187;38;5;137m▄�[38;5;187m███�[48;5;95;38;5;95m█�[48;5;137;38;5;137m██████�[48;5;95m▄▄�[48;5;130m▄▄▄▄▄�[48;5;137m██████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▄▄▄�[48;5;95;38;5;137m▄�[48;5;187m▄�[38;5;187m██�[48;5;95m▄�[48;5;137;38;5;95m▄�[38;5;137m█████�[38;5;95m▄�[38;5;137m███████████�[48;5;95;38;5;95m█�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀�[48;5;187m▄▄▄�[48;5;95;38;5;137m▄�[48;5;137m██�[38;5;95m▄�[49m▀�[0m �[38;5;95m▀▀�[48;5;137m▄▄▄▄▄▄�[49m▀▀▀�[0m �[0m<br />
�[38;5;95m▀▀▀▀▀▀▀▀▀�[0m �[0m<br />
]]))<br />
</syntaxhighlight><br />
</div><br />
<br />
[[File:Squirrel-in-Mudlet.png|frameless]]<br />
<br />
==cecho PR #5669 merged, PR5719 merged, PR5751 open==<br />
;cecho([window], text)<br />
: Echoes text that can be easily formatted with colour, italics, bold, strikethrough, and underline tags. You can also include unicode art in it - try some examples from [http://1lineart.kulaone.com/#/ 1lineart].<br />
: See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:UI Functions#creplaceLine|creplaceLine()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you cecho it will erase any previous echo sent to the label.<br />
<br />
;Parameters<br />
* ''window:''<br />
: Optional - the window name to echo to - can either be none or "main" for the main window, or a miniconsole, userwindow, or label name.<br />
* ''text:''<br />
: The text to display, with color names inside angle brackets <>, ie ''<red>''. If you'd like to use a background color, put it after a colon : - ''<:red>''. You can use the ''<reset''> tag to reset to the default color. You can select any from this list: [[File:ShowColors.png|50px|frameless|Color Table]]<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
cecho("Hi! This text is <red>red, <blue>blue, <green> and green.")<br />
<br />
cecho("<:green>Green background on normal foreground. Here we add an <ivory>ivory foreground.")<br />
<br />
cecho("<blue:yellow>Blue on yellow text!")<br />
<br />
cecho("\n<red>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, <o>overline</o>, and <b>bold</b>.")<br />
<br />
cecho("\n<green><o><u>Green text with over and underline at the same time.</o></u>")<br />
<br />
-- \n adds a new line<br />
cecho("<red>one line\n<green>another line\n<blue>last line")<br />
<br />
cecho("myinfo", "<green>All of this text is green in the myinfo miniconsole.")<br />
<br />
cecho("<green>(╯°□°)<dark_green>╯︵ ┻━┻")<br />
<br />
cecho("°º¤ø,¸¸,ø¤º°`°º¤ø,¸,ø¤°º¤ø,¸¸,ø¤º°`°º¤ø,¸")<br />
<br />
cecho([[<br />
██╗ ██╗ ██╗███╗ ██╗███████╗ █████╗ ██████╗ ████████╗<br />
███║ ██║ ██║████╗ ██║██╔════╝ ██╔══██╗██╔══██╗╚══██╔══╝<br />
╚██║ ██║ ██║██╔██╗ ██║█████╗ ███████║██████╔╝ ██║<br />
██║ ██║ ██║██║╚██╗██║██╔══╝ ██╔══██║██╔══██╗ ██║<br />
██║ ███████╗██║██║ ╚████║███████╗ ██║ ██║██║ ██║ ██║<br />
╚═╝ ╚══════╝╚═╝╚═╝ ╚═══╝╚══════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═╝<br />
]])<br />
</syntaxhighlight><br />
<br />
==cecho2ansi PR# 5672 merged==<br />
<br />
; ansiFormattedString = cecho2ansi(text)<br />
<br />
:Converts cecho formatted text to ansi formatted text. Used by cfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#cecho|cecho()]], [[Manual:Lua_Functions#cfeedTriggers|cfeedTriggers()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
{{note}} This function uses the ansi short colors (0-15) for color names which have base 16 ansi equivalents, such as 'red', 'blue', "lightBlue", "cyan", etc rather than the values defined in the color_table. If there is no base ansi equivalent then it will use the rgb values from the color_table for the color.<br />
<br />
;Parameters<br />
* ''text:''<br />
: The cecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of cfeedTriggers() for a single line.<br />
-- you would most likely just use cfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(cecho2ansi("\n<red>This is red.<reset> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
==decho PR #5669 merged PR5719 merged PR5751 open==<br />
;decho ([name of console,] text)<br />
: Color changes can be made using the format <FR,FG,FB:BR,BG,BB,[BA]> where each field is a number from 0 to 255. The background portion can be omitted using <FR,FG,FB> or the foreground portion can be omitted using <:BR,BG,BB,[BA]>. Arguments 2 and 3 set the default fore and background colors for the string using the same format as is used within the string, sans angle brackets, e.g. ''decho("<50,50,0:0,255,0>test")''.<br />
:You can also include <code><nowiki><i>italics</i></nowiki></code>, <code><nowiki><b>bold</b></nowiki></code>, <code><nowiki><s>strikethrough</s></nowiki></code>, <code><nowiki><o>overline</o></nowiki></code>, and <code><nowiki><u>underline</u></nowiki></code> tags.<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15; however, it does not turn a label into a miniconsole and every time you decho it will erase any previous echo sent to the label.<br />
<br />
: See also: [[#cecho|cecho()]], [[#hecho|hecho()]], [[#copy2decho|copy2decho()]]<br />
<br />
;Parameters<br />
* ''name of console''<br />
: (Optional) Name of the console to echo to. If no name is given, this will defaults to the main window.<br />
* ''text:''<br />
: The text that you’d like to echo with embedded color tags. Tags take the RGB values only, see below for an explanation.<br />
<br />
<br />
{{note}}<br />
Optional background transparancy parameter (BA) available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
decho("<50,50,0:0,255,0>test")<br />
<br />
decho("miniconsolename", "<50,50,0:0,255,0>test")<br />
<br />
decho("\n<255,0,0>Red text with <i>italics</i>, <u>underline</u>, <s>strikethrough</s>, and <b>bold</b> formatting.")<br />
<br />
decho("<\n<0,128,0><o><u>Green text with both over and underlines.</u></o>")<br />
</syntaxhighlight><br />
<br />
==decho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = decho2ansi(text)<br />
<br />
:Converts decho formatted text to ansi formatted text. Used by dfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#dfeedTriggers|dfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The decho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of dfeedTriggers() for a single line.<br />
-- you would most likely just use dfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(decho2ansi("\n<128,0,0>This is red.<r> <i>italic</i>, <b>bold</b>, <s>strikethrough</s>, <u>underline</u>\n"))<br />
</syntaxhighlight><br />
<br />
==getHTMLspan PR#5751 open==<br />
<br />
; spanTag = getHTMLspan(formatTable)<br />
<br />
:Takes in a table of formatting options in the same style as [[Manual:Lua_Functions#getTextFormat|getTextFormat()]] and returns a span tag which will format text after it as the table describes.<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getLabelFormat|getLabelFormat()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''formatTable:''<br />
: Table with formatting options configured. Keys are foreground, background, bold, underline, overline, strikeout, italic, and reverse. All except for foreground and background should be boolean (true/false) values. Foreground and background are either { r, g, b, a } tables, or strings with QSS formatting directives<br />
<br />
;Returns <br />
* A string with the html span tag to format text in accordance with the format table.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Returns a span tag for bold, red text on a green background<br />
local span = getHTMLspan({<br />
foreground = { 255, 0, 0 },<br />
background = "#00FF00",<br />
bold = true<br />
})<br />
<br />
-- span will be '<span style="color: rgb(255, 0, 0);background-color: #00FF00; font-weight: bold; font-style: normal; text-decoration: none;">'<br />
</syntaxhighlight><br />
<br />
==getLabelFormat PR#5751 open==<br />
<br />
; formatTable = getLabelFormat(labelName)<br />
<br />
:Returns a format table like the one returned by getTextFormat and suitable for getHTMLspan which will format text the same way as simply doing an echo to the label would<br />
<br />
;See also: [[Manual:Lua_Functions#getTextFormat|getTextFormat()]], [[Manual:Lua_Functions#getHTMLspan|getHTMLspan()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''labelName:''<br />
: The name of the label to scan the format of<br />
<br />
;Returns <br />
* A table with all the formatting options to achieve a default text format for label labelName. <br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- creates a test label, sets a stylesheet, and then returns the default format table for that label.<br />
createLabel("testLabel", 10, 10, 300, 200, 1)<br />
setLabelStyleSheet([[<br />
color: rgb(0,0,180);<br />
border-width: 1px;<br />
border-style: solid;<br />
border-color: gold;<br />
border-radius: 10px;<br />
font-size: 12.0pt;<br />
background: QLinearGradient( x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #98f041, stop: 0.1 #8cf029, stop: 0.49 #66cc00, stop: 0.5 #52a300, stop: 1 #66cc00);<br />
]])<br />
local fmt = getLabelFormat("testLabel"))<br />
<br />
--[[<br />
{<br />
background = "rgba(0, 0, 0, 0)", -- this is transparent<br />
bold = false,<br />
foreground = "rgb(0,0,180)",<br />
italic = false,<br />
overline = false,<br />
reverse = false,<br />
strikeout = false,<br />
underline = false<br />
}<br />
--]]<br />
<br />
</syntaxhighlight><br />
<br />
==hecho PR #5669 merged, PR5719 merged, PR5751 open==<br />
;hecho([windowName], text)<br />
: Echoes text that can be easily formatted with colour tags in the hexadecimal format. You can also use italics, bold, strikethrough, and underline tags.<br />
: See Also: [[Manual:Lua_Functions#decho|decho()]], [[Manual:Lua_Functions#cecho|cecho()]]<br />
<br />
{{Note}} Support for labels added in Mudlet 4.15<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: (optional) name of the window to echo to. Can either be omitted or "main" for the main window, else specify the miniconsoles name.<br />
* ''text:''<br />
: The text to display, with color changes made within the string using the format |cFRFGFB,BRBGBB or #FRFGFB,BRBGBB where FR is the foreground red value, FG is the foreground green value, FB is the foreground blue value, BR is the background red value, etc., BRBGBB is optional. |r or #r can be used within the string to reset the colors to default. Hexadecimal color codes can be found here: https://www.color-hex.com/<br />
<br />
{{note}}<br />
Transparency for background in hex-format available in Mudlet 4.10+<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
hecho("\n#ffffff White text!")<br />
-- your text in white<br />
hecho("\n#ca0004 Red text! And now reset #rit to the default color")<br />
-- your text in red, then reset to default using #r<br />
hecho("\n#ffffff,ca0004 White text with a red background!")<br />
-- your text in white, against a red background<br />
hecho("\n|c0000ff Blue text, this time using |c instead of #")<br />
-- your text in blue, activated with |c vs #.<br />
hecho("\n#ff0000Red text with #iitalics#/i, |uunderline|/u, #ooverline#/o, #sstrikethrough#/s, and #bbold#/b formatting.")<br />
-- shows the various individual formatting options<br />
hecho("\n#008000#o#uGreen text with both over and underlines.#/o#/u")<br />
</syntaxhighlight><br />
<br />
==hecho2ansi PR# 5671 merged==<br />
<br />
; ansiFormattedString = hecho2ansi(text)<br />
<br />
:Converts hecho formatted text to ansi formatted text. Used by hfeedTriggers, but useful if you want ansi formatted text for any other reason.<br />
<br />
;See also: [[Manual:Lua_Functions#hecho|hecho()]], [[Manual:Lua_Functions#hfeedTriggers|hfeedTriggers()]]<br />
<br />
{{MudletVersion|4.10+}}<br />
<br />
{{Note}} non-color formatting added in Mudlet 4.15+<br />
<br />
;Parameters<br />
* ''text:''<br />
: The hecho formatted text for conversion<br />
<br />
;Returns <br />
* String converted to ansi formatting<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- replicates the functionality of hfeedTriggers() for a single line.<br />
-- you would most likely just use hfeedTriggers, but it makes for a tidy example.<br />
feedTriggers(hecho2ansi("\n#800000This is red.#r #iitalic#/i, #bbold#/b, #sstrikethrough#/s, #uunderline#/u\n"))<br />
</syntaxhighlight><br />
<br />
==windowType PR# 5696 open==<br />
; typeOfWindow = windowType(windowName)<br />
<br />
:Given the name of a window, will return if it's a label, miniconsole, userwindow or a commandline.<br />
<br />
;See also: [[Manual:Lua_Functions#createLabel|createLabel()]], [[Manual:Lua_Functions#openUserWindow|openUserWindow()]]<br />
<br />
{{MudletVersion|4.15}}<br />
<br />
;Parameters<br />
* ''windowName:''<br />
: The name used to create the window element. Use "main" for the main console<br />
<br />
<br />
;Returns <br />
* Window type as string ("label", "miniconsole", "userwindow", or "commandline") or nil+error if it does not exist.<br />
<br />
;Example<br />
<syntaxhighlight lang="lua"><br />
-- Create a Geyser label and and check its type<br />
testLabel = Geyser.Label:new({name = "testLabel"})<br />
display(windowType(testLabel.name)) -- displays "label"<br />
<br />
-- the main console returns "miniconsole" because it uses the same formatting functions<br />
display(windowType("main")) -- displays "miniconsole"<br />
<br />
-- check for the existence of a window<br />
local windowName = "this thing does not exist"<br />
local ok, err = windowType(windowName)<br />
if ok then<br />
-- do things with it, as it does exist.<br />
-- the ok variable will hold the type of window it is ("label", "commandline", etc)<br />
else<br />
cecho("<red>ALERT!! window does not exist")<br />
end<br />
</syntaxhighlight><br />
<br />
; Additional development notes<br />
<br />
=Discord Functions=<br />
: 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 [[Special:MyLanguage/Manual:Scripting#Discord_Rich_Presence|Discord scripting overview]].</div>Demonnic