|
|
 |
|
|
GMCP (Generic MUD Communication Protocol) is a MUD protocol developed over on www.mudstandards.org. 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. |
|
New commands