NotRexed/Hookshot ist als fünfschichtige statische Rekompilierungs-Pipeline aufgebaut, die das Nintendo Switch-2-Remake von The Legend of Zelda: Ocarina of Time (Title-ID 0400486024DEC000 v131072) in ein natives x86_64-Executable transformiert. Durch die Verknüpfung des nx2/-AArch64-zu-C-Lifters, einer nativen Horizon-OS-SDK-22.2.8-Laufzeitumgebung (host/), eines NVN2-API-231.40-Befehlsstrom-Recorders und einer Vulkan-1.3-Mesh-Shader-Replay-Engine mit Eden-SM86-zu-SPIR-V-Shader-Lowering (gpu/vk/) führt Hookshot den Spielcode nativ ohne virtuelle Maschine aus.
Nutze die linke Modulleiste, um die 10 verifizierten Subsysteme des Repositorys nach Architekturschicht zu filtern (AOT Lifter, Dump-Aufnahme, Build & Link System, Betriebssystem- & Dienstlaufzeit, Grafik-API-Front-End, Vulkan 1.3 Renderer, Shader Recompiler, Temporales Upscaling, Builder UI und Tooling), oder prüfe die vollständige PartListTable unten.
| Subsystem & Schicht | Repository-Pfade | Sprache & Upstream-Ursprung | Generiertes Ausgabe-Artefakt | Technische Aufgabe & Beziehungen |
|---|---|---|---|---|
nx2/ Statische Rekompilierung & AArch64 LifterAOT Lifter | nx2/lift.py, nx2/insn.py, nx2/nso2.py, nx2/image.py | Python 3 (Capstone, Unicorn 2.1, LZ4, Zstandard)Ursprung: mkw-recomp (7336f0a) + Rexcomp a64-kit | work/sa/gen/*.c (~1,4 GB über 57 C-Chunks, 294.450 Funktionen) | Lädt Switch-2-NSO-Module bei 0x80000000 mit DT_RELR-Relokationen, löst Sprungtabellen auf (1.475 Tabellen) und übersetzt 17.668.191 ARMv8.2+-Befehle (inklusive UDOT) nach C. |
nx2/nup.py- & nx2/unpack.py-Dump-ExtraktorDump-Erfassung | 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 extrahiert) | Validiert die sieben Switch-2-Dump-Signale für 0400486024DEC000 v131072, extrahiert .nup-Archive und dekomprimiert ZBIC-kodierte main-NSO-Binärdateien ab Firmware 22.0.0+. |
nx2/build.py & nx2/make_game.py Nativer Compiler-TreiberBuild & 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 | Teilt übersetzten Hot-Code auf 8 parallele Übersetzungseinheiten auf, wendet LLVM-Rohformat-11-PGO-Zweigprofile an, kompiliert Cold-Chunks mit -O1 sowie Hot-Chunks mit -O2 und verlinkt die native Binärdatei. |
host/ Native Horizon OS & SDK 22.2.8 HLE-LaufzeitumgebungOS- & Service-Laufzeitumgebung | host/hos_main.c, host/hos_setjmp.c, host/nn_hid.c, host/nn_applet.c, host/posix/ | C11 / Win32 & POSIX Threads / AssemblyTOTKPort hos/ adaptiert über mkw-recomp | Direkt in hookshot.exe / hookshot verlinkt | Ersetzt 485 nn::-SDK-Grenzen zur Laufzeit, reserviert einen virtuellen Gast-Adressraum von 512 GB, bildet nn::os-Fibers auf native Fibers ab und übernimmt Dateisystem, Audio (libopus) sowie HID-Controller. |
host/nvn_native.c-NVN2 (API 231.40) BefehlsrekorderGrafik-API-Frontend | host/nvn_native.c, host/nvn2.c, gpu/render/rx_nvn.h | C11mkw-recomp-NVN2-Schicht | In-Memory-NVN2-Befehlsstrom für gpu/vk/ | Implementiert Switch-2-NVN2-API-231.40-Prozeduren direkt im Gast-Speicher, erfasst Speicherpools beim Submit und leitet Command-Buffer-Übergaben an das Vulkan-Backend weiter. |
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-Korrekturen | hookshot_vk.dll (Windows) / hookshot_vk.so (Linux) | Spielt NVN2-Befehlsströme auf Vulkan 1.3 mit VK_EXT_mesh_shader ab, berücksichtigt Queue-übergreifende WaitEvent-Synchronisierungen, führt HMMA-f16-Cooperative-Matrices für TAAU-/Video-Upscaling aus und verwaltet VRAM-Pool-Spiegel mit Write-Back-Diffing. |
gpu/vk/eden/ Ampere SM86-zu-Maxwell-Lowering & SPIR-V RecompilerShader Recompiler | gpu/vk/eden/, lower_to_maxwell.h, structured_control_flow.cpp | C++20 (Eden-Shader-Rekompilierer + sirit)Eden (Eglantine Build 181) + Lichii-Kontrollfluss-Fixes | hookshot_programs.bin, hookshot_programs.idx, hookshot_pipelines.bin | Transformiert 10.154 Switch-2-Nin_Ounce_NVN2-Ampere-SASS-Shader (SM86, inklusive 249-GPR REGMAP_nx2 Vertex-/Mesh-Programme und Task-Shader) in Maxwell-IR und generiert Vulkan SPIR-V. |
gpu/vk/vk_dlss.cpp NVIDIA DLSS & integrierte AMD-FSR 3.1-UpscalerTemporales 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 Einbindung | Integriertes FSR 3.1 + Laufzeit-nvngx_dlss.dll-Loader | Fängt dynamischen Auflösungs-Jitter, Bewegungsvektoren und Tiefenpuffer von OoT ab, um integriertes AMD FSR 3.1 auf allen GPUs oder optionales NVIDIA DLSS Super Resolution (Transformer-Voreinstellungen K/M/L) bei vorhandenem nvngx_dlss.dll anzusteuern. |
builder/ Hookshot Builder GUI (Windows WPF & Linux AppImage)Spieler-Launcher & Builder-UI | builder/HookshotBuilder.sln, scripts/linux/appimage.sh | C# (.NET 8 WPF auf Windows) / Shell & Python auf LinuxOffizieller Hookshot-Builder | HookshotBuilder.exe / Hookshot-x86_64.AppImage | Überprüft vom Nutzer bereitgestellte .nup- oder romfs+exefs-Dumps, koordiniert den einmaligen 10–45-minütigen lokalen C-Build ohne urheberrechtlich geschützte Assets mitzuliefern und stellt Steuerelemente für Spielen/Update bereit. |
scripts/- & tests/-Spielstandtransfer-Tool, Profiler & RegressionssuiteWerkzeuge & Verifikation | scripts/oot_saves.py, scripts/prof.py, scripts/framelog.py, tests/run_all.py | Python 3 & PowerShellOffizielle Hookshot-Werkzeuge | oot-save-backups/, CI-Prüfgate ohne Spieldateien | Bietet bidirektionale Spielstandmigration zwischen Hookshot und Switch-2-Emulatoren (Lichii, Eglantine, Orchid, NX2navi), 1-ms-Stack-Sampling-Analysen und quellbasierte Regressionstests ohne Spieldateien. |
Mitwirkende, die geliftete C-Chunks debuggen oder den Vulkan-1.3-Renderer in gpu/vk/ modifizieren, können die vierstufige Entwickler-Build-Pipeline direkt aus einem Git-Klon heraus ausführen.
Validiert die sieben Dump-Integritätssignale für Title-ID 0400486024DEC000 v131072 (ExeFS Main-NSO SHA-1-Präfix e0f3ccfa), entpackt 26.2 GB an RomFS-Archiven und dekomprimiert firmware-22.0.0+-ZBIC-kodierte NSO-Sektionen via third_party/zbic.
python nx2/unpack.py --input <path-to-0400486024DEC000-v131072> --out work/dumpMappt das Switch-2-NSO-Image an die Gast-Basisadresse 0x80000000, wendet relative DT_RELR-Relokationen an, löst 1.475 Sprungtabellen auf und emittiert ~1.4 GB an C-Code über 57 Chunks (aufgeteilt in 399 Kompilierungs-Shards mit Hot/Cold-PGO-Trennung).
python nx2/lift.py --dump work/dump --out work/sa/genKompiliert Cold-C-Shards mit -O1 und die 8 split_hot.py-Übersetzungseinheiten mit -O2 samt LLVM-Raw-Format-11-Branch-Profile-Gewichtungen, linkt sie anschließend mit host/hos_main.c via LLD, um hookshot.exe (426 MB) und image.bin zu erzeugen.
python nx2/make_game.py --jobs 8 --pgoKompiliert gpu/vk/ (einschließlich des Eden SM86-zu-Maxwell-Shader-Lowerers, sirit-SPIR-V-Emitters, VMA-Speicherpools und FSR 3.1 / DLSS-Hooks) zu hookshot_vk.dll / hookshot_vk.so und verifiziert alle Quellcode-Regressions-Gates.
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release && cmake --build build && python tests/run_all.pyDer NotRexed/Hookshot-Lifter basiert auf mkw-recomp (Commit 7336f0a) und Rexcomp s a64-kit, eigens erweitert für das Binary des Switch-2-Ocarina of Time-Remakes, das gegen Nintendo SDK 22.2.8 und Firmware 22.0.0+ kompiliert wurde. Da Firmware 22.0.0+ NSO-Segmente mit ZBIC komprimiert, bindet nx2/unpack.py den ZBIC-Decoder von Atmosphere ein, bevor das Image an die Gast-Adresse 0x80000000 geladen wird. Der Lifter übersetzt 17.668.191 ARMv8.2+-Instruktionen – inklusive SIMD-Skalarprodukt-Befehlen wie UDOT – in C-Funktionen, während nx2/split_hot.py LLVM-Format-11-PGO-Profile nutzt, um die heißesten Ausführungspfade in 8 -O2-Übersetzungseinheiten zu isolieren, sodass vollständige Multi-Core-Builds in 10 bis 45 Minuten fertiggestellt sind.
Zur Laufzeit reserviert host/hos_main.c einen zusammenhängenden virtuellen Adressbereich von 512 GB, wodurch 64-Bit-Gastzeiger mit minimalem Overhead dereferenziert werden können. Statt den Horizon-OS-Kernel zu emulieren, fängt Hookshot 485 nn::-SDK-Symbolgrenzen direkt ab: nn::os-Fibers werden auf native Win32-Fibers oder POSIX-setjmp/ucontext-Coroutinen abgebildet, nn::fs-Lesezugriffe ins entpackte Verzeichnis work/dump/romfs geleitet, Umgebungs- und Zwischensequenz-Audiostreams via libopus dekodiert und SDL3-Gamepad-/Gyroskop-Events in nn::hid-Controller-Zustände übersetzt.
Switch-2-Titel rendern über NVN2 (API Version 231.40) für NVIDIA-Ampere-SM86-Hardware mit proprietären Nin_Ounce_NVN2-Shader-Headern und REGMAP_nx2-Registerdateien mit 249 GPRs. host/nvn_native.c von Hookshot implementiert die Aufzeichnung von NVN2-Befehlen direkt im Gastspeicher und streamt Submissions an hookshot_vk.dll / hookshot_vk.so. Innerhalb von gpu/vk/eden/ passt Hookshot den Eden-Shader-Recompiler (Eglantine Build 181 mit Lichii-Fixes für strukturierten Kontrollfluss) an, um 10.154 Ampere-SM86-SASS-Binaries – einschließlich Task- und Mesh-Shader-Stufen – in Maxwell-IR zu transformieren und Standard-Vulkan-1.3-SPIR-V-Module zu emittieren (8.243 aktive Laufzeit-Pipeline-Programme sind in hookshot_programs.bin zwischengespeichert).
Zusätzlich setzt die Remake-Engine auf Ampere-HMMA.1688.F16-Tensor-Instruktionen innerhalb von Compute-Shadern für temporales Anti-Aliasing-Upscaling (TAAU) und das Dekodieren vorgerenderter Zwischensequenzen. gpu/vk/vk_coopmat.cpp von Hookshot übersetzt diese Operationen in VK_KHR_cooperative_matrix, sofern dies von der Host-GPU unterstützt wird, und fängt Jitter sowie Bewegungsvektoren der Engine in gpu/vk/vk_dlss.cpp ab, um das integrierte AMD FSR 3.1 (FidelityFX SDK 1.1.4) oder optionales NVIDIA DLSS Super Resolution (NGX SDK 310.9.16) anzusteuern.
Hookshot baut auf mkw-recomp (Commit 7336f0a) und dem a64-kit von Rexcomp für das statische AArch64-zu-C-Lifting auf, nutzt die hos/-Schicht von TOTKPort für Horizon-OS-HLE-Laufzeit-Shims und den Shader-Recompiler von Eden (Eglantine Build 181) + Lichii, um Switch-2-Ampere-SM86-Shader in Vulkan-1.3-SPIR-V zu überführen.
Ja. Das Ausführen von python tests/run_all.py startet die spielefreie CI-Regressionssuite. Diese verifiziert die Lifter-Instruktionssemantik, die Paketierung der Host-Header (#990) und die Vulkan-Backend-Initialisierung, ohne urheberrechtlich geschützte RomFS- oder ExeFS-Dateien vorauszusetzen.
Ein Kompilieren aller 294.450 gelifteten Funktionen (~1.4 GB an generiertem C über 57 Chunks) mit -O2 würde Stunden dauern und den System-RAM überlasten. nx2/split_hot.py von Hookshot isoliert die am häufigsten ausgeführten Funktionen in 8 Hot-Übersetzungseinheiten, die mit -O2 unter Nutzung von LLVM-PGO-Gewichtungen kompiliert werden, während die restlichen Cold-Chunks mit -O1 übersetzt werden.
Hauptquelle für nx2/-Lifter-Metriken, 485 nn::-HLE-Grenzen, NVN2 API 231.40 und Eden-SM86-Shader-Lowering.
Primärquelle für die split_hot.py-PGO-Build-Pipeline, die hookshot_vk-Kompilierung und tests/run_all.py.
Primärquelle für Verzeichnisstruktur (nx2/, host/, gpu/vk/, builder/, scripts/, tests/) und Upstream-Quellenangaben.