QMud

QMud is a Qt 6 port and continuation of the original MUSHclient (by Nick Gammon), designed and written by Panagiotis Kalogiratos (Nodens) of CthulhuMUD. It is a client program for connecting to MUD (Multi-User Dungeon) games. It is compatible with existing MUSHclient files and plugins, but it will migrate them to its own format in order to maintain separation. As more features are implemented, things were bound to diverge, especially in data persistence, so, as a conscious choice, QMud diverges from the get-go. The active implementation in this repository is C++20 + Qt 6.11.

The official site and documentation of QMud is here: qmud.dev

Project status

QMud is fully functional and early porting issues have been ironed out. There are several improvements and new features implemented already and many more on TODO. It is now also the FIRST and ONLY, at the time of this writing, MUD client with a multithreaded Lua engine. v11.00 essentially marks the first production release. QMud started with a v10 versioning offset in order to guarrantee higher than MUSHclient versioning for compatibility/importing reasons. Please use the issue tracker, with the appropriate template to report issues, request features, etc.

Features

• Cross-platform (Linux, Windows, macOS).
• Unicode, NAWS, Terminal Type, CHARSET, EOR, ECHO, MXP, MSP, MCCP, MMCP, OSC8, xterm256 color, Truecolor, TLS (Direct & Upgrade).
• Lua scripting. The FIRST and ONLY, currently, MUD client with a multithreaded Lua engine that allows ridiculously heavy Lua plugin workloads without lagging the client.
• Copyover-style in-place reload on Linux/macOS (File -> Reload QMud).
• MushReader and LuaAudio implemented natively for VI workflows and are activated by the presence of those plugins in existing world files or by loading the included stub plugins.
• Passive TTS engine enabled automatically when a native screenreader is detected.
• Split-pane scrollback buffer, persistent scrollback buffer/command history.
• Autosave, autobackup, log rotation, log compression.
• Autoupdates.

Contact / Support

For support, testing feedback, and development discussion, join:

• CthulhuMUD Discord

Do NOT use the issue tracker for general support requests.

Contributions

• Bug fix PRs are welcome.
• Feature PRs have to be discussed first either on Issue tracker or Discord.
• You can also contribute with documentation or translations (once work on translations is started; but you can apply to help before that).
• You can test plugins of various MUDs and see if they're working right or not. Open detailed issues if something's not working and make sure to include a link to the source for the plugin in question.
• You can also contribute with funding as funds are needed for code signing certificate, Apple registration etc. in order to bring QMud to the Apple Store/avoid issues with Windows SmartScreen/WDAC.

NOTICE: While contributions/PRs are very welcome, if you open a PR, you are expected to UNDERSTAND the code you're touching AND be able to make requested changes after review. "Vibe coding" is NOT welcome.

Supported platforms

• Linux (primary development platform)
• Windows (source/build support and packaging workflow)
• macOS (source/build support and packaging workflow)

Migration from MUSHclient data

QMud can migrate an existing MUSHclient data tree.

How to Migrate

1. Run QMud.
2. Go to Help → Import from MUSHclient.
3. Select the MUSHclient directory. Migration treats the source directory as READONLY.
4. Wait until it's done. At the end, it will show statistics on what was imported and will prompt to reload or restart depending on platform.

Old manual Migration method. (Still working but obsolete)

Migration is copy-based, so source files are preserved and moved under a migrated marker path after successful import to avoid reprocessing.

What is migrated:

• World list/database entries (including plugin list metadata)
• World files under the worlds tree (.MCL and related world XML data)
• Preference/state data required for normal startup

Path handling during migration normalizes legacy Windows-style paths (for example C:\...) so migrated worlds resolve correctly on the active platform.

