Metadata-Version: 2.5
Name: magmacrunch-fifteen-puzzle
Version: 0.1.1
Summary: 15 PUZZLE - the classic sliding tile puzzle, 3x3 to 6x6. Terminal version.
Project-URL: Homepage, https://magmacrunch.com/arcade/fifteen-puzzle/
Author: magmacrunch media
License-Expression: PolyForm-Noncommercial-1.0.0
License-File: LICENSE
License-File: NOTICE
Keywords: arcade,games,puzzle,sliding-puzzle,terminal,tui
Requires-Python: >=3.10
Requires-Dist: magmacrunch>=0.13.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# 15 PUZZLE (terminal)

The classic sliding tile puzzle in a terminal, from the 8 puzzle on 3x3 to the
35 puzzle on 6x6. The third version beside `web/` and `wii/`, on the
[magmacrunch](https://github.com/magmacrunch-media/magmacrunch) engine's
terminal backend: a cabinet in the magmacrunch arcade and its own command, the
same either way.

```
pip install -e ".[dev]"
fifteen-puzzle                 # or python -m fifteen
fifteen-puzzle --size 3 --play
```

## Keys

| key | |
|---|---|
| arrows (or WASD, hjkl) | slide the tile beside the gap that way |
| left / right on the title | choose the size, 3x3 to 6x6 |
| `R` | reshuffle |
| `Esc` | the title (from the title, back to the arcade) |
| `Q` | quit |

Put the tiles in order, 1 to N row by row, with the gap bottom right. The score
is the move count, so fewer is better; the time is kept beside it.

## It is the browser's game

`fifteen/rules.py` is `web/js/game.js` plus the part of adenosine-puzzle's
`createGame` it relies on: a move is the left slide with the board rotated
round it, and only a move that changed something counts. `tests/test_oracle.py`
checks it: `tools/js_oracle.mjs` loads the website's `adenosine-puzzle.js` and
`web/js/game.js` unmodified with `Math.random` seeded, shuffles and plays a
hundred and thirty games through the game's own `handleMove()`, every size
mashed and thirty 3x3s solved outright by a breadth-first search, and the test
replays every move through the port and requires the same board, move count
and result after each one. So the shuffle is the browser's too, draw for draw.

The oracle needs the website, for the bundle. It finds it the way
`tools/link-shared.mjs` does: `../shared`, `$WEBSITE`, `../../website`,
`../../../web/website`. CI checks the website out beside the game.

Scores are filed the browser's way: one board, `fifteen-puzzle`, with the size
and the time beside each score, and a top ten per size, fewest moves first. A
run is filed only if it makes its size's ten, as the browser files only what it
asked a name for.

**Fewer is better, which the engine has to be told.** The cabinet declares
`lower_is_better`, and needs `magmacrunch` 0.13.0 or later for it: an older
engine would keep the worst runs and show the longest solve on the arcade floor
as BEST.

Needs a 68x21 terminal, which is what the 6x6 takes; the smaller boards draw in
less.

## Licence

[PolyForm Noncommercial 1.0.0](LICENSE), as the rest of this repository. See
[NOTICE](NOTICE).
