Configuration Options

Overview

The getConfig() and setConfig() functions provide a comprehensive interface for managing Mudlet's configuration options programmatically. These functions allow scripts and modules to read current settings and modify them as needed, enabling better integration and customization.

getConfig()

Syntax

getConfig([option])
getConfig("showSentText", enhanced) -- limited to use with "showSentText" for backward compatibility

Description

Returns configuration options similar to those that can be set with setConfig. One could use this to decide if a script should notify the user of suggested changes.

Parameters

• option (optional): Particular option to retrieve - see list below for available ones. This may be a string or an array of strings.
• enhanced (optional): When true, returns enhanced string values for supported options (e.g., "never"/"script"/"always" for showSentText). When false or omitted, returns legacy values for backward compatibility.

Returns

• Returns a table of all options when called without parameters
• Returns the value of a single option when called with a string parameter
• Returns a table of requested options when called with an array of strings
• They are only the configuration options, for example "enableGMCP" means that the "Enable GMCP" box is checked and does not mean that it has been negotiated with the server.

Example

-- Get all config options
local allOptions = getConfig()

-- Get a single option
local gmcpEnabled = getConfig("enableGMCP")

-- Get multiple options
local networkOptions = getConfig({"enableGMCP", "enableMSDP", "enableMSSP"})

-- Suggest enabling GMCP if it is unchecked
if not getConfig("enableGMCP") then
  echo("\nMy script works best with GMCP enabled. You may ")
  cechoLink("<red>click here", function() setConfig("enableGMCP",true) echo("GMCP enabled\n") end, "Enable GMCP", true)
  echo(" to enable it.\n")
end

Advanced getConfig() Usage

For certain configuration options that have been enhanced, getConfig() supports dual-mode access for backward compatibility:

-- Legacy mode (backward compatible) - returns boolean
local legacyValue = getConfig("showSentText")  -- true/false

-- Enhanced mode - returns string values  
local enhancedValue = getConfig("showSentText", true)  -- "never"/"script"/"always"

This dual-mode system ensures existing scripts continue to work while providing access to new functionality.

setConfig()

Syntax

setConfig(option, value)
setConfig({option1 = value1, option2 = value2, ...})

Description

Sets a Mudlet option to a certain value. This comes in handy for scripts that want to customise Mudlet settings to their preferences - for example, setting up mapper room and exit size to one that works for a certain map, or enabling MSDP for a certain game. For transparency reasons, the Debug window (when open) will show which options were modified by scripts.

To set many options at once, pass in a table of options.

Parameters

• option: Particular option to change - see list below for available ones
• value: Value to set - can be a boolean, number, or text depending on the option

Returns

• true if successful
• nil + error message if the option doesn't exist
• Setting mapper options requires the mapper being open first
• For enhanced options like showSentText, accepts both legacy boolean values and new string values with automatic conversion

Example

-- Set a single option
setConfig("mapRoomSize", 5)

-- Set multiple options at once
setConfig({
  mapRoomSize = 6, 
  mapExitSize = 12,
  enableGMCP = true
})

Available Configuration Options

Telnet Protocol Options

Config Key	Description	Type	Default	Available Since
askTlsAvailable	Prompts the user about TLS availability when advertised by the server	boolean	true	4.18
enableCHARSET	Enables CHARSET (character encoding negotiation) protocol support	boolean	true	4.20
enableGMCP	Enables GMCP (Generic Mud Communication Protocol) support	boolean	true	4.16
enableMNES	Enables MNES (Mud New-Environ Standard) protocol support	boolean	false	4.19
enableMSDP	Enables MSDP (Mud Server Data Protocol) support	boolean	false	4.16
enableMSP	Enables MSP (Mud Sound Protocol) support	boolean	true	4.16
enableMSSP	Enables MSSP (Mud Server Status Protocol) support	boolean	true	4.16
enableMTTS	Enables MTTS (Mud Terminal Type Standard) support	boolean	true	4.19
enableMXP	Enables MXP (Mud eXtension Protocol) support	boolean	true	4.20
enableNEWENVIRON	Enables NEW-ENVIRON (client environment variables) protocol support	boolean	true	4.20
forceNewEnvironNegotiationOff	Deprecated: Use enableNEWENVIRON instead. Disables NEW-ENVIRON telnet negotiation	boolean	false	4.19
promptForMXPProcessorOn	Whether the user has been prompted to enable MXP auto-detection	boolean	false	4.20
promptForVersionInTTYPE	Prompted once to include the version number in the terminal type	boolean	false	4.20
specialForceCharsetNegotiationOff	Deprecated: Use enableCHARSET instead. Disables charset negotiation during telnet negotiation	boolean	false	4.16
specialForceCompressionOff	Disables compression negotiation regardless of server offer	boolean	false	4.16
specialForceGAOff	Disables Go-Ahead (GA) signal negotiation	boolean	false	4.16
specialForceMXPProcessorOn	Forces MXP processor on regardless of negotiation (read-only, returns current forced state)	boolean	false	4.20
specialForceMxpNegotiationOff	Deprecated: Use enableMXP instead. Disables MXP negotiation during telnet negotiation	boolean	false	4.16
versionInTTYPE	Include the version number in the terminal type	boolean	false	4.20

