Saving and loading

Keep a maze in a file and play it back later, and what happens to a file that is not a maze py_maze can read.

--save writes the maze, and any collectibles, to a file:

python -m py_maze -d easy --seed 2024 -c 4 --save maze.txt

maze.txt:

# py_maze save 1
# seed: 2024
* ***********
* *     *   *
* *** * *** *
*   * *     *
*** * *******
*   *       *
* *** ***** *
*   *$*$  * *
*** * * *** *
*   * $$*   *
* ******* * *
*         * *
*********** *

A save file is the maze exactly as it is drawn, under a short header recording the format and the seed it came from. That makes it readable, editable by hand and comparable like any other text file. Lines starting with # are comments, so a note about the maze can be kept alongside it.

--load plays a saved maze back:

python -m py_maze --load maze.txt

The maze comes from the file as it was saved, so the options that generate one do not apply to it: --width, --height, --difficulty, --algorithm, --braid and --collectibles are all ignored for a loaded maze. --solve, --animate and the in-game hints work on it exactly as they do on a generated one, and --wall-char and --open-char apply to nothing else: they say how a file that carries no py_maze header was drawn.

--seed is the one of them that is not quite ignored. The grid is in the file and is never re-seeded, but what a mode lays over that grid is not in the file at all - quest mode’s chain of doors and boxes is laid fresh each time a picture is loaded - and that does come from a seed:

So --load picture.txt --mode quest --seed 5 lays the same quest every time, and a document that already carries a quest is played with the chain it carries rather than a new one, seed or no seed.

A loaded maze reports the seed its file records, so a maze that turned out to be worth keeping can still be traced back:

Loading maze...

start
...
end
seed: 2024

Where the chain came from somewhere else, a second line says so. The two seeds answer two different questions - seed: is the grid in the file, and content seed: is the chain laid over it - and only the second is the one --seed reproduces:

python -m py_maze --load picture.txt --mode quest --seed 5

Loading maze...

start
...
end
seed: 11
content seed: 5

The line is there only when the two part, which is a loaded maze the run named a seed of its own for. A generated maze, and a loaded one played with no --seed, have a single seed between them and report the one line they always did. So does a document played back with the chain it was saved with: nothing was laid from a seed at all, so there is no second number to give.

A file that is not a maze this build can read is refused rather than guessed at, with a message naming what was wrong:

python -m py_maze --load notes.txt

Output:

py_maze: notes.txt: not a py_maze save file

The same goes for a ragged maze (notes.txt: line 3 is 4 characters, expected 5), a stray character such as a solution marker pasted back in (notes.txt: unexpected character '.' on line 2), and a file written by a newer build (notes.txt: save format 2 is not supported, this build reads 1).

The format is specified in the save file format: the header, the seed comment, the markers, the ragged-line rule and what a reader refuses, so another tool can write a file py_maze will load.