Skip to content

MAID Tutorial Series

Welcome to the comprehensive MAID tutorial series! This step-by-step guide will take you from installation to creating your own shareable content pack. Whether you are new to MUD development or an experienced developer looking to learn MAID, this tutorial has you covered.

What You Will Learn

By completing this tutorial series, you will:

  • Install and run a MAID server
  • Understand the core architecture (ECS, events, tick loop)
  • Create custom commands for player interaction
  • Build rooms, items, and connect them into a game world
  • Design NPCs with AI-powered dialogue
  • Implement combat systems and skills
  • Package everything into a reusable, shareable content pack

Prerequisites

Before starting, ensure you have:

  • Python 3.12 or higher - MAID uses modern Python features
  • Basic Python knowledge - Familiarity with classes, async/await, and type hints
  • A terminal/command line - You will run commands throughout the tutorials
  • A text editor or IDE - VS Code, PyCharm, or similar recommended
  • Git - For cloning the MAID repository

Estimated Total Time

The complete tutorial series takes approximately 4-5 hours to complete. You can work through it at your own pace, completing one part at a time.

Tutorial Parts

Part 1: Installation & First Run

Estimated time: 15 minutes

Get MAID up and running on your system. Install dependencies, start your first server, and connect as a player to explore the basics.

  • Install MAID with uv package manager
  • Start the server with Telnet and WebSocket support
  • Connect via Telnet and web browser
  • Create a character and explore basic commands
  • Understand the project directory structure

Part 2: Architecture Deep Dive

Estimated time: 20 minutes

Understand how MAID works under the hood. Learn the patterns that make the engine flexible and extensible.

  • Entity Component System (ECS) pattern
  • The tick-based game loop
  • Event-driven communication with EventBus
  • Content pack architecture and layering

Part 3: Your First Commands

Estimated time: 30 minutes

Create your first player commands. Learn the command system that enables player interaction with the game world.

  • Command handler structure and context
  • The @command decorator and registration
  • Argument parsing with @arguments and @pattern
  • Working with EntityReference for targets
  • Testing commands and registering in content packs

Part 4: Creating Rooms & Items

Estimated time: 45 minutes

Build the tangible world players will explore. Create rooms, connect them with exits, and populate them with items.

  • Room structure and components
  • Creating rooms programmatically
  • Using builder commands (@dig, @describe, @tunnel)
  • Item entities and the ItemComponent
  • Containers and inventory systems
  • Hands-on exercise: Build a 5-room dungeon

Part 5: NPCs & Basic AI

Estimated time: 45 minutes

Bring your world to life with Non-Player Characters. From simple shopkeepers to AI-powered conversationalists.

  • NPC entity structure and components
  • Static dialogue with triggers
  • AI-powered dialogue configuration
  • NPC behaviors (patrol, wander, aggression)
  • Creating merchants with shop inventory
  • Hands-on exercise: Create a village shopkeeper

Part 6: Combat & Skills

Estimated time: 30 minutes

Add action to your game with combat systems and character progression.

  • Tick-based combat architecture
  • Combat components and states
  • Damage calculation and armor
  • Healing mechanics
  • Skills and experience progression
  • Creating custom abilities with cooldowns
  • Hands-on exercise: Create a Power Strike ability

Part 7: Your First Content Pack

Estimated time: 45 minutes

Package everything you have built into a shareable content pack that others can install and use.

  • ContentPack protocol and manifest
  • Package structure and pyproject.toml
  • Using the CLI scaffolder
  • Implementing lifecycle methods (on_load, on_unload)
  • Dependency declaration between packs
  • Building, testing, and publishing to PyPI
  • Hands-on exercise: Package the tutorial dungeon

Getting Started

Ready to begin? Start with Part 1 to install MAID and run your first server.

Start Part 1: Installation

Additional Resources

After completing the tutorial, explore these advanced topics:

Resource Description
Hot Reload Guide Update code without restarting the server
Building Commands Reference Complete guide to in-game building
Command System Guide Advanced argument parsing, hooks, and locks
NPC Dialogue Guide Deep dive into AI dialogue configuration
Admin API Reference REST and WebSocket admin interface
Content Pack System Detailed content pack documentation

Need Help?

If you get stuck during the tutorial: