Message Modules

A "Message Module" is an XML-based resource that defines a "Message Service". A Message Service contains multiple DML Records that act as templates for application-specific messages. They can be numerically referenced by their unique ServiceID that is defined within a unique record called _ProtocolInfo. Each DML record inside a Message Service is also given a MessageType that is determined by a _MsgOrder field, or by alphabetically ordering the names of the messages if that field is not present.

XML Format

The root element of a XML message module does not need to be anything specific, however, it's often the name of the file without the .xml extension. The tag of children elements define the names of messages, and the child <RECORD> element describes a template of that message (see here for a detailed look into <RECORD> elements).

There are special reserved field names for important message metadata:

Name	Type	Description
_MsgName	STR	The name of the message. (Overrides the element's tag)
_MsgDescription	STR	A description of the message.
_MsgHandler	STR	Determines which function/method should be called whenever a session receives this message.
_MsgAccessLvl	UBYT	The minimum access level a session is required to have for a server to handle this message.
_MsgOrder	UBYT	Where the message appears in the lookup table. (Used to determine message type)

The only exception to this is the _ProtocolInfo element. This element does not describe a message, but rather provides metadata to the Message Service (such as a name, description, and ID). These are the fields found within this element:

Name	Type	Description
ServiceID	UBYT	A unique ID for the message service being defined.
ProtocolType	STR	A unique, usually short, name for the message service being defined.
ProtocolVersion	INT	The version of the message module.
ProtocolDescription	STR	A short description of the message service.

XML Example

This is the BaseMessages.xml file from both Wizard101 and Pirate101.

<?xml version="1.0" ?>
<BaseMessages>
<_ProtocolInfo>
  <RECORD>
    <ServiceID TYPE="UBYT">1</ServiceID>
    <ProtocolType TYPE="STR">SYSTEM</ProtocolType>
    <ProtocolVersion TYPE="INT">1</ProtocolVersion>
    <ProtocolDescription TYPE="STR">All Common System Messages - Not Game Messages</ProtocolDescription>
  </RECORD>
</_ProtocolInfo>
<MSG_PING>
  <RECORD>
    <_MsgType TYPE="UBYT" NOXFER="TRUE">1</_MsgType>
    <_MsgName TYPE="STR" NOXFER="TRUE">MSG_PING</_MsgName>
    <_MsgDescription TYPE="STR" NOXFER="TRUE">PING request.</_MsgDescription>
    <_MsgHandler TYPE="STR" NOXFER="TRUE">MSG_Ping</_MsgHandler>
    <_MsgAccessLvl TYPE="UBYT" NOXFER="TRUE">0</_MsgAccessLvl>
  </RECORD>
</MSG_PING>
<MSG_PING_RSP>
  <RECORD>
    <_MsgType TYPE="UBYT" NOXFER="TRUE">2</_MsgType>
    <_MsgName TYPE="STR" NOXFER="TRUE">MSG_PING_RSP</_MsgName>
    <_MsgDescription TYPE="STR" NOXFER="TRUE">PING response.</_MsgDescription>
    <_MsgHandler TYPE="STR" NOXFER="TRUE">MSG_PingRsp</_MsgHandler>
    <_MsgAccessLvl TYPE="UBYT" NOXFER="TRUE">0</_MsgAccessLvl>
  </RECORD>
</MSG_PING_RSP>
</BaseMessages>

In this example, two messages are defined: MSG_PING and MSG_PING_RSP. These are two simple messages without any fields. The message service itself is also given metadata via _ProtocolInfo.

The message service is given the ID 1 via the ServiceID field in the _ProtocolInfo record, as well as a ProtocolType, ProtocolVersion, and ProtocolDescription.

The two messages that are defined, MSG_PING, and MSG_PING_RSP, are given the message types 1 and 2 respectively, however, this value is not given by the _MsgType value; this is a legacy field that is ignored entirely. The values 1 and 2 are calculated based on an alphabetical ordering of the _MsgName field because _MsgOrder is not specified.