NotRexed/Hookshot is engineered as a five-layer static recompilation pipeline that transforms the Nintendo Switch 2 remake of The Legend of Zelda: Ocarina of Time (Title ID 0400486024DEC000 v131072) into a native x86_64 executable. By combining the nx2/ AArch64-to-C lifter, a native Horizon OS SDK 22.2.8 runtime (host/), an NVN2 API 231.40 command stream recorder, and a Vulkan 1.3 mesh-shader replay engine with Eden SM86-to-SPIR-V shader lowering (gpu/vk/), Hookshot executes game code natively without a virtual machine.
Use the left module rail to filter the 10 verified repository subsystems by architectural layer (AOT Lifter, Dump Ingestion, Build & Link System, OS & Service Runtime, Graphics API Front-End, Vulkan 1.3 Renderer, Shader Recompiler, Temporal Upscaling, Builder UI, and Tooling), or inspect the complete PartListTable below.
| Subsystem & Layer | Repository Paths | Language & Upstream Lineage | Generated Output Artifact | Engineering Responsibility & Relations |
|---|---|---|---|---|
nx2/ Static Recompilation & AArch64 LifterAOT Lifter | nx2/lift.py, nx2/insn.py, nx2/nso2.py, nx2/image.py | Python 3 (Capstone, Unicorn 2.1, LZ4, Zstandard)mkw-recomp (7336f0a) + Rexcomp a64-kit | work/sa/gen/*.c (~1.4 GB across 57 C chunks, 294,450 functions) | Loads Switch 2 NSO modules at 0x80000000 with DT_RELR relocations, resolves jump tables (1,475 tables), and translates 17,668,191 ARMv8.2+ instructions (including UDOT) to C. |
nx2/nup.py & nx2/unpack.py Dump ExtractorDump Ingestion | nx2/nup.py, nx2/unpack.py, nx2/dump.py, third_party/zbic | Python 3 + C (Atmosphere ZBIC decoder)Hookshot / mkw-recomp | work/dump/exefs + work/dump/romfs (26.2 GB extracted) | Validates the seven Switch 2 dump signals for 0400486024DEC000 v131072, extracts .nup archives, and decompresses firmware 22.0.0+ ZBIC-encoded main NSO binaries. |
nx2/build.py & nx2/make_game.py Native Compiler DriverBuild & Link System | nx2/build.py, nx2/make_game.py, nx2/split_hot.py, nx2/pgo_pieces.py | Python 3 + Clang / LLD (llvm-mingw ucrt-x86_64)mkw-recomp + Hookshot split_hot PGO pipeline | hookshot.exe (426 MB) / hookshot + image.bin | Splits hot lifted code across 8 parallel translation units, applies LLVM raw format 11 PGO branch profiles, compiles cold chunks at -O1 and hot chunks at -O2, and links the native executable. |
host/ Native Horizon OS & SDK 22.2.8 HLE RuntimeOS & Service Runtime | host/hos_main.c, host/hos_setjmp.c, host/nn_hid.c, host/nn_applet.c, host/posix/ | C11 / Win32 & POSIX Threads / AssemblyTOTKPort hos/ adapted via mkw-recomp | Linked directly into hookshot.exe / hookshot | Replaces 485 nn:: SDK boundaries at runtime, reserves a 512 GB guest virtual address space, maps nn::os fibers onto native fibers, and handles filesystem, audio (libopus), and HID controllers. |
host/nvn_native.c NVN2 (API 231.40) Command RecorderGraphics API Front-End | host/nvn_native.c, host/nvn2.c, gpu/render/rx_nvn.h | C11mkw-recomp NVN2 layer | In-memory NVN2 op stream for gpu/vk/ | Implements Switch 2 NVN2 API 231.40 procedures in place over guest memory, captures memory pools at submit time, and streams command buffer submissions to the Vulkan backend. |
gpu/vk/ Vulkan 1.3 Backend & Queue Replay EngineVulkan 1.3 Renderer | gpu/vk/vk_main.cpp, gpu/vk/vk_replay.cpp, gpu/vk/vk_memory.cpp, gpu/vk/vk_draw.cpp, gpu/vk/vk_coopmat.cpp | C++20 (Vulkan 1.3, VMA, Dear ImGui)mkw-recomp gpu/vk + Hookshot OoT fixes | hookshot_vk.dll (Windows) / hookshot_vk.so (Linux) | Replays NVN2 command streams on Vulkan 1.3 with VK_EXT_mesh_shader, honours cross-queue WaitEvent syncs, runs HMMA f16 cooperative matrices for TAAU/movie upscaling, and manages VRAM pool mirrors with write-back diffing. |
gpu/vk/eden/ Ampere SM86-to-Maxwell Lowering & SPIR-V RecompilerShader Recompiler | gpu/vk/eden/, lower_to_maxwell.h, structured_control_flow.cpp | C++20 (Eden shader recompiler + sirit)Eden (Eglantine build 181) + Lichii control flow fixes | hookshot_programs.bin, hookshot_programs.idx, hookshot_pipelines.bin | Lowers 10,154 Switch 2 Nin_Ounce_NVN2 Ampere SASS (SM86) shaders (including 249-GPR REGMAP_nx2 vertex/mesh programs and task shaders) to Maxwell IR and emits Vulkan SPIR-V. |
gpu/vk/vk_dlss.cpp NVIDIA DLSS & Built-In AMD FSR 3.1 UpscalersTemporal Upscaling & Frame Generation | gpu/vk/vk_dlss.cpp, gpu/vk/vk_menu.cpp | C++20 (NVIDIA NGX SDK 310.9.16, AMD FidelityFX SDK 1.1.4)Hookshot native integration | Built-in FSR 3.1 + runtime nvngx_dlss.dll loader | Intercepts OoT's dynamic resolution jitter, motion vectors, and depth buffers to drive built-in AMD FSR 3.1 on all GPUs or optional NVIDIA DLSS Super Resolution (Transformer presets K/M/L) when nvngx_dlss.dll is present. |
builder/ Hookshot Builder GUI (Windows WPF & Linux AppImage)Player Launcher & Builder UI | builder/HookshotBuilder.sln, scripts/linux/appimage.sh | C# (.NET 8 WPF on Windows) / Shell & Python on LinuxHookshot first-party builder | HookshotBuilder.exe / Hookshot-x86_64.AppImage | Verifies user-supplied .nup or romfs+exefs dumps, orchestrates the one-time 10-45 minute local C build without shipping copyrighted assets, and provides Play/Update controls. |
scripts/ & tests/ Save Transfer Utility, Profilers & Regression SuiteTooling & Verification | scripts/oot_saves.py, scripts/prof.py, scripts/framelog.py, tests/run_all.py | Python 3 & PowerShellHookshot first-party tooling | oot-save-backups/, CI game-free regression gate | Provides bidirectional save migration between Hookshot and Switch 2 emulators (Lichii, Eglantine, Orchid, NX2navi), 1 ms stack sampling analysis, and game-free source regression tests. |
Contributors debugging lifted C chunks or modifying the Vulkan 1.3 renderer in gpu/vk/ can run the four-stage developer build pipeline directly from a git clone.
Validates the seven dump integrity signals for Title ID 0400486024DEC000 v131072 (ExeFS main NSO SHA-1 prefix e0f3ccfa), unpacks 26.2 GB of RomFS archives, and decompresses firmware 22.0.0+ ZBIC-encoded NSO sections via third_party/zbic.
python nx2/unpack.py --input <path-to-0400486024DEC000-v131072> --out work/dumpMaps the Switch 2 NSO image at guest base 0x80000000, applies DT_RELR relative relocations, resolves 1,475 jump tables, and emits ~1.4 GB of C code across 57 chunks (split into 399 compilation shards with hot/cold PGO separation).
python nx2/lift.py --dump work/dump --out work/sa/genCompiles cold C shards at -O1 and the 8 split_hot.py translation units at -O2 with LLVM raw format 11 branch profile weights, then links them with host/hos_main.c using LLD to produce hookshot.exe (426 MB) and image.bin.
python nx2/make_game.py --jobs 8 --pgoCompiles gpu/vk/ (including the Eden SM86-to-Maxwell shader lowerer, sirit SPIR-V emitter, VMA memory pools, and FSR 3.1 / DLSS hooks) into hookshot_vk.dll / hookshot_vk.so and verifies all source regression gates.
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release && cmake --build build && python tests/run_all.pyThe NotRexed/Hookshot lifter derives from mkw-recomp (commit 7336f0a) and Rexcomp's a64-kit, extended specifically for the Switch 2 Ocarina of Time remake binary compiled against Nintendo SDK 22.2.8 and firmware 22.0.0+. Because firmware 22.0.0+ compresses NSO segments with ZBIC, nx2/unpack.py integrates Atmosphere's ZBIC decoder before loading the image at guest address 0x80000000. The lifter translates 17,668,191 ARMv8.2+ instructions—including SIMD dot-product instructions like UDOT—into C functions, while nx2/split_hot.py uses LLVM format 11 PGO profiles to isolate the hottest execution paths into 8 -O2 translation units so full multi-core builds finish in 10 to 45 minutes.
At runtime, host/hos_main.c reserves a contiguous 512 GB virtual address region so guest 64-bit pointers can be dereferenced with minimal overhead. Instead of emulating the Horizon OS kernel, Hookshot intercepts 485 nn:: SDK symbol boundaries directly—mapping nn::os fibers onto native Win32 fibers or POSIX setjmp/ucontext coroutines, routing nn::fs reads to the unpacked work/dump/romfs directory, decoding environmental and cutscene audio streams via libopus, and translating SDL3 gamepad/gyroscope events into nn::hid controller states.
Switch 2 titles render through NVN2 (API version 231.40) targeting NVIDIA Ampere SM86 hardware with proprietary Nin_Ounce_NVN2 shader headers and 249-GPR REGMAP_nx2 register files. Hookshot's host/nvn_native.c implements NVN2 command recording in place over guest memory and streams submissions to hookshot_vk.dll / hookshot_vk.so. Inside gpu/vk/eden/, Hookshot adapts the Eden shader recompiler (Eglantine build 181 with Lichii structured control-flow fixes) to lower 10,154 Ampere SM86 SASS binaries—including task and mesh shader stages—into Maxwell IR and emit standard Vulkan 1.3 SPIR-V modules (8,243 active runtime pipeline programs cached in hookshot_programs.bin).
Furthermore, the remake engine relies on Ampere HMMA.1688.F16 tensor instructions inside compute shaders for temporal anti-aliasing upscaling (TAAU) and pre-rendered cutscene decoding. Hookshot's gpu/vk/vk_coopmat.cpp translates those operations to VK_KHR_cooperative_matrix when supported by the host GPU, and intercepts the engine's jitter and motion vectors in gpu/vk/vk_dlss.cpp to drive built-in AMD FSR 3.1 (FidelityFX SDK 1.1.4) or optional NVIDIA DLSS Super Resolution (NGX SDK 310.9.16).
Hookshot builds upon mkw-recomp (commit 7336f0a) and Rexcomp's a64-kit for AArch64-to-C static lifting, TOTKPort's hos/ layer for Horizon OS HLE runtime shims, and the Eden (Eglantine build 181) + Lichii shader recompiler for lowering Switch 2 Ampere SM86 shaders to Vulkan 1.3 SPIR-V.
Yes. Running python tests/run_all.py executes the game-free CI regression suite, which verifies lifter instruction semantics, host header packaging (#990), and Vulkan backend initialization without requiring copyrighted RomFS or ExeFS files.
Compiling all 294,450 lifted functions (~1.4 GB of generated C across 57 chunks) at -O2 would take hours and exhaust system RAM. Hookshot's nx2/split_hot.py isolates the most frequently executed functions into 8 hot translation units compiled at -O2 with LLVM PGO weights while compiling the remaining cold chunks at -O1.
Primary source for nx2/ lifter metrics, 485 nn:: HLE boundaries, NVN2 API 231.40, and Eden SM86 shader lowering.
Primary source for split_hot.py PGO build pipeline, hookshot_vk compilation, and tests/run_all.py.
Primary source for directory layout (nx2/, host/, gpu/vk/, builder/, scripts/, tests/) and upstream attributions.