Your IP : 216.73.216.182
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head>
<meta name="generator" content="HTML Tidy, see www.w3.org" /><title>The CoffeeMud CM1 Server</title>
<link rel="StyleSheet" href="style.css" type="text/css" media="screen" /><!-- Modified by Josh Mueller, 2006-5-5, fix validation errors, add index, and fix spelling errors --></head>
<body>
<center>
<table border="1" cellpadding="10" cellspacing="0" width="90%">
<tbody>
<tr>
<td colspan="2" align="left" bgcolor="#dfdfdf" width="100%">
<h1>CoffeeMud 5.10 Inline Protocols</h1>
</td>
</tr>
<tr>
<td align="left" valign="top" width="20%">
<ul>
<li><a href="#ascii">ASCII</a></li>
<li><a href="#ansi">ANSI</a></li>
<li><a href="#ansi256">ANSI-256</a></li>
<li><a href="#telnet">TELNET</a></li>
<li><a href="#mccp">MCCP</a></li>
<li><a href="#mcp">MCP</a><br />
</li>
<li><a href="#msp">MSP</a></li>
<li><a href="#mxp">MXP</a></li>
<li><a href="#msdp">MSDP</a></li>
<li><a href="#gmcp">GMCP</a></li>
<li><a href="#mssp">MSSP</a></li><li><a href="#discord">DISCORD</a></li>
</ul>
</td>
<td align="left" valign="top">
<p>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.</p>
<h2><a name="ascii">ASCII</a></h2>
<p>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.</p>
<pre style="color: rgb(0, 0, 0); font-style: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; widows: 2; word-spacing: 0px;">Dec Char Dec Char Dec Char Dec Char<br />--------- --------- --------- ----------<br /> 0 NUL (null) 32 SPACE 64 @ 96 `<br /> 1 Not used 33 ! 65 A 97 a<br /> 2 Not used 34 " 66 B 98 b<br /> 3 Not used 35 # 67 C 99 c<br /> 4 Not used 36 $ 68 D 100 d<br /> 5 Not used 37 % 69 E 101 e<br /> 6 Not used 38 & 70 F 102 f<br /> 7 BEL (bell) 39 ' 71 G 103 g<br /> 8 BS (backspace) 40 ( 72 H 104 h<br /> 9 TAB (horz tab) 41 ) 73 I 105 i<br /> 10 LF (NL line feed) 42 * 74 J 106 j<br /> 11 Not used 43 + 75 K 107 k<br /> 12 Not used 44 , 76 L 108 l<br /> 13 CR (carriage return) 45 - 77 M 109 m<br /> 14 Not used 46 . 78 N 110 n<br /> 15 Not used 47 / 79 O 111 o<br /> 16 Not used 48 0 80 P 112 p<br /> 17 Not used 49 1 81 Q 113 q<br /> 18 Not used 50 2 82 R 114 r<br /> 19 Not used 51 3 83 S 115 s<br /> 20 Not used 52 4 84 T 116 t<br /> 21 Not used 53 5 85 U 117 u<br /> 22 Not used 54 6 86 V 118 v<br /> 23 Not used 55 7 87 W 119 w<br /> 24 Not used 56 8 88 X 120 x<br /> 25 Not used 57 9 89 Y 121 y<br /> 26 Not used 58 : 90 Z 122 z<br /> 27 ESC (escape) 59 ; 91 [ 123 {<br /> 28 Not used 60 < 92 \ 124 |<br /> 29 Not used 61 = 93 ] 125 }<br /> 30 Not used 62 > 94 ^ 126 ~<br /> 31 Not used 63 ? 95 _ 127 Not used<br /><br /></pre>
<h2><a name="ascii">ANSI</a></h2>
<p>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.<br />
</p>
<p>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'.</p>
<p>The escape codes that the server may be expected to send
include:</p>
<span style="font-family: monospace;">\033[1;37m
WHITE<br />
\033[1;32m LIGHTG REEN<br />
\033[1;34m LIGHT BLUE<br />
\033[1;31m LIGHT RED<br />
\033[1;33m YELLOW<br />
\033[1;36m LIGHT CYAN<br />
\033[1;35m LIGHT PURPLE<br />
\033[0;37m GREY<br />
\033[0;32m GREEN<br />
\033[0;34m BLUE<br />
\033[0;31m RED<br />
\033[0;33m BROWN<br />
\033[0;36m CYAN<br />
\033[0;35m PURPLE<br />
\033[1;30m DARK GREY<br />
\033[0;30m BLACK<br />
\033[0;0m NONE/TURN OFF/RESTORE DEFAULTS<br />
\033[1m BOLD<br />
\033[4m UNDERLINE<br />
\033[5m BLINK<br />
\033[6m ITALICS<br />
\033[47m WHITE BACKGROUND<br />
\033[42m GREEN BACKGROUND<br />
\033[44m BLUE BACKGROUND<br />
\033[41m RED BACKGROUND<br />
\033[43m YELLOW BACKGROUND<br />
\033[46m CYAN BACKGROUND<br />
\033[45m PURPLE BACKGROUND<br />
\033[40m BLACK BACKGROUND<br />
\033[49m DEFAULT BACKGROUND<br />
</span><br />
<p>* The \033 above is the ASCII-27 (ESCAPE)</p>
<p><br />
</p>
<h2><a name="ansi256">ANSI-256</a></h2>
<p>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.</p>
<p>The format for ANSI-256 is as follows:</p>
<span style="font-family: monospace;">\033[38;5;XXm
FOREGROUND COLOR XX (0 - 255)<br />
</span><span style="font-family: monospace;">\033[48;5;XXm
BACKGROUND COLOR XX (0 - 255)<br />
</span><br />
<h2><a name="telnet"> TELNET</a></h2>
<p>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.</p>
<p>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.</p>
<p>These negotations are of the form:</p>
<p style="font-family: monospace;">[IAC][DO][CODE]</p>
<p>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)</p>
<p>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:</p>
<p style="font-family: monospace;">[IAC][SB][CODE][STREAM][IAC][SE]</p>
<p>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. <br />
</p>
<p>The set of features that the server will automatically
negotiate with the client upon connection includes the following:</p>
<span style="font-family: monospace;">[IAC][DO][TERMTYPE]
Offer to support Terminal Type sub-option. [TERMTYPE] is dec 24</span><br style="font-family: monospace;" />
<span style="font-family: monospace;">[IAC][SB][TERMTYPE][ONE][IAC][SE]
Initiate TermType sub-option negotation, where [ONE] is dec 1<br />
[IAC][WILL][COMPRESS2]</span><span style="font-family: monospace;">
Offer to
support MCCP protocol (see below). [COMPRESS2] is dec 86<br />
[IAC][WILL][MXP]</span><span style="font-family: monospace;">
Offer
to support MXP protocol (see below). [MXP] is dec 91<br />
</span><span style="font-family: monospace;">[IAC][</span><span style="font-family: monospace;">WILL</span><span style="font-family: monospace;">][GMCP]
Offer to support GMCP protocol (see below). [GMCP] is dec 201<br />
</span><span style="font-family: monospace;">[IAC][</span><span style="font-family: monospace;">WILL</span><span style="font-family: monospace;">][MSP]
Offer to support MSP
protocol (see below).
[MSP] is dec 90<br />
</span><span style="font-family: monospace;">[IAC][</span><span style="font-family: monospace;">WILL</span><span style="font-family: monospace;">][MSDP]
Offer
to support MSDP protocol (see below). [MSDP] is dec 69<br />
</span><span style="font-family: monospace;">[IAC][</span><span style="font-family: monospace;">WILL</span><span style="font-family: monospace;">][NAWS]
Offer
to support Window Size sub-option. [NAWS] is dec 31<br />
</span><span style="font-family: monospace;">[IAC][</span><span style="font-family: monospace;">WILL</span><span style="font-family: monospace;">][MSSP]
Offer
to support MSSP protocol (see below). [MSSP] is dec 70</span><br />
<br />
The client will
then be given a period of time to respond with the appropriate DO or
DONT before the server just proceeds with its default
behavior. <br />
<br />
The "Terminal Type" negotiation is expected to be responded to by the
client with:<br />
<span style="font-family: monospace;">[IAC][SB][TERMTYPE][ZERO][CLIENT
NAME][IAC][SE]</span><br />
Where [IAC], [SB], [TERMTYPE], and [SE] are as above. [ZERO]
is
decimal 0. [CLIENT NAME] is an ascii stream of the name of
the
client. <br />
<br />
The NAWS negotiation is expected to be responded to by the client with:<br />
<span style="font-family: monospace;">[IAC][SB][NAWS][WIDTHLB][WIDTHHB][HEIGHTLB][HEIGHTHB][IAC][SE]</span><br />
Where [IAC], [SB], [NAWS], and [SE] are as above. [WIDTHLB]
and
[WIDTHHB] are the low and high byte of the terminal width.
[HEIGHTLB] and [HEIGHTHB] are the low and high byte of the terminal
height (which is unused).<br />
<br />
Other features that may be enabled or modified by clients include:<br />
<br />
<span style="font-weight: bold;">Go-Ahead/Suppress
Go-Ahead:</span><br />
<p>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.</p><p>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.</p>
<p style="font-weight: bold;">Echo</p>
<p>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.<br />
</p>
<p style="font-weight: bold;">Logout</p>
<p>Upon receiving a DO [LOGOUT] code from the client, the
server
will disconnect the client and close its socket. [LOGOUT] is
decimal 18.<br />
</p>
<span style="font-weight: bold;">Are you There?</span><br />
<br />
Upon receiving [IAC][AYT], the server will respond with a space and
\b. The [AYT] code is 246.<br />
<br />
<h2><a name="mccp"> MCCP</a></h2>
<p>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.</p>
<p>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. 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.</p>
<p><br />
</p>
<h2><a name="mcp"> MCP</a></h2>
<p>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 <a href="https://www.moo.mud.org/mcp/mcp2.html">https://www.moo.mud.org/mcp/mcp2.html</a><br />
</p>
<p>Upon connection to the server, the client will be sent a
mcp protocol announcement string:</p>
<p><span style="font-family: monospace;">#$#mcp
version: 2.1 to: 2.1</span><br />
</p>
<p>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:<br />
</p>
<p style="font-family: monospace;">#$#mcp
authentication-key: [AUTH-KEY]</p>
<p>The [AUTH-KEY] sent is then saved by the server to
confirm against other inline MCP messages.<br />
</p>
<p>The MCP protocol general command format is as follows:<br />
<br />
<span style="font-family: monospace;"><span style="font-family: monospace;">#$#[MCP-PACKAGE] [AUTH-KEY]
[KEY]: [VALUE] ... etc ..</span><br />
</span></p>
<p>[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 #$"#$#...</p>
<p>Multi-line commands begin in the following format:</p>
<p><span style="font-family: monospace;">#$#[MCP-PACKAGE]
</span><span style="font-family: monospace;">[AUTH-KEY]
</span><span style="font-family: monospace;">...
etc ... [KEY]*: [VALUE] _data-tag: [TAG-VALUE]</span><br />
</p>
<p>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:<br />
</p>
<p><span style="font-family: monospace;">#$#* </span><span style="font-family: monospace;">[TAG-VALUE] </span><span style="font-family: monospace;">[KEY]: [VALUE] </span><span style="font-family: monospace;"><span style="font-family: monospace;">... etc ... </span><br />
<span style="font-family: monospace;">#$#: </span><span style="font-family: monospace;">[</span><span style="font-family: monospace;">TAG-VALUE</span><span style="font-family: monospace;">] </span><span style="font-family: monospace;">[KEY]: [VALUE] </span><span style="font-family: monospace;">... etc ... </span></span></p>
<p>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:</p>
<p style="font-family: monospace;">#$#mcp-negotiate-can
[AUTH-KEY] package: dns-org-mud-moo-simpleedit min-version: 1.0
max-version: 1.0<br />
#$#mcp-negotiate-can [AUTH-KEY] package: mcp-negotiate min-version: 1.0
max-version: 2.0<br />
#$#mcp-negotiate-end<br />
</p>
<p>This will be followed (or preceded?) by the client
sending a similar set of messages declaring the packages that it
supports.</p>
Packages supported:<br />
<p><span style="font-weight: bold;">dns-org-mud-moo-simpleedit-content</span><br />
</p>
<p>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.</p>
<p>The command sent by the server will look like:</p>
<p><span style="font-family: monospace;">#$#dns-org-mud-moo-simpleedit-content
[AUTH-KEY] reference: #64.name name: Data type: string content*: ""
_data-tag: [NUMBER]</span><br style="font-family: monospace;" />
<span style="font-family: monospace;">#$#* [NUMBER]
content: "[FIRST LINE OF THE FILE]"</span><br style="font-family: monospace;" />
<span style="font-family: monospace;">...</span><br style="font-family: monospace;" />
<span style="font-family: monospace;">#$#: [NUMBER]</span></p>
<p>* 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.</p>
<p><br />
</p>
<h2><a name="msp">MSP</a></h2>
<p>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 <a href="https://www.zuggsoft.com/zmud/msp.htm">https://www.zuggsoft.com/zmud/msp.htm</a><br />
</p>
<p>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.</p>
<p>Once the server is aware of client support, then, at
appropriate times, it will send the MSP inline command, which is as
follows:</p>
<span style="font-family: monospace;">!!SOUND([FILENAME]
V=50 P=25 U=http://webserver.domain/sounds/)</span><br />
<br />
To add new sounds to CoffeeMud, you should put them as a loose wav file
in /resources/web/pub/sounds/ , and also put them in the sounds.zip
file found in the same directory, for people who want to install all
the sounds in their client at once.<br />
The arguments are V)olume (0-100), L) Repeats (-1 for infinity, or a #),
P)riority (0-100), C)ontinue (0 or 1), T)ype (a label), U)RL to download
sound file from.<br />
<br />
<h2><a name="mxp">MXP</a></h2>
<p>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 <a href="https://www.zuggsoft.com/zmud/msp.htm">https://www.zuggsoft.com/zmud/mxp.htm<br />
</a></p>
<p>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.<br />
</p>
<p>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.</p>
<p>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.</p>
<p>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. <br />
</p>
<p>The <span style="font-weight: bold;"><!ELEMENT</span>
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
''. <br />
</p>
<p>The <span style="font-weight: bold;">GUAGE</span>
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.</p>
<p>The <span style="font-weight: bold;">IMAGE</span>
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.<br />
</p>
<p>The <span style="font-weight: bold;">SOUND</span>
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.</p>
<p>The <span style="font-weight: bold;">SEND</span>
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. <br />
</p>
<p>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.<br />
</p>
<p></p>
<h2><a name="msdp">MSDP</a></h2>
<p>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: <a href="https://tintin.mudhalla.net/protocols/msdp/">https://tintin.mudhalla.net/protocols/msdp/</a><br />
</p>
<p>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.</p>
<p>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:</p>
<p><span style="font-family: monospace;">[IAC][SB][MSDP-CODE][MSDP-VAR-CODE][VAR-NAME][MSDP-VAL-CODE][VAR-VALUE]...[IAC][SE]</span><br />
</p>
<p>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.</p>
<p>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:</p>
<p><span style="font-family: monospace;">[IAC][SB][MSDP-CODE][MSDP-VAR-CODE][VAR-NAME][MSDP-VAL-CODE][VAR-VALUE]
</span><span style="font-family: monospace;">[MSDP-VAL-CODE][VAR-VALUE]
</span><span style="font-family: monospace;">...
[IAC][SE]</span></p>
<p>An example of an array would be:</p>
<p><span style="font-family: monospace;">[IAC][SB][MSDP-CODE][MSDP-VAR-CODE][VAR-NAME][MSDP-VAL-CODE]</span><span style="font-family: monospace;">[MSDP-ARRAY-OPEN-CODE]<br />
</span><span style="font-family: monospace;">[MSDP-VAL-CODE]</span><span style="font-family: monospace;">[VAR-VALUE] ... </span><span style="font-family: monospace;"><span style="font-family: monospace;">[MSDP-ARRAY-CLOSE-CODE]</span><span style="font-family: monospace;">[IAC][SE]</span></span></p>
Where [MSDP-ARRAY-OPEN-CODE] is decimal 5, and [MSDP-ARRAY-CLOSE-CODE]
is 6. Tables are defined as embedded key-value
pairs, and
look as follows:<br />
<p><span style="font-family: monospace;">[IAC][SB][MSDP-CODE][MSDP-VAR-CODE][VAR-NAME][MSDP-VAL-CODE]</span><span style="font-family: monospace;">[MSDP-TABLE-OPEN-CODE]</span><span style="font-family: monospace;"><br />
[MSDP-VAR-CODE][VAR-NAME]</span><span style="font-family: monospace;">[MSDP-VAL-CODE]</span><span style="font-family: monospace;">[VAR-VALUE] ... </span><span style="font-family: monospace;"><span style="font-family: monospace;">[MSDP-TABLE-CLOSE-CODE]</span><span style="font-family: monospace;">[IAC][SE]</span></span></p>
[MSDP-TABLE-OPEN-CODE] is decimal 3, and [MSDP-TABLE-CLOSE-CODE] is
decimal 4.<br />
<br />
<p style="font-weight: bold;">Client Commands and
Server Variables<br />
</p>
<p>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. <br />
</p>
<p>"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. </p>
<p>Other "LIST"able things include: CONFIGURABLE_VARIABLES,
REPORTABLE_VARIABLES, REPORTED_VARIABLES, SENDABLE_VARIABLES<br />
</p>
<p>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.</p>
<p>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<br />
</p>
<p></p>
<h2><a name="gmcp">GMCP</a></h2>
<p>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: <a href="https://tintin.mudhalla.net/protocols/msdp/">https://tintin.mudhalla.net/protocols/gmcp/</a></p>
<p>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. </p>
<p>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:</p>
<span style="font-family: monospace;">[IAC][SB][GMCP-CODE][GMCP-PKG-NAME][JSON-DOCUMENT][IAC][SE]</span>
<p> 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.</p>
<p>CoffeeMud supported Packages/Commands:</p>
<table style="text-align: left; width: 100%;" border="1" cellpadding="2" cellspacing="2">
<tbody>
<tr><td><span style="font-weight: bold;">Package/Command</span></td><td><span style="font-weight: bold;">JSON and notes</span></td></tr><tr><td>comm</td><td>Same as comm.tick</td></tr><tr><td>comm.tick</td><td>{} </td></tr><tr>
<td width="25%">core.hello</td>
<td>Arguments: {"client":"client name", "version": 1.0} - sent by Client</td>
</tr>
<tr>
<td width="25%">core.supports.set</td>
<td>Arguments: ["package-name 1.0", "package-name 2.1", ...] Set
the list of supported packages/commands and the version supported
(which is optional) - sent by the Client.</td>
</tr>
<tr>
<td width="25%">core.supports.add</td>
<td>Arguments: ["package-name 1.0", "package-name 2.1", ...] Adds to the list of supported
packages/commands and the version supported (which is optional) - sent
by the Client.</td>
</tr>
<tr>
<td width="25%">core.supports.remove</td>
<td>Arguments: ["package-name", "package-name", ...] Removes from the list of supported
packages/commands.</td>
</tr>
<tr>
<td width="25%">core.keepalive</td>
<td>No arguments. Sent to the server to update session idle timers.</td>
</tr>
<tr>
<td width="25%">core.ping</td>
<td>Returns whatever document is sent. Be careful of endless loops!</td>
</tr>
<tr>
<td width="25%">core.goodbye</td>
<td>No arguments. Closes the session and logs off the user.</td>
</tr>
<tr>
<td width="25%">char.login</td>
<td>Arguments: {"name":"char name", "password": "char pw" } - Logs in a
character, when one is not yet logged in. Sent by the client of
course.</td>
</tr>
<tr><td>char.login.credentials</td><td>Arguments: {"name":"char name", "password": "char pw" } - Eventually logs in a
character, if one is not yet logged in. Sent by the client of
course.</td></tr><tr>
<td width="25%">char.vitals</td>
<td>char.vitals {"hp": 1, "mana": 2, "moves": 3, "maxhp": 4, "maxmana": 5, "maxmoves": 6}.</td>
</tr>
<tr>
<td width="25%">char.statusvars</td>
<td>char.statusvars {"level": 1, "race": "racename", "guild": "clan name"}</td>
</tr>
<tr>
<td width="25%">char.status</td>
<td>char.status {"level": 1, "tnl": 2, "xpnl": 3, "xppl": 4, "hunger":
5, "thirst": 6, "fatigue": 7, "stink_pct": 8, "align": 9, "faction":
10, "state": 22, "pos": "sleeping", "enemy": "enemy name",
"enemyrange": 1, "enemypct": 10} <br />"state" is: 4-afk, 9-sleeping, 11-sitting, 8-in combat, 6-sysmsgs, 12-autorun, 3-normal</td>
</tr>
<tr><td>char</td><td>When supported, sends char.vitals, char.worth, char.maxstats, char.base</td></tr><tr>
<td width="25%">char.base</td>
<td>char.base {"name": "name", "class": "base class", "subclass":
"class name", "race": "race name", "perlevel": 999, "prevlevel": 999,
"pretitle": "title", "clan": "clan name" }</td>
</tr>
<tr>
<td width="25%">char.maxstats</td>
<td>char.maxstats {"maxhp": 1, "maxmana": 2, "maxmoves": 3 }</td>
</tr>
<tr>
<td width="25%">char.worth</td>
<td>char.worth {"gold": 1, "qp": 2, "trains": 3, "pracs": 4 }</td>
</tr>
<tr>
<td width="25%">char.items.inv</td>
<td>char.items.list {"location": "inv", "items": [{"id": 99922, "name": "item name", "attrib": "item attributes"}, ....] }</td>
</tr>
<tr>
<td width="25%">char.items.contents</td>
<td>char.items.list {"location": "container name", "items": [{"id":
99922, "name": "item name", "attrib": "item attributes"}, ....] }</td>
</tr>
<tr>
<td width="25%">char.skills.get</td>
<td>When sent, the optional argument are {"group": "skilltype-domain"},
or {"name": "skill name"}. The response when "name" is sent:
char.skills.info {"group": "skilltype-domain", "skill": "skill name",
"info": "help text"}. The response when "group" is sent:
char.skills.list{"group": "skilltype-domain", "list": ["skill name",
"skill name", ... ] }. With neither are sent: char.skills.groups
["skilltype-domain", ... ]</td>
</tr>
<tr>
<td width="25%">char.effects.get</td>
<td>When sent, the optional argument are {"group": "skilltype-domain"}, or
{"name": "skill name"}. The response when "name" is sent:
char.effects.info {"group": "skilltype-domain", "skill": "skill name",
"info": "help text"}. The response when "group" is sent:
char.effects.list{"group": "skilltype-domain", "list": ["skill name",
"skill name", ... ] }. With neither are sent: char.effects.groups
["skilltype-domain", ... ]</td>
</tr>
<tr>
<td width="25%">group</td>
<td>group {"groupname": "gname", "leader": "playername", "status":
"Private", "count": 1, "members": [ {"name": "playername", "info": {
"hp": 1, "mhp": 2, "mn": 3, "mmn": 4, "mv": 5, "mmv": 6, "lvl": 7,
"align": 8, "tnl": 9 }, ... }</td>
</tr>
<tr><td>room</td><td>When supported, sends room.info, room.items.inv, room.mobiles, room.players, room.enter, room.leave</td></tr><tr><td>room.items</td><td>Sends room.items.inv</td></tr><tr>
<td width="25%">room.info</td>
<td>room.info {"num": 932939, "id":"Area#9", "name": "name", "zone":
"area name", "desc": "room desc", "terrain": "locale domain type",
"move": 3, "details: "", "exits": [{'N': 929292 },...], "coord":
{"id":0,"x":-1,"y":-1,"cont":0} }</td>
</tr>
<tr><td>room.enter</td><td>room.enter "mob name"</td></tr><tr><td>room.leave</td><td>room.leave "mob name"</td></tr><tr>
<td width="25%">room.items.inv</td>
<td> rooms.items.list {"location": "room", "items": [ {"id": 93939, "name": "item name", "attrib": "GMCP attributes"}, ...] } </td>
</tr>
<tr>
<td width="25%">room.items.contents</td>
<td>rooms.items.list {"location": "container name", "items": [ {"id":
93939, "name": "item name", "attrib": "GMCP attributes"}, ...] } </td>
</tr>
<tr>
<td width="25%">room.mobiles</td>
<td>room.mobiles {"npcs": [{"mob name": "mob context name"}, ...] }</td>
</tr>
<tr>
<td width="25%">room.players</td>
<td>room.players {"pcs": [{"mob name": "mob context name"}, ...] }</td>
</tr>
<tr>
<td width="25%">comm.channel</td>
<td>comm.channel {"chan": "channelname", "msg": "message text", "player": "playername" } - sent when channel message arrives</td>
</tr>
<tr>
<td width="25%">comm.channel.players</td>
<td>com.channel.players [{"name": "playername", "channels":
["channelname", ...]} - list of online players and channels they can
read</td>
</tr>
<tr>
<td width="25%">ire.composer.setbuffer</td>
<td>Arguments: "text" After using a local client text editor, this command is sent to transmit the altered text.</td>
</tr>
<tr><td>ire.composer.edit</td><td>ire.composer.edit {"title": "message
title", "text": "message text" } - Sent by server to invoke client-side
offline text editor.</td></tr><tr>
<td width="25%">request.room</td>
<td> - same as room.info</td>
</tr>
<tr>
<td width="25%">request.area</td>
<td> - same as room.info</td>
</tr>
<tr>
<td width="25%">request.char</td>
<td> - same as char.base</td>
</tr>
<tr>
<td width="25%">request.sectors</td>
<td> - same as room.info</td>
</tr>
<tr>
<td width="25%">request.group</td>
<td> - same as group</td>
</tr>
<tr>
<td width="25%">request.quest</td>
<td> Not implemented</td>
</tr>
<tr>
<td width="25%">rawcolor</td>
<td> Does nothing, no idea what it should do.</td>
</tr>
<tr>
<td width="25%">request</td>
<td> Substitute for request.* (such as request.area), except the
"area" part is given instead of a JSON doc. For example: request
"area" would be the same as the request.area command.</td>
</tr>
<tr>
<td width="25%">maplevel</td>
<td> Does nothing, no idea what it should do.</td>
</tr>
<tr>
<td width="25%">client</td>
<td> Not used.</td>
</tr>
<tr>
<td width="25%">client.version</td>
<td> Not used.</td>
</tr>
<tr>
<td width="25%">external.discord.hello</td>
<td>Not implemented</td>
</tr>
<tr>
<td width="25%">msdp</td>
<td>Allows ALL of the features, variables, and data from the MSDP
spec above to be retreived through GMCP, except that the arguments and
data are in JSON documents instead of the MSDP coded format.
Var-Value is changed to maps, arrays to arrays, etc. For
example:<br />MSDP {"list": "commands"}. See the MSDP section above for more details on commands.</td>
</tr><tr><td>Siplet.Input</td><td>Siplet.Input ("title": "prompt text", "text": "current field value"}</td></tr>
</tbody>
</table>
<p>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.</p><p>All others have either special behavior, or must be requested of the server by sending the package name/command.<br />
</p>
<h2><a name="mssp">MSSP</a></h2>
<p>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 <a href="https://tintin.mudhalla.net/protocols/mssp/">https://tintin.mudhalla.net/protocols/mssp/</a></p><p>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. </p>
<p>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:</p>
<span style="font-family: monospace;">[IAC][SB][MSSP-CODE][MSDP-VAR-CODE][VAR-NAME][MSDP-VAL-CODE][VAR-VALUE]...[IAC][SE]</span><p>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.</p><p>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:</p><p>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.</p>
<h2><a name="discord">DISCORD</a></h2>
The MUD supports a two-way channel message interface with the popular
chat site/app "Discord" through a fantastic library called "Javacord".
As suggested, it allows the CoffeeMud administrator to tie
specific in-game message channels to specific Discord channels on a
particular Discord server. Messages then sent from on this
channel from either end are received and displayed at the other.<br /><br />The
Javacord interface requires quite a bit of setup, as well as
cooperation from the administrator of the Discord server itself.<br /><br />The first step is to visit '<a href="https://discord.com/developers/docs/intro">https://discord.com/developers/docs/intro</a>' and create an account.<br /><br />After
authorized, you can click on the Applications tab on the left and then
click New Application button on the upper right. Give your app a
name. Now select the "Bot" tab on the left and set the Username
to your unique Mud name. Under "Privileged Gateway Intents", make
sure all of the Intents are turned ON. Also, make sure you copy
your Bot Token and keep it somewhere safe -- you'll need it later.
After saving everything, you are done with the Discord App.<br /><br />The third step is to visit <a href="https://coffeemud.org/">https://coffeemud.org/</a>
and download the Discord (Javacord) jar file from the link under
"Downloading the Software". Save this jar file in your Coffeemud
"lib" directory for reference later. If you find a more updated
version of the jar file, that will probably be fine also.<br /><br />The fourth step is open up your coffeemud.ini file and make several changes. Set your javacord lib path:<br /><div style="padding: 0px 0px 0px 2px; background-color: rgb(255, 255, 255);">
<div style="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255); font-family: "Courier New"; font-size: 10pt; white-space: nowrap;">
<p style="background-color: rgb(232, 242, 254);"><span style="color: rgb(63, 127, 95);">DISCORD_JAR_PATH=/</span><span style="color: rgb(63, 127, 95); text-decoration: underline;">lib</span><span style="color: rgb(63, 127, 95);">/</span><span style="color: rgb(63, 127, 95); text-decoration: underline;">javacord</span><span style="color: rgb(63, 127, 95);">-3.9.0-shaded.jar</span></p></div>
</div>... and set your discord bot key to the token you copied earlier:<br /><div style="padding: 0px 0px 0px 2px; background-color: rgb(255, 255, 255);">
<div style="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255); font-family: "Courier New"; font-size: 10pt; white-space: nowrap;">
<p style="background-color: rgb(232, 242, 254);"><span style="color: rgb(63, 127, 95);">DISCORD_BOT_KEY=....</span></p></div>
</div>Now you can go up to the CHANNELS= entry and either add
some new channels to correspond with various Discord server channels
with the DISCORD=channelname flag. Do not include the hash-marks
in the channel names.<br /><br />After saving your coffeemud.ini file,
the fifth step is to restart your CoffeeMud server and look for any
discord error messages in the log file. Also look for an entry
that looks like this:<br />Discord Bot auth url: <span style="font-family: monospace;">https://discord.com/oauth2/authorize?client_id=..
..&scope=bot%20applications.commands&permissions=2048&prompt=consent</span><br /><br />Put that link into your browser and authorize your app to interact with the server with messaging privileges.<br /><br />The
last step is contact the administrator of your Discord server and ask
them to authorize your bot for the server. You may need to
provide your apps name. This will be done under the
"Integrations" area of Discord server administration.<br /><br />After this last is done, you *may* need to restart CoffeeMud one more time -- I'm not sure, so give your channels a test.<br />
<p></p>
<p></p>
<p></p>
<p></p>
<p></p>
<p></p>
<p></p>
<p> <br />
<br />
</p>
</td>
</tr>
<tr>
<td style="vertical-align: top;"><br />
</td>
<td style="vertical-align: top;"><br />
</td>
</tr>
</tbody>
</table>
<br />
</center>
</body></html>