# 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 --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 --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//shots` | | `python -I scripts/prof.py ` | a profile sampled with `HOS_PROFILE=` + `HOS_SAMPLE=` + `HOS_SAMPLE_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=` 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=` 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=x` | 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=` | The game's language for this run, a code from `language.txt` | | `HOS_OUTPUT_RES=<0..3>`, `HOS_HANDHELD=1`, `HOS_ASPECT=` | 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=` | (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=` | The graphics card listed as `vk: device ` 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=` | 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 `\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=` | 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 timed from the game's first controller read | | `HOS_INPUT_LIVE=` | 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 ` 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=:,...` | 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 `: