Hookshot Fehlerbehebung und Diagnose-Umgebungsvariablen
Diagnostiziere und behebe jeden dokumentierten Runtime-Crash von Hookshot v2.0.11, GPU-Treiber-Hänger, Texturfehler und Builder-Extraktionsfehler. Durchsuche oder filtere die 10 verifizierten Fehlerblätter unten nach Issue-Tags (#1161, #817, #57, #1176) oder Symptomen, überprüfe die drei Diagnosebereiche (Symptom, Umgebungsvariable, Lösung) und wende gezielte RX_*-Umgebungs-Overrides an.
Nach primärem Issue-Tag (#1161, #817, #57, #1176, RX_*-Diagnose) filtern oder nach Symptom-Schlagwörtern suchen. Jedes Fehlerblatt bietet drei strukturierte Spalten – Beobachtetes Symptom, Umgebungsvariable / Startparameter und Verifizierte v2.0.11-Lösung – samt verknüpften Fehlerbeziehungen.
Issue #1161VK_ERROR_DEVICE_LOST GPU Timeout oder VRAM-Erschöpfung (#1161)
4-GB- bis 6-GB-VRAM-GPUs oder übertaktete Vulkan-Treiber
Tritt bei anspruchsvollen Übergängen in der Hyrule-Ebene oder in Tempeln auf, wenn der ASTC-Textur-Pool plus Schattenkaskaden den physischen VRAM übersteigen oder ein TDR-Treiber-Timeout auslösen.
BEREICH 01 // BEOBACHTETES SYMPTOM
Fataler VK_ERROR_DEVICE_LOST-Popup-Fehler und Absturz auf den Desktop beim Laden von Gebieten
BEREICH 02 // UMGEBUNGSVARIABLE ODER FLAG
graphics_preset=Low/Medium oder RX_SKIP_SHADERS=<hash>
BEREICH 03 // VERIFIZIERTE LÖSUNG
Stelle das Grafik-Preset im Insert/F1-Menü auf Low (4 GB) oder Medium (6 GB) herunter, reduziere die Renderauflösung auf 1.0x und aktualisiere auf den Deskriptor-Pool-Fix von v2.0.11.
Issue #817Freeze im Deku-Baum bei Steam Deck / Linux RADV (#817)
Steam Deck LCD/OLED & Linux AMD RADV (Mesa < 24.3)
Das Betreten des Deku-Baums oder des Spinnennetz-Raums auf Steam Deck (Mesa RADV) kann den GPU-Befehlspuffer aufgrund von Meshlet-Subgruppen-Culling in Shader 2c56dc1006942f74 blockieren.
BEREICH 01 // BEOBACHTETES SYMPTOM
Bildschirm friert ein, während Audio beim Betreten des Deku-Baums in einer Schleife weiterläuft
BEREICH 02 // UMGEBUNGSVARIABLE ODER FLAG
RX_VK_MESH_NOCULL=2c56dc1006942f74
BEREICH 03 // VERIFIZIERTE LÖSUNG
In den Steam-Startoptionen RX_VK_MESH_NOCULL=2c56dc1006942f74 %command% festlegen (oder RX_VK_MESH_NOCULL=1, um das Culling von Meshlets global zu deaktivieren).
Bestimmte AMD-Windows-Treiber unter Adrenalin und Linux kompilieren den Compute-Transcoder von ASTC nach BC7 fehlerhaft, was zu bunten 4x4-Makroblock-Artefakten auf HUD-Icons und Kokiri-Vegetation führt.
BEREICH 01 // BEOBACHTETES SYMPTOM
Schachbrett- oder regenbogenfarbene 4x4-Blöcke auf UI-Icons, Gras- und Wasseroberflächen
BEREICH 02 // UMGEBUNGSVARIABLE ODER FLAG
RX_VK_ASTC_RGBA8=1
BEREICH 03 // VERIFIZIERTE LÖSUNG
Vor dem Start von Hookshot die Variable RX_VK_ASTC_RGBA8=1 exportieren, um eine verlustfreie Software-RGBA8-Dekompression statt Compute-BC7-Transcodierung zu erzwingen.
Issues #1176 & #990Fehler bei Asset-Extraktion oder NSO-Hash-Abweichung in HookshotBuilder (#1176 / #990)
Windows x64 & Linux x86_64 HookshotBuilder
Der Asset-Builder bricht ab, wenn ein Basis-v0-Dump ohne Patch v131072 übergeben wird, ein N64/3DS-ROM statt Switch-2-Title-ID 0400486024DEC000 vorliegt oder Windows-Pfade vor v2.0.11 Nicht-ASCII-Zeichen enthalten.
BEREICH 01 // BEOBACHTETES SYMPTOM
Builder meldet nicht unterstützte ExeFS Build ID oder scheitert bei 99 % des RomFS-Neupackens
Führe ein Update auf Hookshot v2.0.11 durch (behebt UTF-8-Windows-Pfadfehler #1176) und stelle den zusammengeführten Switch-2-v131072-Dump bereit, der zum SHA-1-Präfix e0f3ccfa passt.
docs/DEVELOPMENT.mdIsolierung fehlerhafter benutzerdefinierter oder Driver-spezifischer Shaders (RX_SKIP_SHADERS)
Alle Vulkan-1.3-Plattformen
Überspringt Draw-Calls für einen oder mehrere 64-Bit-NVN2-Shader-Hashes, damit Spieler und Mitwirkende ermitteln können, welche SPIR-V-Pipeline Treiberabstürze oder Grafikfehler verursacht.
BEREICH 01 // BEOBACHTETES SYMPTOM
Bestimmter Partikeleffekt oder Post-Processing-Pass stürzt ab oder blendet das Sichtfeld aus
BEREICH 02 // UMGEBUNGSVARIABLE ODER FLAG
RX_SKIP_SHADERS=<hash1>,<hash2>
BEREICH 03 // VERIFIZIERTE LÖSUNG
Mit RX_LOG_LEVEL=debug starten, um den aktiven Shader-Hash vor dem Absturz zu protokollieren, und anschließend RX_SKIP_SHADERS=<hash> übergeben, um die Pipeline zu umgehen.
docs/DESIGN.md & docs/DEVELOPMENT.mdUmgehung von Funktionsregressionen in geliftetem C über ARM64 Interpreter (RX_FORCE_INTERP)
Windows x64 & Linux x86_64
Leitet einzelne Gastfunktionsadressen (`0x7100xxxxxx`) oder die gesamte Binärdatei durch den Software-ARM64-Interpreter statt durch statische C-Übersetzungen.
BEREICH 01 // BEOBACHTETES SYMPTOM
Akteur-Physikanomalie oder Verdacht auf Softlock in einer gelifteten ARM64-Funktion
BEREICH 02 // UMGEBUNGSVARIABLE ODER FLAG
RX_FORCE_INTERP=0x7100123450 oder RX_FORCE_INTERP=all
BEREICH 03 // VERIFIZIERTE LÖSUNG
Setze RX_FORCE_INTERP auf die verdächtige Gastadresse, um zu verify, ob der Fehler vom statischen nx2/-C-Lifter herrührt.
Steuert die stdout/stderr-Ausführlichkeit von Trace bis Error und protokolliert Registerzustände beim Einstieg/Ausstieg (`X0`–`X7`) für gezielte Gastfunktionen beim Erstellen von GitHub-Issues.
BEREICH 01 // BEOBACHTETES SYMPTOM
Lautloses Schließen beim Start oder Trap durch nicht implementierten HLE-Service-Stub
BEREICH 02 // UMGEBUNGSVARIABLE ODER FLAG
RX_LOG_LEVEL=debug / RX_ABORT_ON_UNIMPL=1
BEREICH 03 // VERIFIZIERTE LÖSUNG
Aus dem Terminal mit RX_LOG_LEVEL=debug (und optional RX_TRACE_FUNC=0x7100xxxxxx) starten, um vollständige Diagnoseprotokolle zu erfassen.
docs/DEVELOPMENT.mdAsset-Lade- & Boot-Logik ohne Mesh-Shader testen (RX_GPU_BACKEND=null)
Headless-CI-Runner & Testsysteme ohne Mesh-Shader
Initialisiert den No-Op-Null-Renderer sowie RX_BOOT_DIRECT=1, damit Entwickler auf Systemen ohne Mesh-Shader RomFS-Mounting, Audio und Save-Parsing per verify überprüfen können.
BEREICH 01 // BEOBACHTETES SYMPTOM
Vulkan-Initialisierung schlägt mit VK_ERROR_EXTENSION_NOT_PRESENT auf älterer GPU fehl
BEREICH 02 // UMGEBUNGSVARIABLE ODER FLAG
RX_GPU_BACKEND=null RX_BOOT_DIRECT=1
BEREICH 03 // VERIFIZIERTE LÖSUNG
RX_GPU_BACKEND=null für Headless-Boot- und Save-Prüfungen nutzen; tatsächliches 3D-Gameplay erfordert eine Hardware-VK_EXT_mesh_shader GPU.
README.md Linux SetupLinux AppImage startet nicht (fehlendes chmod +x oder libfuse2)
Linux x86_64 (Ubuntu, Debian, Fedora, Arch)
Unter On Ubuntu 22.04/24.04 oder Minimal-Distributionen ohne libfuse2 schlägt ein Doppelklick auf Hookshot-v2.0.11-Linux-x86_64.AppImage lautlos fehl, sofern keine Ausführungsrechte vergeben oder --appimage-extract genutzt wird.
BEREICH 01 // BEOBACHTETES SYMPTOM
AppImage öffnet sich nicht oder gibt dlopen(): error loading libfuse.so.2 aus
BEREICH 02 // UMGEBUNGSVARIABLE ODER FLAG
chmod +x *.AppImage oder --appimage-extract-and-run
BEREICH 03 // VERIFIZIERTE LÖSUNG
chmod +x Hookshot-v2.0.11-Linux-x86_64.AppImage ausführen und entweder libfuse2t64 installieren oder --appimage-extract-and-run übergeben.
docs/SAVES.mdBeschädigter Speicherstand oder manueller Speicherpfad-Override (RX_SAVE_PATH & oot_saves.py)
Windows x64 & Linux x86_64
Stellt abgebrochene Schreibvorgänge durch Fallback auf autosave.sav oder durch Neuberechnung der CRC32C-Header-Prüfsumme (`0x0008`) mit scripts/oot_saves.py wieder her.
BEREICH 01 // BEOBACHTETES SYMPTOM
Speicherplatz wird nach Stromausfall oder manuellem Hex-Edit als leer oder als Beschädigte Daten angezeigt
DIAGNOSE-OVERRIDE // RX_FORCE_INTERP & RX_SKIP_SHADERSIsolierung von geliftetem ARM64-Code gegenüber SPIR-V-Shader-Regressionen
Wenn sich ein Absturz oder Softlock nicht durch Senken der VRAM-Voreinstellungen beheben lässt, kombiniere RX_LOG_LEVEL=debug mit RX_SKIP_SHADERS=<hash>, um zu prüfen, ob eine bestimmte NVN2-SPIR-V-Pipeline verantwortlich ist, oder setze RX_FORCE_INTERP=0x7100xxxxxx (oder RX_FORCE_INTERP=all), um Gastfunktionen im Software-ARM64-Interpreter statt über statische C auszuführen.
FEHLERPFAD-SKIZZEN // TOP 3 DER WICHTIGSTEN ISSUES
Visuelle Fehlerpfad-Schemata (#1161 · #817 · #57)
ISSUE #1161
VK_ERROR_DEVICE_LOST Queue TimeoutÜbergang zu Hyrule-Ebene / Tempel oder NVIDIA-621-Driver-Übermittlung
ASTC-Textur-Pool + Schattenkaskaden überschreiten physischen VRAM oder separate Present-Queue löst TDR-Timeout aus → Insert/F1-Voreinstellung auf Low/Medium senken und Hookshot v2.0.11 ausführen.
Betreten des Deku-Baums führt Mesh-Shader 2c56dc1006942f74 aus → RADV-Wave64-Ballot blockiert GPU-Befehlspuffer → RX_VK_MESH_NOCULL=2c56dc1006942f74 %command% übergeben.
ISSUES #57 & #1006
Blockiger 4×4-ASTC-Grafikfehler bei AMD RDNA 2/3Fehlkompilierung des Compute-Transcoders von ASTC nach BC7
Adrenalin- / RADV-Compute-Shader beschädigt 4×4-BC7-Blöcke bei Kokiri-Vegetation und HUD-Icons → RX_VK_ASTC_RGBA8=1 setzen, um CPU-/Software-Dekodierung von RGBA8-Texturen zu erzwingen.
Vollständige Referenztabelle mit 10 Einträgen zu Fehlerbehebung & RX_*-Flags
Fehlerbezeichnung & Issue-Ref
Betroffene Plattform
Umgebungsvariable / Flag
Verwandte Fehler
VK_ERROR_DEVICE_LOST GPU Timeout oder VRAM-Erschöpfung (#1161) Issue #1161
4-GB- bis 6-GB-VRAM-GPUs oder übertaktete Vulkan-Treiber
graphics_preset=Low/Medium oder RX_SKIP_SHADERS=<hash>
Behebung von VK_ERROR_DEVICE_LOST (#1161), Steam Deck-Deku-Baum-Hängern (#817) & AMD-ASTC-Grafikfehlern (#57)
Drei hardwarespezifische Probleme machen den Großteil der Support-Anfragen der Community zu Hookshot aus. Erstens: Issue #1161 (VK_ERROR_DEVICE_LOST) tritt in zwei Szenarien auf: bei NVIDIA-Treibern der 621er-Serie direkt nach der Shader-Vorbereitung beim Start, wenn eine separate Vulkan-Present-Queue aktiv war (in v2.0.9 entschärft und in v2.0.11 optimiert, indem die separate Present-Queue deaktiviert bleibt, während RX_VK_WB_DIFF=1 wieder aktiviert wird), oder bei anspruchsvollen Übergängen zur Hyrule-Ebene bzw. zu Tempeln, wenn der ASTC-Textur-Pool und die Schattenkaskaden den physischen VRAM auf GPUs mit 4 GB bis 6 GB übersteigen. Das Senken des Grafik-Presets im Insert / F1-Menü auf Low (1,5-GB-Pool) oder Medium (2,5-GB-Pool) verhindert eine VRAM-Überlastung.
Zweitens: Issue #817 betrifft Systeme mit Steam Deck LCD/OLED und Linux AMD RADV mit Mesa-Versionen vor 24.3: Beim Betreten des Deku-Baums oder des Spinnennetzzaubers friert der GPU-Befehlspuffer ein, während der Ton weiterläuft. Das Hängenbleiben wird durch Subgruppen-Meshlet-Culling innerhalb von NVN2-Mesh-Shader 2c56dc1006942f74 verursacht; das Setzen der Startoptionen in Steam auf RX_VK_MESH_NOCULL=2c56dc1006942f74 %command% umgeht das Culling für diesen Shader ohne messbaren FPS-Verlust. Drittens: Issues #57 und #1006 auf AMD-Radeon-RX-6000- / RX-7000-GPUs führen zu regenbogenfarbenen 4x4-Blöcken auf Vegetation und HUD-Symbolen, bedingt durch Treiber-Fehlkompilierungen des Compute-Transcoders von ASTC zu BC7; das Exportieren von RX_VK_ASTC_RGBA8=1 schaltet auf verlustfreie Software-RGBA8-Dekompression um.
HookshotBuilder Extraktionsfehler (#1176 / #990) & RX_*-Diagnose-Flags für Entwickler
Wenn HookshotBuilder während der Asset-Extraktion oder der C-Kompilierung fehlschlägt, verify drei Voraussetzungen: (1) Dein Dump entspricht Switch 2 Title-ID 0400486024DEC000 auf Update-Stand v131072 mit ExeFS-Main-NSO-SHA-1-Präfix e0f3ccfa (e0f3ccfa56256410941279ef0b2501356be2222c) und ist kein Basis-v0-Dump oder N64/3DS-ROM; (2) du nutzt Hookshot v2.0.11, wodurch Probleme mit Nicht-ASCII-Windows-Pfaden (#1176), veraltete generierte C-Übersetzungskonflikte (#1197) und fehlende Linux-AppImage-Header (#990) behoben sind; und (3) du hast mindestens 30 GB freien Speicherplatz für die 26,2 GB entpacktes RomFS plus 1,4 GB an generierten C-Quelldateien.
Für fortgeschrittenes Debugging stellt Hookshot feinkörnige Umgebungsvariablen bereit, die in docs/DEVELOPMENT.md dokumentiert sind: RX_LOG_LEVEL=debug und RX_ABORT_ON_UNIMPL=1 decken nicht implementierte HLE-Serviceaufrufe von Horizon OS auf; RX_SKIP_SHADERS=<hash1>,<hash2> deaktiviert bestimmte 64-Bit-NVN2-Shader-Pipelines zur Isolierung von Darstellungsfehlern; RX_FORCE_INTERP=0x7100xxxxxx leitet verdächtige Gastfunktionen über den Software-ARM64-Interpreter; und RX_GPU_BACKEND=null dient zusammen mit RX_BOOT_DIRECT=1 der Headless-Boot-Überprüfung.
TECHNISCHE FAQ // ABSTÜRZE & SPIELSTÄNDE
Fehlerbehebung & Umgebungs-Flags FAQ
Wo richte ich RX_VK_MESH_NOCULL oder RX_VK_ASTC_RGBA8 unter Windows im Vergleich zu Steam Deck ein?
Klicke unter On Steam Deck oder Linux Steam mit der rechten Maustaste auf Hookshot -> Eigenschaften -> Startoptionen und trage ein: RX_VK_MESH_NOCULL=2c56dc1006942f74 %command% (oder kombiniere mehrere Variablen vor %command%). Führe in On Windows PowerShell $env:RX_VK_ASTC_RGBA8=1; .\hookshot.exe aus dem Build-Verzeichnis aus oder hinterlege die Variable unter Windows System Eigenschaften -> Umgebungsvariablen.
Warum schlug das Upgrade von v2.0.7 auf v2.0.9 mit nicht deklarierten g_module_b- oder f_8-Symbolen fehl (#1176 / #1197)?
Vor v2.0.10 konnten abgebrochene oder versionsübergreifende Updates veraltete generierte C-Dateien in work/sa/gen/ hinterlassen, was zu Clang/LLD-Linkerfehlern führte. Ein Update auf Hookshot v2.0.11 verwirft unvollständigen alten generierten Code automatisch und bereinigt alte Übersetzungsshards vor dem Kompilieren.
Wie stelle ich einen Speicherstand wieder her, wenn Hookshot nach einem Absturz Beschädigte Daten meldet?
Prüfe zuerst das Saves-Verzeichnis auf autosave.sav und kopiere die Datei über save_00.sav. Falls du eine Speicherdatei manuell editiert hast, führe python -m nx2.oot_saves verify save_00.sav (oder export-json gefolgt von import-json) aus, damit Hookshot die erforderliche CRC32C-Prüfsumme bei Header-Offset 0x0008 neu berechnet.
PRIMÄRE QUELLEN & VERIFIKATION
Offizielle Diagnose- & Issue-Referenzen zu NotRexed/Hookshot
