====== Dune and GMCP ======

Generic Mud Communication Protocol (GMCP) is a way for Dune to send your MUD client extra information that isn't printed as game text. This is a helpful way to get extra context you can use for scripts and triggers. As a simple example, Dune can send a GMCP message to a GMCP enabled client when your character's health has changed so that you could automatically use a healing command.

===== GMCP Messages =====

Presently Dune only supports sending you GMCP messages as **output**. We do not support any GMCP **input** commands.

Some messages are sent whenever data changes, and will only contain the parts of the data that has changed since the last message. If you want to maintain a full picture of this kind of message's information you must store the data client-side as it arrives and update it over time. See the supported messages documentation that follows for more details.

==== Supported Modules ====

Dune supports opting in to different categories of GMCP messages by telling the game which your client supports. Some clients (like Mudlet) will do this automatically for some packages. Others (like Blightmud) require you to opt-in explicitly.

^ Name      ^ Description  ^
| Char | Character information | 
| Room | Room information | 
| Comm.Channel | Channel information | 
| Guild | Guild specific information ((Enabled automatically for all GMCP clients.)) |

==== Supported Messages by Module ====

Messages marked as type "Full" will always send each data filed. Messages marked as type "Delta" will only send the fields that have changed since the last time the message was sent.

=== Char.Name ===

^ Message Name      ^ Sent When  ^ Type ^ Notes ^
|''Char.Name'' | Login only | Full | Useful for triggers to load per-character or per-guild settings. |

^Data Field ^ Description ^ Example ^
| ''name'' | Character name (all lowercase) | ''"sneak"'' |
| ''fullname'' | Character title | ''"Sneak The Shadow Melder"'' |
| ''guild'' | Character guild | See note below. |

The guild field will be one of the following values (**case sensitive!**((yes, the inconsistency is annoying))): none, Atreid, Fremen, ixian, Gesserit, Harkonnen, Matres, Warrior, Speakers, Sardaurkar, Gesserit.

=== Char.Vitals ===

^ Message Name      ^ Sent When  ^ Type ^ Notes ^
|''Char.Vitals'' | At login, on change | Delta | Good for making health gauges, etc. |

^Data Field ^ Description ^ Example ^
| ''hp'' | Current hit points | ''123'' |
| ''maxhp'' | Maximum((hp may be higher than normal maxhp if you are above 100% HP in-game))  hit points | ''200'' |
| ''sp''((named sp instead of cp to match common GMCP usage)) | Current concentration points (CP).  | ''100'' |
| ''maxsp''((named maxsp instead of maxcp to match common GMCP usage)) | Maximum((sp may be higher than normal maxsp if you are above 100% CP in-game)) concentration points | ''150'' |
| ''string'' | A string description of the vitals information. | ''"H:123/200 M:100/150"'' |

=== Char.Stats ===

^ Message Name      ^ Sent When  ^ Type ^ Notes ^
|''Char.Stats'' | At login, on change | Delta | Base stats **without** modifiers. |

^Data Field ^ Description ^ Example ^
| ''str'' | Base Strength points | ''10'' |
| ''con'' | Base Constitution points | ''12'' |
| ''int'' | Base Intelligence points | ''8'' |
| ''wis'' | Base wisdom points | ''9'' |
| ''dex'' | Base dexterity points | ''15'' |
| ''qui'' | Base quickness points | ''17'' |

=== Char.MaxStats ===

^ Message Name      ^ Sent When  ^ Type ^ Notes ^
|''Char.MaxStats'' | At login, on change | Delta | Effective stats **with** modifiers. |

^Data Field ^ Description ^ Example ^
| ''maxstr'' | Total Strength points | ''15'' |
| ''maxcon'' | Total Constitution points | ''13'' |
| ''maxint'' | Total Intelligence points | ''10'' |
| ''maxwis'' | Total wisdom points | ''10'' |
| ''maxdex'' | Total dexterity points | ''17'' |
| ''maxqui'' | Total quickness points | ''19'' |