1. Install/Run QMud (depending on platform) to create fresh QMud home directory.
2. Copy your MUSHclient's lua contents into QMud/lua directory without overwriting anything. (IF you have placed any custom lua modules there)
3. Copy your MUSHclient scripts directory into QMud/ directory without overwriting anything. (IF you have placed any custom scripts there)
4. Copy your MUSHclient world directory into QMud/ without overwriting anything.
5. Delete QMud.conf and QMud.sqlite from QMud/ directory.
6. Copy your mushclient.ini and mushclient_prefs.sqlite to QMud/ directory.
7. Copy your *.db sqlite databases to QMud/ directory.
8. Run QMud.
9. Change Terminal Type (TTYPE) in world preferences to "QMud" unless you have a reason to keep it mushclient (e.g. Mud does some special handling on TTYPE).
10. (Optional) Do a manual check on your .qdl world files with a text editor to make sure paths have migrated normally. QMud saves paths ALWAYS as RELATIVE to the QMUD_HOME directory and with FORWARD slashes even on Windows. So all paths in the world file should look like: <include name="./worlds/plugins/CthulhuMUD/CthulhuMUD_Mapper.xml" plugin="y" />

Always keep a copy of your original MUSHclient directory. Extensive testing has been done but better safe than sorry.

Data directory resolution (QMUD_HOME)

QMud resolves its startup/data directory in this order:

1. QMUD_HOME environment variable (all platforms).
2. If env var is missing, QMUD_HOME from config file fallback:
   • Linux: ~/.config/QMud/config, then /etc/QMud/config
   • macOS: ~/Library/Application Support/QMud/config, then /Library/Application Support/QMud/config
   • Windows: %LOCALAPPDATA%/QMud/config

When multi-instance mode is enabled (QMUD_ALLOW_MULTI_INSTANCE env var or --multi-instance/ --allow-multi-instance), config fallback is disabled and QMUD_HOME must be set explicitly in the process environment in order to avoid second instances writing to the same datadir.

System config lines support both:

• QMUD_HOME=/path/to/dir
• export QMUD_HOME=/path/to/dir

Quoted values are accepted, and leading ~ is expanded. The same config fallback files can also define any QMUD_* environment flag, and those values are used when the real process environment does not override them.

If nothing is configured, defaults are:

• AppImage: $HOME/QMud
• macOS: ~/Documents/QMud
• Windows and non-AppImage Linux: executable directory

Environment flags and CLI switches

Environment flags

Flags below can be provided either as process environment variables or in the OS config fallback files (QMUD_* entries, used as fallback when not set in the process environment).

• QMUD_HOME: Overrides startup/data directory resolution (see section above).
• QMUD_ALLOW_MULTI_INSTANCE: When set to 1, y, yes, or true, bypasses single-instance enforcement. (Not safe with same datadir). In this mode, QMUD_HOME must be explicitly set in process environment.
• QMUD_DISABLE_UPDATE: When set to 1, y, yes, or true, disables the automatic updates functionality (for distro packaging).
• QMUD_RELOAD_VERBOSE: When set to 1, y, yes, or true, enables verbose per-world reload diagnostics in logs.

CLI switches

• --multi-instance (alias: --allow-multi-instance): Bypass single-instance enforcement for that process. (Not safe with same datadir). In this mode, QMUD_HOME must be explicitly set in process environment.
• --dump-lua-api <output-dir>: Export Lua API inventory to the given directory and exit.

Reload QMud (Copyover-style)

File -> Reload QMud is available on Linux and macOS. It performs a reload keeping worlds connected when possible.

Current behavior/limitations:

• MCCPv1/2 enabled worlds that do not honor IAC DONT COMPRESS/2, on timeout/failure to end compression stream, downgrade to reconnect on reload.
• TLS connected worlds also downgrade to reconnect for the time being.

Build requirements

• CMake 3.21+
• C++20 compiler
• Qt 6 modules: Widgets, Network, Sql, PrintSupport
• Optional Qt 6 module: Multimedia (sound; disabled at runtime if missing)
• Optional Qt 6 module: TextToSpeech (TTS support; disabled if missing)
• zlib
• Lua 5.4 when QMUD_ENABLE_LUA_SCRIPTING=ON (default)
• lua-socket
• lua-json
• lua-lpeg
• lua-sec
• patchelf (for AppImage non-docker target)
• qt6-qtspeech-speechd (and working speech-dispatcher daemon/libspeechd) or qt6-qtspeech-flite (for AppImage non-docker target with TTS support)

Docker build images for AppImage/Windows/macOS have everything required for building already staged. The above is for building natively.

Build instructions

Linux (Ninja/Makefiles)

cmake -S . -B cmake-build-release -DCMAKE_BUILD_TYPE=Release
cmake --build cmake-build-release --target QMud -j"$(nproc)"

Linux AppImage package

