# 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) | | `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) | | `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 | | `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_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_TRACE=1` | Every Horizon call logged, as `--trace` does | | `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 `: