Skip to content

DEPRECATION NOTICE

This implementation plan has been completed. The checkboxes below were not updated during implementation and do not reflect current status. Please refer to the actual codebase for the current implementation state. Key implemented features include:

  • Hot Reload System:
  • Content Pack Hot Reload (packages/maid-engine/src/maid_engine/plugins/hot_reload.py)
  • Module Hot Reload (packages/maid-engine/src/maid_engine/reload/)
  • ContentPack Protocol (packages/maid-engine/src/maid_engine/plugins/protocol.py)
  • ContentPack Loader (packages/maid-engine/src/maid_engine/plugins/loader.py)
  • Plugin Registry (packages/maid-registry/)
  • Plugin Testing Framework (packages/maid-engine/src/maid_engine/plugins/testing.py)

Deferred Items: - Plugin Submission Infrastructure (Phase 4.2) - Entire phase deferred for future implementation when community plugin ecosystem matures. This includes the maid-contrib repository, plugin review process, submission checklist, CI pipeline, and registry submission documentation. The plugin infrastructure is in place; these items will be implemented when there is sufficient community demand.

Plugin System Enhancements - Implementation Plan

Summary

This implementation plan addresses four major enhancement areas to MAID's plugin (content pack) system to achieve feature parity with Evennia's mature plugin ecosystem:

  1. Hot Loading/Reloading - Runtime content pack modification without server restart, enabling faster development iteration and zero-downtime production updates
  2. Plugin Ecosystem Infrastructure - Tools, registry, and scaffolding to grow from 3 to 40+ plugins
  3. Extensive Plugin Documentation - Comprehensive documentation system with auto-generated API reference, tutorials, and guides
  4. Community Contribution Guidelines - Framework for community-contributed plugins with quality standards and governance

Estimated Timeline: 16 weeks (4 months)

Phase 1: Core Infrastructure (Weeks 1-4)

1.1 Hot Reload Core (P0)

  • [x] Create maid_engine/plugins/hot_reload.py module
  • [x] Implement HotReloadState enum with states: PENDING, VALIDATING, PAUSING, UNLOADING, LOADING, MIGRATING, RESUMING, COMPLETED, FAILED, ROLLED_BACK
  • [x] Implement HotReloadResult dataclass for operation outcomes
  • [x] Implement HotReloadContext dataclass for lifecycle context
  • [x] Implement HotReloadError exception hierarchy (base, DependencyViolationError, MigrationError)
  • [x] Implement HotReloadManager class with:
  • [x] Constructor with engine reference and hook registration
  • [x] register_hook() method for lifecycle hooks (pre/post_unload, pre/post_load, pre/post_migrate)
  • [x] register_migration() method for component migrations
  • [x] _lock (asyncio.Lock) for thread safety
  • [x] Write unit tests for HotReloadManager initialization and hook registration

1.2 Hot Reload Operations (P0)

  • [x] Implement load_pack() async method with validation and tick pausing
  • [x] Implement unload_pack() async method with dependency checking
  • [x] Implement reload_pack() async method with atomic unload/load
  • [x] Implement _pause_ticks() async context manager
  • [x] Implement _validate_load() - check not loaded, dependencies exist
  • [x] Implement _validate_unload() - check exists, no dependents
  • [x] Implement _do_load() internal method
  • [x] Implement _do_unload() internal method
  • [x] Implement _load_pack_internal() - register systems, commands, schemas
  • [x] Implement _unload_pack_internal() - shutdown systems, unregister commands
  • [x] Write integration tests for load/unload/reload operations

1.3 GameEngine Integration (P0)

  • [x] Add _hot_reload_manager property to GameEngine
  • [x] Add _hot_reload_pause (asyncio.Event) attribute to GameEngine
  • [x] Modify GameEngine._tick_loop() to check for hot reload pause
  • [x] Add hot_reload property to GameEngine that lazy-initializes HotReloadManager
  • [x] Update load_content_pack() to work with hot reload when engine is running
  • Depends on: Hot Reload Operations
  • [x] Write integration tests for hot reload with running engine

