CoffeeMud 5.11 Inline Protocols

• ASCII
• ANSI
• ANSI-256
• TELNET
• MCCP
• MCP
  
• MSP
• MXP
• MSDP
• GMCP
• MSSP
• MPCP
• Grapevine
• DISCORD
• Twitter/X
• Ollama/LLM

The CoffeeMud Server, like all other MUD servers in its class, is responsible for much of the player view and retains all character and map information.  The server utilizes several protocols that assist a variety of MUD game clients in presenting this view.  This document exists to enumerate and detail those protocols, with special emphasis on any particular CoffeeMud specific additions or changes.

ASCII

All text from the MUD server is transmitted as per the ISO-8859-1 encoding, an 8-bit superset of US-ASCII, though only the specified characters shown below are typically used.  This encoding can be changed from the coffeemud.ini file.  The End-of-line marker follows the Diku standard of LF-CR (\n\r, or 10-13).  Most text files, however, can be encoded using either, or any combination of \n and \r, so long as the same standard is used throughout the file.

Dec Char                 Dec Char  Dec Char  Dec Char
---------                --------- --------- ----------
 0  NUL (null)           32  SPACE 64  @     96  `
 1  Not used             33  !     65  A     97  a
 2  Not used             34  "     66  B     98  b
 3  Not used             35  #     67  C     99  c
 4  Not used             36  $     68  D     100 d
 5  Not used             37  %     69  E     101 e
 6  Not used             38  &     70  F     102 f
 7  BEL (bell)           39  '     71  G     103 g
 8  BS  (backspace)      40  (     72  H     104 h
 9  TAB (horz tab)       41  )     73  I     105 i
 10 LF (NL line feed)    42  *     74  J     106 j
 11 Not used             43  +     75  K     107 k
 12 Not used             44  ,     76  L     108 l
 13 CR (carriage return) 45  -     77  M     109 m
 14 Not used             46  .     78  N     110 n
 15 Not used             47  /     79  O     111 o
 16 Not used             48  0     80  P     112 p
 17 Not used             49  1     81  Q     113 q
 18 Not used             50  2     82  R     114 r
 19 Not used             51  3     83  S     115 s
 20 Not used             52  4     84  T     116 t
 21 Not used             53  5     85  U     117 u
 22 Not used             54  6     86  V     118 v
 23 Not used             55  7     87  W     119 w
 24 Not used             56  8     88  X     120 x
 25 Not used             57  9     89  Y     121 y
 26 Not used             58  :     90  Z     122 z
 27 ESC (escape)         59  ;     91  [     123 {
 28 Not used             60  <     92  \     124 |
 29 Not used             61  =     93  ]     125 }
 30 Not used             62  >     94  ^     126 ~
 31 Not used             63  ?     95  _     127 Not used

ANSI

The ANSI escape sequences are an ASCII-compatible protocol for varying the display of text, and for controlling cursor position and other terminal features.  For our purposes, it is best to think of it as what allows 16 foreground colors for text, and 8 text background colors.  None of the other rich features of ANSI escape codes are presently sent by the server.  If or when they do, this section will be updated.

An escape code begins with the sending of ASCII code 27 'ESC', followed by ASCII 91 '[', followed by one integer, or two integers separated by semicolons, and finally ending with ASCII 109 'm'.

The escape codes that the server may be expected to send include:

* The \033 above is the ASCII-27 (ESCAPE)

ANSI-256

This is a further extension of the color capabilities of ANSI that provides 256 foreground and background colors.   While  ANSI  is supported by basically any and all clients, ANSI-256 tends to be less supported.  This can lead to undefined behavior when one of the special colors are sent by the server.  For this reason, this feature can be specifically turned off by the user using the CONFIG command.

The format for ANSI-256 is as follows:

TELNET

TELNET is a system of inline escape codes that CoffeeMud uses to negotiate client capabilities between the client and server, and to support the other protocols below.  It is defined by RFC-854, which is available on the internet for your inspection.

TELNET negotiations consist of a set of asynchronous message/response pairs.  Typical of this would be the server sending to the client a WILL -feature- or WONT -feature- message, and the client responding with either a DO -feature- or DONT -feature.

These negotations are of the form:

[IAC][DO][CODE]

Where [IAC] is decimal 252, [DO] is either 253 for DO, 254 for DONT, 251 for WILL, or 252 for WONT. [CODE] is one of the TELNET feature codes (see below)

Another type of TELNET negotation is the SUB-OPTION negotation, which allows the client to send more information to the server than can be represented in a single byte.   The format of these is:

[IAC][SB][CODE][STREAM][IAC][SE]

Where [IAC] is decinal 252, [SB] is 250, [SE] is 240, [CODE] is a Sub-Option code (see below), and [STREAM] is one or more bytes specific to the SUB-OPTION code. 

The set of features that the server will automatically negotiate with the client upon connection includes the following:

Go-Ahead is a code sent by the server that informs the client that the it is now waiting for input.  Very few clients support this, and the number that don't outweigh those that do, so, while this feature can be enabled, it is not by default.  The format of this is simple: [IAC][GA] where [GA] is decimal 249. The client may also send [IAC][DO][SGA] to suppress the go-ahead feature, where [SGA] is decimal 3.

CoffeeMud does not send Go-Ahead by default, but activates it for a few mud clients based on the results of the Terminal Type query.

Echo

If enabled, this will cause the server to echo back to the client all the characters sent from it.  While it can be negotiated in the normal way mentioned above, it is more typical to be automatically set by the server in reaction to a Terminal Type response.  For example, if the client says that it is "ZMUD", then echo is automatically disabled, regardless of what the client may have sent previous to that.  The [ECHO] code is decimal 1.

Logout

Upon receiving a DO [LOGOUT] code from the client, the server will disconnect the client and close its socket.  [LOGOUT] is decimal 18.

MCCP

The Mud Client Compression Protocol, when enabled, alters the encoding sent by the server to the client to one that is GZIP compressed ASCII.  There were two versions of this protocol, and CoffeeMud supports version 2.

The protocol is enabled during the early connection period.  The server will send the TELNET code WILL COMPRESS2.  If the client responds with DO COMPRESS2, then the server will wait 750ms and send the TELNET sub-negotiation code 86, after which all output from the server to that client will be in the GZIP compressed format with only a single initial DEFLATE header and no CRC.  No data will be sent, however, for another few seconds to give the client time to process the response and set up.  See also the above section on the TELNET protocol for more information on how negotiations are done.

MCP

The MUD Client Protocol is an entirely in-line system for invoking 'packages' or programs on the server by the client, or on the client by the server.  CoffeeMud supports, by default, only two packages:  one that negotiates the MCP features, and a client-side full screen editor package.  Complete details on MCP can be found at https://www.moo.mud.org/mcp/mcp2.html

Upon connection to the server, the client will be sent a mcp protocol announcement string:

#$#mcp version: 2.1 to: 2.1

If the client does not support MCP, then that's the end of it.  However, if it does support MCP, it will begin sending supported packages information to the server, starting with the following special command:

#$#mcp authentication-key: [AUTH-KEY]

The [AUTH-KEY] sent is then saved by the server to confirm against other inline MCP messages.

The MCP protocol general command format is as follows:

#$#[MCP-PACKAGE] [AUTH-KEY] [KEY]: [VALUE] ... etc ..

[MCP-PACKAGE] would be one of the package names, usually beginning with MCP.  After the following space, the auth-key and another space, followed by an optional set of key:value pairs.  Keys may not contain whitespace.  After the colon must be a whitespace character followed by a double-quoted value, or a value also without whitespace.  The value may then be followed by whitespace and more key:value pairs.  If a string beginning with #$# must be sent to the client by the mud for consumption by the user, then the line should begin with #$"#$#...

Multi-line commands begin in the following format:

#$#[MCP-PACKAGE] [AUTH-KEY] ... etc ... [KEY]*: [VALUE] _data-tag: [TAG-VALUE]

As you can see, if the last real key on the ends with the '*' character and the line ends with a a key called "_data-tag" whose value is a hex number, then it denotes the beginning of a multi-line command.  In this case, the following line would begin with #$#* followed by data-tag value the to continue the previous line, and ends when a line that starts with #$#: is encountered.   Here are some examples:

#$#* [TAG-VALUE] [KEY]: [VALUE] ... etc ...
#$#: [TAG-VALUE] [KEY]: [VALUE] ... etc ...

Anyway, back to the negotiation.  After receiving the authentication-key, the server will immediately respond with a series of messages announcing which packages it supports:

#$#mcp-negotiate-can [AUTH-KEY] package: dns-org-mud-moo-simpleedit min-version: 1.0 max-version: 1.0
#$#mcp-negotiate-can [AUTH-KEY] package: mcp-negotiate min-version: 1.0 max-version: 2.0
#$#mcp-negotiate-end

This will be followed (or preceded?) by the client sending a similar set of messages declaring the packages that it supports.

dns-org-mud-moo-simpleedit-content

This package is sent by the server to the client asking it to open up a screen text editor with the given content.  Once the client user is done editing the file, the package is invoked by the client to send back the changed text.

The command sent by the server will look like:

#$#dns-org-mud-moo-simpleedit-content [AUTH-KEY] reference: #64.name name: Data type: string content*: "" _data-tag: [NUMBER]
#$#* [NUMBER] content: "[FIRST LINE OF THE FILE]"
...
#$#: [NUMBER]

* If a developer wants to add more Server-side MCP packages, they should be written as Java files that implement the com.planet_ink.coffee_mud.Libraries.interfaces.ProtocolLibrary.MCPPackage interface, and placed in the com/planet_ink/coffee_mud/Libraries/mcppkgs/ directory before boot.

MSP

The MUD Sound Protocol allows sound files to be played by the client.  It can also specify a URL to download the sound file from a web server supported by the MUD.  A detailed definition of the protocol can be found at https://www.zuggsoft.com/zmud/msp.htm

Before the server will begin to send MSP inline commands, it will first negotiate client support for the protocol.  It does this using a TELNET WILL MCP escape code, as described above in the TELNET section.

Once the server is aware of client support, then, at appropriate times, it will send the MSP inline command, which is as follows:

MXP

The Mud eXtension Protocol, developed by ZuggSoft, is an HTML-like markup language that provides quite a few client view capabilities that can be driven by the server, but also configured by the client user.  These features include sounds, images, context menus, text markup, color, frames, cursor control, and entities.A detailed definition of the protocol can be found at https://www.zuggsoft.com/zmud/mxp.htm

Not many mud clients support the entire MXP command set.  Presently, that list includes ZMUD, CMUD (both from ZuggSoft themselves), and the Siplet web-based client built into CoffeeMud.  Many other clients, however, support some portion of MXP, so your mileage may vary.

Before the server will begin to send MXP tags, it will first negotiate client support for the protocol.  It does this using a TELNET WILL MXP escape code, as described above in the TELNET section.

Once the server is aware of client support, it will automatically transmit the file /resources/text/mxp.txt to the client, which contains numerous entity definitions for context menus,  health bar tags, and the <SUPPORT tag to notify the client of the MXP features that the client supports.  These include: IMAGE, SEND, GUAGE, FONT, B, IMAGE, and SOUND.

Tags are so similar to HTML as to not really be worth elaboration, but I will anyway.  An example would be: <HITPOINTS>24</HITPOINTS>, after, for example, definiting an MXP entity with <!ELEMENT HITPOINTS '<FONT COLOR=GREEN>' >  This would result in the number 24 being seen as green on the muds client, or whatever else is sent inside <HITPOINTS> tag. 

The <!ELEMENT tag is unique to MXP, and is used to give definition to substitute some tag (such as HITPOINTS with others, such as FONT.  It can also be used to call out or define some value.   <!ELEMENT is followed by the name of the tag being defined, followed by the word EMPTY and the FLAG attribute, or a replacement MXP string in single quotes ''. 

The GUAGE tag is for adding a column to the "health bar" type feature.  The tag begins with <GUAGE [TAG] Max=[MAXTAG] ... , where [TAG] is the name of the tag whose value will update this bar, where [MAXTAG] is the name of the tag whose value updates the maximum value of this bar.  Other attributes include COLOR, and CAPTION.

The IMAGE tag is for sending images to the client.  The format is <IMAGE [FILENAME] URL="http://your.web.site/images/' H=[HEIGHT] W=[WIDTH]>.  Stock images are typically found in the /web/pub/images/mxp/ directory.  Images may be added there, and then associated with objects of various kinds for automatic association by the mud by editing the file /resources/mxp_images.ini and adding a new line or editing an existing line.

The SOUND tag is for sending sounds to the client.  The format is <SOUND FILENAME V=50 P=25 U=http://your.web.site/sounds>.  This is remarkably similar to the MSP format above, which was probably intentional. :)  See the MSP section for more information on CoffeeMud Sounds.

The SEND tag is for creating right-mouse-click context menus on various lines of text to allow the user to enter commands that make use of them without typing.  The format is <SEND HREF="[COMMANDS]" HINT="[TEXT]">  The [COMMANDS] are a |pipe|-delimited list of MUD commands that are entered when a menu option is chosen.  The [TEXT] is a pipe-delimited list of the menu options corresponding to the commands.  The string &text; is used to substitute the value inside the <SEND tag. 

To differentiate MXP tags from normal uses of the less-than < sign, you will often see a carrot ^< preceding the less-than sign, to let the mud know that an MXP tag was embedded in an outgoing string.  MXP also allows traditional HTML entitles, such as &quot; for double-quotes, &lt; for less-than, etc.

MSDP

The MUD Server Data Protocol is a protocol that embeds itself entirely in TELNET sub-option negotiation codes in order to send and receive data and data request commands.  The purpose is to allow extra "unseen" data to be sent to the client from the server, which can then expose or otherwise use the data.  You can find details for this protocol at the following site: https://tintin.mudhalla.net/protocols/msdp/

Before the server will begin to send MSDP data packets, it will first negotiate client support for the protocol.  It does this using a TELNET WILL MSDP escape code, as described above in the TELNET section.  Once MSDP is enabled on both sides, the client may then begin sending "LIST" commands in an MSDP packet to learn the capabilities of the server.

The format of a typical MSDP packet is, as mentioned previously, to embed an MSDP stream inside a TELNET sub-option negotiation packet. A typical key-value pair packet is as follows:

[IAC][SB][MSDP-CODE][MSDP-VAR-CODE][VAR-NAME][MSDP-VAL-CODE][VAR-VALUE]...[IAC][SE]

Where [IAC] is decinal 252, [SB] is 250, [SE] is 240, [MSDP-CODE] is 69, [MSDP-VAR-CODE] is 1, [MSDP-VAL-CODE] is 2, [VAR-NAME] and [VAR-VALUE] are unquoted ascii strings.

Instead of simple string values, MSDP also supports both value lists, arrays, and value tables.   A list is simply a case where more than one [MSDP-VAL-CODE] is provided for a given VAR.  For example:

[IAC][SB][MSDP-CODE][MSDP-VAR-CODE][VAR-NAME][MSDP-VAL-CODE][VAR-VALUE] [MSDP-VAL-CODE][VAR-VALUE] ... [IAC][SE]

An example of an array would be:

[IAC][SB][MSDP-CODE][MSDP-VAR-CODE][VAR-NAME][MSDP-VAL-CODE][MSDP-ARRAY-OPEN-CODE]
[MSDP-VAL-CODE][VAR-VALUE] ... [MSDP-ARRAY-CLOSE-CODE][IAC][SE]

[IAC][SB][MSDP-CODE][MSDP-VAR-CODE][VAR-NAME][MSDP-VAL-CODE][MSDP-TABLE-OPEN-CODE]
[MSDP-VAR-CODE][VAR-NAME][MSDP-VAL-CODE][VAR-VALUE] ... [MSDP-TABLE-CLOSE-CODE][IAC][SE]

Client Commands and Server Variables

Commands are sent as Special variable names, with the value being an argument to the command, which is typically a variable or list of variables. 

"LIST" "COMMANDS" will cause the server to respond with the variable "COMMANDS" and an Array of client commands that may be used.  These are typically "LIST", "REPORT", "UNREPORT", "RESET", and "SEND".  The difference between values "SEND"ed or "REPORT"ed is that SEND orders the server to give a value only on demand, whereas REPORT causes the server to send a new value every time the variable changes on the server side. UNREPORT will stop that behavior for the given variable.   This LIST command is typically the first one sent by the client after MSDP is negotiated.

Other "LIST"able things include: CONFIGURABLE_VARIABLES, REPORTABLE_VARIABLES,  REPORTED_VARIABLES, SENDABLE_VARIABLES

Other than commands, MSDP distinguishes between two types of variables: Reportable and Configurable.  In CoffeeMud, both types can be subject to the SEND command, but only Reportable variables can be the subject of the REPORT command, and only Configurable variables can be changed by the client, or reset using the RESET command.  At this time, CoffeeMud does not support any configurable variables.

Reportable variables include ACCOUNT_NAME, CHARACTER_NAME, SERVER_ID, SERVER_TIME, SPECIFICATION, AFFECTS, ALIGNMENT, EXPERIENCE, EXPERIENCE_MAX,EXPERIENCE_TNL, EXPERIENCE_TNL_MAX, HEALTH, HEALTH_MAX, LEVEL, MANA, MANA_MAX, MONEY, MOVEMENT, MOVEMENT_MAX, OPPONENT_LEVEL, OPPONENT_HEALTH, OPPONENT_HEALTH_MAX, OPPONENT_NAME, OPPONENT_STRENGTH, OPPONENT_RANGE, WORLD_TIME, ROOM, LOCATION, ROOM_NAME, ROOM_VNUM, ROOM_AREA, ROOM_TERRAIN, ROOM_EXITS, ARACHNOS_MUDLIST, ARACHNOS_DEVEL, ARACHNOS_CHAT

GMCP

The Generic Mud Client Protocol is a close sibling to the MSDP protocol, in that it is also entirely implemented using the TELNET sub-option negotiation protocol.  Also like MSDP, GMCP is bi-directional, and intended mostly for communicating information from the server to the client.  Inside each TELNET SB packet is a a string consisting of a GMCP "Package" name/command followed by a a space and then a JSON document.   You can find details for this protocol at the following site: https://tintin.mudhalla.net/protocols/gmcp/

Before the server will begin to send GMCP data packets, it will first negotiate client support for the protocol.  It does this using a TELNET WILL GMCP escape code, as described above in the TELNET section. 

The format of a typical GMCP packet is, as mentioned previously, to embed an GMCP package and JSON document stream inside a TELNET sub-option negotiation packet. A typical packet is as follows:

Where [IAC] is decinal 252, [SB] is 250, [SE] is 240, [GMCP-CODE] is 201, [GMCP-PKG-NAME] is a space-free GMCP package or command word, typically formatted with period-separated package names.  [JSON-DOCUMENT] is just what it sounds like, a JSON document, such as a JSON map, array, string, etc.

CoffeeMud supported Packages/Commands:

Some of the above, if supported, will cause values to be automatically sent by the server to the client when the server detects a change, either immediately, or on the next tick.  These include: comm, comm.tick, char.status, group, char, char.vitals, char.worth, char.maxstats, char.base, char.effects.get, room, room.info, room.mobiles, room.players, room.items, room.items.inv, room.enter, room.leave.

All others have either special behavior, or must be requested of the server by sending the package name/command.

MSSP

The MUD Server Status Protocol is a unique protocol whose purpose is to gather high-level basic information about a MUD without logging in a character.  For this reason, all of the protocol transactions will occur on your Login prompt.  Like MSDP, MSSP is encoded entirely in a TELNET sub-option negotiation packet.  See the TELNET section for more information, and see the website for MSSP at https://tintin.mudhalla.net/protocols/mssp/

Before the server will begin to send MSSP data packets, it will first negotiate client support for the protocol.  It does this using a TELNET WILL MSSP escape code, as described above in the TELNET section.  

The format of a typical MSDP packet is, as mentioned previously, to embed an MSDP stream inside a TELNET sub-option negotiation packet. A typical key-value pair packet is as follows:

Where [IAC] is decinal 252, [SB] is 250, [SE] is 240, [MSSP-CODE] is 70, [MSSP-VAR-CODE] is 1, [MSSP-VAL-CODE] is 2, [VAR-NAME] and [VAR-VALUE] are unquoted ascii strings.

Immediately after the DO MSSP TELNET code is received by the server from the client, CoffeeMud will immediately send the entire MSSP Packet.  Encoded in the VAR-VALUE format mentioned above, this data includes:

NAME, PLAYERS, STATUS, PORT, UPTIME, HOSTNAME, WEBSITE, LANGUAGE, ICON, CHARSET, I3, IMC2, INTERMUD, FAMILY, CRAWL DELAY, CREATED, CONTACT, EMAIL, CODEBASE, AREAS, HELPFILES, MOBILES, OBJECTS, GAMESYSTEM, ROOMS, CLASSES, RACES, SKILLS, ANSI, XTERM 256 COLORS, MXXP, MSP, MXP.  To this list is added any special variables and values defined in the coffeemud.ini file under "MSXPVARS".  See the above MSSP web site for more information on what extra variables might be cool to send.

MPCP

Before the proxy server will begin to send MPCP data packets, it will first negotiate support for the protocol with the mud server through its proxy client connection.  It does this using a TELNET WILL MPCP escape code, as described above in the TELNET section.  

The format of a typical MPCP packet is, as mentioned previously, to embed an MPCP package and JSON document stream inside a TELNET sub-option negotiation packet. A typical packet is as follows:

Where [IAC] is decinal 252, [SB] is 250, [SE] is 240, [MPCP-CODE] is 202, [MPCP-PKG-NAME] is a space-free MPCP package or command word, typically formatted with period-separated package names.  [JSON-DOCUMENT] is just what it sounds like, a JSON document, such as a JSON map, array, string, etc.  The [HASH] is a 20 byte HmacSHA1 of the code and json document, built from a shared secret key. 

Every JSON document must include the "timestamp" field with the epoc time in milliseconds, to prevent replay abuse.

CoffeeMud supported Packages/Commands:

Grapevine

The Grapevine Protocol allows mud information and status, channel and tell messages, and achievements to be shared between muds on its network.  A detailed definition of the protocol can be found at https://grapevine.haus/.  No special libraries or other java configuration is required to enable CoffeeMud support.

Using the service requires going to the grapevine.haus website and registering your mud.  Next, you generate a ClientID and Client Secret.  These are then placed in the coffeemud.ini file under the GVCLIENTID and GVCLIENTSECRET fields.

On boot, CoffeeMud will connect to the grapevine hub and request mud, player, and achievements information.  When assigning your local channels to grapevine, you can really only choose between gossip, testing, and moo at the moment.  The GV command exists to manage and monitor the grapevine network from the command line.

DISCORD

Twitter/X

Ollama/LLM