GMCP Documentation and API

General discussion about the Genesis Web Client located at

Moderator: Eowul

Forum rules
- Use common sense and be respectful towards each other at all times, even when disagreeing.
- Do not reveal sensitive game information. Guild secrets, player seconds are examples of things not allowed.
User avatar
Site Admin
Posts: 3131
Joined: 04 Mar 2010 04:36

GMCP Documentation and API

Post by Cherek » 25 Jan 2015 15:33

Script API

Code: Select all

Within Javascript based triggers and aliases, you can interact with the mud and the client using the gwc object.

gwc.connection.send(output, [resolve aliases])

Send command to Genesis. Supply true as the second argument to enable alias resolving.

gwc.output.color(foreground, background)

Changes the color of the last line received from the mud. You can omit the background color argument if you do not want to change it.


Adds a new line to the output window with the specified text.

gwc.output.replace(searchvalue, newvalue. [use html])

Perform a string replace on the last output line of the mud. Replace uses a string replace on either the html or text value (depending on the third argument).


Object available to store information. All data contained is persisted to the server and will be available as soon as you login.

Note that the userdata object is persisted after the scripts have fired. If you adjust the contents of the userdata object outside of this (for instance by using a setTimeout), it will not be stored until a new trigger has fired.

Object containing the stored GMCP information. This object is automatically updated as new information is received. However, in case of GMCP triggers the new data has not yet been applied (the newest data can be accessed through the 'args' variable.)

| data.character.statusvars | Mapping of variables to readable names | | data.character.status | Contains the latest values of the variables | | data.character.vitals | Contains the latest readings for your character's vitals | | | Contains the information about your current room |

For more information about GMCP, see the documentation

Code: Select all

Generic Mud Communication Protocol
Genesis supports the Generic Mud Communication Protocol, or GMCP, to pass easily parsable information to your mudclient. It's an extension to the normal telnet protocol, and sends messages invisible to the user (even when running a client that do not support GMCP).

The primary purpose of GMCP is to improve the availability of information relevant to your game without providing players with a distinct advantage. As such, any information passed through the protocol will have the same precision / textual representation as through the normal text interface.

At the moment of writing, the Mudlet and CMud client (as of version 3.22) support the GMCP protocol. This only includes the handling of the messages and a variety of the core features that subscribe to the broad- casts provided by the mudlib. It is up to the player to add trigers and or other scripts to use the provided information.

GMCP Messages are formed of a package name, and an optional JSON payload separated by a space. Normally the mud client will handle the parsing and will provide the information in it's native format to the scripts. For exact details, you will need to look into the documentation of your mud- client.

Broadcasts are only sent when you are subscribed to the packages to which they belong. Packages names follow a parent -> child format, which each level separated by a dot. If you subscribe to the Core package, you will receive all broadcasts for packages that start with Core, if you were to subscribe to Core.Subpackage, you would only get those and it's children.

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

Core Broadcasts

    Send upon disconnect. Payload is a string detailing the reasons
    for the disconnect.

Char Broadcasts

    Send upon subscription to the Char package, contains and object
    as payload where each key value pair contains the technical key
    (used in Char.Status) and a text value containing a more humanly
    readable caption.

    Example: { "level" : "Level", "race" : "Race" }


    Upon subscription to the Char package, an initial set of status
    variables is sent. After this initial broadcast, subsequent 
    broadcasts will only contain changed variables.

    Example: { "level" : "myth", "name" : "Eowul", "race" : "elf" }

    At the time of writing, the following status variables are 

    	name, level, gender, race, strength, constitution, 
    	discipline, intelligence, dexterity or wisdom, alignment,


    Similar to the status broadcast, the initial broadcast will 
    contain all initial values, subsequent broadcasts include only
    the updated values.

    Example: { "health" : "very hurt", "mana" : "in full vigour" }

    Currently the following information is included in the vitals

        food, drink, fatigue, mana, health, intoxication

Client commands

    First message send after GMCP has been negotiated. Payload is an
    object, containing the keys "client" and "version".

    Example: { "client" : "GMC", "version" : "1.0.1" }


    Commands to subscribe to the various broadcasts offered by the
    mudib (see supported packages), the payload is an array with
    strings, containing the packages and versions. 

    Example: [ "Core 1", "Room 1" ]

    If the version number is ommited, version 1 is assumed. The set
    command replaces the previous list of subscribed packages. Add
    adds the new packages to the existing list, overwriting the
    version of existing modules with the new one supplied (even if
    it is lower than the existing version). 

    You can unsubscribe from broadcasts using the Core.Supports.Remove
    command. Version numbers are optional and will be ignored when


    Check to see if the server is still responding. A Core.Ping
    message will be sent in reply, containing no payload.


    Only valid while no user is logged in. Contains an object as
    payload with keys name and password. Upon successfull validation
    of the credentials, the user is logged in.

    Example: { "name" : "Eowul", "password" : "topsecret" }


    Request an up to date skill-list for the logged in player. Data
    is returned based on the parameters given.

    When no parameters are supplied, a list of all known skill-
    groups is returned using the Char.Skills.Groups package name and
    containing an array of strings as the payload.

    Example: [ "General", "Weapon" ]

    In order to get the skills for a specific group (or using 'All'
    to get all available skills regardless of group), supply an 
    object as the commmands payload, using 'group' as key and the
    group name as value. This will return a list of skills and their
    values through the Char.Skills.List package. The payload is an
    object with the group name repeated with the 'group' key, and
    the list of skills (another object) using the 'list' key.

    Example: { "group" : "General",
               "list" : { "appraise object" : 10, 
                          "appraise value" : 15 }}

    Unlike most other commands, the numerical value of the skill is
    returned as there is a one to one mapping with it's textual 

    Should you only be interested in the values of a single skill, 
    you can supply an object as payload with both a group and a name
    key, and the skill data will be returned using the 
    Char.Skills.Info packagename, with an object as payload, containing
    the group, name, info and value keys.

    Example: { "group" : "General", "name" : "appraise object",
               "info" : "appraise object", "skill" : 15 }

