|
|
 |
|
|
GMCP (Generic MUD Communication Protocol) is a MUD protocol. It's purpose was to take the ideas of the IRE ATCP protocol and make it generic enough for other MUDs to use. Some people call it ATCP2, but the protocol itself is much more generic than that. It basically just passes a set of messages between the client and server with the data in JSON string format.
GMCP Overview
GMCP defines "messages" within "packages". The general syntax is:
Package.Message JSON-Data
Subpackages are allowed with the format: Package.SubPackage.Message JSON-Data
Package and message documentation is currently available for IRE MUDs (Achaea, Imperian, etc) and for Aardwolf.
Package negotiation
GMCP is enabled by default in CMUD. It can be disabled in the Preferences. The old "Simutronics" preference page has been renamed "Protocols" and a new tab for GMCP has been added. In that Preference screen you can list which packages you want the MUD to enable and send you data for. Each package is on a separate line with the Package.Subpackage name, followed by the numeric version of the package you want to enable. By default, CMUD enables:
Core 1
Char 1
Room 1
Comm 1
IRE.Composer 1
Simply edit this list of packages to include whatever GMCP package you wish to receive.
Accessing GMCP data
When CMUD receives GMCP data, it gets stored in a single large internal table accessed via the %gmcp variable. The format of the %gmcp variable is:
%gmcp.package.message.key
For example, if you look at the IRE documentation, you'll see that the Room.Info package sends various information about the current room. To retrieve the current room Name, you would use:
#SHOW %gmcp.Room.Info.name
easy and simple.
GMCP Triggers
Similar to MXP triggers, the Pattern for the trigger is tested against the Package.SubPackage.Message packet sent by the MUD. When a message matching your trigger is received, your trigger is fired and has access to the %gmcp array just like in any other script. However, the following variables are also set for use in your trigger:
%gmcp.module : main package name
%gmcp.package : actually the subpackage
%gmcp.message : the name of the message
%gmcp.data : the data received for this package as a database variable/string list
%gmcp.olddata : the previous data for this message
%0 : the raw string value received with the message. Should normally be a JSON string
If the data sent by the MUD does not parse as proper JSON, the raw string is stored within the %gmcp_errors.package.subpackage.message array. This can be used for trouble-shooting MUD GMCP implementations.
Keep in mind that the specific GMCP messages are typically MUD-specific. However, CMUD doesn't care what packages and what messages are sent. It just fires your GMCP triggers and stores all of the data in the %gmcp table. So it's very "Generic" as per the GMCP spec.
A GMCP trigger can be either "Trigger on Prompt" or "Trigger on Newline". While these names don't mean much for GMCP, they do create a difference that you can take advantage of. A GMCP trigger with "Trigger on Prompt" set will fire before CMUD does anything with the raw GMCP data. For example, you can capture the Room.Info message before the CMUD mapper does anything with it. A GMCP trigger with "Trigger on Newline" fires *after* CMUD has processed the GMCP data. For the Room.Info messages, the mapper will have already moved to the proper room, or created the proper room before calling your GMCP Room.Info trigger.
Overridding Package negotiation
There is a special package.message called "core.hello" that you can create a GMCP trigger for. This is the initial message sent by CMUD to the MUD when the MUD first asks the client for GMCP support. As per the IRE spec linked above, CMUD normally sends the "core.hello" message with CMUD as the client name and the current CMUD version. CMUD then sends the list of desired packages (defined in your preferences screen) via the "core.supports.set" message.
If you are connecting to a MUD that needs a different handshake protocol, simply create a GMCP trigger with the "Trigger on Prompt" option set for the core.hello message. Within this trigger you can use the #SENDGMCP command to send whatever data you want to the server. The format of the #SENDGMCP command is:
#SENDGMCP "Package.Message" @Table
where @Table is a normal CMUD database variable or string list with the data you want to send. This data will be converted to the correct JSON format needed by GMCP. For example, to emulate the current "core.hello" response, you would do this in your GMCP trigger:
| Code: |
$response = ""
#addkey $response client "CMUD"
#addkey $response version "3.22"
#SENDGMCP "core.hello" $response
$list = {core 1|char 1|room 1|comm 1}
#SENDGMCP "core.supports.set" $list |
Note that if you want to get to the really raw level you can use the #SENDSB command to send the raw telnet data, but then you'll need to do your own JSON parsing, so it's recommended to just use #SENDGMCP instead.
GMCP Mapper usage
The CMUD mapper uses the data send via the Room.Info GMCP package. The Name data is used for the room name, the Exits data is used to set the exits for the room, the Desc data is used for the room description, and the Num data is used for the vNum of the room on the map. No other GMCP data is currently used, but you are free to use the other data in your own GMCP trigger to set room colors based upon terrain type, or many other enhancements.
Since the actual Num field sent via GMCP might differ from the vNum stored in existing (old) maps, CMUD v3 has a feature to automatically update the vNum of rooms on your existing maps as you walk around in Map mode and Safe or Slow speedwalking mode. In Fast mode, the vNum will only update if you move one step at a time. In Safe mode you can actually double-click on the map to speedwalk and each room along the path will get its vNum updated.
A new flag is available in the Room Properties to determine if a room has had a proper vNum saved via GMCP and is also available via the %roomload function for scripting.
If the "Use vNum to match rooms" option is enabled in the Speedwalking page of the Map Properties, the mapper will use the Num data from GMCP to determine which room you are in on the map if CMUD can find a room with a matching saved vNum. You can turn this option off if you perform your own complex scripting of what room you are in.
In the Appearance Map properties you can enable the "Color rooms without Real vNum" to display the rooms that still need to have their vNum data updated via GMCP. You can change the color used for this feature in the Map Properties also.
The Mapper works so well with GMCP that players are encourage to re-walk their maps to get the correct vNum data set. This will make the mapper much more reliable and will make it much harder to get lost. |
| User comments |
| Nick Gammon: Tue Apr 07, 2015 9:22 am |
|
| Quote: |
| GMCP (Generic MUD Communication Protocol) is a MUD protocol developed over on www.mudstandards.org. |
Warning: mudstandards.org domain name has been abandoned by the original owners. It is now an adult products site (in Chinese). |
|
 |
| Vijilante: Wed Apr 08, 2015 12:45 am |
|
| Article edited. Are you aware of any site that still details the protocol? |
|
|
|
|
|
| Vijilante: Wed Apr 08, 2015 8:01 am |
|
Thank you Nick. I had to adjust link into the Web Archive by removing the second "http://". Firefox works at being smart and strips all the important stuff before it.
I also could not access anything beyond the first page of the topic. Do you happen to recall what changes came of the discussion after the first page? |
|
|
| Nick Gammon: Wed Apr 08, 2015 8:58 am |
|
| Quote: |
I also could not access anything beyond the first page of the topic.
|
Neither could I.
I've made a post knocking the first page into more readable form:
http://www.gammon.com.au/forum/?id=12834
If you think I've omitted anything important, or any links you would like added (eg. to more documentation on this site) let me know. |
|
|
| Vijilante: Fri Apr 10, 2015 12:56 am |
|
| Thank you again. I will put together more of the protocol information into a KB Article here. Could adjust your link for CMud references on the GMCP to http://forums.zuggsoft.com/modules/mx_kb/kb.php?mode=doc&k=3047 ? I think it is a little better to go directly to the KB article than a very old forum topic. I will also crosslink your forum topic in the new KB article for the protocol. |
|
|
| Nick Gammon: Fri Apr 10, 2015 4:00 am |
|
Done.
| Quote: |
I will also crosslink your forum topic in the new KB article for the protocol.
|
Thanks. I think my post has a bit more detail than the KB. I'm trying to make it easier for server-writers to interface with GMCP, which will benefit both CMud and MUSHclient. |
|
|
| Vijilante: Fri Apr 10, 2015 2:25 pm |
|
I added the entry for the GMCP protocol. I basically did a copy and paste of Zugg's original post and then made some small edits based on what I saw on your, Aardwolf's, and IRE's pages.
The regex was adjusted to allow hyphens and also requires a minimum of package.message.
I rephrased the requirements for UTF-8 encoding of string data. If I didn't quite get it to match what was arrived at from the discussion or should stress it more, then let me know.
Let me know if you see anything else that needs fixing or think it is all good. |
|
|
| Nick Gammon: Fri Apr 10, 2015 4:17 pm |
|
I fixed my page with regards to case-sensitivity. It appears that package names (like core.hello) are not case-sensitive, whereas JSON names (like "level") are.
I can't comment on the CMud parts of your post, but the rest looks pretty good. :) |
|
|
| Nick Gammon: Fri Apr 10, 2015 4:20 pm |
|
| Are there examples of package names with hyphens in them? I can't see your regexp, can you point to it? |
|
|
| Vijilante: Fri Apr 10, 2015 7:56 pm |
|
There are no examples of package name or messages with hyphen, but the original text says hyphens are allowed. All of the examples on all the pages appeared to specify a minimum of package.message. On that basis I used a regex of: [A-Za-z_][A-Za-z0-9_-]*(?:\.[A-Za-z_][A-Za-z0-9_-]*)+
I didn't put in anything CMud specific since I was just aiming to document the protocol. Just to be sure we are both talking about the same thing; the document attached to this topic is largely unchanged only the link to the defunct site was removed, a new document we created and is at http://forums.zuggsoft.com/modules/mx_kb/kb.php?page=&mode=doc&k=3049
I will add some statements about where case sensitivity matters. |
|
|
| Nick Gammon: Sat Apr 11, 2015 4:15 am |
|
Your previous post mentioned k=3047 not k=3049. I've amended my page, and fixed up the regexp. |
|
|
| Nick Gammon: Sat Apr 11, 2015 4:26 am |
|
| I've given a few MUSHclient-specific examples, simply because I think sometimes an example can save 1000 words of explanation. Feel free to give CMud examples on your page (or link to them) to save being hassled from client users about how to get specific things to work (like find their hit points). |
|
|
|
New commands