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:
- Web Admin API (
packages/maid-engine/src/maid_engine/api/admin/)- Admin Frontend (
packages/maid-engine/admin_frontend/)- Building Commands (
packages/maid-stdlib/src/maid_stdlib/commands/building/)- Grid Builder Commands (
packages/maid-engine/src/maid_engine/commands/grid.py)- 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/)- Profiling Tools (
packages/maid-engine/src/maid_engine/profiling/)- i18n Support (
packages/maid-engine/src/maid_engine/i18n/) — Note: The i18n framework (locale management,@languagecommand,TranslatableText, PO/MO tooling) is implemented, but core gameplay commands (look,move,get,drop,inventory) still use hardcoded English strings. Full gameplay i18n is a future enhancement.- Batch Processor (
packages/maid-engine/src/maid_engine/batch/)
Admin & Developer Tools - Implementation Plan¶
Summary¶
This plan covers the implementation of admin and developer tools to bring MAID to feature parity with Evennia. The tools enable:
- Server administrators to manage servers, players, and content via web interface
- World builders to create and modify game content in real-time with in-game commands
- Developers to debug, profile, and iterate on code with hot reload and profiling tools
- Content creators to edit text content with the in-game editor
- International teams to support multiple languages via i18n infrastructure
Total estimated effort: 14 weeks with ~3.5 FTE
Phase 1: Foundation (Weeks 1-4)¶
1.1 Web Admin Backend - Authentication & Core (Week 1-2)¶
Package:
maid-engine| Priority: P0
- [x] Create admin API router structure at
packages/maid-engine/src/maid_engine/api/admin/ - [x]
__init__.py- Module exports - [x]
router.py- Main admin API router - [x]
auth.py- JWT authentication and authorization - [x] Implement
AdminRoleenum with levels: VIEWER, MODERATOR, BUILDER, ADMIN, SUPERADMIN - [x] Implement
AdminUsermodel with user_id, username, role, permissions - [x] Implement JWT token generation and validation
- [x] Add
get_current_admindependency for route protection - [x] Add
require_role(min_role)dependency factory - [x] Implement rate limiting middleware
- [x] Add admin settings to
config/settings.py: - [x]
AdminSettingswith enabled, host, port, secret_key, token_expiry_hours, etc. - [x] Write tests for authentication flow
1.2 Web Admin Backend - Dashboard & Entities (Week 2)¶
Package:
maid-engine| Priority: P0 | Depends on: 1.1
- [x] Implement
dashboard.py: - [x]
GET /admin/dashboard/- ReturnDashboardData(server, player, world metrics) - [x]
ServerMetricsmodel (uptime, tick_rate, memory, cpu) - [x]
PlayerMetricsmodel (online_count, peak_today, total_accounts) - [x]
WorldMetricsmodel (entity_count, room_count, npc_count) - [x]
WebSocket /admin/dashboard/ws- Real-time metrics streaming - [x]
POST /admin/dashboard/metrics/history- Historical time series data - [x] Implement
entities.py: - [x]
GET /admin/entities/- List entities with pagination and filtering - [x]
GET /admin/entities/{id}- Get single entity with all components - [x]
POST /admin/entities/- Create new entity with components - [x]
PUT /admin/entities/{id}/components/{type}- Update component - [x]
DELETE /admin/entities/{id}- Delete entity - [x]
POST /admin/entities/{id}/components- Add component - [x]
DELETE /admin/entities/{id}/components/{type}- Remove component - [x] Add WebSocket infrastructure for real-time updates (
api/admin/websocket.py) - [x] Write tests for dashboard and entity endpoints
1.3 Web Admin Backend - Players & World (Week 3)¶
Package:
maid-engine| Priority: P0 | Depends on: 1.2
- [x] Implement
players.py: - [x]
GET /admin/players/- Search and list player accounts - [x]
GET /admin/players/{id}- Get player account details - [x]
GET /admin/players/{id}/characters- List player's characters - [x]
POST /admin/players/{id}/ban- Ban player with reason/duration - [x]
POST /admin/players/{id}/unban- Unban player - [x]
POST /admin/players/{id}/kick- Disconnect active session - [x]
PUT /admin/players/{id}/access-level- Set access level - [x]
POST /admin/players/{id}/message- Send message to online player - [x] Implement
world.py: - [x]
GET /admin/world/rooms- List rooms by area - [x]
POST /admin/world/rooms- Create room - [x]
PUT /admin/world/rooms/{id}- Update room - [x]
DELETE /admin/world/rooms/{id}- Delete room and exits - [x]
POST /admin/world/exits- Create exit (with bidirectional option) - [x]
DELETE /admin/world/exits/{room_id}/{direction}- Delete exit - [x]
GET /admin/world/graph- Get world as graph for visualization - [x]
GET /admin/world/areas- List areas/zones - [x] Write tests for player and world endpoints
1.4 Web Admin Backend - Logs, Config & Packs (Week 3-4)¶
Package:
maid-engine| Priority: P0 | Depends on: 1.2
- [x] Implement
logs.py: - [x]
GET /admin/logs/- Search historical logs with filters - [x]
GET /admin/logs/loggers- List available logger names - [x]
WebSocket /admin/logs/stream- Real-time log streaming - [x]
POST /admin/logs/export- Export logs to JSON/CSV - [x] Implement
config.py: - [x]
GET /admin/config/- Get all configuration sections - [x]
GET /admin/config/{section}- Get specific section - [x]
POST /admin/config/validate- Validate config changes - [x]
PUT /admin/config/{section}/{key}- Update config value (SUPERADMIN) - [x]
POST /admin/config/reload- Reload from files (SUPERADMIN) - [x] Implement
packs.py: - [x]
GET /admin/packs/- List content packs with status - [x]
GET /admin/packs/{name}- Get pack details - [x]
POST /admin/packs/{name}/reload- Reload pack - [x] Write tests for logs, config, and packs endpoints
1.5 In-Game Building Commands - Core (Week 3)¶
Package:
maid-stdlib| Priority: P0
- [x] Create command structure at
packages/maid-stdlib/src/maid_stdlib/commands/building/ - [x] Implement target resolution system:
- [x]
here- Current room - [x]
me- Player's character - [x]
<name>- Entity by name in room - [x]
#<id>- Entity by ID - [x] Implement
create.py: - [x]
@create <type> <name> [= template]- Create entity - [x] Support types: item, npc, room, exit, container
- [x] Entity factory interface for extensibility
- [x] Template loading and application
- [x] Implement
destroy.py: - [x]
@destroy <target>- Delete single entity with safety checks - [x]
@purge <filter>- Mass delete with confirmation (ADMIN) - [x] Implement
dig.py: - [x]
@dig <direction> [= room_name]- Create room and exit - [x]
@tunnel <direction> <to_room>- Create bidirectional passage - [x] Support flags: --oneway, --door, --locked, --hidden
- [x] Register commands with
AccessLevel.BUILDER - [x] Write tests for creation commands
1.6 In-Game Building Commands - Modification (Week 4)¶
Package:
maid-stdlib| Priority: P0 | Depends on: 1.5
- [x] Implement
describe.py: - [x]
@describe <target> [text]- Set entity description - [x]
@name <target> <new_name>- Rename entity - [x] Implement
set.py: - [x]
@set <target>/<attribute> = <value>- Set attribute - [x] Value type coercion: string, number, boolean, list, dict, null
- [x] Nested path support:
component.field,component[index] - [x]
@attribute <target> <add|remove|list> <attr>- Manage attributes - [x] Implement
examine.py: - [x]
@examine <target> [component]- Detailed inspection - [x] Show all components with full data
- [x] Support flags: --json, --raw, --history
- [x]
@stat <target>- Show entity statistics - [x] Implement
component.py: - [x]
@component <target> add <type> [data]- Add component - [x]
@component <target> remove <type>- Remove component - [x]
@component <target> list- List components - [x] Write tests for modification commands
1.7 In-Game Building Commands - Navigation & Search (Week 4)¶
Package:
maid-stdlib| Priority: P0 | Depends on: 1.5
- [x] Implement
teleport.py: - [x]
@teleport <target> <destination>- Move entity between rooms - [x]
@goto <location>- Move builder to location - [x] Location resolution: room name, #id, coordinates
- [x] Implement
link.py: - [x]
@link <exit> <destination>- Link exit to room - [x]
@unlink <exit>- Remove exit connection - [x] Implement
find.py: - [x]
@find <type> [filter]- Search entities - [x] Filters: name, zone, flag, component, owner, range, level, created, modified
- [x] Wildcard support in patterns
- [x]
@search <query>- Complex queries - [x] Pagination with --limit and --offset
- [x] Implement
copy.py: - [x]
@copy <target> [new_name]- Clone entity - [x] Deep copy all components
- [x] Implement
zone.py: - [x]
@zone create <name>- Create zone - [x]
@zone assign <room> <zone>- Assign room to zone - [x]
@zone list- List zones - [x] Write tests for navigation and search commands
Phase 2: Core Tools (Weeks 5-10)¶
2.1 Hot Reload System - Module Reloading (Week 5)¶
Package:
maid-engine| Priority: P1
- [x] Create reload infrastructure at
packages/maid-engine/src/maid_engine/reload/ - [x] Implement
manager.py: - [x]
ReloadManagerclass with lock for thread safety - [x]
ReloadScopeenum: MODULE, PACKAGE, CONTENT_PACK, SYSTEM, TEMPLATES, ALL - [x]
ReloadResultdataclass with success, changes, errors, rollback_available - [x] Pre/post reload hooks system
- [x] Implement
module_reloader.py: - [x] Build module dependency graph
- [x] Capture references to classes/functions before reload
- [x]
importlib.reload()with cascade support - [x] Update references to point to new implementations
- [x] Handle class instance migration
- [x] Implement
rollback.py: - [x] Snapshot creation before reload
- [x] State restoration on failure
- [x] Snapshot retention with max limit
- [x] Add
ReloadSettingsto config - [x] Write tests for module reloading
2.2 Hot Reload System - Systems & Content Packs (Week 6)¶
Package:
maid-engine| Priority: P1 | Depends on: 2.1
- [x] Implement
system_reloader.py: - [x] Unregister old system from world
- [x] Preserve system state
- [x] Re-register with new implementation
- [x] Update event handlers
- [x] Implement
pack_reloader.py: - [x] Reload content pack data files
- [x] Re-register commands
- [x] Update templates
- [x] Optionally update existing entities from templates
- [x] Implement
watcher.py: - [x] File system watcher using
watchfiles - [x] Debouncing with configurable delay
- [x] Auto-reload on file change (dev mode)
- [x] Add CLI commands:
- [x]
maid dev reload <target>- Reload module/pack/system - [x]
maid dev reload --watch <paths>- Watch mode - [x] Add in-game commands:
- [x]
@reload <type> <target>- Hot reload - [x]
@rollback [snapshot]- Rollback to previous state - [x] Write integration tests
2.3 Profiling Tools - Memory & Query (Week 7)¶
Package:
maid-engine| Priority: P1
- [x] Create profiling infrastructure at
packages/maid-engine/src/maid_engine/profiling/ - [x] Implement
manager.py: - [x]
ProfileManagerclass - [x]
ProfileSessionwith start/stop - [x]
ProfileTypeenum: MEMORY, QUERY, TICK, NETWORK, ALL - [x] Auto-stop after duration
- [x] Implement
memory.py: - [x]
MemoryCollectorusingtracemalloc - [x]
MemorySnapshotwith total, by_type, by_system, top_objects - [x] Snapshot comparison to find leaks
- [x] Stack trace capture (configurable depth)
- [x] Implement
query.py: - [x]
QueryCollectorwrapping document store execute - [x]
QueryProfilewith query, params, duration, rows, stack_trace - [x] Slow query detection (configurable threshold)
- [x] Query statistics aggregation
- [x] Add
ProfilingSettingsto config - [x] Write tests for memory and query profiling
2.4 Profiling Tools - Tick & Reports (Week 8)¶
Package:
maid-engine| Priority: P1 | Depends on: 2.3
- [x] Implement
tick.py: - [x]
TickCollectoras tick observer - [x]
TickProfilewith tick_number, total_ms, by_system, entity_count - [x] Slow tick detection (default: >250ms at 4 TPS)
- [x] Per-system timing aggregation
- [x] Implement
network.py: - [x]
NetworkCollectorfor I/O profiling - [x] Track bytes in/out per connection
- [x] Message type classification
- [x] Implement
reports.py: - [x] HTML report template with Jinja2
- [x] Memory usage visualization
- [x] Query performance charts
- [x] Tick timing breakdown
- [x] JSON export option
- [x] Add CLI commands:
- [x]
maid dev profile --types=memory,tick --duration=60 - [x]
maid dev memory-snapshot - [x] Add in-game commands:
- [x]
@profile start|stop|status|report - [x]
@memory [top|systems|compare] - [x]
@timing [systems|slow|history] - [x] Write integration tests
2.5 i18n Support - Core Infrastructure (Week 9)¶
Package:
maid-engine| Priority: P1
- [x] Create i18n infrastructure at
packages/maid-engine/src/maid_engine/i18n/ - [x] Implement
catalog.py: - [x]
TranslationEntrydataclass - [x]
TranslationCatalogwith PO/MO file parsing - [x]
load()classmethod for file loading - [x]
translate()with context and plural support - [x] Implement
translator.py: - [x]
Translatorservice class - [x]
current_localecontext variable - [x] Locale loading and management
- [x] Fallback chain (target -> fallback -> original)
- [x] Missing translation handler/logging
- [x] Convenience functions:
_(),_n(),_p() - [x] Implement
loader.py: - [x] PO file parsing
- [x] MO file reading
- [x] Plural form handling
- [x] Add
I18nSettingsto config - [x] Write tests for translation
2.6 i18n Support - Extraction & Integration (Week 10)¶
Package:
maid-engine| Priority: P1 | Depends on: 2.5
- [x] Implement
extractor.py: - [x]
MessageExtractorusing AST parsing - [x] Extract from
_(),_n(),_p(),gettext(), etc. - [x] Location tracking (file:line)
- [x] POT file generation
- [x] Implement
middleware.py: - [x] Session locale detection
- [x] Locale context setup for request handling
- [x] Add CLI commands:
- [x]
maid i18n extract --output=messages.pot - [x]
maid i18n init <locale>- Initialize new language - [x]
maid i18n update- Merge new messages into existing PO - [x]
maid i18n compile- Compile PO to MO - [x]
maid i18n check- Report missing/fuzzy translations - [x] Add in-game command:
- [x]
@language [locale|list]- Set/show language - [x] Implement
TranslatableTextfor dynamic content: - [x] Default text + translations dict
- [x]
@set here/description.es = "..."syntax - [x] Create initial
locales/structure with English base - [x] Create Spanish (es) translation skeleton
- [x] Create German (de) translation skeleton
- [x] Write integration tests
Current Scope: The i18n framework and tooling above are implemented, but core gameplay commands in
maid-stdlib(look,move,get,drop,inventory) andmaid-classic-rpg(combat, magic, crafting) do not yet call_()/gettext()— all user-facing strings in those commands are hardcoded English. Only the@languagecommand and@set(forTranslatableTextfields) currently use the i18n system. Wrapping gameplay command strings with_()is a future enhancement.
Phase 3: UX Tools (Weeks 11-13)¶
3.1 MaidEditor - In-Game Text Editor (Week 11)¶
Package:
maid-stdlib| Priority: P2
- [x] Create editor at
packages/maid-stdlib/src/maid_stdlib/utils/editor.py - [x] Implement
EditorBuffer: - [x] Lines list with cursor position
- [x] Undo stack with snapshot tuples
- [x] Redo stack
- [x] Modified flag
- [x] Implement
EditorConfig: - [x] max_lines, max_line_length, tab_width
- [x] auto_indent, show_line_numbers
- [x] syntax_highlight, syntax_type
- [x] Implement
MaidEditor: - [x]
EditorModeenum: VIEW, INSERT, COMMAND, SEARCH - [x] Command mode handlers (VI-like):
- [x] Movement: h, j, k, l, 0, $, gg, G
- [x] Insert: i, a, o, O
- [x] Delete: x, dd
- [x] Copy/paste: yy, p
- [x] Undo/redo: u, Ctrl+r
- [x] Save/quit: :w, :q, :wq, :q!
- [x] Search: /, n, N
- [x] Insert mode with Escape to exit
- [x] Screen rendering with line numbers
- [x] Status line with mode, position, modified indicator
- [x] Add syntax highlighting for Python, YAML, Markdown
- [x] Implement
@edit <target>/<field>command - [x] Write tests for editor operations
3.2 MaidMenu - Dynamic Menu System (Week 12)¶
Package:
maid-stdlib| Priority: P2
- [x] Create menu at
packages/maid-stdlib/src/maid_stdlib/utils/menu.py - [x] Implement
MenuNode: - [x] key, text, node_type, callback, submenu
- [x] enabled, visible, data fields
- [x] Implement
MenuNodeTypeenum: TEXT, OPTION, INPUT, SUBMENU, SEPARATOR, DYNAMIC - [x] Implement
MenuConfig: - [x] title, header, footer, prompt
- [x] back_key, quit_key with text
- [x] columns, auto_number flags
- [x] Implement
MaidMenu: - [x]
add()- Add option with callback - [x]
add_submenu()- Add nested menu - [x]
add_input()- Add text input with validator - [x]
add_separator()- Visual divider - [x]
add_dynamic()- Runtime-generated options - [x]
run()- Main loop returning result - [x] Navigation between menus
- [x] Input validation
- [x] Create example menus:
- [x] Character creation menu
- [x] Shop interface
- [x] Admin function menu
- [x] Write tests for menu navigation
3.3 MaidTable - Formatted Table Display (Week 12)¶
Package:
maid-stdlib| Priority: P2
- [x] Create table at
packages/maid-stdlib/src/maid_stdlib/utils/table.py - [x] Implement
Column: - [x] header, key, width (auto/fixed)
- [x] min_width, max_width, align
- [x] formatter function, color
- [x] Implement
Alignmentenum: LEFT, CENTER, RIGHT - [x] Implement
BorderStyleenum: NONE, ASCII, UNICODE, DOUBLE - [x] Implement
TableConfig: - [x] border style, show_header, show_row_numbers
- [x] zebra_stripe, max_width, padding
- [x] null_value, truncate_marker
- [x] Implement
MaidTable: - [x]
add_column()- Define column - [x]
add_row()- Add data row (positional or dict) - [x]
add_rows()- Add multiple rows - [x]
render()- Generate formatted string - [x] Auto-calculate column widths
- [x] Truncation with ellipsis
- [x] ANSI color support
- [x] Create helper for common tables (inventory, player list, etc.)
- [x] Write tests for table formatting
3.4 Batch Command/Code Processors (Week 13)¶
Package:
maid-engine| Priority: P2
- [x] Create batch processor at
packages/maid-engine/src/maid_engine/batch/ - [x] Implement
BatchProcessor: - [x]
BatchTypeenum: COMMAND, CODE, MIXED - [x]
BatchResultwith success, executed, failed, errors, output - [x]
execute_file()- Load and execute from path - [x]
execute()- Execute content string - [x] Implement command batch execution:
- [x] Parse lines, skip comments (#)
- [x] Handle multi-line with backslash continuation
- [x] Error capture with line numbers
- [x] Continue on error option
- [x] Implement code batch execution:
- [x] Create namespace with engine, world, entities
- [x] Compile and exec Python code
- [x] Support async main() function
- [x] Sandboxing considerations
- [x] Implement mixed batch parsing:
- [x]
#BEGIN CODE/#END CODEmarkers - [x] Interleave commands and code blocks
- [x] Add dry-run mode
- [x] Add CLI commands:
- [x]
maid batch <file> [--type=auto|command|code|mixed] - [x]
maid batch <file> --dry-run - [x] Add in-game command:
- [x]
@batch <file> [--code] [--dry-run] - [x] Add
BatchSettingsto config - [x] Write tests for batch execution
Phase 4: Polish & Integration (Week 14)¶
4.1 Web Admin Frontend (Week 14)¶
Package:
maid-engine| Priority: P0 | Depends on: 1.1-1.4
- [x] Set up React project at
packages/maid-engine/admin_frontend/: - [x] Vite + React + TypeScript
- [x] TailwindCSS for styling
- [x] React Router for navigation
- [x] React Query for data fetching
- [x] Zustand for state management
- [x] Implement authentication:
- [x] Login form
- [x] JWT token storage
- [x] Protected routes
- [x] Implement Dashboard:
- [x] Server metrics cards
- [x] Player activity chart (Recharts)
- [x] Content pack list
- [x] Recent events feed
- [x] WebSocket for real-time updates
- [x] Implement Entity Browser:
- [x] Filterable entity list
- [x] Component tree view
- [x] Inline editing
- [x] Create/delete entities
- [x] Implement Player Manager:
- [x] Player search and list
- [x] Player detail view
- [x] Ban/unban/kick actions
- [x] Message sending
- [x] Implement World Editor:
- [x] Room graph visualization (reactflow)
- [x] Room property editor
- [x] Exit management
- [x] Area grouping
- [x] Implement Log Viewer:
- [x] Real-time log stream
- [x] Level and logger filters
- [x] Search functionality
- [x] Implement Config Editor:
- [x] Section navigation
- [x] JSON Schema validation
- [x] Change preview
- [x] Build and integrate into static files
- [ ] Write E2E tests with Playwright (stub - test suite uses placeholder
echo "TODO: Add Vitest tests")
4.2 Documentation (Week 14)¶
All packages
- [x] Update CLAUDE.md with new commands
- [x] Write admin API documentation (OpenAPI) - Implemented via FastAPI auto-generation at
/api/docs,/api/redoc, and/api/openapi.json. Seedocs/rest_api.mdanddocs/api/admin.mdfor comprehensive endpoint documentation. - [x] Create building commands reference guide
- [x] Write hot reload usage guide
- [x] Create profiling tools tutorial
- [x] Write i18n contributor guide
- [x] Create translation workflow documentation
- [x] Add docstrings to all public APIs
- [x] Create example batch files
4.3 Integration Testing (Week 14)¶
All packages
- [x] Integration tests for admin API with real database
- [x] End-to-end tests for building commands
- [x] Hot reload tests with running game
- [x] Profiling overhead benchmarks
- [x] i18n tests with multiple locales
- [x] Menu/table rendering tests
- [x] Batch execution tests with fixtures
- [x] Performance regression tests
4.4 Security Audit (Week 14)¶
Package:
maid-engine
- [x] Review admin API authentication
- [x] Verify role-based access control
- [x] Audit code batch execution sandboxing
- [x] Check for injection vulnerabilities in set commands
- [x] Validate rate limiting effectiveness
- [x] Review CORS configuration
- [x] Ensure secrets not logged
Dependencies Summary¶
Phase 1:
1.1 Auth → 1.2 Dashboard/Entities → 1.3 Players/World → 1.4 Logs/Config
1.5 Build Core → 1.6 Build Modify → 1.7 Build Nav/Search
Phase 2:
2.1 Reload Core → 2.2 Reload Systems/Packs
2.3 Profile Core → 2.4 Profile Tick/Reports
2.5 i18n Core → 2.6 i18n Extraction
Phase 3:
3.1 Editor (standalone)
3.2 Menu (standalone)
3.3 Table (standalone)
3.4 Batch (depends on command infrastructure)
Phase 4:
4.1 Frontend → Depends on all Phase 1 backend
4.2-4.4 → Depends on all prior phases
Resource Allocation¶
| Role | FTE | Primary Focus |
|---|---|---|
| Backend Developer | 1.0 | Web Admin API, Hot Reload, Profiling |
| Frontend Developer | 0.5 | Web Admin React UI |
| Systems Developer | 1.0 | Building Commands, Batch Processor |
| Infrastructure | 0.5 | i18n, Editor/Menu/Table |
| QA Engineer | 0.5 | Testing, Documentation |
Success Criteria¶
- [x] Web Admin dashboard shows real-time server metrics
- [x] All 25+ building commands implemented and tested
- [x] Hot reload succeeds >95% of attempts
- [x] Profiling overhead <5% when enabled
- [ ] 80% translation coverage for English, Spanish, German — Not yet achieved: core gameplay commands still use hardcoded English strings and do not call
_()/gettext() - [x] Test coverage >80% across all new code
- [x] All endpoints documented in OpenAPI spec - FastAPI auto-generates OpenAPI documentation from endpoint definitions, Pydantic models, and docstrings. Available at
/api/docs(Swagger UI),/api/redoc(ReDoc), and/api/openapi.json.