Introduction

GMCP is handlet a little bit differently in different clients. E.g. in CMUD it is considered an event, and is handled with event handlers. While in CMUD it is considered a special form of trigger. Also access to the properties are not always the same.

Both clients will "cache" previous values, so this is important when it comes to gmcp objects where the contents/properties change pr fire.

Below i will try to create examples for common use cases in Mudlet and CMUD.

General Best Practice

Use Small, specialized event handlers and triggers

It is recommended best practice to make the event handlers as small as possible, reacting to the "lowest possible" sub module because of this. Also that the handler only uses data from its own "node" and "downwards"

Example:

• You do not want to make a handler for gmcp.Char as the submodules below this fire at completely different intervals and events. Also there is no guarantee that all data in gmcp.Char is available at this time
• Rather make separate handlers for gmcp.Char.Vitals and gmcp.Char.Effects
  • In these handlers, don't access other trees like gmcp.Char.Spells or gmcp.Char.Status

In the event/trigger, use only data from the relevant submodule

For the same reasons above, it is important that each handler only has awareness of the data "below it". Otherwize you will quickly encounter crashes or missing data due to the sparse nature of the protocol. If you need data from other parts of the tree, use Caching.

Example:

• In your gmcp.Char.Vitals handler, do not use the gmcp.Char.Status.name variable
• In your gmcp.Group.Party handler, do not use the gmcp.Char.Vitals.hp variable

Use caching when persistance/global access is needed

It is common that you want to access data from other parts of the gmcp tree in one of the handlers. E.g. you might want to access gmcp.Char.Status.name inside gmcp.Group.Party, or from within the gmcp.Action.Round.

As this can easily cause crashes and undeterministic behaviour due to the sparseness of the data, it is therefore recommended that for such use cases, you cache the inbound data to a global variable/hierarchy.

Note that this is primarily a challenge when communicating across trees, and less of a problem when navigating upwards in the same tree. However, the protocol does not enforce update of a super object when a child is sent, so consider this a general best practice!

Example:

• in your gmcp.Char.Status handler, you store the gmcp.Char.Status.name to a globally accessible variable Char.name
• in your gmcp.Char.Vitals handler, if you need the character name, you use Char.name instead of gmcp.Char.Status.name

Don't drive GUI updates directly from the gmcp handlers

As you don't have control over the frequency of the gmcp events, it is generally a bad practice to have the gmcp handler update gui objects like gauges, buttons or screens. 

Example: 

• If you use the gmcp.Char.Vitals.hp to update a HP indicator in your GUI, it is recommended that the gmcp handler stores the value, and that you have cyclic update of the GUI component, e.g. via timers.

Make your handler "light weight"

To prevent lagging your client, it is recommended that you handler "does as little as possible", generally store the data, then move on. Then do heavier tasks on the data in cyclic processes outside of the event itself.

Mudlet Specific

How to "look at" the gmcp objects

You can use the "display" command to output the full, or parts of the gmcp tree, or print/echo to print out a single property.

Examples:

• lua display(gmcp.Char)
• lua print(gmcp.Char.Vitals.hp)

How to react to a gmcp object

In Mudlet, a gmcp packet is considered an event. The events are named with dotted syntax. e.g. gmcp.Room or gmcp.Char.Vitals

Note that capitilization is important.

A "sub handler" will only fire on the specific event, while a "super" will fire on all sub events. E.g.

• a handler tied to "gmcp.Char" will fire on gmcp.Char, gmcp.Char.Vitals and gmcp.Char.Effects
• a handler tied to "gmcp.Char.Vitals" will NOT fire on gmcp.Char.Status or gmcp.Char.Effects

There are two main ways to setup handlers for events in Mudlet. I recommend reading the documentation for the Mudlet Event_Engine for details, but i will brifely describe the methods here:

1. Set up a method as an event handler in the GUI (easiest, but only allows one handler pr script)
   • Create a new script
   • Give it a name, e.g. "onGmcpCharVitals"
   • in the script, create a function with the same name, eg function onGmcpCharVitals()
   • Add the event name to the "Add user Event Handler" (e.g. gmcp.Char.Vitals) and click the "+" button, so that the event name is pushed up to the "Registered Event Handlers"
2. NOT RECOMMENDED -  Use an AnonymousEventHandler (this is somewhat more complex to do right, but allows multiple handlers in the same script), e.g. 

   • handlerId = registerAnonymousEventHandler("gmcp.Char.Vitals", "processCharVitals")

   • Note! make sure to save the handlerid, and check for its existance before you register a handler when usign this method, otherwize you might get multiple fires pr event

CMUD Specific

To use GMCP in CMUD, you use Triggers,

1. Make a new trigger
2. Set its pattern to the gmcp module name you are interested in, e.g. "Char.Vitals" (This means the trigger will automatically fire when the mud sends updated vitals)
3. Change the Trigger type to "GMCP"
4. In the script part, you can now access the variables directly using %gmcp.Char.Vitals.hp, e.g.
   • #VAR hp %gmcp.Char.Vitals.hp
   • or
   • hp = %gmcp.Char.Vitals.hp