MUD Protocols

Tuesday, 14. July 2020 14:53:39, by Kerrinth

MUD Protocol Support

We are adding limited code support for the following MUD protocols:

GMCP
MCCP
MSDP (variables only)
MSSP
MSP (not yet used)
MXP (not yet used)

We will primarily be supporting GMCP and MCCP. Support for other protocols will be more limited. If you are interested in collaborating on an HTML5 MUD client using GMCP to support touch-based devices, please get in touch with Xiphoid using board 2 or emailing xiphoid at outland.org.

This page is currently the authoritative source of information for GMCP support in Avatar. As we add support for new types of message and expand or change the functionality of existing messages, we will document that here.

Supported GMCP Messages

Client Messages

We support the following messages sent from clients to the server:

Core.Hello

Sends information about the MUD client and its version.
May only be sent before successful login.

Example:

Core.Hello { "client": "MyMUDClient", "version": "1.2.34" }

Char.Login

Logs in using the specified character and password.
May only be sent before successful login.

Example:

Char.Login { "name": "Myalt", "password": "myl0n6c0mpl3xp455w0rd" }

Core.Ping

Ensures server is listening and GMCP is enabled.
Message body is a number which indicates average ping time from previous requests, if available.
Causes server to reply with a Core.Ping message in response.

Example:

Core.Ping 120

Core.KeepAlive

Resets the idle counter for the current character.

Example:

Core.KeepAlive

Core.Supports.Set

Notifies the server about packages supported by the client.
If another Core.Supports.* package has been received earlier, the list is deleted and replaced with the new one.
Message body is an array of strings, each consisting of the module name and version, separated by space.
Module version is a positive non-zero integer.
Most client implementations will only need to send Set once and won't need Add/Remove; exceptions are module implementations provided by plug-ins.

Example:

Core.Supports.Set [ "Char 1", "Char.Skills 1", "Char.Items 1" ]

Core.Supports.Add

Similar to Core.Supports.Set, but appends the supported module list to the one sent earlier.
If no list was sent yet, the behaviour is identical to Core.Supports.Set.
If the list includes module names that were already included earlier, the new version number takes precedence over the previously sent one, even if the newly sent number is lower.
Message body format is identical to that of Core.Supports.Set.

Example:

Core.Supports.Add [ "Char.Vitals 1", "Char.Status 1" ]

Core.Supports.Remove

Removes specified modules from the list of supported modules.
Message body format is similar to Core.Supports.Set, except that module version numbers are optional and ignored if given.

Example:

Core.Supports.Remove [ "Char", "Char.Skills", "Char.Items" ]

Char.Group.List

Sent by client to request groupl information.
Causes server to reply with a Char.Group.List message in response.

Example:

Char.Group.List

Char.Skills.Get

Sent by client to request skill information.
Message body is an object with keys "group" and "name".
If both group and name is provided, the server will send Char.Skills.Info for the specified skill.
If group is provided but name is not, the server will send Char.Skills.List for that group.
Otherwise the server will send Char.Skills.Groups.

Example:

Char.Skills.Get { "group": "Arcane", "name": "fireball" }

Char.Items.Inv

Request for the server to send the list of items in player's inventory.
Message body is empty.
Causes the server to send back an appropriate Char.Items.List message.

Example:

Char.Items.Inv

Char.Items.Contents

Request for the server to send the list of items located inside another item.
Message body is a number identifying the item.
Causes the server to send back an appropriate Char.Items.List message.

Example:

Char.Items.Contents 12345678

Comm.Channel.Players

Request for the server to send Comm.Channel.Players.
No message body.

Example:

Comm.Channel.Players

Server Messages

The following messages may be sent from the server to clients:

Core.Goodbye

Sent by server immediately before terminating a connection.
Message body is a string to be shown to the user - it can explain the reason for the disconnect.

Example:

Core.Goodbye "Leaving the AVATAR System for the 'real world'...
    May your stay in reality be worthwhile."

Core.Ping

Sent in reply to Core.Ping from the client.
No message body.

Example:

Core.Ping

Char.Group.List

Describes the list of group members for the player.
Sent by server on request only.
Message body is an object with keys which are the player name or mob serial and values which describe the status of the group member.

Example:

Char.Group.List [
    { "leader": true, "name": "Xiphling", "level": "Lord", "position": "Stand", "hp": "10000", "maxhp": "10000",
           "mp": "20000", "maxmp": "20000", "mv": "30000", "maxmv": "30000", "tnl": "1428", "align": "-1000" },
    { "leader": false, "name": "Xiphlet", "level": "Lord", "position": "Stand", "hp": "20000", "maxhp": "20000",
           "mp": "10000", "maxmp": "10000", "mv": "30000", "maxmv": "30000", "tnl": "1428", "align": "-1000" }
]

Char.Items.List

List of items at a specified location (room, inv, container).
Message body is an object with keys "location" and "items".
Location value is a string, "inv", "room", or "NUMBER" (for container identification).
Items are returned as an array, where each item is an object with keys "id", "name" and "type".
id is a number identifying the item, name is a string containing a short player-visible item description, type is the type of the object.

