Mallard — Plugin API reference

mud

mud.alias(pattern: string, fn_: function, opts: table?)

Register an input alias that runs a callback when the user's typed line matches a pattern.

Registers an alias on the host: when an input line matches the regex pattern, the provided function is invoked with the captured match. An optional opts table refines registration.

Note: Patterns are regexes; bracket-string literals like [[^g (\w+)$]] are convenient for backslash-heavy patterns.

mud.alias("^note (.+)$", function(m)
  -- handle m
end)

source: mud.rs:655

mud.capture(n: number, opts: table?) -> LuaSpan

Create a span that captures a numbered regex group, optionally styled.

Builds a LuaSpan whose source is capture group n, applying any style options (fg, bg, bold, italic, etc.) from opts. The span's text is cleared so only the styling and the capture index are retained.

Returns LuaSpan — A LuaSpan bound to capture group n with the given style overlay.

Note: Only style fields from opts and the capture index matter; any text in opts is discarded.

local span = mud.capture(1, { fg = "cyan", bold = true })

source: span.rs:344

mud.command(name: string, fn_: function, opts: any)

Register a named command that runs a callback when invoked.

Registers a command with the given name on the host, invoking the supplied function when the command is run. The opts argument refines registration.

mud.command("greet", function()
  -- run command
end)

source: mud.rs:671

mud.command_prefix() -> string

Return the host's configured command prefix string.

Returns the current command prefix used by the host to recognize commands.

Returns string — The command prefix as a string.

local prefix = mud.command_prefix()

source: mud.rs:400

mud.delay(ms: number, fn_: function)

Schedule a callback to run once after a delay in milliseconds.

Registers a one-shot scheduled callback that fires once after ms milliseconds.

Note: Fires only once; use mud.every for a repeating timer.

mud.delay(2000, function()
  -- runs once after 2s
end)

source: mud.rs:820

mud.every(ms: number, fn_: function)

Schedule a callback to run repeatedly on a fixed interval in milliseconds.

Registers a repeating scheduled callback that fires every ms milliseconds.

Note: Repeats indefinitely; use mud.delay for a one-shot timer.

mud.every(10000, function()
  -- runs every 10s
end)

source: mud.rs:828

mud.execute(text: string, opts: table?) -> ()

Run a string through the input pipeline exactly as if the user had typed it.

Feeds text into the same input pipeline that handles typed input: alias expansion, slash-commands, and triggers all apply, and any resulting send goes out to the world. A recursion guard caps nesting depth (EXECUTE_DEPTH_CAP), so triggers or send observers that call mud.execute cannot loop back on themselves indefinitely. Returns nothing.

Note: A plain line that matches no alias, command, or trigger is sent with origin kind "execute" (distinct from a user's "typed" send and from mud.send's "plugin" send). Nesting past the depth cap raises a runtime error.

mud.trigger("^You are hungry\\.$", function()
  mud.execute("eat bread")
end)

source: mud.rs:114, mud.rs:609

mud.gag(pattern: string, opts: table?)

Registers a trigger that gags (hides) lines matching a pattern.

Registers a trigger on `pattern` whose action is to gag the matched line, suppressing it from output. If `opts` is omitted, an empty options table is used before registration.

Note: Delegates to the shared trigger registration path with a single Gag action.

mud.gag("^You feel hungry%.$")

source: mud.rs:793

mud.gag_substring(text: string, opts: table?)

Gags a specific substring of text rather than a whole line.

Registers a substring gag for the given `text`, removing matching text from output while leaving the rest of the line intact.

mud.gag_substring("(secret)")

source: mud.rs:807

mud.note(args: ...any) -> ()

Prints a local note line to the client, optionally styled.

Emits a client-side note that is not sent to the MUD. Supports a legacy single-string form, a string-plus-style-table form, and a span form built from one or more spans/strings/tables. Empty span input produces no output.

Note: The two-argument string+table form is parsed as a style table; a span-form call with no resolvable spans is a no-op.

mud.note("[demo] saw 'ping', replied 'pong'", { fg = "#88ccff" })

source: mud.rs:142

mud.on_send(args: ...any)

Register an observe-only callback that watches every outbound command as it is sent.

Registers a send observer that runs its callback for each outbound command, without altering or blocking it. Call it as mud.on_send(pattern, fn, opts?) to watch only sends matching a regex, or mud.on_send(fn, opts?) with no pattern to watch every send. The callback receives a match object m: capture groups are available as m[1], m[2], ...; m.origin is a table { kind, plugin_id? } describing where the send came from, and m.silent is a boolean telling you whether the send suppressed its local echo. Registered observers appear in the plugin rules browser and can be enabled, disabled, or removed through the returned handle.

Note: Observe-only: the callback cannot change or cancel the send. m.origin.kind is one of "typed", "alias", "command", "trigger", "keymap", "plugin", "execute", or "script". Unlike mud.trigger, the fires_remaining option has no effect on observers.

mud.on_send([[^(n|s|e|w|u|d)$]], function(m)
  mud.note("moved: " .. m[1] .. " (origin: " .. m.origin.kind .. ")")
end, { name = "movement-observer" })

source: mud.rs:663

mud.panel(panel_id: string) -> table

Get a handle to one of the plugin's declared panels.

Returns a handle for the panel with the given id, used to push messages to the panel's webview (:post) and to receive messages from it (:on_message). The panel id must be declared in the plugin manifest; calling :post or :on_message on an undeclared panel logs a warning and is ignored.

Returns table — a panel handle table with :post(name, data) and :on_message(name, fn).

Note: Posting to an undeclared panel returns false; a :post payload over 1 MB is dropped with a warning.

local p = mud.panel("vitals")
p:post("update", { hp = 42 })
p:on_message("click", function(data)
  mud.note("panel clicked")
end)

source: panel.rs:96

mud.play_sound(name: string, opts: table?) -> ()

Plays a named sound with optional volume and tag.

Plays the sound identified by `name`, which must be non-empty. Accepts an options table whose only honored keys in v1 are `volume` (integer 0-100) and `tag` (string); the remaining reserved keys are accepted but currently dropped.

Note: Raises an error on empty name, an out-of-range volume, a non-integer volume, a non-string tag, or any unknown option key.

mud.play_sound("alert", { volume = 80, tag = "combat" })

source: mud.rs:178

mud.replace(args: ...any)

Registers a trigger that replaces matched text with a template.

Registers a replacement trigger; requires at least a pattern and template, raising an error otherwise. A table of patterns as the first argument selects the chain form, where the second argument must be a table containing `with` (and optional `capture`) and an optional third trigger-options table; a single pattern uses the single-line replacement path.

Note: Fewer than two arguments raises an error. In the chain form the second argument must be a table and the optional trigger opts must be a table or absent.

mud.replace("go (%w+)", "go " .. "%1")

source: mud.rs:692

mud.request_restart() -> ()

Requests a restart of the plugin/client.

Signals a restart request through the settings callbacks. If the settings module has not been installed yet, the call is ignored and a warning is logged instead.

Note: Calling this before the settings module is installed logs a warning and does nothing.

mud.request_restart()

source: mud.rs:410

mud.send(text: string, opts: table?) -> ()

Sends text to the MUD, splitting on line boundaries.

Splits `text` into individual lines and sends each to the MUD. The optional options table accepts a single `silent` boolean that suppresses local echo; unknown keys are rejected.

Note: Multi-line text is split and each resulting line is sent separately.

mud.send("go " .. m[1])

source: mud.rs:56, mud.rs:545

mud.send_raw(bytes: string, opts: table?) -> ()

Sends raw bytes directly to the MUD connection.

Writes the given string's bytes to the host connection unmodified. An optional opts table accepts a single boolean key `silent`; when true the send is performed silently.

Note: Unknown keys in opts are rejected; `silent` defaults to false.

mud.send_raw("look\r\n")
mud.send_raw("password\r\n", { silent = true })

source: mud.rs:88, mud.rs:580

mud.sounds(_: ...args) -> table

Returns the list of available sound entries.

Re-reads the host sound list on each call (no caching) and returns an array table. Each element is a table with `name` (string) and `source`, which is either "bundled" or "user".

Returns table — An array table where each entry is { name = string, source = "bundled" | "user" }.

for _, s in ipairs(mud.sounds()) do
  print(s.name, s.source)
end

source: mud.rs:243

mud.span(text: string, opts: table?) -> LuaSpan

Builds a styled text span from text and optional style options.

Constructs a LuaSpan with source type Text from the given text and an optional opts table of styling. An `on_click` function in opts is rejected because click handlers require a plugin context.

Returns LuaSpan — A LuaSpan object with source Text.

Note: on_click handlers are not allowed here; only plugin-context spans support them.

local s = mud.span("hello", { fg = "red" })

source: span.rs:288, span.rs:314

mud.speak(text: string, opts: table?) -> ()

Speaks text aloud via the text-to-speech engine.

Queues `text` (which must be non-empty) as a spoken utterance through the host TTS engine. An optional opts table overrides the global speech settings per call. Overrides are merged over the effective `/global speak-*` settings, and the utterance is dropped entirely if text-to-speech is globally disabled.

