Skip to content

Tutorial Part 1: Installation & First Run

Estimated time: 15 minutes

Welcome to the MAID tutorial series! This first part will guide you through installing MAID and running your first server. By the end of this tutorial, you will have a working MAID server and understand the basics of connecting and interacting with it.

What is MAID?

MAID (Multi AI Dungeon) is a modern MUD (Multi-User Dungeon) engine written in Python 3.12+. MUDs are text-based multiplayer games that have been around since the late 1970s, and MAID brings this classic genre into the modern era with:

  • AI Integration - Built-in support for AI-powered NPCs using providers like Anthropic (Claude), OpenAI, and Ollama
  • Modern Architecture - Async/await throughout, Entity Component System (ECS), and event-driven design
  • Content Pack System - Modular, pluggable architecture for game content
  • Multiple Connection Options - Telnet for classic MUD clients and WebSocket for modern web interfaces

What You Will Learn

In this tutorial, you will:

  1. Install MAID and its dependencies
  2. Start your first MAID server
  3. Connect to the server via Telnet and Web
  4. Create a character and explore basic commands
  5. Understand the project directory structure

Prerequisites

Before starting, ensure you have:

  • Python 3.12 or higher - MAID uses modern Python features
  • Basic Python knowledge - Familiarity with running Python scripts and using pip/package managers
  • A terminal/command line - You will be running commands throughout this tutorial
  • A text editor or IDE - For viewing and editing files (VS Code, PyCharm, or similar recommended)

You can verify your Python version by running:

python --version
# or
python3 --version

If you see Python 3.12.x or higher, you are ready to proceed.

Installation

MAID uses uv, a fast Python package manager, for dependency management. This is the recommended installation method for all platforms.

Step 1: Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

After installation, restart your terminal or run: 

source ~/.bashrc  # or ~/.zshrc on macOS


powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

After installation, restart your terminal.

If you prefer, you can install uv via pip: 

pip install uv

Verify the installation:

uv --version

Step 2: Clone the Repository

git clone https://github.com/Qworg/MAID.git
cd MAID

Step 3: Install Dependencies

uv sync

This command will:

  • Create a virtual environment automatically
  • Install all required dependencies
  • Install MAID in editable mode

Installation Complete

You should see output indicating packages are being installed. When complete, you are ready to start the server.

Platform-Specific Notes

Requirements:

  • macOS 11 (Big Sur) or later is recommended
  • Xcode Command Line Tools may be required for some dependencies: 
    xcode-select --install

Apple Silicon (M1/M2/M3):

uv and MAID work natively on Apple Silicon. No special configuration needed.

Ubuntu/Debian:

You may need to install development headers for some dependencies: 

sudo apt update
sudo apt install python3.12-dev build-essential

Fedora: 

sudo dnf install python3.12-devel gcc

Arch Linux: 

sudo pacman -S python base-devel

WSL2 (Recommended):

For the best experience on Windows, we recommend using Windows Subsystem for Linux 2 (WSL2):

  1. Enable WSL2 following Microsoft's guide
  2. Install Ubuntu from the Microsoft Store
  3. Open Ubuntu and follow the Linux installation instructions above

Native Windows:

MAID can run natively on Windows, but some features may have limited support:

  • Ensure Python is added to your PATH during installation
  • Use PowerShell or Windows Terminal for best results
  • Some telnet clients may require additional configuration

Install Python from python.org and ensure you check "Add Python to PATH" during installation.

Installing with AI Provider Support

MAID supports multiple AI providers for NPC dialogue and content generation. Install the ones you need:

# OpenAI (GPT) support
uv sync --extra openai

# Ollama (local AI) support
uv sync --extra ollama

# All AI providers
uv sync --all-extras

AI is Optional

MAID works perfectly without AI features. You can always add AI provider support later.

Starting the Server

Now that MAID is installed, let us start the server.

Basic Server Start

uv run maid server start

You should see output similar to:

Starting MAID Server...
  Telnet: 0.0.0.0:4000
  Web:    0.0.0.0:8080
  Discovered: maid-stdlib
  Discovered: maid-classic-rpg
  Loaded: maid-stdlib
  Loaded: maid-classic-rpg
