Visual Editor Guide

The MAID Visual Editor is a browser-based admin UI for designing, balancing, and operating game worlds without leaving your browser. It complements (and in many places, replaces) the legacy in-game @-commands.

Overview

The visual editor is delivered as part of the Admin UI, served from the running MAID server at /admin-ui/. It provides:

• Map Editor — visual room/exit layout backed by React Flow
• Room Inspector — multi-tab editor for room metadata, exits, contents, and arbitrary properties
• Content Browser — fast, filterable catalog of every entity in the world
• NPC / Item / Quest / Dialogue Editors — focused, type-aware forms
• Balance Dashboard — combat curves, economy flow, and content density
• Bulk Editor — spreadsheet-style mass editing with CSV round-trip
• Play Mode — embedded terminal for in-context smoke testing
• YAML Import / Export — round-trip with the Tier 1 content pipeline
• Collaboration — presence indicators, entity locks, change log

Getting Started

1. Build the admin UI once:

   cd packages/maid-engine/admin_frontend
   npm install
   npm run build
   

2. Start the server:

   uv run maid server start
   

3. Open http://localhost:8080/admin-ui/ and log in as a user with at least BUILDER access for write operations (VIEWER is enough for read-only). localhost:8080 and 127.0.0.1:8080 are allowed by default for the admin API and WebSocket. If you serve the UI from a different host or port (e.g., the Vite dev server on :3000, or a custom reverse proxy), add that origin to MAID_ADMIN_ALLOWED_ORIGINS so collaboration WebSocket upgrades succeed.

The left sidebar navigates between editors. The currently active editor is highlighted; routes are deep-linkable.

Map Editor

• Create Room tool — click an empty grid cell. Names default to room-N and can be renamed in the inspector.
• Connect tool — drag from one room to another to create an exit. Direction is inferred from relative position.
• Select / Pan / Erase — change cursor mode using the toolbar or shortcuts.
• Layers — toggle visibility of rooms, exits, NPCs, items, players, and zones from the layer panel.
• Layout modes — force, manual, and grid are persisted across reloads via Zustand persist middleware.

Room Inspector

Opens automatically when a room is selected. Tabs:

• Description — name, short and long descriptions, tags
• Exits — list, lock state, hidden flags, and per-exit messages
• Contents — NPCs and items currently in the room
• Properties — arbitrary key/value metadata, useful for content packs

Dirty fields are highlighted; unsaved changes survive tab switches but are cleared when you change selection (with a confirm prompt).

Content Browser

Search by name, filter by tag or component type. Clicking a room deep-links into the Map Editor (/map?room=<id>). Pagination is server-driven via /admin/entities/.

Planned — drag-and-drop placement of entities directly onto the map editor canvas is not yet implemented.

NPC Editor

Tabs: Identity, Stats, AI Config, Behavior, Schedule. The AI Config tab lets you select a provider, edit the system prompt template, and preview a sample response.

Item Editor

Type-specific forms branch on the item kind (weapon, armor, consumable, key, quest item). Equipment requirements and stat bonuses are validated client-side before submission.

Quest Editor

Visual graph of objectives with React Flow. Branching paths supported via edges with conditions; rewards are configured in the side panel.

Dialogue Editor

Conversation trees with conditional edges, faction/relationship requirements, and effect actions on each node.

Balance Dashboard

Three panels backed by /admin/balance/*:

• Combat — player vs monster HP/DPS curves across levels 1-20
• Economy — currency sources vs sinks with net-flow indicator
• Content Density — rooms / NPCs / items / quests per zone

When a live world is loaded, content density aggregates real data; otherwise representative defaults are returned.

Bulk Editor

Spreadsheet view of any entity type:

• Click any editable cell to mutate; changed cells are highlighted yellow.
• Multi-row select via the header checkbox; batch operations include Delete Selected, Set Tag, and Move to Zone.
• CSV Export writes a download of all currently visible rows.
• CSV Import (Preview / Coming Soon) — accepts a file and previews the parsed rows in a diff table. The Apply step is a stub in the current release; round-trip writes will land in a future iteration. Use maid data load from the CLI for production imports.

Play Mode

Preview / Coming Soon. Play Mode currently uses a mock connection and echoes commands back locally. It is shipped as a UI preview so admins can validate the panel layout; the live wire-up to the player WebSocket endpoint is planned for a follow-up release.

Embedded terminal for testing changes without alt-tabbing:

• Connect to a server address (mock by default).
• Quick action buttons fire look, inventory, who.
• Teleport input fires @goto.
• Session recording stores command and output history in localStorage; recordings can be replayed at original timing.

YAML Import / Export

Round-trip with the Tier 1 pipeline:

• Export — pick entity type and zone, choose canonical or compact format, preview the YAML, then download. Room export is fully supported; NPC and Item export are Preview / Coming Soon and emit a placeholder document pending integration with the live entity stores.
• Import (Preview / Coming Soon) — drag-and-drop a .yaml file or paste its contents, click Parse to validate, and review the diff. The Apply step is a stub in the current release; use the CLI maid data load to actually persist documents.

Collaboration

The editor keeps /admin/ws open and subscribes to the editor and world channels. You will see:

• Avatars of other connected editors with cursor positions
• Lock indicators on entities someone else is currently editing
• A change log feed of recent edits across the team

Locks are best-effort and time out after five minutes.

Keyboard Shortcuts

Shortcut	Context	Action
V	Map	Select tool
C	Map	Create-room tool
X	Map	Connect (exit) tool
H	Map	Pan tool
E	Map	Erase tool
Del / Backspace	Map	Delete selected room(s) / exit
Esc	Map / Inspector	Clear selection / close inspector
Cmd/Ctrl + Z	Any editor	Undo
Cmd/Ctrl + Shift + Z	Any editor	Redo

Planned — Cmd/Ctrl + S (save) and / (focus search) shortcuts are documented for the design but are not yet implemented.

Troubleshooting

• Blank screen after build — make sure npm run build completed and that the server is serving /admin-ui/dist. Hard-refresh to clear the cached shell.
• 401 Unauthorized on every request — your CSRF cookie expired; log out and log back in.
• Map shows no rooms — check the layers panel; the rooms layer may be hidden. Also check the search filter.
• Bulk save reports 0 changes — cells must lose focus before they are registered as dirty; click outside the cell first.
• YAML import "no entities found" — the parser expects a top-level list using - markers; nested mappings without a list root are not yet supported in the preview parser. Use the CLI maid data load for complex documents.
• Play Mode commands echo only — Play Mode uses a mock connection by default. A future release will wire it to the player WebSocket endpoint.