Skip to content

API Reference

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

Package Overview

MAID is organized as a monorepo with five publishable packages, each serving a distinct purpose:

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

+--------------------------------------+
|          maid-registry               |  <-- Plugin registry service
+--------------------------------------+

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

maid-registry

Standalone plugin registry service for content pack discovery and management:

  • REST API - Pack registration, search, and metadata
  • Database - Persistent pack information storage

maid-tutorial-world

Example content pack for learning MAID development:

  • Tutorial Areas - Village, forest, goblin camp, hidden cave
  • Example NPCs - Quest givers, shopkeepers, enemies, boss encounters
  • Item Templates - Weapons, potions, quest items
  • Progress Tracking - Tutorial guidance with contextual hints

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 with notation like "2d6+3"
colorize Apply ANSI colors to text
format_table Create ASCII tables

Additional Resources