mux package on StompyMUX Documentation

Attribute

Mon, 01 Jan 0001 00:00:00 +0000

An Attribute handle exposes the same safe native-attribute set as the Wizard-only @attribute command. It is distinct from dynamic State. Create a handle with Object:attribute.

Only descriptions and BattleTech-native attributes are exposed. Names are matched by the native attribute registry; unsupported names raise an error.

Methods

Method	Description
`Attribute:get`	Gets an attribute value.
`Attribute:set`	Sets or clears an attribute.
`Attribute:entries`	Returns every supported attribute.

Attribute:entries

Mon, 01 Jan 0001 00:00:00 +0000

Returns every supported native attribute and its current value.

Function

Synopsis

attributes:entries( )

Arguments

None.

Returns

table entries: A name-to-string table of all supported attributes.

Notes

Unset attributes are included with an empty-string value.

Attribute:get

Mon, 01 Jan 0001 00:00:00 +0000

Gets a supported native attribute.

Function

Synopsis

attributes:get( name )

Arguments

string name: A supported native attribute name.

Returns

string or nil value: The raw value, or nil when unset.

Notes

Unsupported names and invalid handles raise a Lua error.

Attribute:set

Mon, 01 Jan 0001 00:00:00 +0000

Sets or clears a supported native attribute.

Function

Synopsis

attributes:set( name, value )

Arguments

string name: A supported native attribute name.
string or nil value: The new raw value; nil clears the attribute.

Returns

Nothing.

Notes

Values must fit the native attribute buffer and cannot contain embedded NUL bytes. Unsupported names, invalid values, and failed native updates raise an error. This method is unavailable during @lua/check.

mux.connected_players

Mon, 01 Jan 0001 00:00:00 +0000

Lists player connections visible to the normal who command.

Function

Synopsis

mux.connected_players( )

Arguments

None.

Returns

table players: An array of connection records.

Examples

for _, player in ipairs(mux.connected_players()) do
 mux.notify(ctx.enactor, player.name)
end

Notes

Each record contains object (Object), name (string), connected_for (elapsed seconds), and idle_for (elapsed seconds). Hidden players and privileged connection details are omitted.

mux.flow_start

Mon, 01 Jan 0001 00:00:00 +0000

Attaches an interactive flow to a descriptor and shows its first prompt.

Function

Synopsis

mux.flow_start( descriptor, module, first_step )

Arguments

number descriptor: A live descriptor ID, normally ctx.descriptor.
string module: The flow module path, resolved like require.
string first_step: A key in the module’s flows table.

Returns

Nothing.

Examples

mux.flow_start(ctx.descriptor, "confirm_delete.lua", "confirm")

Notes

Raises an error if the descriptor does not exist, already has a flow, or the module lacks the requested step. This function is unavailable during @lua/check.

mux.is_printable_ascii

Mon, 01 Jan 0001 00:00:00 +0000

Tests whether every byte in a string is printable ASCII.

Function

Synopsis

mux.is_printable_ascii( value )

Arguments

string value: The byte string to inspect.

Returns

boolean printable: Whether every byte is between space (0x20) and ~ (0x7e), inclusive.

Examples

assert(mux.is_printable_ascii("Atlas-1"))
assert(not mux.is_printable_ascii("café"))

Notes

The empty string is valid. Control bytes, embedded NUL bytes, DEL, and non-ASCII UTF-8 characters return false.

mux.markup

Mon, 01 Jan 0001 00:00:00 +0000

Validates styled-text markup and returns it unchanged.

Function

Synopsis

mux.markup( value )

Arguments

string value: Styled-text markup to validate.

Returns

string markup: The validated input string.

Examples

local warning = mux.markup("[fg=#ff7000][bold]Warning[/][/]")
local look = mux.markup('[send="look"]Look[/]')

Notes

Invalid tags, colors, link targets, or nesting raise a Lua error. [send] and [prompt] targets are percent-encoded during rendering; [link] accepts http:, https:, and ftp: URIs.

mux.notify

Mon, 01 Jan 0001 00:00:00 +0000

Sends a message to an object.

Function

Synopsis

mux.notify( object, message )

Arguments

number or Object object: The recipient.
string message: Valid UTF-8 text without embedded NUL bytes.

Returns

Nothing.

Examples

mux.notify(ctx.enactor, "The counter advances.")

