WIP: feat(game): achievements with unlock pop-ups and an Insert menu page #392

Draft
Zapiltar wants to merge 8 commits from Zapiltar/Longshot:feat/achievements into main
First-time contributor

Type: feat · Risk: low · Tested on: Windows 11, RTX 3060 Ti · Needs: Linux or a Steam Deck, any GPU

TL;DR

The PC port keeps no record of a player's milestones. This PR adds achievements: 51 of them, following the
RetroAchievements list for the N64 game in its order but with our own names, words and icons, with a short pop-up when
one is earned and a list in the Insert menu. Sixteen interleaved runs in the Market found no frame-rate cost (main 53.5
fps, this PR 54.3), and loading a save in the game unlocked exactly what it holds.

Breakdown

  • Who it helps: anyone who wants a record of their progress: the stones, medallions, gear, songs and side quests.
  • What was wrong: nothing marked a milestone beyond the save file itself.
  • What changes: 51 achievements, unlocked once per install and kept in user/achievements.txt, a pop-up when one is
    earned (Gameplay → Achievement alerts) and a list page (Gameplay → Achievements).
  • What does not change: saves, the game's rendering, the shader caches (no vk_api.h change); nothing unlocks in a
    run where a debug tool was used.
  • How it was checked: the game-free checks (test_oot_achievements and the menu checks), a save loaded in the game
    (9 of 51 unlocked, exactly the ones it holds), the menu and page looked at in main's new menu, and sixteen runs
    against main: no cost.
  • What is still open: a Linux or Steam Deck build and run; a bottle (and milk) seen in a real save.
  • Risk: low: a wrong item or flag name means an achievement that never unlocks, nothing more.

Why

Players have no record of their milestones beyond the save itself: nothing marks getting the Master Sword, defeating
Ganon or collecting the Gold Skulltula Tokens. This adds optional achievements, with a pop-up when one is earned and a
list in the Insert menu. No issue asks for it (the tracker searched: none on achievements); it was first discussed in
#dev-work.

What changed

