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

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.

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
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
specialForceCompressionOff	Disables compression negotiation regardless of server offer	boolean	false	4.16
specialForceGAOff	Disables Go-Ahead (GA) signal negotiation	boolean	false	4.16
specialForceCharsetNegotiationOff	Disables charset negotiation during telnet negotiation	boolean	false	4.16
specialForceMXPNegotiationOff	Disables MXP negotiation during telnet negotiation	boolean	false	4.16
forceNewEnvironNegotiationOff	Disables NEW-ENVIRON telnet negotiation	boolean	false	4.19
versionInTerminalType	Include the version number in the terminal type	boolean	false	4.20
promptForVersionInTerminalType	Prompted once to include the version number in the terminal type	boolean	false	4.20
askTlsAvailable	Prompts the user about TLS availability when advertised by the server	boolean	true	4.18

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	100	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
inputLineStrictUnixEndings	Enforces use of Unix-style \n line endings in input	boolean	false	4.16

Display & Accessibility

Config Key	Description	Type	Default	Available Since
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
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
advertiseScreenReader	Advertise screen reader support to the server over GMCP	boolean	false	4.18
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

Mapper & Map UI Settings

Config Key	Description	Type	Default	Available Since
mapExitSize	The visual width of map exits in the mapper	number	3	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
mapShowRoomBorders	Enables display of room borders in the mapper	boolean	false	4.16
mapperPanelVisible	Whether the mapper panel is currently shown	boolean	true	4.16
show3dMapView	Whether the 3D map view is currently visible	boolean	false	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
showMapInfo	Adds the given contributor name to the mapper info panel	string	—	4.16
hideMapInfo	Removes the given contributor name from the mapper info panel	string	—	4.16

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

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

Common Usage Patterns

Script Initialization

-- Check and configure necessary protocols for your script
local requiredProtocols = {"enableGMCP", "enableMSDP"}
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"
})

Best Practices

1. Batch Operations: When setting multiple related options, use the table syntax to set them all at once.
2. User Notification: Consider notifying users when your script modifies their settings, especially for protocol-related changes.
3. Graceful Handling: Handle cases where setConfig() might fail (returns nil + error message).
4. Version Checking: Be aware of the "Available Since" version for each option to ensure compatibility.

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

Integration with Other Functions

These configuration functions work well with other Mudlet functions:

• enableMapInfo() / disableMapInfo() for mapper contributor panels
• getMudletVersion() for version-specific feature availability
• saveProfile() to persist configuration changes

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.