Notes

The recipient must be a live object. Output styling is adapted to each recipient’s negotiated terminal color depth. This function is unavailable during @lua/check.

mux.object

Mon, 01 Jan 0001 00:00:00 +0000

Creates a validated handle for a native database object.

Function

Synopsis

mux.object( dbref )

Arguments

number or Object dbref: A live database reference or an existing object handle.

Returns

Object object: A handle for the referenced object.

Examples

local object = mux.object(ctx.object)
mux.notify(ctx.enactor, object.name)

Notes

This function is unavailable during @lua/check. Passing an invalid object raises a Lua error.

mux.strip_style

Mon, 01 Jan 0001 00:00:00 +0000

Removes styled-text markup and ANSI styling from a string.

Function

Synopsis

mux.strip_style( value )

Arguments

string value: Styled or unstyled text.

Returns

string plain: The visible unstyled text.

Examples

local command = mux.strip_style(styled_name)

Notes

This is useful before using player-facing text as a command or identifier.

mux.style

Mon, 01 Jan 0001 00:00:00 +0000

Applies styled-text markup described by an options table.

Function

Synopsis

mux.style( value, options )

Arguments

string value: The text to style; it must not contain an embedded NUL byte.
table options: Style fields to apply.

Returns

string styled: The input wrapped in validated styled-text markup.

Examples

local heading = mux.style("Warning", {
 foreground = "#ff7000",
 bold = true,
})

Notes

options.foreground and options.background accept a built-in or configured color name or #RRGGBB. bold, underline, and inverse are booleans. Missing fields have no effect; invalid types and colors raise an error.

mux.telnet_environment_get

Mon, 01 Jan 0001 00:00:00 +0000

Gets an RFC 1572 NEW-ENVIRON variable from a live connection.

Function

Synopsis

mux.telnet_environment_get( descriptor, kind, name )

Arguments

number descriptor: A live descriptor ID, normally ctx.descriptor.
string kind: Either "var" or "uservar".
string name: The binary-safe variable name.

Returns

string or nil value: The binary-safe value, or nil when the variable is absent.

Examples

if mux.telnet_environment_has(ctx.descriptor, "var", "USER") then
 local user = mux.telnet_environment_get(ctx.descriptor, "var", "USER")
end

Notes

A defined empty value returns "". The two kinds are distinct namespaces and all received data is untrusted. An invalid descriptor or kind raises an error; this function is unavailable during @lua/check.

mux.telnet_environment_has

Mon, 01 Jan 0001 00:00:00 +0000

Tests whether an RFC 1572 NEW-ENVIRON variable is defined on a live connection.

Function

Synopsis

mux.telnet_environment_has( descriptor, kind, name )

Arguments

number descriptor: A live descriptor ID, normally ctx.descriptor.
string kind: Either "var" or "uservar".
string name: The binary-safe variable name.

Returns

boolean defined: Whether the variable is present, including with an empty value.

Notes

The two kinds are distinct namespaces. Client-provided names and values are untrusted input. An invalid descriptor or kind raises an error; this function is unavailable during @lua/check.

mux.text_width

Mon, 01 Jan 0001 00:00:00 +0000

Measures the visible byte width of styled text.

Function

Synopsis

mux.text_width( value )

Arguments

string value: Styled or unstyled text.

Returns

number width: The number of visible bytes, excluding markup and ANSI styling.

Notes

The result is a byte width, not a Unicode display-cell calculation.

mux.truncate_text

Mon, 01 Jan 0001 00:00:00 +0000

Truncates styled text to a maximum visible width.

Function

Synopsis

mux.truncate_text( value, width )

Arguments

string value: Styled or unstyled text.
number width: A non-negative maximum visible byte width.

Returns

string truncated: The safely truncated text, including any resets needed for active styles.

Examples

local label = mux.truncate_text(mux.style("Atlas", { bold = true }), 3)

Notes

A negative width raises a Lua error. Markup and ANSI sequences do not count toward the limit.

mux.who_summary

Mon, 01 Jan 0001 00:00:00 +0000

Returns the non-privileged WHO summary.

Function

Synopsis

mux.who_summary( )

Arguments

None.

Returns

table summary: A table with hidden, record, and maximum fields.

Examples

local summary = mux.who_summary()
local maximum = summary.maximum or "no"

