Skip to content

MAID - Multi AI Dungeon

Welcome to the MAID documentation! MAID is a modern MUD (Multi-User Dungeon) engine written in Python 3.12+ that combines traditional MUD gameplay with AI integration.

What is MAID?

MAID is a next-generation MUD engine designed for developers who want to build text-based multiplayer games with modern architecture and AI capabilities. Whether you're creating a classic fantasy RPG, a sci-fi adventure, or something entirely unique, MAID provides the infrastructure you need.

Key Features

AI Integration

  • Built-in support for multiple AI providers (Anthropic, OpenAI, Ollama)
  • AI-powered NPC dialogue and behavior
  • Content generation tools for rooms, items, and characters

Modern Architecture

  • Entity Component System (ECS) - Flexible, composable game objects
  • Event-driven design - Decouple systems with event bus architecture
  • Async/await throughout - High-performance asynchronous I/O
  • Tick-based game loop - Consistent, predictable game state updates

Content Pack System

  • Modular, pluggable content architecture
  • Hot-reload support for development
  • Layered command system with priority resolution
  • Easy to extend and customize

Network Support

  • Telnet server with full protocol negotiation
  • WebSocket support for modern web clients
  • REST API for external integrations
  • Discord bridge for community integration

Persistence & Data Management

  • Durable entity persistence with automatic dirty tracking
  • Database migration framework with namespace isolation
  • YAML-based data loader pipeline for content ingestion

AI-Powered NPCs

  • NPC memory, relationships, and knowledge graphs
  • Automated quest generation from world state
  • NPC autonomy with needs, goals, and schedules

Player Experience

  • Player web client via WebSocket
  • Contextual hint system and progress tracking

Operational Observability

  • Metrics, tracing, and health checks
  • Prometheus-compatible instrumentation
  • AI cost tracking and token budgets

Developer Experience

  • Comprehensive CLI tools
  • Built-in profiling and debugging
  • Full type hints with MyPy strict mode
  • Extensive test coverage

Project Structure

MAID is organized as a monorepo with five publishable packages:

  • maid-engine - Core infrastructure (ECS, networking, auth, storage, plugin system)
  • maid-stdlib - Reusable components, base systems, and utilities
  • maid-classic-rpg - Traditional MUD gameplay content pack
  • maid-registry - Plugin registry server for content pack discovery and management
  • maid-tutorial-world - Beginner-friendly tutorial content pack demonstrating MAID gameplay patterns
maid-classic-rpg / maid-tutorial-world  (Game content)
                |
            maid-stdlib                 (Common components)
                |
            maid-engine                 (Pure infrastructure)

            maid-registry               (Plugin registry service)

Get MAID installed and running on your system

Start your first MAID server in minutes

Learn how to build with MAID

Detailed API documentation

Getting Help

License

MAID is released under the MIT License. See the LICENSE file for details.

Contributing

We welcome contributions! Please see our Contributing Guide for details on how to get started.