DerpyMUD

Navigation

Client specifications

This section is designed for programmers who want to write their own DerpyMUD clients. DerpyMUD supports several different protocols to support a range of clients, with the server assuming telnet initially.

Connecting and telnet negotiation

To connect to the DerpyMUD server, a TCP/IP connection should be opened on port 23 (telnet). The server will begin by sending the following telnet negotiation options (as detailed in RFC 854):

DO NAWS (RFC 1073)
WILL Compress (MCCP)
WILL Compress2 (MCCP)

Negotiation proceeds as per RFC 854, or can be ignored by the client. Negotation or sub-negotiation may be sent at any point by the client, although the server will not send any negotiation sequences after the initial connection. Most commonly, NAWS sub-negotiation is sent by the client when the client terminal / window is resized - the server will format output based on what it believes the client terminal width is set to, defaulting to 80 fixed-width characters.
The server will send and recieve data as UTF-8.
Data can be sent to the server character by character or in batches; the server will accumulate data until a newline (ASCII 10) is recieved.

TA2 Advanced

A client can switch to TA2 protocol in one of two ways:

By sending the string "TA2" followed by a newline as the first data after any telnet negotiation.
By using the .advproto command once logged in.

TA2 advanced protocol allows out of band data to be sent to the client in the form of PML tags, and allows the server to send advanced text formatting options; 24-bit colour, bold, italic, underline and strikethrough formatted text.
TA2 protocol does not support UTF-8 text sent from server to client, althoiugh the client is free to send UTF-8 data to the server.

Text formatting

The TA2 protocol uses the top bit of each byte (0x80) to signify if this is a TA2 tag. If this bit is set, the remaining 7 bit of the byte describe the TA2 format tag, and if this bit is not set, the remaining 7 bits of the byte describe an ASCII character. The bits in a TA2 format byte are defined as:

Bit 7 (0x80) - TA2BIT: If set, this byte is a TA2 format byte.
Bit 6 (0x40) - TA2BIT_ENABLE: If set, this format byte is to enable format flags, otherwise this format byte is to disable them.
Bit 5 (0x20) - TA2BIT_BOLD: Enable or disable bold text formatting.
Bit 4 (0x10) - TA2BIT_ITALIC: Enable or disable italic text formatting.
Bit 3 (0x08) - TA2BIT_UNDERLINE: Enable or disable underline text formatting.
Bit 2 (0x04) - TA2BIT_TEXTCOLOUR: Change text colour, or reset it to default if bit 6 (0x40, TA2BIT_ENABLE) is not set. If bit 6 (0x40, TA2BIT_ENABLE) is set, then the following 6 bytes represent an RRGGBB hex colour to set as the current text colour (case insensitive).
Bit 1 (0x02) - TA2BIT_STRIKEOUT: Enable or disable ~~strikeout~~ text formatting.
Bit 0 (0x01): Unused.

Multiple bits can be set in the same byte, for example bold, italic and colour format options can all be enabled by setting bits 8, 7, 5, 4 and 2 (0xf4).
Text formatting is stateful, so the current text formatting should be applied until it is disabled. Text formatting can also be applied cumulatively, for example if the bold format option is enabled, and then later the underline format option is enabled, then the following text should be both bold and underlined.

Text formatting examples

Example text	Hexadecimal respresentation	Notes
`Bold red text`	`0xe4 0x66 0x66 0x30 0x30 0x30 0x30 "Bold red text"`	`{TA2BIT \| TA2BIT_ENABLE \| TA2BIT_BOLD \| TA2BIT_TEXTCOLOUR} ff0000 "Bold red text"`
`Bold, and italic, then default green`	`0xf4 0x30 0x30 0x66 0x66 0x30 0x30 "Bold, " 0xd0 "and italic," 0xb0 "then default green"`	`{TA2BIT \| TA2BIT_ENABLE \| TA2BIT_BOLD \| TA2BIT_ITALIC \| TA2BIT_TEXTCOLOUR} 00ff00 "Bold, " {TA2BIT \| TA2BIT_ENABLE \| TA2BIT_ITALIC} "and italic," {TA2BIT \| TA2BIT_BOLD \| TA2BIT_ITALIC} "then default green"`
`Bold RGB`	`0xe0 "Bold " 0xc4 0x66 0x66 0x30 0x30 0x30 0x30 "R" 0xc4 0x30 0x30 0x66 0x66 0x30 0x30 "G" 0xc4 0x30 0x30 0x30 0x30 0x66 0x66 "B"`	`{TA2BIT \| TA2BIT_ENABLE \| TA2BIT_BOLD} "Bold" {TA2BIT \| TA2BIT_ENABLE \| TA2BIT_TEXTCOLOUR} ff0000 "R" {TA2BIT \| TA2BIT_ENABLE \| TA2BIT_TEXTCOLOUR} 00ff00 "G" {TA2BIT \| TA2BIT_ENABLE \| TA2BIT_TEXTCOLOUR} 0000ff "B"`

PML

The server can also send out of band (OOB) data in the form of PML (Pouya Markup Language - XML, for all intents and purposes) tags, book-ended by the character code 0x19 and followed by a carriage-return line feed ("\r\n") sequence. These tags are not designed to be displayed to the user, but to convey information to the client application without the client having to scrape human-readable, formatted text from the server. For example, when the user successfully logs in, the server will send a PML tag containing the user's ID and username. This will be sent as:
0x19 <loggedin id="42" username="example"/> 0x19 0x0d 0x0a
A client that supports the TA2 protocol should not display the PML tag, the preceeding or trailing 0x19 byte, nor the trailing newline to the user. The client should ignore any PML tag which it does not understand.

Druink protocol

Druink protocol is built on top of the TA2 protocol, meaning it supports everything that TA2 protocol supports, but it additionally supports Unicode characters. Similarly to TA2 protocol, a client can switch to Druink protocol in one of two ways:

By sending the string "$DRUINK" followed by a newline as the first data after any telnet negotiation.
By using the .druinkproto command once logged in.

Unicode characters are sent to the client as a 0x1a byte, followed by up to 8 hex digits representing the Unicode character, followed by another 0x1a byte, for example:
"\x1a" "26a3" "\x1a" - White smiling face