This is an old revision of the document!

Table of Contents

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 1)
Guild Guild specific information 2)

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!3)): 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 Maximum4) hit points 200
sp5) Current concentration points (CP). 100
maxsp6) Maximum7) 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
str Total Strength points 15
con Total Constitution points 13
int Total Intelligence points 10
wis Total wisdom points 10
dex Total dexterity points 17
qui 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 number8). Uniquely identifies the room. “40ee12ff7ef7bcfc0f6b87fd4e6c6448”
“name” Short description of the room “Arrakeen Shuttle Landing Port”
area Lower-case name of the planet9) you're on. “arrakis” environment Whether you're indoors or outdoors. “indoors”
exits A table/dictionary mapping from exit name to room ID10) TODO

Comm.Channel

TODO

Guild

TODO

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 the Mudlet wiki for more information.

Blightmud

To use Dune's GMCP data in 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: 

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)

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!

1)
Disables in-game channel echo when enabled.
2)
Enabled automatically for all GMCP clients.
3)
yes, the inconsistency is annoying
4)
hp may be higher than normal maxhp if you are above 100% HP in-game
5)
named sp instead of cp to match common GMCP usage
6)
named maxsp instead of maxcp to match common GMCP usage
7)
sp may be higher than normal maxsp if you are above 100% CP in-game
8)
For reasons, Dune uses a hash string and not a number
9)
In the future we may send more specific area names
10)
remember, it's a hash