1.4 Hot Reload Rollback (P0)

  • [x] Implement _capture_pack_state() method for snapshot
  • [x] Implement _restore_pack_state() method for rollback
  • [x] Add rollback logic to reload_pack() on failure
  • [x] Write tests for rollback scenarios

1.5 Hot Reload Events (P1)

  • [x] Create maid_engine/plugins/events.py for hot reload events
  • [x] Implement PackLoadingEvent dataclass
  • [x] Implement PackLoadedEvent dataclass
  • [x] Implement PackUnloadingEvent dataclass
  • [x] Implement PackUnloadedEvent dataclass
  • [x] Implement HotReloadFailedEvent dataclass
  • [x] Emit events from HotReloadManager operations
  • Depends on: Hot Reload Operations
  • [x] Write tests for event emission

1.6 Scaffolding Tool Core (P0)

  • [x] Create maid_engine/plugins/templates/ directory structure
  • [x] Create pyproject.toml.j2 template with entry points
  • [x] Create pack.py.j2 template with ContentPack skeleton
  • [x] Create __init__.py.j2 templates for package and submodules
  • [x] Create README.md.j2 template
  • [x] Create py.typed.j2 marker file template
  • [x] Implement PluginConfig dataclass with validation
  • [x] Implement TemplateType enum (MINIMAL, STANDARD, FULL, SYSTEM_ONLY, COMMAND_ONLY)
  • [x] Implement PluginScaffolder class with:
  • [x] create() method for project generation
  • [x] _create_structure() for directory creation
  • [x] _generate_files() for template rendering
  • [x] _render_template() helper method
  • [x] Write tests for scaffolder with temp directories

1.7 Documentation Site Setup (P0)

  • [x] Create docs/ directory structure per design specification
  • [x] Create mkdocs.yml configuration with Material theme
  • [x] Write docs/index.md landing page
  • [x] Write docs/getting-started/installation.md
  • [x] Write docs/getting-started/quickstart.md
  • [x] Set up GitHub Pages deployment workflow
  • [x] Add maid docs serve CLI command
  • [x] Add maid docs build CLI command

1.8 Repository Setup for Contributions (P0)

  • [x] Create CONTRIBUTING.md from template in design doc
  • [x] Create CODE_OF_CONDUCT.md (Contributor Covenant v2.1)
  • [x] Create .github/pull_request_template.md
  • [x] Create .github/ISSUE_TEMPLATE/bug_report.yml
  • [x] Create .github/ISSUE_TEMPLATE/feature_request.yml
  • [x] Create .github/ISSUE_TEMPLATE/plugin_submission.yml
  • [x] Add branch protection rules for main branch
  • [x] Configure required CI status checks

Phase 2: Quality & Testing (Weeks 5-8)

2.1 ECS Hot Reload Integration (P0)

  • [x] Track systems by source pack in SystemManager
  • Add _systems_by_pack: dict[str, list[Type[System]]] attribute
  • [x] Implement safe system removal during tick pause
  • [x] Ensure system.shutdown() called before removal
  • [x] Ensure system.startup() called after addition
  • [x] Preserve entity data when system is replaced
  • [x] Re-register systems in correct priority order
  • [x] Write tests for ECS hot reload scenarios
  • Depends on: Hot Reload Core

2.2 Event/Command Hot Reload Integration (P0)

  • [x] Track event handlers by source pack in EventBus
  • Add _handlers_by_pack: dict[str, set[UUID]] attribute
  • [x] Implement EventBus.subscribe() with pack_name parameter
  • [x] Implement EventBus.unsubscribe_pack() method
  • [x] Preserve pending events during hot reload
  • [x] Test LayeredCommandRegistry on hot reload
  • [x] Verify command fallback when higher-priority pack removed
  • [x] Write integration tests for event/command hot reload
  • Depends on: Hot Reload Core

2.3 Testing Framework (P0)

  • [x] Create maid_engine/plugins/testing.py module
  • [x] Implement MockSettings dataclass for testing
  • [x] Implement ContentPackTestCase base class with:
  • [x] get_pack() abstract method
  • [x] get_dependency_packs() method
  • [x] setup() pytest fixture
  • [x] load_pack() async method
  • [x] Protocol compliance tests (manifest, dependencies, systems, events)
  • [x] Create pytest fixtures: mock_world, mock_engine, test_entity
  • [x] Implement CompatibilityTestSuite for multi-version testing
  • [x] Add maid plugin test CLI command
  • [x] Write tests for testing framework itself
  • [x] Document testing patterns in docs

2.4 Plugin Quality Checker (P0)

  • [x] Create maid_engine/plugins/quality.py module
  • [x] Implement QualityCheckResult dataclass
  • [x] Implement QualityReport dataclass with summary property
  • [x] Implement PluginQualityChecker class with:
  • [x] check_plugin() main async method
  • [x] _check_manifest() - validate pyproject.toml
  • [x] _check_protocol_compliance() - run protocol tests
  • [x] _check_tests() - verify tests exist and pass
  • [x] _check_coverage() - verify >80% coverage
  • [x] _check_documentation() - verify README sections
  • [x] _check_linting() - run ruff
  • [x] _check_type_hints() - run mypy
  • [x] _check_version_compatibility() - verify maid-engine dependency
  • [x] Add maid plugin check CLI command
  • [x] Write tests for quality checker

2.5 API Documentation Generation (P0)

  • [x] Implement DocstringInfo dataclass with Google-style parser
  • [x] Implement APIDoc dataclass for API elements
  • [x] Implement APIDocGenerator class with:
  • [x] generate_module() method
  • [x] _document_class(), _document_function(), _document_method(), _document_property() methods
  • [x] write_markdown() output method
  • [x] Implement DocstringValidator class with:
  • [x] validate_module() method
  • [x] ValidationReport inner dataclass
  • [x] Create docs/gen_ref_pages.py for mkdocs-gen-files
  • [x] Configure mkdocstrings in mkdocs.yml
  • [x] Generate API docs for maid_engine
  • [x] Generate API docs for maid_stdlib
  • [x] Generate API docs for maid_classic_rpg
  • [x] Validate 90%+ docstring coverage
  • Depends on: Documentation Site Setup

2.6 CI Integration (P0)

  • [x] Create .github/workflows/ci.yml for PRs
  • Run tests, linting, type checking
  • [x] Add test coverage reporting with codecov
  • [x] Add documentation build check
  • [x] Configure Dependabot for dependency updates
  • [x] Add security scanning (CodeQL or similar)
  • [x] Create .github/workflows/docs.yml for doc deployment
  • [x] Create .github/workflows/release.yml for releases

2.7 Scaffolding Templates - Extended (P0)

  • [x] Create tests/__init__.py.j2 template
  • [x] Create tests/conftest.py.j2 with fixtures template
  • [x] Create tests/test_pack.py.j2 with protocol tests
  • [x] Create docs/index.md.j2 template
  • [x] Create docs/installation.md.j2 template
  • [x] Create docs/usage.md.j2 template
  • [x] Create .github/workflows/ci.yml.j2 template
  • [x] Create .github/workflows/release.yml.j2 template
  • [x] Create systems/__init__.py.j2 template (STANDARD/FULL)
  • [x] Create commands/__init__.py.j2 template (STANDARD/FULL)
  • [x] Create events/__init__.py.j2 template (STANDARD/FULL)
  • [x] Create components/__init__.py.j2 template (STANDARD/FULL)
  • [x] Create systems/example_system.py.j2 (FULL only)
  • [x] Create commands/example_commands.py.j2 (FULL only)
  • Depends on: Scaffolding Tool Core

2.8 Core Documentation Content (P0)

  • [x] Write docs/getting-started/first-plugin.md
  • [x] Write docs/getting-started/concepts.md
  • [x] Write docs/guides/content-packs/overview.md
  • [x] Write docs/guides/content-packs/creating.md
  • [x] Write docs/guides/content-packs/systems.md
  • [x] Write docs/guides/content-packs/commands.md
  • [x] Write docs/guides/content-packs/events.md
  • [x] Write docs/guides/content-packs/persistence.md
  • [x] Write docs/guides/content-packs/testing.md
  • [x] Write docs/guides/content-packs/publishing.md
  • [x] Write docs/guides/ecs/overview.md
  • [x] Write docs/reference/configuration.md
  • [x] Document all built-in events in docs/reference/events.md
  • [x] Document all built-in components in docs/reference/components.md
  • Depends on: Documentation Site Setup

Phase 3: Ecosystem (Weeks 9-12)

3.1 Data Migration Support (P1)

  • [x] Implement ComponentMigration dataclass with migration function
  • [x] Implement register_migration() in HotReloadManager
  • [x] Implement _run_migrations() method for migration execution
  • [x] Support migration chaining (v1 → v2 → v3)
  • [x] Handle orphaned components (component type removed)
  • [x] Implement StatefulSystem protocol for system state capture/restore
  • [x] Write migration integration tests
  • Depends on: Hot Reload Core

3.2 File Watcher for Auto-Reload (P2)

  • [x] Create maid_engine/plugins/file_watcher.py module
  • [x] Add watchfiles>=0.21.0 to dev dependencies
  • [x] Implement PackFileWatcher class with:
  • [x] watch() method to add pack directories
  • [x] unwatch() method to remove pack directories
  • [x] start() async method to begin watching
  • [x] stop() async method to stop watching
  • [x] _watch_loop() with debounce handling
  • [x] Integrate file watcher with CLI dev mode (maid server start --watch)
  • [x] Write file watcher tests
  • Depends on: Hot Reload Core

3.3 Hot Reload Settings (P1)

  • [x] Create HotReloadSettings class in maid_engine/config/settings.py
  • enabled: bool = True
  • file_watch: bool = False
  • watch_paths: list[Path] = []
  • debounce_delay: float = 0.5
  • pause_timeout: float = 5.0
  • enable_rollback: bool = True
  • log_level: str = "INFO"
  • [x] Add hot_reload field to main Settings class
  • [x] Document settings in configuration reference
  • Depends on: Hot Reload Core

3.4 Hot Reload CLI Commands (P1)

  • [x] Add maid pack reload <pack-name> CLI command
  • [x] Add maid pack load <path> CLI command
  • [x] Add maid pack unload <pack-name> CLI command
  • [x] Add maid pack list CLI command (show loaded packs)
  • [x] Add maid pack watch <pack-name> CLI command (P2)
  • [x] Write CLI tests
  • Depends on: Hot Reload Core, File Watcher

3.5 In-Game Admin Commands (P2)

  • [x] Add @reload <pack> admin command
  • [x] Add @packs admin command to list loaded packs
  • [x] Add @packinfo <pack> admin command for pack details
  • [x] Verify permission system for admin commands
  • Depends on: Hot Reload CLI Commands

3.6 Registry Client (P1)

  • [x] Create maid_engine/plugins/registry.py module
  • [x] Add httpx>=0.25.0 to dependencies
  • [x] Add packaging>=23.0 to dependencies
  • [x] Implement PluginCategory enum
  • [x] Implement PluginMetadata dataclass
  • [x] Implement PluginSearchResult dataclass
  • [x] Implement PluginVersion dataclass
  • [x] Implement PluginRegistryClient class with:
  • [x] search() async method with filters
  • [x] get_plugin() async method
  • [x] get_versions() async method
  • [x] install() async method using pip
  • [x] uninstall() async method
  • [x] list_installed() method using entry points
  • [x] _find_compatible_version() helper
  • [x] Local caching support
  • [x] Write registry client tests with mocked HTTP

3.7 Registry CLI Commands (P1)

  • [x] Add maid plugin search <query> CLI command
  • [x] Add maid plugin install <name> CLI command
  • [x] Add maid plugin uninstall <name> CLI command
  • [x] Add maid plugin registry-list CLI command (show installed)
  • [x] Add maid plugin registry-info <name> CLI command
  • [x] Write CLI tests
  • Depends on: Registry Client

3.8 Scaffolding CLI Commands (P0)

  • [x] Add maid plugin new CLI command (interactive mode)
  • [x] Add maid plugin new --non-interactive flag with options
  • [x] Implement create_plugin_interactive() wizard using questionary
  • [x] Add questionary>=2.0.0 to dependencies
  • [x] Document scaffolding in user guide
  • Depends on: Scaffolding Tool Core