Example:

Char.Items.List {
    "location": "room",
    "items": [
        { "id": "15442582457", "name": "a rock", "type": "trash" },
        { "id": "15442877992", "name": "a magical fountain", "type": "fountain" }
   ]
}

Char.Skills.Info

Describes information about a single skill.
Sent by server on request only.
Message body is an object with keys "group", "skill", and "info", values are strings.
The group and skill identify the skill, info is a description (usually multi-line) of the skill's functionality and usage.

Example:

Char.Skills.Info {
    "skill": "burning hands",
    "group": "Arcane",
    "info": "Syntax: cast 'burning hands'       [Area Affect]

    Burning hands allows the spellcaster to inflict damage to all mobs in a
    room, by shooting jets of flames from the spellcaster's hands.  The amount
    of damage is determined by the level of the spellcaster.

    As with all area spells, there is no need to specify a target.

    This spell causes fire damage.
    "
}

Char.Skills.List

Describes the list of skills available to the character in the specified group.
Sent by server on request only.
Message body is an object with keys "group" and "list", where group is the name of the skill group and list is the list of skills.

Example:

Char.Skills.List { "group": "Arcane", "list": [ "burning hands", "detect magic" ] }

Char.Skills.Groups

Describes the groups of skills available to the character.
Sent by server on request or when appropriate, e.g. if the list changes.
Message body is an array of names of skill groups.

Example:

Char.Skills.Groups [ "Channel", "Arcane", "Psionic", "Rogue", "Archer", "Ranger",
    "Common", "Warrior", "Lore", "Stance", "Monk", "Ritual", "Object", "Rite" ]

Char.StatusVars

Sent by server after a successful login.
Contains a list of names of character status variables (level, race, etc) and their display captions.
Message body is an object with keys containing the names of the status variables and values containing the captions to be displayed to the user.

Example:

Char.StatusVars {
  "character_name":"Character Name",
  "server_id":"Server ID",
  "server_time":"Server Time",
  "affects":"Affects",
  "alignment":"Alignment",
  "experience_tnl":"TNL",
  "experience_tnl_max":"Max TNL",
  "health":"HP",
  "health_max":"Max HP",
  "level":"Level",
  "sublevel":"Sublevel",
  "race":"Race",
  "class":"Class",
  "mana":"Mana",
  "mana_max":"Max Mana",
  "wimpy":"Wimpy",
  "practice":"Practices",
  "gold":"Gold",
  "movement":"Move",
  "movement_max":"Max Move",
  "hitroll":"Hitroll",
  "damroll":"Damroll",
  "ac":"AC",
  "str":"Str",
  "int":"Int",
  "wis":"Wis",
  "dex":"Dex",
  "con":"Con",
  "str_perm":"Perm Str",
  "int_perm":"Perm Int",
  "wis_perm":"Perm Wis",
  "dex_perm":"Perm Dex",
  "con_perm":"Perm Con",
  "opponent_health":"Opponent HP %",
  "opponent_health_max":"Max Opponent HP %",
  "opponent_level":"Opponent Level",
  "opponent_name":"Opponent Name",
  "area_name":"Area Name",
  "room_exits":"Room Exits",
  "room_name":"Room Name",
  "world_time":"World Time",
  "client_id":"Client ID",
  "client_version":"Client Version",
  "plugin_id":"Plugin ID",
  "ansi_colors":"ANSI Color",
  "utf_8":"UTF-8",
  "sound":"Sound",
  "mxp":"MXP"
}

Char.Status

Sent by server immediately after the initial Char.StatusVars message and whenever the value of a variable changes.
Contains the values of character status variables (level, race, etc).
The full list of variables is only sent with the initial message, subsequent messages only contain changed variables.
Message body is an object with keys containing the names of the variables, as defined by the Char.StatusVars message, and values containing the values of the variables.

Example:

Char.Status {
  "character_name":"Xiphling",
  "affects":{
     "bless":"47",
     "armor":"47",
     "boost":"128"
  },
  "experience_tnl":"1000",
  "experience_tnl_max":"1000",
  "health":"1641",
  "health_max":"1641",
  "level":"51",
  "sublevel":"101",
  "race":"Human",
  "class":"Warrior",
  "mana":"204",
  "mana_max":"204",
  "practice":"669",
  "gold":"64",
  "movement":"954",
  "movement_max":"954",
  "hitroll":"22",
  "damroll":"16",
  "ac":"8",
  "str":"29",
  "int":"23",
  "wis":"23",
  "dex":"23",
  "con":"23",
  "str_perm":"14",
  "int_perm":"13",
  "wis_perm":"13",
  "dex_perm":"13",
  "con_perm":"13",
  "area_name":"{ 1   4} Crom    The Meadow",
  "room_exits":{
     "North":"O",
     "East":"O",
     "South":"O",
     "West":"O"
  },
  "room_name":"West Side of Tree of Knowledge"
}

