Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
executable file
·
250 lines (197 loc) · 6.82 KB

GETTING_STARTED.md

File metadata and controls

executable file
·
250 lines (197 loc) · 6.82 KB

LuminariMUD Getting Started Guide

Overview

This guide covers setting up and running LuminariMUD from source code.

Prerequisites

  • Linux/Unix system (Ubuntu, Debian, CentOS, WSL, macOS)
  • Git installed
  • Internet connection for dependency installation

Installation

Automated Setup

The recommended approach for most users:

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

# Run deployment script (handles everything: database, world data, build)
# Note: You'll be prompted for MySQL root password during setup
./scripts/deploy.sh

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

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

What it does: The script automatically sets up the database, initializes world data, copies config files, and builds the MUD. World initialization is enabled by default (required for the server to start).

Setup with Options

For more control over the deployment:

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

# Run deployment with custom options
./scripts/deploy.sh --dev   # Development build with debug symbols
# Or
./scripts/deploy.sh --auto  # Skip prompts where possible

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

The deploy script automatically:

  • Installs missing dependencies and builds the game (Autotools preferred)
  • Provisions the luminari database and user, runs the in-code db_init_system routines so every table exists (wilderness, vessels, PubSub, help, etc.)
  • Initializes minimal world data (zones, rooms, mobs, objects) - enabled by default
  • Writes generated credentials to lib/mysql_config (mode 600)

Note: Database and world data are both required. The script handles both automatically. You can safely re-run the script to refresh credentials and migrate the schema.

Manual Setup

See the Full Deployment Guide for detailed manual setup instructions.

Connecting to Your MUD

MUD Clients

You can connect using any MUD client:

Popular Clients:

  • Mudlet - Feature-rich, cross-platform (recommended)
  • MUSHclient - Windows, powerful scripting
  • TinTin++ - Terminal-based, Unix/Linux
  • SimpleMU - Windows, beginner-friendly
  • Blowtorch - Android mobile client
  • MUDRammer - iOS mobile client

Basic Connection:

  • Host: localhost or 127.0.0.1
  • Port: 4000 (default)

First Login

  1. Create your first character (automatically gets admin privileges)
  2. Choose name, password, race, and class
  3. Complete character creation
  4. You'll start in the default starting room

Essential Commands

Basic Commands

look / l           - Examine your surroundings
north/south/etc    - Movement (or n/s/e/w/u/d)
get <item>         - Pick up an item
drop <item>        - Drop an item
inventory / i      - Check your inventory
equipment / eq     - View equipped items
who                - List online players
say <message>      - Talk to others in the room
tell <player> <msg>- Send private message
help <topic>       - Access help system

Combat Commands

kill <target>      - Attack a mobile/player
flee               - Escape from combat
rescue <player>    - Rescue someone from combat
bash               - Attempt to knock down opponent
cast '<spell>'     - Cast a spell

Character Commands

score              - View character statistics
affects / aff      - List active affects
practice           - See/improve skills
train              - Spend training points
levelup            - Advance when ready
save               - Force save character
quit               - Exit the game

Builder Commands (Admin)

As the first created character, you have access to builder commands:

Online Creation (OLC)

redit              - Room editor
oedit              - Object editor
medit              - Mobile (NPC) editor
zedit              - Zone editor
sedit              - Shop editor
trigedit           - Trigger editor

Zone Management

zreset             - Reset your current zone
saveall            - Save all OLC changes
show zones         - List all zones
goto <room#>       - Teleport to room

Admin Commands

advance <player> <level> - Set player level
wizhelp            - List immortal commands
shutdown           - Shutdown server
copyover           - Reboot without disconnecting players

Building Your World

Creating Your First Zone

  1. Create a Zone:
zedit new 100        - Create zone 100
zedit 100 name <Zone Name>
zedit 100 top 199    - Set room range (100-199)
zedit save
  1. Create Rooms:
redit 100            - Create/edit room 100
redit name <Room Name>
redit desc           - Enter room description
redit exit north 101 - Link north to room 101
redit save
  1. Create Objects:
oedit 100            - Create/edit object 100
oedit name sword
oedit short a steel sword
oedit long A sharp steel sword lies here.
oedit save
  1. Create Mobiles (NPCs):
medit 100            - Create/edit mobile 100
medit name guard
medit short a city guard
medit long A guard watches the area carefully.
medit level 10
medit save
  1. Save Everything:
saveall              - Save all OLC work

Configuration

Main Configuration Files

  • src/campaign.h - Core game settings
  • src/mud_options.h - Server options
  • src/vnums.h - Virtual number assignments
  • lib/etc/config - Runtime configuration

Changing Port

Edit startup command:

./bin/circle -q 5000 -d lib  # Run on port 5000

Database Setup (REQUIRED)

See Deployment Guide for MySQL/MariaDB setup details.

Troubleshooting

Common Issues

Can't connect:

  • Verify server is running: ps aux | grep circle
  • Check firewall settings
  • Try telnet localhost 4000 to test

Build errors:

  • Ensure all dependencies installed
  • Run autoreconf -fvi if Makefile missing
  • Check log/syslog for errors

Missing files:

  • Run ./scripts/deploy.sh --auto --init-world to create all required files
  • Check symlinks exist: ls -la world text etc

Getting Help

  • In-game help: Type help <topic>
  • Immortal help: Type wizhelp (as admin)
  • Documentation: Browse the docs/ directory
  • Logs: Check log/syslog for errors
  • GitHub: Report issues

Next Steps

  1. Explore the codebase: Review source files in src/
  2. Read documentation:
  3. Start building: Create your own zones and content
  4. Join the community: Connect with other MUD developers

For complete deployment details, see the Deployment Guide