evennia.server.portal.wire_formats

Wire format codecs for WebSocket subprotocol support.

This package implements the strategy pattern for WebSocket wire formats, allowing Evennia to support multiple WebSocket subprotocols as defined by the MUD Standards WebSocket proposal (https://mudstandards.org/websocket/).

Each wire format is a self-contained codec that handles encoding outgoing data and decoding incoming data for a specific WebSocket subprotocol.

Supported subprotocols:

• v1.evennia.com: Evennia’s legacy JSON array format

• json.mudstandards.org: MUD Standards JSON envelope format

• gmcp.mudstandards.org: GMCP over WebSocket

• terminal.mudstandards.org: Raw ANSI terminal over WebSocket

class evennia.server.portal.wire_formats.WireFormat

Bases: object

Abstract base class for WebSocket wire format codecs.

A wire format handles the translation between Evennia’s internal message representation and the bytes sent over the WebSocket connection.

Each subclass corresponds to a specific WebSocket subprotocol name (e.g., “v1.evennia.com”, “json.mudstandards.org”).

name

The subprotocol identifier string, used in Sec-WebSocket-Protocol negotiation.

Type:

str

supports_oob

Whether this format supports out-of-band data (structured commands beyond plain text).

Type:

bool

decode_incoming(payload, is_binary, protocol_flags=None)

Decode an incoming WebSocket message into kwargs for data_in().

Parameters:

• payload (bytes) – Raw WebSocket message payload.

• is_binary (bool) – True if this was a BINARY frame (opcode 2), False if it was a TEXT frame (opcode 1).

• protocol_flags (dict, optional) – The session’s protocol flags, which may affect decoding behavior.

Returns:

dict or None –

A dict of kwargs to pass to session.data_in(),

where each key is an inputfunc name and value is [args, kwargs]. Returns None if the message should be silently ignored.

encode_default(cmdname, *args, protocol_flags=None, **kwargs)

Encode a non-text OOB command for sending to the client.

This handles all outputfuncs that don’t have a specific send_* method, including custom OOB commands.

Parameters:

• cmdname (str) – The OOB command name.

• *args – Command arguments.

• protocol_flags (dict, optional) – Session protocol flags.

• **kwargs – Additional keyword arguments.

Returns:

tuple or None –

A (data_bytes, is_binary) tuple for sendMessage(),

or None if nothing should be sent (e.g., if the format doesn’t support OOB).

encode_prompt(*args, protocol_flags=None, **kwargs)

Encode a prompt for sending to the client.

Default implementation delegates to encode_text with the send_prompt option set.

Parameters:

• *args – Prompt arguments.

• protocol_flags (dict, optional) – Session protocol flags.

• **kwargs – Additional keyword arguments. May include an “options” dict; if absent, one is created with “send_prompt” set to True.

Returns:

tuple or None –

A (data_bytes, is_binary) tuple for sendMessage(),

or None if nothing should be sent.

encode_text(*args, protocol_flags=None, **kwargs)

Encode text output for sending to the client.

This handles the “text” outputfunc — the primary game output. The default implementation processes ANSI markup and returns a UTF-8 encoded BINARY frame. Subclasses that need a different encoding (e.g. HTML conversion) should override this method.

Parameters:

• *args – Text arguments. args[0] is typically the text string.

• protocol_flags (dict, optional) – Session protocol flags that may affect encoding (e.g., NOCOLOR, SCREENREADER, RAW).

• **kwargs – Additional keyword arguments. May include an “options” dict with keys like “raw”, “nocolor”, “screenreader”, “send_prompt”.

Returns:

tuple or None –

A (data_bytes, is_binary) tuple for sendMessage(),

or None if nothing should be sent.

name = None

supports_oob = True

class evennia.server.portal.wire_formats.EvenniaV1Format

Bases: WireFormat

Evennia’s legacy wire format: JSON arrays over TEXT frames.

Wire format:

All frames are TEXT (UTF-8 JSON). Structure: [“cmdname”, [args], {kwargs}]

Text handling:

Outgoing text is converted from ANSI to HTML via parse_html().

OOB:

All commands are effectively OOB — the cmdname field can be any string, not just “text”.

decode_incoming(payload, is_binary, protocol_flags=None)

Decode incoming JSON array message.

Parameters:

• payload (bytes) – UTF-8 encoded JSON: [“cmdname”, [args], {kwargs}]

• is_binary (bool) – Should be False for this format.

• protocol_flags (dict, optional) – Not used by this format.

Returns:

dict or None – kwargs for data_in(), e.g. {“text”: [[“look”], {}]}

encode_default(cmdname, *args, protocol_flags=None, **kwargs)

Encode any OOB command as a JSON array.

Skips the “options” command (legacy behavior).

Returns:

tuple or None –

(json_bytes, False) for TEXT frame, or None

if cmdname is “options”.

encode_prompt(*args, protocol_flags=None, **kwargs)

Encode a prompt as HTML-converted JSON with send_prompt flag.

Returns:

tuple or None – (json_bytes, False) for TEXT frame.

encode_text(*args, protocol_flags=None, **kwargs)

Encode text output as HTML-converted JSON.

Converts ANSI color codes to HTML spans, applies screenreader and raw text options.

Returns:

tuple or None – (json_bytes, False) where False means TEXT frame.

name = 'v1.evennia.com'

supports_oob = True

class evennia.server.portal.wire_formats.JsonStandardFormat

Bases: WireFormat

MUD Standards JSON envelope wire format.

Wire format:

BINARY frames: Raw ANSI text (UTF-8), used for game text I/O. TEXT frames: JSON envelope {“proto”, “id”, “data”} for

structured/OOB data.

Text handling:

Outgoing text retains ANSI escape codes (no HTML conversion). Text is sent as BINARY frames.

OOB:

Supported via TEXT frames. The “proto” field identifies the protocol (e.g., “gmcp”), “id” identifies the command, and “data” carries the JSON payload.

decode_incoming(payload, is_binary, protocol_flags=None)

Decode incoming WebSocket message.

BINARY frames are treated as raw text input. TEXT frames are parsed as JSON envelopes.

Parameters:

• payload (bytes) – The raw frame payload.

• is_binary (bool) – True for BINARY frames, False for TEXT.

• protocol_flags (dict, optional) – Not used.

Returns:

dict or None – kwargs for data_in().

encode_default(cmdname, *args, protocol_flags=None, **kwargs)

Encode an OOB command as a GMCP-in-JSON envelope.

OOB commands are sent as TEXT frames with the JSON envelope format. The command is translated to GMCP naming conventions and wrapped in a {“proto”: “gmcp”, “id”: “Package.Name”, “data”: “…”} envelope.

Parameters:

• cmdname (str) – The OOB command name.

• *args – Command arguments.

• protocol_flags (dict, optional) – Not used.

• **kwargs – Command keyword arguments.

Returns:

tuple or None –

(json_bytes, False) for TEXT frame, or None

if cmdname is “options”.

encode_prompt(*args, protocol_flags=None, **kwargs)

Encode a prompt.

For the JSON standard format, prompts are sent as a JSON envelope in a TEXT frame with proto=”prompt”, allowing the client to distinguish prompts from regular text.

Returns:

tuple or None – (json_bytes, False) for TEXT frame.

name = 'json.mudstandards.org'

supports_oob = True

class evennia.server.portal.wire_formats.GmcpStandardFormat

Bases: WireFormat

GMCP-native wire format over WebSocket.

Wire format:

BINARY frames: Raw ANSI text (UTF-8), used for game text I/O. TEXT frames: GMCP commands in standard format

“Package.Name json_payload”

Text handling:

Outgoing text retains ANSI escape codes (no HTML conversion). Text is sent as BINARY frames.

OOB:

Supported via TEXT frames carrying GMCP messages. The GMCP format is: “Package.Name optional_json_payload”

decode_incoming(payload, is_binary, protocol_flags=None)

Decode incoming WebSocket message.

BINARY frames are raw text input. TEXT frames are GMCP messages.

Parameters:

• payload (bytes) – The raw frame payload.

• is_binary (bool) – True for BINARY frames, False for TEXT.

• protocol_flags (dict, optional) – Not used.

Returns:

dict or None – kwargs for data_in().

encode_default(cmdname, *args, protocol_flags=None, **kwargs)

Encode an OOB command as a GMCP message in a TEXT frame.

Parameters:

• cmdname (str) – The OOB command name.

• *args – Command arguments.

• protocol_flags (dict, optional) – Not used.

• **kwargs – Command keyword arguments.

Returns:

tuple or None –

(gmcp_bytes, False) for TEXT frame, or None

if cmdname is “options”.

name = 'gmcp.mudstandards.org'

supports_oob = True

class evennia.server.portal.wire_formats.TerminalFormat

Bases: WireFormat

Raw ANSI terminal wire format over BINARY WebSocket frames.

Wire format:

All frames are BINARY, containing UTF-8 ANSI text. No TEXT frames are used.

Text handling:

Outgoing text retains ANSI escape codes (no HTML conversion). ANSI is rendered by the client.

OOB:

Not supported. This format has no structured data channel.

decode_incoming(payload, is_binary, protocol_flags=None)

Decode incoming WebSocket frame as raw text input.

Both BINARY and TEXT frames are treated identically as UTF-8 text.

Parameters:

• payload (bytes) – Raw UTF-8 text from the client.

• is_binary (bool) – True for BINARY frames, False for TEXT. Both are handled identically.

• protocol_flags (dict, optional) – Not used.

Returns:

dict or None – {“text”: [[text_string], {}]}

encode_default(cmdname, *args, protocol_flags=None, **kwargs)

OOB commands are not supported in terminal mode.

Returns:

None – Always returns None (OOB data is silently dropped).

name = 'terminal.mudstandards.org'

supports_oob = False

• evennia.server.portal.wire_formats.base
  • WireFormat
    • WireFormat.name
    • WireFormat.supports_oob
    • WireFormat.name
    • WireFormat.supports_oob
    • WireFormat.decode_incoming()
    • WireFormat.encode_text()
    • WireFormat.encode_prompt()
    • WireFormat.encode_default()
• evennia.server.portal.wire_formats.evennia_v1
  • EvenniaV1Format
    • EvenniaV1Format.name
    • EvenniaV1Format.supports_oob
    • EvenniaV1Format.decode_incoming()
    • EvenniaV1Format.encode_text()
    • EvenniaV1Format.encode_prompt()
    • EvenniaV1Format.encode_default()
• evennia.server.portal.wire_formats.gmcp_standard
  • GmcpStandardFormat
    • GmcpStandardFormat.name
    • GmcpStandardFormat.supports_oob
    • GmcpStandardFormat.decode_incoming()
    • GmcpStandardFormat.encode_default()
• evennia.server.portal.wire_formats.json_standard
  • JsonStandardFormat
    • JsonStandardFormat.name
    • JsonStandardFormat.supports_oob
    • JsonStandardFormat.decode_incoming()
    • JsonStandardFormat.encode_prompt()
    • JsonStandardFormat.encode_default()
• evennia.server.portal.wire_formats.terminal
  • TerminalFormat
    • TerminalFormat.name
    • TerminalFormat.supports_oob
    • TerminalFormat.decode_incoming()
    • TerminalFormat.encode_default()