GMCP - Revision history

Dorandraco at 19:01, 30 August 2025

2025-08-30T19:01:41Z

← Older revision		Revision as of 19:01, 30 August 2025
Line 1:		Line 1:
	This document describes the GMCP (Generic MUD Communication Protocol) messages currently implemented by the Unwritten Legends server '''as observed in the 1.0 engine'''. It is intended for client authors (e.g., Mudlet packages) and for internal maintainers.		This document describes the GMCP (Generic MUD Communication Protocol) messages currently implemented by the Unwritten Legends server '''as observed in the 1.0 engine'''. It is intended for client authors (e.g., Mudlet packages) and for internal maintainers.


	== Transport & Negotiation ==		== Transport & Negotiation ==
Line 15:		Line 14:

	UL recognizes client <code>Core.Supports.Set/Add</code> and maintains a capability set but '''does not require''' capabilities to be declared to emit core messages. Custom UL messages are namespaced under <code>UL.*</code>.		UL recognizes client <code>Core.Supports.Set/Add</code> and maintains a capability set but '''does not require''' capabilities to be declared to emit core messages. Custom UL messages are namespaced under <code>UL.*</code>.


	=== Namespaces ===		=== Namespaces ===
Line 26:		Line 24:

	Versioning for the custom namespace is surfaced implicitly by the supported set (<code>"UL 1"</code>). If/when a breaking schema appears, we will add <code>"UL 2"</code> while leaving <code>UL 1</code> available for a deprecation window.		Versioning for the custom namespace is surfaced implicitly by the supported set (<code>"UL 1"</code>). If/when a breaking schema appears, we will add <code>"UL 2"</code> while leaving <code>UL 1</code> available for a deprecation window.


	== Emission Triggers & Frequency ==		== Emission Triggers & Frequency ==
Line 37:		Line 34:

	'''Client guidance:''' handle idempotent updates and partial updates. Where keys are omitted on follow-up messages, merge into the client’s last known state.		'''Client guidance:''' handle idempotent updates and partial updates. Where keys are omitted on follow-up messages, merge into the client’s last known state.


	== Message Catalog ==		== Message Catalog ==
Line 52:		Line 48:
	<li>'''Schema:''' <code>{ "client": string, "version": string }</code></li>		<li>'''Schema:''' <code>{ "client": string, "version": string }</code></li>
	<li>'''Example:''' <code>{ "client": "Unwritten Legends", "version": "1.0.0.0" }</code></li></ul>		<li>'''Example:''' <code>{ "client": "Unwritten Legends", "version": "1.0.0.0" }</code></li></ul>


	==== Core.Supports.Set ====		==== Core.Supports.Set ====
Line 63:		Line 58:

	'''Also observed (client → server):''' <code>Core.Hello</code>, <code>Core.Supports.Set</code>, <code>Core.Supports.Add</code>. The server records client capabilities for future gating but does not currently require them to emit core messages.		'''Also observed (client → server):''' <code>Core.Hello</code>, <code>Core.Supports.Set</code>, <code>Core.Supports.Add</code>. The server records client capabilities for future gating but does not currently require them to emit core messages.


	=== Room ===		=== Room ===
Line 89:		Line 83:

	Future (not yet emitted): <code>Room.Players</code>.		Future (not yet emitted): <code>Room.Players</code>.


	=== Character Identity & State ===		=== Character Identity & State ===
Line 132:		Line 125:
	"level":100		"level":100
	}</pre></li></ul>		}</pre></li></ul>


	==== Char.Status ====		==== Char.Status ====
Line 166:		Line 158:
	"willpower_max":218		"willpower_max":218
	}</pre></li></ul>		}</pre></li></ul>


	==== Char.Stats ====		==== Char.Stats ====
Line 192:		Line 183:
	"lessons":{"available":4,"max":4}		"lessons":{"available":4,"max":4}
	}</pre></li></ul>		}</pre></li></ul>


	=== UL (Unwritten Legends) — custom namespace ===		=== UL (Unwritten Legends) — custom namespace ===
Line 247:		Line 237:
	* '''Schema:''' <code>{ "roundtime": number, "stun": number, "unconscious": number }</code> (seconds)		* '''Schema:''' <code>{ "roundtime": number, "stun": number, "unconscious": number }</code> (seconds)
	* '''Example:''' <code>{ "roundtime": 0, "stun": 0, "unconscious": 0 }</code>		* '''Example:''' <code>{ "roundtime": 0, "stun": 0, "unconscious": 0 }</code>


	=== External.Discord — presence [In Progress] ===		=== External.Discord — presence [In Progress] ===
