evennia.server.portal.telnet_oob

Telnet OOB (Out of band communication)

OOB protocols allow for asynchronous communication between Evennia and compliant telnet clients. The “text” type of send command will always be sent “in-band”, appearing in the client’s main text output. OOB commands, by contrast, can have many forms and it is up to the client how and if they are handled. Examples of OOB instructions could be to instruct the client to play sounds or to update a graphical health bar.

Note that in Evennia’s Web client, all send commands are “OOB commands”, (including the “text” one), there is no equivalence to MSDP/GMCP for the webclient since it doesn’t need it.

This implements the following telnet OOB communication protocols:

• MSDP (Mud Server Data Protocol), as per http://tintin.sourceforge.net/msdp/

• GMCP (Generic Mud Communication Protocol) as per http://www.ironrealms.com/rapture/manual/files/FeatGMCP-txt.html#Generic_MUD_Communication_Protocol%28GMCP%29

---

class evennia.server.portal.telnet_oob.TelnetOOB(protocol)

Bases: object

Implements the MSDP and GMCP protocols.

__init__(protocol)

Initiates by storing the protocol on itself and trying to determine if the client supports MSDP.

Parameters

protocol (Protocol) – The active protocol.

no_msdp(option)

Client reports No msdp supported or wanted.

Parameters

option (Option) – Not used.

do_msdp(option)

Client reports that it supports msdp.

Parameters

option (Option) – Not used.

no_gmcp(option)

If this is reached, it means neither MSDP nor GMCP is supported.

Parameters

option (Option) – Not used.

do_gmcp(option)

Called when client confirms that it can do MSDP or GMCP.

Parameters

option (Option) – Not used.

encode_msdp(cmdname, *args, **kwargs)

Encode into a valid MSDP command.

Parameters

• cmdname (str) – Name of send instruction.

• args (any) – Arguments to OOB command.

• kwargs (any) – Arguments to OOB command.

Notes

The output of this encoding will be MSDP structures on these forms:

[cmdname, [], {}]           -> VAR cmdname VAL ""
[cmdname, [arg], {}]        -> VAR cmdname VAL arg
[cmdname, [args],{}]        -> VAR cmdname VAL ARRAYOPEN VAL arg VAL arg ... ARRAYCLOSE
[cmdname, [], {kwargs}]     -> VAR cmdname VAL TABLEOPEN VAR key VAL val ... TABLECLOSE
[cmdname, [args], {kwargs}] -> VAR cmdname VAL ARRAYOPEN VAL arg VAL arg ... ARRAYCLOSE
                               VAR cmdname VAL TABLEOPEN VAR key VAL val ... TABLECLOSE

Further nesting is not supported, so if an array argument consists of an array (for example), that array will be json-converted to a string.

encode_gmcp(cmdname, *args, **kwargs)

Encode into GMCP messages.

Parameters

• cmdname (str) – GMCP OOB command name.

• args (any) – Arguments to OOB command.

• kwargs (any) – Arguments to OOB command.

Notes

GMCP messages will be outgoing on the following form (the non-JSON cmdname at the start is what IRE games use, supposedly, and what clients appear to have adopted). A cmdname without Package will end up in the Core package, while Core package names will be stripped on the Evennia side.

[cmd_name, [], {}]          -> Cmd.Name
[cmd_name, [arg], {}]       -> Cmd.Name arg
[cmd_name, [args],{}]       -> Cmd.Name [args]
[cmd_name, [], {kwargs}]    -> Cmd.Name {kwargs}
[cmdname, [args, {kwargs}]  -> Core.Cmdname [[args],{kwargs}]

For more flexibility with certain clients, if cmd_name is capitalized, Evennia will leave its current capitalization (So CMD_nAmE would be sent as CMD.nAmE but cMD_Name would be Cmd.Name)

Notes

There are also a few default mappings between evennia outputcmds and GMCP:

client_options -> Core.Supports.Get
get_inputfuncs -> Core.Commands.Get
get_value      -> Char.Value.Get
repeat         -> Char.Repeat.Update
monitor        -> Char.Monitor.Update

decode_msdp(data)

Decodes incoming MSDP data.

Parameters

data (str or list) – MSDP data.

Notes

Clients should always send MSDP data on one of the following forms:

cmdname ''          -> [cmdname, [], {}]
cmdname val         -> [cmdname, [val], {}]
cmdname array       -> [cmdname, [array], {}]
cmdname table       -> [cmdname, [], {table}]
cmdname array cmdname table -> [cmdname, [array], {table}]

Observe that all MSDP_VARS are used to identify cmdnames, so if there are multiple arrays with the same cmdname given, they will be merged into one argument array, same for tables. Different MSDP_VARS (outside tables) will be identified as separate cmdnames.

decode_gmcp(data)

Decodes incoming GMCP data on the form ‘varname <structure>’.

Parameters

data (str or list) – GMCP data.

Notes

Clients send data on the form “Module.Submodule.Cmdname <structure>”. We assume the structure is valid JSON.

The following is parsed into Evennia’s formal structure:

Core.Name                         -> [name, [], {}]
Core.Name string                  -> [name, [string], {}]
Core.Name [arg, arg,...]          -> [name, [args], {}]
Core.Name {key:arg, key:arg, ...} -> [name, [], {kwargs}]
Core.Name [[args], {kwargs}]      -> [name, [args], {kwargs}]

data_out(cmdname, *args, **kwargs)

Return a MSDP- or GMCP-valid subnegotiation across the protocol.

Parameters

• cmdname (str) – OOB-command name.

• args (any) – Arguments to OOB command.

• kwargs (any) – Arguments to OOB command.