Note: Raises an error on empty text, on a non-numeric `rate`/`pitch`/`volume`, or on any unknown option key. Utterances on the same `channel` queue in order; a run of identical same-channel text is coalesced. Omitted `voice`/`rate`/`pitch`/`volume` fall back to the corresponding `/global speak-*` setting.

mud.speak("You have been hit!", { channel = "combat", interrupt = true })

source: mud.rs:269

mud.stop_sounds(opts: table?) -> ()

Stops playing sounds, optionally filtered by tag.

Stops currently playing sounds via the host. An optional opts table accepts a `tag` string; when provided, only sounds matching that tag are stopped, otherwise all sounds stop.

Note: Omitting opts or `tag` stops all sounds.

mud.stop_sounds()
mud.stop_sounds({ tag = "ambient" })

source: mud.rs:222

mud.stop_speech(channel: string?) -> ()

Stops queued and active speech, optionally on one channel.

Stops speech through the host TTS engine. With a `channel` argument, only that lane is affected: its queued utterances are cleared and the active one on that lane is interrupted. With no argument, all queued speech is cleared and everything currently speaking is stopped.

Note: Omitting the channel stops everything; passing a channel that matches the label used in mud.speak stops just that lane.

mud.stop_speech()
mud.stop_speech("combat")

source: mud.rs:327

mud.style(pattern: any, opts: table, trigger_opts: table?)

Registers a restyle rule that reformats matching output.

Classifies the pattern as either a single pattern or a chain. A single pattern registers a restyle; a chain (multiple rows) registers a chain restyle that also accepts trigger_opts.

Note: trigger_opts is only consulted when the pattern is a chain.

mud.style("^You hit (.+)$", { fg = "green" })

source: mud.rs:679

mud.trigger(pattern: any, fn_: function, opts: table?)

Registers a trigger that runs a callback on matching output.

Classifies the pattern as a single pattern or a chain and registers the callback accordingly. The callback receives match information; for capture patterns it is passed the match object.

Note: Single vs. chain patterns are dispatched to different registration paths automatically.

local echo_handle = mud.trigger("^echo (.+)$", function(m)
  mud.send_raw(m[1] .. "\r\n")
end)

source: mud.rs:642

mud.viewport() -> table

Returns the current viewport dimensions.

Queries the host for the viewport size and returns a table with `cols` and `rows` fields.

Returns table — A table { cols = number, rows = number }.

local vp = mud.viewport()
print(vp.cols, vp.rows)

source: mud.rs:382

mud.voices(_: ...args) -> table

Returns the list of available TTS voices.

Queries the host text-to-speech engine and returns an array table of the installed voices. Each element is a table with `id`, `name`, and `language` string fields; the `id` is what you pass as the `voice` option to mud.speak or set via /global speak-voice.

Returns table — An array table where each entry is { id = string, name = string, language = string }.

for _, v in ipairs(mud.voices()) do
  print(v.id, v.name, v.language)
end

source: mud.rs:337

mud.keymap

mud.keymap.activate(name: string)

Pushes a named keymap layer onto the active stack, attributed to the calling plugin.

Applies an Activate operation for the given layer name on behalf of the current plugin, adding that keymap to the layer stack. Ownership is tracked by the plugin id so the host can attribute and manage the layer.

mud.keymap.activate("combat")

source: mud_keymap.rs:134

mud.keymap.clear()

Deactivates all keymap layers, emptying the stack.

Applies a DeactivateAll operation, removing every active keymap layer from the stack regardless of which plugin added it.

mud.keymap.clear()

source: mud_keymap.rs:172

mud.keymap.cycle(direction: string)

Deprecated no-op that only validates its direction argument.

Emits a deprecation note and has no effect in the multi-layer stack model. It accepts only the strings 'next' or 'prev'; any other value raises a runtime error.

Note: Deprecated and does nothing beyond argument validation. Passing anything other than 'next' or 'prev' raises a runtime error.

mud.keymap.cycle("next")

source: mud_keymap.rs:247

mud.keymap.deactivate(name: string)

Removes a named keymap layer from the stack, attributed to the calling plugin.

Applies a Deactivate operation for the given layer name on behalf of the current plugin, removing that keymap from the layer stack.

mud.keymap.deactivate("combat")

source: mud_keymap.rs:144

mud.keymap.deactivate_top()

Removes the topmost keymap layer from the stack.

Applies a DeactivateTop operation, popping the most recently activated keymap layer off the stack.

mud.keymap.deactivate_top()

source: mud_keymap.rs:163

mud.keymap.get_active()