Line 284:		Line 273:

	'''Observed (client → server):''' <code>External.Discord.Hello</code> with empty payload; UL treats support for <code>External.Discord</code> as sufficient to emit <code>Info</code>/<code>Status</code>.		'''Observed (client → server):''' <code>External.Discord.Hello</code> with empty payload; UL treats support for <code>External.Discord</code> as sufficient to emit <code>Info</code>/<code>Status</code>.


	== Handshake Transcript (illustrative) ==		== Handshake Transcript (illustrative) ==
Line 294:		Line 282:
	GMCP -> Core.Supports.Set ["Core 1","Char 1","Room 1","External.Discord 1","UL 1"]		GMCP -> Core.Supports.Set ["Core 1","Char 1","Room 1","External.Discord 1","UL 1"]
	... (Login Snapshot follows: Room.Info, Char., UL., External.Discord.*)</pre>		... (Login Snapshot follows: Room.Info, Char., UL., External.Discord.*)</pre>


	== Client Expectations & Best Practices ==		== Client Expectations & Best Practices ==
Line 303:		Line 290:
	* For <code>UL.</code> messages, check for <code>"UL 1"</code> in <code>Core.Supports.</code> if you want to be strict—UL currently emits them unconditionally to capable clients.		* For <code>UL.</code> messages, check for <code>"UL 1"</code> in <code>Core.Supports.</code> if you want to be strict—UL currently emits them unconditionally to capable clients.
	* Time values in <code>External.Discord.Status.starttime</code> are '''Unix epoch seconds'''.		* Time values in <code>External.Discord.Status.starttime</code> are '''Unix epoch seconds'''.


	== Future Additions (not yet emitted) ==		== Future Additions (not yet emitted) ==
Line 310:		Line 296:
	* Incremental variants: <code>UL.Equipment.Add/Remove</code>, etc.		* Incremental variants: <code>UL.Equipment.Add/Remove</code>, etc.
	* <code>UL.Info { version, schema }</code> (alternative to advertising via <code>Core.Hello</code>)		* <code>UL.Info { version, schema }</code> (alternative to advertising via <code>Core.Hello</code>)


	== Change Log ==		== Change Log ==

	* '''1.0''' — Initial public spec for engine v1.0. Includes Core/Char/Room/External.Discord, and UL namespace (<code>Equipment/Languages/Spells/MartialArt(s)/Timers</code>).		* '''1.0''' — Initial public spec for engine v1.0. Includes Core/Char/Room/External.Discord, and UL namespace (<code>Equipment/Languages/Spells/MartialArt(s)/Timers</code>).

Dorandraco: reformatting

2025-08-30T19:01:02Z

reformatting

Show changes

Dorandraco: Created page with "This document describes the GMCP (Generic MUD Communication Protocol) messages currently implemented by the Unwritten Legends server '''as observed in the 1.0 engine'''. It is intended for client authors (e.g., Mudlet packages) and for internal maintainers. == Transport & Negotiation == UL implements GMCP as a Telnet subnegotiation: * The server offers and accepts GMCP via Telnet '''DO/WILL GMCP'''. * After subnegotiation is active, the client typically sends
2025-08-30T18:34:19Z

Created page with "This document describes the GMCP (Generic MUD Communication Protocol) messages currently implemented by the Unwritten Legends server '''as observed in the 1.0 engine'''. It is intended for client authors (e.g., Mudlet packages) and for internal maintainers. == Transport & Negotiation == UL implements GMCP as a Telnet subnegotiation: * The server offers and accepts GMCP via Telnet '''DO/WILL GMCP'''. * After subnegotiation is active, the client typically sends <co..."

New page
This document describes the GMCP (Generic MUD Communication Protocol) messages currently implemented by the Unwritten Legends server '''as observed in the 1.0 engine'''. It is intended for client authors (e.g., Mudlet packages) and for internal maintainers.

== Transport & Negotiation ==

UL implements GMCP as a Telnet subnegotiation:

* The server offers and accepts GMCP via Telnet '''DO/WILL GMCP'''.
* After subnegotiation is active, the client typically sends <code>Core.Hello</code> and its <code>Core.Supports.Set/Add</code> list. UL tracks the client’s advertised packages.
* The server replies with:
<code>Core.Hello</code> (server identity/version)
<code>Core.Supports.Set</code> advertising what UL can emit.

