Skip to content

Development Environment Setup

This guide covers setting up your development environment for contributing to MAID.

Prerequisites

  • Python 3.12 or later
  • uv package manager
  • Git

Quick Setup

# Clone your fork
git clone https://github.com/YOUR-USERNAME/MAID.git
cd MAID

# Install all dependencies including dev tools
uv sync --all-extras

# Verify installation
uv run pytest packages/ --collect-only

Development Workflow

1. Create a Feature Branch

Always work on a branch, not main:

git checkout -b feature/my-feature
# or for bug fixes
git checkout -b fix/issue-123-description

2. Start the Development Server

For testing changes interactively:

# Start with hot reload enabled
uv run maid server start --watch --debug

# Connect via telnet
telnet localhost 4000

3. Run Tests Frequently

# Run all tests
uv run pytest packages/

# Run tests for specific package
uv run pytest packages/maid-engine/tests/

# Run with coverage
uv run pytest --cov=packages

4. Lint and Type Check

# Lint with ruff
uv run ruff check packages/

# Type check with mypy
uv run mypy packages/

Package Architecture

MAID is a monorepo with strict package layering:

maid-engine      <- Core infrastructure (no game logic)
     ^
     |
maid-stdlib      <- Common components/utilities
     ^
     |
maid-classic-rpg <- Game content

Important boundaries:

  • maid-engine must not import from other packages
  • maid-stdlib may only import from maid-engine
  • maid-classic-rpg may import from both

Hot Reload

Hot reload allows you to see code changes without restarting the server. For detailed information, see:

Interactive Shell

Use the development shell for quick experimentation:

uv run maid dev shell

This gives you an IPython shell with MAID's modules pre-loaded.

Debugging

Enable Debug Logging

# Via environment variable
MAID_LOG_LEVEL=DEBUG uv run maid server start

# Or via CLI flag
uv run maid server start --debug

Common Issues

Import errors after changes:

Clear Python's module cache:

# Force reimport
uv run pytest --cache-clear

Port already in use:

Check what's using the port:

lsof -i :4000