51 achievements, each unlocked once and kept in a small file beside the saves. The list is the RetroAchievements base
set for the N64 game, one row per achievement of theirs and in their order, as far as the game side can see it happen:
51 of its 97 (the other 46, boss challenges and minigames the game keeps no readable sign of yet, are listed in
docs/achievements.md). Only the milestones are shared: every title, description and icon is our own. The game side
checks them in the Inventory page's existing half-second refresh, with no new game hook, and nothing unlocks in a run
where a debug tool was used.

  • List: gpu/vk/oot_achievements.h, an X-macro shared by the game side and the menu (id, title, description, the
    pouch contents it asks for: all of them, or any for the bag tiers; name>=N for a count, the Skulltula Tokens), in
    the RetroAchievements set's order. Item names are the Inventory page's own (gpu/vk/oot_cheat_items.h). Start here,
    then host/oot_achievements.c.
  • Tracking: host/oot_achievements.c hos_oot_achievements_check, called from host/hos_main.c
    oot_inventory_refresh with the counts it already reads twice a second. Rows that need more read a game flag by name
    (gd:, through the control bridge's GameData reader hos_oot_flag_number in host/oot_state_tap.c, under the same
    lock); Bottles adds up the bottle pouch items, Milk the milk among them, and Songs counts the twelve songs
    (OOT_ACHIEVEMENT_SONGS). Unlocks go to user/achievements.txt (<id> <UTC time>, written
    whole through a temporary file; unknown ids kept).
  • Debug tools: a debug action (inventory editor, teleport, age switch, clock) calls hos_oot_achievements_cheated in
    oot_update_player_cheats: nothing unlocks for the rest of that run.
  • Menu (gpu/vk/vk_menu.cpp): the pop-up draw_achievement_toast (with menu_record / menu_record_image, over
    everything; more than three at once show as one "N achievements unlocked"); the Gameplay tab's Achievement alerts
    row; the Achievements row and page draw_achievements (page 6, the Teleport page's layout and keys).
  • Icons: assets/achievements/*.png, 102 icons (unlocked and locked), drawn from plain shapes by
    scripts/make_achievement_icons.py (provenance in assets/achievements/PROVENANCE.txt, format in its README.md).
    nx2/achievement_icons.py packs them into one atlas in a generated header, as nx2/logo_rgba.py does the logo;
    gpu/vk/vk_imgui.cpp achievement_icon loads it as a single texture.
  • No change to vk_api.h or vk_replay.cpp: vk_api.h stamps the shader caches, so this PR makes no player
    prepare shaders again. The game side tells the menu through rx_option_set ids past the Inventory page's.
  • Docs: docs/achievements.md (design, the list and the set's rows not tracked yet, open questions, testing); the
    README's option table.
  • Tests: tests/test_oot_achievements.py (new); test_fps_overlay_order.py, test_readme_menu_rows.py and
    test_shader_stamp_cache.py updated for the pop-up, the new rows and the icons' build step.
  • Left for follow-ups on purpose: players' own icon packs from the mods folder (needs a runtime PNG decoder), and
    the Longshot Launcher's list page (it can read user/achievements.txt).

Screenshots (After: this PR @ 44deed6e on main @ d664e342, main's new Insert menu style; RTX 3060 Ti, 1920x1080,
Quality preset Auto, taken from the screen in the Market with the test save. Before: main has none of it.)

The Gameplay tab's new rows:

The Gameplay tab's rows

The Achievements page, 9 of 51 unlocked from this save:

The Achievements page

The pop-up (unchanged since; this PR @ c996bb31, the first list) is in the first screenshots'
comment
.

Measurements

Verdict: no cost found. Sixteen interleaved runs in the Market put this PR at 54.32 fps against main's 53.45 (+0.88,
inside the runs' spread of about 3 fps each side), and the PR came out ahead in 6 of the 8 pairs. The last measurement's
"slowest window about 2 fps lower" shows again only when each run's single worst 5-second window is taken (51.0 against
48.4); across all 95 windows of each side the slow end is the same: the 5th percentile 45.9 against 46.4, the 10th 47.5
against 47.4, and 19% against 18% of the windows under 50 fps. The new code itself is about 50 µs every half second
(timed directly before). Memory is the same within the runs' spread. Passed.

Hardware: Windows 11 Home 10.0.26300, NVIDIA GeForce RTX 3060 Ti 8 GB (driver 621.14), Intel Core i7-12700F (12 cores,
20 threads), 64 GB RAM
Scene: the Market (child), standing still with no input; borderless 1920x1080 on a second monitor, Quality preset Auto
(this PC: no upscaler), no frame generation, Game frame rate cap Uncapped, V-Sync Off, volume 0 (the sound still mixed).
Method: built with scripts/dev_packs.py: a base of main @ d664e342, this PR as a pack on it (its longshot.exe and
longshot_vk.dll), and a runtime of each, so both arms share every other file and the same shader caches. Every run
started from a copy of one pinned options file (HOS_OPTIONS_FILE) and the same save, through the control bridge
(HOS_CONTROL, scripts/longshot_ctl.py): A through the title until in play, 30 s, then 60 s of the game's own
5-second fps lines, and the process's private memory at the end. One warm-up run of each first (not counted), then eight
pairs, the order alternating (main first in the odd pairs, the PR first in the even ones). A key press that reached the
game opened its menu in one main run; that run was dropped and run again, and the runs since give the focus back to
the window that had it. The number is the median of a run's 5-second windows; the table gives the median of the eight.
How to reproduce: a save in the Market, the settings above, then per build: start with HOS_CONTROL and
HOS_OPTIONS_FILE set, longshot_ctl.py press A until status says play, 30 s, then read the vi: ... fps over the last 5.0 s lines of logs/longshot_log.txt for 60 s.

Before: main @ d664e342 After: this PR @ 44deed6e
fps, median of each run, pairs 1 to 8 53.8 / 49.2 / 56.2 / 53.0 / 55.5 / 48.2 / 52.0 / 57.2 51.2 / 52.0 / 51.0 / 53.8 / 56.5 / 56.7 / 54.8 / 57.5
fps, median of the eight runs 53.45 54.32 (+0.88, +1.6%)
the PR ahead in 6 of 8 pairs
5 s windows, 5th / 10th percentile (all 95) 45.9 / 47.5 46.4 / 47.4
5 s windows under 50 fps 19% 18%
lowest 5 s window of each run, median 51.0 48.4
frame time from the median fps 18.71 ms 18.41 ms
private memory at the end, median (runs vary by ±250 MB) 16669 MB 16383 MB

The new code, timed directly (2026-11-15, a temporary timer around it, one run in the Market, never committed): the
bottle reads average 28 µs and the achievements check, the game-flag lookups included, 21 µs per refresh, against 320 µs
for the Inventory page's item reads that were already there; at two refreshes a second that is about 0.01% of the time.
This list adds no new kind of read: the songs are counted from the counts the page already has, and the milk from the
bottle reads. The icons are one 102-icon atlas (about 6.7 MB), drawn only while the page or a pop-up shows. Earlier
measurements: main @ 0caf0618 against this PR's first 29 rows, 56.2 against 56.5 fps (four runs, 2026-11-14); main @
5274fb72 against the 82-row list, 56.25 against 55.28 (twelve runs, 2026-11-15).

Runs from 23:30 on 2026-11-17 to 00:12 local (this PR @ 44deed6e; the docs/tested commit on top, a8e21dc3, adds docs
only); their files: docs/tested/2026-11-17-achievements-zapiltar-run01.md to
2026-11-18-achievements-zapiltar-run16.md.

The log lines (each measured run's 60 s)
main @ d664e342, main-1
vi: 7280 frames presented (53.2 fps over the last 5.0 s, interval 1)
vi: 7546 frames presented (53.0 fps over the last 5.0 s, interval 1)
vi: 7817 frames presented (54.2 fps over the last 5.0 s, interval 1)
vi: 8089 frames presented (54.4 fps over the last 5.0 s, interval 1)
vi: 8350 frames presented (52.0 fps over the last 5.0 s, interval 1)
vi: 8620 frames presented (53.9 fps over the last 5.0 s, interval 1)
vi: 8892 frames presented (54.3 fps over the last 5.0 s, interval 1)
vi: 9159 frames presented (53.3 fps over the last 5.0 s, interval 1)
vi: 9422 frames presented (52.5 fps over the last 5.0 s, interval 1)
vi: 9693 frames presented (54.1 fps over the last 5.0 s, interval 1)
vi: 9964 frames presented (54.2 fps over the last 5.0 s, interval 1)
vi: 10233 frames presented (53.8 fps over the last 5.0 s, interval 1)
this PR @ 44deed6e, pr-1
vi: 6383 frames presented (49.5 fps over the last 5.0 s, interval 1)
vi: 6619 frames presented (47.0 fps over the last 5.0 s, interval 1)
vi: 6856 frames presented (47.4 fps over the last 5.0 s, interval 1)
vi: 7120 frames presented (52.8 fps over the last 5.0 s, interval 1)
vi: 7381 frames presented (52.2 fps over the last 5.0 s, interval 1)
vi: 7642 frames presented (52.1 fps over the last 5.0 s, interval 1)
vi: 7899 frames presented (51.2 fps over the last 5.0 s, interval 1)
vi: 8134 frames presented (46.9 fps over the last 5.0 s, interval 1)
vi: 8390 frames presented (51.1 fps over the last 5.0 s, interval 1)
vi: 8662 frames presented (54.2 fps over the last 5.0 s, interval 1)
vi: 8909 frames presented (49.3 fps over the last 5.0 s, interval 1)
vi: 9167 frames presented (51.4 fps over the last 5.0 s, interval 1)
this PR @ 44deed6e, pr-2
vi: 6762 frames presented (47.3 fps over the last 5.0 s, interval 1)
vi: 7022 frames presented (51.8 fps over the last 5.0 s, interval 1)
vi: 7255 frames presented (46.4 fps over the last 5.0 s, interval 1)
vi: 7486 frames presented (46.1 fps over the last 5.0 s, interval 1)
vi: 7747 frames presented (52.2 fps over the last 5.0 s, interval 1)
vi: 7994 frames presented (49.3 fps over the last 5.0 s, interval 1)
vi: 8255 frames presented (52.2 fps over the last 5.0 s, interval 1)
vi: 8515 frames presented (51.9 fps over the last 5.0 s, interval 1)
vi: 8775 frames presented (52.0 fps over the last 5.0 s, interval 1)
vi: 9038 frames presented (52.5 fps over the last 5.0 s, interval 1)
vi: 9301 frames presented (52.4 fps over the last 5.0 s, interval 1)
vi: 9564 frames presented (52.6 fps over the last 5.0 s, interval 1)
main @ d664e342, main-2
vi: 6742 frames presented (51.3 fps over the last 5.0 s, interval 1)
vi: 7007 frames presented (52.8 fps over the last 5.0 s, interval 1)
vi: 7254 frames presented (49.2 fps over the last 5.0 s, interval 1)
vi: 7509 frames presented (50.9 fps over the last 5.0 s, interval 1)
vi: 7741 frames presented (46.4 fps over the last 5.0 s, interval 1)
vi: 7983 frames presented (48.4 fps over the last 5.0 s, interval 1)
vi: 8237 frames presented (50.7 fps over the last 5.0 s, interval 1)
vi: 8474 frames presented (47.2 fps over the last 5.0 s, interval 1)
vi: 8712 frames presented (47.5 fps over the last 5.0 s, interval 1)
vi: 8943 frames presented (46.1 fps over the last 5.0 s, interval 1)
vi: 9208 frames presented (52.8 fps over the last 5.0 s, interval 1)
main @ d664e342, main-3
vi: 6763 frames presented (55.0 fps over the last 5.0 s, interval 1)
vi: 7034 frames presented (54.0 fps over the last 5.0 s, interval 1)
vi: 7307 frames presented (54.4 fps over the last 5.0 s, interval 1)
vi: 7573 frames presented (53.1 fps over the last 5.0 s, interval 1)
vi: 7856 frames presented (56.5 fps over the last 5.0 s, interval 1)
vi: 8139 frames presented (56.5 fps over the last 5.0 s, interval 1)
vi: 8421 frames presented (56.4 fps over the last 5.0 s, interval 1)
vi: 8692 frames presented (54.2 fps over the last 5.0 s, interval 1)
vi: 8974 frames presented (56.3 fps over the last 5.0 s, interval 1)
vi: 9257 frames presented (56.5 fps over the last 5.0 s, interval 1)
vi: 9539 frames presented (56.2 fps over the last 5.0 s, interval 1)
vi: 9823 frames presented (56.8 fps over the last 5.0 s, interval 1)
this PR @ 44deed6e, pr-3
vi: 7670 frames presented (55.8 fps over the last 5.0 s, interval 1)
vi: 7926 frames presented (51.0 fps over the last 5.0 s, interval 1)
vi: 8133 frames presented (41.3 fps over the last 5.0 s, interval 1)
vi: 8365 frames presented (46.3 fps over the last 5.0 s, interval 1)
vi: 8620 frames presented (50.9 fps over the last 5.0 s, interval 1)
vi: 8877 frames presented (51.3 fps over the last 5.0 s, interval 1)
vi: 9106 frames presented (45.8 fps over the last 5.0 s, interval 1)
vi: 9344 frames presented (47.6 fps over the last 5.0 s, interval 1)
vi: 9609 frames presented (52.9 fps over the last 5.0 s, interval 1)
vi: 9869 frames presented (51.8 fps over the last 5.0 s, interval 1)
vi: 10139 frames presented (53.9 fps over the last 5.0 s, interval 1)
this PR @ 44deed6e, pr-4
vi: 6865 frames presented (47.1 fps over the last 5.0 s, interval 1)
vi: 7136 frames presented (54.1 fps over the last 5.0 s, interval 1)
vi: 7380 frames presented (48.7 fps over the last 5.0 s, interval 1)
vi: 7622 frames presented (48.4 fps over the last 5.0 s, interval 1)
vi: 7890 frames presented (53.5 fps over the last 5.0 s, interval 1)
vi: 8164 frames presented (54.7 fps over the last 5.0 s, interval 1)
vi: 8421 frames presented (51.4 fps over the last 5.0 s, interval 1)
vi: 8679 frames presented (51.6 fps over the last 5.0 s, interval 1)
vi: 8955 frames presented (55.1 fps over the last 5.0 s, interval 1)
vi: 9236 frames presented (56.1 fps over the last 5.0 s, interval 1)
vi: 9516 frames presented (56.0 fps over the last 5.0 s, interval 1)
vi: 9799 frames presented (56.5 fps over the last 5.0 s, interval 1)
main @ d664e342, main-4
vi: 8294 frames presented (54.9 fps over the last 5.0 s, interval 1)
vi: 8573 frames presented (55.7 fps over the last 5.0 s, interval 1)
vi: 8839 frames presented (53.1 fps over the last 5.0 s, interval 1)
vi: 9090 frames presented (50.1 fps over the last 5.0 s, interval 1)
vi: 9355 frames presented (53.0 fps over the last 5.0 s, interval 1)
vi: 9619 frames presented (52.8 fps over the last 5.0 s, interval 1)
vi: 9876 frames presented (51.2 fps over the last 5.0 s, interval 1)
vi: 10144 frames presented (53.4 fps over the last 5.0 s, interval 1)
vi: 10408 frames presented (52.7 fps over the last 5.0 s, interval 1)
vi: 10666 frames presented (51.5 fps over the last 5.0 s, interval 1)
vi: 10934 frames presented (53.4 fps over the last 5.0 s, interval 1)
vi: 11202 frames presented (53.4 fps over the last 5.0 s, interval 1)
main @ d664e342, main-5
vi: 7790 frames presented (54.8 fps over the last 5.0 s, interval 1)
vi: 8067 frames presented (55.4 fps over the last 5.0 s, interval 1)
vi: 8342 frames presented (54.9 fps over the last 5.0 s, interval 1)
vi: 8617 frames presented (54.8 fps over the last 5.0 s, interval 1)
vi: 8895 frames presented (55.5 fps over the last 5.0 s, interval 1)
vi: 9173 frames presented (55.6 fps over the last 5.0 s, interval 1)
vi: 9450 frames presented (55.3 fps over the last 5.0 s, interval 1)
vi: 9728 frames presented (55.5 fps over the last 5.0 s, interval 1)
vi: 10008 frames presented (55.8 fps over the last 5.0 s, interval 1)
vi: 10289 frames presented (56.0 fps over the last 5.0 s, interval 1)
vi: 10570 frames presented (56.2 fps over the last 5.0 s, interval 1)
vi: 10851 frames presented (56.1 fps over the last 5.0 s, interval 1)
this PR @ 44deed6e, pr-5
vi: 6681 frames presented (56.6 fps over the last 5.0 s, interval 1)
vi: 6964 frames presented (56.5 fps over the last 5.0 s, interval 1)
vi: 7248 frames presented (56.6 fps over the last 5.0 s, interval 1)
vi: 7534 frames presented (57.1 fps over the last 5.0 s, interval 1)
vi: 7809 frames presented (55.0 fps over the last 5.0 s, interval 1)
vi: 8096 frames presented (57.4 fps over the last 5.0 s, interval 1)
vi: 8381 frames presented (56.9 fps over the last 5.0 s, interval 1)
vi: 8667 frames presented (57.1 fps over the last 5.0 s, interval 1)
vi: 8922 frames presented (50.8 fps over the last 5.0 s, interval 1)
vi: 9175 frames presented (50.5 fps over the last 5.0 s, interval 1)
vi: 9456 frames presented (56.0 fps over the last 5.0 s, interval 1)
vi: 9705 frames presented (49.7 fps over the last 5.0 s, interval 1)
this PR @ 44deed6e, pr-6
vi: 6527 frames presented (56.6 fps over the last 5.0 s, interval 1)
vi: 6810 frames presented (56.4 fps over the last 5.0 s, interval 1)
vi: 7094 frames presented (56.7 fps over the last 5.0 s, interval 1)
vi: 7376 frames presented (56.3 fps over the last 5.0 s, interval 1)
vi: 7662 frames presented (57.2 fps over the last 5.0 s, interval 1)
vi: 7942 frames presented (55.9 fps over the last 5.0 s, interval 1)
vi: 8226 frames presented (56.7 fps over the last 5.0 s, interval 1)
vi: 8508 frames presented (56.4 fps over the last 5.0 s, interval 1)
vi: 8790 frames presented (56.3 fps over the last 5.0 s, interval 1)
vi: 9076 frames presented (57.0 fps over the last 5.0 s, interval 1)
vi: 9362 frames presented (57.1 fps over the last 5.0 s, interval 1)
vi: 9648 frames presented (57.1 fps over the last 5.0 s, interval 1)
main @ d664e342, main-6
vi: 6610 frames presented (48.6 fps over the last 5.0 s, interval 1)
vi: 6856 frames presented (49.1 fps over the last 5.0 s, interval 1)
vi: 7079 frames presented (44.5 fps over the last 5.0 s, interval 1)
vi: 7340 frames presented (52.1 fps over the last 5.0 s, interval 1)
vi: 7604 frames presented (52.7 fps over the last 5.0 s, interval 1)
vi: 7829 frames presented (44.9 fps over the last 5.0 s, interval 1)
vi: 8090 frames presented (52.0 fps over the last 5.0 s, interval 1)
vi: 8306 frames presented (43.2 fps over the last 5.0 s, interval 1)
vi: 8541 frames presented (46.8 fps over the last 5.0 s, interval 1)
vi: 8771 frames presented (45.9 fps over the last 5.0 s, interval 1)
vi: 9010 frames presented (47.8 fps over the last 5.0 s, interval 1)
vi: 9260 frames presented (49.9 fps over the last 5.0 s, interval 1)
main @ d664e342, main-7
vi: 6751 frames presented (52.5 fps over the last 5.0 s, interval 1)
vi: 6974 frames presented (44.5 fps over the last 5.0 s, interval 1)
vi: 7229 frames presented (50.8 fps over the last 5.0 s, interval 1)
vi: 7473 frames presented (48.7 fps over the last 5.0 s, interval 1)
vi: 7728 frames presented (50.9 fps over the last 5.0 s, interval 1)
vi: 7989 frames presented (52.1 fps over the last 5.0 s, interval 1)
vi: 8254 frames presented (52.9 fps over the last 5.0 s, interval 1)
vi: 8514 frames presented (51.9 fps over the last 5.0 s, interval 1)
vi: 8778 frames presented (52.8 fps over the last 5.0 s, interval 1)
vi: 9027 frames presented (49.7 fps over the last 5.0 s, interval 1)
vi: 9289 frames presented (52.3 fps over the last 5.0 s, interval 1)
vi: 9554 frames presented (52.9 fps over the last 5.0 s, interval 1)
this PR @ 44deed6e, pr-7
vi: 6149 frames presented (54.8 fps over the last 5.0 s, interval 1)
vi: 6420 frames presented (54.1 fps over the last 5.0 s, interval 1)
vi: 6694 frames presented (54.8 fps over the last 5.0 s, interval 1)
vi: 6970 frames presented (55.1 fps over the last 5.0 s, interval 1)
vi: 7249 frames presented (55.6 fps over the last 5.0 s, interval 1)
vi: 7523 frames presented (54.7 fps over the last 5.0 s, interval 1)
vi: 7798 frames presented (54.9 fps over the last 5.0 s, interval 1)
vi: 8067 frames presented (53.7 fps over the last 5.0 s, interval 1)
vi: 8344 frames presented (55.2 fps over the last 5.0 s, interval 1)
vi: 8621 frames presented (55.2 fps over the last 5.0 s, interval 1)
vi: 8897 frames presented (55.0 fps over the last 5.0 s, interval 1)
vi: 9165 frames presented (53.5 fps over the last 5.0 s, interval 1)
this PR @ 44deed6e, pr-8
vi: 5977 frames presented (52.5 fps over the last 5.0 s, interval 1)
vi: 6250 frames presented (54.4 fps over the last 5.0 s, interval 1)
vi: 6539 frames presented (57.7 fps over the last 5.0 s, interval 1)
vi: 6827 frames presented (57.6 fps over the last 5.0 s, interval 1)
vi: 7116 frames presented (57.7 fps over the last 5.0 s, interval 1)
vi: 7398 frames presented (56.2 fps over the last 5.0 s, interval 1)
vi: 7683 frames presented (56.9 fps over the last 5.0 s, interval 1)
vi: 7970 frames presented (57.3 fps over the last 5.0 s, interval 1)
vi: 8260 frames presented (57.9 fps over the last 5.0 s, interval 1)
vi: 8551 frames presented (58.0 fps over the last 5.0 s, interval 1)
vi: 8832 frames presented (56.1 fps over the last 5.0 s, interval 1)
vi: 9121 frames presented (57.6 fps over the last 5.0 s, interval 1)
main @ d664e342, main-8
vi: 6071 frames presented (56.8 fps over the last 5.0 s, interval 1)
vi: 6358 frames presented (57.3 fps over the last 5.0 s, interval 1)
vi: 6647 frames presented (57.7 fps over the last 5.0 s, interval 1)
vi: 6931 frames presented (56.8 fps over the last 5.0 s, interval 1)
vi: 7216 frames presented (56.8 fps over the last 5.0 s, interval 1)
vi: 7502 frames presented (57.1 fps over the last 5.0 s, interval 1)
vi: 7787 frames presented (57.0 fps over the last 5.0 s, interval 1)
vi: 8072 frames presented (56.9 fps over the last 5.0 s, interval 1)
vi: 8362 frames presented (57.8 fps over the last 5.0 s, interval 1)
vi: 8652 frames presented (57.8 fps over the last 5.0 s, interval 1)
vi: 8939 frames presented (57.4 fps over the last 5.0 s, interval 1)
vi: 9229 frames presented (57.9 fps over the last 5.0 s, interval 1)

Flags and settings

Two Insert menu rows on the Gameplay tab, both in the README's option table; no switch, ini key beyond the row's own, or
build flag.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
Gameplay → Achievement alerts (achievement_alerts= in longshot_options.ini) the pop-up when an achievement unlocks (none) On shows the pop-up; achievements are earned either way all; untested on Linux, Steam Deck, AMD, Intel On: it is the feature's only visible sign in play, and it costs nothing while nothing unlocks
Gameplay → Achievements opens the list (none) a page the list of the 51, unlocked and locked all; untested on Linux, Steam Deck, AMD, Intel —

Testing

Tested:

  • In the game (RTX 3060 Ti, Windows 11, NVIDIA 621.14), this PR @ 44deed6e on main @ d664e342: the test save (the
    stones, the medallions, Zelda's Lullaby, three hearts) loaded with Continue logs achievements: unlocked for exactly
    nine: Kokiri's Emerald, Goron's Ruby, Zora's Sapphire, the five temples and An Audience with the Princess, then
    achievements: 9 of 51 unlocked in every later run, and nothing more in the eleven runs of it. The last of the nine
    proves the first song name, Item_Melody_ZeldaLullaby, in play.
  • main's new Insert menu (this rebase brings it): Gameplay shows Achievement alerts and Achievements between Skip opening
    and Bug report, in the new row style; Enter opens the page, which lists all 51 with their icons, "9 of 51" in the
    banner, and goes back with Esc (screenshots above).
  • python -I -B tests/run_all.py on this branch (Windows 11, llvm-mingw 20261104): 618 passed, 42 failed, 110 skipped;
    clean main @ d664e342 on this PC: 617 passed, 42 failed. The same checks fail on both, none of them this PR's
    (on this PC: the Linux-only checks, the ones needing the Vulkan headers, and others that also fail on clean main),
    with two that each failed once under load and pass alone (test_portable_builder_home here, test_longshot_ctl on
    main). The one more pass is test_oot_achievements, which now also checks all twelve songs, the milk, and all-of and
    any-of on rows of their own.
  • The rebase on main @ d664e342 had two conflicts: main took option id 59 for the transition autosave (the first
    commit's pause, which the second commit takes out again, so vk_api.h still ends as on main) and added the quick
    Debug Tools page beside the Achievements page; both kept.
  • Earlier, on the 82-row list (2026-11-14 and -15, same PC): a new game's first unlock with its pop-up; Achievement
    alerts Off keeps an unlock without one; eight at once show as one pop-up; the page's keys, wheel and clicks; a debug
    tool pauses unlocks for the run; and every item row of the list (all those kept here) unlocked from a save given
    those items.

Not tested:

  • Bottled Up and Fresh from the Farm (the bottle total and the milk): that a held bottle shows among the pouch
    items is unproven. The inventory editor can't give one (the game turns down every Item_Bottle add) and the test save
    has none; the game data's five bottle slots don't say what Link owns (all five IsValid read true on a save with no
    bottle). Both can only fail to unlock, never unlock early.
  • The game-flag rows turning on (riding Epona, Ganon, twenty hearts, ten Big Poes): their flags are there and read 0 on
    this save, and nothing unlocked early; none has been seen turning on.
  • Maestro (all twelve songs): Zelda's Lullaby's name is proven, the other eleven's names are the Inventory page's own,
    not yet seen held.
  • Linux and the Steam Deck (the host code is portable C; the file is moved with rename there).

Must be tested:

  • Linux or a Steam Deck, any GPU (I'm on Windows): build this PR and load a save past the Great Deku Tree (or play to its
    end), expecting the log line achievements: unlocked stone_forest (Kokiri's Emerald), its pop-up, the line
    stone_forest <UTC time> in ~/.local/share/longshot/achievements.txt, and the page listing it as unlocked (Test
    Farm: @Beanstalk linux, asked in this comment,
    waiting for a BigBeans member's 👍; or by hand:
    test request T-MLWS).
  • Windows, the author's own playthrough: a save that holds a bottle and one of milk, expecting the log's inventory probe line to show them among the Item_Bottle* counts, and Fresh from the Farm to unlock (by hand: the author,
    posting the log lines here).

Risks

What could break: little: the tracker runs inside the Inventory page's existing half-second refresh (about 50 µs of
it) and does nothing else, and the menu draws only while a pop-up shows or the page is open. Measured: no frame-rate
cost and no difference in the slow windows (sixteen runs, Measurements). A wrong item or flag name means an achievement
that never unlocks, nothing more. The icon atlas adds one texture (about 6.7 MB) to the menu's.

Turning it off: Achievement alerts Off removes the pop-up; reverting the commits removes everything.

Compatibility: nothing changes for a player's saves, settings or caches: no vk_api.h change, so no shader or
pipeline cache is prepared again, and MKWVK_API_VERSION is unchanged. A new user/achievements.txt appears beside the
saves once something unlocks, and a new achievement_alerts= line in longshot_options.ini.

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.
  • 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.
  • Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported.
  • 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.
  • A file in docs/tested/ for each new measured run (format in docs/tested-configurations.md).
  • 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.
**Type:** feat · **Risk:** low · **Tested on:** Windows 11, RTX 3060 Ti · **Needs:** Linux or a Steam Deck, any GPU ## TL;DR The PC port keeps no record of a player's milestones. This PR adds achievements: 51 of them, following the RetroAchievements list for the N64 game in its order but with our own names, words and icons, with a short pop-up when one is earned and a list in the Insert menu. Sixteen interleaved runs in the Market found no frame-rate cost (main 53.5 fps, this PR 54.3), and loading a save in the game unlocked exactly what it holds. ## Breakdown - **Who it helps:** anyone who wants a record of their progress: the stones, medallions, gear, songs and side quests. - **What was wrong:** nothing marked a milestone beyond the save file itself. - **What changes:** 51 achievements, unlocked once per install and kept in `user/achievements.txt`, a pop-up when one is earned (Gameplay → Achievement alerts) and a list page (Gameplay → Achievements). - **What does not change:** saves, the game's rendering, the shader caches (no `vk_api.h` change); nothing unlocks in a run where a debug tool was used. - **How it was checked:** the game-free checks (`test_oot_achievements` and the menu checks), a save loaded in the game (9 of 51 unlocked, exactly the ones it holds), the menu and page looked at in main's new menu, and sixteen runs against main: no cost. - **What is still open:** a Linux or Steam Deck build and run; a bottle (and milk) seen in a real save. - **Risk:** low: a wrong item or flag name means an achievement that never unlocks, nothing more. ## Why Players have no record of their milestones beyond the save itself: nothing marks getting the Master Sword, defeating Ganon or collecting the Gold Skulltula Tokens. This adds optional achievements, with a pop-up when one is earned and a list in the Insert menu. No issue asks for it (the tracker searched: none on achievements); it was first discussed in #dev-work. ## What changed 51 achievements, each unlocked once and kept in a small file beside the saves. The list is the RetroAchievements base set for the N64 game, one row per achievement of theirs and in their order, as far as the game side can see it happen: 51 of its 97 (the other 46, boss challenges and minigames the game keeps no readable sign of yet, are listed in `docs/achievements.md`). Only the milestones are shared: every title, description and icon is our own. The game side checks them in the Inventory page's existing half-second refresh, with no new game hook, and nothing unlocks in a run where a debug tool was used. - **List**: `gpu/vk/oot_achievements.h`, an X-macro shared by the game side and the menu (id, title, description, the pouch contents it asks for: all of them, or any for the bag tiers; `name>=N` for a count, the Skulltula Tokens), in the RetroAchievements set's order. Item names are the Inventory page's own (`gpu/vk/oot_cheat_items.h`). Start here, then `host/oot_achievements.c`. - **Tracking**: `host/oot_achievements.c` `hos_oot_achievements_check`, called from `host/hos_main.c` `oot_inventory_refresh` with the counts it already reads twice a second. Rows that need more read a game flag by name (`gd:`, through the control bridge's GameData reader `hos_oot_flag_number` in `host/oot_state_tap.c`, under the same lock); `Bottles` adds up the bottle pouch items, `Milk` the milk among them, and `Songs` counts the twelve songs (`OOT_ACHIEVEMENT_SONGS`). Unlocks go to `user/achievements.txt` (`<id> <UTC time>`, written whole through a temporary file; unknown ids kept). - **Debug tools**: a debug action (inventory editor, teleport, age switch, clock) calls `hos_oot_achievements_cheated` in `oot_update_player_cheats`: nothing unlocks for the rest of that run. - **Menu** (`gpu/vk/vk_menu.cpp`): the pop-up `draw_achievement_toast` (with `menu_record` / `menu_record_image`, over everything; more than three at once show as one "N achievements unlocked"); the Gameplay tab's **Achievement alerts** row; the **Achievements** row and page `draw_achievements` (page 6, the Teleport page's layout and keys). - **Icons**: `assets/achievements/*.png`, 102 icons (unlocked and locked), drawn from plain shapes by `scripts/make_achievement_icons.py` (provenance in `assets/achievements/PROVENANCE.txt`, format in its `README.md`). `nx2/achievement_icons.py` packs them into **one atlas** in a generated header, as `nx2/logo_rgba.py` does the logo; `gpu/vk/vk_imgui.cpp` `achievement_icon` loads it as a single texture. - **No change to `vk_api.h` or `vk_replay.cpp`**: `vk_api.h` stamps the shader caches, so this PR makes no player prepare shaders again. The game side tells the menu through `rx_option_set` ids past the Inventory page's. - **Docs**: `docs/achievements.md` (design, the list and the set's rows not tracked yet, open questions, testing); the README's option table. - **Tests**: `tests/test_oot_achievements.py` (new); `test_fps_overlay_order.py`, `test_readme_menu_rows.py` and `test_shader_stamp_cache.py` updated for the pop-up, the new rows and the icons' build step. - **Left for follow-ups on purpose**: players' own icon packs from the `mods` folder (needs a runtime PNG decoder), and the Longshot Launcher's list page (it can read `user/achievements.txt`). **Screenshots** (After: this PR @ 44deed6e on main @ d664e342, main's new Insert menu style; RTX 3060 Ti, 1920x1080, Quality preset Auto, taken from the screen in the Market with the test save. Before: main has none of it.) The Gameplay tab's new rows: ![The Gameplay tab's rows](https://git.magicbean.dev/attachments/ebe39028-236d-4909-82ed-61ca03823ba8) The Achievements page, 9 of 51 unlocked from this save: ![The Achievements page](https://git.magicbean.dev/attachments/471423ce-b52e-4b36-b22f-228a0635e690) The pop-up (unchanged since; this PR @ c996bb31, the first list) is in [the first screenshots' comment](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/392#issuecomment-17722). ## Measurements **Verdict:** no cost found. Sixteen interleaved runs in the Market put this PR at 54.32 fps against main's 53.45 (+0.88, inside the runs' spread of about 3 fps each side), and the PR came out ahead in 6 of the 8 pairs. The last measurement's "slowest window about 2 fps lower" shows again only when each run's single worst 5-second window is taken (51.0 against 48.4); across all 95 windows of each side the slow end is the same: the 5th percentile 45.9 against 46.4, the 10th 47.5 against 47.4, and 19% against 18% of the windows under 50 fps. The new code itself is about 50 µs every half second (timed directly before). Memory is the same within the runs' spread. Passed. Hardware: Windows 11 Home 10.0.26300, NVIDIA GeForce RTX 3060 Ti 8 GB (driver 621.14), Intel Core i7-12700F (12 cores, 20 threads), 64 GB RAM Scene: the Market (child), standing still with no input; borderless 1920x1080 on a second monitor, Quality preset Auto (this PC: no upscaler), no frame generation, Game frame rate cap Uncapped, V-Sync Off, volume 0 (the sound still mixed). Method: built with `scripts/dev_packs.py`: a base of main @ d664e342, this PR as a pack on it (its `longshot.exe` and `longshot_vk.dll`), and a runtime of each, so both arms share every other file and the same shader caches. Every run started from a copy of one pinned options file (`HOS_OPTIONS_FILE`) and the same save, through the control bridge (`HOS_CONTROL`, `scripts/longshot_ctl.py`): A through the title until in play, 30 s, then 60 s of the game's own 5-second fps lines, and the process's private memory at the end. One warm-up run of each first (not counted), then eight pairs, the order alternating (main first in the odd pairs, the PR first in the even ones). A key press that reached the game opened its menu in one main run; that run was dropped and run again, and the runs since give the focus back to the window that had it. The number is the median of a run's 5-second windows; the table gives the median of the eight. How to reproduce: a save in the Market, the settings above, then per build: start with `HOS_CONTROL` and `HOS_OPTIONS_FILE` set, `longshot_ctl.py press A` until `status` says play, 30 s, then read the `vi: ... fps over the last 5.0 s` lines of `logs/longshot_log.txt` for 60 s. | | Before: main @ d664e342 | After: this PR @ 44deed6e | |---|---|---| | fps, median of each run, pairs 1 to 8 | 53.8 / 49.2 / 56.2 / 53.0 / 55.5 / 48.2 / 52.0 / 57.2 | 51.2 / 52.0 / 51.0 / 53.8 / 56.5 / 56.7 / 54.8 / 57.5 | | fps, median of the eight runs | 53.45 | 54.32 (+0.88, +1.6%) | | the PR ahead | | in 6 of 8 pairs | | 5 s windows, 5th / 10th percentile (all 95) | 45.9 / 47.5 | 46.4 / 47.4 | | 5 s windows under 50 fps | 19% | 18% | | lowest 5 s window of each run, median | 51.0 | 48.4 | | frame time from the median fps | 18.71 ms | 18.41 ms | | private memory at the end, median (runs vary by ±250 MB) | 16669 MB | 16383 MB | **The new code, timed directly** (2026-11-15, a temporary timer around it, one run in the Market, never committed): the bottle reads average 28 µs and the achievements check, the game-flag lookups included, 21 µs per refresh, against 320 µs for the Inventory page's item reads that were already there; at two refreshes a second that is about 0.01% of the time. This list adds no new kind of read: the songs are counted from the counts the page already has, and the milk from the bottle reads. The icons are one 102-icon atlas (about 6.7 MB), drawn only while the page or a pop-up shows. Earlier measurements: main @ 0caf0618 against this PR's first 29 rows, 56.2 against 56.5 fps (four runs, 2026-11-14); main @ 5274fb72 against the 82-row list, 56.25 against 55.28 (twelve runs, 2026-11-15). Runs from 23:30 on 2026-11-17 to 00:12 local (this PR @ 44deed6e; the docs/tested commit on top, a8e21dc3, adds docs only); their files: `docs/tested/2026-11-17-achievements-zapiltar-run01.md` to `2026-11-18-achievements-zapiltar-run16.md`. <details><summary>The log lines (each measured run's 60 s)</summary> ``` main @ d664e342, main-1 vi: 7280 frames presented (53.2 fps over the last 5.0 s, interval 1) vi: 7546 frames presented (53.0 fps over the last 5.0 s, interval 1) vi: 7817 frames presented (54.2 fps over the last 5.0 s, interval 1) vi: 8089 frames presented (54.4 fps over the last 5.0 s, interval 1) vi: 8350 frames presented (52.0 fps over the last 5.0 s, interval 1) vi: 8620 frames presented (53.9 fps over the last 5.0 s, interval 1) vi: 8892 frames presented (54.3 fps over the last 5.0 s, interval 1) vi: 9159 frames presented (53.3 fps over the last 5.0 s, interval 1) vi: 9422 frames presented (52.5 fps over the last 5.0 s, interval 1) vi: 9693 frames presented (54.1 fps over the last 5.0 s, interval 1) vi: 9964 frames presented (54.2 fps over the last 5.0 s, interval 1) vi: 10233 frames presented (53.8 fps over the last 5.0 s, interval 1) this PR @ 44deed6e, pr-1 vi: 6383 frames presented (49.5 fps over the last 5.0 s, interval 1) vi: 6619 frames presented (47.0 fps over the last 5.0 s, interval 1) vi: 6856 frames presented (47.4 fps over the last 5.0 s, interval 1) vi: 7120 frames presented (52.8 fps over the last 5.0 s, interval 1) vi: 7381 frames presented (52.2 fps over the last 5.0 s, interval 1) vi: 7642 frames presented (52.1 fps over the last 5.0 s, interval 1) vi: 7899 frames presented (51.2 fps over the last 5.0 s, interval 1) vi: 8134 frames presented (46.9 fps over the last 5.0 s, interval 1) vi: 8390 frames presented (51.1 fps over the last 5.0 s, interval 1) vi: 8662 frames presented (54.2 fps over the last 5.0 s, interval 1) vi: 8909 frames presented (49.3 fps over the last 5.0 s, interval 1) vi: 9167 frames presented (51.4 fps over the last 5.0 s, interval 1) this PR @ 44deed6e, pr-2 vi: 6762 frames presented (47.3 fps over the last 5.0 s, interval 1) vi: 7022 frames presented (51.8 fps over the last 5.0 s, interval 1) vi: 7255 frames presented (46.4 fps over the last 5.0 s, interval 1) vi: 7486 frames presented (46.1 fps over the last 5.0 s, interval 1) vi: 7747 frames presented (52.2 fps over the last 5.0 s, interval 1) vi: 7994 frames presented (49.3 fps over the last 5.0 s, interval 1) vi: 8255 frames presented (52.2 fps over the last 5.0 s, interval 1) vi: 8515 frames presented (51.9 fps over the last 5.0 s, interval 1) vi: 8775 frames presented (52.0 fps over the last 5.0 s, interval 1) vi: 9038 frames presented (52.5 fps over the last 5.0 s, interval 1) vi: 9301 frames presented (52.4 fps over the last 5.0 s, interval 1) vi: 9564 frames presented (52.6 fps over the last 5.0 s, interval 1) main @ d664e342, main-2 vi: 6742 frames presented (51.3 fps over the last 5.0 s, interval 1) vi: 7007 frames presented (52.8 fps over the last 5.0 s, interval 1) vi: 7254 frames presented (49.2 fps over the last 5.0 s, interval 1) vi: 7509 frames presented (50.9 fps over the last 5.0 s, interval 1) vi: 7741 frames presented (46.4 fps over the last 5.0 s, interval 1) vi: 7983 frames presented (48.4 fps over the last 5.0 s, interval 1) vi: 8237 frames presented (50.7 fps over the last 5.0 s, interval 1) vi: 8474 frames presented (47.2 fps over the last 5.0 s, interval 1) vi: 8712 frames presented (47.5 fps over the last 5.0 s, interval 1) vi: 8943 frames presented (46.1 fps over the last 5.0 s, interval 1) vi: 9208 frames presented (52.8 fps over the last 5.0 s, interval 1) main @ d664e342, main-3 vi: 6763 frames presented (55.0 fps over the last 5.0 s, interval 1) vi: 7034 frames presented (54.0 fps over the last 5.0 s, interval 1) vi: 7307 frames presented (54.4 fps over the last 5.0 s, interval 1) vi: 7573 frames presented (53.1 fps over the last 5.0 s, interval 1) vi: 7856 frames presented (56.5 fps over the last 5.0 s, interval 1) vi: 8139 frames presented (56.5 fps over the last 5.0 s, interval 1) vi: 8421 frames presented (56.4 fps over the last 5.0 s, interval 1) vi: 8692 frames presented (54.2 fps over the last 5.0 s, interval 1) vi: 8974 frames presented (56.3 fps over the last 5.0 s, interval 1) vi: 9257 frames presented (56.5 fps over the last 5.0 s, interval 1) vi: 9539 frames presented (56.2 fps over the last 5.0 s, interval 1) vi: 9823 frames presented (56.8 fps over the last 5.0 s, interval 1) this PR @ 44deed6e, pr-3 vi: 7670 frames presented (55.8 fps over the last 5.0 s, interval 1) vi: 7926 frames presented (51.0 fps over the last 5.0 s, interval 1) vi: 8133 frames presented (41.3 fps over the last 5.0 s, interval 1) vi: 8365 frames presented (46.3 fps over the last 5.0 s, interval 1) vi: 8620 frames presented (50.9 fps over the last 5.0 s, interval 1) vi: 8877 frames presented (51.3 fps over the last 5.0 s, interval 1) vi: 9106 frames presented (45.8 fps over the last 5.0 s, interval 1) vi: 9344 frames presented (47.6 fps over the last 5.0 s, interval 1) vi: 9609 frames presented (52.9 fps over the last 5.0 s, interval 1) vi: 9869 frames presented (51.8 fps over the last 5.0 s, interval 1) vi: 10139 frames presented (53.9 fps over the last 5.0 s, interval 1) this PR @ 44deed6e, pr-4 vi: 6865 frames presented (47.1 fps over the last 5.0 s, interval 1) vi: 7136 frames presented (54.1 fps over the last 5.0 s, interval 1) vi: 7380 frames presented (48.7 fps over the last 5.0 s, interval 1) vi: 7622 frames presented (48.4 fps over the last 5.0 s, interval 1) vi: 7890 frames presented (53.5 fps over the last 5.0 s, interval 1) vi: 8164 frames presented (54.7 fps over the last 5.0 s, interval 1) vi: 8421 frames presented (51.4 fps over the last 5.0 s, interval 1) vi: 8679 frames presented (51.6 fps over the last 5.0 s, interval 1) vi: 8955 frames presented (55.1 fps over the last 5.0 s, interval 1) vi: 9236 frames presented (56.1 fps over the last 5.0 s, interval 1) vi: 9516 frames presented (56.0 fps over the last 5.0 s, interval 1) vi: 9799 frames presented (56.5 fps over the last 5.0 s, interval 1) main @ d664e342, main-4 vi: 8294 frames presented (54.9 fps over the last 5.0 s, interval 1) vi: 8573 frames presented (55.7 fps over the last 5.0 s, interval 1) vi: 8839 frames presented (53.1 fps over the last 5.0 s, interval 1) vi: 9090 frames presented (50.1 fps over the last 5.0 s, interval 1) vi: 9355 frames presented (53.0 fps over the last 5.0 s, interval 1) vi: 9619 frames presented (52.8 fps over the last 5.0 s, interval 1) vi: 9876 frames presented (51.2 fps over the last 5.0 s, interval 1) vi: 10144 frames presented (53.4 fps over the last 5.0 s, interval 1) vi: 10408 frames presented (52.7 fps over the last 5.0 s, interval 1) vi: 10666 frames presented (51.5 fps over the last 5.0 s, interval 1) vi: 10934 frames presented (53.4 fps over the last 5.0 s, interval 1) vi: 11202 frames presented (53.4 fps over the last 5.0 s, interval 1) main @ d664e342, main-5 vi: 7790 frames presented (54.8 fps over the last 5.0 s, interval 1) vi: 8067 frames presented (55.4 fps over the last 5.0 s, interval 1) vi: 8342 frames presented (54.9 fps over the last 5.0 s, interval 1) vi: 8617 frames presented (54.8 fps over the last 5.0 s, interval 1) vi: 8895 frames presented (55.5 fps over the last 5.0 s, interval 1) vi: 9173 frames presented (55.6 fps over the last 5.0 s, interval 1) vi: 9450 frames presented (55.3 fps over the last 5.0 s, interval 1) vi: 9728 frames presented (55.5 fps over the last 5.0 s, interval 1) vi: 10008 frames presented (55.8 fps over the last 5.0 s, interval 1) vi: 10289 frames presented (56.0 fps over the last 5.0 s, interval 1) vi: 10570 frames presented (56.2 fps over the last 5.0 s, interval 1) vi: 10851 frames presented (56.1 fps over the last 5.0 s, interval 1) this PR @ 44deed6e, pr-5 vi: 6681 frames presented (56.6 fps over the last 5.0 s, interval 1) vi: 6964 frames presented (56.5 fps over the last 5.0 s, interval 1) vi: 7248 frames presented (56.6 fps over the last 5.0 s, interval 1) vi: 7534 frames presented (57.1 fps over the last 5.0 s, interval 1) vi: 7809 frames presented (55.0 fps over the last 5.0 s, interval 1) vi: 8096 frames presented (57.4 fps over the last 5.0 s, interval 1) vi: 8381 frames presented (56.9 fps over the last 5.0 s, interval 1) vi: 8667 frames presented (57.1 fps over the last 5.0 s, interval 1) vi: 8922 frames presented (50.8 fps over the last 5.0 s, interval 1) vi: 9175 frames presented (50.5 fps over the last 5.0 s, interval 1) vi: 9456 frames presented (56.0 fps over the last 5.0 s, interval 1) vi: 9705 frames presented (49.7 fps over the last 5.0 s, interval 1) this PR @ 44deed6e, pr-6 vi: 6527 frames presented (56.6 fps over the last 5.0 s, interval 1) vi: 6810 frames presented (56.4 fps over the last 5.0 s, interval 1) vi: 7094 frames presented (56.7 fps over the last 5.0 s, interval 1) vi: 7376 frames presented (56.3 fps over the last 5.0 s, interval 1) vi: 7662 frames presented (57.2 fps over the last 5.0 s, interval 1) vi: 7942 frames presented (55.9 fps over the last 5.0 s, interval 1) vi: 8226 frames presented (56.7 fps over the last 5.0 s, interval 1) vi: 8508 frames presented (56.4 fps over the last 5.0 s, interval 1) vi: 8790 frames presented (56.3 fps over the last 5.0 s, interval 1) vi: 9076 frames presented (57.0 fps over the last 5.0 s, interval 1) vi: 9362 frames presented (57.1 fps over the last 5.0 s, interval 1) vi: 9648 frames presented (57.1 fps over the last 5.0 s, interval 1) main @ d664e342, main-6 vi: 6610 frames presented (48.6 fps over the last 5.0 s, interval 1) vi: 6856 frames presented (49.1 fps over the last 5.0 s, interval 1) vi: 7079 frames presented (44.5 fps over the last 5.0 s, interval 1) vi: 7340 frames presented (52.1 fps over the last 5.0 s, interval 1) vi: 7604 frames presented (52.7 fps over the last 5.0 s, interval 1) vi: 7829 frames presented (44.9 fps over the last 5.0 s, interval 1) vi: 8090 frames presented (52.0 fps over the last 5.0 s, interval 1) vi: 8306 frames presented (43.2 fps over the last 5.0 s, interval 1) vi: 8541 frames presented (46.8 fps over the last 5.0 s, interval 1) vi: 8771 frames presented (45.9 fps over the last 5.0 s, interval 1) vi: 9010 frames presented (47.8 fps over the last 5.0 s, interval 1) vi: 9260 frames presented (49.9 fps over the last 5.0 s, interval 1) main @ d664e342, main-7 vi: 6751 frames presented (52.5 fps over the last 5.0 s, interval 1) vi: 6974 frames presented (44.5 fps over the last 5.0 s, interval 1) vi: 7229 frames presented (50.8 fps over the last 5.0 s, interval 1) vi: 7473 frames presented (48.7 fps over the last 5.0 s, interval 1) vi: 7728 frames presented (50.9 fps over the last 5.0 s, interval 1) vi: 7989 frames presented (52.1 fps over the last 5.0 s, interval 1) vi: 8254 frames presented (52.9 fps over the last 5.0 s, interval 1) vi: 8514 frames presented (51.9 fps over the last 5.0 s, interval 1) vi: 8778 frames presented (52.8 fps over the last 5.0 s, interval 1) vi: 9027 frames presented (49.7 fps over the last 5.0 s, interval 1) vi: 9289 frames presented (52.3 fps over the last 5.0 s, interval 1) vi: 9554 frames presented (52.9 fps over the last 5.0 s, interval 1) this PR @ 44deed6e, pr-7 vi: 6149 frames presented (54.8 fps over the last 5.0 s, interval 1) vi: 6420 frames presented (54.1 fps over the last 5.0 s, interval 1) vi: 6694 frames presented (54.8 fps over the last 5.0 s, interval 1) vi: 6970 frames presented (55.1 fps over the last 5.0 s, interval 1) vi: 7249 frames presented (55.6 fps over the last 5.0 s, interval 1) vi: 7523 frames presented (54.7 fps over the last 5.0 s, interval 1) vi: 7798 frames presented (54.9 fps over the last 5.0 s, interval 1) vi: 8067 frames presented (53.7 fps over the last 5.0 s, interval 1) vi: 8344 frames presented (55.2 fps over the last 5.0 s, interval 1) vi: 8621 frames presented (55.2 fps over the last 5.0 s, interval 1) vi: 8897 frames presented (55.0 fps over the last 5.0 s, interval 1) vi: 9165 frames presented (53.5 fps over the last 5.0 s, interval 1) this PR @ 44deed6e, pr-8 vi: 5977 frames presented (52.5 fps over the last 5.0 s, interval 1) vi: 6250 frames presented (54.4 fps over the last 5.0 s, interval 1) vi: 6539 frames presented (57.7 fps over the last 5.0 s, interval 1) vi: 6827 frames presented (57.6 fps over the last 5.0 s, interval 1) vi: 7116 frames presented (57.7 fps over the last 5.0 s, interval 1) vi: 7398 frames presented (56.2 fps over the last 5.0 s, interval 1) vi: 7683 frames presented (56.9 fps over the last 5.0 s, interval 1) vi: 7970 frames presented (57.3 fps over the last 5.0 s, interval 1) vi: 8260 frames presented (57.9 fps over the last 5.0 s, interval 1) vi: 8551 frames presented (58.0 fps over the last 5.0 s, interval 1) vi: 8832 frames presented (56.1 fps over the last 5.0 s, interval 1) vi: 9121 frames presented (57.6 fps over the last 5.0 s, interval 1) main @ d664e342, main-8 vi: 6071 frames presented (56.8 fps over the last 5.0 s, interval 1) vi: 6358 frames presented (57.3 fps over the last 5.0 s, interval 1) vi: 6647 frames presented (57.7 fps over the last 5.0 s, interval 1) vi: 6931 frames presented (56.8 fps over the last 5.0 s, interval 1) vi: 7216 frames presented (56.8 fps over the last 5.0 s, interval 1) vi: 7502 frames presented (57.1 fps over the last 5.0 s, interval 1) vi: 7787 frames presented (57.0 fps over the last 5.0 s, interval 1) vi: 8072 frames presented (56.9 fps over the last 5.0 s, interval 1) vi: 8362 frames presented (57.8 fps over the last 5.0 s, interval 1) vi: 8652 frames presented (57.8 fps over the last 5.0 s, interval 1) vi: 8939 frames presented (57.4 fps over the last 5.0 s, interval 1) vi: 9229 frames presented (57.9 fps over the last 5.0 s, interval 1) ``` </details> ### Flags and settings Two Insert menu rows on the Gameplay tab, both in the README's option table; no switch, ini key beyond the row's own, or build flag. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | Gameplay → Achievement alerts (`achievement_alerts=` in longshot_options.ini) | the pop-up when an achievement unlocks | (none) | On | shows the pop-up; achievements are earned either way | all; untested on Linux, Steam Deck, AMD, Intel | On: it is the feature's only visible sign in play, and it costs nothing while nothing unlocks | | Gameplay → Achievements | opens the list | (none) | a page | the list of the 51, unlocked and locked | all; untested on Linux, Steam Deck, AMD, Intel | — | ## Testing **Tested:** - In the game (RTX 3060 Ti, Windows 11, NVIDIA 621.14), this PR @ 44deed6e on main @ d664e342: the test save (the stones, the medallions, Zelda's Lullaby, three hearts) loaded with Continue logs `achievements: unlocked` for exactly nine: Kokiri's Emerald, Goron's Ruby, Zora's Sapphire, the five temples and An Audience with the Princess, then `achievements: 9 of 51 unlocked` in every later run, and nothing more in the eleven runs of it. The last of the nine proves the first song name, `Item_Melody_ZeldaLullaby`, in play. - main's new Insert menu (this rebase brings it): Gameplay shows Achievement alerts and Achievements between Skip opening and Bug report, in the new row style; Enter opens the page, which lists all 51 with their icons, "9 of 51" in the banner, and goes back with Esc (screenshots above). - `python -I -B tests/run_all.py` on this branch (Windows 11, llvm-mingw 20261104): 618 passed, 42 failed, 110 skipped; clean `main` @ d664e342 on this PC: 617 passed, 42 failed. The same checks fail on both, none of them this PR's (on this PC: the Linux-only checks, the ones needing the Vulkan headers, and others that also fail on clean main), with two that each failed once under load and pass alone (`test_portable_builder_home` here, `test_longshot_ctl` on main). The one more pass is `test_oot_achievements`, which now also checks all twelve songs, the milk, and all-of and any-of on rows of their own. - The rebase on main @ d664e342 had two conflicts: main took option id 59 for the transition autosave (the first commit's pause, which the second commit takes out again, so `vk_api.h` still ends as on main) and added the quick Debug Tools page beside the Achievements page; both kept. - Earlier, on the 82-row list (2026-11-14 and -15, same PC): a new game's first unlock with its pop-up; Achievement alerts Off keeps an unlock without one; eight at once show as one pop-up; the page's keys, wheel and clicks; a debug tool pauses unlocks for the run; and every item row of the list (all those kept here) unlocked from a save given those items. **Not tested:** - **Bottled Up and Fresh from the Farm** (the bottle total and the milk): that a held bottle shows among the pouch items is unproven. The inventory editor can't give one (the game turns down every `Item_Bottle` add) and the test save has none; the game data's five bottle slots don't say what Link owns (all five `IsValid` read true on a save with no bottle). Both can only fail to unlock, never unlock early. - The game-flag rows turning on (riding Epona, Ganon, twenty hearts, ten Big Poes): their flags are there and read 0 on this save, and nothing unlocked early; none has been seen turning on. - Maestro (all twelve songs): Zelda's Lullaby's name is proven, the other eleven's names are the Inventory page's own, not yet seen held. - Linux and the Steam Deck (the host code is portable C; the file is moved with `rename` there). **Must be tested:** - Linux or a Steam Deck, any GPU (I'm on Windows): build this PR and load a save past the Great Deku Tree (or play to its end), expecting the log line `achievements: unlocked stone_forest (Kokiri's Emerald)`, its pop-up, the line `stone_forest <UTC time>` in `~/.local/share/longshot/achievements.txt`, and the page listing it as unlocked (Test Farm: @Beanstalk linux, asked in [this comment](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/392#issuecomment-47983), waiting for a BigBeans member's 👍; or by hand: test request T-MLWS). - Windows, the author's own playthrough: a save that holds a bottle and one of milk, expecting the log's `inventory probe` line to show them among the `Item_Bottle*` counts, and Fresh from the Farm to unlock (by hand: the author, posting the log lines here). ## Risks **What could break:** little: the tracker runs inside the Inventory page's existing half-second refresh (about 50 µs of it) and does nothing else, and the menu draws only while a pop-up shows or the page is open. Measured: no frame-rate cost and no difference in the slow windows (sixteen runs, Measurements). A wrong item or flag name means an achievement that never unlocks, nothing more. The icon atlas adds one texture (about 6.7 MB) to the menu's. **Turning it off:** Achievement alerts Off removes the pop-up; reverting the commits removes everything. **Compatibility:** nothing changes for a player's saves, settings or caches: no `vk_api.h` change, so no shader or pipeline cache is prepared again, and `MKWVK_API_VERSION` is unchanged. A new `user/achievements.txt` appears beside the saves once something unlocks, and a new `achievement_alerts=` line in `longshot_options.ini`. ## 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`. - [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] Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported. - [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] A file in `docs/tested/` for each new measured run (format in `docs/tested-configurations.md`). - [x] 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. <!-- Windows built and run; Linux not yet: under Must be tested (the Test Farm or T-MLWS) --> - [x] Docs updated.
29 achievements from the inventory the game side already reads twice a
second (the sword and shield, both ocarinas, the three stones, the twelve
songs, the five temples' medallions, the bag upgrades). No new game hooks
or guest reads.

- gpu/vk/oot_achievements.h: the shared list (X-macro), ids for the file
- host/oot_achievements.c: unlocks, user/achievements.txt written whole
  (temp file + move), unknown ids kept; paused in a run where the Debug
  tools have been on (HOS_OPT_ACHIEVEMENTS_PAUSED, 58)
- host/hos_main.c: oot_inventory_refresh hands its counts over
- gpu/vk/vk_menu.cpp: the pop-up (queued; more than three at once show
  as one) and the Gameplay tab's Achievement alerts row, on by default
- tests: test_oot_achievements.py; test_fps_overlay_order.py covers the
  pop-up; README lists the row; docs/achievements.md has the design

Hero of Time (defeating Ganon) is WIP: no signal for it is known yet.
Not yet run in the game.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
- Insert menu: the Gameplay tab's Achievements row opens a list page (page 6,
  draw_achievements, the Teleport page's layout and keys); the pop-up and the
  page share achievement_medal
- 58 icons (unlocked and locked), drawn from plain shapes by
  scripts/make_achievement_icons.py (assets/achievements, PROVENANCE.txt,
  README.md); nx2/achievement_icons.py packs them into one atlas texture in a
  generated header, as nx2/logo_rgba.py does the logo; vk_imgui.cpp loads it.
  One texture: 58 of their own ran out the overlays' small texture pool, and
  one texture it cannot make holds back every overlay (the menu was blank)
- The pause: the game side stops unlocking once a debug action runs (the
  inventory editor, teleport, the age switch, the clock) and tells the menu,
  instead of asking the menu whether the tools are on. vk_api.h and
  vk_replay.cpp are back to main's: vk_api.h stamps the shader caches
- Tests: the page, the icons and their atlas, the pause; README rows

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs(achievements): the page, the icons and the pause tested in the game
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 3s
Website / Website on Cloudflare (pull_request_target) Has been skipped
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
c996bb3101
Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs(tested): main against the achievements in the Market, RTX 3060 Ti, Windows 11, four interleaved runs
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 3s
Website / Website on Cloudflare (pull_request_target) Has been skipped
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
25340233c8
Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Author
First-time contributor

Screenshots, this PR @ c996bb31 (RTX 3060 Ti, Windows 11, 1920x1080, Quality preset Auto), taken from the screen while the game ran.

The pop-up, as a save that holds the Kokiri Sword and Deku Shield loads (cropped; the whole screen below):

The pop-up

The Achievements page (Insert → Gameplay → Achievements): 9 of 29 unlocked, the locked ones dimmed with their padlock icons:

The Achievements page

The Gameplay tab's new rows, Achievement alerts and Achievements:

The rows

The pop-up on the whole screen (the FPS counter at Breakdown; it shows the load's first seconds, while shaders were still being built):

The pop-up, whole screen

Screenshots, this PR @ c996bb31 (RTX 3060 Ti, Windows 11, 1920x1080, Quality preset Auto), taken from the screen while the game ran. **The pop-up**, as a save that holds the Kokiri Sword and Deku Shield loads (cropped; the whole screen below): ![The pop-up](https://git.magicbean.dev/attachments/574b1378-b82c-4bfd-ba0d-1bcbfff89656) **The Achievements page** (Insert → Gameplay → Achievements): 9 of 29 unlocked, the locked ones dimmed with their padlock icons: ![The Achievements page](https://git.magicbean.dev/attachments/13ad2055-4700-4801-ba89-1fef1a8b464c) **The Gameplay tab's new rows**, Achievement alerts and Achievements: ![The rows](https://git.magicbean.dev/attachments/937263d8-01d5-4b7f-bea8-81b9771c3c2c) The pop-up on the whole screen (the FPS counter at Breakdown; it shows the load's first seconds, while shaders were still being built): ![The pop-up, whole screen](https://git.magicbean.dev/attachments/45cc786c-a58c-4a23-8440-dadd49147cfb)
Author
First-time contributor

Measured (main @ 0caf0618 against this PR @ 25340233, RTX 3060 Ti, Windows 11, the Market, Quality Auto, uncapped, four interleaved runs after a warm-up of each): main 56.2 fps, this PR 56.5 fps, within the runs' spread, so the tracking costs nothing measurable. The numbers, method and log lines are in Measurements, the four runs in docs/tested (25340233), and the screenshots in the description and the comment above. Still open: the Linux build box (Windows only so far) and the song names, which need a song learned in play.

Measured (main @ 0caf0618 against this PR @ 25340233, RTX 3060 Ti, Windows 11, the Market, Quality Auto, uncapped, four interleaved runs after a warm-up of each): main 56.2 fps, this PR 56.5 fps, within the runs' spread, so the tracking costs nothing measurable. The numbers, method and log lines are in Measurements, the four runs in docs/tested (25340233), and the screenshots in the description and the comment above. Still open: the Linux build box (Windows only so far) and the song names, which need a song learned in play.
Author
First-time contributor

Asked for a Linux tester: T-MLWS (Linux or a Steam Deck: build it, earn one achievement, check the pop-up, the log line and the unlock file). It needs the testing wanted label before it can be claimed. The song names stay under Not tested: I will check them when my playthrough reaches Zelda's Lullaby and post the log line here.

Asked for a Linux tester: T-MLWS (Linux or a Steam Deck: build it, earn one achievement, check the pop-up, the log line and the unlock file). It needs the testing wanted label before it can be claimed. The song names stay under Not tested: I will check them when my playthrough reaches Zelda's Lullaby and post the log line here.
feat(game): 53 more achievements: items, tokens, bosses, hearts, Big Poes, Epona, bottles
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 18s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
e25520b4db
Item rows for the swords, shields, tunics, boots, tools, strength and scale upgrades,
magic, arrows, wallets and masks, and Gold Skulltula Token milestones ("name>=N").
A "gd:" condition reads a game flag by name (host/oot_state_tap.c hos_oot_flag_number):
a defeat counter for each boss and Ganon (Hero of Time), PlayerStatus.MaxLife for 10
and 20 hearts, the Big Poe counter, and the Epona flags. "Bottles" adds up the bottle
pouch items for Bottled Up (unproven: no save with a bottle yet). 164 icons.

Tested in the game: the 38 item rows unlock from a loaded save, nothing unlocks early.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Author
First-time contributor

e25520b4 adds 53 achievements (82 in all, 164 icons). There are 38 item rows (swords, shields, tunics, boots, tools, upgrades, magic, arrows, wallets, Mask of Truth, Bombchus, a Magic Bean) and Gold Skulltula Token milestones from 10 to 100. Also new: one per boss and Hero of Time (Ganon), 10 and 20 hearts, ten Big Poes, riding Epona, and all five bottles.

  • A row can now ask for a count (name>=N), or a game flag by name (gd:), read with the control bridge's GameData reader under the same lock and in the same refresh. There is no new hook.
  • Tested in the game on an RTX 3060 Ti with Windows 11. All 38 item rows unlocked from a loaded save, the token thresholds included, and nothing unlocked early. The flags the new rows use are all present and read as expected.
  • Bottled Up is unproven: the game won't take a bottle from the inventory editor, and the test save has none. It can't unlock early, only fail to unlock. See Testing.
  • Two boxes are unticked again. Rebased: main is 52 commits ahead. Measured: these rows and the bigger atlas aren't measured yet. Both will be done together, after a rebase.
e25520b4 adds 53 achievements (82 in all, 164 icons). There are 38 item rows (swords, shields, tunics, boots, tools, upgrades, magic, arrows, wallets, Mask of Truth, Bombchus, a Magic Bean) and Gold Skulltula Token milestones from 10 to 100. Also new: one per boss and Hero of Time (Ganon), 10 and 20 hearts, ten Big Poes, riding Epona, and all five bottles. - A row can now ask for a count (`name>=N`), or a game flag by name (`gd:`), read with the control bridge's GameData reader under the same lock and in the same refresh. There is no new hook. - Tested in the game on an RTX 3060 Ti with Windows 11. All 38 item rows unlocked from a loaded save, the token thresholds included, and nothing unlocked early. The flags the new rows use are all present and read as expected. - Bottled Up is unproven: the game won't take a bottle from the inventory editor, and the test save has none. It can't unlock early, only fail to unlock. See Testing. - Two boxes are unticked again. Rebased: `main` is 52 commits ahead. Measured: these rows and the bigger atlas aren't measured yet. Both will be done together, after a rebase.
Zapiltar force-pushed feat/achievements from e25520b4db
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 18s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
to 38f22e5ad2
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 4s
Website / Website on Cloudflare (pull_request_target) Has been skipped
beanstalk/approval waiting for a BigBean's 👍 on the request
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
2026-11-15 07:57:04 +00:00
Compare
Author
First-time contributor

Rebased on main @ 5274fb72 (force-pushed, now 38f22e5a), and measured again.

  • Rebase: one real conflict. main took option id 58 for HOS_OPT_RENDER_THREAD, the id this branch's first commit used for the pause. The later commit removes that id again, so vk_api.h ends exactly as on main and the shader caches don't change. The checks give 503 passed and 17 failed; clean main gives 502 and the same 17 failed. The extra pass is test_oot_achievements.
  • Measured (twelve runs in the Market on an RTX 3060 Ti, three pairs with main first and three with the PR first): main 56.25 fps, this PR 55.28. That's −1.0 fps (−1.7%), inside the runs' spread, and the PR came out ahead in two of the six pairs. Its slowest 5-second windows were about 2 fps lower, with the same overlap. Memory is the same within run-to-run variation.
  • The new code, timed directly (a temporary timer, not committed): about 50 µs every half second, against 320 µs for the item reads that were already there. That is too little to explain the gap, so it is reported as measured. The files are docs/tested/2026-11-15-achievements-zapiltar-run01.md to run12.md.

The PR stays WIP until the Linux run (T-MLWS).

Rebased on `main` @ 5274fb72 (force-pushed, now 38f22e5a), and measured again. - **Rebase:** one real conflict. `main` took option id 58 for `HOS_OPT_RENDER_THREAD`, the id this branch's first commit used for the pause. The later commit removes that id again, so `vk_api.h` ends exactly as on `main` and the shader caches don't change. The checks give 503 passed and 17 failed; clean `main` gives 502 and the same 17 failed. The extra pass is `test_oot_achievements`. - **Measured** (twelve runs in the Market on an RTX 3060 Ti, three pairs with `main` first and three with the PR first): `main` 56.25 fps, this PR 55.28. That's −1.0 fps (−1.7%), inside the runs' spread, and the PR came out ahead in two of the six pairs. Its slowest 5-second windows were about 2 fps lower, with the same overlap. Memory is the same within run-to-run variation. - **The new code, timed directly** (a temporary timer, not committed): about 50 µs every half second, against 320 µs for the item reads that were already there. That is too little to explain the gap, so it is reported as measured. The files are `docs/tested/2026-11-15-achievements-zapiltar-run01.md` to `run12.md`. The PR stays WIP until the Linux run (T-MLWS).
Author
First-time contributor

Description moved to main's new pull request template (the rebase brought it): a status line, a Verdict for the measurement with Before/After columns, a Must be tested part (the Linux run, T-MLWS; a bottle and a song from my own playthrough), a Risks section and the Everyone checklist. It also fixes characters an earlier update had garbled (µ, ±, →). The content is unchanged.

Description moved to main's new pull request template (the rebase brought it): a status line, a Verdict for the measurement with Before/After columns, a Must be tested part (the Linux run, T-MLWS; a bottle and a song from my own playthrough), a Risks section and the Everyone checklist. It also fixes characters an earlier update had garbled (µ, ±, →). The content is unchanged.
Author
First-time contributor

@Beanstalk linux, build this PR and play: start a new file and get the Kokiri Sword and Deku Shield (or load a save that has them). Expect the 'Ready for Adventure' pop-up, the log line achievements: unlocked sword_and_shield, and a sword_and_shield <UTC time> line in ~/.local/share/longshot/achievements.txt; then Insert > Gameplay > Achievements lists it as unlocked.

@Beanstalk linux, build this PR and play: start a new file and get the Kokiri Sword and Deku Shield (or load a save that has them). Expect the 'Ready for Adventure' pop-up, the log line `achievements: unlocked sword_and_shield`, and a `sword_and_shield <UTC time>` line in `~/.local/share/longshot/achievements.txt`; then Insert > Gameplay > Achievements lists it as unlocked.
Member

@Zapiltar only members of BigBeans can start the farm.

One of them can approve this request by reacting 👍 to it. This request was for 38f22e5, and the PR has changed since (734b29b), so a 👍 no longer approves it. Comment @Beanstalk again to ask for the new commit.

@Zapiltar only members of `BigBeans` can start the farm. ~~One of them can approve this request by reacting 👍 to it.~~ This request was for `38f22e5`, and the PR has changed since (`734b29b`), so a 👍 no longer approves it. Comment `@Beanstalk` again to ask for the new commit.
HumanBean force-pushed feat/achievements from 38f22e5ad2
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 4s
Website / Website on Cloudflare (pull_request_target) Has been skipped
beanstalk/approval waiting for a BigBean's 👍 on the request
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
to 734b29bc4a
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 5s
CI / Workflow lint (actionlint) (pull_request) Successful in 5s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 4s
Third-party parts / As their notes say (pull_request) Successful in 8s
Website / Website on Cloudflare (pull_request_target) Has been skipped
beanstalk/approval changed since the request: ask again
PR description / Description follows the template (pull_request_target) Successful in 4s
2026-11-15 18:42:18 +00:00
Compare
Zapiltar changed title from WIP: feat(game): achievements with unlock pop-ups and an Insert menu page to feat(game): achievements with unlock pop-ups and an Insert menu page 2026-11-16 04:32:50 +00:00
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: in-game runs on Windows 11, RTX 3060 Ti, with the unlocks and Insert page checked.
  • Nothing gets worse that I know of: not ticked: Measurements shows a 1.0 fps drop it calls unexplained, and its slowest windows ran about 2 fps lower. Measure that cost and state it in Risks, then tick it.
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: in-game runs on Windows 11, RTX 3060 Ti, with the unlocks and Insert page checked. - *Nothing gets worse that I know of*: not ticked: Measurements shows a 1.0 fps drop it calls unexplained, and its slowest windows ran about 2 fps lower. Measure that cost and state it in Risks, then tick it.
Zapiltar changed title from feat(game): achievements with unlock pop-ups and an Insert menu page to WIP: feat(game): achievements with unlock pop-ups and an Insert menu page 2026-11-18 03:04:04 +00:00
Zapiltar force-pushed feat/achievements from 734b29bc4a
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 5s
CI / Workflow lint (actionlint) (pull_request) Successful in 5s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 4s
Third-party parts / As their notes say (pull_request) Successful in 8s
Website / Website on Cloudflare (pull_request_target) Has been skipped
beanstalk/approval changed since the request: ask again
PR description / Description follows the template (pull_request_target) Successful in 4s
to a8e21dc396
Some checks are pending
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request_target) Has been skipped
beanstalk/approval waiting for a BigBean's 👍 on the request
PR description / Description follows the template (pull_request_target) Successful in 3s
2026-11-18 05:12:41 +00:00
Compare
Author
First-time contributor

Screenshots, this PR @ 44deed6e on main @ d664e342 (RTX 3060 Ti, Windows 11, 1920x1080, Quality preset Auto), taken from the screen in the Market with the test save: main's new Insert menu style.

The Gameplay tab's rows, Achievement alerts and Achievements, between Skip opening and Bug report:

The Gameplay tab's rows

The Achievements page: the RetroAchievements list, 9 of 51 unlocked from this save (the stones, the medallions, and meeting Zelda through Zelda's Lullaby), the locked ones dimmed:

The Achievements page

Screenshots, this PR @ 44deed6e on main @ d664e342 (RTX 3060 Ti, Windows 11, 1920x1080, Quality preset Auto), taken from the screen in the Market with the test save: main's new Insert menu style. **The Gameplay tab's rows**, Achievement alerts and Achievements, between Skip opening and Bug report: ![The Gameplay tab's rows](https://git.magicbean.dev/attachments/ebe39028-236d-4909-82ed-61ca03823ba8) **The Achievements page**: the RetroAchievements list, 9 of 51 unlocked from this save (the stones, the medallions, and meeting Zelda through Zelda's Lullaby), the locked ones dimmed: ![The Achievements page](https://git.magicbean.dev/attachments/471423ce-b52e-4b36-b22f-228a0635e690)
Author
First-time contributor

Rebased on main @ d664e342, the list reworked, and measured again (now a8e21dc3).

  • The list follows the RetroAchievements set: one row per achievement of theirs, in their order, as far as the game side can see it happen: 51 of their 97, with our own titles, descriptions and icons (102 icons, redrawn). Rows not in their set are gone (the sword and shield, the Fairy Ocarina, the single songs, the Mirror Shield, Hover Boots, Longshot, Hammer, Golden Gauntlets, Stone of Agony, magic, wallets, the plain boss defeats, ten hearts); new are all twelve songs and a bottle of milk. docs/achievements.md lists the 46 not tracked yet (boss challenges, minigames and side quests with no readable sign yet, capacity upgrades) and why.
  • Measured (sixteen interleaved runs in the Market, RTX 3060 Ti, scripts/dev_packs.py: one base of main, the PR as a pack, one pinned options file): main 53.45 fps, this PR 54.32, the PR ahead in 6 of 8 pairs. The slow end is the same across all 95 windows each (5th percentile 45.9 against 46.4, 19% against 18% under 50 fps); the earlier "slowest window about 2 fps lower" only shows in each run's single worst window, the same on both sides once all windows are counted. That settles the Nothing gets worse box: ticked, with the numbers in Measurements and Risks.
  • In the game: the test save unlocks exactly its nine, including meeting Zelda through Zelda's Lullaby, the first song name proven in play; main's new Insert menu shows both rows and the page (screenshots in the comment above and the description).
  • Rebase: two conflicts (main's option id 59 and its quick Debug Tools page beside ours), both kept; the checks fail exactly what clean main fails here, plus one more pass (test_oot_achievements).
  • The description has the template's new TL;DR and Breakdown. Still open: the Linux run (the Test Farm request was for an older commit, so it has to be asked again) and a bottle seen in a real save.
Rebased on `main` @ d664e342, the list reworked, and measured again (now a8e21dc3). - **The list follows the RetroAchievements set:** one row per achievement of theirs, in their order, as far as the game side can see it happen: 51 of their 97, with our own titles, descriptions and icons (102 icons, redrawn). Rows not in their set are gone (the sword and shield, the Fairy Ocarina, the single songs, the Mirror Shield, Hover Boots, Longshot, Hammer, Golden Gauntlets, Stone of Agony, magic, wallets, the plain boss defeats, ten hearts); new are all twelve songs and a bottle of milk. `docs/achievements.md` lists the 46 not tracked yet (boss challenges, minigames and side quests with no readable sign yet, capacity upgrades) and why. - **Measured** (sixteen interleaved runs in the Market, RTX 3060 Ti, `scripts/dev_packs.py`: one base of main, the PR as a pack, one pinned options file): main 53.45 fps, this PR 54.32, the PR ahead in 6 of 8 pairs. The slow end is the same across all 95 windows each (5th percentile 45.9 against 46.4, 19% against 18% under 50 fps); the earlier "slowest window about 2 fps lower" only shows in each run's single worst window, the same on both sides once all windows are counted. That settles the *Nothing gets worse* box: ticked, with the numbers in Measurements and Risks. - **In the game:** the test save unlocks exactly its nine, including meeting Zelda through Zelda's Lullaby, the first song name proven in play; main's new Insert menu shows both rows and the page (screenshots in the comment above and the description). - **Rebase:** two conflicts (main's option id 59 and its quick Debug Tools page beside ours), both kept; the checks fail exactly what clean `main` fails here, plus one more pass (`test_oot_achievements`). - The description has the template's new TL;DR and Breakdown. Still open: the Linux run (the Test Farm request was for an older commit, so it has to be asked again) and a bottle seen in a real save.
Author
First-time contributor

@Beanstalk linux, build this PR and load a save past the Great Deku Tree (or play to its end). Expect the log line achievements: unlocked stone_forest (Kokiri's Emerald), its pop-up, a stone_forest <UTC time> line in ~/.local/share/longshot/achievements.txt, and Insert > Gameplay > Achievements listing it as unlocked.

@Beanstalk linux, build this PR and load a save past the Great Deku Tree (or play to its end). Expect the log line `achievements: unlocked stone_forest (Kokiri's Emerald)`, its pop-up, a `stone_forest <UTC time>` line in `~/.local/share/longshot/achievements.txt`, and Insert > Gameplay > Achievements listing it as unlocked.
Member

@Zapiltar only members of BigBeans can start the farm. One of them can approve this request by reacting 👍 to it or to this comment.

@Zapiltar only members of `BigBeans` can start the farm. One of them can approve this request by reacting 👍 to it or to this comment.
Member

Farm readiness review for a8e21dc3: loading an already-completed save can bypass the event that awards the achievement. The current scenario also cannot check the local achievements.txt file. Please use a scrubbed repository save just before the award with a repeatable way to trigger it, and verify persistence across restart by hand using disposable data. The farm can then check the triggered log and menu behavior within a run.

Farm readiness review for `a8e21dc3`: loading an already-completed save can bypass the event that awards the achievement. The current scenario also cannot check the local `achievements.txt` file. Please use a scrubbed repository save just before the award with a repeatable way to trigger it, and verify persistence across restart by hand using disposable data. The farm can then check the triggered log and menu behavior within a run.
Some checks are pending
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request_target) Has been skipped
beanstalk/approval waiting for a BigBean's 👍 on the request
PR description / Description follows the template (pull_request_target) Successful in 3s
This pull request is marked as a work in progress.
Some workflows are waiting to be reviewed.
This branch is out-of-date with the base branch
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'feat/achievements:Zapiltar-feat/achievements'
git switch 'Zapiltar-feat/achievements'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
4 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!392
No description provided.