Area 51
This page is for the development of documentation for Lua API functions that are currently being worked on. Ideally the entries here can be created in the same format as will be eventually used in Lua Functions and its sub-sites.
Note: Please use the Area_51/Template to add new entries in the sections below.
Note: Links to other functions need to include the wiki page name before the '#' character in the link identifier on the left side of the '|' divider between the identifier and the display text. e.g.
- [[Manual:Lua_Functions#getCustomLines|getCustomLines()]]
rather than:
- [[#getCustomLines|getCustomLines()]]
which would refer to a link within the current (in this case Area 51) section.
Note: The following headings reflect those present in the main Wiki area of the Lua API functions. It is suggested that new entries are added so as to maintain a sorted alphabetical order under the appropriate heading.
Basic Essential Functions
- These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.
Database Functions
- A collection of functions for helping deal with the database.
Date/Time Functions
- A collection of functions for handling date & time.
File System Functions
- A collection of functions for interacting with the file system.
GMCP Extensions
- A collection of GMCP options for UI builders or server administrators.
Mapper Functions
- A collection of functions that manipulate the mapper and its related features.
setRoomBorderStyle, PR #8985
- setRoomBorderStyle(roomID, style)
- Sets the border style for a specific room on the map. This allows visually distinguishing rooms with dashed or dotted borders instead of the
default solid border - useful for marking temporary, unvisited, or special rooms.
- See also: setRoomBorderColor(), setRoomBorderThickness(), getRoomBorderStyle(), clearRoomBorderStyle()
- Parameters
- roomID:
- The ID of the room to set the border style for.
- style:
- The border style to apply. Valid values: "dashed" (or "dash line") for a dashed border, "dotted" (or "dot line") for a dotted border, or "solid" to reset to the default solid border.
- Returns
- true on success, or nil and an error message if no map is loaded or the room ID is invalid.
- Example
-- set room 1234 to have a dashed border
setRoomBorderStyle(1234, "dashed")
-- set room 1234 to have a dotted border
setRoomBorderStyle(1234, "dotted")
-- reset room 1234 back to solid border
setRoomBorderStyle(1234, "solid")
getRoomBorderStyle, PR #8985
- getRoomBorderStyle(roomID)
- Returns the border style for a specific room on the map.
- See also: setRoomBorderStyle(), clearRoomBorderStyle()
- Parameters
- roomID:
- The ID of the room to get the border style for.
- Returns
- "dashed" if the room has a dashed border, "dotted" if the room has a dotted border, or nil if the room has the default solid border.
- Example
local style = getRoomBorderStyle(1234)
if style then
echo(f"Room 1234 has a {style} border.\n")
else
echo("Room 1234 has a solid (default) border.\n")
end
clearRoomBorderStyle, PR #8985
- clearRoomBorderStyle(roomID)
- Resets the border style for a specific room back to the default solid border.
- See also: setRoomBorderStyle(), getRoomBorderStyle()
- Parameters
- roomID:
- The ID of the room to clear the border style for.
- Returns
- true on success, or nil and an error message if no map is loaded or the room ID is invalid.
- Example
-- reset room 1234 back to solid border
clearRoomBorderStyle(1234)
moveMapLabel, PR #6014 open
- moveMapLabel(areaID/Name, labeID/Text, coordX/deltaX, coordY/deltaY[, coordZ/deltaZ][, absoluteNotRelativeMove])
Re-positions a map label within an area in the 2D mapper, in a similar manner as the moveRoom() function does for rooms and their custom exit lines. When moving a label to given coordinates this is the position that the top-left corner of the label will be positioned at; since the space allocated to a particular room on the map is ± 0.5 around the integer value of its x and y coordinates this means for a label which has a size of 1.0 x 1,0 (w x h) to position it centrally in the space for a single room at the coordinates (x, y, z) it should be positioned at (x - 0.5, y + 0.5, z).
- See also: getMapLabels(), getMapLabel().
Note: pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6014
- Parameters
- areaID/Name:
- Area ID as number or AreaName as string containing the map label.
- labelID/Text:
- Label ID as number (which will be 0 or greater) or the LabelText on a text label. All labels will have a unique ID number but there may be more than one text labels with a non-empty text string; only the first matching one will be moved by this function and image labels also have no text and will match the empty string. with mo or AreaName as string containing the map label.
- coordX/deltaX:
- A floating point number for the absolute coordinate to use or the relative amount to move the label in "room coordinates" along the X-axis.
- coordY/deltaY:
- A floating point number for the absolute coordinate to use or the relative amount to move the label in "room coordinates" along the Y-axis.
- coordZ/deltaZ:
- (Optional) A floating point number for the absolute coordinate to use or the relative amount to move the label in "room coordinates" along the Z-axis, if omitted the label is not moved in the z-axis at all.
- absoluteNotRelativeMove:
- (Optional) a boolean value (defaults to false if omitted) as to whether to move the label to the absolute coordinates (true) or to move it the relative amount from its current location (false).
- Returns
- true on success or nil and an error message on failure, if successful it will also refresh the map display to show the result.
- Example
-- move the first label in the area with the ID number of 2, three spaces to the east and four spaces to the north
moveMapLabel(0, 2, 3.0, 4.0)
-- move the first label in the area with the ID number of 2, one space to the west, note the final boolean argument is unneeded
moveMapLabel(0, 2, -1.0, 0.0, false)
-- move the second label in the area with the ID number of 2, three and a half spaces to the west, and two south **of the center of the current level it is on in the map**:
moveRoom(1, 2, -3.5, -2.0, true)
-- move the second label in the area with the ID number of 2, up three levels
moveRoom(1, 2, 0.0, 0.0, 3.0)
-- move the second label in the "Test 1" area one space to the west, note the last two arguments are unneeded
moveRoom("Test 1", 1, -1.0, 0.0, 0.0, false)
-- move the (top-left corner of the first) label with the text "Home" in the area with ID number 5 to the **center of the whole map**, note the last two arguments are required in this case:
moveRoom(5, "Home", 0.0, 0.0, 0.0, true)
-- all of the above will return the 'true' boolean value assuming there are the indicated labels and areas
moveRoom, PR #6010 open
- moveRoom(roomID, coordX/deltaX, coordY/deltaY[, coordZ/deltaZ][, absoluteNotRelativeMove])
Re-positions a room within an area, in the same manner as the "move to" context menu item for one or more rooms in the 2D mapper. Like that method this will also shift the entirety of any custom exit lines defined for the room concerned. This contrasts with the behavior of the setRoomCoordinates() which only moves the starting point of such custom exit lines so that they still emerge from the room to which they belong but otherwise remain pointing to the original place.
- See also: setRoomCoordinates()
Note: pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/6010
- Parameters
- roomID:
- Room ID number to move.
- coordX/deltaX:
- The absolute coordinate or the relative amount as a number to move the room in "room coordinates" along the X-axis.
- coordY/deltaY:
- The absolute coordinate or the relative amount as a number to move the room in "room coordinates" along the Y-axis.
- coordZ/deltaZ:
- (Optional) the absolute coordinate or the relative amount as a number to move the room in "room coordinates" along the Z-axis, if omitted the room is not moved in the z-axis at all.
- absoluteNotRelativeMove:
- (Optional) a boolean value (defaults to false if omitted) as to whether to move the room to the absolute coordinates (true) or the relative amount from its current location (false).
- Returns
- true on success or nil and an error message on failure, if successful it will also refresh the map display to show the result.
- Example
-- move the first room one space to the east and two spaces to the north
moveRoom(1, 1, 2)
-- move the first room one space to the west, note the final boolean argument is unneeded
moveRoom(1, -1, 0, false)
-- move the first room three spaces to the west, and two south **of the center of the current level it is on in the map**:
moveRoom(1, -3, -2, true)
-- move the second room up three levels
moveRoom(2, 0, 0, 3)
-- move the second room one space to the west, note the last two arguments are unneeded
moveRoom(2, -1, 0, 0, false)
-- move the second room to the **center of the whole map**, note the last two arguments are required in this case:
moveRoom(2, 0, 0, 0, true)
-- all of the above will return the 'true' boolean value assuming there are rooms with 1 and 2 as ID numbers
Miscellaneous Functions
- Miscellaneous functions.
updateMusic, PR #12041 open
- updateMusic(settings table)
- Changes the volume of music that is already playing, without restarting it. The music glides to the new volume over "duration" milliseconds, so it can swell or fade as the player moves.
- Only music played by scripts with playMusicFile() is changed, not music the game plays.
| Required | Key | Value | Default | Purpose |
|---|---|---|---|---|
| Maybe | name | <file name> |
| |
| Maybe | key | <key> |
| |
| Maybe | tag | <tag> |
| |
| No | volume | 1 to 100 | unchanged |
|
| No | duration | <msec> | 0 |
|
- When more than one of name, key and tag is given, music must match all of them.
- Keys in the settings table may be given in any letter case.
- Music is never placed left or right, so "pan" and "direction" are not taken: use updateSounds() for sounds.
- An update can follow its playMusicFile() straight away, even before the file has downloaded. It applies once the music plays.
- Returns
- true, or nil and an error message when no name, key or tag was given, or nothing to change (a volume). Naming music that is not playing is not an error.
- An argument of the wrong type, or a negative duration, raises an error.
See also: getPausedMusic(), getPlayingMusic(), pauseMusic(), playMusicFile(), stopMusic(), updateSounds(), Client.Media.Update
- Example
-- The tavern's music swells as the player walks in, over two seconds
playMusicFile({name = "tavern.mp3", key = "area-music", volume = 20, loops = -1})
updateMusic({key = "area-music", volume = 60, duration = 2000})
-- Every track tagged "ambience" drops back at once
updateMusic({tag = "ambience", volume = 15})
getCustomLoginTextId, PR #3952 open
- getCustomLoginTextId()
Returns the Id number of the custom login text setting from the profile's preferences. Returns 0 if the option is disabled or a number greater than that for the item in the table; note it is possible if using an old saved profile in the future that the number might be higher than expected. As a design policy decision it is not permitted for a script to change the setting, this function is intended to allow a script or package to check that the setting is what it expects.
Introduced along with four other functions to enable game server log-in to be scripted with the simultaneous movement of that functionality from the Mudlet application core code to a predefined doLogin() function, a replacement for which is shown below.
Note: Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952
Only one custom login text has been defined initially:
| Id | Custom text | Introduced in Mudlet version |
|---|---|---|
| 1 | "connect {character name} {password}" | TBD |
The addition of further texts would be subject to negotiation with the Mudlet Makers.
- Example
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:
function doLogin()
if getCustomLoginTextId() ~= 1 then
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")
else
tempTime(2.0, [[sendCustomLoginText()]], 1)
end
end
sendCharacterName, PR #3952 open
- sendCharacterName()
Sends the name entered into the "Character name" field on the Connection Preferences form directly to the game server. Returns true unless there is nothing set in that entry in which case a nil and an error message will be returned instead.
Introduced along with four other functions to enable game server log-in to be scripted with the simultaneous movement of that functionality from the Mudlet application core code to a predefined doLogin() function that may be replaced for more sophisticated requirements.
- See also: getCharacterName(), sendCharacterPassword(), sendCustomLoginText(), getCustomLoginTextId().
Note: Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952
sendCharacterPassword, PR #3952 open
- sendCharacterPassword()
Sends the password entered into the "Password" field on the Connection Preferences form directly to the game server. Returns true unless there is nothing set in that entry or it is too long after (or before) a connection was successfully made in which case a nil and an error message will be returned instead.
Introduced along with four other functions to enable game server log-in to be scripted with the simultaneous movement of that functionality from the Mudlet application core code to a predefined doLogin() function, reproduced below, that may be replaced for more sophisticated requirements.
Note: Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952
- Example
-- The default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:
function doLogin()
if getCharacterName() ~= "" then
tempTime(2.0, [[sendCharacterName()]], 1)
tempTime(3.0, [[sendCharacterPassword()]], 1)
end
end
sendCustomLoginText, PR #3952 open
- sendCustomLoginText()
Sends the custom login text (which does NOT depend on the user's choice of GUI language) selected in the preferences for this profile. The {password} (and {character name} if present) fields will be replaced with the values entered into the "Password" and "Character name" fields on the Connection Preferences form and then sent directly to the game server. Returns true unless there is nothing set in either of those entries (though only if required for the character name) or it is too long after (or before) a connection was successfully made or if the custom login feature is disabled, in which case a nil and an error message will be returned instead.
Introduced along with four other functions to enable game server log-in to be scripted with the simultaneous movement of that functionality from the Mudlet application core code to a predefined doLogin() function, a replacement for which is shown below.
Note: Not available yet. See https://github.com/Mudlet/Mudlet/pull/3952
Only one custom login text has been defined initially:
| Id | Custom text | Introduced in Mudlet version |
|---|---|---|
| 1 | "connect {character name} {password}" | TBD |
The addition of further texts would be subject to negotiation with the Mudlet Makers.
- Example
-- A replacement for the default function placed into LuaGlobal.lua to reproduce the previous behavior of the Mudlet application:
function doLogin()
if getCustomLoginTextId() ~= 1 then
-- We need this particular option but it is not permitted for a script to change the setting, it can only check what it is
echo("\nUnable to login - please select the 'connect {character name} {password}` custom login option in the profile preferences.\n")
else
tempTime(2.0, [[sendCustomLoginText()]], 1)
end
end
Mudlet Object Functions
- A collection of functions that manipulate Mudlet's scripting objects - triggers, aliases, and so forth.
Networking Functions
- A collection of functions for managing networking.
getTelnetOptionsStatus PR #8962, open
- getTelnetOptionsStatus()
- Returns the current status of telnet options that have been negotiated between Mudlet and the game server. This function is useful for debugging telnet protocol issues and understanding which features are currently enabled in your connection. The values returned are the same as those that would be reported back to the Server if it requested them via the telnet option number 5 (STATUS).
- The function returns a table where each key is a telnet option number (0-255), and the value is a sub-table containing the option details. Only options that have been negotiated so far during the telnet session are included in the results. As nearly all options are handled separately in the two directions each numbered option has two statuses to report,
- See also: Telnet Protocols
- Returns
- A table with telnet option numbers as keys, each containing:
- Name: A string with the human-readable name of the telnet option (e.g., "ECHO (1)", "NAWS (31)", "MCCP2 (86)")
- Server: (optional) Boolean indicating if the server (who sent the <IAC><WILL><OPTION> to which Mudlet replied<IAC><DO><OPTION> to agree or <IAC><DONT><OPTION> to disagree to it) has this option enabled (true) or disabled (false). Only present if the server requested this option.
- Mudlet: (optional) Boolean indicating if Mudlet (who sent the <IAC><WILL><OPTION> to which the Server replied <IAC><DO><OPTION> to agree or <IAC><DONT><OPTION> to disagree to it) has this option enabled (true) or disabled (false). Only present if Mudlet requested this option.
- Example
-- Display all negotiated telnet options
local options = getTelnetOptionsStatus()
cecho("<cyan>Current Telnet Options Status:\n")
for optionNumber, details in pairs(options) do
cecho(string.format("<white>Option %d: <yellow>%s<reset>\n", optionNumber, details.Name))
if details.Server ~= nil then
if details.Server then
cecho(" <white>Server: <green>enabled<reset>\n")
else
cecho(" <white>Server: <red>disabled<reset>\n")
end
end
if details.Mudlet ~= nil then
if details.Mudlet ~= nil then
cecho(" <white>Mudlet: <green>enabled<reset>\n")
else
cecho(" <white>Mudlet: <red>disabled<reset>\n")
end
end
end
-- Check if compression (MCCP2) is enabled
local options = getTelnetOptionsStatus()
-- Option 86 is MCCP2 (Mud Client Compression Protocol 2)
if options[86] and options[86].Server then
cecho("<green>Compression is enabled!\n")
else
cecho("<red>Compression is not active.\n")
end
-- Monitor telnet negotiation on connect
function checkTelnetFeatures()
local options = getTelnetOptionsStatus()
-- Check for common features
local features = {
[1] = "Echo",
[3] = "Suppress Go Ahead",
[24] = "Terminal Type",
[31] = "Negotiate Window Size (NAWS)",
[69] = "MSDP",
[86] = "MCCP2 Compression",
[201] = "GMCP"
}
cecho("<cyan>Enabled Features:\n")
for optNum, name in pairs(features) do
if options[optNum] then
local status = "announced"
if options[optNum].Server and options[optNum].Mudlet then
status = "fully enabled"
elseif options[optNum].Server then
status = "server enabled"
elseif options[optNum].Mudlet then
status = "client enabled"
end
cecho(string.format("<white>%s: <green>%s\n", name, status))
end
end
end
registerAnonymousEventHandler("sysConnectionEvent", "checkTelnetFeatures")
Note: This function is primarily intended for debugging telnet protocol issues. Most users won't need to use it in normal scripts, as Mudlet handles telnet negotiation automatically. At the time of introduction there is a suspicion that the status of some options were not being correctly handled and this function was created to provide a means to monitor them.
Note: pending, not yet available. See https://github.com/Mudlet/Mudlet/pull/8962
String Functions
- These functions are used to manipulate strings.
Table Functions
- These functions are used to manipulate tables. Through them you can add to tables, remove values, check if a value is present in the table, check the size of a table, and more.
Text to Speech Functions
- These functions are used to create sound from written words. Check out our Text-To-Speech Manual for more detail on how this all works together.
UI Functions
- These functions are used to construct custom user GUIs. They deal mainly with miniconsole/label/gauge creation and manipulation as well as displaying or formatting information on the screen.
insertPopup, revised in PR #6925
- insertPopup([windowName], text, {commands}, {hints}[{, tool-tips}][, useCurrentFormatElseDefault])
- Creates text with a left-clickable link, and a right-click menu for more options at the end of the current line, like echo. The added text, upon being left-clicked, will do the first command in the list. Upon being right-clicked, it'll display a menu with all possible commands. The menu will be populated with hints, one for each line; if a tool-tips table is not provided the same hints will also be listed one-per-line as a tool-tip but if a matching number of tool-tips are provided they will be concatenated to provide a tool-tip when the text is hovered over by the pointer - these tool-tips can be rich-text to produce information formatted with additional content in the same manner as labels.
- Parameters
- windowName:
- (optional) name of the window as a string to echo to. Use either main or omit for the main window, or the miniconsole's or user-window's name otherwise.
- text:
- the text string to display.
- {commands}:
- a table of lua code to do, in text strings or as functions (since Mudlet 4.11), i.e.
{[[send("hello")]], function() echo("hi!") end}.
- {hints}:
- a table of strings which will be shown on the right-click menu (and popup if no {tool-tips} table is provided). If a particular position in both the commands and hints table are both the empty string "" but there is something in the tool-tips table, no entry for that position will be made in the context menu but the tool-tip can still display something which can include images or text.
- {tool-tips}:
- (optional) a table of possibly rich-text strings which will be shown on the popup if provided.
- useCurrentFormatElseDefault:
- (optional) a boolean value for using either the current formatting options (color, underline, italic and other effects) if true or the link default (blue underline) if false, if omitted the default format is used.
Note: Mudlet will distinguish between the optional tool-tips and the flag to switch between the standard link and the current text format by examining the type of the argument, as such this pair of arguments can be in either order.
- Example
-- Create some text as a clickable with a popup menu, a left click will ''send "sleep"'':
insertPopup("activities to do", {function() send "sleep" end, function() send "sit" end, function() send "stand" end}, {"sleep", "sit", "stand"})
-- alternatively, put commands as text (in [[ and ]] to use quotation marks inside)
insertPopup("activities to do", {[[send "sleep"]], [[send "sit"]], [[send "stand"]]}, {"sleep", "sit", "stand"})
-- one can also provide helpful information
-- todo: an example with rich-text in the tool-tips(s)
Discord Functions
- All functions to customize the information Mudlet displays in Discord's rich presence interface. For an overview on how all of these functions tie in together, see our Discord scripting overview.
Mud Client Media Protocol
- All GMCP functions to send sound and music events. For an overview on how all of these functions tie in together, see our MUD Client Media Protocol scripting overview.
Supported Protocols
Events
- New or revised events that Mudlet can raise to inform a profile about changes. See Mudlet-raised events for the existing ones.
UI Functions
- 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.
=Protocols+
OSC 8: Hyperlink Protocol (Add when 5.2 deploys)
OSC 8 is a standardized terminal escape sequence that enables clickable hyperlinks in terminal output. Mudlet extends it with styling and interactivity, as an alternative to MXP that restricts links to an allowlist of schemes.
The extensions are specified for every client and server in OSC 8 Hyperlinks: MUD Client Extensions. This section describes Mudlet's implementation.
At a glance
- A link is text between two escape sequences. The first carries a URI, and its scheme says what a click does: send a command or a GMCP message, fill the input line, open a web or mail address, connect to another game, or do nothing outside Mudlet.
- A
configparameter on the URI carries JSON that styles the link and gives it a tooltip, a menu, a spoiler, a selected state or timed visibility. - Mudlet reports each feature as a telnet NEW-ENVIRON variable. A server sends a feature only when Mudlet reports it, and any other client shows the link's text.
- Examples for Games puts the features together: exits to click, item menus, shop buttons, settings checkboxes and notices that clear themselves.
Quick Start
Send this command in Mudlet to see working examples:
say !osc8-docs
To try a link of your own without a server, type this in Mudlet's input line. feedTriggers() handles the text as if the game had sent it:
lua feedTriggers('\27]8;;send:look?config={"tooltip":"Look around the room"}\27\\Look\27]8;;\27\\\n')
A server builds the same sequence. In Python, for example:
import json
from urllib.parse import quote
def link(text, uri, config=None):
if config:
uri += "?config=" + quote(json.dumps(config, separators=(",", ":")), safe="")
return f"\x1b]8;;{uri}\x1b\\{text}\x1b]8;;\x1b\\"
def send(command):
return "send:" + quote(command, safe="")
print("Exits: " + link("north", send("north"), {"tooltip": "North to the Market Square"}))
Any language works the same way: percent-encode the command and the JSON, then wrap the text in the two sequences.
Feature Overview
| Feature | What it does | Variable | Version |
|---|---|---|---|
| Basic links | Send a command, fill the input line, open a web page | OSC_HYPERLINKS, OSC_HYPERLINKS_SEND, OSC_HYPERLINKS_PROMPT |
|
| Mail and game links | Open the mail app, or connect to another game after asking | OSC_HYPERLINKS |
|
| GMCP and local links | Send a GMCP message, or put a tooltip, menu or checklist on text without sending anything | OSC_HYPERLINKS_GMCP, OSC_HYPERLINKS_LOCAL |
|
| Style | Colors, weight and decorations | OSC_HYPERLINKS_STYLE_BASIC |
|
| Interactive states | Hover, pressed and visited styles | OSC_HYPERLINKS_STYLE_STATES |
|
| Tooltips | Text shown on hover | OSC_HYPERLINKS_TOOLTIP |
|
| Context menus | Several actions on one link, under an optional title | OSC_HYPERLINKS_MENU |
|
| Visibility | Hide or show a link on a timer or an event | OSC_HYPERLINKS_VISIBILITY |
|
| Spoilers | Text hidden until clicked | OSC_HYPERLINKS_SPOILER |
|
| Disabled links | Links shown but switched off | OSC_HYPERLINKS_DISABLED |
|
| Selection | Radio buttons, checkboxes and toggles | OSC_HYPERLINKS_SELECTION |
|
| Accessibility | Keyboard navigation and screen readers | None needed | |
| Compact syntax | Short property names | OSC_HYPERLINKS_COMPACT |
|
| Presets | Configurations defined once and used by name | OSC_HYPERLINKS_PRESETS |
|
| Display sanitization | Invisible characters shown, not rendered | None needed |
Note:
Every variable reports 0 while the player has turned OSC 8 off. See Turning OSC 8 Off.
Understanding OSC Sequences
OSC (Operating System Command) sequences are part of the ANSI escape sequence family. They allow terminals to receive structured commands from servers, including hyperlink definitions. A sequence starts with ESC ], carries its command, and ends with the String Terminator, ESC \.
| Character | ASCII | Hex | Description |
|---|---|---|---|
| ESC | 27 | 0x1B | Escape character - starts all ANSI sequences |
| ] | 93 | 0x5D | Right bracket - identifies OSC sequences |
| \ | 92 | 0x5C | Backslash - with ESC forms String Terminator |
| ; | 59 | 0x3B | Semicolon - separates parameters |
Note: A sequence must be terminated by either a String Terminator, ESC \, or a BEL (0x07), whichever arrives first. Both have been accepted since Mudlet version 4.20. If neither arrives before the end of the line the sequence started on, Mudlet abandons it and logs a warning, so a stray introducer cannot black out the rest of the session. A sequence longer than 4096 characters has its command ignored, also with a warning.
Basic Links
Create clickable text that sends a command to the game, pre-fills the input line, or opens a web page.
OSC 8 hyperlinks work like HTML tags. The opening sequence carries the link's URI, the link text follows, and a sequence with an empty URI ends the link:
ESC ] 8 ; params ; URI ESC \ visible text ESC ] 8 ; ; ESC \
│ │ │ │
│ │ └── Link target (URL/command) │
│ └── Optional parameters (unused) │
└── OSC 8 identifier └── Empty = close link
- The link text can include ANSI color and formatting.
- A link whose scheme Mudlet does not support is not a link, and Mudlet shows its text as plain text.
- Write schemes in lower case. Mudlet recognizes
send:,prompt:,gmcp:andlocal:only in lower case. - A sequence that opens a link ends any link still open, even when Mudlet does not make the new one.
Available in Mudlet5.1+
URI Schemes
| Scheme | A click | Example | Variable |
|---|---|---|---|
send: |
Sends the command to the game | send:look |
OSC_HYPERLINKS_SEND
|
prompt: |
Puts the command in the input line, for the player to edit | prompt:cast%20fireball |
OSC_HYPERLINKS_PROMPT
|
gmcp: |
gmcp:IRE.Target.Set%20%22rat%22 |
OSC_HYPERLINKS_GMCP
| |
local: |
local:?config=... |
OSC_HYPERLINKS_LOCAL
| |
http: / https: |
Opens the address in the default web browser | https://www.mudlet.org |
OSC_HYPERLINKS
|
ftp: |
Opens the address in the default handler | ftp://files.example.com |
OSC_HYPERLINKS
|
mailto: |
mailto:[email protected]?subject=Hello |
OSC_HYPERLINKS
| |
telnet: / telnets: |
telnet://games.example:4000 |
OSC_HYPERLINKS
| |
preset: |
Not a link: defines a preset | preset:btn?config=... |
OSC_HYPERLINKS_PRESETS
|
send: sends the command as written: Mudlet does not run the player's aliases on it, and by default does not echo it. send: with no command sends an empty line, which a pager can read as "continue".
Examples
Send a command:
ESC ] 8 ; ; send:look ESC \ Look ESC ] 8 ; ; ESC \
Fill the input line:
ESC ] 8 ; ; prompt:cast%20fireball ESC \ Cast Fireball ESC ] 8 ; ; ESC \
Open a web page:
ESC ] 8 ; ; https://www.mudlet.org ESC \ Visit Mudlet ESC ] 8 ; ; ESC \
Note:
When an OSC 8 link and an MXP link nest, a click runs the innermost link around the text. MXP text inside an OSC 8 link, such as the entity &, takes the link's style and is hidden with its spoiler, while an MXP link inside a spoiler stays visible.
Mail and Game Links
A link can open an email to the game's staff, or take the player to another game, such as a sister game or a builders' port. Both come with OSC_HYPERLINKS, and Mudlet 5.1 and older show their text as plain text.
Mail links. A mailto: link opens the player's mail app, with the subject or body that the link gives.
- Mudlet keeps only the recipients (the address,
to,ccandbcc),subjectandbody. It drops every other field, since mail apps act on them:attachcan add one of the player's files to the email. - Mudlet does not make a link whose address or recipients hide a
?,&or#once decoded, since a mail app could read a field hidden there. - The default tooltip reads Write an email to: mailto:[email protected].
Game links. A telnet: or telnets: link connects to a game from inside Mudlet.
- Mudlet asks the player every time, such as Connect to games.example:4000? When one of the player's profiles uses that address, the question names the profile and says that it will log in with the saved details.
- Once the player agrees, Mudlet opens that profile, or creates one named after the host, and connects. A profile that is already connected is brought to the front.
telnets:connects with TLS, and needs a host name: Mudlet does not make atelnets:link to an IP address. It leaves a saved profile's own TLS setting alone, and saves a profile it creates with TLS on.- The default ports are 23 for
telnet:and 992 fortelnets:. An address with no host, or with a port outside 1 to 65535, is not a link. - The default tooltip reads Connect to: telnet://games.example:4000.
Example: write to the staff, or visit the builders' port
ESC ] 8 ; ; mailto:[email protected]?subject=Bug%20report ESC \ email the staff ESC ] 8 ; ; ESC \ ESC ] 8 ; ; telnet://builders.example.com:4001 ESC \ the builders' port ESC ] 8 ; ; ESC \
The first opens a new email to [email protected] with the subject Bug report. The second asks the player before connecting.
GMCP and Local Links
A gmcp: link sends a GMCP message instead of a command, and a local: link sends nothing at all. Each has its own variable, OSC_HYPERLINKS_GMCP and OSC_HYPERLINKS_LOCAL, and Mudlet 5.1 and older show their text as plain text.
GMCP links. A click sends one GMCP message to the game. Nothing is typed, so the game echoes no command and sends no prompt in reply. Use it for actions whose result the game shows another way, such as setting a target or saving a preference.
- The link is
gmcp:, then the package and message name, then, if the message carries data, an encoded space and one JSON value:gmcp:Package.Message%20PERCENT_ENCODED_JSON. Percent-encode the whole message, as for asend:command. - The name is two or more parts separated by dots, such as
IRE.Target.Set. Each part is a letter followed by letters, digits or underscores, and the whole name is at most 128 characters. - Mudlet checks the message when the link arrives, and sends only what it checked. A link with an invalid name or JSON, or a control character anywhere in the message, is not a link, and its text shows as plain text.
- Mudlet never sends a message in the
CoreorChar.Loginpackages, in any letter case.Coreis the connection's own negotiation, andChar.Logincarries passwords. - With GMCP off, a click sends nothing and types nothing at the game.
OSC_HYPERLINKS_GMCPsays only that Mudlet understands the links, so send them only while GMCP is on as well. - The default tooltip names the message, such as Send GMCP: IRE.Target.Set "rat".
Local links. A local: link puts a tooltip, a style, a spoiler, a menu or a checklist on text when there is nothing for a click to send. Its configuration follows the ?, as in local:?config=..., and Mudlet ignores anything between local: and the ?.
- A spoiler reveals, a visibility action runs, and a selection toggles and shows its style, but sends no callback.
- With a menu, a click or Enter opens the menu instead of running its first item, and nothing is sent until the player chooses one. The default tooltip reads Click for menu.
- With no spoiler still hidden, no menu, no selection and no visibility action that a click hides, a click has nothing to do, and the link is a note. Tab skips it, the pointer stays a text cursor, and clicks and keys do what they would on any other text.
Examples
Target a creature with Iron Realms' own message:
ESC ] 8 ; ; gmcp:IRE.Target.Set%20%22rat%22 ESC \ a rat ESC ] 8 ; ; ESC \
A note on a word:
ESC ] 8 ; ; local:?config={"tooltip":"It needs a silver key"} ESC \ sealed door ESC ] 8 ; ; ESC \
A word with a menu and no action of its own: local:?config={"menu":[{"Look":"send:look sword"},{"Wield":"send:wield sword"}]}. Clicking the word opens the menu.
Percent Encoding
JSON configuration is passed as a URL parameter, so special characters must be percent-encoded per RFC 3986. Each becomes %XX, with XX its hex value, so a space in a command is %20.
| Character | Encoded | When to Encode |
|---|---|---|
| Space | %20 |
In commands: cast%20fireball
|
" |
%22 |
In JSON strings |
{ |
%7B |
JSON object start |
} |
%7D |
JSON object end |
: |
%3A |
JSON key-value separator |
, |
%2C |
JSON element separator |
? |
%3F |
In a send: or prompt: command, or a gmcp: message
|
& |
%26 |
In web URL query strings |
# |
%23 |
In web URL fragments |
Must be encoded, always:
&as%26and#as%23, anywhere inside aconfigvalue. These two are what separate one parameter from the next; leaving them raw corrupts the URL for Mudlet or for a stricter client.- Spaces in a bare command URI, such as
prompt:cast%20fireball. - A
?in asend:orprompt:command, as%3F. An unencoded?starts the link's parameters. - In a
Available in Mudlet5.2+gmcp:message's JSON,?,&,#,%and every character outside printable ASCII. Encoding the whole message takes care of them.
Recommended:
- Percent-encode the whole JSON object. It is what every URL-encoding helper produces by default, and it is the only form guaranteed to survive a strict client.
Tolerated by Mudlet:
- Raw, unencoded JSON in a
configvalue, as shown in the preset examples below. Mudlet finds the end of the object by counting braces. Do not rely on this if other clients will read your output.
Never encode:
- The URI scheme (
send:,https://). - The parameter structure itself (
?,=, and the&that separates parameters).
Example: a configuration, encoded
{"style": {"color": "red"}}
Percent-encoded:
%7B%22style%22%3A%7B%22color%22%3A%22red%22%7D%7D
The complete URI:
send:attack?config=%7B%22style%22%3A%7B%22color%22%3A%22red%22%7D%7D
Encoding tools: encodeURIComponent() in JavaScript, urllib.parse.quote(text, safe="") in Python, and socket.url.escape() or a function of your own in Lua.
JSON Configuration
Mudlet extends OSC 8 with JSON configuration for styling and behavior. A client that does not understand the configuration still sees a working link.
Add ?config= and the percent-encoded JSON to the URI:
SCHEME:COMMAND?config=PERCENT_ENCODED_JSON
{
"style": { }, // Visual appearance
"tooltip": "", // Hover text
"menu": [ ], // Right-click options
"title": "", // Menu header (string or {text, style})
"visibility": { }, // Auto-hide/reveal
"selection": { }, // Toggle state
"spoiler": false, // Hidden text
"disabled": false // Non-clickable
}
- Every member is optional, and Mudlet ignores a member it does not know. If the configuration is not valid JSON, Mudlet ignores all of it, and the link still works.
- A boolean may be
Available in Mudlet5.2+trueorfalse, the string"true","false","1"or"0"in any letter case, or the number1or0, for MUD drivers without a JSON boolean. Any other value is ignored, and the property keeps its default.
Style Properties
Control the appearance of hyperlink text: colors, weight, and decorations.
| Property | Type | Description | Example Values |
|---|---|---|---|
color |
String | Text foreground color | "red", "#ff0000", "rgb(255,0,0)"
|
bg |
String | Background color | "blue", "#000080"
|
bold |
Boolean | Bold weight | true, false
|
italic |
Boolean | Italic style | true, false
|
underline |
Boolean/String | Underline style | true, "wavy", "dotted", "dashed"
|
overline |
Boolean/String | Overline, always drawn solid | true, false
|
strikethrough |
Boolean/String | Strikethrough, always drawn solid | true, false
|
text-decoration-color |
String | Color for underline/overline/strikethrough | "red", "#ff0000"
|
- OSC 8 links are not underlined by default, unlike links on a web page. Add
"underline": trueto underline one.The one underline Mudlet adds itself is its focus cue, described under Accessibility.
Available in Mudlet5.2+ - A color is a CSS or X11 color name, such as
"dodgerblue", a hex value such as"#ff0000"or"#f00", orrgb()with numbers from 0 to 255 or percentages, such as"rgb(100%, 0%, 0%)".
Examples
Damage in bold red: {"style": {"color": "red", "bold": true}}
A button, white on green: {"style": {"color": "white", "bg": "#2e7d32", "bold": true}}
A quest keyword with a wavy gold underline: {"style": {"underline": "wavy", "text-decoration-color": "gold"}}
Variable: OSC_HYPERLINKS_STYLE_BASIC
Interactive States
Add visual feedback with pseudo-class states, similar to CSS hover effects in web browsers.
Put the base style at the top level of style, and an object for each state inside it, with the same properties. While a state applies, its properties override the base. When several states apply, the one with the highest priority is used.
A state changes only the properties it gives. The rest keep the base style's, or the text's own formatting where the base gives none, so a hover style that sets only a color keeps the bold your game sent. A state with no style leaves the link as it looks in the state below: a selected link with no hover style still looks selected under the pointer.
| State | Trigger | Priority | Use Case |
|---|---|---|---|
disabled |
Link is disabled | 1 (highest) | Unavailable options |
active |
Mouse button pressed | 2 | Click feedback |
hover |
Mouse cursor over link | 3 | Highlight on mouseover |
focus-visible |
Keyboard focus indicator | 4 | Accessibility |
focus |
Any focus (keyboard/mouse) | 5 | Focus ring |
selected |
Selection state active | 6 | Toggle indicators |
visited |
Link clicked previously | 7 | Show history |
link |
Unvisited link | 8 | Distinct unvisited style |
any-link |
Always applies | 9 (lowest) | Universal styling |
Note: The visited state resets when Mudlet restarts (session-scoped).
Examples
A link that lights up under the pointer: {"style": {"color": "#4aa3ff", "hover": {"color": "white", "underline": true}}}
A button that looks pressed while held: {"style": {"bg": "green", "color": "white", "hover": {"bg": "lightgreen"}, "active": {"bg": "darkgreen"}}}
Help topics that change color once read: {"style": {"link": {"color": "#4aa3ff"}, "visited": {"color": "#a070ff"}}}
A link underlined until it is read: {"style": {"underline": true, "visited": {"underline": false}}}
Variable: OSC_HYPERLINKS_STYLE_STATES
Tooltips
Show custom text when the player hovers a link.
tooltip replaces the default tooltip, which says what a click does:
| Link | Default tooltip |
|---|---|
send:look |
Send: look |
prompt:cast%20fireball |
Prompt: cast fireball |
gmcp:IRE.Target.Set%20%22rat%22 |
Send GMCP: IRE.Target.Set "rat" |
| A web address | Open browser to: and the address |
A mailto: address |
Write an email to: and the address |
A telnet: or telnets: address |
Connect to: and the address |
| A link with a menu | Right-click for menu |
A local: link with a menu |
Click for menu |
| A spoiler | Click to reveal |
Any other local: link |
None |
- A screen reader announces the tooltip first, so write one that says what a click does.
- Tooltips are rendered as plain text. HTML in a
Available in Mudlet5.0+tooltipvalue is displayed literally rather than interpreted. Emoji, including multi-part sequences such as 👨🍳 and 🏳️🌈, display normally.
Example: a word with a short explanation
On a send:help%20mana link:
{"tooltip": "Mana: the energy your spells use. Click for the help file."}
The player reads the short explanation on hover, and gets the help file with a click.
Variable: OSC_HYPERLINKS_TOOLTIP
Context Menus
Offer several actions from one link through a right-click menu, so a line does not need a separate link per action.
- Left-click, or Enter on a focused link, runs the first menu item. Right-click, the Menu key or Shift+F10 opens the menu. On a
Available in Mudlet5.2+local:link, a left click or Enter opens the menu as well. - Each item is an object with one member, its label and its URI, such as
{"Wield": "send:wield sword"}. The string"-"is a separator. - Once a link has a menu, Mudlet does not use the link's own URI. Make it the same action as the first menu item: a client that does not support menus runs the URI instead, so the link does the same thing in both.
- Without a tooltip, a link with a menu shows Right-click for menu, or Click for menu on a
local:link. - Menu labels and
Available in Mudlet5.0+titletext are rendered as plain text. Styling a title uses thestyleobject, not markup in the text.
| Property | Type | Description |
|---|---|---|
menu |
Array | The menu items, and "-" for each separator
|
title |
String/Object | text and a style with the style properties. It has no effect on a link without a menu.
|
Note: For Mudlet, title defaults to teal (#5fbdaf) when no style is specified.
What a menu item can do:
| Item | Choosing it | Version |
|---|---|---|
send: or prompt: |
Does what the same link would | |
| A web address | Opens it in the browser | |
A mailto: address |
Opens the mail app, as a mail link does | |
A telnet: or telnets: address |
Asks, then connects, as a game link does. An address Mudlet could not connect to is grayed out. | |
A gmcp: message |
Sends it, as a GMCP link does. A message that is not valid, or that Mudlet refuses, is grayed out. | |
A local: item |
Left out of the menu, since it has nothing to do | |
Anything else, such as flee |
Sent to the game exactly as written, without percent-decoding |
Older versions type new kinds of item at the game
Mudlet 5.0 and older send a web address in a menu to the game as a command, and Mudlet 5.1 and older do the same with mailto:, telnet: and gmcp: items. Put a gmcp: item in a menu only when Mudlet reports OSC_HYPERLINKS_GMCP, which no older version does. For the others, Mudlet reports its version in the NEW-ENVIRON variable CLIENT_VERSION, such as 5/2/0, so a server can offer these items only to the versions that open them. A mail or game link of its own is safe in any version, since an older Mudlet shows its text.
Example: actions on an item
{
"title": {"text": "a silver sword", "style": {"bold": true}},
"menu": [
{"Look": "send:look sword"},
{"Wield": "send:wield sword"},
"-",
{"Drop": "send:drop sword"}
]
}
On a send:look%20sword link, a click looks at the sword, and a right-click offers all three actions under the sword's name.
Variable: OSC_HYPERLINKS_MENU, which also covers title.
Visibility
Hide or reveal hyperlink text automatically, on a time delay or a trigger. Use it for temporary hints, dismissible prompts, and progressive disclosure.
"conceal": the link shows when printed. It hides at its firstexpireevent, or when the player clicks it: at once, or afterdelayif the link has one."reveal": the link is hidden when printed, and shows afterdelayor at its firstexpireevent, whichever comes first."reveal-then-conceal": the link is hidden when printed, shows as a"reveal"link does, and hides once clicked.- A hidden link's text is replaced with spaces, so the rest of the line keeps its place. With
wholeline, hiding removes the whole line instead.
| Property | Type | Description | Default |
|---|---|---|---|
action |
String/Array | Required. "conceal", "reveal", or "reveal-then-conceal", which can also be written ["reveal", "conceal"] |
None |
delay |
Number | Milliseconds before the action (1000 = 1 second) | None |
expire |
Object | Events that perform the action at once | None |
wholeline |
Boolean | Remove the whole line, not only the link. Use it with "conceal". |
false
|
Expire events:
| Property | Type | The event | Default |
|---|---|---|---|
input |
Boolean | The player sends a command from the main input line | false
|
prompt |
Boolean | The game ends a prompt with GA or EOR | false
|
output |
Boolean | Game text arrives after a quiet gap | false
|
outputDelay |
Number | Milliseconds of quiet that make a gap | 500
|
Note:
Expire events count from when the link is printed, with no click needed first. The first prompt after the link does not count, since it usually ends the output the link arrived in. A script's send(), and text a script prints, count as neither input nor output.
Examples
A hint that goes at the game's next prompt: {"visibility": {"action": "conceal", "expire": {"prompt": true}}}
A tip that goes when the player sends a command: {"visibility": {"action": "conceal", "expire": {"input": true}}}
A hint that appears after five seconds: {"visibility": {"action": "reveal", "delay": 5000}}
A notice that appears after three seconds and goes once clicked: {"visibility": {"action": "reveal-then-conceal", "delay": 3000}}
A line the player deletes by clicking its link: {"visibility": {"action": "conceal", "wholeline": true}}
Variable: OSC_HYPERLINKS_VISIBILITY
Spoilers
Hide text content until clicked, with automatic styling and tooltip generation. A simpler alternative to visibility-based concealment for hints, secrets, and puzzle answers.
- Until revealed, the text is hidden on a background a little lighter or darker than the window's, so the player can see that something is there, and the tooltip says Click to reveal.
- The first click, or Enter, reveals the text and clears that tooltip. After that, the link works as usual.
- With
"disabled": true, the link only reveals.
| Property | Type | Description | Default |
|---|---|---|---|
spoiler |
Boolean | Enable spoiler behavior | false
|
disabled |
Boolean | Prevent function execution after reveal | false
|
Mudlet makes the background from the window's background, by its luminance, Y = 0.2126×R + 0.7152×G + 0.0722×B:
| Luminance | Background Generation |
|---|---|
| < 0.1 (very dark) | Fixed rgb(40, 40, 40)
|
| < 0.5 (dark) | Console background, brightened by a factor of 1.4 |
| ≥ 0.5 (light) | Console background, darkened by a factor of 1.4 |
Examples
A riddle's answer, which only reveals: {"spoiler": true, "disabled": true}
A secret shown in yellow italics once revealed: {"spoiler": true, "style": {"color": "yellow", "italic": true}}
A hint with a menu once revealed: {"spoiler": true, "menu": [{"Show Again": "send:hint"}, {"Disable Hints": "send:hints off"}]}
| Feature | Spoilers | Visibility |
|---|---|---|
| Automatic background | Yes (color-matched) | No (manual styling) |
| Automatic tooltip | Yes ("Click to reveal") | No (manual config) |
| First-click behavior | Reveal only | Execute function |
| Best for | Hints, answers, secrets | Temporary UI elements |
Variable: OSC_HYPERLINKS_SPOILER
Disabled Links
Display links that cannot execute their function when clicked. Useful for locked content, unavailable options, or reveal-only spoilers.
- A click or Enter does nothing, and the menu does not open. A spoiler still reveals.
- Mudlet draws the link with its
disabledstate style. - The disabled style shows from when the link is printed, and stays while the link is hovered, pressed or focused. It keeps the text's own formatting, such as bold from the game, and a screen reader hears disabled.
Available in Mudlet5.2+ - A disabled link stays disabled. To enable it, the server must send a new link.
| Property | Type | Description | Default |
|---|---|---|---|
disabled |
Boolean | Prevent link function execution | false
|
Examples
A locked exit: {"disabled": true, "tooltip": "The trapdoor is locked", "style": {"disabled": {"color": "gray", "strikethrough": true}}}
A spell the player cannot cast yet: {"disabled": true, "tooltip": "Needs 40 more mana", "style": {"disabled": {"color": "gray"}}}
A reveal-only spoiler: {"spoiler": true, "disabled": true}
Variable: OSC_HYPERLINKS_DISABLED
Selection
Create toggleable links that keep state: radio buttons, checkboxes, reaction buttons, voting systems.
- Links belong to named groups. Clicking a link toggles its selected state, and its
selectedstate style shows the change at once. - In exclusive mode, the default, selecting one link clears the others in its group, as with radio buttons. With
"exclusive": false, each link toggles on its own, as with checkboxes. Give every link in a group the sameexclusivevalue. - Each window keeps its own selection state.
| Property | Type | Description | Default |
|---|---|---|---|
group |
String | Required. Group identifier for related links | None |
value |
String | Required. Unique identifier within group | None |
toggle |
Boolean | Allow deselecting by clicking again | true
|
selected |
Boolean | Initial selection state | false
|
exclusive |
Boolean | Radio (true) vs checkbox (false) mode | true
|
disabled |
Boolean | disabled |
false
|
The callback. When the player clicks a send: or prompt: link with a selection, Mudlet adds its new state to the command: selected=true or selected=false, after a ?, or after an & when the command already has a query.
A gmcp: link adds "selected": true or "selected": false to its JSON object, replacing any selected already there, and one with no JSON sends {"selected":true} or {"selected":false}. A gmcp: link with a selection is therefore not valid unless its JSON is an object, or absent. A local: link sends nothing, and keeps and styles its state in Mudlet only, as for a checklist the player ticks off.
Examples, with each configuration shown unencoded for readability
A combat stance, as radio buttons. With "toggle": false, clicking the chosen stance again leaves it chosen:
Link: send:stance%20defensive?config={"selection":{"group":"stance","value":"defensive","toggle":false}}
Selected: stance defensive?selected=true
A channel, as a checkbox that starts ticked:
Link: send:channel%20newbie?config={"selection":{"group":"channels","value":"newbie","exclusive":false,"selected":true}}
Cleared: channel newbie?selected=false
Ticked: channel newbie?selected=true
A command that already has a query: send:react%3Ftype=like calls back with react?type=like&selected=true.
A preference as a checkbox, over GMCP:
Link: gmcp:Game.Preference.Set {"preference":"combatHints"}?config={"selection":{"group":"prefs","value":"combatHints","exclusive":false}}
Checked: Game.Preference.Set {"preference":"combatHints","selected":true}
Cleared: Game.Preference.Set {"preference":"combatHints","selected":false}
A poll option that has run out: {"selection": {"group": "poll", "value": "fish", "disabled": true}, "style": {"disabled": {"strikethrough": true}}}
Note: A ? that is part of the command must be sent as %3F, as in send:react%3Ftype=like?config=.... An unencoded ? begins the link's parameters, and Mudlet keeps none of a send: or prompt: link's parameters in the command, so type=like would not reach the game. In the callback, characters such as spaces after the command's ? arrive percent-encoded, so decode that part as a query string.
Note:
A link that combines menu with selection receives no selected= callback. Its commands come from the menu items rather than the base URI, so there is no single payload to append the state to. Selection state is still tracked and styled. If you need the callback, put the selection on a link without a menu.
Variable: OSC_HYPERLINKS_SELECTION
Accessibility
Enable screen reader users and keyboard-only users to discover, navigate, and activate OSC 8 hyperlinks without a mouse.
- In caret mode, the player moves through the game's output with the keyboard. Tab and Shift+Tab move between links, wrapping around at the ends. Enter or Space activates the focused link, and the Menu key or Shift+F10 opens its menu.
- Caret mode stays on while a link's menu is open, so the player is back on the link when the menu closes.
Available in Mudlet5.2+ - The focused link shows its
Available in Mudlet5.2+focus-visiblestyle, or itsfocusstyle when that is all it has. A link with neither gets Mudlet's focus cue, a blue underline drawn over its usual look, which leaves its colors, bold and italics alone. - A screen reader announces the link's tooltip, then its state: visited, disabled, selected or has menu.
- After the tooltip, the screen reader says what the link is: link; button for a spoiler not yet revealed; radio button or checkbox, followed by checked or not checked in place of selected; or note. A player hears Target the goblin, link or Combat hints, checkbox, checked.
Available in Mudlet5.2+ - Tab skips a note, a
Available in Mudlet5.2+local:link with nothing for a click to do. The caret still reaches it with the arrow keys, and the screen reader then reads its tooltip.
Links work with the keyboard and screen readers with no extra configuration. A few authoring choices make them better:
- Write descriptive tooltips. The tooltip is the first thing a screen reader announces. Without one, the player hears the link's command, such as Send: look.
- Use meaningful selection group and value names. Group names are exposed to assistive technology, so
"combat_stance"is more useful than"g1". - Spoilers are keyboard-safe. The first Enter or Space reveals the text, and a second press activates the link.
- Give focus a style if the blue underline clashes with your colors. A
focus-visiblestyle takes its place, such as{"style": {"color": "#4aa3ff", "focus-visible": {"bg": "#4aa3ff", "color": "black"}}}.
Compact Syntax
Reduce JSON size by roughly 15-25% using single-letter property abbreviations, more when a config is mostly property names. Combine with presets for larger savings.
Mudlet reads both the full and the short names, and one configuration can mix them. Short names change nothing but the size.
| Full | Short | Full | Short | Full | Short |
|---|---|---|---|---|---|
| style | s | color | c | hover | h |
| menu | m | bg | bg | active | a |
| tooltip | t | bold | b | visited | vi |
| title | ti | italic | i | focus | f |
| visibility | v | underline | u | focus-visible | fv |
| selection | sel | overline | o | link | l |
| spoiler | sp | strikethrough | st | any-link | al |
| disabled | d | text-decoration-color | tdc | selected | sl |
The first pair of columns holds the top-level members, the second the style properties, and the third the states.
Note: sel is selection (the top-level object that defines group membership) and sl is selected (the pseudo-class that styles it). Mixing the two is the most common authoring mistake in compact syntax. Note also that d means disabled in both positions: at the top level it blocks interaction, inside style it selects the disabled appearance.
Example
Full names, 71 characters: {"style": {"color": "red", "bold": true, "hover": {"color": "yellow"}}}
Short names, 52 characters: {"s": {"c": "red", "b": true, "h": {"c": "yellow"}}}
Both at once: {"s": {"c": "red"}, "tooltip": "Full names work too"}
Short names pay off when a server sends many links, such as ten or more on a line, or builds them in code. Full names are easier to read and to debug.
Variable: OSC_HYPERLINKS_COMPACT
Presets
Define commonly-used styles once, then reference them by name.
A preset: sequence with empty text defines one. It registers the configuration and shows nothing:
ESC ] 8 ; ; preset:NAME?config=JSON ESC \ ESC ] 8 ; ; ESC \
A link uses it with ?preset=NAME, and can add a &config= of its own, which is deep-merged into the preset, with the link's values winning:
send:attack?preset=danger send:attack?preset=btn&config=%7B%22t%22%3A%22Attack%22%7D
| Preset | Override | Result |
|---|---|---|
{"s":{"c":"red","b":true}} |
{"s":{"c":"blue"}} |
{"s":{"c":"blue","b":true}}
|
{"s":{"c":"red"}} |
{"t":"Tooltip"} |
{"s":{"c":"red"},"t":"Tooltip"}
|
| Format | Example | Encoded Size | Reduction |
|---|---|---|---|
| Full JSON | ?config= + {"style":{"color":"red","bold":true}} |
77 chars | Baseline |
| Shorthand | ?config= + {"s":{"c":"red","b":true}} |
66 chars | 14% |
| Preset | ?preset=danger |
14 chars | 82% |
A preset costs its definition once, so it pays off after two or three uses.
Note:
Mudlet clears presets when the connection closes, and links already printed keep their style. Define presets again after every connect.
Example: one style for every exit
ESC ] 8 ; ; preset:exit?config={"s":{"c":"#4aa3ff","h":{"u":true}}} ESC \ ESC ] 8 ; ; ESC \
ESC ] 8 ; ; send:north?preset=exit ESC \ north ESC ] 8 ; ; ESC \
ESC ] 8 ; ; send:east?preset=exit ESC \ east ESC ] 8 ; ; ESC \
The game defines exit once after connecting. Each exit link then carries 12 characters of configuration instead of the whole style.
Variable: OSC_HYPERLINKS_PRESETS
Examples for Games
Each example combines features from the sections above, and needs the variable of each feature it uses. Configurations are shown unencoded for readability; percent-encode them when sending, as in Quick Start.
Exits to click
The room's exits, each with a tooltip that says where it leads. A locked door shows, but cannot be used.
Exits: north east down
send:north?config={"tooltip":"North to the Market Square"}
send:east?config={"tooltip":"East to the Temple of Light"}
send:down?config={"disabled":true,"tooltip":"The trapdoor is locked","style":{"disabled":{"color":"gray","strikethrough":true}}}
Actions on what is in the room
A creature or an item with a menu of what the player can do to it. A click runs the first action.
send:look%20goblin?config={"title":"a snarling goblin","menu":[{"Look":"send:look goblin"},{"Attack":"send:kill goblin"},"-",{"Consider":"send:consider goblin"}]}
Player names
A name in the who list or on a channel. A click starts a tell in the input line, and the menu offers more.
prompt:tell%20Aldric%20?config={"tooltip":"Aldric, a level 12 ranger","menu":[{"Tell":"prompt:tell Aldric "},{"Finger":"send:finger Aldric"},"-",{"Ignore":"send:ignore Aldric"}]}
A shop
A button that buys, one that fills the input line so the player can change the number, and one for an item the player cannot afford.
a coil of rope 10 gold [buy] [buy several] a steel longsword 300 gold [buy]
send:buy%20rope?config={"tooltip":"Buy a coil of rope for 10 gold"}
prompt:buy%205%20rope?config={"tooltip":"Change the number, then press Enter"}
send:buy%20longsword?config={"disabled":true,"tooltip":"You need 40 more gold","style":{"disabled":{"color":"gray"}}}
Choices that clear away
A quest's Accept and Decline, on a line of their own. Choosing one sends it and removes the line, so the player cannot choose twice.
send:accept?config={"visibility":{"action":"conceal","wholeline":true}}
send:decline?config={"visibility":{"action":"conceal","wholeline":true}}
Settings the player ticks
Channels as checkboxes. Each click sends the channel's command with its new state, for the game to read.
send:channel%20newbie?config={"selection":{"group":"channels","value":"newbie","exclusive":false,"selected":true},"style":{"selected":{"color":"#3c3","bold":true}}}
First click: channel newbie?selected=false
Second click: channel newbie?selected=true
Targets and preferences over GMCP
For a game whose interface already reads GMCP: a creature to target, and a preference the player ticks. Neither types a command, so the game echoes nothing.
gmcp:IRE.Target.Set%20%22goblin%22?config={"tooltip":"Target the goblin"}
gmcp:Game.Preference.Set%20%7B%22preference%22%3A%22combatHints%22%7D?config={"tooltip":"Combat hints","selection":{"group":"prefs","value":"combatHints","exclusive":false}}
Ticked: Game.Preference.Set {"preference":"combatHints","selected":true}
Notes and a checklist
A word that explains itself on hover, and the ingredients of a recipe the player crosses off. Nothing is sent.
local:?config={"tooltip":"It needs a silver key"}
local:?config={"selection":{"group":"stew","value":"barley","exclusive":false},"style":{"selected":{"strikethrough":true}}}
Notices that clear themselves
A mail notice that goes once read or when the player moves on, and a pager button that goes once used.
send:mail?config={"tooltip":"Read your mail","visibility":{"action":"conceal","wholeline":true,"expire":{"input":true}}}
send:?config={"tooltip":"Show the next page","visibility":{"action":"conceal"}}
The first removes its line when clicked, or when the player sends a command. The second sends an empty line, which the pager reads as "continue", and hides once clicked.
An answer behind a spoiler
A riddle's answer, hidden until the player asks for it. It only reveals, so nothing is sent.
send:answer?config={"spoiler":true,"disabled":true}
Help, and links outside the game
Help topics that change color once read, the game's wiki, an email to the staff, and the builders' port.
send:help%20combat?config={"style":{"link":{"color":"#4aa3ff"},"visited":{"color":"#a070ff"}}}
https://wiki.example.com/Combat
mailto:[email protected]?subject=Bug%20report
telnet://builders.example.com:4001
The last two need Mudlet 5.2. Keep them out of menus for older versions, as Context Menus explains.
Security & Limitations
Threat Model
Unlike a terminal emulator, where hyperlinks come from a program you chose to run, an OSC 8 sequence in Mudlet arrives from the game server, and often from another player, whose say, tell or channel text the server relays. Mudlet therefore treats every OSC 8 sequence as untrusted input.
Servers: strip ESC from player text
Server authors carry one obligation the client cannot discharge for them: strip the ESC character (0x1B) from player-supplied text before echoing it to other players. Otherwise one player can author links that another player sees, and every client-side protection below is defending your players from each other rather than from you.
Trusted URI Schemes
Mudlet makes links only for these schemes, and shows any other link's text as plain text:
send:,prompt:
Available in Mudlet5.2+gmcp:, which never sends aCoreorChar.Loginmessage, andlocal:, which does nothing outside Mudlethttp:,https:,ftp:, and
Available in Mudlet5.2+mailto:
Available in Mudlet5.2+telnet:,telnets:, which connect only once the player agreespreset:(for definitions only)
Only web and mailto: addresses reach the operating system's URL handler. Custom schemes and file: targets are rejected and cannot be used to launch a local application.
Limits
- URL length: Maximum 4096 characters
- Invalid JSON: Silently ignored (link still works without styling)
- Multi-line visibility: Only single-line links support visibility management
Display Sanitization
Invisible and direction-reordering characters are shown as a visible \u{202E} escape rather than being rendered, so link text cannot claim one destination while the link carries another. Two policies apply:
| Text | Policy |
|---|---|
| The command or URL shown in the default hint | Everything invisible is escaped |
tooltip, menu labels, title |
Same, except the zero-width joiner, zero-width non-joiner and tag characters |
The exceptions exist because those characters are load-bearing in text meant to be read. The zero-width joiner assembles multi-part emoji such as 👨🍳 and 🏳️🌈, tag characters assemble subdivision flags such as 🏴, and the zero-width non-joiner is required for correct Persian, Arabic and Indic shaping. Emoji in tooltips and menus work normally.
Tooltips, menu labels and title text are rendered as plain text; HTML in them is displayed literally.
Turning OSC 8 Off
Players can disable OSC 8 with Settings → General → Game protocols → Enable OSC 8 hyperlinks from the server (on by default). When off, Mudlet ignores OSC 8 sequences and reports 0 for every OSC_HYPERLINKS* variable, so a well-behaved server falls back to MXP or plain text.
Changing the setting mid-session sends an ad-hoc INFO (2) message covering every OSC_HYPERLINKS* variable the server previously requested, in one subnegotiation. Servers that track these capabilities should honor it without waiting for a reconnect:
IAC SB NEW-ENVIRON (39) INFO (2) USERVAR (3) OSC_HYPERLINKS VAL (1) 0 USERVAR (3) OSC_HYPERLINKS_SEND VAL (1) 0 [ .. ] IAC SE
Reserved Parameters
The parameter names config and preset are reserved for Mudlet's OSC 8 extensions, and Mudlet removes them from a web address before opening it:
| Parameter | Reserved When Client Advertises |
|---|---|
config |
Any of: OSC_HYPERLINKS_STYLE_BASIC, OSC_HYPERLINKS_STYLE_STATES, OSC_HYPERLINKS_TOOLTIP, OSC_HYPERLINKS_MENU, OSC_HYPERLINKS_VISIBILITY, OSC_HYPERLINKS_SPOILER, OSC_HYPERLINKS_DISABLED, OSC_HYPERLINKS_SELECTION, OSC_HYPERLINKS_COMPACT |
preset |
OSC_HYPERLINKS_PRESETS |
- A client that only advertises OSC_HYPERLINKS, OSC_HYPERLINKS_SEND and OSC_HYPERLINKS_PROMPT reserves neither, so no encoding is needed.
- A web address whose own query needs one of these names percent-encodes the name:
https://example.com/?%63%6F%6E%66%69%67=valueforconfig, and%70%72%65%73%65%74forpreset. Mudlet compares the raw, undecoded name, so the encoded one reaches the web page. RFC 3986 §6.2.2.2 would permit decoding the name before comparing it; Mudlet deliberately does not, and a client implementing this protocol must not either. - The encoded name is honored from Mudlet 5.0. Earlier versions decoded the whole query string before looking for reserved names, and took an encoded name as styling anyway, so a server that supports them avoids these names in web URLs entirely.
Available in Mudlet5.0+ - Inside a
configvalue on anhttp:,https:orftp:URL, send&as%26. Mudlet's style parser tolerates a raw&inside JSON, but the URL it opens keeps the rest of the JSON.send:,prompt:,gmcp:andlocal:links discard their whole query, so this does not affect them. - The Cryosphere-MUD/mudlet-url-munger C++ library percent-encodes reserved parameter names in a server's URLs before they are sent.
Implementation Guidance
For Game Servers
Add features in steps, each behind its variable:
- Links. With
OSC_HYPERLINKS, link to web addresses, and, for Mudlet 5.2, to mail addresses and other games. WithOSC_HYPERLINKS_SENDandOSC_HYPERLINKS_PROMPT, usesend:andprompt:. WithOSC_HYPERLINKS_GMCP, usegmcp:while GMCP is on, and withOSC_HYPERLINKS_LOCAL, uselocal:. WithoutOSC_HYPERLINKS, use MXP, ANSI or plain text. - Style. With
OSC_HYPERLINKS_STYLE_BASIC, add colors and decorations, using full property names. WithOSC_HYPERLINKS_STYLE_STATES, add hover, pressed and visited styles. - Interaction. With the variable for each, add tooltips, menus, visibility, spoilers, disabled links and selection.
- Size. With
OSC_HYPERLINKS_PRESETS, define presets after each connect and use?preset=. WithOSC_HYPERLINKS_COMPACT, use short names for links sent in bulk.
- Write a tooltip that says what a click does. It doubles as the screen reader announcement.
- Make a link's own URI the same action as its first menu item.
- Keep the text readable on its own. A client without links, or a player who has turned them off, sees only the text.
- Try each link in Mudlet with
feedTriggers(), as in Quick Start, before the game sends it.
- Strip ESC (0x1B) from anything a player typed before echoing it to another player.
- Do not put irreversible actions behind a bare
send:link. It fires on one left-click with no confirmation, by design. Use a confirmation step of your own. - Re-read capability variables on INFO. A player can turn OSC 8 off mid-session.
- Treat capabilities as a floor, not a promise. Always have a plain-text fallback.
For Client Developers
The standard specifies these extensions for any client: the escape sequence, each scheme and configuration member, capability negotiation, the order in which a click is handled, keyboard and screen reader support, and security rules drawn from defects found in shipped clients. Read its Security section before you implement them.
Quick Reference
{
"style": {
"color": "value",
"bg": "value",
"bold": true,
"italic": true,
"underline": true,
"overline": true,
"strikethrough": true,
"text-decoration-color": "value",
"hover": { /* same properties */ },
"active": { /* same properties */ },
"visited": { /* same properties */ },
"selected": { /* same properties */ },
"disabled": { /* same properties */ }
},
"tooltip": "Hover text",
"menu": [
{"Label": "scheme:command"},
"-",
{"Label2": "scheme:command2"}
],
"title": "Header text", // or {"text": "...", "style": {...}}
"visibility": {
"action": "conceal",
"delay": 5000,
"expire": {
"input": true,
"prompt": true,
"output": true,
"outputDelay": 500
},
"wholeline": false
},
"selection": {
"group": "group_name",
"value": "unique_value",
"toggle": true,
"selected": false,
"exclusive": true,
"disabled": false
},
"spoiler": false,
"disabled": false
}
See Also
- OSC 8 Hyperlinks: MUD Client Extensions - The standard for these extensions, for every client and server
- MXP Protocol - Alternative hyperlink protocol
References
- OSC 8 Specification - Egmont Koblinger
- ANSI Escape Codes - Wikipedia
- RFC 3986 - URI Generic Syntax
- CSS Text Decoration Level 3 - W3C
- RFC 1572 - Telnet Environment Option
MudMaster Chat Protocol (MMCP)
- MMCP is a peer-to-peer protocol enabling out of band data to be sent to connected peers in the form of public or private chats, or general data.
- See MMCP protocol documentation at: https://tintin.mudhalla.net/protocols/mmcp/
- And at: https://mudstandards.org/mud/mmcp/
- See also https://wiki.mudlet.org/w/Notes_on_MMCP
Note: MMCP arrived in Mudlet 4.21. Its 18 available functions are documented in Networking Functions and its four events in Event Engine. The seven below are written but their Lua registrations are still commented out, so no script can call them yet - see https://github.com/Mudlet/Mudlet/pull/7765
Lua functions
- Note for all functions using target as an argument, the argument can be the client chatname or ID of the client as seen in mmcp.displayClientList()
accept
- mmcp.accept(target)
- Accepts an incoming connection request.
- Parameters
- target:
- Incoming client name or ID.
Note: pending, not yet available in initial MMCP release.
deny
- mmcp.deny(target)
- Denies an incoming connection request.
- Parameters
- target:
- Client name or ID.
Note: pending, not yet available in initial MMCP release.
peek
- mmcp.peek(target)
- Sends a request to the target client to peek at their connection list.
- Parameters
- target:
- Client name or ID.
request
- mmcp.request(target)
- Sends a request to the target client to request and connect to their public connections.
- Mudlet will attempt to connect to each of the hosts returned by this command.
- Parameters
- target:
- Client name or ID.
setDoNotDisturb
- mmcp.setDoNotDisturb(target)
- Toggles the Do Not Disturb flag, any incoming connections will be automatically denied.
Note: pending, not yet available in initial MMCP release.
startServer
- mmcp.startServer([port])
- Starts accepting connections from clients.
- Parameters
- port:
- (optional) Port to listen for incoming connections. Default 4050.
Note: pending, not yet available in initial MMCP release.
stopServer
- mmcp.stopServer()
- Stops accepting connections from clients.
Note: pending, not yet available in initial MMCP release.