feat(saves): see what each save slot has and is missing, and change it, outside the game #1401
No reviewers
Labels
No labels
area/accessibility
area/audio
area/input
area/install
area/menu
area/renderer
area/saves
area/tooling
area/upscaling
beanstalk: approved
beanstalk: failed
beanstalk: needs approval
beanstalk: running
beanstalk: tested
ci: approved
good first issue
gpu/amd
gpu/igpu
gpu/intel
gpu/nvidia
help wanted
kind
bug
kind
chore
kind
docs
kind
feature
kind
performance
kind
question
needs measurements
platform/linux
platform/macos
platform/steam-deck
platform/windows
preview
priority
critical
priority
high
priority
low
regression
risk
high
risk
low
risk
medium
status
blocked
status
confirmed
status
duplicate
status
invalid
status
needs-info
status
wontfix
ci: approved
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!1401
Loading…
Reference in a new issue
No description provided.
Delete branch "mooki/Longshot:save-file-editor"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Type: feat · Risk: low · Tested on: Linux, Python 3.12 and 3.14 (game-free checks on a made-up game); one edited save loaded and looked at in the game on Linux, RTX 4090 · Needs: Windows
Why
Nothing lets a player look into a save without starting the game: how close a slot is to 100%, which Gold Skulltulas, chests or heart pieces are missing and where, whether a dungeon's map and keys are all there. Nothing lets a tester or someone finishing a save fix one thing in a file either; the only tools are copying whole save folders (
scripts/longshot_saves.py) or the Debug tools inside a running game. This adds a command line save editor with a full report per slot and the same kind of edits the Debug tools make, with a backup before every write.What changed
scripts/longshot_save_editor.pyreads a save folder and the player's own game folder and reports, per slot, what the slot has and what it is missing, by name and area.setandcleartake a flag, an entry, an area or a whole category;givetakes items (counted ones within the cap the bags and wallets set), hearts, rupees and small keys;startputs Link at a named start place;copycopies a slot. Every write refuses while a game runs, copies the save folder first, writes each file whole beside its place and swaps it in with a rename, reads it back, and puts the files back if that fails. Nothing of the game is in the repository: the flag list, the item table, the quests, the placed objects and the names are read at run time from the game folder.scripts/oot_savefile.py(new): the save file format and the readers under it. A save ends in a sorted table of 64-bit keys (one per placed object that is done: Gold Skulltulas, heart containers, heart pieces); the earlier tools never read it. A file read and written unchanged is byte for byte what it was. Also the game's BYML, SARC and zstd files (zstandardor Python 3.14's own zstd) and the atomic write.scripts/longshot_save_editor.py(new): the catalogue (equipment, items, 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), the report (--json,--missing), the edits, the backup and the checks. It reusesscripts/longshot_saves.pyfor finding the save, the running-game check and the backup folder; that file is not changed.tests/test_longshot_save_editor.py(new): 64 checks on a made-up game and made-up saves: the format, the catalogue, the report and every command with its refusals.--jsonon every command (schema1, what changed, the backup, a reason code for every refusal), for the launcher's save editor and other programs; the text output is unchanged.docs/development.md: a row forLONGSHOT_GAMEin the switch table; a check reads the editor's source for theLONGSHOT_names it reads and fails when one has no row.docs/save-editor.md(new) and one-line links fromdocs/saves.md,docs/saves-script.mdanddocs/development.md.IsTreasureBoxOpen.), asgpu/vk/oot_cheat_items.halready names the pouch items. There is no list of flags, items or names in the source: the lists are read from the player's game folder at run time.Measurements
Verdict: nothing to measure: a command line tool that never runs with the game and is not in any build; no speed claim is made.
Flags and settings
One environment variable, read by the new save editor script only (not by the game or the builder).
LONGSHOT_GAMEromfs), or the RomFS folder, thatscripts/longshot_save_editor.pyreads when--gameis not givenromfs, else asks for--gameTesting
Tested:
python -I -B tests/test_longshot_save_editor.py: 64 checks, on Python 3.12 (the pinned one, withzstandard) and 3.14 (its own zstd), warnings as errors. On the base without the change the file does not exist, so the checks cannot run there. Whole suite on Linux, on this branch rebased onto main544229a26: 665 passed, 40 failed, 17 skipped. The same 40 fail the same way on main544229a26itself (run one by one on a clean checkout), and none touches a save: test_bug_report_defaults, test_cpu_report, test_crt_options, test_damage_debug_menu, test_display_startup_failure, test_dlss_feature_size, test_failed_compile_keeps_objects, test_framegen_preset, test_fsr_uniform_ownership, test_guest_imported, test_hud_layout_row, test_import_reach, test_invalidate_vcore, test_linux_preflight, test_linux_pressure, test_linux_update, test_mirror_budget, test_missing_nup, test_mods_size_table, test_nonuniform_image_arrays, test_parallel_init_order, test_pending_guest_import, test_pipeline_play_cache, test_present_thread, test_profiling_mode, test_readback_timeout_source, test_replay_write_order, test_rumble_menu, test_run_all_changed, test_slow_frames, test_staging_burst, test_switch_table, test_target_image_pool, test_tested_configurations, test_upscaler_round_trip, test_upscaler_rows, test_vcore_escape, test_vk_occlusion_queries, test_vk_swapchain_compat, test_walk_key. Beyond the checks: the report was run on 315 slots of 54 saves (the early, test and a finished real save) without an error, and its numbers for a real finished save agree with what the game's own lists say about it (not published: a player's save). Edits were read back with an independent reader of the same format and agree. In the game (Linux, RTX 4090, driver kernel lines 0, windowless, build 220ffa599, 17 Nov 2026): one slot edited with the tool (6 hearts, 100 rupees, Hookshot, Bomb Bag, 20 bombs, Slingshot, all songs, a dungeon's map and compass, the Gold Skulltulas and one chest of Kokiri Forest, and the start place Hyrule Field, front of the market) was continued from the title with--boot continue. The game loaded it: Link stands on the drawbridge at the field's gate as a child, the HUD shows six hearts, and the pause menu's Items page shows 100 of 200 rupees, 20 bombs, the Slingshot and the Hookshot. The state tap read the edited flags back from the running game: maximum life and life 24 quarters, 100 rupees,IsGetof the Hookshot and of two songs, 20 bombs, the dungeon's map flag and the chest's open flag, all 1 or as set. Run summary:fatal=0 crash=0 devlost=0 kernel=0 nvrm=0. Picture, two panels (uploaded by the maintainer's tooling): 1. the start the tool set, six hearts; 2. the Items page, 100 of 200 rupees, 20 bombs, Slingshot and Hookshot.Not tested: the pause menu's Collection page (the songs were read back from the running game through the state tap, not seen on screen); the Load screen after the edit; Windows (the new file's tests have only run on Linux); a game version other than the one the tool was written against; a save edited with
set allplayed to the end.Must be tested:
python -I -B tests/test_longshot_save_editor.pyand, with your own game folder,python -I scripts/longshot_save_editor.py --game <game folder> report, expecting 64 checks passing and one report per slot (by hand, or the fork's Windows CI part of the Python checks).Risks
What could break: only the tool's own use: an edit writes flags the game does not check against each other, so a set boss or quest can leave the game in a state it would never reach itself. The backup folder keeps the save from before every edit, and the guide says how to put it back. Nothing the game runs is changed.
Turning it off: revert the commits; no other file depends on the new ones.
Compatibility: Nothing changes.
Checklist
Everyone
type(scope): description) of the status line's type.can't be run by hand is in Testing's Not testable by hand, with why.
in Risks.
main.python -I -B tests/run_all.pypasses (any failure that also fails onmainis named).third_party/untouched (a new folder with aPROVENANCE.mdinstead).When it applies
tests/that reads changed source updated in this PR, not weakened (the new checks read the new scripts: the reason codes and the switch row; no existing check was changed).Assisted-by:/Co-Authored-By:trailers.New on this forge; not opened on GitHub.
--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]>WIP: feat(saves): see what each save slot has and is missing, and change it, outside the gameto feat(saves): see what each save slot has and is missing, and change it, outside the gamePushed
6c45402bf. The forge checker warned that the diff addsLONGSHOT_GAME(the folder the save editor reads when--gameis not given), so it now has a row in the switch table ofdocs/development.md, and a new check intests/test_longshot_save_editor.pyreads the editor's source for theLONGSHOT_names it reads and fails when one has no row (it failed before the row was added). The description's Flags and settings section and the Switches documented box are filled in. Nothing else changed: 64 checks in that file pass on Python 3.12 and 3.14,test_env_onandtest_doc_anchorspass.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).
View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.