Dépannage de Hookshot et Variables d’Environnement Vulkan
Diagnostiquez et résolvez chaque plantage d'exécution de Hookshot v2.0.11, blocage de pilote GPU, artefact de texture et erreur d'extraction du générateur répertoriés. Recherchez ou filtrez les 10 fiches d'anomalies vérifiées ci-dessous par tag de ticket (#1161, #817, #57, #1176) ou symptôme, examinez les trois volets de diagnostic (Symptôme, Variable d'environnement, Résolution) et appliquez les surcharges d'environnement RX_* ciblées.
FIG. 6.0 — Tri des anomalies Hookshot et arbre de décision des variables d'environnement RX_* (v2.0.11)
ATLAS DES ANOMALIES // 10 FICHES DE DIAGNOSTIC VÉRIFIÉES
Index interactif des anomalies et banc de diagnostic à trois volets
Filtrez par tag d'anomalie majeur (#1161, #817, #57, #1176, diagnostics RX_*) ou recherchez par mot-clé de symptôme. Chaque fiche d'anomalie présente trois volets encadrés — Symptôme observé, Variable d'environnement / Paramètre de lancement, et Résolution v2.0.11 vérifiée — ainsi que les renvois croisés entre anomalies.
Issue n° 1161Saturation de la VRAM ou de la Timeout VK_ERROR_DEVICE_LOST GPU (n° 1161)
GPU dotés de 4 GB à 6 GB de VRAM ou pilotes Vulkan overclockés
Survient lors de transitions chargées dans la Plaine d'Hyrule ou les Temples, quand le pool de textures ASTC et les cascades d'ombres dépassent la VRAM physique ou provoquent un délai TDR du pilote.
VOLET 01 // SYMPTÔME OBSERVÉ
Fenêtre d'erreur fatale VK_ERROR_DEVICE_LOST et retour au bureau pendant le chargement de zone
VOLET 02 // VARIABLE D'ENVIRONNEMENT OU PARAMÈTRE
graphics_preset=Low/Medium ou RX_SKIP_SHADERS=<hash>
VOLET 03 // RÉSOLUTION VÉRIFIÉE
Baissez le préréglage graphique dans le menu Insert/F1 sur Low (4 GB) ou Medium (6 GB), réduisez l'échelle de rendu à 1.0x et mettez à niveau vers le correctif du pool de descripteurs de v2.0.11.
Issue n° 817Gel d'image dans l'Arbre Mojo sur Steam Deck / Linux RADV (#817)
Linux AMD RADV (Mesa < 24.3) et Steam Deck LCD/OLED
Entrer dans l'Arbre Mojo ou la salle aux toiles d'araignées sous Steam Deck (Mesa RADV) peut bloquer le tampon de commandes GPU en raison du culling de meshlets par sous-groupe sur le shader 2c56dc1006942f74.
VOLET 01 // SYMPTÔME OBSERVÉ
L'écran se fige avec le son en boucle dès l'entrée dans l'Arbre Mojo
VOLET 02 // VARIABLE D'ENVIRONNEMENT OU PARAMÈTRE
RX_VK_MESH_NOCULL=2c56dc1006942f74
VOLET 03 // RÉSOLUTION VÉRIFIÉE
Définissez les options de lancement Steam sur RX_VK_MESH_NOCULL=2c56dc1006942f74 %command% (ou RX_VK_MESH_NOCULL=1 pour désactiver globalement l'élimination des meshlets).
Issues n° 57 et n° 1006Feuillages pixelisés et artefacts de textures HUD sous AMD RDNA 2 / RDNA 3 (#57 / #1006)
AMD Radeon RX série 6000 / RX série 7000 (Windows et Linux)
Certains pilotes AMD Windows Adrenalin et Linux compilent mal le transcodeur compute ASTC vers BC7, générant des macroblocs 4x4 multicolores sur les icônes HUD et le feuillage Kokiri.
VOLET 01 // SYMPTÔME OBSERVÉ
Blocs 4x4 en damier ou arc-en-ciel sur les icônes UI, l'herbe et la surface de l'eau
VOLET 02 // VARIABLE D'ENVIRONNEMENT OU PARAMÈTRE
RX_VK_ASTC_RGBA8=1
VOLET 03 // RÉSOLUTION VÉRIFIÉE
Exportez RX_VK_ASTC_RGBA8=1 avant de lancer Hookshot pour forcer la décompression logicielle RGBA8 sans perte plutôt que le transcodage par compute BC7.
Issues n° 1176 et n° 990Échec de l'extraction des ressources de HookshotBuilder ou non-concordance du hash NSO (#1176 / #990)
Windows x64 et Linux x86_64 HookshotBuilder
L'Asset Builder s'interrompt s'il reçoit un dump de base v0 dépourvu du patch v131072, une ROM N64/3DS au lieu du Title ID 0400486024DEC000 de Switch 2, ou un chemin Windows avec des caractères non-ASCII avant v2.0.11.
VOLET 01 // SYMPTÔME OBSERVÉ
Builder signale ExeFS Build ID non pris en charge ou échoue à 99 % du repack de RomFS
VOLET 02 // VARIABLE D'ENVIRONNEMENT OU PARAMÈTRE
Requiert le v131072 0400486024DEC000 (e0f3ccfa) pour le Title ID
VOLET 03 // RÉSOLUTION VÉRIFIÉE
Update vers Hookshot v2.0.11 (corrige le bug de chemin Windows en UTF-8 #1176) et fournissez le dump v131072 Switch 2 fusionné correspondant au préfixe SHA-1 e0f3ccfa.
docs/DEVELOPMENT.mdIsolation d'un Shaders défaillant personnalisé ou lié à Driver (RX_SKIP_SHADERS)
Toutes les plateformes Vulkan 1.3
Ignore les draw calls pour un ou plusieurs hashs de shaders NVN2 64 bits afin d'aider joueurs et contributeurs à cibler le pipeline SPIR-V causant un plantage du pilote ou un bug visuel.
VOLET 01 // SYMPTÔME OBSERVÉ
Un effet de particules spécifique ou une passe de post-traitement plante ou masque le viewport
VOLET 02 // VARIABLE D'ENVIRONNEMENT OU PARAMÈTRE
RX_SKIP_SHADERS=<hash1>,<hash2>
VOLET 03 // RÉSOLUTION VÉRIFIÉE
Lancez avec RX_LOG_LEVEL=debug pour enregistrer le hash du shader actif avant le plantage, puis transmettez RX_SKIP_SHADERS=<hash> pour contourner ce pipeline.
docs/DESIGN.md & docs/DEVELOPMENT.mdContournement des régressions de fonctions C liftées via ARM64 Interpreter (RX_FORCE_INTERP)
Windows x64 & Linux x86_64
Redirige des adresses précises de fonctions invitées (`0x7100xxxxxx`) ou l'ensemble du binaire vers l'interpréteur logiciel ARM64 au lieu des traductions statiques C.
VOLET 01 // SYMPTÔME OBSERVÉ
Anomalie physique d'acteur ou blocage suspecté dans une fonction ARM64 retranscrite
VOLET 02 // VARIABLE D'ENVIRONNEMENT OU PARAMÈTRE
RX_FORCE_INTERP=0x7100123450 ou RX_FORCE_INTERP=all
VOLET 03 // RÉSOLUTION VÉRIFIÉE
Définissez RX_FORCE_INTERP sur l'adresse invitée suspecte afin de verify si le bug provient du lifter C statique nx2/.
docs/DEVELOPMENT.mdActiver les logs verbeux des appels système Vulkan & HLE (RX_LOG_LEVEL & RX_TRACE_FUNC)
Windows x64 & Linux x86_64
Régule la verbosité de stdout/stderr de trace à error et enregistre l'état des registres d'entrée/sortie (`X0`–`X7`) pour les fonctions invitées ciblées lors du signalement de bugs GitHub.
VOLET 01 // SYMPTÔME OBSERVÉ
Fermeture silencieuse au lancement ou arrêt sur un stub de service HLE non implémenté
VOLET 02 // VARIABLE D'ENVIRONNEMENT OU PARAMÈTRE
RX_LOG_LEVEL=debug / RX_ABORT_ON_UNIMPL=1
VOLET 03 // RÉSOLUTION VÉRIFIÉE
Lancez depuis le terminal avec RX_LOG_LEVEL=debug (et éventuellement RX_TRACE_FUNC=0x7100xxxxxx) pour récupérer les journaux complets de diagnostic.
docs/DEVELOPMENT.mdTester le chargement des ressources et la séquence de boot sans Mesh Shaders (RX_GPU_BACKEND=null)
Runners CI headless et machines de test sans support des mesh shaders
Initialise le moteur de rendu nul sans affichage et RX_BOOT_DIRECT=1 afin que les développeurs sur des machines sans mesh shaders puissent verify le montage RomFS, l'audio et la lecture des sauvegardes.
VOLET 01 // SYMPTÔME OBSERVÉ
L'initialisation de Vulkan échoue avec VK_ERROR_EXTENSION_NOT_PRESENT sur un GPU hérité
VOLET 02 // VARIABLE D'ENVIRONNEMENT OU PARAMÈTRE
RX_GPU_BACKEND=null RX_BOOT_DIRECT=1
VOLET 03 // RÉSOLUTION VÉRIFIÉE
Utilisez RX_GPU_BACKEND=null pour valider le démarrage et les sauvegardes sans affichage ; le jeu 3D effectif nécessite un support matériel de VK_EXT_mesh_shader GPU.
README.md Linux SetupLinux AppImage refuse de se lancer (chmod +x ou libfuse2 manquant)
Linux x86_64 (Ubuntu, Debian, Fedora, Arch)
On Ubuntu 22.04/24.04 ou les distributions minimales sans libfuse2, double-cliquer sur Hookshot-v2.0.11-Linux-x86_64.AppImage échoue sans message à moins d'attribuer les permissions d'exécution ou d'utiliser --appimage-extract.
VOLET 01 // SYMPTÔME OBSERVÉ
AppImage ne s'ouvre pas ou affiche dlopen(): error loading libfuse.so.2
VOLET 02 // VARIABLE D'ENVIRONNEMENT OU PARAMÈTRE
chmod +x *.AppImage ou --appimage-extract-and-run
VOLET 03 // RÉSOLUTION VÉRIFIÉE
Exécutez chmod +x Hookshot-v2.0.11-Linux-x86_64.AppImage et installez libfuse2t64 ou passez --appimage-extract-and-run.
docs/SAVES.mdEmplacement corrompu ou surcharge manuelle du dossier de sauvegarde (RX_SAVE_PATH & oot_saves.py)
Windows x64 & Linux x86_64
Restaure les données après une écriture interrompue en basculant sur autosave.sav ou en recalculant la somme de contrôle d'en-tête CRC32C (`0x0008`) à l'aide de scripts/oot_saves.py.
VOLET 01 // SYMPTÔME OBSERVÉ
L'emplacement affiche vide ou Données corrompues après une coupure de courant ou une édition hexadécimale manuelle
SURCHARGE DE DIAGNOSTIC // RX_FORCE_INTERP & RX_SKIP_SHADERSIsoler le code ARM64 lifté des régressions SPIR-V Shader
Lorsqu'un plantage ou un blocage persiste après avoir réduit les préréglages de VRAM, combinez RX_LOG_LEVEL=debug avec RX_SKIP_SHADERS=<hash> afin d'isoler si un pipeline de NVN2 SPIR-V précis est en cause, ou définissez RX_FORCE_INTERP=0x7100xxxxxx (ou RX_FORCE_INTERP=all) pour exécuter les fonctions invitées via l'interpréteur logiciel ARM64 plutôt que par C statique.
CROQUIS DES SCÉNARIOS DE PANNE // TOP 3 DES ISSUES CRITIQUES
Schémas visuels des modes de défaillance (#1161 · #817 · #57)
ISSUE #1161
VK_ERROR_DEVICE_LOST Queue TimeoutPlaine d'Hyrule / Transition de temple ou soumission de NVIDIA 621 Driver
Le pool de textures de ASTC et les cascades d'ombres saturent la VRAM physique, ou la file de présentation séparée déclenche un timeout TDR → Réduisez le préréglage Insert/F1 sur Low/Medium et exécutez Hookshot v2.0.11.
ISSUE #817
Blocage de l'Arbre Mojo sous Steam Deck RADVInterblocage de culling de meshlets par sous-groupe Mesa RADV
Entrer dans l'Arbre Mojo exécute le mesh shader 2c56dc1006942f74 → l'instruction ballot wave64 sous RADV bloque le tampon de commandes GPU → Transmettez RX_VK_MESH_NOCULL=2c56dc1006942f74 %command%.
ISSUES #57 et #1006
Glitch AMD RDNA 2/3 de blocs 4×4 ASTCErreur de compilation du transcodeur compute ASTC vers BC7
Le compute shader Adrenalin / RADV corrompt les blocs 4×4 BC7 sur la végétation Kokiri et les icônes HUD → Exportez RX_VK_ASTC_RGBA8=1 pour forcer le décodage logiciel/CPU des textures RGBA8.
Registre de référence complet des 10 entrées de dépannage et variables RX_*
Nom du défaut et réf. Issue
Plateforme affectée
Variable d'environnement / Paramètre
Anomalies liées
Saturation de la VRAM ou de la Timeout VK_ERROR_DEVICE_LOST GPU (n° 1161) Issue n° 1161
GPU dotés de 4 GB à 6 GB de VRAM ou pilotes Vulkan overclockés
graphics_preset=Low/Medium ou RX_SKIP_SHADERS=<hash>
Corrigé dans v2.0.9–v2.0.11 · Réduire le préréglage Insert/F1 sur les GPU de 4–6 GB
KPI-TRB-02 // ISSUE #817
2c56dc1006942f74
Blocage de l'Arbre Mojo sous Steam Deck
Bypass avec RX_VK_MESH_NOCULL=2c56dc1006942f74 %command%
KPI-TRB-03 // ISSUES #57 & #1006
RX_VK_ASTC_RGBA8=1
Feuillage en blocs AMD RDNA 2/3
Force la décompression logicielle sans perte RGBA8 au lieu du calcul BC7
KPI-TRB-04 // LIFTER FALLBACK
RX_FORCE_INTERP
ARM64 Interpreter Bypass
Détourne les fonctions suspectes en 0x7100xxxxxx des fragments de code C lifté
SPÉCIFICATION TECHNIQUE // DIAGNOSTIC ET VARIABLES RX_*
Résoudre les erreurs VK_ERROR_DEVICE_LOST (#1161), blocages de l'Arbre Mojo sous Steam Deck (#817) et bugs visuels AMD ASTC (#57)
Trois problèmes matériels spécifiques représentent la majeure partie des demandes d'assistance de la communauté dans Hookshot. Tout d'abord, Issue #1161 (VK_ERROR_DEVICE_LOST) se manifeste dans deux cas bien précis : sur les pilotes NVIDIA de la série 621 juste après la préparation des shaders au lancement lorsqu'une file de présentation Vulkan distincte était active (atténué dans v2.0.9 et optimisé dans v2.0.11 en désactivant cette file distincte tout en rétablissant RX_VK_WB_DIFF=1), ou lors des transitions chargées vers la plaine d'Hyrule et les temples lorsque le pool de textures ASTC et les cascades d'ombres saturent la VRAM physique des GPU de 4 GB à 6 GB. Abaisser le préréglage graphique dans le menu Insert / F1 sur Low (pool de 1,5 GB) ou Medium (pool de 2,5 GB) évite la saturation de la VRAM.
Ensuite, Issue #817 touche les configurations Steam Deck LCD/OLED et Linux AMD RADV tournant sur des versions de Mesa antérieures à 24.3 : entrer dans l'Arbre Mojo ou la salle des toiles bloque la file de commandes GPU tandis que le son continue de tourner en boucle. Ce blocage provient du culling de meshlets par sous-groupes dans le mesh shader 2c56dc1006942f74 de NVN2 ; ajouter RX_VK_MESH_NOCULL=2c56dc1006942f74 %command% dans les options de lancement de Steam désactive le culling pour ce shader précis sans impact mesurable sur le FPS. Enfin, Issues #57 et #1006 provoquent, sur les GPU AMD Radeon RX 6000 / RX 7000, l'apparition de blocs 4x4 multicolores sur la végétation et les icônes de l'HUD à cause d'une mauvaise compilation du transcodeur compute ASTC vers BC7 par le pilote ; définir RX_VK_ASTC_RGBA8=1 permet de basculer vers une décompression logicielle RGBA8 sans perte.
Erreurs d'extraction de HookshotBuilder (#1176 / #990) et variables d'environnement de diagnostic RX_*
Lorsque HookshotBuilder échoue pendant l'extraction des ressources ou la compilation de C, verify trois prérequis : (1) vérifiez que votre dump correspond bien au Title ID 0400486024DEC000 de Switch 2 mis à jour en v131072 avec le préfixe e0f3ccfa pour le SHA-1 du NSO main ExeFS (e0f3ccfa56256410941279ef0b2501356be2222c), et non un dump de base v0 ou une ROM N64/3DS ; (2) assurez-vous d'utiliser Hookshot v2.0.11, qui corrige les échecs liés aux chemins d'accès non-ASCII sous Windows (#1176), les conflits avec des résidus de traductions C générées (#1197) ainsi que les en-têtes Linux AppImage manquants (#990) ; et (3) disposez d'au moins 30 GB d'espace disque disponible pour accueillir les 26,2 GB du RomFS décompressé ainsi que 1,4 GB de sources C générées.
Pour le débogage avancé, Hookshot propose des variables d'environnement détaillées documentées dans docs/DEVELOPMENT.md : RX_LOG_LEVEL=debug et RX_ABORT_ON_UNIMPL=1 mettent en évidence les appels de service HLE Horizon OS non implémentés ; RX_SKIP_SHADERS=<hash1>,<hash2> désactive des pipelines de shaders NVN2 64 bits précis pour isoler une corruption graphique ; RX_FORCE_INTERP=0x7100xxxxxx redirige les fonctions invitées suspectes vers l'interpréteur logiciel ARM64 ; et RX_GPU_BACKEND=null s'associe à RX_BOOT_DIRECT=1 pour vérifier le boot sans interface graphique.
FAQ TECHNIQUE // PLANTAGES ET SAUVEGARDES
Dépannage et FAQ des variables d'environnement
Où renseigner RX_VK_MESH_NOCULL ou RX_VK_ASTC_RGBA8 sur Windows par rapport à Steam Deck ?
On Steam Deck ou Linux Steam, faites un clic droit sur Hookshot -> Propriétés -> Options de lancement et saisissez : RX_VK_MESH_NOCULL=2c56dc1006942f74 %command% (ou combinez plusieurs variables avant %command%). On Windows PowerShell, exécutez $env:RX_VK_ASTC_RGBA8=1; .\hookshot.exe depuis le dossier de build, ou ajoutez la variable dans les propriétés System du Windows -> Variables d'environnement.
Pourquoi la mise à niveau de v2.0.7 vers v2.0.9 a-t-elle échoué avec des symboles g_module_b ou f_8 non déclarés (#1176 / #1197) ?
Avant v2.0.10, une interruption du processus ou une mise à jour d'une version à l'autre pouvait laisser des résidus de fichiers C générés dans work/sa/gen/, provoquant des erreurs d'édition de liens clang/lld. La mise à niveau vers Hookshot v2.0.11 supprime automatiquement le code partiel obsolète et nettoie les anciens fragments de traduction avant de lancer la compilation.
Comment récupérer un emplacement de sauvegarde si Hookshot signale Données corrompues après un plantage ?
Vérifiez d'abord le répertoire des sauvegardes pour localiser autosave.sav et copiez-le par-dessus save_00.sav. Si vous avez modifié manuellement un fichier de sauvegarde, exécutez python -m nx2.oot_saves verify save_00.sav (ou export-json suivi de import-json) pour que Hookshot recalcule la somme de contrôle CRC32C requise à l'offset d'en-tête 0x0008.
SOURCES PRINCIPALES ET VÉRIFICATION
Diagnostic officiel du NotRexed/Hookshot et références de Issue
Détaille la structure des 64 Ko de save_00.sav, la somme de contrôle CRC32C à l'offset 0x0008, la méthode de secours autosave.sav et scripts/oot_saves.py.
Valide le correctif pour le pilote 621 v2.0.9 NVIDIA (#1161), le nettoyage du générateur sous v2.0.10 (#1176/#1197) et le rétablissement de v2.0.11 RX_VK_WB_DIFF=1.
