testsAndMisc/python_pkg/puzzle_solver

Sliding-Square Puzzle Solver

Parses a screenshot of a sliding-square puzzle and solves it via BFS.

Setup

cd puzzle_solver
python -m venv .venv && source .venv/bin/activate
pip install opencv-python-headless numpy

Usage

# From workspace root, with venv active:

# Step 1 – Parse screenshot to editable JSON
python -m puzzle_solver parse screenshot.png -o puzzle.json

# Step 2 – Review & fix any "unknown" squares in puzzle.json
#   (set "type" to: normal / portal / teleporter / key / lock)

# Step 3 – Solve
python -m puzzle_solver solve puzzle.json

# One-shot (no manual review)
python -m puzzle_solver run screenshot.png

# Debug overlay (visualise detected squares on image)
python -m puzzle_solver debug screenshot.png -o debug.png

Game mechanics

Square	JSON type	Description
Empty outline	normal	Regular landing square
Solid fill	player	Starting position
Ring inside	goal	Target destination
Inner square offset	portal	Pass through from the side marked by "side"
Antenna line(s)	teleporter	Warp to paired teleporter ("group" id)
Key symbol	key	Removes matching lock ("lock_id")
Lock symbol	lock	Solid until matching key collected, then vanishes

Movement

You slide in a cardinal direction (up/down/left/right) until you hit another square. If you slide off the grid without hitting anything, you die.

Algorithm

BFS over state = (position, set_of_active_locks). Explores all reachable states and returns the shortest move sequence to the goal.