Files
Triforce-Source/docs/development.md
ruckus7382sfgsgdf fb26495475 Triforce v0.5.2
The new launcher (Windows and Linux: the game's own look, music and settings, saves and mods pages, smaller updates in parts), benchmark mode (Find my best settings: the game tours four places by itself and writes its results), Quit and Restart in the pause menu under Mods, Squadala! in the Mods menu, battle music above 60 fps, menu text, the controller in the menus with the game in the background, the whole GameBanana list, RX 580 and RX 5000/6000 shader fixes, the pipeline cache kept through an update, async present black flashes, and faster builds.
2026-11-19 10:52:50 -06:00

457 lines
127 KiB
Markdown

# 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](../readme.md#project-status) says how far. The design, its stages and
the lessons carried over from MKW: [design.md](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](../CONTRIBUTING.md#development-setup) 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](../readme.md#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 (less what reading the pipeline cache added, except on AMD's driver: `own_for_keep`) 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_CARRY_MB=<MB>` | (Triforce, 11-18) The carry of the pipeline cache's file over an update that changed the translation (`gpu/vk/pcache_bound.h` `carried`): a file for other shaders is read all the same when it is no larger than this (1536 MB unset), leaves room under the bound for as much again and the PC has 31 GB of RAM or more (Windows), so the driver finds what it compiled for the shaders that did not change (AMD's driver keeps no cache of its own for these). `0`: never carried, the rule of 11-14 alone |
| `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](../readme.md#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](../CONTRIBUTING.md#triforce-setup)) |
| `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.