Input & Command Line Settings

Config Key	Description	Type	Default	Available Since
autoClearInputLine	Automatically clears the input line after a command is sent	boolean	false	4.18
blankLinesBehaviour	Controls how blank lines are displayed: "show", "hide", or "replacewithspace"	string	"show"	4.17
caretShortcut	Defines a shortcut to move the input line caret: "none", "tab", "ctrltab", or "f6"	string	"none"	4.17
commandLineHistorySaveSize	The number of lines to retain in the input history	number	500	4.18
compactInputLine	Enables a compact visual style for the input line	boolean	false	4.17
controlCharacterHandling	Defines how control characters are displayed: "asis", "oem", or "picture"	string	"asis"	4.18
editorAutoComplete	Enables auto-completion in the script editor	boolean	true	4.20
inputLineStrictUnixEndings	Enforces use of Unix-style \n line endings in input	boolean	false	4.16

Display & Accessibility

Config Key	Description	Type	Default	Available Since
advertiseScreenReader	Advertise screen reader support to the server over GMCP	boolean	false	4.18
ambiguousEAsianWidthCharacters	Force [Ambiguous Width] characters to be drawn "narrow" or "wide", or do this "auto"-matically depending on the Game Server encoding setting	string	"auto"	4.20
announceIncomingText	Enables screen reader announcement for incoming text	boolean	false	4.18
enableBlinkText	Enables smooth pulsing animation for blinking text (SGR codes 5 and 6). When disabled, blinking text is shown in italics instead	boolean	false	4.21
enableClosedCaption	Enable on-screen captions for events and audio cues	boolean	false	4.20
f3SearchEnabled	Enables or disables the F3 search shortcut in command or output window	boolean	true	4.20
fixUnnecessaryLinebreaks	Applies linebreak fix for some servers (e.g., IRE)	boolean	false	4.16
showSentText	Controls when sent commands are displayed: "never" (never show), "script" (let scripts decide), or "always" (always show). Legacy boolean values are converted automatically.	string	"script"	4.20
showTabConnectionIndicators	Shows connection status indicators on profile tabs	boolean	true	4.20

Mapper & Map UI Settings

Config Key	Description	Type	Default	Available Since
hideMapInfo	Removes the given contributor name from the mapper info panel	string	—	4.16
mapExitSize	The visual width of map exits in the mapper	number	3	4.16
mapInfoColor	The background color of the mapper info box as an indexed list {r, g, b} or {r, g, b, a}	table	{150, 150, 150, 120}	4.20
mapperPanelVisible	Whether the mapper panel is currently shown	boolean	true	4.16
mapRoomSize	The size of rooms in the mapper	number	5	4.16
mapRoundRooms	Whether rooms are drawn as circles (true) or squares (false)	boolean	true	4.16
mapShowGrid	Toggles visibility of mapper grid	boolean	false	4.20
mapShowRoomBorders	Enables display of room borders in the mapper	boolean	false	4.16
show3dMapView	Whether the 3D map view is currently visible	boolean	false	4.16
showMapInfo	Adds the given contributor name to the mapper info panel	string	—	4.16
showRoomIdsOnMap	Whether room IDs are displayed in the mapper	boolean	false	4.16
showUpperLowerLevels	Show upper/lower level indicators in the map	boolean	true	4.20

Logging

Config Key	Description	Type	Default	Available Since
logDirectory	Path to the current profile's log directory	string	(profile-specific)	4.20
logInHTML	If true, logs are saved in HTML format	boolean	false	4.20

IRC Options

