A text-based multiplayer online role-playing game (MUD) server implementing Pathfinder/D&D 3.5 mechanics, built on the robust tbaMUD/CircleMUD foundation with extensive custom enhancements.

• Quick Start - See also docs/QUICKSTART.md
• Overview
• Features
• Installation
• Usage
• Documentation
• Contributing
• Community
• License
• Acknowledgments

Get LuminariMUD running quickly with these simple steps:

Install required libraries first:

# Ubuntu/Debian/WSL2
sudo apt-get update
sudo apt-get install -y build-essential git make autoconf automake \
                        libcrypt-dev libgd-dev libmariadb-dev \
                        libcurl4-openssl-dev libssl-dev mariadb-server \
                        cmake libtool pkg-config gdb valgrind

# 1. Clone the repository
git clone https://github.com/LuminariMUD/Luminari-Source.git
cd Luminari-Source

# 2. Run the deployment script
#    This handles everything: dependencies, database, world data, build
#    You'll be prompted for MySQL root password
./scripts/deploy.sh

# 3. Start the MUD server
./bin/circle -d lib

That's it! Connect to localhost:4000 with any MUD client.

The deployment script automatically:

• Copies configuration files (.example.h → .h)
• Installs any missing dependencies
• Sets up MariaDB database (prompts for root password)
• Creates database and user with generated password
• Initializes world data (zones, rooms, mobs, objects)
• Builds the MUD using autotools (preferred) or CMake
• Creates all required directories and symlinks

Optional flags:

• --auto - Skip prompts where possible (still needs MySQL root password)
• --skip-db - Skip database setup (not recommended)
• --dev - Development build with debug symbols
• --prod - Production optimized build

For detailed information, see docs/deployment/DEPLOYMENT_GUIDE.md

LuminariMUD is a feature-rich MUD server that brings the beloved Pathfinder/D&D 3.5 rule system to life in a text-based multiplayer environment. Built upon the proven tbaMUD/CircleMUD codebase, it features an original world inspired by Biblical, Dragonlance, and Forgotten Realms stories.

Create a MUD with authentic Pathfinder/d20/D&D 3.5 mechanics featuring an original world that fosters a safe, friendly community for like-minded gamers. Our primary goal is building meaningful connections through collaborative storytelling and adventure.

This project embodies commitment, self-motivation, and perseverance through challenges. Creating a MUD is inherently rewarding work, regardless of player base size. We remain dedicated to our initial vision and the hard work required to make this project successful.

• Authentic Pathfinder/D&D 3.5 Mechanics: Complete implementation of familiar rule systems
• Advanced Character System: Multiple races, classes, feats, and skills
• Dynamic Combat: Initiative-based combat with tactical positioning
• Spell System: Comprehensive magic system with spell preparation and components
• Crafting & Alchemy: Extensive item creation and enhancement systems

• Original World Design: Unique setting inspired by Biblical, Dragonlance, and Forgotten Realms
• Quest-Driven Progression: Story-oriented advancement system
• Living World: Heavy scripting for dynamic, responsive environments
• Zone-to-Zone Travel: World map navigation with vehicle support
• High-Quality Content: Custom zones replacing stock content

• MySQL Integration: Persistent player data and world state
• DG Scripting System: Powerful scripting for NPCs, objects, and rooms
• Online Level Creation (OLC): In-game world building tools
• Advanced Networking: Support for modern MUD protocols including MSDP
• Performance Monitoring: Built-in profiling and debugging tools with C++ optimization
• Security Hardened: All PHP tools audited and secured (January 2025)
• Memory Management: Advanced debugging with Valgrind integration

• Operating System: Linux or Unix-like system (including WSL2 Ubuntu)
• Compiler: GCC or Clang (C90/C89 with GNU extensions)
• Build System: CMake 3.12+ or Autotools
• Database: MariaDB 10.0+ or MySQL 5.7+ (REQUIRED - not optional)
• Libraries:
  • libmariadb-dev (MariaDB client library - required)
  • libcrypt, libgd, libm, libcurl, libssl, libcrypto, libpthread

# Install all required dependencies (updated for MariaDB)
sudo apt-get update
sudo apt-get install -y build-essential libcrypt-dev libgd-dev libmariadb-dev \
                        libcurl4-openssl-dev libssl-dev mariadb-server git make cmake \
                        autoconf automake libtool pkg-config

# HIGHLY RECOMMENDED: Install debugging tools (used by debug_game.sh and vgrind.sh)
sudo apt-get install -y gdb valgrind

# Clone the repository
git clone https://github.com/LuminariMUD/Luminari-Source.git
cd Luminari-Source

# Configure required headers (one-time setup)
cp src/campaign.example.h src/campaign.h
cp src/mud_options.example.h src/mud_options.h
cp src/vnums.example.h src/vnums.h
# Edit these files as needed for your configuration

# Option 1: Build with CMake (recommended)
cmake -S . -B build/
cmake --build build/ -j$(nproc)

# Option 2: Traditional build with Autotools
autoreconf -fvi  # Only if configure script missing
./configure
make

# Run the server (after configuration)
bin/circle

# Or use the autorun script for automatic restarts
./autorun

For detailed installation instructions including system requirements, dependencies, database setup, and configuration, please see the Setup and Build Guide.

Windows users (WSL): See the "Auto-WSL integration (Windows)" section in the Setup and Build Guide for targeting a specific WSL distro and for temporarily disabling or re-enabling the Auto-WSL behavior.

# Build everything
make all

# Clean build artifacts
make clean