Server started. Press Ctrl+C to stop.

Understanding the Output

Let us break down what this output tells us:

Line Meaning
Telnet: 0.0.0.0:4000 The Telnet server is listening on port 4000 on all network interfaces
Web: 0.0.0.0:8080 The WebSocket server is listening on port 8080 on all network interfaces
Discovered: maid-stdlib The standard library content pack was found
Discovered: maid-classic-rpg The classic RPG content pack was found
Loaded: maid-stdlib The standard library content pack was loaded successfully
Loaded: maid-classic-rpg The classic RPG content pack was loaded successfully

Default Ports

MAID uses two default ports:

  • Port 4000 - Telnet server for traditional MUD clients
  • Port 8080 - WebSocket server for web clients and the admin interface

Firewall Configuration

If you want to allow external connections (from other computers), ensure ports 4000 and 8080 are open in your firewall.

Server Options

You can customize the server with command-line options:

# Start with custom ports
uv run maid server start --telnet-port 5000 --web-port 9000

# Bind to localhost only (no external access)
uv run maid server start --host 127.0.0.1

# Enable debug mode for verbose logging
uv run maid server start --debug

Connecting to the Server

With the server running, let us connect to it. You have two options: Telnet (traditional) and Web (modern).

Connecting via Telnet

Telnet is the traditional way to connect to MUD servers. It provides a simple text interface.

Using the Built-in Telnet Client

Most systems have a telnet client built-in: 

telnet localhost 4000

Telnet may not be enabled by default. Enable it via:

  1. Open Control Panel
  2. Go to Programs > Turn Windows features on or off
  3. Check "Telnet Client"
  4. Click OK

Then connect: 

telnet localhost 4000

Using a MUD Client

For a better experience, consider using a dedicated MUD client:

  • Mudlet - Cross-platform, feature-rich, with scripting support
  • TinTin++ - Powerful command-line client for Linux/macOS
  • Blightmud - Modern terminal-based client
  • MUSHclient - Windows-only with extensive plugin support

MUD Client Configuration:

Setting Value
Host localhost (or your server IP)
Port 4000
Protocol Telnet

Connecting via Web

MAID provides a WebSocket interface for modern web clients. Open your web browser and navigate to:

http://localhost:8080

The web interface provides:

  • A text input area for commands
  • An output area for server responses
  • Connection status indicator
  • Basic styling for readability

Admin Interface

If you have built the admin frontend, you can access the admin interface at http://localhost:8080/admin-ui/. See the Admin UI documentation for details.

Character Creation and Login

When you first connect, you will be greeted with a welcome message and prompted to either log in or create a new character.

Creating a New Character

  1. Enter your character name when prompted: 

    Welcome to MAID!
Enter your character name: Gandalf

  2. Create a password (you will not see the characters as you type): 

    Creating new character: Gandalf
Enter a password: ********
Confirm password: ********

  3. Enter the game - You will be placed in the starting location: 

    Character created! Welcome, Gandalf!

Town Square
You are standing in the center of a bustling town square...

Logging In with an Existing Character

If you already have a character:

Welcome to MAID!
Enter your character name: Gandalf
Password: ********
Welcome back, Gandalf!

Basic Commands to Try

Now that you are in the game, try these basic commands:

Command Description Example
look See your surroundings look
help List available commands help
help <command> Get help on a specific command help look
who See who is online who
say <message> Say something to the room say Hello, world!
north, south, east, west Move between rooms north
inventory Check your inventory inventory
quit Disconnect from the server quit

Try It Out

After logging in, try typing look to see a description of your current location, then try help to see all available commands.

Project Directory Structure

Understanding the project structure will help you navigate MAID as you progress through the tutorials.

