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.

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

While a super will fire if a sub event is sent, That does not mean that all the data on the super is updated, or indeed, available.

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

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:

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

Note! I do not recomment method 2 unless you are very experienced with Lua and event programming. This is because it is VERY easy to get into a state where the handler will fire multiple times.

Event Handler from the GUI AnonymousEventHandler

CMUD Specific

To use GMCP in CMUD, you use Triggers,

Make a new trigger
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)
Change the Trigger type to "GMCP"
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

Final Realms > GMCP Usage > image2020-9-22_22-15-34.png