WIP: feat(game): achievements with unlock pop-ups and an Insert menu page #392
No reviewers
Labels
No labels
area/accessibility
area/audio
area/input
area/install
area/menu
area/renderer
area/saves
area/tooling
area/upscaling
beanstalk: approved
beanstalk: failed
beanstalk: needs approval
beanstalk: running
beanstalk: tested
ci: approved
good first issue
gpu/amd
gpu/igpu
gpu/intel
gpu/nvidia
help wanted
kind
bug
kind
chore
kind
docs
kind
feature
kind
performance
kind
question
needs measurements
platform/linux
platform/macos
platform/steam-deck
platform/windows
preview
priority
critical
priority
high
priority
low
regression
risk
high
risk
low
risk
medium
status
blocked
status
confirmed
status
duplicate
status
invalid
status
needs-info
status
wontfix
ci: approved
No milestone
No project
No assignees
4 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!392
Loading…
Reference in a new issue
No description provided.
Delete branch "Zapiltar/Longshot:feat/achievements"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Type: feat · Risk: low · Tested on: 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
user/achievements.txt, a pop-up when one isearned (Gameplay → Achievement alerts) and a list page (Gameplay → Achievements).
vk_api.hchange); nothing unlocks in arun where a debug tool was used.
test_oot_achievementsand 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.
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 sidechecks 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.
gpu/vk/oot_achievements.h, an X-macro shared by the game side and the menu (id, title, description, thepouch contents it asks for: all of them, or any for the bag tiers;
name>=Nfor a count, the Skulltula Tokens), inthe 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.host/oot_achievements.chos_oot_achievements_check, called fromhost/hos_main.coot_inventory_refreshwith 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 readerhos_oot_flag_numberinhost/oot_state_tap.c, under the samelock);
Bottlesadds up the bottle pouch items,Milkthe milk among them, andSongscounts the twelve songs(
OOT_ACHIEVEMENT_SONGS). Unlocks go touser/achievements.txt(<id> <UTC time>, writtenwhole through a temporary file; unknown ids kept).
hos_oot_achievements_cheatedinoot_update_player_cheats: nothing unlocks for the rest of that run.gpu/vk/vk_menu.cpp): the pop-updraw_achievement_toast(withmenu_record/menu_record_image, overeverything; 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).assets/achievements/*.png, 102 icons (unlocked and locked), drawn from plain shapes byscripts/make_achievement_icons.py(provenance inassets/achievements/PROVENANCE.txt, format in itsREADME.md).nx2/achievement_icons.pypacks them into one atlas in a generated header, asnx2/logo_rgba.pydoes the logo;gpu/vk/vk_imgui.cppachievement_iconloads it as a single texture.vk_api.horvk_replay.cpp:vk_api.hstamps the shader caches, so this PR makes no playerprepare shaders again. The game side tells the menu through
rx_option_setids past the Inventory page's.docs/achievements.md(design, the list and the set's rows not tracked yet, open questions, testing); theREADME's option table.
tests/test_oot_achievements.py(new);test_fps_overlay_order.py,test_readme_menu_rows.pyandtest_shader_stamp_cache.pyupdated for the pop-up, the new rows and the icons' build step.modsfolder (needs a runtime PNG decoder), andthe Longshot Launcher's list page (it can read
user/achievements.txt).Screenshots (After: this PR @
44deed6eon 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 Achievements page, 9 of 51 unlocked from this save:
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 (itslongshot.exeandlongshot_vk.dll), and a runtime of each, so both arms share every other file and the same shader caches. Every runstarted 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 own5-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_CONTROLandHOS_OPTIONS_FILEset,longshot_ctl.py press Auntilstatussays play, 30 s, then read thevi: ... fps over the last 5.0 slines oflogs/longshot_log.txtfor 60 s.d664e34244deed6eThe 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 @
0caf0618against this PR's first 29 rows, 56.2 against 56.5 fps (four runs, 2026-11-14); main @5274fb72against 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 docsonly); their files:
docs/tested/2026-11-17-achievements-zapiltar-run01.mdto2026-11-18-achievements-zapiltar-run16.md.The log lines (each measured run's 60 s)
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.
achievement_alerts=in longshot_options.ini)Testing
Tested:
44deed6eon main @d664e342: the test save (thestones, the medallions, Zelda's Lullaby, three hearts) loaded with Continue logs
achievements: unlockedfor exactlynine: Kokiri's Emerald, Goron's Ruby, Zora's Sapphire, the five temples and An Audience with the Princess, then
achievements: 9 of 51 unlockedin every later run, and nothing more in the eleven runs of it. The last of the nineproves the first song name,
Item_Melody_ZeldaLullaby, in play.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.pyon this branch (Windows 11, llvm-mingw 20261104): 618 passed, 42 failed, 110 skipped;clean
main@d664e342on 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_homehere,test_longshot_ctlonmain). The one more pass is
test_oot_achievements, which now also checks all twelve songs, the milk, and all-of andany-of on rows of their own.
d664e342had two conflicts: main took option id 59 for the transition autosave (the firstcommit's pause, which the second commit takes out again, so
vk_api.hstill ends as on main) and added the quickDebug Tools page beside the Achievements page; both kept.
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:
items is unproven. The inventory editor can't give one (the game turns down every
Item_Bottleadd) and the test savehas none; the game data's five bottle slots don't say what Link owns (all five
IsValidread true on a save with nobottle). Both can only fail to unlock, never unlock early.
this save, and nothing unlocked early; none has been seen turning on.
not yet seen held.
renamethere).Must be tested:
end), expecting the log line
achievements: unlocked stone_forest (Kokiri's Emerald), its pop-up, the linestone_forest <UTC time>in~/.local/share/longshot/achievements.txt, and the page listing it as unlocked (TestFarm: @Beanstalk linux, asked in this comment,
waiting for a BigBeans member's 👍; or by hand:
test request T-MLWS).
inventory probeline to show them among theItem_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.hchange, so no shader orpipeline cache is prepared again, and
MKWVK_API_VERSIONis unchanged. A newuser/achievements.txtappears beside thesaves once something unlocks, and a new
achievement_alerts=line inlongshot_options.ini.Checklist
Everyone
type(scope): description) of the status line's type.can't be run by hand is in Testing's Not testable by hand, with why.
in Risks.
main.python -I -B tests/run_all.pypasses (any failure that also fails onmainis named).third_party/untouched (a new folder with aPROVENANCE.mdinstead).When it applies
Assisted-by:/Co-Authored-By:trailers.docs/tested/for each new measured run (format indocs/tested-configurations.md).tests/that reads changed source updated in this PR, not weakened.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 Achievements page (Insert → Gameplay → Achievements): 9 of 29 unlocked, the locked ones dimmed with their padlock icons:
The Gameplay tab's new rows, Achievement alerts and Achievements:
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):
Measured (main @
0caf0618against 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.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.
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]>e25520b4adds 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.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.mainis 52 commits ahead. Measured: these rows and the bigger atlas aren't measured yet. Both will be done together, after a rebase.e25520b4db38f22e5ad2Rebased on
main@5274fb72(force-pushed, now38f22e5a), and measured again.maintook option id 58 forHOS_OPT_RENDER_THREAD, the id this branch's first commit used for the pause. The later commit removes that id again, sovk_api.hends exactly as onmainand the shader caches don't change. The checks give 503 passed and 17 failed; cleanmaingives 502 and the same 17 failed. The extra pass istest_oot_achievements.mainfirst and three with the PR first):main56.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.docs/tested/2026-11-15-achievements-zapiltar-run01.mdtorun12.md.The PR stays WIP until the Linux run (T-MLWS).
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.
@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 asword_and_shield <UTC time>line in~/.local/share/longshot/achievements.txt; then Insert > Gameplay > Achievements lists it as unlocked.@Zapiltar only members of
BigBeanscan start the farm.One of them can approve this request by reacting 👍 to it.This request was for38f22e5, and the PR has changed since (734b29b), so a 👍 no longer approves it. Comment@Beanstalkagain to ask for the new commit.38f22e5ad2734b29bc4aWIP: feat(game): achievements with unlock pop-ups and an Insert menu pageto feat(game): achievements with unlock pop-ups and an Insert menu pageBrought 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).
feat(game): achievements with unlock pop-ups and an Insert menu pageto WIP: feat(game): achievements with unlock pop-ups and an Insert menu page734b29bc4aa8e21dc396Screenshots, this PR @
44deed6eon 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 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:
Rebased on
main@d664e342, the list reworked, and measured again (nowa8e21dc3).docs/achievements.mdlists the 46 not tracked yet (boss challenges, minigames and side quests with no readable sign yet, capacity upgrades) and why.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.mainfails here, plus one more pass (test_oot_achievements).@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, astone_forest <UTC time>line in~/.local/share/longshot/achievements.txt, and Insert > Gameplay > Achievements listing it as unlocked.@Zapiltar only members of
BigBeanscan start the farm. One of them can approve this request by reacting 👍 to it or to this comment.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 localachievements.txtfile. 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.View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.