Posts: 62
Joined: 12 Jan 2013 18:03

Re: GMCP Documentation and API

Post by Mercade » 07 Feb 2015 17:38

The levels for health, mana and fatigue were hard-coded into the client in order to provide the health bars.
This has now been made dynamic as it turned out that skipping to 0 for "feeling well" was not conducive to the mental health of users.
Consequently, the following packages are now supported.

Code: Select all


    Request an up to date list of the possible levels for vitals. Data is
    returned based on the parameters given.

    When no parameters are given, a list of all supported vitals is returned
    using the Char.Vitals.List package and containing an array of strings as
    the payload.

    Example: [ "health", "mana" ]

    In order to get the levels for one more more vitals, it accepts a single
    vital, an array of vitals or "All" to get the full list, which will be
    sent with the package Char.Vitals.Levels. The payload is an object with
    as keys the vitals, and an array of the levels as argument.

    Example: { "health" : [ "death's door", ... "feeling very well" ],
               "mana" : [ ... ] }

The latest technical description can be found in game under "help gmcp_tech".

Posts: 62
Joined: 12 Jan 2013 18:03

Re: GMCP Documentation and API

Post by Mercade » 07 Feb 2015 17:40

Upon character creation, a package is sent as follows:

Code: Select all

Char Broadcasts

    Sent upon creation of a character. It contains the name of the player.

    Example: { "name" : "Eowul" }

Posts: 62
Joined: 12 Jan 2013 18:03

Re: GMCP Documentation and API

Post by Mercade » 13 Mar 2015 22:14

The GMCP interface for maps has been changed. The complete ASCII map is now passed with GMCP, along with the coordinates. This way the client doesn't have to rely on the maps being available before from a certain location. For this Room.Info has been amended with the coordinates. This is called when the player moves to another room.

Code: Select all


    Upon subscription of the Room package it will send information about the
    environment the player is in. The payload for each room is an object with
    the following keys:

    id    - A unique identifier for the room. This will remain static as long
            as the code of the room isn't moved.
    short - The short description of the room.
    exits - An array listing the exits of the room.
    doors - An array listing the exits of the room reachable through a door.
    x, y  - Coordinates of the room on the map. Omitted if the room isn't on
            the map. Note x=0 will never happen, so you can test for that.
            The zoomx, zoomy are only given if there is a zoomed map.

    Example: { "id" : "iX5PnH",
               "short" : "A pond with a waterfall.",
               "exits" : [ "up", "east" ],
               "doors" : [ "north" ],
               "x" : x, "y" : y, "zoomx" : zoomx, "zoomy" : zoomy }

In addition, a new Room.Map has been created, that is called whenever the player moves to a new section of the map.

Code: Select all


    This package is sent when a player enters into a new map area. It contains
    the map graphics and optionally the zoomed map graphics.

    Example: { "map"  : "map graphics",
               "zoom" : "zoomed map graphics" }

Note, the Room.Map is NOT called when the player moves to an area that isn't covered by the Map. Whether the player is on the map can be determined by the Room.Info.X being positive (X=0 will not happen on maps). The presence of the zoom function can be determined by the Room.Info.zoomx being positive.

Posts: 62
Joined: 12 Jan 2013 18:03

Re: GMCP Documentation and API

Post by Mercade » 15 Mar 2015 12:47

Information about the team you are in is now available through the Char.Team package:

Code: Select all


    This will send information about the team you are in. If you are not in
    a team (anymore) it sends an empty package { }. The following info is sent:
    - leader  - the name of your leader, or "You" if you are the leader.
    - members - the names of the members of the team. If you are a member,
                it does not include yourself (only your team mates).
    - follow  - "follow" or "stay", depending on the leader's instructions.

    Example: { "leader" : "You", "members" : [ "Eowul" ], "follow" : "stay" }
             { "leader" : "Eowul", "members" : [ ], "follow" : "follow" }

See 'help gmcp_tech' for the full documentation on the GMCP packages.