NotRexed/Hookshot 采用五层静态重编译管线架构，将《塞尔达传说：Ocarina of Time》的 Nintendo Switch 2 重制版（Title ID 0400486024DEC000 v131072）转换为原生 x86_64 可执行文件。通过结合 nx2/ AArch64 转 C 提升器、原生 Horizon OS SDK 22.2.8 运行时（host/）、NVN2 API 231.40 命令流录制器，以及具备 Eden SM86 转 SPIR-V 着色器降级能力的 Vulkan 1.3 网格着色器回放引擎（gpu/vk/），Hookshot 无需虚拟机即可原生执行游戏代码。
使用左侧模块栏按架构层级（AOT Lifter、转储摄取、Build 与 Link System、操作系统与服务运行时、图形 API 前端、Vulkan 1.3 Renderer、Shader Recompiler、时间性超分辨率、Builder UI 以及工具链）筛选全部 10 个已验证的仓库子系统，或在下方查看完整的 PartListTable。
| 子系统与架构层 | 仓库路径 | 语言与上游谱系 | 生成的产物文件 | 工程职责与关联 |
|---|---|---|---|---|
nx2/ 静态重编译 与 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，分布于 57 个 C 分块，294,450 个函数） | 在 0x80000000 处加载 Switch 2 NSO 模块并处理 DT_RELR 重定位，解析跳转表（1,475 个表），并将 17,668,191 条 ARMv8.2+ 指令（包括 UDOT）翻译为 C。 |
nx2/nup.py 与 nx2/unpack.py 转储提取器转储引入 | nx2/nup.py, nx2/unpack.py, nx2/dump.py, third_party/zbic | Python 3 + C（Atmosphere ZBIC 解码器）Hookshot / mkw-recomp | work/dump/exefs + work/dump/romfs（已提取 26.2 GB） | 针对 0400486024DEC000 v131072 校验 Switch 2 转储的七大特征标志，解压 .nup 归档，并解压固件 22.0.0+ 采用 ZBIC 编码的 main NSO 二进制文件。 |
nx2/build.py 与 nx2/make_game.py Native 编译器 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 流水线 | hookshot.exe (426 MB) / hookshot + image.bin | 将提升出的热点代码拆分至 8 个并行翻译单元，应用 LLVM raw format 11 PGO 分支分析特征，以 -O1 编译冷代码块并以 -O2 编译热点块，最终链接生成原生可执行文件。 |
host/ Native Horizon OS 与 SDK 22.2.8 HLE 运行时系统与服务运行时 | host/hos_main.c, host/hos_setjmp.c, host/nn_hid.c, host/nn_applet.c, host/posix/ | C11 / Win32 与 POSIX Threads / Assembly经由 mkw-recomp 适配的 TOTKPort hos/ | 直接链接至 hookshot.exe / hookshot | 在运行时替换 485 nn:: SDK 边界，预留 512 GB 客制虚拟地址空间，将 nn::os 纤程映射到原生纤程，并处理文件系统、音频（libopus）与 HID 控制器。 |
host/nvn_native.c NVN2（API 231.40）命令录制器图形 API 前端 | host/nvn_native.c, host/nvn2.c, gpu/render/rx_nvn.h | C11mkw-recomp NVN2 层 | 供 gpu/vk/ 使用的内存中 NVN2 操作流 | 在客户机内存上就地实现 Switch 2 NVN2 API 231.40 接口过程，在提交时刻捕获内存池状态，并将命令缓冲区提交串流传输至 Vulkan 后端。 |
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 修复 | hookshot_vk.dll (Windows) / hookshot_vk.so (Linux) | 通过 VK_EXT_mesh_shader 在 Vulkan 1.3 上回放 NVN2 命令流，执行跨队列 WaitEvent 同步，运行用于 TAAU/过场动画超采样的 HMMA f16 协作矩阵，并借助回写差异比对管理 VRAM 内存池镜像。 |
gpu/vk/eden/ Ampere SM86 到 Maxwell 降级转换与 SPIR-V RecompilerShader Recompiler | gpu/vk/eden/, lower_to_maxwell.h, structured_control_flow.cpp | C++20（Eden 着色器重编译器 + sirit）Eden（Eglantine 构建 181）+ Lichii 控制流修复 | hookshot_programs.bin, hookshot_programs.idx, hookshot_pipelines.bin | 将 10,154 个 Switch 2 Nin_Ounce_NVN2 Ampere SASS（SM86）着色器（包括 249-GPR REGMAP_nx2 顶点/网格程序与任务着色器）降级至 Maxwell IR，并输出 Vulkan SPIR-V。 |
gpu/vk/vk_dlss.cpp NVIDIA DLSS 与内置 AMD FSR 3.1 超采样技术时间超采样与帧生成 | 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 原生集成 | 内置 FSR 3.1 + 运行时 nvngx_dlss.dll 加载器 | 拦截 OoT 的动态分辨率抖动、运动矢量和深度缓冲区，以在所有 GPU 上驱动内置 AMD FSR 3.1，或在检测到 nvngx_dlss.dll 时启用可选的 NVIDIA DLSS 超分辨率（Transformer 预设 K/M/L）。 |
builder/ Hookshot Builder GUI（Windows WPF 与 Linux AppImage）玩家 Launcher 与 Builder UI | builder/HookshotBuilder.sln, scripts/linux/appimage.sh | C#（Windows 上的 .NET 8 WPF）/ Linux 上的 Shell 与 PythonHookshot 官方第一方构建器 | HookshotBuilder.exe / Hookshot-x86_64.AppImage | 校验用户提供的 .nup 或 romfs+exefs 转储，调度无需分发受版权保护资源的单次 10–45 分钟本地 C 构建，并提供运行/Update 控制面板。 |
scripts/ 与 tests/ 存档迁移工具、性能分析器及回归测试套件工具套件与验证 | scripts/oot_saves.py, scripts/prof.py, scripts/framelog.py, tests/run_all.py | Python 3 与 PowerShellHookshot 官方第一方工具 | oot-save-backups/、免游戏文件 CI 回归检测门禁 | 提供 Hookshot 与各 Switch 2 模拟器（Lichii、Eglantine、Orchid、NX2navi）之间的双向存档迁移、1 ms 堆栈采样性能分析，以及无需游戏资产的源码回归测试。 |
贡献者若要在 gpu/vk/ 中调试提纯后的 C 代码块或修改 Vulkan 1.3 渲染器，可直接在 git 克隆仓库中运行四阶段开发者构建管线。
验证 Title ID 0400486024DEC000 v131072（ExeFS 主 NSO SHA-1 前缀 e0f3ccfa）的七项转储完整性特征，解包 26.2 GB 的 RomFS 归档，并通过 third_party/zbic 解压固件 22.0.0+ 采用 ZBIC 编码的 NSO 区段。
python nx2/unpack.py --input <path-to-0400486024DEC000-v131072> --out work/dump将 Switch 2 NSO 映像映射在客制基址 0x80000000，应用 DT_RELR 相对重定位，解析 1,475 个跳转表，并将 57 个代码块生成为跨 399 个编译分片（包含冷/热 PGO 分离）的约 1.4 GB C 代码。
python nx2/lift.py --dump work/dump --out work/sa/gen以 -O1 编译冷 C 分片，以 -O2 并结合 LLVM 原始格式 11 分支性能剖析权重编译 split_hot.py 生成的 8 个翻译单元，随后使用 LLD 与 host/hos_main.c 链接，生成 hookshot.exe（426 MB）和 image.bin。
python nx2/make_game.py --jobs 8 --pgo将 gpu/vk/（包括 Eden SM86 到 Maxwell 着色器降级器、sirit SPIR-V 发射器、VMA 内存池以及 FSR 3.1 / DLSS 钩子）编译为 hookshot_vk.dll / hookshot_vk.so，并验证所有源码回归测试关卡。
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release && cmake --build build && python tests/run_all.pyNotRexed/Hookshot 提纯器源自 mkw-recomp（commit 7336f0a）与 Rexcomp 的 a64-kit，并专门针对基于任天堂 SDK 22.2.8 和固件 22.0.0+ 编译的 Switch 2 Ocarina of Time 重制版二进制文件进行了扩展。由于固件 22.0.0+ 使用 ZBIC 压缩 NSO 段，nx2/unpack.py 在客制地址 0x80000000 加载映像之前集成了 Atmosphere 的 ZBIC 解码器。提纯器将 17,668,191 条 ARMv8.2+ 指令（包括 UDOT 等 SIMD 点积指令）翻译为 C 函数，同时 nx2/split_hot.py 利用 LLVM 格式 11 的 PGO 配置数据，将执行最频繁的热路径隔离到 8 个 -O2 编译单元中，使完整的多核编译能够在 10 到 45 分钟内完成。
在运行时，host/hos_main.c 会预留一块连续的 512 GB 虚拟地址空间，从而以极低开销直接解引用客制 64 位指针。Hookshot 并未模拟整个 Horizon OS 内核，而是直接拦截 485 nn:: SDK 符号边界：将 nn::os 纤程映射到原生 Win32 纤程或 POSIX setjmp/ucontext 协程，把 nn::fs 读取路由至已解包的 work/dump/romfs 目录，通过 libopus 解码环境音和过场动画音频流，并将 SDL3 手柄/陀螺仪事件翻译为 nn::hid 控制器状态。
Switch 2 游戏通过面向 NVIDIA Ampere SM86 硬件的 NVN2（API 版本 231.40）进行渲染，采用专有的 Nin_Ounce_NVN2 着色器头与 249 个 GPR 的 REGMAP_nx2 寄存器文件。Hookshot 的 host/nvn_native.c 原位在客制内存上实现 NVN2 命令录制，并将提交以流式传入 hookshot_vk.dll / hookshot_vk.so。在 gpu/vk/eden/ 内部，Hookshot 改造了 Eden 着色器重编译器（Eglantine 构建 181，带有 Lichii 结构化控制流修复），将 10,154 个 Ampere SM86 SASS 二进制文件（包括任务与网格着色器阶段）降级为 Maxwell IR，并生成标准 Vulkan 1.3 SPIR-V 模块（在 hookshot_programs.bin 中缓存了 8,243 个活跃运行时管线程序）。
此外，重制版引擎在计算着色器中依赖 Ampere HMMA.1688.F16 张量指令实现时间性抗锯齿超分辨率（TAAU）及预渲染过场动画解码。在宿主 GPU 支持时，Hookshot 的 gpu/vk/vk_coopmat.cpp 会将这些操作转换为 VK_KHR_cooperative_matrix，并在 gpu/vk/vk_dlss.cpp 中拦截引擎的抖动和运动矢量，以驱动内置的 AMD FSR 3.1（FidelityFX SDK 1.1.4）或可选的 NVIDIA DLSS 超分辨率（NGX SDK 310.9.16）。
Hookshot 构建在 mkw-recomp（commit 7336f0a）与 Rexcomp 的 a64-kit 之上以实现 AArch64 到 C 静态提纯，依托 TOTKPort 的 hos/ 层提供 Horizon OS HLE 运行时适配垫片，并采用 Eden（Eglantine 构建 181）+ Lichii 着色器重编译器将 Switch 2 Ampere SM86 着色器降级转换为 Vulkan 1.3 SPIR-V。
可以。运行 python tests/run_all.py 将执行免游戏 CI 回归测试套件，该套件可验证提升器指令语义、宿主机标头打包（#990）以及 Vulkan 后端初始化，无需任何受版权保护的 RomFS 或 ExeFS 文件。
若以 -O2 编译全部 294,450 个提纯函数（跨 57 个代码块，共生成约 1.4 GB C 代码），将耗时数小时并耗尽系统 RAM。Hookshot 的 nx2/split_hot.py 将执行频率最高的函数隔离到 8 个热翻译单元中，配合 LLVM PGO 权重以 -O2 进行编译，其余冷代码块则以 -O1 编译。
nx2/ 提纯器指标、485 nn:: HLE 边界、NVN2 API 231.40 及 Eden SM86 着色器降级的主要来源。
有关 split_hot.py PGO 构建流水线、hookshot_vk 编译与 tests/run_all.py 的主要信息源。
有关目录结构（nx2/、host/、gpu/vk/、builder/、scripts/、tests/）及上游归属的主要信息源。