perf: less game work a frame in Castle Town (registers as locals, vector rewrites) #1576

Open
Veix wants to merge 11 commits from Veix/Longshot:perf/market-game-work into main
First-time contributor

Type: perf · Risk: medium · Tested on: Windows 11, RTX 4070 SUPER · Needs: Windows on AMD and Intel GPUs; a CPU without SSSE3

Scope and title changed on 2026-11-18. This pull request was opened with six pieces, its title ending "(registers as locals, vector rewrites, unchanged texture data left alone)". After review it holds the two translator pieces that carry the gain. Taken out, each with nothing measurable on current main: the FMIN / FMAX fast path, the packaged-texture-data check, the identical-copy check and the capture-buffer worker. The numbers below are this head's.

TL;DR

In Castle Town's market the game's own work takes most of a 60 fps frame, so the frame rate dips. This PR makes the translated game code faster in two ways: a function keeps its hottest console registers in local variables, and five vector instruction forms become one processor instruction each. On a Ryzen 9 9900X the game's work per frame drops from 16.6 to 14.3 ms and the market runs at 61.1 instead of 56.5 fps with the cap lifted to 90. Checked with traced runs against main, each piece also by itself, with game-free tests for the rewritten instructions, and by a tester on a Steam Deck (+7 % where the game's code is the limit).

Breakdown

  • Who it helps: anyone whose frame rate in busy areas is limited by the CPU: Castle Town's market first of all.
  • What was wrong: the lifted code loads and stores the guest context around every instruction, and runs some vector instructions as byte loops.
  • What changes: a function's six most used guest registers and the four flags are C locals, and TBL, EXT, 128-bit vector loads, DUP and FMUL by element are one SSE instruction each.
  • What does not change: the game's patches (a function they touch keeps the context, as before), the host, the renderer, saves, options, the caches' formats.
  • How it was checked: traced runs of a recorded route through the market, main against this PR; each of the two pieces switched off by itself; a standing run; tests/test_vbytes.py and tests/test_vfpx_elem.py.
  • What is still open: Windows on AMD and Intel cards, and a CPU without SSSE3. The game's build takes 12-26 % longer (Risks).
  • Risk: medium: the change reaches every lifted function; each piece has a lift-time switch.

Why

In Castle Town's market the main thread's game work is about 16 ms of the 16.7 ms a 60 fps frame has, so every extra millisecond is a dropped frame. Part of that time is not the game's logic but how its code was translated: registers read from and written to memory around every instruction, and vector instructions spelled out byte by byte.

See #1020, #1560 (a rework of the place the locals hook into, in progress).

What changed

Two changes to how the game's code is written as C. Nothing in third_party/ is edited: both wrap the kit's functions from nx2/.

  • Guest registers and flags as C locals (nx2/guest_locals.py, nx2/lift.py): the kit's A64_LOCAL_REGS / A64_LOCAL_FLAGS on by default, six registers per function plus N, Z, C, V. A function the game's patches touch, one that holds an address they name, one with C spliced into it and one whose code starts below its entry (lift_fixes jumps to the entry from its head, over the place where the locals are loaded: keep_entered_below) keep the context: oot_patches.touches answers that per function, such a function is also written with the kit's context-flag text for every instruction (install_plain), and check_patched() stops the lift if a patched function has locals. The horse's jump blend and the moving floors' patches apply unchanged.
  • Vector instructions as one SSE instruction each (nx2/fastvec.py): TBL with a one-register table (PSHUFB), EXT (PALIGNR or two shifts), 128-bit vector loads, DUP by element, FMUL by element. They were byte loops through the stack; TBL has 2,995 sites in the game and EXT 29,451.
  • tests: tests/test_vbytes.py and tests/test_vfpx_elem.py run every rewritten form both ways against the kit's text; tests/test_entry_below_locals.py checks that a function entered below its first block gets no locals; nx2/test_leaf.py covers the locals.

Measurements

Verdict: faster: 12-15 % less game work a frame, measured in Castle Town's market and on Death Mountain Trail; +15 % fps where the CPU is the limit (720p: 71.6 to 82.0 in the market), +8 % on the walked market route at 4K (56.5 to 61.1), little where the GPU is the limit. Each of the two pieces shows by itself: 1.4 ms for the locals, 1.2 ms for the vector rewrites.

Hardware: Windows 11 (26200), RTX 4070 SUPER 12 GB, NVIDIA 621.24, Ryzen 9 9900X, 64 GB
Scene: Castle Town market by day, the second visit of a recorded route (market, castle, market; 59.5 s); 4K output, DLSS Quality (1440p internal), V-Sync on, default settings, frame rate cap 90 (a measuring setup: above the game's 60, so that the fps can show the gain)
Method: fps and 1% low from present intervals (HOS_PRESENT_TRACE); game work a frame from RX_VK_FRAME_TRACE (game_ms + wait_main_ms, the median of the visit's frames); 2 runs a side; main's two were made 3 hours before this head's (the same build of main, the same settings), so not interleaved
How to reproduce: a save in Castle Town, the route above, HOS_FPS_MAX=90

Baseline: main @ 430eef4f, the base these runs were made on. The head has since been rebased (main has had renderer and build-script changes, none in the code this PR writes) and changed after review in one way that reaches the game: 26 functions whose code starts below their entry keep the context. One run of it on this route gave 61.8 fps and 13.97 ms of game work a frame, so the numbers hold.

Before: main @ 430eef4f After: this PR @ 826cf67c (the head before its rebase) Δ
fps 56.7 / 56.3 61.3 / 60.9 +4.6
1% low fps 26.2 / 28.2 27.5 / 28.1 +0.6
game work a frame, median 16.60 / 16.70 ms 14.26 / 14.58 ms -2.23 ms

Each piece by itself (the same route and settings, one run each, on the earlier head 15c563a8, whose other pieces showed nothing measurable):

game work a frame fps
both pieces 14.27 / 14.30 ms 61.9 / 61.5
without the locals (A64_LOCAL_REGS=0, A64_LOCAL_FLAGS=0) 15.64 ms 58.7
without the vector rewrites (A64_NO_VBYTES=1, A64_NO_VMOVES=1, A64_NO_VFPX_ELEM=1) 15.46 ms 59.6

Standing after a teleport to each place, 30 s measured, two runs a side in the order main, PR, main, PR. First with the GPU out of the way (1280x720 output, DLAA, uncapped, V-Sync off), then as played here (4K, DLSS Quality, cap 120):

Before: main @ 430eef4f After: this PR @ 826cf67c Δ
720p, Castle Town market: fps 72.2 / 70.9 81.9 / 82.1 +15 %
720p, Castle Town market: game work a frame 13.47 / 13.76 ms 11.91 / 11.82 ms -13 %
720p, Death Mountain Trail: fps 108.4 / 112.3 127.9 / 125.9 +15 %
720p, Death Mountain Trail: game work a frame 8.93 / 8.74 ms 7.60 / 7.66 ms -14 %
4K, Castle Town market: fps 72.0 / 71.3 73.9 / 73.8 +3 %
4K, Castle Town market: game work a frame 13.07 / 13.27 ms 11.49 / 11.71 ms -12 %
4K, Death Mountain Trail: fps 94.5 / 94.1 94.2 / 93.7 0 %
4K, Death Mountain Trail: game work a frame 8.89 / 9.06 ms 8.27 / 8.30 ms -8 %

So the gain is there at rest too, and how much of it shows as fps depends on what limits the frame: all of it where the CPU does (720p: the game never waits for the GPU), little or none where the GPU does (4K here: the game's wait for it grows from 0.5 to 1.7 ms a frame in the market, 1.5 to 2.2 ms on the trail).
A tester's Steam Deck OLED (Linux, RADV; both sides built all at -O2; the earlier head, which had these two pieces and four more): Death Mountain Trail under the falling rocks 17.5 to 18.8 fps (+7 %), the frame less the replay 37.9 to 34.1 ms; Castle Town's market, where the Deck's GPU limits, no difference; 8 starts and a session in the Fire Temple without a fault.

[hos host] report: gpu NVIDIA GeForce RTX 4070 SUPER, NVIDIA 621.24
[hos host] report: cpu AMD Ryzen 9 9900X 12-Core Processor (24 threads), 62 GB
[hos host] vk: swapchain 3840x2160, 4 images, fifo (V-Sync On)
run                 fps   1%low    >20    >25    >33 | game work a frame: median
main-none-1        56.7    26.2    355     59      9 | 16.60
main-none-2        56.3    28.2    411     66      9 | 16.70
slim-none-1        61.3    27.5    347     46     13 | 14.26
slim-none-2        60.9    28.1    352     50     10 | 14.58

Works well together with

Three settings main already has add to this change. This PR changes none of them. HOS_KEEP_FREED_PAGES on by default where the PC has the memory follows as a separate pull request. Whether the other two should become defaults is a question for the maintainers; their gain with this PR's code is shown here. The same route, walking, cap at 90, two runs each:

main with this PR's two pieces
default settings 56.5 fps 61.1 fps
with RX_VK_FRAME_GATE=0 and RX_VK_READBACK_LATE=3980,9b040,8b040,44b040,1b580 58.4 fps 65.1 fps
frames over 20 ms, default settings 355 / 411 347 / 352
frames over 20 ms, with the two settings 169 / 211 129 / 143
  • The two settings take away waits: the game no longer waits for the renderer before its next frame, nor for GPU results it asked for. They halve the long frames on either build. In fps they give more with this PR (+4.0) than on main (+1.9): the game's frame is shorter, and without those waits that shows.
  • HOS_KEEP_FREED_PAGES=1 removes the frames in which the game's main thread is blocked for a whole frame while freed memory is given back to the system: 15 to 25 a market visit down to 0, the frames over 25 ms from 29-50 to 12. It costs 0.5 to 0.7 GB of memory in use.

(The rows with the two settings and the third setting's numbers were measured with the earlier head, which had these two pieces and four that changed nothing measurable.)

Flags and settings

Five lift-time switches; two are the kit's own whose default changes, three are new. Each ships on.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
A64_LOCAL_REGS lift time: guest registers a function keeps as C locals 0 (the kit's default) 6 less context traffic in lifted code helps: Zen 5; untested elsewhere 6 for everyone
A64_LOCAL_FLAGS lift time: N, Z, C, V as C locals off on (=0 off) as above as above on
A64_NO_VBYTES lift time: =1 keeps TBL / EXT as byte loops (new) unset one SSSE3 instruction each helps unset
A64_NO_VMOVES lift time: =1 keeps vector loads / DUP as the kit writes them (new) unset one SSE load or shuffle helps unset
A64_NO_VFPX_ELEM lift time: =1 keeps FMUL by element as the kit writes it (new) unset one shuffle and multiply helps a little unset

Testing

Tested: Windows 11, RTX 4070 SUPER, NVIDIA 621.24: the market route above with this head and with main; the build log shows the three gameplay patch sites applied and no warning. The same two pieces, with more on top, have been played by hand for over half an hour in Castle Town, the castle grounds and shops, no glitch seen. python -I -B tests/run_all.py: 633 passed, 36 failed, 113 skipped; every failing check also fails without this change on this PC, none is new. A tester ran the earlier head on a Steam Deck OLED (Linux, RADV): it builds, 8 starts and a minute in the Fire Temple without a crash or a fault in the log.

The Test Farm's first run (the earlier head f862753, Linux, RTX 4070, one run a side) reported a fail on two rules: its picture was taken while Link ran, a few steps apart on the two sides (both pictures are a correct market street), and the 99th-percentile frame time of one 20 s window right after the arrival was 35.9 against 27.0 ms, the median the same (14.2 ms). No crash; its build timing is in Risks. The test asked for below stands still and runs twice a side.

Not tested: Windows on AMD and Intel GPUs; a CPU without SSSE3 (the vector rewrites use PSHUFB and PALIGNR); areas beyond Castle Town and the castle grounds; nx2/test_insn.py and nx2/test_leaf.py --calls on this base.

Must be tested:

  • Linux and Windows, any GPU: teleport to Market_Child, stand 30 s and measure; teleport to DeathMountainTrail_Child, stand 30 s and measure; uncapped, render resolution 50 %, the game's own upscaler, frame generation off; expecting no crash, the same picture as main, and a frame rate not below main's in both places: up to about 10 % above it where the CPU is the limit, about the same where the GPU is (Test Farm: @Beanstalk linux and windows)

Risks

What could break: a lifted function that reads a register or a flag from the context while it lives in a local (the kit's context marks, the patched functions' rule and check_patched() guard this); a vector rewrite on an operand form the tests do not cover.

What it costs: the game's build takes longer, since the C with locals is more work for the lift and the compiler. The Test Farm timed it on an earlier head (Ryzen 7 5800X3D, 6 compile jobs, two builds a side in turn): 592.9 to 748.4 s (+26 %), the lift 74.6 to 95.5 s, the compile 500.0 to 634.7 s. Since then the lift's part is smaller (the plain text is made only for the functions that need it: 55 to 51 s here, 45 s without locals). A tester's Steam Deck: +16 %; here on 12 cores: +12 %. The cost is paid when the game code is built anew: every install takes it nearly in full once, at its first build with this change, and not again on updates that leave the game code as it is.

Turning it off: each piece by its switches above, at build time: the game's code is translated again.

Compatibility: the game's code is lifted and compiled again once after the update (the lift key holds the switches). Saves, longshot_options.ini and the shader and pipeline caches are unchanged.

Issues

See #1020

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). (36 fail here with and without this change; the list is in the first comment.)
  • 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. (The standing runs are interleaved; the walked route's two runs a side were made 3 hours apart, as its method line says.)
  • 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).
  • Docs updated.

🤖 Generated with Claude Code

**Type:** perf · **Risk:** medium · **Tested on:** Windows 11, RTX 4070 SUPER · **Needs:** Windows on AMD and Intel GPUs; a CPU without SSSE3 **Scope and title changed on 2026-11-18.** This pull request was opened with six pieces, its title ending "(registers as locals, vector rewrites, unchanged texture data left alone)". After review it holds the two translator pieces that carry the gain. Taken out, each with nothing measurable on current main: the FMIN / FMAX fast path, the packaged-texture-data check, the identical-copy check and the capture-buffer worker. The numbers below are this head's. ## TL;DR In Castle Town's market the game's own work takes most of a 60 fps frame, so the frame rate dips. This PR makes the translated game code faster in two ways: a function keeps its hottest console registers in local variables, and five vector instruction forms become one processor instruction each. On a Ryzen 9 9900X the game's work per frame drops from 16.6 to 14.3 ms and the market runs at 61.1 instead of 56.5 fps with the cap lifted to 90. Checked with traced runs against main, each piece also by itself, with game-free tests for the rewritten instructions, and by a tester on a Steam Deck (+7 % where the game's code is the limit). ## Breakdown - **Who it helps:** anyone whose frame rate in busy areas is limited by the CPU: Castle Town's market first of all. - **What was wrong:** the lifted code loads and stores the guest context around every instruction, and runs some vector instructions as byte loops. - **What changes:** a function's six most used guest registers and the four flags are C locals, and TBL, EXT, 128-bit vector loads, DUP and FMUL by element are one SSE instruction each. - **What does not change:** the game's patches (a function they touch keeps the context, as before), the host, the renderer, saves, options, the caches' formats. - **How it was checked:** traced runs of a recorded route through the market, main against this PR; each of the two pieces switched off by itself; a standing run; `tests/test_vbytes.py` and `tests/test_vfpx_elem.py`. - **What is still open:** Windows on AMD and Intel cards, and a CPU without SSSE3. The game's build takes 12-26 % longer (Risks). - **Risk:** medium: the change reaches every lifted function; each piece has a lift-time switch. ## Why In Castle Town's market the main thread's game work is about 16 ms of the 16.7 ms a 60 fps frame has, so every extra millisecond is a dropped frame. Part of that time is not the game's logic but how its code was translated: registers read from and written to memory around every instruction, and vector instructions spelled out byte by byte. See #1020, #1560 (a rework of the place the locals hook into, in progress). ## What changed Two changes to how the game's code is written as C. Nothing in `third_party/` is edited: both wrap the kit's functions from `nx2/`. - **Guest registers and flags as C locals** (`nx2/guest_locals.py`, `nx2/lift.py`): the kit's `A64_LOCAL_REGS` / `A64_LOCAL_FLAGS` on by default, six registers per function plus N, Z, C, V. A function the game's patches touch, one that holds an address they name, one with C spliced into it and one whose code starts below its entry (`lift_fixes` jumps to the entry from its head, over the place where the locals are loaded: `keep_entered_below`) keep the context: `oot_patches.touches` answers that per function, such a function is also written with the kit's context-flag text for every instruction (`install_plain`), and `check_patched()` stops the lift if a patched function has locals. The horse's jump blend and the moving floors' patches apply unchanged. - **Vector instructions as one SSE instruction each** (`nx2/fastvec.py`): TBL with a one-register table (PSHUFB), EXT (PALIGNR or two shifts), 128-bit vector loads, DUP by element, FMUL by element. They were byte loops through the stack; TBL has 2,995 sites in the game and EXT 29,451. - tests: `tests/test_vbytes.py` and `tests/test_vfpx_elem.py` run every rewritten form both ways against the kit's text; `tests/test_entry_below_locals.py` checks that a function entered below its first block gets no locals; `nx2/test_leaf.py` covers the locals. ## Measurements **Verdict:** faster: 12-15 % less game work a frame, measured in Castle Town's market and on Death Mountain Trail; +15 % fps where the CPU is the limit (720p: 71.6 to 82.0 in the market), +8 % on the walked market route at 4K (56.5 to 61.1), little where the GPU is the limit. Each of the two pieces shows by itself: 1.4 ms for the locals, 1.2 ms for the vector rewrites. Hardware: Windows 11 (26200), RTX 4070 SUPER 12 GB, NVIDIA 621.24, Ryzen 9 9900X, 64 GB Scene: Castle Town market by day, the second visit of a recorded route (market, castle, market; 59.5 s); 4K output, DLSS Quality (1440p internal), V-Sync on, default settings, frame rate cap 90 (a measuring setup: above the game's 60, so that the fps can show the gain) Method: fps and 1% low from present intervals (`HOS_PRESENT_TRACE`); game work a frame from `RX_VK_FRAME_TRACE` (`game_ms` + `wait_main_ms`, the median of the visit's frames); 2 runs a side; main's two were made 3 hours before this head's (the same build of main, the same settings), so not interleaved How to reproduce: a save in Castle Town, the route above, `HOS_FPS_MAX=90` Baseline: main @ 430eef4f, the base these runs were made on. The head has since been rebased (main has had renderer and build-script changes, none in the code this PR writes) and changed after review in one way that reaches the game: 26 functions whose code starts below their entry keep the context. One run of it on this route gave 61.8 fps and 13.97 ms of game work a frame, so the numbers hold. | | Before: main @ 430eef4f | After: this PR @ 826cf67c (the head before its rebase) | Δ | |---|---|---|---| | fps | 56.7 / 56.3 | 61.3 / 60.9 | +4.6 | | 1% low fps | 26.2 / 28.2 | 27.5 / 28.1 | +0.6 | | game work a frame, median | 16.60 / 16.70 ms | 14.26 / 14.58 ms | -2.23 ms | Each piece by itself (the same route and settings, one run each, on the earlier head 15c563a8, whose other pieces showed nothing measurable): | | game work a frame | fps | |---|---|---| | both pieces | 14.27 / 14.30 ms | 61.9 / 61.5 | | without the locals (`A64_LOCAL_REGS=0`, `A64_LOCAL_FLAGS=0`) | 15.64 ms | 58.7 | | without the vector rewrites (`A64_NO_VBYTES=1`, `A64_NO_VMOVES=1`, `A64_NO_VFPX_ELEM=1`) | 15.46 ms | 59.6 | Standing after a teleport to each place, 30 s measured, two runs a side in the order main, PR, main, PR. First with the GPU out of the way (1280x720 output, DLAA, uncapped, V-Sync off), then as played here (4K, DLSS Quality, cap 120): | | Before: main @ 430eef4f | After: this PR @ 826cf67c | Δ | |---|---|---|---| | 720p, Castle Town market: fps | 72.2 / 70.9 | 81.9 / 82.1 | +15 % | | 720p, Castle Town market: game work a frame | 13.47 / 13.76 ms | 11.91 / 11.82 ms | -13 % | | 720p, Death Mountain Trail: fps | 108.4 / 112.3 | 127.9 / 125.9 | +15 % | | 720p, Death Mountain Trail: game work a frame | 8.93 / 8.74 ms | 7.60 / 7.66 ms | -14 % | | 4K, Castle Town market: fps | 72.0 / 71.3 | 73.9 / 73.8 | +3 % | | 4K, Castle Town market: game work a frame | 13.07 / 13.27 ms | 11.49 / 11.71 ms | -12 % | | 4K, Death Mountain Trail: fps | 94.5 / 94.1 | 94.2 / 93.7 | 0 % | | 4K, Death Mountain Trail: game work a frame | 8.89 / 9.06 ms | 8.27 / 8.30 ms | -8 % | So the gain is there at rest too, and how much of it shows as fps depends on what limits the frame: all of it where the CPU does (720p: the game never waits for the GPU), little or none where the GPU does (4K here: the game's wait for it grows from 0.5 to 1.7 ms a frame in the market, 1.5 to 2.2 ms on the trail). A tester's Steam Deck OLED (Linux, RADV; both sides built all at `-O2`; the earlier head, which had these two pieces and four more): Death Mountain Trail under the falling rocks 17.5 to 18.8 fps (+7 %), the frame less the replay 37.9 to 34.1 ms; Castle Town's market, where the Deck's GPU limits, no difference; 8 starts and a session in the Fire Temple without a fault. ``` [hos host] report: gpu NVIDIA GeForce RTX 4070 SUPER, NVIDIA 621.24 [hos host] report: cpu AMD Ryzen 9 9900X 12-Core Processor (24 threads), 62 GB [hos host] vk: swapchain 3840x2160, 4 images, fifo (V-Sync On) run fps 1%low >20 >25 >33 | game work a frame: median main-none-1 56.7 26.2 355 59 9 | 16.60 main-none-2 56.3 28.2 411 66 9 | 16.70 slim-none-1 61.3 27.5 347 46 13 | 14.26 slim-none-2 60.9 28.1 352 50 10 | 14.58 ``` ### Works well together with Three settings `main` already has add to this change. This PR changes none of them. `HOS_KEEP_FREED_PAGES` on by default where the PC has the memory follows as a separate pull request. Whether the other two should become defaults is a question for the maintainers; their gain with this PR's code is shown here. The same route, walking, cap at 90, two runs each: | | main | with this PR's two pieces | |---|---|---| | default settings | 56.5 fps | 61.1 fps | | with `RX_VK_FRAME_GATE=0` and `RX_VK_READBACK_LATE=3980,9b040,8b040,44b040,1b580` | 58.4 fps | 65.1 fps | | frames over 20 ms, default settings | 355 / 411 | 347 / 352 | | frames over 20 ms, with the two settings | 169 / 211 | 129 / 143 | - The two settings take away waits: the game no longer waits for the renderer before its next frame, nor for GPU results it asked for. They halve the long frames on either build. In fps they give more with this PR (+4.0) than on main (+1.9): the game's frame is shorter, and without those waits that shows. - `HOS_KEEP_FREED_PAGES=1` removes the frames in which the game's main thread is blocked for a whole frame while freed memory is given back to the system: 15 to 25 a market visit down to 0, the frames over 25 ms from 29-50 to 12. It costs 0.5 to 0.7 GB of memory in use. (The rows with the two settings and the third setting's numbers were measured with the earlier head, which had these two pieces and four that changed nothing measurable.) ### Flags and settings Five lift-time switches; two are the kit's own whose default changes, three are new. Each ships on. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `A64_LOCAL_REGS` | lift time: guest registers a function keeps as C locals | 0 (the kit's default) | 6 | less context traffic in lifted code | helps: Zen 5; untested elsewhere | 6 for everyone | | `A64_LOCAL_FLAGS` | lift time: N, Z, C, V as C locals | off | on (`=0` off) | as above | as above | on | | `A64_NO_VBYTES` | lift time: `=1` keeps TBL / EXT as byte loops | (new) | unset | one SSSE3 instruction each | helps | unset | | `A64_NO_VMOVES` | lift time: `=1` keeps vector loads / DUP as the kit writes them | (new) | unset | one SSE load or shuffle | helps | unset | | `A64_NO_VFPX_ELEM` | lift time: `=1` keeps FMUL by element as the kit writes it | (new) | unset | one shuffle and multiply | helps a little | unset | ## Testing **Tested:** Windows 11, RTX 4070 SUPER, NVIDIA 621.24: the market route above with this head and with main; the build log shows the three gameplay patch sites applied and no warning. The same two pieces, with more on top, have been played by hand for over half an hour in Castle Town, the castle grounds and shops, no glitch seen. `python -I -B tests/run_all.py`: 633 passed, 36 failed, 113 skipped; every failing check also fails without this change on this PC, none is new. A tester ran the earlier head on a Steam Deck OLED (Linux, RADV): it builds, 8 starts and a minute in the Fire Temple without a crash or a fault in the log. **The Test Farm's first run** (the earlier head f862753, Linux, RTX 4070, one run a side) reported a fail on two rules: its picture was taken while Link ran, a few steps apart on the two sides (both pictures are a correct market street), and the 99th-percentile frame time of one 20 s window right after the arrival was 35.9 against 27.0 ms, the median the same (14.2 ms). No crash; its build timing is in Risks. The test asked for below stands still and runs twice a side. **Not tested:** Windows on AMD and Intel GPUs; a CPU without SSSE3 (the vector rewrites use PSHUFB and PALIGNR); areas beyond Castle Town and the castle grounds; `nx2/test_insn.py` and `nx2/test_leaf.py --calls` on this base. **Must be tested:** - Linux and Windows, any GPU: teleport to `Market_Child`, stand 30 s and measure; teleport to `DeathMountainTrail_Child`, stand 30 s and measure; uncapped, render resolution 50 %, the game's own upscaler, frame generation off; expecting no crash, the same picture as main, and a frame rate not below main's in both places: up to about 10 % above it where the CPU is the limit, about the same where the GPU is (Test Farm: @Beanstalk linux and windows) ## Risks **What could break:** a lifted function that reads a register or a flag from the context while it lives in a local (the kit's context marks, the patched functions' rule and `check_patched()` guard this); a vector rewrite on an operand form the tests do not cover. **What it costs:** the game's build takes longer, since the C with locals is more work for the lift and the compiler. The Test Farm timed it on an earlier head (Ryzen 7 5800X3D, 6 compile jobs, two builds a side in turn): 592.9 to 748.4 s (+26 %), the lift 74.6 to 95.5 s, the compile 500.0 to 634.7 s. Since then the lift's part is smaller (the plain text is made only for the functions that need it: 55 to 51 s here, 45 s without locals). A tester's Steam Deck: +16 %; here on 12 cores: +12 %. The cost is paid when the game code is built anew: every install takes it nearly in full once, at its first build with this change, and not again on updates that leave the game code as it is. **Turning it off:** each piece by its switches above, at build time: the game's code is translated again. **Compatibility:** the game's code is lifted and compiled again once after the update (the lift key holds the switches). Saves, `longshot_options.ini` and the shader and pipeline caches are unchanged. ## Issues See #1020 ## 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). (36 fail here with and without this change; the list is in the first comment.) - [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. (The standing runs are interleaved; the walked route's two runs a side were made 3 hours apart, as its method line says.) - [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] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Guest registers and flags as C locals (nx2/locals.py), TBL / EXT / vector loads / DUP / FMUL by element as one SSE instruction each (nx2/fastvec.py), scalar FMIN / FMAX with a native fast path (nx2/fastcmp.py), packaged texture data compared before it is written (host/nvn_native.c), identical copies left out in the host's memcpy and memmove (host/nn_libc.c), a capture buffer past the spares destroyed on a worker (gpu/vk/vk_memory.cpp).

Assisted-by: Claude Code
Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_01W2SAEfXdofqCNskZyveUs6
docs: the switches and the measured runs; the packaged-data log switch removed
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 5s
Website / Website on Cloudflare (pull_request_target) Has been skipped
beanstalk/approval approved by HumanBean, dyst (double-reviewed)
beanstalk/any 1/1 fail
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
f862753024
docs/development.md and gpu/vk/switches.def name the new switches; docs/tested/ has one file for each of the eight measured runs; host/nvn_native.c loses its HOS_PKG_LOG diagnostic block (off by default, not needed).

Assisted-by: Claude Code
Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_01W2SAEfXdofqCNskZyveUs6
Author
First-time contributor

Tested in game: Windows 11, RTX 4070 SUPER (NVIDIA 621.24), Ryzen 9 9900X, 4K with DLSS Quality: Castle Town market, castle grounds and back on a recorded route, four traced runs of this branch at 15c563a8 (two at default settings, two with RX_VK_FRAME_GATE=0 and RX_VK_READBACK_LATE set). No crash, no error in the log, both gameplay patches of main applied in the build; 61.7 fps against main's 56.5 with the cap at 90.

Tested in game: Windows 11, RTX 4070 SUPER (NVIDIA 621.24), Ryzen 9 9900X, 4K with DLSS Quality: Castle Town market, castle grounds and back on a recorded route, four traced runs of this branch at 15c563a8 (two at default settings, two with RX_VK_FRAME_GATE=0 and RX_VK_READBACK_LATE set). No crash, no error in the log, both gameplay patches of main applied in the build; 61.7 fps against main's 56.5 with the cap at 90.
Collaborator

Possibly related, for context:

  • PR #282 WIP: perf(vk): re-upload only the part of a texture a GPU write covered — Open Castle Town GPU texture-write upload optimization; overlapping renderer work
  • issue #597 Game: rough frame times in the Castle Town market by day as child Link on nightly 153 at 4K with DLAA — Open report of rough Castle Town market frame times
  • issue #996 Game: Huge performance hit just running short circles in specific spot of Hyrule Town Market — Open report of severe performance loss in the Castle Town market
  • issue #1072 Game: Frame rate drops to 35 FPS in some shops — Open report of low FPS in Castle Town and other shops
  • PR #1209 perf(hos): splice the host's memcpy, memset and string hooks into the lifted SDK — Recently merged host memcpy/memmove hooks; shared copy optimization area
Possibly related, for context: - PR #282 WIP: perf(vk): re-upload only the part of a texture a GPU write covered — Open Castle Town GPU texture-write upload optimization; overlapping renderer work - issue #597 Game: rough frame times in the Castle Town market by day as child Link on nightly 153 at 4K with DLAA — Open report of rough Castle Town market frame times - issue #996 Game: Huge performance hit just running short circles in specific spot of Hyrule Town Market — Open report of severe performance loss in the Castle Town market - issue #1072 Game: Frame rate drops to 35 FPS in some shops — Open report of low FPS in Castle Town and other shops - PR #1209 perf(hos): splice the host's memcpy, memset and string hooks into the lifted SDK — Recently merged host memcpy/memmove hooks; shared copy optimization area
Author
First-time contributor

@Beanstalk linux and windows amd: walk through Castle Town's market for a minute (the debug teleport to Market_Child, then from the gate across the square to the far side and back), once with this PR's defaults and once with RX_VK_FRAME_GATE=0 and RX_VK_READBACK_LATE=3980,9b040,8b040,44b040,1b580. Expecting no crash, the same picture as main, and a higher frame rate than main in both.

Walking matters here: most of this change's gain, and all of the two switches' gain, shows in motion. If the farm can only stand, a standing run is still a useful check for crashes and picture differences, but its fps will say little.

(Edited: the first version asked for standing.)

@Beanstalk linux and windows amd: walk through Castle Town's market for a minute (the debug teleport to `Market_Child`, then from the gate across the square to the far side and back), once with this PR's defaults and once with `RX_VK_FRAME_GATE=0` and `RX_VK_READBACK_LATE=3980,9b040,8b040,44b040,1b580`. Expecting no crash, the same picture as main, and a higher frame rate than main in both. Walking matters here: most of this change's gain, and all of the two switches' gain, shows in motion. If the farm can only stand, a standing run is still a useful check for crashes and picture differences, but its fps will say little. (Edited: the first version asked for standing.)
Member

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

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

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

@dyst approval of `f862753` recorded. This diff touches sensitive paths, so a second member of `BigBeans` must approve it too.
Member
Beanstalk test farm · an earlier run: commit f862753 (the newer results are in a comment below)

Commit f862753 · tier double-reviewed · approved by HumanBean, dyst (👍 on Veix's request) · dashboard

What will be tested · AI plan (gpt-6.1-terra)

The farm will compare main and the PR in child Castle Town Market, including a return visit after Hyrule Castle and scripted movement before each measurement. It will measure standing frame times and FPS, compare screenshots, and time the lift and compile stages; the gameplay portion takes about 15 minutes per tester, apart from builds. A crash, significant visual difference, FPS drop over 10%, or p99 frame-time increase over 15% fails the plan. The standing measurements do not establish the claimed movement-related speedup or isolate the individual optimizations.

  • Where: any (any PC, 1-2 reports).
  • market-revisit: from a new save (settings frame_rate_cap=1, frame_generation=0), then teleport to Market, move the stick, take the picture market-first to compare with main, measure first-visit for 20 s (after 5 s warm-up), teleport to Hyrule Castle, take the picture market-return to compare with main, measure return-visit for 30 s (after 5 s warm-up); 1 run on each side.
  • Build times: main and the PR each built 2 times, alternating, each whole in a fresh folder: the lift again (no kept lift, main's compiled objects kept); every stage timed (shader preparation is not), and the lifted C compared.
  • Measured: crashes, frame times, stutters and hitches, draws and frame rate, VRAM use.
  • The PR fails if: it crashes; or frame rate is more than 10% below main; or a picture differs from main by more than 5%; or frame time (p99) is more than 15% above main.
  • Time: about 14 min of game runs per tester (2 game starts), plus the two builds and 4 timed builds (about 80 min).

Started at 15:01 UTC.

Estimate: done in about 40 min, from the queue and the testers online now.

This diff touches sensitive paths, so it needs two members of BigBeans: nx2/fastcmp.py, nx2/fastvec.py, nx2/lift.py, nx2/locals.py, nx2/oot_patches.py, nx2/test_leaf.py

Target Reports Crash Frame p99 (ms) vs main VRAM peak (MB) vs main Result
any · 1: linux+nvidia+nvidia-proprietary+dgpu NVIDIA GeForce RTX 4070, 615.71.9 1/1 1 none 35.9 vs 27.0 (+33%) 7,594 vs 7,858 (−3%) fail

Measurements · any

Verdict: fail on any (1/1 report): market-revisit screenshot.max_diff; market-revisit first-visit.frametime_p99_ms.max_delta_pct (+32.7%) failed.

Hardware: 1: linux+nvidia+nvidia-proprietary+dgpu NVIDIA GeForce RTX 4070, 615.71.9 AMD Ryzen 7 5800X3D 8-Core Processor, 64 GB RAM
Scene: market-revisit, from a new save (frame_rate_cap=1, frame_generation=0); each cell's settings and switches as the table names them
Method: the Beanstalk test farm: main and this PR built and run on the same PC in one session, game starts alternating (ABBA); market-revisit: 1 game start a side, first-visit 20 s after 5 s warm-up, return-visit 30 s after 5 s warm-up; timed builds: main and this PR each built 2 times a cache, alternating, each a whole build in a fresh folder (lift; shader preparation not timed); each number the median of the runs, then of 1 report
How to reproduce: the farm's plan above (@Beanstalk on this PR runs it again)

Before: main @ 430eef4 After: this PR @ f862753
market-revisit · first-visit · frame rate 65.0 62.5 (−4%)
market-revisit · first-visit · frame time (p99) (ms) 27.0 35.9 (+33%)
market-revisit · first-visit · peak VRAM (MB) 7,858 7,594 (−3%)

Build times (each a median of the timed builds; caches: lift = the lift again (no kept lift, main's compiled objects kept))

Before: main @ 430eef4 After: this PR @ f862753
lift · whole build (s) 592.9 748.4 (+26%)
lift · read (s) 2.1 2.0 (−5%)
lift · lift (s) 74.6 95.5 (+28%)
lift · compile (s) 500.0 634.7 (+27%)
lift · finish (s) 16.0 16.0 (+0%)
lift · lifted C main's differs

Flags and settings

None: the plan varied no setting, switch or build option.

Markdown for the PR description
## Measurements

**Verdict:** fail on any (1/1 report): `market-revisit screenshot.max_diff`; `market-revisit first-visit.frametime_p99_ms.max_delta_pct (+32.7%)` failed.

Hardware: 1: linux+nvidia+nvidia-proprietary+dgpu `NVIDIA GeForce RTX 4070, 615.71.9` `AMD Ryzen 7 5800X3D 8-Core Processor, 64 GB RAM`  
Scene: market-revisit, from a new save (frame_rate_cap=1, frame_generation=0); each cell's settings and switches as the table names them  
Method: the Beanstalk test farm: main and this PR built and run on the same PC in one session, game starts alternating (ABBA); market-revisit: 1 game start a side, first-visit 20 s after 5 s warm-up, return-visit 30 s after 5 s warm-up; timed builds: main and this PR each built 2 times a cache, alternating, each a whole build in a fresh folder (lift; shader preparation not timed); each number the median of the runs, then of 1 report  
How to reproduce: the farm's plan above (`@Beanstalk` on this PR runs it again)

| | Before: main @ 430eef4 | After: this PR @ f862753 |
|---|---|---|
| market-revisit · first-visit · frame rate | 65.0 | 62.5 (−4%) |
| market-revisit · first-visit · frame time (p99) (ms) | 27.0 | 35.9 (+33%) |
| market-revisit · first-visit · peak VRAM (MB) | 7,858 | 7,594 (−3%) |

Build times (each a median of the timed builds; caches: lift = the lift again (no kept lift, main's compiled objects kept))

| | Before: main @ 430eef4 | After: this PR @ f862753 |
|---|---|---|
| lift · whole build (s) | 592.9 | 748.4 (+26%) |
| lift · read (s) | 2.1 | 2.0 (−5%) |
| lift · lift (s) | 74.6 | 95.5 (+28%) |
| lift · compile (s) | 500.0 | 634.7 (+27%) |
| lift · finish (s) | 16.0 | 16.0 (+0%) |
| lift · lifted C | main's | differs |

### Flags and settings

None: the plan varied no setting, switch or build option.
<!-- beanstalk:previous --> <details><summary>Beanstalk test farm · an earlier run: commit <code>f862753</code> (the newer results are in a comment below)</summary> Commit `f862753` · tier **double-reviewed** · approved by HumanBean, dyst (👍 on Veix's request) · [dashboard](https://beanstalk.magicbean.dev/prs/1576) **What will be tested** · AI plan (`gpt-6.1-terra`) The farm will compare main and the PR in child Castle Town Market, including a return visit after Hyrule Castle and scripted movement before each measurement. It will measure standing frame times and FPS, compare screenshots, and time the lift and compile stages; the gameplay portion takes about 15 minutes per tester, apart from builds. A crash, significant visual difference, FPS drop over 10%, or p99 frame-time increase over 15% fails the plan. The standing measurements do not establish the claimed movement-related speedup or isolate the individual optimizations. - **Where:** any (any PC, 1-2 reports). - **market-revisit:** from a new save (settings frame_rate_cap=1, frame_generation=0), then teleport to Market, move the stick, take the picture market-first to compare with main, measure first-visit for 20 s (after 5 s warm-up), teleport to Hyrule Castle, take the picture market-return to compare with main, measure return-visit for 30 s (after 5 s warm-up); 1 run on each side. - **Build times:** main and the PR each built 2 times, alternating, each whole in a fresh folder: the lift again (no kept lift, main's compiled objects kept); every stage timed (shader preparation is not), and the lifted C compared. - **Measured:** crashes, frame times, stutters and hitches, draws and frame rate, VRAM use. - **The PR fails if:** it crashes; or frame rate is more than 10% below main; or a picture differs from main by more than 5%; or frame time (p99) is more than 15% above main. - **Time:** about 14 min of game runs per tester (2 game starts), plus the two builds and 4 timed builds (about 80 min). Started at 15:01 UTC. **Estimate:** done in about 40 min, from the queue and the testers online now. This diff touches sensitive paths, so it needs two members of `BigBeans`: `nx2/fastcmp.py`, `nx2/fastvec.py`, `nx2/lift.py`, `nx2/locals.py`, `nx2/oot_patches.py`, `nx2/test_leaf.py` | Target | Reports | Crash | Frame p99 (ms) vs main | VRAM peak (MB) vs main | Result | | --- | --- | --- | --- | --- | --- | | any · 1: linux+nvidia+nvidia-proprietary+dgpu `NVIDIA GeForce RTX 4070, 615.71.9` | 1/1 [1](https://beanstalk.magicbean.dev/reports/rp_cc0f0b718fad5a2f) | none | 35.9 vs 27.0 (+33%) | 7,594 vs 7,858 (−3%) | fail | #### Measurements · any **Verdict:** fail on any (1/1 report): `market-revisit screenshot.max_diff`; `market-revisit first-visit.frametime_p99_ms.max_delta_pct (+32.7%)` failed. Hardware: 1: linux+nvidia+nvidia-proprietary+dgpu `NVIDIA GeForce RTX 4070, 615.71.9` `AMD Ryzen 7 5800X3D 8-Core Processor, 64 GB RAM` Scene: market-revisit, from a new save (frame_rate_cap=1, frame_generation=0); each cell's settings and switches as the table names them Method: the Beanstalk test farm: main and this PR built and run on the same PC in one session, game starts alternating (ABBA); market-revisit: 1 game start a side, first-visit 20 s after 5 s warm-up, return-visit 30 s after 5 s warm-up; timed builds: main and this PR each built 2 times a cache, alternating, each a whole build in a fresh folder (lift; shader preparation not timed); each number the median of the runs, then of 1 report How to reproduce: the farm's plan above (`@Beanstalk` on this PR runs it again) | | Before: main @ 430eef4 | After: this PR @ f862753 | |---|---|---| | market-revisit · first-visit · frame rate | 65.0 | 62.5 (−4%) | | market-revisit · first-visit · frame time (p99) (ms) | 27.0 | 35.9 (+33%) | | market-revisit · first-visit · peak VRAM (MB) | 7,858 | 7,594 (−3%) | Build times (each a median of the timed builds; caches: lift = the lift again (no kept lift, main's compiled objects kept)) | | Before: main @ 430eef4 | After: this PR @ f862753 | |---|---|---| | lift · whole build (s) | 592.9 | 748.4 (+26%) | | lift · read (s) | 2.1 | 2.0 (−5%) | | lift · lift (s) | 74.6 | 95.5 (+28%) | | lift · compile (s) | 500.0 | 634.7 (+27%) | | lift · finish (s) | 16.0 | 16.0 (+0%) | | lift · lifted C | main's | differs | ### Flags and settings None: the plan varied no setting, switch or build option. <details><summary>Markdown for the PR description</summary> ```markdown ## Measurements **Verdict:** fail on any (1/1 report): `market-revisit screenshot.max_diff`; `market-revisit first-visit.frametime_p99_ms.max_delta_pct (+32.7%)` failed. Hardware: 1: linux+nvidia+nvidia-proprietary+dgpu `NVIDIA GeForce RTX 4070, 615.71.9` `AMD Ryzen 7 5800X3D 8-Core Processor, 64 GB RAM` Scene: market-revisit, from a new save (frame_rate_cap=1, frame_generation=0); each cell's settings and switches as the table names them Method: the Beanstalk test farm: main and this PR built and run on the same PC in one session, game starts alternating (ABBA); market-revisit: 1 game start a side, first-visit 20 s after 5 s warm-up, return-visit 30 s after 5 s warm-up; timed builds: main and this PR each built 2 times a cache, alternating, each a whole build in a fresh folder (lift; shader preparation not timed); each number the median of the runs, then of 1 report How to reproduce: the farm's plan above (`@Beanstalk` on this PR runs it again) | | Before: main @ 430eef4 | After: this PR @ f862753 | |---|---|---| | market-revisit · first-visit · frame rate | 65.0 | 62.5 (−4%) | | market-revisit · first-visit · frame time (p99) (ms) | 27.0 | 35.9 (+33%) | | market-revisit · first-visit · peak VRAM (MB) | 7,858 | 7,594 (−3%) | Build times (each a median of the timed builds; caches: lift = the lift again (no kept lift, main's compiled objects kept)) | | Before: main @ 430eef4 | After: this PR @ f862753 | |---|---|---| | lift · whole build (s) | 592.9 | 748.4 (+26%) | | lift · read (s) | 2.1 | 2.0 (−5%) | | lift · lift (s) | 74.6 | 95.5 (+28%) | | lift · compile (s) | 500.0 | 634.7 (+27%) | | lift · finish (s) | 16.0 | 16.0 (+0%) | | lift · lifted C | main's | differs | ### Flags and settings None: the plan varied no setting, switch or build option. ``` </details> </details>
Member

Farm readiness review for f8627530: I’m holding the second approval. The PR still combines several translator and host changes with two renderer overrides, and the reported gain depends on movement. Please identify which pieces the Windows/Linux run is meant to validate, give the isolated evidence for each change or split the unrelated pieces, and specify a repeatable movement route and a pass condition. A standing run can provide crash and screenshot coverage.

Farm readiness review for `f8627530`: I’m holding the second approval. The PR still combines several translator and host changes with two renderer overrides, and the reported gain depends on movement. Please identify which pieces the Windows/Linux run is meant to validate, give the isolated evidence for each change or split the unrelated pieces, and specify a repeatable movement route and a pass condition. A standing run can provide crash and screenshot coverage.
Owner

@Beanstalk

@Beanstalk
Contributor

Steam Deck OLED (Linux, RADV): it builds, runs without a fault, and is about 7 % faster where the game's own code limits the frame. Where the replay and the GPU limit it, nothing moves. This PR @ f8627530 against its base, main @ 430eef4f.

Where the game's code limits: Death Mountain Trail, adult Link standing under the falling rocks (about 1,270 to 1,300 draws and 255 to 296 compute dispatches a frame), runs in the order main, PR, PR, main:

main, run 1 PR, run 1 PR, run 2 main, run 2
fps 17.70 19.33 18.33 17.36
frame 57.0 ms 52.3 ms 55.1 ms 58.2 ms
replay (render thread) 19.8 ms 19.5 ms 19.7 ms 19.6 ms
frame less replay 37.2 ms 32.8 ms 35.4 ms 38.5 ms
GPU time 27.0 ms 26.8 ms 27.0 ms 27.2 ms
  • Means: 17.5 to 18.8 fps (+7 %); the frame less the replay, which is the game's side with its waits (not this PR's game_ms: no frame trace was taken), 37.9 to 34.1 ms (-10 %). Both runs of the PR are above both runs of main; two runs a side, and two runs of one side differ by up to 1 fps, so the direction is clearer than the size.
  • The replay and the GPU time are the same on both sides: what moves is the game's side, as the PR says.

Where the replay and the GPU limit: Castle Town's market, child Link, a fixed route (three visits a run by the debug teleport, 30 s of a walk with camera swings in each, about 2,100 to 2,250 draws):

main, run 1 PR, run 1 PR, run 2 main, run 2
median frame 49.0 ms 49.0 ms 49.0 ms 49.0 ms
mean 18.6 fps 18.8 fps 19.0 fps 19.1 fps
99th percentile 174 ms 143 ms 180 ms 180 ms
frames of 100 ms or more 33 (6.4 s) 41 (7.0 s) 33 (6.9 s) 36 (7.2 s)

No difference. A wide view of about 2,190 draws, standing: 24.9 fps on main, 24.7 with the PR, the same.

Build and run:

  • The lift's own lines: locals: 16 functions with spliced code kept in the context, locals: 58 functions that hold an address the patches name kept in the context, locals: 1 functions kept in the context for the patches; 32 patched functions checked in the written C.
  • The game's build (--jobs 4, 4 cores): 5,027 s against 4,329 s for main the same morning, 16 % longer.
  • 8 starts of the PR's game, 12 teleports in each market run, the shaders prepared once: 0 fatal lines, no crash, no device loss. The caches' stamp is unchanged, as the description says: main's caches were taken as they were.

Hardware: Steam Deck OLED (AMD Custom APU 0932, Zen 2, 4 cores / 8 threads, AVX2; RADV VANGOGH, Mesa 26.2.0-devel), SteamOS 3.9.5, 16 GB, on the charger, the GPU at a manual 1600 MHz.

Builds: both built on the Deck by the Linux builder (scripts/linux/appimage.sh, then AppRun --cli --update), with LONGSHOT_CHUNK_OPT=all and a local hot list of 918 functions on both sides. So the lifted code is at -O2 everywhere in both games, which is not the default build: the gain above is what the PR adds on top of that.

Settings, the same on both sides: the handheld profile, a fixed 3D resolution of 1536x864 (HOS_RES_LOG=1: 3D scale 1.000 in every run), the game's own upscaler, headless, HOS_FPS_MAX=1000; the player's switches: RX_VK_READBACK_LATE=newest,3980, RX_VK_LATE_DEFER=0, RX_VK_READBACK_EARLY_GAP=120, HOS_RESERVE_CORE=0, RX_VK_VRAM_MB=2800, RX_VK_TEX_MAX_DIM=1024, RX_VK_TEX_SKIP_MB=4, RX_VK_LOAD=create, RX_VK_LOW_SPEC=1, RX_VK_TEX_AHEAD=1, HOS_NATIVE_ZSTD=0. This PR's three run-time switches at their defaults (on). RX_VK_FRAME_GATE unset.

Method: the two games are two sets of files swapped in one game folder, so the settings and the caches are the same files for both. Death Mountain: headless from a save, 720 presents measured once in play, the save copy put back before each run, HOS_OOT_PROTECT_HEARTS=1 on both sides (without it Link dies under the rocks about 20 s into the run and the scene changes: four runs made that way are left out). Market: every present taken from the control bridge's present events; a visit's frames are the presents of 200 draws or more between the teleport's answer and the end of the walk.

Limits:

  • Two runs a side, one PC, one resolution. At 1536x864 this APU spends about 26 ms of GPU time a frame, so a CPU-side gain is diluted; a lower resolution may show more.
  • Both games are all -O2 builds; a default build (-O1 chunks) was not measured.
  • No picture was looked at (headless), so "no visual difference" in the market is not answered here. The PR's game is now installed for play on this Deck; anything seen will be reported here.
  • This CPU has SSSE3 and AVX2: the case without them is not covered.
**Steam Deck OLED (Linux, RADV): it builds, runs without a fault, and is about 7 % faster where the game's own code limits the frame. Where the replay and the GPU limit it, nothing moves.** This PR @ f8627530 against its base, main @ 430eef4f. **Where the game's code limits: Death Mountain Trail, adult Link standing under the falling rocks** (about 1,270 to 1,300 draws and 255 to 296 compute dispatches a frame), runs in the order main, PR, PR, main: | | main, run 1 | PR, run 1 | PR, run 2 | main, run 2 | |---|---|---|---|---| | fps | 17.70 | 19.33 | 18.33 | 17.36 | | frame | 57.0 ms | 52.3 ms | 55.1 ms | 58.2 ms | | replay (render thread) | 19.8 ms | 19.5 ms | 19.7 ms | 19.6 ms | | frame less replay | 37.2 ms | 32.8 ms | 35.4 ms | 38.5 ms | | GPU time | 27.0 ms | 26.8 ms | 27.0 ms | 27.2 ms | - Means: **17.5 to 18.8 fps (+7 %)**; the frame less the replay, which is the game's side with its waits (not this PR's `game_ms`: no frame trace was taken), **37.9 to 34.1 ms (-10 %)**. Both runs of the PR are above both runs of main; two runs a side, and two runs of one side differ by up to 1 fps, so the direction is clearer than the size. - The replay and the GPU time are the same on both sides: what moves is the game's side, as the PR says. **Where the replay and the GPU limit: Castle Town's market, child Link, a fixed route** (three visits a run by the debug teleport, 30 s of a walk with camera swings in each, about 2,100 to 2,250 draws): | | main, run 1 | PR, run 1 | PR, run 2 | main, run 2 | |---|---|---|---|---| | median frame | 49.0 ms | 49.0 ms | 49.0 ms | 49.0 ms | | mean | 18.6 fps | 18.8 fps | 19.0 fps | 19.1 fps | | 99th percentile | 174 ms | 143 ms | 180 ms | 180 ms | | frames of 100 ms or more | 33 (6.4 s) | 41 (7.0 s) | 33 (6.9 s) | 36 (7.2 s) | No difference. A wide view of about 2,190 draws, standing: 24.9 fps on main, 24.7 with the PR, the same. **Build and run:** - The lift's own lines: `locals: 16 functions with spliced code kept in the context`, `locals: 58 functions that hold an address the patches name kept in the context`, `locals: 1 functions kept in the context for the patches; 32 patched functions checked in the written C`. - The game's build (`--jobs 4`, 4 cores): 5,027 s against 4,329 s for main the same morning, 16 % longer. - 8 starts of the PR's game, 12 teleports in each market run, the shaders prepared once: 0 fatal lines, no crash, no device loss. The caches' stamp is unchanged, as the description says: main's caches were taken as they were. **Hardware:** Steam Deck OLED (AMD Custom APU 0932, Zen 2, 4 cores / 8 threads, AVX2; RADV VANGOGH, Mesa 26.2.0-devel), SteamOS 3.9.5, 16 GB, on the charger, the GPU at a manual 1600 MHz. **Builds:** both built on the Deck by the Linux builder (`scripts/linux/appimage.sh`, then `AppRun --cli --update`), with `LONGSHOT_CHUNK_OPT=all` and a local hot list of 918 functions on both sides. So the lifted code is at `-O2` everywhere in both games, which is not the default build: the gain above is what the PR adds on top of that. **Settings, the same on both sides:** the handheld profile, a fixed 3D resolution of 1536x864 (`HOS_RES_LOG=1`: `3D scale 1.000` in every run), the game's own upscaler, headless, `HOS_FPS_MAX=1000`; the player's switches: `RX_VK_READBACK_LATE=newest,3980`, `RX_VK_LATE_DEFER=0`, `RX_VK_READBACK_EARLY_GAP=120`, `HOS_RESERVE_CORE=0`, `RX_VK_VRAM_MB=2800`, `RX_VK_TEX_MAX_DIM=1024`, `RX_VK_TEX_SKIP_MB=4`, `RX_VK_LOAD=create`, `RX_VK_LOW_SPEC=1`, `RX_VK_TEX_AHEAD=1`, `HOS_NATIVE_ZSTD=0`. This PR's three run-time switches at their defaults (on). `RX_VK_FRAME_GATE` unset. **Method:** the two games are two sets of files swapped in one game folder, so the settings and the caches are the same files for both. Death Mountain: headless from a save, 720 presents measured once in play, the save copy put back before each run, `HOS_OOT_PROTECT_HEARTS=1` on both sides (without it Link dies under the rocks about 20 s into the run and the scene changes: four runs made that way are left out). Market: every present taken from the control bridge's `present` events; a visit's frames are the presents of 200 draws or more between the teleport's answer and the end of the walk. **Limits:** - Two runs a side, one PC, one resolution. At 1536x864 this APU spends about 26 ms of GPU time a frame, so a CPU-side gain is diluted; a lower resolution may show more. - Both games are all `-O2` builds; a default build (`-O1` chunks) was not measured. - No picture was looked at (headless), so "no visual difference" in the market is not answered here. The PR's game is now installed for play on this Deck; anything seen will be reported here. - This CPU has SSSE3 and AVX2: the case without them is not covered.
Contributor

Follow-up from play, as said above: a short session with this PR's game on the same Steam Deck OLED, in Game Mode (the log names the build, v2.1.0-rc.3-806-gf8627530): the Fire Temple as adult Link, about a minute in play, 360 to 1,120 draws a frame. Nothing odd in the picture, no crash, 0 fatal lines in the log.

That is one dungeon for one minute: it says the build plays there, not that every area was looked at. The frame rate is already good in that place, so no gain was looked for in this session; the numbers above stay the measurement.

Follow-up from play, as said above: a short session with this PR's game on the same Steam Deck OLED, in Game Mode (the log names the build, `v2.1.0-rc.3-806-gf8627530`): the Fire Temple as adult Link, about a minute in play, 360 to 1,120 draws a frame. Nothing odd in the picture, no crash, 0 fatal lines in the log. That is one dungeon for one minute: it says the build plays there, not that every area was looked at. The frame rate is already good in that place, so no gain was looked for in this session; the numbers above stay the measurement.
Veix force-pushed perf/market-game-work from f862753024
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 5s
Website / Website on Cloudflare (pull_request_target) Has been skipped
beanstalk/approval approved by HumanBean, dyst (double-reviewed)
beanstalk/any 1/1 fail
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 cb7449eefc
Some checks failed
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 12s
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-18 16:36:05 +00:00
Compare
Member

Beanstalk test farm

Commit 26c554e · tier untrusted · approved by nobody yet · dashboard

This diff touches sensitive paths, so it needs two members of BigBeans: nx2/fastvec.py, nx2/guest_locals.py, nx2/lift.py, nx2/oot_patches.py, nx2/ran_funcs.txt, nx2/test_leaf.py

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

<!-- beanstalk:sticky --> ### Beanstalk test farm Commit `26c554e` · tier **untrusted** · approved by nobody yet · [dashboard](https://beanstalk.magicbean.dev/prs/1576) This diff touches sensitive paths, so it needs two members of `BigBeans`: `nx2/fastvec.py`, `nx2/guest_locals.py`, `nx2/lift.py`, `nx2/oot_patches.py`, `nx2/ran_funcs.txt`, `nx2/test_leaf.py` A member of `BigBeans` can review this commit and comment `@Beanstalk` to test it.
Veix changed title from WIP: perf: less game work a frame in Castle Town (registers as locals, vector rewrites, unchanged texture data left alone) to WIP: perf: less game work a frame in Castle Town (registers as locals, vector rewrites) 2026-11-18 16:37:00 +00:00
Author
First-time contributor

Thanks for the review, all three points were fair.

One topic now. The head (cb7449ee, on main 876dc360) is the two translator changes only: registers and flags as C locals, and the vector rewrites. The two host checks, the capture-buffer worker and the FMIN / FMAX fast path are out.

Each piece by itself (Castle Town market, the recorded route, default settings, cap lifted to 90):

Build game work a frame fps
main @ 430eef4f 16.60 / 16.70 ms 56.7 / 56.3
without registers as locals 15.64 ms 58.7
without the vector rewrites 15.46 ms 59.6
this head: both 14.26 / 14.58 ms 61.3 / 60.9

The four pieces that left changed nothing measurable on current main (14.25 to 14.41 ms with any one of them off).

The gain does not depend on movement; that sentence of mine was wrong. Standing after a teleport: the market 13.65 to 11.73 ms of game work, Death Mountain Trail 9.15 to 8.17 ms.

The switches are out of the test and out of this PR. The description shows what they add to it.

The test is in the request below: two teleports, standing, a pass condition.

The farm's first run measured a moving, still-loading scene once a side: its picture was taken while Link ran (both pictures are correct, a few steps apart), and the median frame was the same. Its build timing is solid and in the description now: the build takes 26 % longer there with the locals (12 % here, 16 % on p0lux's Steam Deck; thanks for those runs).

Measured and written with the help of an AI coding agent.

Thanks for the review, all three points were fair. **One topic now.** The head (`cb7449ee`, on main 876dc360) is the two translator changes only: registers and flags as C locals, and the vector rewrites. The two host checks, the capture-buffer worker and the FMIN / FMAX fast path are out. **Each piece by itself** (Castle Town market, the recorded route, default settings, cap lifted to 90): | Build | game work a frame | fps | |---|---|---| | main @ 430eef4f | 16.60 / 16.70 ms | 56.7 / 56.3 | | without registers as locals | 15.64 ms | 58.7 | | without the vector rewrites | 15.46 ms | 59.6 | | this head: both | 14.26 / 14.58 ms | 61.3 / 60.9 | The four pieces that left changed nothing measurable on current main (14.25 to 14.41 ms with any one of them off). **The gain does not depend on movement;** that sentence of mine was wrong. Standing after a teleport: the market 13.65 to 11.73 ms of game work, Death Mountain Trail 9.15 to 8.17 ms. **The switches are out of the test and out of this PR.** The description shows what they add to it. **The test** is in the request below: two teleports, standing, a pass condition. **The farm's first run** measured a moving, still-loading scene once a side: its picture was taken while Link ran (both pictures are correct, a few steps apart), and the median frame was the same. Its build timing is solid and in the description now: the build takes 26 % longer there with the locals (12 % here, 16 % on p0lux's Steam Deck; thanks for those runs). Measured and written with the help of an AI coding agent.
Author
First-time contributor

@Beanstalk linux and windows: teleport to Market_Child, stand 30 s and measure; then teleport to DeathMountainTrail_Child, stand 30 s and measure. Uncapped, render resolution 50 %, the game's own upscaler, frame generation off. Expecting no crash, the same picture as main, and a frame rate not below main's in both places: up to about 10 % above it where the CPU is the limit, about the same where the GPU is.

@Beanstalk linux and windows: teleport to `Market_Child`, stand 30 s and measure; then teleport to `DeathMountainTrail_Child`, stand 30 s and measure. Uncapped, render resolution 50 %, the game's own upscaler, frame generation off. Expecting no crash, the same picture as main, and a frame rate not below main's in both places: up to about 10 % above it where the CPU is the limit, about the same where the GPU is.
Member

@Veix only members of BigBeans can start the farm.

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

@Veix only members of `BigBeans` can start the farm. ~~One of them can approve this request by reacting 👍 to it or to this comment.~~ This request was for `cb7449e`, and the PR has changed since (`34e3d47`), so a 👍 no longer approves it. Comment `@Beanstalk` again to ask for the new commit.
Veix changed title from WIP: perf: less game work a frame in Castle Town (registers as locals, vector rewrites) to perf: less game work a frame in Castle Town (registers as locals, vector rewrites) 2026-11-18 16:46:40 +00:00
dyst left a comment

Verdict: Request changes. The two translator pieces are well built and the gain is real and measured, but with locals on, the functions whose code starts below their entry skip their own register and flag loads: lift_fixes' entry goto lands above the locals' declarations, so those functions run on whatever the stack holds.

For a player this takes 12-15% off the game's own work per frame and up to +15% fps where the CPU limits the frame. It makes the code better on net: the vector rewrites are tight, exact and tested, and asking the patches which functions they touch is a clear improvement on keeping a list by hand. The costs are a build 12-26% longer, measured and stated, and the bug below.

Reviewed: cb7449ee against its base 876dc360. Read in full: nx2/locals.py, nx2/fastvec.py, the changes to nx2/lift.py, nx2/oot_patches.py and nx2/test_leaf.py, nx2/lift_fixes.py's emit_function (unchanged here, but it wraps this PR's emit), the kit's localize_regs, recomp_ldp64 and a64_vfpx_mul32, and the docstrings and word lists of tests/test_vbytes.py and tests/test_vfpx_elem.py. Only skimmed: tests/vbytes_test.c, tests/vfpx_elem_test.c, docs/tested/. Nothing run: a code review.
Fixed in this review: nothing.
Checked and fine:

  • TBL: PSHUFB with the index plus 0x70, saturated, gives 0 exactly for indices of 16 and up. The 8-byte form loads the low half, then clears the top.
  • EXT: PALIGNR's operand order is right for EXT16. EXT8's shifts are right at every imm 0-7, and imm is a literal from the regex.
  • FMUL by element: goes through the same a64_vfpx_mul32_v fast path and the same a64_vfpx_mul32_lanes fallback as the kit's 4-lane FMUL, with the element broadcast. The KIT_MUL32 text guard stops the lift if the kit changes.
  • 128-bit vector loads: recomp_ldp64 is two plain 8-byte loads at a and a + 8, so one 16-byte load reads the same bytes. DUP's widths and Q handling match.
  • Every helper reads its sources before it writes Vd, so Vd = Vn or Vm is safe. The non-SSSE3 fallbacks match.
  • Patched functions keep the context:
    • keep_mentioned catches the patches that carry no (nx2/oot_patches.py mark, such as the dynamic-resolution branch, by their label's address;
    • install_plain gives them the plain FCMP text, so the horse jump patch still finds a64_fcmp32(c,...);
    • check_patched stops the lift if a marked function got locals.
  • A64_LOCAL_FLAGS=0 now means off; the kit took any value as on.
  • fastfp.localize_regs and fastfp.local_regs, imported by name, are both replaced, so fastfp's copy of emit_function follows.

Blocking (to change before merge)

  1. nx2/lift.py:57-61: lift_fixes.install() runs after local_regs.install() and install_plain(), so its emit_function wraps theirs.
    • What goes wrong: for a function whose code starts below its entry (min(body) != e, 26 of them in a lift of OoT), it inserts goto L_<entry>; right after the head (nx2/lift_fixes.py:134-137). But localize_regs has already put uint64_t x19_ = c->x[19], ...; and uint8_t fn_ = c->n, ...; there. The goto jumps over those initialisers: legal C, but the locals are indeterminate.
    • A concrete case: a function that keeps x19 in a local reaches its first c->x[19] = x19_; write-back (before a call, or at its return) and hands its caller a garbage callee-saved register.
    • Why the tests miss it: nx2/test_leaf.py doesn't build that shape, and the game may run through these functions rarely.
    • The fix: the simplest on main's structure is for lift_fixes' emit_function to insert its goto after the locals' declaration lines (they start with uint64_t x or uint8_t fn_), or to put these functions in no_local. #1587 fixes the same bug for #1469 over #1560's nx2/emit.py: the head lines go in before localize_regs declares the locals. A game-free test for it is in #1587 (tests/test_lift_entry_local_regs.py), and its idea fits here too: lift a function entered below its first block with locals on, and check that the declarations come before the goto.

Suggestions (the author may take or leave)

  • Lift time: install_plain's op_text runs the kit's op_text twice for every instruction (the second time with local flags off), though only the ~75 functions in no_local ever read the plain text. That likely accounts for most of the lift's +28% on the farm (74.6 → 95.5 s). Computing the plain text only when a no_local function asks for it (_Plain.__getitem__ calling op_text with flags off on the raw text) would give most of it back.
  • The module's name: nx2/locals.py, imported as local_regs, sits next to a64_lift.local_regs(), a function, and a module named locals reads like the builtin. Something like nx2/guest_locals.py would be clearer.
  • The weaker check: nx2/test_leaf.py no longer compares x9-x15 with locals on. That matches the kit's write-back (the scratch registers aren't stored at a return) and the AAPCS64. A comment saying it rests on no caller reading x9-x15 after a call would keep the next reader from treating it as a bug.

Questions

  • The farm's run on f862753 failed on p99, 35.9 ms against 27.0 (+33%), and on a picture difference (Linux, RTX 4070, Ryzen 7 5800X3D). The explanation, a scene still loading and a picture a few steps apart, is plausible but not shown. Your Windows 1% lows are fine. Will the farm's run on this head be the answer before this is called ready?

Testing: Windows RTX 4070 SUPER and Ryzen 9 9900X runs by the author, traced, 2 a side and each piece alone; p0lux's Steam Deck OLED, +7% where the game's code limits, with -O2 builds on both sides; the farm's earlier run (above). Missing: the farm on this head, AMD and Intel GPUs on Windows, and a CPU without SSSE3 (the fallbacks look right on reading). For what it's worth, on a Ryzen 9 3900X here, #1469's registers alone, without the flags, were within noise (+0.2% and +1.6% over 3 rounds), which is consistent with your split: the flags carry a good part of the locals' 1.4 ms.
Overlaps and merge order:

  • #1469: the same feature. This PR covers more (the flags, the patches asked), so one of the two should close.
  • #1560: replaces fastfp's copy of emit_function with hook points, and conflicts with this PR's wrappers. Whichever merges second ports onto the other; #1560's lift is byte-identical, so porting this onto it is mechanical.
  • #1587: the entry-goto fix over #1560.
  • #1617: store marks by a GPU-page bitmap. It touches different files and work (the marks on stores, not instructions), so the two should add up; neither has been measured with the other.
**Verdict: Request changes.** The two translator pieces are well built and the gain is real and measured, but with locals on, the functions whose code starts below their entry skip their own register and flag loads: `lift_fixes`' entry goto lands above the locals' declarations, so those functions run on whatever the stack holds. For a player this takes 12-15% off the game's own work per frame and up to +15% fps where the CPU limits the frame. It makes the code better on net: the vector rewrites are tight, exact and tested, and asking the patches which functions they touch is a clear improvement on keeping a list by hand. The costs are a build 12-26% longer, measured and stated, and the bug below. **Reviewed:** `cb7449ee` against its base `876dc360`. Read in full: `nx2/locals.py`, `nx2/fastvec.py`, the changes to `nx2/lift.py`, `nx2/oot_patches.py` and `nx2/test_leaf.py`, `nx2/lift_fixes.py`'s `emit_function` (unchanged here, but it wraps this PR's emit), the kit's `localize_regs`, `recomp_ldp64` and `a64_vfpx_mul32`, and the docstrings and word lists of `tests/test_vbytes.py` and `tests/test_vfpx_elem.py`. Only skimmed: `tests/vbytes_test.c`, `tests/vfpx_elem_test.c`, `docs/tested/`. Nothing run: a code review. **Fixed in this review:** nothing. **Checked and fine:** - **TBL:** PSHUFB with the index plus 0x70, saturated, gives 0 exactly for indices of 16 and up. The 8-byte form loads the low half, then clears the top. - **EXT:** PALIGNR's operand order is right for EXT16. EXT8's shifts are right at every imm 0-7, and imm is a literal from the regex. - **FMUL by element:** goes through the same `a64_vfpx_mul32_v` fast path and the same `a64_vfpx_mul32_lanes` fallback as the kit's 4-lane FMUL, with the element broadcast. The `KIT_MUL32` text guard stops the lift if the kit changes. - **128-bit vector loads:** `recomp_ldp64` is two plain 8-byte loads at `a` and `a + 8`, so one 16-byte load reads the same bytes. DUP's widths and Q handling match. - **Every helper reads its sources before it writes Vd,** so Vd = Vn or Vm is safe. The non-SSSE3 fallbacks match. - **Patched functions keep the context:** - `keep_mentioned` catches the patches that carry no `(nx2/oot_patches.py` mark, such as the dynamic-resolution branch, by their label's address; - `install_plain` gives them the plain FCMP text, so the horse jump patch still finds `a64_fcmp32(c,...)`; - `check_patched` stops the lift if a marked function got locals. - `A64_LOCAL_FLAGS=0` now means off; the kit took any value as on. - `fastfp.localize_regs` and `fastfp.local_regs`, imported by name, are both replaced, so fastfp's copy of `emit_function` follows. **Blocking** (to change before merge) 1. `nx2/lift.py:57-61`: `lift_fixes.install()` runs after `local_regs.install()` and `install_plain()`, so its `emit_function` wraps theirs. - **What goes wrong:** for a function whose code starts below its entry (`min(body) != e`, 26 of them in a lift of OoT), it inserts `goto L_<entry>;` right after the head (`nx2/lift_fixes.py:134-137`). But `localize_regs` has already put `uint64_t x19_ = c->x[19], ...;` and `uint8_t fn_ = c->n, ...;` there. The goto jumps over those initialisers: legal C, but the locals are indeterminate. - **A concrete case:** a function that keeps x19 in a local reaches its first `c->x[19] = x19_;` write-back (before a call, or at its return) and hands its caller a garbage callee-saved register. - **Why the tests miss it:** `nx2/test_leaf.py` doesn't build that shape, and the game may run through these functions rarely. - **The fix:** the simplest on main's structure is for `lift_fixes`' `emit_function` to insert its goto after the locals' declaration lines (they start with ` uint64_t x` or ` uint8_t fn_`), or to put these functions in `no_local`. #1587 fixes the same bug for #1469 over #1560's `nx2/emit.py`: the head lines go in before `localize_regs` declares the locals. A game-free test for it is in #1587 (`tests/test_lift_entry_local_regs.py`), and its idea fits here too: lift a function entered below its first block with locals on, and check that the declarations come before the goto. **Suggestions** (the author may take or leave) - **Lift time:** `install_plain`'s `op_text` runs the kit's `op_text` twice for every instruction (the second time with local flags off), though only the ~75 functions in `no_local` ever read the plain text. That likely accounts for most of the lift's +28% on the farm (74.6 → 95.5 s). Computing the plain text only when a `no_local` function asks for it (`_Plain.__getitem__` calling `op_text` with flags off on the raw text) would give most of it back. - **The module's name:** `nx2/locals.py`, imported as `local_regs`, sits next to `a64_lift.local_regs()`, a function, and a module named `locals` reads like the builtin. Something like `nx2/guest_locals.py` would be clearer. - **The weaker check:** `nx2/test_leaf.py` no longer compares x9-x15 with locals on. That matches the kit's write-back (the scratch registers aren't stored at a return) and the AAPCS64. A comment saying it rests on no caller reading x9-x15 after a call would keep the next reader from treating it as a bug. **Questions** - **The farm's run on `f862753`** failed on p99, 35.9 ms against 27.0 (+33%), and on a picture difference (Linux, RTX 4070, Ryzen 7 5800X3D). The explanation, a scene still loading and a picture a few steps apart, is plausible but not shown. Your Windows 1% lows are fine. Will the farm's run on this head be the answer before this is called ready? **Testing:** Windows RTX 4070 SUPER and Ryzen 9 9900X runs by the author, traced, 2 a side and each piece alone; p0lux's Steam Deck OLED, +7% where the game's code limits, with `-O2` builds on both sides; the farm's earlier run (above). Missing: the farm on this head, AMD and Intel GPUs on Windows, and a CPU without SSSE3 (the fallbacks look right on reading). For what it's worth, on a Ryzen 9 3900X here, #1469's registers alone, without the flags, were within noise (+0.2% and +1.6% over 3 rounds), which is consistent with your split: the flags carry a good part of the locals' 1.4 ms. **Overlaps and merge order:** - [#1469](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1469): the same feature. This PR covers more (the flags, the patches asked), so one of the two should close. - [#1560](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1560): replaces fastfp's copy of `emit_function` with hook points, and conflicts with this PR's wrappers. Whichever merges second ports onto the other; #1560's lift is byte-identical, so porting this onto it is mechanical. - [#1587](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1587): the entry-goto fix over #1560. - [#1617](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1617): store marks by a GPU-page bitmap. It touches different files and work (the marks on stores, not instructions), so the two should add up; neither has been measured with the other.
nx2/lift.py Outdated
@ -51,2 +54,4 @@
insn.install()
fastvec.install() # (around the kit's vectorize_fpx, op_text and fpx_header)
fastfp.install() # (before lift_fixes and poll wrap emit_function: theirs go around this one)
local_regs.install(oot_patches.touches) # (around fastfp's emit_function and the kit's localize_regs; the defaults; the patches asked)
Member

lift_fixes.install() runs after this, so its emit_function wraps the locals': its entry goto (lift_fixes.py:137) lands right after the head, above localize_regs' declarations, and the 26 functions entered below their first block skip their register and flag loads. See the review.

lift_fixes.install() runs after this, so its emit_function wraps the locals': its entry goto (lift_fixes.py:137) lands right after the head, above localize_regs' declarations, and the 26 functions entered below their first block skip their register and flag loads. See the review.
Veix force-pushed perf/market-game-work from cb7449eefc
Some checks failed
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 12s
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 34e3d4769f
Some checks failed
beanstalk/approval waiting for a BigBean's 👍 on the request
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 5s
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-18 17:52:59 +00:00
Compare
Author
First-time contributor

Thanks for the careful review. The blocking point is fixed and the suggestions are taken; head 34e3d476, on main c507b98c.

Blocking: the entry goto over the locals' loads. Confirmed here: 26 functions in the lifted code had the goto right above their declarations. A function whose code starts below its entry now keeps the context (keep_entered_below() in nx2/guest_locals.py, into no_local), so lift_fixes stays as it is. After it, a scan of all 294,522 lifted functions finds none with a load behind the goto, and the Market route is unchanged (61.8 fps, 13.97 ms of game work). tests/test_entry_below_locals.py checks the rule without the game, and that it is the same condition lift_fixes writes its goto under.

Build time. Your suggestion is in: the plain text is made only when a no_local function asks. The lifted C is byte-identical and the lift step went from 55 to 51 s here. Most of the cost is the compile and stays. It is paid when the game code is built anew: every install takes it nearly in full once, at its first build with this change, and not again on updates that leave the game code as it is. The hot list that is being looked at for -O2 could later serve lifter changes like this one too: locals only for the functions that run often would keep most of the gain for a fraction of the compile.

Name and comment. nx2/locals.py is nx2/guest_locals.py; test_leaf.py says why x9-x15 are not compared.

The farm. Yes: its run on this head is meant to be the answer. The farm request, posted again for this head since a push voids the earlier one, asks for a standing test, two runs a side, so that neither the picture nor a single window decides it.

Measured and written with the help of an AI coding agent.

Thanks for the careful review. The blocking point is fixed and the suggestions are taken; head `34e3d476`, on main `c507b98c`. **Blocking: the entry goto over the locals' loads.** Confirmed here: 26 functions in the lifted code had the goto right above their declarations. A function whose code starts below its entry now keeps the context (`keep_entered_below()` in `nx2/guest_locals.py`, into `no_local`), so `lift_fixes` stays as it is. After it, a scan of all 294,522 lifted functions finds none with a load behind the goto, and the Market route is unchanged (61.8 fps, 13.97 ms of game work). `tests/test_entry_below_locals.py` checks the rule without the game, and that it is the same condition `lift_fixes` writes its goto under. **Build time.** Your suggestion is in: the plain text is made only when a `no_local` function asks. The lifted C is byte-identical and the lift step went from 55 to 51 s here. Most of the cost is the compile and stays. It is paid when the game code is built anew: every install takes it nearly in full once, at its first build with this change, and not again on updates that leave the game code as it is. The hot list that is being looked at for `-O2` could later serve lifter changes like this one too: locals only for the functions that run often would keep most of the gain for a fraction of the compile. **Name and comment.** `nx2/locals.py` is `nx2/guest_locals.py`; `test_leaf.py` says why x9-x15 are not compared. **The farm.** Yes: its run on this head is meant to be the answer. The farm request, posted again for this head since a push voids the earlier one, asks for a standing test, two runs a side, so that neither the picture nor a single window decides it. Measured and written with the help of an AI coding agent.
Author
First-time contributor

@Beanstalk linux and windows: teleport to Market_Child, stand 30 s and measure; then teleport to DeathMountainTrail_Child, stand 30 s and measure. Uncapped, render resolution 50 %, the game's own upscaler, frame generation off. Expecting no crash, the same picture as main, and a frame rate not below main's in both places: up to about 10 % above it where the CPU is the limit, about the same where the GPU is.

@Beanstalk linux and windows: teleport to `Market_Child`, stand 30 s and measure; then teleport to `DeathMountainTrail_Child`, stand 30 s and measure. Uncapped, render resolution 50 %, the game's own upscaler, frame generation off. Expecting no crash, the same picture as main, and a frame rate not below main's in both places: up to about 10 % above it where the CPU is the limit, about the same where the GPU is.
Member

@Veix only members of BigBeans can start the farm.

One of them can approve this request by reacting 👍 to it or to this comment. This request was for 34e3d47, and the PR has changed since (26c554e), so a 👍 no longer approves it. Comment @Beanstalk again to ask for the new commit.

@Veix only members of `BigBeans` can start the farm. ~~One of them can approve this request by reacting 👍 to it or to this comment.~~ This request was for `34e3d47`, and the PR has changed since (`26c554e`), so a 👍 no longer approves it. Comment `@Beanstalk` again to ask for the new commit.
futondestroyer left a comment

Verdict: Request changes. The below-entry fix addresses the earlier review. The current head still has a packed-flags correctness case and test runners that fail to cover the claimed Linux and baseline x86-64 paths.

Reviewed 34e3d476 against c507b98c, including the new lifter paths, the entry exclusion, vector fixtures, and performance records. No source changes pushed.

  1. nx2/guest_locals.py:125. Inherited A64_PACKED_FLAGS=1 now conflicts with local flags enabled by default. The kit folds CMP's writes into a64_set_nzcv(c, …) before localizing, so the helper updates the context while the following B.EQ can read the entry value of local Z. With incoming Z clear and equal operands, it can miss the branch. Preserve the explicit packed mode by keeping flags in the context when it is selected, or update the localized flags correctly. Add an actual emitted CMP/B.EQ case.
  2. tests/vbytes_test.c:11 and tests/vfpx_elem_test.c:15 include Win32 headers and use Win32 APIs unconditionally, while the scripts are discovered on Linux x86-64. Make those fixtures portable. Also gate the x86-64-v2 and v3 binaries on the host ISA before executing them. The vector runner currently runs those variants before the SSE2 baseline.
  3. nx2/test_leaf.py:66. This validation path installs the existing hooks but misses the new fastvec and guest-local passes and their entry exclusion. Share the production emission setup, or correct what the test claims and provide an emitted-function differential result from the production path.

Independent Windows checks: the four entry tests, the vector differential test with 1,000 random cases per instruction, and the FMUL differential sweep and random checks passed at the exact head. The compiler exercised native, x86-64-v3, and x86-64-v2 on a CPU that supports them. This host has no Linux test environment. The results do not cover the packed-flags combination or a CPU without SSSE3.

Performance evidence: please add a warm interleaved Market comparison at this exact head and publish p99 alongside game work per frame. The headline pair is from earlier commits, and the previous farm run had a p99 and image regression on an earlier head. Keep those results attached to their revisions when evaluating the current change.

PR #1560 changes the same emitter hook structure. The second branch to land needs to recheck the wrappers and their order.

**Verdict: Request changes.** The below-entry fix addresses the earlier review. The current head still has a packed-flags correctness case and test runners that fail to cover the claimed Linux and baseline x86-64 paths. **Reviewed** `34e3d476` against `c507b98c`, including the new lifter paths, the entry exclusion, vector fixtures, and performance records. No source changes pushed. 1. `nx2/guest_locals.py:125`. Inherited `A64_PACKED_FLAGS=1` now conflicts with local flags enabled by default. The kit folds CMP's writes into `a64_set_nzcv(c, …)` before localizing, so the helper updates the context while the following B.EQ can read the entry value of local Z. With incoming Z clear and equal operands, it can miss the branch. Preserve the explicit packed mode by keeping flags in the context when it is selected, or update the localized flags correctly. Add an actual emitted CMP/B.EQ case. 2. `tests/vbytes_test.c:11` and `tests/vfpx_elem_test.c:15` include Win32 headers and use Win32 APIs unconditionally, while the scripts are discovered on Linux x86-64. Make those fixtures portable. Also gate the x86-64-v2 and v3 binaries on the host ISA before executing them. The vector runner currently runs those variants before the SSE2 baseline. 3. `nx2/test_leaf.py:66`. This validation path installs the existing hooks but misses the new `fastvec` and guest-local passes and their entry exclusion. Share the production emission setup, or correct what the test claims and provide an emitted-function differential result from the production path. **Independent Windows checks:** the four entry tests, the vector differential test with 1,000 random cases per instruction, and the FMUL differential sweep and random checks passed at the exact head. The compiler exercised native, x86-64-v3, and x86-64-v2 on a CPU that supports them. This host has no Linux test environment. The results do not cover the packed-flags combination or a CPU without SSSE3. **Performance evidence:** please add a warm interleaved Market comparison at this exact head and publish p99 alongside game work per frame. The headline pair is from earlier commits, and the previous farm run had a p99 and image regression on an earlier head. Keep those results attached to their revisions when evaluating the current change. [PR #1560](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1560) changes the same emitter hook structure. The second branch to land needs to recheck the wrappers and their order.
@ -0,0 +122,4 @@
return
_installed = True
import fastfp
a64_lift.local_regs = fastfp.local_regs = local_regs
Member

Packed NZCV updates the context, while a later conditional branch can read the stale local flags. Please gate packed mode or localize its update too.

Packed NZCV updates the context, while a later conditional branch can read the stale local flags. Please gate packed mode or localize its update too.
@ -0,0 +8,4 @@
#include "a64.h"
#include <stdio.h>
#include <stdlib.h>
#include <windows.h>
Member

This fixture is auto-discovered on Linux x86-64 and needs a non-Win32 path.

This fixture is auto-discovered on Linux x86-64 and needs a non-Win32 path.
perf(lift): registers and flags as locals only in the functions play runs
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
beanstalk/approval changed since the request: ask again
CI / Conventional Commit title (pull_request) Successful in 14s
PR description / Description follows the template (pull_request_target) Successful in 18s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 18s
CI / Workflow lint (actionlint) (pull_request) Successful in 19s
Third-party parts / As their notes say (pull_request) Successful in 20s
26c554ec4d
nx2/ran_funcs.txt names the 77,725 lifted functions a 100-minute play
session ran (scripts/coverage/cover.py, issue #362; addresses only).
The rest keep their registers and flags in the context, as main writes
them: about 58% of the lifted C's estimated compile is for functions
the list does not hold, and locals there cost compile time and give
nothing. A64_LOCAL_FUNCS=all gives every function locals.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
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
beanstalk/approval changed since the request: ask again
CI / Conventional Commit title (pull_request) Successful in 14s
PR description / Description follows the template (pull_request_target) Successful in 18s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 18s
CI / Workflow lint (actionlint) (pull_request) Successful in 19s
Third-party parts / As their notes say (pull_request) Successful in 20s
This pull request doesn't have enough approvals yet. 0 of 1 approvals granted.
This branch is out-of-date with the base branch
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'perf/market-game-work:Veix-perf/market-game-work'
git switch 'Veix-perf/market-game-work'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
7 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!1576
No description provided.