Repository navigation
Client Mudlet and GMCP
TL;DR: The Mudlet package is Lua in
src/, built into oneDreamland.xml. It draws every panel from GMCP data the server sends to any GMCP-capable client, never from matching game text. Merging a change tomasterpublishes 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.cppVerified: 2026-11-02 against dreamland_mudlet b18afc2, dreamland_code 88da8302
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.
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.
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.
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.
python3 build.py # writes Dreamland.xml
python3 build.py --check # fails if Dreamland.xml is staleCommit 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.
Push or merge to master with a change in Dreamland.xml, config.lua, src/ or build.py. The workflow deploy.yml:
- checks
Dreamland.xmlagainstsrc/, - compares the new
Dreamland.xmlandconfig.luawith the zip on thegh-pagesbranch and stops if nothing changed, - zips both files into
downloads/Dreamland.zipongh-pagesand adds one to the number indownloads/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/.
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.
Start here
Get running
Contribute
- Contribute
- Contributing Workflow
- Code Style
- Accessibility
- Writing Player Text
- Game Design Principles
Build areas
- Building
- OLC
- OLC Rooms
- OLC Mobiles
- OLC Objects
- OLC Resets
- OLC Line Editor
- OLC Other Editors
- Area Format
- Area Quests
- Mob Forms and Parts
Fenia
- Fenia
- Fenia Language
- Fenia Triggers
- Fenia Gotchas
- Fenia API
- Fenia Scripts
- Fenia Behaviors
- Fenia Skills and Spells
- Fenia Cookbook
- Fenia Grammar
Engine
- Engine Architecture
- Engine Time and Pulses
- Output Format
- Mechanics Combat
- Mechanics World
- Data Configs
- Item Power
Localization
Clients
More