Actions

GMCP

From Iron Realms Nexus Client Documentation

General MUD Telnet Protocol is a

Module and message names are not case sensitive. JSON key names are case sensitive.

Supported modules

  • Core - core functionality
  • Char - information about a character
  • Char.Skills - information about skills known by the player
  • Char.Items - information about items in inventory and room, with live updates
  • Comm.Channel - identification of communication channels and player lists
  • Room - various information about the current room
  • Redirect - redirect outpot to another window
  • IRE.Rift - IRE-specific, transmits information about the Rift contents
  • IRE.Composer - IRE-specific, used to edit bigger texts client-side
  • IRE.Wiz - used internally by the Nexus client
  • IRE.FileStore - used internally by the Nexus client
  • IRE.Misc - used internally by the fMUD and Nexus clients
  • IRE.Time.Update { "daynight": "120" }

Supported messages by modules

Core

Sent by client:

Core.Hello

  • Needs to be the first message that the client sends, used to identify the client
  • Message body is an object with keys "client" and "version", containing the client's name and version
  • Example: Core.Hello {"Client":"IRE-ChroMUD","Version":"2.7a1"}

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 Set, but appends the supported module list to the one sent earlier
  • If no list was sent yet, the behaviour is identical to 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 Set
  • Example: Core.Supports.Add [ "Char 1", "Char.Skills 1", "Char.Items 1" ]

Core.Supports.Remove

  • Removes specified modules from the list of supported modules
  • Message body format is similar to Set, except that module version numbers are optional and ignored if given
  • Example: Core.Supports.Remove [ "Char", "Char.Skills", "Char.Items" ]

Core.KeepAlive

  • Causes the server to reset the timeout for the logged character, no message body

Core.Ping

  • causes the server to send a Core.Ping back
  • message body is a number which indicates average ping time from previous requests, if available
  • Example: Core.Ping 120

Sent by server:

Core.Ping

  • Sent in reply to Core.Ping. No body.

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 "Goodbye, adventurer"

Char

Sent by client:

Char.Login

  • Used to log in a character, only interpreted if no character is logged in for that connection
  • Message body is an object with keys "name" and "password"
  • Example: Char.Login { "name": "somename", "password": "somepassword" }

Sent by server:

Char.Name

  • Sends the character name and full name which includes the title. This is only sent on login.
  • Example: Char.Name { "name": "Olad", "fullname": "Neophyte Olad" }

Char.Vitals

  • Basic character attributes such as health, mana, etc.
  • Message body is an object containing several variables
  • Additionally, each variable is included in a string, in the format name:cur/max
  • Interpretation of the variables is game specific
  • It is generally safe to assume that the known values are numbers (even though encoded as strings), but other datatypes can be present
  • The "charstats" attribute, if present, holds a list of strings that the client may choose to display to the player in a client-specific way, these hold information about the character state that the game wishes to show to the player
  • Example: Char.Vitals { "hp": "4500", "maxhp": "4800", "mp": "1200", "maxmp": "2500", "ep": "15000", "maxep": "16000", "wp": "14000", "maxwp": "15000", "nl": "10", "string": "H:4500/4800 M:1200/2500 E:15000/16000 W:14000/15000 NL:10/100" }

Char.StatusVars

  • Sent by server after a successful login or after the module is enabled
  • Contains a list of character variables (level, race, etc)
  • Message body is an object
  • Each object element is a name-caption pair, name is the internal name and caption the user-visible one
  • Example: Char.StatusVars { "level": "Level", "race": "Race", "guild": "Guild" }

Char.Status

  • Values of character values defined by StatusVars.
  • A full list is sent by server right after StatusVars, and changes are sent in subsequent messages as they occur.
  • With the exception of the initial Status message, messages only contain changed values; if a variable is not included, it has not changed since the previous Status message.
  • Message body is an object.
  • Each object element is a name-value pair, name is the internal name defined by the StatusVars message and value is the variable value.
  • Example: Char.Status { "level": "58", "city": "Antioch" }

Char.Skills

Sent by client:

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": "elemancy", "name": "firelash" }

Sent by server:

Char.Skills.Groups

  • groups of skills available to the character
  • sent by server on request or at any time (usually if the list changes)
  • for IRE games, groups are skills like Survival or Elemancy
  • message body is an array of strings, each being one name
  • example: Char.Skills.Groups [ "Survival", "Perception", "Elemancy", "Crystalism" ]

Char.Skills.List

  • list of skills in a group available to the character
  • sent by server on request only
  • for IRE games, this is the list visible on AB <skillname>
  • message body is an object with keys "group" and "list", where group is the group name as a string
  • the list value is an array of strings, each being the name of one skill
  • example: { "group": "Elemancy", "list": ["Light", "Stoneskin", "Firelash"] }

Char.Skills.Info

  • information about a single skill, only sent upon request
  • message body is an object, keys are "group", "skill", and "info", values are strings
  • group and skill identify the request, info is a description (usually multi-line) of the skill's functionality and usage
  • Example: Char.Skills.Info { "group": "Elemancy", "skill": "Firelash", "blah blah" }

Char.Items

Sent by client:

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.Item.Contents 12345

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 ""

Sent by server:

Char.Items.List

  • list of items at a specified location (room, inv, held container)
  • message body is an object with keys "location" and "items"
  • location value is a string, "inv", "room", or "repNUMBER" - the last one is container identification
  • items value is an array, whose each item is an object with keys "id", "name" and optionally "attrib"
  • id is a number identifying the item, name is a string containing a short player-visible item description
  • attrib is a string consisting of characters describing item properties:
    • "w" = worn,
    • "W" = wearable but not worn
    • "l" = wielded
    • "g" = groupable
    • "c" = container
    • "t" = takeable
    • "m" = monster
    • "d" = dead monster
    • "x" = should not be targeted (guards, ...)
  • Example: Char.Items.List { "location": "room", "items": [ {"id": 54685, "name": "an apple"}, {"id": 85462, "name": "a tiny worm"}] }