'''Current advertised packages (server → client):''' <code>["Core 1", "Char 1", "Room 1", "External.Discord 1", "UL 1"]</code>

UL recognizes client <code>Core.Supports.Set/Add</code> and maintains a capability set but '''does not require''' capabilities to be declared to emit core messages. Custom UL messages are namespaced under <code>UL.</code>.

=== Namespaces ===

'''Core.'''* – handshake and feature advertisement.
* '''Char.'''* – character identity, state, vitals, stats.
* '''Room.'''* – current room/area summary.
* '''External.Discord.'''* – rich presence metadata for Discord bridge.
* '''UL.'''* – Unwritten Legends–specific messages (equipment, languages, spells, martial arts, timers, etc.).

Versioning for the custom namespace is surfaced implicitly by the supported set (<code>"UL 1"</code>). If/when a breaking schema appears, we will add <code>"UL 2"</code> while leaving <code>UL 1</code> available for a deprecation window.

== Emission Triggers & Frequency ==

'''On login/character entry:''' the server emits a snapshot (marked ''Login Snapshot'' below).

'''On pulse:''' UL’s game loop runs a ''Pulse'' (about 5 s). Certain values (e.g., experience absorption, vitality regen) produce periodic GMCP updates even if unchanged elsewhere. Expect duplicates; clients should de-dup by content or simply accept repeats.

'''On change:''' Some messages are resent when values change (e.g., equipment, active language, room).

'''Client guidance:''' handle idempotent updates and partial updates. Where keys are omitted on follow-up messages, merge into the client’s last known state.

== Message Catalog ==

Each entry lists '''Topic''', '''Direction''', '''When''', '''Schema''', and an '''Example'''.

=== Core ===

==== Core.Hello ====

<ul>
<li>'''Dir:''' server → client</li>
<li>'''When:''' after GMCP negotiation and after receiving client hello (once per session)</li>
<li>'''Schema:''' <code>{ "client": string, "version": string }</code></li>
<li>'''Example:''' <code>{ "client": "Unwritten Legends", "version": "1.0.0.0" }</code></li></ul>

==== Core.Supports.Set ====

<ul>
<li>'''Dir:''' server → client</li>
<li>'''When:''' once after <code>Core.Hello</code></li>
<li>'''Schema:''' array of strings <code><Package> <major></code></li>
<li>'''Example:'''
<source lang="json">["Core 1", "Char 1", "Room 1", "External.Discord 1", "UL 1"]</li></ul>

<blockquote>'''Also observed (client → server):''' <code>Core.Hello</code>, <code>Core.Supports.Set</code>, <code>Core.Supports.Add</code>. The server records client capabilities for future gating but does not currently require them to emit core messages.
</blockquote>

-----

=== 4.2 Room ===

==== Room.Info ====

<ul>
<li>'''Dir:''' server → client</li>
<li>'''When:''' Login Snapshot; on room change; occasionally repeated for resilience</li>
<li>'''Schema:'''
<source lang="json">{ "area": string, "name": string }</li>
<li></li>
<li>or</li>
<li><source lang="json">{ "exits": { string, ... } }</li>
<li></li>
<li>or</li>
<li><source lang="json">{ "id": { string } }</li>
<li>'''Example:'''
<source lang="json">{ "area": "City of Kaezar", "name": "Tempest Road at Avanil Way, Crossroads" }</li>
<li>or
<source lang="json">{ "exits": { "large stone building", "west", "south", "east", "north" } }</li>
<li></li>
<li>or</li>
<li><source lang="json">{ "id": { "8df6a052-9af2-5188-aff0-095e5d3d37a8" } }</li></ul>

<blockquote>Future (not yet emitted): <code>Room.Players</code>.
</blockquote>

-----

=== 4.3 Character Identity & State ===

==== Char.Info ====

