maze_editor

maze_editor

Browser maze editor built with React + Vite + Pyodide.

Runs py_ant_maze directly in the browser by loading a local wheel into Pyodide, so YAML parsing/validation/editing behavior matches the Python package.

Features

• Edit all maze families:
  • 2D: occupancy_grid, edge_grid, radial_arm
  • 3D: occupancy_grid_3d, edge_grid_3d, radial_arm_3d
• Switch 2D/3D mode and maze family from one UI.
• Visual paint tools for cells/walls with click-drag editing.
• Radial-arm controls (arm count, arm size, hub angle, hub size, circular/polygon hub).
• 3D level controls (level selection and level count changes).
• Add new cell/wall elements with token shortcuts.
• YAML editor + format + parse ("Sync to Grid").
• YAML import/export and PNG export (for 3D, exports each level).

Architecture

src/
├── App.tsx                      # Main shell and panel orchestration
├── services/pyodide.ts          # Pyodide init + Python mutation helpers
├── hooks/
│   ├── useMaze.ts               # Main state/actions for parse/edit/create
│   ├── useFileOperations.ts     # Upload/download/export image
│   └── useKeyboardShortcuts.ts  # Token key -> element selection
├── components/
│   ├── editor/                  # Code panel + visual panel wrappers
│   ├── controls/                # Type, size, level, palette, add-element controls
│   ├── layout/                  # Header/loading shells
│   ├── MazeGrid.tsx             # Occupancy/edge rendering + paint
│   └── RadialArmGrid.tsx        # SVG radial-arm rendering + paint
├── constants/defaults.ts        # Default YAML templates and render constants
└── types/maze.ts                # Shared TS maze types

Data flow:

1. useMaze loads Pyodide and installs py_ant_maze wheel.
2. Python-side helpers parse YAML into normalized JSON for the UI.
3. UI actions call Python mutation helpers and round-trip updated YAML/data back.

Use the Editor

Option 1: Deployed

Open https://maze.yihao.one.

Option 2: Local Development

Prerequisites:

• Node.js 18+
• Python 3.10+ (for building the wheel consumed by Pyodide)

1. Build the wheel:

cd ../py_ant_maze
python -m build

2. Start the editor:

cd ../maze_editor
npm install
npm run dev

predev copies ../py_ant_maze/dist/py_ant_maze-0.1.1-py3-none-any.whl into public/ automatically.

Then open the Vite URL shown in terminal (usually http://localhost:5173).

Editing Workflow

1. Choose maze type (and radial hub shape when relevant).
2. Paint cells/walls in the visual grid.
3. Use element palette or keyboard token shortcuts for fast selection.
4. Edit YAML directly in the code panel as needed.
5. Format and Sync to Grid to normalize and re-parse.
6. Export YAML or PNG from the toolbar.

Demo Gallery

Demo	Preview
Maze families and templates
2D and 3D editing
Add start/end points
Occupancy cell size controls
Paint occupancy cells
Edge-grid editing
Add elements and connectors
Radial-arm editing
Radial-arm polygon editing
Save YAML config
Save PNG image