⚔️ TalesMUD

A Modern, Extensible MUD Framework for Web-Based RPGs

Build immersive text-based multiplayer adventures in any genre — fantasy, sci-fi, horror, and beyond

Live Demo • Documentation • Contributing • Roadmap

</div>

📖 Overview

TalesMUD is a complete, production-ready framework for building browser-based Multi-User Dungeons (MUDs) — text-based multiplayer RPGs that run entirely in modern web browsers. Unlike traditional telnet-based MUDs, TalesMUD offers a rich, real-time web experience with persistent world state, live collaboration, and a powerful content creation suite.

Built with Go and Svelte, TalesMUD provides everything you need to launch your own multiplayer text adventure:

⚔️ Full RPG Systems — Combat, character progression, skills, quests, items, and loot
🗺️ World Building Tools — Visual editors for rooms, NPCs, dialogs, and interactive maps
🎨 Genre-Agnostic Design — Easily adapt for fantasy, sci-fi, horror, steampunk, or custom settings
🔧 Lua Scripting — Extend gameplay with custom mechanics, puzzles, and events
🌐 Real-Time Multiplayer — WebSocket-based gameplay with chat, emotes, and player presence
🎮 Modern UX — Rich terminal interface, graphical overlays, mobile-responsive design
🔐 Auth0 Integration — Secure authentication with OAuth2 and role-based access control

🎯 Live Demo

Experience TalesMUD in action at veilspan.com — a small MVP adventure set in the Veilspan Universe on the fantasy world of Aethermoor. This demo showcases the framework's capabilities running a complete fantasy RPG.

📸 Screenshots

In-Game Experience

TalesMUD Game Client Explore richly described rooms with visual backgrounds, interactive terminals, and real-time multiplayer chat

Social & Multiplayer

TalesMUD Chat Engage in conversations with NPCs, collaborate with other players, and experience dynamic storytelling

✨ Key Features

🎮 Complete RPG Framework

Character System

6 core classes (Warrior, Rogue, Ranger, Mage, Cleric, Druid)
Multiple races with unique attributes
Distributable stat points on level-up
Equipment system with 10 slots
Mana system for spellcasters
Persistent character progression

</td> <td width="50%" valign="top">

Combat & Skills

Turn-based tactical combat
29+ skills/spells across classes
Status effects (buffs, debuffs, DoTs, HoTs)
Auto-attack with special abilities
Skill cooldowns & resource management
Loot tables with item rarities

</td> </tr> <tr> <td width="50%" valign="top">

Quest System

Multi-objective quests (Kill, Collect, Deliver, Talk, Visit)
Quest prerequisites and level requirements
Automatic progress tracking
NPC dialog integration
XP, gold, and item rewards
Repeatable daily quests

</td> <td width="50%" valign="top">

World Building

Interconnected room-based world
Visual backgrounds and mood settings
Coordinate-based mapping (X, Y, Z grid)
Dynamic NPC/item spawning
Hidden exits and secret areas
Custom room actions

</td> </tr> </table>

🛠️ Content Creation Suite

Web-Based Editor — Full-featured CRUD interface for all game entities
Visual Map Editor — Grid-based world map with room coordinates
Dialog Tree Builder — Create branching NPC conversations with conditional logic
Lua Script IDE — Syntax highlighting, test runner, and sandboxed execution
Live Preview — Test changes instantly without server restarts
YAML Import/Export — Version control friendly data formats

🎨 Genre Flexibility

TalesMUD's generic, reusable architecture makes it perfect for any setting:

Fantasy — The included demo (Veilspan/Aethermoor) showcases medieval fantasy
Sci-Fi — Space stations, alien worlds, cyberpunk cities
Horror — Lovecraftian mysteries, survival horror, gothic tales
Modern — Contemporary settings, spy thrillers, urban fantasy
Custom — Mix genres or create entirely new worlds

All core systems (combat, quests, items, NPCs, dialogs) are setting-neutral and configurable through the content editor.

🚀 Modern Architecture

Go 1.24 backend with Gin HTTP framework
Svelte 4 frontend with TailwindCSS
SQLite for persistence (simple deployment, no database server needed)
WebSocket real-time communication
Docker containerization for easy hosting
Auth0 OAuth2 authentication
Groq API integration for AI-powered content generation