<ul>
<li>'''Dir:''' server → client</li>
<li>'''When:''' Login Snapshot; on identity changes (rare)</li>
<li>'''Schema:'''
<source lang="json">{
"pretitlename": string, // may be empty
"name": string, // first name
"lastname": string, // surname
"truename": string,
"posttitle": string, // may be empty, includes punctuation
"race": string, // lowercase
"subrace": string, // lowercase
"gender": string, // lowercase (e.g., "male", "female", "neuter")
"age": number, // years
"profession": string, // lowercase
"deity": string, // lowercase
"patronmoon": string, // lowercase
"dominant_hand": string, // "left" | "right"
"level": number
}</li>
<li>'''Example:'''
<source lang="json">{
"pretitlename":"Sir",
"name":"Martaigne",
"lastname":"Shardleigh",
"truename":"Martaigne",
"posttitle":", Plydia's Scourge",
"race":"human",
"subrace":"kivian",
"gender":"male",
"age":57,
"profession":"cleric",
"deity":"thine",
"patronmoon":"tallow",
"dominant_hand":"right",
"level":100
}</li></ul>

==== Char.Status ====

<ul>
<li>'''Dir:''' server → client</li>
<li>'''When:''' Login Snapshot; when status elements change</li>
<li>'''Schema:'''
<source lang="json">{ "position": string, "stance": string }</li>
<li>'''Example:''' <code>{ "position":"standing", "stance":"parry" }</code></li></ul>

==== Char.Vitals ====

<ul>
<li>'''Dir:''' server → client</li>
<li>'''When:''' Login Snapshot; Pulse; any change</li>
<li>'''Schema:'''
<source lang="json">{
"vitality": number, "vitality_max": number,
"essence": number, "essence_max": number,
"stamina": number, "stamina_max": number,
"willpower": number, "willpower_max": number
}</li>
<li>'''Example:'''
<source lang="json">{ "vitality":320, "vitality_max":360, "essence":314, "essence_max":314, "stamina":310, "stamina_max":310, "willpower":218, "willpower_max":218 }</li></ul>

==== Char.Stats ====

<ul>
<li>'''Dir:''' server → client</li>
<li>'''When:''' Login Snapshot (full); Pulse (partial: often just <code>experience_total</code>); on changes</li>
<li>'''Schema (full snapshot):'''
<source lang="json">{
"experience_total": number,
"experience_to_level": number,
"fame": { "current": number, "lifetime": number },
"skillpoints": number,
"arcana": number,
"lessons": { "available": number, "max": number }
}</li>
<li>'''Partial updates:''' UL may send only the keys that changed (e.g., <code>{ "experience_total": 217000943 }</code>). Clients should merge by key.</li>
<li>'''Example (full):'''
<source lang="json">{
"experience_total":216265943,
"experience_to_level":4410000000,
"fame":{"current":102650,"lifetime":193400},
"skillpoints":635,
"arcana":2265,
"lessons":{"available":4,"max":4}
}</li></ul>

-----

=== 4.4 UL (Unwritten Legends) — custom namespace ===

==== UL.Equipment.Set ====

<ul>
<li>'''Dir:''' server → client</li>
<li>'''When:''' Login Snapshot; on equipment/hand changes</li>
<li>'''Schema:'''
<source lang="json">{ "slots": { "left": string, "right": string, ... } }
Slot keys are lowercase; value is an item short name or <code>"none"</code>.</li>
<li>'''Example:''' <code>{ "slots": { "left": "none", "right": "battle-worn t'elt claidheamh-mor" } }</code></li></ul>

==== UL.Languages.Set ====

<ul>
<li>'''Dir:''' server → client</li>
<li>'''When:''' Login Snapshot; on language change</li>
<li>'''Schema:''' <code>{"active": string, "known": string[]}</code> (all lowercase language ids)</li>
<li>'''Example:'''
<source lang="json">{ "active": "common", "known": ["orcish","elvish","anjour", "common"] }</li></ul>

==== UL.Spells.Set ====

* '''Dir:''' server → client
* '''When:''' Login Snapshot; when circles known change
* '''Schema:''' <code>{ "circles": string[] }</code> (string constants as used server-side)
* '''Example:''' <code>{ "circles": ["VIA_FIDE_NIVI", "VIA_GLAS", "VIA_TEG"] }</code>

==== UL.Spells.PreparedSpell ====

* '''Dir:''' server → client
* '''When:''' When spell is prepared or released
* '''Schema:''' <code>{ "spelllongname": string, "spellshortname": string }</code>
* '''Example:''' <code>{ spelllongname = "Fire Cantrip", spellshortname = "vf01" }</code>

==== UL.MartialArt.Active ====