Deprecated accessor returning the name of the top active keymap layer, if any.

Emits a deprecation note and returns the first name from the active layer list, or nil when no layers are active. Use mud.keymap.list_active()[1] instead.

Note: Deprecated; prefer mud.keymap.list_active()[1].

local top = mud.keymap.get_active()

source: mud_keymap.rs:235

mud.keymap.is_active(name: string)

Reports whether a named keymap layer is currently active.

Returns whether a layer with the given name exists anywhere in the active layer stack.

if mud.keymap.is_active("combat") then
  mud.keymap.deactivate("combat")
end

source: mud_keymap.rs:194

mud.keymap.list_active()

Returns the names of all currently active keymaps.

Queries the host for the list of active keymap names and returns them as a Lua array (1-indexed) of strings.

for _, name in ipairs(mud.keymap.list_active()) do
  mud.note(name)
end

source: mud_keymap.rs:181

mud.keymap.on_active_change(f: function)

Registers a callback fired when the set of active keymaps changes (deprecated).

Stores the given function in the Lua registry and appends it to the on_active_change callback list. Emits a deprecation note advising the use of mud.keymap.on_change instead.

Note: Deprecated; the host emits a note steering callers to mud.keymap.on_change.

mud.keymap.on_active_change(function()
  mud.note("keymaps changed")
end)

source: mud_keymap.rs:268

mud.keymap.on_change(f: function)

Registers a callback fired when keymaps change.

Stores the given function in the Lua registry and appends it to the on_change callback list so it is invoked on keymap changes.