Notes

hidden and record are numbers. maximum is a number or nil when the game has no player limit.

Object

Mon, 01 Jan 0001 00:00:00 +0000

An Object is a validated handle for a native database object. Create one with mux.object. Handles become invalid if their object is destroyed or its database slot is reused. Two handles for the same live object compare equal, and tostring(object) produces a value such as object(#123).

Properties

All properties are read-only.

Property	Type	Description
`dbref`	number	The native database reference.
`name`	string	The object’s current name.
`type`	string	`room`, `thing`, `exit`, or `player`.
`description`	string or nil	The native description, if set.
`inside_description`	string or nil	The native inside description, if set.

Methods

Method	Description
`Object:contents`	Lists directly contained objects.
`Object:contents_visible`	Applies native content visibility rules.
`Object:exits`	Lists directly attached exits.
`Object:exits_visible`	Applies native exit visibility rules.
`Object:enter_lock_passes`	Tests an exit’s traversal lock.
`Object:attribute`	Opens the native attribute interface.
`Object:state`	Opens a persistent state namespace.

Object:attribute

Mon, 01 Jan 0001 00:00:00 +0000

Creates an attribute handle for this object.

Function

Synopsis

object:attribute( )

Arguments

None.

Returns

Attribute attributes: A handle for the object’s supported native attributes.

Examples

local attributes = mux.object(ctx.object):attribute()
attributes:set("Mechname", "H-7")
local name = attributes:get("Mechname")

Notes

This method is unavailable during @lua/check.

Object:contents

Mon, 01 Jan 0001 00:00:00 +0000

Returns the objects directly contained by this object.

Function

Synopsis

object:contents( )

Arguments

None.

Returns

table contents: An array of Object handles in native database order.

Notes

The receiver must be able to contain objects. Results are unfiltered; use Object:contents_visible to apply native look visibility rules. This method is unavailable during @lua/check.

Object:contents_visible

Mon, 01 Jan 0001 00:00:00 +0000

Tests whether a directly contained object is visible to a viewer.

Function

Synopsis

object:contents_visible( viewer, member )

Arguments

number or Object viewer: The object viewing the container.
number or Object member: An object directly contained by the receiver.

Returns

boolean visible: Whether native look rules expose the member.

Examples

for _, member in ipairs(room:contents()) do
 if room:contents_visible(ctx.enactor, member) then
 mux.notify(ctx.enactor, member.name)
 end
end

Notes

The receiver must be able to contain objects, and member must be directly contained by it. This method is unavailable during @lua/check.

Object:enter_lock_passes

Mon, 01 Jan 0001 00:00:00 +0000

Tests whether an enactor passes this exit’s default traversal lock.

Function

Synopsis

exit:enter_lock_passes( enactor )

Arguments

number or Object enactor: The object attempting traversal.

Returns

boolean passes: Whether the lock passes.

Notes

The receiver must be an exit. The check sends no lock messages and does not move the enactor. This method is unavailable during @lua/check.

Object:exits

Mon, 01 Jan 0001 00:00:00 +0000

Returns the exits directly attached to this object.

Function

Synopsis

object:exits( )

Arguments

None.

Returns

table exits: An array of Object handles in native database order.

Notes

The receiver must be able to have exits. Results are unfiltered; use Object:exits_visible to apply native look visibility rules. This method is unavailable during @lua/check.

Object:exits_visible

Mon, 01 Jan 0001 00:00:00 +0000

Tests whether a directly attached exit is visible to a viewer.

Function

Synopsis

object:exits_visible( viewer, exit )

Arguments

number or Object viewer: The object viewing the location.
number or Object exit: An exit directly attached to the receiver.

Returns

boolean visible: Whether native exit-display rules expose the exit.

Notes

The receiver must be able to have exits. exit must be an exit attached directly to it. This method is unavailable during @lua/check.

Object:state

Mon, 01 Jan 0001 00:00:00 +0000

Creates a persistent-state handle for one namespace on this object.

Function

Synopsis

object:state( namespace )

Arguments

string namespace: A valid, exact, case-sensitive state namespace.

Returns

State state: A handle for the namespace.

Examples

local state = mux.object(ctx.object):state("counter")
local count = state:get("count", 0) + 1
state:set("count", count)

Notes

The namespace must begin with an ASCII letter and may contain letters, digits, _, -, ., and /. This method is unavailable during @lua/check.

State

Mon, 01 Jan 0001 00:00:00 +0000

A State handle accesses persistent values belonging to one named subsystem on one object. Create a handle with Object:state.

Namespaces and keys are exact and case-sensitive. They begin with an ASCII letter and may contain letters, digits, _, -, ., and /; keys are at most 255 bytes. Values retain their Lua scalar type across reloads and restarts. Supported values are strings, booleans, integers, and finite numbers. Empty strings are values; nil deletes a value.

State:delete

Mon, 01 Jan 0001 00:00:00 +0000

Deletes a persistent state value.

Function

Synopsis

state:delete( key )

Arguments

string key: A valid state key.

Returns

boolean existed: Whether the key existed before deletion.

Notes

The deletion belongs to the current callback transaction.

State:entries

Mon, 01 Jan 0001 00:00:00 +0000

Lists the entries in this state namespace.

Function

Synopsis

state:entries( )

Arguments

None.

Returns

table entries: An array of { key = ..., value = ... } records sorted by key.

Notes

Enumeration requires an active callback transaction and includes earlier writes from that transaction.

State:get

Mon, 01 Jan 0001 00:00:00 +0000

Gets a persistent state value.

Function

Synopsis

state:get( key [, default] )

Arguments

string key: A valid state key.
any default: Optional value returned when the key is absent.

Returns

string, boolean, number, or any value: The stored value, the supplied default, or nil.

Notes

Reads observe writes made earlier in the current callback transaction.

State:get_many

Mon, 01 Jan 0001 00:00:00 +0000

Gets every present value from a requested set of keys.

Function

Synopsis

state:get_many( keys )

Arguments

table keys: An array of valid state-key strings.

Returns

table values: A key-to-value table containing only keys that are present.

Notes

Duplicate requested keys do not change the result. Reads observe earlier writes from the current callback transaction.

State:has

Mon, 01 Jan 0001 00:00:00 +0000

Tests whether a persistent state key exists.

Function

Synopsis

state:has( key )

Arguments

string key: A valid state key.

Returns

boolean exists: Whether the key has a value.

Notes

An empty string is a present value. Reads observe writes made earlier in the current callback transaction.

State:keys

Mon, 01 Jan 0001 00:00:00 +0000

Lists the keys in this state namespace.

Function

Synopsis

state:keys( )

Arguments

None.

Returns

table keys: An array of strings sorted by key.

Notes

Enumeration requires an active callback transaction.

State:set

Mon, 01 Jan 0001 00:00:00 +0000

Sets or deletes a persistent state value.

Function

Synopsis

state:set( key, value )

Arguments

string key: A valid state key.
string, boolean, finite number, or nil value: The new value; nil deletes the key.

Returns

Nothing.

Notes

The update belongs to the current callback transaction. Invalid types, non-finite numbers, and configured storage-limit violations raise an error.

State:set_many

Mon, 01 Jan 0001 00:00:00 +0000

Applies several persistent state updates.

Function

Synopsis

state:set_many( values )

Arguments

table values: A string-keyed table of supported state values.

Returns

Nothing.

Notes

All updates join the current callback transaction. Every key must be a valid string and every value must be a string, boolean, or finite number. Lua tables cannot carry a nil entry, so use State:set or State:delete to remove keys.

mux package on StompyMUX Documentation

Attribute

Methods

See Also

Attribute:entries

Function

Synopsis

Arguments

Returns

Notes

See Also

Attribute:get

Function

Synopsis

Arguments

Returns

Notes

See Also

Attribute:set

Function

Synopsis

Arguments

Returns

Notes

See Also

mux.connected_players

Function

Synopsis

Arguments

Returns

Examples

Notes

See Also

mux.flow_start

Function

Synopsis

Arguments

Returns

Examples

Notes

mux.is_printable_ascii

Function

Synopsis

Arguments

Returns

Examples

Notes

See Also

mux.markup

Function

Synopsis

Arguments

Returns

Examples

Notes

See Also

mux.notify

Function

Synopsis

Arguments

Returns

Examples

Notes

See Also

mux.object

Function

Synopsis

Arguments

Returns

Examples

Notes

See Also

mux.strip_style

Function

Synopsis

Arguments

Returns

Examples

Notes

See Also