From f4b7d0548bcfbfaba38d5a684e015a5403aa9465 Mon Sep 17 00:00:00 2001 From: Jared Miller Date: Tue, 10 Feb 2026 13:13:42 -0500 Subject: [PATCH] Update if-journey.rst with save/restore bug fix details --- docs/how/if-journey.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/how/if-journey.rst b/docs/how/if-journey.rst index 80e6f2d..3ff937e 100644 --- a/docs/how/if-journey.rst +++ b/docs/how/if-journey.rst @@ -241,9 +241,11 @@ RESOLVED: save/restore is now fully implemented and working. Key pieces: - ``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) +- fixed Quetzal ``Stks`` field mapping: ``return_pc`` belongs on the caller frame's ``program_counter``, not the current frame. ``varnum`` is the store variable on the current frame. round-trip tests masked this because writer and parser had the same bug symmetrically +- fixed V3 save branch processing on restore: in-game saves store PC pointing at branch data after the save opcode (0xB5). ``_try_restore()`` detects this and calls ``_branch(True)`` to advance past it. without this, branch bytes were decoded as instructions +- fixed restored local var padding: save files store only declared locals, runtime expects 15 slots. now zero-pads on restore -Quetzal format is now fully supported for both reading and writing saves. +Quetzal format is now fully supported for both reading and writing saves. Diagnostic tooling: ``scripts/zmachine_inspect.py`` for offline state inspection, instruction trace deque (last 20) auto-dumps on crash. what to do next ---------------