Area 51

From Mudlet
Jump to navigation Jump to search

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 Note: Please use the Area_51/Template to add new entries in the sections below.

Note 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 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()
Mudlet VersionAvailable in Mudlet5.0+
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()
Mudlet VersionAvailable in Mudlet5.0+
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()
Mudlet VersionAvailable in Mudlet5.0+
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().
Mudlet VersionAvailable in Mudlet ?.??+

Note 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()
Mudlet VersionAvailable in Mudlet ?.??+

Note 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>  
  • Selects music by file name, the same way stopMusic() does.
  • At least one of name, key or tag is required.
Maybe key <key>  
  • Selects the music with this key.
Maybe tag <tag>  
  • Selects music with this tag.
No volume 1 to 100 unchanged
  • The new volume. Above 100 is 100, and below 1 is 1.
No duration <msec> 0
  • How long the change takes, in milliseconds.
  • 0 makes the change at once; Mudlet still takes 20 milliseconds over it, so that the jump does not click.
  • 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

Mudlet VersionAvailable in Mudlet5.2+
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.

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

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

Only one custom login text has been defined initially:

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

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

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

sendCharacterName, PR #3952 open

sendCharacterName()

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

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

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

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

sendCharacterPassword, PR #3952 open

sendCharacterPassword()

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

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

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

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

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

sendCustomLoginText, PR #3952 open

sendCustomLoginText()

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

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

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

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

Only one custom login text has been defined initially:

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

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

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

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
Mudlet VersionAvailable in Mudlet5.0+
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 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 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 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.

Mudlet VersionAvailable in Mudlet4.20+

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 config parameter 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

OSC 8 Hyperlinks.png

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
Mudlet VersionAvailable in Mudlet4.20+
Mail and game links Open the mail app, or connect to another game after asking OSC_HYPERLINKS
Mudlet VersionAvailable in Mudlet5.2+
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
Mudlet VersionAvailable in Mudlet5.2+
Style Colors, weight and decorations OSC_HYPERLINKS_STYLE_BASIC
Mudlet VersionAvailable in Mudlet4.20+
Interactive states Hover, pressed and visited styles OSC_HYPERLINKS_STYLE_STATES
Mudlet VersionAvailable in Mudlet4.20+
Tooltips Text shown on hover OSC_HYPERLINKS_TOOLTIP
Mudlet VersionAvailable in Mudlet4.20+
Context menus Several actions on one link, under an optional title OSC_HYPERLINKS_MENU
Mudlet VersionAvailable in Mudlet4.20+
Visibility Hide or show a link on a timer or an event OSC_HYPERLINKS_VISIBILITY
Mudlet VersionAvailable in Mudlet4.21+
Spoilers Text hidden until clicked OSC_HYPERLINKS_SPOILER
Mudlet VersionAvailable in Mudlet4.21+
Disabled links Links shown but switched off OSC_HYPERLINKS_DISABLED
Mudlet VersionAvailable in Mudlet4.21+
Selection Radio buttons, checkboxes and toggles OSC_HYPERLINKS_SELECTION
Mudlet VersionAvailable in Mudlet4.21+
Accessibility Keyboard navigation and screen readers None needed
Mudlet VersionAvailable in Mudlet4.21+
Compact syntax Short property names OSC_HYPERLINKS_COMPACT
Mudlet VersionAvailable in Mudlet4.21+
Presets Configurations defined once and used by name OSC_HYPERLINKS_PRESETS
Mudlet VersionAvailable in Mudlet4.21+
Display sanitization Invisible characters shown, not rendered None needed
Mudlet VersionAvailable in Mudlet5.0+

Note Note:

Mudlet VersionAvailable in Mudlet5.0+

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

Mudlet VersionAvailable in Mudlet4.20+

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: and local: only in lower case.
  • Mudlet VersionAvailable in Mudlet5.1+
    A sequence that opens a link ends any link still open, even when Mudlet does not make the new one.

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:
Mudlet VersionAvailable in Mudlet5.2+
Sends one GMCP message to the game. See GMCP and Local Links
gmcp:IRE.Target.Set%20%22rat%22 OSC_HYPERLINKS_GMCP
local:
Mudlet VersionAvailable in Mudlet5.2+
Nothing outside Mudlet. See GMCP and Local Links
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:
Mudlet VersionAvailable in Mudlet5.2+
Opens the mail app. See Mail and Game Links
mailto:[email protected]?subject=Hello OSC_HYPERLINKS
telnet: / telnets:
Mudlet VersionAvailable in Mudlet5.2+
Asks the player, then connects to the game. See Mail and Game Links
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 Note:

Mudlet VersionAvailable in Mudlet5.2+

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 &amp;, takes the link's style and is hidden with its spoiler, while an MXP link inside a spoiler stays visible.

Mail and Game Links

Mudlet VersionAvailable in Mudlet5.2+

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, cc and bcc), subject and body. It drops every other field, since mail apps act on them: attach can 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 a telnets: 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 for telnets:. 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

Mudlet VersionAvailable in Mudlet5.2+

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 a send: 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 Core or Char.Login packages, in any letter case. Core is the connection's own negotiation, and Char.Login carries passwords.
  • With GMCP off, a click sends nothing and types nothing at the game. OSC_HYPERLINKS_GMCP says 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 %26 and # as %23, anywhere inside a config value. 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 a send: or prompt: command, as %3F. An unencoded ? starts the link's parameters.
  • Mudlet VersionAvailable in Mudlet5.2+
    In a 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 config value, 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.

Mudlet VersionAvailable in Mudlet4.20+

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.
  • Mudlet VersionAvailable in Mudlet5.2+
    A boolean may be true or false, the string "true", "false", "1" or "0" in any letter case, or the number 1 or 0, 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": true to underline one.
    Mudlet VersionAvailable in Mudlet5.2+
    The one underline Mudlet adds itself is its focus cue, described under Accessibility.
  • A color is a CSS or X11 color name, such as "dodgerblue", a hex value such as "#ff0000" or "#f00", or rgb() 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.

Mudlet VersionAvailable in Mudlet4.20+

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.

Mudlet VersionAvailable in Mudlet5.2+

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

Mudlet VersionAvailable in Mudlet4.20+

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"
Mudlet VersionAvailable in Mudlet5.2+
A web address Open browser to: and the address
A mailto: address Write an email to: and the address
Mudlet VersionAvailable in Mudlet5.2+
A telnet: or telnets: address Connect to: and the address
Mudlet VersionAvailable in Mudlet5.2+
A link with a menu Right-click for menu
A local: link with a menu Click for menu
Mudlet VersionAvailable in Mudlet5.2+
A spoiler Click to reveal
Any other local: link None
Mudlet VersionAvailable in Mudlet5.2+
  • A screen reader announces the tooltip first, so write one that says what a click does.
  • Mudlet VersionAvailable in Mudlet5.0+
    Tooltips are rendered as plain text. HTML in a tooltip value 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.

Mudlet VersionAvailable in Mudlet4.20+

  • Left-click, or Enter on a focused link, runs the first menu item. Right-click, the Menu key or Shift+F10 opens the menu.
    Mudlet VersionAvailable in Mudlet5.2+
    On a 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.
  • Mudlet VersionAvailable in Mudlet5.0+
    Menu labels and title text are rendered as plain text. Styling a title uses the style object, not markup in the text.
Property Type Description
menu Array The menu items, and "-" for each separator
title String/Object
Mudlet VersionAvailable in Mudlet4.21+
A heading above the items, which cannot be chosen: a string, or text and a style with the style properties. It has no effect on a link without a menu.

MenuTitle.png

Note 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
Mudlet VersionAvailable in Mudlet4.20+
A web address Opens it in the browser
Mudlet VersionAvailable in Mudlet5.1+
A mailto: address Opens the mail app, as a mail link does
Mudlet VersionAvailable in Mudlet5.2+
A telnet: or telnets: address Asks, then connects, as a game link does. An address Mudlet could not connect to is grayed out.
Mudlet VersionAvailable in Mudlet5.2+
A gmcp: message Sends it, as a GMCP link does. A message that is not valid, or that Mudlet refuses, is grayed out.
Mudlet VersionAvailable in Mudlet5.2+
A local: item Left out of the menu, since it has nothing to do
Mudlet VersionAvailable in Mudlet5.2+
Anything else, such as flee Sent to the game exactly as written, without percent-decoding
Mudlet VersionAvailable in Mudlet4.20+

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.

Screenshot 2025-10-17 at 7.48.38 AM.png

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.

Mudlet VersionAvailable in Mudlet4.21+

  • "conceal": the link shows when printed. It hides at its first expire event, or when the player clicks it: at once, or after delay if the link has one.
  • "reveal": the link is hidden when printed, and shows after delay or at its first expire event, 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 Note:

Mudlet VersionAvailable in Mudlet5.2+

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

Try "say !osc8-docs" to try this demo in Mudlet

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.

Mudlet VersionAvailable in Mudlet4.21+

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

Mudlet VersionAvailable in Mudlet4.21+
  • A click or Enter does nothing, and the menu does not open. A spoiler still reveals.
  • Mudlet draws the link with its disabled state style.
  • Mudlet VersionAvailable in Mudlet5.2+
    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.
  • 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.

Mudlet VersionAvailable in Mudlet4.21+

  • Links belong to named groups. Clicking a link toggles its selected state, and its selected state 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 same exclusive value.
  • 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
Mudlet VersionAvailable in Mudlet5.2+
The link cannot be selected or activated, as with the top-level 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.

Mudlet VersionAvailable in Mudlet5.2+

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

Mudlet VersionAvailable in Mudlet5.0+

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.

link management example

Variable: OSC_HYPERLINKS_SELECTION


Accessibility

Enable screen reader users and keyboard-only users to discover, navigate, and activate OSC 8 hyperlinks without a mouse.

Mudlet VersionAvailable in Mudlet4.21+
  • 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.
  • Mudlet VersionAvailable in Mudlet5.2+
    Caret mode stays on while a link's menu is open, so the player is back on the link when the menu closes.
  • Mudlet VersionAvailable in Mudlet5.2+
    The focused link shows its focus-visible style, or its focus style 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.
  • Mudlet VersionAvailable in Mudlet5.2+
    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.
  • Mudlet VersionAvailable in Mudlet5.2+
    Tab skips a note, a 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-visible style 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 VersionAvailable in Mudlet4.21+

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

Mudlet VersionAvailable in Mudlet4.21+

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

Mudlet VersionAvailable in Mudlet5.2+

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:
  • Mudlet VersionAvailable in Mudlet5.2+
    gmcp:, which never sends a Core or Char.Login message, and local:, which does nothing outside Mudlet
  • http:, https:, ftp:, and
    Mudlet VersionAvailable in Mudlet5.2+
    mailto:
  • Mudlet VersionAvailable in Mudlet5.2+
    telnet:, telnets:, which connect only once the player agrees
  • preset: (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

Mudlet VersionAvailable in Mudlet5.0+

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

Mudlet VersionAvailable in Mudlet5.0+

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=value for config, and %70%72%65%73%65%74 for preset. 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.
  • Mudlet VersionAvailable in Mudlet5.0+
    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.
  • Inside a config value on an http:, https: or ftp: 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: and local: 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:

  1. Links. With OSC_HYPERLINKS, link to web addresses, and, for Mudlet 5.2, to mail addresses and other games. With OSC_HYPERLINKS_SEND and OSC_HYPERLINKS_PROMPT, use send: and prompt:. With OSC_HYPERLINKS_GMCP, use gmcp: while GMCP is on, and with OSC_HYPERLINKS_LOCAL, use local:. Without OSC_HYPERLINKS, use MXP, ANSI or plain text.
  2. Style. With OSC_HYPERLINKS_STYLE_BASIC, add colors and decorations, using full property names. With OSC_HYPERLINKS_STYLE_STATES, add hover, pressed and visited styles.
  3. Interaction. With the variable for each, add tooltips, menus, visibility, spoilers, disabled links and selection.
  4. Size. With OSC_HYPERLINKS_PRESETS, define presets after each connect and use ?preset=. With OSC_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.
Server-side safety checklist
Mudlet VersionAvailable in Mudlet5.0+
  • 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

References

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 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 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 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 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 Note: pending, not yet available in initial MMCP release.


stopServer

mmcp.stopServer()
Stops accepting connections from clients.

Note Note: pending, not yet available in initial MMCP release.

Security

Standards