Files
Triforce-Source/docs/development.md
ruckus7382sfgsgdf 6f338c8f56 Triforce v0.5.0
In-game mods (GameBanana browser, search and installs, with the Mask Salesman), code-patch and cheat mods, the devs' test18 to test45 work (full performance overlay, frame pacing on, steady frame rate, save export and import, bug capture, new options rows, Setup's Mods page and Add to Steam), occlusion queries and new defaults, Auto resolution that scales, replay helper threads and robust buffers off by default, the options in sections.
2026-11-17 22:40:50 -06:00

126 KiB

Hookshot (oot-recomp)

Hookshot is the port's name (as Skybound is TOTKPort's and BlueShell is mkw-recomp's); the maintainer's repository folder stays oot-recomp. The game builds as hookshot.exe + hookshot_vk.dll (hookshot + hookshot_vk.so on Linux).

A static recompilation of the Switch 2 The Legend of Zelda: Ocarina of Time remake to native x86-64 Windows and Linux: the game's code lifted to C (NotRexed's a64-kit, Rexcomp's AArch64 kit), the Horizon OS and NVN2 implemented natively, the GPU work replayed on Vulkan. It is a fork of mkw-recomp (..\mkw-recomp, Mario Kart World), whose paths it keeps so MKW's fixes apply here.

No game files are in this repository. The dump is read where it lies (work/dump.txt); everything made from it (modules, image, lifted C, builds, runs) goes to work/, which git ignores.

Status: the game plays; the README's status table says how far. The design, its stages and the lessons carried over from MKW: design.md.

Use

Requirements: Python 3 with pip install -r requirements.txt (lz4, numpy, capstone, unicorn 2.1, zstandard, and the button-prompt packages); a compiler: on Windows llvm-mingw (HOOKSHOT_MINGW, or an llvm-mingw folder in the clone), else emsdk's clang at C:\emsdk (or EMSDK) with Visual Studio's C++ tools; on Linux clang and lld. For the Vulkan back end: distro Vulkan / SPIR-V / VMA headers under /usr, or HOOKSHOT_VULKAN_HEADERS / HOOKSHOT_SPIRV_HEADERS / HOOKSHOT_VMA_HEADERS, or a CPM package cache (RX_CPM, else cpm in the clone, else the old caches in mkw-recomp's work/eg or ..\Eglantine\.cache\cpm). Without those the standalone build stops. CONTRIBUTING.md has the rest.

Run everything with python -I from this folder.

Command What
python -I nx2/nup.py <file.nup> --extract work/dump the .nup dump package to work/dump/exefs + romfs (newest title; ZBIC NSOs made plain by nx2/unpack.py)
python -I nx2/dump.py --dump <folder with exefs/ and romfs/> --set what the dump is (Switch 1 or 2, ids, modules, SDK, NVN); --set records it in work/dump.txt
python -I nx2/lift.py [--write] image + discovery + coverage (work/image/coverage.txt); --write emits the C to work/gen
python -I nx2/census.py --nx2 instruction census per module, after the Switch 2 forms
python -I nx2/test_insn.py [--per 6 --states 12] every instruction form the game uses, Unicorn vs lifted C
python -I nx2/test_leaf.py [--count 3000 --states 4] [--calls] random whole functions (or call trees), Unicorn vs recompiled native code on the real image
python -I nx2/lift.py --standalone --write then python -I nx2/build.py --standalone --jobs 4 the standalone game: work/sa/build/hookshot.exe + hookshot_vk.dll
powershell -File scripts/run-vk.ps1 [-Window] [-Seconds 120] [-Name x] a muted test run on Vulkan, with screenshots in work/runs/<name>/shots
python -I scripts/prof.py <stacks file> a profile sampled with HOS_PROFILE=<seconds> + HOS_SAMPLE=<thread> + HOS_SAMPLE_FILE=<stacks file> (the sampler runs only with HOS_PROFILE set), named from the linker maps

The dump can also come from OOT_DUMP (its folder) or OOT_EXEFS; OOT_WORK moves the work folder.

The built game's own arguments (image.bin, --romfs, --user, --trace, --prepare-shaders) are in the README's Running the game from the command line.

Scripted test input (HOS_INPUT_SCRIPT and HOS_INPUT_LIVE) is applied before the window-focus check. A log saying the game window is not in front does not mean those presses were discarded. HOS_HEADLESS and HOS_WINDOW_NOACTIVATE change window creation, not this input routing. The game must still reach a state that reads and responds to the supplied controller input.

Physical keyboard and mouse input stays with the foreground window. Physical controllers can also play in the background when the existing "Controller in background" option or HOS_INPUT_BACKGROUND=1 enables them; HOS_INPUT_BACKGROUND=0 overrides that option. With HOS_INPUT_EXCLUSIVE set (to any value, 0 too) the script alone drives the game until 5 s after its last press; without it the player's devices add to the script's presses. It is not a focus override.

Switches for testing and debugging

The running game reads its switches from the environment or from hookshot_env.txt beside image.bin (one NAME=VALUE a line, # for notes; HOS_ENV_FILE=<path> reads that file instead). The build reads its own from the environment. The README has the ones players are asked to try (RX_VK_ASTC_RGBA8, RX_VK_LOW_SPEC, RX_VK_MOVIE_UPSCALE, RX_VK_SKIP_CODE, HOS_OOT_CHEATS). There are several hundred more, most of them one-off experiments: grep -rn 'getenv("' host gpu/vk lists them, and the comment where each is read says what it does. "Set" below means any value, 0 included.

RX_VK_MESH_NOCULL=<prefix,...> turns off the culling in the task shaders whose native code key starts with one of the prefixes. On a Steam Deck, RX_VK_MESH_NOCULL=2c56dc1006942f74 avoids the same hang without leaving anything out: that task shader walks a coarse depth grid cell by cell for every meshlet and ends with visible = (result & 1) | (c3[2320] & 4), bit 4 being the game's own "draw everything". The switch makes that answer true, and dead code elimination removes the grid walk, so every meshlet is drawn and the rasterizer clips what is off screen. It costs some GPU time on cards that cull quickly, so it is off unless set. The log says "culling off, every meshlet drawn" for each task shader it changed.

Running a test

Switch What it does
HOS_HEADLESS (set) No window: the renderer draws offscreen, for screenshots and frame dumps
HOS_WINDOW_SIZE=<w>x<h> The window's size in pixels (1280x720 by default, wider for an ultrawide picture; 64 to 16384 a side)
HOS_WINDOW_NOACTIVATE (set) The window opens behind the others and does not take the focus (Windows)
HOS_FULLSCREEN=1 Starts in fullscreen; the Insert menu's Fullscreen row is then left alone
HOS_AUDIO=0 No sound device is opened (the mixer still runs); scripts/run-vk.ps1 sets it unless -Sound
HOS_LANGUAGE=<code> The game's language for this run, a code from language.txt
HOS_OUTPUT_RES=<0..3>, HOS_HANDHELD=1, HOS_ASPECT=<ratio> Over the options file: the output resolution (0 2048x1152, 1 2560x1440, 2 3840x2160, 3 1920x1080), the handheld profile, a picture wider than 16:9 (2.3889 for 3440x1440; the Ultrawide row's 21:9 is 2.3704, 64:27, and its 32:9 3.5556)
HOS_DYNRES=0, HOS_REALTIME_STEP=0, HOS_TEXT_SPEED=<0..3> Over the options file: Resolution 100% (non-zero: Auto), Game speed Per frame (1: Real time), Text speed
HOS_STEP_STEADY=0 (Triforce, on by default since the lab's A/B; =0 the mean of the last five as before) The game's real-time step kept steady, after NX2navi's steady step (host/step_steady.h, host/nn_vi.c realtime_step): the mean of the last 12 present intervals without their longest and shortest in place of the mean of the last five (HOS_REALTIME_WINDOW), the paced period itself where that mean is within 3% of it, and what the display showed and the game was not given repaid at a 64th a frame, 10% of the step at most (a quarter second owed at most). A cap the game holds steps it by the period exactly, and a hitch is paid back over most of a second instead of in the next five frames (a 50 ms frame at 240: 200 frames of at most 10% more, where the mean of five gave five steps of 13 ms). Game time still follows the clock
RX_VK_FRAMEGEN=0, RX_VK_FRAMEGEN_MULT=<2..8>, RX_VK_PACE=0, RX_VK_UPSCALE=<0..2> No frame generation whatever the menu says; over the options file: its multiplier, frame pacing, the upscaling filter
RX_VK_FRAMEGEN_FINE=0 Frame generation's own made frames (Auto, 2x to 8x) the old way: a vector per 16x16 pixels in steps of 4 pixels, a blend of four of them per pixel, a pixel alike in both frames taken as still. Without it, a vector per 8x8 pixels to a fraction of a pixel, settled among its neighbours, and one motion per pixel (gpu/vk/vk_framegen.cpp fine_vectors, shaders/fg_fine_*.comp), which keeps moving straight lines straight and thin lines drawn (tests/test_framegen_lines.py measures both)
RX_VK_PACE_SMOOTH=0 (Triforce, on by default since the lab's A/B; =0 off) The Frame pacing row on the plain present too, without frame generation: with the row on, a picture of the game's that comes sooner than seven eighths of the recent interval after the last one waits for that, its blit on the queue and the queue's lock let go; a late one goes at once, and none waits more than 50 ms (gpu/vk/present_smooth.h, after NX2navi's pace_smooth). Without it the row spaces only frame generation's frames, as before. With RX_VK_PRESENT_THREAD=0 the present is on the game's presenting thread, so a wait also holds that thread's next frame: what that does to the rate under the cap is for a measurement before it is on. A vk: frame pacing line every 1200 pictures says how many waited and how long
RX_VK_PRESENT_THREAD=1 (off by default since the lab showed no gain) (Triforce, on by default; =0 as before) The game's presents go out from a present thread of their own (gpu/vk/present_thread.h, after NX2navi's present thread): the presenting thread records and submits the blit as before (the frame fence, the swapchain's image, the overlays, the bug capture's copy and the frame log's: the same commands in the same order on the queue), then hands the pacing's wait (RX_VK_PACE_SMOOTH) and the present call to that thread and goes on to its next frame; the next present waits first until the one handed over is out, so one is in hand at most. Not with frame generation, NVIDIA DLSS frame generation or AMD Anti-Lag 2 (presents and stages of their own); NVIDIA Reflex's present markers carry their frame's id. The vk: a frame's present line every 120 presents says how many went out from it, the presenting thread's time in the present and how much of it was the wait for the present before, and the pacing's wait and the present call (on whichever thread); the stall line's present is the presenting thread's, with that wait named
RX_VK_REFLEX_LIMIT=1 (Triforce, off by default) With the NVIDIA Reflex row on and no frame generation, Reflex's sleep holds the Game frame rate cap (the sleep mode's minimum interval) where each frame starts, in place of the game's own wait, as the Reflex frame limit row does with DLSS frame generation: one wait a frame, timed by the driver (gpu/vk/vk_reflex.cpp reflex_pace, the rule gpu/vk/dlssg_pace.h's; after NX2navi's low_latency). The game's own wait holds a movie, a frame RivaTuner holds, a window that showed nothing for 200 ms, and the rest of the run once over half of 60 frames came sooner than three quarters of the period, or when the driver refuses the interval. vk: NVIDIA Reflex: frame limit: lines say who holds it; the Full overlay's Frame limit line says NVIDIA Reflex after the rate. The Reflex frame limit row's text does not cover this switch yet
HOS_PACE_HANDOFF=0 The game's own wait paces every frame, whatever the Reflex frame limit row says and whether RivaTuner Statistics Server runs: the renderer is never asked whether another limiter holds a frame, and RivaTuner gets no limit from the game (host/nn_vi.c pace_handed, gpu/vk/vk_pace.cpp)
HOS_FPS_STEADY=0, =1, =2 (Triforce, off by default: the Steady frame rate row, over it) 1 any rate, 2 steps of the display's refresh: the game's frames paced to a period this PC holds in the scene, never shorter than the Game frame rate cap's (host/pace_steady.h, host/nn_vi.c steady_period). The rate is chosen by probes (pace_steady_probed): 32 frames at the cap, unpaced, the last 24 of them measured, at the start, 2 s after a load, at least every 12 s, and when a quarter of the last 64 frames ran late (2 s after the last probe at the soonest, twice that each time a probe changes nothing, up to 12 s); the rate becomes the first the last three probes' 90th percentile fits in with 2% to spare where that is slower, or the first it fits in with 5% to spare where that is faster. A frame paced slower does more work (the lab's Market: 11.6 ms unpaced, 15.5 ms paced at 55 fps), so the frames' own measure as they run chased the rate down; frames late now only bring a probe on, and the rate is never under what a probe shows the PC holds. HOS_FPS_STEADY_PROBE=0: no probes, the rule below as before. Without probes: what a frame took is its present interval less the longest of the pacing's waits in it (the acquire's, on the presenting thread or another, and the present's hold), and what it needed the interval less all of them (OoT's main thread and Presentation Thread take turns; where the waits add up to the whole interval, the longest: pace_steady_measure); a quarter of the last 64 frames that took more than the period lowers it at once to the first rate their 90th percentile fits in with 2% to spare, and once it has held 3 s since a raise (6 s since a lowering, doubled for each lowering within 30 s of a raise, up to 120 s, and back to 6 s at a load) it rises to the fastest rate the 90th percentile of what the last 512 frames needed fits in with 5% to spare (one rate at a time where the game acquires on another thread). A frame that took over 2.5 times the median of the last 64 (hitches among them), a present interval over 250 ms, and the frames of the 2 s after such a load (the scene is not its measure yet) are left out; the first lowering after a load waits for 128 frames of the new scene and takes their 90th percentile. The acquire's wait starts the frames a period apart (the steady step then gives the game the period as its time step) and the present holds each picture of the game's to the period after the last, less a 64th of it (gpu/vk/present_smooth.h present_smooth_paced_at, with or without the Frame pacing row; not with frame generation). Another limiter holding the frames (RivaTuner, Reflex) puts the cap back while it does. vi: steady frame rate: lines at each change say what the frames needed, and every 5 s what the rule was given (what the frames took and needed at p50 and p90, the present interval's p50, the waits a frame by kind, the frames kept and left out by reason, how many of the last 64 kept were late, and the probes and what the last three took unpaced); the vk: frame pacing line counts the present's holds
HOS_FPS_STEADY_PROBE=0 (Triforce, with HOS_FPS_STEADY or the Steady frame rate row) No unpaced probes: the rate by the frames' own measure as they run, as before test31 (host/pace_steady.h pace_steady_probed, host/nn_vi.c steady_period); the frames' work grows when they are paced slower, and that rule slides down
HOS_PACE_SPIN=0, HOS_PACE_SPIN=<microseconds> (Triforce) The game's own frame wait on the high-resolution timer for the whole wait, as before, which wakes up to about 0.5 ms after the frame's time. By default the timer takes the wait up to 0.6 ms before the frame's time and the rest is yielded away on the clock, so the frame starts on its time (host/pace_wait.h, host/nn_vi.c pace_sleep); a number is another margin. Every 5 s in which frames waited a vi: frame waits line says how long after their time the waits ended, on average and at most
HOS_RTSS=0 RivaTuner Statistics Server is left out entirely: nothing of it is read or loaded and its profile is not touched; a line triforce_rtss_profile.txt holds from a run that did not close is only reported in the log (gpu/vk/rtss_limit.cpp, The options file below)
HOS_RTSS_DLSSG=1 With DLSS frame generation RivaTuner is tried as the limiter too, at the cap times the multiplier in effect, with every safeguard (off: the game's own wait or Reflex, gpu/vk/pace_rule.h says why)
RX_VK_DEVICE=<n> The graphics card listed as vk: device <n> in the log, over the menu's GPU device
HOOKSHOT_NO_UPDATE_CHECK=1 No look for a newer release at the start
HOS_SINGLE_INSTANCE=0 (Triforce) No lock on the game folder: as before, a second copy of the game starts on a folder one already runs from. By default the first holds a lock named after its game folder (host/hos_instance.h), taken before the log is opened; a second copy waits up to 5 s for one that is ending (20 s after the menu's Restart), then says in a message box which process holds the folder and ends (a --prepare-shaders run or HOS_HEADLESS: an @@error line, and the prepare ends as one with no Vulkan). Other folders (the lab's copy, the owner's game) never meet. The log's instance: line says what this run did
HOS_TRACE=1 Every Horizon call logged, as --trace does
HOS_SAVE_EXPORT_DIR=<folder> Where the System tab's Export save rows write their zip, in place of the Downloads folder (set in the environment; tests/test_save_share.py uses it)
HOS_SAVE_LOCK=0, TRIFORCE_SAVE_LOCK=0 (Triforce) The save's lock between the game and Setup: the game holds <user>\save.lock open without sharing from its first save mount to its end, and Setup's Convert saves holds it across its copy (host/save_tx.h save_tx_lock, setup/Guard.cs SaveLock). A running game makes Setup refuse the copy; a game started during one waits for it (30 s at most) before it reads its save. HOS_SAVE_LOCK=0: the game takes none; TRIFORCE_SAVE_LOCK=0: Setup takes none and only looks at the running programs, as before
RX_BACKEND=<name> Unset or vulkan: hookshot_vk.dll; any other value but eden: the WebGPU renderer, when the exe was built with one

Input for scripted runs

Switch What it does
HOS_INPUT_SCRIPT=<presses> Presses timed from the game's first controller read
HOS_INPUT_LIVE=<file> A file the test appends lines of presses to, read every 30 ms; each line's times count from when it is read. A line !cheat <n> sends a Cheats page action, !synclog logs the NVN syncs (!dump, !shots, !rdoc and !flasharm are the WebGPU renderer's)
HOS_INPUT_FRAME_CLOCK=1 The script's time runs at 60 game frames a second instead of the wall clock
HOS_INPUT_EXCLUSIVE, HOS_INPUT_BACKGROUND, HOS_INPUT_SCRIPT_BACKGROUND (set) As above; the last lets every device count while the window is behind another one
RX_VK_MENU_SCRIPT=<seconds>:<key>,... Timed Insert menu keys: INS, UP, DOWN, LEFT, RIGHT, ESC, ENTER, TABL, TABR
RX_VK_UI_PROMPTS=pad or keys The menu's button prompts for a controller or the keys, whatever was used last (screenshots)
RX_VK_UI_GAME_FONT=0 The menu, the counter and the start-up screen in the included Libertinus, not the game's own font

The presses are <seconds>:<button>[+<button>...][/<ms>], separated by commas, for example 2:A,5.5:LUP/1500,9:ZL+R. The buttons are A B X Y L R ZL ZR PLUS MINUS LS RS LEFT UP RIGHT DOWN, and the sticks pushed to their edge LUP LDOWN LLEFT LRIGHT RUP RDOWN RLEFT RRIGHT. A press is held for 200 ms unless /<ms> says otherwise. The names are case-sensitive, and an unknown one is ignored.

Pictures and frames

Switch What it does
RX_VK_SHOTS=<dir> A PNG every RX_VK_SHOT_EVERY presents (300) as vk_<present>.png, at RX_VK_SHOT_W x RX_VK_SHOT_H (1280x720)
RX_VK_FLASH=1 The flash detector, with RX_VK_SHOTS and RX_VK_SHOT_EVERY=1: writes the frames around a flash and dumps the next one
RX_VK_FRAMELOG=<file> Every frame shown, at 320x180, while <file>.go exists; python -I scripts/framelog.py <file> finds the flashes
RX_VK_DUMP=<present>[+<count>][,...] Every step of the frame after that present as PNGs, in dump_<present> under RX_VK_DUMP_DIR (or RX_VK_SHOTS, or the current folder); RX_VK_DUMP_STEPS=<lo>-<hi> and RX_VK_DUMP_PROGS=<key>,... narrow it
RX_VK_PASS_TRACE=1 The passes of the last frames, logged at a flash or a dark frame (RX_VK_PASS_TRACE_AT=<n>: every n-th present)
RX_VK_PROBE=1 or 2 The centre texel after every pass: probe_<frame>.txt at a flash (1), or probe_all_<n>.txt at speed (2); python -I scripts/probe.py reads them
RX_VK_DUMP_FAILED=<dir> The native code of every program that does not translate, for nx2/lower_test.py (game data: keep it local)

Time and profiles

Switch What it does
HOS_PROFILE=<seconds> Every interval, the busiest threads in the log; it also starts the samplers below
HOS_SAMPLE=<thread> + HOS_SAMPLE_FILE=<file> One thread's stacks, sampled every millisecond (needs HOS_PROFILE); python -I scripts/prof.py <file> reads them
HOS_SAMPLE_ALL=<file> Every game and renderer thread every 2 ms while <file>.go exists (needs HOS_PROFILE); scripts/crit.py, scripts/vkprof.py and scripts/hotlist.py read it (on Linux with RX_MAPS=<game folder>: they name frames from its hookshot and hookshot_vk.so)
HOS_THREAD_TIMES=<seconds> Every interval, the threads that used over 5% of a core
HOS_FPS_LOG (set), HOS_PRESENT_TRACE=<csv> The game's frame limiter, VRR flags and nominal rate every 300 presents; a CSV line per game present
RX_VK_FRAME_LOG=<csv> A CSV line per present: frame, seconds, frame time in ms
RX_VK_FRAME_TRACE=1 A line a frame in triforce_frames.csv beside the game (the lab's scenarios keep it as frames.csv): present to present, the waits for shaders and pipelines, the uploads, and the replay's parts (memsync_ms ... tex_lookup_ms: the draws' parts are sampled and summed over every thread that records). (Triforce, wp20, gpu/vk/frame_trace.h) Then each frame split as the stall line splits a long one: replay_ms (the submits and the present phase), present_ms, dispatch_ms, qsubmit_ms, par_wait_ms (the replay thread's waits for its helpers' segments), outside_ms (the frame less the replay and the present: the game's own update), game_wait_ms (the game's fence waits), captures_ms (the captures at its submits), wb_wait_ms and wb_held_ms (the waits for write-backs, and their part after the writer's recording was done: RX_VK_WB_WAIT_REC), qs_bg_ms (the queue submits beside a background import). python -I scripts/frame_rank.py <run folder or csv> ranks what made the frames over the 99th percentile and over 1.5x the median by these, per window (the Market, the tour's stays, the loads)
RX_VK_WB_WAIT_REC=1 (Triforce, off by default; the handoff's §12.9, gpu/vk/wb_rec_wait.h) A wait for a write-back still on the GPU (a capture's late pages on the game's submitting thread, a read or binding of a page put off) ends once the recording its submission was finished in is done on the GPU, not when the submissions' timeline reaches it: that timeline is held below any submission stopped at an event wait, and the lab's Market had 20-46 ms waits of the game's thread with the GPU 4 submissions behind. Whatever the switch, the wait for the recording comes first and the rest is counted: the stall line's N of them X ms after their writer's recording was done, the late: line's ms of the wait after the recording that finished it was done, the frame trace's wb_held_ms. Off: the captures' late-page wait orders something not known yet (RX_VK_LATE_NEW), so it is tried with the lab's flicker count first
RX_VK_PASS_TIMING=1 or 2 GPU time per pass (2: per program too), logged every 600 presents
RX_VK_SLOW_LOG=<ms> The replay's times for each frame that took longer than this
RX_VK_STALL_LOG=<ms> or 0 On in every run (gpu/vk/stall_watch.h): every 600 of the game's frames a vk: frame times line (the longest frame and how many were over 33, 50, 100 and 250 ms, present to present and in the replay's own time), and for each frame of 50 ms or more a vk: stall line of where its time went: the replay's phases, memory sync's parts, the waits for write-backs still on the GPU (how far ahead, and whether behind a present's blit), the waits for shaders or pipelines, the uploads, the pools imported where they were bound, the GPU behind, the present (its image, fence, call and Reflex's sleep), the game's fence waits, the rest, and a pool's trial in guest memory if one is under way (RX_VK_DEMOTE_QUICK); and the new textures left for the next frame and whether the frame's picture was held (RX_VK_HOLD_MS), whose holds the 600-frame line counts too. At most 3 stall lines a second and 1500 a session. <ms>: the stall line's threshold; 0: neither line
HOS_PGO=<file> In a run of an RX_PGO=gen build: <file>.reset clears the counters, <file>.dump writes them to <file>. It is read before hookshot_env.txt, so set it in the environment

The GPU

Switch What it does
RX_VK_VALIDATION (set) The Khronos validation layer
RX_VK_CHECKPOINTS=0 No NVIDIA checkpoints (on by default; after a lost device they name the draw it stopped at). (Triforce) The boundaries between a frame's work have markers too: the write-back diff pass, each recording's start, uploads and end, the present's blit and its menu (gpu/vk/checkpoint_kinds.h); the report reads the two stages' last markers together, says what followed the last one reached, and logs the switches, the queue's timeline and the mirrors' piece binds the submits wait for. (P4) Each marking thread numbers its own markers in a ring of its own (15 of 4096; threads after the 15th share a 16th), no atomic shared by the recording threads; the report names a marker's ring and reads the markers around it in that ring
RX_VK_HANG_DUMP=<file> or 0 The hang watch (Windows) is on in every run: once no frame was shown for RX_VK_HANG_SEC seconds (20) with the game's window in front, the top of every thread's stack goes into the log and the whole stacks into triforce_hang.txt in the game folder, once a stall and at most three times a run. <file>: that file instead, and every second counts whatever window is in front. 0: no watch
RX_VK_NOOPT (set) Pipelines built without the driver's optimisations
RX_VK_PASS_BARRIER=game or full The barrier a draw pass starts with (gpu/vk/pass_barrier.h). game: a pass right after another, with nothing recorded between (no barrier of the game's, no copy, clear, uniform update or dispatch), waits for the earlier work in its fragment stages only, so its vertex, task and mesh work may overlap the earlier pass's fragments; a pass the replay itself split off for a hazard (a pass of its own in the log) and RX_VK_BARRIER_EVERY_DRAW's keep a full one. (Triforce, P4) "Nothing recorded between" is the command buffer's own count (RX_VK_BARRIER_CONTEXT), so beside the Replay helper threads too. full: a full barrier at every pass start, as before. Unset: game with NVIDIA's driver, full on every other card. The log's vk: pass barriers: line says which, and the frame statistics' pass starts ordered in their fragment stages only how many a frame
RX_VK_SPLIT_BARRIER=pass or full (Triforce) A long submission goes to the GPU in parts of 120 draws and dispatches (RX_VK_CHUNK); gpu/vk/barrier_rules.h. pass: a pass open at a part's split goes on in the next part, begun again with the same targets behind a barrier of its attachments' outputs alone and with what its draws sampled and wrote, so the GPU does not drain between two draws of one of the game's passes; where the part's end records anything (its uniform updates, its write-backs) or an event's write is held, the full barriers as before. A parallel replay's segments are not split into parts: each begins and ends with a full barrier, so nothing goes on across a segment's edge. full: a full barrier at each part's end and the next one's start, as before. Unset: pass with NVIDIA's driver, full on every other card. The log's vk: a submission's parts: lines say which and, every 3,600 splits, how many went on in their pass and how many of those parts had uploads (whose own full barriers order them after the part before all the same)
RX_VK_EVENT_BARRIER=late or full (Triforce) An event signal in the game's command stream (gpu/vk/barrier_rules.h). late: nothing is recorded at the signal and its pass goes on (the word's buffer is bound there, as before); the event's word is written right after the next full barrier on its command buffer (the game's next barrier, a dispatch's or pass start's), so after all the work before the signal, and a recording's end writes what is still held behind a full barrier before its write-backs copy the words to the game's memory; a wait the replay finds met for an event whose write is held gets a full barrier first. The game sees the word at that barrier rather than at the signal. full: the pass ended, a full barrier and the write at each signal, as before. Unset: with the pass barriers' game mode (RX_VK_PASS_BARRIER: NVIDIA's driver). Not with the parallel replay. The vk: event signals: line says which
RX_VK_TAIL_EARLY=1 or =0 (Triforce, on by default since options_version 6; over the Debug tab's Start next frame early row, tail_early=0 to turn it off; read at the start; after NX2navi's tail_early) The early tail (gpu/vk/tail_early.h, gpu/vk/vk_replay.cpp): the replay cuts a frame's recording at the gameplay upscale's dispatch (the game's network, or DLSS, DLAA, FSR in its place) and records the rest, the upscaler and the interface, as one command buffer; its event signals are held. At the recording's end a tail that wrote no binding (its inline uniform updates aside), bound no guest memory itself, ran no program of the game's that reaches guest memory through the page table or a texel buffer, and wrote no texture back has its event words written in its upload command buffer, after the scene's write-backs and ahead of its own commands: OoT's present poll then sees its frame's event while the GPU still runs the tail. Any other tail has the words written at its end, as before. Also with the parallel replay (its segments end at that dispatch) and with the lazy write-back. Not with RX_VK_BENCH or a frame dump. A vk: the early tail line at the start says on, and every 1200 tails how many went early and why the others did not. Not yet run in the game
RX_VK_DISPATCH_BARRIER=game (Triforce) Off unless set, not yet run in the game: a dispatch right after another, nothing recorded between, records no full barrier of its own (not an indirect one, nor a program a stand-in may take over), as NX2navi's barrier_game does; the game's own barriers order its dispatches. Only the game shows whether that is always so (a one-frame band or flicker where it is not): a switch for the lab. A vk: RX_VK_DISPATCH_BARRIER=game: line every 20,000 dispatches it left without one. (wp14, P4) It no longer stands aside while the Replay helper threads record (most frames at the Market, so the lab's earlier run of it measured little): "nothing recorded between" is the command buffer's own count of its commands (gpu/vk/cmd_work.h, RX_VK_BARRIER_CONTEXT), a segment being a command buffer of its own
RX_VK_BARRIER_CONTEXT=0 (Triforce, P4; after NX2navi's per-context barrier state) What the barrier rules ask, "was anything recorded into this command buffer since its last full barrier, its last pass's end, its last dispatch", is answered by each command buffer's own count of its commands (gpu/vk/cmd_work.h), where one count of every thread's commands served before (an atomic add on every command by every recording thread). So the rules hold while the Replay helper threads record: the left-out repeats of a full barrier, RX_VK_PASS_BARRIER's pass starts and RX_VK_DISPATCH_BARRIER. A command buffer's begin starts its state afresh; each segment begins and ends with a full barrier, so no rule relaxes across a segment's edge. RX_VK_SPLIT_BARRIER asks also whether anything went to the queue between two parts (every submit is counted). The rules' defaults are as they were. 0: the one count, and the rules standing aside while the helper threads record, as before. The vk: barrier state: line at the start says which; the frame statistics' full barriers recorded, ... left out and pass starts ordered in their fragment stages only show the difference
RX_VK_BATCH=parts, 1 or 0 Held submits (gpu/vk/vk_replay.cpp batch_way). 1 (the default with Mesa's RADV): every submit held until something needs the GPU's results or the queue's order. (Triforce) parts, off unless set: only a whole submission's recordings are held, and only while the game's submit is being replayed; a part goes at once with those held before it, as do 4 held (RX_VK_BATCH_MAX), and the held go when the replay of the game's submit returns. Neither changes the command buffers or their order on the queue. 0: each submit at once (the default elsewhere). The vk: batched submits lines say which and how many command buffers went in each queue call
RX_VK_FOLIAGE_SHADOW_CULL=<layer>[f] Off unless set, not yet run in the game: the draws of mesh programs into the sun's shadow cascades (depth only, square, wider than 768) from that layer of the cascades on (0 to 2; NX2navi's is 1) that cull neither face are drawn with their back faces culled (the front ones with f, as 1f): the foliage's double-sided cards draw half their fragments there (gpu/vk/foliage_shadow.h). Not the same picture: a card facing away from the sun casts no shadow in those cascades. The log says vk: RX_VK_FOLIAGE_SHADOW_CULL at the start and names the first draws it culled (vk: foliage shadow cull:)
RX_VK_FIFO (set), RX_VK_IMMEDIATE (set) The swapchain's present mode for one run, over the Insert menu's VSync row: FIFO, as with vsync forced by a driver; immediate, where the surface lists it. Unset, the row decides (gpu/vk/present_mode.h): On is mailbox where the driver has it (immediate on Windows where it has none, FIFO elsewhere), Off immediate wherever the surface lists it
RX_VK_SKIP_PROG=<prefix>,... Leaves out the draws of these programs (default 53509044401d78d2; - leaves out none)
RX_VK_PIPE_SKIP=0, 1 or 2 Default/1: wait for shader translation; a pending pipeline can be skipped only for attachment-only draws whose targets hold an earlier frame. 0: wait for every pipeline too. 2: restore the old skip for untranslated draws with persistent targets; this can omit writes before the shader is known. Translated memory-writing draws still wait
RX_VK_PIPE_FRAME_WAIT_MS=<ms>, RX_VK_PIPE_ONESHOT_BUDGET=1, RX_VK_PIPE_SKIP_NEW=0 A draw whose pipeline is not ready (gpu/vk/pipe_wait.h, NX2navi's rules). A full-screen draw (at most 6 vertices over half the pass or more: a lighting, fog or tone mapping pass) into targets that hold an earlier frame is left out only where the hold of the last picture takes its frame (RX_VK_HOLD_PIPELINES); where it cannot (at its bound, resting after one, or off) the draw waits for its pipeline up to this many ms a frame in all (50, at most 500), then 40 ms more, and is left out after both; its job goes to the front of the workers' queue meanwhile. 0: left out, as before. RX_VK_PIPE_ONESHOT_BUDGET=1 (off; NX2navi has it on): draws into targets drawn once and draws whose shaders write memory wait from the same budget and are left out once it is spent, instead of waiting until their pipeline is made. RX_VK_PIPE_SKIP_NEW=0: a pass whose colour target is drawn for the first time is kept by its depth target alone, as before (by default its draws wait, as for any target drawn once: the game's item icon capture). The log's vk: pipelines not ready line counts them
RX_VK_PIPE_FAST_WORKERS=0, RX_VK_PIPE_LINK_MS=<ms> A pipeline whose stage libraries were cold has those libraries built by a worker first and is linked from them, ready with that link, and its whole optimised build follows as a job of its own (gpu/vk/pipe_wait.h libs_first, NX2navi's pipe_fast_workers); a draw that waits for it runs the libraries and the link, not the whole build. 0: the whole build first and the cold libraries after it, as before. RX_VK_PIPE_LINK_MS=<ms> (0 by default, at most 100; NX2navi's 6): the links made on the draws' threads in a frame take at most this long; a new pipeline after that is linked by a worker, its draws left out or waited for meanwhile (needs the fast pipeline link and the first switch on)
RX_VK_PRECOMPILE=0 or 1 The shader preparation before the title off or on (on in builds made with RX_RELEASE=1, as the builders' are)
RX_VK_PREPARE_THREADS=<n> The threads the shaders are translated and their driver's part made on before the title, 1 to 64. Unset: every processor, a thread past half of them for each GB of RAM free at the start, and half in a process started above normal priority (the log's "the shaders' preparation runs on" line says how many)
RX_VK_TASK_MESH_FALLBACK=0 or 1 Task + mesh draws through the compute fallback (1) or the driver's mesh shaders (0). By default the fallback is on for AMD's Windows driver for RDNA 2 (every RX 6000 card and that generation's integrated GPUs: the driver whose vk: vendor fixes line names the "AMD proprietary shader compiler"), where the native path timed out the driver on the RX 6700 XT and RX 6800 XT (issue 996)
RX_VK_MESH_AHEAD=0 (Triforce, on by default, after NX2navi's mesh_ahead; =0 as before) An indirect mesh draw's records are copied into a ring as {count, 1, 1} before it, outside the pass, so each one ended its pass and the next draw began it again (OoT's foliage, grass and leaves: about 16 a frame at the Market). Now the first indirect mesh draw of a run copies the records of the indirect mesh draws after it as well, in the same three barriers, and those stay in the pass: a run is the indirect mesh draws after it with only state, draws, counter reports and render conditions between (gpu/vk/vk_replay.cpp mesh_run_kind); a dispatch, a barrier, a copy, a clear, a uniform update, new targets or an event ends it, so no work of the game's between can write the records after they were copied. A draw takes only the entry copied for it (its op, records, count and stride); at most 32 draws and 1 MB of the ring a run (gpu/vk/mesh_ahead.h). A vk: indirect mesh draws line every 20,000 conversions says how many took their records from an earlier draw
RX_VK_NO_PROGRAM_CACHE (set) Neither reads nor writes hookshot_programs.bin and the pipeline notes
RX_VK_PROGRAM_CARRY=0 The program cache (triforce_programs.bin) is good for one build of the translator only, as before: any change to its files, a log line or a host option's number in gpu/vk/vk_api.h too, translates every program again, and the pipeline cache, the pipeline notes and the prepare's record go with it. By default the cache is carried over an update that changed nothing of what translates (gpu/vk/program_carry.h has the rule, tests/test_program_carry.py holds it): the translation stamp (nx2/build.py translation_stamp) is the translator's files without vk_api.h, without the parts of vk_shader.cpp marked as outside it, and without comments, blank lines and spaces at lines' ends. The log's vk: program cache line at the start says whether the programs were kept, carried over an update of the translator (and from which build), or translated again (and how many the cache had); while they are translated again a line now and then counts them. Switching it either way translates every program once more
RX_VK_GPL=1 or 0, RX_VK_GPL_KEEP_LINKS (set) The fast pipeline link (VK_EXT_graphics_pipeline_library; gpu/vk/gpl_rules.h), on by default since options_version 5: a new pipeline is linked from its program's two shader libraries where the driver has them compiled, and the optimised build replaces it. The Debug tab's Fast pipeline link row is the same without an environment to set (fast_pipeline_link=1); the switch goes over the row. With it the preparation has its driver's part ("Compiling shaders"), which now goes on after a start that died in it, leaving out the programs that start had in the driver's hands (triforce_prepared.bin.warming and .warming.skip), up to three starts in a row. RX_VK_GPL_KEEP_LINKS: the linked pipelines the optimised ones replaced are kept for the run, as before, instead of destroyed 600 presents and 10 s later. RX_VK_NO_WARM (set): no driver's part; RX_VK_GPL_SYNC (set): a cold library is compiled in the draw; RX_VK_GPL_NO_CACHE (set): the libraries are not kept in the pipeline cache
RX_VK_SPV_PACK=0 Every shader module kept for the whole run, as before. By default the SPIR-V of graphics and mesh programs is kept packed in memory (gpu/vk/spv_store.h, to about 0.37 of its size) and their shader modules, which the driver otherwise holds for the whole run, are made only for the time a pipeline is created with them, on the thread that builds it. Compute programs, the programs the preparation lets go and the programs a draw reads from the cache itself keep their modules. The log's vk: shader code packed lines say what it comes to and what it costs
RX_VK_PCACHE_RAM=1 Off by default (in its one session on, v0.4.0-test9, it gave back nothing the working set showed). With it, once the PC has had under 1.5 GB of RAM available at two looks a second apart, the pipeline cache (when it is 256 MB or more) is destroyed once no pipeline creation is using it (gpu/vk/pcache_gate.h): the pipelines built after that go without it and it is not saved again that session, so mkw_vk_pipelines.bin keeps its last save. The log's vk: RAM short ...: the pipeline cache ... is let go line says when and what the working set did. Whatever this switch says, the cache's save in play waits while a copy of it would not fit in the RAM available with 2 GB to spare (the save at the game's close does not), and the builder of the predicted pipelines behind the game rests while under 3 GB (or a tenth of a PC of more than 30 GB) is available (gpu/vk/mem_parts.h)
RX_VK_WRITERS_WAIT_MS=<ms> (Triforce) How long the game's close waits for the files the renderer is writing on threads of their own (gpu/vk/file_writers.h; 2000 by default, 0: no wait and nothing refused, as before). The close ends the process through ExitProcess, which stops every other thread where it is: the pipeline cache's save in play, the order file, a bug capture's or a debug picture, the hang report, the predicted pipelines' list, the frame log. At the close (HOS_OPT_EXITING) no such write begins any more and the ones under way are waited for; one still going at the bound is cut, and is one of the files written whole beside the old (.part / .tmp, then put in place: the prepared record triforce_prepared.bin and the .for files are now too), or a list whose reader takes whole records only. The log's vk: exit: the files being written ... were waited for line says how long, and what was cut
RX_VK_OPTIONS_MERGE=0 (Triforce) The menu writes its own values over triforce_options.ini in place at every change, as before. By default (gpu/vk/ini_merge.h, vk_menu.cpp save) each line it writes is merged by its key with the file as it is then: a line changed outside the game while it runs (a text editor, a tool) and not changed in the game since the game read or wrote the file is written as the file has it, so a change made outside and one made in the menu within the same second both stay (a row changed on both sides is the game's); the game takes such a line at its next start. The file is written whole beside the old one and put in its place (in place only where another program holds it open so that it cannot be replaced). The log's menu: options: ... changed in triforce_options.ini outside the game line names such lines
RX_VK_MEM_PARTS=0 No vk: memory, the parts line. By default every 600 presents it gives the working set, the game's own memory committed and in RAM (a sample of its pages), the rest of the working set in RAM by what it is (a sample too: the program's code, the driver's code, other code, mapped files and views, write-combined or uncached memory, the heaps and other private memory), the shader modules alive and the packed stages, the pipeline cache, the pipelines and stage libraries kept (how many a draw has had, how many were given back) and the allocator's blocks in system memory (gpu/vk/mem_parts.h), and what its walks and samples took. It is written on a thread of its own that nothing waits for; the guest window's walk is made again every eighth line
HOS_MEM_CENSUS=<seconds> or 0 (Triforce) The guest memory census (host/guest_census.h), on by default every 5 seconds, on a thread of its own: a mem: census line with what the runtime handed out of the guest window by kind (the program and the system region, the heap, the address regions and the game's own pages in them, what lies outside them: the physical maps and first touches), the game's own count against the 9809 MB it is told it has, the pages the game let go that stay committed (zeroed under an import, or discarded with a freed region) and what the give-back gave back, the process's commit and working set, and the PC's commit and RAM; and a mem: census, the renderer line with the Vulkan back end's big holders (its imports, mirrors, VRAM in use, the allocator's blocks in system memory, the pipeline cache, the pipelines and stage libraries kept, the shader modules). A count of bits a 4 KB page, kept as each place commits, maps or lets go of guest pages. 0: no line (and, with the give-back off, nothing kept)
HOS_MEM_GIVE_BACK=1 or 2 (Triforce) Off by default, not yet run in the game: the pages the game let go that stay committed because an import held them (FreeMemoryPages, UnmapPhysicalMemory) or because they were discarded with a freed address region are decommitted once nothing of the renderer imports them, from 4 GB up (below it pages are handed out without a commit), up to 256 MB a census pass, in runs of 16 MB at most; the renderer answers and runs the decommit with its import locks held (gpu/vk/vk_memory.cpp guest_release_unimported), so no import can lock them between. 1: every pass; 2: only while the PC is short (its commit past 85% of its limit, or under 1.5 GB of RAM available). The census line's given back says how much
HOS_MEM_MAP_RESULT=0 (Triforce) MapPhysicalMemory answers success even where Windows refused the commit, as before. By default it answers Horizon's LimitReached (0x10801), which the SDK turns into its out-of-memory result, and the log says mem: MapPhysicalMemory ...: the commit failed
RX_VK_PRECOMPILE_KEEP=1 or 0 The precompile keeps every pipeline it builds for the session (1), or keeps none of them: they are built for the caches and let go, and a draw that first needs one builds it from there (0). Unset or auto: kept where the RAM available at the precompile and what the game holds already come to 22 GB or more, on a PC of 20 GB or more (gpu/vk/mem_parts.h keep_all_pipelines); the log's vk: precompile: line says which and why
RX_VK_PIPE_RELEASE=0, RX_VK_PIPE_RELEASE_EVERY=<presents> Every kept pipeline stays for the session, as before. By default, while the PC's RAM is short (under 1.5 GB available at two looks in a row), every 300 presents up to 512 of the kept pipelines no draw has had yet are given back to the driver (gpu/vk/pipe_release.h); a draw that needs one later has it built again by a worker. The log's vk: RAM short: ... kept pipelines no draw has had given back lines say how many and what the working set did
RX_VK_PCACHE_MAX_MB=<MB> The bound on the pipeline cache's file, mkw_vk_pipelines.bin (gpu/vk/pcache_bound.h): a file over it is not read (the cache starts empty and the next save writes a new one), and data over it is not written (the file keeps its last save). Unset: an eighth of the PC's RAM, 2048 MB at least and 8192 MB at most. 0: no bound, as before
RX_VK_PCACHE_PLAY_FILE=0, RX_VK_PCACHE_FOLD_MB=<MB> The pipeline cache's play file (gpu/vk/pcache_play.h, NX2navi's play cache): once the preparation is done, what a run compiles goes into a second cache with a file of its own, mkw_vk_pipelines_play.bin beside the first (a creation asks the first cache without compiling, then the play cache), and a save writes that small file; mkw_vk_pipelines.bin is written only when the preparation built into it. Before, a save after a few new pipelines wrote the whole file again (2.6 GB at the owner's start after its precompile). At a start whose play file has reached RX_VK_PCACHE_FOLD_MB (64) it is folded into the first cache, that session builds into it as before, and its first save writes it and removes the play file. Needs pipelineCreationCacheControl. 0: no play file, as before
RX_VK_FETCH_BOUNDS=0 or 1, RX_VK_NAN_BITS=0 or 1, RX_VK_GATHER_OFFSET=0 or 1 The translation's vendor and driver workarounds (gpu/vk/vk_vendor.h) off or on for one run, whatever the GPU; the log's vk: vendor fixes line says which are on. By default: out-of-bounds texel fetches answered with 0 on every GPU but NVIDIA's; NaN tests on a value's bits on AMD's older Windows shader compiler (RX 5000 and RX 6000); gathers nudged by 1/512 of a texel on AMD's and Intel's drivers. They change the shaders' translation (one preparation of the shaders)
RX_VK_MIRROR=0, RX_VK_MIRROR_MB=<MB> No VRAM mirrors of the game's memory pools (on for discrete cards); their budget
RX_VK_DEMOTE_QUICK=0 A pool the CPU and the GPU both write is tried in guest memory (vk_memory.cpp demote_trials); by default a trial whose GPU time a frame is over 3 times its baseline and 5 ms more, after 3 frames or more, ends then, settling or measured, and is judged as a slower one is (mirrored again, measured again: gpu/vk/demote_watch.h). 0: every trial runs its 10 settling and its measured frames, as before (in the owner's logs, some twenty frames of 100 ms for a pool at 106 ms against 7.4)
RX_VK_IMPORT_AHEAD=1 or 0 On by default with NVIDIA's driver (=0 off). Off for test12 to test14: the GPU hung at the title in 6 of 12 lab runs; the cause, the game's freed pages decommitted under an import the background thread had not finished (bg_held), is closed and the lab's A/B with it was clean in 10 of 10 (gpu/vk/import_ahead.h). The ranges of the game's memory a run imported on a binding's own thread (8 to 17 ms each on an RTX 5090), whole as they were imported (their span over the game's pools included; the first version kept 16 MB chunks, which a binding across their ends imported again as one), are kept in triforce_imports_ahead.txt beside the game, at most 256, and the next runs import them on the background import thread as soon as the game's pools reach them, 4 at a look, at each change of the pool table and every 8 submissions (gpu/vk/import_ahead.h), each range once a session, and none while the PC's RAM is low (under 3 GB available, or a tenth of the RAM: the RAM's rule gives idle imports back then, and the two took turns on the same ranges in the owner's test9 session). A file of the first version's chunks is read as it is. Unset: off (it was on with NVIDIA's driver only, as RX_VK_ASYNC_IMPORT is); 1: on any card; 0: off. (Triforce) A race that fits the hang is closed since: the host decommitted the game's freed pages under an import the background thread had locked and not yet put in the pool table (vk_memory.cpp bg_held; RX_VK_BG_IMPORT_HOLD=0: not, as before, for the A/B); it stays off until a lab A/B with =1 hangs no more. The log's vk: imports ahead lines count them and name the ranges sent, vk: the game's pages ... are freed under a background import the frees that window met; the stall line's "pools imported where bound" is what is left
RX_VK_UPLOAD_AGAIN_MS=<ms> A texture uploaded before whose memory the game wrote again, met by a draw after the frame's uploads took this long (16), is uploaded at the next frame instead; its last bytes are drawn meanwhile, at most 8 frames in a row (gpu/vk/upload_owed.h later). New textures are never left so (theirs is RX_VK_HOLD_MS's rule). 0: every one at once, as before. The log's "left for the next frame" lines and the stall line count them. RX_VK_UPLOAD_AGAIN_FRAMES=<n>: a texture's upload is left so at most that many frames in a row (2: its last bytes drawn a frame or two at most; 8: as before). With 16 ms nothing was ever left in the lab's runs (the frames with re-upload bursts took 9.8 ms of uploads); 3 spreads a burst over the frames after it, its textures a frame or two late meanwhile, which is why it is not the default
RX_VK_UPLOAD_TORN=0 (Triforce, wp18-flash) A texture uploaded before, 1 MB or more, whose storage the CPU has rewritten since the copy its re-upload would read (a capture's copy of one of its whole pages, every 16th and the last, differs from guest memory at the draw's look) keeps its last bytes for that frame and is uploaded at the next frame with what that frame's capture took (gpu/vk/upload_torn.h): a copy taken while the game was still writing the texture was test29's white frames at the Market after a tour (BC6H bytes passing through, decoded to bright colours the bloom spread over the picture). At most one frame in a row, and not for a texture found so in the two presents before (one the CPU rewrites every frame is uploaded as before). Not a dispatch's upload. 0: uploaded at once, as before. The log's re-uploads of storage the CPU rewrote since its capture lines count them, those found and those left (with 0 too: the measure of how often a copy may have been taken mid-write)
RX_VK_REUPLOAD_EARLY=0 The textures the CPU keeps rewriting (uploaded again from its writes twice or more within 120 presents, 1 MB or more, sampled in the frame or the one before, not drawn into by the GPU) are looked at once on the replay thread before a parallel replay's segments begin, after the dry pass, their uploads in the recording before the segments: not made by a segment under the recording lock, where the other recording threads queued behind them (lab S2 after a tour: 4 to 12 such uploads of 28 to 84 MB in ~13% of the frames, the descriptor time 24 ms over the threads against 3). 0: the segments' looks alone, as before. The log's textures the CPU keeps rewriting, looked at before line says how many and how long (gpu/vk/reupload_early.h)
RX_VK_UPLOAD_SAME=0 (Triforce) A texture uploaded before whose storage the CPU wrote again is checked against the bytes its image holds (gpu/vk/upload_same.h): the units of its storage the writes reached (each level's and layer's GOB-block rows, as its upload reads them) whose bytes hash as at their last upload are not uploaded, and when that is all of them nothing is. The upload of the rest reads the copy the check hashed, so that what is kept is what the image got; any other upload and any GPU write forget it. Textures of 16 MB or less uploaded on the CPU (block-compressed, or under 8 MB), not sparse; one whose checks find nothing the same 4 times in a row is uploaded unchecked for its next 64 re-uploads. Lab S2 after some tours: the game rewrote a few big BC textures the Market samples with the bytes they had, 40 to 60 MB every 4 to 5 frames (the Market at 62-78 fps against 83-96, ~26 GB of uploads in its stay). 0: every re-upload made as before. The log's re-uploads checked against the bytes their images hold line says what it looked at, found the same and uploaded. RX_VK_UPLOAD_SAME_KEEP=0: the check hashes every byte it looks at; by default a page the submit-time capture keeps a copy of is hashed once and its hash kept with the copy until a capture copies other bytes into it (about half of those textures' pages passed through other bytes between two captures)
RX_VK_UPLOAD_SAME_ASTC=0 (Triforce) ASTC textures decoded on the GPU (kept as RGBA8, BC3 or BC1; 2D only) are checked too, by RX_VK_UPLOAD_SAME's check: one unit a layer, its levels from the first one the image keeps, which is what the GPU decoder stages of a layer a write reached; the staging reads the copy the check hashed. Lab S2's Market after a tour: the game rewrote such textures with the bytes they had (1536 x 1536 ASTC 5x5 of 11 levels, 768 x 768 kept as BC3, 512 x 512), staged and decoded again unchecked, about 1.4 GB in 10 s (90 fps down to 72, the 1% low 57 to 33). 0: ASTC re-uploads made as before, every layer a write reached staged and decoded. The re-uploads checked line says what of it was ASTC; the re-uploads not checked line every 600 frames counts the re-uploads made without the check, by route and by why
RX_VK_TWIN_SAME=0 (Triforce) The parallel replay's twin (a texture an earlier segment samples that a later segment of the same submission uploaded, uploaded again in the earlier segment's uploads so that its draws see the bytes as submitted) uploads only what that submission's uploads into the image asked for (gpu/vk/upload_same.h note_upload; the whole storage when one of them was whole or the image was made again), and where every unit it reads has a hash kept by RX_VK_UPLOAD_SAME's check, reads a copy of them hashed as copied: when the copy holds the bytes the hashes are of, the hashes are kept. Before, the twin uploaded the whole storage and, unchecked, forgot the hashes the later segment's checked upload had just kept, so the next rewrite of the same bytes was uploaded again, the twin with it, every few frames: lab S2's Market after a tour, about 97% of what was still uploaded unchecked in those loops, up to 6.9 GB in one stay. 0: the twin uploads the whole storage and forgets the hashes, as before. The log's the parallel replay's twins line every 600 frames counts them, the bytes uploaded against the whole, and how many kept the hashes
RX_VK_UPLOAD_EARLIEST=0 (Triforce) A parallel replay's upload of a texture, made by the worker of a later segment of the submission while an earlier one is still being recorded, is recorded into the init command buffer of the earliest segment still being recorded (submitted before that segment's uploads and commands; gpu/vk/upload_earliest.h, vk_texture.cpp UploadRedirect). Every segment before it has ended its recording and no longer samples the texture, and every one from it on finds the upload at or before its place in the queue, so no earlier segment uploads the texture again (the twin, RX_VK_TWIN_SAME): it is uploaded once, the same bytes. Lab S2's heavy Market loops (round 48) uploaded 2.1 GB of twins in their last minutes, the big streamed or new textures each uploaded once by a later segment and again by an earlier one; those twins took the frames' upload budget (RX_VK_UPLOAD_NEW_MB, RX_VK_UPLOAD_NEW_MS), and the new textures after them were left for the next frame, the picture held. Only an upload staged from the CPU as it is recorded is moved: not one read on the GPU (the GPU unswizzle, from the pool) or decided from live memory (the all-zero clear), which in the earlier segment's init would run before a segment between writes that memory on the GPU. Not for a texture the GPU drew (its contents are the GPU's; the CPU's writes over it, RX_VK_CPU_OVER_GPU, keep their own path) or a sparse one: those keep the segment's own uploads, and the twin. The uploads' GPU time in an init command buffer is not in the segments' GPU time. 0: every upload in its segment's own uploads, the twin as before. The log's uploads recorded into an earlier segment's init command buffer line every 600 frames (with 0 too) counts them and the bytes, and how often and how long a segment's end waited for its init lock, each segment's own, held while such an upload (or a new image's first layout change) is recorded into its init (its submit waits as long)
RX_VK_SHADOW_KEEP=0 (Triforce) A texture page the submit-time capture takes with the bytes its shadow copy holds (the copy the uploads read, RX_VK_TEX_SAME's compare) keeps that copy as it is, not copied again, its kept hash with it (gpu/vk/shadow_prev.h). Lab S2's Market after some tours: about half of the ~400 texture pages a capture took, six captures a frame, held their copy's bytes. Only for a page the capture takes once; any other is copied as before, and the shadow holds what the capture holds either way. 0: every page copied, as before. The log's texture shadow (600 takes) line counts the pages compared, left, given back and copied
RX_VK_SHADOW_PREV=0 (Triforce) A texture page the capture takes with other bytes keeps the copy it had, and that copy's hash, beside the new one (gpu/vk/shadow_prev.h Prev), and a capture that brings those bytes back gives it back, hash and all: no copy, and the re-upload check after it finds the hashes kept (lab S2's Market after some tours: the other half of those pages went back and forth between two versions, and a check hashed each again after every change, 0.2 to 0.3 ms a frame). A kept copy that does not come back within 8 changes of its page, or within 64 captures, goes; at most 64 MB are kept. 0: none kept, a changed page copied over as before. The texture shadow line says how many are kept and how many went
RX_VK_SHADOW_VERS (Triforce) The copies a texture page keeps beside its own in the shadow (gpu/vk/shadow_prev.h Vers): RX_VK_SHADOW_PREV keeps one, and a page whose captures bring more than two versions (A, B, C, A every few frames) is copied again for every version but the one before the last. 2 to 4 keep that many, newest first, and a capture that brings any kept version's bytes takes that one back, the copy it had becoming the newest, so each version a page cycles through while it is still among the kept copies is copied once: 4 KB a version, under the same 64 MB cap. Unset or 1: one copy, as before. The texture shadow line counts the pages given a copy of their own, one before it, and two or more before
RX_VK_SHADOW_CHECK=1 (Triforce) Each texture page RX_VK_SHADOW_KEEP or RX_VK_SHADOW_PREV left uncopied is compared with the capture's copy again after the capture is taken, and the hashes kept with the shadow's copies are hashed again: the texture shadow check line every 600 captures counts the copies that differ and the hashes that are not of their bytes, both of which must be 0. Slow: for the lab's checks. Unset or 0: not checked
RX_VK_HOLD_MS=<ms> Hold the last picture (gpu/vk/present_hold.h, on by default): a new texture a draw samples after the frame's uploads took their budget (RX_VK_UPLOAD_NEW_MS, RX_VK_UPLOAD_NEW_MB) is uploaded at the next frame, the dummy drawn in its place, and that frame is not shown: the window gets the last complete picture again, the Insert menu, the counters and the notices drawn over it, until a frame is drawn with every texture complete. The game runs on underneath. No frame generation makes a frame from a held one, and the one shown after a hold starts its history anew (and the temporal upscalers theirs). <ms>: the hold's bound (250); at it the rest are uploaded at once and the next frame is shown whatever it holds, and no hold comes for 120 presents (twice as long after each hold at its bound that follows, up to 1920). 0: no hold, no new texture left for later: the one frame that takes them all, as before. The log's vk: hold: lines, the stall line and the 600-frame line count them
RX_VK_HOLD_PIPELINES=0 A frame with draws or dispatches left out because their program, pipeline or compute pipeline was still being made is held as one with a texture still owed its bytes (RX_VK_HOLD_MS's hold, with its bound and its rests; NX2navi's frame hold, gpu/vk/pipe_wait.h): by default the window keeps the last complete picture instead of showing one that lacks a pass. 0: such frames are shown, as before
RX_VK_UPLOAD_NEW_MS=<ms>, RX_VK_UPLOAD_NEW_MB=<MB> The new textures' budget a frame while the hold is on: once the frame's uploads took 12 ms or 64 MB, a new texture is left for the next frame (ASTC ones too; the frame's first upload always goes). 12 ms keeps an area change's frames near 16.7 ms with their draws and memory sync; 64 MB is what the GPU copies or decodes in a few milliseconds, so that no frame leaves it a backlog. 0: that half of the budget off
RX_VK_UPLOAD_SPLIT_MB=<MB> A new layered ASTC texture whose texels are more than this (128) has its first upload in parts while the hold is on, the texture's layers over at most 6 frames (gpu/vk/layer_split.h): its draws sample the dummy and its frames are held until the last part is in; for a dispatch or at the hold's bound what is left goes at once. In the owner's test7 session one 1365 x 1365 x 90 texture kept as BC3 took one frame's upload command buffer 114.8 ms of GPU time. 0: whole, as before. The stall line counts the parts
RX_VK_DUMMY_GEN=0 A frame that left textures for later makes every texture view a draw resolved stale (destroy_gen), as before. By default only the looks that resolved to the dummy for want of their texture are (texture_dummy_generation, vk_draw.cpp texture_view_of); the stall line counts the views resolved anew
RX_VK_VIEW_KEEP=0 Any texture's end (an eviction, a dead render target let go, a texture made BC3 from BC1, the compaction moving one) makes every texture look of every recording thread stale, and each is resolved anew when next met (the slot, the cache, the view, under the parallel replay's lock), as before. By default a thread that finds the destroy generation moved keeps the looks of the textures whose views did not go: those are noted by their creation number before the generation moves (gpu/vk/view_keep.h, vk_draw.cpp texture_view_of); never a look of no texture or no view, nor a flat texture's 3D copy. More than 1024 gone since a thread's last pass: all resolved anew. The log's vk: texture looks kept lines count them, the stall line the views resolved anew. After NX2navi's tex_gen_undo
RX_VK_DESC_KEEP=0 or check The per-binding reuse of a draw's descriptors (gpu/vk/desc_keep.h, on by default): a draw that builds its descriptors takes, for each sampled texture, user uniform buffer, stage's constants and read-only storage buffer, what the program's last draw on that thread resolved it to, while everything it was resolved from is the same: the texture's handle, its slot's registration, the samplers', no texture destroyed or made again, no texture left for later and the same submission; the buffer's address and size, no inline uniform update, no pool moved or mirror made, the same recording. 0: every descriptor resolved, as before (so also with RX_VK_NO_DESC_REUSE, RX_VK_SAMPLER_CACHE=0 and the descriptor diagnostics). check: every descriptor resolved too, and one that comes out otherwise than what was kept for the same inputs is counted and logged (vk: descriptor reuse check): the way to try the rules. The frame statistics' a frame's descriptors line says how many were resolved and taken, how many pushes were whole, of the changed bindings or of nothing, and how many sets were written, through a template, or bound again
RX_VK_DESC_SIG=0 or check The whole-draw skip by the signature of a draw's descriptor inputs (gpu/vk/desc_sig.h, on by default with the per-binding reuse): a draw whose bindings moved, of the program whose descriptors its last draw pushed in that command buffer, first reads what each of them is resolved from (a texture's handle and its slot's version, a user uniform buffer's address and size, a read-only storage buffer's address and size words, a driver bank's stage generation) and the stamps the per-binding reuse gives each kind; when that equals the signature the pushed descriptors were built from, and their build kept every one, the build and the push are left out (a build would take each of them again and push nothing). Push programs only, of the kinds the per-binding reuse keeps: not those with storage buffers they write, tables, texel buffers or storage images, not the mesh fallback or RenoDX's. 0: built, as before. check: built too, and one that comes out otherwise than what is pushed is counted and logged (vk: descriptor signature check). The frame statistics' a frame's descriptor signatures line says how many draws read theirs and how many were kept whole
RX_VK_DESC_SET_KEEP=0, RX_VK_DESC_TEMPLATE=0 A program over the driver's push limit (32 descriptors on NVIDIA's, AMD's and Intel's drivers) has a set written for each draw that builds its descriptors. By default a set whose descriptors are all as those of the last one written for that layout in the recording is bound again instead, while no texture was destroyed or made again and no pool moved, and a set written is written through the program's descriptor update template (Vulkan 1.1). (Triforce, after NX2navi's desc_template) A program within the push limit has its descriptors pushed whole (in a new command buffer, or after another program at its bind point) through a push descriptor template of its own (vkCmdPushDescriptorSetWithTemplateKHR, one a program and bind point, from the same entries and packed array as a set's), not with the write structs the driver walks one by one; a push of the changed bindings only keeps its write structs. The frame statistics' a frame's descriptors line counts the pushes made through it. With RX_VK_RECORDER the packet copies the packed array (gpu/vk/vk_recorder.h). RX_VK_DESC_SET_KEEP=0: a new set each time; RX_VK_DESC_TEMPLATE=0: sets written and pushes made with the write structs; both as before
RX_VK_CREATE_NEW_MS=<ms> While the hold is on, a sampled texture seen for the first time once the frame's makes took this long (8), or its uploads their budget, is not made yet (vk_texture.cpp create_later): the draw samples the dummy, the frame is held, the next frame makes it. The frame's first make always goes; never a dispatch's. 0: made at once, as before (a texture left for later was made all the same). The stall line counts the textures made, their time, those not made yet, and the images made
RX_VK_UNSWIZZLE_MT_MB=<MB> A block-linear level unswizzled on the CPU is split over several threads (a thread for each 2 MB, 8 at most) from this size (4); 16: from 16 MB, as before
RX_VK_PROGRAM_READAHEAD=<n> After a draw reads a program from the program cache itself, or takes one read ahead, workers read the next n programs (32) and keep them made for the draws that come to them, 512 at most (gpu/vk/program_readahead.h). 0: none, as before. The log's vk: programs from the cache lines and the stall line count them
RX_VK_PROGRAM_READ_UNLOCKED=0 A draw that reads a program from the program cache itself, or waits for one the read-ahead's worker is reading, lets the shaders' lock go meanwhile, so that the replay's helper threads go on picking their own programs (they queued behind it: "the program picks waited 169 ms for the shaders' lock" at the Market's arrival); a second draw of that program waits for the first's result, and the record stays listed until it is read (gpu/vk/program_read_once.h). A program's release waits until no pick has the lock let go. 0: read and waited for under the lock, as before. The stall line counts the waits for another draw's read, and the picks' waits to take the lock again with their waits for it
RX_VK_STAGE_CODE_CACHE=<MB> What a program pick made of a stage's bytes (the control section and the code area read from guest memory: its code key, the instructions lowered to Maxwell) is kept by those bytes, 64 MB at most, the least recently used going first: a program object met for the first time whose stages' bytes were met before (the game makes them again at loads) takes a copy instead of decoding them again under the shaders' lock (gpu/vk/stage_code_cache.h; an entry is taken only for the same bytes, byte for byte). The save's load-in frame said "the program picks read the stages' code 45.6 ms": a stage was some 60 us to read and decode, and is 3 us to find. 0: none, each stage decoded again for each program object, as before. The log's vk: the stages' code read for the program picks lines count them
RX_VK_STAGE_CODE_LAZY=0 A program pick reads the stages of a program object it meets for the first time without lowering their code: their keys, NVN stages and headers (what finds the program) come from the control sections and code areas, and the code is lowered (and kept, RX_VK_STAGE_CODE_CACHE) only when the pick translates a variant. A program found in memory, read ahead or in the program cache was made from stages that lower (its key names them); one not found has its stages lowered before it is translated, and should one not lower, the pick starts again from those that do: the program it was before (gpu/vk/stage_code_cache.h). The save's load-in frame lowered every stage of each program object met, 48 of a stage's 60 us, for programs all prepared before the title. Not with RX_VK_REJECT_STAGES, RX_VK_REJECT_KEYS, RX_VK_OLD_LOWERING, RX_VK_DUMP_NATIVE or RX_VK_DUMP_FAILED, which act in the lowering. 0: each stage lowered as it is read, as before. The log's vk: the stages' code read for the program picks lines count the stages read without lowering and those lowered since
RX_VK_STAGE_CODE_UNLOCKED=0 A program pick reads the stages of a program object it meets for the first time (guest memory, their keys, the stage code cache) with the shaders' lock let go, as a draw's own read of a program (gpu/vk/program_read_once.h: a program's release waits until no pick has the lock let go), so that the replay's helper threads go on picking their own programs meanwhile; two picks of one object at once each read it, and the first list put stands. 0: read under the lock, as before. The stall line's "the program picks read the stages' code" counts the read and the lock's taking again
RX_VK_PROGRAM_ORDER=0 Each session writes the order its draws first needed their programs in (read from the program cache, or translated), the first 4096, into triforce_program_order.bin beside the cache now and then (this session's first, then those of the sessions before it has not met). The next session's read-ahead workers, from the first draw on (the title and the file select), read those programs in that order whenever no draw asks them for anything, the whole order, and keep them made apart from the shelf until a draw takes them (RX_VK_PROGRAM_ORDER_KEEP below; gpu/vk/program_order.h): the save's load-in frame read some 100 programs on the draws' threads before. Not with the RAM low. 0: neither read nor written, as before. The stall line says why the draws read what they still read themselves (named by no order, read ahead and let go before, not read ahead yet) and how many they took in this order; the log says once when the whole order has been gone through, and how many programs it keeps
RX_VK_PROGRAM_ORDER_KEEP=0 A program read ahead in the last sessions' order stays until a draw takes it, whatever the draws meet meanwhile, and nothing in the order is passed by: the workers read all of it (4096 at most) while the title and the file select stand still, and a program a draw's ask read that the order names is kept with these, not on the shelf, which lets its oldest go. Only a RAM gone short lets them go (all of them). The pipelines' warm keeps its window: the first 512 kept and not taken are read with it, those beyond without, each warmed as the draws take warmed ones (the nearest first). Some 40 to 50 KB a program packed: the owner's order of 2411 programs some 100 to 120 MB, 4096 at most some 200 MB. The owner's test37 session (SDR, where the order's sessions were HDR Native) took another path through the order and its load-in frame read 115 programs itself, 64 of them read ahead and let go as behind where the draws were, 51 passed by. 0: the rules before: 512 at most, each until the draws are 256 places past it (where the draws are: the middle place of the last 16 programs they needed first), what lies behind not read
RX_VK_PROGRAM_READAHEAD_NOTES=0 The read-ahead's next programs are those after it in the pipeline notes' order (the order earlier sessions first built their pipelines: an area's programs lie together), 4 workers, the compute programs too (in the order play first dispatched them, triforce_computes.bin), and a full shelf lets its oldest go; the program cache file's order only for a program neither names. 0: the file's order (since the shaders are prepared before the title, the preparation's), one worker, no compute programs, and nothing more read once 512 wait, as before (test16's file select load took 7 of some 600 programs read ahead that way)
RX_VK_PIPELINE_WARM=0 or 1 Where the precompile keeps no pipelines (the RAM spared) and the fast pipeline link is on, the read-ahead's worker that has just read a program makes, before any draw can have it, the stage libraries of the pipelines the pipeline notes name for it (asked of the caches only: one the driver would have to compile is left to its draw) and links them; the draw takes the link made in place of linking its own, and the whole build follows as before (gpu/vk/pipe_warm.h). At most 32 notes a program variant, 512 links held for draws that have not come (the oldest let go beyond) and 1024 libraries no draw has had; nothing made while the RAM is low or short, and what is held goes back to the driver while it is short. 0: none, as before; 1: the libraries only. The log's vk: pipelines made behind the draws lines count them
RX_VK_PIPELINE_WARM_FOLLOW=1 Off by default (test19: the lab's tour showed no gain). 1: the warm follows the draws: a program read within 64 places (in the notes' order) after one the draws consumed in the last 2 s has its libraries made and linked, one within 192 its libraries only, one farther (or once the draws stopped taking) nothing; and the libraries no draw has had are kept up to 2048, the oldest let go beyond (with the links made from it), so the bound never stops the warm (gpu/vk/pipe_warm.h, test18: 2266 links made, 276 taken, the libraries at their bound from the load on); it spends at most 250 ms of the workers' time a second (500 saved up), and never makes again a library it let go. Off: every program read is warmed whole and the libraries stop at 1024, as before
RX_VK_COMPUTE_WARM=1 Off by default (test19: the lab's tour showed no gain). 1: where the precompile keeps no pipelines, the read-ahead's worker that has just read a compute program play dispatched (triforce_computes.bin) makes its compute pipeline, asked of the caches only, as its first dispatch would; the dispatch that takes the program has it. One a program while it waits on the read-ahead's shelf, destroyed when the shelf lets the program go and given back while the RAM is short; once a program variant a session. Off: each compute pipeline is made at its first dispatch, as before
RX_VK_PIPELINE_ORDER=0 Each session writes the order its draws first needed their pipelines in (a new one, or one the precompile kept that no draw had), the first 4096, into triforce_pipeline_order.bin beside the pipeline notes now and then, from the presents on a thread of its own (this session's first, then those of the sessions before it has not met). Where the pipeline warm runs (RX_VK_PIPELINE_WARM), the next session finds each one's note before play and the warm makes, for a program variant the read-ahead has read, the pipelines that order names for it and no other (32 at most a variant; the notes' other pipelines are not made then, and the warm does not follow the draws): their stage libraries asked of the caches and their links, held for the draws by their place in the order, 1024 at most (beyond, the farthest ahead goes, and none is made farther), and 2048 libraries no draw has had at most. Where the draws are: the middle place of the last 16 pipelines they needed first; a link held 512 places behind it goes with the libraries only it held, and none is made there (gpu/vk/pipe_order.h): the save's load-in frame made 86 to 92 ms of pipelines on the draws' threads, the warm's links from the notes let go before the load came (lab round 37: 1964 made, 54 taken). The first session after this writes the file; the next one has it. 0: neither read nor written, the warm from the notes as before. The stall line counts the pipelines new to the draws, those linked ahead (of them in this order), and the links and stage libraries the draws made themselves; the log's vk: pipelines made ahead in the order lines the rest
RX_VK_VRAM_MB=<MB> The texture cache's budget as a fixed size, whatever the card. Unset: on a card the driver allows more than 8.5 GB, no size (RX_VK_TEX_PRESSURE); on a smaller one 45% of what the driver allows; with RX_VK_TEX_PRESSURE=0 70% of it above 8.5 GB, at most 6 GB (the rule before)
RX_VK_TEX_PRESSURE=0 or =<pct> (Triforce, after NX2navi's TEX_VRAM_PRESSURE) On a card the driver allows more than 8.5 GB, with VK_EXT_memory_budget, not an integrated GPU, without RX_VK_VRAM_MB and without a quality preset whose budget applies, the texture budget follows the live use instead of the fixed 6 GB: textures go once the driver's count, less the free space in the blocks they can take back, is past 80% of what the driver allows now, the least recently used first, each unused 2 s or more, 64 a pass, down to 2% under that line (gpu/vk/tex_pressure.h); the 90% and 97% rules and the compaction's lines stay. While the system's commit is low the fixed size comes back (RX_VK_TEX_COMMIT_FREE_MB). 0: the fixed size, as before; <pct>: that line (50 to 95). The log's vk: texture budget line at the start says which, and the vk: VRAM: line every 600 presents the budget (by live use: what the textures may hold before the line) and the line
RX_VK_TEX_KEEP_TAKEN=0 (Triforce, after NX2navi's TEX_KEEP_TAKEN) While VRAM is short, a texture uploaded from memory that the game let go 30 presents ago goes first (RX_VK_LET_GO_PCT); one the game has taken back before waits 8 times the longest it stayed let go before a take-back, when that is longer (gpu/vk/tex_pressure.h): made again, the frame that wants it draws the dummy (NX2navi: Kakariko's haze gone every few seconds). The eviction by age still takes it. 0: the 30 presents alone, as before
RX_VK_TEX_COME_BACK=0 (Triforce, after NX2navi's pause for drops that come back) Where the budget follows the live use: when in 240 presents 64 or more textures the line let go went and half or more of them were made again within 600, the line stands aside for 600 presents, doubled at each such period up to 7200; a period with fewer back ends the doubling (gpu/vk/tex_pressure.h ComeBack). The 90% and 97% rules and the compaction's lines still hold meanwhile. The log says when a pause begins. 0: no pause
RX_VK_TEX_STEP=<n> The live textures one pass of texture_sweep over the budget lets go of at most (64 where the budget follows the live use; the render targets drawn over since do not count), the rest at the next look two presents on, not ten. Set, on any card, the fixed size's too; 0: no step, one cut as before
RX_VK_TEX_COMMIT_FREE_MB=<MB> Where the budget follows the live use: while less of the system's commit than that is free (the default: the larger of 4 GB and a tenth of the limit, NX2navi's), the fixed size is the budget again (Windows charges a discrete card's memory to the commit, and an allocation that fails there ends the game). 0: never. Not on Linux
RX_VK_SWEEP_ALL=1 Every texture of the cache ordered by its last use for every pass of vk_texture.cpp texture_sweep, as before. By default a pass under the budget (every 10 presents, and the dead render targets' passes between them) orders only the textures it can take: those the GPU drew and those the game let go; the others it passes over all the same. Over the budget every texture is ordered. The log's "passes for the dead render targets between the looks" line says what a pass costs
RX_VK_TEX_RATE_HIGH=0 The texture eviction's waits (vk_texture.cpp texture_sweep: 60 presents unused over the budget, 30 after the game let a texture go, 600 or 3600 for one the GPU drew, the compaction's 600 and 1800) count presents above 60 a second, as before. By default they count their seconds at any rate up to 480 a second (gpu/vk/present_rate.h, after NX2navi's M19): at the Market's 94 a second "60 presents" were 0.64 s. Below 60 they count seconds unless RX_VK_TEX_RATE_LOW=0. The log says the first time a run goes above 68 a second
RX_VK_TEX_DETAIL=full, reduced or low The texture detail for one run, over the Insert menu's Texture detail row: whole textures, or the large ones without their largest level, or without two (gpu/vk/tex_detail.h). Unset, the row decides, and its Automatic goes by what the driver allows: full from 10,240 MB, low under 6,144 MB, never full on an integrated GPU
RX_VK_TEX_BC1=0/1 Opaque ASTC textures kept as BC1 instead of BC3 for one run, or not, over the Debug tab's Opaque textures as BC1 row (on by default since options_version 5): a texture the renderer keeps as BC3 whose every block the GPU decoder writes opaque is encoded as BC1, half the video memory, the same texels (gpu/vk/tex_bc1.h, gpu/vk/astc_opaque.h). One whose memory later holds blocks with alpha, or that a copy on the GPU writes, becomes BC3 for good; the log counts both
RX_VK_COMPACT=1, RX_VK_COMPACT_PCT=<50..90>, RX_VK_COMPACT_MB=<MB> VRAM compaction (off by default): the textures that are not render targets in a pool of their own, moved out of sparsely used blocks a few a present so that the blocks go back to the driver, and the texture budget holding the driver's count at that share of what it allows (85); the free space that starts a run (512; 192 while the count is over 90%)
RX_VK_SKIP_COMPRESSED_OVER_RT=1 A compressed (ASTC, BC, ETC2/EAC) texture made over storage render targets used is not uploaded, as before: bosses and new enemies all blue the first time
RX_VK_NO_WRITEBACK (set) GPU writes to mirrored pools are not copied back to guest memory (an experiment, for A/B)
RX_VK_WB_DIFF=0 Write-backs copy every byte again instead of only what changed against a VRAM shadow (the diff is on by default; v2.0.9 and v2.0.10 had it off, issue 1161)
RX_VK_LAZY_WB=1, =2 or =0 The lazy write-back for one run, over the Debug tab's Lazy write-back row (lazy_write-back=1; on by default since options_version 5; docs/lazy-writeback.md, gpu/vk/wb_lazy_state.h): a whole page of what shaders write into a mirrored pool that the CPU leaves alone is no longer copied back at every submission; its page has no access, and whoever touches it (the game's code or the host's, by a fault; a host call that hands it to the kernel; the GPU through the import) has it copied down first. Windows only. On AMD's driver the row alone leaves it off, as NX2navi did after games ended in play there; =1 turns it on anyway. =2 is the self-check: every copy is still made, the pages are protected and paid as if not, and each payment compares what it would have copied with guest memory: a MISMATCH at guest line is a page it would have got wrong. The log says vk: lazy write-back on (or why off) at the start, and every 600 submits vk: lazy write-back (600 submits): the MB not copied, the pages owed, the pages paid by a fault, a host call, a GPU read, a mirror given up and a recording's submit, the payments and their time, and what failed
RX_VK_LAZY_PAYERS=<1..4> (Triforce, 4 by default; =1 as before) How many of the lazy write-back's payments copy at once (gpu/vk/wb_lazy_payers.h, NX2navi's wb_lazy_unlocked). A payment's copy goes onto the queue after everything submitted so far and its thread waits for it (0.5 to 3 ms each in the owner's sessions, up to 21 ms at a load); with one at a time, a second thread that touched another owed page, or the replay giving a mirror up, waited for the first one's copy to come back before its own went onto the queue. Each payment holds a slot of its own (a command buffer and a fence); the pages of two payments are never the same ones (gpu/vk/wb_lazy_state.h), and each copy still goes onto the one queue after everything before it. The 600-submit line vk: lazy write-back (600 submits) ends with the payments that waited for a free slot and the most slots in use at once
RX_VK_GEN_SEED=<n> The page write generations (gpu/vk/write_gen.h) start at n and not at 1 (decimal, or hex with 0x; 2^62 at most). They are 64 bits; the 32-bit ones of earlier builds ran out after days of play, and textures and mirrors then kept old contents. RX_VK_GEN_SEED=0xFFFF0000 takes a play test across 2^32 within seconds: the log says the write generations start at and, at the crossing, this run has made 4294967296 write generations, and nothing in the picture should change there
RX_VK_DLSS=0/1/2, RX_VK_DLSS_PRESET=<letter>, RX_VK_DLSS_LOG=1, RX_VK_REFLEX, RX_VK_REFLEX_LOG=1, RX_VK_ANTILAG=0/1 NVIDIA DLSS and Reflex, and AMD Anti-Lag 2, for one run (=- on Reflex or Anti-Lag 2: its extensions not even enabled): the readme's NVIDIA DLSS section. RX_VK_DLSS_TRACE=<frames> logs one frame's large draws every that many frames, RX_VK_DLSS_DEBUG=motion shows the motion vectors, =alternate the game's own upscale every other frame
RX_VK_FSR4=0/1/2, RX_VK_FSR_DIR=<folder> AMD FSR 4 for one run (0 never, 1 FSR 4, 2 its Native AA), and another folder for AMD's DLLs (not from hookshot_env.txt): the readme's AMD FSR 4 section. RX_VK_FSR4=1/2 and RX_VK_DLSS=1/2 go over the Upscaler row, a saved FSR 3.1 too where the engine they ask for runs; RX_VK_FSR=1 goes over them (one upscaler at a time; =2: FSR 3.1 as its Native AA, the 3D at full size). The DLSS trace and debug switches above apply to FSR 4 too, on the frame chain they share
RX_VK_FSR4_FG=0/1 AMD FSR 4's frame generation, the Frame generation row's AMD FSR 4 (gpu/vk/vk_fsr4.cpp fsr4fg): 0 never in this run (RX_VK_FSR4=0 too, which keeps AMD's library unloaded); 1 any frame generation AMD's library lists for the card counts, an FSR 3.1 one too, so the path can be tried on a card without FSR 4's (the row then offers AMD FSR 4 there; the log names the version in use)
TRIFORCE_MENU_AHEAD=0 (Triforce) What the options' rows ask of NVIDIA's and AMD's libraries (whether DLSS, FSR 4 and FSR 4's frame generation run here: NGX's start, AMD's loader) asked at the options' open on the presenting thread, as before, and not once on a thread of its own as soon as the game runs (gpu/vk/vk_menu.cpp menu_ahead; its log line says how long each took). For comparing: the first open waited about 2 s for them in test11
RX_VK_AA=<0..3>, RX_VK_AA_KEEP=1 The anti-aliasing for one run, over the Insert menu's Anti-aliasing row: 0 the game's own SMAA, 1 none, 2 FXAA, 3 SMAA at its Ultra preset in its place (gpu/vk/aa_rows.h, gpu/vk/vk_aa.cpp). Unset, the row decides; with DLSS, DLAA or FSR drawing, neither applies. The game's SMAA is three compute programs known by their keys (game build e0f3ccfa): with another choice in effect its composition is replaced and its edge and weight passes are left out, and RX_VK_AA_KEEP=1 keeps those two running. The log says vk: aa: when a composition is first replaced, why one was left to the game, and when none was found for a minute
RX_VK_ASYNC=1 The replay on a thread of its own instead of the game's submitting thread
RX_VK_OCC_QUERY=0, RX_VK_OCC_QUERY_SKIP=<addr>[,...], RX_VK_OCC_COND=0, RX_VK_OCC_LOG_COND=1 (on by default since 11-17: +2.7 to +4.6% fps in every scene measured, 10-12% fewer draws, no flicker added; RX_VK_OCC_QUERY=0 turns it off) The game's samples-passed reports (which objects show; a count of 0 is not drawn) get their real counts: the replay still writes each report as it passes it with 4096 (RX_VK_OCC_FIXED, everything visible), and the draws from its reset are counted by Vulkan occlusion queries (precise where the card has them); once the GPU is done with the recording that holds them the count is written into the report's record over the 4096, as NX2navi writes it at completion. The done recordings are found with one look at the recordings' timeline (nothing waits) as a game's fence wait ends (the game reads its counts after it), at each recording's begin and each present, at the latest when the recording's slot comes round. The game's report records rotate (a ring: an address is another object's at its next report), so a count is written only while its report is still the newest at its address, and only when it is whole (every query available, no draw left out, reset and report in one recording, read back within 8 presents); otherwise the record keeps its 4096. The game also predicates draws and clears on these words (render conditions), decided as NX2navi decides them: a word whose newest report is a samples-passed one whose count is still to come is unknown and the condition renders; a word whose count was written (or for which none comes) is read from memory as before, where a written 0 skips the draws and clears it gates. A count goes in only over the value the replay left in the word (a compare-and-write: never over the game's CPU re-arming the record), and a record rewritten in the stream after its report (a small buffer clear, a report of another counter type) gets no count. A parallel replay's segments signal the recordings' timeline and are sealed as they are submitted, so their counts are written too. The count word is written as the replay writes a report (guest_cpu_write, and the word kept out of the mirrors' write-backs). With hostQueryReset (Vulkan 1.2) a recording's queries are reset on the CPU once read, only those it used. RX_VK_OCC_QUERY_SKIP: report addresses that keep the fixed answer (the log's occlusion query sites lines list the first 64 addresses with their counts). The log's occlusion queries line every 600 presents: the reports, how many were counted whole and why not, the counts written at completion (and of them 0), those not written and why (lost, superseded by a later report at the address, late, a render condition's), the mean latency in presents and how many were written after the next present, where the done recordings were found, and the render conditions on samples-passed words (rendered because a count was pending, rendered or skipped from a written count, from memory with no count to come, as before in the knob's off phases) with the draws and clears they skipped. RX_VK_OCC_COND=0: a condition on a samples-passed word always renders (the counts are still written), to tell the counts from the skips. RX_VK_OCC_LOG_COND=1: one such condition in 499 logged (300 lines), with both words, their sources (pending, written, memory) and the present. Lab: the knob occq in RX_VK_LAB_AB runs the queries the whole run and writes the counts of the reports made in its phases (gpu/vk/occ_answer.h, vk_replay.cpp "occlusion queries")
RX_VK_GATE_WAIT_MS=<1..100> (Triforce, off unless set, after NX2navi's gate_wait_ms, whose default is 10; not yet run in the game) A submission whose first command buffer begins (after state only) with a wait for an event the game signals from the CPU, unmet in the replay's order, waits at its submit for that signal, at most this long, before its capture and its replay (gpu/vk/gate_wait.h, gpu/vk/vk_replay.cpp gate_wait_signal): the capture then holds what the game wrote up to its signal, and the submission is replayed in the submit call on the submitting thread, instead of stopping at the wait and going on from the order thread (sync_watch) with a second capture once the signal came. The wait holds no lock and looks at the event's word in the game's memory. One that runs out goes as before; after 4 that ran out, once they are more than a tenth, it is off for the run (logged). A vk: RX_VK_GATE_WAIT_MS line every 600 waits gives their mean and how many ran out; the order line's captures at a CPU event's wait and made to go by presents say how often the old way was taken
RX_VK_CAPTURE_BEHIND=0 (Triforce, on by default; =0 as before) The submit-time capture (gpu/vk/vk_memory.cpp capture_make) takes the write marks on the game's submitting thread and copies there only the pages read at once (the late pages and the texture storage); the rest of its copies, in parts of 32 pages, go to the capture's copy helpers while that thread replays the submission (gpu/vk/capture_behind.h). A read of a page as submitted copies its part itself when no helper has taken it yet, or waits for the helper; every part is done and flushed before a recording is submitted and before the thread goes back to the game. Only with the replay on the submitting thread (not RX_VK_ASYNC=1), with copy helpers (RX_VK_CAPTURE_THREADS, not RX_VK_LOW_SPEC), at least 128 pages behind and at most 512 ahead (a scene's load: copied whole as before). At the Market the old copy was ~0.25 ms of each submit's ~0.35 ms capture, six submits a frame. The 120-present line a frame's captures at the game's submits gives their time on the game's threads (the scan, the copies made there, and the copies behind made or waited for by the replay), the MB copied and behind, and who copied the parts; the stall line names the captures when they took 1 ms or more
RX_VK_PARALLEL=<0..8>, RX_VK_PARALLEL_AUTO=<2..8> The parallel replay: a frame's large command buffers recorded on that many threads, always, or wherever short trials as the game runs find it faster than the replay thread alone; RX_VK_PARALLEL=0: never. The Debug tab's Replay helper threads row is the second without an environment to set (replay_helper_threads= 1 to 7 for 2 to 8 threads); either switch goes over the row. The row's Automatic (8), which it is unless the options file says otherwise, is the count gpu/vk/replay_threads.h gives the PC: none, on every PC since 11-17 (it was 2 or 3 with five cores or more: in the owner's play the helper threads brought 10-25 s stretches at 39-48 fps when moving, the game's own frame time 4 to 10-13 ms, and with none there were none); a count on the row, or RX_VK_PARALLEL_AUTO, still runs them. The log says at the start what was chosen (replay helper threads:) and at each trial which way is in use (parallel replay, trial). Between trials the tuner's rule (gpu/vk/replay_threads.h rule) judges every 120 frames on the replay thread alone: where the replay is plainly the frame's limit (70% of the frame or more) and the helper threads would take at least 1 ms and a tenth of the frame off it, never counting below the GPU's time (the game waits for each frame's GPU work), they are turned on without a trial; where they cannot pay (no command buffer large enough to cut, the GPU's time about as long as the replay's, or the replay under 60% of the frame: the game's own threads are its limit) no trial is made while that holds; trials decide the rest, and a trial that takes the helpers back off holds the rule's "on" for 3,600 presents. The log says so (parallel replay, the rule) when its verdict changes. RX_VK_PARALLEL_RULE=0: trials only, as before. With DLSS or FSR on, for upscaling or frame generation, the dry pass tells their hooks in the draws in stream order, and each command buffer from the first draw or dispatch that takes what they noted (the upscale, or the engine's point before the bloom) on is recorded in order after the segments before it (gpu/vk/stream_order.h); RX_VK_PARALLEL_TEMPORAL=0: the replay thread records alone then, as before. The frame statistics' a frame's parallel replay: line says in how many frames the threads recorded, the command buffers in segments and alone (and why), and the time in them; the next one (its parts) where that time went: the setup before the threads begin, how soon each command buffer's first segment reached the GPU, the helper threads' wake-up, each command buffer's longest segment, the replay thread's wait, the submits, the recording lock's waits, and the segments' GPU time (the GPU time line counts the segments too; it left them out). After each trial's line a trial N's parts line gives its three parts' frame, replay thread's time, GPU time, the rest of the frame, full barriers and draws, and the helper threads' parts. That header lists what an audit of the parallel replay found and fixed, and what is left. RX_VK_NO_DRY_COPIES=1: the dry pass does not mark what copies and texture clears write, as before. The replay thread records the next segment to submit itself when no helper thread has begun it (it only waited before, on the core kept for it); RX_VK_PARALLEL_OWN=0: it waits for the helper threads, as before. RX_VK_PARALLEL_SEG=<32..>: the draws and dispatches a segment is cut for (160); RX_VK_PARALLEL_SEGS=<2..12>: the most segments a command buffer is cut into (6), without which a smaller RX_VK_PARALLEL_SEG cuts no finer once a command buffer has six segments' worth
RX_VK_PARALLEL_BACKOFF=0 The tuner's trials as before: one every 1,800 presents after one that kept the way, each with 104 frames the other way. With the back-off (the default, gpu/vk/replay_threads.h Tuner) each trial that keeps the way, the other way longer than both of its own parts, puts the next one off twice as long (3,600, 7,200, then 14,400 presents at most; a margin of 10% or more counts twice), one too close to tell keeps the old interval (the first such one after a change of scene or way: 900 presents), and once the way has held so the other way is tried for 64 frames, not 104; a short trial that finds the other way shorter changes nothing itself, a full trial follows at once. The next trial comes early (900 presents after the last one at the soonest, never while the rule says no trial) when the scene clearly changes: two windows of 120 frames in a row whose draws moved by a quarter (200 at least) or whose replay or GPU time moved by 30% (1 ms at least) from the first window after the way was set, or a trial whose first and last parts did. In the lab's steady Market a trial came every ~2,090 presents, each ~100 frames 1.9 ms longer; the trial lines now end with when the next may come, and parallel replay, the scene changed says when one was brought forward
RX_VK_RECORDER=thread, =defer, =sync (off unless set; not yet measured in the game) thread: the replay thread's vkCmd* calls packed with copies of their arguments into a ring and made by a recorder thread of their own, in order (gpu/vk/vk_recorder.h); the replay thread waits for it at every command buffer begin, end and reset, submit, wait, readback and destruction. Beside the Replay helper threads too (no longer refused with RX_VK_PARALLEL): a parallel replay's segments make their calls themselves, after the ring has been run (segments_begin), and the recorder is idle while they record. With it on, the frame statistics' a frame's recorder thread line says how many of the replay's calls it made a frame and in how long, and how long the replay thread waited for it; what it saves is the replay time line's commands with it against without it. defer and sync are its test steps (held and run on the same thread). RX_VK_RECORDER_RING_MB (8), RX_VK_RECORDER_SPIN_US, RX_VK_RECORDER_STATS=0, RX_VK_RECORDER_POISON=1, RX_VK_RECORDER_PIN (next, sibling or a mask)
RX_VK_REPLAY_PRIO=0 or 1 (Triforce, on by default, after NX2navi's recorder_prio; =0 as before) A thread runs at the highest priority while it replays the game's frames (the submitting thread's replay and its capture, the present, the stopped work the order thread lets on: gpu/vk/vk_replay.cpp ReplayPin) and gets its own priority back after, so the game's code it runs between replays keeps the game's priority; the core kept for the replay is kept from the game's threads only, and the helper threads and the capture's copy helpers (above normal) outranked a replay at the game's priority there. A thread at that priority or above already is left alone. The replay thread of RX_VK_ASYNC=1 and the recorder thread of RX_VK_RECORDER=thread take the level for good. =1: above normal. The log's vk: a thread that replays runs at line says which (gpu/vk/replay_prio.h)
HOS_VCORES=0, HOS_CORES=<1..8>, HOS_RESERVE_CORE=0 No virtual cores; the cores the game sees (6); no core kept for the replay (one is, with 8 or more logical processors)
HOS_VCORE_SPIN_US=<us>, HOS_VCORE_SPIN_MAX=<n> (Triforce, on by default; HOS_VCORE_SPIN_US=0 as before) A game thread that waits for a virtual core it asked a holder to give up spins for it, up to 250 us, before it sleeps (host/hos_thread.c vc_spin, after NX2navi's core_take): the holder gives the core up at its next checkpoint, mostly within microseconds, and the waiter then runs without an OS wake. Who gets a core does not change, only how soon. At most HOS_VCORE_SPIN_MAX threads spin at once and the rest sleep at once: by default a quarter of the logical processors beyond 8, at most 4 (none with 8 or fewer, 1 with 12, 2 with 16). The vcores: line (every 5 s) counts the waits that ended in the spin and those that slept, the time spun, the spins left out for the cap, and how soon a granted core ran after a spin and after a sleep; the start's vcores: a waiter spins up to line says what is in effect. A yield with no thread waiting for a core takes no lock (NX2navi's yield fast path)
RX_VK_HELPER_SPIN_US=<us> (Triforce, on by default; =0 as before) The parallel replay's spins (gpu/vk/helper_spin.h, after NX2navi's replay workers): a helper thread with no segment to record spins up to 100 us for the next before it sleeps, and the replay thread spins as long for a segment a helper records before it sleeps for it. The frame statistics' its spins line, after the parallel replay's parts, says how often each ended in the spin or slept and the time spun
HOS_X3D=0 (Windows) The game's threads and the replay's core are not kept on the die with the largest L3 cache. By default they are, on a processor whose L3 caches differ in size and whose largest serves 8 or more cores (AMD's two-die X3D parts: a 7950X3D's or 9950X3D's 3D V-Cache die; host/hos_x3d.h), and the log's cpu: logical processors ... share the largest L3 cache line says so. On every other processor nothing changes and the log has no such line
HOS_POWER_THROTTLING=1 (Windows) Windows' power throttling of a window not in front left as it is (for A/B runs). By default every run, the shader preparation's too, opts out of it at the start: full speed, not the efficiency speed (EcoQoS) Windows 11 gives such a process, and the 1 ms timer resolution kept, which Windows 11 may otherwise ignore for it (Windows 10: full speed only). The log's power: line says what Windows took
HOS_HOST_ZSTD=1 or 2 The game's files (.zs) decoded by the host's zstd (third_party/zstd) instead of the game's own translated decoder; off unless set, and nobody has played with it on. 1: the host decodes what host/host_zstd.h takes (whole buffers, and the loading threads' streams with their content size and room for it), the game's code the rest, errors included. 2: check, the game's code decodes everything as before and the host beside it, and the log's zstd check: ... MISMATCH lines name every difference (its zstd: lines count what was compared): the way to try it before 1. Game build e0f3ccfa only. The lift needs both of its calls (nx2/oot_patches.py patch_host_zstd): a build log that says the host's zstd decoder's calls were found at 1 of 2 places has one only, and the switch then covers only that function

Building

A build reads and writes tens of gigabytes. When the game folder or the build files folder is on a hard drive, make_game.py warns that an SSD is much faster and builds anyway (the builders ask before they start).

Switch What it does
HOOKSHOT_JOBS=<n> (or --jobs) Compilers at once (default one per CPU thread, each started when the free memory holds it; HOOKSHOT_MEM_GATE=0 turns that check off)
HOOKSHOT_LIFT_JOBS=<n> Processes that write the lifted C. Forked on Linux and macOS: default the cores, at most 16, one per 2 GB of free memory. Spawned on Windows (nx2/emit_pool.py), where they also cut the big chunks and share the page marks: default half the processors, at most 8, one per GB of free memory. 1: one process, on every system; the C is the same whatever the count
HOOKSHOT_KEEP_BUILD_FILES=1 Keeps the lifted C and the objects after a build, so that the next one compiles only what changed
HOOKSHOT_EARLY_COMPILE=0 (Windows) Not compiled beside the lift: libopus and the two renderers, which need no translated code. By default make_game.py starts build.py with RX_EARLY=1 for them while the game is translated (the lift's own processes take at most half the processors there), and the build proper finds their objects made
HOOKSHOT_MEM_GIANT=1 or 0 Whether the memory gate counts a function of 1.2 MB or more by the square of its size (a chunk that is one 5 MB function takes 6.2 GB, not the 1.9 GB it is counted at otherwise). By default only on a PC with less than 14 GB free when the compile starts: with more, counting the giants in full halves the compilers running at once for no need
HOOKSHOT_MEM_LOG=1 For each file compiled, @@mem <file> <peak MB> <counted MB> <seconds>: the most memory its compiler was seen holding, beside what the memory gate counted it at (mem_need in nx2/build.py). For fitting the gate after a change to the lift or the compiler
HOOKSHOT_MINGW=<dir>, HOOKSHOT_MSVC=1 The llvm-mingw to build with; the Visual Studio route instead
HOOKSHOT_SINGLE_INSTANCE=0 (Triforce) Hookshot Builder takes no lock on its build tools, as before. By default a second builder for the same tools folder (builder/HookshotBuilder/Instance.cs, named after Tools.Root), its --cli included, waits up to 5 s for one that is ending, then says so and ends: two of them built into one work folder and stopped each other's build. Triforce Setup has its own lock (setup/Guard.cs Instance)
TRIFORCE_LEGACY_PATHS=1 (Triforce) Triforce Setup keeps .NET Framework's legacy path checks, which refuse paths of 260 characters and more whatever its manifest says (an exe csc builds is taken as written for .NET 4.0). By default setup/Setup.cs Main sets the two switches 4.6.2 defaults to (Switch.System.IO.UseLegacyPathHandling, Switch.System.IO.BlockLongPaths) before any path is used, so that with Windows' own LongPathsEnabled on Setup reads and writes deep paths
RX_CPM=<dir>, WGPU_NATIVE=<dir> The CPM cache (Vulkan and SPIR-V headers, VMA, FFmpeg) and wgpu-native
RX_TARGET=windows On Linux: the Windows game, with llvm-mingw's Linux build in HOOKSHOT_MINGW
RX_RELEASE=1 A release build (make_game.py sets it): no console window, the shaders prepared before the title
RX_PGO=gen or RX_PGO=<file> The hot code counting its branches for a profile, or built with one (make_game.py passes the shipped profile)
RX_MARCH=<level> The CPU level to build for (default this PC's: x86-64-v3, else x86-64-v2, else x86-64)
RX_VK_ONLY=1 Only the Vulkan back end, with no lift
OOT_WORK, OOT_DUMP, OOT_EXEFS, OOT_ROMFS The work folder and the dump's folders, over work/dump.txt
HOS_MODS=<folder> The mods folder, in place of mods in the game folder: for the running game (RomFS mods, cheat files) and for a build (the code patches it applies)

Mods: code patches and cheats

The game loads RomFS mods at its start (host/mods.c). The two kinds of mod that change what the game does go other ways, because the game's code is C compiled ahead of time and cannot be patched while it runs.

The mods folder, for the game and for a build alike (host/mods.c find_mods, nx2/code_mods.py find_mods, which must stay the same walk): a mod is a folder under mods that holds a romfs, exefs or cheats folder, at most four levels down, and nothing below a mod is looked at. A folder whose name starts with - or _ is off, one that starts with . is skipped. Mods are ordered by their path under mods, ASCII letters' case ignored, and the last one wins. Triforce Setup's mod manager can switch a mod by renaming its folder and order mods by a prefix, and needs no other file.

Code patches (<mod>/exefs/*.ips, *.pchtxt), nx2/code_mods.py:

  • make_game.py calls build_step once its copy of the game's code (<work>/exefs) is there and checked, after the copy the game folder keeps for updates (.triforce_exefs) is made and before the lift key is taken. The patches go into that copy, a module with a patch written again as a plain NSO, and the lift reads it: lift.py, chunks.py and the rest of the translator know nothing of mods.
  • The lift key hashes the files of that copy, so the patched bytes are in it: a patch added, taken out, switched off or edited translates the game again, a patch that changes no byte does not, and neither does a change to code_mods.py itself (LIFT_KEY_NOT).
  • A patch names its module by build id (the .ips file's name, the .pchtxt file's @nsobid-, trailing zeros left out or not) and may be for any module of the exefs. Offsets count the NSO's 0x100-byte header, as Atmosphere and the emulators read them; .pchtxt knows @flag offset_shift, @enabled, @disabled, @little-endian, @big-endian and @stop. Mods in order, a mod's files by name, the later write wins and the build says which file wrote over which.
  • A file is refused whole, with a line that says why: another build's, cut short, a value that cannot be read, a write into the header, past the image or between the segments. The last leaves out code caves, which the translator has not been tried on.
  • The build writes triforce_code_mods.txt into the game folder when it is done: a line per patch file, tab separated, applied or refused, the file's FNV-1a 64 and size, its path under the mods folder, then the module and the bytes changed, or the reason. The next build (the game's update offer runs --update) reads the mods folder again, so the same patches are built in again, and says which of the record's are gone, changed or refused now. The game reads the record at its start (host/mod_code.h) and logs for each patch file whether it is built in or waits for a build, and which built-in patches are gone from the folder.

Cheats (<mod>/cheats/<first 16 digits of main's build id>.txt), host/mod_cheats.h and host/mod_cheats.c:

  • Read at the start, run by an interpreter once a game frame, at the game's present and on its thread (hos_mod_cheats_frame). Nothing is compiled in, so a cheat file needs no build. NX2navi compiled in the cheats that write instructions; Triforce's translator has no switchable patches, so such a cheat (an opcode 0 into a module's .text) is refused and belongs in a code patch.
  • The opcodes it runs are listed at the top of host/mod_cheats.h: 0 to A and C0 to C3 of Atmosphere's cheat machine. Any other is refused when the file is read, the whole cheat, by name. Registers are shared by one file's cheats within a frame and cleared between frames; a master code runs first.
  • Memory is the program image and the heap, each access checked (mod_cheat_readable); the modules' code (hos_code in the generated hos_image.c) is never written. Region 0 is the module main's base (hos_main_base), 1 and 2 HOS_HEAP_BASE, 3 0x08000000, as host/hos_svc.c tells the game.
  • Each cheat that is not a heading has a row on the System tab, 96 at most (gpu/vk/mod_cheat_rows.h; option ids 130 to 133 in gpu/vk/vk_api.h). The rows are not in the options file: triforce_cheats.txt in the game folder has a line for each cheat that is on, its number (FNV-1a 32 of <mod>/<name>) and that text, and a cheat listed there is on at the start.

The options file

hookshot_options.ini, in the game folder, holds the Insert menu's rows as <key>=<number>: the row's name in lower case with _ for spaces (frame_generation=2, invert_camera_x=1), except Output resolution, which is output_res. gpu/vk/vk_menu.cpp writes the whole file at every change (save; (Triforce) merged by key with a change made outside the game meanwhile, and written whole: RX_VK_OPTIONS_MERGE above), with options_version=4, microphone_device=<name> when a microphone is chosen by name, and the controls (pad_<button> and key_<button>: the README's Controls). A value outside a row's range is clamped when it is read. Where the number is not the obvious one:

Key Values
quality_preset 0 Custom, 1 Minimum (6GB), 2 Low (8GB), 3 Balanced (12GB), 4 High (16GB), 5 Ultra (20GB+); each sets Texture detail: Low, Reduced, Full, Full, Full
gpu_device 0 Auto, n the n-th card with Vulkan 1.3 as the row lists them
frame_generation 0 Off, 1 Auto, 2 to 8 the multiplier, 9 AMD FSR 4 (the made frame by AMD's frame generation library, gpu/vk/vk_fsr4.cpp fsr4fg; where that cannot run the value stays in the file and the row shows and runs 2x: gpu/vk/framegen_rows.h)
frame_rate_cap 0 60, 1 90, 2 120, 3 144, 4 165, 5 240, 6 the monitor's refresh rate; -1 45, -2 40, -3 30
steady_frame_rate 0 Off, 1 any rate (the cap, then 200, 180, 160, 144, 120, 110, 100, 90, 80, 72, 66, 60, 55, 50, 45, 40, 36, 30 under it), 2 whole divisions of the display's refresh rate under the cap, from 30 up (host/pace_steady.h)
resolution 0 Auto, 1 100%, 2 75%, 3 67%, 4 50%
output_res 0 2048x1152, 1 2560x1440, 2 3840x2160, 3 1920x1080, 4 5120x1440, 5 5120x2880
ultrawide 0 16:9, 1 16:10, 2 21:9, 3 32:9 (before options_version 6, 1 was the monitor's shape: read as the nearest of the four, gpu/vk/ultrawide_rows.h)
hdr 0 Off, 1 Expanded, 2 Native (the game's own)
hdr_paper_white, hdr_peak_brightness nits: 80 to 400, and 400 to 10,000
renodx_tonemapper 0 Vanilla, 1 PsychoV35, 2 RenoDRT
renodx_gamma_correction 0 Off, 1 2.2, 2 BT.1886 (2.4)
renodx_match_tone_slope 0 Off, 1 On (as out of the box): PsychoV35's rows, with renodx_tone_slope and renodx_hue_clip
renodx_tone_slope, renodx_highlight_saturation 0 to 100, 50 unchanged: the first PsychoV35's, the second RenoDRT's
renodx_blowout, renodx_flare 0 to 100, 0 none: RenoDRT's
renodx_hue_clip, renodx_hue_correction, renodx_color_grading percent, 0 to 100: 50, 100 and 100 out of the box; the first PsychoV35's, the others RenoDRT's
dlss the Upscaler: 0 the game's own, 1 NVIDIA DLSS, 2 NVIDIA DLAA, 3 AMD FSR 3.1, 4 AMD FSR 4, 5 AMD FSR 4 Native AA, 6 AMD FSR 3.1 Native AA (the row shows it after FSR 3.1)
upscaling 0 Off, 1 Catmull-Rom, 2 Lanczos
anti-aliasing 0 the game's own SMAA, 1 Off, 2 FXAA, 3 SMAA Ultra
texture_detail 0 Automatic, 1 Full, 2 Reduced, 3 Low
fps_counter 0 Off, 1 On, 2 Full (NX2navi's full performance overlay in the counter's place: vk_menu.cpp draw_perf, the frame times and the figures per frame gpu/vk/perf_stats.h, the machine's numbers sampled twice a second on a thread of their own gpu/vk/perf_machine.cpp)
opaque_textures_as_bc1 0 Off, 1 On
sharpness, rumble_strength, motion_sensitivity_x, motion_sensitivity_y percent
mouse_sensitivity hundredths: 100 is 1.00
stick_dead_zone 0 Default (24%), 1 5%, 2 10%, 3 15%, 4 20%, 5 30%
left_stick_dead_zone, right_stick_dead_zone -1 As Stick dead zone, 0 to 50 percent
vibration_curve hundredths, 20 to 150: the power on the motors' rumble, 100 is 1.00 (none)
walk_key 0 Off, 1 Caps Lock, 2 Shift, 3 Ctrl, 4 Tab
walk_scale hundredths, 20 to 90: 51 is 0.51 of the stick's travel
robust_buffers 0 Auto (on), 1 Off, 2 On
game_speed 0 Per frame, 1 Real time
text_speed 0 Normal, 1 2x, 2 4x, 3 Instant
menu_sounds percent, 0 to 100: 80 unless set, 0 silent. The settings' own sounds, the game's interface sounds from its RomFS (host/menu_sound.c, gpu/vk/menu_sound_events.h; option ids 135 and 136), under master_volume
microphone 0 Off, 1 Default, 2 and up a microphone (the name in microphone_device decides which)
mouse_camera 0 As the stick, 1 Native
layout_preset 0 Nintendo, 1 Xbox / PC, 2 Swap Face, 3 Custom
button_prompts 0 Auto (the controller there at the start; none: the keyboard and mouse), 1 Switch, 2 Xbox, 3 PlayStation 4, 4 PlayStation 5, 5 Steam Deck, 6 Keyboard & mouse (host/prompts.c, nx2/prompt_keys.py)
replay_helper_threads 0 Off, 1 to 7 the parallel replay tried on 2 to 8 threads, 8 Automatic (the default; the Debug tab). A file that says 0 stays Off: delete the line, or choose Automatic on the Debug tab, for the default

The Game language row is not in this file: its choice is the code line of language.txt in the game folder, which the menu rewrites in place (gpu/vk/game_language.h: the code alone on that line, the rest of the file as it was, and only a code the file itself names) and the host reads at the start (host/nn_applet.c). Nor are the Mod cheats rows: which of a mod's cheats are on is the host's to keep, in triforce_cheats.txt (Mods: code patches and cheats above).

The other rows are 0 Off and 1 On. Some are read at the start, before the menu exists, by the code that needs them: handheld_profile and output_res (host/nn_applet.c), ultrawide (host/hos_main.c), frame_rate_cap (host/nn_vi.c; the monitor's rate is the display's the window opens on, rounded, 30 to 240, and 60 when it cannot be read), robust_buffers (gpu/vk/vk_main.cpp), texture_detail (gpu/vk/vk_texture.cpp, at the first texture) and the controls (host/nn_hid.c).

The renodx_ rows other than renodx_hdr are read at every frame (gpu/vk/vk_renodx.cpp fill_settings), and the menu shows the rows of one tonemapper while it is the one chosen. RenoDX's mod for this game has Vanilla and PsychoV35; RenoDRT and the gamma correction come from gpu/vk/shaders/renodx_glue, three files of Triforce's own that scripts/renodx_shaders.py compiles together with RenoDX's scene shaders and its output encoder as the build fetched them (nothing of RenoDX is in the repository or changed). RenoDRT calls RenoDX's library; the gamma correction is on the finished picture, HUD included, and the tone mappers are given a peak with it taken out, so that the brightest light still lands on the HDR peak brightness. A change to a glue file changes the stamp of renodx_spv.h, which the next build then compiles again.

RivaTuner Statistics Server has no row: where it is installed and running it is the game's frame limiter, and an options file that still has the test builds' rivatuner_limit= is read by nothing (the next save drops the line). A thread of gpu/vk/rtss_limit.cpp looks twice a second: it puts the limit (gpu/vk/pace_rule.h pace_rtss_want: the cap in effect, Monitor's rate and the caps under 60 included, times the frames shown for each of the game's with frame generation 2x to 8x or AMD FSR 4) into RTSS's profile for the executable through RTSS's own hooks library (RTSSHooks64.dll from RTSS's folder: FramerateLimit and FramerateLimitDenominator, nothing else, no other profile), reads it back, and once RTSS is seen holding the game to it (gpu/vk/rtss_decide.h rtss_decide) the host's wait steps aside (gpu/vk/vk_pace.cpp), the in-house frame generation's display thread leaves its own spacing of made frames to RTSS, and Reflex is given no frame limit. A limit lower than the profile's waits 5 s before it is written, a higher one 1 s, so a multiplier that changes in play does not rewrite the profile each time. What the profile held is kept in triforce_rtss_profile.txt in the game folder before the first change (one line per executable, the others' lines kept, a file that does not read left alone) and goes back at the exit; the next start puts it back after a kill or a crash, unless the player changed the profile since. The game's own wait holds the frames instead with frame generation on Auto (its presents follow the screen's refresh, not the game, so no limit on them holds the game) and with DLSS frame generation (Streamline presents on a pace of its own: HOS_RTSS_DLSSG=1 tries RTSS there), during movies (the profile keeps the play limit), while no picture went out for 200 ms (a minimised window), while RTSS is not installed, not running or has not hooked the game, and when the profile does not keep the limit (no administrator rights) or RTSS refuses it, unless a limit the player set in RTSS, at or under the game's, holds the game (then RTSS holds movies too). A hold needs a present since the frame start two frames back, so a window that stops showing gives the frames back within two frames. RTSS's count past 1.05 times the limit three periods running, 30 s hooked with the limit and no hold, or the game's frames coming sooner than the cap give the frames back; RTSS is tried again a minute later (three times), and at once when RTSS starts again or another limit is wanted. The game never starts RTSS, installs nothing and asks for no rights. vk: pace: lines in the log say which limiter is in force and why; the Full overlay's Frame limit line names RivaTuner or NVIDIA Reflex after the rate when either holds the frames.

Layout

Path What
docs/design.md why mkw-recomp's pipeline, the architecture, MKW's lessons as rules, stages, testing
nx2/ the lift pipeline and its tests (mkw-recomp's, made game-neutral; kit.py has the paths), and make_game.py, which the builders run
host/ the standalone Horizon runtime (TOTKPort's hos/ as adapted by mkw-recomp), with the native NVN2 layer nvn_native.c; host/posix has the Win32 calls on Linux
gpu/vk/ the Vulkan back end (hookshot_vk.dll, hookshot_vk.so), with Eden's shader recompiler and sirit
gpu/render/, gpu/third_party/ the WebGPU renderer the Windows exe falls back to when it was built with wgpu-native, its op stream (rx_nvn.h), suyu's decoders
builder/ Hookshot Builder: the Windows app (.NET 8 WPF), its setup and MSI, and the Linux builder and launcher scripts
setup/ Triforce Setup, the program players run (.NET Framework 4.8, WPF): Setup.cs installs, updates and runs make_game.py, Shell*.cs and Main.xaml are its window, Guard.cs is what keeps a run from damaging an install, Mods.cs the mods folder as the Mods page lists and changes it, Steam.cs and SteamArt.cs the Add to Steam shortcut and its pictures, Sound.cs the game's own decide and cancel sounds as Setup plays them (decoded in memory from the player's game folder: no sound is shipped; TRIFORCE_SOUND_LOG=<file> writes down, in a test run, the sounds that would have played) (CONTRIBUTING.md)
scripts/ test runs, the profile and log readers, the save copier (oot_saves.py), release tooling, scripts/linux (dependencies, AppImage)
tests/ the game-free checks, all run by tests/run_all.py
third_party/ a64-kit (Hookshot's few changes marked (hookshot)), libopus, zbic (Atmosphere's zstd with ZBIC, for unpacking only), SDL2's licence, Dear ImGui and its Vulkan backend, zstd's decoder, the Libertinus fonts, SMAA's reference shader and lookup textures (the Anti-aliasing row's SMAA Ultra)

License: GPL-3.0-or-later, as mkw-recomp: a64-kit's translator is suyu's (GPL-2.0-or-later) and Eden's code is GPL-3.0.