feat(menu): a Progress editor in the Debug tools (chests, Gold Skulltulas, hearts, bosses, start place) and Inventory amounts that keep every press #1411

Open
mooki wants to merge 8 commits from mooki/Longshot:progress-editor into main
Member

Type: feat · Risk: medium · Tested on: Linux (Arch), RTX 4090 (NVIDIA) · Needs: Windows (any GPU), AMD or Intel graphics (a run of the editor)

Why

A tester or player who wants a save "with this chest open, that Gold Skulltula taken, Gohma beaten and a heart more" can only play there or edit the save file by hand. The Debug tab's Inventory page gives items but no progress, and its amounts do not always follow the keys: a held Left or Right on a quantity lost presses (#871, "repeated presses result in only one item being added"). This PR adds a Progress page after Inventory that shows what the loaded save has, by area, and changes it in the running game (a chest, a Skulltula, a piece of heart, a dungeon's items and small keys, a boss as a group, hearts, rupees, the place Link starts), and it makes the Inventory page's amounts keep every press. Two defects found by building a save with the Inventory page are fixed too: a song unlocked there was missing from the game's save, and the Deku Stick and Deku Nut bags had no row.

How to reproduce

For #871 (the Inventory part):

Seen on: Windows 11, RTX 5080, NVIDIA 621.24, v3.0.0-rc.4 (the reporter's report.txt)
Settings and switches: Debug tools On
Steps: open Debug, Inventory, Items, a quantity (bombs), Edit amount, then hold or press Right several times.
Expected: the quantity goes up by the number of presses.
Actual: one item is added. The reporter's longshot_log.txt has exactly one cheats: inventory ... +1 line for each item he edited: the other presses never reached the game.

What changed

The Progress page reads the player's own game files when it first opens (a few seconds, on a thread of its own), builds its areas and categories from them, reads the live flags and changes them through the game's own setters at Link's updates, so the pause screens and the game's autosave see a change as they see the real thing. No flag name, list or table of the game is in the source. The Inventory amounts now go through a queue.

  • gpu/vk/game_files.h, game_byml.h (new): the game-file readers (moved out of vk_game_font.h, which keeps three using lines) and a lazy BYML reader.
  • gpu/vk/progress_catalog.h, progress_editor.h, progress_types.h, progress_boss_sets.h (new): the catalogue (areas, chests, Gold Skulltulas, pieces of heart, containers, dungeon items, small keys, bosses, quests, start places) made from the player's files by rules, and the Editor (have/of, set one, set all, a boss's end set in one batch, the counters that depend on them). A start place on the other age's map than Link's is greyed. The bosses' end sets are 32-bit hashes only, taken from #68's tables (no name).
  • gpu/vk/progress_page.h, gpu/vk/vk_menu.cpp: the page (keys, navigation, drawing) and its row on the Debug tab (Row::cheat 12, after Inventory).
  • gpu/vk/vk_api.h, gpu/vk/progress_api.h, host/rx_backend.c: three MkwVkHost calls, progress_read, progress_apply, progress_state. MKWVK_API_VERSION 29 → 31 (main is 29; the open #1358 holds 30 and #68 holds 33).
  • host/oot_progress.c, host/hos_main.c: the game side: reads straight from the game's memory on the menu's thread (every pointer checked to lie in the guest), writes queued for Link's update (at most 32 changes an update, in order, through SetBool, SetInt, SetEnum, SetKey64 and the pouch event, only while a ring has room). oot_teleport is split so the travel to a start place sends the same event under the same checks.
  • gpu/vk/cheat_queue.h, gpu/vk/vk_menu.cpp (#871): the Debug tab's actions were one atomic int that Link's update took with an exchange; a press before the next update replaced the waiting one. They wait in a queue of sixteen now and the presses of one item's amount are summed into the action that is waiting.
  • host/hos_main.c oot_gamedata_set_bool: writes the saved copy of a Bool too (the game's autosave writes the file from it): a song unlocked on the Inventory page was in the running game and not in the save (5 of 12 songs in a made save). The age switch shares the function.
  • gpu/vk/oot_cheat_items.h: rows for the Deku Stick and Deku Nut bags (three sizes each).
  • docs/progress-editor.md (new), README.md, docs/development.md: how to use it, what each change does, HOS_OOT_TRACE_PROGRESS=1, API versions.
  • tests (all game-free): test_progress_catalog.py, test_progress_page.py, test_progress_menu.py, test_oot_progress_host.py, test_cheat_queue.py new; test_cheat_items.py, test_pipeline_tour.py, test_audio_output_devices.py updated, none weakened.

What it does not do:

  • Quests are read-only. The game's quest manager undoes a step written while it runs; only a boss's end set moves its quest.
  • Hearts are given as a pickup, never by writing life (the game rewrites life every frame). The pieces in hand are the pieces set modulo four.
  • Ganon and Ganondorf get a kill counter only: no end set is carried for them.
  • The Inventory page's Gold Skulltula Tokens row still changes the count alone, not the placed Skulltulas' keys.
  • Menu texts are English only.

Measurements

Nothing to time: the page does nothing until it is opened, and its flag reads (a few hundred, twice a second) run on the menu's thread. What was checked is that it works, in Testing.

Flags and settings

One switch and one menu row, no ini key.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
HOS_OOT_TRACE_PROGRESS=1 Logs each change the Progress editor applies (the flag's hash and the value) and each batch that stops none off A log line for each change and each stopped batch for a bug report about the editor off; for testing
Debug tab, Progress Opens the editor (needs Debug tools On and a loaded save) none shown with the other tools The page untested on Windows on with Debug tools

Testing

Tested: Linux (Arch, kernel 7.2.15), RTX 4090 (NVIDIA 615.78.08), i9-13900K, 93 GB; headless, 2026-11-17; main @ 544229a26 and this PR @ 9bdbc2c94.

  • The new game-free tests, both ways. On main's source each fails: tests/test_cheat_queue.py (vk_menu.cpp does not include cheat_queue.h; the header is new), tests/test_cheat_items.py (the StickBag rows are []), tests/test_oot_progress_host.py bool_both_copies (FAIL ... *at(song + 0x17) == 1: the saved copy was not written), tests/test_progress_catalog.cpp's start-place checks (they do not compile without the age guard). On this PR they pass; test_cheat_queue.py also under TSan (--tsan). The engine's test passed under g++, clang++, ASan+UBSan and TSan on an earlier head of this branch, and under g++ on this one.

  • The whole suite, python -I -B tests/run_all.py --jobs 6 in a fresh home, once on this PR and once on main @ 544229a26. This PR: 668 passed, 41 failed, 17 skipped (709 checks). Main: 663 passed, 41 failed, 17 skipped (704 checks). The same 41 test files fail on both (compared by name, reports/SaveEditGame-files/suite/final-*-suite.txt.names): this machine's and main's own (test_bug_report_defaults, test_cpu_report, test_crash_record, test_linux_pressure, test_mirror_budget, test_present_thread, test_profiling_mode, test_staging_burst, test_target_image_pool, test_missing_nup and the rest of the list in the files). The five new files pass here: test_cheat_queue, test_oot_progress_host, test_progress_catalog, test_progress_menu, test_progress_page.

  • Linux build. A full make_game.py build of the branch (before one change to tests/test_audio_output_devices.py) exited 0 (176 s, the lifted code and objects from an earlier build of the same branch).

  • Windows, compiled, not run. The Windows-target syntax check of every changed fixture (llvm-mingw 20261104): PASS for all of them (test_oot_progress_host, test_progress_catalog, test_progress_page, test_cheat_queue, test_cheat_items, test_audio_output_devices); test_pipeline_tour.py runs on Linux only. test_audio_output_devices.py failed this check on main too ('memmove'/'tmpfile' deprecated: its parser fixture lacked _CRT_SECURE_NO_WARNINGS); it is added here.

  • In the game (Linux, NVIDIA, headless; the pictures are below; build of 4ca7bd4c4, which differs from this head only in tests/test_audio_output_devices.py). One hold, two games on one made save (a child in Hyrule Field with 16 Deku Nuts, 5 Gold Skulltulas, 1 piece of heart in hand, 4 hearts, Gohma already beaten): game 1 was driven by scripted menu keys (RX_VK_MENU_SCRIPT, 150 keys) through Debug, Inventory (nuts: four Left, three Right at 0.7 s, four Right at 80 ms, two Left) and Debug, Progress (Hyrule Field's Chest 1, Gold Skulltulas 1 and 2, heart pieces 1 and 3; one heart more; Gohma cleared, then set again; the start place "Front Of Market", the child's map); then Link arrived there and the game saved. Game 2 is a new process on the files game 1 left, and its flags were read the moment play began, before any key:

    Flag read from the running game Before After the keys (game 1) Game 2, at once after loading
    Deku Nuts 16 17 (13 of 13 presses landed, each its own cheats: inventory line) 17
    Hyrule Field Chest 1 not opened opened opened
    Gold Skulltula count (5 others already in the save) 5 7 7
    Pieces of heart in hand (set modulo four) 1 3 3
    Max life 16 (4 hearts) 20 (5 hearts) 20
    Gohma: counter, quest step 1, 4c0a63f4 0, 576277fa after the clear; then 1, d52b1014 (the end step) 1, d52b1014

    The log has the 43 progress: lines (nine batches, every op "made", none skipped), then save trace lines at the arrival, and a save file written after the script began. Game 2 then drew the same pages with Chest 1, Skulltulas 1 and 2, pieces 1 and 3 Had, 5 of 20 hearts, 3 of 4 for the next heart, Gohma Beaten, and the Inventory page's Deku Nuts at quantity 17; the game's own pause screen showed 5 hearts and Deku Nut 17/20. No fatal, crash, device-lost or kernel driver line in either game. Pictures: 1-game1-editing.jpg (the keys' effect page by page, the travel's arrival with Saving...), 2-game2-read-back.jpg (game 2's pages), 3-game2-pause-screens.jpg.

Game 1: the Debug tab's Progress row, Chest 1 flipped to Had, Gold Skulltulas 1 and 2 Had, heart pieces 1 and 3 Had, one heart more (5 of 20), Gohma marked beaten, the start place chosen, and the arrival with the game saving.

Game 2, a new process on the files game 1 saved: the same pages read back (Chest 1, Skulltulas 1 and 2, pieces 1 and 3 Had; 5 of 20 hearts, 3 of 4 pieces; Gohma beaten; Deku Nuts 17 on the Inventory page).

Game 2's own pause screens: five hearts, Deku Nut 17 of 20, rupees 125.

  • #871: the 13 key presses of the amounts all landed, in order, at the game's 60 updates a second. At that speed the old single slot would not have lost one either (Link took each press before the next), so the run shows that every press arrives, not the loss itself; the loss is shown by the game-free test_cheat_queue.py (two threads) and by the reporter's log.
  • One difference from playing: the save had Gohma's quest one step past the end step (4c0a63f4); the editor's "beaten" ends at the end step (d52b1014) and the pause screens, the autosave and the second load took it without a sign of trouble. A boss set this way may differ from the game's own in that one quest step.

Not tested:

  • Windows: the editor, the queue and the host side have not run on Windows; the changed fixtures and the host were only compiled for it (above).
  • Other GPUs (AMD, Intel) and the Steam Deck: no run. The page uses the menu's own widgets and no new renderer code.
  • Adult Link, the dungeons' items and small keys, Set all and Clear all, rupees, the quests list, and every start place but one: not tried in the game (the game-free tests cover the rules on a test game).
  • Whether a boss marked beaten as a group leaves a save the game accepts in every part (only Gohma, one save); the other seven bosses' end sets come from #68's tables and were not run here.
  • A real controller or mouse on the page: the keys were scripted (RX_VK_MENU_SCRIPT); the mouse code is only read and tested on a fake.

Must be tested:

  • Windows, any GPU (by hand, or a Windows request to the Test Farm for the Debug tab's Progress page): load a save, Debug tools On, Debug, Progress, Areas, an area, Chests, Enter on a chest, then Back to the top and Hearts and rupees, Right; expecting "Had" on the chest after a second and one heart more on the pause screen.
  • AMD or Intel graphics (by hand, or an AMD or Intel request to the Test Farm for the Debug tab's Progress page): the same steps, expecting the page to draw like the pictures above (it uses the menu's own widgets only) and "Had" on the chest.

Risks

What could break: The host reads the game's data manager from the menu's thread with every pointer checked against the guest window, and writes only at Link's update through the game's own setters; a game whose layout differs would answer "no such flag" (reads) or stop a batch with a log line (writes), not crash. A change to a quest-linked flag (a boss's end set) can leave a save the game would not have made (for example a boss marked beaten whose door the player has not opened); the page says what each change does. The queue replaces one atomic int, so a menu action now also waits behind a waiting one instead of replacing it. The MkwVkHost table grows by three entries after monitor_select.

Turning it off: Debug tools Off hides the row; reverting the commits removes the page and the queue.

Compatibility: MKWVK_API_VERSION 29 → 31: build the host and the renderer together. Saves and longshot_options.ini are not touched; a save the editor changed is the game's own save of the changed flags.

Issues

See #871 (the Inventory part: the reporter's log shows exactly the lost-press pattern the queue removes; the run in the game shows every press landing, not the old loss).
Overlaps: #68 (co-op) carries the same eight boss end sets in host/oot_coop.c; this PR holds them as hashes in gpu/vk/progress_boss_sets.h and reads the same flags through its own host calls.

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).
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main (544229a26).
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named).
  • 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.
  • Screenshots of the same spot, captioned like the Measurements columns, for a change that shows on screen.
  • MKWVK_API_VERSION bumped (gpu/vk/vk_api.h's MkwVkHost or MkwVkRenderer changed).
  • A game-free test added for the fix, failing on main and passing here.
  • A check under tests/ that reads changed source updated in this PR, not weakened.
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths.
  • Docs updated.

New on this forge; not opened on GitHub.

**Type:** feat · **Risk:** medium · **Tested on:** Linux (Arch), RTX 4090 (NVIDIA) · **Needs:** Windows (any GPU), AMD or Intel graphics (a run of the editor) ## Why A tester or player who wants a save "with this chest open, that Gold Skulltula taken, Gohma beaten and a heart more" can only play there or edit the save file by hand. The Debug tab's Inventory page gives items but no progress, and its amounts do not always follow the keys: a held Left or Right on a quantity lost presses (#871, "repeated presses result in only one item being added"). This PR adds a **Progress** page after Inventory that shows what the loaded save has, by area, and changes it in the running game (a chest, a Skulltula, a piece of heart, a dungeon's items and small keys, a boss as a group, hearts, rupees, the place Link starts), and it makes the Inventory page's amounts keep every press. Two defects found by building a save with the Inventory page are fixed too: a song unlocked there was missing from the game's save, and the Deku Stick and Deku Nut bags had no row. ## How to reproduce For #871 (the Inventory part): **Seen on:** Windows 11, RTX 5080, NVIDIA 621.24, v3.0.0-rc.4 (the reporter's `report.txt`) **Settings and switches:** Debug tools On **Steps:** open Debug, Inventory, Items, a quantity (bombs), Edit amount, then hold or press Right several times. **Expected:** the quantity goes up by the number of presses. **Actual:** one item is added. The reporter's `longshot_log.txt` has exactly one `cheats: inventory ... +1` line for each item he edited: the other presses never reached the game. ## What changed The Progress page reads the player's own game files when it first opens (a few seconds, on a thread of its own), builds its areas and categories from them, reads the live flags and changes them through the game's own setters at Link's updates, so the pause screens and the game's autosave see a change as they see the real thing. No flag name, list or table of the game is in the source. The Inventory amounts now go through a queue. - `gpu/vk/game_files.h`, `game_byml.h` (new): the game-file readers (moved out of `vk_game_font.h`, which keeps three `using` lines) and a lazy BYML reader. - `gpu/vk/progress_catalog.h`, `progress_editor.h`, `progress_types.h`, `progress_boss_sets.h` (new): the catalogue (areas, chests, Gold Skulltulas, pieces of heart, containers, dungeon items, small keys, bosses, quests, start places) made from the player's files by rules, and the `Editor` (have/of, set one, set all, a boss's end set in one batch, the counters that depend on them). A start place on the other age's map than Link's is greyed. The bosses' end sets are 32-bit hashes only, taken from #68's tables (no name). - `gpu/vk/progress_page.h`, `gpu/vk/vk_menu.cpp`: the page (keys, navigation, drawing) and its row on the Debug tab (`Row::cheat` 12, after Inventory). - `gpu/vk/vk_api.h`, `gpu/vk/progress_api.h`, `host/rx_backend.c`: three `MkwVkHost` calls, `progress_read`, `progress_apply`, `progress_state`. **`MKWVK_API_VERSION` 29 → 31** (main is 29; the open #1358 holds 30 and #68 holds 33). - `host/oot_progress.c`, `host/hos_main.c`: the game side: reads straight from the game's memory on the menu's thread (every pointer checked to lie in the guest), writes queued for Link's update (at most 32 changes an update, in order, through `SetBool`, `SetInt`, `SetEnum`, `SetKey64` and the pouch event, only while a ring has room). `oot_teleport` is split so the travel to a start place sends the same event under the same checks. - `gpu/vk/cheat_queue.h`, `gpu/vk/vk_menu.cpp` (#871): the Debug tab's actions were one atomic int that Link's update took with an exchange; a press before the next update replaced the waiting one. They wait in a queue of sixteen now and the presses of one item's amount are summed into the action that is waiting. - `host/hos_main.c` `oot_gamedata_set_bool`: writes the saved copy of a Bool too (the game's autosave writes the file from it): a song unlocked on the Inventory page was in the running game and not in the save (5 of 12 songs in a made save). The age switch shares the function. - `gpu/vk/oot_cheat_items.h`: rows for the Deku Stick and Deku Nut bags (three sizes each). - `docs/progress-editor.md` (new), `README.md`, `docs/development.md`: how to use it, what each change does, `HOS_OOT_TRACE_PROGRESS=1`, API versions. - tests (all game-free): `test_progress_catalog.py`, `test_progress_page.py`, `test_progress_menu.py`, `test_oot_progress_host.py`, `test_cheat_queue.py` new; `test_cheat_items.py`, `test_pipeline_tour.py`, `test_audio_output_devices.py` updated, none weakened. What it does not do: - **Quests are read-only.** The game's quest manager undoes a step written while it runs; only a boss's end set moves its quest. - **Hearts are given as a pickup**, never by writing life (the game rewrites life every frame). The pieces in hand are the pieces set modulo four. - **Ganon and Ganondorf** get a kill counter only: no end set is carried for them. - **The Inventory page's Gold Skulltula Tokens row** still changes the count alone, not the placed Skulltulas' keys. - **Menu texts are English only.** ## Measurements Nothing to time: the page does nothing until it is opened, and its flag reads (a few hundred, twice a second) run on the menu's thread. What was checked is that it works, in Testing. ### Flags and settings One switch and one menu row, no ini key. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `HOS_OOT_TRACE_PROGRESS=1` | Logs each change the Progress editor applies (the flag's hash and the value) and each batch that stops | none | off | A log line for each change and each stopped batch | for a bug report about the editor | off; for testing | | Debug tab, **Progress** | Opens the editor (needs Debug tools On and a loaded save) | none | shown with the other tools | The page | untested on Windows | on with Debug tools | ## Testing **Tested:** Linux (Arch, kernel 7.2.15), RTX 4090 (NVIDIA 615.78.08), i9-13900K, 93 GB; headless, 2026-11-17; main @ 544229a26 and this PR @ 9bdbc2c94. - **The new game-free tests, both ways.** On main's source each fails: `tests/test_cheat_queue.py` (`vk_menu.cpp does not include cheat_queue.h`; the header is new), `tests/test_cheat_items.py` (`the StickBag rows are []`), `tests/test_oot_progress_host.py` `bool_both_copies` (`FAIL ... *at(song + 0x17) == 1`: the saved copy was not written), `tests/test_progress_catalog.cpp`'s start-place checks (they do not compile without the age guard). On this PR they pass; `test_cheat_queue.py` also under TSan (`--tsan`). The engine's test passed under g++, clang++, ASan+UBSan and TSan on an earlier head of this branch, and under g++ on this one. - **The whole suite**, `python -I -B tests/run_all.py --jobs 6` in a fresh home, once on this PR and once on main @ 544229a26. This PR: 668 passed, 41 failed, 17 skipped (709 checks). Main: 663 passed, 41 failed, 17 skipped (704 checks). The same 41 test files fail on both (compared by name, `reports/SaveEditGame-files/suite/final-*-suite.txt.names`): this machine's and main's own (`test_bug_report_defaults`, `test_cpu_report`, `test_crash_record`, `test_linux_pressure`, `test_mirror_budget`, `test_present_thread`, `test_profiling_mode`, `test_staging_burst`, `test_target_image_pool`, `test_missing_nup` and the rest of the list in the files). The five new files pass here: `test_cheat_queue`, `test_oot_progress_host`, `test_progress_catalog`, `test_progress_menu`, `test_progress_page`. - **Linux build.** A full `make_game.py` build of the branch (before one change to `tests/test_audio_output_devices.py`) exited 0 (176 s, the lifted code and objects from an earlier build of the same branch). - **Windows, compiled, not run.** The Windows-target syntax check of every changed fixture (llvm-mingw 20261104): PASS for all of them (`test_oot_progress_host`, `test_progress_catalog`, `test_progress_page`, `test_cheat_queue`, `test_cheat_items`, `test_audio_output_devices`); `test_pipeline_tour.py` runs on Linux only. `test_audio_output_devices.py` failed this check on main too (`'memmove'`/`'tmpfile'` deprecated: its parser fixture lacked `_CRT_SECURE_NO_WARNINGS`); it is added here. - **In the game** (Linux, NVIDIA, headless; the pictures are below; build of `4ca7bd4c4`, which differs from this head only in `tests/test_audio_output_devices.py`). One hold, two games on one made save (a child in Hyrule Field with 16 Deku Nuts, 5 Gold Skulltulas, 1 piece of heart in hand, 4 hearts, Gohma already beaten): game 1 was driven by scripted menu keys (`RX_VK_MENU_SCRIPT`, 150 keys) through Debug, Inventory (nuts: four Left, three Right at 0.7 s, four Right at 80 ms, two Left) and Debug, Progress (Hyrule Field's Chest 1, Gold Skulltulas 1 and 2, heart pieces 1 and 3; one heart more; Gohma cleared, then set again; the start place "Front Of Market", the child's map); then Link arrived there and the game saved. Game 2 is a new process on the files game 1 left, and its flags were read the moment play began, before any key: | Flag read from the running game | Before | After the keys (game 1) | Game 2, at once after loading | |---|---|---|---| | Deku Nuts | 16 | 17 (13 of 13 presses landed, each its own `cheats: inventory` line) | 17 | | Hyrule Field Chest 1 | not opened | opened | opened | | Gold Skulltula count (5 others already in the save) | 5 | 7 | 7 | | Pieces of heart in hand (set modulo four) | 1 | 3 | 3 | | Max life | 16 (4 hearts) | 20 (5 hearts) | 20 | | Gohma: counter, quest step | 1, `4c0a63f4` | 0, `576277fa` after the clear; then 1, `d52b1014` (the end step) | 1, `d52b1014` | The log has the 43 `progress:` lines (nine batches, every op "made", none skipped), then `save trace` lines at the arrival, and a save file written after the script began. Game 2 then drew the same pages with Chest 1, Skulltulas 1 and 2, pieces 1 and 3 `Had`, `5 of 20 hearts`, `3 of 4 for the next heart`, Gohma `Beaten`, and the Inventory page's Deku Nuts at quantity 17; the game's own pause screen showed 5 hearts and `Deku Nut 17/20`. No fatal, crash, device-lost or kernel driver line in either game. Pictures: `1-game1-editing.jpg` (the keys' effect page by page, the travel's arrival with `Saving...`), `2-game2-read-back.jpg` (game 2's pages), `3-game2-pause-screens.jpg`. ![Game 1: the Debug tab's Progress row, Chest 1 flipped to Had, Gold Skulltulas 1 and 2 Had, heart pieces 1 and 3 Had, one heart more (5 of 20), Gohma marked beaten, the start place chosen, and the arrival with the game saving.](https://git.magicbean.dev/attachments/4f4ea4dc-4caa-4187-940e-800c84f4f7fd) ![Game 2, a new process on the files game 1 saved: the same pages read back (Chest 1, Skulltulas 1 and 2, pieces 1 and 3 Had; 5 of 20 hearts, 3 of 4 pieces; Gohma beaten; Deku Nuts 17 on the Inventory page).](https://git.magicbean.dev/attachments/181e9703-0a81-4daf-9773-0af47f6f19de) ![Game 2's own pause screens: five hearts, Deku Nut 17 of 20, rupees 125.](https://git.magicbean.dev/attachments/8f60599b-c413-4027-9292-1b97f1c2bf80) - **#871:** the 13 key presses of the amounts all landed, in order, at the game's 60 updates a second. At that speed the old single slot would not have lost one either (Link took each press before the next), so the run shows that every press arrives, not the loss itself; the loss is shown by the game-free `test_cheat_queue.py` (two threads) and by the reporter's log. - **One difference from playing:** the save had Gohma's quest one step past the end step (`4c0a63f4`); the editor's "beaten" ends at the end step (`d52b1014`) and the pause screens, the autosave and the second load took it without a sign of trouble. A boss set this way may differ from the game's own in that one quest step. **Not tested:** - Windows: the editor, the queue and the host side have not run on Windows; the changed fixtures and the host were only compiled for it (above). - Other GPUs (AMD, Intel) and the Steam Deck: no run. The page uses the menu's own widgets and no new renderer code. - Adult Link, the dungeons' items and small keys, Set all and Clear all, rupees, the quests list, and every start place but one: not tried in the game (the game-free tests cover the rules on a test game). - Whether a boss marked beaten as a group leaves a save the game accepts in every part (only Gohma, one save); the other seven bosses' end sets come from #68's tables and were not run here. - A real controller or mouse on the page: the keys were scripted (`RX_VK_MENU_SCRIPT`); the mouse code is only read and tested on a fake. **Must be tested:** - Windows, any GPU (by hand, or a Windows request to the Test Farm for the Debug tab's Progress page): load a save, Debug tools On, Debug, Progress, Areas, an area, Chests, Enter on a chest, then Back to the top and Hearts and rupees, Right; expecting "Had" on the chest after a second and one heart more on the pause screen. - AMD or Intel graphics (by hand, or an AMD or Intel request to the Test Farm for the Debug tab's Progress page): the same steps, expecting the page to draw like the pictures above (it uses the menu's own widgets only) and "Had" on the chest. ## Risks **What could break:** The host reads the game's data manager from the menu's thread with every pointer checked against the guest window, and writes only at Link's update through the game's own setters; a game whose layout differs would answer "no such flag" (reads) or stop a batch with a log line (writes), not crash. A change to a quest-linked flag (a boss's end set) can leave a save the game would not have made (for example a boss marked beaten whose door the player has not opened); the page says what each change does. The queue replaces one atomic int, so a menu action now also waits behind a waiting one instead of replacing it. The `MkwVkHost` table grows by three entries after `monitor_select`. **Turning it off:** Debug tools Off hides the row; reverting the commits removes the page and the queue. **Compatibility:** `MKWVK_API_VERSION` 29 → 31: build the host and the renderer together. Saves and `longshot_options.ini` are not touched; a save the editor changed is the game's own save of the changed flags. ## Issues See #871 (the Inventory part: the reporter's log shows exactly the lost-press pattern the queue removes; the run in the game shows every press landing, not the old loss). Overlaps: #68 (co-op) carries the same eight boss end sets in `host/oot_coop.c`; this PR holds them as hashes in `gpu/vk/progress_boss_sets.h` and reads the same flags through its own host calls. ## 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] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main` (544229a26). - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). - [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. - [x] Screenshots of the same spot, captioned like the Measurements columns, for a change that shows on screen. - [x] `MKWVK_API_VERSION` bumped (`gpu/vk/vk_api.h`'s `MkwVkHost` or `MkwVkRenderer` changed). - [x] A game-free test added for the fix, failing on `main` and passing here. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [x] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. - [x] Docs updated. New on this forge; not opened on GitHub.
`read_file`, `unzstd` and `sarc_file` were written for the menu's game font (`vk_game_font.h`) and are about to be used by a second
reader of the player's own game files (the Progress editor). They move to `gpu/vk/game_files.h`, with the dictionary of the pack
chosen by the frame's dictionary id; `vk_game_font.h` keeps three `using` lines, so `vk_imgui.cpp` and `tests/test_game_font.cpp`
name them where they did.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Three new `MkwVkHost` calls, appended after `monitor_select`: `progress_read` (the live value of each of n flags, read on the
caller's thread from the game's memory; -1 while no save is loaded), `progress_apply` (queue up to 1,024 changes: set a Bool, an
Int, an Enum or a 64-bit key, add to a pouch content, travel to a start) and `progress_state` (a ticket's answer).
`host/oot_progress.c` applies the queue at Link's updates, at most 32 an update, in order, through the game's own setters (never a
direct write), after checking that their ring has room; a batch the game stops taking is reported, not retried for ever.

`oot_teleport` is split into `oot_teleport_ready` and `oot_teleport_send` so that a travel to a named start sends the same event
under the same checks (one every 8 s, none while an event plays or a map loads); `oot_pouch_change` is reused as it is.

`tests/test_oot_progress_host.py` compiles the host file with a flat fake guest memory (`-Wall -Wextra -Werror`) and checks reads,
order, the per-update cap, ring-full stops and resumes, the refusals and the travel. `tests/test_audio_output_devices.py` takes
version 31 and the three new last callbacks.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
`progress_catalog.h` reads the player's own game files at run time (on a worker thread, as the menu's game font does) and builds
the areas and categories of progress from them: chests, Gold Skulltulas, pieces of heart, heart containers, dungeon maps,
compasses, boss keys, small keys, bosses, quests and the named start places. No flag name, list or table of the game is in the
source: only the rules that turn the game's data into categories, and the boss end sets as hashes (`progress_boss_sets.h`).
`game_byml.h` is the lazy BYML reader it needs. `progress_editor.h` (`Editor`, a `Source` the page drives) answers have/of for a
category, sets or clears one entry or a whole category, fixes the counters that depend on them (tokens, pieces), and gives a boss
its whole end set, quest step, kill counter, heart container and boss key in one batch (a boss whose hashes the game's flag list
does not declare is shown, not editable; quests are listed read-only). A start place on the other age's map than Link's is greyed
and refused (the Bool `Sequence_IsChildhood` says his age; a map named for neither age holds nothing back): the travel's event
takes a map and no age. It reads and writes through a `FlagIO` that it is given, so the tests use a fake game.

`tests/test_progress_catalog.py` builds a small test game as a romfs folder and runs the C++ fixture under g++ or clang++.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
A new row on the Debug tab after Inventory (Row::cheat 12) opens page 6: areas as cards with have/of, an area's categories, the
entries of a category with Had / Missing, Set all and Clear all (asked twice: a mass change is not one press), hearts and rupees,
the bosses as groups, the quest steps (read-only), and the start places (Enter travels there and lets the game save it). The page
says `Reading the game's files...` while the catalogue is made, why it failed when it cannot be, and `Load a save to edit the
progress.` without a save. `progress_page.h` holds the keys and the navigation apart from the drawing, so
`tests/test_progress_page.py` runs them on a fake source; `tests/test_progress_menu.py` checks the row's wiring in vk_menu.cpp.
The Progress row is in the README's Debug table.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
`oot_gamedata_set_bool` wrote a Bool's live byte (entry + 22) only. The game's autosave writes the file from the saved copy (the
byte after it), so a song unlocked on the Inventory page read as learned in the running game and was missing from the save: in a
save built with the editor 5 of 12 songs were not there (ClearedSave, hold 1; the same run showed that writing both copies of a Bool
or Int persists: 139 of 143 rows). Both bytes are written now; the age switch shares the function.

`tests/test_oot_progress_host.py` (`bool_both_copies`) cuts the real function out of host/hos_main.c and runs it on the fixture's
game data: it fails on the live-only write (`FAIL ... *at(song + 0x17) == 1`) and passes with both bytes written, the entry's other
bytes and the other flags untouched.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
The Upgrades section listed the bomb bags, quivers and bullet bags but not the bags that raise the sticks' and the nuts' capacity
(`Item_StickBag_*`, `Item_NutBag_*`, three sizes each), so a save made with the editor never held more than the smallest of either
(ClearedSave, hold 1). Six rows, after the bullet bags; each is an item Link has or not, like the other bags.
`tests/test_cheat_items.py` fails without them (`the StickBag rows are []`).

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
fix(menu): the Debug tab's actions wait in a queue and an amount's presses are summed, so a held key on the Inventory page loses none (#871)
Some checks failed
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 8s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 15s
CI / Workflow lint (actionlint) (pull_request) Successful in 16s
Website / Website on Cloudflare (pull_request_target) Has been skipped
Third-party parts / As their notes say (pull_request) Successful in 27s
PR description / Description follows the template (pull_request_target) Successful in 9s
9bdbc2c948
The menu handed Link's update one action through a single atomic int (`cheat_action`, taken with an exchange at each update). A
press before the next update replaced the one waiting, so on the Inventory page a held Left or Right (12 presses a second, 30 after
a second and a half) or a quick run of them kept only the last whenever the game ran slower than the keys repeat. The reporter's log
of #871 has exactly one `cheats: inventory ... +1` line for each item he edited and says "repeated presses result in only one item
being added". The host side never saw the others.

`gpu/vk/cheat_queue.h` (`CheatQueue`, a mutex, sixteen places): actions wait in order; the presses of one item's amount are summed
into the action that is waiting (within -64 to 63, what one action holds), so Link's next update gives the whole change in one
pouch event instead of several that could overtake each other. Every `cheat_action.store` in vk_menu.cpp is a `push` or
`push_amount` now, and `menu_take_cheat_action` takes from the queue.

`tests/test_cheat_queue.py` compiles the header (also under TSan): order, the limit of sixteen, the sums, never into another
item's, a tool's or an unlock, the saturation, and 200,000 presses from one thread against a taker on another with none lost; it
reads vk_menu.cpp for the wiring (it fails on main's source: `vk_menu.cpp does not include cheat_queue.h`).
`tests/test_pipeline_tour.py`'s two source checks name the new calls.

This is the defect the log shows. A run of the game that settles whether it is the whole of #871 (the count the menu shows lags
the game's by up to half a second, and the pouch's own event lands a few presents later) is still to be read.

Assisted-by: Claude Sonnet 5.5
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
mooki changed title from WIP: feat(menu): a Progress editor in the Debug tools (chests, Gold Skulltulas, hearts, bosses, start place) and Inventory amounts that keep every press to feat(menu): a Progress editor in the Debug tools (chests, Gold Skulltulas, hearts, bosses, start place) and Inventory amounts that keep every press 2026-11-17 13:25:55 +00:00
Some checks failed
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 8s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 15s
CI / Workflow lint (actionlint) (pull_request) Successful in 16s
Website / Website on Cloudflare (pull_request_target) Has been skipped
Third-party parts / As their notes say (pull_request) Successful in 27s
PR description / Description follows the template (pull_request_target) Successful in 9s
This pull request has changes conflicting with the target branch.
  • gpu/vk/vk_api.h
  • host/rx_backend.c
  • tests/test_audio_output_devices.py
View command line instructions

Manual merge helper

Use this merge commit message when completing the merge manually.

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'progress-editor:mooki-progress-editor'
git switch 'mooki-progress-editor'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
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!1411
No description provided.