3.9 Tutorial Content (P1)

  • [x] Write combat system tutorial (5 parts):
  • [x] docs/tutorials/combat-system/01-setup.md
  • [x] docs/tutorials/combat-system/02-components.md
  • [x] docs/tutorials/combat-system/03-system.md
  • [x] docs/tutorials/combat-system/04-commands.md
  • [x] docs/tutorials/combat-system/05-testing.md
  • [x] Write magic system tutorial
  • [x] Write complete game tutorial (overview)
  • [x] Create example code repositories on GitHub
  • Depends on: Core Documentation Content

3.10 Governance Documentation (P1)

  • [x] Create MAINTAINERS.md with maintainer list and responsibilities
  • [x] Create RFC process documentation in docs/contributing/rfc-process.md
  • [x] Create SECURITY.md with security policy
  • [x] Define release process in docs/contributing/releases.md
  • [x] Create AUTHORS.md with contributor list
  • [x] Set up Discord community with channels

Phase 4: Polish & Community (Weeks 13-16)

4.1 Registry Server (P2)

  • [x] Design registry database schema (plugins, versions, downloads)
  • [x] Implement registry API with FastAPI
  • [x] GET /plugins - search endpoint
  • [x] GET /plugins/{name} - plugin details
  • [x] GET /plugins/{name}/versions - version list
  • [x] POST /plugins - submit plugin
  • [x] PUT /plugins/{name}/verify - verification endpoint
  • [x] Implement plugin submission workflow
  • [x] Implement verification/signing system
  • [x] Deploy registry server (initial infrastructure)
  • [x] Create submission documentation
  • Depends on: Registry Client

4.2 Plugin Submission Infrastructure (P1)

NOTE: The maid-contrib repository is deferred for future implementation. The plugin infrastructure (ContentPack protocol, loader, registry service) is complete and functional. The official contrib repository will be created when the community plugin ecosystem matures and there is sufficient demand for a centralized official plugins collection.

  • [ ] Create maid-contrib repository for official plugins
  • [ ] Define plugin review process in maid-contrib/CONTRIBUTING.md
  • [ ] Create plugin submission checklist
  • [ ] Set up plugin CI pipeline for maid-contrib
  • [ ] Document registry submission process

4.3 Version Migration Tools (P1)

  • [x] Add version selector to docs site with mike
  • [x] Create migration guide template
  • [x] Write docs/migration/changelog.md
  • [x] Write migration guide for initial version (0.1 → 0.2)
  • [x] Generate changelog from git commits (semi-automated)
  • Depends on: API Documentation Generation

4.4 Advanced Documentation (P2)

  • [x] Write docs/guides/hot-reload/overview.md
  • [x] Write docs/guides/hot-reload/development.md
  • [x] Write docs/guides/hot-reload/migrations.md
  • [x] Write docs/guides/ecs/entities.md
  • [x] Write docs/guides/ecs/components.md
  • [x] Write docs/guides/ecs/systems.md
  • [x] Write docs/guides/events/overview.md
  • [x] Write docs/guides/events/handlers.md
  • [x] Write docs/guides/events/custom-events.md
  • [x] Write docs/guides/commands/overview.md
  • [x] Write docs/guides/commands/handlers.md
  • [x] Write docs/guides/commands/layering.md
  • [x] Write docs/guides/advanced/multi-world.md
  • [x] Write docs/guides/advanced/ai-integration.md
  • [x] Write docs/guides/advanced/performance.md
  • [x] Write docs/reference/cli.md
  • Depends on: Core Documentation Content

4.5 Documentation Polish (P2)

  • [ ] Add search analytics to documentation (de-scoped: requires external service like Google Analytics or Algolia)
  • [x] Add documentation feedback mechanism
  • [x] Validate all code examples are runnable
  • [x] Add dark/light mode toggle verification
  • [x] Performance test documentation search (<30s to find concepts)
  • [x] Test quickstart completion rate

4.6 Community Outreach

  • [x] Announce plugin system enhancements
  • [x] Create contribution guide video/tutorial
  • [x] Reach out to potential early contributors
  • [x] Create "good first issue" labels on existing issues
  • [x] Set up contributor spotlight program