=== Char.Status and Char.StatusVars ===

^ Message Name      ^ Sent When  ^ Type ^ Notes ^
|''Char.Status'' | At login, on change | Delta | Misc character status values. |
| ''Char.StatusVars'' | At login, on change | Delta | Descriptive labels for each of the fields in ''Char.Status'' |

^Data Field ^ Description ^
| ''level'' | Your player level |
| ''money'' | Solaris your player is carrying |
| ''bankmoney'' | Solaris your player has in the bank |
| ''short'' | Your player's short description |
| ''guild'' | Your player's guild name (or none). |
| ''subguild'' | Your player's subguild (or none). |
| ''xp'' | Your player's current exp. |
| ''maxxp'' | Your player's current exp cap. |
| ''wimpy'' | Your player's set wimpy percentage value. |
| ''wimpy_dir'' | Your player's set preferred wimpy direction (or none). |
| ''aim'' | Your player's set preferred aim location. |
| ''quest_points'' | The number of quest points your player has. |
| ''kills'' | Your total number of kills |
| ''deaths'' | Your total number of deaths |
| ''explorer_rating'' | Your explorer rating. |
| ''pk'' | Whether or not you're pk (1 or 0). |
| ''inn'' | Whether o not you have an inn rented (1 or 0). |
| ''global_exp_bonus'' | The global exp bonus, if any (floating point number) |
| ''guild_exp_bonus'' | The exp bonus for your guild, if any (floating point number) |
| ''explorer_exp_bonus'' | Your personal explorer rating exp bonus, if any (floating point number) |
| ''personal_exp_bonus'' | Your personal exp bonus, if any (floating point number) |
| ''total_exp_bonus'' | Your total exp bonus including all of the bonuses mentioned above (floating point number) |

=== Room ===

^ Message Name      ^ Sent When  ^ Type ^ Notes ^
|''Room.Info'' | At login, whenever you move | Full | Useful for mapping. |

