Skip to content

Client Mudlet and GMCP

Kit Oliynyk edited this page Nov 13, 2026 · 2 revisions

TL;DR: The Mudlet package is Lua in src/, built into one Dreamland.xml. It draws every panel from GMCP data the server sends to any GMCP-capable client, never from matching game text. Merging a change to master publishes a new zip, and the game offers it to every Mudlet player on the next connect. Use when: you change the Mudlet package, write a GMCP client for another tool, or add a field to the data that GMCP clients receive. Source of truth: dreamland_mudlet/src/*.lua, dreamland_mudlet/build.py, dreamland_mudlet/.github/workflows/deploy.yml, dreamland_code/plug-ins/gmcp/impl.cpp Verified: 2026-11-02 against dreamland_mudlet b18afc2, dreamland_code 88da8302

For players

Create a Mudlet profile for host dreamland.rocks, port 9000, and connect. On the first connect the game offers the package. Accept, and it updates itself the same way later. The game's own help for client settings (help clients) lists the config flags that some clients need (noiac, notelnet, telnetga). See Clients.

The package adds a side panel with health, mana and move bars, an enemy bar in a fight, location, weather and time, quests, group, affects, stats, who is online, command buttons and chat tabs. It speaks the language the player picked in the game (English, Ukrainian or Russian). The game text itself is never hidden or moved. The panel only repeats it, so a screen-reader player loses nothing.

Alias dl:

Input Effect
dl Help.
dl hide, dl show Hide or show the side panel.
dl width 30 Panel width in percent of the window, clamped to 15 to 60.

On a fresh profile the package removes Mudlet's generic mapper, because it builds a map from game text and fights the GMCP mapper over the same rooms. If the profile already holds rooms that the package did not draw, the generic mapper stays.

What the server sends

GMCP starts when the client answers the server's IAC WILL GMCP with DO GMCP. The server then sends the following. Everything is in plug-ins/gmcp/impl.cpp.

Message When Content
Client.GUI on negotiation The package version, a newline, and the zip URL. Mudlet re-downloads the package whenever the version string changes.
Client.Map on negotiation {url} of a starter map file (Dreamland-mapping.dat). Mudlet offers it on an empty map.
External.Discord.Info on negotiation {applicationid, inviteurl} for Discord rich presence.
Char.Vitals every prompt {hp, maxhp, mp, maxmp, mv, maxmv}, the conventional keys, so a bare client can draw gauges.
Dreamland.Prompt every prompt The whole prompt object, changed blocks only. Same fields as the web client, see Prompt fields. The resume field is web-only and absent here.
External.Discord.Status when it changes Level and profession, zone, fighting or not, group size, session start. Never the character name, because Discord shows it to friends.
Comm.Channel.Text each chat message The web chat frame plus channel (the channel id) and talker (the peer's name). See the chat event in Client-Web-Protocol.
Room.Info on entering a room and on entering the game {num, name, area, map, exits}: room vnum, names in the player's language, the zone's map page URL, and exits as {direction letter: target vnum} limited to what the player can see.
Char.Combat when it changes {fighting, name, health}: whether the player is fighting, the opponent's name as the player sees it, and its health in percent. An unseen opponent is the game's "someone" in the player's language, a doppelganger shows the face it copied. Out of combat only {fighting: false}. The package does not read this message yet: its enemy bar takes the health percent from the fight prompt field and shows no name.

The panel merges Dreamland.Prompt into its own table: a block that is not in the message has not changed. A block value of none means "empty, hide the panel".

The server also negotiates MCCP, MSSP, EOR and MSP (sound). Sound URLs point at the web client's sound folder, so Mudlet needs MSP enabled in its settings.

Sending data to GMCP clients from game code goes through the out-of-band registry. A new message is a GMCPCOMMAND_RUN(name) block in plug-ins/gmcp/impl.cpp called from an outOfBandManager->run(...) site. If the data is already in the prompt object, add the field to a web prompt listener instead and GMCP clients get it for free.

The package

dreamland_mudlet has these parts:

Path What
src/00_core.lua Namespace dl, settings file, language pick (dl.lang() from the prompt), colour table.
src/01_strings.lua Panel strings in three languages.
src/02_layout.lua, 03_panel.lua Window layout and the panels.
src/04_chat.lua Chat tabs (all, room, personal, group, world) fed by Comm.Channel.Text. Each line also stays in the main window.
src/05_buttons.lua Command buttons.
src/06_events.lua Event handlers, dl alias, start-up.
src/07_mapper.lua Mapper drawn from Room.Info.
build.py Assembles Dreamland.xml from src/*.lua.
config.lua Package name (mpackage = "Dreamland").
tools/ Builds the starter map.

Rules the code follows, keep them:

  • All data comes from GMCP (Char.Vitals, Dreamland.Prompt, Comm.Channel.Text, Room.Info). Never match game text. That keeps the package working in every game language and with any custom prompt.
  • Never gag or move game text. The panels repeat, they do not replace.
  • Handlers are registered as named event handlers under one owner and deleted on reload, so reinstalling does not double them.

Mapper

Room.Info carries the vnum, names, the exits and the zone's map URL. The file name in that URL (midgaard in .../maps/midgaard.html) is the stable key of a Mudlet area. Rooms are placed next to a neighbour that is already on the map, otherwise in a fresh patch to the right of the area. Exits are only ever added, because the server hides exits the player cannot see right now (darkness, hidden doors), and that is not a removal.

On an empty map, the first Room.Info triggers a download of the starter map from Client.Map, then the room is drawn. The starter map holds the first zones a new character walks through: intro, midgaard, newbie2 and school. tools/map_rooms.py dumps those zones from the area XML as Room.Info shaped JSON (tools/rooms.json), and tools/build_map.lua feeds that to the package's own mapper inside Mudlet and saves Dreamland-mapping.dat. Run the build in an empty profile, it wipes the map first.

Build and test

python3 build.py          # writes Dreamland.xml
python3 build.py --check  # fails if Dreamland.xml is stale

Commit Dreamland.xml together with src/. The deploy workflow runs build.py --check and fails on a stale file.

To try a change in Mudlet, run these in the Mudlet input line (the lua prefix runs Lua):

lua uninstallPackage("Dreamland")
lua installPackage("/path/to/Dreamland.xml")

Connect to the real game with a test character. There is no offline harness.

Release

Push or merge to master with a change in Dreamland.xml, config.lua, src/ or build.py. The workflow deploy.yml:

  1. checks Dreamland.xml against src/,
  2. compares the new Dreamland.xml and config.lua with the zip on the gh-pages branch and stops if nothing changed,
  3. zips both files into downloads/Dreamland.zip on gh-pages and adds one to the number in downloads/version.

The game server reads that version (a file refreshed periodically from the gh-pages copy) and sends it in Client.GUI. The server falls back to a number compiled into plug-ins/gmcp/impl.cpp if the file is missing. Every Mudlet player then sees the offer to update on the next connect. The package URLs are served from GitHub Pages: https://dreamland-mud.github.io/dreamland_mudlet/downloads/.

Other GMCP clients

Any client that negotiates GMCP gets the same messages, so a different front end needs only a handler for Dreamland.Prompt, Char.Vitals, Char.Combat, Room.Info and Comm.Channel.Text. TinTin++ and other telnet clients also work without GMCP, as plain text clients. See Clients.

See also

Clone this wiki locally