Char.Items.Add

  • informs the client about an item being added to the specified location
  • message body is an object with keys "location" and "item"
  • location is same as with List, item is an object with the same structure as one item from the items array of List
  • Example: Char.Items.Add { "location": "room", "item": { "id": "239602", "name": "an elegant white letter", "icon": "container", "attrib": "c" } }
  • Example: Char.Items.Add { "location": "room", "item": { "id": "303060", "name": "a gold nugget", "icon": "commodity" } }
  • Example: Char.Items.Add { "location": "inv", "item": { "id": "303060", "name": "a gold nugget", "icon": "commodity", "attrib": "t" } }

Char.Items.Remove

  • informs the client about an item being removed from the location
  • message body is an object with keys "location" and "item"
  • location is same as with List, item is an integer value identifying the item
  • Example: Char.Items.Remove { "location": "room", "item": { "id": "239602", "name": "an elegant white letter", "icon": "container", "attrib": "t" } }
  • Example: Char.Items.Remove { "location": "inv", "item": { "id": "303060", "name": "a gold nugget", "icon": "commodity" } }

Char.Items.Update

  • informs the client about an item's attributes being changed - only sent for inventory items
  • message body syntax the same as with Add
  • Example: Char.Items.Remove { "location": "room", "item": 123988 }

Comm.Channel

Sent by client:

Comm.Channel.Players

  • request for the server to send Comm.Channel.Players
  • no message body

Sent by server:

Comm.Channel.Players

  • list of players and organizations (city, guild, ...) that they share with this player
  • message body is an array with each element describing one player
  • each element is an object with keys "name" and "channels", name is a string, channels is an array
  • the channels array may be omitted if empty; if given, it is a list of organization names
  • example: Comm.Channel.Players [{"name": "Player1", "channels: ["Some city", "Some guild"]}, {"name": "Player2"}]

Comm.Channel.List

  • list of communication channels available to the player, sent on login/negotiation and if changed
  • 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":"ct", "caption":"Some city", "command":"ct"}, {"name":"gt", "caption":"Some guild", "command":"gt"}]

Comm.Channel.Start

  • informs the client that text that follows is something said over a communication channel
  • message body is a text containing the channel name
  • for tells from/to another player, the channel name is "tell Name"
  • Example: Comm.Channel.Start "ct"
  • Example: Comm.Channel.Start "tell Player1"

Comm.Channel.End

  • ends a channel text started by Comm.Channel.Start
  • message body is a text containing the channel name

Room

Sent by server:

Room.Info

  • Contains information about the room that the player is in. Some of these may be IRE-specific
  • Message body is an object with the following keys
  • "num" - number identifying the room
  • "name" - string containing the brief description
  • "area" - string containing area name
  • "environment" - string containing environment type ("Hills", "Ocean", ...)
  • "coords" - room coordinates (string of numbers separated by commas - area,X,Y,X,building, building is optional
  • "map" - map information - URL pointing to a map image, followed by X and Y room (not pixel) coordinates on the map
  • "details" - array holding further information about a room - shop,bank,...
  • "exits" - object containing exits, each key is a direction and each value is the number identifying the target room
  • Example: Room.Info {"num": 12345, "name": "On a hill", "area": "Barren hills", "environment": "Hills", "coords": "45,5,4,3", "map": "www.imperian.com/itex/maps/clientmap.php?map=45&level=3 5 4", "exits": { "n": 12344, "se": 12336 }, "details": [ "shop", "bank" ] }

Room.WrongDir

  • Sent if the player attempts to move in a non-existant direction using the standard movement commands
  • Upon receiving this message, the client can safely assume that the specified direction does not lead anywhere at this time
  • Message body is a string with the name if the non-existant exit
  • Example: Room.WrongDir "ne"

Redirect

Sent by server:

Redirect.Window

  • Specifies a window to redirect further input to
  • Message body is a string specifying the window to redirect to
  • The main window is referred to as "main", and is the default if the message body is omitted or empty
  • Example: Redirect.Window "map"

IRE.Rift

Sent by server:

IRE.Rift.List

  • contents of a Rift storage
  • sent upon receiving the IRE.Rift.Request message
  • message body is an array, with each element being an object containing three keys - "name" is item name, "amount" is a number holding the item's amount, and "desc" is user-visible description

IRE.Rift.Change

  • sent whenever the item amount in a Rift changes
  • message body is an object with the same structure as one element of an array sent with the IRE.Rift.List message

Sent by client:

IRE.Rift.Request

  • asks the server to send the Rift contents using the IRE.Rift.List message

IRE.Composer

Sent by server:

IRE.Composer.Edit

  • sent by the server when the player enters an in-game editor. Body is an object, with keys "title" and "text". Text contains the current buffer, title is a title that can be shown to the user.

Sent by client:

IRE.Composer.SetBuffer

  • Sent by the client upon successfully editing a text which was sent to the client in an IRE.Composer.Edit message earlier
  • Sending this message only changes the edit buffer, but does not end the editing session
  • on IRE games, the client may send the command *save to save a text, or command *quit to abort editing (IRE.Composer.SetBuffer is not sent in this case) - this behaviour is IRE-specific and is one of the reasons why the Composer module is in the IRE namespace