^Data Field ^ Description ^ Example ^
| ''num'' | Room number((For reasons, Dune uses a hash string and not a number)). Uniquely identifies the room. | ''"40ee12ff7ef7bcfc0f6b87fd4e6c6448"'' |
| "name" | Short description of the room | "Arrakeen Shuttle Landing Port" |
| ''area'' | Lower-case name of the planet((In the future we may send more specific area names)) you're on. | ''"arrakis"'' | 
| ''environment'' | Whether you're indoors or outdoors. | ''"indoors"'' |
| ''exits'' | A table/dictionary mapping from exit name to room ID((remember, it's a hash)) | See below. |

Example room info:
<code javascript>
{
  "name": "Arrakeen Shuttle Landing Port",
  "area": "arrakis",
  "num": "40ee12ff7ef7bcfc0f6b87fd4e6c6448"
  "environment": "outdoors",
  "exits": {
    "east": "baa2786919e34132d5096695e744a145",
    "west": "8ccbdd326a1db11dfd21a38f950c8aa8",
    "north": "22c354ced799589b3c0fd31ba457d854",
    "south": "44bded38d46d812602e63a0267c9fa7e"
  },
}
</code>

**Note**: A few select areas that are highly custom may be missing exit information. This is a known issue and will hopefully be addressed in the future. The majority of areas will send correct GMCP data.


=== Comm.Channel.List ===

^ Message Name      ^ Sent When  ^ Type ^ Notes ^
|''Comm.Channel.List'' | At login | Full | Useful for setting up channel capture. |

^Data Field ^ Description ^
| ''command'' | Command to use to speak on the channel. |
| ''enabled'' | Whether the channel is on/off (0 or 1). |
| ''channel'' | Name of the channel. |
| ''name'' | Name of the channel. | 

Channel list information is sent only at login, and as an array. Each each array value is a dict with the data fields listed above. 

Example:
<code javascript>
[
  {
    "command": "chat",
    "enabled": 1,
    "channel": "chat",
    "name": "chat"
  },
  {
    "command": "discord",
    "enabled": 0,
    "channel": "discord",
    "name": "discord"
  },
  {
    "command": "newbie",
    "enabled": 1,
    "channel": "newbie",
    "name": "newbie"
  }
]
</code>

=== Comm.Channel.Text ===

^ Message Name      ^ Sent When  ^ Type ^ Notes ^
|''Comm.Channel.Text'' | On channel message | Full | Capture these messages for channel capture. |

^Data Field ^ Description ^
| ''text'' | Channel message text (includes speaker) |
| ''channel'' | Name of the channel the message was sent on. |
| ''talker'' | Name of the person that spoke. |
| ''channel_ansi'' | Name of the channel (with ANSI colours). | 

Example:
<code javascript>
{
  "text": "Paradox : yeee\n",
  "channel_ansi": "\u001b[1m[\u001b[0m\u001b[31mchat\u001b[0m\u001b[1m]\u001b[0m",
  "talker": "Paradox",
  "channel": "chat"
}
</code>

By default channel messages will be sent both in-game and over GMCP for clients that opt-in to the ''Comm.Channel'' module. If you want channel messages to be sent **only** over GMCP, then ''set gmcp_chans on'' in-game. To restore the original behaviour: ''unset gmcp_chans''. If you use this setting make sure you have a GMCP channel capture trigger configured or you won't see any channel messages!!!

=== Guild ===

Guild data varies widely by guild. See each page for more information.
  * [[atreides|House Atreides]]
  * [[gesserit|Bene Gesserit]]
  * [[tleilax|Bene Tleilax]]
  * [[warriors|Bene Gesserit Warriors]]
  * [[fremen|Fremen]]
  * [[harkonnen|House Harkonnen]]
  * [[matres|Honored Matres]]
  * [[sardaukar|Imperial Sardaukar]]
  * [[img|Ixian Machine Guild]]
  * [[speakers|Fish Speakers]]


===== Client Setup =====

How to use GMCP messages sent by Dune depends on which MUD client you're using.

==== Mudlet ====

You can use ''gmod.enableModule("USERNAME", "XXX")'' from Lua code to opt-in to a supported module. E.g. use  ''gmod.enableModule("sneak", "Comm.Channel")''  to have in-game channel echo turned off and channel messages sent only via GMCP.  You can use whatever you want for the first username argument, it has no relation to your in-game character.

By default Mudlet enables ''Char'' and ''Room'' modules, and Dune sends ''Guild'' by default. Only enable ''Comm.Channel'' if you have set up a channel capture trigger.

See [[https://wiki.mudlet.org/w/Manual:Supported_Protocols#GMCP|the Mudlet wiki]] for more information.

==== Blightmud ====

To use Dune's GMCP data in [[https://github.com/blightmud/blightmud|Blightmud]] you'll have to set up a script that will register some of the supported packages described above, and add handlers to do something with the received data.

You can use ''gmcp.register("XXXX")'' from Lua code to opt-in to a supported module. E.g. use ''gmcp.register("Comm.Channel")'' to have in-game channel echo turned off and channel messages sent only via GMCP.

Example:
<code lua>
function gmcp_init()
  --Uncomment next line to see all raw GMCP messages (good for debugging).
  --gmcp.echo(true)

  -- Register some packages to get information sent from the MUD.
  gmcp.register('Room')
  gmcp.register('Room.Info')
  gmcp.register('Char')
  gmcp.register('Char.Info')
  gmcp.register('Char.Vitals')
  gmcp.register('Char.Guild')

 -- Example handler for receiving room info
  gmcp.receive('Room.Info', function(data)
    obj = json.decode(data)
    blight.output("You're now in room: " .. data['name'])
  end)
end

gmcp.on_ready(gmcp_init)
</code>

See ''/help gmcp'' from inside Blightmud for more information.

==== Other ====

Other MUD clients that support GMCP can be made to work with Dune but it will require you to figure out how to configure it. Consider adding steps to this wiki page!