perf(host): OoT's OptimizeChangeBank no longer reloads a neighbouring map each time Link turns (HOS_OCB_HOLD_MS) #1814
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
6 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!1814
Loading…
Reference in a new issue
No description provided.
Delete branch "GummiNaomi/Longshot:perf/ocb-hold"
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: perf · Risk: medium · Tested on: Windows 11, RTX 4070 SUPER, Ryzen 9 9950X3D (SMT off, held to 4 cores) · Needs: 16 cores; a Steam Deck; Linux; a sprint to an area's exit
TL;DR
In Castle Town's market, walking or turning around the fountain made the game's background loader throw away a neighbouring map it had half loaded and load another, over and over, because Link stood inside the range of two neighbours and the game picked whichever he faced. That kept the loader threads busy and the frame rate low on CPUs with few cores. This PR makes a new neighbour count only once it has stayed the game's choice for 2 seconds. In the fountain's basin with the game on 4 cores: 55.0 to 66.6 fps, frames over 16.7 ms 43 % to 17 %, the loaders' CPU 29-41 % of a core to 5-7 %; area changes arrive as before.
Breakdown
HOS_OCB_HOLD_MS(2000 by default); until then the game's update sees the held map still chosen.HOS_OCB_HOLD_MS=0(oroff) restores the game's choice at every frame.Why
The market's plaza lies inside the load radius of two neighbouring maps at once (Hyrule Field's, 78 units, and Hyrule Castle's, 50). OoT's OptimizeChangeBank manager (vtable 0x84bc1a28) updates every frame (f_832b9880): among the units whose radius Link is in, it picks the one he moves towards while he moves (or for a while after), else the nearest, asks for it and lets go of the others. Asking for another map than the one loading or loaded cancels it: the loader thread lets go of everything it set up and starts the new one from its layouts. Circling or turning in the plaza flips the choice between the field and the castle every second or so, and each flip is a cancel and a full load: in the 4-core fountain basin the loader threads used 29 to 41 % of a core and over 40 % of frames missed 60 fps.
#1642 (TrashPanda, open) throttles the OptimizeChange thread (3 ms of sleep after each 0.3 ms of work): that limits how much of a core those reloads take; this PR removes the reloads themselves, so the two are complementary (with this, the thread has far less to throttle). #1646 (Jiro113, open) shortens the waits behind FreeAddressRegion that the loaders' releases cause; also complementary.
See #1642, #1646.
What changed
One line of the game's update now asks the host which unit to take; the host keeps the held map until a new choice has lasted the hold.
nx2/oot_patches.pypatch_ocb_hold: at the update's choice (L_832b9dc8in f_832b9880)x21 = hos_oot_ocb_pick(c, x19, x21), the hook declared once, the same text on a second run, a warning when not found; the function keeps its registers in the context (its address is named in the file). With the registers as C locals the call passes the manager's local (x19_); a function in that form without anx19_local is left as it is (the report then warns), sincec->x[19]may be stale there (a later commit on this branch; a test covers that form).host/oot_ocb_hold.h(new): the rule and the manager's fields it reads (the held map: the one asked for next, else the one loading or loaded; a different choice taken once it has stayed the choice that long, without a break), game-free;host/oot_ocb_hold.c(new):hos_oot_ocb_pick,HOS_OCB_HOLD_MS(2000 by default; 0, a negative value oroff: the game's own choice), one log line saying the hold.HOS_OCB_HOLD_MSrows indocs/development.mdandgpu/vk/switches.def; six files underdocs/tested/.tests/test_ocb_hold.py(new): the rule (the header compiled alone: no hold, nothing held or the same choice give the game's choice; another choice gives the held map until it has lasted the hold without a break); which map is held, read from a manager laid out as the game has it (the next one asked for, else the current one in states 1 to 4, none with a direct request); the switch's values (unset or empty the default, a whole number,off); the patch (the choice through the host once, where the update tests it; with the registers as locals only where the manager's register has its local; a file patched before or whose code differs left as it is; the host's function declared).Measurements
Verdict: faster and smoother where the choice flickers: the 4-core fountain basin 55.0 -> 66.6 fps (+21 %, -3.18 ms a frame, 95 %: -3.70 to -2.67), frames over 16.7 ms 43.2 -> 17.1 %, 99th percentile 42.7 -> 23.0 ms, frames of 33.3 ms or more 542 -> 36; the loader threads 29-41 % -> 5-7 % of a core. Area changes: the same.
Hardware: Windows 11 Pro 26200, RTX 4070 SUPER 12 GB (NVIDIA 617.42), Ryzen 9 9950X3D with SMT off, 32 GB; the game held to 4 cores (process affinity 0xF00)
Scene: Castle Town's market (child): walked from the entrance into the fountain's basin from the
kokiri-startsave, then four cycles of small circles there; output 2560x1440, uncapped (HOS_FPS_MAX=1000), no window (HOS_HEADLESS=1)Method:
RX_VK_FRAME_TRACE=1, the circles' frames only; three pairs, interleaved (main, PR | PR, main | main, PR) by swapping the executable in one game folder; a 95 % interval for the difference of the means by a bootstrap over 3 s blocks; the loaders' CPU fromHOS_THREAD_TIMES=5How to reproduce: the same walk and circles with and without the change (or
HOS_OCB_HOLD_MS=0on this PR); the runs also hadRX_VK_ASTC_BC_ALL=1 RX_VK_IMAGE_BLOCK_MB=32 RX_VK_LOAD=create RX_VK_BC_LAYERS=8 RX_VK_LATE_FIX=0Baseline: main @
f505340b, 11 commits before this PR's base (0de25c3e); none of those 11 touches these files.f505340bf505340bArea changes, six teleports each way (Castle Town's market, Hyrule Field, Kokiri Forest, twice): arrival times 5.4 / 4.3 / 2.9 / 4.6 / 3.2 / 2.8 s with the hold against 5.2 / 3.2 / 2.9 / 4.9 / 3.3 / 2.9 s on main; the same pictures with every model present; a walk south to the field's exit ends at the same spot and event in both.
Flags and settings
One switch added; the hold is on by default.
HOS_OCB_HOLD_MSTesting
Tested: in the game, on main @
f505340bwith this change: the six fountain runs and the six area changes above (0 errors in every log). On this head:tests/test_ocb_hold.pypasses;tests/test_tested_configurations.pyfails only as it does on main on Windows (line endings). Of the 59 checks that read the files this PR changes, the 21 that fail on this PC fail the same way on main @0de25c3e(MSVC headers under-Werror, a missing Tooling checkout, linker setup, and main's own switch-table gaps); none is this PR's.Not tested: other hold values (1000 ms was borderline: a circle faces each neighbour for about a second); 16 cores; a sprint straight to an area's exit, where the next map's preload may start up to 2 s later; the Steam Deck; Linux.
Must be tested:
HOS_OCB_HOLD_MS=0, expecting fewer long frames with the hold (the default) (Test Farm: @Beanstalk steamdeck, the market fountain circles with HOS_OCB_HOLD_MS=0 against unset)HOS_OCB_HOLD_MS=0(by hand: a person, the arrival time in the log)Risks
What could break: a neighbouring map that Link turns towards and runs for can start preloading up to 2 s later, so an exit reached very quickly may load more at the loading screen; the game's own loading still handles it. A wrong manager layout would pass the game's choice through (the rule only replaces the choice by the map already asked for).
Turning it off:
HOS_OCB_HOLD_MS=0(oroff).Compatibility: the lifted code changes (one line of one function; it keeps its registers in the context), so the game is translated again; saves, options and caches otherwise as before.
Issues
See #1642, #1646
Checklist
Everyone
type(scope): description) of the status line's type.main.python -I -B tests/run_all.pypasses (any failure that also fails onmainis named). (The changed files' checks on this PC; failures are main's own here.)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).mainand passing here.tests/that reads changed source updated in this PR, not weakened.🤖 Generated with Claude Code
Verdict: Request changes. The hold cache needs a stable bank identity and verified guest layout before it can safely suppress reloads.
Reviewed
48b45e7bagainst0de25c3e.host/oot_ocb_hold.c:14,36andhost/oot_ocb_hold.h:26–43: a reused slot can inherit the old occupant’s hold timer. Invalidate on identity change or key the timer to the bank identity and lifetime. Add a same-slot replacement case within the hold window.nx2/oot_patches.py:877–901andhost/oot_ocb_hold.h:79–91: the read assumes guest map layout and pointer lifetime. Validate the build/layout and the live ownership of the referenced storage. Fall back to ordinary behavior on an unsupported layout or stale reference.host/oot_ocb_hold.h:47–56: define and enforce the behavior of negative switch values consistently with the documented disable behavior. Add explicit unset, zero, negative and positive cases.After the source fixes, validate the final default at the new head on real bank transitions and representative hardware. Prior runs remain evidence for the revision the author exercised.
Tested on 16 cores on Windows. For me it fixes the stutter I reported in #1831.
What I ran. My own build of the v3.0.0 tag with this pull request's two commits (
5042e895and48b45e7b) applied as a patch, plus the changes of my own that #1831 lists (none touches loading). The patch applies to v3.0.0 with line offsets only. In my build the text of the two new host files is compiled as part of an existing host file, unchanged. The build log says "oot_patches: the preload manager's choice of a neighbouring map through the host in code_039.c", with no warning, and the game's log has "ocb: a new neighbour to preload is taken once it stays the choice 2000 ms".PC and settings. Ryzen 9 9950X3D (16 cores, 32 logical processors, nothing set to limit them), RTX 5090, Windows 11. 3840x2160, DLSS Quality, cap 240, as in #1831. No recorder.
RX_VK_FRAME_TRACE=1,HOS_THREAD_TIMES=2andHOS_FS_TRACE=1in both runs.Two runs of the same build, child, day: stand at the market's fountain, then flip left and right for about 20 seconds.
HOS_OCB_HOLD_MS=0With the hold the flips run at 88% of standing; without it, at 65%. It also does better than the read delay I used in #1831 to show the cause (91 fps at 4 ms). The stutter is gone.
Going out to Hyrule Field right after the flips felt normal with the hold.
Not measured: the loading time on the way out, and other hold values.
@Beanstalk
@HumanBean approval of
48b45e7recorded. This diff touches sensitive paths, so a second member ofBigBeansmust approve it too.Beanstalk test farm
Commit
6da6c3c· tier untrusted · approved by nobody yet · dashboardThis diff touches sensitive paths, so it needs two members of
BigBeans:nx2/oot_patches.pyA member of
BigBeanscan review this commit and comment@Beanstalkto test it.48b45e7ba26da6c3cca3Tested #1814 at
48b45e7b, not the later merged6da6c3cc. Both arms used main068fb8ebplus a local stand-in for #1815. Steam Deck OLED, 1280×800, fullscreen Game Mode, HDR on, GPU held at peak clocks as main does on Deck.Standing in the Market, I alternated
HOS_OCB_HOLD_MS=0and2000, with #1810 and #1780 off throughout. Two pairs, 60 s per run. Medians, off → on:Moving, I only tested all three on against main. On the Field walk (2 pairs), fps went from 21.85 to 22.7 (+3.9%), 1% low from 12.45 to 14.7 fps, p99 from 80 to 68 ms, and frames over 50 ms from 16.3% to 8.55%.
The fountain circle and sprint (3 pairs) went from 19.3 to 19.7 fps. Both arms reached the load in about 24 s; that doesn't tell us when preload started. The Market turn (5 pairs) went from 19.8 to 21.8 fps, but two pairs went the other way. Two or three pairs are a first check, and none of the moving runs isolates the hold.
@futondestroyer thank you for the review. This was merged before your three points were addressed, so they are fixed in a follow-up: #1870 (branch
GummiNaomi:fix/ocb-hold-review, head7afc46f8).host/oot_ocb_hold.hoot_ocb_pick,oot_ocb_key): a choice is now the manager, the unit and the map in it (a hash of the unit's own path), seen by every update with no gap over 500 ms; any change restarts its time. Test: the same slot refilled with another map within the hold is taken 2 s after the new occupant became the choice (3600 ms), not on the old one's time (main: 2000 ms); also a pause and another manager.oot_ocb_layout,oot_ocb_held,host/oot_ocb_hold.c,nx2/oot_patches.pypatch_file): before each read the host checks the manager as its constructor builds it (vtable 0x84bc1a28, each path pointer at its own 0x100-byte buffer inside the manager, buffer sizes, length, state, in-use flags, the chosen unit in use) and reads only those buffers, so nothing outside the live manager is read; any mismatch gives the game's own choice (counted, logged once). The patch is made only in the supported build's lift, and the host checks main's build id. Tests: each mismatch, including a stale pointer to memory that holds the held path (main followed it).oot_ocb_hold_ms): a negative whole number is now off (0), as documented, like0andoff; read once whatever the value. Tests: unset, empty, 0, negative, positive, off and malformed values, each also as the update sees it.At
7afc46f8on 4 cores in the fountain basin (Ryzen 9 9950X3D SMT off, RTX 4070 SUPER): 70.4 fps against main 8f462db5's 71.1 (runs overlap: 69.6-71.7 against 70.5-71.5), loaders 6-8 % of a core on both, 43 % withHOS_OCB_HOLD_MS=-1; 0 updates refused by the layout check; 6 of 6 area changes on both. Details in the follow-up's description.