NotRexed/Hookshot est conçu comme un pipeline de recompilation statique à cinq couches qui transforme le remake Nintendo Switch 2 de The Legend of Zelda: Ocarina of Time (Title ID 0400486024DEC000 v131072) en un exécutable x86_64 natif. En combinant le lifter nx2/ AArch64 vers C, un runtime natif Horizon OS SDK 22.2.8 (host/), un enregistreur de flux de commandes NVN2 API 231.40 et un moteur de relecture de mesh shaders Vulkan 1.3 avec conversion descendante des shaders Eden SM86 vers SPIR-V (gpu/vk/), Hookshot exécute le code du jeu nativement sans machine virtuelle.
Utilisez le rail de modules de gauche pour filtrer les 10 sous-systèmes vérifiés du dépôt par couche architecturale (AOT Lifter, Ingestion du dump, Build et System Link, Runtime OS et services, Front-end graphique API, Renderer Vulkan 1.3, Shader Recompiler, Mise à l'échelle temporelle, Builder UI et Outillage), ou examinez le tableau complet PartListTable ci-dessous.
| Sous-système et couche | Chemins du dépôt | Langage et filiation amont | Artefact produit généré | Rôle technique et dépendances |
|---|---|---|---|---|
nx2/ Recompilation statique et 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 répartis sur 57 blocs C, 294 450 fonctions) | Charge les modules Switch 2 NSO à l'adresse 0x80000000 avec les réadressages DT_RELR, résout les tables de saut (1 475 tables) et traduit 17 668 191 instructions ARMv8.2+ (y compris UDOT) en C. |
Extracteur de dump nx2/nup.py et nx2/unpack.pyIngestion du dump | nx2/nup.py, nx2/unpack.py, nx2/dump.py, third_party/zbic | Python 3 + C (décodeur Atmosphere ZBIC)Hookshot / mkw-recomp | work/dump/exefs + work/dump/romfs (26.2 GB extraits) | Valide les sept signatures d'intégrité du dump Switch 2 pour 0400486024DEC000 v131072, extrait les archives .nup et décompresse les binaires NSO main encodés en ZBIC du firmware 22.0.0+. |
Compilateur nx2/build.py et nx2/make_game.py Native DriverBuild et 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 + pipeline PGO split_hot Hookshot | hookshot.exe (426 MB) / hookshot + image.bin | Répartit le code dynamique généré sur 8 unités de traduction parallèles, applique les profils de branchement LLVM format brut 11 PGO, compile les blocs froids en -O1 et les blocs chauds en -O2, puis édite les liens de l'exécutable natif. |
Native host/ Horizon OS et HLE d'exécution SDK 22.2.8Exécution OS et services | host/hos_main.c, host/hos_setjmp.c, host/nn_hid.c, host/nn_applet.c, host/posix/ | C11 / Win32 et POSIX Threads / Assemblyhos/ TOTKPort adapté via mkw-recomp | Lié directement dans hookshot.exe / hookshot | Remplace les limites 485 nn:: SDK au moment de l'exécution, réserve un espace d'adressage virtuel invité de 512 GB, mappe les fibres nn::os sur des fibres natives et gère le système de fichiers, l'audio (libopus) ainsi que les manettes HID. |
Enregistreur de commandes host/nvn_native.c NVN2 (API 231.40)Front-end API graphique | host/nvn_native.c, host/nvn2.c, gpu/render/rx_nvn.h | C11Couche mkw-recomp NVN2 | Flux d'opérations NVN2 en mémoire pour gpu/vk/ | Implémente les routines API 231.40 de Switch 2 NVN2 directement sur la mémoire invitée, capture les pools de mémoire à la soumission et transmet les tampons de commandes au backend Vulkan. |
Backend gpu/vk/ Vulkan 1.3 et Engine Queue ReplayVulkan 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 + correctifs Hookshot OoT | hookshot_vk.dll (Windows) / hookshot_vk.so (Linux) | Rejoue les flux de commandes NVN2 sous Vulkan 1.3 avec VK_EXT_mesh_shader, applique la synchronisation inter-files WaitEvent, exécute les matrices coopératives HMMA f16 pour l'upscaling vidéo/TAAU et gère les miroirs de pools VRAM avec diff en réécriture. |
Abaissment gpu/vk/eden/ Ampere SM86 vers Maxwell et Recompiler SPIR-VShader Recompiler | gpu/vk/eden/, lower_to_maxwell.h, structured_control_flow.cpp | C++20 (recompilateur de shaders Eden + sirit)Eden (build Eglantine 181) + correctifs de flux de contrôle Lichii | hookshot_programs.bin, hookshot_programs.idx, hookshot_pipelines.bin | Convertit 10 154 shaders SASS (SM86) Ampere Nin_Ounce_NVN2 de Switch 2 (dont les programmes vertex/mesh à 249 registres REGMAP_nx2 et les shaders de tâches) vers la RI Maxwell, puis génère le Vulkan SPIR-V. |
Technologies d'upscaling gpu/vk/vk_dlss.cpp NVIDIA DLSS et intégrée AMD FSR 3.1Mise à l'échelle temporelle et génération d'images | gpu/vk/vk_dlss.cpp, gpu/vk/vk_menu.cpp | C++20 (NVIDIA NGX SDK 310.9.16, AMD FidelityFX SDK 1.1.4)Intégration native Hookshot | FSR 3.1 intégré + chargeur dynamique nvngx_dlss.dll | Intercepte le jitter de résolution dynamique, les vecteurs de mouvement et les tampons de profondeur d'OoT pour piloter le FSR 3.1 AMD intégré sur tous les GPU ou l'upscaling optionnel NVIDIA DLSS Super Resolution (préréglages Transformer K/M/L) lorsque nvngx_dlss.dll est présent. |
GUI Hookshot builder/ Builder (WPF Windows et AppImage Linux)Launcher pour les joueurs et UI Builder | builder/HookshotBuilder.sln, scripts/linux/appimage.sh | C# (.NET 8 WPF sous Windows) / Shell et Python sous LinuxGénérateur officiel Hookshot | HookshotBuilder.exe / Hookshot-x86_64.AppImage | Vérifie les dumps .nup ou romfs+exefs fournis par l'utilisateur, orchestre la compilation C locale unique de 10 à 45 minutes sans distribuer de ressources protégées par le droit d'auteur, et offre les commandes Jouer/Update. |
Outil de transfert de sauvegardes, profileurs et suite de non-régression scripts/ et tests/Outillage et vérification | scripts/oot_saves.py, scripts/prof.py, scripts/framelog.py, tests/run_all.py | Python 3 et PowerShellOutils officiels Hookshot | oot-save-backups/, contrôle de non-régression CI sans données de jeu | Assure la migration bidirectionnelle des sauvegardes entre Hookshot et les émulateurs Switch 2 (Lichii, Eglantine, Orchid, NX2navi), l'échantillonnage de la pile à 1 ms et les tests de non-régression de code source sans données propriétaires. |
Les contributeurs qui déboguent des blocs C convertis ou modifient le moteur de rendu Vulkan 1.3 dans gpu/vk/ peuvent exécuter le pipeline de compilation développeur en quatre étapes directement depuis un clone git.
Valide les sept signaux d'intégrité du dump pour le Title ID 0400486024DEC000 v131072 (préfixe e0f3ccfa de SHA-1 pour NSO main de ExeFS), décompresse 26,2 GB d'archives RomFS et extrait les sections NSO encodées en ZBIC du firmware 22.0.0+ via third_party/zbic.
python nx2/unpack.py --input <path-to-0400486024DEC000-v131072> --out work/dumpMappe l'image NSO de Switch 2 à l'adresse de base invitée 0x80000000, applique les relocalisations relatives DT_RELR, résout 1 475 tables de saut et génère environ 1,4 GB de code C répartis sur 57 blocs (scindés en 399 fragments de compilation avec séparation PGO chaud/froid).
python nx2/lift.py --dump work/dump --out work/sa/genCompile les fragments C froids avec -O1 et les 8 unités de traduction de split_hot.py avec -O2 à l'aide des poids de profil de branchement LLVM au format brut 11, puis les lie avec host/hos_main.c via LLD pour générer hookshot.exe (426 MB) et image.bin.
python nx2/make_game.py --jobs 8 --pgoCompile gpu/vk/ (incluant le module d'abaissement de shaders SM86 vers Maxwell d'Eden, l'émetteur SPIR-V sirit, les pools de mémoire VMA et les hooks FSR 3.1 / DLSS) en hookshot_vk.dll / hookshot_vk.so et vérifie toutes les barrières de non-régression des sources.
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release && cmake --build build && python tests/run_all.pyLe lifter de NotRexed/Hookshot est dérivé de mkw-recomp (commit 7336f0a) et du kit a64 d'Rexcomp, enrichi spécifiquement pour le binaire du remake Ocarina of Time de Switch 2 compilé avec Nintendo SDK 22.2.8 et le firmware 22.0.0+. Dans la mesure où le firmware 22.0.0+ compresse les segments NSO avec ZBIC, nx2/unpack.py intègre le décodeur ZBIC de Atmosphere avant de charger l'image à l'adresse invitée 0x80000000. Le lifter traduit 17 668 191 instructions ARMv8.2+ — y compris les instructions SIMD de produit scalaire telles que UDOT — en fonctions C, tandis que nx2/split_hot.py s'appuie sur les profils PGO LLVM format 11 pour isoler les chemins d'exécution les plus sollicités dans 8 unités de traduction compilées en -O2, permettant ainsi aux compilations multicoeurs complètes de s'achever en 10 à 45 minutes.
À l'exécution, host/hos_main.c alloue une plage d'adresses virtuelles contiguë de 512 GB afin de déréférencer les pointeurs 64 bits invités avec un surcoût minimal. Au lieu d'émuler le noyau d'Horizon OS, Hookshot intercepte directement les frontières de symboles 485 nn:: SDK — en mappant les fibres nn::os sur des fibres Win32 natives ou des coroutines setjmp/ucontext sous POSIX, en redirigeant les lectures nn::fs vers le répertoire work/dump/romfs extrait, en décodant les flux audio d'ambiance et des cinématiques via libopus, et en convertissant les événements de manette/gyroscope SDL3 en états de contrôleur nn::hid.
Les jeux Switch 2 effectuent leur rendu via NVN2 (version API 231.40) ciblant le matériel NVIDIA Ampere SM86, avec des en-têtes de shaders propriétaires Nin_Ounce_NVN2 et des fichiers de registres REGMAP_nx2 à 249 GPR. Le composant host/nvn_native.c d'Hookshot assure l'enregistrement des commandes NVN2 sur place au sein de la mémoire invitée et transmet les soumissions vers hookshot_vk.dll / hookshot_vk.so. Au sein de gpu/vk/eden/, Hookshot adapte le recompilateur de shaders d'Eden (build Eglantine 181 avec les correctifs de flux de contrôle structuré Lichii) pour convertir 10 154 binaires SASS Ampere SM86 — y compris les étapes de task et mesh shaders — en Maxwell IR et générer des modules standard Vulkan 1.3 SPIR-V (8 243 programmes de pipeline actifs mis en cache dans hookshot_programs.bin au moment de l'exécution).
De plus, le moteur du remake s'appuie sur les instructions tensorielles HMMA.1688.F16 de Ampere au sein des compute shaders pour l'antialiasing temporel avec upscaling (TAAU) et le décodage des cinématiques précalculées. Le composant gpu/vk/vk_coopmat.cpp d'Hookshot traduit ces opérations en instructions VK_KHR_cooperative_matrix dès lors que le GPU hôte les prend en charge, et intercepte le jitter ainsi que les vecteurs de mouvement du moteur dans gpu/vk/vk_dlss.cpp pour alimenter le AMD FSR 3.1 intégré (FidelityFX SDK 1.1.4) ou, en option, NVIDIA DLSS Super Resolution (NGX SDK 310.9.16).
Hookshot s'appuie sur mkw-recomp (commit 7336f0a) et sur l'a64-kit de Rexcomp pour la conversion statique de AArch64 vers C, sur la couche hos/ de TOTKPort pour les shims d'exécution d'Horizon OS HLE, ainsi que sur le recompilateur de shaders Eden (build Eglantine 181) + Lichii pour convertir les shaders Switch 2 Ampere SM86 vers Vulkan 1.3 SPIR-V.
Oui. L'exécution de python tests/run_all.py lance la suite de régression CI sans jeu, qui valide la sémantique des instructions du lifter, l'empaquetage des en-têtes hôtes (#990) et l'initialisation du backend Vulkan sans nécessiter de fichiers sous copyright RomFS ou ExeFS.
Compiler l'ensemble des 294 450 fonctions converties (~1,4 GB de code C généré réparti sur 57 blocs) avec -O2 prendrait plusieurs heures et saturerait la RAM système. nx2/split_hot.py d'Hookshot isole les fonctions les plus fréquemment exécutées dans 8 unités de traduction chaudes compilées en -O2 avec les profils de pondération LLVM PGO, tout en compilant le reste des blocs froids en -O1.
Source principale pour les métriques du lifter nx2/, les frontières 485 nn:: HLE, NVN2 API 231.40 et la conversion de shaders Eden SM86.
Source principale pour le pipeline de build PGO split_hot.py, la compilation de hookshot_vk et tests/run_all.py.
Source principale pour la structure des répertoires (nx2/, host/, gpu/vk/, builder/, scripts/, tests/) et les attributions amont.