Micromouse Maze Simulator & Editor

A lightweight, high-performance web-based simulator for Micromouse maze design and algorithm testing. Built with modular Vanilla JavaScript, HTML, and CSS.

🚀 Live Demo

Click here to try the Simulator

---

✨ Key Features

🎨 UI/UX & Interactions

• 📱 Mobile-First Design:
  • Responsive Sidebar: Slide-out drawer on mobile with backdrop dimming and "click-to-close" logic.
  • Global Toggle: Decoupled sidebar toggle button located in the global header.
• 👆 Advanced Gestures:
  • Pinch-to-Zoom: Native-like pinch zooming on touch devices.
  • Pan & Drag: Move the maze view freely using touch (mobile) or mouse drag (desktop).
• 🌗 Smart Theme Toggle: Animated Sun/Moon switch for Dark/Light mode.
• ✨ Adaptive Overlay: Status info box automatically fades to transparent when overlapping with the maze grid.
• 🎞️ Enhanced Visualization: New backtracking animation (shrinking nodes) for clearer DFS execution.
• 📸 Image Import: Includes a Python Companion Tool to convert real-world maze photos into compatible .json maps with an interactive GUI editor.

⚡ High Performance & Architecture

• Web Worker Support: Heavy algorithm calculations run in a background thread, ensuring the UI never freezes, even on large maps.
• Modular Design: Codebase split into logical modules (Renderer, Interactions, Animator) for easy maintenance.

🧠 Pathfinding & Simulation

Includes standard algorithms with Visual Animations:

• 🎬 Dual Animation Modes:

• Map Calculation: Visualizes the "search wave" propagation (Flood Fill, BFS, Dijkstra).

• Physical Simulation: Simulates a single mouse agent moving and backtracking (DFS, Wall Follower).

• 🚀 Speed Control: Adjust animation speed in real-time with a slider.

• Supported Algorithms:

• 🌊 Flood Fill: The classic Micromouse algorithm (guaranteed shortest path).

• ⭐ A Search:* Heuristic-based search (Manhattan distance).

• 🔍 Dijkstra: Uniform cost search.

• 🌀 DFS: Depth-First Search with backtracking visualization.

• ⬅️ / ➡️ Wall Follower: Left/Right-Hand rules simulation.

---

📸 Maze Image Converter (Python Tool)

This project includes a powerful offline Python tool located in the tools/ directory. It allows you to convert photos of physical mazes (Classic 16x16 or Half-size 32x32) into JSON format for the simulator.

Features:

• 🖼️ Auto-Detection: Automatically detects maze size from filenames.
• ✨ Interactive GUI: Verify walls and set start/goal positions visually.
• 📐 Auto-Correction: Aligns grids and fixes perspective issues.

👉 Check out the Tool Documentation here (For Traditional Chinese instructions, see 中文說明)

---

🎨 UI/UX

• Dark/Light Theme: Auto-detects system preference.
• 🖱️ Mouse Wheel Zoom: Smooth zooming logic centered on the maze.
• 🌍 Multi-Language: English, Traditional Chinese (繁體中文), and Japanese (日本語).
• 📊 Path Analysis: Real-time stats for Steps, Turns, and Straightaways.

---

📂 Project Structure

The project follows a modular architecture:

micromouse-sim/
├── index.html           # Main entry point
├── style.css            # Styling and CSS variables
├── maps/                # Pre-loaded map files (.json)
├── tools/               # 🐍 Python Utility Tools
│   ├── maze_converter.py    # Image to JSON converter & editor
│   ├── requirements.txt     # Python dependencies
│   ├── README.md            # Tool documentation (English)
│   └── Readme_zh.md         # Tool documentation (Chinese)
│
├── js/
│   ├── setup.js         # Global variables & DOM initialization
│   ├── ui_control.js    # Main controller & Worker communication
│   ├── maze_core.js     # Data model & Hex compression logic
│   ├── maze_worker.js   # Background thread for heavy algorithms
│   ├── i18n.js          # Internationalization
│   ├── maps_index.js    # Map file registry
│   │
│   ├── ui/              # UI Modules
│   │   ├── animator.js      # Animation logic (Step/Time-based)
│   │   ├── interactions.js  # Mouse/Touch events (Drag-to-draw)
│   │   └── renderer.js      # SVG & Grid rendering
│   │
│   ├── utils/           # Utility functions
│   │   └── path_analyzer.js # Path statistics calculation
│   │
│   └── algos/           # Algorithm implementations
│       ├── astar.js
│       ├── bfs.js
│       ├── dfs.js
│       ├── dijkstra.js
│       ├── flood_fill.js
│       ├── manhattan.js
│       └── wall_follower.js

---

📚 Micromouse Resources

Want to learn more about real-world Micromouse competitions? Check out our curated list of events and resources:

• 📄 Introduction & Competition Links (English)
• 📄 電腦鼠介紹與賽事連結 (中文)

---

🚀 Getting Started

Prerequisites

You only need a modern web browser (Chrome, Firefox, Edge, Safari). No npm or backend required.

Note: Due to browser security policies (CORS) regarding Web Workers, this project cannot be run directly by opening the index.html file path (file://) in some browsers.

Local Installation

1. Clone the repository:

git clone https://github.com/yingchaotw/micromouse-sim.git

2. Run a local server (Recommended):

• VS Code: Install "Live Server" extension and click "Go Live".
• Python: python -m http.server
• Node: npx serve

3. Open http://localhost:5500 (or your port) in the browser.

---

🕹 How to Use

1. Setup: Select a size preset (16x16 / 32x32) or enter custom dimensions.

2. Draw Walls:

   • Select "Edit Wall" mode.
   • Draw: Click and drag across grid lines.
   • Move/Pan: Click and drag on empty space (Desktop) or use one finger (Mobile) to pan the view.
   • Zoom: Use Mouse Wheel (Desktop) or Pinch gesture (Mobile).

3. Configure: Set Start (S) and Goal (G) points.

4. Simulate:

• Choose an algorithm.
• Check "🎬 Animate" for visualization.
• Adjust the Speed Slider to control playback.
• Click Run.

---

🤝 Contributing

Contributions are welcome!

1. Fork the project.
2. Create your feature branch (git checkout -b feature/NewFeature).
3. Commit your changes.
4. Push to the branch.
5. Open a Pull Request.

---

📝 License

Distributed under the MIT License. See LICENSE for more information.

---

🙏 Acknowledgements

• Inspired by standard Micromouse competition rules.
• Algorithms based on Graph Theory and Maze Solving techniques.