🧩 Meiro

Terminal-based maze generation & solving game

Navigate through algorithmically generated mazes with style 🎯

✨ Features

🎮 Interactive Gameplay • Navigate with WASD or arrow keys
🧠 Multiple Algorithms • Recursive Backtracking, Kruskal's MST, Prim's MST
🎨 Beautiful Rendering • Unicode art with emoji characters
⚡ Lightning Fast • Written in Haskell for optimal performance
📦 Zero Dependencies • Single static binary, ready to run
🌍 Cross Platform • macOS (Intel & Apple Silicon) and Linux support

---

🚀 Quick Start

One-line Install

curl -fsSL https://raw.githubusercontent.com/k1-c/meiro/main/install.sh | bash

Or with custom install directory:

curl -fsSL https://raw.githubusercontent.com/k1-c/meiro/main/install.sh | MEIRO_INSTALL_DIR=~/.local/bin bash

Command & Arguments

# Basic usage - start game with default settings
meiro

# Specify maze size (width x height) - both must be odd numbers >= 5
meiro --size 15x15
meiro -s 25x35

# Choose algorithm
meiro --algorithm recursive    # Recursive Backtracking (default)
meiro --algorithm kruskal      # Kruskal's MST
meiro --algorithm prim         # Prim's MST
meiro -a kruskal              # Short form

# Combine options
meiro --size 41x31 --algorithm prim

# Help & version
meiro --help                   # Show help message
meiro --version                # Show version info

Available Options:

Option	Short	Description	Default
--size WxH	-s	Maze dimensions (width x height, both must be odd numbers ≥ 5)	25x15
--algorithm	-a	Generation algorithm (recursive, kruskal, prim)	recursive
--help	-h	Show help message	-
--version	-v	Show version information	-

---

🎯 How to Play

██████████████████████████████
██🏠    ██  ██              ██
██████  ██  ██  ██  ██████  ██
██      ██      ██  ██      ██
██  ██████████████  ██  ██████
██  ██              ██      ██
██  ██████  ██████████████  ██
██          ██          ██  ██
██████████████████  ██  ██  ██
██          ██      ██  ██  ██
██  ██████  ██  ██████████  ██
██  ██          ██          ██
██  ██████████████  ██████████
██                        🤖██
██████████████████████████████

Controls:

• WASD or Arrow Keys • Move around
• Q • Quit game

---

🔬 Algorithms

🌿 Recursive Backtracking (Default)

• Type: Depth-First Search
• Characteristics: Creates long winding passages with high "river" factor
• Performance: O(n) time, O(n) space
• Best for: Classic maze feel with challenging paths

🌊 Kruskal's Algorithm

• Type: Minimum Spanning Tree
• Characteristics: Creates more open areas with shorter dead ends
• Performance: O(n log n) time, O(n) space
• Best for: Balanced difficulty with multiple solution paths

🎯 Prim's Algorithm

• Type: Minimum Spanning Tree (growing tree)
• Characteristics: Creates dense branching with organic growth patterns
• Performance: O(n log n) time, O(n) space
• Best for: Compact mazes with natural-looking structures

---

🏗️ Architecture

Built with modern Haskell practices:

src/
├── Meiro/
│   ├── Types.hs              # Core data types
│   ├── Utils.hs              # Utility functions
│   ├── Rendering.hs          # Terminal rendering
│   ├── Gameplay.hs           # Game logic & input
│   └── Algorithms/
│       ├── RecursiveBacktrack.hs
│       ├── Kruskal.hs        # Union-Find implementation
│       └── Prim.hs           # Set-based algorithm

Tech Stack:

• Language: Haskell with GHC 9.10
• Build System: Stack
• Dependencies: Minimal (only base libraries)
• Testing: Hspec + QuickCheck
• CI/CD: GitHub Actions

---

🛠️ Development

Prerequisites

• Stack
• GHC 9.10.2

Build from Source

git clone https://github.com/k1-c/meiro.git
cd meiro

# Development build
stack build

# Run tests
stack test

# Build optimized binary
stack build --copy-bins --local-bin-path ./dist

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

---

📊 Performance

Metric	Value
Binary Size	~4MB
Memory Usage	<10MB
Startup Time	<100ms
50x50 Maze	<1ms generation

---

🎨 Customization

Meiro supports custom rendering styles through the CellStyle configuration:

customStyle = CellStyle
    { wallChar   = "██"
    , pathChar   = "  "
    , startChar  = "🏠"
    , goalChar   = "🏁"
    , playerChar = "🤖"
    }

---

📋 System Requirements

Supported Platforms:

• macOS 10.15+ (Intel & Apple Silicon)
• Linux x86_64 (Ubuntu 18.04+, etc.)

Requirements:

• Terminal with Unicode support
• 4MB free disk space
• 10MB RAM

---

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Made with ❤️ in Haskell

Report Bug • Request Feature • Contribute