Char.Vitals

Sent by server whenever a prompt is displayed to the player.
Contains basic information about character attributes (hp, mana, etc).
Message body is an object containing key-value pairs corresponding to character attributes.
Each variable is also included in a string in the format name:cur/max.

Example:

Char.Vitals {
  "hp":"1641",
  "maxhp":"1641",
  "mp":"204",
  "maxmp":"204",
  "mv":"954",
  "maxmv":"954",
  "wgt":"31",
  "tnl":"1000",
  "maxtnl":"1000",
  "maxwgt":"950",
  "items":"4",
  "maxitems":"205",
  "string":"HP:1641/1641 Mana:204/204 Mv:954/954 TNL:1000/1000 Wgt:31/950 Items:4/205"
}

Comm.Channel.List

Sent by server after a successful login and when new channels become available.
Contains a list of communication channels available to the player.
Message body is an array of objects, each object representing one channel.
Each object has keys "name", "caption" and "command" - name is internal name, caption is player-visible name, command is command used to communicate over this channel.

Example:

Comm.Channel.List [
  { "name":"ask", "caption":"Ask", "command":"ask" },
  { "name":"auction", "caption":"Auction", "command":"auction" },
  { "name":"chat", "caption":"Chat", "command":"chat" },
  { "name":"grtz", "caption":"Grtz", "command":"grtz" },
  { "name":"joke", "caption":"Joke", "command":"joke" },
  { "name":"music", "caption":"Music", "command":"music" },
  { "name":"newbie", "caption":"Newbie", "command":"newbie" },
  { "name":"quest", "caption":"Quest", "command":"quest" },
  { "name":"shout", "caption":"Shout", "command":"shout" },
  { "name":"yell", "caption":"Yell", "command":"yell" },
  { "name":"eslchat", "caption":"ESLChat", "command":"eslchat" },
  { "name":"buddy", "caption":"Buddy", "command":"buddy" },
  { "name":"hero", "caption":"Hero", "command":"hero" },
  { "name":"lord", "caption":"Lord", "command":"lord" }
]

Comm.Channel.Players

Sent by server in response to Comm.Channel.Players from the client.
Contains a list of players and the channels they currently have enabled.
Message body is an array of objects with each object describing a player and the channels they currently have enabled.
Each object has keys "name", which is the name of the character, and "channels", which is an array of channel names.

Example:

Comm.Channel.Players [
   {
      "name":"Xiphling",
      "channels":[
         "newbie",
         "yell",
         "hero"
      ]
   },
   {
      "name":"Xiphoid",
      "channels":[
         "ask",
         "auction",
         "chat",
         "grtz",
         "joke",
         "music",
         "newbie",
         "quest",
         "shout",
         "yell",
         "eslchat",
         "buddy",
         "hero",
         "lord"
      ]
   }
]

Comm.Channel.Text

Sent by server when a message is sent to a communications channel.
Message body is an object with the fields "talker", "channel" and "text" - talker is the person sending the message to the channel, channel is the channel receiving the message and text is the complete text of the message.

Example:

Comm.Channel.Text {
   "channel":"chat",
   "talker":"Xiphling",
   "text":"Xiphling chats 'Hello world!'"
}

Room.Info

Sent by server when player enters a room.
Message body is an object containing information about the room. Keys are as follows:
- name - name of the room.
- zone - the area containing the room.
- environment - the environment of the room.
- exits - object containing exits, each key is a direction and values may be one of "O" (open) or "C" (closed).
- details - array which may contain the following strings: dark, underwater, water, infirmary, anti-magic, lloydable, norecall, noquit, pet shop, bank, locker.

Example:

Room.Info {
  "name":"Approaching Wayward Marina, Unofficial \"Bank\"",
  "zone":"{23  30} Zahri   Mervue",
  "environment":"city",
  "exits":{
     "North":"O",
     "South":"O"
  },
  "details":[
     "bank"
  ]
}

Room.Players

Sent by server when player enters a room.
Describes players and mobs in the room.
Message body is an object with keys containing either unique mob serial numbers or player names and values containing objects describing the player or mob.

Example:

Room.Players {
  "Xiphling":{ "name":"Xiphling", "fullname":"(White Aura) Xiphling is here." },
  "4525":{ "name":"4525", "fullname":"A kobold giggles then commences to fart in your direction." },
  "4520":{ "name":"4520", "fullname":"A kobold drools as it takes a grab for your arm." }
}

Room.AddPlayer

Sent by server when a player or mobile enters the room.
Message body is the same as for Room.Players.

Example:

Room.AddPlayer { "4537":{"name":"4537", "fullname":"A kobold giggles then commences to fart in your direction."} }

Room.RemovePlayer

Sent by server when a player or mobile leaves the room.
Message body is the unique player name or mobile serial number.

Example:

 Room.RemovePlayer "4537"

Room.WrongDir

Sent by server when the player tries to leave the current room in an invalid direction.
Message body is a string indicating the invalid direction.

Example:

Room.WrongDir "west"