evennia.server.portal.wire_formats.base

Base wire format interface for WebSocket subprotocol codecs.

All wire format implementations must subclass WireFormat and implement the encoding/decoding methods. Each format represents a specific WebSocket subprotocol as defined by RFC 6455 Sec-WebSocket-Protocol negotiation.

class evennia.server.portal.wire_formats.base.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

name = None

supports_oob = True

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_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.

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_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).