MUDdown

Features

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

MUDdown Format

  • Markdown-native game output — Room descriptions, combat logs, dialogue, and system messages are all structured Markdown. Readable as plain text, beautifully rendered in browsers, parseable by machines.
  • Container blocks — Semantic blocks (:::room, :::combat, :::dialogue, :::system, and more) with typed attributes give structure to every game event.
  • Interactive link schemes — Clickable commands via go:, cmd:, item:, npc:, player:, and help: schemes. Point-and-click or type — your choice.
  • YAML frontmatter — Room metadata, connections, item references, and lighting are declared in frontmatter for machine consumption.
  • Wire protocol — JSON envelopes over WebSocket carry typed MUDdown payloads (room, combat, dialogue, system, narrative).

Gameplay

  • 24-room demo world — "Northkeep" spans 5 regions with fully interconnected bidirectional exits: town center, market district, harbor, north road, and catacombs.
  • Item system — 31 items across 22 rooms. Pick up, drop, equip, unequip, use, examine, and combine items. Equipment slots for weapon, armor, and accessory.
  • NPC dialogue — 16 NPCs with branching dialogue trees. Talk to merchants, guards, and townsfolk across Northkeep.
  • LLM-powered conversations — NPCs with backstories use an LLM to generate freeform, in-character dialogue. Dynamic speech, mood, narrative, and response suggestions — with automatic fallback to static dialogue trees when the LLM is unavailable.
  • Turn-based combat — Attack NPCs, flee from danger. Shared NPC HP for players in the same room, defeat tracking, and 20-minute respawn timers.
  • Character creation — Choose a name and class (Warrior, Mage, Rogue, or Cleric) with distinct starting stats.
  • Multi-player — See other players in rooms, broadcast chat, arrival and departure messages.
  • Entity lifecycle hooks — NPCs react to events: greet players on room entry, respawn to home rooms, reset state on timers.
  • Detailed help system — Type help <command> for per-command usage, aliases, and examples. The overview table links to each command via help: links.
  • AI game assistant — The hint command gives context-aware suggestions based on your location, inventory, and surroundings. Uses AI when available, with a static fallback.
  • Dynamic room descriptions — Room narratives adapt to your character's state: class, health, equipment, active combat, and surroundings. The LLM rewrites the static description in real time, with graceful fallback to the original text.
  • Lore search — The lore command answers questions about the game world using vector search over all rooms, NPCs, items, and recipes. When an LLM is available, results are synthesized into a narrative answer; otherwise you get relevant excerpts.

Web Client

  • Browser-based play — Full MUD client at /play with auto-reconnecting WebSocket, command history (up/down arrows), and clickable game links.
  • MUDdown renderer — Converts MUDdown markup to styled HTML: headings, bold, italic, code, lists, tables, blockquotes, and interactive game links.
  • Inventory panel — Sidebar (persistent), floating overlay, or hidden — your choice, persisted in localStorage.
  • Hint panel — Persistent sidebar or floating overlay that displays the latest AI hint with clickable suggested commands. Auto-opens on first hint.
  • Character selection — Create and switch between characters from the play screen (requires login).
  • Dark terminal aesthetic — Monospace typography, carefully tuned dark theme, responsive layout.

Authentication & Persistence

  • OAuth2 login — Sign in with Discord, GitHub, Microsoft, or Google. No passwords to manage.
  • Player persistence — Room position, inventory, equipment, and HP saved across sessions via 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 without affecting normal gameplay.

AI Integration

  • MCP server — Game state exposed as Model Context Protocol resources (room, inventory, stats, map, help). AI agents can read and interact with the world.
  • Tool-calling interface — 15 granular MCP tools (look, go, examine, get, drop, inventory, equip, unequip, use, talk, attack, say, combine, lore, available_actions) plus a raw game_command fallback. AI agents play with semantic actions, not string parsing.
  • Structured schemas — All game constructs are typed data that LLMs can parse, reason about, and act on.
  • LLM NPC abstraction — Provider-agnostic dialogue generation via the Vercel AI SDK. Anthropic supported out of the box; swap in other providers (OpenAI, Ollama) by changing a single env var.
  • LLM room description engine — Generates player-aware room narratives using structured context (static room description, exits, and player state such as inventory, equipment, combat, and HP). Same provider-agnostic abstraction as NPC dialogue, with timeout and sanitization safeguards.
  • Vector-based lore search (RAG) — TF-IDF vector store indexes all game content at startup. The lore command retrieves relevant documents by cosine similarity and feeds them to the LLM as context for grounded, factual answers.

Accessibility

  • ARIA-mapped blocks — Container blocks carry semantic roles: room → main, system → alert, combat → log, dialogue → group.
  • Screenreader-first — Text is the primary interface. Structured Markdown ensures content is navigable and meaningful without visual rendering.

Infrastructure

  • Turborepo monorepo — Shared types, independent packages, parallel builds. TypeScript throughout with strict mode.
  • MUDdown parser — Extracts blocks, attributes, links, sections, and frontmatter from MUDdown documents. 56 unit tests.
  • Reusable client library — Framework-agnostic @muddown/client package with MUDdown renderer, WebSocket connection manager, command history, game link resolver, and inventory state validation. 86 unit tests.
  • React Native mobile app — Expo-based iOS/Android client with native MUDdown renderer, character selection, command input with history, and tappable game links.
  • Tauri desktop app — Native desktop client for macOS, Windows, and Linux via Tauri v2. Includes native menu bar, system tray with connection status, OS notifications, keyboard shortcuts, persistent window state, auto-updater with signed releases, and Apple notarization support for macOS distribution (pending enrollment).
  • Production deployment — Debian server with nginx, TLS via Let's Encrypt, systemd service, CI/CD via GitHub Actions.
  • Comprehensive test suite — 701 tests across parser, server, client, and MCP packages via vitest.