Dome Client is a modern WebSocket-powered MUD client with a built-in IDE. Designed for MOOs, but it works for any MUD.

From the repository folder, double-click run domeclient.bat. It installs dependencies on first run, creates a local .env from .env-example-local when needed, builds the browser bundle, and starts the client. Open the local URL printed by the server.

The multi-MUD connect screen includes a bundled directory of active/recently reachable games from muindex, MUDVerse, MudStats, IPTIA, Mudhaven, Vineyard, Grapevine, the Evennia Game Index, and the Anime MUD Network. muindex entries include measured language and charset metadata where available; selecting one applies its default encoding, including GBK/Big5, EUC-KR, and KOI8-R language defaults. TopMUDSites, MUDConnect, and the unreliable TheMUDs.org listing are not used.

Dome Client is the maintained successor to the Legacy Dome Client, with ongoing fixes, modernized dependencies, a developer IDE for editing MOO verbs & properties, and expanded documentation.

It is a browser-based MUD client built with Node.js, Express, and Socket.io. It bridges browser WebSocket connections to traditional telnet-based MUD servers, so players can connect without installing anything.

This project is a fork of SindomeCorp/dome-client, which in turn follows the earlier Legacy Dome Client. The fork preserves the original BSD 3-Clause licensing and attribution. Directory metadata is collected from the sources documented in the bundled data and refresh script.

This fork extends the original SindomeCorp/dome-client for general-purpose multi-MUD use:

• Supports connections to arbitrary MUD hosts and ports instead of a single configured game.
• Adds a bundled directory of 1,144 deduplicated MUDs from the active/recent directory sources listed above, including anime/Dragonball games from AMN and Evennia games.
• Includes 286 additional active MUD entries imported from IPTIA’s software-organized directory, after filtering detail pages to MUD/MUSH/MUCK/MOO categories and excluding BBS records.
• Adds clickable directory links with search, language filtering, an experimental genre filter, website links, and a wiki-only view/list.
• Adds MSSP option-70 checks beside directory entries, a progressive single-variable MSSP scan, and clean popup lists for MUDs declaring values such as players, rooms, areas, races, and other MSSP variables. The bundled scan records 445 MSSP-capable and 699 non-MSSP entries; bulk checks skip known non-MSSP games.
• Adds explicit and automatic encoding support for UTF-8, GBK/GB18030, Big5, EUC-KR/CP949, Shift-JIS, EUC-JP, KOI8-R/KOI8-U, CP866, Windows code pages, and ISO-8859-1.
• Applies per-MUD encoding defaults from directory metadata and remembers manually selected encodings per host and port.
• Excludes stale directory sources such as TheMUDs.org, TopMUDSites, and MUDConnect.
• Improves command delivery with ordered socket writes, byte-accurate command encoding, connection checks, and acknowledgements.
• Includes run domeclient.bat for local Windows setup, building, server startup, readiness checking, and browser launch.

The directory can be refreshed with scripts/refresh-mud-directory.mjs. IPTIA entries can be re-imported with node scripts/import-iptia-mud-directory.mjs; its importer uses the site’s www endpoint with certificate verification disabled because the site’s certificate is not consistently valid, and still validates the returned page/category data before adding entries. The requested community sources can be refreshed with node scripts/import-community-mud-sources.mjs, and MSSP capability metadata can be refreshed with node scripts/scan-mud-directory-mssp.mjs. Directory data is bundled locally so the connect page remains usable without live directory requests.

git clone https://github.com/shywolfee/dome-client.git
cd dome-client
npm i
cp .env-example-local .env
npm start

Open in Browser: http://localhost:8080

This mode uses your configured MUD_HOST/MUD_PORT as the fixed game to connect to. Set MUD_TLS_ENABLED=true only when that configured MUD endpoint supports TLS; the backend connection will use Node's normal certificate verification.

git clone https://github.com/shywolfee/dome-client.git
cd dome-client
npm i
cp .env-example-local .env

Set the following in .env:

MULTI_MUD=true
MUD_HOST=default-game-if-user-does-not-enter-one.com
MUD_PORT=default-port
# Optional: expose the per-connection TLS checkbox and honor transport_mode=tls links.
MUD_TLS_ENABLED=false

Then start:

npm start

Open in Browser: http://localhost:8080

In this mode, the splash page is host/port-first and users can connect to different games; successful connections are tracked in persisted multi-MUD metrics. Set MUD_TLS_ENABLED=true to expose an optional Use TLS connection choice for users. Plain TCP remains the default for each new host/port.

Quick links: Requirements · Connection Modes · Planned Improvements · Contributing

These are tracked goals for the fork:

• Proper mobile support across phone and tablet screen sizes, including touch-friendly terminal interaction.
• An Electron desktop application with a packaged local runtime.
• MSSP integration for live player counts and other server-status readouts.
• Opt-in live directory updates from the mu*index API, with local bundled data remaining available as a fallback.
• More automated reachability checks and directory refresh reporting.
• More complete per-MUD language and encoding metadata.

• Node.js 22+
• npm

MUD is the generic product and runtime term in Dome Client. MOO is retained for MOO-specific protocol behavior, editor language support, status-route compatibility such as /moo/status/, and legacy internal config object names. Environment variables, routes, data files, storage keys, and public docs links keep their existing names for compatibility.

• Browser-based MUD play over WebSocket with no installation.
• Optional explicit TLS for backend MUD connections via MUD_TLS_ENABLED.
• Two connection modes:
  • Single-MUD mode (MULTI_MUD=false): fixed game from MUD_HOST/MUD_PORT.
  • Multi-MUD mode (MULTI_MUD=true): user enters host/port to enter connect flow with persisted per-game metrics.
• Terminal-accurate ANSI rendering with a stateful parser (including reset/inverse handling), full Xterm256 support, and TrueColor (38;2/48;2) foreground/background rendering in both live output and exported logs.
• HTTPS support.
• Automatic URL linkification in output buffer.
• Inline media previews for image/video/YouTube links with expand/collapse toggles.
• Host/IP enrichment for [host=...] tokens, with clickable IP/hostname lookup links.
• Copy-friendly wrapping for #obj and $ref-style tokens in buffer output.
• Regex-based client alerts with optional sound/window attention on match.
• Connection safety UX: disconnect overlay with one-click reconnect, unload warning while connected, and graceful @quit on page exit.
• Live health panel with hover/click detail view and rolling CPU/RAM/user charts (when status service is configured).
• Input ergonomics: command history recall, long-input-friendly arrow behavior, and keyboard shortcuts (Pause/Break, Home, Insert, Ctrl+R).
• Command history search overlay (Ctrl+R) with live filtering, de-duplicated exact matches, keyboard navigation, and one-key insert back into the input buffer.
• Mobile-focused UX: plain-text keyboard hints for command entry (no autocorrect/caps), dedicated up/down history buttons, responsive input sizing, touch-friendly action toolbar, centered overlay dialogs, and guarded clear-buffer confirmation.
• Rich client options: command hints, local echo, image preview, overlay transparency, buffer size, alert sound, font/theme choices, editor mode selection, separate input/output font sizing, configurable input text/background colors, and Scroll Up to Pause autoscroll behavior.
• Optional Screen Reader Mode: preserves the visible terminal and existing live region while removing ANSI/control and decorative terminal noise from new accessible output and announcing prompts after nearby output.
• Client options Import/Export workflow: download all preferences as JSON, import recognized keys locally, validate ranges, normalize legacy values, and reset to defaults with explicit confirmation.
• Session log export as HTML for preserving and sharing scrollback, with a client option to switch between default self-contained inline CSS and a lighter legacy linked stylesheet mode.
• Better nowrap output handling via SDWC markers (SDWC-START-NOWRAP / SDWC-END-NOWRAP) and a mobile-friendly wrap option for long horizontal content.
• Built-in keyboard shortcuts for both client and IDE workflows.
• Optional URL-shortener integration.
• Optional status-service integration.
• Native bridge integration support (window.DomeBridge / window.DomeNative) for mobile wrappers, including queued startup event handling and native log-download routing when available.
• Fully bundled client styling (local LESS/CSS and glyph assets), removing runtime dependency on external dome.css for consistent mobile/desktop rendering.
• Optional multi-game landing mode (MULTI_MUD) with host/port-first connect flow and persisted per-game connection metrics.
• MSSP directory checks from the multi-MUD landing page. Individual Check MSSP buttons query the selected variable for one game. The Scan selected value control checks only the chosen MSSP variable across the bundled entries and opens a sorted popup containing only MUD names and that value, avoiding the time and clutter of fetching every variable for every game. MSSP checks use the standard Telnet option 70 negotiation and do not send login commands.
• Directory metadata includes clickable declared websites, discovered wiki links, experimental genre labels, and source provenance. The wiki control opens a focused list without mixing wiki URLs into the terminal connection links.

• Intended for game-specific deployments where the client should always connect to one configured game.
• Splash and metadata are game-name centric (MUD_NAME is shown in heading/copy).
• Backend socket connections use MUD_HOST and MUD_PORT directly.
• MUD_TLS_ENABLED=true makes every backend MUD connection use TLS; URL query parameters do not override this mode.

