Guides

MUD Scripting with open-source tools

This guide outlines the architecture for a modular, event-driven scripting framework in Mudlet using Lua. By moving logic from individual trigger fields into a centralized package, developers can ensure script maintainability and easier debugging across different MUD environments.

3-5 hours5 steps
MUD Scripting with open-source tools hero illustration
1

Establish a Protected Namespace

Avoid polluting the global Lua environment by encapsulating all functions and variables within a single table. This prevents collisions with other installed plugins or Mudlet's internal functions.

init.lua
MyScript = MyScript or {}
MyScript.config = MyScript.config or {}
MyScript.state = MyScript.state or {}

function MyScript.echo(msg)
  cecho("<white>[<cyan>MyScript<white>] " .. msg .. "\n")
end

⚠ Common Pitfalls

  • •Declaring variables without 'local' inside functions will still leak to the global scope even if a namespace table exists.
  • •Overwriting existing Mudlet globals like 'send' or 'echo' by accident.
2

Implement an Event-Driven Architecture

Instead of hardcoding logic directly into trigger boxes, use Mudlet's event system. Create a central handler function that reacts to 'sysMessage' or custom GMCP events. This allows multiple scripts to react to the same data without interference.

events.lua
function MyScript.onVitalsUpdate(event, ...) 
  local data = gmcp.Char.Vitals
  MyScript.state.hp = tonumber(data.hp)
  MyScript.state.maxhp = tonumber(data.maxhp)
  
  if MyScript.state.hp < (MyScript.state.maxhp * 0.3) then
    MyScript.echo("Low Health Warning!")
  end
end

registerAnonymousEventHandler("gmcp.Char.Vitals", "MyScript.onVitalsUpdate")

⚠ Common Pitfalls

  • •Registering handlers multiple times on script re-save, leading to duplicate execution. Use a boolean check or unregister existing handlers first.
  • •Assuming GMCP data is always present; check for table existence before indexing.
3

Standardize Trigger Pattern Handling

Use Perl-compatible regular expressions (PCRE) in Mudlet triggers to capture data, but delegate the processing to a Lua function. This keeps the 'Trigger' item in the UI clean and the logic version-controllable.

triggers.lua
-- Trigger Pattern: ^You receive (\d+) gold sovereigns from (.*)\.$
-- Trigger Script:
MyScript.handleGoldGain(multimatches[1][2], multimatches[1][3])

function MyScript.handleGoldGain(amount, source)
  amount = tonumber(amount)
  MyScript.state.goldBalance = (MyScript.state.goldBalance or 0) + amount
  MyScript.echo(string.format("Gained %d gold from %s", amount, source))
end

⚠ Common Pitfalls

  • •Using index 1 for capture groups in multimatches; remember that multimatches[1][1] is the full match, [1][2] is the first capture.
  • •Neglecting to handle line breaks or color codes if the trigger isn't set to 'ignore colors'.
4

Create a Debugging and Logging Utility

MUD scripts often fail silently. Implement a debug toggle and a wrapper for pcall (protected call) to capture stack traces without crashing the entire script engine.

utils.lua
MyScript.debugMode = true

function MyScript.debug(msg)
  if MyScript.debugMode then
    cecho("<grey>[DEBUG] " .. msg .. "\n")
  end
end

function MyScript.safeCall(func, ...)
  local status, err = pcall(func, ...)
  if not status then
    MyScript.echo("<red>Error: " .. err)
    return nil
  end
  return true
end

⚠ Common Pitfalls

  • •Leaving debug mode on in production, which can cause significant lag during high-frequency combat spam.
5

Package for Distribution

Use Mudlet's 'mpackage' format to bundle scripts, triggers, aliases, and timers. Ensure the package includes an 'OnInstall' and 'OnUninstall' logic to clean up variables or UI elements.

installer.lua
function MyScript.install()
  MyScript.echo("Initializing MyScript package...")
  -- Setup default configs if they don't exist
end

registerAnonymousEventHandler("sysInstall", "MyScript.install")

⚠ Common Pitfalls

  • •Failing to clean up timers or UI labels on uninstall, leaving 'ghost' elements on the user's screen.
  • •Hardcoding file paths that only exist on your local machine.

What you built

Following a modular architecture ensures that your MUD scripts remain functional as the game's codebase evolves. By centralizing logic in Lua tables and leveraging Mudlet's event system, you create a professional-grade toolset that is easy to debug, share, and maintain.