Config Key	Description	Type	Default	Available Since
ircHostName	IRC server hostname (default: "irc.libera.chat"	string	(profile-specific)	4.20
ircHostPort	IRC server port (default: 6667, use 6697 for SSL)	number	(profile-specific)	4.20
ircHostSecure	Whether to use SSL/TLS connection	boolean	(profile-specific)	4.20
ircChannels	Space-separated list of channels to join (e.g., "#mudlet #help")	string	(profile-specific)	4.20
ircNickName	Your IRC nickname	string	(profile-specific)	4.20
ircPassword	IRC server password (if required)	string	(profile-specific)	4.20

Enhanced Configuration Options

Some configuration options have been upgraded to provide more granular control while maintaining backward compatibility:

Config Key	Legacy Values	Enhanced Values	Description	Available Since
showSentText	true/false	"never"/"script"/"always"	Command echo behavior: never show commands, let scripts control via send(cmd, true/false), or always show commands	4.20

Common Usage Patterns

Script Initialization

-- Check and configure necessary protocols for your script
local requiredProtocols = {"enableGMCP", "enableCHARSET"}
for _, protocol in ipairs(requiredProtocols) do
  if not getConfig(protocol) then
    setConfig(protocol, true)
    cecho(f"<green>Enabled {protocol} for better script functionality.\n")
  end
end

Mapper Configuration

-- Configure mapper for better visibility
setConfig({
  mapRoomSize = 8,
  mapExitSize = 4,
  mapShowRoomBorders = true,
  showRoomIdsOnMap = true
})

Accessibility Setup

-- Configure for screen reader users
if getConfig("advertiseScreenReader") then
  setConfig({
    announceIncomingText = true,
    enableClosedCaption = true
  })
end

Input Line Customization

-- Configure input line behavior
setConfig({
  autoClearInputLine = true,
  compactInputLine = false,
  commandLineHistorySaveSize = 200,
  caretShortcut = "tab"
})

Enhanced Option Usage

-- Working with enhanced showSentText option
local currentMode = getConfig("showSentText", true)  -- Get string value
if currentMode == "never" then
  cecho("Commands will never be shown on screen\n")
elseif currentMode == "script" then
  cecho("Scripts control command visibility\n")
elseif currentMode == "always" then
  cecho("Commands will always be shown on screen\n")
end

-- Set using string values
setConfig("showSentText", "script")  -- Let scripts decide

-- Legacy boolean values still work
setConfig("showSentText", true)   -- Converts to "script"
setConfig("showSentText", false)  -- Converts to "never"

IRC

-- configure IRC to connect to Libera Chat with SSL
setConfig("ircHostName", "irc.libera.chat")
setConfig("ircHostPort", 6697)
setConfig("ircHostSecure", true)
setConfig("ircChannels", "#mudlet #mygamechannel")
setConfig("ircNickName", "CoolPlayer123")

-- read current IRC configuration
local hostname = getConfig("ircHostName")
local port = getConfig("ircHostPort")
local secure = getConfig("ircHostSecure")
local channels = getConfig("ircChannels")
local nickname = getConfig("ircNickName")

echo(string.format("IRC: %s@%s:%d (SSL: %s)\n", nickname, hostname, port, tostring(secure)))
echo("Channels: " .. channels .. "\n")

Error Handling

-- Safe configuration setting
local function safeSetConfig(option, value)
  local success, error = setConfig(option, value)
  if not success then
    cecho(f"<red>Failed to set {option}: {error}\n")
    return false
  end
  return true
end

-- Usage
if safeSetConfig("mapRoomSize", 10) then
  cecho("<green>Successfully updated map room size.\n")
end

Experimental Settings

These settings enable experimental features that are still in development. They may change, break, or be removed in future versions. Use with caution! 🧪

Config Key	Description	Type	Default	Available Since
experiment.3dmap.modernmapper	Toggles between the old (legacy) and new (modern) 3D mapper.	boolean	false	PTB
experiment.3d-player-icon	Displays a 3D player icon on the mapper	boolean	false	PTB
experiment.rendering.originalish	Activates the "originalish" rendering experiment. Part of a mutually exclusive group; enabling it will disable other rendering experiments.	boolean	true	PTB
experiment.rendering.more-transparent	Activates the "more-transparent" rendering experiment. Part of a mutually exclusive group; enabling it will disable other rendering experiments.	boolean	false	PTB
experiment.render-in-out-exits	Adds a dashed line between rooms connected by in/out exits. Adds a pair of triangles pointing into the middle of the room, or outwards to the exterior to indicate type of in/out exit.	boolean	false	PTB
experiment.osc8.visibility	Automatically hide or reveal hyperlink text based on time delays or user triggers. Perfect for temporary hints, dismissible prompts, or progressive disclosure interfaces.	boolean	false	PTB

A list of current experiments that your Mudlet supports can be found with getConfig("experiment.list").

Version Compatibility

Most configuration options are available from Mudlet 4.16+, with newer options added in subsequent versions. Always check the "Available Since" column to ensure compatibility with your target Mudlet version.

Migration Notes for v4.20+: The showSentText option was enhanced from a boolean to a tri-state system. Legacy profiles are automatically migrated: true becomes "script" (default), false becomes "never". Existing scripts using getConfig("showSentText") continue to receive boolean values for backward compatibility.