MAID/
├── packages/                    # The three main packages
│   ├── maid-engine/             # Core infrastructure
│   │   └── src/maid_engine/
│   │       ├── core/            # Engine, World, ECS, Events
│   │       ├── commands/        # Command registry
│   │       ├── config/          # Settings framework
│   │       ├── plugins/         # Content pack system
│   │       ├── net/             # Networking (Telnet, WebSocket)
│   │       └── storage/         # Persistence
│   │
│   ├── maid-stdlib/             # Standard library
│   │   └── src/maid_stdlib/
│   │       ├── components/      # Health, Inventory, Position
│   │       ├── events/          # Movement, combat events
│   │       ├── commands/        # look, move, get, drop
│   │       └── utils/           # Dice, text formatting
│   │
│   └── maid-classic-rpg/        # Classic MUD content pack
│       └── src/maid_classic_rpg/
│           ├── systems/         # Combat, magic, quests
│           ├── commands/        # Game-specific commands
│           └── data/            # NPCs, items, areas
│
├── docs/                        # Documentation
├── pyproject.toml               # Project configuration
├── uv.lock                      # Dependency lock file
└── CLAUDE.md                    # Development instructions

Package Architecture

MAID is organized as a monorepo with three packages that build on each other:

┌────────────────────────────────────────┐
│         maid-classic-rpg               │ <- Game content (what players see)
├────────────────────────────────────────┤
│           maid-stdlib                  │ <- Common components & utilities
├────────────────────────────────────────┤
│           maid-engine                  │ <- Pure infrastructure
└────────────────────────────────────────┘
Package Purpose You Would Modify This For
maid-engine Core infrastructure - networking, ECS, events Building new engine features
maid-stdlib Reusable components and utilities Adding common game mechanics
maid-classic-rpg Classic MUD gameplay Creating game content

Exercises

Practice what you have learned with these exercises.

Exercise 1: Start the Server with Debug Mode

Start the server with debug mode enabled to see verbose logging:

uv run maid server start --debug

What to look for:

  • Additional log messages showing system initialization
  • Event emissions and handler registrations
  • Detailed connection information when clients connect

Press Ctrl+C to stop the server when done.

Exercise 2: Connect via Both Telnet and Web

  1. Start the server normally: uv run maid server start
  2. Open a terminal and connect via Telnet: telnet localhost 4000
  3. Open a browser and navigate to: http://localhost:8080
  4. Create characters with different names in each
  5. Use the who command to see both characters online

What to observe:

  • Both connections work simultaneously
  • Commands entered in one connection do not appear in the other
  • The who command shows all connected players

Exercise 3: Explore Basic Commands

After connecting, try these commands and note what they do:

  1. look - Describe your current room
  2. help - List all available commands
  3. help look - Get detailed help on the look command
  4. north (or another direction) - Move to an adjacent room
  5. look again - See the new room description
  6. inventory (or i) - Check what you are carrying
  7. say Hello everyone! - Say something out loud
  8. quit - Disconnect gracefully

Challenge: Find the starting NPC and try talking to them using the talk command.

Troubleshooting

Connection Refused

If you see "Connection refused" when trying to connect:

  1. Verify the server is running - Check the terminal where you started the server
  2. Check the port - Ensure you are connecting to port 4000 (Telnet) or 8080 (Web)
  3. Try localhost explicitly: 
    telnet 127.0.0.1 4000

Port Already in Use

If you see "Address already in use":

# Check what is using the port
lsof -i :4000

# Use different ports
uv run maid server start --telnet-port 5000 --web-port 9000

Python Version Issues

If you see errors about Python version:

# Check your Python version
python --version

# Use a specific Python version with uv
uv python install 3.12
uv sync

What's Next?

Congratulations! You have successfully installed MAID, started a server, and connected as a player. In the next part of this tutorial, we will dive deep into MAID's architecture to understand how all the pieces fit together.

Coming up in Part 2: Architecture Deep Dive

  • Understanding the Entity Component System (ECS)
  • How the event bus enables decoupled systems
  • The tick-based game loop
  • Content packs and how they work together

< Back to Tutorial Index Next: Part 2 - Architecture >

Quick Reference

Useful Commands

Command Description
uv run maid server start Start the server with defaults
uv run maid server start --debug Start with debug logging
uv run maid --help Show all CLI commands
telnet localhost 4000 Connect via Telnet

Default Ports

Service Port
Telnet 4000
WebSocket 8080

In-Game Commands

Command Alias Description
look l Look around
help ? Get help
inventory i Check inventory
quit - Disconnect