🚀 Quick Start

Prerequisites

Go 1.24+ (Download)
Node.js 18+ (Download)
Make (optional, for convenience commands)

Installation

# Clone the repository
git clone https://github.com/TalesMUD/talesmud.git
cd talesmud

# Build everything (backend + frontend)
make build

# Run the server
make run-server

The server will start on http://localhost:8010. Visit in your browser to begin!

Docker Deployment

# Start with Docker Compose
docker-compose up -d

Configuration

Create a .env file in the project root:

# Server
PORT=8010
GIN_MODE=debug
SQLITE_PATH=./talesmud.db

# Auth0 (optional, for authentication)
AUTH_ENABLED=false
AUTH0_DOMAIN=https://your-domain.auth0.com/
AUTH0_AUDIENCE=your-api-audience
AUTH0_WK_JWKS=https://your-domain.auth0.com/.well-known/jwks.json

# Admin (for export/import endpoints)
ADMIN_USER=admin
ADMIN_PASSWORD=admin

# Optional: AI character generation via Groq
GROQ_API_KEY=your-groq-api-key

See Configuration for full details.

🎯 Technology Stack

Backend

| Component | Technology | |-----------|------------| | Language | Go 1.24 | | HTTP Framework | Gin | | WebSocket | Gorilla WebSocket | | Database | SQLite (JSON document storage) | | Scripting | Lua (gopher-lua) | | Authentication | Auth0 JWT | | AI Integration | Groq API | | Logging | Logrus |

Frontend

| Component | Technology | |-----------|------------| | Framework | Svelte 4.2 | | Build Tool | Vite 6 | | Styling | TailwindCSS 3.4 | | Terminal | xterm.js | | HTTP Client | Axios | | Router | yrv | | Flow Diagrams | xyflow |

Infrastructure

| Component | Technology | |-----------|------------| | Container | Docker | | Orchestration | Docker Compose | | CI/CD | GitHub Actions |

📚 Core Concepts

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    Web Browser Client                        │
│              (Svelte SPA + xterm.js Terminal)               │
└──────────────────────┬──────────────────────────────────────┘
                       │ WebSocket + REST API
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                   Go Server (Gin)                            │
├──────────────────┬──────────────────┬───────────────────────┤
│  HTTP API        │  MUD Server      │  WebSocket Handler    │
│  (REST + Auth)   │  (Game Engine)   │  (Real-time Comms)    │
└──────────────────┴──────────────────┴───────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              Service Layer (Business Logic)                  │
│  Characters • Rooms • Items • NPCs • Quests • Dialogs       │
└──────────────────────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│            Repository Layer (Data Access)                    │
│              Generic SQLite with JSON payloads              │
└──────────────────────────────────────────────────────────────┘

Game Loop

The game engine runs a concurrent event loop processing:

Player Commands — Movement, combat, item interactions
NPC Behaviors — Idle chatter, patrol paths, combat AI
Combat Instances — Turn-based battles with initiative tracking
Quest Tracking — Automatic progress updates from game events
Room Updates — Spawner checks, NPC respawns, state sync

Message System

All game output is routed through a message audience system:

Origin — To the command sender only
User — To a specific user
Room — To all players in a room
RoomWithoutOrigin — To room except sender
Global — Server-wide broadcast

🎮 Game Systems

Combat

Turn-based combat with:

Initiative rolls (1d20 + DEX modifier)
Auto-attack each round
Skills/spells with mana costs or cooldowns
Defensive stance (+50% defense)
Flee attempts (50% + DEX bonus)
Status effects (stun, DoT, HoT, buffs, debuffs)
XP and loot on victory

Character Progression

Leveling — Flattened XP curve (gentle L2-5, transitional L6-15, steeper L16+)
Distributable Stats — 2 points per level to allocate freely
Class Caps — Prevent degenerate builds (e.g., warriors cap INT at 5)
Exploration XP — 5 XP per new room, 15 XP for new zones
Mana System — Scales with level and INT for casters
Equipment — Weapons, armor, accessories with stat bonuses

Quests

Data-driven quest definitions with:

Multiple objective types (Kill, Collect, Deliver, Visit, Talk, Custom Lua)
Prerequisites (required quests, level)
Rewar

Talesmud

Install / Use

README