• Intended for hub/public client deployments where users choose host/port at connect time.
• Splash switches to generic Play Now with a host/port connect form.
• Client passes selected host/port to the backend per connection.
• MUD_HOST/MUD_PORT still serve as fallback defaults for empty/invalid user input.
• Missing or invalid selected ports, including values below 23, fall back to MUD_HOST/MUD_PORT.
• When MUD_TLS_ENABLED=true, the splash form shows a per-host Use TLS checkbox and direct URLs may include transport_mode=tls.
• Direct transport_mode=tls URLs are honored only when both MULTI_MUD=true and MUD_TLS_ENABLED=true; otherwise they connect with plain TCP.
• Successful connections are counted and persisted across restarts in data/multi-mud-metrics.json.
• The connection stats list tracks TCP and TLS separately for the same host and port, and TLS rows link back with transport_mode=tls.

Example direct multi-MUD TLS URL:

/player-client/?gh=secure.example.org&gp=6697&transport_mode=tls

• Built-in IDE editor for verb and property editing, including multi-tab editing workflows.
• Object Browser and Property Browser panes in the IDE for fast navigation across loaded objects.
• Ctrl/Cmd-click code navigation in the IDE (@edit target jumps), with optional parent-chain lookup support.
• Hover overlays in the IDE for verb/property metadata lookups via SDWC out-of-band commands.
• Optional VMS note workflow for program saves (can append a commit-style note line after @program saves).
• Optional MOO parser diagnostics for verb editors, with a deployment flag to block @program saves while parser errors are visible.
• Scratch pad workflow (@scratch / @edit me.scratch) for temporary editing and recall.
• Optional individual editor-window mode (non-IDE) with unsaved-change protection.

Optional IDE integrations can be disabled per deployment when the connected MOO does not support their command flows. See docs/ide-editor.md for the related environment flags.

1. Install system dependencies (Ubuntu example):

   sudo apt update
   sudo apt install -y nodejs npm git supervisor

2. Clone the repository and install npm packages:

   git clone https://github.com/SindomeCorp/dome-client.git
   cd dome-client
   npm install

3. Copy .env-example-local (for local/dev) or .env-example-production (for production) to .env and adjust for your environment.
   • For MOO-side integration, see docs/MOO-SETUP.md
4. Start the development server:

   npm start

5. Connect in your browser to the NODE_SOCKET_URL defined in your .env. For example: http://localhost:8080

The repository ships with supervisor.conf for managing the process via Supervisor on Ubuntu. Link it into Supervisor's configuration directory and reload:

sudo ln -s "$(pwd)/supervisor.conf" /etc/supervisor/conf.d/dome-client.conf
sudo supervisorctl reread
sudo supervisorctl update

After linking, manage the service with sudo supervisorctl start dome-client, sudo supervisorctl restart dome-client, etc. Adjust the paths inside supervisor.conf if the repository lives somewhere other than /opt/dome-client.

Start the application:

node src/server.js

To run it in the background:

sudo nohup node src/server.js &

On production systems, SSL certificates are typically readable only by root. Start the server with sudo so Node can access the key files.

All application code resides in src/ and follows a layered design:

• src/server.js starts the Express application.
• src/config/ builds configuration objects from environment variables.
• src/routes/ maps HTTP routes to controllers.
• src/controllers/ handle request and response logic.
• src/services/ contain reusable domain logic.
• src/middleware/ contains middleware helpers (for example error and LESS middleware).
• src/logger.js exposes a shared Winston logger.
• src/env.js defines and validates environment variables.
• View templates live in views/; see views/README.md for directory layout and templating guidelines.

Controllers may depend on services and configuration, but services remain independent of Express. Tests live in test/ and mirror this structure.

Set IP_BLOCKLIST_PATH to a plain-text file to reject exact client IPs before serving web pages, static assets, or Socket.io connections. Leave it empty to disable blocking. The file is loaded when the web client starts, accepts one IP per line, and ignores blank lines or # comments. Invalid entries are logged and skipped.

When NODE_SOCKET_PROXIED=true, block-list checks use the left-most X-Forwarded-For address for both HTTP and Socket.io requests. Enable that only behind a trusted reverse proxy.

The in-browser editor uses Ace v1.43.2 with a custom MOO mode and optional Vim keybindings. Custom modules live under src/client/features/editor/ace and are bundled during the build. Run npm start or npm run build after editing these modules to regenerate client assets. See docs/ace-notes.md for details.

If you want the IDE to function properly you'll need to make a few verb changes/additions on your MOO.

• MOO Verbs Setup

• Production Deployment
• Autocomplete
• URL Shortener
• Website Auth
• Status Service
• Health Endpoint

sudo setcap 'cap_net_bind_service=+ep' $(which node)

npm run lint

npm run deadcode
npm run deadcode:deps
npm run deadcode:exports
npm run deadcode:files

Dead-code analysis uses Knip and is configured to scan source, tests, templates, and tooling while ignoring generated assets under public/.

See the dedicated testing guide: docs/TESTING.md.

Run npm run lint and npm test before committing. Coverage must remain at or above 80%.