cmake -S . -B cmake-build-release \
  -DCMAKE_BUILD_TYPE=Release \
  -DQMUD_ENABLE_APPIMAGE=ON
cmake --build cmake-build-release --target AppImage -j"$(nproc)"

The packaged AppImage is generated under cmake-build-release/appimage/.

Windows (Visual Studio 2022)

cmake -S . -B cmake-build-release -G "Visual Studio 17 2022" -A x64
cmake --build cmake-build-release --config Release --target QMud

macOS (Ninja/Makefiles)

cmake -S . -B cmake-build-release -DCMAKE_BUILD_TYPE=Release
cmake --build cmake-build-release --target QMud -j"$(sysctl -n hw.ncpu)"

Cross/Docker-build AppImage/Windows/macOS on Linux

Build the cross-build images first:

docker build -t qmud-appimage-builder:qt6.11 -f tools/docker/appimage-qt611/Dockerfile tools/docker/appimage-qt611
docker build -t qmud-macos-builder:qt6.11 -f tools/docker/macos-qt611/Dockerfile tools/docker/macos-qt611
docker build -t qmud-windows-builder:qt6.11 -f tools/docker/windows-qt611/Dockerfile tools/docker/windows-qt611

Configure once (Docker targets are Linux-host only):

cmake -S . -B cmake-build-release \
  -DCMAKE_BUILD_TYPE=Release \
  -DQMUD_ENABLE_APPIMAGE=OFF \
  -DQMUD_ENABLE_APPIMAGE_DOCKER=ON \
  -DQMUD_ENABLE_MAC_DOCKER=ON \
  -DQMUD_ENABLE_WINDOCKER=ON \
  -DQMUD_DOCKER_EXECUTABLE=docker

Build cross targets:

cmake --build cmake-build-release --target AppImageDocker
cmake --build cmake-build-release --target MacDockerU
cmake --build cmake-build-release --target WinDocker

MacDockerU is the default macOS packaging target and produces universal x86_64/arm64 binaries. To build a single-architecture macOS package manually, use MacDocker with QMUD_MAC_DOCKER_ARCH set at configure time:

cmake -S . -B cmake-build-release -DQMUD_MAC_DOCKER_ARCH=aarch64
cmake --build cmake-build-release --target MacDocker

QMUD_MAC_DOCKER_ARCH accepts x86_64 or aarch64.

Notice that Qt is always universal as it is not customly built for QMud.

Artifacts are written to:

• AppImage: cmake-build-release/appimage-docker-out
• macOS: cmake-build-release/mac-docker-out
• Windows: cmake-build-release/windows-docker-out

Running tests

Configure with tests enabled:

cmake -S . -B cmake-build-release \
  -DCMAKE_BUILD_TYPE=Release \
  -DQMUD_ENABLE_TESTING=ON \
  -DQMUD_ENABLE_GUI_TESTS=ON

Build and run all registered tests:

cmake --build cmake-build-release -j"$(nproc)"
ctest --test-dir cmake-build-release --output-on-failure

Run the default quick suite used for pull requests:

ctest --test-dir cmake-build-release --output-on-failure --label-exclude slow

CI policy:

• .github/workflows/pipelines.yml is the authoritative CI workflow.
• Pull requests should require the Pipelines / PR/Push quick suite (exclude slow) and package build jobs to pass before merge.

Purposeful deviations from MUSHclient

These are intentional design choices in QMud:

• Qt-native UI/runtime stack instead of MFC.
• Regex engine uses QRegularExpression (PCRE2 behavior).
• XML parsing/serialization uses Qt XML APIs (QXmlStreamReader).
• Lua sqlite3 integration is implemented on top of Qt SQL (QSqlDatabase/QSqlQuery) via the in-tree Lua binding layer.
• Windows Script Host integrations have not been ported; Lua is the ONLY supported scripting engine.
• PNG has been depracated and handled with native Qt.
• Legacy SHS code was deprecated; hashing paths use Qt (QCryptographicHash).
• Newly written XML metadata uses qmud elements; legacy muclient are still read for compatibility.

Contributors

• Abigail Brady (Cryosphere)
• RunnerScrab

License

QMud is licensed under the GNU General Public License v3.0. See LICENSE.

Third-party license texts are in skeleton/docs/licenses.

Qt source archive