Skip to content

API Reference

Welcome to the MAID API documentation. This reference covers all three packages that make up the MAID framework.

Package Overview

MAID's core framework is organized as three layered packages, each serving a distinct purpose (the monorepo also ships additional packages such as maid-registry, maid-tutorial-world, and teltest):

+--------------------------------------+
|         maid-classic-rpg             |  <-- Game content
+--------------------------------------+
|           maid-stdlib                |  <-- Common components
+--------------------------------------+
|           maid-engine                |  <-- Pure infrastructure
+--------------------------------------+

maid-engine

The core infrastructure package providing the foundation for all MAID games:

  • Entity Component System (ECS) - Flexible entity management
  • Networking - Telnet and WebSocket connections
  • Authentication - Account and session management
  • Storage - Document-based persistence
  • Content Packs - Plugin system for extensibility
  • AI Integration - LLM provider abstraction
  • i18n - Internationalization support
  • Persistence - Durable entity persistence
  • Migrations - Database migration framework
  • Observability - Metrics, logging, tracing, health checks
  • Loader - World data loader pipeline

maid-stdlib

The standard library package providing reusable building blocks:

  • Components - Health, Inventory, Position, Stats, etc.
  • Systems - Regeneration, position sync, health checks
  • Events - Movement, combat, item interactions
  • Commands - look, move, get, drop, inventory
  • Utilities - Dice rolling, text formatting
  • NPC Memory - Episodic memory system
  • Relationships - NPC relationship tracking
  • Knowledge - Knowledge graph and gossip
  • Quest Generation - Automated quest generation

maid-classic-rpg

The classic MUD content pack providing complete gameplay:

  • Combat System - Turn-based tactical combat
  • Magic System - Spells, effects, mana management
  • Economy - Shops, trading, banking
  • Crafting - Recipes, materials, progression
  • Social - Guilds, factions, achievements
  • Quests - Objectives, rewards, progression
  • NPC Dialogue - AI-powered conversations
  • NPC Autonomy - Needs, goals, schedules, social behavior
  • Quest Generation - Dynamic quest creation from world state

Quick Reference

Core Infrastructure (maid-engine)

Class Description
GameEngine Main game engine - manages tick loop and content packs
World Central state management and entity tracking
EventBus Event-driven communication system
Entity Base entity class for game objects
Component Base class for entity components
System Base class for game systems

Content Pack API

Class Description
ContentPack Protocol defining content pack interface
BaseContentPack Base implementation for content packs
ContentPackLoader Discovers and loads content packs
LayeredCommandRegistry Priority-based command resolution

Storage

Class Description
DocumentStore Abstract document storage interface
InMemoryDocumentStore In-memory implementation for testing
DocumentCollection Collection of documents

Common Components (maid-stdlib)

Component Description
HealthComponent Hit points and health management
ManaComponent Magic points for spellcasting
InventoryComponent Item storage and management
PositionComponent Location tracking
StatsComponent Character attributes (in maid-classic-rpg)

Utilities (maid-stdlib)

Function Description
roll_dice Roll dice (num_dice, sides, modifier) and return a detailed result
colorize Apply ANSI colors to text
format_table Create ASCII tables

Additional Resources