perf(host): OoT's OptimizeChangeBank no longer reloads a neighbouring map each time Link turns (HOS_OCB_HOLD_MS) #1814

Merged
HumanBean merged 2 commits from GummiNaomi/Longshot:perf/ocb-hold into main 2026-11-20 07:52:42 +00:00
Member

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

  • Who it helps: CPUs with few cores (the Steam Deck likely too, not measured), in places between two neighbouring maps: Castle Town's market plaza and fountain above all.
  • What was wrong: OoT's OptimizeChangeBank thread preloads one neighbouring map, chosen every frame from Link's position and heading; a different choice cancels the map being loaded and loads the new one from the start, and flipping back loads the first again.
  • What changes: a choice other than the map already asked for is taken only once it has stayed the choice for HOS_OCB_HOLD_MS (2000 by default); until then the game's update sees the held map still chosen.
  • What does not change: a first choice, a direct request and the game's other mode are the game's own; map changes; HOS_OCB_HOLD_MS=0 (or off) restores the game's choice at every frame.
  • How it was checked: three interleaved pairs against main in the 4-core fountain basin; six teleports each way (same arrival times and pictures); a game-free test of the rule and the patch.
  • What is still open: other hold values; 16 cores; a sprint to an exit (its preload may start up to 2 s later); the Steam Deck and Linux.
  • Risk: medium: a neighbour's preload can start up to 2 s later when Link turns towards it and keeps going.

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.

  • lift: nx2/oot_patches.py patch_ocb_hold: at the update's choice (L_832b9dc8 in 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 an x19_ local is left as it is (the report then warns), since c->x[19] may be stale there (a later commit on this branch; a test covers that form).
  • host: 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 or off: the game's own choice), one log line saying the hold.
  • docs: the HOS_OCB_HOLD_MS rows in docs/development.md and gpu/vk/switches.def; six files under docs/tested/.
  • tests: 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-start save, 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 from HOS_THREAD_TIMES=5
How to reproduce: the same walk and circles with and without the change (or HOS_OCB_HOLD_MS=0 on this PR); the runs also had RX_VK_ASTC_BC_ALL=1 RX_VK_IMAGE_BLOCK_MB=32 RX_VK_LOAD=create RX_VK_BC_LAYERS=8 RX_VK_LATE_FIX=0

Baseline: main @ f505340b, 11 commits before this PR's base (0de25c3e); none of those 11 touches these files.

Before: main @ f505340b After: this PR @ f505340b Δ (95 %)
fps (three runs) 56.1 / 55.4 / 53.5 68.1 / 65.2 / 66.6 +21 %
mean frame, pooled 18.18 ms 15.01 ms -3.18 ms (-3.70 to -2.67)
frames >= 16.7 ms, pooled 43.2 % 17.1 % -26 points
99th percentile frame 42.7 ms 23.0 ms -19.7 ms
frames of 33.3 ms or more 542 36
loader threads, % of a core 29.0 / 34.2 / 40.7 5.4 / 6.1 / 6.7
  ocb-m-a        main        4598 frames   56.1 fps  late 40.6 %  median 15.94 ms
  ocb-m-b        main        4380 frames   55.4 fps  late 43.6 %  median 16.24 ms
  ocb-m-c        main        4614 frames   53.5 fps  late 45.5 %  median 16.31 ms
  ocb-o-a        ocb         5122 frames   68.1 fps  late 14.9 %  median 14.34 ms
  ocb-o-b        ocb         4746 frames   65.2 fps  late 20.2 %  median 14.87 ms
  ocb-o-c        ocb         5138 frames   66.6 fps  late 16.4 %  median 14.68 ms
main       pooled 13592 frames   55.0 fps  mean 18.18 ms  late 43.2 %
ocb        pooled 15006 frames   66.6 fps  mean 15.01 ms  late 17.1 %
ocb - main: mean -3.179 ms (-17.48 % frame time, fps +21.18 %); 95 % interval -3.702 to -2.665 ms
main pooled             13592 frames  55.0 fps mean 18.18 ms late  43.2 % p99  42.7 p99.9  52.7 hitches 542 (39.88/1000)
ocb pooled              15006 frames  66.6 fps mean 15.01 ms late  17.1 % p99  23.0 p99.9  43.2 hitches  36 (2.40/1000)
[hos ModuleSystemWorker3] ocb: a new neighbour to preload is taken once it stays the choice 2000 ms (HOS_OCB_HOLD_MS; 0: the game's own at every frame)

Area 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.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
HOS_OCB_HOLD_MS how long a new neighbouring map must stay the game's choice before its preload replaces the current one (none: the game's choice every frame) 2000 far fewer cancelled and repeated map loads where two neighbours overlap helps on 4 cores in the market; untested on 16 cores, other values, the Deck 2000 for everyone; 0 or off for the game's own

Testing

Tested: in the game, on main @ f505340b with this change: the six fountain runs and the six area changes above (0 errors in every log). On this head: tests/test_ocb_hold.py passes; tests/test_tested_configurations.py fails 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:

  • steamdeck: walk into Castle Town's fountain and circle for a minute with and without 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)
  • windows, any GPU: sprint from the market's plaza out to Hyrule Field, expecting the field to arrive as fast as with 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 (or off).

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

  • 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). (The changed files' checks on this PC; failures are main's own here.)
  • 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.
  • A file in docs/tested/ for each new measured run (format in docs/tested-configurations.md).
  • A game-free test added for the fix, failing on main and passing here.
  • A check under tests/ that reads changed source updated in this PR, not weakened.
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Not built on Linux.)
  • Docs updated.

🤖 Generated with Claude Code

**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 - **Who it helps:** CPUs with few cores (the Steam Deck likely too, not measured), in places between two neighbouring maps: Castle Town's market plaza and fountain above all. - **What was wrong:** OoT's OptimizeChangeBank thread preloads one neighbouring map, chosen every frame from Link's position and heading; a different choice cancels the map being loaded and loads the new one from the start, and flipping back loads the first again. - **What changes:** a choice other than the map already asked for is taken only once it has stayed the choice for `HOS_OCB_HOLD_MS` (2000 by default); until then the game's update sees the held map still chosen. - **What does not change:** a first choice, a direct request and the game's other mode are the game's own; map changes; `HOS_OCB_HOLD_MS=0` (or `off`) restores the game's choice at every frame. - **How it was checked:** three interleaved pairs against main in the 4-core fountain basin; six teleports each way (same arrival times and pictures); a game-free test of the rule and the patch. - **What is still open:** other hold values; 16 cores; a sprint to an exit (its preload may start up to 2 s later); the Steam Deck and Linux. - **Risk:** medium: a neighbour's preload can start up to 2 s later when Link turns towards it and keeps going. ## 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. - lift: `nx2/oot_patches.py` `patch_ocb_hold`: at the update's choice (`L_832b9dc8` in 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 an `x19_` local is left as it is (the report then warns), since `c->x[19]` may be stale there (a later commit on this branch; a test covers that form). - host: `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 or `off`: the game's own choice), one log line saying the hold. - docs: the `HOS_OCB_HOLD_MS` rows in `docs/development.md` and `gpu/vk/switches.def`; six files under `docs/tested/`. - tests: `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-start` save, 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 from `HOS_THREAD_TIMES=5` How to reproduce: the same walk and circles with and without the change (or `HOS_OCB_HOLD_MS=0` on this PR); the runs also had `RX_VK_ASTC_BC_ALL=1 RX_VK_IMAGE_BLOCK_MB=32 RX_VK_LOAD=create RX_VK_BC_LAYERS=8 RX_VK_LATE_FIX=0` Baseline: main @ f505340b, 11 commits before this PR's base (0de25c3e); none of those 11 touches these files. | | Before: main @ f505340b | After: this PR @ f505340b | Δ (95 %) | |---|---|---|---| | fps (three runs) | 56.1 / 55.4 / 53.5 | 68.1 / 65.2 / 66.6 | +21 % | | mean frame, pooled | 18.18 ms | 15.01 ms | -3.18 ms (-3.70 to -2.67) | | frames >= 16.7 ms, pooled | 43.2 % | 17.1 % | -26 points | | 99th percentile frame | 42.7 ms | 23.0 ms | -19.7 ms | | frames of 33.3 ms or more | 542 | 36 | | | loader threads, % of a core | 29.0 / 34.2 / 40.7 | 5.4 / 6.1 / 6.7 | | ``` ocb-m-a main 4598 frames 56.1 fps late 40.6 % median 15.94 ms ocb-m-b main 4380 frames 55.4 fps late 43.6 % median 16.24 ms ocb-m-c main 4614 frames 53.5 fps late 45.5 % median 16.31 ms ocb-o-a ocb 5122 frames 68.1 fps late 14.9 % median 14.34 ms ocb-o-b ocb 4746 frames 65.2 fps late 20.2 % median 14.87 ms ocb-o-c ocb 5138 frames 66.6 fps late 16.4 % median 14.68 ms main pooled 13592 frames 55.0 fps mean 18.18 ms late 43.2 % ocb pooled 15006 frames 66.6 fps mean 15.01 ms late 17.1 % ocb - main: mean -3.179 ms (-17.48 % frame time, fps +21.18 %); 95 % interval -3.702 to -2.665 ms main pooled 13592 frames 55.0 fps mean 18.18 ms late 43.2 % p99 42.7 p99.9 52.7 hitches 542 (39.88/1000) ocb pooled 15006 frames 66.6 fps mean 15.01 ms late 17.1 % p99 23.0 p99.9 43.2 hitches 36 (2.40/1000) [hos ModuleSystemWorker3] ocb: a new neighbour to preload is taken once it stays the choice 2000 ms (HOS_OCB_HOLD_MS; 0: the game's own at every frame) ``` Area 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. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `HOS_OCB_HOLD_MS` | how long a new neighbouring map must stay the game's choice before its preload replaces the current one | (none: the game's choice every frame) | 2000 | far fewer cancelled and repeated map loads where two neighbours overlap | helps on 4 cores in the market; untested on 16 cores, other values, the Deck | 2000 for everyone; 0 or off for the game's own | ## Testing **Tested:** in the game, on main @ f505340b with this change: the six fountain runs and the six area changes above (0 errors in every log). On this head: `tests/test_ocb_hold.py` passes; `tests/test_tested_configurations.py` fails 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:** - steamdeck: walk into Castle Town's fountain and circle for a minute with and without `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) - windows, any GPU: sprint from the market's plaza out to Hyrule Field, expecting the field to arrive as fast as with `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` (or `off`). **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 - [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). (The changed files' checks on this PC; failures are main's own here.) - [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] A file in `docs/tested/` for each new measured run (format in `docs/tested-configurations.md`). - [x] A game-free test added for the fix, failing on `main` and passing here. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [ ] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Not built on Linux.) - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
perf(host): OoT's OptimizeChangeBank no longer reloads a neighbouring map each time Link turns (HOS_OCB_HOLD_MS)
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 12s
PR description / Description follows the template (pull_request_target) Failing after 15s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 16s
CI / Workflow lint (actionlint) (pull_request) Successful in 16s
Third-party parts / As their notes say (pull_request) Successful in 14s
Website / Website on Cloudflare (pull_request_target) Has been skipped
5042e89578
OoT's OptimizeChangeBank thread preloads one neighbouring map, chosen every frame from
Link's position and heading among the units the current map lists. Asking for another
map than the one loading or loaded cancels it, and when the choice flips back the first
map is read, decompressed and set up again. Where the choice flickers between two
neighbours (standing or circling in the fountain's basin in Castle Town's market), the
loaders reloaded maps over and over.

Now a new choice is taken only once it has stayed the choice for HOS_OCB_HOLD_MS (2000
by default; 0 or off: the game's own choice every frame). A first choice, a direct
request and the game's other mode are the game's own.

Assisted-by: Claude Code
Co-Authored-By: Claude Opus 5.5 <[email protected]>
fix(lift): the OCB hold leaves the update as it is where the manager has no local
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 7s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 11s
CI / Workflow lint (actionlint) (pull_request) Successful in 11s
Third-party parts / As their notes say (pull_request) Successful in 13s
PR description / Description follows the template (pull_request_target) Failing after 5s
beanstalk/approval needs a second approval (sensitive paths)
Website / Website on Cloudflare (pull_request_target) Has been skipped
48b45e7ba2
With the registers as locals the choice is in x21_ and the manager in x19_; c->x[19]
may be stale there (x19 is callee-saved and kept in its local). Where the function has
no x19_ local, patch_ocb_hold now leaves the code as it is (the report warns) instead
of passing c->x[19]. A test covers that form.

Assisted-by: Claude Code
Co-Authored-By: Claude Opus 5.5 <[email protected]>
futondestroyer left a comment

Verdict: Request changes. The hold cache needs a stable bank identity and verified guest layout before it can safely suppress reloads.

Reviewed 48b45e7b against 0de25c3e.

  • host/oot_ocb_hold.c:14,36 and host/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–901 and host/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.

**Verdict: Request changes.** The hold cache needs a stable bank identity and verified guest layout before it can safely suppress reloads. Reviewed `48b45e7b` against `0de25c3e`. - `host/oot_ocb_hold.c:14,36` and `host/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–901` and `host/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.
First-time contributor

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 (5042e895 and 48b45e7b) 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=2 and HOS_FS_TRACE=1 in 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.

At the fountain No switch (hold 2000 ms) HOS_OCB_HOLD_MS=0
Standing 109.4 fps 106.3 fps
Flips 96.8 fps 69.1 fps
Flips: frames over 16.7 ms 0.1% 22.1%
Flips: frames over 22 ms none in 21 s 99 in 17 s
Flips: files opened 36 40,047 (2,315 a second)
Flips: ARes Loading, OptimizeChangeBanc, ParallelDecompThread, Resource Memory (% of a core) 0, 0, 0, 0 55, 47, 30, 16
Flips: BaseProcExecutor (% of a core) 179 149

With 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.

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 (5042e895 and 48b45e7b) 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=2` and `HOS_FS_TRACE=1` in 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. | At the fountain | No switch (hold 2000 ms) | `HOS_OCB_HOLD_MS=0` | |---|---|---| | Standing | 109.4 fps | 106.3 fps | | Flips | 96.8 fps | 69.1 fps | | Flips: frames over 16.7 ms | 0.1% | 22.1% | | Flips: frames over 22 ms | none in 21 s | 99 in 17 s | | Flips: files opened | 36 | 40,047 (2,315 a second) | | Flips: ARes Loading, OptimizeChangeBanc, ParallelDecompThread, Resource Memory (% of a core) | 0, 0, 0, 0 | 55, 47, 30, 16 | | Flips: BaseProcExecutor (% of a core) | 179 | 149 | With 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.
Owner

@Beanstalk

@Beanstalk
Member

@HumanBean approval of 48b45e7 recorded. This diff touches sensitive paths, so a second member of BigBeans must approve it too.

@HumanBean approval of `48b45e7` recorded. This diff touches sensitive paths, so a second member of `BigBeans` must approve it too.
Member

Beanstalk test farm

Commit 6da6c3c · tier untrusted · approved by nobody yet · dashboard

This diff touches sensitive paths, so it needs two members of BigBeans: nx2/oot_patches.py

A member of BigBeans can review this commit and comment @Beanstalk to test it.

<!-- beanstalk:sticky --> ### Beanstalk test farm Commit `6da6c3c` · tier **untrusted** · approved by nobody yet · [dashboard](https://beanstalk.magicbean.dev/prs/1814) This diff touches sensitive paths, so it needs two members of `BigBeans`: `nx2/oot_patches.py` A member of `BigBeans` can review this commit and comment `@Beanstalk` to test it.
GummiNaomi force-pushed perf/ocb-hold from 48b45e7ba2
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 7s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 11s
CI / Workflow lint (actionlint) (pull_request) Successful in 11s
Third-party parts / As their notes say (pull_request) Successful in 13s
PR description / Description follows the template (pull_request_target) Failing after 5s
beanstalk/approval needs a second approval (sensitive paths)
Website / Website on Cloudflare (pull_request_target) Has been skipped
to 6da6c3cca3
Some checks failed
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
CI / Python source checks (ubuntu-24.04, part 1/2) (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 11s
PR description / Description follows the template (pull_request_target) Failing after 18s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 20s
CI / Workflow lint (actionlint) (pull_request) Successful in 22s
Third-party parts / As their notes say (pull_request) Successful in 22s
beanstalk/approval not approved yet
CI / Website build and checks (pull_request) Failing after 2m23s
2026-11-20 07:46:33 +00:00
Compare
HumanBean deleted branch perf/ocb-hold 2026-11-20 07:52:42 +00:00
Contributor

Tested #1814 at 48b45e7b, not the later merged 6da6c3cc. Both arms used main 068fb8eb plus 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=0 and 2000, with #1810 and #1780 off throughout. Two pairs, 60 s per run. Medians, off → on:

  • 21.1 → 21.6 fps (+2.4%); both on runs beat both off runs.
  • 1% low: 14.25 → 15.65 fps; p99 frame time: 70.5 → 64 ms.
  • Frames over 50 ms: 19.7% → 12.8%.

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.

Tested #1814 at `48b45e7b`, not the later merged `6da6c3cc`. Both arms used main `068fb8eb` plus 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=0` and `2000`, with #1810 and #1780 off throughout. Two pairs, 60 s per run. Medians, off → on: - 21.1 → 21.6 fps (+2.4%); both on runs beat both off runs. - 1% low: 14.25 → 15.65 fps; p99 frame time: 70.5 → 64 ms. - Frames over 50 ms: 19.7% → 12.8%. 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.
Author
Member

@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, head 7afc46f8).

  1. A reused slot inheriting the hold timer (host/oot_ocb_hold.h oot_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.
  2. Guest layout and pointer lifetime (oot_ocb_layout, oot_ocb_held, host/oot_ocb_hold.c, nx2/oot_patches.py patch_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).
  3. Negative switch values (oot_ocb_hold_ms): a negative whole number is now off (0), as documented, like 0 and off; read once whatever the value. Tests: unset, empty, 0, negative, positive, off and malformed values, each also as the update sees it.

At 7afc46f8 on 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 % with HOS_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.

@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`, head 7afc46f8). 1. **A reused slot inheriting the hold timer** (`host/oot_ocb_hold.h` `oot_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. 2. **Guest layout and pointer lifetime** (`oot_ocb_layout`, `oot_ocb_held`, `host/oot_ocb_hold.c`, `nx2/oot_patches.py` `patch_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). 3. **Negative switch values** (`oot_ocb_hold_ms`): a negative whole number is now off (0), as documented, like `0` and `off`; read once whatever the value. Tests: unset, empty, 0, negative, positive, off and malformed values, each also as the update sees it. At 7afc46f8 on 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 % with `HOS_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.
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
6 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!1814
No description provided.