# Clean autotools files (keeps Makefile & config.h)
make scrub

# Full clean (removes everything, requires autoreconf)
make distclean

# Run unit tests
make cutest

# Generate dependencies
make depend

# Rebuild from scratch
autoreconf -fiv && ./configure && make all

# Start the server directly
bin/circle

# Start with specific port
bin/circle -p 4000

# Run with autorun script (recommended for production)
./autorun

# Run in background
nohup bin/circle &

• campaign.h: Core game settings and world configuration
• mud_options.h: Server options and feature toggles
• vnums.h: Virtual number assignments for objects, rooms, and NPCs

• Connect via telnet: telnet your-server-ip 4000
• Use a MUD client like MUSHclient, TinTin++, or Mudlet for enhanced experience

• Use in-game OLC (Online Level Creation) commands
• Access building documentation in /docs/
• Follow building standards and guidelines

• Review code in modular C files
• Use the DG scripting system for advanced features
• Contribute via GitHub pull requests

• 📚 Complete Documentation Index: Navigate all documentation by audience and topic
• 🔧 Technical Master Index: Complete technical documentation overview

• Architecture: Server architecture and design patterns
• Setup Guide: Detailed installation and configuration
• Developer Guide: Coding standards and API reference

• Combat System: Combat mechanics and calculations
• Player Management: Character creation and progression
• World Simulation: World systems and mechanics

• Testing Guide: Quality assurance and testing procedures
• Troubleshooting: Common issues and solutions
• PHP Tools Guide: Web tools security audit and deployment
• Ultimate Writing Guide: Zone building and content creation
• AI Assistant Guide: Comprehensive guide for AI-assisted development

We welcome contributions from developers, builders, and community members! Please read our guidelines before contributing.

1. Fork the Repository

   # Fork on GitHub, then clone your fork
   git clone https://github.com/YOUR_USERNAME/Luminari-Source.git
   cd Luminari-Source

2. Create a Feature Branch

   git checkout -b feature/your-feature-name

3. Make Your Changes

   • Follow our coding standards (see Developer Guide)
   • Add tests for new functionality
   • Update documentation as needed

4. Test Your Changes

   make clean
   make all
   make cutest  # Run unit tests

5. Submit a Pull Request

   • Push your branch to your fork
   • Create a pull request with a clear description
   • Reference any related issues

• Coding Standards: Follow existing code style and conventions
• Documentation: Update relevant documentation for new features
• Testing: Include unit tests for new functionality
• Commit Messages: Use clear, descriptive commit messages

• World Building: Follow established lore and building standards
• Help Files: Maintain consistency with existing help system
• Scripts: Use DG scripting best practices

• Use GitHub Issues to report bugs
• Include steps to reproduce the issue
• Provide system information and error messages
• Check existing issues before creating new ones

• Lead Programmer: Manages code standards and development workflow
• Game Designer: Defines game mechanics and project direction
• Programmers: Implement game mechanics and features

• World Designer: Designs maps, zones, and building standards
• Lore Designer: Develops world background and stories
• Quest Designers: Creates quest content and rewards
• Builders: Creates world content, scripts, and quests
• Lead Scripter: Develops universal scripts and provides support

• Lead Administrator: Manages staff and community standards
• Administrators: Support player relations and enforce guidelines
• Help File Lead: Organizes help system and documentation

Contributions to this project must be accompanied by a Contributor License Agreement. You retain copyright to your contribution; this gives us permission to use and redistribute your contributions as part of the project.

• Discord: Join our community - Primary communication hub
• GitHub Discussions: Use for development-related discussions
• Issues: Report bugs and request features

• Respect: Treat all community members with respect and kindness
• Collaboration: Work together towards common goals
• Constructive Feedback: Provide helpful, actionable feedback
• Inclusivity: Welcome newcomers and help them get started

• Discord: Ask questions in appropriate channels
• Documentation: Check our comprehensive documentation first
• GitHub Issues: For bug reports and feature requests
• In-Game Help: Use the built-in help system

# Missing dependencies
sudo apt-get install build-essential mariadb-server libmariadb-dev libgd-dev

# Permission issues
chmod +x configure
chmod +x licheck

# Clean build
make clean && make

# Database connection problems
# Check MariaDB service status
sudo systemctl status mariadb
# Or for older systems:
sudo systemctl status mysql

# Port already in use
# Check what's using port 4000
netstat -tulpn | grep :4000

• Verify all .h configuration files are properly set up
• Check file permissions on configuration files
• Ensure database credentials are correct

1. Check the Troubleshooting Guide
2. Search existing GitHub Issues
3. Ask on Discord for community support
4. Create a GitHub Issue for bugs or feature requests

This project uses a dual licensing approach:

Code contributed by the tbaMUD project follows their licensing terms. See tbamud.com for details.

Custom code developed for LuminariMUD is released into the public domain:

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.

For complete license details, see the LICENSE file.

• tbaMUD: The base MUD codebase
• CircleMUD: The original foundation
• CWG (Copper) MUD: Additional enhancements and features

• Biblical Stories: Spiritual and moral themes
• Dragonlance: Epic fantasy elements
• Forgotten Realms: Rich world-building traditions

• Current Version: LuminariMUD 2.4839 (tbaMUD 3.64)
• Repository: https://github.com/LuminariMUD/Luminari-Source
• Created: July 16, 2019
• Language: C (ANSI C90/C89 standard) with C++11 performance monitoring
• Last Updated: January 2025

Remember: The work itself is the reward. Focus on creating something meaningful for the community.

For more information, visit our technical documentation or join our Discord community.