* '''Dir:''' server → client
* '''When:''' Login Snapshot; when active style changes
* '''Schema:''' <code>{ "style": string, "moves": string[] }</code>
* '''Example:''' <code>{ "style":"Qai Sun Crane", "moves":["crescentkick","spinkick","roundhouse"] }</code>

==== UL.MartialArts.Set ====

* '''Dir:''' server → client
* '''When:''' Login Snapshot; when learned styles change
* '''Schema:''' <code>{ "styles": string[] }</code>
* '''Example:''' <code>{ "styles":["Assault","Qai Sun Bear","Berserk","Brawling"] }</code>

==== UL.Timers ====

* '''Dir:''' server → client
* '''When:''' Login Snapshot; Pulse; on timer changes
* '''Schema:''' <code>{ "roundtime": number, "stun": number, "unconscious": number }</code> (seconds)
* '''Example:''' <code>{ "roundtime": 0, "stun": 0, "unconscious": 0 }</code>

-----

=== 4.5 External.Discord — presence [In Progress] ===

==== External.Discord.Info ====

* '''Dir:''' server → client
* '''When:''' Login Snapshot (if client supports <code>External.Discord</code>); may be resent on config change
* '''Schema:''' <code>{ "applicationid": string, "inviteurl": string, "gamename": string }</code>
* '''Example:''' <code>{ "applicationid":"1409606830350401667", "inviteurl":"https://discord.gg/yourinvite", "gamename":"Unwritten Legends" }</code>
* '''Known Issues:''' inviteurl is currently disabled from send as the Discord server is not public

==== External.Discord.Status ====

<ul>
<li>'''Dir:''' server → client</li>
<li>'''When:''' Login Snapshot; on presence changes (details/state/party/time)</li>
<li>'''Schema:'''
<source lang="json">{
"details": string, // e.g., "martaigne • Adventurer"
"state": string, // freeform (e.g., "Logging in...")
"largeimage": string, // key for Discord rich presence image
"partysize": number,
"partymax": number,
"starttime": number // Unix epoch seconds
}</li>
<li>'''Example:'''
<source lang="json">{
"details":"martaigne • Adventurer",
"state":"Logging in...",
"largeimage":"server-icon",
"partysize":1,
"partymax":1,
"starttime":1756234455
}</li></ul>

<blockquote>'''Observed (client → server):''' <code>External.Discord.Hello</code> with empty payload; UL treats support for <code>External.Discord</code> as sufficient to emit <code>Info</code>/<code>Status</code>.
</blockquote>

-----

== 5) Handshake Transcript (illustrative) ==

<pre>GMCP <- Core.Hello { "client":"Mudlet", "version":"4.19.1" }
GMCP <- Core.Supports.Set [ "Char 1", "Char.Skills 1", "Char.Items 1", "Room 1", "IRE.Rift 1", "IRE.Composer 1", "External.Discord 1", "Client.Media 1", "Char.Login 1" ]
GMCP <- External.Discord.Hello
GMCP -> Core.Hello { "client":"Unwritten Legends", "version":"1.0.0.0" }
GMCP -> Core.Supports.Set ["Core 1","Char 1","Room 1","External.Discord 1","UL 1"]
... (Login Snapshot follows: Room.Info, Char., UL., External.Discord.)</pre>

-----

== 6) Client Expectations & Best Practices ==

Treat repeated messages as '''idempotent'''; ignore duplicates or update your HUD accordingly.
* Expect '''partial updates''' (e.g., <code>Char.Stats</code> with only <code>experience_total</code>). Merge by key.
* Unknown keys are '''forward-compatible'''; ignore them safely.
* For <code>UL.</code> messages, check for <code>"UL 1"</code> in <code>Core.Supports.</code> if you want to be strict—UL currently emits them unconditionally to capable clients.
* Time values in <code>External.Discord.Status.starttime</code> are '''Unix epoch seconds'''.

-----

== 7) Future Additions (not yet emitted) ==

* <code>Char.Affects.Set/Add/Remove</code>
* Incremental variants: <code>UL.Equipment.Add/Remove</code>, etc.
* <code>UL.Info { version, schema }</code> (alternative to advertising via <code>Core.Hello</code>)

-----

== 8) Change Log ==

* '''1.0''' — Initial public spec for engine v1.0. Includes Core/Char/Room/External.Discord, and UL namespace (<code>Equipment/Languages/Spells/MartialArt(s)/Timers</code>).

-----

''Questions or schema proposals?'' Open an issue, or add examples at the bottom of this doc and tag maintainers.