feat(saves): a text form of the game's saves to share without the game's files, with to-text, from-text and check-text #1403

Open
mooki wants to merge 9 commits from mooki/Longshot:save-text-format into main
Member

Type: feat · Risk: low · Tested on: Linux, Python 3.14, game-free checks on made-up saves, copies of a real finished save and six library saves, and a game run (Linux, RTX 4090) of a save made by from-text beside the same save as the game wrote it · Needs: Windows

Why

A tester or a player who wants to hand someone their progress has to send the game's own save files, and the only safe way to publish one is the scrubber, which keeps a whole progress.sav, one slot and a grey picture, for the repository only. Moving a save between Longshot, Hookshot, ReLink and NX2navi means knowing four folder layouts, and NX2navi's players already exchange a zip with the game's pictures in it. There is no way to say "this slot, at this point of the game, for this game version" in a file that is readable, has no picture, no path, no user id and no file time, and can be checked before anything is written.

What changed

Builds on #1401 (the offline save editor): this PR's base is that PR's branch, save-file-editor (head 6c45402bf, on main 544229a26), for scripts/oot_savefile.py, the reader and the byte-exact writer the codec stands on. Review only the six files below; merge #1401 first, then retarget this PR to main.

A save becomes one JSON file (*.ootsave.json, format oot-save-text version 1): every flag of each slot by the hash of its name and its typed value, the key run of the placed objects, the plain fields (place, hearts, rupees, the world's clock), the game version and who made it. progress.sav, account.sav and option.sav come back from it byte for byte; caption.sav comes back identical but for the picture, which is the scrubber's grey one. No game file is read.

  • scripts/oot_save_text.py (new): the codec, on oot_savefile.SaveFile (header, table bounds, key run, murmur3, write_atomic): the table's 32 groups, 16 layouts of the data section, strings with the old bytes the game leaves after their end, values it cannot read kept as {"raw": hex}, the plain fields, validation, the canonical JSON writer.
  • scripts/longshot_saves.py: to-text, from-text (merges by slot, --replace-all, --keep-settings, --dry-run, the guards and the backup every copy has) and check-text; ReLink as a program (import relink, export relink, to-text relink: the same files and user id as Longshot, in its own folder); to-text --from-zip / from-text --to-zip for NX2navi's share zip, checked as NX2navi's import checks it. guards() and backup_folder() are run()'s own checks moved out; copy_saves gains replace_all and label; nothing else of the old commands changes.
  • docs/save-text.md (new): the format, what is left out (against what scrub removes), the round-trip rules, the refusals; one-line pointers from docs/saves.md and docs/saves-script.md, which also gets a ReLink section.
  • tests/test_save_text.py (new): 69 checks, with the made-up saves packed byte by byte in the test.
  • Unchanged on purpose: scrub, check-repo-saves, the repository's saves rule, the game, the launcher, the website. A text file is still a save and does not make one fit for the repository.

Measurements

Verdict: nothing to measure: a command line tool that never runs with the game and is in no build; no speed claim is made.

Flags and settings

One environment variable shows in the diff against main because it comes from #1401, which this PR is stacked on (documented there in docs/development.md); this PR's own six files add no switch, menu row or ini key. Its row, as #1401 has it:

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
LONGSHOT_GAME The game folder (with its romfs), or the RomFS folder, that scripts/longshot_save_editor.py reads when --game is not given not read unset: the editor uses the current folder if it holds romfs, else asks for --game names the folder once instead of on every command helps: tested by the checks (unset and empty are refused with a reason) set it in your shell if you edit saves often; leave it unset otherwise

Testing

Tested: python -I -B tests/test_save_text.py (69 checks) and tests/test_longshot_saves.py (63), tests/test_doc_anchors.py, tests/test_longshot_save_editor.py (64, #1401's, still passing on the rebased branch), tests/run_all.py save_text longshot_saves doc_anchors, on Linux with Python 3.14. On copies, nothing posted: the finished 100% save (six slots, two cleared) and six library saves (saved by NX2navi, Hookshot and Longshot): to-text then from-text gives every progress.sav, account.sav and option.sav byte for byte and every caption.sav equal up to its picture, with no value kept raw. Against NX2navi's own launcher/saves.py: the zip its export_save writes is read, the zip this tool writes passes its read_zip and import_zip. The whole suite, tests/run_all.py --jobs 6 --strict through the idle gate in a fresh worktree and home: 662 passed, 44 failed, 17 skipped on this head (f57e97b2a) against 661 / 44 / 17 on its base (6c45402bf, #1401) and 660 / 44 / 17 on main (544229a26): the same 44 fail on all three, so none is caused by this change, and the one more pass is test_save_text.py. The 44 on main too, in a temporary worktree (Tooling is not beside it, fixtures that compile need build state a fresh worktree lacks, one needs this PC's CPU build): test_bug_report.py, test_bug_report_defaults.py, test_cpu_report.py, test_crash_groups.py, test_crash_record.py, test_crt_options.py, test_damage_debug_menu.py, test_display_startup_failure.py, test_dlss_feature_size.py, test_failed_compile_keeps_objects.py, test_framegen_preset.py, test_fsr_uniform_ownership.py, test_guest_imported.py, test_hardware_report.py, test_hud_layout_row.py, test_import_reach.py, test_invalidate_vcore.py, test_linux_preflight.py, test_linux_pressure.py, test_linux_update.py, test_mirror_budget.py, test_missing_nup.py, test_mods_size_table.py, test_nonuniform_image_arrays.py, test_parallel_init_order.py, test_pending_guest_import.py, test_pipeline_play_cache.py, test_present_thread.py, test_profiling_mode.py, test_readback_timeout_source.py, test_replay_write_order.py, test_rumble_menu.py, test_run_all_changed.py, test_slow_frames.py, test_staging_burst.py, test_switch_table.py, test_target_image_pool.py, test_tested_configurations.py, test_upscaler_round_trip.py, test_upscaler_rows.py, test_vcore_escape.py, test_vk_occlusion_queries.py, test_vk_swapchain_compat.py, test_walk_key.py.

Game run: once, Linux, RTX 4090, windowless, build 63ddacdc9 (a warm reflink clone of a built game), 17 Nov 06:15, 73 s, reports/SaveFormat-files/hold1. The library save adult-kakariko (not a player's own: a crash-report file kept for debugging) went through to-text then from-text into a fresh user folder with its slot_00 only (A); its own slot_00 went into another (B, the control). Each game booted from the title, pressed A on Continue and the Load card, and was in control on KakarikoVillage_Adult after 25 s (A) and 24 s (B). The game's state read matches the source's values on both, field by field: adult, 24 of 24 quarter hearts, 77 rupees, position (1.69, 108.91, 37.06). The game's own flag query for 128 flags of the source's progress.sav (78 Bool, 50 Int) returned all 128 equal on A and on B. The game did not write the slot's files (hashes equal to what was put in); it added only account.sav (320 bytes), on both. No fatal, crash, device-lost or kernel driver line on either, journal complete. No speed claim is made.

After: this PR @ f57e97b2a, Linux, RTX 4090: the Load list and card, the text-made save (A, top: plain grey picture, the scrubbed date 1/1/2026 12:00 a.m., Autosave, six hearts, the same item icons) beside the library's own save (B, bottom: its own picture and date)
After: this PR @ f57e97b2a, Linux, RTX 4090: in play after Continue, and 30 s later, the text-made save (A, left) beside the library's own (B, right): the same room, hearts, magic and the Hookshot on the item button
After: this PR @ f57e97b2a, Linux, RTX 4090: the pause menu, seven shots each, the text-made save (A, left) beside the library's own (B, right): Items with the Hookshot and 77 rupees, then System (R moved from Items to System and stayed there)

The game reads A's caption.sav as a 3,345-byte JPEG (the scrubber's grey one) and B's as 33,449 bytes, the same map in both. Normalized picture difference A against B: 0.001 to 0.002 on the pause pages, 0.008 in play, 0.029 30 s later (the world moves).

Not tested: Windows (the folder discovery tests are Linux-only, as the script's); a game version other than the one the tool knows (2982123, game 1.1.1); the game on a text-made save of a child, of a save with an option.sav or an account whose cleared-once mark is set, or of several slots at once (this run has one adult slot and no option.sav); a save the game has written over a text-made one, taken back to text; the pause menu's Collection and Equipment pages (the run's R presses stayed on System).

Must be tested:

  • Windows, any GPU (and Linux on another GPU than the RTX 4090), with a game you built: python -I scripts/longshot_saves.py to-text --out a.ootsave.json, then from-text a.ootsave.json --to <an empty folder>, then start the game with --user on a folder holding that save, load the slot, expecting it to load at the same place with a plain grey Load-screen picture (by hand: look at the Load screen and at where Link stands; the Test Farm only starts from repository saves). The Linux RTX 4090 run is the game run above.
  • Windows, any GPU: on a copy of a Longshot save folder, python -I scripts/longshot_saves.py to-text --longshot <its data folder> --out a.ootsave.json, then check-text a.ootsave.json and from-text a.ootsave.json --to <a new folder>, expecting check-text to pass and every progress.sav, account.sav and option.sav in the new folder to equal the original (fc /b) (by hand; tests/test_save_text.py is skipped there by RUN_ALL_SKIP, as test_longshot_saves.py is).

Risks

What could break: only the new commands; run() now calls guards() and backup_folder(), which hold the code it had, and copy_saves has two new parameters with the old behaviour as default (the 63 existing checks pass unchanged). from-text replaces slots of a real save: it backs up the whole target first, builds everything in a temp folder before touching it and swaps in by renames with rollback.

Turning it off: revert the commits; nothing else depends on the new files.

Compatibility: Nothing changes for a player who does not use the new commands. list now also shows ReLink.

Checklist

Everyone

  • One topic.
  • The title is a Conventional Commit (type(scope): description) of the status line's type.
  • Why gives the reason plainly and links the issues that fit (the tracker searched).
  • Tested on my own PC where it runs (in the game, for a change the game runs), as Testing's Tested says; what
    can't be run by hand is in Testing's Not testable by hand, with why.
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Nothing gets worse that I know of: any cost (speed, latency, memory, a setup that worked before) is measured and
    in Risks.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main. (Stacked on #1401: this branch is on save-file-editor @ 6c45402bf, which is on main @ 544229a26; both still merge cleanly with main @ 67efc4d3e, as the forge shows. This PR's own diff against #1401 is the six files above. Retarget to main when #1401 lands.)
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named). (Named under Tested: the same 44 tests fail on main @ 544229a26, on #1401's head and on this branch; none is branch-only.)
  • No game files, dumps, build output or generated files.
  • third_party/ untouched (a new folder with a PROVENANCE.md instead).
  • The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
  • Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value. (LONGSHOT_GAME is #1401's, documented there in docs/development.md; this PR adds no switch.)
  • A check under tests/ that reads changed source updated in this PR, not weakened. (tests/test_save_text.py is new and reads scripts/longshot_saves.py and scripts/oot_save_text.py; tests/test_longshot_saves.py is untouched and passes.)
  • Docs updated.

New on this forge; not opened on GitHub.

**Type:** feat · **Risk:** low · **Tested on:** Linux, Python 3.14, game-free checks on made-up saves, copies of a real finished save and six library saves, and a game run (Linux, RTX 4090) of a save made by `from-text` beside the same save as the game wrote it · **Needs:** Windows ## Why A tester or a player who wants to hand someone their progress has to send the game's own save files, and the only safe way to publish one is the scrubber, which keeps a whole `progress.sav`, one slot and a grey picture, for the repository only. Moving a save between Longshot, Hookshot, ReLink and NX2navi means knowing four folder layouts, and NX2navi's players already exchange a zip with the game's pictures in it. There is no way to say "this slot, at this point of the game, for this game version" in a file that is readable, has no picture, no path, no user id and no file time, and can be checked before anything is written. ## What changed **Builds on #1401** (the offline save editor): this PR's base is that PR's branch, `save-file-editor` (head 6c45402bf, on `main` 544229a26), for `scripts/oot_savefile.py`, the reader and the byte-exact writer the codec stands on. Review only the six files below; merge #1401 first, then retarget this PR to `main`. A save becomes one JSON file (`*.ootsave.json`, format `oot-save-text` version 1): every flag of each slot by the hash of its name and its typed value, the key run of the placed objects, the plain fields (place, hearts, rupees, the world's clock), the game version and who made it. `progress.sav`, `account.sav` and `option.sav` come back from it byte for byte; `caption.sav` comes back identical but for the picture, which is the scrubber's grey one. No game file is read. - `scripts/oot_save_text.py` (new): the codec, on `oot_savefile.SaveFile` (header, table bounds, key run, `murmur3`, `write_atomic`): the table's 32 groups, 16 layouts of the data section, strings with the old bytes the game leaves after their end, values it cannot read kept as `{"raw": hex}`, the plain fields, validation, the canonical JSON writer. - `scripts/longshot_saves.py`: `to-text`, `from-text` (merges by slot, `--replace-all`, `--keep-settings`, `--dry-run`, the guards and the backup every copy has) and `check-text`; ReLink as a program (`import relink`, `export relink`, `to-text relink`: the same files and user id as Longshot, in its own folder); `to-text --from-zip` / `from-text --to-zip` for NX2navi's share zip, checked as NX2navi's import checks it. `guards()` and `backup_folder()` are `run()`'s own checks moved out; `copy_saves` gains `replace_all` and `label`; nothing else of the old commands changes. - `docs/save-text.md` (new): the format, what is left out (against what `scrub` removes), the round-trip rules, the refusals; one-line pointers from `docs/saves.md` and `docs/saves-script.md`, which also gets a ReLink section. - `tests/test_save_text.py` (new): 69 checks, with the made-up saves packed byte by byte in the test. - Unchanged on purpose: `scrub`, `check-repo-saves`, the repository's saves rule, the game, the launcher, the website. A text file is still a save and does not make one fit for the repository. ## Measurements **Verdict:** nothing to measure: a command line tool that never runs with the game and is in no build; no speed claim is made. ### Flags and settings One environment variable shows in the diff against `main` because it comes from #1401, which this PR is stacked on (documented there in `docs/development.md`); this PR's own six files add no switch, menu row or ini key. Its row, as #1401 has it: | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `LONGSHOT_GAME` | The game folder (with its `romfs`), or the RomFS folder, that `scripts/longshot_save_editor.py` reads when `--game` is not given | not read | unset: the editor uses the current folder if it holds `romfs`, else asks for `--game` | names the folder once instead of on every command | helps: tested by the checks (unset and empty are refused with a reason) | set it in your shell if you edit saves often; leave it unset otherwise | ## Testing **Tested:** `python -I -B tests/test_save_text.py` (69 checks) and `tests/test_longshot_saves.py` (63), `tests/test_doc_anchors.py`, `tests/test_longshot_save_editor.py` (64, #1401's, still passing on the rebased branch), `tests/run_all.py save_text longshot_saves doc_anchors`, on Linux with Python 3.14. On copies, nothing posted: the finished 100% save (six slots, two cleared) and six library saves (saved by NX2navi, Hookshot and Longshot): `to-text` then `from-text` gives every `progress.sav`, `account.sav` and `option.sav` byte for byte and every `caption.sav` equal up to its picture, with no value kept raw. Against NX2navi's own `launcher/saves.py`: the zip its `export_save` writes is read, the zip this tool writes passes its `read_zip` and `import_zip`. The whole suite, `tests/run_all.py --jobs 6 --strict` through the idle gate in a fresh worktree and home: **662 passed, 44 failed, 17 skipped** on this head (f57e97b2a) against 661 / 44 / 17 on its base (6c45402bf, #1401) and 660 / 44 / 17 on `main` (544229a26): the same 44 fail on all three, so none is caused by this change, and the one more pass is `test_save_text.py`. The 44 on `main` too, in a temporary worktree (Tooling is not beside it, fixtures that compile need build state a fresh worktree lacks, one needs this PC's CPU build): test_bug_report.py, test_bug_report_defaults.py, test_cpu_report.py, test_crash_groups.py, test_crash_record.py, test_crt_options.py, test_damage_debug_menu.py, test_display_startup_failure.py, test_dlss_feature_size.py, test_failed_compile_keeps_objects.py, test_framegen_preset.py, test_fsr_uniform_ownership.py, test_guest_imported.py, test_hardware_report.py, test_hud_layout_row.py, test_import_reach.py, test_invalidate_vcore.py, test_linux_preflight.py, test_linux_pressure.py, test_linux_update.py, test_mirror_budget.py, test_missing_nup.py, test_mods_size_table.py, test_nonuniform_image_arrays.py, test_parallel_init_order.py, test_pending_guest_import.py, test_pipeline_play_cache.py, test_present_thread.py, test_profiling_mode.py, test_readback_timeout_source.py, test_replay_write_order.py, test_rumble_menu.py, test_run_all_changed.py, test_slow_frames.py, test_staging_burst.py, test_switch_table.py, test_target_image_pool.py, test_tested_configurations.py, test_upscaler_round_trip.py, test_upscaler_rows.py, test_vcore_escape.py, test_vk_occlusion_queries.py, test_vk_swapchain_compat.py, test_walk_key.py. **Game run:** once, Linux, RTX 4090, windowless, build 63ddacdc9 (a warm reflink clone of a built game), 17 Nov 06:15, 73 s, `reports/SaveFormat-files/hold1`. The library save `adult-kakariko` (not a player's own: a crash-report file kept for debugging) went through `to-text` then `from-text` into a fresh user folder with its slot_00 only (A); its own slot_00 went into another (B, the control). Each game booted from the title, pressed A on Continue and the Load card, and was in control on `KakarikoVillage_Adult` after 25 s (A) and 24 s (B). The game's state read matches the source's values on both, field by field: adult, 24 of 24 quarter hearts, 77 rupees, position (1.69, 108.91, 37.06). The game's own flag query for 128 flags of the source's `progress.sav` (78 Bool, 50 Int) returned all 128 equal on A and on B. The game did not write the slot's files (hashes equal to what was put in); it added only `account.sav` (320 bytes), on both. No fatal, crash, device-lost or kernel driver line on either, journal complete. No speed claim is made. ![After: this PR @ f57e97b2a, Linux, RTX 4090: the Load list and card, the text-made save (A, top: plain grey picture, the scrubbed date 1/1/2026 12:00 a.m., Autosave, six hearts, the same item icons) beside the library's own save (B, bottom: its own picture and date)](https://git.magicbean.dev/attachments/c15a04f3-4e3e-44ca-9812-9c01ed2a9064) ![After: this PR @ f57e97b2a, Linux, RTX 4090: in play after Continue, and 30 s later, the text-made save (A, left) beside the library's own (B, right): the same room, hearts, magic and the Hookshot on the item button](https://git.magicbean.dev/attachments/62e36e12-50e2-4ee7-a45f-d90bc88f29e9) ![After: this PR @ f57e97b2a, Linux, RTX 4090: the pause menu, seven shots each, the text-made save (A, left) beside the library's own (B, right): Items with the Hookshot and 77 rupees, then System (R moved from Items to System and stayed there)](https://git.magicbean.dev/attachments/5701b779-c722-4088-a2db-cd6b2d8f1ec2) The game reads A's `caption.sav` as a 3,345-byte JPEG (the scrubber's grey one) and B's as 33,449 bytes, the same map in both. Normalized picture difference A against B: 0.001 to 0.002 on the pause pages, 0.008 in play, 0.029 30 s later (the world moves). **Not tested:** Windows (the folder discovery tests are Linux-only, as the script's); a game version other than the one the tool knows (2982123, game 1.1.1); the game on a text-made save of a child, of a save with an `option.sav` or an account whose cleared-once mark is set, or of several slots at once (this run has one adult slot and no `option.sav`); a save the game has written over a text-made one, taken back to text; the pause menu's Collection and Equipment pages (the run's R presses stayed on System). **Must be tested:** - Windows, any GPU (and Linux on another GPU than the RTX 4090), with a game you built: `python -I scripts/longshot_saves.py to-text --out a.ootsave.json`, then `from-text a.ootsave.json --to <an empty folder>`, then start the game with `--user` on a folder holding that save, load the slot, expecting it to load at the same place with a plain grey Load-screen picture (by hand: look at the Load screen and at where Link stands; the Test Farm only starts from repository saves). The Linux RTX 4090 run is the game run above. - Windows, any GPU: on a copy of a Longshot save folder, `python -I scripts/longshot_saves.py to-text --longshot <its data folder> --out a.ootsave.json`, then `check-text a.ootsave.json` and `from-text a.ootsave.json --to <a new folder>`, expecting `check-text` to pass and every `progress.sav`, `account.sav` and `option.sav` in the new folder to equal the original (`fc /b`) (by hand; `tests/test_save_text.py` is skipped there by `RUN_ALL_SKIP`, as `test_longshot_saves.py` is). ## Risks **What could break:** only the new commands; `run()` now calls `guards()` and `backup_folder()`, which hold the code it had, and `copy_saves` has two new parameters with the old behaviour as default (the 63 existing checks pass unchanged). `from-text` replaces slots of a real save: it backs up the whole target first, builds everything in a temp folder before touching it and swaps in by renames with rollback. **Turning it off:** revert the commits; nothing else depends on the new files. **Compatibility:** Nothing changes for a player who does not use the new commands. `list` now also shows ReLink. ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). - [x] Tested on my own PC where it runs (in the game, for a change the game runs), as Testing's Tested says; what can't be run by hand is in Testing's Not testable by hand, with why. - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Nothing gets worse that I know of: any cost (speed, latency, memory, a setup that worked before) is measured and in Risks. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main`. (Stacked on #1401: this branch is on `save-file-editor` @ 6c45402bf, which is on `main` @ 544229a26; both still merge cleanly with `main` @ 67efc4d3e, as the forge shows. This PR's own diff against #1401 is the six files above. Retarget to `main` when #1401 lands.) - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). (Named under Tested: the same 44 tests fail on `main` @ 544229a26, on #1401's head and on this branch; none is branch-only.) - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [x] Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value. (`LONGSHOT_GAME` is #1401's, documented there in `docs/development.md`; this PR adds no switch.) - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. (`tests/test_save_text.py` is new and reads `scripts/longshot_saves.py` and `scripts/oot_save_text.py`; `tests/test_longshot_saves.py` is untouched and passes.) - [x] Docs updated. New on this forge; not opened on GitHub.
scripts/longshot_save_editor.py reads a save folder and reports, slot by slot, what the slot has and what it
is missing, by name and area: items, equipment, masks, upgrades, songs, quest items, hearts, heart containers
and pieces, rupees, chests, Gold Skulltulas, each dungeon's map, compass, boss key and small keys, bosses, the
Hall of Fallen Foes, story and side quests. set and clear take a flag, an entry, an area or a whole category;
give takes items (counted ones within the cap the bags and wallets set), hearts, rupees and small keys; start
puts Link at a named start place; copy copies a slot. Every write refuses while a game runs, copies the save
folder first, writes each file whole and swaps it in by a rename, reads it back and puts the files back if
that fails.

The categories, totals and the way each is told apart in the file are read from the player's own game folder
(--game): the flag list, the pouch table, the quests, the maps' placements and the game's text. Nothing of the
game is in the repository. scripts/oot_savefile.py is the layer below: the save file format (a file read and
written unchanged is byte for byte what it was, the 64-bit key table stays sorted), the game's BYML, SARC and
zstd files, and the atomic write.

tests/test_longshot_save_editor.py runs it all on a made-up game and made-up saves: the format, the
catalogue, the report, every command and its refusals.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
docs/save-editor.md says what the report counts and where each count is read, what set, clear, give, start and copy
do and do not do, and what keeps a save safe. The report names a slot that cannot be read and goes on with the
others; the game's text falls back to another English archive, and the output is safe for a console that cannot
print the game's typographic quotes.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Mini-games (the quests with no kind) are their own category: listed, never part of 100%, and `all` leaves them alone. Setting a boss also sets its heart container and its dungeon's boss key, and clearing takes them away. A bigger bomb bag, quiver, wallet or bag keeps the smaller tiers, and the slot card's item flags follow every item edit. The guide says what an edit still does not write.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
--json prints one JSON object on stdout and nothing on stderr: for set, clear, give, start and copy what changed, the files written, the backup folder and a read-back verdict; for items and places the lists; for report a schema version. A refusal is {"ok": false, "error": {"code", "message"}} with a code a program can switch on (running, other_version, out_of_range, would_overwrite ...). The text output is unchanged. docs/save-editor.md has the keys and the codes.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Fail carries a code and every place that raises it names one, so rewording a message cannot change what a program sees in --json. longshot_saves.py's refusals are given their codes where the editor calls it. Two checks: every Fail in the scripts has an explicit code the guide lists, and a patched message leaves the codes as they were.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
docs(saves): the editor writes a slot's two files only, never the account's cleared-once mark
All checks were successful
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 9s
Website / Website on Cloudflare (pull_request_target) Has been skipped
CI / Workflow lint (actionlint) (pull_request) Successful in 17s
Guide screenshots / Guide images and local UI source review (pull_request) Successful in 18s
PR description / Description follows the template (pull_request_target) Successful in 11s
Third-party parts / As their notes say (pull_request) Successful in 23s
073339dd9d
Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
docs(saves): LONGSHOT_GAME, the folder the save editor reads when --game is not given, has a row in the development guide
All checks were successful
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 7s
CI / Workflow lint (actionlint) (pull_request) Successful in 12s
Guide screenshots / Guide images and local UI source review (pull_request) Successful in 13s
Third-party parts / As their notes say (pull_request) Successful in 18s
PR description / Description follows the template (pull_request_target) Successful in 9s
6c45402bf7
A check reads the editor's source for the LONGSHOT_ names it reads and fails when one has no row in docs/development.md's switch table.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
A save as one JSON file with every flag of its slots and nothing of the game: no Load-screen picture (a mid-grey one is made
when files are made from the text, as the scrubber makes it), no path, user id or file time, the saved date reset as the scrubber
resets it, and the settings only when asked. progress.sav, account.sav and option.sav come back byte for byte, caption.sav but
for the picture. Plain fields (hearts, rupees, place, the world's clock) and the provenance (game version, source project,
converter version) are in the file; a text file of another game version is refused unless asked.

longshot_saves.py gains to-text, from-text (--dry-run, the guards and the backup every copy has, replacing only the slots the
file has) and check-text, and ReLink as a program (a fork of Longshot: the same files and user id, its own folder).
scripts/oot_save_text.py is the codec, on oot_savefile.py's reader of the header and the key run.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
feat(saves): the text form reads and makes NX2navi's share zip
All checks were successful
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 7s
CI / Workflow lint (actionlint) (pull_request) Successful in 16s
Website / Website on Cloudflare (pull_request_target) Has been skipped
Guide screenshots / Guide images and local UI source review (pull_request) Successful in 17s
Third-party parts / As their notes say (pull_request) Successful in 23s
PR description / Description follows the template (pull_request_target) Successful in 9s
f57e97b2ab
to-text --from-zip reads NX2navi-save-*.zip as NX2navi's own import does (manifest format, version and title id, every path
inside save/, no link, 4,000 files and 256 MB, a save file in it, each file's CRC; key files left out), and from-text --to-zip
makes a zip NX2navi's Import a Save takes: the files with a mid-grey picture, a manifest without an export time, every entry
dated 2026-01-01. Checked against NX2navi's launcher/saves.py: its export_save zip is read here, this zip passes its read_zip
and import_zip.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
mooki changed title from WIP: feat(saves): a text form of the game's saves to share without the game's files, with to-text, from-text and check-text to feat(saves): a text form of the game's saves to share without the game's files, with to-text, from-text and check-text 2026-11-17 12:27:13 +00:00
Author
Member

Description only, no code change: the description check failed because the diff against main includes #1401's LONGSHOT_GAME (this PR is stacked on it) and the Flags and settings section did not list it. It now has #1401's row for it, and the base line says both branches still merge cleanly with current main.

Description only, no code change: the description check failed because the diff against `main` includes #1401's `LONGSHOT_GAME` (this PR is stacked on it) and the Flags and settings section did not list it. It now has #1401's row for it, and the base line says both branches still merge cleanly with current `main`.
Owner

Brought up to the ready-for-review standard (#1454): the checklist's Everyone list has two new boxes, added here from what this PR's description and comments show (please check they match what you know).

  • Tested on my own PC: ticked: Testing's Tested: the author ran the checks on Linux with Python 3.14 and a game run of a text-made save.
  • Nothing gets worse that I know of: ticked: A command-line tool with a one-line reason for no measurement, and Risks names no slowdown or memory cost.
Brought up to the [ready-for-review standard](https://git.magicbean.dev/MagicBeanDev/Longshot/src/branch/main/CONTRIBUTING.md#ready-for-review-out-of-wip) (#1454): the checklist's Everyone list has two new boxes, added here from what this PR's description and comments show (please check they match what you know). - *Tested on my own PC*: ticked: Testing's Tested: the author ran the checks on Linux with Python 3.14 and a game run of a text-made save. - *Nothing gets worse that I know of*: ticked: A command-line tool with a one-line reason for no measurement, and Risks names no slowdown or memory cost.
All checks were successful
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 7s
CI / Workflow lint (actionlint) (pull_request) Successful in 16s
Website / Website on Cloudflare (pull_request_target) Has been skipped
Guide screenshots / Guide images and local UI source review (pull_request) Successful in 17s
Third-party parts / As their notes say (pull_request) Successful in 23s
PR description / Description follows the template (pull_request_target) Successful in 9s
This pull request doesn't have enough approvals yet. 0 of 1 approvals granted.
This branch is out-of-date with the base branch
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'save-text-format:mooki-save-text-format'
git switch 'mooki-save-text-format'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Longshot!1403
No description provided.