GMCP triggers

Posted by Kyle Hankinson June 16th, 2026

GMCP triggers

GMCP (Generic MUD Communication Protocol) lets a MUD send your client structured data out of band: your health, the current room, your inventory, and more. Instead of scraping that information out of the text on screen with fragile regular expressions, you can react to the data directly and reliably.

This post covers how to fire a trigger when a GMCP value changes, and how to read the data with getGMCP.

Enabling GMCP

GMCP is enabled per connection and is on by default. You can toggle it in the connection editor. Two console commands help while you work:

#gmcp

Prints every GMCP value the MUD has sent so far, as formatted JSON. This is the quickest way to discover what your MUD exposes and the exact key names to match against.

#enableGMCP

Re-negotiates GMCP with the server if it was turned off.

How GMCP data is keyed

The client flattens each GMCP package into dotted paths. If the MUD sends:

Char.Vitals { "hp": 100, "maxhp": 120, "mana": 50 }

the client stores:

Char.Vitals.hp    = 100
Char.Vitals.maxhp = 120
Char.Vitals.mana  = 50

Nested objects keep extending the path, so Room.Info { "name": "Town Square", "exits": { "north": "101" } } becomes Room.Info.name and Room.Info.exits.north.

Creating a GMCP trigger

In the trigger editor, set the match type to "variable updated (including GMCP)". The trigger's pattern is then a GMCP path, not a regular expression, and the trigger fires whenever the value at that path changes.

For example, a trigger with the pattern:

Char.Vitals.hp

fires every time your health changes. To watch several paths with a single trigger, separate them with a pipe:

Char.Vitals.hp | Char.Vitals.mana

Matching is case-insensitive by default.

Reading the value with getGMCP

When a GMCP trigger fires, the path that changed is available as \0, and you read values with getGMCP:

  • getGMCP('Char.Vitals.hp') returns the single value (for example 100).
  • getGMCP('Char.Vitals') returns an object with everything under that branch: { hp: 100, maxhp: 120, mana: 50 }.

Example: low-health warning

Match type variable updated (including GMCP), pattern Char.Vitals.hp:

var hp  = getGMCP('Char.Vitals.hp');
var max = getGMCP('Char.Vitals.maxhp');

// Show current health in the app icon badge.
badge(hp + '/' + max);

if (max && hp / max < 0.25) {
    log('Warning: health is low (' + hp + '/' + max + ')');
    beep();
}

Example: show the current room in the status bar

Match type variable updated (including GMCP), pattern Room.Info.name:

status('Room: ' + getGMCP('Room.Info.name'));

Tips

  • Run #gmcp first to see exactly which packages and key names your MUD sends. Field names (for example hp versus maxhp) vary between MUDs.
  • A GMCP trigger matches on the path, not the value, so the action runs on every change. Use getGMCP inside the action to read the current value and decide what to do.
  • Because the data is structured, a GMCP trigger is almost always more reliable than a text trigger for anything the MUD reports over GMCP (health, room, inventory).
  • See the Functions post for getGMCP and setGMCP, and the Scripts post for sharing helper functions across triggers.
Tags: Scripting