mud.keymap.on_change(function()
  mud.note("active: " .. #mud.keymap.list_active())
end)

source: mud_keymap.rs:202

mud.keymap.set_active(name: any)

Activates a named keymap or deactivates all keymaps (deprecated).

Accepts a string name to activate that keymap, or nil to deactivate all keymaps; any other Lua type raises a runtime error. Emits a deprecation note pointing to mud.keymap.activate / mud.keymap.clear.

Note: Deprecated in favor of mud.keymap.activate / mud.keymap.clear. Passing anything other than a string or nil raises a runtime error.

mud.keymap.set_active("combat")
mud.keymap.set_active(nil)

source: mud_keymap.rs:214

mud.keymap.toggle(name: string)

Toggles a named keymap on or off, attributed to the calling plugin.

Applies a Toggle keymap operation for the given name as the current plugin, flipping that keymap's active state.

mud.keymap.toggle("combat")

source: mud_keymap.rs:154

mud.timer

mud.timer.after(ms: number, fn_: function)

Schedules a one-shot callback after a delay in milliseconds (deprecated).

Registers a non-repeating scheduled callback to run once after ms milliseconds. On first use it logs a one-time warning that this name is deprecated in favor of mud.delay.

Note: Deprecated; use mud.delay instead. A one-time warning is logged on first use and the old name will be removed in a future release.

mud.timer.after(1000, function()
  mud.note("one second later")
end)

source: mud.rs:845

mud.timer.every(ms: number, fn_: function)

Schedules a repeating callback every ms milliseconds (deprecated).

Registers a repeating scheduled callback that runs every ms milliseconds. On first use it logs a one-time warning that this name is deprecated in favor of mud.every.

Note: Deprecated; use mud.every instead. A one-time warning is logged on first use and the old name will be removed in a future release.

mud.timer.every(5000, function()
  mud.note("tick")
end)

source: mud.rs:866

vars

vars.delete(name: string) -> ()

Deletes a session variable.

Removes the variable named `name` from the host's variable store. No error is raised if it does not exist.

vars.delete("target")

source: vars.rs:43

vars.get(name: string) -> any

Read a persisted plugin variable by name.

Looks up the named variable in the host's variable store and returns its value as a string. Returns nil when the variable is not set.

Returns any — The stored value as a string, or nil if the variable does not exist.

Note: Values are always returned as strings; missing keys return nil, so guard with `or` and convert with tonumber as needed.

local count = tonumber(vars.get("demo_count") or "0") + 1

source: vars.rs:14

vars.set(name: string, value: any) -> ()

Set or delete a persisted plugin variable.

Stores the value under the given name in the host's variable store. Strings are stored verbatim; integers, numbers, and booleans ("true"/"false") are stringified before storage; other types fall back to Lua's tostring coercion. Passing nil deletes the variable.

Note: All values are coerced to strings; passing nil removes the variable rather than storing an empty value.

vars.set("demo_count", tostring(count))

source: vars.rs:23

vars.snapshot() -> table

Return all plugin variables as a table.

Builds and returns a fresh Lua table containing every key/value pair currently in the host's variable store.

Returns table — A table mapping each variable name to its stored value.

for name, value in pairs(vars.snapshot()) do log.info(name .. "=" .. value) end

source: vars.rs:50

storage

storage.byte_size() -> number

Returns the total byte size of the plugin's stored data.

Returns the number of bytes currently used by the calling plugin's storage.

Returns number — The total storage size in bytes as a number.

table.insert(lines, "  (total bytes: " .. tostring(storage.byte_size()) .. ")")

source: storage.rs:77

storage.delete(key: string) -> ()

Removes a key from the plugin's persistent storage.

Deletes the value stored under `key` for the current plugin and world. No error is raised if the key does not exist.

Note: Scoped to the current plugin and world; deleting an absent key is a no-op.

storage.delete("last_echo")

source: storage.rs:58

storage.get(key: string) -> any

Reads a value from the plugin's persistent storage.

Looks up `key` and, if present, parses the stored JSON string back into a Lua value. Returns nil when the key is absent.

Returns any — The decoded Lua value for the key, or nil if it is not set.

Note: Errors if the stored value is not valid JSON. Use `or` to supply a default since a missing key yields nil.

local n = (storage.get(k) or 0) + 1

source: storage.rs:37

storage.has(key: string) -> boolean

Reports whether a storage key exists.

Returns true if `key` is present in the current plugin and world's storage, false otherwise.

Returns boolean — Boolean indicating whether the key is set.

if storage.has("notes") then end

source: storage.rs:51

storage.keys() -> table

Lists all storage keys for the plugin.

Returns a sequence table of every key currently stored for this plugin and world, indexed from 1.

Returns table — An array-style table of key strings.

for _, k in ipairs(storage.keys()) do
  print(k)
end

source: storage.rs:66

storage.set(key: string, value: any) -> ()

Writes a value to the plugin's persistent storage.

Encodes `value` as JSON and stores it under `key`. Passing nil for `value` deletes the key instead.

Note: `value` of nil deletes the key as sugar. Errors if the value cannot be JSON-encoded or the underlying store rejects the write (e.g. size limits).

storage.set("last_echo", m[1])

source: storage.rs:21

settings

settings.get(key: string) -> any

Reads a declared setting value for the current plugin and world.

Returns the value of the named setting, converted from JSON to a Lua value. If the key is not declared in the plugin manifest, it logs a warning and returns nil.

Returns any — The setting value as a Lua value, or nil if the key is not declared.

Note: An undeclared key does not error; it logs a warning and yields nil.

local enabled = settings.get("auto_walk")
if enabled then
  print("auto walk on")
end

source: settings.rs:150

settings.on(event: string, f: function) -> ()

Registers a callback for settings change events.

Subscribes a callback to settings events. Only the "change" event is supported; any other event name raises an error.

Note: Passing any event other than "change" raises an error.

settings.on("change", function()
  print("settings changed")
end)

source: settings.rs:177

settings.snapshot() -> table

Returns a table of all current settings for the plugin and world.

Builds and returns a Lua table mapping each setting key to its current value, converted from JSON.

Returns table — A table mapping setting keys to their current values.

local s = settings.snapshot()
for k, v in pairs(s) do
  print(k, v)
end

source: settings.rs:164

events

events.emit(name: string, data: any) -> ()

Emit a named event with a JSON-encodable payload to the world.

Converts data to JSON and emits an event under the given name on the current world. Errors if the payload cannot be JSON-encoded.

Note: Raises an error if data cannot be encoded to JSON.

events.emit("net.mallard.showcase.echo", { text = m[1] })

source: events.rs:42

events.on(name: string, fn_: function) -> userdata

Subscribe a callback to a named event and return a handle.

Registers fn_ as a listener for events named name on the current world and returns a userdata handle that can be used to unsubscribe.

Returns userdata — A userdata event handle (supports :remove() to unsubscribe).

local h = events.on("net.mallard.showcase.echo", function(data)
  mud.note(data.text)
end)

source: events.rs:54

world

world.on(event: string, f: function) -> ()

Register a callback for a world event.

Registers the given function as a handler for the named world event. Valid events are "connect", "disconnect", and "line"; handlers are appended so multiple callbacks may be registered for the same event.

Note: Any event name other than "connect", "disconnect", or "line" raises an error ("unknown world event").

world.on("line", function(line)
  log.info("got: " .. line)
end)

source: world.rs:92

ui

ui.notify(title: string, body: string, opts: table?) -> ()

Shows a desktop notification with a title and body.

Displays a notification with the given `title` and `body`. The optional `opts.icon` selects the icon style; "warning" and "error" map to their respective icons and any other value (or omission) defaults to info.

Note: Requires the Notifications capability; raises an error if the plugin lacks that permission. Unrecognized icon values fall back to info.

ui.notify("Server error", line.text, { icon = "error" })

source: ui.rs:14

log

log.error(args: ...args) -> ()

Log a message at error level.

Stringifies the supplied arguments into a single message and writes it to the host log at error level.

log.error("failed to load config")

source: log.rs:13

log.info(args: ...args) -> ()

Log a message at info level.

Stringifies the supplied arguments into a single message and writes it to the host log at info level.

log.info("demo plugin loaded for world '" .. mud.world.name .. "'")

source: log.rs:13

log.warn(args: ...args) -> ()

Write a warning-level log message built from the given arguments.

Stringifies all passed arguments into a single message and emits it to the host log at the warn level. Accepts any number of arguments.

Note: The message is assembled by the host's argument stringifier; non-string values are converted automatically.

log.warn("unexpected state", value)

source: log.rs:13

keychain

keychain.delete(name: string) -> boolean

Delete a plugin's stored keychain credential by name.

Requires the Keychain permission. Deletes the OS keychain entry stored under a key namespaced to this plugin and also removes the key name from the plugin's keychain sidecar record. Returns whether an entry existed.

Returns boolean — boolean: true if a credential existed and was deleted, false if there was no entry.

Note: Requires Keychain permission; errors if the keychain backend is unavailable.

keychain.delete("api_token")

source: keychain.rs:71

keychain.get(name: string) -> string?

Retrieve a plugin's stored keychain credential by name.

Requires the Keychain permission. Reads the OS keychain entry stored under a key namespaced to this plugin and returns its value, or nil if no such entry exists.

Returns string? — string?: the stored value, or nil if no entry exists.

Note: Requires Keychain permission; errors if the keychain backend is unavailable.

local token = keychain.get("api_token")

source: keychain.rs:53

keychain.set(name: string, value: string) -> boolean

Store a plugin keychain credential under the given name.

Requires the Keychain permission and rejects values larger than the keychain byte limit. Writes the value to the OS keychain under a key namespaced to this plugin and records the key name in the plugin's sidecar so it can be swept on uninstall.

Returns boolean — boolean: always true on success.

Note: Requires Keychain permission; errors if the value is too large or the keychain backend is unavailable.

keychain.set("api_token", token)

source: keychain.rs:26

gmcp

gmcp.get(path: string) -> string?

Read the current GMCP value at a dotted path.

Returns the cached GMCP value stored at the given path, or nil if none is present. Requires GmcpAccess permission for path; a permission failure raises an error.

Returns string? — The stored string value at path, or nil if absent.

Note: Errors if the plugin lacks GmcpAccess permission for the path.

local v = gmcp.get("Char.Vitals.hp")
mud.note(tostring(v))

source: gmcp.rs:48

gmcp.on(prefix: string, fn_: function) -> userdata

Subscribe to GMCP packages matching a prefix and return a handle.

Registers fn_ for GMCP packages whose name starts with prefix and returns a userdata handle. The prefix must be non-empty and at most 256 characters; it is lowercased at registration so matching is case-insensitive, while the callback still receives the original-case package name. Requires GmcpAccess permission for the (lowercased) prefix.

Returns userdata — A userdata GMCP handle.

Note: Empty prefixes and prefixes over 256 chars raise an error; matching is case-insensitive due to lowercasing at registration.

gmcp.on("Char.Vitals", function(pkg, data)
  mud.note(data.hp)
end)

source: gmcp.rs:60

gmcp.send(pkg: string, data: any?) -> ()

Send a GMCP message for the given package to the connected world.

Validates that the package name is non-empty and that the plugin holds GmcpAccess permission for that package, then dispatches the message to the current world. When data is nil or omitted no payload is sent; otherwise the value is converted to JSON and sent as the payload.

Note: Errors if pkg is empty, if the plugin lacks GmcpAccess permission for pkg, or if the data fails JSON encoding.

gmcp.send("Char.Login", { name = "hero" })

source: gmcp.rs:98

mxp

mxp.get_entity(name: string) -> string?

Returns the current value of a named MXP entity, or nil if unset.

Looks up the MXP entity by name for the current world and returns its value. Returns nil when no entity with that name exists.

Returns string? — The entity's string value, or nil if the entity is not set.

local hp = mxp.get_entity("hp")
if hp then
  print("HP entity: " .. hp)
end

source: mxp.rs:141

mxp.on(tag: string, fn_: function) -> userdata

Registers a listener for a custom MXP tag, returning a handle.

Subscribes a callback to fire when the named custom MXP tag is received in the current world; the callback receives the tag name, attributes, and text. Returns a userdata handle that supports :remove() to unregister the listener.

Returns userdata — A userdata MXP handle supporting :remove() to unregister.

Note: Passing a built-in tag logs a warning and registers the listener anyway, but it will never fire.

local h = mxp.on("RoomName", function(name, attrs, text)
  print("room: " .. text)
end)

source: mxp.rs:81

mxp.on_entity(name: string, fn_: function) -> userdata

Registers a listener for changes to a named MXP entity, returning a handle.

Subscribes a callback to fire when the named MXP entity changes in the current world. The name is matched case-insensitively (lowercased internally). Returns a userdata handle supporting :remove() to unregister.

Returns userdata — A userdata entity handle supporting :remove() to unregister.

local h = mxp.on_entity("hp", function(value)
  print("hp changed: " .. tostring(value))
end)

source: mxp.rs:116

keymap

keymap.bind(combo_str: string, fn_: function) -> userdata

Bind a key combination to a Lua callback.

Registers the given callback to run when the parsed key combination is pressed, returning a userdata handle for the binding. Combination strings use modifier+key syntax such as "Ctrl+Shift+M", "F5", "Mod+Shift+G", or a bare key like "j".

Returns userdata — userdata: a handle representing the registered key binding.

Note: A combination consisting only of modifiers with no key is rejected as a parse error.

keymap.bind("Ctrl+Shift+M", function()
  mud.note("pressed")
end)

source: keymap.rs:154

EntityHandle object

handle:remove()

Unsubscribes an entity listener registered with mxp.on_entity().

Removes the entity subscription for this handle's world and listener, then drops the stored Lua callback so it can no longer fire. After calling this the registered callback is fully detached.

Note: Idempotent intent aside, the handle is meant to be removed once; the underlying callback id is dropped.

local echo_handle = mxp.on_entity("echo", function(e) end)
-- later, when no longer needed:
echo_handle:remove()

source: mxp.rs:54

EventHandle object

handle:remove()

Unsubscribes an entity listener registered with mxp.on_entity().

Removes the entity subscription for this handle's world and listener, then drops the stored Lua callback so it can no longer fire. After calling this the registered callback is fully detached.

Note: Idempotent intent aside, the handle is meant to be removed once; the underlying callback id is dropped.

local echo_handle = mxp.on_entity("echo", function(e) end)
-- later, when no longer needed:
echo_handle:remove()

source: events.rs:22

GmcpHandle object

handle:remove()

Unsubscribes an entity listener registered with mxp.on_entity().

Removes the entity subscription for this handle's world and listener, then drops the stored Lua callback so it can no longer fire. After calling this the registered callback is fully detached.

Note: Idempotent intent aside, the handle is meant to be removed once; the underlying callback id is dropped.

local echo_handle = mxp.on_entity("echo", function(e) end)
-- later, when no longer needed:
echo_handle:remove()

source: gmcp.rs:21

KeymapHandle object

handle:remove()

Unsubscribes an entity listener registered with mxp.on_entity().

Removes the entity subscription for this handle's world and listener, then drops the stored Lua callback so it can no longer fire. After calling this the registered callback is fully detached.

Note: Idempotent intent aside, the handle is meant to be removed once; the underlying callback id is dropped.

local echo_handle = mxp.on_entity("echo", function(e) end)
-- later, when no longer needed:
echo_handle:remove()

source: keymap.rs:128

LuaHandle object

handle:disable()

Disables the trigger, alias, scheduled task, or command behind this handle.

Marks the handle's enabled flag false and disables the underlying entity in the engine. Triggers, aliases, and commands are set disabled by id; for scheduled handles the timer is stopped by name if one exists.

Note: For scheduled (delay/every) handles, disabling stops the timer; re-enabling cannot re-arm it (see handle:enable).

local h = mud.trigger("^You are hungry$", function() end)
h:disable()

source: mud.rs:465

handle:enable()

Enables the trigger, alias, or command behind this handle.

Sets the handle's enabled flag true and re-enables the underlying trigger, alias, or command by id in the engine. Scheduled handles are a no-op here because the anonymous scheduled entry is not persisted.

Note: For scheduled work created by mud.delay/mud.every, enable() does nothing; you must call mud.delay/mud.every again to register a new scheduled entry.

local h = mud.alias("^hp$", function() end)
h:disable()
h:enable()

source: mud.rs:481

handle:remove()

Unsubscribes an entity listener registered with mxp.on_entity().

Removes the entity subscription for this handle's world and listener, then drops the stored Lua callback so it can no longer fire. After calling this the registered callback is fully detached.

Note: Idempotent intent aside, the handle is meant to be removed once; the underlying callback id is dropped.

local echo_handle = mxp.on_entity("echo", function(e) end)
-- later, when no longer needed:
echo_handle:remove()

source: mud.rs:500

LuaMatch object

m:capture(n: number, opts: table?)

Builds a span overlay that reuses the text of capture group n.

Constructs a styled span whose text is taken from capture group n, applying any style options from opts. The overlay's own text is cleared so the captured text is used as the content, and the result is returned as a span object for use with span-form effects.

local s = m:capture(1, { fg = "red" })
m:replace(1, s)

source: mud_match.rs:347

m:gag()

Suppresses the matched line from output.

Sets the match's gag effect so the line that triggered the callback is not displayed.

Note: Affects the whole line; there is no way to ungag once set within the callback.

trigger("^spam$", function(m)
  m:gag()
end)

source: mud_match.rs:220

m:note(args: ...any)

Appends a note line to the match's effects.

In legacy form, m:note(string) or m:note(string, opts_table) creates a plain span from the string and applies an optional style table to it. Otherwise the arguments are interpreted as spans (or a span list) and pushed as a note only if the resulting span list is non-empty.

Note: With one or two args where the first is a string, the second table is treated as a style; otherwise all args are parsed as spans. Empty span results are dropped.

m:note("connection established", { fg = "green" })

source: mud_match.rs:322

m:raw(key: any)

Looks up the raw (unstyled) text for a capture key.

Returns the raw captured string for the given key, or nil if no such raw value exists.

local who = m:raw(1)
if who then m:send("greet " .. who) end

source: mud_match.rs:213

m:replace(args: ...any)

Replaces a match target with a replacement string, function result, or spans.

Requires at least a target and a replacement. With a single string or function as the replacement it uses the legacy replace path; otherwise the remaining arguments are parsed as spans/captures. Errors if no arguments are given.

Note: Requires at least (target, replacement) or it errors. For chain matches, an integer target that resolves to an earlier (non-completing) row is silently dropped.

m:replace(1, m:capture(1, { fg = "yellow" }))

source: mud_match.rs:252

m:send(text: string, opts: table?)

Queues a command to be sent to the server.

Pushes a send request with the given text. The optional opts table accepts only a boolean silent key; any other key is rejected and a non-boolean silent value raises an error.

Note: Unknown option keys are rejected; silent must be a boolean if provided.

m:send("look", { silent = true })

source: mud_match.rs:298

m:style(spec: table)

Applies styling to captures of the match.

Accepts a spec table in single-capture form ({ capture = N, ... }) or multi-capture form ({ captures = {...}, ... }) and pushes the corresponding style effects. For chain matches, flat capture indices are translated to completing-row-local indices and targets on earlier rows are silently dropped.

Note: In chain matches a capture that belongs to an earlier row is silently ignored rather than styled.

m:style({ capture = 1, fg = "cyan", bold = true })

source: mud_match.rs:225

MxpHandle object

handle:remove()

Unsubscribes an entity listener registered with mxp.on_entity().

Removes the entity subscription for this handle's world and listener, then drops the stored Lua callback so it can no longer fire. After calling this the registered callback is fully detached.

Note: Idempotent intent aside, the handle is meant to be removed once; the underlying callback id is dropped.

local echo_handle = mxp.on_entity("echo", function(e) end)
-- later, when no longer needed:
echo_handle:remove()

source: mxp.rs:30

PanelHandle object

panel:on_message(arg2: string, arg3: function)

Register a callback for messages of a given name sent from the panel.

Subscribes a Lua function to messages named arg2 coming from this panel. If the panel id was not declared in the plugin manifest, a warning is logged and the listener is never registered.

Note: Silently does nothing (only a warning is logged) if the panel id is not declared in the manifest.

local panel = mud.panel("my.panel")
panel:on_message("send", function(data)
  mud.note(data.text)
end)

source: panel.rs:76

panel:post(arg2: string, arg3: any)

Send a named message with a JSON payload to the panel.

Serializes arg3 to JSON and dispatches it to this panel under the name arg2. Returns false (logging a warning) if the panel id is not declared in the manifest or if the serialized payload exceeds 1 MB; otherwise dispatches and returns true.

Returns boolean — true if the message was dispatched, false if the panel is undeclared or the payload exceeds 1 MB.

Note: Payloads larger than 1 MB when serialized are dropped and return false.

local panel = mud.panel("my.panel")
panel:post("connects", { n = get_or("connects", 0) })

source: panel.rs:49