TinyMUX

GMCP Protocol

Hardcode

Overview

TinyMUX supports the Generic MUD Communication Protocol (GMCP), a telnet option (option 201) that enables structured data exchange between the server and compatible clients. GMCP allows the server to send JSON-encoded data frames to clients and receive structured messages in return, enabling rich client features beyond plain text.

Protocol Negotiation

GMCP is negotiated as a standard telnet option. When a client connects, the server offers GMCP via the telnet option negotiation mechanism. Clients that support GMCP (such as Mudlet and MUSHclient) respond affirmatively, and structured communication can begin. Clients that do not support GMCP simply decline the option, and the connection proceeds as normal text-only telnet.

Receiving GMCP Data

When a GMCP-capable client sends a GMCP message to the server, the message is delivered to the connected player’s A_GMCP attribute. The substitution registers are set as follows:

  • %0 – The GMCP package name (e.g., Char.Login).
  • %1 – The JSON payload.

This allows softcode to react to client-initiated GMCP messages by placing code on the GMCP attribute of a player or a parent object.

Sending GMCP Data

gmcp()

gmcp(<player>, <package>, <json>)

Sends a GMCP frame to <player> with the specified package name and JSON data. The <json> argument should be a valid JSON string. If the player’s connection does not have GMCP negotiated, the call has no effect.

Use Cases

GMCP enables a wide range of client-side features that go beyond what is possible with plain text output:

  • Health and status bars – Send Char.Vitals data so the client can display graphical gauges.
  • Room information – Send Room.Info with room name, description, and exits so the client can render a map.
  • Character statistics – Transmit character attributes for display in a dedicated panel.
  • Client-side scripting – Provide structured data that client-side scripts can process without parsing free-form text.

Example

Send room information to a player via GMCP:

&GMCP_ROOM_UPDATE #123=$^room_change:think gmcp(%#, Room.Info, json(object, name, [name(here)], num, [num(here)]))

gmcp(), @chatformat, Telnet, Network Layer.