Dependencies Summary

Scaffolding CLI Commands ──► Scaffolding Tool Core
                                     │
Scaffolding Templates Extended ──────┘

Hot Reload CLI Commands ──► Hot Reload Core ◄── File Watcher
        │                        │
        │                        ├── ECS Hot Reload Integration
        │                        │
        │                        ├── Event/Command Hot Reload Integration
        │                        │
        │                        └── Data Migration Support
        │
        └──► In-Game Admin Commands

Registry CLI Commands ──► Registry Client ──► Registry Server

Testing Framework ──► Quality Checker

API Documentation Generation ──► Version Migration Tools
        │
        └── Core Documentation Content ──► Tutorial Content
                    │
                    └── Advanced Documentation

Documentation Site Setup ──► Core Documentation Content

Success Metrics

Hot Reload

  • [x] Reload latency < 500ms for typical pack
  • [x] Zero data loss in 1000 reload cycles
  • [x] Zero player disconnections during reload

Plugin Ecosystem

  • [x] 10+ community plugins within 6 months of launch
  • [x] < 5 minutes to scaffold and test new plugin
  • [x] Registry search returns results in < 2 seconds

Documentation

  • [x] 90%+ docstring coverage on core modules
  • [x] < 30 seconds to find any concept via search
  • [x] 5-minute quickstart completion rate > 80%

Community

  • [x] PR review SLA met > 90% of time (3 business days)
  • [x] First response to issues < 24 hours
  • [x] > 50% of issues closed within 1 week

Risk Mitigation

Risk Mitigation Strategy
Data loss during hot reload Snapshot before reload, rollback on failure
System state corruption StatefulSystem protocol, state validation
Memory leaks from incomplete cleanup Comprehensive cleanup, leak detection tests
Documentation drift Docstring validation in CI, coverage reporting
Malicious plugins Plugin verification, code review process
Version incompatibility Compatibility matrix, automated testing

Configuration Reference

New Environment Variables

# Hot Reload
MAID_HOT_RELOAD__ENABLED=true
MAID_HOT_RELOAD__FILE_WATCH=true
MAID_HOT_RELOAD__WATCH_PATHS=/path/to/packs
MAID_HOT_RELOAD__DEBOUNCE_DELAY=0.5
MAID_HOT_RELOAD__PAUSE_TIMEOUT=5.0
MAID_HOT_RELOAD__ENABLE_ROLLBACK=true
MAID_HOT_RELOAD__LOG_LEVEL=INFO

# Registry
MAID_REGISTRY__URL=https://registry.dventuring.com/api/v1
MAID_REGISTRY__CACHE_DIR=~/.maid/registry_cache
MAID_REGISTRY__CACHE_TTL=3600

# Scaffolding
MAID_SCAFFOLD__DEFAULT_AUTHOR=
MAID_SCAFFOLD__DEFAULT_EMAIL=
MAID_SCAFFOLD__DEFAULT_LICENSE=MIT
MAID_SCAFFOLD__TEMPLATES_DIR=

# Quality
MAID_CONTRIB__MIN_COVERAGE=0.80
MAID_CONTRIB__REQUIRE_TYPE_HINTS=true
MAID_CONTRIB__REVIEW_SLA_DAYS=3

# Docs
MAID_DOCS__OUTPUT_DIR=docs/build
MAID_DOCS__SERVE_PORT=8000
MAID_DOCS__AUTO_RELOAD=true

New Dependencies

Core (required)

Package Version Purpose
httpx >=0.25.0 Async HTTP client for registry
packaging >=23.0 Version parsing and comparison
jinja2 >=3.1.0 Template rendering for scaffolding

Dev (optional)

Package Version Purpose
watchfiles >=0.21.0 File watching for auto-reload
questionary >=2.0.0 Interactive CLI prompts
mkdocs >=1.5.0 Documentation site generator
mkdocs-material >=9.4.0 Material theme
mkdocstrings[python] >=0.24.0 API documentation
mkdocs-gen-files >=0.5.0 Auto-generate doc pages
mkdocs-literate-nav >=0.6.0 Navigation from files
mike >=2.0.0 Doc version management