Ice Maze Generator

This repo generates candidate ice-maze puzzle boards, scores them with a native hill-climbing optimizer, deduplicates them by board symmetry, and optionally uploads qualifying results into the mazebench/PuzzleDatabase repository.

The algorithm scores a board by building the full state graph for two moving pieces, finding a longest shortest path (the graph diameter), and measuring how many steps along that path have 3 or more choices. The hill-climber then starts from a random board and toggles walls to improve that score. I find that I can quickly generate very complex puzzles containing 40+ decisions within a small 8x8 box. The more decisions a solution contains the more planning is required.

Requirements

• Python 3.10+ recommended
• g++ with C++20 support
• A GitHub token with access to mazebench/PuzzleDatabase if you want to upload

Python dependencies:

pip install -r requirements.txt

Setup

Create a .env file in the repo root with your GitHub token if you plan to upload:

GITHUB_TOKEN=your_token_here

python-dotenv is supported, but the code also falls back to reading .env manually.

Quick Start

Generate mazes, queue good results locally, and upload them in the same run:

python3 main.py --mode both --count 100

Generate mazes but do not upload them yet:

python3 main.py --mode generate --count 100

Run only the queue uploader against previously generated files:

python3 main.py --mode upload-queue

Upload a large backlog of queued files in batch commits:

python3 main.py --mode upload-queue-batch --upload-batch-size 1000

Useful tuning flags:

• --players: number of synchronized players to solve for
• --width, --height: playable board size
• --wall-prob: random starting wall density
• --max-walls: cap on wall cells, or -1 for no cap
• --max-changes: hill-climb neighborhood size
• --max-threads: thread count for neighborhood evaluation
• --min-result: minimum difficulty required before a result is queued
• --upload-batch-size: number of queued results per commit in upload-queue-batch mode

See all options with:

python3 main.py --help

Lower-Level Worker

worker/run_hillclimb.py is the lower-level runner around the native optimizer. It is useful when you want to test the hill-climber directly without the queue/upload orchestration in main.py.

Example:

python3 worker/run_hillclimb.py --count 10 --players 2 --width 8 --height 8