From 5b7cb252b5e1a7693e35b00af28d2dd56cc9b9e5 Mon Sep 17 00:00:00 2001 From: Jared Miller Date: Tue, 10 Feb 2026 10:07:38 -0500 Subject: [PATCH] Update if-journey docs with save/restore completion Save/restore is now fully implemented in the hybrid interpreter. Updated open question 7 to reflect completion, marked the what-to-do-next item as done, and updated the milestone section to include save/restore in the "what works" list. Also noted the QuetzalParser off-by-one bug fix (return_pc parsing). --- docs/how/if-journey.rst | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/how/if-journey.rst b/docs/how/if-journey.rst index 759e58e..d5e93eb 100644 --- a/docs/how/if-journey.rst +++ b/docs/how/if-journey.rst @@ -234,12 +234,14 @@ How hard is it to add words to a z-machine dictionary at runtime? The dictionary 7. Save/restore in the hybrid interpreter ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -``op_save`` is a stub that always branches false (game prints "Failed."). The infrastructure is mostly there — ``TrivialFilesystem.save_game()`` prompts for a filename and writes to disk, ``QuetzalParser`` can read save files — but two pieces are missing: +RESOLVED: save/restore is now fully implemented and working. Key pieces: -- ``QuetzalWriter`` chunk generators (``ifhd``, ``cmem``, ``stks``) are all stubs returning ``"0"`` -- ``op_save`` doesn't collect game state or call the filesystem +- ``QuetzalWriter`` chunk generators implemented (``IFhd`` for header, ``CMem`` for XOR-compressed dynamic memory, ``Stks`` for stack frame serialization) +- ``op_save`` and ``op_restore`` wired to filesystem layer via ``TrivialFilesystem`` +- round-trip tested: save game state, restore it, continue playing +- fixed ``QuetzalParser`` off-by-one bug in return_pc parsing (was reading ptr+3, should be ptr+2) -To make save work: implement ``QuetzalWriter`` (XOR-compress dynamic memory against original story, serialize stack frames into Quetzal format), then wire ``op_save`` to generate the bytes and call ``self._ui.filesystem.save_game(data)``. Restore should be simpler since ``QuetzalParser`` already works — just need to wire ``op_restore`` to call ``filesystem.restore_game()`` and apply the parsed state. +Quetzal format is now fully supported for both reading and writing saves. what to do next --------------- @@ -254,7 +256,7 @@ Concrete next steps, roughly ordered. Update as items get done. - [x] build level 1 prototype: regardless of interpreter choice, implement the terminal object, IF mode, and subprocess dfrotz path. this proves the MUD-side architecture (mode stack, spectators, save/restore) independently of the interpreter question. (done — see ``docs/how/if-terminal.txt``) -- [ ] implement save/restore: finish ``QuetzalWriter`` chunk generators and wire ``op_save``/``op_restore`` to the filesystem layer. restore should be easier since ``QuetzalParser`` already works. +- [x] implement save/restore: finished ``QuetzalWriter`` chunk generators (IFhd, CMem, Stks) and wired ``op_save``/``op_restore`` to filesystem. quetzal round-trip now works — can save during gameplay, restore, and continue. also fixed parser off-by-one bug in return_pc. - [ ] study MojoZork's multiplayer model: read the MultiZork source for how it handles multiple players in one z-machine. document the pattern for our eventual level 4. @@ -273,7 +275,8 @@ What works: - instruction trace deque (last 20 instructions) for debugging state errors - smoke test: ``scripts/run_zork1.py`` runs the game headless, exercises core opcode paths - parser and lexer: all Zork 1 commands work (look, open mailbox, read leaflet, inventory, take, drop, navigation) -- the interpreter is fully playable for Zork 1 (save/restore not yet wired — see open question 7) +- save/restore: full quetzal format support for persisting and restoring game state +- the interpreter is fully playable for Zork 1 What this enables: