mud

MUD telnet protocol encoding and decoding utilities.

Provides encode/decode functions for: - GMCP (Generic MUD Communication Protocol, option 201) - MSDP (MUD Server Data Protocol, option 69) - MSSP (MUD Server Status Protocol, option 70) - ZMP (Zenith MUD Protocol, option 93) - ATCP (Achaea Telnet Client Protocol, option 200) - AARDWOLF (Aardwolf protocol, option 102)

All encode functions return the payload bytes only (the content between IAC SB <option> and IAC SE). The caller is responsible for framing with subnegotiation markers.

gmcp_encode(package, data=None)

Encode a GMCP message.

Parameters:

• package (str) – GMCP package name (e.g., “Char.Vitals”)

• data (Any) – Optional data to encode as JSON

Return type:

bytes

Returns:

Encoded GMCP payload bytes

gmcp_decode(buf, encoding='utf-8')

Decode a GMCP payload.

Parameters:

• buf (bytes) – GMCP payload bytes

• encoding (str) – Character encoding to try first, falls back to latin-1.

Return type:

tuple[str, Any]

Returns:

Tuple of (package, data), where data is None if no JSON present

Raises:

ValueError – If JSON is malformed

msdp_encode(variables)

Encode variables to MSDP wire format.

Parameters:

variables (dict[str, Any]) – Dictionary of variable names to values

Return type:

bytes

Returns:

Encoded MSDP payload bytes

msdp_decode(buf, encoding='utf-8')

Decode MSDP wire bytes to dictionary.

Parameters:

• buf (bytes) – MSDP payload bytes

• encoding (str) – Character encoding to try first, falls back to latin-1.

Return type:

dict[str, Any]

Returns:

Dictionary of variable names to values

mssp_encode(variables)

Encode variables to MSSP wire format.

Parameters:

variables (dict[str, str | list[str]]) – Dictionary of variable names to string values or lists

Return type:

bytes

Returns:

Encoded MSSP payload bytes

mssp_decode(buf, encoding='utf-8')

Decode MSSP wire bytes to dictionary.

Parameters:

• buf (bytes) – MSSP payload bytes

• encoding (str) – Character encoding to try first, falls back to latin-1.

Return type:

dict[str, str | list[str]]

Returns:

Dictionary with str values for single entries, list[str] for multiple

class MsdpParser(buf, encoding='utf-8')

State machine for parsing MSDP wire bytes.

Initialize parser with raw MSDP buffer.

parse_value()

Parse a single MSDP value at current position.

Return type:

Any

parse()

Parse the full MSDP buffer into a dict.

Return type:

dict[str, Any]

zmp_decode(buf, encoding='utf-8')

Decode ZMP payload to list of NUL-delimited strings.

The first element is the command name, the rest are arguments.

Parameters:

• buf (bytes) – ZMP payload bytes (NUL-delimited).

• encoding (str) – Character encoding to try first, falls back to latin-1.

Return type:

list[str]

Returns:

List of strings [command, arg1, arg2, ...].

atcp_decode(buf, encoding='utf-8')

Decode ATCP payload to (package, value) tuple.

Format is package.name value separated by the first space. If no space is present, value is an empty string.

Parameters:

• buf (bytes) – ATCP payload bytes.

• encoding (str) – Character encoding to try first, falls back to latin-1.

Return type:

tuple[str, str]

Returns:

Tuple of (package, value).

aardwolf_decode(buf)

Decode Aardwolf protocol payload.

Parameters:

buf (bytes) – Aardwolf payload bytes (typically 1-2 bytes).

Return type:

dict[str, Any]

Returns:

Dict with channel, channel_byte, data_byte, and data_bytes (for longer payloads).