MUDdown

Features

MUDdown is a modern MUD platform built on Markdown. Here's what's live today.

Format & Protocol

  • Markdown-native output — Rooms, combat, dialogue, and system messages are structured Markdown, readable as plain text and rendered in any client.
  • Container blocks — Semantic blocks (:::room, :::combat, :::dialogue, :::system) with typed attributes carry every game event.
  • Interactive link schemes — Clickable commands via go:, cmd:, item:, npc:, player:, and help:.
  • YAML frontmatter — Room metadata, exits, items, and lighting declared up front for machine consumption.
  • Wire protocol — JSON envelopes over WebSocket carry typed MUDdown payloads.
  • ARIA-labelled blocks — Container blocks (:::room, :::system, :::combat, :::dialogue) are rendered with role="group" and a descriptive aria-label, so screenreaders can navigate output by block type without conflicting with the surrounding game-log live region.

Gameplay

  • 24-room demo world — "Northkeep" spans 5 regions: town center, market, harbor, north road, and catacombs.
  • Items & equipment — 31 items across 22 rooms; pick up, drop, equip, unequip, use, examine, and combine, with weapon, armor, and accessory slots.
  • NPCs & dialogue — 16 NPCs with branching dialogue trees and entity lifecycle hooks.
  • Turn-based combat — Attack, flee, shared NPC HP, defeat tracking, and respawn timers.
  • Character creation — Pick a name and class: Warrior, Mage, Rogue, or Cleric.
  • Multi-player — See other players in rooms, broadcast chat, arrival and departure messages.
  • Help system — help <command> for per-command usage, with clickable cross-references via help: links.

AI & LLM

  • LLM-powered NPCs — NPCs with backstories generate in-character dialogue at runtime, with automatic fallback to static dialogue trees.
  • Immediate talk feedback — Player speech and a short NPC acknowledgement render before the LLM reply lands, masking generation latency.
  • Dynamic room descriptions — Room narratives adapt to your class, health, equipment, and combat state.
  • AI game assistant — The hint command gives context-aware suggestions based on your location, inventory, and surroundings.
  • Lore search (RAG) — The lore command answers questions via TF-IDF vector search across rooms, NPCs, items, and recipes.
  • MCP server — Game state exposed as Model Context Protocol resources with 15 granular tools for agent play.
  • Provider-agnostic — Vercel AI SDK abstraction; Anthropic out of the box, swap providers with a single env var.

Play Anywhere

  • Web client — Full browser MUD at /play with auto-reconnecting WebSocket, command history, inventory and hint panels, and clickable game links.
  • Desktop app — Native Tauri v2 client for macOS, Windows, and Linux with menu bar, system tray, OS notifications, keyboard shortcuts, and persistent window state.
  • Mobile app — Expo-based iOS/Android client with native MUDdown renderer, character selection, and tappable game links.
  • Terminal client — Full-featured Node.js CLI with readline-based input, startup wizard, browser-based OAuth, and shell mode.
  • Telnet bridge — TLS proxy (port 2323) with NAWS sizing, TTYPE ANSI detection, numbered link mode, and OSC 8 hyperlinks including Mudlet send:-URI support.
  • Discord bridge — Play from a Discord DM via the /play slash command; interactive links render as buttons and select menus.

Accounts & Persistence

  • OAuth login — Sign in with Discord, GitHub, Microsoft, or Google. No passwords to manage.
  • Player persistence — Room position, inventory, equipment, and HP saved across sessions in SQLite.
  • World state persistence — Room items, NPC health, and defeated NPC tracking survive server restarts.
  • Rate limiting — Per-session token-bucket throttling protects against command flooding.
  • Discord Rich Presence — Optional, opt-in: the desktop app can show your region, room title, and session time on your Discord profile via local IPC only. Off by default.

Infrastructure

  • Turborepo monorepo — Shared types, independent packages, parallel builds. TypeScript strict mode throughout.
  • MUDdown parser — Extracts blocks, attributes, links, sections, and frontmatter from any MUDdown document.
  • Reusable client library — Framework-agnostic @muddown/client with renderer, connection manager, history, link resolver, and inventory state.
  • Signed desktop downloads — Authenticode-signed Windows MSIs via Microsoft Artifact Signing, with macOS notarization support built into the release pipeline. Downloads page auto-detects OS and architecture.
  • Production deployment — Debian server with nginx, TLS via Let's Encrypt, systemd units, CI/CD via GitHub Actions.
  • Comprehensive test suite — 1388 tests across parser, server, client, bridge, discord-bridge, MCP, desktop, and website packages via vitest.