Skip to content

Content Pack Cookbook

Practical, copy-pasteable recipes for common MUD building patterns. Each recipe is self-contained and uses real MAID APIs.

Recipes

Recipe What You'll Build
Locked Door A key item that unlocks a gated exit using lock expressions
Shop NPC A merchant NPC with inventory, buy/sell commands
Respawning Monster A monster that dies, waits, then respawns automatically
Crafting Station A station where players combine ingredients into items
Timed Event A recurring world event on a timer (e.g., volcano eruption)
Teleport Portal A portal that moves players between rooms or worlds
Weather Effects Dynamic room descriptions that change with the weather
Level Gating Restrict area access to players above a minimum level
Hidden Room A secret exit revealed by a search command
Custom Command Create a brand-new player command from scratch
Player Housing Let players claim rooms and place furniture

How to Use These Recipes

Each recipe follows the same format:

  1. Problem — What you want to accomplish
  2. Solution — Complete, working code you can drop into a content pack
  3. How It Works — Key concepts explained
  4. Variations — Common modifications
  5. See Also — Links to detailed API docs

Where Code Goes

All recipe code lives inside a content pack. If you haven't built one yet, see Your First Content Pack. The typical structure:

my-pack/
├── src/my_pack/
│   ├── __init__.py
│   ├── pack.py          # ContentPack implementation
│   ├── components/      # Custom components
│   ├── systems/         # ECS systems
│   ├── commands/        # Player commands
│   └── events/          # Custom events
└── tests/

Key Imports

Most recipes use these imports:

from uuid import UUID
from maid_engine.core.ecs import Component, System, Entity
from maid_engine.core.events import Event, EventBus
from maid_engine.core.world import World
from maid_engine.commands.registry import CommandRegistry
from maid_engine.commands import CommandContext
from maid_engine.commands.decorators import command
from maid_stdlib.components import (
    HealthComponent, InventoryComponent, DescriptionComponent,
    ItemComponent, NPCComponent, PositionComponent,
)